@staix/agent-hub 0.20.0 → 0.22.0

package/src/cli/source-output.ts

@@ -0,0 +1,29 @@
+// Human output for `ahub source add|list` (#508). Pure: data in, spans out, no I/O. `--json` is the caller's branch and prints the same data.
+import { blank, grid, heading, pair, s } from "./sdlc-output.ts";
+import { moment } from "./sdlc-output.ts";
+import type { Span } from "./console-state.ts";
+
+const list = (value: unknown): any[] => Array.isArray(value) ? value : [];
+const size = (bytes: unknown) => typeof bytes === "number" && Number.isFinite(bytes) ? bytes < 1024 ? `${bytes} B` : bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KiB` : `${(bytes / 1024 / 1024).toFixed(1)} MiB` : "unknown";
+
+/** `ahub source add`: what was registered, and whether it was new or an upgrade of an existing record. */
+export function renderSourceAdd(result: unknown, columns?: number): Span[][] {
+  const r = result as any, out: Span[][] = [...heading(r?.created ? `Registered ${r?.id}` : r?.upgraded ? `Already registered ${r?.id}; now private` : `Already registered ${r?.id}`, columns)];
+  out.push(...pair("kind", r?.kind ?? "unknown", columns, 8), ...pair("origin", r?.origin ?? "unknown", columns, 8), ...pair("sha256", r?.sha256 ?? "unknown", columns, 8), ...pair("size", size(r?.bytes), columns, 8));
+  out.push(...pair("private", r?.private ? "yes" : "no", columns, 8, r?.private ? "attention" : undefined), ...pair("text", r?.text ? "projected" : "none (no converter handles these bytes)", columns, 8, r?.text ? undefined : "muted"));
+  if (list(r?.reasons).length) out.push(...pair("because", list(r.reasons).join("; "), columns, 8, "attention"));
+  return out;
+}
+
+/** `ahub source list`: one row per registered source, newest last. The person sees every origin of a private source. */
+export function renderSourceList(rows: unknown, columns?: number, now = Date.now()): Span[][] {
+  const sources = list(rows);
+  if (!sources.length) return [[s("no sources registered; add one with ahub source add <path|url>", "muted")]];
+  const out: Span[][] = [...heading(`Sources (${sources.length})`, columns)];
+  out.push(...grid(["ID", "KIND", "SIZE", "PRIVATE", "ADDED", "ORIGIN"], sources.map((row: any) => [
+    s(row.id, "issueRef"), s(row.kind), s(size(row.bytes)), s(row.private ? "yes" : "no", row.private ? "attention" : "muted"), s(moment(row.added_at, now)), s(row.origin),
+  ]), columns));
+  const many = sources.filter((row: any) => list(row.origins).length > 1);
+  for (const row of many) out.push(blank, ...pair(row.id, `${list(row.origins).length} origins: ${list(row.origins).map((o: any) => `${o.origin}${o.private ? " (private)" : ""}`).join("; ")}`, columns, 20, undefined));
+  return out;
+}

package/src/cli/task-output.ts

@@ -5,6 +5,7 @@
 // and detail, empty refs and plan): this module shows that stub and never asks for more.
 import { type Span, type Tone, plural, table, terminalText, wrap } from "./console-state.ts";
 import { moment } from "./sdlc-output.ts";
+import { taskHolderText } from "./role-holders.ts";
 
 type Line = Span[];
 // Local copies of the layout primitives of sdlc-output.ts (#814 T1), the source of these helpers: that file stays untouched by this task
@@ -100,8 +101,8 @@ function taskBlock(task: any, columns: number | undefined, now: number, detail:
   const out: Line[] = [...para(`${id}  ${dash(task?.title)}`, columns, undefined, "", 6).map((line, i): Line => i === 0 ? [s(id, "taskRef"), s(line[0]!.text.slice(id.length), "strong")] : line)];
   const w = 10;
   out.push(...pair("state", `${dash(task?.state)}${task?.cancelled ? " (cancelled)" : ""}`, columns, w, stateTone(task?.state), "  "),
-    ...pair("class", dash(task?.class), columns, w, undefined, "  "), ...pair("owner", dash(task?.owner), columns, w, undefined, "  "), ...pair("reviewer", dash(task?.reviewer), columns, w, undefined, "  "));
-  if (task?.planner) out.push(...pair("planner", task.planner, columns, w, undefined, "  "));
+    ...pair("class", dash(task?.class), columns, w, undefined, "  "), ...pair("owner", taskHolderText(task, "owner"), columns, w, undefined, "  "), ...pair("reviewer", taskHolderText(task, "reviewer"), columns, w, undefined, "  "));
+  if (task?.planner !== undefined) out.push(...pair("planner", taskHolderText(task, "planner"), columns, w, undefined, "  "));
   if (task?.reserved) out.push(...pair("reserved", task.reserved, columns, w, undefined, "  "));
   out.push(...pair("after", ids(task?.deps), columns, w, undefined, "  "));
   if (typeof task?.release === "number") out.push(...pair("release", `#${task.release}`, columns, w, undefined, "  "));

