vouchington-tooling 0.40.0 → 0.42.0

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

@@ -0,0 +1,15 @@
+import type { FeedbackCoverage } from '../agent-blackboard/index.mts';
+import { type PolicyRun } from './policy-run.mts';
+import type { RetrospectiveFrontMatter } from './retrospective-front-matter.mts';
+/** Rejects, naming the field, any argument the document's own front matter contradicts. */
+export declare function checkFrontMatter(front: RetrospectiveFrontMatter, args: {
+    sessionId: string;
+    workOutcome: string;
+    feedbackCoverage: FeedbackCoverage;
+    repositories: string[] | undefined;
+}): void;
+/**
+ * The canonical (sorted, deduplicated, lowercase) repositories: the argument, else the
+ * document's front matter, else the policy's `pullRequestDefaults().repositories`, else an error.
+ */
+export declare function resolveRepositories(args: string[] | undefined, front: string[] | undefined, policy: Omit<PolicyRun, 'export' | 'input'>): Promise<string[]>;

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

@@ -0,0 +1,41 @@
+import { normalizeRepositories } from "../agent-blackboard/feedback-codec.mjs";
+import { runPolicyExport } from "./policy-run.mjs";
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+/** Rejects, naming the field, any argument the document's own front matter contradicts. */
+export function checkFrontMatter(front, args) {
+    const mismatches = [];
+    if (front.sessionId !== undefined && front.sessionId !== args.sessionId)
+        mismatches.push('session_id does not match sessionId');
+    if (front.workOutcome !== undefined && front.workOutcome !== args.workOutcome)
+        mismatches.push('work_outcome does not match workOutcome');
+    if (front.feedbackCoverage !== undefined) {
+        // Field by field, so the document's JSON key order does not matter; sources stay ordered.
+        const { status, sources, droppedCount } = args.feedbackCoverage;
+        const given = front.feedbackCoverage;
+        if (given.status !== status ||
+            given.droppedCount !== droppedCount ||
+            !same(given.sources, sources))
+            mismatches.push('feedback_coverage does not match feedbackCoverage');
+    }
+    if (front.repositories !== undefined &&
+        args.repositories !== undefined &&
+        !same(normalizeRepositories(front.repositories), normalizeRepositories(args.repositories)))
+        mismatches.push('repositories does not match repositories');
+    if (mismatches.length)
+        throw new Error(`retrospective front matter contradicts the arguments: ${mismatches.join('; ')}`);
+}
+/**
+ * The canonical (sorted, deduplicated, lowercase) repositories: the argument, else the
+ * document's front matter, else the policy's `pullRequestDefaults().repositories`, else an error.
+ */
+export async function resolveRepositories(args, front, policy) {
+    const given = args ?? front;
+    if (given !== undefined)
+        return normalizeRepositories(given);
+    const defaults = await runPolicyExport({ ...policy, export: 'pullRequestDefaults', input: {} });
+    const repositories = (defaults.status === 'ok' ? defaults.result : undefined);
+    if (Array.isArray(repositories?.repositories) && repositories.repositories.length)
+        return normalizeRepositories(repositories.repositories);
+    throw new Error('repositories is required: pass it, put it in the front matter, or have the policy ' +
+        'pullRequestDefaults export return { repositories }');
+}

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

@@ -0,0 +1,2 @@
+import { type ToolDefinition } from './tools-schema.mts';
+export declare const RETROSPECTIVE_TOOLS: readonly ToolDefinition[];

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

