@staix/agent-hub 0.12.21 → 0.12.22

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

@@ -812,8 +812,15 @@ session modes (`default`, `plan`, `auto`, `yolo`) but nothing per server or tool
   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. Unknown native baseline refuses
-  restoration. Actual native unattended flags, not broker-wide flags, govern
+  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,
@@ -823,8 +830,17 @@ session modes (`default`, `plan`, `auto`, `yolo`) but nothing per server or tool
   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. Without
-  separate native identity proof, prior files remain for manual inspection.
+  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.
@@ -2075,7 +2091,7 @@ acts on the stopped state directory.
 ## 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. Internal teardown notices direct inspection and `ahub pi`, without claiming a person requested them. Console notices name the next action or automatic-start state; headless code 0 is still an exit and settles active deliveries as uncertain.
+- 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)
 
@@ -2104,3 +2120,20 @@ acts on the stopped state directory.
   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.
@@ -508,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.

package/docs/verified.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "documents": {
     "README.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "146db2d192b3dfc129fd9fef2dd24452aa7f64ae",
       "paths": [
         "package.json",
         "src/",
@@ -11,14 +11,14 @@
       ]
     },
     "docs/security.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "48fc0eebcf24cb2bbb0a3a1abc17530ef49ed395",
       "paths": [
         "src/",
         "templates/"
       ]
     },
     "docs/operations.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "146db2d192b3dfc129fd9fef2dd24452aa7f64ae",
       "paths": [
         "package.json",
         "src/",
@@ -35,7 +35,7 @@
       ]
     },
     "docs/quickstart.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "146db2d192b3dfc129fd9fef2dd24452aa7f64ae",
       "paths": [
         "package.json",
         "src/",
@@ -43,7 +43,7 @@
       ]
     },
     "docs/agent-notes/adapters.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "48fc0eebcf24cb2bbb0a3a1abc17530ef49ed395",
       "paths": [
         "src/adapters/",
         "src/pi/",
@@ -55,11 +55,12 @@
         "src/hub/daemon.ts",
         "src/hub/permission-mode.ts",
         "src/hub/tool-refusal.ts",
-        "src/cli/identity.ts"
+        "src/cli/identity.ts",
+        "src/local/tools.ts"
       ]
     },
     "docs/agent-notes/benchmarks.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "48fc0eebcf24cb2bbb0a3a1abc17530ef49ed395",
       "paths": [
         "scripts/benchmarks/",
         "test/benchmarks/",
@@ -71,7 +72,7 @@
       ]
     },
     "docs/agent-notes/budget.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "48fc0eebcf24cb2bbb0a3a1abc17530ef49ed395",
       "paths": [
         "src/hub/budget.ts",
         "src/cli/statusline-tee.ts",
@@ -83,7 +84,7 @@
       ]
     },
     "docs/agent-notes/bus.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "48fc0eebcf24cb2bbb0a3a1abc17530ef49ed395",
       "paths": [
         "src/hub/bus.ts",
         "src/hub/envelope.ts",
@@ -95,7 +96,7 @@
       ]
     },
     "docs/agent-notes/daemon.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "48fc0eebcf24cb2bbb0a3a1abc17530ef49ed395",
       "paths": [
         "src/hub/daemon.ts",
         "src/hub/control-client.ts",
@@ -118,11 +119,15 @@
         "src/cli/console-state.ts",
         "src/cli/identity.ts",
         "src/cli/identity-audit.ts",
-        "src/hub/registry.ts"
+        "src/hub/registry.ts",
+        "src/cli/main.ts",
+        "src/cli/launch.ts",
+        "src/hub/child-process.ts",
+        "src/hub/bus.ts"
       ]
     },
     "docs/agent-notes/local-worker.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "48fc0eebcf24cb2bbb0a3a1abc17530ef49ed395",
       "paths": [
         "src/adapters/local-worker.ts",
         "src/local/",
@@ -141,7 +146,7 @@
       ]
     },
     "docs/agent-notes/tasks.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "48fc0eebcf24cb2bbb0a3a1abc17530ef49ed395",
       "paths": [
         "src/hub/tasks.ts",
         "src/hub/board.ts",
@@ -158,7 +163,7 @@
       ]
     },
     "docs/agent-notes/tests.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "48fc0eebcf24cb2bbb0a3a1abc17530ef49ed395",
       "paths": [
         "test/",
         "scripts/check.sh",
@@ -172,7 +177,8 @@
         "src/hub/child-process.ts",
         "src/switchyard/sidecar.ts",
         "src/local/sandbox.ts",
-        "src/models/mlx.ts"
+        "src/models/mlx.ts",
+        "src/cli/upgrade-interactive.ts"
       ]
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.12.21",
+  "version": "0.12.22",
   "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.21",
