vouchington-tooling 0.41.0 → 0.42.0

package/dist/mcp-server/policy-run.mjs

@@ -0,0 +1,116 @@
+import { fileURLToPath } from 'node:url';
+import { resolvePolicyModule } from "./policy-config.mjs";
+import { policyEnvironment, spawnPolicy, } from "./policy-spawn.mjs";
+/** How long each policy export may run before its process is killed, in milliseconds. */
+export const POLICY_TIMEOUTS_MS = {
+    validateRetrospective: 30_000,
+    validatePullRequest: 120_000,
+    pullRequestDefaults: 120_000,
+};
+const POLICY_MAX_OUTPUT_BYTES = 1_000_000;
+const STDERR_EXCERPT_BYTES = 2_000;
+const RUNNER = fileURLToPath(new URL('../../bin/policy-runner.mjs', import.meta.url));
+function failure(name, reason, outcome) {
+    const stderr = outcome?.stderr.trim().slice(-STDERR_EXCERPT_BYTES);
+    return new Error(`policy ${name} ${reason}${stderr ? `: ${stderr}` : ''}`);
+}
+function parseReply(name, outcome) {
+    let reply;
+    try {
+        reply = JSON.parse(outcome.stdout);
+    }
+    catch {
+        throw failure(name, 'produced output that is not valid JSON', outcome);
+    }
+    if (reply?.ok === false)
+        throw failure(name, `failed: ${String(reply.error)}`);
+    if (reply?.ok !== true)
+        throw failure(name, 'produced an unrecognized reply');
+    return reply.skipped === true ? { status: 'skipped' } : { status: 'ok', result: reply.result };
+}
+/**
+ * Runs one export of the worktree's declared policy module in a fresh child process (never in
+ * this one). Resolves `no-policy` when the worktree declares none and `skipped` when the module
+ * lacks the export. A timeout, crash, non-zero exit, oversized output, or unusable reply throws:
+ * a failed policy is never a pass.
+ */
+export async function runPolicyExport(run) {
+    const secrets = credentialValues(run.env);
+    // A policy can echo a credential it was given (GH_TOKEN) in a stack, stderr, or result; the
+    // caller of an MCP tool must never receive one. Diagnostics may carry it JSON-escaped too.
+    const escaped = secrets.map((secret) => JSON.stringify(secret).slice(1, -1));
+    const forms = [...new Set([...escaped, ...secrets])].sort((a, b) => b.length - a.length);
+    const spawn = run.spawn ?? spawnPolicy;
+    // stderr is scrubbed whole, before its excerpt could cut a credential into an unmatched suffix.
+    const scrubbing = async (request) => {
+        const outcome = await spawn(request);
+        return { ...outcome, stderr: scrubText(outcome.stderr, forms) };
+    };
+    try {
+        const result = await runUnscrubbed(run, scrubbing);
+        return result.status === 'ok'
+            ? { status: 'ok', result: scrubValue(result.result, secrets) }
+            : result;
+    }
+    catch (error) {
+        throw new Error(scrubText(error.message, forms), { cause: error });
+    }
+}
+const CREDENTIAL_NAMES = ['AGENT_BLACKBOARD_TOKEN', 'GH_TOKEN', 'GITHUB_TOKEN'];
+/**
+ * Credential values held by the server, longest first. A value too short to redact without
+ * mangling every output fails closed: the policy never runs rather than risk echoing it.
+ */
+function credentialValues(env) {
+    const values = CREDENTIAL_NAMES.map((name) => env[name]).filter((value) => Boolean(value));
+    if (values.some((value) => value.length < 4))
+        throw new Error(`a credential (${CREDENTIAL_NAMES.join(', ')}) is too short to redact: policy tools refuse to run`);
+    return [...new Set(values)].sort((a, b) => b.length - a.length);
+}
+function scrubText(text, secrets) {
+    return secrets.reduce((scrubbed, secret) => scrubbed.replaceAll(secret, '[REDACTED]'), text);
+}
+function scrubValue(value, secrets) {
+    if (secrets.length === 0 || value === undefined)
+        return value;
+    // Each secret is matched in its JSON-escaped form so the round trip stays valid JSON.
+    const escaped = secrets.map((secret) => JSON.stringify(secret).slice(1, -1));
+    return JSON.parse(scrubText(JSON.stringify(value), escaped));
+}
+async function runUnscrubbed(run, spawn) {
+    const { export: name } = run;
+    const module = await resolvePolicyModule(run.worktree);
+    if (module === undefined)
+        return { status: 'no-policy' };
+    const timeoutMs = POLICY_TIMEOUTS_MS[name];
+    const outcome = await spawn({
+        command: process.execPath,
+        args: [RUNNER, module],
+        cwd: run.worktree,
+        env: policyEnvironment(run.env),
+        input: JSON.stringify({ policyVersion: 1, export: name, input: run.input }),
+        timeoutMs,
+        maxOutputBytes: POLICY_MAX_OUTPUT_BYTES,
+    });
+    if (outcome.timedOut)
+        throw failure(name, `timed out after ${timeoutMs / 1000}s`);
+    if (outcome.overflowed)
+        throw failure(name, `wrote more than ${POLICY_MAX_OUTPUT_BYTES} bytes of output`);
+    if (outcome.exitCode !== 0)
+        throw failure(name, `exited with code ${outcome.exitCode}`, outcome);
+    return parseReply(name, outcome);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+/** Runs a validator export and checks its result is `{ errors: string[], warnings?: string[] }`. */
+export async function runValidator(run) {
+    const outcome = await runPolicyExport(run);
+    if (outcome.status !== 'ok')
+        return outcome;
+    const result = outcome.result;
+    if (!isStringArray(result?.errors) ||
+        (result.warnings !== undefined && !isStringArray(result.warnings)))
+        throw new Error(`policy ${run.export} must return { errors: string[], warnings?: string[] }`);
+    return { errors: result.errors, warnings: result.warnings ?? [] };
+}

package/dist/mcp-server/policy-spawn.d.mts

@@ -0,0 +1,24 @@
+export type PolicyRequest = {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    input: string;
+    timeoutMs: number;
+    maxOutputBytes: number;
+};
+export type PolicyOutcome = {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    /** True when stdout or stderr exceeded `maxOutputBytes` and the child was killed. */
+    overflowed: boolean;
+};
+export type PolicySpawner = (request: PolicyRequest) => Promise<PolicyOutcome>;
+/**
+ * The child's whole environment. Blackboard credentials and NODE_OPTIONS are never passed; GitHub
+ * tokens are passed only when the server has them, for the checks that call `gh`.
+ */
+export declare function policyEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare const spawnPolicy: PolicySpawner;

package/dist/mcp-server/policy-spawn.mjs

@@ -0,0 +1,97 @@
+import { spawn } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
+function isExecutable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The directory of the first `gh` on the server's PATH, so policy checks can call it. */
+function ghDirectory(env) {
+    const found = (env.PATH ?? '')
+        .split(delimiter)
+        .filter((directory) => directory !== '')
+        .find((directory) => isExecutable(join(directory, 'gh')));
+    return found === undefined ? [] : [found];
+}
+/** The fixed system directories, node's own, and the directory holding `gh`, deduplicated. */
+function policyPath(env) {
+    const directories = [
+        '/usr/bin',
+        '/bin',
+        '/usr/local/bin',
+        '/opt/homebrew/bin',
+        dirname(process.execPath),
+        ...ghDirectory(env),
+    ];
+    return [...new Set(directories)].join(delimiter);
+}
+/**
+ * The child's whole environment. Blackboard credentials and NODE_OPTIONS are never passed; GitHub
+ * tokens are passed only when the server has them, for the checks that call `gh`.
+ */
+export function policyEnvironment(env) {
+    const child = { PATH: policyPath(env) };
+    for (const name of ['HOME', 'GH_TOKEN', 'GITHUB_TOKEN']) {
+        const value = env[name];
+        if (value !== undefined)
+            child[name] = value;
+    }
+    return child;
+}
+export const spawnPolicy = (request) => new Promise((resolve, reject) => {
+    const child = spawn(request.command, request.args, {
+        cwd: request.cwd,
+        env: request.env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        // Its own process group, so every grandchild the policy started can be killed with it.
+        detached: process.platform !== 'win32',
+    });
+    const killGroup = () => {
+        try {
+            process.kill(-child.pid, 'SIGKILL');
+        }
+        catch {
+            child.kill('SIGKILL');
+        }
+    };
+    const chunks = { stdout: [], stderr: [] };
+    const sizes = { stdout: 0, stderr: 0 };
+    let timedOut = false;
+    let overflowed = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        killGroup();
+    }, request.timeoutMs);
+    for (const name of ['stdout', 'stderr'])
+        child[name].on('data', (chunk) => {
+            sizes[name] += chunk.length;
+            if (sizes[name] > request.maxOutputBytes) {
+                overflowed = true;
+                killGroup();
+            }
+            else
+                chunks[name].push(chunk);
+        });
+    child.on('error', (error) => {
+        clearTimeout(timer);
+        reject(error);
+    });
+    // Reap anything the policy left running in its group as soon as the runner exits: a descendant
+    // would otherwise keep the GitHub token it inherited, and one holding an inherited pipe would
+    // delay `close` until the timeout.
+    child.on('exit', () => {
+        clearTimeout(timer);
+        killGroup();
+    });
+    child.on('close', (exitCode) => {
+        const text = (name) => Buffer.concat(chunks[name]).toString('utf8');
+        resolve({ exitCode, stdout: text('stdout'), stderr: text('stderr'), timedOut, overflowed });
+    });
+    child.stdin.on('error', () => { });
+    child.stdin.end(request.input);
+});

