vouchington-tooling 0.1.5 → 0.1.7

package/README.md

@@ -50,7 +50,8 @@ vouchington stage-review-payload optional|required <source> <destination>
 `download-optional-run-artifacts` uses the current Actions run and host. Pattern mode discovers
 non-expired artifacts across the run, keeps the first result for each name (matching `gh run
 download`), and extracts each selected name into its own directory. Ordinary absence is reported as
-`availability=unavailable`; invalid names and cancellation remain hard failures.
+`availability=unavailable`. Artifact listing retries up to three times with bounded backoff;
+exhausted transport errors, invalid names, and cancellation remain hard failures.
 
 `retrospective-transcript` discovers Codex and Claude transcripts by default. It also reads a
 Claude-compatible transcript when `CURSOR_SESSION_ID` is set, and Grok's `updates.jsonl` session
@@ -134,8 +135,38 @@ import {
   readDiagnosticReportSummaries,
 } from 'vouchington-tooling/vitest-diagnostics'
 import { runRetrospectiveTranscript } from 'vouchington-tooling/retrospective-transcript'
+import { buildSessionFrictionReport, recordFriction } from 'vouchington-tooling/session-friction'
 ```
 
+`session-friction` is an opt-in capture and reporting library. Callers supply the session id,
+absolute log directory, host-independent observation, and journal loader; it does not inspect host
+environment variables, install hooks, or connect to a journal service by itself. Invoking
+`recordFriction` touches the session log even when no event is classified, preserving the
+difference between an observed clean session and missing evidence. Report markdown keeps backend
+diagnostics separate from its paste-safe output. Capture stores at most 500 events per session,
+truncates event detail to 1,000 characters, and consumes up to 500 entries from the journal loader
+when building a report, stopping earlier when its aggregate 1 MB inspected-byte budget is reached.
+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. The supplied log directory must be dedicated
+to session-friction; existing directories must already be owner-only, while newly created
+directories and log files are enforced as owner-only when recording. Reads use a fixed bounded
+buffer that can detect growth one byte beyond the documented 2 MB cap.
+Ownership checks require POSIX effective-user IDs (Linux and macOS); session-friction throws on
+Windows and other platforms where those IDs are unavailable.
+Root-owned system symlink ancestors are supported for paths such as macOS `/var`; callers must not
+allow the directory chain to be mutated while it is being validated.
+Command-prefix normalization recognizes simple shell
+segments with single or double quotes; it does not evaluate substitutions or implement a full shell
+grammar. Normalization attempts limited redaction of obvious credential patterns but is not a secret
+scrubber; callers must ensure credentials are never included in captured commands.
+Failure classification inspects at most 100,000 structured-stderr characters, split evenly between
+the beginning and end when input exceeds that bound.
+Cooperating log readers and writers are serialized, including the initial clean-session
+touch. Recording and report log reads are synchronous: on contention they block the caller's
+event loop for up to one second before failing explicitly. Avoid these APIs on hot request paths.
+
 The artifact, review-payload, HTTP body, and pagination APIs validate untrusted inputs at their
 boundaries. Review posting lives in `gha-post-review` and talks to GitHub only through caller-supplied
 credentials (job token or a minted Claude GitHub App token).

package/dist/index.d.mts

@@ -1,5 +1,7 @@
 export { codexChildren, codexIdentity, computeTranscriptFacts, formatTranscriptFacts, formatUnavailable, resolveTranscriptFile, runRetrospectiveTranscript, } from './retrospective-transcript/index.mts';
 export type { ResolveOptions, TokenTotals, TranscriptFacts, } from './retrospective-transcript/index.mts';
+export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from './session-friction/index.mts';
+export type { FrictionEvent, FrictionEventKind, FrictionLogOptions, FrictionLogReadResult, FrictionObservation, JournalEntry, JournalLoader, JournalLoadResult, PermissionRequestObservation, SessionFrictionReport, SessionFrictionReportOptions, ToolResultObservation, } from './session-friction/index.mts';
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mts';
 export type { EphemeralListenerOptions, RunnerPortPolicy } from './runner-port-policy/index.mts';
 export { extractAlterTableAddColumnLocations, extractCreateIndexMetadata, extractCreateTableMetadata, extractDefaultFunction, extractDropIndexMetadata, extractFuncCallArgColumnNames, extractMigrationConstraintMetadata, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mts';

package/dist/index.mjs

@@ -1,5 +1,6 @@
 /* eslint-disable max-lines -- package entry point enumerates the supported public API. */
 export { codexChildren, codexIdentity, computeTranscriptFacts, formatTranscriptFacts, formatUnavailable, resolveTranscriptFile, runRetrospectiveTranscript, } from './retrospective-transcript/index.mjs';
+export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from './session-friction/index.mjs';
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mjs';
 export { extractAlterTableAddColumnLocations, extractCreateIndexMetadata, extractCreateTableMetadata, extractDefaultFunction, extractDropIndexMetadata, extractFuncCallArgColumnNames, extractMigrationConstraintMetadata, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mjs';
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from './sql-scanner/index.mjs';

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

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

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

@@ -0,0 +1,78 @@
+import { isWellFormedUnicode, markdownAuditText } from './text.mjs';
+const GROUP_HEADER = /^- `(recurring|one-off)` — `GitHub Actions` — .*[^\s]$/;
+const EVIDENCE = /^ {2}- Evidence: .*[^\s]$/;
+const ROOT_DIAGNOSTIC = /^ {2}- Root diagnostic: .*[^\s]$/;
+const DISPOSITION = /^ {2}- Disposition: .*[^\s]$/;
+const BLANK = /^\s*$/;
+const CI_FAILURES_HEADER = '## CI Failures';
+const CI_FAILURE_BLOCK_MAX_BYTES = 10_000;
+const FIELD_PREFIXES = [
+    '- `recurring` — `GitHub Actions` — ',
+    '- `one-off` — `GitHub Actions` — ',
+    '  - Evidence: ',
+    '  - Root diagnostic: ',
+    '  - Disposition: ',
+];
+function safeField(line) {
+    const prefix = FIELD_PREFIXES.find((value) => line.startsWith(value));
+    /* v8 ignore next -- matchBlock currently passes only fields with a known prefix. */
+    if (!prefix)
+        return markdownAuditText(line) || null;
+    const content = markdownAuditText(line.slice(prefix.length));
+    return content ? `${prefix}${content}` : null;
+}
+function matchBlock(markdown) {
+    if (!isWellFormedUnicode(markdown))
+        return null;
+    const lines = markdown.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
+    let index = 0;
+    const consume = (pattern) => {
+        while (index < lines.length && BLANK.test(lines[index]))
+            index++;
+        const line = lines[index];
+        if (line === undefined || !pattern.test(line))
+            return null;
+        index++;
+        return line;
+    };
+    const fields = [
+        consume(GROUP_HEADER),
+        consume(EVIDENCE),
+        consume(ROOT_DIAGNOSTIC),
+        consume(DISPOSITION),
+    ];
+    if (fields.some((field) => field === null))
+        return null;
+    if (!lines.slice(index).every((line) => BLANK.test(line)))
+        return null;
+    const safeFields = fields.map((field) => safeField(field));
+    if (safeFields.some((field) => field === null))
+        return null;
+    return safeFields.join('\n');
+}
+export function isConformingCiFailureBlock(markdown) {
+    if (markdown.length > CI_FAILURE_BLOCK_MAX_BYTES ||
+        Buffer.byteLength(markdown) > CI_FAILURE_BLOCK_MAX_BYTES)
+        return false;
+    return matchBlock(markdown) !== null;
+}
+function journalMarkdown(entries) {
+    return [...entries].flatMap((entry) => {
+        const data = entry?.data;
+        return data?.type === 'journal' && typeof data.markdown === 'string' ? [data.markdown] : [];
+    });
+}
+export function getConformingGroups(entries) {
+    return journalMarkdown(entries)
+        .map(matchBlock)
+        .filter((block) => block !== null);
+}
+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)})`;
+    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/classify.d.mts

