@fitlab-ai/agent-infra 0.11.2 → 0.11.3

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 } 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;
@@ -104,11 +104,11 @@ type TaskFinalizationResult = Readonly<{
   status: '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';
@@ -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];
 }
 
@@ -598,15 +593,12 @@ 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 (!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 +613,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 +639,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 +655,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'
@@ -697,6 +683,7 @@ async function applyUnderLock(
 ): 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,8 +723,36 @@ async function applyUnderLock(
     }
   }
 
-  let lifecycleResult: TaskFinalizationStep | null = null;
   let changed = false;
+  let backfillResult: TaskFinalizationStep | null = 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
+      };
+      return failed(taskId, detail, {
+        backfill: backfillResult,
+        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)
+    });
+  }
+
+  let lifecycleResult: TaskFinalizationStep | null = null;
   try {
     const resolved = resolveTaskRef(taskId, { repoRoot });
     const registry = resolved.ok && resolved.state === 'completed' ? inspectShortIdRegistry(repoRoot) : null;
@@ -749,6 +764,7 @@ async function applyUnderLock(
       };
       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
@@ -763,6 +779,7 @@ async function applyUnderLock(
       };
       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
@@ -780,15 +797,15 @@ async function applyUnderLock(
       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;
+      changed = changed || result.changed;
       receipt = updateReceipt(repoRoot, receipt, { lifecycle: 'done', lastError: null });
     }
   } 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;
@@ -800,7 +817,7 @@ async function applyUnderLock(
   taskComment = initialComment.step;
   changed = changed || initialComment.changed;
   if (initialComment.error) {
-    return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification: null }, changed, initialComment.error);
+    return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification: null }, changed, initialComment.error);
   }
 
   let verification: TaskFinalizationStep | null = null;
@@ -826,7 +843,7 @@ async function applyUnderLock(
         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);
