vouchington-tooling 0.43.0 → 0.45.0

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;

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

@@ -0,0 +1,38 @@
+import { validateFeedbackEnvelope } from "../agent-blackboard/index.mjs";
+import { optionalString } from "./args.mjs";
+import { byCreatedAt } from "./handlers-journal.mjs";
+import { readEntriesIfPresent } from "./journal-read.mjs";
+function retrospectiveData(entry) {
+    const data = entry?.data;
+    if (data?.type !== 'retrospective')
+        return undefined;
+    // A schema-versioned entry must be a valid envelope; unversioned legacy entries stay accepted.
+    if (data.schemaVersion !== undefined) {
+        try {
+            validateFeedbackEnvelope(data);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return data;
+}
+/** 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 };
+};

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

@@ -73,10 +73,10 @@ export function worktreeExecutor(worktree, env, timeoutMs = FACTS_TIMEOUT_MS) {
 export function sensitiveValues(compose, env) {
     const given = compose?.knownSensitiveValues;
     if (given !== undefined && (!Array.isArray(given) || given.some((v) => typeof v !== 'string')))
-        throw new Error('compose.knownSensitiveValues must be an array of strings');
+        throw new Error('knownSensitiveValues must be an array of strings');
     // Redaction ignores values under four characters, so promising to redact one would be false.
     if (given?.some((value) => value.length < 4))
-        throw new Error('compose.knownSensitiveValues entries must be at least 4 characters');
+        throw new Error('knownSensitiveValues entries must be at least 4 characters');
     // Facts commands inherit the GitHub tokens, so their output is redacted of those values too.
     const credentials = [env.AGENT_BLACKBOARD_TOKEN, env.GH_TOKEN, env.GITHUB_TOKEN].filter((value) => Boolean(value));
     const values = [...(given ?? []), ...credentials];

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

@@ -0,0 +1,17 @@
+import { type Args } from './args.mts';
+import { type ToolContext } from './context.mts';
+import type { FeedbackEnvelope, FeedbackIdentity } from '../agent-blackboard/feedback-types.mts';
+type Mode = 'interactive' | 'autonomous';
+/** Writes a validated envelope through the same verified path as `journal_append`. */
+export declare function deliver(envelope: FeedbackEnvelope, identity: FeedbackIdentity, mode: Mode, context: ToolContext): Promise<Record<string, unknown>>;
+/**
+ * Saves exactly the content a dry run previewed. The token is single use and bound to the
+ * session, the worktree and the event id; an unknown, spent, restarted or mismatched token is
+ * one error. The policy accepted this content at preview time, so it is not run again.
+ */
+export declare function saveFromPreview(args: Args, context: ToolContext, identity: FeedbackIdentity, mode: Mode, sourceEventId: string): Promise<{
+    policy: {
+        warnings: string[];
+    };
+}>;
+export {};

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

@@ -0,0 +1,60 @@
+import { rejectUnknown, requiredString } from "./args.mjs";
+import { outboxDirectory } from "./context.mjs";
+import { deliveryResponse } from "./handlers-journal.mjs";
+import { previewRegistry } from "./preview-registry.mjs";
+import { validateFeedbackEnvelope, writeFeedback } from "../agent-blackboard/index.mjs";
+/** Writes a validated envelope through the same verified path as `journal_append`. */
+export async function deliver(envelope, identity, mode, context) {
+    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);
+}
+/** The only arguments a token save takes: everything else was fixed by the dry run. */
+const TOKEN_SAVE_ARGS = [
+    'sessionId',
+    'worktree',
+    'parentSessionId',
+    'agent',
+    'version',
+    'mode',
+    'sourceEventId',
+    'previewToken',
+];
+/**
+ * Saves exactly the content a dry run previewed. The token is single use and bound to the
+ * session, the worktree and the event id; an unknown, spent, restarted or mismatched token is
+ * one error. The policy accepted this content at preview time, so it is not run again.
+ */
+export async function saveFromPreview(args, context, identity, mode, sourceEventId) {
+    rejectUnknown(args, TOKEN_SAVE_ARGS);
+    const token = requiredString(args, 'previewToken');
+    const preview = previewRegistry.take(token, {
+        sessionId: context.sessionId,
+        parentSessionId: identity.parentSessionId,
+        mode,
+        worktree: context.worktree,
+        sourceEventId,
+    });
+    if (preview === undefined)
+        throw new Error('previewToken is unknown, already used, expired by a restart, or bound to a different ' +
+            'session, worktree or sourceEventId: run the dry run again');
+    // The server owns the timestamp, as for every other write.
+    const envelope = { ...preview.envelope, timestamp: new Date().toISOString() };
+    try {
+        validateFeedbackEnvelope(envelope);
+        const response = await deliver(envelope, identity, mode, context);
+        return { ...response, policy: { warnings: preview.warnings } };
+    }
+    catch (error) {
+        // Nothing was stored, so the caller may retry with the same token.
+        previewRegistry.restore(token, preview);
+        throw error;
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { SnapshotCleanupReceipt } from '../agent-blackboard/snapshot-types.mts';
+/** What the server itself recorded when it exported a snapshot. Never read from a caller. */
+export type SnapshotRecord = {
+    sessionId: string;
+    worktree: string;
+    path: string;
+    /** The exporting client's own capability; kept server-side and never returned to a caller. */
+    clientToken?: string;
+    directory?: string;
+    receipt?: SnapshotCleanupReceipt;
+};
+export type SnapshotRegistry = {
+    /** Records an export and returns the server-minted, unguessable cleanup token. */
+    register: (record: SnapshotRecord) => string;
+    /** Removes and returns the record when the token is known and bound to this caller. */
+    take: (token: string, sessionId: string, worktree: string) => SnapshotRecord;
+    /** Puts a taken record back after a failed cleanup so the same token can retry. */
+    restore: (token: string, record: SnapshotRecord) => void;
+};
+export declare const MAX_RECORDS = 256;
+/**
+ * Tokens live in memory only. A server restart forgets every binding, so an old token is then
+ * rejected as unknown and the file is left for the operating system to reap from its temp directory.
+ */
+export declare function createSnapshotRegistry(): SnapshotRegistry;

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

@@ -0,0 +1,32 @@
+import { randomBytes } from 'node:crypto';
+export const MAX_RECORDS = 256;
+const REJECTED = 'cleanupToken is unknown, already used, or bound to another session or worktree; nothing was deleted';
+/**
+ * Tokens live in memory only. A server restart forgets every binding, so an old token is then
+ * rejected as unknown and the file is left for the operating system to reap from its temp directory.
+ */
+export function createSnapshotRegistry() {
+    const records = new Map();
+    const store = (token, record) => {
+        records.set(token, record);
+        // A long-lived server must not grow without bound; the oldest export is forgotten first.
+        while (records.size > MAX_RECORDS)
+            records.delete(records.keys().next().value);
+    };
+    return {
+        register(record) {
+            const token = randomBytes(32).toString('base64url');
+            store(token, record);
+            return token;
+        },
+        take(token, sessionId, worktree) {
+            const record = records.get(token);
+            // One message for every rejection, so a probe learns nothing about other sessions' tokens.
+            if (!record || record.sessionId !== sessionId || record.worktree !== worktree)
+                throw new Error(REJECTED);
+            records.delete(token);
+            return record;
+        },
+        restore: store,
+    };
+}