vouchington-tooling 0.44.0 → 0.46.0

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,124 @@
+import { hostname, userInfo } from 'node:os';
+import { validateGitHubBodyLength } from "../gh-cli/body-length.mjs";
+import { assertPolicyAllowed } from "./context.mjs";
+import { agentLabel, deriveAgent } from "./pr-agent.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);
+}
+/**
+ * The head to validate. An update accepts the worktree branch, or an alias branch whose HEAD is
+ * the live head commit, and then uses the live head name; anything else is rejected.
+ */
+async function headFor(kind, git, live, pr, worktreeHead) {
+    if (worktreeHead === undefined)
+        return live.headRefName;
+    if (live === undefined || kind !== 'update' || live.headRefName === worktreeHead)
+        return worktreeHead;
+    const sha = (await git(['rev-parse', 'HEAD'])).trim();
+    if (sha !== live.headRefOid)
+        throw new Error(`pull request ${pr} has head ${live.headRefName} at ${live.headRefOid}, not the worktree branch ${worktreeHead} at ${sha}`);
+    return live.headRefName;
+}
+/** 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);
+    // The local branch is checked before any diagnostic or alias resolution can echo or drop it.
+    if (worktreeHead !== undefined && secrets.some((secret) => worktreeHead.includes(secret)))
+        throw new Error('the worktree branch name contains a server credential: rename the branch');
+    const head = await headFor(kind, git, live, pr, worktreeHead);
+    // 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 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),
+        agent: agentLabel(deriveAgent(context.env, context.clientName?.()), input.agent, input.model),
+    }, 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/server.mjs

@@ -15,6 +15,7 @@ const INSTRUCTIONS = 'Journals agent-blackboard feedback for a vouchington consu
  */
 export function createMcpServer(sdk, environment, version) {
     const mcp = new sdk.McpServer({ name: SERVER_NAME, version }, { instructions: INSTRUCTIONS });
+    environment.clientName ??= () => mcp.server.getClientVersion()?.name;
     mcp.server.registerCapabilities({ tools: {} });
     mcp.server.setRequestHandler(sdk.ListToolsRequestSchema, async () => ({ tools: [...TOOLS] }));
     mcp.server.setRequestHandler(sdk.CallToolRequestSchema, async (request) => callTool(request.params.name, request.params.arguments, environment));

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,
@@ -31,21 +41,21 @@ const FIELDS = {
         description: 'Markdown paragraphs or bullets, joined by blank lines.',
     },
     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.' },
+    agent: text('Optional, and never trusted. The server derives the Agent line from its own launch ' +
+        'environment (harness markers) and the MCP client name; a value that does not name the ' +
+        'derived agent is rendered as "caller-claimed", and with nothing derivable the agent is ' +
+        '"unknown".'),
+    model: text('Optional, and never trusted. The server cannot derive the model, so it is rendered as ' +
+        '"caller-claimed model: <model>" in parentheses after the agent.'),
+    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 = [
-    'title',
-    'summary',
-    'impact',
-    'relatedIssues',
-    'details',
-    'agent',
-    'mode',
-    'workspaceSetup',
-];
+const REQUIRED = ['title', 'summary', 'impact', 'relatedIssues', 'details', 'workspaceSetup'];
 const RENDERING = 'The server renders the body from the structured input (Summary, Impact, Related issues, ' +
     'Details, then Workspace setup, Agent, Device and Worktree lines) and runs the checkout ' +
     'policy validatePullRequest export in a child process; the head branch is the ' +
@@ -54,7 +64,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 ' +
@@ -63,7 +75,7 @@ export const PR_TOOLS = [
         "repository's stack tooling. Returns { number, url, warnings }.", openWorld(ADDITIVE), FIELDS, REQUIRED),
     tool('pr_update', "Replaces an open pull request's title and body. " +
         RENDERING +
-        "The pull request's head branch must be the worktree branch. The live Shepherd Journal is " +
+        "The pull request's head must be the worktree branch, or the worktree HEAD must be the pull request's head commit (an alias branch); the live head name is then used. The live Shepherd Journal is " +
         'preserved and nothing else is carried over from the live body. Validation errors block ' +
         'the update. Returns { number, url, warnings }.', openWorld(MUTATING), { ...FIELDS, pr: PR_NUMBER }, [...REQUIRED, 'pr']),
 ];

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/dist/{session-friction → private-files}/lock.mjs

@@ -131,6 +131,7 @@ function removeStaleLock(lockPath) {
             return true;
         }
         catch {
+            /* v8 ignore next -- requires an unexpected filesystem failure during stale-lock recovery. */
             return false;
         }
     });
@@ -174,7 +175,7 @@ export function withFileLock(path, action) {
                 throw statusError;
             }
             if (!lockStatus.isFile())
-                throw new Error('session-friction log lock must be a regular file');
+                throw new Error('log lock must be a regular file');
             if (removeStaleLock(lockPath))
                 continue;
             waitForLock();
@@ -189,5 +190,5 @@ export function withFileLock(path, action) {
             unlinkSync(lockPath);
         }
     }
-    throw new Error(`could not acquire session-friction log lock for ${basename(path)}`);
+    throw new Error(`could not acquire file lock for ${basename(path)}`);
 }

package/dist/private-files/log-file.d.mts

@@ -0,0 +1,3 @@
+export declare function openLogFile(path: string, flags: number): number;
+export declare function readLogContent(descriptor: number, maximumBytes: number): string;
+export declare function writeAll(descriptor: number, value: string): void;