vouchington-tooling 0.44.0 → 0.45.0

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

@@ -1,5 +1,6 @@
 import { archiveBlackboardSession, ensureBlackboardSession, exportSnapshot, } from "../agent-blackboard/index.mjs";
 import { optionalRecord, optionalString, requiredNullableString } from "./args.mjs";
+import { isObject } from "../agent-blackboard/snapshot-partition-guards.mjs";
 import { readIdentity } from "./context.mjs";
 function readSelection(args) {
     const data = optionalRecord(args, 'data');
@@ -33,15 +34,33 @@ export const sessionArchive = async (_args, context) => archiveBlackboardSession
     env: context.env,
     dependencies: context.dependencies,
 });
+/** A partition directory and signed receipt, only when the client itself reported both. */
+function recordedPartitions(outcome) {
+    const { directory, cleanupReceipt } = outcome;
+    return typeof directory === 'string' && isObject(cleanupReceipt)
+        ? { directory, receipt: cleanupReceipt }
+        : {};
+}
 export const snapshotExport = async (args, context) => {
     const selection = readSelection(args);
+    const outcome = await exportSnapshot({
+        // An empty selection means "everything"; leave it unset rather than send an empty filter.
+        ...(Object.keys(selection).length === 0 ? {} : { selection }),
+        env: context.env,
+        dependencies: context.dependencies,
+    });
+    // The client's own token stays server-side: the server records the export and mints a token bound to
+    // the caller's sessionId and worktree, which `snapshot_cleanup` checks before touching disk.
+    const { cleanupToken: clientToken, ...reported } = outcome;
     return {
         sessionId: context.sessionId,
-        ...(await exportSnapshot({
-            // An empty selection means "everything"; leave it unset rather than send an empty filter.
-            ...(Object.keys(selection).length === 0 ? {} : { selection }),
-            env: context.env,
-            dependencies: context.dependencies,
-        })),
+        ...reported,
+        cleanupToken: context.snapshots.register({
+            sessionId: context.sessionId,
+            worktree: context.worktree,
+            path: outcome.path,
+            ...(typeof clientToken === 'string' ? { clientToken } : {}),
+            ...recordedPartitions(outcome),
+        }),
     };
 };

package/dist/mcp-server/handlers-snapshot-cleanup.d.mts

@@ -0,0 +1,7 @@
+import type { ToolHandler } from './context.mts';
+/**
+ * Deletes the files one `snapshot_export` recorded. The caller supplies only the token: the paths
+ * and the signed receipt come from the server's own record, and the record is checked against the
+ * caller's sessionId and resolved worktree before any filesystem call.
+ */
+export declare const snapshotCleanup: ToolHandler;

package/dist/mcp-server/handlers-snapshot-cleanup.mjs

@@ -0,0 +1,36 @@
+import { cleanupSnapshotPartitions } from "../agent-blackboard/index.mjs";
+import { loadClient } from "../agent-blackboard/client.mjs";
+import { requiredString } from "./args.mjs";
+/**
+ * Deletes the files one `snapshot_export` recorded. The caller supplies only the token: the paths
+ * and the signed receipt come from the server's own record, and the record is checked against the
+ * caller's sessionId and resolved worktree before any filesystem call.
+ */
+export const snapshotCleanup = async (args, context) => {
+    const token = requiredString(args, 'cleanupToken');
+    // Taking the record is synchronous, so a concurrent second call finds the token already spent.
+    const record = context.snapshots.take(token, context.sessionId, context.worktree);
+    try {
+        const client = await loadClient(context.dependencies);
+        // A client that wrote an ownership marker must clean with its own capability, or the marker
+        // outlives the file. Older clients fall back to the in-tree receipt-based cleanup.
+        if (client.cleanupSnapshotPartitions && record.clientToken !== undefined)
+            await client.cleanupSnapshotPartitions({
+                path: record.path,
+                ...(record.directory === undefined ? {} : { directory: record.directory }),
+                cleanupToken: record.clientToken,
+            });
+        else
+            await cleanupSnapshotPartitions({
+                path: record.path,
+                ...(record.directory === undefined ? {} : { directory: record.directory }),
+                ...(record.receipt === undefined ? {} : { receipt: record.receipt }),
+            });
+    }
+    catch (error) {
+        context.snapshots.restore(token, record);
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`snapshot cleanup failed and the cleanupToken is still valid; retry the same call. ${reason}`, { cause: error });
+    }
+    return { sessionId: context.sessionId, cleaned: true };
+};

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

