vouchington-tooling 0.24.1 → 0.26.0

package/dist/mcp-server/harness.test-helpers.mjs

@@ -0,0 +1,48 @@
+import { join } from 'node:path';
+import { afterEach, beforeEach } from 'vitest';
+import { callTool } from './dispatch.mjs';
+import { BLACKBOARD_ENV, fakeBlackboard, } from './fake-blackboard.test-helpers.mjs';
+import { createRepoFixture } from './git-fixture.test-helpers.mjs';
+import { runIsolatedGit } from './worktree.mjs';
+/** A fresh pair of real repositories for every test. */
+export function useRepoFixture() {
+    let fixture;
+    beforeEach(() => {
+        fixture = createRepoFixture();
+    });
+    afterEach(() => fixture?.cleanup());
+    return () => fixture;
+}
+export function outboxPath(worktree) {
+    return join(worktree, '.local', 'blackboard-outbox');
+}
+/** Calls tools against a repository fixture with the blackboard client faked. */
+export function harness(fixture, options = {}) {
+    const fake = fakeBlackboard(options);
+    const environment = {
+        launchRoot: fixture.main,
+        env: options.env ?? BLACKBOARD_ENV,
+        runGit: runIsolatedGit,
+        blackboard: fake.dependencies,
+    };
+    return { fake, call: (name, args) => callTool(name, args, environment) };
+}
+export function textOf(result) {
+    return result.content.map((part) => part.text).join('\n');
+}
+export function jsonOf(result) {
+    return JSON.parse(textOf(result));
+}
+export const JOURNAL_ARGS = {
+    sessionId: 'native:owner',
+    parentSessionId: null,
+    agent: 'codex',
+    version: '1',
+    mode: 'autonomous',
+    markdown: '## Finding\nThe build cache was cold.',
+    sourceEventId: 'journal:1',
+    workOutcome: 'success',
+    repositories: ['owner/repo'],
+    feedbackCoverage: { status: 'complete', sources: ['tool-result'], droppedCount: 0 },
+    timestamp: '2026-01-01T00:00:00.000Z',
+};

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

@@ -0,0 +1,20 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { BlackboardClientDependencies } from '../agent-blackboard/client.mts';
+import type { RunTextCommand } from '../gh-cli/exec.mts';
+import { type SdkImporter } from './sdk.mts';
+export type RunMcpServerOptions = {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    version: string;
+    importSdk?: SdkImporter;
+    runGit?: RunTextCommand;
+    /** Defaults to stdio. Tests pass one half of an in-memory pair. */
+    transport?: Transport;
+    /** Test seam: replaces how the consumer's `agent-blackboard` client is loaded. */
+    blackboard?: BlackboardClientDependencies;
+};
+/**
+ * Starts the server and resolves once it is connected. Nothing on this path may write to stdout:
+ * stdout is the protocol channel, so diagnostics go to stderr.
+ */
+export declare function runMcpServer(options: RunMcpServerOptions): Promise<void>;

package/dist/mcp-server/run.mjs

@@ -0,0 +1,21 @@
+import { loadMcpSdk } from './sdk.mjs';
+import { createMcpServer } from './server.mjs';
+import { launchWorktreeRoot, runIsolatedGit } from './worktree.mjs';
+/**
+ * Starts the server and resolves once it is connected. Nothing on this path may write to stdout:
+ * stdout is the protocol channel, so diagnostics go to stderr.
+ */
+export async function runMcpServer(options) {
+    const runGit = options.runGit ?? runIsolatedGit;
+    const sdk = await loadMcpSdk(options.importSdk);
+    const launchRoot = await launchWorktreeRoot(options.cwd, runGit);
+    const environment = {
+        launchRoot,
+        env: options.env,
+        runGit,
+        ...(options.blackboard === undefined ? {} : { blackboard: options.blackboard }),
+    };
+    const server = createMcpServer(sdk, environment, options.version);
+    /* v8 ignore next -- the stdio default is exercised by the spawned-process test */
+    await server.connect(options.transport ?? new sdk.StdioServerTransport());
+}

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

