vouchington-tooling 0.42.0 → 0.44.0

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

@@ -0,0 +1,49 @@
+import { findShepherdJournal } from "./pr-journal.mjs";
+const FIELDS = ['body', 'headRefName', 'baseRefName', 'state'];
+/** The live pull request as gh reports it, rejected unless it is open. */
+export async function livePullRequest(gh, pr) {
+    const output = await gh(['pr', 'view', String(pr), '--json', FIELDS.join(',')]);
+    const live = JSON.parse(output);
+    if (!isLive(live))
+        throw new Error(`gh pr view ${pr} did not return ${FIELDS.join(', ')}`);
+    // A closed or merged PR can share a reused branch name; its history must not be rewritten.
+    if (live.state !== 'OPEN')
+        throw new Error(`pull request ${pr} is ${live.state}, not OPEN`);
+    return live;
+}
+function isLive(value) {
+    return FIELDS.every((field) => typeof value?.[field] === 'string');
+}
+/**
+ * The base to validate an existing pull request against: its live base. An explicit `base` that
+ * differs is rejected, because `gh pr edit` here changes only the title and body.
+ */
+export function liveBase(pr, live, given) {
+    if (given !== undefined && given !== live.baseRefName)
+        throw new Error(`pull request ${pr} targets ${live.baseRefName}, not ${given}`);
+    return live.baseRefName;
+}
+/**
+ * Re-reads the live pull request just before the edit and aborts if its Shepherd Journal or base
+ * changed since the body was prepared and validated, so an entry appended in between is never
+ * overwritten and a retargeted PR never gets a body validated against its old base.
+ */
+export async function assertJournalUnchanged(gh, pr, preparedFrom, base) {
+    const now = await livePullRequest(gh, pr);
+    if (now.baseRefName !== base)
+        throw new Error(`pull request ${pr} was retargeted to ${now.baseRefName}; run pr_update again`);
+    if (findShepherdJournal(now.body) !== findShepherdJournal(preparedFrom))
+        throw new Error(`the Shepherd Journal of pull request ${pr} changed meanwhile; run pr_update again`);
+}
+/** The server's credential values that must never reach the policy or GitHub, longest first. */
+export function credentials(env) {
+    const values = [env.AGENT_BLACKBOARD_TOKEN, env.GH_TOKEN, env.GITHUB_TOKEN].filter((value) => value !== undefined && value.length >= 4);
+    return [...new Set(values)].sort((a, b) => b.length - a.length);
+}
+/** Replaces every server credential in every string of a JSON-shaped value. */
+export function redactCredentials(value, secrets) {
+    if (value === undefined || secrets.length === 0)
+        return value;
+    const json = secrets.reduce((text, secret) => text.split(JSON.stringify(secret).slice(1, -1)).join('[REDACTED]'), JSON.stringify(value));
+    return JSON.parse(json);
+}

package/dist/mcp-server/pr-tools.test-helpers.d.mts

@@ -0,0 +1,54 @@
+import type { RepoFixture } from './git-fixture.test-helpers.mts';
+import type { GhRunner } from './pr-gh.mts';
+import type { PolicyOutcome, PolicyRequest } from './policy-spawn.mts';
+export declare const PR_ARGS: {
+    sessionId: string;
+    title: string;
+    summary: string;
+    impact: string;
+    relatedIssues: {
+        number: number;
+        relation: string;
+        reason: string;
+    }[];
+    details: string[];
+    base: string;
+    agent: string;
+    mode: string;
+    workspaceSetup: string;
+};
+export declare function declarePolicy(fixture: RepoFixture): void;
+type Reply = (name: string, input: Record<string, unknown>) => unknown;
+export declare function policy(reply: Reply): {
+    requests: {
+        name: string;
+        input: Record<string, unknown>;
+    }[];
+    spawnPolicy: (request: PolicyRequest) => Promise<PolicyOutcome>;
+};
+type GhCall = {
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    body?: string;
+};
+/** A fake gh: records calls (reading any --body-file while it still exists) and replies by verb. */
+export declare function fakeGh(replies?: {
+    view?: unknown;
+    create?: string;
+    edit?: string;
+}): {
+    calls: GhCall[];
+    bodyFiles: {
+        path: string;
+        mode: number;
+    }[];
+    runGh: GhRunner;
+};
+export declare const device: () => {
+    user: string;
+    host: string;
+};
+/** Gives the fixture an `origin` that already has the linked branch at its current commit. */
+export declare function usePushedRemote(fixture: () => RepoFixture): void;
+export {};

