vouchington-tooling 0.2.0 → 0.3.1

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

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { chmod, open, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { countsFor, manifestFor, snapshotLine, } from './snapshot-partition-format.mjs';
+import { readLines, writeAll } from './snapshot-partition-io.mjs';
+async function copyBlock(block, output, hash) {
+    const input = await open(block.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const buffer = Buffer.allocUnsafe(64 * 1024);
+    try {
+        for (;;) {
+            const { bytesRead } = await input.read(buffer);
+            if (!bytesRead)
+                return;
+            const bytes = buffer.subarray(0, bytesRead);
+            hash.update(bytes);
+            await writeAll(output, bytes);
+        }
+    }
+    finally {
+        await input.close();
+    }
+}
+export async function writePartitions(index, manifest, directory, maxSessions, maxBytes) {
+    const partitions = [];
+    const indexFile = await open(index, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let active;
+    const start = async () => {
+        const number = partitions.length + 1;
+        const temporary = join(directory, `.partition-${number}.tmp`);
+        active = {
+            block: { sessionId: '', path: '', bytes: 0, sessions: 0, entries: 0 },
+            file: await open(temporary, 'wx', 0o600),
+            temporary,
+            hash: createHash('sha256'),
+        };
+        return active;
+    };
+    const finish = async () => {
+        if (!active)
+            return;
+        const partitionManifest = manifestFor(manifest, active.block);
+        const terminal = Buffer.from(snapshotLine({ type: 'manifest', manifest: partitionManifest }));
+        await writeAll(active.file, terminal);
+        active.hash.update(terminal);
+        await active.file.sync();
+        await active.file.close();
+        await chmod(active.temporary, 0o400);
+        const path = join(directory, `partition-${partitions.length + 1}.jsonl`);
+        await rename(active.temporary, path);
+        const bytes = active.block.bytes + terminal.byteLength;
+        partitions.push({
+            path,
+            counts: countsFor(active.block, bytes),
+            checksum: { algorithm: 'sha256', value: active.hash.digest('hex') },
+            manifest: partitionManifest,
+        });
+        active = undefined;
+    };
+    try {
+        for await (const sourceLine of readLines(indexFile)) {
+            const block = JSON.parse(sourceLine);
+            if (active && active.block.sessions + block.sessions > maxSessions)
+                await finish();
+            let candidate = {
+                ...block,
+                sessions: (active?.block.sessions ?? 0) + block.sessions,
+                entries: (active?.block.entries ?? 0) + block.entries,
+            };
+            let terminalBytes = Buffer.byteLength(snapshotLine({ type: 'manifest', manifest: manifestFor(manifest, candidate) }));
+            if (active && active.block.bytes + block.bytes + terminalBytes > maxBytes) {
+                await finish();
+                candidate = { ...block };
+                terminalBytes = Buffer.byteLength(snapshotLine({ type: 'manifest', manifest: manifestFor(manifest, candidate) }));
+            }
+            if (block.bytes + terminalBytes > maxBytes)
+                throw new Error(`snapshot session ${block.sessionId} is too large for one partition`);
+            const target = active ?? (await start());
+            target.block.sessions += block.sessions;
+            target.block.entries += block.entries;
+            target.block.bytes += block.bytes;
+            await copyBlock(block, target.file, target.hash);
+        }
+        await finish();
+        return partitions;
+    }
+    finally {
+        await indexFile.close();
+        await active?.file.close().catch(() => undefined);
+    }
+}

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

@@ -0,0 +1,10 @@
+import { chmod, mkdtemp, open } from 'node:fs/promises';
+import type { SnapshotPartitionOptions, SnapshotPartitionResult } from './snapshot-types.mts';
+declare const defaults: {
+    open: typeof open;
+    mkdtemp: typeof mkdtemp;
+    chmod: typeof chmod;
+};
+export declare function setSnapshotFilesystemForTest(overrides?: Partial<typeof defaults>): void;
+export declare function partitionSnapshot(options: SnapshotPartitionOptions): Promise<SnapshotPartitionResult>;
+export {};

package/dist/agent-blackboard/snapshot-partitions.mjs

@@ -0,0 +1,102 @@
+import { constants } from 'node:fs';
+import { chmod, lstat, mkdtemp, open, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, resolve } from 'node:path';
+import { stageSnapshot } from './snapshot-partition-read.mjs';
+import { writeCleanupReceipt } from './snapshot-cleanup-receipt.mjs';
+import { readLines } from './snapshot-partition-io.mjs';
+import { writePartitions } from './snapshot-partition-write.mjs';
+const MAX_SESSIONS = 25;
+const MAX_BYTES = 1024 * 1024;
+const SOURCE_NAME = /^agent-blackboard-snapshot-[0-9a-f-]{36}\.jsonl$/;
+const defaults = { open, mkdtemp, chmod };
+let filesystem = defaults;
+export function setSnapshotFilesystemForTest(overrides) {
+    filesystem = { ...defaults, ...overrides };
+}
+function assertLimit(value, fallback, label) {
+    const limit = value ?? fallback;
+    if (!Number.isSafeInteger(limit) || limit < 1)
+        throw new Error(`${label} must be a positive integer`);
+    return limit;
+}
+function assertGeneratedSnapshot(path) {
+    if (!isAbsolute(path))
+        throw new Error('snapshot path must be absolute');
+    if (dirname(resolve(path)) !== resolve(tmpdir()) || !SOURCE_NAME.test(basename(path)))
+        throw new Error('snapshot path must be a generated temporary snapshot path');
+}
+function assertVerification(bytes, checksum, manifest, options) {
+    if (options.checksum &&
+        (options.checksum.algorithm !== 'sha256' || options.checksum.value !== checksum))
+        throw new Error('snapshot checksum does not match');
+    if (options.counts &&
+        (options.counts.bytes !== bytes ||
+            options.counts.sessions !== manifest.counts.sessions ||
+            options.counts.entries !== manifest.counts.entries ||
+            options.counts.records !== manifest.counts.records))
+        throw new Error('snapshot counts do not match');
+}
+async function hashSnapshot(source) {
+    const hash = (await import('node:crypto')).createHash('sha256');
+    for await (const _line of readLines(source, hash)) {
+        // Consume the full descriptor to hash the same source a second time.
+    }
+    return hash.digest('hex');
+}
+export async function partitionSnapshot(options) {
+    assertGeneratedSnapshot(options.path);
+    const before = await lstat(options.path);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1)
+        throw new Error('snapshot path must be an unlinked generated regular file');
+    let source;
+    let stage;
+    let directory;
+    try {
+        source = await filesystem.open(options.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        stage = await filesystem.mkdtemp(resolve(tmpdir(), 'agent-blackboard-partition-stage-'));
+        directory = await filesystem.mkdtemp(resolve(tmpdir(), 'agent-blackboard-partitions-'));
+        const permissions = await Promise.allSettled([
+            filesystem.chmod(stage, 0o700),
+            filesystem.chmod(directory, 0o700),
+        ]);
+        const permissionFailure = permissions.find((result) => result.status === 'rejected');
+        if (permissionFailure?.status === 'rejected')
+            throw permissionFailure.reason;
+        const opened = await source.stat();
+        if (!opened.isFile() ||
+            opened.nlink !== 1 ||
+            opened.dev !== before.dev ||
+            opened.ino !== before.ino)
+            throw new Error('snapshot path changed while it was being opened');
+        const staged = await stageSnapshot(source, stage);
+        const after = await source.stat();
+        if (after.dev !== opened.dev ||
+            after.ino !== opened.ino ||
+            after.nlink !== 1 ||
+            opened.size !== staged.bytes ||
+            after.size !== staged.bytes)
+            throw new Error('snapshot path changed while it was being read');
+        if ((await hashSnapshot(source)) !== staged.checksum)
+            throw new Error('snapshot path changed while it was being read');
+        await source.close();
+        source = undefined;
+        assertVerification(staged.bytes, staged.checksum, staged.manifest, options);
+        const partitions = await writePartitions(staged.index, staged.manifest, directory, assertLimit(options.maxSessions, MAX_SESSIONS, 'maxSessions'), assertLimit(options.maxBytes, MAX_BYTES, 'maxBytes'));
+        return {
+            directory: directory,
+            partitions,
+            cleanupReceipt: await writeCleanupReceipt(directory, partitions),
+        };
+    }
+    catch (error) {
+        if (directory)
+            await rm(directory, { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        await source?.close().catch(() => undefined);
+        if (stage)
+            await rm(stage, { recursive: true, force: true });
+    }
+}

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

@@ -0,0 +1,67 @@
+export type SnapshotSelection = {
+    agent?: string;
+    version?: string;
+    parentSessionId?: string | null;
+    data?: Record<string, unknown>;
+    inactiveForHours?: number;
+};
+export type SnapshotCounts = {
+    sessions: number;
+    entries: number;
+    records: number;
+    bytes: number;
+};
+export type SnapshotManifest = {
+    schemaVersion: 1;
+    status: 'complete';
+    createdAt: string;
+    completedAt: string;
+    selection: SnapshotSelection & {
+        archived: false;
+    };
+    counts: Omit<SnapshotCounts, 'bytes'>;
+    ordering: {
+        sessions: 'createdAt ascending';
+        entries: 'createdAt ascending within session';
+    };
+    consistency: 'best-effort';
+};
+export type SnapshotChecksum = {
+    algorithm: 'sha256';
+    value: string;
+};
+export type SnapshotPartitionOptions = {
+    path: string;
+    checksum?: SnapshotChecksum;
+    counts?: SnapshotCounts;
+    maxSessions?: number;
+    maxBytes?: number;
+};
+export type SnapshotPartition = {
+    path: string;
+    counts: SnapshotCounts;
+    checksum: SnapshotChecksum;
+    manifest: SnapshotManifest;
+};
+export type SnapshotCleanupReceipt = {
+    schemaVersion: 1;
+    directory: string;
+    directoryDev: number;
+    directoryIno: number;
+    token: string;
+    partitions: Array<{
+        name: string;
+        checksum: SnapshotChecksum;
+    }>;
+    signature: string;
+};
+export type SnapshotPartitionResult = {
+    directory: string;
+    partitions: SnapshotPartition[];
+    cleanupReceipt: SnapshotCleanupReceipt;
+};
+export type SnapshotCleanupOptions = {
+    path?: string;
+    directory?: string;
+    receipt?: SnapshotCleanupReceipt;
+};

package/dist/agent-blackboard/snapshot-types.mjs

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

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

@@ -0,0 +1,3 @@
+export { cleanupSnapshotPartitions } from './snapshot-partition-cleanup.mts';
+export { partitionSnapshot } from './snapshot-partitions.mts';
+export type * from './snapshot-types.mts';

package/dist/agent-blackboard/snapshot.mjs

@@ -0,0 +1,2 @@
+export { cleanupSnapshotPartitions } from './snapshot-partition-cleanup.mjs';
+export { partitionSnapshot } from './snapshot-partitions.mjs';

package/dist/cli/commands/agent-blackboard.d.mts

@@ -0,0 +1,3 @@
+import { readJournal } from '../../agent-blackboard/index.mts';
+export declare function setJournalReaderForTest(reader?: typeof readJournal): void;
+export declare function runAgentBlackboardCommand(args: string[]): Promise<number>;

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

@@ -0,0 +1,114 @@
+import { appendJournal, formatJournalEntries, probeBlackboard, readJournal, } from '../../agent-blackboard/index.mjs';
+import { cleanupSnapshotPartitions, partitionSnapshot } from '../../agent-blackboard/snapshot.mjs';
+let journalReader = readJournal;
+export function setJournalReaderForTest(reader) {
+    journalReader = reader ?? readJournal;
+}
+export async function runAgentBlackboardCommand(args) {
+    try {
+        const [command, ...rest] = args;
+        if (command === 'probe' && rest.length === 0) {
+            await probeBlackboard();
+            return 0;
+        }
+        if (command === 'journal')
+            return await runJournal(rest);
+        if (command === 'snapshot')
+            return await runSnapshot(rest);
+        throw new Error('usage: agent-blackboard probe | journal append|entries | snapshot partition|cleanup');
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
+}
+async function runSnapshot(args) {
+    const [action, ...flags] = args;
+    const values = flagsToValues(flags);
+    if (action === 'cleanup') {
+        assertAllowed(values, ['snapshot', 'partition-directory', 'receipt']);
+        if (values['partition-directory'] && !values.receipt)
+            throw new Error('--receipt is required with --partition-directory');
+        await cleanupSnapshotPartitions({
+            ...(values.snapshot ? { path: values.snapshot } : {}),
+            ...(values['partition-directory'] ? { directory: values['partition-directory'] } : {}),
+            ...(values.receipt ? { receipt: JSON.parse(values.receipt) } : {}),
+        });
+        process.stdout.write('{"cleaned":true}\n');
+        return 0;
+    }
+    if (action === 'partition') {
+        assertAllowed(values, ['snapshot', 'checksum', 'counts']);
+        const counts = JSON.parse(required(values, 'counts'));
+        process.stdout.write(`${JSON.stringify(await partitionSnapshot({
+            path: required(values, 'snapshot'),
+            checksum: { algorithm: 'sha256', value: required(values, 'checksum') },
+            counts,
+        }))}\n`);
+        return 0;
+    }
+    throw new Error('usage: agent-blackboard snapshot partition|cleanup');
+}
+async function runJournal(args) {
+    const [action, ...flags] = args;
+    const values = flagsToValues(flags);
+    if (action === 'entries') {
+        assertAllowed(values, ['session-id']);
+        const sessionId = required(values, 'session-id');
+        let entries;
+        try {
+            entries = await journalReader(sessionId);
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                throw error;
+            entries = [];
+        }
+        process.stdout.write(`${formatJournalEntries(sessionId, entries)}\n`);
+        return 0;
+    }
+    if (action === 'append') {
+        assertAllowed(values, [
+            'session-id',
+            'agent',
+            'version',
+            'file',
+            '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`);
+        return 0;
+    }
+    throw new Error('usage: agent-blackboard journal append|entries');
+}
+function flagsToValues(flags) {
+    const values = {};
+    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 ?? ''}`);
+        const key = flag.slice(2);
+        if (key in values)
+            throw new Error(`duplicate option: ${flag}`);
+        values[key] = value;
+    }
+    return values;
+}
+function assertAllowed(values, allowed) {
+    for (const key of Object.keys(values))
+        if (!allowed.includes(key))
+            throw new Error(`unknown option: --${key}`);
+}
+function required(values, key) {
+    const value = values[key];
+    if (!value)
+        throw new Error(`--${key} is required`);
+    return value;
+}
+function isNotFound(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        (('status' in error && error.status === 404) ||
+            ('statusCode' in error && error.statusCode === 404)));
+}

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

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

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

@@ -0,0 +1,33 @@
+import { parseArgs } from 'node:util';
+import { runRetrospectiveFacts, } from '../../retrospective-facts/index.mjs';
+export async function runRetrospectiveFactsCommand(args) {
+    try {
+        const { values } = parseArgs({
+            args,
+            strict: true,
+            options: {
+                pr: { type: 'string' },
+                branch: { type: 'string' },
+                'no-pr': { type: 'boolean' },
+                repo: { type: 'string' },
+                raw: { type: 'boolean' },
+            },
+        });
+        const options = {
+            ...(values.pr === undefined ? {} : { pr: values.pr }),
+            ...(values.branch === undefined ? {} : { branch: values.branch }),
+            ...(values['no-pr'] === undefined ? {} : { noPr: values['no-pr'] }),
+            ...(values.repo === undefined ? {} : { repo: values.repo }),
+            ...(values.raw ? { raw: true } : {}),
+        };
+        process.stdout.write(await runRetrospectiveFacts({
+            ...options,
+            onWarning: (message) => process.stderr.write(`${message}\n`),
+        }));
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
+}

package/dist/cli/index.mjs

@@ -16,6 +16,8 @@ import { runSwiftSemanticEqualCommand } from './commands/swift-semantic-equal.mj
 import { runVitestBlobManifestCommand } from './commands/vitest-blob-manifest.mjs';
 import { runRetrospectiveTranscriptCommand } from './commands/retrospective-transcript.mjs';
 import { runLinkSkill } from './commands/link-skill.mjs';
+import { runRetrospectiveFactsCommand } from './commands/retrospective-facts.mjs';
+import { runAgentBlackboardCommand } from './commands/agent-blackboard.mjs';
 import { runWithHostLock } from './commands/with-host-lock.mjs';
 import { parseCli } from './parse.mjs';
 import { packageScriptPath } from './script-path.mjs';
@@ -58,6 +60,11 @@ const SCRIPT_PATHS = {
         path: 'scripts/gha/install-playwright-chromium-arm64.sh',
     },
     'ghcr-package-retention': { command: 'bash', path: 'scripts/gha/ghcr-package-retention.sh' },
+    'harness-admission-lane': {
+        command: 'bash',
+        path: 'scripts/gha/harness-admission-lane.sh',
+    },
+    'harness-assert-gates': { command: 'bash', path: 'scripts/gha/harness-assert-gates.sh' },
 };
 export function runCli(argv = process.argv) {
     const parsed = parseCli(argv);
@@ -102,6 +109,10 @@ export function runCli(argv = process.argv) {
             return runRetrospectiveTranscriptCommand(parsed.args);
         case 'link-skill':
             return runLinkSkill(parsed);
+        case 'retrospective-facts':
+            return runRetrospectiveFactsCommand(parsed.args);
+        case 'agent-blackboard':
+            return runAgentBlackboardCommand(parsed.args);
     }
 }
 function readInstalledVersion() {

package/dist/cli/parse.d.mts

@@ -48,6 +48,12 @@ export type ParsedCli = {
     name: string;
     sourceRoot: string;
     targetRoot: string;
+} | {
+    kind: 'retrospective-facts';
+    args: string[];
+} | {
+    kind: 'agent-blackboard';
+    args: string[];
 } | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup;
-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 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' | 'harness-admission-lane' | 'harness-assert-gates';
 export declare function parseCli(argv: readonly string[]): ParsedCli;

package/dist/cli/parse.mjs

@@ -20,6 +20,8 @@ const SCRIPT_COMMANDS = new Set([
     'wait-for-apt-locks',
     'install-playwright-chromium-arm64',
     'ghcr-package-retention',
+    'harness-admission-lane',
+    'harness-assert-gates',
 ]);
 export function parseCli(argv) {
     const args = argv.slice(2);
@@ -52,6 +54,10 @@ export function parseCli(argv) {
         return { kind: 'retrospective-transcript', args: rest };
     if (command === 'link-skill')
         return parseLinkSkill(rest);
+    if (command === 'retrospective-facts')
+        return { kind: 'retrospective-facts', args: rest };
+    if (command === 'agent-blackboard')
+        return { kind: 'agent-blackboard', 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  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  link-skill                    Link one packaged skill into an explicit consumer 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...]\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]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>\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  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\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>...\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 function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

@@ -27,12 +27,16 @@ Commands:
   wait-for-apt-locks            Wait until apt/dpkg lock files are free
   install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json
   ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN
+  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out
+  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled
   nuget-central-version         Validate a Directory.Packages.props PackageVersion delta
   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
   link-skill                    Link one packaged skill into an explicit consumer directory
+  retrospective-facts           Gather immutable facts for a retrospective
+  agent-blackboard              Probe and journal an Agent Blackboard deployment
 
 Options:
   -h, --help       Show this help
@@ -82,12 +86,20 @@ materialize-pr-context
 wait-for-apt-locks
 install-playwright-chromium-arm64 [name:archive...]
 ghcr-package-retention <url-encoded-package>...
+harness-admission-lane <lanes>
+harness-assert-gates <gate>...
 nuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>
 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]
-link-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>
+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 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]
 `;
 export function printUsage(stream = process.stdout) {
     stream.write(USAGE);

package/dist/gha-dependabot-automerge-action/index.test-helpers.d.mts

@@ -19,4 +19,4 @@ export declare function runPolicy(metadata: DependencyUpdate[] | string | undefi
 }, dependabot?: {
     directory: string;
     ecosystem: string;
-}, expectedBase?: string, expectedHead?: string, manualRules?: string, confirmedPullRequestOverrides?: Error | Record<string, unknown>, initialRefreshError?: Error): Promise<ScriptResult>;
+}, expectedBase?: string, expectedHead?: string, manualRules?: string, confirmedPullRequestOverrides?: Error | Record<string, unknown>, initialRefreshError?: Error, metadataOutcome?: string): Promise<ScriptResult>;

package/dist/gha-dependabot-automerge-action/index.test-helpers.mjs

@@ -14,7 +14,7 @@ export function update(prevVersion, newVersion, updateType, dependencyName = 'ex
         updateType,
     };
 }
-export async function runPolicy(metadata, pullRequestOverrides = {}, freshPullRequestOverrides = {}, mergeToken = 'merge-token', mutationResult = {}, dependabot = { directory: '/', ecosystem: 'npm' }, expectedBase, expectedHead, manualRules = '[]', confirmedPullRequestOverrides = freshPullRequestOverrides, initialRefreshError) {
+export async function runPolicy(metadata, pullRequestOverrides = {}, freshPullRequestOverrides = {}, mergeToken = 'merge-token', mutationResult = {}, dependabot = { directory: '/', ecosystem: 'npm' }, expectedBase, expectedHead, manualRules = '[]', confirmedPullRequestOverrides = freshPullRequestOverrides, initialRefreshError, metadataOutcome = 'success') {
     if (!script)
         throw new Error('Dependabot auto-merge script is missing');
     const failures = [];
@@ -74,6 +74,7 @@ export async function runPolicy(metadata, pullRequestOverrides = {}, freshPullRe
     const environment = {
         DEPENDABOT_DIRECTORY: dependabot.directory,
         DEPENDABOT_ECOSYSTEM: dependabot.ecosystem,
+        DEPENDABOT_METADATA_OUTCOME: metadataOutcome,
         EXPECTED_BASE_SHA: expectedBase ?? String(eventPullRequest.base.sha),
         EXPECTED_HEAD_SHA: expectedHead ?? String(eventPullRequest.head.sha),
         GRAPHQL_URL: 'https://github.example.test/api/graphql',

package/dist/index.d.mts

@@ -2,6 +2,10 @@ export { linkSkill, readSkillManifest } from './skill-discovery/index.mts';
 export type { LinkSkillOptions, LinkSkillResult, SkillManifest, SkillManifestEntry, } from './skill-discovery/index.mts';
 export { codexChildren, codexIdentity, computeTranscriptFacts, formatTranscriptFacts, formatUnavailable, resolveTranscriptFile, runRetrospectiveTranscript, } from './retrospective-transcript/index.mts';
 export type { ResolveOptions, TokenTotals, TranscriptFacts, } from './retrospective-transcript/index.mts';
+export { runRetrospectiveFacts } from './retrospective-facts/index.mts';
+export type { CommandExecutor, CommandResult, RetrospectiveFactsOptions, } from './retrospective-facts/index.mts';
+export { appendJournal, assertSessionId, cleanupSnapshotPartitions, partitionSnapshot, probeBlackboard, readJournal, resolveBlackboardConnection, } from './agent-blackboard/index.mts';
+export type { BlackboardConnection, SnapshotChecksum, SnapshotCleanupReceipt, SnapshotCleanupOptions, SnapshotCounts, SnapshotManifest, SnapshotPartition, SnapshotPartitionOptions, SnapshotPartitionResult, SnapshotSelection, } from './agent-blackboard/index.mts';
 export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from './session-friction/index.mts';
 export type { FrictionEvent, FrictionEventKind, FrictionLogOptions, FrictionLogReadResult, FrictionObservation, JournalEntry, JournalLoader, JournalLoadResult, PermissionRequestObservation, SessionFrictionReport, SessionFrictionReportOptions, ToolResultObservation, } from './session-friction/index.mts';
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mts';

package/dist/index.mjs

@@ -1,6 +1,8 @@
 /* eslint-disable max-lines -- package entry point enumerates the supported public API. */
 export { linkSkill, readSkillManifest } from './skill-discovery/index.mjs';
 export { codexChildren, codexIdentity, computeTranscriptFacts, formatTranscriptFacts, formatUnavailable, resolveTranscriptFile, runRetrospectiveTranscript, } from './retrospective-transcript/index.mjs';
+export { runRetrospectiveFacts } from './retrospective-facts/index.mjs';
+export { appendJournal, assertSessionId, cleanupSnapshotPartitions, partitionSnapshot, probeBlackboard, readJournal, resolveBlackboardConnection, } from './agent-blackboard/index.mjs';
 export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from './session-friction/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';

package/dist/retrospective-facts/exec.d.mts

@@ -0,0 +1,3 @@
+import type { CommandExecutor, CommandResult } from './shared.mts';
+export declare const shell: CommandExecutor;
+export declare function rawBlock(command: string, args: string[], result: CommandResult): string;