+          return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification }, changed, finalComment.error);
         }
       } else {
         receipt = updateReceipt(repoRoot, receipt, { lastError: null });
@@ -850,7 +867,7 @@ async function applyUnderLock(
         if (warningComment.step.status !== 'no-op') taskComment = warningComment.step;
         changed = changed || warningComment.changed;
       }
-      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);
@@ -875,7 +892,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,99 +901,18 @@ 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 = await syncPendingSummary({ repoRoot, taskId, agent: request.agent, receipt, commentSync });
   receipt = summary.receipt;
   changed = changed || summary.changed;
   if (summary.error) {
     receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-    const warningComment = await syncPendingTaskComment({
-      repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
-    });
-    receipt = warningComment.receipt;
-    if (warningComment.step.status !== 'no-op') taskComment = warningComment.step;
-    changed = changed || warningComment.changed;
-    return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step }, changed, summary.error);
-  }
-
-  let postSummaryVerification: 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);
-    }
+    return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification, summary: summary.step }, changed, summary.error);
   }
   receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-  if (receipt.summary !== 'pending' && receipt.postSummaryVerification !== 'pending' && receipt.warningProjection === 'done' && openWarnings(receipt).length === 0) {
-    const resolved = resolveTaskRef(taskId, { repoRoot });
-    if (resolved.ok && resolved.state === 'completed') clearDeliverySummary(resolved.taskDir);
-  }
-  return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification, summary: summary.step, postSummaryVerification }, changed);
+  return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification, summary: summary.step }, changed);
 }
 
 async function applyTaskFinalization(request: TaskFinalizationRequest, options: TaskFinalizationOptions): Promise<TaskFinalizationResult> {

package/lib/task/lifecycle.ts

@@ -58,7 +58,7 @@ type TaskLifecycleRequest =
   | { taskRef: string; intent: 'close-codescan'; agent: string; alertNumber: number; reason: string; dryRun?: boolean }
   | { taskRef: string; intent: 'close-dependabot'; agent: string; alertNumber: number; reason: string; dryRun?: boolean }
   | { taskRef: string; intent: 'restore'; agent: string; stagingDir: string; issueNumber: number; dryRun?: boolean }
-  | { taskRef: string; intent: 'recover-started'; agent: string; stage: 'analysis' | 'review-analysis' | 'plan' | 'review-plan' | 'code' | 'review-code'; round: number; artifact: string; reason: string; dryRun?: boolean };
+  | { taskRef: string; intent: 'recover-started'; agent: string; auto: true; dryRun?: boolean };
 
 type HotState = 'active' | 'blocked' | 'completed';
 type SourceState = HotState | 'staging';
@@ -209,7 +209,7 @@ function actionAndNote(request: TaskLifecycleRequest, restoredFiles = 0): { acti
   if (request.intent === 'complete') return { action: 'Complete Task', note: 'Task moved to completed/' };
   if (request.intent === 'close-codescan') return { action: 'Close Codescan', note: `Code Scanning alert #${request.alertNumber} dismissed: ${request.reason}` };
   if (request.intent === 'close-dependabot') return { action: 'Close Dependabot', note: `Dependabot alert #${request.alertNumber} dismissed: ${request.reason}` };
-  if (request.intent === 'recover-started') return { action: 'Recover Started', note: request.reason };
+  if (request.intent === 'recover-started') return { action: 'Recover Started', note: 'automatic recovery' };
   return { action: 'Restore Task', note: `Restored ${restoredFiles} files from Issue #${request.issueNumber}` };
 }
 

package/lib/task/manual-validation-receipt.ts

@@ -14,6 +14,7 @@ import {
 
 const MANUAL_VALIDATION_RECEIPT_SCHEMA = 'agent-infra/manual-validation-receipt';
 const MANUAL_VALIDATION_RECEIPT_VERSION = 1;
+const MANUAL_VALIDATION_RECEIPT_PLACEHOLDER = '[[manual-validation-receipt]]';
 
 type ManualValidationReceipt = Readonly<{
   schema: typeof MANUAL_VALIDATION_RECEIPT_SCHEMA;
@@ -73,13 +74,17 @@ function manualValidationFinalSummaryDigest(body: string): string {
   const projection = heading
     ? body.slice(heading.index, heading.index + heading[0].length + (nextSection?.index ?? afterHeading.length)).replace(/\s+$/u, '')
     : body;
-  const preimage = projection.replace(/receipt=(?:[a-f0-9]{64}|<receipt>)/gu, 'receipt=<receipt>');
+  const preimage = projection
+    .replace(/\n*<!--\s*canonical-pr-change-report\s*-->\s*/gu, '')
+    .replace(/<!--\s*manual-validation-receipt:\s*[\s\S]*?-->/gu, MANUAL_VALIDATION_RECEIPT_PLACEHOLDER)
+    .replace(/receipt=(?:[a-f0-9]{64}|<receipt>)/gu, 'receipt=<receipt>');
   return createHash('sha256').update(preimage, 'utf8').digest('hex');
 }
 
 function manualValidationFinalSummaryProjectionMatches(body: string, receipt: ManualValidationReceipt): boolean {
   const identity = `transaction=${receipt.transactionId}; receipt=${receipt.receiptDigest}; evidence=${receipt.evidenceDigest}; head=${receipt.prHeadSha}`;
-  return body.includes(identity) && manualValidationFinalSummaryDigest(body) === receipt.finalSummaryDigest;
+  return (body.includes(identity) || body.includes(MANUAL_VALIDATION_RECEIPT_PLACEHOLDER))
+    && manualValidationFinalSummaryDigest(body) === receipt.finalSummaryDigest;
 }
 
 function validateManualValidationReceipt(value: unknown, expected?: ManualValidationReceiptIdentity): ManualValidationReceiptResult {
@@ -137,6 +142,7 @@ function readManualValidationReceipt(taskDir: string, expected?: ManualValidatio
 export {
   MANUAL_VALIDATION_RECEIPT_SCHEMA,
   MANUAL_VALIDATION_RECEIPT_VERSION,
+  MANUAL_VALIDATION_RECEIPT_PLACEHOLDER,
   createManualValidationReceipt,
   manualValidationFinalSummaryDigest,
   manualValidationFinalSummaryProjectionMatches,

package/lib/task/orchestration.ts

@@ -1417,19 +1417,34 @@ function recoverPreparedOrchestrationDelegation(
   }
 }
 
+type ActivatedRecoveryEvent = Readonly<{
+  receiptId: string;
+  stage: DelegationStage;
+  round: number;
+  artifact: string;
+  startedAgent: string;
+  childId: string;
+  stopRevision: number;
+  consumer: string;
+  consumedAt: string;
+}>;
+
+function recoveryReceiptMatches(
+  receipt: DelegationReceipt,
+  taskId: string,
+  event: ActivatedRecoveryEvent
+): boolean {
+  return receipt.taskId === taskId
+    && receipt.stage === event.stage
+    && receipt.round === event.round
+    && receipt.artifact === event.artifact
+    && receipt.childId === event.childId
+    && normalizeAgentToken(event.startedAgent) === normalizeAgentToken(receipt.client);
+}
+
 function recoverActivatedOrchestrationDelegationUnderLock(
   taskRef: string,
-  event: Readonly<{
-    receiptId: string;
-    stage: DelegationStage;
-    round: number;
-    artifact: string;
-    startedAgent: string;
-    childId: string;
-    stopRevision: number;
-    consumer: string;
-    consumedAt: string;
-  }>,
+  event: ActivatedRecoveryEvent,
   options: OrchestrationOptions = {}
 ): OrchestrationResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
@@ -1442,14 +1457,7 @@ function recoverActivatedOrchestrationDelegationUnderLock(
   ];
   const receipt = matches.find((candidate) => candidate.id === event.receiptId);
   if (!receipt) return failed('ORCHESTRATION_DELEGATION_MISSING', 'recovery receipt does not exist', resolved.taskId);
-  if (
-    receipt.taskId !== resolved.taskId
-    || receipt.stage !== event.stage
-    || receipt.round !== event.round
-    || receipt.artifact !== event.artifact
-    || receipt.childId !== event.childId
-    || normalizeAgentToken(event.startedAgent) !== normalizeAgentToken(receipt.client)
-  ) {
+  if (!recoveryReceiptMatches(receipt, resolved.taskId, event)) {
     return failed('ORCHESTRATION_PROVENANCE_MISMATCH', 'recovery selector does not match the delegation receipt', resolved.taskId);
   }
   if (receipt.status === 'aborted' && run.pendingDelegation === null) {
@@ -1461,6 +1469,9 @@ function recoverActivatedOrchestrationDelegationUnderLock(
   if (run.receipts.some((candidate) => candidate.id === receipt.id)) {
     return failed('ORCHESTRATION_RECEIPT_DUPLICATE', 'recovery receipt already exists in the completed receipt history', resolved.taskId);
   }
+  if (run.status !== 'running' || run.pause !== null) {
+    return failed('ORCHESTRATION_RECOVERY_UNSAFE', 'activated recovery cannot replace an unrelated orchestration pause', resolved.taskId);
+  }
   const aborted = abortActivatedDelegation(receipt, {
     childId: event.childId,
     stopRevision: event.stopRevision,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.11.2",
+  "version": "0.11.3",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/rules/lifecycle-orchestration.en.md

@@ -12,19 +12,33 @@
 
 `orchestration.json` records stages, model policy, child identity, and actual outcomes. Records use the current structure; trusted local operators may correct them and rerun validation. Existing task write locks and atomic writes protect updates.
 
-## Codex Host
+## Current Host
 
-- Use native spawn, wait, and App Server results from the current host; forward task operations through the existing broker.
+- Use native spawn, wait, and App Server results from the current host. A task-bound sandbox executes ordinary task orchestration locally in the current worktree.
+- Codex controller `open`, `verify`, and `close` remain restricted broker operations. After `open`, complete typed `verify` with the same lease proof before accepting the task, control-generation, and controller-instance binding.
 - Prepare validates the current task, model policy, and host preflight. Start and terminal records associate observed parent/child identity; failure must not be recorded as success.
-- Local execution does not require capability, controller attestation, or one-use consumption authority. Do not add automatic child discovery, spawn under a new lock protocol, orphan recovery, or a dedicated recovery protocol.
+- Client-specific preflight, event sources, and stop-evidence validation belong to the client adapter. The common orchestrator calls only the shared capability and contains no client-ID branches.
+
+## Activated Delegation Recovery
+
+- Before `begin-or-resume`, the orchestrator calls internal `task-lifecycle <task> recover-started --agent <client> --auto`. This entry is not user-facing and never infers child termination from missing liveness evidence.
+- The client adapter declares recovery support and validates trusted stop evidence for the current pending delegation. Unsupported adapters and runs without an activated pending delegation return `no-op`; uncertain termination fails closed.
+- Recovery consumes stop evidence, saves an aborted receipt while clearing pending, then appends the Activity Log terminal row. If the run save succeeds and the log write fails, the next invocation appends only the missing row.
+- Routing continues only after `no-op` or `applied`. Lost control responses are not reconstructed; the next operator invocation relies on the idempotent persisted state.
+
+## Current-only Cutover and Rollback
+
+- Enter a quiet window before cutover: let in-flight orchestration intents return, stop the wrapper/controller, and preserve the worktree, task/run/orchestration state, receipts, registration, and audit. For an unknown result, inspect local `status`/`route` before using existing recover/advance semantics; do not replay an old broker request.
+- Deploy or roll back the CLI, broker, controller adapter, and protocol as one versioned unit. After stopping the old container/broker, rebuild and run `ai sandbox start --recreate <task-ref>` to resume with a new control generation; never reuse an old token, proof, or request.
+- On either the new or rolled-back version, first confirm the same task through `status`/`route`, then require a successful typed controller `open`→`verify`. Keep the quiet window and evidence intact if any check fails; do not mix component versions or rewrite domain facts.
 
 ## Model Policy
 
 - A new run persists model and reasoning effort for both roles. Explicit policy is atomic across all four role fields; only a fully absent explicit policy may fall back to the current client's `agentClients[].orchestration`.
 - Route resolves requested model/effort by role, and prepare matches both before snapshotting. Native spawn must not inherit session defaults.
-- Native start records host-observed actual model/effort. Each mismatch needs its own fallback reason (the claude-code path may leave this blank and follow the recording rules instead), and requested values must never be fabricated as actual evidence.
+- Native start records host-observed actual model/effort. Fields declared unobservable by the adapter follow the recording rules; each observable mismatch needs its own fallback reason, and requested values must never be fabricated as actual evidence.
 - Model selection is labeled as a complete catalog, partial catalog, or interactive-only guidance; a local override enum must not be presented as complete.
-- claude-code's requested reasoning effort does not yet support per-role dispatch (concurrent tasks would race on a shared file); `delegationEvidence.actualReasoningEffort` is declared `spawn-ack`, meaning it is only recorded when honestly observed in a native spawn lifecycle event (Start/Stop) — it is not a promise of per-role dispatch and does not gate activation.
+- An adapter must declare any policy field it cannot dispatch per role. Values observed in host events are actual evidence only; they do not promise dispatch or gate activation.
 
 ## Stable Pause Conditions
 

package/templates/.agents/rules/lifecycle-orchestration.zh-CN.md

@@ -12,19 +12,33 @@
 
 `orchestration.json` 记录阶段、模型策略、child 身份及实际执行结果。记录必须符合当前结构；本地操作者可直接修正后重新校验。已有任务写锁与原子写入继续保护写操作。
 
-## Codex 宿主
+## 当前宿主
 
-- 使用当前宿主的原生 spawn、wait 与 App Server 结果；任务操作通过现有 broker 转发。
+- 使用当前宿主的原生 spawn、wait 与 App Server 结果；task-bound sandbox 在当前 worktree 本地执行普通任务编排。
+- Codex controller 的 `open`、`verify`、`close` 继续通过受限 broker 执行。`open` 后必须用同一 lease proof 完成 typed `verify`，再接受 task、control generation 和 controller instance 绑定。
 - prepare 校验当前任务、模型策略与宿主 preflight。启动和完成记录关联实际 parent/child 身份，失败不得写成成功。
-- 不要求 capability、controller attestation 或一次性消费授权本地实现；不新增 child 自动发现、锁内启动交接、孤立 child 恢复或专用恢复协议。
+- 客户端特有的 preflight、事件来源与停止证据校验由客户端适配器实现；公共总控只调用统一能力。不得在公共流程中新增客户端 ID 分支。
+
+## Activated delegation 自动恢复
+
+- 总控在 `begin-or-resume` 前调用内部 `task-lifecycle <task> recover-started --agent <client> --auto`。该入口不公开给用户，也不从缺少存活证据推断 child 已终止。
+- 客户端适配器决定是否支持恢复，并验证当前 pending delegation 的可信停止证据；不支持或没有 activated pending 时返回 `no-op`，无法确认停止时失败关闭。
+- 恢复按固定顺序消费停止证据、保存 aborted receipt 并清除 pending，再写 Activity Log 结束记录。任务状态已保存而日志未写时，下次调用只补日志。
+- 只有 `no-op` 或 `applied` 才能继续 route。控制响应丢失时不重建恢复结果；下一次人为调用依靠幂等状态继续。
+
+## Current-only 切换与回滚
+
+- 切换前进入静默窗口：等待在途编排 intent 返回，停止 wrapper/controller，并保留 worktree、task/run/orchestration 状态、receipts、registration 与 audit。结果未知时先用本地 `status`/`route` 判断 domain 是否已提交，再按现有 recover/advance 语义处理；旧 broker request 不重放。
+- CLI、broker、controller adapter 和协议必须作为同一版本单元部署或回退。停止旧 container/broker 后执行 rebuild 与 `ai sandbox start --recreate <task-ref>`，以新 control generation 恢复执行；旧 token、proof 和 request 不得复用。
+- 新版本或回退版本都必须先核对同一任务的 `status`/`route`，再要求 controller typed `open`→`verify` 成功。任一检查失败时继续保持静默并保留证据，不局部混用组件或改写 domain 事实。
 
 ## 模型策略
 
 - 新 run 必须固化 executor/reviewer 各自的 model 与 reasoning effort；显式策略必须四字段原子完整，完全没有显式字段时才读取当前 client 的 `agentClients[].orchestration`。重入不得静默改写策略。
 - route 按 role 返回 requested model/effort，prepare 必须在工作区快照前精确匹配两者；原生 spawn 不能继承会话默认值。
-- 原生 start 必须记录宿主观察到的 actual model/effort。任一字段与 requested 不同时必须记录独立 fallback reason（claude-code 路径下允许留空，按记录规则处理）；requested 值不得补造 actual 证据。
+- 原生 start 必须记录宿主观察到的 actual model/effort。适配器声明无法观察的字段按记录规则处理；任一可观察字段与 requested 不同时必须记录独立 fallback reason，requested 值不得补造 actual 证据。
 - 模型选择能力必须标记 complete catalog、partial catalog 或 interactive-only guidance；局部 override 枚举不得冒充完整目录。
-- claude-code 的 requested reasoning effort 暂不支持按角色下发（跨任务共享文件存在写入竞态）；`delegationEvidence.actualReasoningEffort` 声明为 `spawn-ack`，语义为"仅能在宿主原生 spawn 生命周期事件（Start/Stop）里如实观察到时记录，不构成按角色下发的承诺，也不构成放行门禁"。
+- 客户端无法按角色下发的策略字段必须由适配器明确声明；宿主事件中观察到的值只作为实际证据，不构成下发承诺或放行门禁。
 
 ## 稳定暂停条件
 

package/templates/.agents/skills/complete-manual-validation/SKILL.en.md

@@ -21,7 +21,7 @@ Before generating the validation completion report, read `.agents/rules/evidence
 - This skill closes the manual-validation status in an existing PR summary comment; it does not create a parallel ordinary validation comment.
 - It must write `manual-validation.md` or `manual-validation-r{N}.md` so later PR summary refreshes can reuse the validation result.
 - If the `sync-pr` summary comment is missing, fail instead of creating a partial fallback summary; before the receipt, completion log, and final summary are all committed, the remote summary may only be pending/non-pass.
-- Before generating manual-validation artifact Markdown that will be synced to an Issue, read `.agents/rules/sync-content-generation.md` and follow its generator-side constraints; Issue sync remains transparent and does not parse or rewrite the body.
+- Before generating manual-validation artifact Markdown referenced by the task comment and PR summary, read `.agents/rules/sync-content-generation.md` and follow its generator-side constraints. Keep the artifact local instead of publishing it as an Issue artifact comment.
 - After this skill runs, update `task.md` immediately.
 
 Version stamp rule: when creating or updating `task.md` frontmatter, read `.agents/rules/version-stamp.md` first and write or refresh `agent_infra_version`.
@@ -106,7 +106,7 @@ The coordinator owns pending summary, receipt, completion log, final promotion,
 
 After the transaction coordinator succeeds, the core has atomically recorded `manual-validation.completed` with the same transaction/receipt/head identity. Do not append the Activity Log manually.
 
-If the task has a valid `platform_issue_identity`, run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`, then `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {manual-validation-artifact} --agent {standard-agent-token}`.
+If the task has a valid `platform_issue_identity`, run only `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`. Keep the manual-validation artifact as local evidence and PR-summary input; do not publish it as an Issue comment.
 
 ### 8. Verification Gate