@staix/agent-hub 0.13.0 → 0.15.0

package/src/adapters/codex-review-isolation.ts

@@ -8,7 +8,7 @@ import { homedir, tmpdir } from "node:os";
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { realPath } from "../hub/project.ts";
-import type { ReviewerBackend, ReviewerLaunch, ReviewerPrepareContext } from "./reviewer-print.ts";
+import type { ReviewerBackend, ReviewerCauseClass, ReviewerLaunch, ReviewerPrepareContext } from "./reviewer-print.ts";
 
 const TOOLS = ["hub_review", "hub_task_show"];
 /** A version refusal names only versions and a command, so the daemon may show it (#691). */
@@ -176,8 +176,10 @@ function ownServer(text: string): Record<string, unknown> {
 }
 
 /** All reads are model-free and bounded; stdout/config/env values never become diagnostic text. */
-async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string }> {
+async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string; causeClass?: ReviewerCauseClass; detail?: string }> {
   let root: string | undefined;
+  // #722: the proof leg being run, so a refusal names a class and never text from the native CLI. `timedOut` is set by `run` only.
+  let leg: ReviewerCauseClass = "binary", timedOut = false;
   try {
     const cwd = realPath(ctx.cwd), env = peerChildEnv(ctx.peer), bound = resolveCommand(ctx, cwd);
     const initialBinaryMetadata = bound.files.map(metadata).join(";");
@@ -191,12 +193,12 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
       return bound.files.map(metadata).join(";") === initialBinaryMetadata;
     };
     const run = (args: readonly string[], capture = true, maxBytes = CAP) => new Promise<string>((resolveOutput, reject) => {
-      if (ctx.signal.aborted || performance.now() >= deadline) { reject(new Error("metadata deadline")); return; }
+      if (ctx.signal.aborted || performance.now() >= deadline) { if (!ctx.signal.aborted) timedOut = true; reject(new Error("metadata deadline")); return; }
       const [cmd, ...prefix] = bound.command;
       const child = spawn(cmd!, [...prefix, ...args], { cwd, env, detached: true, stdio: ["ignore", "pipe", "pipe"] });
       let output = "", bytes = 0, failed = false, settled = false;
       const stop = () => { failed = true; void finish(null); };
-      const timer = setTimeout(stop, Math.max(1, Math.min(2000, deadline - performance.now())));
+      const timer = setTimeout(() => { if (!ctx.signal.aborted) timedOut = true; stop(); }, Math.max(1, Math.min(2000, deadline - performance.now())));
       ctx.signal.addEventListener("abort", stop, { once: true });
       const finish = async (code: number | null) => {
         if (settled) return; settled = true; clearTimeout(timer); ctx.signal.removeEventListener("abort", stop);
@@ -211,14 +213,18 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
       child.once("close", code => { void finish(code); });
     });
     // #691: the verified versions and the person's trust live in compat.ts; every proof below still runs after trust.
+    leg = "version";
     const verdict = assessVersion("codex-review", COMPAT["codex-review"].parse(await run(["--version"])));
     if (!verdict.ok) throw new VersionRefusal(verdict.reason);
     const version = verdict.version;
+    leg = "mcp_inventory";
     if (Buffer.byteLength(ctx.mcpConfig) > CAP || ctx.privatePaths.length > 128) throw new Error("policy bounds exceeded");
     const hub = ownServer(ctx.mcpConfig);
     // Apps creates a runtime MCP server outside the configured inventory; independently pin and read back its gate.
     const policy = ["-c", "notify=[]", "--disable", "plugins", "--disable", "hooks", "--disable", "apps", "-c", 'web_search="disabled"', "-c", `projects=${toml({ [cwd]: { trust_level: "untrusted" } })}`];
+    leg = "plugins_hooks_apps";
     proveDisabledFeatures(await run(["features", "list", ...policy]));
+    leg = "mcp_inventory";
     const before = inventory(await run(["mcp", "list", "--json", ...policy]));
     if (before.some(row => row.name === "agent-hub")) throw new Error("ambient hub MCP collision");
     const servers: Record<string, unknown> = Object.assign(Object.create(null), { "agent-hub": hub });
@@ -232,6 +238,7 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
     const observedEnv = object(observedTransport.env ?? {}), intendedEnv = object(hub.env);
     if (observedTransport.type !== "stdio" || observedTransport.command !== hub.command || JSON.stringify(observedTransport.args ?? []) !== JSON.stringify(hub.args) || Object.keys(observedEnv).length !== Object.keys(intendedEnv).length || Object.entries(intendedEnv).some(([key, value]) => observedEnv[key] !== value)) throw new Error("hub transport changed");
     // A real native sandbox probes a fresh private fixture: the model never sees these files.
+    leg = "sandbox_proof";
     root = realPath(mkdtempSync(join(tmpdir(), "ahub-codex-review-isolation-")));
     const privateFile = join(root, "private.env"), publicFile = join(root, "public.txt"), writeFile = join(root, "write-proof");
     const coreName = join(root, ".env"), coreStateDir = join(root, ".agenthub", "state"), coreState = join(coreStateDir, "private.txt");
@@ -245,8 +252,10 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
     writeFileSync(privateFile, "private fixture"); writeFileSync(publicFile, "public fixture"); writeFileSync(globFile, "glob private fixture");
     symlinkSync(globFile, alias);
     const filesystem: Record<string, string> = { "/": "read", [privateFile]: "deny", [join(globRoot, "**", "*.env")]: "deny" };
+    leg = "credential_root";
     for (const glob of codexCoreDenyGlobs()) filesystem[glob] = "deny";
     denyCredentialRoots(filesystem, [...hostCredentialRoots(env, cwd), ...hostCredentialRoots({ HOME: fixtureHome }, cwd)], cwd);
+    leg = "sandbox_proof";
     for (const entry of ctx.privatePaths) {
       if (typeof entry !== "string" || !entry || Buffer.byteLength(entry) > 4096 || /\p{Cc}/u.test(entry)) throw new Error("invalid private path policy");
       // Native Seatbelt supports *, ?, and closed character classes, not brace alternatives.
@@ -268,6 +277,7 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
     const script = 'if /bin/cat "$1" >/dev/null 2>&1; then echo AHUB_CODEX_PUBLIC_READ; fi; if /bin/cat "$2" >/dev/null 2>&1; then exit 12; else echo AHUB_CODEX_PRIVATE_DENIED; fi; if (echo no > "$3") 2>/dev/null; then exit 13; else echo AHUB_CODEX_WRITE_DENIED; fi; if /bin/cat "$4" >/dev/null 2>&1; then exit 14; else echo AHUB_CODEX_GLOB_PRIVATE_DENIED; fi; if /bin/cat "$5" >/dev/null 2>&1; then exit 15; else echo AHUB_CODEX_ALIAS_PRIVATE_DENIED; fi; if /bin/cat "$6" >/dev/null 2>&1; then exit 16; else echo AHUB_CODEX_CORE_NAME_DENIED; fi; if /bin/cat "$7" >/dev/null 2>&1; then exit 17; else echo AHUB_CODEX_CORE_STATE_DENIED; fi; if /bin/cat "$8" >/dev/null 2>&1; then exit 18; else echo AHUB_CODEX_HOST_CONFIG_DENIED; fi; if /bin/cat "$9" >/dev/null 2>&1; then exit 19; else echo AHUB_CODEX_HOST_KUBE_DENIED; fi; if /bin/cat "${10}" >/dev/null 2>&1; then exit 20; else echo AHUB_CODEX_HOST_DOCKER_DENIED; fi; if /bin/cat "${11}" >/dev/null 2>&1; then exit 21; else echo AHUB_CODEX_HOST_ALIAS_DENIED; fi';
     const proof = await run(["sandbox", "-P", "ahub-review", "-C", cwd, ...policy, ...permissions, "/bin/sh", "-c", script, "proof", publicFile, privateFile, writeFile, globFile, alias, coreName, coreState, hostConfig, hostKube, hostDocker, hostAlias]);
     if (proof.trim() !== "AHUB_CODEX_PUBLIC_READ\nAHUB_CODEX_PRIVATE_DENIED\nAHUB_CODEX_WRITE_DENIED\nAHUB_CODEX_GLOB_PRIVATE_DENIED\nAHUB_CODEX_ALIAS_PRIVATE_DENIED\nAHUB_CODEX_CORE_NAME_DENIED\nAHUB_CODEX_CORE_STATE_DENIED\nAHUB_CODEX_HOST_CONFIG_DENIED\nAHUB_CODEX_HOST_KUBE_DENIED\nAHUB_CODEX_HOST_DOCKER_DENIED\nAHUB_CODEX_HOST_ALIAS_DENIED" || existsSync(writeFile)) throw new Error("native sandbox isolation unverified");
+    leg = "binary";
     if (!current()) throw new Error("binary or config changed during proof");
     const cleanupRoot = root;
     const launchProfile = digest(toml({ profile, servers, policy }));
@@ -279,12 +289,13 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
   } catch (error) {
     if (root) { try { rmSync(root, { recursive: true, force: true }); } catch { /* unavailable remains refused */ } }
     // Name only the path class of an unusable credential root so a stale ~/.docker link is fixable; never a path or contents.
-    if (error instanceof VersionRefusal) return { unavailable: error.message };
+    if (error instanceof VersionRefusal) return { unavailable: error.message, causeClass: "version" };
     if (error instanceof CredentialRootError) {
       const why = { dangling: "a dangling link", unreadable: "an unreadable path", unsupported: "unsupported syntax or overlapping the checkout" }[error.kind];
-      return { unavailable: `Codex reviewer isolation receipt unavailable (credential root ${error.label} is ${why}; remove or repair it)` };
+      return { unavailable: `Codex reviewer isolation receipt unavailable (credential root ${error.label} is ${why}; remove or repair it)`, causeClass: "credential_root", detail: `${error.label}: ${why}` };
     }
-    return { unavailable: "Codex reviewer isolation receipt unavailable (version, MCP inventory, sandbox, configuration or process proof)" };
+    // A timeout is a proof command that ran out of time, whichever leg it was on; every other refusal names the leg that was running.
+    return { unavailable: "Codex reviewer isolation receipt unavailable (version, MCP inventory, sandbox, configuration or process proof)", causeClass: timedOut ? "timeout" : leg };
   }
 }
 

package/src/adapters/compat.ts

@@ -27,6 +27,10 @@ export interface CompatPolicy {
 
 const plain = (text: string) => text.length <= 64 && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(text) ? text : undefined;
 export const COMPAT = {
+  // Receipt: docs/verification/2026-10-23-headless-claude-permissions.md
+  "claude-implementer": { label: "Claude headless implementer", verified: ["2.1.309"], gate: "contract", probe: ["claude", "--version"],
+    parse: out => plain(out.trim().replace(/ \(Claude Code\)$/, "")),
+    trustNote: "The native prompt-tool allow, deny, MCP error/disconnect and hook-failure fallthrough have an isolated receipt. No dontAsk/bypass fallback exists; another version's permission behavior is unverified." },
   // 0.163.0 receipt: docs/verification/2026-10-22-codex-reviewer-isolation.md
   "codex-review": { label: "Codex reviewer (codex-cli)", verified: ["0.146.0", "0.163.0"], gate: "isolation", probe: ["codex", "--version"], config: "codex_bin",
     parse: out => plain(out.trim().replace(/^codex-cli /, "")),

package/src/adapters/conformance/enrollment.ts

@@ -20,7 +20,8 @@ export function assertAcpLegEnrollment(definitions: readonly AdapterDefinition[]
 }
 export function definitionIdentities(definitions: readonly AdapterDefinition[]): { id: string; definition: AdapterDefinition }[] {
   return definitions.flatMap(definition => [{ id: definition.kind, definition },
-    ...(definition.reviewerVariant ? [{ id: `${definition.kind}:reviewer`, definition: definition.reviewerVariant }] : [])]);
+    ...(definition.reviewerVariant ? [{ id: `${definition.kind}:reviewer`, definition: definition.reviewerVariant }] : []),
+    ...(definition.headlessVariant ? [{ id: `${definition.kind}:implementer`, definition: definition.headlessVariant }] : [])]);
 }
 export function assertEnrollment(definitions: readonly AdapterDefinition[], enrolled: readonly string[], unsupported: Readonly<Record<string, string>>, unsupportedLegs: Readonly<Record<string, string>> = {}, coherence?: (definition: AdapterDefinition) => void): void {
   assertAcpLegEnrollment(definitions, unsupportedLegs);

package/src/adapters/conformance/fakes/acp-server.ts

@@ -103,7 +103,9 @@ async function prompt(id: number, text: string) {
   if (text.includes("PERMISSION")) {
     // Kimi 2.0.1's shape: the arguments travel on the tool_call update, the permission request has none.
     const announced = text.includes("ANNOUNCED");
-    if (announced) send({ jsonrpc: "2.0", method: "session/update", params: { sessionId: "s1", update: { sessionUpdate: "tool_call", toolCallId: "tc1", title: "Bash", status: "pending", rawInput: "rm -rf build && make" } } });
+    // `ACTIONCMD[<command>]` (#636) replaces the announced command, so a test can send a classed or an unclassed shell call.
+    const actionCommand = text.match(/ACTIONCMD\[([^\]]+)\]/)?.[1];
+    if (announced) send({ jsonrpc: "2.0", method: "session/update", params: { sessionId: "s1", update: { sessionUpdate: "tool_call", toolCallId: "tc1", title: "Bash", status: "pending", rawInput: actionCommand ? { command: actionCommand } : "rm -rf build && make" } } });
     // Kimi 2.1.1's shape (captured 2026-09-30, issue #72): no rawInput before the answer; the argument JSON
     // streams as content text on tool_call_update, cumulatively, and the request itself carries none.
     const tool = text.includes("HUBTOOL") || text.includes("NOONCE") ? "mcp__agent-hub__hub_task_list" : text.includes("SPOOF") ? "mcp__agent-hub__rm_rf" : "Bash";

package/src/adapters/definitions/builtin-metadata.ts

@@ -19,7 +19,7 @@ import { piRecoveryContinuity } from "./native-recovery-continuity.ts";
 import { piConductorStartArgs } from "./native-cli-pi.ts";
 import { claudeNativeLaunch, CLAUDE_LAUNCH_POLICY } from "./native-cli-claude-launch.ts";
 import { codexNativeLaunch, CODEX_LAUNCH_POLICY } from "./native-cli-codex-launch.ts";
-import { createCodex, createKimi, createJcode, createPi, createLocal, createClaudeReviewer } from "./native-factories.ts";
+import { createCodex, createKimi, createJcode, createPi, createLocal, createClaudeReviewer, createClaudeImplementer } from "./native-factories.ts";
 import { CLAUDE_DISPLAY, CODEX_DISPLAY, KIMI_DISPLAY, PI_DISPLAY, LOCAL_DISPLAY, JCODE_DISPLAY } from "./native-display.ts";
 import { CLAUDE_RECOVERY_SESSION, CODEX_RECOVERY_SESSION, KIMI_RECOVERY_SESSION, PI_RECOVERY_SESSION, LOCAL_RECOVERY_SESSION, JCODE_RECOVERY_SESSION } from "./native-recovery.ts";
 import { claudeWindows, codexWindows } from "./native-quota.ts";
@@ -80,6 +80,18 @@ const CLAUDE_REVIEWER_VARIANT: AdapterDefinition = {
   cli: { command: "claude", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY,
 };
 
+/** #525 R5a: no idle child; the host binds an owned worktree and one native session per task. */
+const CLAUDE_IMPLEMENTER_VARIANT: AdapterDefinition = {
+  api: 1, kind: "claude", displayName: "Claude Code implementer", family: "claude", transport: "hub-native",
+  roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
+  start: { create: createClaudeImplementer, daemonPort: "claude-implementer", forms: headlessForms, defaultForm: "headless", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+  identity: { mcp: "env", currentChild: true }, instances: { mode: "headless", roles: ["implementer", "verifier"] },
+  permission: { grants: { ask: "every write, edit and shell command asks", "ask-when-needed": "file tools inside the owned worktree may run automatically; shell and protected paths ask" } },
+  session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: false, launchKind: "claude-implementer", crashPlan: () => ({ resume: {}, how: "Claude implementer resumes its recorded per-task sessions" }) },
+  turnEnd: "adapter", budget: { account: "claude" },
+  cli: { command: "claude", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY,
+};
+
 // Sources: peer-catalog.ts roles, roster.ts defaults, start-mode.ts forms, permission-mode.ts grants,
 // daemon.ts runtime mappings/stop policy, budget.ts exemptions, and ui/peer-palette.ts CSS foregrounds.
 export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Object.freeze([
@@ -89,7 +101,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     roles: Object.freeze(["planner", "reviewer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
     start: { forms: Object.freeze(["tui"] as const), defaultForm: "tui", launch: claudeNativeLaunch, version: claudeObservedVersion, ...CLAUDE_LAUNCH_POLICY, conductorStartable: true,
       unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--dangerously-load-development-channels", "--dangerously-skip-permissions"]) },
-    identity: { mcp: "channel-plugin" }, instances: { mode: "external", roles: ["reviewer", "planner"] }, attach: { externalHello: true, recoveryLaunch: claudeRecoveryLaunch },
+    identity: { mcp: "channel-plugin" }, instances: { mode: "external", roles: ["planner", "implementer", "verifier", "reviewer"] }, attach: { externalHello: true, recoveryLaunch: claudeRecoveryLaunch },
     // Approval enforcement belongs to the verified native transport and host permission gate.
     permission: { grants: { ask: "Claude's own permission rules decide",
       "ask-when-needed": "file tools on project files run without asking, outside .agenthub, .git and agent configuration; other tools keep Claude's own rules",
@@ -97,7 +109,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     session: { idField: "sessionId", currentId: sessionId("sessionId"), configDirEnv: "CLAUDE_CONFIG_DIR", zeroTurnFresh: true, launchKind: "claude-channel", launchRecord: true, ...CLAUDE_RECOVERY_SESSION, crashPlan: claudeCrashPlan, unrecordedTerminal: "always" },
     turnEnd: "native-hook", budget: { account: "claude", checkpoint: true, reader: { source: "claude status line", read: claudeWindows }, context: { source: "claude_statusline", read: claudeContext } },
     cli: { command: "claude", entry: { lifecycleAdmission: true, execute: runClaudeEntry }, preview: previewClaude, usage: [["ahub claude [--print-command] [--unattended] [args...]", "launch Claude Code with the hub channel"]], retainedTerminalNotice: claudeRetainedTerminalNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY, hooks: { recallPlatform: "claude", recallSource: "claude", recallInjected: true, pluginInventory: claudePluginInventory },
-    reviewerVariant: CLAUDE_REVIEWER_VARIANT,
+    reviewerVariant: CLAUDE_REVIEWER_VARIANT, headlessVariant: CLAUDE_IMPLEMENTER_VARIANT,
   },
   {
     reviewerVariant: CODEX_REVIEWER_VARIANT,

package/src/adapters/definitions/native-channel-state.ts

@@ -10,7 +10,7 @@ export function claudePeer(value: string | undefined): string {
 const CLAUDE_PEER = /^claude(?:-[a-z0-9-]+)?$/;
 
 /** Per-peer Claude state file names. The builtin claude peer keeps its original names, so nothing migrates. */
-export function claudeStateFile(base: "claude-launch" | "claude-session" | "claude-context", peer: string): string {
+export function claudeStateFile(base: "claude-launch" | "claude-session" | "claude-context" | "claude-task-sessions", peer: string): string {
   // #624: another kind (agy is a hyphen-free builtin too) must never resolve to Claude's own files.
   if (!CLAUDE_PEER.test(peer) || !PEER.test(peer)) throw new Error(`${peer} is not a Claude peer; Claude state files belong to Claude peers only`);
   return peer.includes("-") ? `${base}.${peer}.json` : `${base}.json`;

package/src/adapters/definitions/native-cli-entry-claude.ts

@@ -8,11 +8,14 @@ import { claudeStateFile } from "../../hub/claude-state.ts";
 
 export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void> {
   const { args, cwd, stateDir, cliDir, unattendedEnv, projectConfig, fail } = ctx;
-  // #450 I3: a claude-<name> instance keeps its own identity, launch and recovery records; it never owns a worktree.
+  // Each terminal instance keeps its canonical hub identity and its separately validated execution root.
   const peer = ctx.instance ?? "claude";
   if (ctx.hubStarted) {
-    // #223: the hub starts a headless reviewer and runs one `claude -p` per review; nothing runs in this terminal.
-    if (args.includes("--print-command") || args.includes("--dry-run")) return console.log(JSON.stringify({ peer, start: "hub", note: "a headless reviewer the hub runs per review" }, null, 2));
+    // Both builtin headless variants are hub-owned; nothing runs in this terminal.
+    const declaration = ctx.instance ? projectConfig().instances?.[ctx.instance] : undefined;
+    const writer = declaration?.roles?.includes("implementer") && declaration.start_mode === "headless";
+    const description = writer ? "a headless implementer the hub runs per task" : "a headless reviewer the hub runs per review";
+    if (args.includes("--print-command") || args.includes("--dry-run")) return console.log(JSON.stringify({ peer, start: "hub", note: description }, null, 2));
     const hub = await ctx.connect();
     try {
       const snapshot = (await hub.request({ t: "status" })).status;
@@ -20,17 +23,19 @@ export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void>
       const res = await hub.request({ t: "start", peer, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
       if (res.ok !== true) fail(String(res.error ?? `${peer} was not started`));
     } finally { hub.close(); }
-    return console.log(`${peer} started: a headless reviewer the hub runs per review (stop it with ahub stop ${peer})`);
+    return console.log(`${peer} started: ${description} (stop it with ahub stop ${peer})`);
   }
   const { launcherPreview, readControl, prepareTerminalLaunch, registerTerminalLaunch, claudeObservationHooks, buildLaunch, runClaudeLaunch, processSignature, recordClaudeLaunch, cleanupStaleClaudeSettings, nativeLaunchEnv, childEnv, cleanupClaudeSettings } = ctx.helpers;
   if (args.includes("--print-command") || args.includes("--dry-run")) {
     try { return console.log(JSON.stringify(launcherPreview("claude", args, cwd, stateDir, unattendedEnv), null, 2)); }
     catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
   }
+  const executionCwd = ctx.instance ? ctx.helpers.resolveExecutionCwd(peer) : cwd;
+  ctx.executionCwd = executionCwd;
   const control = readControl(stateDir);
   if (control?.instanceId) {
     process.env.AGENTHUB_INSTANCE_ID = control.instanceId;
-    const terminal = await prepareTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd: cwd } : undefined);
+    const terminal = await prepareTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd } : undefined);
     if (!terminal) process.env.AGENTHUB_LAUNCH_ID = randomUUID();
     else {
       const hub = await ctx.connect();
@@ -41,7 +46,7 @@ export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void>
   // `--settings` outranks project and user settings, so the tee has to wrap whichever status line would have won:
   // project local, then project, then user.
   let original: { command?: string; refreshInterval?: number; padding?: number } | undefined;
-  for (const file of [join(cwd, ".claude", "settings.local.json"), join(cwd, ".claude", "settings.json"), join(process.env.HOME ?? "", ".claude", "settings.json")]) {
+  for (const file of [join(executionCwd, ".claude", "settings.local.json"), join(executionCwd, ".claude", "settings.json"), join(process.env.HOME ?? "", ".claude", "settings.json")]) {
     try {
       original ??= JSON.parse(readFileSync(file, "utf8")).statusLine;
     } catch {
@@ -58,14 +63,14 @@ export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void>
     let launchRecord: ClaudeLaunchRecord | undefined;
     if (control?.instanceId) {
       // Publish only the final launch's installed hook and effective permission flags.
-      launchRecord = { ...(ctx.instance ? { peer } : {}), instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID!, permissionHook: launch.permissionHook === true, hookPurpose: launch.hookPurpose, settingsFile: launch.settingsFile, launcherPid: process.pid, launcherSignature: processSignature(process.pid), unattended: launch.unattended === true };
+      launchRecord = { ...(ctx.instance ? { peer, executionCwd } : {}), instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID!, permissionHook: launch.permissionHook === true, hookPurpose: launch.hookPurpose, settingsFile: launch.settingsFile, launcherPid: process.pid, launcherSignature: processSignature(process.pid), unattended: launch.unattended === true };
       recordClaudeLaunch(stateDir, launchRecord);
       cleanupStaleClaudeSettings(stateDir, previousLaunch);
     }
     if (launch.warning) console.error(launch.warning);
     const env = nativeLaunchEnv("claude", childEnv());
     if (ctx.instance) env.AGENTHUB_PEER_ID = peer; // the channel plugin and the statusline tee write for this instance
-    result = await runClaudeLaunch(launch, { cwd, stateDir, env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd }, ...(launchRecord ? { record: launchRecord } : {}) });
+    result = await runClaudeLaunch(launch, { cwd: executionCwd, stateDir, env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd }, ...(launchRecord ? { record: launchRecord } : {}) });
   } finally {
     cleanupClaudeSettings(stateDir, launch.settingsFile);
   }

package/src/adapters/definitions/native-cli-entry-codex.ts

@@ -5,6 +5,19 @@ export async function runCodexEntry(ctx: NativeCliEntryContext): Promise<void> {
   const peer = ctx.instance ?? "codex";
   const { args, cwd, stateDir, unattendedEnv, projectConfig, connect, fail, exec } = ctx;
   const { launcherPreview, buildLaunch, readControl, prepareTerminalLaunch, registerTerminalLaunch } = ctx.helpers;
+  if (ctx.hubStarted) {
+    // #720: the hub starts a headless reviewer (a fresh Codex per review); nothing runs in this terminal, so there is no TUI launch,
+    // no terminal recovery and no exec. Launch arguments were already refused by instanceLaunchArguments.
+    if (args.includes("--print-command") || args.includes("--dry-run")) return console.log(JSON.stringify({ peer, start: "hub", note: "a headless reviewer the hub runs per review" }, null, 2));
+    const hub = await connect();
+    try {
+      const snapshot = (await hub.request({ t: "status" })).status;
+      const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
+      const res = await hub.request({ t: "start", peer, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+      if (res.ok !== true) fail(String(res.error ?? `${peer} was not started`));
+    } finally { hub.close(); }
+    return console.log(`${peer} started: a headless reviewer the hub runs per review (stop it with ahub stop ${peer})`);
+  }
   if (args.includes("--print-command") || args.includes("--dry-run")) {
     try { return console.log(JSON.stringify(launcherPreview("codex", args, cwd, stateDir, unattendedEnv), null, 2)); }
     catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }

package/src/adapters/definitions/native-cli-entry-types.ts

@@ -16,6 +16,8 @@ export interface NativeCliEntryContext {
   execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv): never;
   takeFlags(argv: string[], single: string[], repeated: string[]): { one: Record<string, string>; many: Record<string, string[]>; rest: string[] };
   helpers: {
+    /** Fixed host validation; the entry never chooses or creates an execution worktree. */
+    resolveExecutionCwd(peer: string): string;
     launcherPreview: typeof import("../../cli/preview.ts").launcherPreview;
     readControl: typeof import("../../hub/control-client.ts").readControl;
     recordTerminalLaunch: typeof import("../../cli/terminal-recovery.ts").recordTerminalLaunch;

package/src/adapters/definitions/native-factories.ts

@@ -60,6 +60,13 @@ export function createReviewer(ctx: CreateContext): PeerAdapter {
   return new ReviewerPrintPeer(ctx.instance, ctx.daemon.reviewerPrint);
 }
 
+export function createClaudeImplementer(ctx: CreateContext): PeerAdapter {
+  if (!("claudeImplementer" in ctx.daemon)) throw new Error("Claude implementer requires its per-task transport options");
+  if (ctx.permission !== "ask" && ctx.permission !== "ask-when-needed") throw new Error("Claude implementer requires ask or ask-when-needed");
+  const { ClaudeImplementerPeer } = require("../claude-implementer.ts") as typeof import("../claude-implementer.ts");
+  return new ClaudeImplementerPeer(ctx.instance, ctx.daemon.claudeImplementer);
+}
+
 /** Preserve existing transport option types and object identity; selection stays host-owned. */
 export const DAEMON_PORTS = {
   "codex-appserver": (options: Extract<DaemonPorts, { codex: unknown }>["codex"]) => ({ codex: options }),
@@ -68,5 +75,6 @@ export const DAEMON_PORTS = {
   "pi-rpc": (options: Extract<DaemonPorts, { pi: unknown }>["pi"]) => ({ pi: options }),
   "local-worker": (options: Extract<DaemonPorts, { local: unknown }>["local"]) => ({ local: options }),
   "reviewer-print": (options: Extract<DaemonPorts, { reviewerPrint: unknown }>["reviewerPrint"]) => ({ reviewerPrint: options }),
+  "claude-implementer": (options: Extract<DaemonPorts, { claudeImplementer: unknown }>["claudeImplementer"]) => ({ claudeImplementer: options }),
   "claude-print": (options: Extract<DaemonPorts, { claudePrint: unknown }>["claudePrint"]) => ({ claudePrint: options }),
 } satisfies Record<DaemonEngine, unknown>;

package/src/adapters/kimi-wire-usage.ts

@@ -0,0 +1,303 @@
+import { closeSync, fstatSync, lstatSync, openSync, readSync, readdirSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join, sep } from "node:path";
+import { realPath } from "../hub/project.ts";
+import { safeModelLabel } from "../omniroute/usage.ts";
+
+/**
+ * Kimi's session wire log as a usage source (#285 phase 2). This file is the only code that knows the format.
+ *
+ * Format followed: `<kimi home>/session_index.jsonl` rows `{ sessionId, sessionDir, ... }`, and per session
+ * `<sessionDir>/agents/<agent>/wire.jsonl`, one JSON object per line. The first line is
+ * `{ type: "metadata", protocol_version }`; each model request writes
+ * `{ type: "usage.record", agentId, model, usage: { inputOther, output, inputCacheRead, inputCacheCreation }, usageScope, time }`.
+ * Read from the wire logs of 524 sessions on one machine, all `protocol_version` 1.5, with the hub's own Kimi 2.3.0 install (the issue
+ * recorded the same rows on 2.1.1; the hub verifies 2.2.0 and 2.3.0 in `compat.ts`). Which build wrote which log is not recorded in
+ * them, and the live legs of #285 AC11 are a separate person receipt, so a protocol this file has not seen is `unknown`, never a count.
+ *
+ * Rules: the file is private and holds prompts, so only the four integers, the model label and the time are copied out of a usage
+ * row, nothing is logged, and a line is looked at only when it is short. An error, a shrunk or replaced file, an unknown row shape, a
+ * truncated last line or a missing index gives `unknown` and never a partial count: a read commits its offsets only when every file
+ * of the session was read cleanly.
+ */
+
+export const KIMI_WIRE_PROTOCOLS: readonly string[] = ["1.5"];
+
+export type KimiWireReason =
+  | "no-index" | "outside-home" | "io-error" | "partial-line" | "no-metadata" | "untested-protocol"
+  | "malformed-row" | "unknown-row-shape" | "oversized-row" | "shrunk" | "rotated" | "missing" | "moved";
+
+/** One model request. `id` is opaque and stable across hub restarts: a hash of the session, the agent and the row's byte offset. */
+export interface KimiWireRow {
+  id: string;
+  /** epoch ms the row was written, from Kimi's own clock */
+  at: number;
+  model?: string;
+  inputOther: number;
+  inputCacheCreation: number;
+  inputCacheRead: number;
+  output: number;
+}
+
+export type KimiWireRead =
+  | { status: "ok"; rows: KimiWireRow[]; /** bytes remain unread because of the per-call bound: read again */ more: boolean }
+  | { status: "unknown"; reason: KimiWireReason };
+
+/** What counts against `budget.kimi_tokens_5h`: new input, cache writes and output. Cache reads are recorded and shown, never counted. */
+export function kimiCountedTokens(row: Pick<KimiWireRow, "inputOther" | "inputCacheCreation" | "output">): number {
+  return row.inputOther + row.inputCacheCreation + row.output;
+}
+
+/** Everything the row's four counters add up to, the cache reads included (the `usage` event's `totalTokens`). */
+export function kimiRowTotal(row: Pick<KimiWireRow, "inputOther" | "inputCacheCreation" | "inputCacheRead" | "output">): number {
+  return kimiCountedTokens(row) + row.inputCacheRead;
+}
+
+export interface KimiWireOptions {
+  /** Kimi's data home (`KIMI_CODE_HOME`, else `~/.kimi-code`). */
+  home: string;
+  /** The ACP session id the hub owns; matched exactly against `session_index.jsonl`. */
+  sessionId: string;
+  /** Bytes read per call in total, across every file of the session (the call runs on the daemon's event loop). */
+  maxBytes?: number;
+}
+
+const SESSION_ID = /^[A-Za-z0-9_-]{1,128}$/;
+const AGENT_NAME = /^[A-Za-z0-9._-]{1,64}$/;
+const MAX_AGENTS = 256;
+/** A usage row is a few hundred bytes. A longer line is a prompt, a message or a tool output: skipped without being parsed. */
+const LINE_CAP = 64 * 1024;
+const INDEX_CAP = 16 * 1024 * 1024;
+const DEFAULT_CHUNK = 1024 * 1024;
+const MARKER = Buffer.from('"usage.record"');
+const TRANSIENT: ReadonlySet<KimiWireReason> = new Set(["no-index", "io-error", "partial-line"]);
+
+/** `print` is the content fingerprint of the consumed region at `offset` (see `fingerprint`): identity that survives inode reuse. */
+interface FileState { dev: number; ino: number; offset: number; skipping: boolean; print: string }
+/** The bytes the fingerprint covers at each end of the consumed region: Kimi's metadata line (with its creation time) and the last bytes read. */
+const PRINT_HEAD = 64, PRINT_TAIL = 256;
+class Unknown extends Error { constructor(readonly reason: KimiWireReason) { super(reason); } }
+
+const count = (value: unknown): number | undefined => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+const inside = (root: string, path: string): boolean => path.startsWith(root + sep);
+
+export class KimiWireReader {
+  private readonly home: string;
+  private readonly sessionId: string;
+  private readonly chunk: number;
+  private dir: string | undefined;
+  private files = new Map<string, FileState>();
+  private broken: KimiWireReason | undefined;
+
+  constructor(options: KimiWireOptions) {
+    this.home = options.home;
+    this.sessionId = options.sessionId;
+    this.chunk = Math.max(LINE_CAP * 2, options.maxBytes ?? DEFAULT_CHUNK);
+  }
+
+  /** The rows written since the last successful read, sub-agents included. */
+  read(): KimiWireRead {
+    if (this.broken) return { status: "unknown", reason: this.broken };
+    try {
+      const dir = this.resolve();
+      const next = new Map<string, FileState>();
+      const rows: KimiWireRow[] = [];
+      let more = false, budget = this.chunk;
+      const agents = this.agents(dir);
+      for (const name of this.files.keys()) if (!agents.has(name)) throw new Unknown("missing");
+      for (const [name, wire] of agents) {
+        const previous = this.files.get(name);
+        if (budget <= 0) { if (previous) next.set(name, previous); more = true; continue; } // the bound is spent: this file waits for the next call
+        const result = this.readFile(name, wire, previous, budget);
+        next.set(name, result.state);
+        rows.push(...result.rows);
+        budget -= result.read;
+        more ||= result.more;
+      }
+      this.files = next;
+      return { status: "ok", rows, more };
+    } catch (error) {
+      const reason: KimiWireReason = error instanceof Unknown ? error.reason : "io-error";
+      if (!TRANSIENT.has(reason)) this.broken = reason; // the log no longer matches what was counted: stays unknown for this session
+      return { status: "unknown", reason };
+    }
+  }
+
+  /** The session directory from its index row, resolved once with realPath and kept inside `<home>/sessions`. */
+  private resolve(): string {
+    if (!SESSION_ID.test(this.sessionId)) throw new Unknown("no-index");
+    let root: string;
+    try { root = realPath(join(this.home, "sessions")); } catch { throw new Unknown("no-index"); }
+    if (this.dir) {
+      let again: string;
+      try { again = realPath(this.dir); } catch { throw new Unknown("moved"); }
+      if (again !== this.dir) throw new Unknown("moved");
+      return this.dir;
+    }
+    const text = this.index();
+    let listed: string | undefined;
+    for (const line of text.split("\n")) {
+      if (!line.includes(this.sessionId)) continue;
+      try {
+        const row = JSON.parse(line);
+        if (row && row.sessionId === this.sessionId && typeof row.sessionDir === "string" && row.sessionDir) listed = row.sessionDir;
+      } catch { /* a line that is not ours is not our problem */ }
+    }
+    if (!listed) throw new Unknown("no-index");
+    let dir: string;
+    try { dir = realPath(listed); } catch { throw new Unknown("no-index"); }
+    if (!inside(root, dir)) throw new Unknown("outside-home");
+    this.dir = dir;
+    return dir;
+  }
+
+  /** The index, opened once and sized from that descriptor, so a link swapped in between a check and the read cannot lift the bound. */
+  private index(): string {
+    let fd: number;
+    try { fd = openSync(join(this.home, "session_index.jsonl"), "r"); } catch { throw new Unknown("no-index"); }
+    try {
+      const stat = fstatSync(fd);
+      if (!stat.isFile() || stat.size > INDEX_CAP) throw new Unknown("io-error");
+      const buffer = Buffer.allocUnsafe(stat.size);
+      let got = 0;
+      while (got < stat.size) {
+        const n = readSync(fd, buffer, got, stat.size - got, got);
+        if (n <= 0) break;
+        got += n;
+      }
+      return buffer.toString("utf8", 0, got);
+    } catch (error) { throw error instanceof Unknown ? error : new Unknown("io-error"); }
+    finally { closeSync(fd); }
+  }
+
+  /** `agents/<name>/wire.jsonl` of every agent that has one: the main agent and its sub-agents. */
+  private agents(dir: string): Map<string, string> {
+    const out = new Map<string, string>();
+    const files = new Set<string>(); // one file seen under two names (a link, a hard link) is counted once
+    let names: string[];
+    try { names = readdirSync(join(dir, "agents")).filter(name => AGENT_NAME.test(name)).sort(); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return out; throw new Unknown("io-error"); }
+    if (names.length > MAX_AGENTS) throw new Unknown("io-error");
+    for (const name of names) {
+      const path = join(dir, "agents", name, "wire.jsonl");
+      try { lstatSync(path); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; throw new Unknown("io-error"); }
+      let real: string;
+      try { real = realPath(path); } catch { throw new Unknown("io-error"); }
+      if (!inside(dir, real)) throw new Unknown("outside-home");
+      let identity: string;
+      try { const stat = statSync(real); identity = `${stat.dev}:${stat.ino}`; } catch { throw new Unknown("io-error"); }
+      if (files.has(identity)) continue;
+      files.add(identity);
+      out.set(name, real);
+    }
+    return out;
+  }
+
+  /**
+   * A hash of the first and last bytes of what was consumed, a pure function of the file's content and the offset. A file replaced by
+   * another (log rotation, a restored session) can get the same device and inode on Linux, and from the old offset its new content parses
+   * mid-line: the stored fingerprint no longer matches, which is `rotated`, never a read.
+   */
+  private fingerprint(fd: number, offset: number): string {
+    if (offset <= 0) return "";
+    const hash = createHash("sha256");
+    for (const [start, length] of [[0, Math.min(offset, PRINT_HEAD)], [Math.max(0, offset - PRINT_TAIL), Math.min(offset, PRINT_TAIL)]] as const) {
+      const buffer = Buffer.allocUnsafe(length);
+      let got = 0;
+      while (got < length) {
+        let n: number;
+        try { n = readSync(fd, buffer, got, length - got, start + got); } catch { throw new Unknown("io-error"); }
+        if (n <= 0) throw new Unknown("shrunk");
+        got += n;
+      }
+      hash.update(buffer);
+    }
+    return hash.digest("hex");
+  }
+
+  private readFile(agent: string, path: string, previous: FileState | undefined, limit: number): { state: FileState; rows: KimiWireRow[]; more: boolean; read: number } {
+    let fd: number;
+    try { fd = openSync(path, "r"); } catch { throw new Unknown("io-error"); }
+    try {
+      const stat = fstatSync(fd);
+      if (!stat.isFile()) throw new Unknown("io-error");
+      if (previous && (previous.dev !== stat.dev || previous.ino !== stat.ino)) throw new Unknown("rotated");
+      if (previous && stat.size < previous.offset) throw new Unknown("shrunk");
+      if (previous && this.fingerprint(fd, previous.offset) !== previous.print) throw new Unknown("rotated");
+      const state: FileState = previous ? { ...previous } : { dev: stat.dev, ino: stat.ino, offset: 0, skipping: false, print: "" };
+      const started = state.offset;
+      const seal = (done: FileState): FileState => ({ ...done, print: done.offset === started && previous ? done.print : this.fingerprint(fd, done.offset) });
+      const rows: KimiWireRow[] = [];
+      const length = Math.min(limit, stat.size - state.offset);
+      if (length <= 0) return { state, rows, more: false, read: 0 };
+      const buffer = Buffer.allocUnsafe(length);
+      let got = 0;
+      while (got < length) {
+        let n: number;
+        try { n = readSync(fd, buffer, got, length - got, state.offset + got); } catch { throw new Unknown("io-error"); }
+        if (n <= 0) break;
+        got += n;
+      }
+      if (got < length) throw new Unknown("shrunk");
+      const base = state.offset;
+      const reachedEnd = base + length >= stat.size;
+      let pos = 0;
+      if (state.skipping) {
+        const end = buffer.indexOf(10, 0);
+        if (end < 0) return { state: seal({ ...state, offset: base + length }), rows, more: !reachedEnd, read: length };
+        pos = end + 1;
+        state.skipping = false;
+      }
+      while (pos < length) {
+        const end = buffer.indexOf(10, pos);
+        if (end < 0) {
+          const tail = length - pos;
+          if (tail >= LINE_CAP) {
+            // A line longer than any usage row: refuse only when it looks like one, else skip it unread.
+            if (buffer.subarray(pos, pos + 256).includes(MARKER) || base + pos === 0) throw new Unknown(base + pos === 0 ? "no-metadata" : "oversized-row");
+            state.skipping = true;
+            pos = length;
+            break;
+          }
+          if (reachedEnd) throw new Unknown("partial-line");
+          break; // the chunk ended inside a line: it is read whole next call
+        }
+        const lineStart = base + pos, size = end - pos;
+        if (size > LINE_CAP) {
+          if (buffer.subarray(pos, pos + 256).includes(MARKER) || lineStart === 0) throw new Unknown(lineStart === 0 ? "no-metadata" : "oversized-row");
+        } else if (lineStart === 0) {
+          this.metadata(buffer.toString("utf8", pos, end));
+        } else if (buffer.subarray(pos, end).includes(MARKER)) {
+          const row = this.row(agent, lineStart, buffer.toString("utf8", pos, end));
+          if (row) rows.push(row);
+        }
+        pos = end + 1;
+      }
+      state.offset = base + pos;
+      return { state: seal(state), rows, more: state.offset < stat.size, read: length };
+    } finally { closeSync(fd); }
+  }
+
+  private metadata(line: string): void {
+    let value: any;
+    try { value = JSON.parse(line); } catch { throw new Unknown("no-metadata"); }
+    if (!value || value.type !== "metadata" || typeof value.protocol_version !== "string") throw new Unknown("no-metadata");
+    if (!KIMI_WIRE_PROTOCOLS.includes(value.protocol_version)) throw new Unknown("untested-protocol");
+  }
+
+  /** A line that mentions `usage.record`: a usage row, or (valid JSON of another type) something that only quotes it. */
+  private row(agent: string, offset: number, line: string): KimiWireRow | undefined {
+    let value: any;
+    try { value = JSON.parse(line); } catch { throw new Unknown("malformed-row"); }
+    if (!value || typeof value !== "object" || value.type !== "usage.record") return undefined;
+    const usage = value.usage;
+    const inputOther = count(usage?.inputOther), output = count(usage?.output), inputCacheRead = count(usage?.inputCacheRead), inputCacheCreation = count(usage?.inputCacheCreation);
+    const at = value.time;
+    if (inputOther === undefined || output === undefined || inputCacheRead === undefined || inputCacheCreation === undefined
+      || (value.usageScope !== "turn" && value.usageScope !== "session")
+      || typeof at !== "number" || !Number.isSafeInteger(at) || at <= 0 || at > 8.64e15) throw new Unknown("unknown-row-shape");
+    const model = safeModelLabel(value.model);
+    const id = createHash("sha256").update(this.sessionId).update("\0").update(agent).update("\0").update(String(offset)).digest("hex").slice(0, 32);
+    return { id, at, ...(model ? { model } : {}), inputOther, inputCacheCreation, inputCacheRead, output };
+  }
+}