@staix/agent-hub 0.12.36 → 0.12.38

package/src/adapters/acp.ts

@@ -68,7 +68,7 @@ export interface AcpOptions {
   /** Production Qwen only; legacy benchmark adapters retain their own native policy. */
   qwen025?: boolean;
   /** A production adapter's source-pinned identity; no table is inferred from it. */
-  expectedAgent?: { name: string; version: string };
+  expectedAgent?: { name: string; version: string | ((version: unknown) => boolean) };
   /** Vendors with uncertain load semantics must explicitly echo the restored identity. */
   requireLoadSessionEcho?: boolean;
   /** Bound for native mode acknowledgement; defaults to the handshake deadline. */
@@ -242,7 +242,8 @@ export class AcpPeer extends BasePeer {
       // The configured peer id and command are labels, not an agent-specific mode contract.
       // Installed Kimi Code CLI's ACP initialize advertises this exact name.
       this.kimiAgent = init?.agentInfo?.name === "Kimi Code CLI";
-      if (this.opts.expectedAgent && (init?.agentInfo?.name !== this.opts.expectedAgent.name || init?.agentInfo?.version !== this.opts.expectedAgent.version)) throw new Error("native ACP identity is not verified for this production adapter");
+      const expected = this.opts.expectedAgent, version = init?.agentInfo?.version;
+      if (expected && (init?.agentInfo?.name !== expected.name || !(typeof expected.version === "function" ? expected.version(version) : version === expected.version))) throw new Error("native ACP identity is not verified for this production adapter");
       this.qwenAgent = qwenNativeIdentity(this.id, this.opts.qwen025, init, this.opts.kind);
       const resume = this.opts.resumeSessionId;
       if (!resume) return this.request("session/new", { cwd: this.opts.cwd, mcpServers: this.opts.mcpServers ?? [] });

package/src/adapters/agy/definition.ts

@@ -0,0 +1,61 @@
+import type { AdapterDefinition, LaunchContext, LaunchPlan } from "../registry-types.ts";
+import { AGY_REVIEWER_VARIANT } from "../definitions/reviewer-variants.ts";
+import { AGY_FACTS_HOOK } from "./hooks.ts";
+
+const DISPLAY = { palette: { fg: "#6558a6", bg: "#f1effa" } };
+const shellQuote = (value: string): string => `'${value.replace(/'/g, `'\\''`)}'`;
+
+function agyLaunch(ctx: LaunchContext): LaunchPlan {
+  const argv = ["agy", ...ctx.userArgs], command = argv.map(shellQuote).join(" ");
+  const metadata = { packageEntrypoint: ctx.entrypoint, command, argv, env: {}, kind: "agy", peer: ctx.instance } as LaunchPlan["metadata"] & { kind: "agy"; peer: string };
+  return { cmd: "agy", args: ctx.userArgs, metadata };
+}
+
+/** Antigravity is an unmanaged, pull-only peer attached from its native project plugin. */
+export const AGY_DEFINITION: AdapterDefinition = {
+  api: 1,
+  kind: "agy",
+  displayName: "Antigravity",
+  family: "agy",
+  transport: "ws-pull",
+  roles: ["implementer", "verifier"],
+  optional: true,
+  defaultOnRoster: false,
+  trust: { onPrem: false, hubSandboxed: false },
+  start: {
+    forms: ["tui"],
+    defaultForm: "tui",
+    ownsTerminal: form => form === "tui",
+    launch: agyLaunch,
+    conductorStartable: false,
+    hubSwitches: [],
+    ownedFlags: ["--new", "--continue", "--conversation", "--resume"],
+    conductorStartArgs: args => args.length ? new Error("conductor starts accept no launch overrides; use ahub agy") : {},
+  },
+  identity: { mcp: "channel-plugin" },
+  attach: {
+    pullOnlyForms: ["tui"],
+    recoveryLaunch: instance => ({ kind: "agy", peer: instance }),
+    pullOnlyNotice: "pull-only: messages wait for hub_inbox; permission modes and session recovery are not managed",
+  },
+  permission: {
+    modes: {},
+    unmanaged: "Antigravity selects its own permission mode in its TUI; no hub permission mode",
+    unmanagedForms: ["tui"],
+    unmanagedNote: "Antigravity approves tools in its own TUI; no hub permission mode",
+    unmanagedStatusNote: "unmanaged native permission policy",
+  },
+  session: {
+    idField: "sessionId",
+    currentId: () => undefined,
+    freshOnRestore: true,
+    recoveryRefusal: () => "Antigravity session continuity and resume are unavailable until native behavior is verified",
+  },
+  turnEnd: "native-hook",
+  cli: { command: "agy", authority: "person", startWords: () => ["agy"] },
+  display: DISPLAY,
+  routing: { allowedRoles: ["implementer", "verifier"] },
+  reviewer: { defaultPool: false, declaration: "automatic", unavailable: "agy is an implementer peer (#485)" },
+  reviewerVariant: AGY_REVIEWER_VARIANT,
+  hooks: { factsHook: AGY_FACTS_HOOK },
+};

package/src/adapters/agy/entry.ts

@@ -0,0 +1,76 @@
+import { publicArg } from "../definitions/native-cli-preview-common.ts";
+import { spawn, spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import type { NativeCliEntryContext } from "../definitions/native-cli-entry-types.ts";
+import { bundleInStatus, rosterInStatus } from "../../hub/status-roster.ts";
+import { ensureAgyMcp, cleanupAgyMcp, type AgyMcpOptions } from "../../cli/agy-mcp.ts";
+import { peerChildEnv } from "../../hub/child-process.ts";
+
+export function agyTuiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv) {
+  return { cwd, env, stdio: "inherit" as const };
+}
+
+function runAgyTui(argv: string[], cwd: string, env: NodeJS.ProcessEnv): Promise<number> {
+  const child = spawn("agy", argv, agyTuiSpawnOptions(cwd, env));
+  return new Promise((resolveExit, reject) => {
+    const forward = (signal: NodeJS.Signals) => {
+      if (child.exitCode !== null || child.signalCode !== null) return;
+      try { child.kill(signal); } catch { /* The native child may exit as the signal arrives. */ }
+    };
+    const onInterrupt = () => forward("SIGINT");
+    const onTerminate = () => forward("SIGTERM");
+    const onHangup = () => forward("SIGHUP");
+    const cleanup = () => {
+      process.off("SIGINT", onInterrupt);
+      process.off("SIGTERM", onTerminate);
+      process.off("SIGHUP", onHangup);
+    };
+    process.on("SIGINT", onInterrupt);
+    process.on("SIGTERM", onTerminate);
+    process.on("SIGHUP", onHangup);
+    child.once("error", error => { cleanup(); reject(error); });
+    child.once("close", code => { cleanup(); resolveExit(code ?? 1); });
+  });
+}
+
+export async function runAgyEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const { args, cwd, stateDir, cliDir, connect, fail } = ctx;
+  if (ctx.instance) fail("extra Antigravity TUI instances are not verified in P1");
+  const preview = args.includes("--print-command") || args.includes("--dry-run");
+  const unattended = ctx.unattendedEnv || args.includes("--unattended");
+  const nativeArgs = args.filter(arg => !["--print-command", "--dry-run", "--unattended"].includes(arg));
+  // Headless, resume and native approval overrides are not silently passed through an unverified hub mapping.
+  if (nativeArgs.some(arg => ["--print", "-p", "--prompt", "--input-format", "--output-format", "--conversation", "--continue", "-c", "--new", "--mode", "--dangerously-skip-permissions"].some(flag => arg === flag || arg.startsWith(`${flag}=`)))) fail("agy P1 supports a fresh TUI only; headless, resume and permission flags need a verified mapping");
+  if (unattended) fail("agy P1 native permissions are unmanaged; unattended mode has no verified prompt mapping");
+  const argv = nativeArgs;
+  if (preview) { console.log(JSON.stringify({ command: "agy", args: argv.map(publicArg), mode: "tui", permission: "unmanaged", mcp: ".agents/plugins/agent-hub/", writes: false })); return; }
+  const version = spawnSync("agy", ["--version"], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, env: peerChildEnv("agy") });
+  if (version.status !== 0 || version.stdout.trim() !== "1.4.2") fail("agy P1 requires the verified Antigravity CLI 1.4.2");
+  const hub = await connect();
+  let options: AgyMcpOptions | undefined;
+  let pluginWritten = false;
+  try {
+    if (!hub.features.includes("native_hook_launch")) fail("running hub lacks the verified native hook launcher; upgrade or restart it before launching agy");
+    const status = (await hub.request({ t: "status" })).status;
+    if (rosterInStatus(status, "agy") !== true) fail("agy is off roster; add it with ahub roster add agy");
+    const admitted = await hub.request({ t: "native_hook_launch", op: "begin", peer: "agy" });
+    if (!admitted.ok || typeof admitted.launchId !== "string" || typeof admitted.instanceId !== "string") fail(admitted.error ?? "native hook launch was not admitted");
+    options = { projectRoot: cwd, stateDir, serverJs: bundleInStatus(status) ?? resolve(cliDir, "../../plugins/agent-hub/server.js"),
+      hookScript: resolve(cliDir, "facts-hook.ts"), peer: "agy", launchId: admitted.launchId, instanceId: admitted.instanceId };
+    const written = ensureAgyMcp(options);
+    pluginWritten = written.changed;
+    if (written.tracked) console.error("The managed agy plugin is tracked; review its local machine paths before committing");
+    console.error("Antigravity: pull-only TUI; native permissions unmanaged, no hub sandbox");
+    const env: NodeJS.ProcessEnv = { ...ctx.helpers.nativeLaunchEnv("agy", ctx.helpers.childEnv()), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
+    delete env.AGENTHUB_CHANNEL;
+    const code = await runAgyTui(argv, cwd, env);
+    if (code !== 0) process.exitCode = code;
+  } finally {
+    if (options) {
+      // Revoke launcher authority before cleanup; stale cleanup never removes a newer managed launch.
+      await hub.request({ t: "native_hook_launch", op: "end", peer: "agy", launchId: options.launchId }).catch(() => {});
+      if (pluginWritten) try { cleanupAgyMcp(options); } catch { console.error("Managed agy plugin cleanup refused: files changed or ownership could not be verified"); }
+    }
+    hub.close();
+  }
+}

package/src/adapters/agy/hooks.ts

@@ -0,0 +1,81 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative } from "node:path";
+import { createHash } from "node:crypto";
+import type { NativeFactsInput, NativeFactsPort, NativeFactsTranscript } from "../registry-types.ts";
+
+const EVENTS = ["SessionStart", "PreInvocation", "PostInvocation", "PreToolUse", "PostToolUse", "Stop"] as const;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const record = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+
+/** The pinned 1.4.2 envelope has no event name: the managed command supplies it separately. */
+export function decodeAgyHook(event: string, value: unknown): NativeFactsInput | undefined {
+  if (!(EVENTS as readonly string[]).includes(event) || !record(value) || typeof value.conversationId !== "string" || !UUID.test(value.conversationId)
+    || typeof value.transcriptPath !== "string" || !isAbsolute(value.transcriptPath) || value.transcriptPath.length > 4096
+    || !Array.isArray(value.workspacePaths) || !value.workspacePaths.length || value.workspacePaths.length > 32
+    || !value.workspacePaths.every(path => typeof path === "string" && path.length <= 4096 && isAbsolute(path))) return;
+  if (event === "Stop" && typeof value.fullyIdle !== "boolean") return;
+  const call = record(value.toolCall) ? value.toolCall : undefined;
+  if ((event === "PreToolUse" || event === "PostToolUse") && (!call || typeof call.name !== "string" || call.name.length > 128 || !record(call.args))) return;
+  const native = call?.args as Record<string, unknown> | undefined;
+  // Only the observed native read is classified. Unobserved edits never receive a scoped grant or effect attribution.
+  const observedRead = call?.name === "view_file" && typeof native?.AbsolutePath === "string";
+  const phase = ({ SessionStart: "session", PreInvocation: "start", PostInvocation: "post", PreToolUse: "pre", PostToolUse: "post", Stop: "stop" } as const)[event as typeof EVENTS[number]];
+  return { event: event as NativeFactsInput["event"], phase, sessionId: value.conversationId, transcriptPath: value.transcriptPath,
+    workspacePaths: value.workspacePaths as string[], tool: observedRead ? "Read" : typeof call?.name === "string" ? call.name : "", input: observedRead ? { file_path: native!.AbsolutePath } : native ?? {},
+    ...(Number.isSafeInteger(value.stepIdx) && (value.stepIdx as number) >= 0 ? { toolUseId: `${value.conversationId}:${value.stepIdx}` } : {}),
+    ...(Number.isSafeInteger(value.invocationNum) && (value.invocationNum as number) >= 0 ? { invocation: value.invocationNum as number } : {}),
+    ...(event === "Stop" ? { fullyIdle: value.fullyIdle as boolean, terminationReason: typeof value.terminationReason === "string" ? value.terminationReason : "" } : {}) };
+}
+
+export function encodeAgyHook(event: string, text?: string): Record<string, unknown> | undefined {
+  // `allow` does not override native approval. Until a prompt mapping is proven, leave all native permissions alone.
+  if (text && (event === "SessionStart" || event === "PreInvocation")) return { injectSteps: [{ ephemeralMessage: text }] };
+  return undefined;
+}
+
+/** Only native-generated rows under the exact session cache path count as readback/completion evidence. */
+export function readAgyTranscript(session: string, transcript: string): NativeFactsTranscript {
+  const empty: NativeFactsTranscript = { factIds: [] };
+  if (!UUID.test(session)) return empty;
+  const home = process.env.HOME ?? homedir();
+  const candidates = ["antigravity-cli", "antigravity", "antigravity-ide"].map(surface => join(home, ".gemini", surface, "brain", session, ".system_generated/logs/transcript_full.jsonl"));
+  if (!candidates.includes(transcript)) return empty;
+  let fd: number | undefined;
+  try {
+    let cursor = home;
+    for (const name of relative(home, transcript).split("/")) { cursor = join(cursor, name); if (lstatSync(cursor).isSymbolicLink()) return empty; }
+    fd = openSync(transcript, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.nlink !== 1) return empty;
+    // ponytail: completion lookback is capped at 4 MiB (as for Claude). A larger final row is unverified;
+    // upgrade to a native completion cursor if that ceiling becomes insufficient.
+    const cap = 4 * 1024 * 1024;
+    for (let window = 64 * 1024; ; window = Math.min(cap, window * 2)) {
+      const start = Math.max(0, stat.size - window), from = start > 0 ? start - 1 : 0;
+      const buffer = Buffer.alloc(stat.size - from);
+      let bytes = 0;
+      while (bytes < buffer.length) {
+        const count = readSync(fd, buffer, bytes, buffer.length - bytes, from + bytes);
+        if (!count) break;
+        bytes += count;
+      }
+      const lines = buffer.subarray(0, bytes).toString("utf8").split("\n");
+      // The preceding byte distinguishes a cut inside a row from a row beginning exactly at the window.
+      if (start) lines.shift();
+      const out: NativeFactsTranscript = { factIds: [] };
+      for (const line of lines) {
+        let row: unknown; try { row = JSON.parse(line); } catch { continue; }
+        if (!record(row) || row.status !== "DONE") continue;
+        if (row.source === "SYSTEM_SDK" && row.type === "EPHEMERAL_MESSAGE" && typeof row.content === "string") {
+          for (const match of row.content.matchAll(/agent-hub facts \[([a-zA-Z0-9-]{1,128})\]/g)) out.factIds.push(match[1]!);
+        }
+        if (row.source === "MODEL" && row.type === "PLANNER_RESPONSE" && Number.isSafeInteger(row.step_index)
+          && typeof row.content === "string" && row.content.trim().length > 0 && (!Array.isArray(row.tool_calls) || row.tool_calls.length === 0)) out.completion = { id: createHash("sha256").update(`${session}:${row.step_index}:${line}`).digest("hex"), index: row.step_index as number };
+      }
+      if (out.completion || start === 0 || window === cap) return out;
+    }
+  } catch { return empty; } finally { if (fd !== undefined) closeSync(fd); }
+}
+
+export const AGY_FACTS_HOOK: NativeFactsPort = { decode: decodeAgyHook, encode: encodeAgyHook, read: readAgyTranscript };

package/src/adapters/claude-channel.ts

@@ -368,6 +368,7 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
     const res = await hub.request({ t: "send", body, to, reply_to });
     if (!res.ok) return text(`not sent: ${res.error}`);
     if (res.recorded) return text("recorded only ([FYI]): it is on the hub console and log, and no peer spent a turn on it");
+    if (res.dropped === "hop") return text(res.notice);
     const sent = `sent to: ${res.targets.join(", ") || "(no other peers attached)"}`;
     return text(typeof res.notice === "string" ? `${sent}; ${res.notice}` : sent);
   }

package/src/adapters/claude-print.ts

@@ -1,10 +1,8 @@
-import { spawn, type ChildProcess } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { childEnv, peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+import { childEnv } from "../hub/child-process.ts";
 import { hubGitSync } from "../hub/git.ts";
 import { changedPathGroups } from "../hub/review-brief.ts";
-import { HUB, frame, type Envelope } from "../hub/envelope.ts";
-import { BasePeer } from "../hub/peers.ts";
+import { type Envelope } from "../hub/envelope.ts";
+import { ReviewerPrintPeer, type ReviewerBackend, type ReviewerPrintOptions } from "./reviewer-print.ts";
 
 export interface ClaudePrintUsage { input_tokens?: number; output_tokens?: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number }
 
@@ -23,6 +21,7 @@ export interface ClaudePrintOptions {
   /** Whether this peer recorded a verdict on the task since `since` (ms). */
   verdictSince(task: number, since: number): boolean;
   onUsage?(usage: ClaudePrintUsage, task: number): void;
+  onUnavailable?: ReviewerPrintOptions["onUnavailable"];
   log?(line: string): void;
 }
 
@@ -74,157 +73,20 @@ export function reviewDiff(cwd: string, commit: unknown, policy: { privatePath(p
   return `Diff of ${commit} against its merge base with the checkout's HEAD:\n${body}${note}`;
 }
 
-/** The review's leader exited but its process group could not be confirmed gone; the child handle is kept. */
-class GroupCleanupError extends Error {}
-
-const reviewTask = (env: Envelope): number | undefined => {
-  if (env.from !== HUB || env.kind !== "review") return undefined;
-  const id = Number(env.refs?.task);
-  return Number.isSafeInteger(id) && id > 0 ? id : undefined;
+export const claudeReviewerBackend: ReviewerBackend = {
+  id: "claude",
+  prepare: async context => ({ command: context.command ?? ["claude"],
+    args: claudePrintArgs(context.sessionId, context.mcpConfig, context.systemPrompt, context.privatePaths),
+    isolation: { backend: "claude", version: "existing-223-contract", binary: (context.command ?? ["claude"])[0]!, profile: "strict-mcp-read-grep-glob",
+      readOnly: true, strictMcp: true, ephemeral: true, evidence: ["#223 fixed native allowlist, strict MCP config and unpersisted session"] } }),
+  usage: event => {
+    const row = event as { type?: string; usage?: ClaudePrintUsage } | null;
+    return row?.type === "result" ? row.usage : undefined;
+  },
 };
 
-/**
- * #223 R3: a hub-native Claude reviewer. Idle with no process; each hub review request runs one `claude -p` child in a
- * new session (never resumed), so no verdict sees an earlier round or builder chat. Its final text is not published:
- * the verdict is the child's own `hub_review` call.
- */
-export class ClaudePrintPeer extends BasePeer {
-  readonly hubNative = true;
-  private generation = 0;
-  private child: ChildProcess | undefined;
-  private activeDeliveryId: string | undefined;
-  /** The task whose review the running child was started for (R4: the hub records `fresh` for its verdict). */
-  reviewing: number | undefined;
-  private reviewSeq = 0;
-  /** Identifies the running child's authority over `task`; a replacement child for the same task gets a new token. */
-  reviewToken(task: number): number | undefined { return this.reviewing === task ? this.reviewSeq : undefined; }
-
-  constructor(id: string, private readonly opts: ClaudePrintOptions) { super(id, opts.watchdogMs); }
-
-  recoveryMetadata(): Record<string, unknown> { return { launch: { kind: "claude-print", peer: this.id } }; }
-
-  async start(): Promise<void> {
-    // A retained child means a review's process group was never confirmed gone: no new review beside it.
-    if (this.child) throw new Error(`${this.id}: an earlier review's process group is still running; stop it first`);
-    this.setState("idle");
-  }
-
-  async stop(reason?: string): Promise<void> {
-    this.generation++; // fence before the first await: a late exit settles nothing
-    this.settle("needs_review", reason ?? "review stopped before settlement");
-    if (this.child) this.setState("busy"); // unavailable, not offline, until the group is confirmed gone
-    await this.kill(); // throws when the child could not be stopped; its handle is kept and the peer stays busy
-    this.setState("offline");
-  }
-
-  protected override onWatchdog(): void {
-    this.generation++;
-    this.settle("needs_review", "review watchdog timeout");
-    // Busy until the old child is gone: a new review never runs beside it.
-    void this.kill().then(() => { if (this.state === "busy") super.onWatchdog(); }, (error: Error) => this.opts.log?.(`[${this.id}] watchdog stop failed, staying busy: ${error.message}`));
-  }
-
-  async deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
-    if (this.state !== "idle") {
-      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} is ${this.state}` });
-      throw new Error(`${this.id} is ${this.state}`);
-    }
-    const generation = ++this.generation;
-    this.activeDeliveryId = deliveryId;
-    this.setState("busy");
-    if (deliveryId) this.delivery({ id: deliveryId, state: "accepted" });
-    void this.run(envs, generation).catch((error: Error) => {
-      if (generation !== this.generation) return;
-      this.settle("needs_review", `claude reviewer failed: ${error.message}`);
-      void this.kill().then(() => this.setState("idle"), () => undefined);
-    });
-  }
-
-  private async run(envs: Envelope[], generation: number): Promise<void> {
-    const missing: number[] = [];
-    let started = false;
-    let failure: { state: "failed_safe" | "needs_review"; reason: string } | undefined;
-    for (const env of envs) {
-      const task = reviewTask(env);
-      if (task === undefined) continue; // a withdrawal or other notice: nothing to review
-      if (env.private) { failure = { state: "needs_review", reason: "a private review is the person's, never a cloud reviewer's" }; break; }
-      const since = Date.now();
-      let code: number | null;
-      try { code = await this.review(env, task, generation); }
-      catch (error) {
-        if (generation !== this.generation) return;
-        if (error instanceof GroupCleanupError) {
-          // 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}`);
-          return;
-        }
-        // Once an earlier review in this batch ran, the batch had effects: hold it for a person, never requeue it.
-        failure = { state: started ? "needs_review" : "failed_safe", reason: `claude reviewer could not start: ${(error as Error).message}` }; break;
-      }
-      started = true;
-      if (generation !== this.generation) return;
-      let recorded = false;
-      try { recorded = this.opts.verdictSince(task, since); } catch (error) { this.opts.log?.(`[${this.id}] verdict check for task #${task} failed: ${(error as Error).message}`); }
-      if (!recorded) missing.push(task);
-      if (code !== 0) this.opts.log?.(`[${this.id}] review of task #${task} exited ${code}`);
-    }
-    if (generation !== this.generation) return;
-    this.settle(failure?.state ?? (missing.length ? "needs_review" : "completed"), failure?.reason ?? (missing.length ? `no verdict recorded for task ${missing.map(id => `#${id}`).join(", ")}` : undefined));
-    this.setState("idle");
-  }
-
-  private review(env: Envelope, task: number, generation: number): Promise<number | null> {
-    const [cmd = "claude", ...prefix] = this.opts.command ?? ["claude"];
-    const args = [...prefix, ...claudePrintArgs(randomUUID(), this.opts.mcpConfig, this.opts.systemPrompt, this.opts.privatePaths)];
-    return new Promise((resolve, reject) => {
-      const child = spawn(cmd, args, { cwd: this.opts.cwd, detached: true, env: peerChildEnv(this.id), stdio: ["pipe", "pipe", "ignore"] });
-      // Owned before any await, so a stop that lands before "spawn" still finds and kills it.
-      this.child = child;
-      child.once("error", error => { if (this.child === child) this.child = 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
-        this.reviewing = task; this.reviewSeq++;
-        let facts: string | undefined;
-        try { facts = this.opts.facts?.(env); } catch (error) { this.opts.log?.(`[${this.id}] review facts for task #${task} failed: ${(error as Error).message}`); }
-        child.stdin!.end(`${frame(env)}${facts ? `\n\n${facts}` : ""}`);
-      });
-      let buffer = "";
-      child.stdout!.on("data", (chunk: Buffer) => {
-        if (generation !== this.generation) return;
-        this.touch();
-        buffer += chunk.toString("utf8");
-        for (let i; (i = buffer.indexOf("\n")) >= 0;) {
-          const line = buffer.slice(0, i); buffer = buffer.slice(i + 1);
-          try {
-            const event = JSON.parse(line) as { type?: string; usage?: ClaudePrintUsage };
-            if (event.type === "result" && event.usage) this.opts.onUsage?.(event.usage, task);
-          } catch { /* not a stream-json line */ }
-        }
-      });
-      child.once("exit", code => {
-        if (this.child === child) this.reviewing = 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).
-        stopOwnedProcess(child, { group: true }).then(() => { if (this.child === child) this.child = undefined; resolve(code); },
-          (error: Error) => reject(new GroupCleanupError(error.message)));
-      });
-    });
-  }
-
-  private settle(state: "completed" | "failed_safe" | "needs_review", reason?: string): void {
-    const id = this.activeDeliveryId;
-    this.activeDeliveryId = undefined;
-    if (id) this.delivery({ id, state, ...(reason ? { reason } : {}) });
-  }
-
-  /** Revokes the verdict authority at once, then stops the child; on failure the handle is kept and the error thrown. */
-  private async kill(): Promise<void> {
-    this.reviewing = undefined;
-    const child = this.child;
-    if (!child) return;
-    await stopOwnedProcess(child, { group: true });
-    if (this.child === child) this.child = undefined;
-  }
+/** Compatibility wrapper for the released Claude transport and its existing tests. */
+export class ClaudePrintPeer extends ReviewerPrintPeer {
+  constructor(id: string, options: ClaudePrintOptions) { super(id, { ...options, backend: claudeReviewerBackend }); }
+  override recoveryMetadata(): Record<string, unknown> { return { launch: { kind: "claude-print", peer: this.id } }; }
 }