@staix/agent-hub 0.12.42 → 0.12.44

package/src/cli/launch.ts

@@ -1,3 +1,4 @@
+import { claudePeer as defaultChannelPeer } from "../hub/claude-state.ts";
 // Launchers inject only the flags the hub owns and refuse user-supplied duplicates.
 import { claudeStateFile } from "../hub/claude-state.ts";
 import { mkdirSync, writeFileSync, renameSync, unlinkSync, lstatSync, readFileSync, openSync, closeSync, readSync, accessSync, constants, linkSync } from "node:fs";
@@ -159,7 +160,7 @@ async function withClaudeLaunchRecord(stateDir: string, action: () => void): Pro
 }
 
 function writeClaudeLaunchRecord(stateDir: string, record: Record<string, unknown>): void {
-  const file = join(stateDir, claudeStateFile("claude-launch", typeof record.peer === "string" ? record.peer : "claude")), temp = `${file}.${randomUUID()}.tmp`;
+  const file = join(stateDir, claudeStateFile("claude-launch", typeof record.peer === "string" ? record.peer : defaultChannelPeer(undefined))), temp = `${file}.${randomUUID()}.tmp`;
   try { writeFileSync(temp, JSON.stringify(record), { mode: 0o600 }); renameSync(temp, file); }
   finally { try { unlinkSync(temp); } catch { /* the rename normally consumed it */ } }
 }
@@ -202,7 +203,7 @@ export async function recordClaudeNative(stateDir: string, launch: ClaudeLaunchR
   const publication = await withClaudeLaunchRecord(stateDir, () => {
     let current: ClaudeLaunchRecord;
     try {
-      const file = join(stateDir, claudeStateFile("claude-launch", launch.peer ?? "claude")), stat = lstatSync(file);
+      const file = join(stateDir, claudeStateFile("claude-launch", launch.peer ?? defaultChannelPeer(undefined))), stat = lstatSync(file);
       if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || !process.getuid || stat.uid !== process.getuid()) return;
       current = JSON.parse(readFileSync(file, "utf8"));
     } catch { return; }
@@ -219,7 +220,7 @@ export async function recordClaudeNative(stateDir: string, launch: ClaudeLaunchR
       writeFileSync(temp, JSON.stringify({ ...launch, nativePid: pid, nativeSignature: signature, nativeIdentity: "direct-child" }), { mode: 0o600, flag: "wx" });
       renameSync(temp, file);
     } finally { try { unlinkSync(temp); } catch { /* atomic rename consumed our private temporary file */ } }
-    try { recorded = sameClaudeLaunch(JSON.parse(readFileSync(join(stateDir, claudeStateFile("claude-launch", launch.peer ?? "claude")), "utf8")), launch); } catch { /* replaced or unreadable managed record */ }
+    try { recorded = sameClaudeLaunch(JSON.parse(readFileSync(join(stateDir, claudeStateFile("claude-launch", launch.peer ?? defaultChannelPeer(undefined))), "utf8")), launch); } catch { /* replaced or unreadable managed record */ }
   });
   if (publication.warning) report?.(publication.warning);
   return publication.recorded && recorded;
