@staix/agent-hub 0.12.33 → 0.12.34

package/src/cli/preview.ts

@@ -1,134 +1,23 @@
-import { definitionOf, kindOf } from "../adapters/registry.ts";
-import { jcodeCommand } from "../adapters/jcode.ts";
-import { qwenSessionId } from "../hub/crash.ts";
-import { readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { definitionOf, builtinPreviewOf } from "../adapters/registry.ts";
 import { loadConfig } from "../hub/daemon.ts";
 import { childEnv } from "../hub/child-process.ts";
-import { relayModelIds } from "../models/relay.ts";
-import { buildPiLaunch } from "../pi/launch.ts";
 import { startModeOf } from "../hub/start-mode.ts";
-import { buildLaunch, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, claudeObservationHooks, type Launch } from "./launch.ts";
+import { buildLaunch, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, claudeObservationHooks } from "./launch.ts";
 import { kimiMcpPlan } from "./kimi-mcp.ts";
+import { jcodeCommand } from "../adapters/jcode.ts";
+import { qwenSessionId } from "../hub/crash.ts";
+import { relayModelIds } from "../models/relay.ts";
+import { buildPiLaunch } from "../pi/launch.ts";
 
-const REDACTED = "[redacted]";
-const UNRESOLVED = "[unresolved]";
-/** Arbitrary native arguments can contain secrets even without a credential-looking key. */
-function publicArg(arg: string): string {
-  const flags = new Set(["--settings", "--model", "--mcp-config", "--session-id", "--session-file", "--resume", "--continue", "--print", "--safe", "--new"]);
-  const key = arg.split("=", 1)[0]!;
-  return flags.has(key) ? (arg.includes("=") ? key + "=" + REDACTED : key) : REDACTED;
-}
-function nativeCommand(command: string[], trusted: string[]): string[] {
-  return command.map((value, i) => value === trusted[i] ? value : REDACTED);
-}
-/** Read-only preview. Inputs passed to shared native builders are redacted before serialization. */
+/** Read-only builtin preview. Native redaction uses the same launch builders as actual startup. */
 export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi" | "qwen" | "jcode", raw: string[], cwd: string, stateDir: string, unattended: boolean) {
   const args = raw.filter(arg => !["--print-command", "--dry-run", "--json"].includes(arg));
   const config = loadConfig(cwd);
-  const unresolved: { field: string; reason: string }[] = [];
-  let launch: Launch;
-  let kimiMetadata: { mode: "tui" | "headless"; mcp: { file: string; action: string; changed: boolean; tracked: boolean } } | undefined;
-  let envNames = Object.keys(childEnv()).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR"]);
-  const value = (flag: string) => {
-    const at = args.indexOf(flag);
-    if (at < 0) return undefined;
-    const next = args[at + 1];
-    if (!next || next.startsWith("--")) throw new Error("missing option value");
-    return next;
-  };
-  if (tool === "claude") {
-    let original: { command?: string; refreshInterval?: number; padding?: number } | undefined;
-    for (const file of [join(cwd, ".claude/settings.local.json"), join(cwd, ".claude/settings.json"), join(process.env.HOME ?? "", ".claude/settings.json")]) {
-      try { original ??= JSON.parse(readFileSync(file, "utf8")).statusLine; } catch { /* optional */ }
-    }
-    // Build with original inputs so channel selection and owned-flag validation match normal launch.
-    const facts = claudeObservationHooks(config, { script: join(import.meta.dir, "facts-hook.ts"), stateDir });
-    launch = buildLaunch(tool, args, { preview: true, unattended, statusLine: { script: join(import.meta.dir, "statusline-tee.ts"), stateDir, ...(original ? { original: { command: original.command ? REDACTED : "", ...(typeof original.refreshInterval === "number" && Number.isFinite(original.refreshInterval) ? { refreshInterval: original.refreshInterval } : {}), ...(typeof original.padding === "number" && Number.isFinite(original.padding) ? { padding: original.padding } : {}) } } : {}) }, ...(facts ? { facts } : {}) });
-    // Merged caller settings change the native argument count. Rebuild a redacted preview,
-    // retaining the managed hooks but never serializing caller settings or their file path.
-    const safeArgs = args.map((arg, i) => {
-      if (args[i - 1] === "--settings") return "{}";
-      if (arg.startsWith("--settings=")) return "--settings={}";
-      if (["--unattended", "--safe", "--new"].includes(arg)) return arg;
-      return publicArg(arg);
-    });
-    const publicLaunch = buildLaunch(tool, safeArgs, { preview: true, unattended, statusLine: { script: join(import.meta.dir, "statusline-tee.ts"), stateDir,
-      ...(original ? { original: { command: original.command ? REDACTED : "", ...(typeof original.refreshInterval === "number" && Number.isFinite(original.refreshInterval) ? { refreshInterval: original.refreshInterval } : {}), ...(typeof original.padding === "number" && Number.isFinite(original.padding) ? { padding: original.padding } : {}) } } : {}) }, facts });
-    publicLaunch.args.splice(0, 2, ...launch.args.slice(0, 2)); // channel selection was verified against the original MCP config
-    launch = publicLaunch;
-  } else if (tool === "codex") {
-    // A fresh native proxy is assigned by start, never guessed from an old status file.
-    launch = buildLaunch(tool, args, { unattended, proxyUrl: UNRESOLVED, codexBin: config.codex_bin === "codex" ? "codex" : REDACTED });
-    const passthrough = args.filter(arg => !["--unattended", "--safe", "--new"].includes(arg));
-    launch.args = launch.args.slice(0, launch.args.length - passthrough.length).concat(passthrough.map(publicArg));
-    unresolved.push({ field: "proxyUrl", reason: "assigned when the native adapter starts; preview does not start it" });
-  } else if (tool === "jcode") {
-    const mode = value("--mode") ?? "headless", model = value("--model"), profile = value("--provider-profile"), session = value("--session-id");
-    if (mode !== "headless") throw new Error("Jcode TUI driving is unverified");
-    for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode", "--provider-profile", "--session-id"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Jcode option");
-    if (session !== undefined && !qwenSessionId(session)) throw new Error("invalid Jcode session identity");
-    const cmd = jcodeCommand(nativeCommand(config.jcode_cmd, ["jcode"]), "acp", UNRESOLVED, UNRESOLVED, model ? REDACTED : undefined, profile || config.jcode_provider_profile ? REDACTED : undefined);
-    launch = { cmd: cmd[0]!, args: cmd.slice(1) };
-    unresolved.push({ field: "ownedDaemon", reason: "private daemon/socket and source-pinned native identity verified at start; preview starts nothing" });
-    unresolved.push({ field: "hubTools", reason: "project MCP bridge required; native tool-call receipt remains unverified" });
-  } else if (kindOf(tool) === "qwen") {
-    const mode = value("--mode") ?? "headless", model = value("--model");
-    const adapter = definitionOf(tool)!;
-    if (!(adapter.start.forms as readonly string[]).includes(mode)) throw new Error("Qwen TUI is not offered before verification");
-    for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode", "--session-id"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Qwen option");
-    const sessionId = value("--session-id");
-    if (sessionId !== undefined && !adapter.session.crashIdentity?.({ sessionId }).sessionId) throw new Error("invalid Qwen session identity");
-    if (sessionId) unresolved.push({ field: "sessionId", reason: "requested through ACP session/load at start; preview does not load or expose it" });
-    launch = adapter.start.launch({ instance: tool, form: "headless", projectRoot: cwd, stateDir, entrypoint: join(import.meta.dir, "main.js"),
-      userArgs: [], unattended: false, env: {}, preview: true, nativeCommand: nativeCommand(config.qwen_cmd, ["qwen", "--acp"]), model: model ? REDACTED : undefined });
-    unresolved.push({ field: "nativeIdentity", reason: "Qwen Code 0.25.0 identity and permission modes are checked at ACP initialization; preview starts nothing" });
-  } else if (tool === "kimi") {
-    const model = value("--model");
-    const mode = value("--mode") ?? startModeOf(config.peers, "kimi");
-    if (mode !== "tui" && mode !== "headless") throw new Error("invalid Kimi mode");
-    for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Kimi option");
-    if (mode === "headless") {
-      launch = buildKimiLaunch(nativeCommand(config.kimi_cmd, ["kimi", "acp"]), model ? REDACTED : undefined);
-      unresolved.push({ field: "sessionId", reason: "ACP session identity is available only after native initialization" });
-    } else {
-      const native = buildKimiTuiLaunch(config.kimi_cmd, model ? REDACTED : undefined);
-      launch = { ...native, cmd: native.cmd === "kimi" ? "kimi" : REDACTED, args: native.args.map(arg => arg === "--model" || arg === REDACTED ? arg : REDACTED) };
-      envNames = Object.keys(nativeLaunchEnv("kimi", childEnv())).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR"]);
-    }
-    const { file, action, changed, tracked } = kimiMcpPlan(cwd, stateDir, join(import.meta.dir, "../../plugins/agent-hub/server.js"), mode);
-    kimiMetadata = { mode, mcp: { file, action, changed, tracked } };
-  } else {
-    const mode = value("--mode") ?? startModeOf(config.peers, "pi"); // #269: the same default `ahub pi` takes
-    const backend = value("--backend") ?? config.pi.backend;
-    if (!["headless", "tui"].includes(mode) || !["auto", "dgx", "mlx"].includes(backend) || (value("--session-id") && value("--session-file"))) throw new Error("invalid Pi options");
-    if (args.includes("--replace-session") && (!value("--session-file") || value("--session-id"))) throw new Error("--replace-session requires --session-file, without --session-id");
-    for (let i = 0; i < args.length; i++) {
-      if (args[i] === "--replace-session") continue;
-      if (!["--mode", "--backend", "--model", "--session-id", "--session-file"].includes(args[i]!) || !value(args[i]!)) throw new Error("unknown Pi option");
-      i++;
-    }
-    if (args.includes("--replace-session")) unresolved.push({ field: "session replacement", reason: "requires a person, a validated managed file and an offline settled owner at runtime; preview changes nothing" });
-    const models = relayModelIds({ enableHubAuto: true, mlx: config.mlx.enabled === false ? undefined : config.mlx, mlxAlias: "mlx/fast", allowedDGXmodels: { "dgx/coding": config.pi.dgx_coding, "dgx/fast": config.pi.dgx_fast } });
-    const pi = buildPiLaunch({
-      stateDir, cmd: nativeCommand(config.pi.cmd, ["pi"]), mode: mode as "headless" | "tui", backend: backend as "auto" | "dgx" | "mlx",
-      ...(value("--model") ? { model: REDACTED } : {}),
-      ...(value("--session-id") ? { sessionId: REDACTED } : {}),
-      ...(value("--session-file") ? { sessionFile: REDACTED } : {}),
-      relay: { url: UNRESOLVED, token: UNRESOLVED, models: models.map(id => ({ id })) },
-      tools: [], preamble: REDACTED, maxSteps: config.pi.max_steps,
-    }, {}, resolve(join(import.meta.dir, "../pi/extension.ts")), UNRESOLVED, UNRESOLVED);
-    launch = pi;
-    envNames = Object.keys(pi.env).concat(["PATH", "HOME", "USER", "SHELL", "TMPDIR", "TERM", "TERM_PROGRAM", "LANG", "LC_ALL", "LC_CTYPE", "NO_COLOR", "CODEX_HOME"].filter(key => process.env[key] !== undefined));
-    if (mode === "tui") envNames.push("AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR");
-    unresolved.push({ field: "bridge/relay endpoints and owner credentials", reason: "assigned at runtime; preview does not bind a server or start a model" });
-    if (!value("--session-id") && !value("--session-file")) unresolved.push({ field: "sessionId", reason: "new native session identity is not allocated by preview" });
-  }
-  if (tool === "claude") envNames.push("AGENTHUB_CHANNEL");
-  if (tool === "claude" || tool === "codex") {
-    envNames.push("AGENTHUB_INSTANCE_ID", "AGENTHUB_LAUNCH_ID");
-    unresolved.push({ field: "env.AGENTHUB_INSTANCE_ID", reason: tool === "claude" ? "injected when an existing daemon instance is read at launch; preview does not read runtime state" : "injected when a verified Orca terminal launch is recorded against the daemon; preview does not record it" });
-    unresolved.push({ field: "env.AGENTHUB_LAUNCH_ID", reason: "allocated only for a verified Orca terminal launch; preview does not query Orca, allocate identity or write launch records" });
-  }
-  return { tool, ...(kimiMetadata ?? {}), cmd: launch.cmd, args: launch.args, settings: tool === "claude" && launch.args.includes("--settings") ? launch.args[launch.args.indexOf("--settings") + 1] : undefined, envNames: [...new Set(envNames)].sort(), ...(launch.warning ? { warning: launch.warning } : {}), unresolved, redaction: "Arbitrary user arguments, settings, commands and configured executable overrides are redacted. Environment values are never displayed.", needs: ["Native executable, accounts and runtime readiness are not checked."] };
+  const definition = definitionOf(tool), preview = builtinPreviewOf(tool);
+  if (!definition || !preview) throw new Error("native preview definition unavailable");
+  return preview({ tool, args, cwd, stateDir, cliDir: import.meta.dir, unattended, config, definition,
+    baseEnvNames: Object.keys(childEnv()).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR"]),
+    helpers: { buildLaunch, claudeObservationHooks, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, childEnv,
+      startModeOf, kimiMcpPlan, jcodeCommand, qwenSessionId, relayModelIds, buildPiLaunch },
+  });
 }

