vouchington-tooling 0.30.0 → 0.32.0

package/README.md

@@ -455,6 +455,8 @@ Version one recognizes literal-key `apiResponse`, `apiNoContent`, `apiOpenApiRaw
 `ctx.pipeline`, `ctx.response.empty/buffer/xml`, `ctx.request.json/buffer`, `parseJsonBody`,
 `ctx.setStatus`, and static `Content-Type` setters. The input source files and TypeScript checker
 are the source representation; the adapter does not parse or discover a repository on its own.
+Reading the handler context in another object's computed assignment key preserves its binding;
+assignments or updates to the context itself, including side effects inside that key, still reject it.
 
 Error-only 405 routes require a terminal throw on the handler's own context. Named handlers and
 imported wrappers are followed through compiler declarations; conditional, caught, recursive,
@@ -506,6 +508,8 @@ A status setter must dominate each body emission, including separate branches; c
 aliases are followed, assigned mutable context aliases and object-literal context wrappers fail closed,
 and helper parameters must resolve to the registered caller's unchanged response context.
 Helper-owned contracts also account for response emissions in their proven caller scopes.
+Feasible assignments or deletions of response methods through canonical context aliases invalidate
+that dispatch evidence; dead, ignored, or unrelated method mutations preserve the contract.
 Indirect response `call`, `apply`, and `bind` forms fail closed, including borrowed context receivers.
 SSE frames and branded content variants reject body-forbidden 1xx, 204, 205, and 304 statuses.
 Literal bracket response methods have the same emission checks as property methods. Unrelated raw emissions
@@ -592,9 +596,11 @@ for minimizing summaries and excluding raw logs, transcripts, environment dumps,
 secrets. A bound violation fails visibly without clipping findings.
 
 `writeFeedback({identity, envelope, mode, ...})` accepts an exact caller-owned session identity and
-never manufactures native agent identities. Interactive mode requires an absolute private outbox
-directory. The writer persists before transport with atomic rename, file/directory fsync, a stable
-record path, and owner-only permissions. The outbox holds at most 128 records and 2 MB. Saturation,
+never manufactures native agent identities. Interactive mode requires an absolute outbox
+directory. Ancestor ownership and permissions are not checked; existing directory and record modes
+are accepted. New directories and files default to `0700` and `0600`. The outbox itself must be a
+real directory, and records must be regular files. The writer persists before transport with atomic
+rename, file/directory fsync, and a stable record path. The outbox holds at most 128 records and 2 MB. Saturation,
 corruption, or persistence failure blocks capture and preserves unsent records. Delivered records
 are removed only after matching readback. Pending state includes count and a safe diagnostic;
 interactive CLI exit zero means durable retention, and callers must inspect the printed status to

package/bin/node-guard.mjs

@@ -0,0 +1,9 @@
+// Plain JavaScript on purpose: the bin shims import this first, and it must parse and run on old
+// Node releases so the version check can report a clear error before any TypeScript output loads.
+const REQUIRED_MAJOR = 24
+
+/** One stderr line when `found` is older than the supported Node, otherwise undefined. */
+export function unsupportedNodeMessage(found = process.versions.node) {
+  if (Number(found.split('.')[0]) >= REQUIRED_MAJOR) return undefined
+  return `vouchington requires Node >=${REQUIRED_MAJOR} (found ${found})\n`
+}

package/bin/vouchington-mcp.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// The stable entry point of the MCP server: `<node> <install>/node_modules/vouchington-tooling/bin/
+// vouchington-mcp.mjs`. It takes no arguments and skips CLI argument parsing, so a CLI refactor
+// cannot move it. Plain JavaScript on purpose: the Node version check runs before anything else.
+// ES2015 syntax only (no `??`, `?.`, or top-level await) so this file parses on every Node that can
+// load a `.mjs` at all (12.17+), and the message prints there. Older Node cannot load `.mjs`.
+import { unsupportedNodeMessage } from './node-guard.mjs'
+
+const unsupported = unsupportedNodeMessage()
+if (unsupported === undefined) {
+  import('../dist/mcp-server/main.mjs')
+    .then((main) => main.runMcpMain())
+    .catch((error) => {
+      process.stderr.write(String((error && error.stack) || error) + '\n')
+      process.exitCode = 1
+    })
+} else {
+  process.stderr.write(unsupported)
+  process.exitCode = 1
+}

