vouchington-tooling 0.41.0 → 0.43.0

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

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

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

@@ -1,6 +1,8 @@
-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;
 export declare function outboxPath(worktree: string): string;
@@ -12,6 +14,13 @@ export type Harness = {
 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,8 +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/journal-read.d.mts

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,116 @@
+import { fileURLToPath } from 'node:url';
+import { resolvePolicyModule } from "./policy-config.mjs";
+import { policyEnvironment, spawnPolicy, } from "./policy-spawn.mjs";
+/** How long each policy export may run before its process is killed, in milliseconds. */
+export const POLICY_TIMEOUTS_MS = {
+    validateRetrospective: 30_000,
+    validatePullRequest: 120_000,
+    pullRequestDefaults: 120_000,
+};
+const POLICY_MAX_OUTPUT_BYTES = 1_000_000;
+const STDERR_EXCERPT_BYTES = 2_000;
+const RUNNER = fileURLToPath(new URL('../../bin/policy-runner.mjs', import.meta.url));
+function failure(name, reason, outcome) {
+    const stderr = outcome?.stderr.trim().slice(-STDERR_EXCERPT_BYTES);
+    return new Error(`policy ${name} ${reason}${stderr ? `: ${stderr}` : ''}`);
+}
+function parseReply(name, outcome) {
+    let reply;
+    try {
+        reply = JSON.parse(outcome.stdout);
+    }
+    catch {
+        throw failure(name, 'produced output that is not valid JSON', outcome);
+    }
+    if (reply?.ok === false)
+        throw failure(name, `failed: ${String(reply.error)}`);
+    if (reply?.ok !== true)
+        throw failure(name, 'produced an unrecognized reply');
+    return reply.skipped === true ? { status: 'skipped' } : { status: 'ok', result: reply.result };
+}
+/**
+ * Runs one export of the worktree's declared policy module in a fresh child process (never in
+ * this one). Resolves `no-policy` when the worktree declares none and `skipped` when the module
+ * lacks the export. A timeout, crash, non-zero exit, oversized output, or unusable reply throws:
+ * a failed policy is never a pass.
+ */
+export async function runPolicyExport(run) {
+    const secrets = credentialValues(run.env);
+    // A policy can echo a credential it was given (GH_TOKEN) in a stack, stderr, or result; the
+    // caller of an MCP tool must never receive one. Diagnostics may carry it JSON-escaped too.
+    const escaped = secrets.map((secret) => JSON.stringify(secret).slice(1, -1));
+    const forms = [...new Set([...escaped, ...secrets])].sort((a, b) => b.length - a.length);
+    const spawn = run.spawn ?? spawnPolicy;
+    // stderr is scrubbed whole, before its excerpt could cut a credential into an unmatched suffix.
+    const scrubbing = async (request) => {
+        const outcome = await spawn(request);
+        return { ...outcome, stderr: scrubText(outcome.stderr, forms) };
+    };
+    try {
+        const result = await runUnscrubbed(run, scrubbing);
+        return result.status === 'ok'
+            ? { status: 'ok', result: scrubValue(result.result, secrets) }
+            : result;
+    }
+    catch (error) {
+        throw new Error(scrubText(error.message, forms), { cause: error });
+    }
+}
+const CREDENTIAL_NAMES = ['AGENT_BLACKBOARD_TOKEN', 'GH_TOKEN', 'GITHUB_TOKEN'];
+/**
+ * Credential values held by the server, longest first. A value too short to redact without
+ * mangling every output fails closed: the policy never runs rather than risk echoing it.
+ */
+function credentialValues(env) {
+    const values = CREDENTIAL_NAMES.map((name) => env[name]).filter((value) => Boolean(value));
+    if (values.some((value) => value.length < 4))
+        throw new Error(`a credential (${CREDENTIAL_NAMES.join(', ')}) is too short to redact: policy tools refuse to run`);
+    return [...new Set(values)].sort((a, b) => b.length - a.length);
+}
+function scrubText(text, secrets) {
+    return secrets.reduce((scrubbed, secret) => scrubbed.replaceAll(secret, '[REDACTED]'), text);
+}
+function scrubValue(value, secrets) {
+    if (secrets.length === 0 || value === undefined)
+        return value;
+    // Each secret is matched in its JSON-escaped form so the round trip stays valid JSON.
+    const escaped = secrets.map((secret) => JSON.stringify(secret).slice(1, -1));
+    return JSON.parse(scrubText(JSON.stringify(value), escaped));
+}
+async function runUnscrubbed(run, spawn) {
+    const { export: name } = run;
+    const module = await resolvePolicyModule(run.worktree);
+    if (module === undefined)
+        return { status: 'no-policy' };
+    const timeoutMs = POLICY_TIMEOUTS_MS[name];
+    const outcome = await spawn({
+        command: process.execPath,
+        args: [RUNNER, module],
+        cwd: run.worktree,
+        env: policyEnvironment(run.env),
+        input: JSON.stringify({ policyVersion: 1, export: name, input: run.input }),
+        timeoutMs,
+        maxOutputBytes: POLICY_MAX_OUTPUT_BYTES,
+    });
+    if (outcome.timedOut)
+        throw failure(name, `timed out after ${timeoutMs / 1000}s`);
+    if (outcome.overflowed)
+        throw failure(name, `wrote more than ${POLICY_MAX_OUTPUT_BYTES} bytes of output`);
+    if (outcome.exitCode !== 0)
+        throw failure(name, `exited with code ${outcome.exitCode}`, outcome);
+    return parseReply(name, outcome);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+/** Runs a validator export and checks its result is `{ errors: string[], warnings?: string[] }`. */
+export async function runValidator(run) {
+    const outcome = await runPolicyExport(run);
+    if (outcome.status !== 'ok')
+        return outcome;
+    const result = outcome.result;
+    if (!isStringArray(result?.errors) ||
+        (result.warnings !== undefined && !isStringArray(result.warnings)))
+        throw new Error(`policy ${run.export} must return { errors: string[], warnings?: string[] }`);
+    return { errors: result.errors, warnings: result.warnings ?? [] };
+}

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

@@ -0,0 +1,24 @@
+export type PolicyRequest = {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    input: string;
+    timeoutMs: number;
+    maxOutputBytes: number;
+};
+export type PolicyOutcome = {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    /** True when stdout or stderr exceeded `maxOutputBytes` and the child was killed. */
+    overflowed: boolean;
+};
+export type PolicySpawner = (request: PolicyRequest) => Promise<PolicyOutcome>;
+/**
+ * The child's whole environment. Blackboard credentials and NODE_OPTIONS are never passed; GitHub
+ * tokens are passed only when the server has them, for the checks that call `gh`.
+ */
+export declare function policyEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare const spawnPolicy: PolicySpawner;

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

@@ -0,0 +1,97 @@
+import { spawn } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
+function isExecutable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The directory of the first `gh` on the server's PATH, so policy checks can call it. */
+function ghDirectory(env) {
+    const found = (env.PATH ?? '')
+        .split(delimiter)
+        .filter((directory) => directory !== '')
+        .find((directory) => isExecutable(join(directory, 'gh')));
+    return found === undefined ? [] : [found];
+}
+/** The fixed system directories, node's own, and the directory holding `gh`, deduplicated. */
+function policyPath(env) {
+    const directories = [
+        '/usr/bin',
+        '/bin',
+        '/usr/local/bin',
+        '/opt/homebrew/bin',
+        dirname(process.execPath),
+        ...ghDirectory(env),
+    ];
+    return [...new Set(directories)].join(delimiter);
+}
+/**
+ * The child's whole environment. Blackboard credentials and NODE_OPTIONS are never passed; GitHub
+ * tokens are passed only when the server has them, for the checks that call `gh`.
+ */
+export function policyEnvironment(env) {
+    const child = { PATH: policyPath(env) };
+    for (const name of ['HOME', 'GH_TOKEN', 'GITHUB_TOKEN']) {
+        const value = env[name];
+        if (value !== undefined)
+            child[name] = value;
+    }
+    return child;
+}
+export const spawnPolicy = (request) => new Promise((resolve, reject) => {
+    const child = spawn(request.command, request.args, {
+        cwd: request.cwd,
+        env: request.env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        // Its own process group, so every grandchild the policy started can be killed with it.
+        detached: process.platform !== 'win32',
+    });
+    const killGroup = () => {
+        try {
+            process.kill(-child.pid, 'SIGKILL');
+        }
+        catch {
+            child.kill('SIGKILL');
+        }
+    };
+    const chunks = { stdout: [], stderr: [] };
+    const sizes = { stdout: 0, stderr: 0 };
+    let timedOut = false;
+    let overflowed = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        killGroup();
+    }, request.timeoutMs);
+    for (const name of ['stdout', 'stderr'])
+        child[name].on('data', (chunk) => {
+            sizes[name] += chunk.length;
+            if (sizes[name] > request.maxOutputBytes) {
+                overflowed = true;
+                killGroup();
+            }
+            else
+                chunks[name].push(chunk);
+        });
+    child.on('error', (error) => {
+        clearTimeout(timer);
+        reject(error);
+    });
+    // Reap anything the policy left running in its group as soon as the runner exits: a descendant
+    // would otherwise keep the GitHub token it inherited, and one holding an inherited pipe would
+    // delay `close` until the timeout.
+    child.on('exit', () => {
+        clearTimeout(timer);
+        killGroup();
+    });
+    child.on('close', (exitCode) => {
+        const text = (name) => Buffer.concat(chunks[name]).toString('utf8');
+        resolve({ exitCode, stdout: text('stdout'), stderr: text('stderr'), timedOut, overflowed });
+    });
+    child.stdin.on('error', () => { });
+    child.stdin.end(request.input);
+});

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;