@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/dist/lib/internal/manual-validation.js

@@ -0,0 +1,331 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { locateActivityLog, pairEntries } from '../task/activity-log.js';
+import { resolveTaskRef } from '../task/resolve-ref.js';
+import { applyTaskEvent } from '../task/events.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.js';
+import { normalizeAgentToken } from '../agent-clients/tokens.js';
+import { createManualValidationReceipt, manualValidationFinalSummaryDigest, manualValidationFinalSummaryProjectionMatches, readManualValidationReceipt, writeManualValidationReceiptAtomic } from '../task/manual-validation-receipt.js';
+import { archiveManualValidationGeneration, createManualValidationTransaction, readManualValidationTransaction, retryManualValidationTransaction, summaryPreimageDigest, transitionManualValidationTransaction, validateManualValidationGenerationArchive, writeManualValidationTransactionAtomic } from '../task/manual-validation-transaction.js';
+import { sha256File } from '../task/artifact-receipts.js';
+import { summaryCommentState, syncPullRequestSummary } from '../platform/pr-summary.js';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
+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>]`;
+function result(status, error = null, extra = {}) {
+    return { status, changed: false, error, ...extra };
+}
+function printFailure(format, error) {
+    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, phase, transactionId, receiptDigest = '', evidenceDigest = '', prHeadSha = '') {
+    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) {
+    let content;
+    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, values, cwd, options = {}) {
+    const prepareOnly = values.prepare === 'true';
+    const required = prepareOnly
+        ? ['artifact', 'summaryFile', 'agent']
+        : ['artifact', 'summaryFile', 'changeReportFile', 'agent'];
+    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, prepareOnly, options));
+    }
+    catch (error) {
+        if (error instanceof TaskExecutionLockError)
+            return result('failed', { code: error.code, message: error.message });
+        throw error;
+    }
+}
+async function executeManualValidationTransactionLocked(taskRef, values, cwd, resolved, agent, primaryResult, prepareOnly, options) {
+    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 = 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 = () => 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;
+    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) => {
+        throw new Error(`${failure.code}: ${failure.message}`);
+    };
+    const transitionAndPersist = (phase, patch = {}) => {
+        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, 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;
+        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, 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, start) {
+    const values = {};
+    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) => letter.toUpperCase());
+        if (values[key])
+            return { values, error: `duplicate option '${flag}'` };
+        values[key] = value;
+    }
+    return { values };
+}
+async function manualValidation(args = []) {
+    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 };
+//# sourceMappingURL=manual-validation.js.map

package/dist/lib/internal/platform-pr.js

@@ -13,10 +13,10 @@ 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) {
     return flag.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
 }
@@ -122,7 +122,7 @@ async function platformPr(args = []) {
         '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) {
@@ -210,7 +210,21 @@ async function platformPr(args = []) {
             return;
         }
         try {
-            finish(await syncPullRequestSummary(taskRef, { cwd, agent: values.agent, body: readFile(values.bodyFile, cwd), changeReportFile: values.changeReportFile, primaryResult: primaryResult, 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, 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/dist/lib/internal/release-workflow.js

@@ -1,113 +1,78 @@
 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';
 import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs } from '../git/workflow.js';
 import { inspectPlatformRelease, reconcileReleaseMilestones } from '../platform/releases.js';
 import { inspectHomebrewChannel, inspectNpmChannel } from '../release/channels.js';
 import { releaseSnapshot } from '../release/workflow.js';
+import { collectDemoTranscript } from './demo-transcript.js';
+import { createDemoPromotion, promoteDemoAssets, recoverDemoPromotion } from './demo-promotion.js';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
-function command(cwd, executable, args) {
-    return spawnSync(executable, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+function command(cwd, executable, args, options = {}) {
+    return spawnSync(executable, args, {
+        cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, ...options.env }
+    });
 }
-// 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/'
-];
-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) {
-    const files = new Set();
-    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) {
-    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) {
     if (!fs.existsSync(filePath))
         return false;
     const header = fs.readFileSync(filePath).subarray(0, 6).toString('ascii');
     return header === 'GIF87a' || header === 'GIF89a';
 }
-function writeDigestAtomically(cwd, digest) {
-    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, run = command) {
-    let digest;
-    try {
-        digest = computeDemoInputDigest(cwd);
+async function runOptionalDemo(cwd, run = command, collect = collectDemoTranscript) {
+    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 };
     }
-    catch (error) {
-        return { status: 'failed', reasonCode: 'DEMO_DIGEST_FAILED', message: String(error), 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',
@@ -116,7 +81,8 @@ function runOptionalDemo(cwd, run = command) {
         };
     }
     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',
@@ -124,18 +90,24 @@ function runOptionalDemo(cwd, run = command) {
             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 };
 }
 function git(cwd, args, run = command, trim = true) {
@@ -189,7 +161,7 @@ function inspectPostReleaseFacts(cwd, commit, run = command) {
         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 ?? []
     };
@@ -322,7 +294,8 @@ async function releaseWorkflow(args = []) {
     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;
         }
@@ -446,6 +419,12 @@ async function releaseWorkflow(args = []) {
         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`);
@@ -458,7 +437,7 @@ async function releaseWorkflow(args = []) {
         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;
@@ -487,5 +466,5 @@ async function releaseWorkflow(args = []) {
     }
     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 };
 //# sourceMappingURL=release-workflow.js.map