vouchington-tooling 0.29.0 → 0.31.0

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  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\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>...\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

@@ -3,7 +3,6 @@ export const USAGE = `Usage: vouchington <command> [options]
 Commands:
   runner-port-policy   Print or validate a runner port policy
   with-host-lock       Run a command under a host-wide lock
-  agent-harness-config          Apply classifier-auto + sandbox keys to agent harnesses
   gha-runtime-audit             Audit successful GitHub Actions job runtimes
   require-up-to-date            Require HEAD to include a fetched remote branch
   gitleaks-directory-scan       Scan a directory with Gitleaks
@@ -66,10 +65,6 @@ with-host-lock
   [--on-acquire-timeout fail|run-unlocked]
   -- <command> [args...]
 
-agent-harness-config dump
-agent-harness-config check|apply [--global] [--repo PATH]... [--harness claude|codex|grok|cursor]...
-  [--home PATH]
-
 gha-runtime-audit
   [--repository owner/name]   Default GITHUB_REPOSITORY
   [--branch main]
@@ -123,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/contract-schema/contract-schema-bounded-array.d.mts

@@ -9,7 +9,5 @@ export type ExtractionContext = {
     options: ExtractContractSchemaOptions;
 };
 type SchemaForType = (type: ts.Type, context: ExtractionContext) => ContractSchemaNode;
-export declare function boundedArraySchema(type: ts.Type, context: ExtractionContext, schemaForType: SchemaForType): Extract<ContractSchemaNode, {
-    type: 'array';
-}> | undefined;
+export declare function boundedArraySchema(type: ts.Type, context: ExtractionContext, schemaForType: SchemaForType): ContractSchemaNode | undefined;
 export {};

package/dist/contract-schema/contract-schema-bounded-array.mjs

@@ -16,6 +16,11 @@ export function boundedArraySchema(type, context, schemaForType) {
     if (!(uniqueItemsType.flags & ts.TypeFlags.BooleanLiteral)) {
         throw unsupportedType(type, context.checker, `${alias} uniqueness must be literal`);
     }
+    if (itemType.flags & ts.TypeFlags.Never) {
+        if (minItems !== 0)
+            throw unsupportedType(type, context.checker, `${alias} has impossible never element bounds`);
+        return { type: 'tuple', items: [], optionalItems: 0 };
+    }
     return {
         type: 'array',
         items: schemaForType(itemType, context),

package/dist/contract-schema/contract-schema-object-tuple.mjs

@@ -1,7 +1,7 @@
 import ts from './typescript-api.mjs';
 import { compareSymbols } from './contract-schema-type-utils.mjs';
 export function objectSchema(type, context, schemaForType) {
-    const properties = {};
+    const properties = new Map();
     for (const property of context.checker.getPropertiesOfType(type).toSorted(compareSymbols)) {
         const declaration = property.valueDeclaration;
         /* v8 ignore start */
@@ -12,10 +12,10 @@ export function objectSchema(type, context, schemaForType) {
             throw new Error(`Property "${property.name}" has no type`);
         /* v8 ignore stop */
         try {
-            properties[property.name] = {
+            properties.set(property.name, {
                 required: !(property.flags & ts.SymbolFlags.Optional),
                 schema: schemaForType(propertyType, context),
-            };
+            });
         }
         catch (error) {
             throw new Error(`Property "${property.name}": ${error.message}`, { cause: error });
@@ -24,8 +24,10 @@ export function objectSchema(type, context, schemaForType) {
     const stringIndex = context.checker.getIndexInfoOfType(type, ts.IndexKind.String);
     return {
         type: 'object',
-        properties,
-        additionalProperties: stringIndex ? schemaForType(stringIndex.type, context) : false,
+        properties: Object.fromEntries(properties),
+        additionalProperties: stringIndex && !(stringIndex.type.flags & ts.TypeFlags.Never)
+            ? schemaForType(stringIndex.type, context)
+            : false,
     };
 }
 /* v8 ignore start -- checker internal used only for compiler-synthesized properties */

package/dist/contract-schema/contract-schema-type-extractor.mjs

@@ -80,6 +80,17 @@ function schemaForType(type, context) {
         return buildUnion();
     }
     if (type.isIntersection()) {
+        const index = checker.getIndexTypeOfType(type, ts.IndexKind.String);
+        const properties = checker.getPropertiesOfType(type);
+        if (index && index.flags & ts.TypeFlags.Never && properties.length > 0) {
+            if (properties.some((property) => !(property.flags & ts.SymbolFlags.Optional)))
+                throw unsupportedType(type, checker, 'never string index conflicts with named properties');
+            if (checker.getSignaturesOfType(type, ts.SignatureKind.Call).length > 0)
+                throw unsupportedType(type, checker, 'callable types are not supported');
+            if (checker.getSignaturesOfType(type, ts.SignatureKind.Construct).length > 0)
+                throw unsupportedType(type, checker, 'constructable types are not supported');
+            return { type: 'object', properties: {}, additionalProperties: false };
+        }
         return {
             type: 'intersection',
             variants: distinctNodes(type.types.map((variant) => schemaForType(variant, context))),
@@ -104,6 +115,8 @@ function schemaForType(type, context) {
         /* v8 ignore next */
         if (!typeArguments[0])
             throw unsupportedType(type, checker, 'array element type is missing');
+        if (typeArguments[0].flags & ts.TypeFlags.Never)
+            return { type: 'tuple', items: [], optionalItems: 0 };
         return { type: 'array', items: schemaForType(typeArguments[0], context) };
     }
     if (checker.getSignaturesOfType(type, ts.SignatureKind.Call).length > 0) {

package/dist/contract-schema/contract-schema-validator.mjs

@@ -66,7 +66,7 @@ function validateObject(node, value, path, context, checkUnexpected) {
     if (!isObject(value))
         return requireType(false, 'object', value, path, context);
     for (const [key, property] of Object.entries(node.properties)) {
-        if (!(key in value)) {
+        if (!Object.hasOwn(value, key)) {
             if (property.required) {
                 addIssue(context, propertyPath(path, key), 'missing-required', 'Required field is missing');
             }
@@ -77,7 +77,7 @@ function validateObject(node, value, path, context, checkUnexpected) {
     if (!checkUnexpected)
         return;
     for (const [key, nested] of Object.entries(value)) {
-        if (key in node.properties)
+        if (Object.hasOwn(node.properties, key))
             continue;
         if (node.additionalProperties === false) {
             addUnexpectedIssue(context, propertyPath(path, key));

package/dist/index.d.mts

@@ -15,8 +15,6 @@ export type { EphemeralListenerOptions, RunnerPortPolicy } from './runner-port-p
 export { extractAlterTableAddColumnLocations, extractCreateIndexMetadata, extractCreateTableMetadata, extractDefaultFunction, extractDropIndexMetadata, extractFuncCallArgColumnNames, extractMigrationConstraintMetadata, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mts';
 export type { ForeignKey, SqlCreateIndexMetadata, SqlCreateTableColumn, SqlCreateTableMetadata, SqlDropIndexMetadata, SqlIndexParam, SqlMigrationConstraintMetadata, } from './sql-ast/index.mts';
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from './sql-scanner/index.mts';
-export { applyHarnessConfig, checkHarnessConfig, dumpHarnessPolicy, planHarnessConfig, DEFAULT_EXTRA_WRITABLE_ROOTS, } from './agent-harness-config/index.mts';
-export type { ApplyTarget, FilePlan, FileResult, HarnessApplyResult, HarnessCheckResult, HarnessConfigOptions, HarnessId, HarnessPlan, HarnessPolicyDump, JsonPatch, KeyDrift, TomlPatch, TomlValue, } from './agent-harness-config/index.mts';
 export { auditCiJobRuntime, parseWorkflowNameMatch } from './gha-runtime-audit/index.mts';
 export type { GhApiExecutor, RuntimeAuditOptions, RuntimeAuditResult, RuntimeAuditWorkflowFilter, RuntimeJobResult, RuntimeSample, } from './gha-runtime-audit/index.mts';
 export { checkGhaWorkspacePolicy } from './gha-workspace-policy/index.mts';

package/dist/index.mjs

@@ -8,7 +8,6 @@ export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_M
 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';
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from './sql-scanner/index.mjs';
-export { applyHarnessConfig, checkHarnessConfig, dumpHarnessPolicy, planHarnessConfig, DEFAULT_EXTRA_WRITABLE_ROOTS, } from './agent-harness-config/index.mjs';
 export { auditCiJobRuntime, parseWorkflowNameMatch } from './gha-runtime-audit/index.mjs';
 export { checkGhaWorkspacePolicy } from './gha-workspace-policy/index.mjs';
 export { requireUpToDate } from './require-up-to-date/index.mjs';

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;
 };

package/dist/mcp-server/run.mjs

@@ -1,4 +1,4 @@
-import { loadMcpSdk } from './sdk.mjs';
+import { assertBlackboardInstalled, loadMcpSdk } from './sdk.mjs';
 import { createMcpServer } from './server.mjs';
 import { launchWorktreeRoot, runIsolatedGit } from './worktree.mjs';
 /**
@@ -8,11 +8,14 @@ import { launchWorktreeRoot, runIsolatedGit } from './worktree.mjs';
 export async function runMcpServer(options) {
     const runGit = options.runGit ?? runIsolatedGit;
     const sdk = await loadMcpSdk(options.importSdk);
+    if (options.blackboard === undefined)
+        assertBlackboardInstalled(options.resolveFrom);
     const launchRoot = await launchWorktreeRoot(options.cwd, runGit);
     const environment = {
         launchRoot,
         env: options.env,
         runGit,
+        ...(options.resolveFrom === undefined ? {} : { resolveFrom: options.resolveFrom }),
         ...(options.blackboard === undefined ? {} : { blackboard: options.blackboard }),
     };
     const server = createMcpServer(sdk, environment, options.version);

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

@@ -9,9 +9,18 @@ export type McpSdk = {
     ListToolsRequestSchema: typeof ListToolsRequestSchema;
 };
 export type SdkImporter = (specifier: string) => Promise<unknown>;
-export declare const MISSING_SDK_MESSAGE: string;
+/**
+ * The directory the server was installed into: the parent of the outermost `node_modules` above
+ * `from`, which is where `pnpm add` must run so the peers resolve from this package. Outside any
+ * `node_modules` (a source checkout) it is the module's own directory.
+ */
+export declare function installDirectory(from?: string | URL): string;
+export declare function missingSdkMessage(directory: string): string;
 /**
  * Imports the SDK lazily. A static import would make every `vouchington` command fail on a
  * consumer that never installed the optional peer.
  */
-export declare function loadMcpSdk(importSdk?: SdkImporter): Promise<McpSdk>;
+export declare function loadMcpSdk(importSdk?: SdkImporter, directory?: string): Promise<McpSdk>;
+export declare function missingBlackboardMessage(directory: string): string;
+/** Fails fast at startup when `agent-blackboard` cannot be resolved from this package's install. */
+export declare function assertBlackboardInstalled(resolveFrom?: string | URL): void;

package/dist/mcp-server/sdk.mjs

@@ -6,17 +6,34 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { createRequire } from 'node:module';
+import { dirname, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { isMissingModuleError } from '../agent-blackboard/client.mjs';
 const SDK_PACKAGE = '@modelcontextprotocol/sdk';
-export const MISSING_SDK_MESSAGE = `vouchington mcp needs ${SDK_PACKAGE} (and its zod peer), which is an optional peer ` +
-    `dependency of vouchington-tooling and is not installed. Install it next to ` +
-    `vouchington-tooling: pnpm add -D ${SDK_PACKAGE} zod`;
+/**
+ * The directory the server was installed into: the parent of the outermost `node_modules` above
+ * `from`, which is where `pnpm add` must run so the peers resolve from this package. Outside any
+ * `node_modules` (a source checkout) it is the module's own directory.
+ */
+export function installDirectory(from = import.meta.url) {
+    const file = typeof from === 'string' && !from.startsWith('file:') ? from : fileURLToPath(from);
+    const marker = `${sep}node_modules${sep}`;
+    const index = file.indexOf(marker);
+    return index === -1 ? dirname(file) : file.slice(0, index);
+}
+export function missingSdkMessage(directory) {
+    return (`vouchington mcp needs ${SDK_PACKAGE} (and its zod peer), which is an optional peer ` +
+        `dependency of vouchington-tooling and is not installed. Install it in the directory ` +
+        `vouchington-tooling is installed in, not in a project: cd ${directory} && ` +
+        `pnpm add ${SDK_PACKAGE} zod`);
+}
 const defaultImporter = (specifier) => import(__rewriteRelativeImportExtension(specifier));
 /**
  * Imports the SDK lazily. A static import would make every `vouchington` command fail on a
  * consumer that never installed the optional peer.
  */
-export async function loadMcpSdk(importSdk = defaultImporter) {
+export async function loadMcpSdk(importSdk = defaultImporter, directory = installDirectory()) {
     try {
         const [server, stdio, types] = await Promise.all([
             importSdk(`${SDK_PACKAGE}/server/mcp.js`),
@@ -27,7 +44,22 @@ export async function loadMcpSdk(importSdk = defaultImporter) {
     }
     catch (error) {
         if (isMissingModuleError(error))
-            throw new Error(MISSING_SDK_MESSAGE, { cause: error });
+            throw new Error(missingSdkMessage(directory), { cause: error });
         throw error;
     }
 }
+export function missingBlackboardMessage(directory) {
+    return ('vouchington mcp needs agent-blackboard, which is an optional peer dependency of ' +
+        'vouchington-tooling and is not installed. Install it in the directory vouchington-tooling ' +
+        `is installed in, not in a project: cd ${directory} && pnpm add agent-blackboard`);
+}
+/** Fails fast at startup when `agent-blackboard` cannot be resolved from this package's install. */
+export function assertBlackboardInstalled(resolveFrom = import.meta.url) {
+    try {
+        createRequire(resolveFrom).resolve('agent-blackboard');
+    }
+    catch (error) {
+        // `resolve` only fails when the package cannot be found from `resolveFrom`.
+        throw new Error(missingBlackboardMessage(installDirectory(resolveFrom)), { cause: error });
+    }
+}

package/dist/mcp-server/server.mjs

@@ -2,8 +2,9 @@ import { callTool } from './dispatch.mjs';
 import { TOOLS } from './tools.mjs';
 export const SERVER_NAME = 'vouchington-tooling';
 const INSTRUCTIONS = 'Journals agent-blackboard feedback for a vouchington consumer. Every tool takes an explicit ' +
-    'sessionId and an optional worktree (an absolute path listed by `git worktree list` for the ' +
-    'repository this server was launched from). Hosts prefix the tool names differently: Claude ' +
+    'sessionId and an optional worktree (the absolute path of a git worktree top level; it ' +
+    'defaults to the launch directory worktree and is required when the server was launched ' +
+    'outside one). Hosts prefix the tool names differently: Claude ' +
     'Code mcp__vouchington-tooling__<tool>, Codex mcp__vouchington_tooling__<tool>, Grok ' +
     'vouchington-tooling__<tool> (through search_tool and use_tool), Cursor the vouchington-tooling ' +
     'namespace (through GetDynamicTools and CallDynamicTool). Search for journal_append before ' +

package/dist/mcp-server/tools.mjs

@@ -7,8 +7,9 @@ const SESSION_ID = {
 };
 const WORKTREE = {
     type: 'string',
-    description: 'Absolute path of a worktree listed by `git worktree list` for the repository the server ' +
-        'was launched from. Defaults to the launch worktree.',
+    description: 'Absolute path of the top level of a git worktree (`git rev-parse --show-toplevel`), not a ' +
+        'subdirectory. Defaults to the launch directory worktree; required when the server was ' +
+        'launched outside a git worktree.',
 };
 const PARENT_SESSION_ID = {
     type: ['string', 'null'],

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

@@ -1,18 +1,25 @@
 import { type RunTextCommand } from '../gh-cli/exec.mts';
-/** Runs git without inherited `GIT_*` variables so `GIT_DIR` cannot redirect the check. */
+/**
+ * The environment for git: no inherited `GIT_*` variables, so `GIT_DIR` cannot redirect the check,
+ * and the C locale, so git's diagnostics are not translated and can be classified reliably.
+ */
+export declare function isolatedGitEnv(): NodeJS.ProcessEnv;
 export declare const runIsolatedGit: RunTextCommand;
-/** The worktree root containing `cwd`, or a message that says how to fix the launch directory. */
-export declare function launchWorktreeRoot(cwd: string, runGit: RunTextCommand): Promise<string>;
-/** Paths of the non-bare entries in `git worktree list --porcelain` output. */
-export declare function parseWorktreeList(porcelain: string): string[];
 /**
- * Resolves the worktree a tool call may act on. The list is read from git on every call, so
- * worktrees created after the server started are accepted and removed ones are not. The
- * comparison is exact on real paths: a subdirectory of a worktree, or an unrelated repository,
- * is rejected.
+ * The worktree root containing `cwd`, or undefined when git reports `cwd` is not inside one (so
+ * the server may be launched from anywhere). Any other git failure, such as a missing git binary
+ * or an unsafe repository, is thrown with the cause rather than reported as "outside a worktree".
+ */
+export declare function launchWorktreeRoot(cwd: string, runGit: RunTextCommand): Promise<string | undefined>;
+/**
+ * Resolves the worktree a tool call may act on. It must be an absolute path that, after
+ * resolving symlinks, is exactly the top level of a git worktree (of any repository on the
+ * machine). A subdirectory, a relative or nonexistent path, and a non-git directory are rejected.
+ * Git is asked on every call, so worktrees created after the server started are accepted and
+ * removed ones are not. Without `requested`, the launch worktree is used when there is one.
  */
 export declare function resolveWorktree(input: {
-    launchRoot: string;
+    launchRoot: string | undefined;
     requested?: string | undefined;
     runGit: RunTextCommand;
 }): Promise<string>;

package/dist/mcp-server/worktree.mjs

@@ -5,8 +5,15 @@ import { promisify } from 'node:util';
 import { createCommandRunner } from '../gh-cli/exec.mjs';
 import { gitEnv } from '../shared-context/index.mjs';
 const execFileAsync = promisify(execFile);
-/** Runs git without inherited `GIT_*` variables so `GIT_DIR` cannot redirect the check. */
-export const runIsolatedGit = createCommandRunner('git', (command, args) => execFileAsync(command, args, { env: gitEnv() }));
+/**
+ * The environment for git: no inherited `GIT_*` variables, so `GIT_DIR` cannot redirect the check,
+ * and the C locale, so git's diagnostics are not translated and can be classified reliably.
+ */
+export function isolatedGitEnv() {
+    const { LANGUAGE: _language, ...env } = gitEnv();
+    return { ...env, LC_ALL: 'C' };
+}
+export const runIsolatedGit = createCommandRunner('git', (command, args) => execFileAsync(command, args, { env: isolatedGitEnv() }));
 async function canonical(path) {
     try {
         return await realpath(path);
@@ -15,44 +22,54 @@ async function canonical(path) {
         return undefined;
     }
 }
-/** The worktree root containing `cwd`, or a message that says how to fix the launch directory. */
+/**
+ * git's two "no worktree here" outcomes: outside any repository, and inside a `.git` directory.
+ * The messages are English because `isolatedGitEnv` forces the C locale.
+ */
+function isNotAGitRepository(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const { stderr, message } = error;
+    return [stderr, message].some((text) => typeof text === 'string' && /not a git repository|must be run in a work tree/i.test(text));
+}
+/**
+ * The worktree root containing `cwd`, or undefined when git reports `cwd` is not inside one (so
+ * the server may be launched from anywhere). Any other git failure, such as a missing git binary
+ * or an unsafe repository, is thrown with the cause rather than reported as "outside a worktree".
+ */
 export async function launchWorktreeRoot(cwd, runGit) {
+    let output;
     try {
-        return await realpath((await runGit(['-C', cwd, 'rev-parse', '--show-toplevel'])).trim());
+        output = await runGit(['-C', cwd, 'rev-parse', '--show-toplevel']);
     }
     catch (error) {
-        throw new Error(`vouchington mcp must be launched inside a git worktree; ${cwd} is not one (${errorText(error)})`);
+        if (isNotAGitRepository(error))
+            return undefined;
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`git could not determine the worktree of ${cwd}: ${reason}. Check that git is installed and ` +
+            'on PATH, that the directory exists, and that the repository is readable by this user ' +
+            '(see safe.directory).', { cause: error });
     }
-}
-/** Paths of the non-bare entries in `git worktree list --porcelain` output. */
-export function parseWorktreeList(porcelain) {
-    const paths = [];
-    for (const block of porcelain.split(/\r?\n\r?\n/)) {
-        const lines = block.split(/\r?\n/);
-        const first = lines.find((line) => line.startsWith('worktree '));
-        if (first !== undefined && !lines.includes('bare'))
-            paths.push(first.slice('worktree '.length));
-    }
-    return paths;
+    return realpath(output.trim());
 }
 /**
- * Resolves the worktree a tool call may act on. The list is read from git on every call, so
- * worktrees created after the server started are accepted and removed ones are not. The
- * comparison is exact on real paths: a subdirectory of a worktree, or an unrelated repository,
- * is rejected.
+ * Resolves the worktree a tool call may act on. It must be an absolute path that, after
+ * resolving symlinks, is exactly the top level of a git worktree (of any repository on the
+ * machine). A subdirectory, a relative or nonexistent path, and a non-git directory are rejected.
+ * Git is asked on every call, so worktrees created after the server started are accepted and
+ * removed ones are not. Without `requested`, the launch worktree is used when there is one.
  */
 export async function resolveWorktree(input) {
     const { launchRoot, requested, runGit } = input;
-    if (requested !== undefined && !isAbsolute(requested))
-        throw new Error('worktree must be an absolute path to a git worktree of the launch repository');
-    const target = requested === undefined ? launchRoot : await canonical(requested);
-    const listing = await runGit(['-C', launchRoot, 'worktree', 'list', '--porcelain']);
-    const known = (await Promise.all(parseWorktreeList(listing).map(canonical))).filter((path) => path !== undefined);
-    if (target !== undefined && known.includes(target))
+    if (requested === undefined && launchRoot === undefined)
+        throw new Error('worktree is required: this server was launched outside a git worktree, so pass ' +
+            'worktree as the absolute path of the git worktree to act on');
+    const path = requested ?? launchRoot;
+    if (!isAbsolute(path))
+        throw new Error('worktree must be an absolute path to a git worktree');
+    const target = await canonical(path);
+    if (target !== undefined && (await launchWorktreeRoot(target, runGit)) === target)
         return target;
-    throw new Error(`worktree ${requested ?? launchRoot} is not a worktree of the repository this server was ` +
-        `launched from (${launchRoot}). Registered worktrees: ${known.join(', ')}`);
-}
-function errorText(error) {
-    return error instanceof Error ? error.message : String(error);
+    throw new Error(`worktree ${path} is not the top level of a git worktree: it must exist and be the ` +
+        'directory `git rev-parse --show-toplevel` reports, not a subdirectory of it');
 }

package/dist/openapi-document/build-openapi-catalog-sse.d.mts

@@ -0,0 +1,4 @@
+import type { buildOperationResponse } from './build-openapi-response.mts';
+import type { RegisteredRoute, ResponseContract } from './operation-types.mts';
+/** Keeps a cataloged stream unavailable until its extracted variants describe SSE. */
+export declare function retainCatalogSseResponse(kind: RegisteredRoute['kind'] | undefined, variants: readonly ResponseContract[], rendered: ReturnType<typeof buildOperationResponse>): ReturnType<typeof buildOperationResponse>;