@fitlab-ai/agent-infra 0.11.3 → 0.11.5

package/dist/lib/task/finalization.js

@@ -3,16 +3,19 @@ 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';
+import { applyTaskLifecycle, inspectTaskLifecycleProgress } from './lifecycle.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { inspectShortIdRegistry } from './short-id.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
 import { verifyTaskEvent } from './verification.js';
 import { projectFinalizationWarning } from './workflow-warning-intents.js';
 import { mergeOperationWarnings } from './operation-outcome.js';
+import { readTaskFinalizationHandoff } from './finalization-handoff.js';
+import { readSandboxControlManifest } from '../sandbox/control/lifecycle.js';
+import { validateSandboxControlIdentity } from '../sandbox/control/identity-sentinel.js';
 const RECEIPT_VERSION = 4;
 const FINALIZATION_STEPS = ['lifecycle', 'task-comment', 'verification', 'summary'];
 function finalizationRoot(repoRoot) {
@@ -89,19 +92,32 @@ function validateReceipt(value, taskId) {
     const receipt = value;
     const controlBinding = receipt.controlBinding;
     const states = ['pending', 'done', 'skipped'];
-    if (receipt.version !== RECEIPT_VERSION || receipt.taskId !== taskId || receipt.intent !== 'complete'
+    const requiredKeys = [
+        'version', 'taskId', 'intent', 'receiptId', 'revision', 'lifecycle', 'taskComment',
+        'verification', 'summary', 'warningProjection', 'warnings', 'updatedAt', 'lastError'
+    ];
+    if (receipt.controlBinding !== undefined)
+        requiredKeys.push('controlBinding');
+    if (Object.keys(receipt).sort().join('\0') !== requiredKeys.sort().join('\0')
+        ||
+            receipt.version !== RECEIPT_VERSION || receipt.taskId !== taskId || receipt.intent !== 'complete'
         || typeof receipt.receiptId !== 'string' || receipt.receiptId.length === 0
         || !Number.isSafeInteger(receipt.revision) || Number(receipt.revision) < 0
-        || !states.includes(String(receipt.lifecycle))
-        || !states.includes(String(receipt.taskComment))
-        || !states.includes(String(receipt.verification))
-        || !states.includes(String(receipt.summary))
-        || !['pending', 'done'].includes(String(receipt.warningProjection))
+        || !states.includes(receipt.lifecycle)
+        || !states.includes(receipt.taskComment)
+        || !states.includes(receipt.verification)
+        || !states.includes(receipt.summary)
+        || !['pending', 'done'].includes(receipt.warningProjection)
         || !Array.isArray(receipt.warnings) || receipt.warnings.some((warning) => !validWarning(warning))
-        || typeof receipt.updatedAt !== 'string'
-        || (receipt.lastError !== null && (typeof receipt.lastError !== 'object' || Array.isArray(receipt.lastError)))
+        || typeof receipt.updatedAt !== 'string' || receipt.updatedAt.length === 0
+        || (receipt.lastError !== null && (typeof receipt.lastError !== 'object' || Array.isArray(receipt.lastError)
+            || Object.keys(receipt.lastError).sort().join('\0') !== ['code', 'message', 'retryable'].join('\0')
+            || typeof receipt.lastError.code !== 'string'
+            || typeof receipt.lastError.message !== 'string'
+            || typeof receipt.lastError.retryable !== 'boolean'))
         || (receipt.controlBinding !== undefined && (!controlBinding || typeof controlBinding !== 'object'
             || Array.isArray(controlBinding)
+            || Object.keys(controlBinding).sort().join('\0') !== ['generation', 'requestId'].join('\0')
             || typeof controlBinding.generation !== 'string' || controlBinding.generation.length === 0
             || typeof controlBinding.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(controlBinding.requestId))))
         throw new Error('receipt schema is invalid');
@@ -134,6 +150,12 @@ function writeReceipt(repoRoot, receipt) {
         throw error;
     }
 }
+export function bindTaskFinalizationReceipt(repoRoot, taskId, controlBinding) {
+    const receipt = readReceipt(path.resolve(repoRoot), taskId);
+    if (!receipt)
+        throw new Error('TASK_FINALIZATION_PREPARATION_REQUIRED');
+    return updateReceipt(path.resolve(repoRoot), receipt, { controlBinding, lastError: null });
+}
 function updateReceipt(repoRoot, receipt, patch) {
     const current = readReceipt(repoRoot, receipt.taskId);
     if (!current || current.receiptId !== receipt.receiptId)
@@ -221,6 +243,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 +329,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 +413,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 +426,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 +440,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 +540,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 +620,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;
@@ -528,8 +651,15 @@ async function applyUnderLock(request, taskId, options) {
         return failed(taskId, errorOf(error, 'TASK_FINALIZATION_RECEIPT_INVALID'));
     }
     if (options.controlBinding && (receipt.controlBinding?.generation !== options.controlBinding.generation
-        || receipt.controlBinding.requestId !== options.controlBinding.requestId))
-        receipt = updateReceipt(repoRoot, receipt, { controlBinding: options.controlBinding });
+        || receipt.controlBinding.requestId !== options.controlBinding.requestId)) {
+        const state = resolveTaskRef(taskId, { repoRoot });
+        if (!(receipt.lifecycle === 'done' && state.ok && state.state === 'completed')) {
+            return failed(taskId, {
+                code: 'TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE',
+                message: 'canonical receipt is not bound to the current sandbox request', retryable: false
+            });
+        }
+    }
     const preflightState = resolveTaskRef(taskId, { repoRoot });
     if (options.preflight && preflightState.ok && preflightState.state === 'active') {
         try {
@@ -551,80 +681,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 +774,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 +807,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 +866,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 +888,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 +897,141 @@ 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', () => {
+            if (options.controlBinding && options.manifestPath) {
+                try {
+                    const manifest = readSandboxControlManifest(options.manifestPath);
+                    const identity = validateSandboxControlIdentity({
+                        publicStatusDir: manifest.publicStatusDir,
+                        root: path.dirname(path.resolve(options.manifestPath)),
+                        mode: manifest.mode,
+                        taskId: manifest.taskId,
+                        generation: manifest.generation,
+                        controlRootId: manifest.controlRootId
+                    });
+                    if (identity.state !== 'valid' || manifest.taskId !== resolved.taskId
+                        || manifest.generation !== options.controlBinding.generation
+                        || fs.realpathSync.native(manifest.repoRoot) !== fs.realpathSync.native(repoRoot)) {
+                        throw new Error('current sandbox manifest does not match finalization request');
+                    }
+                }
+                catch (error) {
+                    return failed(resolved.taskId, {
+                        code: 'TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE',
+                        message: error instanceof Error ? error.message : String(error), retryable: false
+                    });
+                }
+            }
+            let receipt = readReceipt(repoRoot, resolved.taskId);
+            if (!receipt && options.controlBinding && options.handoffDirectory && request.handoffSha256) {
+                try {
+                    const handoff = readTaskFinalizationHandoff(options.handoffDirectory, resolved.taskId, options.controlBinding, request.handoffSha256);
+                    receipt = validateReceipt(handoff.receipt, resolved.taskId);
+                    if (receipt.lifecycle !== 'pending')
+                        throw new Error('handoff lifecycle must be pending');
+                    if (inspectTaskLifecycleProgress(repoRoot, resolved.taskId, request.agent) === 'unknown') {
+                        throw new Error('TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE');
+                    }
+                    writeReceipt(repoRoot, receipt);
+                    try {
+                        handoff.cleanup();
+                    }
+                    catch { /* keep the persisted canonical receipt usable */ }
+                }
+                catch (error) {
+                    return failed(resolved.taskId, {
+                        code: 'TASK_FINALIZATION_HANDOFF_INVALID',
+                        message: error instanceof Error ? error.message : String(error), retryable: false
+                    });
+                }
+            }
+            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 (options.controlBinding) {
+                const proof = inspectTaskLifecycleProgress(repoRoot, resolved.taskId, request.agent);
+                const oldBinding = receipt.controlBinding;
+                if (!oldBinding || oldBinding.generation !== options.controlBinding.generation || proof === 'unknown') {
+                    return failed(resolved.taskId, {
+                        code: 'TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE',
+                        message: 'canonical receipt has no valid host recovery proof', retryable: false
+                    });
+                }
+                if (oldBinding.requestId !== options.controlBinding.requestId && proof === 'not-started') {
+                    if (receipt.lifecycle !== 'pending' || !options.handoffDirectory || !request.handoffSha256) {
+                        return failed(resolved.taskId, {
+                            code: 'TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE',
+                            message: 'pending receipt cannot be rebound without a current handoff', retryable: false
+                        });
+                    }
+                    try {
+                        const handoff = readTaskFinalizationHandoff(options.handoffDirectory, resolved.taskId, options.controlBinding, request.handoffSha256);
+                        const nextReceipt = validateReceipt(handoff.receipt, resolved.taskId);
+                        if (nextReceipt.receiptId !== receipt.receiptId || nextReceipt.intent !== receipt.intent
+                            || nextReceipt.lifecycle !== 'pending')
+                            throw new Error('handoff is not continuous with canonical receipt');
+                        receipt = updateReceipt(repoRoot, receipt, { controlBinding: options.controlBinding });
+                        try {
+                            handoff.cleanup();
+                        }
+                        catch { /* keep the persisted canonical receipt usable */ }
+                    }
+                    catch (error) {
+                        return failed(resolved.taskId, {
+                            code: 'TASK_FINALIZATION_HANDOFF_INVALID',
+                            message: error instanceof Error ? error.message : String(error), retryable: 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