vouchington-tooling 0.44.0 → 0.46.0

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,8 @@ export declare function harness(fixture: RepoFixture, options?: FakeOptions & {
         user: string;
         host: string;
     };
+    snapshots?: SnapshotRegistry;
+    clientName?: () => string | undefined;
 }): 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,8 @@ 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 }),
+        ...(options.clientName === undefined ? {} : { clientName: options.clientName }),
     };
     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-agent.d.mts

@@ -0,0 +1,12 @@
+import { type HarnessId } from '../agent-harness-identity/index.mts';
+/**
+ * The harness that launched this server, from the launch environment first and the MCP client's
+ * `initialize` `clientInfo.name` second. Neither comes from a tool argument.
+ */
+export declare function deriveAgent(env: NodeJS.ProcessEnv, clientName?: string): HarnessId | undefined;
+/**
+ * The text of the `Agent:` line before the session. The agent is the derived harness; a caller
+ * `agent` that does not name it, or any `model`, is shown as caller-claimed and never replaces it.
+ * With nothing derivable the agent is `unknown`.
+ */
+export declare function agentLabel(derived: HarnessId | undefined, claimedAgent: string | undefined, claimedModel: string | undefined): string;

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

@@ -0,0 +1,34 @@
+import { inspectHarnessEnvironment } from "../agent-harness-identity/index.mjs";
+const PRECEDENCE = ['codex', 'claude', 'cursor', 'grok'];
+/**
+ * The harness that launched this server, from the launch environment first and the MCP client's
+ * `initialize` `clientInfo.name` second. Neither comes from a tool argument.
+ */
+export function deriveAgent(env, clientName) {
+    const found = inspectHarnessEnvironment(env);
+    const present = {
+        codex: Boolean(found.codex.sessionId),
+        claude: found.claude.compatMode || Boolean(found.claude.sessionId),
+        cursor: found.cursor.agentMarker || Boolean(found.cursor.sessionId),
+        grok: found.grok.agentMarker || found.grok.hookEvent || Boolean(found.grok.sessionId),
+    };
+    const fromEnv = PRECEDENCE.find((id) => present[id]);
+    if (fromEnv !== undefined)
+        return fromEnv;
+    const name = clientName?.toLowerCase() ?? '';
+    return PRECEDENCE.find((id) => name.includes(id));
+}
+/**
+ * The text of the `Agent:` line before the session. The agent is the derived harness; a caller
+ * `agent` that does not name it, or any `model`, is shown as caller-claimed and never replaces it.
+ * With nothing derivable the agent is `unknown`.
+ */
+export function agentLabel(derived, claimedAgent, claimedModel) {
+    const notes = [];
+    const claim = claimedAgent?.trim();
+    if (claim && !(derived !== undefined && claim.toLowerCase().includes(derived)))
+        notes.push(`caller-claimed agent: ${claim}`);
+    if (claimedModel)
+        notes.push(`caller-claimed model: ${claimedModel}`);
+    return `${derived ?? 'unknown'}${notes.length ? ` (${notes.join('; ')})` : ''}`;
+}

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

@@ -7,12 +7,16 @@ export type PullRequestProvenance = {
     host: string;
     /** The checkout label, see {@link worktreeLabel}. */
     worktree: string;
+    /** The Agent line text before the session, see `agentLabel`. */
+    agent: string;
 };
 /**
  * The pull request body: the Summary, Impact, Related issues and Details sections followed by the
- * provenance lines. Pure; the caller supplies the device and worktree facts.
+ * provenance lines. With `noSourceIssue` the Related issues section holds `noSourceStatement`
+ * (default {@link defaultNoSourceStatement}) instead of `- None`. Pure; the caller supplies the
+ * device and worktree facts.
  */
-export declare function renderPullRequestBody(input: PullRequestInput, provenance: PullRequestProvenance): string;
+export declare function renderPullRequestBody(input: PullRequestInput, provenance: PullRequestProvenance, noSourceStatement?: string): string;
 /**
  * The worktree label: the path after `/worktrees/` when present, `main` for the repository's main
  * worktree, else the directory name.

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

@@ -3,13 +3,24 @@ function relatedLine(issue) {
     const verb = issue.relation === 'closes' ? 'Closes' : 'Refs';
     return `- ${verb} #${issue.number} — ${issue.reason}`;
 }
+/** The default no-source statement; a policy `renderNoSourceIssue` export may replace it. */
+function defaultNoSourceStatement(reason) {
+    return `- No source issue — ${reason}`;
+}
 /**
  * The pull request body: the Summary, Impact, Related issues and Details sections followed by the
- * provenance lines. Pure; the caller supplies the device and worktree facts.
+ * provenance lines. With `noSourceIssue` the Related issues section holds `noSourceStatement`
+ * (default {@link defaultNoSourceStatement}) instead of `- None`. Pure; the caller supplies the
+ * device and worktree facts.
  */
