@staix/agent-hub 0.12.34 → 0.12.35

package/src/cli/terminal-recovery.ts

@@ -1,6 +1,9 @@
 import { shellQuote } from "./shell-quote.ts";
 export { shellQuote } from "./shell-quote.ts";
-import { definitionOf } from "../adapters/registry.ts";
+import { definitionOf, type KindMap } from "../adapters/registry.ts";
+import { readInstanceConfig, readInstanceRoleConfig } from "../hub/instance-config.ts";
+import { effectiveInstanceRoles } from "../hub/instances.ts";
+import { resolveInstanceExecutionCwd } from "../hub/instance-execution.ts";
 import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
@@ -28,7 +31,7 @@ export type CommandRunner = (argv: readonly string[]) => Promise<CommandResult>;
 /** Stable process identity hook. It returns a digest, never raw process metadata. */
 export type ProcessIdentity = (pid: number) => string | undefined | Promise<string | undefined>;
 
-export type TerminalPeer = "codex" | "claude" | "pi";
+export type TerminalPeer = string;
 export interface SessionRef { sessionId: string; sessionFile?: string; backend?: string; model?: string; }
 
 export interface LaunchMetadata {
@@ -48,6 +51,10 @@ export interface TerminalBinding {
   incarnationId: string;
   worktreeId: string;
   projectRoot: string;
+  /** Authenticated declared-extra execution root; canonical projectRoot remains the authority. */
+  executionCwd?: string;
+  /** Verified Orca grouping root, only canonical project or the authorized execution worktree. */
+  terminalRoot?: string;
   sessionId: string;
   sessionFile?: string;
   backend?: string;
@@ -129,6 +136,8 @@ export interface TerminalCreateResult {
 
 export interface TerminalRecoveryOptions {
   runner?: CommandRunner;
+  /** Exact execution root returned by authenticated extra startup; checked against the current declaration. */
+  executionCwd?: string;
   /** Defaults to `orca`; callers in a managed session may pin another executable. */
   orcaExecutable?: string;
   /** Absolute path to this package's JS entrypoint. */
@@ -150,6 +159,8 @@ export interface TerminalRecoveryOptions {
 export interface RecordedTerminalLaunch {
   peer: TerminalPeer;
   projectRoot: string;
+  executionCwd?: string;
+  terminalRoot?: string;
   stateDir: string;
   instanceId: string;
   launcherPid: number;
@@ -243,6 +254,7 @@ function normalizeOptions(options?: CommandRunner | TerminalRecoveryOptions): Re
     runner: config.runner ?? defaultRunner(orcaExecutable),
     orcaExecutable,
     packageEntrypoint: config.packageEntrypoint ?? defaultEntrypoint,
+    executionCwd: config.executionCwd ?? "",
     stateDir: config.stateDir ?? "",
     instanceId: config.instanceId ?? "",
     processIdentity: config.processIdentity ?? defaultProcessIdentity,
@@ -312,9 +324,30 @@ export function recordPath(stateDir: string): string {
   return join(stateDir, RECORD_FILE);
 }
 
+/** Extra terminal ownership is supported only for the native proxy transport; other I2 extras stay headless. */
+function executionRoot(peer: string, projectRoot: string, captured?: string): string {
+  const builtin = definitionOf(peer);
+  if (builtin?.session.launchRecord) return projectRoot;
+  const { instances: declarations, roles } = readInstanceRoleConfig(projectRoot);
+  const definition = definitionOf(peer, declarations);
+  if (!definition?.session.launchRecord) throw new Error(`${peer}: no managed terminal recovery adapter`);
+  if (definition.transport !== "codex-appserver" || !declarations?.[peer]) throw new Error(`${peer}: I2 extra instance has no managed terminal support`);
+  const expected = resolveInstanceExecutionCwd(projectRoot, peer, declarations, effectiveInstanceRoles(peer, declarations, roles));
+  if (captured !== undefined && captured !== expected) throw new Error(`${peer}: declared execution worktree changed; manual recovery required`);
+  return expected;
+}
+
+function savedTerminalRoot(binding: Pick<TerminalBinding, "peer" | "projectRoot" | "executionCwd" | "terminalRoot">): string {
+  const expected = executionRoot(binding.peer, binding.projectRoot, binding.executionCwd ?? binding.projectRoot);
+  if (definitionOf(binding.peer)) return binding.projectRoot;
+  const root = binding.terminalRoot ?? binding.projectRoot;
+  if (root !== binding.projectRoot && root !== expected) throw new Error(`${binding.peer}: recorded Orca grouping root is not authorized`);
+  return root;
+}
+
 function validRecord(item: unknown): item is RecordedTerminalLaunch {
   const row = object(item);
-  return typeof row.peer === "string" && typeof row.projectRoot === "string" && typeof row.instanceId === "string" && typeof row.handle === "string" && typeof row.incarnationId === "string" && typeof row.worktreeId === "string" && typeof row.launcherPid === "number" && typeof row.launcherSignature === "string" && row.launcherSignature.length > 0 && typeof row.launchId === "string" && row.launchId.length > 0;
+  return typeof row.peer === "string" && typeof row.projectRoot === "string" && (row.executionCwd === undefined || typeof row.executionCwd === "string") && (row.terminalRoot === undefined || typeof row.terminalRoot === "string") && typeof row.instanceId === "string" && typeof row.handle === "string" && typeof row.incarnationId === "string" && typeof row.worktreeId === "string" && typeof row.launcherPid === "number" && typeof row.launcherSignature === "string" && row.launcherSignature.length > 0 && typeof row.launchId === "string" && row.launchId.length > 0;
 }
 
 /**
@@ -410,13 +443,15 @@ export async function recordTerminalLaunch(peer: TerminalPeer, projectRoot: stri
   const handle = process.env.ORCA_TERMINAL_HANDLE;
   const worktreeIdFromEnv = process.env.ORCA_WORKTREE_ID;
   if (!handle || !worktreeIdFromEnv) return undefined;
+  if (!definitionOf(peer) && !config.executionCwd) throw new Error(`${peer}: recording an extra terminal requires its authenticated startup execution root`);
+  const expectedRoot = executionRoot(peer, projectRoot, config.executionCwd || undefined);
   const value = await run(config.runner, ["terminal", "show", "--terminal", handle, "--json"]);
   const terminal = terminalObject(value);
   const actualRoot = nestedString(terminal, ["worktreePath", "projectRoot"]);
   const actualHandle = nestedString(terminal, ["handle"]);
   const actualWorktree = nestedString(terminal, ["worktreeId"]);
   const incarnationId = nestedString(terminal, ["incarnationId"]);
-  if (actualHandle !== handle || !actualRoot || !rootMatches(actualRoot, projectRoot) || actualWorktree !== worktreeIdFromEnv || !incarnationId) {
+  if (actualHandle !== handle || !actualRoot || !(rootMatches(actualRoot, projectRoot) || !definitionOf(peer) && rootMatches(actualRoot, expectedRoot)) || actualWorktree !== worktreeIdFromEnv || !incarnationId) {
     throw new OrcaCommandError(blocker("project-root-mismatch", "Orca launch terminal failed canonical root/worktree readback", peer, handle));
   }
   const launcherSignature = await config.processIdentity(process.pid);
@@ -424,7 +459,7 @@ export async function recordTerminalLaunch(peer: TerminalPeer, projectRoot: stri
   const launchId = randomUUID();
   process.env.AGENTHUB_LAUNCH_ID = launchId;
   process.env.AGENTHUB_INSTANCE_ID = instanceId;
-  const row: RecordedTerminalLaunch = { peer, projectRoot, stateDir, instanceId, launcherPid: process.pid, launcherSignature, launchId, handle, incarnationId, worktreeId: actualWorktree, env: allowedEnv({ env: process.env }) };
+  const row: RecordedTerminalLaunch = { peer, projectRoot, ...(!definitionOf(peer) ? { executionCwd: expectedRoot, terminalRoot: actualRoot } : {}), stateDir, instanceId, launcherPid: process.pid, launcherSignature, launchId, handle, incarnationId, worktreeId: actualWorktree, env: allowedEnv({ env: process.env }) };
   const existing = launchRecords(stateDir);
   // #215: rewriting an unreadable file would replace every other launcher's record with this one, and recovery would
   // then read those launchers as gone.
@@ -470,12 +505,12 @@ function sessionFrom(terminal: Record<string, unknown>): string | undefined {
   return nestedString(terminal, ["sessionId", "agentSessionId", "resumeSessionId"]) ?? nestedString(wait, ["sessionId", "agentSessionId", "resumeSessionId", "session", "agentSession"]) ?? nestedString(session, ["id", "sessionId"]);
 }
 
-function identityFrom(terminal: Record<string, unknown>): TerminalPeer | undefined {
+function identityFrom(terminal: Record<string, unknown>, instances?: KindMap): TerminalPeer | undefined {
   const wait = object(terminal.agentWait);
   const session = object(terminal.session);
   const candidates = [terminal.agentIdentity, terminal.agent, wait.agentIdentity, wait.agent, session.agentIdentity, session.agent];
   for (const candidate of candidates) {
-    if (typeof candidate === "string" && definitionOf(candidate)?.session.launchRecord) return candidate as TerminalPeer;
+    if (typeof candidate === "string" && definitionOf(candidate, instances)?.session.launchRecord) return candidate as TerminalPeer;
   }
   return undefined;
 }
@@ -513,7 +548,9 @@ function launchFor(peer: TerminalPeer, projectRoot: string, sessionId: string, o
   const binding: TerminalBinding = { peer, projectRoot, sessionId, handle: nestedString(source, ["handle"])!,
     incarnationId: nestedString(source, ["incarnationId"])!, worktreeId: nestedString(source, ["worktreeId"])!,
     ...(ref?.sessionFile ? { sessionFile: ref.sessionFile } : {}), ...(ref?.backend ? { backend: ref.backend } : {}), ...(ref?.model ? { model: ref.model } : {}), launch, launchMetadata: launch };
-  const tail = definitionOf(peer)?.session.resumeArgv?.(binding, false);
+  const adapter = definitionOf(peer) ?? definitionOf(peer, readInstanceConfig(projectRoot).instances);
+  const nativeTail = adapter?.session.resumeArgv?.(binding, false);
+  const tail = nativeTail && adapter ? [nativeTail[0]!, ...(peer !== adapter.kind ? ["--as", peer] : []), ...nativeTail.slice(1)] : undefined;
   if (!tail) throw new Error(`${peer}: no recorded terminal resume adapter`);
   const argv = [...launch.argv, ...tail];
   const command = [...prefix, ...argv.map(shellQuote)].join(" ");
@@ -538,7 +575,10 @@ function verifyBindingData(actual: Record<string, unknown>, binding: TerminalBin
   const root = nestedString(actual, ["worktreePath", "projectRoot"]);
   const worktree = nestedString(actual, ["worktreeId"]);
   if (handle !== binding.handle || incarnation !== binding.incarnationId || worktree !== binding.worktreeId) return blocker("stale-terminal", "captured terminal identity changed; refusing to mutate it", binding.peer, binding.handle);
-  if (!rootMatches(root, binding.projectRoot)) return blocker("project-root-mismatch", "terminal belongs to a different project root; refusing to mutate it", binding.peer, binding.handle);
+  let expectedRoot: string;
+  try { expectedRoot = savedTerminalRoot(binding); }
+  catch { return blocker("project-root-mismatch", "declared terminal execution root changed or is unavailable; refusing to mutate it", binding.peer, binding.handle); }
+  if (!rootMatches(root, expectedRoot)) return blocker("project-root-mismatch", "terminal belongs to a different project root; refusing to mutate it", binding.peer, binding.handle);
   return undefined;
 }
 
@@ -560,6 +600,7 @@ export async function inspectSavedTerminal(binding: TerminalBinding, options?: C
   const completeIdentity = (value: Record<string, unknown>) =>
     [nestedString(value, ["handle"]), nestedString(value, ["incarnationId"]), nestedString(value, ["worktreeId"]), nestedString(value, ["worktreePath", "projectRoot"])].every(Boolean);
   try {
+    savedTerminalRoot(binding);
     const shown = terminalObject(await run(config.runner, ["terminal", "show", "--terminal", binding.handle, "--json"]));
     if (!completeIdentity(shown)) return unknown();
     const issue = verifyBindingData(shown, binding);
@@ -603,6 +644,7 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
   const byPeer: Partial<Record<TerminalPeer, TerminalBinding>> = {};
   const requested = (Object.entries(sessions) as [TerminalPeer, string | SessionRef | undefined][]).map(([peer, value]) => [peer, typeof value === "string" ? { sessionId: value } : value] as const).filter((entry): entry is [TerminalPeer, SessionRef] => !!entry[1]?.sessionId);
   if (!requested.length) return { bindings, byPeer, blockers, manualRequired: false };
+  const instances = requested.some(([peer]) => definitionOf(peer) === undefined) ? readInstanceConfig(projectRoot).instances : undefined;
   // #215: without the records a terminal could be bound from Orca metadata alone, losing the launch's captured
   // CODEX_HOME or CLAUDE_CONFIG_DIR: an unreadable file blocks the binding, never reads as "no records".
   const rows = launchRecords(config.stateDir);
@@ -619,6 +661,15 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
 
   for (const [peer, ref] of requested) {
     const sessionId = ref.sessionId;
+    const adapter = definitionOf(peer, instances), extra = definitionOf(peer) === undefined;
+    if (!adapter?.session.launchRecord || extra && adapter.transport !== "codex-appserver") { blockers.push(blocker("ownership-unknown", `${peer}: no declared managed-terminal recovery adapter`, peer)); continue; }
+    const ownRecord = records.find(item => item.peer === peer);
+    let expectedRoot: string, expectedTerminalRoot: string;
+    try {
+      expectedRoot = executionRoot(peer, projectRoot, ownRecord?.executionCwd ?? projectRoot);
+      expectedTerminalRoot = savedTerminalRoot({ peer, projectRoot, executionCwd: ownRecord?.executionCwd, terminalRoot: ownRecord?.terminalRoot });
+    }
+    catch { blockers.push(blocker("ownership-unknown", `${peer}: declared execution worktree changed or is unverified`, peer)); continue; }
     // #215: a launcher whose identity cannot be read may be this peer's: binding from Orca metadata would lose its launch.
     const unread = unknown.find((item) => item.peer === peer);
     if (unread) {
@@ -629,7 +680,7 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
       blockers.push(blocker("ownership-unknown", `${recordPath(config.stateDir)} holds a launch record that cannot be evaluated and may be this ${peer} launcher's, so no terminal can be bound to its launch; next action: inspect that row and fix it, or end that launcher and remove its row, then plan or resume again`, peer));
       continue;
     }
-    const candidates = listed.filter((terminal) => rootMatches(terminal.worktreePath ?? terminal.projectRoot, projectRoot));
+    const candidates = listed.filter((terminal) => rootMatches(terminal.worktreePath ?? terminal.projectRoot, expectedTerminalRoot));
     const peerCandidates: Record<string, unknown>[] = [];
     for (const listedTerminal of candidates) {
       const handle = nestedString(listedTerminal, ["handle"]);
@@ -642,16 +693,16 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
         continue;
       }
       // A show readback is required; list can be stale between recovery steps.
-      if (!rootMatches(terminal.worktreePath ?? terminal.projectRoot, projectRoot)) continue;
-      const identity = identityFrom(terminal);
+      if (!rootMatches(terminal.worktreePath ?? terminal.projectRoot, expectedTerminalRoot)) continue;
+      const identity = identityFrom(terminal, instances);
       const terminalSession = sessionFrom(terminal);
       const recorded = records.find((item) => item.peer === peer && item.handle === handle && item.worktreeId === terminal.worktreeId && item.incarnationId === terminal.incarnationId);
       // A recorded launcher proves ownership; the daemon's supplied session id is the
       // authoritative session id when Orca omits it from terminal metadata.
-      if ((identity === peer && terminalSession === sessionId) || (recorded !== undefined && (identity === undefined || identity === peer) && (terminalSession === undefined || terminalSession === sessionId))) peerCandidates.push(terminal);
+      if ((!extra && identity === peer && terminalSession === sessionId) || (recorded !== undefined && (identity === undefined || identity === peer || extra && identity === adapter.kind) && (terminalSession === undefined || terminalSession === sessionId))) peerCandidates.push(terminal);
     }
     if (!peerCandidates.length) {
-      const ownershipUnknown = candidates.some((terminal) => identityFrom(terminal) === undefined && !records.some((item) => item.handle === terminal.handle));
+      const ownershipUnknown = candidates.some((terminal) => identityFrom(terminal, instances) === undefined && !records.some((item) => item.handle === terminal.handle));
       blockers.push(ownershipUnknown
         ? blocker("ownership-unknown", `cannot prove ${peer} terminal ownership from Orca metadata`, peer)
         : blocker("missing-terminal", `no ${peer} terminal with session ${sessionId} in ${projectRoot}`, peer));
@@ -676,9 +727,9 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
     const recorded = records.find((item) => item.peer === peer && item.handle === handle && item.worktreeId === terminal.worktreeId && item.incarnationId === terminal.incarnationId);
     // Orca observation supplies file identity; launch arguments are not observed native session-file evidence.
     const { args: _launchArgs, ...observedTerminal } = terminal;
-    const sessionFile = definitionOf(peer)?.session.crashIdentity?.(observedTerminal).sessionFile;
+    const sessionFile = definitionOf(peer, instances)?.session.crashIdentity?.(observedTerminal).sessionFile;
     const launch = launchFor(peer, projectRoot, sessionId, config, terminal, recorded, { ...ref, ...(sessionFile ? { sessionFile } : {}) });
-    const binding: TerminalBinding = { peer, handle, incarnationId, worktreeId, projectRoot, sessionId, ...(sessionFile ? { sessionFile } : {}), ...(ref.backend ? { backend: ref.backend } : {}), ...(ref.model ? { model: ref.model } : {}), launch, launchMetadata: launch };
+    const binding: TerminalBinding = { peer, handle, incarnationId, worktreeId, projectRoot, ...(extra ? { executionCwd: expectedRoot, terminalRoot: expectedTerminalRoot } : {}), sessionId, ...(sessionFile ? { sessionFile } : {}), ...(ref.backend ? { backend: ref.backend } : {}), ...(ref.model ? { model: ref.model } : {}), launch, launchMetadata: launch };
     bindings.push(binding);
     byPeer[peer] = binding;
   }
@@ -750,6 +801,7 @@ export async function createTerminal(binding: TerminalBinding, options?: Command
   const config = normalizeOptions(options);
   let made: string | undefined; // a later failure must still report the terminal it created
   try {
+    savedTerminalRoot(binding);
     const worktreeSelector = binding.worktreeId.startsWith("id:") ? binding.worktreeId : `id:${binding.worktreeId}`;
     // The coordinator journals a pending creation before this call and reconciles
     // it on resume. Other agents in the worktree do not imply a prior create.

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

@@ -1,4 +1,5 @@
 import { definitionOf } from "../adapters/registry.ts";
+import { readInstanceConfig } from "../hub/instance-config.ts";
 import type { TerminalBinding } from "./terminal-recovery.ts";
 
 export type RestoreReceipt =
@@ -23,10 +24,16 @@ export type RestoreReceiptStatus = "unstarted" | "pending" | "waiting:pending" |
 function malformed(): never { throw new Error("invalid restore receipt"); }
 const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
 const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
-function terminalBinding(value: unknown): TerminalBinding {
-  if (!object(value) || typeof value.peer !== "string" || !definitionOf(value.peer)?.session.launchRecord) malformed();
+function terminalBinding(value: unknown, historical = false): TerminalBinding {
+  if (!object(value) || typeof value.peer !== "string") malformed();
   for (const key of ["handle", "incarnationId", "worktreeId", "projectRoot", "sessionId"]) if (!text(value[key])) malformed();
-  for (const key of ["sessionFile", "backend", "model"]) if (value[key] !== undefined && typeof value[key] !== "string") malformed();
+  if (historical) {
+    if (!/^[a-z][a-z0-9-]{0,31}$/.test(value.peer)) malformed();
+  } else try {
+    const adapter = definitionOf(value.peer) ?? definitionOf(value.peer, readInstanceConfig(value.projectRoot as string).instances);
+    if (!adapter?.session.launchRecord) malformed();
+  } catch { malformed(); }
+  for (const key of ["sessionFile", "backend", "model", "executionCwd", "terminalRoot"]) if (value[key] !== undefined && typeof value[key] !== "string") malformed();
   const launch = value.launch;
   const validLaunch = (v: unknown) => object(v) && text(v.packageEntrypoint) && text(v.command)
     && Array.isArray(v.argv) && v.argv.every(arg => typeof arg === "string")
@@ -36,7 +43,9 @@ function terminalBinding(value: unknown): TerminalBinding {
 }
 
 /** Decode legacy representations only here. Absence is unstarted, never pending or failed. */
-export function decodeRestoreReceipt(value: unknown): RestoreReceipt | undefined {
+export function decodeRestoreReceipt(value: unknown, options: { authority?: "current" | "historical" } = {}): RestoreReceipt | undefined {
+  // Historical decoding proves receipt structure only, never current permission to launch or replace a peer.
+  const historical = options.authority === "historical";
   if (value === undefined) return undefined;
   if (value === "pending" || value === "failed") return { state: value };
   if (!object(value)) malformed();
@@ -47,14 +56,14 @@ export function decodeRestoreReceipt(value: unknown): RestoreReceipt | undefined
       case "pending": case "failed": return { state: value.state };
       case "waiting": {
         if (value.origin !== "pending" && value.origin !== "failed") malformed();
-        return { state: "waiting", origin: value.origin, binding: terminalBinding(value.binding) };
+        return { state: "waiting", origin: value.origin, binding: terminalBinding(value.binding, historical) };
       }
-      case "done": return { state: "done", binding: terminalBinding(value.binding) };
+      case "done": return { state: "done", binding: terminalBinding(value.binding, historical) };
       default: return malformed();
     }
   }
   if (Object.hasOwn(value, "attachmentReceipt")) malformed();
-  return { state: "done", binding: terminalBinding(value) };
+  return { state: "done", binding: terminalBinding(value, historical) };
 }
 
 export function restoreReceiptStatus(value: unknown): RestoreReceiptStatus {

package/src/cli/upgrade-runtime.ts

@@ -1,5 +1,6 @@
 import { resolveAcceptedBinding } from "./recovery-guidance.ts";
 import { ADAPTERS, definitionOf } from "../adapters/registry.ts";
+import { readInstanceConfig } from "../hub/instance-config.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";
@@ -32,13 +33,16 @@ const attachedBinding = (binding: TerminalBinding, sessionId: string): TerminalB
 export const PACKAGE_ROOT = resolve(import.meta.dir, "../..");
 const orcaExecutable = () => process.env.ORCA_CLI_COMMAND || (process.env.ORCA_DEV_REPO_ROOT ? "orca-dev" : process.platform === "linux" && !process.env.ORCA_TERMINAL_HANDLE ? "orca-ide" : "orca");
 
+/** Definitions are resolved against the owning project's current trusted declarations, never a global instance map. */
+const projectDefinition = (peer: string, projectRoot: string) => definitionOf(peer) ?? definitionOf(peer, readInstanceConfig(projectRoot).instances);
+
 const sessionState = (binding: TerminalBinding): "found" | "missing" | "unknown" => {
-  const state = definitionOf(binding.peer)?.session.transcriptExists?.(binding);
+  const state = projectDefinition(binding.peer, binding.projectRoot)?.session.transcriptExists?.(binding);
   return state === "unknown" ? "unknown" : state === false ? "missing" : "found";
 };
-const sessionPath = (binding: TerminalBinding) => definitionOf(binding.peer)?.session.transcriptPath?.(binding);
-export const observedSession = (peer: string, value: RecoveryPeer | undefined) => value?.[definitionOf(peer)?.session.idField ?? "sessionId"];
-const nativeZeroTurn = (stateDir: string, binding: TerminalBinding, phase: "plan" | "attach" | "verify") => definitionOf(binding.peer)?.session.zeroTurn?.({ stateDir, binding, phase }) === true;
+const sessionPath = (binding: TerminalBinding) => projectDefinition(binding.peer, binding.projectRoot)?.session.transcriptPath?.(binding);
+export const observedSession = (peer: string, value: RecoveryPeer | undefined, projectRoot?: string) => value?.[(projectRoot ? projectDefinition(peer, projectRoot) : definitionOf(peer))?.session.idField ?? "sessionId"];
+const nativeZeroTurn = (stateDir: string, binding: TerminalBinding, phase: "plan" | "attach" | "verify") => projectDefinition(binding.peer, binding.projectRoot)?.session.zeroTurn?.({ stateDir, binding, phase }) === true;
 const unresumable = (binding: TerminalBinding) => sessionState(binding) === "unknown"
   ? `codex: the session store ${sessionPath(binding)} cannot be read, so whether thread ${binding.sessionId} can resume is unknown`
   : `codex: thread ${binding.sessionId} has no resumable transcript under ${sessionPath(binding)}`;
@@ -64,7 +68,9 @@ function terminalOptions(run: RunCommand = runCommand): TerminalRecoveryOptions
 
 /** `fresh` (#215: the operator's choice, or a planned fresh start) starts Codex or Claude without resuming its recorded session. */
 export function restoredTerminalArgv(entrypoint: string, projectRoot: string, binding: TerminalBinding, fresh = false): string[] {
-  const tail = definitionOf(binding.peer)?.session.resumeArgv?.(binding, fresh);
+  const adapter = projectDefinition(binding.peer, binding.projectRoot);
+  const nativeTail = adapter?.session.resumeArgv?.(binding, fresh);
+  const tail = nativeTail && adapter ? [nativeTail[0]!, ...(binding.peer !== adapter.kind ? ["--as", binding.peer] : []), ...nativeTail.slice(1)] : undefined;
   if (!tail) throw new Error(`${binding.peer}: no recorded terminal resume adapter`);
   return [process.execPath, entrypoint, "--project", projectRoot, ...tail];
 }
@@ -108,9 +114,9 @@ export async function endPlannedPeer(planned: PlannedProject, peer: RecoveryPeer
     // The hub holds what a peer that goes offline mid-turn was working on (`uncertain` in bus.ts).
     if (now.state === "busy") cut = "; its turn was cut: a delivery it had not settled is held as needs_review, and its queue stays held until ahub queue resolve";
     if (binding) {
-      if (observedSession(binding.peer, now) !== binding.sessionId) return refused(`the session attached now is not the one the plan bound to terminal ${binding.handle}`);
+      if (observedSession(binding.peer, now, binding.projectRoot) !== binding.sessionId) return refused(`the session attached now is not the one the plan bound to terminal ${binding.handle}`);
       // The same question the plan asked (`makeUpgradePlan`), for this one peer.
-      const session = definitionOf(binding.peer)?.session.crashIdentity ? { sessionId: binding.sessionId, ...(now.sessionFile ? { sessionFile: now.sessionFile } : {}), ...(now.args?.backend ? { backend: now.args.backend } : {}), ...(now.args?.model ? { model: now.args.model } : {}) } : binding.sessionId;
+      const session = projectDefinition(binding.peer, binding.projectRoot)?.session.crashIdentity ? { sessionId: binding.sessionId, ...(now.sessionFile ? { sessionFile: now.sessionFile } : {}), ...(now.args?.backend ? { backend: now.args.backend } : {}), ...(now.args?.model ? { model: now.args.model } : {}) } : binding.sessionId;
       const found = await inspectTerminals(planned.project.root, { [binding.peer]: session }, { ...terminalOptions(run), stateDir: planned.project.stateDir, instanceId: planned.source.instanceId });
       current = found.byPeer[binding.peer];
       if (found.manualRequired || !current) return refused(`its terminal cannot be bound again: ${found.blockers[0]?.message ?? "no terminal was found"}`);
@@ -135,7 +141,20 @@ export async function endPlannedPeer(planned: PlannedProject, peer: RecoveryPeer
   }
 }
 
-export async function inspectRecovery(project: Project, targetFeatures?: readonly string[]): Promise<Inspection> {
+/** 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 declared = Object.keys(readInstanceConfig(projectRoot).instances ?? {});
+  if (!declared.length) return undefined;
+  if (Array.isArray(features) && features.every(feature => typeof feature === "string") && features.includes("peer_instances")) return undefined;
+  if (observedPeers && typeof observedPeers === "object" && !Array.isArray(observedPeers)) {
+    const peers = Object.entries(observedPeers);
+    if (peers.every(([, peer]) => !!peer && typeof peer === "object" && typeof (peer as { state?: unknown }).state === "string") &&
+      !peers.some(([id, peer]) => declared.includes(id) && (peer as { state: string }).state !== "offline")) return undefined;
+  }
+  return "source lacks peer_instances support for this project's declared instances; restart the source with a supporting agent-hub version before retrying recovery; for a first upgrade, end any extra native sessions and temporarily remove the instance declarations, upgrade the source, then declare them again; legacy peer identities were not reinterpreted";
+}
+
+export async function inspectRecovery(project: Project, targetFeatures?: readonly string[], purpose?: "cleanup"): 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.
@@ -181,6 +200,8 @@ export async function inspectRecovery(project: Project, targetFeatures?: readonl
     }
   }
   if (!status || !control) return { state: "unavailable", peers: [], blockers: ["authenticated source status unavailable"] };
+  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); }
   catch (error) {
@@ -232,7 +253,7 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
     const reconnectOnly: string[] = [];
     for (const peer of source.peers) {
       if (peer.state === "offline") continue;
-      const adapter = definitionOf(peer.id);
+      const adapter = projectDefinition(peer.id, project.root);
       const refusal = adapter?.session.recoveryRefusal?.(peer);
       if (refusal) { blockers.push(refusal); continue; }
       if (adapter?.transport === "claude-channel") {
@@ -263,7 +284,7 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
         }
       }
       if (adapter?.session.launchRecord && (!adapter.session.restoreArgs || peer.args?.mode === "tui")) {
-        const session = observedSession(peer.id, peer);
+        const session = observedSession(peer.id, peer, project.root);
         if (!session) blockers.push(adapter.session.crashIdentity
           ? `${peer.id}: original session ID is unknown; manual-required; next action: reconnect the original ${adapter.displayName} session and make a new recovery plan`
           : `${peer.id}: original conversation ID is unknown; manual-required; next action: reconnect the original native session and make a new recovery plan`);
@@ -279,7 +300,7 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
     });
     blockers.push(...terminals.blockers.map((b) => `${b.message}${b.terminalReference ? ` (terminal ${b.terminalReference})` : ""}${b.nextAction ? `; next action: ${b.nextAction}` : ""}`));
     const freshStart: string[] = [];
-    for (const binding of terminals.bindings) if (definitionOf(binding.peer)?.session.missingEvidence === "rollout") {
+    for (const binding of terminals.bindings) if (projectDefinition(binding.peer, binding.projectRoot)?.session.missingEvidence === "rollout") {
       const transcript = sessionState(binding);
       if (transcript === "found") continue;
       if (transcript === "missing" && nativeZeroTurn(project.stateDir, binding, "plan")) { freshStart.push(binding.peer); continue; }
@@ -333,7 +354,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       const bindings = op.plan.projects.find((p) => p.project.id === project.id)?.terminals as TerminalBinding[] | undefined;
       for (const binding of bindings ?? []) {
         // Preserve the captured legacy profile for terminal bindings without a dedicated native config variable.
-        const key = definitionOf(binding.peer)?.session.configDirEnv ?? "CLAUDE_CONFIG_DIR";
+        const key = projectDefinition(binding.peer, binding.projectRoot)?.session.configDirEnv ?? "CLAUDE_CONFIG_DIR";
         if (binding.launch.env[key]) value[key] = binding.launch.env[key];
       }
     }
@@ -365,8 +386,8 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     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 });
     const peer = observed.peers.find((item) => item.id === saved.peer);
-    const session = observedSession(saved.peer, peer);
-    if (session !== saved.sessionId || definitionOf(saved.peer)?.session.crashIdentity && progress.reattachments?.[saved.peer] && saved.sessionFile && peer?.sessionFile !== saved.sessionFile) throw nativeFailure(planned, saved.peer, "session_changed", `${saved.peer}: daemon session changed during terminal revalidation; manual-required`, { handle: saved.handle, expectedSession: saved.sessionId, ...(session === undefined ? {} : { observedSession: session }) });
+    const session = observedSession(saved.peer, peer, saved.projectRoot);
+    if (session !== saved.sessionId || projectDefinition(saved.peer, saved.projectRoot)?.session.crashIdentity && progress.reattachments?.[saved.peer] && saved.sessionFile && peer?.sessionFile !== saved.sessionFile) throw nativeFailure(planned, saved.peer, "session_changed", `${saved.peer}: daemon session changed during terminal revalidation; manual-required`, { handle: saved.handle, expectedSession: saved.sessionId, ...(session === undefined ? {} : { observedSession: session }) });
     return current;
   };
   /** Whether Orca's inventory lists the terminal; a failed, not-ok, truncated or non-JSON answer shows nothing. */
@@ -391,7 +412,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       return { state: "unknown", why: `the target hub reads as ${target.state === "running" ? `instance ${target.instanceId}, not ${progress.instanceId}` : target.state}`, ...(settled ? {} : { step: "wait until the target answers" }) };
     }
     const attached = target.peers.find((p) => p.id === peer && p.state !== "offline");
-    const session = observedSession(peer, attached);
+    const session = observedSession(peer, attached, planned.project.root);
     if (session) return { state: "live", session };
     let endedTerminal: Pick<TerminalBinding, "handle" | "incarnationId" | "worktreeId"> | undefined;
     // #225: the launch records of every instance this operation started for the project, the current one first: a
@@ -487,7 +508,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       if (live.state !== "running") throw nativeFailure(planned, binding.peer, "target_unavailable", `${binding.peer}: target hub reads as ${live.state} while awaiting attachment; saved terminal retained`, { handle: binding.handle, targetState: live.state });
       if (live.instanceId !== progress.instanceId || live.version !== op.plan.version || live.recovery?.operationId !== op.id) throw nativeFailure(planned, binding.peer, "target_unavailable", `${binding.peer}: target identity changed while awaiting attachment`, { handle: binding.handle, targetState: live.state });
       const peer = live.peers.find((p) => p.id === binding.peer && p.state !== "offline");
-      const session = observedSession(binding.peer, peer);
+      const session = observedSession(binding.peer, peer, binding.projectRoot);
       const changed = !!session && expectedSession !== null && session !== expectedSession;
       // #64: only the original zero-turn Claude may change identity without an operator choice. Re-read persistence
       // at attachment, not at the plan or wait start; an already accepted replacement is bound to its own id.
@@ -540,7 +561,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       }
     } catch { /* unavailable metadata stays unknown; raw output/errors never enter the receipt */ }
     const peer = live.peers.find((p) => p.id === binding.peer);
-    const session = peer?.state === "offline" ? undefined : observedSession(binding.peer, peer);
+    const session = peer?.state === "offline" ? undefined : observedSession(binding.peer, peer, binding.projectRoot);
     (progress.attachmentTimeouts ??= {})[binding.peer] = { at: now(), terminal,
       hub: { state: live.state, ...(live.instanceId ? { instanceId: live.instanceId } : {}), ...(peer ? { peerState: peer.state } : {}), ...(session ? { sessionId: session } : {}) },
       lastHubConnectAttempt: "unknown" };
@@ -572,10 +593,16 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       }
       // Reuse capability proof only after verifying the cached root and digest still identify these exact bytes.
       const cached = op.targetDigest === target.digest && op.targetRoot === target.root;
-      if (cached && op.targetFeatures !== undefined) return { ...target, targetFeatures: [...op.targetFeatures] };
-      // A legacy cached operation already past commit needs no capability proof to finish restoration (#215).
+      // Once every source committed, compatibility cannot be re-applied using mutable project declarations.
+      // Package identity/hash and live-test authority above still bind these retained bytes.
+      if (cached && op.projects?.every(project => ["stopped", "started", "peers-restored", "verified"].includes(project.phase))) {
+        return { ...target, ...(op.targetFeatures === undefined ? {} : { targetFeatures: [...op.targetFeatures] }) };
+      }
+      if (cached && op.targetFeatures !== undefined) {
+        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");
+        return { ...target, targetFeatures: [...op.targetFeatures] };
+      }
       // A prepared commitSent receipt remains uncertain and must still obtain proof before a possible commit.
-      if (cached && op.projects?.every(project => ["stopped", "started", "peers-restored", "verified"].includes(project.phase))) return target;
       // Legacy uncommitted receipts acquire verified feature evidence before source compatibility checks.
       const probe = await run([process.execPath, "-e", `import * as target from ${JSON.stringify(join(target.root, "src/hub/control-client.ts"))}; console.log(JSON.stringify({protocol: target.PROTOCOL, features: target.DAEMON_FEATURES ?? []}))`]);
       let metadata: { protocol?: unknown; features?: unknown } | undefined;
@@ -584,6 +611,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       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];
       if (metadata.protocol !== PROTOCOL) throw new FinalRefusal("target protocol requires a newer coordinator; staged package retained, runtimes unchanged");
+      if (!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");
       const verified = { ...target, targetFeatures };
       // Existing peer/waiver compatibility checks remain properties of the already verified bytes.
       if (op.targetDigest && op.targetDigest === target.digest && op.targetRoot === target.root) return verified;
@@ -630,7 +658,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
           progress.terminals[key] = true; save(); continue;
         }
         // #215: check resume viability again right before the destructive effect (a planned fresh start has none to lose).
-        const transcript = definitionOf(binding.peer)?.session.missingEvidence === "rollout" ? sessionState(binding) : "found";
+        const transcript = projectDefinition(binding.peer, binding.projectRoot)?.session.missingEvidence === "rollout" ? sessionState(binding) : "found";
         if (transcript === "unknown") throw new Error(`${unresumable(binding)}; no terminal was closed; make that store readable first`);
         if (transcript === "missing" && !planned.freshStart?.includes("codex")) {
           throw new Error(`${unresumable(binding)}; no terminal was closed. To continue without its conversation, end that Codex session and close its Orca terminal ${binding.handle} first, then resume`);
@@ -663,11 +691,11 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       const live = await inspectRecovery(planned.project);
       if (live.instanceId !== progress.instanceId) throw new Error("target daemon changed before peer restore");
       if (group === "native" && !onlyPeer) {
-        for (const peer of planned.source.peers.filter(p => definitionOf(p.id)?.session.restoreArgs && p.state !== "offline" && !(definitionOf(p.id)?.session.launchRecord && p.args?.mode === "tui"))) {
+        for (const peer of planned.source.peers.filter(p => projectDefinition(p.id, planned.project.root)?.session.restoreArgs && p.state !== "offline" && !(projectDefinition(p.id, planned.project.root)?.session.launchRecord && p.args?.mode === "tui"))) {
           const current = live.peers.find((p) => p.id === peer.id);
           if (current && current.state !== "offline") continue;
-          const adapter = definitionOf(peer.id)!;
-          const args = [peer.id];
+          const adapter = projectDefinition(peer.id, planned.project.root)!;
+          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);
           const captured = adapter.session.restoreArgs!(peer);
@@ -679,7 +707,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       }
       let claudeGroup = false;
       for (const plannedBinding of planned.terminals as TerminalBinding[]) {
-        if ((definitionOf(plannedBinding.peer)?.transport === "claude-channel") !== (claudeGroup = group !== "native") || onlyPeer && plannedBinding.peer !== onlyPeer) continue;
+        if ((projectDefinition(plannedBinding.peer, plannedBinding.projectRoot)?.transport === "claude-channel") !== (claudeGroup = group !== "native") || onlyPeer && plannedBinding.peer !== onlyPeer) continue;
         const key = `restored:${plannedBinding.peer}`;
         try {
           // #225: after a restart, the stopped target's terminal for this peer goes first; a session it had accepted
@@ -697,16 +725,16 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
           // start of a Codex thread with nothing to lose that still has no rollout; an unreadable store is neither.
           const chosen = !recordedOnly && !!progress.fresh?.[original.peer];
           let read: ReturnType<typeof sessionState> | undefined;
-          const transcript = () => definitionOf(original.peer)?.session.missingEvidence !== "rollout" || (chosen && !accepted) ? "found" : (read ??= sessionState(original));
+          const transcript = () => projectDefinition(original.peer, original.projectRoot)?.session.missingEvidence !== "rollout" || (chosen && !accepted) ? "found" : (read ??= sessionState(original));
           // An accepted session starts new again only when it has nothing to resume: a Codex thread that never got a
           // rollout, or a Claude session with no transcript (`--resume` could never succeed, #21).
           const fresh = () => recordedOnly ? false : accepted
-            ? (definitionOf(original.peer)?.session.missingEvidence === "rollout" ? (chosen || !!planned.freshStart?.includes(original.peer)) && transcript() === "missing" : nativeZeroTurn(planned.project.stateDir, original, "attach"))
+            ? (projectDefinition(original.peer, original.projectRoot)?.session.missingEvidence === "rollout" ? (chosen || !!planned.freshStart?.includes(original.peer)) && transcript() === "missing" : nativeZeroTurn(planned.project.stateDir, original, "attach"))
             : chosen || (!!planned.freshStart?.includes(original.peer) && transcript() === "missing");
           // The runner ends this with the choices `status` shows (nextActions); resume comes first and launches a failed
           // peer again, which helps once its cause (a transient Orca create failure, a fixed store) is gone.
           // The waiver's audit label: the operator's choice, a Claude with nothing to resume, or the plan's Codex fresh start.
-          const waiver = () => progress.fresh?.[original.peer] ? "fresh-session" : definitionOf(original.peer)?.transport === "claude-channel" ? "zero-turn" : "fresh-start";
+          const waiver = () => progress.fresh?.[original.peer] ? "fresh-session" : projectDefinition(original.peer, original.projectRoot)?.transport === "claude-channel" ? "zero-turn" : "fresh-start";
           const notRestored = (why: string) => new Error(fresh()
             ? `${original.peer}: ${why}; read that terminal in Orca for the launcher's error and fix its cause`
             : `${original.peer}: ${why}; session ${original.sessionId} was not restored; resume launches it again once the cause is fixed`);
@@ -807,7 +835,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
           // The planned session already attached is the restoration (the table's row for it), not a reason to block.
           const evidence = await peerEvidence(planned, progress, original.peer);
           if (evidence.state === "live" && evidence.session === original.sessionId) {
-            if (repair) await settle(evidence.session);
+            if (repair) await settle(evidence.session!); // equality with the recorded string session id above proves this value
             else { progress.terminals[key] = { state: "done", binding: await revalidateTerminal(planned, progress, original, false) } satisfies RestoreReceipt; save(); }
             continue;
           }
@@ -815,7 +843,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
           if (transcript() === "unknown") throw new Error(`${unresumable(original)}; no terminal was created; make that store readable first`);
           if (transcript() === "missing" && !fresh()) {
             progress.terminals[key] = { state: "failed" } satisfies RestoreReceipt; save();
-            if (recordedOnly) throw new MissingRecordedSession({ projectId: planned.project.id, peer: original.peer, sessionId: original.sessionId, kind: definitionOf(original.peer)!.session.missingEvidence!, checkedPath: sessionPath(original) });
+            if (recordedOnly) throw new MissingRecordedSession({ projectId: planned.project.id, peer: original.peer, sessionId: original.sessionId, kind: projectDefinition(original.peer, original.projectRoot)!.session.missingEvidence!, checkedPath: sessionPath(original) });
             throw notRestored(unresumable(original).slice("codex: ".length));
           }
           if (fresh()) {
@@ -878,7 +906,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
               const marker = progress.reattachments?.[plannedBinding.peer];
               if (marker) marker.binding = binding;
               progress.terminals[key] = { state: "failed" } satisfies RestoreReceipt; save();
-              throw new MissingRecordedSession({ projectId: planned.project.id, peer: plannedBinding.peer, sessionId: binding.sessionId, kind: definitionOf(plannedBinding.peer)!.session.missingEvidence!, checkedPath: sessionPath(binding) });
+              throw new MissingRecordedSession({ projectId: planned.project.id, peer: plannedBinding.peer, sessionId: binding.sessionId, kind: projectDefinition(plannedBinding.peer, plannedBinding.projectRoot)!.session.missingEvidence!, checkedPath: sessionPath(binding) });
             }
           }
           if (error instanceof ReattachmentRequired || isDatabaseBusy(error)) throw error;
@@ -899,7 +927,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     installPlugin: async (op) => {
       const configured = new Set<string>();
       for (const planned of op.plan.projects) {
-        const binding = (planned.terminals as TerminalBinding[]).find((t) => definitionOf(t.peer)?.transport === "claude-channel");
+        const binding = (planned.terminals as TerminalBinding[]).find((t) => projectDefinition(t.peer, t.projectRoot)?.transport === "claude-channel");
         if (!binding) continue;
         const profile = binding.launch.env.CLAUDE_CONFIG_DIR ?? "default";
         if (configured.has(profile)) continue;
@@ -936,7 +964,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
         try { archived = JSON.parse(readFileSync(archive, "utf8")); } catch { return { continuity: "not-archived" }; }
         if (!archived || typeof archived !== "object" || (archived as { operationId?: unknown }).operationId !== op.id) return { continuity: "not-archived" };
         try {
-          const continuity = definitionOf(source.id)?.session.continuityBookmark;
+          const continuity = projectDefinition(source.id, project.root)?.session.continuityBookmark;
           if (!continuity) return;
           const binding = planned ? resolveAcceptedBinding(planned, progress, source.id as TerminalBinding["peer"]) : undefined;
           writeRecoveryContinuity(project.stateDir, { schema: 1, operationId: op.id, projectId: project.id, projectRoot: project.root, at: now(),
@@ -963,21 +991,21 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
         // A #225 restart clears the old target's repair fence, never its accepted conversation.
         const retained = retired?.state === "done" && accepted?.state === "done" && retired.binding.peer === old.id && retired.binding.projectRoot === planned.project.root && retired.binding.sessionId === accepted.binding.sessionId;
         if ((recordedOnly || retained) && accepted?.state === "done") {
-          const session = observedSession(old.id, peer);
+          const session = observedSession(old.id, peer, planned.project.root);
           if (session !== accepted.binding.sessionId || repair && accepted.binding.sessionId !== repair.binding.sessionId ||
-              definitionOf(old.id)?.session.launchRecord && definitionOf(old.id)?.session.crashIdentity && (recordedOnly || old.sessionFile) && accepted.binding.sessionFile && peer.sessionFile !== accepted.binding.sessionFile) throw nativeFailure(planned, old.id, "session_changed", `${old.id}: reattached a different recorded conversation`, { handle: accepted.binding.handle, expectedSession: accepted.binding.sessionId, ...(session === undefined ? {} : { observedSession: session }) });
+              projectDefinition(old.id, planned.project.root)?.session.launchRecord && projectDefinition(old.id, planned.project.root)?.session.crashIdentity && (recordedOnly || old.sessionFile) && accepted.binding.sessionFile && peer.sessionFile !== accepted.binding.sessionFile) throw nativeFailure(planned, old.id, "session_changed", `${old.id}: reattached a different recorded conversation`, { handle: accepted.binding.handle, expectedSession: accepted.binding.sessionId, ...(session === undefined ? {} : { observedSession: session }) });
           continue;
         }
         if (!recordedOnly && (progress.fresh?.[old.id] || planned.freshStart?.includes(old.id))) continue; // #215: a new session was accepted (recorded)
-        if (definitionOf(old.id)?.session.idField === "threadId" && peer.threadId !== old.threadId) throw nativeFailure(planned, old.id, "session_changed", "Codex resumed a different conversation", { ...(old.threadId ? { expectedSession: old.threadId } : {}), ...(peer.threadId ? { observedSession: peer.threadId } : {}) });
-        if (definitionOf(old.id)?.transport === "claude-channel" && peer.sessionId !== old.sessionId) {
+        if (projectDefinition(old.id, planned.project.root)?.session.idField === "threadId" && peer.threadId !== old.threadId) throw nativeFailure(planned, old.id, "session_changed", "Codex resumed a different conversation", { ...(old.threadId ? { expectedSession: old.threadId } : {}), ...(peer.threadId ? { observedSession: peer.threadId } : {}) });
+        if (projectDefinition(old.id, planned.project.root)?.transport === "claude-channel" && peer.sessionId !== old.sessionId) {
           // #64: the restore gate already accepted a fresh session when the original never
           // persisted a transcript. Re-derive persistence from the binding exactly like that
           // gate did, so a first turn landing after the plan was made keeps the check strict.
-          const binding = (planned.terminals as TerminalBinding[]).find((t) => definitionOf(t.peer)?.transport === "claude-channel");
+          const binding = (planned.terminals as TerminalBinding[]).find((t) => projectDefinition(t.peer, t.projectRoot)?.transport === "claude-channel");
           if (recordedOnly || !binding || binding.sessionId !== old.sessionId || !nativeZeroTurn(planned.project.stateDir, binding, "verify")) throw nativeFailure(planned, old.id, "session_changed", "Claude resumed a different conversation", { ...(old.sessionId ? { expectedSession: old.sessionId } : {}), ...(peer.sessionId ? { observedSession: peer.sessionId } : {}) });
         }
-        if (definitionOf(old.id)?.session.launchRecord && definitionOf(old.id)?.session.crashIdentity && (peer.sessionId !== old.sessionId || (old.sessionFile && peer.sessionFile !== old.sessionFile))) throw nativeFailure(planned, old.id, "session_changed", "Pi resumed a different conversation", { ...(old.sessionId ? { expectedSession: old.sessionId } : {}), ...(peer.sessionId ? { observedSession: peer.sessionId } : {}) });
+        if (projectDefinition(old.id, planned.project.root)?.session.launchRecord && projectDefinition(old.id, planned.project.root)?.session.crashIdentity && (peer.sessionId !== old.sessionId || (old.sessionFile && peer.sessionFile !== old.sessionFile))) throw nativeFailure(planned, old.id, "session_changed", "Pi resumed a different conversation", { ...(old.sessionId ? { expectedSession: old.sessionId } : {}), ...(peer.sessionId ? { observedSession: peer.sessionId } : {}) });
       }
       for (const original of planned.terminals as TerminalBinding[]) {
         const saved = decodeRestoreReceipt(progress.terminals[`restored:${original.peer}`]);