vouchington-tooling 0.41.0 → 0.42.0

package/bin/policy-runner.mjs

@@ -0,0 +1,26 @@
+// Runs one export of a consumer's policy module in this fresh process, so the MCP server never
+// imports checkout code. argv[2] is the real path of the module. stdin is one JSON object,
+// { policyVersion: 1, export, input }. stdout is one JSON object, { ok: true, result },
+// { ok: true, skipped: true } when the module has no such export, or { ok: false, error }.
+// Console output and direct stdout writes from the policy go to stderr so they cannot corrupt the
+// reply.
+import { readFileSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+
+const writeReply = process.stdout.write.bind(process.stdout)
+process.stdout.write = process.stderr.write.bind(process.stderr)
+console.log = console.info = console.debug = console.error
+
+async function run() {
+  const request = JSON.parse(readFileSync(0, 'utf8'))
+  if (request.policyVersion !== 1) throw new Error('unsupported policyVersion')
+  const policy = await import(pathToFileURL(process.argv[2]).href)
+  if (typeof policy[request.export] !== 'function') return { ok: true, skipped: true }
+  return { ok: true, result: await policy[request.export](request.input) }
+}
+
+const reply = await run().catch((error) => ({
+  ok: false,
+  error: String((error && error.stack) || error),
+}))
+writeReply(JSON.stringify(reply), () => process.exit(0))

package/dist/agent-blackboard/feedback-codec.d.mts

@@ -1,5 +1,6 @@
 export { normalizeRepositories } from './feedback-fields.mts';
 import type { FeedbackEnvelope } from './feedback-types.mts';
+export declare const FEEDBACK_MARKDOWN_MAX_BYTES = 12000;
 export declare function validateFeedbackEnvelope(value: unknown): asserts value is FeedbackEnvelope;
 export declare function redactFeedbackText(value: string, knownSensitiveValues?: string[]): string;
 /** Bytes by which the envelope exceeds its markdown or whole-envelope limit; 0 when it fits. */

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

@@ -2,7 +2,7 @@ import { normalizeRepositories, validateFeedbackText, validateFeedbackReferences
 export { normalizeRepositories } from "./feedback-fields.mjs";
 import { isCount, isObject } from "./snapshot-partition-guards.mjs";
 const FEEDBACK_MAX_BYTES = 16_384;
-const FEEDBACK_MARKDOWN_MAX_BYTES = 12_000;
+export const FEEDBACK_MARKDOWN_MAX_BYTES = 12_000;
 const OUTCOMES = [
     'in-progress',
     'success',

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 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 journal is deprecated and being phased out: agents journal through the mcp server.\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 journal is deprecated and being phased out: agents journal through the mcp server.\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, retrospective_check, retrospective_save,\n                         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

@@ -126,7 +126,8 @@ agent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '
 agent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]
 mcp
   (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,
-                         session_ensure, snapshot_export, and session_archive over stdio.
+                         session_ensure, retrospective_check, retrospective_save,
+                         snapshot_export, and session_archive over stdio.
                          Needs the optional @modelcontextprotocol/sdk peer (and zod).
                          Launch it from inside the repository's git worktree.
 `;

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

@@ -1,12 +1,17 @@
 import type { BlackboardClientDependencies } from '../agent-blackboard/client.mts';
 import type { FeedbackIdentity } from '../agent-blackboard/feedback-types.mts';
+import type { PolicySpawner } from './policy-spawn.mts';
 import { type Args } from './args.mts';
 /** What a handler may rely on: every field here was validated before the handler ran. */
-type ToolContext = {
+export type ToolContext = {
     sessionId: string;
     worktree: string;
     env: NodeJS.ProcessEnv;
     dependencies: BlackboardClientDependencies;
+    /** The launch directory's worktree top level, or undefined when it is not inside one. */
+    launchRoot: string | undefined;
+    /** Test seam: replaces the child process a policy export runs in. */
+    spawnPolicy?: PolicySpawner;
 };
 export type ToolHandler = (args: Args, context: ToolContext) => Promise<Record<string, unknown>>;
 /**
@@ -15,5 +20,9 @@ export type ToolHandler = (args: Args, context: ToolContext) => Promise<Record<s
  */
 export declare function outboxDirectory(worktree: string): string;
 export declare function readSessionId(args: Args): string;
+/** The caller identity, fully validated before any policy runs or anything is written. */
 export declare function readIdentity(args: Args, sessionId: string): FeedbackIdentity;
-export {};
+/** Policy modules run only for a server whose launch repository bounds the worktrees it acts on. */
+export declare function assertPolicyAllowed(context: {
+    launchRoot: string | undefined;
+}): void;

package/dist/mcp-server/context.mjs

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { assertSessionId } from "../agent-blackboard/session-id.mjs";
+import { validateFeedbackIdentity } from "../agent-blackboard/feedback-identity.mjs";
 import { requiredNullableString, requiredString } from "./args.mjs";
 /**
  * The consumer convention for the interactive outbox. It is derived, never accepted from the
@@ -13,11 +14,23 @@ export function readSessionId(args) {
     assertSessionId(value);
     return value;
 }
+/** The caller identity, fully validated before any policy runs or anything is written. */
 export function readIdentity(args, sessionId) {
-    return {
+    const identity = {
         sessionId,
         parentSessionId: requiredNullableString(args, 'parentSessionId'),
         agent: requiredString(args, 'agent'),
         version: requiredString(args, 'version'),
     };
+    validateFeedbackIdentity(identity);
+    return identity;
+}
+/** Policy modules run only for a server whose launch repository bounds the worktrees it acts on. */
+export function assertPolicyAllowed(context) {
+    // Policy and facts children are reaped by Unix process group; Windows has no equivalent here.
+    if (process.platform === 'win32')
+        throw new Error('policy tools are not supported on Windows: run the server on macOS or Linux');
+    if (context.launchRoot === undefined)
+        throw new Error('policy tools require the server to be launched inside a repository worktree: relaunch ' +
+            'it from the repository so the worktree argument is bound to that repository');
 }

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

@@ -1,5 +1,6 @@
 import type { BlackboardClientDependencies } from '../agent-blackboard/client.mts';
 import type { RunTextCommand } from '../gh-cli/exec.mts';
+import type { PolicySpawner } from './policy-spawn.mts';
 export type ServerEnvironment = {
     /** The launch directory's worktree top level, or undefined when it is not inside one. */
     launchRoot: string | undefined;
@@ -9,6 +10,8 @@ export type ServerEnvironment = {
     resolveFrom?: string | URL;
     /** Test seam: replaces how the consumer's `agent-blackboard` client is loaded. */
     blackboard?: BlackboardClientDependencies;
+    /** Test seam: replaces the child process a policy export runs in. */
+    spawnPolicy?: PolicySpawner;
 };
 export type ToolCallResult = {
     content: Array<{

package/dist/mcp-server/dispatch.mjs

@@ -2,6 +2,7 @@ import { FeedbackDeliveryError } from "../agent-blackboard/index.mjs";
 import { optionalString, rejectUnknown, requireObject } from "./args.mjs";
 import { readSessionId } from "./context.mjs";
 import { journalAppend, journalEntries } from "./handlers-journal.mjs";
+import { retrospectiveCheck, retrospectiveSave } from "./handlers-retrospective.mjs";
 import { outboxFlush, outboxStatus } from "./handlers-outbox.mjs";
 import { sessionArchive, sessionEnsure, snapshotExport } from "./handlers-session.mjs";
 import { TOOLS } from "./tools.mjs";
@@ -12,6 +13,8 @@ const HANDLERS = {
     outbox_status: outboxStatus,
     outbox_flush: outboxFlush,
     session_ensure: sessionEnsure,
+    retrospective_check: retrospectiveCheck,
+    retrospective_save: retrospectiveSave,
     snapshot_export: snapshotExport,
     session_archive: sessionArchive,
 };
@@ -51,6 +54,8 @@ export async function callTool(name, rawArguments, environment) {
             sessionId,
             worktree,
             env: environment.env,
+            launchRoot: environment.launchRoot,
+            ...(environment.spawnPolicy === undefined ? {} : { spawnPolicy: environment.spawnPolicy }),
             // The client resolves from this package's install, like the SDK, never from the worktree.
             dependencies: {
                 ...environment.blackboard,

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

@@ -1,4 +1,17 @@
-import { type ToolHandler } from './context.mts';
+import { type FeedbackCoverage, type FeedbackDeliveryResult, type WorkOutcome } from '../agent-blackboard/index.mts';
+import { type Args } from './args.mts';
+import { type ToolContext, type ToolHandler } from './context.mts';
+export declare const MODES: readonly ["interactive", "autonomous"];
+export declare const OUTCOMES: readonly WorkOutcome[];
+export declare function readCoverage(args: Args): FeedbackCoverage;
 export declare const journalAppend: ToolHandler;
+/**
+ * The tool result for a write: the delivery result plus the server-owned timestamp (a first
+ * append takes the current time; a retry of the same event reports the one already stored or
+ * retained) and the outbox counts. Autonomous delivery never uses an outbox, so it has nothing
+ * pending; interactive delivery reports the outbox as it is after delivery.
+ */
+export declare function deliveryResponse(result: FeedbackDeliveryResult, context: ToolContext, mode: (typeof MODES)[number]): Record<string, unknown>;
+export declare function byCreatedAt(left: unknown, right: unknown): number;
 /** Every entry as the client returns it, oldest first. Nothing is filtered or rewritten. */
 export declare const journalEntries: ToolHandler;

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

@@ -2,8 +2,8 @@ import { appendJournalMarkdown, readJournal, } from "../agent-blackboard/index.m
 import { optionalRecord, optionalString, requiredChoice, requiredString, requiredStringArray, rejectUnknown, } from "./args.mjs";
 import { outboxDirectory, readIdentity } from "./context.mjs";
 import { outboxCounts } from "./handlers-outbox.mjs";
-const MODES = ['interactive', 'autonomous'];
-const OUTCOMES = [
+export const MODES = ['interactive', 'autonomous'];
+export const OUTCOMES = [
     'in-progress',
     'success',
     'failure',
@@ -20,7 +20,7 @@ const COVERAGE_STATUSES = [
     'not-assessed',
     'not-started',
 ];
-function readCoverage(args) {
+export function readCoverage(args) {
     const coverage = optionalRecord(args, 'feedbackCoverage');
     if (coverage === undefined)
         throw new Error('feedbackCoverage is required');
@@ -60,11 +60,16 @@ export const journalAppend = async (args, context) => {
         env: context.env,
         dependencies: context.dependencies,
     });
-    // The server owns the timestamp: a first append takes the current time, and a retry of the same
-    // event (same session, sourceEventId, and content) reports the one already stored or retained.
+    return deliveryResponse(result, context, mode);
+};
+/**
+ * The tool result for a write: the delivery result plus the server-owned timestamp (a first
+ * append takes the current time; a retry of the same event reports the one already stored or
+ * retained) and the outbox counts. Autonomous delivery never uses an outbox, so it has nothing
+ * pending; interactive delivery reports the outbox as it is after delivery.
+ */
+export function deliveryResponse(result, context, mode) {
     const timestamp = result.status === 'delivered' ? result.receipt.timestamp : result.timestamp;
-    // Autonomous delivery never uses an outbox, so it has nothing pending. Interactive delivery
-    // reports the outbox as it is after delivery, split into the caller's session and the worktree.
     const counts = mode === 'interactive'
         ? outboxCounts(context.worktree, context.sessionId)
         : { pendingCount: 0, worktreePendingCount: 0 };
@@ -77,14 +82,14 @@ export const journalAppend = async (args, context) => {
         ...(storedVersion === undefined ? {} : { storedVersion }),
         ...counts,
     };
-};
+}
 // `Entries.get` documents no order, and `createdAt` is a service-generated ISO 8601 UTC time whose
 // text order is time order. An entry without a usable `createdAt` sorts first rather than throwing.
 function createdAtOf(entry) {
     const createdAt = entry?.createdAt;
     return typeof createdAt === 'string' ? createdAt : '';
 }
-function byCreatedAt(left, right) {
+export function byCreatedAt(left, right) {
     const leftAt = createdAtOf(left);
     const rightAt = createdAtOf(right);
     if (leftAt === rightAt)

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

@@ -0,0 +1,12 @@
+import { type ToolHandler } from './context.mts';
+/** Whether the session already holds a retrospective, and which (sourceEventId, issues, prs). */
+export declare const retrospectiveCheck: ToolHandler;
+/** The default event id, hashed when the session id would push it past the 256-byte limit. */
+export declare function defaultSourceEventId(sessionId: string): string;
+/**
+ * Saves the session's retrospective: composes it when `compose` is given, checks the arguments
+ * against the document's front matter, runs the checkout's `validateRetrospective` policy (in a
+ * child process) and writes nothing if it reports errors, then writes through the same verified
+ * path as `journal_append`.
+ */
+export declare const retrospectiveSave: ToolHandler;

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

@@ -0,0 +1,154 @@
+import { createHash } from 'node:crypto';
+import { createFeedbackEnvelope, validateFeedbackEnvelope, writeFeedback, } from "../agent-blackboard/index.mjs";
+import { optionalRecord, optionalString, requiredChoice, requiredString, requiredStringArray, } from "./args.mjs";
+import { assertPolicyAllowed, outboxDirectory, readIdentity } from "./context.mjs";
+import { byCreatedAt, deliveryResponse, MODES, OUTCOMES, readCoverage, } from "./handlers-journal.mjs";
+import { readEntriesIfPresent } from "./journal-read.mjs";
+import { runValidator } from "./policy-run.mjs";
+import { parseRetrospectiveFrontMatter } from "./retrospective-front-matter.mjs";
+import { FEEDBACK_MARKDOWN_MAX_BYTES, redactFeedbackText, } from "../agent-blackboard/feedback-codec.mjs";
+import { composeFromArgs, sensitiveValues } from "./retrospective-input.mjs";
+import { checkFrontMatter, resolveRepositories } from "./retrospective-resolve.mjs";
+function retrospectiveData(entry) {
+    const data = entry?.data;
+    return data?.type === 'retrospective' ? data : undefined;
+}
+/** Whether the session already holds a retrospective, and which (sourceEventId, issues, prs). */
+export const retrospectiveCheck = async (args, context) => {
+    const sourceEventId = optionalString(args, 'sourceEventId');
+    const entries = await readEntriesIfPresent(context.sessionId, context.env, context.dependencies);
+    const found = (entries ?? [])
+        .toSorted(byCreatedAt)
+        .flatMap((entry) => {
+        const data = retrospectiveData(entry);
+        return data === undefined ? [] : [data];
+    })
+        .filter((data) => sourceEventId === undefined || data.sourceEventId === sourceEventId)
+        .map((data) => ({
+        sourceEventId: data.sourceEventId,
+        timestamp: data.timestamp,
+        issues: data.issues ?? [],
+        prs: data.prs ?? [],
+    }));
+    return { sessionId: context.sessionId, saved: found.length > 0, entries: found };
+};
+function readMarkdownSource(args) {
+    const compose = optionalRecord(args, 'compose');
+    if ((args.markdown === undefined) === (compose === undefined))
+        throw new Error('pass exactly one of markdown or compose');
+    return compose === undefined ? { markdown: requiredString(args, 'markdown') } : { compose };
+}
+/** The default event id, hashed when the session id would push it past the 256-byte limit. */
+export function defaultSourceEventId(sessionId) {
+    const id = `retrospective-${sessionId}`;
+    return Buffer.byteLength(id) <= 256
+        ? id
+        : `retrospective-${createHash('sha256').update(sessionId).digest('hex')}`;
+}
+/**
+ * Saves the session's retrospective: composes it when `compose` is given, checks the arguments
+ * against the document's front matter, runs the checkout's `validateRetrospective` policy (in a
+ * child process) and writes nothing if it reports errors, then writes through the same verified
+ * path as `journal_append`.
+ */
+export const retrospectiveSave = async (args, context) => {
+    assertPolicyAllowed(context);
+    const identity = readIdentity(args, context.sessionId);
+    const mode = requiredChoice(args, 'mode', MODES);
+    const workOutcome = requiredChoice(args, 'workOutcome', OUTCOMES);
+    const feedbackCoverage = readCoverage(args);
+    const argRepositories = args.repositories === undefined ? undefined : requiredStringArray(args, 'repositories');
+    const sourceEventId = optionalString(args, 'sourceEventId') ?? defaultSourceEventId(context.sessionId);
+    const category = optionalString(args, 'category');
+    if (args.dryRun !== undefined && typeof args.dryRun !== 'boolean')
+        throw new Error('dryRun must be a boolean');
+    const policy = {
+        worktree: context.worktree,
+        env: context.env,
+        ...(context.spawnPolicy === undefined ? {} : { spawn: context.spawnPolicy }),
+    };
+    const { markdown: given, compose } = readMarkdownSource(args);
+    const secrets = sensitiveValues(compose, context.env);
+    // Everything the policy sees is derived from the redacted document, never the raw input.
+    const redactedGiven = given === undefined ? undefined : redactFeedbackText(given, secrets);
+    // Reject a document that can never be stored before any policy export runs for it.
+    if (redactedGiven !== undefined && Buffer.byteLength(redactedGiven) > FEEDBACK_MARKDOWN_MAX_BYTES)
+        throw new Error(`markdown must be at most ${FEEDBACK_MARKDOWN_MAX_BYTES} bytes`);
+    const early = redactedGiven === undefined ? undefined : parseRetrospectiveFrontMatter(redactedGiven);
+    const repositories = await resolveRepositories(argRepositories, early?.repositories, policy);
+    const markdown = redactedGiven ??
+        redactFeedbackText(await composeFromArgs(compose, {
+            sessionId: context.sessionId,
+            repositories,
+            workOutcome,
+            feedbackCoverage,
+            worktree: context.worktree,
+            env: context.env,
+            dependencies: context.dependencies,
+        }), secrets);
+    const front = early ?? parseRetrospectiveFrontMatter(markdown);
+    checkFrontMatter(front, {
+        sessionId: context.sessionId,
+        workOutcome,
+        // The document was redacted before parsing, so compare it with equally redacted sources.
+        feedbackCoverage: {
+            ...feedbackCoverage,
+            sources: feedbackCoverage.sources.map((source) => redactFeedbackText(source, secrets)),
+        },
+        repositories: argRepositories,
+    });
+    // Building the envelope first rejects empty or oversized markdown before any policy runs.
+    const envelope = createFeedbackEnvelope({
+        schemaVersion: 1,
+        type: 'retrospective',
+        sourceEventId,
+        // The server owns the timestamp, as in journal_append.
+        timestamp: new Date().toISOString(),
+        date: front.date,
+        issues: front.issues,
+        prs: front.prs,
+        repositories,
+        markdown,
+        workOutcome,
+        feedbackCoverage,
+        ...(category === undefined ? {} : { category }),
+    }, { knownSensitiveValues: secrets });
+    const redactedFront = parseRetrospectiveFrontMatter(envelope.markdown);
+    validateFeedbackEnvelope(envelope);
+    const report = await runValidator({
+        ...policy,
+        export: 'validateRetrospective',
+        input: {
+            sessionId: context.sessionId,
+            parentSessionId: identity.parentSessionId,
+            mode,
+            workOutcome,
+            // The envelope's copy, which is redacted like the markdown.
+            feedbackCoverage: envelope.feedbackCoverage,
+            repositories,
+            markdown: envelope.markdown,
+            sourceEventId,
+            metadata: {
+                date: redactedFront.date,
+                issues: redactedFront.issues,
+                prs: redactedFront.prs,
+                description: redactedFront.description,
+            },
+        },
+    });
+    if ('errors' in report && report.errors.length)
+        throw new Error(`policy rejected the retrospective:\n- ${report.errors.join('\n- ')}`);
+    const warnings = 'warnings' in report ? report.warnings : [];
+    if (args.dryRun === true)
+        return { markdown: envelope.markdown, policy: { warnings } };
+    const directory = mode === 'interactive' ? outboxDirectory(context.worktree) : undefined;
+    const result = await writeFeedback({
+        identity,
+        envelope,
+        mode,
+        ...(directory === undefined ? {} : { outboxDirectory: directory }),
+        env: context.env,
+        dependencies: context.dependencies,
+    });
+    return { ...deliveryResponse(result, context, mode), policy: { warnings } };
+};

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

@@ -1,6 +1,7 @@
 import { type ToolCallResult } from './dispatch.mts';
 import { type FakeBlackboard, type FakeOptions } from './fake-blackboard.test-helpers.mts';
 import { type RepoFixture } from './git-fixture.test-helpers.mts';
+import type { PolicySpawner } from './policy-spawn.mts';
 /** A fresh pair of real repositories for every test. */
 export declare function useRepoFixture(): () => RepoFixture;
 export declare function outboxPath(worktree: string): string;
@@ -12,6 +13,7 @@ export type Harness = {
 export declare function harness(fixture: RepoFixture, options?: FakeOptions & {
     env?: NodeJS.ProcessEnv;
     launchRoot?: string | undefined;
+    spawnPolicy?: PolicySpawner;
 }): 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

@@ -24,6 +24,7 @@ export function harness(fixture, options = {}) {
         env: options.env ?? BLACKBOARD_ENV,
         runGit: runIsolatedGit,
         blackboard: fake.dependencies,
+        ...(options.spawnPolicy === undefined ? {} : { spawnPolicy: options.spawnPolicy }),
     };
     return { fake, call: (name, args) => callTool(name, args, environment) };
 }

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

@@ -0,0 +1,9 @@
+import { type JournalLoader } from '../agent-blackboard/index.mts';
+import type { BlackboardClientDependencies } from '../agent-blackboard/client.mts';
+/**
+ * Every entry of the session through the server's own blackboard client, or undefined when the
+ * session was never created (the blackboard answers 404). Any other failure is thrown.
+ */
+export declare function readEntriesIfPresent(sessionId: string, env: NodeJS.ProcessEnv, dependencies: BlackboardClientDependencies): Promise<unknown[] | undefined>;
+/** The journal loader `composeRetrospective` takes, reading through the server's own client. */
+export declare function serverJournalLoader(env: NodeJS.ProcessEnv, dependencies: BlackboardClientDependencies): JournalLoader;

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

@@ -0,0 +1,33 @@
+import { readJournal } from "../agent-blackboard/index.mjs";
+function isNotFound(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        (('status' in error && error.status === 404) ||
+            ('statusCode' in error && error.statusCode === 404)));
+}
+/**
+ * Every entry of the session through the server's own blackboard client, or undefined when the
+ * session was never created (the blackboard answers 404). Any other failure is thrown.
+ */
+export async function readEntriesIfPresent(sessionId, env, dependencies) {
+    try {
+        return await readJournal(sessionId, env, dependencies);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+/** The journal loader `composeRetrospective` takes, reading through the server's own client. */
+export function serverJournalLoader(env, dependencies) {
+    return async (sessionId) => {
+        const entries = await readEntriesIfPresent(sessionId, env, dependencies);
+        return entries === undefined
+            ? { status: 'not-found' }
+            : {
+                status: 'ok',
+                entries: entries,
+            };
+    };
+}

package/dist/mcp-server/policy-config.d.mts

@@ -0,0 +1,6 @@
+/**
+ * The real path of the policy module the worktree's package.json declares as
+ * `"vouchington-tooling": { "policy": "<relative path>" }`, or undefined when it declares none.
+ * The path must be relative and, after resolving symlinks, stay inside the worktree.
+ */
+export declare function resolvePolicyModule(worktree: string): Promise<string | undefined>;

package/dist/mcp-server/policy-config.mjs

@@ -0,0 +1,60 @@
+import { readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative, sep } from 'node:path';
+function packagePolicy(worktree, text) {
+    let manifest;
+    try {
+        manifest = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${join(worktree, 'package.json')} is not valid JSON`);
+    }
+    const section = manifest?.['vouchington-tooling'];
+    if (section === undefined)
+        return undefined;
+    // A malformed section must not read as "no policy declared", which would skip validation.
+    if (section === null || typeof section !== 'object' || Array.isArray(section))
+        throw new Error('package.json "vouchington-tooling" must be an object');
+    const policy = section.policy;
+    if (policy === undefined)
+        return undefined;
+    if (typeof policy !== 'string' || !policy.trim())
+        throw new Error('package.json "vouchington-tooling".policy must be a non-empty string path');
+    return policy;
+}
+/**
+ * The real path of the policy module the worktree's package.json declares as
+ * `"vouchington-tooling": { "policy": "<relative path>" }`, or undefined when it declares none.
+ * The path must be relative and, after resolving symlinks, stay inside the worktree.
+ */
+export async function resolvePolicyModule(worktree) {
+    let text;
+    try {
+        text = await readFile(join(worktree, 'package.json'), 'utf8');
+    }
+    catch (error) {
+        // Only a missing manifest means "no policy"; an unreadable one must not silently disable it.
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw new Error(`${join(worktree, 'package.json')} could not be read: ${error.message}`, {
+            cause: error,
+        });
+    }
+    const declared = packagePolicy(worktree, text);
+    if (declared === undefined)
+        return undefined;
+    if (isAbsolute(declared))
+        throw new Error(`policy path ${declared} must be relative`);
+    const root = await realpath(worktree);
+    let resolved;
+    try {
+        resolved = await realpath(join(root, declared));
+    }
+    catch {
+        throw new Error(`policy module ${declared} does not exist in the worktree`);
+    }
+    const inside = relative(root, resolved);
+    // relative(), not a prefix test, so a worktree at the filesystem root still contains its files.
+    if (!inside || inside === '..' || inside.startsWith(`..${sep}`) || isAbsolute(inside))
+        throw new Error(`policy path ${declared} must stay inside the worktree`);
+    return resolved;
+}

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

