@staix/agent-hub 0.14.0 → 0.16.0

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/local-worker.ts

@@ -235,7 +235,7 @@ export class LocalPeer extends BasePeer {
   ): Promise<string> {
     const { maxSteps = 30 } = this.opts;
     const turnSignal = this.abort!.signal;
-    // claude-mem's observer is a cloud model: nothing of a PII turn is captured.
+    // Local capture preserves the host privacy fence: nothing of a PII turn is recorded.
     const capture = policy?.pii ? undefined : this.opts.capture;
     // Unknown gateway state is never permission to send PII.
     if (policy?.pii && !(await this.opts.omni.onCampus())) {
@@ -245,6 +245,7 @@ export class LocalPeer extends BasePeer {
     this.routePii = !!policy?.pii;
     const ctx = this.toolContext(envs, turnSignal, !!policy?.pii, reply);
     let usedTools = false;
+    let captureInvocation = 0;
     for (let step = 0; step < maxSteps; step++) {
       this.elide(msgs);
       const res = await this.call(msgs, policy, envs);
@@ -280,7 +281,7 @@ export class LocalPeer extends BasePeer {
           if (this.approvalStopReason) { this.abort?.abort(); throw new ApprovalWaitStop(this.approvalStopReason); }
           this.observeTool(call, output, policy, `${this.sessionId}.${turn}.${step}`);
           // Hub tool arguments/results are not capture evidence; Tasks owns its screened memory writes.
-          if (name !== "hub_send" && !TASK_TOOL_NAMES.has(name) && !CONDUCTOR_TOOL_NAMES.has(name)) capture?.observe({ tool: call.function.name, args: call.function.arguments, output, id: call.id, paths: touchedPaths(call.function.name, safeParse(call.function.arguments)) });
+          if (name !== "hub_send" && !TASK_TOOL_NAMES.has(name) && !CONDUCTOR_TOOL_NAMES.has(name)) capture?.observe({ tool: call.function.name, args: call.function.arguments, output, id: call.id, sourceId: `${this.sessionId}.${turn}.${step}.${captureInvocation++}`, paths: touchedPaths(call.function.name, safeParse(call.function.arguments)) });
         }
       } finally { if (results.length) this.routes.observeResults(res.routeDecision, res.message, results); }
     }
@@ -293,7 +294,7 @@ export class LocalPeer extends BasePeer {
       cwd: this.opts.cwd,
       deny: this.opts.tools.deny,
       readOnly: this.opts.tools.readOnly,
-      permit: async (title, tool, _signal, canonicalTarget, _observe, originalPath) => {
+      permit: async (title, tool, _signal, canonicalTarget, _observe, originalPath, input) => {
         if (turnSignal.aborted) return "aborted";
         const generation = this.turn;
         let observed = false;
@@ -313,7 +314,7 @@ export class LocalPeer extends BasePeer {
           const finish = (decision: ToolApproval) => { turnSignal.removeEventListener("abort", onAbort); resolve(decision); };
           const onAbort = () => finish("aborted");
           turnSignal.addEventListener("abort", onAbort, { once: true });
-          this.opts.tools.permit(title, tool, turnSignal, canonicalTarget, observe, originalPath).then(finish, (error) => { turnSignal.removeEventListener("abort", onAbort); reject(error); });
+          this.opts.tools.permit(title, tool, turnSignal, canonicalTarget, observe, originalPath, input).then(finish, (error) => { turnSignal.removeEventListener("abort", onAbort); reject(error); });
         });
         if (generation !== this.turn || (turnSignal.aborted && picked !== "expired")) return "aborted";
         // Legacy permit callbacks can represent a person's denial without provenance. A true

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. */
@@ -268,7 +270,7 @@ export interface AdapterDefinition {
     trace?: "route" | "backend";
     backendLabel?: string;
   };
-  budget?: { account: string; quotaExempt?: boolean; instrumented?: boolean; reader?: QuotaReader; context?: ContextReader; checkpoint?: boolean; resetSoftTokensOnResume?: boolean };
+  budget?: { account: string; quotaExempt?: boolean; /** Why this peer has no provider quota, shown by `ahub budget` and the dashboard (#285 AC6). */ noQuotaReason?: string; instrumented?: boolean; reader?: QuotaReader; context?: ContextReader; checkpoint?: boolean; resetSoftTokensOnResume?: boolean };
   configuration?: {
     schema?(ports: NativeConfigValidators): Record<string, NativeConfigCheck>;
     routingSchema?(ports: NativeConfigValidators): Record<string, NativeConfigCheck>;
@@ -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")],

package/src/adapters/reviewer-print.ts

@@ -1,6 +1,6 @@
-import { spawn, type ChildProcess } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+import { OwnedPrintChild, PrintChildCleanupError } from "./claude-print-child.ts";
 import { randomUUID } from "node:crypto";
-import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { HUB, frame } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
 import type { Envelope } from "../hub/envelope.ts";
@@ -107,9 +107,6 @@ export interface ReviewerPrintOptions {
   bindingCurrent?(task: number, binding: ReviewerReviewBinding): boolean;
 }
 
-// ponytail: 256 KiB per NDJSON frame and 4 MiB stdout per review child. Raise only with measured native receipts.
-const MAX_REVIEW_FRAME_BYTES = 256 * 1024, MAX_REVIEW_OUTPUT_BYTES = 4 * 1024 * 1024;
-class GroupCleanupError extends Error {}
 type ReviewTarget = Omit<ReviewerFailure, "cause">;
 interface ReviewBatch { targets: (ReviewTarget | undefined)[]; next: number; failures: ReviewerFailure[] }
 const reviewTarget = (env: Envelope): ReviewTarget | undefined => {
@@ -129,8 +126,7 @@ const reviewTask = (env: Envelope): number | undefined => {
 export class ReviewerPrintPeer extends BasePeer {
   readonly hubNative = true;
   private generation = 0;
-  private child: ChildProcess | undefined;
-  private childStop: ((child: ChildProcess) => Promise<void>) | undefined;
+  private child: OwnedPrintChild | undefined;
   private childCleanup: (() => Promise<void>) | undefined;
   private childCurrent: (() => boolean) | undefined;
   private reviewMcpClose: (() => void) | undefined;
@@ -242,7 +238,7 @@ export class ReviewerPrintPeer extends BasePeer {
       try { result = await this.review(env, task, generation); }
       catch (error) {
         if (generation !== this.generation) return;
-        if (error instanceof GroupCleanupError) {
+        if (error instanceof PrintChildCleanupError) {
           // Unavailable until a stop confirms the group gone: no new review runs beside the survivors.
           this.opts.log?.(`[${this.id}] review of task #${task}: ${error.message}`);
           this.settle("needs_review", `review process group still running: ${error.message}`);
@@ -329,60 +325,41 @@ export class ReviewerPrintPeer extends BasePeer {
     let mcpClosed=false;
     const closeMcp=()=>{ if(mcpClosed)return; mcpClosed=true; mcp?.close(); if(this.reviewMcpClose===closeMcp)this.reviewMcpClose=undefined; };
     this.reviewMcpClose=closeMcp;
-    let ownedChild: ChildProcess | undefined, releasing: Promise<void> | undefined;
+    let ownedChild: OwnedPrintChild | undefined, releasing: Promise<void> | undefined;
     let policyTimer: ReturnType<typeof setInterval> | undefined;
     const release = () => releasing ??= Promise.resolve().then(() => launch?.cleanup?.()).then(() => {});
     try {
     launch = await this.prepare(randomUUID(), input, task, mcp?.config);
     if (generation !== this.generation || this.opts.admit?.(env) === false || launch.current?.() === false) throw new ReviewerUnavailableError("reviewer isolation or admission changed before child spawn", launch.current?.() === false ? "binary" : "unknown");
     this.receipt = launch.isolation;
-    const [cmd, ...prefix] = launch.command;
     let quota = false;
-    return await new Promise<{ code: number | null; quota: boolean }>((resolve, reject) => {
-      const child = spawn(cmd!, [...prefix, ...launch!.args], { cwd: launch!.cwd ?? this.opts.cwd, detached: true,
-        env: peerChildEnv(this.id, launch!.envMode === "replace" ? launch!.env : { ...process.env, ...launch!.env }), stdio: ["pipe", "pipe", "ignore"] });
-      // Owned before any await, so a stop that lands before "spawn" still finds and kills it.
-      this.child = child;
-      ownedChild = child;
-      this.childStop = launch!.stop;
-      this.childCleanup = release;
-      this.childCurrent = launch!.watchCurrent ? launch!.current : undefined;
-      child.once("error", error => { if (this.child === child) { this.child = undefined; this.childStop = undefined; } reject(error); });
-      child.stdin!.on("error", () => { /* the child exited before reading its prompt; its exit settles the review */ });
-      child.once("spawn", () => {
-        trackGroup(child);
-        if (generation !== this.generation) { child.stdin!.destroy(); return; } // stopped meanwhile: no prompt
+    const child = new OwnedPrintChild({ peer: this.id, command: launch.command, args: launch.args,
+      cwd: launch.cwd ?? this.opts.cwd, env: launch.env, envMode: launch.envMode, input,
+      current: () => generation === this.generation, stop: launch.stop,
+      onError: () => { if (this.child === child) this.child = undefined; },
+      onSpawn: () => {
         this.runningBinding={task,binding};
         this.reviewing = task; this.reviewSeq++;
         if (this.childCurrent) policyTimer = setInterval(() => { this.reviewToken(task); }, 100);
-        child.stdin!.end(input);
-      });
-      let buffer = "", outputBytes = 0;
-      child.stdout!.on("data", (chunk: Buffer) => {
-        if (generation !== this.generation) return;
-        outputBytes += chunk.length;
-        if (outputBytes > MAX_REVIEW_OUTPUT_BYTES) { this.abortReview("review output limit exceeded"); return; }
-        buffer += chunk.toString("utf8");
-        for (let i; (i = buffer.indexOf("\n")) >= 0;) {
-          const line = buffer.slice(0, i); buffer = buffer.slice(i + 1);
-          if (Buffer.byteLength(line) > MAX_REVIEW_FRAME_BYTES) { this.abortReview("review output limit exceeded"); return; }
-          try {
-            const event: unknown = JSON.parse(line);
-            const usage = this.opts.backend.usage?.(event);
-            if (usage) this.opts.onUsage?.(usage, task);
-            if (this.opts.backend.failure?.(event) === "quota") quota = true;
-          } catch { /* not a stream-json line */ }
-        }
-        if (Buffer.byteLength(buffer) > MAX_REVIEW_FRAME_BYTES) { this.abortReview("review output limit exceeded"); return; }
-        this.touch();
-      });
-      child.once("exit", code => {
-        if (this.child === child) { this.reviewing = undefined; this.runningBinding=undefined; } // the verdict authority ends with the leader
-        // The review ends when its whole process group is gone (an MCP server or other descendant may outlive the leader).
-        (launch!.stop ? launch!.stop(child) : stopOwnedProcess(child, { group: true })).then(() => { if (this.child === child) { this.child = undefined; this.childStop = undefined; } resolve({ code, quota }); },
-          (error: Error) => reject(new GroupCleanupError(error.message)));
-      });
+      },
+      onFrame: event => {
+        const usage = this.opts.backend.usage?.(event);
+        if (usage) this.opts.onUsage?.(usage, task);
+        if (this.opts.backend.failure?.(event) === "quota") quota = true;
+      },
+      onActivity: () => this.touch(),
+      onLimit: () => this.abortReview("review output limit exceeded"),
+      onLeaderExit: () => {
+        if (this.child === child) { this.reviewing = undefined; this.runningBinding=undefined; }
+      },
     });
+    // Owned before any await, so a stop that lands before "spawn" still finds and kills it.
+    this.child = ownedChild = child;
+    this.childCleanup = release;
+    this.childCurrent = launch.watchCurrent ? launch.current : undefined;
+    const code = await child.done;
+    if (this.child === child) this.child = undefined;
+    return { code, quota };
     } finally {
       closeMcp();
       if (policyTimer) clearInterval(policyTimer);
@@ -403,8 +380,8 @@ export class ReviewerPrintPeer extends BasePeer {
     this.runningBinding=undefined;
     const child = this.child;
     if (!child) return;
-    await (this.childStop ? this.childStop(child) : stopOwnedProcess(child, { group: true }));
-    if (this.child === child) { await this.childCleanup?.(); this.child = undefined; this.childStop = undefined; this.childCleanup = undefined; this.childCurrent = undefined; }
+    await child.stop();
+    if (this.child === child) { await this.childCleanup?.(); this.child = undefined; this.childCleanup = undefined; this.childCurrent = undefined; }
   }
 }