@@ -0,0 +1,17 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import type { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+/** The slice of `@modelcontextprotocol/sdk` this server uses, loaded only when `mcp` runs. */
+export type McpSdk = {
+    McpServer: typeof McpServer;
+    StdioServerTransport: typeof StdioServerTransport;
+    CallToolRequestSchema: typeof CallToolRequestSchema;
+    ListToolsRequestSchema: typeof ListToolsRequestSchema;
+};
+export type SdkImporter = (specifier: string) => Promise<unknown>;
+export declare const MISSING_SDK_MESSAGE: string;
+/**
+ * Imports the SDK lazily. A static import would make every `vouchington` command fail on a
+ * consumer that never installed the optional peer.
+ */
+export declare function loadMcpSdk(importSdk?: SdkImporter): Promise<McpSdk>;

package/dist/mcp-server/sdk.mjs

@@ -0,0 +1,33 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { isMissingModuleError } from '../agent-blackboard/client.mjs';
+const SDK_PACKAGE = '@modelcontextprotocol/sdk';
+export const MISSING_SDK_MESSAGE = `vouchington mcp needs ${SDK_PACKAGE} (and its zod peer), which is an optional peer ` +
+    `dependency of vouchington-tooling and is not installed. Install it next to ` +
+    `vouchington-tooling: pnpm add -D ${SDK_PACKAGE} zod`;
+const defaultImporter = (specifier) => import(__rewriteRelativeImportExtension(specifier));
+/**
+ * Imports the SDK lazily. A static import would make every `vouchington` command fail on a
+ * consumer that never installed the optional peer.
+ */
+export async function loadMcpSdk(importSdk = defaultImporter) {
+    try {
+        const [server, stdio, types] = await Promise.all([
+            importSdk(`${SDK_PACKAGE}/server/mcp.js`),
+            importSdk(`${SDK_PACKAGE}/server/stdio.js`),
+            importSdk(`${SDK_PACKAGE}/types.js`),
+        ]);
+        return { ...server, ...stdio, ...types };
+    }
+    catch (error) {
+        if (isMissingModuleError(error))
+            throw new Error(MISSING_SDK_MESSAGE, { cause: error });
+        throw error;
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ServerEnvironment } from './dispatch.mts';
+import type { McpSdk } from './sdk.mts';
+export declare const SERVER_NAME = "vouchington-tooling";
+/**
+ * Builds the server. The tool list and call handlers go on the low-level `server` because the
+ * high-level `registerTool` path needs zod schemas, and this package keeps zod out of its own code.
+ */
+export declare function createMcpServer(sdk: McpSdk, environment: ServerEnvironment, version: string): McpServer;

package/dist/mcp-server/server.mjs

@@ -0,0 +1,17 @@
+import { callTool } from './dispatch.mjs';
+import { TOOLS } from './tools.mjs';
+export const SERVER_NAME = 'vouchington-tooling';
+const INSTRUCTIONS = 'Journals agent-blackboard feedback for a vouchington consumer. Every tool takes an explicit ' +
+    'sessionId and an optional worktree (an absolute path listed by `git worktree list` for the ' +
+    'repository this server was launched from). Tool errors are actionable; do not fall back to a CLI.';
+/**
+ * Builds the server. The tool list and call handlers go on the low-level `server` because the
+ * high-level `registerTool` path needs zod schemas, and this package keeps zod out of its own code.
+ */
+export function createMcpServer(sdk, environment, version) {
+    const mcp = new sdk.McpServer({ name: SERVER_NAME, version }, { instructions: INSTRUCTIONS });
+    mcp.server.registerCapabilities({ tools: {} });
+    mcp.server.setRequestHandler(sdk.ListToolsRequestSchema, async () => ({ tools: [...TOOLS] }));
+    mcp.server.setRequestHandler(sdk.CallToolRequestSchema, async (request) => callTool(request.params.name, request.params.arguments, environment));
+    return mcp;
+}

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

@@ -0,0 +1,19 @@
+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 TOOLS: readonly ToolDefinition[];
+export {};

package/dist/mcp-server/tools.mjs

@@ -0,0 +1,120 @@
+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 a worktree listed by `git worktree list` for the repository the server ' +
+        'was launched from. Defaults to the launch 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'];
+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 ' +
+        'envelope in the worktree outbox when the blackboard is unreachable.', ADDITIVE, {
+        ...IDENTITY,
+        mode: { enum: ['interactive', 'autonomous'], description: 'Delivery mode.' },
+        markdown: { type: 'string', description: 'Journal note as markdown text (max 12000 bytes).' },
+        sourceEventId: { type: 'string', pattern: ID_PATTERN, description: 'Stable event id.' },
+        workOutcome: { enum: OUTCOMES, description: 'Outcome of the work being reported.' },
+        repositories: {
+            type: 'array',
+            items: { type: 'string' },
+            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.',
+        },
+        timestamp: {
+            type: 'string',
+            description: 'Optional ISO 8601 time; defaults to now and is returned. Reuse the same sourceEventId ' +
+                'and timestamp when retrying, because the whole envelope must match.',
+        },
+        category: { type: 'string', description: 'Optional context; never changes entry type.' },
+    }, [
+        ...IDENTITY_REQUIRED,
+        'mode',
+        'markdown',
+        'sourceEventId',
+        'workOutcome',
+        'repositories',
+        'feedbackCoverage',
+    ]),
+    tool('journal_entries', 'Returns every entry of one session, oldest first, as JSON: { sessionId, entries }. Each ' +
+        'entry is exactly as the blackboard returns it ({ sessionId, createdAt, data }), including ' +
+        'non-journal types such as retrospective and legacy entries without a feedback envelope.', READ_ONLY),
+    tool('outbox_status', 'Reports how many unsent journal records the worktree outbox retains. sessionId identifies ' +
+        'the caller; the count covers the whole outbox.', READ_ONLY),
+    tool('outbox_flush', 'Delivers retained outbox records and returns the remaining count. sessionId identifies the ' +
+        'caller; the flush covers every record in the worktree outbox.', 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),
+    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, {
+        agent: AGENT,
+        version: VERSION,
+        parentSessionId: PARENT_SESSION_ID,
+        data: { type: 'object', description: 'Top-level session data fields to match exactly.' },
+        dataArrayContains: { type: 'object', description: 'Exact string membership in arrays.' },
+        inactiveForHours: { type: 'number', exclusiveMinimum: 0 },
+    }),
+    tool('session_archive', 'Marks a session as distilled. Its metadata becomes immutable; entries stay appendable.', MUTATING),
+];

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

