vouchington-tooling 0.43.0 → 0.45.0

package/dist/mcp-server/fake-blackboard.test-helpers.d.mts

@@ -13,6 +13,8 @@ export type FakeOptions = {
     omitArchive?: boolean;
     omitSnapshots?: boolean;
     exportResult?: unknown;
+    /** Gives the fake client its own capability-aware snapshot cleanup. */
+    clientCleanup?: (options: unknown) => Promise<void>;
     /** Makes `ensure` fail for any other identity, and `get` report a session with this one. */
     conflictingSession?: {
         id: string;

package/dist/mcp-server/fake-blackboard.test-helpers.mjs

@@ -81,6 +81,9 @@ export function fakeBlackboard(options = {}) {
         Sessions,
         Entries,
         ...(options.omitSnapshots ? {} : { Snapshots }),
+        ...(options.clientCleanup === undefined
+            ? {}
+            : { cleanupSnapshotPartitions: options.clientCleanup }),
     };
     return { dependencies: { loadClient: async () => module }, calls, stored };
 }

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

@@ -1,4 +1,4 @@
-import { type ToolHandler } from './context.mts';
+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

@@ -1,115 +1,24 @@
-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]);
-}
+import { positiveInteger } from "./pr-input.mjs";
+import { assertJournalUnchanged } from "./pr-live.mjs";
+import { ghIn, gitIn, policyFor, prepare } from "./pr-prepare.mjs";
 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));
+    const { body, errors, warnings } = await prepare(args, context, 'validate', readPr(args, false));
     return { body, errors, warnings };
 };
 export const handlePrCreate = async (args, context) => {
-    const prepared = await prepare(args, context, undefined);
+    const prepared = await prepare(args, context, 'create', undefined);
     rejectErrors(prepared);
     const { input, head, body } = prepared;
     const defaults = await pullRequestDefaults(policyFor(context), input);
@@ -127,7 +36,7 @@ export const handlePrCreate = async (args, context) => {
 };
 export const handlePrUpdate = async (args, context) => {
     const pr = readPr(args, true);
-    const prepared = await prepare(args, context, pr);
+    const prepared = await prepare(args, context, 'update', pr);
     rejectErrors(prepared);
     await assertJournalUnchanged(ghIn(context), pr, prepared.liveBody, prepared.input.base);
     const url = await withBodyFile(prepared.body, async (bodyFile) => (await ghIn(context)([

package/dist/mcp-server/handlers-retrospective-save.d.mts

@@ -0,0 +1,10 @@
+import { type ToolHandler } from './context.mts';
+/** The default event id, hashed when the session id would push it past the 256-byte limit. */
+export declare function defaultSourceEventId(sessionId: string): string;
+/**
+ * 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 declare const retrospectiveSave: ToolHandler;

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

@@ -0,0 +1,138 @@
+import { createHash } from 'node:crypto';
+import { createFeedbackEnvelope, validateFeedbackEnvelope } from "../agent-blackboard/index.mjs";
+import { optionalRecord, optionalString, requiredChoice, requiredString, requiredStringArray, } from "./args.mjs";
+import { assertPolicyAllowed, readIdentity } from "./context.mjs";
+import { MODES, OUTCOMES, readCoverage } from "./handlers-journal.mjs";
+import { runValidator } from "./policy-run.mjs";
+import { previewRegistry } from "./preview-registry.mjs";
+import { deliver, saveFromPreview } from "./retrospective-preview.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 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 sourceEventId = optionalString(args, 'sourceEventId') ?? defaultSourceEventId(context.sessionId);
+    if (args.previewToken !== undefined)
+        return saveFromPreview(args, context, identity, mode, sourceEventId);
+    const workOutcome = requiredChoice(args, 'workOutcome', OUTCOMES);
+    const feedbackCoverage = readCoverage(args);
+    const argRepositories = args.repositories === undefined ? undefined : requiredStringArray(args, 'repositories');
+    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);
+    if (compose !== undefined && args.knownSensitiveValues !== undefined)
+        throw new Error('with compose, pass knownSensitiveValues inside compose');
+    // A markdown save redacts every argument with the same values a compose save would.
+    const secrets = sensitiveValues(compose ?? { knownSensitiveValues: args.knownSensitiveValues }, 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) {
+        const previewToken = previewRegistry.put({
+            sessionId: context.sessionId,
+            parentSessionId: identity.parentSessionId,
+            mode,
+            worktree: context.worktree,
+            sourceEventId,
+            envelope,
+            warnings,
+        });
+        return { markdown: envelope.markdown, previewToken, policy: { warnings } };
+    }
+    return { ...(await deliver(envelope, identity, mode, context)), policy: { warnings } };
+};

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

@@ -1,12 +1 @@
-import { type ToolHandler } from './context.mts';
-/** Whether the session already holds a retrospective, and which (sourceEventId, issues, prs). */
-export declare const retrospectiveCheck: ToolHandler;
-/** The default event id, hashed when the session id would push it past the 256-byte limit. */
-export declare function defaultSourceEventId(sessionId: string): string;
-/**
- * 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 declare const retrospectiveSave: ToolHandler;
+export { defaultSourceEventId, retrospectiveSave } from './handlers-retrospective-save.mts';

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

@@ -1,154 +1 @@
-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 } };
-};
+export { defaultSourceEventId, retrospectiveSave } from "./handlers-retrospective-save.mjs";

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.