[ZacxDev]

What

1. GET /api/attention/summary: what a status bar polls. It takes a personal token only (requireAPIToken) and is owner-scoped.
2. Token scopes (migration 0068): full (the default; every existing token) or summary. A summary token reaches GET (and HEAD) /api/attention/summary and nothing else.

Reworked per the round-0 answers:

• Q1: a summary-only scope replaces "read-only = every GET".
• D1: no CLI verb; the bar GETs the endpoint over HTTPS.
• D2: url only; the path field is gone.

Why

The bar needs one cheap, owner-scoped read of "what is waiting on me", plus a credential on disk that can do nothing but that read.

How

The summary

• "Waiting" means exactly s.attentionItems(ctx). It is the same function the Asks page, the badge and attention_list use, and there is no second predicate. Busy and idle are context only.
• Item text follows the push rule.
  • title is textplain.Title(Source).
  • why is the first line of attentionPushBody. Secrets are redacted, a session is summary only, and a draft is who and where only.
  • It never includes Detail, options or suggestions.
  • A reply-draft item now carries its draftPushBody, and attentionPushBody returns it for plugin items, so the summary never quotes an inbound message.
• url is MUSTER_PUBLIC_URL + the tap route /attention/open/<key> for an ask or a session, or + the item's own link for a draft or a task. It is "" when MUSTER_PUBLIC_URL is unset. There are no per-item lookups (no ByAsk, no agent read, no focus read), so the cost is about one badge render.
• Hosts. Each host has online, status_report, and busy/idle counts of Claude (or agent-runtime) windows. An offline host counts 0/0.
• Global fields. nudge_mode is off, or chiefNudgeMode(owner) when chief nudges are on. ts is server time. partial is set when a queue source failed.

Scopes

• The check. One allowlist, tokenScopeRoutes (scope → mux patterns, matched on http.Request.Pattern), is checked in the single admit path admitAPIToken. Every token wrapper goes through that path, including the hook-tier door at auth.go:438. The current table is summary → {"GET /api/attention/summary"}; net/http serves HEAD through the GET pattern.
• Fails closed. Only full is unlimited. An unknown or blank scope reaches nothing, and a request with no matched pattern is refused to every scope but full. A route added later is refused to a summary token until someone adds it to the table.
• GET /api/whoami is denied to a summary token, on purpose. A bar doesn't need it, and the summary's own 200/401/403 already tells you whether the token works. There was no strong reason to allow it.
• Minting. A radio choice: "Full access" (checked by default) or "Bar summary only (can read the Attention summary and nothing else)". The token page, GET /api/tokens (muster token ls, "scope") and whoami show the scope. An unknown scope at mint is a 400, and api_tokens_scope_check backs that up in the database.
• Rollback. An older image would admit a summary token as full access, so the migration header says to revoke all non-full tokens first.

