@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/lib/task/artifact-repair-intent.ts

@@ -1,71 +1,200 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 
 import type { ArtifactSchemaFamily } from './artifact-schema.ts';
+import { parseArtifactName } from './artifact-name.ts';
 
-type ArtifactRepairIntent = Readonly<{
-  version: 1;
+export type ArtifactRecoveryPhase =
+  | 'orchestration.prepare'
+  | 'artifact.finalize-local'
+  | 'task-event.completed';
+export type ArtifactRecoveryState =
+  | 'awaiting-recovery'
+  | 'finalize-ready'
+  | 'commit-started'
+  | 'passed'
+  | 'consumed'
+  | 'aborted';
+
+export type ArtifactRecoveryIntent = Readonly<{
+  version: 3;
   taskId: string;
   family: ArtifactSchemaFamily;
   artifact: string;
-  state: 'awaiting-repair' | 'passed' | 'consumed';
-  baselineSemanticDigest: string | null;
-  artifactSha256: string;
-  semanticDigest: string;
+  round: number;
+  state: ArtifactRecoveryState;
+  baselineSha256: string;
+  baselineSemanticDigest: string;
+  stagingId: string;
+  candidateSha256: string | null;
+  finalArtifactSha256: string | null;
+  finalSemanticDigest: string | null;
+  recoveryOperationId: string;
+  phase: ArtifactRecoveryPhase | null;
+  authorityDigest: string | null;
+  requestId: string;
+  errorCode: string | null;
+  errorMessage: string | null;
+  createdAt: number;
+  updatedAt: number;
 }>;
 
-function intentRoot(repoRoot: string): string {
+export function artifactRecoveryIntentRoot(repoRoot: string): string {
   return path.join(repoRoot, '.agents', 'workspace', '.local-artifact-finalization-intents');
 }
 
+export function artifactRecoveryRoot(taskDir: string, stagingId: string): string {
+  return path.join(taskDir, '.local-artifact-recovery', stagingId);
+}
+
 function intentPath(repoRoot: string, taskId: string, family: ArtifactSchemaFamily, artifact: string): string {
-  return path.join(intentRoot(repoRoot), `${taskId}-${family}-${artifact}.json`);
+  return path.join(artifactRecoveryIntentRoot(repoRoot), `${taskId}-${family}-${artifact}.json`);
+}
+
+function validDigest(value: unknown): value is string {
+  return typeof value === 'string' && /^[a-f0-9]{64}$/u.test(value);
+}
+
+function validTaskId(value: unknown): value is string {
+  return typeof value === 'string' && /^TASK-\d{8}-\d{6}$/u.test(value);
+}
+
+function validToken(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && !/[\r\n]/u.test(value);
+}
+
+function validRecoveryId(value: unknown): value is string {
+  return typeof value === 'string' && /^[a-f0-9-]{16,64}$/u.test(value);
 }
 
-function isArtifactRepairIntent(value: unknown): value is ArtifactRepairIntent {
+function validArtifact(value: unknown, family: unknown, round: unknown): value is string {
+  if (typeof value !== 'string' || path.basename(value) !== value || !value.endsWith('.md')) return false;
+  const parsed = parseArtifactName(value);
+  return Boolean(parsed && parsed.family === family && parsed.round === round);
+}
+
+function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+}
+
+export function isArtifactRecoveryIntent(value: unknown): value is ArtifactRecoveryIntent {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
   const intent = value as Record<string, unknown>;
-  return intent.version === 1
-    && typeof intent.taskId === 'string' && /^TASK-\d{8}-\d{6}$/.test(intent.taskId)
-    && typeof intent.family === 'string' && ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'].includes(intent.family)
-    && typeof intent.artifact === 'string' && intent.artifact.length > 0
-    && ['awaiting-repair', 'passed', 'consumed'].includes(String(intent.state))
-    && (intent.baselineSemanticDigest === null || (typeof intent.baselineSemanticDigest === 'string' && /^[a-f0-9]{64}$/.test(intent.baselineSemanticDigest)))
-    && typeof intent.artifactSha256 === 'string' && /^[a-f0-9]{64}$/.test(intent.artifactSha256)
-    && typeof intent.semanticDigest === 'string' && /^[a-f0-9]{64}$/.test(intent.semanticDigest)
-    && (intent.state === 'awaiting-repair' ? intent.baselineSemanticDigest === intent.semanticDigest : true);
+  return exactKeys(intent, [
+    'artifact', 'authorityDigest', 'baselineSemanticDigest', 'baselineSha256', 'candidateSha256',
+    'createdAt', 'errorCode', 'errorMessage', 'family', 'finalArtifactSha256', 'finalSemanticDigest',
+    'phase', 'recoveryOperationId', 'requestId', 'round', 'stagingId', 'state', 'taskId', 'updatedAt',
+    'version'
+  ])
+    && intent.version === 3
+    && validTaskId(intent.taskId)
+    && typeof intent.family === 'string'
+    && ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'].includes(intent.family)
+    && Number.isSafeInteger(intent.round) && (intent.round as number) > 0
+    && validArtifact(intent.artifact, intent.family, intent.round)
+    && ['awaiting-recovery', 'finalize-ready', 'commit-started', 'passed', 'consumed', 'aborted'].includes(String(intent.state))
+    && validDigest(intent.baselineSha256)
+    && validDigest(intent.baselineSemanticDigest)
+    && validRecoveryId(intent.stagingId)
+    && (intent.candidateSha256 === null || validDigest(intent.candidateSha256))
+    && (intent.finalArtifactSha256 === null || validDigest(intent.finalArtifactSha256))
+    && (intent.finalSemanticDigest === null || validDigest(intent.finalSemanticDigest))
+    && validRecoveryId(intent.recoveryOperationId)
+    && intent.stagingId === intent.recoveryOperationId
+    && (intent.phase === null || ['orchestration.prepare', 'artifact.finalize-local', 'task-event.completed'].includes(String(intent.phase)))
+    && (intent.authorityDigest === null || validDigest(intent.authorityDigest))
+    && validToken(intent.requestId)
+    && (intent.errorCode === null || validToken(intent.errorCode))
+    && (intent.errorMessage === null || validToken(intent.errorMessage))
+    && Number.isSafeInteger(intent.createdAt)
+    && Number.isSafeInteger(intent.updatedAt)
+    && (intent.state === 'awaiting-recovery'
+      ? intent.finalArtifactSha256 === null && intent.finalSemanticDigest === null
+      : true)
+    && (intent.state === 'finalize-ready' || intent.state === 'commit-started' || intent.state === 'passed' || intent.state === 'consumed'
+      ? validDigest(intent.candidateSha256) && validDigest(intent.finalArtifactSha256) && validDigest(intent.finalSemanticDigest)
+      : true)
+    && (intent.state === 'aborted' ? intent.errorCode !== null && intent.errorMessage !== null : true);
 }
 
-function readArtifactRepairIntent(
+export function readArtifactRecoveryIntent(
   repoRoot: string,
   taskId: string,
   family: ArtifactSchemaFamily,
   artifact: string
-): ArtifactRepairIntent | null {
+): ArtifactRecoveryIntent | null {
+  if (!validTaskId(taskId) || !validArtifact(artifact, family, parseArtifactName(artifact)?.round)) {
+    throw new Error('ARTIFACT_RECOVERY_INTENT_INVALID: recovery journal identity is invalid');
+  }
   const target = intentPath(repoRoot, taskId, family, artifact);
   if (!fs.existsSync(target)) return null;
   let value: unknown;
   try { value = JSON.parse(fs.readFileSync(target, 'utf8')) as unknown; }
-  catch (error) { throw new Error(`ARTIFACT_REPAIR_INTENT_INVALID: ${String(error)}`); }
-  if (!isArtifactRepairIntent(value) || value.taskId !== taskId || value.family !== family || value.artifact !== artifact) {
-    throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
+  catch (error) { throw new Error(`ARTIFACT_RECOVERY_INTENT_INVALID: ${String(error)}`); }
+  if (!isArtifactRecoveryIntent(value) || value.taskId !== taskId || value.family !== family || value.artifact !== artifact) {
+    throw new Error('ARTIFACT_RECOVERY_INTENT_INVALID: recovery journal schema is invalid');
   }
   return value;
 }
 
-function writeArtifactRepairIntent(repoRoot: string, value: ArtifactRepairIntent): void {
-  if (!isArtifactRepairIntent(value)) throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
-  const directory = intentRoot(repoRoot);
+export function writeArtifactRecoveryIntent(
+  repoRoot: string,
+  value: unknown,
+  options: Readonly<{ expected?: ArtifactRecoveryIntent | null }> = {}
+): void {
+  if (!isArtifactRecoveryIntent(value)) throw new Error('ARTIFACT_RECOVERY_INTENT_INVALID: recovery journal schema is invalid');
+  const intent = value;
+  const directory = artifactRecoveryIntentRoot(repoRoot);
   fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
-  const target = intentPath(repoRoot, value.taskId, value.family, value.artifact);
-  const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
-  fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
-  try { fs.renameSync(temporary, target); }
+  const target = intentPath(repoRoot, intent.taskId, intent.family, intent.artifact);
+  const lock = `${target}.lock`;
+  let descriptor: number;
+  try { descriptor = fs.openSync(lock, 'wx', 0o600); }
   catch (error) {
-    try { fs.unlinkSync(temporary); } catch { /* preserve primary error */ }
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+      throw new Error('ARTIFACT_RECOVERY_INTENT_CONFLICT: another journal writer owns the intent');
+    }
     throw error;
   }
+  try {
+    const current = fs.existsSync(target)
+      ? readArtifactRecoveryIntent(repoRoot, intent.taskId, intent.family, intent.artifact)
+      : null;
+    if (!isDeepStrictEqual(current, options.expected ?? null)) {
+      throw new Error('ARTIFACT_RECOVERY_INTENT_CONFLICT: recovery journal changed during finalization');
+    }
+    const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(intent)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    try { fs.renameSync(temporary, target); }
+    catch (error) {
+      try { fs.unlinkSync(temporary); } catch { /* preserve the primary error */ }
+      throw error;
+    }
+  } finally {
+    fs.closeSync(descriptor);
+    try { fs.unlinkSync(lock); } catch { /* preserve the primary result */ }
+  }
+}
+
+export function findArtifactRecoveryIntentsByOperation(
+  repoRoot: string,
+  operationId: string
+): readonly ArtifactRecoveryIntent[] {
+  if (!validToken(operationId)) throw new Error('ARTIFACT_RECOVERY_OPERATION_INVALID: recovery operation id is invalid');
+  const directory = artifactRecoveryIntentRoot(repoRoot);
+  if (!fs.existsSync(directory)) return Object.freeze([]);
+  return Object.freeze(fs.readdirSync(directory)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => {
+      const target = path.join(directory, name);
+      let value: unknown;
+      try { value = JSON.parse(fs.readFileSync(target, 'utf8')) as unknown; }
+      catch (error) { throw new Error(`ARTIFACT_RECOVERY_INTENT_INVALID: ${String(error)}`); }
+      if (!isArtifactRecoveryIntent(value)) throw new Error('ARTIFACT_RECOVERY_INTENT_INVALID: recovery journal schema is invalid');
+      return value;
+    })
+    .filter((value) => value.recoveryOperationId === operationId));
 }
 
-export { readArtifactRepairIntent, writeArtifactRepairIntent };
-export type { ArtifactRepairIntent };
+export { intentPath as artifactRecoveryIntentPath };

package/lib/task/artifact-schema.ts

@@ -1,13 +1,5 @@
-type ArtifactFamily =
-  | 'analysis'
-  | 'review-analysis'
-  | 'plan'
-  | 'review-plan'
-  | 'code'
-  | 'review-code'
-  | 'manual-validation'
-  | 'validation-run'
-  | 'pr-review';
+import { parseArtifactName } from './artifact-name.ts';
+import type { ArtifactFamily } from './artifact-name.ts';
 
 type ArtifactSchemaFamily = Exclude<ArtifactFamily, 'manual-validation' | 'validation-run' | 'pr-review'>;
 type ArtifactLocale = 'zh-CN' | 'en';
@@ -30,25 +22,6 @@ type ArtifactSkeletonInput = Readonly<{
   locale?: ArtifactLocale;
 }>;
 
-type ArtifactFamilySpec = Readonly<{
-  family: ArtifactFamily;
-  sectionAliases: readonly [string, string];
-  heading: string;
-  labels: readonly [string, string];
-}>;
-
-const ARTIFACT_FAMILY_CATALOG = [
-  { family: 'analysis', sectionAliases: ['分析', 'Analysis'], heading: '分析', labels: ['需求分析报告', 'Requirements Analysis'] },
-  { family: 'review-analysis', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['需求分析审查', 'Analysis Review'] },
-  { family: 'plan', sectionAliases: ['设计', 'Design'], heading: '设计', labels: ['技术方案', 'Technical Plan'] },
-  { family: 'review-plan', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['技术方案审查', 'Plan Review'] },
-  { family: 'code', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['实现报告', 'Implementation Report'] },
-  { family: 'review-code', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['代码审查', 'Code Review'] },
-  { family: 'manual-validation', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['人工验证', 'Manual Validation'] },
-  { family: 'validation-run', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['验证运行证据', 'Validation Run Evidence'] },
-  { family: 'pr-review', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['PR 审查报告', 'PR Review Report'] }
-] as const satisfies readonly ArtifactFamilySpec[];
-
 const LOCAL_SECTIONS = {
   analysis: [
     ['source', '需求来源', 'Requirements Source'],
@@ -157,8 +130,9 @@ function renderArtifactSkeleton(input: ArtifactSkeletonInput): string {
   const schema = getArtifactSchema(input.family);
   if (!schema) throw new Error(`unknown artifact schema family '${input.family}'`);
   const locale = input.locale ?? 'zh-CN';
-  const roundMatch = input.artifact.match(/-r(\d+)\.md$/);
-  const round = roundMatch ? Number(roundMatch[1]) : 1;
+  const identity = parseArtifactName(input.artifact);
+  if (identity?.family !== input.family) throw new Error(`invalid artifact identity '${input.artifact}' for '${input.family}'`);
+  const round = identity.round;
   const title = schema.title[locale === 'en' ? 'en' : 'zh'];
   const headings = locale === 'en' ? 'en' : 'zh';
   const lines = [
@@ -176,14 +150,11 @@ function renderArtifactSkeleton(input: ArtifactSkeletonInput): string {
 }
 
 export {
-  ARTIFACT_FAMILY_CATALOG,
   ARTIFACT_SCHEMAS,
   getArtifactSchema,
   renderArtifactSkeleton
 };
 export type {
-  ArtifactFamily,
-  ArtifactFamilySpec,
   ArtifactLocale,
   ArtifactSchema,
   ArtifactSchemaFamily,

package/lib/task/capabilities.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { parseArtifactName } from './artifact-name.ts';
 import type { InvalidationDocument } from './invalidation.ts';
 import { invalidationBlocks, isArtifactInvalidated, parseInvalidationDocument } from './invalidation.ts';
 import { receiptForOutput } from './artifact-receipts.ts';
@@ -141,13 +142,9 @@ function canStart(action: LifecycleAction, facts: LifecycleFacts, trigger: Expli
   return deny('CAPABILITY_ACTION_UNKNOWN');
 }
 
-function artifactRound(name: string): number {
-  const match = /-r(\d+)\.md$/.exec(name);
-  return match ? Number(match[1]) : 1;
-}
-
 function latestArtifact(names: readonly string[]): string | null {
-  return [...names].sort((left, right) => artifactRound(right) - artifactRound(left) || left.localeCompare(right))[0] ?? null;
+  return names.map(parseArtifactName).filter((identity) => identity !== null)
+    .sort((left, right) => right.round - left.round || left.name.localeCompare(right.name))[0]?.name ?? null;
 }
 
 function reviewedInputName(content: string, expectedFamily: 'analysis' | 'plan' | 'code'): string | null {
@@ -242,17 +239,11 @@ function buildLifecycleFacts(taskDir: string, content: string, taskState = 'acti
       const stat = fs.lstatSync(path.join(taskDir, name));
       return stat.isFile() && !stat.isSymbolicLink();
     });
-    const artifactFamilies = {
-      analysis: /^analysis(?:-r\d+)?\.md$/,
-      'review-analysis': /^review-analysis(?:-r\d+)?\.md$/,
-      plan: /^plan(?:-r\d+)?\.md$/,
-      'review-plan': /^review-plan(?:-r\d+)?\.md$/,
-      code: /^code(?:-r\d+)?\.md$/,
-      'review-code': /^review-code(?:-r\d+)?\.md$/
-    } as const;
-    const familyFor = (name: string): keyof typeof artifactFamilies | null =>
-      (Object.keys(artifactFamilies) as Array<keyof typeof artifactFamilies>)
-        .find((family) => artifactFamilies[family].test(name)) ?? null;
+    const artifactFamilies = ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'] as const;
+    const familyFor = (name: string) => {
+      const family = parseArtifactName(name)?.family;
+      return artifactFamilies.find((candidate) => candidate === family) ?? null;
+    };
     const activeFiles = files.filter((name) => {
       const family = familyFor(name);
       return !family || !isArtifactInvalidated(invalidation.document, family, name);
@@ -260,13 +251,13 @@ function buildLifecycleFacts(taskDir: string, content: string, taskState = 'acti
     const artifactHashes: Record<string, string> = {};
     for (const name of activeFiles) artifactHashes[name] = sha256File(path.join(taskDir, name));
     const artifacts: Partial<Record<LifecycleAction, readonly string[]>> = Object.fromEntries(
-      (Object.keys(artifactFamilies) as Array<keyof typeof artifactFamilies>).map((family) => [
-        family, activeFiles.filter((name) => artifactFamilies[family].test(name))
+      artifactFamilies.map((family) => [
+        family, activeFiles.filter((name) => familyFor(name) === family)
       ])
     ) as Partial<Record<LifecycleAction, readonly string[]>>;
     const staleArtifacts: Partial<Record<LifecycleAction, readonly string[]>> = Object.fromEntries(
-      (Object.keys(artifactFamilies) as Array<keyof typeof artifactFamilies>).map((family) => [
-        family, files.filter((name) => artifactFamilies[family].test(name) && isArtifactInvalidated(invalidation.document, family, name))
+      artifactFamilies.map((family) => [
+        family, files.filter((name) => familyFor(name) === family && isArtifactInvalidated(invalidation.document, family, name))
       ])
     ) as Partial<Record<LifecycleAction, readonly string[]>>;
     const qualification = parseTaskQualification(content);
@@ -274,7 +265,7 @@ function buildLifecycleFacts(taskDir: string, content: string, taskState = 'acti
     const qualificationStaleArtifacts: string[] = [];
     if (qualification.qualification.present) {
       const constraints = new Map(qualification.qualification.constraints.map((row) => [row.constraintId, row.digest]));
-      for (const family of Object.keys(artifactFamilies) as Array<keyof typeof artifactFamilies>) {
+      for (const family of artifactFamilies) {
         if (!ARTIFACT_AUDIT_FAMILIES.has(family)) continue;
         const name = latestArtifact(artifacts[family] ?? []);
         if (!name) continue;

package/lib/task/codex-orchestration.ts

@@ -29,10 +29,18 @@ import {
   OrchestrationStateError,
   pauseMatchingOrchestrationDelegation,
   prepareOrchestrationDelegation,
+  routeOrchestration,
   reconcileMatchingOrchestrationDelegation,
   sealMatchingOrchestrationDelegationWithHostEvidence
 } from './orchestration.ts';
+import { randomUUID, createHash } from 'node:crypto';
 import type { OrchestrationOptions, OrchestrationResult } from './orchestration.ts';
+import {
+  consumeLifecycleRecoveryAttestation,
+  issueLifecycleRecoveryAttestation,
+  validateLifecycleRecoveryAttestation,
+  type LifecycleRecoveryAttestationV1
+} from './control-authority.ts';
 
 type LifecycleStore = ReturnType<typeof createCodexLifecycleStore>;
 type CapabilityStore = ReturnType<typeof createCodexCapabilityStore>;
@@ -46,6 +54,7 @@ type CodexBridgeOptions = Readonly<{
   buildIdentity?: LifecycleBuildIdentity;
   orchestrationOptions?: OrchestrationOptions;
   controllerBinding?: Readonly<{ instanceDigest: string; controlGeneration: string }>;
+  deferLifecycleRecoveryConsumption?: boolean;
 }>;
 
 type CodexSpawnIdentity = Readonly<{
@@ -59,6 +68,10 @@ type CodexSpawnIdentity = Readonly<{
   requestedReasoningEffort?: string;
 }>;
 
+function buildIdentityDigest(value: LifecycleBuildIdentity): string {
+  return createHash('sha256').update(JSON.stringify(value), 'utf8').digest('hex');
+}
+
 function coreOptions(options: CodexBridgeOptions): OrchestrationOptions {
   return { ...options.orchestrationOptions, repoRoot: options.repoRoot ?? options.orchestrationOptions?.repoRoot };
 }
@@ -126,7 +139,8 @@ async function prepareCodexOrchestrationDelegation(
     client: AgentClientId;
     requestedModel?: string;
     requestedReasoningEffort?: string;
-    capabilityToken?: string;
+    capabilityRef?: string;
+    lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
   }>,
   options: CodexBridgeOptions = {}
 ): Promise<OrchestrationResult> {
@@ -136,10 +150,11 @@ async function prepareCodexOrchestrationDelegation(
     const resolved = resolveTaskRef(taskRef, { repoRoot });
     if (!resolved.ok) return bridgeFailure(resolved.code, resolved.message);
     const preflight = await (options.preflight ?? preflightCodexLifecycleEvidence)(repoRoot);
-    if (!input.capabilityToken) {
+    const capabilityRef = input.capabilityRef;
+    if (!capabilityRef) {
       return bridgeFailure(
         'ORCHESTRATION_CODEX_CAPABILITY_REQUIRED',
-        'Codex prepare requires a current-session capability token'
+        'Codex prepare requires a current-session capability reference'
       );
     }
     const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(repoRoot);
@@ -168,7 +183,7 @@ async function prepareCodexOrchestrationDelegation(
       controlGeneration: localController.controlGeneration
     } : null);
     const capabilityStore = options.capabilityStore ?? createCodexCapabilityStore();
-    const attested = capabilityStore.inspect(input.capabilityToken);
+    const attested = capabilityStore.inspectReference(capabilityRef);
     const capabilityIdentity = verifyLifecycleBuildIdentity(attested.buildIdentity, buildIdentity);
     if (!capabilityIdentity.ok) {
       return bridgeFailure(capabilityIdentity.code!, capabilityIdentity.message!);
@@ -193,14 +208,60 @@ async function prepareCodexOrchestrationDelegation(
         controlGeneration: controller.controlGeneration
       } } : {})
     };
+    if (input.lifecycleRecoveryAttestation) {
+      try { validateLifecycleRecoveryAttestation(input.lifecycleRecoveryAttestation); }
+      catch (error) {
+        return bridgeFailure(
+          'LIFECYCLE_AUTHORITY_ATTESTATION_INVALID',
+          error instanceof Error ? error.message : String(error)
+        );
+      }
+    }
+    let lifecycleRecoveryAttestation: LifecycleRecoveryAttestationV1 | null = input.lifecycleRecoveryAttestation ?? null;
+    const routed = input.capabilityRef && !lifecycleRecoveryAttestation
+      ? routeOrchestration(taskRef, coreOptions(options))
+      : null;
+    if (routed && !routed.next) return routed;
+    if (routed?.next && ['analysis', 'plan', 'code'].includes(routed.next.stage)) {
+      const recoveryRequest = {
+        version: 1 as const,
+        requestId: randomUUID(),
+        operationId: randomUUID(),
+        phase: 'orchestration.prepare' as const,
+        taskId: resolved.taskId,
+        family: routed.next.stage === 'analysis' ? 'analysis' as const
+          : routed.next.stage === 'plan' ? 'plan' as const : 'code' as const,
+        artifact: routed.next.artifact,
+        round: routed.next.round,
+        lifecycleRequestId: randomUUID(),
+        authorityRef: capabilityRef,
+        expectedControlGeneration: controller?.controlGeneration ?? '',
+        expectedControllerInstanceDigest: controller?.instanceDigest ?? '0'.repeat(64),
+        expectedBuildIdentityDigest: buildIdentityDigest(buildIdentity),
+        expectedHookDefinitionHash: preflight.hookDefinitionHash
+      };
+      const authority = issueLifecycleRecoveryAttestation(recoveryRequest, {
+        capabilityStore,
+        ...(controller ? { controllerBinding: controller } : {}),
+        buildIdentity
+      });
+      if (authority.status === 'rejected' || !authority.attestation) {
+        return bridgeFailure(
+          authority.error?.code ?? 'LIFECYCLE_AUTHORITY_REJECTED',
+          authority.error?.message ?? 'lifecycle authority was rejected'
+        );
+      }
+      lifecycleRecoveryAttestation = authority.attestation;
+    }
     const prepared = prepareOrchestrationDelegation(taskRef, {
       ...input,
-      lifecycleProvenance
+      lifecycleProvenance,
+      lifecycleRecoveryAttestation
     }, {
       ...coreOptions(options),
       validateLifecycleCapability: () => {
         try {
-          const validated = capabilityStore.validate(input.capabilityToken!, capabilityExpected);
+          const validated = capabilityStore.validateReference(capabilityRef, capabilityExpected);
           if (validated.sessionId !== attested.sessionId
             || validated.turnId !== attested.turnId
             || validated.toolUseId !== attested.toolUseId) {
@@ -214,23 +275,18 @@ async function prepareCodexOrchestrationDelegation(
           return capabilityFailure(error);
         }
       },
-      consumeLifecycleCapability: () => {
-        try {
-          const consumed = capabilityStore.consume(input.capabilityToken!, capabilityExpected);
-          if (consumed.sessionId !== attested.sessionId
-            || consumed.turnId !== attested.turnId
-            || consumed.toolUseId !== attested.toolUseId) {
-            return {
-              code: 'CODEX_CAPABILITY_IDENTITY_CHANGED',
-              message: 'capability identity changed during consumption'
-            };
-          }
-          return null;
-        } catch (error) {
-          return capabilityFailure(error);
-        }
-      }
+      consumeLifecycleCapability: () => null
     });
+    if (lifecycleRecoveryAttestation && !options.deferLifecycleRecoveryConsumption && prepared.status !== 'failed') {
+      try {
+        consumeLifecycleRecoveryAttestation(lifecycleRecoveryAttestation);
+      } catch (error) {
+        return bridgeFailure(
+          error instanceof Error ? error.name : 'LIFECYCLE_AUTHORITY_CONSUME_FAILED',
+          error instanceof Error ? error.message : String(error)
+        );
+      }
+    }
     return identityWarnings.length > 0 && prepared.status !== 'failed'
       ? { ...prepared, warnings: Object.freeze(identityWarnings) }
       : prepared;
@@ -283,7 +339,12 @@ async function activateCodexOrchestrationDelegation(
     const contextVerification = contextPath
       ? verifySandboxControllerWithWarnings(contextPath, { repoRoot })
       : null;
-    const controller = contextVerification?.context ?? null;
+    const controller = options.controllerBinding
+      ?? brokerControllerBinding()
+      ?? (contextVerification?.context ? {
+        instanceDigest: contextVerification.context.controllerInstanceDigest,
+        controlGeneration: contextVerification.context.controlGeneration
+      } : null);
     const activated = activateMatchingOrchestrationDelegation('codex', {
       nativeAgent: evidence.nativeAgent,
       childId: evidence.childThreadId,
@@ -305,7 +366,7 @@ async function activateCodexOrchestrationDelegation(
         capabilityTurnId: evidence.parentTurnId,
         spawnToolUseId: evidence.spawnToolUseId,
         spawnObservedAt: record.spawnObservedAt ?? undefined,
-        controllerInstanceDigest: controller?.controllerInstanceDigest ?? null,
+        controllerInstanceDigest: controller?.instanceDigest ?? null,
         controlGeneration: controller?.controlGeneration ?? null
       }
     }, coreOptions(options));

package/lib/task/commit-identity.ts

@@ -0,0 +1,31 @@
+import { execFileSync } from 'node:child_process';
+
+import type { CheckpointIntent } from './commit-intent.ts';
+
+function gitText(repoRoot: string, args: readonly string[]): string {
+  return execFileSync('git', [...args], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  }).trim();
+}
+
+function checkpointCommitMatches(repoRoot: string, intent: CheckpointIntent, head: string): boolean {
+  try {
+    const parent = gitText(repoRoot, ['rev-parse', `${head}^`]);
+    const tree = gitText(repoRoot, ['rev-parse', `${head}^{tree}`]);
+    const message = gitText(repoRoot, ['show', '-s', '--format=%s', head]);
+    const changed = gitText(repoRoot, ['diff-tree', '--no-commit-id', '--name-only', '-r', head])
+      .split('\n')
+      .filter(Boolean)
+      .sort();
+    return parent === intent.expectedHead
+      && tree === intent.expectedTree
+      && message === intent.message
+      && JSON.stringify(changed) === JSON.stringify([...intent.paths].sort());
+  } catch {
+    return false;
+  }
+}
+
+export { checkpointCommitMatches };