@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/lib/internal/manual-validation.ts

@@ -0,0 +1,315 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { locateActivityLog, pairEntries } from '../task/activity-log.ts';
+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 { 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';
+import { sha256File } from '../task/artifact-receipts.ts';
+import { summaryCommentState, syncPullRequestSummary } from '../platform/pr-summary.ts';
+import type { PlatformClient } from '../platform/context.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
+
+const USAGE = `Usage: agent-infra-internal manual-validation transaction <task-ref> --prepare --artifact <artifact> --summary-file <path> --agent <agent> [--cwd <path>]
+       agent-infra-internal manual-validation transaction <task-ref> --artifact <artifact> --summary-file <path> --change-report-file <path> --agent <agent> [--result pr_created|pr_reused|no_op] [--cwd <path>]`;
+
+type OutputFormat = 'json' | 'text';
+type ManualValidationCoordinatorOptions = {
+  client?: PlatformClient;
+  archiveGeneration?: typeof archiveManualValidationGeneration;
+};
+type ManualValidationResult = {
+  status: 'applied' | 'failed';
+  changed: false;
+  error: { code: string; message: string } | null;
+  transaction?: ManualValidationTransaction;
+  receipt?: ManualValidationReceipt;
+  prepared?: boolean;
+  idempotent?: boolean;
+  [key: string]: unknown;
+};
+function result(status: 'applied' | 'failed', error: { code: string; message: string } | null = null, extra: Record<string, unknown> = {}): ManualValidationResult {
+  return { status, changed: false, error, ...extra };
+}
+
+function printFailure(format: OutputFormat, error: { code: string; message: string }): void {
+  if (format === 'json') process.stdout.write(`${JSON.stringify(result('failed', error))}\n`);
+  else process.stderr.write(`${error.code}: ${error.message}\n`);
+  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;
+
+function manualSummaryBody(body: string, phase: 'pending' | 'final', transactionId: string, receiptDigest = '', evidenceDigest = '', prHeadSha = ''): 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, () => {
+    if (inserted) return '';
+    inserted = true;
+    return `${section}\n\n`;
+  });
+  return inserted ? `${updated.replace(/\s+$/u, '')}\n` : `${body.replace(/\s+$/u, '')}\n\n${section}\n`;
+}
+
+function openManualValidationStarted(taskMdPath: string): { present: boolean; transactionId: string | null } {
+  let content: string;
+  try { content = fs.readFileSync(taskMdPath, 'utf8'); }
+  catch { return { present: false, transactionId: null }; }
+  const section = locateActivityLog(content);
+  if (!section) return { present: false, transactionId: null };
+  const row = pairEntries(section.entries)
+    .filter((item) => item.step === 'Complete Manual Validation' && item.started && !item.done)
+    .at(-1);
+  if (!row) return { present: false, transactionId: null };
+  return {
+    present: true,
+    transactionId: /(?:^|;\s*)transaction=([A-Za-z0-9][A-Za-z0-9._-]{0,127})(?:;|$)/u.exec(row.note)?.[1] ?? null
+  };
+}
+
+async function executeManualValidationTransaction(taskRef: string, values: Record<string, string>, cwd: string, options: ManualValidationCoordinatorOptions = {}) {
+  const prepareOnly = values.prepare === 'true';
+  const required = prepareOnly
+    ? ['artifact', 'summaryFile', 'agent'] as const
+    : ['artifact', 'summaryFile', 'changeReportFile', 'agent'] as const;
+  const missing = required.find((key) => !values[key]);
+  if (missing) return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_ARGS_INVALID', message: `transaction requires --${missing.replace(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`)}` });
+  const agent = normalizeAgentToken(values.agent!);
+  if (!agent) return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_ARGS_INVALID', message: 'transaction agent is invalid' });
+  const primaryResult = values.result ?? 'no_op';
+  if (!['pr_created', 'pr_reused', 'no_op'].includes(primaryResult)) return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_ARGS_INVALID', message: '--result must be pr_created, pr_reused, or no_op' });
+  const resolved = resolveTaskRef(taskRef, { repoRoot: cwd });
+  if (!resolved.ok) return result('failed', { code: resolved.code, message: resolved.message });
+  try {
+    return await withTaskExecutionLock(
+      resolved.repoRoot,
+      resolved.taskId,
+      `manual-validation:${taskRef}`,
+      () => executeManualValidationTransactionLocked(taskRef, values, cwd, resolved, agent, primaryResult as 'pr_created' | 'pr_reused' | 'no_op', prepareOnly, options)
+    );
+  } catch (error) {
+    if (error instanceof TaskExecutionLockError) return result('failed', { code: error.code, message: error.message });
+    throw error;
+  }
+}
+
+async function executeManualValidationTransactionLocked(
+  taskRef: string,
+  values: Record<string, string>,
+  cwd: string,
+  resolved: Extract<ReturnType<typeof resolveTaskRef>, { ok: true }>,
+  agent: string,
+  primaryResult: 'pr_created' | 'pr_reused' | 'no_op',
+  prepareOnly: boolean,
+  options: ManualValidationCoordinatorOptions
+) {
+  const artifactPath = path.resolve(resolved.taskDir, values.artifact!);
+  if (!prepareOnly && !fs.existsSync(artifactPath)) return result('failed', { code: 'MANUAL_VALIDATION_ARTIFACT_MISSING', message: `manual-validation artifact is missing: ${values.artifact}` });
+  const currentState = await summaryCommentState(taskRef, { cwd, client: options.client });
+  if (!currentState.pullRequest) return result('failed', { code: 'MANUAL_VALIDATION_PR_REQUIRED', message: 'canonical pull-request head is unavailable' });
+  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 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;
+  if (!transactionResult.ok && transactionResult.error.code === 'MANUAL_VALIDATION_TRANSACTION_IDENTITY_MISMATCH') {
+    const existing = readManualValidationTransaction(resolved.taskDir);
+    if (!existing.ok) return result('failed', existing.error);
+    if (!['aborted', 'recovery-required', 'committed'].includes(existing.value.phase)) return result('failed', transactionResult.error);
+    try { validateManualValidationGenerationArchive(resolved.taskDir, existing.value, existing.value.phase === 'committed'); }
+    catch (error) { return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: error instanceof Error ? error.message : String(error) }); }
+    previousTransaction = existing.value;
+    transactionResult = { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_MISSING', message: 'previous failed transaction was archived for a new pull-request head' } };
+  }
+  if (!transactionResult.ok && transactionResult.error.code !== 'MANUAL_VALIDATION_TRANSACTION_MISSING') return result('failed', transactionResult.error);
+  if (transactionResult.ok && transactionResult.value.phase === 'committed') return result('applied', null, { transaction: transactionResult.value, receipt: transactionResult.value.committedReceipt, idempotent: true });
+  const openStarted = transactionResult.ok ? { present: false, transactionId: null } : openManualValidationStarted(resolved.taskMdPath);
+  if (openStarted.present && !openStarted.transactionId) {
+    return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: 'open manual-validation started event has no recoverable transactionId' });
+  }
+  if (previousTransaction && openStarted.transactionId === previousTransaction.transactionId) {
+    return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: 'previous manual-validation generation is still open; retry the existing transaction before starting a new generation' });
+  }
+  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 createTransaction = (): ManualValidationTransaction => createManualValidationTransaction({
+    transactionId,
+    taskId: resolved.taskId,
+    prNumber: pullRequest.number,
+    prHeadSha: pullRequest.head.sha,
+    evidenceDigest,
+    summaryPreimage: preimage,
+    pendingSummaryDigest: summaryPreimageDigest(pendingBody),
+    finalSummaryDigest: manualValidationFinalSummaryDigest(manualSummaryBody(finalBodyWithoutReceipt, 'final', transactionId, '<receipt>', evidenceDigest, pullRequest.head.sha)),
+    artifact: values.artifact!,
+    attempt: 1,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString()
+  });
+  let transaction: ManualValidationTransaction;
+  const idempotent = transactionResult.ok;
+  let startedEventApplied = false;
+  if (!transactionResult.ok) {
+    transaction = createTransaction();
+    const started = applyTaskEvent({ taskRef, event: 'manual-validation.started', agent, initiator: 'model', requestId: transactionId, reasonCode: 'user-request', transactionId }, { lockAlreadyHeld: true, repoRoot: cwd });
+    if (started.status === 'failed') return result('failed', started.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_FAILED', message: 'manual-validation started event failed' });
+    startedEventApplied = true;
+    if (previousTransaction) {
+      try { archiveGeneration(resolved.taskDir, previousTransaction, previousTransaction.phase === 'committed'); }
+      catch (error) { return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: error instanceof Error ? error.message : String(error) }); }
+    }
+    writeManualValidationTransactionAtomic(resolved.taskDir, transaction);
+  } else {
+    transaction = transactionResult.value;
+    if (['aborted', 'recovery-required'].includes(transaction.phase)) {
+      const retried = retryManualValidationTransaction(transaction);
+      if (!retried.ok) return result('failed', retried.error);
+      transaction = retried.value;
+      writeManualValidationTransactionAtomic(resolved.taskDir, transaction);
+    }
+  }
+  if (transaction.phase === 'prepared' && !startedEventApplied) {
+    const started = applyTaskEvent({ taskRef, event: 'manual-validation.started', agent, initiator: 'model', requestId: transaction.transactionId, reasonCode: 'user-request', transactionId: transaction.transactionId }, { lockAlreadyHeld: true, repoRoot: cwd });
+    if (started.status === 'failed') return result('failed', started.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_FAILED', message: 'manual-validation started event failed' });
+  }
+  if (prepareOnly) return result('applied', null, { transaction, prepared: true, idempotent });
+  const transactionFailure = (failure: { code: string; message: string }): never => {
+    throw new Error(`${failure.code}: ${failure.message}`);
+  };
+  const transitionAndPersist = (
+    phase: Parameters<typeof transitionManualValidationTransaction>[1],
+    patch: Parameters<typeof transitionManualValidationTransaction>[2] = {}
+  ): void => {
+    const next = transitionManualValidationTransaction(transaction, phase, patch);
+    if (!next.ok) throw new Error(`${next.error.code}: ${next.error.message}`);
+    transaction = next.value;
+    writeManualValidationTransactionAtomic(resolved.taskDir, transaction);
+  };
+  try {
+    if (transaction.phase === 'prepared') {
+      const staged = await syncPullRequestSummary(taskRef, {
+        cwd, client: options.client, agent, body: pendingBody, changeReportFile: path.resolve(cwd, values.changeReportFile!), primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', strict: true,
+        manualValidation: { phase: 'pending' }, lockAlreadyHeld: true
+      });
+      if (!['applied', 'no-op'].includes(staged.status)) transactionFailure(staged.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_FAILED', message: 'pending summary staging failed' });
+      transitionAndPersist('summary-staged');
+    }
+    let receiptResult = readManualValidationReceipt(resolved.taskDir, {
+      transactionId: transaction.transactionId,
+      taskId: resolved.taskId,
+      prNumber: pullRequest.number,
+      prHeadSha: pullRequest.head.sha,
+      evidenceDigest: transaction.evidenceDigest,
+      artifact: values.artifact!
+    });
+    if (!receiptResult.ok && receiptResult.error.code !== 'MANUAL_VALIDATION_RECEIPT_MISSING') transactionFailure(receiptResult.error);
+    let receipt: ManualValidationReceipt;
+    if (receiptResult.ok) {
+      receipt = receiptResult.value;
+    } else {
+      receipt = createManualValidationReceipt({
+      transactionId: transaction.transactionId,
+      taskId: resolved.taskId,
+      prNumber: pullRequest.number,
+      prHeadSha: pullRequest.head.sha,
+      evidenceDigest: transaction.evidenceDigest,
+      artifact: values.artifact!,
+      artifactSha256: sha256File(artifactPath),
+      pendingSummaryDigest: transaction.pendingSummaryDigest,
+      finalSummaryDigest: transaction.finalSummaryDigest,
+      committedAt: new Date().toISOString()
+      });
+      writeManualValidationReceiptAtomic(resolved.taskDir, receipt);
+    }
+    if (transaction.phase === 'summary-staged') {
+      transitionAndPersist('receipt-committed', { committedReceipt: receipt.receiptDigest });
+    }
+    if (transaction.phase === 'receipt-committed' && !transaction.eventAppended) {
+      const completed = applyTaskEvent({ taskRef, event: 'manual-validation.completed', agent, initiator: 'model', requestId: transaction.transactionId, reasonCode: 'user-request', artifact: values.artifact, summaryResult: 'human-confirmed validation and committed receipt', transactionId: transaction.transactionId, receiptDigest: receipt.receiptDigest, prHeadSha: receipt.prHeadSha }, { lockAlreadyHeld: true, repoRoot: cwd });
+      if (completed.status === 'failed') transactionFailure(completed.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_FAILED', message: 'manual-validation completion event failed' });
+      transitionAndPersist('receipt-committed', { eventAppended: true });
+    }
+    if (transaction.phase === 'receipt-committed') {
+      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,
+      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' });
+    const postWrite = await summaryCommentState(taskRef, { cwd, client: options.client });
+    if (!/^###\s+✅\s+(?:Manual Validation Passed|人工验证已通过)\s*$/mu.test(postWrite.comment?.body ?? '') || postWrite.pullRequest?.head.sha !== receipt.prHeadSha || !manualValidationFinalSummaryProjectionMatches(postWrite.comment?.body ?? '', receipt)) transactionFailure({ code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: 'final summary post-write verification failed' });
+    transitionAndPersist('committed', { postWriteVerified: true });
+    return result('applied', null, { transaction, receipt, idempotent: false });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (transaction.phase === 'final-promotion-in-progress') {
+      try {
+        await syncPullRequestSummary(taskRef, {
+          cwd, client: options.client, agent, body: pendingBody, changeReportFile: path.resolve(cwd, values.changeReportFile!), primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', strict: true,
+          manualValidation: { phase: 'pending' }, lockAlreadyHeld: true
+        });
+      } catch {
+        // Preserve recovery-required when pending compensation cannot be confirmed.
+      }
+    }
+    const failedTransaction = transitionManualValidationTransaction(transaction, 'recovery-required', { error: message.slice(0, 400) });
+    if (failedTransaction.ok) writeManualValidationTransactionAtomic(resolved.taskDir, failedTransaction.value);
+    return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message });
+  }
+}
+
+function parse(args: string[], start: number): { values: Record<string, string>; error?: string } {
+  const values: Record<string, string> = {};
+  for (let index = start; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag === '--prepare') {
+      if (values.prepare) return { values, error: `duplicate option '${flag}'` };
+      values.prepare = 'true';
+      continue;
+    }
+    if (!['--format', '--cwd', '--artifact', '--summary-file', '--change-report-file', '--agent', '--result'].includes(flag)) return { values, error: `unknown option '${flag}'` };
+    const value = args[++index];
+    if (!value || value.startsWith('--')) return { values, error: `option '${flag}' requires a value` };
+    const key = flag.slice(2).replace(/-([a-z])/gu, (_, letter: string) => letter.toUpperCase());
+    if (values[key]) return { values, error: `duplicate option '${flag}'` };
+    values[key] = value;
+  }
+  return { values };
+}
+
+async function manualValidation(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('manual-validation', args)) return;
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(`${USAGE}\n`); return; }
+  const operation = args[0];
+  const isTransaction = operation === 'transaction' && internalHandlerRoute('manual-validation', 'transaction', operation);
+  if (!isTransaction) { printFailure('json', { code: 'MANUAL_VALIDATION_ARGS_INVALID', message: 'transaction operation is required' }); return; }
+  const taskRef = args[1];
+  if (!taskRef || taskRef.startsWith('--')) { printFailure('json', { code: 'MANUAL_VALIDATION_ARGS_INVALID', message: 'task ref is required' }); return; }
+  const parsed = parse(args, 2);
+  if (parsed.error) { printFailure('json', { code: 'MANUAL_VALIDATION_ARGS_INVALID', message: parsed.error }); return; }
+  const values = parsed.values;
+  const format = values.format === 'text' ? 'text' : 'json';
+  const output = await executeManualValidationTransaction(taskRef, values, path.resolve(values.cwd ?? process.cwd()));
+  process.stdout.write(format === 'json' ? `${JSON.stringify(output)}\n` : `${output.status === 'applied' ? 'Manual validation transaction committed.' : `${output.error?.code}: ${output.error?.message}`}\n`);
+  if (output.status === 'failed') process.exitCode = 1;
+}
+
+export { executeManualValidationTransaction, manualValidation };