Contract (docs/attention.md#the-summary-api)

{"ts":1800000000,"nudge_mode":"off","partial":false,"hosts":[{"host":"host-a","online":true,"status_report":true,"busy":1,"idle":0}],"items":[{"key":"ask-5","kind":"ask","host":"","title":"chief","why":"Ship it?","since":1799999940,"age_secs":60,"offline":false,"url":"https://muster.example.test/attention/open/ask-5"}]}

• kind is one of ask, session, question, plugin, task.
• nudge_mode is one of off, shadow, live.
• hosts and items are never null.
• url is "" when MUSTER_PUBLIC_URL is unset.
• Fields may be added; none is renamed or removed. The whole string is pinned by TestTheSummaryDocumentIsTheDocumentedShape.

Tests

• Red at origin/main: the new tests do not compile (undefined: ScopeFull, undefined: attentionSummary).
• Green at HEAD: go test -race passed under scripts/with-test-pg.sh (DB required) for internal/api, internal/apitokens, internal/db and cmd/muster.
• Green on the merged tree with current main, which now includes fix(chief-nudges): the generic ask shows the chief's read #384: internal/chiefnudge was added to the same run, and all passed.
• Other gates: go build and go vet pass, the leakscan is clean, and make verb-ledger reports 23/23.

Scope tests:

• TestABarSummaryTokenReachesTheSummaryAndNothingElse: GET/HEAD summary → 200. A summary token gets 403 with the scope sentence before the handler runs (store List/Revoke never called) on these 12 routes:

  • GET /api/agents/chief/messages
  • GET /api/agents
  • GET /api/tasks
  • GET /api/tasks/1
  • GET /api/flows/jobs
  • GET /api/whoami
  • GET /api/tokens
  • DELETE /api/tokens/1
  • POST /api/tasks
  • PATCH /api/tasks/1/status
  • POST /api/flows/jobs
  • POST /api/agents/chief/messages

  The same requests with a full token are not refused, and its List and Revoke reach the store.

• TestATokenOfAnUnknownScopeReachesNothing: "", admin and Summary are refused everywhere, the summary included.

• TestTheScopeAllowlistIsExactlyTheSummaryRoute: pins the whole table, and checks that its pattern is in routes.golden.

• TestTheMintPageOffersABarSummaryToken and TestAMintNamingAnUnknownScopeIsABadRequest.

• TestATokensScopeIsStoredAndReadBack (PG): checks the record, list and Authenticate; that an unknown scope is refused before any write; the DB CHECK; the audit scope; and NOT NULL DEFAULT 'full'.

• TestABarSummaryTokenMintedOnThePageReadsTheSummaryAndNothingElse (PG): the end-to-end loop. A summary token gets the summary, and is refused on GET /api/tasks, GET /api/whoami and revoking itself, after which it is still live. A full token minted on the same page reads /api/tasks.

Mutation battery (detached copy, real Postgres). The unmutated control was 20 PASS, 0 FAIL, 0 SKIP. "Killed" means every named test failed, counted from --- FAIL lines.

mutant	killed by
allowlist dropped (tokenScopeAdmits always true)	TestABarSummaryTokenReachesTheSummaryAndNothingElse, TestATokenOfAnUnknownScopeReachesNothing, PG loop
allowlist widened to every GET for summary	TestABarSummaryTokenReachesTheSummaryAndNothingElse, PG loop
table gains GET /api/whoami	the same 2 + TestTheScopeAllowlistIsExactlyTheSummaryRoute
door check removed	3 tests
unknown scope treated as full	TestATokenOfAnUnknownScopeReachesNothing
summary pattern misspelled (bar locked out)	3 tests
store insert ignores the scope / Authenticate drops it	TestATokensScopeIsStoredAndReadBack + PG loop
store accepts an unknown scope	TestATokensScopeIsStoredAndReadBack
page default flips off "Full access" / page ignores the choice	TestTheMintPageOffersABarSummaryToken (+ PG loop)
owner scope dropped	TestTheSummaryIsTheOwnersQueueAndHosts, isolation walk TestNoRouteLetsOneUserReachAnothersData
why = raw Text	TestTheSummaryItemSaysWhatItsPushSays, TestTheSummaryRedactsExactlyAsThePushDoes, PG test
tap route dropped from url	3 tests
url built without a public origin	TestTheSummaryItemSaysWhatItsPushSays

The first round of this battery is in the earlier version of this description; those summary-shape mutants are unchanged.

Two harness defects, found and fixed before these numbers:

• A -run filter (Scope|UnknownScope) did not match TestABarSummaryToken…, so those tests never ran and the mutants read as SURVIVED.
• With the door broken, an unwired handler panicked and took the test binary down. The refused-route loops now count a handler panic as "admitted".

Not verified: nothing has been deployed. The endpoint and the scope have not been exercised against the live server or a real bar.

🤖 Generated with Claude Code

[ZacxDev]

Audit round 0 (requirements & deletion) at 8b7d9968. Verdict: requirement questioned (Q1), with deletion candidates D1 and D2.

The audit found 15 requirements, 5 of them unattributed. All 5 were kept apart from D1 and D2.

D1 — the `muster attention summary` CLI verb (+cli.md, verb ledger 23→24, CLI tests): the bar can GET the endpoint over https directly, removing the devrc CLI-pin/server-version coupling
D2 — the `path` item field alongside `url`: MUSTER_PUBLIC_URL is set live so `url` is always populated, and the never-remove contract makes the duplicate permanent
Q1 — Is "read-only" meant to be every GET a personal token reaches (as built: includes agent message bodies, tasks, projects, flows via the hook-tier door), or a narrower scope for the bar's on-disk token? Recommendation: keep method-scope as built. · forcing: user

[ZacxDev]

The operator's answers to the round-0 premises, relayed word for word:

Q1=answered: Summary only — the bar's token gets a scope that can call only GET /api/attention/summary, not every GET a personal token reaches
D1=deleted
D2=deleted

[ZacxDev]

Audit round 1 (full, at 69c3b855): 0 🔴, so the ladder ends here. It found 2 🟡 and 2 🟢. These are fixed in 6cd34820, which is not re-audited:

• 🟢 The summary now reads the hub once, and both hosts[] and the waiting items share that snapshot. Pinned by TestTheSummaryReadsTheHubOnce.
• 🟡 Documented in the 0068 header and schema.md: during a forward rollout, old pods ignore scope. Mint summary tokens only after the rollout completes.
• 🟢 The rollback revoke now runs in a transaction with SET LOCAL muster.scope = 'all' and a count check. Without the setting, forced RLS makes the UPDATE silently change 0 rows; this was measured.
• 🟡 Left open on purpose: the title tests here will go red once fix(attention): asks and waiting sessions name the exact tmux target #388, which changes how windows are named, is merged too. The PR that lands second updates them.

No route bypasses the scope check. Every personal-token door goes through admitAPIToken, and the tap route is session-only.

1. The summary reads Hosts() once and shares the snapshot between hosts[] and the waiting items.
2. The migration header and schema.md say to mint summary tokens only after a rollout completes.
3. The rollback revoke sets muster.scope='all' inside a transaction and checks the count.