@@ -3,6 +3,7 @@ import { type FakeBlackboard, type FakeOptions } from './fake-blackboard.test-he
 import { type RepoFixture } from './git-fixture.test-helpers.mts';
 import type { GhRunner } from './pr-gh.mts';
 import type { PolicySpawner } from './policy-spawn.mts';
+import type { SnapshotRegistry } from './snapshot-registry.mts';
 /** A fresh pair of real repositories for every test. */
 export declare function useRepoFixture(): () => RepoFixture;
 export declare function outboxPath(worktree: string): string;
@@ -21,6 +22,7 @@ export declare function harness(fixture: RepoFixture, options?: FakeOptions & {
         user: string;
         host: string;
     };
+    snapshots?: SnapshotRegistry;
 }): 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

@@ -27,6 +27,7 @@ export function harness(fixture, options = {}) {
         ...(options.spawnPolicy === undefined ? {} : { spawnPolicy: options.spawnPolicy }),
         ...(options.runGh === undefined ? {} : { runGh: options.runGh }),
         ...(options.device === undefined ? {} : { device: options.device }),
+        ...(options.snapshots === undefined ? {} : { snapshots: options.snapshots }),
     };
     return { fake, call: (name, args) => callTool(name, args, environment) };
 }

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

@@ -4,6 +4,7 @@ export declare const POLICY_TIMEOUTS_MS: {
     readonly validateRetrospective: 30000;
     readonly validatePullRequest: 120000;
     readonly pullRequestDefaults: 120000;
+    readonly renderNoSourceIssue: 30000;
 };
 type PolicyExport = keyof typeof POLICY_TIMEOUTS_MS;
 export type PolicyResult = {

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

@@ -6,6 +6,7 @@ export const POLICY_TIMEOUTS_MS = {
     validateRetrospective: 30_000,
     validatePullRequest: 120_000,
     pullRequestDefaults: 120_000,
+    renderNoSourceIssue: 30_000,
 };
 const POLICY_MAX_OUTPUT_BYTES = 1_000_000;
 const STDERR_EXCERPT_BYTES = 2_000;

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

@@ -10,9 +10,11 @@ export type PullRequestProvenance = {
 };
 /**
  * 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.
+ * provenance lines. With `noSourceIssue` the Related issues section holds `noSourceStatement`
+ * (default {@link defaultNoSourceStatement}) instead of `- None`. Pure; the caller supplies the
+ * device and worktree facts.
  */
-export declare function renderPullRequestBody(input: PullRequestInput, provenance: PullRequestProvenance): string;
+export declare function renderPullRequestBody(input: PullRequestInput, provenance: PullRequestProvenance, noSourceStatement?: string): string;
 /**
  * The worktree label: the path after `/worktrees/` when present, `main` for the repository's main
  * worktree, else the directory name.

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

@@ -3,12 +3,24 @@ function relatedLine(issue) {
     const verb = issue.relation === 'closes' ? 'Closes' : 'Refs';
     return `- ${verb} #${issue.number} — ${issue.reason}`;
 }
+/** The default no-source statement; a policy `renderNoSourceIssue` export may replace it. */
+function defaultNoSourceStatement(reason) {
+    return `- No source 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.
+ * provenance lines. With `noSourceIssue` the Related issues section holds `noSourceStatement`
+ * (default {@link defaultNoSourceStatement}) instead of `- None`. Pure; the caller supplies the
+ * device and worktree facts.
  */
-export function renderPullRequestBody(input, provenance) {
-    const related = input.relatedIssues.length ? input.relatedIssues.map(relatedLine) : ['- None'];
+export function renderPullRequestBody(input, provenance, noSourceStatement) {
+    const related = input.relatedIssues.length
+        ? input.relatedIssues.map(relatedLine)
+        : [
+            input.noSourceIssue === undefined
+                ? '- None'
+                : (noSourceStatement ?? defaultNoSourceStatement(input.noSourceIssue.reason)),
+        ];
     const agent = input.model === undefined ? input.agent : `${input.agent} (${input.model})`;
     return [
         '## Summary',

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

@@ -13,4 +13,7 @@ export declare function pullRequestDefaults(policy: Omit<PolicyRun, 'export' | '
     title: string;
     base: string;
     relatedIssues: RelatedIssue[];
+    noSourceIssue?: {
+        reason: string;
+    };
 }): Promise<PullRequestDefaults>;

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

@@ -11,11 +11,16 @@ function optionalName(value, field) {
  * checkout declares no policy or the policy lacks the export.
  */
 export async function pullRequestDefaults(policy, input) {
-    const { title, base, relatedIssues } = input;
+    const { title, base, relatedIssues, noSourceIssue } = input;
     const outcome = await runPolicyExport({
         ...policy,
         export: 'pullRequestDefaults',
-        input: { title, base, relatedIssues },
+        input: {
+            title,
+            base,
+            relatedIssues,
+            ...(noSourceIssue === undefined ? {} : { noSourceIssue }),
+        },
     });
     if (outcome.status !== 'ok')
         return { labels: [] };

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

@@ -1,5 +1,5 @@
 import { type Args } from './args.mts';
-declare const PR_MODES: readonly ["interactive", "autonomous"];
+import { type PullRequestMode } from './pr-mode.mts';
 export type RelatedIssue = {
     number: number;
     relation: 'closes' | 'refs';
@@ -10,17 +10,24 @@ export type PullRequestInput = {
     summary: string;
     impact: string;
     relatedIssues: RelatedIssue[];
+    /** Set instead of relatedIssues when the pull request has no source issue. */
+    noSourceIssue?: {
+        reason: string;
+    };
     details: string[];
     base: string;
     agent: string;
     model?: string;
-    mode: (typeof PR_MODES)[number];
+    /** The trusted mode, see {@link trustedMode}; never the caller's word alone. */
+    mode: PullRequestMode;
     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 {};
+/**
+ * Reads and validates the structured pull request fields shared by the three pr_* tools. The mode
+ * comes from the server's `env`; the caller's optional `mode` can only narrow it.
+ */
+export declare function readPullRequestInput(args: Args, env: NodeJS.ProcessEnv): PullRequestInput;

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

@@ -1,4 +1,5 @@
 import { optionalString, rejectUnknown, requireObject, requiredChoice, requiredString, requiredStringArray, } from "./args.mjs";
+import { trustedMode } from "./pr-mode.mjs";
 const PR_MODES = ['interactive', 'autonomous'];
 const RELATIONS = ['closes', 'refs'];
 const MAX_TITLE_CHARACTERS = 256;
@@ -22,6 +23,15 @@ function readRelatedIssues(args) {
         };
     });
 }
+function readNoSourceIssue(args, related) {
+    if (args.noSourceIssue === undefined)
+        return undefined;
+    const value = requireObject(args.noSourceIssue);
+    rejectUnknown(value, ['reason']);
+    if (related.length)
+        throw new Error('noSourceIssue and a non-empty relatedIssues are mutually exclusive');
+    return { reason: singleLine(value, 'reason') };
+}
 function readDetails(args) {
     const details = requiredStringArray(args, 'details');
     details.forEach((detail, index) => {
@@ -41,21 +51,28 @@ function singleLine(args, key) {
         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) {
+/**
+ * Reads and validates the structured pull request fields shared by the three pr_* tools. The mode
+ * comes from the server's `env`; the caller's optional `mode` can only narrow it.
+ */
+export function readPullRequestInput(args, env) {
     const title = singleLine(args, 'title');
     checkTitleLength(title);
     const model = args.model === undefined ? undefined : singleLine(args, 'model');
+    const relatedIssues = readRelatedIssues(args);
+    const noSourceIssue = readNoSourceIssue(args, relatedIssues);
+    const requested = args.mode === undefined ? undefined : requiredChoice(args, 'mode', PR_MODES);
     return {
         title,
         summary: requiredString(args, 'summary'),
         impact: requiredString(args, 'impact'),
-        relatedIssues: readRelatedIssues(args),
+        relatedIssues,
+        ...(noSourceIssue === undefined ? {} : { noSourceIssue }),
         details: readDetails(args),
         base: optionalString(args, 'base') ?? 'main',
         agent: singleLine(args, 'agent'),
         ...(model === undefined ? {} : { model }),
-        mode: requiredChoice(args, 'mode', PR_MODES),
+        mode: trustedMode(env, requested),
         // It renders on its own provenance line; a newline would forge the lines after it.
         workspaceSetup: singleLine(args, 'workspaceSetup'),
     };

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

@@ -5,7 +5,9 @@ export type LivePullRequest = {
     baseRefName: string;
     state: string;
 };
-/** The live pull request as gh reports it, rejected unless it is open. */
+/** The live pull request as gh reports it, whatever its state. */
+export declare function readLivePullRequest(gh: RunTextCommand, pr: number): Promise<LivePullRequest>;
+/** The live pull request, 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

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

@@ -1,11 +1,16 @@
 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) {
+/** The live pull request as gh reports it, whatever its state. */
+export async function readLivePullRequest(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(', ')}`);
+    return live;
+}
+/** The live pull request, rejected unless it is open. */
+export async function livePullRequest(gh, pr) {
+    const live = await readLivePullRequest(gh, pr);
     // 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`);

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

@@ -0,0 +1,7 @@
+export type PullRequestMode = 'interactive' | 'autonomous';
+/**
+ * The mode the policy sees. It fails closed: an automation marker in the server's launch
+ * environment means `autonomous` whatever the caller asks, and the caller's `requested` mode can
+ * only narrow `interactive` to `autonomous`, never widen it.
+ */
+export declare function trustedMode(env: NodeJS.ProcessEnv, requested: PullRequestMode | undefined): PullRequestMode;

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

@@ -0,0 +1,34 @@
+/**
+ * Environment variables that mark an automated launch. A marker counts when it is set to anything
+ * except an empty string, `0` or `false`.
+ */
+const AUTOMATION_MARKERS = [
+    'CI',
+    'GITHUB_ACTIONS',
+    'GITLAB_CI',
+    'BUILDKITE',
+    'CIRCLECI',
+    'JENKINS_URL',
+    'TF_BUILD',
+    'CODEBUILD_BUILD_ID',
+    'VOUCHINGTON_AUTOMATION',
+];
+/** Whether the server's own launch environment carries an automation marker. */
+function isAutomationContext(env) {
+    // Claude Code sets this to exactly '0' for unattended runs; a missing or other value never
+    // means autonomous, so it can only narrow.
+    if (env.CLAUDE_CODE_SESSION_ATTENDED === '0')
+        return true;
+    return AUTOMATION_MARKERS.some((name) => {
+        const value = env[name]?.trim().toLowerCase();
+        return value !== undefined && value !== '' && value !== '0' && value !== 'false';
+    });
+}
+/**
+ * The mode the policy sees. It fails closed: an automation marker in the server's launch
+ * environment means `autonomous` whatever the caller asks, and the caller's `requested` mode can
+ * only narrow `interactive` to `autonomous`, never widen it.
+ */
+export function trustedMode(env, requested) {
+    return isAutomationContext(env) || requested === 'autonomous' ? 'autonomous' : 'interactive';
+}

package/dist/mcp-server/pr-no-source.d.mts

@@ -0,0 +1,9 @@
+import { type PolicyRun } from './policy-run.mts';
+import type { PullRequestInput } from './pr-input.mts';
+/**
+ * The statement for the Related issues section of a pull request with no source issue, from the
+ * policy's optional `renderNoSourceIssue({ reason })` export (a non-empty string, rendered as is).
+ * Undefined when the pull request has a source issue, or the checkout declares no such export, in
+ * which case the generic default statement renders.
+ */
+export declare function noSourceStatement(policy: Omit<PolicyRun, 'export' | 'input'>, input: PullRequestInput): Promise<string | undefined>;

package/dist/mcp-server/pr-no-source.mjs

@@ -0,0 +1,22 @@
+import { runPolicyExport } from "./policy-run.mjs";
+/**
+ * The statement for the Related issues section of a pull request with no source issue, from the
+ * policy's optional `renderNoSourceIssue({ reason })` export (a non-empty string, rendered as is).
+ * Undefined when the pull request has a source issue, or the checkout declares no such export, in
+ * which case the generic default statement renders.
+ */
+export async function noSourceStatement(policy, input) {
+    if (input.noSourceIssue === undefined)
+        return undefined;
+    const outcome = await runPolicyExport({
+        ...policy,
+        export: 'renderNoSourceIssue',
+        input: { reason: input.noSourceIssue.reason },
+    });
+    if (outcome.status !== 'ok')
+        return undefined;
+    if (typeof outcome.result !== 'string' || !outcome.result.trim())
+        throw new Error('policy renderNoSourceIssue must return a non-empty string');
+    // Only blank lines around the statement go; the first line's indentation is significant Markdown.
+    return outcome.result.replace(/^(?:[ \t]*\r?\n)+/, '').trimEnd();
+}

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

@@ -0,0 +1,25 @@
+import type { RunTextCommand } from '../gh-cli/exec.mts';
+import type { Args } from './args.mts';
+import { type ToolContext } from './context.mts';
+import type { PolicyRun } from './policy-run.mts';
+import { type PullRequestInput } from './pr-input.mts';
+export type Prepared = {
+    input: PullRequestInput;
+    head: string;
+    body: string;
+    errors: string[];
+    warnings: string[];
+    /** The live body the update was prepared from. */
+    liveBody?: string;
+};
+/**
+ * `create` has no live pull request. `update` requires one that is OPEN and whose head is the
+ * worktree branch. `validate` only reads one, of any state and head, for its Shepherd Journal,
+ * base and head.
+ */
+export type PrepareKind = 'create' | 'update' | 'validate';
+export declare function gitIn(context: ToolContext): RunTextCommand;
+export declare function ghIn(context: ToolContext): RunTextCommand;
+export declare function policyFor(context: ToolContext): Omit<PolicyRun, 'export' | 'input'>;
+/** Renders the body, preserves the live journal for an update, and runs the policy validator. */
+export declare function prepare(args: Args, context: ToolContext, kind: PrepareKind, pr: number | undefined): Promise<Prepared>;

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

@@ -0,0 +1,103 @@
+import { hostname, userInfo } from 'node:os';
+import { validateGitHubBodyLength } from "../gh-cli/body-length.mjs";
+import { assertPolicyAllowed } from "./context.mjs";
+import { renderPullRequestBody, worktreeLabel } from "./pr-body.mjs";
+import { createGhRunner, ghEnvironment } from "./pr-gh.mjs";
+import { checkTitleLength, readPullRequestInput } from "./pr-input.mjs";
+import { preserveShepherdJournal } from "./pr-journal.mjs";
+import { credentials, liveBase, livePullRequest, readLivePullRequest, redactCredentials, } from "./pr-live.mjs";
+import { noSourceStatement } from "./pr-no-source.mjs";
+import { runValidator } from "./policy-run.mjs";
+import { parseWorktreeList } from "./worktree.mjs";
+export function gitIn(context) {
+    return (args) => context.runGit(['-C', context.worktree, ...args]);
+}
+export function ghIn(context) {
+    const run = context.runGh ?? createGhRunner(context.env);
+    const env = ghEnvironment(context.env);
+    return (args) => run(args, { cwd: context.worktree, env });
+}
+export function policyFor(context) {
+    return {
+        worktree: context.worktree,
+        env: context.env,
+        ...(context.spawnPolicy === undefined ? {} : { spawn: context.spawnPolicy }),
+    };
+}
+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]);
+}
+async function liveFor(kind, context, pr) {
+    if (pr === undefined)
+        return undefined;
+    return kind === 'update'
+        ? livePullRequest(ghIn(context), pr)
+        : readLivePullRequest(ghIn(context), pr);
+}
+/** Renders the body, preserves the live journal for an update, and runs the policy validator. */
+export async function prepare(args, context, kind, 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, context.env), secrets);
+    checkTitleLength(given.title);
+    const git = gitIn(context);
+    const live = await liveFor(kind, context, pr);
+    // A read-only validation of an existing pull request judges the head that pull request has.
+    const worktreeHead = live !== undefined && kind === 'validate' ? undefined : await currentBranch(git);
+    const head = worktreeHead ?? live.headRefName;
+    // 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');
+    if (live !== undefined && kind === 'update' && 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 };
+    // A live pull request may come from a fork whose branch shares the base's name.
+    if (head === base && !(kind === 'validate' && live !== undefined))
+        throw new Error(`head branch ${head} must differ from base ${base}`);
+    const device = (context.device ?? (() => ({ user: userInfo().username, host: hostname() })))();
+    const statement = await noSourceStatement(policyFor(context), input);
+    let body = renderPullRequestBody(input, { sessionId: context.sessionId, ...device, worktree: await label(context, git) }, statement);
+    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,
+            ...(input.noSourceIssue === undefined ? {} : { noSourceIssue: input.noSourceIssue }),
+            ...(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 }),
+    };
+}

