@staix/agent-hub 0.27.0 → 0.28.0

package/src/cli/main.ts

@@ -19,7 +19,7 @@ import { parseConfiguredAcpArguments, runConfiguredAcpEntry, requireActiveConfig
 import type { NativeCliEntryContext } from "../adapters/definitions/native-cli-entry-types.ts";
 import { BUILTIN_CLI_ENTRIES, createProjectAdapterCatalog, definitionOf, DOCTOR_TOOL_PROBES, DOCTOR_MEMORY_CAPTURE_PEERS, DOCTOR_PLUGIN_PROBE, nativeDoctorCheck, nativeMemoryCaptureRow, type MemorySetupReading, nativeDoctorRecoveryIdentity, nativeDoctorOptionalProbes } from "../adapters/registry.ts";
 import { parsePiFlags } from "../adapters/definitions/native-cli-pi.ts";
-import { supportsBoardReleaseFilter, supportsBoardColumnMetadata } from "./board-read.ts";
+import { supportsBoardReleaseFilter, supportsBoardColumnMetadata, readAllTasks } from "./board-read.ts";
 import { matchesPolicy } from "../hub/path-policy.ts";
 import { projectedDiff } from "../hub/projected-diff.ts";
 import { TextProjections } from "../hub/text-projection.ts";
@@ -70,7 +70,10 @@ import { inspectProject, startProject, stopProject, runProjectDaemon } from "../
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 import { openManager, startManager, stopManager } from "../hub/manager.ts";
 import { OmniRoute } from "../omniroute/client.ts";
-import { init, planInit } from "./init.ts";
+import { autonomyInheritanceChange, init, initSettingRows, planInit } from "./init.ts";
+import { INIT_USAGE, parseInitSettings } from "./init-settings.ts";
+import { promptGate, runInitPrompt, settingLines, shadowOffered, type InitAnswers } from "./init-prompt.ts";
+import { loadPacks } from "../hub/packs.ts";
 import { launcherPreview } from "./preview.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";
@@ -101,6 +104,7 @@ import { armRuns, benchCompare, benchCsv, benchReport, formatCompare, formatRepo
 import { benchPreflight, defaultIo, runBench } from "./bench.ts";
 import { ADDONS, isAddon, type AddonName } from "../hub/tooling.ts";
 import { goalCommand, memoryCommand, memoryStaleAnchorsCommand } from "./memory.ts";
+import { runSpecs, runSpecsStamp } from "./specs.ts";
 import { formatMemoryStaleAnchors } from "../hub/memory-stale-anchors.ts";
 import { AGENT_MEM_VERSION, assertAgentMemVersion, selectedMemoryProfile } from "../hub/memory-profile.ts";
 import { checkMemoryProfiles, formatMemoryProfileCheck } from "../hub/memory-profile-check.ts";
@@ -1037,23 +1041,28 @@ const commands: Record<string, () => Promise<void> | void> = {
     const setupFlags = takeFlags(args.filter(arg => arg !== "--yes"), ["--agents"], []);
     if (setupFlags.rest.length) fail("usage: ahub setup [--yes] [--agents <a,b>]");
     const registry = new Registry(), rl = process.stdin.isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
+    let homesFailed = false, homesFailure: unknown;
     try {
       const found = recoveryLauncherCurrent || delegatedPeer ? await discoverClaudeHomes({ home: homedir(), env: process.env }) : await usedClaudeHomes(registry, homedir(), process.env);
       for (const notice of found.notices) console.log(terminalText(notice));
-      await setupClaudeHomes({ homes: found.homes, env: process.env, packageRoot: root, yes: args.includes("--yes"),
-        interactive: !!rl,
-        current: () => { recoveryLauncherCurrent?.(); assertLifecycleAvailable(cwd); },
-        print: line => console.log(terminalText(line)), ask: async prompt => rl ? rl.question(prompt) : null,
-        probe: (argv, options) => { recoveryLauncherCurrent?.(); const result = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8", env: options.env, timeout: options.timeoutMs, maxBuffer: 1024 * 1024 }); recoveryLauncherCurrent?.(); return { status: result.status ?? -1, stdout: result.stdout ?? "" }; },
-        run: async (argv, env) => { recoveryLauncherCurrent?.(); const result = spawnSync(argv[0]!, argv.slice(1), { stdio: "inherit", env, timeout: 30_000 }); recoveryLauncherCurrent?.(); return result.status ?? -1; },
-      });
+      try {
+        await setupClaudeHomes({ homes: found.homes, env: process.env, packageRoot: root, yes: args.includes("--yes"),
+          interactive: !!rl,
+          current: () => { recoveryLauncherCurrent?.(); assertLifecycleAvailable(cwd); },
+          print: line => console.log(terminalText(line)), ask: async prompt => rl ? rl.question(prompt) : null,
+          probe: (argv, options) => { recoveryLauncherCurrent?.(); const result = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8", env: options.env, timeout: options.timeoutMs, maxBuffer: 1024 * 1024 }); recoveryLauncherCurrent?.(); return { status: result.status ?? -1, stdout: result.stdout ?? "" }; },
+          run: async (argv, env) => { recoveryLauncherCurrent?.(); const result = spawnSync(argv[0]!, argv.slice(1), { stdio: "inherit", env, timeout: 30_000 }); recoveryLauncherCurrent?.(); return result.status ?? -1; },
+        });
+      } catch (error) { homesFailed = true; homesFailure = error; }
       // #608: the one question about the default agent set, after the Claude homes and before doctor.
       if (!recoveryLauncherCurrent && !delegatedPeer) {
+        assertLifecycleAvailable(cwd);
         const refused = await setupStartAgents({ home: hubHome(), roots: [...registry.list().map(row => row.root), cwd], ...(setupFlags.one["--agents"] !== undefined ? { flag: setupFlags.one["--agents"] } : {}), yes: args.includes("--yes"),
           ...(rl ? { ask: async (prompt: string) => { try { return await rl.question(prompt); } catch { return null; } } } : {}), print: line => console.log(terminalText(line)) });
         if (refused) fail(refused);
       }
     } finally { registry.close(); rl?.close(); }
+    if (homesFailed) fail(startupDiagnostic(homesFailure));
     // #935: register the acon console plugin (acon reads it at its next start; no acon install is needed for this).
     const acon = registerAconPlugin(hubHome(), join(root, "src", "ui", "plugin.ts"));
     console.log("error" in acon ? `acon plugin not registered: ${acon.error}` : acon.changed ? `acon plugin registered: ${acon.path}` : `acon plugin up to date: ${acon.path}`);
@@ -1062,28 +1071,69 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   init: async () => {
-    const flags = takeFlags(args.filter(arg => arg !== "--dry-run" && arg !== "--json" && arg !== "--shadow" && arg !== "--release-guard"), ["--profile"], []);
-    if (flags.rest.length) fail("usage: ahub init [--profile dev|research|writing|general|<pack>] [--shadow] [--release-guard] [--dry-run --json]");
+    // #1065 T1: the settings flags come out first (a value flag takes the next word), then the older flags as before.
+    let settings: ReturnType<typeof parseInitSettings>;
+    try { settings = parseInitSettings(args); } catch (error) { return fail((error as Error).message); }
+    const flags = takeFlags(settings.rest.filter(arg => arg !== "--dry-run" && arg !== "--json" && arg !== "--shadow" && arg !== "--release-guard" && arg !== "--yes"), ["--profile"], []);
+    if (flags.rest.length) fail(INIT_USAGE);
     // A pack is a project file in .agenthub/roles/<name>.pack.json (#513a); init resolves the name and refuses an unknown one with the profiles and packs it knows.
-    const requestedProfile = flags.one["--profile"];
+    let requestedProfile = flags.one["--profile"];
     const newProject = !existsSync(join(cwd, ".agenthub/config.json"));
+    let request = settings.request, asked = Object.keys(request.values).length > 0;
+    let shadow = args.includes("--shadow"), releaseGuard = args.includes("--release-guard");
+    // #1065 T2: a person at a terminal on a new project, with no flag that sets anything and no --yes, is asked each setting (init-prompt.ts). Every other run, including a delegated peer, a live test and any run
+    // without a terminal, is never asked and gets defaults plus its flags. The gate is checked here, before any file is read or written, and --dry-run never prompts.
+    const flagGiven = asked || settings.request.autonomy !== undefined || requestedProfile !== undefined || shadow || releaseGuard;
+    if (promptGate({ newProject, flagGiven, yes: args.includes("--yes"), dryRun: args.includes("--dry-run"), stdinIsTTY: !!process.stdin.isTTY, stdoutIsTTY: !!process.stdout.isTTY, role: identity.role, delegated: !!delegatedPeer, liveTest })) {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      // Ctrl-C closes the readline interface, which settles a pending question as null: the prompt ends with nothing written.
+      const interrupted = new Promise<null>(done => rl.once("close", () => done(null)));
+      const ask = (question: string): Promise<string | null> => Promise.race([rl.question(question).catch(() => null), interrupted]);
+      const machine = readAutonomyDefaults(hubHome(), [cwd]);
+      const preview = (answers: InitAnswers): string[] => {
+        const rows = initSettingRows(cwd, answers.profile, answers.shadow, answers.releaseGuard, answers.request);
+        const plan = planInit(cwd, answers.profile, answers.shadow, answers.releaseGuard, answers.request);
+        // The same autonomy-inheritance row `--dry-run` shows, from the one helper: a new project inherits the trusted machine preset after the writes unless the answer was off.
+        const inherit = autonomyInheritanceChange(cwd, machine.enabled, answers.request.autonomy);
+        if (inherit) plan.push(inherit);
+        return [...plan.map(change => `${change.action} ${change.path}: ${change.reason}${change.managedBlock ? ` (managed block: ${change.managedBlock})` : ""}`), ...settingLines(rows)];
+      };
+      let result: Awaited<ReturnType<typeof runInitPrompt>>;
+      try {
+        result = await runInitPrompt({ ask, print: line => console.log(terminalText(line)) },
+          { ...(machine.startAgents ? { machineAgents: machine.startAgents } : {}), packs: [...loadPacks(cwd).packs.keys()], shadowAvailable: shadowOffered(repoOf(cwd)) }, preview);
+      } finally { rl.close(); }
+      if (!result.ok) { console.error(`ahub init: ${result.reason === "refused" ? result.message : result.reason === "interrupted" ? `interrupted; ${result.message}` : result.message}`); process.exitCode = result.reason === "refused" ? 1 : 0; return; }
+      requestedProfile = result.answers.profile; request = result.answers.request; asked = Object.keys(request.values).length > 0; shadow = result.answers.shadow; releaseGuard = result.answers.releaseGuard;
+    }
+    // `--autonomy off` skips the machine inheritance on a new project; `inherit` is today's behaviour. Neither changes an existing project.
+    const inheritAutonomy = newProject && request.autonomy !== "off";
+    if (!newProject && request.autonomy !== undefined) console.error("note: --autonomy applies to a new project only; this project already exists, so its autonomy settings are unchanged");
     if (args.includes("--dry-run")) {
-      const plan = planInit(cwd, requestedProfile, args.includes("--shadow"), args.includes("--release-guard"));
+      const plan = planInit(cwd, requestedProfile, shadow, releaseGuard, request);
+      const rows = initSettingRows(cwd, requestedProfile, shadow, releaseGuard, request);
       const defaults = readAutonomyDefaults(hubHome(), [cwd]);
-      if (newProject && defaults.enabled) plan.push({ action: existsSync(join(cwd, ".agenthub/config.local.json")) ? "modify" : "create", path: join(cwd, ".agenthub/config.local.json"), reason: "inherit the trusted machine autonomy preset; consent is checked at daemon startup" });
+      const inherit = inheritAutonomy ? autonomyInheritanceChange(cwd, defaults.enabled, request.autonomy) : undefined;
+      if (inherit) plan.push(inherit);
       if (defaults.notice) console.error(defaults.notice);
-      return console.log(args.includes("--json") ? JSON.stringify(plan, null, 2) : plan.map(change => `${change.action} ${change.path}: ${change.reason}${change.managedBlock ? ` (managed block: ${change.managedBlock})` : ""}`).join("\n") || "already up to date");
+      // Without a settings flag the preview is the bare list of file rows, as it always was; with one it is { changes, settings }.
+      if (args.includes("--json")) return console.log(JSON.stringify(asked ? { changes: plan, settings: rows } : plan, null, 2));
+      const settingLines = rows.map(row => `  ${row.key}: ${row.from === undefined ? "(not set)" : JSON.stringify(row.from)} -> ${JSON.stringify(row.to)} (${row.file})`);
+      return console.log([...plan.map(change => `${change.action} ${change.path}: ${change.reason}${change.managedBlock ? ` (managed block: ${change.managedBlock})` : ""}`), ...settingLines].join("\n") || "already up to date");
     }
     assertLifecycleAvailable(cwd);
-    if (newProject && delegatedPeer && readAutonomyDefaults(hubHome(), [cwd]).enabled) fail("machine autonomy inheritance is person-only; delegated live tests cannot apply it");
-    const changed = init(cwd, requestedProfile, args.includes("--shadow"), args.includes("--release-guard"));
+    if (inheritAutonomy && delegatedPeer && readAutonomyDefaults(hubHome(), [cwd]).enabled) fail("machine autonomy inheritance is person-only; delegated live tests cannot apply it (ahub init --autonomy off skips it)");
+    let changed: string[];
+    try { changed = init(cwd, requestedProfile, shadow, releaseGuard, request); } catch (error) { return fail((error as Error).message); }
     const project = registeredProject();
     console.log(changed.length ? changed.map((p) => `${existsSync(p) ? "wrote" : "removed"} ${p}`).join("\n") : "already up to date");
     if (newProject) {
-      const registry = new Registry();
-      try { for (const line of await inheritMachineAutonomy(project, hubHome(), autonomyEnvironment(process.env, !!process.stdin.isTTY), registry)) console.log(terminalText(line)); }
-      finally { registry.close(); }
-      // #608: the machine's default agent set, copied the same way (person-only: a delegated live test never inherits it).
+      if (inheritAutonomy) {
+        const registry = new Registry();
+        try { for (const line of await inheritMachineAutonomy(project, hubHome(), autonomyEnvironment(process.env, !!process.stdin.isTTY), registry)) console.log(terminalText(line)); }
+        finally { registry.close(); }
+      }
+      // #608: the machine's default agent set, copied the same way (person-only: a delegated live test never inherits it). An explicit --agents is already in config.local.json, so it wins.
       if (!delegatedPeer) { const roots = (() => { const r = new Registry(); try { return r.list().map(row => row.root); } finally { r.close(); } })(); for (const line of inheritMachineStart(cwd, hubHome(), [...roots, cwd])) console.log(terminalText(line)); }
     }
     const config = projectConfig(), examples = resolveProfile(config.profile, config.profile_overrides).example_checks;
@@ -1201,29 +1251,42 @@ const commands: Record<string, () => Promise<void> | void> = {
     const hub = await connect();
     try {
       if (operation === "list") {
-        const { one, rest: flags } = takeFlags(rest, ["--peer"], []);
-        if (flags.length) fail("usage: ahub queue list [--peer <id>] [--json] [--full] [--color=auto|always|never]");
-        const result = await hub.request({ t: "queue", op: "list", ...(one["--peer"] ? { peer: one["--peer"] } : {}) });
+        const all = rest.includes("--all");
+        const { one, rest: flags } = takeFlags(rest.filter((word) => word !== "--all"), ["--peer"], []);
+        if (flags.length) fail("usage: ahub queue list [--peer <id>] [--all] [--json] [--full] [--color=auto|always|never]");
+        const result = await hub.request({ t: "queue", op: "list", ...(one["--peer"] ? { peer: one["--peer"] } : {}), ...(all ? { all: true } : {}) });
         if (!result.ok) fail(result.error,result.refusalAudited===true,result.authorityRefused);
         if (options.json) return console.log(JSON.stringify(result.deliveries, null, 2));
         printOutput(renderQueue(result.deliveries, options.columns, Date.now()), options.color);
+        // #1096: rows a resolution already settled are history, hidden by default; say how many and how to see them, on stderr so a pipe of the table stays clean.
+        if (result.hiddenSettled) console.error(`${result.hiddenSettled} settled deliver${result.hiddenSettled === 1 ? "y" : "ies"} hidden (already resolved); ahub queue list --all shows them`);
         return;
       }
       if (operation === "discard") {
         // #713: the person's bulk clear of one peer's queue. Without --yes it only says how many it would discard.
         const yes = rest.includes("--yes");
         const { one, rest: others } = takeFlags(rest.filter((word) => word !== "--yes"), ["--peer", "--reason", "--state"], []);
-        if (others.length || !one["--peer"] || (one["--state"] !== undefined && !["queued", "needs_review"].includes(one["--state"]))) fail("usage: ahub queue discard --peer <id> --reason <text> [--state queued|needs_review] [--yes]");
+        if (others.length || !one["--peer"] || (one["--state"] !== undefined && !["queued", "needs_review", "failed"].includes(one["--state"]))) fail("usage: ahub queue discard --peer <id> --reason <text> [--state queued|needs_review|failed] [--yes]; without --state it clears the peer's queued and unsettled failed deliveries");
         if (yes && !one["--reason"]?.trim()) fail("ahub queue discard needs --reason <text> with --yes: it is recorded on every discarded delivery");
-        const result = await hub.request({ t: "queue", op: "discard", peer: one["--peer"], ...(one["--state"] ? { state: one["--state"] } : {}), ...(yes ? { confirmed: true, reason: one["--reason"] } : {}) }, 60_000);
+        // #1096: with no --state the bulk clear takes the peer's queued rows and its unsettled failed rows (needs_review rows still need an explicit --state, as before); an explicit --state names exactly one kind.
+        const states = one["--state"] === undefined ? ["queued", "failed"] : [one["--state"]];
+        // A hub from before `queue_discard_states` ignores `states` and discards queued rows whatever kind was asked for, so the new wire form is never sent to it. A single queued or needs_review kind still goes in the legacy `state` field that every hub reads.
+        const legacy = states.length === 1 && (states[0] === "queued" || states[0] === "needs_review");
+        if (!legacy && !hub.features.includes("queue_discard_states")) fail(`the running hub predates failed-row discard and would discard queued rows instead of ${one["--state"] === undefined ? "queued and failed rows" : `${one["--state"]} rows`}; nothing was sent. Upgrade and restart it first, or run ahub queue discard --peer ${one["--peer"]} --state queued to clear queued rows only`);
+        const result = await hub.request({ t: "queue", op: "discard", peer: one["--peer"], ...(legacy ? { state: states[0] } : { states }), ...(yes ? { confirmed: true, reason: one["--reason"] } : {}) }, 60_000);
         if (!result.ok) fail(result.error,result.refusalAudited===true,result.authorityRefused);
         if (options.json) return console.log(JSON.stringify(result, null, 2));
-        if (!yes) return console.log(`${result.count} ${result.state} deliver${result.count === 1 ? "y" : "ies"} for ${result.peer}; nothing discarded. Run again with --reason <text> --yes to discard them.`);
-        console.log(`discarded ${result.discarded} of ${result.count} ${result.state} deliver${result.count === 1 ? "y" : "ies"} for ${result.peer}${result.refused ? `; ${result.refused} refused (${Object.entries(result.refusedBy ?? {}).map(([why, n]) => `${why} ${n}`).join(", ")})` : ""}`);
+        // One kind keeps the sentence this command always printed ("12 queued deliveries for claude"); a mix of kinds names each ("3 queued and 2 failed deliveries for claude").
+        const present = Object.entries(result.byState ?? {}).filter(([, n]) => n) as [string, number][];
+        const noun = `deliver${result.count === 1 ? "y" : "ies"}`;
+        const what = present.length > 1 ? `${result.count} ${noun}` : `${result.count} ${present[0]?.[0] ?? states.join(" or ")} ${noun}`;
+        const split = present.length > 1 ? ` (${present.map(([kind, n]) => `${n} ${kind}`).join(" and ")})` : "";
+        if (!yes) return console.log(`${what} for ${result.peer}${split}; nothing discarded. Run again with --reason <text> --yes to discard them.`);
+        console.log(`discarded ${result.discarded} of ${what} for ${result.peer}${split}${result.refused ? `; ${result.refused} refused (${Object.entries(result.refusedBy ?? {}).map(([why, n]) => `${why} ${n}`).join(", ")})` : ""}`);
         return;
       }
       const [id, ...flags] = rest;
-      if (!id || !["show", "resolve"].includes(operation)) fail("usage: ahub queue show <id> | resolve <id> --action completed|retry|discard --reason <text> [--revision N] | discard --peer <id> --reason <text> [--state queued|needs_review] [--yes]");
+      if (!id || !["show", "resolve"].includes(operation)) fail("usage: ahub queue show <id> | resolve <id> --action completed|retry|discard --reason <text> [--revision N] | discard --peer <id> --reason <text> [--state queued|needs_review|failed] [--yes]");
       if (operation === "show") {
         if (flags.length) fail("usage: ahub queue show <id>");
         const shown = await hub.request({ t: "queue", op: "show", id });
@@ -1628,11 +1691,11 @@ const commands: Record<string, () => Promise<void> | void> = {
     const state = rest.find((a) => !a.startsWith("--"));
     if (byColumn && !boardStatus) boardStatus = (await boardHub.request({ t: "status" })).status;
     if (byColumn && !supportsBoardColumnMetadata(boardStatus)) fail("running hub does not support accurate board column metadata; use a compatible daemon");
-    const tasks = JSON.parse(await taskOp("hub_task_list", { ...(ready ? { ready: true } : state ? { state } : {}), ...(release ? { release } : {}), ...(byColumn ? { columnMetadata: true } : {}) }, false, boardHub)) as any[];
+    const tasks = await readAllTasks(args => taskOp("hub_task_list", args, false, boardHub), { ...(ready ? { ready: true } : state ? { state } : {}), ...(release ? { release } : {}), ...(byColumn ? { columnMetadata: true } : {}) }, identity.role === "tools");
     if (options.json && !byColumn) return console.log(JSON.stringify(tasks, null, 2));
     let allTasks: any[] | null = tasks;
     if (ready || state || release) {
-      try { allTasks = JSON.parse(await taskOp("hub_task_list", byColumn ? { columnMetadata: true } : {}, true, boardHub)) as any[]; }
+      try { allTasks = await readAllTasks(args => taskOp("hub_task_list", args, true, boardHub), byColumn ? { columnMetadata: true } : {}, identity.role === "tools"); }
       catch (error) {
         if (byColumn) fail("board column dependency context unavailable; retry with a complete snapshot");
         allTasks = null;
@@ -1871,13 +1934,13 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (sub !== "propose" || rest.length < 1) fail("usage: ahub task propose [<class>] <title...> | show <id> | assign <id> <peer> | unassign <id> | cancel <id> --reason <text> | escalate <id> | handoff --project <root|id> <title...>");
     // `--class` is the explicit form. A first word that is a class name is still taken as the class (the documented
     // short form), but said out loud: "review the auth module" would otherwise be filed as class review, silently.
-    const urgent = rest.includes("--urgent"), backlog = rest.includes("--backlog");
-    const flags = takeFlags(rest.filter((a) => a !== "--urgent" && a !== "--backlog"), ["--owner", "--detail", "--class"], ["--path", "--after"]);
+    const urgent = rest.includes("--urgent"), backlog = rest.includes("--backlog"), needsNetwork = rest.includes("--needs-network"), needsWorktree = rest.includes("--needs-worktree");
+    const flags = takeFlags(rest.filter((a) => a !== "--urgent" && a !== "--backlog" && a !== "--needs-network" && a !== "--needs-worktree"), ["--owner", "--detail", "--class"], ["--path", "--after"]);
     const positional = !flags.one["--class"] && ((CLASSES as readonly string[]).includes(flags.rest[0] ?? "") || Object.hasOwn((() => { const config = projectConfig(); return resolveProfile(config.profile, config.profile_overrides); })().classes, flags.rest[0] ?? "")) && flags.rest.length > 1;
     const cls = flags.one["--class"] ?? (positional ? flags.rest[0] : undefined);
     const title = (positional ? flags.rest.slice(1) : flags.rest).join(" ");
     if (positional) console.error(`note: "${cls}" was taken as the class and left out of the title; use --class <c> when the title itself starts with that word`);
-    console.log(await taskOp("hub_task_propose", { ...(cls ? { class: cls } : {}), title, owner: flags.one["--owner"], detail: flags.one["--detail"], ...(flags.many["--path"]?.length ? { refs: { paths: flags.many["--path"] } } : {}), ...(flags.many["--after"]?.length ? { after: flags.many["--after"].map(Number) } : {}), ...(urgent ? { urgent: true } : {}), ...(backlog ? { backlog: true } : {}) }));
+    console.log(await taskOp("hub_task_propose", { ...(cls ? { class: cls } : {}), title, owner: flags.one["--owner"], detail: flags.one["--detail"], ...(flags.many["--path"]?.length ? { refs: { paths: flags.many["--path"] } } : {}), ...(flags.many["--after"]?.length ? { after: flags.many["--after"].map(Number) } : {}), ...(urgent ? { urgent: true } : {}), ...(needsNetwork ? { needs_network: true } : {}), ...(needsWorktree ? { needs_worktree: true } : {}), ...(backlog ? { backlog: true } : {}) }));
   },
 
   review: async () => {
@@ -2220,7 +2283,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (args.includes("--all")) return printProjects(options);
     const hub = await connect();
     try {
-      const { status } = await hub.request({ t: "status" });
+      const { status } = await hub.request({ t: "status", specs: true });
       if (options.json) return console.log(JSON.stringify(status, null, 2));
       const quota = await hub.request({ t: "budget" });
       printOutput(renderStatus({ ...status, budget: quota.budget ?? {} }, options.columns, Date.now(), options.full), options.color);
@@ -2373,6 +2436,14 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (options.json) return console.log(JSON.stringify(data, null, 2));
     printOutput(renderReport(data, options.columns, Date.now(), by >= 0), options.color);
   },
+  specs: async () => {
+    if (args[0] !== "stamp") { process.exitCode = runSpecs(args, cwd, loadConfig(cwd).specs); return; }
+    // #1064 T3: person only. An agent identity never gets here (stamp is a `console` command in classifyPeerCommand); runSpecsStamp also refuses a run with no terminal.
+    const rl = process.stdin.isTTY && process.stdout.isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
+    try {
+      process.exitCode = await runSpecsStamp(args.slice(1), cwd, loadConfig(cwd).specs, { isTTY: !!rl, ask: async question => /^y(es)?$/i.test((await rl!.question(`${question} [y/N] `)).trim()) });
+    } finally { rl?.close(); }
+  },
   usage: async () => {
     const options = outputOptions();
     const rest = outputArguments();

package/src/cli/output.ts

@@ -10,9 +10,11 @@ import { ownerIsolationText } from "./role-holders.ts";
 import { schedulePeriodText, scheduleWhen } from "../hub/schedules.ts";
 import { formatReport, formatTaskReport, type Report, type TaskReport } from "../hub/report.ts";
 import type { Counter, LimitsResult, TotalResult, UsageResult } from "../hub/usage-rollup.ts";
+import type { SpecsStatus } from "../hub/specs-task.ts";
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
+  specs?: SpecsStatus & { missingBlockHint?: boolean };
   queueBackpressure?: QueueBackpressureStatus;
   pendingRestart?: readonly { key: string; reason: string }[];
   retainedConfig?: readonly { key: string; reason: string }[];
@@ -211,6 +213,13 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   if (data.roleInfo) data = { ...data, peers: Object.fromEntries(Object.entries(data.peers).map(([peer, value]) => [peer, { ...value, ...data.roleInfo?.[peer] }])) };
   const out = lines(`agent-hub${data.version ? ` ${data.version}` : ""}  pid ${data.pid ?? "unknown"}  control 127.0.0.1:${data.controlPort ?? "unknown"}`, columns, "info");
   if (data.cwd) out.push(...lines(data.cwd, columns));
+  const specs = data.specs;
+  if (specs && [specs.specCount, specs.documents, specs.errors, specs.stale].every(value => Number.isSafeInteger(value) && value >= 0)
+    && (specs.specCount > 0 || specs.documents > 0 || specs.errors > 0)) {
+    out.push(...lines(`specs: ${specs.specCount} (errors ${specs.errors}, stale ${specs.stale})`, columns, specs.errors || specs.stale ? "attention" : undefined));
+    if (specs.truncated) out.push(...lines("specs: report truncated; narrow specs.roots and run ahub specs check", columns, "attention"));
+    if (specs.missingBlockHint) out.push(...lines("specs: AGENTS.md has no specs instruction block; read the covering specs before changing their paths", columns, "attention"));
+  }
   for (const pending of data.pendingRestart ?? []) out.push(...detail("pending restart", `${pending.key}: ${pending.reason}`, columns, "attention"));
   if (data.mainCheckout) out.push(...detail("main checkout", data.mainCheckout, columns, "attention"));
   for (const drift of data.agentDrift ?? []) out.push(...detail("agent CLI drift", `${drift.id} ${drift.version} ${drift.state}; last receipt ${drift.receipt}`, columns, "attention"));
@@ -532,6 +541,11 @@ function fields(value: unknown, columns: number | undefined, now: number, prefix
 export function renderQueueShow(delivery: any, columns?: number, now = Date.now()): Span[][] {
   const out = [...lines("Delivery", columns, "strong"), ...fields(delivery, columns, now)];
   if (delivery?.state === "needs_review" && delivery.id) out.push([], ...detail("resolve", `ahub queue resolve ${delivery.id} --action completed|retry|discard --reason <text>`, columns, "failure"));
+  // #1096: a failed row that no one has settled can be cleared by the person or the conductor; one a resolution already settled says what is left (nothing).
+  else if (delivery?.state === "failed" && delivery.id) {
+    if (delivery.resolvedBy) out.push([], ...detail("resolve", `already resolved by ${delivery.resolvedBy}; nothing is left to do for this row${delivery.resolvedBy === "retry" ? " (its redelivery is a separate delivery: ahub queue list)" : ""}`, columns, "muted"));
+    else out.push([], ...detail("resolve", `ahub queue resolve ${delivery.id} --action discard|completed --reason <text>  (discard to drop it, completed to acknowledge it as handled; the person or the conductor)`, columns, "failure"));
+  }
   return out;
 }
 export function renderModelsStatus(status: unknown, columns?: number, now = Date.now()): Span[][] {

package/src/cli/setup-homes.ts

@@ -1,6 +1,8 @@
 import { checkClaudeHome, claudeHomeEnvironment, type ClaudeHome, type ClaudeHomeProbe } from "./claude-homes.ts";
 import { installClaudeProfileHook } from "./claude-profile-hook.ts";
 
+const marketplaceRemovalRefusal = (home: string) => new Error(`Claude setup refused marketplace removal in ${home}; non-user plugin rows were preserved`);
+
 export interface SetupHomesPorts {
   env: NodeJS.ProcessEnv;
   packageRoot: string;
@@ -21,9 +23,11 @@ export async function setupClaudeHomes(ports: SetupHomesPorts): Promise<void> {
   for (const home of ports.homes) initial.push(await checkClaudeHome(home, ports.packageRoot, ports.env, ports.probe, undefined, true));
   for (const check of initial) {
     ports.print(`Claude home ${check.home.path}: plugin ${check.plugin.state}; hook ${check.hook.state}.`);
+    for (const notice of ("notices" in check.plugin ? check.plugin.notices : undefined) ?? []) ports.print(`${check.home.path}: ${notice}.`);
     if (check.plugin.state === "unknown" || check.hook.state === "refused") throw new Error(`Claude setup cannot safely inspect ${check.home.path}; nothing was changed`);
+    if (check.next?.blocked) throw marketplaceRemovalRefusal(check.home.path);
   }
-  for (const check of initial) if (check.next) ports.print(`${check.home.path}: ${check.next.argv.join(" ")} (${check.next.why})`);
+  for (const check of initial) if (check.next) ports.print(`${check.home.path}: ${check.next.blocked ? "setup blocked" : check.next.argv.join(" ")} (${check.next.why})`);
   if (initial.every(check => !check.next && check.hook.state === "installed")) return;
   if (!ports.yes && ports.interactive === false) throw new Error("not a terminal: nothing was changed; rerun with --yes to apply");
   if (!ports.yes && !["y", "yes"].includes((await ports.ask("Install the hub plugin and project-neutral hook in these Claude homes? [y/N] "))?.trim().toLowerCase() ?? "")) { ports.print("Claude setup was not changed."); return; }
@@ -31,11 +35,22 @@ export async function setupClaudeHomes(ports: SetupHomesPorts): Promise<void> {
   for (const check of initial) {
     let current = check;
     for (let step = 0; current.next && step < 6; step++) {
-      ports.print(`${check.home.path}: ${current.next.argv.join(" ")} (${current.next.why})`);
+      const action = current.next;
+      if (action.blocked) throw marketplaceRemovalRefusal(check.home.path);
+      ports.print(`${check.home.path}: ${action.argv.join(" ")} (${action.why})`);
       ports.current?.();
-      if (await ports.run(current.next.argv, claudeHomeEnvironment(check.home, ports.env)) !== 0) throw new Error(`Claude plugin setup failed for ${check.home.path}; no later home was changed`);
+      if (action.argv[2] === "marketplace" && action.argv[3] === "remove") {
+        const fresh = await checkClaudeHome({ ...check.home, exists: true }, ports.packageRoot, ports.env, ports.probe, undefined, true);
+        if (fresh.plugin.state === "unknown") throw new Error(`Claude plugin inventory is unavailable for ${check.home.path}`);
+        if (fresh.next?.blocked) throw marketplaceRemovalRefusal(check.home.path);
+        if (JSON.stringify(fresh.next?.argv) !== JSON.stringify(action.argv)) { current = fresh; continue; }
+        current = fresh;
+        ports.current?.();
+      }
+      if (await ports.run(action.argv, claudeHomeEnvironment(check.home, ports.env)) !== 0) throw new Error(`Claude plugin setup failed for ${check.home.path}; no later home was changed`);
       current = await checkClaudeHome({ ...check.home, exists: true }, ports.packageRoot, ports.env, ports.probe, undefined, true);
       if (current.plugin.state === "unknown") throw new Error(`Claude plugin inventory is unavailable for ${check.home.path}`);
+      if (current.next?.blocked) throw marketplaceRemovalRefusal(check.home.path);
     }
     if (current.next) throw new Error(`Claude setup exceeded six plugin steps for ${check.home.path}`);
     ports.current?.();

package/src/cli/specs.ts

@@ -0,0 +1,150 @@
+import { chmodSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { SpecsEngine, stampFrontmatter, type SpecsConfig, type SpecsStampRow } from "../hub/specs.ts";
+import { terminalText } from "./console-state.ts";
+import { editJsonText } from "./init-settings.ts";
+
+export interface SpecsOutput { out(line: string): void; error(line: string): void }
+const output: SpecsOutput = { out: line => console.log(line), error: line => console.error(line) };
+
+/** Read-only repository inspection: no daemon connection or stamp mutation. */
+export function runSpecs(args: readonly string[], root: string, config: SpecsConfig, io: SpecsOutput = output): number {
+  const [command, ...rest] = args;
+  const usage = "usage: ahub specs list [--json] | check [--require-fresh] [--base <ref>] [--json] | covers <file...>";
+  if (!["list", "check", "covers"].includes(command ?? "")) { io.error(usage); return 1; }
+  let json = false, requireFresh = false, base: string | undefined;
+  const paths: string[] = [];
+  for (let index = 0; index < rest.length; index++) {
+    const arg = rest[index]!;
+    if (arg === "--json" && command !== "covers" && !json) json = true;
+    else if (arg === "--require-fresh" && command === "check" && !requireFresh) requireFresh = true;
+    else if (arg === "--base" && command === "check" && base === undefined) {
+      base = rest[++index];
+      if (!base || base.startsWith("-")) { io.error("specs: --base needs a Git reference; name a commit or branch"); return 1; }
+    } else if (command === "covers" && !arg.startsWith("-")) paths.push(arg);
+    else { io.error(usage); return 1; }
+  }
+  if (command === "covers" && !paths.length) { io.error(usage); return 1; }
+  try {
+    const engine = new SpecsEngine(root, config);
+    if (command === "list" || command === "covers") {
+      const report = command === "list" ? engine.list() : engine.covers(paths);
+      if (json) io.out(JSON.stringify(report));
+      else {
+        for (const spec of report.specs) io.out(terminalText(`${spec.id} (${spec.path}): ${spec.title}`));
+        for (const item of report.items) io.error(terminalText(`specs: ${item.severity} ${item.code}: ${item.message}; ${item.nextSteps}`));
+        if (report.truncated) io.error("specs: scan truncated; narrow specs.roots and run ahub specs check again");
+      }
+      return report.errors ? 1 : 0;
+    }
+    const report = engine.check({ ...(base === undefined ? {} : { base }), requireFresh });
+    if (json) io.out(JSON.stringify(report));
+    else if (report.specCount || report.freshness.length || report.items.length || report.truncated) {
+      for (const item of report.items) io.out(terminalText(`specs: ${item.severity} ${item.code}: ${item.message}; ${item.nextSteps}`));
+      for (const row of report.freshness) if (row.state === "stale") {
+        io.out(terminalText(`specs: ${row.path}: stale (${row.commitsSince ?? "unknown"} source commits${row.dirty ? "; uncommitted source changes" : ""})`));
+      }
+      if (report.truncated) io.out("specs: scan truncated; narrow specs.roots and run ahub specs check again");
+      io.out(`specs: ${report.specCount} specs, ${report.errors} errors, ${report.warnings} warnings, ${report.stale} stale`);
+    }
+    return report.errors || requireFresh && report.stale ? 1 : 0;
+  } catch (error) {
+    io.error(terminalText(`specs: ${error instanceof Error ? error.message : "inspection unavailable"}; check the repository and specs configuration, then run ahub specs check again`));
+    return 1;
+  }
+}
+
+interface PreparedStamp { path: string; absolute: string; original: Buffer; next: Buffer; mode: number }
+/** The new bytes for every file a stamp would change, made without writing; a string is the reason one could not be made. A stamps file takes all of its entries in one write. */
+function prepareStamps(root: string, rows: readonly SpecsStampRow[]): PreparedStamp[] | string {
+  const byFile = new Map<string, SpecsStampRow[]>();
+  for (const row of rows) byFile.set(row.path, [...(byFile.get(row.path) ?? []), row]);
+  const files: PreparedStamp[] = [];
+  for (const [path, group] of byFile) {
+    const absolute = resolve(root, path), original = readFileSync(absolute), mode = statSync(absolute).mode & 0o777; // the file keeps its own permissions
+    if (group[0]!.kind === "stamps-file") {
+      let text = original.toString("utf8");
+      for (const row of group) text = editJsonText(text, ["documents", row.document!, "verifiedAgainst"], row.to);
+      JSON.parse(text); // the edit must still be the JSON the engine reads
+      files.push({ path, absolute, original, next: Buffer.from(text, "utf8"), mode });
+    } else {
+      const done = stampFrontmatter(original.toString("latin1"), group[0]!.to);
+      if (!done.ok) return `${path}: ${done.error}`;
+      files.push({ path, absolute, original, next: Buffer.from(done.text, "latin1"), mode });
+    }
+  }
+  return files;
+}
+
+/** What `ahub specs stamp` needs from its surroundings: whether a person is at a terminal, and a yes/no question to ask them. Tests pass their own. */
+export interface SpecsStampTerminal { isTTY: boolean; ask(question: string): Promise<boolean> }
+
+const STAMP_USAGE = "usage: ahub specs stamp <id-or-document>... [--yes]";
+const writeAtomic = (path: string, bytes: Buffer, mode: number): void => {
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temporary, bytes, { mode, flag: "wx" });
+  chmodSync(temporary, mode);
+  renameSync(temporary, path);
+};
+
+/**
+ * #1064 T3: `ahub specs stamp <id-or-document>... [--yes]`, a person's record that they reviewed a spec or stamped document against HEAD.
+ * Person only, three ways: main.ts refuses any agent identity before this runs (the command is `console` class, and `--live-test` delegation is refused for it too), this refuses
+ * a run without a terminal even with --yes, and nothing here talks to the hub. It shows what it would write (the old and new stamp per document), asks, and then changes only the
+ * `verified-against` line of a spec, or the `verifiedAgainst` value of a stamps-file entry, keeping every other byte. It is refused, writing nothing, while a document's covered
+ * paths have uncommitted changes. The new stamp is the full HEAD SHA, so it is an ancestor of HEAD.
+ */
+export async function runSpecsStamp(args: readonly string[], root: string, config: SpecsConfig, terminal: SpecsStampTerminal, io: SpecsOutput = output): Promise<number> {
+  const targets: string[] = [];
+  let yes = false;
+  for (const arg of args) {
+    if (arg === "--yes" && !yes) yes = true;
+    else if (!arg.startsWith("-")) targets.push(arg);
+    else { io.error(STAMP_USAGE); return 1; }
+  }
+  if (!targets.length) { io.error(STAMP_USAGE); return 1; }
+  if (!terminal.isTTY) {
+    io.error("specs: stamping records a person's review and needs a terminal, even with --yes; run ahub specs stamp in your own terminal, or in ahub console; nothing was written");
+    return 1;
+  }
+  try {
+    const engine = new SpecsEngine(root, config);
+    const plan = engine.stampPlan(targets);
+    if (plan.refusals.length) {
+      for (const refusal of plan.refusals) io.error(terminalText(`specs: ${refusal}`));
+      io.error("specs: nothing was written");
+      return 1;
+    }
+    const short = (sha: string | null) => sha === null ? "none" : sha.slice(0, 12);
+    io.out(terminalText(`stamp against HEAD ${plan.head.slice(0, 12)}:`));
+    for (const row of plan.rows) io.out(terminalText(`  ${row.path}${row.document ? ` (${row.document})` : ""}: ${short(row.from)} -> ${short(row.to)}${row.from === row.to ? " (already this stamp)" : ""}`));
+    const changing = plan.rows.filter(row => row.from !== row.to);
+    if (!changing.length) { io.out("specs: every named document already holds this stamp; nothing to write"); return 0; }
+    // Every file's new bytes are made before anyone is asked, so a document that cannot be stamped is refused up front and no file is written for it, and what the person approves is
+    // exactly what is written. `original` is what the new bytes were made from.
+    const prepared = prepareStamps(engine.rootPath, changing);
+    if (typeof prepared === "string") { io.error(terminalText(`specs: ${prepared}; nothing was written`)); return 1; }
+    if (!yes && !await terminal.ask(`Record that you reviewed ${changing.length === 1 ? "this document" : `these ${changing.length} documents`} against HEAD ${plan.head.slice(0, 12)}?`)) {
+      io.out("specs: not stamped; nothing was written");
+      return 0;
+    }
+    // The answer may have taken minutes. Revalidate what the person was shown before any write: HEAD, every target's plan row (so a covered path that became dirty is refused), and each
+    // file's bytes. Any difference refuses the whole run.
+    const again = engine.stampPlan(targets);
+    const changed = again.refusals.length ? again.refusals.map(refusal => `specs: ${refusal}`)
+      : again.head !== plan.head || JSON.stringify(again.rows) !== JSON.stringify(plan.rows) ? ["specs: HEAD or a document's covered paths changed while you were deciding"]
+      : prepared.filter(file => !readFileSync(file.absolute).equals(file.original)).map(file => `specs: ${file.path} changed while you were deciding`);
+    if (changed.length) {
+      for (const line of changed) io.error(terminalText(line));
+      io.error("specs: nothing was written; review the current state and run ahub specs stamp again");
+      return 1;
+    }
+    // ponytail: a change in the instant between this recheck and the renames below is not seen; each rename is atomic and the diff is the person's to review before committing, so there is no lock. A lock file if two people stamp one checkout.
+    for (const file of prepared) writeAtomic(file.absolute, file.next, file.mode);
+    io.out(`specs: stamped ${changing.length} document${changing.length === 1 ? "" : "s"} at ${plan.head.slice(0, 12)}; review the diff and commit it`);
+    return 0;
+  } catch (error) {
+    io.error(terminalText(`specs: ${error instanceof Error ? error.message : "stamping unavailable"}; check the repository and specs configuration, then run ahub specs stamp again`));
+    return 1;
+  }
+}

package/src/cli/terminal-recovery.ts

@@ -225,7 +225,7 @@ function runnerFailure(argv: readonly string[], result: CommandResult): Recovery
 async function run(runner: CommandRunner, argv: readonly string[]): Promise<unknown> {
   const result = await runner(argv);
   if (commandStatus(result) !== 0) {
-    // Orca 1.4.223 answers a handle whose terminal was removed with `{"ok":false,"error":{"code":"terminal_handle_stale"}}`.
+    // Orca 1.4.223 and, rechecked read-only, 1.4.245 (docs/verification/2026-11-02-orca-1.4.245-cli-contract.md) answer a handle whose terminal was removed with `{"ok":false,"error":{"code":"terminal_handle_stale"}}`.
     if (errorCode(result) === "terminal_handle_stale") {
       const handle = argv.includes("--terminal") ? argv[argv.indexOf("--terminal") + 1] : undefined;
       throw new OrcaCommandError({ code: "terminal-gone", message: `the Orca terminal${handle ? ` ${handle}` : ""} no longer exists` });
@@ -300,17 +300,41 @@ function defaultRunner(executable: string): CommandRunner {
 export const orcaExecutable = (): string => resolveOrcaExecutable();
 
 /**
- * #269: the Orca worktree a terminal for this project can be opened in: the one this process runs in, or the one the
- * last recorded `ahub <peer>` launch of this project used. Undefined when there is none or the record does not read.
- * ponytail: the environment's worktree is taken as this project's; a hub started from another project's Orca terminal
- * (`ahub --project`, the dashboard manager's start, an upgrade or restart that brings several projects up from one
- * terminal) opens the terminal there and `ahub <peer>` then fails its root readback. Ask Orca for the worktree's path
- * and compare it if that case shows up.
+ * #269: whether Orca is in play for this project: this process runs in an Orca terminal, or an earlier `ahub <peer>`
+ * launch of this project recorded a worktree. It is only a hint for a synchronous "could a start open a terminal"
+ * answer. It is never the worktree a terminal is opened in: the environment names the worktree of whatever terminal
+ * this process was started from, which is another project's when `ahub --project`, the dashboard manager or an upgrade
+ * brought this project up (#1089). `resolveStartTerminalWorktree` names the worktree.
  */
-export function startTerminalWorktree(projectRoot: string, stateDir: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
-  if (env.ORCA_WORKTREE_ID) return env.ORCA_WORKTREE_ID;
+export function startTerminalCandidate(projectRoot: string, stateDir: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.ORCA_WORKTREE_ID) return true;
   const records = launchRecords(stateDir);
-  return records === "unreadable" ? undefined : records.rows.filter((row) => row.projectRoot === projectRoot).at(-1)?.worktreeId;
+  return records !== "unreadable" && records.rows.some((row) => row.projectRoot === projectRoot && typeof row.worktreeId === "string");
+}
+
+/** #1089: how many worktrees one `orca worktree list` asks for; a longer list is reported as truncated and never read as "none". */
+const WORKTREE_LIST_LIMIT = 500;
+
+/**
+ * #1089: the Orca worktree whose root is exactly this project's root, asked of Orca and never taken from the caller's
+ * environment. The match is exact because `ahub <peer>` compares the terminal's worktree root with the project root by
+ * equality and refuses on a difference: a terminal opened in any other worktree would only fail later. The refusal names
+ * the cause and the next step and carries no path; Orca's own words go in `detail` for the hub log.
+ */
+export async function resolveStartTerminalWorktree(projectRoot: string, options?: CommandRunner | TerminalRecoveryOptions): Promise<{ ok: true; worktreeId: string } | { ok: false; why: string; detail?: string }> {
+  const config = normalizeOptions(options);
+  let value: unknown;
+  try { value = await run(config.runner, ["worktree", "list", "--limit", String(WORKTREE_LIST_LIMIT), "--json"]); }
+  catch (error) {
+    return { ok: false, why: "Orca could not list its worktrees, so no terminal was opened. Check that Orca is running (orca worktree list), then start the peer again, or set terminal.open", detail: (error as Error).message };
+  }
+  const payload = responseResult(value);
+  const rows = Array.isArray(payload.worktrees) ? payload.worktrees.map(object) : [];
+  const matches = rows.filter((row) => row.isArchived !== true && rootMatches(row.path, projectRoot) && typeof row.id === "string" && row.id.length > 0);
+  if (matches.length === 1) return { ok: true, worktreeId: String(matches[0]!.id) };
+  if (matches.length > 1) return { ok: false, why: "more than one Orca worktree has this project's root, so no terminal was opened. Archive the extra entry in Orca, or set terminal.open" };
+  if (payload.truncated === true) return { ok: false, why: `Orca's worktree list was cut off at ${WORKTREE_LIST_LIMIT} rows before one with this project's root appeared, so no terminal was opened. Archive worktrees you no longer use in Orca, or set terminal.open` };
+  return { ok: false, why: "Orca has no worktree whose root is this project's root, so no terminal was opened. Open this project in Orca (add it as a repository or worktree), then start the peer again, or set terminal.open" };
 }
 
 /** #269: a new Orca terminal running `command` (a complete, already quoted command line); the terminal's handle. */
@@ -791,7 +815,7 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
 }
 
 /**
- * One bounded Orca wait. Orca 1.4.223 answers a wait that timed out with exit 1 and `{"ok":false,"error":{"code":"timeout"}}`:
+ * One bounded Orca wait. Orca 1.4.223 and, rechecked read-only, 1.4.245 (docs/verification/2026-11-02-orca-1.4.245-cli-contract.md) answer a wait that timed out with exit 1 and `{"ok":false,"error":{"code":"timeout"}}`:
  * that is "not satisfied", not a failure. Any other failure still throws.
  */
 async function waitSatisfied(runner: CommandRunner, handle: string, timeoutMs: number): Promise<boolean> {