@fitlab-ai/agent-infra 0.9.15 → 0.11.0

package/dist/lib/task/local-artifact-finalization.js

@@ -2,12 +2,13 @@ import fs from 'node:fs';
 import { inspectDecisionDetailDuplicates } from './decision-details.js';
 import { scanVisibleMarkdown } from './markdown.js';
 import { parseArtifactName } from './artifact-name.js';
-import { hasOpenArtifactRound, validateArtifactPublication, validateCompletedArtifact } from './artifact-lifecycle.js';
+import { hasOpenArtifactRound, parseCodePlanInputReference, validateArtifactPublication, validateCompletedArtifact } from './artifact-lifecycle.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { expectedQualificationRelations, validateQualificationAudit } from './qualification-audit.js';
 import { canonicalSemanticDigest, inspectArtifactPatterns, inspectArtifactStructure, sha256Content } from './artifact-operations.js';
 import { getArtifactSchema } from './artifact-schema.js';
-import { readArtifactRepairIntent, writeArtifactRepairIntent } from './artifact-repair-intent.js';
+import { readArtifactRecoveryIntent } from './artifact-repair-intent.js';
+import { beginArtifactRecovery, commitArtifactRecovery, consumeArtifactRecovery, prepareArtifactRecoveryFinal, prepareArtifactRecoveryCommit, recordArtifactRecoveryPassed, reconcileArtifactRecovery, recoveryContextFromIntent, stageArtifactCandidate } from './artifact-recovery.js';
 import { consumeLifecycleRecoveryAttestation, lifecycleRecoveryAttestationDigest, validateLifecycleRecoveryAttestation } from './control-authority.js';
 const LOCAL_ARTIFACT_REQUIRED_SECTIONS = {
     analysis: getArtifactSchema('analysis').sections.map((section) => section.headings.zh),
@@ -35,14 +36,21 @@ function validFinalizerAuthority(authority, request, taskId) {
         && authority.requestId.length > 0
         && authority.operationId.length > 0;
 }
-function consumeLocalArtifactFinalizationIntent(repoRoot, intent) {
+function recoveryInfo(context) {
+    return {
+        recoveryId: context.recoveryId,
+        candidatePath: context.stagingPath,
+        baselineSha256: context.baselineSha256,
+        baselineSemanticDigest: context.baselineSemanticDigest
+    };
+}
+function consumeLocalArtifactFinalizationIntent(repoRoot, intent, options = {}) {
     if (intent.state === 'consumed')
         return intent;
-    if (intent.state !== 'passed')
-        throw new Error('LOCAL_FINALIZATION_INTENT_INVALID: only passed provenance can be consumed');
-    const consumed = { ...intent, state: 'consumed', updatedAt: Date.now() };
-    writeArtifactRepairIntent(repoRoot, consumed, { expected: intent });
-    return consumed;
+    const resolved = resolveTaskRef(intent.taskId, { repoRoot });
+    if (!resolved.ok)
+        throw new Error(resolved.message);
+    return consumeArtifactRecovery(recoveryContextFromIntent(repoRoot, resolved.taskDir, intent), options);
 }
 function localDiagnosticCode(code) {
     const map = {
@@ -54,78 +62,56 @@ function localDiagnosticCode(code) {
     return map[code] ?? 'LOCAL_STRUCTURAL_INVALID';
 }
 function localDiagnostic(item) {
-    const code = localDiagnosticCode(item.code);
-    if (!code)
-        return null;
-    return {
-        code,
-        message: item.message,
-        repairable: item.repairable,
-        line: item.line,
-        ...(item.operation?.kind === 'replace-line'
-            ? { from: item.operation.from, to: item.operation.to, operation: 'replace-line' }
-            : {})
-    };
+    return { code: localDiagnosticCode(item.code), message: item.message, line: item.line };
 }
 function isStatusPattern(pattern) {
     return pattern === '^\\$ ';
 }
 function validateLocalArtifact(content, options) {
     const schema = getArtifactSchema(options.family);
-    const patterns = schema.requiredPatterns;
     const diagnostics = [];
     const scanned = scanVisibleMarkdown(content);
     const structure = inspectArtifactStructure(content, schema);
-    for (const item of structure.diagnostics) {
-        const mapped = localDiagnostic(item);
-        if (mapped)
-            diagnostics.push(mapped);
-    }
+    for (const item of structure.diagnostics)
+        diagnostics.push(localDiagnostic(item));
     const statusSection = schema.sections.find((section) => section.id === 'state-check');
     if (statusSection) {
         const statusHeading = scanned.headings.find((heading) => (heading.level === 2 && [statusSection.headings.zh, statusSection.headings.en].some((name) => (heading.text === name || heading.text === `${name}:` || heading.text === `${name}：`))));
         if (statusHeading) {
             const next = scanned.headings.find((candidate) => candidate.start > statusHeading.start && candidate.level <= 2);
             const body = content.slice(statusHeading.end, next?.start ?? content.length);
-            for (const pattern of patterns.filter(isStatusPattern)) {
+            for (const pattern of schema.requiredPatterns.filter(isStatusPattern)) {
                 if (!new RegExp(pattern, 'm').test(body)) {
-                    diagnostics.push({ code: 'LOCAL_STATUS_COMMAND_MISSING', message: `status section '${statusHeading.text}' is missing required command output`, repairable: false, line: content.slice(0, statusHeading.start).split('\n').length });
+                    diagnostics.push({ code: 'LOCAL_STATUS_COMMAND_MISSING', message: `status section '${statusHeading.text}' is missing required command output`, line: content.slice(0, statusHeading.start).split('\n').length });
                 }
             }
         }
     }
     const patternInspection = inspectArtifactPatterns(content, {
         ...schema,
-        requiredPatterns: patterns.filter((item) => !isStatusPattern(item))
+        requiredPatterns: schema.requiredPatterns.filter((item) => !isStatusPattern(item))
     });
-    for (const item of patternInspection.diagnostics) {
-        diagnostics.push({ code: 'LOCAL_REQUIRED_PATTERN_MISSING', message: item.message, repairable: false, line: null });
-    }
+    for (const item of patternInspection.diagnostics)
+        diagnostics.push({ code: 'LOCAL_REQUIRED_PATTERN_MISSING', message: item.message, line: null });
     const decisionDetails = inspectDecisionDetailDuplicates(content);
-    if (!decisionDetails.ok) {
-        diagnostics.push({ code: 'LOCAL_DECISION_DETAIL_DUPLICATE', message: decisionDetails.message, repairable: false, line: null });
-    }
+    if (!decisionDetails.ok)
+        diagnostics.push({ code: 'LOCAL_DECISION_DETAIL_DUPLICATE', message: decisionDetails.message, line: null });
     if (options.taskContent !== undefined) {
         const expected = expectedQualificationRelations(options.taskContent, options.family);
-        if (!expected.ok) {
-            diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${expected.code}: ${expected.message}`, repairable: false, line: null });
-        }
+        if (!expected.ok)
+            diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${expected.code}: ${expected.message}`, line: null });
         const qualification = validateQualificationAudit(options.taskContent, content, {
-            family: options.family === 'analysis' ? 'analysis' : options.family === 'plan' ? 'plan' : 'code',
+            family: options.family,
             artifact: options.artifact,
             expectedUpstreamRelations: expected.ok ? expected.relations : undefined
         });
-        if (!qualification.ok) {
-            diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${qualification.code}: ${qualification.message}`, repairable: false, line: null });
-        }
+        if (!qualification.ok)
+            diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${qualification.code}: ${qualification.message}`, line: null });
     }
-    const repairable = structure.repair !== null && diagnostics.length === 1 && diagnostics[0]?.repairable === true;
-    const semanticDigestValue = canonicalSemanticDigest(content, structure.repair);
     return {
         ok: diagnostics.length === 0,
         family: options.family,
-        semanticDigest: semanticDigestValue,
-        repairable,
+        semanticDigest: canonicalSemanticDigest(content),
         diagnostics
     };
 }
@@ -135,13 +121,24 @@ function failedFinalization(request, error, extra = {}) {
         taskId: null, taskDir: null,
         family: request.family, artifact: request.artifact,
         artifactSha256: null, semanticDigest: null,
-        repairable: false, diagnostics: [], error, ...extra
+        diagnostics: [], error, ...extra
+    };
+}
+function tupleFor(request, taskId, authority) {
+    const round = parseArtifactName(request.artifact)?.round ?? 0;
+    return {
+        taskId,
+        family: request.family,
+        artifact: request.artifact,
+        round,
+        requestId: authority?.lifecycleRequestId ?? `local-finalize:${taskId}:${request.family}:${round}`,
+        phase: authority?.phase ?? 'artifact.finalize-local',
+        authorityDigest: authority ? authorityDigest(authority) : null
     };
 }
-/** Read and validate once; callers publish this content before committing provenance. */
-function prepareLocalArtifact(request, candidate, authority) {
-    const failed = (code, message) => ({
-        result: failedFinalization(request, { code, message }), content: candidate ?? ''
+function prepareLocalArtifact(request, candidate, authority, preflightOnly = false) {
+    const failed = (code, message, extra = {}) => ({
+        result: failedFinalization(request, { code, message }, extra), content: candidate ?? ''
     });
     const resolved = resolveTaskRef(request.taskRef, { repoRoot: request.repoRoot });
     if (!resolved.ok)
@@ -149,114 +146,201 @@ function prepareLocalArtifact(request, candidate, authority) {
     const parsed = parseArtifactName(request.artifact);
     if (!parsed || parsed.family !== request.family)
         return failed('ARTIFACT_IDENTITY_INVALID', `artifact '${request.artifact}' does not match ${request.family}`);
-    let content;
+    if (authority && !validFinalizerAuthority(authority, request, resolved.taskId)) {
+        return failed('LOCAL_EXECUTION_AUTHORITY_INVALID', 'finalizer authority does not match the artifact tuple');
+    }
     let taskContent;
+    let content;
+    let recovery;
+    let recoveryState;
     try {
         taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
-        if (candidate !== undefined) {
-            const error = validateArtifactPublication(resolved.taskDir, request.family, request.artifact);
-            if (error)
-                return failed(error.code, error.message);
-            if (resolved.state !== 'active' || !hasOpenArtifactRound(taskContent, request.family, parsed.round)) {
-                return failed('ARTIFACT_IDENTITY_INVALID', 'candidate must match one open started round in an active task');
-            }
-            content = candidate;
+        if (request.recoveryId) {
+            const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
+            if (!intent || intent.recoveryOperationId !== request.recoveryId)
+                return failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'recovery id does not match the artifact journal');
+            if (!['awaiting-preflight-recovery', 'preflight-ready', 'preflight-commit-started', 'preflight-passed', 'full-finalizer-ready', 'commit-started'].includes(intent.state))
+                return failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', `recovery journal is in '${intent.state}' state`);
+            recoveryState = intent.state;
+            recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
+            content = fs.existsSync(recovery.stagingPath)
+                ? fs.readFileSync(recovery.stagingPath, 'utf8')
+                : fs.readFileSync(recovery.formalPath, 'utf8');
         }
         else {
             const validated = validateCompletedArtifact(resolved.taskDir, request.family, request.artifact, parsed.round);
             if (!validated.ok)
                 return failed(validated.error.code, validated.error.message);
-            content = fs.readFileSync(validated.artifact.path, 'utf8');
+            content = candidate ?? fs.readFileSync(validated.artifact.path, 'utf8');
         }
     }
     catch (error) {
         return failed('ARTIFACT_NOT_READABLE', String(error));
     }
+    if (resolved.state !== 'active' || !hasOpenArtifactRound(taskContent, request.family, parsed.round)) {
+        return failed('ARTIFACT_IDENTITY_INVALID', 'candidate must match one open started round in an active task');
+    }
     const validation = validateLocalArtifact(content, {
         family: request.family, requiredSections: request.requiredSections, taskContent, artifact: request.artifact
     });
     const artifactSha256 = sha256Content(content);
-    const { semanticDigest, repairable, diagnostics } = validation;
     const result = failedFinalization(request, {
-        code: 'LOCAL_ARTIFACT_INVALID', message: diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
-    }, { taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256, semanticDigest, repairable, diagnostics });
-    const preparedBase = { result, content, repoRoot: resolved.repoRoot };
-    if (authority !== undefined && !validFinalizerAuthority(authority, request, resolved.taskId)) {
+        code: 'LOCAL_ARTIFACT_INVALID',
+        message: validation.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
+    }, {
+        taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256,
+        semanticDigest: validation.semanticDigest, diagnostics: validation.diagnostics
+    });
+    if (request.recoveryId) {
+        if (!validation.ok)
+            return { result, content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+        if (preflightOnly && recovery && recoveryState === 'awaiting-preflight-recovery') {
+            const staged = stageArtifactCandidate(recovery, Buffer.from(content, 'utf8'), { lockAlreadyHeld: request.lockAlreadyHeld });
+            prepareArtifactRecoveryCommit(recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: request.lockAlreadyHeld });
+        }
         return {
-            ...preparedBase,
-            result: { ...result, repairable: false, error: {
-                    code: 'LOCAL_EXECUTION_AUTHORITY_INVALID',
-                    message: 'finalizer authority does not match the artifact tuple'
-                }, diagnostics: [] }
+            result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(recovery) },
+            content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld
         };
     }
-    const reject = (code, message) => ({
-        ...prepared, result: { ...result, repairable: false, error: { code, message },
-            diagnostics: [{ code, message, repairable: false, line: null }] }
-    });
-    let intent;
-    try {
-        intent = readArtifactRepairIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
-    }
-    catch (error) {
-        return { ...preparedBase, result: { ...result, repairable: false, diagnostics: [],
-                error: { code: 'LOCAL_FINALIZATION_INTENT_INVALID', message: String(error) } } };
+    const existing = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
+    if (existing?.state === 'passed' || existing?.state === 'consumed') {
+        if (existing.state === 'consumed' && (existing.finalArtifactSha256 !== artifactSha256 || existing.finalSemanticDigest !== validation.semanticDigest)) {
+            return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'formal artifact does not match its completed recovery journal'), content, repoRoot: resolved.repoRoot, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+        }
+        if (existing.finalArtifactSha256 === artifactSha256 && existing.finalSemanticDigest === validation.semanticDigest) {
+            const context = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, existing);
+            return {
+                result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) },
+                content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld
+            };
+        }
     }
-    const prepared = { ...preparedBase, expectedIntent: intent };
-    if (intent && intent.recoveryOperationId !== null
-        && (!authority || intent.recoveryOperationId !== authority.operationId)) {
-        return reject('LOCAL_REPAIR_PROVENANCE_CONFLICT', 'local repair provenance is owned by another recovery operation');
+    if (existing && ['preflight-ready', 'preflight-commit-started', 'preflight-passed', 'full-finalizer-ready'].includes(existing.state)) {
+        const context = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, existing);
+        return {
+            result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(context) },
+            content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld
+        };
     }
-    if (repairable) {
-        if (intent && (intent.state !== 'awaiting-repair' || intent.baselineSemanticDigest !== semanticDigest)) {
-            return reject('LOCAL_REPAIR_PROVENANCE_CONFLICT', 'a different local repair baseline is already recorded for this artifact');
+    if (existing?.state === 'commit-started') {
+        if (existing.finalArtifactSha256 !== artifactSha256 || existing.finalSemanticDigest !== validation.semanticDigest) {
+            return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'formal artifact does not match the interrupted recovery journal'), content, repoRoot: resolved.repoRoot, authority, lockAlreadyHeld: request.lockAlreadyHeld };
         }
-        if (intent && !authority)
-            return prepared;
-    }
-    else {
-        if (!validation.ok)
-            return prepared;
-        if (intent?.state === 'awaiting-repair' && intent.baselineSemanticDigest !== semanticDigest) {
-            return reject('LOCAL_REPAIR_BASELINE_MISMATCH', 'the repaired artifact semantic digest does not match the recorded repair baseline');
+        const context = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, existing);
+        const reconciled = reconcileArtifactRecovery(context, {
+            lockAlreadyHeld: request.lockAlreadyHeld,
+            validateFinal: () => validation.semanticDigest === existing.finalSemanticDigest
+        });
+        if (reconciled.status !== 'passed') {
+            return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', `interrupted recovery could not be reconciled: ${reconciled.status}`), content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld };
         }
-        if ((intent?.state === 'passed' || intent?.state === 'consumed')
-            && (intent.artifactSha256 !== artifactSha256 || intent.semanticDigest !== semanticDigest)) {
-            return reject('LOCAL_REPAIR_PROVENANCE_CONFLICT', 'the artifact changed after its finalization provenance was recorded');
+        return {
+            result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(context) },
+            content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld
+        };
+    }
+    try {
+        if (validation.ok) {
+            if (preflightOnly) {
+                const context = beginArtifactRecovery(tupleFor(request, resolved.taskId, authority), Buffer.from(content, 'utf8'), {
+                    repoRoot: resolved.repoRoot, taskDir: resolved.taskDir,
+                    ...(authority ? { recoveryId: authority.operationId } : {}), lockAlreadyHeld: request.lockAlreadyHeld
+                });
+                const staged = stageArtifactCandidate(context, Buffer.from(content, 'utf8'), { lockAlreadyHeld: request.lockAlreadyHeld });
+                prepareArtifactRecoveryCommit(context, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: request.lockAlreadyHeld });
+                return { result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) }, content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+            }
+            const context = recordArtifactRecoveryPassed(tupleFor(request, resolved.taskId, authority), {
+                repoRoot: resolved.repoRoot,
+                taskDir: resolved.taskDir,
+                expectedFinalSha256: artifactSha256,
+                expectedFinalSemanticDigest: validation.semanticDigest,
+                ...(authority ? { recoveryId: authority.operationId } : {}),
+                lockAlreadyHeld: request.lockAlreadyHeld
+            });
+            recovery = context;
+            return { result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(context) }, content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld };
         }
