@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/dist/lib/task/events.js

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { appendActivityEntry, locateActivityLog, pairEntries, startedBackedRows } from './activity-log.js';
-import { buildArtifactLinkSection, artifactName, inspectArtifactDirectory, parseReviewedInputReference, parseCodePlanInputReference, parseArtifactName, resolveArtifactContext, validateCompletedArtifact } from './artifact-lifecycle.js';
+import { buildArtifactLinkSection, inspectArtifactDirectory, parseReviewedInputReference, parseCodePlanInputReference, resolveArtifactContext, validateCompletedArtifact } from './artifact-lifecycle.js';
+import { artifactName, parseArtifactName } from './artifact-name.js';
 import { ArtifactReceiptError, parseArtifactReceipts, sha256File, upsertArtifactReceipt } from './artifact-receipts.js';
 import { parseTypedTaskFrontmatter } from './frontmatter.js';
 import { consumeImplementationInput, IMPLEMENTATION_INPUT_ALIASES, parseImplementationInputs, renderImplementationInputs } from './implementation-inputs.js';
@@ -15,12 +16,16 @@ import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-
 import { captureTaskWriteMetadata, writeTask } from './write.js';
 import { allowsManualOverride } from './guard-override.js';
 import { consumeLocalArtifactFinalizationIntent, readLocalArtifactFinalizationIntent, validateLocalArtifact } from './local-artifact-finalization.js';
+import { writeArtifactRecoveryIntent, readArtifactRecoveryIntent } from './artifact-repair-intent.js';
+import { reconcileArtifactRecovery, recoveryContextFromIntent, sha256Content } from './artifact-recovery.js';
 import { buildLifecycleFacts, canStart } from './capabilities.js';
 import { createInvalidationOperation, invalidationMutation, parseInvalidationDocument, targetIdFor, upsertInvalidation } from './invalidation.js';
 import { consumeReworkIntents, parseReworkIntentDocument, reworkIntentMutation, supersedeReworkIntents } from './rework-intent.js';
 import { ARTIFACT_FAMILIES, expectedQualificationRelations, parseQualificationAudit, parseTaskQualification, upstreamArtifactDigest, validateQualificationAudit } from './qualification-audit.js';
 import { getArtifactSchema } from './artifact-schema.js';
-import { inspectArtifactContract } from './artifact-operations.js';
+import { canonicalSemanticDigest, inspectArtifactContract } from './artifact-operations.js';
+import { consumeLifecycleRecoveryAttestation, lifecycleRecoveryAttestationDigest, validateLifecycleRecoveryAttestation } from './control-authority.js';
+import { readManualValidationCompletion } from './manual-validation-completion.js';
 const eventCatalog = [
     'analyze.started', 'analyze.awaiting-input', 'analyze.completed',
     'review-analysis.started', 'review-analysis.completed',
@@ -46,8 +51,8 @@ const SCHEMAS = {
     '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'] }
 };
