@fitlab-ai/agent-infra 0.11.1 → 0.11.3

package/lib/agent-clients/adapters/codex-lifecycle/recovery.ts

@@ -0,0 +1,297 @@
+import fs from 'node:fs';
+
+import { createCodexLifecycleStore } from './store.ts';
+import type { StoredCodexLifecycle } from './store.ts';
+import { managedDelegationRole } from '../../../task/delegation-receipts.ts';
+import type { DelegationReceipt } from '../../../task/delegation-receipts.ts';
+import { normalizeAgentToken } from '../../tokens.ts';
+import { locateActivityLog, pairEntries, appendActivityEntry } from '../../../task/activity-log.ts';
+import type { ActivityLogSection, StepRow } from '../../../task/activity-log.ts';
+import { captureTaskWriteMetadata, writeTask } from '../../../task/write.ts';
+import { parseTypedTaskFrontmatter } from '../../../task/frontmatter.ts';
+import { resolveTaskRef } from '../../../task/resolve-ref.ts';
+import { resolveAgentRuntimeStoreRoot } from '../../../runtime/agent-runtime.ts';
+import {
+  recoverActivatedOrchestrationDelegationUnderLock,
+  readRun
+} from '../../../task/orchestration.ts';
+import type { OrchestrationOptions, OrchestrationRun } from '../../../task/orchestration.ts';
+import type {
+  AgentClientLifecycleRecoveryRequest,
+  AgentClientLifecycleRecoveryResult
+} from '../../adapter.ts';
+
+const ACTIONS = {
+  analysis: 'Analyze Task',
+  'review-analysis': 'Review Analysis',
+  plan: 'Plan Task',
+  'review-plan': 'Review Plan',
+  code: 'Code Task',
+  'review-code': 'Review Code'
+} as const;
+
+type RecoveryStage = keyof typeof ACTIONS;
+type LifecycleRecoveryRequest = AgentClientLifecycleRecoveryRequest;
+type LifecycleRecoveryResult = AgentClientLifecycleRecoveryResult;
+type LifecycleRecoveryOptions = Readonly<{
+  repoRoot?: string;
+  now?: () => string;
+  orchestration?: Pick<OrchestrationOptions, 'diagnosticLog' | 'now'>;
+  lifecycleStore?: ReturnType<typeof createCodexLifecycleStore>;
+  writeTask?: typeof writeTask;
+}>;
+
+type RecoveryCandidate = Readonly<{
+  receipt: DelegationReceipt;
+  row: StepRow;
+}>;
+
+function result(
+  request: LifecycleRecoveryRequest,
+  status: LifecycleRecoveryResult['status'],
+  extra: Partial<LifecycleRecoveryResult> = {}
+): LifecycleRecoveryResult {
+  return {
+    status,
+    changed: status === 'applied',
+    targetState: 'active',
+    requestRef: request.taskRef,
+    intent: 'recover-started',
+    taskId: null,
+    receiptId: null,
+    childId: null,
+    error: null,
+    ...extra
+  };
+}
+
+function failure(
+  request: LifecycleRecoveryRequest,
+  status: 'owner-unknown' | 'conflict',
+  code: string,
+  message: string,
+  extra: Partial<LifecycleRecoveryResult> = {}
+): LifecycleRecoveryResult {
+  return result(request, status, { error: { code, message }, ...extra });
+}
+
+function actionPattern(receipt: Pick<DelegationReceipt, 'stage' | 'round'>): RegExp | null {
+  const action = ACTIONS[receipt.stage as RecoveryStage];
+  if (!action) return null;
+  const escaped = action.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  return new RegExp(`^${escaped} \\(Round ${receipt.round}(?:, (?:fix for review-code(?:-r[2-9]|-r[1-9]\\d+)?.md|decision II-[1-9]\\d*))?\\)$`, 'u');
+}
+
+function openRows(section: ActivityLogSection): StepRow[] {
+  return pairEntries([...section.entries]).filter((row) => row.started !== '' && row.done === '');
+}
+
+function rowForReceipt(rows: readonly StepRow[], receipt: DelegationReceipt): StepRow[] {
+  const pattern = actionPattern(receipt);
+  return pattern ? rows.filter((row) => pattern.test(row.step)) : [];
+}
+
+function readLifecycleStore(
+  options: LifecycleRecoveryOptions,
+  repoRoot: string
+): ReturnType<typeof createCodexLifecycleStore> {
+  return options.lifecycleStore ?? createCodexLifecycleStore({
+    root: resolveAgentRuntimeStoreRoot({ repoRoot, store: 'lifecycle' }),
+    cliVersion: 'recovery',
+    now: options.now
+  });
+}
+
+function readStoredEvidence(
+  store: ReturnType<typeof createCodexLifecycleStore>,
+  childId: string
+): StoredCodexLifecycle | { missing: true } | { error: Error } {
+  try {
+    return store.read(childId);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes('was not found uniquely')) return { missing: true };
+    return { error: error instanceof Error ? error : new Error(message) };
+  }
+}
+
+function validateStopRecord(
+  record: StoredCodexLifecycle,
+  receipt: DelegationReceipt
+): { ok: true } | { ok: false; code: string; message: string } {
+  const start = record.state.startEvidence;
+  const stop = record.state.stopEvidence;
+  const provenance = receipt.lifecycleProvenance;
+  const host = receipt.hostEvidence;
+  if (
+    receipt.client !== 'codex'
+    || !provenance
+    || host?.kind !== 'codex-lifecycle-v2'
+    || !start
+    || !stop
+    || record.state.status !== 'stop-ready'
+    || stop.terminalStatus !== 'completed'
+    || stop.hookStopObserved !== true
+    || start.childThreadId !== receipt.childId
+    || start.parentThreadId !== receipt.parentId
+    || managedDelegationRole(start.nativeAgent) !== receipt.role
+    || start.hookDefinitionHash !== provenance.hookDefinitionHash
+    || host.hookDefinitionHash !== provenance.hookDefinitionHash
+    || host.capabilitySessionId !== provenance.capabilitySessionId
+    || host.capabilityTurnId !== provenance.capabilityTurnId
+    || host.capabilityToolUseId !== provenance.capabilityToolUseId
+    || host.spawnToolUseId !== start.spawnToolUseId
+    || !host.spawnObservedAt
+    || host.spawnObservedAt !== record.spawnObservedAt
+    || host.controllerInstanceDigest !== provenance.controllerInstanceDigest
+    || host.controlGeneration !== provenance.controlGeneration
+    || typeof host.controllerInstanceDigest !== 'string'
+    || typeof host.controlGeneration !== 'string'
+    || host.startRevision < 1
+    || record.revision <= host.startRevision
+    || record.state.child?.childThreadId !== receipt.childId
+    || record.state.stop?.childThreadId !== receipt.childId
+  ) {
+    return { ok: false, code: 'RECOVERY_STOP_EVIDENCE_INVALID', message: 'Codex stop evidence does not match the activated receipt' };
+  }
+  if (record.consumer !== null && record.consumer !== receipt.id) {
+    return { ok: false, code: 'RECOVERY_CONSUMER_CONFLICT', message: `Codex lifecycle evidence was consumed by '${record.consumer}'` };
+  }
+  return { ok: true };
+}
+
+function abortedCandidates(run: OrchestrationRun, rows: readonly StepRow[]): RecoveryCandidate[] {
+  const candidates = run.receipts.flatMap((receipt) => {
+    if (receipt.status !== 'aborted' || receipt.activatedAt === null || receipt.client !== 'codex') return [];
+    const matches = rowForReceipt(rows, receipt);
+    return matches.length === 1 ? [{ receipt, row: matches[0]! }] : [];
+  });
+  return candidates;
+}
+
+function appendRecoveryLog(
+  request: LifecycleRecoveryRequest,
+  taskId: string,
+  section: ActivityLogSection,
+  candidate: RecoveryCandidate,
+  repoRoot: string,
+  writer: typeof writeTask
+): LifecycleRecoveryResult {
+  const metadata = captureTaskWriteMetadata();
+  const body = appendActivityEntry(section, {
+    time: metadata.timestamp,
+    step: `${candidate.row.step} [aborted]`,
+    agent: request.agent,
+    note: `terminated Codex delegation; receipt=${candidate.receipt.id}; child=${candidate.receipt.childId}`
+  });
+  const written = writer({
+    taskRef: taskId,
+    expectedState: 'active',
+    mutations: [{ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body }]
+  }, { repoRoot, metadataProvider: () => metadata });
+  if (written.status === 'failed') {
+    return failure(request, 'owner-unknown', 'RECOVERY_LOG_WRITE_FAILED', written.error.message, {
+      taskId, receiptId: candidate.receipt.id, childId: candidate.receipt.childId
+    });
+  }
+  return result(request, 'applied', {
+    taskId, receiptId: candidate.receipt.id, childId: candidate.receipt.childId
+  });
+}
+
+function recoverStartedLifecycleUnderLock(
+  request: LifecycleRecoveryRequest,
+  options: LifecycleRecoveryOptions = {}
+): LifecycleRecoveryResult {
+  if (!request || request.intent !== 'recover-started' || request.auto !== true || normalizeAgentToken(request.agent) !== 'codex') {
+    return failure(request, 'conflict', 'RECOVERY_PAYLOAD_INVALID', 'automatic recovery requires a task and the Codex agent');
+  }
+  const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failure(request, 'conflict', resolved.code, resolved.message);
+  const taskId = resolved.taskId;
+  let content: string;
+  try {
+    content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    parseTypedTaskFrontmatter(content);
+  } catch (error) {
+    return failure(request, 'conflict', 'RECOVERY_TASK_INVALID', error instanceof Error ? error.message : String(error), { taskId });
+  }
+  const section = locateActivityLog(content);
+  if (!section) return failure(request, 'conflict', 'RECOVERY_LOG_INVALID', 'task has no unique Activity Log section', { taskId });
+  let run: OrchestrationRun | null;
+  try {
+    run = readRun(resolved.taskDir, options.orchestration);
+  } catch (error) {
+    return failure(request, 'owner-unknown', 'RECOVERY_ORCHESTRATION_UNKNOWN', error instanceof Error ? error.message : String(error), { taskId });
+  }
+  if (!run) return result(request, 'no-op', { taskId });
+
+  const rows = openRows(section);
+  const pending = run.pendingDelegation;
+  if (!pending) {
+    const candidates = abortedCandidates(run, rows);
+    if (candidates.length === 0) return result(request, 'no-op', { taskId });
+    if (candidates.length > 1) {
+      return failure(request, 'conflict', 'RECOVERY_CANDIDATE_AMBIGUOUS', 'more than one aborted delegation has an open lifecycle row', { taskId });
+    }
+    return appendRecoveryLog(request, taskId, section, candidates[0]!, resolved.repoRoot, options.writeTask ?? writeTask);
+  }
+  if (pending.status !== 'activated') return result(request, 'no-op', { taskId });
+  if (pending.client !== 'codex' || run.status !== 'running' || run.pause !== null) {
+    return failure(request, 'conflict', 'RECOVERY_ORCHESTRATION_INVALID', 'activated recovery requires one running Codex delegation', {
+      taskId, receiptId: pending.id, childId: pending.childId
+    });
+  }
+  const matchingRows = rowForReceipt(rows, pending);
+  if (matchingRows.length !== 1 || normalizeAgentToken(matchingRows[0]!.agent) !== 'codex' || matchingRows[0]!.note !== 'started') {
+    return failure(request, 'conflict', 'RECOVERY_LOG_CONFLICT', 'activated delegation does not have one matching open lifecycle row', {
+      taskId, receiptId: pending.id, childId: pending.childId
+    });
+  }
+  if (!pending.childId) {
+    return failure(request, 'conflict', 'RECOVERY_DELEGATION_INVALID', 'activated delegation has no child identity', { taskId, receiptId: pending.id });
+  }
+  const store = readLifecycleStore(options, resolved.repoRoot);
+  const stored = readStoredEvidence(store, pending.childId);
+  if ('error' in stored) return failure(request, 'owner-unknown', 'RECOVERY_STORE_UNKNOWN', stored.error.message, { taskId, receiptId: pending.id, childId: pending.childId });
+  if ('missing' in stored) return failure(request, 'owner-unknown', 'RECOVERY_STOP_EVIDENCE_MISSING', 'matching Codex lifecycle stop evidence is missing', { taskId, receiptId: pending.id, childId: pending.childId });
+  const evidence = validateStopRecord(stored, pending);
+  if (!evidence.ok) return failure(request, evidence.code === 'RECOVERY_CONSUMER_CONFLICT' ? 'conflict' : 'owner-unknown', evidence.code, evidence.message, { taskId, receiptId: pending.id, childId: pending.childId });
+
+  let consumed = stored;
+  if (stored.consumer === null) {
+    try {
+      consumed = store.consume(pending.childId, pending.id, pending.hostEvidence?.hookDefinitionHash);
+    } catch (error) {
+      return failure(request, 'owner-unknown', 'RECOVERY_EVIDENCE_CONSUME_FAILED', error instanceof Error ? error.message : String(error), { taskId, receiptId: pending.id, childId: pending.childId });
+    }
+  }
+  if (!consumed.consumedAt) {
+    return failure(request, 'owner-unknown', 'RECOVERY_EVIDENCE_INVALID', 'consumed stop evidence has no timestamp', { taskId, receiptId: pending.id, childId: pending.childId });
+  }
+  const recovered = recoverActivatedOrchestrationDelegationUnderLock(taskId, {
+    receiptId: pending.id,
+    stage: pending.stage,
+    round: pending.round,
+    artifact: pending.artifact,
+    startedAgent: request.agent,
+    childId: pending.childId,
+    stopRevision: consumed.revision,
+    consumer: pending.id,
+    consumedAt: consumed.consumedAt
+  }, { ...options.orchestration, repoRoot: resolved.repoRoot, now: options.now });
+  if (recovered.status === 'failed' || !recovered.run) {
+    return failure(request, 'owner-unknown', recovered.error?.code ?? 'RECOVERY_ORCHESTRATION_FAILED', recovered.error?.message ?? 'orchestration recovery failed', { taskId, receiptId: pending.id, childId: pending.childId });
+  }
+  return appendRecoveryLog(request, taskId, section, { receipt: recovered.run.receipts.at(-1)!, row: matchingRows[0]! }, resolved.repoRoot, options.writeTask ?? writeTask);
+}
+
+function recoverStartedLifecycleFromAdapter(
+  request: LifecycleRecoveryRequest,
+  options: LifecycleRecoveryOptions = {}
+): LifecycleRecoveryResult {
+  return recoverStartedLifecycleUnderLock(request, options);
+}
+
+export { recoverStartedLifecycleFromAdapter, recoverStartedLifecycleUnderLock };
+export type { LifecycleRecoveryOptions, LifecycleRecoveryRequest, LifecycleRecoveryResult };