@@ -333,7 +334,7 @@ export function buildLaunch(
 ): Launch {
   const adapter = definitionOf(tool);
   if (!adapter) throw new Error("native launch definition unavailable");
-  const { metadata: _metadata, ...launch } = adapter.start.launch({
+  const { metadata: _metadata, ...launch } = adapter.start.launch!({
     instance: ctx.instance ?? tool, form: "tui", projectRoot: process.cwd(), stateDir: ctx.facts?.stateDir ?? ctx.statusLine?.stateDir ?? "",
     entrypoint: resolve(import.meta.dir, "main.js"), userArgs, env: {}, ...ctx,
   });

package/src/cli/main.js

@@ -6,4 +6,8 @@ if (!version || !(Number(version[1]) > 1 || (Number(version[1]) === 1 && (Number
   process.exit(1);
 }
 
-await import("./main.ts");
+// Shell completion asks on every Tab: answer from the help entries without loading the CLI (#603).
+if (process.argv[2] === "__complete") {
+  const { completeWords } = await import("./completion.ts");
+  console.log(completeWords(process.argv.slice(process.argv[3] === "--" ? 4 : 3)).join("\n"));
+} else await import("./main.ts");

package/src/cli/main.ts

@@ -1,9 +1,11 @@
 #!/usr/bin/env bun
+import { claudePeer as defaultChannelPeer } from "../hub/claude-state.ts";
 import { effectiveInstanceRoles } from "../hub/instances.ts";
 import { resolveInstanceExecutionCwd } from "../hub/instance-execution.ts";
-import { readInstanceConfig } from "../hub/instance-config.ts";
+import { readInstanceRoleConfig, readInstanceConfig, type InstanceRoleConfig } from "../hub/instance-config.ts";
+import { parseConfiguredAcpArguments, runConfiguredAcpEntry, requireActiveConfiguredAcp } from "./configured-acp-entry.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 { BUILTIN_CLI_ENTRIES, createProjectAdapterCatalog, 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";
 import { matchesPolicy } from "../hub/path-policy.ts";
@@ -73,12 +75,13 @@ import { addonReport, appendRecords, formatAddons, formatResearch, LABELS, label
 import { summarize, summarizeByTask } from "../hub/report.ts";
 import { hasTree, planUndo, repoOf, restore, Turns } from "../hub/snapshots.ts";
 import { pathWarnings } from "../hub/conflicts.ts";
+import { COMPLETION_SHELLS, completionScript } from "./completion.ts";
 import { classifyPeerCommand, cliCommandLabel, detectCliIdentity, LIVE_TEST_PERSON_REFUSAL, liveTestRefusal, peerCommandRefusal } from "./identity.ts";
 import { recordCliAudit, recordDelegatedCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
 import { paint, permissionBoundary, resolveColor, wrap, type Span } from "./console-state.ts";
 import { outputWidth, renderRoster, renderStatus, renderBoard, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, type DoctorCheck } from "./output.ts";
-import { renderHelp } from "./help.ts";
+import { renderHelp, configuredAcpHelp } from "./help.ts";
 import { renderTailEvent } from "./tail-render.ts";
 import { archiveProblem, archiveState, damagedState, failureText, MANIFEST, planReset, resetLines, resetRuntime, startState, type ResetPlan } from "./reset.ts";
 
@@ -117,16 +120,32 @@ try {
     }
   } 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 markedConfig = markedPeer && markedRoot && !definitionOf(markedPeer) ? readInstanceConfig(realPath(markedRoot)) : undefined;
+    const declarations = markedConfig?.instances;
+    if (markedPeer && markedRoot && markedConfig && declarations && Object.hasOwn(declarations, markedPeer)) {
       const canonicalRoot = realPath(markedRoot), config = loadConfig(canonicalRoot);
-      const executionCwd = resolveInstanceExecutionCwd(canonicalRoot, markedPeer, declarations, effectiveInstanceRoles(markedPeer, declarations, config.roles));
+      const executionCwd = resolveInstanceExecutionCwd(canonicalRoot, markedPeer, declarations, effectiveInstanceRoles(markedPeer, declarations, config.roles, markedConfig.catalog), markedConfig.catalog);
       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;
+let peerConfig: ReturnType<typeof readInstanceConfig>;
+const needsProjectDeclarations = cliCommandLabel(given, rest) === "unknown"
+  || rest.some(arg => arg === "--as" || arg.startsWith("--as="))
+  || !!process.env.AGENTHUB_PEER_ID && !definitionOf(process.env.AGENTHUB_PEER_ID)
+  || given === "help" && !!rest[0] && cliCommandLabel(rest[0], []) === "unknown";
+try { peerConfig = needsProjectDeclarations ? readInstanceConfig(cwd) : { catalog: createProjectAdapterCatalog(), ignored: [] }; } catch (error) { fail(startupDiagnostic(error)); }
+/** Local declarations for a command the running daemon answers. A config file that is mid-edit or invalid must not
+ * block it (lowering a permission, listing or reloading settings): such a read falls back to builtins and keeps its
+ * diagnostic for a key that only a declaration could define. */
+function localDeclarations(): { scope: Pick<InstanceRoleConfig, "instances" | "catalog">; error?: string } {
+  try { return { scope: readInstanceRoleConfig(cwd) }; }
+  catch (error) { return { scope: { catalog: createProjectAdapterCatalog() }, error: startupDiagnostic(error) }; }
+}
+const projectCatalog = peerConfig.catalog;
+const configuredCommand = !definitionOf(given) && projectCatalog.definitionOf(given)?.permission.genericAcp !== undefined;
 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);
@@ -134,8 +153,11 @@ const needsInstances = definitionOf(given) && rest.some(arg => arg === "--as" ||
 let declaredInstances: ReturnType<typeof readInstanceConfig>["instances"];
 let nativeSelection: ReturnType<typeof instanceLaunchArguments>;
 try {
-  declaredInstances = needsInstances ? readInstanceConfig(cwd).instances : undefined;
-  nativeSelection = instanceLaunchArguments(given, rest, declaredInstances);
+  declaredInstances = needsInstances || configuredCommand ? peerConfig.instances : undefined;
+  if (configuredCommand && !(rest.length === 1 && ["--help", "-h"].includes(rest[0]!))) {
+    const selection = parseConfiguredAcpArguments(given, rest, projectCatalog, declaredInstances);
+    nativeSelection = { ...(selection.peer !== given ? { instance: selection.peer } : {}), args: [...rest] };
+  } else 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
@@ -145,10 +167,19 @@ const cmd = asksHelp(given) || (definitionOf(given)?.start.passthrough !== true
 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 peerDefinition = (peer: unknown) => {
+  if (typeof peer !== "string") return undefined;
+  const bound = projectCatalog.definitionOf(peer, peerConfig.instances);
+  if (bound) return bound;
+  const current = readInstanceConfig(cwd);
+  return current.catalog.definitionOf(peer, current.instances);
+};
 const requireNamedPeerFeature = (hub: ControlClient, peer: string | undefined) => {
-  if (peer !== undefined && !definitionOf(peer)) requirePeerInstances(hub.features);
+  if (peer !== undefined && !definitionOf(peer)) {
+    const adapter = peerDefinition(peer);
+    if (adapter?.permission.genericAcp !== undefined && !hub.features.includes("configured_acp")) throw new Error("running hub lacks configured_acp; upgrade and restart it first");
+    if (adapter?.kind !== peer) requirePeerInstances(hub.features);
+  }
 };
 
 /** The project config, saying on stderr which machine-local fields it had to ignore (issue #17). */
@@ -159,8 +190,8 @@ const projectConfig = () => {
 };
 const stateDir = selected.stateDir;
 const caller = declaredInstances ? detectCliIdentity(process.env, declaredInstances) : unboundCaller;
-const commandLabel = cliCommandLabel(cmd, args);
-const commandAccess = classifyPeerCommand(cmd, args);
+const commandLabel = cliCommandLabel(cmd, args, projectCatalog);
+const commandAccess = classifyPeerCommand(cmd, args, projectCatalog);
 // Agent-authored content keeps its peer. Operational starts/holds may borrow console authority for live verification.
 const delegationRefused = liveTest && caller.role === "tools" && commandAccess !== "allowed" && liveTestRefusal(cmd, args);
 const delegatedPeer = liveTest && caller.role === "tools" && commandAccess !== "allowed" && !delegationRefused ? caller.peer : undefined;
@@ -407,11 +438,11 @@ function fail(message: string): never {
   process.exit(1);
 }
 
-async function taskOp(op: string, a: Record<string, unknown>, throwOnError = false, connection?: ControlClient): Promise<string> {
+async function taskOp(op: string, a: Record<string, unknown>, throwOnError = false, connection?: ControlClient, timeoutMs?: number): Promise<string> {
   const hub = connection ?? await connect();
   try {
     if (op === "hub_task_cancel" && !hub.features.includes("task_cancel")) fail("this daemon does not support task cancellation; upgrade it first");
-    const res = await hub.request({ t: "task", op, args: a }, op === "github_import" ? 60_000 : 30_000);
+    const res = await hub.request({ t: "task", op, args: a }, timeoutMs ?? (op === "github_import" ? 60_000 : 30_000));
     if (!res.ok) { if (throwOnError) throw new Error(res.error); audit("refused"); fail(res.error); }
     return res.text;
   } finally { if (!connection) hub.close(); }
@@ -761,10 +792,16 @@ const commands: Record<string, () => Promise<void> | void> = {
   help: () => {
     const color = resolveColor(undefined, { isTTY: !!process.stdout.isTTY, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR }) === true;
     const topic = asksHelp(args[0]) ? undefined : args[0];
-    const text = renderHelp(process.stdout.columns ?? 80, color, topic);
+    const text = topic && !definitionOf(topic) && projectCatalog.definitionOf(topic)?.permission.genericAcp !== undefined
+      ? configuredAcpHelp(topic) : renderHelp(process.stdout.columns ?? 80, color, topic);
     if (!text) fail(`unknown command "${topic}"; run ahub help`);
     console.log(text);
   },
+  completion: () => {
+    const script = completionScript(args[0]);
+    if (args.length !== 1 || !script) fail(`usage: ahub completion ${COMPLETION_SHELLS.join("|")}`);
+    process.stdout.write(script!);
+  },
   "--version": () => console.log(VERSION),
   version: () => console.log(VERSION),
 
@@ -1332,7 +1369,8 @@ const commands: Record<string, () => Promise<void> | void> = {
     const [peer, mode] = positional;
     if (positional.length > 2 || positional.some(arg => arg.startsWith("--")) || (mode !== undefined && !isPermissionMode(mode))) fail("usage: ahub permission [<peer> [ask|ask-when-needed|never-ask]] [--yes]");
     if (mode === "never-ask" && !args.includes("--yes")) fail("never-ask requires --yes; nothing was changed");
-    if (mode === "never-ask" && peer) console.error(`never-ask: ${permissionBoundary(peer)}; approval prompts are disabled`);
+    const { scope: permissionScope, error: permissionScopeError } = localDeclarations();
+    if (mode === "never-ask" && peer) console.error(`never-ask: ${permissionBoundary(peer, permissionScope.instances, permissionScope.catalog)}; approval prompts are disabled${permissionScopeError ? ` (project config unreadable: ${permissionScopeError})` : ""}`);
     const hub = await connect();
     try {
       const reply = await hub.request({ t: "permission", ...(peer ? { peer } : {}), ...(mode ? { mode, confirmed: args.includes("--yes") } : {}) }, 35_000);
@@ -1381,14 +1419,15 @@ const commands: Record<string, () => Promise<void> | void> = {
     const allowed: Record<string, string[]> = { list: ["--json"], get: ["--json"], set: ["--yes", "--preview", "--now"], undo: [], reload: [] };
     if (!Object.hasOwn(allowed, sub) || flags.some((flag) => !allowed[sub]!.includes(flag)) || extra.length) fail(usage);
     if ((sub === "get" && (!key || text !== undefined)) || (sub === "set" && (!key || text === undefined)) || ((sub === "list" || sub === "undo" || sub === "reload") && key !== undefined)) fail(usage);
-    const def = key === undefined ? undefined : settingDef(key);
-    if (typeof def === "string") fail(`${key}: ${def}`);
+    const { scope: settingScope, error: settingScopeError } = localDeclarations();
+    const def = key === undefined ? undefined : settingDef(key, settingScope.instances, settingScope.catalog);
+    if (typeof def === "string") fail(settingScopeError && def.startsWith("unknown setting") ? `${key}: ${def}; the project config could not be read: ${settingScopeError}` : `${key}: ${def}`);
     if (flags.includes("--now") && (typeof def !== "object" || def.group !== "Roster")) fail(usage);
     const value = sub === "set" ? parseSettingText(def!, text!) : undefined;
     const peer = def?.group === "Permissions" || def?.group === "Roster" ? def.path.at(-1)! : undefined;
     if (sub === "set" && value === "never-ask" && !flags.includes("--preview")) {
       if (!flags.includes("--yes")) fail("never-ask requires --yes; nothing was changed");
-      console.error(`never-ask: ${permissionBoundary(peer!)}; approval prompts are disabled`);
+      console.error(`never-ask: ${permissionBoundary(peer!, settingScope.instances, settingScope.catalog)}; approval prompts are disabled`);
     }
     const hub = await connect();
     try {
@@ -1438,7 +1477,9 @@ const commands: Record<string, () => Promise<void> | void> = {
         return console.log(paint([{ text: result.text }], false));
       }
       if (sub === "undo") {
-        const view = await request({ t: "settings_get" }), undoDef = settingDef(view.undo);
+        const view = await request({ t: "settings_get" }), undoDef = settingDef(view.undo, settingScope.instances, settingScope.catalog);
+        // A roster undo of a declared peer needs its confirmation prompt; without readable declarations, refuse rather than skip it.
+        if (typeof undoDef === "string" && settingScopeError) fail(`pending undo ${String(view.undo)}: ${undoDef}; the project config could not be read: ${settingScopeError}`);
         const rosterPeer = typeof undoDef !== "string" && undoDef.group === "Roster" ? undoDef.path[1] : undefined;
         let confirm: string | undefined;
         if (rosterPeer) {
@@ -1656,7 +1697,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   facts: async () => {
     if (!args.includes("--hook")) return fail("usage: ahub facts --hook (a Claude Code PreToolUse, PostToolUse and Stop hook)");
     try {
-      const out = await factsHook(await Bun.stdin.text(), stateDir, process.env.AGENTHUB_PEER_ID ?? "claude");
+      const out = await factsHook(await Bun.stdin.text(), stateDir, process.env.AGENTHUB_PEER_ID ?? defaultChannelPeer(undefined));
       if (out) console.log(out);
     } catch {
       // a hook that fails must not get in the way of the tool call
@@ -1665,7 +1706,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   "check-path": async () => {
     const hook = args.includes("--hook");
     const { one, rest } = takeFlags(args.filter((a) => a !== "--hook"), ["--peer"], []);
-    const peer = one["--peer"] ?? "claude";
+    const peer = one["--peer"] ?? defaultChannelPeer(undefined);
     let target = rest[0];
     try {
       if (hook) {
@@ -1722,10 +1763,10 @@ const commands: Record<string, () => Promise<void> | void> = {
     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;
+      const { instances: declarations, catalog } = readInstanceConfig(cwd);
       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));
+      const current = resolveInstanceExecutionCwd(cwd, turn.peer, declarations, effectiveInstanceRoles(turn.peer, declarations, config.roles, catalog), catalog);
       if (realPath(current) !== realPath(recordedWorkspace)) fail(`turn ${id}'s recorded execution workspace changed; nothing was restored`);
       return current;
     };
@@ -2055,7 +2096,18 @@ async function runConductorCommand(): Promise<void> {
     input = { peer: args[0] };
   } else {
     // Native TUIs return a human launch command through the daemon; an agent shell never executes it.
-    const parseStart = definitionOf(cmd)?.start.conductorStartArgs;
+    if (configuredCommand) {
+      const selection = parseConfiguredAcpArguments(cmd, args, projectCatalog, declaredInstances);
+      if (selection.preview) return runConfiguredAcpEntry({ kind: cmd, raw: args, catalog: projectCatalog, instances: declaredInstances, connect, print: text => console.log(text) });
+      if (selection.sessionId) fail("conductor starts accept no session override; a person starts a configured ACP session");
+      const hub = await connect();
+      try {
+        await requireActiveConfiguredAcp(hub, cmd, selection.peer, text => console.error(text));
+        console.log(await taskOp("hub_peer_start", { peer: selection.peer, mode: "headless" }, false, hub, 70_000));
+      } finally { hub.close(); }
+      return;
+    }
+    const parseStart = projectCatalog.definitionOf(cmd)?.start.conductorStartArgs;
     const parsed = parseStart ? parseStart(args) : args.length ? new Error(`conductor starts accept no launch overrides; use ahub ${cmd}`) : {};
     if (parsed instanceof Error) fail(parsed.message);
     op = "hub_peer_start";
@@ -2065,7 +2117,12 @@ async function runConductorCommand(): Promise<void> {
   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`));
+const runConfigured = configuredCommand ? async () => {
+  const selection = parseConfiguredAcpArguments(cmd, args, projectCatalog, declaredInstances);
+  if (!selection.preview) assertLifecycleAvailable();
+  await runConfiguredAcpEntry({ kind: cmd, raw: args, catalog: projectCatalog, instances: declaredInstances, connect, print: text => console.log(text), operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+} : undefined;
+const run = identity.role === "tools" && commandAccess === "conductor" ? runConductorCommand : (Object.hasOwn(commands, cmd) ? commands[cmd] : undefined) ?? runConfigured ?? (() => fail(`unknown command "${cmd}"; run ahub help`));
 try {
   assertDelegatedAuditConsumer(); // Local command paths must not begin after the authenticated consumer was replaced either.
   await run();

package/src/cli/memory.ts

@@ -1,12 +1,12 @@
 import { detectCliIdentity } from "./identity.ts";
 import { createStalenessProbe } from "../hub/memory-staleness.ts";
-import { looksSecret, type MemoryStore } from "@staix/agent-mem";
+import { looksSecret, memoryProjectKey, type MemoryStore } from "@staix/agent-mem";
 import type { SyncOptions } from "@staix/agent-mem";
 import { MEMORY_USAGE as CORE_MEMORY_USAGE, rawMemoryCommand, rawGoalCommand } from "@staix/agent-mem";
 import { mentionsPrivatePath, promotionScreen, withoutPii } from "../hub/memory-policy.ts";
 import { currentRouting, detectSignals } from "../hub/routing.ts";
 import { loadConfig } from "../hub/daemon.ts";
-import { bindProfileMemory, memoryProjectFor, openProfileMemory, MEMORY_PROFILE_UNAVAILABLE, MEMORY_SPLIT_INCOMPLETE, type MemoryProfileReceipt, type ProfileMemoryOptions } from "../hub/memory-profile.ts";
+import { bindProfileMemory, memoryProjectFor, memoryProjectForStore, openProfileMemory, MEMORY_PROFILE_UNAVAILABLE, MEMORY_SPLIT_INCOMPLETE, type MemoryProfileReceipt, type ProfileMemoryOptions } from "../hub/memory-profile.ts";
 
 export { GOAL_USAGE } from "@staix/agent-mem";
 export const MEMORY_USAGE = `${CORE_MEMORY_USAGE} | decay [--days N] [--json] | profile-check [--json]`;
@@ -16,9 +16,12 @@ const fail = (message: string): never => { throw new Error(message); };
 const loadConfigSafe = (cwd: string) => { try { return loadConfig(cwd); } catch { return undefined; } };
 
 
+/** The project key: an injected store resolves the alias in its own home, the default open in the ambient one (#240). */
+const projectOf = (cwd: string, provided: MemoryStore | undefined): string => provided ? memoryProjectForStore(provided, cwd) : memoryProjectFor(cwd);
+
 /** Bind each command at entry; the CLI closes default opens and injected stores remain caller-owned. */
-function commandStores(provided: MemoryStore | undefined, options: ProfileMemoryOptions) {
-  try { return { ...(provided ? bindProfileMemory(provided) : openProfileMemory(options)), owned: !provided }; }
+function commandStores(provided: MemoryStore | undefined, options: ProfileMemoryOptions, cwd: string) {
+  try { return { ...(provided ? bindProfileMemory(provided, undefined, memoryProjectKey(cwd)) : openProfileMemory(options)), owned: !provided }; }
   catch (error) { throw new Error(error instanceof Error && error.message === MEMORY_SPLIT_INCOMPLETE ? error.message : MEMORY_PROFILE_UNAVAILABLE); }
 }
 function profileOutput(text: string, json: boolean, profile: MemoryProfileReceipt | undefined, person: boolean): string {
@@ -43,9 +46,9 @@ export async function memoryCommand(args: string[], cwd: string, opts: { store?:
     const cutoffMs = (opts.now ?? Date.now)() - days * 24 * 3600_000;
     if (!Number.isSafeInteger(days) || !Number.isFinite(cutoffMs) || Math.abs(cutoffMs) > 8_640_000_000_000_000) fail("--days is outside the supported date range");
     const cutoff = new Date(cutoffMs).toISOString();
-    const project = memoryProjectFor(cwd), routing = currentRouting(cwd), paths = privatePaths();
+    const project = projectOf(cwd, opts.store), routing = currentRouting(cwd), paths = privatePaths();
     // Review must not promote a held source while reading it: only explicit person actions may append rows.
-    const context = commandStores(opts.store, { project, deferPromotions: true, now: opts.now });
+    const context = commandStores(opts.store, { project, deferPromotions: true, now: opts.now }, cwd);
     const store = context.store;
     try {
       context.binding.assertCurrent();
@@ -67,9 +70,9 @@ export async function memoryCommand(args: string[], cwd: string, opts: { store?:
     } finally { if (context.owned) store.close(); }
   }
   let showStale = false;
-  const project = memoryProjectFor(cwd);
+  const project = projectOf(cwd, opts.store);
   const context = commandStores(opts.store, { project, ttlMs: (loadConfigSafe(cwd)?.memory.short_ttl_days ?? 14) * 24 * 3600_000,
-    screen: promotionScreen(project, cwd, () => currentRouting(cwd), privatePaths) });
+    screen: promotionScreen(project, cwd, () => currentRouting(cwd), privatePaths) }, cwd);
   try {
     context.binding.assertCurrent();
     const text = await rawMemoryCommand(args, cwd, { ...opts, project, store: context.store, open: () => context.store,
@@ -92,8 +95,8 @@ export async function memoryCommand(args: string[], cwd: string, opts: { store?:
 export async function goalCommand(args: string[], cwd: string, opts: { store?: MemoryStore; link?: (goal: string, task: string) => Promise<string>; person?: boolean } = {}): Promise<string> {
   const person = opts.person ?? detectCliIdentity(process.env).role === "console";
   const policy = (): string[] => { try { return loadConfig(cwd).pii?.paths ?? []; } catch (e) { return fail(`the project's config does not load (${(e as Error).message}); fix it before using long-term tasks`); } };
-  const project = memoryProjectFor(cwd);
-  const context = commandStores(opts.store, { project });
+  const project = projectOf(cwd, opts.store);
+  const context = commandStores(opts.store, { project }, cwd);
   try {
     context.binding.assertCurrent();
     const text = await rawGoalCommand(args, cwd, { ...opts, project, store: context.store, open: () => context.store,

package/src/cli/output.ts

@@ -246,6 +246,7 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     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 (typeof p.statusNotice?.message === "string" && p.statusNotice.message) out.push(...detail("status notice", p.statusNotice.message, columns, "attention"));
     if (p.requestedModel && p.servedBy && p.requestedModel !== p.servedBy) out.push(...detail("requested model", p.requestedModel, columns));
     if (typeof p.importantWaitingSince === "number" && p.importantWaitingNote) out.push(...detail("important waiting", `${p.importantWaitingNote.replace(/^\d+ important messages? waiting/, "important messages waiting")}`, columns, "attention"));
     if (typeof p.oldestQueuedAt === "number") out.push(...detail(`${id} oldest queued`, relative(p.oldestQueuedAt, now), columns, "muted"));

package/src/cli/preview.ts

@@ -32,3 +32,12 @@ export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi" | "qwen
     unresolved: [...result.unresolved, { field: "executionCwd", reason: "verified by the daemon at instance start; preview does not start or authorize a worktree" }],
   };
 }
+
+/** Configured commands are arbitrary machine-local argv; preview never displays their values or starts a child. */
+export function configuredAcpPreview(kind: string, peer: string, resumed: boolean) {
+  return { tool: kind, peer, mode: "headless", cmd: "[redacted]", args: ["[redacted]"],
+    ...(resumed ? { sessionId: "[redacted]" } : {}),
+    envNames: [], redaction: "Configured executable, argv and session values are withheld.",
+    unresolved: [{ field: "runtime", reason: "Native identity, owned process group, accounts and daemon catalog are checked at start; preview runs nothing." }],
+    needs: ["A trusted config.local.json declaration and a running hub with configured_acp support."] };
+}

package/src/cli/recovery-guidance.ts

@@ -27,7 +27,7 @@ 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 projectDefinition = (peer: string, root: string) => definitionOf(peer) ?? definitionOf(peer, readInstanceConfig(root).instances);
+const projectDefinition = (peer: string, root: string) => { const builtin = definitionOf(peer); if (builtin) return builtin; const bound = readInstanceConfig(root); return bound.catalog.definitionOf(peer, bound.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"));

package/src/cli/terminal-recovery.ts

@@ -1,6 +1,6 @@
 import { shellQuote } from "./shell-quote.ts";
 export { shellQuote } from "./shell-quote.ts";
-import { definitionOf, type KindMap } from "../adapters/registry.ts";
+import { createProjectAdapterCatalog, definitionOf, type ProjectAdapterCatalog, type KindMap } from "../adapters/registry.ts";
 import { readInstanceConfig, readInstanceRoleConfig } from "../hub/instance-config.ts";
 import { effectiveInstanceRoles } from "../hub/instances.ts";
 import { resolveInstanceExecutionCwd } from "../hub/instance-execution.ts";
@@ -179,6 +179,8 @@ const MAX_WAIT_MS = 10 * 60 * 1000;
 export const MAX_COMMAND_MS = 30_000;
 /** #215: a replacement's readiness is awaited in slices this long, checking between them whether its launcher still runs. */
 const EXIT_SLICE_MS = 5_000;
+/** #599: after the replacement reads idle, its session mapping is re-read this often until the deadline. */
+const MAP_POLL_MS = 1_000;
 const ALLOWED_ENV = ["CODEX_HOME", "CLAUDE_CONFIG_DIR"] as const;
 type AllowedEnvName = (typeof ALLOWED_ENV)[number];
 
@@ -330,8 +332,8 @@ export function recordPath(stateDir: string): string {
 function executionRoot(peer: string, projectRoot: string, captured?: string): string {
   const builtin = definitionOf(peer);
   if (builtin?.session.launchRecord) return projectRoot;
-  const { instances: declarations, roles } = readInstanceRoleConfig(projectRoot);
-  const definition = definitionOf(peer, declarations);
+  const { instances: declarations, roles, catalog } = readInstanceRoleConfig(projectRoot);
+  const definition = catalog.definitionOf(peer, declarations);
   if (!definition?.session.launchRecord) throw new Error(`${peer}: no managed terminal recovery adapter`);
   if (!declarations?.[peer] || definition.transport !== "codex-appserver" && definition.transport !== "claude-channel") throw new Error(`${peer}: extra instance has no managed terminal support`);
   // #450 I3: a Claude instance reviews or plans in the canonical checkout; it never owns an execution worktree.
@@ -339,7 +341,7 @@ function executionRoot(peer: string, projectRoot: string, captured?: string): st
     if (captured !== undefined && captured !== projectRoot) throw new Error(`${peer}: recorded execution root changed; manual recovery required`);
     return projectRoot;
   }
-  const expected = resolveInstanceExecutionCwd(projectRoot, peer, declarations, effectiveInstanceRoles(peer, declarations, roles));
+  const expected = resolveInstanceExecutionCwd(projectRoot, peer, declarations, effectiveInstanceRoles(peer, declarations, roles, catalog), catalog);
   if (captured !== undefined && captured !== expected) throw new Error(`${peer}: declared execution worktree changed; manual recovery required`);
   return expected;
 }
@@ -554,12 +556,12 @@ function sessionFrom(terminal: Record<string, unknown>): string | undefined {
   return nestedString(terminal, ["sessionId", "agentSessionId", "resumeSessionId"]) ?? nestedString(wait, ["sessionId", "agentSessionId", "resumeSessionId", "session", "agentSession"]) ?? nestedString(session, ["id", "sessionId"]);
 }
 
-function identityFrom(terminal: Record<string, unknown>, instances?: KindMap): TerminalPeer | undefined {
+function identityFrom(terminal: Record<string, unknown>, instances: KindMap | undefined, catalog: ProjectAdapterCatalog): TerminalPeer | undefined {
   const wait = object(terminal.agentWait);
   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 (typeof candidate === "string" && definitionOf(candidate, instances)?.session.launchRecord) return candidate as TerminalPeer;
+    if (typeof candidate === "string" && catalog.definitionOf(candidate, instances)?.session.launchRecord) return candidate as TerminalPeer;
   }
   return undefined;
 }
@@ -597,7 +599,8 @@ function launchFor(peer: TerminalPeer, projectRoot: string, sessionId: string, o
   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 adapter = definitionOf(peer) ?? definitionOf(peer, readInstanceConfig(projectRoot).instances);
+  const scope = definitionOf(peer) ? undefined : readInstanceConfig(projectRoot);
+  const adapter = definitionOf(peer) ?? scope!.catalog.definitionOf(peer, scope!.instances);
   const nativeTail = adapter?.session.resumeArgv?.(binding, false);
   const tail = nativeTail && adapter ? [nativeTail[0]!, ...(peer !== adapter.kind ? ["--as", peer] : []), ...nativeTail.slice(1)] : undefined;
   if (!tail) throw new Error(`${peer}: no recorded terminal resume adapter`);
@@ -695,7 +698,8 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
   const byPeer: Partial<Record<TerminalPeer, TerminalBinding>> = {};
   const requested = (Object.entries(sessions) as [TerminalPeer, string | SessionRef | undefined][]).map(([peer, value]) => [peer, typeof value === "string" ? { sessionId: value } : value] as const).filter((entry): entry is [TerminalPeer, SessionRef] => !!entry[1]?.sessionId);
   if (!requested.length) return { bindings, byPeer, blockers, manualRequired: false };
-  const instances = requested.some(([peer]) => definitionOf(peer) === undefined) ? readInstanceConfig(projectRoot).instances : undefined;
+  const scope = requested.some(([peer]) => definitionOf(peer) === undefined) ? readInstanceConfig(projectRoot) : { instances: undefined, catalog: createProjectAdapterCatalog() };
+  const { instances, catalog } = scope;
   // #215: without the records a terminal could be bound from Orca metadata alone, losing the launch's captured
   // CODEX_HOME or CLAUDE_CONFIG_DIR: an unreadable file blocks the binding, never reads as "no records".
   const rows = launchRecords(config.stateDir);
@@ -712,7 +716,7 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
 
   for (const [peer, ref] of requested) {
     const sessionId = ref.sessionId;
-    const adapter = definitionOf(peer, instances), extra = definitionOf(peer) === undefined;
+    const adapter = catalog.definitionOf(peer, instances), extra = definitionOf(peer) === undefined;
     if (!adapter?.session.launchRecord || extra && adapter.transport !== "codex-appserver" && adapter.transport !== "claude-channel") { blockers.push(blocker("ownership-unknown", `${peer}: no declared managed-terminal recovery adapter`, peer)); continue; }
     const ownRecord = records.find(item => item.peer === peer);
     let expectedRoot: string, expectedTerminalRoot: string;
@@ -745,7 +749,7 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
       }
       // A show readback is required; list can be stale between recovery steps.
       if (!rootMatches(terminal.worktreePath ?? terminal.projectRoot, expectedTerminalRoot)) continue;
-      const identity = identityFrom(terminal, instances);
+      const identity = identityFrom(terminal, instances, catalog);
       const terminalSession = sessionFrom(terminal);
       const recorded = records.find((item) => item.peer === peer && item.handle === handle && item.worktreeId === terminal.worktreeId && item.incarnationId === terminal.incarnationId);
       // A recorded launcher proves ownership; the daemon's supplied session id is the
@@ -753,7 +757,7 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
       if ((!extra && identity === peer && terminalSession === sessionId) || (recorded !== undefined && (identity === undefined || identity === peer || extra && identity === adapter.kind) && (terminalSession === undefined || terminalSession === sessionId))) peerCandidates.push(terminal);
     }
     if (!peerCandidates.length) {
-      const ownershipUnknown = candidates.some((terminal) => identityFrom(terminal, instances) === undefined && !records.some((item) => item.handle === terminal.handle));
+      const ownershipUnknown = candidates.some((terminal) => identityFrom(terminal, instances, catalog) === undefined && !records.some((item) => item.handle === terminal.handle));
       blockers.push(ownershipUnknown
         ? blocker("ownership-unknown", `cannot prove ${peer} terminal ownership from Orca metadata`, peer)
         : blocker("missing-terminal", `no ${peer} terminal with session ${sessionId} in ${projectRoot}`, peer));
@@ -782,7 +786,7 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
     const recorded = records.find((item) => item.peer === peer && item.handle === handle && item.worktreeId === terminal.worktreeId && item.incarnationId === terminal.incarnationId);
     // Orca observation supplies file identity; launch arguments are not observed native session-file evidence.
     const { args: _launchArgs, ...observedTerminal } = terminal;
-    const sessionFile = definitionOf(peer, instances)?.session.crashIdentity?.(observedTerminal).sessionFile;
+    const sessionFile = catalog.definitionOf(peer, instances)?.session.crashIdentity?.(observedTerminal).sessionFile;
     const launch = launchFor(peer, projectRoot, sessionId, config, terminal, recorded, { ...ref, ...(sessionFile ? { sessionFile } : {}) });
     const binding: TerminalBinding = { peer, handle, incarnationId, worktreeId, projectRoot, ...(extra ? { executionCwd: expectedRoot, terminalRoot: expectedTerminalRoot } : {}), sessionId, ...(sessionFile ? { sessionFile } : {}), ...(ref.backend ? { backend: ref.backend } : {}), ...(ref.model ? { model: ref.model } : {}), launch, launchMetadata: launch };
     bindings.push(binding);
@@ -909,16 +913,24 @@ export async function createTerminal(binding: TerminalBinding, options?: Command
       idle = await waitForIdle(replacement, slice(), config);
     }
     if (!idle.satisfied) return { created: true, ready: false, manualRequired: true, blockers: idle.blockers };
-    // An idle terminal may be the login shell the launcher returned to.
-    const launch = await launches();
-    if (launch.gone) return exited("exited");
-    const shown = await showBinding(replacement, config);
-    const identity = identityFrom(shown);
-    const session = sessionFrom(shown);
-    const recorded = launch.live;
     const same = (value: string | undefined) => anySession || value === binding.sessionId;
-    if ((identity !== binding.peer || !same(session)) && !(recorded && (identity === undefined || identity === binding.peer) && (session === undefined || same(session)))) {
-      return { created: true, ready: true, manualRequired: true, blockers: [blocker("ambiguous-create", `created terminal ${createdHandle} cannot be mapped to the original ${binding.peer} session`, binding.peer, createdHandle)] };
+    let session: string | undefined;
+    // An idle terminal may be the login shell the launcher returned to, or a TUI that has not yet recorded its
+    // launch or been identified by Orca (#599): poll until it maps, contradicts, or the deadline passes.
+    for (;;) {
+      const launch = await launches();
+      if (launch.gone) return exited("exited");
+      const shown = await showBinding(replacement, config);
+      const scope = definitionOf(binding.peer) ? { instances: undefined, catalog: createProjectAdapterCatalog() } : readInstanceConfig(binding.projectRoot);
+      const identity = identityFrom(shown, scope.instances, scope.catalog);
+      session = sessionFrom(shown);
+      const recorded = launch.live;
+      if ((identity === binding.peer && same(session)) || (recorded && (identity === undefined || identity === binding.peer) && (session === undefined || same(session)))) break;
+      const contradicts = (identity !== undefined && identity !== binding.peer) || (session !== undefined && !same(session));
+      if (contradicts || Date.now() >= deadline) {
+        return { created: true, ready: true, manualRequired: true, blockers: [blocker("ambiguous-create", `created terminal ${createdHandle} cannot be mapped to the original ${binding.peer} session`, binding.peer, createdHandle)] };
+      }
+      await Bun.sleep(Math.max(1, Math.min(MAP_POLL_MS, deadline - Date.now())));
     }
     if (anySession && session) replacement = { ...replacement, sessionId: session };
     return { created: true, ready: true, manualRequired: false, binding: replacement, newBinding: replacement, blockers: [] };

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

@@ -1,4 +1,4 @@
-import { definitionOf } from "../adapters/registry.ts";
+import { ADAPTERS, definitionOf } from "../adapters/registry.ts";
 import { readInstanceConfig } from "../hub/instance-config.ts";
 import type { TerminalBinding } from "./terminal-recovery.ts";
 
@@ -102,7 +102,8 @@ export function restoreTransition(receipt: RestoreReceipt, evidence: RestoreEvid
 /** Checkable compact documentation, enumerated through the same pure decision function. */
 export function renderRestoreTransitionTable(): string {
   const launch = { packageEntrypoint: "table", command: "table", argv: [], env: {} };
-  const binding: TerminalBinding = { peer: "codex", handle: "selected", incarnationId: "selected", worktreeId: "selected", projectRoot: "table", sessionId: "planned", launch, launchMetadata: launch };
+  const examplePeer = ADAPTERS.find(definition => definition.transport === "codex-appserver")!.kind;
+  const binding: TerminalBinding = { peer: examplePeer, handle: "selected", incarnationId: "selected", worktreeId: "selected", projectRoot: "table", sessionId: "planned", launch, launchMetadata: launch };
   const receipts: RestoreReceipt[] = [{ state: "pending" }, { state: "waiting", origin: "pending", binding }, { state: "waiting", origin: "failed", binding }, { state: "done", binding }, { state: "failed" }];
   const launchers: RestoreEvidence["launcher"][] = ["live", "gone", "unknown", "no-record-yet", "replaced", "older-instance"];
   const result = (receipt: RestoreReceipt, evidence: RestoreEvidence, unchanged = false) => {