vouchington-tooling 0.44.0 → 0.46.0

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/gh-cli/env.d.mts

@@ -0,0 +1,9 @@
+/**
+ * The environment to spawn `gh` with: `env` minus `CLICOLOR_FORCE`. A non-zero `CLICOLOR_FORCE`
+ * makes `gh ... --json` emit ANSI-colored JSON even on a pipe, and `NO_COLOR` does not override
+ * it, so callers that `JSON.parse` gh output would throw. Deleting the key (rather than setting
+ * it to `0`) restores gh's default and never adds a variable the caller did not have. Every other
+ * variable passes through untouched; the input is not mutated. Windows environment variable names
+ * are case-insensitive, so the key is matched case-insensitively there.
+ */
+export declare function ghSpawnEnv(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): NodeJS.ProcessEnv;

package/dist/gh-cli/env.mjs

@@ -0,0 +1,12 @@
+/**
+ * The environment to spawn `gh` with: `env` minus `CLICOLOR_FORCE`. A non-zero `CLICOLOR_FORCE`
+ * makes `gh ... --json` emit ANSI-colored JSON even on a pipe, and `NO_COLOR` does not override
+ * it, so callers that `JSON.parse` gh output would throw. Deleting the key (rather than setting
+ * it to `0`) restores gh's default and never adds a variable the caller did not have. Every other
+ * variable passes through untouched; the input is not mutated. Windows environment variable names
+ * are case-insensitive, so the key is matched case-insensitively there.
+ */
+export function ghSpawnEnv(env = process.env, platform = process.platform) {
+    const isForcedColor = (key) => platform === 'win32' ? key.toUpperCase() === 'CLICOLOR_FORCE' : key === 'CLICOLOR_FORCE';
+    return Object.fromEntries(Object.entries(env).filter(([key]) => !isForcedColor(key)));
+}

package/dist/gh-cli/exec.d.mts

@@ -1,16 +1,19 @@
 /** A text-mode command runner: argv in, stdout out. Rejects on a non-zero exit. */
 export type RunTextCommand = (args: string[]) => Promise<string>;
 /** The `child_process.execFile` shape `createCommandRunner` wraps — injectable for tests. */
