vouchington-tooling 0.18.0 → 0.19.0

package/README.md

@@ -10,7 +10,7 @@ npm install @libpg-query/parser
 # (classic compiler API; typescript@7's package root is version-only)
 npm install @typescript/typescript6
 # optional, only for vouchington-tooling/agent-blackboard and agent-blackboard CLI commands
-npm install agent-blackboard@^0.5.0
+npm install agent-blackboard@^0.6.0
 ```
 
 ## CLI
@@ -34,6 +34,7 @@ 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 download-optional-run-artifacts --name coverage-tooling --name coverage-web --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"
@@ -57,7 +58,7 @@ vouchington wait-for-apt-locks
 vouchington retrospective-transcript --jsonl /path/to/transcript.jsonl
 vouchington retrospective-facts --pr 49 --repo vouchington/vouchington-infra --raw
 vouchington agent-blackboard probe
-vouchington agent-blackboard journal append --session-id <uuid> --agent codex --version 1 --file note.md
+vouchington agent-blackboard journal append --session-id <uuid> --agent codex --version 1 --file note.md --repository vouchington/vouchington-tooling
 vouchington agent-blackboard journal entries --session-id <uuid>
 vouchington agent-blackboard snapshot partition --snapshot <snapshot.jsonl> --checksum <sha256> --counts <counts.json>
 vouchington agent-blackboard snapshot cleanup --snapshot <snapshot.jsonl> --partition-directory <partitions-dir> --receipt <receipt-json>
@@ -91,6 +92,17 @@ download`), and extracts each selected name into its own directory. Ordinary abs
 `availability=unavailable`. Artifact listing retries up to three times with bounded backoff;
 exhausted transport errors, invalid names, and cancellation remain hard failures.
 
