@staix/agent-hub 0.12.22 → 0.12.24

package/scripts/check-docs.mjs

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync, readdirSync, statSync, lstatSync, readlinkSync } from "node:fs";
+import { join, resolve, dirname, relative } from "node:path";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+// Stamps record a human source review, not an automatic proof of the prose.
+const args = process.argv.slice(2);
+const requireFresh = args.includes("--require-fresh");
+const jsonOutput = args.includes("--json");
+const committed = args.includes("--committed");
+const root = resolve(args.find((arg) => !["--require-fresh", "--json", "--committed"].includes(arg)) ?? fileURLToPath(new URL("..", import.meta.url)));
+const errors = [];
+const reports = [];
+const documents = [];
+let headId;
+let packageVersion;
+// Node-side equivalent of hub/git.ts: a readback must not execute repository-configured helpers.
+const safeGitConfig = ["core.fsmonitor=false", "core.hooksPath=/dev/null", "diff.external=", "core.pager=cat", "credential.helper=", "core.askpass="];
+const git = (...args) => spawnSync("git", ["--no-pager", ...safeGitConfig.flatMap(value => ["-c", value]), ...args], { cwd: root, encoding: "utf8", env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }, timeout: 2000, maxBuffer: 256 * 1024 });
+const read = (path) => {
+  if (!committed) return readFileSync(join(root, path), "utf8");
+  const result = git("show", `${headId}:${path}`);
+  if (result.status !== 0) throw new Error("committed documentation evidence unavailable");
+  return result.stdout;
+};
+const safePath = (path) => typeof path === "string" && path.length > 0 && !path.startsWith("/") && !path.startsWith("-") && !path.split("/").includes("..") && !path.includes("\\") && !path.includes(":");
+const evidenceExists = (path) => committed ? git("cat-file", "-e", `${headId}:${path}`).status === 0 : existsSync(join(root, path));
+const documentExists = (path) => {
+  if (!committed) return existsSync(join(root, path)) && statSync(join(root, path)).isFile();
+  const type = git("cat-file", "-t", `${headId}:${path}`);
+  return type.status === 0 && type.stdout.trim() === "blob";
+};
+/** Never refresh the index through git status: it can run configured clean/process filters. */
+const dirtiness = (paths) => {
+  const unknown = { status: 1, stdout: "" }, dirty = { status: 0, stdout: "dirty" };
+  const staged = git("diff-index", "--cached", "--quiet", "--no-ext-diff", "--no-textconv", "HEAD", "--", ...paths);
+  if (staged.status === 1) return dirty;
+  if (staged.status !== 0) return unknown;
+  const untracked = git("ls-files", "--others", "--exclude-standard", "-z", "--", ...paths);
+  if (untracked.status !== 0) return unknown;
+  if (untracked.stdout) return dirty;
+  const tracked = git("ls-files", "--stage", "-z", "--", ...paths);
+  if (tracked.status !== 0) return unknown;
+  const entries = tracked.stdout.split("\0").filter(Boolean);
+  if (entries.length > 4096) return unknown;
+  try {
+    for (const entry of entries) {
+      const match = /^([0-7]{6}) ([0-9a-f]{40}) ([0-3])\t([\s\S]+)$/.exec(entry);
+      if (!match) return unknown;
+      const [, mode, oid, stage, path] = match;
+      if (stage !== "0") return dirty;
+      // ponytail: gitlinks/large or transformed files stay unverified; never invoke a filter to establish equivalence.
+      if (!["100644", "100755", "120000"].includes(mode)) return unknown;
+      const file = resolve(root, path), within = relative(root, file);
+      if (!within || within.startsWith("../") || within === "..") return unknown;
+      for (let parent = dirname(file); parent !== root; parent = dirname(parent)) if (!lstatSync(parent).isDirectory() || lstatSync(parent).isSymbolicLink()) return unknown;
+      if (!existsSync(file) && mode !== "120000") return dirty;
+      const info = lstatSync(file);
+      let bytes;
+      if (mode === "120000") { if (!info.isSymbolicLink()) return dirty; bytes = readlinkSync(file, { encoding: "buffer" }); }
+      else { if (!info.isFile() || info.isSymbolicLink()) return dirty; if (info.size > 4 * 1024 * 1024) return unknown; bytes = readFileSync(file); }
+      const hash = createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex");
+      if (hash !== oid || mode !== "120000" && !!(info.mode & 0o111) !== (mode === "100755")) return dirty;
+    }
+    return { status: 0, stdout: "" };
+  } catch { return unknown; }
+};
+
+try {
+  if (committed) {
+    const head = git("rev-parse", "--verify", "HEAD");
+    if (head.status !== 0 || !/^[0-9a-f]{40}$/.test(head.stdout.trim())) throw new Error("HEAD does not resolve");
+    headId = head.stdout.trim();
+    const dirty = dirtiness(["docs", "README.md", "package.json"]);
+    if (dirty.status !== 0 || dirty.stdout) errors.push("documentation evidence files are dirty or unavailable");
+  }
+  const manifest = JSON.parse(read("docs/verified.json"));
+  if (manifest.schemaVersion !== 1 || !manifest.documents || typeof manifest.documents !== "object" || Array.isArray(manifest.documents)) throw new Error("invalid docs/verified.json schema");
+  let noteNames;
+  if (committed) {
+    const notes = git("ls-tree", "-z", "--name-only", `${headId}:docs/agent-notes`);
+    if (notes.status !== 0) throw new Error("committed agent notes unavailable");
+    noteNames = notes.stdout.split("\0").filter(Boolean);
+  } else noteNames = readdirSync(join(root, "docs/agent-notes"));
+  const required = ["README.md", "docs/security.md", "docs/operations.md", "docs/quickstart.md", ...noteNames.filter((name) => name.endsWith(".md")).map((name) => `docs/agent-notes/${name}`)];
+  for (const path of required.sort()) if (!Object.hasOwn(manifest.documents, path)) errors.push(`missing manifest entry: ${path}`);
+  const pkg = JSON.parse(read("package.json"));
+  if (typeof pkg.version === "string" && /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:[+][0-9A-Za-z.-]+)?$/.test(pkg.version)) packageVersion = pkg.version;
+  const version = read("README.md").match(/^Status: ([^,\s]+),/m)?.[1];
+  if (version !== pkg.version) errors.push(`README status version ${version ?? "missing"} differs from package.json ${pkg.version}`);
+  const head = git("rev-parse", "--verify", "HEAD");
+  if (head.status !== 0 || !/^[0-9a-f]{40}$/.test(head.stdout.trim())) throw new Error("HEAD does not resolve");
+  if (committed && headId !== head.stdout.trim()) throw new Error("HEAD changed during documentation readback");
+  headId = head.stdout.trim();
+  for (const [doc, entry] of Object.entries(manifest.documents).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+    const record = { ...(safePath(doc) ? { path: doc } : {}), state: "unknown" }; documents.push(record);
+    if (!safePath(doc) || !documentExists(doc)) { errors.push(`missing or invalid document: ${doc}`); continue; }
+    const stamp = entry?.verifiedAgainst;
+    if (typeof stamp !== "string" || !/^[0-9a-f]{40}$/.test(stamp) || git("cat-file", "-e", `${stamp}^{commit}`).status !== 0) { errors.push(`${doc}: verified commit does not resolve: ${String(stamp)}`); continue; }
+    record.verifiedAgainst = stamp;
+    if (git("merge-base", "--is-ancestor", stamp, "HEAD").status !== 0) { record.state = "nonancestor"; errors.push(`${doc}: verified commit is not an ancestor of HEAD: ${stamp}`); continue; }
+    if (!Array.isArray(entry.paths) || entry.paths.length === 0 || entry.paths.some((path) => !safePath(path))) { errors.push(`${doc}: invalid covered paths`); continue; }
+    let valid = true;
+    for (const path of entry.paths) {
+      // Git pathspecs let a scope cover a directory or an explicit wildcard (upgrade*.ts).
+      if (!/[?*\[]/.test(path) && evidenceExists(path)) continue;
+      // Preserve Git pathspec matching; every selected entry must exist in the captured committed tree.
+      const files = git("ls-files", ...(committed ? [`--with-tree=${headId}`] : []), "-z", "--", path);
+      const matches = files.stdout.split("\0").filter(Boolean);
+      if (files.status !== 0 || matches.length === 0 || matches.some((file) => !evidenceExists(file))) { errors.push(`${doc}: covered path no longer exists: ${path}`); valid = false; }
+    }
+    if (!valid) continue;
+    const count = git("rev-list", "--count", `${stamp}..HEAD`, "--", ...entry.paths);
+    const dirty = dirtiness(entry.paths);
+    if (count.status !== 0 || dirty.status !== 0) { errors.push(`${doc}: cannot compute source drift`); continue; }
+    const commits = Number(count.stdout.trim());
+    if (!Number.isSafeInteger(commits) || commits < 0) { errors.push(`${doc}: invalid source commit count`); continue; }
+    record.commits = commits; record.dirty = !!dirty.stdout; record.state = commits || dirty.stdout ? "stale" : "fresh";
+    if (commits || dirty.stdout) reports.push(`${doc}: stale (${commits} source commit${commits === 1 ? "" : "s"}${dirty.stdout ? "; uncommitted source changes" : ""})`);
+  }
+} catch (error) { errors.push(error instanceof Error ? error.message : String(error)); }
+if (!jsonOutput) for (const report of reports) console.log(`docs: ${report}`);
+if (requireFresh && reports.length) errors.push("release requires fresh documentation stamps");
+if (requireFresh && errors.length) errors.push("release refused: merge the release PR with a merge commit and verify all documentation stamps before tagging");
+if (jsonOutput) console.log(JSON.stringify({ schemaVersion: 1, ...(headId ? { head: headId } : {}), ...(packageVersion ? { version: packageVersion } : {}), documents, errors: errors.length, fresh: !errors.length && !reports.length }));
+else for (const error of errors) console.error(`docs: ERROR ${error}`);
+if (errors.length) process.exitCode = 1;
+else if (!jsonOutput) console.log(`docs: OK (${reports.length} stale document${reports.length === 1 ? "" : "s"})`);

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,7 +1,9 @@
+import { activityText, updateActivity, type Activity, type ActivityKind } from "../hub/activity.ts";
 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 { KIMI_MODE_IDS, type PermissionMode } from "../hub/permission-mode.ts";