@@ -0,0 +1,2 @@
+import type { FrictionEvent, FrictionObservation } from './types.mts';
+export declare function classifyFrictionObservation(observation: FrictionObservation): Omit<FrictionEvent, 'timestamp'> | null;

package/dist/session-friction/classify.mjs

@@ -0,0 +1,87 @@
+import { normalizeCommandPrefix } from './normalize.mjs';
+import { boundedText, isWellFormedUnicode, normalizeAuditText } from './text.mjs';
+const FAILURE_TOKENS = [
+    ['Operation not permitted', /Operation not permitted/i],
+    ['E2BIG', /\bE2BIG\b/i],
+    ['EPERM', /\bEPERM\b/i],
+];
+const CONNECTION_REFUSED = /\bECONNREFUSED\b/i;
+const URL_USERINFO = /([a-z][a-z0-9+.-]{0,31}:\/\/)[^\s/?#@]*@/gi;
+const STDERR_INSPECTION_MAX_LENGTH = 100_000;
+const COMMAND_INSPECTION_MAX_LENGTH = 10_000;
+const IPV4_OCTET = '(?:25[0-5]|2[0-4]\\d|1\\d{2}|[1-9]?\\d)';
+const LOOPBACK_ADDRESSES = [
+    new RegExp(String.raw `(?<![0-9a-z_.:-])(?:127\.${IPV4_OCTET}(?:\.${IPV4_OCTET}){2}|localhost)(?![0-9a-z_.-])`, 'i'),
+    /(?<![0-9a-z_.-])\[(?:::1|0:0:0:0:0:0:0:1)(?:%[a-z0-9_.-]+)?\](?![0-9a-z_.-])/i,
+    /(?<![0-9a-z_.:\x5b\x5d-])(?:::1|0:0:0:0:0:0:0:1)(?:%[a-z0-9_.-]+)?(?::\d{1,5})?(?![0-9a-z_.:\x5b\x5d-])/i,
+];
+const DETAIL_MAX_LENGTH = 1_000;
+function boundedTail(value, maximum) {
+    let start = Math.max(0, value.length - maximum);
+    const first = value.charCodeAt(start);
+    const previous = value.charCodeAt(start - 1);
+    if (first >= 0xdc00 && first <= 0xdfff && previous >= 0xd800 && previous <= 0xdbff)
+        start++;
+    return value.slice(start);
+}
+function boundedStderr(value) {
+    if (value.length <= STDERR_INSPECTION_MAX_LENGTH)
+        return value;
+    const headLength = Math.floor((STDERR_INSPECTION_MAX_LENGTH - 1) / 2);
+    const head = boundedText(value, headLength);
+    const tail = boundedTail(value, STDERR_INSPECTION_MAX_LENGTH - 1 - head.length);
+    return `${head}\n${tail}`;
+}
+function withoutUrlUserinfo(line) {
+    return line.includes('://') && line.includes('@') ? line.replace(URL_USERINFO, '$1') : line;
+}
+export function classifyFrictionObservation(observation) {
+    if (!observation || typeof observation !== 'object')
+        return null;
+    if (typeof observation.command !== 'string')
+        return null;
+    const command = boundedText(observation.command, COMMAND_INSPECTION_MAX_LENGTH);
+    if (!isWellFormedUnicode(command) || normalizeAuditText(command) === '')
+        return null;
+    const commandPrefix = normalizeCommandPrefix(command, observation.commandWrappers);
+    if (commandPrefix === '' || !isWellFormedUnicode(commandPrefix))
+        return null;
+    if (observation.type === 'permission-request') {
+        return { kind: 'sandbox-escalation', commandPrefix, detail: 'permission-request' };
+    }
+    if (observation.type !== 'tool-result')
+        return null;
+    if (observation.escalationDetail !== undefined &&
+        typeof observation.escalationDetail !== 'string')
+        return null;
+    const escalationDetail = normalizeAuditText(boundedText(observation.escalationDetail ?? '', DETAIL_MAX_LENGTH));
+    if (!isWellFormedUnicode(escalationDetail))
+        return null;
+    if (escalationDetail) {
+        return {
+            kind: 'sandbox-escalation',
+            commandPrefix,
+            detail: escalationDetail,
+        };
+    }
+    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;
+    const token = FAILURE_TOKENS.find(([, pattern]) => pattern.test(stderr))?.[0];
+    if (token)
+        return { kind: 'sandbox-failure', commandPrefix, detail: `stderr matched "${token}"` };
+    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',
+        };
+    }
+    return null;
+}

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

