vouchington-tooling 0.37.0 → 0.37.2

package/README.md

@@ -89,6 +89,22 @@ vouchington post-review
 vouchington stage-review-payload optional|required <source> <destination>
 ```
 
+### Running `allocate-browser-safe-ports` without an install
+
+The allocator is a standalone Python script that needs only the Python 3 standard library: no
+Node, no `pnpm install`. Run it from the extracted published tarball:
+
+```bash
+npm pack vouchington-tooling@<version>   # or download the registry .tgz
+mkdir extracted && tar -xzf vouchington-tooling-<version>.tgz -C extracted
+python3 extracted/package/scripts/allocate-browser-safe-ports.py <count> [--policy ...] [--forbidden-ports ...]
+```
+
+`pnpm dlx` and `npx` resolve the package's whole dependency tree, which can fail under
+`minimumReleaseAge` (`ERR_PNPM_NO_MATURE_MATCHING_VERSION`) when a lockstep-published dependency
+straddles the cutoff. CI jobs without an install should fetch the tarball instead. Tests enforce
+that the script stays stdlib-only and reads only its two sibling JSON files.
+
 For persistent `pnpm-install`, v5 metadata tracks structural inputs separately from the
 `--install-scripts` policy. A warm scripts-enabled tree can therefore toggle
 `true → false → true` without forced reconciliation; a tree first installed with scripts disabled
@@ -216,6 +232,7 @@ import {
   installFakeGit,
   runNamedChecks,
 } from 'vouchington-tooling/shared-context'
+import { createSourceModuleGraph } from 'vouchington-tooling/source-module-graph'
 import {
   decodeSelectedFiles,
   writeSelectedFilesOutput,
@@ -439,7 +456,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
@@ -657,6 +674,18 @@ TypeScript and route rows from Markdown. Callers configure declaration names and
 runbook headings, then compare the returned data using their own route policy.
 See the [API contract](docs/basic-auth-doc-sync.md).
 
+## TypeScript source graph
+
+`vouchington-tooling/source-module-graph` exports `createSourceModuleGraph`. It accepts the
+`modules` report from released no-mistakes
+`analyzeTypeScriptModules({ root, files })`, plus the caller's root, ordered source extensions,
+aliases, and file inventory. It resolves local imports and reexport owners without reading or
+parsing source again. `runtimeImports(file)` uses binding references rather than declaration
+presence, and `reachableFrom(entrypoints, { runtimeOnly: true })` follows used runtime imports,
+reexports, and literal dynamic/require loads. Missing or incomplete facts for a reached file
+throw; external specifiers resolve to `null`. The default file inventory limit is 10,000
+files and can be reduced with `maxFiles`.
+
 ## SQL view declarations
 
 `vouchington-tooling/sql-ast` exports `extractViewDeclarations(sql)` and the

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';