peaks-loop 4.0.47 → 4.0.49

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

@@ -13,6 +13,7 @@
  */
 import { readCompactLifecycle, writeCompactLifecycle } from '../compact-statusline/compact-lifecycle-store.js';
 import { AUTO_COMPACT_RED_LINE_RATIO } from '../context/auto-compact-types.js';
+import { tryGetSessionDir } from '../session/getSessionDir.js';
 /**
  * PRD-002b slice 2 — extract the few cross-cutting magic numbers
  * that actually appear at runtime call sites in this orchestrator.
@@ -68,11 +69,18 @@ export function newCompactRunId(now) {
  * 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.
+ * The session id is resolved through `tryGetSessionDir` FIRST, so the
+ * guard's throw is answered before the store is entered and the failing
+ * branch is a value the caller must handle rather than a `catch` nobody
+ * reads. The residual `catch` is therefore unreachable for a bad id;
+ * anything that reaches it is a store fault, and a store fault is still
+ * not "there is no open run" — hence `unresolvable`, never `none`.
  */
 function readOpenCompactLifecycle(input) {
+    const resolved = tryGetSessionDir(input.projectRoot, input.sessionId);
+    if (!resolved.ok) {
+        return { kind: 'unresolvable', reason: resolved.reason };
+    }
     let out;
     try {
         out = readCompactLifecycle({
@@ -85,10 +93,21 @@ function readOpenCompactLifecycle(input) {
             staleAfterMs: Number.MAX_SAFE_INTEGER
         });
     }
-    catch {
-        return null;
+    catch (error) {
+        return { kind: 'unresolvable', reason: summarizeLifecycleError(error) };
     }
-    return out.kind === 'valid' ? out.record : null;
+    return out.kind === 'valid' ? { kind: 'found', record: out.record } : { kind: 'none' };
+}
+export function readOpenDispatchRun(input) {
+    const read = readOpenCompactLifecycle(input);
+    if (read.kind === 'unresolvable')
+        return read;
+    if (read.kind === 'none')
+        return { kind: 'none' };
+    const record = read.record;
+    if (record.stage !== 'armed' && record.stage !== 'compacting')
+        return { kind: 'none' };
+    return { kind: 'open', runId: record.runId, stage: record.stage, triggerRatio: record.triggerRatio };
 }
 /**
  * Slice 2026-08-01-compact-lifecycle (Task 5): the local transition
@@ -220,6 +239,18 @@ export function summarizeLifecycleError(error) {
  * `afterRatio` to append the "observed compaction point" row that makes the
  * intent-vs-observed gap readable after a real session. The return value is
  * telemetry only — callers that ignore it are unaffected.
+ *
+ * `lifecycleWritten` (repair R6) makes the returned record honest about
+ * whether the RUN actually moved. Before it, a failed write still returned
+ * the full envelope, so a store that could not be written reported a settle
+ * on every probe, forever: the run stayed `armed`, the next probe found it
+ * open again, and each one added another "observed compaction point" row —
+ * an unbounded append driven by a write that never happened. A failed write
+ * is not an absent run (the facts are real and stay true, so the caller may
+ * still record the measurement), but it is also not a settled one. This is
+ * the same field `settleOpenLifecycleRunOnCompactEvent` carries, for the
+ * same reason, so the two settle paths no longer disagree about what a write
+ * failure means.
  */
 export function settleOpenLifecycleRun(input) {
     // A `conservative-fallback` probe means no signal was available at
@@ -229,12 +260,17 @@ export function settleOpenLifecycleRun(input) {
         return null;
     if (input.measuredRatio >= input.autoFireThreshold)
         return null;
-    const prior = readOpenCompactLifecycle({
+    const openRead = readOpenCompactLifecycle({
         projectRoot: input.projectRoot,
         sessionId: input.sessionId
     });
-    if (prior === null)
+    // Both `none` and `unresolvable` mean "nothing to settle" HERE, and the
+    // collapse is legitimate on this path rather than a fail-open: settling
+    // ADMITS nothing. No record can exist under an id that names no session
+    // directory, so there is nothing this probe could have been about.
+    if (openRead.kind !== 'found')
         return null;
+    const prior = openRead.record;
     // Only a run that was actually dispatched can be completed by a
     // post-compact measurement. Both `compacting` (the in-band trigger is
     // satisfied) and `armed` (a trigger was registered and could fire at
@@ -253,6 +289,8 @@ export function settleOpenLifecycleRun(input) {
             ...(withAfterRatio ? { afterRatio: input.measuredRatio } : {})
         };
         try {
+            if (input.failLifecycleWrite)
+                throw new Error('lifecycle store unavailable');
             writeCompactLifecycle({
                 projectRoot: input.projectRoot,
                 sessionId: input.sessionId,
@@ -260,7 +298,10 @@ export function settleOpenLifecycleRun(input) {
             });
         }
         catch {
-            return;
+            // Best-effort telemetry, as everywhere in this file — but the failure is
+            // REPORTED to the caller as `lifecycleWritten: false` rather than folded
+            // into a record that reads as settled.
+            return false;
         }
         try {
             input.onLifecycleStage?.(stage, record);
@@ -268,10 +309,187 @@ export function settleOpenLifecycleRun(input) {
         catch {
             // Observer failures are not ours to propagate.
         }
+        return true;
     };
     // `verifying` = we hold a measurement and are checking it.
     emit('verifying', false);
-    // `completed` = the measurement confirms the drop; publish it.
-    emit('completed', true);
+    // `completed` = the measurement confirms the drop; publish it. This write
+    // is the one that closes the run, so it is the one that is reported.
+    const lifecycleWritten = emit('completed', true);
+    return { runId: prior.runId, triggerRatio: prior.triggerRatio, afterRatio: input.measuredRatio, lifecycleWritten };
+}
+/**
+ * rid `2026-09-13-compact-event-settle`: close out an open compact run because
+ * the HARNESS said one completed — `PostCompact` — rather than because a later
+ * probe noticed the ratio had fallen.
+ *
+ * WHY THIS IS A SECOND FUNCTION AND NOT A FLAG ON THE ONE ABOVE. The function
+ * above is defined by two MEASUREMENT gates: it refuses when nothing could be
+ * measured, and refuses when the number it got has not dropped far enough. Both
+ * are correct for a probe, whose ratio is an INFERENCE about whether something
+ * happened. Handed a harness event, both are wrong in the same direction —
+ * the harness has already stated that the compaction happened, so a probe that
+ * could not measure, or measured something larger, contradicts nothing. The
+ * event is the evidence; the ratio is a consequence.
+ *
+ * What survives from the probe path is the ATTRIBUTION gate, and only that:
+ * there must be an open run (`compacting` / `armed`) for this event to be
+ * about. A `PostCompact` on a session where peaks-loop never dispatched has
+ * nothing to settle — objectively, the run the event would complete does not
+ * exist. (`queued` / `preparing` are excluded for the probe path's reason: a
+ * run that died before dispatch never had a compaction to complete.)
+ *
+ * `afterRatio` is recorded ONLY when it is a genuine DROP below the ratio the
+ * dispatch was made at. Immediately after a compaction, `readContextPercent`
+ * prefers the statusline file, which may still hold the PRE-compact value; the
+ * one thing this row must not do is launder that stale reading into an
+ * `afterRatio` and publish "the context did not shrink" as a measurement. A
+ * `null` here means "no honest post-compact number was available at the moment
+ * the event fired" — and that is NOT self-healing: the record is left at
+ * `completed` with no number, `computeWindowCalibration` skips `observed` rows
+ * that carry none, and the probe path refuses a run that is no longer open. The
+ * pair is then closed by `fillEventSettledMeasurement` below — but only on the
+ * probes that reach it, which is not all of them: that call sits in the
+ * BELOW-THRESHOLD branch of `runAutoCompact` (`auto-compact-orchestrator.ts:567`
+ * guards it, `:589` calls it). A probe that instead commits to compacting does
+ * not merely defer the measurement: `advance('queued')` writes a fresh run to
+ * the same one-record-per-session store (`auto-compact-orchestrator.ts:668`), so
+ * the `completed`-without-`afterRatio` record this pair was owed is gone and the
+ * pair stays unmeasured. That loss is inherent rather than an oversight — once a
+ * second compaction has happened, no later ratio can be attributed to the first,
+ * so there is nothing honest left to fill — and it is visible as `unmeasured` in
+ * `peaks compact history` (QA residual R9). A fabricated number is not
+ * recoverable at all, which is why the stale reading is dropped rather than
+ * corrected.
+ *
+ * `verifying` is deliberately NOT emitted: its documented meaning is "we hold a
+ * measurement and are checking it", and on this path there may be no
+ * measurement at all. Emitting it would move the same untruth from the history
+ * row into the lifecycle record.
+ *
+ * Returns the settled facts, or `null` when there was nothing to settle. `null`
+ * means exactly ONE thing here — there was no OPEN run for this event to be
+ * about. A run that was open but whose record could not be written is not
+ * `null`: it returns the facts read off that run with `lifecycleWritten: false`,
+ * because a failed write is not an absent run, and a caller that cannot tell the
+ * two apart ends up telling the user a falsehood (see `compact-event-settle.ts`).
+ */
+export function settleOpenLifecycleRunOnCompactEvent(input) {
+    const openRead = readOpenCompactLifecycle({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId
+    });
+    // Same collapse as `settleOpenLifecycleRun` above, for the same reason:
+    // an unresolvable id names no session directory, so no open run exists
+    // for this event to be about, and `null` here admits nothing.
+    if (openRead.kind !== 'found')
+        return null;
+    const prior = openRead.record;
+    if (prior.stage !== 'compacting' && prior.stage !== 'armed')
+        return null;
+    const afterRatio = input.measuredRatio !== null && input.measuredRatio < prior.triggerRatio ? input.measuredRatio : null;
+    const record = {
+        schemaVersion: 1,
+        runId: prior.runId,
+        stage: 'completed',
+        updatedAt: new Date().toISOString(),
+        triggerRatio: prior.triggerRatio,
+        redLine: prior.redLine,
+        ...(afterRatio !== null ? { afterRatio } : {})
+    };
+    const facts = { runId: prior.runId, triggerRatio: prior.triggerRatio, afterRatio };
+    try {
+        if (input.failLifecycleWrite)
+            throw new Error('lifecycle store unavailable');
+        writeCompactLifecycle({
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            record
+        });
+    }
+    catch {
+        // Deliberately NOT `null`. The run WAS open and the write FAILED; returning
+        // the same value as "no run is open" is the conflation the repo's own lint
+        // names at this exact line (`catch-return-null — caller cannot distinguish
+        // failure from success`), and it reached the user as "No compact run was
+        // open", which is false.
+        return { ...facts, lifecycleWritten: false };
+    }
+    try {
+        input.onLifecycleStage?.('completed', record);
+    }
+    catch {
+        // Observer failures are not ours to propagate.
+    }
+    return { ...facts, lifecycleWritten: true };
+}
+/**
+ * rid `2026-09-13-compact-event-settle` (repair R1): supply the measurement a
+ * harness-settled run was left owing.
+ *
+ * The function above deliberately refuses to launder a post-compact reading
+ * that has not dropped — and right after a compaction that refusal is the
+ * NORMAL case, because the statusline still holds the pre-compact value. The
+ * run is then closed at `completed` with no `afterRatio`, so the dispatch's
+ * calibration pair never closes and "intent vs observed" stays blank for
+ * exactly the compactions this slice exists to witness. This function is what
+ * makes the function above's promise payable.
+ *
+ * WHY NOT WIDEN `settleOpenLifecycleRun`. That one re-emits `verifying` before
+ * `completed`, which on an already-`completed` record is a backwards stage
+ * transition with no observer to serve. This is not a settlement — the run IS
+ * settled; only the number is owed. So no stage is rewritten here.
+ *
+ * WRITING `afterRatio` ONTO THE RECORD IS THE IDEMPOTENCE TOKEN: every later
+ * probe finds it present and returns `null`, so however many probes follow, one
+ * compaction yields exactly one late measurement.
+ *
+ * THE DROP GATE IS THE EVENT PATH'S OWN (`measuredRatio < triggerRatio`), not
+ * the probe path's `autoFireThreshold`. `afterRatio` has to mean "below the
+ * ratio this run was dispatched at" — the rule the event path already enforces
+ * — or a run dispatched under the threshold (a forced or banded dispatch) would
+ * let a NON-drop through the one path that can still write a `completed` record.
+ * `conservative-fallback` is refused for the probe path's reason: its `0` is
+ * the absence of a measurement, not an empty context.
+ *
+ * Returns the filled record, or `null` when no run is owed a measurement.
+ */
+export function fillEventSettledMeasurement(input) {
+    if (input.source === 'conservative-fallback')
+        return null;
+    const openRead = readOpenCompactLifecycle({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId
+    });
+    // Same collapse as the two settle paths above — `null` here admits nothing.
+    if (openRead.kind !== 'found')
+        return null;
+    const prior = openRead.record;
+    // Exactly one shape is owed a number: the one the EVENT path leaves behind.
+    // `settleOpenLifecycleRun` never writes it (it always carries `afterRatio`),
+    // and a `failed` run never dispatched, so it has no row to pair with.
+    if (prior.stage !== 'completed' || prior.afterRatio !== undefined)
+        return null;
+    if (input.measuredRatio >= prior.triggerRatio)
+        return null;
+    const record = {
+        schemaVersion: 1,
+        runId: prior.runId,
+        stage: 'completed',
+        updatedAt: new Date().toISOString(),
+        triggerRatio: prior.triggerRatio,
+        redLine: prior.redLine,
+        afterRatio: input.measuredRatio
+    };
+    try {
+        writeCompactLifecycle({
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            record
+        });
+    }
+    catch {
+        return null;
+    }
     return { runId: prior.runId, triggerRatio: prior.triggerRatio, afterRatio: input.measuredRatio };
 }

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

@@ -36,13 +36,14 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { getSessionIdCanonical } from '../session/session-manager.js';
+import { getSessionDir } from '../session/getSessionDir.js';
 import { resolveOuterSessionId } from '../session/binding-status-service.js';
 import { resolveCanonicalProjectRoot } from '../config/config-service.js';
 import { describeHarnessWindowSync, harnessWindowSyncWarning } from '../context/harness-window-config.js';
 import { AUTO_COMPACT_PRE_COMPACT_RATIO, DEPRECATED_ENVELOPE_FIELDS } from '../context/auto-compact-types.js';
 import { describeMode, thresholdFor } from './auto-compact-modes.js';
 import { resolveAutoCompactProfile } from '../mode/mode-status-service.js';
-import { CompactLifecyclePublisher, newCompactRunId, resolveDispatchedStage, settleOpenLifecycleRun, summarizeLifecycleError } from './auto-compact-lifecycle.js';
+import { CompactLifecyclePublisher, fillEventSettledMeasurement, newCompactRunId, readOpenDispatchRun, resolveDispatchedStage, settleOpenLifecycleRun, summarizeLifecycleError } from './auto-compact-lifecycle.js';
 const PRE_COMPACT_REASON = 'pre-compact-auto';
 /**
  * Map a context ratio to a `CompactTrigger` action. Pure; the side
@@ -195,7 +196,10 @@ export function buildConvergencePlan(input) {
  * transcript).
  */
 function appendAutoDecisionLog(input) {
-    const dir = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'txt');
+    // Repair R6: same hand-rolled join as `writePreCompactCheckpoint`. All four
+    // session-scoped paths in this file now go through the axis builder; none
+    // composes the join itself, so none can resolve outside the project root.
+    const dir = join(getSessionDir(input.projectRoot, input.sessionId), 'txt');
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
     const logPath = join(dir, 'auto-decisions.md');
@@ -235,7 +239,7 @@ function appendAutoDecisionLog(input) {
  * state re-injection. Not a capability peaks-loop has today.
  */
 function writeMainSessionCompactIntent(input) {
-    const dir = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'txt');
+    const dir = join(getSessionDir(input.projectRoot, input.sessionId), 'txt');
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
     const path = join(dir, 'auto-compact-pending.json');
@@ -255,7 +259,12 @@ function writeMainSessionCompactIntent(input) {
  * checkpoint` so D7's post-compact-detect picks it up unchanged.
  */
 function writePreCompactCheckpoint(input) {
-    const dir = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'checkpoints');
+    // Repair R6: this used to hand-roll the session join, which is the one shape
+    // `getSessionDir`'s own header records as NOT covered by the guard — an
+    // unsafe id resolved outside the project root and the checkpoint was written
+    // there. The gate above now refuses an unresolvable id before this point, but
+    // `--force` outranks that gate, so this join has to hold on its own.
+    const dir = join(getSessionDir(input.projectRoot, input.sessionId), 'checkpoints');
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
     const prefix = input.redLine === true ? 'red-line-' : 'pre-compact-';
@@ -382,14 +391,37 @@ export async function runAutoCompact(input) {
         // 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.
-        const settled = settleOpenLifecycleRun({
+        const settleRead = settleOpenLifecycleRun({
             projectRoot: input.projectRoot,
             sessionId,
             measuredRatio: probe.ratio,
             source: probe.source,
             autoFireThreshold: thresholdFor(mode, 'autoFire'),
-            onLifecycleStage: input.onLifecycleStage
+            onLifecycleStage: input.onLifecycleStage,
+            failLifecycleWrite: input.testHooks?.failLifecycleWrite
         });
+        // Repair R6 (AC3): a settle whose lifecycle write FAILED has not settled the
+        // run — the record is still resting at `armed` / `compacting`, so the next
+        // probe finds the same run open and settles it again. Appending the
+        // "observed compaction point" row anyway writes one row per probe for a
+        // compaction the lifecycle store never recorded: an unbounded append driven
+        // by a write that did not happen, and a history row whose paired lifecycle
+        // record does not exist. Nothing is lost by deferring the row — `probe.ratio`
+        // is re-measured on every probe, so the retry carries a fresh number.
+        const settled = settleRead !== null && !settleRead.lifecycleWritten
+            ? null
+            : (settleRead ??
+                // Repair R1 (`2026-09-13-compact-event-settle`): the HARNESS event may
+                // already have closed this run WITHOUT an honest post-compact number —
+                // in which case the call above finds nothing open, and without this the
+                // calibration pair stays blank for exactly the compactions the event path
+                // exists to witness. Fills the number the event owed.
+                fillEventSettledMeasurement({
+                    projectRoot: input.projectRoot,
+                    sessionId,
+                    measuredRatio: probe.ratio,
+                    source: probe.source
+                }));
         // Slice 2026-09-13-auto-compact-trigger-ownership (T4): a settle means a
         // dispatched compact demonstrably landed. Append an `observed` row
         // carrying the measured ratio, so `peaks compact history` can show
@@ -449,6 +481,85 @@ export async function runAutoCompact(input) {
     }
     const isRedLine = decision.reason === 'red-line';
     const now = input.now ?? new Date();
+    // rid `2026-09-14-compact-dispatch-backoff`: ONE dispatch per compact
+    // attempt.
+    //
+    // The decision above fires whenever the ratio is at or over the auto-fire
+    // threshold, and the ratio does not come back down on its own — nothing in
+    // peaks-loop can compact a running session, and the harness fires only at
+    // its own red line. So "shouldCompact" was true on every probe, forever: one
+    // real session's `compact-history.jsonl` holds 1075 dispatch rows, 444
+    // checkpoints and ZERO compactions over 15.5 h — and the file was still
+    // growing while this slice ran. Re-dispatching bought nothing, because the
+    // `ide-native` dispatch only installs a PreToolUse hook and installing it
+    // again is a documented no-op: 1074 of those 1075 rows say `already
+    // installed` in their own `dispatchMessage`. It produced rows, not
+    // compactions.
+    //
+    // The lifecycle store already knows whether an attempt is outstanding (see
+    // `readOpenDispatchRun` — `armed`/`compacting` = dispatched, `completed`/
+    // `failed` = over), so the gate needs no new state and no threshold: it is
+    // keyed on the STAGE of the open run, never on a ratio, which is why it
+    // survives any future realignment of the 0.65/0.70/0.85/0.95 table.
+    //
+    // What is NOT suppressed: the probe still measures and still reports. The
+    // envelope carries the LIVE ratio plus the ratio the open ask was made at,
+    // so "it crossed and it is still high, unanswered" stays legible on every
+    // turn — the difference between a quiet signal and a silenced one.
+    //
+    // `force` (the `--force` test seam, "force compact at any ratio") outranks
+    // the inference: an explicit instruction must not be silently reduced to a
+    // no-op, which would make the published flag a lie.
+    // Repair R6: `readOpenDispatchRun` answers in THREE states, not two. `none`
+    // admits the dispatch; `unresolvable` means the backoff's question could not
+    // be asked — the session id names no session directory, so no lifecycle
+    // record can exist under it and the gate used to read that as "nothing is
+    // outstanding". Measured on ONE directory before this: a legal sid found the
+    // open `armed` run and suppressed the dispatch; `./<legal sid>`, which joins
+    // to the identical path, returned `null` and dispatched. A gate that reads a
+    // string instead of the artifact the string names is the defect the whole
+    // id axis exists to close, so an unanswerable question is NOT an admit: the
+    // conservative direction is to leave the dispatch undone and say why.
+    const openRun = readOpenDispatchRun({ projectRoot: input.projectRoot, sessionId });
+    if (openRun.kind === 'unresolvable' && input.force !== true) {
+        return {
+            ok: true,
+            code: 'AUTO_COMPACT_UNRESOLVED_SESSION',
+            message: `Context at ${(probe.ratio * 100).toFixed(1)}%; a compact may be warranted, but this session's ` +
+                `directory could not be resolved (${openRun.reason}), so whether a compact was already dispatched ` +
+                `for this crossing cannot be answered. Not dispatching: an unanswered question is not a 'no'. ` +
+                `The session id comes from the active binding or from the caller.`,
+            data: {
+                sessionId,
+                ratio: probe.ratio,
+                source: probe.source,
+                decision: 'unresolved-session',
+                harnessWindow
+            }
+        };
+    }
+    if (openRun.kind === 'open' && input.force !== true) {
+        return {
+            ok: true,
+            code: 'AUTO_COMPACT_ALREADY_ARMED',
+            message: `Context at ${(probe.ratio * 100).toFixed(1)}% — still above the ` +
+                `${(thresholdFor(mode, 'autoFire') * 100).toFixed(0)}% auto-fire threshold (mode=${mode}); ` +
+                `a compact was already dispatched for this crossing at ${(openRun.triggerRatio * 100).toFixed(1)}% ` +
+                `(run ${openRun.runId}, resting at '${openRun.stage}') and nothing has compacted since. ` +
+                `Not dispatching again: the trigger is already registered, so a second dispatch would install the ` +
+                `same hook and add a checkpoint and a history row without adding a capability. ` +
+                `Re-probe with \`peaks code context-now\`.`,
+            data: {
+                sessionId,
+                ratio: probe.ratio,
+                source: probe.source,
+                decision: 'already-armed',
+                armedAtRatio: openRun.triggerRatio,
+                armedRunId: openRun.runId,
+                harnessWindow
+            }
+        };
+    }
     // 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.
@@ -654,7 +765,7 @@ export async function runAutoCompact(input) {
     };
 }
 export function appendCompactHistoryEvent(input) {
-    const dir = join(input.projectRoot, '.peaks', '_runtime', input.sessionId);
+    const dir = getSessionDir(input.projectRoot, input.sessionId);
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
     const path = join(dir, 'compact-history.jsonl');

package/dist/services/code/compact-event-settle.d.ts

@@ -0,0 +1,134 @@
+/** The harness's own report of what caused a compaction. */
+export type CompactTrigger = 'manual' | 'auto';
+/**
+ * Which layer settled the run. `post-compact-hook` = the harness's event;
+ * `post-compact-probe` (written by the orchestrator) = a later probe's
+ * measurement. The two are deliberately distinct strings so a reader of
+ * `compact-history.jsonl` can tell a NOTIFICATION from an INFERENCE — which is
+ * the entire instrument this slice exists to build.
+ */
+export declare const COMPACT_EVENT_PATHWAY = "post-compact-hook";
+/**
+ * One post-compact reading: the ratio, the window it was divided by, and the
+ * adapter that produced it — all from a SINGLE probe call, so the three cannot
+ * disagree with each other.
+ */
+export type PostCompactMeasurement = {
+    /** `null` = nothing could be measured. Never `0`, which means "unknown". */
+    readonly ratio: number | null;
+    readonly ide: string;
+    readonly windowTokens: number | null;
+    readonly windowSource: string | null;
+};
+export type CompactSettleResult = {
+    readonly settled: true;
+    readonly runId: string;
+    readonly beforeRatio: number;
+    /** The measured post-compact ratio, or `null` when none was trustworthy. */
+    readonly afterRatio: number | null;
+    /** Present only when the harness reported one. */
+    readonly trigger?: CompactTrigger;
+    /**
+     * Whether the `observed` row for this event is on disk. `false` means
+     * there is none, for one of two DIFFERENT reasons, told apart by
+     * `lifecycleWritten`:
+     *
+     *   - `lifecycleWritten: true` — the append was attempted and threw.
+     *   - `lifecycleWritten: false` — the append was deliberately not made,
+     *     because the settle it would describe is one the store never
+     *     recorded (see `lifecycleWritten`).
+     */
+    readonly historyWritten: boolean;
+    /**
+     * False when the lifecycle record could not be written. The run is then
+     * still open, and this path does NOT append the `observed` row: the row
+     * would assert a settled measurement for a run the store still holds at
+     * `armed` / `compacting`, and each arrival would add another one. The
+     * row is deferred rather than lost — the run stays open, so the retry
+     * that does land owns the row and measures the ratio at that moment.
+     * This is repair R6's answer on the probe path
+     * (`auto-compact-orchestrator.ts`), applied here so the two settle
+     * paths agree.
+     *
+     * The two halves are reported separately rather than collapsed: a caller
+     * that sees only one of them cannot say which half of the settlement
+     * landed.
+     */
+    readonly lifecycleWritten: boolean;
+} | {
+    readonly settled: false;
+    /**
+     * `nothing-to-settle` — there was no open run. `different-session` — the
+     * payload named a harness session that is not this project's, so the open
+     * run was left alone. The second is a refusal of ATTRIBUTION, not an
+     * absence of it, and a reader told "nothing was open" would be told
+     * something false.
+     */
+    readonly reason: 'nothing-to-settle' | 'different-session';
+};
+/**
+ * Read `trigger` out of an already-parsed `PostCompact` payload.
+ *
+ * Anything that is not exactly `'manual'` or `'auto'` yields `undefined` — a
+ * missing field, a `null`, a number, another string, a payload that is not an
+ * object at all. This function never throws and never guesses (see this file's
+ * header, refusal 1).
+ */
+export declare function readTriggerFromHookPayload(payload: unknown): CompactTrigger | undefined;
+/**
+ * Read the harness session id out of an already-parsed `PostCompact` payload.
+ *
+ * Same contract as `readTriggerFromHookPayload`: a missing field, an empty
+ * string, a number, a non-object payload — every one of those is `undefined`,
+ * and "absent" is an expected input rather than an error (see this file's
+ * header, refusal 4, for what the caller does with it and what it does with
+ * `undefined`).
+ */
+export declare function readSessionIdFromHookPayload(payload: unknown): string | undefined;
+/**
+ * The post-compact ruler: the same probe the orchestrator uses, so this row
+ * divides by the same denominator the dispatch did.
+ *
+ * `ratio` is `null` when nothing could be measured — a `conservative-fallback`
+ * probe reports `0`, but that `0` means "unknown", and recording it here would
+ * publish a real, infinitely-deep drop. The rest of the reading (adapter, the
+ * window the ratio divides by) is still carried, because knowing WHICH adapter
+ * could not measure is diagnostic.
+ */
+export declare function measurePostCompact(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly env: NodeJS.ProcessEnv;
+}): PostCompactMeasurement;
+/**
+ * Settle whatever compact run is open in `sessionId`, because the harness just
+ * reported one.
+ *
+ * `measure` is the ruler, injected rather than called directly for one concrete
+ * reason: the production ruler prefers `~/.claude/statusline-state.json`, a real
+ * file whose contents differ on every machine that runs the test suite. A test
+ * asserting this row's `afterRatio` against the developer's own statusline would
+ * pass or fail by accident. It is called at most once — the IDE tag and the
+ * window come from the same reading, so they cannot disagree with each other.
+ *
+ * Returns `{ settled: false }` when there is no open run — the honest answer,
+ * not an error — and when the payload names another harness session. The two
+ * say different things in `reason`, because they are different facts.
+ */
+export declare function settleCompactFromHarnessEvent(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly trigger?: CompactTrigger | undefined;
+    /**
+     * The harness session id the payload named, when it named one (see
+     * `readSessionIdFromHookPayload`). Refused when it is present AND this
+     * project's own harness session id resolves AND the two differ. Absent, or
+     * unresolvable on this side, is accepted: a guard that cannot see what it is
+     * checking against must not become a hook that never settles anything.
+     */
+    readonly hookSessionId?: string | undefined;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    readonly measure?: (() => PostCompactMeasurement | null) | undefined;
+    /** Failure injection for the lifecycle write — the seam `CompactLifecyclePublisher` already takes. */
+    readonly failLifecycleWrite?: boolean | undefined;
+}): CompactSettleResult;