@@ -0,0 +1,48 @@
+import { ADDITIVE, COVERAGE, IDENTITY, IDENTITY_REQUIRED, ID_PATTERN, OUTCOMES, READ_ONLY, tool, } from "./tools-schema.mjs";
+export const RETROSPECTIVE_TOOLS = [
+    tool('retrospective_check', 'Reports whether the session already holds a retrospective: { sessionId, saved, entries } ' +
+        'where each entry is { sourceEventId, timestamp, issues, prs } for an entry of type ' +
+        'retrospective, oldest first. sourceEventId narrows the result. A session that was never ' +
+        'created reports saved: false.', READ_ONLY, { sourceEventId: { type: 'string', pattern: ID_PATTERN, description: 'Only this event id.' } }),
+    tool('retrospective_save', 'Saves the session retrospective after the checkout policy accepts it, and returns the same ' +
+        'verified receipt as journal_append (status, receipt, timestamp, pendingCount, ' +
+        'worktreePendingCount) plus policy.warnings. Pass exactly one of markdown (a finished ' +
+        'document opening with the front matter composeRetrospective writes: date, issues, prs ' +
+        'and optionally session_id, description, work_outcome, feedback_coverage, repositories, ' +
+        'each line key: <JSON>; any that repeat an argument must equal it) or compose (the retrospective ' +
+        'composer input: narrative, date, issues, prs, description, facts, transcript, tools, ' +
+        'architecture, optional knownSensitiveValues; the server adds the rest). compose.transcript ' +
+        'takes only { sessionId?, harnessSessionId? } (sessionId must be the call sessionId; the ' +
+        'transcript is found by harnessSessionId, the harness session UUID, else by sessionId when ' +
+        'that is a UUID, in the default session roots of the worktree) or { status, reason } to report it ' +
+        'unassessed; any path override is rejected. The server redacts its blackboard token ' +
+        'from the document before the policy sees it. dryRun returns ' +
+        '{ markdown, policy: { warnings } } and writes nothing. The worktree package.json may ' +
+        'declare "vouchington-tooling": { "policy": "<module>" }; its validateRetrospective export ' +
+        'runs in a child process, and any error it reports rejects the save with nothing written. ' +
+        'Policy tools need a server launched inside a repository worktree. The server owns the ' +
+        'timestamp. sourceEventId defaults to retrospective-<sessionId> (retrospective-<sha256 hex of the ' +
+        'sessionId> when that exceeds 256 bytes); saving changed content ' +
+        'under the same sourceEventId is an event-conflict, so a revision needs a new ' +
+        'sourceEventId. Repeat an identical markdown call to retry. compose regenerates the document, ' +
+        'so deliver a retained compose save with outbox_flush instead of repeating it. Counts ' +
+        'follow journal_append.', ADDITIVE, {
+        ...IDENTITY,
+        mode: { enum: ['interactive', 'autonomous'], description: 'Delivery mode.' },
+        workOutcome: { enum: OUTCOMES, description: 'Outcome of the work being reported.' },
+        feedbackCoverage: COVERAGE,
+        repositories: {
+            type: 'array',
+            items: { type: 'string' },
+            minItems: 1,
+            description: 'Exact owner/name repositories; stored sorted, deduplicated and lowercase. Default: ' +
+                'the front matter repositories, else the policy pullRequestDefaults repositories; ' +
+                'an error when none.',
+        },
+        markdown: { type: 'string', description: 'Finished retrospective markdown.' },
+        compose: { type: 'object', description: 'Composer input; exclusive with markdown.' },
+        sourceEventId: { type: 'string', pattern: ID_PATTERN, description: 'Stable event id.' },
+        category: { type: 'string', description: 'Optional context; never changes entry type.' },
+        dryRun: { type: 'boolean', description: 'Compose and validate only; write nothing.' },
+    }, [...IDENTITY_REQUIRED, 'mode', 'workOutcome', 'feedbackCoverage']),
+];

package/dist/mcp-server/tools-schema.d.mts

@@ -0,0 +1,54 @@
+export type JsonSchema = Record<string, unknown>;
+export type ToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, JsonSchema>;
+        required: string[];
+        additionalProperties: false;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare const ID_PATTERN = "^[A-Za-z0-9._:-]+$";
+export declare const PARENT_SESSION_ID: JsonSchema;
+export declare const AGENT: JsonSchema;
+export declare const VERSION: JsonSchema;
+export declare const OUTCOMES: string[];
+export declare const COVERAGE: JsonSchema;
+export declare const READ_ONLY: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export declare const ADDITIVE: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export declare const IDEMPOTENT_ADDITIVE: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export declare const MUTATING: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export declare function tool(name: string, description: string, annotations: ToolDefinition['annotations'], properties?: Record<string, JsonSchema>, required?: string[]): ToolDefinition;
+export declare const IDENTITY: {
+    parentSessionId: JsonSchema;
+    agent: JsonSchema;
+    version: JsonSchema;
+};
+export declare const IDENTITY_REQUIRED: string[];

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