@@ -0,0 +1 @@
+export declare function ensurePrivateDirectory(directory: string, create: boolean): boolean;

package/dist/session-friction/directory.mjs

@@ -0,0 +1,71 @@
+import { chmodSync, lstatSync, mkdirSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+const PRIVATE_DIRECTORY_MODE = 0o700;
+function isCode(error, code) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && error.code === code);
+}
+function directoryChain(directory) {
+    const chain = [directory];
+    let current = directory;
+    while (dirname(current) !== current) {
+        current = dirname(current);
+        chain.push(current);
+    }
+    return chain.reverse();
+}
+export function ensurePrivateDirectory(directory, create) {
+    const chain = directoryChain(directory);
+    const effectiveUserId = process.geteuid?.();
+    if (effectiveUserId === undefined)
+        throw new Error('session-friction requires POSIX directory permissions');
+    for (const [index, path] of chain.entries()) {
+        let created = false;
+        let status;
+        try {
+            status = lstatSync(path);
+        }
+        catch (error) {
+            /* v8 ignore next -- unexpected filesystem errors are propagated unchanged. */
+            if (!isCode(error, 'ENOENT'))
+                throw error;
+            if (!create)
+                return false;
+            try {
+                mkdirSync(path, { mode: PRIVATE_DIRECTORY_MODE });
+                created = true;
+            }
+            catch (mkdirError) {
+                /* v8 ignore next -- another process can create the directory after lstat. */
+                if (!isCode(mkdirError, 'EEXIST'))
+                    throw mkdirError;
+            }
+            status = lstatSync(path);
+        }
+        const leaf = index === chain.length - 1;
+        if (status.isSymbolicLink()) {
+            if (leaf || status.uid !== 0)
+                throw new Error('session-friction log directory must be a private directory');
+            try {
+                status = statSync(path);
+            }
+            catch {
+                throw new Error('session-friction log directory must be a private directory');
+            }
+        }
+        if (!status.isDirectory())
+            throw new Error('session-friction log directory must be a private directory');
+        if (created)
+            chmodSync(path, PRIVATE_DIRECTORY_MODE);
+        if (!created) {
+            const ownedByCaller = status.uid === effectiveUserId;
+            const ownedByRoot = status.uid === 0;
+            const writableByOthers = (status.mode & 0o022) !== 0;
+            const sticky = (status.mode & 0o1000) !== 0;
+            if ((leaf && ((status.mode & 0o777) !== PRIVATE_DIRECTORY_MODE || !ownedByCaller)) ||
+                (!leaf && !ownedByCaller && !ownedByRoot) ||
+                (!leaf && writableByOthers && !sticky))
+                throw new Error('session-friction log directory must be a private directory');
+        }
+    }
+    return true;
+}

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

@@ -0,0 +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 { isConformingCiFailureBlock } from './ci-failures.mts';
+export type { FrictionEvent, FrictionEventKind, FrictionLogOptions, FrictionLogReadResult, FrictionObservation, JournalEntry, JournalLoadResult, JournalLoader, PermissionRequestObservation, SessionFrictionReport, SessionFrictionReportOptions, ToolResultObservation, } from './types.mts';

package/dist/session-friction/index.mjs

@@ -0,0 +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 { isConformingCiFailureBlock } from './ci-failures.mjs';

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

@@ -0,0 +1 @@
+export declare function withFileLock<Result>(path: string, action: () => Result): Result;

package/dist/session-friction/lock.mjs

