vouchington-tooling 0.0.21 → 0.1.0

package/README.md

@@ -37,6 +37,7 @@ vouchington run-with-timeout 120 10 docker push example
 vouchington lint-links --offline
 vouchington materialize-pr-context
 vouchington wait-for-apt-locks
+vouchington retrospective-transcript --jsonl /path/to/transcript.jsonl
 vouchington install-playwright-chromium-arm64
 vouchington ghcr-package-retention example%2Fapi
 vouchington nuget-central-version trusted.props candidate.props metadata.json out.props
@@ -45,6 +46,12 @@ vouchington post-review
 vouchington stage-review-payload optional|required <source> <destination>
 ```
 
+`retrospective-transcript` discovers Codex and Claude transcripts by default. It also reads a
+Claude-compatible transcript when `CURSOR_SESSION_ID` is set, and Grok's `updates.jsonl` session
+layout when `GROK_SESSION_ID` is set. Use `--grok-sessions-dir` to point discovery at a nondefault
+Grok session root. Without `--session-id`, it reads those session identities from the host
+environment.
+
 Host-lock environment:
 
 | Variable                                | Default               | Meaning                                     |
@@ -83,6 +90,7 @@ import {
 import { createArtifactClassifier, runCleanup } from 'vouchington-tooling/gha-artifacts-cleanup'
 import { validateOptionalHttpOrigin } from 'vouchington-tooling/http-origin'
 import { boundPendingLine, splitCompleteLines } from 'vouchington-tooling/process-line-buffer'
+import { runBrowserSession } from 'vouchington-tooling/browser-session-runner'
 import {
   generateSchemaSnapshot,
   renderSchemaMarkdown,
@@ -111,8 +119,28 @@ import { validateNugetUpdate } from 'vouchington-tooling/nuget-central-version'
 import { normalizeSwiftSource } from 'vouchington-tooling/swift-semantic-equal'
 import { parseUniqueSwiftBinaryTargetChecksum } from 'vouchington-tooling/swift-source-offset'
 import { validateResolvedPinDelta } from 'vouchington-tooling/swift-resolved-pin-delta'
+import {
+  formatDiagnosticReportSummaries,
+  readDiagnosticReportSummaries,
+} from 'vouchington-tooling/vitest-diagnostics'
+import { runRetrospectiveTranscript } from 'vouchington-tooling/retrospective-transcript'
 ```
 
 The artifact, review-payload, HTTP body, and pagination APIs validate untrusted inputs at their
 boundaries. Review posting lives in `gha-post-review` and talks to GitHub only through caller-supplied
 credentials (job token or a minted Claude GitHub App token).
+
+`vitest-diagnostics` reads Node diagnostic report JSON from a caller-selected directory. It sorts
+filenames, tolerates partial files, returns only a bounded field allowlist, and never emits raw
+native frame symbols. Both structured reads and text rendering have hard report-count limits.
+
+`browser-session-runner` supervises caller-created browser-test processes. Callers supply command
+construction, line classification, retry/outcome policy, and budgets; the library owns process-group
+termination, output line buffering, shared deadlines, progress watchdogs, diagnostics, and parent signals.
+The returned process must identify a dedicated process group, such as a child spawned with
+`detached: true`; its `processGroupId` is signalled without assuming the child PID is a group ID.
+Stall exits use the caller's `classifyExit` policy, while parent signals and shared-deadline expiration
+are terminal. Output is decoded independently per stream; unfinished lines are classified at close and
+`diagnosticTailBytes` retains a UTF-8-safe tail no larger than its byte budget.
+The runner uses monotonic elapsed time, rejects timer budgets above Node's maximum delay, and waits for
+the dedicated process group to exit after the direct child closes so descendants cannot overlap a retry.

package/dist/browser-session-runner/attempt.d.mts

@@ -0,0 +1,2 @@
+import type { BrowserSessionDeps, BrowserSessionOptions, BrowserSessionResult } from './types.mts';
+export declare function runAttempt(options: BrowserSessionOptions, deps: BrowserSessionDeps, deadline: number, attempt: number): Promise<BrowserSessionResult>;

package/dist/browser-session-runner/attempt.mjs

