@staix/agent-hub 0.20.0 → 0.22.0

package/src/adapters/acp.ts

@@ -1,6 +1,7 @@
 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 { randomUUID } from "node:crypto";
 import { renderDigest, replyAudience, replyParent, sanitize, type Envelope, type PeerId, type PeerState } from "../hub/envelope.ts";
 import { acpQuotaRefusal, type ACPQuotaRefusal } from "./acp-quota.ts";
 import type { PermissionMode } from "../hub/permission-mode.ts";
@@ -49,6 +50,23 @@ export interface ACPUsageDiagnostic {
   total?: number;
 }
 
+/**
+ * One prompt's own token counters from its result's `usage` (Jcode 0.99.1: `inputTokens`, `outputTokens`, optional `cachedReadTokens` and `cachedWriteTokens`; a result with several provider
+ * calls carries their sum). Per turn, not a session total, and the provider's `totalTokens` is deliberately not read: Jcode adds the cached read on top of an input that already contains it for
+ * OpenAI-style providers, so that total double counts. Input and output must both be non-negative safe integers, else the whole record is unknown; an optional bucket that is present but
+ * malformed is dropped alone (unknown, never zero). Counters only: nothing else of the payload escapes.
+ */
+export interface ACPTurnUsage { inputTokens: number; outputTokens: number; cacheReadTokens?: number; cacheWriteTokens?: number }
+export function acpTurnUsage(result: unknown): ACPTurnUsage | undefined {
+  if (!result || typeof result !== "object" || Array.isArray(result)) return undefined;
+  const usage = (result as Record<string, unknown>).usage;
+  if (!usage || typeof usage !== "object" || Array.isArray(usage)) return undefined;
+  const u = usage as Record<string, unknown>;
+  const count = (v: unknown): v is number => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+  if (!count(u.inputTokens) || !count(u.outputTokens)) return undefined;
+  return { inputTokens: u.inputTokens, outputTokens: u.outputTokens, ...(count(u.cachedReadTokens) ? { cacheReadTokens: u.cachedReadTokens } : {}), ...(count(u.cachedWriteTokens) ? { cacheWriteTokens: u.cachedWriteTokens } : {}) };
+}
+
 /** Counter-only projection: no source payload, text, tools or metadata escapes. */
 export function normalizeACPUsage(value: unknown, source: ACPUsageDiagnostic["source"] = "usage_update"): ACPUsageDiagnostic {
   const unknown: ACPUsageDiagnostic = { source, availability: "unsupported", shape: "none" };
@@ -66,7 +84,8 @@ export function normalizeACPUsage(value: unknown, source: ACPUsageDiagnostic["so
     const a = f[input!], b = f[output!];
     return valid(a) && valid(b) && Number.isFinite(a + b) ? { source, availability: "known", shape: "input-output", total: a + b } : { source, availability: "invalid", shape: "input-output" };
   }
-  if (f.used !== undefined) {
+  // Either half of the pair names an occupancy update: one with `size` but no `used` (or the reverse) is a malformed reading, which must invalidate the previous value, not vanish as unrelated.
+  if (f.used !== undefined || f.size !== undefined) {
     if (!valid(f.used) || !valid(f.size) || !Number.isSafeInteger(f.used) || !Number.isSafeInteger(f.size) || f.size <= 0) return { source, availability: "invalid", shape: "context-used" };
     // Qwen 0.24.7 derives this from collectContextData: occupancy is not cumulative consumption.
     return { source, availability: "unsupported", shape: "context-used", contextUsed: f.used, contextCapacity: f.size };
@@ -110,6 +129,8 @@ export interface AcpOptions {
   preamble?: string;
   /** The session's running token total from `usage_update` (checked totalTokens or input/output pair; `used` context occupancy is diagnostic only). Cumulative, not a delta. */
   onTokens?: (sessionTotal: number, sessionId: string) => void;
+  /** One finished prompt's own counters (see `acpTurnUsage`), once per prompt that reported them; never a session total, so it never feeds `onTokens`. The sessionId is the adapter's own. */
+  onTurnUsage?: (usage: ACPTurnUsage, sessionId: string) => void;
   /** 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;
@@ -138,6 +159,45 @@ const HANDSHAKE_MS = 30_000;
 const TOOL_INPUT_CAP = 64;
 const TOOL_CEILING_MS = 30 * 60_000;
 
+export interface ManagedAcpLaunch {
+  readonly generation: string;
+  readonly cwd: string;
+  readonly sessionId: string;
+}
+interface ManagedAcpLaunchRecord {
+  readonly id: PeerId;
+  readonly options: AcpOptions;
+  readonly proc: ChildProcessWithoutNullStreams;
+  readonly proof: AcpOwnedGroup;
+  readonly receipt: Readonly<ManagedAcpLaunch>;
+}
+// Host evidence is deliberately outside runtime properties: copied metadata, private-field names
+// and an overridden start/recovery getter cannot manufacture a verified managed spawn.
+const managedLaunches = new WeakMap<object, ManagedAcpLaunchRecord>();
+function currentManagedLaunch(peer: unknown, expectedOptions: AcpOptions): ManagedAcpLaunchRecord | undefined {
+  if (!peer || (typeof peer !== "object" && typeof peer !== "function")) return undefined;
+  const record = managedLaunches.get(peer);
+  if (!record) return undefined;
+  const id = Object.getOwnPropertyDescriptor(peer, "id");
+  if (id?.value !== record.id || record.options !== expectedOptions || record.proc.exitCode !== null || record.proc.signalCode !== null) return undefined;
+  return record;
+}
+/** Exact host options identity is required; a factory that copies/replaces those options has no host binding. */
+export function managedAcpLaunch(peer: unknown, expectedOptions: AcpOptions): Readonly<ManagedAcpLaunch> | undefined {
+  return currentManagedLaunch(peer, expectedOptions)?.receipt;
+}
+/** Recheck the actual captured owned group after an await, then require the same current launch. */
+export async function verifyManagedAcpLaunch(peer: unknown, expectedOptions: AcpOptions): Promise<boolean> {
+  const record = currentManagedLaunch(peer, expectedOptions);
+  if (!record) return false;
+  try { await record.proof.verify(); }
+  catch {
+    if (peer && typeof peer === "object" && managedLaunches.get(peer) === record) managedLaunches.delete(peer);
+    return false;
+  }
+  return currentManagedLaunch(peer, expectedOptions) === record;
+}
+
 /**
  * The canonical tool binding (#138): an announced `<tool> (<server> MCP Server)` title resolves to
  * `mcp__<server>__<tool>` only when <server> is one this session was configured with. A title that
@@ -239,7 +299,7 @@ export class AcpPeer extends BasePeer {
   private readonly permissionWaits = new Set<AbortController>();
 
   protected override setState(next: PeerState): void {
-    if (next === "offline") { this.clearActivity(); this.cancelPermissions(); }
+    if (next === "offline") { managedLaunches.delete(this); this.clearActivity(); this.cancelPermissions(); }
     super.setState(next);
   }
 
@@ -266,11 +326,14 @@ export class AcpPeer extends BasePeer {
   }
 
   async start(): Promise<void> {
+    managedLaunches.delete(this);
     if (this.opts.requireOwnedGroup && this.proc) throw new Error("Configured ACP still has a process; stop it before starting another");
     this.stopping = false;
+    const launchedId = this.id;
+    const launchedCwd = this.opts.cwd;
     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 });
+    const proc = spawn(bin!, args, { cwd: launchedCwd, env: peerChildEnv(this.id, { ...process.env, ...(this.opts.env ?? {}) }), stdio: ["pipe", "pipe", "pipe"], detached: true });
     this.proc = proc;
     trackGroup(proc);
     proc.on("error", (e) => { if (!this.opts.requireOwnedGroup || this.proc === proc) this.down(`spawn failed: ${e.message}`); });
@@ -310,11 +373,13 @@ export class AcpPeer extends BasePeer {
         setTimeout(() => reject(new Error(`${this.id} did not complete the ACP handshake within ${HANDSHAKE_MS / 1000} s`)), HANDSHAKE_MS).unref();
       });
       const session = await Promise.race([handshake(), timeout]);
+      const nativeSession = session?.sessionId;
       if (this.nativePolicy !== undefined && (typeof session?.sessionId !== "string" || !session.sessionId.trim()
         || Buffer.byteLength(session.sessionId) > 4096 || /[\p{Cc}\p{Cf}]/u.test(session.sessionId))) {
         throw new Error("Configured ACP did not provide a valid native session identity");
       }
       this.sessionId = session.sessionId;
+      this.onDoing?.("reset");
       const modes: unknown = session.modes?.availableModes;
       this.availableModes = new Set(Array.isArray(modes) ? modes.flatMap((mode) => typeof mode?.id === "string" ? [mode.id] : []) : []);
       // A recovered session can retain a previous runtime opt-in. An advertised non-default mode
@@ -328,8 +393,13 @@ export class AcpPeer extends BasePeer {
         if (!owned || owned.proc !== proc || this.proc !== proc || this.stopping) throw new Error("Configured ACP process ownership could not be verified");
         await owned.proof.verify();
         if (this.proc !== proc || this.stopping) throw new Error("Configured ACP process ownership could not be verified");
+        if (typeof nativeSession !== "string" || !nativeSession.trim() || Buffer.byteLength(nativeSession) > 4096 || /[\p{Cc}\p{Cf}]/u.test(nativeSession)) throw new Error("Configured ACP did not provide a valid native session identity");
+        if (this.id !== launchedId || this.opts.cwd !== launchedCwd || this.sessionId !== nativeSession) throw new Error("Configured ACP peer identity changed during startup");
+        managedLaunches.set(this, { id: launchedId, options: this.opts, proc, proof: owned.proof,
+          receipt: Object.freeze({ generation: randomUUID(), cwd: launchedCwd, sessionId: nativeSession }) });
       }
     } catch (e) {
+      managedLaunches.delete(this);
       this.setState("offline");
       if (this.proc === proc) {
         if (this.opts.requireOwnedGroup) {
@@ -390,6 +460,7 @@ export class AcpPeer extends BasePeer {
   }
 
   async stop(reason?: string): Promise<void> {
+    managedLaunches.delete(this);
     if (this.activityOpen) this.endActivity("stopped", true);
     this.stopping = true;
     this.cancelPermissions();
@@ -453,6 +524,8 @@ export class AcpPeer extends BasePeer {
         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");
+        const turnUsage = acpTurnUsage(result);
+        if (turnUsage) try { this.opts.onTurnUsage?.(turnUsage, this.sessionId); } catch { /* a counter sink never costs a turn */ }
         this.primed = true;
         const body = this.chunks.join("").trim();
         // What was steered into the turn is answered by it too: its senders hear back, and the hop cap still holds.
@@ -597,6 +670,7 @@ export class AcpPeer extends BasePeer {
   }
 
   private down(reason: string): void {
+    managedLaunches.delete(this);
     this.clearCancelWait();
     if (this.nativePolicy !== undefined || this.opts.requireOwnedGroup) reason = "Configured ACP transport stopped";
     this.opts.log?.(`[${this.id}] ${reason}`);
@@ -657,6 +731,8 @@ export class AcpPeer extends BasePeer {
         for (const map of [this.toolInputs, this.toolText, this.toolTitles]) while (map.size > TOOL_INPUT_CAP) map.delete(map.keys().next().value as string);
       }
       else if (u?.sessionUpdate === "usage_update") this.observeUsage(u, "usage_update");
+      // #878: the plan's in-progress entry, for the hub's DOING column only.
+      else if (u?.sessionUpdate === "plan") this.onDoing?.("todo", Array.isArray(u.entries) ? u.entries.find((e: any) => e?.status === "in_progress")?.content : undefined);
     } 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;

package/src/adapters/channel-peer.ts

@@ -48,6 +48,10 @@ export class WsPeer extends BasePeer {
     this.claimed = sock;
     this.claimedPullOnly = pullOnly;
   }
+  /** Host transport observation, distinct from the peer's activity state. */
+  get attached(): boolean { return !!this.sock && this.sock.readyState === WebSocket.OPEN && !this.claiming; }
+  get managedLaunchId(): string | undefined { return this.attached ? this.sock?.data.launchId : undefined; }
+
   /** A session that shows pushes holds the peer or is arriving: a session without them must not take it (issue #205). */
   get channelHeld(): boolean {
     return (!!this.sock && !this.pullOnly) || (this.claiming && !this.claimedPullOnly);

package/src/adapters/claude-channel.ts

@@ -17,6 +17,7 @@ import { VERSION } from "../version.ts";
 import { IMPLEMENTER_HUB_TOOL_NAMES, IMPLEMENTER_PERMISSION_TOOL, ACTIONABLE_MESSAGE_INSTRUCTION, projectConductorTools, projectToolList, CONDUCTOR_TOOL_NAMES, DEFAULT_ROLES, roleContract, TASK_TOOL_NAMES, TASK_TOOLS, profileTaskTools } from "../hub/hub-tools.ts";
 import { frame, replyParent, sanitize, HUB_MESSAGE_INSTRUCTION, type Envelope } from "../hub/envelope.ts";
 import { renderHeldHint } from "../hub/delivery-hints.ts";
+import { acceptsNativePermissionRequest, buildNativePermissionProbe, NATIVE_PERMISSION_PROBE_MAX_PER_LAUNCH } from "../hub/native-permission-request.ts";
 
 // A native session is pinned at launch. Unlike a new CLI invocation after `cd`,
 // its MCP server must not silently move to another hub (including while offline).
@@ -26,6 +27,7 @@ const projectRoot = process.env.AGENTHUB_PROJECT_DIR ?? process.cwd();
 /** tools mode: the same server, run by Kimi (ACP mcpServers), Codex (mcp_servers override) or Jcode. Their messages arrive through their own adapters, so no channel here. Not the "tools-only" Claude below. */
 const toolsMode = process.env.AGENTHUB_MODE === "tools";
 const permissionTool = toolsMode && process.env.AGENTHUB_PERMISSION_TOOL === "1";
+let invalidPermissionAttempts = 0;
 /**
  * #368: a tools-mode server acts as exactly the peer whose owned launch started it, and the project's Jcode MCP entry names none, so the
  * id comes from the owned process env alone. With none (a person's own `jcode` run in this project outside the hub) it connects as nobody,
@@ -212,7 +214,7 @@ async function withPendingHint<T>(result: T, recommendInbox = true): Promise<T>
 async function push(envs: Envelope[], deliveryId?: string, generation?: string): Promise<void> {
   const parent = replyParent(envs); // reply_to on this id keeps the hop count honest
   const single = envs.length === 1;
-  const content = single ? parent.body : envs.map((e) => `--- from ${e.from} (id ${e.id}, kind ${e.kind}) ---\n${sanitize(e.body)}`).join("\n\n");
+  const content = single ? sanitize(parent.body) : envs.map((e) => `--- from ${e.from} (id ${e.id}, kind ${e.kind}) ---\n${sanitize(e.body)}`).join("\n\n");
   const meta = {
     source: single ? parent.from : "hub-digest",
     ...(single ? {} : { sources: [...new Set(envs.map((e) => e.from))].join(",") }),
@@ -396,16 +398,21 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
   if (name === "hub_permission_request") {
     const deny = (message: string) => text(JSON.stringify({ behavior: "deny", message }));
     if (!permissionTool || !hub) return deny("hub permission unavailable");
-    if (typeof args?.tool_name !== "string" || !/^[A-Za-z][A-Za-z0-9_.:/-]{0,127}$/.test(args.tool_name)
-      || !args.input || typeof args.input !== "object" || Array.isArray(args.input)
-      || typeof args.tool_use_id !== "string" || !args.tool_use_id.length || args.tool_use_id.length > 256) return deny("invalid native permission request");
+    if (!acceptsNativePermissionRequest(args)) {
+      // Diagnostic validation only: its response can never authorize this invalid native request.
+      if (++invalidPermissionAttempts <= NATIVE_PERMISSION_PROBE_MAX_PER_LAUNCH) {
+        const probe = buildNativePermissionProbe(args);
+        if (probe) try { await hub.request(probe, 1000); } catch { /* Old or unavailable hubs still deny locally. */ }
+      }
+      return deny("invalid native permission request");
+    }
     try {
       // Only this fixed client capability permits host wrapper grants; older clients keep person approval.
       const res = await hub.request({ t: "permission_request", tool: args?.tool_name, input: args?.input, wrapperProtocol: 1 }, 3_605_000);
       if (res.ok !== true || res.behavior !== "allow") return deny(typeof res.message === "string" ? res.message : "permission denied");
       if (res.wrapperProtocol !== undefined && res.wrapperProtocol !== 1) return deny("unsupported host execution response");
       const updated = res.wrapperProtocol === 1 ? res.updatedInput : undefined;
-      if (res.wrapperProtocol === 1 && (args.tool_name !== "Bash" || !updated || typeof updated !== "object" || Array.isArray(updated) || typeof updated.command !== "string")) return deny("invalid host execution response");
+      if (res.wrapperProtocol === 1 && (args?.tool_name !== "Bash" || !updated || typeof updated !== "object" || Array.isArray(updated) || typeof updated.command !== "string")) return deny("invalid host execution response");
       return text(JSON.stringify({ behavior: "allow", updatedInput: updated ?? args?.input }));
     } catch { return deny("hub permission unavailable"); }
   }
@@ -458,7 +465,7 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
 }
 
 // Inbox results still show fresh counts, without telling a held or refused reader to retry in a loop.