-export function renderPullRequestBody(input, provenance) {
-    const related = input.relatedIssues.length ? input.relatedIssues.map(relatedLine) : ['- None'];
-    const agent = input.model === undefined ? input.agent : `${input.agent} (${input.model})`;
+export function renderPullRequestBody(input, provenance, noSourceStatement) {
+    const related = input.relatedIssues.length
+        ? input.relatedIssues.map(relatedLine)
+        : [
+            input.noSourceIssue === undefined
+                ? '- None'
+                : (noSourceStatement ?? defaultNoSourceStatement(input.noSourceIssue.reason)),
+        ];
     return [
         '## Summary',
         '',
@@ -28,7 +39,7 @@ export function renderPullRequestBody(input, provenance) {
         input.details.join('\n\n'),
         '',
         `Workspace setup: ${input.workspaceSetup}`,
-        `Agent: ${agent} session ${provenance.sessionId}`,
+        `Agent: ${provenance.agent} session ${provenance.sessionId}`,
         `Device: ${provenance.user}@${provenance.host.toLowerCase()}`,
         `Worktree: ${provenance.worktree}`,
         '',

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

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

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

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

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

@@ -3,6 +3,7 @@ import { constants } from 'node:fs';
 import { access, stat } from 'node:fs/promises';
 import { delimiter, isAbsolute, join } from 'node:path';
 import { promisify } from 'node:util';
+import { ghSpawnEnv } from "../gh-cli/env.mjs";
 const execFileAsync = promisify(execFile);
 const FALLBACKS = ['/opt/homebrew/bin/gh', '/usr/local/bin/gh', '/usr/bin/gh'];
 const MAX_BUFFER_BYTES = 16_000_000;
@@ -36,7 +37,7 @@ export async function locateGh(env, fallbacks = FALLBACKS) {
  * GH_REPO, which would point gh at a repository other than the validated worktree's.
  */
 export function ghEnvironment(env) {
-    const { AGENT_BLACKBOARD_URL: _url, AGENT_BLACKBOARD_TOKEN: _token, GH_REPO: _repo, ...rest } = env;
+    const { AGENT_BLACKBOARD_URL: _url, AGENT_BLACKBOARD_TOKEN: _token, GH_REPO: _repo, ...rest } = ghSpawnEnv(env);
     return rest;
 }
 /** A runner that locates gh once, on first use, from the server's environment. */

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

@@ -1,5 +1,5 @@
 import { type Args } from './args.mts';
-declare const PR_MODES: readonly ["interactive", "autonomous"];
+import { type PullRequestMode } from './pr-mode.mts';
 export type RelatedIssue = {
     number: number;
     relation: 'closes' | 'refs';
@@ -10,17 +10,25 @@ export type PullRequestInput = {
     summary: string;
     impact: string;
     relatedIssues: RelatedIssue[];
+    /** Set instead of relatedIssues when the pull request has no source issue. */
+    noSourceIssue?: {
+        reason: string;
+    };
     details: string[];
     base: string;
-    agent: string;
+    /** The caller's claim only; the rendered Agent line comes from `agentLabel`. */
+    agent?: string;
     model?: string;
-    mode: (typeof PR_MODES)[number];
+    /** The trusted mode, see {@link trustedMode}; never the caller's word alone. */
+    mode: PullRequestMode;
     workspaceSetup: string;
 };
 /** A positive integer argument, such as a pull request number or an issue number. */
 export declare function positiveInteger(value: unknown, label: string): number;
 /** Rechecked after redaction, which can lengthen a title. */
 export declare function checkTitleLength(title: string): void;
-/** Reads and validates the structured pull request fields shared by the three pr_* tools. */
-export declare function readPullRequestInput(args: Args): PullRequestInput;
-export {};
+/**
+ * Reads and validates the structured pull request fields shared by the three pr_* tools. The mode
+ * comes from the server's `env`; the caller's optional `mode` can only narrow it.
+ */
+export declare function readPullRequestInput(args: Args, env: NodeJS.ProcessEnv): PullRequestInput;

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

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

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

@@ -2,10 +2,13 @@ import type { RunTextCommand } from '../gh-cli/exec.mts';
 export type LivePullRequest = {
     body: string;
     headRefName: string;
+    headRefOid: string;
     baseRefName: string;
     state: string;
 };
-/** The live pull request as gh reports it, rejected unless it is open. */
+/** The live pull request as gh reports it, whatever its state. */
+export declare function readLivePullRequest(gh: RunTextCommand, pr: number): Promise<LivePullRequest>;
+/** The live pull request, rejected unless it is open. */
 export declare function livePullRequest(gh: RunTextCommand, pr: number): Promise<LivePullRequest>;
 /**
  * The base to validate an existing pull request against: its live base. An explicit `base` that

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

@@ -1,11 +1,16 @@
 import { findShepherdJournal } from "./pr-journal.mjs";
-const FIELDS = ['body', 'headRefName', 'baseRefName', 'state'];
-/** The live pull request as gh reports it, rejected unless it is open. */
-export async function livePullRequest(gh, pr) {
+const FIELDS = ['body', 'headRefName', 'headRefOid', 'baseRefName', 'state'];
+/** The live pull request as gh reports it, whatever its state. */
+export async function readLivePullRequest(gh, pr) {
     const output = await gh(['pr', 'view', String(pr), '--json', FIELDS.join(',')]);
     const live = JSON.parse(output);
     if (!isLive(live))
         throw new Error(`gh pr view ${pr} did not return ${FIELDS.join(', ')}`);
+    return live;
+}
+/** The live pull request, rejected unless it is open. */
+export async function livePullRequest(gh, pr) {
+    const live = await readLivePullRequest(gh, pr);
     // A closed or merged PR can share a reused branch name; its history must not be rewritten.
     if (live.state !== 'OPEN')
         throw new Error(`pull request ${pr} is ${live.state}, not OPEN`);

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

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

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

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

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

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