@staix/agent-hub 0.12.26 → 0.12.28

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 Issue and pull request numbers in the entries for 0.7.7 and earlier refer to the previous repository, archived on 2026-09-30 when this repository's history was rewritten; the one exception is the open smoke-check issue, formerly #12, which moved here as #1. Numbers in newer entries refer to this repository.
 
+## 0.12.28
+
+- Recover an offline Pi owner with person-selected preserved history via `ahub pi --replace-session --session-file`, retaining prior identity metadata and queued work while refusing live owners and unsettled effects (#403).
+
+- Tell a pull-only session (a Kimi TUI, a Claude session without pushes) that important messages are waiting: the hub sends an advisory count over its control link and every hub tool result but `hub_inbox` ends with it until a read drains them; `hub_inbox` replies also carry the important count. Make `scripts/check.sh` take a heavy-job slot shared by every worktree of the repo, so a second gate waits (bounded by `AHUB_CHECK_LOCK_WAIT_S`) and names the holder instead of overlapping (#398).
+
+## 0.12.27
+
+- Refine the dashboard Office view with an intrinsic 12 px/unit scale, 1 px non-scaling hairlines and padded room cards in flat and isometric themes, and un-nest the desk More control into a separately reconciled sibling button so screen readers can reach it (#394).
+- Shrink the floating pet window to a compact 150x150 panel with the original pixel art in deeper state colors and a configurable base palette (`pet.palette`, or 1/2/3/4 while the window is key: blue, teal, violet, ochre) with a matching rim line so it reads on light backgrounds, reveal the status pill and message composer only while the pointer is over the character, and drop the pill shadow (#391 follow-up).
+- Split the local dashboard into cookie-backed views, compact task cards with shared dialog/column details, and exact-id attention badges; move character presentation to the standalone pet window (#391 Task A).
+- Add an opt-in macOS floating pet window with built-in pixels, counts-only local state, a console message pencil, saved position and signed process ownership; keep terminal pet reads available to agent shells (#391 Task B).
+
 ## 0.12.26
 
 - Import claude-mem observations under a checkout-independent identity, so the same observation is one entry on every machine after sync however the checkouts differ; scan the source database project-aware with a persisted machine-local cursor (`--restart` re-scans), so unrelated projects cannot starve the requested one; reconcile legacy duplicate imports with `ahub memory dedupe` through append-only supersede operations (#380).

package/README.md

@@ -4,7 +4,7 @@ Native multi-agent hub for one developer's machine: Claude Code, Codex, Kimi Cod
 hub-owned local-LLM worker, with optional Qwen Code and Jcode support, collaborate as peers in independent project directories, with
 task-aware model routing (Switchyard) in front of a self-hosted gateway (OmniRoute).
 
-Status: 0.12.26, control protocol 16. Durable delivery records distinguish queued
+Status: 0.12.28, control protocol 16. Durable delivery records distinguish queued
 work from uncertain execution. The [smoke checklist](docs/smoke.md) records
 verified paths and remaining prerequisites.
 
@@ -33,7 +33,7 @@ cd <your project> && ahub init && ahub up
 Or install the same version from GitHub:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.12.26 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.12.28 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.
@@ -81,7 +81,7 @@ an N-peer message bus and attaches each agent through its native control surface
 | --- | --- | --- | --- |
 | Claude Code | channel plugin push (`notifications/claude/channel`) under `ahub claude`; otherwise tools-only, read with `hub_inbox` | MCP tools | queued by Claude Code, grouped on next turn; tools-only: queued at the hub |
 | Codex | app-server `turn/start` (idle) / `turn/steer` (busy) | proxy intercepts `item/agentMessage` | steer or queue |
-| Kimi Code | ACP `session/prompt` | ACP `session/update` stream | queue (`turn.agent_busy`) |
+| Kimi Code | TUI: pull with `hub_inbox`; headless: ACP `session/prompt` | TUI: `hub_send`; headless: ACP `session/update` stream | TUI: hub queue with important-count hints; headless: queue (`turn.agent_busy`) |
 | Pi | RPC or managed native TUI extension | hub-approved tools | queued until `agent_settled` |
 | Local worker | hub-native agent loop | hub-native | hub-owned |
 

package/docs/agent-notes/bus.md

@@ -14,6 +14,7 @@ Scope: delivery, digests and condensation, reply addressing, priority and limits
 - A reply is addressed, never broadcast. An adapter that answers a delivery passes `to: replyAudience(envs)`; anything else with an `inReplyTo` inherits that envelope's sender. Leaving `to` empty fans the message out to every peer.
 - `digest` is not a peer: addressing a reply at the envelopes the peer was handed sends it nowhere once a delivery was condensed. The bus resolves `digest` back through `lastDelivery.originals`; anything else that reads a reply's `to` has to do the same.
 - A pull-only peer (a Claude session without channel pushes or Kimi in its own TUI) is never drained; `Bus.pull` hands it what one push would take. Drain and pull share `held()` (recovery, an uncertain delivery, any pause, the lifecycle `deliveryHeld` fence) and `remember()` (so `reply_to` resolves), and a drain rechecks `deliverable()` after condensing because such a session can take the peer meanwhile. A pull is journaled `completed` in the same transaction as the bus snapshot, never `accepted`; a failed one puts back only that peer's queue and preface and never reloads the snapshot.
+- The `onImportantQueued` nudge for a pull-only peer (#398) is advisory: it never dequeues, steers, journals or settles, and a throw from it never stops an enqueue.
 - `resolveDelivery` mutates queues in place; a refused or failed resolution puts back only that peer's queue and preface and keeps every pause. Never reload a snapshot on a live bus.
 - `restore` takes queued work from the journal, never from the committed snapshot once the journal has state (an empty journal, revision 0, is seeded from the commit): from the commit only an empty queue key is carried over, for an offline peer whose key no delivery ever persisted (#234). Never resurrect a non-empty queue from it.
 - The journal's owner check (`rejectLiveOwner` in `delivery-journal.ts`) judges the manifest pid with `processLiveness` and its `pidSignature`, never a bare probe (rule: `daemon.md`).

package/docs/agent-notes/tests.md

@@ -14,5 +14,6 @@ Scope: tests, fakes and the test gate. Read before adding or changing a test or
 - A request that a test expects a stop or shutdown to cut gets its rejection handler where the request is created, never after the awaited teardown: a late `catch` races the reset and the run fails on an unhandled rejection.
 - Run `bun scripts/seeded-check.ts` before reporting the seeded-guard gate complete. Keep the `scripts/seeds.json` cases sequential; require the same named test green before its seeded assertion fails. Seed rot, survivors, setup/compiler failures, timeout/watchdog termination and process leaks fail the gate. Never run the full seed runner from a unit test or mutate the source checkout; inspect preserved failed fixtures before removing them. CI runs this in the required Linux `seeded guards` job after the ordinary check, separately from `scripts/check.sh`.
 
+- `scripts/check.sh` holds the repo's heavy-job slot (`<git common dir>/ahub-heavy.lock`, #398) for the whole run, so a test never runs the real gate; `test/check-lock.test.ts` runs a copy in a scratch repo.
 - The whole-suite watchdog is `AHUB_CHECK_HANG_S` (default in `scripts/check.sh`, hosted macOS value in `.github/workflows/check.yml`; #378, macOS CI hit it while tests still passed): raise it only when the suite was still progressing at the cutoff, never for a hung test, and keep the per-test 20 s timeout.
 - A seed's named test must run on Linux, where the seeded job runs: a darwin-only test reports no result there and fails the job (#382). Cover a macOS-only protection with its regression test instead.

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.12.26 and control protocol 16. Live verification
+This guide describes ahub 0.12.28 and control protocol 16. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Command output
@@ -156,8 +156,8 @@ status read it says loading; later failures preserve the prior count with a noti
 Panels retain their existing full-board refresh and loading/error handling.
 
 The dashboard Task board shows the same shared public-board progress model,
-including state counts, waiting, stacked segments and a labeled four-stage track
-per row. Filtering rows does not filter overall progress. The existing signature guard
+including overall state counts, waiting and stacked segments; each task detail
+retains its labeled four-stage track. Filtering rows does not filter overall progress. The existing signature guard
 updates the live region only when progress changes. The stacked SVG fills the
 section width; its text legend carries every state count. Theme offers System,
 Light and Dark; it is applied before first paint and stored in a host-scoped loopback cookie
@@ -170,8 +170,8 @@ is tracked in `docs/smoke.md` and remains unverified until performed.
 The dashboard Office section (#264, phase 1 of 4) draws the same snapshot as a
 static flat office: one desk per peer in a stable slot (claude, codex, kimi, pi,
 local, then others by id; a peer going offline dims its desk and never moves
-another), rooms for the board columns in a fixed order (To Do, Work floor,
-Review, Done shelf as a count only), at most 8 cards per room with "+N more"
+another), rooms for the board columns in a fixed order (To do, Work floor,
+Review, Done as a count only), at most 8 cards per room with "+N more"
 filtering the task list to that state, and at most 12 desks with "+N peers".
 Work-floor cards sit at the owner's desk, marked for rework; a busy peer's task
 bubble names its task only when it has exactly one in progress. Every peer
@@ -1289,7 +1289,9 @@ reporting, and shares results explicitly with `hub_send`. Status, the console an
 the dashboard show `pull-only`, the waiting count and the last inbox read. Messages
 and important markers do not push or interrupt it. There is no hub busy state,
 watchdog, console approval, hub permission mode, context reading, automatic quota
-pause/handoff, shared final answer or session resume. Read quota and approve tools
+pause/handoff, shared final answer or session resume. When important messages are
+waiting, every other hub tool result ends with a line saying how many, so the model
+reads `hub_inbox` before starting long local work (#398). Read quota and approve tools
 in Kimi's own TUI; a person can pause the hub queue by hand. End the native terminal
 session there, not with `ahub stop kimi`.
 
@@ -1619,21 +1621,21 @@ section is what they run.
 
 Upgrade running projects with the target release's own coordinator. It accepts
 a running source on control protocol 9 (0.6.x), 10 (0.7.0 through 0.12.0),
-11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15), 14 (0.12.16), 15 (0.12.17 through 0.12.19) or 16 (0.12.20 through 0.12.26), and only
+11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15), 14 (0.12.16), 15 (0.12.17 through 0.12.19) or 16 (0.12.20 through 0.12.28), and only
 a target on its own protocol, so the target's coordinator fits every supported
 source and carries every recovery fix released up to it. Protocol 8 and older
 (0.5.x and earlier) are refused as `manual-bootstrap-required`. Run from the
 project directory, without replacing the global CLI first:
 
 ```bash
-bunx --package @staix/agent-hub@0.12.26 ahub upgrade --to 0.12.26 --dry-run
-bunx --package @staix/agent-hub@0.12.26 ahub upgrade --to 0.12.26 --yes
+bunx --package @staix/agent-hub@0.12.28 ahub upgrade --to 0.12.28 --dry-run
+bunx --package @staix/agent-hub@0.12.28 ahub upgrade --to 0.12.28 --yes
 ```
 
 | Running now | Coordinator to use |
 | --- | --- |
 | 0.6.x (protocol 9) | the target's, through `bunx` as above |
-| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 through 0.12.19 (protocol 15), 0.12.20 through 0.12.26 (protocol 16) | the target's, through `bunx` as above |
+| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 through 0.12.19 (protocol 15), 0.12.20 through 0.12.28 (protocol 16) | the target's, through `bunx` as above |
 | any supported source, with the installed CLI already at the target | `ahub upgrade` below, which is the same coordinator |
 | 0.5.x or earlier (protocol 8 and older) | not supported: bootstrap by hand with the matching CLI |
 
@@ -1665,14 +1667,14 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.26 --dry-run
+ahub upgrade --to 0.12.28 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.12.26 --yes
+ahub upgrade --to 0.12.28 --yes
 ahub recovery status [<operation-id>]
 ahub recovery resume [<operation-id>]
 ahub recovery abort [<operation-id>]
@@ -2354,6 +2356,13 @@ test files twenty times on macOS, in its own concurrency group; it does not repl
 `scripts/check.sh` stops a suite still running after `AHUB_CHECK_HANG_S` seconds
 (600 by default); hosted macOS CI sets 780 inside the unchanged 15-minute job
 limit (#378).
+The gate holds `<git common dir>/ahub-heavy.lock` across every worktree of a
+repository. A second gate waits up to `AHUB_CHECK_LOCK_WAIT_S` (1800 seconds by
+default; 0 fails immediately) and names the holder. A holder whose PID is gone
+is reaped. This filesystem slot works without a running hub; it covers this
+gate, not arbitrary build commands. PID reuse can retain a stale slot, and two
+waiters reaping the same dead owner can race; broader scheduling remains an
+operator responsibility (#398).
 
 ## Preview initialization and native launch
 
@@ -2453,6 +2462,31 @@ terminal exits, a requested stop (`ahub stop pi`), requested shutdown and
 recovery operations suppress this restart. Crash recovery's #66
 recorded-session/fresh-start choices are unchanged.
 
+### Explicit Pi history replacement
+
+If an offline Pi owner has no verified persisted resume state, inspect the old
+session and any partial work, then select a preserved file explicitly:
+
+```sh
+ahub pi --replace-session --session-file <managed-file>
+```
+
+The file must be inside this project's `.agenthub/state/pi-sessions/` and its
+session header must identify the same project. The selected session keeps its
+existing identity. This is a person-only recovery action; default restart never
+selects another session or infers that missing history was empty. A session id
+alone is insufficient. Add `--headless` to run the selected history in background.
+`--print-command` validates flags without checking the live owner or changing it.
+
+Replacement requires an existing offline owner whose native process is proven
+gone, with settled tools, receipts and approvals, outside a recovery operation.
+An unclaimed pending TUI launch uses the ordinary restart path instead. Before
+revoking the old owner, the hub durably saves private previous/selected session
+metadata in `pi-session-replacements/` beside `pi-sessions/`. Failed validation or
+record storage leaves the old owner intact. All session files, queued work and
+journal records remain. Uncertain effects are never retried by this selection;
+inspect and reconcile them before continuing.
+
 ### Pi/local unanswered approvals
 
 An expired Pi/local request says "approval expired: no person answered". The
@@ -2522,8 +2556,10 @@ An idle Pi with no message/file yet records its live empty-session proof before
 stopping, so its next start resumes that identity. A Pi stopped after its first
 prompt was accepted but before history was persisted is not treated as empty:
 its delivery is held, and another start refuses until resume history is verified.
-Inspect and settle the held delivery before deliberately replacing that unpersisted
-session by restarting the hub; the stop never silently chooses a fresh session.
+Inspect and settle the held delivery before selecting preserved history through
+[explicit Pi history replacement](#explicit-pi-history-replacement). The stop
+never silently chooses a fresh session; replacement requires an offline, settled
+owner and a validated managed session file.
 
 A pull-only Kimi TUI has no controlled restore or resume. While it is attached,
 upgrade/restart planning stops before effects and asks the person to end Kimi in
@@ -2879,20 +2915,36 @@ nor drawing a character changes authority, config files, task state or polling.
 Explicit `ahub pet` and text status use the configured line face; prompt tokens
 remain character-independent. Native glyph width and tmux are unverified.
 
-## Dashboard attention character (#280)
+## Dashboard views and attention (#391, replaces the #280 in-page character)
+
+Top buttons select Board, Office, Stream, Agents, Message, Memory or Settings
+within the same page. The selected view and board column focus use the shared
+host-scoped cookie helper; the URL fragment remains reserved for the session
+ticket. Sections are hidden rather than fetched separately. Projects and
+Benchmarks live under Agents alongside peers, approvals and usage budgets.
+Office mode stays an explicit Off/Flat/Isometric preference inside Office.
+
+Board cards show id/title, priority, owner dot and overdue/check markers.
+Click or Enter opens a native detail dialog with the full stage/dependency,
+release/date, SDLC, detail and GitHub content plus existing Pull/Return/Assign
+controls. Snapshot changes refresh the dialog; project reset or a task leaving
+the snapshot closes it. Expand on a column shows one wide list of full details;
+Back returns to compact cards. State/agent/release filters still apply.
+
+The shared pure needs model now drives the nav attention badge and existing
+action-count tab title. Agents has a live pending-approval count even when
+attention metadata is unavailable. Activation switches to the matching view
+and focuses only the exact visible approval/task id; missing or filtered rows
+receive fixed structural guidance, with no peer or first-row fallback. No
+workflow action is issued and no filter is changed by attention navigation.
+Invalid/legacy attention hides its badge and restores the base title.
+
+The in-page pet, its SVG and character/pixel payload are removed. The standalone
+macOS window owns character presentation. Existing snapshot poll, session,
+request types and CSP hashes remain; no route, request or timer is added.
+Browser screenshots/CSP-console verification are separate manual evidence on
+the implementation PR; VM/HTTP fixtures do not establish human visual results.
 
-The dashboard header draws the configured built-in character independently of
-Office. It uses the same structural needs model as status and the console. The
-accessible button names the character, state and action/watch counts; the tab
-title shows the action count. Activating the button scrolls and focuses the exact
-visible approval/task/peer row, or its related section with fixed id-only guidance
-when the row is filtered or unavailable. It performs no action and changes no
-filters. Legacy snapshots without attention keep the widget hidden.
-
-Only a live approval alternates the two waiting poses once per second through
-CSS. `pet.blink:false` and reduced motion retain a static pose. No new timer,
-request, image protocol or character-file load is added. Project reset clears
-the widget and title. Native/browser visual validation remains unverified.
 With mini/full characters, active console notices remain visible away from the
 character: panel body rows show the bounded wrapped notice, and stream mode
 prints each fresh notice once through the existing local stream. Footer prose
@@ -2943,3 +2995,43 @@ A later issue lookup or profile-preparation failure also returns the IDs confirm
 Release cut audits return exact counts with at most 32 example IDs per category; the dashboard states how many IDs are shown when truncated. Scope grouping and indexed approval dates avoid scanning each task history for every release. Full audit pagination remains a future extension.
 
 Release cards include task states in their refresh key, so completion of an outside prerequisite updates blocked counts even when the release and audit preview are unchanged.
+
+## Standalone macOS pet window (#391)
+
+From a person's terminal, `ahub pet --window` starts one floating, transparent
+JXA panel per project; `ahub pet --window --close` closes it. Other platforms
+print unsupported and retain `ahub pet` / `ahub pet --short`. An agent-marked
+shell may read the terminal pet but cannot start or close the window.
+
+Set `pet.window: true` in `.agenthub/config.json` or `config.local.json` to start
+it with `ahub up`. A window-only local opt-in preserves inherited `pet:false`
+for terminal/status/dashboard presentation; explicit local character options
+retain their existing presentation override behavior. The
+window uses the configured built-in character, full pixel frame and blink
+choice. Its body opens `ahub ui`; the pencil opens an inline console message
+box (Enter sends through `ahub say`, Esc cancels). Drag the body to move it;
+`pet-window-pos.json` remembers the position, with an on-screen fallback if a
+saved display has disappeared. The panel joins all Spaces without a Dock icon.
+The 150x150 panel keeps the status pill and message composer hidden until the
+pointer is over the character. Deep state colors and a dark rim shadow keep the
+pixel silhouette readable on light backgrounds. `pet.palette` selects the base
+color: teal (default, b), blue (a), violet (c) or ochre (d), each with its own
+rim line; the waiting/blocked/review/offline colors stay fixed. While the
+window is key, 1/2/3/4 switch blue/teal/violet/ochre and save the choice.
+From a terminal, `ahub pet --palette <blue|teal|violet|ochre>` writes the
+choice to `pet.palette` in `.agenthub/config.local.json`.
+While working, the pixel art bobs in a 0.7-second stepped CSS loop; reduced-motion preferences keep it still.
+
+A detached Bun host refreshes `pet-view.json` once per second using `readPet`
+and `loadPetConfig`. The file contains only state/counts/character/blink and
+built-in pixels. It uses no dashboard session or HTTP listener. An unavailable
+hub displays Offline for two seconds, then the panel and host exit. Closing
+JXA exits the host too. `pet-window.pid` holds the host's process signature;
+an uncertain owner is retained rather than signalled. A stale owner requires
+an explicit `--close` before restarting; a malformed pidfile requires operator
+inspection. A send failure is unconfirmed: check the stream before retrying.
+
+Native transparency/floating and the bridge were verified in the macOS spike.
+Real keystrokes, dragging and persistence, Spaces, message delivery and body
+click need the manual PR checklist before merge; automated fixtures do not
+establish those native results.

package/docs/quickstart.md

@@ -17,7 +17,7 @@ ahub setup                                # installs the Claude Code channel plu
 Or use the matching GitHub release:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.12.26
+bun add -g github:STAIxBWLB/agent-hub#v0.12.28
 ahub setup
 ```
 

package/docs/security.md

@@ -109,7 +109,7 @@ Please report vulnerabilities privately through GitHub's "Report a vulnerability
 
 - `ahub ui` uses the authenticated console control connection to start an ephemeral HTTP listener on `127.0.0.1`. No UI listener exists before that command. The control and Codex proxy ports continue to refuse every `Origin` header.
 - The daemon issues a cryptographically random, single-use bootstrap ticket valid for 60 seconds. The CLI opens the dashboard with that ticket in the URL fragment, never a query string or the control token. The static page removes the fragment immediately and exchanges it with a same-origin POST. Tickets are consumed once; expired tickets cannot create sessions.
-- The exchange creates a separate random session, valid for one hour without renewal, in an `HttpOnly; SameSite=Strict; Path=/` cookie named for this listener's port. Sessions and tickets live only in memory and die with the daemon. The page itself keeps one more cookie, `agent-hub-theme` (issue #246): script-set, `SameSite=Strict`, kept for a year for the whole `127.0.0.1` host, and read back only as one of `system`, `light` or `dark`. A second script-set cookie, `agent-hub-office` (issue #264), keeps the Office view choice under the same attributes and is read back only as `off`, `flat` or `isometric`. HTTP is loopback-only; the cookie is not a substitute for the origin checks.
+- The exchange creates a separate random session, valid for one hour without renewal, in an `HttpOnly; SameSite=Strict; Path=/` cookie named for this listener's port. Sessions and tickets live only in memory and die with the daemon. The page itself keeps one more cookie, `agent-hub-theme` (issue #246): script-set, `SameSite=Strict`, kept for a year for the whole `127.0.0.1` host, and read back only as one of `system`, `light` or `dark`. A second script-set cookie, `agent-hub-office` (issue #264), keeps the Office view choice under the same attributes and is read back only as `off`, `flat` or `isometric`. The #391 view split adds two more script-set cookies under the same attributes: `agent-hub-view`, read back only as one of the seven view names, and `agent-hub-column-focus`, read back only as one of the five board columns or empty. HTTP is loopback-only; the cookie is not a substitute for the origin checks.
 - Every request must have the exact listener Host. Every data or action request, including the ticket exchange and snapshot polling, must be POST with the exact listener Origin and JSON content type. Foreign and missing origins, missing or expired sessions, oversized bodies and unknown actions are rejected. There is no CORS support. The only unauthenticated GET is the fixed, data-free HTML shell. No files or paths are served dynamically.
 - Responses are non-cacheable, cannot be framed, suppress referrers, and use a content security policy restricting scripts/styles to the shipped inline content and connections to this origin. Browser text is rendered with textContent, never interpreted as HTML.
 - The browser receives a bounded redacted event stream, peer states and queue counts, public task views, budget windows, pending approvals, the settings rows (closed values and ids, the file each comes from) and each startable peer's start plan (issue #269), benchmark run summaries (issue #251): the newest runs in `~/.agenthub/bench/`, whichever project on this machine ran them, by suite name, arm label, state, the task id in progress, counts, tokens and times, never suite text, and the office view's optional fields (issue #264): each peer's open turn (start time, attributed task id, attribution kind), a `checking` flag on tasks whose check is running, and warning `links` of overlapping, conflicting or cohort tasks (task and peer ids only, never paths, symbols or reasons; a PII task never joins a link, and a private or PII-attributed turn exposes no task id). Private envelope bodies and PII task text never cross this endpoint. Local-worker and Pi approval titles can contain PII, so their details remain terminal-only; the dashboard identifies the request and directs the operator to `ahub tail` before allowing it. Budget checkpoint summaries are also omitted.
@@ -226,11 +226,14 @@ owner/reviewer ids, approval ids and numeric times, peer delivery states and
 budget pause times. It is assembled from the same allowlisted input as status;
 task text, plans, approval prose, error text and paths are excluded. This input
 is supplied only inside console-authorized dashboard snapshots, never ordinary
-status replies or status.json. The pet creates trusted inline SVG pixel nodes
-from built-in literal frames with existing theme colours, without HTML insertion,
-inline handlers, style attributes or external assets. Existing CSP hashing,
-headers, origin and session authorization remain in force. Clicking scrolls and
-focuses only; it cannot grant permissions or invoke a mutation.
+status replies or status.json. The #391 dashboard projects this input into nav
+and tab-title counts; the in-page pet and its character/pixel injection are gone.
+Attention navigation switches a local view and focuses an exact visible row id,
+with structural guidance when missing. It cannot grant permissions or invoke a
+mutation. Compact-card detail/dialog controls retain the existing authenticated
+workflow actions and project/instance fencing. Existing CSP hashing, headers,
+origin and session authorization remain in force; data uses text/DOM nodes,
+without HTML insertion, inline handlers or external assets.
 
 
 ## Hub-owned structured memory (#258)
@@ -251,3 +254,28 @@ refused; unknown visibility proceeds with a warning for the configured remote.
 Short-term segments, machine identity and the derived index are excluded from
 sync. Suggested graph edges are off by default and are not evidence until a
 person confirms them. Operational details and limits: [hub memory](memory.md).
+
+## Standalone pet window (#391)
+
+The macOS window reads local files only. Its detached host reuses `readPet`,
+including signed-daemon liveness and recovery-lock handling, and publishes an
+atomic counts-only `pet-view.json` (state, act/watch, known character, blink,
+palette from the closed list, built-in pixel frame). It excludes item ids,
+task titles/text, refs, paths,
+notices and approval prose. Missing or unconfirmed status produces only
+`{offline:true}`. Process and position files are separate from this view.
+
+The local WKWebView has a deny-by-default CSP, with only its shipped inline
+script/style allowed and network connections forbidden. Text never becomes
+HTML or executable source. The retained JXA bridge accepts fixed drag/send/
+palette/open/close operations; `NSTask` invokes the host-supplied Bun/CLI/project argv
+and appends `say`, `--` and a single message argument, or `pet`, `--palette`
+and one closed palette name. It does not evaluate a
+shell string. Message text is never logged by the window/host; command stdout
+and stderr go to the null device. `ahub say` keeps its existing console-message
+authority and recording behavior, and `ahub ui` opens its existing session.
+The CLI restricts `pet --window` (including close) to console identity, while
+plain terminal pet reads and `pet --palette` remain available to agent shells;
+the palette write merges only the closed name into `.agenthub/config.local.json`,
+validated and replaced by temp file and rename. Signed pidfiles
+fence instance ownership and close; unknown owners are never signalled.

package/docs/specs/2026-09-19-agent-hub-design.md

@@ -710,7 +710,11 @@ fragment ticket for an HttpOnly, SameSite=Strict browser session. The control li
 retains its blanket Origin refusal. The browser receives no control token.
 
 One static HTML file, without a build step or runtime dependency, polls public
-snapshots once per second. The latest 200 redacted bus events are retained only
+snapshots once per second. #391 Task A keeps this `/` surface and poll while
+splitting its sections into Board/Office/Stream/Agents/Message/Memory/Settings
+views with a cookie-backed selection. Compact task cards open a native dialog;
+one `taskDetail` function renders both the dialog and expanded-column cards.
+Filters, exact-id attention navigation and existing workflow controls remain. The latest 200 redacted bus events are retained only
 once the listener starts. The API exposes only permission answers, peer
 pause/resume, console messages, task proposal and assignment. All task changes
 use `Tasks`; budget pauses keep the terminal's override requirement.
@@ -731,7 +735,9 @@ project registry and adds explicit project selection, authenticated instance
 ownership and a separate optional dashboard manager. Runtime data and routing
 remain per project. Native memory aliases remain compatible and shared.
 Control protocol 7 adds project/instance identity and console-only dashboard
-snapshot/action forwarding. Existing project-local UI security rules still apply.
+snapshot/action forwarding. Existing project-local UI security rules still apply. #391 Task A changes only client view selection;
+project/instance fencing still invalidates open task details and stale controls.
+No additional project route, request or timer is introduced.
 
 
 ## Amendment: externally managed Ollama MLX (issue #51)
@@ -2678,21 +2684,21 @@ C/dumb/linux/unknown locale surfaces use ASCII even when blocks were requested.
 Body foreground is uncoloured; only the Gyul leaf uses an existing accent tone.
 Native terminal/font/tmux proof remains a separate verification leg.
 
-## Shared dashboard attention (#280, phase 4)
+## Shared dashboard attention (#280, replaced by #391 Task A)
 
-The existing authenticated UI snapshot receives an optional allowlisted attention
-input and enabled/character/blink presentation fields. Status wire/file callers
-retain their phase3 summary/items projection and never receive this input. The
-page invokes the same injected needs function on this body-free input, renders
-the selected built-in full block frame as SVG pixels and exposes state/counts
-through an accessible button. Its click only reaches an exact visible list row
-or the relevant heading with fixed structural guidance; no action request occurs.
+The authenticated snapshot retains optional body-free needs input. The same
+injected pure needs function drives global nav action/watch counts and the
+existing tab-title action count; status/file readers retain their summary/items
+projection. The Agents button separately shows live pending approvals. The
+in-page character, SVG, character frames and pixel injection are removed; the
+standalone #391 Task B window owns that presentation.
 
-DOM writes and title counts follow the derived signature, not every poll. A
-waiting pulse uses CSS transform/opacity only, with a static reduced-motion and
-blink-off escape. There is no extra timer, request, route or authority; legacy
-or invalid snapshots make attention unavailable. Project changes clear stale
-attention and restore the title. The existing CSP/header policy is unchanged.
+Attention activation switches views and selects only the exact visible
+approval/task id. Default/delivery/budget items without a visible exact target
+show their related heading and fixed id-only guidance, never a peer or first-row
+fallback. Filters and workflow state are unchanged. Signature guards suppress
+unchanged DOM writes, invalid legacy input stays unavailable, and project
+changes reset attention and close stale dialogs. CSP/header policy remains.
 
 ## Amendment: hub memory, tiers and graph (#258, phase 1)
 
@@ -2710,20 +2716,12 @@ and rebuilds; the dashboard's Memory section is read-only inside the existing CS
 long-term tasks with leases (decision 9's amendment), claude-mem import and model-suggested edges follow in later phases.
 
 
-## Dashboard attention projection (#280, phase 4 in progress)
+## Dashboard attention projection (#280, superseded by #391)
 
-The existing dashboard snapshot supplies optional allowlisted needs input and
-known presentation choices; normal status/file payloads do not gain that input.
-The header independently projects the shared pure needs function into literal
-built-in SVG pixels and an accessible state/count label. Unchanged state and
-choices do not rewrite pet DOM. Clicks navigate only to exact visible rows or
-related headings, never issue actions or alter filters. Missing/invalid legacy
-input hides the widget. Project resets clear retained navigation and title.
+#391 Task A replaces the in-page pixel widget with nav/title counts as defined
+in Shared dashboard attention above. Native character presentation is the
+standalone Task B window; browser attention uses no character data or frames.
 
-The two approved waiting frames alternate in CSS once per second only while
-a live approval exists. Reduced motion and blink-off remain static. Every other
-state stays still. No timer/request or new asset dependency is introduced;
-existing header policy and computed CSP hashes apply.
 ## Amendment: hub memory between machines and long-term tasks (#258, phase 2)
 
 Decision 9 is amended for memory only: the memory directory is a git repository that tracks `log/*.jsonl` and syncs
@@ -2830,3 +2828,89 @@ session instead of assuming that an older extension provides the fence.
 Prompt lineage lasts until logical `agent_settled`: native retry, compaction or
 continuation starts inside that run retain the same command id. A later personal
 run has no hub command lineage.
+
+## Amendment: standalone attention window (#391 Task B, supersedes #280 dashboard pet)
+
+The #280 phase-4 dashboard pet is replaced by an optional standalone macOS JXA
+window. Task B adds the window first; #391 Task A removes the existing in-page
+character and retains shared attention counts/navigation. Terminal characters
+and read-only `ahub pet` behavior remain.
+
+`ahub pet --window` / `--window --close` are console-identity commands;
+`pet.window:true` opts into startup from `ahub up`. Non-macOS reports unsupported.
+One detached Bun host per project holds a signed pidfile in stateDir, reads
+`readPet` and `loadPetConfig` every second and atomically writes state, act/watch,
+character, blink and the full built-in `petPixels(CHARACTERS[...])` frame. No
+item ids/text/titles or external image assets are included. Unavailable status
+writes exactly `{offline:true}`; JXA displays Offline for two seconds, exits,
+and the host follows. A closed/crashed JXA also ends the host. A stale owner
+requires explicit close; an unconfirmed owner is retained.
+
+`osascript -l JavaScript` creates an accessory, borderless nonactivating
+NSPanel subclass that can become key, uses NSFloatingWindowLevel and
+canJoinAllSpaces | stationary, and embeds a transparent local WKWebView. Its
+one-second NSTimer loads the atomic view and calls `update(json)` with an
+explicit no-op completion function (a JS null completion block crashes on the
+verified macOS). The fixed bridge moves/saves position, makes the pencil's
+inline text box key, sends a console message through NSTask argv to `ahub say`,
+opens the dashboard through `ahub ui`, or closes. Enter sends; Esc cancels.
+No shell evaluation, new dependency, compile step, HTTP listener or network
+request is added. Message contents are not logged by this surface.
+Working animates only the pixel SVG through a 0.7-second stepped CSS bob, disabled by prefers-reduced-motion; no frame, timer or view-file change is added.
+
+The repaired Mac spike verified a transparent floating key panel and both
+bridge directions. Real input/drag/Spaces and end-to-end stream delivery remain
+manual acceptance evidence on the implementation PR, not inferred from the
+spike's process metrics or automated fixtures.
+
+## Amendment: dashboard views and task detail (#391 Task A)
+
+The existing page has one nav button per view, with `aria-current`; sections
+carry `data-view` and selection toggles only `hidden`. A shared cookie helper
+stores theme, Office mode, selected view and optional board column focus.
+The one-time ticket keeps exclusive use of the URL fragment. Projects and
+Benchmarks join peers, approvals and budgets under Agents.
+
+Compact task cards retain drag/drop, id/title, priority, owner dot and
+check/overdue markers. Click/Enter opens a native `dialog` via `showModal()`.
+`taskDetail` supplies full current public content and existing controls to that
+dialog and to a focused column's one-wide-list cards. Each snapshot updates the
+open detail; disappearance/project reset closes it. Back restores compact mode,
+and state/peer/release filters remain active in focus. Attention targets exact
+visible row ids with heading guidance when absent. No new route, API request,
+timer, source text/ref/history projection or external asset is introduced.
+
+
+## Explicit offline Pi history selection (#403)
+
+A person may run `ahub pi --replace-session --session-file <managed-file>` only
+for an existing offline, settled Pi owner with a proven-gone native process.
+Pending tools, receipts, approvals and recovery hold replacement. The console
+control path alone authorizes this operation; peer and conductor tools cannot
+supply that authority. Validate the selected managed path and project/session
+header before any prior owner teardown, then durably write private previous
+and selected metadata. Retain all session files, queues and journal records.
+Start the selected persisted identity through the existing permission policy
+and verified teardown. There is no automatic fallback, implicit empty-session
+proof or effect retry; ordinary restart and captureResume remain strict.
+
+## Amendment: pull-only latency (#398)
+
+A pull-only peer learns of important work only when its model calls a hub tool,
+and repo-heavy work was coordinated over chat it read too late.
+
+- When an `important` envelope is queued for a pull-only peer, the bus calls the
+  advisory `onImportantQueued` hook and the daemon sends that peer's control
+  socket `{t:"queued", queued, important}`, as it does when a pull-only session
+  attaches with important work already queued. It is not a delivery: nothing is
+  dequeued, steered, journaled or settled, and the queue still waits for
+  `hub_inbox`. The `inbox` reply adds `waitingImportant`.
+- The plugin caches the counts and appends one line naming the important count
+  to every hub tool result except `hub_inbox` until a read reports none. An older
+  plugin ignores the unknown push; an older hub never sends it.
+- `scripts/check.sh` takes a heavy-job slot, a directory in the git common dir
+  shared by every worktree, before any step. A second gate waits up to
+  `AHUB_CHECK_LOCK_WAIT_S` (1800 s; 0 fails at once) and names the holder; a
+  holder whose pid is gone is reaped. The slot works with no hub running. It is
+  not bus-visible; moving it into the hub is the upgrade if pid reuse or reap
+  races bite.