@staix/agent-hub 0.14.0 → 0.15.0

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([
@@ -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-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 };
+  }
+}

package/src/adapters/registry-types.ts

@@ -1,3 +1,4 @@
+import type { ClaudeImplementerOptions } from "./claude-implementer.ts";
 import type { ReviewerBackend, ReviewerPrintOptions } from "./reviewer-print.ts";
 import type { SettingDef } from "../hub/settings.ts";
 import type { Addon } from "../hub/tooling.ts";
@@ -20,7 +21,7 @@ import type { BuiltinCliEntry } from "./definitions/native-cli-entry-types.ts";
 import type { NativePreviewBuilder } from "./definitions/native-cli-preview-common.ts";
 
 export type StartForm = "tui" | "headless";
-export type DaemonEngine = "codex-appserver" | "acp" | "owned-acp" | "pi-rpc" | "local-worker" | "claude-print" | "reviewer-print";
+export type DaemonEngine = "codex-appserver" | "acp" | "owned-acp" | "pi-rpc" | "local-worker" | "claude-print" | "reviewer-print" | "claude-implementer";
 
 /** Existing buildLaunch inputs plus the startup-bound instance and project identity. */
 export interface LaunchContext {
@@ -62,7 +63,8 @@ export type DaemonPorts =
   | { pi: PiOptions }
   | { local: LocalOptions }
   | { claudePrint: ClaudePrintOptions }
-  | { reviewerPrint: ReviewerPrintOptions };
+  | { reviewerPrint: ReviewerPrintOptions }
+  | { claudeImplementer: ClaudeImplementerOptions };
 
 export interface CreateContext<Ports extends DaemonPorts = DaemonPorts> {
   instance: string;
@@ -200,7 +202,7 @@ export interface AdapterDefinition {
     ownedFlags: readonly string[];
     conductorStartArgs?(args: string[]): { mode?: StartForm } | Error;
   };
-  identity: { mcp: "acp-session" | "project-file" | "env" | "channel-plugin" };
+  identity: { mcp: "acp-session" | "project-file" | "env" | "channel-plugin"; currentChild?: true };
   /** Declaration admission only; execution-root and runtime owner proof remain host responsibilities. */
   instances?: { mode: "external" | "headless"; roles?: readonly string[];
     /** Each declared instance runs its own native data home (`jcode_home`) and may pass its own provider, model and profile names (#685). Fixed builtins only. */
@@ -300,6 +302,8 @@ export interface AdapterDefinition {
   hooks?: Partial<NativeHooks>;
   /** #223: what a declared headless reviewer-only instance of this kind runs as. Fixed builtins only. */
   reviewerVariant?: AdapterDefinition;
+  /** #525: fixed builtin variant for declared headless implementer instances. */
+  headlessVariant?: AdapterDefinition;
   /** Fixed host backend; runtime isolation proof is required before bus admission. */
   reviewer?: { backend?: ReviewerBackend; defaultPool: boolean; unavailable?: string; declaration: "automatic" | "explicit" };
 }

package/src/adapters/registry.ts

@@ -24,7 +24,10 @@ function immutable<T>(value: T, seen = new WeakSet<object>()): T {
 }
 
 const fixedBuiltinDefinitions = new Set<AdapterDefinition>([...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN, QWEN_DEFINITION, AGY_DEFINITION, AGY_REVIEWER_VARIANT]);
-for (const definition of [...fixedBuiltinDefinitions]) if (definition.reviewerVariant) fixedBuiltinDefinitions.add(definition.reviewerVariant);
+for (const definition of [...fixedBuiltinDefinitions]) {
+  if (definition.reviewerVariant) fixedBuiltinDefinitions.add(definition.reviewerVariant);
+  if (definition.headlessVariant) fixedBuiltinDefinitions.add(definition.headlessVariant);
+}
 
 /** Keep the native catalog's order, independently of the legacy default-role object order. */
 export const ADAPTERS: readonly AdapterDefinition[] = immutable([
@@ -65,6 +68,7 @@ for (const definition of [...ADAPTERS, ...declarationOnlyDefinitions]) {
   assertDefinitionCoherence(definition);
   assertNativeCapabilityScope(definition);
   if (definition.reviewerVariant) { assertDefinitionCoherence(definition.reviewerVariant); assertNativeCapabilityScope(definition.reviewerVariant); }
+  if (definition.headlessVariant) { assertDefinitionCoherence(definition.headlessVariant); assertNativeCapabilityScope(definition.headlessVariant); }
   if (definition.api !== ADAPTER_API || definitions.has(definition.kind)) throw new Error("invalid builtin adapter registry");
   definitions.set(definition.kind, definition);
 }
@@ -114,7 +118,11 @@ function resolvedDefinition(id: string, kind: string | undefined, instances: Kin
   const reviewerOnly = Array.isArray(roles) && !types.isProxy(roles) && roles.length === 1 && Object.getOwnPropertyDescriptor(roles, "0")?.value === "reviewer";
   const variant = definition?.reviewerVariant;
   const fresh = variant?.reviewer?.declaration === "automatic" || ownField(declaration, "review_mode") === "fresh";
-  return variant && kind !== id && reviewerOnly && ownField(declaration, "start_mode") === "headless" && fresh ? variant : definition;
+  const headless = kind !== id && ownField(declaration, "start_mode") === "headless";
+  if (variant && headless && reviewerOnly && fresh) return variant;
+  const roleValues = Array.isArray(roles) && !types.isProxy(roles) && roles.length <= 4 ? Array.from({ length: roles.length }, (_, index) => Object.getOwnPropertyDescriptor(roles, String(index))?.value) : [];
+  const writerRoles = roleValues.includes("implementer") && roleValues.every(role => role === "implementer" || role === "verifier");
+  return headless && writerRoles && definition?.headlessVariant ? definition.headlessVariant : definition;
 }
 export function familyOf(id: string, instances?: KindMap): string | undefined {
   return definitionOf(id, instances)?.family;
@@ -217,6 +225,7 @@ export function assertDefinitionCoherence(definition: AdapterDefinition): void {
     }
   }
   if (definition.reviewerVariant && !definition.reviewerVariant.reviewer) fail("reviewerVariant.reviewer", "reviewer variant lacks reviewer policy");
+  if (definition.headlessVariant && (definition.headlessVariant.transport !== "hub-native" || !definition.headlessVariant.start.create || definition.headlessVariant.instances?.mode !== "headless")) fail("headlessVariant", "implementer variant requires its headless hub-native factory");
   if (definition.reviewer?.unavailable && (definition.start.create || definition.reviewer.backend)) fail("reviewer", "unavailable reviewer must remain metadata-only");
 }
 
@@ -233,7 +242,10 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
     ["routing", definition.routing !== undefined],
     ["projection", definition.projection !== undefined],
     ["instances.nativeHome", declared(definition.instances, "nativeHome")], // #685: a fixed-builtin assumption, one native data home per declared instance
+    ["identity.currentChild", declared(definition.identity, "currentChild")],
     ["reviewerVariant", definition.reviewerVariant !== undefined],
+    ["headlessVariant", definition.headlessVariant !== undefined],
+    ["start.daemonPort claude-implementer", definition.start.daemonPort === "claude-implementer"],
     ["reviewer", definition.reviewer !== undefined],
     ["hooks.factsHook", declared(definition.hooks, "factsHook")],
     ["cli.entry", declared(definition.cli, "entry")],