package/bin/vouchington.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Plain JavaScript on purpose: the Node version check runs before any TypeScript output loads.
+// ES2015 syntax only (no `??`, `?.`, or top-level await) so this file parses on every Node that can
+// load a `.mjs` at all (12.17+), and the message prints there. Older Node cannot load `.mjs`.
+import { unsupportedNodeMessage } from './node-guard.mjs'
+
+const unsupported = unsupportedNodeMessage()
+if (unsupported === undefined) {
+  import('../dist/cli/index.mjs')
+    .then((main) => main.runMain())
+    .catch((error) => {
+      process.stderr.write(String((error && error.stack) || error) + '\n')
+      process.exitCode = 1
+    })
+} else {
+  process.stderr.write(unsupported)
+  process.exitCode = 1
+}

package/dist/agent-blackboard/feedback-outbox-counts.d.mts

@@ -0,0 +1,5 @@
+/** Counts a session separately from all retry records in the shared worktree outbox. */
+export declare function feedbackOutboxCounts(directory: string, sessionId: string): {
+    pendingCount: number;
+    worktreePendingCount: number;
+};

package/dist/agent-blackboard/feedback-outbox-counts.mjs

@@ -0,0 +1,11 @@
+import { assertSessionId } from './session-id.mjs';
+import { readFeedbackOutbox } from './feedback-outbox.mjs';
+/** Counts a session separately from all retry records in the shared worktree outbox. */
+export function feedbackOutboxCounts(directory, sessionId) {
+    assertSessionId(sessionId);
+    const records = readFeedbackOutbox(directory);
+    return {
+        pendingCount: records.filter((record) => record.identity.sessionId === sessionId).length,
+        worktreePendingCount: records.length,
+    };
+}

package/dist/agent-blackboard/feedback-outbox-directory.d.mts

@@ -0,0 +1,2 @@
+/** The outbox is temporary retry state; ancestor ownership and modes do not govern it. */
+export declare function ensureOutboxDirectory(directory: string, create: boolean): boolean;

package/dist/agent-blackboard/feedback-outbox-directory.mjs

