@staix/agent-hub 0.20.0 → 0.22.0

package/src/cli/main.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env bun
-import { conductorOperation, OPERATIONAL_PERSON_GUIDANCE } from "../hub/operational-authority.ts";
+import { assertConductorOperationLocal, authorizeConductorOperation, authorizeConductorLaunch, issueConductorOperation, preflightConductorRecovery, retireConductorOperation } from "./conductor-recovery.ts";
+import { conductorLocalOperation, conductorOperation, OPERATIONAL_PERSON_GUIDANCE } from "../hub/operational-authority.ts";
+import { sayRecipients } from "./say-input.ts";
 import type { DeliverableRow } from "../hub/tasks.ts";
 import { kimiSourceRow } from "../hub/budget-notes.ts";
 import { hubGitSync, hubGitEnv } from "../hub/git.ts";
@@ -20,23 +22,28 @@ import { supportsBoardReleaseFilter, supportsBoardColumnMetadata } from "./board
 import { matchesPolicy } from "../hub/path-policy.ts";
 import { projectedDiff } from "../hub/projected-diff.ts";
 import { TextProjections } from "../hub/text-projection.ts";
+import { fetchSourceUrl, MAX_SOURCE_BYTES, publicSourceView, screenRegistration, SourceRegistry, validSourceId, type SourceMeta } from "../hub/sources.ts";
+import { renderSourceAdd, renderSourceList } from "./source-output.ts";
+import { renderScheduleChange, renderScheduleList, renderScheduleRun } from "./schedule-output.ts";
+import { renderIntake, renderIntakeChange } from "./intake-output.ts";
+import { renderLearnChange, renderLearnList } from "./learn-output.ts";
 import { terminalText } from "./console-state.ts";
 import { parseSettingsEditArgs, runSettingsEdit, SETTINGS_EDIT_USAGE } from "./settings-edit.ts";
 import { petView, readPet, renderPet } from "./pet.ts";
 import { startPetWindow, closePetWindow } from "../pet/window.ts";
 import { loadPetConfig, savePetPalette } from "./pet-config.ts";
-import { profileName, projectProfile, resolveProfile } from "../hub/profiles.ts";
+import { projectProfile, resolveProfile } from "../hub/profiles.ts";
 import { catalogAssignments, loadRoleCatalog, selectedRoles } from "../hub/roles.ts";
 import { attachWatch } from "./watch.ts";
 import { verifiedJcodeCommand } from "../adapters/jcode.ts";
 import { configureJcodeMcp, jcodeExtraMcpServers } from "./jcode-mcp.ts";
 import { qwenSessionId } from "../hub/crash.ts";
 import { isPermissionMode } from "../hub/permission-mode.ts";
-import { parseSettingText, settingDef, settingText, type SettingRow } from "../hub/settings.ts";
+import { parseSettingText, settingDef, settingText, undoableDef, type SettingRow } from "../hub/settings.ts";
 import { startModeOf } from "../hub/start-mode.ts";
-import { OVERLAY_FILE, parseOverlay, parseRouting, routingText, type Routing, type RoutingOverlay } from "../hub/routing.ts";
+import { currentRouting, OVERLAY_FILE, parseOverlay, parseRouting, routingText, type Routing, type RoutingOverlay } from "../hub/routing.ts";
 import { spawn, spawnSync } from "node:child_process";
-import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { chmodSync, closeSync, constants, existsSync, fstatSync, openSync, readFileSync, readSync, renameSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
@@ -59,8 +66,8 @@ import { VERSION } from "../version.ts";
 import { freeText } from "./free-text.ts";
 import { createInterface } from "node:readline/promises";
 import { createInterface as lineReader } from "node:readline";
-import { activeOperation, assertLifecycleAvailable, operationIdPattern, readOperation, recoveryLock, recoveryRunner, signedRunner, stopSignedRunner, supportsAction } from "../hub/recovery-store.ts";
-import { childEnv } from "../hub/child-process.ts";
+import { activeOperation, assertLifecycleAvailable, operationIdPattern, readOperation, writeOperation, recoveryLock, recoveryRunner, signedRunner, stopSignedRunner, supportsAction } from "../hub/recovery-store.ts";
+import { childEnv, personEnv } from "../hub/child-process.ts";
 import { abortRecovery, createOperation, disposeRecovery, recordRecoveryDelegation, repairedFreshSession, reattachRecovery, liveProjects, nextChoices, nextActionsText, publicOperation, recoveryCommand, registeredProjects, runRecovery, type RecoveryOperation, type Inspection } from "./upgrade.ts";
 import { endPlannedPeer, makeRecoveryDriver, makeUpgradePlan, preserveSource } from "./upgrade-runtime.ts";
 import { exactVersion, latestRelease, newerVersion } from "./recovery-package.ts";
@@ -93,10 +100,10 @@ import { agentShellCause, classifyPeerCommand, cliCommandLabel, detectCliIdentit
 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, renderBacklog, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, renderUsage, renderLimits, renderTotal, type DoctorCheck } from "./output.ts";
+import { outputWidth, renderRoster, renderStatus, renderBoard, renderBacklog, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderOrphanCleanup, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, renderUsage, renderLimits, renderTotal, type DoctorCheck } from "./output.ts";
 import { renderHelp, configuredAcpHelp } from "./help.ts";
 import { renderBacklogResult, renderGroom, renderReleaseChange, renderReleaseList, renderReleaseNew, renderReleaseShow, renderTaskCancel, renderTaskShow } from "./task-output.ts";
-import { renderAuthorization, renderSdlcCosts, renderSdlcExplain, renderSdlcMetrics, renderSdlcQueue, renderSdlcRelease, renderSdlcStatus } from "./sdlc-output.ts";
+import { renderAuthorization, renderSdlcCosts, renderSdlcExplain, renderSdlcMerge, renderSdlcMetrics, renderSdlcQueue, renderSdlcRelease, renderSdlcStatus } from "./sdlc-output.ts";
 import { renderTailEvent } from "./tail-render.ts";
 import { archiveProblem, archiveState, damagedState, failureText, MANIFEST, planReset, resetLines, resetRuntime, startState, type ResetPlan } from "./reset.ts";
 
@@ -160,7 +167,7 @@ function localDeclarations(): { scope: Pick<InstanceRoleConfig, "instances" | "c
   catch (error) { return { scope: { catalog: createProjectAdapterCatalog() }, error: startupDiagnostic(error) }; }
 }
 const projectCatalog = peerConfig.catalog;
-const configuredCommand = !definitionOf(given) && projectCatalog.definitionOf(given)?.permission.genericAcp !== undefined;
+const configuredCommand = !definitionOf(given) && (projectCatalog.definitionOf(given)?.permission.genericAcp !== undefined || peerConfig.declaredExternalInstances?.some(row => row.kind === given) === true);
 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);
@@ -170,7 +177,7 @@ let nativeSelection: ReturnType<typeof instanceLaunchArguments>;
 try {
   declaredInstances = needsInstances || configuredCommand ? peerConfig.instances : undefined;
   if (configuredCommand && !(rest.length === 1 && ["--help", "-h"].includes(rest[0]!))) {
-    const selection = parseConfiguredAcpArguments(given, rest, projectCatalog, declaredInstances);
+    const selection = parseConfiguredAcpArguments(given, rest, projectCatalog, declaredInstances, peerConfig.declaredExternalInstances);
     nativeSelection = { ...(selection.peer !== given ? { instance: selection.peer } : {}), args: [...rest] };
   } else nativeSelection = instanceLaunchArguments(given, rest, declaredInstances);
 } catch (error) { fail(startupDiagnostic(error)); }
