@staix/agent-hub 0.20.0 → 0.21.0

package/src/cli/upgrade-runtime.ts

@@ -1,10 +1,14 @@
+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 { 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";
@@ -78,8 +82,8 @@ export function restoredTerminalArgv(entrypoint: string, projectRoot: string, bi
 
 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 client = await ControlClient.connect(project.stateDir, { ...(conductorPeer ? { role: "tools" as const, peer: conductorPeer } : { role: "console" as const }), projectRoot: project.root, projectId: project.id }, RECOVERY_CONTROL_TIMEOUT_MS, protocol);
   try {
     const reply = await client.request(message, RECOVERY_CONTROL_TIMEOUT_MS);
     if (reply.ok === false) {
@@ -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 }, RECOVERY_CONTROL_TIMEOUT_MS, 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"> = {}) =>
@@ -510,6 +570,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     const idle = await waitForIdle(retired, 120_000, 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();
@@ -566,6 +627,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;
       }
@@ -609,6 +671,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 +690,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 +707,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 +776,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 +788,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 +800,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 +880,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 +895,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 +960,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 +974,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) {
@@ -970,6 +1051,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 +1087,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");

package/src/cli/upgrade.ts

@@ -1,6 +1,7 @@
 import { nativeRestoreGroup } from "../adapters/definitions/native-identity-defaults.ts";
 import { definitionOf } from "../adapters/registry.ts";
 import { readInstanceConfig } from "../hub/instance-config.ts";
+import { validExternalInstanceBinding, type ExternalInstanceBinding } from "../hub/external-instance.ts";
 import { LIVE_TEST_PERSON_REFUSAL } from "./identity.ts";
 import { checkedSessionPath } from "./recovery-session-file.ts";
 import { canChooseFresh, decodeRestoreReceipt, restoreReceiptStatus } from "./upgrade-restore-state.ts";
@@ -11,7 +12,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { REGISTRY_DB_BUSY_TIMEOUT_MS, PROJECT_COLUMNS, projectFromRow, type Project } from "../hub/registry.ts";
 import { hubHome } from "../hub/project.ts";
-import { acquireRecoveryLock, claimRunner, coordinatorCurrent, readOperation, recoveryCommand, recoveryLock, releaseRecoveryLock, writeOperation } from "../hub/recovery-store.ts";
+import { acquireRecoveryLock, claimRunner, coordinatorCurrent, operationIdPattern, readOperation, recoveryCommand, recoveryLock, releaseRecoveryLock, writeOperation } from "../hub/recovery-store.ts";
 import { resolveAcceptedBinding, piArchiveExit, recordedPeerGuidance, type RecoveryNativePeer } from "./recovery-guidance.ts";
 import type { TerminalBinding } from "./terminal-recovery.ts";
 import { RecoveryPresentationError, type RecoveryPresentationCause, type RecoveryWaitTiming } from "./upgrade-presentation-data.ts";
@@ -25,6 +26,10 @@ const projectDefinition = (peer: string, root?: string) => {
 
 export interface RecoveryPeer {
   id: string;
+  /** Read-only source observation; never consumed as restoration arguments. */
+  observation?: { kind: string; attached: boolean; sessionDigest?: string };
+  /** Captured stable module/instance identity; never a portable current-owner proof. */
+  externalInstance?: ExternalInstanceBinding;
   state: string;
   threadId?: string;
   sessionId?: string;
@@ -126,6 +131,8 @@ export interface RecoveryOperation {
   sourceRoot: string;
   /** Ids-only initiating and subsequent delegated invocations; retained across coordinator replacement. */
   delegatedAudits?: RecoveryDelegationAudit[];
+  /** Source template bytes only when the project has no routing.toml; integrity is sealed in the private policy digest. */
+  conductorRoutingDefaults?: Record<string, string>;
   targetRoot?: string;
   targetDigest?: string;
   /** Verified capability evidence bound to targetRoot/targetDigest; absence is legacy unknown, not an empty list. */
@@ -409,12 +416,13 @@ export function planFingerprint(plan: Omit<UpgradePlan, "fingerprint">): string
   return createHash("sha256").update(JSON.stringify(stable)).digest("hex");
 }
 
-export function createOperation(plan: UpgradePlan, sourceRoot: string, home = hubHome(), delegation?: RecoveryDelegation): RecoveryOperation {
+export function createOperation(plan: UpgradePlan, sourceRoot: string, home = hubHome(), delegation?: RecoveryDelegation, operationId: string = randomUUID()): RecoveryOperation {
+  if (!operationIdPattern.test(operationId)) throw new Error("invalid recovery operation ID");
   if (plan.blockers.length || plan.projects.some((p) => p.blockers.length)) throw new Error("upgrade plan has blockers; no runtimes were changed");
   if (!plan.projects.length) throw new Error("no running projects to recover");
   const { fingerprint, ...body } = plan;
   if (planFingerprint(body) !== fingerprint) throw new Error("upgrade plan fingerprint is invalid");
-  const id = randomUUID();
+  const id = operationId;
   const op: RecoveryOperation = {
     schema: 1, id, plan, sourceRoot, createdAt: Date.now(), updatedAt: Date.now(), phase: "pending", step: "stage",
     projects: plan.projects.map((p) => ({ id: p.project.id, phase: "pending", terminals: {} })),
@@ -487,6 +495,10 @@ function validateReceipt(id: string, op: RecoveryOperation, historical = false):
       op.projects.some((p, i) => p.id !== op.plan.projects[i]?.project.id)) throw new Error("reviewed operation plan or project scope changed");
   const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
   for (const [index, progress] of op.projects.entries()) {
+    const planned = op.plan.projects[index]!;
+    for (const peer of planned.source.peers) {
+      if (Object.hasOwn(peer, "externalInstance") && !validExternalInstanceBinding(peer.externalInstance, planned.project.root, peer.id)) throw new Error("invalid retained external module instance binding");
+    }
     if (progress.repairedSessions !== undefined) {
       if (!object(progress.repairedSessions)) throw new Error("invalid repaired session provenance");
       for (const [peer, protectedSession] of Object.entries(progress.repairedSessions)) {
@@ -559,6 +571,45 @@ export interface RecoveryDriver {
   now(): number;
   /** Trusted per-invocation delegation, supplied only by the CLI's identity preflight. */
   readonly liveTestPeer?: string;
+  /** Trusted actor from the live conductor preflight; receipt audit rows confer no authority. */
+  readonly conductorPeer?: string;
+  /** Host-only current authority proof for this exact operation and every affected project. */
+  authorize?(op: RecoveryOperation, phase: "run" | "abort" | "effect"): Promise<void>;
+}
+
+async function authorizeRecoveryDriver(driver: RecoveryDriver, op: RecoveryOperation, phase: "run" | "abort" | "effect"): Promise<void> {
+  if (driver.conductorPeer === undefined) return;
+  if (!validRecoveryDelegation({ peer: driver.conductorPeer, command: "recovery-run" }) || typeof driver.authorize !== "function") throw new Error("conductor recovery authorization unavailable");
+  await driver.authorize(op, phase);
+}
+
+/** Closed effect ports only. Inspection stays read-only; person drivers keep their existing behavior. */
+export function guardedRecoveryDriver(driver: RecoveryDriver, operation: () => RecoveryOperation): RecoveryDriver {
+  if (driver.conductorPeer === undefined) return driver;
+  const guard = <A extends unknown[], R>(action: (...args: A) => Promise<R>) => async (...args: A): Promise<R> => {
+    await authorizeRecoveryDriver(driver, operation(), "effect");
+    try { return await action(...args); }
+    finally { await authorizeRecoveryDriver(driver, operation(), "effect"); }
+  };
+  return {
+    ...driver,
+    stage: guard((...args: Parameters<RecoveryDriver["stage"]>) => driver.stage(...args)),
+    prepare: guard((...args: Parameters<RecoveryDriver["prepare"]>) => driver.prepare(...args)),
+    abort: guard((...args: Parameters<RecoveryDriver["abort"]>) => driver.abort(...args)),
+    commit: guard((...args: Parameters<RecoveryDriver["commit"]>) => driver.commit(...args)),
+    closeTerminals: guard((...args: Parameters<RecoveryDriver["closeTerminals"]>) => driver.closeTerminals(...args)),
+    start: guard((...args: Parameters<RecoveryDriver["start"]>) => driver.start(...args)),
+    restore: guard((...args: Parameters<RecoveryDriver["restore"]>) => driver.restore(...args)),
+    installPlugin: guard((...args: Parameters<RecoveryDriver["installPlugin"]>) => driver.installPlugin(...args)),
+    installGlobal: guard((...args: Parameters<RecoveryDriver["installGlobal"]>) => driver.installGlobal(...args)),
+    ...(driver.refreshManager ? { refreshManager: guard((op: RecoveryOperation) => driver.refreshManager!(op)) } : {}),
+    release: guard((...args: Parameters<RecoveryDriver["release"]>) => driver.release(...args)),
+    verify: guard((...args: Parameters<RecoveryDriver["verify"]>) => driver.verify(...args)),
+    stopAndArchive: guard((...args: Parameters<RecoveryDriver["stopAndArchive"]>) => driver.stopAndArchive(...args)),
+    inspect: (...args) => driver.inspect(...args),
+    ...(driver.recordedSessionState ? { recordedSessionState: (binding: TerminalBinding, kind: "rollout" | "transcript") => driver.recordedSessionState!(binding, kind) } : {}),
+    sleep: ms => driver.sleep(ms), now: () => driver.now(),
+  };
 }
 
 /** Resumable state machine. Driver actions are preceded by receipts and followed by live readback. */
@@ -567,6 +618,7 @@ export async function runRecovery(id: string, driver: RecoveryDriver, home = hub
   // mutable phase. A concurrent runner may have completed the operation meanwhile.
   let op = readOperation<RecoveryOperation>(id, home);
   validateReceipt(id, op);
+  if (driver.conductorPeer !== undefined) await authorizeRecoveryDriver(driver, op, "run");
   acquireRecoveryLock(id, home);
   const releaseRunner = claimRunner(id, home);
   try {
@@ -577,11 +629,13 @@ export async function runRecovery(id: string, driver: RecoveryDriver, home = hub
       releaseRunner();
       return op;
     }
-    if (driver.liveTestPeer) {
-      appendRecoveryDelegation(op, { peer: driver.liveTestPeer, command: "recovery-run" }, driver.now());
+    if (driver.conductorPeer !== undefined) await authorizeRecoveryDriver(driver, op, "run");
+    if (driver.conductorPeer ?? driver.liveTestPeer) {
+      appendRecoveryDelegation(op, { peer: (driver.conductorPeer ?? driver.liveTestPeer)!, command: "recovery-run" }, driver.now());
       writeOperation(id, op, home);
     }
   } catch (error) { releaseRunner(); throw error; }
+  driver = guardedRecoveryDriver(driver, () => op);
   let targetFeatures: readonly string[] = [];
   const save = () => { op.updatedAt = driver.now(); writeOperation(id, op, home); };
   const step = (value: string) => { op.step = value; save(); };
@@ -867,6 +921,7 @@ export function publicOperation(op: RecoveryOperation, runnerPid?: number | "unk
  * release, installation or completion. A later normal resume owns those steps.
  */
 export async function reattachRecovery(id: string, peer: string, driver: RecoveryDriver, home = hubHome()): Promise<RecoveryOperation> {
+  if (driver.conductorPeer !== undefined) throw new Error("recovery reattachment is person-only");
   let op = readOperation<RecoveryOperation>(id, home);
   validateReceipt(id, op);
   const selection = () => {
@@ -929,6 +984,7 @@ export async function reattachRecovery(id: string, peer: string, driver: Recover
 export async function abortRecovery(id: string, driver: RecoveryDriver, home = hubHome()): Promise<void> {
   let op = readOperation<RecoveryOperation>(id, home);
   validateReceipt(id, op, true);
+  if (driver.conductorPeer !== undefined) await authorizeRecoveryDriver(driver, op, "abort");
   acquireRecoveryLock(id, home);
   const releaseRunner = claimRunner(id, home);
   try {
@@ -940,10 +996,12 @@ export async function abortRecovery(id: string, driver: RecoveryDriver, home = h
       if (recoveryLock(home) === id) releaseRecoveryLock(id, home);
       return;
     }
-    if (driver.liveTestPeer) {
-      appendRecoveryDelegation(op, { peer: driver.liveTestPeer, command: "recovery abort" }, driver.now());
+    if (driver.conductorPeer !== undefined) await authorizeRecoveryDriver(driver, op, "abort");
+    if (driver.conductorPeer ?? driver.liveTestPeer) {
+      appendRecoveryDelegation(op, { peer: (driver.conductorPeer ?? driver.liveTestPeer)!, command: "recovery abort" }, driver.now());
       writeOperation(id, op, home);
     }
+    driver = guardedRecoveryDriver(driver, () => op);
     if (abandoned(op)) writeOperation(id, op, home);
     const { fingerprint, ...body } = op.plan;
     if (fingerprint !== planFingerprint(body)) throw new Error("operation plan changed");
@@ -971,6 +1029,7 @@ export async function abortRecovery(id: string, driver: RecoveryDriver, home = h
  * every runtime this operation held or started is verified released or stopped.
  */
 export async function disposeRecovery(id: string, choice: { fresh: string } | { stop: true }, reason: string, driver: RecoveryDriver, home = hubHome()): Promise<RecoveryOperation> {
+  if (driver.conductorPeer !== undefined) throw new Error("recovery disposition is person-only");
   let op: RecoveryOperation;
   try { op = readOperation<RecoveryOperation>(id, home); validateReceipt(id, op, "stop" in choice); }
   catch (error) { if (driver.liveTestPeer && "fresh" in choice) throw new Error(LIVE_TEST_PERSON_REFUSAL); throw error; }