package/src/cli/recovery-guidance.ts

@@ -1,3 +1,4 @@
+import { ADAPTERS, definitionOf } from "../adapters/registry.ts";
 import { recordedFileState } from "./recovery-session-file.ts";
 import { decodeRestoreReceipt } from "./upgrade-restore-state.ts";
 import { shellQuote } from "./terminal-recovery.ts";
@@ -25,11 +26,13 @@ export interface RecoveryGuidanceOptions {
 
 const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
 const argv = (...words: string[]): string => words.map(shellQuote).join(" ");
-const peers: readonly RecoveryNativePeer[] = ["codex", "pi", "claude"];
+const peers = (): RecoveryNativePeer[] => ADAPTERS.filter(adapter => adapter.session.launchRecord)
+  .sort((a, b) => Number(a.transport === "claude-channel") - Number(b.transport === "claude-channel"))
+  .map(adapter => adapter.kind as RecoveryNativePeer);
 
 function sourceSession(peer: RecoveryNativePeer, source: RecoveryPeer | undefined): { sessionId?: string; sessionFile?: string } {
-  const sessionId = peer === "codex" ? source?.threadId : source?.sessionId;
-  const sessionFile = peer === "pi" ? source?.sessionFile ?? source?.args?.sessionFile : undefined;
+  const sessionId = source?.[definitionOf(peer)?.session.idField ?? "sessionId"];
+  const sessionFile = definitionOf(peer)?.session.crashIdentity ? source?.sessionFile ?? source?.args?.sessionFile : undefined;
   return { ...(text(sessionId) ? { sessionId } : {}), ...(text(sessionFile) ? { sessionFile } : {}) };
 }
 
@@ -70,7 +73,7 @@ export function resolveAcceptedBinding(planned: PlannedProject, progress: Projec
  * current receipts and the original plan. A malformed current receipt otherwise stays unavailable.
  */
 export function recordedPeerGuidance(planned: PlannedProject, progress: ProjectProgress, options: RecoveryGuidanceOptions = {}): RecordedPeerGuidance[] {
-  return peers.map(peer => {
+  return peers().map(peer => {
     let session: { sessionId?: string; sessionFile?: string } | undefined;
     let unavailable = false;
     const override = options.recorded && Object.hasOwn(options.recorded, peer) ? options.recorded[peer] : undefined;
@@ -82,18 +85,19 @@ export function recordedPeerGuidance(planned: PlannedProject, progress: ProjectP
       } catch { unavailable = true; }
     }
     const sessionId = text(session?.sessionId) ? session.sessionId : undefined;
-    const sessionFile = peer === "pi" && text(session?.sessionFile) ? session.sessionFile : undefined;
+    const sessionFile = definitionOf(peer)?.session.crashIdentity && text(session?.sessionFile) ? session.sessionFile : undefined;
     if (unavailable || (!sessionId && !sessionFile)) return { peer, note: `${peer}: recorded session identity unavailable; inspect the retained recovery receipt before choosing a conversation` };
     const prefix = ["ahub", "--project", planned.project.root];
-    const command = peer === "codex"
-      ? sessionId ? argv(...prefix, "codex", "resume", sessionId) : undefined
-      : peer === "pi"
-        ? sessionFile ? argv(...prefix, "pi", "--session-file", sessionFile) : sessionId ? argv(...prefix, "pi", "--session-id", sessionId) : undefined
-        : sessionId ? argv(...prefix, "claude", "--resume", sessionId) : undefined;
-    let note = peer === "claude"
+    const adapter = definitionOf(peer)!;
+    const tail = adapter.session.resumeArgv?.({ sessionId: sessionId ?? "", ...(sessionFile ? { sessionFile } : {}) }, false);
+    const start = adapter.cli.startWords("tui");
+    // Person guidance preserves its legacy implied startup form; terminal creation pins the explicit form.
+    const personTail = tail && start.every((word, index) => tail[index] === word) ? [tail[0]!, ...tail.slice(start.length)] : tail;
+    const command = personTail ? argv(...prefix, ...personTail) : undefined;
+    let note = definitionOf(peer)?.transport === "claude-channel"
       ? "The existing Claude channel may reconnect while its native session remains open. Transcript availability is unknown; the recorded resume command is guidance, not proof that the transcript can be resumed."
-      : peer === "codex" ? "Recorded Codex thread; leave the old native client before resuming this conversation."
-        : "Recorded Pi conversation; preserve this session when starting Pi again.";
+      : definitionOf(peer)?.session.idField === "threadId" ? `Recorded ${definitionOf(peer)!.displayName} thread; leave the old native client before resuming this conversation.`
+        : `Recorded ${definitionOf(peer)!.displayName} conversation; preserve this session when starting ${definitionOf(peer)!.displayName} again.`;
     if (sessionFile && options.stopAndArchiveCommand && recordedFileState(sessionFile) === "missing") {
       note = `Recorded Pi session file is positively missing. Fresh-session is not supported for Pi. ${piArchiveExit(planned, options.stopAndArchiveCommand)}`;
     }

package/src/cli/setup.ts

@@ -1,80 +1,2 @@
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { realPath } from "../hub/project.ts";
-import { VERSION } from "../version.ts";
-
-export const PLUGIN = "agent-hub@agent-hub";
-const MARKETPLACE = "agent-hub";
-
-export interface InstalledPlugin {
-  id: string;
-  version?: string;
-  installPath?: string;
-}
-export interface Marketplace {
-  name: string;
-  path?: string;
-}
-
-/** `claude plugin list --json` / `claude plugin marketplace list --json`. Anything that does not parse is an empty list. */
-export function parseList<T>(json: string): T[] {
-  try {
-    const d = JSON.parse(json);
-    return Array.isArray(d) ? d : [];
-  } catch {
-    return [];
-  }
-}
-
-const real = (p: string) => {
-  try {
-    return realPath(p);
-  } catch {
-    return p;
-  }
-};
-const read = (p: string) => {
-  try {
-    return readFileSync(p, "utf8");
-  } catch {
-    return undefined;
-  }
-};
-
-export type PluginState = { state: "missing" } | { state: "current"; version: string } | { state: "stale"; version: string; why: string };
-
-/**
- * Is the installed Claude plugin the one this hub ships? The version is compared, and so is the bundle itself: Claude
- * Code runs a cached copy, and a copy taken from an earlier build of the same version speaks an older wire protocol.
- */
-export function pluginState(plugins: InstalledPlugin[], packageRoot: string): PluginState {
-  const mine = plugins.find((p) => p.id === PLUGIN);
-  if (!mine) return { state: "missing" };
-  const version = mine.version ?? "unknown";
-  if (version !== VERSION) return { state: "stale", version, why: `version ${version}, this hub is ${VERSION}` };
-  const shipped = read(join(packageRoot, "plugins", "agent-hub", "server.js"));
-  const cached = mine.installPath ? read(join(mine.installPath, "server.js")) : undefined;
-  if (shipped !== undefined && cached !== undefined && shipped !== cached) return { state: "stale", version, why: "same version, but the cached bundle differs from the one this hub ships" };
-  return { state: "current", version };
-}
-
-export interface SetupStep {
-  why: string;
-  argv: string[];
-}
-
-/**
- * The next thing `ahub setup` has to do, or nothing. One step at a time: the state is read again after every step,
- * because what a step leaves behind is Claude Code's business (removing a marketplace may uninstall its plugins).
- */
-export function nextStep(plugins: InstalledPlugin[], marketplaces: Marketplace[], packageRoot: string): SetupStep | undefined {
-  const root = real(packageRoot);
-  const market = marketplaces.find((m) => m.name === MARKETPLACE);
-  if (market && real(market.path ?? "") !== root) return { why: `the ${MARKETPLACE} marketplace points at ${market.path ?? "another source"}, not at this package`, argv: ["claude", "plugin", "marketplace", "remove", MARKETPLACE] };
-  if (!market) return { why: "register this package as a Claude Code plugin marketplace", argv: ["claude", "plugin", "marketplace", "add", root] };
-  const state = pluginState(plugins, root);
-  if (state.state === "missing") return { why: "install the channel plugin", argv: ["claude", "plugin", "install", PLUGIN] };
-  // Uninstall rather than update: with an unchanged version number an update has nothing to do.
-  if (state.state === "stale") return { why: `replace the installed plugin (${state.why})`, argv: ["claude", "plugin", "uninstall", PLUGIN] };
-  return undefined;
-}
+/** Compatibility exports; native plugin policy belongs to its adapter definition leaf. */
+export { PLUGIN, parseList, pluginState, nextStep, type InstalledPlugin, type Marketplace, type PluginState, type SetupStep } from "../adapters/definitions/native-cli-claude-setup.ts";

package/src/cli/shell-quote.ts

@@ -0,0 +1,3 @@
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/src/cli/terminal-recovery.ts

@@ -1,3 +1,6 @@
+import { shellQuote } from "./shell-quote.ts";
+export { shellQuote } from "./shell-quote.ts";
+import { definitionOf } from "../adapters/registry.ts";
 import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
@@ -231,9 +234,7 @@ export class OrcaCommandError extends Error {
 }
 
 /** POSIX quoting for the single command-string argument accepted by Orca. */
-export function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
+
 
 function normalizeOptions(options?: CommandRunner | TerminalRecoveryOptions): Required<TerminalRecoveryOptions> {
   const config: TerminalRecoveryOptions = typeof options === "function" ? { runner: options } : options ?? {};
@@ -474,7 +475,7 @@ function identityFrom(terminal: Record<string, unknown>): TerminalPeer | undefin
   const session = object(terminal.session);
   const candidates = [terminal.agentIdentity, terminal.agent, wait.agentIdentity, wait.agent, session.agentIdentity, session.agent];
   for (const candidate of candidates) {
-    if (candidate === "codex" || candidate === "claude" || candidate === "pi") return candidate;
+    if (typeof candidate === "string" && definitionOf(candidate)?.session.launchRecord) return candidate as TerminalPeer;
   }
   return undefined;
 }
@@ -504,13 +505,17 @@ function requireAbsoluteEntrypoint(value: string): string {
 
 function launchFor(peer: TerminalPeer, projectRoot: string, sessionId: string, options: Required<TerminalRecoveryOptions>, source: Record<string, unknown>, recorded?: RecordedTerminalLaunch, ref?: SessionRef): LaunchMetadata {
   const packageEntrypoint = requireAbsoluteEntrypoint(options.packageEntrypoint);
-  const argv = peer === "codex"
-    ? ["bun", packageEntrypoint, "--project", projectRoot, "codex", "resume", sessionId]
-    : peer === "claude"
-      ? ["bun", packageEntrypoint, "--project", projectRoot, "claude", "--resume", sessionId]
-      : ["bun", packageEntrypoint, "--project", projectRoot, "pi", "--mode", "tui", ...(ref?.backend ? ["--backend", ref.backend] : []), ...(ref?.model ? ["--model", ref.model] : []), ...(ref?.sessionFile ? ["--session-file", ref.sessionFile] : ["--session-id", sessionId])];
   const env = { ...allowedEnv(source), ...(recorded?.env ?? {}) };
   const prefix = ALLOWED_ENV.filter((name) => env[name] !== undefined).map((name) => `${name}=${shellQuote(env[name]!)}`);
+  const launch: LaunchMetadata = { packageEntrypoint, argv: ["bun", packageEntrypoint, "--project", projectRoot], env, command: "" };
+  launch.command = [...prefix, ...launch.argv.map(shellQuote)].join(" ");
+  // Identity and environment were independently verified before this pure two-phase launch construction.
+  const binding: TerminalBinding = { peer, projectRoot, sessionId, handle: nestedString(source, ["handle"])!,
+    incarnationId: nestedString(source, ["incarnationId"])!, worktreeId: nestedString(source, ["worktreeId"])!,
+    ...(ref?.sessionFile ? { sessionFile: ref.sessionFile } : {}), ...(ref?.backend ? { backend: ref.backend } : {}), ...(ref?.model ? { model: ref.model } : {}), launch, launchMetadata: launch };
+  const tail = definitionOf(peer)?.session.resumeArgv?.(binding, false);
+  if (!tail) throw new Error(`${peer}: no recorded terminal resume adapter`);
+  const argv = [...launch.argv, ...tail];
   const command = [...prefix, ...argv.map(shellQuote)].join(" ");
   return { packageEntrypoint, command, argv, env };
 }
@@ -669,7 +674,9 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
       continue;
     }
     const recorded = records.find((item) => item.peer === peer && item.handle === handle && item.worktreeId === terminal.worktreeId && item.incarnationId === terminal.incarnationId);
-    const sessionFile = peer === "pi" ? nestedString(terminal, ["sessionFile", "sessionPath"]) ?? nestedString(object(terminal.session), ["file", "path"]) : undefined;
+    // Orca observation supplies file identity; launch arguments are not observed native session-file evidence.
+    const { args: _launchArgs, ...observedTerminal } = terminal;
+    const sessionFile = definitionOf(peer)?.session.crashIdentity?.(observedTerminal).sessionFile;
     const launch = launchFor(peer, projectRoot, sessionId, config, terminal, recorded, { ...ref, ...(sessionFile ? { sessionFile } : {}) });
     const binding: TerminalBinding = { peer, handle, incarnationId, worktreeId, projectRoot, sessionId, ...(sessionFile ? { sessionFile } : {}), ...(ref.backend ? { backend: ref.backend } : {}), ...(ref.model ? { model: ref.model } : {}), launch, launchMetadata: launch };
     bindings.push(binding);

package/src/cli/upgrade-interactive.ts

@@ -1,3 +1,4 @@
+import { definitionOf } from "../adapters/registry.ts";
 import { renderPlan, renderOperation, renderBlocked, renderSummary, renderStep, renderWait, renderMenu, choiceInstruction, type RecoveryPresentationOptions, type MenuPresentationItem } from "./upgrade-presentation.ts";
 import { quoted, wrap } from "./console-state.ts";
 import { operationLines, stepLabel } from "./upgrade-labels.ts";
@@ -83,7 +84,8 @@ const left = (op: { id: string; sourceRoot?: string }, io: ScreenIO): string =>
 export function peerKind(planned: PlannedProject, peer: RecoveryPeer): "tui" | "headless" | "unmanaged" | "offline" {
   if (peer.state === "offline") return "offline";
   if ((planned.terminals as { peer: string }[]).some((t) => t.peer === peer.id)) return "tui";
-  if (peer.id === "claude" || peer.id === "codex" || (peer.id === "pi" && peer.args?.mode === "tui")) return "unmanaged";
+  const unrecorded = definitionOf(peer.id)?.session.unrecordedTerminal;
+  if (unrecorded === "always" || unrecorded === "tui" && peer.args?.mode === "tui") return "unmanaged";
   return "headless";
 }
 
@@ -93,7 +95,7 @@ function peerAction(planned: PlannedProject, peer: RecoveryPeer): string {
   if (planned.freshStart?.includes(peer.id)) return "restarts as a new session (no turn to lose)";
   const terminal = (planned.terminals as { peer: string; handle: string }[]).find((t) => t.peer === peer.id);
   if (terminal) return `resumes its session in a new terminal (replaces ${terminal.handle})`;
-  return peer.id === "pi" ? "restarts headless on its recorded session" : "restarts headless as a new session";
+  return definitionOf(peer.id)?.session.restoreOnStart ? "restarts headless on its recorded session" : "restarts headless as a new session";
 }
 
 const KINDS = { tui: "TUI", headless: "headless", unmanaged: "own", offline: "-" } as const;

package/src/cli/upgrade-restore-state.ts

@@ -1,3 +1,4 @@
+import { definitionOf } from "../adapters/registry.ts";
 import type { TerminalBinding } from "./terminal-recovery.ts";
 
 export type RestoreReceipt =
@@ -23,7 +24,7 @@ function malformed(): never { throw new Error("invalid restore receipt"); }
 const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
 const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
 function terminalBinding(value: unknown): TerminalBinding {
-  if (!object(value) || typeof value.peer !== "string" || !["codex", "claude", "pi"].includes(value.peer)) malformed();
+  if (!object(value) || typeof value.peer !== "string" || !definitionOf(value.peer)?.session.launchRecord) malformed();
   for (const key of ["handle", "incarnationId", "worktreeId", "projectRoot", "sessionId"]) if (!text(value[key])) malformed();
   for (const key of ["sessionFile", "backend", "model"]) if (value[key] !== undefined && typeof value[key] !== "string") malformed();
   const launch = value.launch;