@fitlab-ai/agent-infra 0.9.8 → 0.9.10

package/lib/agent-clients/adapters/codex-lifecycle/build-identity.ts

@@ -3,6 +3,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import semver from 'semver';
+
 const LIFECYCLE_PROTOCOL_VERSION = 3;
 
 type LifecycleBuildIdentity = Readonly<{
@@ -26,12 +28,27 @@ type IdentityVerification = Readonly<{
   ok: boolean;
   code: string | null;
   message: string | null;
+  warnings: readonly LifecycleIdentityWarning[];
+}>;
+
+type LifecycleIdentityWarning = Readonly<{
+  code: 'CODEX_LIFECYCLE_BUILD_MISMATCH' | 'CODEX_LIFECYCLE_CONTRACT_MISMATCH';
+  message: string;
+  action: 'rebuild-sandbox';
 }>;
 
 function exactText(value: unknown): value is string {
   return typeof value === 'string' && value.trim() === value && value.length > 0;
 }
 
+function isCanonicalLifecyclePackageVersion(value: unknown): value is string {
+  return typeof value === 'string' && semver.valid(value) === value;
+}
+
+function isLifecycleProtocolVersion(value: unknown): value is typeof LIFECYCLE_PROTOCOL_VERSION {
+  return value === LIFECYCLE_PROTOCOL_VERSION;
+}
+
 function normalizeRelativePath(value: string): string {
   return value.replaceAll('\\', '/');
 }
@@ -191,36 +208,46 @@ function verifyLifecycleBuildIdentity(
     return {
       ok: false,
       code: 'CODEX_LIFECYCLE_PROTOCOL_MISMATCH',
-      message: 'Codex lifecycle protocol version does not match'
+      message: 'Codex lifecycle protocol version does not match',
+      warnings: []
     };
   }
+  const warnings: LifecycleIdentityWarning[] = [];
   if (actual.packageVersion !== expected.packageVersion
     || actual.internalExecutableBuildHash !== expected.internalExecutableBuildHash) {
-    return {
-      ok: false,
+    warnings.push({
       code: 'CODEX_LIFECYCLE_BUILD_MISMATCH',
-      message: 'Codex lifecycle executable build identity does not match'
-    };
+      message: 'Codex lifecycle executable build identity differs; rebuild the sandbox if the runtime is stale',
+      action: 'rebuild-sandbox'
+    });
   }
   if (actual.lifecycleContractHash !== expected.lifecycleContractHash) {
-    return {
-      ok: false,
+    warnings.push({
       code: 'CODEX_LIFECYCLE_CONTRACT_MISMATCH',
-      message: 'Codex lifecycle contract identity does not match'
-    };
+      message: 'Codex lifecycle contract identity differs; rebuild the sandbox if the runtime is stale',
+      action: 'rebuild-sandbox'
+    });
   }
-  return { ok: true, code: null, message: null };
+  return {
+    ok: true,
+    code: null,
+    message: null,
+    warnings: Object.freeze(warnings)
+  };
 }
 
 export {
   LIFECYCLE_PROTOCOL_VERSION,
   computeLifecycleBuildIdentity,
+  isCanonicalLifecyclePackageVersion,
+  isLifecycleProtocolVersion,
   readLifecycleManifestFiles,
   resolveLifecycleExecutableFiles,
   verifyLifecycleBuildIdentity
 };
 export type {
   IdentityVerification,
+  LifecycleIdentityWarning,
   LifecycleBuildIdentity,
   LifecycleManifestFiles,
   LifecycleBuildIdentityOptions

package/lib/agent-clients/adapters/codex-lifecycle/capability-store.ts

@@ -2,7 +2,12 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { verifyLifecycleBuildIdentity } from './build-identity.ts';
+import {
+  isCanonicalLifecyclePackageVersion,
+  isLifecycleProtocolVersion,
+  LIFECYCLE_PROTOCOL_VERSION,
+  verifyLifecycleBuildIdentity
+} from './build-identity.ts';
 import type { LifecycleBuildIdentity } from './build-identity.ts';
 import { resolveAgentRuntimeStoreRoot } from '../../../runtime/agent-runtime.ts';
 
@@ -11,6 +16,36 @@ type CodexControllerBinding = Readonly<{
   instanceDigest: string;
   controlGeneration: string;
 }>;
+type CodexCapabilityProjection = Readonly<
+  | { kind: 'absent' }
+  | { kind: 'protocol-version'; value: typeof LIFECYCLE_PROTOCOL_VERSION }
+  | { kind: 'semver'; value: string }
+  | { kind: 'digest-prefix'; value: string }
+  | { kind: 'presence'; present: boolean }
+>;
+type CodexCapabilityProvenanceField = Readonly<{
+  matches: boolean;
+  expected: CodexCapabilityProjection;
+  actual: CodexCapabilityProjection;
+}>;
+type CodexCapabilityProvenanceDetail = Readonly<{
+  kind: 'codex-capability-provenance-mismatch';
+  version: 1;
+  fields: Readonly<{
+    taskId: CodexCapabilityProvenanceField;
+    hookDefinitionHash: CodexCapabilityProvenanceField;
+    buildIdentity: Readonly<{
+      protocolVersion: CodexCapabilityProvenanceField;
+      packageVersion: CodexCapabilityProvenanceField;
+      internalExecutableBuildHash: CodexCapabilityProvenanceField;
+      lifecycleContractHash: CodexCapabilityProvenanceField;
+    }>;
+    controller: Readonly<{
+      instanceDigest: CodexCapabilityProvenanceField;
+      controlGeneration: CodexCapabilityProvenanceField;
+    }>;
+  }>;
+}>;
 type CodexCapabilityRecord = Readonly<{
   schemaVersion: 1;
   revision: number;
@@ -45,23 +80,222 @@ const DEFAULT_MAX_RECORDS = 128;
 const LOCK_RETRY_MS = 10;
 const LOCK_TIMEOUT_MS = 1_000;
 const LOCK_STALE_MS = 30_000;
+const DETAIL_DOMAIN = 'codex-capability-provenance/v1';
+const TASK_ID_PATTERN = /^TASK-[0-9]{8}-[0-9]{6}$/u;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+const DIGEST_PREFIX_PATTERN = /^sha256:[0-9a-f]{16}$/u;
 
 function digest(value: string): string {
   return crypto.createHash('sha256').update(value).digest('hex');
 }
 
-function capabilityError(code: string, message: string): Error {
+function capabilityError(code: string, message: string, detail?: CodexCapabilityProvenanceDetail): Error {
   const error = new Error(`${code}: ${message}`);
   error.name = code;
+  if (detail) (error as Error & { detail: CodexCapabilityProvenanceDetail }).detail = detail;
   return error;
 }
 
+function objectValue(value: unknown, key: string): unknown {
+  if (!value || typeof value !== 'object') return undefined;
+  return (value as Record<string, unknown>)[key];
+}
+
+function digestPrefix(fieldName: string, value: string): CodexCapabilityProjection {
+  return {
+    kind: 'digest-prefix',
+    value: `sha256:${crypto.createHash('sha256')
+      .update(`${DETAIL_DOMAIN}\0${fieldName}\0${value}`)
+      .digest('hex')
+      .slice(0, 16)}`
+  };
+}
+
+function projectDigest(fieldName: string, value: unknown, pattern: RegExp): CodexCapabilityProjection {
+  return typeof value === 'string' && pattern.test(value) ? digestPrefix(fieldName, value) : { kind: 'absent' };
+}
+
+function projectTaskId(value: unknown): CodexCapabilityProjection {
+  return projectDigest('taskId', value, TASK_ID_PATTERN);
+}
+
+function projectHash(fieldName: string, value: unknown): CodexCapabilityProjection {
+  return projectDigest(fieldName, value, SHA256_PATTERN);
+}
+
+function projectProtocol(value: unknown): CodexCapabilityProjection {
+  return isLifecycleProtocolVersion(value)
+    ? { kind: 'protocol-version', value: LIFECYCLE_PROTOCOL_VERSION }
+    : { kind: 'absent' };
+}
+
+function projectPackageVersion(value: unknown): CodexCapabilityProjection {
+  return isCanonicalLifecyclePackageVersion(value)
+    ? { kind: 'semver', value }
+    : { kind: 'absent' };
+}
+
+function projectPresence(value: unknown): CodexCapabilityProjection {
+  return { kind: 'presence', present: Boolean(value && typeof value === 'object') };
+}
+
+function field(matches: boolean, expected: CodexCapabilityProjection, actual: CodexCapabilityProjection): CodexCapabilityProvenanceField {
+  return { matches, expected, actual };
+}
+
+function provenanceDetail(
+  record: CodexCapabilityRecord,
+  expected: Readonly<{
+    taskId: string;
+    hookDefinitionHash: string;
+    buildIdentity: LifecycleBuildIdentity;
+    controller?: CodexControllerBinding;
+  }>
+): CodexCapabilityProvenanceDetail {
+  const actualBuild = record.buildIdentity;
+  const expectedBuild = expected.buildIdentity;
+  const actualController = record.controller;
+  const expectedController = expected.controller ?? null;
+  return {
+    kind: 'codex-capability-provenance-mismatch',
+    version: 1,
+    fields: {
+      taskId: field(
+        record.taskId === expected.taskId,
+        projectTaskId(expected.taskId),
+        projectTaskId(record.taskId)
+      ),
+      hookDefinitionHash: field(
+        record.hookDefinitionHash === expected.hookDefinitionHash,
+        projectHash('hookDefinitionHash', expected.hookDefinitionHash),
+        projectHash('hookDefinitionHash', record.hookDefinitionHash)
+      ),
+      buildIdentity: {
+        protocolVersion: field(
+          objectValue(actualBuild, 'protocolVersion') === objectValue(expectedBuild, 'protocolVersion'),
+          projectProtocol(objectValue(expectedBuild, 'protocolVersion')),
+          projectProtocol(objectValue(actualBuild, 'protocolVersion'))
+        ),
+        packageVersion: field(
+          objectValue(actualBuild, 'packageVersion') === objectValue(expectedBuild, 'packageVersion'),
+          projectPackageVersion(objectValue(expectedBuild, 'packageVersion')),
+          projectPackageVersion(objectValue(actualBuild, 'packageVersion'))
+        ),
+        internalExecutableBuildHash: field(
+          objectValue(actualBuild, 'internalExecutableBuildHash') === objectValue(expectedBuild, 'internalExecutableBuildHash'),
+          projectHash('buildIdentity.internalExecutableBuildHash', objectValue(expectedBuild, 'internalExecutableBuildHash')),
+          projectHash('buildIdentity.internalExecutableBuildHash', objectValue(actualBuild, 'internalExecutableBuildHash'))
+        ),
+        lifecycleContractHash: field(
+          objectValue(actualBuild, 'lifecycleContractHash') === objectValue(expectedBuild, 'lifecycleContractHash'),
+          projectHash('buildIdentity.lifecycleContractHash', objectValue(expectedBuild, 'lifecycleContractHash')),
+          projectHash('buildIdentity.lifecycleContractHash', objectValue(actualBuild, 'lifecycleContractHash'))
+        )
+      },
+      controller: {
+        instanceDigest: field(
+          sameControllerField(actualController, expectedController, 'instanceDigest'),
+          projectPresence(objectValue(expectedController, 'instanceDigest') === undefined ? null : expectedController),
+          projectPresence(objectValue(actualController, 'instanceDigest') === undefined ? null : actualController)
+        ),
+        controlGeneration: field(
+          sameControllerField(actualController, expectedController, 'controlGeneration'),
+          projectPresence(objectValue(expectedController, 'controlGeneration') === undefined ? null : expectedController),
+          projectPresence(objectValue(actualController, 'controlGeneration') === undefined ? null : actualController)
+        )
+      }
+    }
+  };
+}
+
+function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  return Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function isCodexControllerBinding(value: unknown): value is CodexControllerBinding {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return exactKeys(record, ['instanceDigest', 'controlGeneration'])
+    && typeof record.instanceDigest === 'string'
+    && typeof record.controlGeneration === 'string';
+}
+
+function isProjection(value: unknown): value is CodexCapabilityProjection {
+  if (!value || typeof value !== 'object') return false;
+  const record = value as Record<string, unknown>;
+  if (record.kind === 'absent') return exactKeys(record, ['kind']);
+  if (record.kind === 'protocol-version') {
+    return exactKeys(record, ['kind', 'value']) && isLifecycleProtocolVersion(record.value);
+  }
+  if (record.kind === 'semver') {
+    return exactKeys(record, ['kind', 'value']) && isCanonicalLifecyclePackageVersion(record.value);
+  }
+  if (record.kind === 'digest-prefix') {
+    return exactKeys(record, ['kind', 'value'])
+      && typeof record.value === 'string'
+      && DIGEST_PREFIX_PATTERN.test(record.value);
+  }
+  if (record.kind === 'presence') {
+    return exactKeys(record, ['kind', 'present']) && typeof record.present === 'boolean';
+  }
+  return false;
+}
+
+function isProvenanceField(value: unknown): value is CodexCapabilityProvenanceField {
+  if (!value || typeof value !== 'object') return false;
+  const record = value as Record<string, unknown>;
+  return exactKeys(record, ['matches', 'expected', 'actual'])
+    && typeof record.matches === 'boolean'
+    && isProjection(record.expected)
+    && isProjection(record.actual);
+}
+
+function isCodexCapabilityProvenanceDetail(value: unknown): value is CodexCapabilityProvenanceDetail {
+  if (!value || typeof value !== 'object') return false;
+  const record = value as Record<string, unknown>;
+  if (!exactKeys(record, ['kind', 'version', 'fields'])
+    || record.kind !== 'codex-capability-provenance-mismatch'
+    || record.version !== 1
+    || !record.fields || typeof record.fields !== 'object') return false;
+  const fields = record.fields as Record<string, unknown>;
+  if (!exactKeys(fields, ['taskId', 'hookDefinitionHash', 'buildIdentity', 'controller'])
+    || !isProvenanceField(fields.taskId)
+    || !isProvenanceField(fields.hookDefinitionHash)) return false;
+  const buildIdentity = fields.buildIdentity;
+  const controller = fields.controller;
+  if (!buildIdentity || typeof buildIdentity !== 'object' || !controller || typeof controller !== 'object') return false;
+  const build = buildIdentity as Record<string, unknown>;
+  const binding = controller as Record<string, unknown>;
+  return exactKeys(build, ['protocolVersion', 'packageVersion', 'internalExecutableBuildHash', 'lifecycleContractHash'])
+    && exactKeys(binding, ['instanceDigest', 'controlGeneration'])
+    && isProvenanceField(build.protocolVersion)
+    && isProvenanceField(build.packageVersion)
+    && isProvenanceField(build.internalExecutableBuildHash)
+    && isProvenanceField(build.lifecycleContractHash)
+    && isProvenanceField(binding.instanceDigest)
+    && isProvenanceField(binding.controlGeneration);
+}
+
+function sameControllerField(
+  left: unknown,
+  right: unknown,
+  key: keyof CodexControllerBinding
+): boolean {
+  if (left === null || right === null) return left === null && right === null;
+  return isCodexControllerBinding(left)
+    && isCodexControllerBinding(right)
+    && left[key] === right[key];
+}
+
 function sameController(
-  left: CodexControllerBinding | null,
-  right: CodexControllerBinding | null
+  left: unknown,
+  right: unknown
 ): boolean {
-  return left?.instanceDigest === right?.instanceDigest
-    && left?.controlGeneration === right?.controlGeneration;
+  if (left === null || right === null) return left === null && right === null;
+  return isCodexControllerBinding(left)
+    && isCodexControllerBinding(right)
+    && left.instanceDigest === right.instanceDigest
+    && left.controlGeneration === right.controlGeneration;
 }
 
 function createCodexCapabilityStore(options: CodexCapabilityStoreOptions = {}) {
@@ -275,27 +509,54 @@ function createCodexCapabilityStore(options: CodexCapabilityStoreOptions = {}) {
     return next;
   }
 
-  function consume(token: string, expected: Readonly<{
+  function validateRecord(record: CodexCapabilityRecord, expected: Readonly<{
     taskId: string;
     hookDefinitionHash: string;
     buildIdentity: LifecycleBuildIdentity;
     controller?: CodexControllerBinding;
   }>): CodexCapabilityRecord {
-    sweep();
-    const { file, record } = loadActive(token);
     if (record.status === 'consumed') {
       throw capabilityError('CODEX_CAPABILITY_REPLAY', 'capability token was already consumed');
     }
     if (record.status !== 'attested') {
       throw capabilityError('CODEX_CAPABILITY_NOT_ATTESTED', 'capability token has no current-session hook attestation');
     }
-    const identity = verifyLifecycleBuildIdentity(record.buildIdentity, expected.buildIdentity);
+    const identity = record.buildIdentity && typeof record.buildIdentity === 'object'
+      ? verifyLifecycleBuildIdentity(record.buildIdentity, expected.buildIdentity)
+      : { ok: false };
     if (!identity.ok
       || record.taskId !== expected.taskId
       || record.hookDefinitionHash !== expected.hookDefinitionHash
       || !sameController(record.controller, expected.controller ?? null)) {
-      throw capabilityError('CODEX_CAPABILITY_PROVENANCE_MISMATCH', 'capability consumption identity does not match');
+      throw capabilityError(
+        'CODEX_CAPABILITY_PROVENANCE_MISMATCH',
+        'capability consumption identity does not match',
+        provenanceDetail(record, expected)
+      );
     }
+    return record;
+  }
+
+  function validate(token: string, expected: Readonly<{
+    taskId: string;
+    hookDefinitionHash: string;
+    buildIdentity: LifecycleBuildIdentity;
+    controller?: CodexControllerBinding;
+  }>): CodexCapabilityRecord {
+    sweep();
+    const { record } = loadActive(token);
+    return validateRecord(record, expected);
+  }
+
+  function consume(token: string, expected: Readonly<{
+    taskId: string;
+    hookDefinitionHash: string;
+    buildIdentity: LifecycleBuildIdentity;
+    controller?: CodexControllerBinding;
+  }>): CodexCapabilityRecord {
+    sweep();
+    const { file, record } = loadActive(token);
+    validateRecord(record, expected);
     const next: CodexCapabilityRecord = Object.freeze({
       ...record,
       revision: record.revision + 1,
@@ -310,13 +571,16 @@ function createCodexCapabilityStore(options: CodexCapabilityStoreOptions = {}) {
     return loadActive(token).record;
   }
 
-  return Object.freeze({ arm, attest, consume, inspect, sweep });
+  return Object.freeze({ arm, attest, consume, inspect, validate, sweep });
 }
 
 export { createCodexCapabilityStore };
 export type {
   CapabilityStatus,
+  CodexCapabilityProjection,
+  CodexCapabilityProvenanceDetail,
   CodexCapabilityRecord,
   CodexCapabilityStoreOptions,
   CodexControllerBinding
 };
+export { isCodexCapabilityProvenanceDetail };

package/lib/agent-clients/adapters/codex-lifecycle/controller-context.ts

@@ -0,0 +1,163 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { getProcessIdentityState, type ProcessIdentity } from '../../../server/process-state.ts';
+import type { CodexControllerLeaseProofV1, CodexControllerLeaseV1 } from '../../../sandbox/control/controller-registration.ts';
+import {
+  computeLifecycleBuildIdentity,
+  verifyLifecycleBuildIdentity,
+  type LifecycleBuildIdentity,
+  type LifecycleIdentityWarning
+} from './build-identity.ts';
+
+const HEX_256 = /^[a-f0-9]{64}$/u;
+
+export type CodexSandboxControllerContextV2 = Readonly<{
+  version: 2;
+  taskId: string;
+  controlGeneration: string;
+  controllerInstanceDigest: string;
+  controllerProcess: ProcessIdentity;
+  controllerLease: Readonly<{ version: 1; leaseId: string; leaseSecret: string }>;
+  issuedAt: number;
+  expiresAt: number;
+  buildIdentity: LifecycleBuildIdentity;
+  hookDefinitionHash: string;
+}>;
+
+function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+}
+
+function validProcess(value: unknown): value is ProcessIdentity {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const identity = value as Record<string, unknown>;
+  return exactKeys(identity, ['pid', 'startTime'])
+    && Number.isSafeInteger(identity.pid) && (identity.pid as number) > 0
+    && Number.isSafeInteger(identity.startTime) && (identity.startTime as number) >= 0;
+}
+
+function validBuildIdentity(value: unknown): value is LifecycleBuildIdentity {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const identity = value as Record<string, unknown>;
+  return exactKeys(identity, [
+    'internalExecutableBuildHash', 'lifecycleContractHash', 'packageVersion', 'protocolVersion'
+  ])
+    && identity.protocolVersion === 3
+    && typeof identity.packageVersion === 'string' && identity.packageVersion.length > 0
+    && typeof identity.internalExecutableBuildHash === 'string' && HEX_256.test(identity.internalExecutableBuildHash)
+    && typeof identity.lifecycleContractHash === 'string' && HEX_256.test(identity.lifecycleContractHash);
+}
+
+function validateContext(value: unknown): CodexSandboxControllerContextV2 {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
+  }
+  const context = value as Record<string, unknown>;
+  const lease = context.controllerLease as Record<string, unknown> | null;
+  if (!exactKeys(context, [
+    'buildIdentity', 'controlGeneration', 'controllerInstanceDigest', 'controllerLease',
+    'controllerProcess', 'expiresAt', 'hookDefinitionHash', 'issuedAt',
+    'taskId', 'version'
+  ])
+    || context.version !== 2
+    || typeof context.taskId !== 'string' || context.taskId.length === 0
+    || typeof context.controlGeneration !== 'string' || context.controlGeneration.length === 0
+    || typeof context.controllerInstanceDigest !== 'string' || !HEX_256.test(context.controllerInstanceDigest)
+    || !validProcess(context.controllerProcess)
+    || !lease || !exactKeys(lease, ['leaseId', 'leaseSecret', 'version'])
+    || lease.version !== 1
+    || typeof lease.leaseId !== 'string' || !HEX_256.test(lease.leaseId)
+    || typeof lease.leaseSecret !== 'string' || !HEX_256.test(lease.leaseSecret)
+    || !Number.isSafeInteger(context.issuedAt)
+    || !Number.isSafeInteger(context.expiresAt)
+    || (context.expiresAt as number) <= (context.issuedAt as number)
+    || !validBuildIdentity(context.buildIdentity)
+    || typeof context.hookDefinitionHash !== 'string' || !HEX_256.test(context.hookDefinitionHash)) {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
+  }
+  return context as unknown as CodexSandboxControllerContextV2;
+}
+
+export function contextFromControllerLease(
+  lease: CodexControllerLeaseV1,
+  input: Readonly<{ hookDefinitionHash: string }>
+): CodexSandboxControllerContextV2 {
+  return Object.freeze({
+    version: 2,
+    taskId: lease.taskId,
+    controlGeneration: lease.controlGeneration,
+    controllerInstanceDigest: lease.controllerInstanceDigest,
+    controllerProcess: lease.controllerProcess,
+    controllerLease: Object.freeze({ version: 1, leaseId: lease.leaseId, leaseSecret: lease.leaseSecret }),
+    issuedAt: lease.issuedAt,
+    expiresAt: lease.expiresAt,
+    buildIdentity: lease.buildIdentity,
+    hookDefinitionHash: input.hookDefinitionHash
+  });
+}
+
+export function writeCodexSandboxControllerContext(
+  contextPath: string,
+  context: CodexSandboxControllerContextV2
+): void {
+  validateContext(context);
+  fs.mkdirSync(path.dirname(contextPath), { recursive: true, mode: 0o700 });
+  const temporary = path.join(path.dirname(contextPath), `.${path.basename(contextPath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(context, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    fs.chmodSync(temporary, 0o600);
+    fs.renameSync(temporary, contextPath);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+}
+
+export function verifyCodexSandboxControllerContextWithWarnings(
+  contextPath: string,
+  options: Readonly<{
+    repoRoot?: string;
+    now?: number;
+    generation?: string;
+    probeProcess?: (identity: ProcessIdentity) => 'alive' | 'dead' | 'unknown';
+  }> = {}
+): Readonly<{ context: CodexSandboxControllerContextV2; warnings: readonly LifecycleIdentityWarning[] }> {
+  let stat: fs.Stats;
+  try {
+    stat = fs.lstatSync(contextPath);
+  } catch {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()
+    || (process.platform !== 'win32' && (stat.mode & 0o077) !== 0)) {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
+  }
+  let context: CodexSandboxControllerContextV2;
+  try {
+    context = validateContext(JSON.parse(fs.readFileSync(contextPath, 'utf8')));
+  } catch {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
+  }
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const generation = options.generation ?? process.env.AGENT_INFRA_CONTROL_GENERATION;
+  const state = (options.probeProcess ?? getProcessIdentityState)(context.controllerProcess);
+  if (context.controlGeneration !== generation
+    || context.expiresAt <= (options.now ?? Date.now())
+    || state !== 'alive') {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
+  }
+  const currentBuildIdentity = computeLifecycleBuildIdentity(repoRoot);
+  const identity = verifyLifecycleBuildIdentity(context.buildIdentity, currentBuildIdentity);
+  if (!identity.ok) throw new Error(`${identity.code}: ${identity.message}`);
+  return Object.freeze({ context: Object.freeze(context), warnings: identity.warnings });
+}
+
+export function controllerProofFromContext(context: CodexSandboxControllerContextV2): CodexControllerLeaseProofV1 {
+  return Object.freeze({
+    version: 1,
+    leaseId: context.controllerLease.leaseId,
+    leaseSecret: context.controllerLease.leaseSecret,
+    controllerProcess: context.controllerProcess
+  });
+}

package/lib/agent-clients/adapters/codex-lifecycle/evidence.ts

@@ -147,6 +147,16 @@ function same(left: unknown, right: unknown): boolean {
   return JSON.stringify(left) === JSON.stringify(right);
 }
 
+function sameChildCorrelation(
+  left: Extract<CodexLifecycleEvent, { type: 'hook-child' }>,
+  right: Extract<CodexLifecycleEvent, { type: 'hook-child' }>
+): boolean {
+  return left.sessionId === right.sessionId
+    && left.childThreadId === right.childThreadId
+    && left.parentThreadId === right.parentThreadId
+    && left.nativeAgent === right.nativeAgent;
+}
+
 function requiredStrings(event: CodexLifecycleEvent): boolean {
   return Object.entries(event).every(([key, value]) =>
     key === 'forkedFromId'
@@ -286,6 +296,15 @@ function reduceCodexLifecycleEvent(
   const existing = state[key];
   if (existing) {
     if (same(existing, event)) return state;
+    if (
+      existing.type === 'hook-child'
+      && event.type === 'hook-child'
+      && sameChildCorrelation(existing, event)
+      && (existing.source === 'parent-rollout') !== (event.source === 'parent-rollout')
+    ) {
+      if (existing.source !== 'parent-rollout') return state;
+      return derive(Object.freeze({ ...state, child: Object.freeze({ ...event }) }));
+    }
     return invalid(state, 'CODEX_EVIDENCE_REPLAY_CONFLICT', `conflicting '${event.type}' event`);
   }
   return derive(Object.freeze({ ...state, [key]: Object.freeze({ ...event }) }));

package/lib/agent-clients/adapters/codex-lifecycle/manifest-files.json

@@ -3,6 +3,7 @@
     "bin/internal-cli.ts",
     "lib/internal/codex-lifecycle.ts",
     "lib/internal/codex-sandbox-controller.ts",
+    "lib/internal/sandbox-control.ts",
     "lib/internal/task-orchestration.ts",
     "lib/task/codex-orchestration.ts",
     "lib/task/delegation-receipts.ts",
@@ -10,10 +11,17 @@
     "lib/agent-clients/adapters/codex-lifecycle/build-identity.ts",
     "lib/agent-clients/adapters/codex-lifecycle/capability-store.ts",
     "lib/agent-clients/adapters/codex-lifecycle/sandbox-controller.ts",
+    "lib/agent-clients/adapters/codex-lifecycle/controller-context.ts",
     "lib/agent-clients/adapters/codex-lifecycle/app-server.ts",
     "lib/agent-clients/adapters/codex-lifecycle/evidence.ts",
     "lib/agent-clients/adapters/codex-lifecycle/store.ts",
-    "lib/agent-clients/adapters/codex-lifecycle/manifest-files.json"
+    "lib/agent-clients/adapters/codex-lifecycle/manifest-files.json",
+    "lib/sandbox/control/protocol.ts",
+    "lib/sandbox/control/client.ts",
+    "lib/sandbox/control/executor.ts",
+    "lib/sandbox/control/controller-registration.ts",
+    "lib/server/process-state.ts",
+    "lib/sandbox/shell.ts"
   ],
   "contractFiles": [
     ".codex/hooks.json",