vouchington-tooling 0.24.1 → 0.26.0

package/dist/cli/installed-version.mjs

@@ -0,0 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { readPackageVersion } from '../package-version.mjs';
+export function readInstalledVersion() {
+    return readPackageVersion(JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')));
+}

package/dist/cli/parse-forwarded-commands.d.mts

@@ -37,6 +37,9 @@ type ForwardedCommand = {
 } | {
     kind: 'agent-blackboard';
     args: string[];
+} | {
+    kind: 'mcp';
+    args: string[];
 };
 export declare function parseForwardedCommand(command: string | undefined, args: string[]): ForwardedCommand | undefined;
 export {};

package/dist/cli/parse-forwarded-commands.mjs

@@ -25,5 +25,7 @@ export function parseForwardedCommand(command, args) {
         return { kind: 'retrospective-facts', args };
     if (command === 'agent-blackboard')
         return { kind: 'agent-blackboard', args };
+    if (command === 'mcp')
+        return { kind: 'mcp', args };
     return undefined;
 }

package/dist/cli/parse.d.mts

@@ -66,6 +66,9 @@ export type ParsedCli = {
 } | {
     kind: 'agent-blackboard';
     args: string[];
+} | {
+    kind: 'mcp';
+    args: string[];
 } | {
     kind: 'require-up-to-date';
     remote: string;

package/dist/cli/usage.d.mts

@@ -1,4 +1,4 @@
-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  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling\n  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this\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 --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal flush --outbox-directory PATH\nInteractive journal append requires --outbox-directory PATH.\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  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)\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  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling\n  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this\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 --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal flush --outbox-directory PATH\nInteractive journal append requires --outbox-directory PATH.\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]\nmcp\n  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,\n                         session_ensure, snapshot_export, and session_archive over stdio.\n                         Needs the optional @modelcontextprotocol/sdk peer (and zod).\n                         Launch it from inside the repository's git worktree.\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;
 export declare function commandNames(usage?: string): string[];
 export declare function commandUsage(command: string, usage?: string): string;

package/dist/cli/usage.mjs

@@ -45,6 +45,7 @@ Commands:
   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
+  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)
 
 Options:
   -h, --help       Show this help
@@ -124,6 +125,11 @@ agent-blackboard journal flush --outbox-directory PATH
 Interactive journal append requires --outbox-directory PATH.
 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]
