@fitlab-ai/agent-infra 0.11.3 → 0.11.4

package/dist/lib/task/finalization.js

@@ -3,7 +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 } from '../platform/completion-backfill.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';
@@ -221,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,
@@ -236,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();
 }
@@ -305,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) {
@@ -319,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}`;
@@ -334,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',
@@ -433,8 +518,12 @@ async function syncPendingSummary(input) {
     let { receipt } = input;
     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', lastError: null
@@ -509,7 +598,19 @@ 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;
@@ -551,80 +652,87 @@ async function applyUnderLock(request, taskId, options) {
     }
     let changed = false;
     let backfillResult = null;
-    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
-            };
+    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' });
+            }
+        }
+        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: backfillResult,
+                backfill: { status: detail.retryable ? 'blocked' : 'failed', changed: false, error: detail },
                 completedSteps: completedSteps(receipt),
                 pendingSteps: pendingSteps(receipt)
             });
         }
-        changed = result.changed;
-        if (result.changed && receipt.taskComment !== 'pending') {
-            receipt = updateReceipt(repoRoot, receipt, { taskComment: 'pending' });
-        }
-    }
-    catch (error) {
-        const detail = errorOf(error, 'COMPLETION_BACKFILL_FAILED', true);
-        return failed(taskId, detail, {
-            backfill: { status: detail.retryable ? 'blocked' : 'failed', changed: false, error: detail },
-            completedSteps: completedSteps(receipt),
-            pendingSteps: pendingSteps(receipt)
-        });
-    }
+    else
+        backfillResult = { status: 'no-op', changed: false, error: null };
     let lifecycleResult = null;
     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, {
-                backfill: backfillResult,
-                lifecycle: { status: 'failed', changed: false, error: detail },
-                taskComment: null,
-                verification: null
-            }, changed, detail);
-        }
-        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, {
-                backfill: backfillResult,
-                lifecycle: { status: 'failed', changed: false, error: detail },
-                taskComment: null,
-                verification: null
-            }, changed, detail);
-        }
-        const lifecycleDone = receipt.lifecycle === 'done' && resolved.ok && resolved.state === 'completed' && shortIds !== null;
-        if (lifecycleDone) {
+        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, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment: null, verification: null }, result.changed, lifecycleResult.error);
             }
             changed = changed || result.changed;
-            receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'done', lastError: null });
         }
     }
     catch (error) {
@@ -637,27 +745,26 @@ async function applyUnderLock(request, taskId, options) {
     }
     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, { backfill: backfillResult, 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
@@ -671,72 +778,58 @@ async function applyUnderLock(request, taskId, options) {
                 }
             }
             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, { backfill: backfillResult, 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);
             }
-            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, {
-                backfill: backfillResult, 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 (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);
+            }
+            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, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification: { 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 = await syncPendingSummary({ repoRoot, taskId, agent: request.agent, receipt, commentSync });
+    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) {
@@ -744,9 +837,20 @@ async function applyUnderLock(request, taskId, options) {
         return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification, summary: summary.step }, changed, summary.error);
     }
     receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-    return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification, summary: summary.step }, changed);
+    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 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 });
     }
@@ -755,7 +859,7 @@ 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.prepare', () => prepareUnderLock(request, resolved.taskId, options));
     }
     catch (error) {
         const detail = error instanceof TaskExecutionLockError
@@ -764,5 +868,59 @@ async function applyTaskFinalization(request, options) {
         return failed(resolved.taskId, detail);
     }
 }
-export { applyFinalizationReceiptMutation, applyTaskFinalization, issueCapability as createFinalizationCapability, readTaskFinalizationReceipt, terminalResult };
+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 });
+    }
+    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.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
+            ? { code: error.code, message: error.message, retryable: error.code === 'ORCHESTRATION_LOCK_BUSY' }
+            : errorOf(error, 'TASK_FINALIZATION_FAILED');
+        return failed(resolved.taskId, detail);
+    }
+}
+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