@staix/agent-hub 0.12.34 → 0.12.36

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

@@ -1,8 +1,10 @@
 import { resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+import { bundleInStatus, rosterInStatus } from "../../hub/status-roster.ts";
 
 export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const peer = ctx.instance ?? "kimi";
   const { args, cwd, stateDir, cliDir, unattendedEnv, projectConfig, connect, fail, takeFlags } = ctx;
   const { launcherPreview, startModeOf, buildKimiTuiLaunch, configureKimiMcp, nativeLaunchEnv, childEnv } = ctx.helpers;
   if (args.includes("--print-command") || args.includes("--dry-run")) {
@@ -10,13 +12,14 @@ export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
     catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
   }
   const { one, rest } = takeFlags(args, ["--mode", "--model"], []);
-  const mode = one["--mode"] ?? startModeOf(projectConfig().peers, "kimi"), model = one["--model"];
+  const mode = one["--mode"] ?? (ctx.instance ? "headless" : startModeOf(projectConfig().peers, "kimi")), model = one["--model"];
+  if (ctx.instance && mode !== "headless") fail("extra Kimi instances require headless mode");
   if (rest.length || !["tui", "headless"].includes(mode)) fail("usage: ahub kimi [--mode tui|headless] [--model <alias>]");
   if (mode === "tui" && one["--mode"] === undefined && !(process.stdin.isTTY && process.stdout.isTTY)) {
     if (model) fail("Kimi's TUI needs a terminal for these options; run in a terminal or add --mode headless");
     const hub = await connect();
     try {
-      const reply = await hub.request({ t: "peer_start", peer: "kimi" }, 35_000);
+      const reply = await hub.request({ t: "peer_start", peer }, 35_000);
       if (!reply.ok) fail(reply.error);
       return console.log(reply.already ? "kimi is already attached" : `kimi: opened a terminal running ${reply.command}; it attaches pull-only when its TUI is ready`);
     } finally { hub.close(); }
@@ -26,14 +29,17 @@ export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
     if (mode === "tui") {
       const launch = buildKimiTuiLaunch(projectConfig().kimi_cmd, model);
       const snapshot = (await hub.request({ t: "status" })).status;
-      if (snapshot?.roster?.find((row: any) => row.peer === "kimi")?.on === false) fail("kimi is off roster; add it with ahub roster add kimi");
-      const peer = snapshot?.peers?.kimi;
-      if (peer && !["offline"].includes(peer.state) && !peer.pullOnly) fail("Kimi is running headless; run ahub stop kimi before starting its TUI");
-      const admission = await hub.request({ t: "start", peer: "kimi", args: { mode: "tui" }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+      const rostered = rosterInStatus(snapshot, peer);
+      if (rostered === undefined) fail("cannot read kimi's roster membership from the running hub; upgrade or restart it, then retry (nothing was started)");
+      if (!rostered) fail("kimi is off roster; add it with ahub roster add kimi");
+      const owner = snapshot?.peers?.[peer];
+      if (owner && !["offline"].includes(owner.state) && !owner.pullOnly) fail("Kimi is running headless; run ahub stop kimi before starting its TUI");
+      const admission = await hub.request({ t: "start", peer, args: { mode: "tui" }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
       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 {
@@ -42,11 +48,11 @@ export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
       if (result.error) fail(`cannot run ${launch.cmd}: ${result.error.message}`);
       process.exit(result.status ?? 1);
     }
-    const peer = (await hub.request({ t: "status" })).status?.peers?.kimi;
-    if (peer?.pullOnly && peer.state !== "offline") fail("Kimi runs in a terminal; end it there before starting a headless one");
-    configureKimiMcp(cwd, stateDir, resolve(cliDir, "../../plugins/agent-hub/server.js"), "headless");
-    const res = await hub.request({ t: "start", peer: "kimi", args: { mode: "headless", model }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+    const owner = (await hub.request({ t: "status" })).status?.peers?.[peer];
+    if (owner?.pullOnly && owner.state !== "offline") fail("Kimi runs in a terminal; end it there before starting a headless one");
+    if (!ctx.instance) configureKimiMcp(cwd, stateDir, resolve(cliDir, "../../plugins/agent-hub/server.js"), "headless");
+    const res = await hub.request({ t: "start", peer, args: { mode: "headless", model }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
     if (!res.ok) fail(res.error);
-    console.log(res.already ? "kimi is already attached" : 'kimi attached (headless). Talk to it with: ahub say @kimi "..."');
+    console.log(res.already ? `${peer} is already attached` : `${peer} attached (headless). Talk to it with: ahub say @${peer} "..."`);
   } finally { hub.close(); }
 }

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

@@ -1,14 +1,15 @@
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 
 export async function runLocalEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const peer = ctx.instance ?? "local";
   const { args, connect, fail } = ctx;
   const opt = (flag: string) => (args.includes(flag) ? args[args.indexOf(flag) + 1] ?? fail(`${flag} needs a value`) : undefined);
   for (const flag of ["--route", "--model"]) if (args.includes(flag) && (!opt(flag) || opt(flag)!.startsWith("--"))) fail(`${flag} needs a value`);
   if (args.includes("--route") && args.includes("--model")) fail("use --route or --model, not both");
   if (args.some((a, i) => i % 2 === 0 && !["--route", "--model"].includes(a))) fail("usage: ahub local [--route <id> | --model <id>]");
   const hub = await connect();
-  const res = await hub.request({ t: "start", peer: "local", args: { route: opt("--route"), model: opt("--model") }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+  const res = await hub.request({ t: "start", peer, args: { route: opt("--route"), model: opt("--model") }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
   hub.close();
   if (!res.ok) fail(res.error);
-  console.log(res.already ? "local is already attached" : `local attached on ${res.model}. Give it work with: ahub say @local "..."`);
+  console.log(res.already ? `${peer} is already attached` : `${peer} attached on ${res.model}. Give it work with: ahub say @${peer} "..."`);
 }

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

@@ -2,6 +2,7 @@ import { parsePiFlags } from "./native-cli-pi.ts";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 
 export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const peer = ctx.instance ?? "pi";
   const { args, cwd, stateDir, unattendedEnv, projectConfig, connect, fail, execWithEnv } = ctx;
   const { launcherPreview, startModeOf, recoveryLock, readControl, recordTerminalLaunch } = ctx.helpers;
   // --headless is --mode headless everywhere this command goes: the preview, the hub and the conductor path.
@@ -12,7 +13,8 @@ export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
   }
   const flags = parsePiFlags(args, fail);
   // #269: with no flag, Pi's start mode decides, and that is its TUI unless a person set headless.
-  const options = { ...flags, mode: flags.mode ?? startModeOf(projectConfig().peers, "pi") };
+  const options = { ...flags, mode: flags.mode ?? (ctx.instance ? "headless" : startModeOf(projectConfig().peers, "pi")) };
+  if (ctx.instance && options.mode !== "headless") fail("extra Pi instances require headless mode");
   if (flags.mode === undefined && options.mode === "tui" && !(process.stdin.isTTY && process.stdout.isTTY)) {
     // The default asked for the TUI and there is no terminal here (the console's command line, a script): the hub
     // opens one, or says how to. It is never downgraded to headless. The fixed command carries no option, so one
@@ -20,7 +22,7 @@ export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
     if (Object.keys(flags).length) fail("Pi's TUI needs a terminal, and these options are not passed to one the hub opens: run this in a terminal, or add --mode headless");
     const hub = await connect();
     try {
-      const reply = await hub.request({ t: "peer_start", peer: "pi" }, 35_000);
+      const reply = await hub.request({ t: "peer_start", peer }, 35_000);
       if (reply.ok !== true) {
         const error = String(reply.error ?? "pi start refused");
         fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "peer_start"/i.test(error) ? `${error}; upgrade the running hub, or run ahub pi --mode headless` : error);
@@ -32,9 +34,9 @@ export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
   // trip, so a resume in that window never reads it as gone; an ordinary launch records only after the hub accepted it.
   const recovering = options.mode === "tui" && !!process.env.AGENTHUB_RECOVERY_OPERATION && process.env.AGENTHUB_RECOVERY_OPERATION === recoveryLock();
   const before = readControl(stateDir);
-  if (recovering && before?.instanceId) await recordTerminalLaunch("pi", cwd, stateDir, before.instanceId);
+  if (recovering && before?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, before.instanceId);
   const hub = await connect();
-  const res = await hub.request({ t: "start", peer: "pi", args: options, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+  const res = await hub.request({ t: "start", peer, args: options, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
   hub.close();
   if (!res.ok) fail(res.error);
   if (options.mode === "tui") {
@@ -44,8 +46,8 @@ export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
     delete launchEnv.AGENTHUB_RECOVERY_OPERATION;
     delete launchEnv.AGENTHUB_UNATTENDED;
     const control = readControl(stateDir);
-    if (!recovering && control?.instanceId) await recordTerminalLaunch("pi", cwd, stateDir, control.instanceId);
+    if (!recovering && control?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, control.instanceId);
     return execWithEnv(launch.cmd, launch.args, launchEnv);
   }
-  console.log(res.already ? "pi is already attached" : 'pi attached (headless). Talk to it with: ahub say @pi "..."');
+  console.log(res.already ? `${peer} is already attached` : `${peer} attached (headless). Talk to it with: ahub say @${peer} "..."`);
 }

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

@@ -1,6 +1,7 @@
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 
 export async function runQwenEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const peer = ctx.instance ?? "qwen";
   const { args, cwd, stateDir, unattendedEnv, connect, fail, takeFlags } = ctx;
   const { launcherPreview } = ctx.helpers;
   if (args.includes("--print-command") || args.includes("--dry-run")) {
@@ -13,8 +14,8 @@ export async function runQwenEntry(ctx: NativeCliEntryContext): Promise<void> {
   if (rest.length || (one["--mode"] !== undefined && !(adapter.start.forms as readonly string[]).includes(one["--mode"]))) fail("Qwen TUI is not offered before verification; usage: ahub qwen [--mode headless] [--model <alias>] [--session-id <id>]");
   const hub = await connect();
   try {
-    const reply = await hub.request({ t: "start", peer: "qwen", args: { mode: "headless", ...(one["--model"] ? { model: one["--model"] } : {}), ...(one["--session-id"] ? { sessionId: one["--session-id"] } : {}) }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 35_000);
+    const reply = await hub.request({ t: "start", peer, args: { mode: "headless", ...(one["--model"] ? { model: one["--model"] } : {}), ...(one["--session-id"] ? { sessionId: one["--session-id"] } : {}) }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 35_000);
     if (!reply.ok) fail(reply.error);
-    console.log(reply.already ? "qwen is already attached" : "qwen attached (headless); use ahub say @qwen and the console for approvals");
+    console.log(reply.already ? `${peer} is already attached` : `${peer} attached (headless); use ahub say @${peer} and the console for approvals`);
   } finally { hub.close(); }
 }

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

@@ -4,6 +4,9 @@ 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/definitions/native-recovery.ts

@@ -33,10 +33,10 @@ export const CODEX_RECOVERY_SESSION: SessionPolicy = {
     if (phase !== "plan") return false;
     let current: string | undefined, started = false, turned = false;
     for (const e of readEvents(join(stateDir, "events.jsonl"))) {
-      if (e.type === "native_thread" && e.peer === "codex") {
+      if (e.type === "native_thread" && e.peer === binding.peer) {
         current = e.thread;
         if (e.thread === binding.sessionId && e.fresh) started = true;
-      } else if (e.type === "turn_start" && e.peer === "codex" && current === binding.sessionId) turned = true;
+      } else if (e.type === "turn_start" && e.peer === binding.peer && current === binding.sessionId) turned = true;
     }
     return started && !turned;
   },

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

@@ -7,9 +7,9 @@ export class QwenIdentityError extends Error {
   constructor() { super("Qwen Code 0.25.0 native identity is not verified; check the executable and its advertised ACP version"); }
 }
 
-export function qwenNativeIdentity(instance: string, production: boolean | undefined, init: unknown): boolean {
+export function qwenNativeIdentity(instance: string, production: boolean | undefined, init: unknown, kind?: string): boolean {
   const native = init as { agentInfo?: { name?: unknown; version?: unknown } } | null | undefined;
-  const verified = production === true && instance === "qwen" && native?.agentInfo?.name === "qwen-code" && native?.agentInfo?.version === "0.25.0";
+  const verified = production === true && (kind ?? instance) === "qwen" && native?.agentInfo?.name === "qwen-code" && native?.agentInfo?.version === "0.25.0";
   if (production && !verified) throw new QwenIdentityError();
   return verified;
 }

package/src/adapters/local-worker.ts

@@ -18,6 +18,7 @@ import type { ExecutionBudgetDecision } from "../hub/execution-budget.ts";
 export interface LocalOptions {
   profile?: import("../hub/profiles.ts").ProfileSelection;
   sdlcStages?: readonly string[];
+  sdlcCriteria?: boolean;
   cwd: string;
   omni: OmniRoute;
   /** Absent = always the fixed model on OmniRoute. */
@@ -108,7 +109,7 @@ export class LocalPeer extends BasePeer {
         await this.requireBudget(envs, "model_calls");
         if (generation !== this.turn) throw new Error("route belongs to an ended turn");
         if (signal.aborted) throw new Error("turn cancelled before model request");
-        const tools = judge ? undefined : [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
+        const tools = judge ? undefined : [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
         const result = await this.opts.omni.chat({ model, messages, ...(tools ? { tools } : {}), ...(judge ? { max_tokens: maxTokens ?? 2048 } : {}) }, { signal, ...(pii ? { onCampusOnly: true } : {}) });
         this.recordUsage(result, model, task);
         if (generation !== this.turn) throw new Error("route belongs to an ended turn");
@@ -378,7 +379,7 @@ export class LocalPeer extends BasePeer {
     const route = policy?.route ?? this.opts.route;
     const fixedModel = policy?.fixedModel ?? this.opts.fixedModel;
     const task = policy?.task === undefined ? undefined : Number(policy.task);
-    const tools = [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
+    const tools = [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
     const signal = this.abort!.signal;
     const messages: ChatMessage[] = [{ role: "system", content: system(this.opts.cwd, this.opts.preamble) }, ...this.history, ...turnMsgs];
     const routed = await this.hubCall(route, messages, policy, signal);

package/src/adapters/pi.ts

@@ -33,6 +33,8 @@ class PiPromptNotStarted extends Error {
 }
 class PiPromptUncertain extends Error {}
 export interface PiOptions {
+  /** stateDir owns this native instance; hubStateDir retains the canonical daemon binding. */
+  hubStateDir?: string;
   cwd: string; stateDir: string; cmd?: string[]; mode: "headless" | "tui"; backend: "auto" | "dgx" | "mlx"; sessionFile?: string; sessionId?: string;
   model?: string;
   relay: PiRelay; executeTool: (name: string, args: unknown, toolCallId: string, sessionId?: string, signal?: AbortSignal, context?: PiToolContext) => Promise<string | PiToolResult>; tools: PiToolSchema[];
@@ -385,7 +387,7 @@ export class PiPeer extends BasePeer {
     const extension = resolve(join(import.meta.dir, "../pi/extension.ts"));
     const inherited: NodeJS.ProcessEnv = {};
     for (const key of ["PATH", "HOME", "USER", "SHELL", "TMPDIR", "TERM", "TERM_PROGRAM", "LANG", "LC_ALL", "LC_CTYPE", "NO_COLOR", "CODEX_HOME"]) if (process.env[key]) inherited[key] = process.env[key];
-    this._tuiLaunch = buildPiLaunch(this.opts, inherited, extension, bridge.port!, token);
+    this._tuiLaunch = buildPiLaunch({ ...this.opts, instance: this.id }, inherited, extension, bridge.port!, token);
     const { cmd: bin, args, env } = this._tuiLaunch;
     if (this.opts.mode === "tui") { return; }
     // Its own process group, stopped as a whole (#115, as Codex's in #113).

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,4 +262,9 @@ 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. */
+export type KindMap = Readonly<Record<string, { readonly kind: string }>>;

package/src/adapters/registry.ts

@@ -4,7 +4,8 @@ import { DAEMON_PORTS } from "./definitions/native-factories.ts";
 export { DAEMON_PORTS };
 import { NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN } from "./definitions/builtin-metadata.ts";
 import { QWEN_DEFINITION } from "./definitions/qwen.ts";
-import type { AdapterDefinition } from "./registry-types.ts";
+import type { AdapterDefinition, KindMap } from "./registry-types.ts";
+import { types } from "node:util";
 
 export type * from "./registry-types.ts";
 export const ADAPTER_API = 1;
@@ -25,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([
@@ -36,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);
 }
@@ -45,15 +48,39 @@ export const QUOTA_HANDOFF_PLATFORMS: Readonly<Record<string, string>> = Object.
   ADAPTERS.flatMap(adapter => adapter.hooks?.recallPlatform ? [[adapter.kind, adapter.hooks.recallPlatform]] : []),
 ));
 
-/** A1 registers kinds only. Undeclared suffixes never acquire a native kind or admission. */
-export function kindOf(id: string): string | undefined {
-  return definitions.has(id) ? id : undefined;
+/** 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;
 }
-export function definitionOf(id: string): AdapterDefinition | undefined {
-  return definitions.get(id);
+/** 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)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(instances))) return undefined;
+  const field = Object.getOwnPropertyDescriptor(instances, id);
+  if (!field || !Object.hasOwn(field, "value") || !field.enumerable) return undefined;
+  const entry: unknown = field.value;
+  if (!entry || typeof entry !== "object" || types.isProxy(entry) || Array.isArray(entry)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(entry))) return undefined;
+  const kind = Object.getOwnPropertyDescriptor(entry, "kind");
+  if (!kind || !Object.hasOwn(kind, "value") || !kind.enumerable || typeof kind.value !== "string" || !definitions.has(kind.value)) return undefined;
+  const prefix = `${kind.value}-`;
+  return /^[a-z][a-z0-9-]{0,31}$/.test(id) && id.startsWith(prefix) && /^[a-z0-9][a-z0-9-]*$/.test(id.slice(prefix.length)) ? kind.value : undefined;
 }
-export function familyOf(id: string): string | undefined {
-  return definitionOf(id)?.family;
+/** Legacy ids retain their identity. Extra instances resolve only through the explicit project map. */
+export function kindOf(id: string, instances?: KindMap): string | undefined {
+  return definitions.has(id) ? id : typeof id === "string" ? declaredKind(id, instances) : undefined;
+}
+export function definitionOf(id: string, instances?: KindMap): AdapterDefinition | undefined {
+  const kind = kindOf(id, instances);
+  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;
 }
 
 /** Compatibility projection order is observable in default role maps and planner selection. */
@@ -97,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

@@ -1,5 +1,5 @@
 import { recoveryPresentationFlag } from "./recovery-presentation-options.ts";
-import { definitionOf } from "../adapters/registry.ts";
+import { definitionOf, kindOf, type KindMap } from "../adapters/registry.ts";
 
 /** Recovery reads this declaration before delegating to another package's CLI. */
 export const LIVE_TEST_SUPPORTED = true;
@@ -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";
 }
 
@@ -29,7 +30,7 @@ export type CliIdentity =
   | { role: "invalid"; reason: string };
 
 /** Honest defaults for native shells, not authentication against an agent that can edit its environment. */
-export function detectCliIdentity(env: Readonly<Record<string, string | undefined>>): CliIdentity {
+export function detectCliIdentity(env: Readonly<Record<string, string | undefined>>, instances?: KindMap): CliIdentity {
   const hub = env.AGENTHUB_PEER_ID;
   const claude = env.CLAUDECODE;
   const session = env.CLAUDE_CODE_SESSION_ID;
@@ -42,7 +43,7 @@ export function detectCliIdentity(env: Readonly<Record<string, string | undefine
   if (session !== undefined && claude === undefined) return invalid("CLAUDE_CODE_SESSION_ID without CLAUDECODE marker");
   if (claude !== undefined && codex !== undefined) return invalid("conflicting native agent markers");
   const native = claude !== undefined ? "claude" : codex !== undefined ? "codex" : undefined;
-  if (hub !== undefined && native !== undefined && hub !== native) return invalid("AGENTHUB_PEER_ID conflicts with native agent marker");
+  if (hub !== undefined && native !== undefined && (kindOf(hub, instances) ?? hub) !== native) return invalid("AGENTHUB_PEER_ID conflicts with native agent marker");
   const peer = hub ?? native;
   return peer === undefined ? { role: "console" } : { role: "tools", peer };
 }

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";
@@ -7,15 +8,50 @@ import { processLiveness, processSignature } from "../pi/process-signature.ts";
 import { realPath } from "../hub/project.ts";
 import { peerChildEnv, processTable } from "../hub/child-process.ts";
 import { definitionOf } from "../adapters/registry.ts";
+import type { InstancesConfig } from "../hub/instances.ts";
 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[]; hubStarted?: true } {
+  if (!definitionOf(command)) return { args: [...raw] };
+  const args: string[] = [];
+  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; }
+    if (arg !== "--as" && !arg.startsWith("--as=")) { args.push(arg); continue; }
+    if (instance !== undefined) throw new Error("--as may appear only once");
+    const id = arg === "--as" ? raw[++index] : arg.slice("--as=".length);
+    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;
+  }
+  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. */
+export function requirePeerInstances(features: unknown): void {
+  if (!Array.isArray(features) || !features.includes("peer_instances")) throw new Error("running hub lacks peer_instances; upgrade it before starting an extra instance");
+}
+
 /** Launch identity belongs to the native child, never to the agent that invoked the wrapper. */
-export function nativeLaunchEnv(tool: "claude" | "codex" | "pi" | "kimi", source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+export function nativeLaunchEnv(tool: string, source: NodeJS.ProcessEnv, instances?: InstancesConfig): NodeJS.ProcessEnv {
   const env = peerChildEnv(tool, source);
   delete env.AGENTHUB_UNATTENDED;
   // Channel evidence for the plugin (issue #205): set beside the development-channel flag `buildLaunch` always passes.
-  const definition = definitionOf(tool);
+  const definition = definitionOf(tool, instances);
   if (definition?.identity.mcp === "channel-plugin") env.AGENTHUB_CHANNEL = "1";
   if (definition?.attach?.pullOnlyForms?.includes("tui")) delete env.AGENTHUB_MODE; // its MCP child must attach pull-only, never as a tools socket
   return env;
@@ -67,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; }
@@ -119,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 */ } }
 }
@@ -162,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; }
@@ -179,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;
@@ -289,12 +327,12 @@ export function sessionSettings(tee?: StatusLineTee, facts?: FactsHook): string
 export function buildLaunch(
   tool: "claude" | "codex",
   userArgs: string[],
-  ctx: { unattended: boolean; proxyUrl?: string; codexBin?: string; statusLine?: StatusLineTee; facts?: FactsHook; preview?: boolean },
+  ctx: { instance?: string; unattended: boolean; proxyUrl?: string; codexBin?: string; statusLine?: StatusLineTee; facts?: FactsHook; preview?: boolean },
 ): Launch {
   const adapter = definitionOf(tool);
   if (!adapter) throw new Error("native launch definition unavailable");
   const { metadata: _metadata, ...launch } = adapter.start.launch({
-    instance: tool, form: "tui", projectRoot: process.cwd(), stateDir: ctx.facts?.stateDir ?? ctx.statusLine?.stateDir ?? "",
+    instance: ctx.instance ?? tool, form: "tui", projectRoot: process.cwd(), stateDir: ctx.facts?.stateDir ?? ctx.statusLine?.stateDir ?? "",
     entrypoint: resolve(import.meta.dir, "main.js"), userArgs, env: {}, ...ctx,
   });
   return launch;