@@ -207,11 +214,30 @@ const stateDir = selected.stateDir;
 var operationalAuditReady=false, operationalRefusalRecorded=false;
 const caller = declaredInstances ? detectCliIdentity(process.env, declaredInstances) : unboundCaller;
 const commandLabel = cliCommandLabel(cmd, args, projectCatalog);
-const commandAccess = classifyPeerCommand(cmd, args, projectCatalog);
+let commandAccess = classifyPeerCommand(cmd, args, projectCatalog);
+const continuationPeer = process.env.AGENTHUB_RECOVERY_CONDUCTOR;
+const continuationId = process.env.AGENTHUB_RECOVERY_OPERATION;
+let recoveryLauncher = false, recoveryRunnerContinuation = false;
+let recoveryLauncherCurrent: (() => void) | undefined;
+if (continuationPeer !== undefined) {
+  if (caller.role !== "tools" || caller.peer !== continuationPeer || !continuationId || !operationIdPattern.test(continuationId) || liveTest) fail("conductor recovery authority unavailable; the person runs it in ahub console or a terminal");
+  let operation: RecoveryOperation;
+  try { operation = readOperation<RecoveryOperation>(continuationId); }
+  catch { fail("conductor recovery authority unavailable; the person runs it in ahub console or a terminal"); }
+  if (!operation || operation.id !== continuationId || typeof operation.sourceRoot !== "string") fail("conductor recovery authority unavailable; the person runs it in ahub console or a terminal");
+  if (cmd === "recovery-run" && args.length === 1 && args[0] === continuationId) {
+    await authorizeConductorOperation(operation, continuationPeer);
+    if (realPath(operation.sourceRoot) !== realPath(resolve(import.meta.dir, "../.."))) fail("conductor recovery authority unavailable; the person runs it in ahub console or a terminal");
+    recoveryRunnerContinuation = true; commandAccess = "conductor";
+  } else if (process.env.AGENTHUB_RECOVERY_CONTINUATION === continuationId) {
+    await authorizeConductorLaunch(operation, continuationPeer, cwd, resolve(import.meta.dir, "../.."), cmd, args); recoveryLauncher = true; recoveryLauncherCurrent = () => assertConductorOperationLocal(operation, continuationPeer);
+  } else fail("conductor recovery authority unavailable; the person runs it in ahub console or a terminal");
+}
+const conductorPeer = !liveTest && caller.role === "tools" && (recoveryRunnerContinuation || ["restart", "upgrade", "recovery"].includes(cmd) && commandAccess === "conductor") ? caller.peer : undefined;
 // 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;
-const identity = delegatedPeer ? { role: "console" as const } : caller;
+const identity = delegatedPeer || recoveryLauncher ? { role: "console" as const } : caller;
 operationalAuditReady=identity.role==="tools" && commandAccess==="conductor" && conductorOperation(cmd,args)!==undefined;
 function audit(outcome: "run" | "refused" | "invalid"): void {
   if (caller.role === "console") return;
@@ -576,13 +602,13 @@ function printRecoveryStatus(op: RecoveryOperation, message: string, presentatio
   }
 }
 async function recoveryEndInspection(op: RecoveryOperation): Promise<Record<string, Inspection | undefined>> {
-  const driver = makeRecoveryDriver(undefined, delegatedPeer);
+  const driver = makeRecoveryDriver(undefined, delegatedPeer, undefined, conductorPeer);
   return Object.fromEntries(await Promise.all(op.plan.projects.map(async planned => [planned.project.id, await driver.inspect(planned.project).catch(() => undefined)] as const)));
 }
 
 function spawnRecovery(operation: RecoveryOperation, quiet = false, presentation?: RecoveryPresentationOptions): void {
   const child = spawn(process.execPath, [join(operation.sourceRoot, "src/cli/main.js"), ...liveTestArgs, "recovery-run", operation.id], {
-    cwd, detached: true, stdio: "ignore", env: { ...process.env, AGENTHUB_RECOVERY_OPERATION: operation.id },
+    cwd, detached: true, stdio: "ignore", env: { ...process.env, AGENTHUB_RECOVERY_OPERATION: operation.id, ...(conductorPeer ? { AGENTHUB_PEER_ID: conductorPeer, AGENTHUB_RECOVERY_CONDUCTOR: conductorPeer } : {}) },
   });
   child.on("error", () => console.error(`runner launch failed; use ${recoveryCommand(operation, "resume")}`));
   child.unref();
@@ -657,7 +683,7 @@ function upgradeHost(kind: "restart" | "upgrade", version: string): UpgradeHost
     lock: recoveryLock,
     read: (id) => readOperation<RecoveryOperation>(id),
     runner: recoveryRunner,
-    live: (op) => liveProjects(op, makeRecoveryDriver(undefined, delegatedPeer).inspect),
+    live: (op) => liveProjects(op, makeRecoveryDriver(undefined, delegatedPeer, undefined, conductorPeer).inspect),
     endInspection: recoveryEndInspection,
     endPeer: (planned, peer) => endPlannedPeer(planned, peer),
     runnerStoppable: (id) => signedRunner(id) !== undefined,
@@ -684,6 +710,7 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   // Before the value reaches a package spec or the registry: a range such as 0.13 would resolve to whatever matches.
   if (to !== undefined) { try { exactVersion(to); } catch (error) { fail((error as Error).message); } }
   // An older CLI must not coordinate a newer target (docs/operations.md): the target's own coordinator takes over.
+  if (conductorPeer && kind === "upgrade" && newerVersion(to!, VERSION)) fail("a supporting target coordinator is required; the person runs it in ahub console or a terminal");
   if (kind === "upgrade" && newerVersion(to!, VERSION) && process.env.AGENTHUB_UPGRADE_HANDOVER !== "1") {
     const argv = ["x", "--package", `@staix/agent-hub@${to}`, "ahub", ...liveTestArgs, "upgrade", "--to", to!, ...rest, ...display.flags, ...(dry && !rest.includes("--dry-run") ? ["--dry-run"] : [])];
     console.error(`ahub: ${to} is newer than this CLI (${VERSION}), so its own coordinator runs the upgrade: bun ${argv.join(" ")}`);
@@ -703,7 +730,8 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   }
   if (kind === "upgrade") console.error("ahub: Kimi now defaults to its own TUI (pull-only) in projects without peers.kimi.start_mode. To keep ACP: ahub settings set peers.kimi.start_mode headless");
   if (interactive) return onTerminal((io) => planScreen(upgradeHost(kind, to ?? VERSION), io), display.options);
-  const plan = await makeUpgradePlan(kind, to ?? VERSION, kind === "restart" ? cwd : undefined);
+  const plan = await makeUpgradePlan(kind, to ?? VERSION, kind === "restart" ? cwd : undefined, undefined, conductorPeer);
+  if (conductorPeer) await preflightConductorRecovery(plan, conductorPeer);
   const jsonApply = display.json && yes && !dry;
   // #814: a person reading a pipe or a dry run gets the plan screen's rows, with every blocker, reconnect-only session and
   // fresh start in them. `--json` keeps the document and the stderr lines (#206) exactly as they were.
@@ -715,7 +743,7 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   const blockers = [...plan.blockers, ...plan.projects.flatMap((p) => p.blockers.map((b) => `${p.project.id}: ${b}`))];
   if (display.json) for (const blocker of blockers) console.error(`ahub: blocker: ${blocker}`);
   if (dry) return;
-  if (blockers.length) { if (jsonApply) console.log(JSON.stringify(plan, null, 2)); fail("plan has blockers; no runtime was changed"); }
+  if (blockers.length) { if (jsonApply) console.log(JSON.stringify(plan, null, 2)); fail(conductorPeer ? "conductor recovery cannot prove this plan; no runtime was changed; the person runs it in ahub console or a terminal" : "plan has blockers; no runtime was changed"); }
   assertLifecycleAvailable();
   if (!yes) {
     if (!process.stdin.isTTY) fail("review --dry-run and use --yes in non-interactive sessions");
@@ -724,10 +752,21 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
       if (!/^(y|yes)$/i.test((await rl.question("Apply this project list and restore its sessions? [y/N] ")).trim())) return;
     } finally { rl.close(); }
   }
