@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/lib/task/control-authority.ts

@@ -1,4 +1,6 @@
 import path from 'node:path';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
 
 import { normalizeAgentToken } from '../agent-clients/tokens.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
@@ -37,9 +39,484 @@ import {
   type TaskLifecycleRequest,
   type TaskLifecycleResult
 } from './lifecycle.ts';
+import {
+  recoverStartedLifecycleUnderLock,
+  recoveryFailure,
+  type LifecycleRecoveryResult
+} from './lifecycle-recovery.ts';
+import type { LifecycleRecoveryRequest } from './lifecycle-recovery.ts';
+import { locateActivityLog } from './activity-log.ts';
 import { resolveTaskRef, TASK_ID_RE } from './resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import { verifyTaskEvent } from './verification.ts';
+import { createCodexCapabilityStore } from '../agent-clients/adapters/codex-lifecycle/capability-store.ts';
+import {
+  findArtifactRecoveryIntentsByOperation,
+  writeArtifactRecoveryIntent,
+  type ArtifactRecoveryIntent
+} from './artifact-repair-intent.ts';
+import {
+  computeLifecycleBuildIdentity,
+  verifyLifecycleBuildIdentity,
+  type LifecycleBuildIdentity
+} from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
+
+export type LifecycleAuthorityPhase =
+  | 'orchestration.prepare'
+  | 'artifact.finalize-local'
+  | 'task-event.completed';
+
+export type LifecycleAuthorityRequestV1 = Readonly<{
+  version: 1;
+  requestId: string;
+  operationId: string;
+  phase: LifecycleAuthorityPhase;
+  taskId: string;
+  family: 'analysis' | 'plan' | 'code';
+  artifact: string;
+  round: number;
+  lifecycleRequestId: string;
+  authorityRef: string;
+  expectedControlGeneration: string;
+  expectedControllerInstanceDigest: string;
+  expectedBuildIdentityDigest: string;
+  expectedHookDefinitionHash: string;
+}>;
+
+export type LifecycleRecoveryAttestationV1 = Readonly<{
+  version: 1;
+  attestationId: string;
+  authorityRefDigest: string;
+  operationId: string;
+  phase: LifecycleAuthorityPhase;
+  requestId: string;
+  lifecycleRequestId: string;
+  taskId: string;
+  family: 'analysis' | 'plan' | 'code';
+  artifact: string;
+  round: number;
+  controlGeneration: string;
+  controllerInstanceDigest: string;
+  sessionId: string;
+  turnId: string;
+  toolUseId: string;
+  buildIdentityDigest: string;
+  hookDefinitionHash: string;
+  issuedAt: number;
+  expiresAt: number;
+}>;
+
+export type LifecycleAuthorityResponseV1 = Readonly<{
+  version: 1;
+  requestId: string;
+  operationId: string;
+  phase: LifecycleAuthorityPhase;
+  status: 'issued' | 'already-completed' | 'rejected';
+  attestation: LifecycleRecoveryAttestationV1 | null;
+  error: { code: string; message: string } | null;
+}>;
+
+type LifecycleAuthorityIssuerOptions = Readonly<{
+  controllerBinding?: TaskControlControllerBinding | null;
+  capabilityStore?: ReturnType<typeof createCodexCapabilityStore>;
+  buildIdentity?: LifecycleBuildIdentity;
+  now?: () => number;
+  operationAttestations?: Map<string, LifecycleRecoveryAttestationV1>;
+}>;
+
+export type LifecycleRecoveryOperationQueryV1 = Readonly<{
+  version: 1;
+  operationId: string;
+  status: 'unknown' | 'in-progress' | 'committed';
+  capabilityState: 'unknown' | 'reserved' | 'consumed';
+  phases: readonly Readonly<{
+    phase: LifecycleAuthorityPhase;
+    requestId: string;
+    attestationId: string | null;
+    state: 'issued' | 'consumed' | 'observed';
+  }>[];
+}>;
+
+const lifecycleAuthorityPhases: readonly LifecycleAuthorityPhase[] = [
+  'orchestration.prepare', 'artifact.finalize-local', 'task-event.completed'
+];
+const lifecycleAuthorityFamilies = ['analysis', 'plan', 'code'] as const;
+const lifecycleAuthorityArtifact = /^(?:analysis|plan|code)(?:-r[1-9]\d*)?\.md$/u;
+const lifecycleAuthorityDigest = (value: string): string => crypto.createHash('sha256').update(value, 'utf8').digest('hex');
+const lifecycleAuthorityBuildDigest = (value: LifecycleBuildIdentity): string => lifecycleAuthorityDigest(JSON.stringify(value));
+
+export function lifecycleRecoveryAttestationDigest(value: LifecycleRecoveryAttestationV1): string {
+  return lifecycleAuthorityDigest(JSON.stringify(value));
+}
+
+function authorityExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+}
+
+export function validateLifecycleAuthorityRequest(value: unknown): LifecycleAuthorityRequestV1 {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('LIFECYCLE_AUTHORITY_REQUEST_INVALID');
+  const request = value as Record<string, unknown>;
+  if (!authorityExactKeys(request, [
+    'artifact', 'authorityRef', 'expectedBuildIdentityDigest', 'expectedControlGeneration',
+    'expectedControllerInstanceDigest', 'expectedHookDefinitionHash', 'family', 'lifecycleRequestId',
+    'operationId', 'phase', 'requestId', 'round', 'taskId', 'version'
+  ])
+    || request.version !== 1
+    || typeof request.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(request.requestId)
+    || typeof request.operationId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(request.operationId)
+    || !lifecycleAuthorityPhases.includes(request.phase as LifecycleAuthorityPhase)
+    || typeof request.taskId !== 'string' || !/^TASK-\d{8}-\d{6}$/u.test(request.taskId)
+    || !lifecycleAuthorityFamilies.includes(request.family as typeof lifecycleAuthorityFamilies[number])
+    || typeof request.artifact !== 'string' || !lifecycleAuthorityArtifact.test(request.artifact)
+    || !Number.isSafeInteger(request.round) || (request.round as number) < 1
+    || typeof request.lifecycleRequestId !== 'string' || !request.lifecycleRequestId || /[\r\n]/u.test(request.lifecycleRequestId)
+    || typeof request.authorityRef !== 'string' || !request.authorityRef || /[\r\n]/u.test(request.authorityRef)
+    || typeof request.expectedControlGeneration !== 'string' || !request.expectedControlGeneration
+    || typeof request.expectedControllerInstanceDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(request.expectedControllerInstanceDigest)
+    || typeof request.expectedBuildIdentityDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(request.expectedBuildIdentityDigest)
+    || typeof request.expectedHookDefinitionHash !== 'string' || !/^[a-f0-9]{64}$/u.test(request.expectedHookDefinitionHash)) {
+    throw new Error('LIFECYCLE_AUTHORITY_REQUEST_INVALID');
+  }
+  const expectedArtifactFamily = request.artifact as string;
+  if (!expectedArtifactFamily.startsWith(request.family as string)) throw new Error('LIFECYCLE_AUTHORITY_REQUEST_INVALID');
+  return request as LifecycleAuthorityRequestV1;
+}
+
+export function validateLifecycleRecoveryAttestation(
+  value: unknown,
+  now = Date.now()
+): LifecycleRecoveryAttestationV1 {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('LIFECYCLE_AUTHORITY_ATTESTATION_INVALID');
+  const attestation = value as Record<string, unknown>;
+  if (!authorityExactKeys(attestation, [
+    'artifact', 'attestationId', 'authorityRefDigest', 'buildIdentityDigest', 'controlGeneration',
+    'controllerInstanceDigest', 'expiresAt', 'family', 'hookDefinitionHash', 'issuedAt',
+    'lifecycleRequestId', 'operationId', 'phase', 'requestId', 'round', 'sessionId',
+    'taskId', 'toolUseId', 'turnId', 'version'
+  ])
+    || attestation.version !== 1
+    || typeof attestation.attestationId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(attestation.attestationId)
+    || typeof attestation.authorityRefDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(attestation.authorityRefDigest)
+    || typeof attestation.operationId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(attestation.operationId)
+    || !lifecycleAuthorityPhases.includes(attestation.phase as LifecycleAuthorityPhase)
+    || typeof attestation.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(attestation.requestId)
+    || typeof attestation.lifecycleRequestId !== 'string' || !attestation.lifecycleRequestId
+    || typeof attestation.taskId !== 'string' || !/^TASK-\d{8}-\d{6}$/u.test(attestation.taskId)
+    || !lifecycleAuthorityFamilies.includes(attestation.family as typeof lifecycleAuthorityFamilies[number])
+    || typeof attestation.artifact !== 'string' || !lifecycleAuthorityArtifact.test(attestation.artifact)
+    || !Number.isSafeInteger(attestation.round) || (attestation.round as number) < 1
+    || typeof attestation.controlGeneration !== 'string' || !attestation.controlGeneration
+    || typeof attestation.controllerInstanceDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(attestation.controllerInstanceDigest)
+    || typeof attestation.sessionId !== 'string' || !attestation.sessionId
+    || typeof attestation.turnId !== 'string' || !attestation.turnId
+    || typeof attestation.toolUseId !== 'string' || !attestation.toolUseId
+    || typeof attestation.buildIdentityDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(attestation.buildIdentityDigest)
+    || typeof attestation.hookDefinitionHash !== 'string' || !/^[a-f0-9]{64}$/u.test(attestation.hookDefinitionHash)
+    || !Number.isSafeInteger(attestation.issuedAt) || !Number.isSafeInteger(attestation.expiresAt)
+    || (attestation.expiresAt as number) <= (attestation.issuedAt as number)
+    || (attestation.expiresAt as number) <= now) {
+    throw new Error('LIFECYCLE_AUTHORITY_ATTESTATION_INVALID');
+  }
+  return attestation as LifecycleRecoveryAttestationV1;
+}
+
+const authorityOperationMap = new WeakMap<object, Map<string, LifecycleRecoveryAttestationV1>>();
+const authorityRecords = new Map<string, Readonly<{
+  store: ReturnType<typeof createCodexCapabilityStore>;
+  capabilityRef: string;
+  expected: Readonly<{
+    taskId: string;
+    hookDefinitionHash: string;
+    buildIdentity: LifecycleBuildIdentity;
+    controller: TaskControlControllerBinding;
+  }>;
+}>>();
+const consumedAuthorityPhases = new Set<string>();
+
+export function issueLifecycleRecoveryAttestation(
+  input: LifecycleAuthorityRequestV1,
+  options: LifecycleAuthorityIssuerOptions = {}
+): LifecycleAuthorityResponseV1 {
+  let request: LifecycleAuthorityRequestV1;
+  try { request = validateLifecycleAuthorityRequest(input); }
+  catch (error) {
+    return { version: 1, requestId: String((input as { requestId?: unknown })?.requestId ?? ''), operationId: String((input as { operationId?: unknown })?.operationId ?? ''), phase: (input as { phase?: LifecycleAuthorityPhase })?.phase ?? 'artifact.finalize-local', status: 'rejected', attestation: null, error: { code: 'LIFECYCLE_AUTHORITY_REQUEST_INVALID', message: error instanceof Error ? error.message : String(error) } };
+  }
+  const binding = options.controllerBinding ?? null;
+  if (!binding) return authorityRejected(request, 'LOCAL_EXECUTION_AUTHORITY_UNAVAILABLE', 'current controller authority is unavailable');
+  if (binding.controlGeneration !== request.expectedControlGeneration
+    || binding.instanceDigest !== request.expectedControllerInstanceDigest) {
+    return authorityRejected(request, 'LIFECYCLE_AUTHORITY_CONTROLLER_MISMATCH', 'current controller binding does not match the request');
+  }
+  const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(process.cwd());
+  if (lifecycleAuthorityBuildDigest(buildIdentity) !== request.expectedBuildIdentityDigest) {
+    return authorityRejected(request, 'LIFECYCLE_AUTHORITY_BUILD_MISMATCH', 'current lifecycle build does not match the request');
+  }
+  const store = options.capabilityStore ?? createCodexCapabilityStore();
+  const registry = options.operationAttestations ?? authorityOperationMap.get(store) ?? new Map<string, LifecycleRecoveryAttestationV1>();
+  authorityOperationMap.set(store, registry);
+  const key = `${request.requestId}\0${request.operationId}\0${request.phase}`;
+  const prior = registry.get(key);
+  if (prior) return { version: 1, requestId: request.requestId, operationId: request.operationId, phase: request.phase, status: 'already-completed', attestation: prior, error: null };
+  try {
+    const expected = {
+      taskId: request.taskId,
+      hookDefinitionHash: request.expectedHookDefinitionHash,
+      buildIdentity,
+      controller: binding
+    };
+    const record = store.reserveReference(request.authorityRef, request.operationId, expected);
+    if (!record.sessionId || !record.turnId || !record.toolUseId) throw new Error('CODEX_CAPABILITY_IDENTITY_INVALID: capability hook attestation is incomplete');
+    const now = (options.now ?? Date.now)();
+    const attestation = validateLifecycleRecoveryAttestation({
+      version: 1,
+      attestationId: crypto.randomUUID(),
+      authorityRefDigest: lifecycleAuthorityDigest(request.authorityRef),
+      operationId: request.operationId,
+      phase: request.phase,
+      requestId: request.requestId,
+      lifecycleRequestId: request.lifecycleRequestId,
+      taskId: request.taskId,
+      family: request.family,
+      artifact: request.artifact,
+      round: request.round,
+      controlGeneration: binding.controlGeneration,
+      controllerInstanceDigest: binding.instanceDigest,
+      sessionId: record.sessionId,
+      turnId: record.turnId,
+      toolUseId: record.toolUseId,
+      buildIdentityDigest: lifecycleAuthorityBuildDigest(buildIdentity),
+      hookDefinitionHash: request.expectedHookDefinitionHash,
+      issuedAt: now,
+      expiresAt: Math.min(record.expiresAt, now + 30_000)
+    }, now);
+    store.reserveRecoveryPhase(
+      request.authorityRef,
+      request.operationId,
+      request.phase,
+      request.requestId,
+      expected
+    );
+    registry.set(key, attestation);
+    authorityRecords.set(attestation.attestationId, { store, capabilityRef: request.authorityRef, expected });
+    return { version: 1, requestId: request.requestId, operationId: request.operationId, phase: request.phase, status: 'issued', attestation, error: null };
+  } catch (error) {
+    return authorityRejected(request, error instanceof Error && error.name.startsWith('CODEX_') ? error.name : 'LIFECYCLE_AUTHORITY_REJECTED', error instanceof Error ? error.message : String(error));
+  }
+}
+
+export function consumeLifecycleRecoveryAttestation(
+  value: LifecycleRecoveryAttestationV1,
+  now = Date.now()
+): void {
+  const attestation = validateLifecycleRecoveryAttestation(value, now);
+  if (consumedAuthorityPhases.has(attestation.attestationId)) return;
+  const record = authorityRecords.get(attestation.attestationId);
+  if (!record) throw new Error('LIFECYCLE_AUTHORITY_ATTESTATION_UNKNOWN');
+  record.store.consumeRecoveryPhase(
+    record.capabilityRef,
+    attestation.operationId,
+    attestation.phase,
+    attestation.requestId,
+    record.expected
+  );
+  if (attestation.phase === 'task-event.completed') {
+    record.store.consumeReference(record.capabilityRef, attestation.operationId, record.expected);
+  }
+  consumedAuthorityPhases.add(attestation.attestationId);
+}
+
+export function queryLifecycleRecoveryOperation(
+  operationId: string,
+  options: Readonly<{
+    repoRoot?: string;
+    capabilityStore?: ReturnType<typeof createCodexCapabilityStore>;
+  }> = {}
+): LifecycleRecoveryOperationQueryV1 {
+  if (!/^[a-f0-9-]{16,64}$/u.test(operationId)) {
+    throw new Error('LIFECYCLE_RECOVERY_OPERATION_INVALID');
+  }
+  const store = options.capabilityStore ?? createCodexCapabilityStore();
+  const registry = authorityOperationMap.get(store);
+  const known = [...(registry?.values() ?? [])].filter((value) => value.operationId === operationId);
+  const intents = options.repoRoot ? findArtifactRecoveryIntentsByOperation(options.repoRoot, operationId) : [];
+  const capabilities = store.findByRecoveryOperation(operationId);
+  const phaseMap = new Map<string, LifecycleRecoveryOperationQueryV1['phases'][number]>();
+  for (const capability of capabilities) {
+    for (const phase of capability.recoveryPhases) {
+      phaseMap.set(`${phase.phase}\0${phase.requestId}`, {
+        phase: phase.phase,
+        requestId: phase.requestId,
+        attestationId: null,
+        state: phase.state === 'consumed' ? 'consumed' : 'observed'
+      });
+    }
+  }
+  for (const attestation of known) {
+    const key = `${attestation.phase}\0${attestation.requestId}`;
+    const durable = phaseMap.get(key);
+    phaseMap.set(key, {
+      phase: attestation.phase,
+      requestId: attestation.requestId,
+      attestationId: attestation.attestationId,
+      state: durable?.state === 'consumed' || consumedAuthorityPhases.has(attestation.attestationId)
+        ? 'consumed' : 'issued'
+    });
+  }
+  for (const intent of intents) {
+    if (!intent.phase) continue;
+    const key = `${intent.phase}\0${intent.requestId}`;
+    if (phaseMap.has(key)) continue;
+    phaseMap.set(key, {
+      phase: intent.phase,
+      requestId: intent.requestId,
+      attestationId: null,
+      state: intent.state === 'consumed' ? 'consumed' : 'observed'
+    });
+  }
+  const capabilityState = capabilities.some((record) => record.recoveryState === 'consumed')
+    ? 'consumed'
+    : capabilities.some((record) => record.recoveryState === 'reserved') ? 'reserved' : 'unknown';
+  const committed = capabilityState === 'consumed' || intents.some((intent) => intent.state === 'consumed');
+  return {
+    version: 1,
+    operationId,
+    status: committed ? 'committed' : capabilityState === 'reserved' || phaseMap.size > 0 ? 'in-progress' : 'unknown',
+    capabilityState,
+    phases: Object.freeze([...phaseMap.values()])
+  };
+}
+
+type LifecycleRecoveryCompensationOptions = Readonly<{
+  repoRoot: string;
+  controllerBinding: TaskControlControllerBinding;
+  capabilityStore?: ReturnType<typeof createCodexCapabilityStore>;
+  buildIdentity?: LifecycleBuildIdentity;
+  now?: () => number;
+}>;
+
+function lifecycleRecoveryCompensationError(code: string, message: string): Error {
+  const error = new Error(`${code}: ${message}`);
+  error.name = code;
+  return error;
+}
+
+function lifecycleRecoveryEventCommitted(
+  selector: LifecycleAuthorityRequestV1,
+  repoRoot: string
+): boolean {
+  const resolved = resolveTaskRef(selector.taskId, { repoRoot });
+  if (!resolved.ok || resolved.taskId !== selector.taskId) return false;
+  let content: string;
+  try { content = fs.readFileSync(resolved.taskMdPath, 'utf8'); }
+  catch { return false; }
+  const section = locateActivityLog(content);
+  if (!section) return false;
+  const labels = { analysis: 'Analyze Task', plan: 'Plan Task', code: 'Code Task' } as const;
+  const prefix = `${labels[selector.family]} (Round ${selector.round}`;
+  return section.entries.some((entry) => {
+    if (entry.step.endsWith(' [started]') || !entry.step.startsWith(prefix)) return false;
+    const delimiter = entry.step[prefix.length];
+    return (delimiter === ',' || delimiter === ')') && entry.note.endsWith(`→ ${selector.artifact}`);
+  });
+}
+
+function lifecycleRecoveryIntentMatches(
+  intent: ArtifactRecoveryIntent,
+  selector: LifecycleAuthorityRequestV1
+): boolean {
+  return intent.taskId === selector.taskId
+    && intent.family === selector.family
+    && intent.artifact === selector.artifact
+    && (intent.state === 'commit-started' || intent.state === 'consumed');
+}
+
+/**
+ * Completes only the durable tail of a committed task event after a process
+ * restart. The task event itself is the commit boundary and is never replayed.
+ */
+export function recoverLifecycleRecoveryOperation(
+  input: LifecycleAuthorityRequestV1,
+  options: LifecycleRecoveryCompensationOptions
+): LifecycleRecoveryOperationQueryV1 {
+  const selector = validateLifecycleAuthorityRequest(input);
+  if (selector.phase !== 'task-event.completed') {
+    throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_PHASE_UNSUPPORTED', 'only task-event.completed supports durable compensation');
+  }
+  const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(options.repoRoot);
+  if (selector.expectedBuildIdentityDigest !== lifecycleAuthorityBuildDigest(buildIdentity)) {
+    throw lifecycleRecoveryCompensationError('LIFECYCLE_AUTHORITY_BUILD_MISMATCH', 'current lifecycle build does not match the recovery request');
+  }
+  if (selector.expectedControlGeneration !== options.controllerBinding.controlGeneration
+    || selector.expectedControllerInstanceDigest !== options.controllerBinding.instanceDigest) {
+    throw lifecycleRecoveryCompensationError('LIFECYCLE_AUTHORITY_CONTROLLER_MISMATCH', 'current controller binding does not match the recovery request');
+  }
+  const store = options.capabilityStore ?? createCodexCapabilityStore();
+  const expected = {
+    taskId: selector.taskId,
+    hookDefinitionHash: selector.expectedHookDefinitionHash,
+    buildIdentity,
+    controller: options.controllerBinding
+  };
+  const capabilities = store.findByRecoveryOperation(selector.operationId);
+  if (capabilities.length !== 1 || capabilities[0]!.capabilityRefDigest !== lifecycleAuthorityDigest(selector.authorityRef)) {
+    throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_PROVENANCE_INVALID', 'durable capability provenance does not identify this operation');
+  }
+  const capability = capabilities[0]!;
+  const build = verifyLifecycleBuildIdentity(capability.buildIdentity, buildIdentity);
+  const expiredReserved = capability.status === 'expired' && capability.recoveryState === 'reserved';
+  if (!build.ok
+    || capability.taskId !== selector.taskId
+    || capability.hookDefinitionHash !== selector.expectedHookDefinitionHash
+    || capability.controller?.controlGeneration !== options.controllerBinding.controlGeneration
+    || capability.controller?.instanceDigest !== options.controllerBinding.instanceDigest
+    || capability.recoveryState === 'unreserved'
+    || capability.recoveryOperationId !== selector.operationId
+    || (!['attested', 'consumed'].includes(capability.status) && !expiredReserved)) {
+    throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_PROVENANCE_INVALID', 'durable capability provenance does not match the recovery request');
+  }
+  const phase = capability.recoveryPhases.find((entry) => entry.phase === selector.phase);
+  if (!phase) {
+    throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_PHASE_MISSING', 'durable task completion phase is missing');
+  }
+  const intents = findArtifactRecoveryIntentsByOperation(options.repoRoot, selector.operationId)
+    .filter((intent) => intent.taskId === selector.taskId
+      && intent.family === selector.family
+      && intent.artifact === selector.artifact);
+  if (intents.length !== 1) {
+    throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_INTENT_INVALID', 'durable artifact recovery intent does not identify this task event');
+  }
+  const intent = intents[0]!;
+  if (!lifecycleRecoveryIntentMatches(intent, selector)
+    || intent.phase !== selector.phase
+    || intent.requestId !== selector.lifecycleRequestId
+    || intent.authorityDigest === null) {
+    throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_INTENT_INVALID', 'durable artifact recovery intent does not match the recovery request');
+  }
+  if (!lifecycleRecoveryEventCommitted(selector, options.repoRoot)) {
+    throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_COMMIT_UNCONFIRMED', 'task completion is not durably present; compensation is not allowed');
+  }
+  if (capability.recoveryState === 'reserved') {
+    if (phase.state === 'issued') {
+      store.consumeRecoveryPhase(selector.authorityRef, selector.operationId, selector.phase, phase.requestId, expected, { allowExpiredReserved: true });
+    }
+    store.consumeReference(selector.authorityRef, selector.operationId, expected, { allowExpiredReserved: true });
+  } else if (phase.state !== 'consumed') {
+    throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_STATE_INVALID', 'consumed capability has an unconsumed completion phase');
+  }
+  if (intent.state !== 'consumed') {
+    writeArtifactRecoveryIntent(options.repoRoot, {
+      ...intent,
+      state: 'consumed',
+      updatedAt: (options.now ?? Date.now)()
+    }, { expected: intent });
+  }
+  return queryLifecycleRecoveryOperation(selector.operationId, { repoRoot: options.repoRoot, capabilityStore: store });
+}
+
+function authorityRejected(request: LifecycleAuthorityRequestV1, code: string, message: string): LifecycleAuthorityResponseV1 {
+  return { version: 1, requestId: request.requestId, operationId: request.operationId, phase: request.phase, status: 'rejected', attestation: null, error: { code, message } };
+}
 
 export type TaskControlControllerBinding = Readonly<{
   instanceDigest: string;
@@ -53,6 +530,7 @@ export type TaskControlExecutionContext =
       repoRoot: string;
       runtimeDir?: string;
       controllerBinding?: TaskControlControllerBinding | null;
+      lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
     }>
   | Readonly<{
       source: 'sandbox-executor';
@@ -66,6 +544,7 @@ export type TaskControlExecutionContext =
       requestId: string;
       diagnosticLog?: OrchestrationDiagnosticLogger;
       controllerBinding?: TaskControlControllerBinding | null;
+      lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
     }>;
 
 export type TaskControlOrchestrationIntent =
@@ -92,7 +571,15 @@ export type TaskControlOperation =
       options?: Omit<OrchestrationOptions, 'repoRoot'>;
     }>;
 
-export type TaskControlDispatchResult = TaskLifecycleResult | TaskFinalizationResult | OrchestrationResult;
+export type TaskControlDispatchResult = TaskLifecycleResult | LifecycleRecoveryResult | TaskFinalizationResult | OrchestrationResult;
+
+export function taskControlOperationKey(operation: TaskControlOperation): string {
+  if (operation.family === 'task-finalization') return 'complete';
+  if (operation.family === 'task-lifecycle') return operation.request.intent;
+  return operation.intent === 'route'
+    ? operation.input && operation.input.completed === true ? 'route.clean-completion' : 'route.read'
+    : operation.intent;
+}
 
 export type TaskLifecycleControlRequest = TaskLifecycleRequest & Readonly<{
   overrideTicket?: string;
@@ -121,13 +608,18 @@ export function createDirectHostExecutionContext(params: Readonly<{
   repoRoot: string;
   runtimeDir?: string;
   controllerBinding?: TaskControlControllerBinding | null;
+  lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
 }>): TaskControlExecutionContext {
   return {
     source: 'direct-host',
     mode: 'direct-host',
     repoRoot: absolute('repoRoot', params.repoRoot),
     ...(params.runtimeDir === undefined ? {} : { runtimeDir: absolute('runtimeDir', params.runtimeDir) }),
-    ...(params.controllerBinding === undefined ? {} : { controllerBinding: binding(params.controllerBinding) })
+    ...(params.controllerBinding === undefined ? {} : { controllerBinding: binding(params.controllerBinding) }),
+    ...(params.lifecycleRecoveryAttestation === undefined ? {} : {
+      lifecycleRecoveryAttestation: params.lifecycleRecoveryAttestation === null
+        ? null : validateLifecycleRecoveryAttestation(params.lifecycleRecoveryAttestation)
+    })
   };
 }
 
@@ -141,6 +633,7 @@ export function createSandboxExecutorExecutionContext(params: Readonly<{
   requestId: string;
   diagnosticLog?: OrchestrationDiagnosticLogger;
   controllerBinding?: TaskControlControllerBinding | null;
+  lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
 }>): TaskControlExecutionContext {
   if (!/^TASK-\d{8}-\d{6}$/u.test(params.taskId) || !params.generation || !params.requestId) {
     invalidContext('sandbox binding is incomplete');
@@ -160,7 +653,11 @@ export function createSandboxExecutorExecutionContext(params: Readonly<{
     manifestPath: absolute('manifestPath', params.manifestPath),
     requestId: params.requestId,
     ...(params.diagnosticLog === undefined ? {} : { diagnosticLog: params.diagnosticLog }),
-    ...(params.controllerBinding === undefined ? {} : { controllerBinding: binding(params.controllerBinding) })
+    ...(params.controllerBinding === undefined ? {} : { controllerBinding: binding(params.controllerBinding) }),
+    ...(params.lifecycleRecoveryAttestation === undefined ? {} : {
+      lifecycleRecoveryAttestation: params.lifecycleRecoveryAttestation === null
+        ? null : validateLifecycleRecoveryAttestation(params.lifecycleRecoveryAttestation)
+    })
   };
 }
 
@@ -170,6 +667,7 @@ export function assertTaskControlExecutionContext(context: TaskControlExecutionC
     absolute('repoRoot', context.repoRoot);
     if (context.runtimeDir !== undefined) absolute('runtimeDir', context.runtimeDir);
     binding(context.controllerBinding);
+    if (context.lifecycleRecoveryAttestation) validateLifecycleRecoveryAttestation(context.lifecycleRecoveryAttestation);
     return;
   }
   if (context.mode !== 'task-bound-sandbox' || !/^TASK-\d{8}-\d{6}$/u.test(context.taskId)
@@ -184,6 +682,7 @@ export function assertTaskControlExecutionContext(context: TaskControlExecutionC
     invalidContext('runtimeDir is not bound to the manifest control root');
   }
   binding(context.controllerBinding);
+  if (context.lifecycleRecoveryAttestation) validateLifecycleRecoveryAttestation(context.lifecycleRecoveryAttestation);
 }
 
 function operationTaskId(context: TaskControlExecutionContext, taskRef: string): void {
@@ -219,12 +718,15 @@ function lifecycleTaskId(request: TaskLifecycleControlRequest, repoRoot: string)
 async function applyLifecycleWithAuthority(
   context: TaskControlExecutionContext,
   request: TaskLifecycleControlRequest
-): Promise<TaskLifecycleResult & { humanOverride?: unknown }> {
+): Promise<(TaskLifecycleResult | LifecycleRecoveryResult) & { humanOverride?: unknown }> {
   const conflict = overrideDryRunConflict(request as unknown as Record<string, unknown>);
   if (conflict) {
     return taskLifecycleFailure(request, { code: 'LIFECYCLE_PAYLOAD_INVALID', message: conflict.message });
   }
-  const execute = async (): Promise<TaskLifecycleResult & { humanOverride?: unknown }> => {
+  const execute = async (): Promise<(TaskLifecycleResult | LifecycleRecoveryResult) & { humanOverride?: unknown }> => {
+    if (request.intent === 'recover-started') {
+      return recoverStartedLifecycleUnderLock(request as LifecycleRecoveryRequest, { repoRoot: context.repoRoot });
+    }
     const lifecycleResult = applyTaskLifecycle(request, { repoRoot: context.repoRoot });
     if (lifecycleResult.status !== 'failed' || !request.overrideTicket) return lifecycleResult;
     if (!request.overrideTarget || !request.overrideScope) {
@@ -258,6 +760,9 @@ async function applyLifecycleWithAuthority(
     );
   } catch (error) {
     if (!(error instanceof TaskExecutionLockError)) throw error;
+    if (request.intent === 'recover-started') {
+      return recoveryFailure(request as LifecycleRecoveryRequest, 'owner-unknown', error.code, error.message);
+    }
     return taskLifecycleFailure(request, { code: error.code, message: error.message }, taskId);
   }
 }
@@ -284,12 +789,16 @@ function orchestration(
         client: input.client as AgentClientId,
         requestedModel: input.requestedModel as string | undefined,
         requestedReasoningEffort: input.requestedReasoningEffort as string | undefined,
-        ...(input.capabilityToken === undefined ? {} : { capabilityToken: input.capabilityToken as string })
+        ...(input.capabilityRef === undefined ? {} : { capabilityRef: input.capabilityRef as string }),
+        ...(context.lifecycleRecoveryAttestation === undefined
+          ? {}
+          : { lifecycleRecoveryAttestation: context.lifecycleRecoveryAttestation })
       };
       if (prepareInput.client === 'codex') {
         return prepareCodexOrchestrationDelegation(operation.taskRef, prepareInput, {
           repoRoot: context.repoRoot,
           orchestrationOptions: options,
+          deferLifecycleRecoveryConsumption: context.source === 'sandbox-executor',
           ...(context.controllerBinding ? { controllerBinding: context.controllerBinding } : {})
         });
       }
@@ -332,7 +841,7 @@ function orchestrationFailure(error: unknown): OrchestrationResult {
 export function dispatchTaskControlOperation(
   context: TaskControlExecutionContext,
   operation: Extract<TaskControlOperation, { family: 'task-lifecycle' }>
-): Promise<TaskLifecycleResult & { humanOverride?: unknown }>;
+): Promise<(TaskLifecycleResult | LifecycleRecoveryResult) & { humanOverride?: unknown }>;
 export function dispatchTaskControlOperation(
   context: TaskControlExecutionContext,
   operation: Extract<TaskControlOperation, { family: 'task-finalization' }>
@@ -395,7 +904,7 @@ function operationInvalid(message: string): never {
 
 const LIFECYCLE_FLAGS = new Set([
   '--agent', '--reason', '--unblock-condition', '--note', '--alert-number', '--staging-dir', '--issue-number',
-  '--override-ticket', '--override-target', '--override-scope', '--dry-run'
+  '--stage', '--round', '--artifact', '--override-ticket', '--override-target', '--override-scope', '--dry-run'
 ]);
 
 const FINALIZATION_FLAGS = new Set(['--agent']);
@@ -403,7 +912,7 @@ const FINALIZATION_FLAGS = new Set(['--agent']);
 const ORCHESTRATION_FLAGS = new Set([
   '--agent', '--max-steps', '--executor-model', '--executor-reasoning-effort', '--reviewer-model',
   '--reviewer-reasoning-effort', '--client', '--requested-model', '--requested-reasoning-effort',
-  '--capability-token', '--parent-id', '--before-fingerprint', '--stage', '--round', '--artifact', '--role',
+  '--capability-ref', '--parent-id', '--before-fingerprint', '--stage', '--round', '--artifact', '--role',
   '--native-agent', '--child-id', '--spawn-mode', '--actual-model', '--actual-reasoning-effort',
   '--model-fallback-reason', '--reasoning-effort-fallback-reason', '--exit-code', '--after-fingerprint',
   '--changed-paths', '--code', '--message', '--recoverable', '--git-worktree-root'
@@ -475,8 +984,29 @@ export function parseTaskControlOperation(
       ...(value(values, '--override-scope') ? { overrideScope: value(values, '--override-scope') } : {}),
       ...(value(values, '--alert-number') ? { alertNumber: Number(value(values, '--alert-number')) } : {}),
       ...(value(values, '--issue-number') ? { issueNumber: Number(value(values, '--issue-number')) } : {}),
+      ...(value(values, '--stage') ? { stage: value(values, '--stage') } : {}),
+      ...(value(values, '--round') ? { round: Number(value(values, '--round')) } : {}),
+      ...(value(values, '--artifact') ? { artifact: value(values, '--artifact') } : {}),
       ...(values['--dry-run'] === true ? { dryRun: true } : {})
     };
+    if (intent === 'recover-started') {
+      const recoveryFlags = new Set(['--agent', '--stage', '--round', '--artifact', '--reason']);
+      for (const flag of Object.keys(values)) {
+        if (!recoveryFlags.has(flag)) operationInvalid(`option '${flag}' is not supported for recover-started`);
+      }
+      required(values, ['--stage', '--round', '--artifact', '--reason']);
+      const stage = value(values, '--stage');
+      if (!['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'].includes(stage ?? '')) {
+        operationInvalid('--stage must be a supported lifecycle stage');
+      }
+      const round = Number(value(values, '--round'));
+      if (!Number.isSafeInteger(round) || round < 1) operationInvalid('--round must be a positive integer');
+      if (value(values, '--reason')!.includes('\n') || value(values, '--reason')!.includes('\r')) {
+        operationInvalid('--reason must be a single line');
+      }
+    } else if (values['--stage'] !== undefined || values['--round'] !== undefined || values['--artifact'] !== undefined) {
+      operationInvalid('--stage, --round, and --artifact are only supported for recover-started');
+    }
     return { family, request: input as unknown as TaskLifecycleControlRequest };
   }
 
@@ -519,7 +1049,7 @@ export function parseTaskControlOperation(
   if (parsedIntent === 'prepare') {
     input.requestedModel = value(values, '--requested-model');
     input.requestedReasoningEffort = value(values, '--requested-reasoning-effort');
-    input.capabilityToken = value(values, '--capability-token');
+    input.capabilityRef = value(values, '--capability-ref');
   }
   if (parsedIntent === 'await-activation') {
     required(values, ['--stage', '--round', '--artifact', '--role']);