package/dist/mcp-server/preview-registry.d.mts

@@ -0,0 +1,25 @@
+import type { FeedbackEnvelope } from '../agent-blackboard/feedback-types.mts';
+/** What a dry run validated: the redacted envelope and the scope its token is bound to. */
+export type Preview = {
+    sessionId: string;
+    parentSessionId: string | null;
+    mode: 'interactive' | 'autonomous';
+    worktree: string;
+    sourceEventId: string;
+    envelope: FeedbackEnvelope;
+    warnings: string[];
+};
+export type PreviewScope = Omit<Preview, 'envelope' | 'warnings'>;
+/** In-memory, single-use preview tokens. A restarted server starts with none. */
+export declare class PreviewRegistry {
+    #private;
+    constructor(limit?: number);
+    /** Stores a preview under a fresh 32-byte base64url token, evicting the oldest past the cap. */
+    put(preview: Preview): string;
+    /** Removes and returns the preview, only when it is bound to exactly this scope. */
+    take(token: string, scope: PreviewScope): Preview | undefined;
+    /** Stores a preview under a token (a taken one too), evicting the oldest past the cap. */
+    restore(token: string, preview: Preview): void;
+    clear(): void;
+}
+export declare const previewRegistry: PreviewRegistry;

package/dist/mcp-server/preview-registry.mjs

