@fitlab-ai/agent-infra 0.11.2 → 0.11.4

package/dist/lib/task/finalization.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { syncPlatformComment } from '../platform/issue-comments.js';
 import { canonicalizeSummaryBody } from '../platform/comment-safety.js';
+import { backfillCompletionComments, inspectCompletionBackfillEligibility } from '../platform/completion-backfill.js';
 import { taskIssueIdentity } from '../platform/task-identities.js';
 import { parseTaskFrontmatter } from './frontmatter.js';
 import { applyTaskLifecycle } from './lifecycle.js';
@@ -12,8 +13,8 @@ import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-
 import { verifyTaskEvent } from './verification.js';
 import { projectFinalizationWarning } from './workflow-warning-intents.js';
 import { mergeOperationWarnings } from './operation-outcome.js';
-const RECEIPT_VERSION = 3;
-const FINALIZATION_STEPS = ['lifecycle', 'task-comment', 'verification', 'summary', 'post-summary-verification'];
+const RECEIPT_VERSION = 4;
+const FINALIZATION_STEPS = ['lifecycle', 'task-comment', 'verification', 'summary'];
 function finalizationRoot(repoRoot) {
     return path.join(repoRoot, '.agents', 'workspace', '.task-finalization');
 }
@@ -34,11 +35,11 @@ function failed(taskId, error, overrides = {}) {
         status: error.retryable ? 'blocked' : 'failed',
         changed: false,
         taskId,
+        backfill: null,
         lifecycle: null,
         taskComment: null,
         verification: null,
         summary: null,
-        postSummaryVerification: null,
         completedSteps: [],
         pendingSteps: [...FINALIZATION_STEPS],
         result: error.retryable ? 'blocked' : 'failed',
@@ -58,10 +59,8 @@ function emptyReceipt(taskId, controlBinding) {
         taskComment: 'pending',
         verification: 'pending',
         summary: 'pending',
-        postSummaryVerification: 'pending',
         warningProjection: 'done',
         warnings: [],
-        summarySha256: null,
         ...(controlBinding ? { controlBinding } : {}),
         updatedAt: now(),
         lastError: null
@@ -97,10 +96,8 @@ function validateReceipt(value, taskId) {
         || !states.includes(String(receipt.taskComment))
         || !states.includes(String(receipt.verification))
         || !states.includes(String(receipt.summary))
-        || !states.includes(String(receipt.postSummaryVerification))
         || !['pending', 'done'].includes(String(receipt.warningProjection))
         || !Array.isArray(receipt.warnings) || receipt.warnings.some((warning) => !validWarning(warning))
-        || (receipt.summarySha256 !== null && (typeof receipt.summarySha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(receipt.summarySha256)))
         || typeof receipt.updatedAt !== 'string'
         || (receipt.lastError !== null && (typeof receipt.lastError !== 'object' || Array.isArray(receipt.lastError)))
         || (receipt.controlBinding !== undefined && (!controlBinding || typeof controlBinding !== 'object'
@@ -154,8 +151,6 @@ function pendingSteps(receipt) {
 function stepState(receipt, step) {
     if (step === 'task-comment')
         return receipt.taskComment;
-    if (step === 'post-summary-verification')
-        return receipt.postSummaryVerification;
     return receipt[step];
 }
 function lifecycleStep(result) {
@@ -226,6 +221,77 @@ function resolveStepWarnings(receipt, step) {
         ? { ...warning, status: 'resolved', resolvedAt: now() }
         : warning);
 }
+function verificationWarnings(result) {
+    const warnings = [];
+    for (const invocation of result.invocations) {
+        const checks = Array.isArray(invocation.payload.checks) ? invocation.payload.checks : [invocation.payload];
+        for (const value of checks) {
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                continue;
+            const check = value;
+            const status = check.effectiveStatus ?? check.status;
+            const target = typeof check.checkId === 'string' && check.checkId ? check.checkId : typeof check.type === 'string' ? check.type : null;
+            if (!target || status === 'pass')
+                continue;
+            const blocked = status === 'blocked';
+            const message = [check.reason, check.message, check.action]
+                .filter((item) => typeof item === 'string' && item.length > 0)
+                .join(' - ');
+            warnings.push({
+                step: 'verification', target, code: blocked ? 'CHECK_BLOCKED' : 'CHECK_FAILED',
+                retryable: blocked, severity: 'ACTION_REQUIRED',
+                message: message || `verification ${String(status)}`
+            });
+        }
+    }
+    return mergeOperationWarnings(warnings);
+}
+function applyVerificationWarnings(receipt, result) {
+    if (result.status === 'pass')
+        return resolveStepWarnings(receipt, 'verification');
+    const observed = new Map();
+    for (const invocation of result.invocations) {
+        const checks = Array.isArray(invocation.payload.checks) ? invocation.payload.checks : [invocation.payload];
+        for (const value of checks) {
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                continue;
+            const check = value;
+            const target = typeof check.checkId === 'string' && check.checkId ? check.checkId : typeof check.type === 'string' ? check.type : null;
+            if (!target)
+                continue;
+            const status = check.effectiveStatus ?? check.status;
+            if (status === 'pass')
+                observed.set(target, 'pass');
+        }
+    }
+    for (const warning of verificationWarnings(result))
+        observed.set(warning.target, warning);
+    if (observed.size === 0) {
+        return replaceWarning(receipt, warningFromError('verification', verificationFailure(result)), 'open');
+    }
+    let warnings = [...receipt.warnings];
+    for (const [target, current] of observed) {
+        if (current === 'pass') {
+            warnings = warnings.map((warning) => warning.step === 'verification' && warning.target === target && warning.status === 'open'
+                ? { ...warning, status: 'resolved', resolvedAt: now() }
+                : warning);
+            continue;
+        }
+        warnings = warnings.map((warning) => warning.step === 'verification' && warning.target === target
+            && warning.status === 'open' && warning.code !== current.code
+            ? { ...warning, status: 'resolved', resolvedAt: now() }
+            : warning);
+        const key = warningKey(current);
+        warnings = [...warnings.filter((warning) => warningKey(warning) !== key), warningRecord(current, 'open')];
+    }
+    return warnings;
+}
+function shouldRunBackfill(receipt) {
+    return receipt.lifecycle !== 'done'
+        || receipt.taskComment === 'pending'
+        || receipt.verification === 'pending'
+        || receipt.warnings.some((warning) => warning.step === 'backfill' && warning.status === 'open');
+}
 function issueCapability(receipt, scope) {
     return {
         receiptId: receipt.receiptId,
@@ -241,6 +307,21 @@ function capabilityError(code, message) {
     Object.assign(error, { code });
     return error;
 }
+function hasPreparedTaskDocument(repoRoot, taskId) {
+    const resolved = resolveTaskRef(taskId, { repoRoot });
+    if (!resolved.ok)
+        return false;
+    if (resolved.state === 'completed')
+        return true;
+    if (resolved.state !== 'active')
+        return false;
+    try {
+        return parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8')).status === 'completed';
+    }
+    catch {
+        return false;
+    }
+}
 function mutationKeys(value) {
     return Object.keys(value).sort();
 }
@@ -310,9 +391,8 @@ function mutationPatch(current, mutation) {
         : { warningProjection: 'pending', lastError: mutation.error };
 }
 function applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, mutation, consumed) {
-    const resolved = resolveTaskRef(receipt.taskId, { repoRoot });
-    if (!resolved.ok || resolved.state !== 'completed') {
-        throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires a completed task');
+    if (!hasPreparedTaskDocument(repoRoot, receipt.taskId)) {
+        throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires an active prepared task or a completed task');
     }
     const current = readReceipt(repoRoot, receipt.taskId);
     if (!current || current.receiptId !== receipt.receiptId || current.revision !== receipt.revision) {
@@ -324,11 +404,10 @@ function applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability
     return next;
 }
 function applyFinalizationReceiptMutation(repoRoot, receipt, capability, mutation) {
-    const resolved = resolveTaskRef(receipt.taskId, { repoRoot });
-    if (!resolved.ok || resolved.state !== 'completed') {
-        throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires a completed task');
+    if (!hasPreparedTaskDocument(repoRoot, receipt.taskId)) {
+        throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires an active prepared task or a completed task');
     }
-    return withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.receipt-mutation', () => applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, mutation, new Set()));
+    return withTaskExecutionLock(repoRoot, receipt.taskId, 'task-finalization.receipt-mutation', () => applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, mutation, new Set()));
 }
 function warningKey(warning) {
     return `${warning.step}\0${warning.code}\0${warning.target}`;
@@ -339,7 +418,8 @@ function reconcileWarningProjection(repoRoot, taskId, receipt, consumed) {
     const warnings = [...new Map(receipt.warnings.map((warning) => [warningKey(warning), warning])).values()];
     for (const warning of warnings) {
         try {
-            const projected = projectFinalizationWarning(taskId, warning, { repoRoot });
+            const superseded = warning.status === 'resolved' && receipt.warnings.some((item) => item.status === 'open' && item.step === warning.step && item.target === warning.target && item.code !== warning.code);
+            const projected = projectFinalizationWarning(taskId, warning, { repoRoot, resolution: superseded ? 'superseded' : 'passed' });
             if (projected.status === 'failed') {
                 const detail = {
                     code: projected.error?.code || 'FINALIZATION_WARNING_PROJECTION_FAILED',
@@ -436,16 +516,17 @@ function readDeliverySummary(taskDir, taskId) {
 }
 async function syncPendingSummary(input) {
     let { receipt } = input;
-    if (receipt.summary !== 'pending') {
-        return { receipt, step: { status: receipt.summary === 'skipped' ? 'skipped' : 'no-op', changed: false, error: null }, changed: false, error: null };
-    }
     try {
         const resolved = resolveTaskRef(input.taskId, { repoRoot: input.repoRoot });
-        if (!resolved.ok || resolved.state !== 'completed')
-            throw Object.assign(new Error('completed task is unavailable for summary sync'), { code: 'SUMMARY_STAGING_INVALID' });
+        if (!resolved.ok || !hasPreparedTaskDocument(input.repoRoot, input.taskId))
+            throw Object.assign(new Error('prepared task is unavailable for summary sync'), { code: 'SUMMARY_STAGING_INVALID' });
+        if (!fs.existsSync(path.join(resolved.taskDir, '.delivery-summary.json'))) {
+            receipt = updateReceipt(input.repoRoot, receipt, { summary: 'skipped', lastError: null });
+            return { receipt, step: { status: 'skipped', changed: false, error: null }, changed: false, error: null };
+        }
         if (!taskIssueIdentity(parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8')))) {
             receipt = updateReceipt(input.repoRoot, receipt, {
-                summary: 'skipped', postSummaryVerification: 'skipped', summarySha256: null, lastError: null
+                summary: 'skipped', lastError: null
             });
             return { receipt, step: { status: 'skipped', changed: false, error: null }, changed: false, error: null };
         }
@@ -460,8 +541,7 @@ async function syncPendingSummary(input) {
             const resolvedWarning = receipt.warnings.some((warning) => warning.step === 'summary' && warning.status === 'open');
             const warnings = resolveStepWarnings(receipt, 'summary');
             receipt = updateReceipt(input.repoRoot, receipt, {
-                summary: skipped ? 'skipped' : 'done', postSummaryVerification: skipped ? 'skipped' : receipt.postSummaryVerification,
-                summarySha256: skipped ? null : summary.sha256,
+                summary: skipped ? 'skipped' : 'done',
                 taskComment: resolvedWarning ? 'pending' : receipt.taskComment,
                 warningProjection: warnings.some((warning) => warning.status === 'open') ? 'pending' : 'done',
                 warnings,
@@ -488,14 +568,9 @@ async function syncPendingSummary(input) {
         return { receipt, step: { status: 'blocked', changed: false, error }, changed: false, error };
     }
 }
-function clearDeliverySummary(taskDir) {
-    const file = path.join(taskDir, '.delivery-summary.json');
-    if (fs.existsSync(file))
-        fs.unlinkSync(file);
-}
 function terminalResult(taskId, receipt, steps, changed, error = null) {
     const pending = pendingSteps(receipt);
-    const blocked = [steps.lifecycle, steps.taskComment, steps.verification, steps.summary, steps.postSummaryVerification].some((step) => step?.status === 'blocked');
+    const blocked = [steps.backfill, steps.lifecycle, steps.taskComment, steps.verification, steps.summary].some((step) => step?.status === 'blocked');
     const warnings = openWarnings(receipt);
     const postLifecyclePending = receipt.lifecycle === 'done' && (pending.some((step) => step !== 'lifecycle') || receipt.warningProjection === 'pending');
     const hardError = error?.code.startsWith('FINALIZATION_') || error?.code === 'TASK_FINALIZATION_RECEIPT_INVALID';
@@ -503,18 +578,18 @@ function terminalResult(taskId, receipt, steps, changed, error = null) {
         status: hardError ? (error?.retryable ? 'blocked' : 'failed') : pending.length === 0 ? 'completed' : postLifecyclePending ? 'completed' : blocked ? 'blocked' : 'failed',
         changed,
         taskId,
+        backfill: steps.backfill ?? null,
         lifecycle: steps.lifecycle ?? null,
         taskComment: steps.taskComment ?? null,
         verification: steps.verification ?? null,
         summary: steps.summary ?? null,
-        postSummaryVerification: steps.postSummaryVerification ?? null,
         completedSteps: completedSteps(receipt),
         pendingSteps: pending,
         result: hardError
             ? (error?.retryable ? 'blocked' : 'failed')
-            : postLifecyclePending && (warnings.length > 0 || receipt.warningProjection === 'pending')
+            : postLifecyclePending
                 ? 'completed_with_warnings'
-                : pending.length === 0 || postLifecyclePending
+                : pending.length === 0
                     ? 'completed'
                     : blocked
                         ? 'blocked'
@@ -523,9 +598,22 @@ function terminalResult(taskId, receipt, steps, changed, error = null) {
         error: hardError ? error : postLifecyclePending ? null : error
     };
 }
-async function applyUnderLock(request, taskId, options) {
+function preparedResult(taskId, receipt, steps, changed) {
+    return {
+        status: 'prepared', changed, taskId,
+        backfill: steps.backfill ?? null,
+        lifecycle: steps.lifecycle ?? null,
+        taskComment: steps.taskComment ?? null,
+        verification: steps.verification ?? null,
+        summary: steps.summary ?? null,
+        completedSteps: completedSteps(receipt), pendingSteps: pendingSteps(receipt),
+        result: 'prepared', warnings: openWarnings(receipt), error: null
+    };
+}
+async function prepareUnderLock(request, taskId, options) {
     const repoRoot = path.resolve(options.repoRoot);
     const lifecycle = options.lifecycle ?? applyTaskLifecycle;
+    const backfill = options.backfill ?? backfillCompletionComments;
     const commentSync = options.commentSync ?? syncPlatformComment;
     const verify = options.verify ?? verifyTaskEvent;
     const consumedCapabilities = new Set();
@@ -562,52 +650,89 @@ async function applyUnderLock(request, taskId, options) {
             return failed(taskId, errorOf(error, 'TASK_FINALIZATION_PREFLIGHT_FAILED', true));
         }
     }
-    let lifecycleResult = null;
     let changed = false;
-    try {
-        const resolved = resolveTaskRef(taskId, { repoRoot });
-        const registry = resolved.ok && resolved.state === 'completed' ? inspectShortIdRegistry(repoRoot) : null;
-        if (registry && registry.status !== 'valid') {
-            const detail = {
-                code: 'TASK_FINALIZATION_SHORT_ID_REGISTRY_UNAVAILABLE',
-                message: `cannot verify canonical short-id registry: ${registry.error.code}: ${registry.error.message}`,
-                retryable: false
-            };
-            receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: detail });
-            return terminalResult(taskId, receipt, {
-                lifecycle: { status: 'failed', changed: false, error: detail },
-                taskComment: null,
-                verification: null
-            }, changed, detail);
+    let backfillResult = null;
+    let runBackfill = shouldRunBackfill(receipt);
+    if (!runBackfill && receipt.lifecycle === 'done') {
+        const eligibility = inspectCompletionBackfillEligibility(taskId, { cwd: repoRoot });
+        if (eligibility.status === 'failed')
+            return failed(taskId, eligibility.error, {
+                completedSteps: completedSteps(receipt), pendingSteps: pendingSteps(receipt), warnings: openWarnings(receipt)
+            });
+        runBackfill = eligibility.eligible;
+    }
+    if (receipt.lifecycle === 'done' && runBackfill && receipt.summary === 'done') {
+        receipt = updateReceipt(repoRoot, receipt, { summary: 'pending' });
+    }
+    if (runBackfill)
+        try {
+            const result = await backfill(taskId, { agent: request.agent, cwd: repoRoot });
+            backfillResult = commentStep(result);
+            const issueNotLinked = result.status === 'no-op' && result.error?.code === 'ISSUE_NOT_LINKED';
+            if (!issueNotLinked && (result.status !== 'applied' && result.status !== 'no-op' || result.error)) {
+                const detail = backfillResult.error ?? {
+                    code: 'COMPLETION_BACKFILL_FAILED', message: 'completion artifact backfill did not reach a successful terminal result', retryable: true
+                };
+                if (receipt.lifecycle !== 'done')
+                    return failed(taskId, detail, {
+                        backfill: backfillResult,
+                        completedSteps: completedSteps(receipt),
+                        pendingSteps: pendingSteps(receipt)
+                    });
+                const warnings = replaceWarning(receipt, warningFromError('backfill', detail), 'open');
+                receipt = updateReceipt(repoRoot, receipt, { warningProjection: 'pending', warnings, lastError: detail });
+                receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+                if (!detail.retryable)
+                    return failed(taskId, detail, {
+                        changed, backfill: backfillResult, completedSteps: completedSteps(receipt),
+                        pendingSteps: pendingSteps(receipt), warnings: openWarnings(receipt)
+                    });
+                return terminalResult(taskId, receipt, { backfill: backfillResult }, changed, detail);
+            }
+            changed = result.changed;
+            if (receipt.warnings.some((warning) => warning.step === 'backfill' && warning.status === 'open')) {
+                const warnings = receipt.warnings.map((warning) => warning.step === 'backfill' && warning.status === 'open'
+                    ? { ...warning, status: 'resolved', resolvedAt: now() }
+                    : warning);
+                receipt = updateReceipt(repoRoot, receipt, { warningProjection: 'pending', warnings, lastError: null });
+            }
+            if (result.changed && receipt.taskComment !== 'pending') {
+                receipt = updateReceipt(repoRoot, receipt, { taskComment: 'pending' });
+            }
         }
-        const shortIds = registry?.status === 'valid' ? registry.shortIds : null;
-        if (shortIds?.has(taskId)) {
-            const detail = {
-                code: 'TASK_FINALIZATION_CANONICAL_STATE_INVALID',
-                message: 'completed task still has an active short-id registry entry',
-                retryable: false
-            };
-            receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: detail });
-            return terminalResult(taskId, receipt, {
-                lifecycle: { status: 'failed', changed: false, error: detail },
-                taskComment: null,
-                verification: null
-            }, changed, detail);
+        catch (error) {
+            const detail = errorOf(error, 'COMPLETION_BACKFILL_FAILED', true);
+            if (receipt.lifecycle === 'done') {
+                const warnings = replaceWarning(receipt, warningFromError('backfill', detail), 'open');
+                receipt = updateReceipt(repoRoot, receipt, { warningProjection: 'pending', warnings, lastError: detail });
+                receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+                return terminalResult(taskId, receipt, {
+                    backfill: { status: 'blocked', changed: false, error: detail }
+                }, changed, detail);
+            }
+            return failed(taskId, detail, {
+                backfill: { status: detail.retryable ? 'blocked' : 'failed', changed: false, error: detail },
+                completedSteps: completedSteps(receipt),
+                pendingSteps: pendingSteps(receipt)
+            });
         }
-        const lifecycleDone = receipt.lifecycle === 'done' && resolved.ok && resolved.state === 'completed' && shortIds !== null;
-        if (lifecycleDone) {
+    else
+        backfillResult = { status: 'no-op', changed: false, error: null };
+    let lifecycleResult = null;
+    try {
+        const resolved = resolveTaskRef(taskId, { repoRoot });
+        if (receipt.lifecycle === 'done' && resolved.ok && resolved.state === 'completed') {
             lifecycleResult = { status: 'no-op', changed: false, error: null };
             receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'done', lastError: null });
         }
         else {
-            const result = lifecycle({ taskRef: taskId, intent: 'complete', agent: request.agent }, { repoRoot, ...(options.metadataProvider ? { metadataProvider: options.metadataProvider } : {}) });
+            const result = lifecycle({ taskRef: taskId, intent: 'complete', agent: request.agent }, { repoRoot, prepareOnly: true, ...(options.metadataProvider ? { metadataProvider: options.metadataProvider } : {}) });
             lifecycleResult = lifecycleStep(result);
             if (result.status !== 'applied' && result.status !== 'no-op') {
                 receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: lifecycleResult.error });
-                return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment: null, verification: null }, result.changed, lifecycleResult.error);
+                return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment: null, verification: null }, result.changed, lifecycleResult.error);
             }
-            changed = result.changed;
-            receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'done', lastError: null });
+            changed = changed || result.changed;
         }
     }
     catch (error) {
@@ -616,31 +741,30 @@ async function applyUnderLock(request, taskId, options) {
             receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: detail });
         }
         catch { /* preserve the primary error */ }
-        return failed(taskId, detail, { lifecycle: lifecycleResult });
+        return failed(taskId, detail, { backfill: backfillResult, lifecycle: lifecycleResult });
     }
     let taskComment = null;
     receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-    const initialComment = await syncPendingTaskComment({
-        repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
-    });
-    receipt = initialComment.receipt;
-    taskComment = initialComment.step;
-    changed = changed || initialComment.changed;
-    if (initialComment.error) {
-        return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification: null }, changed, initialComment.error);
-    }
     let verification = null;
-    try {
-        receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-        const verificationPending = receipt.verification === 'pending';
-        const result = await verify({ taskRef: taskId, event: 'complete-task.completed' }, { repoRoot });
-        verification = verificationStep(result);
-        if (result.status === 'pass') {
-            if (verificationPending) {
-                const capability = issueCapability(receipt, 'verification');
-                receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
-                    scope: 'verification', operation: 'succeeded'
-                }, consumedCapabilities);
+    if (receipt.verification !== 'pending') {
+        verification = { status: receipt.verification === 'skipped' ? 'skipped' : 'no-op', changed: false, error: null };
+    }
+    else {
+        try {
+            receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+            const verificationState = resolveTaskRef(taskId, { repoRoot });
+            const verificationEvent = verificationState.ok && verificationState.state === 'completed'
+                ? 'complete-task.completed'
+                : 'complete-task.prepared';
+            const result = await verify({ taskRef: taskId, event: verificationEvent }, { repoRoot });
+            verification = verificationStep(result);
+            if (result.status === 'pass') {
+                const resolvedTaskWarning = receipt.warnings.some((warning) => warning.step === 'verification' && warning.status === 'open');
+                const warnings = applyVerificationWarnings(receipt, result);
+                receipt = updateReceipt(repoRoot, receipt, {
+                    verification: 'done', taskComment: resolvedTaskWarning ? 'pending' : receipt.taskComment,
+                    warningProjection: warnings.length > 0 ? 'pending' : 'done', warnings, lastError: null
+                });
                 receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
                 const finalComment = await syncPendingTaskComment({
                     repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
@@ -650,176 +774,101 @@ async function applyUnderLock(request, taskId, options) {
                     taskComment = finalComment.step;
                 changed = changed || finalComment.changed;
                 if (finalComment.error) {
-                    return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification }, changed, finalComment.error);
+                    return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification }, changed, finalComment.error);
                 }
             }
             else {
-                receipt = updateReceipt(repoRoot, receipt, { lastError: null });
-            }
-        }
-        else {
-            const detail = verification.error ?? { code: 'VERIFY_FAILED', message: 'verification failed', retryable: true };
-            if (verificationPending) {
-                const capability = issueCapability(receipt, 'verification');
-                receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
-                    scope: 'verification', operation: 'failed', error: detail
-                }, consumedCapabilities);
-                receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-            }
-            else {
-                const warnings = replaceWarning(receipt, warningFromError('verification', detail), 'open');
+                const detail = verification.error ?? { code: 'VERIFY_FAILED', message: 'verification failed', retryable: true };
+                const warnings = applyVerificationWarnings(receipt, result);
                 receipt = updateReceipt(repoRoot, receipt, {
                     verification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: detail
                 });
                 receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-                const warningComment = await syncPendingTaskComment({ repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities });
+                const warningComment = await syncPendingTaskComment({
+                    repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
+                });
                 receipt = warningComment.receipt;
-                if (warningComment.step.status !== 'no-op')
-                    taskComment = warningComment.step;
+                taskComment = warningComment.step;
                 changed = changed || warningComment.changed;
+                if (warningComment.error) {
+                    return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification }, changed, warningComment.error);
+                }
+                return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification }, changed, detail);
             }
-            return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification }, changed, detail);
         }
-    }
-    catch (error) {
-        const detail = errorOf(error, 'VERIFY_FAILED', true);
-        try {
-            if (receipt.verification === 'pending') {
-                const capability = issueCapability(receipt, 'verification');
-                receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
-                    scope: 'verification', operation: 'failed', error: detail
-                }, consumedCapabilities);
-            }
-            else {
+        catch (error) {
+            const detail = errorOf(error, 'VERIFY_FAILED', true);
+            try {
                 const warnings = replaceWarning(receipt, warningFromError('verification', detail), 'open');
                 receipt = updateReceipt(repoRoot, receipt, {
                     verification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: detail
                 });
-            }
-            receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-        }
-        catch (writeError) {
-            const persistence = errorOf(writeError, 'FINALIZATION_RECEIPT_WRITE_FAILED', true);
-            const hardError = {
-                code: 'FINALIZATION_RECEIPT_WRITE_FAILED',
-                message: `Unable to persist verification failure (${detail.code}: ${detail.message}): ${persistence.message}`,
-                retryable: true
-            };
-            return terminalResult(taskId, receipt, {
-                lifecycle: lifecycleResult, taskComment, verification: { status: 'blocked', changed: false, error: detail }
-            }, changed, hardError);
-        }
-        try {
-            const warningComment = await syncPendingTaskComment({ repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities });
-            receipt = warningComment.receipt;
-            if (warningComment.step.status !== 'no-op')
-                taskComment = warningComment.step;
-            changed = changed || warningComment.changed;
-        }
-        catch { /* preserve the primary error */ }
-        return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification: { status: 'blocked', changed: false, error: detail } }, changed, detail);
-    }
-    const summary = await syncPendingSummary({ repoRoot, taskId, agent: request.agent, receipt, commentSync });
-    receipt = summary.receipt;
-    changed = changed || summary.changed;
-    if (summary.error) {
-        receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-        const warningComment = await syncPendingTaskComment({
-            repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
-        });
-        receipt = warningComment.receipt;
-        if (warningComment.step.status !== 'no-op')
-            taskComment = warningComment.step;
-        changed = changed || warningComment.changed;
-        return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step }, changed, summary.error);
-    }
-    let postSummaryVerification = null;
-    if (receipt.postSummaryVerification === 'skipped') {
-        postSummaryVerification = { status: 'skipped', changed: false, error: null };
-    }
-    else if (receipt.postSummaryVerification !== 'pending') {
-        const replay = await commentSync(taskId, {
-            kind: 'summary', agent: request.agent, body: '', cwd: repoRoot, verifyOnly: true,
-            summaryAuthorization: { sha256: receipt.summarySha256 ?? '' }
-        });
-        postSummaryVerification = commentStep(replay);
-        if (replay.status !== 'applied' && replay.status !== 'no-op') {
-            const error = postSummaryVerification.error ?? { code: 'SUMMARY_VERIFICATION_FAILED', message: 'summary replay verification failed', retryable: true };
-            const warnings = replaceWarning(receipt, warningFromError('post-summary-verification', error), 'open');
-            receipt = updateReceipt(repoRoot, receipt, { postSummaryVerification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: error });
-            receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-            return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step, postSummaryVerification }, changed, error);
-        }
-    }
-    else {
-        try {
-            const summaryVerification = await commentSync(taskId, {
-                kind: 'summary', agent: request.agent, body: '', cwd: repoRoot, verifyOnly: true,
-                summaryAuthorization: { sha256: receipt.summarySha256 ?? '' }
-            });
-            if (summaryVerification.status !== 'applied' && summaryVerification.status !== 'no-op') {
-                const error = commentStep(summaryVerification).error ?? { code: 'SUMMARY_VERIFICATION_FAILED', message: 'summary verification failed', retryable: true };
-                const warnings = replaceWarning(receipt, warningFromError('post-summary-verification', error), 'open');
-                receipt = updateReceipt(repoRoot, receipt, { postSummaryVerification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: error });
                 receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-                const warningComment = await syncPendingTaskComment({ repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities });
-                receipt = warningComment.receipt;
-                if (warningComment.step.status !== 'no-op')
-                    taskComment = warningComment.step;
-                changed = changed || warningComment.changed;
-                return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step, postSummaryVerification: commentStep(summaryVerification) }, changed, error);
             }
