peaks-loop 4.0.0-beta.9 → 4.0.3

package/dist/services/code/auto-compact-orchestrator.js

@@ -1,7 +1,7 @@
 /**
  * Auto-compact orchestrator (v2.13.0 AC-2 + AC-3 + AC-4).
  *
- * Closes the loop between `peaks context now` (AC-1) and the IDE's
+ * Closes the loop between `peaks compact auto` (AC-1) and the IDE's
  * native compact capability (AC-3). peaks-loop is project-aware: it
  * knows the current plan, open questions, recent decisions, in-flight
  * batches, todo state, git status, and active skills. That context is
@@ -16,7 +16,7 @@
  *   3. If 0.85 ≤ ratio < 0.95 (pre-compact zone): peaks-loop prepares
  *      the convergence toolkit (checkpoint + auto-decisions log +
  *      IDE-dispatch handle) and surfaces it to the LLM. The LLM
- *      DECIDES when to fire `peaks code auto-compact --execute`;
+ *      DECIDES when to fire `peaks compact auto --execute`;
  *      peaks-loop does NOT auto-fire. The toolkit is ready so the
  *      LLM doesn't lose context to a last-second `/compact` panic.
  *   4. If ratio < 0.85: skip — return a one-line info row.
@@ -28,43 +28,69 @@
  * the LLM-runner keeps working with context < 95% without human
  * intervention.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { getSessionIdCanonical } from '../session/session-manager.js';
-import { AUTO_COMPACT_PRE_COMPACT_RATIO, AUTO_COMPACT_RED_LINE_RATIO, AUTO_COMPACT_THRESHOLD_RATIO } from '../context/auto-compact-types.js';
+import { AUTO_COMPACT_THRESHOLD_RATIO } from '../context/auto-compact-types.js';
+import { describeMode, thresholdFor } from './auto-compact-modes.js';
+import { read24hState } from '../24h-mode/store.js';
 const PRE_COMPACT_REASON = 'pre-compact-auto';
 /**
  * Map a context ratio to a `CompactTrigger` action. Pure; the side
  * effects (checkpoint + IDE dispatch) live in `runAutoCompact`. Two
- * tiers:
+ * tiers (standard mode; partial mode shifts both thresholds):
  *
- *   - ratio < 0.85 → 'none' or 'soft-warn'
- *   - ratio ≥ 0.85 → 'pre-compact' (async-friendly path)
- *   - ratio ≥ 0.95 → 'red-line' (synchronous gate)
+ *   - ratio < preCompact → 'none' or 'soft-warn'
+ *   - ratio ≥ preCompact → 'pre-compact' (async-friendly path)
+ *   - ratio ≥ redLine    → 'red-line' (synchronous gate)
+ *
+ * Slice 2026-07-28 (rid-027): `mode` selects the threshold table.
+ * Default `'standard'` (0.85/0.95). `'partial'` (0.70/0.85) is used
+ * when 24h long-run mode is active or `--mode partial` is passed.
  */