-  const current = await makeUpgradePlan(kind, plan.version, kind === "restart" ? cwd : undefined);
+  const current = await makeUpgradePlan(kind, plan.version, kind === "restart" ? cwd : undefined, undefined, conductorPeer);
   if (current.fingerprint !== plan.fingerprint) fail("plan changed during review; run the command again");
+  const routingDefaults = conductorPeer ? await preflightConductorRecovery(plan, conductorPeer) : undefined;
   const sourceRoot = preserveSource(plan);
-  const operation = createOperation(plan, sourceRoot, undefined, delegatedPeer ? { peer: delegatedPeer, command: kind } : undefined);
+  let operation: RecoveryOperation;
+  if (conductorPeer) {
+    const id = randomUUID();
+    const pending: RecoveryOperation = { schema: 1, id, plan, sourceRoot, createdAt: Date.now(), updatedAt: Date.now(), phase: "pending", step: "stage", ...(routingDefaults ? { conductorRoutingDefaults: routingDefaults } : {}), projects: plan.projects.map(row => ({ id: row.project.id, phase: "pending", terminals: {} })) };
+    const target = await makeRecoveryDriver().stage(pending);
+    pending.targetRoot = target.root; pending.targetDigest = target.digest; pending.targetFeatures = target.targetFeatures;
+    await issueConductorOperation(pending, conductorPeer);
+    operation = createOperation(plan, sourceRoot, undefined, { peer: conductorPeer, command: kind }, id);
+    operation.targetRoot = target.root; operation.targetDigest = target.digest; operation.targetFeatures = target.targetFeatures; operation.conductorRoutingDefaults = routingDefaults;
+    writeOperation(id, operation);
+  } else operation = createOperation(plan, sourceRoot, undefined, delegatedPeer ? { peer: delegatedPeer, command: kind } : undefined);
   if (display.json) { spawnRecovery(operation, true); console.log(JSON.stringify(publicOperation(operation), null, 2)); }
   else spawnRecovery(operation, false, humanRecovery(false) ? display.options : undefined);
 }
@@ -741,6 +780,40 @@ function parseRecoveryReattach(argv: readonly string[]): { id: string; peer: Ter
   return { id: argv[1]!, peer: argv[2] as TerminalPeer };
 }
 
+/** #248: `ahub bench run` arguments, checked before anything runs (#933: also before the conductor's admission writes its audit row). */
+function benchRunArgs(rest: string[]) {
+  const { one, many, rest: positional } = takeFlags(rest, ["--arm", "--repeat", "--tasks", "--memory"], ["--addon"]);
+  if (one["--memory"] !== undefined && !(MEMORY_MODES as readonly string[]).includes(one["--memory"])) fail(`--memory takes ${MEMORY_MODES.join(", ")}`);
+  // #248: `--addon ripwire=off` declares the arm's add-on state; the run refuses peers that do not match it.
+  const addons: Partial<Record<AddonName, "on" | "off">> = {};
+  for (const spec of many["--addon"] ?? []) {
+    const [name, state] = spec.split("=");
+    if (!name || !isAddon(name) || (state !== "on" && state !== "off") || addons[name]) fail(`--addon takes <name>=on|off once per add-on, name one of ${ADDONS.join(", ")}`);
+    addons[name] = state;
+  }
+  const suite = positional[0];
+  const repeat = one["--repeat"] === undefined ? 1 : Number(one["--repeat"]);
+  if (!suite || positional.length !== 1 || !one["--arm"]?.trim() || !Number.isSafeInteger(repeat) || repeat < 1 || repeat > 100) {
+    fail("usage: ahub bench run <suite.json> --arm <label> [--repeat 1..100] [--tasks a,b] [--addon <name>=on|off]... [--memory off|claude-mem|native|both]");
+  }
+  return { one, addons, suite, repeat };
+}
+/** Another project is `ahub --project <dir> research`; anything unknown is refused rather than ignored. */
+function researchArgs(): void {
+  const sub = args[0], flags = new Set(["--all", "--json", "--since", "--format"]), valued = new Set(["--since", "--format"]);
+  for (let i = sub === "export" || sub === "backfill" || sub === "addons" ? 1 : 0; i < args.length; i++) {
+    if (!flags.has(args[i]!)) fail(`ahub research: unknown argument ${args[i]} (another project: ahub --project <dir> research)`);
+    if (valued.has(args[i]!)) i++;
+  }
+}
+const SOURCE_USAGE = "usage: ahub source add <path|url> [--json] [--color=auto|always|never] | list [--json] [--color=auto|always|never]";
+/** #933: a local conductor form's argument check, run before the `admit` handshake so a usage error leaves no admitted row. */
+const LOCAL_OPERATION_ARGS: Record<string, () => void> = {
+  "bench run": () => { benchRunArgs(args.filter(arg => arg !== "--json").slice(1)); },
+  "research backfill": researchArgs,
+  "source add": () => { const operands = args.filter(arg => arg !== "--json" && arg !== "--full" && !arg.startsWith("--color=")); if (operands[0] !== "add" || operands.length !== 2 || !operands[1]) fail(SOURCE_USAGE); },
+};
+
 const commands: Record<string, () => Promise<void> | void> = {
   upgrade: () => upgrade("upgrade"),
   restart: () => upgrade("restart"),
@@ -778,7 +851,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       const result = await reattachRecovery(selected.id, selected.peer, makeRecoveryDriver());
       if (display.json) { console.log(JSON.stringify(publicOperation(result), null, 2)); return; }
       printRecovery(renderOperation(result, undefined, display.options));
-      const live = await liveProjects(result, makeRecoveryDriver(undefined, delegatedPeer).inspect);
+      const live = await liveProjects(result, makeRecoveryDriver(undefined, delegatedPeer, undefined, conductorPeer).inspect);
       printRecovery(renderBlocked(result, nextChoices(result, undefined, live), display.options));
       return;
     }
@@ -805,15 +878,20 @@ const commands: Record<string, () => Promise<void> | void> = {
         audit("refused"); fail(LIVE_TEST_PERSON_REFUSAL);
       }
     }
+    if (conductorPeer) {
+      if (operation.id !== id) fail("conductor recovery authority unavailable; the person runs it in ahub console or a terminal");
+      await authorizeConductorOperation(operation, conductorPeer);
+    }
     const runner = recoveryRunner(id);
     if (action === "status") {
       // #215: abort and resume are offered by what the open sources show, read as the runner's errors read them.
-      const live = runner ? {} : await liveProjects(operation, makeRecoveryDriver(undefined, delegatedPeer).inspect);
+      const live = runner ? {} : await liveProjects(operation, makeRecoveryDriver(undefined, delegatedPeer, undefined, conductorPeer).inspect);
       if (display.json) console.log(JSON.stringify(publicOperation(operation, runner, live), null, 2));
       else printRecovery(renderRecoveryStatus(operation, runner, nextChoices(operation, runner, live), display.options));
     }
     else if (action === "abort") {
-      await abortRecovery(id, makeRecoveryDriver(undefined, delegatedPeer));
+      await abortRecovery(id, makeRecoveryDriver(undefined, delegatedPeer, undefined, conductorPeer));
+      if (conductorPeer) retireConductorOperation(readOperation<RecoveryOperation>(id), conductorPeer);
       if (display.json) console.log(JSON.stringify(publicOperation(readOperation<RecoveryOperation>(id)), null, 2));
       else console.log("preflight cancelled; no committed transition was rolled back");
     }