+  "version": "0.12.22",
   "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",

package/plugins/agent-hub/server.js

@@ -15404,7 +15404,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.12.21",
+  version: "0.12.22",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",

package/src/adapters/acp.ts

@@ -128,6 +128,7 @@ export class AcpPeer extends BasePeer {
   private readonly toolTitles = new Map<string, string>(); // the title a call was announced with, per call id (#138)
   private primed = false;
   private turn = 0; // generation: a prompt cancelled by the watchdog must not touch the turn that followed it
+  private stopping = false;
   private activeDeliveryId: string | undefined;
   private deliveryAccepted = false;
 
@@ -144,6 +145,7 @@ export class AcpPeer extends BasePeer {
   }
 
   async start(): Promise<void> {
+    this.stopping = false;
     const [bin, ...args] = this.opts.cmd;
     // Its own process group, stopped as a whole (#115, as Codex's in #113): an agent CLI may be a launcher with a native child.
     const proc = spawn(bin!, args, { cwd: this.opts.cwd, env: peerChildEnv(this.id, { ...process.env, ...(this.opts.env ?? {}) }), stdio: ["pipe", "pipe", "pipe"], detached: true });
@@ -222,18 +224,21 @@ export class AcpPeer extends BasePeer {
     this.permissionMode = mode;
   }
 
-  async stop(): Promise<void> {
-    if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: "ACP session stopped before settlement" });
+  async stop(reason?: string): Promise<void> {
+    this.stopping = true;
+    if (reason !== undefined) this.turn++; // a requested stop cannot escalate or complete the cancelled turn
+    if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: reason ?? "ACP session stopped before settlement" });
     this.activeDeliveryId = undefined;
     const proc = this.proc;
-    if (!proc) return;
+    if (!proc) { this.setState("offline"); return; }
     await stopOwnedProcess(proc, { group: true }); // also when it exited: what it left in its group fails the stop
     if (this.proc === proc) this.proc = undefined;
+    this.setState("offline");
   }
 
   /** Resolves once the prompt is in flight; the turn result arrives on its own. */
   async deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
