@staix/agent-hub 0.12.36 → 0.12.38

package/src/adapters/codex-review-isolation.ts

@@ -0,0 +1,290 @@
+import { DENY_NAMES, DENY_SEGMENTS } from "@staix/agent-mem/platform";
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir, tmpdir } from "node:os";
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+import { realPath } from "../hub/project.ts";
+import type { ReviewerBackend, ReviewerLaunch, ReviewerPrepareContext } from "./reviewer-print.ts";
+
+const VERSION = "0.146.0", TOOLS = ["hub_review", "hub_task_show"];
+const CAP = 128 * 1024, MAX_SERVERS = 64;
+const digest = (value: string | Buffer) => createHash("sha256").update(value).digest("hex");
+/** Conservative translation of the portable core's regex sources; unfamiliar syntax refuses the receipt. */
+export function codexCoreDenyGlobs(names: readonly string[] = DENY_NAMES, segments: readonly string[] = DENY_SEGMENTS): string[] {
+  if (names.length > 64 || segments.length > 64) throw new Error("core deny policy bound exceeded");
+  const globs: string[] = [];
+  for (const source of names) {
+    if (typeof source !== "string" || source.length > 256) throw new Error("unverified core deny pattern");
+    const anchored = source.startsWith("^");
+    let body = anchored ? source.slice(1) : source;
+    const branch = "(\\.|$)", branchSuffix = anchored && body.endsWith(branch);
+    const end = !branchSuffix && body.endsWith("$");
+    if (!anchored && !end) throw new Error("unverified core deny pattern");
+    if (branchSuffix) body = body.slice(0, -branch.length);
+    else if (end) body = body.slice(0, -1);
+    let literal = "";
+    for (let i = 0; i < body.length; i++) {
+      const char = body[i]!;
+      if (char === "\\" && body[i + 1] === ".") { literal += "."; i++; }
+      else if (/^[A-Za-z0-9_-]$/.test(char)) literal += char;
+      else throw new Error("unverified core deny pattern");
+    }
+    if (!literal) throw new Error("empty core deny pattern");
+    const glob = `/**/${anchored ? "" : "*"}${literal}${end ? "" : "*"}`;
+    globs.push(glob, `${glob}/**`);
+  }
+  for (const segment of segments) {
+    if (typeof segment !== "string" || segment.length > 256 || !/^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(segment) || segment.split("/").some(part => part === "." || part === "..")) throw new Error("unverified core deny segment");
+    globs.push(`/**/${segment}`, `/**/${segment}/**`);
+  }
+  return [...new Set(globs)];
+}
+
+const inside = (file: string, root: string) => { const part = relative(root, file); return part === "" || part !== ".." && !part.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) && !isAbsolute(part); };
+const object = (value: unknown): Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid metadata");
+  return value as Record<string, unknown>;
+};
+function toml(value: unknown): string {
+  if (typeof value === "string" || typeof value === "boolean" || typeof value === "number") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(toml).join(",")}]`;
+  return `{${Object.entries(object(value)).map(([key, item]) => `${JSON.stringify(key)}=${toml(item)}`).join(",")}}`;
+}
+function metadata(file: string): string {
+  try { const link = lstatSync(file), stat = statSync(file); return [link.dev, link.ino, link.mtimeMs, stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(":"); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return "absent"; throw new Error("config metadata unavailable"); }
+}
+function configFiles(cwd: string, env: NodeJS.ProcessEnv): string[] {
+  const home = resolve(env.CODEX_HOME ?? join(homedir(), ".codex"));
+  const files = [join(home, "config.toml"), join(home, "cloud-config-bundle-cache.json"), "/etc/codex/config.toml", "/etc/codex/requirements.toml", "/etc/codex/managed_config.toml"];
+  // Include ancestors even outside the git root: no trust/layout assumption can hide a changed layer.
+  for (let dir = cwd; ; dir = dirname(dir)) { files.push(join(dir, ".codex", "config.toml")); if (dirname(dir) === dir) break; }
+  return files;
+}
+// Bounded host credential roots, not a universal private-home classifier. Never inspect their file contents.
+const HOST_CREDENTIAL_PATHS = [".config", ".ssh", ".aws", ".azure", ".kube", ".docker", ".gnupg", ".codex", ".claude", ".kimi", ".kimi-code", ".gemini", ".git-credentials", ".vault-token", "Library/Keychains", ".local/share/keyrings", ".password-store"] as const;
+const HOST_CREDENTIAL_ENV = ["XDG_CONFIG_HOME", "CODEX_HOME", "CLAUDE_CONFIG_DIR", "KIMI_CODE_HOME", "KIMI_HOME", "GEMINI_CLI_HOME", "GNUPGHOME", "AWS_SHARED_CREDENTIALS_FILE", "AWS_CONFIG_FILE", "AZURE_CONFIG_DIR", "DOCKER_CONFIG", "GOOGLE_APPLICATION_CREDENTIALS"] as const;
+/** A credential root that cannot be resolved. `label` is a path class (a standard name or an env var name), never a path or contents. */
+class CredentialRootError extends Error {
+  constructor(readonly label: string, readonly kind: "dangling" | "unreadable" | "unsupported") { super("credential root refused"); }
+}
+interface CredentialRoot { path: string; label: string }
+function hostCredentialRoots(env: NodeJS.ProcessEnv, cwd: string): CredentialRoot[] {
+  const home = resolve(cwd, env.HOME || homedir());
+  const homes = [...new Set([home, canonicalLabelled(home, "HOME")])];
+  const roots: CredentialRoot[] = homes.flatMap(base => HOST_CREDENTIAL_PATHS.map(entry => ({ path: join(base, entry), label: `~/${entry}` })));
+  const configured: CredentialRoot[] = HOST_CREDENTIAL_ENV.flatMap(key => env[key] ? [{ path: env[key]!, label: `$${key}` }] : []);
+  if (env.KUBECONFIG) configured.push(...env.KUBECONFIG.split(delimiter).filter(Boolean).map(path => ({ path, label: "$KUBECONFIG" })));
+  if (configured.length > 64) throw new Error("credential root bound exceeded");
+  for (const { path: entry, label } of configured) {
+    if (Buffer.byteLength(entry) > 4096 || /\p{Cc}/u.test(entry)) throw new CredentialRootError(label, "unsupported");
+    roots.push({ path: entry.startsWith("~/") ? resolve(home, entry.slice(2)) : resolve(cwd, entry), label });
+  }
+  const seen = new Set<string>();
+  return roots.filter(root => !seen.has(root.path) && seen.add(root.path));
+}
+function canonicalLabelled(lexical: string, label: string): string {
+  try { return credentialCanonicalPath(lexical); }
+  catch (error) { throw new CredentialRootError(label, (error as NodeJS.ErrnoException).code === "ENOENT" ? "dangling" : "unreadable"); }
+}
+/** Resolve absent descendants through the deepest existing ancestor; dangling links refuse admission. */
+function credentialCanonicalPath(lexical: string): string {
+  // Same strict ancestor algorithm as policyRealPath; importing path-policy here would cycle through the registry.
+  let ancestor = lexical;
+  for (;;) {
+    try { lstatSync(ancestor); break; }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT" || dirname(ancestor) === ancestor) throw error;
+      ancestor = dirname(ancestor);
+    }
+  }
+  return join(realPath(ancestor), relative(ancestor, lexical));
+}
+function denyCredentialRoots(filesystem: Record<string, string>, roots: readonly CredentialRoot[], cwd: string): void {
+  for (const { path: lexical, label } of roots) {
+    // Native profile keys with glob metacharacters cannot represent these literal host locations safely.
+    if (/[?*\[\]{}]/.test(lexical)) throw new CredentialRootError(label, "unsupported");
+    const targets = new Set([lexical, canonicalLabelled(lexical, label)]);
+    for (const target of targets) {
+      if (/[?*\[\]{}]/.test(target) || inside(cwd, target)) throw new CredentialRootError(label, "unsupported");
+      filesystem[target] = "deny"; filesystem[`${target.replace(/\/$/, "")}/**`] = "deny";
+    }
+  }
+}
+
+function resolveCommand(ctx: ReviewerPrepareContext, cwd: string): { command: string[]; files: string[] } {
+  const [name = "codex", ...prefix] = ctx.command ?? [];
+  const found = isAbsolute(name) ? name : Bun.which(name);
+  if (!found) throw new Error("host executable unavailable");
+  let binary = realPath(found);
+  // Bind the actual native binary, not the mutable npm launcher/interpreter selection.
+  if (basename(binary) === "codex.js") {
+    const target = process.platform === "darwin" ? process.arch === "arm64" ? "aarch64-apple-darwin" : "x86_64-apple-darwin"
+      : process.platform === "linux" ? process.arch === "arm64" ? "aarch64-unknown-linux-musl" : "x86_64-unknown-linux-musl" : undefined;
+    if (!target || !["arm64", "x64"].includes(process.arch)) throw new Error("unverified native platform");
+    const suffix = `${process.platform}-${process.arch === "x64" ? "x64" : "arm64"}`;
+    const manifest = createRequire(binary).resolve(`@openai/codex-${suffix}/package.json`);
+    binary = realPath(join(dirname(manifest), "vendor", target, "bin", "codex"));
+  }
+  const files = [binary];
+  if (inside(binary, cwd)) throw new Error("project executable refused");
+  for (const [index, arg] of prefix.entries()) {
+    // Privileged host argv may include a fixture/launcher script, but never a project-owned one.
+    if (isAbsolute(arg) && (index === 0 || /\.(?:js|ts|mjs|cjs|sh)$/.test(arg)) && existsSync(arg) && statSync(arg).isFile()) {
+      const file = realPath(arg); if (inside(file, cwd)) throw new Error("project command prefix refused"); files.push(file);
+    } else if (/\.(?:js|ts|mjs|cjs|sh)$/.test(arg)) throw new Error("unbound command prefix refused");
+  }
+  return { command: [binary, ...prefix], files };
+}
+interface Server { name: string; enabled: boolean; type: "stdio" | "http"; transport: Record<string, unknown> }
+function inventory(text: string): Server[] {
+  const raw: unknown = JSON.parse(text);
+  if (!Array.isArray(raw) || raw.length > MAX_SERVERS) throw new Error("inventory bound exceeded");
+  const seen = new Set<string>();
+  return raw.map(value => {
+    const row = object(value), transport = object(row.transport);
+    if (typeof row.name !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(row.name) || seen.has(row.name) || typeof row.enabled !== "boolean") throw new Error("invalid inventory identity");
+    seen.add(row.name);
+    const type = transport.type;
+    if (type !== "stdio" && type !== "http" && type !== "streamable_http") throw new Error("unverified MCP transport");
+    return { name: row.name, enabled: row.enabled, type: type === "stdio" ? "stdio" : "http", transport };
+  });
+}
+/** The configured MCP list omits runtime-synthesized Apps; verify the fixed feature gate separately. */
+function proveDisabledFeatures(text: string): void {
+  const rows = text.trim().split(/\r?\n/).map(line => line.trim());
+  if (rows.length > 512) throw new Error("feature inventory bound exceeded");
+  for (const name of ["apps", "plugins", "hooks"]) {
+    const matches = rows.filter(line => line.split(/\s+/)[0] === name);
+    if (matches.length !== 1 || !new RegExp(`^${name}\\s+stable\\s+false$`).test(matches[0]!)) throw new Error("effective feature isolation unverified");
+  }
+}
+function ownServer(text: string): Record<string, unknown> {
+  const config = object(JSON.parse(text)), servers = object(config.mcpServers);
+  if (Object.keys(servers).length !== 1 || !Object.hasOwn(servers, "agent-hub")) throw new Error("fixed hub MCP required");
+  const hub = object(servers["agent-hub"]);
+  if (Object.keys(hub).some(key => !["command", "args", "env"].includes(key)) || typeof hub.command !== "string" || !hub.command || hub.args !== undefined && (!Array.isArray(hub.args) || hub.args.some(arg => typeof arg !== "string"))) throw new Error("invalid hub transport");
+  const env = hub.env === undefined ? {} : object(hub.env);
+  if (Object.values(env).some(value => typeof value !== "string")) throw new Error("invalid hub environment");
+  return { command: hub.command, args: hub.args ?? [], env, enabled: true, required: true, enabled_tools: TOOLS };
+}
+
+/** All reads are model-free and bounded; stdout/config/env values never become diagnostic text. */
+async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string }> {
+  let root: string | undefined;
+  try {
+    const cwd = realPath(ctx.cwd), env = peerChildEnv(ctx.peer), bound = resolveCommand(ctx, cwd);
+    const initialBinaryMetadata = bound.files.map(metadata).join(";");
+    // Hash content once per receipt, then fence the identity with dev/ino/size/mtime/ctime metadata.
+    const binaryHash = digest(bound.files.map(file => digest(readFileSync(file))).join(";"));
+    if (bound.files.map(metadata).join(";") !== initialBinaryMetadata) throw new Error("binary changed while hashing");
+    const watched = configFiles(cwd, env), initialConfig = watched.map(metadata).join(";");
+    const deadline = performance.now() + 12_000;
+    const current = () => {
+      if (ctx.signal.aborted || watched.map(metadata).join(";") !== initialConfig) return false;
+      return bound.files.map(metadata).join(";") === initialBinaryMetadata;
+    };
+    const run = (args: readonly string[], capture = true, maxBytes = CAP) => new Promise<string>((resolveOutput, reject) => {
+      if (ctx.signal.aborted || performance.now() >= deadline) { reject(new Error("metadata deadline")); return; }
+      const [cmd, ...prefix] = bound.command;
+      const child = spawn(cmd!, [...prefix, ...args], { cwd, env, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+      let output = "", bytes = 0, failed = false, settled = false;
+      const stop = () => { failed = true; void finish(null); };
+      const timer = setTimeout(stop, Math.max(1, Math.min(2000, deadline - performance.now())));
+      ctx.signal.addEventListener("abort", stop, { once: true });
+      const finish = async (code: number | null) => {
+        if (settled) return; settled = true; clearTimeout(timer); ctx.signal.removeEventListener("abort", stop);
+        try { await stopOwnedProcess(child, { group: true, termMs: 100, killMs: 500 }); }
+        catch { reject(new Error("metadata cleanup unconfirmed")); return; }
+        if (failed || ctx.signal.aborted || code !== 0) reject(new Error("metadata proof refused")); else resolveOutput(output);
+      };
+      child.once("spawn", () => { trackGroup(child); if (ctx.signal.aborted) stop(); });
+      child.stdout.on("data", (chunk: Buffer) => { bytes += chunk.length; if (bytes > maxBytes) stop(); else if (capture) output += chunk.toString("utf8"); });
+      child.stderr.on("data", (chunk: Buffer) => { bytes += chunk.length; if (bytes > maxBytes) stop(); });
+      child.once("error", () => { failed = true; void finish(null); });
+      child.once("close", code => { void finish(code); });
+    });
+    if ((await run(["--version"])).trim() !== `codex-cli ${VERSION}`) throw new Error("native version has no isolation receipt");
+    if (Buffer.byteLength(ctx.mcpConfig) > CAP || ctx.privatePaths.length > 128) throw new Error("policy bounds exceeded");
+    const hub = ownServer(ctx.mcpConfig);
+    // Apps creates a runtime MCP server outside the configured inventory; independently pin and read back its gate.
+    const policy = ["--disable", "plugins", "--disable", "hooks", "--disable", "apps", "-c", 'web_search="disabled"', "-c", `projects=${toml({ [cwd]: { trust_level: "untrusted" } })}`];
+    proveDisabledFeatures(await run(["features", "list", ...policy]));
+    const before = inventory(await run(["mcp", "list", "--json", ...policy]));
+    if (before.some(row => row.name === "agent-hub")) throw new Error("ambient hub MCP collision");
+    const servers: Record<string, unknown> = Object.assign(Object.create(null), { "agent-hub": hub });
+    for (const server of before) servers[server.name] = server.type === "stdio" ? { command: "/usr/bin/false", enabled: false } : { url: "http://127.0.0.1:1", enabled: false };
+    const mcp = ["-c", `mcp_servers=${toml(servers)}`];
+    const after = inventory(await run(["mcp", "list", "--json", ...policy, ...mcp]));
+    if (after.length !== before.length + 1 || after.some(row => row.name !== "agent-hub" && !before.some(old => old.name === row.name)) || after.filter(row => row.enabled).map(row => row.name).join(",") !== "agent-hub") throw new Error("MCP inventory changed or is not strict");
+    const observed = object(JSON.parse(await run(["mcp", "get", "agent-hub", "--json", ...policy, ...mcp])));
+    if (observed.name !== "agent-hub" || observed.enabled !== true || !Array.isArray(observed.enabled_tools) || JSON.stringify(observed.enabled_tools) !== JSON.stringify(TOOLS)) throw new Error("hub tool allowlist unverified");
+    const observedTransport = object(observed.transport);
+    const observedEnv = object(observedTransport.env ?? {}), intendedEnv = object(hub.env);
+    if (observedTransport.type !== "stdio" || observedTransport.command !== hub.command || JSON.stringify(observedTransport.args ?? []) !== JSON.stringify(hub.args) || Object.keys(observedEnv).length !== Object.keys(intendedEnv).length || Object.entries(intendedEnv).some(([key, value]) => observedEnv[key] !== value)) throw new Error("hub transport changed");
+    // A real native sandbox probes a fresh private fixture: the model never sees these files.
+    root = realPath(mkdtempSync(join(tmpdir(), "ahub-codex-review-isolation-")));
+    const privateFile = join(root, "private.env"), publicFile = join(root, "public.txt"), writeFile = join(root, "write-proof");
+    const coreName = join(root, ".env"), coreStateDir = join(root, ".agenthub", "state"), coreState = join(coreStateDir, "private.txt");
+    const fixtureHome = join(root, "host-home"), hostConfig = join(fixtureHome, ".config", "gh", "hosts.yml"), hostKube = join(fixtureHome, ".kube", "config"), hostDocker = join(fixtureHome, ".docker", "config.json"), hostAlias = join(root, "host-alias.yml");
+    for (const file of [hostConfig, hostKube, hostDocker]) { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, "synthetic host credential fixture"); }
+    symlinkSync(hostConfig, hostAlias);
+    mkdirSync(coreStateDir, { recursive: true });
+    writeFileSync(coreName, "core name fixture"); writeFileSync(coreState, "core state fixture");
+    const globRoot = join(root, "glob"), nested = join(globRoot, "nested"), globFile = join(nested, "private.env"), alias = join(root, "alias.env");
+    mkdirSync(globRoot); mkdirSync(nested);
+    writeFileSync(privateFile, "private fixture"); writeFileSync(publicFile, "public fixture"); writeFileSync(globFile, "glob private fixture");
+    symlinkSync(globFile, alias);
+    const filesystem: Record<string, string> = { "/": "read", [privateFile]: "deny", [join(globRoot, "**", "*.env")]: "deny" };
+    for (const glob of codexCoreDenyGlobs()) filesystem[glob] = "deny";
+    denyCredentialRoots(filesystem, [...hostCredentialRoots(env, cwd), ...hostCredentialRoots({ HOME: fixtureHome }, cwd)], cwd);
+    for (const entry of ctx.privatePaths) {
+      if (typeof entry !== "string" || !entry || Buffer.byteLength(entry) > 4096 || /\p{Cc}/u.test(entry)) throw new Error("invalid private path policy");
+      // Native Seatbelt supports *, ?, and closed character classes, not brace alternatives.
+      if (/[{}]/.test(entry)) throw new Error("unverified private path pattern");
+      const homePath = entry === "~" || entry.startsWith("~/");
+      const absolute = homePath ? resolve(homedir(), entry.slice(2)) : isAbsolute(entry) ? entry : resolve(cwd, entry);
+      const patterns = new Set([absolute]);
+      if (!/[?*\[\]]/.test(absolute) && existsSync(absolute)) patterns.add(realPath(absolute));
+      if (!isAbsolute(entry) && !homePath && entry !== "." && entry !== "..") {
+        patterns.add(join(cwd, "**", entry));
+        // ctx combines PII path patterns and local substring denies: broadening is safer than omission.
+        if (!/[?*\[\]]/.test(entry)) patterns.add(join(cwd, "**", `*${entry.replace(/^\.\//, "").replace(/\/$/, "")}*`));
+      }
+      for (const pattern of patterns) { filesystem[pattern] = "deny"; filesystem[`${pattern.replace(/\/$/, "")}/**`] = "deny"; }
+    }
+    const profile = { filesystem, network: { enabled: false } }, permissions = ["-c", `permissions=${toml({ "ahub-review": profile })}`, "-c", 'default_permissions="ahub-review"'];
+    // ponytail: drain the pinned catalog without retaining it, capped at 4 MiB; replace with quiet config validation when the native CLI provides it.
+    await run(["debug", "models", "--bundled", ...policy, ...permissions], false, 4 * 1024 * 1024);
+    const script = 'if /bin/cat "$1" >/dev/null 2>&1; then echo AHUB_CODEX_PUBLIC_READ; fi; if /bin/cat "$2" >/dev/null 2>&1; then exit 12; else echo AHUB_CODEX_PRIVATE_DENIED; fi; if (echo no > "$3") 2>/dev/null; then exit 13; else echo AHUB_CODEX_WRITE_DENIED; fi; if /bin/cat "$4" >/dev/null 2>&1; then exit 14; else echo AHUB_CODEX_GLOB_PRIVATE_DENIED; fi; if /bin/cat "$5" >/dev/null 2>&1; then exit 15; else echo AHUB_CODEX_ALIAS_PRIVATE_DENIED; fi; if /bin/cat "$6" >/dev/null 2>&1; then exit 16; else echo AHUB_CODEX_CORE_NAME_DENIED; fi; if /bin/cat "$7" >/dev/null 2>&1; then exit 17; else echo AHUB_CODEX_CORE_STATE_DENIED; fi; if /bin/cat "$8" >/dev/null 2>&1; then exit 18; else echo AHUB_CODEX_HOST_CONFIG_DENIED; fi; if /bin/cat "$9" >/dev/null 2>&1; then exit 19; else echo AHUB_CODEX_HOST_KUBE_DENIED; fi; if /bin/cat "${10}" >/dev/null 2>&1; then exit 20; else echo AHUB_CODEX_HOST_DOCKER_DENIED; fi; if /bin/cat "${11}" >/dev/null 2>&1; then exit 21; else echo AHUB_CODEX_HOST_ALIAS_DENIED; fi';
+    const proof = await run(["sandbox", "-P", "ahub-review", "-C", cwd, ...policy, ...permissions, "/bin/sh", "-c", script, "proof", publicFile, privateFile, writeFile, globFile, alias, coreName, coreState, hostConfig, hostKube, hostDocker, hostAlias]);
+    if (proof.trim() !== "AHUB_CODEX_PUBLIC_READ\nAHUB_CODEX_PRIVATE_DENIED\nAHUB_CODEX_WRITE_DENIED\nAHUB_CODEX_GLOB_PRIVATE_DENIED\nAHUB_CODEX_ALIAS_PRIVATE_DENIED\nAHUB_CODEX_CORE_NAME_DENIED\nAHUB_CODEX_CORE_STATE_DENIED\nAHUB_CODEX_HOST_CONFIG_DENIED\nAHUB_CODEX_HOST_KUBE_DENIED\nAHUB_CODEX_HOST_DOCKER_DENIED\nAHUB_CODEX_HOST_ALIAS_DENIED" || existsSync(writeFile)) throw new Error("native sandbox isolation unverified");
+    if (!current()) throw new Error("binary or config changed during proof");
+    const cleanupRoot = root;
+    const launchProfile = digest(toml({ profile, servers, policy }));
+    return { command: bound.command, args: ["exec", "--ephemeral", "--ignore-user-config", "--ignore-rules", "--json", "--color", "never", "-C", cwd, ...policy, ...permissions, ...mcp, "-c", `developer_instructions=${toml(ctx.systemPrompt)}`, "-"], env,
+      current: () => { try { return current(); } catch { return false; } },
+      cleanup: () => rmSync(cleanupRoot, { recursive: true, force: true }),
+      isolation: { backend: "codex", version: VERSION, binary: `sha256:${binaryHash}`, profile: `sha256:${launchProfile}`, readOnly: true, strictMcp: true, ephemeral: true,
+        evidence: ["model-free-mcp-inventory-disabled-ambient", "hub-tools-exact-allowlist", "plugins-and-hooks-disabled", "apps-disabled-effective-feature-readback", "web-search-disabled", "project-untrusted", "native-public-read-private-deny-write-deny", "native-glob-and-symlink-private-deny", "portable-core-name-and-state-deny", "standard-host-credential-roots-denied", "binary-config-stable", "binary-hash-once-metadata-fence", "session-ephemeral"] } };
+  } catch (error) {
+    if (root) { try { rmSync(root, { recursive: true, force: true }); } catch { /* unavailable remains refused */ } }
+    // Name only the path class of an unusable credential root so a stale ~/.docker link is fixable; never a path or contents.
+    if (error instanceof CredentialRootError) {
+      const why = { dangling: "a dangling link", unreadable: "an unreadable path", unsupported: "unsupported syntax or overlapping the checkout" }[error.kind];
+      return { unavailable: `Codex reviewer isolation receipt unavailable (credential root ${error.label} is ${why}; remove or repair it)` };
+    }
+    return { unavailable: "Codex reviewer isolation receipt unavailable (version, MCP inventory, sandbox, configuration or process proof)" };
+  }
+}
+
+export const codexReviewerBackend: ReviewerBackend = {
+  id: "codex", prepare,
+  usage(event) {
+    const row = event as { type?: string; usage?: { input_tokens?: number; output_tokens?: number; cached_input_tokens?: number } };
+    return row?.type === "turn.completed" && row.usage ? { input_tokens: row.usage.input_tokens, output_tokens: row.usage.output_tokens, cache_read_input_tokens: row.usage.cached_input_tokens } : undefined;
+  },
+};

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

@@ -1,3 +1,4 @@
+import { claudeReviewerBackend, CODEX_REVIEWER_VARIANT, KIMI_REVIEWER_VARIANT } from "./reviewer-variants.ts";
 import { kimiAcpCommand } from "./native-daemon-kimi.ts";
 import { claudeRecoveryLaunch, kimiRecoveryLaunch, claudeRetainedTerminalNotice, piRetainedTerminalNotice, codexRetainedTerminalNotice, codexRosterReturnNotice, jcodeStartPreflight, claudeObservedVersion, codexObservedVersion } from "./native-daemon-policy.ts";
 import { piConfigSchema, localConfigSchema, piRoutingSchema, localRoutingSchema, PI_SETTINGS, PI_RESTART_REASONS, LOCAL_RESTART_REASONS, piEffectiveConfig } from "./native-config-policy.ts";
@@ -65,7 +66,7 @@ const CLAUDE_REVIEWER_VARIANT: AdapterDefinition = {
   identity: { mcp: "env" },
   permission: { modes: {}, unmanaged: "each review runs read-only (Read, Grep, Glob) and may call only hub_review and hub_task_show" },
   session: { idField: "sessionId", currentId: () => undefined, freshOnRestore: true, launchKind: "claude-print", crashPlan: () => ({ resume: {}, how: "claude reviewer: starts again; every review runs in a new session" }) },
-  turnEnd: "adapter", budget: { account: "claude" }, routing: { reviewOnly: true },
+  turnEnd: "adapter", budget: { account: "claude" }, routing: { reviewOnly: true }, reviewer: { backend: claudeReviewerBackend, defaultPool: true, declaration: "automatic" },
   cli: { command: "claude", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY,
 };
 
@@ -88,6 +89,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     reviewerVariant: CLAUDE_REVIEWER_VARIANT,
   },
   {
+    reviewerVariant: CODEX_REVIEWER_VARIANT,
     api: 1, kind: "codex", displayName: "Codex", family: "codex", transport: "codex-appserver",
     roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
     start: { create: createCodex, daemonPort: "codex-appserver", forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: codexNativeLaunch, version: codexObservedVersion, ...CODEX_LAUNCH_POLICY, conductorStartable: true,
@@ -98,9 +100,10 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
       grants: { ask: "the session's own approval policy applies again", "ask-when-needed": "approval policy on-request on every turn", "never-ask": "approval policy never on every turn: nothing asks" } },
     session: { nativeRevert: true, idField: "threadId", currentId: sessionId("threadId"), configDirEnv: "CODEX_HOME", zeroTurnFresh: true, launchKind: "codex", launchRecord: true, ...CODEX_RECOVERY_SESSION, crashPlan: codexCrashPlan, unrecordedTerminal: "always" },
     turnEnd: "adapter", budget: { account: "codex", checkpoint: true, reader: { source: "codex rateLimits", read: codexWindows }, context: { source: "codex_token_usage", read: codexContext } },
-    cli: { command: "codex", retainedTerminalNotice: codexRetainedTerminalNotice, rosterReturnNotice: codexRosterReturnNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["codex"] }, display: CODEX_DISPLAY, hooks: { recallPlatform: "codex", recallSource: "codex", recallInjected: true, pluginInventory: codexPluginInventory, classifyTool: codexToolSemantic },
+    cli: { command: "codex", launchConfigKeys: ["codex_bin"], retainedTerminalNotice: codexRetainedTerminalNotice, rosterReturnNotice: codexRosterReturnNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["codex"] }, display: CODEX_DISPLAY, hooks: { recallPlatform: "codex", recallSource: "codex", recallInjected: true, pluginInventory: codexPluginInventory, classifyTool: codexToolSemantic },
   },
   {
+    reviewerVariant: KIMI_REVIEWER_VARIANT,
     api: 1, kind: "kimi", displayName: "Kimi Code", family: "kimi", transport: "acp",
     roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
     start: { create: createKimi, acpCommand: kimiAcpCommand, explicitHeadlessMode: true, planCommand: () => "ahub kimi", daemonPort: "acp", forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("kimi", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
@@ -113,7 +116,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
       unmanagedForms: Object.freeze(["tui"] as const), unmanagedStatusNote: "Kimi approves tools in its own TUI; no hub permission mode", unmanagedNote: "Kimi approves tools and selects its permission mode in its own TUI; no hub permission mode" },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "acp", ...KIMI_RECOVERY_SESSION, crashPlan: kimiCrashPlan },
     turnEnd: "adapter", budget: { account: "kimi", resetSoftTokensOnResume: true, context: { source: "acp_usage_update", read: acpContextValue } }, capabilities: { watch: true }, init: { mcpFile: ".kimi-code/mcp.json" }, hooks: { recallPlatform: "kimi", recallSource: "kimi" },
-    cli: { command: "kimi", stopNotice: form => form === "tui" ? "Kimi belongs to its own TUI terminal; end it in that terminal" : "", startWords: form => ["kimi", "--mode", form] }, display: KIMI_DISPLAY,
+    cli: { command: "kimi", launchConfigKeys: ["kimi_cmd", "peers.kimi.start_mode"], stopNotice: form => form === "tui" ? "Kimi belongs to its own TUI terminal; end it in that terminal" : "", startWords: form => ["kimi", "--mode", form] }, display: KIMI_DISPLAY,
   },
   {
     api: 1, kind: "pi", enabledSwitchStartOnly: true, displayName: "Pi", family: "pi", transport: "hub-native",
@@ -125,7 +128,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     session: { idField: "sessionId", currentId: sessionId("sessionId"), restoreOnStart: true, launchKind: "pi", launchRecord: true, ...PI_RECOVERY_SESSION, crashPlan: piCrashPlan, unrecordedTerminal: "tui", continuityBookmark: piRecoveryContinuity, continuity: { key: "pi", parse: parsePiContinuity } },
     turnEnd: "adapter", budget: { account: "pi", instrumented: true }, reporting: { tokensNotReported: true }, configuration: { schema: piConfigSchema, routingSchema: piRoutingSchema, settings: PI_SETTINGS, restartReasons: PI_RESTART_REASONS, validateEffective: piEffectiveConfig },
     routing: { localAllowedRefusal: "local_allowed = false also excludes pi for this class", longContext: "backend-limit", preferredTier: true, handoffPriority: 0, trace: "backend", backendLabel: "pi" },
-    cli: { command: "pi", previewArgs: ["--mode", "tui"], retainedTerminalNotice: piRetainedTerminalNotice, personOnlyFlags: ["--replace-session"], startWords: form => ["pi", "--mode", form] }, display: PI_DISPLAY,
+    cli: { command: "pi", launchConfigKeys: ["pi.cmd", "pi.backend", "pi.dgx_coding", "pi.dgx_fast", "pi.max_steps", "routing.pi", "peers.pi.start_mode"], previewArgs: ["--mode", "tui"], retainedTerminalNotice: piRetainedTerminalNotice, personOnlyFlags: ["--replace-session"], startWords: form => ["pi", "--mode", form] }, display: PI_DISPLAY,
   },
   {
     api: 1, kind: "local", displayName: "Local worker", family: "local", transport: "hub-native",
@@ -137,7 +140,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "local", ...LOCAL_RECOVERY_SESSION, crashPlan: localCrashPlan },
     turnEnd: "adapter", budget: { account: "local", quotaExempt: true, instrumented: true }, configuration: { schema: localConfigSchema, routingSchema: localRoutingSchema, restartReasons: LOCAL_RESTART_REASONS },
     routing: { localAllowedRefusal: "local_allowed = false for this class", longContext: "skip-owner", preferredTier: true, handoffPriority: 1, trace: "route" },
-    cli: { command: "local", startWords: () => ["local"] }, display: LOCAL_DISPLAY,
+    cli: { command: "local", launchConfigKeys: ["local.deny", "local.bash_network", "local.network_allow", "local.max_steps", "local.read_allow", "routing.local"], startWords: () => ["local"] }, display: LOCAL_DISPLAY,
   },
   {
     api: 1, kind: "jcode", displayName: "Jcode", family: "jcode", transport: "acp",
@@ -148,7 +151,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
       ask: "no verified hub mode mapping; native policy only", "ask-when-needed": "no verified hub mode mapping; native policy only", "never-ask": "no verified hub mode mapping; native policy only" } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "jcode", ...JCODE_RECOVERY_SESSION, crashPlan: jcodeCrashPlan }, turnEnd: "adapter", budget: { account: "jcode" },
     // Jcode has no dedicated CSS swatch today: retain peer-palette.ts's existing 'other' fallback.