+import { renderDigest, replyAudience, replyParent, sanitize, type Envelope, type PeerId, type PeerState } from "../hub/envelope.ts";
+import { acpQuotaRefusal, type ACPQuotaRefusal } from "./acp-quota.ts";
+import { KIMI_MODE_IDS, QWEN_MODE_IDS, type PermissionMode } from "../hub/permission-mode.ts";
 import { BasePeer } from "../hub/peers.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 
@@ -58,6 +60,12 @@ export interface AcpOptions {
   /** Coordinator-visible selected model only; contains no prompts or command arguments. */
   launchModel?: string;
   permissionMode?: PermissionMode;
+  /** Production Qwen only; legacy benchmark adapters retain their own native policy. */
+  qwen025?: boolean;
+  /** A production adapter's source-pinned identity; no table is inferred from it. */
+  expectedAgent?: { name: string; version: string };
+  /** Vendors with uncertain load semantics must explicitly echo the restored identity. */
+  requireLoadSessionEcho?: boolean;
   /** Bound for native mode acknowledgement; defaults to the handshake deadline. */
   permissionModeTimeoutMs?: number;
   /** Load this earlier session (ACP `session/load`) instead of starting a new one: crash recovery, issue #37. */
@@ -66,6 +74,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,12 +85,18 @@ 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>;
+  onPermission?: (req: PermissionRequest, signal?: AbortSignal) => Promise<string | undefined>;
   /** Tool titles approved once without asking: the hub's own tools, as Codex gets them (issue #72). Exact names only. */
   autoApprove?: (toolTitle: string) => boolean;
+  /** Transient person-only stream; no native update escapes through another observer. */
+  onActivity?: (item: Activity) => void;
+  isPrivateTurn?: () => boolean;
   log?: (line: string) => void;
 }
 
