@fitlab-ai/agent-infra 0.9.5 → 0.9.6

package/lib/sandbox/workspace-view.ts

@@ -9,6 +9,23 @@ export type SandboxWorkspaceView = Readonly<{
   taskMountPath: string | null;
 }>;
 
+export const SANDBOX_WORKSPACE_VIEW_STATES = Object.freeze([
+  'active',
+  'completed',
+  'blocked',
+  'archive'
+] as const);
+
+export function sandboxWorkspaceViewStatePaths(root: string): ReadonlyArray<Readonly<{
+  state: typeof SANDBOX_WORKSPACE_VIEW_STATES[number];
+  hostPath: string;
+}>> {
+  return SANDBOX_WORKSPACE_VIEW_STATES.map((state) => ({
+    state,
+    hostPath: path.join(root, state)
+  }));
+}
+
 export function sandboxWorkspaceViewPaths(params: Readonly<{
   base: string;
   project: string;
@@ -31,8 +48,10 @@ export function sandboxWorkspaceViewPaths(params: Readonly<{
 
 export type SandboxControlSetup = Readonly<{
   channelDir: string;
+  statusDir: string;
   manifestPath: string;
   token: string;
+  generation: string;
 }>;
 
 export function sandboxControlPaths(params: Readonly<{
@@ -40,13 +59,19 @@ export function sandboxControlPaths(params: Readonly<{
   project: string;
   container: string;
   identity: SandboxWorkspaceIdentity;
-}>): Readonly<{ root: string; channelDir: string; manifestPath: string }> {
+}>): Readonly<{ root: string; channelDir: string; statusDir: string; processingDir: string; manifestPath: string }> {
   const identityKey = params.identity.mode === 'task-bound'
     ? `task-bound:${params.identity.taskId}`
     : 'branch-only';
   const digest = createHash('sha256').update(identityKey).digest('hex').slice(0, 16);
   const root = path.resolve(params.base, params.project, params.container, digest);
-  return { root, channelDir: path.join(root, 'channel'), manifestPath: path.join(root, 'manifest.json') };
+  return {
+    root,
+    channelDir: path.join(root, 'channel'),
+    statusDir: path.join(root, 'public'),
+    processingDir: path.join(root, 'processing'),
+    manifestPath: path.join(root, 'manifest.json')
+  };
 }
 
 function assertSafeDirectory(directory: string, expectedBase: string): void {
@@ -59,6 +84,44 @@ function assertSafeDirectory(directory: string, expectedBase: string): void {
   }
 }
 
+function assertSafeMountTargetPath(target: string, worktreeRoot: string, canonicalWorktreeRoot: string): void {
+  const relative = path.relative(worktreeRoot, target);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Sandbox workspace mount target escapes its worktree: ${target}`);
+  }
+  let current = worktreeRoot;
+  for (const segment of ['', ...relative.split(path.sep).filter(Boolean)]) {
+    current = segment ? path.join(current, segment) : current;
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        throw new Error(`Sandbox workspace mount target must not contain a symbolic link: ${current}`);
+      }
+      const canonicalRelative = path.relative(canonicalWorktreeRoot, fs.realpathSync.native(current));
+      if (canonicalRelative.startsWith('..') || path.isAbsolute(canonicalRelative)) {
+        throw new Error(`Sandbox workspace mount target escapes its real worktree: ${current}`);
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+  }
+}
+
+export function prepareSandboxWorkspaceMountTargets(worktreeRoot: string): void {
+  const resolvedWorktreeRoot = path.resolve(worktreeRoot);
+  const canonicalWorktreeRoot = fs.realpathSync.native(resolvedWorktreeRoot);
+  const workspaceRoot = path.resolve(resolvedWorktreeRoot, '.agents', 'workspace');
+  const statePaths = sandboxWorkspaceViewStatePaths(workspaceRoot);
+  const registryTarget = path.join(workspaceRoot, 'active', '.short-ids.json');
+  for (const target of [workspaceRoot, ...statePaths.map(({ hostPath }) => hostPath), registryTarget]) {
+    assertSafeMountTargetPath(target, resolvedWorktreeRoot, canonicalWorktreeRoot);
+  }
+  fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 });
+  for (const { hostPath } of statePaths) {
+    fs.mkdirSync(hostPath, { recursive: true, mode: 0o700 });
+  }
+  fs.closeSync(fs.openSync(registryTarget, 'a', 0o600));
+}
+
 export function assertSandboxTaskSource(repoRoot: string, taskId: string): string {
   if (!/^TASK-\d{8}-\d{6}$/.test(taskId)) throw new Error('SANDBOX_TASK_SOURCE_INVALID');
   const activeRoot = fs.realpathSync.native(path.join(repoRoot, '.agents', 'workspace', 'active'));
@@ -85,11 +148,10 @@ export function materializeSandboxWorkspaceView(params: Readonly<{
   assertSafeDirectory(projectRoot, path.resolve(params.base));
   assertSafeDirectory(root, projectRoot);
   fs.mkdirSync(root, { recursive: true, mode: 0o700 });
-  for (const state of ['active', 'completed', 'blocked', 'archive']) {
-    const stateDir = path.join(root, state);
-    assertSafeDirectory(stateDir, root);
-    fs.rmSync(stateDir, { recursive: true, force: true });
-    fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  for (const { hostPath } of sandboxWorkspaceViewStatePaths(root)) {
+    assertSafeDirectory(hostPath, root);
+    fs.rmSync(hostPath, { recursive: true, force: true });
+    fs.mkdirSync(hostPath, { recursive: true, mode: 0o700 });
   }
 
   const active = path.join(root, 'active');
@@ -119,12 +181,16 @@ export function materializeSandboxControl(params: Readonly<{
   branch: string;
   identity: SandboxWorkspaceIdentity;
 }>): SandboxControlSetup {
-  const { root, channelDir, manifestPath } = sandboxControlPaths(params);
+  const { root, channelDir, statusDir, processingDir, manifestPath } = sandboxControlPaths(params);
   assertSafeDirectory(root, path.resolve(params.base));
   const consumedDir = path.join(root, 'consumed');
   assertSafeDirectory(consumedDir, root);
   fs.rmSync(consumedDir, { recursive: true, force: true });
   fs.mkdirSync(consumedDir, { recursive: true, mode: 0o700 });
+  for (const directory of [statusDir, processingDir]) {
+    assertSafeDirectory(directory, root);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  }
   for (const queue of ['requests', 'responses']) {
     const directory = path.join(channelDir, queue);
     assertSafeDirectory(directory, root);
@@ -132,9 +198,10 @@ export function materializeSandboxControl(params: Readonly<{
     fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
   }
   const token = randomBytes(32).toString('hex');
+  const generation = randomBytes(16).toString('hex');
   const repoRoot = fs.realpathSync.native(params.repoRoot);
   const manifest: SandboxControlManifest = {
-    version: 2,
+    version: 3,
     repoRoot,
     worktreeRoot: fs.realpathSync.native(params.worktreeRoot),
     project: params.project,
@@ -143,8 +210,11 @@ export function materializeSandboxControl(params: Readonly<{
     mode: params.identity.mode,
     taskId: params.identity.mode === 'task-bound' ? params.identity.taskId : null,
     token,
-    channelDir
+    generation,
+    channelDir,
+    publicStatusDir: statusDir,
+    processingDir
   };
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest)}\n`, { mode: 0o600 });
-  return { channelDir, manifestPath, token };
+  return { channelDir, statusDir, manifestPath, token, generation };
 }

package/lib/sandbox/worktree-safety.ts

@@ -0,0 +1,234 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { runProbe } from './shell.ts';
+
+type WorktreeChange = {
+  indexStatus: string;
+  worktreeStatus: string;
+  path: string;
+  originalPath?: string;
+};
+
+type WorktreeSnapshot = {
+  worktree: string;
+  branch: string;
+  head: string;
+  changes: readonly WorktreeChange[];
+  identity: string;
+};
+
+type WorktreeInspection =
+  | { status: 'clean'; snapshot: WorktreeSnapshot }
+  | { status: 'dirty'; snapshot: WorktreeSnapshot }
+  | { status: 'failed'; worktree: string; message: string };
+
+type WorktreeRemovalPermit = {
+  mode: 'clean' | 'discard';
+  snapshot: WorktreeSnapshot;
+};
+
+type Probe = typeof runProbe;
+
+function probeText(probe: Probe, cwd: string, args: string[]): string {
+  const result = probe('git', ['-C', cwd, ...args], { encoding: 'utf8' });
+  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 parseStatus(raw: string): WorktreeChange[] {
+  const records = raw.split('\0');
+  const changes: WorktreeChange[] = [];
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index] ?? '';
+    if (!record || record.startsWith('# ')) continue;
+    if (record.startsWith('? ')) {
+      changes.push({ indexStatus: '?', worktreeStatus: '?', path: record.slice(2) });
+      continue;
+    }
+    if (record.startsWith('1 ')) {
+      const match = /^1 (..) \S+ \S+ \S+ \S+ \S+ \S+ (.*)$/s.exec(record);
+      if (!match) throw new Error('Unable to parse git porcelain v2 ordinary record');
+      changes.push({ indexStatus: match[1]![0]!, worktreeStatus: match[1]![1]!, path: match[2]! });
+      continue;
+    }
+    if (record.startsWith('2 ')) {
+      const match = /^2 (..) \S+ \S+ \S+ \S+ \S+ \S+ \S+ (.*)$/s.exec(record);
+      const originalPath = records[++index];
+      if (!match || originalPath === undefined || originalPath === '') {
+        throw new Error('Unable to parse git porcelain v2 rename record');
+      }
+      changes.push({
+        indexStatus: match[1]![0]!,
+        worktreeStatus: match[1]![1]!,
+        path: match[2]!,
+        originalPath
+      });
+      continue;
+    }
+    if (record.startsWith('u ')) {
+      const match = /^u (..) \S+ \S+ \S+ \S+ \S+ \S+ \S+ \S+ (.*)$/s.exec(record);
+      if (!match) throw new Error('Unable to parse git porcelain v2 unmerged record');
+      changes.push({ indexStatus: match[1]![0]!, worktreeStatus: match[1]![1]!, path: match[2]! });
+      continue;
+    }
+    throw new Error(`Unsupported git porcelain v2 record '${record[0] ?? ''}'`);
+  }
+  return changes;
+}
+
+function updatePart(hash: ReturnType<typeof createHash>, label: string, value: string | Buffer): void {
+  const data = Buffer.isBuffer(value) ? value : Buffer.from(value, 'utf8');
+  hash.update(`${label.length}:${label}:${data.length}:`, 'utf8');
+  hash.update(data);
+}
+
+function resolveSnapshotPath(worktree: string, relativePath: string): string {
+  const resolved = path.resolve(worktree, relativePath);
+  const relative = path.relative(worktree, resolved);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Git reported a path outside the worktree: ${JSON.stringify(relativePath)}`);
+  }
+  return resolved;
+}
+
+function hashPath(hash: ReturnType<typeof createHash>, worktree: string, relativePath: string, probe: Probe): void {
+  updatePart(hash, 'path', relativePath);
+  const target = resolveSnapshotPath(worktree, relativePath);
+  let stat: fs.Stats;
+  try {
+    stat = fs.lstatSync(target);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      updatePart(hash, 'kind', 'absent');
+      return;
+    }
+    throw error;
+  }
+
+  updatePart(hash, 'mode', String(stat.mode & 0o7777));
+  if (stat.isFile()) {
+    updatePart(hash, 'kind', 'file');
+    updatePart(hash, 'content', fs.readFileSync(target));
+    return;
+  }
+  if (stat.isSymbolicLink()) {
+    updatePart(hash, 'kind', 'symlink');
+    updatePart(hash, 'target', fs.readlinkSync(target));
+    return;
+  }
+  if (stat.isDirectory()) {
+    updatePart(hash, 'kind', 'git-directory');
+    const nestedHead = probeText(probe, target, ['rev-parse', '--verify', 'HEAD']).trim();
+    const nestedStatus = probeText(probe, target, [
+      'status', '--porcelain=v2', '-z', '--branch', '--untracked-files=all', '--ignore-submodules=none'
+    ]);
+    const nestedIndex = probeText(probe, target, ['ls-files', '--stage', '-z']);
+    updatePart(hash, 'nested-head', nestedHead);
+    updatePart(hash, 'nested-status', nestedStatus);
+    updatePart(hash, 'nested-index', nestedIndex);
+    for (const change of parseStatus(nestedStatus)) {
+      hashPath(hash, target, change.path, probe);
+      if (change.originalPath) hashPath(hash, target, change.originalPath, probe);
+    }
+    return;
+  }
+  throw new Error(`Unsupported file type in dirty snapshot: ${JSON.stringify(relativePath)}`);
+}
+
+function captureOnce(worktree: string, probe: Probe): WorktreeSnapshot {
+  const resolvedWorktree = path.resolve(worktree);
+  const branch = probeText(probe, resolvedWorktree, ['rev-parse', '--abbrev-ref', 'HEAD']).trim();
+  const head = probeText(probe, resolvedWorktree, ['rev-parse', '--verify', 'HEAD']).trim();
+  const status = probeText(probe, resolvedWorktree, [
+    'status', '--porcelain=v2', '-z', '--branch', '--untracked-files=all', '--ignore-submodules=none'
+  ]);
+  const index = probeText(probe, resolvedWorktree, ['ls-files', '--stage', '-z']);
+  if (!branch) throw new Error('Unable to determine worktree branch');
+  if (!head) throw new Error('Unable to determine worktree HEAD');
+  const changes = parseStatus(status);
+  const hash = createHash('sha256');
+  updatePart(hash, 'worktree', resolvedWorktree);
+  updatePart(hash, 'branch', branch);
+  updatePart(hash, 'head', head);
+  updatePart(hash, 'status', status);
+  updatePart(hash, 'index', index);
+  for (const change of changes) {
+    hashPath(hash, resolvedWorktree, change.path, probe);
+    if (change.originalPath) hashPath(hash, resolvedWorktree, change.originalPath, probe);
+  }
+  return { worktree: resolvedWorktree, branch, head, changes, identity: hash.digest('hex') };
+}
+
+function inspectWorktree(worktree: string, { probe = runProbe }: { probe?: Probe } = {}): WorktreeInspection {
+  const resolvedWorktree = path.resolve(worktree);
+  try {
+    const first = captureOnce(resolvedWorktree, probe);
+    const second = captureOnce(resolvedWorktree, probe);
+    if (first.identity !== second.identity) {
+      return { status: 'failed', worktree: resolvedWorktree, message: 'Snapshot changed while inspecting 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));
+}
+
+function createCleanPermit(snapshot: WorktreeSnapshot): WorktreeRemovalPermit {
+  if (snapshot.changes.length > 0) throw new Error('Cannot create a clean permit for a dirty worktree');
+  return { mode: 'clean', snapshot };
+}
+
+function createDiscardPermit(snapshot: WorktreeSnapshot): WorktreeRemovalPermit {
+  if (snapshot.changes.length === 0) throw new Error('Cannot create a discard permit for a clean worktree');
+  return { mode: 'discard', snapshot };
+}
+
+function verifyWorktreePermit(
+  permit: WorktreeRemovalPermit,
+  options: { probe?: Probe } = {}
+): WorktreeSnapshot {
+  const current = 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}`);
+  }
+  return current.snapshot;
+}
+
+function formatWorktreeSnapshot(snapshot: WorktreeSnapshot): string {
+  const lines = snapshot.changes.map((change) => {
+    const rename = change.originalPath ? ` <- ${JSON.stringify(change.originalPath)}` : '';
+    return `  ${change.indexStatus}${change.worktreeStatus} ${JSON.stringify(change.path)}${rename}`;
+  });
+  return [
+    `Worktree: ${JSON.stringify(snapshot.worktree)}`,
+    `Branch: ${snapshot.branch}`,
+    `HEAD: ${snapshot.head}`,
+    ...lines,
+    `Snapshot identity: ${snapshot.identity}`
+  ].join('\n');
+}
+
+export {
+  createCleanPermit,
+  createDiscardPermit,
+  formatWorktreeSnapshot,
+  inspectWorktree,
+  inspectWorktrees,
+  verifyWorktreePermit
+};
+export type { WorktreeChange, WorktreeInspection, WorktreeRemovalPermit, WorktreeSnapshot };

package/lib/server/process-control.ts

@@ -24,6 +24,17 @@ export type StopCommand =
   | { kind: 'signal'; signal: NodeJS.Signals }
   | { kind: 'exec'; command: string; args: string[] };
 
+export type ProcessTreeStopCommand =
+  | { kind: 'group-signal'; pid: number; signal: NodeJS.Signals }
+  | { kind: 'exec'; command: string; args: string[] };
+
+export function buildProcessTreeStopCommand(pid: number, platform: NodeJS.Platform): ProcessTreeStopCommand {
+  if (platform === 'win32') {
+    return { kind: 'exec', command: 'taskkill', args: ['/PID', String(pid), '/T', '/F'] };
+  }
+  return { kind: 'group-signal', pid: -pid, signal: 'SIGTERM' };
+}
+
 export function buildStopCommand(pid: number, platform: NodeJS.Platform): StopCommand {
   if (platform === 'win32') {
     return { kind: 'exec', command: 'taskkill', args: ['/PID', String(pid), '/T', '/F'] };

package/lib/task/artifact-lifecycle.ts

@@ -16,6 +16,7 @@ const artifactFamilyCatalog = [
   { family: 'code', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['实现报告', 'Implementation Report'] },
   { family: 'review-code', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['代码审查', 'Code Review'] },
   { family: 'manual-validation', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['人工验证', 'Manual Validation'] },
+  { family: 'validation-run', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['验证运行证据', 'Validation Run Evidence'] },
   { family: 'pr-review', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['PR 审查报告', 'PR Review Report'] }
 ] as const;
 
@@ -257,7 +258,8 @@ const OPTIONAL_CONTEXT: Partial<Record<ArtifactFamily, { family: ArtifactFamily;
   analysis: { family: 'review-analysis', requireReference: true },
   plan: { family: 'review-plan', requireReference: true },
   'review-code': { family: 'review-plan' },
-  'manual-validation': { family: 'review-code' }
+  'manual-validation': { family: 'review-code' },
+  'validation-run': { family: 'review-code' }
 };
 
 function resolveArtifactContext(taskRef: string, family: string, options: InspectOptions = {}): ArtifactContextResult {
@@ -376,12 +378,11 @@ function resolveDecisionImplementationInput(
   if (pending.length === 0) return { input: null };
   const activity = locateActivityLog(content);
   if (!activity) return { error: 'task has no unique Activity Log section' };
-  const reviewEntries = activity.entries.filter((entry) =>
+  const completed = activity.entries.some((entry) =>
     /^Review Code \(Round \d+\)$/.test(entry.step) && entry.note.includes(`→ ${review.name}`)
   );
-  const completed = reviewEntries.at(-1);
   if (!completed) return { error: `cannot find completed Activity Log identity for ${review.name}` };
-  try { return { input: selectPendingImplementationInput(rows, completed.time) }; }
+  try { return { input: selectPendingImplementationInput(rows) }; }
   catch (error) { return { error: error instanceof Error ? error.message : String(error) }; }
 }
 

package/lib/task/codex-orchestration.ts

@@ -0,0 +1,233 @@
+import {
+  preflightCodexLifecycleEvidence,
+  resolveCodexSpawnedChild,
+  resolveCodexTerminal,
+  resolveCodexThread
+} from '../agent-clients/adapters/codex-lifecycle/app-server.ts';
+import { createCodexLifecycleStore } from '../agent-clients/adapters/codex-lifecycle/store.ts';
+import type { AgentClientId } from '../agent-clients/types.ts';
+import {
+  activateMatchingOrchestrationDelegation,
+  pauseMatchingOrchestrationDelegation,
+  prepareOrchestrationDelegation,
+  reconcileMatchingOrchestrationDelegation,
+  sealMatchingOrchestrationDelegationWithHostEvidence
+} from './orchestration.ts';
+import type { OrchestrationOptions, OrchestrationResult } from './orchestration.ts';
+
+type LifecycleStore = ReturnType<typeof createCodexLifecycleStore>;
+type CodexBridgeOptions = Readonly<{
+  repoRoot?: string;
+  store?: LifecycleStore;
+  preflight?: typeof preflightCodexLifecycleEvidence;
+  resolveThread?: typeof resolveCodexThread;
+  resolveTerminal?: typeof resolveCodexTerminal;
+  orchestrationOptions?: OrchestrationOptions;
+}>;
+
+type CodexSpawnIdentity = Readonly<{
+  sessionId: string;
+  turnId: string;
+  toolUseId: string;
+  transcriptPath: string;
+  nativeAgent: string;
+  taskName: string;
+  requestedModel?: string;
+  requestedReasoningEffort?: string;
+}>;
+
+function coreOptions(options: CodexBridgeOptions): OrchestrationOptions {
+  return { ...options.orchestrationOptions, repoRoot: options.repoRoot ?? options.orchestrationOptions?.repoRoot };
+}
+
+function bridgeFailure(code: string, message: string): OrchestrationResult {
+  return {
+    status: 'failed', changed: false, taskId: null, run: null, next: null,
+    error: { code, message }
+  };
+}
+
+function pauseBridge(code: string, message: string, options: CodexBridgeOptions): OrchestrationResult {
+  const paused = pauseMatchingOrchestrationDelegation('codex', code, message, coreOptions(options));
+  return paused.error?.code === 'ORCHESTRATION_DELEGATION_MISSING'
+    ? bridgeFailure(code, message)
+    : paused;
+}
+
+function requiredStore(options: CodexBridgeOptions): LifecycleStore {
+  if (!options.store) throw new Error('Codex lifecycle store is required for orchestration bridge events');
+  return options.store;
+}
+
+async function prepareCodexOrchestrationDelegation(
+  taskRef: string,
+  input: Readonly<{
+    client: AgentClientId;
+    requestedModel?: string;
+    requestedReasoningEffort?: string;
+  }>,
+  options: CodexBridgeOptions = {}
+): Promise<OrchestrationResult> {
+  if (input.client !== 'codex') return prepareOrchestrationDelegation(taskRef, input, coreOptions(options));
+  try {
+    await (options.preflight ?? preflightCodexLifecycleEvidence)(options.repoRoot ?? process.cwd());
+  } catch (error) {
+    return bridgeFailure(
+      'ORCHESTRATION_CLIENT_PREFLIGHT_FAILED',
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+  return prepareOrchestrationDelegation(taskRef, input, coreOptions(options));
+}
+
+async function activateCodexOrchestrationDelegation(
+  childThreadId: string,
+  options: CodexBridgeOptions = {}
+): Promise<OrchestrationResult> {
+  try {
+    const store = requiredStore(options);
+    const resolved = await (options.resolveThread ?? resolveCodexThread)(childThreadId);
+    store.apply(resolved.resolution.thread);
+    for (const reroute of resolved.reroutes) store.apply(reroute);
+    store.apply(resolved.resolution.settings);
+    const record = store.read(childThreadId);
+    const evidence = record.state.startEvidence;
+    if (record.state.status !== 'start-ready' || !evidence) {
+      return pauseBridge('ORCHESTRATION_CODEX_START_EVIDENCE_INVALID', 'Codex lifecycle start evidence is not ready', options);
+    }
+    return activateMatchingOrchestrationDelegation('codex', {
+      nativeAgent: evidence.nativeAgent,
+      childId: evidence.childThreadId,
+      parentId: evidence.parentThreadId,
+      spawnMode: evidence.spawnMode,
+      actualModel: evidence.actualModel.value,
+      actualReasoningEffort: evidence.actualReasoningEffort.value,
+      ...(evidence.modelFallbackReason ? { modelFallbackReason: evidence.modelFallbackReason } : {}),
+      ...(evidence.reasoningEffortFallbackReason
+        ? { reasoningEffortFallbackReason: evidence.reasoningEffortFallbackReason }
+        : {}),
+      hostEvidence: {
+        kind: 'codex-lifecycle-v1',
+        hookDefinitionHash: evidence.hookDefinitionHash,
+        startRevision: record.revision
+      }
+    }, coreOptions(options));
+  } catch (error) {
+    return pauseBridge('ORCHESTRATION_CODEX_START_FAILED', error instanceof Error ? error.message : String(error), options);
+  }
+}
+
+async function activateCodexSpawnDelegation(
+  spawn: CodexSpawnIdentity,
+  options: CodexBridgeOptions = {}
+): Promise<OrchestrationResult> {
+  try {
+    const store = requiredStore(options);
+    const childThreadId = resolveCodexSpawnedChild(spawn.transcriptPath, spawn);
+    const resolved = await (options.resolveThread ?? resolveCodexThread)(childThreadId);
+    store.applyToSpawn(spawn, {
+      type: 'hook-child',
+      sessionId: spawn.sessionId,
+      turnId: spawn.turnId,
+      childThreadId,
+      parentThreadId: resolved.resolution.thread.parentThreadId,
+      nativeAgent: spawn.nativeAgent,
+      source: 'parent-rollout'
+    });
+    return activateCodexOrchestrationDelegation(childThreadId, {
+      ...options,
+      store,
+      resolveThread: async () => resolved
+    });
+  } catch (error) {
+    return pauseBridge('ORCHESTRATION_CODEX_START_FAILED', error instanceof Error ? error.message : String(error), options);
+  }
+}
+
+async function sealCodexOrchestrationDelegation(
+  childThreadId: string,
+  options: CodexBridgeOptions = {}
+): Promise<OrchestrationResult> {
+  try {
+    const store = requiredStore(options);
+    const existing = store.read(childThreadId);
+    if (!existing.consumer) {
+      store.apply(await (options.resolveTerminal ?? resolveCodexTerminal)(childThreadId));
+    }
+    const record = store.read(childThreadId);
+    const evidence = record.state.stopEvidence;
+    if (record.state.status !== 'stop-ready' || !evidence || !record.state.startEvidence) {
+      return pauseBridge('ORCHESTRATION_CODEX_STOP_EVIDENCE_INVALID', 'Codex lifecycle stop evidence is not ready', options);
+    }
+    return sealMatchingOrchestrationDelegationWithHostEvidence(
+      'codex',
+      { nativeAgent: record.state.startEvidence.nativeAgent, childId: childThreadId },
+      (receipt) => {
+        const consumed = store.consume(childThreadId, receipt.id, receipt.hostEvidence?.hookDefinitionHash);
+        return {
+          stopRevision: consumed.revision,
+          consumer: consumed.consumer!,
+          consumedAt: consumed.consumedAt!
+        };
+      },
+      coreOptions(options)
+    );
+  } catch (error) {
+    return pauseBridge('ORCHESTRATION_CODEX_STOP_FAILED', error instanceof Error ? error.message : String(error), options);
+  }
+}
+
+async function sealCodexParentDelegation(
+  parentThreadId: string,
+  options: CodexBridgeOptions = {}
+): Promise<OrchestrationResult> {
+  try {
+    const store = requiredStore(options);
+    const candidates = store.findByParent(parentThreadId);
+    if (!candidates.length) return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+    for (const consumed of candidates.filter((record) => record.consumer)) {
+      const replayed = await sealCodexOrchestrationDelegation(consumed.state.startEvidence!.childThreadId, options);
+      if (replayed.error?.code !== 'ORCHESTRATION_DELEGATION_MISSING') return replayed;
+    }
+    const active = candidates.find((record) => !record.consumer);
+    if (!active) return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+    const start = active.state.startEvidence!;
+    const child = active.state.child!;
+    if (!active.state.terminal) {
+      store.apply(await (options.resolveTerminal ?? resolveCodexTerminal)(start.childThreadId));
+    }
+    if (!store.read(start.childThreadId).state.stop) {
+      store.apply({
+        type: 'hook-stop',
+        sessionId: parentThreadId,
+        turnId: child.turnId,
+        childThreadId: start.childThreadId,
+        nativeAgent: start.nativeAgent,
+        source: 'parent-rollout'
+      });
+    }
+    return sealCodexOrchestrationDelegation(start.childThreadId, options);
+  } catch (error) {
+    if (error instanceof Error && error.message === 'CODEX_TURN_NOT_TERMINAL') {
+      return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'The matching Codex child has not completed');
+    }
+    return pauseBridge('ORCHESTRATION_CODEX_STOP_FAILED', error instanceof Error ? error.message : String(error), options);
+  }
+}
+
+function reconcileCodexOrchestrationDelegation(
+  childThreadId: string,
+  options: CodexBridgeOptions = {}
+): OrchestrationResult {
+  return reconcileMatchingOrchestrationDelegation('codex', childThreadId, coreOptions(options));
+}
+
+export {
+  activateCodexOrchestrationDelegation,
+  activateCodexSpawnDelegation,
+  prepareCodexOrchestrationDelegation,
+  reconcileCodexOrchestrationDelegation,
+  sealCodexParentDelegation,
+  sealCodexOrchestrationDelegation
+};
+export type { CodexBridgeOptions };