-server.setRequestHandler(CallToolRequestSchema, async (req) => withPendingHint(await callTool(req), req.params.name !== "hub_inbox"));
+server.setRequestHandler(CallToolRequestSchema, async (req) => withPendingHint(await callTool(req), req.params.name !== "hub_inbox" && req.params.name !== "hub_source_read"));
 
 await server.connect(new StdioServerTransport());
 // The host (Claude Code, Codex, Kimi) talks over stdin; once it is gone nothing can use this server, and a leftover would keep reconnecting.

package/src/adapters/claude-implementer.ts

@@ -11,9 +11,21 @@ import { sessionSettings } from "../cli/launch.ts";
 import { assessVersion, COMPAT } from "./compat.ts";
 import { OwnedPrintChild, PrintChildCleanupError, type OwnedPrintChildOptions } from "./claude-print-child.ts";
 import { ClaudeTaskSessions } from "./claude-task-sessions.ts";
+import { formatClaudeFailure, type ClaudeFailureTrace } from "../hub/claude-failure-stage.ts";
 import type { PermissionMode } from "../hub/permission-mode.ts";
 import type { ReviewerPrintUsage } from "./reviewer-print.ts";
 
+const provenVersions = new WeakMap<() => boolean, string>();
+function provenVersion(binding: () => boolean): string | undefined { return provenVersions.get(binding); }
+function sealFailureTrace(trace: ClaudeFailureTrace | undefined): void { try { trace?.seal(); } catch { /* diagnostics never affect owned cleanup */ } }
+function discardFailureTrace(trace: ClaudeFailureTrace | undefined): void { try { trace?.discard(); } catch { /* diagnostics never affect owned cleanup */ } }
+function readFailureTrace(trace: ClaudeFailureTrace | undefined): unknown {
+  if (!trace) return undefined;
+  // Every returned trace is sealed by onLeaderExit before authority is revoked.
+  try { return trace.take(); }
+  catch { discardFailureTrace(trace); return undefined; }
+}
+
 export interface ClaudeImplementerOptions {
   cwd: string;
   stateDir: string;
@@ -38,6 +50,12 @@ export interface ClaudeImplementerOptions {
   notify?(message: string): void;
   /** Test/embedding-only proof port; project configuration cannot select it. */
   prove?(): Promise<() => boolean>;
+  /** Host-observed failure evidence bound to one admitted native launch. */
+  failureTrace?(launch: Readonly<OwnedToolsLaunch>, nativeVersion?: string): ClaudeFailureTrace;
+  /** Resolve current privacy at final rendering; unknown or a throw is private. */
+  failurePrivate?(task?: number): boolean;
+  /** Optional host observer of the fixed, already privacy-screened failure message. */
+  failureLog?(message: string): void;
 }
 export interface ImplementerTurn { sessionId: string; resume: boolean; persistent: boolean }
 export function claudeImplementerArgs(turn: ImplementerTurn, mcp: string, settings: string, prompt: string, model?: string): string[] {
@@ -65,7 +83,9 @@ export async function proveClaudeImplementer(peer: string, command: readonly str
     const observed = COMPAT["claude-implementer"].parse(version), verdict = assessVersion("claude-implementer", observed);
     if (!verdict.ok) throw new Error(verdict.reason);
     if (fingerprint() !== binding) throw new Error("Claude implementer binary changed during proof");
-    return () => { try { return fingerprint() === binding; } catch { return false; } };
+    const proof = () => { try { return fingerprint() === binding; } catch { return false; } };
+    provenVersions.set(proof, verdict.version);
+    return proof;
   } finally { clearTimeout(timer); await child.stop(); rmSync(home, { recursive: true, force: true }); }
 }
 
@@ -84,6 +104,7 @@ export class ClaudeImplementerPeer extends BasePeer {
   private command: readonly string[] | undefined;
   private deliveryId: string | undefined;
   private inputReleased = false;
+  private failureTrace: ClaudeFailureTrace | undefined;
   private sessions: ClaudeTaskSessions;
   private stopping: Promise<void> | undefined;
   private stoppingTarget: "idle" | "offline" | undefined;
@@ -126,6 +147,7 @@ export class ClaudeImplementerPeer extends BasePeer {
     }
     this.stoppingTarget = next;
     ++this.generation; this.active = undefined; this.childAbort?.abort(); this.childAbort = undefined; this.abort?.abort(); this.clearWatchdog();
+    discardFailureTrace(this.failureTrace); this.failureTrace = undefined;
     this.settle(this.inputReleased ? "needs_review" : "failed_safe", reason);
     if (this.owned || this.running) this.setState("busy");
     const work: Promise<void> = Promise.resolve().then(async () => {
@@ -166,8 +188,10 @@ export class ClaudeImplementerPeer extends BasePeer {
   }
   private async run(groups: { task?: number; envs: Envelope[] }[], generation: number, running: Promise<void>): Promise<void> {
     const current = () => generation === this.generation && !this.abort?.signal.aborted;
+    let failureReason: string | undefined;
     try {
       for (let group of groups) {
+        failureReason = undefined;
         if (!current() || !this.binding?.()) throw new Error("Claude implementer admission changed");
         group = { ...group, envs: group.envs.filter(env => !env.private && this.options.admit(env)) };
         if (!group.envs.length) continue;
@@ -181,6 +205,7 @@ export class ClaudeImplementerPeer extends BasePeer {
           }
         }
         const launchId = randomUUID(), directory = mkdtempSync(join(this.options.stateDir, "claude-child-")), settings = join(directory, "settings.json");
+        let launchFailureTrace: ClaudeFailureTrace | undefined;
         this.cleanup = () => rmSync(directory, { recursive: true, force: true });
         writeFileSync(settings, sessionSettings(undefined, { script: this.options.factsHook, stateDir: this.options.stateDir, purpose: "permission" }), { mode: 0o600, flag: "wx" });
         const env = { AGENTHUB_MODE: "tools", AGENTHUB_PEER_ID: this.id, AGENTHUB_STATE_DIR: this.options.stateDir, AGENTHUB_PROJECT_DIR: this.options.projectRoot,
@@ -197,11 +222,15 @@ export class ClaudeImplementerPeer extends BasePeer {
               void this.cancel("Claude implementer admission changed before child start", "idle").catch(() => {});
               return;
             }
-            this.inputReleased = true; // OwnedPrintChild releases stdin immediately after this synchronous admission fence.
             this.childAbort = new AbortController();
-            this.active = { permissionHook: true, launchId, generation: `${generation}:${launchId}`, sessionId: turn.sessionId, signal: this.childAbort.signal, ...(group.task !== undefined ? { task: group.task } : {}) };
+            const launch: OwnedToolsLaunch = Object.freeze({ permissionHook: true, launchId, generation: `${generation}:${launchId}`, sessionId: turn.sessionId, signal: this.childAbort.signal, ...(group.task !== undefined ? { task: group.task } : {}) });
+            this.active = launch;
+            try { launchFailureTrace = this.options.failureTrace?.(Object.freeze({ ...launch }), provenVersion(this.binding!)); }
+            catch { launchFailureTrace = undefined; }
+            this.failureTrace = launchFailureTrace;
+            this.inputReleased = true; // OwnedPrintChild releases stdin immediately after this synchronous admission fence.
           },
-          onLeaderExit: () => { this.active = undefined; this.childAbort?.abort(); this.childAbort = undefined; },
+          onLeaderExit: () => { sealFailureTrace(launchFailureTrace); this.active = undefined; this.childAbort?.abort(); this.childAbort = undefined; },
           onActivity: () => this.touch(),
           onLimit: () => { void this.cancel("Claude implementer output limit exceeded", "idle").catch(() => {}); },
           onFrame: event => {
@@ -220,12 +249,21 @@ export class ClaudeImplementerPeer extends BasePeer {
         catch (error) {
           // spawn ENOENT has no owned group. A started child with failed group cleanup must keep its handle.
           if (child.process.pid === undefined) this.owned = undefined;
+          if (error instanceof PrintChildCleanupError) failureReason = this.failureReason(group.task, launchFailureTrace);
+          else discardFailureTrace(launchFailureTrace);
+          if (this.failureTrace === launchFailureTrace) this.failureTrace = undefined;
           throw error;
         }
         this.active = undefined; this.owned = undefined;
         this.cleanup?.(); this.cleanup = undefined;
-        if (!current()) return;
-        if (code !== 0 || !result || failed) throw new Error("Claude implementer turn failed");
+        if (!current()) { discardFailureTrace(launchFailureTrace); if (this.failureTrace === launchFailureTrace) this.failureTrace = undefined; return; }
+        if (code !== 0 || !result || failed) {
+          failureReason = this.failureReason(group.task, launchFailureTrace) ?? "Claude implementer turn failed";
+          if (this.failureTrace === launchFailureTrace) this.failureTrace = undefined;
+          throw new Error("Claude implementer turn failed");
+        }
+        discardFailureTrace(launchFailureTrace);
+        if (this.failureTrace === launchFailureTrace) this.failureTrace = undefined;
       }
       if (current()) {
         if (this.running === running) this.running = undefined;
@@ -234,7 +272,11 @@ export class ClaudeImplementerPeer extends BasePeer {
     } catch (error) {
       this.active = undefined; this.childAbort?.abort(); this.childAbort = undefined;
       if (current()) {
-        this.settle(this.inputReleased ? "needs_review" : "failed_safe", error instanceof PrintChildCleanupError ? "Claude implementer cleanup incomplete" : "Claude implementer turn failed");
+        const reason = error instanceof PrintChildCleanupError
+          ? failureReason === "Claude implementer turn failed (details withheld)" ? "Claude implementer cleanup incomplete; details withheld"
+            : failureReason ? `Claude implementer cleanup incomplete; ${failureReason}` : "Claude implementer cleanup incomplete"
+          : failureReason ?? "Claude implementer turn failed";
+        this.settle(this.inputReleased ? "needs_review" : "failed_safe", reason);
         if (this.owned) this.setState("busy"); else {
           this.cleanup?.(); this.cleanup = undefined;
           if (this.running === running) this.running = undefined;
@@ -243,4 +285,15 @@ export class ClaudeImplementerPeer extends BasePeer {
       }
     }
   }
+
+  private failureReason(task: number | undefined, trace: ClaudeFailureTrace | undefined): string | undefined {
+    if (!trace) return undefined;
+    const evidence = readFailureTrace(trace);
+    if (!evidence) return undefined;
+    let privateTurn = true;
+    try { privateTurn = this.options.failurePrivate?.(task) !== false; } catch { /* unknown privacy is private */ }
+    const message = formatClaudeFailure(evidence, privateTurn);
+    try { this.options.failureLog?.(message); } catch { /* host observation never changes settlement */ }
+    return message;
+  }
 }

package/src/adapters/codex-appserver.ts

@@ -9,6 +9,15 @@ import type { ContextReader } from "./registry-types.ts";
 import { ACTION_BUDGET_OPTION, type ActionGateVerdict, type PermissionRequest } from "./acp.ts";
 
 const UNIDENTIFIED_CANCELLATION_NOTICE = "Codex cancelled turn has no verified native id; reattach the native session before further hub delivery";
+const PLANNER_SANDBOX_REFUSAL = "Codex planner thread requires a confirmed read-only sandbox";
+
+/** Codex 0.164.0 SandboxPolicy readOnly variant; an unreadable or widened policy is not proof. */
+function confirmsReadOnlySandbox(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const policy = value as Record<string, unknown>;
+  return policy.type === "readOnly" && Object.keys(policy).every(key => key === "type" || key === "networkAccess")
+    && (!Object.hasOwn(policy, "networkAccess") || typeof policy.networkAccess === "boolean");
+}
 
 /** A counter Codex reported: a finite non-negative number, otherwise 0 (an absent kind is not a negative delta). */
 const counter = (value: unknown): number => { const n = Number(value); return Number.isFinite(n) && n >= 0 ? n : 0; };
@@ -16,6 +25,8 @@ export interface CodexOptions {
   /** Port the TUI attaches to: `codex --enable tui_app_server --remote ws://127.0.0.1:<proxyPort>`. */
   proxyPort: number;
   permissionMode?: PermissionMode;
+  /** Live host planner ceiling on initial thread start/resume; the attached person may change later turn policy. */
+  threadSandbox?: "read-only" | (() => "read-only" | "unavailable" | undefined);
   /** Host-only always-ask gate, shared with ACP; an absent verdict preserves native handling. */
   actionGate?: (call: { names: readonly string[]; kind?: string; input: unknown }, session: string) => ActionGateVerdict | undefined;
   onPermission?: (request: PermissionRequest, signal?: AbortSignal) => Promise<string | undefined>;
@@ -71,6 +82,10 @@ interface Link {
   backlog: string[]; // TUI frames that arrived before the upstream socket opened
   approvalIds: Set<string | number>; // intercepted native ids stay tombstoned for this socket lifetime
   tracked: Map<string | number, string>; // request id -> method, for thread/start and thread/resume
+  /** Correlated native initial policy, retained even before this instance gains the planner role. */
+  readOnlyThread?: string;
+  /** An ordinary client reused an outstanding id; this link cannot attest a planner thread until reattach. */
+  ambiguousThreadRpc?: true;
 }
 
 const TRACKED = new Set(["thread/start", "thread/resume"]);
@@ -233,7 +248,7 @@ export class CodexPeer extends BasePeer {
   /** Resolves when app-server accepts the turn. Only called while idle, i.e. a thread exists and no turn runs. */
   deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
     const link = this.link;
-    if (this.state !== "idle" || !link || link.up.readyState !== WebSocket.OPEN) {
+    if (this.state !== "idle" || !link || link.up.readyState !== WebSocket.OPEN || !this.threadSandboxReady(link)) {
       if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} is not injectable` });
       return Promise.reject(new Error(`${this.id} is not injectable`));
     }
@@ -285,6 +300,10 @@ export class CodexPeer extends BasePeer {
           reject(e);
         },
       });
+      if (!this.threadSandboxReady(link)) {
+        const pending = this.pending.get(id); this.pending.delete(id);
+        pending?.reject(new Error(`${this.id} is not injectable`)); return;
+      }
       link.up.send(
         JSON.stringify({ method: "turn/start", id, params: this.applyPermissionPolicy({ threadId: this.threadId, input: [{ type: "text", text }] }, id) }),
       );
@@ -299,7 +318,7 @@ export class CodexPeer extends BasePeer {
   steer(envs: Envelope[], deliveryId?: string): Promise<void> {
     const link = this.link;
     const expectedTurnId = [...this.activeTurns].reverse().find((t) => !t.startsWith("unknown:"));
-    if (!link || link.up.readyState !== WebSocket.OPEN || !expectedTurnId) {
+    if (!link || link.up.readyState !== WebSocket.OPEN || !expectedTurnId || !this.threadSandboxReady(link)) {
       if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} has no steerable turn` });
       return Promise.reject(new Error(`${this.id} has no steerable turn`));
     }
@@ -346,6 +365,10 @@ export class CodexPeer extends BasePeer {
         reject: fail,
       });
       const input = [{ type: "text", text: this.render(envs) }];
+      if (!this.threadSandboxReady(link)) {
+        const pending = this.pending.get(id); this.pending.delete(id);
+        pending?.reject(new Error(`${this.id} is not injectable`)); return;
+      }
       link.up.send(JSON.stringify({ method: "turn/steer", id, params: { threadId: this.threadId, expectedTurnId, input } }));
     });
   }
@@ -358,12 +381,16 @@ export class CodexPeer extends BasePeer {
   steerText(text: string): Promise<"accepted" | "refused" | "unanswered"> {
     const link = this.link;
     const expectedTurnId = [...this.activeTurns].reverse().find((t) => !t.startsWith("unknown:"));
-    if (!link || link.up.readyState !== WebSocket.OPEN || !expectedTurnId) return Promise.resolve("refused");
+    if (!link || link.up.readyState !== WebSocket.OPEN || !expectedTurnId || !this.threadSandboxReady(link)) return Promise.resolve("refused");
     const id = this.nextId--;
     return new Promise((resolve) => {
       const timer = setTimeout(() => this.pending.delete(id) && resolve("unanswered"), this.opts.steerTimeoutMs ?? 10_000);
       timer.unref?.();
       this.pending.set(id, { resolve: () => (clearTimeout(timer), resolve("accepted")), reject: () => (clearTimeout(timer), resolve("refused")) });
+      if (!this.threadSandboxReady(link)) {
+        const pending = this.pending.get(id); this.pending.delete(id);
+        pending?.reject(new Error(`${this.id} is not injectable`)); return;
+      }
       link.up.send(JSON.stringify({ method: "turn/steer", id, params: { threadId: this.threadId, expectedTurnId, input: [{ type: "text", text }] } }));
     });
   }
@@ -483,6 +510,7 @@ export class CodexPeer extends BasePeer {
     this.link = undefined;
     this.restoringApprovals.clear();
     this.threadId = "";
+    this.onDoing?.("reset");
     this.contextEpoch++;
     this.deliveryEpoch++;
     this.retiredTurns.clear(); this.unidentifiedCancellation = false;
@@ -560,6 +588,9 @@ export class CodexPeer extends BasePeer {
   private fromTui(link: Link, raw: string): void {
     const msg = parse(raw);
     if (msg?.id !== undefined && !msg.method && link.approvalIds.has(msg.id)) return;
+    const sandbox = this.threadSandboxPolicy();
+    const threadRequest = TRACKED.has(msg?.method), turnRequest = msg?.method === "turn/start" || msg?.method === "turn/steer";
+    if (sandbox === "unavailable" && (threadRequest || turnRequest) || sandbox === "read-only" && turnRequest && (link !== this.link || link.tracked.size > 0 || link.readOnlyThread !== this.threadId)) return this.refusePlannerThread(link, msg.id);
     if (msg?.method === "turn/interrupt" && link === this.link) this.abortActionWaits(link, typeof msg.params?.turnId === "string" ? msg.params.turnId : undefined);
     if (msg?.method === "turn/start" && msg.params && link === this.link) {
       const thread = typeof msg.params.threadId === "string" ? msg.params.threadId : this.threadId;
@@ -572,7 +603,15 @@ export class CodexPeer extends BasePeer {
         raw = JSON.stringify(msg);
       }
     }
-    if (msg?.id !== undefined && TRACKED.has(msg.method)) link.tracked.set(msg.id, msg.method);
+    if (msg?.id !== undefined && TRACKED.has(msg.method)) {
+      if (link.tracked.has(msg.id)) link.ambiguousThreadRpc = true;
+      if (sandbox === "read-only") {
+        if (link.ambiguousThreadRpc || msg.params !== undefined && (!msg.params || typeof msg.params !== "object" || Array.isArray(msg.params))) return this.refusePlannerThread(link, msg.id);
+        msg.params = { ...msg.params, sandbox: "read-only" };
+        raw = JSON.stringify(msg);
+      }
+      link.tracked.set(msg.id, msg.method);
+    }
     if (link.up.readyState === WebSocket.OPEN) link.up.send(raw);
     else link.backlog.push(raw);
   }
@@ -595,7 +634,11 @@ export class CodexPeer extends BasePeer {
     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)) {
+      const sandbox = this.threadSandboxPolicy();
+      const readOnly = !link.ambiguousThreadRpc && msg.error === undefined && typeof msg.result?.thread?.id === "string" && !!msg.result.thread.id && confirmsReadOnlySandbox(msg.result?.sandbox);
+      if (sandbox === "unavailable" || sandbox === "read-only" && !readOnly) return this.refusePlannerThread(link, msg.id);
       if (typeof msg.result?.thread?.id === "string") {
+        link.readOnlyThread = readOnly ? msg.result.thread.id : undefined;
         // 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);
@@ -606,6 +649,32 @@ export class CodexPeer extends BasePeer {
     link.tui.send(raw);
   }
 
+  private threadSandboxPolicy(): "read-only" | "unavailable" | undefined {
+    try {
+      const value = typeof this.opts.threadSandbox === "function" ? this.opts.threadSandbox() : this.opts.threadSandbox;
+      return value === undefined || value === "read-only" ? value : "unavailable";
+    } catch { return "unavailable"; }
+  }
+
+  /** Role changes never turn an ordinary writable/unknown thread into a proved planner thread. */
+  private threadSandboxReady(link: Link): boolean {
+    const sandbox = this.threadSandboxPolicy();
+    if (sandbox === "unavailable") { this.refusePlannerThread(link, undefined); return false; }
+    if (sandbox === "read-only") {
+      if (link.tracked.size > 0) return false;
+      if (link !== this.link || link.readOnlyThread !== this.threadId) { this.refusePlannerThread(link, undefined); return false; }
+    }
+    return true;
+  }
+
+  /** Refuse before adoption or another host delivery, including while a previous thread was idle. */
+  private refusePlannerThread(link: Link, id: unknown): void {
+    if (link.tui.readyState === WebSocket.OPEN && (typeof id === "string" || typeof id === "number")) link.tui.send(JSON.stringify({ id, error: { code: -32000, message: PLANNER_SANDBOX_REFUSAL } }));
+    link.tracked.clear();
+    this.detach(link);
+    link.tui.close(1008, PLANNER_SANDBOX_REFUSAL);
+  }
+
   private abortActionWaits(link?: Link, turn?: string): void {
     for (const [controller, wait] of this.actionWaits) if ((!link || wait.link === link) && (!turn || wait.turn === turn)) controller.abort();
   }
@@ -673,6 +742,7 @@ export class CodexPeer extends BasePeer {
     this.freshThread = fresh;
     this.link = link;
     this.threadId = threadId;
+    this.onDoing?.("reset");
     this.contextEpoch++;
     this.deliveryEpoch++;
     this.retiredTurns.clear(); this.unidentifiedCancellation = false;
@@ -722,6 +792,9 @@ export class CodexPeer extends BasePeer {
       this.opts.onUsage?.({ rateLimitReachedType: "usageLimitExceeded" }, true);
     }
     if (link !== this.link || params.threadId !== this.threadId) return;
+    // #878: the bound thread's name and its plan's in-progress step, for the hub's DOING column only.
+    if (method === "thread/name/updated") return void this.onDoing?.("title", params.threadName);
+    if (method === "turn/plan/updated") return void this.onDoing?.("todo", Array.isArray(params.plan) ? params.plan.find((s: any) => s?.status === "inProgress")?.step : undefined);
     const nativeId = method === "turn/started" || method === "turn/completed" ? params.turn?.id : params.turnId;
     if (typeof nativeId === "string" && this.retiredTurns.has(nativeId)) {
       if (method === "turn/completed") this.retiredTurns.delete(nativeId);

package/src/adapters/conformance/fakes/jcode-agent.ts

@@ -1,6 +1,6 @@
 import { createServer } from "node:net";
 import { basename, dirname, join } from "node:path";
-import { writeSync, appendFileSync, mkdirSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { writeSync, appendFileSync, mkdirSync, writeFileSync, existsSync, readFileSync, rmSync } from "node:fs";
 import { createInterface } from "node:readline";
 const args = process.argv.slice(2), value = (key: string) => args[args.indexOf(key) + 1];
 const record = args.includes("--record") ? value("--record") : undefined;
@@ -76,7 +76,11 @@ if (args.includes("version")) {
       }
       const finish = () => {
         send({ jsonrpc: "2.0", method: "session/update", params: { sessionId: session, update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "JCODE_REPLY" } } } });
-        send({ jsonrpc: "2.0", id: msg.id, result: { stopReason: args.includes("--max-tokens-stop") ? "max_tokens" : "end_turn" } });
+        // `--usage-script F`: the 0.99.1 shapes, as probed (docs/verification/2026-10-28-jcode-0.99.1-usage.md). F is a JSON object `{ updates: [...], usage: {...} | null, sessionId?: string }`:
+        // each `updates` entry becomes a `usage_update` notification (for `sessionId` when given, else this session), and `usage` is the prompt result's `usage` member (absent when null).
+        const script = args.includes("--usage-script") && existsSync(value("--usage-script")!) ? JSON.parse(readFileSync(value("--usage-script")!, "utf8")) : undefined;
+        for (const update of script?.updates ?? []) send({ jsonrpc: "2.0", method: "session/update", params: { sessionId: script.sessionId ?? session, update: { sessionUpdate: "usage_update", ...update } } });
+        send({ jsonrpc: "2.0", id: msg.id, result: { stopReason: args.includes("--max-tokens-stop") ? "max_tokens" : "end_turn", ...(script?.usage ? { usage: script.usage } : {}) } });
         if (args.includes("--exit-after-prompt")) setTimeout(() => process.exit(0), 30);
       };
       const steerFile = args.includes("--steer-file") ? value("--steer-file")! : undefined;