-        prepared.result = { ...result, status: 'passed', error: null };
-        if (intent?.state === 'consumed')
-            return prepared;
+        const context = beginArtifactRecovery(tupleFor(request, resolved.taskId, authority), Buffer.from(content, 'utf8'), {
+            repoRoot: resolved.repoRoot,
+            taskDir: resolved.taskDir,
+            ...(authority ? { recoveryId: authority.operationId } : {}),
+            lockAlreadyHeld: request.lockAlreadyHeld
+        });
+        recovery = context;
+        return {
+            result: { ...result, recovery: recoveryInfo(context) },
+            content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld
+        };
+    }
+    catch (error) {
+        return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', String(error)), content, repoRoot: resolved.repoRoot, authority, lockAlreadyHeld: request.lockAlreadyHeld };
     }
-    const timestamp = Date.now();
-    return { ...prepared, provenance: {
-            version: 2, taskId: resolved.taskId, family: request.family, artifact: request.artifact,
-            state: repairable ? 'awaiting-repair' : 'passed',
-            baselineSemanticDigest: repairable ? semanticDigest : intent?.baselineSemanticDigest ?? null,
-            artifactSha256, semanticDigest,
-            recoveryOperationId: authority?.operationId ?? intent?.recoveryOperationId ?? null,
-            phase: authority?.phase ?? intent?.phase ?? null,
-            authorityDigest: authority ? authorityDigest(authority) : intent?.authorityDigest ?? null,
-            requestId: authority?.lifecycleRequestId ?? intent?.requestId ?? `local-finalize:${resolved.taskId}`,
-            createdAt: intent?.createdAt ?? timestamp,
-            updatedAt: timestamp
-        } };
 }
