@fitlab-ai/agent-infra 0.9.6 → 0.9.7

package/lib/agent-clients/adapters/codex-lifecycle/app-server.ts

@@ -19,6 +19,12 @@ type DiscoveredHook = Readonly<{
   matcher: string | null;
   command: string;
   enabled: boolean;
+  source: string;
+  sourcePathDigest: string;
+  trustStatus: string;
+  currentHash: string;
+  isManaged: boolean;
+  pluginId: string | null;
 }>;
 
 type AppServerTransportOptions = Readonly<{
@@ -134,7 +140,11 @@ function validateCodexLifecycleHookConfig(value: unknown): void {
   if (!valid) throw new Error('CODEX_PREFLIGHT_HOOKS_INVALID: lifecycle hooks are invalid');
 }
 
-function parseCodexHooksList(value: unknown, repoRoot: string): readonly DiscoveredHook[] {
+function parseCodexHooksList(
+  value: unknown,
+  repoRoot: string,
+  expectedSource: 'direct-host' | 'isolated-user' = 'direct-host'
+): readonly DiscoveredHook[] {
   const root = object(value);
   const entries = Array.isArray(root?.data) ? root.data : [];
   const entry = entries.map(object).find((candidate) => candidate?.cwd === repoRoot);
@@ -147,13 +157,28 @@ function parseCodexHooksList(value: unknown, repoRoot: string): readonly Discove
       eventName: String(hook.eventName ?? ''),
       matcher: typeof hook.matcher === 'string' ? hook.matcher : null,
       command: String(hook.command ?? ''),
-      enabled: hook.enabled === true
+      enabled: hook.enabled === true,
+      source: String(hook.source ?? ''),
+      sourcePathDigest: typeof hook.sourcePath === 'string' && path.isAbsolute(hook.sourcePath)
+        ? crypto.createHash('sha256').update(hook.sourcePath).digest('hex')
+        : '',
+      trustStatus: String(hook.trustStatus ?? ''),
+      currentHash: String(hook.currentHash ?? ''),
+      isManaged: hook.isManaged === true,
+      pluginId: typeof hook.pluginId === 'string' ? hook.pluginId : null
     }));
   const valid = LIFECYCLE_HOOKS.every(({ event, matcher, phase }) => hooks.some((hook) =>
     hook.eventName === event.replace(/^./, (character) => character.toLowerCase())
     && hook.matcher === matcher
     && hook.command === `node "$(git rev-parse --show-toplevel)/.agents/hooks/lifecycle-delegation.js" --client codex --event ${phase}`
     && hook.enabled
+    && hook.currentHash.length > 0
+    && hook.sourcePathDigest.length === 64
+    && hook.pluginId === null
+    && (expectedSource === 'isolated-user'
+      ? hook.source === 'user' && hook.trustStatus !== 'modified'
+      : (hook.source === 'project' && hook.trustStatus === 'trusted')
+        || hook.isManaged && hook.trustStatus === 'managed')
   ));
   if (!valid) throw new Error('CODEX_PREFLIGHT_HOOKS_NOT_LOADED: lifecycle hooks are not loaded for this workspace');
   return Object.freeze(hooks);
@@ -541,13 +566,45 @@ async function preflightCodexLifecycleEvidence(
   let discoveredHooks: readonly DiscoveredHook[];
   try {
     await transport.initialize();
-    discoveredHooks = parseCodexHooksList(await transport.request('hooks/list', { cwds: [repoRoot] }), repoRoot);
+    discoveredHooks = parseCodexHooksList(
+      await transport.request('hooks/list', { cwds: [repoRoot] }),
+      repoRoot,
+      process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT ? 'isolated-user' : 'direct-host'
+    );
   } finally { transport.close(); }
+  const lifecycleHooks = LIFECYCLE_HOOKS.map(({ event, matcher, phase }) => discoveredHooks.filter((hook) =>
+    hook.eventName === event.replace(/^./, (character) => character.toLowerCase())
+    && hook.matcher === matcher
+    && hook.command === `node "$(git rev-parse --show-toplevel)/.agents/hooks/lifecycle-delegation.js" --client codex --event ${phase}`
+  ));
+  if (lifecycleHooks.some((matches) => matches.length !== 1)) {
+    throw new Error('CODEX_PREFLIGHT_HOOK_SOURCE_AMBIGUOUS: lifecycle hook source is not unique');
+  }
+  const matchedHooks = lifecycleHooks.flat();
+  const sources = new Set(matchedHooks.map((hook) => hook.isManaged ? 'managed' : hook.source));
+  const sourcePathDigests = new Set(matchedHooks.map((hook) => hook.sourcePathDigest));
+  if (sources.size !== 1 || sourcePathDigests.size !== 1) {
+    throw new Error('CODEX_PREFLIGHT_HOOK_SOURCE_AMBIGUOUS: lifecycle hooks do not share one exact source');
+  }
+  const source = [...sources][0];
+  const hookSource = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT
+    ? 'isolated-user'
+    : source === 'managed' ? 'managed' : 'project';
   return Object.freeze({
     cliVersion: match[1],
     hookDefinitionHash,
     staticReady: true,
     discoveredHooks,
+    hookProvenance: Object.freeze({
+      hookSource,
+      hookSourcePathDigest: [...sourcePathDigests][0]!,
+      hookSourceHash: crypto.createHash('sha256').update(JSON.stringify(matchedHooks.map((hook) => ({
+        eventName: hook.eventName,
+        matcher: hook.matcher,
+        command: hook.command,
+        currentHash: hook.currentHash
+      })))).digest('hex')
+    }),
     runtimeLiveness,
     diagnostics: transport.diagnostics
   });

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/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"
+  ]
+}