@staix/agent-hub 0.12.35 → 0.12.37

package/src/adapters/definitions/reviewer-variants.ts

@@ -0,0 +1,32 @@
+import type { AdapterDefinition } from "../registry-types.ts";
+import { claudeReviewerBackend } from "../claude-print.ts";
+import { codexReviewerBackend } from "../codex-review-isolation.ts";
+import { createReviewer, createCodexReviewer } from "./native-factories.ts";
+import { CODEX_DISPLAY, KIMI_DISPLAY } from "./native-display.ts";
+
+export { claudeReviewerBackend };
+/** No launch path is exposed by metadata-only placeholders. */
+function unavailableLaunch(): never { throw new Error("Reviewer unavailable: verified runtime support is deferred to #533"); }
+
+function reviewerVariant(kind: string, displayName: string, reviewer: NonNullable<AdapterDefinition["reviewer"]>, display: AdapterDefinition["display"]): AdapterDefinition {
+  return {
+    api: 1, kind, family: kind, displayName, transport: "hub-native", roles: ["reviewer"],
+    defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: false },
+    start: { ...(reviewer.backend ? { create: createReviewer, daemonPort: "reviewer-print" as const } : {}), forms: ["headless"], defaultForm: "headless", ownsTerminal: () => false,
+      launch: unavailableLaunch,
+      conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    identity: { mcp: "env" },
+    permission: { modes: {}, readOnly: { kind: "hub-gate", allow: ["read", "search", "think"] }, unmanaged: "fresh read-only reviewer; an isolation receipt is required before startup" },
+    session: { idField: "sessionId", currentId: () => undefined, freshOnRestore: true, launchKind: "reviewer-print", crashPlan: () => ({ resume: {}, how: "starts a fresh isolated review session" }) },
+    turnEnd: "adapter", budget: { account: kind }, routing: { reviewOnly: true },
+    reviewer, cli: { command: kind, startWords: () => [] }, display,
+  };
+}
+const codexVariant = reviewerVariant("codex", "Codex reviewer", { backend: codexReviewerBackend, defaultPool: true, declaration: "explicit" }, CODEX_DISPLAY);
+export const CODEX_REVIEWER_VARIANT: AdapterDefinition = { ...codexVariant, start: { ...codexVariant.start, create: createCodexReviewer } };
+export const KIMI_REVIEWER_VARIANT = reviewerVariant("kimi", "Kimi reviewer", { defaultPool: false, declaration: "explicit", unavailable: "Kimi reviewer unavailable: runtime and isolation verification deferred to #533" }, KIMI_DISPLAY);
+/** Data-only declared placeholder for route explanations; no factory, backend or native argv. */
+export const AGY_DEFINITION: AdapterDefinition = {
+  ...reviewerVariant("agy", "agy reviewer", { defaultPool: false, declaration: "automatic", unavailable: "agy reviewer unavailable: native adapter and isolation verification deferred to #533" }, { palette: { fg: "#6558a6", bg: "#f1effa" } }),
+  optional: true,
+};

package/src/adapters/jcode.ts

@@ -17,15 +17,29 @@ export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: s
   return [...command, kind, "--socket", socket, "--cwd", cwd, "--no-update", "--no-selfdev", ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : []),
     ...(kind === "serve" ? ["--temporary-server", "--owner-pid", String(process.pid), "--server-name", "agent-hub-jcode"] : ["--mcp-tools", "eager"])];
 }