package/dist/mcp-server/retrospective-facts-input.d.mts

@@ -0,0 +1,6 @@
+import type { Args } from './args.mts';
+/**
+ * Checks `compose.facts`: either `{ status, reason }` (unassessed) or a live collection selector,
+ * never both. Returns whether live collection was requested.
+ */
+export declare function checkFactsInput(facts: Args): boolean;

package/dist/mcp-server/retrospective-facts-input.mjs

@@ -0,0 +1,25 @@
+/** A plain branch name: no scheme or colon, no leading dash, no `..`. */
+const BRANCH = /^(?!-)(?!.*\.\.)[A-Za-z0-9._/-]+$/;
+/**
+ * Checks `compose.facts`: either `{ status, reason }` (unassessed) or a live collection selector,
+ * never both. Returns whether live collection was requested.
+ */
+export function checkFactsInput(facts) {
+    const selectors = ['pr', 'branch', 'noPr'].filter((key) => key in facts);
+    if ('status' in facts) {
+        if (selectors.length)
+            throw new Error(`compose.facts: status is exclusive with ${selectors.join(', ')}`);
+        return false;
+    }
+    if ('reason' in facts)
+        throw new Error('compose.facts.reason requires a status');
+    // The collector trusts these types; a string "false" must not read as noPr: true.
+    // gh accepts a pull request URL for either, which would reach another repository.
+    if ('pr' in facts && (typeof facts.pr !== 'string' || !/^\d+$/.test(facts.pr)))
+        throw new Error('compose.facts.pr must be a pull request number string');
+    if ('branch' in facts && (typeof facts.branch !== 'string' || !BRANCH.test(facts.branch)))
+        throw new Error('compose.facts.branch must be a branch name');
+    if ('noPr' in facts && typeof facts.noPr !== 'boolean')
+        throw new Error('compose.facts.noPr must be a boolean');
+    return true;
+}