@@ -92,7 +97,7 @@ function validateTaskEventRequest(request) {
         if (modeRequired.some((key) => request[key] === undefined) || forbidden.some((key) => request[key] !== 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))
+    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' };
@@ -104,6 +109,19 @@ function validateTaskEventRequest(request) {
         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]
+        ])
+            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` };
@@ -202,7 +220,9 @@ function identity(request) {
     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
         };
     }
@@ -257,6 +277,24 @@ function normalizeStarted(request, repoRoot) {
         return { error: { code: 'EVENT_ARTIFACT_CONFLICT', message: `implementationInput '${request.implementationInput ?? ''}' conflicts with artifact context` }, context };
     return { request: { ...request, round, artifact: context.next.name, fixFor: expectedFix, implementationInput: expectedImplementation }, context };
 }
+function validateManualValidationCompletion(taskDir, taskId, request, artifactPath) {
+    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, family) {
     const spec = FAMILY[family];
     if (family === 'manual-validation') {
@@ -277,6 +315,59 @@ function openStartedIdentity(rows, family) {
 function reviewInputFamily(family) {
     return family === 'review-analysis' ? 'analysis' : family === 'review-plan' ? 'plan' : 'code';
 }
+function reconcileReviewCompletionReplay(repoRoot, taskDir, taskId, family, artifact, round) {
+    const stage = REVIEW_LEDGER_STAGES[family];
+    if (!stage)
+        return null;
+    const reviewFamily = family;
+    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', 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, input) {
     if (family.startsWith('review-')) {
         return input.family === reviewInputFamily(family) ? 'reviewed-input' : 'approval-context';
@@ -623,6 +714,11 @@ function applyTaskEventUnlocked(request, options = {}) {
         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)
@@ -644,6 +740,25 @@ function applyTaskEventUnlocked(request, options = {}) {
             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';
@@ -654,16 +769,30 @@ function applyTaskEventUnlocked(request, options = {}) {
     const row = manual ? openRows.at(-1) : matchingRows[0];
     let completedArtifact = null;
     let localFinalizationIntent = null;
+    let reviewFinalizationIntent = null;
+    let reviewContent = 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)
+    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'))
@@ -673,8 +802,12 @@ function applyTaskEventUnlocked(request, options = {}) {
         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;
             try {
                 reviewContent = fs.readFileSync(completedArtifact.path, 'utf8');
             }
@@ -703,6 +836,20 @@ function applyTaskEventUnlocked(request, options = {}) {
             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;
             try {
                 artifactContent = fs.readFileSync(completedArtifact.path, 'utf8');
@@ -734,27 +881,29 @@ function applyTaskEventUnlocked(request, options = {}) {
                     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)) {
@@ -778,6 +927,43 @@ function applyTaskEventUnlocked(request, options = {}) {
     const findingCountError = validateReviewFindingCounts(normalized, content, eventIdentity.family, 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, 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 = null;
     if (eventIdentity.phase === 'completed' && eventIdentity.family !== 'manual-validation' && eventIdentity.family !== 'validation-run') {
         const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
@@ -914,14 +1100,54 @@ function applyTaskEventUnlocked(request, options = {}) {
         });
     }
     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,
@@ -938,6 +1164,33 @@ function applyTaskEventUnlocked(request, options = {}) {
     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', 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);
@@ -984,7 +1237,7 @@ function applyTaskEvent(request, options = {}) {
     if (!resolved.ok)
         return applyTaskEventUnlocked(request, options);
     try {
-        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-event.${request.event}`, () => applyTaskEventUnlocked(request, options));
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-event.${request.event}`, () => applyTaskEventUnlocked(request, { ...options, lockAlreadyHeld: true }));
     }
     catch (error) {
         if (!(error instanceof TaskExecutionLockError))

package/dist/lib/task/finalization-state.js

@@ -0,0 +1,9 @@
+export function taskFinalizationReceiptState(receipt) {
+    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';
+}
+//# sourceMappingURL=finalization-state.js.map

package/dist/lib/task/human-override.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
+import { parseArtifactName } from './artifact-name.js';
 import { locateActivityLog } from './activity-log.js';
 import { applyPrReviewActivityIntent } from './activity-intent.js';
 import { applyHumanDecision } from './decision-intents.js';
@@ -406,10 +407,7 @@ function resourceForSnapshot(policy, options, frontmatter) {
     if (policy.producerId === 'platform.issue') {
         const identity = options.probeIssueNumber !== undefined
             ? resourceIdentity(options.probeIssueNumber)
-            : taskIssueIdentity((frontmatter || {})) || (() => {
-                const number = toPositiveInteger(frontmatter?.issue_number);
-                return number === null ? null : resourceIdentity(number);
-            })();
+            : taskIssueIdentity((frontmatter || {}));
         return identity ? { kind: 'issue', identity, number: resourceIdentityNumber(identity) } : null;
     }
     if (policy.producerId === 'platform.pull-request') {
@@ -480,11 +478,11 @@ async function probePlatformFailure(taskRef, policy, resolved, options) {
     }
     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;
@@ -577,12 +575,8 @@ function latestArtifact(taskDir, family) {
     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) => 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, resolved) {
     const candidates = [

package/dist/lib/task/implementation-inputs.js

@@ -1,3 +1,4 @@
+import { parseArtifactName } from './artifact-name.js';
 import { parseTable } from './sections.js';
 const SECTION_ALIASES = ['实现输入', 'Implementation Inputs'];
 const COLUMNS = [
@@ -5,7 +6,6 @@ const COLUMNS = [
     'decided_at', 'status', 'consumed_by'
 ];
 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$/;
 function validateInput(row) {
     if (!/^II-[1-9]\d*$/.test(row.id))
         throw new Error(`implementation input id '${row.id}' is invalid`);
@@ -17,7 +17,7 @@ function validateInput(row) {
     const valid = (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`);
 }
@@ -122,7 +122,7 @@ function selectPendingImplementationInput(rows) {
     })[0] ?? null;
 }
 function consumeImplementationInput(rows, id, artifact) {
-    if (!ARTIFACT_RE.test(artifact))
+    if (parseArtifactName(artifact)?.family !== 'code')
         throw new Error(`implementation input artifact '${artifact}' is invalid`);
     let found = false;
     const next = rows.map((row) => {