@@ -0,0 +1,70 @@
+export const ID_PATTERN = '^[A-Za-z0-9._:-]+$';
+const SESSION_ID = {
+    type: 'string',
+    pattern: ID_PATTERN,
+    maxLength: 256,
+    description: 'Explicit session id (URL-safe). Never inferred by the server.',
+};
+const WORKTREE = {
+    type: 'string',
+    description: 'Absolute path of the top level of a git worktree (`git rev-parse --show-toplevel`), not a ' +
+        'subdirectory. Defaults to the launch directory worktree; required when the server was ' +
+        'launched outside a git worktree.',
+};
+export const PARENT_SESSION_ID = {
+    type: ['string', 'null'],
+    pattern: ID_PATTERN,
+    maxLength: 256,
+    description: 'Direct parent session id, or null for a root session.',
+};
+export const AGENT = { type: 'string', maxLength: 128, description: 'Agent name.' };
+export const VERSION = { type: 'string', maxLength: 128, description: 'Agent version.' };
+export const OUTCOMES = [
+    'in-progress',
+    'success',
+    'failure',
+    'cancelled',
+    'timed-out',
+    'no-change',
+    'policy-refusal',
+    'unknown',
+];
+const COVERAGE_STATUSES = ['complete', 'partial', 'unavailable', 'not-assessed', 'not-started'];
+export const COVERAGE = {
+    type: 'object',
+    properties: {
+        status: { enum: COVERAGE_STATUSES },
+        sources: { type: 'array', items: { type: 'string' } },
+        droppedCount: { type: 'integer', minimum: 0 },
+    },
+    required: ['status'],
+    additionalProperties: false,
+    description: 'Explicit coverage; sources default to [] and droppedCount to 0.',
+};
+export const READ_ONLY = flags(true, false, true);
+export const ADDITIVE = flags(false, false, false);
+export const IDEMPOTENT_ADDITIVE = flags(false, false, true);
+export const MUTATING = flags(false, true, true);
+function flags(readOnly, destructive, idempotent) {
+    return {
+        readOnlyHint: readOnly,
+        destructiveHint: destructive,
+        idempotentHint: idempotent,
+        openWorldHint: false,
+    };
+}
+export function tool(name, description, annotations, properties = {}, required = []) {
+    return {
+        name,
+        description,
+        inputSchema: {
+            type: 'object',
+            properties: { sessionId: SESSION_ID, worktree: WORKTREE, ...properties },
+            required: ['sessionId', ...required],
+            additionalProperties: false,
+        },
+        annotations,
+    };
+}
+export const IDENTITY = { parentSessionId: PARENT_SESSION_ID, agent: AGENT, version: VERSION };
+export const IDENTITY_REQUIRED = ['parentSessionId', 'agent', 'version'];

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

@@ -1,19 +1,2 @@
-type JsonSchema = Record<string, unknown>;
-export type ToolDefinition = {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: 'object';
-        properties: Record<string, JsonSchema>;
-        required: string[];
-        additionalProperties: false;
-    };
-    annotations: {
-        readOnlyHint: boolean;
-        destructiveHint: boolean;
-        idempotentHint: boolean;
-        openWorldHint: boolean;
-    };
-};
+import { type ToolDefinition } from './tools-schema.mts';
 export declare const TOOLS: readonly ToolDefinition[];
-export {};

package/dist/mcp-server/tools.mjs