@@ -99,6 +115,9 @@ export function canonicalMcpToolName(announcedTitle: string | undefined, serverN
 }
 
 class RpcTimeoutError extends Error {}
+export class QwenIdentityError extends Error {
+  constructor() { super("Qwen Code 0.25.0 native identity is not verified; check the executable and its advertised ACP version"); }
+}
 
 type Pending = { resolve: (v: any) => void; reject: (e: Error) => void };
 
@@ -117,6 +136,7 @@ export class AcpPeer extends BasePeer {
   private permissionMode: PermissionMode;
   private modeUnknown = false;
   private kimiAgent = false;
+  private qwenAgent = false;
   private availableModes = new Set<string>();
   private proc: ChildProcessWithoutNullStreams | undefined;
   private sessionId = "";
@@ -130,7 +150,62 @@ export class AcpPeer extends BasePeer {
   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>; reported: boolean; released: Promise<void>; release: () => void } | undefined;
+  private promptActivity = false;
+  private activityOpen = false;
+  private activityPrivate = false;
+  private activityStub = false;
+  private activityStarted = 0;
+  private activityPending: { kind: "message" | "thought"; text: string } | undefined;
+  private activityTimer: ReturnType<typeof setTimeout> | undefined;
+  private emitActivity(kind: ActivityKind, text: string): void {
+    if (!this.opts.onActivity || !this.activityOpen) return;
+    // Privacy latches for the whole turn, even when the associated task closes mid-turn.
+    try { this.activityPrivate ||= this.opts.isPrivateTurn?.() === true; } catch { this.activityPrivate = true; }
+    if (this.activityPrivate) {
+      if (this.activityStub) return;
+      this.activityStub = true; kind = "private"; text = "Private turn: activity withheld";
+    }
+    try { this.opts.onActivity({ kind, text: activityText(text), at: Date.now(), turn: this.turn }); } catch { /* watch cannot affect delivery */ }
+  }
+  private flushActivity(): void {
+    clearTimeout(this.activityTimer); this.activityTimer = undefined;
+    const pending = this.activityPending; this.activityPending = undefined;
+    if (pending) this.emitActivity(pending.kind, pending.text);
+  }
+  private updateWatch(u: unknown): void {
+    if (!this.opts.onActivity) return;
+    const item = updateActivity(u);
+    if (!item) return;
+    if (item.kind === "message" || item.kind === "thought") {
+      if (this.activityPending?.kind !== item.kind || (this.activityPending.text.length + item.text.length > 4096)) this.flushActivity();
+      if (this.activityPending) this.activityPending.text += item.text;
+      else this.activityPending = { kind: item.kind, text: item.text };
+      this.activityTimer ??= setTimeout(() => this.flushActivity(), 50);
+      this.activityTimer.unref?.();
+    } else { this.flushActivity(); this.emitActivity(item.kind, item.text); }
+  }
+  private clearActivity(): void {
+    clearTimeout(this.activityTimer); this.activityTimer = undefined; this.activityPending = undefined;
+  }
+  private endActivity(reason: string, discardPending = false): void {
+    if (discardPending) this.clearActivity(); else this.flushActivity();
+    this.emitActivity("turn_end", `${reason}; ${Date.now() - this.activityStarted} ms`);
+    this.activityOpen = false;
+  }
+  private readonly permissionWaits = new Set<AbortController>();
+
+  protected override setState(next: PeerState): void {
+    if (next === "offline") { this.clearActivity(); this.cancelPermissions(); }
+    super.setState(next);
+  }
+
+  private cancelPermissions(): void {
+    for (const wait of this.permissionWaits) wait.abort();
+    this.permissionWaits.clear();
+  }
 
   constructor(
     id: PeerId,
@@ -165,12 +240,16 @@ export class AcpPeer extends BasePeer {
       // The configured peer id and command are labels, not an agent-specific mode contract.
       // Installed Kimi Code CLI's ACP initialize advertises this exact name.
       this.kimiAgent = init?.agentInfo?.name === "Kimi Code CLI";
+      if (this.opts.expectedAgent && (init?.agentInfo?.name !== this.opts.expectedAgent.name || init?.agentInfo?.version !== this.opts.expectedAgent.version)) throw new Error("native ACP identity is not verified for this production adapter");
+      this.qwenAgent = this.opts.qwen025 === true && this.id === "qwen" && init?.agentInfo?.name === "qwen-code" && init?.agentInfo?.version === "0.25.0";
+      if (this.opts.qwen025 && !this.qwenAgent) throw new QwenIdentityError();
       const resume = this.opts.resumeSessionId;
       if (!resume) return this.request("session/new", { cwd: this.opts.cwd, mcpServers: this.opts.mcpServers ?? [] });
       // The agent replays the session as updates while it loads; they arrive before the peer is idle, so none of
       // them is taken for an answer.
       if (!init?.agentCapabilities?.loadSession) throw new Error(`${this.id} cannot load an earlier session (the agent offers no loadSession)`);
       const loaded = await this.request("session/load", { sessionId: resume, cwd: this.opts.cwd, mcpServers: this.opts.mcpServers ?? [] });
+      if ((loaded?.sessionId !== undefined && loaded.sessionId !== resume) || (this.opts.requireLoadSessionEcho && loaded?.sessionId !== resume)) throw new Error("native ACP load did not confirm the requested conversation; no restored session is claimed");
       return { ...loaded, sessionId: resume };
     };
     const timeout = new Promise<never>((_, reject) => {
@@ -185,7 +264,7 @@ export class AcpPeer extends BasePeer {
       // must be reset for the configured ask default before any prompt; a fresh ask session stays untouched.
       const resetResumed = this.opts.resumeSessionId && typeof session.modes?.currentModeId === "string" && session.modes.currentModeId !== KIMI_MODE_IDS.ask;
       // Other ACP vendors retain their native policy, including reported non-default modes on resume.
-      if (this.kimiAgent && (this.permissionMode !== "ask" || resetResumed)) await this.setPermissionMode(this.permissionMode);
+      if (this.qwenAgent || (this.kimiAgent && (this.permissionMode !== "ask" || resetResumed))) await this.setPermissionMode(this.permissionMode);
     } catch (e) {
       this.setState("offline");
       if (this.proc === proc) {
@@ -198,13 +277,13 @@ export class AcpPeer extends BasePeer {
 
   getPermissionMode(): PermissionMode { return this.permissionMode; }
   get permissionModeState(): PermissionMode | "unknown" | "unmanaged" {
-    return !this.kimiAgent ? "unmanaged" : this.modeUnknown ? "unknown" : this.permissionMode;
+    return !this.kimiAgent && !this.qwenAgent ? "unmanaged" : this.modeUnknown ? "unknown" : this.permissionMode;
   }
 
   async setPermissionMode(mode: PermissionMode): Promise<void> {
-    if (!this.kimiAgent) throw new Error(`${this.id} permission mode ${mode} unmanaged: this ACP agent has no verified mode mapping; use Kimi Code CLI or add an agent-specific mapping`);
+    if (!this.kimiAgent && !this.qwenAgent) throw new Error(`${this.id} permission mode ${mode} unmanaged: this ACP agent has no verified mode mapping; use Kimi Code CLI or add an agent-specific mapping`);
     if (this.modeUnknown) throw new Error(`${this.id} permission mode unknown after an unanswered change; restart the peer before changing modes`);
-    const id = KIMI_MODE_IDS[mode];
+    const id = (this.qwenAgent ? QWEN_MODE_IDS : KIMI_MODE_IDS)[mode];
     if (!this.sessionId || !this.proc || !this.availableModes.has(id)) throw new Error(`${this.id} permission mode ${mode} unavailable: session does not offer ${id}`);
     try {
       await this.request("session/set_mode", { sessionId: this.sessionId, modeId: id }, this.opts.permissionModeTimeoutMs ?? HANDSHAKE_MS);
@@ -220,12 +299,22 @@ export class AcpPeer extends BasePeer {
       }
       throw new Error(`${this.id} permission mode ${mode} refused: ${(error as Error).message}`);
     }
+    // A mode reply after a cancelled prompt must also observe its queued cleanup.
+    if (this.cancelWait?.reported) await this.cancelWait.released;
     if (this.modeUnknown) throw new Error(`${this.id} permission mode unknown; restart the peer`);
     this.permissionMode = mode;
   }
 
   async stop(reason?: string): Promise<void> {
+    if (this.activityOpen) this.endActivity("stopped", true);
     this.stopping = true;
+    this.cancelPermissions();
+    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;
@@ -244,14 +333,28 @@ export class AcpPeer extends BasePeer {
     }
     const turn = ++this.turn;
     this.activeDeliveryId = deliveryId;
+    this.activeLegacy = deliveryId ? undefined : { turn, envs };
     this.deliveryAccepted = false;
+    this.promptActivity = false;
     this.chunks = [];
+    this.activityOpen = true;
+    this.activityPrivate = envs.some(env => env.private === true);
+    try { this.activityPrivate ||= this.opts.isPrivateTurn?.() === true; } catch { this.activityPrivate = true; }
+    this.activityStub = false; this.activityStarted = Date.now();
     this.setState("busy");
+    this.emitActivity("delivery", envs.map(env => `${env.from} ${env.id}`).join(", "));
+
     // session/prompt answers only when the turn ends, so deliver resolves now and failures come back through onFailed.
     const prompt = this.request("session/prompt", { sessionId: this.sessionId, prompt: [{ type: "text", text: this.primed || !this.opts.preamble ? renderDigest(envs, this.primed) : `${this.opts.preamble}\n\n${renderDigest(envs, false)}` }] });
+    const reported = () => { if (this.cancelWait?.turn === turn) this.cancelWait.reported = true; };
+    void prompt.then(reported, reported);
     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.endActivity(typeof result?.stopReason === "string" ? result.stopReason : "unknown", result?.stopReason === "cancelled");
         this.observeUsage(result, "prompt_result");
         this.primed = true;
         const body = this.chunks.join("").trim();
@@ -264,13 +367,36 @@ 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
+        }
+        this.endActivity("failed", true);
+        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;
       });
   }
@@ -285,6 +411,12 @@ export class AcpPeer extends BasePeer {
   }
 
   protected override onWatchdog(): void {
+    if (this.state !== "busy") return;
+    if (this.cancelWait) { this.clearWatchdog(); return; }
+    this.endActivity("watchdog cancelled", true);
+    const cancelledTurn = this.turn;
+    this.cancelPermissions();
+    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;
@@ -293,12 +425,34 @@ 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?.();
+      let release!: () => void;
+      const released = new Promise<void>(resolve => { release = resolve; });
+      this.cancelWait = { turn: cancelledTurn, successor, timer, reported: false, released, release };
+    }
+  }
+
+  private clearCancelWait(): void {
+    const waiting = this.cancelWait;
+    this.cancelWait = undefined;
+    if (waiting) { clearTimeout(waiting.timer); waiting.release(); }
   }
 
   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);
   }
 
@@ -309,6 +463,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();
@@ -325,13 +480,28 @@ export class AcpPeer extends BasePeer {
     } 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();
+      this.updateWatch(u);
       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).