@@ -0,0 +1,193 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { basename } from 'node:path';
+const LOCK_ATTEMPTS = 200;
+const STALE_LOCK_AGE_MS = 30_000;
+const LOCK_OWNER_MAX_BYTES = 32;
+const MAX_PID = 2_147_483_647;
+const LOCK_CREATE_FLAGS = constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW;
+const lockWait = new Int32Array(new SharedArrayBuffer(4));
+function waitForLock() {
+    // Intentional synchronous backoff for CLI and hook callers.
+    Atomics.wait(lockWait, 0, 0, 5);
+}
+function hasCode(error, code) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && error.code === code);
+}
+function isFresh(mtimeMs) {
+    const age = Date.now() - Math.floor(mtimeMs);
+    return age > -STALE_LOCK_AGE_MS && age < STALE_LOCK_AGE_MS;
+}
+function inspectLock(lockPath) {
+    let descriptor;
+    try {
+        descriptor = openSync(lockPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch {
+        /* v8 ignore next -- detects a lock that disappears or is replaced while being inspected. */
+        return null;
+    }
+    try {
+        const status = fstatSync(descriptor);
+        /* v8 ignore next -- opening a non-regular lock requires a platform-specific FIFO/device. */
+        if (!status.isFile())
+            return null;
+        if (status.size > LOCK_OWNER_MAX_BYTES)
+            return isFresh(status.mtimeMs)
+                ? null
+                : { dev: status.dev, ino: status.ino, mtimeMs: status.mtimeMs, owner: null };
+        const buffer = Buffer.alloc(LOCK_OWNER_MAX_BYTES + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const bytes = readSync(descriptor, buffer, length, buffer.length - length, length);
+            if (bytes === 0)
+                break;
+            length += bytes;
+        }
+        /* v8 ignore next -- detects external growth after the descriptor metadata check. */
+        if (length > LOCK_OWNER_MAX_BYTES)
+            return null;
+        const rawOwner = buffer.subarray(0, length).toString();
+        return {
+            dev: status.dev,
+            ino: status.ino,
+            mtimeMs: status.mtimeMs,
+            owner: /^[1-9][0-9]*$/.test(rawOwner) ? Number(rawOwner) : null,
+        };
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function withReaperLock(lockPath, action) {
+    const reaperPath = `${lockPath}.reap`;
+    let descriptor;
+    try {
+        descriptor = openSync(reaperPath, LOCK_CREATE_FLAGS, 0o600);
+    }
+    catch (error) {
+        /* v8 ignore next 2 -- requires a narrow filesystem race or platform open failure. */
+        if (hasCode(error, 'EEXIST') || hasCode(error, 'ENOENT'))
+            return false;
+        /* v8 ignore next -- unexpected platform errors must propagate. */
+        throw error;
+    }
+    try {
+        return action();
+    }
+    finally {
+        closeSync(descriptor);
+        try {
+            unlinkSync(reaperPath);
+        }
+        catch { }
+    }
+}
+function removeOrphanedReaper(reaperPath) {
+    try {
+        const inspected = lstatSync(reaperPath);
+        if (isFresh(inspected.mtimeMs))
+            return false;
+        const current = lstatSync(reaperPath);
+        /* v8 ignore next 5 -- requires external replacement during stale-reaper recovery. */
+        if (current.dev !== inspected.dev ||
+            current.ino !== inspected.ino ||
+            current.mtimeMs !== inspected.mtimeMs)
+            return false;
+        unlinkSync(reaperPath);
+        return true;
+    }
+    catch {
+        /* v8 ignore next -- requires external removal during stale-reaper recovery. */
+        return false;
+    }
+}
+function removeStaleLock(lockPath) {
+    return withReaperLock(lockPath, () => {
+        try {
+            const inspected = inspectLock(lockPath);
+            if (!inspected)
+                return false;
+            const fresh = isFresh(inspected.mtimeMs);
+            const { owner } = inspected;
+            if (typeof owner === 'number' && Number.isInteger(owner) && owner > 0 && owner <= MAX_PID) {
+                try {
+                    process.kill(owner, 0);
+                    return false;
+                }
+                catch (error) {
+                    if (!hasCode(error, 'ESRCH'))
+                        return false;
+                }
+            }
+            else if (fresh)
+                return false;
+            const current = lstatSync(lockPath);
+            /* v8 ignore next 5 -- requires external replacement despite the reaper protocol. */
+            if (current.dev !== inspected.dev ||
+                current.ino !== inspected.ino ||
+                current.mtimeMs !== inspected.mtimeMs)
+                return false;
+            unlinkSync(lockPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+export function withFileLock(path, action) {
+    const lockPath = `${path}.lock`;
+    const reaperPath = `${lockPath}.reap`;
+    for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt++) {
+        let reaperExists = false;
+        try {
+            lstatSync(reaperPath);
+            reaperExists = true;
+        }
+        catch (error) {
+            /* v8 ignore next -- unexpected reaper lstat failures must propagate. */
+            if (!hasCode(error, 'ENOENT'))
+                throw error;
+        }
+        if (reaperExists) {
+            if (removeOrphanedReaper(reaperPath))
+                continue;
+            waitForLock();
+            continue;
+        }
+        let descriptor;
+        try {
+            descriptor = openSync(lockPath, LOCK_CREATE_FLAGS, 0o600);
+        }
+        catch (error) {
+            if (!hasCode(error, 'EEXIST'))
+                throw error;
+            let lockStatus;
+            try {
+                lockStatus = lstatSync(lockPath);
+            }
+            catch (statusError) {
+                /* v8 ignore next -- requires the owner to release between EEXIST and lstat. */
+                if (hasCode(statusError, 'ENOENT'))
+                    continue;
+                /* v8 ignore next -- requires an unexpected lstat failure during the same race. */
+                throw statusError;
+            }
+            if (!lockStatus.isFile())
+                throw new Error('session-friction log lock must be a regular file');
+            if (removeStaleLock(lockPath))
+                continue;
+            waitForLock();
+            continue;
+        }
+        try {
+            writeFileSync(descriptor, String(process.pid));
+            return action();
+        }
+        finally {
+            closeSync(descriptor);
+            unlinkSync(lockPath);
+        }
+    }
+    throw new Error(`could not acquire session-friction log lock for ${basename(path)}`);
+}

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

@@ -0,0 +1,8 @@
+import type { FrictionLogOptions, FrictionLogReadResult, FrictionObservation } from './types.mts';
+export declare const FRICTION_LOG_MAX_EVENTS = 500;
+export declare function requireDirectory(directory: string): string;
+export declare function eventLimit(maxEvents: number | undefined): number;
+export declare function recordFriction(sessionId: string, observation: FrictionObservation, options: FrictionLogOptions & {
+    timestamp?: string | (() => string);
+}): void;
+export declare function readFrictionLog(sessionId: string, options: FrictionLogOptions): FrictionLogReadResult;

package/dist/session-friction/log.mjs

@@ -0,0 +1,195 @@
+import { closeSync, constants, fchmodSync, fstatSync, openSync, readSync, writeSync } 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 { boundedText, isSafeAuditText, isWellFormedUnicode, normalizeAuditText } from './text.mjs';
+import { decodeUtf8 } from './utf8.mjs';
+import { sanitizeSessionId } from './session-id.mjs';
+export const FRICTION_LOG_MAX_EVENTS = 500;
+const LOG_MAX_BYTES = 2_000_000;
+const EVENT_FIELD_MAX_LENGTH = 1_000;
+export function requireDirectory(directory) {
+    if (typeof directory !== 'string')
+        throw new Error('log directory must be a string');
+    if (Buffer.byteLength(directory) > 4096)
+        throw new Error('session-friction log directory path is too long');
+    if (!isAbsolute(directory))
+        throw new Error('session-friction log directory must be absolute');
+    return resolve(directory);
+}
+export function eventLimit(maxEvents) {
+    const limit = maxEvents ?? FRICTION_LOG_MAX_EVENTS;
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new Error('maxEvents must be a positive integer');
+    return Math.min(limit, FRICTION_LOG_MAX_EVENTS);
+}
+function logPath(sessionId, directory) {
+    return join(requireDirectory(directory), `${sanitizeSessionId(sessionId)}.jsonl`);
+}
+function validEvent(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return ((record.kind === 'sandbox-escalation' || record.kind === 'sandbox-failure') &&
+        isSafeAuditText(record.timestamp) &&
+        isSafeAuditText(record.commandPrefix) &&
+        isSafeAuditText(record.detail));
+}
+function openLogFile(path, flags) {
+    let descriptor;
+    try {
+        descriptor = openSync(path, flags | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            (error.code === 'ELOOP' || error.code === 'EISDIR' || error.code === 'ENOTDIR'))
+            throw new Error('session-friction log must be a regular file');
+        throw error;
+    }
+    try {
+        const status = fstatSync(descriptor);
+        if (!status.isFile() || status.nlink !== 1)
+            throw new Error('session-friction log must be a regular file');
+        return descriptor;
+    }
+    catch (error) {
+        closeSync(descriptor);
+        throw error;
+    }
+}
+function readLogContent(descriptor) {
+    if (fstatSync(descriptor).size > LOG_MAX_BYTES)
+        throw new Error('session-friction log is too large');
+    const buffer = Buffer.alloc(LOG_MAX_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+        const bytes = readSync(descriptor, buffer, length, buffer.length - length, length);
+        if (bytes === 0)
+            break;
+        length += bytes;
+    }
+    /* v8 ignore next -- detects external growth after the descriptor size check. */
+    if (length > LOG_MAX_BYTES)
+        throw new Error('session-friction log is too large');
+    return decodeUtf8(buffer.subarray(0, length));
+}
+function validEventCount(content, limit) {
+    let count = 0;
+    for (const line of content.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            if (validEvent(JSON.parse(line)))
+                count++;
+        }
+        catch { }
+        if (count >= limit)
+            break;
+    }
+    return count;
+}
+function atEventLimit(content, limit) {
+    return validEventCount(content, limit) >= limit;
+}
+function writeAll(descriptor, value) {
+    const buffer = Buffer.from(value);
+    let offset = 0;
+    while (offset < buffer.length) {
+        const written = writeSync(descriptor, buffer, offset, buffer.length - offset);
+        /* v8 ignore next -- a zero-byte synchronous file write is an external I/O failure. */
+        if (written === 0)
+            throw new Error('session-friction log write made no progress');
+        offset += written;
+    }
+}
+export function recordFriction(sessionId, observation, options) {
+    const maxEvents = eventLimit(options.maxEvents);
+    const timestamp = typeof options.timestamp === 'function' ? options.timestamp() : options.timestamp;
+    if (timestamp !== undefined && typeof timestamp !== 'string')
+        throw new Error('timestamp must be a string');
+    const rawTimestamp = timestamp ?? new Date().toISOString();
+    const normalizedTimestamp = normalizeAuditText(boundedText(rawTimestamp, EVENT_FIELD_MAX_LENGTH));
+    if (!normalizedTimestamp)
+        throw new Error('timestamp must be non-empty');
+    if (!isWellFormedUnicode(normalizedTimestamp))
+        throw new Error('timestamp must be well-formed Unicode');
+    const classified = classifyFrictionObservation(observation);
+    const path = logPath(sessionId, options.directory);
+    const directory = requireDirectory(options.directory);
+    ensurePrivateDirectory(directory, true);
+    withFileLock(path, () => {
+        /* v8 ignore next 2 -- requires the directory path to be replaced after its lock is acquired. */
+        if (!ensurePrivateDirectory(directory, false))
+            throw new Error('session-friction log directory disappeared while acquiring the lock');
+        const descriptor = openLogFile(path, constants.O_CREAT | constants.O_RDWR | constants.O_APPEND);
+        try {
+            fchmodSync(descriptor, 0o600);
+            if (fstatSync(descriptor).size > LOG_MAX_BYTES)
+                throw new Error('session-friction log is too large');
+            if (!classified)
+                return;
+            const content = readLogContent(descriptor);
+            if (atEventLimit(content, maxEvents))
+                return;
+            const event = {
+                ...classified,
+                commandPrefix: normalizeAuditText(classified.commandPrefix),
+                detail: normalizeAuditText(classified.detail),
+                timestamp: normalizedTimestamp,
+            };
+            /* v8 ignore next -- normalized classified fields satisfy validEvent defensively. */
+            if (!validEvent(event))
+                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');
+            writeAll(descriptor, addition);
+        }
+        finally {
+            closeSync(descriptor);
+        }
+    });
+}
+export function readFrictionLog(sessionId, options) {
+    const maxEvents = eventLimit(options.maxEvents);
+    const path = logPath(sessionId, options.directory);
+    const directory = requireDirectory(options.directory);
+    if (!ensurePrivateDirectory(directory, false))
+        return { status: 'absent' };
+    try {
+        return withFileLock(path, () => {
+            /* v8 ignore next -- detects directory removal after acquiring the file lock. */
+            if (!ensurePrivateDirectory(directory, false))
+                return { status: 'absent' };
+            const descriptor = openLogFile(path, constants.O_RDONLY);
+            try {
+                const events = [];
+                for (const line of readLogContent(descriptor).split('\n')) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const value = JSON.parse(line);
+                        if (validEvent(value))
+                            events.push(value);
+                    }
+                    catch { }
+                    if (events.length >= maxEvents)
+                        break;
+                }
+                return events.length ? { status: 'events', events } : { status: 'empty' };
+            }
+            finally {
+                closeSync(descriptor);
+            }
+        });
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return { status: 'absent' };
+        throw error;
+    }
+}

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

@@ -0,0 +1 @@
+export declare function normalizeCommandPrefix(command: string, wrappersToStrip?: string[]): string;

package/dist/session-friction/normalize.mjs

@@ -0,0 +1,174 @@
+const MAX_COMMAND_TOKEN_LENGTH = 40;
+const MAX_COMMAND_LENGTH = 100_000;
+const MAX_COMMAND_WRAPPERS = 16;
+const REDACTED_TOKEN = '[REDACTED]';
+const CREDENTIAL_OPTION = /^--?(?:api[-_]?key|auth|credential|password|secret|token)=/i;
+const URL_USERINFO = /^[a-z][a-z0-9+.-]*:\/\/[^/@\s]+@/i;
+const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const PACKAGE_RUNNERS = new Set(['npm', 'npx', 'pnpm', 'pnpx', 'yarn']);
+const GIT_OPTIONS_WITH_ARGS = new Set(['-C', '-c', '--git-dir', '--work-tree']);
+const ENV_OPTIONS_WITH_ARGS = new Set(['-C', '--chdir', '-S', '--split-string', '-u', '--unset']);
+const ENV_OPTIONS_WITHOUT_ARGS = new Set([
+    '-i',
+    '--ignore-environment',
+    '-0',
+    '--null',
+    '-v',
+    '--debug',
+]);
+const GIT_OPTIONS_WITHOUT_ARGS = new Set([
+    '-v',
+    '--version',
+    '-h',
+    '--help',
+    '--exec-path',
+    '--html-path',
+    '--man-path',
+    '--info-path',
+    '-p',
+    '--paginate',
+    '-P',
+    '--no-pager',
+    '--no-replace-objects',
+    '--bare',
+]);
+function splitCommand(command) {
+    const result = [];
+    let segment = [];
+    let word = '';
+    let quote;
+    let escaped = false;
+    const flushWord = () => {
+        if (word)
+            segment.push(word);
+        word = '';
+    };
+    const flushSegment = () => {
+        flushWord();
+        if (segment.length)
+            result.push(segment);
+        segment = [];
+    };
+    for (const char of command) {
+        if (escaped) {
+            word += char;
+            escaped = false;
+        }
+        else if (char === '\\' && quote !== "'") {
+            escaped = true;
+        }
+        else if (quote) {
+            if (char === quote)
+                quote = undefined;
+            else
+                word += char;
+        }
+        else if (char === '"' || char === "'")
+            quote = char;
+        else if (';&|<>\n\r'.includes(char))
+            flushSegment();
+        else if (/\s/.test(char))
+            flushWord();
+        else
+            word += char;
+    }
+    if (escaped)
+        word += '\\';
+    flushSegment();
+    return result;
+}
+function redact(token) {
+    return token.length > MAX_COMMAND_TOKEN_LENGTH ||
+        CREDENTIAL_OPTION.test(token) ||
+        URL_USERINFO.test(token)
+        ? REDACTED_TOKEN
+        : token;
+}
+function stripAssignments(tokens) {
+    let index = 0;
+    while (index < tokens.length && ENV_ASSIGNMENT.test(tokens[index]))
+        index++;
+    const wrapper = tokens[index];
+    // Assignments without an executable are represented by a safe sentinel.
+    if (wrapper !== 'env' && !wrapper?.endsWith('/env'))
+        return index < tokens.length ? tokens.slice(index) : index ? [REDACTED_TOKEN] : tokens;
+    index++;
+    while (index < tokens.length) {
+        const option = tokens[index];
+        if (option === '--') {
+            index++;
+            break;
+        }
+        const optionName = option.split('=', 1)[0];
+        const splitStringOption = optionName === '-S' || (optionName.length >= 5 && '--split-string'.startsWith(optionName));
+        if (splitStringOption)
+            return [REDACTED_TOKEN];
+        const abbreviatedArgument = optionName.length >= 5 && '--chdir'.startsWith(optionName);
+        if (ENV_OPTIONS_WITH_ARGS.has(optionName) || abbreviatedArgument) {
+            index += option.includes('=') ? 1 : 2;
+            continue;
+        }
+        if (ENV_OPTIONS_WITHOUT_ARGS.has(option)) {
+            index++;
+            continue;
+        }
+        if (option.startsWith('-'))
+            return [REDACTED_TOKEN];
+        break;
+    }
+    while (index < tokens.length && ENV_ASSIGNMENT.test(tokens[index]))
+        index++;
+    if (index < tokens.length)
+        return tokens.slice(index);
+    return tokens.some((token) => ENV_ASSIGNMENT.test(token)) ? [REDACTED_TOKEN] : [];
+}
+function stripGitOptions(tokens) {
+    let index = 0;
+    while (index < tokens.length) {
+        const token = tokens[index];
+        if (token === '--')
+            return tokens.slice(index + 1);
+        if (GIT_OPTIONS_WITH_ARGS.has(token)) {
+            if (index + 1 >= tokens.length)
+                return [REDACTED_TOKEN];
+            index += 2;
+        }
+        else if (GIT_OPTIONS_WITHOUT_ARGS.has(token) || /^--[a-z0-9-]+=/i.test(token))
+            index++;
+        else
+            break;
+    }
+    return tokens.slice(index);
+}
+function packageRunner(token) {
+    return [...PACKAGE_RUNNERS].some((runner) => token === runner || token.endsWith(`/${runner}`));
+}
+function normalizeSegment(tokens) {
+    const [first, ...rest] = tokens;
+    if (!first)
+        return '';
+    if (packageRunner(first) && (rest[0] === 'run' || rest[0] === 'exec') && rest[1])
+        return `${redact(first)} ${rest[0]} ${redact(rest[1])}`;
+    const effective = first === 'git' || first.endsWith('/git') ? stripGitOptions(rest) : rest;
+    return effective[0] ? `${redact(first)} ${redact(effective[0])}` : redact(first);
+}
+export function normalizeCommandPrefix(command, wrappersToStrip = []) {
+    if (command.length > MAX_COMMAND_LENGTH)
+        return '[REDACTED: command too long]';
+    const segments = splitCommand(command);
+    let index = 0;
+    while (index < segments.length - 1 && stripAssignments(segments[index])[0] === 'cd')
+        index++;
+    const tokens = stripAssignments(segments[index] ?? []);
+    const wrapperValues = Array.isArray(wrappersToStrip) ? wrappersToStrip : [];
+    const wrapperNames = new Set(wrapperValues
+        .slice(0, MAX_COMMAND_WRAPPERS)
+        .filter((value) => typeof value === 'string' && value.length > 0 && value.length <= MAX_COMMAND_TOKEN_LENGTH));
+    let wrappers = 0;
+    while (tokens[wrappers] && wrapperNames.has(tokens[wrappers]))
+        wrappers++;
+    if (!wrappers)
+        return normalizeSegment(tokens);
+    const nested = normalizeSegment(stripAssignments(tokens.slice(wrappers)));
+    return nested ? `${redact(tokens[0])} ${nested}` : redact(tokens[0]);
+}

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

@@ -0,0 +1,2 @@
+import type { SessionFrictionReport, SessionFrictionReportOptions } from './types.mts';
+export declare function buildSessionFrictionReport(sessionId: string, options: SessionFrictionReportOptions): Promise<SessionFrictionReport>;

package/dist/session-friction/report.mjs

@@ -0,0 +1,113 @@
+import { eventLimit, readFrictionLog, requireDirectory } from './log.mjs';
+import { buildCiFailuresSection, getConformingGroups } from './ci-failures.mjs';
+import { buildSandboxSection } from './sandbox.mjs';
+import { validateSessionId } from './session-id.mjs';
+const JOURNAL_ENTRY_MAX_COUNT = 500;
+const JOURNAL_MARKDOWN_MAX_BYTES = 10_000;
+const JOURNAL_TOTAL_MAX_BYTES = 1_000_000;
+function journalData(entry) {
+    try {
+        const data = entry?.data;
+        return data ? { type: data.type, markdown: data.markdown } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function collectEntries(entries) {
+    const result = [];
+    let consumed = 0;
+    let inspectedBytes = 0;
+    let retainedBytes = 0;
+    let truncated = false;
+    for await (const entry of entries) {
+        consumed++;
+        const data = journalData(entry);
+        const markdown = data?.markdown;
+        if (data?.type === 'journal' && typeof markdown === 'string') {
+            const bytes = Buffer.byteLength(markdown);
+            inspectedBytes += bytes;
+            if (bytes > JOURNAL_MARKDOWN_MAX_BYTES)
+                truncated = true;
+            if (bytes <= JOURNAL_MARKDOWN_MAX_BYTES && retainedBytes + bytes <= JOURNAL_TOTAL_MAX_BYTES) {
+                result.push({ data: { type: 'journal', markdown } });
+                retainedBytes += bytes;
+            }
+        }
+        if (consumed >= JOURNAL_ENTRY_MAX_COUNT ||
+            inspectedBytes >= JOURNAL_TOTAL_MAX_BYTES ||
+            retainedBytes >= JOURNAL_TOTAL_MAX_BYTES) {
+            truncated = true;
+            break;
+        }
+    }
+    return { entries: result, truncated };
+}
+function errorMessage(error) {
+    try {
+        return error instanceof Error ? error.message : String(error);
+    }
+    catch {
+        return '[unprintable error]';
+    }
+}
+function sandboxMarkdown(friction) {
+    if (friction.status === 'events')
+        return buildSandboxSection(friction.events);
+    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);
+        if (journal.status === 'ok' && journal.truncated)
+            return {
+                markdown: '## CI Failures\nStatus: unavailable (journal scan incomplete)\n\n' +
+                    sandboxMarkdown(friction),
+            };
+        const markdown = buildCiFailuresSection(sessionId, journal, friction.status);
+        return { markdown: `${markdown}\n\n${sandboxMarkdown(friction)}` };
+    }
+    catch (error) {
+        const ciMarkdown = journal.status === 'ok' && journal.truncated
+            ? '## CI Failures\nStatus: unavailable (journal scan incomplete)'
+            : journal.status === 'ok' && journal.markdownBlocks.length === 0
+                ? '## CI Failures\nStatus: unavailable (friction log unreadable)'
+                : buildCiFailuresSection(sessionId, journal, 'empty');
+        return {
+            markdown: `${ciMarkdown}\n\n## Sandbox & Permission Audit\nStatus: unavailable (friction log unreadable)`,
+            diagnostic: errorMessage(error),
+        };
+    }
+}
+export async function buildSessionFrictionReport(sessionId, options) {
+    validateSessionId(sessionId);
+    requireDirectory(options.directory);
+    eventLimit(options.maxEvents);
+    let journal;
+    try {
+        const loaded = await options.journalLoader(sessionId);
+        if (loaded.status === 'not-found')
+            journal = { status: 'ok', markdownBlocks: [], truncated: false };
+        else {
+            const collected = await collectEntries(loaded.entries);
+            journal = {
+                status: 'ok',
+                markdownBlocks: getConformingGroups(collected.entries),
+                truncated: collected.truncated,
+            };
+        }
+    }
+    catch (error) {
+        const diagnostic = errorMessage(error);
+        journal = { status: 'unreachable', diagnostic };
+    }
+    const report = reportFromLog(sessionId, options, journal);
+    if (journal.status === 'unreachable') {
+        const diagnostic = report.diagnostic
+            ? `${journal.diagnostic}; ${report.diagnostic}`
+            : journal.diagnostic;
+        return { ...report, diagnostic };
+    }
+    return report;
+}

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

@@ -0,0 +1,2 @@
+import type { FrictionEvent } from './types.mts';
+export declare function buildSandboxSection(events: FrictionEvent[]): string;

package/dist/session-friction/sandbox.mjs

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

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

@@ -0,0 +1,2 @@
+export declare function validateSessionId(sessionId: string): void;
+export declare function sanitizeSessionId(sessionId: string): string;

package/dist/session-friction/session-id.mjs

@@ -0,0 +1,17 @@
+import { createHash } from 'node:crypto';
+import { isWellFormedUnicode, normalizeAuditText } from './text.mjs';
+const SESSION_ID_MAX_LENGTH = 4096;
+export function validateSessionId(sessionId) {
+    if (typeof sessionId !== 'string')
+        throw new Error('sessionId must be a string');
+    if (sessionId.length > SESSION_ID_MAX_LENGTH)
+        throw new Error('sessionId is too long');
+    if (!isWellFormedUnicode(sessionId))
+        throw new Error('sessionId must be well-formed Unicode');
+    if (normalizeAuditText(sessionId) === '')
+        throw new Error('sessionId must be non-empty');
+}
+export function sanitizeSessionId(sessionId) {
+    validateSessionId(sessionId);
+    return createHash('sha256').update(sessionId).digest('hex');
+}

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

@@ -0,0 +1,5 @@
+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;

package/dist/session-friction/text.mjs

@@ -0,0 +1,45 @@
+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();
+}
+export function boundedText(value, maximum) {
+    let end = Math.min(value.length, maximum);
+    if (end < value.length &&
+        /[\uD800-\uDBFF]/.test(value[end - 1]) &&
+        /[\uDC00-\uDFFF]/.test(value[end]))
+        end--;
+    return value.slice(0, end);
+}
+export function isWellFormedUnicode(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+            index++;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff)
+            return false;
+    }
+    return true;
+}
+export function isSafeAuditText(value) {
+    return (typeof value === 'string' &&
+        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)
+            break;
+        result += escaped;
+    }
+    return result;
+}

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

@@ -0,0 +1,52 @@
+export type FrictionEventKind = 'sandbox-escalation' | 'sandbox-failure';
+export type FrictionEvent = {
+    kind: FrictionEventKind;
+    timestamp: string;
+    commandPrefix: string;
+    detail: string;
+};
+export type ToolResultObservation = {
+    type: 'tool-result';
+    command: string;
+    commandWrappers?: string[];
+    escalationDetail?: string;
+    structuredStderr?: string;
+};
+export type PermissionRequestObservation = {
+    type: 'permission-request';
+    command: string;
+    commandWrappers?: string[];
+};
+export type FrictionObservation = ToolResultObservation | PermissionRequestObservation;
+export type FrictionLogReadResult = {
+    status: 'absent';
+} | {
+    status: 'empty';
+} | {
+    status: 'events';
+    events: FrictionEvent[];
+};
+export type FrictionLogOptions = {
+    directory: string;
+    maxEvents?: number;
+};
+export type JournalEntry = {
+    data?: {
+        type?: unknown;
+        markdown?: unknown;
+    };
+};
+export type JournalLoadResult = {
+    status: 'ok';
+    entries: Iterable<JournalEntry> | AsyncIterable<JournalEntry>;
+} | {
+    status: 'not-found';
+};
+export type JournalLoader = (sessionId: string) => JournalLoadResult | Promise<JournalLoadResult>;
+export type SessionFrictionReport = {
+    markdown: string;
+    diagnostic?: string;
+};
+export type SessionFrictionReportOptions = FrictionLogOptions & {
+    journalLoader: JournalLoader;
+};

package/dist/session-friction/types.mjs

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export declare function decodeUtf8(value: Uint8Array): string;

package/dist/session-friction/utf8.mjs

@@ -0,0 +1,8 @@
+export function decodeUtf8(value) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(value);
+    }
+    catch {
+        throw new Error('session-friction log is not valid UTF-8');
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -41,6 +41,11 @@
       "import": "./dist/retrospective-transcript/index.mjs",
       "default": "./dist/retrospective-transcript/index.mjs"
     },