@@ -0,0 +1,18 @@
+import { type RunTextCommand } from '../gh-cli/exec.mts';
+/** Runs git without inherited `GIT_*` variables so `GIT_DIR` cannot redirect the check. */
+export declare const runIsolatedGit: RunTextCommand;
+/** The worktree root containing `cwd`, or a message that says how to fix the launch directory. */
+export declare function launchWorktreeRoot(cwd: string, runGit: RunTextCommand): Promise<string>;
+/** Paths of the non-bare entries in `git worktree list --porcelain` output. */
+export declare function parseWorktreeList(porcelain: string): string[];
+/**
+ * Resolves the worktree a tool call may act on. The list is read from git on every call, so
+ * worktrees created after the server started are accepted and removed ones are not. The
+ * comparison is exact on real paths: a subdirectory of a worktree, or an unrelated repository,
+ * is rejected.
+ */
+export declare function resolveWorktree(input: {
+    launchRoot: string;
+    requested?: string | undefined;
+    runGit: RunTextCommand;
+}): Promise<string>;

package/dist/mcp-server/worktree.mjs

@@ -0,0 +1,58 @@
+import { execFile } from 'node:child_process';
+import { realpath } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { promisify } from 'node:util';
+import { createCommandRunner } from '../gh-cli/exec.mjs';
+import { gitEnv } from '../shared-context/index.mjs';
+const execFileAsync = promisify(execFile);
+/** Runs git without inherited `GIT_*` variables so `GIT_DIR` cannot redirect the check. */
+export const runIsolatedGit = createCommandRunner('git', (command, args) => execFileAsync(command, args, { env: gitEnv() }));
+async function canonical(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The worktree root containing `cwd`, or a message that says how to fix the launch directory. */
+export async function launchWorktreeRoot(cwd, runGit) {
+    try {
+        return await realpath((await runGit(['-C', cwd, 'rev-parse', '--show-toplevel'])).trim());
+    }
+    catch (error) {
+        throw new Error(`vouchington mcp must be launched inside a git worktree; ${cwd} is not one (${errorText(error)})`);
+    }
+}
+/** Paths of the non-bare entries in `git worktree list --porcelain` output. */
+export function parseWorktreeList(porcelain) {
+    const paths = [];
+    for (const block of porcelain.split(/\r?\n\r?\n/)) {
+        const lines = block.split(/\r?\n/);
+        const first = lines.find((line) => line.startsWith('worktree '));
+        if (first !== undefined && !lines.includes('bare'))
+            paths.push(first.slice('worktree '.length));
+    }
+    return paths;
+}
+/**
+ * Resolves the worktree a tool call may act on. The list is read from git on every call, so
+ * worktrees created after the server started are accepted and removed ones are not. The
+ * comparison is exact on real paths: a subdirectory of a worktree, or an unrelated repository,
+ * is rejected.
+ */
+export async function resolveWorktree(input) {
+    const { launchRoot, requested, runGit } = input;
+    if (requested !== undefined && !isAbsolute(requested))
+        throw new Error('worktree must be an absolute path to a git worktree of the launch repository');
+    const target = requested === undefined ? launchRoot : await canonical(requested);
+    const listing = await runGit(['-C', launchRoot, 'worktree', 'list', '--porcelain']);
+    const known = (await Promise.all(parseWorktreeList(listing).map(canonical))).filter((path) => path !== undefined);
+    if (target !== undefined && known.includes(target))
+        return target;
+    throw new Error(`worktree ${requested ?? launchRoot} is not a worktree of the repository this server was ` +
+        `launched from (${launchRoot}). Registered worktrees: ${known.join(', ')}`);
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/session-friction/audit-block.d.mts

@@ -0,0 +1,4 @@
+import type { JournalEntry } from './types.mts';
+/** Returns the paste-safe block, or null when the markdown is not exactly one conforming block. */
+export declare function matchAuditBlock(markdown: string, patterns: readonly RegExp[], prefixes: readonly string[]): string | null;
+export declare function conformingBlocks(entries: Iterable<JournalEntry>, match: (markdown: string) => string | null): string[];

package/dist/session-friction/audit-block.mjs

@@ -0,0 +1,45 @@
+import { isWellFormedUnicode, markdownAuditText } from './text.mjs';
+const BLANK = /^\s*$/;
+function sanitizeField(line, prefixes) {
+    const prefix = prefixes.find((value) => line.startsWith(value));
+    /* v8 ignore next -- callers only pass lines that matched a pattern with a known prefix. */
+    if (!prefix)
+        return markdownAuditText(line) || null;
+    const content = markdownAuditText(line.slice(prefix.length));
+    return content ? `${prefix}${content}` : null;
+}
+// Consumes exactly one line per pattern (skipping blank lines between them) and nothing else.
+function matchLines(markdown, patterns) {
+    if (!isWellFormedUnicode(markdown))
+        return null;
+    const lines = markdown.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
+    let index = 0;
+    const fields = [];
+    for (const pattern of patterns) {
+        while (index < lines.length && BLANK.test(lines[index]))
+            index++;
+        const line = lines[index];
+        if (line === undefined || !pattern.test(line))
+            return null;
+        fields.push(line);
+        index++;
+    }
+    return lines.slice(index).every((line) => BLANK.test(line)) ? fields : null;
+}
+/** Returns the paste-safe block, or null when the markdown is not exactly one conforming block. */
+export function matchAuditBlock(markdown, patterns, prefixes) {
+    const fields = matchLines(markdown, patterns);
+    if (!fields)
+        return null;
+    const safeFields = fields.map((field) => sanitizeField(field, prefixes));
+    return safeFields.some((field) => field === null) ? null : safeFields.join('\n');
+}
+export function conformingBlocks(entries, match) {
+    return [...entries]
+        .flatMap((entry) => {
+        const data = entry?.data;
+        return data?.type === 'journal' && typeof data.markdown === 'string' ? [data.markdown] : [];
+    })
+        .map(match)
+        .filter((block) => block !== null);
+}

package/dist/session-friction/ci-failures.d.mts

@@ -1,6 +1,7 @@
 import type { FrictionLogReadResult, JournalEntry } from './types.mts';
 export declare function isConformingCiFailureBlock(markdown: string): boolean;
 export declare function getConformingGroups(entries: Iterable<JournalEntry>): string[];
+export declare function incompleteCiSection(markdownBlocks: string[]): string;
 export declare function buildCiFailuresSection(sessionId: string, journal: {
     status: 'ok';
     markdownBlocks: string[];
@@ -8,4 +9,4 @@ export declare function buildCiFailuresSection(sessionId: string, journal: {
 } | {
     status: 'unreachable';
     diagnostic: string;
-}, frictionStatus: FrictionLogReadResult['status']): string;
+}, frictionStatus: FrictionLogReadResult['status'] | 'journal-only'): string;

package/dist/session-friction/ci-failures.mjs

@@ -1,9 +1,9 @@
-import { isWellFormedUnicode, markdownAuditText } from './text.mjs';
+import { conformingBlocks, matchAuditBlock } from './audit-block.mjs';
+import { markdownAuditText } from './text.mjs';
 const GROUP_HEADER = /^- `(recurring|one-off)` — `GitHub Actions` — .*[^\s]$/;
 const EVIDENCE = /^ {2}- Evidence: .*[^\s]$/;
 const ROOT_DIAGNOSTIC = /^ {2}- Root diagnostic: .*[^\s]$/;
 const DISPOSITION = /^ {2}- Disposition: .*[^\s]$/;
-const BLANK = /^\s*$/;
 const CI_FAILURES_HEADER = '## CI Failures';
 const CI_FAILURE_BLOCK_MAX_BYTES = 10_000;
 const FIELD_PREFIXES = [
@@ -13,42 +13,8 @@ const FIELD_PREFIXES = [
     '  - Root diagnostic: ',
     '  - Disposition: ',
 ];
-function safeField(line) {
-    const prefix = FIELD_PREFIXES.find((value) => line.startsWith(value));
-    /* v8 ignore next -- matchBlock currently passes only fields with a known prefix. */
-    if (!prefix)
-        return markdownAuditText(line) || null;
-    const content = markdownAuditText(line.slice(prefix.length));
-    return content ? `${prefix}${content}` : null;
-}
 function matchBlock(markdown) {
-    if (!isWellFormedUnicode(markdown))
-        return null;
-    const lines = markdown.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
-    let index = 0;
-    const consume = (pattern) => {
-        while (index < lines.length && BLANK.test(lines[index]))
-            index++;
-        const line = lines[index];
-        if (line === undefined || !pattern.test(line))
-            return null;
-        index++;
-        return line;
-    };
-    const fields = [
-        consume(GROUP_HEADER),
-        consume(EVIDENCE),
-        consume(ROOT_DIAGNOSTIC),
-        consume(DISPOSITION),
-    ];
-    if (fields.some((field) => field === null))
-        return null;
-    if (!lines.slice(index).every((line) => BLANK.test(line)))
-        return null;
-    const safeFields = fields.map((field) => safeField(field));
-    if (safeFields.some((field) => field === null))
-        return null;
-    return safeFields.join('\n');
+    return matchAuditBlock(markdown, [GROUP_HEADER, EVIDENCE, ROOT_DIAGNOSTIC, DISPOSITION], FIELD_PREFIXES);
 }
 export function isConformingCiFailureBlock(markdown) {
     if (markdown.length > CI_FAILURE_BLOCK_MAX_BYTES ||
@@ -56,16 +22,14 @@ export function isConformingCiFailureBlock(markdown) {
         return false;
     return matchBlock(markdown) !== null;
 }
-function journalMarkdown(entries) {
-    return [...entries].flatMap((entry) => {
-        const data = entry?.data;
-        return data?.type === 'journal' && typeof data.markdown === 'string' ? [data.markdown] : [];
-    });
-}
 export function getConformingGroups(entries) {
-    return journalMarkdown(entries)
-        .map(matchBlock)
-        .filter((block) => block !== null);
+    return conformingBlocks(entries, matchBlock);
+}
+export function incompleteCiSection(markdownBlocks) {
+    return [
+        `${CI_FAILURES_HEADER}\nStatus: unavailable (journal scan incomplete)`,
+        ...markdownBlocks,
+    ].join('\n\n');
 }
 export function buildCiFailuresSection(sessionId, journal, frictionStatus) {
     if (journal.status === 'unreachable')

package/dist/session-friction/journal.d.mts

@@ -0,0 +1,14 @@
+import type { JournalEntry, JournalLoader } from './types.mts';
+export type JournalScan = {
+    status: 'ok';
+    entries: JournalEntry[];
+    truncated: boolean;
+} | {
+    status: 'not-found';
+} | {
+    status: 'unreachable';
+    diagnostic: string;
+};
+export declare function errorMessage(error: unknown): string;
+/** Loads the session journal through the caller's loader within the shared bounded scan. */
+export declare function scanJournal(sessionId: string, loader: JournalLoader): Promise<JournalScan>;

package/dist/session-friction/journal.mjs

@@ -0,0 +1,66 @@
+const JOURNAL_ENTRY_MAX_COUNT = 500;
+const JOURNAL_MARKDOWN_MAX_BYTES = 10_000;
+const JOURNAL_TOTAL_MAX_BYTES = 1_000_000;
+function journalData(entry) {
+    try {
+        const data = entry?.data;
+        return data ? { type: data.type, markdown: data.markdown } : undefined;
+    }
+    catch {
+        return 'unreadable';
+    }
+}
+async function collectEntries(entries) {
+    const result = [];
+    let consumed = 0;
+    let inspectedBytes = 0;
+    let retainedBytes = 0;
+    let truncated = false;
+    for await (const entry of entries) {
+        consumed++;
+        const scanned = journalData(entry);
+        if (scanned === 'unreadable')
+            truncated = true;
+        const data = scanned === 'unreadable' ? undefined : scanned;
+        const markdown = data?.markdown;
+        if (data?.type === 'journal' && typeof markdown !== 'string')
+            truncated = true;
+        if (data?.type === 'journal' && typeof markdown === 'string') {
+            const bytes = Buffer.byteLength(markdown);
+            inspectedBytes += bytes;
+            if (bytes > JOURNAL_MARKDOWN_MAX_BYTES)
+                truncated = true;
+            if (bytes <= JOURNAL_MARKDOWN_MAX_BYTES && retainedBytes + bytes <= JOURNAL_TOTAL_MAX_BYTES) {
+                result.push({ data: { type: 'journal', markdown } });
+                retainedBytes += bytes;
+            }
+        }
+        if (consumed >= JOURNAL_ENTRY_MAX_COUNT ||
+            inspectedBytes >= JOURNAL_TOTAL_MAX_BYTES ||
+            retainedBytes >= JOURNAL_TOTAL_MAX_BYTES) {
+            truncated = true;
+            break;
+        }
+    }
+    return { entries: result, truncated };
+}
+export function errorMessage(error) {
+    try {
+        return error instanceof Error ? error.message : String(error);
+    }
+    catch {
+        return '[unprintable error]';
+    }
+}
+/** Loads the session journal through the caller's loader within the shared bounded scan. */
+export async function scanJournal(sessionId, loader) {
+    try {
+        const loaded = await loader(sessionId);
+        if (loaded.status === 'not-found')
+            return { status: 'not-found' };
+        return { status: 'ok', ...(await collectEntries(loaded.entries)) };
+    }
+    catch (error) {
+        return { status: 'unreachable', diagnostic: errorMessage(error) };
+    }
+}