[DeadWaveWave]

💡 Change Scope

• Small Change: Fast feedback, localized UI/logic, low-risk.
• Large Change: New feature, cross-boundary logic, runtime-risk (persistence, IPC, lifecycle, recovery).

📝 What Does This PR Do?

Tide Phase 2.5, fourth step: the "needs you" inbox at the top of the sidebar panel, as the Tide Spec describes.

• Inbox: one row per agent waiting for you, across every project. Each row shows:

  • the project tile, the agent's title, and "project · Space";
  • how long ago it started waiting ("Just now", "2 min ago", "1 h ago").

  One click switches to that project and focuses the agent, the same path as the sidebar rows and the top-bar chip (on mobile it only centres the agent).

  The whole block is hidden when no agent is waiting. Hidden agents are included, because they still need you.

• Wait time:

  • A wait is timed only from a transition this window saw: the agent was seen doing something else, then started waiting.
  • Agents restored at launch, or first seen already waiting, show "Waiting" instead of an invented duration.
  • The timer is transient renderer state (a small store fed by the shell), so it keeps counting while the sidebar is collapsed and is never saved.
  • The label refreshes every 30 s, only while rows are shown.

• Shared project tile: the rail's coloured tile becomes ProjectTile (with a small size), so the rail and inbox, and later the command center, show the same project identity.

---

🏗️ Large Change Spec (Required if "Large Change" is checked)

1. Context & Business Logic

Approved Tide Spec, app shell:

顶部是跨所有项目的「需要你」收件箱，显示等了多久，点一下切到对应项目并飞到那个窗口

and its state table:

跨项目「需要你」…UI 派生…由状态计算

GitHub's and Linear's inboxes follow the same pattern: one list across all sources, a relative age, and one click to the item.

2. State Ownership & Invariants

• Agent status is still owned by the agent run-state model; the inbox only reads it.
• The only new state is the wait-start store. It is transient, written only by useAgentWaitingSinceTracker in the shell, and never persisted.

Invariants:

1. The inbox, the rail badges and the top-bar chip list the same agents, because all three come from summarizeAgentActivity and buildSidebarAgentItems. They update in the same render.
2. A duration is shown only for a wait that started while this window was watching; otherwise the row says "Waiting".
3. A wait stamp is kept while the agent keeps waiting, cleared when it moves on, and dropped when the window closes.

3. Verification Plan & Regression Layer

• Unit:
  • agentWaitingSince.spec.ts covers stamping, keeping the stamp, no guess after restore or first sight, clearing and forgetting, and no change when nothing changed.
  • waitDuration.spec.ts covers unknown, now, minutes, hours and a clock moving backwards.
  • SidebarAttentionInbox.spec.tsx covers empty, rows with place and wait, accessible names, and the click target.
  • agentActivitySummary.spec.ts checks the project and Space names.
• E2E: workspace-canvas.attention-inbox.spec.ts launches a real Claude hook agent in one project, switches to another and drives it to waiting. It then checks:
  • the rail badge and the inbox row appear in the same animation frame;
  • the row says "Site · Project canvas, Just now";
  • one click switches to that project and focuses the agent's terminal;
  • the row is gone on standby.

---

✅ Delivery & Compliance Checklist

• The local quick gate passes: pnpm verify:quick / pnpm pre-commit is green; any additional focused tests are reported above.
• Full CI passes on the final revision before merge; local quick checks are not reported as full regression.
• I have signed the CLA if required (see CLA.md).
• I have included new tests to lock down the behavior (or explicitly stated why it's untestable).
• I have strictly adhered to the DEVELOPMENT.md architectural boundaries.
• I have attached a screenshot or screen recording (if this touches the UI).
• I have updated the documentation accordingly (if adding a feature or changing a contract).

Local (macOS arm64):

• pnpm verify:quick passed: related Vitest 192 files / 910 tests, native contracts 6 / 9, representative E2E 15 tests.
• The inbox E2E passed 3/3 on repeat.
• The sidebar, primary-sidebar and Claude hook specs passed: 37 passed, 1 skipped.

First full CI run (39025693440, on 0dc403e9): every job passed except ci-macos (2), where color-identity.spec:282 and pixel-light.spec:167 failed in the shared wheel-zoom helper (zoom stayed at 1). That is the same failure seen on main before the rail change (spatial-pixel.materials:223), and it does not touch the sidebar. All three passed 9/9 locally on this build. Rerunning the failed job.

Full CI on the final revision: running.

📸 Screenshots / Visual Evidence

Inbox crops in Cove dark, Cove light, Pixel and Pixel light, from the real agent flow, are on the review page shown to the owner (who asked for review pages to be shown without waiting for approval).

🤖 Generated with Claude Code