@fitlab-ai/agent-infra 0.9.6 → 0.9.8

package/dist/lib/task/verification-engine.js

@@ -151,7 +151,7 @@ function checkOrchestrationState({ taskDir }) {
     if (isFailClosedLegacyPause(run)) {
         return passResult('orchestration-state', 'Legacy orchestration run is safely paused');
     }
-    if (run.schemaVersion !== 2 || !['paused', 'completed'].includes(run.status)) {
+    if (![2, 3].includes(run.schemaVersion) || !['paused', 'completed'].includes(run.status)) {
         return failResult('orchestration-state', `Expected paused or completed run, received '${run.status}'`);
     }
     if (run.status === 'paused' && (!run.pause?.code || !run.pause?.message)) {
@@ -261,7 +261,22 @@ function checkOrchestrationEvidence({ taskDir }) {
             && guards?.commitAuthorizationUnused === true
             && guards?.completionEvidenceAbsent === true
             && guards?.commitIntentAbsent === true;
-        if (!validModelRecovery && !validCapabilityRecovery) {
+        const validClaudeCodeRecovery = recovery.code === 'CLIENT_CAPABILITY_ENABLED_NO_MIGRATION'
+            && recovery.previousSchemaVersion === 3
+            && recovery.previousStatus === 'paused'
+            && recovery.previousPause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
+            && recovery.client === 'claude-code'
+            && recovery.resultingStatus === 'running'
+            && exactText(recovery.recoveredAt)
+            && guards?.stepCount === 0
+            && guards?.nextStage === null
+            && guards?.baselineEmpty === true
+            && guards?.receiptCount === 0
+            && guards?.pendingDelegation === false
+            && guards?.commitAuthorizationUnused === true
+            && guards?.completionEvidenceAbsent === true
+            && guards?.commitIntentAbsent === true;
+        if (!validModelRecovery && !validCapabilityRecovery && !validClaudeCodeRecovery) {
             return failResult('orchestration-evidence', 'Run recovery history contains invalid provenance');
         }
     }
@@ -292,26 +307,37 @@ function checkOrchestrationEvidence({ taskDir }) {
         }
         const activated = ['activated', 'stage-completed', 'sealed', 'consumed'].includes(receipt.status);
         if (activated) {
-            if (!exactText(receipt.actualModel)) {
-                return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual model`);
+            const isClaudeCode = receipt.client === 'claude-code';
+            if (!isClaudeCode) {
+                if (!exactText(receipt.actualModel)) {
+                    return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual model`);
+                }
+                if (!exactText(receipt.actualReasoningEffort)) {
+                    return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual reasoning effort`);
+                }
             }
-            if (!exactText(receipt.actualReasoningEffort)) {
-                return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual reasoning effort`);
+            // parentId/childId 校验对所有 client 保持统一（不新增分支）；spawnMode 检查按 client 判断
+            if (!exactText(receipt.parentId) || !exactText(receipt.childId) || receipt.parentId === receipt.childId) {
+                return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid delegation identity`);
             }
-            if (!exactText(receipt.parentId) || !exactText(receipt.childId) || receipt.parentId === receipt.childId || receipt.spawnMode !== 'fresh') {
+            if (!isClaudeCode && receipt.spawnMode !== 'fresh') {
                 return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid fresh delegation identity`);
             }
-            if (receipt.actualModel !== receipt.requestedModel && !exactText(receipt.modelFallbackReason)) {
-                return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' model fallback is not justified`);
+            if (receipt.actualModel != null && receipt.actualModel !== receipt.requestedModel) {
+                if (!isClaudeCode && !exactText(receipt.modelFallbackReason)) {
+                    return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' model fallback is not justified`);
+                }
             }
-            if (receipt.actualModel === receipt.requestedModel && receipt.modelFallbackReason !== null) {
+            if ((receipt.actualModel == null || receipt.actualModel === receipt.requestedModel)
+                && receipt.modelFallbackReason !== null) {
                 return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated model fallback reason`);
             }
-            if (receipt.actualReasoningEffort !== receipt.requestedReasoningEffort
-                && !exactText(receipt.reasoningEffortFallbackReason)) {
-                return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' reasoning-effort fallback is not justified`);
+            if (receipt.actualReasoningEffort != null && receipt.actualReasoningEffort !== receipt.requestedReasoningEffort) {
+                if (!isClaudeCode && !exactText(receipt.reasoningEffortFallbackReason)) {
+                    return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' reasoning-effort fallback is not justified`);
+                }
             }
-            if (receipt.actualReasoningEffort === receipt.requestedReasoningEffort
+            if ((receipt.actualReasoningEffort == null || receipt.actualReasoningEffort === receipt.requestedReasoningEffort)
                 && receipt.reasoningEffortFallbackReason !== null) {
                 return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated reasoning-effort fallback reason`);
             }
@@ -774,7 +800,7 @@ function checkReviewLedger({ taskDir, config }) {
         return passResult("review-ledger", "Disagreement ledger has no entries");
     }
     const stageScope = Array.isArray(config.stage_scope) ? config.stage_scope : null;
-    const maxRounds = Number(resolveReviewSetting(config, "max_handshake_rounds", DEFAULT_MAX_HANDSHAKE_ROUNDS));
+    const maxRounds = Number(resolveReviewSetting(config, "maxHandshakeRounds", DEFAULT_MAX_HANDSHAKE_ROUNDS));
     const problems = [];
     let inScopeCount = 0;
     for (const cells of rows) {
@@ -916,7 +942,13 @@ function checkPostReviewCommit({ taskDir, config }) {
                 return blockedResult("post-review-commit", relation.message, relation.code);
             }
             if (relation.status === "strict") {
-                return failResult("post-review-commit", "Merged PR evidence did not establish squash merge equivalence", "PR_MERGE_IDENTITY_INVALID");
+                return resolvePostReviewIdentityFailure(task.content, {
+                    code: "PR_MERGE_IDENTITY_INVALID",
+                    message: "Merged PR evidence did not establish squash merge equivalence"
+                });
+            }
+            if (relation.code === "PR_MERGE_IDENTITY_INVALID") {
+                return resolvePostReviewIdentityFailure(task.content, relation);
             }
             return failResult("post-review-commit", relation.message, relation.code);
         }
@@ -981,21 +1013,47 @@ function checkPostReviewCommit({ taskDir, config }) {
     }
     const exemption = resolvePostReviewExemption(task.content);
     if (!exemption.ok)
-        return failResult("post-review-commit", exemption.message);
-    if (exemption.exempt) {
-        return passResult("post-review-commit", `${commits.length} post-review commit(s) covered by a human-decided exemption`);
+        return failResult("post-review-commit", exemption.message, exemption.code);
+    if (exemption.exemptions.length > 0) {
+        return passResult("post-review-commit", `${commits.length} post-review commit(s) covered by a human-decided exemption: ${formatPostReviewExemptions(exemption.exemptions)}`);
     }
     return failResult("post-review-commit", `${commits.length} commit(s) to code/rule paths after reviewed commit ${sha.slice(0, 8)}; re-run review-code or record a human-decided exemption`);
 }
+function resolvePostReviewIdentityFailure(content, failure) {
+    const exemption = resolvePostReviewExemption(content);
+    if (!exemption.ok) {
+        return failResult("post-review-commit", exemption.message, exemption.code);
+    }
+    if (exemption.exemptions.length === 0) {
+        return failResult("post-review-commit", failure.message, failure.code);
+    }
+    return passResult("post-review-commit", `Human-decided post-review exemption overrode ${failure.code}: ${failure.message}; ${formatPostReviewExemptions(exemption.exemptions)}`);
+}
+function formatPostReviewExemptions(exemptions) {
+    return exemptions.map((row) => `${row.id}: ${row.evidence}`).join("; ");
+}
 function resolvePostReviewExemption(content) {
     try {
+        const rows = parseLedger(content);
+        const invalid = validateLedgerRows(rows);
+        if (invalid) {
+            return {
+                ok: false,
+                code: "POST_REVIEW_EXEMPTION_INVALID",
+                message: `${invalid.code}: ${invalid.message}`
+            };
+        }
         return {
             ok: true,
-            exempt: parseLedger(content).some((row) => row.stage === POST_REVIEW_COMMIT_STAGE && row.status === "human-decided")
+            exemptions: rows.filter((row) => row.stage === POST_REVIEW_COMMIT_STAGE)
         };
     }
-    catch {
-        return { ok: false, message: "Invalid disagreement ledger" };
+    catch (error) {
+        return {
+            ok: false,
+            code: "POST_REVIEW_EXEMPTION_INVALID",
+            message: `Invalid disagreement ledger: ${error instanceof Error ? error.message : String(error)}`
+        };
     }
 }
 function checkReviewFact({ taskDir, artifactFile }) {

package/dist/lib/task/verification.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { verifyInProcess } from './verification-engine.js';
 import { parseArtifactName } from './artifact-lifecycle.js';
 import { resolveTaskRef } from './resolve-ref.js';
+import { allowsManualOverride } from './guard-override.js';
 const gate = (skill, expectedState, artifactFamily) => ({
     skill, expectedState, mode: 'gate', ...(artifactFamily ? { artifactFamily } : {})
 });
@@ -47,7 +48,7 @@ function verifyTaskEvent(request, options = {}) {
     if (!resolved.ok)
         return failure(request, resolved.code, resolved.message, { taskId: resolved.taskId, skill: spec.skill, mode: spec.mode });
     const identity = { taskId: resolved.taskId, taskDir: resolved.taskDir, taskState: resolved.state, skill: spec.skill, mode: spec.mode };
-    if (resolved.state !== spec.expectedState) {
+    if (resolved.state !== spec.expectedState && !allowsManualOverride(options.manualOverride, 'task-verify', 'VERIFY_TASK_STATE_MISMATCH')) {
         return failure(request, 'VERIFY_TASK_STATE_MISMATCH', `event '${request.event}' requires workspace '${spec.expectedState}', received '${resolved.state}'`, identity);
     }
     if (spec.artifactFamily) {
@@ -66,12 +67,23 @@ function verifyTaskEvent(request, options = {}) {
     if (spec.mode === 'gate') {
         const payload = engine({ mode: 'gate', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [], repositoryRoot: resolved.repoRoot });
         const status = payload.gate;
+        if (status !== 'pass' && allowsManualOverride(options.manualOverride, 'verification-engine', status === 'blocked' ? 'CHECK_BLOCKED' : 'CHECK_FAILED')) {
+            invocations.push({ status: 'pass', exitCode: 0, payload: { ...payload, gate: 'pass', humanOverride: 'human-approved', originalGate: status } });
+            return {
+                status: 'pass', changed: false, event: request.event, requestRef: request.taskRef,
+                ...identity, artifact: request.artifact ?? null, invocations, error: null
+            };
+        }
         invocations.push({ status, exitCode: { pass: 0, fail: 1, blocked: 2 }[status], payload });
     }
     else {
         for (const check of spec.checks ?? []) {
             const payload = engine({ mode: 'checks', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [check], repositoryRoot: resolved.repoRoot });
             const status = payload.status;
+            if (status !== 'pass' && allowsManualOverride(options.manualOverride, 'verification-engine', status === 'blocked' ? 'CHECK_BLOCKED' : 'CHECK_FAILED')) {
+                invocations.push({ status: 'pass', exitCode: 0, payload: { ...payload, status: 'pass', humanOverride: 'human-approved', originalStatus: status } });
+                break;
+            }
             invocations.push({ status, exitCode: { pass: 0, fail: 1, blocked: 2 }[status], payload });
             if (status !== 'pass')
                 break;

package/dist/lib/task/workflow-warning-intents.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import { resolveTaskRef } from './resolve-ref.js';
 import { WORKFLOW_WARNING_COLUMNS, WORKFLOW_WARNING_HEADINGS, WORKFLOW_WARNING_SEVERITIES, WORKFLOW_WARNING_STATUSES, parseWorkflowWarnings } from './workflow-warnings.js';
 import { captureTaskWriteMetadata, writeTask } from './write.js';
+import { allowsManualOverride } from './guard-override.js';
 function failed(intent, code, message, taskId = null, entityId = null) {
     return { status: 'failed', changed: false, intent: intent.kind, taskId, entityId, before: null, after: null, warnings: [], operations: [], error: { code, message } };
 }
@@ -54,7 +55,8 @@ function applyWorkflowWarningIntent(intent, options = {}) {
     const resolved = resolveTaskRef(intent.taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
         return failed(intent, resolved.code, resolved.message, resolved.taskId);
-    if (resolved.state !== 'active')
+    const stateOverride = allowsManualOverride(options.manualOverride, 'workflow-warning', 'TASK_STATE_MISMATCH');
+    if (resolved.state !== 'active' && !stateOverride)
         return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
     let content;
     let rows;
@@ -114,7 +116,7 @@ function applyWorkflowWarningIntent(intent, options = {}) {
             after = { ...before, status: intent.status, resolvedAt: metadata.timestamp, resolution };
     }
     const writeResult = writeTask({
-        taskRef: intent.taskRef, expectedState: 'active', mutations: [...sectionMutation(content), rowMutation(after)], dryRun: intent.dryRun
+        taskRef: intent.taskRef, expectedState: stateOverride ? resolved.state : 'active', mutations: [...sectionMutation(content), rowMutation(after)], dryRun: intent.dryRun
     }, {
         ...options,
         taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state },

package/dist/lib/task/write.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { VERSION } from '../version.js';
 import { parseTypedTaskFrontmatter, updateTaskFrontmatter } from './frontmatter.js';
 import { resolveTaskRef } from './resolve-ref.js';
+import { allowsManualOverride } from './guard-override.js';
 import { mutateTableRow, upsertSection } from './sections.js';
 const DEFAULT_FILE_SYSTEM = {
     readFileSync: (file) => fs.readFileSync(file, 'utf8'),
@@ -70,7 +71,7 @@ function writeTask(request, options = {}) {
         taskMdPath: resolved.taskMdPath,
         actualState: resolved.state
     };
-    if (resolved.state !== request.expectedState) {
+    if (resolved.state !== request.expectedState && !allowsManualOverride(options.manualOverride, 'task.write', 'TASK_STATE_MISMATCH')) {
         return failure(request, identity, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected ${request.expectedState}`);
     }
     const io = { ...DEFAULT_FILE_SYSTEM, ...options.fileSystem };

package/dist/lifecycle-build-manifest.json

@@ -0,0 +1,6 @@
+{
+  "protocolVersion": 3,
+  "packageVersion": "0.9.8",
+  "sourceInputHash": "fb481e6579519b3fd10c9ca9bf284d65498f935c034a14c047d023345abeb87c",
+  "internalExecutableBuildHash": "d8dcdf602b61001ba9829aa2027cccadcc9c371ccf9e29c3d681fd02d5a3a5af"
+}

package/lib/agent-clients/adapters/claude-code.ts

@@ -16,7 +16,7 @@ const claudeCodeAdapter = defineAgentClientAdapter({
     commands: { level: 'integrated' },
     hooks: { level: 'integrated' },
     subagents: { level: 'experimental' },
-    orchestration: { level: 'unsupported' },
+    orchestration: { level: 'experimental' },
     sandbox: { level: 'integrated' },
     verification: { level: 'compatible' }
   },
@@ -26,8 +26,8 @@ const claudeCodeAdapter = defineAgentClientAdapter({
     guidance: 'Use the host model picker for the complete model and reasoning-effort catalog.'
   },
   delegationEvidence: {
-    actualModel: 'unavailable',
-    actualReasoningEffort: 'unavailable'
+    actualModel: 'host-event',
+    actualReasoningEffort: 'spawn-ack'
   },
   project: {
     ownedPathPrefixes: ['.claude/'],

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<{
@@ -19,6 +20,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 +141,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 +158,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);
@@ -533,7 +559,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();
@@ -541,13 +567,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
+};