@fitlab-ai/agent-infra 0.11.2 → 0.11.4

package/lib/task/finalization.ts

@@ -4,6 +4,7 @@ import { createHash, randomUUID } from 'node:crypto';
 
 import { syncPlatformComment } from '../platform/issue-comments.ts';
 import { canonicalizeSummaryBody } from '../platform/comment-safety.ts';
+import { backfillCompletionComments, inspectCompletionBackfillEligibility } from '../platform/completion-backfill.ts';
 import type { PlatformResult } from '../platform/types.ts';
 import { taskIssueIdentity } from '../platform/task-identities.ts';
 import { parseTaskFrontmatter } from './frontmatter.ts';
@@ -25,8 +26,8 @@ import {
   type OperationWarningSeverity
 } from './operation-outcome.ts';
 
-const RECEIPT_VERSION = 3 as const;
-const FINALIZATION_STEPS = ['lifecycle', 'task-comment', 'verification', 'summary', 'post-summary-verification'] as const;
+const RECEIPT_VERSION = 4 as const;
+const FINALIZATION_STEPS = ['lifecycle', 'task-comment', 'verification', 'summary'] as const;
 type FinalizationStep = typeof FINALIZATION_STEPS[number];
 type FinalizationStepState = 'pending' | 'done' | 'skipped';
 type FinalizationError = { code: string; message: string; retryable: boolean };
