@staix/agent-hub 0.12.45 → 0.13.0

package/src/adapters/jcode.ts

@@ -1,4 +1,5 @@
 import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { assessVersion, COMPAT, type CompatVerdict } from "./compat.ts";
 import { createConnection } from "node:net";
 import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdtempSync, openSync, readSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -12,21 +13,25 @@ export interface JcodeOptions extends Omit<AcpOptions, "cmd" | "qwen025" | "expe
   command: string[];
   home: string;
   providerProfile?: string;
+  /** The hub peer id this Jcode acts for: "jcode" for the base peer, an instance id for an extra one (#685). */
+  peer?: string;
+  /** Initial native provider (`-p`), passed exactly as the person wrote it (#685). The hub never handles model credentials. */
+  provider?: string;
   /** How long a native steer may take to be acknowledged (#572); default 5 s. */
   steerTimeoutMs?: number;
 }
-export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: string, cwd: string, model?: string, profile?: string): string[] {
+export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: string, cwd: string, model?: string, profile?: string, provider?: string, peer = "jcode"): string[] {
   if (!command.length || command.some(word => typeof word !== "string" || !word)) throw new Error("jcode_cmd must name an executable argv");
-  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"])];
+  return [...command, kind, "--socket", socket, "--cwd", cwd, "--no-update", "--no-selfdev", ...(provider ? ["-p", provider] : []), ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : []),
+    ...(kind === "serve" ? ["--temporary-server", "--owner-pid", String(process.pid), "--server-name", `agent-hub-${peer}`] : ["--mcp-tools", "eager"])];
 }
 export interface JcodeTuiBinding { launchId: string; sessionId: string }
 export type JcodeTuiState = { state: "waiting"; binding: JcodeTuiBinding } |
   { state: "ready"; binding: JcodeTuiBinding; launch: { cmd: string; args: string[]; env: NodeJS.ProcessEnv } };
 
-export function jcodeTuiCommand(command: string[], socket: string, sessionId: string, model?: string, profile?: string): string[] {
+export function jcodeTuiCommand(command: string[], socket: string, sessionId: string, model?: string, profile?: string, provider?: string): string[] {
   if (!command.length || command.some(word => typeof word !== "string" || !word)) throw new Error("jcode_cmd must name an executable argv");
-  return [...command, "--socket", socket, "--resume", sessionId, "--no-update", "--no-selfdev",
+  return [...command, "--socket", socket, "--resume", sessionId, "--no-update", "--no-selfdev", ...(provider ? ["-p", provider] : []),
     ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : [])];
 }
 
@@ -65,17 +70,8 @@ export class JcodeOptionMismatch extends Error {
   constructor(readonly option: "--session-id" | "--model" | "--provider-profile") { super("Jcode launch options differ from its running session"); }
 }
 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;
-}
+/** #691: the verdict lives in `src/adapters/compat.ts` (line, verified versions, the person's trust); never pin here. */
+export const jcodeVersionSupported = (version: unknown): boolean => assessVersion("jcode", version).ok;
 
 /** A native steer the server did not take, with nothing sent: the message may safely stay queued. */
 class SteerRefused extends Error {}
@@ -137,20 +133,56 @@ function nativeSteer(socket: string, cwd: string, sessionId: string, text: strin
 }
 
 /** The wrapper contract preserves every configured prefix argument before the native probe. */
