#221 feat(box): phones and agents read the box's open attention items

Stacks on #219 (the box's attention items), rebased onto main with #207 (phone API v2). Only the last commit is new here; review it once #219 has settled.

Summary

A phone and an agent read what needs a person through the surfaces they already have, instead of a new API. Both are read only.

 phone API (port 1379, phone token)
   GET  /phone/v1/info                 capabilities: transcript, events, push, interrupt
+                                                    + attention (a box that keeps items)
+  GET  /phone/v1/attention?session=S  the box's open items, as briefs
 berthd mcp
   berth_sessions, berth_screen, …
+  berth_attention { session? }        the same list

Both go through one shape, AttentionItem.Brief() (internal/box/attention.go):

AttentionBrief { key, revision, kind, title, options, recommended,
                 status, snoozed_until, session, created, updated }

It has no details, answer, closed_reason or by. Those stay on the box's own API, the same way the attention.* events leave an item's words out. Settled items aren't listed. If the store can't read its file, the phone gets a 500, not an empty list.

Evidence

Live, on a real box (.claude/skills/verify-berthd/scripts/attention-reads-live.sh, new): it builds berthd and runs a box in a network namespace of its own, with a dummy 100.64.7.9, so its phone listener gets a 1379 of its own. Then it posts an ask about a session (with details), puts a snooze mark on a signal key, and posts and answers a third item. It reads them back through the phone listener and through berthd mcp, and checks both against GET /v1/attention?open=1 with the words taken out.

• Before (this branch's base, #219):

  GET /phone/v1/attention      → 404 page not found
  tools/call berth_attention   → {"code":-32602,"message":"unknown tool berth_attention"}
  

• After:

  ok: box, phone and berth_attention list the same 2 open items, without words;
      no token 401, wrong token 401, phone POST 405
  

  [{"key":"signal:acme-shop-sh-1igb:waiting","revision":1,"kind":"mark","status":"open","snoozed_until":"2030-01-01T09:00:00Z", …},
   {"key":"session:acme-shop-sh-1igb","revision":1,"kind":"decision","title":"Ship the acme checkout on Friday?",
    "options":[{"label":"Ship"},{"label":"Wait","description":"after the sale"}],"recommended":"Ship","status":"open","session":"acme-shop-sh-1igb", …}]
  

  info answers "capabilities":["transcript","events","push","interrupt","attention"].

Unit:

• TestThePhoneListsTheBoxsOpenAttentionItemsWithoutTheirWords: the route equals the store's open list, is filtered by session, answers [] for none, gets 401 without the token or with a wrong one, refuses POST/PATCH/DELETE and leaves the item as it was, and info lists attention.
• TestThePhoneSaysWhenTheBoxCantReadItsAttentionItems: an unreadable store answers 500, a box with no store answers 501 and its info doesn't list attention.
• TestTheAttentionToolReadsTheBoxsOpenItemsWithoutTheirWords: the tool calls GET /v1/attention?open=1[&session=] and returns the briefs, with no details.

Checks: go vet ./..., go test -race ./... (see below) and docs-site build pass. This PR has no app changes. Fork PR CI needs a maintainer's approval and the run-ci label.

The verify skill gets features/phone-and-mcp-reads.md and a row in its map. Docs: reference/phone-api.mdx (the route and the capability), the MCP tool table in guides/runs.mdx, and the changelog.

Merge Danger

Door: two-way

Additive read routes: one phone route, one MCP tool, one capability string. Reverting removes them; nothing is stored.

Blast Radius: small

A phone or an agent can now read an open item's title and option labels and descriptions. Anything with the phone token already reads agents' conversations, which carry the same questions, so this exposes nothing new. Clients that compare info.capabilities exactly will see one more entry.

🤖 Generated with Claude Code

---

^{Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.}