@fitlab-ai/agent-infra 0.11.7 → 0.11.9

package/dist/lib/task/finalization.js

@@ -5,8 +5,11 @@ 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 { inspectPlatformIssue, syncPlatformIssue } from '../platform/issues.js';
+import { resourceIdentityEquals } from '../platform/resource-identity.js';
 import { parseTaskFrontmatter } from './frontmatter.js';
-import { applyTaskLifecycle, inspectTaskLifecycleProgress } from './lifecycle.js';
+import { recoverPlatformOperations } from './platform-operation-recovery.js';
+import { applyTaskLifecycle, inspectTaskLifecycleProgress, previewTaskCompletion } from './lifecycle.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { inspectShortIdRegistry } from './short-id.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
@@ -329,19 +332,16 @@ function capabilityError(code, message) {
     Object.assign(error, { code });
     return error;
 }
-function hasPreparedTaskDocument(repoRoot, taskId) {
+function hasFinalizationTaskDocument(repoRoot, taskId) {
     const resolved = resolveTaskRef(taskId, { repoRoot });
-    if (!resolved.ok)
-        return false;
-    if (resolved.state === 'completed')
-        return true;
-    if (resolved.state !== 'active')
+    if (!resolved.ok || (resolved.state !== 'active' && resolved.state !== 'completed'))
         return false;
     try {
-        return parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8')).status === 'completed';
+        const journal = JSON.parse(fs.readFileSync(path.join(resolved.taskDir, '.task-lifecycle.json'), 'utf8'));
+        return journal.taskId === taskId && journal.intent === 'complete';
     }
     catch {
-        return false;
+        return resolved.state === 'completed';
     }
 }
 function mutationKeys(value) {
@@ -388,7 +388,14 @@ function mutationPatch(current, mutation) {
     if (mutation.scope === 'task-comment') {
         if (mutation.operation === 'succeeded') {
             const warnings = resolveStepWarnings(current, 'task-comment');
-            return { taskComment: mutation.state, warningProjection: warnings.length > 0 ? 'pending' : 'done', warnings, lastError: null };
+            const retryWithResolvedWarning = mutation.state === 'done'
+                && current.warnings.some((warning) => warning.step === 'task-comment' && warning.status === 'open');
+            return {
+                taskComment: retryWithResolvedWarning ? 'pending' : mutation.state,
+                warningProjection: warnings.length > 0 || retryWithResolvedWarning ? 'pending' : 'done',
+                warnings,
+                lastError: null
+            };
         }
         const warnings = replaceWarning(current, warningFromError('task-comment', mutation.error), 'open');
         return { taskComment: 'pending', warningProjection: 'pending', warnings, lastError: mutation.error };
@@ -413,8 +420,8 @@ function mutationPatch(current, mutation) {
         : { warningProjection: 'pending', lastError: mutation.error };
 }
 function applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, mutation, consumed) {
-    if (!hasPreparedTaskDocument(repoRoot, receipt.taskId)) {
-        throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires an active prepared task or a completed task');
+    if (!hasFinalizationTaskDocument(repoRoot, receipt.taskId)) {
+        throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires an active task or a completed task');
     }
     const current = readReceipt(repoRoot, receipt.taskId);
     if (!current || current.receiptId !== receipt.receiptId || current.revision !== receipt.revision) {
@@ -426,8 +433,8 @@ function applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability
     return next;
 }
 function applyFinalizationReceiptMutation(repoRoot, receipt, capability, mutation) {
-    if (!hasPreparedTaskDocument(repoRoot, receipt.taskId)) {
-        throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires an active prepared task or a completed task');
+    if (!hasFinalizationTaskDocument(repoRoot, receipt.taskId)) {
+        throw capabilityError('FINALIZATION_SCOPE_INVALID', 'finalization capability requires an active task or a completed task');
     }
     return withTaskExecutionLock(repoRoot, receipt.taskId, 'task-finalization.receipt-mutation', () => applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, mutation, new Set()));
 }
@@ -483,7 +490,15 @@ async function syncPendingTaskComment(input) {
         };
     }
     try {
-        const result = await commentSync(taskId, { kind: 'task', agent, cwd: repoRoot });
+        const result = await commentSync(taskId, {
+            kind: 'task', agent, cwd: repoRoot, dependency: 'required',
+            ...(input.projection ? {
+                taskProjection: {
+                    content: input.projection.content,
+                    sha256: createHash('sha256').update(input.projection.content).digest('hex')
+                }
+            } : {})
+        });
         const step = commentStep(result);
         if (result.status === 'applied' || result.status === 'no-op') {
             const skipped = result.error?.code === 'ISSUE_NOT_LINKED';
@@ -492,6 +507,14 @@ async function syncPendingTaskComment(input) {
                 scope: 'task-comment', operation: 'succeeded', state: skipped ? 'skipped' : 'done'
             }, consumedCapabilities);
             receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+            if (!skipped && receipt.taskComment === 'pending') {
+                const retry = await syncPendingTaskComment({
+                    ...input,
+                    receipt,
+                    projection: input.refreshProjection?.() ?? input.projection
+                });
+                return { ...retry, changed: result.changed || retry.changed };
+            }
             return { receipt, step: skipped ? { ...step, status: 'skipped' } : step, changed: result.changed, error: null };
         }
         const detail = step.error ?? { code: 'COMMENT_SYNC_FAILED', message: 'task comment synchronization failed', retryable: true };
@@ -540,8 +563,8 @@ async function syncPendingSummary(input) {
     let { receipt } = input;
     try {
         const resolved = resolveTaskRef(input.taskId, { repoRoot: input.repoRoot });
-        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 (!resolved.ok || (resolved.state !== 'active' && resolved.state !== 'completed'))
+            throw Object.assign(new Error('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 };
@@ -555,7 +578,8 @@ async function syncPendingSummary(input) {
         const summary = readDeliverySummary(resolved.taskDir, input.taskId);
         const result = await input.commentSync(input.taskId, {
             kind: 'summary', agent: input.agent, body: summary.body, cwd: input.repoRoot,
-            summaryAuthorization: { sha256: summary.sha256 }
+            summaryAuthorization: { sha256: summary.sha256 },
+            dependency: 'required'
         });
         const step = commentStep(result);
         if (result.status === 'applied' || result.status === 'no-op') {
@@ -565,7 +589,7 @@ async function syncPendingSummary(input) {
             receipt = updateReceipt(input.repoRoot, receipt, {
                 summary: skipped ? 'skipped' : 'done',
                 taskComment: resolvedWarning ? 'pending' : receipt.taskComment,
-                warningProjection: warnings.some((warning) => warning.status === 'open') ? 'pending' : 'done',
+                warningProjection: warnings.some((warning) => warning.status === 'open') || resolvedWarning ? 'pending' : 'done',
                 warnings,
                 lastError: null
             });
@@ -595,9 +619,12 @@ function terminalResult(taskId, receipt, steps, changed, error = null) {
     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';
+    const terminalVerificationPending = receipt.lifecycle === 'done' && receipt.verification === 'pending';
+    const resultError = error ?? (terminalVerificationPending ? steps.verification?.error : null) ?? null;
+    const hardError = error?.code.startsWith('FINALIZATION_') || error?.code === 'TASK_FINALIZATION_RECEIPT_INVALID'
+        || terminalVerificationPending;
     return {
-        status: hardError ? (error?.retryable ? 'blocked' : 'failed') : pending.length === 0 ? 'completed' : postLifecyclePending ? 'completed' : blocked ? 'blocked' : 'failed',
+        status: hardError ? (resultError?.retryable ? 'blocked' : 'failed') : pending.length === 0 ? 'completed' : postLifecyclePending ? 'completed' : blocked ? 'blocked' : 'failed',
         changed,
         taskId,
         backfill: steps.backfill ?? null,
@@ -608,7 +635,7 @@ function terminalResult(taskId, receipt, steps, changed, error = null) {
         completedSteps: completedSteps(receipt),
         pendingSteps: pending,
         result: hardError
-            ? (error?.retryable ? 'blocked' : 'failed')
+            ? (resultError?.retryable ? 'blocked' : 'failed')
             : postLifecyclePending
                 ? 'completed_with_warnings'
                 : pending.length === 0
@@ -617,7 +644,7 @@ function terminalResult(taskId, receipt, steps, changed, error = null) {
                         ? 'blocked'
                         : 'failed',
         warnings,
-        error: hardError ? error : postLifecyclePending ? null : error
+        error: hardError ? resultError : postLifecyclePending ? null : resultError
     };
 }
 function preparedResult(taskId, receipt, steps, changed) {
@@ -637,7 +664,8 @@ async function prepareUnderLock(request, taskId, options) {
     const lifecycle = options.lifecycle ?? applyTaskLifecycle;
     const backfill = options.backfill ?? backfillCompletionComments;
     const commentSync = options.commentSync ?? syncPlatformComment;
-    const verify = options.verify ?? verifyTaskEvent;
+    const issueSync = options.issueSync ?? syncPlatformIssue;
+    const issueInspect = options.issueInspect ?? inspectPlatformIssue;
     const consumedCapabilities = new Set();
     let receipt;
     try {
@@ -679,6 +707,101 @@ async function prepareUnderLock(request, taskId, options) {
             return failed(taskId, errorOf(error, 'TASK_FINALIZATION_PREFLIGHT_FAILED', true));
         }
     }
+    if (preflightState.ok && preflightState.state === 'active') {
+        const recovery = await recoverPlatformOperations(taskId, 'all', { agent: request.agent, cwd: repoRoot });
+        if (recovery.status !== 'applied' && recovery.status !== 'no-op') {
+            return failed(taskId, recovery.error ?? {
+                code: 'PLATFORM_OPERATION_RECOVERY_PENDING',
+                message: 'Pending platform operations remain unresolved',
+                retryable: true
+            });
+        }
+        const taskContent = fs.readFileSync(preflightState.taskMdPath, 'utf8');
+        const taskFrontmatter = parseTaskFrontmatter(taskContent);
+        const issueIdentity = taskIssueIdentity(taskFrontmatter);
+        if (issueIdentity) {
+            const base = typeof taskFrontmatter.delivery_base_ref === 'string' ? taskFrontmatter.delivery_base_ref.trim() : '';
+            let synced;
+            try {
+                synced = await issueSync(taskId, {
+                    agent: request.agent, cwd: repoRoot, requirements: true, issueType: true, fields: true,
+                    ...(base ? { inLabels: 'from-diff', base } : {}), dependency: 'required'
+                });
+            }
+            catch (error) {
+                const detail = errorOf(error, 'FINALIZATION_ISSUE_METADATA_FAILED', true);
+                return failed(taskId, detail);
+            }
+            const issueOperations = synced.operations;
+            const badOperation = issueOperations?.find((operation) => ['requirements', 'issue-type', 'fields', ...(base ? ['labels:in'] : [])].includes(operation.name)
+                && operation.status !== 'applied' && operation.status !== 'no-op'
+                && !(operation.name === 'requirements' && operation.status === 'skipped' && operation.reasonCode === 'NO_REQUIREMENTS_ANCHOR'));
+            if ((synced.status !== 'applied' && synced.status !== 'no-op') || synced.error || badOperation) {
+                const error = synced.error ?? {
+                    code: badOperation?.reasonCode || 'FINALIZATION_ISSUE_METADATA_UNCONFIRMED',
+                    message: `Required Issue metadata operation '${badOperation?.name ?? 'sync'}' was not confirmed`,
+                    retryable: true
+                };
+                return failed(taskId, errorOf(error, 'FINALIZATION_ISSUE_METADATA_FAILED', true));
+            }
+            let inspected;
+            try {
+                inspected = await issueInspect(taskId, { cwd: repoRoot });
+            }
+            catch (error) {
+                return failed(taskId, errorOf(error, 'FINALIZATION_ISSUE_INSPECT_FAILED', true));
+            }
+            if (inspected.status !== 'no-op' || inspected.error || !inspected.issue
+                || !resourceIdentityEquals(inspected.issue.identity, issueIdentity)) {
+                return failed(taskId, inspected.error ?? {
+                    code: 'FINALIZATION_ISSUE_IDENTITY_UNCONFIRMED',
+                    message: 'Required Issue metadata could not be reread under the bound Issue identity',
+                    retryable: true
+                });
+            }
+            for (const name of ['requirements', 'issue-type', 'fields', ...(base ? ['labels:in'] : [])]) {
+                const operation = issueOperations?.find((candidate) => candidate.name === name);
+                if (!operation)
+                    return failed(taskId, {
+                        code: 'FINALIZATION_ISSUE_METADATA_UNCONFIRMED',
+                        message: `Required Issue metadata operation '${name}' was not reported`, retryable: true
+                    });
+                const before = synced.issue;
+                const remote = inspected.issue;
+                if (name === 'requirements') {
+                    const expected = typeof operation.value === 'string' ? operation.value : before?.body;
+                    if (expected === undefined || remote.body !== expected)
+                        return failed(taskId, {
+                            code: 'FINALIZATION_ISSUE_REQUIREMENTS_UNCONFIRMED', message: 'Issue requirements did not match the verified target', retryable: true
+                        });
+                }
+                else if (name === 'issue-type') {
+                    const expected = typeof operation.value === 'string' ? operation.value : before?.issueType;
+                    if (!expected || remote.issueType !== expected)
+                        return failed(taskId, {
+                            code: 'FINALIZATION_ISSUE_TYPE_UNCONFIRMED', message: 'Issue Type did not match the verified target', retryable: true
+                        });
+                }
+                else if (name === 'labels:in') {
+                    const expected = Array.isArray(operation.value) ? operation.value : before?.labels;
+                    if (!expected || expected.filter((label) => label.startsWith('in:')).sort().join('\0')
+                        !== remote.labels.filter((label) => label.startsWith('in:')).sort().join('\0'))
+                        return failed(taskId, {
+                            code: 'FINALIZATION_IN_LABELS_UNCONFIRMED', message: 'Issue in-labels did not match the verified target', retryable: true
+                        });
+                }
+                else {
+                    const expected = operation.value && typeof operation.value === 'object'
+                        ? operation.value
+                        : before?.fields;
+                    if (!expected || Object.entries(expected).some(([field, value]) => remote.fields[field] !== value))
+                        return failed(taskId, {
+                            code: 'FINALIZATION_ISSUE_FIELDS_UNCONFIRMED', message: 'Pinned Issue fields did not match the verified target', retryable: true
+                        });
+                }
+            }
+        }
+    }
     let changed = false;
     let backfillResult = null;
     let runBackfill = shouldRunBackfill(receipt);
@@ -748,9 +871,10 @@ async function prepareUnderLock(request, taskId, options) {
     else
         backfillResult = { status: 'no-op', changed: false, error: null };
     let lifecycleResult = null;
+    let projection;
     try {
         const resolved = resolveTaskRef(taskId, { repoRoot });
-        if (receipt.lifecycle === 'done' && resolved.ok && resolved.state === 'completed') {
+        if (resolved.ok && resolved.state === 'completed') {
             lifecycleResult = { status: 'no-op', changed: false, error: null };
             receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'done', lastError: null });
         }
@@ -762,6 +886,12 @@ async function prepareUnderLock(request, taskId, options) {
                 return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment: null, verification: null }, result.changed, lifecycleResult.error);
             }
             changed = changed || result.changed;
+            if (result.timestamp && result.agentInfraVersion) {
+                projection = previewTaskCompletion(taskId, request.agent, {
+                    repoRoot,
+                    metadataProvider: () => ({ timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion })
+                });
+            }
         }
     }
     catch (error) {
@@ -774,88 +904,15 @@ async function prepareUnderLock(request, taskId, options) {
     }
     let taskComment = null;
     receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-    let verification = null;
-    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
-                });
-                receipt = finalComment.receipt;
-                if (finalComment.step.status !== 'no-op')
-                    taskComment = finalComment.step;
-                changed = changed || finalComment.changed;
-                if (finalComment.error) {
-                    return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification }, changed, finalComment.error);
-                }
-            }
-            else {
-                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
-                });
-                receipt = warningComment.receipt;
-                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);
-            }
-        }
-        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, {
-                    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);
-        }
-    }
+    const currentProjection = () => projection
+        ? previewTaskCompletion(taskId, request.agent, {
+            repoRoot,
+            metadataProvider: () => ({ timestamp: projection.timestamp, agentInfraVersion: projection.agentInfraVersion })
+        })
+        : undefined;
+    const verification = receipt.verification === 'done'
+        ? { status: 'no-op', changed: false, error: null }
+        : { status: 'skipped', changed: false, error: null };
     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 };
@@ -868,7 +925,7 @@ async function prepareUnderLock(request, taskId, options) {
     receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
     if (receipt.taskComment === 'pending') {
         const finalComment = await syncPendingTaskComment({
-            repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
+            repoRoot, taskId, agent: request.agent, receipt, projection: currentProjection(), refreshProjection: currentProjection, commentSync, consumedCapabilities
         });
         receipt = finalComment.receipt;
         taskComment = finalComment.step;
@@ -906,7 +963,7 @@ async function commitPreparedTaskFinalization(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.commit', () => {
+        return await withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.commit', async () => {
             if (options.controlBinding && options.manifestPath) {
                 try {
                     const manifest = readSandboxControlManifest(options.manifestPath);
@@ -958,7 +1015,7 @@ async function commitPreparedTaskFinalization(request, options) {
                 return failed(resolved.taskId, {
                     code: 'TASK_FINALIZATION_PREPARATION_REQUIRED', message: 'sandbox preparation receipt is unavailable', retryable: true
                 });
-            if (receipt.lifecycle === 'done' && resolved.state === 'completed') {
+            if (receipt.lifecycle === 'done' && receipt.verification !== 'pending' && resolved.state === 'completed') {
                 return terminalResult(resolved.taskId, receipt, { lifecycle: { status: 'no-op', changed: false, error: null } }, false);
             }
             if (options.controlBinding) {
@@ -997,7 +1054,7 @@ async function commitPreparedTaskFinalization(request, options) {
                     }
                 }
             }
-            if (receipt.taskComment === 'pending' || receipt.verification === 'pending' || receipt.summary === 'pending' || receipt.warningProjection === 'pending') {
+            if (receipt.taskComment === '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) });
@@ -1009,6 +1066,7 @@ async function commitPreparedTaskFinalization(request, options) {
                     message: `cannot verify canonical short-id registry: ${registry.error.code}: ${registry.error.message}`,
                     retryable: false
                 });
+            receipt = updateReceipt(repoRoot, receipt, { verification: 'pending' });
             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);
@@ -1016,8 +1074,80 @@ async function commitPreparedTaskFinalization(request, options) {
                 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);
+            let verificationResult;
+            try {
+                verificationResult = await (options.verify ?? verifyTaskEvent)({ taskRef: resolved.taskId, event: 'complete-task.completed' }, { repoRoot });
+            }
+            catch (error) {
+                const detail = errorOf(error, 'VERIFY_FAILED', true);
+                const warnings = replaceWarning(receipt, warningFromError('verification', detail), 'open');
+                let updated;
+                try {
+                    updated = updateReceipt(repoRoot, receipt, {
+                        lifecycle: 'done', verification: 'pending', taskComment: 'pending', warningProjection: 'pending',
+                        warnings, lastError: detail
+                    });
+                }
+                catch (persistCause) {
+                    const persistError = errorOf(persistCause, 'FINALIZATION_RECEIPT_WRITE_FAILED', true);
+                    persistError.code = 'FINALIZATION_RECEIPT_WRITE_FAILED';
+                    persistError.message = `${persistError.message}; verification also failed: ${detail.code}: ${detail.message}`;
+                    return failed(resolved.taskId, persistError, {
+                        changed: result.changed,
+                        lifecycle: step,
+                        verification: { status: 'blocked', changed: false, error: persistError },
+                        completedSteps: completedSteps(receipt), pendingSteps: pendingSteps(receipt), warnings: openWarnings(receipt)
+                    });
+                }
+                const verification = { status: detail.retryable ? 'blocked' : 'failed', changed: false, error: detail };
+                return terminalResult(resolved.taskId, updated, { lifecycle: step, verification }, result.changed, detail);
+            }
+            const verification = verificationStep(verificationResult);
+            if (verificationResult.status === 'pass') {
+                const resolvedVerificationWarning = receipt.warnings.some((warning) => warning.step === 'verification' && warning.status === 'open');
+                const warnings = applyVerificationWarnings(receipt, verificationResult);
+                const hasOpenWarnings = warnings.some((warning) => warning.status === 'open');
+                let updated;
+                try {
+                    updated = updateReceipt(repoRoot, receipt, {
+                        lifecycle: 'done', verification: 'done',
+                        taskComment: resolvedVerificationWarning ? 'pending' : receipt.taskComment,
+                        warningProjection: hasOpenWarnings ? 'pending' : 'done', warnings, lastError: null
+                    });
+                }
+                catch (persistCause) {
+                    const persistError = errorOf(persistCause, 'FINALIZATION_RECEIPT_WRITE_FAILED', true);
+                    persistError.code = 'FINALIZATION_RECEIPT_WRITE_FAILED';
+                    return failed(resolved.taskId, persistError, {
+                        changed: result.changed,
+                        lifecycle: step,
+                        verification,
+                        completedSteps: completedSteps(receipt), pendingSteps: pendingSteps(receipt), warnings: openWarnings(receipt)
+                    });
+                }
+                return terminalResult(resolved.taskId, updated, { lifecycle: step, verification }, result.changed);
+            }
+            const detail = verification.error ?? { code: 'VERIFY_FAILED', message: 'verification failed', retryable: true };
+            const warnings = applyVerificationWarnings(receipt, verificationResult);
+            let updated;
+            try {
+                updated = updateReceipt(repoRoot, receipt, {
+                    lifecycle: 'done', verification: 'pending', taskComment: 'pending', warningProjection: 'pending',
+                    warnings, lastError: detail
+                });
+            }
+            catch (persistCause) {
+                const persistError = errorOf(persistCause, 'FINALIZATION_RECEIPT_WRITE_FAILED', true);
+                persistError.code = 'FINALIZATION_RECEIPT_WRITE_FAILED';
+                persistError.message = `${persistError.message}; verification also failed: ${detail.code}: ${detail.message}`;
+                return failed(resolved.taskId, persistError, {
+                    changed: result.changed,
+                    lifecycle: step,
+                    verification: { status: 'blocked', changed: false, error: persistError },
+                    completedSteps: completedSteps(receipt), pendingSteps: pendingSteps(receipt), warnings: openWarnings(receipt)
+                });
+            }
+            return terminalResult(resolved.taskId, updated, { lifecycle: step, verification }, result.changed, detail);
         });
     }
     catch (error) {

package/dist/lib/task/lifecycle.js

@@ -4,7 +4,8 @@ import path from 'node:path';
 import { appendActivityEntry, locateActivityLog } from './activity-log.js';
 import { artifactFamilyCatalog, inspectArtifactDirectory } from './artifact-lifecycle.js';
 import { parseArtifactName } from './artifact-name.js';
-import { parseTypedTaskFrontmatter } from './frontmatter.js';
+import { parseTypedTaskFrontmatter, updateTaskFrontmatter } from './frontmatter.js';
+import { upsertSection } from './sections.js';
 import { locateHotTaskDirs, resolveTaskRef, TASK_ID_RE } from './resolve-ref.js';
 import { configuredShortIdLength, executeShortIdCommand, loadShortIdByTaskId, mutateShortIdRegistry } from './short-id.js';
 import { captureTaskWriteMetadata, writeTask } from './write.js';
@@ -261,6 +262,31 @@ function mutationsFor(request, content, metadata, restoredFiles, allowMissingAct
     }
     return mutations;
 }
+function previewTaskCompletion(taskRef, agent, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        throw Object.assign(new Error(resolved.message), { code: resolved.code });
+    if (resolved.state !== 'active')
+        throw Object.assign(new Error(`task ${resolved.taskId} is ${resolved.state}, expected active`), { code: 'TASK_STATE_MISMATCH' });
+    const original = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    const metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
+    if (!isValidAgentInfraVersion(metadata.agentInfraVersion))
+        throw Object.assign(new Error('metadata agentInfraVersion is invalid'), { code: 'LIFECYCLE_METADATA_FAILED' });
+    const mutations = mutationsFor({ taskRef: resolved.taskId, intent: 'complete', agent }, original, metadata, 0);
+    if (!Array.isArray(mutations))
+        throw Object.assign(new Error(mutations.message), { code: mutations.code });
+    let content = original;
+    for (const mutation of mutations) {
+        if (mutation.kind === 'frontmatter')
+            content = updateTaskFrontmatter(content, mutation.set, mutation.remove);
+        else if (mutation.kind === 'section')
+            content = upsertSection(content, mutation).content;
+        else
+            throw Object.assign(new Error('completion projection contains an unsupported mutation'), { code: 'LIFECYCLE_PROJECTION_INVALID' });
+    }
+    content = updateTaskFrontmatter(content, { updated_at: metadata.timestamp, agent_infra_version: metadata.agentInfraVersion });
+    return { taskId: resolved.taskId, content, timestamp: metadata.timestamp, agentInfraVersion: metadata.agentInfraVersion };
+}
 function writeJournal(file, journal, io, create = false) {
     const temporary = `${file}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
     io.writeFileSync(temporary, `${JSON.stringify(journal, null, 2)}\n`, 'wx');
@@ -593,6 +619,16 @@ function applyTaskLifecycle(requestInput, options = {}) {
             completed.add('registry-committed');
     }
     let taskOperations = [];
+    if (options.prepareOnly && !matchingCompletion(io.readFileSync(path.join(sourcePath, 'task.md')), request, restoredFiles)) {
+        return {
+            ...failed(request, { code: '', message: '' }), status: 'applied', changed: true, error: null,
+            taskId, sourceState, targetState: spec.target, sourcePath, targetPath,
+            task: { operations: [] }, directory: { effect: 'unchanged', changed: false },
+            shortId: { effect: 'unchanged', shortId: null, changed: false },
+            timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion,
+            journalPath, completedSteps: [...completed], pendingSteps: STEPS.filter((step) => !completed.has(step))
+        };
+    }
     if (matchingCompletion(io.readFileSync(path.join(sourcePath, 'task.md')), request, restoredFiles))
         completed.add('task-written');
     if (!completed.has('task-written')) {
@@ -724,5 +760,5 @@ function applyTaskLifecycle(requestInput, options = {}) {
         journalPath, completedSteps: [...completed], pendingSteps: []
     };
 }
-export { lifecycleIntentCatalog, lifecycleFailureCatalog, lifecycleProducerCatalog, applyTaskLifecycle };
+export { lifecycleIntentCatalog, lifecycleFailureCatalog, lifecycleProducerCatalog, applyTaskLifecycle, previewTaskCompletion };
 //# sourceMappingURL=lifecycle.js.map