package/dist/mcp-server/retrospective-front-matter.d.mts

@@ -0,0 +1,22 @@
+import type { FeedbackReference } from '../agent-blackboard/index.mts';
+/** The fields of the front matter `composeRetrospective` writes, with camelCase names. */
+export type RetrospectiveFrontMatter = {
+    date: string;
+    issues: FeedbackReference[];
+    prs: FeedbackReference[];
+    sessionId?: string;
+    description?: string;
+    workOutcome?: string;
+    feedbackCoverage?: {
+        status: string;
+        sources: string[];
+        droppedCount: number;
+    };
+    repositories?: string[];
+};
+/**
+ * Parses the block from the leading `---` line to the next `---` line. Every line is
+ * `key: <JSON value>`; unknown keys, duplicates, malformed lines and ill-typed values are errors,
+ * and `date`, `issues`, and `prs` are required.
+ */
+export declare function parseRetrospectiveFrontMatter(markdown: string): RetrospectiveFrontMatter;

package/dist/mcp-server/retrospective-front-matter.mjs

@@ -0,0 +1,88 @@
+const KEYS = [
+    'date',
+    'issues',
+    'prs',
+    'session_id',
+    'description',
+    'work_outcome',
+    'feedback_coverage',
+    'repositories',
+];
+const isString = (value) => typeof value === 'string';
+const isStrings = (value) => Array.isArray(value) && value.every(isString);
+const isReference = (value) => (isString(value) && value.trim() !== '') || (Number.isSafeInteger(value) && value > 0);
+function fail(message) {
+    throw new Error(`retrospective front matter: ${message}`);
+}
+function parseLines(block) {
+    const values = new Map();
+    // composeRetrospective joins its sections with blank lines, so blank lines are allowed.
+    for (const line of block.split('\n').filter((candidate) => candidate !== '')) {
+        const separator = line.indexOf(': ');
+        const key = separator < 0 ? '' : line.slice(0, separator);
+        if (!KEYS.includes(key))
+            fail(separator < 0 || !/^[a-z_]+$/.test(key)
+                ? `malformed line ${JSON.stringify(line)}; each line is "key: <JSON value>"`
+                : `unknown key ${key}`);
+        if (values.has(key))
+            fail(`duplicate key ${key}`);
+        try {
+            values.set(key, JSON.parse(line.slice(separator + 2)));
+        }
+        catch {
+            fail(`${key} is not a JSON value`);
+        }
+    }
+    return values;
+}
+function coverageOf(coverage) {
+    if (typeof coverage !== 'object' ||
+        coverage === null ||
+        Object.keys(coverage).some((key) => !['status', 'sources', 'droppedCount'].includes(key)) ||
+        !isString(coverage.status) ||
+        !isStrings(coverage.sources) ||
+        !Number.isSafeInteger(coverage.droppedCount))
+        fail('feedback_coverage must be { status, sources, droppedCount }');
+    return coverage;
+}
+/**
+ * Parses the block from the leading `---` line to the next `---` line. Every line is
+ * `key: <JSON value>`; unknown keys, duplicates, malformed lines and ill-typed values are errors,
+ * and `date`, `issues`, and `prs` are required.
+ */
+export function parseRetrospectiveFrontMatter(markdown) {
+    const block = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(markdown.replaceAll('\r\n', '\n'))?.[1];
+    if (block === undefined)
+        fail('the document must start with a block between two "---" lines, as composeRetrospective writes');
+    const values = parseLines(block);
+    const { date, issues, prs } = Object.fromEntries(values);
+    if (!isString(date) || !/^\d{4}-\d{2}-\d{2}$/.test(date))
+        fail('date must be a YYYY-MM-DD string');
+    for (const [name, list] of [
+        ['issues', issues],
+        ['prs', prs],
+    ])
+        if (!Array.isArray(list) || !list.every(isReference))
+            fail(`${name} must be an array of positive integers or non-empty strings`);
+    const text = (key) => {
+        const value = values.get(key);
+        if (value !== undefined && !isString(value))
+            fail(`${key} must be a string`);
+        return value;
+    };
+    const repositories = values.get('repositories');
+    if (repositories !== undefined && !isStrings(repositories))
+        fail('repositories must be an array of strings');
+    const coverage = values.get('feedback_coverage');
+    const parsed = {
+        date,
+        issues: issues,
+        prs: prs,
+        sessionId: text('session_id'),
+        description: text('description'),
+        workOutcome: text('work_outcome'),
+        feedbackCoverage: coverage === undefined ? undefined : coverageOf(coverage),
+        repositories: repositories,
+    };
+    return Object.fromEntries(Object.entries(parsed).filter(([, value]) => value !== undefined));
+}

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