@@ -1,62 +1,5 @@
-const ID_PATTERN = '^[A-Za-z0-9._:-]+$';
-const SESSION_ID = {
-    type: 'string',
-    pattern: ID_PATTERN,
-    maxLength: 256,
-    description: 'Explicit session id (URL-safe). Never inferred by the server.',
-};
-const WORKTREE = {
-    type: 'string',
-    description: 'Absolute path of the top level of a git worktree (`git rev-parse --show-toplevel`), not a ' +
-        'subdirectory. Defaults to the launch directory worktree; required when the server was ' +
-        'launched outside a git worktree.',
-};
-const PARENT_SESSION_ID = {
-    type: ['string', 'null'],
-    pattern: ID_PATTERN,
-    maxLength: 256,
-    description: 'Direct parent session id, or null for a root session.',
-};
-const AGENT = { type: 'string', maxLength: 128, description: 'Agent name.' };
-const VERSION = { type: 'string', maxLength: 128, description: 'Agent version.' };
-const OUTCOMES = [
-    'in-progress',
-    'success',
-    'failure',
-    'cancelled',
-    'timed-out',
-    'no-change',
-    'policy-refusal',
-    'unknown',
-];
-const COVERAGE_STATUSES = ['complete', 'partial', 'unavailable', 'not-assessed', 'not-started'];
-const READ_ONLY = flags(true, false, true);
-const ADDITIVE = flags(false, false, false);
-const IDEMPOTENT_ADDITIVE = flags(false, false, true);
-const MUTATING = flags(false, true, true);
-function flags(readOnly, destructive, idempotent) {
-    return {
-        readOnlyHint: readOnly,
-        destructiveHint: destructive,
-        idempotentHint: idempotent,
-        openWorldHint: false,
-    };
-}
-function tool(name, description, annotations, properties = {}, required = []) {
-    return {
-        name,
-        description,
-        inputSchema: {
-            type: 'object',
-            properties: { sessionId: SESSION_ID, worktree: WORKTREE, ...properties },
-            required: ['sessionId', ...required],
-            additionalProperties: false,
-        },
-        annotations,
-    };
-}
-const IDENTITY = { parentSessionId: PARENT_SESSION_ID, agent: AGENT, version: VERSION };
-const IDENTITY_REQUIRED = ['parentSessionId', 'agent', 'version'];
+import { ADDITIVE, AGENT, COVERAGE, IDEMPOTENT_ADDITIVE, IDENTITY, IDENTITY_REQUIRED, ID_PATTERN, MUTATING, OUTCOMES, PARENT_SESSION_ID, READ_ONLY, VERSION, tool, } from "./tools-schema.mjs";
+import { RETROSPECTIVE_TOOLS } from "./tools-retrospective.mjs";
 export const TOOLS = [
     tool('journal_append', 'Appends one journal entry to the caller session and returns the verified read-back receipt. ' +
         'Nothing is written unless every required field validates. Interactive mode retains the ' +
@@ -78,17 +21,7 @@ export const TOOLS = [
             minItems: 1,
             description: 'Exact owner/name repositories this entry concerns.',
         },
-        feedbackCoverage: {
-            type: 'object',
-            properties: {
-                status: { enum: COVERAGE_STATUSES },
-                sources: { type: 'array', items: { type: 'string' } },
-                droppedCount: { type: 'integer', minimum: 0 },
-            },
-            required: ['status'],
-            additionalProperties: false,
-            description: 'Explicit coverage; sources default to [] and droppedCount to 0.',
-        },
+        feedbackCoverage: COVERAGE,
         category: { type: 'string', description: 'Optional context; never changes entry type.' },
     }, [
         ...IDENTITY_REQUIRED,
@@ -112,6 +45,7 @@ export const TOOLS = [
         'as sourceEventId and diagnostic.', IDEMPOTENT_ADDITIVE),
     tool('session_ensure', 'Idempotently creates a session, or verifies that an existing one has the same identity. ' +
         'Returns the session id and whether it was created.', IDEMPOTENT_ADDITIVE, IDENTITY, IDENTITY_REQUIRED),
+    ...RETROSPECTIVE_TOOLS,
     tool('snapshot_export', 'Exports non-archived sessions into a private local JSONL file chosen by the blackboard ' +
         'client. Returns the path, counts, checksum, manifest, and cleanupToken; never the records. ' +
         'sessionId identifies the caller.', ADDITIVE, {

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

@@ -11,12 +11,19 @@ export declare const runIsolatedGit: RunTextCommand;
  * or an unsafe repository, is thrown with the cause rather than reported as "outside a worktree".
  */
 export declare function launchWorktreeRoot(cwd: string, runGit: RunTextCommand): Promise<string | undefined>;
+/**
+ * The worktree paths in `git worktree list --porcelain -z` output: NUL-terminated fields, an empty
+ * field ending each record, so a path containing a newline cannot forge a record.
+ */
+export declare function parseWorktreeList(output: string): string[];
 /**
  * Resolves the worktree a tool call may act on. It must be an absolute path that, after
- * resolving symlinks, is exactly the top level of a git worktree (of any repository on the
- * machine). A subdirectory, a relative or nonexistent path, and a non-git directory are rejected.
- * Git is asked on every call, so worktrees created after the server started are accepted and
- * removed ones are not. Without `requested`, the launch worktree is used when there is one.
+ * resolving symlinks, is exactly the top level of a git worktree. A subdirectory, a relative or
+ * nonexistent path, and a non-git directory are rejected. When the server was launched inside a
+ * repository, the path must also be one of that repository's worktrees (primary or linked), so an
+ * unrelated `git init` directory is refused. A server launched outside any repository accepts the
+ * top level of any worktree. Git is asked on every call, so worktrees created after the server
+ * started are accepted and removed ones are not. Without `requested`, the launch worktree is used.
  */
 export declare function resolveWorktree(input: {
     launchRoot: string | undefined;

package/dist/mcp-server/worktree.mjs

@@ -52,12 +52,33 @@ export async function launchWorktreeRoot(cwd, runGit) {
     }
     return realpath(output.trim());
 }
+/**
+ * The worktree paths in `git worktree list --porcelain -z` output: NUL-terminated fields, an empty
+ * field ending each record, so a path containing a newline cannot forge a record.
+ */
+export function parseWorktreeList(output) {
+    return output
+        .split('\0')
+        .filter((field) => field.startsWith('worktree '))
+        .map((field) => field.slice('worktree '.length));
+}
+/**
+ * The real paths of every worktree of the repository containing `root` (the primary worktree and
+ * each linked one).
+ */
+async function repositoryWorktrees(root, runGit) {
+    const output = await runGit(['-C', root, 'worktree', 'list', '--porcelain', '-z']);
+    const paths = parseWorktreeList(output).map(canonical);
+    return new Set((await Promise.all(paths)).filter((path) => path !== undefined));
+}
 /**
  * Resolves the worktree a tool call may act on. It must be an absolute path that, after
- * resolving symlinks, is exactly the top level of a git worktree (of any repository on the
- * machine). A subdirectory, a relative or nonexistent path, and a non-git directory are rejected.
- * Git is asked on every call, so worktrees created after the server started are accepted and
- * removed ones are not. Without `requested`, the launch worktree is used when there is one.
+ * resolving symlinks, is exactly the top level of a git worktree. A subdirectory, a relative or
+ * nonexistent path, and a non-git directory are rejected. When the server was launched inside a
+ * repository, the path must also be one of that repository's worktrees (primary or linked), so an
+ * unrelated `git init` directory is refused. A server launched outside any repository accepts the
+ * top level of any worktree. Git is asked on every call, so worktrees created after the server
+ * started are accepted and removed ones are not. Without `requested`, the launch worktree is used.
  */
 export async function resolveWorktree(input) {
     const { launchRoot, requested, runGit } = input;
@@ -68,8 +89,12 @@ export async function resolveWorktree(input) {
     if (!isAbsolute(path))
         throw new Error('worktree must be an absolute path to a git worktree');
     const target = await canonical(path);
-    if (target !== undefined && (await launchWorktreeRoot(target, runGit)) === target)
-        return target;
+    if (target !== undefined && (await launchWorktreeRoot(target, runGit)) === target) {
+        if (launchRoot === undefined || (await repositoryWorktrees(launchRoot, runGit)).has(target))
+            return target;
+        throw new Error(`worktree ${path} is not a worktree of the repository this server was launched in ` +
+            `(${launchRoot}); \`git worktree list\` there names the worktrees it may act on`);
+    }
     throw new Error(`worktree ${path} is not the top level of a git worktree: it must exist and be the ` +
         'directory `git rev-parse --show-toplevel` reports, not a subdirectory of it');
 }

package/dist/pg-schema-snapshot/generated-arbiter-facts.d.mts

@@ -11,7 +11,7 @@ type GeneratedArbiterRoot = {
     kind: 'parenthesized';
     expression: GeneratedArbiterRoot;
 } | {
-    kind: 'functionCall' | 'cast' | 'nullTest' | 'distinctness' | 'parameter' | 'typedLiteral' | 'literal' | 'binary' | 'unary' | 'case' | 'subquery' | 'other';
+    kind: 'functionCall' | 'cast' | 'nullTest' | 'distinctness' | 'parameter' | 'typedLiteral' | 'literal' | 'binary' | 'unary' | 'array' | 'case' | 'subquery' | 'other';
 };
 export type GeneratedArbiterExpression = {
     columns: readonly GeneratedArbiterName[];

package/docs/mcp-server.md

@@ -6,8 +6,8 @@ a tool argument; there is no temp file, `--file`, or replay command. The server
 existing `vouchington-tooling/agent-blackboard` exports and adds no provider protocol.
 
 Phase 1 of [vouchington-tooling#324](https://github.com/vouchington/vouchington-tooling/issues/324)
-covers the journal, outbox, session, and snapshot tools below. Retrospective and pull request tools
-are later phases.
+covers the journal, outbox, session, and snapshot tools below. Phase 2 adds the retrospective tools
+and the policy contract they run. Pull request tools are a later phase.
 
 ## Install
 
@@ -40,8 +40,10 @@ environment. The server never searches for, prints, or mints them.
 
 ## CLI fallback
 
-If MCP is unavailable, use `vouchington agent-blackboard journal append|entries|flush|status` as described
-in the blackboard skill. Record the fallback and delivery status in the journal and tell the human. The CLI resolves its
+MCP is the supported path. If it is unavailable, restore it first as the blackboard skill describes.
+As a last resort, use `vouchington agent-blackboard journal append|entries|flush|status` as described
+there; sandboxed Claude Code and Codex withhold the token, so it can only retain records in the
+outbox the server later flushes. Record the fallback and delivery status in the journal and tell the human. The CLI resolves its
 client from its own installation, so install `agent-blackboard` alongside that trusted CLI.
 Run the script with a verified absolute `node` and a cleared environment (`env -i`), never through
 its `#!/usr/bin/env node` line, which takes `node` from a possibly repository-controlled `PATH`.
@@ -80,15 +82,17 @@ Every tool takes an explicit `sessionId` (`^[A-Za-z0-9._:-]+$`, at most 256 char
 server never infers, and an optional `worktree`. Unknown arguments are rejected. Failures come back
 as MCP tool errors (`isError: true`) with an actionable message rather than crashing the server.
 
-| Tool              | Arguments besides `sessionId` and `worktree`                                                                                                                                       | Returns                                                                                                                                          |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `journal_append`  | `parentSessionId`, `agent`, `version`, `mode` (`interactive` or `autonomous`), `markdown`, `sourceEventId`, `workOutcome`, `repositories`, `feedbackCoverage`, optional `category` | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`), `pendingCount`, `worktreePendingCount`          |
-| `journal_entries` | none                                                                                                                                                                               | `sessionId` and `entries`, every entry oldest first                                                                                              |
-| `outbox_status`   | none                                                                                                                                                                               | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`                                          |
-| `outbox_flush`    | none                                                                                                                                                                               | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `deliveredCount`, `rejected` (when any) |
-| `session_ensure`  | `parentSessionId`, `agent`, `version`                                                                                                                                              | `sessionId`, `status` (`created` or `exists`), `archived`                                                                                        |
-| `snapshot_export` | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours`                                                                                    | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken`                                                                            |
-| `session_archive` | none                                                                                                                                                                               | `sessionId`, `archived: true`                                                                                                                    |
+| Tool                  | Arguments besides `sessionId` and `worktree`                                                                                                                                             | Returns                                                                                                                                          |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `journal_append`      | `parentSessionId`, `agent`, `version`, `mode` (`interactive` or `autonomous`), `markdown`, `sourceEventId`, `workOutcome`, `repositories`, `feedbackCoverage`, optional `category`       | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`), `pendingCount`, `worktreePendingCount`          |
+| `journal_entries`     | none                                                                                                                                                                                     | `sessionId` and `entries`, every entry oldest first                                                                                              |
+| `outbox_status`       | none                                                                                                                                                                                     | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`                                          |
+| `outbox_flush`        | none                                                                                                                                                                                     | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `deliveredCount`, `rejected` (when any) |
+| `session_ensure`      | `parentSessionId`, `agent`, `version`                                                                                                                                                    | `sessionId`, `status` (`created` or `exists`), `archived`                                                                                        |
+| `retrospective_check` | optional `sourceEventId`                                                                                                                                                                 | `sessionId`, `saved`, `entries` (`sourceEventId`, `timestamp`, `issues`, `prs` of each retrospective, oldest first)                              |
+| `retrospective_save`  | `parentSessionId`, `agent`, `version`, `mode`, `workOutcome`, `feedbackCoverage`, exactly one of `markdown` or `compose`, optional `repositories`, `sourceEventId`, `category`, `dryRun` | as `journal_append` plus `policy.warnings`; with `dryRun`, `markdown` and `policy.warnings`                                                      |
+| `snapshot_export`     | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours`                                                                                          | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken`                                                                            |
+| `session_archive`     | none                                                                                                                                                                                     | `sessionId`, `archived: true`                                                                                                                    |
 
 `journal_append` validates the whole feedback envelope with `validateFeedbackEnvelope` before
 anything is written, so a missing required field writes nothing. It returns the verified read-back
@@ -161,20 +165,92 @@ is unavailable.
 The server sends the same list in its MCP `instructions`, so a harness that surfaces server
 instructions shows it to the agent.
 
+## Retrospective tools and the policy contract
+
+`retrospective_check` reads the session through the same client as `journal_entries` and reports the
+entries whose envelope `type` is `retrospective`. A session that was never created (the blackboard
+answers 404) reports `saved: false`.
+
+`retrospective_save` builds a `retrospective` envelope and writes it exactly as `journal_append`
+does (same receipt, `pendingCount`, `worktreePendingCount`, outbox rules, and server-owned
+timestamp; a `timestamp` argument is rejected). The document comes from `markdown` or from
+`compose`, the input of `composeRetrospective` (`narrative`, `date`, `issues`, `prs`,
+`description`, `facts`, `transcript`, `tools`, `architecture`, optional `knownSensitiveValues`;
+unknown keys are rejected, and the journal audit reads through the server's own client).
+`compose.transcript` accepts only `{ sessionId?, harnessSessionId? }` (`sessionId` must equal the
+call's `sessionId`) or `{ status, reason }` for an unassessed transcript. The transcript is found by
+`harnessSessionId`, the harness's own session UUID, else by the call's `sessionId` when that is a
+UUID; otherwise the call fails rather than reporting the transcript unavailable. When the server's environment names its harness session (`CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, and so on), only that session's transcript is read (after `/clear` or a thread switch, reconnect the server, or pass `{ status, reason }`); `jsonlPath`, `projectsDir`, `codexSessionsDir`,
+`grokSessionsDir`, and `cwd` are rejected, and the server reads the transcript from the worktree
+and its default session roots. The server's blackboard token, and any `knownSensitiveValues`, are
+redacted from the document before the policy sees it or the envelope is stored. Facts commands
+are killed after 120 seconds. `compose.facts` takes `pr`, `branch`, `noPr`, or `{ status, reason }`;
+`repo` is rejected, so the server's GitHub token never queries a repository other than the
+worktree's. Facts run `git` and `gh` in the worktree as the server's user, honoring its
+repository configuration (which can select helpers that run code), so the worktree, including
+`.git/config`, must be as trusted as the policy module. `dryRun`
+runs every check and returns the document without writing.
+
+The document must open with the front matter `composeRetrospective` writes: lines of
+`key: <JSON value>` between two `---` lines. Recognized keys are `date`, `issues`, `prs` (required),
+`session_id`, `description`, `work_outcome`, `feedback_coverage` (`status`, `sources`,
+`droppedCount`), and `repositories`; anything else, a duplicate, or a malformed line is rejected.
+`session_id`, `work_outcome`, `feedback_coverage`, and `repositories` must equal the arguments when
+present. `repositories` resolves from the argument, else the front matter, else the policy's
+`pullRequestDefaults()` result, else an error, and is stored sorted, deduplicated, and lowercase.
+The default `sourceEventId` is `retrospective-<sessionId>`, or `retrospective-<sha256 hex of the
+sessionId>` when that would exceed 256 bytes. Re-saving identical content returns the
+stored receipt and timestamp. Changed content under the same `sourceEventId` is an
+`event-conflict`; a revision needs a new `sourceEventId`. `compose` regenerates the document from
+the live journal and repository, so repeating a `compose` call is not a retry: when an interactive
+save is retained in the outbox, deliver it with `outbox_flush`.
+
+### Policy module
+
+The consumer's root `package.json` may declare
+`"vouchington-tooling": { "policy": "dev/agent-policy.mts" }`. The path must be relative and, after
+resolving symlinks, stay inside the worktree. Without a declaration the policy checks are skipped.
+Policy tools also require a server launched inside a repository worktree on macOS or Linux (they
+refuse to run on Windows, where the server cannot reap a policy's descendants by process group),
+and refuse to run when `AGENT_BLACKBOARD_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN` is set to a value
+shorter than four characters, which could not be redacted from policy output. Each call runs one named
+export in a fresh child process (`bin/policy-runner.mjs`, started with the server's own Node), never
+inside the server, with the worktree as its working directory and an environment of only `HOME`,
+`PATH` (`/usr/bin`, `/bin`, `/usr/local/bin`, `/opt/homebrew/bin`, the Node directory, and the
+directory of the first `gh` on the server's `PATH`, deduplicated), and `GH_TOKEN` / `GITHUB_TOKEN` when the server has
+them. Blackboard credentials and `NODE_OPTIONS` are not passed. The child still runs as the
+server's user, so this is not a sandbox: on Linux it could read the server's environment from
+`/proc/<server pid>/environ`. Treat the policy module as trusted code. After the runner exits, its
+whole process group is killed, so nothing it started outlives the call. The runner reads
+`{ policyVersion: 1, export, input }` on stdin and writes `{ ok: true, result }` (or
+`{ ok: false, error }`) on stdout; a missing export is skipped.
+
+| Export                  | Input                                                                                                                                                                       | Result                                      | Timeout |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------- |
+| `validateRetrospective` | `sessionId`, `parentSessionId`, `mode`, `workOutcome`, `feedbackCoverage`, `repositories`, `markdown`, `sourceEventId`, `metadata` (`date`, `issues`, `prs`, `description`) | `{ errors: string[], warnings?: string[] }` | 30 s    |
+| `pullRequestDefaults`   | `{}`                                                                                                                                                                        | `{ repositories: string[] }`                | 120 s   |
+| `validatePullRequest`   | reserved for the pull request tools                                                                                                                                         | `{ errors: string[], warnings?: string[] }` | 120 s   |
+
+Any `errors` reject the save and write nothing. A non-zero exit, a timeout (reported as
+`policy <export> timed out after <N>s`), output over 1 MB, malformed JSON, or a result of the wrong
+shape is an error, never a pass.
+
 ## Worktree validation
 
 `worktree` is checked on every call. It must be an absolute path that, after resolving symlinks,
 equals the top level of a git worktree, that is, what `git rev-parse --show-toplevel` prints when
-run in it. Any git worktree on the machine is accepted, including one of a repository unrelated to
-the launch directory, so the tools can act on every checkout the user can reach. Worktrees created
-after launch are accepted and removed ones are refused. Rejected: a subdirectory of a worktree, a
+run in it. When the server was launched inside a repository, the real path must also equal one of
+the `worktree` entries of `git worktree list --porcelain` run in the launch root (the primary
+worktree or a linked one), so an unrelated repository is refused. A server launched outside any
+repository accepts the top level of any git worktree for the journal tools, but refuses the policy
+tools. Worktrees created after launch are accepted and removed ones are refused. Rejected: a subdirectory of a worktree, a
 relative or nonexistent path, and a directory that is not in a git worktree. Git runs without
 `GIT_*` variables, so `GIT_DIR` cannot redirect the check, and with `LC_ALL=C` and no `LANGUAGE`, so
 its "not a git repository" diagnostic is never translated.
 
 `worktree` only chooses where the outbox lives. It is not a trust boundary for loading code: the
-server never imports modules from it, and a tool that needs to must first get a repository allowlist
-from the machine registration.
+server never imports modules from it. The policy tools run the declared module only in a child
+process without blackboard credentials, as described above.
 
 When `worktree` is omitted, the launch directory's worktree top level is used if the launch
 directory is inside one, and it is validated like any explicit path. If the server was launched

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -377,7 +377,7 @@
   },
   "devDependencies": {
     "@ast-grep/cli": "0.45.3",
-    "@modelcontextprotocol/sdk": "1.31.0",
+    "@modelcontextprotocol/sdk": "1.32.0",
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
     "agent-blackboard": "^0.6.1",