@staix/agent-hub 0.12.35 → 0.12.36

package/src/adapters/claude-print.ts

@@ -0,0 +1,230 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { childEnv, peerChildEnv, stopOwnedProcess, trackGroup } 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";
+
+export interface ClaudePrintUsage { input_tokens?: number; output_tokens?: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number }
+
+export interface ClaudePrintOptions {
+  cwd: string;
+  /** The native argv prefix; `claude` from PATH by default. */
+  command?: readonly string[];
+  /** The agent-hub MCP server in tools mode for this instance, as `--mcp-config` JSON. */
+  mcpConfig: string;
+  systemPrompt: string;
+  /** pii.paths and local.deny entries, passed to Claude as Read deny rules. */
+  privatePaths?: readonly string[];
+  watchdogMs: number;
+  /** Facts the hub adds to one review request (a bounded diff of its head); never the builder's narrative. */
+  facts?(env: Envelope): string | undefined;
+  /** Whether this peer recorded a verdict on the task since `since` (ms). */
+  verdictSince(task: number, since: number): boolean;
+  onUsage?(usage: ClaudePrintUsage, task: number): void;
+  log?(line: string): void;
+}
+
+/** The flags that make each review a new, unpersisted session with read-only tools and only the verdict tools. */
+export function claudePrintArgs(sessionId: string, mcpConfig: string, systemPrompt: string, privatePaths: readonly string[] = []): string[] {
+  return ["-p", "--output-format", "stream-json", "--verbose", "--no-session-persistence", "--session-id", sessionId,
+    "--strict-mcp-config", "--mcp-config", mcpConfig, "--setting-sources", "",
+    "--tools", "Read,Grep,Glob", "--allowedTools", "mcp__agent-hub__hub_review", "mcp__agent-hub__hub_task_show", "Read", "Grep", "Glob",
+    ...(privatePaths.length ? ["--disallowedTools", ...readDenyRules(privatePaths)] : []),
+    "--permission-mode", "dontAsk", "--append-system-prompt", systemPrompt];
+}
+
+/**
+ * Claude's own Read deny rules for the project's private paths (pii.paths, local.deny).
+ * ponytail: Claude evaluates these, not the hub's path policy (no symlink or case-alias resolution); the hub's own
+ * guarantee is that it never puts private content into the prompt. Run reviews of private-path work on-prem.
+ */
+export function readDenyRules(paths: readonly string[]): string[] {
+  return paths.flatMap(entry => {
+    const rule = entry.startsWith("/") ? `/${entry}` : `./${entry.replace(/^\.\//, "")}`;
+    return /[*?]/.test(entry) ? [`Read(${rule})`] : [`Read(${rule})`, `Read(${rule.replace(/\/$/, "")}/**)`];
+  });
+}
+
+const DIFF_CAP = 100_000;
+/**
+ * The review's head against its merge base with the project checkout's HEAD, bounded. Only a hex commit id is used.
+ * ponytail: a fixed byte cap; the reviewer reads the rest of the files with Read/Grep, add a per-file summary if reviews
+ * of large changes miss things.
+ */
+export function reviewDiff(cwd: string, commit: unknown, policy: { privatePath(path: string): boolean; nameable(text: string): boolean }): string | undefined {
+  if (typeof commit !== "string" || !/^[0-9a-f]{7,40}$/i.test(commit)) return undefined;
+  const git = (args: string[]) => hubGitSync(["-C", cwd, "diff", "--no-ext-diff", "--no-textconv", "--no-color", "--relative", ...args], { encoding: "utf8", env: childEnv(process.env), maxBuffer: 16 * 1024 * 1024, timeout: 15_000 });
+  const unavailable = `Diff of ${commit} unavailable here; read the changed files with Read and Grep.`;
+  // Paths first, as groups (both sides of a move or copy): a group is withheld whole when any side is private.
+  const groups = changedPathGroups(cwd, commit);
+  if (!groups) return unavailable;
+  const changed = groups.map(g => g.paths);
+  const shownGroups = changed.filter(group => !group.some(path => policy.privatePath(path)));
+  const shown = shownGroups.flat();
+  const hidden = changed.length - shownGroups.length;
+  const note = hidden ? `\n[${hidden} changed file(s) withheld by the project's privacy policy]` : "";
+  if (!shown.length) return `Diff of ${commit}: no changed file can be shown.${note}`;
+  const r = git(["-M", "--stat", "--patch", `HEAD...${commit}`, "--", ...shown.map(path => `:(literal)${path}`)]);
+  if (r.status !== 0 || typeof r.stdout !== "string") return unavailable;
+  if (!policy.nameable(r.stdout)) return `Diff of ${commit} withheld: it matches a private-data pattern. Read the changed files with Read and Grep.${note}`;
+  const bytes = Buffer.from(r.stdout, "utf8");
+  const body = bytes.length > DIFF_CAP ? `${bytes.subarray(0, DIFF_CAP).toString("utf8")}\n[diff cut at ${DIFF_CAP} of ${bytes.length} bytes; read the rest with Read and Grep]` : r.stdout;
+  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;
+};
+
+/**
+ * #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;
+  }
+}

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

@@ -6,7 +6,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 } from "./native-factories.ts";
+import { createCodex, createKimi, createJcode, createPi, createLocal, createClaudeReviewer } 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";
@@ -54,6 +54,21 @@ const hubGrants = {
   "never-ask": "every tool runs without asking, inside the hub sandbox and path guard",
 };
 
+/**
+ * #223: a declared `claude-*` instance with `start_mode: "headless"` and roles exactly ["reviewer"]. The hub runs one
+ * fresh `claude -p` session per review request (src/adapters/claude-print.ts); it never owns a terminal or a session.
+ */
+const CLAUDE_REVIEWER_VARIANT: AdapterDefinition = {
+  api: 1, kind: "claude", displayName: "Claude Code reviewer", family: "claude", transport: "hub-native",
+  roles: Object.freeze(["reviewer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
+  start: { create: createClaudeReviewer, daemonPort: "claude-print", forms: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("claude", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+  identity: { mcp: "env" },
+  permission: { modes: {}, unmanaged: "each review runs read-only (Read, Grep, Glob) and may call only hub_review and hub_task_show" },
+  session: { idField: "sessionId", currentId: () => undefined, freshOnRestore: true, launchKind: "claude-print", crashPlan: () => ({ resume: {}, how: "claude reviewer: starts again; every review runs in a new session" }) },
+  turnEnd: "adapter", budget: { account: "claude" }, routing: { reviewOnly: true },
+  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([
@@ -70,6 +85,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", 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,
   },
   {
     api: 1, kind: "codex", displayName: "Codex", family: "codex", transport: "codex-appserver",

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

@@ -3,9 +3,22 @@ import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import type { ClaudeLaunchRecord } from "../../cli/launch.ts";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+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.
+  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));
+    const hub = await ctx.connect();
+    try {
+      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})`);
+  }
   const { launcherPreview, readControl, recordTerminalLaunch, 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)); }
@@ -14,7 +27,7 @@ export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void>
   const control = readControl(stateDir);
   if (control?.instanceId) {
     process.env.AGENTHUB_INSTANCE_ID = control.instanceId;
-    const terminal = await recordTerminalLaunch("claude", cwd, stateDir, control.instanceId);
+    const terminal = await recordTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd: cwd } : undefined);
     if (!terminal) process.env.AGENTHUB_LAUNCH_ID = randomUUID();
   }
   // `--settings` outranks project and user settings, so the tee has to wrap whichever status line would have won:
@@ -30,19 +43,20 @@ export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void>
   // Turn-free facts and opted-in task sweeps share native PreToolUse/PostToolUse/Stop observations.
   const facts = claudeObservationHooks(projectConfig(), { script: join(cliDir, "facts-hook.ts"), stateDir });
   let previousLaunch: unknown;
-  try { previousLaunch = JSON.parse(readFileSync(join(stateDir, "claude-launch.json"), "utf8")); } catch { /* no previous managed launch */ }
+  try { previousLaunch = JSON.parse(readFileSync(join(stateDir, claudeStateFile("claude-launch", peer)), "utf8")); } catch { /* no previous managed launch */ }
   const launch = buildLaunch("claude", args, { unattended: unattendedEnv, statusLine: { script: join(cliDir, "statusline-tee.ts"), stateDir, ...(original ? { original } : {}) }, ...(facts ? { facts } : {}) });
   let result: Awaited<ReturnType<typeof runClaudeLaunch>>;
   try {
     let launchRecord: ClaudeLaunchRecord | undefined;
     if (control?.instanceId) {
       // Publish only the final launch's installed hook and effective permission flags.
-      launchRecord = { 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 } : {}), 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 } : {}) });
   } finally {
     cleanupClaudeSettings(stateDir, launch.settingsFile);

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

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
-import { rosterInStatus } from "../../hub/status-roster.ts";
+import { bundleInStatus, rosterInStatus } from "../../hub/status-roster.ts";
 
 export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
   const { args, cwd, stateDir, cliDir, unattendedEnv, connect, fail, takeFlags } = ctx;
@@ -18,7 +18,8 @@ export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
     const rostered = rosterInStatus(snapshot, "jcode");
     if (rostered === undefined) fail("cannot read jcode's roster membership from the running hub; upgrade or restart it, then retry (nothing was started)");
     if (!rostered) fail("jcode is off roster; add it with ahub roster add jcode");
-    const written = configureJcodeMcp(cwd, stateDir, resolve(cliDir, "../../plugins/agent-hub/server.js"));
+    // The daemon verifies the entry against its own bundle; fall back to this CLI's copy only for a hub that reports none.
+    const written = configureJcodeMcp(cwd, stateDir, bundleInStatus(snapshot) ?? resolve(cliDir, "../../plugins/agent-hub/server.js"));
     if (written.tracked) console.error(".jcode/mcp.json is tracked; review this local machine-path change before committing it");
     const reply = await hub.request({ t: "start", peer: "jcode", args: { mode: "headless", model: one["--model"], providerProfile: one["--provider-profile"], sessionId: one["--session-id"] }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 65_000);
     if (!reply.ok) fail(reply.error);

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

@@ -1,7 +1,7 @@
 import { resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
-import { rosterInStatus } from "../../hub/status-roster.ts";
+import { bundleInStatus, rosterInStatus } from "../../hub/status-roster.ts";
 
 export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
   const peer = ctx.instance ?? "kimi";
@@ -38,7 +38,8 @@ export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
       if (!admission.ok) fail(admission.error);
       let result: ReturnType<typeof spawnSync>;
       try {
-        const written = configureKimiMcp(cwd, stateDir, resolve(cliDir, "../../plugins/agent-hub/server.js"), "tui");
+        // The daemon's own bundle, so the MCP server matches the hub it talks to (#502); this CLI's copy only for an older hub.
+        const written = configureKimiMcp(cwd, stateDir, bundleInStatus(snapshot) ?? resolve(cliDir, "../../plugins/agent-hub/server.js"), "tui");
         if (written.tracked) console.error(".kimi-code/mcp.json is tracked; the agent-hub entry contains machine paths. Review this local change before committing it.");
         result = spawnSync(launch.cmd, launch.args, { cwd, stdio: "inherit", env: { ...nativeLaunchEnv("kimi", childEnv()), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
       } finally {

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

@@ -5,6 +5,8 @@ import type { AdapterDefinition } from "../registry-types.ts";
 /** Private static builtin relocation ports. The CLI binds identity, project and authority before invocation. */
 export interface NativeCliEntryContext {
   instance?: string; executionCwd?: string;
+  /** #223: the selected instance is started by the hub (a headless reviewer), never as a terminal launch. */
+  hubStarted?: true;
   args: string[]; cwd: string; stateDir: string; cliDir: string; unattendedEnv: boolean; definition: AdapterDefinition;
   projectConfig(): HubConfig;
   connect(): Promise<ControlClient>;

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

@@ -38,6 +38,12 @@ export function createLocal(ctx: CreateContext): PeerAdapter {
   return new LocalPeer(ctx.instance, ctx.daemon.local);
 }
 
+export function createClaudeReviewer(ctx: CreateContext): PeerAdapter {
+  if (!("claudePrint" in ctx.daemon)) throw new Error("Claude reviewer requires its print transport options");
+  const { ClaudePrintPeer } = require("../claude-print.ts") as typeof import("../claude-print.ts");
+  return new ClaudePrintPeer(ctx.instance, ctx.daemon.claudePrint);
+}
+
 /** 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 }),
@@ -45,4 +51,5 @@ export const DAEMON_PORTS = {
   "owned-acp": (options: Extract<DaemonPorts, { jcode: unknown }>["jcode"]) => ({ jcode: options }),
   "pi-rpc": (options: Extract<DaemonPorts, { pi: unknown }>["pi"]) => ({ pi: options }),
   "local-worker": (options: Extract<DaemonPorts, { local: unknown }>["local"]) => ({ local: options }),
+  "claude-print": (options: Extract<DaemonPorts, { claudePrint: unknown }>["claudePrint"]) => ({ claudePrint: options }),
 } satisfies Record<DaemonEngine, unknown>;

package/src/adapters/registry-types.ts

@@ -13,9 +13,10 @@ import type { CodexOptions } from "./codex-appserver.ts";
 import type { JcodeOptions } from "./jcode.ts";
 import type { LocalOptions } from "./local-worker.ts";
 import type { PiOptions } from "./pi.ts";
+import type { ClaudePrintOptions } from "./claude-print.ts";
 
 export type StartForm = "tui" | "headless";
-export type DaemonEngine = "codex-appserver" | "acp" | "owned-acp" | "pi-rpc" | "local-worker";
+export type DaemonEngine = "codex-appserver" | "acp" | "owned-acp" | "pi-rpc" | "local-worker" | "claude-print";
 
 /** Existing buildLaunch inputs plus the startup-bound instance and project identity. */
 export interface LaunchContext {
@@ -53,7 +54,8 @@ export type DaemonPorts =
   | { acp: AcpOptions }
   | { jcode: JcodeOptions }
   | { pi: PiOptions }
-  | { local: LocalOptions };
+  | { local: LocalOptions }
+  | { claudePrint: ClaudePrintOptions };
 
 export interface CreateContext<Ports extends DaemonPorts = DaemonPorts> {
   instance: string;
@@ -223,6 +225,8 @@ export interface AdapterDefinition {
   reporting?: { tokensNotReported?: boolean };
   /** Legacy native routing policy; external definitions cannot claim these host-specific policies. */
   routing?: {
+    /** Takes reviews only: never chosen or nominated as a task owner, for any class. */
+    reviewOnly?: true;
     localAllowedRefusal?: string;
     longContext?: "backend-limit" | "skip-owner";
     preferredTier?: boolean;
@@ -258,6 +262,8 @@ export interface AdapterDefinition {
   };
   display: { palette: { fg: string; bg: string; tone?: string; ansi?: string } };
   hooks?: Partial<NativeHooks>;
+  /** #223: what a declared headless reviewer-only instance of this kind runs as. Fixed builtins only. */
+  reviewerVariant?: AdapterDefinition;
 }
 
 /** Explicit project declarations, passed by the bound host. No process-global instance registration. */

package/src/adapters/registry.ts

@@ -26,6 +26,7 @@ function immutable<T>(value: T, seen = new WeakSet<object>()): T {
 }
 
 const fixedBuiltinDefinitions = new Set<AdapterDefinition>([...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN, QWEN_DEFINITION]);
+for (const definition of [...fixedBuiltinDefinitions]) if (definition.reviewerVariant) fixedBuiltinDefinitions.add(definition.reviewerVariant);
 
 /** Keep the native catalog's order, independently of the legacy default-role object order. */
 export const ADAPTERS: readonly AdapterDefinition[] = immutable([
@@ -37,6 +38,7 @@ const definitions = new Map<string, AdapterDefinition>();
 for (const definition of ADAPTERS) {
   assertDaemonEngine(definition);
   assertNativeCapabilityScope(definition);
+  if (definition.reviewerVariant) { assertDaemonEngine(definition.reviewerVariant); assertNativeCapabilityScope(definition.reviewerVariant); }
   if (definition.api !== ADAPTER_API || definitions.has(definition.kind)) throw new Error("invalid builtin adapter registry");
   definitions.set(definition.kind, definition);
 }
@@ -46,6 +48,13 @@ export const QUOTA_HANDOFF_PLATFORMS: Readonly<Record<string, string>> = Object.
   ADAPTERS.flatMap(adapter => adapter.hooks?.recallPlatform ? [[adapter.kind, adapter.hooks.recallPlatform]] : []),
 ));
 
+/** Own enumerable data field of a plain object, never a caller accessor or an inherited value. */
+function ownField(value: unknown, key: string): unknown {
+  if (!value || typeof value !== "object" || types.isProxy(value) || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return undefined;
+  const field = Object.getOwnPropertyDescriptor(value, key);
+  return field && Object.hasOwn(field, "value") && field.enumerable ? field.value : undefined;
+}
 /** Declaration reads never execute caller accessors or inherit another project's mapping. */
 function declaredKind(id: string, instances: KindMap | undefined): string | undefined {
   if (!instances || typeof instances !== "object" || types.isProxy(instances) || Array.isArray(instances)
@@ -66,7 +75,9 @@ export function kindOf(id: string, instances?: KindMap): string | undefined {
 }
 export function definitionOf(id: string, instances?: KindMap): AdapterDefinition | undefined {
   const kind = kindOf(id, instances);
-  return kind === undefined ? undefined : definitions.get(kind);
+  const definition = kind === undefined ? undefined : definitions.get(kind);
+  // #223: only a declared extra (never the builtin id) with start_mode "headless" runs as the kind's reviewer variant.
+  return definition?.reviewerVariant && kind !== id && ownField(ownField(instances, id), "start_mode") === "headless" ? definition.reviewerVariant : definition;
 }
 export function familyOf(id: string, instances?: KindMap): string | undefined {
   return definitionOf(id, instances)?.family;
@@ -113,6 +124,7 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
     ["session.crashIdentity", declared(definition.session, "crashIdentity")],
     ["start.daemonPort pi-rpc", definition.start.daemonPort === "pi-rpc"],
     ["routing", definition.routing !== undefined],
+    ["reviewerVariant", definition.reviewerVariant !== undefined],
   ];
   const field = restricted.find(([, present]) => present)?.[0];
   if (field) throw new Error(`${field} is restricted to fixed builtin adapter definitions`);

package/src/cli/help.ts

@@ -23,6 +23,10 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub pet [--short]", "read attention without connecting; --short prints ahub!N only when action is needed"],
     ["ahub sdlc status [task] | explain <task> | export <task> | record <task> <receipt-json>", "read head-bound lifecycle gates and the next actor/action (person only)"],
     ["ahub sdlc queue <owner/repo> | release <owner/repo> [live-issue...]", "read-only merge and release evidence (person only)"],
+    ["ahub sdlc accept <task> --issue <n> [--repo owner/repo]", "accept the task's spec issue at its current body; build entry needs it in enforce (person only)"],
+    ["ahub sdlc plan-review <task> <revision> <reason...> [--review full|delta|none --reviewers N --ci full|focused|reuse]", "record planner review, scope and host-read issue metadata"],
+    ["ahub sdlc costs [owner/repo]", "read bounded planner cost metrics for linked merged PRs"],
+    ["ahub backlog groom | return <task> <revision> <reason...>", "read grooming findings or return accepted untouched work to backlog (planner/person)"],
     ["ahub status [--json] [--full] [--color=auto|always|never]", "the hub, its peers, model backends and task counts"],
     ["ahub status --all [--json] [--color=auto|always|never]", "show every registered project"],
     ["ahub logs [-f]", "the last 100 lines of hub.log; -f shows the last 10 and follows it"],
@@ -84,6 +88,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub task cancel <id> --reason <text> [--superseded-by <ref>] [--revision N]", "person only: close obsolete work with a reason; retain its history without stopping native work or releasing dependents"],
     ["ahub task label <id> ok|regressed|reverted|incomplete|wrong|abandoned", "your later verdict on an approved task, kept in the research records (research must be on)"],
     ["ahub review <id> approved|changes_requested [note...] [--unmet <item>]...", "give a review verdict on a task"],
+    ["ahub review brief <id>", "print the review brief of a task's commit: reviewable and excluded files, rules, coverage to account for"],
     ["ahub route explain <id>", "why a task went where it went, its reserved owner included"],
     ["ahub route explain --class <c> <title...>", "what would happen to such a task now"],
     ["ahub ask [--remember] <question...>", "answer from the task board, shared memory and this run's log, with the ids it rests on"],

package/src/cli/identity.ts

@@ -13,13 +13,14 @@ export const LIVE_TEST_PERSON_REFUSAL = "live-test cannot write person-attribute
 
 /** Person verdicts and user-authored workflow content are never delegated. */
 export function liveTestRefusal(command: string, args: readonly string[], context: { repairedFresh?: boolean } = {}): boolean {
+  if (command === "sdlc" && args[0] === "plan-review") return true;
   if (args.some(arg => arg === "--as-user" || arg.startsWith("--as-user="))) return true;
   const sub = command === "recovery" ? recoveryAction(args) : args.find(arg => arg !== "--json");
   return ["task", "role", "goal"].includes(command)
     || (command === "backlog" && sub !== "list") || (command === "release" && !["list", "show"].includes(sub ?? ""))
     || (command === "memory" && sub !== "graph")
     || (command === "recovery" && (sub === "reattach" || sub === "dispose" && context.repairedFresh === true))
-    || (command === "board" && args[0] === "import") || (command === "sdlc" && args[0] === "record")
+    || (command === "board" && args[0] === "import") || (command === "sdlc" && (args[0] === "record" || args[0] === "accept"))
     || (command === "bench" && args.find(arg => arg !== "--json") === "run") || command === "pet";
 }
 

package/src/cli/launch.ts

@@ -1,4 +1,5 @@
 // Launchers inject only the flags the hub owns and refuse user-supplied duplicates.
+import { claudeStateFile } from "../hub/claude-state.ts";
 import { mkdirSync, writeFileSync, renameSync, unlinkSync, lstatSync, readFileSync, openSync, closeSync, readSync, accessSync, constants, linkSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { randomUUID, createHash } from "node:crypto";
@@ -12,10 +13,10 @@ import { kimiAcpCommand } from "../adapters/definitions/native-daemon-kimi.ts";
 export const CLAUDE_CHANNEL = "plugin:agent-hub@agent-hub";
 
 /** Consume only ahub's selector, never native arguments after the passthrough delimiter. */
-export function instanceLaunchArguments(command: string, raw: readonly string[], instances?: InstancesConfig): { instance?: string; args: string[] } {
+export function instanceLaunchArguments(command: string, raw: readonly string[], instances?: InstancesConfig): { instance?: string; args: string[]; hubStarted?: true } {
   if (!definitionOf(command)) return { args: [...raw] };
   const args: string[] = [];
-  let instance: string | undefined;
+  let instance: string | undefined, hubStarted = false;
   for (let index = 0; index < raw.length; index++) {
     const arg = raw[index]!;
     if (arg === "--") { args.push(...raw.slice(index)); break; }
@@ -25,9 +26,19 @@ export function instanceLaunchArguments(command: string, raw: readonly string[],
     if (!id || id.startsWith("--")) throw new Error("--as needs a declared instance id");
     const declaration = instances && Object.hasOwn(instances, id) ? instances[id] : undefined;
     if (!declaration || declaration.kind !== command || !definitionOf(id, instances)) throw new Error("--as must name a declared instance of this command's native kind");
+    // #223: a headless reviewer is started by the hub, never from this terminal.
+    hubStarted = definitionOf(id, instances) === definitionOf(command)?.reviewerVariant;
     instance = id;
   }
-  return { ...(instance ? { instance } : {}), args };
+  if (hubStarted && args.some(arg => arg !== "--print-command" && arg !== "--dry-run")) throw new Error(`${instance} is a headless reviewer the hub runs per review: ahub ${command} --as ${instance} takes no launch arguments`);
+  return { ...(instance ? { instance } : {}), args, ...(hubStarted ? { hubStarted: true as const } : {}) };
+}
+
+/** The running daemon bound this instance at startup; a declaration added later, or an older daemon, is not proof. */
+export function requireActiveInstance(status: unknown, instance: string): void {
+  const active = (status as { activeInstances?: unknown } | undefined)?.activeInstances;
+  if (!Array.isArray(active)) throw new Error("running hub does not report its declared instances; upgrade it before starting an extra instance");
+  if (!active.includes(instance)) throw new Error(`running hub has not loaded the declaration of ${instance}; restart the hub (ahub restart) after declaring it`);
 }
 
 /** Only an authenticated daemon hello can authorize extra-instance effects. */
@@ -92,6 +103,8 @@ export function cleanupStaleClaudeSettings(stateDir: string, previous: unknown,
 
 export interface ClaudeLaunchRecord extends Record<string, unknown> {
   instanceId: string; launchId: string; settingsFile?: string; launcherPid: number; launcherSignature?: string;
+  /** A claude-<name> instance (#450 I3); absent for the builtin claude peer, whose file keeps its original name. */
+  peer?: string;
 }
 
 export interface ClaudeLaunchPublication { recorded: boolean; warning?: string; }
@@ -144,7 +157,7 @@ async function withClaudeLaunchRecord(stateDir: string, action: () => void): Pro
 }
 
 function writeClaudeLaunchRecord(stateDir: string, record: Record<string, unknown>): void {
-  const file = join(stateDir, "claude-launch.json"), temp = `${file}.${randomUUID()}.tmp`;
+  const file = join(stateDir, claudeStateFile("claude-launch", typeof record.peer === "string" ? record.peer : "claude")), temp = `${file}.${randomUUID()}.tmp`;
   try { writeFileSync(temp, JSON.stringify(record), { mode: 0o600 }); renameSync(temp, file); }
   finally { try { unlinkSync(temp); } catch { /* the rename normally consumed it */ } }
 }
@@ -187,7 +200,7 @@ export async function recordClaudeNative(stateDir: string, launch: ClaudeLaunchR
   const publication = await withClaudeLaunchRecord(stateDir, () => {
     let current: ClaudeLaunchRecord;
     try {
-      const file = join(stateDir, "claude-launch.json"), stat = lstatSync(file);
+      const file = join(stateDir, claudeStateFile("claude-launch", launch.peer ?? "claude")), stat = lstatSync(file);
       if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || !process.getuid || stat.uid !== process.getuid()) return;
       current = JSON.parse(readFileSync(file, "utf8"));
     } catch { return; }
@@ -204,7 +217,7 @@ export async function recordClaudeNative(stateDir: string, launch: ClaudeLaunchR
       writeFileSync(temp, JSON.stringify({ ...launch, nativePid: pid, nativeSignature: signature, nativeIdentity: "direct-child" }), { mode: 0o600, flag: "wx" });
       renameSync(temp, file);
     } finally { try { unlinkSync(temp); } catch { /* atomic rename consumed our private temporary file */ } }
-    try { recorded = sameClaudeLaunch(JSON.parse(readFileSync(join(stateDir, "claude-launch.json"), "utf8")), launch); } catch { /* replaced or unreadable managed record */ }
+    try { recorded = sameClaudeLaunch(JSON.parse(readFileSync(join(stateDir, claudeStateFile("claude-launch", launch.peer ?? "claude")), "utf8")), launch); } catch { /* replaced or unreadable managed record */ }
   });
   if (publication.warning) report?.(publication.warning);
   return publication.recorded && recorded;