vouchington-tooling 0.43.0 → 0.45.0

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

@@ -12,7 +12,8 @@ const FIELDS = {
     impact: text('Who or what is affected, as markdown.'),
     relatedIssues: {
         type: 'array',
-        description: 'Issues this pull request closes or refs; may be empty.',
+        description: 'Issues this pull request closes or refs. Empty when it has none; with no source issue ' +
+            'at all, give noSourceIssue as well (it is rejected beside a non-empty list).',
         items: {
             type: 'object',
             properties: {
@@ -24,6 +25,15 @@ const FIELDS = {
             additionalProperties: false,
         },
     },
+    noSourceIssue: {
+        type: 'object',
+        description: 'Declares a pull request with no source issue, mutually exclusive with a non-empty ' +
+            'relatedIssues. Rendered inside Related issues (the policy may supply the wording) and ' +
+            'passed to the policy, which may allow it only in interactive mode.',
+        properties: { reason: text('Single-line reason there is no source issue.') },
+        required: ['reason'],
+        additionalProperties: false,
+    },
     details: {
         type: 'array',
         minItems: 1,
@@ -33,7 +43,12 @@ const FIELDS = {
     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.' },
+    mode: {
+        enum: ['interactive', 'autonomous'],
+        description: 'Optional. The server derives the mode from its own launch environment and fails closed: ' +
+            'an automation marker (CI, GITHUB_ACTIONS and similar) means autonomous. This argument ' +
+            'can only narrow interactive to autonomous, never widen it.',
+    },
     workspaceSetup: text('Text for the Workspace setup line, such as how the worktree was prepared.'),
 };
 const REQUIRED = [
@@ -43,7 +58,6 @@ const REQUIRED = [
     'relatedIssues',
     'details',
     'agent',
-    'mode',
     'workspaceSetup',
 ];
 const RENDERING = 'The server renders the body from the structured input (Summary, Impact, Related issues, ' +
@@ -54,7 +68,9 @@ 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),
+        'Journal preserved; the pull request may be in any state and on any head (the head given to ' +
+        'the policy is its own, and no liveness check applies, unlike pr_update). 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 ' +

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

@@ -15,9 +15,15 @@ export const RETROSPECTIVE_TOOLS = [
         '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 ' +
+        'unassessed; any path override is rejected. The server redacts its blackboard token and ' +
+        'knownSensitiveValues (also accepted beside markdown, not beside compose) from the ' +
+        'document, category and feedbackCoverage before the policy sees them. dryRun returns ' +
+        '{ markdown, previewToken, policy: { warnings } } and writes nothing; the previewToken is ' +
+        'opaque, single use, held in server memory (a restart drops it) and bound to the sessionId, ' +
+        'worktree and sourceEventId. To save exactly the previewed content, call again with ' +
+        'previewToken, the identity, mode and the same sourceEventId, and no markdown, compose, ' +
+        'workOutcome, feedbackCoverage, repositories, category or knownSensitiveValues. The ' +
+        'policy is not run again for a token save. 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 ' +
@@ -29,7 +35,10 @@ export const RETROSPECTIVE_TOOLS = [
         'follow journal_append.', ADDITIVE, {
         ...IDENTITY,
         mode: { enum: ['interactive', 'autonomous'], description: 'Delivery mode.' },
-        workOutcome: { enum: OUTCOMES, description: 'Outcome of the work being reported.' },
+        workOutcome: {
+            enum: OUTCOMES,
+            description: 'Outcome of the work being reported; required without previewToken.',
+        },
         feedbackCoverage: COVERAGE,
         repositories: {
             type: 'array',
@@ -44,5 +53,16 @@ export const RETROSPECTIVE_TOOLS = [
         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']),
+        knownSensitiveValues: {
+            type: 'array',
+            items: { type: 'string', minLength: 4 },
+            description: 'Values redacted from every argument of a markdown save.',
+        },
+        previewToken: {
+            type: 'string',
+            description: 'Token from a dry run; saves exactly that content. Exclusive with the content.',
+        },
+    }, 
+    // workOutcome and feedbackCoverage are required unless previewToken carries them.
+    [...IDENTITY_REQUIRED, 'mode']),
 ];

package/dist/mcp-server/tools.mjs

@@ -58,5 +58,11 @@ export const TOOLS = [
         dataArrayContains: { type: 'object', description: 'Exact string membership in arrays.' },
         inactiveForHours: { type: 'number', exclusiveMinimum: 0 },
     }),
+    tool('snapshot_cleanup', 'Deletes the snapshot file (and partition directory, when one was recorded) that ' +
+        'snapshot_export produced. Takes only the cleanupToken it returned: the server resolves the ' +
+        'paths from its own record, never from the caller. The token is bound to the sessionId and ' +
+        'worktree that exported, is single-use, and is forgotten when the server restarts (the ' +
+        'file is then left for the OS to reap). A failed cleanup keeps the token valid and names ' +
+        'any retained tombstone so the same call can retry. Call it as a finally step.', { ...MUTATING, idempotentHint: false }, { cleanupToken: { type: 'string', description: 'The cleanupToken snapshot_export returned.' } }, ['cleanupToken']),
     tool('session_archive', 'Marks a session as distilled. Its metadata becomes immutable; entries stay appendable.', MUTATING),
 ];

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;

package/dist/retrospective-distill/shape.mjs

@@ -0,0 +1,111 @@
+import { isDeepStrictEqual } from 'node:util';
+import { validateFeedbackEnvelope } from "../agent-blackboard/index.mjs";
+import { isCheckpointEntry } from "./checkpoint-entry.mjs";
+import { isRetrospectiveEntry } from "./retrospective-entry.mjs";
+function quarantineReason(entry) {
+    if (entry.data.type !== 'journal' && entry.data.type !== 'retrospective')
+        return 'unknown-entry-type';
+    if (entry.data.schemaVersion !== undefined) {
+        try {
+            validateFeedbackEnvelope(entry.data);
+        }
+        catch {
+            return 'invalid-feedback-envelope';
+        }
+    }
+    return undefined;
+}
+function hasUnresolvedType(entry) {
+    return quarantineReason(entry) !== undefined;
+}
+function classifyShape(session, entries) {
+    if (entries.some(hasUnresolvedType))
+        return 'entry-type-unresolved';
+    if (entries.some(isRetrospectiveEntry))
+        return 'retrospective';
+    if (entries.length === 0) {
+        // Loose equality on purpose: a partition record missing `parentSessionId` entirely (the reader
+        // trusts the file on disk and does not re-validate every field against the Session interface —
+        // see partition-records.mts) must fall to zero-entry-root. This is a topology and capture-gap
+        // signal, never evidence of crash or clean completion. `=== null` would silently misroute
+        // `undefined` into the wrong, discarded bucket.
+        return session.parentSessionId == null ? 'zero-entry-root' : 'zero-entry-child';
+    }
+    return entries.every(isCheckpointEntry) ? 'checkpoint-only' : 'journal-only';
+}
+function newestRetrospectiveAt(entries) {
+    let newest;
+    for (const entry of entries) {
+        if (!isRetrospectiveEntry(entry))
+            continue;
+        if (newest === undefined || Date.parse(entry.createdAt) > Date.parse(newest))
+            newest = entry.createdAt;
+    }
+    return newest;
+}
+// Eligibility rule:
+// (has a retrospective entry AND retroAt < retroCutoff) OR (lastActive < sessionCutoff).
+// An entry-type-unresolved session gets no issue-filing or archival pass "this run, regardless of
+// its age", so it is never eligible — that check short-circuits before the formula.
+function isEligible(session, entries, shape, cutoffs) {
+    if (shape === 'entry-type-unresolved')
+        return false;
+    const retroAt = newestRetrospectiveAt(entries);
+    const staleRetro = retroAt !== undefined && Date.parse(retroAt) < Date.parse(cutoffs.retroCutoff);
+    const lastActive = entries.reduce((latest, entry) => Date.parse(entry.createdAt) > Date.parse(latest) ? entry.createdAt : latest, session.createdAt);
+    const staleSession = Date.parse(lastActive) < Date.parse(cutoffs.sessionCutoff);
+    return staleRetro || staleSession;
+}
+// An event is its session, `sourceEventId`, and content; the server assigns `timestamp` per attempt
+// (a retry or a late write beside it can store the same event twice), so it is not identity.
+function withoutTimestamp(data) {
+    return Object.fromEntries(Object.entries(data).filter(([key]) => key !== 'timestamp'));
+}
+function normalizeSourceEvents(entries) {
+    const events = new Map();
+    const unique = [];
+    let duplicateEntryCount = 0;
+    let conflictCount = 0;
+    for (const entry of entries) {
+        if (entry.data.schemaVersion !== 1 || quarantineReason(entry) !== undefined) {
+            unique.push(entry);
+            continue;
+        }
+        const key = `${entry.sessionId}:${String(entry.data.sourceEventId)}`;
+        const existing = events.get(key);
+        if (!existing) {
+            events.set(key, entry);
+            unique.push(entry);
+            continue;
+        }
+        if (!isDeepStrictEqual(withoutTimestamp(existing.data), withoutTimestamp(entry.data))) {
+            conflictCount++;
+            continue;
+        }
+        duplicateEntryCount++;
+        // At-least-once replay does not postpone a source event's distillation age.
+        if (Date.parse(entry.createdAt) < Date.parse(existing.createdAt)) {
+            unique[unique.indexOf(existing)] = entry;
+            events.set(key, entry);
+        }
+    }
+    return { unique, duplicateEntryCount, conflictCount };
+}
+export function classifySession(session, entries, cutoffs) {
+    const { unique, duplicateEntryCount, conflictCount } = normalizeSourceEvents(entries);
+    const shape = conflictCount ? 'entry-type-unresolved' : classifyShape(session, unique);
+    const reasons = entries
+        .map(quarantineReason)
+        .filter((reason) => reason !== undefined);
+    for (let index = 0; index < conflictCount; index++)
+        reasons.push('conflicting-source-event');
+    return {
+        sessionId: session.id,
+        shape,
+        eligible: isEligible(session, unique, shape, cutoffs),
+        ...(duplicateEntryCount ? { duplicateEntryCount } : {}),
+        ...(reasons.length === 0
+            ? {}
+            : { quarantine: { entryCount: reasons.length, reasons: [...new Set(reasons)].toSorted() } }),
+    };
+}