+/** Set on every owned jcode process: no Claude MCP import, and no native telemetry (jcode-telemetry-core is_enabled, #529). */
+const JCODE_OWNED_ENV = { JCODE_DISABLE_CLAUDE_MCP: "1", JCODE_NO_TELEMETRY: "1" } as const;
+/** The oldest native release accepted; its ACP, serve and MCP contract was verified live on 0.98.1 (docs/verification). */
+export const JCODE_MIN_VERSION = "0.98.0";
+/** The first native release assumed to break that contract: the next major. Lower it when a release is shown to break. */
+export const JCODE_BREAKING_VERSION = "1.0.0";
+const release = (version: string) => /^(\d+)\.(\d+)\.(\d+)$/.exec(version)?.slice(1).map(Number);
+const compare = (a: number[], b: number[]) => a[0]! - b[0]! || a[1]! - b[1]! || a[2]! - b[2]!;
+/** A plain release from JCODE_MIN_VERSION up to, not including, JCODE_BREAKING_VERSION; the minor is not pinned (#529). */
+export function jcodeVersionSupported(version: unknown): boolean {
+  const v = typeof version === "string" ? release(version) : undefined;
+  return !!v && compare(v, release(JCODE_MIN_VERSION)!) >= 0 && compare(v, release(JCODE_BREAKING_VERSION)!) < 0;
+}
+
 /** The wrapper contract preserves every configured prefix argument before the native probe. */
 export function verifiedJcodeCommand(command: string[], cwd: string): boolean {
   const [bin, ...prefix] = command;
   if (!bin) return false;
   try {
-    const result = spawnSync(bin, [...prefix, "--quiet", "version", "--json"], { cwd, env: peerChildEnv("jcode"), encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024 });
+    const result = spawnSync(bin, [...prefix, "--quiet", "version", "--json"], { cwd, env: { ...peerChildEnv("jcode"), ...JCODE_OWNED_ENV }, encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024 });
     if (result.status !== 0) return false;
     const version = JSON.parse(result.stdout);
-    return version.semver === "0.94.0";
+    return jcodeVersionSupported(version.semver);
   } catch { return false; }
 }
 