package/lib/internal/platform-pr.ts

@@ -25,11 +25,11 @@ const USAGE = `Usage: agent-infra-internal platform-pr inspect <task-ref> [--cwd
        agent-infra-internal platform-pr sync-in-labels --pr <N> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr summary-context <task-ref> [--cwd <path>]
        agent-infra-internal platform-pr change-report <task-ref> --agent <agent> --mechanical-file <path> --precheck-file <path> [--dry-run] [--cwd <path>]
-       agent-infra-internal platform-pr summary-sync <task-ref> --agent <agent> --body-file <path|-> --change-report-file <path> --result <pr_created|pr_reused|no_op> [--strict] [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr summary-sync <task-ref> --agent <agent> --body-file <path|-> --change-report-file <path> --result <pr_created|pr_reused|no_op> [--manual-phase pending|final ...] [--strict] [--dry-run] [--cwd <path>]
 `;
 
 const BOOLEAN_FLAGS = new Set(['--draft', '--dry-run', '--metadata', '--closing-issue', '--strict']);
-const VALUE_FLAGS = new Set(['--cwd', '--agent', '--base', '--head', '--title-file', '--body-file', '--change-report-file', '--mechanical-file', '--precheck-file', '--pr', '--result']);
+const VALUE_FLAGS = new Set(['--cwd', '--agent', '--base', '--head', '--title-file', '--body-file', '--change-report-file', '--mechanical-file', '--precheck-file', '--pr', '--result', '--manual-phase', '--transaction-id', '--receipt-digest', '--pr-head-sha']);
 
 function key(flag: string): string {
   return flag.slice(2).replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
@@ -111,7 +111,7 @@ async function platformPr(args: string[] = []): Promise<void> {
     'sync-in-labels': ['cwd', 'pr', 'dryRun'],
     'summary-context': ['cwd'],
     'change-report': ['cwd', 'agent', 'mechanicalFile', 'precheckFile', 'dryRun'],
-    'summary-sync': ['cwd', 'agent', 'bodyFile', 'changeReportFile', 'result', 'dryRun', 'strict']
+    'summary-sync': ['cwd', 'agent', 'bodyFile', 'changeReportFile', 'result', 'manualPhase', 'transactionId', 'receiptDigest', 'prHeadSha', 'dryRun', 'strict']
   };
   const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
@@ -160,7 +160,18 @@ async function platformPr(args: string[] = []): Promise<void> {
     if (typeof values.changeReportFile !== 'string') { fail('summary-sync requires --change-report-file'); return; }
     if (!primaryResult) { fail('summary-sync requires --result pr_created, pr_reused, or no_op'); return; }
     try {
-      finish(await syncPullRequestSummary(taskRef, { cwd, agent: values.agent, body: readFile(values.bodyFile, cwd), changeReportFile: values.changeReportFile, primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', dryRun: values.dryRun === true, strict: values.strict === true }));
+      const manualPhase = values.manualPhase;
+      if (manualPhase !== undefined && manualPhase !== 'pending' && manualPhase !== 'final') { fail('--manual-phase must be pending or final'); return; }
+      finish(await syncPullRequestSummary(taskRef, {
+        cwd, agent: values.agent, body: readFile(values.bodyFile, cwd), changeReportFile: values.changeReportFile,
+        primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', dryRun: values.dryRun === true, strict: values.strict === true,
+        ...(manualPhase ? { manualValidation: {
+          phase: manualPhase,
+          ...(typeof values.transactionId === 'string' ? { transactionId: values.transactionId } : {}),
+          ...(typeof values.receiptDigest === 'string' ? { receiptDigest: values.receiptDigest } : {}),
+          ...(typeof values.prHeadSha === 'string' ? { prHeadSha: values.prHeadSha } : {})
+        } } : {})
+      }));
     } catch (error) {
       fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`);
     }

package/lib/internal/release-workflow.ts

@@ -1,6 +1,5 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import semver from 'semver';
 
@@ -9,115 +8,95 @@ import { inspectPlatformRelease, reconcileReleaseMilestones } from '../platform/
 import { inspectHomebrewChannel, inspectNpmChannel } from '../release/channels.ts';
 import { releaseSnapshot } from '../release/workflow.ts';
 import type { PostReleaseFacts, ReleaseFacts } from '../release/workflow.ts';
+import { collectDemoTranscript } from './demo-transcript.ts';
+import { createDemoPromotion, promoteDemoAssets, recoverDemoPromotion } from './demo-promotion.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
-function command(cwd: string, executable: string, args: string[]) {
-  return spawnSync(executable, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+type CommandOptions = { env?: NodeJS.ProcessEnv };
+
+function command(cwd: string, executable: string, args: string[], options: CommandOptions = {}) {
+  return spawnSync(executable, args, {
+    cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, ...options.env }
+  });
 }
 
 type CommandResult = ReturnType<typeof command>;
-type CommandRunner = (cwd: string, executable: string, args: string[]) => CommandResult;
+type CommandRunner = (cwd: string, executable: string, args: string[], options?: CommandOptions) => CommandResult;
 type DemoResult = {
   status: 'recorded' | 'skipped' | 'failed';
-  reasonCode: 'DEMO_INPUTS_UNCHANGED' | 'GIT_LFS_MISSING' | 'VHS_MISSING' | 'FFMPEG_MISSING'
+  reasonCode: 'DEMO_TRANSCRIPT_UNCHANGED' | 'DEMO_TRANSCRIPT_UNAVAILABLE' | 'DEMO_TRANSCRIPT_FAILED'
+    | 'DEMO_PROMOTION_FAILED' | 'DEMO_PROMOTION_RECOVERY_REQUIRED' | 'DEMO_PROMOTION_CLEANUP_FAILED'
+    | 'GIT_LFS_MISSING' | 'VHS_MISSING' | 'FFMPEG_MISSING'
     | 'DEMO_COMMAND_FAILED' | 'DEMO_OUTPUT_MISSING' | 'DEMO_OUTPUT_INVALID'
-    | 'DEMO_OUTPUT_TOO_LARGE' | 'DEMO_DIGEST_FAILED' | null;
+    | 'DEMO_OUTPUT_TOO_LARGE' | null;
   message: string | null;
   outputPath: string | null;
 };
 
-// The tape is the canonical init interaction contract. Do not hash all of
-// lib/init.ts: non-visual config serialization changes must not re-record it.
-const DEMO_INPUT_PATHS = [
-  'assets/demo-init.tape',
-  'scripts/demo-regen.sh',
-  'scripts/normalize-gif-duration.py',
-  'bin/cli.ts',
-  'lib/log.ts',
-  'lib/prompt.ts',
-  'lib/paths.ts',
-  'lib/render.ts',
-  'lib/sandbox/engines/'
-] as const;
-const DEMO_DIGEST_PATH = 'assets/demo-init.inputs.sha256';
+const DEMO_DIGEST_PATH = 'assets/demo-init.transcript.sha256';
 const DEMO_OUTPUT_PATH = 'assets/demo-init.gif';
 const DEMO_MAX_BYTES = 4 * 1024 * 1024;
 
-function demoInputFiles(cwd: string): string[] {
-  const files = new Set<string>();
-  for (const input of DEMO_INPUT_PATHS) {
-    if (input.endsWith('/')) {
-      const listed = command(cwd, 'git', ['ls-files', '--', input]);
-      if (listed.status !== 0) throw new Error(String(listed.stderr || `Unable to list ${input}`));
-      const directoryFiles = String(listed.stdout).split('\n').filter(Boolean);
-      if (!directoryFiles.length) throw new Error(`Canonical demo input directory is empty: ${input}`);
-      for (const file of directoryFiles) files.add(file.replaceAll('\\', '/'));
-    } else {
-      files.add(input);
-    }
-  }
-  const sorted = [...files].sort((left, right) => Buffer.from(left).compare(Buffer.from(right)));
-  if (!sorted.length) throw new Error('Canonical demo input set is empty');
-  for (const file of sorted) {
-    const absolute = path.join(cwd, file);
-    if (!fs.statSync(absolute).isFile()) throw new Error(`Canonical demo input is not a file: ${file}`);
-  }
-  return sorted;
-}
-
-function computeDemoInputDigest(cwd: string): string {
-  const hash = crypto.createHash('sha256');
-  for (const file of demoInputFiles(cwd)) {
-    const bytes = fs.readFileSync(path.join(cwd, file));
-    hash.update(file);
-    hash.update('\0');
-    hash.update(String(bytes.byteLength));
-    hash.update('\0');
-    hash.update(bytes);
-    hash.update('\0');
-  }
-  return hash.digest('hex');
-}
-
 function validGif(filePath: string): boolean {
   if (!fs.existsSync(filePath)) return false;
   const header = fs.readFileSync(filePath).subarray(0, 6).toString('ascii');
   return header === 'GIF87a' || header === 'GIF89a';
 }
 
-function writeDigestAtomically(cwd: string, digest: string): void {
-  const target = path.join(cwd, DEMO_DIGEST_PATH);
-  const temporary = `${target}.tmp-${process.pid}`;
-  fs.writeFileSync(temporary, `${digest}\n`);
-  fs.renameSync(temporary, target);
-}
-
-function runOptionalDemo(cwd: string, run: CommandRunner = command): DemoResult {
-  let digest: string;
-  try {
-    digest = computeDemoInputDigest(cwd);
-  } catch (error) {
-    return { status: 'failed', reasonCode: 'DEMO_DIGEST_FAILED', message: String(error), outputPath: null };
+async function runOptionalDemo(
+  cwd: string,
+  run: CommandRunner = command,
+  collect = collectDemoTranscript
+): Promise<DemoResult> {
+  const recovery = recoverDemoPromotion(cwd);
+  if (recovery?.status === 'failed') {
+    return { status: 'failed', reasonCode: recovery.code === 'DEMO_PROMOTION_CLEANUP_FAILED' ? recovery.code : 'DEMO_PROMOTION_RECOVERY_REQUIRED', message: recovery.message, outputPath: null };
+  }
+  const transcript = await collect(cwd);
+  if (transcript.status === 'failed') {
+    return { status: 'failed', reasonCode: transcript.reasonCode, message: transcript.message, outputPath: null };
   }
   const digestPath = path.join(cwd, DEMO_DIGEST_PATH);
   const priorDigest = fs.existsSync(digestPath) ? fs.readFileSync(digestPath, 'utf8').trim() : '';
-  if (/^[0-9a-f]{64}$/.test(priorDigest) && priorDigest === digest) {
-    return { status: 'skipped', reasonCode: 'DEMO_INPUTS_UNCHANGED', message: null, outputPath: null };
+  if (/^[0-9a-f]{64}$/.test(priorDigest) && priorDigest === transcript.sha256) {
+    return { status: 'skipped', reasonCode: 'DEMO_TRANSCRIPT_UNCHANGED', message: null, outputPath: null };
   }
+  const promotion = createDemoPromotion(cwd, transcript.transcript);
+  const discardPromotion = () => fs.rmSync(promotion.directory, { recursive: true, force: true });
   const lfs = run(cwd, 'git', ['lfs', 'version']);
   if (lfs.status !== 0) {
+    discardPromotion();
     return { status: 'failed', reasonCode: 'GIT_LFS_MISSING', message: String(lfs.stderr || lfs.stdout), outputPath: null };
   }
   const lfsAttribute = run(cwd, 'git', ['check-attr', 'filter', '--', DEMO_OUTPUT_PATH]);
   if (lfsAttribute.status !== 0 || !String(lfsAttribute.stdout).trim().endsWith(': lfs')) {
+    discardPromotion();
     return { status: 'failed', reasonCode: 'GIT_LFS_MISSING', message: `${DEMO_OUTPUT_PATH} is not tracked by Git LFS`, outputPath: null };
   }
   const vhs = run(cwd, 'vhs', ['--version']);
-  if (vhs.status !== 0) return { status: 'skipped', reasonCode: 'VHS_MISSING', message: null, outputPath: null };
+  if (vhs.status !== 0) {
+    discardPromotion();
+    return {
+      status: 'failed',
+      reasonCode: 'VHS_MISSING',
+      message: String(vhs.stderr || vhs.stdout) || 'VHS is required to record the changed demo transcript',
+      outputPath: null
+    };
+  }
   const ffmpeg = run(cwd, 'ffmpeg', ['-version']);
-  if (ffmpeg.status !== 0) return { status: 'skipped', reasonCode: 'FFMPEG_MISSING', message: null, outputPath: null };
-  const demo = run(cwd, 'npm', ['run', 'demo:regen']);
+  if (ffmpeg.status !== 0) {
+    discardPromotion();
+    return {
+      status: 'failed',
+      reasonCode: 'FFMPEG_MISSING',
+      message: String(ffmpeg.stderr || ffmpeg.stdout) || 'ffmpeg is required to record the changed demo transcript',
+      outputPath: null
+    };
+  }
+  const stagedOutputPath = path.relative(cwd, promotion.staging.gif).replaceAll(path.sep, '/');
+  const demo = run(cwd, 'npm', ['run', 'demo:regen'], { env: { DEMO_OUTPUT_PATH: stagedOutputPath } });
   if (demo.status !== 0) {
+    discardPromotion();
     return {
       status: 'failed',
       reasonCode: 'DEMO_COMMAND_FAILED',
@@ -126,7 +105,8 @@ function runOptionalDemo(cwd: string, run: CommandRunner = command): DemoResult
     };
   }
   const outputPath = DEMO_OUTPUT_PATH;
-  if (!fs.existsSync(path.join(cwd, outputPath))) {
+  if (!fs.existsSync(promotion.staging.gif)) {
+    discardPromotion();
     return {
       status: 'failed',
       reasonCode: 'DEMO_OUTPUT_MISSING',
@@ -134,18 +114,24 @@ function runOptionalDemo(cwd: string, run: CommandRunner = command): DemoResult
       outputPath: null
     };
   }
-  const absoluteOutput = path.join(cwd, outputPath);
+  const absoluteOutput = promotion.staging.gif;
   if (!validGif(absoluteOutput)) {
+    discardPromotion();
     return { status: 'failed', reasonCode: 'DEMO_OUTPUT_INVALID', message: `${outputPath} is not a GIF`, outputPath: null };
   }
   if (fs.statSync(absoluteOutput).size > DEMO_MAX_BYTES) {
+    discardPromotion();
     return { status: 'failed', reasonCode: 'DEMO_OUTPUT_TOO_LARGE', message: `${outputPath} exceeds 4 MiB`, outputPath: null };
   }
-  const pointer = run(cwd, 'git', ['lfs', 'pointer', `--file=${outputPath}`]);
+  const pointer = run(cwd, 'git', ['lfs', 'pointer', `--file=${stagedOutputPath}`]);
   if (pointer.status !== 0 || !String(pointer.stdout).includes(`size ${fs.statSync(absoluteOutput).size}`)) {
+    discardPromotion();
     return { status: 'failed', reasonCode: 'DEMO_OUTPUT_INVALID', message: 'Git LFS could not produce a matching pointer', outputPath: null };
   }
-  writeDigestAtomically(cwd, digest);
+  const promoted = promoteDemoAssets(cwd, promotion.staging, `${process.pid}-${Date.now()}`);
+  if (promoted.status === 'failed') {
+    return { status: 'failed', reasonCode: promoted.code ?? 'DEMO_PROMOTION_FAILED', message: promoted.message, outputPath: null };
+  }
   return { status: 'recorded', reasonCode: null, message: null, outputPath };
 }
 
@@ -207,7 +193,7 @@ function inspectPostReleaseFacts(
     remoteHead,
     newVersion,
     changedPaths,
-    demoInputSha256: digest && /^[0-9a-f]{64}$/.test(digest) ? digest : null,
+    demoTranscriptSha256: digest && /^[0-9a-f]{64}$/.test(digest) ? digest : null,
     worktree: snapshot?.worktree ?? [],
     staged: snapshot?.staged ?? []
   };
@@ -333,7 +319,8 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
   if (internalHandlerRoute('release-workflow', 'prepare', action || '')) {
     if (before.phase !== 'unprepared') {
       const milestones = await reconcileReleaseMilestones(version, { cwd });
-      process.stdout.write(`${JSON.stringify({ ...milestones, snapshot: before })}\n`);
+      const snapshot = releaseSnapshot(version, await inspectFacts(cwd, version));
+      process.stdout.write(`${JSON.stringify({ ...milestones, snapshot })}\n`);
       process.exitCode = milestones.status === 'failed' ? 1 : milestones.status === 'blocked' ? 2 : 0;
       return;
     }
@@ -420,6 +407,11 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
   if (!['published', 'post-pending'].includes(before.phase) || !channelsComplete || before.facts.smoke !== 'success') {
     process.stdout.write(`${JSON.stringify({ status: before.facts.smoke === 'failed' ? 'failed' : 'blocked', changed: false, snapshot: before, error: { code: 'RELEASE_CHANNELS_PENDING', message: 'Release channels or smoke workflow are not complete' } })}\n`); process.exitCode = before.facts.smoke === 'failed' ? 1 : 2; return;
   }
+  const recovery = recoverDemoPromotion(cwd);
+  if (recovery?.status === 'failed') {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: true, snapshot: before, error: { code: recovery.code, message: recovery.message } })}\n`);
+    process.exitCode = 1; return;
+  }
   const worktreeError = inspectPostWorktree(cwd);
   if (worktreeError) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: worktreeError })}\n`);
@@ -430,7 +422,7 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: true, snapshot: before, error: { code: 'RELEASE_POST_COMMAND_FAILED', message: String(built.stderr || built.stdout) } })}\n`);
     process.exitCode = 1; return;
   }
-  const demo = runOptionalDemo(cwd);
+  const demo = await runOptionalDemo(cwd);
   if (demo.status === 'failed') {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: true, snapshot: before, demo, error: { code: 'RELEASE_POST_DEMO_FAILED', message: demo.message } })}\n`);
     process.exitCode = 1; return;
@@ -449,5 +441,5 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
   process.stdout.write(`${JSON.stringify({ status: 'applied', changed: true, demo, snapshot, error: null })}\n`);
 }
 
-export { changedPaths, computeDemoInputDigest, inspectFacts, inspectLocalReleaseFacts, inspectPostReleaseFacts, inspectPostWorktree, releaseSmokeStatus, releaseWorkflow, runOptionalDemo };
+export { changedPaths, inspectFacts, inspectLocalReleaseFacts, inspectPostReleaseFacts, inspectPostWorktree, releaseSmokeStatus, releaseWorkflow, runOptionalDemo };
 export type { CommandRunner, DemoResult };