@staix/agent-hub 0.12.20 → 0.12.22

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

@@ -89,7 +89,8 @@ Facts below are tagged **verified** (measured on 2026-09-19 on the owner's Mac)
 7. Quota relay hands open tasks to the `local` peer first, then waits for the window
    reset for judgment-heavy classes. Task-level escalation on verification failure.
 8. Safety defaults: cross-peer text is framed as untrusted; permission prompts stay on
-   unless `--unattended`; ports bind loopback only; Kimi ACP permission requests are
+   unless `--unattended` or an operator-selected permission mode (issues #240,
+   #242); ports bind loopback only; Kimi ACP permission requests are
    relayed to the hub console. Loopback is not enough on its own (any web page can open a
    WebSocket to 127.0.0.1), so the control WS requires a per-run token and both hub
    servers refuse requests that carry an `Origin` header (amended in M1).
@@ -97,8 +98,9 @@ Facts below are tagged **verified** (measured on 2026-09-19 on the owner's Mac)
 10. Shared memory reuses claude-mem as the single store; the hub never runs its own
     memory database. Native capture stays where it exists (Claude hooks, Codex plugin,
     Kimi transcript bridge); the hub captures only the local worker and adds
-    cross-platform recall, task-scoped briefs and explicit shared notes. The bus still
-    passes messages, never transcripts.
+    cross-platform recall, task-scoped briefs and explicit shared notes. Hub tool calls
+    are not captured; Tasks alone decides what screened tool text reaches memory.
+    The bus still passes messages, never transcripts.
 
 ## Design
 
@@ -279,9 +281,10 @@ peer. Peer ids claimed over the control WS must not be `user` or a hub-managed a
   injection is dropped for the same reason as `dynamicTools`.
 - PII (amended in M4): a task matching `signals.pii_patterns` is owned by `local` or by
   nobody; its envelopes are `private` (console tail and `hub.log` print a stub), lists show
-  `[pii]` to everyone but `local`, `ahub task show` is the one place the console reads it; the
-  reviewer is the console user; `local` answers such a turn to the console only, keeps it out
-  of its history, refuses it when the only gateway is off campus (Cloudflare Access), and
+  `[pii]` to everyone but `local` inside a PII turn; `ahub task show` is the one place
+  the console reads it. The reviewer is the console user; `local` answers such a turn
+  to the console only, keeps it out of its history, refuses it when the only gateway
+  is off campus (Cloudflare Access), and
   nothing reaches claude-mem (no brief, no note, no capture), because claude-mem's observer is
   a cloud model (verified: `/api/health` reports `ai.provider: claude`).
 
@@ -486,7 +489,8 @@ inside a peer.
 ### Safety
 
 - Untrusted framing on all cross-peer text; standing instruction once per session.
-- `ahub claude` and `ahub codex` keep normal permission prompts. `--unattended` opts into
+- `ahub claude` and `ahub codex` keep native permission defaults unless the person
+  selects a permission mode (issues #240, #242). `--unattended` opts into
   `--dangerously-skip-permissions` (Claude) and `--dangerously-bypass-approvals-and-sandbox`
   (Codex 0.154.0 documents this flag, not `--yolo`) and prints a warning.
 - Kimi and local tools: cwd-scoped, secrets denylist (a secrets directory, `.env*`, keys).
@@ -496,7 +500,7 @@ inside a peer.
 ### Configuration and state
 
 - `.agenthub/config.json` (roles, ports, filter tiers, watchdog), `.agenthub/routing.toml`.
-- `.agenthub/state/` gitignored: `hub.pid`, `status.json`, `control-token` (0600, per run),
+- `.agenthub/state/` gitignored: `status.json` (with the daemon's pid and process signature, #226; daemons up to 0.12.20 also wrote `hub.pid`), `control-token` (0600, per run),
   `hub.db` (tasks, messages, budget; from M4), `hub.log`, `switchyard.toml`, `checkpoint.md`.
 - Env: `AGENTHUB_STATE_DIR`, `AGENTHUB_OMNIROUTE_URL`, `OMNIROUTE_API_KEY`,
   `AGENTHUB_SWITCHYARD_BIN`, `AGENTHUB_UNATTENDED`.
@@ -763,7 +767,8 @@ session modes (`default`, `plan`, `auto`, `yolo`) but nothing per server or tool
   `hub_send` or a task tool, are answered with their `allow_once` option by the
   hub, without a console prompt, and logged by tool name only. This matches the
   `approval_mode = "approve"` Codex already gets for the same tools. Every other
-  request keeps the console path; `allow_always` is never chosen automatically.
+  request keeps the console path unless the person opts into the permission modes
+  below (issues #240, #242); `allow_always` is never chosen automatically.
 - For the other tools, the console payload falls back to the streamed argument
   text once it is a complete JSON object. A partial stream stays unresolved and
   keeps `allow_always` withheld.
@@ -776,6 +781,84 @@ session modes (`default`, `plan`, `auto`, `yolo`) but nothing per server or tool
   configured server of the same name, so only the hub's `agent-hub` server can
   produce the approved names.
 
+## Amendment: operator permission modes (issues #240, #242)
+
+- Modes: ask leaves native decisions unchanged; ask-when-needed uses native
+  Kimi/Codex policies or scoped Claude/Pi/local grants; never-ask suppresses
+  prompts within each peer's existing execution boundaries.
+- Runtime CLI permission changes are refused from ordinary agent shells.
+  Never-ask needs --yes; console mode selection needs a separate y. These
+  policy/role checks do not contain a hostile same-user shell: Kimi can clear
+  markers, use --yes or read the control token and impersonate the console.
+  The security and operations guides name that boundary explicitly.
+- permission_modes defaults merge per peer across config files. Automatic
+  effects stop at ask-when-needed. Never-ask from an applied untracked config remains ask until
+  a person's source-labelled console y at hub start; no boot --yes applies it.
+  Git-tracked mode defaults are ignored and never offered for confirmation.
+  Every non-ask start logs mode and source (config file or runtime choice). Successful
+  runtime changes clear pending config confirmations; startup choices are reconciled
+  under the peer fence before a new adapter is exposed to bus delivery. Runtime changes and
+  confirmations remain daemon-local and expire on stop.
+- Newly added native peers replay their non-offline state to drain queued work,
+  publish state telemetry and persist sessions. Offline/absent ask clears only
+  the hub choice. Unattended metadata is saved after successful startup, and
+  concurrent joined starts with different flags are refused. Refused default
+  confirmation remains handled until state changes; Esc defers without declining.
+- Kimi mapping requires the actual Kimi Code CLI identity: yolo for
+  ask-when-needed, auto for never-ask, default for ask. Another ACP agent starts fresh or resumed as unmanaged: its reported mode is
+  untouched, and runtime changes are refused until its table exists. Set-mode replies precede prompts;
+  missing ids/refused startup changes fail. A timeout is unknown/offline and
+  the owned process group stops, so a late reply cannot restore a live peer.
+  Loaded non-default Kimi modes are reset for project ask.
+- Codex overlays on-request/never on every outgoing turn/start without changing
+  sandbox fields. Ask restores a known native policy once after an accepted
+  turn; rejected restoration remains pending. Restoration debt and captured
+  policies are per thread and survive proxy detach and thread/start or thread/resume.
+  A known restoring turn retains its baseline even if the TUI echoes the resumed
+  response's sticky override, in any hub permission mode. After restoration is
+  admitted, a later repeated TUI policy is indistinguishable from an explicit
+  native choice and passes through; only the restoring turn is protected.
+  Unknown native baseline refuses restoration while attached, with instructions
+  to close the TUI and run `ahub permission codex ask`; detached ask succeeds and
+  returns a CLI-visible note about the old thread's unchanged native policy. Actual native unattended flags, not broker-wide flags, govern
+  the refusal to change a bypassed session.
+- Claude ask-when-needed allows only Read/Edit/Write/MultiEdit/NotebookEdit/LS
+  and bounded Glob/Grep targets resolved with realPath beneath project root,
+  outside .agenthub/.git/.claude/.codex/.qwen/.kimi/.pi/.mcp.json. Missing/nonresolving or escaping targets,
+  protected case aliases, symlinks and uncertain wildcard/filter targets yield
+  no decision. Never-ask answers allow; ask and transport errors decide nothing.
+  Merged/generated settings are 0600 state files passed by path, never inline
+  in argv. Preview writes no settings file. The owning launcher removes its settings file
+  after native exit; earlier active or unknown launchers retain theirs. Verified
+  dead wrapper and native identities permit crash fallback cleanup. Direct binary
+  launches publish the native child PID/signature while running, bound to the exact
+  launch record; crash cleanup additionally requires its PID absent from a verified
+  process table. Script/interpreter native ownership remains unknown. Without
+  separate native identity proof, prior files remain for manual inspection. Every
+  launch atomically publishes its managed hook/session record without depending
+  on the native-proof lock. Exact-binding native proof is stored separately, so
+  an old callback cannot replace a later launch record. The populated signed
+  native-proof lock waits up to 250 ms for a live owner; an unknown/busy lock
+  disables only native identity/crash cleanup with exact-path guidance. Managed
+  hooks keep working for the current launch.
+- Permission-only Claude PreToolUse never drives busy state. Only the former
+  observation purposes retain native turn bookkeeping. Hook identity/purpose
+  are launch/session bound; unverified hook status reads unverified.
+- Pi/local read never asks. Ask-when-needed grants write/edit inside the project, outside the shared native
+  configuration segments (.claude/.codex/.qwen/.kimi/.pi/.mcp.json, compared folded and by the path within the
+  project) and never through a hard link; bash and mutating
+  git retain console approval. Never-ask grants once, retaining sandbox and
+  path guards; no mode gives allow-always. ACP tools have no hub sandbox and
+  the never-ask confirmation names that difference.
+- Console-role permission and permission_default requests are additive;
+  ordinary tools/conductor/messages cannot change or confirm modes. Status
+  includes non-ask/unverified/unknown mode state and pending defaults; facts
+  replies include permission and authenticated projectRoot. Unknown requests
+  are answered, so PROTOCOL remains unchanged. permission_mode events retain
+  schema 1 and include only peer/from/to, never tool arguments.
+- Live benign Kimi/Claude results and unverified Codex/Pi limits are recorded
+  in docs/smoke.md. No extra account prompts accompany these review corrections.
+
 ## Amendment: approval notifications and timeout (issue #5)
 
 - A waiting permission request raises one macOS notification (`osascript`) with
@@ -994,7 +1077,11 @@ session modes (`default`, `plan`, `auto`, `yolo`) but nothing per server or tool
   awaited an approval. An approval is saved before its dependents are assigned,
   so the daemon's 60 s release timer sweeps for ownerless tasks whose last event
   is `blocked` or `ready` and that wait for nothing: each is offered once per hub
-  run, once an attached peer can take it, outside recovery operations.
+  run, once an attached peer can take it, outside recovery operations. An offer
+  is used up only by an assignment, after an approval and on the timer alike;
+  failed dependent reads, ready writes or assignments do not escape a saved
+  approval. Their notices are best effort because notification can read the
+  same unavailable board. An ownerless task stays eligible once a peer can take it.
 - A recovery commit also waits for task operations in flight and for completion
   checks queued or running: both can write the board after its integrity digest
   (a check the commit's stop kills records `check interrupted`).
@@ -1360,14 +1447,59 @@ approval. Deny is direct. Pending requests include expiry and are withdrawn by
 Panels expose Peers, Approvals, Tasks, Queue and Events with bounded polling and
 Unicode cell widths, fall back below 80x24, and restore terminal state on exit.
 
+Whole-board progress (#246) uses one pure `taskProgress` function shared by the
+console and hashed dashboard script. It reads only public id/state/deps fields;
+PII stubs count like other tasks. Waiting partitions proposed tasks whose public
+dependencies are not approved, including unknown dependencies. Approved/all gives
+the done fraction (zero on an empty board). Four stages are proposed, in progress,
+in review and approved; changes requested returns to stage two and is marked.
+The console Tasks panel has a 20-cell ASCII summary bar and fixed four-cell row
+meters, preserving width and color-off geometry. Cells and percentage round down;
+count labels use importance order changes requested, review, waiting, in progress,
+proposed, then unknown when nonzero, and drop only from the end. The stream count is in the fixed footer,
+from existing all-state status counts; it makes no board fetch and retains a
+row-one scroll region for terminal scrollback. Loading/failed reads never imply
+confirmed empty progress. Dashboard filters affect rows only, not totals. Its
+full-width stacked SVG and stages have text equivalents; the existing signature
+guard prevents unchanged snapshots from mutating the progress live region.
+System/Light/Dark choice is applied as `data-theme` before first paint, persists
+in a one-year host-scoped `SameSite=Strict` cookie through guarded access and
+follows OS CSS preference on System. Cookie port independence shares the choice
+between hub starts and projects. The shared model is injected before the page's
+own inline script/style CSP hashes, with no new control message or CLI JSON change.
+UI public rows expose optional public-view deps for waiting. This is additive
+metadata enrichment of the existing ui_snapshot payload, not a changed control
+message envelope/operation, so it does not bump PROTOCOL. Unknown task states
+count in an explicit unknown bucket with stage zero; no NaN or prototype-key
+updates are permitted. Approval fraction is derived from counts/total at display
+time, avoiding a redundant floating-ratio field.
+
 Console semantic colors (issue #201) use spans with a fixed terminal-native
 palette: cyan information, bold cyan active/selected labels, green availability
 and success, yellow attention/waiting, red failure/intervention, and restrained
 bright-black metadata. Offline peers, ordinary titles, action details and body
 lines use the default foreground. Existing labels, selection markers and
-confirmation prompts remain sufficient without color. Stream headers use event
-structure for their tone; body text is never parsed for meaning or passed
-through as terminal styling. Denial requests and observed expiry/cancellation
+confirmation prompts remain sufficient without color. Console stream headers
+color meaningful tokens only (#239; dated issue Decisions): Claude bright blue
+(94), Codex bright cyan (96), all other peers default; `task` magenta (35, never
+bold), numbers bold default foreground (1), task references magenta underlined
+(4;35), and other issue references underlined default foreground (4). No token
+SGR equals a state or peer SGR. Green/yellow/red remain states/approvals/failures,
+cyan remains navigation. Case-insensitive `task #N`, `Task #N`, `[task #N]` and
+`[review #N]` identify task references; unbracketed prose `review #N` remains an
+issue reference. Ordinary words keep default foreground;
+there is no hashing or user theme.
+Only hub-written peer slots, state words and structural markers receive their
+semantic tones; title words and markers cannot choose them. Numeric tokens have
+whole-token boundaries, so UUIDs and ISO identifiers stay plain. Legacy notices
+lack typed reference ranges: the task/review prefix heuristic is bounded by a
+`ponytail:` comment; other `#N` tokens use the issue tone until structured notice
+spans classify assign/which references. Header text crosses `terminalText` before tokenization. Wrapped headers normalize
+tabs to spaces first; plain headers retain their original tabs in both color modes. Wrapped spans retain the source classification. After a projection
+miss on the first physical header, only structural tones remain. A missed
+continuation and all later continuations are fully plain. Projection advances
+a span index through the source once, keeping long permission titles bounded. Bodies and every
+command-output line stay plain. Denial requests and observed expiry/cancellation
 are red; an answered remote closure lacks option-kind metadata and is not
 guessed to be a denial.
 
@@ -1654,7 +1786,10 @@ push `accepted` and show none of them.
   to the newest end of the cache) for `reply_to` like a push, and a read clears
   the peer's failure streak as a completed push does. If that journal write fails, only this peer's queue
   and preface are put back (every pause stays) and the bus stops with
-  `delivery journal unavailable`. A pull is not a native turn and is not
+  `delivery journal unavailable`. A refused or failed `resolveDelivery` likewise
+  puts back only that peer's queue and preface and keeps every pause. Queue
+  contents change in place, preserving arrays held by a suspended drain; only
+  the constructor and recovery restore reload a bus snapshot. A pull is not a native turn and is not
   counted as supervision. The row is completed at hand-out, before anything
   shows the model saw it: a reply lost on the way, a tool call cancelled with
   Esc or a plugin that dies loses the batch (a `ponytail:` ceiling in
@@ -1789,9 +1924,9 @@ acts on the stopped state directory.
   Checked, then renamed by path: a symlink swapped in between still wins
   (marked `ponytail:`; `renameat` on a held descriptor would close it).
 - Between stop and act: after `stopProject` the CLI takes the project's
-  registry claim (`Registry.claim` with its own pid), the claim a daemon must
+  registry claim (`Registry.claim` with its own pid and process signature), the claim a daemon must
   hold to run, and checks that no manifest names a daemon whose pid is alive
-  or uncertain (`processAlive`, the rule `inspectProject` uses); either failing
+  or uncertain (`processLiveness`, the rule `inspectProject` uses, #226); either failing
   means a hub started in between and nothing is reset. A reset's claim carries
   the instance prefix `reset-`, so losing the claim to a concurrent reset says
   so. A crashed daemon's manifest (`status.json`, `control-token`, `hub.pid`
@@ -1800,7 +1935,7 @@ acts on the stopped state directory.
   removes it and `--all` archives it. With the claim held, the CLI checks the
   machine's recovery lock again, so an upgrade or recovery that took it in
   between does not run beside the reset. The claim is released when the reset
-  ends; a reset that dies leaves a dead pid, which the next claim takes over.
+  ends; a reset that dies leaves a dead or reused pid with its signature, which the next claim takes over.
 - Failures: the plan is read only for the dry run, so `--all --yes` archives a
   state directory it cannot read as it is (its dry run says what it could not
   read). A failure after the stop says how far it got. A runtime reset that
@@ -1849,9 +1984,8 @@ acts on the stopped state directory.
   text right after the pattern check and before triage. "Held as private" is met
   by holding the task back entirely: until the verdict it is not on the board, so
   no envelope, notice, triage call, brief or note of the hub's can read it. The
-  local worker's claude-mem capture of its own tool calls is outside this: in an
-  ordinary turn it sends a proposal's arguments whatever the verdict (an existing
-  gap for every hub tool, not closed here). Writing it as
+  local worker never captures hub tool calls (#230), so a proposal's arguments
+  cannot bypass the verdict through capture. Writing it as
   a PII task first was rejected: a PII task opening lifts every silent turn-free
   cohort for good and switches facts off (#107, #108), so every proposal would do
   that. The proposal's tool call waits for the verdict, as it already waits for
@@ -1930,3 +2064,76 @@ acts on the stopped state directory.
   before any measurement: the model itself labels at least 90% of the positives
   `pii` (an unknown verdict counts as a miss). The report goes to
   `docs/verification/`; the script exits 1 under the bound.
+
+## Amendment: research records (issue #247)
+
+- Opt-in per project (`research.enabled`, off by default). When a task is approved, the daemon builds its record from
+  the project's `events.jsonl` with the same function `ahub research backfill` uses (`taskRecords` in
+  `src/hub/research.ts`), so live and backfilled records agree, and appends it to the machine-wide store
+  `~/.agenthub/research/<sha256(project id)[0:16]>.jsonl`. Records hold ids, states, counts, tokens and times only,
+  because the events do; schema and fields: [research](../research.md).
+- The board has no terminal state but `approved`, and it is final, so each approved task gets one record; a person's
+  later verdict (`ahub task label`, including `abandoned`) is a separate label record bound to the task's proposal
+  time. A task is keyed by project, id and proposal time, because `ahub reset --all` restarts the ids and the store
+  keeps the older records. Measures (success, first pass, rework, check failures over checks run, tokens and wall time
+  per task) are derived when reported, never stored.
+- The record counts everything attributed to the task, the turn that approved it included: that turn ends after the
+  approval and its usage arrives later, so the writer waits until no open turn is attributed to the task (polled every
+  10 s, at most 30 minutes; a stopping hub writes once its peers have stopped). The first record written for a
+  task is final; a label binds to the current board's task, else to the store's only record with that id, or with
+  `--created` to a named one from before a reset. Task events carry the board's move `reason` (a closed
+  list) so reassignments are counted by reason.
+- Recording never blocks or fails the task flow: the writer runs after the board event, and a failure is one
+  hub.log line per run. ponytail: it reads the whole events file for each record; an incremental per-task index
+  if that file grows large.
+- Agents may read the measures and export; backfill and labels are a person's (identity gate).
+
+## Amendment: proven Pi tool refusals and idle exit recovery (issues #254, #255)
+
+- A trusted guard uses `PreEffectToolRefusal` only when that operation has performed no task or board effect; PII screening and its telemetry record may precede the refusal. Pi receives the same `error: <message>` refusal as the control client, and its session/call receipt is `done`. Initial task ownership/dependency/state checks and conductor entry peer/mode/assignment/escalation validation opt into the type; shared helpers default to ordinary errors, and conductor checks after an awaited release validation stay ordinary. Generic errors, board readback failures after a write, and receipt settlement write failures remain uncertain/pending and are never repeated. A legacy pending row has no pre-effect proof in its stored fingerprint/state/result, so startup preserves it; neither present board state nor a matching error message establishes historical refusal.
+- Each Pi owner reports one exit with cause, exit code or signal, whether startup completed, whether a turn/tool was active, whether teardown was expected, and the last validated tool name only. TUI shutdown/owner-loss and verified stop teardown lack observed OS status and record unknown. A successfully stopped claimed TUI owner reports once; a never-owned launch reports no invented exit. Replacement teardown says the owner stopped for a new Pi owner even if replacement startup is refused. Internal teardown notices direct inspection and `ahub pi`, without claiming a person requested them. Replacement, failed-start and active-turn guidance takes precedence over the automatic-start-disabled notice. Console notices name the next action or automatic-start state; headless code 0 is still an exit and settles active deliveries as uncertain.
+- With `pi.auto_start`, an unexpected idle headless exit attempts its verified persisted session once in a 60 s window. The daemon owns the attempt/window across adapter replacements, blocks throughout an in-flight attempt, and rearms the 60 s window when that attempt settles. It checks current-owner identity, completed startup, turn/tool inactivity, start serialization, shutdown and recovery before and after awaited receipt drain/session capture. Missing or invalid persisted state leaves Pi offline with `ahub pi` guidance, with no fresh-session fallback. A second exit inside the window stays offline. Requested stops, stale owners, startup failures, active turns/tools and native terminal exits never trigger this automatic path; crash recovery's existing #66 behavior remains separate.
+## Amendment: benchmarks (issue #251)
+
+- `ahub bench` runs a person's suite file (tasks with a starting commit, an optional setup and a verify command)
+  against the peers attached to a hub, in a project opted in with `bench.enabled`, because every attempt resets the work
+  tree (`git checkout --force --detach <commit>` with HEAD checked against the pin, `git clean -ffdx -e /.agenthub`, then a
+  clean-tree check). Before
+  anything changes the runner requires the project to be the root of its repository, nothing tracked under `.agenthub/`
+  (in any letter case) in the tree or in any suite ref, every ref to be a commit, which it pins for the run, and a
+  clean tree. The runner is a console client: it proposes each
+  task as the console does and polls the board, so the task flow is unchanged and no new control request exists.
+- `setup` and `verify` run in their own process group, bounded; the group is stopped at the bound, on an interrupt and
+  when the command exits. An approved attempt's measures come from #247's `taskRecords` for the task proposed last with
+  that id, read once the turns started since its proposal have ended (waiting only while their peers are busy or
+  paused, at most 10 minutes, outside the attempt's duration); a timeout, an error, an interrupted wait, a wait that
+  runs out with the turn still open, or a hub status that cannot be read while it is open leaves none, never partial
+  ones. The fingerprint lists only the peers attached at the start.
+- Results go to `~/.agenthub/bench/<run>.jsonl` (ids, outcomes, exit codes, counts, times; never suite text or command
+  output). A run's state comes from its end record or its runner's liveness (`processLiveness`). Comparisons are
+  derived when asked: an arm is every run of it that is over (a stopped run included), runs of different suites or
+  suite versions are not mixed unless asked, and each difference has a seeded 95% bootstrap interval, inconclusive
+  below five attempts counted for that measure per arm (errors are not counted for pass rate or wall time).
+- A task that times out stops the run, because an agent may still work in the tree the next attempt would reset.
+  ponytail: a board state to withdraw an open task would let the run continue. The fingerprint holds what the hub's
+  status reports (a requested model for Pi, permission modes once #242 lands); ponytail: read each peer's launch
+  settings for the rest.
+- The dashboard snapshot carries run summaries and per-arm measures only. `bench run` is a person's (identity gate,
+  wherever `--json` stands); reading results is not. Schema and commands: [bench](../bench.md).
+
+
+## Amendment: Pi/local approval expiry and cancellation (issue #253)
+
+- An unanswered Pi/local approval returns an explicit expiry result: no person answered, do not retry that call, hand off or stop. It is not an answered denial. Two consecutive expiry results in the same native Pi turn or local worker turn end that turn with a console notice. An expiry counts toward the streak only when no person answered a request of that peer while it was pending (a per-peer answer epoch makes a parallel batch safe for an answering person); a grant served from the always cache or a permission mode is not an answer and does not reset the streak, and an actual new turn resets it. The turn ends through the same abort path an execution-budget stop uses, so Pi stays attached and the sender is told the approval reason. Supported Pi and local complete that correlated delivery after the reason reply, allowing the next queued message without an operator release. Pi clears the turn-only approval state at settlement and failure, so idle human shells remain usable and later failures cannot inherit its reason; a delayed approval abort rechecks that the same turn is still running. An extension that cannot abort a turn (one that does not advertise `approvalTurnAbort`) leaves Pi offline instead, with `ahub pi` restart and held-delivery settlement guidance. The second result remains an expiry tool failure before the abort. Approval stops do not invoke automatic safe replay or inference handoff.
+- Tool cancellation reaches the central approval registry. Settlement atomically removes the request and timer/abort listener before publishing closure or resolving. Late answers fail, cannot populate Pi's exact-tool always cache, and do not hold recovery waiting for approvals. Tool and budget continuations retain their captured session/generation; an admission response rechecks the owner and controller before changing a timer or recording a stop, and an old extension callback never aborts a later turn. Normal tool requests carry the session and generation captured before budget admission; the bridge refuses missing/stale lineage before registry, receipt or effect work, with restart guidance for an older extension. Spawned headless owners are pinned by the actual child process signature and its proven RPC session; TUI owners require the native claim. A Pi native abort is scoped to the verified owner, session, turn generation and call id; it withdraws only that call. Early native aborts fence a bounded set of call ids, with overflow failing closed for the remainder of that running turn. A managed tool that does not settle within the stop grace does not block the teardown: the stop goes on (shutdown, owner teardown, process stop) and reports the failure at the end.
+- A person's TUI shell command uses the existing authenticated idle reservation, session/owner/generation validation, sandbox and run-budget admission. It bypasses hub approval only in that trusted context and returns the sandbox's structured exit code through the receipt and native extension. Model tool arguments or printed output cannot establish human origin or exit status.
+- The dashboard counts waiting Pi/local approvals and directs the person to the console or `ahub tail` / `ahub permit`. It keeps those rows deny-only and never reveals private titles.
+
+## Amendment: requested headless peer stop (issue #278)
+
+- A console-role `{ t: "peer_stop", peer }` request stops a hub-owned headless ACP, Pi or local runtime through its adapter's owned-runtime teardown. Success is `{ ok: true, state: "offline" }`; refusal or incomplete stop is `{ ok: false, error }` naming the reason and next action. New requests already receive an unknown-request reply on older hubs, so `PROTOCOL` stays unchanged.
+- Refuse agent/tools-role callers, unknown or offline peers, Claude/Codex and Pi TUI owners, and recovery/shutdown-held mutations. Starts, requested stops and permission changes are fenced per peer; recovery preparation waits until requested stops finish. A TUI is ended in its terminal, or by the upgrade plan's verified terminal binding.
+- A requested stop marks each in-flight delivery `needs_review` with a fixed ids-only stop reason, cancels pending approvals, and fences stale native completion/failure callbacks. It never completes or implicitly redelivers interrupted work, invokes failure escalation, or triggers Pi's idle auto-restart. The operator inspects effects and explicitly resolves the delivery before replay. Queued unattempted work remains for the next manual start under existing holds/pauses.
+- `ahub stop <peer>` is human-only in `classifyPeerCommand`, prints the returned state, and reports an older hub's unknown request as requiring an upgrade, with a nonzero exit. The upgrade plan's headless `endPlannedPeer` uses the same console request; the daemon does not close a native terminal.
+
+- Requested stop admission also holds per-peer drain, pull and steering before any teardown await, without changing operator/budget pauses. Arriving work remains queued for explicit restart. Idle Pi captures live empty-session proof before stopping; a first accepted prompt with unpersisted history is not silently recreated as empty.

package/docs/specs/2026-09-20-upgrade-recovery-design.md

@@ -17,16 +17,24 @@ their matching CLI; the new coordinator never guesses a PID to terminate.
 
 ## Commands
 
-- `ahub upgrade --to <exact-version> --dry-run`: inspect the running registered
-  projects, release identity, native session mappings and blockers.
-- `ahub upgrade --to <exact-version> [--yes]`: review the plan, revalidate it and
-  schedule an independent recovery process. `--yes` accepts the displayed scope;
-  it never overrides blockers.
+- `ahub upgrade [--to <exact-version>] --dry-run`: inspect the running registered
+  projects, release identity, native session mappings and blockers. Without
+  `--to` the target is the registry's latest release (#272).
+- `ahub upgrade [--to <exact-version>] [--yes]`: review the plan, revalidate it and
+  schedule an independent recovery process. `--yes` accepts the displayed scope
+  and needs `--to`; it never overrides blockers. On a terminal without either
+  flag the review, the apply and the progress are one interactive session (see
+  "Interactive screens").
+- A target newer than the running CLI is handed to that release's own
+  coordinator (`bun x --package @staix/agent-hub@<version> ahub upgrade --to
+  <version>` with the same flags), named on stderr first and confirmed on a
+  terminal (#272).
 - `ahub --project <path|id> restart [--dry-run] [--yes]`: recover one project using
   the current package, without changing the global installation or plugin.
-- `ahub recovery status|resume <operation-id>`: read redacted progress or resume
-  the recorded operation after checking live ownership.
-- `ahub recovery abort <operation-id>`: cancel a preflight and release its lock
+- `ahub recovery status|resume [<operation-id>]`: read redacted progress or resume
+  the recorded operation after checking live ownership. Without an id every
+  `recovery` command takes the operation that holds the machine's lock (#272).
+- `ahub recovery abort [<operation-id>]`: cancel a preflight and release its lock
   only before a runtime has stopped or a terminal mutation has been attempted.
 
 Upgrade uses all affected running registrations. Stopped projects stay stopped.
@@ -50,6 +58,9 @@ parents/hops, retries, dedupe state, prefaces, manual pauses and peer descriptor
 The existing task and budget databases remain authoritative. A mismatched or
 corrupt snapshot blocks startup. Snapshot restoration precedes peer attachment;
 release is idempotent and retires replayable snapshot state before delivery.
+Journal-backed restoration retains missing empty queue entries from the committed
+bus snapshot, including peers that remain offline. The journal stays authoritative
+for queued work and receipts; a non-empty snapshot queue is never replayed over it.
 Release atomically moves that snapshot to a private per-operation archive before
 lifting the hold. Archives retain evidence for an uncertain release and are never
 automatically replayed. Preparation freezes the peer roster; a new unplanned peer
@@ -322,7 +333,12 @@ nor accepted when the target cannot read recovery waivers; `status` then says
 why in its own `freshSession` field, since `next` holds commands only. A runner
 record that cannot be read shows as `unknown` in `status`, never as no runner;
 while it reads so, resume, abort and dispose are all refused (the runner claim
-cannot tell its owner), so `next` names only `status` again. Otherwise `status` and every error that lists choices build them with one function
+cannot tell its owner), so `next` names only `status` again. The runner row
+carries its runner's process signature (#226): a row whose pid now belongs to
+another process (after a reboot, for example) is no runner and the next claim
+replaces it; one whose process exists but cannot be identified is `unknown`, and
+the claim refuses it with that reason, never a raw `kill` error. A row an older
+runner wrote has no signature and is judged by its pid alone, as before. Otherwise `status` and every error that lists choices build them with one function
 (`nextActions`), in this order: resume (which also launches a failed peer
 again), unless it can never get past what is live (`resumeBlocked`): a
 recorded final refusal (staging refused the fixed target or preserved source), a
@@ -330,11 +346,11 @@ missing project directory, a hub that speaks another control protocol, a
 runtime other than the one the receipt expects (a replaced source; a target not
 fenced to this operation, another instance or another version), a stopped
 pending source, a prepared source of a #215 coordinator that stopped with no
-commit request, a target that stopped after it started (restarting it is not
-supported in this release: its peers would have to be relaunched against the
-new instance), or any other stopped runtime without this operation's unreleased
-restart snapshot to start from (unavailable, starting or stopping is waited
-for). Then abort where `abortRefusal` allows it; a fresh session for each failed
+commit request, a target that stopped after it started when the operation's
+coordinator predates #225, or any other stopped runtime without this operation's
+unreleased restart snapshot to start from (unavailable, starting or stopping is
+waited for). A target that stopped after it started, with that snapshot, is
+started again by resume (#225, below). Then abort where `abortRefusal` allows it; a fresh session for each failed
 Codex or Claude restoration, only where resume is offered (resume launches the
 new session, and dispose refuses `--fresh-session` on the same predicate); and
 last stop-and-archive where `disposeRefusal` allows it, or else `wait until
@@ -366,7 +382,15 @@ target instance. It is live when its process signature matches, gone when the
 pid no longer exists (ESRCH) or now belongs to another process, and unknown when
 the pid exists but its identity cannot be read. Unknown is never treated as gone. At planning, an
 unknown Claude launcher blocks: whether the attached session is managed cannot
-be told.
+be told. A row that fails validation is never dropped and never read as "no
+launcher" (#228): unless its readable `peer`, `projectRoot` or `instanceId` names
+another launcher, it is unknown for that peer (it blocks binding, creation and the
+plan's managed check), and `ahub <peer>` writes every such row back unchanged,
+replacing only its own valid row. A launcher recorded by 0.12.12 or older hashed
+`ps` in its own TZ and locale (the pin came with #177): when the pinned signature
+differs, the signature computed the unpinned way in the reader's environment is
+compared too, and a match is live; a reader in another environment still reads
+such a launcher as gone.
 Restore reads this evidence in one place: the target's report, which counts only
 when the target runs as the expected instance, then the recorded launcher. A
 target that does not, a launcher that cannot be read, or a launcher record file
@@ -382,7 +406,18 @@ operation, and the runner keeps the disposition's own error. Abort and `next` de
 (`abortRefusal`). `status`, abort and the runner's errors read the same live
 state: every project not yet verified, its source or its target. A manifest
 whose pid no longer exists reads as stopped, whatever protocol it names; probing
-it would read unavailable forever. A stopped runtime also reports whose
+it would read unavailable forever. So does a manifest whose pid now belongs to
+another process (#226): from 0.12.21 `status.json` carries the daemon's process
+signature (`pidSignature`, in the file only; the status reply is unchanged, so no
+protocol bump), the registry claim carries it bound to the claiming instance, and
+every ownership check (manifest, claim, runner, manager owner) goes through one
+helper that reads live, gone or unknown. Recovery reads the claim from the
+registry as it is now, never from the plan's frozen copy. Daemons no longer write
+`hub.pid`; one an older daemon left is an unsigned legacy record. Records without
+a signature give the answers they always did, so an unsigned claim whose pid was
+reused still reads as starting: no command clears it (a hub started by 0.12.20 or
+older that crashed before a reboot), and the operations guide gives the manual
+clear after the process at that pid is checked. A stopped runtime also reports whose
 unreleased restart snapshot its state directory holds.
 An attached session is the target's report of that peer online with a thread
 (Codex) or session (Claude, Pi) id.
@@ -404,7 +439,9 @@ An attached session is the target's report of that peer online with a thread
 | project `prepared`, no `commitSent`, operation of a #215 coordinator | source stopped (crashed before any commit request) | blocks; the phase stays `prepared` (nothing was committed, so there is nothing to start from); not offered | abort if no effects, dispose | `<c> recovery abort <id>` without effects, else stop-and-archive (the lock refuses starting that hub by hand) |
 | project `prepared` | source unavailable, starting, stopping or not inspected | as above when it reads again | none: abort (its hold may still stand) and stop-and-archive are refused until it reads | `<c> recovery status <id>` once it answers |
 | project `prepared`, operation of an older coordinator (no `commitSent` written) | source not running, or not inspected | as its own runner does | dispose once it reads running, stopped or missing; abort neither offered nor accepted (it may have committed) | `<c> recovery status <id>` |
-| project `started` or `peers-restored` | target stopped (a crash or reboot after it started), with or without its snapshot | blocks; not offered: restarting it is not supported in this release | dispose; no fresh session | `the target stopped after it started; restarting it is not supported in this release` |
+| project `started` or `peers-restored` | target stopped (a crash or reboot after it started), this operation's snapshot kept | records the restart (dead instance, time), retires the dead instance's done `restored:<peer>` receipts, moves the project back to `stopped` and starts the target from the snapshot; once per resume | dispose | `the target stopped after it started; resume restarts it from this operation's snapshot` (`stopped again after restart <n> in this resume` when it stops again) |
+| project `started` or `peers-restored` | target stopped, snapshot gone | blocks; not offered | dispose | `this operation's restart snapshot is gone, so nothing can start it` |
+| `retired:<peer>` (a done restoration of a dead target instance) | Orca lists its terminal, or cannot be read | closed under the close receipt rules (`closedRetired:<peer>` `pending` until Orca no longer lists it); an unreadable inventory changes nothing | dispose | `close Orca terminal <handle> by hand` or `check it in Orca`, `then <c> recovery resume <id>` |
 | project `stopped` | target stopped without this operation's snapshot (never committed) | blocks; not offered | dispose | `the target is stopped and this operation's restart snapshot is gone` |
 | project `stopped`, `started` or `peers-restored` | target running unfenced, as another instance or another version | blocks; not offered | dispose | `daemon is not owned by this recovery operation` (or `daemon instance changed`, `target daemon version mismatch`) |
 | any, at staging | preserved source or staged target changed, or (first staging of these bytes only) target protocol or recovery waivers refused | blocks; recorded as `final`, so resume is never offered again | abort if no effects, dispose | the refusal |
@@ -437,10 +474,39 @@ and its `next` entry says what that runner cannot do. Stop-and-archive stops a
 target that speaks an older control protocol at that protocol (a `kill` fenced
 by its instance), then waits for its manifest and registry claim as the
 lifecycle stop does. The disposition and its audit are written before the first
-act. A recovery launch of `ahub codex` records its launcher before the hub's
+act. When the operation's coordinator predates #215, that same write sets the
+receipt's `schema` to 2 (#227): an older runner never reads `disposition`, and an
+older global `ahub recovery resume` still runs it, but every older runner and
+abort refuses a schema other than 1 before it takes the lock or claims the
+runner, so it exits having written nothing (an older `resume` still prints
+`scheduled`; an older `status` still prints the receipt). A #215 coordinator's
+operation keeps schema 1: its runner refuses a disposition itself, and a 0.12.20
+CLI can still rerun its dispose. This release accepts schema 2 only with a
+disposition, and the next abort or dispose that holds the runner claim moves a
+schema-1 disposition 0.12.20 recorded on an older coordinator's operation to 2. A recovery launch of `ahub codex` records its launcher before the hub's
 `start` round trip; an ordinary launch records it after, so a refused start never
 replaces the record of a Codex already running.
 
+#225: a target that stopped after it started is restarted only while its state
+directory holds this operation's unreleased snapshot. The runner records the restart
+in the project's receipt (`restarts`: the dead instance and the time) before acting,
+moves each done `restored:<peer>` binding to `retired:<peer>`, clears the instance
+and moves the project back to `stopped`, whose path starts the target from the
+snapshot; the journal imports the snapshot only at revision 0, so the second start
+continues from what the first wrote. `closed:<peer>`, `commitSent`, `fresh`, waivers
+and the install flags stay. Restore closes each retired terminal (or finds it
+absent) before relaunching that peer, and a peer whose retired session was an
+accepted new one (fresh choice, fresh start, zero-turn Claude) is relaunched by that
+id, which the operation-fenced waiver already covers, unless it has nothing to resume
+(a Codex thread with no rollout, a Claude session with no transcript): that one starts
+new under the waiver. Evidence reads the launch
+records of every instance the operation started for the project, the dead ones
+included, and a peer attached to the new instance without a session id is a session
+of unknown identity, never "nothing attached". One restart per project per resume:
+a target that stops again blocks with the restart count, so a crash loop never
+spins unattended. Operations whose coordinator predates #225 keep refusing (their
+own runner does), with stop-and-archive as the way out.
+
 A Codex thread with no rollout is not blocked at the plan only when the hub saw
 Codex start it (`native_thread` with `fresh`, logged by the adapter when it
 adopts a thread) and logged no Codex `turn_start` while it was the adopted
@@ -450,3 +516,71 @@ lose. Detaching forgets nothing; a thread whose start the log does not show
 (resumed, an older hub, a pruned log) is unsure and stays a plan blocker, as
 does one with turns. A planned fresh start still needs the store to show the
 rollout missing: an unreadable store blocks the close and the create.
+
+### Interactive screens (#272)
+
+`ahub upgrade`, `ahub restart` and bare `ahub recovery` on a terminal are a
+front end to the commands above, never a second coordinator.
+
+- The screens (`src/cli/upgrade-interactive.ts`) read the plan, the receipt, the
+  runner claim and the live inspections, and change an operation only by running
+  `recovery resume|abort|dispose` or `reset` as a child process, with the
+  operation's own coordinator (`recoveryArgv`, the argv form of
+  `recoveryCommand`). Each command decides its own refusal.
+- The operation screen's choices are `nextChoices`, the structured form of the
+  `next` list: `nextActions` is its text, and the invariant test that holds
+  `next` to what the commands accept also holds the two together.
+- One choice is not in `next`: cancelling while a runner only waits for its
+  source (`cancellableWait`: phase `running`, step `prepare:<project>`, no
+  effect receipt, no commit request). The screen stops only a runner that
+  `signedRunner` names: a claim whose recorded process signature still matches.
+  `recoveryRunner` answers an unsigned claim (a coordinator of 0.12.20 or older)
+  from its bare pid, which is enough to wait for and never enough to signal, so
+  cancel is not offered for it. The receipt is read again at the key press, and
+  `recovery abort` then reads what is live once more. A runner killed after it
+  recorded an effect leaves an operation that abort refuses and resume
+  continues, as after any runner crash.
+- The plan screen can end attached agents before the operation exists (user
+  request, 2026-10-10: choose to end headless or TUI agents during an upgrade).
+  A TUI agent is ended by closing the terminal the plan bound to its session; a
+  headless agent by the console-role request `peer_stop` to its hub (#278),
+  which an older hub answers as unknown. The plan is not acted on as it was
+  drawn: `endPlannedPeer` reads again the lock, the hub instance and the peer's
+  attachment, and for a TUI agent the attached session and the terminal's
+  handle and incarnation (`inspectTerminals` for that one session); any
+  difference ends nothing. `closeTerminal` itself compares only the terminal's
+  handle, incarnation, worktree and root. An ended agent is offline in the next
+  plan, so it is neither waited for nor restored. Nothing is ended once an
+  operation holds the lock: the coordinator's roster check reads a planned peer
+  that left as a changed source. With several projects in the plan an agent is
+  named `<project id>/<peer id>`, and a bare name attached in more than one
+  selects none. A Ctrl+C between two agents leaves the rest alone.
+- A Ctrl+C while `apply` checks the plan again creates no operation.
+- Ctrl+C leaves the screens and stops nothing; the terminal is not read again
+  after it, because a parent process that died on the same signal (`bun x`, a
+  hand-over) may have returned the terminal to the shell. While a progress view
+  runs, a line (Enter) opens the operation screen instead. A prompt answers an
+  interrupt or the end of input with no value, never with text.
+- A follow that starts right after a command scheduled a runner (resume, a
+  fresh session) waits for that runner's first write, up to 5 seconds: until
+  then the receipt still shows the blocked state it was scheduled from. It
+  starts from the receipt as the command left it (a fresh-session choice writes
+  the receipt itself before it schedules the runner).
+- The daemon's `recovery inspect` lists every condition `recoveryReady()` waits
+  for in `blockers` (task commands, completion checks, Pi calls and a release
+  in flight, an unsettled Pi, besides busy peers, approvals, startup and a
+  budget transition). The roster identity comparison is not listed. A hub that
+  is not ready and names no cause is shown as such.
+- The progress view prints the receipt's steps and, during `prepare`, the
+  source's own readiness blockers. `inspectRecovery` copies them into
+  `Inspection.recovery.waiting` for display only; `planFingerprint` leaves
+  `recovery` out, so they never change a plan's identity.
+- Without `--to` the target is `npm view @staix/agent-hub version`. `--yes`
+  keeps requiring `--to`, so an unattended apply names its release. `--to` is
+  checked as an exact version before it reaches the registry or a package spec.
+- The dry-run plan gains `projects[].source.recovery.waiting` when the hub
+  reports something in progress; nothing else in the non-interactive output
+  changes.
+- Out of scope: a hub-side interrupt of a running turn (the running source may
+  be older and would not know the request), and answering approvals from the
+  screens.