@astudioplus/compressor 0.1.0

package/dist/engine/tiers/structural.js

@@ -0,0 +1,199 @@
+import { OMISSION_MARKER } from "../types.js";
+export function tierResult(before, after, id) {
+    if (after === before)
+        return { content: before };
+    return { content: after, transform: { id, charsSaved: before.length - after.length } };
+}
+const ANSI_RE = /\u001b\[[0-9;:<=>?]*[ -\/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b[@-_]/g;
+// strips remaining C0 controls and DEL, but never \t (0x09) or \n (0x0a)
+const CONTROL_RE = /[\u0000-\u0008\u000b-\u001f\u007f]/g;
+export function stripAnsi(content) {
+    const next = content.replace(ANSI_RE, '').replace(CONTROL_RE, '');
+    return tierResult(content, next, 'strip-ansi');
+}
+const BLANK_RE = /^[ \t]*$/;
+export function collapseBlankRuns(content) {
+    const lines = content.split('\n');
+    const out = [];
+    let run = [];
+    const flush = () => {
+        if (run.length === 0)
+            return;
+        if (run.length >= 3)
+            out.push('');
+        else
+            out.push(...run);
+        run = [];
+    };
+    for (const line of lines) {
+        if (BLANK_RE.test(line)) {
+            run.push(line);
+            continue;
+        }
+        flush();
+        out.push(line);
+    }
+    flush();
+    return tierResult(content, out.join('\n'), 'collapse-blank');
+}
+export function dedupeLines(content) {
+    const lines = content.split('\n');
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line === undefined)
+            break;
+        let run = 1;
+        while (i + run < lines.length && lines[i + run] === line)
+            run += 1;
+        if (run >= 3 && line.trim() !== '') {
+            out.push(line, `[compressor: previous line repeated ${run - 1} more times]`);
+        }
+        else {
+            for (let k = 0; k < run; k += 1)
+                out.push(line);
+        }
+        i += run;
+    }
+    return tierResult(content, out.join('\n'), 'dedupe-lines');
+}
+// Claude Code Read prefixes: "   123→content" (U+2192) or tab-separated variants.
+const LINE_NUM_CAPTURE_RE = /^ *(\d+)(?:→|\t)/;
+export function lineNumberOf(line) {
+    const digits = LINE_NUM_CAPTURE_RE.exec(line)?.[1];
+    return digits === undefined ? undefined : Number(digits);
+}
+// 'informative' marker style: what the omitted region contains, so the model
+// can skip it or retrieve surgically instead of paginating the whole file.
+const FAILURE_LINE_RE = /\b(error|fail(ed|ure)?|warn(ing)?|exception|panic|fatal)\b/i;
+/**
+ * Scan omitted lines for error/failure/warning content. Original coordinates
+ * follow the same rules as the marker math: embedded Read line numbers are
+ * authoritative; `firstFileLine + index` is the fallback when the caller
+ * vouches that positions are file lines. Marker lines inserted by earlier
+ * tiers in this run are never counted as content.
+ */
+export function scanFailureLines(lines, firstFileLine) {
+    let count = 0;
+    const found = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line === undefined || line.includes(OMISSION_MARKER))
+            continue;
+        if (!FAILURE_LINE_RE.test(line))
+            continue;
+        count += 1;
+        if (found.length < 3) {
+            const n = lineNumberOf(line) ?? (firstFileLine === undefined ? undefined : firstFileLine + i);
+            if (n !== undefined)
+                found.push(n);
+        }
+    }
+    return { count, lines: found };
+}
+/** "L1, L2, L3 (first 3)" — the qualifier only when matches were truncated. */
+export function formatMatchLines(scan) {
+    return scan.lines.join(', ') + (scan.count > 3 ? ' (first 3)' : '');
+}
+export function omissionMarker(a, b, estTokens, meta, style, omittedLines) {
+    const head = `[compressor: lines ${a}-${b} omitted (~${estTokens} est tokens)`;
+    const limit = b - a + 1;
+    if (meta.tool === 'read' && meta.filePath !== undefined) {
+        const file = meta.filePath;
+        if (style === 'deterrent') {
+            return `${head} — likely irrelevant; Read ${file} offset=${a} limit=${limit} ONLY if the problem you are chasing points into this range]`;
+        }
+        if (style === 'informative') {
+            const scan = scanFailureLines(omittedLines, a);
+            if (scan.count === 0) {
+                return `${head} — no error/failure/warning lines in the omitted range; safe to skip. Read ${file} offset=${a} limit=${limit} only if needed]`;
+            }
+            const nearest = scan.lines[0] ?? a;
+            return `${head} — ${scan.count} lines matching error/fail/warn at lines ${formatMatchLines(scan)} — Read ${file} offset=${nearest} limit=20 for the nearest match; full range offset=${a} limit=${limit}]`;
+        }
+        return `${head} — Read ${file} with offset=${a} and limit=${limit} to retrieve]`;
+    }
+    if (style === 'deterrent') {
+        return `${head} — likely irrelevant; re-run with a narrower filter (grep, --quiet, head) ONLY if the problem you are chasing points into this range]`;
+    }
+    if (style === 'informative') {
+        const scan = scanFailureLines(omittedLines, a);
+        if (scan.count === 0) {
+            return `${head} — no error/failure/warning lines in the omitted range; safe to skip. Re-run with a narrower filter (grep, --quiet, head) only if needed]`;
+        }
+        return `${head} — ${scan.count} lines matching error/fail/warn at lines ${formatMatchLines(scan)} — re-run with a narrower filter (grep, --quiet, head) to retrieve]`;
+    }
+    return `${head} — re-run with a narrower filter (grep, --quiet, head) to retrieve]`;
+}
+/** For omissions whose original file line range is unknown: no offset/limit claim. */
+function countMarker(count, unit, estTokens, meta, style, omitted) {
+    const head = `[compressor: ${count} ${unit} omitted (~${estTokens} est tokens)`;
+    if (meta.tool === 'read' && meta.filePath !== undefined) {
+        const file = meta.filePath;
+        if (style === 'deterrent') {
+            return `${head} — likely irrelevant; Read ${file} ONLY if the problem you are chasing points into the omitted content]`;
+        }
+        if (style === 'informative') {
+            const matches = scanFailureLines(omitted.split('\n')).count;
+            return matches === 0
+                ? `${head} — no error/failure/warning lines in the omitted content; safe to skip. Read ${file} only if needed]`
+                : `${head} — ${matches} lines matching error/fail/warn in the omitted content — Read ${file} to retrieve]`;
+        }
+        return `${head} — Read ${file} to retrieve]`;
+    }
+    if (style === 'deterrent') {
+        return `${head} — likely irrelevant; re-run with a narrower filter (grep, --quiet, head) ONLY if the problem you are chasing points into the omitted content]`;
+    }
+    if (style === 'informative') {
+        const matches = scanFailureLines(omitted.split('\n')).count;
+        return matches === 0
+            ? `${head} — no error/failure/warning lines in the omitted content; safe to skip. Re-run with a narrower filter (grep, --quiet, head) only if needed]`
+            : `${head} — ${matches} lines matching error/fail/warn in the omitted content — re-run with a narrower filter (grep, --quiet, head) to retrieve]`;
+    }
+    return `${head} — re-run with a narrower filter (grep, --quiet, head) to retrieve]`;
+}
+/** Fallback for content too few-lined to truncate by lines (minified blobs etc.). */
+function truncateChars(content, meta, policy, estimate) {
+    const est = estimate(content);
+    const ratio = policy.truncateBudget / est;
+    const headChars = Math.max(1, Math.floor(content.length * ratio * 0.6));
+    const tailChars = Math.max(1, Math.floor(content.length * ratio * 0.4));
+    if (headChars + tailChars >= content.length)
+        return { content };
+    const omitted = content.slice(headChars, content.length - tailChars);
+    const marker = countMarker(omitted.length, 'chars', estimate(omitted), meta, policy.markerStyle, omitted);
+    const next = `${content.slice(0, headChars)}\n${marker}\n${content.slice(content.length - tailChars)}`;
+    return tierResult(content, next, 'truncate');
+}
+export function truncateHeadTail(content, meta, policy, estimate, positionsAreFileLines = true) {
+    const est = estimate(content);
+    if (est <= policy.truncateBudget)
+        return { content };
+    const lines = content.split('\n');
+    const total = lines.length;
+    const ratio = policy.truncateBudget / est;
+    const keep = Math.max(2, Math.floor(total * ratio));
+    if (keep >= total)
+        return truncateChars(content, meta, policy, estimate);
+    const headCount = Math.max(1, Math.floor(keep * 0.6));
+    const tailCount = Math.max(1, keep - headCount);
+    const omitStart = headCount + 1;
+    const omitEnd = total - tailCount;
+    if (omitEnd < omitStart)
+        return { content };
+    const omittedLines = lines.slice(headCount, total - tailCount);
+    const omitted = omittedLines.join('\n');
+    const estOmitted = estimate(omitted);
+    // Embedded Read line numbers are authoritative for the file range; array
+    // positions are valid file lines only when no earlier tier removed lines.
+    const a = lineNumberOf(omittedLines[0] ?? '');
+    const b = lineNumberOf(omittedLines[omittedLines.length - 1] ?? '');
+    const marker = a !== undefined && b !== undefined && a <= b
+        ? omissionMarker(a, b, estOmitted, meta, policy.markerStyle, omittedLines)
+        : positionsAreFileLines
+            ? omissionMarker(omitStart, omitEnd, estOmitted, meta, policy.markerStyle, omittedLines)
+            : countMarker(omittedLines.length, 'lines', estOmitted, meta, policy.markerStyle, omitted);
+    const next = [...lines.slice(0, headCount), marker, ...lines.slice(total - tailCount)].join('\n');
+    return tierResult(content, next, 'truncate');
+}