-            const result = await verify({ taskRef: taskId, event: 'complete-task.completed' }, { repoRoot });
-            postSummaryVerification = verificationStep(result);
-            if (result.status === 'pass') {
-                const resolvedWarning = receipt.warnings.some((warning) => warning.step === 'post-summary-verification' && warning.status === 'open');
-                const warnings = resolveStepWarnings(receipt, 'post-summary-verification');
-                receipt = updateReceipt(repoRoot, receipt, {
-                    postSummaryVerification: 'done', taskComment: resolvedWarning ? 'pending' : receipt.taskComment,
-                    warningProjection: warnings.some((warning) => warning.status === 'open') ? 'pending' : 'done', warnings, lastError: null
-                });
-                receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-                const warningComment = await syncPendingTaskComment({ repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities });
-                receipt = warningComment.receipt;
-                if (warningComment.step.status !== 'no-op')
-                    taskComment = warningComment.step;
-                changed = changed || warningComment.changed;
+            catch (writeError) {
+                const persistence = errorOf(writeError, 'FINALIZATION_RECEIPT_WRITE_FAILED', true);
+                const hardError = {
+                    code: 'FINALIZATION_RECEIPT_WRITE_FAILED',
+                    message: `Unable to persist verification failure (${detail.code}: ${detail.message}): ${persistence.message}`,
+                    retryable: true
+                };
+                return terminalResult(taskId, receipt, {
+                    backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification: { status: 'blocked', changed: false, error: detail }
+                }, changed, hardError);
             }
-            else {
-                const error = postSummaryVerification.error ?? { code: 'VERIFY_FAILED', message: 'post-summary verification failed', retryable: true };
-                const warnings = replaceWarning(receipt, warningFromError('post-summary-verification', error), 'open');
-                receipt = updateReceipt(repoRoot, receipt, { postSummaryVerification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: error });
-                receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+            try {
                 const warningComment = await syncPendingTaskComment({ repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities });
                 receipt = warningComment.receipt;
                 if (warningComment.step.status !== 'no-op')
                     taskComment = warningComment.step;
                 changed = changed || warningComment.changed;
-                return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step, postSummaryVerification }, changed, error);
             }
