peaks-loop 4.0.3 → 4.0.5

package/dist/services/compact-statusline/compact-lifecycle-store.js

@@ -0,0 +1,222 @@
+// src/services/compact-statusline/compact-lifecycle-store.ts
+//
+// Slice 2026-08-01-compact-lifecycle (Task 1/5). Pure persistence
+// for the runtime *compact lifecycle* record that the auto-compact
+// orchestrator writes on every state transition. The record is the
+// single source of truth that downstream statusline / dashboard
+// consumers (Tasks 2-5) read to decide what to display.
+//
+// Storage:
+//   .peaks/_runtime/<sessionId>/compact-lifecycle.json
+//
+// Writes go through a temp-file-then-rename in the same directory,
+// so a crash mid-write never leaves a half-written record. Reads
+// validate parsed values explicitly (numeric ranges, stage enum,
+// terminal-stage semantics) and return a tagged union so callers
+// can distinguish `missing` / `valid` / `invalid` / `stalled`.
+//
+// Stalled detection: an **active** stage (queued / preparing /
+// compacting / verifying) is `stalled` when (nowMs - updatedAt) >
+// staleAfterMs. Terminal stages (`completed`, `failed`) NEVER go
+// stalled — the record is the historical answer, not a heartbeat.
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getSessionDir } from '../session/getSessionDir.js';
+const LIFECYCLE_FILENAME = 'compact-lifecycle.json';
+const ERROR_SUMMARY_MAX = 160;
+const ACTIVE_STAGES = [
+    'queued',
+    'preparing',
+    'compacting',
+    'verifying',
+];
+const ALL_STAGES = [
+    'queued',
+    'preparing',
+    'compacting',
+    'verifying',
+    'completed',
+    'failed',
+];
+function lifecyclePath(projectRoot, sessionId) {
+    return join(getSessionDir(projectRoot, sessionId), LIFECYCLE_FILENAME);
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isStage(v) {
+    return typeof v === 'string' && ALL_STAGES.includes(v);
+}
+function isActiveStage(stage) {
+    return ACTIVE_STAGES.includes(stage);
+}
+function isFiniteRatio(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1;
+}
+function coerceRecord(raw) {
+    if (!isPlainObject(raw)) {
+        throw new Error('compact-lifecycle: root must be a JSON object');
+    }
+    if (raw['schemaVersion'] !== 1) {
+        throw new Error(`compact-lifecycle: schemaVersion must be 1 (got ${JSON.stringify(raw['schemaVersion'])})`);
+    }
+    if (typeof raw['runId'] !== 'string' || raw['runId'].length === 0) {
+        throw new Error('compact-lifecycle: runId must be a non-empty string');
+    }
+    if (!isStage(raw['stage'])) {
+        throw new Error(`compact-lifecycle: stage must be one of ${ALL_STAGES.join('|')} (got ${JSON.stringify(raw['stage'])})`);
+    }
+    if (typeof raw['updatedAt'] !== 'string' || Number.isNaN(Date.parse(raw['updatedAt']))) {
+        throw new Error('compact-lifecycle: updatedAt must be an ISO 8601 string');
+    }
+    if (!isFiniteRatio(raw['triggerRatio'])) {
+        throw new Error(`compact-lifecycle: triggerRatio must be a finite number in [0,1] (got ${JSON.stringify(raw['triggerRatio'])})`);
+    }
+    if (raw['afterRatio'] !== undefined && !isFiniteRatio(raw['afterRatio'])) {
+        throw new Error(`compact-lifecycle: afterRatio must be a finite number in [0,1] (got ${JSON.stringify(raw['afterRatio'])})`);
+    }
+    if (typeof raw['redLine'] !== 'boolean') {
+        throw new Error(`compact-lifecycle: redLine must be a boolean (got ${JSON.stringify(raw['redLine'])})`);
+    }
+    const stage = raw['stage'];
+    if (stage === 'failed') {
+        const failedAt = raw['failedAt'];
+        if (!isStage(failedAt) || failedAt === 'failed' || failedAt === 'completed') {
+            throw new Error(`compact-lifecycle: failedAt must be one of the active stages (got ${JSON.stringify(failedAt)})`);
+        }
+        const errorSummary = raw['errorSummary'];
+        if (errorSummary !== undefined && typeof errorSummary !== 'string') {
+            throw new Error(`compact-lifecycle: errorSummary must be a string when provided (got ${JSON.stringify(errorSummary)})`);
+        }
+        return {
+            schemaVersion: 1,
+            runId: raw['runId'],
+            stage,
+            updatedAt: raw['updatedAt'],
+            triggerRatio: raw['triggerRatio'],
+            redLine: raw['redLine'],
+            failedAt: failedAt,
+            ...(raw['afterRatio'] !== undefined ? { afterRatio: raw['afterRatio'] } : {}),
+            ...(errorSummary !== undefined ? { errorSummary: errorSummary } : {}),
+        };
+    }
+    // Non-failed records must NOT carry a failedAt or errorSummary.
+    if (raw['failedAt'] !== undefined) {
+        throw new Error('compact-lifecycle: failedAt is only allowed when stage="failed"');
+    }
+    if (raw['errorSummary'] !== undefined) {
+        throw new Error('compact-lifecycle: errorSummary is only allowed when stage="failed"');
+    }
+    return {
+        schemaVersion: 1,
+        runId: raw['runId'],
+        stage,
+        updatedAt: raw['updatedAt'],
+        triggerRatio: raw['triggerRatio'],
+        redLine: raw['redLine'],
+        ...(raw['afterRatio'] !== undefined ? { afterRatio: raw['afterRatio'] } : {}),
+    };
+}
+function clampErrorSummary(value) {
+    if (value === undefined)
+        return undefined;
+    return value.length > ERROR_SUMMARY_MAX ? value.slice(0, ERROR_SUMMARY_MAX) : value;
+}
+/**
+ * Atomically write a compact lifecycle record. Uses a temp file in
+ * the same directory plus `renameSync`, so a crash mid-write never
+ * leaves a half-written record (atomic on POSIX, near-atomic on
+ * Windows — same contract `24h-mode/store.ts` and
+ * `session-checkpoint-service.ts` use).
+ *
+ * Side effects:
+ *   - creates `<sessionDir>/` if missing
+ *   - clamps `errorSummary` to 160 characters (longer strings are
+ *     truncated at the head, not padded)
+ *   - removes the temp file on rename failure (best effort)
+ *
+ * Throws on I/O failure or validation rejection; the caller decides
+ * whether to retry / log / surface to the user.
+ */
+export function writeCompactLifecycle(input) {
+    const path = lifecyclePath(input.projectRoot, input.sessionId);
+    mkdirSync(dirname(path), { recursive: true });
+    // Validate the record the caller passed BEFORE opening a tmp file,
+    // so a malformed caller doesn't leave a tmp file dangling.
+    // (Re-coercing also catches cases where the caller bypassed TypeScript.)
+    const validated = coerceRecord({
+        ...input.record,
+        errorSummary: clampErrorSummary(input.record.errorSummary),
+    });
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        writeFileSync(tmp, JSON.stringify(validated, null, 2) + '\n', 'utf8');
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // best effort: the OS will reap the tmp file eventually
+        }
+        throw error;
+    }
+}
+/**
+ * Read a compact lifecycle record and classify it.
+ *
+ * Return kinds:
+ *   - `missing`  — no record has ever been written for this session
+ *   - `valid`    — record parsed and validated; stage is terminal
+ *                  (completed/failed) OR is active but still fresh
+ *   - `invalid`  — file exists but is malformed / wrong schema / out
+ *                  of range. `reason` is a single-line English message
+ *                  (no CLI verbs, no stack traces). The caller MUST
+ *                  surface this to a human — we never silently turn
+ *                  a corrupted record into `missing`.
+ *   - `stalled`  — record is valid and is currently an ACTIVE stage,
+ *                  but `updatedAt` is older than `staleAfterMs` (a
+ *                  heartbeat that never arrived). Terminal stages
+ *                  never go stalled.
+ */
+export function readCompactLifecycle(input) {
+    const path = lifecyclePath(input.projectRoot, input.sessionId);
+    if (!existsSync(path)) {
+        return { kind: 'missing' };
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        return {
+            kind: 'invalid',
+            reason: `compact-lifecycle: unable to read record file: ${error.message}`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            kind: 'invalid',
+            reason: `compact-lifecycle: malformed JSON (${error.message})`,
+        };
+    }
+    let record;
+    try {
+        record = coerceRecord(parsed);
+    }
+    catch (error) {
+        return { kind: 'invalid', reason: error.message };
+    }
+    if (isActiveStage(record.stage)) {
+        const updatedAtMs = Date.parse(record.updatedAt);
+        if (!Number.isNaN(updatedAtMs) && input.nowMs - updatedAtMs > input.staleAfterMs) {
+            return { kind: 'stalled', record };
+        }
+    }
+    return { kind: 'valid', record };
+}

