@staix/agent-hub 0.12.33 → 0.12.35

package/src/cli/output.ts

@@ -1,3 +1,4 @@
+import { definitionOf } from "../adapters/registry.ts";
 import { boardColumns, type BoardPeerInput } from "../ui/task-board.ts";
 import { peerStyle } from "../ui/peer-palette.ts";
 import { cells, TABLES, table, fitLine, wrap, duration, relative, plural, terminalText, initialConsoleState, stateTone, type Span, type Tone } from "./console-state.ts";
@@ -234,8 +235,8 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
         : flat(p.paused).replace(/^(budget: .*), resets .+$/, "$1; reset unknown");
       out.push(...detail("paused", pauseText, columns, "attention"));
     }
-    if (p.toolsOnly) out.push(...detail(id === "kimi" && p.pullOnly ? "pull-only" : "tools-only", flat(p.toolsOnly).replace(/^(?:tools-only|pull-only):\s*/, ""), columns, "attention"));
-    if (p.pullOnly && id === "kimi") out.push(...detail("kimi last read", typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never", columns, "muted"));
+    if (p.toolsOnly) out.push(...detail(definitionOf(id)?.attach?.pullOnlyForms?.includes("tui") && p.pullOnly ? "pull-only" : "tools-only", flat(p.toolsOnly).replace(/^(?:tools-only|pull-only):\s*/, ""), columns, "attention"));
+    if (p.pullOnly && definitionOf(id)?.attach?.pullOnlyForms?.includes("tui")) out.push(...detail(`${id} last read`, typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never", columns, "muted"));
     if (p.permissionNote) out.push(...detail("permission", p.permissionNote, columns, "muted"));
     if (p.requestedModel && p.servedBy && p.requestedModel !== p.servedBy) out.push(...detail("requested model", p.requestedModel, columns));
     if (typeof p.oldestQueuedAt === "number") out.push(...detail(`${id} oldest queued`, relative(p.oldestQueuedAt, now), columns, "muted"));

package/src/cli/preview.ts

@@ -1,134 +1,34 @@
-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 { instanceLaunchArguments, 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. */
-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));
+/** 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, requestedInstance?: string) {
   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" });
+  const selected = instanceLaunchArguments(tool, requestedInstance ? ["--as", requestedInstance, ...raw] : raw, config.instances);
+  const args = selected.args.filter(arg => !["--print-command", "--dry-run", "--json"].includes(arg));
+  const definition = definitionOf(tool), preview = builtinPreviewOf(tool);
+  if (!definition || !preview) throw new Error("native preview definition unavailable");
+  if (selected.instance && definition.start.explicitHeadlessMode) {
+    const mode = args.indexOf("--mode");
+    if (mode >= 0 && args[mode + 1] !== "headless") throw new Error("extra instances require headless mode");
+    if (mode < 0 && !args.includes("--headless")) args.push("--mode", "headless");
   }
-  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 result = 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: (native, argv, ctx) => buildLaunch(native, argv, { ...ctx, ...(selected.instance ? { instance: selected.instance } : {}) }), claudeObservationHooks, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, childEnv,
+      startModeOf, kimiMcpPlan, jcodeCommand, qwenSessionId, relayModelIds, buildPiLaunch },
+  });
+  if (!selected.instance) return result;
+  return { ...result, instance: selected.instance,
+    ...(result.mcp ? { mcp: { ...result.mcp, action: "session-scoped MCP identity; shared project file unchanged", changed: false } } : {}),
+    unresolved: [...result.unresolved, { field: "executionCwd", reason: "verified by the daemon at instance start; preview does not start or authorize a worktree" }],
+  };
 }

package/src/cli/recovery-guidance.ts

@@ -1,10 +1,12 @@
+import { ADAPTERS, definitionOf, type AdapterDefinition, type KindMap } from "../adapters/registry.ts";
+import { readInstanceConfig } from "../hub/instance-config.ts";
 import { recordedFileState } from "./recovery-session-file.ts";
 import { decodeRestoreReceipt } from "./upgrade-restore-state.ts";
 import { shellQuote } from "./terminal-recovery.ts";
 import type { TerminalBinding } from "./terminal-recovery.ts";
 import type { Inspection, PlannedProject, ProjectProgress, RecoveryOperation, RecoveryPeer } from "./upgrade.ts";
 
-export type RecoveryNativePeer = "codex" | "pi" | "claude";
+export type RecoveryNativePeer = string;
 export type RecordedSessionOverride = Pick<TerminalBinding, "sessionId" | "sessionFile">;
 export interface RecordedPeerGuidance {
   peer: RecoveryNativePeer;
@@ -25,28 +27,35 @@ 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 projectDefinition = (peer: string, root: string) => definitionOf(peer) ?? definitionOf(peer, readInstanceConfig(root).instances);
+const peers = (instances: KindMap | undefined): RecoveryNativePeer[] => [...ADAPTERS.map(adapter => adapter.kind), ...Object.keys(instances ?? {})]
+  .filter(peer => definitionOf(peer, instances)?.session.launchRecord)
+  .sort((a, b) => Number(definitionOf(a, instances)?.transport === "claude-channel") - Number(definitionOf(b, instances)?.transport === "claude-channel"));
 
-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;
+function sourceSession(adapter: AdapterDefinition, source: RecoveryPeer | undefined): { sessionId?: string; sessionFile?: string } {
+  const sessionId = source?.[adapter.session.idField];
+  const sessionFile = adapter.session.crashIdentity ? source?.sessionFile ?? source?.args?.sessionFile : undefined;
   return { ...(text(sessionId) ? { sessionId } : {}), ...(text(sessionFile) ? { sessionFile } : {}) };
 }
 
 /** Fixed person commands for the existing Pi archive exit; this helper performs no lifecycle action. */
-export function piArchiveExit(planned: PlannedProject, stopAndArchiveCommand: string): string {
-  return `Run ${stopAndArchiveCommand}; after stop-and-archive, run ${argv("ahub", "--project", planned.project.root, "pi")}. A proven missing archived bookmark is retired by the normal Pi start without a fresh fallback in that same call; repeat the normal start as its notice directs.`;
+export function piArchiveExit(planned: PlannedProject, stopAndArchiveCommand: string, peer?: RecoveryNativePeer): string {
+  const adapter = peer ? projectDefinition(peer, planned.project.root) : undefined;
+  if (peer && (!adapter?.session.launchRecord || adapter.session.personFresh !== false)) throw new Error("recorded archive-exit peer has no current trusted Pi recovery declaration");
+  const instance = peer && adapter && peer !== adapter.kind ? ["--as", peer] : [];
+  return `Run ${stopAndArchiveCommand}; after stop-and-archive, run ${argv("ahub", "--project", planned.project.root, "pi", ...instance)}. A proven missing archived bookmark is retired by the normal Pi start without a fresh fallback in that same call; repeat the normal start as its notice directs.`;
 }
 
 /** Accepted identity outlives an incarnation's repair fence. Malformed evidence never means absence. */
-export function resolveAcceptedBinding(planned: PlannedProject, progress: ProjectProgress, peer: RecoveryNativePeer): TerminalBinding | undefined {
+export function resolveAcceptedBinding(planned: PlannedProject, progress: ProjectProgress, peer: RecoveryNativePeer, options: { authority?: "current" | "historical" } = {}): TerminalBinding | undefined {
   if (progress.id !== planned.project.id) throw new Error("recorded binding project mismatch");
+  if (options.authority !== "historical" && !projectDefinition(peer, planned.project.root)?.session.launchRecord) throw new Error("recorded binding peer has no current trusted recovery declaration");
   const binding = (value: unknown): TerminalBinding => {
-    const receipt = decodeRestoreReceipt({ state: "done", binding: value });
+    const receipt = decodeRestoreReceipt({ state: "done", binding: value }, options);
     if (receipt?.state !== "done" || receipt.binding.peer !== peer || receipt.binding.projectRoot !== planned.project.root) throw new Error("recorded binding does not match its peer and project");
     return receipt.binding;
   };
-  const restored = decodeRestoreReceipt(progress.terminals[`restored:${peer}`]);
+  const restored = decodeRestoreReceipt(progress.terminals[`restored:${peer}`], options);
   if (restored?.state === "done" || restored?.state === "waiting") return binding(restored.binding);
   if (progress.reattachments !== undefined) {
     if (!progress.reattachments || typeof progress.reattachments !== "object" || Array.isArray(progress.reattachments)) throw new Error("invalid recorded reattachment markers");
@@ -70,7 +79,18 @@ 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 => {
+  let instances: KindMap | undefined;
+  try { instances = readInstanceConfig(planned.project.root).instances; }
+  catch {
+    // ponytail: failed-config guidance shows at most 64 recorded extra ids, the declaration ceiling;
+    // share an exported instance limit if that ceiling grows. These rows confer no launch authority.
+    const base = peers(undefined), recorded = [...planned.terminals.map(value => (value as { peer?: unknown })?.peer),
+      ...Object.keys(progress.reattachments ?? {}), ...Object.keys(progress.terminals).filter(key => key.startsWith("restored:")).map(key => key.slice("restored:".length))];
+    const extra = [...new Set(recorded.filter((peer): peer is string => typeof peer === "string" && /^[a-z][a-z0-9-]{0,31}$/.test(peer) && !base.includes(peer)))].slice(0, 64);
+    return [...base, ...extra].map(peer => ({ peer, note: `${peer}: recorded session identity unavailable; project instance configuration could not be read; inspect the retained recovery receipt before choosing a conversation` }));
+  }
+  return peers(instances).map(peer => {
+    const adapter = definitionOf(peer, instances)!;
     let session: { sessionId?: string; sessionFile?: string } | undefined;
     let unavailable = false;
     const override = options.recorded && Object.hasOwn(options.recorded, peer) ? options.recorded[peer] : undefined;
@@ -78,24 +98,25 @@ export function recordedPeerGuidance(planned: PlannedProject, progress: ProjectP
     else {
       try {
         session = resolveAcceptedBinding(planned, progress, peer)
-          ?? sourceSession(peer, planned.source.peers.find(row => row.id === peer));
+          ?? sourceSession(adapter, planned.source.peers.find(row => row.id === peer));
       } catch { unavailable = true; }
     }
     const sessionId = text(session?.sessionId) ? session.sessionId : undefined;
-    const sessionFile = peer === "pi" && text(session?.sessionFile) ? session.sessionFile : undefined;
+    const sessionFile = adapter.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 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 instanceTail = personTail && peer !== adapter.kind ? [personTail[0]!, "--as", peer, ...personTail.slice(1)] : personTail;
+    const command = instanceTail ? argv(...prefix, ...instanceTail) : undefined;
+    let note = adapter.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.";
+      : adapter.session.idField === "threadId" ? `Recorded ${adapter.displayName} thread; leave the old native client before resuming this conversation.`
+        : `Recorded ${adapter.displayName} conversation; preserve this session when starting ${adapter.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)}`;
+      note = `Recorded Pi session file is positively missing. Fresh-session is not supported for Pi. ${piArchiveExit(planned, options.stopAndArchiveCommand, peer)}`;
     }
     const reattachCommand = command ? options.reattachCommand?.(peer) : undefined;
     return { peer, ...(sessionId ? { sessionId } : {}), ...(sessionFile ? { sessionFile } : {}), ...(command ? { command } : {}), ...(reattachCommand ? { reattachCommand } : {}), note };

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, `'\\''`)}'`;
+}