-    cli: { command: "jcode", authority: "person", startWords: () => ["jcode"] }, display: JCODE_DISPLAY, hooks: { recallPlatform: "jcode" },
+    cli: { command: "jcode", authority: "person", launchConfigKeys: ["jcode_cmd", "jcode_home", "jcode_provider_profile"], startWords: () => ["jcode"] }, display: JCODE_DISPLAY, hooks: { recallPlatform: "jcode" },
   },
 ] satisfies AdapterDefinition[]);
 

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

@@ -1,3 +1,4 @@
+import { retainedLaunchWarning } from "./native-cli-retained.ts";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -14,6 +15,8 @@ export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void>
     if (args.includes("--print-command") || args.includes("--dry-run")) return console.log(JSON.stringify({ peer, start: "hub", note: "a headless reviewer the hub runs per review" }, null, 2));
     const hub = await ctx.connect();
     try {
+      const snapshot = (await hub.request({ t: "status" })).status;
+      const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
       const res = await hub.request({ t: "start", peer, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
       if (res.ok !== true) fail(String(res.error ?? `${peer} was not started`));
     } finally { hub.close(); }

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

@@ -1,3 +1,4 @@
+import { retainedLaunchWarning } from "./native-cli-retained.ts";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 
 export async function runCodexEntry(ctx: NativeCliEntryContext): Promise<void> {
@@ -19,6 +20,8 @@ export async function runCodexEntry(ctx: NativeCliEntryContext): Promise<void> {
   // only when a future recovery receipt supplies independently verified exact-instance execution-root evidence.
   if (recovering && !ctx.instance && before?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, before.instanceId);
   const hub = await connect();
+  const snapshot = (await hub.request({ t: "status" })).status;
+  const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
   const res = await hub.request({ t: "start", peer, args: { unattended: launch0.unattended === true }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
   hub.close();
   if (!res.ok) fail(res.error);
@@ -28,7 +31,8 @@ export async function runCodexEntry(ctx: NativeCliEntryContext): Promise<void> {
   }
   const control = readControl(stateDir);
   if ((!recovering || ctx.instance) && control?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd: ctx.executionCwd } : undefined);
-  const launch = buildLaunch("codex", args, { unattended: unattendedEnv, instance: peer, proxyUrl: res.proxyUrl, codexBin: projectConfig().codex_bin });
+  const runningCodexBin = res.retainedLaunchConfig?.codex_bin;
+  const launch = buildLaunch("codex", args, { unattended: unattendedEnv, instance: peer, proxyUrl: res.proxyUrl, codexBin: typeof runningCodexBin === "string" ? runningCodexBin : projectConfig().codex_bin });
   if (launch0.warning) console.error(launch0.warning);
   exec(launch.cmd, launch.args, "codex");
 }

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

@@ -1,3 +1,4 @@
+import { retainedLaunchWarning } from "./native-cli-retained.ts";
 import { resolve } from "node:path";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 import { bundleInStatus, rosterInStatus } from "../../hub/status-roster.ts";
@@ -18,6 +19,7 @@ export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
     const rostered = rosterInStatus(snapshot, "jcode");
     if (rostered === undefined) fail("cannot read jcode's roster membership from the running hub; upgrade or restart it, then retry (nothing was started)");
     if (!rostered) fail("jcode is off roster; add it with ahub roster add jcode");
+    const warning = retainedLaunchWarning(snapshot, "jcode", ctx.definition); if (warning) console.error(warning);
     // The daemon verifies the entry against its own bundle; fall back to this CLI's copy only for a hub that reports none.
     const written = configureJcodeMcp(cwd, stateDir, bundleInStatus(snapshot) ?? resolve(cliDir, "../../plugins/agent-hub/server.js"));
     if (written.tracked) console.error(".jcode/mcp.json is tracked; review this local machine-path change before committing it");

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

@@ -1,3 +1,4 @@
+import { retainedLaunchWarning } from "./native-cli-retained.ts";
 import { resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
@@ -6,19 +7,22 @@ import { bundleInStatus, rosterInStatus } from "../../hub/status-roster.ts";
 export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
   const peer = ctx.instance ?? "kimi";
   const { args, cwd, stateDir, cliDir, unattendedEnv, projectConfig, connect, fail, takeFlags } = ctx;
-  const { launcherPreview, startModeOf, buildKimiTuiLaunch, configureKimiMcp, nativeLaunchEnv, childEnv } = ctx.helpers;
+  const { launcherPreview, readControl, startModeOf, buildKimiTuiLaunch, configureKimiMcp, nativeLaunchEnv, childEnv } = ctx.helpers;
   if (args.includes("--print-command") || args.includes("--dry-run")) {
     try { return console.log(JSON.stringify(launcherPreview("kimi", args, cwd, stateDir, unattendedEnv), null, 2)); }
     catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
   }
   const { one, rest } = takeFlags(args, ["--mode", "--model"], []);
-  const mode = one["--mode"] ?? (ctx.instance ? "headless" : startModeOf(projectConfig().peers, "kimi")), model = one["--model"];
+  const acceptedMode = readControl(stateDir)?.startModes?.[peer];
+  const mode = one["--mode"] ?? (ctx.instance ? "headless" : acceptedMode ?? startModeOf(projectConfig().peers, "kimi")), model = one["--model"];
   if (ctx.instance && mode !== "headless") fail("extra Kimi instances require headless mode");
   if (rest.length || !["tui", "headless"].includes(mode)) fail("usage: ahub kimi [--mode tui|headless] [--model <alias>]");
   if (mode === "tui" && one["--mode"] === undefined && !(process.stdin.isTTY && process.stdout.isTTY)) {
     if (model) fail("Kimi's TUI needs a terminal for these options; run in a terminal or add --mode headless");
     const hub = await connect();
     try {
+      const snapshot = (await hub.request({ t: "status" })).status;
+      const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
       const reply = await hub.request({ t: "peer_start", peer }, 35_000);
       if (!reply.ok) fail(reply.error);
       return console.log(reply.already ? "kimi is already attached" : `kimi: opened a terminal running ${reply.command}; it attaches pull-only when its TUI is ready`);
@@ -27,15 +31,17 @@ export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
   const hub = await connect();
   try {
     if (mode === "tui") {
-      const launch = buildKimiTuiLaunch(projectConfig().kimi_cmd, model);
       const snapshot = (await hub.request({ t: "status" })).status;
       const rostered = rosterInStatus(snapshot, peer);
       if (rostered === undefined) fail("cannot read kimi's roster membership from the running hub; upgrade or restart it, then retry (nothing was started)");
       if (!rostered) fail("kimi is off roster; add it with ahub roster add kimi");
+      const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
       const owner = snapshot?.peers?.[peer];
       if (owner && !["offline"].includes(owner.state) && !owner.pullOnly) fail("Kimi is running headless; run ahub stop kimi before starting its TUI");
       const admission = await hub.request({ t: "start", peer, args: { mode: "tui" }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
       if (!admission.ok) fail(admission.error);
+      const runningCommand = admission.retainedLaunchConfig?.kimi_cmd;
+      const launch = buildKimiTuiLaunch(Array.isArray(runningCommand) && runningCommand.every((arg: unknown) => typeof arg === "string") ? runningCommand : projectConfig().kimi_cmd, model);
       let result: ReturnType<typeof spawnSync>;
       try {
         // The daemon's own bundle, so the MCP server matches the hub it talks to (#502); this CLI's copy only for an older hub.
@@ -48,7 +54,9 @@ export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
       if (result.error) fail(`cannot run ${launch.cmd}: ${result.error.message}`);
       process.exit(result.status ?? 1);
     }
-    const owner = (await hub.request({ t: "status" })).status?.peers?.[peer];
+    const snapshot = (await hub.request({ t: "status" })).status;
+    const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
+    const owner = snapshot?.peers?.[peer];
     if (owner?.pullOnly && owner.state !== "offline") fail("Kimi runs in a terminal; end it there before starting a headless one");
     if (!ctx.instance) configureKimiMcp(cwd, stateDir, resolve(cliDir, "../../plugins/agent-hub/server.js"), "headless");
     const res = await hub.request({ t: "start", peer, args: { mode: "headless", model }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });

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

@@ -1,3 +1,4 @@
+import { retainedLaunchWarning } from "./native-cli-retained.ts";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 
 export async function runLocalEntry(ctx: NativeCliEntryContext): Promise<void> {
@@ -8,6 +9,8 @@ export async function runLocalEntry(ctx: NativeCliEntryContext): Promise<void> {
   if (args.includes("--route") && args.includes("--model")) fail("use --route or --model, not both");
   if (args.some((a, i) => i % 2 === 0 && !["--route", "--model"].includes(a))) fail("usage: ahub local [--route <id> | --model <id>]");
   const hub = await connect();
+  const snapshot = (await hub.request({ t: "status" })).status;
+  const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
   const res = await hub.request({ t: "start", peer, args: { route: opt("--route"), model: opt("--model") }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
   hub.close();
   if (!res.ok) fail(res.error);

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

@@ -1,3 +1,4 @@
+import { retainedLaunchWarning } from "./native-cli-retained.ts";
 import { parsePiFlags } from "./native-cli-pi.ts";
 import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
 
@@ -12,8 +13,9 @@ export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
     catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
   }
   const flags = parsePiFlags(args, fail);
+  const acceptedMode = ctx.helpers.readControl(stateDir)?.startModes?.[peer];
   // #269: with no flag, Pi's start mode decides, and that is its TUI unless a person set headless.
-  const options = { ...flags, mode: flags.mode ?? (ctx.instance ? "headless" : startModeOf(projectConfig().peers, "pi")) };
+  const options = { ...flags, mode: flags.mode ?? (ctx.instance ? "headless" : acceptedMode ?? startModeOf(projectConfig().peers, "pi")) };
   if (ctx.instance && options.mode !== "headless") fail("extra Pi instances require headless mode");
   if (flags.mode === undefined && options.mode === "tui" && !(process.stdin.isTTY && process.stdout.isTTY)) {
     // The default asked for the TUI and there is no terminal here (the console's command line, a script): the hub
@@ -22,6 +24,8 @@ export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
     if (Object.keys(flags).length) fail("Pi's TUI needs a terminal, and these options are not passed to one the hub opens: run this in a terminal, or add --mode headless");
     const hub = await connect();
     try {
+      const snapshot = (await hub.request({ t: "status" })).status;
+      const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
       const reply = await hub.request({ t: "peer_start", peer }, 35_000);
       if (reply.ok !== true) {
         const error = String(reply.error ?? "pi start refused");
@@ -36,6 +40,8 @@ export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
   const before = readControl(stateDir);
   if (recovering && before?.instanceId) await recordTerminalLaunch(peer, cwd, stateDir, before.instanceId);
   const hub = await connect();
+  const snapshot = (await hub.request({ t: "status" })).status;
+  const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
   const res = await hub.request({ t: "start", peer, args: options, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
   hub.close();
   if (!res.ok) fail(res.error);

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

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

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

@@ -1,3 +1,4 @@
+import { runAgyEntry } from "../agy/entry.ts";
 import type { BuiltinCliEntry } from "./native-cli-entry-types.ts";
 import { runClaudeEntry } from "./native-cli-entry-claude.ts";
 import { runCodexEntry } from "./native-cli-entry-codex.ts";
@@ -9,6 +10,7 @@ import { runLocalEntry } from "./native-cli-entry-local.ts";
 
 // Fixed trusted builtins only. No project configuration, caller payload or external module can register an entry.
 export const builtinCliEntries: readonly BuiltinCliEntry[] = Object.freeze([
+  { command: "agy", lifecycleAdmission: true, execute: runAgyEntry },
   { command: "claude", lifecycleAdmission: true, execute: runClaudeEntry },
   { command: "codex", lifecycleAdmission: true, execute: runCodexEntry },
   { command: "jcode", lifecycleAdmission: true, execute: runJcodeEntry },

package/src/adapters/definitions/native-cli-retained.ts

@@ -0,0 +1,15 @@
+import type { AdapterDefinition } from "../registry-types.ts";
+
+/** Explain a retained launch setting using only metadata from the selected adapter definition. */
+export function retainedLaunchWarning(status: unknown, peer: string, definition: AdapterDefinition): string | undefined {
+  const keys = definition.cli.launchConfigKeys;
+  const retained = (status as { retainedConfig?: unknown } | undefined)?.retainedConfig;
+  if (!keys?.length || !Array.isArray(retained)) return;
+  const pending = retained.flatMap(row => {
+    if (!row || typeof row !== "object") return [];
+    const key = (row as { key?: unknown }).key;
+    return typeof key === "string" && keys.some(candidate => key === candidate || key.startsWith(`${candidate}.`)) ? [key] : [];
+  });
+  const unique = [...new Set(pending)];
+  return unique.length ? `ahub: config retained: ${unique.join(", ")}; starting ${peer} with the running value; run ahub settings reload to apply the file's value` : undefined;
+}