@staix/agent-hub 0.12.34 → 0.12.36

package/src/cli/main.ts

@@ -1,4 +1,8 @@
 #!/usr/bin/env bun
+import { effectiveInstanceRoles } from "../hub/instances.ts";
+import { resolveInstanceExecutionCwd } from "../hub/instance-execution.ts";
+import { readInstanceConfig } from "../hub/instance-config.ts";
+import type { NativeCliEntryContext } from "../adapters/definitions/native-cli-entry-types.ts";
 import { BUILTIN_CLI_ENTRIES, definitionOf, DOCTOR_TOOL_PROBES, DOCTOR_MEMORY_CAPTURE_PEERS, DOCTOR_PLUGIN_PROBE, nativeDoctorCheck, nativeDoctorRecoveryIdentity, nativeDoctorOptionalProbes } from "../adapters/registry.ts";
 import { parsePiFlags } from "../adapters/definitions/native-cli-pi.ts";
 import { supportsBoardReleaseFilter, supportsBoardColumnMetadata } from "./board-read.ts";
@@ -27,7 +31,7 @@ import { basename, dirname, join, relative, resolve } from "node:path";
 import { ControlClient, readControl } from "../hub/control-client.ts";
 import { loadConfig } from "../hub/daemon.ts";
 import { factsHook } from "./facts-hook.ts";
-import { hubHome, projectContext, realPath } from "../hub/project.ts";
+import { hubHome, projectContext, projectRoot, realPath } from "../hub/project.ts";
 import { Registry, type Project } from "../hub/registry.ts";
 import { inspectProject, startProject, stopProject, runProjectDaemon } from "../hub/lifecycle.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
@@ -36,7 +40,7 @@ import { OmniRoute } from "../omniroute/client.ts";
 import { MemoryClient } from "../memory/client.ts";
 import { init, planInit } from "./init.ts";
 import { launcherPreview } from "./preview.ts";
-import { cleanupStaleClaudeSettings, cleanupClaudeSettings, buildLaunch, buildKimiTuiLaunch, claudeObservationHooks, nativeLaunchEnv, recordClaudeLaunch, runClaudeLaunch, type ClaudeLaunchRecord, UNATTENDED_WARNING } from "./launch.ts";
+import { instanceLaunchArguments, requirePeerInstances, requireActiveInstance, cleanupStaleClaudeSettings, cleanupClaudeSettings, buildLaunch, buildKimiTuiLaunch, claudeObservationHooks, nativeLaunchEnv, recordClaudeLaunch, runClaudeLaunch, type ClaudeLaunchRecord, UNATTENDED_WARNING } from "./launch.ts";
 import { configureKimiMcp } from "./kimi-mcp.ts";
 import { nextStep, parseList, pluginState, type InstalledPlugin, type Marketplace } from "./setup.ts";
 import { CLASSES } from "../hub/board.ts";
@@ -101,11 +105,6 @@ while (argv[0] === "--project" || argv[0] === "--live-test") {
   }
 }
 const [given = "help", ...rest] = argv;
-// `ahub <command> -h` alone asks for that command's help instead of running it. Elsewhere `-h` may be message text
-// (`ahub say try ls -h`), and claude and codex pass their arguments on to the agent.
-const asksHelp = (a: string | undefined) => a === "--help" || a === "-h";
-const cmd = asksHelp(given) || (definitionOf(given)?.start.passthrough !== true && rest.length === 1 && asksHelp(rest[0])) ? "help" : given;
-const args = cmd === "help" && given !== "help" && !asksHelp(given) ? [given] : rest;
 let selected: { root: string; stateDir: string };
 try {
   if (selector) {
@@ -116,9 +115,42 @@ try {
       const registered = known ?? projects.find((p) => p.root === context.root);
       selected = registered ?? context;
     }
-  } else selected = projectContext(process.cwd());
-} catch (error) { fail((error as Error).message); }
+  } else {
+    const markedPeer = process.env.AGENTHUB_PEER_ID, markedRoot = process.env.AGENTHUB_PROJECT_DIR;
+    const declarations = markedPeer && markedRoot && !definitionOf(markedPeer) ? readInstanceConfig(realPath(markedRoot)).instances : undefined;
+    if (markedPeer && markedRoot && declarations && Object.hasOwn(declarations, markedPeer)) {
+      const canonicalRoot = realPath(markedRoot), config = loadConfig(canonicalRoot);
+      const executionCwd = resolveInstanceExecutionCwd(canonicalRoot, markedPeer, declarations, effectiveInstanceRoles(markedPeer, declarations, config.roles));
+      if (realPath(projectRoot(process.cwd())) !== realPath(executionCwd)) fail("native instance workspace does not match its declared checkout");
+      selected = projectContext(canonicalRoot);
+    } else selected = projectContext(process.cwd());
+  }
+} catch (error) { fail(startupDiagnostic(error)); }
 const cwd = selected.root;