+    "./session-friction": {
+      "types": "./dist/session-friction/index.d.mts",
+      "import": "./dist/session-friction/index.mjs",
+      "default": "./dist/session-friction/index.mjs"
+    },
     "./sql-ast": {
       "types": "./dist/sql-ast/index.d.mts",
       "import": "./dist/sql-ast/index.mjs",

package/scripts/gha/download-optional-run-artifacts.sh

@@ -71,15 +71,39 @@ download_exact() {
   GH_HOST="$github_host" gh run download "$GITHUB_RUN_ID" --repo "$repository" --name "$artifact" --dir "$directory"
 }
 
-list_artifact_names() {
+list_artifact_names_once() {
   GH_HOST="$github_host" gh api \
     --paginate \
     "repos/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID/artifacts?per_page=100" \
     --jq '.artifacts[] | select(.expired | not) | .name'
 }
 
+list_artifact_names() {
+  local attempt status=0 delay artifact_names
+  for attempt in 1 2 3; do
+    if artifact_names=$(list_artifact_names_once); then
+      [ -z "$artifact_names" ] || printf '%s\n' "$artifact_names"
+      return 0
+    else
+      status=$?
+    fi
+    case "$status" in 130|143) return "$status" ;; esac
+    if [ "$attempt" -lt 3 ]; then
+      delay=2
+      [ "$attempt" -eq 2 ] && delay=5
+      echo "::warning::Optional same-run artifact listing failed (attempt $attempt/3 exit=$status); retrying in ${delay}s" >&2
+      if sleep "$delay"; then :; else return $?; fi
+    fi
+  done
+  echo "[optional-run-artifacts] listing exhausted attempts=3 exit=$status" >&2
+  return "$status"
+}
+
 download_pattern() {
-  artifacts=$(list_artifact_names | awk '!seen[$0]++') || return $?
+  artifacts=$(list_artifact_names) || return $?
+  if [ -n "$artifacts" ]; then
+    artifacts=$(printf '%s\n' "$artifacts" | awk '!seen[$0]++')
+  fi
   selected_artifacts=()
   while IFS= read -r artifact; do
     [ -n "$artifact" ] || continue