@@ -0,0 +1,29 @@
+import { type FeedbackCoverage, type WorkOutcome } from '../agent-blackboard/index.mts';
+import type { BlackboardClientDependencies } from '../agent-blackboard/client.mts';
+import { type Args } from './args.mts';
+/** The longest a facts subprocess may run before it is killed. */
+export declare const FACTS_TIMEOUT_MS = 120000;
+type ComposeBase = {
+    sessionId: string;
+    repositories: string[];
+    workOutcome: WorkOutcome;
+    feedbackCoverage: FeedbackCoverage;
+    worktree: string;
+    env: NodeJS.ProcessEnv;
+    dependencies: BlackboardClientDependencies;
+};
+/**
+ * Facts commands run in the worktree and never see the blackboard credentials, NODE_OPTIONS, or
+ * GIT_* overrides that could point git away from the validated worktree.
+ */
+export declare function worktreeExecutor(worktree: string, env: NodeJS.ProcessEnv, timeoutMs?: number): (command: string, args: string[]) => Promise<{
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+}>;
+/** The caller's `compose.knownSensitiveValues` plus the server's blackboard token, when set. */
+export declare function sensitiveValues(compose: Args | undefined, env: NodeJS.ProcessEnv): string[];
+/** Builds the retrospective markdown with `composeRetrospective`, rejecting unknown input keys. */
+export declare function composeFromArgs(compose: Args, base: ComposeBase): Promise<string>;
+export {};

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

