peaks-loop 4.0.47 → 4.0.48

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

@@ -275,3 +275,172 @@ export function settleOpenLifecycleRun(input) {
     emit('completed', true);
     return { runId: prior.runId, triggerRatio: prior.triggerRatio, afterRatio: input.measuredRatio };
 }
+/**
+ * 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 prior = readOpenCompactLifecycle({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId
+    });
+    if (prior === null)
+        return null;
+    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 prior = readOpenCompactLifecycle({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId
+    });
+    if (prior === null)
+        return null;
+    // 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

@@ -42,7 +42,7 @@ import { describeHarnessWindowSync, harnessWindowSyncWarning } from '../context/
 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, 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
@@ -389,7 +389,18 @@ export async function runAutoCompact(input) {
             source: probe.source,
             autoFireThreshold: thresholdFor(mode, 'autoFire'),
             onLifecycleStage: input.onLifecycleStage
-        });
+        }) ??
+            // 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

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

@@ -0,0 +1,122 @@
+/** 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;
+    /**
+     * False when the run settled but the `observed` row could not be
+     * appended. The settlement is the load-bearing half and is never undone
+     * for this, but the two outcomes are not the same fact.
+     */
+    readonly historyWritten: boolean;
+    /**
+     * False when the lifecycle record could not be written. The run is then
+     * still open, so a later probe will settle it from its own measurement —
+     * but the `observed` row is appended anyway, because the harness's
+     * statement is evidence independent of that write. The two failures 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;

package/dist/services/code/compact-event-settle.js

@@ -0,0 +1,219 @@
+/**
+ * rid `2026-09-13-compact-event-settle` — what runs when the HARNESS says a
+ * compaction completed.
+ *
+ * THE PROBLEM THIS EXISTS TO DELETE. Before this slice peaks-loop learned that
+ * a compaction had happened by INFERENCE: `src/services/code/auto-compact-orchestrator.ts`
+ * probes the context ratio on every run, and a ratio that has fallen back below
+ * the auto-fire threshold is taken as proof that a previously-dispatched
+ * compact landed. That is a guess with three failure modes, all silent — the
+ * probe may not measure at all (`conservative-fallback`), the next probe may
+ * not come for minutes (during which the ratio has already climbed back up),
+ * and a compaction that left the ratio high is invisible.
+ *
+ * `PostCompact` is the harness STATING it. This module turns that statement
+ * into the same lifecycle settlement the probe path produces, plus an
+ * `observed` row carrying the one fact the probe path can never produce: what
+ * the harness said the compaction WAS — `manual` or `auto`.
+ *
+ * FOUR THINGS THIS MODULE REFUSES TO DO, EACH FOR A REASON:
+ *
+ *   1. It does not invent a `trigger`. `PostCompact`'s payload schema is
+ *      truncated in the retrievable docs, so a payload without the field is an
+ *      expected input. Absent stays absent. Defaulting it to `'auto'` would
+ *      answer "has this machine ever auto-compacted?" with a fabricated yes,
+ *      which is worse than the current "no answer".
+ *   2. It does not settle when no run is open. A `PostCompact` on a session
+ *      peaks-loop never dispatched for has nothing to attribute, and
+ *      `CompactHistoryEvent.beforeRatio` is a required number that could only
+ *      be filled with a ratio measured AFTER the compaction — a fabricated
+ *      "before". See the RD tech-doc §D8: covering that case needs a
+ *      `PreCompact` snapshot and is a separate slice, not a widened contract.
+ *   3. It does not let a stale measurement become an `afterRatio`. The probe's
+ *      statusline source may still hold the pre-compact value at the instant
+ *      this runs; `settleOpenLifecycleRunOnCompactEvent` drops anything that is
+ *      not below the dispatch ratio.
+ *   4. It does not settle a run off an event that names a DIFFERENT harness
+ *      session, and it does not label one `'main'` without checking. A payload
+ *      whose `session_id` is another session's would otherwise close this
+ *      project's open run and file the row as the main session's. The check is
+ *      best-effort in one direction only: an absent `session_id`, or a project
+ *      whose own harness session id cannot be resolved, is accepted rather than
+ *      refused — a guard that cannot see the name it is checking against must
+ *      not turn a missing field into a hook that never settles anything.
+ *
+ * NOTHING HERE THROWS. The caller is a hook on the harness's compaction path,
+ * where a failure must cost a telemetry row and nothing else.
+ */
+import { resolveAutoCompactProfile } from '../mode/mode-status-service.js';
+import { readContextPercent } from '../context/auto-compact-reader.js';
+import { resolveOuterSessionId } from '../session/binding-status-service.js';
+import { appendCompactHistoryEvent } from './auto-compact-orchestrator.js';
+import { settleOpenLifecycleRunOnCompactEvent } from './auto-compact-lifecycle.js';
+/**
+ * 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 const COMPACT_EVENT_PATHWAY = 'post-compact-hook';
+/**
+ * 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 function readTriggerFromHookPayload(payload) {
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload))
+        return undefined;
+    const raw = payload.trigger;
+    return raw === 'manual' || raw === 'auto' ? raw : 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 function readSessionIdFromHookPayload(payload) {
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload))
+        return undefined;
+    const raw = payload.session_id;
+    return typeof raw === 'string' && raw.length > 0 ? raw : 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 function measurePostCompact(input) {
+    const probe = readContextPercent({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        outerSessionId: resolveOuterSessionId(input.projectRoot, input.sessionId, input.env),
+        env: input.env
+    });
+    const unmeasurable = probe.source === 'conservative-fallback';
+    return {
+        ratio: unmeasurable ? null : probe.ratio,
+        ide: probe.ide,
+        windowTokens: unmeasurable || typeof probe.capacityTokens !== 'number' ? null : probe.capacityTokens,
+        windowSource: unmeasurable ? null : (probe.capacitySource ?? null)
+    };
+}
+/**
+ * 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 function settleCompactFromHarnessEvent(input) {
+    const env = input.env ?? process.env;
+    const measure = input.measure ??
+        (() => measurePostCompact({ projectRoot: input.projectRoot, sessionId: input.sessionId, env }));
+    // Attribution first, and before the probe: an event that is not about this
+    // session must not spend a measurement, and must not touch this run at all.
+    // The comparison is harness-id to harness-id — the payload's `session_id` and
+    // this project's own outer session id as `resolveOuterSessionId` resolves it
+    // (env signal, then the binding's recorded id). It is never compared against
+    // the peaks-loop session id, which is a different namespace and would differ
+    // on every legitimate event.
+    if (input.hookSessionId !== undefined) {
+        const ownOuterSessionId = resolveOuterSessionId(input.projectRoot, input.sessionId, env);
+        if (ownOuterSessionId !== undefined && ownOuterSessionId !== input.hookSessionId) {
+            return { settled: false, reason: 'different-session' };
+        }
+    }
+    let measurement = null;
+    try {
+        measurement = measure();
+    }
+    catch {
+        // A ruler that broke is not a reason to refuse the harness's statement.
+        measurement = null;
+    }
+    const settled = settleOpenLifecycleRunOnCompactEvent({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        measuredRatio: measurement?.ratio ?? null,
+        failLifecycleWrite: input.failLifecycleWrite
+    });
+    if (settled === null) {
+        return { settled: false, reason: 'nothing-to-settle' };
+    }
+    const event = {
+        schemaVersion: 1,
+        kind: 'observed',
+        ts: new Date().toISOString(),
+        // The guard above refused every payload that named another session, so
+        // reaching here means the event named this one or named none. The row is
+        // therefore attributable to the main session, which is the only session
+        // this command settles.
+        target: 'main',
+        mode: resolveAutoCompactProfile(input.projectRoot),
+        ide: measurement?.ide ?? 'claude-code',
+        pathway: COMPACT_EVENT_PATHWAY,
+        beforeRatio: settled.triggerRatio,
+        ...(settled.afterRatio !== null ? { afterRatio: settled.afterRatio } : {}),
+        ...(input.trigger !== undefined ? { trigger: input.trigger } : {}),
+        redLine: false,
+        ok: true,
+        checkpointPath: '',
+        dispatchMessage: `PostCompact fired: the harness reported a ${input.trigger ?? 'unreported-trigger'} compaction, ` +
+            `settling the run dispatched at ${(settled.triggerRatio * 100).toFixed(1)}%` +
+            (settled.afterRatio !== null
+                ? ` (measured now at ${(settled.afterRatio * 100).toFixed(1)}%)`
+                : ' (no post-compact measurement available)'),
+        ...(settled.afterRatio !== null
+            ? { windowTokens: measurement?.windowTokens ?? null, windowSource: measurement?.windowSource ?? null }
+            : {})
+    };
+    try {
+        appendCompactHistoryEvent({ projectRoot: input.projectRoot, sessionId: input.sessionId, event });
+    }
+    catch {
+        // The lifecycle run is already settled; losing the history row is the
+        // smaller loss, and a throwing hook is the larger one. Reported rather
+        // than silenced: "the run settled but the row is missing" and "the row is
+        // on disk" are different facts, and a caller that cannot tell them apart
+        // cannot diagnose a hook that has stopped recording anything.
+        return {
+            settled: true,
+            runId: settled.runId,
+            beforeRatio: settled.triggerRatio,
+            afterRatio: settled.afterRatio,
+            historyWritten: false,
+            lifecycleWritten: settled.lifecycleWritten,
+            ...(input.trigger !== undefined ? { trigger: input.trigger } : {})
+        };
+    }
+    return {
+        settled: true,
+        runId: settled.runId,
+        beforeRatio: settled.triggerRatio,
+        afterRatio: settled.afterRatio,
+        historyWritten: true,
+        lifecycleWritten: settled.lifecycleWritten,
+        ...(input.trigger !== undefined ? { trigger: input.trigger } : {})
+    };
+}

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

@@ -26,6 +26,20 @@ export interface CompactHistoryEvent {
     readonly kind?: 'dispatch' | 'observed';
     /** `observed` rows only: the measured post-compact ratio. */
     readonly afterRatio?: number;