-export type ExecFileText = (command: string, args: string[]) => Promise<{
+export type ExecFileText = (command: string, args: string[], options?: {
+    env: NodeJS.ProcessEnv;
+}) => Promise<{
     stdout: string;
 }>;
 /**
  * Builds a `RunTextCommand` bound to a fixed binary. The default `exec` wraps `execFile` via
  * `promisify` so a test can inject a fake without spawning a real process; `runGh`/`runGit` below
- * are this factory applied to the two binaries this module cares about.
+ * are this factory applied to the two binaries this module cares about. `buildEnv` maps the
+ * parent environment to the one the child is spawned with (identity by default).
  */
-export declare function createCommandRunner(command: string, exec?: ExecFileText): RunTextCommand;
-/** Runs `gh` and returns its stdout. */
+export declare function createCommandRunner(command: string, exec?: ExecFileText, buildEnv?: (env: NodeJS.ProcessEnv) => NodeJS.ProcessEnv): RunTextCommand;
+/** Runs `gh` and returns its stdout, with `CLICOLOR_FORCE` removed so `--json` output stays plain. */
 export declare const runGh: RunTextCommand;
 /** Runs `git` and returns its stdout. */
 export declare const runGit: RunTextCommand;

package/dist/gh-cli/exec.mjs

@@ -1,18 +1,20 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { ghSpawnEnv } from "./env.mjs";
 const execFileAsync = promisify(execFile);
 /**
  * Builds a `RunTextCommand` bound to a fixed binary. The default `exec` wraps `execFile` via
  * `promisify` so a test can inject a fake without spawning a real process; `runGh`/`runGit` below
- * are this factory applied to the two binaries this module cares about.
+ * are this factory applied to the two binaries this module cares about. `buildEnv` maps the
+ * parent environment to the one the child is spawned with (identity by default).
  */
-export function createCommandRunner(command, exec = (cmd, args) => execFileAsync(cmd, args)) {
+export function createCommandRunner(command, exec = (cmd, args, options) => execFileAsync(cmd, args, { ...options, encoding: 'utf8' }), buildEnv = (env) => env) {
     return async (args) => {
-        const { stdout } = await exec(command, args);
+        const { stdout } = await exec(command, args, { env: buildEnv(process.env) });
         return stdout;
     };
 }
-/** Runs `gh` and returns its stdout. */
-export const runGh = createCommandRunner('gh');
+/** Runs `gh` and returns its stdout, with `CLICOLOR_FORCE` removed so `--json` output stays plain. */
+export const runGh = createCommandRunner('gh', undefined, ghSpawnEnv);
 /** Runs `git` and returns its stdout. */
 export const runGit = createCommandRunner('git');

package/dist/gh-cli/index.d.mts

@@ -1,4 +1,5 @@
 export { createCommandRunner, runGh, runGit } from './exec.mts';
+export { ghSpawnEnv } from './env.mts';
 export type { ExecFileText, RunTextCommand } from './exec.mts';
 export { DiffCommandError, processDiffCommand } from './diff.mts';
 export type { DiffBlockCallback, DiffCommand } from './diff.mts';

package/dist/gh-cli/index.mjs

@@ -1,4 +1,5 @@
 export { createCommandRunner, runGh, runGit } from "./exec.mjs";
+export { ghSpawnEnv } from "./env.mjs";
 export { DiffCommandError, processDiffCommand } from "./diff.mjs";
 export { GITHUB_BODY_MAX_CHARACTERS, validateGitHubBodyLength } from "./body-length.mjs";
 export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadError, HeadNotPushedError, HeadOutOfDateError, resolveHeadBranch, } from "./pr-create.mjs";

package/dist/gha-post-review/github.mjs

@@ -1,5 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { appendFileSync } from 'node:fs';
+import { ghSpawnEnv } from "../gh-cli/env.mjs";
 import { ReviewPayloadError } from "../gha-review-payload/index.mjs";
 import { readRegularReviewPayload } from "../gha-review-payload/index.mjs";
 import { createActionsClaudeTokenIo, withClaudeAppToken } from "./claude-token.mjs";
@@ -11,7 +12,7 @@ export function createGhExec(exec = execFileSync) {
     return (args, options) => exec('gh', [...args], {
         encoding: 'utf8',
         input: options?.input,
-        env: options?.env ?? process.env,
+        env: ghSpawnEnv(options?.env ?? process.env),
     }).trim();
 }
 export function writePostedOutput(posted, commentCount, outputPath = process.env.GITHUB_OUTPUT) {

package/dist/index.d.mts

@@ -8,8 +8,8 @@ export { runRetrospectiveFacts } from './retrospective-facts/index.mts';
 export type { CommandExecutor, CommandResult, RetrospectiveFactsOptions, } from './retrospective-facts/index.mts';
 export { appendJournal, assertSessionId, cleanupSnapshotPartitions, partitionSnapshot, probeBlackboard, readJournal, resolveBlackboardConnection, } from './agent-blackboard/index.mts';
 export type { BlackboardConnection, SnapshotChecksum, SnapshotCleanupReceipt, SnapshotCleanupOptions, SnapshotCounts, SnapshotManifest, SnapshotPartition, SnapshotPartitionOptions, SnapshotPartitionResult, SnapshotSelection, } from './agent-blackboard/index.mts';
-export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from './session-friction/index.mts';
-export type { FrictionEvent, FrictionEventKind, FrictionLogOptions, FrictionLogReadResult, FrictionObservation, JournalEntry, JournalLoader, JournalLoadResult, PermissionRequestObservation, SessionFrictionReport, SessionFrictionReportOptions, ToolResultObservation, } from './session-friction/index.mts';
+export { isConformingCiFailureBlock } from './audit-journal/ci-failures.mts';
+export type { JournalEntry, JournalLoader, JournalLoadResult } from './audit-journal/types.mts';
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mts';
 export type { EphemeralListenerOptions, RunnerPortPolicy } from './runner-port-policy/index.mts';
 export { extractCreateTableMetadata, extractDefaultFunction, extractFuncCallArgColumnNames, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mts';
@@ -95,7 +95,7 @@ export { validateResolvedPinDelta } from './swift-resolved-pin-delta/index.mts';
 export type { ResolvedDocument, ResolvedPin, ValidateResolvedPinDeltaOptions, } from './swift-resolved-pin-delta/index.mts';
 export { DEFAULT_MAX_DIAGNOSTIC_REPORTS, DEFAULT_MAX_FORMATTED_DIAGNOSTIC_REPORTS, formatDiagnosticReportSummaries, HARD_MAX_DIAGNOSTIC_REPORTS, readDiagnosticReportSummaries, summarizeDiagnosticReport, } from './vitest-diagnostics/index.mts';
 export type { DiagnosticReportLimitOptions, DiagnosticReportSummary, } from './vitest-diagnostics/index.mts';
-export { createCommandRunner, runGh, runGit } from './gh-cli/index.mts';
+export { createCommandRunner, ghSpawnEnv, runGh, runGit } from './gh-cli/index.mts';
 export type { ExecFileText, RunTextCommand } from './gh-cli/index.mts';
 export { DiffCommandError, processDiffCommand } from './gh-cli/index.mts';
 export type { DiffBlockCallback, DiffCommand } from './gh-cli/index.mts';

package/dist/index.mjs

@@ -4,7 +4,7 @@ export { HARNESS_IDS, inspectHarnessEnvironment, selectHarnessSession, } from ".
 export { codexChildren, codexIdentity, computeTranscriptFacts, formatTranscriptFacts, formatUnavailable, resolveTranscriptFile, runRetrospectiveTranscript, } from "./retrospective-transcript/index.mjs";
 export { runRetrospectiveFacts } from "./retrospective-facts/index.mjs";
 export { appendJournal, assertSessionId, cleanupSnapshotPartitions, partitionSnapshot, probeBlackboard, readJournal, resolveBlackboardConnection, } from "./agent-blackboard/index.mjs";
-export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from "./session-friction/index.mjs";
+export { isConformingCiFailureBlock } from "./audit-journal/ci-failures.mjs";
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from "./runner-port-policy/index.mjs";
 export { extractCreateTableMetadata, extractDefaultFunction, extractFuncCallArgColumnNames, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from "./sql-ast/index.mjs";
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from "./sql-scanner/index.mjs";
@@ -52,7 +52,7 @@ export { normalizeSwiftSource } from "./swift-semantic-equal/index.mjs";
 export { isSwiftCodeOffset, parseUniqueSwiftBinaryTargetChecksum, } from "./swift-source-offset/index.mjs";
 export { validateResolvedPinDelta } from "./swift-resolved-pin-delta/index.mjs";
 export { DEFAULT_MAX_DIAGNOSTIC_REPORTS, DEFAULT_MAX_FORMATTED_DIAGNOSTIC_REPORTS, formatDiagnosticReportSummaries, HARD_MAX_DIAGNOSTIC_REPORTS, readDiagnosticReportSummaries, summarizeDiagnosticReport, } from "./vitest-diagnostics/index.mjs";
-export { createCommandRunner, runGh, runGit } from "./gh-cli/index.mjs";
+export { createCommandRunner, ghSpawnEnv, runGh, runGit } from "./gh-cli/index.mjs";
 export { DiffCommandError, processDiffCommand } from "./gh-cli/index.mjs";
 export { GITHUB_BODY_MAX_CHARACTERS, validateGitHubBodyLength } from "./gh-cli/index.mjs";
 export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadError, HeadNotPushedError, HeadOutOfDateError, resolveHeadBranch, } from "./gh-cli/index.mjs";

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,10 +15,14 @@ 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. */
     runGh?: GhRunner;
+    /** The connected MCP client's `clientInfo.name`, once `initialize` has completed. */
+    clientName?: () => string | undefined;
     /** Test seam: replaces the operating system user and host name. */
     device?: () => {
         user: string;

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;
@@ -15,11 +16,15 @@ export type ServerEnvironment = {
     spawnPolicy?: PolicySpawner;
     /** Test seam: replaces locating and running gh. */
     runGh?: GhRunner;
+    /** The connected MCP client's `clientInfo.name`, once `initialize` has completed. */
+    clientName?: () => string | undefined;
     /** Test seam: replaces the operating system user and host name. */
     device?: () => {
         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,7 +65,9 @@ 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.clientName === undefined ? {} : { clientName: environment.clientName }),
             ...(environment.device === undefined ? {} : { device: environment.device }),
             ...(environment.spawnPolicy === undefined ? {} : { spawnPolicy: environment.spawnPolicy }),
             // The client resolves from this package's install, like the SDK, never from the worktree.

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';