+const unboundCaller = detectCliIdentity(process.env);
+const markerNeedsDeclaration = unboundCaller.role === "invalid" && unboundCaller.reason === "AGENTHUB_PEER_ID conflicts with native agent marker"
+  && process.env.AGENTHUB_PEER_ID !== undefined && !definitionOf(process.env.AGENTHUB_PEER_ID);
+const needsInstances = definitionOf(given) && rest.some(arg => arg === "--as" || arg.startsWith("--as=")) || markerNeedsDeclaration;
+let declaredInstances: ReturnType<typeof readInstanceConfig>["instances"];
+let nativeSelection: ReturnType<typeof instanceLaunchArguments>;
+try {
+  declaredInstances = needsInstances ? readInstanceConfig(cwd).instances : undefined;
+  nativeSelection = instanceLaunchArguments(given, rest, declaredInstances);
+} catch (error) { fail(startupDiagnostic(error)); }
+const selectedInstance = nativeSelection.instance;
+// `ahub <command> -h` alone asks for that command's help instead of running it. Elsewhere `-h` may be message text
+// (`ahub say try ls -h`), and claude and codex pass their arguments on to the agent.
+const asksHelp = (a: string | undefined) => a === "--help" || a === "-h";
+const cmd = asksHelp(given) || (definitionOf(given)?.start.passthrough !== true && nativeSelection.args.length === 1 && asksHelp(nativeSelection.args[0])) ? "help" : given;
+const args = cmd === "help" && given !== "help" && !asksHelp(given) ? [given] : nativeSelection.args;
+
+/** Resolve a named peer only against this project's current trusted declarations. */
+const peerDefinition = (peer: unknown) => typeof peer === "string"
+  ? definitionOf(peer) ?? definitionOf(peer, readInstanceConfig(cwd).instances) : undefined;
+const requireNamedPeerFeature = (hub: ControlClient, peer: string | undefined) => {
+  if (peer !== undefined && !definitionOf(peer)) requirePeerInstances(hub.features);
+};
+
 /** The project config, saying on stderr which machine-local fields it had to ignore (issue #17). */
 const projectConfig = () => {
   const config = loadConfig(cwd);
@@ -126,7 +158,7 @@ const projectConfig = () => {
   return config;
 };
 const stateDir = selected.stateDir;
-const caller = detectCliIdentity(process.env);
+const caller = declaredInstances ? detectCliIdentity(process.env, declaredInstances) : unboundCaller;
 const commandLabel = cliCommandLabel(cmd, args);
 const commandAccess = classifyPeerCommand(cmd, args);
 // Agent-authored content keeps its peer. Operational starts/holds may borrow console authority for live verification.
@@ -216,18 +248,18 @@ async function healthy(): Promise<boolean> {
   finally { hub?.close(); }
 }
 
-function exec(bin: string, argv: string[], tool?: "claude" | "codex" | "kimi"): never {
-  const env = tool ? nativeLaunchEnv(tool, childEnv()) : childEnv();
-  const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
+function exec(bin: string, argv: string[], tool?: "claude" | "codex" | "kimi", executionCwd = cwd): never {
+  const env = tool ? nativeLaunchEnv(selectedInstance ?? tool, childEnv(), declaredInstances) : childEnv();
+  const res = spawnSync(bin, argv, { cwd: executionCwd, stdio: "inherit", env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
   if (res.error) fail(`cannot run ${bin}: ${res.error.message}`);
   process.exit(res.status ?? 1);
 }
 
-function execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv): never {
-  const env: NodeJS.ProcessEnv = { ...nativeLaunchEnv("pi", extra), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
+function execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv, executionCwd = cwd): never {
+  const env: NodeJS.ProcessEnv = { ...nativeLaunchEnv(selectedInstance ?? "pi", extra, declaredInstances), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
   delete env.AGENTHUB_RECOVERY_OPERATION;
   delete env.AGENTHUB_UNATTENDED;
-  const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env });
+  const res = spawnSync(bin, argv, { cwd: executionCwd, stdio: "inherit", env });
   if (res.error) fail(`cannot run ${bin}: ${res.error.message}`);
   process.exit(res.status ?? 1);
 }
@@ -324,6 +356,12 @@ async function orphanDoctor(kill: boolean, options: ReturnType<typeof outputOpti
   if (failed) fail(`${failed} orphaned hub process(es) could not be stopped`);
 }
 
+/** Startup refusals remain single-line and bounded even for malformed local declarations. */
+function startupDiagnostic(error: unknown): string {
+  const message = error instanceof Error ? error.message : "invalid startup configuration";
+  return message.replace(/[\p{Cc}\p{Cf}]/gu, " ").replace(/\s+/g, " ").trim().slice(0, 512) || "invalid startup configuration";
+}
+
 function fail(message: string): never {
   console.error(`ahub: ${message}`);
   process.exit(1);
@@ -552,7 +590,10 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
 
 /** Strict person command: recorded identity only, no session or terminal overrides. */
 function parseRecoveryReattach(argv: readonly string[]): { id: string; peer: TerminalPeer } | undefined {
-  if (argv.length !== 3 || argv[0] !== "reattach" || !operationIdPattern.test(argv[1]!) || definitionOf(argv[2]!)?.session.launchRecord !== true) return undefined;
+  if (argv.length !== 3 || argv[0] !== "reattach" || !operationIdPattern.test(argv[1]!) || !/^[a-z][a-z0-9-]{0,31}$/.test(argv[2]!)) return undefined;
+  const builtin = definitionOf(argv[2]!);
+  if (builtin && builtin.session.launchRecord !== true) return undefined;
+  // Extra peers are resolved against the operation's canonical project by the recovery core, never by suffix.
   return { id: argv[1]!, peer: argv[2] as TerminalPeer };
 }
 
@@ -805,13 +846,25 @@ const commands: Record<string, () => Promise<void> | void> = {
   ...Object.fromEntries(BUILTIN_CLI_ENTRIES.map(entry => [entry.command, async () => {
     // Preserve the original guard before native effects; previews remain read-only and precede this guard.
     if (entry.lifecycleAdmission && !args.includes("--print-command") && !args.includes("--dry-run")) assertLifecycleAvailable();
-    return entry.execute({ args, cwd, stateDir, cliDir: import.meta.dir, unattendedEnv, definition: entry.definition,
-      projectConfig, connect, fail, exec, execWithEnv, takeFlags,
-      helpers: { launcherPreview, readControl, recordTerminalLaunch, recoveryLock, processSignature,
+    const nativeConnect = async () => {
+      const hub = await connect();
+      try { if (selectedInstance) { requirePeerInstances(hub.features); requireActiveInstance((await hub.request({ t: "status" })).status, selectedInstance); } return hub; }
+      catch (error) { hub.close(); throw error; }
+    };
+    if (selectedInstance && !args.includes("--print-command") && !args.includes("--dry-run")) {
+      const hub = await nativeConnect(); hub.close();
+    }
+    const context: NativeCliEntryContext = { args, cwd, stateDir, cliDir: import.meta.dir, unattendedEnv, definition: entry.definition,
+      ...(selectedInstance ? { instance: selectedInstance } : {}), ...(nativeSelection.hubStarted ? { hubStarted: true as const } : {}),
+      projectConfig, connect: nativeConnect, fail,
+      exec: (bin, argv, tool) => exec(bin, argv, tool, context.executionCwd),
+      execWithEnv: (bin, argv, env) => execWithEnv(bin, argv, env, context.executionCwd), takeFlags,
+      helpers: { launcherPreview: (tool, raw, projectRoot, state, unattended) => launcherPreview(tool, raw, projectRoot, state, unattended, selectedInstance), readControl, recordTerminalLaunch, recoveryLock, processSignature,
         buildLaunch, claudeObservationHooks, recordClaudeLaunch, cleanupStaleClaudeSettings, cleanupClaudeSettings,
         nativeLaunchEnv, runClaudeLaunch, childEnv, qwenSessionId, configureJcodeMcp, configureKimiMcp,
         buildKimiTuiLaunch, startModeOf },
-    });
+    };
+    return entry.execute(context);
   }])),
 
   models: async () => {
@@ -897,7 +950,7 @@ const commands: Record<string, () => Promise<void> | void> = {
 
   watch: async () => {
     const peer = args[0];
-    if (typeof peer !== "string" || !definitionOf(peer)?.capabilities?.watch) fail("usage: ahub watch kimi|qwen [--no-thoughts] [--color=auto|always|never]");
+    if (typeof peer !== "string" || !peerDefinition(peer)?.capabilities?.watch) fail("usage: ahub watch kimi|qwen [--no-thoughts] [--color=auto|always|never]");
     if (args.slice(1).some(arg => arg !== "--no-thoughts" && !/^--color=(auto|always|never)$/.test(arg))) fail("unsupported watch option");
     const color = resolveColor(args.find(arg => arg.startsWith("--color="))?.slice(8), { isTTY: !!process.stdout.isTTY, ...process.env });
     if (color instanceof Error) fail(color.message);
@@ -979,6 +1032,10 @@ const commands: Record<string, () => Promise<void> | void> = {
   backlog: async () => {
     const [sub, id, revision, value, ...reason] = args;
     if (sub === "list" && args.length === 1) return console.log(await taskOp("hub_backlog_list", {}));
+    if (sub === "groom" && args.length === 1) return console.log(await taskOp("hub_planner_groom", {}));
+    if (["return", "return-untouched"].includes(sub ?? "") && /^[1-9]\d*$/.test(id ?? "") && /^\d+$/.test(revision ?? "") && args.length >= 4) {
+      return console.log(await taskOp("hub_backlog_return_untouched", { id: Number(id), revision: Number(revision), reason: args.slice(3).join(" ") }));
+    }
     if (sub === "add" && args.length >= 3) return console.log(await taskOp("hub_task_propose", { class: id, title: args.slice(2).join(" "), backlog: true }));
     if (!/^[1-9]\d*$/.test(id ?? "")) fail("usage: ahub backlog list|add <class> <title...>|pull|return <id>|plan|pin <id> <revision> <value> <reason...>|undo <id> <revision>");
     if (["pull", "return"].includes(sub ?? "") && args.length === 2) return console.log(await taskOp(sub === "pull" ? "backlog_pull" : "backlog_return", { id }));
@@ -1061,6 +1118,31 @@ const commands: Record<string, () => Promise<void> | void> = {
       finally { hub.close(); }
       return;
     }
+    if (sub === "costs") {
+      if (args.length > 2) fail("usage: ahub sdlc costs [owner/repository]");
+      return console.log(await taskOp("hub_sdlc_costs", { ...(args[1] ? { repo: args[1] } : {}) }));
+    }
+    if (sub === "plan-review") {
+      const revision = Number(args[2]);
+      if (!Number.isSafeInteger(id) || id! <= 0 || !Number.isSafeInteger(revision) || revision < 0 || args.length < 4) fail("usage: ahub sdlc plan-review <task> <revision> <reason...>");
+      const flags = takeFlags(args.slice(3), ["--review", "--reviewers", "--ci"], []);
+      const scope = flags.one["--review"], reviewers = flags.one["--reviewers"];
+      if (!flags.rest.length || (scope === undefined) !== (reviewers === undefined)) fail("plan-review needs a reason and both --review and --reviewers when supplying review scope");
+      return console.log(await taskOp("hub_plan_review", { id, revision, reason: flags.rest.join(" "), ...(scope !== undefined ? { review: { scope, reviewers: Number(reviewers) } } : {}), ...(flags.one["--ci"] !== undefined ? { ci: flags.one["--ci"] } : {}) }));
+    }
+    if (sub === "accept") {
+      // #481 S1: the person accepts the task's spec issue at its current body; agent shells are refused before this runs.
+      const flags = takeFlags(args.slice(2), ["--issue", "--repo"], []);
+      const issue = Number(flags.one["--issue"]), repo = flags.one["--repo"];
+      if (flags.rest.length || !Number.isSafeInteger(id) || id! <= 0 || !Number.isSafeInteger(issue) || issue <= 0) fail("usage: ahub sdlc accept <task> --issue <n> [--repo owner/repository]");
+      const hub = await connect();
+      try {
+        const reply = await hub.request({ t: "sdlc", op: "accept", id, issue, ...(repo ? { repo } : {}) }, 30_000);
+        if (!reply.ok) fail(reply.error);
+        console.log(`task #${id}: spec issue #${issue} accepted at body edit ${reply.acceptance?.lastEditedAt ?? "never"}`);
+      } finally { hub.close(); }
+      return;
+    }
     if (sub === "record") {
       if (args.length !== 3 || !Number.isSafeInteger(id) || id! <= 0 || Buffer.byteLength(args[2]!) > 32768) fail("usage: ahub sdlc record <task> '<receipt JSON>'");
       let receipt: unknown; try { receipt = JSON.parse(args[2]!); } catch { fail("receipt must be valid JSON"); }
@@ -1128,9 +1210,14 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   review: async () => {
+    // #520: the review brief a reviewer gets, for a person or an outside tool.
+    if (args[0] === "brief") {
+      if (args.length !== 2 || !/^\d+$/.test(args[1]!)) fail("usage: ahub review brief <task id>");
+      return console.log(await taskOp("review_brief", { id: Number(args[1]) }));
+    }
     const { one, many, rest } = takeFlags(args, ["--head"], ["--unmet"]);
     const [id, verdict, ...note] = rest;
-    if (!id || !verdict) fail("usage: ahub review <id> approved|changes_requested [note...] [--unmet <item>]...");
+    if (!id || !verdict) fail("usage: ahub review <id> approved|changes_requested [note...] [--unmet <item>]... | ahub review brief <id>");
     console.log(await taskOp("hub_review", { id: Number(id), verdict, ...(one["--head"] ? { head: one["--head"] } : {}), note: note.join(" "), ...(many["--unmet"]?.length ? { unmet: many["--unmet"] } : {}) }));
   },
 
@@ -1202,9 +1289,10 @@ const commands: Record<string, () => Promise<void> | void> = {
   roster: async () => {
     const options = outputOptions(), flags = args.filter(arg => arg.startsWith("--")), positional = outputArguments().filter(arg => arg !== "--yes" && arg !== "--now");
     const [sub = "list", peer, ...extra] = positional;
-    if (!["list", "add", "remove"].includes(sub) || extra.length || (sub === "list" ? peer !== undefined : !definitionOf(peer ?? "")) || flags.some(flag => !["--json", "--full", "--yes", "--now"].includes(flag) && !flag.startsWith("--color=")) || (sub !== "list" && options.json) || (sub !== "remove" && flags.some(flag => ["--yes", "--now"].includes(flag)))) fail("usage: ahub roster [--json] | add <peer> | remove <peer> [--yes] [--now]");
+    if (!["list", "add", "remove"].includes(sub) || extra.length || (sub === "list" ? peer !== undefined : !peerDefinition(peer)) || flags.some(flag => !["--json", "--full", "--yes", "--now"].includes(flag) && !flag.startsWith("--color=")) || (sub !== "list" && options.json) || (sub !== "remove" && flags.some(flag => ["--yes", "--now"].includes(flag)))) fail("usage: ahub roster [--json] | add <peer> | remove <peer> [--yes] [--now]");
     const hub = await connect();
     try {
+      requireNamedPeerFeature(hub, peer);
       const request = async (message: Record<string, unknown>) => { const reply = await hub.request(message, 35_000); if (reply.ok !== true) fail(String(reply.error ?? "roster request refused")); return reply; };
       if (sub === "list") {
         const view = await request({ t: "settings_get" });
@@ -1565,7 +1653,22 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (!turn.ended) fail(`turn ${id} is still running`);
     const { start_tree: startTree, end_tree: endTree } = turn;
     if (!startTree || !endTree) fail(`turn ${id} has no ${startTree ? "end" : "start"} snapshot: the hub stopped during it, or a snapshot failed (see hub.log)`);
-    const repo = repoOf(cwd) ?? fail(`${cwd} is not in a git work tree`);
+    const recordedWorkspace = turnRecords(t => t.workspace(id), undefined);
+    const undoWorkspace = (): string => {
+      // Old turns, including external peers and ids declared only later, belong to the canonical checkout.
+      if (recordedWorkspace === undefined) return cwd;
+      const declarations = readInstanceConfig(cwd).instances;
+      if (!declarations || !Object.hasOwn(declarations, turn.peer)) fail(`turn ${id}'s recorded instance is no longer declared; nothing was restored`);
+      const config = projectConfig();
+      const current = resolveInstanceExecutionCwd(cwd, turn.peer, declarations, effectiveInstanceRoles(turn.peer, declarations, config.roles));
+      if (realPath(current) !== realPath(recordedWorkspace)) fail(`turn ${id}'s recorded execution workspace changed; nothing was restored`);
+      return current;
+    };
+    const undoCwd = undoWorkspace();
+    const requireUndoWorkspace = () => {
+      if (realPath(undoWorkspace()) !== realPath(undoCwd)) fail(`turn ${id}'s execution workspace changed; nothing was restored`);
+    };
+    const repo = repoOf(undoCwd) ?? fail(`${undoCwd} is not in a git work tree`);
     if (!hasTree(repo, startTree) || !hasTree(repo, endTree)) fail(`turn ${id}'s snapshots are gone from the git object store (git gc prunes them after two weeks)`);
     // Another peer's turn that overlapped this one in time has its changes in this turn's diff as well.
     const undoConfig = projectConfig();
@@ -1587,11 +1690,12 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (first.undone) return console.log(`turn ${id} is already undone: its files are as they were before it started`);
     console.log(first.restore.length ? `turn ${id} changed:\n  ${first.restore.join("\n  ")}` : `turn ${id} changed no files`);
     console.log("(every change made in the project during the turn counts as its own, including any by Claude or by you)");
-    const projections = new TextProjections({ cwd, stateDir, config: undoConfig.text_projection ?? {}, deny: undoConfig.local.deny, readAllow: undoConfig.local.read_allow, log: line => console.error(line) });
-    const preview = projectedDiff({ repo, from: endTree, to: startTree, paths: first.restore, projections, deny: undoConfig.local.deny, privatePath: path => matchesPolicy(cwd, join(repo.top, path), undoConfig.pii?.paths ?? []) });
+    const projections = new TextProjections({ cwd: undoCwd, stateDir, config: undoConfig.text_projection ?? {}, deny: undoConfig.local.deny, readAllow: undoConfig.local.read_allow, log: line => console.error(line) });
+    const preview = projectedDiff({ repo, from: endTree, to: startTree, paths: first.restore, projections, deny: undoConfig.local.deny, privatePath: path => matchesPolicy(undoCwd, join(repo.top, path), undoConfig.pii?.paths ?? []) });
     if (preview) console.log(terminalText("Undo preview (end snapshot to start snapshot):\n" + preview));
 
     if (!args.includes("--yes")) return console.log("nothing was changed; add --yes to restore these files");
+    requireUndoWorkspace();
     if (args.includes("--context")) {
       console.log(await taskOp("turn_revert", { turn: id }));
       reverted = true;
@@ -1599,6 +1703,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     // A peer may have written meanwhile (the revert alone can take seconds): plan again right before restoring.
     const second = plan();
     if (second.restore.join("\0") !== first.restore.join("\0")) fail(`the project changed while undoing; nothing was restored, run ahub undo again${reverted ? " without --context (Codex's conversation was already reverted)" : ""}`);
+    requireUndoWorkspace();
     restore(repo, startTree, second.restore);
     if (second.restore.length) console.log(`restored to their state before ${id}`);
   },
@@ -1706,9 +1811,10 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     if (["assign", "clear"].includes(args[0] ?? "")) {
       const [op, peer, id] = args;
-      if (!peer || !definitionOf(peer ?? "") || !id && op === "assign" || args.length > 3) fail("usage: ahub role assign <peer> <id> | clear <peer> [<id>]");
+      if (!peer || !peerDefinition(peer) || !id && op === "assign" || args.length > 3) fail("usage: ahub role assign <peer> <id> | clear <peer> [<id>]");
       const hub = await connect();
       try {
+        requireNamedPeerFeature(hub, peer);
         const view = await hub.request({ t: "settings_get" }); if (!view.ok) fail(view.error);
         const row = (view.rows as SettingRow[]).find(row => row.key === `catalog_roles.${peer}`); if (!row) fail("this hub does not support catalog role settings");
         const current = Array.isArray(row!.pending) ? row!.pending : Array.isArray(row!.value) ? row!.value : [];
@@ -1825,8 +1931,9 @@ async function runConductorCommand(): Promise<void> {
     if (parsed instanceof Error) fail(parsed.message);
     op = "hub_peer_start";
     // #269: a mode may only repeat the peer's start mode, which a person sets; without one the hub takes that mode.
-    input = { peer: cmd, ...parsed };
+    input = { peer: selectedInstance ?? cmd, ...parsed };
   }
+  if (selectedInstance) { const hub = await connect(); try { requirePeerInstances(hub.features); } finally { hub.close(); } }
   console.log(await taskOp(op, input));
 }
 const run = identity.role === "tools" && commandAccess === "conductor" ? runConductorCommand : (Object.hasOwn(commands, cmd) ? commands[cmd] : undefined) ?? (() => fail(`unknown command "${cmd}"; run ahub help`));

package/src/cli/preview.ts

@@ -2,7 +2,7 @@ import { definitionOf, builtinPreviewOf } from "../adapters/registry.ts";
 import { loadConfig } from "../hub/daemon.ts";
 import { childEnv } from "../hub/child-process.ts";
 import { startModeOf } from "../hub/start-mode.ts";
-import { buildLaunch, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, claudeObservationHooks } 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";
@@ -10,14 +10,25 @@ import { relayModelIds } from "../models/relay.ts";
 import { buildPiLaunch } from "../pi/launch.ts";
 
 /** 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));
+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 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");
-  return preview({ tool, args, cwd, stateDir, cliDir: import.meta.dir, unattended, config, definition,
+  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");
+  }
+  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, claudeObservationHooks, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, childEnv,
+    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,11 +1,12 @@
-import { ADAPTERS, definitionOf } from "../adapters/registry.ts";
+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;
@@ -26,30 +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 = (): 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);
+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 = source?.[definitionOf(peer)?.session.idField ?? "sessionId"];
-  const sessionFile = definitionOf(peer)?.session.crashIdentity ? 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");
@@ -73,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;
@@ -81,25 +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 = definitionOf(peer)?.session.crashIdentity && 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 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"
+    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."
-      : 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.`;
+      : 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/reset.ts

@@ -10,6 +10,8 @@ import { HUB_DB_BUSY_TIMEOUT_MS } from "../hub/db-timeout.ts";
 
 /** Agent session resume pointers. `pi-sessions/` holds Pi transcripts, history rather than pointers, and stays. */
 export const SESSION_POINTERS = ["sessions.json", "claude-session.json", "claude-context.json"];
+/** The fixed pointers plus each Claude instance's own session and context files (#450 I3). */
+const sessionPointers = (stateDir: string): string[] => [...SESSION_POINTERS, ...(existsSync(stateDir) ? readdirSync(stateDir).filter(name => /^claude-(session|context)\.[a-z][a-z0-9-]{0,31}\.json$/.test(name)) : [])];
 /** What a running daemon publishes; a daemon that did not stop cleanly (crash, SIGKILL, forced exit) leaves it. */
 export const MANIFEST = ["status.json", "control-token", "hub.pid"];
 
@@ -51,7 +53,7 @@ const shaped = (ok: boolean, what: string) => { if (!ok) throw new Error(`invali
 /** What a reset would act on, read from the state directory without changing it (hub.db opened read-only). */
 export function planReset(stateDir: string, projectId: string): ResetPlan {
   const plan: ResetPlan = { queued: [], needsReview: [], inFlight: [], manualHolds: [], budgetPauses: [], conductorHolds: [],
-    sessionPointers: SESSION_POINTERS.filter((name) => existsSync(join(stateDir, name))), entries: existsSync(stateDir) ? readdirSync(stateDir).length : 0 };
+    sessionPointers: sessionPointers(stateDir).filter((name) => existsSync(join(stateDir, name))), entries: existsSync(stateDir) ? readdirSync(stateDir).length : 0 };
   const file = join(stateDir, "hub.db");
   if (!existsSync(file)) return plan;
   // A read-only open of a WAL database creates hub.db-wal and -shm when the last writer's close removed them (Linux),
@@ -143,7 +145,7 @@ export function resetRuntime(stateDir: string, project: Project): { settled: str
       })();
     } finally { db.close(); }
   }
-  for (const name of SESSION_POINTERS) rmSync(join(stateDir, name), { force: true });
+  for (const name of sessionPointers(stateDir)) rmSync(join(stateDir, name), { force: true });
   // The caller has checked that no daemon behind these is alive or uncertain: they are a crashed run's leftovers.
   const stale = MANIFEST.filter((name) => existsSync(join(stateDir, name)));
   for (const name of stale) rmSync(join(stateDir, name), { force: true });

package/src/cli/statusline-tee.ts

@@ -6,6 +6,7 @@
 import { spawnSync } from "node:child_process";
 import { chmodSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { claudePeer, claudeStateFile } from "../hub/claude-state.ts";
 
 const input = await Bun.stdin.text();
 let own = "";
@@ -15,6 +16,8 @@ try {
   const pct = (w: any) => (typeof w?.used_percentage === "number" ? `${Math.round(w.used_percentage)}%` : "-");
   if (limits) own = `agent-hub  5h ${pct(limits.five_hour)}  wk ${pct(limits.seven_day)}`;
   const dir = process.env.AGENTHUB_STATE_DIR;
+  // Usage is per account and shared; context and session belong to this peer (#450 I3: a claude-<name> instance).
+  const peer = claudePeer(process.env.AGENTHUB_PEER_ID);
   if (limits && dir) {
     mkdirSync(dir, { recursive: true });
     const file = join(dir, "claude-usage.json");
@@ -25,7 +28,7 @@ try {
   if (sessionId && dir) {
     // Bind context to the launcher, daemon and native session. Persist no prompts or transcript text.
     mkdirSync(dir, { recursive: true });
-    const file = join(dir, "claude-context.json");
+    const file = join(dir, claudeStateFile("claude-context", peer));
     const c = parsed.context_window;
     const current = c?.current_usage;
     const numeric = (v: unknown) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
@@ -38,7 +41,7 @@ try {
   }
   if (sessionId && dir) {
     mkdirSync(dir, { recursive: true });
-    const file = join(dir, "claude-session.json");
+    const file = join(dir, claudeStateFile("claude-session", peer));
     // The transcript path lets the hub tell a zero-turn session (file not yet created, so
     // `claude --resume` can never work) from one whose conversation must be preserved (#64).
     const transcriptPath = typeof parsed.transcript_path === "string" && parsed.transcript_path ? parsed.transcript_path : undefined;