vouchington-tooling 0.41.0 → 0.43.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                         pr_validate, pr_create, pr_update,\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,9 @@ 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,
+                         pr_validate, pr_create, pr_update,
+                         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/gh-cli/pr-create.d.mts

@@ -39,6 +39,8 @@ export type BuildGhPrCreateArgsOptions = {
     draft?: boolean;
     head: string;
     labels?: readonly string[];
+    milestone?: string;
+    projects?: readonly string[];
     reviewers?: readonly string[];
     title: string;
 };

package/dist/gh-cli/pr-create.mjs

@@ -53,7 +53,7 @@ export async function assertHeadPushed(runGit, { branch, remote = 'origin' }) {
 }
 /** Pure argv builder for `gh pr create`. `head` is always passed explicitly (never omitted). */
 export function buildGhPrCreateArgs(options) {
-    const { base, bodyFile, draft = false, head, labels = [], reviewers = [], title } = options;
+    const { base, bodyFile, draft = false, head, labels = [], milestone, projects = [], reviewers = [], title, } = options;
     const args = ['pr', 'create', '--title', title, '--body-file', bodyFile, '--head', head];
     if (base !== undefined)
         args.push('--base', base);
@@ -61,6 +61,10 @@ export function buildGhPrCreateArgs(options) {
         args.push('--draft');
     for (const label of labels)
         args.push('--label', label);
+    if (milestone !== undefined)
+        args.push('--milestone', milestone);
+    for (const project of projects)
+        args.push('--project', project);
     for (const reviewer of reviewers)
         args.push('--reviewer', reviewer);
     return args;

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

@@ -1,12 +1,28 @@
 import type { BlackboardClientDependencies } from '../agent-blackboard/client.mts';
 import type { FeedbackIdentity } from '../agent-blackboard/feedback-types.mts';
+import type { RunTextCommand } from '../gh-cli/exec.mts';
+import type { GhRunner } from './pr-gh.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;
+    /** Runs git with the isolated environment; callers add their own `-C <worktree>`. */
+    runGit: RunTextCommand;
+    /** Test seam: replaces locating and running gh. */
+    runGh?: GhRunner;
+    /** Test seam: replaces the operating system user and host name. */
+    device?: () => {
+        user: string;
+        host: string;
+    };
 };
 export type ToolHandler = (args: Args, context: ToolContext) => Promise<Record<string, unknown>>;
 /**
@@ -15,5 +31,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,7 @@
 import type { BlackboardClientDependencies } from '../agent-blackboard/client.mts';
 import type { RunTextCommand } from '../gh-cli/exec.mts';
+import type { GhRunner } from './pr-gh.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 +11,15 @@ 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;
+    /** Test seam: replaces locating and running gh. */
+    runGh?: GhRunner;
+    /** Test seam: replaces the operating system user and host name. */
+    device?: () => {
+        user: string;
+        host: string;
+    };
 };
 export type ToolCallResult = {
     content: Array<{

package/dist/mcp-server/dispatch.mjs

@@ -2,8 +2,10 @@ 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 { handlePrCreate, handlePrUpdate, handlePrValidate } from "./handlers-pr.mjs";
 import { TOOLS } from "./tools.mjs";
 import { resolveWorktree } from "./worktree.mjs";
 const HANDLERS = {
@@ -12,6 +14,11 @@ const HANDLERS = {
     outbox_status: outboxStatus,
     outbox_flush: outboxFlush,
     session_ensure: sessionEnsure,
+    retrospective_check: retrospectiveCheck,
+    retrospective_save: retrospectiveSave,
+    pr_validate: handlePrValidate,
+    pr_create: handlePrCreate,
+    pr_update: handlePrUpdate,
     snapshot_export: snapshotExport,
     session_archive: sessionArchive,
 };
@@ -51,6 +58,11 @@ export async function callTool(name, rawArguments, environment) {
             sessionId,
             worktree,
             env: environment.env,
+            launchRoot: environment.launchRoot,
+            runGit: environment.runGit,
+            ...(environment.runGh === undefined ? {} : { runGh: environment.runGh }),
+            ...(environment.device === undefined ? {} : { device: environment.device }),
+            ...(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-pr.d.mts

@@ -0,0 +1,4 @@
+import { type ToolHandler } from './context.mts';
+export declare const handlePrValidate: ToolHandler;
+export declare const handlePrCreate: ToolHandler;
+export declare const handlePrUpdate: ToolHandler;

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

@@ -0,0 +1,143 @@
+import { hostname, userInfo } from 'node:os';
+import { validateGitHubBodyLength } from "../gh-cli/body-length.mjs";
+import { createPullRequest } from "../gh-cli/pr-create.mjs";
+import { assertPolicyAllowed } from "./context.mjs";
+import { runValidator } from "./policy-run.mjs";
+import { renderPullRequestBody, worktreeLabel } from "./pr-body.mjs";
+import { pullRequestNumber, withBodyFile } from "./pr-body-file.mjs";
+import { pullRequestDefaults } from "./pr-defaults.mjs";
+import { createGhRunner, ghEnvironment } from "./pr-gh.mjs";
+import { checkTitleLength, positiveInteger, readPullRequestInput, } from "./pr-input.mjs";
+import { preserveShepherdJournal } from "./pr-journal.mjs";
+import { assertJournalUnchanged, credentials, liveBase, livePullRequest, redactCredentials, } from "./pr-live.mjs";
+import { parseWorktreeList } from "./worktree.mjs";
+function gitIn(context) {
+    return (args) => context.runGit(['-C', context.worktree, ...args]);
+}
+function ghIn(context) {
+    const run = context.runGh ?? createGhRunner(context.env);
+    const env = ghEnvironment(context.env);
+    return (args) => run(args, { cwd: context.worktree, env });
+}
+async function currentBranch(git) {
+    const branch = (await git(['rev-parse', '--abbrev-ref', 'HEAD'])).trim();
+    if (branch === 'HEAD')
+        throw new Error('the worktree has a detached HEAD: check out a branch');
+    return branch;
+}
+async function label(context, git) {
+    const listing = await git(['worktree', 'list', '--porcelain', '-z']);
+    return worktreeLabel(context.worktree, parseWorktreeList(listing)[0]);
+}
+function readPr(args, required) {
+    if (args.pr === undefined && !required)
+        return undefined;
+    return positiveInteger(args.pr, 'pr');
+}
+function policyFor(context) {
+    return {
+        worktree: context.worktree,
+        env: context.env,
+        ...(context.spawnPolicy === undefined ? {} : { spawn: context.spawnPolicy }),
+    };
+}
+/** Renders the body, preserves the live journal for an update, and runs the policy validator. */
+async function prepare(args, context, pr) {
+    assertPolicyAllowed(context);
+    // No server credential may reach the policy or gh, whatever the caller wrote: every field is
+    // redacted before anything is rendered or forwarded.
+    const secrets = credentials(context.env);
+    const given = redactCredentials(readPullRequestInput(args), secrets);
+    checkTitleLength(given.title);
+    const git = gitIn(context);
+    const head = await currentBranch(git);
+    // Branch names are refs passed to gh as is: redacting one would name a branch that does not exist.
+    if (secrets.some((secret) => head.includes(secret)))
+        throw new Error('the worktree branch name contains a server credential: rename the branch');
+    if (secrets.some((secret) => args.base?.includes(secret)))
+        throw new Error('base contains a server credential: use another base branch');
+    const live = pr === undefined ? undefined : await livePullRequest(ghIn(context), pr);
+    if (live !== undefined && live.headRefName !== head)
+        throw new Error(`pull request ${pr} has head ${live.headRefName}, not the worktree branch ${head}`);
+    const base = live === undefined
+        ? given.base
+        : liveBase(pr, live, redactCredentials(args.base, secrets));
+    const input = { ...given, base };
+    if (head === base)
+        throw new Error(`head branch ${head} must differ from base ${base}`);
+    const device = (context.device ?? (() => ({ user: userInfo().username, host: hostname() })))();
+    let body = renderPullRequestBody(input, {
+        sessionId: context.sessionId,
+        ...device,
+        worktree: await label(context, git),
+    });
+    if (live !== undefined)
+        body = preserveShepherdJournal(body, live.body);
+    body = redactCredentials(body, secrets);
+    const length = validateGitHubBodyLength(body);
+    if (!length.ok)
+        throw new Error(`the rendered body has ${length.characterCount} characters; GitHub allows ${length.maxCharacterCount}`);
+    const report = await runValidator({
+        ...policyFor(context),
+        export: 'validatePullRequest',
+        input: {
+            title: input.title,
+            body,
+            base: input.base,
+            head,
+            mode: input.mode,
+            ...(pr === undefined ? {} : { pr }),
+        },
+    });
+    const errors = 'errors' in report ? report.errors : [];
+    const warnings = 'warnings' in report ? report.warnings : [];
+    return {
+        input,
+        head,
+        body,
+        errors,
+        warnings,
+        ...(live === undefined ? {} : { liveBody: live.body }),
+    };
+}
+function rejectErrors(prepared) {
+    if (prepared.errors.length)
+        throw new Error(`policy rejected the pull request:\n- ${prepared.errors.join('\n- ')}`);
+}
+export const handlePrValidate = async (args, context) => {
+    const { body, errors, warnings } = await prepare(args, context, readPr(args, false));
+    return { body, errors, warnings };
+};
+export const handlePrCreate = async (args, context) => {
+    const prepared = await prepare(args, context, undefined);
+    rejectErrors(prepared);
+    const { input, head, body } = prepared;
+    const defaults = await pullRequestDefaults(policyFor(context), input);
+    const url = await withBodyFile(body, (bodyFile) => createPullRequest({ runGh: ghIn(context), runGit: gitIn(context) }, {
+        bodyFile,
+        draft: true,
+        title: input.title,
+        base: input.base,
+        head,
+        labels: defaults.labels,
+        ...(defaults.milestone === undefined ? {} : { milestone: defaults.milestone }),
+        ...(defaults.project === undefined ? {} : { projects: [defaults.project] }),
+    }));
+    return { number: pullRequestNumber(url), url, warnings: prepared.warnings };
+};
+export const handlePrUpdate = async (args, context) => {
+    const pr = readPr(args, true);
+    const prepared = await prepare(args, context, pr);
+    rejectErrors(prepared);
+    await assertJournalUnchanged(ghIn(context), pr, prepared.liveBody, prepared.input.base);
+    const url = await withBodyFile(prepared.body, async (bodyFile) => (await ghIn(context)([
+        'pr',
+        'edit',
+        String(pr),
+        '--title',
+        prepared.input.title,
+        '--body-file',
+        bodyFile,
+    ])).trim());
+    return { number: pr, url, warnings: prepared.warnings };
+};

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;