package/dist/services/compact-statusline/compact-statusline-service.d.ts

@@ -1,16 +1,36 @@
+import { type CompactLifecycleStage } from './compact-lifecycle-store.js';
+export type CompactDisplayKind = 'none' | 'queued' | 'preparing' | 'compacting' | 'verifying' | 'completed' | 'failed' | 'stalled' | 'invalid';
 export interface CompactStatuslineState {
-    readonly kind: 'missing' | 'idle' | 'pending' | 'red-line' | 'just-compacted';
-    readonly label: string;
+    readonly kind: CompactDisplayKind;
+    readonly filledCells: 0 | 2 | 4 | 6 | 8;
+    readonly triggerRatio?: number;
+    readonly afterRatio?: number;
+    readonly redLine?: boolean;
+    readonly failedAt?: CompactLifecycleStage;
     readonly detail?: string;
 }
+/**
+ * 10-second completed-window expiry. The brief (Task 6 design requirement)
+ * calls out: once a compact lifecycle reaches `completed`, the primary
+ * statusline should surface the success indicator for at most 10 seconds,
+ * then fall back to the C1 baseline so the consumer (the IDE) does not
+ * keep a green ✓ pinned on the status bar indefinitely. The narrow window
+ * is sufficient for the human to see "we just compacted" and long enough
+ * to not flap on subsequent reads. Adjustable after real timing feedback.
+ */
+export declare const COMPLETED_EXPIRY_MS = 10000;
 export declare function decideCompactStatusline(input: {
     readonly projectRoot: string;
     readonly sessionId: string | null;
     readonly now: number;
+    readonly staleAfterMs?: number;
+    readonly completedExpiryMs?: number;
 }): CompactStatuslineState;
 /**
- * Plain-text render: just the label. The LLM embeds this in
- * the Claude Code statusline. Pure: no side effects, no I/O
- * beyond the two file reads.
+ * Plain-text render: the cell bar + a small annotation. The bar is
+ * always the fixed-width 8-cell shape `[████░░░░]`. After-ratio is
+ * only rendered when the lifecycle record carries a real one.
+ *
+ * The output never contains `?` characters — we never guess a ratio.
  */
 export declare function renderCompactStatusline(state: CompactStatuslineState): string;