-export function evaluateCompactTrigger(ratio) {
-    if (ratio < AUTO_COMPACT_PRE_COMPACT_RATIO) {
+export function evaluateCompactTrigger(ratio, mode = 'standard') {
+    const autoFire = thresholdFor(mode, 'autoFire');
+    const preCompact = thresholdFor(mode, 'preCompact');
+    const redLine = thresholdFor(mode, 'redLine');
+    if (ratio < autoFire) {
         return ratio < 0.5
             ? { kind: 'none' }
             : {
                 kind: 'soft-warn',
                 ratio,
-                message: `Context at ${(ratio * 100).toFixed(1)}%; below the 85% pre-compact threshold.`
+                message: `Context at ${(ratio * 100).toFixed(1)}%; below the ${(autoFire * 100).toFixed(0)}% auto-fire threshold (mode=${mode}).`
             };
     }
-    if (ratio >= AUTO_COMPACT_RED_LINE_RATIO) {
+    if (ratio >= redLine) {
         return {
             kind: 'red-line',
             ratio,
-            message: `Context at ${(ratio * 100).toFixed(1)}% ≥ 95% red line. Synchronous compact REQUIRED (LLM cannot opt out).`
+            message: `Context at ${(ratio * 100).toFixed(1)}% ≥ ${(redLine * 100).toFixed(0)}% red line (mode=${mode}). Synchronous compact REQUIRED (LLM cannot opt out).`
+        };
+    }
+    if (ratio < preCompact) {
+        // Part 22: auto-fire zone (0.80 ≤ ratio < 0.85). peaks-loop
+        // preempts and runs `peaks compact auto --execute` itself
+        // without LLM involvement. The LLM is not asked to "decide";
+        // the toolkit is applied synchronously. Closes the
+        // LLM-misjudges-context window that previously let the
+        // ratio drift to 0.95 before the auto-fire kicked in.
+        return {
+            kind: 'auto-fire',
+            ratio,
+            message: `Context at ${(ratio * 100).toFixed(1)}% in auto-fire zone (≥${(autoFire * 100).toFixed(0)}% / <${(preCompact * 100).toFixed(0)}%, mode=${mode}). peaks-loop will fire compact without LLM confirmation.`
         };
     }
-    // 0.85 ≤ ratio < 0.95: pre-compact zone — toolkit ready, LLM decides.
+    // pre-compact zone (0.85 ≤ ratio < 0.95): kept for backward
+    // compat with operators who configured the higher threshold.
+    // In practice peaks-loop already auto-fired at the lower
+    // threshold; the pre-compact zone today is the "already fired"
+    // zone.
     return {
         kind: 'pre-compact',
         ratio,
         toolkitReady: true,
-        message: `Context at ${(ratio * 100).toFixed(1)}% in pre-compact zone (0.85–0.95). Convergence toolkit is ready; LLM decides when to fire \`peaks code auto-compact --execute\`.`
+        message: `Context at ${(ratio * 100).toFixed(1)}% in pre-compact zone (≥${(preCompact * 100).toFixed(0)}% / <${(redLine * 100).toFixed(0)}%, mode=${mode}). peaks-loop already fired the auto-compact pathway at the auto-fire threshold; the LLM does not need to act.`
     };
 }
 /**
@@ -80,7 +106,7 @@ export function evaluateCompactTrigger(ratio) {
  *                                regardless of in-flight batch.
  */
 export function evaluateAutoCompactDecision(input) {
-    const trigger = evaluateCompactTrigger(input.ratio);
+    const trigger = evaluateCompactTrigger(input.ratio, input.mode ?? 'standard');
     if (trigger.kind === 'none' || trigger.kind === 'soft-warn') {
         return { shouldCompact: false, reason: 'below-threshold', trigger };
     }
@@ -206,6 +232,22 @@ function writePreCompactCheckpoint(input) {
     writeFileSync(path, JSON.stringify(content, null, 2), 'utf8');
     return path;
 }
+/**
+ * Slice 2026-07-28 (rid-027): resolve the auto-compact mode from
+ * 24h-mode awareness. Returns `'partial'` when the session is
+ * `24H_ACTIVE`, otherwise `'standard'`. The CLI flag `--mode` takes
+ * precedence (caller passes `input.mode` directly), so this helper is
+ * only consulted when the flag is absent.
+ */
+function resolveAutoCompactMode(projectRoot, sessionId) {
+    try {
+        const snap = read24hState(projectRoot, sessionId);
+        return snap.state === '24H_ACTIVE' ? 'partial' : 'standard';
+    }
+    catch {
+        return 'standard';
+    }
+}
 /**
  * Execute the auto-compact flow.
  *
@@ -235,6 +277,10 @@ export async function runAutoCompact(input) {
             nextActions: ['Run `peaks workspace init --change-id <id>` to bind a session']
         };
     }
+    // Slice 2026-07-28 (rid-027): resolve mode. CLI flag `--mode` wins;
+    // 24h-mode awareness yields 'partial' when 24h_ACTIVE; default
+    // 'standard' preserves v2.13.0 zero-pause contract.
+    const mode = input.mode ?? resolveAutoCompactMode(input.projectRoot, sessionId);
     // Lazy import to avoid the AC-1 module depending on the orchestrator.
     const { readContextPercent } = await import('../context/auto-compact-reader.js');
     const probe = readContextPercent({
@@ -246,7 +292,8 @@ export async function runAutoCompact(input) {
         ratio: probe.ratio,
         inFlightBatch: input.inFlightBatch,
         force: input.force,
-        bypassRedLine: input.bypassRedLine
+        bypassRedLine: input.bypassRedLine,
+        mode
     });
     if (!decision.shouldCompact) {
         return {
@@ -277,12 +324,12 @@ export async function runAutoCompact(input) {
         ? [
             'RED-LINE compact dispatched — further sub-agent dispatch BLOCKED until ratio < 0.85',
             'Post-compact resume picks up the convergence plan from auto-decisions.md',
-            'Next `peaks context now` probe will confirm ratio dropped below 0.85'
+            'Next `peaks compact auto` probe will confirm ratio dropped below 0.85'
         ]
         : [
             'Pre-compact dispatched — IDE compact in progress (async)',
             'Post-compact resume picks up the convergence plan from auto-decisions.md',
-            'Next `peaks context now` probe will confirm ratio dropped below 0.85'
+            'Next `peaks compact auto` probe will confirm ratio dropped below 0.85'
         ];
     const plan = buildConvergencePlan({
         sessionId,
@@ -316,6 +363,31 @@ export async function runAutoCompact(input) {
         env: input.env,
         target
     });
+    // Slice 2026-07-30-compact-visibility: append a compact-history
+    // event so the new 'peaks compact history' CLI and the
+    // 'peaks statusline compact' indicator have a record. The
+    // append is best-effort: a write failure must NOT block the
+    // compact return envelope.
+    try {
+        appendCompactHistoryEvent({
+            projectRoot: input.projectRoot,
+            sessionId,
+            event: {
+                schemaVersion: 1,
+                ts: now.toISOString(),
+                target,
+                mode,
+                ide: dispatch.ide,
+                pathway: dispatch.pathway,
+                beforeRatio: probe.ratio,
+                redLine: isRedLine,
+                ok: dispatch.ok,
+                checkpointPath,
+                dispatchMessage: dispatch.message,
+            },
+        });
+    }
+    catch { /* best-effort; do not fail the compact return */ }
     return {
         ok: dispatch.ok,
         code: dispatch.ok
@@ -323,8 +395,8 @@ export async function runAutoCompact(input) {
             : 'AUTO_COMPACT_DISPATCH_FAILED',
         message: dispatch.ok
             ? isRedLine
-                ? `RED-LINE compact dispatched (${dispatch.ide} / ${dispatch.pathway} / target=${target}); checkpoint at ${checkpointPath}. Further sub-agent dispatch is BLOCKED until ratio < 0.85.`
-                : `Auto-compact dispatched (${dispatch.ide} / ${dispatch.pathway} / target=${target}); checkpoint at ${checkpointPath}.`
+                ? `RED-LINE compact dispatched (${dispatch.ide} / ${dispatch.pathway} / target=${target} / mode=${mode} — ${describeMode(mode)}); checkpoint at ${checkpointPath}. Further sub-agent dispatch is BLOCKED until ratio < 0.85.`
+                : `Auto-compact dispatched (${dispatch.ide} / ${dispatch.pathway} / target=${target} / mode=${mode} — ${describeMode(mode)}); checkpoint at ${checkpointPath}.`
             : `Auto-compact checkpoint written but IDE dispatch failed: ${dispatch.message}`,
         data: {
             sessionId,
@@ -334,10 +406,18 @@ export async function runAutoCompact(input) {
             convergencePlan: plan,
             dispatch,
             target,
+            mode,
             redLineGated: isRedLine
         }
     };
 }
+export function appendCompactHistoryEvent(input) {
+    const dir = join(input.projectRoot, '.peaks', '_runtime', input.sessionId);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const path = join(dir, 'compact-history.jsonl');
+    appendFileSync(path, JSON.stringify(input.event) + '\n', 'utf8');
+}
 // Keep dirname import live for symmetry with sibling services that
 // use it for path joins; tree-shaking removes it in builds.
 void dirname;

package/dist/services/code/dag-orchestrator.d.ts

@@ -25,7 +25,7 @@
  *  dispatch --from-dag`) consumes the planner's output but the planner
  *  itself is a library.
  */
-import { type SliceDag } from '../dispatch/slice-dag.js';
+import { type SliceDag, type Wave, type WaveArtifact, type WaveOptions } from '../dispatch/slice-dag.js';
 import { type SliceContract } from '../dispatch/contract-store.js';
 export interface DispatchSpec {
     readonly sliceId: string;
@@ -126,3 +126,32 @@ export declare function runDag(dag: SliceDag, opts: RunDagOptions): Promise<DagR
  * peaks-code LLM) executes the per-IDE tool calls.
  */
 export declare function runLayeredDag(dag: SliceDag, opts: RunDagOptions): Promise<DagRunResult>;
+/**
+ * Plan a slice DAG into ordered dispatch Waves.
+ *
+ * Each topological level is split into chunks of at most
+ * `opts.maxConcurrency` slice IDs (default 6). Wave ordering follows
+ * topological level order; within each level, slices preserve
+ * `topologicalLevels`'s foundation / upstreamSync / id-asc priority sort.
+ */
+export declare function planDispatchWaves(dag: SliceDag, opts?: WaveOptions): readonly Wave[];
+/**
+ * Backward-compat wrapper: flatten `planDispatchWaves(dag)` into a flat
+ * sequence of stub `DispatchSpec`s. The original `runDag` /
+ * `runLayeredDag` do NOT consume this; the wrapper exists only so
+ * external callers that imported `planDispatch(dag)` keep their shape.
+ */
+export declare function planDispatch(dag: SliceDag): readonly DispatchSpec[];
+/**
+ * Run a single Wave: dispatch `wave.slices` in parallel, return a
+ * `WaveArtifact` envelope on success. On any per-slice failure or
+ * cancellation, REJECTS with `DagPlanError` — caller treats the
+ * rejection as a barrier violation and rolls back siblings.
+ *
+ * `passArtifacts`: when true, the returned envelope includes each
+ * slice's public surface (callers splice into downstream Wave prompts).
+ *
+ * `priorArtifacts` is reserved for future artifact-injection. This MVP
+ * accepts the shape but does not yet splice it into the prompt.
+ */
+export declare function runWaveWithArtifacts(dag: SliceDag, wave: Wave, runner: (spec: DispatchSpec) => Promise<SliceOutcome>, priorArtifacts?: readonly WaveArtifact[], opts?: WaveOptions): Promise<WaveArtifact>;

package/dist/services/code/dag-orchestrator.js

@@ -25,7 +25,7 @@
  *  dispatch --from-dag`) consumes the planner's output but the planner
  *  itself is a library.
  */
-import { hashDag, InvalidSliceDagError, topologicalLevels, validateDag } from '../dispatch/slice-dag.js';
+import { hashDag, InvalidSliceDagError, topologicalLevels, validateDag, DEFAULT_WAVE_OPTIONS } from '../dispatch/slice-dag.js';
 import { formatContractInjection, writeContract } from '../dispatch/contract-store.js';
 import { formatTestToolDetection } from '../dispatch/test-tool-detection.js';
 /** Thrown when the DAG has no feasible plan (validation error). */
@@ -302,3 +302,108 @@ export async function runLayeredDag(dag, opts) {
         contracts
     };
 }
+/* ──────────────────────────────────────────────────────────────────────────
+ * Slice 2026-07-28 — DAG wave + barrier (rid-029 E direction).
+ *
+ * The original `runDag` + `runLayeredDag` above dispatch an ENTIRE
+ * topological level in one `Promise.all` burst. For 24-hour scenarios
+ * with >=20 sub-agents this saturates the host. The wave planner below
+ * chunks each level into Waves of at most `maxConcurrency` slice IDs,
+ * and `runWaveWithArtifacts` runs one Wave at a time, returning a
+ * `WaveArtifact` envelope that downstream Waves can consume.
+ *
+ * Backward-compat: the original flat-dispatch APIs above are untouched;
+ * `planDispatchWaves` + `runWaveWithArtifacts` are purely additive.
+ * ────────────────────────────────────────────────────────────────────────── */
+/**
+ * Plan a slice DAG into ordered dispatch Waves.
+ *
+ * Each topological level is split into chunks of at most
+ * `opts.maxConcurrency` slice IDs (default 6). Wave ordering follows
+ * topological level order; within each level, slices preserve
+ * `topologicalLevels`'s foundation / upstreamSync / id-asc priority sort.
+ */
+export function planDispatchWaves(dag, opts = DEFAULT_WAVE_OPTIONS) {
+    validateDag(dag);
+    if (opts.maxConcurrency <= 0) {
+        throw new DagPlanError(`WaveOptions.maxConcurrency must be > 0 (got ${opts.maxConcurrency})`);
+    }
+    const levels = topologicalLevels(dag);
+    const waves = [];
+    let waveIndex = 0;
+    for (const level of levels) {
+        for (let i = 0; i < level.length; i += opts.maxConcurrency) {
+            const chunk = level.slice(i, i + opts.maxConcurrency);
+            waves.push({ waveIndex, slices: chunk });
+            waveIndex += 1;
+        }
+    }
+    return waves;
+}
+/**
+ * Backward-compat wrapper: flatten `planDispatchWaves(dag)` into a flat
+ * sequence of stub `DispatchSpec`s. The original `runDag` /
+ * `runLayeredDag` do NOT consume this; the wrapper exists only so
+ * external callers that imported `planDispatch(dag)` keep their shape.
+ */
+export function planDispatch(dag) {
+    const waves = planDispatchWaves(dag);
+    const out = [];
+    for (const w of waves) {
+        for (const sliceId of w.slices) {
+            out.push({ sliceId, role: '', label: null, prompt: '', contractBlock: '' });
+        }
+    }
+    return out;
+}
+/**
+ * Run a single Wave: dispatch `wave.slices` in parallel, return a
+ * `WaveArtifact` envelope on success. On any per-slice failure or
+ * cancellation, REJECTS with `DagPlanError` — caller treats the
+ * rejection as a barrier violation and rolls back siblings.
+ *
+ * `passArtifacts`: when true, the returned envelope includes each
+ * slice's public surface (callers splice into downstream Wave prompts).
+ *
+ * `priorArtifacts` is reserved for future artifact-injection. This MVP
+ * accepts the shape but does not yet splice it into the prompt.
+ */
+export async function runWaveWithArtifacts(dag, wave, runner, priorArtifacts = [], opts = DEFAULT_WAVE_OPTIONS) {
+    validateDag(dag);
+    if (wave.slices.length === 0) {
+        throw new DagPlanError(`runWaveWithArtifacts: wave ${wave.waveIndex} has no slices`);
+    }
+    const collectedContracts = {};
+    const completedLeaves = [];
+    const settled = await Promise.all(wave.slices.map(async (sliceId) => {
+        const spec = buildDispatchSpec(dag, sliceId, []);
+        try {
+            const outcome = await runner(spec);
+            return { sliceId, outcome };
+        }
+        catch (err) {
+            return {
+                sliceId,
+                outcome: { status: 'failed', reason: err.message }
+            };
+        }
+    }));
+    for (const { sliceId, outcome } of settled) {
+        if (outcome.status === 'done') {
+            completedLeaves.push(sliceId);
+            if (opts.passArtifacts) {
+                collectedContracts[sliceId] = outcome.publicSurface;
+            }
+        }
+        else {
+            void priorArtifacts;
+            throw new DagPlanError(`wave ${wave.waveIndex} aborted on slice ${sliceId}: ${outcome.status === 'failed' ? outcome.reason : outcome.status}`);
+        }
+    }
+    return {
+        waveIndex: wave.waveIndex,
+        completedLeaves,
+        contracts: collectedContracts,
+        passedAt: new Date().toISOString()
+    };
+}

package/dist/services/code/status-line-renderer.d.ts

@@ -18,6 +18,8 @@ export type SubAgentLiveView = {
     readonly progress: number | null;
     readonly lastBeatAgoSec: number | null;
     readonly isStale: boolean;
+    readonly isNeverStarted: boolean;
+    readonly stage: string | null;
 };
 export type SwarmSummary = {
     readonly total: number;

package/dist/services/code/status-line-renderer.js

@@ -6,12 +6,23 @@ export function viewSubAgent(record, now = () => new Date()) {
         ? Math.max(0, Math.floor((now().getTime() - new Date(record.lastBeatAt).getTime()) / 1000))
         : null;
     const isStale = lastBeatAgo !== null && lastBeatAgo > STALE_THRESHOLD_SEC;
+    // Slice 2026-07-29-dispatch-stall-governance / S2 (AC-2.3) — never-
+    // started: no heartbeat ever landed (lastBeatAgo is null AND the
+    // record has not been promoted by a startup-timeout marker).
+    const isNeverStarted = lastBeatAgo === null && record.status === 'queued';
     return {
         role: record.role,
         status: record.status,
         progress: latest ? latest.progress : null,
         lastBeatAgoSec: lastBeatAgo,
-        isStale
+        isStale,
+        isNeverStarted,
+        // S5 — surface the optional stage label so a long-running agent is
+        // legible. Reads from the record's `stage` field (added in the
+        // same slice); undefined on legacy records degrades to null.
+        stage: typeof record.stage === 'string'
+            ? (record.stage ?? null)
+            : null
     };
 }
 /** Aggregate swarm summary. */
@@ -50,6 +61,13 @@ function renderOne(record, now) {
     const view = viewSubAgent(record, now);
     const pct = view.progress !== null ? `${view.progress}%` : '?%';
     const ago = view.lastBeatAgoSec !== null ? `${view.lastBeatAgoSec}s ago` : 'no beat';
-    const stale = view.isStale ? ' ⚠ stale' : '';
-    return `${view.role} ${pct} (${ago})${stale}`;
+    // Slice 2026-07-29-dispatch-stall-governance / S2 (AC-2.3) — render
+    // never-started distinctly from stale so the orchestrator's eye can
+    // tell a sub-agent that never picked up the work apart from one that
+    // has gone quiet after starting.
+    const marker = view.isNeverStarted ? ' ⚠ never-started' : view.isStale ? ' ⚠ stale' : '';
+    // S5 (AC-5.2) — surface the optional stage label inline so a long-
+    // `running` agent is legible. Empty stage is omitted silently.
+    const stageSuffix = view.stage && view.stage.length > 0 ? ` [${view.stage}]` : '';
+    return `${view.role} ${pct} (${ago})${marker}${stageSuffix}`;
 }

package/dist/services/code-review/ocr-service.d.ts

@@ -52,7 +52,7 @@ export interface SubprocessRunner {
  * present (peaks-loop was installed but its dependency tree is
  * corrupt, or the user removed it).
  *
- * Walks up from this file (dist/src/services/code-review/) to
+ * Walks up from this file (dist/services/code-review/) to
  * find the project root, then checks node_modules.
  */
 export declare function resolveOcrLauncher(searchRoots: readonly string[]): string | null;

package/dist/services/code-review/ocr-service.js

@@ -101,7 +101,7 @@ const DEFAULT_RUNNER = {
  * present (peaks-loop was installed but its dependency tree is
  * corrupt, or the user removed it).
  *
- * Walks up from this file (dist/src/services/code-review/) to
+ * Walks up from this file (dist/services/code-review/) to
  * find the project root, then checks node_modules.
  */
 export function resolveOcrLauncher(searchRoots) {
@@ -122,8 +122,11 @@ export function resolveOcrLauncher(searchRoots) {
  * (2) the user's cwd.
  */
 export function defaultOcrSearchRoots(currentDirPath, cwd) {
-    // currentDirPath is dist/src/services/code-review/; walk up 4 to repo root.
-    const peaksRoot = join(currentDirPath, '..', '..', '..', '..');
+    // currentDirPath is dist/services/code-review/ under tsc rootDir=src;
+    // walk up 3 to repo root. If tsconfig.build.json#rootDir ever reverts
+    // to "." (emits dist/src/services/code-review/), this must become
+    // walk-4 — keep these two in lockstep.
+    const peaksRoot = join(currentDirPath, '..', '..', '..');
     return [peaksRoot, cwd];
 }
 /**

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

@@ -0,0 +1,41 @@
+export interface CompactHistoryEvent {
+    readonly schemaVersion: 1;
+    readonly ts: string;
+    readonly target: 'main' | 'sub-agent' | 'worker';
+    readonly mode: 'standard' | 'partial' | 'aggressive';
+    readonly ide: string;
+    readonly pathway: string;
+    readonly beforeRatio: number;
+    readonly redLine: boolean;
+    readonly ok: boolean;
+    readonly checkpointPath: string;
+    readonly dispatchMessage: string;
+}
+export type CompactHistoryReadResult = {
+    readonly kind: 'file-missing';
+    readonly path: string;
+} | {
+    readonly kind: 'empty';
+    readonly path: string;
+} | {
+    readonly kind: 'ok';
+    readonly path: string;
+    readonly events: ReadonlyArray<CompactHistoryEvent>;
+    readonly parseErrors: ReadonlyArray<{
+        readonly line: number;
+        readonly raw: string;
+    }>;
+};
+export declare function readCompactHistory(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+}): CompactHistoryReadResult;
+export interface CompactHistorySummary {
+    readonly totalCompacts: number;
+    readonly lastTs: string | null;
+    readonly lastBeforeRatio: number | null;
+    readonly lastRedLine: boolean;
+    readonly redLineCount: number;
+    readonly failedCount: number;
+}
+export declare function summarizeCompactHistory(events: ReadonlyArray<CompactHistoryEvent>): CompactHistorySummary;

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

@@ -0,0 +1,62 @@
+// src/services/compact-history/compact-history-service.ts
+//
+// Slice 2026-07-30-compact-visibility (slice 1/4). Pure-function
+// reader for the .peaks/_runtime/<sessionId>/compact-history.jsonl
+// file that auto-compact-orchestrator now appends to on every
+// dispatch. The CLI surface `peaks compact history` and the
+// statusline indicator both consume this service.
+//
+// The file is one JSON event per line. Malformed lines are
+// surfaced as { kind: 'parse-error', line, raw } records so the
+// caller (CLI / statusline) can warn without aborting the whole
+// read.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function readCompactHistory(input) {
+    const path = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'compact-history.jsonl');
+    if (!existsSync(path)) {
+        return { kind: 'file-missing', path };
+    }
+    const raw = readFileSync(path, 'utf8');
+    const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+    if (lines.length === 0) {
+        return { kind: 'empty', path };
+    }
+    const events = [];
+    const parseErrors = [];
+    lines.forEach((line, idx) => {
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.beforeRatio !== 'number' || typeof parsed.ts !== 'string') {
+                parseErrors.push({ line: idx + 1, raw: line });
+                return;
+            }
+            events.push(parsed);
+        }
+        catch {
+            parseErrors.push({ line: idx + 1, raw: line });
+        }
+    });
+    return { kind: 'ok', path, events, parseErrors };
+}
+export function summarizeCompactHistory(events) {
+    if (events.length === 0) {
+        return {
+            totalCompacts: 0,
+            lastTs: null,
+            lastBeforeRatio: null,
+            lastRedLine: false,
+            redLineCount: 0,
+            failedCount: 0,
+        };
+    }
+    const last = events[events.length - 1];
+    return {
+        totalCompacts: events.length,
+        lastTs: last.ts,
+        lastBeforeRatio: last.beforeRatio,
+        lastRedLine: last.redLine,
+        redLineCount: events.filter((e) => e.redLine).length,
+        failedCount: events.filter((e) => !e.ok).length,
+    };
+}

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

@@ -0,0 +1,16 @@
+export interface CompactStatuslineState {
+    readonly kind: 'missing' | 'idle' | 'pending' | 'red-line' | 'just-compacted';
+    readonly label: string;
+    readonly detail?: string;
+}
+export declare function decideCompactStatusline(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string | null;
+    readonly now: 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.
+ */
+export declare function renderCompactStatusline(state: CompactStatuslineState): string;