vouchington-tooling 0.1.4 → 0.1.5

package/README.md

@@ -20,6 +20,7 @@ vouchington gha-runtime-audit --pr-workflow CI --push-workflow '/^Main CI \\(.+\
 vouchington gha-output name
 vouchington gha-needs-results
 vouchington download-with-diagnostics <url> <destination>
+vouchington download-optional-run-artifacts --pattern 'coverage-*' --dir ./coverage-fallback
 vouchington host-pressure-diagnostics
 vouchington allocate-browser-safe-ports 2 --policy ./policy.json --forbidden-ports ./ports.json
 vouchington diagnose-port-collision --ports "2200 2216"
@@ -46,6 +47,11 @@ vouchington post-review
 vouchington stage-review-payload optional|required <source> <destination>
 ```
 
+`download-optional-run-artifacts` uses the current Actions run and host. Pattern mode discovers
+non-expired artifacts across the run, keeps the first result for each name (matching `gh run
+download`), and extracts each selected name into its own directory. Ordinary absence is reported as
+`availability=unavailable`; invalid names and cancellation remain hard failures.
+
 `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

package/dist/cli/index.mjs

@@ -26,6 +26,10 @@ const SCRIPT_PATHS = {
         command: 'bash',
         path: 'scripts/gha/download-with-diagnostics.sh',
     },
+    'download-optional-run-artifacts': {
+        command: 'bash',
+        path: 'scripts/gha/download-optional-run-artifacts.sh',
+    },
     'host-pressure-diagnostics': {
         command: 'bash',
         path: 'scripts/gha/host-pressure-diagnostics.sh',

package/dist/cli/parse.d.mts

@@ -44,5 +44,5 @@ export type ParsedCli = {
     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 type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'download-optional-run-artifacts' | '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

@@ -4,6 +4,7 @@ const SCRIPT_COMMANDS = new Set([
     'gha-output',
     'gha-needs-results',
     'download-with-diagnostics',
+    'download-optional-run-artifacts',
     'host-pressure-diagnostics',
     'allocate-browser-safe-ports',
     'diagnose-port-collision',

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  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 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  download-optional-run-artifacts  Download optional artifacts from the current run\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...]\ndownload-optional-run-artifacts (--name <name> | --pattern <pattern>) --dir <directory>\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] [--expected-sha256 SHA256] [--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

@@ -7,6 +7,7 @@ Commands:
   gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record
   gha-needs-results             Fail if required GitHub Actions job results failed
   download-with-diagnostics     Download a URL and report HTTP status on failure
+  download-optional-run-artifacts  Download optional artifacts from the current run
   host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot
   allocate-browser-safe-ports   Allocate Fetch-safe localhost ports
   diagnose-port-collision       Capture bounded localhost port diagnostics
@@ -59,6 +60,7 @@ gha-runtime-audit
 gha-output <name>
 gha-needs-results [label]
 download-with-diagnostics <url> <destination> [-- curl-args...]
+download-optional-run-artifacts (--name <name> | --pattern <pattern>) --dir <directory>
 host-pressure-diagnostics
 allocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]
 diagnose-port-collision [--ports "2200 2216"] [--output-dir PATH]
@@ -72,7 +74,7 @@ check-cache-size <path> <max-bytes> <label>
 make-shard-matrix <total>
 load-runner-env
 clean-workspace
-install-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]
+install-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]
 run-with-timeout <timeout-seconds> <kill-after-seconds> <command...>
 lint-links [--offline] [--config PATH] [--glob PATTERN] [files...]
 materialize-pr-context

package/dist/gha-post-review/post.mjs