@@ -0,0 +1,38 @@
+import { randomBytes } from 'node:crypto';
+const KEYS = ['sessionId', 'parentSessionId', 'mode', 'worktree', 'sourceEventId'];
+/** In-memory, single-use preview tokens. A restarted server starts with none. */
+export class PreviewRegistry {
+    #previews = new Map();
+    #limit;
+    constructor(limit = 32) {
+        this.#limit = limit;
+    }
+    /** Stores a preview under a fresh 32-byte base64url token, evicting the oldest past the cap. */
+    put(preview) {
+        const token = randomBytes(32).toString('base64url');
+        this.restore(token, preview);
+        return token;
+    }
+    /** Removes and returns the preview, only when it is bound to exactly this scope. */
+    take(token, scope) {
+        const preview = this.#previews.get(token);
+        // The scope is what the policy saw at preview time, so every field must match.
+        if (preview === undefined || KEYS.some((key) => preview[key] !== scope[key]))
+            return undefined;
+        this.#previews.delete(token);
+        return preview;
+    }
+    /** Stores a preview under a token (a taken one too), evicting the oldest past the cap. */
+    restore(token, preview) {
+        this.#previews.set(token, preview);
+        for (const oldest of this.#previews.keys()) {
+            if (this.#previews.size <= this.#limit)
+                break;
+            this.#previews.delete(oldest);
+        }
+    }
+    clear() {
+        this.#previews.clear();
+    }
+}
+export const previewRegistry = new PreviewRegistry();

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

@@ -0,0 +1,3 @@
+import type { ToolHandler } from './context.mts';
+/** Whether the session already holds a retrospective, and which (sourceEventId, issues, prs). */
+export declare const retrospectiveCheck: ToolHandler;