@@ -0,0 +1,40 @@
+import { type PolicySpawner } from './policy-spawn.mts';
+/** How long each policy export may run before its process is killed, in milliseconds. */
+export declare const POLICY_TIMEOUTS_MS: {
+    readonly validateRetrospective: 30000;
+    readonly validatePullRequest: 120000;
+    readonly pullRequestDefaults: 120000;
+};
+type PolicyExport = keyof typeof POLICY_TIMEOUTS_MS;
+export type PolicyResult = {
+    status: 'no-policy';
+} | {
+    status: 'skipped';
+} | {
+    status: 'ok';
+    result: unknown;
+};
+export type PolicyRun = {
+    worktree: string;
+    export: PolicyExport;
+    input: unknown;
+    env: NodeJS.ProcessEnv;
+    /** Test seam: replaces the real child process. */
+    spawn?: PolicySpawner;
+};
+/**
+ * Runs one export of the worktree's declared policy module in a fresh child process (never in
+ * this one). Resolves `no-policy` when the worktree declares none and `skipped` when the module
+ * lacks the export. A timeout, crash, non-zero exit, oversized output, or unusable reply throws:
+ * a failed policy is never a pass.
+ */
+export declare function runPolicyExport(run: PolicyRun): Promise<PolicyResult>;
+export type ValidatorReport = {
+    errors: string[];
+    warnings: string[];
+};
+/** Runs a validator export and checks its result is `{ errors: string[], warnings?: string[] }`. */
+export declare function runValidator(run: PolicyRun): Promise<ValidatorReport | {
+    status: 'no-policy' | 'skipped';
+}>;
+export {};