@@ -0,0 +1,195 @@
+import { StringDecoder } from 'node:string_decoder';
+import { boundPendingLine, splitCompleteLines } from '../process-line-buffer/index.mjs';
+import { tailText } from './tail.mjs';
+import { TailQueue } from './tail-queue.mjs';
+export function runAttempt(options, deps, deadline, attempt) {
+    return new Promise((resolve, reject) => {
+        const startedAt = deps.now(), process = options.start(attempt);
+        if (!Number.isSafeInteger(process.processGroupId) ||
+            process.processGroupId <= 0 ||
+            process.processGroupId > 2_147_483_647) {
+            try {
+                process.kill('SIGKILL');
+            }
+            catch { }
+            throw new RangeError('processGroupId must be positive');
+        }
+        const maxTail = options.diagnosticTailBytes ?? 4096;
+        const drainTimeoutMs = options.graceMs + (options.processGroupDrainMs ?? options.graceMs);
+        const tail = new TailQueue(maxTail);
+        let startupProgress = false, semanticProgress = false;
+        let failure, hasFailure = false, childExited = false, closeExit, draining = false, drainDone = false, reason = 'exit', complete = false, terminating = false;
+        let killTimer, stallTimer;
+        const listeners = [];
+        const finish = (exit) => {
+            if (complete)
+                return;
+            complete = true;
+            deps.clearTimeout(deadlineTimer);
+            if (killTimer)
+                deps.clearTimeout(killTimer);
+            deps.clearTimeout(stallTimer);
+            for (const remove of listeners)
+                remove();
+            const result = {
+                attempts: 0,
+                deadlineExceeded: reason === 'deadline',
+                diagnosticTail: tailText(tail.toBuffer(), maxTail),
+                exit,
+                reason,
+                semanticProgress,
+                startupProgress,
+            };
+            if (hasFailure)
+                reject(failure);
+            else
+                resolve(result);
+        };
+        const signal = (value) => {
+            try {
+                deps.killProcessGroup(process.processGroupId, value);
+            }
+            catch { }
+            try {
+                process.kill(value);
+            }
+            catch { }
+        };
+        const terminate = (nextReason) => {
+            if (nextReason === 'deadline' && childExited && reason === 'exit')
+                return;
+            if (nextReason === 'parent-signal' || nextReason === 'deadline') {
+                if (reason === 'exit' || reason === 'startup-stall' || reason === 'semantic-stall')
+                    reason = nextReason;
+                else if (reason !== nextReason)
+                    return;
+            }
+            else if (reason !== 'exit')
+                return;
+            else if (nextReason !== 'exit')
+                reason = nextReason;
+            if (terminating)
+                return;
+            terminating = true;
+            killTimer = deps.setTimeout(() => {
+                if (deps.isProcessGroupAlive(process.processGroupId))
+                    signal('SIGKILL');
+            }, options.graceMs);
+            signal('SIGTERM');
+        };
+        const fail = (error) => {
+            if (hasFailure)
+                return;
+            failure = error;
+            hasFailure = true;
+            terminate('exit');
+        };
+        const drain = () => {
+            if (draining)
+                return;
+            draining = true;
+            void deps.waitForProcessGroupExit(process.processGroupId, drainTimeoutMs).then(() => {
+                drainDone = true;
+                if (closeExit)
+                    finish(closeExit);
+            }, (error) => {
+                fail(error);
+                finish(closeExit ?? { code: null, signal: null });
+            });
+        };
+        const armStall = (ms, nextReason) => {
+            if (stallTimer)
+                deps.clearTimeout(stallTimer);
+            stallTimer = deps.setTimeout(() => terminate(nextReason), ms);
+        };
+        const consume = () => {
+            const decoder = new StringDecoder('utf8');
+            let pending = '';
+            const line = (value) => {
+                const event = options.onLine(value);
+                if (event === 'startup' && !startupProgress) {
+                    startupProgress = true;
+                    if (!childExited)
+                        armStall(options.semanticStallMs, 'semantic-stall');
+                }
+                if (event === 'semantic') {
+                    semanticProgress = true;
+                    if (startupProgress && !childExited)
+                        armStall(options.semanticStallMs, 'semantic-stall');
+                }
+            };
+            const appendLines = (text) => {
+                tail.append(text);
+                const split = splitCompleteLines(pending + text);
+                pending = boundPendingLine(split.pending);
+                for (const value of split.complete)
+                    line(value);
+            };
+            return {
+                flush: () => {
+                    appendLines(decoder.end());
+                    if (pending)
+                        line(pending);
+                },
+                write: (chunk) => appendLines(decoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))),
+            };
+        };
+        const streams = [process.stdout, process.stderr].map((stream) => stream ? consume() : undefined);
+        for (const [index, stream] of [process.stdout, process.stderr].entries())
+            stream?.on('data', (chunk) => {
+                try {
+                    streams[index].write(chunk);
+                }
+                catch (error) {
+                    fail(error);
+                }
+            });
+        for (const stream of [process.stdout, process.stderr])
+            stream?.on('error', fail);
+        const remainingDeadlineMs = deadline - deps.now();
+        const deadlineTimer = deps.setTimeout(() => terminate('deadline'), Math.max(1, remainingDeadlineMs));
+        const remainingStartupMs = options.startupStallMs - (deps.now() - startedAt);
+        armStall(Math.max(1, remainingStartupMs), 'startup-stall');
+        if (remainingStartupMs <= 0)
+            terminate('startup-stall');
+        if (remainingDeadlineMs <= 0)
+            terminate('deadline');
+        for (const value of ['SIGINT', 'SIGTERM']) {
+            const listener = () => terminate('parent-signal');
+            deps.onParentSignal(value, listener);
+            listeners.push(() => deps.offParentSignal(value, listener));
+        }
+        process.on('error', () => terminate('exit'));
+        process.on('exit', () => {
+            if (reason === 'exit' && deps.now() >= deadline)
+                reason = 'deadline';
+            childExited = true;
+            deps.clearTimeout(stallTimer);
+            if (!deps.isProcessGroupAlive(process.processGroupId))
+                return;
+            terminate(reason);
+            drain();
+        });
+        process.on('close', (code, value) => {
+            for (const stream of streams)
+                try {
+                    stream?.flush();
+                }
+                catch (error) {
+                    fail(error);
+                }
+            if (!childExited &&
+                deps.now() >= deadline &&
+                reason !== 'parent-signal' &&
+                reason !== 'deadline')
+                reason = 'deadline';
+            closeExit = { code, signal: value };
+            if (!deps.isProcessGroupAlive(process.processGroupId))
+                return finish(closeExit);
+            terminate(reason);
+            drain();
+            if (drainDone || hasFailure)
+                finish(closeExit);
+        });
+    });
+}