+    /**
+     * rid `2026-09-13-compact-event-settle`: what the HARNESS said caused the
+     * compaction — `manual` (a user ran `/compact`) or `auto` (the harness's own
+     * window fired). Written only by the `PostCompact` hook path, which is the
+     * only path a harness reports it on.
+     *
+     * OPTIONAL, AND ABSENT MEANS "NOT REPORTED" — never "manual", never "auto".
+     * `PostCompact`'s payload schema is truncated in the retrievable docs, so a
+     * payload without the field is an expected input, not an error; the whole
+     * reason this column exists is that "has this machine ever auto-compacted?"
+     * has no answer today, and a defaulted value would answer it falsely.
+     * Rows that predate the slice omit it, exactly like `windowTokens` / `kind`.
+     */
+    readonly trigger?: 'manual' | 'auto';
 }
 /**
  * One dispatch paired with the measurement that followed it — the

package/dist/services/config/config-restore.d.ts

@@ -1,9 +1,20 @@
+export interface RestoreListResult {
+    /**
+     * True when `~/.peaks/config.json.1.x.bak` exists — i.e. whether there is
+     * anything to restore from at all. Meaning is identical to
+     * `RollbackPlan.available`.
+     */
+    available: boolean;
+    fields: string[];
+}
 export interface RestoreResult {
+    /** See `RestoreListResult.available`. */
+    available: boolean;
     field: string;
     applied: boolean;
     sidecarPath?: string;
 }
