@staix/agent-hub 0.12.21 → 0.12.23

package/docs/verification/2026-10-11-0.12.23.md

@@ -0,0 +1,90 @@
+# Agent-hub 0.12.23 verification
+
+Release preparation for 0.12.23, performed on 2026-10-11 with Bun 1.4.2 on macOS. The release changes no file under `src/`, `test/` or `scripts/` relative to main at `94b489d`: it carries the version, the rebuilt plugin bundle, the changelog section, the document review below and the stamps in `docs/verified.json`. Production application is verified separately after publication.
+
+## What the release holds
+
+Seventeen pull requests merged since `v0.12.22` (`deeae76..94b489d`): settings and start modes (#269, pull requests #290 and #292), the assignment delivery fixes (#276, #297), the sandbox follow-ups and the hub's one git helper (#281), Kimi's context reading (#285 phase 1), the Codex steer and dashboard start fixes (#296, #298), readable command output (#284, pull requests #291, #299 and #314), the SQLite busy timeouts and the named retryable restart outcome (#303, pull requests #305 and #313), the ACP cancellation wait (#304), the Kimi quota refusal pause and handoff (#306) the macOS timing fixtures (#287), and the console's Left and Right tab keys, Events colours and unrepeated context readings (#309, pull request #312).
+
+Control protocol stays 16 (`PROTOCOL` in `src/hub/control-client.ts`) and the events schema stays 1 (`EVENTS_SCHEMA` in `src/hub/events.ts`). The new console-role requests (`settings_get`, `settings_set`, `settings_undo`, `settings_preview`, `peer_start`) are answered as unknown by an older hub, and the new fields are optional.
+
+## Changelog
+
+Sixteen of the seventeen pull requests have their entry in the 0.12.23 section; #291 and #299 share the #284 entry, and #305 and #313 each have their own #303 entry. #314, merged while this release was prepared, corrects how the unreleased #284 output splits a file name that holds combining marks or joined emoji; it is a clause of the #284 entry. The #309 line arrived under Unreleased with the merge of #312 and was moved into the section. No entry describes work that is not merged. The section heading carries no date, as no earlier section does. A closing line records the protocol and schema.
+
+## Document review
+
+`node scripts/check-docs.mjs` listed 13 stale documents at `bce5d00`. For each, the source commits since its stamp were read as the changed lines of `src/`, `scripts/`, `templates/`, `package.json` and `.github/`, with the commit messages, and the document was read against the code at `bce5d00`. All 13 are restamped; none is deferred. The corrections are in `88d4920`.
+
+`origin/main` then moved by #314 (`76f1695`, `src/cli/output.ts` and its test) and was merged into the branch with a merge commit, `002abf4`. Its change was read against the five documents it made stale again: none describes the split at that level and nothing needed a correction.
+
+`origin/main` moved once more by #312 (`94b489d`: `src/cli/console-state.ts`, `src/cli/console.ts` and the context line of the tail in `src/hub/daemon.ts`), merged in `e3313dd`. It made ten documents stale. Its own text in the operations guide ("Operator console and panels", "Native context readings") was read against the reducer, the paste branch and the tail's stamp and is accurate; README, the quickstart, the security guide and the six agent notes say nothing the change touches. No correction was needed and the ten are stamped at that merge commit.
+
+| Document | Source commits | Changed | Stamp |
+| --- | --- | --- | --- |
+| `README.md` | 16 | yes | `e3313dd` |
+| `docs/security.md` | 16 | yes | `e3313dd` |
+| `docs/operations.md` | 17 | yes | `e3313dd` |
+| `docs/quickstart.md` | 16 | yes | `e3313dd` |
+| `docs/agent-notes/adapters.md` | 12 | scope line only | `e3313dd` |
+| `docs/agent-notes/benchmarks.md` | 5 | no | `88d4920` |
+| `docs/agent-notes/budget.md` | 9 | yes | `e3313dd` |
+| `docs/agent-notes/bus.md` | 9 | no | `e3313dd` |
+| `docs/agent-notes/daemon.md` | 12 | yes | `e3313dd` |
+| `docs/agent-notes/local-worker.md` | 2 | scope line only | `88d4920` |
+| `docs/agent-notes/models.md` | 1 | no | `88d4920` |
+| `docs/agent-notes/tasks.md` | 12 | no | `e3313dd` |
+| `docs/agent-notes/tests.md` | 17 | no | `e3313dd` |
+
+README, the operations guide and the quickstart cover `package.json`, so their stamp has to follow the version commit (`62318e1`); the merge commit `e3313dd` does. Both stamps (`e3313dd` and `88d4920`) name commits of the release branch: the release pull request is merged with a merge commit, never squashed or rebased.
+
+### What changed
+
+- `README.md`, `docs/quickstart.md`: the dashboard also starts a peer in its start mode and shows the settings, and what an ordinary session may change (#269). The unified dashboard's Start opens a TUI only through a terminal provider; both pages said TUIs are launched from a terminal only.
+- `docs/security.md`:
+  - `terminal.open` is in `MACHINE_LOCAL` (`src/hub/config-trust.ts`) and was missing from the list of machine-local fields under "Trust boundaries".
+  - "A conductor may ... start supported headless peers" contradicted the page's own start-mode paragraph: `conductorStart` starts any startable peer in the mode a person set.
+  - The list of what the browser receives omitted the settings rows and the start plans (`settingsSnapshot`, `startPlans` in `src/hub/daemon.ts`).
+- `docs/operations.md`: the authority paragraph of "Settings" omitted that an ordinary session may set a start mode back to `tui` (the registry's `floor`, `settingRefusal` in `src/hub/settings.ts`). The version, the protocol-16 source lists and the upgrade commands follow the release.
+- `docs/agent-notes/daemon.md`: two rules the changes introduced and no note held. Every `new Database(` under `src/` is followed by its own named `busy_timeout`, enforced by `test/db-busy-timeout.test.ts` (#303). The manager's `start_peer` deadline is matched by the exact text `ControlClient.request` resolves with, and the reopen guard and the retry hold share `PEER_START_RETRY_MS` (#298).
+- `docs/agent-notes/budget.md`: Kimi's occupancy is a context reading only, and a gate crossing sends a checkpoint request to Claude and Codex only (#285); a quota resume notice is published before the unread notices it replaces are withdrawn (#306).
+- `AGENTS.md` and the scope lines of the daemon, adapters and local-worker notes name the files this release added (`start-mode.ts`, `terminal-open.ts`, `recovery-error.ts`, `db-timeout.ts`, `git.ts`), and `docs/verified.json` covers them, with `ui.ts` and `settings.ts` for the daemon note.
+
+### What was checked and found accurate
+
+- `docs/operations.md`: "Command output" against `src/cli/help.ts` and the flag handling in `src/cli/main.ts`; "Settings" and "Start modes" against `src/hub/settings.ts`, `src/hub/start-mode.ts`, `src/hub/terminal-open.ts` and `hubStart`; the assignment delivery paragraph against `assignOwner` and `undeliveredNotice`; the Kimi quota paragraphs against `src/adapters/acp-quota.ts`, `Budget.report` and `Bus.failed`; the `database_busy` paragraph against `src/hub/recovery-error.ts` and `runRecovery`; the Kimi context reading against `acpContext` and the adapter's idle acceptance; the dashboard Start timings against `src/hub/manager.ts`. The ACP cancellation wait (#304) needs no operator text: the daemon's bus always has a journal, and the wait applies to a bus without one.
+- `docs/security.md`: the settings and start-mode sections against the registry, `NEVER_EDITABLE`, the dashboard session window (`SETTINGS_MS`) and `personEnv`; the sandbox paragraph against `hubWriteRegexes` and `moduleGitDirs`.
+- `adapters.md`: the steer rule (#296), the occupancy rule (#285), the cancellation wait (#304), the quota contract (#306), the `stop(reason)` return of journal-less work and the terminal environment rule (#269), each against `src/adapters/acp.ts`, `src/adapters/codex-appserver.ts` and `src/hub/child-process.ts`.
+- `tasks.md`: the `assignOwner` rule against `src/hub/tasks.ts` at the head (#276, #297), and the overlay rule against `checkOverlay`.
+- `bus.md`: the quota flag changes `Bus.failed` only for a paused peer and is stated in `budget.md`; nothing in the note is contradicted.
+- `local-worker.md`: the submodule rules and the git helper against `src/local/deny.ts`, `src/local/sandbox.ts` and `src/hub/git.ts`.
+- `benchmarks.md`: the two #304 paragraphs against the adapter's cancellation deadline. `models.md`: its one commit renames a busy-timeout constant.
+- `tests.md`: against the workflow change, the ACP fake's held trailing updates and the harness of the new test files (`settings`, `start-modes`, `recovery-busy`, `hub-git`, `output-cli`).
+
+### What was not checked
+
+- The 5,600 changed lines under `test/` were not read assertion by assertion: for `tests.md` the fakes, the helpers and the opening of each new test file were read.
+- `src/ui/index.html` was read for the start controls only; the Settings section's rendering was not compared with the guides line by line.
+- The table-rendering code of `src/cli/output.ts` was not compared with the wrapping and banding sentences of "Command output"; `docs/verification/2026-10-10-cli-output-phase1.md` and `-phase2.md` record that check.
+- Sections of the operations guide that none of the merged commits touch in substance were not re-read in full.
+- `docs/events.md`, `docs/smoke.md` and the design spec are outside `docs/verified.json` and were not reviewed.
+
+## Checks
+
+All at the head of the branch after the merge of #312 and the last restamp, unless a line says otherwise.
+
+- `node scripts/check-docs.mjs`: `docs: OK (0 stale documents)`.
+- `bun x tsc --noEmit`: clean (exit 0).
+- `bun scripts/build.mjs --check`: the bundle and the plugin manifest are fresh (exit 0).
+- `scripts/check.sh`, admitted through `dot admit` and run without the agent session's environment markers, on the tree of the commit that holds this restamp (the merge `e3313dd` plus documents only): 1972 tests across 132 files in 311 s, 1972 pass, 0 fail, 26,811 expectations, no daemon leak; `check: OK`. This is the first full run on #312 and #314 together. An earlier run at `7ebd860`, before either merge, had 1953 pass and 0 fail.
+- `git diff origin/main...HEAD -- src test scripts` is empty.
+- CI at `e80c7af` (run 38104252746), first attempt: `check` on macOS (1972 pass, 0 fail, `check: OK`), `check` on Ubuntu (1941 pass, 31 skips, 0 fail, `check: OK`) and `seeded guards` (`seeded: OK (6 sequential guards, 13.237 s)`). The commit after `e80c7af` adds only this line; its own run is recorded on the pull request.
+
+## Not proven live (human-only)
+
+No live leg was run for this release. `docs/smoke.md` lists what stays unverified against real agents, among it: the settings leg and the start-mode legs (#269), Kimi 2.1.1's `usage_update` arrival through the hub (#285), the native measurement owed for #304, and the interactive upgrade legs (#272). An upgrade of a running 0.12.22 hub to this release has not been run.
+
+## Left for the owner
+
+- `test/upgrade-cli.test.ts` gained `withRestartDiagnostics` and the `AHUB_RESTART_DIAGNOSTICS_DIR` variable CI sets (#303). No note says a new installed-layout restart fixture should use it; whether that is a rule for `tests.md` is undecided.
+- `docs/operations.md` still says "From an installed CLI older than 0.12.22, start it once by hand" and titles the start-mode migration "from 0.12.22 and earlier"; both are historical and were left.

package/docs/verified.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "documents": {
     "README.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "e3313ddb1673edc91fb567793e42723d441e53f2",
       "paths": [
         "package.json",
         "src/",
@@ -11,14 +11,14 @@
       ]
     },
     "docs/security.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "e3313ddb1673edc91fb567793e42723d441e53f2",
       "paths": [
         "src/",
         "templates/"
       ]
     },
     "docs/operations.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "e3313ddb1673edc91fb567793e42723d441e53f2",
       "paths": [
         "package.json",
         "src/",
@@ -35,7 +35,7 @@
       ]
     },
     "docs/quickstart.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "e3313ddb1673edc91fb567793e42723d441e53f2",
       "paths": [
         "package.json",
         "src/",
@@ -43,7 +43,7 @@
       ]
     },
     "docs/agent-notes/adapters.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "e3313ddb1673edc91fb567793e42723d441e53f2",
       "paths": [
         "src/adapters/",
         "src/pi/",
@@ -55,11 +55,14 @@
         "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",
+        "src/hub/start-mode.ts",
+        "src/hub/terminal-open.ts"
       ]
     },
     "docs/agent-notes/benchmarks.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "88d49207d57a43e8beed8dbf95ad4a0283495b43",
       "paths": [
         "scripts/benchmarks/",
         "test/benchmarks/",
@@ -71,7 +74,7 @@
       ]
     },
     "docs/agent-notes/budget.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "e3313ddb1673edc91fb567793e42723d441e53f2",
       "paths": [
         "src/hub/budget.ts",
         "src/cli/statusline-tee.ts",
@@ -83,7 +86,7 @@
       ]
     },
     "docs/agent-notes/bus.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "e3313ddb1673edc91fb567793e42723d441e53f2",
       "paths": [
         "src/hub/bus.ts",
         "src/hub/envelope.ts",
@@ -95,7 +98,7 @@
       ]
     },
     "docs/agent-notes/daemon.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "e3313ddb1673edc91fb567793e42723d441e53f2",
       "paths": [
         "src/hub/daemon.ts",
         "src/hub/control-client.ts",
@@ -118,21 +121,32 @@
         "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",
+        "src/hub/ui.ts",
+        "src/hub/settings.ts",
+        "src/hub/start-mode.ts",
+        "src/hub/terminal-open.ts",
+        "src/hub/recovery-error.ts",
+        "src/hub/db-timeout.ts"
       ]
     },
     "docs/agent-notes/local-worker.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "88d49207d57a43e8beed8dbf95ad4a0283495b43",
       "paths": [
         "src/adapters/local-worker.ts",
         "src/local/",
         "src/memory/capture.ts",
         "src/hub/facts.ts",
-        "src/hub/permission-mode.ts"
+        "src/hub/permission-mode.ts",
+        "src/hub/git.ts"
       ]
     },
     "docs/agent-notes/models.md": {
-      "verifiedAgainst": "ab2925f7848a2eb848e9f0ab664df297c2c0f5fb",
+      "verifiedAgainst": "88d49207d57a43e8beed8dbf95ad4a0283495b43",
       "paths": [
         "src/models/",
         "src/hub/inference.ts",
@@ -141,7 +155,7 @@
       ]
     },
     "docs/agent-notes/tasks.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "e3313ddb1673edc91fb567793e42723d441e53f2",
       "paths": [
         "src/hub/tasks.ts",
         "src/hub/board.ts",
@@ -158,7 +172,7 @@
       ]
     },
     "docs/agent-notes/tests.md": {
-      "verifiedAgainst": "c084278691cd0c978e8208df6ba9eaa62031d7f2",
+      "verifiedAgainst": "e3313ddb1673edc91fb567793e42723d441e53f2",
       "paths": [
         "test/",
         "scripts/check.sh",
@@ -172,7 +186,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.23",
   "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.23",
   "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

@@ -15215,7 +15215,18 @@ import { join as join2 } from "path";
 // src/hub/project.ts
 import { existsSync, lstatSync, readFileSync, realpathSync } from "fs";
 import { basename, dirname, isAbsolute, join, resolve } from "path";
+
+// src/hub/git.ts
 import { spawnSync } from "child_process";
+var SAFE_CONFIG = ["core.fsmonitor=false", "core.hooksPath=/dev/null", "diff.external=", "core.pager=cat", "credential.helper=", "core.askpass="];
+var hubGitArgv = (args) => ["git", "--no-pager", ...SAFE_CONFIG.flatMap((c) => ["-c", c]), ...args];
+var hubGitEnv = (env = process.env) => ({ ...env, GIT_TERMINAL_PROMPT: "0" });
+function hubGitSync(args, options) {
+  const argv = hubGitArgv(args);
+  return spawnSync(argv[0], argv.slice(1), { ...options, env: hubGitEnv(options.env ?? process.env) });
+}
+
+// src/hub/project.ts
 var canonical = (path) => {
   const absolute = resolve(path);
   try {
@@ -15226,7 +15237,7 @@ var canonical = (path) => {
   }
 };
 function gitRoot(dir) {
-  const result = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  const result = hubGitSync(["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
   if (result.status !== 0)
     return;
   const root = result.stdout.trim();
@@ -15404,7 +15415,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.12.21",
+  version: "0.12.23",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",
@@ -15509,7 +15520,7 @@ var CONDUCTOR_TOOLS = [
   tool("hub_task_show", "Read a task's public view and history, its done summary and check result included. PII tasks remain stubs. Only the conductor and the task's current owner and reviewer may use this tool.", { id }, ["id"]),
   tool("hub_task_assign", "Move a task to another peer, as the conductor, or redirect a task you proposed while it is proposed and nobody accepted it. A task that still waits gets the peer as its reserved owner. When you have an explicit capabilities list, the conductor needs assign capability for any assign, the proposer only to hand the task to another peer.", { id, peer: str }, ["id", "peer"]),
   tool("hub_task_escalate", "Escalate a task through the normal task flow, as the conductor. Requires assign capability when explicitly listed.", { id }, ["id"]),
-  tool("hub_peer_start", "Start local, kimi or headless pi. Claude, Codex and Pi TUI requests return a command for the person to run, without launching a terminal.", { peer: { type: "string", enum: ["local", "kimi", "pi", "claude", "codex"] }, mode: { type: "string", enum: ["headless", "tui"] } }, ["peer"]),
+  tool("hub_peer_start", "Start local, kimi, pi, claude or codex in the start mode a person set for it; you cannot choose the mode. A headless peer starts at once. A TUI peer (claude, and pi and codex by default) opens in a terminal with a fixed command; when the hub cannot open a terminal the call fails with the command for the person to run.", { peer: { type: "string", enum: ["local", "kimi", "pi", "claude", "codex"] } }, ["peer"]),
   tool("hub_peer_hold", "Hold a peer's deliveries as the conductor. This hold is separate from the person's hold and budget pauses.", { peer: str }, ["peer"]),
   tool("hub_peer_release", "Release only the conductor hold you placed. Never lifts a person's hold or a budget pause.", { peer: str }, ["peer"])
 ];

package/src/adapters/acp-quota.ts

@@ -0,0 +1,13 @@
+/** Provider refusal observed from Kimi Code CLI 2.1.1 on 2026-10-11. No weekly/monthly or Qwen text is verified. */
+export const KIMI_2_1_1_5H_REFUSAL_PREFIX = "Authentication required: 403 You've reached your 5-hour usage limit. Your quota will reset when the current 5-hour window ends.";
+export interface ACPQuotaRefusal {
+  id: "5h";
+  used: 1;
+  windowMins: 300;
+  source: "kimi ACP usage-limit refusal";
+}
+/** Identity and turn/effect fencing are the caller's responsibility; an arbitrary 'quota' error is not a known refusal. */
+export function acpQuotaRefusal(message: string): ACPQuotaRefusal | undefined {
+  if (!message.startsWith(KIMI_2_1_1_5H_REFUSAL_PREFIX)) return undefined;
+  return { id: "5h", used: 1, windowMins: 300, source: "kimi ACP usage-limit refusal" };
+}

package/src/adapters/acp.ts

@@ -1,6 +1,7 @@
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { createInterface } from "node:readline";
-import { renderDigest, replyAudience, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
+import { renderDigest, replyAudience, replyParent, sanitize, type Envelope, type PeerId } from "../hub/envelope.ts";
+import { acpQuotaRefusal, type ACPQuotaRefusal } from "./acp-quota.ts";
 import { KIMI_MODE_IDS, type PermissionMode } from "../hub/permission-mode.ts";
 import { BasePeer } from "../hub/peers.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
@@ -66,6 +67,8 @@ export interface AcpOptions {
   /** Optional launch environment; recovery authority is always removed before spawn. */
   env?: NodeJS.ProcessEnv;
   watchdogMs?: number;
+  /** Bound for a journal-less watchdog cancellation to report its prompt; defaults to the 30 s ACP handshake cap. */
+  cancelWaitMs?: number;
   /** ACP stdio MCP servers for the session (the hub's task tools). */
   mcpServers?: { name: string; command: string; args: string[]; env: { name: string; value: string }[] }[];
   /** Appended to the standing instruction of the first delivery (role contract). */
@@ -75,7 +78,10 @@ export interface AcpOptions {
   /** The prompt rejected or ended without normal completion, even when it streamed partial text.
    *  Same shape as Pi's onTurnFailure; a stale cancelled turn never reports. */
   onTurnFailure?: (envs: Envelope[], reason: string) => Promise<void> | void;
-  onUsageDiagnostic?: (observation: ACPUsageDiagnostic) => void;
+  /** The sessionId is the adapter's own: the daemon binds a context reading to it, not to a lookup of its own (#285). */
+  onUsageDiagnostic?: (observation: ACPUsageDiagnostic, sessionId: string) => void;
+  /** Return true only when the current-session refusal has an authoritative quota pause; otherwise hold delivery. */
+  onQuotaRefusal?: (window: ACPQuotaRefusal) => boolean;
   /** Resolve with an optionId, or undefined to cancel. Absent = every request is cancelled.
    *  A request whose payload could not be resolved is titled as such and carries no session-wide allow option. */
   onPermission?: (req: PermissionRequest) => Promise<string | undefined>;
@@ -128,8 +134,12 @@ 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 activeLegacy: { turn: number; envs: Envelope[] } | undefined;
   private deliveryAccepted = false;
+  private cancelWait: { turn: number; successor: number; timer: ReturnType<typeof setTimeout> } | undefined;
+  private promptActivity = false;
 
   constructor(
     id: PeerId,
@@ -144,6 +154,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,24 +233,35 @@ 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;
+    this.clearCancelWait();
+    const legacy = this.activeLegacy;
+    this.activeLegacy = undefined;
+    // Journal-less work has no durable receipt: return it before a requested stop
+    // invalidates its generation, while stopping still prevents a drain.
+    if (legacy?.turn === this.turn) this.onFailed?.(legacy.envs);
+    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}`);
     }
     const turn = ++this.turn;
     this.activeDeliveryId = deliveryId;
+    this.activeLegacy = deliveryId ? undefined : { turn, envs };
     this.deliveryAccepted = false;
+    this.promptActivity = false;
     this.chunks = [];
     this.setState("busy");
     // session/prompt answers only when the turn ends, so deliver resolves now and failures come back through onFailed.
@@ -247,6 +269,9 @@ export class AcpPeer extends BasePeer {
     prompt
       .then((result) => {
         if (turn !== this.turn) return; // superseded: these chunks belong to a later turn
+        // This prompt has reported. A synchronous observer stop must not return
+        // completed work as if its native request were still in flight.
+        if (this.activeLegacy?.turn === turn) this.activeLegacy = undefined;
         this.observeUsage(result, "prompt_result");
         this.primed = true;
         const body = this.chunks.join("").trim();
@@ -259,13 +284,35 @@ export class AcpPeer extends BasePeer {
         }
       })
       .catch((e: Error) => {
-        this.opts.log?.(`[${this.id}] prompt failed: ${e.message}`);
-        if (turn === this.turn) this.reportTurnFailure(envs, e.message); // a watchdog-cancelled turn reports stale, never as this turn's failure
-        if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: e.message });
-        else if (!deliveryId) this.onFailed?.(envs);
+        if (turn !== this.turn) {
+          if (this.cancelWait?.turn === turn) this.opts.log?.(`[${this.id}] cancelled prompt rejected: ${sanitize(e.message)}`);
+          return; // cancelled prompt errors are discarded, like their late results
+        }
+        const reason = sanitize(e.message);
+        this.opts.log?.(`[${this.id}] prompt failed: ${reason}`);
+        const quota = !this.stopping && this.kimiAgent ? acpQuotaRefusal(e.message) : undefined;
+        if (quota) {
+          let paused = false;
+          try { paused = this.opts.onQuotaRefusal?.(quota) === true; }
+          catch (error) { this.opts.log?.(`[${this.id}] quota pause failed: ${sanitize(error instanceof Error ? error.message : String(error))}`); }
+          const safe = paused && !this.deliveryAccepted && !this.promptActivity;
+          if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: safe ? "failed_safe" : "needs_review", reason, ...(safe ? { quota: true as const } : {}) });
+          else if (!deliveryId && this.activeLegacy?.turn === turn) { this.activeLegacy = undefined; this.onFailed?.(envs, safe ? { quota: true } : undefined); }
+          return; // quota relay owns reassignment, not the ordinary turn-failure path
+        }
+        this.reportTurnFailure(envs, reason);
+        if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason });
+        else if (!deliveryId && this.activeLegacy?.turn === turn) { this.activeLegacy = undefined; this.onFailed?.(envs); }
       })
       .finally(() => {
-        if (turn === this.turn && this.state === "busy") this.setState("idle");
+        const waiting = this.cancelWait;
+        if (waiting?.turn === turn) {
+          this.clearCancelWait();
+          if (!this.stopping && this.turn === waiting.successor && this.state === "busy") this.setState("idle");
+          return;
+        }
+        if (turn === this.turn && !this.stopping && this.state === "busy") this.setState("idle");
+        if (this.activeLegacy?.turn === turn) this.activeLegacy = undefined;
         if (turn === this.turn && this.activeDeliveryId === deliveryId) this.activeDeliveryId = undefined;
       });
   }
@@ -280,6 +327,10 @@ export class AcpPeer extends BasePeer {
   }
 
   protected override onWatchdog(): void {
+    if (this.state !== "busy") return;
+    if (this.cancelWait) { this.clearWatchdog(); return; }
+    const cancelledTurn = this.turn;
+    this.activeLegacy = undefined; // the cancelled prompt is discarded, never returned by a later stop
     const durable = !!this.activeDeliveryId;
     if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: "ACP turn watchdog timeout" });
     this.activeDeliveryId = undefined;
@@ -288,12 +339,31 @@ export class AcpPeer extends BasePeer {
     // ACP updates carry only a session ID, not a turn ID. After a durable turn times out,
     // keep the adapter offline until it is restarted so late chunks cannot contaminate a new turn.
     if (durable) this.setState("offline");
-    else super.onWatchdog();
+    else {
+      this.clearWatchdog(); // waiting for cancellation is not a second inactive model turn
+      const successor = this.turn;
+      const timer = setTimeout(() => {
+        const waiting = this.cancelWait;
+        if (!waiting || waiting.turn !== cancelledTurn || waiting.successor !== successor) return;
+        this.clearCancelWait();
+        if (!this.stopping && this.turn === successor) {
+          this.setState("offline"); // keep queued work until restart
+          this.opts.log?.(`[${this.id}] cancelled prompt did not report within the cancellation deadline; peer offline, queued work retained; stop and restart the peer to resume delivery`);
+        }
+      }, this.opts.cancelWaitMs ?? HANDSHAKE_MS);
+      timer.unref?.();
+      this.cancelWait = { turn: cancelledTurn, successor, timer };
+    }
+  }
+
+  private clearCancelWait(): void {
+    if (this.cancelWait) clearTimeout(this.cancelWait.timer);
+    this.cancelWait = undefined;
   }
 
   private observeUsage(value: unknown, source: ACPUsageDiagnostic["source"]): void {
     const observation = normalizeACPUsage(value, source);
-    this.opts.onUsageDiagnostic?.(observation);
+    this.opts.onUsageDiagnostic?.(observation, this.sessionId);
     if (observation.availability === "known") this.opts.onTokens?.(observation.total!, this.sessionId);
   }
 
@@ -304,6 +374,7 @@ export class AcpPeer extends BasePeer {
   }
 
   private down(reason: string): void {
+    this.clearCancelWait();
     this.opts.log?.(`[${this.id}] ${reason}`);
     for (const p of this.pending.values()) p.reject(new Error(reason));
     this.pending.clear();
@@ -313,19 +384,34 @@ 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);
     } catch {
       return; // not protocol output
     }
-    if (this.state === "busy") this.touch();
+    if (this.state === "busy" && !this.cancelWait) this.touch();
 
     if (msg.method === "session/update") {
       if (msg.params?.sessionId && msg.params.sessionId !== this.sessionId) return;
-      if (this.state !== "busy") return;
-      this.acceptDelivery();
       const u = msg.params?.update;
+      // Occupancy is the session's, not the turn's: 2.1.1's source text emits usage_update after the prompt
+      // resolves, when the peer may already be idle (read from the source, not observed live; #285). So a
+      // context-used update is accepted while idle too, but then it must name the current session; in a turn the
+      // lenient session check above stands, as before. Every other update stays behind the busy gate, and a
+      // watchdog-cancelled turn's late chunks still lose their turn (the prompt result path is turn-fenced); an
+      // occupancy reading carries no turn state.
+      if (u?.sessionUpdate === "usage_update" && this.state !== "offline") {
+        const observation = normalizeACPUsage(u, "usage_update");
+        if (observation.shape === "context-used") {
+          if ((this.state === "busy" && !this.cancelWait) || msg.params?.sessionId === this.sessionId) this.opts.onUsageDiagnostic?.(observation, this.sessionId);
+          return;
+        }
+      }
+      if (this.state !== "busy" || this.cancelWait) return;
+      this.promptActivity = true;
+      this.acceptDelivery();
       if (u?.sessionUpdate === "agent_message_chunk" && u.content?.type === "text") this.chunks.push(u.content.text);
       // The permission request that follows may carry no `rawInput` (Kimi 2.0.1 does not), and then the
       // console would be asked to approve a bare tool name. Keep what the call said it would run (issue #31).
@@ -344,6 +430,8 @@ export class AcpPeer extends BasePeer {
       }
       else if (u?.sessionUpdate === "usage_update") this.observeUsage(u, "usage_update");
     } else if (msg.method === "session/request_permission") {
+      if (this.cancelWait) { this.send({ jsonrpc: "2.0", id: msg.id, result: { outcome: { outcome: "cancelled" } } }); return; }
+      if (this.state === "busy" && (!msg.params?.sessionId || msg.params.sessionId === this.sessionId)) this.promptActivity = true;
       void this.answerPermission(msg);
     } else if (msg.method && msg.id !== undefined) {
       this.send({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: "method not supported by agent-hub" } });
@@ -395,7 +483,7 @@ export class AcpPeer extends BasePeer {
     } finally {
       clearInterval(alive); // also when there is no handler at all
     }
-    const valid = options.some((o) => o.optionId === picked);
+    const valid = turn === this.turn && !this.stopping && options.some((o) => o.optionId === picked);
     this.send({
       jsonrpc: "2.0",
       id: msg.id,