vouchington-tooling 0.0.22 → 0.1.1

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/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, BrowserSessionOutput, BrowserSessionProcess, BrowserSessionResult, BrowserSessionTerminationReason, BrowserSessionWatchdog, BrowserSessionWatchdogCleanup, BrowserSessionWatchdogController, } 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';

package/dist/index.mjs

@@ -1,4 +1,5 @@
 /* eslint-disable max-lines -- package entry point enumerates the supported public API. */
+export { codexChildren, codexIdentity, computeTranscriptFacts, formatTranscriptFacts, formatUnavailable, resolveTranscriptFile, runRetrospectiveTranscript, } from './retrospective-transcript/index.mjs';
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mjs';
 export { extractAlterTableAddColumnLocations, extractCreateIndexMetadata, extractCreateTableMetadata, extractDefaultFunction, extractDropIndexMetadata, extractFuncCallArgColumnNames, extractMigrationConstraintMetadata, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mjs';
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from './sql-scanner/index.mjs';
@@ -12,6 +13,7 @@ export { decodeSelectedFiles, encodeSelectedFiles, formatMultilineOutput, SELECT
 export { createArtifactClassifier, parseArtifactPatternsJson, planRunDeletions, runCleanup, sweepCleanup, } from './gha-artifacts-cleanup/index.mjs';
 export { validateOptionalHttpOrigin } from './http-origin/index.mjs';
 export { boundPendingLine, DEFAULT_MAX_PENDING_LINE_LENGTH, DEFAULT_TRUNCATED_LINE_MARKER, splitCompleteLines, } from './process-line-buffer/index.mjs';
+export { ProcessGroupDrainTimeoutError, runBrowserSession, } from './browser-session-runner/index.mjs';
 export { buildSchemaSnapshot, detectRenamedIndexes, generateSchemaSnapshot, indexShapeKey, readSchemaCatalog, renderSchemaMarkdown, stableStringify, writeSchemaSnapshot, } from './pg-schema-snapshot/index.mjs';
 export { buildOpenApiDocument, hashContractSchema, nodeToOpenApi, writeOpenApi, } from './openapi-document/index.mjs';
 export { decide, deriveRetryAttempt } from './transient-retry/index.mjs';
@@ -33,3 +35,4 @@ export { validateNugetUpdate } from './nuget-central-version/index.mjs';
 export { normalizeSwiftSource } from './swift-semantic-equal/index.mjs';
 export { isSwiftCodeOffset, parseUniqueSwiftBinaryTargetChecksum, } from './swift-source-offset/index.mjs';
 export { validateResolvedPinDelta } from './swift-resolved-pin-delta/index.mjs';
+export { DEFAULT_MAX_DIAGNOSTIC_REPORTS, DEFAULT_MAX_FORMATTED_DIAGNOSTIC_REPORTS, formatDiagnosticReportSummaries, HARD_MAX_DIAGNOSTIC_REPORTS, readDiagnosticReportSummaries, summarizeDiagnosticReport, } from './vitest-diagnostics/index.mjs';

package/dist/retrospective-transcript/claude.d.mts

@@ -0,0 +1,2 @@
+import { type TranscriptFacts } from './shared.mts';
+export declare function computeClaude(lines: string[][]): TranscriptFacts;

package/dist/retrospective-transcript/claude.mjs

@@ -0,0 +1,67 @@
+import { applyCommand, asNumber, asRecord, emptyFacts, parseLines, } from './shared.mjs';
+function hasPromptContent(content) {
+    if (typeof content === 'string')
+        return true;
+    if (!Array.isArray(content))
+        return false;
+    return content.some((block) => {
+        const value = asRecord(block);
+        return (value !== undefined && value.type !== 'tool_result' && value.type !== 'advisor_tool_result');
+    });
+}
+export function computeClaude(lines) {
+    const facts = emptyFacts();
+    const seen = new Set();
+    const advisorIds = new Set();
+    for (const group of lines) {
+        for (const record of parseLines(group)) {
+            if (typeof record.uuid === 'string' && (seen.has(record.uuid) || !seen.add(record.uuid)))
+                continue;
+            const subagent = record.isSidechain === true;
+            const message = asRecord(record.message);
+            if (!subagent && record.type === 'user' && record.isCompactSummary === true)
+                facts.compactions++;
+            if (!subagent &&
+                record.type === 'user' &&
+                hasPromptContent(message?.content) &&
+                record.isMeta !== true &&
+                record.isCompactSummary !== true)
+                facts.userPrompts++;
+            if (record.type === 'assistant') {
+                if (!subagent)
+                    facts.assistantResponses++;
+                const usage = asRecord(message?.usage);
+                const totals = subagent ? facts.subagentTokens : facts.tokens;
+                totals.input += asNumber(usage?.input_tokens);
+                totals.output += asNumber(usage?.output_tokens);
+                totals.cacheRead += asNumber(usage?.cache_read_input_tokens);
+                totals.cacheCreation += asNumber(usage?.cache_creation_input_tokens);
+            }
+            const blocks = Array.isArray(message?.content) ? message.content : [];
+            for (const block of blocks) {
+                const value = asRecord(block);
+                if (!value)
+                    continue;
+                if (value.type === 'tool_use' || value.type === 'server_tool_use') {
+                    facts.toolCalls++;
+                    if (subagent)
+                        facts.subagentToolCalls++;
+                    if (value.name === 'advisor' && typeof value.id === 'string')
+                        advisorIds.add(value.id);
+                    if (value.name === 'Bash' || value.name === 'bash') {
+                        const command = asRecord(value.input)?.command;
+                        if (typeof command === 'string')
+                            applyCommand(command, facts);
+                    }
+                }
+                else if ((value.type === 'tool_result' && value.is_error === true) ||
+                    (typeof value.type === 'string' && value.type.endsWith('_tool_result_error')))
+                    facts.failedToolCalls++;
+                else if (value.type === 'advisor_tool_result' && typeof value.tool_use_id === 'string')
+                    advisorIds.add(value.tool_use_id);
+            }
+        }
+    }
+    facts.advisorCalls = advisorIds.size;
+    return facts;
+}

package/dist/retrospective-transcript/codex-segment.d.mts

@@ -0,0 +1,2 @@
+import { type CodexSegment } from './shared.mts';
+export declare function segmentCodex(lines: string[]): CodexSegment | undefined;

package/dist/retrospective-transcript/codex-segment.mjs

@@ -0,0 +1,73 @@
+import { asNumber, asRecord, emptyTokens, parseLines, } from './shared.mjs';
+function hasInheritedParent(sessionMeta) {
+    const payload = asRecord(sessionMeta.payload);
+    return (asRecord(asRecord(payload?.source)?.subagent) !== undefined ||
+        typeof payload?.forked_from_id === 'string' ||
+        typeof payload?.parent_thread_id === 'string' ||
+        (typeof payload?.id === 'string' &&
+            typeof payload.session_id === 'string' &&
+            payload.id.toLowerCase() !== payload.session_id.toLowerCase()));
+}
+function isOwnedTaskStart(record, timestampMs) {
+    if (record.type !== 'event_msg')
+        return false;
+    const payload = asRecord(record.payload);
+    if (payload?.type !== 'task_started' || typeof payload.started_at !== 'number')
+        return false;
+    return payload.started_at >= 1_000_000_000_000
+        ? payload.started_at >= timestampMs
+        : payload.started_at >= Math.floor(timestampMs / 1000);
+}
+function usage(record) {
+    if (record.type !== 'event_msg')
+        return undefined;
+    const payload = asRecord(record.payload);
+    if (payload?.type !== 'token_count')
+        return undefined;
+    const totals = asRecord(asRecord(payload?.info)?.total_token_usage);
+    if (!totals)
+        return undefined;
+    return {
+        input: asNumber(totals.input_tokens),
+        output: asNumber(totals.output_tokens),
+        cacheRead: asNumber(totals.cached_input_tokens),
+        cacheCreation: 0,
+    };
+}
+function retainHighWater(previous, current) {
+    return {
+        input: Math.max(previous.input, current.input),
+        output: Math.max(previous.output, current.output),
+        cacheRead: Math.max(previous.cacheRead, current.cacheRead),
+        cacheCreation: 0,
+    };
+}
+export function segmentCodex(lines) {
+    const content = lines.filter(Boolean);
+    const sessionMeta = parseLines(content.slice(0, 1))[0];
+    if (sessionMeta?.type !== 'session_meta')
+        return { lines: content, baseline: emptyTokens() };
+    if (!hasInheritedParent(sessionMeta))
+        return { lines: content.slice(1), baseline: emptyTokens() };
+    const timestamp = asRecord(sessionMeta.payload)?.timestamp;
+    const timestampMs = typeof timestamp === 'string' ? Date.parse(timestamp) : Number.NaN;
+    if (!Number.isFinite(timestampMs))
+        return undefined;
+    const ownedIndex = content.findIndex((line, index) => {
+        if (index === 0)
+            return false;
+        const record = parseLines([line])[0];
+        return record ? isOwnedTaskStart(record, timestampMs) : false;
+    });
+    if (ownedIndex === -1)
+        return undefined;
+    let baseline;
+    for (const record of parseLines(content.slice(1, ownedIndex))) {
+        const current = usage(record);
+        if (current)
+            baseline = retainHighWater(baseline ?? emptyTokens(), current);
+    }
+    if (!baseline)
+        return undefined;
+    return { lines: content.slice(ownedIndex), baseline };
+}

package/dist/retrospective-transcript/codex.d.mts

@@ -0,0 +1,10 @@
+import { type CodexSegment, type TokenTotals, type TranscriptFacts } from './shared.mts';
+export declare function codexChildren(lines: string[], ownerPath?: string): Array<{
+    threadId: string;
+    agentPath: string;
+}>;
+export declare function codexIdentity(lines: string[]): {
+    threadId?: string;
+    agentPath: string;
+};
+export declare function computeCodex(lines: string[], subagents?: CodexSegment[], baseline?: TokenTotals): TranscriptFacts;

package/dist/retrospective-transcript/codex.mjs

@@ -0,0 +1,170 @@
+import { applyCommand, asNumber, asRecord, emptyFacts, emptyTokens, parseLines, } from './shared.mjs';
+import { customExecCommands } from './javascript-command.mjs';
+function usage(record) {
+    const payload = asRecord(record.payload);
+    const totals = asRecord(asRecord(payload?.info)?.total_token_usage);
+    if (record.type !== 'event_msg' || payload?.type !== 'token_count' || !totals)
+        return undefined;
+    return {
+        input: asNumber(totals.input_tokens),
+        output: asNumber(totals.output_tokens),
+        cacheRead: asNumber(totals.cached_input_tokens),
+        cacheCreation: 0,
+    };
+}
+function commands(payload) {
+    const raw = payload.type === 'function_call' ? payload.arguments : payload.input;
+    if (payload.type === 'local_shell_call') {
+        const input = asRecord(raw);
+        const value = asRecord(input?.action)?.command ?? input?.command;
+        if (typeof value === 'string')
+            return [value];
+        if (!Array.isArray(value))
+            return [];
+        return value.every((item) => typeof item === 'string') ? [value.join(' ')] : [];
+    }
+    const customExec = payload.type === 'custom_tool_call' && payload.name === 'exec';
+    if (!customExec && !['exec_command', 'bash', 'shell', 'Bash'].includes(String(payload.name)))
+        return [];
+    if (typeof raw !== 'string')
+        return [];
+    if (customExec)
+        return customExecCommands(raw);
+    try {
+        const value = asRecord(JSON.parse(raw));
+        const candidate = value?.cmd ?? value?.command;
+        return typeof candidate === 'string' ? [candidate] : [];
+    }
+    catch {
+        return [];
+    }
+}
+function hasFailedOutcome(value) {
+    if (Array.isArray(value))
+        return value.some(hasFailedOutcome);
+    const payload = asRecord(value);
+    if (!payload)
+        return false;
+    if (payload.type === 'input_text' && typeof payload.text === 'string') {
+        try {
+            return hasFailedOutcome(JSON.parse(payload.text));
+        }
+        catch {
+            return false;
+        }
+    }
+    if (payload.status === 'failed' || payload.status === 'error' || payload.is_error === true)
+        return true;
+    if ((typeof payload.exit_code === 'number' && payload.exit_code !== 0) ||
+        (typeof payload.exitCode === 'number' && payload.exitCode !== 0) ||
+        payload.success === false)
+        return true;
+    return [payload.output, payload.result, payload.metadata].some(hasFailedOutcome);
+}
+function isCall(payload) {
+    return (['function_call', 'custom_tool_call'].includes(String(payload.type)) ||
+        (typeof payload.type === 'string' && payload.type.endsWith('_call')));
+}
+function isCallOutcome(payload) {
+    return typeof payload.type === 'string' && payload.type.endsWith('_call_output');
+}
+function addDelta(current, previous, target) {
+    target.input += Math.max(0, current.input - previous.input);
+    target.output += Math.max(0, current.output - previous.output);
+    target.cacheRead += Math.max(0, current.cacheRead - previous.cacheRead);
+    return {
+        input: Math.max(current.input, previous.input),
+        output: Math.max(current.output, previous.output),
+        cacheRead: Math.max(current.cacheRead, previous.cacheRead),
+        cacheCreation: 0,
+    };
+}
+function applyRecords(records, facts, subagent, baseline = emptyTokens()) {
+    let previous = baseline;
+    const calls = new Set();
+    const failed = new Set();
+    let anonymousFailures = 0;
+    let previousCompaction;
+    for (const record of records) {
+        const payload = asRecord(record.payload);
+        if (!subagent && record.type === 'event_msg' && payload?.type === 'user_message')
+            facts.userPrompts++;
+        if (!subagent && record.type === 'event_msg' && payload?.type === 'agent_message')
+            facts.assistantResponses++;
+        const compaction = record.type === 'compacted'
+            ? 'top-level'
+            : record.type === 'event_msg' && payload?.type === 'context_compacted'
+                ? 'context-event'
+                : undefined;
+        if (compaction && previousCompaction !== undefined && previousCompaction !== compaction)
+            previousCompaction = undefined;
+        else if (compaction) {
+            facts.compactions++;
+            previousCompaction = compaction;
+        }
+        else
+            previousCompaction = undefined;
+        const totals = usage(record);
+        if (totals) {
+            previous = addDelta(totals, previous, subagent ? facts.subagentTokens : facts.tokens);
+        }
+        if (record.type !== 'response_item' || !payload)
+            continue;
+        const id = typeof payload.call_id === 'string'
+            ? payload.call_id
+            : typeof payload.id === 'string'
+                ? payload.id
+                : undefined;
+        if (isCall(payload)) {
+            if (!id || !calls.has(id)) {
+                facts.toolCalls++;
+                if (subagent)
+                    facts.subagentToolCalls++;
+                if (id)
+                    calls.add(id);
+                if (payload.name === 'advisor')
+                    facts.advisorCalls++;
+                for (const rawCommand of commands(payload))
+                    applyCommand(rawCommand, facts);
+            }
+        }
+        if ((isCall(payload) || isCallOutcome(payload)) && hasFailedOutcome(payload)) {
+            if (id)
+                failed.add(id);
+            else
+                anonymousFailures++;
+        }
+    }
+    facts.failedToolCalls += [...failed].filter((id) => calls.has(id)).length + anonymousFailures;
+}
+export function codexChildren(lines, ownerPath = '/root') {
+    const direct = new Map();
+    const base = ownerPath.replace(/\/$/, '');
+    for (const record of parseLines(lines)) {
+        const payload = asRecord(record.payload);
+        if (record.type !== 'event_msg' || payload?.type !== 'sub_agent_activity')
+            continue;
+        const threadId = payload.agent_thread_id;
+        const agentPath = payload.agent_path;
+        if (typeof threadId !== 'string' || typeof agentPath !== 'string')
+            continue;
+        const normalized = agentPath.replace(/\/$/, '');
+        if (normalized.startsWith(`${base}/`) && !normalized.slice(base.length + 1).includes('/'))
+            direct.set(threadId, normalized);
+    }
+    return [...direct].map(([threadId, agentPath]) => ({ threadId, agentPath }));
+}
+export function codexIdentity(lines) {
+    const payload = asRecord(parseLines(lines.filter(Boolean).slice(0, 1))[0]?.payload);
+    return {
+        ...(typeof payload?.id === 'string' ? { threadId: payload.id } : {}),
+        agentPath: typeof payload?.agent_path === 'string' ? payload.agent_path : '/root',
+    };
+}
+export function computeCodex(lines, subagents = [], baseline) {
+    const facts = emptyFacts();
+    applyRecords(parseLines(lines), facts, false, baseline);
+    for (const subagent of subagents)
+        applyRecords(parseLines(subagent.lines), facts, true, subagent.baseline);
+    return facts;
+}

package/dist/retrospective-transcript/format.d.mts

@@ -0,0 +1,4 @@
+import type { TranscriptFacts } from './shared.mts';
+export declare function sessionLabel(value: string): string;
+export declare function formatTranscriptFacts(sessionId: string, facts: TranscriptFacts): string;
+export declare const formatUnavailable: (reason: string) => string;

package/dist/retrospective-transcript/format.mjs

@@ -0,0 +1,22 @@
+const LABEL_CHARACTER = /[^A-Za-z0-9._-]+/g;
+export function sessionLabel(value) {
+    return value.replace(/\s+/g, '_').replace(LABEL_CHARACTER, '_').slice(0, 128) || 'transcript';
+}
+export function formatTranscriptFacts(sessionId, facts) {
+    return [
+        '=== Transcript Facts ===',
+        `Session: ${sessionLabel(sessionId)}`,
+        `User prompts: ${facts.userPrompts}`,
+        `Assistant responses: ${facts.assistantResponses}`,
+        `Tool calls: ${facts.toolCalls} (failed: ${facts.failedToolCalls})`,
+        `no-mistakes invocations: ${facts.noMistakesInvocations}`,
+        `advisor calls: ${facts.advisorCalls}`,
+        `Push commands attempted: ${facts.pushCommandAttempts}`,
+        `Compactions: ${facts.compactions}`,
+        `Tokens: input=${facts.tokens.input} output=${facts.tokens.output} cache_read=${facts.tokens.cacheRead} cache_creation=${facts.tokens.cacheCreation}`,
+        `Subagent tool calls: ${facts.subagentToolCalls}`,
+        `Subagent tokens: input=${facts.subagentTokens.input} output=${facts.subagentTokens.output} cache_read=${facts.subagentTokens.cacheRead} cache_creation=${facts.subagentTokens.cacheCreation}`,
+        '',
+    ].join('\n');
+}
+export const formatUnavailable = (reason) => `=== Transcript Facts ===\nStatus: unavailable (${reason.replace(/\s+/g, ' ').slice(0, 240)})\n`;

package/dist/retrospective-transcript/index.d.mts

@@ -0,0 +1,22 @@
+import { type CodexSegment, type TranscriptFacts } from './shared.mts';
+export type { TokenTotals, TranscriptFacts } from './shared.mts';
+export { codexChildren, codexIdentity } from './codex.mts';
+export { formatTranscriptFacts, formatUnavailable } from './format.mts';
+export type ResolveOptions = {
+    sessionId?: string;
+    jsonlPath?: string;
+    projectsDir?: string;
+    codexSessionsDir?: string;
+    grokSessionsDir?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+};
+type TranscriptResolution = {
+    path: string;
+    sessionId: string;
+} | {
+    error: string;
+};
+export declare function resolveTranscriptFile(options: ResolveOptions): TranscriptResolution;
+export declare function computeTranscriptFacts(lines: string[], subagents?: Array<string[] | CodexSegment>): TranscriptFacts;
+export declare function runRetrospectiveTranscript(options: ResolveOptions): Promise<string>;

package/dist/retrospective-transcript/index.mjs

@@ -0,0 +1,157 @@
+import { existsSync, globSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { codexChildren, codexIdentity, computeCodex } from './codex.mjs';
+import { segmentCodex } from './codex-segment.mjs';
+import { computeClaude } from './claude.mjs';
+import { formatTranscriptFacts, formatUnavailable, sessionLabel } from './format.mjs';
+import { emptyFacts, hasMalformedInteriorRecord, parseLines, } from './shared.mjs';
+export { codexChildren, codexIdentity } from './codex.mjs';
+export { formatTranscriptFacts, formatUnavailable } from './format.mjs';
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MALFORMED_INTERIOR = 'malformed interior transcript record';
+function globFrom(root, pattern) {
+    return globSync(pattern, { cwd: root }).map((path) => join(root, path));
+}
+export function resolveTranscriptFile(options) {
+    if (options.sessionId && !SESSION_ID.test(options.sessionId))
+        return { error: 'invalid session id format' };
+    if (options.jsonlPath) {
+        const filename = basename(options.jsonlPath, '.jsonl');
+        const fileSessionId = filename.slice(-36);
+        return {
+            path: options.jsonlPath,
+            sessionId: options.sessionId?.toLowerCase() ??
+                (SESSION_ID.test(fileSessionId) ? fileSessionId.toLowerCase() : sessionLabel(filename)),
+        };
+    }
+    const env = options.env ?? process.env;
+    const sessionId = options.sessionId ??
+        ['CODEX_THREAD_ID', 'CLAUDE_CODE_SESSION_ID', 'CURSOR_SESSION_ID', 'GROK_SESSION_ID']
+            .map((key) => env[key])
+            .find(Boolean);
+    if (!sessionId)
+        return {
+            error: 'no session id (pass --session-id or set CODEX_THREAD_ID, CLAUDE_CODE_SESSION_ID, CURSOR_SESSION_ID, or GROK_SESSION_ID)',
+        };
+    if (!SESSION_ID.test(sessionId))
+        return { error: 'invalid session id format' };
+    const normalizedSessionId = sessionId.toLowerCase();
+    const codex = options.codexSessionsDir ?? join(env.CODEX_HOME || join(homedir(), '.codex'), 'sessions');
+    const claude = options.projectsDir ?? join(env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects');
+    const grokHome = env.GROK_HOME || join(homedir(), '.grok');
+    const grok = options.grokSessionsDir ?? join(grokHome, 'sessions');
+    const encodedCwd = encodeURIComponent(options.cwd ?? process.cwd());
+    const grokExact = join(grok, encodedCwd, normalizedSessionId, 'updates.jsonl');
+    const grokPaths = existsSync(grokExact)
+        ? [grokExact]
+        : globFrom(grok, `*/${normalizedSessionId}/updates.jsonl`);
+    const codexPaths = globFrom(codex, `**/rollout-*-${normalizedSessionId}.jsonl`);
+    const claudePaths = globFrom(claude, `*/${normalizedSessionId}.jsonl`);
+    const paths = [...grokPaths, ...codexPaths, ...claudePaths].sort();
+    if (paths.length > 1)
+        return { error: `multiple transcripts found for session ${normalizedSessionId}` };
+    return paths[0]
+        ? { path: paths[0], sessionId: normalizedSessionId }
+        : { error: `no transcript found for session ${normalizedSessionId}` };
+}
+function schema(lines) {
+    const records = parseLines(lines);
+    const kinds = new Set(records
+        .map((record) => record.type === 'user' || record.type === 'assistant'
+        ? 'claude'
+        : record.type === 'session_meta' ||
+            record.type === 'event_msg' ||
+            record.type === 'response_item' ||
+            record.type === 'compacted'
+            ? 'codex'
+            : undefined)
+        .filter(Boolean));
+    return kinds.size === 1 ? [...kinds][0] : undefined;
+}
+export function computeTranscriptFacts(lines, subagents = []) {
+    const detected = schema(lines);
+    if (!detected)
+        return emptyFacts();
+    if (detected === 'claude')
+        return computeClaude([
+            lines,
+            ...subagents.map((value) => (Array.isArray(value) ? value : value.lines)),
+        ]);
+    if (subagents.some(Array.isArray))
+        throw new TypeError('Codex subagents must be segmented');
+    return computeCodex(lines, subagents);
+}
+async function readLines(path) {
+    return (await readFile(path, 'utf8').catch(() => undefined))?.split('\n');
+}
+function childPath(threadId, sessionsDir) {
+    if (!SESSION_ID.test(threadId))
+        return undefined;
+    const paths = globFrom(sessionsDir, `**/rollout-*-${threadId}.jsonl`).sort();
+    return paths.length === 1 ? paths[0] : undefined;
+}
+function matchesChildIdentity(lines, threadId, agentPath) {
+    const first = parseLines(lines.filter(Boolean).slice(0, 1))[0];
+    if (first?.type !== 'session_meta')
+        return true;
+    const identity = codexIdentity(lines);
+    const threadMatches = identity.threadId?.toLowerCase() === threadId.toLowerCase();
+    return threadMatches && identity.agentPath.replace(/\/$/, '') === agentPath;
+}
+async function codexSubagents(lines, sessionsDir, ownerPath, visited = new Set()) {
+    const result = [];
+    for (const edge of codexChildren(lines, ownerPath)) {
+        if (visited.has(edge.threadId))
+            continue;
+        visited.add(edge.threadId);
+        const path = childPath(edge.threadId, sessionsDir);
+        if (!path || !existsSync(path))
+            return undefined;
+        const child = await readLines(path);
+        if (!child ||
+            schema(child) !== 'codex' ||
+            hasMalformedInteriorRecord(child) ||
+            !matchesChildIdentity(child, edge.threadId, edge.agentPath))
+            return undefined;
+        const segment = segmentCodex(child);
+        if (!segment)
+            return undefined;
+        result.push(segment);
+        const nested = await codexSubagents(segment.lines, sessionsDir, edge.agentPath, visited);
+        if (!nested)
+            return undefined;
+        result.push(...nested);
+    }
+    return result;
+}
+export async function runRetrospectiveTranscript(options) {
+    const resolved = resolveTranscriptFile(options);
+    if ('error' in resolved)
+        return formatUnavailable(resolved.error);
+    const lines = await readLines(resolved.path);
+    if (!lines)
+        return formatUnavailable('could not read transcript');
+    const detected = schema(lines);
+    if (!detected)
+        return formatUnavailable('unsupported or mixed transcript schema');
+    if (hasMalformedInteriorRecord(lines))
+        return formatUnavailable(MALFORMED_INTERIOR);
+    if (detected === 'claude') {
+        const directory = join(dirname(resolved.path), basename(resolved.path, '.jsonl'), 'subagents');
+        const subagents = await Promise.all(globFrom(directory, '*.jsonl').sort().map(readLines));
+        return formatTranscriptFacts(resolved.sessionId, computeTranscriptFacts(lines, subagents.filter((value) => value !== undefined && schema(value) === 'claude' && !hasMalformedInteriorRecord(value))));
+    }
+    const identity = codexIdentity(lines);
+    const root = segmentCodex(lines);
+    if (!root)
+        return formatUnavailable('could not segment Codex transcript');
+    const codexHome = (options.env ?? process.env).CODEX_HOME;
+    const subagents = await codexSubagents(root.lines, options.codexSessionsDir ??
+        (options.jsonlPath ? dirname(resolved.path) : undefined) ??
+        join(codexHome || join(homedir(), '.codex'), 'sessions'), identity.agentPath, new Set([identity.threadId ?? resolved.sessionId].filter((threadId) => SESSION_ID.test(threadId))));
+    if (!subagents)
+        return formatUnavailable('could not resolve a referenced Codex child transcript');
+    return formatTranscriptFacts(resolved.sessionId, computeCodex(root.lines, subagents, root.baseline));
+}

package/dist/retrospective-transcript/javascript-command.d.mts

@@ -0,0 +1 @@
+export declare function customExecCommands(raw: string): string[];