vouchington-tooling 0.36.2 → 0.37.1

package/README.md

@@ -439,7 +439,7 @@ when building a report, stopping earlier when its aggregate 1 MB inspected-byte
 Bounded journal scans that stop before exhaustion are reported as incomplete rather than clean.
 Report liveness inherits the caller-supplied journal loader, which must bound its own I/O and yields.
 Log reads are capped at 2 MB, journal Markdown at 10,000 bytes per entry,
-and rendered audit fields at 120 escaped characters. Permission requests record requested outcomes; explicit result observations may record approved
+and rendered audit fields are kept whole: composition loads the journal and friction log once, redacts each field from its raw text before Markdown escaping (a caller-supplied redactor runs first, then the built-in one), then renders the CI and sandbox sections, measures the real envelope against its 12,000-byte markdown and 16,384-byte envelope limits, and shrinks them in a few bounded attempts. A block shrinks Root diagnostic first and Evidence last, cutting only at token boundaries (never inside a URL or SHA) with a trailing `…`; groups that still cannot fit are omitted and counted in an explicit conforming group that points at the journal. The final attempt keeps only that omission note (about 300 bytes), so an input within roughly 300 bytes of the limit can still fail to compose. A caller-supplied `budgets` cap limits rendered groups only; the omission note is exempt from it. Permission requests record requested outcomes; explicit result observations may record approved
 or denied outcomes. A decision and simultaneous tool failure are both retained and counted in
 the report. Escalation detail without a decision remains unknown. Localhost connection
 refusal is an ambiguous failure and does not establish a sandbox cause. The supplied log directory must be dedicated

package/dist/agent-blackboard/feedback-audit-source.d.mts

