@fitlab-ai/agent-infra 0.9.5 → 0.9.7

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

@@ -0,0 +1,227 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const LIFECYCLE_PROTOCOL_VERSION = 3;
+
+type LifecycleBuildIdentity = Readonly<{
+  protocolVersion: 3;
+  packageVersion: string;
+  internalExecutableBuildHash: string;
+  lifecycleContractHash: string;
+}>;
+
+type LifecycleBuildIdentityOptions = Readonly<{
+  executableFiles?: readonly string[];
+  contractFiles?: readonly string[];
+}>;
+
+type LifecycleManifestFiles = Readonly<{
+  executableFiles: readonly string[];
+  contractFiles: readonly string[];
+}>;
+
+type IdentityVerification = Readonly<{
+  ok: boolean;
+  code: string | null;
+  message: string | null;
+}>;
+
+function exactText(value: unknown): value is string {
+  return typeof value === 'string' && value.trim() === value && value.length > 0;
+}
+
+function normalizeRelativePath(value: string): string {
+  return value.replaceAll('\\', '/');
+}
+
+function readLifecycleManifestFiles(packageRoot: string): LifecycleManifestFiles {
+  const file = path.join(
+    packageRoot,
+    'lib',
+    'agent-clients',
+    'adapters',
+    'codex-lifecycle',
+    'manifest-files.json'
+  );
+  const value = JSON.parse(fs.readFileSync(file, 'utf8')) as {
+    executableFiles?: unknown;
+    contractFiles?: unknown;
+  };
+  if (!Array.isArray(value.executableFiles)
+    || !Array.isArray(value.contractFiles)
+    || !value.executableFiles.every(exactText)
+    || !value.contractFiles.every(exactText)
+    || new Set(value.executableFiles).size !== value.executableFiles.length
+    || new Set(value.contractFiles).size !== value.contractFiles.length) {
+    throw new Error('Lifecycle manifest file list is invalid');
+  }
+  return Object.freeze({
+    executableFiles: Object.freeze([...value.executableFiles] as string[]),
+    contractFiles: Object.freeze([...value.contractFiles] as string[])
+  });
+}
+
+function executablePackageRoot(): string {
+  let current = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const candidate = path.join(current, 'package.json');
+    if (fs.existsSync(candidate)) {
+      const value = JSON.parse(fs.readFileSync(candidate, 'utf8')) as { name?: unknown };
+      if (value.name === '@fitlab-ai/agent-infra') return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) throw new Error('Lifecycle executable package root is unavailable');
+    current = parent;
+  }
+}
+
+function hashFiles(root: string, files: readonly string[]): string {
+  const hash = crypto.createHash('sha256');
+  for (const relative of [...new Set(files.map(normalizeRelativePath))].sort()) {
+    if (path.isAbsolute(relative) || relative.split(/[\\/]/u).includes('..')) {
+      throw new Error(`Lifecycle manifest path '${relative}' is unsafe`);
+    }
+    const file = path.join(root, relative);
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+      throw new Error(`Lifecycle manifest entry '${relative}' must be a regular file`);
+    }
+    hash.update(relative);
+    hash.update('\0');
+    hash.update(fs.readFileSync(file));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+function resolveLifecycleExecutableFiles(root: string, entries: readonly string[]): string[] {
+  const pending = [...entries];
+  const resolved = new Set<string>();
+  while (pending.length > 0) {
+    const relative = normalizeRelativePath(pending.pop()!);
+    if (resolved.has(relative)) continue;
+    resolved.add(relative);
+    if (!/\.[cm]?[jt]s$/u.test(relative)) continue;
+    const file = path.join(root, relative);
+    const source = fs.readFileSync(file, 'utf8');
+    const imports = source.matchAll(/(?:\bfrom\s*|\bimport\s*(?:\(\s*)?)["'](\.[^"']+)["']/gu);
+    for (const match of imports) {
+      const requested = match[1]!;
+      const base = path.resolve(path.dirname(file), requested);
+      const candidates = [
+        base,
+        `${base}.ts`, `${base}.js`,
+        path.join(base, 'index.ts'), path.join(base, 'index.js')
+      ];
+      const dependency = candidates.find((candidate) => fs.existsSync(candidate) && fs.lstatSync(candidate).isFile());
+      if (!dependency) throw new Error(`Lifecycle executable dependency '${requested}' from '${relative}' is unavailable`);
+      const dependencyRelative = path.relative(root, dependency);
+      if (dependencyRelative.startsWith('..') || path.isAbsolute(dependencyRelative)) {
+        throw new Error(`Lifecycle executable dependency '${requested}' escapes the package root`);
+      }
+      pending.push(normalizeRelativePath(dependencyRelative));
+    }
+  }
+  return [...resolved].sort();
+}
+
+function computeLifecycleBuildIdentity(
+  repoRoot: string,
+  options: LifecycleBuildIdentityOptions = {}
+): LifecycleBuildIdentity {
+  const packageRoot = executablePackageRoot();
+  const executableRoot = options.executableFiles ? repoRoot : packageRoot;
+  const defaults = readLifecycleManifestFiles(packageRoot);
+  const packageJson = JSON.parse(fs.readFileSync(path.join(executableRoot, 'package.json'), 'utf8')) as {
+    version?: unknown;
+  };
+  if (!exactText(packageJson.version)) throw new Error('Lifecycle package version is invalid');
+  let internalExecutableBuildHash: string;
+  if (options.executableFiles) {
+    internalExecutableBuildHash = hashFiles(repoRoot, options.executableFiles);
+  } else {
+    const manifestFile = path.join(executableRoot, 'dist', 'lifecycle-build-manifest.json');
+    if (fs.existsSync(manifestFile)) {
+      const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8')) as {
+        protocolVersion?: unknown;
+        packageVersion?: unknown;
+        sourceInputHash?: unknown;
+        internalExecutableBuildHash?: unknown;
+      };
+      if (manifest.protocolVersion !== LIFECYCLE_PROTOCOL_VERSION
+        || manifest.packageVersion !== packageJson.version
+        || !exactText(manifest.sourceInputHash)
+        || !exactText(manifest.internalExecutableBuildHash)) {
+        throw new Error('Lifecycle executable build manifest is stale or invalid');
+      }
+      if (fileURLToPath(import.meta.url).split(path.sep).includes('dist')) {
+        const compiledFiles = defaults.executableFiles.map((file) =>
+          file.endsWith('.ts') ? path.join('dist', file.replace(/\.ts$/u, '.js')) : file
+        );
+        if (hashFiles(executableRoot, resolveLifecycleExecutableFiles(executableRoot, compiledFiles)) !== manifest.internalExecutableBuildHash) {
+          throw new Error('Lifecycle compiled executable build does not match its manifest');
+        }
+      } else if (hashFiles(executableRoot, resolveLifecycleExecutableFiles(executableRoot, defaults.executableFiles)) !== manifest.sourceInputHash) {
+        throw new Error('Lifecycle executable build manifest is stale or invalid');
+      }
+      internalExecutableBuildHash = manifest.internalExecutableBuildHash;
+    } else internalExecutableBuildHash = hashFiles(
+      executableRoot,
+      resolveLifecycleExecutableFiles(executableRoot, defaults.executableFiles)
+    );
+  }
+  return Object.freeze({
+    protocolVersion: LIFECYCLE_PROTOCOL_VERSION,
+    packageVersion: packageJson.version,
+    internalExecutableBuildHash,
+    lifecycleContractHash: hashFiles(
+      repoRoot,
+      options.contractFiles ?? defaults.contractFiles
+    )
+  });
+}
+
+function verifyLifecycleBuildIdentity(
+  expected: LifecycleBuildIdentity,
+  actual: LifecycleBuildIdentity
+): IdentityVerification {
+  if (actual.protocolVersion !== expected.protocolVersion) {
+    return {
+      ok: false,
+      code: 'CODEX_LIFECYCLE_PROTOCOL_MISMATCH',
+      message: 'Codex lifecycle protocol version does not match'
+    };
+  }
+  if (actual.packageVersion !== expected.packageVersion
+    || actual.internalExecutableBuildHash !== expected.internalExecutableBuildHash) {
+    return {
+      ok: false,
+      code: 'CODEX_LIFECYCLE_BUILD_MISMATCH',
+      message: 'Codex lifecycle executable build identity does not match'
+    };
+  }
+  if (actual.lifecycleContractHash !== expected.lifecycleContractHash) {
+    return {
+      ok: false,
+      code: 'CODEX_LIFECYCLE_CONTRACT_MISMATCH',
+      message: 'Codex lifecycle contract identity does not match'
+    };
+  }
+  return { ok: true, code: null, message: null };
+}
+
+export {
+  LIFECYCLE_PROTOCOL_VERSION,
+  computeLifecycleBuildIdentity,
+  readLifecycleManifestFiles,
+  resolveLifecycleExecutableFiles,
+  verifyLifecycleBuildIdentity
+};
+export type {
+  IdentityVerification,
+  LifecycleBuildIdentity,
+  LifecycleManifestFiles,
+  LifecycleBuildIdentityOptions
+};

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

@@ -0,0 +1,321 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { verifyLifecycleBuildIdentity } from './build-identity.ts';
+import type { LifecycleBuildIdentity } from './build-identity.ts';
+
+type CapabilityStatus = 'armed' | 'attested' | 'consumed' | 'expired';
+type CodexControllerBinding = Readonly<{
+  instanceDigest: string;
+  controlGeneration: string;
+}>;
+type CodexCapabilityRecord = Readonly<{
+  schemaVersion: 1;
+  revision: number;
+  tokenDigest: string;
+  taskId: string;
+  status: CapabilityStatus;
+  buildIdentity: LifecycleBuildIdentity;
+  controller: CodexControllerBinding | null;
+  sessionId: string | null;
+  turnId: string | null;
+  toolUseId: string | null;
+  hookDefinitionHash: string | null;
+  armedAt: number;
+  expiresAt: number;
+  attestedAt: number | null;
+  consumedAt: number | null;
+}>;
+
+type CodexCapabilityStoreOptions = Readonly<{
+  root?: string;
+  now?: () => number;
+  token?: () => string;
+  ttlMs?: number;
+  tombstoneMs?: number;
+  maxRecords?: number;
+  beforeCompareAndSwap?: (input: Readonly<{ path: string; expectedRevision: number }>) => void;
+}>;
+
+const DEFAULT_TTL_MS = 30_000;
+const DEFAULT_TOMBSTONE_MS = 86_400_000;
+const DEFAULT_MAX_RECORDS = 128;
+const LOCK_RETRY_MS = 10;
+const LOCK_TIMEOUT_MS = 1_000;
+const LOCK_STALE_MS = 30_000;
+
+function digest(value: string): string {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function capabilityError(code: string, message: string): Error {
+  const error = new Error(`${code}: ${message}`);
+  error.name = code;
+  return error;
+}
+
+function sameController(
+  left: CodexControllerBinding | null,
+  right: CodexControllerBinding | null
+): boolean {
+  return left?.instanceDigest === right?.instanceDigest
+    && left?.controlGeneration === right?.controlGeneration;
+}
+
+function createCodexCapabilityStore(options: CodexCapabilityStoreOptions = {}) {
+  const root = options.root
+    ?? path.join(process.cwd(), '.agents', 'workspace', '.runtime', 'codex-capabilities');
+  const now = options.now ?? Date.now;
+  const createToken = options.token ?? (() => crypto.randomBytes(32).toString('base64url'));
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+  const tombstoneMs = options.tombstoneMs ?? DEFAULT_TOMBSTONE_MS;
+  const maxRecords = options.maxRecords ?? DEFAULT_MAX_RECORDS;
+  fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+  fs.chmodSync(root, 0o700);
+
+  function fileFor(token: string): string {
+    return path.join(root, `${digest(token)}.json`);
+  }
+
+  function read(file: string): CodexCapabilityRecord {
+    const value = JSON.parse(fs.readFileSync(file, 'utf8')) as CodexCapabilityRecord;
+    if (value.schemaVersion !== 1 || !Number.isSafeInteger(value.revision) || value.revision < 1) {
+      throw capabilityError('CODEX_CAPABILITY_STATE_INVALID', 'capability record schema is invalid');
+    }
+    return value;
+  }
+
+  function withWriteLock<T>(operation: () => T): T {
+    const lock = path.join(root, '.write.lock');
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    let descriptor: number | null = null;
+    while (descriptor === null) {
+      try {
+        descriptor = fs.openSync(lock, 'wx', 0o600);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        try {
+          if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS) {
+            fs.unlinkSync(lock);
+            continue;
+          }
+        } catch (lockError) {
+          if ((lockError as NodeJS.ErrnoException).code === 'ENOENT') continue;
+          throw lockError;
+        }
+        if (Date.now() >= deadline) {
+          throw capabilityError('CODEX_CAPABILITY_STORE_BUSY', 'capability store is busy');
+        }
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MS);
+      }
+    }
+    try {
+      return operation();
+    } finally {
+      fs.closeSync(descriptor);
+      fs.unlinkSync(lock);
+    }
+  }
+
+  function write(file: string, value: CodexCapabilityRecord, expectedRevision: number): void {
+    const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+      encoding: 'utf8',
+      flag: 'wx',
+      mode: 0o600
+    });
+    try {
+      withWriteLock(() => {
+        options.beforeCompareAndSwap?.({ path: file, expectedRevision });
+        const actualRevision = fs.existsSync(file) ? read(file).revision : 0;
+        if (actualRevision !== expectedRevision) {
+          throw capabilityError(
+            'CODEX_CAPABILITY_REVISION_CONFLICT',
+            `capability revision changed from ${expectedRevision} to ${actualRevision}`
+          );
+        }
+        fs.renameSync(temporary, file);
+        fs.chmodSync(file, 0o600);
+      });
+    } finally {
+      if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+    }
+  }
+
+  function files(): string[] {
+    return fs.readdirSync(root)
+      .filter((name) => /^[a-f0-9]{64}\.json$/u.test(name))
+      .map((name) => path.join(root, name));
+  }
+
+  function expire(record: CodexCapabilityRecord, file: string, timestamp: number): CodexCapabilityRecord {
+    if ((record.status === 'armed' || record.status === 'attested') && timestamp > record.expiresAt) {
+      const expired = Object.freeze({
+        ...record,
+        revision: record.revision + 1,
+        status: 'expired' as const
+      });
+      write(file, expired, record.revision);
+      return expired;
+    }
+    return record;
+  }
+
+  function sweep(): void {
+    const timestamp = now();
+    const records = files().map((file) => ({ file, record: expire(read(file), file, timestamp) }));
+    for (const entry of records) {
+      const terminalAt = entry.record.consumedAt ?? entry.record.expiresAt;
+      if (['consumed', 'expired'].includes(entry.record.status)
+        && timestamp - terminalAt > tombstoneMs) {
+        fs.unlinkSync(entry.file);
+      }
+    }
+    const remaining = files().map((file) => ({ file, record: read(file) }));
+    if (remaining.length <= maxRecords) return;
+    const removable = remaining
+      .filter(({ record }) => ['consumed', 'expired'].includes(record.status))
+      .sort((left, right) =>
+        (left.record.consumedAt ?? left.record.expiresAt)
+        - (right.record.consumedAt ?? right.record.expiresAt));
+    while (files().length > maxRecords && removable.length > 0) {
+      fs.unlinkSync(removable.shift()!.file);
+    }
+    if (files().length > maxRecords) {
+      throw capabilityError('CODEX_CAPABILITY_CAPACITY_EXCEEDED', 'capability store has too many active records');
+    }
+  }
+
+  function arm(input: Readonly<{
+    taskId: string;
+    buildIdentity: LifecycleBuildIdentity;
+    controller?: CodexControllerBinding;
+  }>): CodexCapabilityRecord & Readonly<{ token: string; path: string; marker: string }> {
+    sweep();
+    const token = createToken();
+    const file = fileFor(token);
+    if (fs.existsSync(file)) throw capabilityError('CODEX_CAPABILITY_TOKEN_COLLISION', 'capability token already exists');
+    const timestamp = now();
+    const record: CodexCapabilityRecord = Object.freeze({
+      schemaVersion: 1,
+      revision: 1,
+      tokenDigest: digest(token),
+      taskId: input.taskId,
+      status: 'armed',
+      buildIdentity: input.buildIdentity,
+      controller: input.controller ?? null,
+      sessionId: null,
+      turnId: null,
+      toolUseId: null,
+      hookDefinitionHash: null,
+      armedAt: timestamp,
+      expiresAt: timestamp + ttlMs,
+      attestedAt: null,
+      consumedAt: null
+    });
+    write(file, record, 0);
+    return Object.freeze({
+      ...record,
+      token,
+      path: file,
+      marker: `agent-infra-codex-capability:${token}`
+    });
+  }
+
+  function loadActive(token: string): Readonly<{ file: string; record: CodexCapabilityRecord }> {
+    const file = fileFor(token);
+    if (!fs.existsSync(file)) {
+      throw capabilityError('CODEX_CAPABILITY_MISSING', 'capability token was not found');
+    }
+    const record = expire(read(file), file, now());
+    if (record.status === 'expired') {
+      throw capabilityError('CODEX_CAPABILITY_EXPIRED', 'capability token expired');
+    }
+    return { file, record };
+  }
+
+  function attest(input: Readonly<{
+    token: string;
+    sessionId: string;
+    turnId: string;
+    toolUseId: string;
+    hookDefinitionHash: string;
+    buildIdentity: LifecycleBuildIdentity;
+    controller?: CodexControllerBinding;
+  }>): CodexCapabilityRecord {
+    const { file, record } = loadActive(input.token);
+    if (record.status !== 'armed') {
+      throw capabilityError(
+        record.status === 'consumed' ? 'CODEX_CAPABILITY_REPLAY' : 'CODEX_CAPABILITY_STATE_INVALID',
+        `capability is ${record.status}, expected armed`
+      );
+    }
+    const identity = verifyLifecycleBuildIdentity(record.buildIdentity, input.buildIdentity);
+    if (!identity.ok || !sameController(record.controller, input.controller ?? null)) {
+      throw capabilityError('CODEX_CAPABILITY_PROVENANCE_MISMATCH', 'capability build or controller identity does not match');
+    }
+    if (![input.sessionId, input.turnId, input.toolUseId, input.hookDefinitionHash]
+      .every((value) => value.trim().length > 0)) {
+      throw capabilityError('CODEX_CAPABILITY_IDENTITY_INVALID', 'hook identity is incomplete');
+    }
+    const timestamp = now();
+    const next: CodexCapabilityRecord = Object.freeze({
+      ...record,
+      revision: record.revision + 1,
+      status: 'attested',
+      sessionId: input.sessionId,
+      turnId: input.turnId,
+      toolUseId: input.toolUseId,
+      hookDefinitionHash: input.hookDefinitionHash,
+      attestedAt: timestamp
+    });
+    write(file, next, record.revision);
+    return next;
+  }
+
+  function consume(token: string, 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);
+    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');
+    }
+    const next: CodexCapabilityRecord = Object.freeze({
+      ...record,
+      revision: record.revision + 1,
+      status: 'consumed',
+      consumedAt: now()
+    });
+    write(file, next, record.revision);
+    return next;
+  }
+
+  function inspect(token: string): CodexCapabilityRecord {
+    return loadActive(token).record;
+  }
+
+  return Object.freeze({ arm, attest, consume, inspect, sweep });
+}
+
+export { createCodexCapabilityStore };
+export type {
+  CapabilityStatus,
+  CodexCapabilityRecord,
+  CodexCapabilityStoreOptions,
+  CodexControllerBinding
+};

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