@@ -1,4 +1,4 @@
-import { ReviewPayloadError, bodyOnlyReviewFallback, indexReviewFiles, parseReviewPayload, remapReviewComments, } from '../gha-review-payload/index.mjs';
+import { ReviewPayloadError, indexReviewFiles, parseReviewPayload, remapReviewComments, } from '../gha-review-payload/index.mjs';
 export { MAX_REVIEW_COMMENTS as MAX_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES as MAX_PAYLOAD_BYTES, ReviewPayloadError as PostReviewError, } from '../gha-review-payload/index.mjs';
 export function runPostReview(payloadPath, io) {
     try {
@@ -12,14 +12,7 @@ export function runPostReview(payloadPath, io) {
         const first = io.postReview(review);
         if (first.ok)
             return { posted: true };
-        if (first.status !== 422) {
-            throw new ReviewPayloadError(`GitHub review POST failed (HTTP ${first.status}).`);
-        }
-        const retry = io.postReview(bodyOnlyReviewFallback(review, first.status));
-        if (!retry.ok) {
-            throw new ReviewPayloadError(`GitHub review POST retry failed (HTTP ${retry.status}).`);
-        }
-        return { posted: true };
+        throw new ReviewPayloadError(`GitHub review POST failed (HTTP ${first.status}).`);
     }
     finally {
         io.removeFile(payloadPath);

package/dist/gha-review-payload/index.d.mts

@@ -1,4 +1,4 @@
-export { MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, ReviewPayloadError, bodyOnlyReviewFallback, parseReviewPayload, reviewCommentSubject, } from './payload.mts';
+export { MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, ReviewPayloadError, parseReviewPayload, reviewCommentSubject, } from './payload.mts';
 export type { ReviewComment, ReviewSide, SanitizedReview } from './payload.mts';
 export { indexReviewFiles, parsePatchCommentable, parseReviewFilesJson } from './diff.mts';
 export type { CommentableIndex, CommentableLine, LineKind, ReviewFile } from './diff.mts';

package/dist/gha-review-payload/index.mjs

@@ -1,4 +1,4 @@
-export { MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, ReviewPayloadError, bodyOnlyReviewFallback, parseReviewPayload, reviewCommentSubject, } from './payload.mjs';
+export { MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, ReviewPayloadError, parseReviewPayload, reviewCommentSubject, } from './payload.mjs';
 export { indexReviewFiles, parsePatchCommentable, parseReviewFilesJson } from './diff.mjs';
 export { nearestReviewLine, remapReviewComments, rewriteSnappedSuggestion, snapReviewNote, } from './remap.mjs';
 export { readRegularReviewPayload, stageReviewPayload, writeStagedOutput } from './file.mjs';

package/dist/gha-review-payload/payload.d.mts

@@ -23,8 +23,6 @@ export type SanitizedReview = {
 export declare function reviewCommentSubject(comment: ReviewComment): string;
 /**
  * Parses untrusted JSON into the exact review wire shape accepted by the caller's poster.
- * Unknown fields and malformed comments are dropped; the supplied commit id always wins.
+ * Unknown fields are ignored, malformed findings fail closed, and the supplied commit id wins.
  */
 export declare function parseReviewPayload(bytes: Buffer, commitId: string): SanitizedReview;
-/** Builds the body-only fallback used when inline review placement is rejected. */
-export declare function bodyOnlyReviewFallback(review: SanitizedReview, status: number): SanitizedReview;

package/dist/gha-review-payload/payload.mjs

@@ -49,7 +49,7 @@ export function reviewCommentSubject(comment) {
 }
 /**
  * Parses untrusted JSON into the exact review wire shape accepted by the caller's poster.
- * Unknown fields and malformed comments are dropped; the supplied commit id always wins.
+ * Unknown fields are ignored, malformed findings fail closed, and the supplied commit id wins.
  */
 export function parseReviewPayload(bytes, commitId) {
     if (!isCommitId(commitId)) {
@@ -70,42 +70,26 @@ export function parseReviewPayload(bytes, commitId) {
     }
     const record = parsed;
     const body = typeof record.body === 'string' ? record.body : '';
-    const rawComments = Array.isArray(record.comments) ? record.comments : [];
-    const valid = rawComments.flatMap((comment) => {
+    if (record.comments !== undefined && !Array.isArray(record.comments)) {
+        throw new ReviewPayloadError('comments must be an array when provided.');
+    }
+    const rawComments = record.comments ?? [];
+    if (rawComments.length > MAX_REVIEW_COMMENTS) {
+        throw new ReviewPayloadError(`Payload has more than ${MAX_REVIEW_COMMENTS} inline comments.`);
+    }
+    const comments = rawComments.map((comment) => {
         const sanitized = sanitizeComment(comment);
-        return sanitized ? [sanitized] : [];
+        if (!sanitized)
+            throw new ReviewPayloadError('Every finding must be a valid inline comment.');
+        return sanitized;
     });
-    const kept = valid.slice(0, MAX_REVIEW_COMMENTS);
-    const overflow = valid.slice(MAX_REVIEW_COMMENTS);
-    const parts = [body];
-    if (overflow.length > 0) {
-        parts.push(`## Comments over the ${MAX_REVIEW_COMMENTS}-comment cap`, ...overflow.map((comment) => `- ${reviewCommentSubject(comment)}`));
-    }
-    const reviewBody = parts.filter((part) => part.length > 0).join('\n\n');
-    if (reviewBody.length === 0 && kept.length === 0) {
+    if (body.length === 0 && comments.length === 0) {
         throw new ReviewPayloadError('Payload has no review body and no valid comments.');
     }
     return {
         event: 'COMMENT',
         commit_id: commitId,
-        body: reviewBody.length > 0 ? reviewBody : 'Inline findings only.',
-        comments: kept,
-    };
-}
-/** Builds the body-only fallback used when inline review placement is rejected. */
-export function bodyOnlyReviewFallback(review, status) {
-    const listed = review.comments.length === 0
-        ? []
-        : [
-            '## Inline findings not posted',
-            `The inline comments were rejected (HTTP ${status}). The findings were:`,
-            ...review.comments.map((comment) => `- ${reviewCommentSubject(comment)}`),
-        ];
-    const body = [review.body, ...listed].filter((part) => part.length > 0).join('\n\n');
-    return {
-        event: 'COMMENT',
-        commit_id: review.commit_id,
-        body: body.length > 0 ? body : `Inline findings not posted (HTTP ${status}).`,
-        comments: [],
+        body: body.length > 0 ? body : 'Inline findings only.',
+        comments,
     };
 }

package/dist/gha-review-payload/remap.d.mts

@@ -9,5 +9,5 @@ export declare function nearestReviewLine(candidates: Array<{
     line: number;
     kind: LineKind;
 } | undefined;
-/** Places comments on commentable diff lines, remapping renames and recording dropped findings. */
+/** Places every finding on a commentable diff line and fails if any finding cannot be placed. */
 export declare function remapReviewComments(review: SanitizedReview, index: CommentableIndex): SanitizedReview;

package/dist/gha-review-payload/remap.mjs

@@ -1,4 +1,4 @@
-import { reviewCommentSubject } from './payload.mjs';
+import { ReviewPayloadError } from './payload.mjs';
 export function snapReviewNote(path, line) {
     return `_Regarding \`${path}:${line}\` (not in the diff hunk; posted on the nearest commentable line)._`;
 }
@@ -62,28 +62,19 @@ function placeComment(comment, index) {
         return withSnap({ ...target, side: alt, line: nearAlt.line }, originalPath, originalLine);
     return null;
 }
-/** Places comments on commentable diff lines, remapping renames and recording dropped findings. */
+/** Places every finding on a commentable diff line and fails if any finding cannot be placed. */
 export function remapReviewComments(review, index) {
     const kept = [];
-    const dropped = [];
     for (const comment of review.comments) {
         const placed = placeComment(comment, index);
-        if (placed)
-            kept.push(placed);
-        else
-            dropped.push(comment);
+        if (!placed) {
+            throw new ReviewPayloadError(`Inline finding cannot be placed on the pull request diff: ${comment.path}:${comment.line}.`);
+        }
+        kept.push(placed);
     }
-    const extras = dropped.length === 0
-        ? []
-        : [
-            '## Inline findings not posted',
-            'These comments could not be placed on a diff hunk:',
-            ...dropped.map((comment) => `- ${reviewCommentSubject(comment)}`),
-        ];
-    const body = [review.body, ...extras].filter((part) => part.length > 0).join('\n\n');
     return {
         ...review,
-        body: body.length > 0 ? body : 'Inline findings only.',
+        body: review.body.length > 0 ? review.body : 'Inline findings only.',
         comments: kept,
     };
 }

package/dist/index.d.mts

@@ -35,7 +35,7 @@ export { MissingResponseBodyError, readResponseBody, readResponseBodyAsBuffer, R
 export type { ReadResponseBodyOptions } from './http-body/index.mts';
 export { parseAstGrepRuleArgs, runAstGrepRule } from './ast-grep-rule/index.mts';
 export type { AstGrepRuleInvocation, RunAstGrepRuleOptions } from './ast-grep-rule/index.mts';
-export { bodyOnlyReviewFallback, indexReviewFiles, MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, nearestReviewLine, parsePatchCommentable, parseReviewFilesJson, parseReviewPayload, readRegularReviewPayload, remapReviewComments, ReviewPayloadError, reviewCommentSubject, rewriteSnappedSuggestion, snapReviewNote, stageReviewPayload, writeStagedOutput, } from './gha-review-payload/index.mts';
+export { indexReviewFiles, MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, nearestReviewLine, parsePatchCommentable, parseReviewFilesJson, parseReviewPayload, readRegularReviewPayload, remapReviewComments, ReviewPayloadError, reviewCommentSubject, rewriteSnappedSuggestion, snapReviewNote, stageReviewPayload, writeStagedOutput, } from './gha-review-payload/index.mts';
 export type { CommentableIndex, CommentableLine, LineKind, PayloadRequirement, ReviewComment, ReviewFile, ReviewSide, SanitizedReview, } from './gha-review-payload/index.mts';
 export { CLAUDE_OIDC_AUDIENCE, createActionsClaudeTokenIo, mintClaudeAppToken, PostReviewError, requireEnv, resolveReviewPostToken, revokeClaudeAppToken, runPostReview, runPostReviewCli, withClaudeAppToken, } from './gha-post-review/index.mts';
 export type { ClaudeTokenIo, PostResult, PostReviewIo, PullFile, ReviewPostToken, } from './gha-post-review/index.mts';

package/dist/index.mjs

@@ -20,7 +20,7 @@ export { decide, deriveRetryAttempt } from './transient-retry/index.mjs';
 export { escapeSpreadsheetFormula, parseCsvRows, streamCsvRows, stripCsvBom } from './csv/index.mjs';
 export { MissingResponseBodyError, readResponseBody, readResponseBodyAsBuffer, ResponseBodyTooLargeError, } from './http-body/index.mjs';
 export { parseAstGrepRuleArgs, runAstGrepRule } from './ast-grep-rule/index.mjs';
-export { bodyOnlyReviewFallback, indexReviewFiles, MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, nearestReviewLine, parsePatchCommentable, parseReviewFilesJson, parseReviewPayload, readRegularReviewPayload, remapReviewComments, ReviewPayloadError, reviewCommentSubject, rewriteSnappedSuggestion, snapReviewNote, stageReviewPayload, writeStagedOutput, } from './gha-review-payload/index.mjs';
+export { indexReviewFiles, MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, nearestReviewLine, parsePatchCommentable, parseReviewFilesJson, parseReviewPayload, readRegularReviewPayload, remapReviewComments, ReviewPayloadError, reviewCommentSubject, rewriteSnappedSuggestion, snapReviewNote, stageReviewPayload, writeStagedOutput, } from './gha-review-payload/index.mjs';
 export { CLAUDE_OIDC_AUDIENCE, createActionsClaudeTokenIo, mintClaudeAppToken, PostReviewError, requireEnv, resolveReviewPostToken, revokeClaudeAppToken, runPostReview, runPostReviewCli, withClaudeAppToken, } from './gha-post-review/index.mjs';
 export { nextPageCursorFromLinkHeader, nextPageUrlFromLinkHeader, validatePaginationRequestUrl, } from './http-link-pagination/index.mjs';
 export { cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, mintPresignedControl, transportObjectKeys, } from './coverage-transport/index.mjs';

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

@@ -0,0 +1,8 @@
+import { type ParsedLine } from './shared.mts';
+export declare class CodexMessageCounter {
+    private previous;
+    private userPrompts;
+    private assistantResponses;
+    add(record: ParsedLine, payload: ParsedLine | undefined): void;
+    totals(): [number, number];
+}

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

@@ -0,0 +1,66 @@
+import { asRecord } from './shared.mjs';
+function isInjectedBlock(raw) {
+    const text = raw.trim();
+    // Hosted metadata occupies complete input blocks; inner fields can vary by runtime version.
+    const agents = /^# AGENTS\.md instructions for [^\r\n]+(?:\r?\n)+<INSTRUCTIONS(?:\s[^>]*)?>[\s\S]*<\/INSTRUCTIONS>$/.test(text);
+    const environment = /^<environment_context(?:\s[^>]*)?>[\s\S]*<\/environment_context>$/.test(text);
+    const skill = /^<skill(?:\s[^>]*)?>[\s\S]*<\/skill>$/.test(text);
+    return agents || environment || skill;
+}
+function isInjectedUser(payload) {
+    if (!Array.isArray(payload.content) || payload.content.length === 0)
+        return false;
+    return payload.content.map(asRecord).every((item) => {
+        return (item?.type === 'input_text' && typeof item.text === 'string' && isInjectedBlock(item.text));
+    });
+}
+function message(record, payload) {
+    if (record.type === 'response_item' && payload?.type === 'message') {
+        if (payload.role === 'user' || payload.role === 'assistant')
+            return { role: payload.role, schema: 'current' };
+    }
+    else if (record.type === 'event_msg') {
+        if (payload?.type === 'user_message')
+            return { role: 'user', schema: 'legacy' };
+        if (payload?.type === 'agent_message')
+            return { role: 'assistant', schema: 'legacy' };
+    }
+    return undefined;
+}
+function isDuplicate(previous, current) {
+    // Hosted rollouts currently emit user as current→legacy and assistant as legacy→current;
+    // keep directional to avoid merging inverse-order distinct turns (see pairing tests).
+    return ((current.role === 'user' && previous?.schema === 'current' && current.schema === 'legacy') ||
+        (current.role === 'assistant' && previous?.schema === 'legacy' && current.schema === 'current'));
+}
+export class CodexMessageCounter {
+    previous;
+    userPrompts = 0;
+    assistantResponses = 0;
+    add(record, payload) {
+        const current = message(record, payload);
+        const injected = current?.schema === 'current' &&
+            current.role === 'user' &&
+            payload !== undefined &&
+            isInjectedUser(payload);
+        if (!current) {
+            this.previous = undefined;
+            return;
+        }
+        // Injected records are transparent because hosted metadata can split a duplicate pair.
+        if (injected)
+            return;
+        if (this.previous?.role === current.role && isDuplicate(this.previous, current)) {
+            this.previous = undefined;
+            return;
+        }
+        if (current.role === 'user')
+            this.userPrompts++;
+        else
+            this.assistantResponses++;
+        this.previous = current;
+    }
+    totals() {
+        return [this.userPrompts, this.assistantResponses];
+    }
+}

package/dist/retrospective-transcript/codex.mjs

@@ -1,4 +1,5 @@
 import { applyCommand, asNumber, asRecord, emptyFacts, emptyTokens, parseLines, } from './shared.mjs';
+import { CodexMessageCounter } from './codex-messages.mjs';
 import { customExecCommands } from './javascript-command.mjs';
 function usage(record) {
     const payload = asRecord(record.payload);
@@ -83,14 +84,13 @@ function applyRecords(records, facts, subagent, baseline = emptyTokens()) {
     let previous = baseline;
     const calls = new Set();
     const failed = new Set();
+    const messages = new CodexMessageCounter();
     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++;
+        if (!subagent)
+            messages.add(record, payload);
         const compaction = record.type === 'compacted'
             ? 'top-level'
             : record.type === 'event_msg' && payload?.type === 'context_compacted'
@@ -135,6 +135,11 @@ function applyRecords(records, facts, subagent, baseline = emptyTokens()) {
                 anonymousFailures++;
         }
     }
+    if (!subagent) {
+        const [userPrompts, assistantResponses] = messages.totals();
+        facts.userPrompts += userPrompts;
+        facts.assistantResponses += assistantResponses;
+    }
     facts.failedToolCalls += [...failed].filter((id) => calls.has(id)).length + anonymousFailures;
 }
 export function codexChildren(lines, ownerPath = '/root') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -223,7 +223,7 @@
   },
   "dependencies": {
     "csv-parse": "7.0.2",
-    "csv-stringify": "6.8.2",
+    "csv-stringify": "6.8.3",
     "dockerfile-ast": "0.7.1",
     "picomatch": "4.0.5",
     "yaml": "2.9.0"

package/scripts/gha/download-optional-run-artifacts.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  echo 'usage: download-optional-run-artifacts.sh (--name <name> | --pattern <pattern>) --dir <directory>' >&2
+  exit 2
+}
+
+selector=''
+selector_type=''
+destination=''
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --name|--pattern)
+      [ -z "$selector_type" ] && [ "$#" -ge 2 ] || usage
+      selector_type="${1#--}"
+      selector="$2"
+      shift 2
+      ;;
+    --dir)
+      [ -z "$destination" ] && [ "$#" -ge 2 ] || usage
+      destination="$2"
+      shift 2
+      ;;
+    *) usage ;;
+  esac
+done
+
+[ -n "$selector_type" ] && [ -n "$selector" ] && [ -n "$destination" ] || usage
+[ -n "${GITHUB_OUTPUT:-}" ] || { echo 'GITHUB_OUTPUT must be set' >&2; exit 2; }
+[ -n "${GITHUB_REPOSITORY:-}" ] || { echo 'GITHUB_REPOSITORY must be set' >&2; exit 2; }
+[ -n "${GITHUB_RUN_ID:-}" ] || { echo 'GITHUB_RUN_ID must be set' >&2; exit 2; }
+github_host="${GH_HOST:-${GITHUB_SERVER_URL:-https://github.com}}"
+github_host="${github_host#*://}"
+github_host="${github_host%%/*}"
+[ -n "$github_host" ] || { echo 'GitHub host must be set' >&2; exit 2; }
+repository="$GITHUB_REPOSITORY"
+case "$github_host" in
+  github.com|*.ghe.com) ;;
+  *)
+    if [ -z "${GH_ENTERPRISE_TOKEN:-${GITHUB_ENTERPRISE_TOKEN:-}}" ]; then
+      enterprise_token="${GH_TOKEN:-${GITHUB_TOKEN:-}}"
+      [ -z "$enterprise_token" ] || export GH_ENTERPRISE_TOKEN="$enterprise_token"
+    fi
+    ;;
+esac
+
+validate_artifact_name() {
+  case "$1" in
+    ''|.|..|*/*|*\\*)
+      echo '[optional-run-artifacts] invalid artifact name' >&2
+      return 2
+      ;;
+  esac
+}
+
+download_exact() {
+  artifact="$1"
+  directory="$2"
+  validate_artifact_name "$artifact" || return $?
+  artifacts=$(list_artifact_names) || return $?
+  found=0
+  while IFS= read -r candidate; do
+    if [ "$candidate" = "$artifact" ]; then
+      found=1
+      break
+    fi
+  done < <(printf '%s\n' "$artifacts")
+  [ "$found" -eq 1 ] || return 3
+  echo "[optional-run-artifacts] attempt selector=$selector_type" >&2
+  GH_HOST="$github_host" gh run download "$GITHUB_RUN_ID" --repo "$repository" --name "$artifact" --dir "$directory"
+}
+
+list_artifact_names() {
+  GH_HOST="$github_host" gh api \
+    --paginate \
+    "repos/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID/artifacts?per_page=100" \
+    --jq '.artifacts[] | select(.expired | not) | .name'
+}
+
+download_pattern() {
+  artifacts=$(list_artifact_names | awk '!seen[$0]++') || return $?
+  selected_artifacts=()
+  while IFS= read -r artifact; do
+    [ -n "$artifact" ] || continue
+    # shellcheck disable=SC2254
+    # selector is the caller's intended glob pattern.
+    case "$artifact" in
+      $selector) ;;
+      *) continue ;;
+    esac
+    validate_artifact_name "$artifact" || return $?
+    selected_artifacts+=("$artifact")
+    echo "[optional-run-artifacts] selected artifact=$artifact" >&2
+  done < <(printf '%s\n' "$artifacts")
+  count=${#selected_artifacts[@]}
+  echo "[optional-run-artifacts] selection selector=pattern count=$count" >&2
+  [ "$count" -gt 0 ] || return 3
+  for artifact in "${selected_artifacts[@]}"; do
+    echo "[optional-run-artifacts] attempt artifact=$artifact" >&2
+    GH_HOST="$github_host" gh run download "$GITHUB_RUN_ID" --repo "$repository" --name "$artifact" --dir "$destination/$artifact" || return $?
+  done
+}
+
+if [ "$selector_type" = name ]; then
+  if download_exact "$selector" "$destination"; then status=0; else status=$?; fi
+else
+  if download_pattern; then status=0; else status=$?; fi
+fi
+if [ "$status" -eq 0 ]; then
+  echo 'availability=available' >> "$GITHUB_OUTPUT"
+  echo "[optional-run-artifacts] result=available selector=$selector_type" >&2
+else
+  case "$status" in
+    130|143) exit "$status" ;;
+    3)
+      echo 'availability=unavailable' >> "$GITHUB_OUTPUT"
+      echo "::warning::Optional same-run artifact unavailable; continuing with validated fallback (selector=$selector_type exit=$status)" >&2
+      echo "[optional-run-artifacts] result=unavailable selector=$selector_type exit=$status" >&2
+      ;;
+    *)
+      echo "[optional-run-artifacts] result=error selector=$selector_type exit=$status" >&2
+      exit "$status"
+      ;;
+  esac
+fi

package/scripts/gha/install-github-release.sh

@@ -2,7 +2,7 @@
 set -euo pipefail
 
 usage() {
-  echo "usage: install-github-release.sh --repo owner/name --version VERSION --asset TEMPLATE --bin NAME [--tag-prefix PREFIX] [--strip-components N] [--bin-dir DIR] [--version-flag FLAG] [--checksums-asset NAME] [--no-checksum]" >&2
+  echo "usage: install-github-release.sh --repo owner/name --version VERSION --asset TEMPLATE --bin NAME [--tag-prefix PREFIX] [--strip-components N] [--bin-dir DIR] [--version-flag FLAG] [--checksums-asset NAME] [--expected-sha256 SHA256] [--no-checksum]" >&2
 }
 
 REPO="${REPO:-}"
@@ -14,6 +14,7 @@ STRIP_COMPONENTS="${STRIP_COMPONENTS:-1}"
 BIN_DIR="${INSTALL_BIN_DIR:-}"
 VERSION_FLAG="${VERSION_FLAG:---version}"
 CHECKSUMS_ASSET="${CHECKSUMS_ASSET:-}"
+EXPECTED_SHA256="${EXPECTED_SHA256:-}"
 NO_CHECKSUM="${NO_CHECKSUM:-0}"
 
 if [ -n "${RELEASE_OWNER:-}" ] && [ -n "${RELEASE_REPO:-}" ]; then
@@ -67,6 +68,11 @@ while [ "${#}" -gt 0 ]; do
       CHECKSUMS_ASSET="$2"
       shift 2
       ;;
+    --expected-sha256)
+      [ "${#}" -ge 2 ] || { usage; exit 2; }
+      EXPECTED_SHA256="$2"
+      shift 2
+      ;;
     --no-checksum)
       NO_CHECKSUM=1
       shift
@@ -97,6 +103,11 @@ if ! [[ "$STRIP_COMPONENTS" =~ ^[0-9]+$ ]]; then
   exit 2
 fi
 
+if [ -n "$EXPECTED_SHA256" ] && ! [[ "$EXPECTED_SHA256" =~ ^[[:xdigit:]]{64}$ ]]; then
+  echo "install-github-release.sh: --expected-sha256 must be a 64-character hexadecimal SHA-256 digest" >&2
+  exit 2
+fi
+
 BIN_DIR="${BIN_DIR:-${RUNNER_TEMP:-${HOME}/.local}/bin}"
 mkdir -p "$BIN_DIR"
 if [ -n "${GITHUB_PATH:-}" ]; then
@@ -150,10 +161,12 @@ extract_dir="${work}-extract"
 rm -rf "$extract_dir"
 mkdir -p "$extract_dir"
 curl -fsSL -o "$archive" "${base_url}/${asset_name}"
-if [ "$NO_CHECKSUM" != 1 ]; then
-  if [ -n "$checksums_name" ]; then
+if [ -n "$EXPECTED_SHA256" ] || [ "$NO_CHECKSUM" != 1 ]; then
+  if [ -n "$EXPECTED_SHA256" ]; then
+    expected="$EXPECTED_SHA256"
+  elif [ -n "$checksums_name" ]; then
     curl -fsSL -o "${archive}.checksums" "${base_url}/${checksums_name}"
-    expected=$(grep -F "$asset_name" "${archive}.checksums" | awk '{print $1}')
+    expected=$(awk -v file="$asset_name" '$2 == file || $2 == "*" file { print $1 }' "${archive}.checksums")
     rm "${archive}.checksums"
   else
     curl -fsSL -o "${archive}.sha256" "${base_url}/${asset_name}.sha256"