+Name mode takes one or more `--name <artifact>` flags (mutually exclusive with `--pattern`), lists
+the run's artifacts once, and extracts every requested name that is present into `<dir>/<name>`.
+Names are matched literally, in request order, with repeats downloaded once; empty names, `.`, `..`,
+and names containing `/`, `\`, or a line break are rejected before anything is listed. Requested
+names absent from the run are skipped with a single bounded `::warning::` (the absent count, the
+first three names, then `and N more`) and never one line per name. `availability=available` means at
+least one requested artifact was downloaded; `availability=unavailable` (exit 0) means none was
+present. A present artifact whose download fails is a hard failure: the helper stops at the first
+one, prints `download failed artifact=<name> exit=<n>`, exits non-zero (a downloader exit of 3 is
+reported as 1 so it cannot be mistaken for absence), and writes no `availability` output.
+
 `require-up-to-date` fetches the requested remote branch and fails unless its fetched tip is an
 ancestor of `HEAD`. `gitleaks-directory-scan` builds and scans isolated staged-index and current
 nonignored-working-tree mirrors with an explicit config; `--directory` selects the repository root.
@@ -125,7 +137,10 @@ GitHub reports a merged PR whose `baseRefName` is `main`; a merged PR into anoth
 as not merged to main, and a missing base is unavailable.
 
 Agent Blackboard support is optional: only the `agent-blackboard` subpath and its CLI commands
-need `agent-blackboard@^0.5.0`. Snapshot cleanup accepts only package-generated temporary paths.
+need `agent-blackboard@^0.6.0`. Snapshot cleanup accepts only package-generated temporary paths.
+`appendJournal` requires a `repositories: string[]` argument. The CLI accepts one or more
+`--repository owner/name` flags; it records the entry's exact repositories and updates the session's
+cumulative repository list before appending.
 Programmatic callers launched from a different workspace directory pass their own module URL as
 `dependencies: { resolveFrom: import.meta.url }`; the CLI defaults to the current package context.
 It captures a target under a private tombstone, validates partition names, permissions, JSONL,

package/dist/agent-blackboard/index.d.mts

@@ -10,7 +10,12 @@ export type BlackboardClientModule = {
     Sessions: new (connection: BlackboardConnection) => {
         ensure(input: unknown): Promise<{
             status: 'created' | 'exists';
+            session: {
+                data: Record<string, unknown>;
+                archivedAt?: string | null;
+            };
         }>;
+        patch(input: unknown): Promise<unknown>;
         list(input: unknown): Promise<unknown>;
         get(id: string): Promise<unknown>;
     };
@@ -32,6 +37,7 @@ export declare function appendJournal(input: {
     sessionId: string;
     agent: string;
     version: string;
+    repositories: string[];
     markdownFile: string;
     parentSessionId?: string | null;
     timestamp?: string;

package/dist/agent-blackboard/index.mjs

@@ -30,6 +30,7 @@ export async function appendJournal(input) {
     assertSessionId(input.sessionId);
     if (input.parentSessionId != null)
         assertSessionId(input.parentSessionId, 'parent session id');
+    const repositories = normalizeRepositories(input.repositories, true);
     const timestamp = input.timestamp === undefined ? new Date() : new Date(input.timestamp);
     if (Number.isNaN(timestamp.valueOf()))
         throw new Error('journal timestamp is not a valid date-time');
@@ -44,18 +45,42 @@ export async function appendJournal(input) {
         throw new Error(`note file is empty: ${input.markdownFile}`);
     const connection = resolveBlackboardConnection(input.env);
     const { Sessions, Entries } = await loadClient(input.dependencies);
-    await new Sessions(connection).ensure({
+    const sessions = new Sessions(connection);
+    const ensured = await sessions.ensure({
         id: input.sessionId,
         parentSessionId: input.parentSessionId ?? null,
         agent: input.agent,
         version: input.version,
     });
+    if (ensured.session.archivedAt != null)
+        throw new Error(`session is archived; create a new session: ${input.sessionId}`);
+    const current = ensured.session.data.repositories;
+    const cumulative = normalizeRepositories(current, false);
+    const merged = [...new Set([...cumulative, ...repositories])].sort();
+    if (JSON.stringify(current) !== JSON.stringify(merged))
+        await sessions.patch({ sessionId: input.sessionId, data: { repositories: merged } });
     const entry = await new Entries(connection).append({
         sessionId: input.sessionId,
-        data: { type: 'journal', markdown, timestamp: timestamp.toISOString() },
+        data: { type: 'journal', markdown, timestamp: timestamp.toISOString(), repositories },
     });
     return `Journaled to agent-blackboard session ${input.sessionId} (entry created at ${entry.createdAt}).`;
 }
+function normalizeRepositories(value, required) {
+    if (value === undefined && !required)
+        return [];
+    if (!Array.isArray(value) || (required && value.length === 0))
+        throw new Error('repositories must be a non-empty array of owner/name strings');
+    const repositories = [];
+    for (const candidate of value) {
+        if (typeof candidate !== 'string')
+            throw new Error('repositories must be a non-empty array of owner/name strings');
+        const repository = candidate.trim().toLowerCase();
+        if (!/^[a-z0-9-]+\/[a-z0-9._-]+$/.test(repository))
+            throw new Error(`invalid repository: ${candidate}`);
+        repositories.push(repository);
+    }
+    return [...new Set(repositories)].sort();
+}
 export async function readJournal(sessionId, env, dependencies) {
     assertSessionId(sessionId);
     const { Entries } = await loadClient(dependencies);

package/dist/agent-blackboard/snapshot-partition-format.mjs

@@ -21,6 +21,11 @@ function isSelection(value) {
         return false;
     if (value.data !== undefined && !isObject(value.data))
         return false;
+    if (value.dataArrayContains !== undefined &&
+        (!isObject(value.dataArrayContains) ||
+            Object.keys(value.dataArrayContains).length === 0 ||
+            Object.entries(value.dataArrayContains).some(([key, member]) => key.length === 0 || typeof member !== 'string' || member.length === 0)))
+        return false;
     return (value.inactiveForHours === undefined ||
         (typeof value.inactiveForHours === 'number' &&
             Number.isFinite(value.inactiveForHours) &&

package/dist/agent-blackboard/snapshot-types.d.mts

@@ -3,6 +3,7 @@ export type SnapshotSelection = {
     version?: string;
     parentSessionId?: string | null;
     data?: Record<string, unknown>;
+    dataArrayContains?: Record<string, string>;
     inactiveForHours?: number;
 };
 export type SnapshotCounts = {

package/dist/cli/commands/agent-blackboard.mjs

@@ -51,7 +51,8 @@ async function runSnapshot(args) {
 }
 async function runJournal(args) {
     const [action, ...flags] = args;
-    const values = flagsToValues(flags);
+    const { repositories, remaining } = action === 'append' ? extractRepositories(flags) : { repositories: [], remaining: flags };
+    const values = flagsToValues(remaining);
     if (action === 'entries') {
         assertAllowed(values, ['session-id']);
         const sessionId = required(values, 'session-id');
@@ -76,11 +77,31 @@ async function runJournal(args) {
             'parent-session-id',
             'timestamp',
         ]);
-        process.stdout.write(`${await appendJournal({ sessionId: required(values, 'session-id'), agent: required(values, 'agent'), version: values.version ?? 'unknown', markdownFile: required(values, 'file'), ...(values['parent-session-id'] ? { parentSessionId: values['parent-session-id'] } : {}), ...('timestamp' in values ? { timestamp: values.timestamp } : {}) })}\n`);
+        process.stdout.write(`${await appendJournal({ sessionId: required(values, 'session-id'), agent: required(values, 'agent'), version: values.version ?? 'unknown', repositories: requiredRepositories(repositories), markdownFile: required(values, 'file'), ...(values['parent-session-id'] ? { parentSessionId: values['parent-session-id'] } : {}), ...('timestamp' in values ? { timestamp: values.timestamp } : {}) })}\n`);
         return 0;
     }
     throw new Error('usage: agent-blackboard journal append|entries');
 }
+function extractRepositories(flags) {
+    const repositories = [];
+    const remaining = [];
+    for (let index = 0; index < flags.length; index += 2) {
+        const flag = flags[index];
+        const value = flags[index + 1];
+        if (!flag?.startsWith('--') || value === undefined)
+            throw new Error(`invalid option: ${flag ?? ''}`);
+        if (flag === '--repository')
+            repositories.push(value);
+        else
+            remaining.push(flag, value);
+    }
+    return { repositories, remaining };
+}
+function requiredRepositories(repositories) {
+    if (repositories.length === 0)
+        throw new Error('--repository is required');
+    return repositories;
+}
 function flagsToValues(flags) {
     const values = {};
     for (let index = 0; index < flags.length; index += 2) {

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  agent-harness-config          Apply classifier-auto + sandbox keys to agent harnesses\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\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  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\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  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\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  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\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\nagent-harness-config dump\nagent-harness-config check|apply [--global] [--repo PATH]... [--harness claude|codex|grok|cursor]...\n  [--home PATH]\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\nrequire-up-to-date --remote <name> --branch <name>\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\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]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-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>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\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]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --session-id UUID --agent NAME --version VERSION --file PATH [--parent-session-id UUID] [--timestamp ISO8601]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\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  agent-harness-config          Apply classifier-auto + sandbox keys to agent harnesses\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\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  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\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  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\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  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\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\nagent-harness-config dump\nagent-harness-config check|apply [--global] [--repo PATH]... [--harness claude|codex|grok|cursor]...\n  [--home PATH]\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\nrequire-up-to-date --remote <name> --branch <name>\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\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]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-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>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\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]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

@@ -83,7 +83,7 @@ gha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--
 gha-output <name>
 gha-needs-results [label]
 download-with-diagnostics <url> <destination> [-- curl-args...]
-download-optional-run-artifacts (--name <name> | --pattern <pattern>) --dir <directory>
+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]
@@ -116,7 +116,7 @@ retrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH]
 link-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill
 retrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]
 agent-blackboard probe
-agent-blackboard journal append --session-id UUID --agent NAME --version VERSION --file PATH [--parent-session-id UUID] [--timestamp ISO8601]
+agent-blackboard journal append --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601]
 agent-blackboard journal entries --session-id UUID
 agent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{"sessions":N,"entries":N,"records":N,"bytes":N}'
 agent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]

package/dist/gha-download-optional-run-artifacts.test-helpers.d.mts

@@ -0,0 +1,17 @@
+export type RunOptions = {
+    readonly args?: readonly string[] | ((temporaryDirectory: string) => readonly string[]);
+    readonly env?: Readonly<Record<string, string>>;
+    readonly ghScript?: string;
+    readonly sleepScript?: string;
+};
+export declare function runHelper(options?: RunOptions): {
+    output: string;
+    temporaryDirectory: string;
+    pid: number;
+    stdout: string;
+    stderr: string;
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    error?: Error;
+};
+export declare function cleanupTemporaryDirectories(): void;

package/dist/gha-download-optional-run-artifacts.test-helpers.mjs

@@ -0,0 +1,50 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, join, resolve } from 'node:path';
+const script = resolve('packages/vouchington-tooling/scripts/gha/download-optional-run-artifacts.sh');
+const temporaryDirectories = [];
+export function runHelper(options = {}) {
+    const temporaryDirectory = mkdtempSync(join(tmpdir(), 'download-optional-run-artifacts-'));
+    temporaryDirectories.push(temporaryDirectory);
+    const binDirectory = join(temporaryDirectory, 'bin');
+    const githubOutput = join(temporaryDirectory, 'github-output');
+    const ghPath = join(binDirectory, 'gh');
+    mkdirSync(binDirectory);
+    writeFileSync(ghPath, options.ghScript ??
+        '#!/bin/sh\nif [ "$1" = api ]; then echo transport-download-control; else printf "downloaded %s\\n" "$*"; fi\n');
+    chmodSync(ghPath, 0o755);
+    if (options.sleepScript !== undefined) {
+        const sleepPath = join(binDirectory, 'sleep');
+        writeFileSync(sleepPath, options.sleepScript);
+        chmodSync(sleepPath, 0o755);
+    }
+    const args = typeof options.args === 'function'
+        ? options.args(temporaryDirectory)
+        : (options.args ?? [
+            '--name',
+            'transport-download-control',
+            '--dir',
+            join(temporaryDirectory, 'coverage-control'),
+        ]);
+    const result = spawnSync('bash', [script, ...args], {
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            GITHUB_OUTPUT: githubOutput,
+            GITHUB_REPOSITORY: 'owner/repo',
+            GITHUB_RUN_ID: '1234',
+            PATH: binDirectory + delimiter + process.env.PATH,
+            ...options.env,
+        },
+    });
+    return {
+        ...result,
+        output: existsSync(githubOutput) ? readFileSync(githubOutput, 'utf8') : '',
+        temporaryDirectory,
+    };
+}
+export function cleanupTemporaryDirectories() {
+    for (const directory of temporaryDirectories.splice(0))
+        rmSync(directory, { force: true, recursive: true });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -334,13 +334,13 @@
     "remark-gfm": "4.0.1",
     "smol-toml": "1.8.0",
     "spdx-expression-parse": "5.0.0",
-    "yaml": "2.9.0"
+    "yaml": "2.9.1"
   },
   "devDependencies": {
     "@ast-grep/cli": "0.45.3",
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
-    "agent-blackboard": "^0.5.0"
+    "agent-blackboard": "^0.6.0"
   },
   "peerDependencies": {
     "typescript": ">=5"

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

@@ -2,18 +2,34 @@
 set -euo pipefail
 
 usage() {
-  echo 'usage: download-optional-run-artifacts.sh (--name <name> | --pattern <pattern>) --dir <directory>' >&2
+  echo 'usage: download-optional-run-artifacts.sh (--name <name>... | --pattern <pattern>) --dir <directory>' >&2
   exit 2
 }
 
+contains() {
+  local needle="$1" item
+  shift
+  for item in "$@"; do
+    [ "$item" != "$needle" ] || return 0
+  done
+  return 1
+}
+
 selector=''
 selector_type=''
+names=()
 destination=''
 while [ "$#" -gt 0 ]; do
   case "$1" in
-    --name|--pattern)
+    --name)
+      { [ "$selector_type" != pattern ] && [ "$#" -ge 2 ] && [ -n "$2" ]; } || usage
+      selector_type=name
+      if [ "${#names[@]}" -eq 0 ] || ! contains "$2" "${names[@]}"; then names+=("$2"); fi
+      shift 2
+      ;;
+    --pattern)
       [ -z "$selector_type" ] && [ "$#" -ge 2 ] || usage
-      selector_type="${1#--}"
+      selector_type=pattern
       selector="$2"
       shift 2
       ;;
@@ -26,7 +42,8 @@ while [ "$#" -gt 0 ]; do
   esac
 done
 
-[ -n "$selector_type" ] && [ -n "$selector" ] && [ -n "$destination" ] || usage
+[ -n "$selector_type" ] && [ -n "$destination" ] || usage
+[ "$selector_type" != pattern ] || [ -n "$selector" ] || 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; }
@@ -47,30 +64,13 @@ esac
 
 validate_artifact_name() {
   case "$1" in
-    ''|.|..|*/*|*\\*)
+    ''|.|..|*/*|*\\*|*$'\n'*|*$'\r'*)
       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_once() {
   GH_HOST="$github_host" gh api \
     --paginate \
@@ -126,8 +126,47 @@ download_pattern() {
   done
 }
 
+warn_absent() {
+  local requested="$1" count=$(($# - 1)) list='' name
+  shift
+  for name in "${@:1:3}"; do
+    list="${list:+$list, }$name"
+  done
+  [ "$count" -le 3 ] || list="$list and $((count - 3)) more"
+  echo "::warning::Optional same-run artifacts absent: $count of $requested requested (${list//\%/%25})" >&2
+}
+
+download_names() {
+  local name status listed_names
+  listed=()
+  present=()
+  absent=()
+  for name in "${names[@]}"; do
+    validate_artifact_name "$name" || return $?
+  done
+  listed_names=$(list_artifact_names) || return $?
+  while IFS= read -r name; do
+    listed+=("$name")
+  done <<< "$listed_names"
+  for name in "${names[@]}"; do
+    if contains "$name" "${listed[@]}"; then present+=("$name"); else absent+=("$name"); fi
+  done
+  echo "[optional-run-artifacts] selection selector=name requested=${#names[@]} present=${#present[@]} absent=${#absent[@]}" >&2
+  [ "${#absent[@]}" -eq 0 ] || warn_absent "${#names[@]}" "${absent[@]}"
+  [ "${#present[@]}" -gt 0 ] || return 3
+  for name in "${present[@]}"; do
+    echo "[optional-run-artifacts] attempt selector=name artifact=$name" >&2
+    if GH_HOST="$github_host" gh run download "$GITHUB_RUN_ID" --repo "$repository" --name "$name" --dir "$destination/$name"; then :; else
+      status=$?
+      echo "[optional-run-artifacts] download failed artifact=$name exit=$status" >&2
+      [ "$status" -ne 3 ] || status=1
+      return "$status"
+    fi
+  done
+}
+
 if [ "$selector_type" = name ]; then
-  if download_exact "$selector" "$destination"; then status=0; else status=$?; fi
+  if download_names; then status=0; else status=$?; fi
 else
   if download_pattern; then status=0; else status=$?; fi
 fi
@@ -139,7 +178,7 @@ else
     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
+      [ "$selector_type" = name ] || 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
       ;;
     *)

package/scripts/gha/write-github-multiline-output.sh

@@ -26,17 +26,17 @@ delimiter_prefix=$(printf '%s' "$output_name" | tr '[:lower:]-' '[:upper:]_')
 delimiter=''
 attempt=1
 while [[ $attempt -le 10 ]]; do
-  if ! uuid=$(uuidgen); then
-    echo 'uuidgen failed while creating a GitHub output delimiter' >&2
+  if ! random_suffix=$(LC_ALL=C od -An -v -N16 -tx1 /dev/urandom | LC_ALL=C tr -d '[:space:]'); then
+    echo 'random suffix generation failed while creating a GitHub output delimiter' >&2
     exit 1
   fi
-  if [[ -z "$uuid" ]]; then
-    echo 'uuidgen returned an empty GitHub output delimiter suffix' >&2
+  if [[ ! "$random_suffix" =~ ^[[:xdigit:]]{32}$ ]]; then
+    echo 'random suffix generator returned an invalid GitHub output delimiter suffix' >&2
     exit 1
   fi
 
-  normalized_uuid=$(printf '%s' "$uuid" | tr '[:lower:]-' '[:upper:]_')
-  delimiter="${delimiter_prefix}_${normalized_uuid}"
+  normalized_suffix=$(printf '%s' "$random_suffix" | tr '[:lower:]-' '[:upper:]_')
+  delimiter="${delimiter_prefix}_${normalized_suffix}"
   if ! grep -Fq -- "$delimiter" "$payload_file"; then
     break
   fi

package/skills/blackboard/SKILL.md

@@ -14,6 +14,9 @@ subagent-identity rules.
    evidence, and any tracking reference.
 2. Preserve the provider's required session and parent-session identity. Never invent, guess,
    print, search for, or persist credentials outside its documented mechanism.
+   When the provider supports structured repository metadata, keep a cumulative list of canonical
+   repositories on each agent's own session and tag each entry with only its relevant repositories.
+   Update session metadata before appending, and stop if that update fails.
 3. If the journal service cannot authenticate or persist a mandatory entry, stop and report the
    blocker rather than silently substituting a local file or memory.
 4. Read journal entries oldest-first when preparing a retrospective or clustering follow-ups; use

package/skills/retrospective/SKILL.md

@@ -14,6 +14,8 @@ Read the local `AGENTS.md`, `CLAUDE.md`, and journal guidance first.
    sources. Do not estimate unknown facts from memory or transcripts.
 3. Summarize the outcome, plan-versus-actual differences, validation evidence, recurring friction,
    and actionable process improvements. Keep one-off noise separate from repeatable root causes.
+   Preserve the repository attribution of the source entries in the retrospective record when the
+   journal supports it; a retrospective spanning repositories names every represented repository.
 4. Save through the repository's required durable mechanism and report the record identifier plus
    any follow-up decisions.
 

package/skills/retrospective-distill/SKILL.md

@@ -8,7 +8,9 @@ description: Distill completed session records into a small set of verified, act
 Use when completed retrospectives or journals should become durable follow-up work. Read local
 `AGENTS.md`, `CLAUDE.md`, issue policy, and journal retention rules before any mutation.
 
-1. Enumerate only completed, eligible session records. Leave in-progress sessions intact.
+1. Enumerate only completed, eligible session records. For repository-scoped work, filter sessions
+   by repository membership and use only entries attributed to that repository. Keep untagged legacy
+   records unclassified instead of inferring their repository. Leave in-progress sessions intact.
 2. Cluster findings by root cause, favoring a few broad actionable themes over many narrow issues.
    Treat a finding already linked to an open tracker as context, not a duplicate.
 3. Verify each candidate against the current base and search existing issues and open changes before
@@ -17,7 +19,9 @@ Use when completed retrospectives or journals should become durable follow-up wo
    validation. Route every authorized creation through
    [github-issue](../github-issue/SKILL.md), including its repository gate, label approval, and
    denied-external tracking behavior.
-5. Archive only records that were fully processed under the repository's retention rules; report
+5. Archive only records that were fully processed across every represented repository under the
+   repository's retention rules. A one-repository pass leaves a multi-repository session active
+   until its other repositories have been reviewed. Report
    created, updated, skipped, and deferred themes with reasons.
 
 Use source records only for local verification and leave them in the repository's approved journal

package/skills/test-authoring/SKILL.md

@@ -18,3 +18,6 @@ rules before choosing a runner-specific approach.
 
 Read [tautological tests](references/tautological-tests.md) before finishing any test whose
 assertion is not obviously falsifiable by a defect in the code under test.
+
+Read [dependency boundaries](references/dependency-boundaries.md) before asserting on anything a
+dependency produces, and whenever a dependency upgrade breaks a test.

package/skills/test-authoring/references/core-practice.md

@@ -2,7 +2,9 @@
 
 Choose the lowest realistic boundary that can observe the contract. Mock external systems and
 uncontrolled infrastructure; exercise internal module composition where practical. Test behavior,
-failure paths, authorization, and security-relevant validation rather than private calls.
+failure paths, authorization, and security-relevant validation rather than private calls, and
+assert what this repository owns rather than what its [dependencies](dependency-boundaries.md)
+produce.
 
 Start with a failing test when the behavior is testable. Finish only when the production path, its
 public contract, documentation, and generated artifacts move together. Do not leave placeholders or

package/skills/test-authoring/references/dependency-boundaries.md

@@ -0,0 +1,37 @@
+# Dependency boundaries
+
+Test the code this repository owns. A dependency's behavior — its algorithms, error messages, output
+formats, internal file layout, exit codes, the URLs and query strings it builds, its pagination and
+retry strategy, and the order or number of calls it makes — belongs to that dependency's own tests.
+An assertion that pins any of it fails when the dependency ships a release rather than when this
+repository regresses, so every upgrade arrives as a red build that no change here caused.
+
+Apply the [tautological tests](tautological-tests.md) falsifiability check with ownership added: for
+every assertion, name a defect in this repository's code that would make it fail. If only a
+dependency release could fail it, delete it. If it covers owned logic but also pins incidental
+dependency detail, rewrite it to assert the owned outcome. What the repository chooses or promises
+is owned even when a dependency carries it out — the rules it enables, its thresholds and scopes,
+the arguments, endpoints, and parameters it passes, how it handles a dependency's exit codes and
+errors, and any call count or order its own logic requires — so test it, but through the
+dependency's public API rather than its internals.
+
+Watch for these shapes. A version-drift guard deep-imports a package's private files or calls its
+internal functions so the suite notices when upstream behavior changes; it couples the suite to a
+layout the package never promised, so delete it, and when documentation relies on dependency
+behavior, link to the dependency's own documentation instead of restating and pinning it. A
+dependency re-test runs a dependency with fabricated input and asserts what it returns; a wrapper
+that only forwards configuration needs one test proving the configuration arrives, not a second copy
+of the dependency's suite. An upstream-output pin asserts exact dependency-owned messages, markdown,
+JSON envelopes, or renderer markup when the owned contract is narrower; assert the rule identifier,
+status, or owned field instead. A sequence-bound fake answers by call order — chained one-shot mock
+responses, or a queue of canned replies consumed in turn — when the code under test does not own
+that order, so a dependency that adds a request, paginates differently, or reorders its calls hands
+the wrong reply to the wrong call; route the fake by request meaning, such as method and pathname,
+and assert the owned result rather than dependency-incidental URL, query-string, or call-count
+details.
+
+When a dependency upgrade breaks a test, first ask whether the test pinned dependency behavior. If
+it did, fix the test by deleting or rewriting it rather than re-pinning the new upstream value, and
+do not add a guard that fails on the next release. If the failure traces to owned code or owned
+configuration — the dependency now rejects arguments this repository passes, or returns a result
+this repository's logic mishandles — it is a real regression, so fix the owned code instead.