-        }
-        catch (error) {
-            const detail = errorOf(error, 'POST_SUMMARY_VERIFY_FAILED', true);
-            const warnings = replaceWarning(receipt, warningFromError('post-summary-verification', detail), 'open');
-            receipt = updateReceipt(repoRoot, receipt, { postSummaryVerification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: detail });
-            receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-            const warningComment = await syncPendingTaskComment({ repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities });
-            receipt = warningComment.receipt;
-            if (warningComment.step.status !== 'no-op')
-                taskComment = warningComment.step;
-            changed = changed || warningComment.changed;
-            return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step, postSummaryVerification: { status: 'blocked', changed: false, error: detail } }, changed, detail);
+            catch { /* preserve the primary error */ }
+            return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification: { status: 'blocked', changed: false, error: detail } }, changed, detail);
         }
     }
+    let summary = receipt.summary === 'pending'
+        ? await syncPendingSummary({ repoRoot, taskId, agent: request.agent, receipt, commentSync })
+        : { receipt, step: { status: 'no-op', changed: false, error: null }, changed: false, error: null };
+    receipt = summary.receipt;
+    changed = changed || summary.changed;
+    if (summary.error) {
+        receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+        return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification, summary: summary.step }, changed, summary.error);
+    }
     receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-    if (receipt.summary !== 'pending' && receipt.postSummaryVerification !== 'pending' && receipt.warningProjection === 'done' && openWarnings(receipt).length === 0) {
-        const resolved = resolveTaskRef(taskId, { repoRoot });
-        if (resolved.ok && resolved.state === 'completed')
-            clearDeliverySummary(resolved.taskDir);
+    if (receipt.taskComment === 'pending') {
+        const finalComment = await syncPendingTaskComment({
+            repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
+        });
+        receipt = finalComment.receipt;
+        taskComment = finalComment.step;
+        changed = changed || finalComment.changed;
+        if (finalComment.error) {
+            return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification, summary: summary.step }, changed, finalComment.error);
+        }
     }
