vouchington-tooling 0.2.0 → 0.3.0

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>\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>
+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/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;

package/dist/retrospective-facts/exec.mjs

@@ -0,0 +1,19 @@
+import { spawn } from 'node:child_process';
+export const shell = (command, args) => new Promise((resolve) => {
+    const child = spawn(command, args);
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (data) => {
+        stdout += data;
+    });
+    child.stderr.on('data', (data) => {
+        stderr += data;
+    });
+    child.on('close', (exitCode) => resolve({ ok: exitCode === 0, stdout, stderr, exitCode }));
+    child.on('error', (error) => resolve({ ok: false, stdout, stderr: error.message, exitCode: null }));
+});
+export function rawBlock(command, args, result) {
+    return `$ ${command} ${args.join(' ')}\n${result.stdout}${result.stderr ? `${result.stdout ? '\n' : ''}stderr:\n${result.stderr}` : ''}\n\n`;
+}

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

@@ -0,0 +1,2 @@
+import { type CommandExecutor, type RetrospectiveFactsOptions } from './shared.mts';
+export declare function foreignFacts(options: RetrospectiveFactsOptions, execute: CommandExecutor): Promise<string>;

package/dist/retrospective-facts/foreign.mjs

@@ -0,0 +1,36 @@
+import { rawBlock } from './exec.mjs';
+import { apiFiles, count, dirs, format, objectField, readJson, stringField } from './format.mjs';
+import { PR_JSON_FIELDS } from './shared.mjs';
+export async function foreignFacts(options, execute) {
+    const args = ['pr', 'view', options.pr, '--repo', options.repo, '--json', PR_JSON_FIELDS];
+    const result = await execute('gh', args);
+    const data = result.ok ? readJson(result.stdout) : undefined;
+    const state = stringField(data, 'state', result.ok ? 'unavailable' : 'gh failed');
+    const base = stringField(data, 'baseRefName');
+    const merged = state === 'MERGED'
+        ? base === 'main'
+            ? 'yes (GitHub reports PR MERGED into main)'
+            : base === 'unavailable'
+                ? 'unavailable'
+                : `no (GitHub reports PR MERGED into ${base})`
+        : state === 'OPEN' || state === 'CLOSED'
+            ? `no (GitHub reports PR ${state})`
+            : 'unavailable';
+    return format({
+        fetch: 'not run (scoped GitHub repository)',
+        fetchStatus: 'not run',
+        fetchNote: 'scoped GitHub state is authoritative',
+        branch: stringField(data, 'headRefName'),
+        pr: stringField(data, 'number'),
+        state,
+        mergedAt: stringField(data, 'mergedAt'),
+        mergeCommit: objectField(data, 'mergeCommit', 'oid'),
+        merged,
+        commits: 'unavailable',
+        prCommits: count(data, 'commits'),
+        files: apiFiles(data),
+        dirs: dirs(data),
+        changeSource: 'api',
+        scoped: `${options.repo}#${options.pr}`,
+    }, options.raw ? rawBlock('gh', args, result) : '');
+}

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

@@ -0,0 +1,10 @@
+export declare function format(f: Record<string, string | undefined> & {
+    changeSource?: 'api' | 'local';
+}, raw: string): string;
+export declare function readJson(value: string): Record<string, unknown> | undefined;
+export declare function stringField(value: Record<string, unknown> | undefined, key: string, fallback?: string): string;
+export declare function objectField(value: Record<string, unknown> | undefined, key: string, child: string): string | undefined;
+export declare function count(value: Record<string, unknown> | undefined, key: string): string;
+export declare function topDirs(files: string): string;
+export declare function dirs(value: Record<string, unknown> | undefined): string;
+export declare function apiFiles(value: Record<string, unknown> | undefined): string;

package/dist/retrospective-facts/format.mjs

@@ -0,0 +1,64 @@
+export function format(f, raw) {
+    const scoped = f.scoped ? `n/a (scoped to ${f.scoped})` : undefined;
+    const fileSource = f.changeSource === 'api' ? 'GitHub API' : 'origin/main';
+    return `=== Retrospective Facts ===\nFetch: ${f.fetch}\nFetch status: ${f.fetchStatus}\nFetch note: ${f.fetchNote}\nBranch: ${f.branch}\nPR: ${f.pr ?? 'unavailable'}\nPR state: ${f.state}\nPR merged at: ${f.mergedAt ?? 'unavailable'}\nPR merge commit: ${f.mergeCommit ?? 'unavailable'}\nMerged to main: ${f.merged}\nCommits ahead of origin/main: ${f.commits ?? 'unavailable'}\nPR commits: ${f.prCommits ?? 'unavailable'}\nRemote updates for origin/${f.branch}: ${f.remote ?? scoped ?? 'unavailable'}\nPush-like updates for origin/${f.branch}: ${f.pushes ?? scoped ?? 'unavailable'}\nFiles changed from ${fileSource}: ${f.files}\nTop-level dirs changed from ${fileSource}: ${f.dirs}\nWorking tree changes: ${scoped ?? f.working ?? 'unavailable'}\n${raw}`;
+}
+export function readJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function stringField(value, key, fallback = 'unavailable') {
+    const field = value?.[key];
+    return typeof field === 'string' || typeof field === 'number' ? String(field) : fallback;
+}
+export function objectField(value, key, child) {
+    const field = value?.[key];
+    return field && typeof field === 'object'
+        ? stringField(field, child)
+        : undefined;
+}
+export function count(value, key) {
+    const length = listLength(value, key);
+    if (length === undefined)
+        return 'unavailable';
+    return length >= 100
+        ? "100+ (gh's commits list caps at 100; actual count may be higher)"
+        : String(length);
+}
+function listLength(value, key) {
+    return Array.isArray(value?.[key]) ? value[key].length : undefined;
+}
+export function topDirs(files) {
+    const dirs = [
+        ...new Set(files
+            .split('\n')
+            .filter(Boolean)
+            .map((file) => (file.includes('/') ? file.split('/')[0] : 'root'))),
+    ];
+    return dirs.length ? dirs.sort().join(',') : 'none';
+}
+export function dirs(value) {
+    const files = value?.files;
+    if (!Array.isArray(files))
+        return 'unavailable';
+    const result = topDirs(files
+        .map((file) => typeof file === 'object' && file
+        ? stringField(file, 'path', '')
+        : '')
+        .join('\n'));
+    const total = stringField(value, 'changedFiles');
+    return total !== 'unavailable' && Number(total) > files.length
+        ? `${result} (partial: gh returned ${files.length} of ${total} changed files)`
+        : result;
+}
+export function apiFiles(value) {
+    const total = stringField(value, 'changedFiles');
+    const listed = listLength(value, 'files');
+    return total !== 'unavailable' && listed !== undefined && Number(total) !== listed
+        ? `${total} (partial: gh returned ${listed} of ${total} changed files)`
+        : total;
+}