@@ -61,6 +62,7 @@ type TaskFinalizationOptions = Readonly<{
   controlBinding?: Readonly<{ generation: string; requestId: string }>;
   metadataProvider?: TaskLifecycleOptions['metadataProvider'];
   lifecycle?: typeof applyTaskLifecycle;
+  backfill?: typeof backfillCompletionComments;
   commentSync?: typeof syncPlatformComment;
   verify?: typeof verifyTaskEvent;
   preflight?: typeof verifyTaskEvent;
@@ -76,10 +78,8 @@ type TaskFinalizationReceipt = Readonly<{
   taskComment: FinalizationStepState;
   verification: FinalizationStepState;
   summary: FinalizationStepState;
-  postSummaryVerification: FinalizationStepState;
   warningProjection: WarningProjectionState;
   warnings: readonly FinalizationWarning[];
-  summarySha256: string | null;
   controlBinding?: Readonly<{ generation: string; requestId: string }>;
   updatedAt: string;
   lastError: FinalizationError | null;
@@ -101,17 +101,17 @@ type TaskCommentSyncOutcome = Readonly<{
 }>;
 
 type TaskFinalizationResult = Readonly<{
-  status: 'completed' | 'failed' | 'blocked';
+  status: 'prepared' | 'completed' | 'failed' | 'blocked';
   changed: boolean;
   taskId: string | null;
+  backfill: TaskFinalizationStep | null;
   lifecycle: TaskFinalizationStep | null;
   taskComment: TaskFinalizationStep | null;
   verification: TaskFinalizationStep | null;
   summary: TaskFinalizationStep | null;
-  postSummaryVerification: TaskFinalizationStep | null;
   completedSteps: readonly FinalizationStep[];
   pendingSteps: readonly FinalizationStep[];
-  result: 'completed' | 'completed_with_warnings' | 'failed' | 'blocked';
+  result: 'prepared' | 'completed' | 'completed_with_warnings' | 'failed' | 'blocked';
   warnings: readonly OperationWarning[];
   error: FinalizationError | null;
 }>;
@@ -144,11 +144,11 @@ function failed(
     status: error.retryable ? 'blocked' : 'failed',
     changed: false,
     taskId,
+    backfill: null,
     lifecycle: null,
     taskComment: null,
     verification: null,
     summary: null,
-    postSummaryVerification: null,
     completedSteps: [],
     pendingSteps: [...FINALIZATION_STEPS],
     result: error.retryable ? 'blocked' : 'failed',
@@ -169,10 +169,8 @@ function emptyReceipt(taskId: string, controlBinding?: Readonly<{ generation: st
     taskComment: 'pending',
     verification: 'pending',
     summary: 'pending',
-    postSummaryVerification: 'pending',
     warningProjection: 'done',
     warnings: [],
-    summarySha256: null,
     ...(controlBinding ? { controlBinding } : {}),
     updatedAt: now(),
     lastError: null
@@ -208,10 +206,8 @@ function validateReceipt(value: unknown, taskId: string): TaskFinalizationReceip
     || !states.includes(String(receipt.taskComment))
     || !states.includes(String(receipt.verification))
     || !states.includes(String(receipt.summary))
-    || !states.includes(String(receipt.postSummaryVerification))
     || !['pending', 'done'].includes(String(receipt.warningProjection))
     || !Array.isArray(receipt.warnings) || receipt.warnings.some((warning) => !validWarning(warning))
-    || (receipt.summarySha256 !== null && (typeof receipt.summarySha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(receipt.summarySha256)))
     || typeof receipt.updatedAt !== 'string'
     || (receipt.lastError !== null && (typeof receipt.lastError !== 'object' || Array.isArray(receipt.lastError)))
     || (receipt.controlBinding !== undefined && (!controlBinding || typeof controlBinding !== 'object'
@@ -250,7 +246,7 @@ function writeReceipt(repoRoot: string, receipt: TaskFinalizationReceipt): void
 function updateReceipt(
   repoRoot: string,
   receipt: TaskFinalizationReceipt,
-  patch: Partial<Pick<TaskFinalizationReceipt, 'lifecycle' | 'taskComment' | 'verification' | 'summary' | 'postSummaryVerification' | 'warningProjection' | 'warnings' | 'summarySha256' | 'controlBinding' | 'lastError'>>
+  patch: Partial<Pick<TaskFinalizationReceipt, 'lifecycle' | 'taskComment' | 'verification' | 'summary' | 'warningProjection' | 'warnings' | 'controlBinding' | 'lastError'>>
 ): TaskFinalizationReceipt {
   const current = readReceipt(repoRoot, receipt.taskId);
   if (!current || current.receiptId !== receipt.receiptId) throw capabilityError(
@@ -272,7 +268,6 @@ function pendingSteps(receipt: TaskFinalizationReceipt): FinalizationStep[] {
 
 function stepState(receipt: TaskFinalizationReceipt, step: FinalizationStep): FinalizationStepState {
   if (step === 'task-comment') return receipt.taskComment;
-  if (step === 'post-summary-verification') return receipt.postSummaryVerification;
   return receipt[step];
 }
 
@@ -319,7 +314,7 @@ function verificationFailure(result: TaskVerificationResult): FinalizationError
 }
 
 function warningFromError(
-  step: FinalizationStep,
+  step: string,
   error: FinalizationError,
   severity: OperationWarningSeverity = 'ACTION_REQUIRED'
 ): OperationWarning {
@@ -362,6 +357,76 @@ function resolveStepWarnings(receipt: TaskFinalizationReceipt, step: Finalizatio
     : warning);
 }
 
+function verificationWarnings(result: TaskVerificationResult): readonly OperationWarning[] {
+  const warnings: OperationWarning[] = [];
+  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 as Record<string, unknown>;
+      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): item is string => 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: TaskFinalizationReceipt,
+  result: TaskVerificationResult
+): readonly FinalizationWarning[] {
+  if (result.status === 'pass') return resolveStepWarnings(receipt, 'verification');
+  const observed = new Map<string, 'pass' | OperationWarning>();
+  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 as Record<string, unknown>;
+      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: TaskFinalizationReceipt): boolean {
+  return receipt.lifecycle !== 'done'
+    || receipt.taskComment === 'pending'
+    || receipt.verification === 'pending'
+    || receipt.warnings.some((warning) => warning.step === 'backfill' && warning.status === 'open');
+}
+
 function issueCapability(receipt: TaskFinalizationReceipt, scope: Exclude<FinalizationStep, 'lifecycle'> | 'warning-projection'): FinalizationCapability {
   return {
     receiptId: receipt.receiptId,
@@ -379,6 +444,15 @@ function capabilityError(code: 'FINALIZATION_CAPABILITY_STALE' | 'FINALIZATION_S
   return error;
 }
 
+function hasPreparedTaskDocument(repoRoot: string, taskId: string): boolean {
+  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: FinalizationMutation): string[] {
   return Object.keys(value).sort();
 }
@@ -456,9 +530,8 @@ function applyFinalizationReceiptMutationUnderLock(
   mutation: FinalizationMutation,
   consumed: Set<string>
 ): TaskFinalizationReceipt {
-  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) {
@@ -476,11 +549,10 @@ function applyFinalizationReceiptMutation(
   capability: FinalizationCapability,
   mutation: FinalizationMutation
 ): TaskFinalizationReceipt {
-  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', () =>
+  return withTaskExecutionLock(repoRoot, receipt.taskId, 'task-finalization.receipt-mutation', () =>
     applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, mutation, new Set<string>())
   );
 }
@@ -494,7 +566,10 @@ function reconcileWarningProjection(repoRoot: string, taskId: string, receipt: T
   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: FinalizationError = {
           code: projected.error?.code || 'FINALIZATION_WARNING_PROJECTION_FAILED',
@@ -598,15 +673,16 @@ async function syncPendingSummary(input: {
   commentSync: typeof syncPlatformComment;
 }): Promise<{ receipt: TaskFinalizationReceipt; step: TaskFinalizationStep; changed: boolean; error: FinalizationError | null }> {
   let { receipt } = input;
-  if (receipt.summary !== 'pending') {
-    return { receipt, step: { status: receipt.summary === 'skipped' ? 'skipped' : 'no-op', changed: false, error: null }, changed: false, error: null };
-  }
   try {
     const resolved = resolveTaskRef(input.taskId, { repoRoot: input.repoRoot });
-    if (!resolved.ok || resolved.state !== 'completed') throw Object.assign(new Error('completed task is unavailable for summary sync'), { code: 'SUMMARY_STAGING_INVALID' });
+    if (!resolved.ok || !hasPreparedTaskDocument(input.repoRoot, input.taskId)) throw Object.assign(new Error('prepared task is unavailable for summary sync'), { code: 'SUMMARY_STAGING_INVALID' });
+    if (!fs.existsSync(path.join(resolved.taskDir, '.delivery-summary.json'))) {
+      receipt = updateReceipt(input.repoRoot, receipt, { summary: 'skipped', lastError: null });
+      return { receipt, step: { status: 'skipped', changed: false, error: null }, changed: false, error: null };
+    }
     if (!taskIssueIdentity(parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8')))) {
       receipt = updateReceipt(input.repoRoot, receipt, {
-        summary: 'skipped', postSummaryVerification: 'skipped', summarySha256: null, lastError: null
+        summary: 'skipped', lastError: null
       });
       return { receipt, step: { status: 'skipped', changed: false, error: null }, changed: false, error: null };
     }
@@ -621,8 +697,7 @@ async function syncPendingSummary(input: {
       const resolvedWarning = receipt.warnings.some((warning) => warning.step === 'summary' && warning.status === 'open');
       const warnings = resolveStepWarnings(receipt, 'summary');
       receipt = updateReceipt(input.repoRoot, receipt, {
-        summary: skipped ? 'skipped' : 'done', postSummaryVerification: skipped ? 'skipped' : receipt.postSummaryVerification,
-        summarySha256: skipped ? null : summary.sha256,
+        summary: skipped ? 'skipped' : 'done',
         taskComment: resolvedWarning ? 'pending' : receipt.taskComment,
         warningProjection: warnings.some((warning) => warning.status === 'open') ? 'pending' : 'done',
         warnings,
@@ -648,20 +723,15 @@ async function syncPendingSummary(input: {
   }
 }
 
-function clearDeliverySummary(taskDir: string): void {
-  const file = path.join(taskDir, '.delivery-summary.json');
-  if (fs.existsSync(file)) fs.unlinkSync(file);
-}
-
 function terminalResult(
   taskId: string,
   receipt: TaskFinalizationReceipt,
-  steps: Partial<Pick<TaskFinalizationResult, 'lifecycle' | 'taskComment' | 'verification' | 'summary' | 'postSummaryVerification'>>,
+  steps: Partial<Pick<TaskFinalizationResult, 'backfill' | 'lifecycle' | 'taskComment' | 'verification' | 'summary'>>,
   changed: boolean,
   error: FinalizationError | null = null
 ): TaskFinalizationResult {
   const pending = pendingSteps(receipt);
-  const blocked = [steps.lifecycle, steps.taskComment, steps.verification, steps.summary, steps.postSummaryVerification].some((step) => step?.status === 'blocked');
+  const blocked = [steps.backfill, steps.lifecycle, steps.taskComment, steps.verification, steps.summary].some((step) => step?.status === 'blocked');
   const warnings = openWarnings(receipt);
   const postLifecyclePending = receipt.lifecycle === 'done' && (pending.some((step) => step !== 'lifecycle') || receipt.warningProjection === 'pending');
   const hardError = error?.code.startsWith('FINALIZATION_') || error?.code === 'TASK_FINALIZATION_RECEIPT_INVALID';
@@ -669,18 +739,18 @@ function terminalResult(
     status: hardError ? (error?.retryable ? 'blocked' : 'failed') : pending.length === 0 ? 'completed' : postLifecyclePending ? 'completed' : blocked ? 'blocked' : 'failed',
     changed,
     taskId,
+    backfill: steps.backfill ?? null,
     lifecycle: steps.lifecycle ?? null,
     taskComment: steps.taskComment ?? null,
     verification: steps.verification ?? null,
     summary: steps.summary ?? null,
-    postSummaryVerification: steps.postSummaryVerification ?? null,
     completedSteps: completedSteps(receipt),
     pendingSteps: pending,
     result: hardError
       ? (error?.retryable ? 'blocked' : 'failed')
-      : postLifecyclePending && (warnings.length > 0 || receipt.warningProjection === 'pending')
+      : postLifecyclePending
         ? 'completed_with_warnings'
-        : pending.length === 0 || postLifecyclePending
+        : pending.length === 0
           ? 'completed'
           : blocked
             ? 'blocked'
@@ -690,13 +760,32 @@ function terminalResult(
   };
 }
 
-async function applyUnderLock(
+function preparedResult(
+  taskId: string,
+  receipt: TaskFinalizationReceipt,
+  steps: Partial<Pick<TaskFinalizationResult, 'backfill' | 'lifecycle' | 'taskComment' | 'verification' | 'summary'>>,
+  changed: boolean
+): TaskFinalizationResult {
+  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: TaskFinalizationRequest,
   taskId: string,
   options: TaskFinalizationOptions
 ): Promise<TaskFinalizationResult> {
   const repoRoot = path.resolve(options.repoRoot);
   const lifecycle = options.lifecycle ?? applyTaskLifecycle;
+  const backfill = options.backfill ?? backfillCompletionComments;
   const commentSync = options.commentSync ?? syncPlatformComment;
   const verify = options.verify ?? verifyTaskEvent;
   const consumedCapabilities = new Set<string>();
@@ -736,136 +825,152 @@ async function applyUnderLock(
     }
   }
 
-  let lifecycleResult: TaskFinalizationStep | null = null;
   let changed = false;
-  try {
-    const resolved = resolveTaskRef(taskId, { repoRoot });
-    const registry = resolved.ok && resolved.state === 'completed' ? inspectShortIdRegistry(repoRoot) : null;
-    if (registry && registry.status !== 'valid') {
-      const detail: FinalizationError = {
-        code: 'TASK_FINALIZATION_SHORT_ID_REGISTRY_UNAVAILABLE',
-        message: `cannot verify canonical short-id registry: ${registry.error.code}: ${registry.error.message}`,
-        retryable: false
+  let backfillResult: TaskFinalizationStep | null = null;
+  let runBackfill = shouldRunBackfill(receipt);
+  if (!runBackfill && receipt.lifecycle === 'done') {
+    const eligibility = inspectCompletionBackfillEligibility(taskId, { cwd: repoRoot });
+    if (eligibility.status === 'failed') return failed(taskId, eligibility.error!, {
+      completedSteps: completedSteps(receipt), pendingSteps: pendingSteps(receipt), warnings: openWarnings(receipt)
+    });
+    runBackfill = eligibility.eligible;
+  }
+  if (receipt.lifecycle === 'done' && runBackfill && receipt.summary === 'done') {
+    receipt = updateReceipt(repoRoot, receipt, { summary: 'pending' });
+  }
+  if (runBackfill) try {
+    const result = await backfill(taskId, { agent: request.agent, cwd: repoRoot });
+    backfillResult = commentStep(result);
+    const issueNotLinked = result.status === 'no-op' && result.error?.code === 'ISSUE_NOT_LINKED';
+    if (!issueNotLinked && (result.status !== 'applied' && result.status !== 'no-op' || result.error)) {
+      const detail = backfillResult.error ?? {
+        code: 'COMPLETION_BACKFILL_FAILED', message: 'completion artifact backfill did not reach a successful terminal result', retryable: true
       };
-      receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: detail });
-      return terminalResult(taskId, receipt, {
-        lifecycle: { status: 'failed', changed: false, error: detail },
-        taskComment: null,
-        verification: null
-      }, changed, detail);
+      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);
     }
-    const shortIds = registry?.status === 'valid' ? registry.shortIds : null;
-    if (shortIds?.has(taskId)) {
-      const detail: FinalizationError = {
-        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 });
+    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' as const, 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, {
-        lifecycle: { status: 'failed', changed: false, error: detail },
-        taskComment: null,
-        verification: null
+        backfill: { status: 'blocked', changed: false, error: detail }
       }, changed, detail);
     }
-    const lifecycleDone = receipt.lifecycle === 'done' && resolved.ok && resolved.state === 'completed' && shortIds !== null;
-    if (lifecycleDone) {
+    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: TaskFinalizationStep | null = null;
+  try {
+    const resolved = resolveTaskRef(taskId, { repoRoot });
+    if (receipt.lifecycle === 'done' && resolved.ok && resolved.state === 'completed') {
       lifecycleResult = { status: 'no-op', changed: false, error: null };
       receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'done', lastError: null });
     } else {
       const result = lifecycle(
         { taskRef: taskId, intent: 'complete', agent: request.agent },
-        { repoRoot, ...(options.metadataProvider ? { metadataProvider: options.metadataProvider } : {}) }
+        { repoRoot, prepareOnly: true, ...(options.metadataProvider ? { metadataProvider: options.metadataProvider } : {}) }
       );
       lifecycleResult = lifecycleStep(result);
       if (result.status !== 'applied' && result.status !== 'no-op') {
         receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: lifecycleResult.error });
-        return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment: null, verification: null }, result.changed, lifecycleResult.error);
+        return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment: null, verification: null }, result.changed, lifecycleResult.error);
       }
-      changed = result.changed;
-      receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'done', lastError: null });
+      changed = changed || result.changed;
     }
   } catch (error) {
     const detail = errorOf(error, 'TASK_FINALIZATION_LIFECYCLE_FAILED');
     try { receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: detail }); } catch { /* preserve the primary error */ }
-    return failed(taskId, detail, { lifecycle: lifecycleResult });
+    return failed(taskId, detail, { backfill: backfillResult, lifecycle: lifecycleResult });
   }
 
   let taskComment: TaskFinalizationStep | null = null;
   receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-  const initialComment = await syncPendingTaskComment({
-    repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
-  });
-  receipt = initialComment.receipt;
-  taskComment = initialComment.step;
-  changed = changed || initialComment.changed;
-  if (initialComment.error) {
-    return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification: null }, changed, initialComment.error);
-  }
 
   let verification: TaskFinalizationStep | null = null;
-  try {
+  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 verificationPending = receipt.verification === 'pending';
+    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: 'complete-task.completed' },
+      { taskRef: taskId, event: verificationEvent },
       { 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);
-        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, { lifecycle: lifecycleResult, taskComment, verification }, changed, finalComment.error);
-        }
-      } else {
-        receipt = updateReceipt(repoRoot, receipt, { lastError: null });
+      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 };
-      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');
-        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;
-        if (warningComment.step.status !== 'no-op') taskComment = warningComment.step;
-        changed = changed || warningComment.changed;
+      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, { 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 {
-        const warnings = replaceWarning(receipt, warningFromError('verification', detail), 'open');
-        receipt = updateReceipt(repoRoot, receipt, {
-          verification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: detail
-        });
-      }
+      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);
@@ -875,7 +980,7 @@ async function applyUnderLock(
         retryable: true
       };
       return terminalResult(taskId, receipt, {
-        lifecycle: lifecycleResult, taskComment, verification: { status: 'blocked', changed: false, error: detail }
+        backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification: { status: 'blocked', changed: false, error: detail }
       }, changed, hardError);
     }
     try {
@@ -884,102 +989,52 @@ async function applyUnderLock(
       if (warningComment.step.status !== 'no-op') taskComment = warningComment.step;
       changed = changed || warningComment.changed;
     } catch { /* preserve the primary error */ }
-    return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification: { status: 'blocked', changed: false, error: detail } }, changed, detail);
+    return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification: { status: 'blocked', changed: false, error: detail } }, changed, detail);
+    }
   }
 
