@fitlab-ai/agent-infra 0.9.8 → 0.9.10

package/lib/sandbox/worktree-safety.ts

@@ -1,7 +1,9 @@
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { runProbe } from './shell.ts';
+import { resolveSandboxTarget } from './workspace-identity.ts';
 
 type WorktreeChange = {
   indexStatus: string;
@@ -16,6 +18,8 @@ type WorktreeSnapshot = {
   head: string;
   changes: readonly WorktreeChange[];
   identity: string;
+  source?: 'registered' | 'recovered';
+  recovery?: WorktreeRecoveryContext;
 };
 
 type WorktreeInspection =
@@ -28,6 +32,14 @@ type WorktreeRemovalPermit = {
   snapshot: WorktreeSnapshot;
 };
 
+type WorktreeRecoveryContext = Readonly<{
+  repoRoot: string;
+  worktreeBase: string;
+  branch: string;
+  identitySource: 'branch-only' | 'task-bound';
+  taskId: string | null;
+}>;
+
 type Probe = typeof runProbe;
 
 function probeText(probe: Probe, cwd: string, args: string[]): string {
@@ -164,6 +176,203 @@ function captureOnce(worktree: string, probe: Probe): WorktreeSnapshot {
   return { worktree: resolvedWorktree, branch, head, changes, identity: hash.digest('hex') };
 }
 
+function probeTextWithEnv(
+  probe: Probe,
+  repoRoot: string,
+  args: string[],
+  env: NodeJS.ProcessEnv
+): string {
+  const result = probe('git', args, { cwd: repoRoot, encoding: 'utf8', env });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const stderr = typeof result.stderr === 'string' ? result.stderr.trim() : result.stderr.toString('utf8').trim();
+    throw new Error(stderr || `git ${args[0] ?? 'command'} failed with exit code ${result.status ?? 'unknown'}`);
+  }
+  return typeof result.stdout === 'string' ? result.stdout : result.stdout.toString('utf8');
+}
+
+function probeMetadataCommand(
+  probe: Probe,
+  repoRoot: string,
+  args: string[],
+  env: NodeJS.ProcessEnv
+): boolean {
+  const result = probe('git', args, { cwd: repoRoot, encoding: 'utf8', env });
+  if (result.error) throw result.error;
+  return result.status === 0;
+}
+
+function hasValidHeadContent(content: string): boolean {
+  return /^(?:ref:\s+refs\/\S+|[0-9a-f]{40}|[0-9a-f]{64})$/i.test(content.trim());
+}
+
+function assertRecoverableMetadata(worktree: string, repoRoot: string, probe: Probe): void {
+  const dotGit = path.join(worktree, '.git');
+  let dotGitStat: fs.Stats;
+  try {
+    dotGitStat = fs.lstatSync(dotGit);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw error;
+  }
+  if (dotGitStat.isSymbolicLink() || dotGitStat.isDirectory()) {
+    throw new Error('WORKTREE_RECOVERY_METADATA_NOT_ELIGIBLE');
+  }
+  if (!dotGitStat.isFile()) throw new Error('WORKTREE_RECOVERY_METADATA_INVALID');
+
+  const content = fs.readFileSync(dotGit, 'utf8').trim();
+  const match = /^gitdir:\s*(.+)$/i.exec(content);
+  if (!match) throw new Error('WORKTREE_RECOVERY_METADATA_INVALID');
+
+  const commonDir = fs.realpathSync.native(path.resolve(repoRoot, probeText(probe, repoRoot, [
+    'rev-parse', '--git-common-dir'
+  ]).trim()));
+  const adminRoot = path.join(commonDir, 'worktrees');
+  const adminPath = path.resolve(path.dirname(dotGit), match[1]!);
+  const relative = path.relative(adminRoot, adminPath);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative) || relative.includes(path.sep)) {
+    throw new Error('WORKTREE_RECOVERY_METADATA_INVALID');
+  }
+
+  if (!fs.existsSync(adminPath)) return;
+  const adminStat = fs.lstatSync(adminPath);
+  if (adminStat.isSymbolicLink()) throw new Error('WORKTREE_RECOVERY_METADATA_INVALID');
+  if (!adminStat.isDirectory()) return;
+
+  const requiredFiles = ['HEAD', 'gitdir', 'commondir', 'index'];
+  if (requiredFiles.some((name) => !fs.existsSync(path.join(adminPath, name)))) return;
+  for (const name of requiredFiles) {
+    const filePath = path.join(adminPath, name);
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('WORKTREE_RECOVERY_METADATA_INVALID');
+  }
+
+  const adminGitdir = fs.readFileSync(path.join(adminPath, 'gitdir'), 'utf8').trim();
+  const adminCommonDir = fs.readFileSync(path.join(adminPath, 'commondir'), 'utf8').trim();
+  const adminGitdirPath = adminGitdir
+    ? fs.realpathSync.native(path.resolve(adminPath, adminGitdir))
+    : '';
+  const canonicalDotGit = fs.realpathSync.native(dotGit);
+  const adminCommonDirPath = adminCommonDir
+    ? fs.realpathSync.native(path.resolve(adminPath, adminCommonDir))
+    : '';
+  if (!adminGitdir || adminGitdirPath !== canonicalDotGit
+    || !adminCommonDir || adminCommonDirPath !== commonDir) {
+    throw new Error('WORKTREE_RECOVERY_METADATA_INVALID');
+  }
+
+  const headContent = fs.readFileSync(path.join(adminPath, 'HEAD'), 'utf8');
+  const indexContent = fs.readFileSync(path.join(adminPath, 'index'));
+  if (!hasValidHeadContent(headContent) || indexContent.subarray(0, 4).toString('ascii') !== 'DIRC') return;
+
+  const validationEnv: NodeJS.ProcessEnv = { ...process.env };
+  for (const key of ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE', 'GIT_WORK_TREE', 'GIT_PREFIX']) {
+    delete validationEnv[key];
+  }
+  validationEnv.GIT_DIR = adminPath;
+  validationEnv.GIT_WORK_TREE = path.resolve(worktree);
+  if (!probeMetadataCommand(probe, repoRoot, ['rev-parse', '--verify', 'HEAD^{commit}'], validationEnv)) return;
+  if (!probeMetadataCommand(probe, repoRoot, ['ls-files', '--stage', '-z'], validationEnv)) return;
+  throw new Error('WORKTREE_RECOVERY_METADATA_REGISTERED');
+}
+
+function parseRecoveredStatus(raw: string): WorktreeChange[] {
+  const records = raw.split('\0');
+  const changes: WorktreeChange[] = [];
+  for (let index = 0; index < records.length;) {
+    const status = records[index++] ?? '';
+    if (!status) continue;
+    const code = status[0] ?? '';
+    if (code === 'R' || code === 'C') {
+      const originalPath = records[index++];
+      const nextPath = records[index++];
+      if (!originalPath || !nextPath) throw new Error('Unable to parse recovered Git rename record');
+      changes.push({ indexStatus: code, worktreeStatus: ' ', path: nextPath, originalPath });
+      continue;
+    }
+    const filePath = records[index++];
+    if (!filePath) throw new Error('Unable to parse recovered Git status record');
+    changes.push({
+      indexStatus: code === 'D' ? ' ' : code,
+      worktreeStatus: code === 'D' ? 'D' : ' ',
+      path: filePath
+    });
+  }
+  return changes;
+}
+
+function captureRecoveredOnce(
+  worktree: string,
+  recovery: WorktreeRecoveryContext,
+  probe: Probe
+): WorktreeSnapshot {
+  const resolvedWorktree = path.resolve(worktree);
+  const resolvedBase = path.resolve(recovery.worktreeBase);
+  const relative = path.relative(resolvedBase, resolvedWorktree);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`WORKTREE_RECOVERY_PATH_INVALID: ${resolvedWorktree}`);
+  }
+  const stat = fs.lstatSync(resolvedWorktree);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('WORKTREE_RECOVERY_PATH_INVALID');
+  const canonicalBase = fs.realpathSync.native(resolvedBase);
+  const canonicalWorktree = fs.realpathSync.native(resolvedWorktree);
+  const canonicalRelative = path.relative(canonicalBase, canonicalWorktree);
+  if (!canonicalRelative || canonicalRelative.startsWith('..') || path.isAbsolute(canonicalRelative)) {
+    throw new Error('WORKTREE_RECOVERY_PATH_INVALID');
+  }
+  const resolvedWorkspace = resolveSandboxTarget(recovery.branch, recovery.repoRoot).workspace;
+  if (recovery.identitySource === 'branch-only' && resolvedWorkspace.mode !== 'branch-only') {
+    throw new Error('WORKTREE_RECOVERY_IDENTITY_CHANGED');
+  }
+  if (recovery.identitySource === 'task-bound'
+    && (resolvedWorkspace.mode !== 'task-bound' || resolvedWorkspace.taskId !== recovery.taskId)) {
+    throw new Error('WORKTREE_RECOVERY_IDENTITY_CHANGED');
+  }
+  assertRecoverableMetadata(resolvedWorktree, recovery.repoRoot, probe);
+
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-recovered-index-'));
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  for (const key of ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_PREFIX']) delete env[key];
+  env.GIT_INDEX_FILE = path.join(tempDir, 'index');
+  env.GIT_WORK_TREE = resolvedWorktree;
+  try {
+    const baseline = probeTextWithEnv(probe, recovery.repoRoot, [
+      'rev-parse', '--verify', `refs/heads/${recovery.branch}^{commit}`
+    ], env).trim();
+    if (!baseline) throw new Error(`WORKTREE_RECOVERY_BRANCH_INVALID: ${recovery.branch}`);
+    probeTextWithEnv(probe, recovery.repoRoot, ['read-tree', baseline], env);
+    probeTextWithEnv(probe, recovery.repoRoot, ['add', '-A', '--', '.'], env);
+    const status = probeTextWithEnv(probe, recovery.repoRoot, [
+      'diff', '--cached', '--name-status', '--find-renames', '-z', '--', '.'
+    ], env);
+    const changes = parseRecoveredStatus(status);
+    const hash = createHash('sha256');
+    updatePart(hash, 'source', 'recovered');
+    updatePart(hash, 'worktree', resolvedWorktree);
+    updatePart(hash, 'repo-root', path.resolve(recovery.repoRoot));
+    updatePart(hash, 'branch', recovery.branch);
+    updatePart(hash, 'baseline', baseline);
+    updatePart(hash, 'identity-source', recovery.identitySource);
+    updatePart(hash, 'task-id', recovery.taskId ?? '');
+    updatePart(hash, 'status', status);
+    for (const change of changes) {
+      hashPath(hash, resolvedWorktree, change.path, probe);
+      if (change.originalPath) hashPath(hash, resolvedWorktree, change.originalPath, probe);
+    }
+    return {
+      worktree: resolvedWorktree,
+      branch: recovery.branch,
+      head: baseline,
+      changes,
+      identity: hash.digest('hex'),
+      source: 'recovered',
+      recovery: { ...recovery }
+    };
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
 function inspectWorktree(worktree: string, { probe = runProbe }: { probe?: Probe } = {}): WorktreeInspection {
   const resolvedWorktree = path.resolve(worktree);
   try {
@@ -182,6 +391,28 @@ function inspectWorktree(worktree: string, { probe = runProbe }: { probe?: Probe
   }
 }
 
+function inspectRecoveredWorktree(
+  worktree: string,
+  recovery: WorktreeRecoveryContext,
+  { probe = runProbe }: { probe?: Probe } = {}
+): WorktreeInspection {
+  const resolvedWorktree = path.resolve(worktree);
+  try {
+    const first = captureRecoveredOnce(resolvedWorktree, recovery, probe);
+    const second = captureRecoveredOnce(resolvedWorktree, recovery, probe);
+    if (first.identity !== second.identity) {
+      return { status: 'failed', worktree: resolvedWorktree, message: 'Snapshot changed while recovering worktree' };
+    }
+    return { status: second.changes.length === 0 ? 'clean' : 'dirty', snapshot: second };
+  } catch (error) {
+    return {
+      status: 'failed',
+      worktree: resolvedWorktree,
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
 function inspectWorktrees(worktrees: readonly string[]): WorktreeInspection[] {
   return [...new Set(worktrees.map((worktree) => path.resolve(worktree)))].sort()
     .map((worktree) => inspectWorktree(worktree));
@@ -201,7 +432,9 @@ function verifyWorktreePermit(
   permit: WorktreeRemovalPermit,
   options: { probe?: Probe } = {}
 ): WorktreeSnapshot {
-  const current = inspectWorktree(permit.snapshot.worktree, options);
+  const current = permit.snapshot.source === 'recovered' && permit.snapshot.recovery
+    ? inspectRecoveredWorktree(permit.snapshot.worktree, permit.snapshot.recovery, options)
+    : inspectWorktree(permit.snapshot.worktree, options);
   if (current.status === 'failed') throw new Error(`Unable to verify worktree permit: ${current.message}`);
   if (current.snapshot.identity !== permit.snapshot.identity || (permit.mode === 'clean' && current.status !== 'clean')) {
     throw new Error(`Worktree changed after authorization: ${permit.snapshot.worktree}`);
@@ -227,8 +460,9 @@ export {
   createCleanPermit,
   createDiscardPermit,
   formatWorktreeSnapshot,
+  inspectRecoveredWorktree,
   inspectWorktree,
   inspectWorktrees,
   verifyWorktreePermit
 };
-export type { WorktreeChange, WorktreeInspection, WorktreeRemovalPermit, WorktreeSnapshot };
+export type { WorktreeChange, WorktreeInspection, WorktreeRecoveryContext, WorktreeRemovalPermit, WorktreeSnapshot };

package/lib/task/codex-orchestration.ts

@@ -1,5 +1,3 @@
-import fs from 'node:fs';
-
 import {
   preflightCodexLifecycleEvidence,
   resolveCodexSpawnedChild,
@@ -7,16 +5,28 @@ import {
   resolveCodexThread
 } from '../agent-clients/adapters/codex-lifecycle/app-server.ts';
 import { createCodexLifecycleStore } from '../agent-clients/adapters/codex-lifecycle/store.ts';
-import { createCodexCapabilityStore } from '../agent-clients/adapters/codex-lifecycle/capability-store.ts';
-import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
-import type { LifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
-import { verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
+import {
+  createCodexCapabilityStore,
+  isCodexCapabilityProvenanceDetail
+} from '../agent-clients/adapters/codex-lifecycle/capability-store.ts';
+import type { CodexCapabilityProvenanceDetail } from '../agent-clients/adapters/codex-lifecycle/capability-store.ts';
+import {
+  computeLifecycleBuildIdentity,
+  verifyLifecycleBuildIdentity,
+  type LifecycleBuildIdentity,
+  type LifecycleIdentityWarning
+} from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
+import { verifyCodexSandboxControllerContextWithWarnings as verifySandboxControllerWithWarnings } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
+import {
+  verifyCodexSandboxControllerContextWithWarnings as verifyControllerContextFileWithWarnings
+} from '../agent-clients/adapters/codex-lifecycle/controller-context.ts';
 import type { AgentClientId } from '../agent-clients/types.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import {
   activateMatchingOrchestrationDelegation,
   hasActivatableOrchestrationDelegation,
   hasSealableOrchestrationDelegation,
+  OrchestrationStateError,
   pauseMatchingOrchestrationDelegation,
   prepareOrchestrationDelegation,
   reconcileMatchingOrchestrationDelegation,
@@ -52,10 +62,27 @@ function coreOptions(options: CodexBridgeOptions): OrchestrationOptions {
   return { ...options.orchestrationOptions, repoRoot: options.repoRoot ?? options.orchestrationOptions?.repoRoot };
 }
 
-function bridgeFailure(code: string, message: string): OrchestrationResult {
+function bridgeFailure(code: string, message: string, detail?: CodexCapabilityProvenanceDetail): OrchestrationResult {
   return {
     status: 'failed', changed: false, taskId: null, run: null, next: null,
-    error: { code, message }
+    error: { code, message, ...(detail ? { detail } : {}) }
+  };
+}
+
+function capabilityFailure(error: unknown): NonNullable<OrchestrationResult['error']> {
+  const detailValue = error instanceof Error
+    ? (error as Error & { detail?: unknown }).detail
+    : undefined;
+  return {
+    code: error instanceof Error && error.name.startsWith('CODEX_CAPABILITY_')
+      ? error.name
+      : 'ORCHESTRATION_CLIENT_PREFLIGHT_FAILED',
+    message: error instanceof Error ? error.message : String(error),
+    ...(error instanceof Error
+      && error.name === 'CODEX_CAPABILITY_PROVENANCE_MISMATCH'
+      && isCodexCapabilityProvenanceDetail(detailValue)
+      ? { detail: detailValue }
+      : {})
   };
 }
 
@@ -71,11 +98,25 @@ function requiredStore(options: CodexBridgeOptions): LifecycleStore {
   return options.store;
 }
 
-function controllerContext(taskId: string, repoRoot: string) {
-  const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
-  return contextPath
-    ? verifyCodexSandboxControllerContext(contextPath, taskId, { repoRoot })
-    : null;
+function brokerControllerBinding(): Readonly<{ instanceDigest: string; controlGeneration: string }> | null {
+  const raw = process.env.AGENT_INFRA_CONTROL_CONTROLLER_BINDING;
+  if (!raw) return null;
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_BINDING_INVALID');
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_BINDING_INVALID');
+  }
+  const binding = value as Record<string, unknown>;
+  if (Object.keys(binding).sort().join(',') !== 'controlGeneration,instanceDigest'
+    || typeof binding.instanceDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(binding.instanceDigest)
+    || typeof binding.controlGeneration !== 'string' || binding.controlGeneration.length === 0) {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_BINDING_INVALID');
+  }
+  return binding as { instanceDigest: string; controlGeneration: string };
 }
 
 async function prepareCodexOrchestrationDelegation(
@@ -101,36 +142,113 @@ async function prepareCodexOrchestrationDelegation(
       );
     }
     const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(repoRoot);
-    const controller = controllerContext(resolved.taskId, repoRoot);
+    const brokerController = brokerControllerBinding();
+    const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+    const contextVerification = contextPath
+      ? (brokerController
+        ? verifyControllerContextFileWithWarnings(contextPath, {
+            repoRoot,
+            generation: process.env.AGENT_INFRA_CONTROL_GENERATION ?? brokerController.controlGeneration
+          })
+        : verifySandboxControllerWithWarnings(contextPath, { repoRoot }))
+      : null;
+    const identityWarnings: LifecycleIdentityWarning[] = [...(contextVerification?.warnings ?? [])];
+    const localController = contextVerification?.context ?? null;
+    if (localController && brokerController
+      && (localController.controllerInstanceDigest !== brokerController.instanceDigest
+        || localController.controlGeneration !== brokerController.controlGeneration)) {
+      return bridgeFailure(
+        'CODEX_SANDBOX_CONTROLLER_BINDING_MISMATCH',
+        'broker and local controller bindings do not match'
+      );
+    }
+    const controller = brokerController ?? (localController ? {
+      instanceDigest: localController.controllerInstanceDigest,
+      controlGeneration: localController.controlGeneration
+    } : null);
     const capabilityStore = options.capabilityStore ?? createCodexCapabilityStore();
-    const consumed = capabilityStore.consume(input.capabilityToken, {
+    const attested = capabilityStore.inspect(input.capabilityToken);
+    const capabilityIdentity = verifyLifecycleBuildIdentity(attested.buildIdentity, buildIdentity);
+    if (!capabilityIdentity.ok) {
+      return bridgeFailure(capabilityIdentity.code!, capabilityIdentity.message!);
+    }
+    identityWarnings.push(...capabilityIdentity.warnings);
+    const lifecycleProvenance = {
+      ...attested.buildIdentity,
+      hookDefinitionHash: preflight.hookDefinitionHash,
+      ...preflight.hookProvenance,
+      capabilitySessionId: attested.sessionId!,
+      capabilityTurnId: attested.turnId!,
+      capabilityToolUseId: attested.toolUseId!,
+      controllerInstanceDigest: controller?.instanceDigest ?? null,
+      controlGeneration: controller?.controlGeneration ?? null
+    };
+    const capabilityExpected = {
       taskId: resolved.taskId,
       hookDefinitionHash: preflight.hookDefinitionHash,
       buildIdentity,
       ...(controller ? { controller: {
-        instanceDigest: controller.controllerInstanceDigest,
+        instanceDigest: controller.instanceDigest,
         controlGeneration: controller.controlGeneration
       } } : {})
-    });
-    return prepareOrchestrationDelegation(taskRef, {
+    };
+    const prepared = prepareOrchestrationDelegation(taskRef, {
       ...input,
-      lifecycleProvenance: {
-        ...consumed.buildIdentity,
-        hookDefinitionHash: preflight.hookDefinitionHash,
-        ...preflight.hookProvenance,
-        capabilitySessionId: consumed.sessionId!,
-        capabilityTurnId: consumed.turnId!,
-        capabilityToolUseId: consumed.toolUseId!,
-        controllerInstanceDigest: controller?.controllerInstanceDigest ?? null,
-        controlGeneration: controller?.controlGeneration ?? null
+      lifecycleProvenance
+    }, {
+      ...coreOptions(options),
+      validateLifecycleCapability: () => {
+        try {
+          const validated = capabilityStore.validate(input.capabilityToken!, capabilityExpected);
+          if (validated.sessionId !== attested.sessionId
+            || validated.turnId !== attested.turnId
+            || validated.toolUseId !== attested.toolUseId) {
+            return {
+              code: 'CODEX_CAPABILITY_IDENTITY_CHANGED',
+              message: 'capability identity changed during validation'
+            };
+          }
+          return null;
+        } catch (error) {
+          return capabilityFailure(error);
+        }
+      },
+      consumeLifecycleCapability: () => {
+        try {
+          const consumed = capabilityStore.consume(input.capabilityToken!, capabilityExpected);
+          if (consumed.sessionId !== attested.sessionId
+            || consumed.turnId !== attested.turnId
+            || consumed.toolUseId !== attested.toolUseId) {
+            return {
+              code: 'CODEX_CAPABILITY_IDENTITY_CHANGED',
+              message: 'capability identity changed during consumption'
+            };
+          }
+          return null;
+        } catch (error) {
+          return capabilityFailure(error);
+        }
       }
-    }, coreOptions(options));
+    });
+    return identityWarnings.length > 0 && prepared.status !== 'failed'
+      ? { ...prepared, warnings: Object.freeze(identityWarnings) }
+      : prepared;
   } catch (error) {
+    if (error instanceof OrchestrationStateError) return bridgeFailure(error.code, error.message);
+    const detailValue = error instanceof Error
+      ? (error as Error & { detail?: unknown }).detail
+      : undefined;
+    const detail = error instanceof Error
+      && error.name === 'CODEX_CAPABILITY_PROVENANCE_MISMATCH'
+      && isCodexCapabilityProvenanceDetail(detailValue)
+      ? detailValue
+      : undefined;
     return bridgeFailure(
       error instanceof Error && error.name.startsWith('CODEX_CAPABILITY_')
         ? error.name
         : 'ORCHESTRATION_CLIENT_PREFLIGHT_FAILED',
-      error instanceof Error ? error.message : String(error)
+      error instanceof Error ? error.message : String(error),
+      detail
     );
   }
 }
@@ -161,16 +279,11 @@ async function activateCodexOrchestrationDelegation(
     });
     const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(repoRoot);
     const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
-    const contextTaskId = contextPath
-      ? (JSON.parse(fs.readFileSync(contextPath, 'utf8')) as { taskId?: unknown }).taskId
+    const contextVerification = contextPath
+      ? verifySandboxControllerWithWarnings(contextPath, { repoRoot })
       : null;
-    if (contextPath && typeof contextTaskId !== 'string') {
-      throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
-    }
-    const controller = contextPath
-      ? verifyCodexSandboxControllerContext(contextPath, contextTaskId as string, { repoRoot })
-      : null;
-    return activateMatchingOrchestrationDelegation('codex', {
+    const controller = contextVerification?.context ?? null;
+    const activated = activateMatchingOrchestrationDelegation('codex', {
       nativeAgent: evidence.nativeAgent,
       childId: evidence.childThreadId,
       parentId: evidence.parentThreadId,
@@ -195,7 +308,12 @@ async function activateCodexOrchestrationDelegation(
         controlGeneration: controller?.controlGeneration ?? null
       }
     }, coreOptions(options));
+    const warnings = contextVerification?.warnings ?? [];
+    return warnings.length > 0 && activated.status !== 'failed'
+      ? { ...activated, warnings: Object.freeze(warnings) }
+      : activated;
   } catch (error) {
+    if (error instanceof OrchestrationStateError) return bridgeFailure(error.code, error.message);
     return pauseBridge('ORCHESTRATION_CODEX_START_FAILED', error instanceof Error ? error.message : String(error), options);
   }
 }
@@ -223,6 +341,7 @@ async function activateCodexSpawnDelegation(
       resolveThread: async () => resolved
     });
   } catch (error) {
+    if (error instanceof OrchestrationStateError) return bridgeFailure(error.code, error.message);
     return pauseBridge('ORCHESTRATION_CODEX_START_FAILED', error instanceof Error ? error.message : String(error), options);
   }
 }
@@ -238,7 +357,11 @@ async function sealCodexOrchestrationDelegation(
     const store = requiredStore(options);
     const existing = store.read(childThreadId);
     if (!existing.consumer) {
-      store.apply(await (options.resolveTerminal ?? resolveCodexTerminal)(childThreadId));
+      const stopTurnId = existing.state.stop?.turnId;
+      if (!stopTurnId) {
+        return pauseBridge('ORCHESTRATION_CODEX_STOP_EVIDENCE_INVALID', 'Codex lifecycle stop hook is not available', options);
+      }
+      store.apply(await (options.resolveTerminal ?? resolveCodexTerminal)(childThreadId, stopTurnId));
     }
     const record = store.read(childThreadId);
     const evidence = record.state.stopEvidence;
@@ -259,6 +382,7 @@ async function sealCodexOrchestrationDelegation(
       coreOptions(options)
     );
   } catch (error) {
+    if (error instanceof OrchestrationStateError) return bridgeFailure(error.code, error.message);
     return pauseBridge('ORCHESTRATION_CODEX_STOP_FAILED', error instanceof Error ? error.message : String(error), options);
   }
 }
@@ -280,7 +404,10 @@ async function sealCodexParentDelegation(
     const start = active.state.startEvidence!;
     const child = active.state.child!;
     if (!active.state.terminal) {
-      store.apply(await (options.resolveTerminal ?? resolveCodexTerminal)(start.childThreadId));
+      const resolveTerminal = options.resolveTerminal ?? resolveCodexTerminal;
+      store.apply(active.state.stop
+        ? await resolveTerminal(start.childThreadId, active.state.stop.turnId)
+        : await resolveTerminal(start.childThreadId));
     }
     if (!store.read(start.childThreadId).state.stop) {
       store.apply({
@@ -294,6 +421,7 @@ async function sealCodexParentDelegation(
     }
     return sealCodexOrchestrationDelegation(start.childThreadId, options);
   } catch (error) {
+    if (error instanceof OrchestrationStateError) return bridgeFailure(error.code, error.message);
     if (error instanceof Error && error.message === 'CODEX_TURN_NOT_TERMINAL') {
       return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'The matching Codex child has not completed');
     }