-export function verifiedJcodeCommand(command: string[], cwd: string): boolean {
+export function jcodeVersion(command: string[], cwd: string): CompatVerdict {
   const [bin, ...prefix] = command;
-  if (!bin) return false;
+  if (!bin) return assessVersion("jcode", undefined);
   try {
     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 jcodeVersionSupported(version.semver);
-  } catch { return false; }
+    return assessVersion("jcode", result.status === 0 ? COMPAT.jcode.parse(result.stdout) : undefined);
+  } catch { return assessVersion("jcode", undefined); }
+}
+export const verifiedJcodeCommand = (command: string[], cwd: string): boolean => jcodeVersion(command, cwd).ok;
+/** Collects at most `cap` bytes; the chunk that would pass it, and every later one, is refused and not kept. */
+export function boundedOutput(cap: number): { push(chunk: Buffer): boolean; text(): string; readonly size: number; readonly overflowed: boolean } {
+  const chunks: Buffer[] = [];
+  let size = 0, overflowed = false;
+  return {
+    push(chunk) { if (overflowed || size + chunk.length > cap) { overflowed = true; return false; } chunks.push(chunk); size += chunk.length; return true; },
+    text: () => Buffer.concat(chunks).toString("utf8"),
+    get size() { return size; },
+    get overflowed() { return overflowed; },
+  };
+}
+/**
+ * The daemon's preflight: the same probe without blocking the event loop (a slow wrapper must not stall peers). The probe owns its
+ * process group: at the deadline, or once stdout passes 64 KiB, the whole group is stopped, descendants included (kimi-review's pattern).
+ */
+export function jcodeVersionAsync(command: string[], cwd: string, timeoutMs = 10_000): Promise<CompatVerdict> {
+  const [bin, ...prefix] = command;
+  if (!bin) return Promise.resolve(assessVersion("jcode", undefined));
+  return new Promise(resolve => {
+    let child: ChildProcess;
+    try { child = spawn(bin, [...prefix, "--quiet", "version", "--json"], { cwd, env: { ...peerChildEnv("jcode"), ...JCODE_OWNED_ENV }, detached: true, stdio: ["ignore", "pipe", "ignore"] }); }
+    catch { resolve(assessVersion("jcode", undefined)); return; }
+    const output = boundedOutput(64 * 1024);
+    let done = false;
+    const finish = async (code: number | null) => {
+      if (done) return; done = true; clearTimeout(timer);
+      try { await stopOwnedProcess(child, { group: true }); } catch { resolve(assessVersion("jcode", undefined)); return; }
+      resolve(assessVersion("jcode", code === 0 && !output.overflowed ? COMPAT.jcode.parse(output.text()) : undefined));
+    };
+    const timer = setTimeout(() => { void finish(null); }, timeoutMs);
+    child.once("spawn", () => trackGroup(child));
+    // Chunks after the cap or after settling are drained and discarded, never buffered.
+    child.stdout!.on("data", (bytes: Buffer) => { if (!done && !output.push(bytes)) void finish(null); });
+    child.once("error", () => { void finish(null); });
+    child.once("close", code => { void finish(code); });
+  });
 }
 
 /** Both processes are ours. The user's global daemon and its sockets are never stopped. */
 export class JcodePeer extends AcpPeer {
-  private readonly launchId = crypto.randomUUID();
+  private readonly launchId: string;
   private socketIdentity: { dev: number; ino: number } | undefined;
   private readonly root: string;
   private readonly socket: string;
@@ -161,21 +193,28 @@ 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");
+    const peer = jcode.peer ?? "jcode";
     jcodeCommand(jcode.command, "acp", "preview", jcode.cwd);
     // 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_OWNED_ENV }, mcpServers: [], requireLoadSessionEcho: true, expectedAgent: { name: "jcode", version: jcodeVersionSupported } });
-    this.root = root; this.socket = socket;
+    const cmd = jcodeCommand(jcode.command, "acp", socket, jcode.cwd, jcode.launchModel, jcode.providerProfile, jcode.provider, peer);
+    const launchId = crypto.randomUUID();
+    // The ACP child gets peerChildEnv(this.id): the instance id, so its hub tools act as this peer and never as the base Jcode. The launch id
+    // goes with it: the daemon admits a hub-tools hello for this peer only when it carries the id of this peer's current owned launch (#368).
+    super(peer, { ...jcode, cmd, env: { ...jcode.env, JCODE_HOME: jcode.home, JCODE_SOCKET: socket, AGENTHUB_LAUNCH_ID: launchId, ...JCODE_OWNED_ENV }, mcpServers: [], requireLoadSessionEcho: true, expectedAgent: { name: "jcode", version: jcodeVersionSupported } });
+    this.root = root; this.socket = socket; this.launchId = launchId;
   }
 
+  /** True only for the id of this peer's current owned launch, while it is not ending: the proof a hub-tools hello must carry (#368). */
+  ownsLaunch(launchId: unknown): boolean { return !this.ending && typeof launchId === "string" && launchId === this.launchId; }
+
   override async start(): Promise<void> {
     // The native loader otherwise imports Codex MCP into the user's store on first use.
     if (!existsSync(join(this.jcode.home, "mcp.json"))) throw new Error("initialize Jcode's global MCP store with its native client before enabling this peer; the hub never initializes or copies it");
     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_OWNED_ENV }, stdio: ["ignore", "ignore", "ignore", "pipe"] });
