vouchington-tooling 0.22.1 → 0.24.0

package/dist/retrospective-transcript/index.mjs

@@ -12,6 +12,12 @@ export { codexChildren, codexIdentity } from './codex.mjs';
 export { formatTranscriptFacts, formatUnavailable } from './format.mjs';
 export { resolveTranscriptFile } from './resolve-transcript-file.mjs';
 const MALFORMED_INTERIOR = 'malformed interior transcript record';
+function partialCapture(lines) {
+    return parseLines(lines).length !== lines.filter((line) => line.trim()).length;
+}
+function unavailable(reason) {
+    return { markdown: formatUnavailable(reason), coverage: 'unavailable' };
+}
 function schema(lines) {
     const records = parseLines(lines);
     const kinds = new Set(records
@@ -74,7 +80,7 @@ async function codexSubagents(lines, sessionsDir, ownerPath, visited = new Set()
         const segment = segmentCodex(child);
         if (!segment)
             return undefined;
-        result.push(segment);
+        result.push({ ...segment, partial: partialCapture(child) });
         const nested = await codexSubagents(segment.lines, sessionsDir, edge.agentPath, visited);
         if (!nested)
             return undefined;
@@ -83,31 +89,45 @@ async function codexSubagents(lines, sessionsDir, ownerPath, visited = new Set()
     return result;
 }
 export async function runRetrospectiveTranscript(options) {
+    return (await runRetrospectiveTranscriptReport(options)).markdown;
+}
+export async function runRetrospectiveTranscriptReport(options) {
     const resolved = resolveTranscriptFile(options);
     if ('error' in resolved)
-        return formatUnavailable(resolved.error);
+        return unavailable(resolved.error);
     const lines = await readLines(resolved.path);
     if (!lines)
-        return formatUnavailable('could not read transcript');
+        return unavailable('could not read transcript');
     const detected = schema(lines);
     if (!detected)
-        return formatUnavailable('unsupported or mixed transcript schema');
+        return unavailable('unsupported or mixed transcript schema');
     if (hasMalformedInteriorRecord(lines))
-        return formatUnavailable(MALFORMED_INTERIOR);
+        return unavailable(MALFORMED_INTERIOR);
     if (detected === 'claude') {
         const directory = join(dirname(resolved.path), basename(resolved.path, '.jsonl'), 'subagents');
         const subagents = await Promise.all(globFrom(directory, '*.jsonl').sort().map(readLines));
-        return formatTranscriptFacts(resolved.sessionId, computeTranscriptFacts(lines, subagents.filter((value) => value !== undefined && schema(value) === 'claude' && !hasMalformedInteriorRecord(value))));
+        const valid = subagents.filter((value) => value !== undefined && schema(value) === 'claude' && !hasMalformedInteriorRecord(value));
+        return {
+            markdown: formatTranscriptFacts(resolved.sessionId, computeTranscriptFacts(lines, valid)),
+            coverage: valid.length === subagents.length && !partialCapture(lines) && !valid.some(partialCapture)
+                ? 'complete'
+                : 'partial',
+        };
     }
     const identity = codexIdentity(lines);
     const root = segmentCodex(lines);
     if (!root)
-        return formatUnavailable('could not segment Codex transcript');
+        return unavailable('could not segment Codex transcript');
     const codexHome = (options.env ?? process.env).CODEX_HOME;
     const subagents = await codexSubagents(root.lines, options.codexSessionsDir ??
         (options.jsonlPath ? dirname(resolved.path) : undefined) ??
         join(codexHome || join(homedir(), '.codex'), 'sessions'), identity.agentPath, new Set([identity.threadId ?? resolved.sessionId].filter((threadId) => SESSION_ID.test(threadId))));
     if (!subagents)
-        return formatUnavailable('could not resolve a referenced Codex child transcript');
-    return formatTranscriptFacts(resolved.sessionId, computeCodex(root.lines, subagents, root.baseline));
+        return unavailable('could not resolve a referenced Codex child transcript');
+    return {
+        markdown: formatTranscriptFacts(resolved.sessionId, computeCodex(root.lines, subagents, root.baseline)),
+        coverage: partialCapture(lines) || subagents.some((segment) => segment.partial)
+            ? 'partial'
+            : 'complete',
+    };
 }

package/dist/session-friction/classify.mjs

@@ -47,7 +47,12 @@ export function classifyFrictionObservation(observation) {
     if (commandPrefix === '' || !isWellFormedUnicode(commandPrefix))
         return null;
     if (observation.type === 'permission-request') {
-        return { kind: 'sandbox-escalation', commandPrefix, detail: 'permission-request' };
+        return {
+            kind: 'sandbox-escalation',
+            commandPrefix,
+            detail: 'permission-request',
+            outcome: 'requested',
+        };
     }
     if (observation.type !== 'tool-result')
         return null;
@@ -57,31 +62,37 @@ export function classifyFrictionObservation(observation) {
     const escalationDetail = normalizeAuditText(boundedText(observation.escalationDetail ?? '', DETAIL_MAX_LENGTH));
     if (!isWellFormedUnicode(escalationDetail))
         return null;
-    if (escalationDetail) {
-        return {
+    if (observation.permissionOutcome !== undefined &&
+        !['approved', 'denied'].includes(observation.permissionOutcome))
+        return null;
+    const permission = escalationDetail || observation.permissionOutcome
+        ? {
             kind: 'sandbox-escalation',
             commandPrefix,
-            detail: escalationDetail,
-        };
-    }
+            detail: escalationDetail || `permission-${observation.permissionOutcome}`,
+            outcome: observation.permissionOutcome ?? 'unknown',
+        }
+        : null;
     const rawStderr = observation.structuredStderr;
     if (rawStderr !== undefined && (typeof rawStderr !== 'string' || !isWellFormedUnicode(rawStderr)))
         return null;
     const stderr = rawStderr ? boundedStderr(rawStderr) : rawStderr;
     if (stderr === undefined)
-        return null;
+        return permission;
     const token = FAILURE_TOKENS.find(([, pattern]) => pattern.test(stderr))?.[0];
-    if (token)
-        return { kind: 'sandbox-failure', commandPrefix, detail: `stderr matched "${token}"` };
+    if (token) {
+        const failure = { kind: 'sandbox-failure', detail: `stderr matched "${token}"` };
+        return permission ? { ...permission, failure } : { ...failure, commandPrefix };
+    }
     if (stderr.split(/\r\n|[\r\n]/).some((rawLine) => {
         const line = withoutUrlUserinfo(rawLine);
         return (CONNECTION_REFUSED.test(line) && LOOPBACK_ADDRESSES.some((pattern) => pattern.test(line)));
     })) {
-        return {
-            kind: 'sandbox-failure',
-            commandPrefix,
-            detail: 'stderr matched localhost connection failure',
+        const failure = {
+            kind: 'ambiguous-failure',
+            detail: 'localhost connection refused; sandbox cause unverified',
         };
+        return permission ? { ...permission, failure } : { ...failure, commandPrefix };
     }
-    return null;
+    return permission;
 }

package/dist/session-friction/coverage-ledger.d.mts

@@ -0,0 +1,10 @@
+export type CoverageLedger = {
+    schemaVersion: 1;
+    retainedEvents: number;
+    logBytes: number;
+    droppedCount: number;
+};
+/** Caller holds the event log lock; incomplete atomic updates must never imply complete capture. */
+export declare function readCoverageLedger(path: string): CoverageLedger | undefined;
+/** The fixed-size atomic sidecar keeps saturation work independent of the accumulated drop count. */
+export declare function writeCoverageLedger(path: string, ledger: CoverageLedger): void;

package/dist/session-friction/coverage-ledger.mjs

@@ -0,0 +1,75 @@
+import { closeSync, constants, fsyncSync, lstatSync, openSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { openLogFile, readLogContent, writeAll, LOG_MAX_BYTES } from './log-file.mjs';
+const LEDGER_MAX_BYTES = 192;
+function missing(error) {
+    return !!error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
+}
+/** Caller holds the event log lock; incomplete atomic updates must never imply complete capture. */
+export function readCoverageLedger(path) {
+    try {
+        lstatSync(`${path}.coverage.pending`);
+        throw new Error('session-friction coverage update is incomplete');
+    }
+    catch (error) {
+        if (!missing(error))
+            throw error;
+    }
+    let descriptor;
+    try {
+        descriptor = openLogFile(`${path}.coverage`, constants.O_RDONLY);
+    }
+    catch (error) {
+        if (missing(error))
+            return undefined;
+        throw error;
+    }
+    try {
+        const value = JSON.parse(readLogContent(descriptor, LEDGER_MAX_BYTES));
+        if (!value || typeof value !== 'object')
+            throw new Error('invalid session-friction coverage ledger');
+        // oxlint-disable-next-line no-mistakes/ts-no-const-aliases -- establish a validated object view
+        const item = value;
+        if (Object.keys(item).length !== 4 ||
+            item.schemaVersion !== 1 ||
+            !Number.isSafeInteger(item.retainedEvents) ||
+            item.retainedEvents < 0 ||
+            item.retainedEvents > 500 ||
+            !Number.isSafeInteger(item.logBytes) ||
+            item.logBytes < 0 ||
+            item.logBytes > LOG_MAX_BYTES ||
+            !Number.isSafeInteger(item.droppedCount) ||
+            item.droppedCount < 1)
+            throw new Error('invalid session-friction coverage ledger');
+        return item;
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+/** The fixed-size atomic sidecar keeps saturation work independent of the accumulated drop count. */
+export function writeCoverageLedger(path, ledger) {
+    if (!Number.isSafeInteger(ledger.droppedCount))
+        throw new Error('session-friction dropped count overflow; capture incomplete');
+    const temporary = `${path}.coverage.pending`;
+    const descriptor = openSync(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+    try {
+        syncDirectory(path);
+        writeAll(descriptor, JSON.stringify(ledger));
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    renameSync(temporary, `${path}.coverage`);
+    syncDirectory(path);
+}
+function syncDirectory(path) {
+    const descriptor = openSync(dirname(path), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}

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

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

package/dist/session-friction/log-file.d.mts

@@ -2,6 +2,6 @@ import type { FrictionEvent } from './types.mts';
 export declare const LOG_MAX_BYTES = 2000000;
 export declare function validEvent(value: unknown): value is FrictionEvent;
 export declare function openLogFile(path: string, flags: number): number;
-export declare function readLogContent(descriptor: number): string;
-export declare function atEventLimit(content: string, limit: number): boolean;
+export declare function readLogContent(descriptor: number, maximumBytes?: number): string;
+export declare function validEventCount(content: string, limit: number): number;
 export declare function writeAll(descriptor: number, value: string): void;

package/dist/session-friction/log-file.mjs

@@ -7,10 +7,25 @@ export function validEvent(value) {
         return false;
     // oxlint-disable-next-line no-mistakes/ts-no-const-aliases -- establish a record view after the runtime object check
     const record = value;
-    return ((record.kind === 'sandbox-escalation' || record.kind === 'sandbox-failure') &&
+    return ((record.kind === 'sandbox-escalation' ||
+        record.kind === 'sandbox-failure' ||
+        record.kind === 'ambiguous-failure') &&
         isSafeAuditText(record.timestamp) &&
         isSafeAuditText(record.commandPrefix) &&
-        isSafeAuditText(record.detail));
+        isSafeAuditText(record.detail) &&
+        (record.failure === undefined || validFailure(record.failure)) &&
+        (record.outcome === undefined ||
+            (typeof record.outcome === 'string' &&
+                ['requested', 'approved', 'denied', 'unknown'].includes(record.outcome))));
+}
+function validFailure(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    // oxlint-disable-next-line no-mistakes/ts-no-const-aliases -- establish a validated object view
+    const failure = value;
+    return (Object.keys(failure).length === 2 &&
+        (failure.kind === 'sandbox-failure' || failure.kind === 'ambiguous-failure') &&
+        isSafeAuditText(failure.detail));
 }
 export function openLogFile(path, flags) {
     let descriptor;
@@ -36,10 +51,10 @@ export function openLogFile(path, flags) {
         throw error;
     }
 }
-export function readLogContent(descriptor) {
-    if (fstatSync(descriptor).size > LOG_MAX_BYTES)
+export function readLogContent(descriptor, maximumBytes = LOG_MAX_BYTES) {
+    if (fstatSync(descriptor).size > maximumBytes)
         throw new Error('session-friction log is too large');
-    const buffer = Buffer.alloc(LOG_MAX_BYTES + 1);
+    const buffer = Buffer.alloc(maximumBytes + 1);
     let length = 0;
     while (length < buffer.length) {
         const bytes = readSync(descriptor, buffer, length, buffer.length - length, length);
@@ -48,11 +63,11 @@ export function readLogContent(descriptor) {
         length += bytes;
     }
     /* v8 ignore next -- detects external growth after the descriptor size check. */
-    if (length > LOG_MAX_BYTES)
+    if (length > maximumBytes)
         throw new Error('session-friction log is too large');
     return decodeUtf8(buffer.subarray(0, length));
 }
-function validEventCount(content, limit) {
+export function validEventCount(content, limit) {
     let count = 0;
     for (const line of content.split('\n')) {
         if (!line.trim())
@@ -67,9 +82,6 @@ function validEventCount(content, limit) {
     }
     return count;
 }
-export function atEventLimit(content, limit) {
-    return validEventCount(content, limit) >= limit;
-}
 export function writeAll(descriptor, value) {
     const buffer = Buffer.from(value);
     let offset = 0;

package/dist/session-friction/log.mjs

@@ -1,9 +1,10 @@
+import { readCoverageLedger, writeCoverageLedger } from './coverage-ledger.mjs';
 import { closeSync, constants, fchmodSync, fstatSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { classifyFrictionObservation } from './classify.mjs';
 import { ensurePrivateDirectory } from './directory.mjs';
 import { withFileLock } from './lock.mjs';
-import { atEventLimit, LOG_MAX_BYTES, openLogFile, readLogContent, validEvent, writeAll, } from './log-file.mjs';
+import { validEventCount, LOG_MAX_BYTES, openLogFile, readLogContent, validEvent, writeAll, } from './log-file.mjs';
 import { sanitizeSessionId } from './session-id.mjs';
 import { boundedText, isWellFormedUnicode, normalizeAuditText } from './text.mjs';
 export const FRICTION_LOG_MAX_EVENTS = 500;
@@ -52,9 +53,23 @@ export function recordFriction(sessionId, observation, options) {
                 throw new Error('session-friction log is too large');
             if (!classified)
                 return;
+            const coverage = readCoverageLedger(path);
+            const logBytes = fstatSync(descriptor).size;
+            if (coverage && coverage.logBytes === logBytes && coverage.retainedEvents >= maxEvents) {
+                writeCoverageLedger(path, { ...coverage, droppedCount: coverage.droppedCount + 1 });
+                return;
+            }
             const content = readLogContent(descriptor);
-            if (atEventLimit(content, maxEvents))
+            const retainedEvents = validEventCount(content, FRICTION_LOG_MAX_EVENTS);
+            if (retainedEvents >= maxEvents) {
+                writeCoverageLedger(path, {
+                    schemaVersion: 1,
+                    logBytes,
+                    retainedEvents,
+                    droppedCount: (coverage?.droppedCount ?? 0) + 1,
+                });
                 return;
+            }
             const event = {
                 ...classified,
                 commandPrefix: normalizeAuditText(classified.commandPrefix),
@@ -66,9 +81,22 @@ export function recordFriction(sessionId, observation, options) {
                 return;
             const prefix = content && !content.endsWith('\n') ? '\n' : '';
             const addition = `${prefix}${JSON.stringify(event)}\n`;
-            if (fstatSync(descriptor).size + Buffer.byteLength(addition) > LOG_MAX_BYTES)
-                throw new Error('session-friction log is too large');
+            if (logBytes + Buffer.byteLength(addition) > LOG_MAX_BYTES) {
+                writeCoverageLedger(path, {
+                    schemaVersion: 1,
+                    logBytes,
+                    retainedEvents,
+                    droppedCount: (coverage?.droppedCount ?? 0) + 1,
+                });
+                return;
+            }
             writeAll(descriptor, addition);
+            if (coverage)
+                writeCoverageLedger(path, {
+                    ...coverage,
+                    logBytes: fstatSync(descriptor).size,
+                    retainedEvents: retainedEvents + 1,
+                });
         }
         finally {
             closeSync(descriptor);
@@ -89,19 +117,38 @@ export function readFrictionLog(sessionId, options) {
             const descriptor = openLogFile(path, constants.O_RDONLY);
             try {
                 const events = [];
+                const ledger = readCoverageLedger(path);
+                let droppedCount = ledger?.droppedCount ?? 0;
+                let retainedEvents = 0;
                 for (const line of readLogContent(descriptor).split('\n')) {
                     if (!line.trim())
                         continue;
                     try {
                         const value = JSON.parse(line);
-                        if (validEvent(value))
-                            events.push(value);
+                        if (validEvent(value)) {
+                            retainedEvents++;
+                            if (events.length < maxEvents)
+                                events.push(value);
+                            else
+                                droppedCount++;
+                        }
+                        else
+                            droppedCount++;
+                    }
+                    catch {
+                        droppedCount++;
                     }
-                    catch { }
-                    if (events.length >= maxEvents)
-                        break;
                 }
-                return events.length ? { status: 'events', events } : { status: 'empty' };
+                if (ledger &&
+                    (ledger.logBytes !== fstatSync(descriptor).size ||
+                        ledger.retainedEvents !== Math.min(retainedEvents, FRICTION_LOG_MAX_EVENTS)))
+                    throw new Error('session-friction coverage ledger does not match retained log');
+                if (!Number.isSafeInteger(droppedCount))
+                    throw new Error('session-friction dropped count overflow; capture incomplete');
+                const coverage = droppedCount ? { truncated: true, droppedCount } : {};
+                return events.length
+                    ? { status: 'events', events, ...coverage }
+                    : { status: 'empty', ...coverage };
             }
             finally {
                 closeSync(descriptor);

package/dist/session-friction/report.mjs

@@ -11,7 +11,7 @@ function journalData(entry) {
         return data ? { type: data.type, markdown: data.markdown } : undefined;
     }
     catch {
-        return undefined;
+        return 'unreadable';
     }
 }
 async function collectEntries(entries) {
@@ -22,8 +22,13 @@ async function collectEntries(entries) {
     let truncated = false;
     for await (const entry of entries) {
         consumed++;
-        const data = journalData(entry);
+        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;
@@ -53,28 +58,52 @@ function errorMessage(error) {
 }
 function sandboxMarkdown(friction) {
     if (friction.status === 'events')
-        return buildSandboxSection(friction.events);
+        return `${friction.truncated ? `## Capture Coverage\nStatus: partial\nDropped records: ${friction.droppedCount}\n\n` : ''}${buildSandboxSection(friction.events)}`;
+    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 incompleteCiSection(markdownBlocks) {
+    return ['## CI Failures\nStatus: unavailable (journal scan incomplete)', ...markdownBlocks].join('\n\n');
+}
 function reportFromLog(sessionId, logOptions, journal) {
     try {
         const friction = readFrictionLog(sessionId, logOptions);
+        const coverage = {
+            journalStatus: journal.status === 'unreachable'
+                ? 'unavailable'
+                : journal.truncated
+                    ? 'partial'
+                    : 'complete',
+            frictionStatus: friction.status,
+            truncated: friction.status !== 'absent' && friction.truncated === true,
+            ...(friction.status === 'absent' ? {} : { droppedCount: friction.droppedCount ?? 0 }),
+        };
         if (journal.status === 'ok' && journal.truncated)
             return {
-                markdown: '## CI Failures\nStatus: unavailable (journal scan incomplete)\n\n' +
-                    sandboxMarkdown(friction),
+                coverage,
+                markdown: incompleteCiSection(journal.markdownBlocks) + '\n\n' + sandboxMarkdown(friction),
             };
         const markdown = buildCiFailuresSection(sessionId, journal, friction.status);
-        return { markdown: `${markdown}\n\n${sandboxMarkdown(friction)}` };
+        return { coverage, markdown: `${markdown}\n\n${sandboxMarkdown(friction)}` };
     }
     catch (error) {
         const ciMarkdown = journal.status === 'ok' && journal.truncated
-            ? '## CI Failures\nStatus: unavailable (journal scan incomplete)'
+            ? incompleteCiSection(journal.markdownBlocks)
             : journal.status === 'ok' && journal.markdownBlocks.length === 0
                 ? '## CI Failures\nStatus: unavailable (friction log unreadable)'
                 : buildCiFailuresSection(sessionId, journal, 'empty');
         return {
+            coverage: {
+                journalStatus: journal.status === 'unreachable'
+                    ? 'unavailable'
+                    : journal.truncated
+                        ? 'partial'
+                        : 'complete',
+                frictionStatus: 'unreadable',
+                truncated: true,
+            },
             markdown: `${ciMarkdown}\n\n## Sandbox & Permission Audit\nStatus: unavailable (friction log unreadable)`,
             diagnostic: errorMessage(error),
         };

package/dist/session-friction/sandbox.mjs

@@ -1,15 +1,22 @@
 import { markdownAuditText } from './text.mjs';
 const SANDBOX_SECTION_HEADER = '## Sandbox & Permission Audit';
-const KIND_ORDER = ['sandbox-escalation', 'sandbox-failure'];
+const KIND_ORDER = [
+    'sandbox-escalation',
+    'sandbox-failure',
+    'ambiguous-failure',
+];
 export function buildSandboxSection(events) {
+    const observations = events.flatMap((event) => event.failure
+        ? [event, { ...event, kind: event.failure.kind, detail: event.failure.detail }]
+        : [event]);
     const groups = KIND_ORDER.map((kind) => {
-        const selected = events.filter((event) => event.kind === kind);
+        const selected = observations.filter((event) => event.kind === kind);
         return selected.length
             ? [
                 `- ${kind} (${selected.length})`,
-                ...selected.map((event) => `  - ${markdownAuditText(event.commandPrefix)} — ${markdownAuditText(event.detail)} — ${markdownAuditText(event.timestamp)}`),
+                ...selected.map((event) => `  - ${markdownAuditText(event.commandPrefix)} — ${markdownAuditText(event.detail)} — ${markdownAuditText(event.timestamp)}${event.kind === 'sandbox-escalation' ? ` — outcome: ${event.outcome ?? 'unknown'}` : ''}`),
             ].join('\n')
             : undefined;
     }).filter((group) => group !== undefined);
-    return `${SANDBOX_SECTION_HEADER}\nEvents observed: ${events.length}\n\n${groups.join('\n')}`;
+    return `${SANDBOX_SECTION_HEADER}\nEvents observed: ${observations.length}\n\n${groups.join('\n')}`;
 }

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

@@ -1,14 +1,20 @@
-export type FrictionEventKind = 'sandbox-escalation' | 'sandbox-failure';
+export type FrictionEventKind = 'sandbox-escalation' | 'sandbox-failure' | 'ambiguous-failure';
 export type FrictionEvent = {
     kind: FrictionEventKind;
     timestamp: string;
     commandPrefix: string;
     detail: string;
+    outcome?: 'requested' | 'approved' | 'denied' | 'unknown';
+    failure?: {
+        kind: 'sandbox-failure' | 'ambiguous-failure';
+        detail: string;
+    };
 };
 export type ToolResultObservation = {
     type: 'tool-result';
     command: string;
     commandWrappers?: string[];
+    permissionOutcome?: 'approved' | 'denied';
     escalationDetail?: string;
     structuredStderr?: string;
 };
@@ -18,14 +24,21 @@ export type PermissionRequestObservation = {
     commandWrappers?: string[];
 };
 export type FrictionObservation = ToolResultObservation | PermissionRequestObservation;
+type FrictionLogCoverage = {
+    truncated: true;
+    droppedCount: number;
+} | {
+    truncated?: false;
+    droppedCount?: never;
+};
 export type FrictionLogReadResult = {
     status: 'absent';
-} | {
+} | ({
     status: 'empty';
-} | {
+} & FrictionLogCoverage) | ({
     status: 'events';
     events: FrictionEvent[];
-};
+} & FrictionLogCoverage);
 export type FrictionLogOptions = {
     directory: string;
     maxEvents?: number;
@@ -43,10 +56,18 @@ export type JournalLoadResult = {
     status: 'not-found';
 };
 export type JournalLoader = (sessionId: string) => JournalLoadResult | Promise<JournalLoadResult>;
+export type SessionFrictionCoverage = {
+    journalStatus: 'complete' | 'partial' | 'unavailable';
+    frictionStatus: 'absent' | 'empty' | 'events' | 'unreadable';
+    truncated: boolean;
+    droppedCount?: number;
+};
 export type SessionFrictionReport = {
+    coverage: SessionFrictionCoverage;
     markdown: string;
     diagnostic?: string;
 };
 export type SessionFrictionReportOptions = FrictionLogOptions & {
     journalLoader: JournalLoader;
 };
+export {};

package/dist/workflow-policy/index.d.mts

@@ -2,6 +2,6 @@ export { evaluateGraphPolicy } from './graph.mts';
 export { evaluateLockPolicy, type ConcurrencyPolicy } from './concurrency.mts';
 export { conditionEntails } from './condition-entailment.mts';
 export { unprovisionedSecretsWithoutReadinessStep } from './secret-readiness.mts';
-export { callerCalleePermissionMismatches } from './permission-mismatches.mts';
+export { callerCalleePermissionMismatches, type CallerCalleePermissionPolicy, } from './permission-mismatches.mts';
 export { missingTopLevelPermissionPaths, parsePermissions, parseWorkflow, requiredWorkflowPermissions, type Workflow, } from './permissions.mts';
 export type { WorkflowTopology, WorkflowTopologyIndex, WorkflowTopologyPolicy, WorkflowNode, WorkflowJobNode, WorkflowStep, } from './types.mts';

package/dist/workflow-policy/index.mjs

@@ -2,5 +2,5 @@ export { evaluateGraphPolicy } from './graph.mjs';
 export { evaluateLockPolicy } from './concurrency.mjs';
 export { conditionEntails } from './condition-entailment.mjs';
 export { unprovisionedSecretsWithoutReadinessStep } from './secret-readiness.mjs';
-export { callerCalleePermissionMismatches } from './permission-mismatches.mjs';
+export { callerCalleePermissionMismatches, } from './permission-mismatches.mjs';
 export { missingTopLevelPermissionPaths, parsePermissions, parseWorkflow, requiredWorkflowPermissions, } from './permissions.mjs';

package/dist/workflow-policy/permission-declarations.d.mts

@@ -0,0 +1,14 @@
+export declare const PERMISSION_LEVEL_RANK: {
+    readonly none: 0;
+    readonly read: 1;
+    readonly write: 2;
+};
+export type PermissionLevel = keyof typeof PERMISSION_LEVEL_RANK;
+type PermissionMap = Record<string, PermissionLevel>;
+export type BoundedPermissionDeclaration = PermissionMap | 'read-all';
+export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
+export declare function isValidPermissionMap(value: unknown): value is PermissionMap;
+export declare function isValidDeclaration(value: unknown): value is BoundedPermissionDeclaration;
+export declare function permissionMap(value: BoundedPermissionDeclaration): Map<string, PermissionLevel>;
+export declare function mergePermissionMaps(target: Map<string, PermissionLevel>, source: Map<string, PermissionLevel>): void;
+export {};