vouchington-tooling 0.44.0 → 0.45.0

package/dist/agent-blackboard/client.d.mts

@@ -32,6 +32,12 @@ export type BlackboardClientModule = {
     Snapshots?: new (connection: BlackboardConnection) => {
         export(options?: unknown): Promise<unknown>;
     };
+    /** Newer clients own the ownership markers of their exports and clean them with a capability. */
+    cleanupSnapshotPartitions?: (options: {
+        path?: string;
+        directory?: string;
+        cleanupToken?: string;
+    }) => Promise<void>;
 };
 type BlackboardClientLoader = () => Promise<BlackboardClientModule>;
 export type BlackboardClientDependencies = {

package/dist/cli/usage.d.mts

@@ -1,4 +1,4 @@
-export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  fresh-base                    Classify the worktree against a remote base branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  gha-collaborator-trust        Classify authors as write-access collaborators or not\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\n  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling\n  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal status --session-id UUID --outbox-directory PATH\nagent-blackboard journal flush --outbox-directory PATH [--session-id UUID]\nInteractive journal append requires --outbox-directory PATH.\nagent-blackboard journal is deprecated and being phased out: agents journal through the mcp server.\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,\n                         session_ensure, retrospective_check, retrospective_save,\n                         pr_validate, pr_create, pr_update,\n                         snapshot_export, and session_archive over stdio.\n                         Needs the optional @modelcontextprotocol/sdk peer (and zod).\n                         Launch it from inside the repository's git worktree.\n";
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  fresh-base                    Classify the worktree against a remote base branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  gha-collaborator-trust        Classify authors as write-access collaborators or not\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\n  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling\n  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal status --session-id UUID --outbox-directory PATH\nagent-blackboard journal flush --outbox-directory PATH [--session-id UUID]\nInteractive journal append requires --outbox-directory PATH.\nagent-blackboard journal is deprecated and being phased out: agents journal through the mcp server.\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,\n                         session_ensure, retrospective_check, retrospective_save,\n                         pr_validate, pr_create, pr_update,\n                         snapshot_export, snapshot_cleanup, and session_archive over stdio.\n                         Needs the optional @modelcontextprotocol/sdk peer (and zod).\n                         Launch it from inside the repository's git worktree.\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;
 export declare function commandNames(usage?: string): string[];
 export declare function commandUsage(command: string, usage?: string): string;

package/dist/cli/usage.mjs

@@ -130,7 +130,7 @@ mcp
   (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,
                          session_ensure, retrospective_check, retrospective_save,
                          pr_validate, pr_create, pr_update,
-                         snapshot_export, and session_archive over stdio.
+                         snapshot_export, snapshot_cleanup, and session_archive over stdio.
                          Needs the optional @modelcontextprotocol/sdk peer (and zod).
                          Launch it from inside the repository's git worktree.
 `;

package/dist/mcp-server/context.d.mts

@@ -3,6 +3,7 @@ import type { FeedbackIdentity } from '../agent-blackboard/feedback-types.mts';
 import type { RunTextCommand } from '../gh-cli/exec.mts';
 import type { GhRunner } from './pr-gh.mts';
 import type { PolicySpawner } from './policy-spawn.mts';
+import type { SnapshotRegistry } from './snapshot-registry.mts';
 import { type Args } from './args.mts';
 /** What a handler may rely on: every field here was validated before the handler ran. */
 export type ToolContext = {
@@ -14,6 +15,8 @@ export type ToolContext = {
     launchRoot: string | undefined;
     /** Test seam: replaces the child process a policy export runs in. */
     spawnPolicy?: PolicySpawner;
+    /** The server's record of its own exports, which `snapshot_cleanup` is bound to. */
+    snapshots: SnapshotRegistry;
     /** Runs git with the isolated environment; callers add their own `-C <worktree>`. */
     runGit: RunTextCommand;
     /** Test seam: replaces locating and running gh. */

package/dist/mcp-server/dispatch.d.mts

@@ -2,6 +2,7 @@ import type { BlackboardClientDependencies } from '../agent-blackboard/client.mt
 import type { RunTextCommand } from '../gh-cli/exec.mts';
 import type { GhRunner } from './pr-gh.mts';
 import type { PolicySpawner } from './policy-spawn.mts';
+import { type SnapshotRegistry } from './snapshot-registry.mts';
 export type ServerEnvironment = {
     /** The launch directory's worktree top level, or undefined when it is not inside one. */
     launchRoot: string | undefined;
@@ -20,6 +21,8 @@ export type ServerEnvironment = {
         user: string;
         host: string;
     };
+    /** Test seam: a fresh registry stands in for a server restart. Defaults to the process's own. */
+    snapshots?: SnapshotRegistry;
 };
 export type ToolCallResult = {
     content: Array<{

package/dist/mcp-server/dispatch.mjs

@@ -2,12 +2,16 @@ import { FeedbackDeliveryError } from "../agent-blackboard/index.mjs";
 import { optionalString, rejectUnknown, requireObject } from "./args.mjs";
 import { readSessionId } from "./context.mjs";
 import { journalAppend, journalEntries } from "./handlers-journal.mjs";
-import { retrospectiveCheck, retrospectiveSave } from "./handlers-retrospective.mjs";
+import { retrospectiveSave } from "./handlers-retrospective.mjs";
+import { retrospectiveCheck } from "./retrospective-check.mjs";
 import { outboxFlush, outboxStatus } from "./handlers-outbox.mjs";
+import { snapshotCleanup } from "./handlers-snapshot-cleanup.mjs";
 import { sessionArchive, sessionEnsure, snapshotExport } from "./handlers-session.mjs";
 import { handlePrCreate, handlePrUpdate, handlePrValidate } from "./handlers-pr.mjs";
+import { createSnapshotRegistry } from "./snapshot-registry.mjs";
 import { TOOLS } from "./tools.mjs";
 import { resolveWorktree } from "./worktree.mjs";
+const PROCESS_SNAPSHOTS = createSnapshotRegistry();
 const HANDLERS = {
     journal_append: journalAppend,
     journal_entries: journalEntries,
@@ -20,6 +24,7 @@ const HANDLERS = {
     pr_create: handlePrCreate,
     pr_update: handlePrUpdate,
     snapshot_export: snapshotExport,
+    snapshot_cleanup: snapshotCleanup,
     session_archive: sessionArchive,
 };
 const DIAGNOSTIC_HINTS = {
@@ -60,6 +65,7 @@ export async function callTool(name, rawArguments, environment) {
             env: environment.env,
             launchRoot: environment.launchRoot,
             runGit: environment.runGit,
+            snapshots: environment.snapshots ?? PROCESS_SNAPSHOTS,
             ...(environment.runGh === undefined ? {} : { runGh: environment.runGh }),
             ...(environment.device === undefined ? {} : { device: environment.device }),
             ...(environment.spawnPolicy === undefined ? {} : { spawnPolicy: environment.spawnPolicy }),

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

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

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

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

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

@@ -1,4 +1,4 @@
-import { type ToolHandler } from './context.mts';
+import type { ToolHandler } from './context.mts';
 export declare const handlePrValidate: ToolHandler;
 export declare const handlePrCreate: ToolHandler;
 export declare const handlePrUpdate: ToolHandler;

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

@@ -1,115 +1,24 @@
-import { hostname, userInfo } from 'node:os';
-import { validateGitHubBodyLength } from "../gh-cli/body-length.mjs";
 import { createPullRequest } from "../gh-cli/pr-create.mjs";
-import { assertPolicyAllowed } from "./context.mjs";
-import { runValidator } from "./policy-run.mjs";
-import { renderPullRequestBody, worktreeLabel } from "./pr-body.mjs";
 import { pullRequestNumber, withBodyFile } from "./pr-body-file.mjs";
 import { pullRequestDefaults } from "./pr-defaults.mjs";
-import { createGhRunner, ghEnvironment } from "./pr-gh.mjs";
-import { checkTitleLength, positiveInteger, readPullRequestInput, } from "./pr-input.mjs";
-import { preserveShepherdJournal } from "./pr-journal.mjs";
-import { assertJournalUnchanged, credentials, liveBase, livePullRequest, redactCredentials, } from "./pr-live.mjs";
-import { parseWorktreeList } from "./worktree.mjs";
-function gitIn(context) {
-    return (args) => context.runGit(['-C', context.worktree, ...args]);
-}
-function ghIn(context) {
-    const run = context.runGh ?? createGhRunner(context.env);
-    const env = ghEnvironment(context.env);
-    return (args) => run(args, { cwd: context.worktree, env });
-}
-async function currentBranch(git) {
-    const branch = (await git(['rev-parse', '--abbrev-ref', 'HEAD'])).trim();
-    if (branch === 'HEAD')
-        throw new Error('the worktree has a detached HEAD: check out a branch');
-    return branch;
-}
-async function label(context, git) {
-    const listing = await git(['worktree', 'list', '--porcelain', '-z']);
-    return worktreeLabel(context.worktree, parseWorktreeList(listing)[0]);
-}
+import { positiveInteger } from "./pr-input.mjs";
+import { assertJournalUnchanged } from "./pr-live.mjs";
+import { ghIn, gitIn, policyFor, prepare } from "./pr-prepare.mjs";
 function readPr(args, required) {
     if (args.pr === undefined && !required)
         return undefined;
     return positiveInteger(args.pr, 'pr');
 }
-function policyFor(context) {
-    return {
-        worktree: context.worktree,
-        env: context.env,
-        ...(context.spawnPolicy === undefined ? {} : { spawn: context.spawnPolicy }),
-    };
-}
-/** Renders the body, preserves the live journal for an update, and runs the policy validator. */
-async function prepare(args, context, pr) {
-    assertPolicyAllowed(context);
-    // No server credential may reach the policy or gh, whatever the caller wrote: every field is
-    // redacted before anything is rendered or forwarded.
-    const secrets = credentials(context.env);
-    const given = redactCredentials(readPullRequestInput(args), secrets);
-    checkTitleLength(given.title);
-    const git = gitIn(context);
-    const head = await currentBranch(git);
-    // Branch names are refs passed to gh as is: redacting one would name a branch that does not exist.
-    if (secrets.some((secret) => head.includes(secret)))
-        throw new Error('the worktree branch name contains a server credential: rename the branch');
-    if (secrets.some((secret) => args.base?.includes(secret)))
-        throw new Error('base contains a server credential: use another base branch');
-    const live = pr === undefined ? undefined : await livePullRequest(ghIn(context), pr);
-    if (live !== undefined && live.headRefName !== head)
-        throw new Error(`pull request ${pr} has head ${live.headRefName}, not the worktree branch ${head}`);
-    const base = live === undefined
-        ? given.base
-        : liveBase(pr, live, redactCredentials(args.base, secrets));
-    const input = { ...given, base };
-    if (head === base)
-        throw new Error(`head branch ${head} must differ from base ${base}`);
-    const device = (context.device ?? (() => ({ user: userInfo().username, host: hostname() })))();
-    let body = renderPullRequestBody(input, {
-        sessionId: context.sessionId,
-        ...device,
-        worktree: await label(context, git),
-    });
-    if (live !== undefined)
-        body = preserveShepherdJournal(body, live.body);
-    body = redactCredentials(body, secrets);
-    const length = validateGitHubBodyLength(body);
-    if (!length.ok)
-        throw new Error(`the rendered body has ${length.characterCount} characters; GitHub allows ${length.maxCharacterCount}`);
-    const report = await runValidator({
-        ...policyFor(context),
-        export: 'validatePullRequest',
-        input: {
-            title: input.title,
-            body,
-            base: input.base,
-            head,
-            mode: input.mode,
-            ...(pr === undefined ? {} : { pr }),
-        },
-    });
-    const errors = 'errors' in report ? report.errors : [];
-    const warnings = 'warnings' in report ? report.warnings : [];
-    return {
-        input,
-        head,
-        body,
-        errors,
-        warnings,
-        ...(live === undefined ? {} : { liveBody: live.body }),
-    };
-}
 function rejectErrors(prepared) {
     if (prepared.errors.length)
         throw new Error(`policy rejected the pull request:\n- ${prepared.errors.join('\n- ')}`);
 }
 export const handlePrValidate = async (args, context) => {
-    const { body, errors, warnings } = await prepare(args, context, readPr(args, false));
+    const { body, errors, warnings } = await prepare(args, context, 'validate', readPr(args, false));
     return { body, errors, warnings };
 };
 export const handlePrCreate = async (args, context) => {
-    const prepared = await prepare(args, context, undefined);
+    const prepared = await prepare(args, context, 'create', undefined);
     rejectErrors(prepared);
     const { input, head, body } = prepared;
     const defaults = await pullRequestDefaults(policyFor(context), input);
@@ -127,7 +36,7 @@ export const handlePrCreate = async (args, context) => {
 };
 export const handlePrUpdate = async (args, context) => {
     const pr = readPr(args, true);
-    const prepared = await prepare(args, context, pr);
+    const prepared = await prepare(args, context, 'update', pr);
     rejectErrors(prepared);
     await assertJournalUnchanged(ghIn(context), pr, prepared.liveBody, prepared.input.base);
     const url = await withBodyFile(prepared.body, async (bodyFile) => (await ghIn(context)([

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

@@ -0,0 +1,10 @@
+import { type ToolHandler } from './context.mts';
+/** The default event id, hashed when the session id would push it past the 256-byte limit. */
+export declare function defaultSourceEventId(sessionId: string): string;
+/**
+ * Saves the session's retrospective: composes it when `compose` is given, checks the arguments
+ * against the document's front matter, runs the checkout's `validateRetrospective` policy (in a
+ * child process) and writes nothing if it reports errors, then writes through the same verified
+ * path as `journal_append`.
+ */
+export declare const retrospectiveSave: ToolHandler;

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

@@ -0,0 +1,138 @@
+import { createHash } from 'node:crypto';
+import { createFeedbackEnvelope, validateFeedbackEnvelope } from "../agent-blackboard/index.mjs";
+import { optionalRecord, optionalString, requiredChoice, requiredString, requiredStringArray, } from "./args.mjs";
+import { assertPolicyAllowed, readIdentity } from "./context.mjs";
+import { MODES, OUTCOMES, readCoverage } from "./handlers-journal.mjs";
+import { runValidator } from "./policy-run.mjs";
+import { previewRegistry } from "./preview-registry.mjs";
+import { deliver, saveFromPreview } from "./retrospective-preview.mjs";
+import { parseRetrospectiveFrontMatter } from "./retrospective-front-matter.mjs";
+import { FEEDBACK_MARKDOWN_MAX_BYTES, redactFeedbackText, } from "../agent-blackboard/feedback-codec.mjs";
+import { composeFromArgs, sensitiveValues } from "./retrospective-input.mjs";
+import { checkFrontMatter, resolveRepositories } from "./retrospective-resolve.mjs";
+function readMarkdownSource(args) {
+    const compose = optionalRecord(args, 'compose');
+    if ((args.markdown === undefined) === (compose === undefined))
+        throw new Error('pass exactly one of markdown or compose');
+    return compose === undefined ? { markdown: requiredString(args, 'markdown') } : { compose };
+}
+/** The default event id, hashed when the session id would push it past the 256-byte limit. */
+export function defaultSourceEventId(sessionId) {
+    const id = `retrospective-${sessionId}`;
+    return Buffer.byteLength(id) <= 256
+        ? id
+        : `retrospective-${createHash('sha256').update(sessionId).digest('hex')}`;
+}
+/**
+ * Saves the session's retrospective: composes it when `compose` is given, checks the arguments
+ * against the document's front matter, runs the checkout's `validateRetrospective` policy (in a
+ * child process) and writes nothing if it reports errors, then writes through the same verified
+ * path as `journal_append`.
+ */
+export const retrospectiveSave = async (args, context) => {
+    assertPolicyAllowed(context);
+    const identity = readIdentity(args, context.sessionId);
+    const mode = requiredChoice(args, 'mode', MODES);
+    const sourceEventId = optionalString(args, 'sourceEventId') ?? defaultSourceEventId(context.sessionId);
+    if (args.previewToken !== undefined)
+        return saveFromPreview(args, context, identity, mode, sourceEventId);
+    const workOutcome = requiredChoice(args, 'workOutcome', OUTCOMES);
+    const feedbackCoverage = readCoverage(args);
+    const argRepositories = args.repositories === undefined ? undefined : requiredStringArray(args, 'repositories');
+    const category = optionalString(args, 'category');
+    if (args.dryRun !== undefined && typeof args.dryRun !== 'boolean')
+        throw new Error('dryRun must be a boolean');
+    const policy = {
+        worktree: context.worktree,
+        env: context.env,
+        ...(context.spawnPolicy === undefined ? {} : { spawn: context.spawnPolicy }),
+    };
+    const { markdown: given, compose } = readMarkdownSource(args);
+    if (compose !== undefined && args.knownSensitiveValues !== undefined)
+        throw new Error('with compose, pass knownSensitiveValues inside compose');
+    // A markdown save redacts every argument with the same values a compose save would.
+    const secrets = sensitiveValues(compose ?? { knownSensitiveValues: args.knownSensitiveValues }, context.env);
+    // Everything the policy sees is derived from the redacted document, never the raw input.
+    const redactedGiven = given === undefined ? undefined : redactFeedbackText(given, secrets);
+    // Reject a document that can never be stored before any policy export runs for it.
+    if (redactedGiven !== undefined && Buffer.byteLength(redactedGiven) > FEEDBACK_MARKDOWN_MAX_BYTES)
+        throw new Error(`markdown must be at most ${FEEDBACK_MARKDOWN_MAX_BYTES} bytes`);
+    const early = redactedGiven === undefined ? undefined : parseRetrospectiveFrontMatter(redactedGiven);
+    const repositories = await resolveRepositories(argRepositories, early?.repositories, policy);
+    const markdown = redactedGiven ??
+        redactFeedbackText(await composeFromArgs(compose, {
+            sessionId: context.sessionId,
+            repositories,
+            workOutcome,
+            feedbackCoverage,
+            worktree: context.worktree,
+            env: context.env,
+            dependencies: context.dependencies,
+        }), secrets);
+    const front = early ?? parseRetrospectiveFrontMatter(markdown);
+    checkFrontMatter(front, {
+        sessionId: context.sessionId,
+        workOutcome,
+        // The document was redacted before parsing, so compare it with equally redacted sources.
+        feedbackCoverage: {
+            ...feedbackCoverage,
+            sources: feedbackCoverage.sources.map((source) => redactFeedbackText(source, secrets)),
+        },
+        repositories: argRepositories,
+    });
+    // Building the envelope first rejects empty or oversized markdown before any policy runs.
+    const envelope = createFeedbackEnvelope({
+        schemaVersion: 1,
+        type: 'retrospective',
+        sourceEventId,
+        // The server owns the timestamp, as in journal_append.
+        timestamp: new Date().toISOString(),
+        date: front.date,
+        issues: front.issues,
+        prs: front.prs,
+        repositories,
+        markdown,
+        workOutcome,
+        feedbackCoverage,
+        ...(category === undefined ? {} : { category }),
+    }, { knownSensitiveValues: secrets });
+    const redactedFront = parseRetrospectiveFrontMatter(envelope.markdown);
+    validateFeedbackEnvelope(envelope);
+    const report = await runValidator({
+        ...policy,
+        export: 'validateRetrospective',
+        input: {
+            sessionId: context.sessionId,
+            parentSessionId: identity.parentSessionId,
+            mode,
+            workOutcome,
+            // The envelope's copy, which is redacted like the markdown.
+            feedbackCoverage: envelope.feedbackCoverage,
+            repositories,
+            markdown: envelope.markdown,
+            sourceEventId,
+            metadata: {
+                date: redactedFront.date,
+                issues: redactedFront.issues,
+                prs: redactedFront.prs,
+                description: redactedFront.description,
+            },
+        },
+    });
+    if ('errors' in report && report.errors.length)
+        throw new Error(`policy rejected the retrospective:\n- ${report.errors.join('\n- ')}`);
+    const warnings = 'warnings' in report ? report.warnings : [];
+    if (args.dryRun === true) {
+        const previewToken = previewRegistry.put({
+            sessionId: context.sessionId,
+            parentSessionId: identity.parentSessionId,
+            mode,
+            worktree: context.worktree,
+            sourceEventId,
+            envelope,
+            warnings,
+        });
+        return { markdown: envelope.markdown, previewToken, policy: { warnings } };
+    }
+    return { ...(await deliver(envelope, identity, mode, context)), policy: { warnings } };
+};

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

@@ -1,12 +1 @@
-import { type ToolHandler } from './context.mts';
-/** Whether the session already holds a retrospective, and which (sourceEventId, issues, prs). */
-export declare const retrospectiveCheck: ToolHandler;
-/** The default event id, hashed when the session id would push it past the 256-byte limit. */
-export declare function defaultSourceEventId(sessionId: string): string;
-/**
- * Saves the session's retrospective: composes it when `compose` is given, checks the arguments
- * against the document's front matter, runs the checkout's `validateRetrospective` policy (in a
- * child process) and writes nothing if it reports errors, then writes through the same verified
- * path as `journal_append`.
- */
-export declare const retrospectiveSave: ToolHandler;
+export { defaultSourceEventId, retrospectiveSave } from './handlers-retrospective-save.mts';

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

@@ -1,154 +1 @@
-import { createHash } from 'node:crypto';
-import { createFeedbackEnvelope, validateFeedbackEnvelope, writeFeedback, } from "../agent-blackboard/index.mjs";
-import { optionalRecord, optionalString, requiredChoice, requiredString, requiredStringArray, } from "./args.mjs";
-import { assertPolicyAllowed, outboxDirectory, readIdentity } from "./context.mjs";
-import { byCreatedAt, deliveryResponse, MODES, OUTCOMES, readCoverage, } from "./handlers-journal.mjs";
-import { readEntriesIfPresent } from "./journal-read.mjs";
-import { runValidator } from "./policy-run.mjs";
-import { parseRetrospectiveFrontMatter } from "./retrospective-front-matter.mjs";
-import { FEEDBACK_MARKDOWN_MAX_BYTES, redactFeedbackText, } from "../agent-blackboard/feedback-codec.mjs";
-import { composeFromArgs, sensitiveValues } from "./retrospective-input.mjs";
-import { checkFrontMatter, resolveRepositories } from "./retrospective-resolve.mjs";
-function retrospectiveData(entry) {
-    const data = entry?.data;
-    return data?.type === 'retrospective' ? data : undefined;
-}
-/** Whether the session already holds a retrospective, and which (sourceEventId, issues, prs). */
-export const retrospectiveCheck = async (args, context) => {
-    const sourceEventId = optionalString(args, 'sourceEventId');
-    const entries = await readEntriesIfPresent(context.sessionId, context.env, context.dependencies);
-    const found = (entries ?? [])
-        .toSorted(byCreatedAt)
-        .flatMap((entry) => {
-        const data = retrospectiveData(entry);
-        return data === undefined ? [] : [data];
-    })
-        .filter((data) => sourceEventId === undefined || data.sourceEventId === sourceEventId)
-        .map((data) => ({
-        sourceEventId: data.sourceEventId,
-        timestamp: data.timestamp,
-        issues: data.issues ?? [],
-        prs: data.prs ?? [],
-    }));
-    return { sessionId: context.sessionId, saved: found.length > 0, entries: found };
-};
-function readMarkdownSource(args) {
-    const compose = optionalRecord(args, 'compose');
-    if ((args.markdown === undefined) === (compose === undefined))
-        throw new Error('pass exactly one of markdown or compose');
-    return compose === undefined ? { markdown: requiredString(args, 'markdown') } : { compose };
-}
-/** The default event id, hashed when the session id would push it past the 256-byte limit. */
-export function defaultSourceEventId(sessionId) {
-    const id = `retrospective-${sessionId}`;
-    return Buffer.byteLength(id) <= 256
-        ? id
-        : `retrospective-${createHash('sha256').update(sessionId).digest('hex')}`;
-}
-/**
- * Saves the session's retrospective: composes it when `compose` is given, checks the arguments
- * against the document's front matter, runs the checkout's `validateRetrospective` policy (in a
- * child process) and writes nothing if it reports errors, then writes through the same verified
- * path as `journal_append`.
- */
-export const retrospectiveSave = async (args, context) => {
-    assertPolicyAllowed(context);
-    const identity = readIdentity(args, context.sessionId);
-    const mode = requiredChoice(args, 'mode', MODES);
-    const workOutcome = requiredChoice(args, 'workOutcome', OUTCOMES);
-    const feedbackCoverage = readCoverage(args);
-    const argRepositories = args.repositories === undefined ? undefined : requiredStringArray(args, 'repositories');
-    const sourceEventId = optionalString(args, 'sourceEventId') ?? defaultSourceEventId(context.sessionId);
-    const category = optionalString(args, 'category');
-    if (args.dryRun !== undefined && typeof args.dryRun !== 'boolean')
-        throw new Error('dryRun must be a boolean');
-    const policy = {
-        worktree: context.worktree,
-        env: context.env,
-        ...(context.spawnPolicy === undefined ? {} : { spawn: context.spawnPolicy }),
-    };
-    const { markdown: given, compose } = readMarkdownSource(args);
-    const secrets = sensitiveValues(compose, context.env);
-    // Everything the policy sees is derived from the redacted document, never the raw input.
-    const redactedGiven = given === undefined ? undefined : redactFeedbackText(given, secrets);
-    // Reject a document that can never be stored before any policy export runs for it.
-    if (redactedGiven !== undefined && Buffer.byteLength(redactedGiven) > FEEDBACK_MARKDOWN_MAX_BYTES)
-        throw new Error(`markdown must be at most ${FEEDBACK_MARKDOWN_MAX_BYTES} bytes`);
-    const early = redactedGiven === undefined ? undefined : parseRetrospectiveFrontMatter(redactedGiven);
-    const repositories = await resolveRepositories(argRepositories, early?.repositories, policy);
-    const markdown = redactedGiven ??
-        redactFeedbackText(await composeFromArgs(compose, {
-            sessionId: context.sessionId,
-            repositories,
-            workOutcome,
-            feedbackCoverage,
-            worktree: context.worktree,
-            env: context.env,
-            dependencies: context.dependencies,
-        }), secrets);
-    const front = early ?? parseRetrospectiveFrontMatter(markdown);
-    checkFrontMatter(front, {
-        sessionId: context.sessionId,
-        workOutcome,
-        // The document was redacted before parsing, so compare it with equally redacted sources.
-        feedbackCoverage: {
-            ...feedbackCoverage,
-            sources: feedbackCoverage.sources.map((source) => redactFeedbackText(source, secrets)),
-        },
-        repositories: argRepositories,
-    });
-    // Building the envelope first rejects empty or oversized markdown before any policy runs.
-    const envelope = createFeedbackEnvelope({
-        schemaVersion: 1,
-        type: 'retrospective',
-        sourceEventId,
-        // The server owns the timestamp, as in journal_append.
-        timestamp: new Date().toISOString(),
-        date: front.date,
-        issues: front.issues,
-        prs: front.prs,
-        repositories,
-        markdown,
-        workOutcome,
-        feedbackCoverage,
-        ...(category === undefined ? {} : { category }),
-    }, { knownSensitiveValues: secrets });
-    const redactedFront = parseRetrospectiveFrontMatter(envelope.markdown);
-    validateFeedbackEnvelope(envelope);
-    const report = await runValidator({
-        ...policy,
-        export: 'validateRetrospective',
-        input: {
-            sessionId: context.sessionId,
-            parentSessionId: identity.parentSessionId,
-            mode,
-            workOutcome,
-            // The envelope's copy, which is redacted like the markdown.
-            feedbackCoverage: envelope.feedbackCoverage,
-            repositories,
-            markdown: envelope.markdown,
-            sourceEventId,
-            metadata: {
-                date: redactedFront.date,
-                issues: redactedFront.issues,
-                prs: redactedFront.prs,
-                description: redactedFront.description,
-            },
-        },
-    });
-    if ('errors' in report && report.errors.length)
-        throw new Error(`policy rejected the retrospective:\n- ${report.errors.join('\n- ')}`);
-    const warnings = 'warnings' in report ? report.warnings : [];
-    if (args.dryRun === true)
-        return { markdown: envelope.markdown, policy: { warnings } };
-    const directory = mode === 'interactive' ? outboxDirectory(context.worktree) : undefined;
-    const result = await writeFeedback({
-        identity,
-        envelope,
-        mode,
-        ...(directory === undefined ? {} : { outboxDirectory: directory }),
-        env: context.env,
-        dependencies: context.dependencies,
-    });
-    return { ...deliveryResponse(result, context, mode), policy: { warnings } };
-};
+export { defaultSourceEventId, retrospectiveSave } from "./handlers-retrospective-save.mjs";