@staix/agent-hub 0.12.23 → 0.12.25

package/docs/specs/2026-10-12-backlog-implementation-plan.md

@@ -0,0 +1,186 @@
+# Remaining implementation plan and issue audit
+
+## Scope and evidence snapshot
+
+- Owner request: audit all open issues, close completed work, correct partial work, plan the remaining implementation and retain the research track with a research label.
+- Repository: STAIxBWLB/agent-hub. Source baseline: main 7759ee8a3c5471e434ea6e0a7b73596a96bdf451, 2026-10-12 KST. The intake contains 27 open issues and one ready open PR, #346.
+- Nineteen delivery PRs have merged since the #324 intake: #325, #326, #328, #329, #330, #331, #333, #334, #335, #336, #337, #338, #339, #340, #341, #342, #343, #344 and #345. Do not equate source merges with release, installation or native acceptance.
+- Solo implementation continues under the existing owner constraint. No ahub coordination, delegated implementers, release, installation or live hub activation is part of this audit.
+- Repository issue bodies remain the acceptance contracts. This document orders their remaining slices; it does not replace their original criteria or authorize new research experiments.
+- Full vault enrichment is skipped for this repository-local audit: GitHub contracts, source and verification receipts resolve the scope without a person or institution ambiguity.
+
+## Phase 0: documentation and API discovery
+
+Read the applicable area notes before editing. Read every docs/agent-notes file before editing daemon.ts, main.ts or launch.ts. Re-read the issue and current source before each slice; this snapshot will drift.
+
+| Existing boundary | Confirmed source or pattern | Use in later work |
+| --- | --- | --- |
+| Task mutations | src/hub/tasks.ts, Board.propose/update in src/hub/board.ts | Extend Tasks, then persist; never mutate Board from an adapter, tool or CLI. |
+| Lifecycle | sdlcConfig, sdlcReceipt, readSdlcPr in src/hub/sdlc.ts; src/hub/workflow.ts; test/sdlc.test.ts and test/workflow.test.ts | Retain exact-head readbacks, bounded receipt claims and existing phase ownership. Custom stage definitions currently refuse. |
+| Profiles | projectProfile, profileClass in src/hub/profiles.ts; docs/profiles.md; test/profiles.test.ts | Reuse base-class mapping. PR #346 adds resolveProfile/mergeProfileOverrides; confirm its merged status before using those APIs. |
+| Roles | loadRoleCatalog, catalogAssignments, selectedRoles, catalogSection in src/hub/roles.ts; docs/roles.md | Guidance adds no authority. Reuse person settings and original proposal identity. |
+| Data policy | docs/data-policy.md; existing declared-path policy and local/Pi managed-tool tests | Extend one matcher, preserving lexical/real-path, alias and hardlink defenses. |
+| Document projection | src/hub/text-projection.ts, projection-exec.ts; docs/text-projection.md; test/projection-surfaces.test.ts | Bounded read-only conversion, scoped historical blobs and sanitized previews. |
+| Shadow Git | docs/profiles.md; test/shadow-repo.test.ts, shadow-cli.test.ts, shadow-daemon.test.ts | Explicit opt-in, protected bare metadata, no preview HEAD/index writes. |
+| Assignment | src/hub/routing.ts assign and route explain | One pure decision for execution policy and explanations. |
+| Evidence and memory | src/hub/research.ts, src/memory/client.ts, brief.ts, capture.ts, src/hub/ask.ts | Keep event identities, unknown observations, fail-open memory and PII exclusion. |
+| Native peers | docs/agent-notes/adapters.md; test/qwen-peer.test.ts; docs/verification/2026-10-11-jcode-peer-contract.md | Per-version capability and identity proof; no invented permission mode or restoration claim. |
+| Dashboard | src/hub/ui.ts and current settings/role controls | Preserve loopback, Origin refusal, CSP, keyboard access and existing public projections. |
+| Verification | docs/agent-notes/tests.md, scripts/check.sh, scripts/seeded-check.ts | Original assertion green, mutation assertion fails; guards run sequentially. |
+
+Allowed APIs are the existing names above and the source confirmed at the start of a slice. Proposed modules and commands below require a spec amendment before implementation; their appearance in this plan is not proof they already exist.
+
+## Audit disposition of every open issue
+
+| Issue | Disposition | Remaining closure evidence |
+| --- | --- | --- |
+| #1 | Keep open, native infrastructure | Authorized off-campus Access leg and natural attached Codex budget pause; never manufacture quota pressure. |
+| #8 | Keep open, research | Normal-use overlap count, conflict attribution and owner decision; review around 2026-10-14, extend if usage is insufficient. |
+| #30 | Keep open, research tracker; correct stale maturity checkboxes | L1-L5 and measured T1-T6, with separate research gates. #185-#189 are already closed. |
+| #41 | Keep open, research | Capability-led isolated transaction, quiescence, fenced two-part resolution, fault injection and actual supported native readback. |
+| #42 | Keep open, research | Versioned executable commitments and all five preregistered pilot arms after #41. |
+| #43 | Keep open, research | Documented development/held-out dataset, predictor and regime outcomes after #42. |
+| #44 | Keep open, research | Telemetry quality, trace replay, then optimizer/live week and review-routing comparison. |
+| #45 | Keep open, research | Adapter observability profiles first, then lattice/model/protocol analysis. |
+| #109 | Keep open, research | Current-version routing-time calibration and held-out errors; automatic rerouting remains gated. |
+| #198 | Keep open, research measurement | Actual PII model recall against fixed 0.90 bound, precision and unknown rate; existing screen is shipped. |
+| #199 | Keep open, research measurement | Mixed Pi/digest workload wait-time comparison; existing load/cooldown source is shipped and absent threshold stays off. |
+| #248 | Keep open, research | Tooling fingerprints, controlled arms, intervals and adopt/optional/drop decisions. |
+| #252 | Correct stale status; keep open, research measurement | GSD analysis and optional gsd-lite are merged; default versus gsd-lite measurement remains. |
+| #256 | Close completed optional implementation after transfer to #273 | AC3 allows explicit native unverified. Preserve identity/provider/tool/stop/recovery/quota obligations in #273; no default replacement. |
+| #257 | Correct partial status; keep open | Custom lifecycle schema, full merge/release readiness and actual advise cycle. Built-in gates/checklists already shipped. |
+| #258 | Keep open | Store/tiers/graph/retrieval, private sync/tombstones/leases, dashboard, import and controlled measurement. |
+| #259 | Correct partial checkboxes; keep open | Glob policy/Claude-grant interaction and PR #346 overrides. Native research-profile run remains explicitly unverified. |
+| #263 | Keep open | Backlog state, person/planner mutations, releases/dates, board/legend and optional read-only GitHub import. |
+| #264 | Keep open | Static Flat view, snapshot motion, optional ids, Isometric and backlog/release scene. |
+| #266 | Keep open, mixed implementation/research | Native capability table, task execution policy, matrix/recommendation and evidence-led escalation. |
+| #273 | Correct and expand owed native ledger; keep open | Dated actual receipts, including merged Kimi #328 and Qwen #331 follow-ups. |
+| #280 | Keep open | Attention model/console line, selected artwork and variants, then status/dashboard. |
+| #285 | Keep open | Owned Kimi wire usage, count windows, source-labelled budget surfaces; credential probe remains a separate decision. |
+| #286 | Keep open | Watch is shipped; terminal-provider integration and gated Qwen dual-output TUI/native coverage remain. |
+| #295 | Correct partial checkboxes; keep open | Reconcile original AC3 byte baseline and finish AC13 task-role board card after #263. Catalog/task/settings/session records already shipped. |
+| #324 | Correct master status; keep open | This ordered backlog and per-slice source/native/research receipts. |
+| #332 | Keep open | Jcode native project MCP tool receipt, remaining PII/native log proof and independently verified restored identity; current 0.94.0 cannot prove automatic restoration. |
+
+Research label set: #8, #30, #41, #42, #43, #44, #45, #109, #198, #199, #248, #252 and #266. A research project profile (#259) and research role definitions (#295) are product features, not themselves experiments. #1 and #273 are native verification ledgers. Mixed #266 remains labelled research while its independently reviewable source slices can proceed.
+
+## Delivery sequence
+
+Each numbered phase is a sequence of small PRs, not one large implementation branch. Work begins only from the current verified main. Preserve unrelated worktrees and unknown dirty work. Dependency arrows refer to completed source contracts, not assumed native success.
+
+### Phase 1: finish the active profile slice and data policy
+
+- Scope: #259; open PR #346 project overrides, then bounded pii.paths/data.readonly glob matching and Claude scoped-grant interaction.
+- PR #346 snapshot: head 384a222e77c74c9e37e6c238dd943da519a9e5aa, local full 2249/0 with check: OK, macOS and Linux platform checks successful after one limited Linux sidecar retry. The 133-guard job is still running at planning time. Both review findings are fixed/resolved. Do not merge before the complete exact-head receipt.
+- Read docs/profiles.md, docs/data-policy.md, docs/agent-notes/tasks.md, local-worker.md, adapters.md and tests.md. Follow the existing resolved-profile propagation and path-policy tests.
+- Specify accepted glob grammar, normalization, directory containment and limits before code; reject ambiguous/unbounded patterns. Use the same lexical/resolved matcher for private task classification, facts exclusion and managed write refusal. Unknown resolution remains conservative. A pattern cannot widen a protected grant.
+- Verify unchanged default dev bytes; isolated shared/local overrides; custom alias/base persistence; disjoint document sections across different owners; all native/local tool schemas; glob symlink/case/parent/hardlink tests; no marker in events/memory; Claude grant refusal for protected paths.
+- Exit: PR #346 merged with cleanup, then glob AC7 proved. Record native/model ingestion as unknown until actual receipts exist. Do not run a multi-agent research pilot as a source test.
+
+### Phase 2: lifecycle completion
+
+- Scope: #257 and the remaining specification boundaries informed by #252.
+- Read docs/sdlc.md, docs/gsd-collaboration-analysis.md, sdlc.ts, workflow.ts and their fake-gh suites. Reuse readSdlcPr, current head fences and existing reviewer/person ownership.
+- Slice A: bounded custom stages, actors and named gates, with cycle/duplicate/unknown validation and versioned persistence. Amend the spec first. Keep built-in default bytes and mode off/advise/enforce semantics.
+- Slice B: read-only merge ordering and release readiness: exact merged/head identities, required checks, unresolved requests/threads, docs stale/nonancestor status and owed native receipts. Every unavailable readback is unknown.
+- Slice C: shared CLI/console/dashboard projections with actor, blocker and next action; no auto-advance, merge/release, capability grant or second writable plan store.
+- Verify stale-head/late-read/reassignment races, missing check set, changes requested, custom gate cycle rejection, PII projection and old row compatibility. A fake GitHub is source evidence only.
+- Exit: source criteria implemented. AC6 actual advise cycle through merge/release remains a separately owed native/operational gate. #252 comparison stays open; full bidirectional GSD import needs its own authority/import contract.
+
+### Phase 3: project board and role card completion
+
+- Scope: #263, then #295 AC13 and AC3 baseline reconciliation.
+- Read docs/agent-notes/tasks.md and daemon.md, current Tasks/Board/routing and role settings controls. Add mutations only through Tasks.
+- Slice A: backlog state and validated promotion/demotion; prove backlog never routes, claims, offers, sweeps or escalates. Migrate legacy rows without rewriting history.
+- Slice B: planner grooming, bounded split/pull, batched notices, pinned/frozen release fences, reason/history and undo. Refuse non-planners and preserve private stubs.
+- Slice C: release create/allocate/freeze/ship and dates. Actual timestamps derive from history, not user input; ship requires all tasks approved or deliberately removed.
+- Slice D: five-column dashboard, ready/waiting distinction, status-backed peer legend, keyboard equivalent for person drag actions, task-role card and optional idempotent read-only GitHub import.
+- Reconcile #295 original 1cbbc57 baseline against the shipped d83cb8dd contract fixture before checking AC3. If an intentional contract amendment is needed, document the exact comparison and reason rather than changing the assertion silently.
+- Verify all state transitions, undo, scope freezes, old rows, actor refusal, marker privacy, keyboard/phone layout and CSP/Origin headers. Use one shared palette and projection.
+- Exit: board contracts and source role surfaces complete; an actual planner/two-release cycle remains unverified until separately run or explicitly recorded as unverified where allowed.
+
+### Phase 4: person attention and agent office views
+
+- Scope: #280 console attention, #264 office, then their dashboard integrations after Phase 3.
+- Read the full original visual contracts and existing console/dashboard models before frontend skills or assets. Use the approved design language and retain list/key paths.
+- Attention slice A: pure needs model from existing approval/default/delivery/storage/message/budget/recovery states; plain console line, count, configuration and --no-pet. No daemon change.
+- Attention slice B: mini/full and ascii/blocks STAI artwork with owner-selected alternatives and license/attribution. Unselected variants remain decisions; do not invent an asset adoption.
+- Attention slice C: optional ids/counts in status and ahub pet commands, then inline SVG/dashboard title count. Never expose task/approval/message bodies beside the pet.
+- Office slice A: officeModel, stable peer slots, static Flat SVG, Off default, keyboard/list highlighting, phone and theme proof; no scene actions.
+- Office slice B: snapshot-triggered motion with reduced-motion static equivalent and settle rules; unchanged snapshots cause no DOM writes. No polling animation loop.
+- Office slice C: bounded optional turn/checking/links id fields, old-page compatibility and no schema bump unless separately justified; then Isometric from the same model/focus order.
+- Office slice D: backlog wall/release docks/planner desk after #263. Measure each served-page size delta against the 30 KB budget.
+- Verify marker privacy, source-labelled attention counts, no outside/data requests, CSP unchanged, no inline handlers/style attributes, no-colour/phone/reduced-motion/keyboard behavior. Live browser/terminal looks remain separately recorded.
+
+### Phase 5: native memory foundations
+
+- Scope: #258. This changes the current hub-does-not-own-a-memory-store architecture; amend spec decisions 9/10 before source changes.
+- Read docs/agent-notes/local-worker.md, tasks.md, daemon.md, src/memory and ask.ts. Reuse privacy filtering and evidence-only answer identities; never include hub-model answers as fresh evidence.
+- Slice A: bounded append-only long-term store, short-term expiry, approval promotion of decision/contract/fail only, deterministic refs/plan/path/issue graph and supersession-aware retrieval. Establish schema/identity/version/tombstone rules first.
+- Slice B: memory CLI and CSP-local dashboard list/neighborhood/detail; incremental index equals rebuild. Suggested model edges stay excluded from briefs/ask until person-confirmed.
+- Slice C: private-remote git sync with two simulated AGENTHUB_HOMEs, immutable segments, concurrent writes and forget propagation. Verify remote privacy; missing/unreadable remote fails open with one notice.
+- Slice D: machine identity, long-term task leases, expiry/person force and explicit concurrent-claim conflict. A synchronized lease is not an atomic distributed lock; preserve uncertain ownership.
+- Slice E: bounded claude-mem import and optional proposed edges, retaining provenance/privacy and confirmed authority. Do not duplicate or mutate the existing claude-mem database.
+- Verify marker absence in store/index/remote, malformed/truncated segment recovery, supersession/linked fail ordering, replay equivalence, concurrent tombstones and lease conflicts.
+- Exit: source contracts and simulated sync proven. AC11 memory-off/claude-mem/native-graph study stays research evidence, not a synthetic acceptance claim.
+
+### Phase 6: execution policy and source-labelled usage
+
+- Scope: independently reviewable #266 source slices and #285 usage/budget surfaces.
+- Read docs/agent-notes/adapters.md, budget.md, models.md and benchmarks.md, routing.ts, research.ts and existing ACP occupancy/wire boundaries.
+- Policy slice A: source/version capability table for model and effort (launch/turn/none/unknown), then bounded per-task/role exec identity with planned/actual records. Unsupported changes refuse or remain visibly unavailable.
+- Policy slice B: trusted policy configuration through the same assign decision as explain; planner overrides only inside the allowed set with a reason; no permission/sandbox changes.
+- Policy slice C: bounded escalation ladder and reviewer risk rules, at most max_steps, unsupported steps recorded and ceiling sent to the person. No performance recommendation is auto-applied.
+- Usage slice A: owned Kimi session wire reader with offsets/rotation/truncation/schema/index fences and sub-agent attribution. Read only usage.record fields; never retain prompt/tool bodies, paths or session ids in public events.
+- Usage slice B: cache-excluded count-window function, fake-clock reset/pause/handoff, native/manual precedence and kind/source/age across budget/status/console/dashboard/doctor. Occupancy never becomes consumption.
+- Usage slice C: optional OAuth quota probe stays off pending the original exact authorization; no tracked token or inferred credential use. Probe failure remains unknown.
+- Verify unknown native cells, pure policy/explain equivalence, PII on-prem restriction, no policy-to-permission coupling, wire rotation/shrink/truncation markers, cache ceiling and old-client behavior.
+- Exit: source policy and usage proved. #266 matrix/Pareto/recommendation quality and native small matrix remain research gates. #285 live source timing/provider quota remain #273 receipts.
+
+### Phase 7: remaining native adapter and watch follow-ups
+
+- Scope: #286 and #332; #256 native obligations live in #273 after implementation closure.
+- Reuse the shipped watch ring/console-only side channel and Qwen/jcode identity fences. Read docs/verification/2026-10-11-acp-watch-t0.md and 2026-10-11-jcode-peer-contract.md.
+- Slice A: fixed-command terminal-provider integration for headless watch and peer-panel shortcut. No caller text, approval or command enters the watch scene.
+- Slice B: Qwen dual-output TUI only after real T0 Q2-Q6 proof; fail/unknown retains explicit refusal. Kimi stays its shipped pull-only TUI, not watch-driven TUI control.
+- Slice C: jcode-specific PII/marker/native log proof and project MCP tool-call receipt. Preserve foreign project entries, unmanaged policy, default-off roster and owned private daemon/socket.
+- Jcode 0.94.0 native session/load does not echo actual restored identity. Do not implement guessed automatic recovery. Wait for a separately proven interface/upstream capability; controlled recovery refuses before effects and manual reopening stays explicit.
+- Verify wrong runtime identity, foreign socket/override, stale entry, late native acknowledgement, owned process teardown and no new-conversation-as-restored claim. Native model/tool/stop/readback remains account-gated.
+- Exit: independently implementable source fixes merged; real native receipts either recorded or still open in #273/#332/#286. No accounts or live instances are started by this plan.
+
+## Preserved research and measurement sequence
+
+These items keep research labels and remain open. Existing issue-specific go-aheads, preregistration, real-account/resource requirements and study validity rules still apply; this planning request does not satisfy a missing experiment authorization.
+
+| Sequence | Issue and required work | Dependencies / exit evidence |
+| --- | --- | --- |
+| R1 | #109 calibration and held-out routing-time prediction assessment | Current-version profile and sealed outcomes; no evaluator leakage or rerouting enablement from source alone. Reuse #329 controlled study as its recorded evidence, not proof of unrun criteria. |
+| R2 | #45 T1 per-adapter observability/capability declarations | Version-specific tests and actual capability gaps; no exactly-once from snapshots or conversation revert alone. |
+| R3 | #41 isolated workspace transactions | R2; supported effect scope/quiescence, durable resolution phases, separate workspace/native rollback readbacks and late-effect fault suite. |
+| R4 | #42 executable commitments | R3; five complete preregistered regimes, target-bound validation/certificates and every requested attempt retained. |
+| R5 | #43 headroom predictor/regime selection | R4; documented dataset, held-out AUROC and always-solo/always-team comparison. |
+| R6 | #44 telemetry quality and trace-replay simulator, then optimizer | Can prepare independently of R3-R5; simulation error first, enough review outcomes, then actual live-week comparison. |
+| R7 | #45 remaining lattice/status, protocol/TLA+ model and five-vendor analysis | Composition reflects the limiting member and #41 conditional guarantees. |
+| R8 | #8 normal-use overlap measurement and owner decision | Review around 2026-10-14; low usage extends the window. It determines default isolation, not an opt-in #41 prerequisite. |
+| R9 | #198 and #199 shipped-system evaluations | Actual authorized local/on-campus screen and mixed load, fixed recall bound 0.90, uncertainty/precision/wait outcomes; defects get follow-up source slices. |
+| R10 | #252 gsd-lite, #248 add-ons, #258 memory and #266 model/effort comparisons | Sealed #251/#247 fingerprints, independent arms, failures/unknowns, effect sizes/intervals and inconclusive counts. No native adoption/default policy without data. |
+
+#30 tracks measured targets T1-T6 and stays open. #1 and #273 retain all infrastructure/native legs, including conditions that cannot safely be manufactured. Research measurement may find a regression; preserve the result and create/fix the actual defect rather than adjusting the target or calling unknown zero.
+
+## Verification and completion contract
+
+- Before heavy local work, read host pressure/current jobs and the resource policy, then use dot admission. One heavy job per repo across all worktrees. Exit 75 is a defer; wait or use already-authorized CI, never bypass or kill an unrelated job.
+- Every source slice gets focused regression checks appropriate to its contract, typecheck, generated plugin rebuild when imported inputs/version change, full scripts/check.sh ending check: OK, exact-head Linux/macOS CI and sequential seeded guards. Preserve original test assertions; a test failure is repaired in source.
+- Gate receipts name full source SHA, run URL, test/guard counts and outcomes. A rerun is an additional attempt, not deletion of the initial failure. Current PR #346's isolated sidecar failure and limited same-head retry remain in its receipt.
+- Refresh current-head source review and resolve/answer every actionable thread. Before merge read gh pr view --comments and unresolved threads plus pending changes requested. Quota-skipped review is not evidence.
+- After confirmed merge, fast-forward main, verify the merged tree, delete only the owned merged branch/worktree. Preserve any foreign/dirty checkout; do not force-remove it.
+- Issue closure requires every original acceptance criterion completed, or its explicitly allowed unverified disposition. Transfer an implementation issue's still-owed native leg to a named open survivor before closing, with exact criteria and no loss of scope. Research issues are retained under the owner's instruction.
+- A full release, installation, live hub activation and paid/account experiments are outside this audit. When separately authorized, use release merge commits, fresh/ancestor doc stamps, exact tag and actual installation/runtime readback. Never label code/CI as native success.
+- Re-read all remaining issue states after each phase; update #324 and the canonical claude-mem work state with completed source, open research/native criteria and the next independent slice.
+
+## Immediate next actions
+
+- Finish #346's 133-guard exact-head gate and fresh review readback; merge/clean only if all required checks pass.
+- Implement #259 glob policy/Claude-grant slice, then #257 custom lifecycle and release-readiness slices.
+- Proceed through board/roles, attention/office, memory and policy/usage phases in dependency order.
+- Keep all research-labelled items open, and record native prerequisites as unknown rather than manufacturing live conditions.