-    return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step, postSummaryVerification }, changed);
+    return preparedResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification, summary: summary.step }, changed);
 }
-async function applyTaskFinalization(request, options) {
+async function prepareTaskFinalization(request, options) {
+    if (request.intent !== 'complete' || !request.taskRef || !request.agent) {
+        return failed(null, { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'complete finalization requires taskRef and agent', retryable: false });
+    }
+    const repoRoot = path.resolve(options.repoRoot);
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot });
+    if (!resolved.ok)
+        return failed(resolved.taskId, { code: resolved.code, message: resolved.message, retryable: false });
+    try {
+        return await withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.prepare', () => prepareUnderLock(request, resolved.taskId, options));
+    }
+    catch (error) {
+        const detail = error instanceof TaskExecutionLockError
+            ? { code: error.code, message: error.message, retryable: error.code === 'ORCHESTRATION_LOCK_BUSY' }
+            : errorOf(error, 'TASK_FINALIZATION_FAILED');
+        return failed(resolved.taskId, detail);
+    }
+}
+async function commitPreparedTaskFinalization(request, options) {
     if (request.intent !== 'complete' || !request.taskRef || !request.agent) {
         return failed(null, { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'complete finalization requires taskRef and agent', retryable: false });
     }
@@ -828,7 +877,37 @@ async function applyTaskFinalization(request, options) {
     if (!resolved.ok)
         return failed(resolved.taskId, { code: resolved.code, message: resolved.message, retryable: false });
     try {
-        return await withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.complete', () => applyUnderLock(request, resolved.taskId, options));
+        return await withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.commit', () => {
+            const receipt = readReceipt(repoRoot, resolved.taskId);
+            if (!receipt)
+                return failed(resolved.taskId, {
+                    code: 'TASK_FINALIZATION_PREPARATION_REQUIRED', message: 'sandbox preparation receipt is unavailable', retryable: true
+                });
+            if (receipt.lifecycle === 'done' && resolved.state === 'completed') {
+                return terminalResult(resolved.taskId, receipt, { lifecycle: { status: 'no-op', changed: false, error: null } }, false);
+            }
+            if (receipt.taskComment === 'pending' || receipt.verification === 'pending' || receipt.summary === 'pending' || receipt.warningProjection === 'pending') {
+                return failed(resolved.taskId, {
+                    code: 'TASK_FINALIZATION_PREPARATION_REQUIRED', message: 'sandbox preparation has pending external steps', retryable: true
+                }, { completedSteps: completedSteps(receipt), pendingSteps: pendingSteps(receipt), warnings: openWarnings(receipt) });
+            }
+            const registry = inspectShortIdRegistry(repoRoot);
+            if (registry.status !== 'valid')
+                return failed(resolved.taskId, {
+                    code: 'TASK_FINALIZATION_SHORT_ID_REGISTRY_UNAVAILABLE',
+                    message: `cannot verify canonical short-id registry: ${registry.error.code}: ${registry.error.message}`,
+                    retryable: false
+                });
+            const lifecycle = options.lifecycle ?? applyTaskLifecycle;
+            const result = lifecycle({ taskRef: resolved.taskId, intent: 'complete', agent: request.agent }, { repoRoot, ...(options.metadataProvider ? { metadataProvider: options.metadataProvider } : {}) });
+            const step = lifecycleStep(result);
+            if (result.status !== 'applied' && result.status !== 'no-op') {
+                const updated = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: step.error });
+                return terminalResult(resolved.taskId, updated, { lifecycle: step }, result.changed, step.error);
+            }
+            const updated = updateReceipt(repoRoot, receipt, { lifecycle: 'done', lastError: null });
+            return terminalResult(resolved.taskId, updated, { lifecycle: step }, result.changed);
+        });
     }
     catch (error) {
         const detail = error instanceof TaskExecutionLockError
@@ -837,5 +916,11 @@ async function applyTaskFinalization(request, options) {
         return failed(resolved.taskId, detail);
     }
 }
-export { applyFinalizationReceiptMutation, applyTaskFinalization, issueCapability as createFinalizationCapability, readTaskFinalizationReceipt, terminalResult };
+async function applyTaskFinalization(request, options) {
+    const prepared = await prepareTaskFinalization(request, options);
+    if (prepared.status !== 'prepared')
+        return prepared;
+    return commitPreparedTaskFinalization(request, options);
+}
+export { applyFinalizationReceiptMutation, commitPreparedTaskFinalization, applyTaskFinalization, prepareTaskFinalization, issueCapability as createFinalizationCapability, readTaskFinalizationReceipt, terminalResult };
 //# sourceMappingURL=finalization.js.map