vouchington-tooling 0.42.0 → 0.43.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  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 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

@@ -127,6 +127,7 @@ agent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH
 mcp
   (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,
                          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,5 +1,7 @@
 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. */
@@ -12,6 +14,15 @@ export type ToolContext = {
     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>>;
 /**

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 { 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. */
@@ -12,6 +13,13 @@ export type ServerEnvironment = {
     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

@@ -5,6 +5,7 @@ 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 = {
@@ -15,6 +16,9 @@ const HANDLERS = {
     session_ensure: sessionEnsure,
     retrospective_check: retrospectiveCheck,
     retrospective_save: retrospectiveSave,
+    pr_validate: handlePrValidate,
+    pr_create: handlePrCreate,
+    pr_update: handlePrUpdate,
     snapshot_export: snapshotExport,
     session_archive: sessionArchive,
 };
@@ -55,6 +59,9 @@ export async function callTool(name, rawArguments, environment) {
             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: {

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/harness.test-helpers.d.mts

@@ -1,6 +1,7 @@
-import { type ToolCallResult } from './dispatch.mts';
+import { type ServerEnvironment, 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 { GhRunner } from './pr-gh.mts';
 import type { PolicySpawner } from './policy-spawn.mts';
 /** A fresh pair of real repositories for every test. */
 export declare function useRepoFixture(): () => RepoFixture;
@@ -14,6 +15,12 @@ export declare function harness(fixture: RepoFixture, options?: FakeOptions & {
     env?: NodeJS.ProcessEnv;
     launchRoot?: string | undefined;
     spawnPolicy?: PolicySpawner;
+    runGit?: ServerEnvironment['runGit'];
+    runGh?: GhRunner;
+    device?: () => {
+        user: string;
+        host: string;
+    };
 }): 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

@@ -22,9 +22,11 @@ export function harness(fixture, options = {}) {
     const environment = {
         launchRoot: 'launchRoot' in options ? options.launchRoot : fixture.main,
         env: options.env ?? BLACKBOARD_ENV,
-        runGit: runIsolatedGit,
+        runGit: options.runGit ?? runIsolatedGit,
         blackboard: fake.dependencies,
         ...(options.spawnPolicy === undefined ? {} : { spawnPolicy: options.spawnPolicy }),
+        ...(options.runGh === undefined ? {} : { runGh: options.runGh }),
+        ...(options.device === undefined ? {} : { device: options.device }),
     };
     return { fake, call: (name, args) => callTool(name, args, environment) };
 }

package/dist/mcp-server/pr-body-file.d.mts

@@ -0,0 +1,4 @@
+/** Writes the body to a private temp file for the duration of `use`, then removes it. */
+export declare function withBodyFile<T>(body: string, use: (file: string) => Promise<T>): Promise<T>;
+/** The pull request number at the end of the URL `gh pr create` prints. */
+export declare function pullRequestNumber(url: string): number;

package/dist/mcp-server/pr-body-file.mjs

@@ -0,0 +1,22 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** Writes the body to a private temp file for the duration of `use`, then removes it. */
+export async function withBodyFile(body, use) {
+    const directory = await mkdtemp(join(tmpdir(), 'vouchington-pr-'));
+    try {
+        const file = join(directory, 'body.md');
+        await writeFile(file, body, { mode: 0o600 });
+        return await use(file);
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+/** The pull request number at the end of the URL `gh pr create` prints. */
+export function pullRequestNumber(url) {
+    const match = /\/pull\/(\d+)\s*$/.exec(url);
+    if (!match)
+        throw new Error(`could not read the pull request number from: ${url}`);
+    return Number(match[1]);
+}

package/dist/mcp-server/pr-body.d.mts

@@ -0,0 +1,20 @@
+import type { PullRequestInput } from './pr-input.mts';
+export type PullRequestProvenance = {
+    sessionId: string;
+    /** The operating system user name. */
+    user: string;
+    /** The host name; lowercased when rendered. */
+    host: string;
+    /** The checkout label, see {@link worktreeLabel}. */
+    worktree: string;
+};
+/**
+ * The pull request body: the Summary, Impact, Related issues and Details sections followed by the
+ * provenance lines. Pure; the caller supplies the device and worktree facts.
+ */
+export declare function renderPullRequestBody(input: PullRequestInput, provenance: PullRequestProvenance): string;
+/**
+ * The worktree label: the path after `/worktrees/` when present, `main` for the repository's main
+ * worktree, else the directory name.
+ */
+export declare function worktreeLabel(worktree: string, mainWorktree: string | undefined): string;

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

@@ -0,0 +1,47 @@
+import { basename } from 'node:path';
+function relatedLine(issue) {
+    const verb = issue.relation === 'closes' ? 'Closes' : 'Refs';
+    return `- ${verb} #${issue.number} — ${issue.reason}`;
+}
+/**
+ * The pull request body: the Summary, Impact, Related issues and Details sections followed by the
+ * provenance lines. Pure; the caller supplies the device and worktree facts.
+ */
+export function renderPullRequestBody(input, provenance) {
+    const related = input.relatedIssues.length ? input.relatedIssues.map(relatedLine) : ['- None'];
+    const agent = input.model === undefined ? input.agent : `${input.agent} (${input.model})`;
+    return [
+        '## Summary',
+        '',
+        input.summary,
+        '',
+        '## Impact',
+        '',
+        input.impact,
+        '',
+        '## Related issues',
+        '',
+        ...related,
+        '',
+        '## Details',
+        '',
+        input.details.join('\n\n'),
+        '',
+        `Workspace setup: ${input.workspaceSetup}`,
+        `Agent: ${agent} session ${provenance.sessionId}`,
+        `Device: ${provenance.user}@${provenance.host.toLowerCase()}`,
+        `Worktree: ${provenance.worktree}`,
+        '',
+    ].join('\n');
+}
+const MARKER = '/worktrees/';
+/**
+ * The worktree label: the path after `/worktrees/` when present, `main` for the repository's main
+ * worktree, else the directory name.
+ */
+export function worktreeLabel(worktree, mainWorktree) {
+    const marker = worktree.indexOf(MARKER);
+    if (marker !== -1)
+        return worktree.slice(marker + MARKER.length);
+    return worktree === mainWorktree ? 'main' : basename(worktree);
+}

package/dist/mcp-server/pr-defaults.d.mts

@@ -0,0 +1,16 @@
+import { type PolicyRun } from './policy-run.mts';
+import type { RelatedIssue } from './pr-input.mts';
+export type PullRequestDefaults = {
+    labels: string[];
+    milestone?: string;
+    project?: string;
+};
+/**
+ * Labels, milestone and project from the policy's `pullRequestDefaults` export; empty when the
+ * checkout declares no policy or the policy lacks the export.
+ */
+export declare function pullRequestDefaults(policy: Omit<PolicyRun, 'export' | 'input'>, input: {
+    title: string;
+    base: string;
+    relatedIssues: RelatedIssue[];
+}): Promise<PullRequestDefaults>;

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

@@ -0,0 +1,35 @@
+import { runPolicyExport } from "./policy-run.mjs";
+function optionalName(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`policy pullRequestDefaults ${field} must be a non-empty string`);
+    return value;
+}
+/**
+ * Labels, milestone and project from the policy's `pullRequestDefaults` export; empty when the
+ * checkout declares no policy or the policy lacks the export.
+ */
+export async function pullRequestDefaults(policy, input) {
+    const { title, base, relatedIssues } = input;
+    const outcome = await runPolicyExport({
+        ...policy,
+        export: 'pullRequestDefaults',
+        input: { title, base, relatedIssues },
+    });
+    if (outcome.status !== 'ok')
+        return { labels: [] };
+    const result = (outcome.result ?? {});
+    if (typeof result !== 'object' || Array.isArray(result))
+        throw new Error('policy pullRequestDefaults must return an object');
+    const labels = result.labels ?? [];
+    if (!Array.isArray(labels) || labels.some((label) => typeof label !== 'string' || !label.trim()))
+        throw new Error('policy pullRequestDefaults labels must be an array of non-empty strings');
+    const milestone = optionalName(result.milestone, 'milestone');
+    const project = optionalName(result.project, 'project');
+    return {
+        labels: labels,
+        ...(milestone === undefined ? {} : { milestone }),
+        ...(project === undefined ? {} : { project }),
+    };
+}

package/dist/mcp-server/pr-gh.d.mts

@@ -0,0 +1,16 @@
+export type GhRunner = (args: string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}) => Promise<string>;
+/**
+ * `gh` on the server's PATH, else a common absolute location. Relative PATH entries are skipped:
+ * gh runs with the target worktree as cwd, where a relative path could name a checkout file.
+ */
+export declare function locateGh(env: NodeJS.ProcessEnv, fallbacks?: readonly string[]): Promise<string>;
+/**
+ * The environment gh runs in: the server's, without the blackboard credentials, and without
+ * GH_REPO, which would point gh at a repository other than the validated worktree's.
+ */
+export declare function ghEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** A runner that locates gh once, on first use, from the server's environment. */
+export declare function createGhRunner(serverEnv: NodeJS.ProcessEnv, locate?: (env: NodeJS.ProcessEnv) => Promise<string>): GhRunner;

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

@@ -0,0 +1,56 @@
+import { execFile } from 'node:child_process';
+import { constants } from 'node:fs';
+import { access, stat } from 'node:fs/promises';
+import { delimiter, isAbsolute, join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const FALLBACKS = ['/opt/homebrew/bin/gh', '/usr/local/bin/gh', '/usr/bin/gh'];
+const MAX_BUFFER_BYTES = 16_000_000;
+/** The longest one gh call may run before it is killed. */
+const GH_TIMEOUT_MS = 120_000;
+async function isExecutableFile(path) {
+    try {
+        await access(path, constants.X_OK);
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `gh` on the server's PATH, else a common absolute location. Relative PATH entries are skipped:
+ * gh runs with the target worktree as cwd, where a relative path could name a checkout file.
+ */
+export async function locateGh(env, fallbacks = FALLBACKS) {
+    const onPath = (env.PATH ?? '')
+        .split(delimiter)
+        .filter((directory) => isAbsolute(directory))
+        .map((directory) => join(directory, 'gh'));
+    for (const candidate of [...onPath, ...fallbacks])
+        if (await isExecutableFile(candidate))
+            return candidate;
+    throw new Error("gh CLI not found on PATH; install gh or add it to the server's PATH");
+}
+/**
+ * The environment gh runs in: the server's, without the blackboard credentials, and without
+ * GH_REPO, which would point gh at a repository other than the validated worktree's.
+ */
+export function ghEnvironment(env) {
+    const { AGENT_BLACKBOARD_URL: _url, AGENT_BLACKBOARD_TOKEN: _token, GH_REPO: _repo, ...rest } = env;
+    return rest;
+}
+/** A runner that locates gh once, on first use, from the server's environment. */
+export function createGhRunner(serverEnv, locate = locateGh) {
+    let located;
+    return async (args, options) => {
+        located ??= locate(serverEnv);
+        const { stdout } = await execFileAsync(await located, args, {
+            cwd: options.cwd,
+            env: options.env,
+            maxBuffer: MAX_BUFFER_BYTES,
+            timeout: GH_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
+        });
+        return stdout;
+    };
+}

package/dist/mcp-server/pr-input.d.mts

@@ -0,0 +1,26 @@
+import { type Args } from './args.mts';
+declare const PR_MODES: readonly ["interactive", "autonomous"];
+export type RelatedIssue = {
+    number: number;
+    relation: 'closes' | 'refs';
+    reason: string;
+};
+export type PullRequestInput = {
+    title: string;
+    summary: string;
+    impact: string;
+    relatedIssues: RelatedIssue[];
+    details: string[];
+    base: string;
+    agent: string;
+    model?: string;
+    mode: (typeof PR_MODES)[number];
+    workspaceSetup: string;
+};
+/** A positive integer argument, such as a pull request number or an issue number. */
+export declare function positiveInteger(value: unknown, label: string): number;
+/** Rechecked after redaction, which can lengthen a title. */
+export declare function checkTitleLength(title: string): void;
+/** Reads and validates the structured pull request fields shared by the three pr_* tools. */
+export declare function readPullRequestInput(args: Args): PullRequestInput;
+export {};

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

@@ -0,0 +1,62 @@
+import { optionalString, rejectUnknown, requireObject, requiredChoice, requiredString, requiredStringArray, } from "./args.mjs";
+const PR_MODES = ['interactive', 'autonomous'];
+const RELATIONS = ['closes', 'refs'];
+const MAX_TITLE_CHARACTERS = 256;
+/** A positive integer argument, such as a pull request number or an issue number. */
+export function positiveInteger(value, label) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1)
+        throw new Error(`${label} must be a positive integer`);
+    return value;
+}
+function readRelatedIssues(args) {
+    const value = args.relatedIssues;
+    if (!Array.isArray(value))
+        throw new Error('relatedIssues is required and must be an array');
+    return value.map((item, index) => {
+        const issue = requireObject(item);
+        rejectUnknown(issue, ['number', 'relation', 'reason']);
+        return {
+            number: positiveInteger(issue.number, `relatedIssues[${index}].number`),
+            relation: requiredChoice(issue, 'relation', RELATIONS),
+            reason: requiredString(issue, 'reason'),
+        };
+    });
+}
+function readDetails(args) {
+    const details = requiredStringArray(args, 'details');
+    details.forEach((detail, index) => {
+        if (!detail.trim())
+            throw new Error(`details[${index}] must not be empty`);
+    });
+    return details;
+}
+/** Rechecked after redaction, which can lengthen a title. */
+export function checkTitleLength(title) {
+    if (Array.from(title).length > MAX_TITLE_CHARACTERS)
+        throw new Error(`title must be at most ${MAX_TITLE_CHARACTERS} characters`);
+}
+function singleLine(args, key) {
+    const value = requiredString(args, key);
+    if (/[\r\n]/.test(value))
+        throw new Error(`${key} must be a single line`);
+    return value;
+}
+/** Reads and validates the structured pull request fields shared by the three pr_* tools. */
+export function readPullRequestInput(args) {
+    const title = singleLine(args, 'title');
+    checkTitleLength(title);
+    const model = args.model === undefined ? undefined : singleLine(args, 'model');
+    return {
+        title,
+        summary: requiredString(args, 'summary'),
+        impact: requiredString(args, 'impact'),
+        relatedIssues: readRelatedIssues(args),
+        details: readDetails(args),
+        base: optionalString(args, 'base') ?? 'main',
+        agent: singleLine(args, 'agent'),
+        ...(model === undefined ? {} : { model }),
+        mode: requiredChoice(args, 'mode', PR_MODES),
+        // It renders on its own provenance line; a newline would forge the lines after it.
+        workspaceSetup: singleLine(args, 'workspaceSetup'),
+    };
+}

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

@@ -0,0 +1,12 @@
+/**
+ * The Shepherd Journal of a pull request body, verbatim: a `<details>` block whose summary is
+ * "Shepherd Journal", else a legacy `## Shepherd Journal` section running to the next H2 or the
+ * end. Examples inside fenced code blocks are ignored. Undefined when the body has none; more than
+ * one candidate, or an unclosed one, is ambiguous and throws rather than guessing.
+ */
+export declare function findShepherdJournal(body: string): string | undefined;
+/**
+ * Appends the live body's journal to `rendered`. The rendered fields must not carry a journal of
+ * their own, and must not leave a code fence open: the journal would be hidden inside it.
+ */
+export declare function preserveShepherdJournal(rendered: string, live: string): string;

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

@@ -0,0 +1,86 @@
+const DETAILS_OPEN = /<details(?:\s[^>]*)?>/gi;
+const DETAILS_CLOSE = /<\/details>/gi;
+const SUMMARY = '<summary>Shepherd Journal</summary>';
+/** An ATX H2 "Shepherd Journal", with optional indent and closing hashes. */
+const LEGACY = /^ {0,3}##[ \t]+Shepherd[ \t]+Journal(?:[ \t]+#+)?[ \t]*$/;
+/** A real ATX H2: `##` then whitespace or the end of the line (so not `###` or `##text`). */
+const H2 = /^ {0,3}##(?:[ \t]|$)/;
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+/** A closing fence carries nothing but whitespace after its marker. */
+const CLOSING_FENCE = /^ {0,3}(`{3,}|~{3,})[ \t]*$/;
+const count = (line, expression) => [...line.matchAll(expression)].length;
+/**
+ * The lines with every fenced code block blanked, so journal-shaped examples there never match,
+ * and whether the text ends inside a fence that never closed.
+ */
+function outsideFences(lines) {
+    let fence;
+    const visible = lines.map((line) => {
+        if (fence === undefined) {
+            const marker = FENCE.exec(line)?.[1];
+            if (marker === undefined)
+                return line;
+            fence = marker;
+            return '';
+        }
+        const marker = CLOSING_FENCE.exec(line)?.[1];
+        if (marker !== undefined && marker[0] === fence[0] && marker.length >= fence.length)
+            fence = undefined;
+        return '';
+    });
+    return { visible, open: fence !== undefined };
+}
+function detailsStarts(lines) {
+    return lines.flatMap((line, index) => line.trim() === SUMMARY && lines[index - 1]?.trim() === '<details>' ? [index] : []);
+}
+/** Depth is tracked on the fence-blanked lines; the block is sliced from the original ones. */
+function detailsBlock(lines, visible, start) {
+    let depth = 1;
+    for (const [index, line] of visible.entries()) {
+        if (index < start)
+            continue;
+        depth += count(line, DETAILS_OPEN) - count(line, DETAILS_CLOSE);
+        if (depth <= 0)
+            return lines.slice(start - 1, index + 1);
+    }
+    // Treating an unclosed journal as absent would let an update overwrite its history.
+    throw new Error('the Shepherd Journal <details> block is never closed; repair it by hand');
+}
+function legacySection(lines, visible, start) {
+    const next = visible.findIndex((line, index) => index > start && H2.test(line));
+    const section = lines.slice(start, next === -1 ? lines.length : next);
+    while (section.at(-1)?.trim() === '')
+        section.pop();
+    return section;
+}
+/**
+ * The Shepherd Journal of a pull request body, verbatim: a `<details>` block whose summary is
+ * "Shepherd Journal", else a legacy `## Shepherd Journal` section running to the next H2 or the
+ * end. Examples inside fenced code blocks are ignored. Undefined when the body has none; more than
+ * one candidate, or an unclosed one, is ambiguous and throws rather than guessing.
+ */
+export function findShepherdJournal(body) {
+    const lines = body.replaceAll('\r\n', '\n').split('\n');
+    const { visible } = outsideFences(lines);
+    const details = detailsStarts(visible);
+    const legacy = visible.flatMap((line, index) => (LEGACY.test(line) ? [index] : []));
+    if (details.length + legacy.length > 1)
+        throw new Error('the pull request body has more than one Shepherd Journal; resolve it by hand');
+    if (details.length === 1)
+        return detailsBlock(lines, visible, details[0]).join('\n');
+    return legacy.length === 1 ? legacySection(lines, visible, legacy[0]).join('\n') : undefined;
+}
+/**
+ * Appends the live body's journal to `rendered`. The rendered fields must not carry a journal of
+ * their own, and must not leave a code fence open: the journal would be hidden inside it.
+ */
+export function preserveShepherdJournal(rendered, live) {
+    if (findShepherdJournal(rendered) !== undefined)
+        throw new Error('the pull request fields contain a Shepherd Journal; the server preserves the live one');
+    const journal = findShepherdJournal(live);
+    if (journal === undefined)
+        return rendered;
+    if (outsideFences(rendered.replaceAll('\r\n', '\n').split('\n')).open)
+        throw new Error('the pull request fields leave a code fence open; close it');
+    return `${rendered.trimEnd()}\n\n${journal}\n`;
+}

package/dist/mcp-server/pr-live.d.mts

@@ -0,0 +1,24 @@
+import type { RunTextCommand } from '../gh-cli/exec.mts';
+export type LivePullRequest = {
+    body: string;
+    headRefName: string;
+    baseRefName: string;
+    state: string;
+};
+/** The live pull request as gh reports it, rejected unless it is open. */
+export declare function livePullRequest(gh: RunTextCommand, pr: number): Promise<LivePullRequest>;
+/**
+ * The base to validate an existing pull request against: its live base. An explicit `base` that
+ * differs is rejected, because `gh pr edit` here changes only the title and body.
+ */
+export declare function liveBase(pr: number, live: LivePullRequest, given: string | undefined): string;
+/**
+ * Re-reads the live pull request just before the edit and aborts if its Shepherd Journal or base
+ * changed since the body was prepared and validated, so an entry appended in between is never
+ * overwritten and a retargeted PR never gets a body validated against its old base.
+ */
+export declare function assertJournalUnchanged(gh: RunTextCommand, pr: number, preparedFrom: string, base: string): Promise<void>;
+/** The server's credential values that must never reach the policy or GitHub, longest first. */
+export declare function credentials(env: NodeJS.ProcessEnv): string[];
+/** Replaces every server credential in every string of a JSON-shaped value. */
+export declare function redactCredentials<T>(value: T, secrets: string[]): T;

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

@@ -0,0 +1,49 @@
+import { findShepherdJournal } from "./pr-journal.mjs";
+const FIELDS = ['body', 'headRefName', 'baseRefName', 'state'];
+/** The live pull request as gh reports it, rejected unless it is open. */
+export async function livePullRequest(gh, pr) {
+    const output = await gh(['pr', 'view', String(pr), '--json', FIELDS.join(',')]);
+    const live = JSON.parse(output);
+    if (!isLive(live))
+        throw new Error(`gh pr view ${pr} did not return ${FIELDS.join(', ')}`);
+    // A closed or merged PR can share a reused branch name; its history must not be rewritten.
+    if (live.state !== 'OPEN')
+        throw new Error(`pull request ${pr} is ${live.state}, not OPEN`);
+    return live;
+}
+function isLive(value) {
+    return FIELDS.every((field) => typeof value?.[field] === 'string');
+}
+/**
+ * The base to validate an existing pull request against: its live base. An explicit `base` that
+ * differs is rejected, because `gh pr edit` here changes only the title and body.
+ */
+export function liveBase(pr, live, given) {
+    if (given !== undefined && given !== live.baseRefName)
+        throw new Error(`pull request ${pr} targets ${live.baseRefName}, not ${given}`);
+    return live.baseRefName;
+}
+/**
+ * Re-reads the live pull request just before the edit and aborts if its Shepherd Journal or base
+ * changed since the body was prepared and validated, so an entry appended in between is never
+ * overwritten and a retargeted PR never gets a body validated against its old base.
+ */
+export async function assertJournalUnchanged(gh, pr, preparedFrom, base) {
+    const now = await livePullRequest(gh, pr);
+    if (now.baseRefName !== base)
+        throw new Error(`pull request ${pr} was retargeted to ${now.baseRefName}; run pr_update again`);
+    if (findShepherdJournal(now.body) !== findShepherdJournal(preparedFrom))
+        throw new Error(`the Shepherd Journal of pull request ${pr} changed meanwhile; run pr_update again`);
+}
+/** The server's credential values that must never reach the policy or GitHub, longest first. */
+export function credentials(env) {
+    const values = [env.AGENT_BLACKBOARD_TOKEN, env.GH_TOKEN, env.GITHUB_TOKEN].filter((value) => value !== undefined && value.length >= 4);
+    return [...new Set(values)].sort((a, b) => b.length - a.length);
+}
+/** Replaces every server credential in every string of a JSON-shaped value. */
+export function redactCredentials(value, secrets) {
+    if (value === undefined || secrets.length === 0)
+        return value;
+    const json = secrets.reduce((text, secret) => text.split(JSON.stringify(secret).slice(1, -1)).join('[REDACTED]'), JSON.stringify(value));
+    return JSON.parse(json);
+}

package/dist/mcp-server/pr-tools.test-helpers.d.mts

@@ -0,0 +1,54 @@
+import type { RepoFixture } from './git-fixture.test-helpers.mts';
+import type { GhRunner } from './pr-gh.mts';
+import type { PolicyOutcome, PolicyRequest } from './policy-spawn.mts';
+export declare const PR_ARGS: {
+    sessionId: string;
+    title: string;
+    summary: string;
+    impact: string;
+    relatedIssues: {
+        number: number;
+        relation: string;
+        reason: string;
+    }[];
+    details: string[];
+    base: string;
+    agent: string;
+    mode: string;
+    workspaceSetup: string;
+};
+export declare function declarePolicy(fixture: RepoFixture): void;
+type Reply = (name: string, input: Record<string, unknown>) => unknown;
+export declare function policy(reply: Reply): {
+    requests: {
+        name: string;
+        input: Record<string, unknown>;
+    }[];
+    spawnPolicy: (request: PolicyRequest) => Promise<PolicyOutcome>;
+};
+type GhCall = {
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    body?: string;
+};
+/** A fake gh: records calls (reading any --body-file while it still exists) and replies by verb. */
+export declare function fakeGh(replies?: {
+    view?: unknown;
+    create?: string;
+    edit?: string;
+}): {
+    calls: GhCall[];
+    bodyFiles: {
+        path: string;
+        mode: number;
+    }[];
+    runGh: GhRunner;
+};
+export declare const device: () => {
+    user: string;
+    host: string;
+};
+/** Gives the fixture an `origin` that already has the linked branch at its current commit. */
+export declare function usePushedRemote(fixture: () => RepoFixture): void;
+export {};

package/dist/mcp-server/pr-tools.test-helpers.mjs

@@ -0,0 +1,67 @@
+import { readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { beforeEach } from 'vitest';
+export const PR_ARGS = {
+    sessionId: 'native:owner',
+    title: 'Add the thing',
+    summary: 'Adds the thing.',
+    impact: 'Nobody breaks.',
+    relatedIssues: [{ number: 7, relation: 'closes', reason: 'tracks the work' }],
+    details: ['First paragraph.', '- a bullet'],
+    base: 'trunk',
+    agent: 'codex',
+    mode: 'autonomous',
+    workspaceSetup: 'fresh worktree',
+};
+export function declarePolicy(fixture) {
+    writeFileSync(join(fixture.linked, 'package.json'), JSON.stringify({ 'vouchington-tooling': { policy: 'policy.mts' } }));
+    writeFileSync(join(fixture.linked, 'policy.mts'), '');
+}
+export function policy(reply) {
+    const requests = [];
+    const spawnPolicy = async (request) => {
+        const { export: name, input } = JSON.parse(request.input);
+        requests.push({ name, input });
+        const result = reply(name, input);
+        const stdout = result === undefined ? { ok: true, skipped: true } : { ok: true, result };
+        return {
+            exitCode: 0,
+            stdout: JSON.stringify(stdout),
+            stderr: '',
+            timedOut: false,
+            overflowed: false,
+        };
+    };
+    return { requests, spawnPolicy };
+}
+/** A fake gh: records calls (reading any --body-file while it still exists) and replies by verb. */
+export function fakeGh(replies = {}) {
+    const calls = [];
+    const bodyFiles = [];
+    const runGh = async (args, options) => {
+        const call = { args, ...options };
+        const file = args[args.indexOf('--body-file') + 1];
+        if (args.includes('--body-file') && file !== undefined) {
+            call.body = readFileSync(file, 'utf8');
+            bodyFiles.push({ path: file, mode: statSync(file).mode & 0o777 });
+        }
+        calls.push(call);
+        if (args[1] === 'view')
+            return JSON.stringify(replies.view);
+        if (args[1] === 'create')
+            return replies.create ?? 'https://github.com/o/r/pull/12\n';
+        return replies.edit ?? 'https://github.com/o/r/pull/5\n';
+    };
+    return { calls, bodyFiles, runGh };
+}
+export const device = () => ({ user: 'Jong', host: 'Laptop.Local' });
+/** Gives the fixture an `origin` that already has the linked branch at its current commit. */
+export function usePushedRemote(fixture) {
+    beforeEach(() => {
+        const f = fixture();
+        const origin = join(f.root, 'origin.git');
+        f.git(f.root, 'init', '--quiet', '--bare', origin);
+        f.git(f.linked, 'remote', 'add', 'origin', origin);
+        f.git(f.linked, 'push', '--quiet', 'origin', 'linked');
+    });
+}

package/dist/mcp-server/tools-pr.d.mts

@@ -0,0 +1,2 @@
+import { type ToolDefinition } from './tools-schema.mts';
+export declare const PR_TOOLS: readonly ToolDefinition[];

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

@@ -0,0 +1,69 @@
+import { ADDITIVE, MUTATING, READ_ONLY, tool, } from "./tools-schema.mjs";
+/** These tools read or write GitHub, outside the server's own state. */
+const openWorld = (annotations) => ({
+    ...annotations,
+    openWorldHint: true,
+});
+const text = (description) => ({ type: 'string', minLength: 1, description });
+const PR_NUMBER = { type: 'integer', minimum: 1, description: 'Pull request number.' };
+const FIELDS = {
+    title: { type: 'string', minLength: 1, maxLength: 256, description: 'Single-line PR title.' },
+    summary: text('What the change does, as markdown.'),
+    impact: text('Who or what is affected, as markdown.'),
+    relatedIssues: {
+        type: 'array',
+        description: 'Issues this pull request closes or refs; may be empty.',
+        items: {
+            type: 'object',
+            properties: {
+                number: { type: 'integer', minimum: 1 },
+                relation: { enum: ['closes', 'refs'] },
+                reason: text('Why the issue is related.'),
+            },
+            required: ['number', 'relation', 'reason'],
+            additionalProperties: false,
+        },
+    },
+    details: {
+        type: 'array',
+        minItems: 1,
+        items: { type: 'string', minLength: 1 },
+        description: 'Markdown paragraphs or bullets, joined by blank lines.',
+    },
+    base: { type: 'string', minLength: 1, description: 'Base branch. Default: main.' },
+    agent: text('Agent name for the Agent line.'),
+    model: text('Optional model name, rendered in parentheses after the agent.'),
+    mode: { enum: ['interactive', 'autonomous'], description: 'Delivery mode, given to the policy.' },
+    workspaceSetup: text('Text for the Workspace setup line, such as how the worktree was prepared.'),
+};
+const REQUIRED = [
+    'title',
+    'summary',
+    'impact',
+    'relatedIssues',
+    'details',
+    'agent',
+    'mode',
+    'workspaceSetup',
+];
+const RENDERING = 'The server renders the body from the structured input (Summary, Impact, Related issues, ' +
+    'Details, then Workspace setup, Agent, Device and Worktree lines) and runs the checkout ' +
+    'policy validatePullRequest export in a child process; the head branch is the ' +
+    "worktree's current branch. Policy tools need a server launched inside a repository worktree. ";
+export const PR_TOOLS = [
+    tool('pr_validate', 'Renders the pull request body and validates it with the checkout policy; writes nothing. ' +
+        RENDERING +
+        'Pass pr to validate an update of that pull request: the live body is read and its Shepherd ' +
+        'Journal preserved. Returns { body, errors, warnings }.', openWorld(READ_ONLY), { ...FIELDS, pr: PR_NUMBER }, REQUIRED),
+    tool('pr_create', 'Creates a draft pull request from the worktree branch. ' +
+        RENDERING +
+        'Validation errors block creation. The policy pullRequestDefaults export may add labels, a ' +
+        'milestone and a project. The branch must already be pushed and current. It sees no stack ' +
+        'membership, so a policy may reject a non-default base; create stacked layers with the ' +
+        "repository's stack tooling. Returns { number, url, warnings }.", openWorld(ADDITIVE), FIELDS, REQUIRED),
+    tool('pr_update', "Replaces an open pull request's title and body. " +
+        RENDERING +
+        "The pull request's head branch must be the worktree branch. The live Shepherd Journal is " +
+        'preserved and nothing else is carried over from the live body. Validation errors block ' +
+        'the update. Returns { number, url, warnings }.', openWorld(MUTATING), { ...FIELDS, pr: PR_NUMBER }, [...REQUIRED, 'pr']),
+];

package/dist/mcp-server/tools.mjs

@@ -1,4 +1,5 @@
 import { ADDITIVE, AGENT, COVERAGE, IDEMPOTENT_ADDITIVE, IDENTITY, IDENTITY_REQUIRED, ID_PATTERN, MUTATING, OUTCOMES, PARENT_SESSION_ID, READ_ONLY, VERSION, tool, } from "./tools-schema.mjs";
+import { PR_TOOLS } from "./tools-pr.mjs";
 import { RETROSPECTIVE_TOOLS } from "./tools-retrospective.mjs";
 export const TOOLS = [
     tool('journal_append', 'Appends one journal entry to the caller session and returns the verified read-back receipt. ' +
@@ -46,6 +47,7 @@ export const TOOLS = [
     tool('session_ensure', 'Idempotently creates a session, or verifies that an existing one has the same identity. ' +
         'Returns the session id and whether it was created.', IDEMPOTENT_ADDITIVE, IDENTITY, IDENTITY_REQUIRED),
     ...RETROSPECTIVE_TOOLS,
+    ...PR_TOOLS,
     tool('snapshot_export', 'Exports non-archived sessions into a private local JSONL file chosen by the blackboard ' +
         'client. Returns the path, counts, checksum, manifest, and cleanupToken; never the records. ' +
         'sessionId identifies the caller.', ADDITIVE, {

package/docs/mcp-server.md

@@ -7,7 +7,7 @@ existing `vouchington-tooling/agent-blackboard` exports and adds no provider pro
 
 Phase 1 of [vouchington-tooling#324](https://github.com/vouchington/vouchington-tooling/issues/324)
 covers the journal, outbox, session, and snapshot tools below. Phase 2 adds the retrospective tools
-and the policy contract they run. Pull request tools are a later phase.
+and the policy contract they run. Phase 3 adds the pull request tools.
 
 ## Install
 
@@ -225,16 +225,90 @@ whole process group is killed, so nothing it started outlives the call. The runn
 `{ policyVersion: 1, export, input }` on stdin and writes `{ ok: true, result }` (or
 `{ ok: false, error }`) on stdout; a missing export is skipped.
 
-| Export                  | Input                                                                                                                                                                       | Result                                      | Timeout |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------- |
-| `validateRetrospective` | `sessionId`, `parentSessionId`, `mode`, `workOutcome`, `feedbackCoverage`, `repositories`, `markdown`, `sourceEventId`, `metadata` (`date`, `issues`, `prs`, `description`) | `{ errors: string[], warnings?: string[] }` | 30 s    |
-| `pullRequestDefaults`   | `{}`                                                                                                                                                                        | `{ repositories: string[] }`                | 120 s   |
-| `validatePullRequest`   | reserved for the pull request tools                                                                                                                                         | `{ errors: string[], warnings?: string[] }` | 120 s   |
+| Export                  | Input                                                                                                                                                                       | Result                                                         | Timeout |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------- |
+| `validateRetrospective` | `sessionId`, `parentSessionId`, `mode`, `workOutcome`, `feedbackCoverage`, `repositories`, `markdown`, `sourceEventId`, `metadata` (`date`, `issues`, `prs`, `description`) | `{ errors: string[], warnings?: string[] }`                    | 30 s    |
+| `pullRequestDefaults`   | `{}` from `retrospective_save`; `{ title, base, relatedIssues }` from `pr_create`                                                                                           | `{ repositories?, labels?, milestone?, project? }` (an object) | 120 s   |
+| `validatePullRequest`   | `title`, `body`, `base`, `head`, `mode`, and `pr` for an update                                                                                                             | `{ errors: string[], warnings?: string[] }`                    | 120 s   |
 
 Any `errors` reject the save and write nothing. A non-zero exit, a timeout (reported as
 `policy <export> timed out after <N>s`), output over 1 MB, malformed JSON, or a result of the wrong
 shape is an error, never a pass.
 
+## Pull request tools
+
+`vouchington mcp` serves `pr_validate`, `pr_create` and `pr_update` besides the journal and
+retrospective tools. All three take `sessionId` (required) and `worktree` (optional), need a server
+launched inside a repository worktree (they run the checkout policy), and share this structured
+input: `title` (single line, at most 256 characters), `summary`, `impact`, `relatedIssues`
+(`[{ number, relation: "closes" | "refs", reason }]`, may be empty), `details` (string array),
+`base` (default `main`), `agent`, optional `model`, `mode` (`interactive` | `autonomous`) and
+`workspaceSetup`. `pr_update` also requires `pr`; `pr_validate` accepts an optional `pr`.
+
+### Rendering
+
+```
+## Summary
+
+<summary>
+
+## Impact
+
+<impact>
+
+## Related issues
+
+- Closes #N — <reason>      (or "Refs #N"; "- None" when empty)
+
+## Details
+
+<details joined by blank lines>
+
+Workspace setup: <workspaceSetup>
+Agent: <agent>[ (<model>)] session <sessionId>
+Device: <os user>@<lowercased hostname>
+Worktree: <path after "/worktrees/", "main" for the main worktree, else the directory name>
+```
+
+The head branch is the worktree's current branch; a detached HEAD, or a head equal to `base`, is
+rejected. The body must stay within GitHub's 65536 characters. `pr_create` sees no stack membership,
+so a consumer policy may reject any `base` other than the default branch; create stacked layers
+with the repository's stack tooling instead.
+
+### Tools
+
+- `pr_validate` (read-only): renders the body, runs the policy `validatePullRequest({ title, body,
+base, head, mode, pr? })` export and returns `{ body, errors, warnings }`. With `pr`, the live
+  body is read (never written) so its Shepherd Journal is preserved as in `pr_update`.
+- `pr_create` (additive): renders and validates (errors block), then calls the policy
+  `pullRequestDefaults({ title, base, relatedIssues })` export for optional `labels`, `milestone`
+  and `project`. It checks the head is pushed and current, writes the body to a mode 0600 temp file
+  (removed afterwards) and runs `gh pr create --draft` with the labels, `--milestone` and
+  `--project`. Returns `{ number, url, warnings }`.
+- `pr_update` (mutating): reads `gh pr view <pr> --json body,headRefName,baseRefName,state`,
+  rejects a pull request that is not `OPEN` or whose head is not the worktree branch, and validates
+  against the live base (an explicit `base` must equal it). It renders, appends the live Shepherd
+  Journal (a `<details><summary>Shepherd Journal</summary>` block, or a legacy `## Shepherd Journal`
+  section to the next H2 or the end; examples in fenced code blocks are ignored), validates with
+  `pr` set (errors block), then runs `gh pr edit <pr> --title --body-file`. More than one journal
+  in the live body, one in the rendered fields, an unclosed journal, or rendered fields that leave
+  a code fence open are rejected rather than guessed. Just before the edit the live body is read
+  again, and the update aborts if its journal changed meanwhile. Nothing else is carried over from
+  the live body. Returns `{ number, url, warnings }`.
+
+Every field is redacted of `AGENT_BLACKBOARD_TOKEN`, `GH_TOKEN`, and `GITHUB_TOKEN` before
+rendering, the policy, or `gh`; a worktree branch name containing one is rejected. `title` and
+`workspaceSetup` must be single lines, and the title is limited to 256 characters after redaction.
+
+### gh access
+
+`gh` is found in the absolute directories of the server's `PATH` (relative entries are skipped,
+since they would resolve inside the target worktree), else at `/opt/homebrew/bin/gh`, `/usr/local/bin/gh` or
+`/usr/bin/gh`; otherwise the tool fails with "gh CLI not found on PATH; install gh or add it to the
+server's PATH". It runs with the worktree as its working directory and the server environment
+without `AGENT_BLACKBOARD_URL`, `AGENT_BLACKBOARD_TOKEN`, and `GH_REPO` (which would point it at
+another repository), and each call is killed after 120 seconds.
+
 ## Worktree validation
 
 `worktree` is checked on every call. It must be an absolute path that, after resolving symlinks,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {

package/skills/pr-description/SKILL.md

@@ -54,6 +54,14 @@ not evidence of a miss; classify genuine CI-only or external infrastructure fail
 Retain confirmed gap records after CI turns green. Diagnose the failure through the repository's
 CI investigation workflow; a failed status alone does not establish a gap.
 
+Create, update, and validate pull requests through the `pr_create`, `pr_update`, and `pr_validate`
+MCP tools with structured input, not by hand-writing a body: pass `title`, `summary`, `impact`,
+`relatedIssues` (`closes` or `refs`, each with a reason), `details` (Markdown paragraphs or
+bullets), `base`, `agent`, optional `model`, `mode`, and `workspaceSetup`. The server renders the
+required headings and provenance lines, runs the repository's policy validation, and blocks on its
+errors, so put the guidance above into `summary`, `impact`, and `details`. Run `pr_validate` first
+to preview the rendered body. `pr_update` preserves the live Shepherd Journal.
+
 Use the repository's approved PR tooling and preserve sections managed by its review automation
 verbatim. Close only issues fully resolved and explain non-closing issue links. Apply this guidance
 to descriptions being created or updated, not a bulk rewrite of historical pull requests.