+mcp
+  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,
+                         session_ensure, snapshot_export, and session_archive over stdio.
+                         Needs the optional @modelcontextprotocol/sdk peer (and zod).
+                         Launch it from inside the repository's git worktree.
 `;
 export function printUsage(stream = process.stdout) {
     stream.write(USAGE);

package/dist/mcp-server/args.d.mts

@@ -0,0 +1,9 @@
+export type Args = Record<string, unknown>;
+export declare function requireObject(value: unknown): Args;
+export declare function rejectUnknown(args: Args, allowed: Iterable<string>): void;
+export declare function requiredString(args: Args, name: string): string;
+export declare function optionalString(args: Args, name: string): string | undefined;
+export declare function requiredNullableString(args: Args, name: string): string | null;
+export declare function requiredChoice<T extends string>(args: Args, name: string, choices: readonly T[]): T;
+export declare function requiredStringArray(args: Args, name: string): string[];
+export declare function optionalRecord(args: Args, name: string): Args | undefined;

package/dist/mcp-server/args.mjs

@@ -0,0 +1,48 @@
+export function requireObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error('tool arguments must be an object');
+    return value;
+}
+export function rejectUnknown(args, allowed) {
+    const known = new Set(allowed);
+    const extra = Object.keys(args).filter((key) => !known.has(key));
+    if (extra.length)
+        throw new Error(`unsupported argument(s): ${extra.join(', ')}`);
+}
+export function requiredString(args, name) {
+    const value = args[name];
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`${name} is required and must be a non-empty string`);
+    return value;
+}
+export function optionalString(args, name) {
+    return args[name] === undefined ? undefined : requiredString(args, name);
+}
+export function requiredNullableString(args, name) {
+    if (args[name] === null)
+        return null;
+    const value = args[name];
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`${name} is required: a non-empty string, or null for none`);
+    return value;
+}
+export function requiredChoice(args, name, choices) {
+    const value = args[name];
+    if (typeof value !== 'string' || !choices.includes(value))
+        throw new Error(`${name} is required and must be one of: ${choices.join(', ')}`);
+    return value;
+}
+export function requiredStringArray(args, name) {
+    const value = args[name];
+    if (!Array.isArray(value) || !value.length || value.some((item) => typeof item !== 'string'))
+        throw new Error(`${name} is required and must be a non-empty array of strings`);
+    return value;
+}
+export function optionalRecord(args, name) {
+    const value = args[name];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error(`${name} must be an object`);
+    return value;
+}

package/dist/mcp-server/context.d.mts

@@ -0,0 +1,19 @@
+import type { BlackboardClientDependencies } from '../agent-blackboard/client.mts';
+import type { FeedbackIdentity } from '../agent-blackboard/feedback-types.mts';
+import { type Args } from './args.mts';
+/** What a handler may rely on: every field here was validated before the handler ran. */
+type ToolContext = {
+    sessionId: string;
+    worktree: string;
+    env: NodeJS.ProcessEnv;
+    dependencies: BlackboardClientDependencies;
+};
+export type ToolHandler = (args: Args, context: ToolContext) => Promise<Record<string, unknown>>;
+/**
+ * The consumer convention for the interactive outbox. It is derived, never accepted from the
+ * caller, so a credentialed, unsandboxed server cannot be pointed at an arbitrary directory.
+ */
+export declare function outboxDirectory(worktree: string): string;
+export declare function readSessionId(args: Args): string;
+export declare function readIdentity(args: Args, sessionId: string): FeedbackIdentity;
+export {};

package/dist/mcp-server/context.mjs

@@ -0,0 +1,23 @@
+import { join } from 'node:path';
+import { assertSessionId } from '../agent-blackboard/session-id.mjs';
+import { requiredNullableString, requiredString } from './args.mjs';
+/**
+ * The consumer convention for the interactive outbox. It is derived, never accepted from the
+ * caller, so a credentialed, unsandboxed server cannot be pointed at an arbitrary directory.
+ */
+export function outboxDirectory(worktree) {
+    return join(worktree, '.local', 'blackboard-outbox');
+}
+export function readSessionId(args) {
+    const value = requiredString(args, 'sessionId');
+    assertSessionId(value);
+    return value;
+}
+export function readIdentity(args, sessionId) {
+    return {
+        sessionId,
+        parentSessionId: requiredNullableString(args, 'parentSessionId'),
+        agent: requiredString(args, 'agent'),
+        version: requiredString(args, 'version'),
+    };
+}

package/dist/mcp-server/dispatch.d.mts

@@ -0,0 +1,18 @@
+import type { BlackboardClientDependencies } from '../agent-blackboard/client.mts';
+import type { RunTextCommand } from '../gh-cli/exec.mts';
+export type ServerEnvironment = {
+    launchRoot: string;
+    env: NodeJS.ProcessEnv;
+    runGit: RunTextCommand;
+    /** Test seam: replaces how the consumer's `agent-blackboard` client is loaded. */
+    blackboard?: BlackboardClientDependencies;
+};
+export type ToolCallResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: true;
+};
+/** Runs one tool call. Every failure becomes an MCP tool error; nothing here throws. */
+export declare function callTool(name: string, rawArguments: unknown, environment: ServerEnvironment): Promise<ToolCallResult>;

package/dist/mcp-server/dispatch.mjs

@@ -0,0 +1,62 @@
+import { join } from 'node:path';
+import { FeedbackDeliveryError } from '../agent-blackboard/index.mjs';
+import { optionalString, rejectUnknown, requireObject } from './args.mjs';
+import { readSessionId } from './context.mjs';
+import { journalAppend, journalEntries, outboxFlush, outboxStatus } from './handlers-journal.mjs';
+import { sessionArchive, sessionEnsure, snapshotExport } from './handlers-session.mjs';
+import { TOOLS } from './tools.mjs';
+import { resolveWorktree } from './worktree.mjs';
+const HANDLERS = {
+    journal_append: journalAppend,
+    journal_entries: journalEntries,
+    outbox_status: outboxStatus,
+    outbox_flush: outboxFlush,
+    session_ensure: sessionEnsure,
+    snapshot_export: snapshotExport,
+    session_archive: sessionArchive,
+};
+const DIAGNOSTIC_HINTS = {
+    'identity-conflict': 'the session already exists with a different parent, agent, or version',
+    'event-conflict': 'sourceEventId was already used with different content or timestamp; use a new sourceEventId',
+    'archived-session': 'the session is archived; write to a new session',
+    'authentication-rejected': 'the blackboard rejected AGENT_BLACKBOARD_TOKEN',
+    'blackboard-unavailable': 'the blackboard could not be reached or returned an error',
+    'configuration-invalid': 'AGENT_BLACKBOARD_URL or AGENT_BLACKBOARD_TOKEN is missing or invalid',
+    'client-unavailable': 'agent-blackboard is not installed in the worktree',
+    'readback-unconfirmed': 'the write could not be confirmed; retry with the same sourceEventId and timestamp',
+    'delivery-timeout': 'delivery timed out; retry with the same sourceEventId and timestamp',
+};
+function describeError(error) {
+    if (error instanceof FeedbackDeliveryError)
+        return `${error.message} (${DIAGNOSTIC_HINTS[error.diagnostic]})`;
+    return error instanceof Error ? error.message : String(error);
+}
+/** Runs one tool call. Every failure becomes an MCP tool error; nothing here throws. */
+export async function callTool(name, rawArguments, environment) {
+    try {
+        const definition = TOOLS.find((candidate) => candidate.name === name);
+        const handler = HANDLERS[name];
+        if (!definition || !handler)
+            throw new Error(`unknown tool ${name}; available: ${TOOLS.map((tool) => tool.name).join(', ')}`);
+        const args = requireObject(rawArguments ?? {});
+        rejectUnknown(args, Object.keys(definition.inputSchema.properties));
+        // Everything below this line may touch disk or the network, so identity comes first.
+        const sessionId = readSessionId(args);
+        const worktree = await resolveWorktree({
+            launchRoot: environment.launchRoot,
+            requested: optionalString(args, 'worktree'),
+            runGit: environment.runGit,
+        });
+        const result = await handler(args, {
+            sessionId,
+            worktree,
+            env: environment.env,
+            // The client resolves from the validated worktree, never from the server's own location.
+            dependencies: { ...environment.blackboard, resolveFrom: join(worktree, 'package.json') },
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (error) {
+        return { isError: true, content: [{ type: 'text', text: describeError(error) }] };
+    }
+}

package/dist/mcp-server/fake-blackboard.test-helpers.d.mts

@@ -0,0 +1,39 @@
+import type { BlackboardClientDependencies } from '../agent-blackboard/client.mts';
+export declare const BLACKBOARD_ENV: {
+    AGENT_BLACKBOARD_URL: string;
+    AGENT_BLACKBOARD_TOKEN: string;
+};
+type StoredEntry = {
+    sessionId?: string;
+    createdAt: string;
+    data: unknown;
+};
+export type FakeOptions = {
+    archived?: boolean;
+    omitArchive?: boolean;
+    omitSnapshots?: boolean;
+    exportResult?: unknown;
+    /** Makes `ensure` fail and `get` report a session with this different identity. */
+    conflictingSession?: {
+        id: string;
+        parentSessionId: null;
+        agent: string;
+        version: string;
+    };
+    entries?: StoredEntry[];
+    entriesError?: unknown;
+};
+export type FakeBlackboard = {
+    dependencies: BlackboardClientDependencies;
+    calls: {
+        ensure: unknown[];
+        patch: unknown[];
+        append: unknown[];
+        archive: string[];
+        export: unknown[];
+    };
+    stored: StoredEntry[];
+};
+/** An in-memory blackboard client faked at the module boundary `loadClient` provides. */
+export declare function fakeBlackboard(options?: FakeOptions): FakeBlackboard;
+export {};

package/dist/mcp-server/fake-blackboard.test-helpers.mjs

@@ -0,0 +1,75 @@
+export const BLACKBOARD_ENV = {
+    AGENT_BLACKBOARD_URL: 'https://provider.test',
+    AGENT_BLACKBOARD_TOKEN: 'test-private-token',
+};
+const SNAPSHOT = {
+    path: '/private/snapshots/export.jsonl',
+    counts: { sessions: 1, entries: 2, records: 3, bytes: 4 },
+    checksum: { algorithm: 'sha256', value: 'abc' },
+    manifest: { schemaVersion: 1 },
+    cleanupToken: 'token',
+};
+/** An in-memory blackboard client faked at the module boundary `loadClient` provides. */
+export function fakeBlackboard(options = {}) {
+    const calls = {
+        ensure: [],
+        patch: [],
+        append: [],
+        archive: [],
+        export: [],
+    };
+    const stored = options.entries ?? [];
+    const data = { repositories: [] };
+    class Sessions {
+        async ensure(input) {
+            calls.ensure.push(input);
+            if (options.conflictingSession)
+                throw new Error('session identity differs');
+            return {
+                status: 'created',
+                session: { data, archivedAt: options.archived ? '2026-01-01T00:00:00.000Z' : null },
+            };
+        }
+        async patch(input) {
+            calls.patch.push(input);
+            data.repositories = input.data.repositories;
+        }
+        async list() { }
+        async get() {
+            return options.conflictingSession;
+        }
+        async archive(sessionId) {
+            calls.archive.push(sessionId);
+        }
+    }
+    if (options.omitArchive)
+        delete Sessions.prototype.archive;
+    class Entries {
+        async append(input) {
+            calls.append.push(input);
+            const entry = {
+                createdAt: `2026-01-01T00:00:${String(stored.length).padStart(2, '0')}.000Z`,
+                data: input.data,
+            };
+            stored.push(entry);
+            return entry;
+        }
+        async *get() {
+            if (options.entriesError !== undefined)
+                throw options.entriesError;
+            yield* stored;
+        }
+    }
+    class Snapshots {
+        async export(input) {
+            calls.export.push(input);
+            return 'exportResult' in options ? options.exportResult : SNAPSHOT;
+        }
+    }
+    const module = {
+        Sessions,
+        Entries,
+        ...(options.omitSnapshots ? {} : { Snapshots }),
+    };
+    return { dependencies: { loadClient: async () => module }, calls, stored };
+}

package/dist/mcp-server/git-fixture.test-helpers.d.mts

@@ -0,0 +1,16 @@
+export type RepoFixture = {
+    /** Real path of the directory holding every repository below. */
+    root: string;
+    /** The primary worktree of the launch repository. */
+    main: string;
+    /** A linked worktree of the launch repository. */
+    linked: string;
+    /** A separate repository created with `git init`. */
+    outside: string;
+    /** A symlink that points at `linked`. */
+    alias: string;
+    git: (cwd: string, ...args: string[]) => string;
+    cleanup: () => void;
+};
+/** Two real repositories under the OS tmpdir: one with a linked worktree, one unrelated. */
+export declare function createRepoFixture(): RepoFixture;

package/dist/mcp-server/git-fixture.test-helpers.mjs

@@ -0,0 +1,35 @@
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { gitEnv } from '../shared-context/index.mjs';
+const IDENTITY = ['-c', 'user.name=Test', '-c', 'user.email=test@example.test'];
+/** Two real repositories under the OS tmpdir: one with a linked worktree, one unrelated. */
+export function createRepoFixture() {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), 'vouchington-mcp-')));
+    const git = (cwd, ...args) => execFileSync('git', [...IDENTITY, '-C', cwd, ...args], {
+        encoding: 'utf8',
+        env: gitEnv(),
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const main = join(root, 'main');
+    const linked = join(root, 'linked');
+    const outside = join(root, 'outside');
+    const alias = join(root, 'alias');
+    mkdirSync(main);
+    git(main, 'init', '--quiet');
+    git(main, 'commit', '--quiet', '--allow-empty', '-m', 'initial');
+    git(main, 'worktree', 'add', '--quiet', '-b', 'linked', linked);
+    mkdirSync(outside);
+    git(outside, 'init', '--quiet');
+    symlinkSync(linked, alias);
+    return {
+        root,
+        main,
+        linked,
+        outside,
+        alias,
+        git,
+        cleanup: () => rmSync(root, { recursive: true, force: true }),
+    };
+}

package/dist/mcp-server/handlers-journal.d.mts

@@ -0,0 +1,6 @@
+import { type ToolHandler } from './context.mts';
+export declare const journalAppend: ToolHandler;
+/** Every entry as the client returns it, oldest first. Nothing is filtered or rewritten. */
+export declare const journalEntries: ToolHandler;
+export declare const outboxStatus: ToolHandler;
+export declare const outboxFlush: ToolHandler;

package/dist/mcp-server/handlers-journal.mjs

@@ -0,0 +1,98 @@
+import { appendJournalMarkdown, feedbackOutboxStatus, flushFeedbackOutbox, readJournal, } from '../agent-blackboard/index.mjs';
+import { optionalRecord, optionalString, requiredChoice, requiredString, requiredStringArray, rejectUnknown, } from './args.mjs';
+import { outboxDirectory, readIdentity } from './context.mjs';
+const MODES = ['interactive', 'autonomous'];
+const OUTCOMES = [
+    'in-progress',
+    'success',
+    'failure',
+    'cancelled',
+    'timed-out',
+    'no-change',
+    'policy-refusal',
+    'unknown',
+];
+const COVERAGE_STATUSES = [
+    'complete',
+    'partial',
+    'unavailable',
+    'not-assessed',
+    'not-started',
+];
+function readCoverage(args) {
+    const coverage = optionalRecord(args, 'feedbackCoverage');
+    if (coverage === undefined)
+        throw new Error('feedbackCoverage is required');
+    rejectUnknown(coverage, ['status', 'sources', 'droppedCount']);
+    const droppedCount = coverage.droppedCount ?? 0;
+    if (typeof droppedCount !== 'number' || !Number.isSafeInteger(droppedCount) || droppedCount < 0)
+        throw new Error('feedbackCoverage.droppedCount must be a non-negative integer');
+    const sources = coverage.sources ?? [];
+    if (!Array.isArray(sources) || sources.some((source) => typeof source !== 'string'))
+        throw new Error('feedbackCoverage.sources must be an array of strings');
+    return {
+        status: requiredChoice(coverage, 'status', COVERAGE_STATUSES),
+        sources: sources,
+        droppedCount,
+    };
+}
+export const journalAppend = async (args, context) => {
+    const identity = readIdentity(args, context.sessionId);
+    const mode = requiredChoice(args, 'mode', MODES);
+    // The envelope includes the timestamp, so a retry of one sourceEventId must reuse it. Fixing the
+    // default here and returning it lets the caller do that.
+    const timestamp = optionalString(args, 'timestamp') ?? new Date().toISOString();
+    const category = optionalString(args, 'category');
+    const result = await appendJournalMarkdown({
+        ...identity,
+        mode,
+        // Interactive delivery needs a durable outbox; autonomous delivery forbids one.
+        ...(mode === 'interactive' ? { outboxDirectory: outboxDirectory(context.worktree) } : {}),
+        markdown: requiredString(args, 'markdown'),
+        sourceEventId: requiredString(args, 'sourceEventId'),
+        workOutcome: requiredChoice(args, 'workOutcome', OUTCOMES),
+        repositories: requiredStringArray(args, 'repositories'),
+        feedbackCoverage: readCoverage(args),
+        timestamp,
+        ...(category === undefined ? {} : { category }),
+        env: context.env,
+        dependencies: context.dependencies,
+    });
+    return { sessionId: context.sessionId, timestamp, ...result };
+};
+// `Entries.get` documents no order, and `createdAt` is a service-generated ISO 8601 UTC time whose
+// text order is time order. An entry without a usable `createdAt` sorts first rather than throwing.
+function createdAtOf(entry) {
+    const createdAt = entry?.createdAt;
+    return typeof createdAt === 'string' ? createdAt : '';
+}
+function byCreatedAt(left, right) {
+    const leftAt = createdAtOf(left);
+    const rightAt = createdAtOf(right);
+    if (leftAt === rightAt)
+        return 0;
+    return leftAt < rightAt ? -1 : 1;
+}
+/** Every entry as the client returns it, oldest first. Nothing is filtered or rewritten. */
+export const journalEntries = async (_args, context) => ({
+    sessionId: context.sessionId,
+    entries: (await readJournal(context.sessionId, context.env, context.dependencies)).toSorted(byCreatedAt),
+});
+export const outboxStatus = async (_args, context) => ({
+    sessionId: context.sessionId,
+    ...feedbackOutboxStatus(outboxDirectory(context.worktree)),
+});
+export const outboxFlush = async (_args, context) => {
+    const directory = outboxDirectory(context.worktree);
+    // Flushing creates the outbox directory, so an empty or absent outbox is reported as is.
+    if (feedbackOutboxStatus(directory).pendingCount === 0)
+        return { sessionId: context.sessionId, status: 'empty', pendingCount: 0, deliveredCount: 0 };
+    return {
+        sessionId: context.sessionId,
+        ...(await flushFeedbackOutbox({
+            directory,
+            env: context.env,
+            dependencies: context.dependencies,
+        })),
+    };
+};

package/dist/mcp-server/handlers-session.d.mts

@@ -0,0 +1,4 @@
+import { type ToolHandler } from './context.mts';
+export declare const sessionEnsure: ToolHandler;
+export declare const sessionArchive: ToolHandler;
+export declare const snapshotExport: ToolHandler;

package/dist/mcp-server/handlers-session.mjs

@@ -0,0 +1,47 @@
+import { archiveBlackboardSession, ensureBlackboardSession, exportSnapshot, } from '../agent-blackboard/index.mjs';
+import { optionalRecord, optionalString, requiredNullableString } from './args.mjs';
+import { readIdentity } from './context.mjs';
+function readSelection(args) {
+    const data = optionalRecord(args, 'data');
+    const arrays = optionalRecord(args, 'dataArrayContains');
+    const inactiveForHours = args.inactiveForHours;
+    if (inactiveForHours !== undefined &&
+        (typeof inactiveForHours !== 'number' || !(inactiveForHours > 0)))
+        throw new Error('inactiveForHours must be a positive number');
+    if (arrays !== undefined && Object.values(arrays).some((value) => typeof value !== 'string'))
+        throw new Error('dataArrayContains must contain only string values');
+    const agent = optionalString(args, 'agent');
+    const version = optionalString(args, 'version');
+    return {
+        ...(agent === undefined ? {} : { agent }),
+        ...(version === undefined ? {} : { version }),
+        ...(args.parentSessionId === undefined
+            ? {}
+            : { parentSessionId: requiredNullableString(args, 'parentSessionId') }),
+        ...(data === undefined ? {} : { data }),
+        ...(arrays === undefined ? {} : { dataArrayContains: arrays }),
+        ...(inactiveForHours === undefined ? {} : { inactiveForHours }),
+    };
+}
+export const sessionEnsure = async (args, context) => ensureBlackboardSession({
+    ...readIdentity(args, context.sessionId),
+    env: context.env,
+    dependencies: context.dependencies,
+});
+export const sessionArchive = async (_args, context) => archiveBlackboardSession({
+    sessionId: context.sessionId,
+    env: context.env,
+    dependencies: context.dependencies,
+});
+export const snapshotExport = async (args, context) => {
+    const selection = readSelection(args);
+    return {
+        sessionId: context.sessionId,
+        ...(await exportSnapshot({
+            // An empty selection means "everything"; leave it unset rather than send an empty filter.
+            ...(Object.keys(selection).length === 0 ? {} : { selection }),
+            env: context.env,
+            dependencies: context.dependencies,
+        })),
+    };
+};

package/dist/mcp-server/harness.test-helpers.d.mts

@@ -0,0 +1,33 @@
+import { type ToolCallResult } from './dispatch.mts';
+import { type FakeBlackboard, type FakeOptions } from './fake-blackboard.test-helpers.mts';
+import { type RepoFixture } from './git-fixture.test-helpers.mts';
+/** A fresh pair of real repositories for every test. */
+export declare function useRepoFixture(): () => RepoFixture;
+export declare function outboxPath(worktree: string): string;
+export type Harness = {
+    fake: FakeBlackboard;
+    call: (name: string, args?: unknown) => Promise<ToolCallResult>;
+};
+/** Calls tools against a repository fixture with the blackboard client faked. */
+export declare function harness(fixture: RepoFixture, options?: FakeOptions & {
+    env?: NodeJS.ProcessEnv;
+}): Harness;
+export declare function textOf(result: ToolCallResult): string;
+export declare function jsonOf(result: ToolCallResult): Record<string, unknown>;
+export declare const JOURNAL_ARGS: {
+    sessionId: string;
+    parentSessionId: null;
+    agent: string;
+    version: string;
+    mode: string;
+    markdown: string;
+    sourceEventId: string;
+    workOutcome: string;
+    repositories: string[];
+    feedbackCoverage: {
+        status: string;
+        sources: string[];
+        droppedCount: number;
+    };
+    timestamp: string;
+};