@staix/agent-hub 0.12.36 → 0.12.37

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";
@@ -16,7 +17,7 @@ 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" | "claude-print";
+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 {
@@ -55,7 +56,8 @@ export type DaemonPorts =
   | { jcode: JcodeOptions }
   | { pi: PiOptions }
   | { local: LocalOptions }
-  | { claudePrint: ClaudePrintOptions };
+  | { claudePrint: ClaudePrintOptions }
+  | { reviewerPrint: ReviewerPrintOptions };
 
 export interface CreateContext<Ports extends DaemonPorts = DaemonPorts> {
   instance: string;
@@ -264,7 +266,9 @@ export interface AdapterDefinition {
   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,7 @@ 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. */
@@ -34,8 +35,10 @@ 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); }
@@ -43,6 +46,10 @@ for (const definition of ADAPTERS) {
   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]] : []),
@@ -77,7 +84,11 @@ export function definitionOf(id: string, instances?: KindMap): AdapterDefinition
   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;
+  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;
@@ -125,6 +136,7 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
     ["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`);
@@ -133,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

@@ -25,6 +25,8 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["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"],

package/src/cli/identity.ts

@@ -13,7 +13,7 @@ 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 (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)

package/src/cli/main.ts

@@ -1118,6 +1118,25 @@ const commands: Record<string, () => Promise<void> | void> = {
       finally { hub.close(); }
       return;
     }
+    if (sub === "train") {
+      const operation = args[1], releaseId = Number(args[2]), revision = Number(args[3]);
+      if (!Number.isSafeInteger(releaseId) || releaseId <= 0) fail("usage: ahub sdlc train report|configure|cut <release-id> [revision] [configuration-json]");
+      if (operation === "report" && args.length === 3) return console.log(await taskOp("hub_release_report", { id: releaseId }));
+      if (!Number.isSafeInteger(revision) || revision < 0) fail("train mutation requires its current revision");
+      if (operation === "cut" && args.length === 4) return console.log(await taskOp("hub_release_cut", { id: releaseId, revision }));
+      if (operation === "configure" && args.length === 5) {
+        let fields;
+        try { fields = JSON.parse(args[4]!); } catch { return fail("release train configuration must be JSON"); }
+        if (!fields || typeof fields !== "object" || Array.isArray(fields) || Object.keys(fields).some(key => !["state", "cut", "hotfix"].includes(key))) fail("invalid release train configuration fields");
+        return console.log(await taskOp("hub_release_configure", { ...fields, id: releaseId, revision }));
+      }
+      fail("usage: ahub sdlc train report|configure|cut <release-id> [revision] [configuration-json]");
+    }
+    if (sub === "release-assign") {
+      const revision = Number(args[2]), release = args[3] === "none" ? null : Number(args[3]);
+      if (!Number.isSafeInteger(id) || id! <= 0 || !Number.isSafeInteger(revision) || revision < 0 || release !== null && (!Number.isSafeInteger(release) || release <= 0) || args.length < 5) fail("usage: ahub sdlc release-assign <task> <planning-revision> <release-id|none> <reason...>");
+      return console.log(await taskOp("hub_release_assign", { id, revision, release, reason: args.slice(4).join(" ") }));
+    }
     if (sub === "costs") {
       if (args.length > 2) fail("usage: ahub sdlc costs [owner/repository]");
       return console.log(await taskOp("hub_sdlc_costs", { ...(args[1] ? { repo: args[1] } : {}) }));

package/src/cli/memory.ts

@@ -1,13 +1,12 @@
 import { detectCliIdentity } from "./identity.ts";
 import { createStalenessProbe } from "../hub/memory-staleness.ts";
-import { looksSecret, type MemoryStore, type StoreOptions } from "@staix/agent-mem";
+import { looksSecret, type MemoryStore } from "@staix/agent-mem";
 import type { SyncOptions } from "@staix/agent-mem";
 import { MEMORY_USAGE as CORE_MEMORY_USAGE, rawMemoryCommand, rawGoalCommand } from "@staix/agent-mem";
-import { memoryProjectKey } from "@staix/agent-mem";
 import { mentionsPrivatePath, promotionScreen, withoutPii } from "../hub/memory-policy.ts";
 import { currentRouting, detectSignals } from "../hub/routing.ts";
 import { loadConfig } from "../hub/daemon.ts";
-import { bindProfileMemory, openProfileMemory, MEMORY_PROFILE_UNAVAILABLE, type MemoryProfileReceipt } from "../hub/memory-profile.ts";
+import { bindProfileMemory, memoryProjectFor, openProfileMemory, MEMORY_PROFILE_UNAVAILABLE, MEMORY_SPLIT_INCOMPLETE, type MemoryProfileReceipt, type ProfileMemoryOptions } from "../hub/memory-profile.ts";
 
 export { GOAL_USAGE } from "@staix/agent-mem";
 export const MEMORY_USAGE = `${CORE_MEMORY_USAGE} | decay [--days N] [--json] | profile-check [--json]`;
@@ -18,9 +17,9 @@ const loadConfigSafe = (cwd: string) => { try { return loadConfig(cwd); } catch
 
 
 /** Bind each command at entry; the CLI closes default opens and injected stores remain caller-owned. */
-function commandStores(provided?: MemoryStore, options: StoreOptions = {}) {
+function commandStores(provided: MemoryStore | undefined, options: ProfileMemoryOptions) {
   try { return { ...(provided ? bindProfileMemory(provided) : openProfileMemory(options)), owned: !provided }; }
-  catch { throw new Error(MEMORY_PROFILE_UNAVAILABLE); }
+  catch (error) { throw new Error(error instanceof Error && error.message === MEMORY_SPLIT_INCOMPLETE ? error.message : MEMORY_PROFILE_UNAVAILABLE); }
 }
 function profileOutput(text: string, json: boolean, profile: MemoryProfileReceipt | undefined, person: boolean): string {
   if (!profile) return text;
@@ -44,9 +43,9 @@ export async function memoryCommand(args: string[], cwd: string, opts: { store?:
     const cutoffMs = (opts.now ?? Date.now)() - days * 24 * 3600_000;
     if (!Number.isSafeInteger(days) || !Number.isFinite(cutoffMs) || Math.abs(cutoffMs) > 8_640_000_000_000_000) fail("--days is outside the supported date range");
     const cutoff = new Date(cutoffMs).toISOString();
-    const project = memoryProjectKey(cwd), routing = currentRouting(cwd), paths = privatePaths();
+    const project = memoryProjectFor(cwd), routing = currentRouting(cwd), paths = privatePaths();
     // Review must not promote a held source while reading it: only explicit person actions may append rows.
-    const context = commandStores(opts.store, { deferPromotions: true, now: opts.now });
+    const context = commandStores(opts.store, { project, deferPromotions: true, now: opts.now });
     const store = context.store;
     try {
       context.binding.assertCurrent();
@@ -68,11 +67,12 @@ export async function memoryCommand(args: string[], cwd: string, opts: { store?:
     } finally { if (context.owned) store.close(); }
   }
   let showStale = false;
-  const context = commandStores(opts.store, { ttlMs: (loadConfigSafe(cwd)?.memory.short_ttl_days ?? 14) * 24 * 3600_000,
-    screen: promotionScreen(memoryProjectKey(cwd), cwd, () => currentRouting(cwd), privatePaths) });
+  const project = memoryProjectFor(cwd);
+  const context = commandStores(opts.store, { project, ttlMs: (loadConfigSafe(cwd)?.memory.short_ttl_days ?? 14) * 24 * 3600_000,
+    screen: promotionScreen(project, cwd, () => currentRouting(cwd), privatePaths) });
   try {
     context.binding.assertCurrent();
-    const text = await rawMemoryCommand(args, cwd, { ...opts, store: context.store, open: () => context.store,
+    const text = await rawMemoryCommand(args, cwd, { ...opts, project, store: context.store, open: () => context.store,
       readable: notes => {
       const paths = privatePaths(), visible = withoutPii(notes, currentRouting(cwd), cwd, paths);
       if (args[0] !== "show" || args.includes("--json")) return visible;
@@ -92,10 +92,11 @@ export async function memoryCommand(args: string[], cwd: string, opts: { store?:
 export async function goalCommand(args: string[], cwd: string, opts: { store?: MemoryStore; link?: (goal: string, task: string) => Promise<string>; person?: boolean } = {}): Promise<string> {
   const person = opts.person ?? detectCliIdentity(process.env).role === "console";
   const policy = (): string[] => { try { return loadConfig(cwd).pii?.paths ?? []; } catch (e) { return fail(`the project's config does not load (${(e as Error).message}); fix it before using long-term tasks`); } };
-  const context = commandStores(opts.store);
+  const project = memoryProjectFor(cwd);
+  const context = commandStores(opts.store, { project });
   try {
     context.binding.assertCurrent();
-    const text = await rawGoalCommand(args, cwd, { ...opts, store: context.store, open: () => context.store,
+    const text = await rawGoalCommand(args, cwd, { ...opts, project, store: context.store, open: () => context.store,
       clean: (title, milestones, project) => !looksSecret(`${title}\n${milestones.join("\n")}`) && withoutPii([{ title, text: milestones.join("\n"), project }], currentRouting(cwd), cwd, policy()).length > 0,
     });
     return profileOutput(text, args.includes("--json"), context.binding.status(context.store), person);