@@ -1,4 +1,5 @@
-import { type SessionFrictionReport, type SessionFrictionReportOptions } from '../session-friction/index.mts';
+import { type FrictionReportInputs, type SessionFrictionReport, type SessionFrictionReportOptions } from '../session-friction/index.mts';
+import type { JournalScan } from '../session-friction/journal.mts';
 import { type JournalAuditOptions, type JournalAuditReport } from './feedback-journal-audit.mts';
 export type AuditSourceInput = {
     friction?: SessionFrictionReportOptions;
@@ -6,8 +7,19 @@ export type AuditSourceInput = {
 };
 export type AuditReport = SessionFrictionReport | JournalAuditReport;
 export declare function assertSingleAuditSource(input: AuditSourceInput): void;
-/** Builds the CI-failure and sandbox sections from the friction log or from journal entries alone. */
-export declare function buildAuditReport(sessionId: string, input: AuditSourceInput): Promise<AuditReport>;
+/** What the audit sections read from outside, loaded once and rendered as often as needed. */
+export type AuditInputs = {
+    kind: 'friction';
+    loaded: FrictionReportInputs;
+} | {
+    kind: 'journal';
+    scanned: JournalScan;
+} | {
+    kind: 'none';
+};
+export declare function loadAuditInputs(sessionId: string, input: AuditSourceInput): Promise<AuditInputs>;
+/** Builds the CI-failure and sandbox sections from loaded inputs, with no further I/O. */
+export declare function renderAuditReport(sessionId: string, input: AuditSourceInput, inputs: AuditInputs): AuditReport;
 /** Only a real log status or an explicit journal-only scan counts as assessed. */
 export declare function auditAssessed({ coverage }: AuditReport): boolean;
 export declare function completeCoverageError(input: AuditSourceInput): Error;

package/dist/agent-blackboard/feedback-audit-source.mjs

@@ -1,17 +1,24 @@
-import { buildSessionFrictionReport, } from "../session-friction/index.mjs";
-import { buildJournalAuditReport, } from "./feedback-journal-audit.mjs";
+import { loadFrictionReportInputs, renderFrictionReport, } from "../session-friction/index.mjs";
+import { loadJournalAuditInput, renderJournalAuditReport, } from "./feedback-journal-audit.mjs";
 const ASSESSED_SOURCE_ERROR = 'complete feedback coverage requires assessed available factual and finding sources';
 const NOT_ASSESSED_MARKDOWN = '## CI Failures\nStatus: unavailable (not assessed)\n\n## Sandbox & Permission Audit\nStatus: unavailable (not assessed)';
 export function assertSingleAuditSource(input) {
     if (input.friction && input.journal)
         throw new Error('composition accepts either a friction or a journal audit source, not both');
 }
-/** Builds the CI-failure and sandbox sections from the friction log or from journal entries alone. */
-export async function buildAuditReport(sessionId, input) {
+export async function loadAuditInputs(sessionId, input) {
     if (input.friction)
-        return buildSessionFrictionReport(sessionId, input.friction);
+        return { kind: 'friction', loaded: await loadFrictionReportInputs(sessionId, input.friction) };
     if (input.journal)
-        return buildJournalAuditReport(sessionId, input.journal);
+        return { kind: 'journal', scanned: await loadJournalAuditInput(sessionId, input.journal) };
+    return { kind: 'none' };
+}
+/** Builds the CI-failure and sandbox sections from loaded inputs, with no further I/O. */
+export function renderAuditReport(sessionId, input, inputs) {
+    if (inputs.kind === 'friction')
+        return renderFrictionReport(sessionId, input.friction, inputs.loaded);
+    if (inputs.kind === 'journal')
+        return renderJournalAuditReport(sessionId, input.journal, inputs.scanned);
     return {
         coverage: { journalStatus: 'unavailable', frictionStatus: 'absent', truncated: false },
         markdown: NOT_ASSESSED_MARKDOWN,

package/dist/agent-blackboard/feedback-codec.d.mts

@@ -2,6 +2,10 @@ export { normalizeRepositories } from './feedback-fields.mts';
 import type { FeedbackEnvelope } from './feedback-types.mts';
 export declare function validateFeedbackEnvelope(value: unknown): asserts value is FeedbackEnvelope;
 export declare function redactFeedbackText(value: string, knownSensitiveValues?: string[]): string;
+/** Bytes by which the envelope exceeds its markdown or whole-envelope limit; 0 when it fits. */
+export declare function feedbackOverflowBytes(input: FeedbackEnvelope, options?: {
+    knownSensitiveValues?: string[];
+}): number;
 export declare function createFeedbackEnvelope(input: FeedbackEnvelope, options?: {
     knownSensitiveValues?: string[];
 }): FeedbackEnvelope;

package/dist/agent-blackboard/feedback-codec.mjs

@@ -2,6 +2,7 @@ import { normalizeRepositories, validateFeedbackText, validateFeedbackReferences
 export { normalizeRepositories } from "./feedback-fields.mjs";
 import { isCount, isObject } from "./snapshot-partition-guards.mjs";
 const FEEDBACK_MAX_BYTES = 16_384;
+const FEEDBACK_MARKDOWN_MAX_BYTES = 12_000;
 const OUTCOMES = [
     'in-progress',
     'success',
@@ -44,7 +45,7 @@ export function validateFeedbackEnvelope(value) {
         throw new Error('timestamp must be a canonical ISO date-time');
     if (JSON.stringify(value.repositories) !== JSON.stringify(normalizeRepositories(value.repositories)))
         throw new Error('repositories must be canonical');
-    validateFeedbackText(value.markdown, 'markdown', 12_000);
+    validateFeedbackText(value.markdown, 'markdown', FEEDBACK_MARKDOWN_MAX_BYTES);
     if (typeof value.workOutcome !== 'string' || !OUTCOMES.includes(value.workOutcome))
         throw new Error('workOutcome must be explicit');
     if (!isObject(value.feedbackCoverage) ||
@@ -88,10 +89,20 @@ export function redactFeedbackText(value, knownSensitiveValues = []) {
         .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+:[^\s/@]+@/gi, '$1[REDACTED]@')
         .replace(/((?:password|secret|token|api[_-]?key)\s*[=:]\s*)(?:"[^"]*"|'[^']*'|[^\s,;]+)/gi, '$1[REDACTED]');
 }
+/** Bytes by which the envelope exceeds its markdown or whole-envelope limit; 0 when it fits. */
+export function feedbackOverflowBytes(input, options = {}) {
+    const envelope = redactedEnvelope(input, options);
+    return Math.max(0, Buffer.byteLength(envelope.markdown) - FEEDBACK_MARKDOWN_MAX_BYTES, Buffer.byteLength(JSON.stringify(envelope)) - FEEDBACK_MAX_BYTES);
+}
 export function createFeedbackEnvelope(input, options = {}) {
-    validateFeedbackText(input.markdown, 'markdown', 12_000);
+    validateFeedbackText(input.markdown, 'markdown', FEEDBACK_MARKDOWN_MAX_BYTES);
     validateFeedbackText(input.timestamp, 'timestamp', 40);
-    const envelope = {
+    const envelope = redactedEnvelope(input, options);
+    validateFeedbackEnvelope(envelope);
+    return envelope;
+}
+function redactedEnvelope(input, options) {
+    return {
         ...input,
         repositories: normalizeRepositories(input.repositories),
         markdown: redactFeedbackText(input.markdown, options.knownSensitiveValues),
@@ -116,6 +127,4 @@ export function createFeedbackEnvelope(input, options = {}) {
                 prs: input.prs.map((ref) => typeof ref === 'string' ? redactFeedbackText(ref, options.knownSensitiveValues) : ref),
             }),
     };
-    validateFeedbackEnvelope(envelope);
-    return envelope;
 }

package/dist/agent-blackboard/feedback-compose-audit.d.mts

@@ -0,0 +1,23 @@
+import type { AuditSourceInput } from './feedback-audit-source.mts';
+export type AuditCaps = {
+    ciBytes: number;
+    sandboxBytes: number;
+};
+type AuditInput = AuditSourceInput & {
+    knownSensitiveValues?: string[] | undefined;
+};
+/** Rendering attempts: measured shrinks, then every audit group omitted. */
+export declare const AUDIT_ATTEMPTS = 5;
+export declare const UNBOUNDED_CAPS: AuditCaps;
+/**
+ * Caps for the next attempt after an overflow, scaled by how much of the rendered audit markdown
+ * (`auditBytes`) must go. The last attempt allows nothing, leaving only omission notes.
+ */
+export declare function shrinkCaps(caps: AuditCaps, auditBytes: number, overflowBytes: number, last: boolean): AuditCaps;
+/**
+ * Audit source with redaction applied to raw field text (escaping first would defeat matching) and
+ * byte caps. A caller-supplied redactor runs first, then the built-in one; caller-supplied caps
+ * can only lower the computed ones.
+ */
+export declare function boundedAuditSource(input: AuditInput, caps: AuditCaps): AuditSourceInput;
+export {};

package/dist/agent-blackboard/feedback-compose-audit.mjs

@@ -0,0 +1,45 @@
+import { redactFeedbackText } from "./feedback-codec.mjs";
+const SHRINK_MARGIN_BYTES = 32;
+/** Rendering attempts: measured shrinks, then every audit group omitted. */
+export const AUDIT_ATTEMPTS = 5;
+export const UNBOUNDED_CAPS = { ciBytes: Infinity, sandboxBytes: Infinity };
+/**
+ * Caps for the next attempt after an overflow, scaled by how much of the rendered audit markdown
+ * (`auditBytes`) must go. The last attempt allows nothing, leaving only omission notes.
+ */
+export function shrinkCaps(caps, auditBytes, overflowBytes, last) {
+    if (last)
+        return { ciBytes: 0, sandboxBytes: 0 };
+    const keep = Math.max(0, auditBytes - overflowBytes - SHRINK_MARGIN_BYTES) / auditBytes;
+    const scale = (cap) => Math.floor(Math.min(cap, auditBytes) * keep);
+    return { ciBytes: scale(caps.ciBytes), sandboxBytes: scale(caps.sandboxBytes) };
+}
+/**
+ * Audit source with redaction applied to raw field text (escaping first would defeat matching) and
+ * byte caps. A caller-supplied redactor runs first, then the built-in one; caller-supplied caps
+ * can only lower the computed ones.
+ */
+export function boundedAuditSource(input, caps) {
+    const redactionFor = (caller) => (value) => redactFeedbackText(caller ? caller(value) : value, input.knownSensitiveValues);
+    const clamp = (caller) => ({
+        ciBytes: Math.min(caller?.ciBytes ?? Infinity, caps.ciBytes),
+        sandboxBytes: Math.min(caller?.sandboxBytes ?? Infinity, caps.sandboxBytes),
+    });
+    return input.friction
+        ? {
+            friction: {
+                ...input.friction,
+                redact: redactionFor(input.friction.redact),
+                budgets: clamp(input.friction.budgets),
+            },
+        }
+        : input.journal
+            ? {
+                journal: {
+                    ...input.journal,
+                    redact: redactionFor(input.journal.redact),
+                    budgets: clamp(input.journal.budgets),
+                },
+            }
+            : {};
+}

package/dist/agent-blackboard/feedback-compose.mjs

@@ -1,7 +1,8 @@
 import { runRetrospectiveFactsReport, } from "../retrospective-facts/index.mjs";
 import { runRetrospectiveTranscriptReport, } from "../retrospective-transcript/index.mjs";
-import { assertSingleAuditSource, auditAssessed, buildAuditReport, completeCoverageError, } from "./feedback-audit-source.mjs";
-import { createFeedbackEnvelope, redactFeedbackText } from "./feedback-codec.mjs";
+import { assertSingleAuditSource, auditAssessed, loadAuditInputs, renderAuditReport, completeCoverageError, } from "./feedback-audit-source.mjs";
+import { AUDIT_ATTEMPTS, boundedAuditSource, shrinkCaps, UNBOUNDED_CAPS, } from "./feedback-compose-audit.mjs";
+import { createFeedbackEnvelope, feedbackOverflowBytes, redactFeedbackText, } from "./feedback-codec.mjs";
 import { validateFeedbackText } from "./feedback-fields.mjs";
 function assessment(title, value) {
     if (!['findings', 'none-observed', 'not-assessed', 'unavailable'].includes(value.status))
@@ -45,25 +46,15 @@ export async function composeRetrospective(input) {
             coverage: input.transcript.status,
         }
         : undefined;
-    const [facts, transcript, audit] = await Promise.all([
+    const [facts, transcript] = await Promise.all([
         'status' in input.facts
             ? Promise.resolve(unavailableFacts)
             : runRetrospectiveFactsReport({ ...input.facts, raw: false }),
         'status' in input.transcript
             ? Promise.resolve(unavailableTranscript)
             : runRetrospectiveTranscriptReport(input.transcript),
-        buildAuditReport(input.sessionId, input),
     ]);
-    if (input.feedbackCoverage.status === 'complete' &&
-        (facts.coverage !== 'complete' ||
-            transcript.coverage !== 'complete' ||
-            ['not-assessed', 'unavailable'].includes(input.tools.status) ||
-            ['not-assessed', 'unavailable'].includes(input.architecture.status) ||
-            !auditAssessed(audit)))
-        throw completeCoverageError(input);
-    if ((audit.coverage.droppedCount ?? 0) > input.feedbackCoverage.droppedCount)
-        throw new Error('feedback coverage dropped count must include observed friction drops');
-    const markdown = [
+    const assemble = (auditMarkdown) => [
         '---',
         `date: ${JSON.stringify(input.date)}`,
         `issues: ${JSON.stringify(input.issues)}`,
@@ -78,11 +69,11 @@ export async function composeRetrospective(input) {
         `## Outcome\nWork outcome: ${input.workOutcome}\nFeedback coverage: ${input.feedbackCoverage.status}\nDropped records: ${input.feedbackCoverage.droppedCount}`,
         `## Verifiable Facts\n${facts.markdown.trim()}`,
         `## Transcript Facts\n${transcript.markdown.trim()}`,
-        audit.markdown,
+        auditMarkdown,
         assessment('Tool Findings', input.tools),
         assessment('Architecture Findings', input.architecture),
     ].join('\n\n');
-    const envelope = createFeedbackEnvelope({
+    const envelopeFor = (markdown) => ({
         schemaVersion: 1,
         type: 'retrospective',
         sourceEventId: 'composition-validation',
@@ -95,5 +86,28 @@ export async function composeRetrospective(input) {
         workOutcome: input.workOutcome,
         feedbackCoverage: input.feedbackCoverage,
     });
-    return envelope.markdown;
+    // The audit sections are the only unbounded ones: render them, measure the real envelope against
+    // its limits, and shrink the audit caps by the measured overflow until it fits.
+    const loaded = await loadAuditInputs(input.sessionId, input);
+    let caps = UNBOUNDED_CAPS;
+    let audit;
+    let markdown;
+    for (let attempt = 1;; attempt++) {
+        audit = renderAuditReport(input.sessionId, boundedAuditSource(input, caps), loaded);
+        markdown = assemble(audit.markdown);
+        const overflow = feedbackOverflowBytes(envelopeFor(markdown));
+        if (!overflow || attempt === AUDIT_ATTEMPTS)
+            break;
+        caps = shrinkCaps(caps, Buffer.byteLength(audit.markdown), overflow, attempt === AUDIT_ATTEMPTS - 1);
+    }
+    if (input.feedbackCoverage.status === 'complete' &&
+        (facts.coverage !== 'complete' ||
+            transcript.coverage !== 'complete' ||
+            ['not-assessed', 'unavailable'].includes(input.tools.status) ||
+            ['not-assessed', 'unavailable'].includes(input.architecture.status) ||
+            !auditAssessed(audit)))
+        throw completeCoverageError(input);
+    if ((audit.coverage.droppedCount ?? 0) > input.feedbackCoverage.droppedCount)
+        throw new Error('feedback coverage dropped count must include observed friction drops');
+    return createFeedbackEnvelope(envelopeFor(markdown)).markdown;
 }

package/dist/agent-blackboard/feedback-journal-audit.d.mts

@@ -1,6 +1,14 @@
+import { type JournalScan } from '../session-friction/journal.mts';
 import type { JournalLoader, SessionFrictionCoverage } from '../session-friction/types.mts';
 export type JournalAuditOptions = {
     journalLoader: JournalLoader;
+    /** Redacts raw field text before Markdown escaping, which would otherwise break matching. */
+    redact?: (value: string) => string;
+    /** Byte allowances for the CI and sandbox sections, as maximums over the built-in budgets. */
+    budgets?: {
+        ciBytes: number;
+        sandboxBytes: number;
+    };
 };
 /** `journal-only` says both sections were assessed from journal entries, with no log observed. */
 export type JournalAuditReport = {
@@ -17,4 +25,7 @@ export type JournalAuditReport = {
  * alone. Unlike `buildSessionFrictionReport`, a session with no journal is unavailable rather than
  * empty: without a log, nothing else establishes that the session was observed.
  */
+export declare function loadJournalAuditInput(sessionId: string, options: JournalAuditOptions): Promise<JournalScan>;
+/** Pure render of a loaded journal scan, so it can be repeated without reloading. */
+export declare function renderJournalAuditReport(sessionId: string, options: JournalAuditOptions, scanned: JournalScan): JournalAuditReport;
 export declare function buildJournalAuditReport(sessionId: string, options: JournalAuditOptions): Promise<JournalAuditReport>;

package/dist/agent-blackboard/feedback-journal-audit.mjs

@@ -13,17 +13,23 @@ function unavailable(reason) {
  * alone. Unlike `buildSessionFrictionReport`, a session with no journal is unavailable rather than
  * empty: without a log, nothing else establishes that the session was observed.
  */
-export async function buildJournalAuditReport(sessionId, options) {
+export async function loadJournalAuditInput(sessionId, options) {
     validateSessionId(sessionId);
-    const scanned = await scanJournal(sessionId, options.journalLoader);
+    return scanJournal(sessionId, options.journalLoader);
+}
+/** Pure render of a loaded journal scan, so it can be repeated without reloading. */
+export function renderJournalAuditReport(sessionId, options, scanned) {
     if (scanned.status === 'unreachable')
         return unavailable('blackboard unreachable');
     if (scanned.status === 'not-found')
         return unavailable('no journal for session');
-    const ci = getConformingGroups(scanned.entries);
-    const sandbox = getConformingSandboxBlocks(scanned.entries);
+    const ci = getConformingGroups(scanned.entries, options.redact, options.budgets?.ciBytes);
+    const sandbox = getConformingSandboxBlocks(scanned.entries, options.redact, options.budgets?.sandboxBytes);
     if (scanned.truncated)
         return report('partial', `${incompleteCiSection(ci)}\n\n${unavailableSandboxSection('journal scan incomplete', sandbox)}`);
     const journal = { status: 'ok', markdownBlocks: ci, truncated: false };
     return report('complete', `${buildCiFailuresSection(sessionId, journal, 'journal-only')}\n\n${journalSandboxSection(sandbox)}`);
 }
+export async function buildJournalAuditReport(sessionId, options) {
+    return renderJournalAuditReport(sessionId, options, await loadJournalAuditInput(sessionId, options));
+}

package/dist/agent-blackboard/feedback-journal-sandbox.d.mts

@@ -1,5 +1,6 @@
+import type { AuditRedactor } from '../session-friction/text.mts';
 import type { JournalEntry } from '../session-friction/types.mts';
 /** Journal entries that hold exactly one sandbox or permission block, made paste-safe. */
-export declare function getConformingSandboxBlocks(entries: Iterable<JournalEntry>): string[];
+export declare function getConformingSandboxBlocks(entries: Iterable<JournalEntry>, redact?: AuditRedactor, maxBytes?: number): string[];
 export declare function unavailableSandboxSection(reason: string, blocks?: string[]): string;
 export declare function journalSandboxSection(blocks: string[]): string;

package/dist/agent-blackboard/feedback-journal-sandbox.mjs

@@ -22,13 +22,31 @@ const FIELD_PREFIXES = [
     '  - Evidence: ',
     '  - Disposition: ',
 ];
-function matchBlock(markdown) {
-    return (matchAuditBlock(markdown, ESCALATION, FIELD_PREFIXES) ??
-        matchAuditBlock(markdown, FAILURE, FIELD_PREFIXES));
+const SANDBOX_BLOCKS_MAX_BYTES = 3_000;
+// Cut Disposition first, then the header detail, and Evidence last; Outcome is never cut.
+const ESCALATION_SHRINK_ORDER = [3, 0, 2];
+const FAILURE_SHRINK_ORDER = [2, 0, 1];
+function matchBlock(markdown, render) {
+    return (matchAuditBlock(markdown, ESCALATION, FIELD_PREFIXES, {
+        ...render,
+        shrinkOrder: ESCALATION_SHRINK_ORDER,
+    }) ??
+        matchAuditBlock(markdown, FAILURE, FIELD_PREFIXES, {
+            ...render,
+            shrinkOrder: FAILURE_SHRINK_ORDER,
+        }));
+}
+/** A conforming block that reports dropped blocks, so omission is never silent. */
+function omissionBlock(count) {
+    return [
+        `- \`ambiguous-failure\` — omitted — ${count} sandbox blocks omitted to fit the size limit; see journal`,
+        '  - Evidence: omitted blocks remain in the session journal',
+        '  - Disposition: see journal for the omitted blocks',
+    ].join('\n');
 }
 /** Journal entries that hold exactly one sandbox or permission block, made paste-safe. */
-export function getConformingSandboxBlocks(entries) {
-    return conformingBlocks(entries, matchBlock);
+export function getConformingSandboxBlocks(entries, redact, maxBytes = SANDBOX_BLOCKS_MAX_BYTES) {
+    return conformingBlocks(entries, matchBlock, Math.min(maxBytes, SANDBOX_BLOCKS_MAX_BYTES), redact, omissionBlock);
 }
 export function unavailableSandboxSection(reason, blocks = []) {
     return [`${SANDBOX_SECTION_HEADER}\nStatus: unavailable (${reason})`, ...blocks].join('\n\n');

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

@@ -1,4 +1,13 @@
 import type { JournalEntry } from './types.mts';
+import { type AuditRender } from './audit-fit.mts';
+import { type AuditRedactor } from './text.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[];
+export declare function matchAuditBlock(markdown: string, patterns: readonly RegExp[], prefixes: readonly string[], render: AuditRender & {
+    shrinkOrder: readonly number[];
+}): string | null;
+/**
+ * Matches every journal block whole while together they fit `totalBudgetBytes`. Otherwise it keeps
+ * the leading blocks that fit an equal share of the total and appends `omission(count)` — itself a
+ * conforming block — so dropped groups are always reported, never silent.
+ */
+export declare function conformingBlocks(entries: Iterable<JournalEntry>, match: (markdown: string, render: AuditRender) => string | null, totalBudgetBytes: number, redact: AuditRedactor | undefined, omission: (count: number) => string): string[];

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

@@ -1,12 +1,16 @@
-import { isWellFormedUnicode, markdownAuditText } from "./text.mjs";
+import { byteLength, fitFields, selectWithin } from "./audit-fit.mjs";
+import { isWellFormedUnicode, markdownAuditUnits } from "./text.mjs";
 const BLANK = /^\s*$/;
-function sanitizeField(line, prefixes) {
+// Below this a block would keep little beyond its field names, so it is omitted (and counted)
+// instead. This only ever drops groups; it never lets the section exceed its budget.
+const MIN_BLOCK_SHARE_BYTES = 300;
+function parseField(line, prefixes, redact) {
     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;
+        return null;
+    const units = markdownAuditUnits(line.slice(prefix.length), redact);
+    return units.length ? { prefix, units } : null;
 }
 // Consumes exactly one line per pattern (skipping blank lines between them) and nothing else.
 function matchLines(markdown, patterns) {
@@ -27,19 +31,30 @@ function matchLines(markdown, patterns) {
     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) {
+export function matchAuditBlock(markdown, patterns, prefixes, render) {
     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');
+    const parsed = fields.map((field) => parseField(field, prefixes, render.redact));
+    const safe = parsed.filter((field) => field !== null);
+    if (safe.length !== parsed.length)
+        return null;
+    const overhead = safe.reduce((sum, { prefix }) => sum + byteLength(prefix), safe.length - 1);
+    const contents = fitFields(safe.map(({ units }) => units), overhead, render.budgetBytes ?? Infinity, render.shrinkOrder);
+    return safe.map(({ prefix }, index) => `${prefix}${contents[index]}`).join('\n');
 }
-export function conformingBlocks(entries, match) {
-    return [...entries]
+/**
+ * Matches every journal block whole while together they fit `totalBudgetBytes`. Otherwise it keeps
+ * the leading blocks that fit an equal share of the total and appends `omission(count)` — itself a
+ * conforming block — so dropped groups are always reported, never silent.
+ */
+export function conformingBlocks(entries, match, totalBudgetBytes, redact, omission) {
+    const markdowns = [...entries]
         .flatMap((entry) => {
         const data = entry?.data;
         return data?.type === 'journal' && typeof data.markdown === 'string' ? [data.markdown] : [];
     })
-        .map(match)
-        .filter((block) => block !== null);
+        .filter((markdown) => match(markdown, { redact }) !== null);
+    const { rendered, omitted } = selectWithin(markdowns, totalBudgetBytes, byteLength(omission(markdowns.length)) + 2, 2, MIN_BLOCK_SHARE_BYTES, (markdown, budgetBytes) => match(markdown, { redact, budgetBytes }));
+    return omitted ? [...rendered, omission(omitted)] : rendered;
 }

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

@@ -0,0 +1,25 @@
+import { type AuditRedactor } from './text.mts';
+export type AuditRender = {
+    redact?: AuditRedactor | undefined;
+    budgetBytes?: number;
+    /** Field indexes that may be cut, least important first; other fields are never cut. */
+    shrinkOrder?: readonly number[];
+};
+export declare function byteLength(value: string): number;
+/**
+ * Renders fields whole while they fit in `budgetBytes` (minus the fixed `overheadBytes`). When they
+ * do not, only the `shrinkOrder` fields are cut, in that order, each down to at most a cut marker,
+ * and only at token boundaries. The result can still exceed the budget if the fields cannot shrink
+ * enough; callers check the size.
+ */
+export declare function fitFields(fields: string[][], overheadBytes: number, budgetBytes: number, shrinkOrder: readonly number[]): string[];
+/**
+ * Renders every item whole when together they fit `totalBytes`. Otherwise renders the largest
+ * leading run of items that each fit an equal share of what remains after `reserveBytes` (for the
+ * omission note), and reports how many were left out. Never renders more than the total allows.
+ * A share below `minShareBytes` would leave only stubs, so fewer items are kept instead.
+ */
+export declare function selectWithin<T>(items: T[], totalBytes: number, reserveBytes: number, separatorBytes: number, minShareBytes: number, render: (item: T, shareBytes: number) => string): {
+    rendered: string[];
+    omitted: number;
+};

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

@@ -0,0 +1,52 @@
+import { fitUnits } from "./text.mjs";
+const MIN_FIELD_BYTES = Buffer.byteLength('…');
+export function byteLength(value) {
+    return Buffer.byteLength(value);
+}
+/**
+ * Renders fields whole while they fit in `budgetBytes` (minus the fixed `overheadBytes`). When they
+ * do not, only the `shrinkOrder` fields are cut, in that order, each down to at most a cut marker,
+ * and only at token boundaries. The result can still exceed the budget if the fields cannot shrink
+ * enough; callers check the size.
+ */
+export function fitFields(fields, overheadBytes, budgetBytes, shrinkOrder) {
+    const sizes = fields.map((units) => byteLength(units.join('')));
+    let excess = sizes.reduce((sum, size) => sum + size, overheadBytes) - budgetBytes;
+    const caps = [...sizes];
+    for (const index of shrinkOrder) {
+        if (excess <= 0)
+            break;
+        const cut = Math.min(excess, Math.max(0, sizes[index] - MIN_FIELD_BYTES));
+        caps[index] = sizes[index] - cut;
+        excess -= cut;
+    }
+    return fields.map((units, index) => caps[index] === sizes[index] ? units.join('') : fitUnits(units, caps[index]));
+}
+/**
+ * Renders every item whole when together they fit `totalBytes`. Otherwise renders the largest
+ * leading run of items that each fit an equal share of what remains after `reserveBytes` (for the
+ * omission note), and reports how many were left out. Never renders more than the total allows.
+ * A share below `minShareBytes` would leave only stubs, so fewer items are kept instead.
+ */
+export function selectWithin(items, totalBytes, reserveBytes, separatorBytes, minShareBytes, render) {
+    const whole = items.map((item) => render(item, Infinity));
+    if (byteLength(whole.join('')) + separatorBytes * Math.max(0, whole.length - 1) <= totalBytes)
+        return { rendered: whole, omitted: 0 };
+    const available = totalBytes - reserveBytes;
+    const renderRun = (count) => {
+        const share = Math.floor((available - separatorBytes * (count - 1)) / count);
+        const rendered = items.slice(0, count).map((item) => render(item, share));
+        const fits = share >= minShareBytes && rendered.every((line) => byteLength(line) <= share);
+        return { rendered, fits };
+    };
+    let low = 0;
+    let high = items.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (renderRun(middle).fits)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return { rendered: low === 0 ? [] : renderRun(low).rendered, omitted: items.length - low };
+}

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

@@ -1,6 +1,7 @@
 import type { FrictionLogReadResult, JournalEntry } from './types.mts';
+import { type AuditRedactor } from './text.mts';
 export declare function isConformingCiFailureBlock(markdown: string): boolean;
-export declare function getConformingGroups(entries: Iterable<JournalEntry>): string[];
+export declare function getConformingGroups(entries: Iterable<JournalEntry>, redact?: AuditRedactor, maxBytes?: number): string[];
 export declare function incompleteCiSection(markdownBlocks: string[]): string;
 export declare function buildCiFailuresSection(sessionId: string, journal: {
     status: 'ok';

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

@@ -13,8 +13,22 @@ const FIELD_PREFIXES = [
     '  - Root diagnostic: ',
     '  - Disposition: ',
 ];
-function matchBlock(markdown) {
-    return matchAuditBlock(markdown, [GROUP_HEADER, EVIDENCE, ROOT_DIAGNOSTIC, DISPOSITION], FIELD_PREFIXES);
+const CI_SECTION_MAX_BYTES = 4_000;
+// Field order: header, Evidence, Root diagnostic, Disposition. Cut Root diagnostic first and
+// Evidence last, so the run URL and commit SHA survive longest.
+const SHRINK_ORDER = [2, 3, 0, 1];
+const SESSION_ID_MAX_BYTES = 120;
+function matchBlock(markdown, render = {}) {
+    return matchAuditBlock(markdown, [GROUP_HEADER, EVIDENCE, ROOT_DIAGNOSTIC, DISPOSITION], FIELD_PREFIXES, { ...render, shrinkOrder: SHRINK_ORDER });
+}
+/** A conforming group that reports dropped groups, so omission is never silent. */
+function omissionGroup(count) {
+    return [
+        `- \`one-off\` — \`GitHub Actions\` — ${count} further failure groups omitted to fit the size limit; see journal`,
+        '  - Evidence: omitted groups remain in the session journal',
+        '  - Root diagnostic: omitted to fit the retrospective size limit',
+        '  - Disposition: see journal for the omitted failure groups',
+    ].join('\n');
 }
 export function isConformingCiFailureBlock(markdown) {
     if (markdown.length > CI_FAILURE_BLOCK_MAX_BYTES ||
@@ -22,8 +36,8 @@ export function isConformingCiFailureBlock(markdown) {
         return false;
     return matchBlock(markdown) !== null;
 }
-export function getConformingGroups(entries) {
-    return conformingBlocks(entries, matchBlock);
+export function getConformingGroups(entries, redact, maxBytes = CI_SECTION_MAX_BYTES) {
+    return conformingBlocks(entries, matchBlock, Math.min(maxBytes, CI_SECTION_MAX_BYTES), redact, omissionGroup);
 }
 export function incompleteCiSection(markdownBlocks) {
     return [
@@ -35,7 +49,7 @@ export function buildCiFailuresSection(sessionId, journal, frictionStatus) {
     if (journal.status === 'unreachable')
         return `${CI_FAILURES_HEADER}\nStatus: unavailable (blackboard unreachable)`;
     if (journal.markdownBlocks.length === 0 && frictionStatus === 'absent')
-        return `${CI_FAILURES_HEADER}\nStatus: unavailable (no friction log for session ${markdownAuditText(sessionId)})`;
+        return `${CI_FAILURES_HEADER}\nStatus: unavailable (no friction log for session ${markdownAuditText(sessionId, undefined, SESSION_ID_MAX_BYTES)})`;
     if (journal.markdownBlocks.length === 0)
         return `${CI_FAILURES_HEADER}\nStatus: none observed`;
     return `${CI_FAILURES_HEADER}\nStatus: failures observed\n\n${journal.markdownBlocks.join('\n\n')}`;

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

@@ -1,6 +1,6 @@
 export { classifyFrictionObservation } from './classify.mts';
 export { normalizeCommandPrefix } from './normalize.mts';
 export { FRICTION_LOG_MAX_EVENTS, readFrictionLog, recordFriction } from './log.mts';
-export { buildSessionFrictionReport } from './report.mts';
+export { buildSessionFrictionReport, loadFrictionReportInputs, renderFrictionReport, type FrictionReportInputs, } from './report.mts';
 export { isConformingCiFailureBlock } from './ci-failures.mts';
 export type { FrictionEvent, FrictionEventKind, FrictionLogOptions, FrictionLogReadResult, FrictionObservation, JournalEntry, JournalLoadResult, JournalLoader, PermissionRequestObservation, SessionFrictionReport, SessionFrictionCoverage, SessionFrictionReportOptions, ToolResultObservation, } from './types.mts';

package/dist/session-friction/index.mjs

@@ -1,5 +1,5 @@
 export { classifyFrictionObservation } from "./classify.mjs";
 export { normalizeCommandPrefix } from "./normalize.mjs";
 export { FRICTION_LOG_MAX_EVENTS, readFrictionLog, recordFriction } from "./log.mjs";
-export { buildSessionFrictionReport } from "./report.mjs";
+export { buildSessionFrictionReport, loadFrictionReportInputs, renderFrictionReport, } from "./report.mjs";
 export { isConformingCiFailureBlock } from "./ci-failures.mjs";

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

@@ -1,2 +1,16 @@
-import type { SessionFrictionReport, SessionFrictionReportOptions } from './types.mts';
+import { type JournalScan } from './journal.mts';
+import type { FrictionLogReadResult, SessionFrictionReport, SessionFrictionReportOptions } from './types.mts';
+type FrictionRead = {
+    result: FrictionLogReadResult;
+} | {
+    error: unknown;
+};
+/** Everything a report reads from outside, loaded once so rendering can be repeated for free. */
+export type FrictionReportInputs = {
+    scanned: JournalScan;
+    read: FrictionRead;
+};
+export declare function loadFrictionReportInputs(sessionId: string, options: SessionFrictionReportOptions): Promise<FrictionReportInputs>;
+export declare function renderFrictionReport(sessionId: string, options: SessionFrictionReportOptions, { scanned, read }: FrictionReportInputs): SessionFrictionReport;
 export declare function buildSessionFrictionReport(sessionId: string, options: SessionFrictionReportOptions): Promise<SessionFrictionReport>;
+export {};

package/dist/session-friction/report.mjs

@@ -3,17 +3,17 @@ import { buildCiFailuresSection, getConformingGroups, incompleteCiSection } from
 import { errorMessage, scanJournal } from "./journal.mjs";
 import { buildSandboxSection } from "./sandbox.mjs";
 import { validateSessionId } from "./session-id.mjs";
-function sandboxMarkdown(friction) {
+function sandboxMarkdown(friction, options) {
     if (friction.status === 'events')
-        return `${friction.truncated ? `## Capture Coverage\nStatus: partial\nDropped records: ${friction.droppedCount}\n\n` : ''}${buildSandboxSection(friction.events)}`;
+        return `${friction.truncated ? `## Capture Coverage\nStatus: partial\nDropped records: ${friction.droppedCount}\n\n` : ''}${buildSandboxSection(friction.events, options.redact, options.budgets?.sandboxBytes)}`;
     if (friction.status === 'empty' && friction.truncated)
         return `## Sandbox & Permission Audit\nStatus: unavailable (partial capture; dropped ${friction.droppedCount} records)`;
     const status = friction.status === 'empty' ? 'none observed' : 'unavailable (no friction log)';
     return `## Sandbox & Permission Audit\nStatus: ${status}`;
 }
-function reportFromLog(sessionId, logOptions, journal) {
-    try {
-        const friction = readFrictionLog(sessionId, logOptions);
+function reportFromLog(sessionId, logOptions, journal, read) {
+    if ('result' in read) {
+        const friction = read.result;
         const coverage = {
             journalStatus: journal.status === 'unreachable'
                 ? 'unavailable'
@@ -27,12 +27,14 @@ function reportFromLog(sessionId, logOptions, journal) {
         if (journal.status === 'ok' && journal.truncated)
             return {
                 coverage,
-                markdown: incompleteCiSection(journal.markdownBlocks) + '\n\n' + sandboxMarkdown(friction),
+                markdown: incompleteCiSection(journal.markdownBlocks) +
+                    '\n\n' +
+                    sandboxMarkdown(friction, logOptions),
             };
         const markdown = buildCiFailuresSection(sessionId, journal, friction.status);
-        return { coverage, markdown: `${markdown}\n\n${sandboxMarkdown(friction)}` };
+        return { coverage, markdown: `${markdown}\n\n${sandboxMarkdown(friction, logOptions)}` };
     }
-    catch (error) {
+    else {
         const ciMarkdown = journal.status === 'ok' && journal.truncated
             ? incompleteCiSection(journal.markdownBlocks)
             : journal.status === 'ok' && journal.markdownBlocks.length === 0
@@ -49,25 +51,33 @@ function reportFromLog(sessionId, logOptions, journal) {
                 truncated: true,
             },
             markdown: `${ciMarkdown}\n\n## Sandbox & Permission Audit\nStatus: unavailable (friction log unreadable)`,
-            diagnostic: errorMessage(error),
+            diagnostic: errorMessage(read.error),
         };
     }
 }
-export async function buildSessionFrictionReport(sessionId, options) {
+export async function loadFrictionReportInputs(sessionId, options) {
     validateSessionId(sessionId);
     requireDirectory(options.directory);
     eventLimit(options.maxEvents);
     const scanned = await scanJournal(sessionId, options.journalLoader);
+    try {
+        return { scanned, read: { result: readFrictionLog(sessionId, options) } };
+    }
+    catch (error) {
+        return { scanned, read: { error } };
+    }
+}
+export function renderFrictionReport(sessionId, options, { scanned, read }) {
     const journal = scanned.status === 'unreachable'
         ? scanned
         : scanned.status === 'not-found'
             ? { status: 'ok', markdownBlocks: [], truncated: false }
             : {
                 status: 'ok',
-                markdownBlocks: getConformingGroups(scanned.entries),
+                markdownBlocks: getConformingGroups(scanned.entries, options.redact, options.budgets?.ciBytes),
                 truncated: scanned.truncated,
             };
-    const report = reportFromLog(sessionId, options, journal);
+    const report = reportFromLog(sessionId, options, journal, read);
     if (journal.status === 'unreachable') {
         const diagnostic = report.diagnostic
             ? `${journal.diagnostic}; ${report.diagnostic}`
@@ -76,3 +86,6 @@ export async function buildSessionFrictionReport(sessionId, options) {
     }
     return report;
 }
+export async function buildSessionFrictionReport(sessionId, options) {
+    return renderFrictionReport(sessionId, options, await loadFrictionReportInputs(sessionId, options));
+}

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

@@ -1,2 +1,3 @@
 import type { FrictionEvent } from './types.mts';
-export declare function buildSandboxSection(events: FrictionEvent[]): string;
+import { type AuditRedactor } from './text.mts';
+export declare function buildSandboxSection(events: FrictionEvent[], redact?: AuditRedactor, maxBytes?: number): string;

package/dist/session-friction/sandbox.mjs

@@ -1,22 +1,43 @@
-import { markdownAuditText } from "./text.mjs";
+import { byteLength, fitFields, selectWithin } from "./audit-fit.mjs";
+import { markdownAuditUnits } from "./text.mjs";
 const SANDBOX_SECTION_HEADER = '## Sandbox & Permission Audit';
+const SANDBOX_SECTION_MAX_BYTES = 3_000;
+// Room for the `- kind (n)` group lines, which are rendered outside the per-event budget.
+const GROUP_LINES_BYTES = 120;
+// Below this an event line would keep little beyond its timestamp, so it is omitted and counted.
+const MIN_EVENT_SHARE_BYTES = 120;
+// Event line fields: command prefix, detail, timestamp. Cut detail first, the timestamp never.
+const SHRINK_ORDER = [1, 0];
 const KIND_ORDER = [
     'sandbox-escalation',
     'sandbox-failure',
     'ambiguous-failure',
 ];
-export function buildSandboxSection(events) {
+/** Reports dropped events as a group in the same shape as the rest, so omission is never silent. */
+function omissionGroup(count) {
+    return `- omitted (${count})\n  - see journal — ${count} events omitted to fit the size limit — n/a`;
+}
+export function buildSandboxSection(events, redact, maxBytes = SANDBOX_SECTION_MAX_BYTES) {
     const observations = events.flatMap((event) => event.failure
         ? [event, { ...event, kind: event.failure.kind, detail: event.failure.detail }]
         : [event]);
+    const render = (event, budgetBytes) => {
+        const outcome = event.kind === 'sandbox-escalation' ? ` — outcome: ${event.outcome ?? 'unknown'}` : '';
+        const [prefix, detail, timestamp] = fitFields([event.commandPrefix, event.detail, event.timestamp].map((field) => markdownAuditUnits(field, redact)), byteLength(`  -  —  — ${outcome}`), budgetBytes, SHRINK_ORDER);
+        return `  - ${prefix} — ${detail} — ${timestamp}${outcome}`;
+    };
+    const total = Math.max(0, Math.min(maxBytes, SANDBOX_SECTION_MAX_BYTES) - GROUP_LINES_BYTES);
+    const { rendered, omitted } = selectWithin(observations, total, byteLength(omissionGroup(observations.length)) + 1, 1, MIN_EVENT_SHARE_BYTES, render);
+    const kept = observations
+        .slice(0, rendered.length)
+        .map((event, i) => ({ event, line: rendered[i] }));
     const groups = KIND_ORDER.map((kind) => {
-        const selected = observations.filter((event) => event.kind === kind);
+        const selected = kept.filter(({ event }) => event.kind === kind);
         return selected.length
-            ? [
-                `- ${kind} (${selected.length})`,
-                ...selected.map((event) => `  - ${markdownAuditText(event.commandPrefix)} — ${markdownAuditText(event.detail)} — ${markdownAuditText(event.timestamp)}${event.kind === 'sandbox-escalation' ? ` — outcome: ${event.outcome ?? 'unknown'}` : ''}`),
-            ].join('\n')
+            ? [`- ${kind} (${selected.length})`, ...selected.map(({ line }) => line)].join('\n')
             : undefined;
     }).filter((group) => group !== undefined);
+    if (omitted)
+        groups.push(omissionGroup(omitted));
     return `${SANDBOX_SECTION_HEADER}\nEvents observed: ${observations.length}\n\n${groups.join('\n')}`;
 }

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

@@ -2,4 +2,17 @@ export declare function normalizeAuditText(value: string): string;
 export declare function boundedText(value: string, maximum: number): string;
 export declare function isWellFormedUnicode(value: string): boolean;
 export declare function isSafeAuditText(value: unknown): value is string;
-export declare function markdownAuditText(value: string): string;
+export type AuditRedactor = (value: string) => string;
+/**
+ * Splits a field into atomic Markdown-escaped units (one code point, plus its backslash when
+ * escaped), so a later cut can never land inside an escape sequence. Redaction runs on the raw
+ * text first: escaping inserts backslashes that would otherwise break secret and token matching.
+ * normalizeAuditText trims and escaping adds no whitespace, so the result has none at its edges.
+ */
+export declare function markdownAuditUnits(value: string, redact?: AuditRedactor): string[];
+/**
+ * Joins escaped units whole, or, when over `maxBytes`, keeps only complete whitespace-separated
+ * tokens (so URLs and SHAs are never split) and marks the cut. Never ends in whitespace.
+ */
+export declare function fitUnits(units: string[], maxBytes: number, atTokens?: boolean): string;
+export declare function markdownAuditText(value: string, redact?: AuditRedactor, maxBytes?: number): string;

package/dist/session-friction/text.mjs

@@ -1,6 +1,5 @@
 const CONTROL_CHARACTERS = /[\p{Cc}\p{Cf}]+/gu;
 const MARKDOWN_CHARACTER = /\\|`|\*|_|~|\[|\]|<|>|#|-|\+|!|\||&/;
-const MARKDOWN_AUDIT_MAX_LENGTH = 120;
 export function normalizeAuditText(value) {
     return value.replace(CONTROL_CHARACTERS, ' ').trim();
 }
@@ -32,14 +31,40 @@ export function isSafeAuditText(value) {
         isWellFormedUnicode(value) &&
         value === normalizeAuditText(value));
 }
-export function markdownAuditText(value) {
-    // Escaping is atomic, so the result may be shorter than the maximum.
-    let result = '';
-    for (const character of normalizeAuditText(value)) {
-        const escaped = MARKDOWN_CHARACTER.test(character) ? `\\${character}` : character;
-        if (result.length + escaped.length > MARKDOWN_AUDIT_MAX_LENGTH)
+/**
+ * Splits a field into atomic Markdown-escaped units (one code point, plus its backslash when
+ * escaped), so a later cut can never land inside an escape sequence. Redaction runs on the raw
+ * text first: escaping inserts backslashes that would otherwise break secret and token matching.
+ * normalizeAuditText trims and escaping adds no whitespace, so the result has none at its edges.
+ */
+export function markdownAuditUnits(value, redact) {
+    const raw = normalizeAuditText(value);
+    return Array.from(redact ? normalizeAuditText(redact(raw)) : raw).map((character) => MARKDOWN_CHARACTER.test(character) ? `\\${character}` : character);
+}
+const CUT_MARKER = '…';
+const WHITESPACE = /^\s$/u;
+/**
+ * Joins escaped units whole, or, when over `maxBytes`, keeps only complete whitespace-separated
+ * tokens (so URLs and SHAs are never split) and marks the cut. Never ends in whitespace.
+ */
+export function fitUnits(units, maxBytes, atTokens = true) {
+    const whole = units.join('');
+    if (Buffer.byteLength(whole) <= maxBytes)
+        return whole;
+    const room = maxBytes - Buffer.byteLength(` ${CUT_MARKER}`);
+    let used = 0;
+    let boundary = 0;
+    for (const [index, unit] of units.entries()) {
+        used += Buffer.byteLength(unit);
+        if (used > room)
             break;
-        result += escaped;
+        if (!atTokens || WHITESPACE.test(unit))
+            boundary = atTokens ? index : index + 1;
     }
-    return result;
+    const kept = units.slice(0, boundary).join('').trimEnd();
+    return kept ? `${kept}${atTokens ? ' ' : ''}${CUT_MARKER}` : CUT_MARKER;
+}
+export function markdownAuditText(value, redact, maxBytes = Infinity) {
+    // Used for identifiers, which have no token boundaries to cut at.
+    return fitUnits(markdownAuditUnits(value, redact), maxBytes, false);
 }

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

@@ -69,5 +69,12 @@ export type SessionFrictionReport = {
 };
 export type SessionFrictionReportOptions = FrictionLogOptions & {
     journalLoader: JournalLoader;
+    /** Redacts raw field text before Markdown escaping, which would otherwise break matching. */
+    redact?: (value: string) => string;
+    /** Byte allowances for the CI and sandbox sections, as maximums over the built-in budgets. */
+    budgets?: {
+        ciBytes: number;
+        sandboxBytes: number;
+    };
 };
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.36.2",
+  "version": "0.37.1",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {