@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/lib/task/events.ts

@@ -4,14 +4,13 @@ import path from 'node:path';
 import { appendActivityEntry, locateActivityLog, pairEntries, startedBackedRows } from './activity-log.ts';
 import {
   buildArtifactLinkSection,
-  artifactName,
   inspectArtifactDirectory,
   parseReviewedInputReference,
   parseCodePlanInputReference,
-  parseArtifactName,
   resolveArtifactContext,
   validateCompletedArtifact
 } from './artifact-lifecycle.ts';
+import { artifactName, parseArtifactName } from './artifact-name.ts';
 import type { ArtifactContextResult, ArtifactErrorCode, ArtifactFamily, ArtifactIdentity } from './artifact-lifecycle.ts';
 import { ArtifactReceiptError, parseArtifactReceipts, sha256File, upsertArtifactReceipt } from './artifact-receipts.ts';
 import type { ArtifactReceipt } from './artifact-receipts.ts';
@@ -39,6 +38,9 @@ import {
   readLocalArtifactFinalizationIntent,
   validateLocalArtifact
 } from './local-artifact-finalization.ts';
+import { writeArtifactRecoveryIntent, readArtifactRecoveryIntent } from './artifact-repair-intent.ts';
+import { reconcileArtifactRecovery, recoveryContextFromIntent, sha256Content } from './artifact-recovery.ts';
+import type { ArtifactRecoveryIntent } from './artifact-repair-intent.ts';
 import type { LocalArtifactFamily, LocalArtifactFinalizationIntent } from './local-artifact-finalization.ts';
 import { buildLifecycleFacts, canStart } from './capabilities.ts';
 import type { ExplicitTrigger, LifecycleAction, TriggerInitiator, TriggerReason } from './capabilities.ts';
@@ -48,7 +50,14 @@ import { consumeReworkIntents, parseReworkIntentDocument, reworkIntentMutation,
 import { ARTIFACT_FAMILIES, expectedQualificationRelations, parseQualificationAudit, parseTaskQualification, upstreamArtifactDigest, validateQualificationAudit } from './qualification-audit.ts';
 import type { QualificationAudit, UpstreamRelation } from './qualification-audit.ts';
 import { getArtifactSchema } from './artifact-schema.ts';
-import { inspectArtifactContract } from './artifact-operations.ts';
+import { canonicalSemanticDigest, inspectArtifactContract } from './artifact-operations.ts';
+import {
+  consumeLifecycleRecoveryAttestation,
+  lifecycleRecoveryAttestationDigest,
+  validateLifecycleRecoveryAttestation,
+  type LifecycleRecoveryAttestationV1
+} from './control-authority.ts';
+import { readManualValidationCompletion } from './manual-validation-completion.ts';
 
 const eventCatalog = [
   'analyze.started', 'analyze.awaiting-input', 'analyze.completed',
@@ -69,6 +78,10 @@ type TaskEventErrorCode =
   | 'EVENT_LOG_CONFLICT' | 'EVENT_ARTIFACT_CONFLICT' | 'EVENT_FINDING_COUNT_MISMATCH'
   | 'EVENT_VERDICT_INVALID'
   | 'EVENT_ORCHESTRATION_COMMIT_FAILED'
+  | 'MANUAL_VALIDATION_RECEIPT_MISSING' | 'MANUAL_VALIDATION_RECEIPT_INVALID'
+  | 'MANUAL_VALIDATION_RECEIPT_IDENTITY_MISMATCH'
+  | 'MANUAL_VALIDATION_TRANSACTION_MISSING' | 'MANUAL_VALIDATION_TRANSACTION_INVALID'
+  | 'MANUAL_VALIDATION_TRANSACTION_IDENTITY_MISMATCH' | 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID'
   | ArtifactErrorCode | TaskWriteErrorCode;
 type TaskEventRequest = {
   taskRef: string; event: TaskEventName | string; agent: string; dryRun?: boolean; orchestrated?: boolean;
@@ -80,11 +93,14 @@ type TaskEventRequest = {
   verdict?: Verdict; blockers?: number; major?: number; minor?: number;
   manualValidation?: number; filesModified?: number; testsPassed?: number;
   summaryResult?: string;
+  transactionId?: string; receiptDigest?: string; prHeadSha?: string;
 };
 type TaskEventError = { code: TaskEventErrorCode; message: string };
 type TaskEventOptions = TaskWriteOptions & {
   commitOrchestrationCompletion?: (plan: OrchestrationStageCompletion) => void;
   lockAlreadyHeld?: boolean;
+  lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
+  deferLifecycleRecoveryConsumption?: boolean;
 };
 type TaskEventResult = {
   status: 'planned' | 'applied' | 'no-op' | 'failed'; changed: boolean;
@@ -112,8 +128,8 @@ const SCHEMAS: Record<TaskEventName, { required?: string[]; optional?: string[]
   'code.completed': { required: ['artifact', 'artifactSha256', 'semanticDigest'], optional: ['round', 'fixFor', 'implementationInput', 'filesModified', 'testsPassed', 'blockers', 'major', 'minor', 'manualValidation', 'orchestrated'] },
   'review-code.started': { optional: ['round'] },
   'review-code.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
-  'manual-validation.started': { optional: ['round'] },
-  'manual-validation.completed': { required: ['artifact', 'summaryResult'], optional: ['round'] },
+  'manual-validation.started': { optional: ['round', 'transactionId'] },
+  'manual-validation.completed': { required: ['artifact', 'summaryResult', 'transactionId', 'receiptDigest', 'prHeadSha'], optional: ['round'] },
   'validation-run.started': { optional: ['round'] },
   'validation-run.completed': { required: ['artifact'], optional: ['round'] }
 };
@@ -146,12 +162,23 @@ function validateTaskEventRequest(request: TaskEventRequest): TaskEventError | n
     const forbidden = fix ? ['filesModified', 'testsPassed'] : ['fixFor', 'blockers', 'major', 'minor', 'manualValidation'];
     if (modeRequired.some((key) => request[key as keyof TaskEventRequest] === undefined) || forbidden.some((key) => request[key as keyof TaskEventRequest] !== undefined)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'code.completed requires either initial or fix completion payload' };
   }
-  if (request.fixFor && !/^review-code(?:-r(?:[2-9]|[1-9]\d+))?\.md$/.test(request.fixFor)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'fixFor must reference a canonical review-code artifact' };
+  if (request.fixFor && parseArtifactName(request.fixFor)?.family !== 'review-code') return { code: 'EVENT_PAYLOAD_INVALID', message: 'fixFor must reference a canonical review-code artifact' };
   if (request.implementationInput && !/^II-[1-9]\d*$/.test(request.implementationInput)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'implementationInput must be a canonical II-N id' };
   if (request.artifactSha256 !== undefined && !/^[0-9a-f]{64}$/i.test(request.artifactSha256)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'artifactSha256 must be a 64-character hexadecimal digest' };
   if (request.semanticDigest !== undefined && !/^[0-9a-f]{64}$/i.test(request.semanticDigest)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'semanticDigest must be a 64-character hexadecimal digest' };
   if (request.fixFor && request.implementationInput) return { code: 'EVENT_PAYLOAD_INVALID', message: 'fixFor and implementationInput are mutually exclusive' };
   if (request.summaryResult !== undefined && (!request.summaryResult.trim() || /[\r\n]/.test(request.summaryResult))) return { code: 'EVENT_PAYLOAD_INVALID', message: 'summaryResult must be a non-empty single line' };
+  if (request.event === 'manual-validation.completed') {
+    for (const [name, value, pattern] of [
+      ['transactionId', request.transactionId, /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u],
+      ['receiptDigest', request.receiptDigest, /^[a-f0-9]{64}$/u],
+      ['prHeadSha', request.prHeadSha, /^[a-f0-9]{40}$/u]
+    ] as const) if (!value || !pattern.test(value)) return { code: 'EVENT_PAYLOAD_INVALID', message: `manual-validation.completed requires a valid ${name}` };
+  }
+  if (request.event === 'manual-validation.started' && request.transactionId !== undefined
+    && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(request.transactionId)) {
+    return { code: 'EVENT_PAYLOAD_INVALID', message: 'manual-validation.started requires a valid transactionId' };
+  }
   if (request.event !== 'analyze.awaiting-input' && /\.(?:started|completed)$/.test(request.event)) {
     if (!request.initiator || !request.requestId || !request.reasonCode) {
       return { code: 'EVENT_TRIGGER_REQUIRED', message: `${request.event} requires --initiator, --request-id, and --reason-code` };
@@ -254,7 +281,9 @@ function identity(request: TaskEventRequest) {
   if (family === 'manual-validation') {
     return {
       family, phase, action: spec.label,
-      note: phase === 'started' ? 'started' : `Manual validation passed → ${request.artifact}; ${request.summaryResult}`,
+      note: phase === 'started'
+        ? `started${request.transactionId ? `; transaction=${request.transactionId}` : ''}`
+        : `Manual validation passed → ${request.artifact}; ${request.summaryResult}; transaction=${request.transactionId}; receipt=${request.receiptDigest}; head=${request.prHeadSha}`,
       target: null
     } as const;
   }
@@ -303,6 +332,28 @@ function normalizeStarted(request: TaskEventRequest, repoRoot: string): { reques
   return { request: { ...request, round, artifact: context.next.name, fixFor: expectedFix, implementationInput: expectedImplementation }, context };
 }
 
+function validateManualValidationCompletion(
+  taskDir: string,
+  taskId: string,
+  request: TaskEventRequest,
+  artifactPath: string
+): TaskEventError | null {
+  const completion = readManualValidationCompletion(taskDir, {
+    transactionId: request.transactionId,
+    taskId,
+    prHeadSha: request.prHeadSha,
+    artifact: request.artifact,
+    receiptDigest: request.receiptDigest
+  });
+  if (!completion.ok) return completion.error;
+  const { receipt, transaction } = completion.value;
+  if (!['receipt-committed', 'final-promotion-in-progress', 'committed'].includes(transaction.phase)) {
+    return { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: 'manual validation completion requires the receipt-backed transaction phase' };
+  }
+  if (sha256File(artifactPath) !== receipt.artifactSha256) return { code: 'MANUAL_VALIDATION_RECEIPT_INVALID', message: 'manual-validation artifact digest does not match the receipt' };
+  return null;
+}
+
 function openStartedIdentity(rows: ReturnType<typeof pairEntries>, family: EventFamily) {
   const spec = FAMILY[family];
   if (family === 'manual-validation') {
@@ -324,6 +375,67 @@ function reviewInputFamily(family: EventFamily): ArtifactFamily {
   return family === 'review-analysis' ? 'analysis' : family === 'review-plan' ? 'plan' : 'code';
 }
 
+function reconcileReviewCompletionReplay(
+  repoRoot: string,
+  taskDir: string,
+  taskId: string,
+  family: EventFamily,
+  artifact: string,
+  round: number
+): TaskEventError | null {
+  const stage = REVIEW_LEDGER_STAGES[family];
+  if (!stage) return null;
+  const reviewFamily = family as 'review-analysis' | 'review-plan' | 'review-code';
+  try {
+    let intent = readArtifactRecoveryIntent(repoRoot, taskId, reviewFamily, artifact);
+    if (!intent) return null;
+    if (intent.state === 'commit-started') {
+      const reconciled = reconcileArtifactRecovery(
+        recoveryContextFromIntent(repoRoot, taskDir, intent),
+        { lockAlreadyHeld: true }
+      );
+      if (reconciled.status !== 'passed' && reconciled.status !== 'consumed') {
+        return {
+          code: 'EVENT_ARTIFACT_CONFLICT',
+          message: `review finalizer recovery remains ${reconciled.status} for ${artifact}`
+        };
+      }
+      intent = reconciled.intent;
+    }
+    if (!['passed', 'consumed'].includes(intent.state)) {
+      return {
+        code: 'EVENT_ARTIFACT_CONFLICT',
+        message: `review finalizer provenance is incomplete for ${artifact}`
+      };
+    }
+    const validated = validateCompletedArtifact(taskDir, FAMILY[family].artifact, artifact, round);
+    if (!validated.ok) {
+      return { code: 'EVENT_ARTIFACT_CONFLICT', message: validated.error.message };
+    }
+    const content = fs.readFileSync(validated.artifact.path, 'utf8');
+    const expectedRequestId = `review-finalize:${taskId}:${stage}:${round}`;
+    if (intent.round !== round
+      || intent.requestId !== expectedRequestId
+      || intent.finalArtifactSha256 !== sha256Content(content)
+      || intent.finalSemanticDigest !== canonicalSemanticDigest(content)) {
+      return {
+        code: 'EVENT_ARTIFACT_CONFLICT',
+        message: `review finalizer provenance does not match ${artifact}`
+      };
+    }
+    if (intent.state === 'passed') {
+      const consumed = { ...intent, state: 'consumed' as const, updatedAt: Date.now() };
+      writeArtifactRecoveryIntent(repoRoot, consumed, { expected: intent });
+    }
+    return null;
+  } catch (error) {
+    return {
+      code: 'EVENT_ARTIFACT_CONFLICT',
+      message: `review finalizer recovery could not be reconciled for ${artifact}: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+}
+
 function relationForStartedInput(family: EventFamily, input: ArtifactIdentity): UpstreamRelation['relation'] {
   if (family.startsWith('review-')) {
     return input.family === reviewInputFamily(family) ? 'reviewed-input' : 'approval-context';
@@ -626,6 +738,10 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
     if (openIdentity && 'conflict' in openIdentity) return failed(request, { code: 'EVENT_LOG_CONFLICT', message: 'artifact family has more than one open started event' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
     if (openIdentity) {
       if (openIdentity.row.agent !== request.agent) return failed(request, { code: 'EVENT_LOG_CONFLICT', message: 'open started event has a different agent' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+      if (initialParts.family === 'manual-validation' && request.transactionId !== undefined) {
+        const existingTransactionId = /(?:^|;\s*)transaction=([A-Za-z0-9][A-Za-z0-9._-]{0,127})(?:;|$)/u.exec(openIdentity.row.note)?.[1];
+        if (existingTransactionId !== undefined && existingTransactionId !== request.transactionId) return failed(request, { code: 'EVENT_LOG_CONFLICT', message: 'open manual-validation started event has a different transactionId' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+      }
       if (request.round !== undefined && request.round !== openIdentity.round) return failed(request, { code: 'EVENT_ARTIFACT_CONFLICT', message: `round ${request.round} conflicts with open round ${openIdentity.round}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
       if (request.fixFor !== undefined && request.fixFor !== openIdentity.fixFor) return failed(request, { code: 'EVENT_ARTIFACT_CONFLICT', message: `fixFor '${request.fixFor}' conflicts with open event` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
       if (request.implementationInput !== openIdentity.implementationInput) return failed(request, { code: 'EVENT_ARTIFACT_CONFLICT', message: `implementationInput '${request.implementationInput ?? ''}' conflicts with open event` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
@@ -641,6 +757,23 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
     if (identity?.family === FAMILY[initialParts.family].artifact) normalized = { ...request, round: identity.round };
   }
   const eventIdentity = identity(normalized);
+  const lifecycleAuthority = options.lifecycleRecoveryAttestation ?? null;
+  if (lifecycleAuthority) {
+    try { validateLifecycleRecoveryAttestation(lifecycleAuthority); }
+    catch (error) {
+      return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: error instanceof Error ? error.message : String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    }
+    const expectedFamily = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
+    if (eventIdentity.phase !== 'completed'
+      || lifecycleAuthority.phase !== 'task-event.completed'
+      || lifecycleAuthority.taskId !== resolved.taskId
+      || lifecycleAuthority.family !== expectedFamily
+      || lifecycleAuthority.artifact !== normalized.artifact
+      || lifecycleAuthority.round !== normalized.round
+      || (normalized.requestId !== undefined && lifecycleAuthority.lifecycleRequestId !== normalized.requestId)) {
+      return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: 'lifecycle completion authority does not match the event tuple' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    }
+  }
   const currentStep = typeof frontmatter.current_step === 'string' ? frontmatter.current_step : '';
   const matchingRows = rows.filter((item) => item.step === eventIdentity.action);
   const manual = eventIdentity.family === 'manual-validation';
@@ -650,21 +783,50 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   const row = manual ? openRows.at(-1) : matchingRows[0];
   let completedArtifact: ArtifactIdentity | null = null;
   let localFinalizationIntent: LocalArtifactFinalizationIntent | null = null;
+  let reviewFinalizationIntent: ArtifactRecoveryIntent | null = null;
+  let reviewContent: string | null = null;
   if (eventIdentity.phase === 'started' && row) {
     if (row.agent !== normalized.agent) return failed(normalized, { code: 'EVENT_LOG_CONFLICT', message: 'open started event has a different agent' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    if (manual && normalized.transactionId !== undefined) {
+      const existingTransactionId = /(?:^|;\s*)transaction=([A-Za-z0-9][A-Za-z0-9._-]{0,127})(?:;|$)/u.exec(row.note)?.[1];
+      if (existingTransactionId !== undefined && existingTransactionId !== normalized.transactionId) {
+        return failed(normalized, { code: 'EVENT_LOG_CONFLICT', message: 'open manual-validation started event has a different transactionId' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+      }
+    }
     return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, row.started, frontmatter, artifactContext);
   }
   if (eventIdentity.phase === 'started' && !manual && completedRows.length > 0) return failed(normalized, { code: 'EVENT_ALREADY_COMPLETED', message: 'event identity is already completed' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
   const done = completedRows.find((item) => item.note === eventIdentity.note);
-  if (eventIdentity.phase === 'completed' && done) return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, done.done, frontmatter, artifactContext);
+  if (eventIdentity.phase === 'completed' && done) {
+    if (!normalized.dryRun && eventIdentity.family.startsWith('review-') && normalized.artifact && normalized.round) {
+      const recoveryError = reconcileReviewCompletionReplay(
+        resolved.repoRoot,
+        resolved.taskDir,
+        resolved.taskId,
+        eventIdentity.family,
+        normalized.artifact,
+        normalized.round
+      );
+      if (recoveryError) return failed(normalized, recoveryError, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    }
+    return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, done.done, frontmatter, artifactContext);
+  }
   if (eventIdentity.phase === 'completed' && completedRows.length > 0 && openRows.length === 0) return failed(normalized, { code: 'EVENT_LOG_CONFLICT', message: 'event identity is already completed with a different payload' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
   if (eventIdentity.phase === 'completed' && !row?.started && !allowsManualOverride(options.manualOverride, 'task-event', 'EVENT_START_MISSING')) return failed(normalized, { code: 'EVENT_START_MISSING', message: 'completion requires one open matching started event' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
   if (eventIdentity.phase === 'completed') {
     const validated = validateCompletedArtifact(resolved.taskDir, FAMILY[eventIdentity.family].artifact, normalized.artifact!, normalized.round);
     if (!validated.ok) return failed(normalized, validated.error, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
     completedArtifact = validated.artifact;
+    if (eventIdentity.family === 'manual-validation') {
+      const validationError = validateManualValidationCompletion(
+        resolved.taskDir,
+        resolved.taskId,
+        normalized,
+        completedArtifact.path
+      );
+      if (validationError) return failed(normalized, validationError, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    }
     if (eventIdentity.family.startsWith('review-')) {
-      let reviewContent: string;
       try { reviewContent = fs.readFileSync(completedArtifact.path, 'utf8'); }
       catch (error) {
         return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `cannot read qualification audit from ${completedArtifact.name}: ${error instanceof Error ? error.message : String(error)}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
@@ -691,6 +853,23 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
       const localFamily = eventIdentity.family === 'analyze'
         ? 'analysis'
         : eventIdentity.family === 'plan' ? 'plan' : 'code';
+      try {
+        localFinalizationIntent = readLocalArtifactFinalizationIntent(
+          resolved.repoRoot, resolved.taskId, localFamily, completedArtifact.name
+        );
+        if (localFinalizationIntent?.state === 'commit-started') {
+          const reconciled = reconcileArtifactRecovery(
+            recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, localFinalizationIntent),
+            { lockAlreadyHeld: true }
+          );
+          if (reconciled.status === 'passed' || reconciled.status === 'consumed') localFinalizationIntent = reconciled.intent;
+        }
+      } catch (error) {
+        return failed(normalized, {
+          code: 'EVENT_ARTIFACT_CONFLICT',
+          message: `local finalizer recovery could not be reconciled for ${completedArtifact.name}: ${error instanceof Error ? error.message : String(error)}`
+        }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+      }
       let artifactContent: string;
       try { artifactContent = fs.readFileSync(completedArtifact.path, 'utf8'); }
       catch (error) {
@@ -720,28 +899,29 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
           message: `semantic digest does not match finalizer result for ${completedArtifact.name}`
         }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
       }
-      try {
-        localFinalizationIntent = readLocalArtifactFinalizationIntent(
-          resolved.repoRoot, resolved.taskId, localFamily, completedArtifact.name
-        );
-      } catch (error) {
-        return failed(normalized, {
-          code: 'EVENT_ARTIFACT_CONFLICT',
-          message: `cannot read local finalizer provenance for ${completedArtifact.name}: ${error instanceof Error ? error.message : String(error)}`
-        }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
-      }
       if (!localFinalizationIntent || !['passed', 'consumed'].includes(localFinalizationIntent.state)) {
         return failed(normalized, {
           code: 'EVENT_ARTIFACT_CONFLICT',
           message: `local finalizer provenance is missing or incomplete for ${completedArtifact.name}`
         }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
       }
-      if (localFinalizationIntent.artifactSha256 !== actualSha256 || localFinalizationIntent.semanticDigest !== local.semanticDigest) {
+      if (localFinalizationIntent.finalArtifactSha256 !== actualSha256 || localFinalizationIntent.finalSemanticDigest !== local.semanticDigest) {
         return failed(normalized, {
           code: 'EVENT_ARTIFACT_CONFLICT',
           message: `local finalizer provenance does not match ${completedArtifact.name}`
         }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
       }
+      if (localFinalizationIntent.authorityDigest !== null) {
+        if (!lifecycleAuthority
+          || localFinalizationIntent.recoveryOperationId !== lifecycleAuthority.operationId
+          || localFinalizationIntent.requestId !== lifecycleAuthority.lifecycleRequestId
+          || localFinalizationIntent.authorityDigest !== lifecycleRecoveryAttestationDigest(lifecycleAuthority)) {
+          return failed(normalized, {
+            code: 'EVENT_ARTIFACT_CONFLICT',
+            message: `local finalizer provenance does not match lifecycle completion authority for ${completedArtifact.name}`
+          }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+        }
+      }
     }
   }
   if (eventIdentity.phase === 'waiting' && section.entries.some((entry) => entry.step === eventIdentity.action && entry.note === eventIdentity.note)) {
@@ -768,6 +948,49 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
     completedArtifact?.path ?? null
   );
   if (findingCountError) return failed(normalized, findingCountError, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+  if (eventIdentity.phase === 'completed' && eventIdentity.family.startsWith('review-') && completedArtifact && reviewContent !== null) {
+    try {
+      reviewFinalizationIntent = readArtifactRecoveryIntent(
+        resolved.repoRoot,
+        resolved.taskId,
+        eventIdentity.family as 'review-analysis' | 'review-plan' | 'review-code',
+        completedArtifact.name
+      );
+      if (!normalized.dryRun && reviewFinalizationIntent?.state === 'commit-started') {
+        const reconciled = reconcileArtifactRecovery(
+          recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, reviewFinalizationIntent),
+          { lockAlreadyHeld: true }
+        );
+        if (reconciled.status === 'passed' || reconciled.status === 'consumed') reviewFinalizationIntent = reconciled.intent;
+      }
+      if (!reviewFinalizationIntent || !['passed', 'consumed'].includes(reviewFinalizationIntent.state)) {
+        return failed(normalized, {
+          code: 'EVENT_ARTIFACT_CONFLICT',
+          message: `review finalizer provenance is missing or incomplete for ${completedArtifact.name}`
+        }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+      }
+      const reviewStage = eventIdentity.family === 'review-analysis'
+        ? 'analysis'
+        : eventIdentity.family === 'review-plan' ? 'plan' : 'code';
+      const actualSha256 = sha256File(completedArtifact.path);
+      const actualSemanticDigest = canonicalSemanticDigest(reviewContent);
+      const expectedRequestId = `review-finalize:${resolved.taskId}:${reviewStage}:${normalized.round}`;
+      if (reviewFinalizationIntent.round !== normalized.round
+        || reviewFinalizationIntent.requestId !== expectedRequestId
+        || reviewFinalizationIntent.finalArtifactSha256 !== actualSha256
+        || reviewFinalizationIntent.finalSemanticDigest !== actualSemanticDigest) {
+        return failed(normalized, {
+          code: 'EVENT_ARTIFACT_CONFLICT',
+          message: `review finalizer provenance does not match ${completedArtifact.name}`
+        }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+      }
+    } catch (error) {
+      return failed(normalized, {
+        code: 'EVENT_ARTIFACT_CONFLICT',
+        message: `review finalizer recovery could not be reconciled for ${completedArtifact.name}: ${error instanceof Error ? error.message : String(error)}`
+      }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    }
+  }
   let orchestrationCompletion: OrchestrationStageCompletion | null = null;
   if (eventIdentity.phase === 'completed' && eventIdentity.family !== 'manual-validation' && eventIdentity.family !== 'validation-run') {
     const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
@@ -887,13 +1110,51 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
     });
   }
   mutations.push({ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body });
-  if (!normalized.dryRun && localFinalizationIntent && completedArtifact && localFinalizationIntent.state === 'passed') {
+  if (!normalized.dryRun && localFinalizationIntent && completedArtifact) {
+    try {
+      if (lifecycleAuthority && localFinalizationIntent.state === 'passed') {
+        const expectedIntent = localFinalizationIntent;
+        localFinalizationIntent = {
+          ...localFinalizationIntent,
+          state: 'commit-started',
+          phase: 'task-event.completed',
+          authorityDigest: lifecycleRecoveryAttestationDigest(lifecycleAuthority),
+          requestId: lifecycleAuthority.lifecycleRequestId,
+          updatedAt: Date.now()
+        };
+        writeArtifactRecoveryIntent(resolved.repoRoot, localFinalizationIntent, { expected: expectedIntent });
+      } else if (!lifecycleAuthority && localFinalizationIntent.state === 'passed') {
+        localFinalizationIntent = consumeLocalArtifactFinalizationIntent(resolved.repoRoot, localFinalizationIntent, { lockAlreadyHeld: options.lockAlreadyHeld });
+      }
+    } catch (error) {
+      return failed(normalized, {
+        code: 'EVENT_ARTIFACT_CONFLICT',
+        message: `local finalizer provenance could not be advanced before task write for ${completedArtifact.name}: ${error instanceof Error ? error.message : String(error)}`
+      }, {
+        taskId: resolved.taskId,
+        taskMdPath: resolved.taskMdPath,
+        fromStep: currentStep,
+        toStep: step,
+        action: eventIdentity.action,
+        phase: eventIdentity.phase,
+        artifactContext
+      });
+    }
+  }
+  if (!normalized.dryRun && reviewFinalizationIntent && completedArtifact && reviewFinalizationIntent.state === 'passed') {
     try {
-      localFinalizationIntent = consumeLocalArtifactFinalizationIntent(resolved.repoRoot, localFinalizationIntent);
+      const expectedIntent = reviewFinalizationIntent;
+      reviewFinalizationIntent = {
+        ...reviewFinalizationIntent,
+        state: 'commit-started',
+        phase: 'task-event.completed',
+        updatedAt: Date.now()
+      };
+      writeArtifactRecoveryIntent(resolved.repoRoot, reviewFinalizationIntent, { expected: expectedIntent });
     } catch (error) {
       return failed(normalized, {
         code: 'EVENT_ARTIFACT_CONFLICT',
-        message: `local finalizer provenance could not be consumed before task write for ${completedArtifact.name}: ${error instanceof Error ? error.message : String(error)}`
+        message: `review finalizer provenance could not be advanced before task write for ${completedArtifact.name}: ${error instanceof Error ? error.message : String(error)}`
       }, {
         taskId: resolved.taskId,
         taskMdPath: resolved.taskMdPath,
@@ -909,6 +1170,30 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
     && ['analyze', 'plan', 'code'].includes(eventIdentity.family);
   const result = writeTask({ taskRef: normalized.taskRef, expectedState: stateOverride ? resolved.state : 'active', dryRun: normalized.dryRun, mutations }, { ...options, invalidationContext: sourceCompletion ? 'source-completion' : 'standard', metadataProvider: () => metadata });
   if (result.status === 'failed') return failed(normalized, result.error, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
+  if (!normalized.dryRun && lifecycleAuthority && localFinalizationIntent && completedArtifact) {
+    try {
+      if (!options.deferLifecycleRecoveryConsumption) consumeLifecycleRecoveryAttestation(lifecycleAuthority);
+      writeArtifactRecoveryIntent(resolved.repoRoot, { ...localFinalizationIntent, state: 'consumed', updatedAt: Date.now() }, { expected: localFinalizationIntent });
+    } catch (error) {
+      return failed(normalized, {
+        code: 'EVENT_ARTIFACT_CONFLICT',
+        message: `task completion was written but lifecycle recovery consumption is incomplete: ${error instanceof Error ? error.message : String(error)}`
+      }, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
+    }
+  }
+  if (!normalized.dryRun && reviewFinalizationIntent && completedArtifact) {
+    try {
+      if (reviewFinalizationIntent.state === 'commit-started') {
+        const consumed = { ...reviewFinalizationIntent, state: 'consumed' as const, updatedAt: Date.now() };
+        writeArtifactRecoveryIntent(resolved.repoRoot, consumed, { expected: reviewFinalizationIntent });
+      }
+    } catch (error) {
+      return failed(normalized, {
+        code: 'EVENT_ARTIFACT_CONFLICT',
+        message: `review finalizer recovery consumption is incomplete: ${error instanceof Error ? error.message : String(error)}`
+      }, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
+    }
+  }
   if (!normalized.dryRun && orchestrationCompletion) {
     try {
       (options.commitOrchestrationCompletion ?? commitOrchestrationStageCompletion)(orchestrationCompletion);
@@ -956,7 +1241,7 @@ function applyTaskEvent(request: TaskEventRequest, options: TaskEventOptions = {
       resolved.repoRoot,
       resolved.taskId,
       `task-event.${request.event}`,
-      () => applyTaskEventUnlocked(request, options)
+      () => applyTaskEventUnlocked(request, { ...options, lockAlreadyHeld: true })
     );
   } catch (error) {
     if (!(error instanceof TaskExecutionLockError)) throw error;

package/lib/task/finalization-state.ts

@@ -0,0 +1,11 @@
+import type { TaskFinalizationReceipt } from './finalization.ts';
+
+export type TaskControlBinding = NonNullable<TaskFinalizationReceipt['controlBinding']>;
+export type TaskControlBindingEvidence = (taskId: string, binding: TaskControlBinding) => 'terminal' | 'pending' | 'mismatch';
+
+export function taskFinalizationReceiptState(receipt: TaskFinalizationReceipt): 'pending' | 'unresolved' | 'complete' {
+  if (receipt.lifecycle !== 'done' || receipt.taskComment === 'pending'
+    || receipt.verification === 'pending' || receipt.warningProjection !== 'done') return 'pending';
+  if (receipt.lastError !== null || receipt.warnings.some((warning) => warning.status === 'open')) return 'unresolved';
+  return 'complete';
+}

package/lib/task/human-override.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 
+import { parseArtifactName } from './artifact-name.ts';
 import { locateActivityLog } from './activity-log.ts';
 import { applyPrReviewActivityIntent } from './activity-intent.ts';
 import { applyHumanDecision } from './decision-intents.ts';
@@ -616,10 +617,7 @@ function resourceForSnapshot(
   if (policy.producerId === 'platform.issue') {
     const identity = options.probeIssueNumber !== undefined
       ? resourceIdentity(options.probeIssueNumber)
-      : taskIssueIdentity((frontmatter || {}) as Record<string, string | number | boolean | null>) || (() => {
-        const number = toPositiveInteger(frontmatter?.issue_number);
-        return number === null ? null : resourceIdentity(number);
-      })();
+      : taskIssueIdentity((frontmatter || {}) as Record<string, string | number | boolean | null>);
     return identity ? { kind: 'issue', identity, number: resourceIdentityNumber(identity) } : null;
   }
   if (policy.producerId === 'platform.pull-request') {
@@ -718,11 +716,11 @@ async function probePlatformFailure(
   }
   const issueIdentity = options.probeIssueNumber !== undefined
     ? resourceIdentity(options.probeIssueNumber)
-    : taskIssueIdentity(frontmatter) || (() => {
-      const number = toPositiveInteger(frontmatter.issue_number);
-      return number === null ? null : resourceIdentity(number);
-    })();
+    : taskIssueIdentity(frontmatter);
   const fact = readPrDeliveryFact(frontmatter);
+  if (fact.status === 'invalid') {
+    return error(fact.error.code, fact.error.message);
+  }
   const pullRequestIdentity = options.probePullRequestNumber !== undefined
     ? resourceIdentity(options.probePullRequestNumber)
     : fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.resource : null;
@@ -814,14 +812,8 @@ async function probeVerificationFailure(taskRef: string, policy: FailurePolicy,
 function latestArtifact(taskDir: string, family: string): string | undefined {
   let names: string[];
   try { names = fs.readdirSync(taskDir); } catch { return undefined; }
-  const candidates = names.filter((name) => (
-    name === `${family}.md` || new RegExp(`^${family}-r\\d+\\.md$`).test(name)
-  ));
-  candidates.sort((a, b) => {
-    const round = (name: string) => Number(/-r(\d+)\.md$/.exec(name)?.[1] ?? 1);
-      return round(b) - round(a);
-    });
-  return candidates[0];
+  return names.map(parseArtifactName).filter((identity) => identity !== null)
+    .filter((identity) => identity.family === family).sort((left, right) => right.round - left.round)[0]?.name;
 }
 
 async function probeVerificationEngineFailure(policy: FailurePolicy, resolved: ProbeTask): Promise<ProducerFailure | OverrideError> {

package/lib/task/implementation-inputs.ts

@@ -1,3 +1,4 @@
+import { parseArtifactName } from './artifact-name.ts';
 import { parseTable } from './sections.ts';
 
 const SECTION_ALIASES = ['实现输入', 'Implementation Inputs'] as const;
@@ -6,7 +7,6 @@ const COLUMNS = [
   'decided_at', 'status', 'consumed_by'
 ] as const;
 const TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}[+-]\d{2}:\d{2}$/;
-const ARTIFACT_RE = /^code(?:-r(?:[2-9]|[1-9]\d+))?\.md$/;
 
 type ImplementationInputStatus = 'declared' | 'pending' | 'not-required' | 'consumed';
 type ImplementationInput = {
@@ -36,7 +36,7 @@ function validateInput(row: ImplementationInput): void {
     (row.status === 'declared' && row.decidedAt === '' && row.consumedBy === '') ||
     (hasValidTimestamp && row.needsImplementation && row.status === 'pending' && row.consumedBy === '') ||
     (hasValidTimestamp && !row.needsImplementation && row.status === 'not-required' && row.consumedBy === '') ||
-    (hasValidTimestamp && row.needsImplementation && row.status === 'consumed' && ARTIFACT_RE.test(row.consumedBy));
+    (hasValidTimestamp && row.needsImplementation && row.status === 'consumed' && parseArtifactName(row.consumedBy)?.family === 'code');
   if (!valid) throw new Error(`implementation input ${row.id} has an invalid state combination`);
 }
 
@@ -143,7 +143,7 @@ function selectPendingImplementationInput(
 function consumeImplementationInput(
   rows: readonly ImplementationInput[], id: string, artifact: string
 ): ImplementationInput[] {
-  if (!ARTIFACT_RE.test(artifact)) throw new Error(`implementation input artifact '${artifact}' is invalid`);
+  if (parseArtifactName(artifact)?.family !== 'code') throw new Error(`implementation input artifact '${artifact}' is invalid`);
   let found = false;
   const next = rows.map((row) => {
     if (row.id !== id) return row;