-    if (this.state !== "idle") {
+    if (this.state !== "idle" || this.stopping) {
       if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} is ${this.state}` });
       throw new Error(`${this.id} is ${this.state}`);
     }
@@ -313,6 +318,7 @@ export class AcpPeer extends BasePeer {
   }
 
   private onLine(line: string): void {
+    if (this.stopping) return; // buffered native callbacks cannot recreate approvals after peer_stop
     let msg: any;
     try {
       msg = JSON.parse(line);

package/src/adapters/codex-appserver.ts

@@ -63,9 +63,9 @@ const TRACKED = new Set(["thread/start", "thread/resume"]);
  */
 export class CodexPeer extends BasePeer {
   private permissionMode: PermissionMode;
-  private nativeApprovalPolicy: unknown;
-  private approvalOverridden = false;
-  private readonly restoringApprovals = new Set<string | number>();
+  private readonly nativeApprovalPolicies = new Map<string, unknown>();
+  private readonly overriddenApprovals = new Set<string>();
+  private readonly restoringApprovals = new Map<string | number, string>();
   private proc: ChildProcess | undefined;
   private server: Server<Link> | undefined;
   private link: Link | undefined; // the connection that owns the current thread
@@ -191,7 +191,6 @@ export class CodexPeer extends BasePeer {
       this.pending.set(id, {
         deliveryId, kind: "deliver",
         resolve: (result) => {
-          if (this.restoringApprovals.delete(id) && this.permissionMode === "ask") this.approvalOverridden = false;
           this.primed = true;
           this.injected = replyParent(envs);
           this.answering = [...envs];
@@ -388,44 +387,50 @@ export class CodexPeer extends BasePeer {
 
   /** Reconcile the daemon's current choice after startup, before the returned proxy URL has a TUI. */
   setStartupPermissionMode(mode: PermissionMode): void {
-    if (this.link || this.state !== "offline" || this.approvalOverridden) throw new Error("codex startup mode reconciliation requires a fresh unattached proxy");
+    if (this.link || this.state !== "offline" || this.overriddenApprovals.size) throw new Error("codex startup mode reconciliation requires a fresh unattached proxy");
     this.permissionMode = mode;
   }
 
-  /**
-   * The hub's choice was cleared while no TUI is attached: this proxy sends no override from now on. Returns false
-   * when an override it already sent cannot be undone on that thread (its native policy was never reported): a thread
-   * started or resumed through the proxy afterwards reports its own policy, and that one is left alone.
-   */
+  /** Clear the overlay while detached, retaining each thread's restoration debt across a resume. */
   clearPermissionMode(): boolean {
-    const restorable = !this.approvalOverridden || this.nativeApprovalPolicy !== undefined;
+    const restorable = [...this.overriddenApprovals].every(thread => this.nativeApprovalPolicies.has(thread));
     this.permissionMode = "ask";
     return restorable;
   }
 
   async setPermissionMode(mode: PermissionMode): Promise<void> {
     if (!this.link || this.link.up.readyState !== WebSocket.OPEN) throw new Error("codex permission mode unavailable: attach the TUI through ahub codex first");
-    if (mode === "ask" && this.approvalOverridden && this.nativeApprovalPolicy === undefined) throw new Error("codex cannot restore ask: native approval policy unavailable; restart the Codex session");
+    if (mode === "ask" && [...this.overriddenApprovals].some(thread => !this.nativeApprovalPolicies.has(thread))) throw new Error("codex cannot restore ask: native approval policy unavailable; close the TUI, then run ahub permission codex ask before you restart the Codex session with ahub codex");
     this.permissionMode = mode;
   }
 
   private applyPermissionPolicy(params: Record<string, unknown>, id: string | number): Record<string, unknown> {
+    const thread = typeof params.threadId === "string" ? params.threadId : this.threadId;
     if (this.permissionMode !== "ask") {
-      this.approvalOverridden = true;
+      this.overriddenApprovals.add(thread);
       return { ...params, approvalPolicy: this.permissionMode === "never-ask" ? "never" : "on-request" };
     }
-    if (this.permissionMode === "ask" && this.approvalOverridden) {
-      this.restoringApprovals.add(id);
-      return { ...params, approvalPolicy: this.nativeApprovalPolicy };
+    if (this.overriddenApprovals.has(thread) && this.nativeApprovalPolicies.has(thread)) {
+      this.restoringApprovals.set(id, thread);
+      return { ...params, approvalPolicy: this.nativeApprovalPolicies.get(thread) };
     }
     return params;
   }
 
+  private settlePermissionRestore(id: string | number, failed: boolean): void {
+    const thread = this.restoringApprovals.get(id);
+    this.restoringApprovals.delete(id);
+    if (thread !== undefined && !failed && this.permissionMode === "ask") this.overriddenApprovals.delete(thread);
+  }
+
   private fromTui(link: Link, raw: string): void {
     const msg = parse(raw);
     if (msg?.method === "turn/start" && msg.params && link === this.link) {
-      if (msg.params.approvalPolicy != null) this.nativeApprovalPolicy = msg.params.approvalPolicy;
-      if (this.permissionMode !== "ask" || this.approvalOverridden) {
+      const thread = typeof msg.params.threadId === "string" ? msg.params.threadId : this.threadId;
+      // A resumed TUI can echo the sticky hub overlay. The restoring turn must use the kept baseline.
+      const restoring = this.overriddenApprovals.has(thread) && this.nativeApprovalPolicies.has(thread);
+      if (msg.params.approvalPolicy != null && !restoring) this.nativeApprovalPolicies.set(thread, msg.params.approvalPolicy);
+      if (this.permissionMode !== "ask" || this.overriddenApprovals.has(thread)) {
         // Native turn overrides persist: ask restores the captured native policy once on successful admission.
         msg.params = this.applyPermissionPolicy(msg.params, msg.id);
         raw = JSON.stringify(msg);
@@ -441,6 +446,7 @@ export class CodexPeer extends BasePeer {
     if (this.state === "busy") this.touch();
     if (!msg) return void link.tui.send(raw);
 
+    if (msg.id !== undefined && !msg.method) this.settlePermissionRestore(msg.id, !!msg.error);
     if (typeof msg.id === "number" && msg.id < 0 && !msg.method) {
       const p = this.pending.get(msg.id);
       this.pending.delete(msg.id);
@@ -448,14 +454,13 @@ export class CodexPeer extends BasePeer {
       else p?.resolve(msg.result);
       return; // ours: the TUI never asked for it
     }
-    if (msg.id !== undefined && !msg.method && this.restoringApprovals.delete(msg.id) && !msg.error && this.permissionMode === "ask") this.approvalOverridden = false;
     if (typeof msg.result?.userAgent === "string") this.version = /^[^/\s]+\/(\d+\.\d+\.\d+(?:-[\w.]+)?)/.exec(msg.result.userAgent)?.[1] ?? this.version;
     const tracked = msg.id !== undefined && !msg.method ? link.tracked.get(msg.id) : undefined;
     if (tracked && link.tracked.delete(msg.id)) {
       if (typeof msg.result?.thread?.id === "string") {
-        this.nativeApprovalPolicy = msg.result?.approvalPolicy;
-        this.approvalOverridden = false;
-        this.restoringApprovals.clear();
+        // A resumed response may report the sticky hub override, not the original native choice.
+        const thread = msg.result.thread.id;
+        if (!this.overriddenApprovals.has(thread) && msg.result.approvalPolicy != null) this.nativeApprovalPolicies.set(thread, msg.result.approvalPolicy);
         this.adopt(link, msg.result.thread.id, tracked === "thread/start");
       }
     }

package/src/adapters/local-worker.ts

@@ -8,7 +8,7 @@ import { renderDigest, replyAudience, replyParent, STANDING_INSTRUCTION, USER, t
 import { CONDUCTOR_TOOL_NAMES, CONDUCTOR_TOOLS, TASK_TOOL_NAMES, TASK_TOOLS } from "../hub/hub-tools.ts";
 import { BasePeer } from "../hub/peers.ts";
 import { profile, proxyEnv, type SandboxNetwork } from "../local/sandbox.ts";
-import { runTool, toolResultFailed, TOOL_SCHEMAS, touchedPaths, type ToolContext } from "../local/tools.ts";
+import { runTool, toolResultFailed, TOOL_SCHEMAS, touchedPaths, ApprovalWaitStop, type ToolApproval, type ApprovalProvenance, type ToolContext } from "../local/tools.ts";
 import type { Capture } from "../memory/capture.ts";
 import type { ChatMessage, ChatResult, OmniRoute, ToolCall } from "../omniroute/client.ts";
 import { safeModelLabel } from "../omniroute/usage.ts";
@@ -32,6 +32,7 @@ export interface LocalOptions {
   onRouteOutcome?: (event: RouteLabelEvent) => void;
   /** The daemon turn id created synchronously on busy, shared with turn_start/end. */
   turnId?: () => string | undefined;
+  onApprovalStop?: (reason: string) => void;
   onTool?: (observation: ToolObservation, task?: string) => void;
   tools: { deny: string[]; permit: ToolContext["permit"]; bashNetwork?: SandboxNetwork; readAllow?: string[] };
   capture?: Capture;
@@ -85,6 +86,9 @@ export class LocalPeer extends BasePeer {
   private abort: AbortController | undefined;
   private budgetTimer?: ReturnType<typeof setTimeout>;
   private budgetStopReason = "";
+  private approvalExpiries = 0;
+  private approvalAnswerEpoch: number | undefined;
+  private approvalStopReason = "";
   private activeDeliveryId: string | undefined;
   private readonly sandboxProfile: string; // built once: profile() spawns git and must stay off the per-call path
   /** What served the last call, for `ahub status`. */
@@ -127,15 +131,15 @@ export class LocalPeer extends BasePeer {
     this.setState("idle");
   }
 
-  async stop(): Promise<void> {
+  async stop(reason?: string): Promise<void> {
     this.endRouteTurn(this.labelTurnId, "failed");
-    if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: "turn stopped before settlement" });
+    if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: reason ?? "turn stopped before settlement" });
     this.activeDeliveryId = undefined;
     this.turn++;
     clearTimeout(this.budgetTimer); this.budgetTimer = undefined;
     this.abort?.abort();
+    this.setState("offline"); // fence direct delivery before the bounded memory request awaits
     await this.opts.capture?.end();
-    this.setState("offline");
   }
 
   /** Resolves once the turn is claimed; a turn that cannot reach any model hands the envelopes back through onFailed. */
@@ -146,6 +150,7 @@ export class LocalPeer extends BasePeer {
     }
     const turn = ++this.turn;
     this.budgetStopReason = "";
+    this.approvalExpiries = 0; this.approvalAnswerEpoch = undefined; this.approvalStopReason = "";
     clearTimeout(this.budgetTimer); this.budgetTimer = undefined;
     this.activeDeliveryId = deliveryId;
     this.abort = new AbortController();
@@ -172,6 +177,14 @@ export class LocalPeer extends BasePeer {
       })
       .catch((e: Error) => {
         if (turn !== this.turn) return; // aborted by the watchdog or stop(): nothing to report, nothing was committed
+        if (e instanceof ApprovalWaitStop) {
+          this.completeMissingToolResults(msgs, "not run: turn ended after unanswered approvals");
+          msgs.push({ role: "assistant", content: e.message });
+          if (!policy?.pii) this.commit(msgs);
+          this.onMessage?.(e.message, reply);
+          if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "completed", reason: e.message });
+          return; // even without effects, an unanswered approval must not trigger safe replay
+        }
         if (this.budgetStopReason && !(e instanceof ExecutionBudgetStop)) e = new ExecutionBudgetStop(this.budgetStopReason);
         this.opts.log?.(`[${this.id}] turn failed: ${e.message}`);
         if (e instanceof ExecutionBudgetStop) {
@@ -263,6 +276,7 @@ export class LocalPeer extends BasePeer {
           if (SIDE_EFFECTS.has(call.function.name) && !output.startsWith("error:")) progress.sideEffects++;
           const result: ChatMessage = { role: "tool", tool_call_id: call.id, content: output, is_error: toolResultFailed(name, output) };
           msgs.push(result); results.push(result);
+          if (this.approvalStopReason) { this.abort?.abort(); throw new ApprovalWaitStop(this.approvalStopReason); }
           this.observeTool(call, output, policy, `${this.sessionId}.${turn}.${step}`);
           // Hub tool arguments/results are not capture evidence; Tasks owns its screened memory writes.
           if (name !== "hub_send" && !TASK_TOOL_NAMES.has(name) && !CONDUCTOR_TOOL_NAMES.has(name)) capture?.observe({ tool: call.function.name, args: call.function.arguments, output, id: call.id, paths: touchedPaths(call.function.name, safeParse(call.function.arguments)) });
@@ -277,14 +291,34 @@ export class LocalPeer extends BasePeer {
     return {
       cwd: this.opts.cwd,
       deny: this.opts.tools.deny,
-      permit: async (title, tool, _signal, path) => {
-        if (turnSignal.aborted) return false;
-        return new Promise<boolean>((resolve, reject) => {
-          const finish = (allowed: boolean) => { turnSignal.removeEventListener("abort", onAbort); resolve(allowed); };
-          const onAbort = () => finish(false);
+      permit: async (title, tool, _signal, canonicalTarget) => {
+        if (turnSignal.aborted) return "aborted";
+        const generation = this.turn;
+        let observed = false;
+        const observe = (provenance: ApprovalProvenance) => {
+          observed = true;
+          if (generation !== this.turn || turnSignal.aborted || this.approvalStopReason) return;
+          if (this.approvalAnswerEpoch !== provenance.answerEpoch) {
+            this.approvalExpiries = 0; this.approvalAnswerEpoch = provenance.answerEpoch;
+          }
+          if (provenance.source === "person") this.approvalExpiries = 0;
+          if (provenance.source === "expired" && provenance.eligibleExpiry !== false && ++this.approvalExpiries >= 2) {
+            this.approvalStopReason = "Local turn stopped after two unanswered approvals; no person answered. Do not retry the calls; inspect prior work before handoff or stopping.";
+            try { this.opts.onApprovalStop?.(this.approvalStopReason); } catch { /* stop remains authoritative */ }
+          }
+        };
+        const picked = await new Promise<ToolApproval>((resolve, reject) => {
+          const finish = (decision: ToolApproval) => { turnSignal.removeEventListener("abort", onAbort); resolve(decision); };
+          const onAbort = () => finish("aborted");
           turnSignal.addEventListener("abort", onAbort, { once: true });
-          this.opts.tools.permit(title, tool, turnSignal, path).then(finish, (error) => { turnSignal.removeEventListener("abort", onAbort); reject(error); });
+          this.opts.tools.permit(title, tool, turnSignal, canonicalTarget, observe).then(finish, (error) => { turnSignal.removeEventListener("abort", onAbort); reject(error); });
         });
+        if (generation !== this.turn || (turnSignal.aborted && picked !== "expired")) return "aborted";
+        // Legacy permit callbacks can represent a person's denial without provenance. A true
+        // result may be automatic, so it must never reset the unanswered-request streak.
+        if (!observed && picked === false) observe({ source: "person", answerEpoch: (this.approvalAnswerEpoch ?? 0) + 1 });
+        if (!observed && picked === "expired") observe({ source: "expired", answerEpoch: this.approvalAnswerEpoch ?? 0, eligibleExpiry: true });
+        return picked;
       },
       sandboxProfile: this.sandboxProfile,
       sandboxEnv: { ...proxyEnv(this.opts.tools.bashNetwork ?? false), AGENTHUB_PEER_ID: this.id },