@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/internal/platform-pr.ts

@@ -14,6 +14,7 @@ import {
 import type { PullRequestResult } from '../platform/pull-requests.ts';
 import { reportWrite, summaryContext, syncPullRequestSummary } from '../platform/pr-summary.ts';
 import type { PlatformResult } from '../platform/types.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-pr inspect <task-ref> [--cwd <path>]
        agent-infra-internal platform-pr resolve-external <task-ref> --agent <agent> [--pr <token>] [--dry-run] [--cwd <path>]
@@ -24,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());
@@ -67,10 +68,22 @@ function readFile(value: string, cwd: string): string {
 }
 
 async function platformPr(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('platform-pr', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
-  if (!operation || !['inspect', 'resolve-external', 'create', 'bind', 'skip', 'sync', 'sync-in-labels', 'summary-context', 'change-report', 'summary-sync'].includes(operation)) { fail('a valid operation is required'); return; }
-  if (operation === 'sync-in-labels') {
+  if (!operation || ![
+    internalHandlerRoute('platform-pr', 'inspect', operation),
+    internalHandlerRoute('platform-pr', 'resolve-external', operation),
+    internalHandlerRoute('platform-pr', 'create', operation),
+    internalHandlerRoute('platform-pr', 'bind', operation),
+    internalHandlerRoute('platform-pr', 'skip', operation),
+    internalHandlerRoute('platform-pr', 'sync', operation),
+    internalHandlerRoute('platform-pr', 'sync-in-labels', operation),
+    internalHandlerRoute('platform-pr', 'summary-context', operation),
+    internalHandlerRoute('platform-pr', 'change-report', operation),
+    internalHandlerRoute('platform-pr', 'summary-sync', operation)
+  ].some(Boolean)) { fail('a valid operation is required'); return; }
+  if (internalHandlerRoute('platform-pr', 'sync-in-labels', operation)) {
     const parsed = parse(args, 1);
     if (parsed.error) { fail(parsed.error); return; }
     const values = parsed.values;
@@ -98,24 +111,24 @@ 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; }
-  if (operation === 'inspect') { finish(await inspectPlatformPullRequest(taskRef, { cwd })); return; }
-  if (operation === 'summary-context') { finish(await summaryContext(taskRef, { cwd })); return; }
+  if (internalHandlerRoute('platform-pr', 'inspect', operation)) { finish(await inspectPlatformPullRequest(taskRef, { cwd })); return; }
+  if (internalHandlerRoute('platform-pr', 'summary-context', operation)) { finish(await summaryContext(taskRef, { cwd })); return; }
   if (typeof values.agent !== 'string' || !values.agent) { fail(`${operation} requires --agent`); return; }
   const agent = normalizeAgentToken(values.agent);
   if (!agent) { fail(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
   values.agent = agent;
-  if (operation === 'change-report') {
+  if (internalHandlerRoute('platform-pr', 'change-report', operation)) {
     if (typeof values.mechanicalFile !== 'string' || typeof values.precheckFile !== 'string') { fail('change-report requires --mechanical-file and --precheck-file'); return; }
     finish(await reportWrite(taskRef, {
       cwd, agent: values.agent, mechanicalFile: values.mechanicalFile, precheckFile: values.precheckFile, dryRun: values.dryRun === true
     }));
     return;
   }
-  if (operation === 'skip') {
+  if (internalHandlerRoute('platform-pr', 'skip', operation)) {
     finish(await skipPlatformPullRequestFact(taskRef, { cwd, agent, dryRun: values.dryRun === true }));
     return;
   }
@@ -124,30 +137,41 @@ async function platformPr(args: string[] = []): Promise<void> {
     fail('--result must be pr_created, pr_reused, or no_op');
     return;
   }
-  if (operation === 'resolve-external') {
+  if (internalHandlerRoute('platform-pr', 'resolve-external', operation)) {
     const pr = values.pr === undefined ? undefined : values.pr;
     if (pr !== undefined && (typeof pr !== 'string' || !pr)) { fail('resolve-external requires --pr <token>'); return; }
     finish(await resolveExternalPullRequest(taskRef, { cwd, agent: values.agent, pr, dryRun: values.dryRun === true }));
     return;
   }
-  if (operation === 'bind') {
+  if (internalHandlerRoute('platform-pr', 'bind', operation)) {
     const pr = values.pr;
     if (typeof pr !== 'string' || !pr) { fail('bind requires --pr <token>'); return; }
     finish(await bindPlatformPullRequest(taskRef, { cwd, agent: values.agent, pr, dryRun: values.dryRun === true }));
     return;
   }
-  if (operation === 'sync') {
+  if (internalHandlerRoute('platform-pr', 'sync', operation)) {
     if (values.metadata !== true && values.closingIssue !== true) { fail('sync requires --metadata or --closing-issue'); return; }
     if (!primaryResult) { fail('sync requires --result pr_created, pr_reused, or no_op'); return; }
     finish(await syncPlatformPullRequest(taskRef, { cwd, agent: values.agent, metadata: values.metadata === true, closingIssue: values.closingIssue === true, primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', dryRun: values.dryRun === true }));
     return;
   }
-  if (operation === 'summary-sync') {
+  if (internalHandlerRoute('platform-pr', 'summary-sync', operation)) {
     if (typeof values.bodyFile !== 'string') { fail('summary-sync requires --body-file'); return; }
     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/platform-release-notes.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { publishReleaseNotes, releaseNoteContext, stageReleaseNotes } from '../platform/release-notes.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 type ParsedOptions = Readonly<{ values: ReadonlyMap<string, string>; switches: ReadonlySet<string> }>;
 
@@ -37,8 +38,9 @@ function finish(result: { status: string; [key: string]: unknown }): void {
 }
 
 async function platformReleaseNotes(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('platform-release-notes', args)) return;
   const [action, ...rest] = args;
-  if (action === 'context') {
+  if (internalHandlerRoute('platform-release-notes', 'context', action ?? '')) {
     const parsed = parseOptions(rest, ['--cwd', '--history-limit', '--from-tag', '--to-tag', '--branch']);
     if (!parsed) return finish(invalidInput('invalid context options'));
     const cwd = path.resolve(parsed.values.get('--cwd') || process.cwd());
@@ -51,7 +53,7 @@ async function platformReleaseNotes(args: string[] = []): Promise<void> {
     }, { cwd }));
     return;
   }
-  if (action === 'stage') {
+  if (internalHandlerRoute('platform-release-notes', 'stage', action ?? '')) {
     const parsed = parseOptions(rest, ['--cwd', '--notes-file']);
     if (!parsed) return finish(invalidInput('invalid stage options'));
     const notesFile = parsed.values.get('--notes-file');
@@ -62,7 +64,7 @@ async function platformReleaseNotes(args: string[] = []): Promise<void> {
     ));
     return;
   }
-  if (action === 'publish') {
+  if (internalHandlerRoute('platform-release-notes', 'publish', action ?? '')) {
     const parsed = parseOptions(
       rest,
       ['--cwd', '--notes-file', '--tag', '--title', '--expected-sha256'],

package/lib/internal/platform-security.ts

@@ -0,0 +1,83 @@
+import path from 'node:path';
+
+import { dismissSecurityAlert, readCommentFile, readSecurityAlert } from '../platform/security-alerts.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
+
+const USAGE = `Usage: agent-infra-internal platform-security read --kind <dependabot|code-scanning> --number <number> [--cwd <path>]
+       agent-infra-internal platform-security dismiss --kind <dependabot|code-scanning> --number <number> --reason <reason> --comment-file <path> [--cwd <path>]
+`;
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'SECURITY_INPUT_INVALID', message, retryable: false } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function finish(result: { status: string; [key: string]: unknown }): void {
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = result.status === 'blocked' ? 2 : result.status === 'failed' ? 1 : 0;
+}
+
+function parseOptions(args: string[]): { values: Map<string, string>; switches: Set<string> } | null {
+  const values = new Map<string, string>();
+  const switches = new Set<string>();
+  const valueFlags = new Set(['--cwd', '--kind', '--number', '--reason', '--comment-file']);
+  for (let index = 0; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag === '--help' || flag === '-h') return null;
+    if (!valueFlags.has(flag) || values.has(flag) || switches.has(flag)) return null;
+    const value = args[++index];
+    if (!value || value.startsWith('--')) return null;
+    values.set(flag, value);
+  }
+  return { values, switches };
+}
+
+function required(values: Map<string, string>, flag: string): string | null {
+  const value = values.get(flag);
+  return value && !value.startsWith('--') ? value : null;
+}
+
+async function platformSecurity(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('platform-security', args)) return;
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const action = args[0];
+  if (!internalHandlerRoute('platform-security', 'read', action ?? '')
+    && !internalHandlerRoute('platform-security', 'dismiss', action ?? '')) {
+    fail('a valid operation is required');
+    return;
+  }
+  if (action !== 'read' && action !== 'dismiss') { fail('a valid operation is required'); return; }
+  const parsed = parseOptions(args.slice(1));
+  if (!parsed) { fail('invalid security alert options'); return; }
+  const kind = required(parsed.values, '--kind');
+  const numberRaw = required(parsed.values, '--number');
+  const cwd = path.resolve(required(parsed.values, '--cwd') || process.cwd());
+  if (!kind || !numberRaw) { fail(`${action} requires --kind and --number`); return; }
+  const number = Number(numberRaw);
+  if (!Number.isSafeInteger(number) || number <= 0) { fail('--number must be a positive integer'); return; }
+
+  if (action === 'read') {
+    if ([...parsed.values.keys()].some((flag) => !['--kind', '--number', '--cwd'].includes(flag))) {
+      fail('read does not accept dismissal options');
+      return;
+    }
+    finish(await readSecurityAlert({ kind: kind as 'dependabot' | 'code-scanning', number }, { cwd }));
+    return;
+  }
+
+  const reason = required(parsed.values, '--reason');
+  const commentFile = required(parsed.values, '--comment-file');
+  if (!reason || !commentFile) { fail('dismiss requires --reason and --comment-file'); return; }
+  const comment = readCommentFile(commentFile, cwd);
+  if (!comment.ok) {
+    finish({ status: 'failed', changed: false, error: comment.error });
+    return;
+  }
+  finish(await dismissSecurityAlert(
+    { kind: kind as 'dependabot' | 'code-scanning', number, reason, comment: comment.value },
+    { cwd }
+  ));
+}
+
+export { platformSecurity };

package/lib/internal/pr-review-grade.ts

@@ -11,6 +11,7 @@ import {
 import type { DecisionRecord, HostResolution } from '../pr-review/evidence-grading.ts';
 import { inspectPlatformPullRequestByNumber } from '../platform/pull-requests.ts';
 import { verifyInProcess } from '../task/verification-engine.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal pr-review-grade decide --input-file <path|-> [--cwd <path>]
        agent-infra-internal pr-review-grade resolve-host --pr <token> [--cwd <path>]
@@ -50,9 +51,14 @@ function readInput(value: string, cwd: string): string {
 }
 
 async function prReviewGrade(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('pr-review-grade', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
-  if (!operation || !['decide', 'resolve-host', 'verify-artifact'].includes(operation)) { fail('a valid operation is required'); return; }
+  if (!operation || ![
+    internalHandlerRoute('pr-review-grade', 'decide', operation),
+    internalHandlerRoute('pr-review-grade', 'resolve-host', operation),
+    internalHandlerRoute('pr-review-grade', 'verify-artifact', operation)
+  ].some(Boolean)) { fail('a valid operation is required'); return; }
   const parsed = parseFlags(args, 1);
   if (parsed.error) { fail(parsed.error); return; }
   const values = parsed.values;
@@ -65,7 +71,7 @@ async function prReviewGrade(args: string[] = []): Promise<void> {
   const unexpected = Object.keys(values).find((key) => !allowed[operation]!.includes(key));
   if (unexpected) { fail(`${operation} does not accept '--${unexpected}'`); return; }
 
-  if (operation === 'decide') {
+  if (internalHandlerRoute('pr-review-grade', 'decide', operation)) {
     if (typeof values.inputFile !== 'string') { fail('decide requires --input-file'); return; }
     let input: unknown;
     try {
@@ -84,7 +90,7 @@ async function prReviewGrade(args: string[] = []): Promise<void> {
     return;
   }
 
-  if (operation === 'resolve-host') {
+  if (internalHandlerRoute('pr-review-grade', 'resolve-host', operation)) {
     const pr = typeof values.pr === 'string' ? values.pr : '';
     if (!pr) { fail('resolve-host requires --pr <token>'); return; }
     const inspected = await inspectPlatformPullRequestByNumber(pr, { cwd });
@@ -109,6 +115,7 @@ async function prReviewGrade(args: string[] = []): Promise<void> {
     return;
   }
 
+  if (!internalHandlerRoute('pr-review-grade', 'verify-artifact', operation)) { fail('operation is not registered'); return; }
   if (typeof values.artifactFile !== 'string') { fail('verify-artifact requires --artifact-file'); return; }
   const artifactPath = path.resolve(cwd, values.artifactFile);
   let result: Record<string, unknown>;

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,114 +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',
@@ -125,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',
@@ -133,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 };
 }
 
@@ -206,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 ?? []
   };
@@ -312,20 +299,28 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
   const version = String(rawVersion || '').replace(/^v/, '');
   const cwdIndex = rest.indexOf('--cwd');
   const cwd = path.resolve(cwdIndex >= 0 && rest[cwdIndex + 1] ? rest[cwdIndex + 1]! : process.cwd());
-  if (!['inspect', 'prepare', 'publish', 'post-prepare', 'post-publish'].includes(action || '') || !semver.valid(version)) {
+  if (![
+    internalHandlerRoute('release-workflow', 'inspect', action || ''),
+    internalHandlerRoute('release-workflow', 'prepare', action || ''),
+    internalHandlerRoute('release-workflow', 'publish', action || ''),
+    internalHandlerRoute('release-workflow', 'post-prepare', action || ''),
+    internalHandlerRoute('release-workflow', 'post-publish', action || '')
+  ].some(Boolean) || !semver.valid(version)) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'RELEASE_INPUT_INVALID', message: 'Usage: release-workflow inspect|prepare|publish|post-prepare|post-publish <version>' } })}\n`);
     process.exitCode = 1; return;
   }
+  if (!ensureInternalHandlerRoute('release-workflow', args)) return;
   const before = releaseSnapshot(version, await inspectFacts(cwd, version));
-  if (action === 'inspect') { process.stdout.write(`${JSON.stringify({ status: 'no-op', changed: false, snapshot: before, error: null })}\n`); return; }
+  if (internalHandlerRoute('release-workflow', 'inspect', action || '')) { process.stdout.write(`${JSON.stringify({ status: 'no-op', changed: false, snapshot: before, error: null })}\n`); return; }
   if (before.facts.localTagConflict) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'GIT_TAG_CONFLICT', message: `Tag v${version} is not reachable from HEAD` } })}\n`);
     process.exitCode = 1; return;
   }
-  if (action === 'prepare') {
+  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;
     }
@@ -352,14 +347,14 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
     process.stdout.write(`${JSON.stringify({ status, changed: true, snapshot, operations: milestones?.operations ?? [], error: tagged.status !== 0 ? { code: 'GIT_TAG_FAILED', message: String(tagged.stderr) } : milestones?.error ?? null })}\n`);
     process.exitCode = failed ? 1 : blocked ? 2 : 0; return;
   }
-  if (action === 'publish') {
+  if (internalHandlerRoute('release-workflow', 'publish', action || '')) {
     if (!before.facts.localTag || !['prepared', 'partially-published'].includes(before.phase)) { process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'RELEASE_PHASE_INVALID', message: `Cannot publish from ${before.phase}` } })}\n`); process.exitCode = 1; return; }
     const branch = git(cwd, ['branch', '--show-current']) || '';
     const refs = [...(!before.facts.remoteBranch ? [branch] : []), ...(!before.facts.remoteTag ? [`refs/tags/v${version}`] : [])];
     const result = pushGitRefs({ cwd, remote: 'origin', refs });
     process.stdout.write(`${JSON.stringify({ ...result, snapshot: releaseSnapshot(version, await inspectFacts(cwd, version)) })}\n`); process.exitCode = result.status === 'failed' ? 1 : result.status === 'degraded' ? 2 : 0; return;
   }
-  if (action === 'post-publish') {
+  if (internalHandlerRoute('release-workflow', 'post-publish', action || '')) {
     const expectedValues = optionValues(rest, '--expected-sha256');
     if (expectedValues.length !== 1 || !/^sha256:[0-9a-f]{64}$/.test(expectedValues[0]!)) {
       process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'RELEASE_INPUT_INVALID', message: 'post-publish requires one --expected-sha256 sha256:<64 hex>' } })}\n`);
@@ -394,6 +389,10 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
     process.exitCode = blocked ? 2 : 1; return;
   }
 
+  if (!internalHandlerRoute('release-workflow', 'post-prepare', action || '')) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'RELEASE_INPUT_INVALID', message: 'release-workflow action is not registered' } })}\n`);
+    process.exitCode = 1; return;
+  }
   if (before.phase === 'complete') {
     process.stdout.write(`${JSON.stringify({ status: 'no-op', changed: false, snapshot: before, error: null })}\n`);
     return;
@@ -408,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`);
@@ -418,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;
@@ -437,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 };