@staix/agent-hub 0.12.19 → 0.12.21

package/docs/specs/2026-09-20-pi-local-models-design.md

@@ -18,6 +18,8 @@ Issue: #25. Pi is a managed project peer for implementation, edits, tests, summa
 - Apple Silicon setup pins Python 3.12, `mlx-lm==0.31.3`, and `Qwen/Qwen3-8B-MLX-4bit` revision `383413e909f3bc5303ce195ebbdf0339c5a1a2a3`.
 - The MLX input estimate is capped at 16,000 tokens; decode and prompt concurrency are one. DGX's default input estimate cap is 262,144 tokens.
 - The relay authenticates every call, rejects browser origins and unknown model aliases, and preserves streamed bytes. It records the requested route and model reported by the backend. Per request it also journals sanitized identity and lifecycle evidence (#139): resolved alias, upstream-configured model, observed provider and served model with their source (gateway header, generation SSE event, or local MLX configuration), outcome (completed, cancelled, failed), duration, and a confirmed-mismatch flag. A request cancelled before any identification stays explicitly unidentified; a backend's mutable last-served label is never a request's own evidence, and a primary/auxiliary role stays unknown without native evidence. Records carry no prompts, tools, keys or Access headers.
+- Load and cooldowns (#199, amended 2026-10-09). A `hub/auto` request bound for MLX keeps exactly its two candidates, MLX then its DGX fallback; load and cooldowns only reorder them, and a fixed alias (`mlx/fast`, `pi_backend = "mlx"`) is never reordered. The fallback goes first when MLX is cooling down, unless the fallback is cooling down or its own last dispatch failed in any way (an error status or a failed stream included) within 30 s and it has not succeeded since. Load moves are opt-in: with `[pi] efficient_wait_ms` set (below the 120 s slot wait; read when the hub first starts Pi), a movable request whose MLX slot is still busy after it, and an enforced tool loop pinned to the fallback, put the fallback first under the same health rule, and only while the request runs under no execution budget, where a move could spend the model call or the time MLX needs (budget-aware moves from the admission's remaining units are the upgrade path). Under #197 `enforce` a load move happens only at a user turn. A moved attempt gets a 15 s deadline to its response headers, after the gateway lookup, and is then abandoned for MLX; a reorder for a cooling MLX keeps the full request deadline. The bound ends with the headers: a stream that stalls or fails after them cannot fall back to MLX, and a failed one marks the fallback failing so later requests do not move. Each relay alias cools down after three consecutive transport or startup failures outside a cooldown (a failure more than twice the cap after the last counted one starts the count over), for 30 s doubling up to 5 min; a busy MLX slot and timeouts cut short by the execution budget never count, and any HTTP answer, a success or an error status, proves the transport works and clears the streak and the cooldown. A cooling DGX alias with no alternative is still tried. An alias that fails before it has a status row (gateway or key unavailable) gets one, so its cooldown shows. Both reorders are invisible to PII, which never reaches the relay (Pi refuses PII work). A load move journals no MLX attempt unless MLX then serves as the fallback. Route events record `source: "load"` or `"cooldown"` and `stateless` for a request without a session key; `events.jsonl` records `cooldown` start and end, and `ahub status` shows the cooldown on the backend line. Before the relay first starts MLX, startup decides as before. The live wait-time measurement on a mixed workload (#199 AC5) is open.
+- Decision, 2026-10-09: load moves are off unless `efficient_wait_ms` is set, a deviation from the issue's "default about 500 ms". Reason: the move is unmeasured (AC5 is open), its bound covers only the response headers, and each review round found another way an unmeasured move could make a request worse than main. Revisit with the AC5 measurement.
 - MLX may fall back to DGX before response streaming begins. Failed non-PII tasks can escalate to configured cloud peers with an explicit warning to reconcile partial effects.
 - Runtime ownership includes process start identity. Project shutdown releases its relay, while explicit `ahub models stop` controls the shared MLX process.
 

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

@@ -50,6 +50,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
@@ -163,3 +166,345 @@ The target coordinator accepts authenticated protocol 9, 10 and 11 sources, then
 uses protocol 11 after startup. Older supported managers are refreshed onto the
 current implementation. The real 0.6.4/protocol-9 transition and the 0.12.0/protocol-10
 development-hub transition are recorded in `docs/smoke.md`.
+
+### Unmanaged Claude sessions (#206)
+
+Amended 2026-10-09. An attached Claude session is managed when a live `ahub claude`
+launcher is recorded for the running daemon instance (`terminal-recovery.json`, its
+launcher identity checked with the shared `processSignature`) and the session record
+(`claude-session.json`) was written by that launch. Managed sessions are closed and
+resumed in a new terminal as before.
+
+Any other attached Claude session is unmanaged: a plain `claude`, an `ahub claude`
+outside Orca, or one whose launcher has ended. Its session record cannot be bound to
+the attached session, so the plan drops the id (no output names it) and lists the
+peer under `reconnectOnly`: no terminal is inspected, closed or relaunched, and the
+source roster check compares its membership only. Before starting the target the
+coordinator writes an operation-fenced waiver (`recovery-waivers.json`, mode 0600),
+so the restored daemon does not require the saved session id for that peer; release
+still requires it to reattach, which the coordinator waits for up to 90 seconds
+(three times the plugin's longest reconnect backoff). Reconnect-only requires the
+source control protocol to equal the target's; otherwise the plan names a blocker
+whose next action is to end the session or relaunch it with `ahub claude` in Orca.
+A live launcher whose record was written by another launch is a blocker, never a
+target. Refused `upgrade --yes` and `restart --yes`, and every dry-run, print each
+blocker on stderr before the final line.
+
+The channel's hello carries no launch id, so a plain `claude` that took the peer id
+from a live managed session is classified as managed. Telling them apart needs the
+launch id at hello, which is a protocol change and is not claimed here. A live
+upgrade with an unmanaged session attached has not been run.
+
+### Partial operations (#215)
+
+Amended 2026-10-09, before implementation.
+
+Expired preparation. The source hold lapses after ten minutes. When a project is
+still `prepared` (terminal effects may already be recorded) and its hold is gone,
+resume re-prepares the same source instead of reporting "source is no longer
+prepared". The running daemon must be the planned source instance: a replaced
+daemon or a source held by another operation is refused, with nothing prepared,
+closed or stopped. The coordinator prepares again under the same operation id,
+waits for readiness within the preparation bound (on timeout it aborts only its
+own hold) and checks the roster again. A peer whose terminal this operation
+already closed must stay detached; every other peer must keep its planned
+conversation. Effect receipts are never reset, so no terminal is closed twice,
+and the exclusive runner claim and instance fencing are unchanged. The
+re-prepared source records a closed peer as offline, so the target daemon does
+not require that peer itself; the coordinator still requires every originally
+attached peer back before release. A roster change while effects are recorded
+names the peer and the choices below instead of asking for a new plan.
+
+Native resume viability. A Codex thread counts as resumable only when a rollout
+file naming it exists under `sessions/` of the store its restoration uses (the
+launcher's captured `CODEX_HOME`, else `~/.codex`); an app-server thread id
+alone proves nothing. The plan blocks a Codex peer without one, the coordinator
+checks again before closing its terminal (closing nothing when it fails) and
+before creating the replacement.
+
+Launcher failure. Orca's `terminal create --command` types the command into a
+login shell, which outlives it, so the terminal never exits with the launcher
+and its exit is no evidence. The evidence is the hub's own: `ahub codex`,
+`ahub claude` and `ahub pi --mode tui` record their launcher (pid and process
+signature) in `terminal-recovery.json` for the terminal they run in, before
+they start the native agent. A replacement is awaited in 5-second slices of
+Orca's `tui-idle` wait (Orca 1.4.223 answers a timed-out wait with exit 1 and
+`{"ok":false,"error":{"code":"timeout"}}`, which counts as not yet). Between
+slices, and once the terminal reads idle (an idle terminal may be the shell the
+launcher returned to), a recorded launcher that is gone means the launch failed,
+recognized within one slice. A launcher whose identity cannot be read is unknown
+and is waited for, never taken as gone. A handle Orca reports
+`terminal_handle_stale` means the terminal is gone only when no recorded
+launcher may still run and Orca no longer lists the terminal's incarnation;
+otherwise the create stays uncertain. A launcher that died before recording
+itself is not distinguished from a slow one, and whether Orca reports the bare
+login shell as TUI-idle is not verified: if it does, the create stops at once as
+not mappable to the session; if not, after the 10-minute readiness bound. Either
+way it blocks as needing manual verification with the receipt `pending`, and the
+next resume, finding no live launcher and no attached session, records `failed`. Resume settles a `pending` or `failed` receipt by what is live
+(the table below): an attached planned (or accepted) session is the
+restoration, a launcher that may run is waited for, and only nothing live makes
+it `failed` or, for `failed`, launches again. No terminal is created while a
+recorded launcher for the peer may run on the target or its session is attached.
+A launch that failed, or a thread found not resumable before the launch, is
+receipted `restored:<peer>` = `failed` and never counts as restored. A Codex
+store that cannot be read (other than missing) is unknown and blocks the plan,
+the close and the create rather than counting as not resumable. Claude's
+zero-turn rule is unchanged; Pi resume viability is not checked.
+
+Failed restoration. The operation blocks naming the peer, its session or thread
+id and the choices. `resume` launches a failed peer again once its cause is
+fixed; a thread that is still not resumable fails again with the same choices.
+
+Status. `ahub recovery status <id>` reports the receipt (phase, step, update
+time, error); whether a runner process holds the operation now (`runner.state`
+`running` with its pid, or `none`); `stale` when the receipt says `running` but
+no runner holds it; each project's phase and effect receipts (`closed:<peer>`,
+`restored:<peer>` as `done`, `pending` or `failed`); whether the shared plugin
+and the global CLI were installed; any lost continuity and disposition; and
+`next`, the commands that apply now. It never contains task or message text.
+`resume` does not start a second runner while one is alive.
+
+Disposition. Two human-only choices, each with a required `--reason`, run from
+an ordinary terminal (agent shells are refused by the CLI identity gate), claim
+the runner (refusing while one is alive) and append to the receipt's audit:
+
+- `ahub recovery dispose <id> --fresh-session <peer> --reason <text>` applies
+  only to a Codex or Claude peer whose restoration is receipted `failed`; Pi is
+  refused, because a restored hub refills a Pi start from its recorded resume.
+  Like reconnect-only (#206), it needs a target that reads
+  `recovery-waivers.json`: staging refuses a target without it when a
+  reconnect-only session is planned, and the fresh launch is refused on one. Per affected project
+  it records the lost session or thread id (`fresh`) and schedules `resume`,
+  which writes an operation-fenced waiver so the restored daemon accepts a new
+  session for that peer, launches the peer without a resume id in a new
+  terminal, records the id the daemon then reports, and verifies everything
+  else as before. The operation may then complete; its status keeps the lost
+  continuity.
+- `ahub recovery dispose <id> --stop-and-archive --reason <text>` abandons the
+  operation. It inspects every project before acting. Every unverified project
+  must read as running, stopped or missing (`disposeRefusal`): any other reading
+  (unavailable, starting, stopping, incompatible, or an inspection that failed)
+  refuses the whole disposition, and a project whose directory is gone is
+  recorded as such (nothing to stop or archive). A
+  source this operation holds and has not committed gets its hold aborted and
+  keeps running. A target this operation started and has not released (a
+  running daemon in phase `restored` under this operation id, other than the
+  source, whether or not the receipt recorded its instance) is stopped by its
+  live instance through the lifecycle stop, which verifies the instance and
+  waits until its manifest and registry claim are gone, and is then inspected
+  again. A daemon this operation does not own, or one already released, is left
+  running. Each project's outcome is recorded as it happens; a disposition that
+  stops partway keeps the lock, and resume and `--fresh-session` then refuse
+  until `--stop-and-archive` is run again and finishes. A stopped project's committed
+  snapshot of this operation moves to `restart.abandoned.<hash>.json`, which is
+  never replayed, so an ordinary `up` works again. Queued envelopes are not
+  delivered from that file; a hub with a delivery journal (protocol 10 and
+  later) reloads the queues it persisted in `hub.db` on its next start.
+  Replacement terminals the operation created stay open, attached to nothing
+  until a hub runs again. Only then is the operation
+  recorded `cancelled` with its disposition (per-project outcome, plugin and CLI
+  state) and the lock released. It is never recorded as completed, the global
+  CLI is not promoted, and terminals it closed stay closed. A project whose
+  target ran is started again with the target's CLI. The archived reset proposed
+  in #214 can follow: no lock or replayable snapshot is left in its way.
+- `abort` stays the escape for a preflight without effects; its refusal names
+  the disposition. It also cancels a prepared project whose source still runs as
+  the same instance after its hold lapsed, which was never committed. A roster
+  change found while no effects are recorded offers `abort` exactly when
+  `abortRefusal` allows it (this operation's lock refuses a new upgrade until it
+  is cancelled).
+
+#### Receipts, evidence and next actions
+
+Resume, abort, dispose, the `next` list of `status` and every error follow this
+table. A `failed` receipt stays `failed` until the relaunch replaces it with
+`pending`, so a refusal on the way (an unreadable store, a launch found live, a
+target without waivers) keeps its choices. `--fresh-session` is neither offered
+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. 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
+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 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
+<project>'s hub settles, then <c> recovery status <id>`. `test/upgrade.test.ts`
+holds `next` to the commands with a fake driver for one project with no peers:
+ten receipt states (pending, prepared, prepared with a sent commit, prepared by
+an older coordinator, prepared with a closed terminal, stopped, started, started
+with a failed Codex restoration, peers restored, a partway stop-and-archive)
+crossed with ten live states (as planned, replaced, held by another operation,
+crashed, crashed with the snapshot kept, unavailable, starting, stopping,
+incompatible, missing); the older coordinator's operation is run there by the
+current runner, and its fakes never fail start, restore or verify (terminals,
+Orca and peers are covered by their own tests, not by this one). Abort, stop-and-archive and `--fresh-session codex` are offered
+exactly when the command accepts them on a twin fixture, and where resume is
+offered it makes progress or its error names a step a person takes first. An error gives only its own step (the
+last column below) and the runner ends it with that list (`next actions: ...`),
+read from the same sources as `status`, so it names abort exactly when
+`abortRefusal` allows it, the same as `status`, and never
+"make a new plan" alone: this operation's lock refuses a new one. `<c>` is the operation's own coordinator, printed in full as
+`bun <preserved source>/src/cli/main.js`: during an upgrade the global `ahub`
+may still be the older release, whose `recovery` lacks these commands.
+"Effects" means any project past `prepared` or any terminal receipt in the whole
+operation. Stop-and-archive (`<c> recovery dispose <id> --stop-and-archive
+--reason <text>`) is offered, as the last `next` entry, exactly when
+`disposeRefusal` allows it; the rows give what else applies.
+
+A recorded launcher is the `terminal-recovery.json` row for that peer on the
+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. 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
+that cannot be read or parsed is unknown and blocks without changing a receipt;
+the record file is written atomically (temp + rename), and a launch is not recorded
+over a record file that cannot be read (that would erase the other launchers'
+records). `ahub codex` and `ahub pi --mode tui` launched by the operation that
+holds the lock record themselves before the hub's start round trip. Whether a
+target reads waivers is one check, used by staging, restore, `next` and dispose. A truncated Orca
+inventory never shows a terminal as gone. While a stop-and-archive is recorded,
+`resume` is refused by the running release, whichever coordinator started the
+operation, and the runner keeps the disposition's own error. Abort and `next` decide with one predicate
+(`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. 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.
+
+| Receipt | Live evidence | Resume | Other actions | Next action text |
+| --- | --- | --- | --- | --- |
+| project `pending` or `prepared`, no effects | roster changed | blocks | abort where `abortRefusal` allows it, dispose | `end that <peer> session` or `restore <peer>'s original session` `before resuming, or end this operation: a new plan can be made once it is cancelled or ended` |
+| project `prepared`, hold ours | roster as planned | roster checked again, then close and commit | abort if no effects | none (it proceeds) |
+| project `prepared`, hold ours | roster changed, effects | blocks, hold kept | dispose | `end that <peer> session` (joined after the plan, or its terminal was closed) or `restore <peer>'s original session`, `then <c> recovery resume <id>` |
+| project `prepared`, hold lapsed (same source instance) | roster as planned | re-prepare, check roster, close, commit | abort if no effects | none |
+| project `prepared`, hold lapsed | roster changed | as the two rows above | as above | as above |
+| project `pending` | source replaced, stopped or missing | blocks, nothing touched; not offered | abort if no effects, dispose | `source runtime changed` |
+| project `pending` or `prepared` | source unavailable, starting or stopping | blocks until it answers | abort as `abortRefusal` decides; stop-and-archive refused until it reads | `wait until it answers` |
+| project `prepared` | source replaced | blocks, nothing touched; not offered | abort if no effects (cancels and leaves that daemon alone), dispose | stop-and-archive |
+| project `pending` or `prepared` | source held by another operation | blocks, nothing touched, until that operation ends | abort if no effects (leaves that hold alone), dispose | `wait until that operation ends or its hold lapses` |
+| any project not verified | project directory missing | blocks; not offered | abort as `abortRefusal` decides, dispose | `the project directory is missing` |
+| any project not verified | hub speaks another control protocol (incompatible) | blocks; not offered | abort as `abortRefusal` decides; stop-and-archive refused | `wait until <project>'s hub settles` (end it by hand: operations guide) |
+| project `prepared` with `commitSent` (a per-project receipt flag written right before the commit request; `step` is rewritten on every resume and is not evidence) | any (the commit may have been sent) | continues from the commit; a stopped source starts the target only from this operation's snapshot, so without it resume is not offered | dispose; abort is neither offered nor accepted | `<c> recovery resume <id>` |
+| 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), 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 |
+| any, at staging | the protocol probe did not answer (killed, exit 1) before the first staging | blocks, not final | dispose; abort if no effects | `resume again once it can run`; once staged, the checks are not run again |
+| disposition recorded, first act not finished | any | refused | abort refused; stop-and-archive where `disposeRefusal` allows it | as the disposition row below |
+| `closed:<peer>` `pending` | Orca still lists the terminal | blocks | dispose | `close Orca terminal <handle> (the login shell it runs in) by hand, then <c> recovery resume <id>` |
+| `closed:<peer>` done | peer attached again | blocks | dispose | `end that <peer> session, then <c> recovery resume <id>` |
+| `restored:<peer>` `pending` or `failed` | session attached with the planned id (or an accepted new one: fresh choice, planned fresh start, zero-turn Claude) | recorded as restored | none: `--fresh-session` is neither offered nor accepted while the inspection shows the planned session attached; when it cannot tell (not inspected, target unreadable), the `failed` receipt alone decides, and a chosen fresh session whose original then attaches is cleared on resume while its audit entry stays | none |
+| `restored:<peer>` `pending` or `failed` | another session attached | blocks | dispose | `end that <peer> session and close its terminal, then <c> recovery resume <id>` |
+| `restored:<peer>` `pending` or `failed` | no session, recorded launcher live or unknown | blocks | dispose | `wait until it attaches, or end it and close terminal <handle>, then <c> recovery resume <id>` |
+| `restored:<peer>` `pending` | no session, launcher gone or never recorded | receipted `failed`, blocks | fresh session (Codex, Claude), dispose | the failed-restoration choices below |
+| `restored:<peer>` `failed` | no session, launcher gone or never recorded | launches again (fresh if chosen) | fresh session (Codex, Claude), dispose | the failed-restoration choices below |
+| `restored:codex` absent | rollout missing | receipted `failed`, blocks, no terminal created | fresh session, dispose | the failed-restoration choices below |
+| any, before close or create | Codex store unreadable | blocks, nothing closed or created | dispose | `make <store> readable, then <c> recovery resume <id>` |
+| `restored:<peer>` absent | the planned session attached | recorded as restored | none | none |
+| `restored:<peer>` absent | another session attached, or a recorded launcher live | blocks, no terminal created | dispose | `end that <peer> session and close its terminal` (or `wait until it attaches, or end it and close terminal <handle>`), `then <c> recovery resume <id>` |
+| any receipt being settled or launched | target hub not running as the expected instance (unavailable, starting or stopping; a stopped or other target is settled by the rows above), or a launcher or launcher record file that cannot be read | blocks; no receipt changes, nothing created | dispose once the target reads running or stopped | `wait until the target answers` (or wait for / end the launcher, or inspect the record file and move it aside), `then <c> recovery resume <id>` |
+| `fresh` recorded for a peer | none live | launches it without a resume id, records the new id | dispose | none |
+| disposition recorded, not finished | any | refused | stop-and-archive only | `rerun <c> recovery dispose <id> --stop-and-archive --reason <text>` where `disposeRefusal` allows it, else `wait until <project>'s hub settles, then <c> recovery status <id>` |
+| `completed` or `cancelled` | any | nothing to do | none | none |
+
+The failed-restoration choices are `<c> recovery dispose <id> --fresh-session
+<peer> --reason <text>` (Codex or Claude; records the lost session and resumes;
+if the original session attaches after all, the recorded loss is cleared) and
+stop-and-archive. When the operation's own coordinator predates these commands
+(it has no `dispose`, refuses abort and resume on a lapsed hold and prints no
+`next`), `<c>` names the running release for every action: abort, status and
+dispose run in that process, while resume still runs the operation's own runner
+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. 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
+thread (Codex writes the rollout with the first message). The plan then lists
+it under `freshStart`, says so, and it restarts as a new session with nothing to
+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.

package/docs/specs/2026-10-04-switchyard-source-port-design.md

@@ -306,4 +306,14 @@ related: 261004-review-agent-hub-switchyard-comparison.md, 261004-plan-agent-hub
 - Existing sidecar routes remain optional and backward compatible; `[hub_routes]` never enters generated sidecar TOML. The sidecar retirement decision remains evidence-driven.
 - Each required phase is a separate reviewable commit and PR. No release or production configuration changes are implied.
 
+## Amendment: session-aware stay/switch (#197, 2026-10-09)
+
+- The stage tier is no longer re-decided in isolation on every call. `planSwitch(pin, fresh, turn, cost)` sits next to `selectStage` in `src/models/route/stage.ts`; `hub/auto` and local `stage` routes both reach it through `stayOrSwitch`, so they record the same trace.
+- Rules: a new session (the relay's `routeSessionKey`, the local route scope) or a compaction starts a fresh pin; a hard override escalates on any turn; a tool-result turn stays on the pinned tier; other changes wait for a user turn; a de-escalation whose conversation exceeds `max_switch_prefill_tokens` stays; a tier whose backend cannot hold the conversation is never chosen. Nothing summarizes, trims or rewrites the forwarded conversation.
+- `hold_turns` is unchanged: the stage hold still counts calls, and enforced, it can only extend past the next user turn, never end inside a tool loop.
+- Enforced, a clean test pass inside a tool loop does not de-escalate: it ends the stage hold, but the efficient tier waits for the next user turn. A dimension-driven escalation that a tool loop defers is not remembered by the planner: it reaches the next user turn only while `selectStage`'s hold still holds the capable tier, so a loop longer than the hold drops it. Hard overrides are never deferred: the planner reads pickTier's override predicate on its own (`hardOverride`), so a repeated failure or critical severity during a capable hold still escalates at once.
+- `routing.toml` top-level `stay_switch = "off" | "shadow" | "enforce"`, default `shadow`, which changes no routing decision. Local routes see no context limits (OmniRoute publishes none to the hub), so only `hub/auto` filters by fit.
+- Route events gain `turnType` (the issue's `turn`: the local `turn` field already holds the turn id), `prefillTokens` (omitted on PII routes, as a private envelope omits its size; a PII route's planner gets no prefill bound, so no plan or reason depends on the size), `staySwitch`, `plan` and `reason`. `ahub report` counts model changes per session and inside tool loops per peer and route; sessions are counted from pins, so they are unknown while `stay_switch` is `off`.
+- Deferred: joining provider cache counters to switches (the relay has no usage events), and switching the default to `enforce` until the measurement in #197 AC6.
+
 Implementation tracking: [#124](https://github.com/STAIxBWLB/agent-hub/issues/124), core [#125](https://github.com/STAIxBWLB/agent-hub/issues/125), local [#126](https://github.com/STAIxBWLB/agent-hub/issues/126), Pi [#127](https://github.com/STAIxBWLB/agent-hub/issues/127), observations [#128](https://github.com/STAIxBWLB/agent-hub/issues/128).

package/docs/verified.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "documents": {
     "README.md": {
-      "verifiedAgainst": "25d6ffe00c490a3690fc81782a45e62bfb383803",
+      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
       "paths": [
         "package.json",
         "src/",
@@ -11,14 +11,14 @@
       ]
     },
     "docs/security.md": {
-      "verifiedAgainst": "25d6ffe00c490a3690fc81782a45e62bfb383803",
+      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
       "paths": [
         "src/",
         "templates/"
       ]
     },
     "docs/operations.md": {
-      "verifiedAgainst": "25d6ffe00c490a3690fc81782a45e62bfb383803",
+      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
       "paths": [
         "package.json",
         "src/",
@@ -35,7 +35,7 @@
       ]
     },
     "docs/quickstart.md": {
-      "verifiedAgainst": "25d6ffe00c490a3690fc81782a45e62bfb383803",
+      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
       "paths": [
         "package.json",
         "src/",
@@ -43,7 +43,7 @@
       ]
     },
     "docs/agent-notes/adapters.md": {
-      "verifiedAgainst": "25d6ffe00c490a3690fc81782a45e62bfb383803",
+      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
       "paths": [
         "src/adapters/",
         "src/pi/",
@@ -52,11 +52,14 @@
         "src/hub/lifecycle.ts",
         "src/memory/capture.ts",
         "scripts/benchmarks/teardown.ts",
-        "src/hub/daemon.ts"
+        "src/hub/daemon.ts",
+        "src/hub/permission-mode.ts",
+        "src/hub/tool-refusal.ts",
+        "src/cli/identity.ts"
       ]
     },
     "docs/agent-notes/benchmarks.md": {
-      "verifiedAgainst": "8b7d7254f1bb5602ec5d658e7814e236f8fb43e7",
+      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
       "paths": [
         "scripts/benchmarks/",
         "test/benchmarks/",
@@ -68,7 +71,7 @@
       ]
     },
     "docs/agent-notes/budget.md": {
-      "verifiedAgainst": "25d6ffe00c490a3690fc81782a45e62bfb383803",
+      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
       "paths": [
         "src/hub/budget.ts",
         "src/cli/statusline-tee.ts",
@@ -80,7 +83,7 @@
       ]
     },
     "docs/agent-notes/bus.md": {
-      "verifiedAgainst": "25d6ffe00c490a3690fc81782a45e62bfb383803",
+      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
       "paths": [
         "src/hub/bus.ts",
         "src/hub/envelope.ts",
@@ -92,7 +95,7 @@
       ]
     },
     "docs/agent-notes/daemon.md": {
-      "verifiedAgainst": "25d6ffe00c490a3690fc81782a45e62bfb383803",
+      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
       "paths": [
         "src/hub/daemon.ts",
         "src/hub/control-client.ts",
@@ -114,20 +117,22 @@
         "src/cli/console.ts",
         "src/cli/console-state.ts",
         "src/cli/identity.ts",
-        "src/cli/identity-audit.ts"
+        "src/cli/identity-audit.ts",
+        "src/hub/registry.ts"
       ]
     },
     "docs/agent-notes/local-worker.md": {
-      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
+      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
       "paths": [
         "src/adapters/local-worker.ts",
         "src/local/",
         "src/memory/capture.ts",
-        "src/hub/facts.ts"
+        "src/hub/facts.ts",
+        "src/hub/permission-mode.ts"
       ]
     },
     "docs/agent-notes/models.md": {
-      "verifiedAgainst": "8b7d7254f1bb5602ec5d658e7814e236f8fb43e7",
+      "verifiedAgainst": "ab2925f7848a2eb848e9f0ab664df297c2c0f5fb",
       "paths": [
         "src/models/",
         "src/hub/inference.ts",
@@ -136,7 +141,7 @@
       ]
     },
     "docs/agent-notes/tasks.md": {
-      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
+      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
       "paths": [
         "src/hub/tasks.ts",
         "src/hub/board.ts",
@@ -147,11 +152,13 @@
         "src/cli/main.ts",
         "src/cli/preview.ts",
         "src/hub/conductor.ts",
-        "src/hub/supervision.ts"
+        "src/hub/supervision.ts",
+        "src/hub/tool-refusal.ts",
+        "src/hub/daemon.ts"
       ]
     },
     "docs/agent-notes/tests.md": {
-      "verifiedAgainst": "25d6ffe00c490a3690fc81782a45e62bfb383803",
+      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
       "paths": [
         "test/",
         "scripts/check.sh",
@@ -161,7 +168,11 @@
         "scripts/ci-gates.mjs",
         "scripts/ci-reuse.mjs",
         ".github/workflows/check.yml",
-        ".github/workflows/release.yml"
+        ".github/workflows/release.yml",
+        "src/hub/child-process.ts",
+        "src/switchyard/sidecar.ts",
+        "src/local/sandbox.ts",
+        "src/models/mlx.ts"
       ]
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.12.19",
+  "version": "0.12.21",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   "license": "MIT",
   "type": "module",

package/plugins/agent-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub",
-  "version": "0.12.19",
+  "version": "0.12.21",
   "description": "Channel between Claude Code and the agent-hub daemon: peer messages from Codex, Kimi and the local worker arrive as channel events; hub_send replies.",
   "author": {
     "name": "Young Joon Lee",