package/src/cli/upgrade-runtime.ts

@@ -1,10 +1,15 @@
+import { authorizeConductorOperation, conductorRecoveryBinding } from "./conductor-recovery.ts";
 import { resolveAcceptedBinding } from "./recovery-guidance.ts";
 import { claudeStateFile } from "../hub/claude-state.ts";
 import { ADAPTERS, definitionOf } from "../adapters/registry.ts";
-import { readInstanceConfig } from "../hub/instance-config.ts";
+import { readInstanceConfig, readInstanceConfigLayers } from "../hub/instance-config.ts";
+import { readRecoveryWaits } from "./recovery-waits.ts";
+import { readAdapterModuleDeclarations } from "../adapters/external-modules.ts";
+import { configRefusal } from "../hub/config-trust.ts";
+import { validExternalInstanceBinding } from "../hub/external-instance.ts";
 import { isDatabaseBusy, isDatabaseBusyReply, RecoveryDatabaseBusy } from "../hub/recovery-error.ts";
 import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join, relative, resolve, sep } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { ControlClient, PROTOCOL, RECOVERY_SOURCE_PROTOCOLS, readControl } from "../hub/control-client.ts";
 import { awaitStopped, inspectProject } from "../hub/lifecycle.ts";
@@ -22,10 +27,9 @@ import { decodeRestoreReceipt, restoreTransition, type RestoreReceipt, type Rest
 import { RecoveryDeferredHubError } from "../hub/deferred-hub.ts";
 import { RecoveryPreservationError, RecoveryPresentationError, type RecoveryNativeCause } from "./upgrade-presentation-data.ts";
 
-/** An unmanaged Claude's plugin retries with a backoff of at most 30 s; three of those bound the reconnect wait (#206). */
-const UNMANAGED_RECONNECT_WAIT_MS = 90_000;
-/** Managed TUI startup can include resume and MCP handshakes; match createTerminal's ten-minute readiness ceiling. */
-const RECONNECT_WAIT_MS = 600_000;
+// #489 H4: the reconnect, unmanaged reconnect, control request, terminal idle and shutdown waits are settings now (`recovery.*`, src/hub/operational-settings.ts), read by `readRecoveryWaits` at the start of
+// each wait. Their defaults are the constants that stood here: an unmanaged Claude's plugin retries with a backoff of at most 30 s and three of those bound its reconnect wait (#206, 90 s); managed TUI startup
+// can include resume and MCP handshakes, so its wait matches createTerminal's ten-minute readiness ceiling (600 s, which is also the setting's floor).
 class AttachmentLauncherGone extends Error {
   constructor(readonly transition: RestoreTransition) { super("chosen attachment launcher exited"); }
 }
@@ -76,12 +80,12 @@ export function restoredTerminalArgv(entrypoint: string, projectRoot: string, bi
   return [process.execPath, entrypoint, "--project", projectRoot, ...tail];
 }
 
-const RECOVERY_CONTROL_TIMEOUT_MS = 30_000;
 
-async function rpc(project: Project, message: Record<string, unknown>, protocol = PROTOCOL): Promise<any> {
-  const client = await ControlClient.connect(project.stateDir, { role: "console", projectRoot: project.root, projectId: project.id }, RECOVERY_CONTROL_TIMEOUT_MS, protocol);
+async function rpc(project: Project, message: Record<string, unknown>, protocol = PROTOCOL, conductorPeer?: string): Promise<any> {
+  const controlTimeoutMs = readRecoveryWaits(project.root).controlTimeoutMs;
+  const client = await ControlClient.connect(project.stateDir, { ...(conductorPeer ? { role: "tools" as const, peer: conductorPeer } : { role: "console" as const }), projectRoot: project.root, projectId: project.id }, controlTimeoutMs, protocol);
   try {
-    const reply = await client.request(message, RECOVERY_CONTROL_TIMEOUT_MS);
+    const reply = await client.request(message, controlTimeoutMs);
     if (reply.ok === false) {
       // An older hub has only its exact SQLite message; preserve compatibility without trusting arbitrary text.
       if (isDatabaseBusyReply(reply)) throw new RecoveryDatabaseBusy();
@@ -142,10 +146,53 @@ export async function endPlannedPeer(planned: PlannedProject, peer: RecoveryPeer
   }
 }
 
+/** No imports or executable catalog reconstruction: unknown kinds are only possible module instances. */
+function recoveryDeclarations(projectRoot: string) {
+  const layers = readInstanceConfigLayers(projectRoot);
+  const modules = readAdapterModuleDeclarations(projectRoot, layers).modules;
+  const local = layers.find(layer => layer.name === "config.local.json");
+  const raw = local && !configRefusal(projectRoot, local.name) ? local.raw : {};
+  const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+  const instances = raw.instances === undefined ? {} : raw.instances;
+  if (!object(instances) || Object.keys(instances).length > 64) throw new Error("recovery instance declaration inventory unavailable");
+  const configured = object(raw.adapters) ? Object.keys(raw.adapters) : [];
+  const moduleInstances = Object.entries(instances).filter(([, entry]) => !object(entry) || typeof entry.kind !== "string" || !definitionOf(entry.kind) && !configured.includes(entry.kind));
+  return { modules, instances, configured, moduleInstances };
+}
+const hasRecoveryFeatures = (features: unknown, required: readonly string[]): features is string[] => Array.isArray(features) && features.every(feature => typeof feature === "string") && required.every(feature => features.includes(feature));
+const EXTERNAL_INSTANCE_FEATURES = ["external_adapter_modules", "peer_instances", "external_adapter_instances"] as const;
+
+/** Includes offline declarations and retained identities, so a reused target cannot downgrade their meaning. */
+export function instanceRecoveryTargetRefusal(projectRoot: string, features: unknown, retainedPeers: readonly RecoveryPeer[] = []): string | undefined {
+  const declarations = recoveryDeclarations(projectRoot);
+  if ((declarations.moduleInstances.length || retainedPeers.some(peer => Object.hasOwn(peer, "externalInstance"))) && !hasRecoveryFeatures(features, EXTERNAL_INSTANCE_FEATURES)) {
+    return "target lacks external_adapter_instances or its external_adapter_modules/peer_instances prerequisites; module instances require a supporting target before recovery effects";
+  }
+}
+
 /** Declared identities cannot be reinterpreted against an older running source's unbound peer rows. */
 export function instanceRecoverySourceRefusal(projectRoot: string, features: unknown, observedPeers?: unknown): string | undefined {
+  const inventory = recoveryDeclarations(projectRoot);
+  if (inventory.moduleInstances.length) {
+    if (!hasRecoveryFeatures(features, EXTERNAL_INSTANCE_FEATURES)) return "source lacks external_adapter_instances or its external_adapter_modules/peer_instances prerequisites; restart with a supporting source before recovering module instances, including offline declarations";
+    const rows = observedPeers && typeof observedPeers === "object" && !Array.isArray(observedPeers) ? observedPeers as Record<string, unknown> : undefined;
+    for (const [id, declaration] of inventory.moduleInstances) {
+      const peer = rows?.[id] as RecoveryPeer | undefined;
+      const binding = peer?.externalInstance;
+      if (!declaration || typeof declaration !== "object" || !peer || !["idle", "busy", "paused", "offline"].includes(peer.state) || !validExternalInstanceBinding(binding, projectRoot, id) || binding.kind !== (declaration as { kind?: unknown }).kind ||
+          !inventory.modules.some(module => module.sha256 === binding.sha256 && relative(projectRoot, resolve(projectRoot, module.path)).split(sep).join("/") === binding.modulePath)) {
+        return "source external module instance binding unavailable or changed; a matching authenticated live startup catalog is required before recovery";
+      }
+    }
+    const configuredIds = [...inventory.configured, ...Object.entries(inventory.instances).filter(([, entry]) => entry && typeof entry === "object" && inventory.configured.includes((entry as { kind: string }).kind)).map(([id]) => id)];
+    if (configuredIds.length && !hasRecoveryFeatures(features, ["configured_acp"])) {
+      if (!rows || !Object.values(rows).every(peer => peer && typeof peer === "object" && typeof (peer as { state?: unknown }).state === "string") || Object.entries(rows).some(([id, peer]) => configuredIds.includes(id) && (peer as { state: string }).state !== "offline")) return "source lacks configured_acp; configured native identities require a supporting source before recovery";
+    }
+    // The authenticated source owns semantic admission; raw config and cached display metadata cannot reconstruct it.
+    return undefined;
+  }
   const bound = readInstanceConfig(projectRoot);
-  if (bound.adapter_modules?.length && !(Array.isArray(features) && features.includes("external_adapter_modules"))) return "source lacks external_adapter_modules; restart with a supporting source before recovering module peers";
+  if (bound.adapter_modules?.length && !hasRecoveryFeatures(features, ["external_adapter_modules"])) return "source lacks external_adapter_modules; restart with a supporting source before recovering module peers";
   const configured = Object.keys(bound.adapters ?? {});
   const configuredIds = [...configured, ...Object.entries(bound.instances ?? {}).filter(([, entry]) => configured.includes(entry.kind)).map(([id]) => id)];
   if (configuredIds.length && !(Array.isArray(features) && features.every(feature => typeof feature === "string") && features.includes("configured_acp"))) {
@@ -163,12 +210,12 @@ export function instanceRecoverySourceRefusal(projectRoot: string, features: unk
   return "source lacks peer_instances support and a declared instance of this project may be live; restart the source with a supporting agent-hub version before retrying recovery; for a first upgrade, end the extra native sessions first (a source whose declared instances are all offline proceeds without further steps); only if one cannot be ended, temporarily remove its declaration, upgrade the source, then declare it again; legacy peer identities were not reinterpreted";
 }
 
-export async function inspectRecovery(project: Project, targetFeatures?: readonly string[], purpose?: "cleanup"): Promise<Inspection> {
+export async function inspectRecovery(project: Project, targetFeatures?: readonly string[], purpose?: "cleanup", conductorPeer?: string): Promise<Inspection> {
   // #226: the claim is judged by the registry as it is now, never by the plan's frozen copy, which holds the source's
   // pid from planning time (after a reboot another process may hold it). A registry that cannot be read throws: the
   // caller reads that as not inspected, never as stopped.
   const claim = registeredProjects().find((p) => p.id === project.id);
-  const base = await inspectProject({ ...project, instanceId: claim?.instanceId ?? null, pid: claim?.pid ?? null, pidSignature: claim?.pidSignature ?? null }, RECOVERY_CONTROL_TIMEOUT_MS);
+  const base = await inspectProject({ ...project, instanceId: claim?.instanceId ?? null, pid: claim?.pid ?? null, pidSignature: claim?.pidSignature ?? null }, readRecoveryWaits(project.root).controlTimeoutMs, conductorPeer);
   if (base.failure?.code === "database_busy") throw new RecoveryDatabaseBusy();
   const control = readControl(project.stateDir);
   const sourceProtocol = control?.protocol;
@@ -203,7 +250,7 @@ export async function inspectRecovery(project: Project, targetFeatures?: readonl
   };
   if (!status && legacySupported && sourceProtocol !== PROTOCOL) {
     try {
-      const readback = await rpc(project, { t: "status" }, sourceProtocol);
+      const readback = await rpc(project, { t: "status" }, sourceProtocol, conductorPeer);
       status = readback.status;
     } catch (error) {
       if (isDatabaseBusy(error)) throw error;
@@ -218,7 +265,7 @@ export async function inspectRecovery(project: Project, targetFeatures?: readonl
   const instanceRefusal = purpose === "cleanup" ? undefined : instanceRecoverySourceRefusal(project.root, status.features, status.peers);
   if (instanceRefusal) return { state: "incompatible", instanceId: status.instanceId, version: status.version, protocol: status.protocol, peers: [], blockers: [instanceRefusal] };
   let response: any;
-  try { response = await rpc(project, { t: "recovery", op: "inspect", expectedInstanceId: status.instanceId, ...(targetFeatures === undefined ? {} : { targetFeatures }) }, sourceProtocol ?? PROTOCOL); }
+  try { response = await rpc(project, { t: "recovery", op: "inspect", expectedInstanceId: status.instanceId, ...(targetFeatures === undefined ? {} : { targetFeatures }) }, sourceProtocol ?? PROTOCOL, conductorPeer); }
   catch (error) {
     if (isDatabaseBusy(error) || targetFeatures !== undefined) throw error;
     // A stop can complete between authenticated status and the second read. Never infer stopped
@@ -227,16 +274,21 @@ export async function inspectRecovery(project: Project, targetFeatures?: readonl
       peers: [], blockers: ["runtime changed during recovery inspection"] };
   }
   const peers = Object.values(response.recovery?.peers ?? {}) as any[];
+  if (peers.some(peer => peer && Object.hasOwn(peer, "externalInstance") && !validExternalInstanceBinding(peer.externalInstance, project.root, peer.id))) {
+    return { state: "incompatible", instanceId: status.instanceId, version: status.version, protocol: status.protocol, peers: [], blockers: ["source external module instance binding is invalid"] };
+  }
   // #272: the hub's own words for what it waits on; shown to the person, never decided on.
   const waiting = (Array.isArray(response.recovery?.blockers) ? response.recovery.blockers : []).filter((b: unknown): b is string => typeof b === "string").slice(0, 20).map((b: string) => b.slice(0, 200));
   return { state: "running", instanceId: status.instanceId, version: status.version, protocol: status.protocol,
     recovery: { operationId: response.recovery?.operationId, phase: response.recovery?.phase, ready: response.recovery?.ready, ...(waiting.length ? { waiting } : {}) }, peers: peers.map((peer) => ({ id: peer.id, state: peer.state,
+      ...(peer.observation === undefined ? {} : { observation: peer.observation }),
+      ...(peer.externalInstance === undefined ? {} : { externalInstance: peer.externalInstance }),
       ...(peer.threadId ? { threadId: peer.threadId } : {}), ...(peer.sessionId ? { sessionId: peer.sessionId } : {}),
       ...(typeof (peer.sessionFile ?? peer.launch?.sessionFile) === "string" ? { sessionFile: peer.sessionFile ?? peer.launch.sessionFile } : {}),
       ...(peer.launch ? { args: Object.fromEntries(Object.entries(peer.launch).filter(([k, v]) => ["model", "route", "sessionFile", "mode", "backend"].includes(k) && typeof v === "string")) as Record<string, string> } : {}) })), blockers: [] };
 }
 
-export async function makeUpgradePlan(kind: "restart" | "upgrade", version: string, selectedRoot?: string, run: RunCommand = runCommand): Promise<UpgradePlan> {
+export async function makeUpgradePlan(kind: "restart" | "upgrade", version: string, selectedRoot?: string, run: RunCommand = runCommand, conductorPeer?: string): Promise<UpgradePlan> {
   const projects = registeredProjects();
   const sourceDigest = packageDigest(PACKAGE_ROOT);
   const currentVersion = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")).version;
@@ -258,7 +310,7 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
   for (const project of projects) {
     if (kind === "restart" && project.root !== selectedRoot) continue;
     let source: Inspection;
-    try { source = await inspectRecovery(project); }
+    try { source = await inspectRecovery(project, undefined, undefined, conductorPeer); }
     catch { source = { state: "unavailable", peers: [], blockers: ["source recovery metadata could not be authenticated"] }; }
     if (source.state === "stopped" || source.state === "missing") continue;
     const blockers = [...source.blockers];
@@ -288,6 +340,7 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
         if (!launcher) {
           unrecordedTerminals.push(peer.id);
           delete peer.sessionId;
+          delete peer.args; // An unmanaged channel reconnects itself; its observed identity is not restoration data.
           if (source.protocol === PROTOCOL) reconnectOnly.push(peer.id);
           else blockers.push(`${peer.id}: unmanaged session (no live ahub claude launcher recorded) runs a protocol-${source.protocol} plugin and cannot reconnect to a protocol-${PROTOCOL} hub; next action: end that Claude session, or relaunch it with ahub claude in an Orca terminal, then make a new plan`);
           continue;
@@ -364,7 +417,12 @@ export function preserveSource(plan: UpgradePlan, home = hubHome()): string {
   return dest;
 }
 
-export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?: string, clock?: Pick<RecoveryDriver, "now" | "sleep">): RecoveryDriver {
+const unboundRecoveryInspection = inspectRecovery;
+
+export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?: string, clock?: Pick<RecoveryDriver, "now" | "sleep">, conductorPeer?: string): RecoveryDriver {
+  let authorizedOperation: RecoveryOperation | undefined;
+  const recoveryCurrent = async () => { if (conductorPeer) { if (!authorizedOperation) throw new FinalRefusal("conductor recovery authority unavailable"); await authorizeConductorOperation(authorizedOperation, conductorPeer); } };
+  const inspectRecovery = (project: Project, features?: readonly string[], purpose?: "cleanup") => unboundRecoveryInspection(project, features, purpose, conductorPeer);
   const now = clock?.now ?? (() => Date.now());
   const sleep = clock?.sleep ?? ((ms: number) => Bun.sleep(ms));
   /** `only`: one binding's native profile, for a command run once per profile (#450 I3: Claude instances may differ). */
@@ -376,6 +434,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     value.AGENTHUB_HOME = hubHome(); value.AGENTHUB_RECOVERY_OPERATION = op.id;
     value.AGENTHUB_UNATTENDED = "0";
     if (liveTestPeer) value.AGENTHUB_PEER_ID = liveTestPeer;
+    if (conductorPeer) value.AGENTHUB_PEER_ID = conductorPeer;
     if (project) {
       value.AGENTHUB_PROJECT_DIR = project.root; value.AGENTHUB_STATE_DIR = project.stateDir;
       delete value.CODEX_HOME; delete value.CLAUDE_CONFIG_DIR;
@@ -390,14 +449,15 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
   };
   const command = async (op: RecoveryOperation, args: string[], project?: Project, only?: TerminalBinding) => {
     const result = await run([process.execPath, join(op.targetRoot!, "src/cli/main.js"), ...(project ? ["--project", project.root] : []), ...(liveTestPeer ? ["--live-test"] : []), ...args],
-      { env: env(op, project, only), cwd: project?.root ?? op.plan.projects[0]!.project.root, timeoutMs: 180_000 });
+      { env: { ...env(op, project, only), ...(conductorPeer ? { AGENTHUB_RECOVERY_CONDUCTOR: conductorPeer, AGENTHUB_RECOVERY_CONTINUATION: op.id } : {}) }, cwd: project?.root ?? op.plan.projects[0]!.project.root, timeoutMs: 180_000 });
     if (result.code !== 0) throw new Error(`target command ${args[0]} failed; inspect recovery state before retrying`);
     return result;
   };
-  const control = (project: Project, op: string, id: string, instance: string, targetFeatures?: readonly string[]) => {
+  const control = async (project: Project, op: string, id: string, instance: string, targetFeatures?: readonly string[]) => {
+    await recoveryCurrent();
     const sourceProtocol = readControl(project.stateDir)?.protocol;
     const protocol = sourceProtocol !== undefined && RECOVERY_SOURCE_PROTOCOLS.includes(sourceProtocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number]) ? sourceProtocol : PROTOCOL;
-    return rpc(project, { t: "recovery", op, operationId: id, expectedInstanceId: instance, ...(targetFeatures === undefined ? {} : { targetFeatures }) }, protocol).then(() => {});
+    return rpc(project, { t: "recovery", op, operationId: id, expectedInstanceId: instance, ...(targetFeatures === undefined ? {} : { targetFeatures }), ...(conductorPeer && authorizedOperation ? { authority: conductorRecoveryBinding(authorizedOperation, project, conductorPeer) } : {}) }, protocol, conductorPeer).then(() => {});
   };
   const nativeFailure = (planned: PlannedProject, peer: string, reason: RecoveryNativeCause["reason"], message: string,
     details: Omit<RecoveryNativeCause, "kind" | "reason" | "projectId" | "peer"> = {}) =>
@@ -409,7 +469,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     if (found.manualRequired || !current || (exact && (current.handle !== saved.handle || current.incarnationId !== saved.incarnationId || current.worktreeId !== saved.worktreeId || current.projectRoot !== saved.projectRoot))) {
       throw nativeFailure(planned, saved.peer, "terminal_unverified", `${saved.peer}: saved terminal identity changed or is not verified; manual-required`, { handle: saved.handle });
     }
-    const idle = await waitForIdle(exact ? saved : current, 120_000, options);
+    const idle = await waitForIdle(exact ? saved : current, readRecoveryWaits(planned.project.root).terminalIdleWaitMs, options);
     if (!idle.satisfied) throw nativeFailure(planned, saved.peer, "terminal_unverified", `${saved.peer}: terminal is not idle; manual-required`, { handle: saved.handle });
     const observed = await inspectRecovery(planned.project);
     if (observed.instanceId !== progress.instanceId) throw nativeFailure(planned, saved.peer, "target_unavailable", `${saved.peer}: daemon instance changed during terminal revalidation`, { handle: saved.handle, targetState: observed.state });
@@ -507,9 +567,10 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       if (seen !== "absent") throw new Error(closeUnsettled(retired, seen));
       progress.terminals[key] = true; save(); return;
     }
-    const idle = await waitForIdle(retired, 120_000, terminalOptions(run));
+    const idle = await waitForIdle(retired, readRecoveryWaits(retired.projectRoot).terminalIdleWaitMs, terminalOptions(run));
     if (!idle.satisfied) throw new Error(`${peer}: terminal ${retired.handle} of the stopped target's session is not verified idle; finish or cancel its turn, or close that terminal by hand, first`);
     progress.terminals[key] = "pending"; save();
+    await recoveryCurrent();
     const result = await closeTerminal(retired, 0, terminalOptions(run));
     if (result.manualRequired) throw new Error(`${peer}: closing terminal ${retired.handle} of the stopped target's session was not verified; manual-required`);
     progress.terminals[key] = true; save();
@@ -522,7 +583,8 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     };
     const binding = waiting.binding;
     const matchesTerminal = (terminal: Pick<TerminalBinding, "handle" | "incarnationId" | "worktreeId">) => terminal.handle === binding.handle && terminal.incarnationId === binding.incarnationId && terminal.worktreeId === binding.worktreeId;
-    const startedAt = now(), deadline = startedAt + RECONNECT_WAIT_MS;
+    const reconnectWaitMs = readRecoveryWaits(planned.project.root).reconnectWaitMs; // read once, at the start: a wait already running keeps the deadline the receipt records
+    const startedAt = now(), deadline = startedAt + reconnectWaitMs;
     const waitStep = op.step;
     if (waitStep) {
       (op.waits ??= {})[waitStep] = { waitStartedAt: new Date(startedAt).toISOString(), deadlineAt: new Date(deadline).toISOString() };
@@ -566,6 +628,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       const decision = restoreTransition(waiting, { target: "running", launcher: launchState,
         session: session && peer && ["idle", "busy", "paused"].includes(peer.state) ? changed ? "other" : "planned" : "none", allowOther: zeroTurn || expectedSession === null, binding });
       if (decision.action === "settle" && session) {
+        await recoveryCurrent();
         if (zeroTurn) waiveRecoveryPeers(planned.project.stateDir, op.id, { [binding.peer]: "zero-turn" });
         return session;
       }
@@ -594,7 +657,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       hub: { state: live.state, ...(live.instanceId ? { instanceId: live.instanceId } : {}), ...(peer ? { peerState: peer.state } : {}), ...(session ? { sessionId: session } : {}) },
       lastHubConnectAttempt: "unknown" };
     save();
-    throw nativeFailure(planned, binding.peer, "attachment_timeout", `${binding.peer}: attachment not verified within ${RECONNECT_WAIT_MS / 1000} s; terminal ${binding.handle} retained; resume after it attaches (native-start diagnostic recorded; last hub connect attempt unknown)`, { handle: binding.handle, timeoutMs: RECONNECT_WAIT_MS });
+    throw nativeFailure(planned, binding.peer, "attachment_timeout", `${binding.peer}: attachment not verified within ${reconnectWaitMs / 1000} s; terminal ${binding.handle} retained; resume after it attaches (native-start diagnostic recorded; last hub connect attempt unknown)`, { handle: binding.handle, timeoutMs: reconnectWaitMs });
     } catch (error) { waitFailed = true; throw error; }
     finally {
       const finish = () => {
@@ -609,6 +672,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
   };
   return {
     ...(liveTestPeer === undefined ? {} : { liveTestPeer }),
+    ...(conductorPeer ? { conductorPeer, authorize: async (op: RecoveryOperation) => { await authorizeConductorOperation(op, conductorPeer); authorizedOperation = op; } } : {}),
     now, sleep, inspect: inspectRecovery,
     recordedSessionState: async (binding, kind) => nativeRecordedSessionState(binding, kind),
     stage: async (op) => {
@@ -627,6 +691,10 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
         return { ...target, ...(op.targetFeatures === undefined ? {} : { targetFeatures: [...op.targetFeatures] }) };
       }
       if (cached && op.targetFeatures !== undefined) {
+        for (const planned of op.plan.projects) {
+          const refusal = typeof planned.project?.root === "string" ? instanceRecoveryTargetRefusal(planned.project.root, op.targetFeatures, planned.source.peers) : undefined;
+          if (refusal) throw new FinalRefusal(refusal);
+        }
         if (!op.targetFeatures.includes("external_adapter_modules") && op.plan.projects.some(planned => typeof planned.project?.root === "string" && (readInstanceConfig(planned.project.root).adapter_modules?.length ?? 0) > 0)) throw new FinalRefusal("target lacks external_adapter_modules; module peers require a supporting target before recovery effects");
         if (!op.targetFeatures.includes("configured_acp") && op.plan.projects.some(planned => typeof planned.project?.root === "string" && Object.keys(readInstanceConfig(planned.project.root).adapters ?? {}).length > 0)) throw new FinalRefusal("target lacks configured_acp; configured adapters require a supporting target before recovery effects");
         if (!op.targetFeatures.includes("peer_instances") && op.plan.projects.some(planned => typeof planned.project?.root === "string" && Object.keys(readInstanceConfig(planned.project.root).instances ?? {}).length > 0)) throw new FinalRefusal("target lacks peer_instances; declared project instances require a supporting target before recovery effects");
@@ -640,6 +708,10 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       if (!metadata || typeof metadata !== "object" || !Number.isInteger(metadata.protocol)) throw new Error(`the staged target's control protocol could not be read (probe exit ${probe.code}); staged package retained, runtimes unchanged; resume again once it can run`);
       if (!Array.isArray(metadata.features) || !metadata.features.every((feature: unknown) => typeof feature === "string" && feature.length > 0)) throw new Error("the staged target features could not be read; staged package retained, runtimes unchanged");
       const targetFeatures: readonly string[] = [...metadata.features];
+      for (const planned of op.plan.projects) {
+        const refusal = typeof planned.project?.root === "string" ? instanceRecoveryTargetRefusal(planned.project.root, targetFeatures, planned.source.peers) : undefined;
+        if (refusal) throw new FinalRefusal(refusal);
+      }
       if (!targetFeatures.includes("external_adapter_modules") && op.plan.projects.some(planned => typeof planned.project?.root === "string" && (readInstanceConfig(planned.project.root).adapter_modules?.length ?? 0) > 0)) throw new FinalRefusal("target lacks external_adapter_modules; module peers require a supporting target before recovery effects");
       if (!targetFeatures.includes("configured_acp") && op.plan.projects.some(planned => typeof planned.project?.root === "string" && Object.keys(readInstanceConfig(planned.project.root).adapters ?? {}).length > 0)) throw new FinalRefusal("target lacks configured_acp; configured adapters require a supporting target before recovery effects");
       if (metadata.protocol !== PROTOCOL) throw new FinalRefusal("target protocol requires a newer coordinator; staged package retained, runtimes unchanged");
@@ -705,6 +777,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
         // the original peer roster and verified target features, including after a resume.
         await control(planned.project, "prepare", op.id, planned.source.instanceId!, op.targetFeatures);
         progress.terminals[key] = "pending"; save();
+        await recoveryCurrent();
         const result = await closeTerminal(binding, 0, terminalOptions(run));
         if (result.manualRequired) throw new Error(`${binding.peer}: terminal close not verified; manual-required`);
         progress.terminals[key] = true; save();
@@ -716,6 +789,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
         throw new Error("committed restart snapshot is missing or belongs to another operation");
       }
       const reconnect = op.plan.projects.find((planned) => planned.project.id === p.id)?.reconnectOnly ?? [];
+      await recoveryCurrent();
       if (reconnect.length) waiveRecoveryPeers(p.stateDir, op.id, Object.fromEntries(reconnect.map((peer) => [peer, "reconnect-only"])));
       await command(op, ["up"], p);
     },
@@ -727,6 +801,10 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
           const current = live.peers.find((p) => p.id === peer.id);
           if (current && current.state !== "offline") continue;
           const adapter = projectDefinition(peer.id, planned.project.root)!;
+          if (conductorPeer) {
+            await rpc(planned.project, { t: "recovery_restore", peer: peer.id, authority: conductorRecoveryBinding(op, planned.project, conductorPeer) }, PROTOCOL, conductorPeer);
+            continue;
+          }
           const args = [adapter.cli.command, ...(peer.id !== adapter.kind ? ["--as", peer.id] : [])];
           const refusal = adapter.session.recoveryRefusal?.(peer, "restore");
           if (refusal) throw new Error(refusal);
@@ -803,6 +881,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
             // #21: a Claude session that never got a first turn has no transcript, so `claude --resume S` can never
             // succeed and accepting its fresh attach loses nothing. Otherwise only the planned id, or a new session
             // the operator or the plan accepted, counts as restored.
+            await recoveryCurrent();
             if (attached !== original.sessionId && !fresh() && !(!recordedOnly && nativeZeroTurn(planned.project.stateDir, original, "attach"))) {
               throw new Error(`${original.peer}: terminal creation outcome is uncertain: session ${attached} is attached instead of ${original.sessionId}; end that ${original.peer} session and close its terminal first`);
             }
@@ -817,6 +896,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
             // Any other accepted session needs the target to waive the saved id, or release would wait for it forever;
             // a launch writes the waiver first, but this must not rely on that.
             // The planned session needs no waiver: the target's snapshot already expects it.
+            await recoveryCurrent();
             if (attached !== original.sessionId && attached !== plannedBinding.sessionId) waiveRecoveryPeers(planned.project.stateDir, op.id, { [original.peer]: waiver() });
             if (repair) repair.state = "attempted"; // a verified spontaneous reattachment also closes this repair allowance
             // The person accepted one loss, not a permanent exemption for later repairs of the replacement.
@@ -881,6 +961,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
           if (fresh()) {
             if (!targetReadsWaivers(op)) throw new Error(`${original.peer}: target ${op.plan.version} predates recovery waivers, so it cannot accept a new session`);
             // The restored daemon must accept the new session instead of the recorded one.
+            await recoveryCurrent();
             waiveRecoveryPeers(planned.project.stateDir, op.id, { [original.peer]: waiver() });
           }
           if (repair) {
@@ -894,6 +975,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
             command: ["env", ...Object.entries(assignments).map(([k, v]) => `${k}=${v}`), ...argv].map(shellQuote).join(" ") };
           const binding = { ...original, launch, launchMetadata: launch };
           progress.terminals[key] = { state: "pending" } satisfies RestoreReceipt; save();
+          await recoveryCurrent();
           const restored = await createTerminal(binding, { ...terminalOptions(run), stateDir: planned.project.stateDir, instanceId: progress.instanceId }, undefined, fresh());
           const exited = restored.blockers.find((b) => b.code === "launcher-exited");
           if (exited) {
@@ -949,9 +1031,10 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       }
       if (group !== "native" && !onlyPeer) for (const id of planned.reconnectOnly ?? []) {
         // #206: nothing is launched for an unmanaged session; its plugin reconnects by itself, within a bound.
-        const deadline = now() + UNMANAGED_RECONNECT_WAIT_MS;
+        const unmanagedWaitMs = readRecoveryWaits(planned.project.root).unmanagedReconnectWaitMs;
+        const deadline = now() + unmanagedWaitMs;
         while (!(await inspectRecovery(planned.project)).peers.some((p) => p.id === id && p.state !== "offline")) {
-          if (now() >= deadline) throw nativeFailure(planned, id, "attachment_timeout", `${id}: the unmanaged session did not reconnect within ${UNMANAGED_RECONNECT_WAIT_MS / 1000} s; if that Claude session was closed, start Claude in the project again (its plugin reconnects) first`, { timeoutMs: UNMANAGED_RECONNECT_WAIT_MS });
+          if (now() >= deadline) throw nativeFailure(planned, id, "attachment_timeout", `${id}: the unmanaged session did not reconnect within ${unmanagedWaitMs / 1000} s; if that Claude session was closed, start Claude in the project again (its plugin reconnects) first`, { timeoutMs: unmanagedWaitMs });
           await sleep(1000);
         }
       }
@@ -970,6 +1053,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       if (!configured.size) await command(op, ["setup", "--yes"]);
     },
     installGlobal: async (op) => {
+      await recoveryCurrent();
       const result = await run([process.execPath, "add", "-g", `@staix/agent-hub@${op.plan.version}`, "--ignore-scripts"], { env: env(op), timeoutMs: 180_000 });
       if (result.code !== 0) throw new Error("global installation failed; project runtimes use the retained staged package");
       const readback = await run(["ahub", "--version"], { env: env(op) });
@@ -1005,7 +1089,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
         } catch { return { continuity: "unavailable" }; } // optional metadata must not wedge stop-and-archive
       }
     },
-    refreshManager: async (op) => { await refreshManager({ home: hubHome(), cli: join(op.targetRoot!, "src/cli/main.ts") }); },
+    refreshManager: async (op) => { if (conductorPeer && op.plan.kind === "restart") return; await refreshManager({ home: hubHome(), cli: join(op.targetRoot!, "src/cli/main.ts") }); },
     verify: async (planned, progress, op, save) => {
       const live = await inspectRecovery(planned.project);
       if (live.instanceId !== progress.instanceId || live.version !== op.plan.version || live.recovery?.operationId !== op.id) throw new Error("target identity verification failed");