package/lib/agent-clients/adapters/codex-lifecycle/sandbox-controller.ts

@@ -9,10 +9,8 @@ import * as toml from 'smol-toml';
 import {
   requestCodexControllerClose,
   requestCodexControllerOpen,
-  requestCodexControllerVerify,
-  requestSandboxControl
+  requestCodexControllerVerify
 } from '../../../sandbox/control/client.ts';
-import { readSandboxControlStatus } from '../../../sandbox/control/state.ts';
 import { getProcessStartTime, type ProcessIdentity } from '../../../server/process-state.ts';
 import { LIFECYCLE_PROTOCOL_VERSION, type LifecycleIdentityWarning } from './build-identity.ts';
 import {
@@ -46,7 +44,7 @@ type ControllerOptions = Readonly<{
   control?: ControllerControl;
   now?: () => number;
   codexVersion?: () => string;
-  verifyTaskBinding?: (taskId: string, control: ControllerControl) => void;
+  verifyController?: typeof requestCodexControllerVerify;
   openController?: typeof requestCodexControllerOpen;
   closeController?: typeof requestCodexControllerClose;
   environment?: NodeJS.ProcessEnv;
@@ -117,40 +115,22 @@ function verifyRuntime(runtimeDir: string): void {
   }
 }
 
-function verifyControl(taskId: string, control: ControllerControl): void {
+function verifyControllerBinding(
+  context: CodexSandboxControllerContextV2,
+  control: ControllerControl,
+  requestControllerVerify: typeof requestCodexControllerVerify
+): void {
   verifyRuntime(control.runtimeDir);
-  let status: ReturnType<typeof readSandboxControlStatus> | null = null;
-  let lastError: unknown = null;
-  for (let attempt = 0; attempt < 5; attempt += 1) {
-    try {
-      status = readSandboxControlStatus(control.statusDir);
-      break;
-    } catch (error) {
-      lastError = error;
-      if (attempt < 4) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
-    }
-  }
-  if (!status) {
-    throw new Error(`CODEX_SANDBOX_CONTROLLER_CONTROL_UNAVAILABLE: ${String(lastError)}`);
-  }
-  if (status.generation !== control.generation
-    || status.state !== 'healthy'
-    || Date.now() - status.updatedAt > 1_500) {
-    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTROL_UNAVAILABLE');
-  }
-  const response = requestSandboxControl({
-    family: 'task-orchestration',
-    args: [taskId, 'status'],
+  const verified = requestControllerVerify({
+    controllerProof: controllerProofFromContext(context),
     ...control,
     timeoutMs: 30_000
   });
-  let payload: { taskId?: unknown } = {};
-  try {
-    payload = JSON.parse(response.stdout) as { taskId?: unknown };
-  } catch {
+  if (verified.binding.taskId !== context.taskId
+    || verified.binding.controlGeneration !== context.controlGeneration
+    || verified.binding.controllerInstanceDigest !== context.controllerInstanceDigest) {
     throw new Error('CODEX_SANDBOX_CONTROLLER_TASK_BINDING_INVALID');
   }
-  if (payload.taskId !== taskId) throw new Error('CODEX_SANDBOX_CONTROLLER_TASK_BINDING_INVALID');
 }
 
 function verifyCodexSandboxControllerContextWithWarnings(
@@ -349,7 +329,7 @@ function prepareCodexSandboxController(
       || opened.lease.controllerProcess.startTime !== parentStartTime) {
       throw new Error('SANDBOX_CONTROL_RESULT_INVALID');
     }
-    (options.verifyTaskBinding ?? verifyControl)(taskId, control);
+    verifyControllerBinding(context, control, options.verifyController ?? requestCodexControllerVerify);
     const contextPath = path.join(home, 'controller-context.json');
     writeCodexSandboxControllerContext(contextPath, context);
 

package/lib/agent-clients/adapters/codex-lifecycle/store.ts

@@ -43,23 +43,10 @@ type ActiveCodexLifecycleEvidenceQuery = Readonly<{
 const LOCK_RETRY_MS = 10;
 const LOCK_TIMEOUT_MS = 1_000;
 const LOCK_STALE_MS = 30_000;
-const RECOVERY_CONSUMER_RE = /^lifecycle-recovery:([^:\r\n]+):([^:\r\n]+)$/u;
-
 function digest(value: string): string {
   return crypto.createHash('sha256').update(value).digest('hex');
 }
 
-function isRecoveryConsumer(value: string): boolean {
-  return RECOVERY_CONSUMER_RE.test(value);
-}
-
-function recoveryConsumer(taskId: string, receiptId: string): string {
-  if (!/^[^:\r\n]+$/u.test(taskId) || !/^[^:\r\n]+$/u.test(receiptId)) {
-    throw new Error('Codex lifecycle recovery claim identity is invalid');
-  }
-  return `lifecycle-recovery:${taskId}:${receiptId}`;
-}
-
 function readRecord(file: string): StoredCodexLifecycle {
   const value = JSON.parse(fs.readFileSync(file, 'utf8')) as StoredCodexLifecycle;
   if (
@@ -310,45 +297,15 @@ function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
     expectedHookDefinitionHash?: string
   ): StoredCodexLifecycle {
     if (!consumer.trim()) throw new Error('Codex lifecycle consumer is required');
-    if (consumer.startsWith('lifecycle-recovery:')) {
-      throw new Error('Codex lifecycle recovery claims require claimRecovery');
-    }
     return consumeInternal(childThreadId, consumer, expectedHookDefinitionHash);
   }
 
-  function claimRecovery(
-    childThreadId: string,
-    taskId: string,
-    receiptId: string,
-    expectedHookDefinitionHash?: string
-  ): StoredCodexLifecycle {
-    return consumeInternal(
-      childThreadId,
-      recoveryConsumer(taskId, receiptId),
-      expectedHookDefinitionHash
-    );
-  }
-
-  function releaseRecovery(childThreadId: string, consumer: string): boolean {
-    if (!/^lifecycle-recovery:[^:\r\n]+:[^:\r\n]+$/.test(consumer)) return false;
-    return withWriteLock(() => {
-      const matches = findByChild(childThreadId);
-      if (matches.length !== 1) return false;
-      const file = matches[0]!;
-      const current = readRecord(file);
-      if (current.state.status !== 'stop-ready' || current.consumer !== consumer || !current.consumedAt) return false;
-      fs.unlinkSync(file);
-      return true;
-    });
-  }
-
   function expireBefore(cutoff: string): number {
     return withWriteLock(() => {
       let changed = 0;
       for (const file of recordFiles(root)) {
         const current = readRecord(file);
         if (current.updatedAt >= cutoff) continue;
-        if (current.consumer && isRecoveryConsumer(current.consumer)) continue;
         if (current.consumer || ['invalid', 'expired', 'stop-ready'].includes(current.state.status)) {
           fs.unlinkSync(file);
           changed += 1;
@@ -368,7 +325,7 @@ function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
     });
   }
 
-  return Object.freeze({ root, apply, applyToSpawn, consume, claimRecovery, releaseRecovery, expireBefore, findByParent, read });
+  return Object.freeze({ root, apply, applyToSpawn, consume, expireBefore, findByParent, read });
 }
 
 export { createCodexLifecycleStore, hasActiveCodexLifecycleEvidence };

package/lib/agent-clients/adapters/codex.ts

@@ -28,6 +28,16 @@ const codexAdapter = defineAgentClientAdapter({
     actualModel: 'app-server',
     actualReasoningEffort: 'app-server'
   },
+  orchestrationAdapter: {
+    prepareDelegation: async (...args) => {
+      const { prepareCodexOrchestrationDelegation } = await import('../../task/codex-orchestration.ts');
+      return prepareCodexOrchestrationDelegation(...args);
+    },
+    recoverStarted: async (...args) => {
+      const { recoverStartedLifecycleFromAdapter } = await import('./codex-lifecycle/recovery.ts');
+      return recoverStartedLifecycleFromAdapter(...args);
+    }
+  },
   project: {
     ownedPathPrefixes: ['.codex/'],
     managed: ['.codex/hooks.json', '.codex/agents/'],

package/lib/internal/cli-route-inventory.ts

@@ -46,7 +46,7 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
   'platform-security': ['read', 'dismiss'],
   'platform-metadata': ['init-labels', 'init-milestones'],
   'platform-context': ['resolve'],
-  'platform-comment': ['list', 'recover', 'owner', 'backfill', 'sync'],
+  'platform-comment': ['list', 'recover', 'owner', 'backfill', 'stage-summary', 'sync'],
   'platform-issue': ['inspect', 'create', 'bind', 'sync'],
   'platform-pr': ['inspect', 'summary-context', 'resolve-external', 'create', 'bind', 'skip', 'sync', 'change-report', 'summary-sync', 'sync-in-labels'],
   'platform-pr-review': ['inspect', 'list', 'publish-pr', 'publish-task'],

package/lib/internal/manual-validation.ts

@@ -6,7 +6,7 @@ import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { applyTaskEvent } from '../task/events.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 import { normalizeAgentToken } from '../agent-clients/tokens.ts';
-import { createManualValidationReceipt, manualValidationFinalSummaryDigest, manualValidationFinalSummaryProjectionMatches, readManualValidationReceipt, writeManualValidationReceiptAtomic } from '../task/manual-validation-receipt.ts';
+import { MANUAL_VALIDATION_RECEIPT_PLACEHOLDER, createManualValidationReceipt, manualValidationFinalSummaryDigest, manualValidationFinalSummaryProjectionMatches, readManualValidationReceipt, writeManualValidationReceiptAtomic } from '../task/manual-validation-receipt.ts';
 import { archiveManualValidationGeneration, createManualValidationTransaction, readManualValidationTransaction, retryManualValidationTransaction, summaryPreimageDigest, transitionManualValidationTransaction, validateManualValidationGenerationArchive, writeManualValidationTransactionAtomic } from '../task/manual-validation-transaction.ts';
 import type { ManualValidationTransaction } from '../task/manual-validation-transaction.ts';
 import type { ManualValidationReceipt } from '../task/manual-validation-receipt.ts';
@@ -43,28 +43,23 @@ function printFailure(format: OutputFormat, error: { code: string; message: stri
   process.exitCode = 1;
 }
 
-const MANUAL_VALIDATION_STATUS_SECTION = /^###\s+(?:⚠️\s+(?:需人工校验|Manual Validation Required)|✅\s+(?:人工验证已通过|无需人工校验|Manual Validation Passed|No Manual Validation Required)|⏳\s+(?:人工验证待收尾|Manual Validation Pending))\s*$[\s\S]*?(?=^#{1,3}\s|(?![\s\S]))/gmu;
-const TRAILING_CANONICAL_REPORT_PLACEHOLDER = /\n*<!--\s*canonical-pr-change-report\s*-->\s*$/u;
+const MANUAL_VALIDATION_STATUS_HEADING = /^###\s+(?:⚠️\s+(?:需人工校验|Manual Validation Required)|✅\s+(?:人工验证已通过|无需人工校验|Manual Validation Passed|No Manual Validation Required)|⏳\s+(?:人工验证待收尾|Manual Validation Pending))\s*$/mu;
 
-function manualSummaryBody(body: string, phase: 'pending' | 'final', transactionId: string, receiptDigest = '', evidenceDigest = '', prHeadSha = ''): string {
+function manualSummaryBody(body: string, phase: 'pending' | 'final'): string {
   const chinese = /###\s+(?:⚠️\s+需人工校验|✅\s+(?:人工验证已通过|无需人工校验)|⏳\s+人工验证待收尾)\s*$/mu.test(body);
-  const section = phase === 'pending'
-    ? chinese
-      ? `### ⏳ 人工验证待收尾\n\n人工验证证据已暂存；事务 ${transactionId} 正在等待最终完成。`
-      : `### ⏳ Manual Validation Pending\n\nManual validation evidence is staged; transaction ${transactionId} is awaiting final promotion.`
-    : chinese
-      ? `### ✅ 人工验证已通过\n\n人工验证已通过；transaction=${transactionId}; receipt=${receiptDigest}; evidence=${evidenceDigest}; head=${prHeadSha}.`
-      : `### ✅ Manual Validation Passed\n\nManual validation passed; transaction=${transactionId}; receipt=${receiptDigest}; evidence=${evidenceDigest}; head=${prHeadSha}.`;
-  let inserted = false;
-  const updated = body.replace(MANUAL_VALIDATION_STATUS_SECTION, (matched) => {
-    if (inserted) return '';
-    inserted = true;
-    const trailingPlaceholder = TRAILING_CANONICAL_REPORT_PLACEHOLDER.exec(matched)?.[0];
-    return trailingPlaceholder
-      ? `${trailingPlaceholder.trim()}\n\n${section}\n\n`
-      : `${section}\n\n`;
-  });
-  return inserted ? `${updated.replace(/\s+$/u, '')}\n` : `${body.replace(/\s+$/u, '')}\n\n${section}\n`;
+  const heading = phase === 'pending'
+    ? chinese ? '### ⏳ 人工验证待收尾' : '### ⏳ Manual Validation Pending'
+    : chinese ? '### ✅ 人工验证已通过' : '### ✅ Manual Validation Passed';
+  const marker = phase === 'final'
+    ? `\n\n${MANUAL_VALIDATION_RECEIPT_PLACEHOLDER}`
+    : '';
+  if (MANUAL_VALIDATION_STATUS_HEADING.test(body)) {
+    return `${body.replace(MANUAL_VALIDATION_STATUS_HEADING, `${heading}${marker}`).replace(/\s+$/u, '')}\n`;
+  }
+  const fallback = phase === 'pending'
+    ? chinese ? '人工验证正在等待最终完成。' : 'Manual validation is awaiting final promotion.'
+    : chinese ? '人工验证已通过。' : 'Manual validation passed.';
+  return `${body.replace(/\s+$/u, '')}\n\n${heading}${marker}\n\n${fallback}\n`;
 }
 
 function openManualValidationStarted(taskMdPath: string): { present: boolean; transactionId: string | null } {
@@ -126,7 +121,9 @@ async function executeManualValidationTransactionLocked(
   const pullRequest = currentState.pullRequest;
   const preimageBody = currentState.comment?.body ?? '';
   const preimage = { commentId: currentState.comment?.id ?? null, body: preimageBody, digest: summaryPreimageDigest(preimageBody) };
-  const evidenceDigest = sha256File(path.resolve(cwd, values.summaryFile!));
+  const summaryPath = path.resolve(cwd, values.summaryFile!);
+  const finalBodyWithoutReceipt = fs.readFileSync(summaryPath, 'utf8');
+  const evidenceDigest = sha256File(summaryPath);
   const archiveGeneration = options.archiveGeneration ?? archiveManualValidationGeneration;
   let transactionResult = readManualValidationTransaction(resolved.taskDir, { taskId: resolved.taskId, prNumber: pullRequest.number, prHeadSha: pullRequest.head.sha, evidenceDigest, artifact: values.artifact! });
   let previousTransaction: ManualValidationTransaction | null = null;
@@ -151,8 +148,7 @@ async function executeManualValidationTransactionLocked(
   const transactionId = transactionResult.ok
     ? transactionResult.value.transactionId
     : (openStarted.transactionId ?? values.transactionId ?? `mv-${Date.now()}`);
-  const finalBodyWithoutReceipt = fs.readFileSync(path.resolve(cwd, values.summaryFile!), 'utf8');
-  const pendingBody = manualSummaryBody(finalBodyWithoutReceipt, 'pending', transactionId);
+  const pendingBody = manualSummaryBody(finalBodyWithoutReceipt, 'pending');
   const createTransaction = (): ManualValidationTransaction => createManualValidationTransaction({
     transactionId,
     taskId: resolved.taskId,
@@ -161,7 +157,7 @@ async function executeManualValidationTransactionLocked(
     evidenceDigest,
     summaryPreimage: preimage,
     pendingSummaryDigest: summaryPreimageDigest(pendingBody),
-    finalSummaryDigest: manualValidationFinalSummaryDigest(manualSummaryBody(finalBodyWithoutReceipt, 'final', transactionId, '<receipt>', evidenceDigest, pullRequest.head.sha)),
+    finalSummaryDigest: manualValidationFinalSummaryDigest(manualSummaryBody(finalBodyWithoutReceipt, 'final')),
     artifact: values.artifact!,
     attempt: 1,
     createdAt: new Date().toISOString(),
@@ -254,7 +250,7 @@ async function executeManualValidationTransactionLocked(
       transitionAndPersist('final-promotion-in-progress');
     }
     const promoted = await syncPullRequestSummary(taskRef, {
-      cwd, client: options.client, agent, body: manualSummaryBody(finalBodyWithoutReceipt, 'final', transaction.transactionId, receipt.receiptDigest, receipt.evidenceDigest, receipt.prHeadSha), changeReportFile: path.resolve(cwd, values.changeReportFile!), primaryResult, strict: true,
+      cwd, client: options.client, agent, body: manualSummaryBody(finalBodyWithoutReceipt, 'final'), changeReportFile: path.resolve(cwd, values.changeReportFile!), primaryResult, strict: true,
       manualValidation: { phase: 'final', transactionId: transaction.transactionId, receiptDigest: receipt.receiptDigest, prHeadSha: receipt.prHeadSha, authority: 'coordinator' }, lockAlreadyHeld: true
     });
     if (!['applied', 'no-op'].includes(promoted.status)) transactionFailure(promoted.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: 'final summary promotion failed' });

package/lib/internal/platform-comment.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
 
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import {
@@ -8,15 +9,19 @@ import {
   syncPlatformComment
 } from '../platform/issue-comments.ts';
 import type { CommentKind } from '../platform/issue-comments.ts';
+import { canonicalizeSummaryBody } from '../platform/comment-safety.ts';
+import { platformResult } from '../platform/types.ts';
 import type { PlatformResult } from '../platform/types.ts';
 import { recoverTaskFromComments } from '../platform/task-recovery.ts';
 import { backfillCompletionComments } from '../platform/completion-backfill.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-comment list --issue <token> [--cwd <path>]
        agent-infra-internal platform-comment recover --issue <token> --task-id <TASK-id> --output <staging-task.md> [--cwd <path>]
        agent-infra-internal platform-comment owner <task-ref> [--cwd <path>]
        agent-infra-internal platform-comment backfill <task-ref> --agent <agent> [--cwd <path>]
+       agent-infra-internal platform-comment stage-summary <task-ref> --body-file <path|-> [--cwd <path>]
        agent-infra-internal platform-comment sync <task-ref> --kind <kind> --agent <agent> [--artifact <file>] [--body-file <path|->] [--status-label <label>] [--backfill] [--cwd <path>]
 `;
 
@@ -64,6 +69,7 @@ async function platformComment(args: string[] = []): Promise<void> {
     internalHandlerRoute('platform-comment', 'recover', operation),
     internalHandlerRoute('platform-comment', 'owner', operation),
     internalHandlerRoute('platform-comment', 'backfill', operation),
+    internalHandlerRoute('platform-comment', 'stage-summary', operation),
     internalHandlerRoute('platform-comment', 'sync', operation)
   ].some(Boolean)) { fail('a valid operation is required'); return; }
   const hasTaskRef = operation !== 'list' && operation !== 'recover';
@@ -144,6 +150,38 @@ async function platformComment(args: string[] = []): Promise<void> {
     finish(await backfillCompletionComments(taskRef!, { cwd, agent: normalizedAgent }));
     return;
   }
+  if (internalHandlerRoute('platform-comment', 'stage-summary', operation)) {
+    const unexpected = Object.keys(parsed.values).find((key) => !['cwd', 'bodyFile'].includes(key));
+    if (unexpected) { fail(`stage-summary does not accept '--${unexpected}'`); return; }
+    if (typeof parsed.values.bodyFile !== 'string') { fail('stage-summary requires --body-file'); return; }
+    let body: string;
+    try { body = readBodyFile(parsed.values.bodyFile, cwd); }
+    catch (error) { fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`); return; }
+    const canonical = canonicalizeSummaryBody(body);
+    if (!canonical.ok) { fail(`unable to stage summary: ${canonical.error.code}: ${canonical.error.message}`); return; }
+    body = canonical.value;
+    const resolved = resolveTaskRef(taskRef!, { repoRoot: cwd });
+    if (!resolved.ok || resolved.state !== 'active') { fail('stage-summary requires an active task'); return; }
+    const target = path.join(resolved.taskDir, '.delivery-summary.json');
+    const value = { taskId: resolved.taskId, body, sha256: createHash('sha256').update(body).digest('hex') };
+    const previous = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
+    const next = `${JSON.stringify(value)}\n`;
+    if (previous === next) {
+      finish(platformResult('no-op'));
+      return;
+    }
+    const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+      fs.writeFileSync(temporary, next, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+      fs.renameSync(temporary, target);
+    } catch (error) {
+      try { fs.unlinkSync(temporary); } catch { /* preserve primary error */ }
+      fail(`unable to stage summary: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+    finish(platformResult('applied', { operations: [{ name: 'delivery-summary', status: 'applied', reasonCode: null }] }));
+    return;
+  }
   if (!internalHandlerRoute('platform-comment', 'sync', operation)) { fail('operation is not registered'); return; }
   const kind = parsed.values.kind;
   const agent = parsed.values.agent;