+    const [bin, ...args] = jcodeCommand(this.jcode.command, "serve", this.socket, this.jcode.cwd, this.jcode.launchModel, this.jcode.providerProfile, this.jcode.provider, this.id);
+    const server = spawn(bin!, args, { cwd: this.jcode.cwd, detached: true, env: { ...peerChildEnv(this.id), JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, JCODE_READY_FD: "3", AGENTHUB_LAUNCH_ID: this.launchId, ...JCODE_OWNED_ENV }, stdio: ["ignore", "ignore", "ignore", "pipe"] });
     this.server = server; trackGroup(server);
     try {
       await new Promise<void>((resolve, reject) => {
@@ -279,11 +318,13 @@ export class JcodePeer extends AcpPeer {
       : options.providerProfile !== undefined && options.providerProfile !== this.jcode.providerProfile ? "--provider-profile" : undefined;
     if (differs) throw new JcodeOptionMismatch(differs);
     if (!savedSession(this.jcode.home, sessionId)) return { state: "waiting", binding };
-    const [cmd, ...args] = jcodeTuiCommand(this.jcode.command, this.socket, sessionId, this.jcode.launchModel, this.jcode.providerProfile);
-    return { state: "ready", binding, launch: { cmd: cmd!, args, env: { JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, ...JCODE_OWNED_ENV } } };
+    const [cmd, ...args] = jcodeTuiCommand(this.jcode.command, this.socket, sessionId, this.jcode.launchModel, this.jcode.providerProfile, this.jcode.provider);
+    // The TUI is the person's own client of this peer's server. The shared project MCP entry names no peer (#685), so every launch
+    // path supplies its own id: the base Jcode's too, or its MCP child would fall back to the channel default.
+    return { state: "ready", binding, launch: { cmd: cmd!, args, env: { JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, AGENTHUB_PEER_ID: this.id, AGENTHUB_LAUNCH_ID: this.launchId, ...JCODE_OWNED_ENV } } };
   }
   override recoveryMetadata(): Record<string, unknown> {
-    return { ...super.recoveryMetadata(), launch: { kind: "jcode", peer: "jcode", mode: "headless", ...(this.jcode.launchModel ? { model: this.jcode.launchModel } : {}), ...(this.jcode.providerProfile ? { providerProfile: this.jcode.providerProfile } : {}) } };
+    return { ...super.recoveryMetadata(), launch: { kind: "jcode", peer: this.id, mode: "headless", ...(this.jcode.launchModel ? { model: this.jcode.launchModel } : {}), ...(this.jcode.providerProfile ? { providerProfile: this.jcode.providerProfile } : {}) } };
   }
 }
 

package/src/adapters/kimi-review.ts

@@ -1,4 +1,5 @@
 import { spawn, type ChildProcess } from "node:child_process";
+import { assessVersion, COMPAT } from "./compat.ts";
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
@@ -7,7 +8,7 @@ import { stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { realPath } from "../hub/project.ts";
 import type { ReviewerBackend, ReviewerPrepareContext } from "./reviewer-print.ts";
 
-const VERSION = "2.2.0", MANAGED = "managed:kimi-code";
+const MANAGED = "managed:kimi-code";
 const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
 const hash = (text: string) => createHash("sha256").update(text).digest("hex");
 /** Native discovery can walk above cwd; check lexical aliases as well as the physical temporary root. */
@@ -133,7 +134,9 @@ export const kimiReviewerBackend: ReviewerBackend = {
       const executable = realPath(Bun.which(native[0]!, { PATH: process.env.PATH }) ?? resolve(native[0]!));
       const command = [executable, ...native.slice(1)];
       const executableStat = lstatSync(executable);
-      if (await version(command, cwd, env, context.signal) !== VERSION) throw new Error("unsupported Kimi version; receipt covers 2.2.0");
+      // #691: the verified versions and the person's trust live in compat.ts.
+      const verdict = assessVersion("kimi-review", COMPAT["kimi-review"].parse(await version(command, cwd, env, context.signal)));
+      if (!verdict.ok) throw new Error(verdict.reason);
       const fingerprints = [configFile, mcpFile, agentFile].map(file => hash(read(file, 2_097_152)));
       let cleaned = false;
       const cleanup = () => { if (cleaned) return; rmSync(root, { recursive: true, force: true }); cleaned = true; };
@@ -149,7 +152,7 @@ export const kimiReviewerBackend: ReviewerBackend = {
               && ["credentials", "oauth", "device_id"].every((name, index) => realPath(join(source, name)) === sources[index] && realPath(join(tool, name)) === sources[index]);
           } catch { return false; }
         },
-        isolation: { backend: "kimi", version: VERSION, binary: executable, profile: "private-config-exact-two-tools-shared-native-oauth", readOnly: true, strictMcp: true, ephemeral: true,
+        isolation: { backend: "kimi", version: verdict.version, binary: executable, profile: "private-config-exact-two-tools-shared-native-oauth", readOnly: true, strictMcp: true, ephemeral: true,
           enforcement: "native-policy", freshSession: true, hubToolsOnly: true,
           evidence: ["#533 person ruling2026-10-19: native execution-time exact tool allowlist, no kernel sandbox", "private config/cwd/empty skills; shared OAuth directory symlinks and native lock/atomic rename", "task-bound in-process hub MCP; no full control token", "residual: interruption mid-refresh may require native re-login"] },
       };

package/src/adapters/registry-types.ts

@@ -202,7 +202,9 @@ export interface AdapterDefinition {
   };
   identity: { mcp: "acp-session" | "project-file" | "env" | "channel-plugin" };
   /** Declaration admission only; execution-root and runtime owner proof remain host responsibilities. */
-  instances?: { mode: "external" | "headless"; roles?: readonly string[] };
+  instances?: { mode: "external" | "headless"; roles?: readonly string[];
+    /** Each declared instance runs its own native data home (`jcode_home`) and may pass its own provider, model and profile names (#685). Fixed builtins only. */
+    nativeHome?: true };
   attach?: {
     /** The authenticated external hello may claim this id; independent of MCP configuration shape. */
     externalHello?: boolean;

package/src/adapters/registry.ts

@@ -232,6 +232,7 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
     ["start.daemonPort pi-rpc", definition.start.daemonPort === "pi-rpc"],
     ["routing", definition.routing !== undefined],
     ["projection", definition.projection !== undefined],
+    ["instances.nativeHome", declared(definition.instances, "nativeHome")], // #685: a fixed-builtin assumption, one native data home per declared instance
     ["reviewerVariant", definition.reviewerVariant !== undefined],
     ["reviewer", definition.reviewer !== undefined],
     ["hooks.factsHook", declared(definition.hooks, "factsHook")],

package/src/cli/agents.ts

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process";
+import { assessVersion, COMPAT, describe, isCompatId, readTrust, trustFile, writeTrust, type CompatId, type CompatVerdict } from "../adapters/compat.ts";
+
+/** #691: what `ahub agents` and `ahub doctor` show for each gated native CLI. */
+export interface AgentVersionRow { id: CompatId; executable?: string; verdict: CompatVerdict; policy: string }
+
+/** `commands` carries the configured argv (codex_bin, jcode_cmd, qwen_cmd); the probe words follow it. */
+export function agentVersions(commands: Partial<Record<CompatId, readonly string[]>> = {}): AgentVersionRow[] {
+  const trusted = readTrust();
+  return (Object.keys(COMPAT) as CompatId[]).map(id => {
+    const [defaultBin, ...words] = COMPAT[id].probe;
+    const [bin = defaultBin, ...prefix] = commands[id] ?? [defaultBin];
+    const executable = Bun.which(bin) ?? undefined;
+    if (!executable) return { id, verdict: { ok: false, state: "unknown", reason: `${COMPAT[id].label} not found on PATH` }, policy: describe(id) };
+    const result = spawnSync(executable, [...prefix, ...words], { encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024, env: { ...process.env, JCODE_NO_TELEMETRY: "1", JCODE_DISABLE_CLAUDE_MCP: "1" } });
+    return { id, executable, verdict: assessVersion(id, result.status === 0 ? COMPAT[id].parse(result.stdout ?? "") : undefined, trusted), policy: describe(id) };
+  });
+}
+
+export function runAgents(args: string[], commands: Partial<Record<CompatId, readonly string[]>>, fail: (message: string) => never): void {
+  const [sub, id, version, ...rest] = args.filter(arg => arg !== "--json");
+  if (sub === "trust") {
+    const revoke = rest.includes("--revoke");
+    if (!isCompatId(id) || !version || rest.some(arg => arg !== "--revoke")) fail(`usage: ahub agents trust <${Object.keys(COMPAT).join("|")}> <version> [--revoke]`);
+    // The issue requires saying what trust covers before it is recorded.
+    if (!revoke) console.log(`${COMPAT[id].label} ${version}: ${COMPAT[id].trustNote}`);
+    let rows;
+    try { rows = writeTrust(id, version, revoke); } catch (error) { fail((error as Error).message); }
+    if (revoke) return console.log(`revoked: ${id} ${version} (${rows.length} trusted on this machine, ${trustFile()})`);
+    console.log(`trusted on this machine: ${COMPAT[id].label} ${version}\nUndo: ahub agents trust ${id} ${version} --revoke`);
+    return;
+  }
+  if (sub !== undefined) fail("usage: ahub agents [--json] | ahub agents trust <id> <version> [--revoke]");
+  const rows = agentVersions(commands);
+  if (args.includes("--json")) return console.log(JSON.stringify(rows.map(row => ({ id: row.id, executable: row.executable ?? null, ...row.verdict, policy: row.policy })), null, 2));
+  for (const row of rows) {
+    const v = row.verdict;
+    console.log(`${row.id.padEnd(13)} ${(v.version ?? "-").padEnd(10)} ${v.state.padEnd(9)} ${row.policy}${v.ok ? (v.note ? `\n${" ".repeat(14)}${v.note}` : "") : `\n${" ".repeat(14)}${v.reason}`}`);
+  }
+}

package/src/cli/console-review.ts

@@ -0,0 +1,54 @@
+// #711 / #380: the console's review guidance. Pure strings and decisions, no terminal code and no state import: console-state.ts renders them.
+// Nothing here changes authority: the console runs `ahub review` as the person, and the hub decides.
+
+export type Verdict = "approved" | "changes_requested";
+/** The task a review choice was opened for, taken from the selected row or the open detail. */
+export interface ReviewChoice { id: number; title: string; reviewerIsUser: boolean }
+
+const MAX_TITLE = 40;
+const clean = (text: string) => text.replace(/[\p{Cc}\p{Cf}]/gu, " ").replace(/\s+/g, " ").trim();
+/** The title as the choice line shows it: quoted, one line, cut to the width; a private task is `[pii]`. */
+export function choiceTitle(row: { title?: unknown; signals?: unknown }): string {
+  const priv = (Array.isArray(row.signals) && row.signals.some(s => s === "pii" || s === "pii_path")) || row.title === "[pii]";
+  if (priv) return "[pii]";
+  const text = clean(String(row.title ?? ""));
+  return JSON.stringify(text.length > MAX_TITLE ? `${text.slice(0, MAX_TITLE - 3)}...` : text);
+}
+
+/** The choice for a task row, or undefined when it is not one the person can review (not in review). */
+export function reviewChoiceFor(row: any): ReviewChoice | undefined {
+  if (!row || row.state !== "in_review" || !Number.isSafeInteger(Number(row.id)) || Number(row.id) <= 0) return undefined;
+  return { id: Number(row.id), title: choiceTitle(row), reviewerIsUser: row.reviewer === "user" };
+}
+
+/** The prompt line while the choice is open (#711 change 1). The title is already quoted. */
+export const choicePrompt = (c: ReviewChoice): string => `review #${c.id} ${c.title}: a approve  c request changes  Esc cancel`;
+/** What `a` and `c` prefill on the input line. The trailing space is where the note goes. */
+export const verdictInput = (id: number, verdict: Verdict): string => `review ${id} ${verdict} `;
+/** The guide line shown above the input after a choice (#711 change 1). */
+export const verdictGuide = (id: number, verdict: Verdict): string =>
+  verdict === "approved" ? `Enter approves #${id}. You can type a note first. Esc cancels.` : "Say what to fix, then Enter. Esc cancels.";
+
+/** The footer hint for a task in review (#711 change 2): the verb, and whose review it is when it is the person's. */
+export const reviewHint = (reviewer: unknown): string => reviewer === "user" ? "your review: r approve or request changes" : "r approve or request changes";
+
+/**
+ * A `review <id> <verdict> [note]` line the person typed, checked before it is sent: a changes request must say what to fix (#711 change 1). Returns the refusal,
+ * or undefined when the line is fine or is not a review line at all (other commands are validated where they always were).
+ */
+export function reviewRefusal(args: readonly string[]): string | undefined {
+  if (args[0] !== "review") return undefined;
+  const verdict = args[2];
+  if (verdict !== "changes_requested") return undefined;
+  const note = args.slice(3).filter(word => !word.startsWith("--")).join(" ").trim();
+  return note ? undefined : "say what to fix before requesting changes";
+}
+
+/** The notice after a review command finished: `#372 approved`, `#372 changes requested`, or the CLI's own refusal verbatim (#711 change 3). */
+export function reviewResult(args: readonly string[], code: number, diagnostic: string): { text: string; tone: "success" | "failure" } | undefined {
+  if (args[0] !== "review" || !/^\d+$/.test(args[1] ?? "")) return undefined;
+  const verdict = args[2];
+  if (verdict !== "approved" && verdict !== "changes_requested") return undefined;
+  if (code) return { text: clean(diagnostic) || `command exited ${code}`, tone: "failure" };
+  return { text: `#${args[1]} ${verdict === "approved" ? "approved" : "changes requested"}`, tone: "success" };
+}