-  const 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) {
     receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-    const warningComment = await syncPendingTaskComment({
+    return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification, summary: summary.step }, changed, summary.error);
+  }
+  receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+  if (receipt.taskComment === 'pending') {
+    const finalComment = await syncPendingTaskComment({
       repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
     });
-    receipt = warningComment.receipt;
-    if (warningComment.step.status !== 'no-op') taskComment = warningComment.step;
-    changed = changed || warningComment.changed;
-    return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step }, changed, summary.error);
-  }
-
-  let postSummaryVerification: TaskFinalizationStep | null = null;
-  if (receipt.postSummaryVerification === 'skipped') {
-    postSummaryVerification = { status: 'skipped', changed: false, error: null };
-  } else if (receipt.postSummaryVerification !== 'pending') {
-    const replay = await commentSync(taskId, {
-      kind: 'summary', agent: request.agent, body: '', cwd: repoRoot, verifyOnly: true,
-      summaryAuthorization: { sha256: receipt.summarySha256 ?? '' }
-    });
-    postSummaryVerification = commentStep(replay);
-    if (replay.status !== 'applied' && replay.status !== 'no-op') {
-      const error = postSummaryVerification.error ?? { code: 'SUMMARY_VERIFICATION_FAILED', message: 'summary replay verification failed', retryable: true };
-      const warnings = replaceWarning(receipt, warningFromError('post-summary-verification', error), 'open');
-      receipt = updateReceipt(repoRoot, receipt, { postSummaryVerification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: error });
-      receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-      return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step, postSummaryVerification }, changed, error);
-    }
-  } else {
-    try {
-      const summaryVerification = await commentSync(taskId, {
-        kind: 'summary', agent: request.agent, body: '', cwd: repoRoot, verifyOnly: true,
-        summaryAuthorization: { sha256: receipt.summarySha256 ?? '' }
-      });
-      if (summaryVerification.status !== 'applied' && summaryVerification.status !== 'no-op') {
-        const error = commentStep(summaryVerification).error ?? { code: 'SUMMARY_VERIFICATION_FAILED', message: 'summary verification failed', retryable: true };
-        const warnings = replaceWarning(receipt, warningFromError('post-summary-verification', error), 'open');
-        receipt = updateReceipt(repoRoot, receipt, { postSummaryVerification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: error });
-        receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-        const warningComment = await syncPendingTaskComment({ repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities });
-        receipt = warningComment.receipt;
-        if (warningComment.step.status !== 'no-op') taskComment = warningComment.step;
-        changed = changed || warningComment.changed;
-        return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step, postSummaryVerification: commentStep(summaryVerification) }, changed, error);
-      }
-      const result = await verify({ taskRef: taskId, event: 'complete-task.completed' }, { repoRoot });
-      postSummaryVerification = verificationStep(result);
-      if (result.status === 'pass') {
-        const resolvedWarning = receipt.warnings.some((warning) => warning.step === 'post-summary-verification' && warning.status === 'open');
-        const warnings = resolveStepWarnings(receipt, 'post-summary-verification');
-        receipt = updateReceipt(repoRoot, receipt, {
-          postSummaryVerification: 'done', taskComment: resolvedWarning ? 'pending' : receipt.taskComment,
-          warningProjection: warnings.some((warning) => warning.status === 'open') ? 'pending' : 'done', warnings, lastError: null
-        });
-        receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-        const warningComment = await syncPendingTaskComment({ repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities });
-        receipt = warningComment.receipt;
-        if (warningComment.step.status !== 'no-op') taskComment = warningComment.step;
-        changed = changed || warningComment.changed;
-      } else {
-        const error = postSummaryVerification.error ?? { code: 'VERIFY_FAILED', message: 'post-summary verification failed', retryable: true };
-        const warnings = replaceWarning(receipt, warningFromError('post-summary-verification', error), 'open');
-        receipt = updateReceipt(repoRoot, receipt, { postSummaryVerification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: error });
-        receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-        const warningComment = await syncPendingTaskComment({ repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities });
-        receipt = warningComment.receipt;
-        if (warningComment.step.status !== 'no-op') taskComment = warningComment.step;
-        changed = changed || warningComment.changed;
-        return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step, postSummaryVerification }, changed, error);
-      }
-    } catch (error) {
-      const detail = errorOf(error, 'POST_SUMMARY_VERIFY_FAILED', true);
-      const warnings = replaceWarning(receipt, warningFromError('post-summary-verification', detail), 'open');
-      receipt = updateReceipt(repoRoot, receipt, { postSummaryVerification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: detail });
-      receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-      const warningComment = await syncPendingTaskComment({ repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities });
-      receipt = warningComment.receipt;
-      if (warningComment.step.status !== 'no-op') taskComment = warningComment.step;
-      changed = changed || warningComment.changed;
-      return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step, postSummaryVerification: { status: 'blocked', changed: false, error: detail } }, changed, detail);
+    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);
     }
   }
