vouchington-tooling 0.0.22 → 0.1.1

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,196 @@
+import { createOutputConsumer } from './output.mjs';
+import { tailText } from './tail.mjs';
+import { TailQueue } from './tail-queue.mjs';
+import { createWatchdogLifecycle, registerWatchdogSetup } from './watchdog.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 watchdog = createWatchdogLifecycle();
+        const listeners = [];
+        const captureFailure = (error) => !hasFailure && ((failure = error), (hasFailure = true));
+        const finish = (exit) => {
+            if (complete)
+                return;
+            complete = true;
+            deps.clearTimeout(deadlineTimer);
+            if (killTimer)
+                deps.clearTimeout(killTimer);
+            deps.clearTimeout(stallTimer);
+            watchdog.complete(captureFailure);
+            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 || complete)
+                return;
+            captureFailure(error);
+            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 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 streams = [process.stdout, process.stderr].map((stream, index) => stream
+            ? createOutputConsumer(options, tail, index === 0 ? 'stdout' : 'stderr', line)
+            : 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);
+        });
+        try {
+            const setup = options.watchdog?.({
+                attempt,
+                deadline,
+                now: () => deps.now(),
+                process,
+                terminate: () => {
+                    if (!childExited)
+                        terminate('provider-watchdog');
+                },
+            });
+            registerWatchdogSetup(setup, watchdog, fail);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+}

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, BrowserSessionOutput, BrowserSessionProcess, BrowserSessionResult, BrowserSessionTerminationReason, BrowserSessionWatchdog, BrowserSessionWatchdogCleanup, BrowserSessionWatchdogController, } 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,68 @@
+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)), attempts };
+        options.onAttemptComplete?.(snapshotResult(last));
+        if (last.reason === 'parent-signal' ||
+            last.reason === 'deadline' ||
+            options.classifyExit(last.exit, omitAttempts(last)) !== 'retry')
+            return last;
+    }
+    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;
+}
+function snapshotResult(result) {
+    return { ...result, exit: { ...result.exit } };
+}

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

@@ -0,0 +1,8 @@
+import type { BrowserSessionOptions, BrowserSessionOutput } from './types.mts';
+import type { TailQueue } from './tail-queue.mts';
+type OutputConsumer = {
+    flush(): void;
+    write(chunk: string | Buffer): void;
+};
+export declare function createOutputConsumer(options: BrowserSessionOptions, tail: TailQueue, source: BrowserSessionOutput['source'], onLine: (line: string) => void): OutputConsumer;
+export {};

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

@@ -0,0 +1,24 @@
+import { StringDecoder } from 'node:string_decoder';
+import { boundPendingLine, splitCompleteLines } from '../process-line-buffer/index.mjs';
+export function createOutputConsumer(options, tail, source, onLine) {
+    const decoder = new StringDecoder('utf8');
+    let pending = '';
+    const appendLines = (text) => {
+        tail.append(text);
+        const split = splitCompleteLines(pending + text);
+        pending = boundPendingLine(split.pending);
+        for (const value of split.complete)
+            onLine(value);
+    };
+    return {
+        flush: () => {
+            appendLines(decoder.end());
+            if (pending)
+                onLine(pending);
+        },
+        write: (chunk) => {
+            options.onOutput?.({ chunk, source });
+            appendLines(decoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+        },
+    };
+}

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,70 @@
+import type { ChildProcess } from 'node:child_process';
+export type BrowserSessionEvent = 'startup' | 'semantic';
+export type BrowserSessionExit = {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+};
+export type BrowserSessionOutput = {
+    chunk: string | Buffer;
+    source: 'stderr' | 'stdout';
+};
+export type BrowserSessionTerminationReason = 'deadline' | 'parent-signal' | 'provider-watchdog' | 'semantic-stall' | 'startup-stall';
+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' | BrowserSessionTerminationReason;
+    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 BrowserSessionWatchdogController = {
+    attempt: number;
+    deadline: number;
+    now(): number;
+    process: BrowserSessionProcess;
+    terminate(reason?: 'provider-watchdog'): void;
+};
+export type BrowserSessionWatchdogCleanup = () => void;
+export type BrowserSessionWatchdog = (controller: BrowserSessionWatchdogController) => void | BrowserSessionWatchdogCleanup | Promise<void | BrowserSessionWatchdogCleanup>;
+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;
+    onOutput?(output: BrowserSessionOutput): void;
+    onAttemptComplete?(result: BrowserSessionResult): void;
+    processGroupDrainMs?: number;
+    semanticStallMs: number;
+    start(attempt: number): BrowserSessionProcess;
+    startupStallMs: number;
+    watchdogIntervalMs?: number;
+    watchdog?: BrowserSessionWatchdog;
+};
+export {};

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

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

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

@@ -0,0 +1,10 @@
+export type WatchdogCleanup = () => void;
+type WatchdogSetup = void | WatchdogCleanup | Promise<void | WatchdogCleanup>;
+type WatchdogLifecycle = ReturnType<typeof createWatchdogLifecycle>;
+export declare function createWatchdogLifecycle(): {
+    complete: (onError: (error: unknown) => void) => void;
+    isComplete: () => boolean;
+    register: (next: void | WatchdogCleanup, onError: (error: unknown) => void) => void;
+};
+export declare function registerWatchdogSetup(setup: WatchdogSetup, lifecycle: WatchdogLifecycle, onError: (error: unknown) => void): void;
+export {};

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

@@ -0,0 +1,38 @@
+export function createWatchdogLifecycle() {
+    let complete = false;
+    let cleanup;
+    const run = (next, onError) => {
+        try {
+            next();
+        }
+        catch (error) {
+            onError(error);
+        }
+    };
+    return {
+        complete: (onError) => {
+            complete = true;
+            if (!cleanup)
+                return;
+            const next = cleanup;
+            cleanup = undefined;
+            run(next, onError);
+        },
+        isComplete: () => complete,
+        register: (next, onError) => {
+            if (!next)
+                return;
+            if (complete)
+                return run(next, onError);
+            cleanup = next;
+        },
+    };
+}
+export function registerWatchdogSetup(setup, lifecycle, onError) {
+    if (!(setup instanceof Promise))
+        return lifecycle.register(setup, onError);
+    void setup.then((cleanup) => lifecycle.register(cleanup, onError), (error) => {
+        if (!lifecycle.isComplete())
+            onError(error);
+    });
+}

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;