@fitlab-ai/agent-infra 0.9.7 → 0.9.9

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

@@ -7,6 +7,7 @@ import semver from 'semver';
 
 import type { ChildProcessWithoutNullStreams } from 'node:child_process';
 import type { CodexLifecycleEvent } from './evidence.ts';
+import { resolveAgentRuntimeStoreRoot } from '../../../runtime/agent-runtime.ts';
 
 type JsonObject = Record<string, unknown>;
 type ThreadResolution = Readonly<{
@@ -35,6 +36,10 @@ type AppServerTransportOptions = Readonly<{
   timeoutMs?: number;
   rolloutReadAttempts?: number;
   rolloutRetryMs?: number;
+  threadReadAttempts?: number;
+  threadRetryMs?: number;
+  terminalReadAttempts?: number;
+  terminalRetryMs?: number;
 }>;
 
 type CodexRuntimeIdentity = Readonly<{
@@ -51,6 +56,10 @@ const LIFECYCLE_HOOKS = Object.freeze([
 ]);
 const DEFAULT_ROLLOUT_READ_ATTEMPTS = 81;
 const DEFAULT_ROLLOUT_RETRY_MS = 100;
+const DEFAULT_THREAD_READ_ATTEMPTS = 21;
+const DEFAULT_THREAD_RETRY_MS = 100;
+const DEFAULT_TERMINAL_READ_ATTEMPTS = 21;
+const DEFAULT_TERMINAL_RETRY_MS = 100;
 
 function object(value: unknown): JsonObject | null {
   return value && typeof value === 'object' && !Array.isArray(value)
@@ -66,6 +75,7 @@ function resolveCodexSpawnedChild(
   transcriptPath: string,
   expected: Readonly<{
     sessionId: string;
+    turnId: string;
     toolUseId: string;
     nativeAgent: string;
     taskName: string;
@@ -110,15 +120,19 @@ function resolveCodexSpawnedChild(
   ) throw new Error('Codex parent rollout spawn identity does not match the hook event');
   const activities = records.filter((record) => {
     const payload = object(record?.payload);
+    const item = object(payload?.item);
     return record?.type === 'event_msg'
-      && payload?.type === 'sub_agent_activity'
-      && payload.event_id === expected.toolUseId
-      && payload.kind === 'started'
-      && payload.agent_path === `/root/${expected.taskName}`
-      && nonEmpty(payload.agent_thread_id);
+      && payload?.type === 'item_completed'
+      && payload.thread_id === expected.sessionId
+      && payload.turn_id === expected.turnId
+      && item?.type === 'SubAgentActivity'
+      && item.id === expected.toolUseId
+      && item.kind === 'started'
+      && item.agent_path === `/root/${expected.taskName}`
+      && nonEmpty(item.agent_thread_id);
   });
   if (activities.length !== 1) throw new Error('Codex parent rollout child activity was not found uniquely');
-  return nonEmpty(object(activities[0]?.payload)?.agent_thread_id)!;
+  return nonEmpty(object(object(activities[0]?.payload)?.item)?.agent_thread_id)!;
 }
 
 function validateCodexLifecycleHookConfig(value: unknown): void {
@@ -132,7 +146,7 @@ function validateCodexLifecycleHookConfig(value: unknown): void {
       return entry.hooks.some((hookValue) => {
         const hook = object(hookValue);
         return hook?.type === 'command'
-          && hook.timeout === 15
+          && hook.timeout === 30
           && hook.command === `node "$(git rev-parse --show-toplevel)/.agents/hooks/lifecycle-delegation.js" --client codex --event ${phase}`;
       });
     });
@@ -477,18 +491,30 @@ async function resolveCodexThread(
     const readResult = object(await transport.request('thread/read', { threadId: childThreadId, includeTurns: false }));
     const readThread = object(readResult?.thread);
     if (nonEmpty(readThread?.id) !== childThreadId) throw new Error('Codex App Server returned the wrong child thread');
-    let resolution: ThreadResolution;
+    let rolloutRecords: readonly unknown[];
     try {
-      const rolloutRecords = await resolveCodexRolloutRecords(
+      rolloutRecords = await resolveCodexRolloutRecords(
         readResult,
         childThreadId,
         options.rolloutReadAttempts ?? DEFAULT_ROLLOUT_READ_ATTEMPTS,
         options.rolloutRetryMs ?? DEFAULT_ROLLOUT_RETRY_MS
       );
-      resolution = parseCodexThreadResolution(readResult, rolloutRecords);
     } catch {
       throw new Error('Codex App Server rollout metadata is unavailable');
     }
+    let resolution = parseCodexThreadResolution(readResult, rolloutRecords);
+    const threadReadAttempts = options.threadReadAttempts ?? DEFAULT_THREAD_READ_ATTEMPTS;
+    for (let attempt = 1; resolution.thread.forkedFromId !== null && attempt < threadReadAttempts; attempt += 1) {
+      await new Promise((resolve) => setTimeout(resolve, options.threadRetryMs ?? DEFAULT_THREAD_RETRY_MS));
+      const refreshed = object(await transport.request('thread/read', { threadId: childThreadId, includeTurns: false }));
+      if (nonEmpty(object(refreshed?.thread)?.id) !== childThreadId) {
+        throw new Error('Codex App Server returned the wrong child thread');
+      }
+      resolution = parseCodexThreadResolution(refreshed, rolloutRecords);
+    }
+    if (resolution.thread.forkedFromId !== null) {
+      throw new Error('Codex App Server fresh thread metadata is unavailable');
+    }
     const reroutes = transport.notifications
       .filter((entry) => entry.method === 'model/rerouted')
       .map((entry) => parseCodexModelReroute(entry.params))
@@ -506,20 +532,37 @@ async function resolveCodexThread(
 
 async function resolveCodexTerminal(
   childThreadId: string,
-  options: AppServerTransportOptions = {}
+  expectedTurnIdOrOptions: string | AppServerTransportOptions = {},
+  terminalOptions: AppServerTransportOptions = {}
 ): Promise<Extract<CodexLifecycleEvent, { type: 'app-terminal' }>> {
+  const expectedTurnId = typeof expectedTurnIdOrOptions === 'string' ? expectedTurnIdOrOptions : null;
+  const options = typeof expectedTurnIdOrOptions === 'string' ? terminalOptions : expectedTurnIdOrOptions;
   const transport = new CodexAppServerTransport(options);
   transport.start();
   try {
     await transport.initialize();
-    const result = object(await transport.request('thread/read', { threadId: childThreadId, includeTurns: true }));
-    const thread = object(result?.thread);
-    if (nonEmpty(thread?.id) !== childThreadId) throw new Error('Codex App Server returned the wrong child thread');
-    const turns = Array.isArray(thread?.turns) ? thread.turns : [];
-    const turn = turns.at(-1);
-    const turnValue = object(turn);
-    if (!turnValue || turnValue.status === 'inProgress') throw new Error('CODEX_TURN_NOT_TERMINAL');
-    return parseCodexTurnCompleted({ threadId: childThreadId, turn });
+    const attempts = expectedTurnId ? options.terminalReadAttempts ?? DEFAULT_TERMINAL_READ_ATTEMPTS : 1;
+    let abnormal: Extract<CodexLifecycleEvent, { type: 'app-terminal' }> | null = null;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      const result = object(await transport.request('thread/read', { threadId: childThreadId, includeTurns: true }));
+      const thread = object(result?.thread);
+      if (nonEmpty(thread?.id) !== childThreadId) throw new Error('Codex App Server returned the wrong child thread');
+      const turns = Array.isArray(thread?.turns) ? thread.turns : [];
+      const turn = expectedTurnId
+        ? turns.find((candidate) => object(candidate)?.id === expectedTurnId)
+        : turns.at(-1);
+      const turnValue = object(turn);
+      if (turnValue && turnValue.status !== 'inProgress') {
+        const terminal = parseCodexTurnCompleted({ threadId: childThreadId, turn });
+        if (terminal.status === 'completed') return terminal;
+        abnormal = terminal;
+      }
+      if (attempt + 1 < attempts) {
+        await new Promise((resolve) => setTimeout(resolve, options.terminalRetryMs ?? DEFAULT_TERMINAL_RETRY_MS));
+      }
+    }
+    if (abnormal) return abnormal;
+    throw new Error('CODEX_TURN_NOT_TERMINAL');
   } finally {
     transport.close();
   }
@@ -558,7 +601,7 @@ async function preflightCodexLifecycleEvidence(
   }
 
   const hookDefinitionHash = crypto.createHash('sha256').update(hooksRaw).digest('hex');
-  const runtimeRoot = path.join(repoRoot, '.agents', 'workspace', '.runtime', 'codex-lifecycle');
+  const runtimeRoot = resolveAgentRuntimeStoreRoot({ repoRoot, store: 'lifecycle' });
   const runtimeLiveness = hasCodexRuntimeLiveness(runtimeRoot, hookDefinitionHash, runtimeIdentity);
 
   const transport = new CodexAppServerTransport();

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<{
@@ -32,6 +34,14 @@ 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('\\', '/');
 }
@@ -215,6 +225,8 @@ function verifyLifecycleBuildIdentity(
 export {
   LIFECYCLE_PROTOCOL_VERSION,
   computeLifecycleBuildIdentity,
+  isCanonicalLifecyclePackageVersion,
+  isLifecycleProtocolVersion,
   readLifecycleManifestFiles,
   resolveLifecycleExecutableFiles,
   verifyLifecycleBuildIdentity

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

@@ -2,14 +2,50 @@ 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';
 
 type CapabilityStatus = 'armed' | 'attested' | 'consumed' | 'expired';
 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;
@@ -44,28 +80,227 @@ 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 = {}) {
   const root = options.root
-    ?? path.join(process.cwd(), '.agents', 'workspace', '.runtime', 'codex-capabilities');
+    ?? resolveAgentRuntimeStoreRoot({ store: 'capabilities' });
   const now = options.now ?? Date.now;
   const createToken = options.token ?? (() => crypto.randomBytes(32).toString('base64url'));
   const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
@@ -274,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,
@@ -309,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 };