package/dist/mcp-server/pr-tools.test-helpers.mjs

@@ -0,0 +1,67 @@
+import { readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { beforeEach } from 'vitest';
+export const PR_ARGS = {
+    sessionId: 'native:owner',
+    title: 'Add the thing',
+    summary: 'Adds the thing.',
+    impact: 'Nobody breaks.',
+    relatedIssues: [{ number: 7, relation: 'closes', reason: 'tracks the work' }],
+    details: ['First paragraph.', '- a bullet'],
+    base: 'trunk',
+    agent: 'codex',
+    mode: 'autonomous',
+    workspaceSetup: 'fresh worktree',
+};
+export function declarePolicy(fixture) {
+    writeFileSync(join(fixture.linked, 'package.json'), JSON.stringify({ 'vouchington-tooling': { policy: 'policy.mts' } }));
+    writeFileSync(join(fixture.linked, 'policy.mts'), '');
+}
+export function policy(reply) {
+    const requests = [];
+    const spawnPolicy = async (request) => {
+        const { export: name, input } = JSON.parse(request.input);
+        requests.push({ name, input });
+        const result = reply(name, input);
+        const stdout = result === undefined ? { ok: true, skipped: true } : { ok: true, result };
+        return {
+            exitCode: 0,
+            stdout: JSON.stringify(stdout),
+            stderr: '',
+            timedOut: false,
+            overflowed: false,
+        };
+    };
+    return { requests, spawnPolicy };
+}
+/** A fake gh: records calls (reading any --body-file while it still exists) and replies by verb. */
+export function fakeGh(replies = {}) {
+    const calls = [];
+    const bodyFiles = [];
+    const runGh = async (args, options) => {
+        const call = { args, ...options };
+        const file = args[args.indexOf('--body-file') + 1];
+        if (args.includes('--body-file') && file !== undefined) {
+            call.body = readFileSync(file, 'utf8');
+            bodyFiles.push({ path: file, mode: statSync(file).mode & 0o777 });
+        }
+        calls.push(call);
+        if (args[1] === 'view')
+            return JSON.stringify(replies.view);
+        if (args[1] === 'create')
+            return replies.create ?? 'https://github.com/o/r/pull/12\n';
+        return replies.edit ?? 'https://github.com/o/r/pull/5\n';
+    };
+    return { calls, bodyFiles, runGh };
+}
+export const device = () => ({ user: 'Jong', host: 'Laptop.Local' });
+/** Gives the fixture an `origin` that already has the linked branch at its current commit. */
+export function usePushedRemote(fixture) {
+    beforeEach(() => {
+        const f = fixture();
+        const origin = join(f.root, 'origin.git');
+        f.git(f.root, 'init', '--quiet', '--bare', origin);
+        f.git(f.linked, 'remote', 'add', 'origin', origin);
+        f.git(f.linked, 'push', '--quiet', 'origin', 'linked');
+    });
+}

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

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

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

@@ -0,0 +1,69 @@
+import { ADDITIVE, MUTATING, READ_ONLY, tool, } from "./tools-schema.mjs";
+/** These tools read or write GitHub, outside the server's own state. */
+const openWorld = (annotations) => ({
+    ...annotations,
+    openWorldHint: true,
+});
+const text = (description) => ({ type: 'string', minLength: 1, description });
+const PR_NUMBER = { type: 'integer', minimum: 1, description: 'Pull request number.' };
+const FIELDS = {
+    title: { type: 'string', minLength: 1, maxLength: 256, description: 'Single-line PR title.' },
+    summary: text('What the change does, as markdown.'),
+    impact: text('Who or what is affected, as markdown.'),
+    relatedIssues: {
+        type: 'array',
+        description: 'Issues this pull request closes or refs; may be empty.',
+        items: {
+            type: 'object',
+            properties: {
+                number: { type: 'integer', minimum: 1 },
+                relation: { enum: ['closes', 'refs'] },
+                reason: text('Why the issue is related.'),
+            },
+            required: ['number', 'relation', 'reason'],
+            additionalProperties: false,
+        },
+    },
+    details: {
+        type: 'array',
+        minItems: 1,
+        items: { type: 'string', minLength: 1 },
+        description: 'Markdown paragraphs or bullets, joined by blank lines.',
+    },
+    base: { type: 'string', minLength: 1, description: 'Base branch. Default: main.' },
+    agent: text('Agent name for the Agent line.'),
+    model: text('Optional model name, rendered in parentheses after the agent.'),
+    mode: { enum: ['interactive', 'autonomous'], description: 'Delivery mode, given to the policy.' },
+    workspaceSetup: text('Text for the Workspace setup line, such as how the worktree was prepared.'),
+};
+const REQUIRED = [
+    'title',
+    'summary',
+    'impact',
+    'relatedIssues',
+    'details',
+    'agent',
+    'mode',
+    'workspaceSetup',
+];
+const RENDERING = 'The server renders the body from the structured input (Summary, Impact, Related issues, ' +
+    'Details, then Workspace setup, Agent, Device and Worktree lines) and runs the checkout ' +
+    'policy validatePullRequest export in a child process; the head branch is the ' +
+    "worktree's current branch. Policy tools need a server launched inside a repository worktree. ";
+export const PR_TOOLS = [
+    tool('pr_validate', 'Renders the pull request body and validates it with the checkout policy; writes nothing. ' +
+        RENDERING +
+        'Pass pr to validate an update of that pull request: the live body is read and its Shepherd ' +
+        'Journal preserved. Returns { body, errors, warnings }.', openWorld(READ_ONLY), { ...FIELDS, pr: PR_NUMBER }, REQUIRED),
+    tool('pr_create', 'Creates a draft pull request from the worktree branch. ' +
+        RENDERING +
+        'Validation errors block creation. The policy pullRequestDefaults export may add labels, a ' +
+        'milestone and a project. The branch must already be pushed and current. It sees no stack ' +
+        'membership, so a policy may reject a non-default base; create stacked layers with the ' +
+        "repository's stack tooling. Returns { number, url, warnings }.", openWorld(ADDITIVE), FIELDS, REQUIRED),
+    tool('pr_update', "Replaces an open pull request's title and body. " +
+        RENDERING +
+        "The pull request's head branch must be the worktree branch. The live Shepherd Journal is " +
+        'preserved and nothing else is carried over from the live body. Validation errors block ' +
+        'the update. Returns { number, url, warnings }.', openWorld(MUTATING), { ...FIELDS, pr: PR_NUMBER }, [...REQUIRED, 'pr']),
+];

package/dist/mcp-server/tools.mjs

@@ -1,4 +1,5 @@
 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 { PR_TOOLS } from "./tools-pr.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. ' +
@@ -46,6 +47,7 @@ export const TOOLS = [
     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,
+    ...PR_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/pull-request-diff/diff-size.d.mts

@@ -0,0 +1,29 @@
+export type DiffLineChanges = {
+    added: number;
+    deleted: number;
+};
+export type LargeDiffThresholds = {
+    /** A diff adding strictly more lines than this is large. */
+    addedLines: number;
+    /** A diff deleting strictly more lines than this is large. */
+    deletedLines: number;
+};
+/**
+ * Example thresholds for a "decide whether to split this PR" gate: additions are the trigger for a
+ * split, while deletion-heavy retirement work stays coherent at a larger limit. Callers pass their
+ * own `LargeDiffThresholds`; these are only a default.
+ */
+export declare const DEFAULT_LARGE_DIFF_THRESHOLDS: Readonly<LargeDiffThresholds>;
+/**
+ * Added + removed lines in a unified diff (`git diff <base>...HEAD` output), excluding the
+ * `+++`/`---` file-header lines so renamed/moved files don't double-count their path lines.
+ *
+ * Known limitation: this matches the literal `+++`/`---` prefix, not "is this actually a file
+ * header." An added line whose content starts with `++`, or a removed line whose content starts
+ * with `--` (a SQL comment, a CLI flag), renders as `+++`/`---` once the diff marker is prepended
+ * and is silently excluded from the count. For a coarse "probably needs a split" heuristic with an
+ * explicit override, that undercount is acceptable; this is not a full hunk parser.
+ */
+export declare function countDiffLineChanges(diffText: string): DiffLineChanges;
+/** True when either count is strictly greater than its threshold. */
+export declare function exceedsLargeDiffThreshold(changes: DiffLineChanges, thresholds?: LargeDiffThresholds): boolean;

package/dist/pull-request-diff/diff-size.mjs

@@ -0,0 +1,35 @@
+/**
+ * Example thresholds for a "decide whether to split this PR" gate: additions are the trigger for a
+ * split, while deletion-heavy retirement work stays coherent at a larger limit. Callers pass their
+ * own `LargeDiffThresholds`; these are only a default.
+ */
+export const DEFAULT_LARGE_DIFF_THRESHOLDS = Object.freeze({
+    addedLines: 5000,
+    deletedLines: 20_000,
+});
+/**
+ * Added + removed lines in a unified diff (`git diff <base>...HEAD` output), excluding the
+ * `+++`/`---` file-header lines so renamed/moved files don't double-count their path lines.
+ *
+ * Known limitation: this matches the literal `+++`/`---` prefix, not "is this actually a file
+ * header." An added line whose content starts with `++`, or a removed line whose content starts
+ * with `--` (a SQL comment, a CLI flag), renders as `+++`/`---` once the diff marker is prepended
+ * and is silently excluded from the count. For a coarse "probably needs a split" heuristic with an
+ * explicit override, that undercount is acceptable; this is not a full hunk parser.
+ */
+export function countDiffLineChanges(diffText) {
+    const changes = { added: 0, deleted: 0 };
+    for (const line of diffText.split('\n')) {
+        if (line.startsWith('+++') || line.startsWith('---'))
+            continue;
+        if (line.startsWith('+'))
+            changes.added++;
+        else if (line.startsWith('-'))
+            changes.deleted++;
+    }
+    return changes;
+}
+/** True when either count is strictly greater than its threshold. */
+export function exceedsLargeDiffThreshold(changes, thresholds = DEFAULT_LARGE_DIFF_THRESHOLDS) {
+    return changes.added > thresholds.addedLines || changes.deleted > thresholds.deletedLines;
+}

package/dist/pull-request-diff/index.d.mts

@@ -0,0 +1,2 @@
+export { countDiffLineChanges, DEFAULT_LARGE_DIFF_THRESHOLDS, exceedsLargeDiffThreshold, } from './diff-size.mts';
+export type { DiffLineChanges, LargeDiffThresholds } from './diff-size.mts';

package/dist/pull-request-diff/index.mjs

@@ -0,0 +1 @@
+export { countDiffLineChanges, DEFAULT_LARGE_DIFF_THRESHOLDS, exceedsLargeDiffThreshold, } from "./diff-size.mjs";

package/dist/retrospective-distill/args.d.mts

@@ -0,0 +1,13 @@
+export type DistillClassifyArgs = {
+    partitionPath: string;
+    retroCutoff: string;
+    sessionCutoff: string;
+};
+/**
+ * Parses `<partition.jsonl> --retro-cutoff <iso> --session-cutoff <iso>`.
+ *
+ * The classifier never computes its own cutoffs: the eligibility rule is evaluated against
+ * whatever `retroCutoff`/`sessionCutoff` the caller passes in, so a classifier run always matches
+ * the caller's own idea of "eligible" for that same run.
+ */
+export declare function parseDistillClassifyArgs(argv: string[]): DistillClassifyArgs;

package/dist/retrospective-distill/args.mjs

@@ -0,0 +1,27 @@
+import { parseStringFlags } from "./flag-args.mjs";
+function requireIsoCutoff(value, flag) {
+    if (value === undefined)
+        throw new Error(`${flag} is required`);
+    if (Number.isNaN(Date.parse(value)))
+        throw new Error(`${flag} must be a valid ISO 8601 timestamp`);
+    return value;
+}
+/**
+ * Parses `<partition.jsonl> --retro-cutoff <iso> --session-cutoff <iso>`.
+ *
+ * The classifier never computes its own cutoffs: the eligibility rule is evaluated against
+ * whatever `retroCutoff`/`sessionCutoff` the caller passes in, so a classifier run always matches
+ * the caller's own idea of "eligible" for that same run.
+ */
+export function parseDistillClassifyArgs(argv) {
+    const { values, positional } = parseStringFlags(argv, ['--retro-cutoff', '--session-cutoff']);
+    const [partitionPath, ...extra] = positional;
+    if (partitionPath === undefined || extra.length > 0) {
+        throw new Error('expected exactly one positional argument: the partition JSONL path');
+    }
+    return {
+        partitionPath,
+        retroCutoff: requireIsoCutoff(values.get('--retro-cutoff'), '--retro-cutoff'),
+        sessionCutoff: requireIsoCutoff(values.get('--session-cutoff'), '--session-cutoff'),
+    };
+}

package/dist/retrospective-distill/checkpoint-entry.d.mts

@@ -0,0 +1,2 @@
+import type { SessionEntry } from './session-types.mts';
+export declare function isCheckpointEntry(entry: SessionEntry): boolean;

package/dist/retrospective-distill/checkpoint-entry.mjs

@@ -0,0 +1,11 @@
+// Historic hook-written journal entries stay in the journal until they are archived, even though
+// no hook appends them anymore: agents write their own journal entries. They kept
+// `type: "journal"` and carry this structural `checkpoint` field, which is the only marker that
+// tells one apart from an agent-written entry — the rendered markdown heading is never inspected.
+// Session-shape classification (shape.mts) reads it so those sessions stay `checkpoint-only`.
+const CHECKPOINT_KINDS = ['compaction', 'command-failure', 'pr-create', 'push'];
+const CHECKPOINT_ENTRY_FIELD = 'checkpoint';
+export function isCheckpointEntry(entry) {
+    const value = entry.data[CHECKPOINT_ENTRY_FIELD];
+    return typeof value === 'string' && CHECKPOINT_KINDS.includes(value);
+}

package/dist/retrospective-distill/fixtures.test-helpers.d.mts

@@ -0,0 +1,3 @@
+import type { Session, SessionEntry } from './session-types.mts';
+export declare function sessionFixture(overrides?: Partial<Session>): Session;
+export declare function entryFixture(overrides?: Partial<SessionEntry>): SessionEntry;

package/dist/retrospective-distill/fixtures.test-helpers.mjs

@@ -0,0 +1,21 @@
+export function sessionFixture(overrides = {}) {
+    return {
+        id: 'session-1',
+        parentSessionId: null,
+        agent: 'claude',
+        version: '1',
+        createdAt: '2026-07-01T00:00:00.000Z',
+        lastEntryAt: null,
+        archivedAt: null,
+        data: {},
+        ...overrides,
+    };
+}
+export function entryFixture(overrides = {}) {
+    return {
+        sessionId: 'session-1',
+        createdAt: '2026-07-01T00:00:00.000Z',
+        data: {},
+        ...overrides,
+    };
+}

package/dist/retrospective-distill/flag-args.d.mts

@@ -0,0 +1,5 @@
+export type ParsedFlagArgs = {
+    values: Map<string, string>;
+    positional: string[];
+};
+export declare function parseStringFlags(argv: string[], flags: readonly string[]): ParsedFlagArgs;

package/dist/retrospective-distill/flag-args.mjs

@@ -0,0 +1,31 @@
+// Walks argv for `--flag value` pairs. A value may itself start with a dash (a file path, say), so
+// a missing value is `undefined`, the end-of-options marker, or another recognized flag.
+export function parseStringFlags(argv, flags) {
+    const values = new Map();
+    const positional = [];
+    let optionsEnded = false;
+    let consumed = -1;
+    for (const [i, arg] of argv.entries()) {
+        if (i === consumed)
+            continue;
+        if (!optionsEnded && arg === '--') {
+            optionsEnded = true;
+        }
+        else if (!optionsEnded && flags.includes(arg)) {
+            const value = argv[i + 1];
+            if (value === undefined || value === '--' || flags.includes(value))
+                throw new Error(`${arg} requires a value`);
+            if (values.has(arg))
+                throw new Error(`${arg} may only be specified once`);
+            values.set(arg, value);
+            consumed = i + 1;
+        }
+        else if (!optionsEnded && arg.startsWith('-')) {
+            throw new Error(`unknown option: ${arg}`);
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { values, positional };
+}

package/dist/retrospective-distill/index.d.mts

@@ -0,0 +1,10 @@
+export { parseDistillClassifyArgs } from './args.mts';
+export type { DistillClassifyArgs } from './args.mts';
+export { isCheckpointEntry } from './checkpoint-entry.mts';
+export { readPartitionRecords } from './partition-records.mts';
+export type { PartitionData } from './partition-records.mts';
+export { isRetrospectiveEntry } from './retrospective-entry.mts';
+export { runDistillClassify } from './run.mts';
+export { classifySession } from './shape.mts';
+export type { DistillCutoffs, SessionClassification, SessionShape } from './shape.mts';
+export type { Session, SessionEntry } from './session-types.mts';

package/dist/retrospective-distill/index.mjs

@@ -0,0 +1,6 @@
+export { parseDistillClassifyArgs } from "./args.mjs";
+export { isCheckpointEntry } from "./checkpoint-entry.mjs";
+export { readPartitionRecords } from "./partition-records.mjs";
+export { isRetrospectiveEntry } from "./retrospective-entry.mjs";
+export { runDistillClassify } from "./run.mjs";
+export { classifySession } from "./shape.mjs";

package/dist/retrospective-distill/partition-records.d.mts

@@ -0,0 +1,6 @@
+import type { Session, SessionEntry } from './session-types.mts';
+export type PartitionData = {
+    sessions: Session[];
+    entriesBySession: Map<string, SessionEntry[]>;
+};
+export declare function readPartitionRecords(path: string): Promise<PartitionData>;

package/dist/retrospective-distill/partition-records.mjs

@@ -0,0 +1,49 @@
+import { readFile } from 'node:fs/promises';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// Mirrors the record envelope the agent-blackboard client's own partition writer emits: one JSON
+// object per line, discriminated by `type`. A partition file is written read-only only after its
+// own terminal `manifest` line has already validated, so this reader trusts the bytes on disk — it
+// does not re-verify partition integrity, only recognizes the shapes it can use. An unrecognized
+// `type` (a future upstream record kind, or the top-level snapshot stream's own `error` record,
+// which partition files never carry) is skipped rather than treated as fatal, so a
+// forward-compatible upstream release can't break this classifier.
+function parseLine(line) {
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch {
+        throw new Error('partition contains a line that is not valid JSON');
+    }
+    if (!isRecord(record) || typeof record.type !== 'string') {
+        throw new Error('partition contains a record with no string "type" field');
+    }
+    return record;
+}
+export async function readPartitionRecords(path) {
+    const raw = await readFile(path, 'utf8');
+    const sessions = [];
+    const entriesBySession = new Map();
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const record = parseLine(line);
+        if (record.type === 'session' && isRecord(record.session)) {
+            sessions.push(record.session);
+            continue;
+        }
+        if (record.type === 'entry' && isRecord(record.entry)) {
+            const entry = record.entry;
+            const existing = entriesBySession.get(entry.sessionId);
+            if (existing)
+                existing.push(entry);
+            else
+                entriesBySession.set(entry.sessionId, [entry]);
+        }
+        // 'manifest' (the partition's own terminal line) and any other record type carry no
+        // session-shape information for this classifier and are intentionally ignored.
+    }
+    return { sessions, entriesBySession };
+}

package/dist/retrospective-distill/retrospective-entry.d.mts

@@ -0,0 +1,3 @@
+import type { SessionEntry } from './session-types.mts';
+/** Whether a journal entry was written as a session retrospective. */
+export declare function isRetrospectiveEntry(entry: SessionEntry): boolean;

package/dist/retrospective-distill/retrospective-entry.mjs

@@ -0,0 +1,4 @@
+/** Whether a journal entry was written as a session retrospective. */
+export function isRetrospectiveEntry(entry) {
+    return entry.data.type === 'retrospective';
+}

package/dist/retrospective-distill/run.d.mts

@@ -0,0 +1,5 @@
+/**
+ * Pure local JSONL parsing plus classification — no network, blackboard client, or writes, so it
+ * can run under a read-only inspector sandbox. Returns one tab-separated line per session.
+ */
+export declare function runDistillClassify(argv: string[]): Promise<string>;

package/dist/retrospective-distill/run.mjs

@@ -0,0 +1,28 @@
+import { parseDistillClassifyArgs } from "./args.mjs";
+import { readPartitionRecords } from "./partition-records.mjs";
+import { classifySession } from "./shape.mjs";
+function formatLine(sessionId, shape, eligible) {
+    return `${sessionId}\t${shape}\t${eligible ? 'eligible' : 'not-yet-eligible'}`;
+}
+/**
+ * Pure local JSONL parsing plus classification — no network, blackboard client, or writes, so it
+ * can run under a read-only inspector sandbox. Returns one tab-separated line per session.
+ */
+export async function runDistillClassify(argv) {
+    const args = parseDistillClassifyArgs(argv);
+    const { sessions, entriesBySession } = await readPartitionRecords(args.partitionPath);
+    if (sessions.length === 0)
+        return 'No sessions found in partition.';
+    const cutoffs = { retroCutoff: args.retroCutoff, sessionCutoff: args.sessionCutoff };
+    return sessions
+        .map((session) => {
+        const entries = entriesBySession.get(session.id) ?? [];
+        const { shape, eligible, quarantine, duplicateEntryCount } = classifySession(session, entries, cutoffs);
+        const line = formatLine(session.id, shape, eligible) +
+            (duplicateEntryCount ? `\tduplicate-events=${duplicateEntryCount}` : '');
+        return quarantine
+            ? `${line}\tquarantined=${quarantine.entryCount};reasons=${quarantine.reasons.join(',')}`
+            : line;
+    })
+        .join('\n');
+}

package/dist/retrospective-distill/session-types.d.mts

@@ -0,0 +1,17 @@
+/** Structurally compatible with the agent-blackboard client's `Session`, so no client install is needed. */
+export interface Session {
+    id: string;
+    parentSessionId: string | null;
+    agent: string;
+    version: string;
+    createdAt: string;
+    lastEntryAt: string | null;
+    archivedAt: string | null;
+    data: Record<string, unknown>;
+}
+/** Structurally compatible with the agent-blackboard client's `SessionEntry`. */
+export interface SessionEntry {
+    sessionId: string;
+    createdAt: string;
+    data: Record<string, unknown>;
+}

package/dist/retrospective-distill/session-types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/retrospective-distill/shape.d.mts

@@ -0,0 +1,29 @@
+import type { Session, SessionEntry } from './session-types.mts';
+/**
+ * Session shape taxonomy and distillation eligibility.
+ *
+ * This code is the source of truth for both. The retrospective-distill skill is the canonical
+ * human-facing description; when an inspector's hand classification and this output disagree on
+ * the same session, fix the skill to match this code, not the other way around.
+ *
+ * `zero-entry-child` / `zero-entry-root` name a session-topology fact (whether `parentSessionId`
+ * is set), not a completion signal: a delegated child that dies mid-task is a zero-entry-child
+ * session too, indistinguishable here from one that finished its bounded assignment cleanly.
+ * Docs referencing this split must not imply "child" means "completed normally".
+ */
+export type SessionShape = 'retrospective' | 'entry-type-unresolved' | 'checkpoint-only' | 'journal-only' | 'zero-entry-child' | 'zero-entry-root';
+export type SessionClassification = {
+    sessionId: string;
+    shape: SessionShape;
+    eligible: boolean;
+    quarantine?: {
+        entryCount: number;
+        reasons: string[];
+    };
+    duplicateEntryCount?: number;
+};
+export type DistillCutoffs = {
+    retroCutoff: string;
+    sessionCutoff: string;
+};
+export declare function classifySession(session: Session, entries: SessionEntry[], cutoffs: DistillCutoffs): SessionClassification;