package/dist/browser-session-runner/index.d.mts

@@ -0,0 +1,4 @@
+import type { BrowserSessionDeps, BrowserSessionOptions, BrowserSessionResult } from './types.mts';
+export type { BrowserSessionDeps, BrowserSessionEvent, BrowserSessionExit, BrowserSessionOptions, BrowserSessionProcess, BrowserSessionResult, } from './types.mts';
+export { ProcessGroupDrainTimeoutError } from './process-group.mts';
+export declare function runBrowserSession(options: BrowserSessionOptions, deps?: BrowserSessionDeps): Promise<BrowserSessionResult>;

package/dist/browser-session-runner/index.mjs

@@ -0,0 +1,64 @@
+import { runAttempt } from './attempt.mjs';
+import { expiredResult } from './result.mjs';
+import { isProcessGroupAlive, waitForProcessGroupExit } from './process-group.mjs';
+export { ProcessGroupDrainTimeoutError } from './process-group.mjs';
+const defaultDeps = {
+    clearInterval,
+    clearTimeout,
+    isProcessGroupAlive,
+    killProcessGroup: (processGroupId, signal) => {
+        try {
+            process.kill(-processGroupId, signal);
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                throw error;
+        }
+    },
+    now: () => performance.now(),
+    offParentSignal: (signal, listener) => process.off(signal, listener),
+    onParentSignal: (signal, listener) => process.on(signal, listener),
+    setInterval,
+    setTimeout,
+    waitForProcessGroupExit,
+};
+export async function runBrowserSession(options, deps = defaultDeps) {
+    validateOptions(options);
+    if (deps === defaultDeps && process.platform === 'win32')
+        throw new Error('browser-session-runner default process-group control is unsupported on Windows');
+    const deadline = deps.now() + options.deadlineMs;
+    let last;
+    let attempts = 0;
+    for (let attempt = 1; attempt <= options.attempts && deps.now() < deadline; attempt += 1) {
+        attempts = attempt;
+        last = await runAttempt(options, deps, deadline, attempt);
+        if (last.reason === 'parent-signal' ||
+            last.reason === 'deadline' ||
+            options.classifyExit(last.exit, omitAttempts(last)) !== 'retry')
+            return { ...last, attempts };
+    }
+    if (attempts === options.attempts)
+        return { ...last, attempts };
+    return { ...(last ?? expiredResult()), attempts, deadlineExceeded: true, reason: 'deadline' };
+}
+function validateOptions(options) {
+    const maxTimerDelay = 2_147_483_647;
+    for (const [name, value] of [
+        ['attempts', options.attempts],
+        ['deadlineMs', options.deadlineMs],
+        ['graceMs', options.graceMs],
+        ['processGroupDrainMs', options.processGroupDrainMs ?? options.graceMs],
+        ['semanticStallMs', options.semanticStallMs],
+        ['startupStallMs', options.startupStallMs],
+        ['watchdogIntervalMs', options.watchdogIntervalMs ?? 1000],
+    ]) {
+        if (!Number.isSafeInteger(value) || value <= 0 || value > maxTimerDelay)
+            throw new RangeError(`${name} must be a positive Node timer delay`);
+    }
+    const tailBytes = options.diagnosticTailBytes ?? 4096;
+    if (!Number.isSafeInteger(tailBytes) || tailBytes <= 0)
+        throw new RangeError('diagnosticTailBytes must be positive');
+}
+function omitAttempts({ attempts: _attempts, ...result }) {
+    return result;
+}