package/docs/specs/2026-10-12-office-view-design.md

@@ -0,0 +1,212 @@
+---
+title: Office view of live agent work in the dashboard
+date: 2026-10-12
+project: agent-hub
+status: phases 1-4 implemented (Flat and Isometric office with motion and turn/checking/link fields); phase 5 pending #263
+issue: 264
+---
+
+# Office view of live agent work in the dashboard
+
+Issue #264. The dashboard shows lists; seeing "who is doing what, with whom,
+right now" meant reading several of them. This spec adds an office view: a pure
+model, one SVG renderer, and (in a later phase) two projections. Ideas only are
+taken from agenttrail (e4ba2da) and Hermes3D (beb7629), both MIT; no code or
+asset is copied.
+
+## Design (all phases)
+
+- A pure, self-contained `officeModel(snapshot, previous, { cols })` in
+  `src/ui/office-model.ts` turns the snapshot into a scene description (desks,
+  rooms, cards, counts, marks, transitions) and is injected into the page by
+  `toString()` like `taskProgress`, before the CSP hashes are computed.
+- The model is built by allowlist: peer states, queue counts and permission
+  modes; task ids, classes, states, owners, reviewers, deps and public titles;
+  approval counts by peer; budget pause readings. `env.body`, task detail,
+  approval titles, paths and symbols never enter (marker test).
+- One renderer draws the model as inline SVG with `createElementNS`, from the
+  same `render(snapshot)` call as the lists, only when its signature changed.
+  No timer, no `requestAnimationFrame`, no request. Colours come from the
+  page's theme tokens through CSS classes; every state also carries a glyph
+  and a text label.
+- An always-visible View control in the page header offers Off (the default), Flat, and in
+  phase 4 Isometric; the choice persists in the host-scoped `agent-hub-office`
+  cookie with the `agent-hub-theme` attributes and try/catch fallback (#246).
+- Layout: stable desk slots (claude, codex, kimi, pi, local, then others by id;
+  sticky across snapshots via the previous scene, so a peer keeps its slot when
+  others come and go); rooms are the board columns in a fixed order; at most 8
+  cards per room then "+N more" (filters the task list to that state); the Done
+  shelf is a count; more than 12 desks shows "+N peers". `cols` comes from the
+  section width: rooms left to right when wide, stacked when narrow.
+- Interaction: desks and cards are focusable SVG groups with `role="button"`
+  and accessible names; activation scrolls to and highlights the matching list
+  row, and a list row highlights its desk or card on focus and hover. The scene
+  performs no action and sends no request; the closed action list is unchanged.
+- Room counts equal `taskProgress(tasks).counts` for the same snapshot (pinned
+  by a test, including randomized boards).
+
+## Phasing (per the issue)
+
+1. `officeModel` and the static Flat office: desks, states, rooms, cards,
+   counts, the view control, list highlighting. No daemon change. (This
+   document's implementation phase.)
+2. Motion from the snapshot: card moves, message arcs, delivery marks, the busy
+   latch, the settle rule. No daemon change.
+3. Optional snapshot fields `turn`, `checking`, `links` and what they draw.
+4. The Isometric projection of the same model.
+5. Backlog wall, release docks and the planner's desk, once #263 lands.
+
+Phase 1 decisions within the spec:
+
+- `previous` is the previous scene model, not the raw snapshot: sticky slots
+  and transitions both read from it, and `resetView` clears it so a project
+  switch starts fresh.
+- The primary condition of a desk is the first of offline, paused, waiting on
+  approval, busy, idle; the raised-hand count, inbox tray, mode badge and break
+  sign are independent marks that combine freely with it.
+- Work-floor cards sit at the owner's desk (at most 3, then "+N more" as text);
+  a card whose owner has no visible desk waits in the Work floor room. Tasks in
+  an unknown state are counted (`counts.unknown`) but placed nowhere.
+- The busy bubble names the task only when the peer has exactly one
+  `in_progress` task; it is never guessed (phase 3 adds the exact `turn`
+  field).
+- Transitions are computed as data in phase 1 (desks added/removed, cards
+  moved); they drive motion only from phase 2.
+
+Phase 2 decisions within the spec:
+
+- Motion is CSS only. Cards are persistent keyed SVG nodes positioned by CSSOM
+  `transform`, so a changed placement animates through a `transform` transition
+  (0.8 s); desks never move and are rebuilt in place when their content
+  changes. The busy glyph and the raised hand pulse (`opacity` keyframes); an
+  idle desk has no animation class. `prefers-reduced-motion: reduce` removes
+  all scene transitions and animations.
+- Arcs, delivery marks and the busy latch are transient marks with an absolute
+  expiry timestamp in the model. The renderer draws them once with a keyframe
+  fade whose delay is computed at render time (hold, then fade over the final
+  second, `fill: forwards`), so "fade after 10 seconds" needs no timer; expired
+  nodes purge lazily on the next changed render or on their own animationend.
+- The model's clock for arc expiry is the snapshot's own newest envelope
+  timestamp (`eventTime`), not wall time: an unchanged snapshot yields an
+  identical model at any wall time, so the signature guard still writes
+  nothing. Wall time enters only as `options.now` at the moment an event row is
+  first consumed (alert/latch horizons) and in the settle gap.
+- Event rows are deduped by `seq` against `lastSeq`, so re-rendering the same
+  snapshot (for example after a task-filter change) draws nothing twice. The
+  first snapshot after load or a project switch consumes rows without drawing
+  them: no replay of history.
+- The settle flag is carried unchanged while nothing moves, and recomputed when
+  a snapshot brings changes: gap over 3 s since the last change, or more than
+  6 transitions (card moves, desk adds/removals, new marks) at once, jump
+  straight to final positions.
+- Arc fan-out: an envelope with no `to` draws an arc to every visible desk; a
+  `from` that is not a peer (hub, console) starts at a fixed anchor point.
+  Delivery marks from `quiet` rows land on every named peer; `off_roster` rows
+  are not drawn (the mapping table names only overflow, undeliverable, stale
+  and quiet). Event `reason` strings are never copied into the model.
+
+Phase 3 decisions within the spec:
+
+- `status.peers[id].turn` is built in `uiSnapshot` from the daemon's `turns`
+  map as `{ since, task?, attribution }`. A private turn (a peer holding a PII
+  task) or an attribution flagged `pii` omits `task`; such a turn can exist
+  only for the in-process local worker, since the board refuses PII tasks to
+  any other owner.
+- The exact busy bubble uses `turn.task` whenever present (even when the peer
+  has zero or several in_progress tasks, and even if the task meanwhile left
+  the board, then with a plain label). The phase-1 heuristic is the fallback
+  for an older daemon that sends no `turn`.
+- `tasks[].checking` comes from `Tasks.isChecking` at snapshot time. A checking
+  task stays `in_progress`, so its card never moves; the mark is a glyph plus
+  an accessible-name note, not a state.
+- `links[]` is assembled in `uiSnapshot`: overlap pairs from the new
+  `Tasks.overlapLinks()` (the board's own `overlapHits`, so `ahub route` and
+  the scene cannot drift) and `Tasks.cohortLinks()` (`Cohorts.list()`), plus
+  conflicts from a bounded (12) in-memory list the daemon fills where it
+  already emits `conflict` events, deduped by task pair and dropped once either
+  task leaves the open states. All three carry task and peer ids only; overlap
+  and cohort links exclude PII tasks through `overlapHits`/`formCohort`.
+- The scene validates links down to the three kinds and their id lists (an
+  older or newer peer of the protocol that sends more is ignored), draws a
+  dashed line per consecutive desk pair with a kind/task-ids label, and treats
+  links as state: no fade, present while the link exists.
+- `PROTOCOL` (16) and `EVENTS_SCHEMA` (1) are pinned by a test; the fields are
+  additive and optional both ways.
+
+Phase 4 decisions within the spec:
+
+- Isometric is a pure coordinate projection at the renderer, not a second
+  scene: `officeProject(x, y)` maps grid coordinates to (x - y) cos 30,
+  (x + y) sin 30 and every node is laid out upright in local coordinates and
+  positioned by its projected CSSOM transform. Desk and room tiles become
+  parallelogram polygons (the linear image of their rect); cards, text labels,
+  bubbles, marks and arc labels stay upright. No WebGL, no library, no new
+  route, no CSP change.
+- The DOM is projection-independent: the same keyed nodes in the same order
+  with the same accessible names, so focus order is identical (AC7, tested by
+  comparing serialized tab order between Flat and Isometric). The viewBox is
+  the projected bounding box with a small margin; the SVG keeps `width: 100%`,
+  so phone width scales without horizontal page scroll.
+- A projection switch repaints every node in place (the projection is part of
+  each reconcile signature) and is treated as a settle: positions jump, no
+  transform transition storms. Card moves under Isometric animate through the
+  same transform transition as Flat; reduced motion removes it all as before.
+- Size accounting against the issue's 30 KB budget (page base 59,329 bytes at
+  phase 1 branch point): phase 1 +11,040, phase 2 +7,340, phase 3 +2,141,
+  phase 4 +1,704, art polish +3,559; final 89,113 bytes, +25,784 total,
+  inside the budget. The iso shelf's base skirt was dropped to stay under it.
+- Art polish (2026-10-12): two reference concept images (a flat view and an
+  isometric view) were generated with Higgsfield (nano_banana_pro) and kept
+  outside the repo (scratchpad); they served as drawing references only. Per
+  this issue's "art made in code, with no image files" rule, nothing ships as
+  an image: no asset files, no CSP change, no new route. What was adopted:
+  outline-shape condition glyphs (pause bars, ring, filled dot, cross) and a
+  raised hand drawn as palm-and-fingers shapes, a person avatar per desk
+  (inside the flat tile; standing behind the iso desk), an extruded iso desk
+  (top plus two front legs), a name plate parallelogram on the iso desk's
+  front edge, the warm-accent (--amber) emphasis on a waiting desk, faint
+  wireframe iso room boxes with small-caps labels at the base, a Done shelf
+  cabinet (flat) and stacked boxes on a slab (iso) with the count kept as
+  text, two-column room cards with thin dividers, and arc arrowheads at the
+  target end.
+
+## Verification
+
+- `test/office-model.test.ts`: mapping fixture, counts equality with
+  `taskProgress`, slot stability, transitions, caps, glyph/label coverage, the
+  marker test (no body, detail, approval title or PII text in the model);
+  phase 2: arcs, delivery marks and the busy latch from event rows, no replay
+  on the first snapshot, seq dedupe, arc expiry on the snapshot clock, and the
+  settle rule (first snapshot, gap, transition storm, flag stability);
+  phase 3: the exact bubble and its fallback, finishing-a-turn, the checking
+  mark, link validation, and markers in turn-adjacent data, check output and
+  conflict reasons never reaching the model.
+- `test/office-view.test.ts`: injection and CSP cleanliness of the served page,
+  the cookie (default Off, persistence, blocked-cookie fallback), no
+  timer/request/colour literal in the scene code, reduced-motion and motion CSS
+  scans, no DOM write on an unchanged snapshot (counting fake document), focus
+  and activation highlighting, "+N more" filtering, `resetView` clearing;
+  phase 2: card moves keep their node and animate by transform, arcs/marks/
+  latch draw once with fade timing, departure fade purges on animationend;
+  phase 3: the exact bubble, finishing-a-turn line, check-running mark and
+  warning lines render.
+- `test/tasks.test.ts`: `overlapLinks`/`cohortLinks` carry ids only and exclude
+  PII tasks. `test/daemon.test.ts`: `ui_snapshot` carries `turn`, `checking`
+  and overlap/cohort links against a real daemon, pins `PROTOCOL` (16) and
+  `EVENTS_SCHEMA` (1), and proves a PII task keeps its stub, refuses a
+  non-local owner and joins no link.
+- The live browser look (two agents working, both themes, console open) is
+  recorded in `docs/smoke.md` as unverified for phase 1.
+
+
+## Merge review corrections
+
+Current snapshot task privacy is checked again when warning links are built,
+including cohorts and conflicts created before a task became private. The Off
+selector stays visible outside the hidden scene. Filtered card activation reveals
+its task; Work overflow includes rework. Sticky desk coordinates set scene bounds.
+The existing snapshot poll prunes transient deadlines even when the model is
+unchanged; reduced-motion departures are immediate and settled paints receive no
+appearance class. Explicit unattributed turns never use the legacy task guess.
+Large warning caps prioritize conflicts; distinct kinds use parallel offsets.
+Original test assertions are retained. Physical visual readback remains pending.

package/docs/text-projection.md

@@ -0,0 +1,19 @@
+# Bounded text projections (#259)
+
+- Optional machine-local text_projection maps lowercase extensions to argv arrays. Each uses one separate {input} argument. No shell string, automatic converter install or default command.
+- Example: { "text_projection": { ".docx": ["/usr/bin/textutil", "-convert", "txt", "-stdout", "{input}"] } }. Configure the converter explicitly for the machine. Shared/tracked config cannot choose these programs.
+- Facts excludes private paths before conversion. The converter reads an immutable snapshot in an owned temporary directory, from its own scratch directory, with literal read grants for that file and for the program and script files its argv names (relative ones are passed as absolute paths, and the directories above an in-project script can be listed) (nothing else in the project is readable, even under a `local.read_allow` entry that encloses it, so a converter that follows an include or loads a sibling helper module fails), uses the existing macOS no-network/read-only sandbox and has a 5-second deadline, 16 MiB input cap and 256 KiB stdout/stderr cap. A trusted helper owns and stops its process group; converter stderr is never published.
+- Output caches in state by raw content hash, extension and argv/program/script metadata fingerprint. Invalid/oversized cache or failing/unavailable conversion falls back to the existing raw/binary facts behavior, with one bounded notice per extension. A conversion that fails with its full deadline is not tried again for the same bytes and command for the life of the hub process, within a bounded in-memory record (#382).
+- Raw hashes and git blob identities remain the change identities. Projected text only supplies presentation diffs. A projected read or patch cannot establish raw-file write attribution. Existing text privacy checks and header sanitization still apply.
+- Converter programs may require temporary writes/caches; those fail under this read-only policy. Use a converter that emits stdout. The owner and other native same-user processes remain outside this boundary.
+- Linux retains no-sandbox/no-converter behavior. No native model/account study runs. Shadow repositories and profile override/glob follow-ups remain open in #259.
+
+# Review and undo previews
+
+- A configured projection adds text diffs to review notices and `ahub undo` previews. These are project-snapshot changes, not evidence of authorship or permission to restore raw files.
+- Review uses the original task-proposal snapshot, persisted by task id and proposal time. Reviewer replacement and daemon restart retain that baseline. It is never repaired with a later snapshot. Missing or pruned baselines, undeclared paths, disabled snapshots and private snapshot windows are marked unavailable.
+- Review includes changed files under declared refs/plan paths and section files only. Private tasks have no review projection. Declared private paths are withheld before conversion; private-data patterns are withheld before publication. Document bodies enter neither task history nor memory through this feature.
+- Undo projects the recorded end snapshot back to the recorded start snapshot. It still checks raw files for later edits, concurrent/unknown turns and pruned trees, then repeats its plan immediately before restore. Conversion never writes or authorizes a raw restore.
+- Historical blobs must be regular files in the project scope. Symlinks, hub/git metadata and denylisted paths are refused. Deleted and created documents use their stored bytes; no current file read substitutes for a missing old version. Converter identities must agree across a pair.
+- A preview shares an 8-second monotonic deadline across git reads, conversion and diffing. Each converter still has at most 5 seconds; termination stops its owned process group. At most 8 files and 12000 UTF-8 bytes of presentation are shown, with explicit omissions. CLI previews strip terminal controls and all inserted headers are quoted.
+- Converter failure preserves the ordinary file-only view. Linux continues to refuse conversion without the supported sandbox. Native model consumption and live research-profile/account studies remain unverified.

package/docs/verification/2026-10-11-acp-watch-t0.md

@@ -0,0 +1,33 @@
+# ACP watch verification, 2026-10-11
+
+- Scope: #286 Part 1, headless Kimi/Qwen transient watch only. No native account, model, TUI or production hub was started during this solo implementation.
+- Base: e4146115, agent-hub 0.12.23, protocol 16. Fake protocol tests establish the hub contract; they do not establish what a vendor actually emits.
+- Kimi source baseline: 2.1.1, recorded in #286. Qwen source baseline: expected ACP 0.25.0; #256's source inventory found installed CLI 0.25.0 versus ACP/package 0.24.1. The production adapter refuses that identity drift.
+
+| Check | Verdict | Reason and consequence |
+| --- | --- | --- |
+| K1 | Unverified | Native read/edit/command/approval turn not run. Fake ACP message/thought/tools/plan/approval projection is tested, actual field coverage unknown. |
+| K2 | Unverified | No concurrent native visualizer session. No `watch --native` offered. |
+| K3 | Unverified | No second writer started. No concurrent resume command offered. |
+| K4 | Unverified | No Kimi web session inspection. ACP transport retained. |
+| Q1 | Unverified | Installed ACP identity drift; no native turn run. Fake 0.25.0 contract only. |
+| Q2 | Unverified | Dual output busy/submit round trip not run. TUI mode remains refused. |
+| Q3 | Unverified | Native dual-output approvals and MCP identity not run. No TUI permission mapping shipped. |
+| Q4 | Unverified | No native external turn cancellation test. No TUI watchdog shipped. |
+| Q5 | Unverified | Unread native event-file limit not tested. No file transport shipped. |
+| Q6 | Unverified | Native TUI recovery not tested. Existing ACP recovery stays separate. |
+| Q7 | Unverified | Final isolated provider environment not exercised; CLI version alone is insufficient. |
+
+# Delivered contract
+
+- `ahub watch kimi|qwen` subscribes to a console-only memory ring, replays it, then streams new items. It sends only `watch` and `status` requests. `q` and Ctrl+C leave without stopping the peer.
+- The ring holds at most 500 items and 256 KiB of serialized UTF-8 JSON per peer. Item text is bounded at 4096 UTF-16 code units. Message/thought chunks coalesce up to that cap or a 50 ms flush boundary; tool/permission/end boundaries flush synchronously.
+- Tool updates project only declared fields, locations and bounded last text lines, or diff line counts. ACP terminal references without inline output say output is unavailable; filesystem/terminal capability remains disabled. No terminal RPC or native session file is read.
+- Private envelopes, daemon-marked private turns and associated PII work show one stub. Privacy stays latched if the task closes during the turn; unreadable privacy state also withholds activity.
+- Watch is unavailable for Kimi pull-only TUI mode, off-roster Qwen and non-ACP peers. Jcode is outside this slice. No terminal-provider automation or console Peers-panel shortcut ships here.
+- Existing final-answer delivery and existing native approval display (console and dashboard) retain their own policies. Watch adds no copy to the bus, events, hub.log, UI, tools or claude-mem. A final answer containing a marker can still reach the existing answer bus; that is not a watch side channel.
+- Native payload coverage, model/tool execution and TUI claims remain unverified. No performance or quality comparison was measured.
+
+# Marker fixture provenance
+
+- Existing ACP approval payloads appear in the dashboard as well as the console (`uiSnapshot` and the existing dashboard allow/deny integration test). Watch does not change that approval policy. The transient-only marker is in thoughts, read/edit tool arguments and tool output; the separate executable approval command and final answer are ordinary unmarked fixtures. The test checks the transient marker is absent even while that independent approval is pending. All marker assertions are retained.

package/docs/verification/2026-10-11-agent-config-inventory.md

@@ -0,0 +1,20 @@
+# Project agent configuration inventory (#323)
+
+Read on 2026-10-11. No native model turn was run. Version commands: Claude Code 2.1.296, Codex 0.146.0, Kimi 2.1.1, Qwen 0.25.0, Pi 1.0.1. The Qwen npm manifest at the selected executable tree says 0.24.1 despite the CLI reporting 0.25.0; do not use the manifest as served/native-version proof.
+
+| Peer | Project paths established | Source and limit |
+| --- | --- | --- |
+| Claude | `.claude/settings.json`, `.claude/settings.local.json`, `.claude/skills/`, `.claude/agents/`, `.mcp.json` | [Vendor settings](https://code.claude.com/docs/en/settings), [skills](https://code.claude.com/docs/en/skills), [MCP](https://code.claude.com/docs/en/mcp). Closed vendor source; current documentation, no native discovery run. |
+| Codex | `.codex/config.toml`, `.agents/skills/`; legacy skills in config roots | [0.146.0 loader](https://github.com/openai/codex/blob/be449751a978f02e5bbba886999662956c7f38f5/codex-rs/core-skills/src/loader.rs), `repo_skill_roots` probes `.agents/skills` between cwd and project root. Config commands and trust are vendor-owned. |
+| Kimi | `.kimi-code/mcp.json`, `.kimi-code/local.toml`, `.kimi-code/skills/`, `.agents/skills/` | [2.1.1 skills](https://github.com/MoonshotAI/kimi-code/blob/a00639d0654d2c91c6f0c1388267b62ad51f8b9c/docs/en/customization/skills.md), [configuration](https://github.com/MoonshotAI/kimi-code/blob/a00639d0654d2c91c6f0c1388267b62ad51f8b9c/docs/en/configuration/config-files.md), [MCP](https://github.com/MoonshotAI/kimi-code/blob/a00639d0654d2c91c6f0c1388267b62ad51f8b9c/docs/en/customization/mcp.md). Project stdio MCP entries run local commands. Legacy `.kimi` remains protected for earlier versions. |
+| Qwen | `.qwen/settings.json`, `.qwen/skills/`, `.agents/skills/`, `.qwen/hooks/`, `.qwen/commands/`, `.qwen/agents/`, `.mcp.json` | Installed `chunks/chunk-ZYDMQCQP.js` declares `SKILL_PROVIDER_CONFIG_DIRS = [".qwen", ".agents"]`; `chunk-J6QWYIXU.js` maps them to `<projectRoot>/<provider>/skills` and lists startup/configuration paths. [Vendor skills](https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/). Package-version mismatch above; no live discovery claim. |
+| Pi | `.pi/settings.json`, `.pi/skills/`, `.pi/extensions/`, resource paths configured there | [1.0.1 resource loader](https://github.com/earendil-works/pi/blob/a7229ddc21810d6245105978033b7df645ecc2f7/packages/coding-agent/src/core/resource-loader.ts). Installed package documentation also lists `.agents/skills`; that additional discovery path was not proven in the executing bundled CLI. It is protected by the shared rule regardless. |
+| Local | `.agenthub/config*.json`, `.agenthub/routing*.toml`; no native skill/MCP discovery | Repository loader and local tool implementation. The existing hub configuration refusal applies. |
+
+## Decisions
+
+- Exclude `.agents` from scoped automatic file grants: skills may direct code/tool use and are loaded by several supported peers. Existing `.claude`, `.codex`, `.qwen`, `.kimi`, `.kimi-code`, `.pi` and `.mcp.json` exclusions cover their configured project resources.
+- Exclude `.claude.json` conservatively as an agent configuration filename. The documented default is home-level `~/.claude.json`, not a project-local file; default project discovery of `.claude.json` was not established. Do not claim that adding this name proves a project loader exists.
+- The owner's 2026-10-11 decision keeps `AGENTS.md`, `CLAUDE.md`, `QWEN.md` grantable by default. `scoped_grants.protect_instructions` enables protection for those three names only, including folded and symlink spellings. It persists as machine-local `protect_instruction_files`, applies after the settings write or undo, and is available only through person settings surfaces.
+- Configured arbitrary skill/hook paths and configurable context filenames are not a complete name inventory. The hub does not infer additional protected filenames from arbitrary native settings. No guarantee for every vendor-loaded path follows from this list.
+- The option affects scoped writes/edits, not instruction reads or explicit human approval/never-ask. A tracked project file cannot set this machine-local policy. Ordinary dashboard sessions may enable protection, but weakening it requires a settings session; agent/tools/conductor surfaces cannot change it.

package/docs/verification/2026-10-11-jcode-peer-contract.md

@@ -0,0 +1,27 @@
+# Jcode peer contract (#332)
+
+Installed CLI: jcode 0.94.0, release build b6c63ff04ca6786d4d328a086d7f3ac06d6fb578, read through version --json. This identifies [1jehuang/jcode](https://github.com/1jehuang/jcode/tree/b6c63ff04ca6786d4d328a086d7f3ac06d6fb578), not the unrelated cnjack/jcode project.
+
+## Verified source surfaces
+
+- src/cli/acp.rs: native identity jcode/package version, protocol 1, new/load/prompt/cancel/close. Session-scoped mcpServers arrays are tolerated but ignored. No session/set_mode or request_permission mapping is provided.
+- crates/jcode-base/src/mcp/protocol.rs and manager.rs: per-session project directory selects .jcode/mcp.json, then .mcp.json, then .claude/mcp.json. Later names override. Both servers and mcpServers are accepted; shared:false makes the connection session-owned.
+- src/cli/dispatch.rs and crates/jcode-app-core/src/server/socket.rs: serve runs in the foreground, a private --socket selects the runtime, JCODE_READY_FD signals listening, temporary-server/owner-pid support cleanup. Automatic updates and self-dev can be disabled. No global stop command is required.
+- Native MCP first-use import can write Codex definitions into Jcode's global store. The hub refuses startup until that native store exists; it never initializes or copies it. Credentials stay in the operator's native store.
+- ACP load returns no restored id while attach_existing_session can replace its internal id from History. Therefore 0.94.0 cannot prove restored identity through this interface. Automatic crash/controlled recovery is withheld. A manually requested load must echo an exact id or refuses without a model prompt or restored claim. Fakes can exercise that positive echo contract; they do not establish native 0.94.0 restoration.
+
+## Alternative assessment
+
+| Surface | Jcode | Qwen | Pi |
+| --- | --- | --- | --- |
+| Integration | Owned daemon/socket plus ACP and project MCP | Owned ACP, session MCP | Native events and hub-moderated tools |
+| Permission boundary | Unmanaged native policy, no hub sandbox | Version-specific native modes, no hub sandbox | Hub path guard/sandbox for managed tools |
+| Provider choice | Operator's native provider profile | Operator's native provider | Existing hub relay policy |
+| Recovery | Refuse unproven native identity restoration | Saved ACP conversation | Existing file/id restoration |
+| Quota | Unknown unless observed/pinned | Unknown unless observed/pinned | Existing on-prem policy and measurements |
+
+No local comparison of RAM, latency, quality, resources or operator overhead ran. Upstream performance claims are not this workspace's measurement. Jcode is optional and does not replace class defaults or establish reliable verification from a role label.
+
+## Unverified native legs
+
+Provider/model serving, project MCP discovery and a real hub-tool call, native permissions, native stop/child teardown and recovery all remain unverified. Source inspection, fakes, a CLI version and a listening socket are separate evidence, not native model/tool readiness.