-function commitLocalArtifactProvenance(prepared) {
+function commitLocalArtifactProvenance(prepared, options = {}) {
+    if (!prepared.recovery || !prepared.repoRoot || prepared.result.status === 'failed' && !prepared.result.recovery)
+        return prepared.result;
+    if (prepared.result.status === 'failed')
+        return prepared.result;
     try {
-        if (prepared.provenance) {
-            writeArtifactRepairIntent(prepared.repoRoot, prepared.provenance, { expected: prepared.expectedIntent ?? null });
+        const intent = readArtifactRecoveryIntent(prepared.repoRoot, prepared.recovery.taskId, prepared.recovery.family, prepared.recovery.artifact);
+        if (!intent)
+            throw new Error('ARTIFACT_RECOVERY_INTENT_MISSING');
+        let committed;
+        if (intent.state === 'passed' || intent.state === 'consumed') {
+            return {
+                ...prepared.result,
+                changed: false,
+                artifactSha256: intent.finalArtifactSha256,
+                semanticDigest: intent.finalSemanticDigest,
+                error: null
+            };
         }
-        return prepared.result;
+        else if (intent.state === 'commit-started') {
+            const reconciled = reconcileArtifactRecovery(prepared.recovery, {
+                lockAlreadyHeld: prepared.lockAlreadyHeld,
+                afterPublish: options.afterPublish
+            });
+            committed = reconciled.intent;
+        }
+        else if (intent.state === 'awaiting-preflight-recovery') {
+            const staged = stageArtifactCandidate(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
+            prepareArtifactRecoveryCommit(prepared.recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+        }
+        if (intent.state === 'preflight-ready' || intent.state === 'preflight-commit-started') {
+            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+        }
+        if (committed?.state === 'preflight-passed' || intent.state === 'preflight-passed') {
+            prepareArtifactRecoveryFinal(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
+            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+        }
+        else if (intent.state === 'full-finalizer-ready') {
+            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+        }
+        if (!committed || committed.state !== 'passed')
+            throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed?.state ?? intent.state}'`);
+        return {
+            ...prepared.result,
+            status: 'passed',
+            changed: false,
+            artifactSha256: committed.finalArtifactSha256,
+            semanticDigest: committed.finalSemanticDigest,
+            error: null
+        };
     }
     catch (error) {
+        if (error instanceof Error && error.message.startsWith('TASK_WORKFLOW_FAULT_INJECTED:'))
+            throw error;
         return { ...prepared.result, status: 'failed', error: {
-                code: 'LOCAL_FINALIZATION_INTENT_WRITE_FAILED', message: String(error)
+                code: 'LOCAL_RECOVERY_COMMIT_FAILED', message: String(error)
             } };
     }
 }
 function finalizeLocalArtifact(request, authority, options = {}) {
-    const result = commitLocalArtifactProvenance(prepareLocalArtifact(request, undefined, authority));
+    const prepared = prepareLocalArtifact(request, undefined, authority);
+    const result = commitLocalArtifactProvenance(prepared);
     if (authority && !options.deferLifecycleRecoveryConsumption && result.status === 'passed') {
         try {
             consumeLifecycleRecoveryAttestation(authority);
@@ -270,5 +354,10 @@ function finalizeLocalArtifact(request, authority, options = {}) {
     }
     return result;
 }
-export { LOCAL_ARTIFACT_REQUIRED_SECTIONS, consumeLocalArtifactFinalizationIntent, finalizeLocalArtifact, prepareLocalArtifact, commitLocalArtifactProvenance, readArtifactRepairIntent as readLocalArtifactFinalizationIntent, canonicalSemanticDigest as semanticDigest, sha256Content, validateLocalArtifact };
+/** Validate and seal an immutable preflight generation without publishing the formal artifact. */
+function preflightLocalArtifact(request, authority) {
+    const prepared = prepareLocalArtifact(request, undefined, authority, true);
+    return prepared.result;
+}
+export { LOCAL_ARTIFACT_REQUIRED_SECTIONS, consumeLocalArtifactFinalizationIntent, finalizeLocalArtifact, preflightLocalArtifact, prepareLocalArtifact, commitLocalArtifactProvenance, readArtifactRecoveryIntent as readLocalArtifactFinalizationIntent, canonicalSemanticDigest as semanticDigest, sha256Content, validateLocalArtifact };
 //# sourceMappingURL=local-artifact-finalization.js.map

package/dist/lib/task/manual-validation-receipt.js

@@ -28,7 +28,11 @@ function manualValidationReceiptDigest(receipt) {
 }
 function manualValidationFinalSummaryDigest(body) {
     const heading = /^###\s+✅\s+(?:Manual Validation Passed|人工验证已通过)\s*$/mu.exec(body);
-    const projection = heading ? body.slice(heading.index).replace(/\s+$/u, '') : body;
+    const afterHeading = heading ? body.slice(heading.index + heading[0].length) : '';
+    const nextSection = heading ? /^#{1,3}\s/mu.exec(afterHeading) : null;
+    const projection = heading
+        ? body.slice(heading.index, heading.index + heading[0].length + (nextSection?.index ?? afterHeading.length)).replace(/\s+$/u, '')
+        : body;
     const preimage = projection.replace(/receipt=(?:[a-f0-9]{64}|<receipt>)/gu, 'receipt=<receipt>');
     return createHash('sha256').update(preimage, 'utf8').digest('hex');
 }

package/dist/lib/task/orchestration.js

@@ -7,7 +7,7 @@ import { validateCurrentTaskContract } from './current-contract.js';
 import { parseReviewSummary } from './review-artifacts.js';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
 import { resolveTaskRef } from './resolve-ref.js';
-import { activateDelegation, abortPreparedDelegation, completeDelegationStage, consumeDelegation, dispatchDelegation, foldBlankToNull, isDelegationReceipt, managedDelegationRole, prepareDelegation, sealDelegation } from './delegation-receipts.js';
+import { activateDelegation, abortActivatedDelegation, abortPreparedDelegation, completeDelegationStage, consumeDelegation, dispatchDelegation, foldBlankToNull, isDelegationReceipt, managedDelegationRole, prepareDelegation, sealDelegation } from './delegation-receipts.js';
 import { normalizeAgentClients } from '../agent-clients/config.js';
 import { resolveAgentRuntimeStoreRoot } from '../runtime/agent-runtime.js';
 import { getAgentClientCapability, getAgentClientDelegationEvidence, getAgentClientModelSelection } from '../agent-clients/registry.js';
@@ -21,6 +21,7 @@ import { resolveDeliveryTarget, resolveDiffBase, resolveTargetHead } from './del
 import { buildLifecycleFacts, canStart, recommendNext } from './capabilities.js';
 import { hasOpenLifecycleExecution } from './activity-log.js';
 import { invalidationBlocks } from './invalidation.js';
+import { normalizeAgentToken } from '../agent-clients/tokens.js';
 function supportsLifecycleDelegation(client) {
     return getAgentClientCapability(client, 'subagents').level !== 'unsupported'
         && getAgentClientCapability(client, 'orchestration').level !== 'unsupported'
@@ -1090,6 +1091,55 @@ function recoverPreparedOrchestrationDelegation(taskRef, options = {}) {
         return failed('ORCHESTRATION_PREPARED_RECOVERY_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
 }
+function recoverActivatedOrchestrationDelegationUnderLock(taskRef, event, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failed(resolved.code, resolved.message, resolved.taskId);
+    const run = readRun(resolved.taskDir, options);
+    if (!run)
+        return failed('ORCHESTRATION_RUN_MISSING', 'no orchestration run exists', resolved.taskId);
+    const matches = [
+        ...(run.pendingDelegation ? [run.pendingDelegation] : []),
+        ...run.receipts.filter((receipt) => receipt.id === event.receiptId)
+    ];
+    const receipt = matches.find((candidate) => candidate.id === event.receiptId);
+    if (!receipt)
+        return failed('ORCHESTRATION_DELEGATION_MISSING', 'recovery receipt does not exist', resolved.taskId);
+    if (receipt.taskId !== resolved.taskId
+        || receipt.stage !== event.stage
+        || receipt.round !== event.round
+        || receipt.artifact !== event.artifact
+        || receipt.childId !== event.childId
+        || normalizeAgentToken(event.startedAgent) !== normalizeAgentToken(receipt.client)) {
+        return failed('ORCHESTRATION_PROVENANCE_MISMATCH', 'recovery selector does not match the delegation receipt', resolved.taskId);
+    }
+    if (receipt.status === 'aborted' && run.pendingDelegation === null) {
+        return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
+    }
+    if (run.pendingDelegation?.id !== receipt.id || receipt.status !== 'activated') {
+        return failed('ORCHESTRATION_RECOVERY_UNSAFE', 'recovery requires one matching activated pending delegation', resolved.taskId);
+    }
+    if (run.receipts.some((candidate) => candidate.id === receipt.id)) {
+        return failed('ORCHESTRATION_RECEIPT_DUPLICATE', 'recovery receipt already exists in the completed receipt history', resolved.taskId);
+    }
+    const aborted = abortActivatedDelegation(receipt, {
+        childId: event.childId,
+        stopRevision: event.stopRevision,
+        consumer: event.consumer,
+        consumedAt: event.consumedAt
+    });
+    if (!aborted.ok)
+        return failed(aborted.code, aborted.message, resolved.taskId);
+    const updated = withUpdatedRun(run, {
+        status: 'running',
+        pause: null,
+        nextStage: null,
+        pendingDelegation: null,
+        receipts: Object.freeze([...run.receipts, aborted.receipt])
+    }, options.now);
+    saveRun(resolved.taskDir, updated);
+    return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
+}
 function completeOrchestrationStage(taskRef, event, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
@@ -1204,5 +1254,5 @@ function pauseOrchestration(taskRef, code, message, recoverable, options = {}) {
     saveRun(resolved.taskDir, updated);
     return { status: 'paused', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
 }
-export { activateMatchingOrchestrationDelegation, activateOrchestrationDelegation, awaitOrchestrationDelegationActivation, advanceOrchestration, beginOrResumeOrchestration, commitOrchestrationStageCompletion, completeOrchestrationStage, dispatchOrchestrationDelegation, inspectOrchestrationStage, hasActivatableOrchestrationDelegation, hasSealableOrchestrationDelegation, OrchestrationStateError, orchestrationPath, pauseMatchingOrchestrationDelegation, pauseOrchestration, planOrchestrationStageCompletion, prepareOrchestrationDelegation, readRun, reconcileMatchingOrchestrationDelegation, recoverPreparedOrchestrationDelegation, routeOrchestration, sealMatchingOrchestrationDelegation, sealMatchingOrchestrationDelegationWithHostEvidence, sealOrchestrationDelegation, statusOrchestration, };
+export { activateMatchingOrchestrationDelegation, activateOrchestrationDelegation, awaitOrchestrationDelegationActivation, advanceOrchestration, beginOrResumeOrchestration, commitOrchestrationStageCompletion, completeOrchestrationStage, dispatchOrchestrationDelegation, inspectOrchestrationStage, hasActivatableOrchestrationDelegation, hasSealableOrchestrationDelegation, OrchestrationStateError, orchestrationPath, pauseMatchingOrchestrationDelegation, pauseOrchestration, planOrchestrationStageCompletion, prepareOrchestrationDelegation, readRun, reconcileMatchingOrchestrationDelegation, recoverPreparedOrchestrationDelegation, recoverActivatedOrchestrationDelegationUnderLock, routeOrchestration, sealMatchingOrchestrationDelegation, sealMatchingOrchestrationDelegationWithHostEvidence, sealOrchestrationDelegation, statusOrchestration, };
 //# sourceMappingURL=orchestration.js.map