package/dist/engine/types.d.ts

@@ -0,0 +1,71 @@
+/** Operating mode. 'full' = no optimization anywhere. */
+export type Mode = 'full' | 'optimized' | 'slim';
+/** What produced the content being compressed. */
+export type ToolKind = 'read' | 'bash' | 'search' | 'other';
+/** Detected content kind, used to pick transforms. */
+export type ContentKind = 'code' | 'test-log' | 'build-log' | 'generic';
+export interface CompressMeta {
+    tool: ToolKind;
+    mode: Mode;
+    /** Source file path when known (drives code detection by extension). */
+    filePath?: string;
+    /**
+     * True when the model explicitly requested a range (Read offset/limit).
+     * Targeted reads always pass through untouched.
+     */
+    targeted?: boolean;
+}
+/**
+ * Token estimator injected by the caller (engine stays dependency-free and
+ * pure). Estimates are used ONLY for threshold decisions, never reported as
+ * savings.
+ */
+export type Estimator = (text: string) => number;
+/**
+ * Omission-marker phrasing. Measured (bench-20260610-114234): the plain
+ * recovery affordance invites whole-file pagination via targeted reads,
+ * nullifying savings on ~half of cells. 'deterrent' frames recovery as
+ * conditional; 'informative' additionally reports what the omitted region
+ * contains (failure-pattern scan) so the model can skip or retrieve
+ * surgically.
+ */
+export type MarkerStyle = 'plain' | 'deterrent' | 'informative';
+/** All thresholds are estimated tokens. Content below `touch` is never modified. */
+export interface Policy {
+    structural: boolean;
+    codeAware: boolean;
+    logAware: boolean;
+    markerStyle: MarkerStyle;
+    /** below this, return input unchanged */
+    touch: number;
+    /** head/tail truncation budget for a single tool result */
+    truncateBudget: number;
+    /** strip comment-only/blank lines in code above this */
+    commentStrip: number;
+    /** skeleton view (imports + signatures) above this; Infinity = never */
+    skeleton: number;
+    /** apply test/build log filtering above this; Infinity = never */
+    logFilter: number;
+}
+export interface AppliedTransform {
+    /** e.g. 'strip-ansi', 'dedupe-lines', 'truncate', 'comment-strip', 'skeleton', 'log-filter' */
+    id: string;
+    charsSaved: number;
+}
+export interface CompressStats {
+    bytesIn: number;
+    bytesOut: number;
+    estTokensIn: number;
+    estTokensOut: number;
+    kind: ContentKind;
+    transforms: AppliedTransform[];
+}
+export interface CompressResult {
+    content: string;
+    stats: CompressStats;
+}
+/**
+ * Marker wrapped around every omission so the model can recover what was cut.
+ * Content already containing this marker is never re-compressed (idempotency).
+ */
+export declare const OMISSION_MARKER = "[compressor:";