@@ -41,9 +55,10 @@ export class JcodePeer extends AcpPeer {
   constructor(private readonly jcode: JcodeOptions) {
     if (!isAbsolute(jcode.home)) throw new Error("jcode_home must be an absolute native data path");
     jcodeCommand(jcode.command, "acp", "preview", jcode.cwd);
-    const root = mkdtempSync(join(tmpdir(), "ahub-jcode-")), socket = join(root, "s");
+    // The name must end in ".sock": jcode names its debug socket by replacing that suffix, so "s" binds one path twice.
+    const root = mkdtempSync(join(tmpdir(), "ahub-jcode-")), socket = join(root, "j.sock");
     const cmd = jcodeCommand(jcode.command, "acp", socket, jcode.cwd, jcode.launchModel, jcode.providerProfile);
-    super("jcode", { ...jcode, cmd, env: { ...jcode.env, JCODE_HOME: jcode.home, JCODE_SOCKET: socket, JCODE_DISABLE_CLAUDE_MCP: "1" }, mcpServers: [], requireLoadSessionEcho: true, expectedAgent: { name: "jcode", version: "0.94.0" } });
+    super("jcode", { ...jcode, cmd, env: { ...jcode.env, JCODE_HOME: jcode.home, JCODE_SOCKET: socket, ...JCODE_OWNED_ENV }, mcpServers: [], requireLoadSessionEcho: true, expectedAgent: { name: "jcode", version: jcodeVersionSupported } });
     this.root = root; this.socket = socket;
   }
 
@@ -53,7 +68,7 @@ export class JcodePeer extends AcpPeer {
     if (existsSync(this.socket)) { this.preserveRoot = true; throw new Error("Jcode private socket is occupied; no daemon was adopted or removed"); }
     this.ending = false;
     const [bin, ...args] = jcodeCommand(this.jcode.command, "serve", this.socket, this.jcode.cwd, this.jcode.launchModel, this.jcode.providerProfile);
-    const server = spawn(bin!, args, { cwd: this.jcode.cwd, detached: true, env: { ...peerChildEnv("jcode"), JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, JCODE_READY_FD: "3", JCODE_DISABLE_CLAUDE_MCP: "1" }, stdio: ["ignore", "ignore", "ignore", "pipe"] });
+    const server = spawn(bin!, args, { cwd: this.jcode.cwd, detached: true, env: { ...peerChildEnv("jcode"), JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, JCODE_READY_FD: "3", ...JCODE_OWNED_ENV }, stdio: ["ignore", "ignore", "ignore", "pipe"] });
     this.server = server; trackGroup(server);
     try {
       await new Promise<void>((resolve, reject) => {

package/src/adapters/registry-types.ts

@@ -1,3 +1,4 @@
+import type { ReviewerBackend, ReviewerPrintOptions } from "./reviewer-print.ts";
 import type { SettingDef } from "../hub/settings.ts";
 import type { Addon } from "../hub/tooling.ts";
 import type { RecoveryContinuityBookmark } from "../hub/recovery-continuity.ts";
@@ -13,9 +14,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" | "reviewer-print";
 
 /** Existing buildLaunch inputs plus the startup-bound instance and project identity. */
 export interface LaunchContext {
@@ -53,7 +55,9 @@ export type DaemonPorts =
   | { acp: AcpOptions }
   | { jcode: JcodeOptions }
   | { pi: PiOptions }
-  | { local: LocalOptions };
+  | { local: LocalOptions }
+  | { claudePrint: ClaudePrintOptions }
+  | { reviewerPrint: ReviewerPrintOptions };
 
 export interface CreateContext<Ports extends DaemonPorts = DaemonPorts> {
   instance: string;
@@ -223,6 +227,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,7 +264,11 @@ 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;
+  /** Fixed host backend; runtime isolation proof is required before bus admission. */
+  reviewer?: { backend?: ReviewerBackend; defaultPool: boolean; unavailable?: string; declaration: "automatic" | "explicit" };
 }
 
 /** Explicit project declarations, passed by the bound host. No process-global instance registration. */
-export type KindMap = Readonly<Record<string, { readonly kind: string }>>;
+export type KindMap = Readonly<Record<string, { readonly kind: string; readonly roles?: readonly string[]; readonly start_mode?: "tui" | "headless"; readonly review_mode?: "fresh" }>>;

package/src/adapters/registry.ts

@@ -1,3 +1,4 @@
+import { AGY_DEFINITION } from "./definitions/reviewer-variants.ts";
 import { builtinCliEntries } from "./definitions/native-cli-entry.ts";
 import { builtinPreview } from "./definitions/native-cli-preview.ts";
 import { DAEMON_PORTS } from "./definitions/native-factories.ts";
@@ -25,7 +26,8 @@ function immutable<T>(value: T, seen = new WeakSet<object>()): T {
   return Object.freeze(value);
 }
 
-const fixedBuiltinDefinitions = new Set<AdapterDefinition>([...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN, QWEN_DEFINITION]);
+const fixedBuiltinDefinitions = new Set<AdapterDefinition>([...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN, QWEN_DEFINITION, AGY_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([
@@ -33,19 +35,33 @@ export const ADAPTERS: readonly AdapterDefinition[] = immutable([
   QWEN_DEFINITION,
   ...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN.filter(definition => definition.kind === "jcode"),
 ]);
+// Unavailable declarations are metadata, not supported native peers or launchers.
+const declarationOnlyDefinitions: readonly AdapterDefinition[] = immutable([AGY_DEFINITION]);
 const definitions = new Map<string, AdapterDefinition>();
-for (const definition of ADAPTERS) {
+for (const definition of [...ADAPTERS, ...declarationOnlyDefinitions]) {
   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);
 }
 
+/** Default kind slots derive from fixed reviewer policy, not a second vendor list in the host. */
+export const REVIEW_POOL_KINDS: readonly string[] = Object.freeze([...definitions.values()].filter(definition => !!(definition.reviewerVariant ?? definition).reviewer).map(definition => definition.kind));
+export const DEFAULT_REVIEW_POOL: readonly string[] = Object.freeze(ADAPTERS.filter(definition => (definition.reviewerVariant ?? definition).reviewer?.defaultPool === true).map(definition => definition.kind));
+
 /** Native quota handoff platform names, distinct from per-delivery recall injection policy. */
 export const QUOTA_HANDOFF_PLATFORMS: Readonly<Record<string, string>> = Object.freeze(Object.fromEntries(
   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 +82,13 @@ 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.
+  const declaration = ownField(instances, id), roles = ownField(declaration, "roles");
+  const reviewerOnly = Array.isArray(roles) && !types.isProxy(roles) && roles.length === 1 && Object.getOwnPropertyDescriptor(roles, "0")?.value === "reviewer";
+  const variant = definition?.reviewerVariant;
+  const fresh = variant?.reviewer?.declaration === "automatic" || ownField(declaration, "review_mode") === "fresh";
+  return variant && kind !== id && reviewerOnly && ownField(declaration, "start_mode") === "headless" && fresh ? variant : definition;
 }
 export function familyOf(id: string, instances?: KindMap): string | undefined {
   return definitionOf(id, instances)?.family;
@@ -113,6 +135,8 @@ 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],
+    ["reviewer", definition.reviewer !== undefined],
   ];
   const field = restricted.find(([, present]) => present)?.[0];
   if (field) throw new Error(`${field} is restricted to fixed builtin adapter definitions`);
@@ -121,8 +145,8 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
 /** Ordered catalog projections consumed by generic core hosts. */
 export const STARTABLE_PEERS = SUPPORTED_PEERS;
 export type SupportedPeer = typeof SUPPORTED_PEERS[number];
-export function isSupportedPeer(peer: unknown): peer is SupportedPeer { return typeof peer === "string" && definitionOf(peer) !== undefined; }
-export function isStartablePeer(peer: unknown): peer is SupportedPeer { return typeof peer === "string" && definitionOf(peer)?.start.conductorStartable === true; }
+export function isSupportedPeer(peer: unknown): peer is SupportedPeer { return typeof peer === "string" && ADAPTERS.some(definition => definition.kind === peer); }
+export function isStartablePeer(peer: unknown): peer is SupportedPeer { return isSupportedPeer(peer) && definitionOf(peer)?.start.conductorStartable === true; }
 
 /** Body-free browser metadata, derived from the same native participation and managed-tool contracts. */
 export const ADAPTER_DISPLAY = Object.fromEntries(ADAPTERS.map(adapter => [adapter.kind, {

package/src/adapters/reviewer-print.ts

@@ -0,0 +1,319 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+import { HUB, frame } from "../hub/envelope.ts";
+import { BasePeer } from "../hub/peers.ts";
+import type { Envelope } from "../hub/envelope.ts";
+
+export interface ReviewerPrintUsage { input_tokens?: number; output_tokens?: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number }
+export interface ReviewerIsolationReceipt {
+  backend: string;
+  version: string;
+  binary: string;
+  profile: string;
+  readOnly: true;
+  strictMcp: true;
+  ephemeral: true;
+  evidence: readonly string[];
+}
+export interface ReviewerPrepareContext {
+  peer: string;
+  cwd: string;
+  sessionId: string;
+  mcpConfig: string;
+  systemPrompt: string;
+  privatePaths: readonly string[];
+  command?: readonly string[];
+  signal: AbortSignal;
+}
+export interface ReviewerLaunch {
+  command: readonly string[];
+  args: readonly string[];
+  isolation: ReviewerIsolationReceipt;
+  /** Recheck the fixed producer's binary/config binding immediately before the model child is spawned. */
+  current?: () => boolean;
+  env?: NodeJS.ProcessEnv;
+  cleanup?: () => void | Promise<void>;
+}
+export interface ReviewerBackend {
+  id: string;
+  prepare(context: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string }>;
+  usage?(event: unknown): ReviewerPrintUsage | undefined;
+  failure?(event: unknown): "quota" | undefined;
+}
+export interface ReviewerFailure {
+  task: number;
+  head?: string;
+  flowRevision?: number;
+  cause: "start_failed" | "quota" | "no_verdict";
+}
+
+export interface ReviewerPrintOptions {
+  cwd: string;
+  command?: readonly string[];
+  mcpConfig: string;
+  systemPrompt: string;
+  privatePaths?: readonly string[];
+  watchdogMs: number;
+  backend: ReviewerBackend;
+  facts?(env: Envelope): string | undefined;
+  verdictSince(task: number, since: number): boolean;
+  onUsage?(usage: ReviewerPrintUsage, task: number): void;
+  onUnavailable?(failure: ReviewerFailure, current: () => boolean): void | Promise<void>;
+  log?(line: string): void;
+}
+
+// ponytail: 256 KiB per NDJSON frame and 4 MiB stdout per review child. Raise only with measured native receipts.
+const MAX_REVIEW_FRAME_BYTES = 256 * 1024, MAX_REVIEW_OUTPUT_BYTES = 4 * 1024 * 1024;
+class GroupCleanupError extends Error {}
+type ReviewTarget = Omit<ReviewerFailure, "cause">;
+interface ReviewBatch { targets: (ReviewTarget | undefined)[]; next: number; failures: ReviewerFailure[] }
+const reviewTarget = (env: Envelope): ReviewTarget | undefined => {
+  const task = reviewTask(env);
+  if (task === undefined || env.private) return undefined;
+  const revision = Number(env.refs?.reviewRevision);
+  return { task, ...(typeof env.refs?.commit === "string" ? { head: env.refs.commit } : {}), ...(Number.isSafeInteger(revision) && revision > 0 ? { flowRevision: revision } : {}) };
+};
+const remainingFailures = (batch: ReviewBatch, start: number, cause: ReviewerFailure["cause"]): ReviewerFailure[] =>
+  batch.targets.slice(start).flatMap(target => target ? [{ ...target, cause }] : []);
+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 class ReviewerPrintPeer extends BasePeer {
+  readonly hubNative = true;
+  private generation = 0;
+  private child: ChildProcess | undefined;
+  private activeDeliveryId: string | undefined;
+  private batch: ReviewBatch | undefined;
+  private preparation: { abort: AbortController; done: Promise<ReviewerLaunch> } | undefined;
+  private receipt: ReviewerIsolationReceipt | undefined;
+  get isolationReceipt(): ReviewerIsolationReceipt | undefined { return this.receipt; }
+  /** 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: ReviewerPrintOptions) { super(id, opts.watchdogMs); }
+
+  recoveryMetadata(): Record<string, unknown> { return { launch: { kind: "reviewer-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`);
+    if (this.preparation) throw new Error(`${this.id}: reviewer preparation is still running`);
+    this.receipt = undefined;
+    const generation = ++this.generation;
+    try {
+      const launch = await this.prepare(randomUUID());
+      try {
+        if (generation !== this.generation || launch.current?.() === false) throw new Error("reviewer isolation changed before startup");
+        this.receipt = launch.isolation;
+      } finally { await launch.cleanup?.(); }
+    } catch (error) { if (generation === this.generation) this.setState("offline"); throw error; }
+    if (generation === this.generation) this.setState("idle");
+  }
+
+  async stop(reason?: string): Promise<void> {
+    this.generation++; // fence before the first await: a late exit settles nothing
+    this.receipt = undefined;
+    this.batch = undefined;
+    this.preparation?.abort.abort();
+    await this.preparation?.done.catch(() => {});
+    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.abortReview("review watchdog timeout"); }
+
+  private abortReview(reason: "review watchdog timeout" | "review output limit exceeded"): void {
+    const generation = ++this.generation, batch = this.batch, preparation = this.preparation;
+    this.reviewing = undefined;
+    this.receipt = undefined;
+    this.clearWatchdog();
+    preparation?.abort.abort();
+    this.settle("needs_review", reason);
+    // Revoke first, then confirm both preparation and the model's whole group are gone before fallback.
+    void (async () => {
+      if (preparation) await preparation.done.catch(() => {});
+      if (generation !== this.generation) return;
+      await this.kill();
+      if (generation !== this.generation) return; // a person's stop owns the hold; never reroute it
+      if (batch) await this.reportFailures([...batch.failures, ...remainingFailures(batch, batch.next, "no_verdict")], generation);
+      if (generation === this.generation && this.state === "busy") { this.batch = undefined; super.onWatchdog(); }
+    })().catch((error: Error) => this.opts.log?.(`[${this.id}] review cleanup failed, staying busy`));
+  }
+
+  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.batch = { targets: envs.map(reviewTarget), next: 0, failures: [] };
+    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", `reviewer failed: ${error.message}`);
+      void this.kill().then(() => { if (generation === this.generation) { this.batch = undefined; this.setState("idle"); } }, () => undefined);
+    });
+  }
+
+  private async run(envs: Envelope[], generation: number): Promise<void> {
+    const missing: number[] = [];
+    let started = false;
+    const batch = this.batch!;
+    const reroute = batch.failures;
+    let failure: { state: "failed_safe" | "needs_review"; reason: string } | undefined;
+    for (const [index, env] of envs.entries()) {
+      batch.next = index;
+      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 result: { code: number | null; quota: boolean };
+      try { result = 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: `reviewer could not start: ${(error as Error).message}` };
+        reroute.push(...remainingFailures(batch, index, "start_failed"));
+        batch.next = envs.length;
+        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);
+        const target = batch.targets[index];
+        if (target) reroute.push({ ...target, cause: result.quota ? "quota" : "no_verdict" });
+        if (result.quota) {
+          reroute.push(...remainingFailures(batch, index + 1, "quota"));
+          batch.next = envs.length;
+          break;
+        }
+      }
+      batch.next = index + 1;
+      if (result.code !== 0) this.opts.log?.(`[${this.id}] review of task #${task} exited ${result.code}`);
+    }
+    if (generation !== this.generation) return;
+    this.clearWatchdog(); // the child is gone; keep busy while the host settles the remaining walk
+    this.settle(failure?.state ?? (missing.length ? "needs_review" : "completed"), failure?.reason ?? (missing.length ? `no verdict recorded for task ${missing.map(id => `#${id}`).join(", ")}` : undefined));
+    await this.reportFailures(reroute, generation);
+    if (generation === this.generation) { this.batch = undefined; this.setState("idle"); }
+  }
+
+  private async reportFailures(failures: readonly ReviewerFailure[], generation: number): Promise<void> {
+    const seen = new Set<string>();
+    for (const failed of failures) {
+      if (generation !== this.generation) return;
+      const identity = JSON.stringify([failed.task, failed.head, failed.flowRevision]);
+      if (seen.has(identity)) continue;
+      seen.add(identity);
+      try { await this.opts.onUnavailable?.(failed, () => generation === this.generation); }
+      catch { this.opts.log?.(`[${this.id}] reviewer fallback could not be recorded; inspect the task`); }
+    }
+  }
+
+  private prepare(sessionId: string): Promise<ReviewerLaunch> {
+    const abort = new AbortController();
+    const done = (async () => {
+      const launch = await this.opts.backend.prepare({ peer: this.id, cwd: this.opts.cwd, sessionId, mcpConfig: this.opts.mcpConfig,
+        systemPrompt: this.opts.systemPrompt, privatePaths: this.opts.privatePaths ?? [], command: this.opts.command, signal: abort.signal });
+      if ("unavailable" in launch) throw new Error(launch.unavailable);
+      const proof = launch.isolation;
+      if (abort.signal.aborted || !proof || proof.backend !== this.opts.backend.id || proof.readOnly !== true || proof.strictMcp !== true || proof.ephemeral !== true || !proof.binary || !proof.version || !proof.profile || !proof.evidence.length || !launch.command.length) {
+        await launch.cleanup?.();
+        throw new Error("reviewer isolation is unavailable or preparation was cancelled");
+      }
+      return launch;
+    })();
+    const pending = { abort, done };
+    this.preparation = pending;
+    void done.finally(() => { if (this.preparation === pending) this.preparation = undefined; }).catch(() => {});
+    return done;
+  }
+
+  private async review(env: Envelope, task: number, generation: number): Promise<{ code: number | null; quota: boolean }> {
+    const launch = await this.prepare(randomUUID());
+    try {
+    if (generation !== this.generation || launch.current?.() === false) throw new Error("reviewer isolation changed before child spawn");
+    this.receipt = launch.isolation;
+    const [cmd, ...prefix] = launch.command;
+    let quota = false;
+    return await new Promise<{ code: number | null; quota: boolean }>((resolve, reject) => {
+      const child = spawn(cmd!, [...prefix, ...launch.args], { cwd: this.opts.cwd, detached: true, env: peerChildEnv(this.id, { ...process.env, ...launch.env }), stdio: ["pipe", "pipe", "ignore"] });
+      // Owned before any await, so a stop that lands before "spawn" still finds and kills it.
+      this.child = child;
+      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 = "", outputBytes = 0;
+      child.stdout!.on("data", (chunk: Buffer) => {
+        if (generation !== this.generation) return;
+        outputBytes += chunk.length;
+        if (outputBytes > MAX_REVIEW_OUTPUT_BYTES) { this.abortReview("review output limit exceeded"); return; }
+        buffer += chunk.toString("utf8");
+        for (let i; (i = buffer.indexOf("\n")) >= 0;) {
+          const line = buffer.slice(0, i); buffer = buffer.slice(i + 1);
+          if (Buffer.byteLength(line) > MAX_REVIEW_FRAME_BYTES) { this.abortReview("review output limit exceeded"); return; }
+          try {
+            const event: unknown = JSON.parse(line);
+            const usage = this.opts.backend.usage?.(event);
+            if (usage) this.opts.onUsage?.(usage, task);
+            if (this.opts.backend.failure?.(event) === "quota") quota = true;
+          } catch { /* not a stream-json line */ }
+        }
+        if (Buffer.byteLength(buffer) > MAX_REVIEW_FRAME_BYTES) { this.abortReview("review output limit exceeded"); return; }
+        this.touch();
+      });
+      child.once("exit", code => {
+        if (this.child === child) this.reviewing = undefined; // 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, quota }); },
+          (error: Error) => reject(new GroupCleanupError(error.message)));
+      });
+    });
+    } finally {
+      try { await launch.cleanup?.(); }
+      catch { this.opts.log?.(`[${this.id}] reviewer isolation cleanup incomplete`); }
+    }
+  }
+
+  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/cli/help.ts

@@ -23,6 +23,12 @@ 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 train report|configure|cut <release-id> [revision] [json]", "plan a release and freeze its approved scope after resource/quota admission"],
+    ["ahub sdlc release-assign <task> <revision> <release-id|none> <reason>", "assign approved/in-flight work without changing execution"],
+    ["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 +90,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" || args[0] === "release-assign" || args[0] === "train" && args[1] !== "report")) 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";
 }