vouchington-tooling 0.42.0 → 0.44.0

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;