@@ -350,6 +520,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.state === "offline") { 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" } });
@@ -362,6 +534,7 @@ export class AcpPeer extends BasePeer {
   }
 
   private async answerPermission(msg: any): Promise<void> {
+    this.flushActivity();
     const call = msg.params?.toolCall ?? {};
     const once = (msg.params?.options ?? []).find((o: PermissionOption) => o.kind === "allow_once");
     const id = typeof call.toolCallId === "string" ? call.toolCallId : undefined;
@@ -375,6 +548,8 @@ export class AcpPeer extends BasePeer {
     const identity = [typeof call.title === "string" ? call.title : undefined, canonical].find((candidate) => candidate !== undefined && this.opts.autoApprove?.(candidate));
     if (once && identity) {
       this.opts.log?.(`permission auto-approved for ${this.id}: ${identity}`); // the name only: arguments may quote a PII turn
+      this.emitActivity("ask", `${String(msg.id)}: ${activityText(announced ?? call.title)} (automatic)`);
+      this.emitActivity("answered", `${String(msg.id)}: allow_once (automatic)`);
       return this.send({ jsonrpc: "2.0", id: msg.id, result: { outcome: { outcome: "selected", optionId: once.optionId } } });
     }
     // The approver has to see what runs, not only the tool's name ("Bash"). The request itself carries it
@@ -389,19 +564,25 @@ export class AcpPeer extends BasePeer {
     const named = typeof call.title === "string" && jsonObject(call.title) === undefined ? call.title : announced;
     // An unknown payload is never dressed up as a description, and it must not buy a blanket grant.
     const title: string = raw === undefined ? `${named ?? "tool call"} (payload not reported by the agent)` : `${named ?? "tool call"}${input}`;
+    this.emitActivity("ask", `${String(msg.id)}: ${activityText(title)}; answer in ahub console`);
     const options: PermissionOption[] = (msg.params?.options ?? []).filter((o: PermissionOption) => (raw !== undefined && !cut) || o.kind !== "allow_always");
     // Only a bare tool name travels on its own (a desktop notice shows it); anything prose-like stays in the title.
     const tool = typeof named === "string" && /^[\w.:@-]{1,80}$/.test(named) ? named : undefined;
     // Waiting for a person is not the agent going silent: keep the watchdog from cancelling the turn meanwhile.
     const turn = this.turn;
     const alive = setInterval(() => this.state === "busy" && turn === this.turn && this.touch(), Math.max(10, Math.min(30_000, Math.floor(this.watchdogMs / 3))));
+    const controller = new AbortController();
+    this.permissionWaits.add(controller);
     let picked: string | undefined;
     try {
-      picked = await this.opts.onPermission?.({ peer: this.id, title, options, ...(tool ? { tool } : {}) }).catch(() => undefined);
+      const cancelled = new Promise<undefined>(resolve => controller.signal.addEventListener("abort", () => resolve(undefined), { once: true }));
+      picked = await Promise.race([this.opts.onPermission?.({ peer: this.id, title, options, ...(tool ? { tool } : {}) }, controller.signal).catch(() => undefined), cancelled]);
     } finally {
       clearInterval(alive); // also when there is no handler at all
+      this.permissionWaits.delete(controller);
     }
-    const valid = options.some((o) => o.optionId === picked);
+    const valid = !controller.signal.aborted && this.state !== "offline" && turn === this.turn && !this.stopping && options.some((o) => o.optionId === picked);
+    if (turn === this.turn) this.emitActivity("answered", `${String(msg.id)}: ${valid ? options.find(o => o.optionId === picked)?.kind : "cancelled"}`);
     this.send({
       jsonrpc: "2.0",
       id: msg.id,