package/dist/services/compact-statusline/compact-statusline-service.js

@@ -1,83 +1,273 @@
 // src/services/compact-statusline/compact-statusline-service.ts
 //
-// Slice 2026-07-30-compact-visibility (slice 3/4). Pure helper
-// for the 'peaks statusline compact' indicator. Reads
-// .peaks/_runtime/<sessionId>/auto-compact-pending.json +
-// compact-history.jsonl and decides the single-line text
-// the LLM should embed in Claude Code's statusline.
+// Slice 2026-08-01-compact-lifecycle (Task 3/5). Pure semantic
+// decision + render helper for the 'peaks statusline compact'
+// indicator. Reads .peaks/_runtime/<sessionId>/compact-lifecycle.json
+// first (the canonical source of truth) and falls back to the legacy
+// auto-compact-pending.json + compact-history.jsonl only when the
+// lifecycle record is missing.
 //
-// State machine:
-//   - pending: a 'block' intent is sitting in
-//     auto-compact-pending.json → 'compact pending (<ratio>)'
-//   - redLine: pending.redLine === true → 'REDLINE 0.95'
-//   - just-compacted: history has an event within the last
-//     30 seconds → 'just compacted (<from>→<to>)'
-//   - idle: nothing recent → '--'
-//   - missing: no session binding or no orchestrator run yet
-//     → '' (empty)
+// Decision priority (explicit, no implicit fall-through):
+//   1. lifecycle missing  → fall back to legacy (pending → queued,
+//      recent history → completed WITHOUT an invented after-ratio,
+//      else none)
+//   2. lifecycle invalid  → 'invalid' (NEVER fall back to legacy
+//      — a corrupted lifecycle is not a green progress bar)
+//   3. lifecycle valid    → map stage to filledCells via the
+//      documented cell table
+//   4. lifecycle stalled  → 'stalled' kind, retains the cell that
+//      the active stage was holding
+//
+// Cell mapping (frozen first-version contract):
+//   queued     → 0 cells
+//   preparing  → 2 cells
+//   compacting → 4 cells
+//   verifying  → 6 cells
+//   completed  → 8 cells
+//   failed     → keep the failedAt cell (default to compacting = 4)
+//   none       → 0 cells
+//   invalid    → 0 cells (no false reassurance)
+//   stalled    → keep the active stage's cell
+//
+// Render contract: the rendered label is a fixed-width 8-cell bar
+// (`[████░░░░]` filled from the left). NO `?` characters. NO guessed
+// ratios. After-ratio is only rendered when the lifecycle record
+// carries a real one; otherwise the bar shows a stable "no
+// measurement" hint.
 import { existsSync, readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-const JUST_COMPACTED_WINDOW_MS = 30_000;
+import { getSessionDir } from '../session/getSessionDir.js';
+import { readCompactLifecycle, } from './compact-lifecycle-store.js';
+/**
+ * Concrete first-version stale timeout. Adjustable after real timing
+ * evidence from the auto-compact orchestrator (it currently writes a
+ * heartbeat on every state transition; 120 s is the longest realistic
+ * gap between a heartbeat and an actual stall).
+ */
+const DEFAULT_STALE_AFTER_MS = 120_000;
+/**
+ * 10-second completed-window expiry. The brief (Task 6 design requirement)
+ * calls out: once a compact lifecycle reaches `completed`, the primary
+ * statusline should surface the success indicator for at most 10 seconds,
+ * then fall back to the C1 baseline so the consumer (the IDE) does not
+ * keep a green ✓ pinned on the status bar indefinitely. The narrow window
+ * is sufficient for the human to see "we just compacted" and long enough
+ * to not flap on subsequent reads. Adjustable after real timing feedback.
+ */
+export const COMPLETED_EXPIRY_MS = 10_000;
+/** Legacy mtime window for the "just compacted" indicator. */
+const LEGACY_JUST_COMPACTED_WINDOW_MS = 30_000;
+const CELL_BY_STAGE = new Map([
+    ['queued', 0],
+    ['preparing', 2],
+    ['compacting', 4],
+    ['verifying', 6],
+    ['completed', 8],
+    ['failed', 4],
+]);
+const FILLED = '█';
+const EMPTY = '░';
+const BAR_WIDTH = 8;
+const NO_AFTER_RATIO_HINT = 'after-ratio not recorded';
+function renderBar(filledCells) {
+    return `[${FILLED.repeat(filledCells)}${EMPTY.repeat(BAR_WIDTH - filledCells)}]`;
+}
+function renderLegacyBar(filledCells) {
+    return renderBar(filledCells);
+}
 export function decideCompactStatusline(input) {
+    const staleAfterMs = input.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+    const completedExpiryMs = input.completedExpiryMs ?? COMPLETED_EXPIRY_MS;
     if (input.sessionId === null) {
-        return { kind: 'missing', label: '' };
+        return { kind: 'none', filledCells: 0 };
+    }
+    const sessionDir = getSessionDir(input.projectRoot, input.sessionId);
+    // Priority 1: lifecycle reads. Lifecycle is the canonical source of
+    // truth; invalid is non-recoverable in this decision layer.
+    const lifecycle = readCompactLifecycle({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        nowMs: input.now,
+        staleAfterMs,
+    });
+    if (lifecycle.kind === 'valid') {
+        // 10-second completed-expiry: once a compact lifecycle reaches
+        // `completed`, the primary statusline should surface the success
+        // indicator for at most COMPLETED_EXPIRY_MS (10s), then fall back to
+        // the C1 baseline so the IDE does not keep a green ✓ pinned on the
+        // status bar indefinitely. The narrow window is sufficient for the
+        // human to see "we just compacted" and long enough to not flap on
+        // subsequent reads. The narrow read of `updatedAt` is intentional: we
+        // surface the truth ("the run completed") and immediately expire
+        // rather than carrying forward a stale green check.
+        //
+        // Note: the expiry applies ONLY to `kind: 'completed'`. The `failed`
+        // stage is deliberately PERSISTENT — the orchestrator writes a single
+        // terminal `failed` record and the user (or the next slice's QA gate)
+        // needs to see it on the statusline until the next lifecycle write
+        // clears it. Expiring a failed record would silently hide a real
+        // failure from the human and is a NO-GO. The `stalled` failure mode
+        // is distinct and is computed by the lifecycle store (not here).
+        if (lifecycle.record.stage === 'completed') {
+            const updatedAtMs = Date.parse(lifecycle.record.updatedAt);
+            if (!Number.isNaN(updatedAtMs) && input.now - updatedAtMs > completedExpiryMs) {
+                return { kind: 'none', filledCells: 0 };
+            }
+        }
+        return stateFromLifecycle(lifecycle.record);
+    }
+    if (lifecycle.kind === 'stalled') {
+        return stateFromStalled(lifecycle.record);
+    }
+    if (lifecycle.kind === 'invalid') {
+        return {
+            kind: 'invalid',
+            filledCells: 0,
+            detail: lifecycle.reason,
+        };
+    }
+    // lifecycle.kind === 'missing' → fall back to legacy files.
+    return decideLegacyFallback({
+        projectRoot: input.projectRoot,
+        sessionDir,
+        now: input.now,
+    });
+}
+function stateFromLifecycle(record) {
+    if (record.stage === 'failed') {
+        const failedAt = record.failedAt ?? 'compacting';
+        const state = {
+            kind: 'failed',
+            filledCells: CELL_BY_STAGE.get(failedAt) ?? 4,
+            triggerRatio: record.triggerRatio,
+            redLine: record.redLine,
+            failedAt,
+        };
+        if (record.errorSummary !== undefined) {
+            return { ...state, detail: record.errorSummary };
+        }
+        return state;
+    }
+    const filledCells = CELL_BY_STAGE.get(record.stage) ?? 0;
+    const base = {
+        kind: record.stage,
+        filledCells,
+        triggerRatio: record.triggerRatio,
+        redLine: record.redLine,
+    };
+    if (record.stage === 'completed' && typeof record.afterRatio === 'number') {
+        return { ...base, afterRatio: record.afterRatio };
+    }
+    return base;
+}
+function stateFromStalled(record) {
+    const filledCells = CELL_BY_STAGE.get(record.stage) ?? 4;
+    const detailText = record.stage === 'failed'
+        ? record.errorSummary
+        : `no heartbeat for ${record.stage} stage`;
+    const state = {
+        kind: 'stalled',
+        filledCells,
+        triggerRatio: record.triggerRatio,
+        redLine: record.redLine,
+    };
+    if (detailText !== undefined) {
+        return { ...state, detail: detailText };
     }
-    const runtimeDir = join(input.projectRoot, '.peaks', '_runtime', input.sessionId);
-    const pendingPath = join(runtimeDir, 'txt', 'auto-compact-pending.json');
-    const historyPath = join(runtimeDir, 'compact-history.jsonl');
-    // Priority 1: a pending compact intent.
+    return state;
+}
+function decideLegacyFallback(input) {
+    const { sessionDir, now } = input;
+    const pendingPath = `${sessionDir}/txt/auto-compact-pending.json`;
+    const historyPath = `${sessionDir}/compact-history.jsonl`;
+    // Priority 1 within legacy: a pending intent.
     if (existsSync(pendingPath)) {
         try {
             const raw = readFileSync(pendingPath, 'utf8');
             const parsed = JSON.parse(raw);
             if (parsed.pending === true) {
-                if (parsed.redLine === true) {
-                    return {
-                        kind: 'red-line',
-                        label: `REDLINE ${(parsed.ratio ?? 0).toFixed(2)}`,
-                        detail: pendingPath,
-                    };
-                }
                 return {
-                    kind: 'pending',
-                    label: `compact pending (${(parsed.ratio ?? 0).toFixed(2)})`,
+                    kind: 'queued',
+                    filledCells: 0,
+                    ...(typeof parsed.ratio === 'number' ? { triggerRatio: parsed.ratio } : {}),
+                    ...(parsed.redLine === true ? { redLine: true } : {}),
                     detail: pendingPath,
                 };
             }
         }
-        catch { /* fall through to history check */ }
+        catch {
+            // fall through to history check
+        }
     }
-    // Priority 2: the most recent history event is within 30s.
+    // Priority 2 within legacy: a recent history event within 30s.
     if (existsSync(historyPath)) {
         try {
             const mtimeMs = statSync(historyPath).mtimeMs;
-            if (input.now - mtimeMs <= JUST_COMPACTED_WINDOW_MS) {
-                const raw = readFileSync(historyPath, 'utf8');
-                const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
-                const last = lines[lines.length - 1];
-                if (last !== undefined) {
-                    const parsed = JSON.parse(last);
-                    const from = (parsed.beforeRatio ?? 0).toFixed(2);
-                    const to = (parsed.ok === false) ? 'failed' : '0.0?';
-                    return {
-                        kind: 'just-compacted',
-                        label: parsed.redLine === true
-                            ? `just compacted (REDLINE ${from}→?)`
-                            : `just compacted (${from}→${to})`,
-                        detail: historyPath,
-                    };
-                }
+            if (now - mtimeMs <= LEGACY_JUST_COMPACTED_WINDOW_MS) {
+                // CRITICAL: no invented after-ratio. The history event may
+                // carry a beforeRatio, but never a measured after-ratio;
+                // this is the legacy path and we honour the "no measurement"
+                // default.
+                return {
+                    kind: 'completed',
+                    filledCells: 8,
+                    detail: historyPath,
+                };
             }
         }
-        catch { /* fall through to idle */ }
+        catch {
+            // fall through to idle
+        }
     }
-    return { kind: 'idle', label: '--' };
+    return { kind: 'none', filledCells: 0 };
 }
 /**
- * Plain-text render: just the label. The LLM embeds this in
- * the Claude Code statusline. Pure: no side effects, no I/O
- * beyond the two file reads.
+ * Plain-text render: the cell bar + a small annotation. The bar is
+ * always the fixed-width 8-cell shape `[████░░░░]`. After-ratio is
+ * only rendered when the lifecycle record carries a real one.
+ *
+ * The output never contains `?` characters — we never guess a ratio.
  */
 export function renderCompactStatusline(state) {
-    return state.label;
+    switch (state.kind) {
+        case 'none':
+            return `compact ${renderLegacyBar(0)}`;
+        case 'queued':
+            return `compact ${renderLegacyBar(0)}${state.redLine === true ? ' (redLine)' : ''}`;
+        case 'preparing':
+            return `compact ${renderBar(2)}`;
+        case 'compacting':
+            return `compact ${renderBar(4)}`;
+        case 'verifying':
+            return `compact ${renderBar(6)}`;
+        case 'completed':
+            return formatCompleted(state);
+        case 'failed':
+            return formatFailed(state);
+        case 'stalled':
+            return formatStalled(state);
+        case 'invalid':
+            return formatInvalid(state);
+    }
+}
+function formatCompleted(state) {
+    const bar = renderBar(8);
+    if (typeof state.afterRatio === 'number') {
+        return `compact ${bar} → ${state.afterRatio.toFixed(2)}`;
+    }
+    return `compact ${bar} (${NO_AFTER_RATIO_HINT})`;
+}
+function formatFailed(state) {
+    const filledAt = state.failedAt ?? 'compacting';
+    const cells = CELL_BY_STAGE.get(filledAt) ?? 4;
+    const bar = renderBar(cells);
+    const detail = state.detail ? ` — ${state.detail}` : '';
+    return `compact ${bar} failed at ${filledAt}${detail}`;
+}
+function formatStalled(state) {
+    const bar = renderBar(state.filledCells);
+    const detail = state.detail ? ` — ${state.detail}` : '';
+    return `compact ${bar} stalled${detail}`;
+}
+function formatInvalid(state) {
+    return `compact status unreadable: ${state.detail ?? 'lifecycle record malformed'}`;
 }

package/dist/services/context/auto-compact-reader.d.ts

@@ -3,6 +3,16 @@ export interface ReadContextPercentInput {
     readonly projectRoot: string;
     readonly sessionId: string;
     readonly env?: NodeJS.ProcessEnv | undefined;
+    /**
+     * Slice 2026-07-31-rid-002: explicit byte count from `--prompt-size <bytes>`.
+     * When set to a finite non-negative number, short-circuits the entire
+     * env / statusline / transcript chain with `source: 'user-overridden'`.
+     * Mac escape hatch — Claude Code Mac does NOT inject
+     * `CLAUDE_CONTEXT_USAGE_PERCENT` into PreToolUse sub-shells, so the
+     * user (or a hook wrapper) can inject the bytes they observed themselves.
+     * Priority P0 — above everything else.
+     */
+    readonly promptSizeBytes?: number | undefined;
 }
 /**
  * Read env-var-based context percentage. Returns `null` when the env
@@ -19,12 +29,30 @@ declare function readEnvPercent(env: NodeJS.ProcessEnv, varName: string): number
  */
 declare function readClaudeStatuslinePercent(): number | null;
 /**
- * Conservative transcript-size fallback. Walks
- * `~/.claude/projects/<hash>/<sid>.jsonl` and estimates
+ * Recursive search for `<sessionId>.jsonl` under `projectsDir`. Used by
+ * `readClaudeTranscriptFallback` and exported via `_internal` so unit
+ * tests can drive it without monkey-patching `os.homedir` (which is
+ * non-configurable in ESM module namespaces).
+ *
+ * The Mac layout encodes the cwd as a single hash directory; on Mac
+ * Claude Code nests the transcript under that hash with an extra level
+ * of subdirectory we cannot predict ahead of time. A flat readdir misses
+ * that branch and returns null — the silent-failure mode that this fix
+ * closes.
+ */
+declare function findTranscriptJsonl(projectsDir: string, sessionId: string): {
+    path: string;
+    bytes: number;
+} | null;
+/**
+ * Conservative transcript-size fallback. Recursively searches
+ * `~/.claude/projects/<hash>/<sid-or-nested>.jsonl` (Mac may nest
+ *  the jsonl under an
+ * extra directory we cannot predict ahead of time) and estimates
  * `ratio = bytesUsed / 256K`. Returns the bytes seen so the
  * orchestrator can show "estimated from 124KB of 256KB transcript"
- * in the envelope. Tagged `'conservative-fallback'` so callers
- * know NOT to treat this as a hard gate.
+ * in the envelope. Tagged `'transcript-estimate'` (v2.14.0) so callers
+ * know it is a real signal, NOT a hard gate.
  */
 declare function readClaudeTranscriptFallback(sessionId: string): {
     ratio: number;
@@ -47,5 +75,6 @@ export declare const _internal: {
     readEnvPercent: typeof readEnvPercent;
     readClaudeStatuslinePercent: typeof readClaudeStatuslinePercent;
     readClaudeTranscriptFallback: typeof readClaudeTranscriptFallback;
+    findTranscriptJsonl: typeof findTranscriptJsonl;
 };
 export {};