package/dist/browser-session-runner/process-group.d.mts

@@ -0,0 +1,5 @@
+export declare class ProcessGroupDrainTimeoutError extends Error {
+    constructor(processGroupId: number, timeoutMs: number);
+}
+export declare function isProcessGroupAlive(processGroupId: number): boolean;
+export declare function waitForProcessGroupExit(processGroupId: number, timeoutMs: number): Promise<void>;

package/dist/browser-session-runner/process-group.mjs

@@ -0,0 +1,23 @@
+export class ProcessGroupDrainTimeoutError extends Error {
+    constructor(processGroupId, timeoutMs) {
+        super(`Process group ${processGroupId} did not exit within ${timeoutMs}ms after SIGKILL`);
+        this.name = 'ProcessGroupDrainTimeoutError';
+    }
+}
+export function isProcessGroupAlive(processGroupId) {
+    try {
+        process.kill(-processGroupId, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+export async function waitForProcessGroupExit(processGroupId, timeoutMs) {
+    const deadline = performance.now() + timeoutMs;
+    while (isProcessGroupAlive(processGroupId)) {
+        if (performance.now() >= deadline)
+            throw new ProcessGroupDrainTimeoutError(processGroupId, timeoutMs);
+        await new Promise((resolve) => setTimeout(resolve, Math.min(10, deadline - performance.now())));
+    }
+}

package/dist/browser-session-runner/result.d.mts

@@ -0,0 +1,2 @@
+import type { BrowserSessionResult } from './types.mts';
+export declare function expiredResult(): BrowserSessionResult;

package/dist/browser-session-runner/result.mjs

@@ -0,0 +1,11 @@
+export function expiredResult() {
+    return {
+        attempts: 0,
+        deadlineExceeded: true,
+        diagnosticTail: '',
+        exit: { code: null, signal: null },
+        reason: 'deadline',
+        semanticProgress: false,
+        startupProgress: false,
+    };
+}

package/dist/browser-session-runner/tail-queue.d.mts

@@ -0,0 +1,8 @@
+export declare class TailQueue {
+    readonly maxBytes: number;
+    readonly chunks: Buffer[];
+    bytes: number;
+    constructor(maxBytes: number);
+    append(text: string): void;
+    toBuffer(): Buffer;
+}

package/dist/browser-session-runner/tail-queue.mjs

@@ -0,0 +1,30 @@
+export class TailQueue {
+    maxBytes;
+    chunks = [];
+    bytes = 0;
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+    }
+    append(text) {
+        const chunk = Buffer.from(text);
+        if (chunk.length >= this.maxBytes) {
+            this.chunks.splice(0, this.chunks.length, chunk.subarray(-this.maxBytes));
+            this.bytes = this.maxBytes;
+            return;
+        }
+        this.chunks.push(chunk);
+        this.bytes += chunk.length;
+        while (this.bytes > this.maxBytes) {
+            const first = this.chunks[0];
+            const overflow = this.bytes - this.maxBytes;
+            if (first.length <= overflow)
+                this.chunks.shift();
+            else
+                this.chunks[0] = first.subarray(overflow);
+            this.bytes -= Math.min(first.length, overflow);
+        }
+    }
+    toBuffer() {
+        return Buffer.concat(this.chunks, this.bytes);
+    }
+}

package/dist/browser-session-runner/tail.d.mts

@@ -0,0 +1 @@
+export declare function tailText(tail: Buffer, maxBytes: number): string;

package/dist/browser-session-runner/tail.mjs

@@ -0,0 +1,12 @@
+export function tailText(tail, maxBytes) {
+    const bounded = tail.subarray(Math.max(0, tail.length - maxBytes));
+    for (let start = 0; start < Math.min(4, bounded.length); start += 1) {
+        for (let end = 0; end < Math.min(4, bounded.length - start); end += 1) {
+            try {
+                return new TextDecoder('utf-8', { fatal: true }).decode(bounded.subarray(start, bounded.length - end));
+            }
+            catch { }
+        }
+    }
+    return '';
+}

package/dist/browser-session-runner/types.d.mts

@@ -0,0 +1,53 @@
+import type { ChildProcess } from 'node:child_process';
+export type BrowserSessionEvent = 'startup' | 'semantic';
+export type BrowserSessionExit = {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+};
+type BrowserSessionStream = {
+    on(event: 'data', listener: (chunk: string | Buffer) => void): unknown;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+};
+export type BrowserSessionResult = {
+    attempts: number;
+    deadlineExceeded: boolean;
+    diagnosticTail: string;
+    exit: BrowserSessionExit;
+    reason: 'exit' | 'parent-signal' | 'semantic-stall' | 'startup-stall' | 'deadline';
+    startupProgress: boolean;
+    semanticProgress: boolean;
+};
+export type BrowserSessionProcess = Pick<ChildProcess, 'kill'> & {
+    processGroupId: number;
+    on(event: 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    stderr?: BrowserSessionStream | null;
+    stdout?: BrowserSessionStream | null;
+};
+export type BrowserSessionDeps = {
+    clearInterval(handle: unknown): void;
+    clearTimeout(handle: unknown): void;
+    isProcessGroupAlive(processGroupId: number): boolean;
+    killProcessGroup(processGroupId: number, signal: NodeJS.Signals): void;
+    now(): number;
+    offParentSignal(signal: NodeJS.Signals, listener: () => void): void;
+    onParentSignal(signal: NodeJS.Signals, listener: () => void): void;
+    setInterval(callback: () => void, ms: number): unknown;
+    setTimeout(callback: () => void, ms: number): unknown;
+    waitForProcessGroupExit(processGroupId: number, timeoutMs: number): Promise<void>;
+};
+export type BrowserSessionOptions = {
+    attempts: number;
+    classifyExit(exit: BrowserSessionExit, result: Omit<BrowserSessionResult, 'attempts'>): 'retry' | 'return';
+    deadlineMs: number;
+    diagnosticTailBytes?: number;
+    graceMs: number;
+    onLine(line: string): BrowserSessionEvent | undefined;
+    processGroupDrainMs?: number;
+    semanticStallMs: number;
+    start(attempt: number): BrowserSessionProcess;
+    startupStallMs: number;
+    watchdogIntervalMs?: number;
+};
+export {};

package/dist/browser-session-runner/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/cli/commands/retrospective-transcript.d.mts

@@ -0,0 +1 @@
+export declare function runRetrospectiveTranscriptCommand(args: string[]): Promise<number>;

package/dist/cli/commands/retrospective-transcript.mjs

@@ -0,0 +1,31 @@
+import { parseArgs } from 'node:util';
+import { runRetrospectiveTranscript, } from '../../retrospective-transcript/index.mjs';
+export async function runRetrospectiveTranscriptCommand(args) {
+    try {
+        const { values } = parseArgs({
+            args,
+            strict: true,
+            options: {
+                'session-id': { type: 'string' },
+                jsonl: { type: 'string' },
+                'projects-dir': { type: 'string' },
+                'codex-sessions-dir': { type: 'string' },
+                'grok-sessions-dir': { type: 'string' },
+            },
+        });
+        const options = {
+            ...(values['session-id'] ? { sessionId: values['session-id'] } : {}),
+            ...(values.jsonl ? { jsonlPath: values.jsonl } : {}),
+            ...(values['projects-dir'] ? { projectsDir: values['projects-dir'] } : {}),
+            ...(values['codex-sessions-dir'] ? { codexSessionsDir: values['codex-sessions-dir'] } : {}),
+            ...(values['grok-sessions-dir'] ? { grokSessionsDir: values['grok-sessions-dir'] } : {}),
+            env: process.env,
+        };
+        process.stdout.write(await runRetrospectiveTranscript(options));
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
+}

package/dist/cli/index.mjs

@@ -14,6 +14,7 @@ import { runPostReviewCommand } from './commands/post-review.mjs';
 import { runStageReviewPayloadCommand } from './commands/stage-review-payload.mjs';
 import { runSwiftSemanticEqualCommand } from './commands/swift-semantic-equal.mjs';
 import { runVitestBlobManifestCommand } from './commands/vitest-blob-manifest.mjs';
+import { runRetrospectiveTranscriptCommand } from './commands/retrospective-transcript.mjs';
 import { runWithHostLock } from './commands/with-host-lock.mjs';
 import { parseCli } from './parse.mjs';
 import { packageScriptPath } from './script-path.mjs';
@@ -92,6 +93,8 @@ export function runCli(argv = process.argv) {
             return runHttpOrigin(parsed.field, parsed.value);
         case 'gha-artifacts-cleanup':
             return runGhaArtifactsCleanup(parsed);
+        case 'retrospective-transcript':
+            return runRetrospectiveTranscriptCommand(parsed.args);
     }
 }
 function readInstalledVersion() {

package/dist/cli/parse.d.mts

@@ -40,6 +40,9 @@ export type ParsedCli = {
     kind: 'http-origin';
     field: string;
     value: string;
+} | {
+    kind: 'retrospective-transcript';
+    args: string[];
 } | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup;
 export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release' | 'run-with-timeout' | 'lint-links' | 'materialize-pr-context' | 'wait-for-apt-locks' | 'install-playwright-chromium-arm64' | 'ghcr-package-retention';
 export declare function parseCli(argv: readonly string[]): ParsedCli;

package/dist/cli/parse.mjs

@@ -47,6 +47,8 @@ export function parseCli(argv) {
         return { kind: 'stage-review-payload', args: rest };
     if (command === 'http-origin')
         return parseHttpOrigin(rest);
+    if (command === 'retrospective-transcript')
+        return { kind: 'retrospective-transcript', args: rest };
     if (command === 'gha-artifacts-cleanup')
         return parseGhaArtifactsCleanup(rest);
     if (command !== undefined && SCRIPT_COMMANDS.has(command)) {

package/dist/cli/usage.d.mts

@@ -1,2 +1,2 @@
-export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\nhost-pressure-diagnostics\nallocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\n";
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\nhost-pressure-diagnostics\nallocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

@@ -30,6 +30,7 @@ Commands:
   swift-semantic-equal          Compare Swift sources ignoring comments and whitespace
   post-review                   Post one COMMENT review from a staged payload file
   stage-review-payload          Validate a review payload file into a staging directory
+  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts
 
 Options:
   -h, --help       Show this help
@@ -82,6 +83,7 @@ nuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-
 swift-semantic-equal <base> <head> <file.swift>
 post-review
 stage-review-payload optional|required <source> <destination>
+retrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]
 `;
 export function printUsage(stream = process.stdout) {
     stream.write(USAGE);

package/dist/coverage-transport/outcome.mjs

@@ -23,7 +23,9 @@ export function assertCoverageTransportOutcome(suite, primary, artifactAttempt1,
         return true;
     }
     if (artifactSucceeded) {
-        emit(`::warning::Coverage persisted only to GitHub artifacts for suite=${suite}; S3 primary is degraded.`);
+        if (primary !== 'skipped') {
+            emit(`::warning::Coverage persisted only to GitHub artifacts for suite=${suite}; S3 primary is degraded.`);
+        }
         return true;
     }
     emit(`::error::COVERAGE_TRANSPORT_EXHAUSTED suite=${suite} Neither S3 nor GitHub artifacts persisted the coverage pair.`);

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+export { codexChildren, codexIdentity, computeTranscriptFacts, formatTranscriptFacts, formatUnavailable, resolveTranscriptFile, runRetrospectiveTranscript, } from './retrospective-transcript/index.mts';
+export type { ResolveOptions, TokenTotals, TranscriptFacts, } from './retrospective-transcript/index.mts';
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mts';
 export type { EphemeralListenerOptions, RunnerPortPolicy } from './runner-port-policy/index.mts';
 export { extractAlterTableAddColumnLocations, extractCreateIndexMetadata, extractCreateTableMetadata, extractDefaultFunction, extractDropIndexMetadata, extractFuncCallArgColumnNames, extractMigrationConstraintMetadata, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mts';
@@ -20,6 +22,8 @@ export { createArtifactClassifier, parseArtifactPatternsJson, planRunDeletions,
 export type { ArtifactClassification, ArtifactClassifier, ArtifactPatterns, CleanupRequest, DeletionSummary, } from './gha-artifacts-cleanup/index.mts';
 export { validateOptionalHttpOrigin } from './http-origin/index.mts';
 export { boundPendingLine, DEFAULT_MAX_PENDING_LINE_LENGTH, DEFAULT_TRUNCATED_LINE_MARKER, splitCompleteLines, } from './process-line-buffer/index.mts';
+export { ProcessGroupDrainTimeoutError, runBrowserSession, } from './browser-session-runner/index.mts';
+export type { BrowserSessionDeps, BrowserSessionEvent, BrowserSessionExit, BrowserSessionOptions, BrowserSessionProcess, BrowserSessionResult, } from './browser-session-runner/index.mts';
 export { buildSchemaSnapshot, detectRenamedIndexes, generateSchemaSnapshot, indexShapeKey, readSchemaCatalog, renderSchemaMarkdown, stableStringify, writeSchemaSnapshot, } from './pg-schema-snapshot/index.mts';
 export type { CatalogQuery, PartitionPolicy, SchemaCatalog, SchemaGrowthMaps, SchemaSnapshot, SchemaTableSnapshot, } from './pg-schema-snapshot/index.mts';
 export { buildOpenApiDocument, hashContractSchema, nodeToOpenApi, writeOpenApi, } from './openapi-document/index.mts';
@@ -56,3 +60,5 @@ export { normalizeSwiftSource } from './swift-semantic-equal/index.mts';
 export { isSwiftCodeOffset, parseUniqueSwiftBinaryTargetChecksum, } from './swift-source-offset/index.mts';
 export { validateResolvedPinDelta } from './swift-resolved-pin-delta/index.mts';
 export type { ResolvedDocument, ResolvedPin, ValidateResolvedPinDeltaOptions, } from './swift-resolved-pin-delta/index.mts';
+export { DEFAULT_MAX_DIAGNOSTIC_REPORTS, DEFAULT_MAX_FORMATTED_DIAGNOSTIC_REPORTS, formatDiagnosticReportSummaries, HARD_MAX_DIAGNOSTIC_REPORTS, readDiagnosticReportSummaries, summarizeDiagnosticReport, } from './vitest-diagnostics/index.mts';
+export type { DiagnosticReportLimitOptions, DiagnosticReportSummary, } from './vitest-diagnostics/index.mts';