@@ -21,7 +21,9 @@ type CodexLifecycleEvent =
       sessionId: string;
       turnId: string;
       childThreadId: string;
+      parentThreadId: string;
       nativeAgent: string;
+      source?: 'hook' | 'parent-rollout';
     }>
   | Readonly<{
       type: 'app-thread';
@@ -29,6 +31,7 @@ type CodexLifecycleEvent =
       parentThreadId: string;
       forkedFromId: string | null;
       sourceParentThreadId: string;
+      nativeAgent: string;
     }>
   | Readonly<{
       type: 'app-settings';
@@ -56,6 +59,7 @@ type CodexLifecycleEvent =
       turnId: string;
       childThreadId: string;
       nativeAgent: string;
+      source?: 'hook' | 'parent-rollout';
     }>;
 
 type CodexStartEvidence = Readonly<{
@@ -79,7 +83,7 @@ type CodexStopEvidence = Readonly<{
   childThreadId: string;
   turnId: string;
   terminalStatus: 'completed';
-  hookStopObserved: true;
+  hookStopObserved: boolean;
 }>;
 
 type CodexLifecycleStatus =
@@ -153,20 +157,32 @@ function requiredStrings(event: CodexLifecycleEvent): boolean {
 function derive(state: CodexLifecycleState): CodexLifecycleState {
   const { spawn, child, thread, settings, reroute, terminal, stop } = state;
   if (spawn && child && (
-    spawn.sessionId !== child.sessionId
+    spawn.sessionId !== child.parentThreadId
     || spawn.nativeAgent !== child.nativeAgent
   )) {
     return invalid(state, 'CODEX_EVIDENCE_IDENTITY_MISMATCH', 'hook spawn and child identity do not match');
   }
+  if (child && child.sessionId !== child.parentThreadId) {
+    return invalid(state, 'CODEX_EVIDENCE_IDENTITY_MISMATCH', 'child event session does not match the parent thread');
+  }
   if (child && thread && child.childThreadId !== thread.childThreadId) {
     return invalid(state, 'CODEX_EVIDENCE_IDENTITY_MISMATCH', 'hook and App Server child identity do not match');
   }
+  if (child && thread && child.nativeAgent !== thread.nativeAgent) {
+    return invalid(state, 'CODEX_EVIDENCE_IDENTITY_MISMATCH', 'hook and App Server agent roles do not match');
+  }
+  if (child && thread && child.parentThreadId !== thread.parentThreadId) {
+    return invalid(state, 'CODEX_EVIDENCE_PARENT_MISMATCH', 'hook and App Server parent identity do not match');
+  }
   if (spawn && thread && (
     thread.parentThreadId !== spawn.sessionId
     || thread.sourceParentThreadId !== spawn.sessionId
   )) {
     return invalid(state, 'CODEX_EVIDENCE_PARENT_MISMATCH', 'App Server parent identity does not match the spawning session');
   }
+  if (spawn && thread && spawn.nativeAgent !== thread.nativeAgent) {
+    return invalid(state, 'CODEX_EVIDENCE_IDENTITY_MISMATCH', 'spawn and App Server agent roles do not match');
+  }
   if (thread?.forkedFromId !== null && thread?.forkedFromId !== undefined) {
     return invalid(state, 'CODEX_EVIDENCE_FORK_FORBIDDEN', 'forked child threads are not fresh lifecycle evidence');
   }
@@ -233,7 +249,7 @@ function derive(state: CodexLifecycleState): CodexLifecycleState {
       childThreadId: startEvidence.childThreadId,
       turnId: terminal.turnId,
       terminalStatus: 'completed',
-      hookStopObserved: true
+      hookStopObserved: stop.source !== 'parent-rollout'
     });
   }
   const status: CodexLifecycleStatus = stopEvidence

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

@@ -0,0 +1,26 @@
+{
+  "executableFiles": [
+    "bin/internal-cli.ts",
+    "lib/internal/codex-lifecycle.ts",
+    "lib/internal/codex-sandbox-controller.ts",
+    "lib/internal/task-orchestration.ts",
+    "lib/task/codex-orchestration.ts",
+    "lib/task/delegation-receipts.ts",
+    "lib/task/orchestration.ts",
+    "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/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"
+  ],
+  "contractFiles": [
+    ".codex/hooks.json",
+    ".codex/agents/agent-infra-lifecycle-executor.toml",
+    ".codex/agents/agent-infra-lifecycle-reviewer.toml",
+    ".agents/hooks/lifecycle-delegation.js",
+    ".agents/skills/run-task/SKILL.md",
+    ".agents/rules/lifecycle-orchestration.md"
+  ]
+}