@@ -0,0 +1,16 @@
+import { lstatSync, mkdirSync } from 'node:fs';
+/** The outbox is temporary retry state; ancestor ownership and modes do not govern it. */
+export function ensureOutboxDirectory(directory, create) {
+    if (create)
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+    try {
+        if (!lstatSync(directory).isDirectory())
+            throw new Error(`feedback outbox must be a directory: ${directory}`);
+        return true;
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}

package/dist/agent-blackboard/feedback-outbox.mjs

@@ -2,7 +2,7 @@ import { canonicalFeedback, canonicalFeedbackEvent } from './feedback-canonical.
 import { createHash, randomUUID } from 'node:crypto';
 import { closeSync, constants, fsyncSync, fstatSync, openSync, readdirSync, renameSync, unlinkSync, } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
-import { ensurePrivateDirectory } from '../session-friction/directory.mjs';
+import { ensureOutboxDirectory } from './feedback-outbox-directory.mjs';
 import { withFileLock } from '../session-friction/lock.mjs';
 import { openLogFile, readLogContent, writeAll } from '../session-friction/log-file.mjs';
 import { validateFeedbackEnvelope } from './feedback-codec.mjs';
@@ -13,9 +13,9 @@ const FEEDBACK_OUTBOX_MAX_BYTES = 2_000_000;
 const RECORD_MAX_BYTES = 18_000;
 function outboxDirectory(directory, create) {
     if (typeof directory !== 'string' || directory.length > 4096 || !isAbsolute(directory))
-        throw new Error('feedback outbox requires an absolute private directory');
+        throw new Error('feedback outbox requires an absolute directory');
     const path = resolve(directory);
-    ensurePrivateDirectory(path, create);
+    ensureOutboxDirectory(path, create);
     return path;
 }
 function filename(record) {
@@ -27,8 +27,6 @@ function readRecord(path) {
     const descriptor = openLogFile(path, constants.O_RDONLY);
     try {
         const status = fstatSync(descriptor);
-        if ((status.mode & 0o777) !== 0o600 || status.uid !== process.geteuid?.())
-            throw new Error('feedback outbox record must be private and owned by caller');
         const bytes = status.size;
         if (bytes > RECORD_MAX_BYTES)
             throw new Error('feedback outbox record is too large');
@@ -72,7 +70,7 @@ function syncDirectory(directory) {
 }
 export function feedbackOutboxStatus(directory) {
     const path = outboxDirectory(directory, false);
-    if (!ensurePrivateDirectory(path, false))
+    if (!ensureOutboxDirectory(path, false))
         return { status: 'empty', pendingCount: 0 };
     return withFileLock(join(path, '.records'), () => {
         const pendingCount = records(path).length;
@@ -86,7 +84,7 @@ export function listFeedbackOutbox(directory) {
 /** Reads the retained records without creating the outbox directory. */
 export function readFeedbackOutbox(directory) {
     const path = outboxDirectory(directory, false);
-    if (!ensurePrivateDirectory(path, false))
+    if (!ensureOutboxDirectory(path, false))
         return [];
     return withFileLock(join(path, '.records'), () => records(path).map((item) => item.record));
 }

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

@@ -24,3 +24,4 @@ export { composeRetrospective } from './feedback-compose.mts';
 export type { RetrospectiveCompositionInput, FeedbackAssessment } from './feedback-compose.mts';
 export type { JournalAuditOptions } from './feedback-journal-audit.mts';
 export type { JournalEntry, JournalLoader, JournalLoadResult } from '../session-friction/types.mts';
+export { feedbackOutboxCounts } from './feedback-outbox-counts.mts';

package/dist/agent-blackboard/index.mjs

@@ -63,3 +63,4 @@ export { createFeedbackEnvelope, validateFeedbackEnvelope } from './feedback-cod
 export { writeFeedback, verifyFreshFeedback, flushFeedbackOutbox, FeedbackDeliveryError, } from './feedback-delivery.mjs';
 export { feedbackOutboxStatus, readFeedbackOutbox } from './feedback-outbox.mjs';
 export { composeRetrospective } from './feedback-compose.mjs';
+export { feedbackOutboxCounts } from './feedback-outbox-counts.mjs';

package/dist/api-contract-discovery/protocol-http-association.mjs

@@ -8,6 +8,7 @@ import { unsupportedContextAlias } from './protocol-context-alias.mjs';
 import { expressionReceiver } from './protocol-write-receiver.mjs';
 import { visit } from './response-contract-route-analysis.mjs';
 import { isSupportedProtocolCallback } from './protocol-callback-invocation.mjs';
+import { mutatesHttpResponseMethod } from './protocol-http-method-mutations.mjs';
 import { opaqueProtocolCallbackPath } from './protocol-opaque-callback.mjs';
 const responseMethods = new Set([
     'setStatus',
@@ -26,6 +27,8 @@ export function associateHttpResponse(call, response, checker, siblings) {
     const emissions = new Map();
     for (const [scope, context] of httpContextScopes(handler, checker))
         visit(scope, (node) => {
+            if (mutatesHttpResponseMethod(node, context, checker))
+                throw new Error('HTTP response context method is mutated');
             if (ts.isCallExpression(node) &&
                 executableProtocolPath(node, checker) &&
                 responseMethods.has(indirectHttpResponseMethod(node, context, checker) ?? ''))

package/dist/api-contract-discovery/protocol-http-method-mutations.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** A feasible write through a canonical context alias invalidates response dispatch evidence. */
+export declare function mutatesHttpResponseMethod(node: ts.Node, context: ts.Symbol, checker: ts.TypeChecker): boolean;

package/dist/api-contract-discovery/protocol-http-method-mutations.mjs

@@ -0,0 +1,31 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { contextResponseMethod } from './protocol-http-context.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { opaqueProtocolCallbackPath } from './protocol-opaque-callback.mjs';
+const responseMethods = new Set([
+    'setStatus',
+    'pipeline',
+    'json',
+    'response',
+    'response.buffer',
+    'response.empty',
+]);
+/** A feasible write through a canonical context alias invalidates response dispatch evidence. */
+export function mutatesHttpResponseMethod(node, context, checker) {
+    let target;
+    if (ts.isBinaryExpression(node) &&
+        node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+        node.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+        target = node.left;
+    if (ts.isDeleteExpression(node))
+        target = node.expression;
+    if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+        (node.operator === ts.SyntaxKind.PlusPlusToken ||
+            node.operator === ts.SyntaxKind.MinusMinusToken))
+        target = node.operand;
+    if (!target ||
+        !responseMethods.has(contextResponseMethod(unwrapExpression(target), context, checker, true) ?? ''))
+        return false;
+    return executableProtocolPath(node, checker) || opaqueProtocolCallbackPath(node, checker);
+}

package/dist/api-contract-discovery/registered-route-binding-writes.mjs

@@ -8,6 +8,14 @@ export function hasBindingWrite(declaration, checker) {
     const binding = checker.getSymbolAtLocation(declaration.name);
     let written = false;
     const referencesBinding = (node) => {
+        // Index expressions and computed property names read their keys, not write them.
+        // inspect still visits these expressions separately to detect nested side-effect writes.
+        if (ts.isComputedPropertyName(node))
+            return;
+        if (ts.isElementAccessExpression(node)) {
+            referencesBinding(node.expression);
+            return;
+        }
         if (ts.isIdentifier(node) && checker.getSymbolAtLocation(node) === binding)
             written = true;
         node.forEachChild(referencesBinding);

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

@@ -0,0 +1,4 @@
+export declare function flagsToValues(flags: string[]): Record<string, string>;
+export declare function assertAllowed(values: Record<string, string>, allowed: string[]): void;
+export declare function required(values: Record<string, string>, key: string): string;
+export declare function validatedSessionId(sessionId: string | undefined): string | undefined;

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

@@ -0,0 +1,34 @@
+import { assertSessionId } from '../../agent-blackboard/session-id.mjs';
+export 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;
+}
+export function assertAllowed(values, allowed) {
+    for (const key of Object.keys(values))
+        if (!allowed.includes(key))
+            throw new Error(`unknown option: --${key}`);
+}
+export function required(values, key) {
+    const value = values[key];
+    if (!value)
+        throw new Error(`--${key} is required`);
+    return value;
+}
+export function validatedSessionId(sessionId) {
+    if (sessionId !== undefined) {
+        assertSessionId(sessionId);
+        if (sessionId.length > 256)
+            throw new Error('session identity is too long');
+    }
+    return sessionId;
+}

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

@@ -1,5 +1,7 @@
-import { appendJournal, flushFeedbackOutbox, formatJournalEntries, probeBlackboard, readJournal, } from '../../agent-blackboard/index.mjs';
+import { assertAllowed, flagsToValues, required, validatedSessionId, } from './agent-blackboard-flags.mjs';
+import { appendJournal, feedbackOutboxCounts, flushFeedbackOutbox, formatJournalEntries, probeBlackboard, readJournal, } from '../../agent-blackboard/index.mjs';
 import { cleanupSnapshotPartitions, partitionSnapshot } from '../../agent-blackboard/snapshot.mjs';
+const dependencies = { resolveFrom: import.meta.url };
 let journalReader = readJournal;
 export function setJournalReaderForTest(reader) {
     journalReader = reader ?? readJournal;
@@ -8,14 +10,14 @@ export async function runAgentBlackboardCommand(args) {
     try {
         const [command, ...rest] = args;
         if (command === 'probe' && rest.length === 0) {
-            await probeBlackboard();
+            await probeBlackboard(undefined, dependencies);
             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|flush | snapshot partition|cleanup');
+        throw new Error('usage: agent-blackboard probe | journal append|entries|flush|status | snapshot partition|cleanup');
     }
     catch (error) {
         process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
@@ -53,10 +55,20 @@ async function runJournal(args) {
     const [action, ...flags] = args;
     const { repositories, remaining } = action === 'append' ? extractRepositories(flags) : { repositories: [], remaining: flags };
     const values = flagsToValues(remaining);
-    if (action === 'flush') {
-        assertAllowed(values, ['outbox-directory']);
-        const result = await flushFeedbackOutbox({ directory: required(values, 'outbox-directory') });
-        process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (action === 'flush' || action === 'status') {
+        assertAllowed(values, ['outbox-directory', 'session-id']);
+        const directory = required(values, 'outbox-directory');
+        const sessionId = validatedSessionId(action === 'status' ? required(values, 'session-id') : values['session-id']);
+        const result = action === 'flush'
+            ? await flushFeedbackOutbox({ directory, dependencies })
+            : { pendingCount: 0 };
+        const counts = sessionId !== undefined ? feedbackOutboxCounts(directory, sessionId) : result;
+        process.stdout.write(`${JSON.stringify({
+            ...result,
+            ...counts,
+            sessionId,
+            status: counts.pendingCount ? 'pending' : 'empty',
+        })}\n`);
         return 0;
     }
     if (action === 'entries') {
@@ -64,7 +76,7 @@ async function runJournal(args) {
         const sessionId = required(values, 'session-id');
         let entries;
         try {
-            entries = await journalReader(sessionId);
+            entries = await journalReader(sessionId, undefined, dependencies);
         }
         catch (error) {
             if (!isNotFound(error))
@@ -91,6 +103,7 @@ async function runJournal(args) {
             'outbox-directory',
         ]);
         const result = await appendJournal({
+            dependencies,
             mode: required(values, 'mode'),
             sourceEventId: required(values, 'source-event-id'),
             workOutcome: required(values, 'work-outcome'),
@@ -108,10 +121,14 @@ async function runJournal(args) {
             ...('timestamp' in values ? { timestamp: values.timestamp } : {}),
             parentSessionId: values['parent-session-id'] ?? null,
         });
-        process.stdout.write(`${JSON.stringify(result)}\n`);
+        // Autonomous mode has no outbox, so its receipt must not depend on one.
+        const counts = values.mode === 'autonomous'
+            ? { pendingCount: 0, worktreePendingCount: 0 }
+            : feedbackOutboxCounts(required(values, 'outbox-directory'), required(values, 'session-id'));
+        process.stdout.write(`${JSON.stringify({ ...result, ...counts })}\n`);
         return 0;
     }
-    throw new Error('usage: agent-blackboard journal append|entries|flush');
+    throw new Error('usage: agent-blackboard journal append|entries|flush|status');
 }
 function extractRepositories(flags) {
     const repositories = [];
@@ -133,31 +150,6 @@ function requiredRepositories(repositories) {
         throw new Error('--repository is required');
     return repositories;
 }
-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 &&

package/dist/cli/index.d.mts

@@ -1,3 +1,5 @@
 #!/usr/bin/env node
 export declare function runCli(argv?: readonly string[]): number | Promise<number>;
 export declare function isMainModule(metaUrl: string, argv1: string | undefined): boolean;
+/** Runs the CLI and records its exit code. `bin/vouchington.mjs` calls this after its Node check. */
+export declare function runMain(argv?: readonly string[], run?: typeof runCli): Promise<void>;

package/dist/cli/index.mjs

@@ -159,17 +159,17 @@ export function isMainModule(metaUrl, argv1) {
         return metaUrl === pathToFileURL(resolve(argv1)).href;
     }
 }
-/* v8 ignore next 8 */
-if (isMainModule(import.meta.url, process.argv[1])) {
-    const result = runCli();
-    if (typeof result === 'number')
-        process.exitCode = result;
-    else {
-        result.then((code) => {
-            process.exitCode = code;
-        }, (error) => {
-            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-            process.exitCode = 1;
-        });
+/** Runs the CLI and records its exit code. `bin/vouchington.mjs` calls this after its Node check. */
+export async function runMain(argv = process.argv, run = runCli) {
+    try {
+        process.exitCode = await run(argv);
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
     }
 }
+/* v8 ignore next 3 */
+if (isMainModule(import.meta.url, process.argv[1])) {
+    void runMain();
+}

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  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  gha-collaborator-trust        Classify authors as write-access collaborators or not\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\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>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\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 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  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  gha-collaborator-trust        Classify authors as write-access collaborators or not\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\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>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\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 status --session-id UUID --outbox-directory PATH\nagent-blackboard journal flush --outbox-directory PATH [--session-id UUID]\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

@@ -118,7 +118,8 @@ retrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME]
 agent-blackboard probe
 agent-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]
 agent-blackboard journal entries --session-id UUID
-agent-blackboard journal flush --outbox-directory PATH
+agent-blackboard journal status --session-id UUID --outbox-directory PATH
+agent-blackboard journal flush --outbox-directory PATH [--session-id UUID]
 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]

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

@@ -1,9 +1,12 @@
 import type { BlackboardClientDependencies } from '../agent-blackboard/client.mts';
 import type { RunTextCommand } from '../gh-cli/exec.mts';
 export type ServerEnvironment = {
-    launchRoot: string;
+    /** The launch directory's worktree top level, or undefined when it is not inside one. */
+    launchRoot: string | undefined;
     env: NodeJS.ProcessEnv;
     runGit: RunTextCommand;
+    /** Test seam: where `agent-blackboard` resolves from. Defaults to this package's own module. */
+    resolveFrom?: string | URL;
     /** Test seam: replaces how the consumer's `agent-blackboard` client is loaded. */
     blackboard?: BlackboardClientDependencies;
 };

package/dist/mcp-server/dispatch.mjs

@@ -1,4 +1,3 @@
-import { join } from 'node:path';
 import { FeedbackDeliveryError } from '../agent-blackboard/index.mjs';
 import { optionalString, rejectUnknown, requireObject } from './args.mjs';
 import { readSessionId } from './context.mjs';
@@ -23,7 +22,7 @@ const DIAGNOSTIC_HINTS = {
     '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',
+    'client-unavailable': 'agent-blackboard is not installed next to vouchington-tooling',
     'readback-unconfirmed': 'the write could not be confirmed; retry the same call (same sourceEventId and content)',
     'delivery-timeout': 'delivery timed out; retry the same call (same sourceEventId and content)',
 };
@@ -52,8 +51,11 @@ export async function callTool(name, rawArguments, environment) {
             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') },
+            // The client resolves from this package's install, like the SDK, never from the worktree.
+            dependencies: {
+                ...environment.blackboard,
+                resolveFrom: environment.resolveFrom ?? import.meta.url,
+            },
         });
         return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     }

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

@@ -1,16 +1,11 @@
-import { flushFeedbackOutbox, readFeedbackOutbox } from '../agent-blackboard/index.mjs';
+import { flushFeedbackOutbox, feedbackOutboxCounts } from '../agent-blackboard/index.mjs';
 import { outboxDirectory } from './context.mjs';
 /**
  * The outbox belongs to the worktree, not to one session, so two counts are reported. `pendingCount`
  * is the caller's session only; `worktreePendingCount` is every session's records.
  */
 export function outboxCounts(worktree, sessionId) {
-    // A read that never creates the directory, so asking about an empty outbox leaves no trace.
-    const records = readFeedbackOutbox(outboxDirectory(worktree));
-    return {
-        pendingCount: records.filter((record) => record.identity.sessionId === sessionId).length,
-        worktreePendingCount: records.length,
-    };
+    return feedbackOutboxCounts(outboxDirectory(worktree), sessionId);
 }
 function sessionStatus(pendingCount) {
     return pendingCount === 0 ? 'empty' : 'pending';

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

@@ -11,6 +11,7 @@ export type Harness = {
 /** Calls tools against a repository fixture with the blackboard client faked. */
 export declare function harness(fixture: RepoFixture, options?: FakeOptions & {
     env?: NodeJS.ProcessEnv;
+    launchRoot?: string | undefined;
 }): Harness;
 export declare function textOf(result: ToolCallResult): string;
 export declare function jsonOf(result: ToolCallResult): Record<string, unknown>;

package/dist/mcp-server/harness.test-helpers.mjs

@@ -20,7 +20,7 @@ export function outboxPath(worktree) {
 export function harness(fixture, options = {}) {
     const fake = fakeBlackboard(options);
     const environment = {
-        launchRoot: fixture.main,
+        launchRoot: 'launchRoot' in options ? options.launchRoot : fixture.main,
         env: options.env ?? BLACKBOARD_ENV,
         runGit: runIsolatedGit,
         blackboard: fake.dependencies,

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

@@ -0,0 +1,5 @@
+/**
+ * Entry of `bin/vouchington-mcp.mjs`: starts the server without parsing CLI arguments and records
+ * the exit code. The open stdin keeps the process alive after a successful start.
+ */
+export declare function runMcpMain(): Promise<void>;

package/dist/mcp-server/main.mjs

@@ -0,0 +1,8 @@
+import { runMcpCommand } from '../cli/commands/mcp.mjs';
+/**
+ * Entry of `bin/vouchington-mcp.mjs`: starts the server without parsing CLI arguments and records
+ * the exit code. The open stdin keeps the process alive after a successful start.
+ */
+export async function runMcpMain() {
+    process.exitCode = await runMcpCommand([]);
+}

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

@@ -10,6 +10,8 @@ export type RunMcpServerOptions = {
     runGit?: RunTextCommand;
     /** Defaults to stdio. Tests pass one half of an in-memory pair. */
     transport?: Transport;
+    /** Test seam: where the startup check looks for `agent-blackboard`. Defaults to this module. */
+    resolveFrom?: string | URL;
     /** Test seam: replaces how the consumer's `agent-blackboard` client is loaded. */
     blackboard?: BlackboardClientDependencies;
 };