@@ -0,0 +1,145 @@
+import { composeRetrospective, } from "../agent-blackboard/index.mjs";
+import { rejectUnknown } from "./args.mjs";
+import { inspectHarnessEnvironment, selectHarnessSession, } from "../agent-harness-identity/index.mjs";
+import { SESSION_ID } from "../retrospective-transcript/resolve-transcript-file.mjs";
+import { serverJournalLoader } from "./journal-read.mjs";
+import { checkFactsInput } from "./retrospective-facts-input.mjs";
+import { spawnPolicy } from "./policy-spawn.mjs";
+const HARNESSES = ['codex', 'claude', 'cursor', 'grok'];
+const COMPOSE_KEYS = [
+    'narrative',
+    'date',
+    'issues',
+    'prs',
+    'description',
+    'facts',
+    'transcript',
+    'tools',
+    'architecture',
+    'knownSensitiveValues',
+];
+const COMPOSE_REQUIRED = COMPOSE_KEYS.filter((key) => key !== 'knownSensitiveValues');
+/** No `repo`: a caller must not aim the server's GitHub token at another repository. */
+const FACTS_KEYS = ['pr', 'branch', 'noPr', 'status', 'reason'];
+/** No path overrides: the server reads the session's transcript from its own default roots. */
+const TRANSCRIPT_KEYS = ['sessionId', 'harnessSessionId', 'status', 'reason'];
+/** The longest a facts subprocess may run before it is killed. */
+export const FACTS_TIMEOUT_MS = 120_000;
+const MAX_OUTPUT_BYTES = 10_000_000;
+function section(compose, name, keys) {
+    const value = compose[name];
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error(`compose.${name} must be an object`);
+    rejectUnknown(value, keys);
+    return value;
+}
+/**
+ * Facts commands run in the worktree and never see the blackboard credentials, NODE_OPTIONS, or
+ * GIT_* overrides that could point git away from the validated worktree.
+ */
+export function worktreeExecutor(worktree, env, timeoutMs = FACTS_TIMEOUT_MS) {
+    const safe = Object.fromEntries(Object.entries(env).filter(([name]) => !name.startsWith('AGENT_BLACKBOARD_') &&
+        !name.startsWith('GIT_') &&
+        name !== 'NODE_OPTIONS'));
+    // Each command runs in its own process group, killed whole when it exits or times out, so a
+    // helper that git or gh starts cannot outlive the call with an inherited GH_TOKEN.
+    return async (command, args) => {
+        let outcome;
+        try {
+            outcome = await spawnPolicy({
+                command,
+                args,
+                cwd: worktree,
+                env: safe,
+                input: '',
+                timeoutMs,
+                maxOutputBytes: MAX_OUTPUT_BYTES,
+            });
+        }
+        catch (error) {
+            return { ok: false, stdout: '', stderr: error.message, exitCode: null };
+        }
+        const { stdout, stderr, exitCode, timedOut, overflowed } = outcome;
+        if (timedOut || overflowed) {
+            const reason = timedOut
+                ? `timed out after ${timeoutMs} ms`
+                : `wrote more than ${MAX_OUTPUT_BYTES} bytes`;
+            return { ok: false, stdout, stderr: `${stderr}${command} ${reason}`, exitCode: null };
+        }
+        return { ok: exitCode === 0, stdout, stderr, exitCode };
+    };
+}
+/** The caller's `compose.knownSensitiveValues` plus the server's blackboard token, when set. */
+export function sensitiveValues(compose, env) {
+    const given = compose?.knownSensitiveValues;
+    if (given !== undefined && (!Array.isArray(given) || given.some((v) => typeof v !== 'string')))
+        throw new Error('compose.knownSensitiveValues must be an array of strings');
+    // Redaction ignores values under four characters, so promising to redact one would be false.
+    if (given?.some((value) => value.length < 4))
+        throw new Error('compose.knownSensitiveValues entries must be at least 4 characters');
+    // Facts commands inherit the GitHub tokens, so their output is redacted of those values too.
+    const credentials = [env.AGENT_BLACKBOARD_TOKEN, env.GH_TOKEN, env.GITHUB_TOKEN].filter((value) => Boolean(value));
+    const values = [...(given ?? []), ...credentials];
+    // The composer JSON-escapes structured fields, so each value is also redacted in that form.
+    const escaped = values.map((value) => JSON.stringify(value).slice(1, -1));
+    // Longest first, so a shorter value that is a prefix of a credential cannot break its match.
+    return [...new Set([...values, ...escaped])].sort((a, b) => b.length - a.length);
+}
+/**
+ * The transcript collector input: the server's worktree and default session roots only. A caller
+ * may name the session (it must be this one), give the harness's own UUID session id when the
+ * blackboard session id is not one, or report the transcript as unassessed.
+ */
+function transcriptInput(transcript, base) {
+    if ('status' in transcript) {
+        if ('sessionId' in transcript || 'harnessSessionId' in transcript)
+            throw new Error('compose.transcript: sessionId and harnessSessionId are exclusive with status');
+        return transcript;
+    }
+    // A reason without a status is malformed, not a request to read the transcript.
+    if ('reason' in transcript)
+        throw new Error('compose.transcript.reason requires a status');
+    if (transcript.sessionId !== undefined && transcript.sessionId !== base.sessionId)
+        throw new Error('compose.transcript.sessionId must equal the sessionId of the call');
+    const harnessId = transcript.harnessSessionId ?? base.sessionId;
+    // Transcripts are found by the harness's UUID; never let a lookup fail into "unavailable".
+    if (typeof harnessId !== 'string' || !SESSION_ID.test(harnessId))
+        throw new Error('compose.transcript needs a UUID session id: pass harnessSessionId (the harness session ' +
+            'UUID) or { status, reason }');
+    // When the harness that launched the server names its session, no other transcript is read.
+    const own = selectHarnessSession(inspectHarnessEnvironment(base.env), HARNESSES)?.sessionId;
+    if (own !== undefined && own.toLowerCase() !== harnessId.toLowerCase())
+        // A server can outlive its session (Claude Code /clear, a Codex thread switch).
+        throw new Error('compose.transcript may read only the harness session that launched the server: if the ' +
+            'session changed since (/clear, a thread switch), reconnect the server (/mcp in Claude ' +
+            'Code, or restart Codex), or pass { status, reason }');
+    return { sessionId: harnessId, cwd: base.worktree };
+}
+function factsInput(facts, base) {
+    return checkFactsInput(facts)
+        ? { ...facts, execute: worktreeExecutor(base.worktree, base.env) }
+        : facts;
+}
+/** Builds the retrospective markdown with `composeRetrospective`, rejecting unknown input keys. */
+export async function composeFromArgs(compose, base) {
+    rejectUnknown(compose, COMPOSE_KEYS);
+    const missing = COMPOSE_REQUIRED.filter((key) => compose[key] === undefined);
+    if (missing.length)
+        throw new Error(`compose is missing: ${missing.join(', ')}`);
+    if (typeof compose.narrative !== 'string' || !compose.narrative.trim())
+        throw new Error('compose.narrative must be a non-empty string');
+    const facts = section(compose, 'facts', FACTS_KEYS);
+    const transcript = section(compose, 'transcript', TRANSCRIPT_KEYS);
+    const input = {
+        ...compose,
+        sessionId: base.sessionId,
+        repositories: base.repositories,
+        workOutcome: base.workOutcome,
+        feedbackCoverage: base.feedbackCoverage,
+        facts: factsInput(facts, base),
+        transcript: transcriptInput(transcript, base),
+        knownSensitiveValues: sensitiveValues(compose, base.env),
+        journal: { journalLoader: serverJournalLoader(base.env, base.dependencies) },
+    };
+    return composeRetrospective(input);
+}

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[];