vouchington-tooling 0.44.0 → 0.45.0

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,
+    };
+}

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

@@ -12,7 +12,8 @@ const FIELDS = {
     impact: text('Who or what is affected, as markdown.'),
     relatedIssues: {
         type: 'array',
-        description: 'Issues this pull request closes or refs; may be empty.',
+        description: 'Issues this pull request closes or refs. Empty when it has none; with no source issue ' +
+            'at all, give noSourceIssue as well (it is rejected beside a non-empty list).',
         items: {
             type: 'object',
             properties: {
@@ -24,6 +25,15 @@ const FIELDS = {
             additionalProperties: false,
         },
     },
+    noSourceIssue: {
+        type: 'object',
+        description: 'Declares a pull request with no source issue, mutually exclusive with a non-empty ' +
+            'relatedIssues. Rendered inside Related issues (the policy may supply the wording) and ' +
+            'passed to the policy, which may allow it only in interactive mode.',
+        properties: { reason: text('Single-line reason there is no source issue.') },
+        required: ['reason'],
+        additionalProperties: false,
+    },
     details: {
         type: 'array',
         minItems: 1,
@@ -33,7 +43,12 @@ const FIELDS = {
     base: { type: 'string', minLength: 1, description: 'Base branch. Default: main.' },
     agent: text('Agent name for the Agent line.'),
     model: text('Optional model name, rendered in parentheses after the agent.'),
-    mode: { enum: ['interactive', 'autonomous'], description: 'Delivery mode, given to the policy.' },
+    mode: {
+        enum: ['interactive', 'autonomous'],
+        description: 'Optional. The server derives the mode from its own launch environment and fails closed: ' +
+            'an automation marker (CI, GITHUB_ACTIONS and similar) means autonomous. This argument ' +
+            'can only narrow interactive to autonomous, never widen it.',
+    },
     workspaceSetup: text('Text for the Workspace setup line, such as how the worktree was prepared.'),
 };
 const REQUIRED = [
@@ -43,7 +58,6 @@ const REQUIRED = [
     'relatedIssues',
     'details',
     'agent',
-    'mode',
     'workspaceSetup',
 ];
 const RENDERING = 'The server renders the body from the structured input (Summary, Impact, Related issues, ' +
@@ -54,7 +68,9 @@ export const PR_TOOLS = [
     tool('pr_validate', 'Renders the pull request body and validates it with the checkout policy; writes nothing. ' +
         RENDERING +
         'Pass pr to validate an update of that pull request: the live body is read and its Shepherd ' +
-        'Journal preserved. Returns { body, errors, warnings }.', openWorld(READ_ONLY), { ...FIELDS, pr: PR_NUMBER }, REQUIRED),
+        'Journal preserved; the pull request may be in any state and on any head (the head given to ' +
+        'the policy is its own, and no liveness check applies, unlike pr_update). Returns ' +
+        '{ body, errors, warnings }.', openWorld(READ_ONLY), { ...FIELDS, pr: PR_NUMBER }, REQUIRED),
     tool('pr_create', 'Creates a draft pull request from the worktree branch. ' +
         RENDERING +
         'Validation errors block creation. The policy pullRequestDefaults export may add labels, a ' +

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

@@ -15,9 +15,15 @@ export const RETROSPECTIVE_TOOLS = [
         'takes only { sessionId?, harnessSessionId? } (sessionId must be the call sessionId; the ' +
         'transcript is found by harnessSessionId, the harness session UUID, else by sessionId when ' +
         'that is a UUID, in the default session roots of the worktree) or { status, reason } to report it ' +
-        'unassessed; any path override is rejected. The server redacts its blackboard token ' +
-        'from the document before the policy sees it. dryRun returns ' +
-        '{ markdown, policy: { warnings } } and writes nothing. The worktree package.json may ' +
+        'unassessed; any path override is rejected. The server redacts its blackboard token and ' +
+        'knownSensitiveValues (also accepted beside markdown, not beside compose) from the ' +
+        'document, category and feedbackCoverage before the policy sees them. dryRun returns ' +
+        '{ markdown, previewToken, policy: { warnings } } and writes nothing; the previewToken is ' +
+        'opaque, single use, held in server memory (a restart drops it) and bound to the sessionId, ' +
+        'worktree and sourceEventId. To save exactly the previewed content, call again with ' +
+        'previewToken, the identity, mode and the same sourceEventId, and no markdown, compose, ' +
+        'workOutcome, feedbackCoverage, repositories, category or knownSensitiveValues. The ' +
+        'policy is not run again for a token save. The worktree package.json may ' +
         'declare "vouchington-tooling": { "policy": "<module>" }; its validateRetrospective export ' +
         'runs in a child process, and any error it reports rejects the save with nothing written. ' +
         'Policy tools need a server launched inside a repository worktree. The server owns the ' +
@@ -29,7 +35,10 @@ export const RETROSPECTIVE_TOOLS = [
         'follow journal_append.', ADDITIVE, {
         ...IDENTITY,
         mode: { enum: ['interactive', 'autonomous'], description: 'Delivery mode.' },
-        workOutcome: { enum: OUTCOMES, description: 'Outcome of the work being reported.' },
+        workOutcome: {
+            enum: OUTCOMES,
+            description: 'Outcome of the work being reported; required without previewToken.',
+        },
         feedbackCoverage: COVERAGE,
         repositories: {
             type: 'array',
@@ -44,5 +53,16 @@ export const RETROSPECTIVE_TOOLS = [
         sourceEventId: { type: 'string', pattern: ID_PATTERN, description: 'Stable event id.' },
         category: { type: 'string', description: 'Optional context; never changes entry type.' },
         dryRun: { type: 'boolean', description: 'Compose and validate only; write nothing.' },
-    }, [...IDENTITY_REQUIRED, 'mode', 'workOutcome', 'feedbackCoverage']),
+        knownSensitiveValues: {
+            type: 'array',
+            items: { type: 'string', minLength: 4 },
+            description: 'Values redacted from every argument of a markdown save.',
+        },
+        previewToken: {
+            type: 'string',
+            description: 'Token from a dry run; saves exactly that content. Exclusive with the content.',
+        },
+    }, 
+    // workOutcome and feedbackCoverage are required unless previewToken carries them.
+    [...IDENTITY_REQUIRED, 'mode']),
 ];

package/dist/mcp-server/tools.mjs

@@ -58,5 +58,11 @@ export const TOOLS = [
         dataArrayContains: { type: 'object', description: 'Exact string membership in arrays.' },
         inactiveForHours: { type: 'number', exclusiveMinimum: 0 },
     }),
+    tool('snapshot_cleanup', 'Deletes the snapshot file (and partition directory, when one was recorded) that ' +
+        'snapshot_export produced. Takes only the cleanupToken it returned: the server resolves the ' +
+        'paths from its own record, never from the caller. The token is bound to the sessionId and ' +
+        'worktree that exported, is single-use, and is forgotten when the server restarts (the ' +
+        'file is then left for the OS to reap). A failed cleanup keeps the token valid and names ' +
+        'any retained tombstone so the same call can retry. Call it as a finally step.', { ...MUTATING, idempotentHint: false }, { cleanupToken: { type: 'string', description: 'The cleanupToken snapshot_export returned.' } }, ['cleanupToken']),
     tool('session_archive', 'Marks a session as distilled. Its metadata becomes immutable; entries stay appendable.', MUTATING),
 ];

package/docs/mcp-server.md

@@ -82,17 +82,18 @@ Every tool takes an explicit `sessionId` (`^[A-Za-z0-9._:-]+$`, at most 256 char
 server never infers, and an optional `worktree`. Unknown arguments are rejected. Failures come back
 as MCP tool errors (`isError: true`) with an actionable message rather than crashing the server.
 
-| Tool                  | Arguments besides `sessionId` and `worktree`                                                                                                                                             | Returns                                                                                                                                          |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `journal_append`      | `parentSessionId`, `agent`, `version`, `mode` (`interactive` or `autonomous`), `markdown`, `sourceEventId`, `workOutcome`, `repositories`, `feedbackCoverage`, optional `category`       | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`), `pendingCount`, `worktreePendingCount`          |
-| `journal_entries`     | none                                                                                                                                                                                     | `sessionId` and `entries`, every entry oldest first                                                                                              |
-| `outbox_status`       | none                                                                                                                                                                                     | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`                                          |
-| `outbox_flush`        | none                                                                                                                                                                                     | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `deliveredCount`, `rejected` (when any) |
-| `session_ensure`      | `parentSessionId`, `agent`, `version`                                                                                                                                                    | `sessionId`, `status` (`created` or `exists`), `archived`                                                                                        |
-| `retrospective_check` | optional `sourceEventId`                                                                                                                                                                 | `sessionId`, `saved`, `entries` (`sourceEventId`, `timestamp`, `issues`, `prs` of each retrospective, oldest first)                              |
-| `retrospective_save`  | `parentSessionId`, `agent`, `version`, `mode`, `workOutcome`, `feedbackCoverage`, exactly one of `markdown` or `compose`, optional `repositories`, `sourceEventId`, `category`, `dryRun` | as `journal_append` plus `policy.warnings`; with `dryRun`, `markdown` and `policy.warnings`                                                      |
-| `snapshot_export`     | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours`                                                                                          | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken`                                                                            |
-| `session_archive`     | none                                                                                                                                                                                     | `sessionId`, `archived: true`                                                                                                                    |
+| Tool                  | Arguments besides `sessionId` and `worktree`                                                                                                                                                                                                                                                  | Returns                                                                                                                                          |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `journal_append`      | `parentSessionId`, `agent`, `version`, `mode` (`interactive` or `autonomous`), `markdown`, `sourceEventId`, `workOutcome`, `repositories`, `feedbackCoverage`, optional `category`                                                                                                            | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`), `pendingCount`, `worktreePendingCount`          |
+| `journal_entries`     | none                                                                                                                                                                                                                                                                                          | `sessionId` and `entries`, every entry oldest first                                                                                              |
+| `outbox_status`       | none                                                                                                                                                                                                                                                                                          | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`                                          |
+| `outbox_flush`        | none                                                                                                                                                                                                                                                                                          | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `deliveredCount`, `rejected` (when any) |
+| `session_ensure`      | `parentSessionId`, `agent`, `version`                                                                                                                                                                                                                                                         | `sessionId`, `status` (`created` or `exists`), `archived`                                                                                        |
+| `retrospective_check` | optional `sourceEventId`                                                                                                                                                                                                                                                                      | `sessionId`, `saved`, `entries` (`sourceEventId`, `timestamp`, `issues`, `prs` of each retrospective, oldest first)                              |
+| `retrospective_save`  | `parentSessionId`, `agent`, `version`, `mode`, `workOutcome`, `feedbackCoverage`, exactly one of `markdown` or `compose`, optional `repositories`, `sourceEventId`, `category`, `dryRun`, `knownSensitiveValues` (markdown only); or `previewToken` with identity, `mode` and `sourceEventId` | as `journal_append` plus `policy.warnings`; with `dryRun`, `markdown`, `previewToken` and `policy.warnings`                                      |
+| `snapshot_export`     | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours`                                                                                                                                                                                               | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken`                                                                            |
+| `snapshot_cleanup`    | `cleanupToken`                                                                                                                                                                                                                                                                                | `sessionId`, `cleaned: true`                                                                                                                     |
+| `session_archive`     | none                                                                                                                                                                                                                                                                                          | `sessionId`, `archived: true`                                                                                                                    |
 
 `journal_append` validates the whole feedback envelope with `validateFeedbackEnvelope` before
 anything is written, so a missing required field writes nothing. It returns the verified read-back
@@ -146,6 +147,35 @@ outbox does not create the directory. `snapshot_export` never accepts a destinat
 `agent-blackboard` client chooses a private file and returns its path. `session_archive` is the one
 destructive tool; archived metadata is immutable, while entries stay appendable.
 
+### Snapshot cleanup
+
+`snapshot_export` writes a private file in the OS temp directory, and `snapshot_cleanup` is the only
+way to delete it through the server. It was chosen over cleanup inside `session_archive` because
+the exporting session and the archived sessions differ during distillation, and cleanup must run
+whether or not archiving happened. Call it as a finally step after processing, on success and on
+failure.
+
+- **No caller-chosen path.** The tool takes only `cleanupToken` (`path`, `directory`, and `receipt`
+  are unsupported arguments). The server records the export's file path itself, plus a partition
+  directory and its signed receipt when the client reports both, and cleans exactly that record.
+  When the client's export carried its own cleanup capability, the server keeps it (never
+  returning it) and cleans through the client's `cleanupSnapshotPartitions`, so the client's
+  ownership marker goes with the file; otherwise it uses the in-tree `cleanupSnapshotPartitions`.
+- **Server-minted, bound token.** `snapshot_export` replaces the client's `cleanupToken` with 32
+  random bytes the server generates, recorded with the caller's `sessionId` and resolved `worktree`.
+  The binding is checked before any filesystem call.
+- **Single use.** A successful cleanup spends the token; a repeat fails as unknown and deletes
+  nothing. The record is taken synchronously, so concurrent calls cannot both clean.
+- **Failure modes.** An unknown, forged (including a path used as a token), spent, other-session, or
+  other-worktree token fails with one message and deletes nothing; a mismatched caller does not spend
+  the owner's token. If the cleanup itself fails, the token stays valid and the error carries the
+  reason, including the retained tombstone path when a partition directory was half removed, so the
+  same call can retry. A file that is already gone counts as cleaned.
+- **Server restart.** Bindings are in memory only. After a restart every earlier token is unknown, so
+  the file is left for the operating system to reap from its temp directory; run the distill pass
+  again to export a fresh snapshot. The registry also remembers at most 256 exports and forgets the
+  oldest first.
+
 The outbox lives at `<worktree>/.local/blackboard-outbox` and is used only in interactive mode.
 Autonomous mode forbids a filesystem outbox, so a failed delivery is an error.
 
@@ -168,7 +198,9 @@ instructions shows it to the agent.
 ## Retrospective tools and the policy contract
 
 `retrospective_check` reads the session through the same client as `journal_entries` and reports the
-entries whose envelope `type` is `retrospective`. A session that was never created (the blackboard
+entries whose envelope `type` is `retrospective`. A schema-versioned entry counts only when its
+envelope passes `validateFeedbackEnvelope`; a malformed one is not saved, while an unversioned legacy
+entry is still accepted. A session that was never created (the blackboard
 answers 404) reports `saved: false`.
 
 `retrospective_save` builds a `retrospective` envelope and writes it exactly as `journal_append`
@@ -189,7 +221,20 @@ are killed after 120 seconds. `compose.facts` takes `pr`, `branch`, `noPr`, or `
 worktree's. Facts run `git` and `gh` in the worktree as the server's user, honoring its
 repository configuration (which can select helpers that run code), so the worktree, including
 `.git/config`, must be as trusted as the policy module. `dryRun`
-runs every check and returns the document without writing.
+runs every check and returns the document without writing, plus a `previewToken`.
+
+`knownSensitiveValues` (each at least 4 characters) is also accepted beside `markdown`, and
+redacts the markdown, `category` and `feedbackCoverage` just as `compose.knownSensitiveValues`
+does; with `compose`, pass it inside `compose`. The `previewToken` is 32 random bytes (base64url),
+opaque, single use, and held only in server memory: a restart drops every token, and the registry
+keeps the 32 most recent. It is bound to the `sessionId`, `parentSessionId`, `mode`, the resolved worktree, the `sourceEventId`
+and the exact redacted content. Save it by calling `retrospective_save` again with the identity,
+the same `parentSessionId`, `mode`, `sourceEventId` and `previewToken`, and none of `markdown`, `compose`,
+`workOutcome`, `feedbackCoverage`, `repositories`, `category`, `knownSensitiveValues` or `dryRun`.
+The server stores exactly the previewed content (so a sensitive value never has to be sent
+again), mints a new timestamp, and does not run the policy again. An unknown, spent, restarted or
+mismatched token is one error and the dry run must be repeated; a mismatch does not spend the
+token, and neither does a failed write.
 
 The document must open with the front matter `composeRetrospective` writes: lines of
 `key: <JSON value>` between two `---` lines. Recognized keys are `date`, `issues`, `prs` (required),
@@ -229,7 +274,7 @@ whole process group is killed, so nothing it started outlives the call. The runn
 | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------- |
 | `validateRetrospective` | `sessionId`, `parentSessionId`, `mode`, `workOutcome`, `feedbackCoverage`, `repositories`, `markdown`, `sourceEventId`, `metadata` (`date`, `issues`, `prs`, `description`) | `{ errors: string[], warnings?: string[] }`                    | 30 s    |
 | `pullRequestDefaults`   | `{}` from `retrospective_save`; `{ title, base, relatedIssues }` from `pr_create`                                                                                           | `{ repositories?, labels?, milestone?, project? }` (an object) | 120 s   |
-| `validatePullRequest`   | `title`, `body`, `base`, `head`, `mode`, and `pr` for an update                                                                                                             | `{ errors: string[], warnings?: string[] }`                    | 120 s   |
+| `validatePullRequest`   | `title`, `body`, `base`, `head`, the trusted `mode`, `noSourceIssue` when given, and `pr` when set                                                                          | `{ errors: string[], warnings?: string[] }`                    | 120 s   |
 
 Any `errors` reject the save and write nothing. A non-zero exit, a timeout (reported as
 `policy <export> timed out after <N>s`), output over 1 MB, malformed JSON, or a result of the wrong
@@ -241,9 +286,33 @@ shape is an error, never a pass.
 retrospective tools. All three take `sessionId` (required) and `worktree` (optional), need a server
 launched inside a repository worktree (they run the checkout policy), and share this structured
 input: `title` (single line, at most 256 characters), `summary`, `impact`, `relatedIssues`
-(`[{ number, relation: "closes" | "refs", reason }]`, may be empty), `details` (string array),
-`base` (default `main`), `agent`, optional `model`, `mode` (`interactive` | `autonomous`) and
-`workspaceSetup`. `pr_update` also requires `pr`; `pr_validate` accepts an optional `pr`.
+(`[{ number, relation: "closes" | "refs", reason }]`, may be empty), optional `noSourceIssue`
+(`{ reason }`, see below), `details` (string array), `base` (default `main`), `agent`, optional
+`model`, optional `mode` (`interactive` | `autonomous`) and `workspaceSetup`. `pr_update` also
+requires `pr`; `pr_validate` accepts an optional `pr`.
+
+### Trusted mode
+
+The mode the policy sees is derived by the server from its own launch environment, never from the
+caller. It fails closed: when any automation marker is set to something other than an empty
+string, `0` or `false` (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `BUILDKITE`, `CIRCLECI`,
+`JENKINS_URL`, `TF_BUILD`, `CODEBUILD_BUILD_ID`, `VOUCHINGTON_AUTOMATION`), the mode is
+`autonomous` whatever the caller passes. `CLAUDE_CODE_SESSION_ATTENDED` set to exactly `0` (Claude
+Code's marker for an unattended `claude -p` run, inherited by MCP servers) also means `autonomous`;
+a missing value or `1` never does. This list is a superset of the downstream check it replaces,
+which was exactly `GITHUB_ACTIONS === 'true' || CI === 'true'`. Otherwise the mode is `interactive`. The optional `mode`
+argument can only narrow `interactive` to `autonomous` (it never widens), so an autonomous run
+cannot unlock an interactive-only policy exception. The policy child receives no env markers, so it
+relies on this value.
+
+### Pull requests with no source issue
+
+Pass `noSourceIssue: { reason }` (a single line) with an empty `relatedIssues`; a non-empty
+`relatedIssues` beside it is rejected. The Related issues section then holds the generic statement
+`- No source issue — <reason>` instead of `- None`. A policy may replace the statement by
+exporting `renderNoSourceIssue({ reason })`, returning a non-empty string (30 s). The field also
+reaches `validatePullRequest` (with the trusted `mode`, so the policy can apply an interactive-only
+rule) and `pullRequestDefaults`.
 
 ### Rendering
 
@@ -258,7 +327,8 @@ input: `title` (single line, at most 256 characters), `summary`, `impact`, `rela
 
 ## Related issues
 
-- Closes #N — <reason>      (or "Refs #N"; "- None" when empty)
+- Closes #N — <reason>      (or "Refs #N"; "- None" when empty;
+                             "- No source issue — <reason>" for noSourceIssue)
 
 ## Details
 
@@ -270,18 +340,20 @@ Device: <os user>@<lowercased hostname>
 Worktree: <path after "/worktrees/", "main" for the main worktree, else the directory name>
 ```
 
-The head branch is the worktree's current branch; a detached HEAD, or a head equal to `base`, is
-rejected. The body must stay within GitHub's 65536 characters. `pr_create` sees no stack membership,
+The head branch is the worktree's current branch (for `pr_validate` with `pr`, the live pull
+request's head, which may equal `base` for a fork); otherwise a detached HEAD, or a head equal to `base`, is rejected. The body must stay within GitHub's 65536 characters. `pr_create` sees no stack membership,
 so a consumer policy may reject any `base` other than the default branch; create stacked layers
 with the repository's stack tooling instead.
 
 ### Tools
 
 - `pr_validate` (read-only): renders the body, runs the policy `validatePullRequest({ title, body,
-  base, head, mode, pr? })` export and returns `{ body, errors, warnings }`. With `pr`, the live
-  body is read (never written) so its Shepherd Journal is preserved as in `pr_update`.
+  base, head, mode, noSourceIssue?, pr? })` export and returns `{ body, errors, warnings }`. With
+  `pr`, the live body is read (never written) so its Shepherd Journal is preserved as in
+  `pr_update`. The liveness checks of `pr_update` do not apply: any state (merged or closed
+  included) and any head are accepted, and the policy sees the pull request's own head and base.
 - `pr_create` (additive): renders and validates (errors block), then calls the policy
-  `pullRequestDefaults({ title, base, relatedIssues })` export for optional `labels`, `milestone`
+  `pullRequestDefaults({ title, base, relatedIssues, noSourceIssue? })` export for optional `labels`, `milestone`
   and `project`. It checks the head is pushed and current, writes the body to a mode 0600 temp file
   (removed afterwards) and runs `gh pr create --draft` with the labels, `--milestone` and
   `--project`. Returns `{ number, url, warnings }`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -391,13 +391,13 @@
     "yaml": "2.9.1"
   },
   "devDependencies": {
-    "@ast-grep/cli": "0.45.3",
+    "@ast-grep/cli": "0.50.0",
     "@modelcontextprotocol/sdk": "1.32.1",
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
     "agent-blackboard": "^0.6.1",
     "no-mistakes": "0.83.0",
-    "smol-toml": "1.9.0",
+    "smol-toml": "1.9.1",
     "typescript5": "npm:typescript@5.9.3"
   },
   "peerDependencies": {

package/skills/retrospective/SKILL.md

@@ -15,7 +15,9 @@ local `AGENTS.md`, and journal guidance first.
 1. Read the agent's own journal oldest-first and check for an existing retrospective. Capture a
    material new observation before filing a follow-up issue. Preserve entry-level repository tags.
 2. Generate routine repository and transcript facts with the approved composer: pass `compose` to
-   the `retrospective_save` MCP tool and preview the composition with `dryRun`, never a CLI. Keep exact factual
+   the `retrospective_save` MCP tool and preview the composition with `dryRun`, never a CLI. Save the preview by passing its
+   `previewToken` to `retrospective_save` (no markdown); put sensitive values only in
+   `compose.knownSensitiveValues`, or `knownSensitiveValues` for a markdown save. Keep exact factual
    section markers generated, preserve unavailable counts, and never replace missing evidence with
    invented zero statistics. Do not paste raw collectors' output or manually reconstruct facts.
 3. Record work outcome, feedback coverage, and delivery independently. Success, failure,

package/skills/retrospective-distill/SKILL.md

@@ -126,6 +126,11 @@ difference is a conflicting payload and stays quarantined.
   sessions into retrospective and stale (checkpoint-only, journal-only, zero-entry child, and
   zero-entry root).
 
+Cleanup, as a finally step: whether processing succeeded or failed, call `snapshot_cleanup` with
+the `cleanupToken` from `snapshot_export`, with the same `sessionId` and `worktree`, once the
+snapshot is no longer needed. The token is single-use and server-restart-scoped; if cleanup fails,
+retry the same call.
+
 Use source records only for local verification and leave them in the repository's approved journal
 or retention system. Public issue bodies contain only the minimum bounded facts or redacted
 summaries needed to establish the problem, proposed work, relevant areas, and validation. Never