-  receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-  if (receipt.summary !== 'pending' && receipt.postSummaryVerification !== 'pending' && receipt.warningProjection === 'done' && openWarnings(receipt).length === 0) {
-    const resolved = resolveTaskRef(taskId, { repoRoot });
-    if (resolved.ok && resolved.state === 'completed') clearDeliverySummary(resolved.taskDir);
+  return preparedResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification, summary: summary.step }, changed);
+}
+
+async function prepareTaskFinalization(request: TaskFinalizationRequest, options: TaskFinalizationOptions): Promise<TaskFinalizationResult> {
+  if (request.intent !== 'complete' || !request.taskRef || !request.agent) {
+    return failed(null, { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'complete finalization requires taskRef and agent', retryable: false });
+  }
+  const repoRoot = path.resolve(options.repoRoot);
+  const resolved = resolveTaskRef(request.taskRef, { repoRoot });
+  if (!resolved.ok) return failed(resolved.taskId, { code: resolved.code, message: resolved.message, retryable: false });
+  try {
+    return await withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.prepare', () => prepareUnderLock(request, resolved.taskId, options));
+  } catch (error) {
+    const detail = error instanceof TaskExecutionLockError
+      ? { code: error.code, message: error.message, retryable: error.code === 'ORCHESTRATION_LOCK_BUSY' }
+      : errorOf(error, 'TASK_FINALIZATION_FAILED');
+    return failed(resolved.taskId, detail);
   }
-  return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step, postSummaryVerification }, changed);
 }
 