@@ -823,7 +901,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       const stop = flags.length === 1 && flags[0] === "--stop-and-archive";
       const reason = one["--reason"]?.trim() ?? "";
       if (!reason || reason.length > 500 || (flags.length && !stop) || stop === !!one["--fresh-session"]) fail(usage);
-      const result = await disposeRecovery(id, stop ? { stop: true } : { fresh: one["--fresh-session"]! }, reason, makeRecoveryDriver(undefined, delegatedPeer));
+      const result = await disposeRecovery(id, stop ? { stop: true } : { fresh: one["--fresh-session"]! }, reason, makeRecoveryDriver(undefined, delegatedPeer, undefined, conductorPeer));
       if (!stop) {
         if (display.json) { console.log(JSON.stringify(publicOperation(result), null, 2)); return spawnRecovery(result, true); }
         console.log(`${one["--fresh-session"]}: a fresh session is accepted and the lost one is recorded; resuming`);
@@ -834,7 +912,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     else if (["completed", "cancelled"].includes(operation.phase)) console.log(display.json ? JSON.stringify(publicOperation(operation, runner), null, 2) : `recovery is already ${operation.phase}`);
     // #215: an operation being abandoned is never resumed, whichever coordinator started it (an older one would).
-    else if (operation.disposition) fail(`a stop-and-archive of this operation is partway; nothing was resumed; ${nextActionsText(operation, await liveProjects(operation, makeRecoveryDriver(undefined, delegatedPeer).inspect))}`);
+    else if (operation.disposition) fail(`a stop-and-archive of this operation is partway; nothing was resumed; ${nextActionsText(operation, await liveProjects(operation, makeRecoveryDriver(undefined, delegatedPeer, undefined, conductorPeer).inspect))}`);
     else if (runner === "unknown") {
       if (display.json) console.log(JSON.stringify(publicOperation(operation, runner), null, 2));
       else if (humanRecovery(false)) printRecoveryStatus(operation, "Runner ownership is unknown; nothing was started.", display.options);
@@ -853,8 +931,9 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
   "recovery-run": async () => {
     if (args.length !== 1 || process.env.AGENTHUB_RECOVERY_OPERATION !== args[0]) fail("recovery-run is an internal command");
-    const result = await runRecovery(args[0]!, makeRecoveryDriver(undefined, delegatedPeer));
+    const result = await runRecovery(args[0]!, makeRecoveryDriver(undefined, delegatedPeer, undefined, conductorPeer));
     if (result.phase !== "completed") process.exitCode = 1;
+    else if (conductorPeer) retireConductorOperation(result, conductorPeer);
   },
   help: () => {
     const color = resolveColor(undefined, { isTTY: !!process.stdout.isTTY, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR }) === true;
@@ -923,10 +1002,11 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   setup: async () => {
+    recoveryLauncherCurrent?.();
     assertLifecycleAvailable();
     const root = join(import.meta.dir, "..", "..");
     const state = () => {
-      const out = (argv: string[]) => spawnSync("claude", argv, { encoding: "utf8" }).stdout ?? "";
+      const out = (argv: string[]) => { recoveryLauncherCurrent?.(); const result = spawnSync("claude", argv, { encoding: "utf8", ...(recoveryLauncherCurrent ? { timeout: 30_000 } : {}) }); recoveryLauncherCurrent?.(); return result.stdout ?? ""; };
       return nextStep(parseList<InstalledPlugin>(out(["plugin", "list", "--json"])), parseList<Marketplace>(out(["plugin", "marketplace", "list", "--json"])), root);
     };
     let step = state();
@@ -943,17 +1023,21 @@ const commands: Record<string, () => Promise<void> | void> = {
       }
       for (let i = 0; step && i < 6; i++, step = state()) {
         console.log(`> ${step.argv.join(" ")}   (${step.why})`);
-        if (spawnSync(step.argv[0]!, step.argv.slice(1), { stdio: "inherit" }).status !== 0) fail(`"${step.argv.join(" ")}" failed; nothing after it was run`);
+        recoveryLauncherCurrent?.();
+        if (spawnSync(step.argv[0]!, step.argv.slice(1), { stdio: "inherit", ...(recoveryLauncherCurrent ? { timeout: 30_000 } : {}) }).status !== 0) fail(`"${step.argv.join(" ")}" failed; nothing after it was run`);
+        recoveryLauncherCurrent?.();
       }
       if (step) fail(`still not done after 6 steps; next would be: ${step.argv.join(" ")}`);
     }
-    await commands.doctor!();
+    if (recoveryLauncherCurrent) recoveryLauncherCurrent();
+    else await commands.doctor!();
   },
 
   init: () => {
     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] [--shadow] [--release-guard] [--dry-run --json]");
-    const requestedProfile = flags.one["--profile"] === undefined ? undefined : profileName(flags.one["--profile"]);
+    if (flags.rest.length) fail("usage: ahub init [--profile dev|research|writing|general|<pack>] [--shadow] [--release-guard] [--dry-run --json]");
+    // 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"];
     if (args.includes("--dry-run")) {
       const plan = planInit(cwd, requestedProfile, args.includes("--shadow"), args.includes("--release-guard"));
       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");
@@ -983,8 +1067,9 @@ const commands: Record<string, () => Promise<void> | void> = {
   up: async () => {
     const unattended = unattendedEnv || args.includes("--unattended");
     if (unattended) console.error(UNATTENDED_WARNING);
-    const status = await startProject(registeredProject(), { unattended, liveTest });
+    const status = await startProject(registeredProject(), { unattended, liveTest, ...(recoveryLauncherCurrent ? { current: recoveryLauncherCurrent, env: { ...personEnv(process.env), AGENTHUB_RECOVERY_OPERATION: continuationId, AGENTHUB_PEER_ID: continuationPeer, AGENTHUB_RECOVERY_CONDUCTOR: continuationPeer, AGENTHUB_RECOVERY_CONTINUATION: continuationId } } : {}) });
     console.log(`ahub up (ws://127.0.0.1:${status.controlPort}), state in ${stateDir}`);
+    if (recoveryLauncherCurrent) { recoveryLauncherCurrent(); return; }
     try { if (loadPetConfig(cwd).window) console.log(await startPetWindow(stateDir, cwd)); }
     catch { console.error("Pet window was not started; run ahub pet --window to inspect it."); }
     if (process.stdin.isTTY && process.stdout.isTTY && !args.includes("--no-console")) await runConsole({ client: await connect(), cwd, stateDir, liveTest });
@@ -1048,9 +1133,10 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   say: async () => {
-    const lead = args.findIndex((a) => !/^@[a-z][a-z0-9-]*$/.test(a)); // only leading @tokens are recipients
-    const to = args.slice(0, lead === -1 ? args.length : lead).map((a) => a.slice(1));
-    const body = lead === -1 ? "" : freeText(args.slice(lead), "ahub say [@peer ...] <text>");
+    let addressed: ReturnType<typeof sayRecipients>;
+    try { addressed = sayRecipients(args); } catch (error) { return fail((error as Error).message); }
+    const { to, text } = addressed;
+    const body = text.length ? freeText(text, "ahub say [@peer ...] <text>") : "";
     const hub = await connect();
     const res = await hub.request({ t: "send", body, to });
     hub.close();
@@ -1249,8 +1335,161 @@ const commands: Record<string, () => Promise<void> | void> = {
     return shown(renderReleaseChange)(taskOp("release_change", { name, revision: Number(revision), fields }));
   },
 
+  smoke: async () => {
+    // Log every live-test invocation, including syntax/target refusals; native output never joins the audit.
+    if (liveTest && caller.role === "console") {
+      try { recordCliAudit(stateDir, "user", commandLabel, "run"); }
+      catch { return fail("smoke audit unavailable; nothing was executed"); }
+    }
+    const options = outputOptions();
+    const operands = args.filter(arg => arg !== "--json");
+    const usage = "usage: ahub --live-test smoke run qwen-dual-output --project-id <id> --receipt <file.json> [--timeout-ms <100..120000>] [--json]";
+    const values = new Map<string, string>();
+    if (operands[0] !== "run" || operands[1] !== "qwen-dual-output") return fail(usage);
+    for (let n = 2; n < operands.length; n += 2) {
+      const key = operands[n], value = operands[n + 1];
+      if (!key || !["--project-id", "--receipt", "--timeout-ms"].includes(key) || !value || value.startsWith("--") || values.has(key)) return fail(usage);
+      values.set(key, value);
+    }
+    if (!values.has("--project-id") || !values.has("--receipt")) return fail(usage);
+    const home = process.env.AGENTHUB_HOME;
+    if (!liveTest || !home) return fail("smoke target refused");
+    const { validateSmokeTarget } = await import("./smoke-target.ts");
+    const { runSmoke } = await import("./smoke-run.ts");
+    const project = registeredProjects(home).find(project => project.root === cwd && project.stateDir === stateDir);
+    if (!project) return fail("smoke target refused");
+    // Keep path spelling for the guard: project selection above canonicalizes symlinks for ordinary CLI commands.
+    const smokeCwd = selector && selector !== project.id ? resolve(invokedFrom, selector) : cwd;
+    const checked = validateSmokeTarget({ cwd: smokeCwd, hubHome: home, project, expectedProjectId: values.get("--project-id")!, liveTest });
+    const target = { ...checked, check: () => { checked.check(); assertDelegatedAuditConsumer(); } };
+    const abort = new AbortController();
+    const interrupted = () => abort.abort();
+    process.on("SIGINT", interrupted); process.on("SIGTERM", interrupted);
+    try {
+      const result = await runSmoke(target, { leg: "qwen-dual-output", receipt: values.get("--receipt")!, timeoutMs: Number(values.get("--timeout-ms") ?? "60000"), signal: abort.signal });
+      process.exitCode = result.outcome === "passed" ? 0 : 1;
+      if (options.json) return console.log(JSON.stringify(result));
+      console.log(`smoke ${result.outcome} (${result.reason}): ${result.counts.submits} submits, ${result.counts.stops} stops; cleanup ${result.checks.cleaned ? "confirmed" : "unconfirmed"}`);
+    } finally { process.removeListener("SIGINT", interrupted); process.removeListener("SIGTERM", interrupted); }
+  },
+
+  room: async () => {
+    if (liveTest && !["list", "status"].includes(args[0] ?? "")) fail(LIVE_TEST_PERSON_REFUSAL);
+    const { runRoomCommand, roomCommandError } = await import("./room.ts");
+    const hub = await connect();
+    try { await runRoomCommand(args, message => hub.request(message)); }
+    catch (error) { fail(roomCommandError(error)); }
+    finally { hub.close(); }
+  },
+
+  broker: async () => {
+    const { runBrokerCommand, brokerCommandError } = await import("./broker.ts");
+    try { await runBrokerCommand(args, stateDir); }
+    catch (error) { fail(brokerCommandError(error)); }
+  },
+
+  source: async () => {
+    // #508: the source registry. `add` is the person's or the configured conductor's (#933: admitted and audited by the daemon before this runs) and local:
+    // it reads and writes the hub state dir directly and needs no daemon. A URL is fetched here, once, by this process; no hub tool or agent ever fetches one.
+    const options = outputOptions();
+    const operands = args.filter(arg => arg !== "--json" && arg !== "--full" && !arg.startsWith("--color="));
+    const [sub, ...rest] = operands;
+    const registry = new SourceRegistry(stateDir);
+    if (sub === "list" && rest.length === 0) {
+      const rows = registry.list();
+      if (options.json) return console.log(JSON.stringify(rows, null, 2));
+      return printOutput(renderSourceList(rows, options.columns, Date.now()), options.color);
+    }
+    if (sub !== "add" || rest.length !== 1 || !rest[0]) return fail(SOURCE_USAGE);
+    const target = rest[0], config = projectConfig();
+    const isUrl = /^[a-z][a-z0-9+.-]*:\/\//i.test(target);
+    let bytes: Buffer, origin: string, kind: "file" | "url", absolute: string | undefined;
+    try {
+      if (isUrl) {
+        const fetched = await fetchSourceUrl(target);
+        bytes = fetched.bytes; origin = fetched.finalUrl; kind = "url";
+      } else {
+        absolute = realPath(resolve(cwd, target));
+        const fd = openSync(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+          const st = fstatSync(fd);
+          if (!st.isFile()) throw new Error("not a regular file");
+          if (st.size > MAX_SOURCE_BYTES) throw new Error(`file is ${st.size} bytes, over the ${MAX_SOURCE_BYTES} byte cap (MAX_PROJECTION_INPUT); nothing was stored`);
+          bytes = Buffer.alloc(st.size); let got = 0;
+          while (got < bytes.length) { const n = readSync(fd, bytes, got, bytes.length - got, got); if (!n) break; got += n; }
+          if (got !== st.size) throw new Error("the file changed while it was read");
+        } finally { closeSync(fd); }
+        origin = absolute; kind = "file";
+      }
+    } catch (error) { return fail(`cannot register ${isUrl ? "that URL" : target}: ${(error as Error).message}`); }
+    const projections = new TextProjections({ cwd, stateDir, config: config.text_projection ?? {}, deny: config.local.deny, readAllow: config.local.read_allow, log: line => console.error(line) });
+    const extension = /\.[A-Za-z0-9]{1,16}$/.exec(isUrl ? new URL(origin).pathname : origin)?.[0] ?? "";
+    const verdict = screenRegistration({ bytes, kind, ...(absolute ? { path: absolute, typedPath: resolve(cwd, target) } : {}) }, {
+      piiPaths: config.pii?.paths ?? [], piiPatterns: currentRouting(cwd).signals.pii_patterns, cwd, matchesPolicy,
+      project: data => extension ? projections.projectBytes(join(cwd, `source${extension.toLowerCase()}`), data)?.text : undefined,
+    });
+    let added;
+    try { added = registry.add({ bytes, kind, origin, private: verdict.private, ...(verdict.text !== undefined ? { text: verdict.text } : {}) }); }
+    catch (error) { return fail(`cannot register ${isUrl ? "that URL" : target}: ${(error as Error).message}`); }
+    const meta = registry.get(added.id);
+    if (!meta) return fail(`the record for ${added.id} cannot be read after it was registered; inspect ${join(stateDir, "sources")}`);
+    const result = { id: added.id, created: added.created, upgraded: added.upgraded, kind: meta.kind, origin: meta.origin, sha256: meta.sha256, bytes: meta.bytes, private: meta.private, text: added.text, reasons: verdict.reasons };
+    if (options.json) return console.log(JSON.stringify(result, null, 2));
+    printOutput(renderSourceAdd(result, options.columns), options.color);
+  },
+
+  schedule: async () => {
+    // #335 (#512 AC3 and AC4): the person's schedule commands; #933: run, pause and resume are the configured conductor's too, admitted and audited by the daemon.
+    // The hub keeps the schedules, their periods and the pause; this process only asks.
+    const split = splitPresentation(args);
+    const present = outputOptions(split.flags); // before any request: an invalid --color must refuse before a mutation is sent
+    const [sub, id, ...extra] = split.operands;
+    const usage = "usage: ahub schedule list | run <id> | pause <id> | resume <id> [--json] [--color=auto|always|never]";
+    if (sub === "list" && id === undefined) return showToolText(data => renderScheduleList(data, present.columns, Date.now()), await taskOp("schedule_list", {}), present);
+    if (!["run", "pause", "resume"].includes(sub ?? "") || !id || extra.length) return fail(usage);
+    if (sub === "run") return showToolText(data => renderScheduleRun(data, present.columns), await taskOp("schedule_run", { id }, false, undefined, 90_000), present);
+    return showToolText(data => renderScheduleChange(sub as "pause" | "resume", data, present.columns, Date.now()), await taskOp(sub === "pause" ? "schedule_pause" : "schedule_resume", { id }), present);
+  },
+
+  learn: async () => {
+    // #514b: the person's verdict on a recurring-criterion candidate (#514a). Person only, end to end: `learn` is a `console` command for an agent shell (classifyPeerCommand has no entry for it, so the
+    // identity layer refuses it before this runs), and the daemon refuses any caller but the person again. `accept` writes ONE key (profile_overrides.review_checklist) to the machine-local
+    // config through the settings writer; nothing in a card's text is written.
+    const split = splitPresentation(args);
+    const present = outputOptions(split.flags); // before any request: an invalid --color must refuse before a mutation is sent
+    const usage = "usage: ahub learn list [--all] | accept <id> | reject <id> [--json] [--color=auto|always|never]";
+    const [sub, ...rest] = split.operands;
+    if (sub === "list" && rest.every(arg => arg === "--all")) {
+      const all = rest.includes("--all");
+      return showToolText(data => renderLearnList(data, present.columns, all), await taskOp("learn_list", { ...(all ? { all: true } : {}) }), present);
+    }
+    const [id, ...extra] = rest;
+    if ((sub !== "accept" && sub !== "reject") || !id || extra.length || !/^[1-9]\d*$/.test(id)) return fail(usage);
+    return showToolText(data => renderLearnChange(sub, data, present.columns), await taskOp(sub === "accept" ? "learn_accept" : "learn_reject", { id: Number(id) }), present);
+  },
+
+  intake: async () => {
+    // #334 (#511a): natural-language intake. Person only, except approve (#933: the configured conductor too, admitted and audited by the daemon).
+    // The request is a draft backlog card that nothing offers until `approve`; the hub, not this process, splits it.
+    const split = splitPresentation(args, { valueFlags: ["--source"] });
+    const present = outputOptions(split.flags); // before any request: an invalid --color must refuse before a mutation is sent
+    const usage = "usage: ahub intake \"<text>\" [--source <id>...] | approve <id> | discard <id> [--json] [--color=auto|always|never]";
+    const sources: string[] = [], words: string[] = [];
+    for (let i = 0; i < split.operands.length; i++) {
+      const arg = split.operands[i]!;
+      if (arg === "--source") { const id = split.operands[++i]; if (!id) return fail("--source needs a source id"); sources.push(id); } else words.push(arg);
+    }
+    const [sub, id] = words;
+    if ((sub === "approve" || sub === "discard") && words.length === 2 && !sources.length) {
+      if (!/^[1-9]\d*$/.test(id!)) return fail(usage);
+      return showToolText(data => renderIntakeChange(sub, data, present.columns), await taskOp(sub === "approve" ? "intake_approve" : "intake_discard", { id: Number(id) }), present);
+    }
+    if (words.length !== 1 || !words[0]!.trim()) return fail(usage);
+    return showToolText(data => renderIntake(data, present.columns), await taskOp("intake", { text: words[0], ...(sources.length ? { sources } : {}) }, false, undefined, 90_000), present);
+  },
+
   deliverables: async () => {
-    // #317: what each task delivered and what a reviewer approved, by id, hash and size (a path only where the PII screen allows it). Person only: the daemon refuses an agent.
+    // #317: what each task delivered and what a reviewer approved, by id, hash and size (a path only where the PII screen allows it). #933: an agent gets only the rows hub_task_show would show it.
     const options = outputOptions();
     const { one, rest } = takeFlags(args, ["--task"], []);
     const approved = rest.includes("--approved"), check = rest.includes("--check");
@@ -1415,14 +1654,19 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     if (sub === "merge") {
       // #786 T1: the guarded merge of one approved task; a person or the configured conductor asks, the daemon re-reads every gate.
-      const flags = takeFlags(args.slice(2), [], []);
+      // #899: the decision prints for a person; `--json` is the same view as a document. The presentation flags are read before the
+      // request, so an invalid --color refuses before a mutation is sent, and they never reach the hub.
+      const split = splitPresentation(args.slice(1)), display = outputOptions(split.flags);
+      const task = Number(split.operands[0]), flags = takeFlags(split.operands.slice(1), [], []);
       const dryRun = flags.rest.includes("--dry-run");
-      if (flags.rest.some(arg => arg !== "--dry-run") || !Number.isSafeInteger(id) || id! <= 0) fail("usage: ahub sdlc merge <task> [--dry-run]");
+      if (flags.rest.some(arg => arg !== "--dry-run") || !Number.isSafeInteger(task) || task <= 0) fail("usage: ahub sdlc merge <task> [--dry-run] [--json]");
       const hub = await connect();
       try {
-        const reply = await hub.request({ t: "sdlc", op: "merge", id, ...(dryRun ? { dryRun: true } : {}) }, 60_000);
+        const reply = await hub.request({ t: "sdlc", op: "merge", id: task, ...(dryRun ? { dryRun: true } : {}) }, 60_000);
         if (!reply.ok) fail(reply.error);
-        console.log(JSON.stringify({ task: reply.task, mode: reply.mode, ran: reply.ran, decision: reply.decision, ...(reply.argv ? { argv: reply.argv } : {}), ...(reply.refused ? { refused: reply.refused } : {}), ...(reply.result ? { result: reply.result } : {}) }, null, 2));
+        const view = { task: reply.task, mode: reply.mode, ran: reply.ran, decision: reply.decision, ...(reply.argv ? { argv: reply.argv } : {}), ...(reply.refused ? { refused: reply.refused } : {}), ...(reply.result ? { result: reply.result } : {}) };
+        if (display.json) console.log(JSON.stringify(view, null, 2));
+        else printOutput(renderSdlcMerge(view, display.columns, Date.now()), display.color);
         if (reply.decision === "refused" || reply.ran && reply.result?.state !== "merged") process.exitCode = 1;
       } finally { hub.close(); }
       return;
@@ -1481,6 +1725,13 @@ const commands: Record<string, () => Promise<void> | void> = {
       if (rest.length !== 1) fail("usage: ahub task show <id> [--json] [--full] [--color=auto|always|never]");
       return shownTask(renderTaskShow)(taskOp("task_show", { id: rest[0] }));
     }
+    if (sub === "claim") {
+      // #901: a person's verdict on one declared plan claim. The claim is named by its 1-based slot and its text is never typed, stored or printed here.
+      const { one, rest: positional } = takeFlags(rest, ["--model", "--model-said"], []);
+      if (positional.length !== 3 || !/^[1-9]\d*$/.test(positional[0]!) || !/^[1-9]\d*$/.test(positional[1]!) || !["supported", "unsupported", "unclear"].includes(positional[2]!)) fail("usage: ahub task claim <id> <slot> <supported|unsupported|unclear> [--model <label>] [--model-said <supported|unsupported|unclear>]");
+      const reply = JSON.parse(await taskOp("claim_verdict", { id: Number(positional[0]), slot: Number(positional[1]), verdict: positional[2], ...(one["--model"] === undefined ? {} : { model: one["--model"] }), ...(one["--model-said"] === undefined ? {} : { modelVerdict: one["--model-said"] }) })) as { task: number; recorded?: { slot: number; verdict: string; model?: string; modelVerdict?: string } };
+      return console.log(`task #${reply.task}: claim ${reply.recorded?.slot} recorded as ${reply.recorded?.verdict}${reply.recorded?.model ? ` (model ${reply.recorded.model}` : ""}${reply.recorded?.modelVerdict ? `${reply.recorded?.model ? ", " : " ("}model said ${reply.recorded.modelVerdict}` : ""}${reply.recorded?.model || reply.recorded?.modelVerdict ? ")" : ""}`);
+    }
     if (sub === "escalate") return console.log(await taskOp("task_escalate", { id: rest[0] }));
     if (sub === "assign") {
       const { one, rest: positional } = takeFlags(rest, ["--role", "--revision"], []);
@@ -1495,14 +1746,18 @@ const commands: Record<string, () => Promise<void> | void> = {
       return console.log(await taskOp("task_unassign", { id: positional[0], role, ...(revision === undefined ? {} : { revision }) }));
     }
     if (sub === "label") {
-      // #247: a person's later verdict on an approved task (the identity gate keeps it human-only), for research records.
+      // #247: a later verdict on an approved task, for research records (#933: an agent's own task only, attributed to it).
       const { one, rest: positional } = takeFlags(rest, ["--created"], []);
       const id = Number(positional[0]), label = positional[1] as Label;
       if (positional.length !== 2 || !/^[1-9]\d*$/.test(positional[0]!) || !Number.isSafeInteger(id) || !(LABELS as readonly string[]).includes(label)) fail(`usage: ahub task label <id> ${LABELS.join("|")} [--created <time from ahub research export>]`);
+      // #933: the daemon checks the current board row only, so an agent never names an earlier task with this id from before a reset.
+      if (identity.role === "tools" && one["--created"] !== undefined) fail("--created names an earlier task with this id; only the person labels it (ahub console or a terminal)");
       const project = researchProject();
+      // #933: an agent labels only its own task, which the daemon checks by role; its record names it, so it never reads as the person's verdict.
+      if (identity.role === "tools") await taskOp("task_label_check", { id });
       let record: TaskRecord;
       try { record = labelTarget(readStores(project.id), readEvents(join(stateDir, "events.jsonl")), id, one["--created"]); } catch (error) { fail((error as Error).message); }
-      appendRecords(project.id, [{ schema: RESEARCH_SCHEMA, kind: "label", project: projectKey(project.id), task: id, createdAt: record!.createdAt!, label, at: new Date().toISOString() }]);
+      appendRecords(project.id, [{ schema: RESEARCH_SCHEMA, kind: "label", project: projectKey(project.id), task: id, createdAt: record!.createdAt!, label, at: new Date().toISOString(), ...(identity.role === "tools" ? { by: identity.peer } : {}) }]);
       return console.log(`task #${id} (approved ${record!.approvedAt}) labelled ${label} in the research records`);
     }
     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>");
@@ -1715,7 +1970,7 @@ 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, settingScope.instances, settingScope.catalog);
+        const view = await request({ t: "settings_get" }), undoDef = undoableDef(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;
@@ -1831,26 +2086,13 @@ const commands: Record<string, () => Promise<void> | void> = {
     const json = args.includes("--json");
     const [sub, ...rest] = args.filter((a) => a !== "--json");
     if (sub === "run") {
-      const { one, many, rest: positional } = takeFlags(rest, ["--arm", "--repeat", "--tasks", "--memory"], ["--addon"]);
-      if (one["--memory"] !== undefined && !(MEMORY_MODES as readonly string[]).includes(one["--memory"])) fail(`--memory takes ${MEMORY_MODES.join(", ")}`);
-      // #248: `--addon ripwire=off` declares the arm's add-on state; the run refuses peers that do not match it.
-      const addons: Partial<Record<AddonName, "on" | "off">> = {};
-      for (const spec of many["--addon"] ?? []) {
-        const [name, state] = spec.split("=");
-        if (!name || !isAddon(name) || (state !== "on" && state !== "off") || addons[name]) fail(`--addon takes <name>=on|off once per add-on, name one of ${ADDONS.join(", ")}`);
-        addons[name] = state;
-      }
-      const suite = positional[0];
-      const repeat = one["--repeat"] === undefined ? 1 : Number(one["--repeat"]);
-      if (!suite || positional.length !== 1 || !one["--arm"]?.trim() || !Number.isSafeInteger(repeat) || repeat < 1 || repeat > 100) {
-        fail("usage: ahub bench run <suite.json> --arm <label> [--repeat 1..100] [--tasks a,b] [--addon <name>=on|off]... [--memory off|claude-mem|native|both]");
-      }
+      const { one, addons, suite, repeat } = benchRunArgs(rest);
       await benchPreflight(cwd, loadConfig(cwd).bench.enabled); // the suite's refs are checked once it is read
       let interrupted = false;
       const stop = () => { interrupted = true; console.log("stopping at the next check: the attempt in progress is recorded as interrupted (a task still open is named)"); };
       process.on("SIGINT", stop);
       try {
-        const run = await runBench({ cwd, stateDir, suitePath: resolve(invokedFrom, suite!), arm: one["--arm"]!.trim(), repeat, addons, ...(one["--memory"] ? { memory: one["--memory"] as MemoryMode } : {}), only: one["--tasks"]?.split(",").map((t) => t.trim()).filter(Boolean), stopped: () => interrupted }, defaultIo(stateDir, cwd));
+        const run = await runBench({ cwd, stateDir, suitePath: resolve(invokedFrom, suite!), arm: one["--arm"]!.trim(), repeat, addons, ...(one["--memory"] ? { memory: one["--memory"] as MemoryMode } : {}), only: one["--tasks"]?.split(",").map((t) => t.trim()).filter(Boolean), stopped: () => interrupted }, defaultIo(stateDir, cwd, identity.role === "tools" ? identity.peer : undefined));
         return console.log(formatBenchReport(benchReport(readRuns().filter((r) => r.header.run === run))).join("\n"));
       } finally { process.off("SIGINT", stop); }
     }
@@ -1915,12 +2157,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   research: () => {
     // #247: measures from the opt-in research records; `export` writes them out, `backfill` builds them from events.jsonl.
     const [sub] = args;
-    // Another project is `ahub --project <dir> research`; anything unknown is refused rather than ignored.
-    const flags = new Set(["--all", "--json", "--since", "--format"]), valued = new Set(["--since", "--format"]);
-    for (let i = sub === "export" || sub === "backfill" || sub === "addons" ? 1 : 0; i < args.length; i++) {
-      if (!flags.has(args[i]!)) fail(`ahub research: unknown argument ${args[i]} (another project: ahub --project <dir> research)`);
-      if (valued.has(args[i]!)) i++;
-    }
+    researchArgs();
     if (sub === "backfill") {
       const project = researchProject();
       const written = appendRecords(project.id, taskRecords(readEvents(join(stateDir, "events.jsonl")), project.id, { version: VERSION, source: "backfill" }));
@@ -2084,9 +2321,14 @@ const commands: Record<string, () => Promise<void> | void> = {
       if (why.length) fail(`refusing to undo ${id}: ${why.join("\n")}${reverted ? "\nCodex's conversation was already reverted; restore the files later with ahub undo without --context" : ""}`);
       return p;
     };
+    // #798 D3: the hub saw these submodules dirty when the turn ended and cannot see inside them: they are never restored, and never counted as "no change".
+    const unobserved = turn.unobserved ?? [];
+    const unobservedNote = unobserved.length ? `\nthese submodules were changed during the turn and their contents cannot be restored (the hub does not observe inside a submodule); undo them in the submodule itself:\n  ${unobserved.join("\n  ")}` : "";
     const first = plan();
-    if (first.undone) return console.log(`turn ${id} is already undone: its files are as they were before it started`);
-    console.log(first.restore.length ? `turn ${id} changed:\n  ${first.restore.join("\n  ")}` : `turn ${id} changed no files`);
+    if (first.undone && !unobserved.length) return console.log(`turn ${id} is already undone: its files are as they were before it started`);
+    if (first.undone) return console.log(`turn ${id}: its files are as they were before it started${unobservedNote}`);
+    // "changed no files" is true of the files the hub observes and false of the turn: with a submodule dirty it says what it can and cannot see instead.
+    console.log((first.restore.length ? `turn ${id} changed:\n  ${first.restore.join("\n  ")}` : unobserved.length ? `turn ${id} changed no files the hub can restore` : `turn ${id} changed no files`) + unobservedNote);
     console.log("(every change made in the project during the turn counts as its own, including any by Claude or by you)");
     const projections = new TextProjections({ cwd: undoCwd, stateDir, config: undoConfig.text_projection ?? {}, deny: undoConfig.local.deny, readAllow: undoConfig.local.read_allow, log: line => console.error(line) });
     const preview = projectedDiff({ repo, from: endTree, to: startTree, paths: first.restore, projections, deny: undoConfig.local.deny, privatePath: path => matchesPolicy(undoCwd, join(repo.top, path), undoConfig.pii?.paths ?? []) });
@@ -2115,6 +2357,8 @@ const commands: Record<string, () => Promise<void> | void> = {
     await stopProject(project);
     console.log("hub stopped");
   },
+  // The counterpart of `ahub up`: the same verified graceful stop as `ahub kill`, never a second shutdown path.
+  down: async () => { await commands.kill!(); },
 
   reset: async () => {
     if (args.some((a) => !["--all", "--yes"].includes(a))) fail("usage: ahub reset [--all] [--yes]");
@@ -2235,7 +2479,15 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     if (args.includes("--orphans")) {
       if(identity.role==="tools" && args.includes("--kill")) {
-        const hub=await connect();try {const result=await hub.request({t:"conductor_operational",op:"orphans"},10_000);if(result.ok!==true)fail(String(result.error??"orphan inspection unavailable"),result.refusalAudited===true,result.authorityRefused);console.log(JSON.stringify(result,null,2));}finally{hub.close();}return;
+        // #812: the conductor's shell asks the hub to stop its own orphan; #899: the answer prints for a person unless --json.
+        const hub=await connect();
+        try {
+          const result=await hub.request({t:"conductor_operational",op:"orphans"},10_000);
+          if(result.ok!==true)fail(String(result.error??"orphan inspection unavailable"),result.refusalAudited===true,result.authorityRefused);
+          if (options.json) console.log(JSON.stringify(result,null,2));
+          else printOutput(renderOrphanCleanup(result, options.columns), options.color);
+        } finally{hub.close();}
+        return;
       }
       return orphanDoctor(args.includes("--kill"), options);
     }
@@ -2395,20 +2647,26 @@ function inspectDoctorRouting(cwd: string): { routing?: Routing; errors: string[
 }
 
 async function runConductorCommand(): Promise<void> {
+  if (recoveryRunnerContinuation) return commands[cmd]!();
   const operation=conductorOperation(cmd,args);
   if(operation) {
     const unavailable=`conductor authorization unavailable; nothing was executed; ${OPERATIONAL_PERSON_GUIDANCE}`;
     const descriptor=readControl(stateDir);
+    // Offline resume proves the source-issued local continuation inside the command; no console connection is borrowed.
+    if (conductorPeer && cmd === "recovery" && (!descriptor?.pid || !descriptor.pidSignature || processLiveness(descriptor.pid, descriptor.pidSignature) !== "live")) return commands.recovery!();
     if(!descriptor?.instanceId || !descriptor.projectId || !descriptor.pid || !descriptor.pidSignature || processLiveness(descriptor.pid,descriptor.pidSignature)!=="live")fail(unavailable);
     let hub:ControlClient;
     try {hub=await connect(3000);} catch {fail(unavailable);}
     let release:(()=>void)|undefined;
     try {
       let result:any;
-      try {result=await hub.request({t:"conductor_operational",op:"authorize",command:operation},3000);} catch {fail(unavailable);}
+      // #933: a form that runs in this process is admitted and audited once here (`admit`), after its arguments pass; any other form's own request admits it.
+      if(conductorLocalOperation(operation))LOCAL_OPERATION_ARGS[operation]?.();
+      try {result=await hub.request({t:"conductor_operational",op:conductorLocalOperation(operation)?"admit":"authorize",command:operation},3000);} catch {fail(unavailable);}
       if(result.ok!==true)fail(result.authorityRefused===true || result.authorityRefused===false?String(result.error??unavailable):unavailable,result.refusalAudited===true,result.authorityRefused);
       if(!hub.instanceId)fail(unavailable);
-      release=ControlClient.pinInstance(stateDir,hub.instanceId);
+      // Recovery replaces its source instance. Its own per-project proofs fence every later connection.
+      if (!conductorPeer || !["restart", "upgrade", "recovery"].includes(cmd)) release=ControlClient.pinInstance(stateDir,hub.instanceId);
       await commands[cmd]!();
     } finally {release?.();hub.close();}
     return;
@@ -2430,11 +2688,14 @@ async function runConductorCommand(): Promise<void> {
   } else {
     // Native TUIs return a human launch command through the daemon; an agent shell never executes it.
     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) });
+      const selection = parseConfiguredAcpArguments(cmd, args, projectCatalog, declaredInstances, peerConfig.declaredExternalInstances);
+      if (selection.preview) return runConfiguredAcpEntry({ kind: cmd, raw: args, catalog: projectCatalog, instances: declaredInstances, declaredExternalInstances: peerConfig.declaredExternalInstances, projectRoot: cwd, 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 {
+        const external = selection.peer !== cmd && (peerConfig.declaredExternalInstances?.some(row => row.id === selection.peer && row.kind === cmd)
+          || projectCatalog.externalDefinitions.some(definition => definition.kind === cmd));
+        if (external) fail("external module instances require an explicit person start");
         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(); }
@@ -2451,9 +2712,9 @@ async function runConductorCommand(): Promise<void> {
   console.log(await taskOp(op, input));
 }
 const runConfigured = configuredCommand ? async () => {
-  const selection = parseConfiguredAcpArguments(cmd, args, projectCatalog, declaredInstances);
+  const selection = parseConfiguredAcpArguments(cmd, args, projectCatalog, declaredInstances, peerConfig.declaredExternalInstances);
   if (!selection.preview) assertLifecycleAvailable();
-  await runConfiguredAcpEntry({ kind: cmd, raw: args, catalog: projectCatalog, instances: declaredInstances, connect: connectLaunch, print: text => console.log(text), operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+  await runConfiguredAcpEntry({ kind: cmd, raw: args, catalog: projectCatalog, instances: declaredInstances, declaredExternalInstances: peerConfig.declaredExternalInstances, projectRoot: cwd, connect: connectLaunch, 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 {