-export declare function listAvailableFields(): string[];
+export declare function listAvailableFields(): RestoreListResult;
 export declare function restoreField(opts: {
     field: string;
     apply: boolean;

package/dist/services/config/config-restore.js

@@ -9,21 +9,52 @@ import { backupConfigPath } from './config-migration.js';
  * can review before adopting. Fields in the deferred-design set
  * (workspaces, providers, proxy) throw RESTORE_GUARDED so the user has
  * to acknowledge explicitly.
+ *
+ * MISSING BACKUP IS NOT A FAILURE (rid 2026-09-13-two-decisions ①, user-
+ * decided). `~/.peaks/config.json.1.x.bak` only exists on a machine that ran
+ * `peaks config migrate --apply`; a machine that never did is in its NORMAL
+ * initial state, not in an error state. Both subcommands therefore report it
+ * as a SUCCESS carrying `available: false` rather than throwing — the sibling
+ * `rollback` already did, and `restore` exited 1 for the same state, so a
+ * script could not ask either one "was there ever a backup?" without knowing
+ * which subcommand it was talking to.
+ *
+ * ⚠️ THE COST, ACCEPTED BY THE USER: an existing script that read exit 1 as
+ * "never backed up" loses that signal. The replacement is `available` — it is
+ * on EVERY envelope this module produces, on the success path (`false` ⇒
+ * nothing to restore, exit 0) and on the failure path (`true` ⇒ a backup IS
+ * there and the field/guard was the problem, exit 1), so one JSON key answers
+ * the question that used to take the exit code, and it distinguishes "no
+ * backup" from "backup exists but the field is not in it".
  */
 const GUARDED_FIELDS = new Set(['workspaces', 'providers', 'proxy']);
+/**
+ * The parsed `.bak`, or `null` when there is none. `null` is the normal
+ * "nothing was ever migrated" state (see the module comment), not an error.
+ *
+ * A `.bak` that exists but does not parse still throws: `available` means
+ * "the backup file is present", and a present-but-malformed one is a real
+ * failure the caller must surface.
+ */
 function readBakContent() {
     const bak = backupConfigPath();
     if (!existsSync(bak)) {
-        throw new Error('NO_BACKUP: ~/.peaks/config.json.1.x.bak not found');
+        return null;
     }
     return JSON.parse(readFileSync(bak, 'utf8'));
 }
 export function listAvailableFields() {
     const bak = readBakContent();
-    return Object.keys(bak).filter((k) => k !== 'version');
+    if (bak === null) {
+        return { available: false, fields: [] };
+    }
+    return { available: true, fields: Object.keys(bak).filter((k) => k !== 'version') };
 }
 export function restoreField(opts) {
     const bak = readBakContent();
+    if (bak === null) {
+        return { available: false, field: opts.field, applied: false };
+    }
     if (!(opts.field in bak)) {
         throw new Error(`FIELD_NOT_FOUND: ${opts.field} is not in config.json.1.x.bak`);
     }
@@ -33,7 +64,7 @@ export function restoreField(opts) {
     const home = homedir();
     const sidecar = join(home, '.peaks', `config.json.restore-${opts.field}.json`);
     if (!opts.apply) {
-        return { field: opts.field, applied: false };
+        return { available: true, field: opts.field, applied: false };
     }
     mkdirSync(join(home, '.peaks'), { recursive: true });
     const payload = {
@@ -43,5 +74,5 @@ export function restoreField(opts) {
         restoredAt: new Date().toISOString(),
     };
     writeFileSync(sidecar, JSON.stringify(payload, null, 2) + '\n', 'utf8');
-    return { field: opts.field, applied: true, sidecarPath: sidecar };
+    return { available: true, field: opts.field, applied: true, sidecarPath: sidecar };
 }