-async function applyTaskFinalization(request: TaskFinalizationRequest, options: TaskFinalizationOptions): Promise<TaskFinalizationResult> {
+async function commitPreparedTaskFinalization(request: TaskFinalizationRequest, options: TaskFinalizationOptions): Promise<TaskFinalizationResult> {
   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 });
   }
@@ -987,7 +1042,38 @@ async function applyTaskFinalization(request: TaskFinalizationRequest, options:
   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.complete', () => applyUnderLock(request, resolved.taskId, options));
+    return await withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.commit', () => {
+      const receipt = readReceipt(repoRoot, resolved.taskId);
+      if (!receipt) return failed(resolved.taskId, {
+        code: 'TASK_FINALIZATION_PREPARATION_REQUIRED', message: 'sandbox preparation receipt is unavailable', retryable: true
+      });
+      if (receipt.lifecycle === 'done' && resolved.state === 'completed') {
+        return terminalResult(resolved.taskId, receipt, { lifecycle: { status: 'no-op', changed: false, error: null } }, false);
+      }
+      if (receipt.taskComment === 'pending' || receipt.verification === 'pending' || receipt.summary === 'pending' || receipt.warningProjection === 'pending') {
+        return failed(resolved.taskId, {
+          code: 'TASK_FINALIZATION_PREPARATION_REQUIRED', message: 'sandbox preparation has pending external steps', retryable: true
+        }, { completedSteps: completedSteps(receipt), pendingSteps: pendingSteps(receipt), warnings: openWarnings(receipt) });
+      }
+      const registry = inspectShortIdRegistry(repoRoot);
+      if (registry.status !== 'valid') return failed(resolved.taskId, {
+        code: 'TASK_FINALIZATION_SHORT_ID_REGISTRY_UNAVAILABLE',
+        message: `cannot verify canonical short-id registry: ${registry.error.code}: ${registry.error.message}`,
+        retryable: false
+      });
+      const lifecycle = options.lifecycle ?? applyTaskLifecycle;
+      const result = lifecycle(
+        { taskRef: resolved.taskId, intent: 'complete', agent: request.agent },
+        { repoRoot, ...(options.metadataProvider ? { metadataProvider: options.metadataProvider } : {}) }
+      );
+      const step = lifecycleStep(result);
+      if (result.status !== 'applied' && result.status !== 'no-op') {
+        const updated = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: step.error });
+        return terminalResult(resolved.taskId, updated, { lifecycle: step }, result.changed, step.error);
+      }
+      const updated = updateReceipt(repoRoot, receipt, { lifecycle: 'done', lastError: null });
+      return terminalResult(resolved.taskId, updated, { lifecycle: step }, result.changed);
+    });
   } catch (error) {
     const detail = error instanceof TaskExecutionLockError
       ? { code: error.code, message: error.message, retryable: error.code === 'ORCHESTRATION_LOCK_BUSY' }
@@ -996,9 +1082,17 @@ async function applyTaskFinalization(request: TaskFinalizationRequest, options:
   }
 }
 
+async function applyTaskFinalization(request: TaskFinalizationRequest, options: TaskFinalizationOptions): Promise<TaskFinalizationResult> {
+  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