package/dist/engine/types.js

@@ -0,0 +1,5 @@
+/**
+ * Marker wrapped around every omission so the model can recover what was cut.
+ * Content already containing this marker is never re-compressed (idempotency).
+ */
+export const OMISSION_MARKER = '[compressor:';

package/dist/hook/copilot.d.ts

@@ -0,0 +1,5 @@
+import type { MarkerStyle, Mode } from '../engine/types.ts';
+export interface CopilotHookResult {
+    output: string | null;
+}
+export declare function handleCopilotPostToolUse(payloadJson: string, mode: Mode, markerStyle?: MarkerStyle): CopilotHookResult;

package/dist/hook/copilot.js

@@ -0,0 +1,136 @@
+import { compressCall, isRecord, pickLeaf, rebuildWithLeaf, recordCompression } from "./core.js";
+/** Copilot CLI / cloud-agent built-in tool names → engine ToolKind. */
+function toolKindFor(toolName) {
+    switch (toolName) {
+        case 'view':
+            return 'read';
+        case 'bash':
+        case 'powershell':
+            return 'bash';
+        case 'grep':
+        case 'glob':
+            return 'search';
+        default:
+            return 'other';
+    }
+}
+// `toolArgs` is documented only as `unknown`, so the view tool's argument
+// names are sniffed liberally and fail open: no match means no filePath /
+// not targeted, which only ever makes compression more conservative.
+const FILE_PATH_KEYS = ['path', 'filePath', 'file_path', 'file'];
+/**
+ * The reference page types toolArgs as `unknown`, but the CLI docs' only
+ * concrete payload example shows it as a JSON-ENCODED STRING
+ * ("toolArgs":"{\"command\":\"ls\"}"). Accept both forms: object as-is,
+ * string via JSON.parse. Anything else (or unparseable) falls back to {} —
+ * fail open: no filePath, not targeted, compression stays conservative.
+ */
+function parseToolArgs(raw) {
+    if (isRecord(raw)) {
+        return raw;
+    }
+    if (typeof raw === 'string') {
+        try {
+            const parsed = JSON.parse(raw);
+            if (isRecord(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // fall through to {}
+        }
+    }
+    return {};
+}
+const RANGE_KEYS = [
+    'offset',
+    'limit',
+    'startLine',
+    'endLine',
+    'start_line',
+    'end_line',
+    'range',
+    'viewRange',
+    'view_range',
+];
+function filePathFrom(args) {
+    for (const key of FILE_PATH_KEYS) {
+        const value = args[key];
+        if (typeof value === 'string') {
+            return value;
+        }
+    }
+    return undefined;
+}
+function isTargeted(args) {
+    return RANGE_KEYS.some((key) => args[key] != null);
+}
+export function handleCopilotPostToolUse(payloadJson, mode, markerStyle) {
+    try {
+        if (mode === 'full') {
+            return { output: null };
+        }
+        const payload = JSON.parse(payloadJson);
+        if (!isRecord(payload)) {
+            return { output: null };
+        }
+        const toolName = typeof payload['toolName'] === 'string' ? payload['toolName'] : '';
+        const toolArgs = parseToolArgs(payload['toolArgs']);
+        const tool = toolKindFor(toolName);
+        const toolResult = payload['toolResult'];
+        // postToolUse is success-only; if a non-success result ever arrives,
+        // emitting modifiedResult (which forces resultType "success") would
+        // rewrite a failure into a success. Never do that.
+        if (isRecord(toolResult) &&
+            toolResult['resultType'] !== undefined &&
+            toolResult['resultType'] !== 'success') {
+            return { output: null };
+        }
+        // Documented shape: the text the model sees is toolResult.textResultForLlm.
+        // Unknown shapes fall back to the generic longest-string-leaf walk.
+        let text = null;
+        let genericLeaf = null;
+        if (isRecord(toolResult) && typeof toolResult['textResultForLlm'] === 'string') {
+            text = toolResult['textResultForLlm'];
+        }
+        else {
+            genericLeaf = pickLeaf(toolResult, tool);
+            if (genericLeaf === null) {
+                return { output: null };
+            }
+            text = genericLeaf.text;
+        }
+        const call = {
+            toolKind: tool,
+            targeted: tool === 'read' && isTargeted(toolArgs),
+            text,
+        };
+        const filePath = tool === 'read' ? filePathFrom(toolArgs) : undefined;
+        if (filePath !== undefined) {
+            call.filePath = filePath;
+        }
+        const compressed = compressCall(call, mode, markerStyle);
+        if (!compressed.worthwhile) {
+            return { output: null };
+        }
+        recordCompression('copilot', call, compressed, mode);
+        // The replacement schema carries exactly one string. Documented shape (or
+        // a bare-string result): the compressed text IS the replacement. Unknown
+        // structured shapes: rebuild the structure with only the big leaf
+        // rewritten (siblings preserved) and render it as JSON.
+        const replacement = genericLeaf === null || genericLeaf.path.length === 0
+            ? compressed.text
+            : JSON.stringify(rebuildWithLeaf(toolResult, genericLeaf.path, compressed.text));
+        return {
+            output: JSON.stringify({
+                modifiedResult: {
+                    resultType: 'success',
+                    textResultForLlm: replacement,
+                },
+            }),
+        };
+    }
+    catch {
+        return { output: null };
+    }
+}

package/dist/hook/core.d.ts

@@ -0,0 +1,36 @@
+import type { CompressStats, MarkerStyle, Mode, ToolKind } from '../engine/types.ts';
+export interface CompressibleCall {
+    toolKind: ToolKind;
+    filePath?: string;
+    targeted: boolean;
+    text: string;
+}
+export interface CompressedCall {
+    text: string;
+    /** false = leave the tool output alone (below floor, marker present, throw) */
+    worthwhile: boolean;
+    /** engine stats for the worthwhile case (ledger needs tokens/transforms) */
+    stats?: CompressStats;
+}
+export declare function compressCall(call: CompressibleCall, mode: Mode, markerStyle?: MarkerStyle): CompressedCall;
+/**
+ * Fire-and-forget ledger entry for a worthwhile compression. Called by the
+ * protocol layers (they know which agent they serve). Never awaited on the
+ * hot path; the hook entries settle pending writes (capped at 250ms) before
+ * exiting. Privacy: sizes and transform ids only — no paths, no content.
+ */
+export declare function recordCompression(agent: 'claude-code' | 'copilot', call: CompressibleCall, compressed: CompressedCall, mode: Mode): void;
+export type LeafPath = ReadonlyArray<string | number>;
+export interface Leaf {
+    path: LeafPath;
+    text: string;
+}
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Find the single string worth compressing in a tool response of unknown
+ * shape: a bare string directly, a bash stdout field when present, otherwise
+ * the longest string leaf anywhere in the structure.
+ */
+export declare function pickLeaf(toolResponse: unknown, tool: ToolKind): Leaf | null;
+/** Shape-preserving rewrite: clone the response with only the leaf replaced. */
+export declare function rebuildWithLeaf(toolResponse: unknown, path: LeafPath, text: string): unknown;

package/dist/hook/core.js

@@ -0,0 +1,138 @@
+import { OMISSION_MARKER } from "../engine/types.js";
+import { compress, policyFor } from "../engine/index.js";
+import { cheapEstimator } from "../tokens/estimate.js";
+import { appendLedger } from "../ledger/write.js";
+/** Below either floor the rewrite is noise: don't churn the context. */
+const MIN_SAVED_CHARS = 200;
+const MIN_SAVED_RATIO = 0.1;
+/**
+ * Length of the compressed output EXCLUDING marker lines, mirroring the
+ * engine's decide() filter (engine/index.ts). The floors must be measured
+ * against content only: marker text is the marker-style experiment's
+ * treatment (informative/deterrent markers run ~50-120 chars longer than
+ * plain, multiplied by one marker per skeleton gap), so a marker-inclusive
+ * `saved` lets arms flip between compressed and full passthrough near either
+ * floor — the arms would then differ in WHAT the model sees, not just in
+ * marker phrasing, and the treatment marker would be absent exactly when
+ * phrasing is being compared.
+ */
+function lengthSansMarkers(text) {
+    if (!text.includes(OMISSION_MARKER)) {
+        return text.length;
+    }
+    return text
+        .split('\n')
+        .filter((line) => !line.includes(OMISSION_MARKER))
+        .join('\n').length;
+}
+export function compressCall(call, mode, markerStyle) {
+    try {
+        const meta = { tool: call.toolKind, mode, targeted: call.targeted };
+        if (call.filePath !== undefined) {
+            meta.filePath = call.filePath;
+        }
+        const base = policyFor(mode);
+        const policy = markerStyle === undefined ? base : { ...base, markerStyle };
+        const result = compress(call.text, meta, policy, cheapEstimator);
+        // marker-stripped so worthwhileness is style-invariant (see above)
+        const saved = call.text.length - lengthSansMarkers(result.content);
+        if (saved < MIN_SAVED_CHARS || saved < call.text.length * MIN_SAVED_RATIO) {
+            return { text: call.text, worthwhile: false };
+        }
+        return { text: result.content, worthwhile: true, stats: result.stats };
+    }
+    catch {
+        // FAIL-OPEN: a broken hook must never break the user's agent.
+        return { text: call.text, worthwhile: false };
+    }
+}
+/**
+ * Fire-and-forget ledger entry for a worthwhile compression. Called by the
+ * protocol layers (they know which agent they serve). Never awaited on the
+ * hot path; the hook entries settle pending writes (capped at 250ms) before
+ * exiting. Privacy: sizes and transform ids only — no paths, no content.
+ */
+export function recordCompression(agent, call, compressed, mode) {
+    try {
+        if (!compressed.worthwhile) {
+            return;
+        }
+        void appendLedger({
+            ts: new Date().toISOString(),
+            agent,
+            tool: call.toolKind,
+            mode,
+            charsIn: call.text.length,
+            charsOut: compressed.text.length,
+            estTokensIn: compressed.stats?.estTokensIn ?? cheapEstimator(call.text),
+            estTokensOut: compressed.stats?.estTokensOut ?? cheapEstimator(compressed.text),
+            transforms: compressed.stats?.transforms.map((t) => t.id) ?? [],
+        }).catch(() => { });
+    }
+    catch {
+        // FAIL-OPEN: the ledger must never break the hook.
+    }
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function longestStringLeaf(value, path, best) {
+    if (typeof value === 'string') {
+        return best === null || value.length > best.text.length ? { path, text: value } : best;
+    }
+    if (Array.isArray(value)) {
+        return value.reduce((acc, item, i) => longestStringLeaf(item, [...path, i], acc), best);
+    }
+    if (isRecord(value)) {
+        return Object.entries(value).reduce((acc, [key, item]) => longestStringLeaf(item, [...path, key], acc), best);
+    }
+    return best;
+}
+/**
+ * Find the single string worth compressing in a tool response of unknown
+ * shape: a bare string directly, a bash stdout field when present, otherwise
+ * the longest string leaf anywhere in the structure.
+ */
+export function pickLeaf(toolResponse, tool) {
+    if (typeof toolResponse === 'string') {
+        return { path: [], text: toolResponse };
+    }
+    if (tool === 'bash' && isRecord(toolResponse) && typeof toolResponse['stdout'] === 'string') {
+        return { path: ['stdout'], text: toolResponse['stdout'] };
+    }
+    if (isRecord(toolResponse) || Array.isArray(toolResponse)) {
+        return longestStringLeaf(toolResponse, [], null);
+    }
+    return null;
+}
+/** Shape-preserving rewrite: clone the response with only the leaf replaced. */
+export function rebuildWithLeaf(toolResponse, path, text) {
+    if (path.length === 0) {
+        return text;
+    }
+    const clone = structuredClone(toolResponse);
+    let cursor = clone;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const key = path[i];
+        if (Array.isArray(cursor) && typeof key === 'number') {
+            cursor = cursor[key];
+        }
+        else if (isRecord(cursor) && typeof key === 'string') {
+            cursor = cursor[key];
+        }
+        else {
+            throw new Error('leaf path mismatch');
+        }
+    }
+    const last = path[path.length - 1];
+    if (Array.isArray(cursor) && typeof last === 'number') {
+        cursor[last] = text;
+    }
+    else if (isRecord(cursor) && typeof last === 'string') {
+        cursor[last] = text;
+    }
+    else {
+        throw new Error('leaf path mismatch');
+    }
+    return clone;
+}

package/dist/hook/exit.d.ts

@@ -0,0 +1,22 @@
+/** Hard cap on how long pending ledger appends may delay hook exit. */
+export declare const SETTLE_CAP_MS = 250;
+/**
+ * Deliver hook output, give in-flight ledger appends up to SETTLE_CAP_MS to
+ * flush, then guarantee process termination. Shared by both bundled hook
+ * entries and the CLI `hook` subcommands — every protocol surface gets the
+ * same hot-path bound. Never throws (fail-open).
+ *
+ * Order matters: stdout is written BEFORE the settle race, so marker delivery
+ * never serializes behind ledger filesystem latency.
+ *
+ * The cap alone only bounds the JS await. On modern Node (>= ~22),
+ * process.exit() performs a clean shutdown that joins the libuv threadpool;
+ * an appendFile blocked in open(2) (hung NFS/SMB home dir, dead FUSE mount,
+ * reader-less FIFO) never returns, so that join never completes and the
+ * process lives forever — stalling the agent for its hook timeout, or
+ * indefinitely on hosts without one. When the race times out we therefore
+ * terminate with SIGKILL: kernel-level, bypasses the threadpool join. The
+ * resulting non-zero exit makes the host ignore this call's stdout, which is
+ * still fail-open — the original tool output passes through unmodified.
+ */
+export declare function settleThenExit(output: string | null): Promise<void>;

package/dist/hook/exit.js

@@ -0,0 +1,56 @@
+import process from 'node:process';
+import { settleLedger } from "../ledger/write.js";
+/** Hard cap on how long pending ledger appends may delay hook exit. */
+export const SETTLE_CAP_MS = 250;
+/**
+ * Deliver hook output, give in-flight ledger appends up to SETTLE_CAP_MS to
+ * flush, then guarantee process termination. Shared by both bundled hook
+ * entries and the CLI `hook` subcommands — every protocol surface gets the
+ * same hot-path bound. Never throws (fail-open).
+ *
+ * Order matters: stdout is written BEFORE the settle race, so marker delivery
+ * never serializes behind ledger filesystem latency.
+ *
+ * The cap alone only bounds the JS await. On modern Node (>= ~22),
+ * process.exit() performs a clean shutdown that joins the libuv threadpool;
+ * an appendFile blocked in open(2) (hung NFS/SMB home dir, dead FUSE mount,
+ * reader-less FIFO) never returns, so that join never completes and the
+ * process lives forever — stalling the agent for its hook timeout, or
+ * indefinitely on hosts without one. When the race times out we therefore
+ * terminate with SIGKILL: kernel-level, bypasses the threadpool join. The
+ * resulting non-zero exit makes the host ignore this call's stdout, which is
+ * still fail-open — the original tool output passes through unmodified.
+ */
+export async function settleThenExit(output) {
+    try {
+        if (output !== null) {
+            await new Promise((resolve) => {
+                process.stdout.write(output, () => resolve());
+            });
+        }
+    }
+    catch {
+        // fail-open: EPIPE etc. — still settle the ledger and exit below
+    }
+    // default true: if anything below throws, take the kernel-level exit
+    let timedOut = true;
+    try {
+        let timer;
+        timedOut = await Promise.race([
+            settleLedger().then(() => false),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(true), SETTLE_CAP_MS);
+            }),
+        ]);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        timedOut = true;
+    }
+    if (timedOut) {
+        process.kill(process.pid, 'SIGKILL');
+    }
+    process.exit(0);
+}