peaks-loop 4.0.3 → 4.0.5

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

@@ -31,9 +31,10 @@
 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_THRESHOLD_RATIO } from '../context/auto-compact-types.js';
+import { AUTO_COMPACT_PRE_COMPACT_RATIO, 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';
+import { readCompactLifecycle, writeCompactLifecycle } from '../compact-statusline/compact-lifecycle-store.js';
 const PRE_COMPACT_REASON = 'pre-compact-auto';
 /**
  * Map a context ratio to a `CompactTrigger` action. Pure; the side
@@ -121,6 +122,16 @@ export function evaluateAutoCompactDecision(input) {
     if (input.force) {
         return { shouldCompact: true, reason: 'pre-compact', trigger };
     }
+    // Slice 2026-07-31-rid-mac-transcript-estimate-trigger: transcript-estimate
+    // is the ONLY signal available on Mac Claude Code (no env-var, no statusline
+    // poll). The gate above already returns shouldCompact: true at ratio ≥ 0.85,
+    // but this forward-compat carve-out makes the source-aware rule explicit so
+    // any future source-aware downgrading cannot silently re-introduce the
+    // Mac auto-compact silent-failure mode without an audit. No higher-priority
+    // source is present (`claude-code-env` would have been P1, `statusline-poll`
+    // P2, `user-overridden` P4) — Mac's only signal is `transcript-estimate`.
+    if (input.source === 'transcript-estimate' && input.ratio >= AUTO_COMPACT_PRE_COMPACT_RATIO)
+        return { shouldCompact: true, reason: 'pre-compact', trigger };
     // Default: peaks-loop drives pre-compact autonomously.
     return { shouldCompact: true, reason: 'pre-compact', trigger };
 }
@@ -248,6 +259,219 @@ function resolveAutoCompactMode(projectRoot, sessionId) {
         return 'standard';
     }
 }
+/**
+ * One id per compact attempt. Timestamp-prefixed so a human reading
+ * the raw record can order runs by eye; the random suffix keeps two
+ * attempts inside the same millisecond distinct.
+ */
+function newCompactRunId(now) {
+    const stamp = now.toISOString().replace(/[:.]/g, '-');
+    const suffix = Math.random().toString(16).slice(2, 8);
+    return `compact-${stamp}-${suffix}`;
+}
+/**
+ * Slice 2026-08-01-compact-lifecycle (Task 5): read an open compact
+ * record ignoring staleness.
+ *
+ * The lifecycle store classifies an active record as `stalled` after a
+ * caller-supplied `staleAfterMs` window. That classification exists for
+ * the statusline renderer (Task 2/3) — it tells the user "this run
+ * hasn't heartbeated for a while".
+ *
+ * For settling a run by measurement, staleness is irrelevant: if a
+ * record exists at `compacting`, a post-compact probe that measures a
+ * drop should still complete it, even if the probe itself ran hours
+ * later. Wrapping that unbounded read here keeps the magic number out
+ * of the settle path and makes the intent self-documenting.
+ *
+ * Returns `null` for any non-`valid` kind (missing / invalid /
+ * stalled). Errors from the underlying read are swallowed — settling
+ * is best-effort telemetry and must never bubble.
+ */
+function readOpenCompactLifecycle(input) {
+    let out;
+    try {
+        out = readCompactLifecycle({
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            nowMs: Date.now(),
+            // Number.MAX_SAFE_INTEGER disables the store's staleness gate
+            // for this call — see the doc comment above for why settling
+            // intentionally ignores staleness.
+            staleAfterMs: Number.MAX_SAFE_INTEGER
+        });
+    }
+    catch {
+        return null;
+    }
+    return out.kind === 'valid' ? out.record : null;
+}
+/**
+ * Slice 2026-08-01-compact-lifecycle (Task 5): the local transition
+ * builder. Carries `runId`, `triggerRatio` and `redLine` forward from
+ * the run that opened, and remembers the prior stage so a failure can
+ * name the stage it died in.
+ *
+ * TRUTHFULNESS: this publisher only ever emits a stage the calling
+ * process has actually PROVED. It never emits `verifying` or
+ * `completed` off the back of a successful dispatch — see
+ * `runAutoCompact` and `settleOpenLifecycleRun` for the reason.
+ *
+ * Telemetry is strictly subordinate to the compact itself: every write
+ * is best-effort, and a store failure must not change the threshold
+ * decision, the dispatch, or the returned envelope.
+ */
+class CompactLifecyclePublisher {
+    ctx;
+    lastStage = 'queued';
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** Publish an active stage the process has proved. */
+    advance(stage) {
+        this.lastStage = stage;
+        this.write({
+            schemaVersion: 1,
+            runId: this.ctx.runId,
+            stage,
+            updatedAt: new Date().toISOString(),
+            triggerRatio: this.ctx.triggerRatio,
+            redLine: this.ctx.redLine
+        });
+    }
+    /** Publish the terminal failure, attributed to the last stage reached. */
+    fail(error) {
+        this.write({
+            schemaVersion: 1,
+            runId: this.ctx.runId,
+            stage: 'failed',
+            updatedAt: new Date().toISOString(),
+            triggerRatio: this.ctx.triggerRatio,
+            redLine: this.ctx.redLine,
+            failedAt: this.lastStage,
+            errorSummary: summarizeLifecycleError(error)
+        });
+    }
+    write(record) {
+        try {
+            if (this.ctx.failLifecycleWrite)
+                throw new Error('lifecycle store unavailable');
+            writeCompactLifecycle({
+                projectRoot: this.ctx.projectRoot,
+                sessionId: this.ctx.sessionId,
+                record
+            });
+        }
+        catch {
+            // Best-effort telemetry: a lifecycle write failure must never
+            // change the compact decision, the dispatch, or the envelope.
+            return;
+        }
+        try {
+            this.ctx.onLifecycleStage?.(record.stage, record);
+        }
+        catch {
+            // An observer is a passive listener; its failure is not ours.
+        }
+    }
+}
+/**
+ * Reduce an arbitrary thrown value to a single-line, bounded summary
+ * fit for a statusline. Stack frames are dropped (the record is a
+ * human-facing indicator, not a crash dump); the store clamps the
+ * result to its own 160-character cap as a second line of defence.
+ *
+ * `null` / `undefined` thrown values — a real possibility from
+ * `Promise.reject(null)` or a thrown `undefined` — must not collapse
+ * to the empty string, which the store would then reject as missing.
+ * They map to a fixed "unknown error" sentinel so the record always
+ * carries some diagnostic text.
+ */
+function summarizeLifecycleError(error) {
+    let raw;
+    if (error instanceof Error)
+        raw = error.message;
+    else if (error === null || error === undefined)
+        raw = 'unknown error';
+    else
+        raw = String(error);
+    if (raw.length === 0)
+        raw = 'unknown error';
+    const firstLine = raw.split('\n')[0] ?? '';
+    const collapsed = firstLine.replace(/\s+/g, ' ').trim();
+    return collapsed.length === 0 ? 'unknown error' : (collapsed.length > 160 ? collapsed.slice(0, 160) : collapsed);
+}
+/**
+ * Slice 2026-08-01-compact-lifecycle (Task 5, Step 4): close out an
+ * open compact run using a REAL measurement.
+ *
+ * This is the integration with the actual post-compact detection path.
+ * The claude-code adapter's `postCompactDetectCommand` is
+ * `peaks compact auto --json` — i.e. the next probe through this very
+ * function. So when a probe finds a run still sitting at `compacting`
+ * and MEASURES a ratio that has dropped below the auto-fire threshold,
+ * that measurement is the proof the compact landed. Only then do we
+ * emit `verifying` (we have a measurement in hand) followed by
+ * `completed` (it confirms the drop), carrying the measured
+ * `afterRatio`.
+ *
+ * We refuse to complete when:
+ *   - the probe could not measure anything (`conservative-fallback`
+ *     returns `ratio: 0`, which means "unknown", NOT "empty"). Writing
+ *     `afterRatio: 0` there would publish a fabricated number;
+ *   - the ratio is still at or above the auto-fire threshold — the
+ *     compact has not landed, so the run stays open.
+ */
+function settleOpenLifecycleRun(input) {
+    // A `conservative-fallback` probe means no signal was available at
+    // all. Its `ratio: 0` is the absence of a measurement, so it can
+    // never be evidence that the context shrank.
+    if (input.source === 'conservative-fallback')
+        return;
+    if (input.measuredRatio >= input.autoFireThreshold)
+        return;
+    const prior = readOpenCompactLifecycle({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId
+    });
+    if (prior === null)
+        return;
+    // Only a run that was actually dispatched (`compacting`) can be
+    // completed by a post-compact measurement.
+    if (prior.stage !== 'compacting')
+        return;
+    const emit = (stage, withAfterRatio) => {
+        const record = {
+            schemaVersion: 1,
+            runId: prior.runId,
+            stage,
+            updatedAt: new Date().toISOString(),
+            triggerRatio: prior.triggerRatio,
+            redLine: prior.redLine,
+            ...(withAfterRatio ? { afterRatio: input.measuredRatio } : {})
+        };
+        try {
+            writeCompactLifecycle({
+                projectRoot: input.projectRoot,
+                sessionId: input.sessionId,
+                record
+            });
+        }
+        catch {
+            return;
+        }
+        try {
+            input.onLifecycleStage?.(stage, record);
+        }
+        catch {
+            // Observer failures are not ours to propagate.
+        }
+    };
+    // `verifying` = we hold a measurement and are checking it.
+    emit('verifying', false);
+    // `completed` = the measurement confirms the drop; publish it.
+    emit('completed', true);
+}
 /**
  * Execute the auto-compact flow.
  *
@@ -293,9 +517,28 @@ export async function runAutoCompact(input) {
         inFlightBatch: input.inFlightBatch,
         force: input.force,
         bypassRedLine: input.bypassRedLine,
-        mode
+        mode,
+        // Slice 2026-07-31-rid-mac-transcript-estimate-trigger: pipe the source
+        // tag through so `evaluateAutoCompactDecision` can apply the
+        // source-aware carve-out for Mac's `transcript-estimate` signal.
+        source: probe.source
     });
     if (!decision.shouldCompact) {
+        // Slice 2026-08-01-compact-lifecycle (Task 5): this probe IS the
+        // adapter's `postCompactDetectCommand`. A ratio that has fallen
+        // back below the auto-fire threshold is the real, measured proof
+        // that a previously-dispatched compact landed — so settle any run
+        // still open at `compacting`. Nothing is written when there is no
+        // open run, when the ratio is still high, or when the probe could
+        // not measure at all.
+        settleOpenLifecycleRun({
+            projectRoot: input.projectRoot,
+            sessionId,
+            measuredRatio: probe.ratio,
+            source: probe.source,
+            autoFireThreshold: thresholdFor(mode, 'autoFire'),
+            onLifecycleStage: input.onLifecycleStage
+        });
         return {
             ok: true,
             code: decision.reason === 'in-flight-batch' ? 'AUTO_COMPACT_WAIT' : 'AUTO_COMPACT_SKIP',
@@ -314,55 +557,129 @@ export async function runAutoCompact(input) {
     }
     const isRedLine = decision.reason === 'red-line';
     const now = input.now ?? new Date();
-    const checkpointPath = writePreCompactCheckpoint({
+    // Slice 2026-08-01-compact-lifecycle (Task 5): the decision has now
+    // committed to compacting, so the run is `queued`. One runId per
+    // attempt; every later transition carries it forward.
+    const lifecycle = new CompactLifecyclePublisher({
         projectRoot: input.projectRoot,
         sessionId,
-        now,
-        redLine: isRedLine
+        runId: newCompactRunId(now),
+        triggerRatio: probe.ratio,
+        redLine: isRedLine,
+        onLifecycleStage: input.onLifecycleStage,
+        failLifecycleWrite: input.testHooks?.failLifecycleWrite
     });
-    const nextActions = isRedLine
-        ? [
-            '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 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 compact auto` probe will confirm ratio dropped below 0.85'
-        ];
-    const plan = buildConvergencePlan({
-        sessionId,
-        projectRoot: input.projectRoot,
-        ratio: probe.ratio,
-        checkpointPath,
-        nextActions,
-        redLine: isRedLine
-    });
-    appendAutoDecisionLog({ projectRoot: input.projectRoot, sessionId, plan });
+    lifecycle.advance('queued');
+    let checkpointPath;
+    let plan;
+    let nextActions;
+    try {
+        // `preparing` covers checkpoint + convergence-plan + recovery writes.
+        lifecycle.advance('preparing');
+        if (input.testHooks?.failPreparing)
+            throw new Error('disk full while writing checkpoint');
+        checkpointPath = writePreCompactCheckpoint({
+            projectRoot: input.projectRoot,
+            sessionId,
+            now,
+            redLine: isRedLine
+        });
+        nextActions = isRedLine
+            ? [
+                '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 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 compact auto` probe will confirm ratio dropped below 0.85'
+            ];
+        plan = buildConvergencePlan({
+            sessionId,
+            projectRoot: input.projectRoot,
+            ratio: probe.ratio,
+            checkpointPath,
+            nextActions,
+            redLine: isRedLine
+        });
+        appendAutoDecisionLog({ projectRoot: input.projectRoot, sessionId, plan });
+    }
+    catch (error) {
+        lifecycle.fail(error);
+        // Preserve the original error contract: the caller gets the same
+        // `AUTO_COMPACT_DISPATCH_FAILED` envelope shape it already handles,
+        // not a thrown exception and not a widened type.
+        return {
+            ok: false,
+            code: 'AUTO_COMPACT_DISPATCH_FAILED',
+            message: `Auto-compact preparation failed before IDE dispatch: ${summarizeLifecycleError(error)}`,
+            data: {
+                sessionId,
+                ratio: probe.ratio,
+                source: probe.source,
+                target: input.target ?? 'main',
+                mode,
+                redLineGated: isRedLine
+            }
+        };
+    }
     // Lazy import to keep AC-3 (IDE dispatch) pluggable; tests mock this module.
     const { dispatchIdeCompact } = await import('../context/auto-compact-dispatcher.js');
     const target = input.target ?? 'main';
-    // Slice 2026-06-28: when targeting the main session, write an
-    // intent record so the next main-session LLM turn fires `/compact`
-    // in-band. Without this record the LLM has no signal that the
-    // orchestrator asked for compact; the dispatcher alone would have
-    // been a no-op against the main Claude Code window.
-    if (target === 'main') {
-        writeMainSessionCompactIntent({
+    let dispatch;
+    try {
+        // `compacting` is the last stage this process can prove: the IDE
+        // performs the actual compaction out-of-band, so a successful
+        // dispatch return is NOT evidence the context shrank.
+        lifecycle.advance('compacting');
+        if (input.testHooks?.failCompacting)
+            throw new Error('IDE dispatch exploded');
+        // Slice 2026-06-28: when targeting the main session, write an
+        // intent record so the next main-session LLM turn fires `/compact`
+        // in-band. Without this record the LLM has no signal that the
+        // orchestrator asked for compact; the dispatcher alone would have
+        // been a no-op against the main Claude Code window.
+        if (target === 'main') {
+            writeMainSessionCompactIntent({
+                projectRoot: input.projectRoot,
+                sessionId,
+                ratio: probe.ratio,
+                redLine: isRedLine,
+                now
+            });
+        }
+        dispatch = await dispatchIdeCompact({
             projectRoot: input.projectRoot,
             sessionId,
-            ratio: probe.ratio,
-            redLine: isRedLine,
-            now
+            env: input.env,
+            target
         });
     }
-    const dispatch = await dispatchIdeCompact({
-        projectRoot: input.projectRoot,
-        sessionId,
-        env: input.env,
-        target
-    });
+    catch (error) {
+        lifecycle.fail(error);
+        return {
+            ok: false,
+            code: 'AUTO_COMPACT_DISPATCH_FAILED',
+            message: `Auto-compact checkpoint written but IDE dispatch threw: ${summarizeLifecycleError(error)}`,
+            data: {
+                sessionId,
+                ratio: probe.ratio,
+                source: probe.source,
+                checkpointPath,
+                convergencePlan: plan,
+                target,
+                mode,
+                redLineGated: isRedLine
+            }
+        };
+    }
+    // A dispatcher that returns `ok: false` did not compact anything —
+    // record that as a failure at `compacting` rather than leaving the
+    // run looking like it is still in progress.
+    if (!dispatch.ok) {
+        lifecycle.fail(new Error(dispatch.message));
+    }
     // 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

package/dist/services/code/post-compact-detector.js

@@ -65,8 +65,12 @@ function safeReadCheckpoint(absPath) {
         const content = mutable;
         return { path: absPath, mtime: stat.mtime, content };
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return null;
+    catch (err) { // TODO(g2): legacy silent catch — now narrows to IO errors only (grace: 1 minor release, v2.14.0)
+        if (err instanceof ReferenceError)
+            throw err; // surface module-load bugs
+        if (err instanceof SyntaxError)
+            throw err; // surface parse bugs
+        return null; // only swallow IO errors
     }
 }
 function readLatestTodayCheckpoint(runtimeDir, now) {
@@ -223,8 +227,12 @@ function readActiveSkillName(projectRoot) {
         const presence = getSkillPresence(projectRoot);
         return presence?.skill;
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return undefined;
+    catch (err) { // TODO(g2): legacy silent catch — now narrows to IO errors only (grace: 1 minor release, v2.14.0)
+        if (err instanceof ReferenceError)
+            throw err; // surface module-load bugs
+        if (err instanceof SyntaxError)
+            throw err; // surface parse bugs
+        return undefined; // only swallow IO errors
     }
 }
 /**

package/dist/services/code/step-08-gate.js

@@ -85,8 +85,12 @@ function readProgressIfAny(projectRoot, sessionId, jid) {
         }
         return null;
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return null;
+    catch (err) { // narrows to IO errors only — surface ReferenceError / SyntaxError so future module-load or parse bugs fail loudly (instead of silently masking progress.json corruption)
+        if (err instanceof ReferenceError)
+            throw err; // surface module-load bugs
+        if (err instanceof SyntaxError)
+            throw err; // surface parse bugs (corrupt progress.json)
+        return null; // only swallow IO errors (ENOENT, EACCES, …)
     }
 }
 function readPromptFromLastPromptFile(projectRoot, sessionId) {

package/dist/services/compact-statusline/compact-lifecycle-store.d.ts

@@ -0,0 +1,68 @@
+export type CompactLifecycleStage = 'queued' | 'preparing' | 'compacting' | 'verifying' | 'completed' | 'failed';
+export interface CompactLifecycleRecord {
+    readonly schemaVersion: 1;
+    readonly runId: string;
+    readonly stage: CompactLifecycleStage;
+    readonly updatedAt: string;
+    readonly triggerRatio: number;
+    readonly afterRatio?: number;
+    readonly redLine: boolean;
+    readonly failedAt?: Exclude<CompactLifecycleStage, 'failed' | 'completed'>;
+    readonly errorSummary?: string;
+}
+export type CompactLifecycleRead = {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'valid';
+    readonly record: CompactLifecycleRecord;
+} | {
+    readonly kind: 'invalid';
+    readonly reason: string;
+} | {
+    readonly kind: 'stalled';
+    readonly record: CompactLifecycleRecord;
+};
+/**
+ * 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 declare function writeCompactLifecycle(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly record: CompactLifecycleRecord;
+}): void;
+/**
+ * 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 declare function readCompactLifecycle(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly nowMs: number;
+    readonly staleAfterMs: number;
+}): CompactLifecycleRead;