peaks-loop 4.0.46 → 4.0.48

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/code/orchestrator-can-do.d.ts

@@ -18,8 +18,10 @@
  *        decide, ?, 选择, 决定). If yes → soft warning, NOT a blocker
  *        (the LLM should AskUserQuestion, which is cheap).
  *   Q4 — Is context usage sustainable? (probe `peaks code context-now
- *        --json`). ratio ≥ 0.95 → blocker (red-line); ≥ 0.85 →
- *        blocker (auto-compact-now).
+ *        --json`). ratio ≥ 0.95 → WARNING (red-line, ask-and-wait);
+ *        ≥ 0.85 → WARNING (pre-compact band). Never a blocker — see the
+ *        comment on the Q4 branch in `buildOrchestratorCanDoResult`, and
+ *        `evaluateCompactTrigger`, which is the face this one must agree with.
  *
  * Decision rule:
  *   canDoInSession === (blockers.length === 0)

package/dist/services/code/orchestrator-can-do.js

@@ -18,8 +18,10 @@
  *        decide, ?, 选择, 决定). If yes → soft warning, NOT a blocker
  *        (the LLM should AskUserQuestion, which is cheap).
  *   Q4 — Is context usage sustainable? (probe `peaks code context-now
- *        --json`). ratio ≥ 0.95 → blocker (red-line); ≥ 0.85 →
- *        blocker (auto-compact-now).
+ *        --json`). ratio ≥ 0.95 → WARNING (red-line, ask-and-wait);
+ *        ≥ 0.85 → WARNING (pre-compact band). Never a blocker — see the
+ *        comment on the Q4 branch in `buildOrchestratorCanDoResult`, and
+ *        `evaluateCompactTrigger`, which is the face this one must agree with.
  *
  * Decision rule:
  *   canDoInSession === (blockers.length === 0)
@@ -153,6 +155,7 @@ export async function probeSubAgentAvailable(projectRoot, peaksBin = DEFAULT_PEA
         await execFileAsync(command, [...args, 'sub-agent', 'dispatch', '--role', 'rd', '--help'], {
             cwd: projectRoot,
             timeout: 5000,
+            windowsHide: true,
         });
         return true;
     }
@@ -171,6 +174,7 @@ export async function probeContextRatio(projectRoot, peaksBin = DEFAULT_PEAKS_BI
         const { stdout } = await execFileAsync(command, [...args, 'code', 'context-now', '--project', projectRoot, '--json'], {
             cwd: projectRoot,
             timeout: 10000,
+            windowsHide: true,
         });
         const parsed = JSON.parse(stdout);
         const ratio = typeof parsed.data?.ratio === 'number' ? parsed.data.ratio : 0;
@@ -205,13 +209,41 @@ export function buildOrchestratorCanDoResult(input, signals) {
         blockers.push('sub-agent dispatch unavailable (peaks sub-agent dispatch --help failed)');
         suggestions.push('verify peaks CLI is on PATH; check `peaks --version`');
     }
-    // Q4 — context ratio gate. ≥0.95 → red-line; ≥0.85 → pre-compact.
+    // Q4 — context ratio. ≥0.95 → red-line; ≥0.85 → pre-compact. A WARNING, not
+    // a blocker, and the difference is deliberate (E3, rid 2026-09-13-defects-e).
+    //
+    // Why this is not a blocker any more, and why it is not an oversight:
+    //
+    //   The peak this answers is "can this slice run in the current session".
+    //   Context ratio cannot answer "no" to it. The reason is the one the
+    //   T3 slice (2026-09-13-auto-compact-trigger-ownership) landed on the
+    //   OTHER face of this same threshold: peaks-loop has no executor for a
+    //   running session, so it cannot compact its way out of a high ratio —
+    //   `evaluateCompactTrigger` therefore says of the red line "peaks-loop has
+    //   asked the harness to compact and is WAITING for it — sub-agent dispatch
+    //   is NOT blocked; carry on and re-probe". A probe that returned
+    //   `canDoInSession: false` here would contradict that sentence for the same
+    //   0.95 on the same number, and its only programmatic consumer
+    //   (`code-orchestrator-can-do.ts`) turns the false into exit code 1 — i.e.
+    //   it would re-open, at the CLI layer, exactly the deadlock T3 deleted.
+    //
+    //   Nor does the pre-compact zone (0.85–0.95) earn a blocker: the trigger's
+    //   message there is "peaks-loop already fired the auto-compact pathway; the
+    //   LLM does not need to act", which is the opposite of "you may not proceed".
+    //
+    //   What a blocker would still need to be true: THE ORCHESTRATOR itself
+    //   cannot continue. It can — the slice's edits are delegated to a sub-agent
+    //   (Q1), and the orchestrator's own context is only spent co-ordinating.
+    //
+    //   So the ratio is reported, warned about, and given a next action; the
+    //   verdict is left to the blockers that really are un-survivable (a
+    //   hard-blocked path family, an unreachable sub-agent dispatcher).
     if (signals.q4ContextRatio >= ORCHESTRATOR_REDLINE_RATIO) {
-        blockers.push(`context red-line (ratio=${signals.q4ContextRatio.toFixed(2)} ≥ ${ORCHESTRATOR_REDLINE_RATIO}); auto-compact now or push to next session`);
+        warnings.push(`context red-line (ratio=${signals.q4ContextRatio.toFixed(2)} ≥ ${ORCHESTRATOR_REDLINE_RATIO}): peaks-loop has asked the harness to compact and is waiting for it; dispatch is NOT blocked — carry on and re-probe with \`peaks code context-now\``);
         suggestions.push('peaks code auto-compact');
     }
     else if (signals.q4ContextRatio >= ORCHESTRATOR_PRECOMPACT_RATIO) {
-        blockers.push(`context near limit (ratio=${signals.q4ContextRatio.toFixed(2)} ≥ ${ORCHESTRATOR_PRECOMPACT_RATIO}); auto-compact or push to next session`);
+        warnings.push(`context near limit (ratio=${signals.q4ContextRatio.toFixed(2)} ≥ ${ORCHESTRATOR_PRECOMPACT_RATIO}): in the pre-compact band; peaks-loop fires the auto-compact pathway itself and dispatch is NOT blocked`);
         suggestions.push('peaks code auto-compact');
     }
     // Q3 — user-decision keywords → soft warning, NOT a blocker. The

package/dist/services/codegraph/codegraph-exclude-reconciler.js

@@ -176,7 +176,8 @@ export const CODEGRAPH_CONFIG_FILENAME = 'config.json';
 export function readTrackedFiles(projectRoot) {
     const stdout = execFileSync('git', ['-C', projectRoot, 'ls-files'], {
         encoding: 'utf8',
-        maxBuffer: 64 * 1024 * 1024
+        maxBuffer: 64 * 1024 * 1024,
+        windowsHide: true
     });
     return stdout
         .split('\n')

package/dist/services/codegraph/codegraph-process-runner.js

@@ -27,7 +27,7 @@ function terminateCodegraphProcess(childProcess) {
     }
     if (process.platform === 'win32') {
         if (process.env.SystemRoot) {
-            spawn(join(process.env.SystemRoot, 'System32', 'taskkill.exe'), ['/pid', String(childProcess.pid), '/T', '/F'], { shell: false, stdio: 'ignore' });
+            spawn(join(process.env.SystemRoot, 'System32', 'taskkill.exe'), ['/pid', String(childProcess.pid), '/T', '/F'], { shell: false, stdio: 'ignore', windowsHide: true });
         }
         else {
             childProcess.kill();
@@ -47,7 +47,8 @@ export function defaultCodegraphProcessRunner(invocation) {
             cwd: invocation.cwd,
             detached: process.platform !== 'win32',
             env: createCodegraphEnvironment(),
-            shell: false
+            shell: false,
+            windowsHide: true
         });
         const timeout = setTimeout(() => {
             terminateCodegraphProcess(childProcess);

package/dist/services/compact/request-transition-hook.js

@@ -15,8 +15,11 @@
  *
  * The hook is INVOKED from `src/cli/commands/request-commands.ts`
  * (RD→QA boundary) and from any future QA→final-review boundary. The
- * 0.95 red line is NOT changed: the existing auto-compact
- * orchestrator continues to refuse dispatch at ratio ≥ 0.95.
+ * 0.95 red line is unchanged in THRESHOLD but not in behaviour: the
+ * auto-compact orchestrator asks the harness to compact and reports that
+ * it is waiting. It does not refuse sub-agent dispatch — peaks-loop has no
+ * executor for a running session, so a refusal gated nothing and deadlocked
+ * the runner (slice 2026-09-13-auto-compact-trigger-ownership).
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';

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

@@ -10,7 +10,82 @@ export interface CompactHistoryEvent {
     readonly ok: boolean;
     readonly checkpointPath: string;
     readonly dispatchMessage: string;
+    /**
+     * Slice 2026-09-13-auto-compact-trigger-ownership (T4): the window this
+     * dispatch divided by. `beforeRatio * windowTokens` is the token point
+     * peaks-loop asked the harness to compact at.
+     */
+    readonly windowTokens?: number | null;
+    /** Which layer produced `windowTokens` (env-override | harness-env | config | model-heuristic | default). */
+    readonly windowSource?: string | null;
+    /**
+     * `dispatch` — peaks-loop asked for a compact (every row written before
+     * this slice is implicitly one of these). `observed` — a later probe
+     * MEASURED the ratio after a dispatched compact, proving one landed.
+     */
+    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
+ * intent-vs-observed record for the harness auto-compact window.
+ *
+ * Why a pair and not a number: the slice that owns this instrument could not
+ * run a real Claude Code session, and the harness's own documentation gives
+ * the env var as a WINDOW, not a trigger point, so "a window of X makes the
+ * harness fire at Y%" has no documented answer. Fabricating Y would be worse
+ * than not having it. Recording the intent (`requested*`) next to whatever
+ * the next real session actually measures (`observed*`) is the honest
+ * substitute: after one real session the gap becomes a measured fact.
+ */
+export interface WindowCalibrationPair {
+    readonly dispatchedAt: string;
+    readonly windowTokens: number | null;
+    readonly windowSource: string | null;
+    /** The ratio at which peaks-loop asked. */
+    readonly requestedRatio: number;
+    /** `requestedRatio * windowTokens` — token point asked for; null with no window. */
+    readonly requestedTokens: number | null;
+    /** Measured ratio of the first `observed` row after this dispatch. */
+    readonly observedRatio: number | null;
+    readonly observedTokens: number | null;
+    /**
+     * `observedTokens - requestedTokens`. Negative = the harness compacted
+     * BEFORE the point peaks-loop asked for (which is the harness's own
+     * trigger firing early). Null while unmeasured.
+     */
+    readonly driftTokens: number | null;
+    readonly measured: boolean;
+}
+export interface WindowCalibration {
+    readonly pairs: ReadonlyArray<WindowCalibrationPair>;
+    /** Dispatches with no following measurement yet. */
+    readonly unmeasured: number;
+    /** The window in force on the most recent dispatch, for a one-line read. */
+    readonly lastWindowTokens: number | null;
+}
+/**
+ * Pair each dispatched compact with the measurement that followed it. Pure;
+ * tolerates a file written by an earlier release (no `windowTokens`, no
+ * `kind`) — those rows produce a pair with a null window rather than an
+ * error, because the history file is append-only and never rewritten.
+ */
+export declare function computeWindowCalibration(events: ReadonlyArray<CompactHistoryEvent>): WindowCalibration;
 export type CompactHistoryReadResult = {
     readonly kind: 'file-missing';
     readonly path: string;

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

@@ -12,6 +12,55 @@
 // read.
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+/**
+ * Pair each dispatched compact with the measurement that followed it. Pure;
+ * tolerates a file written by an earlier release (no `windowTokens`, no
+ * `kind`) — those rows produce a pair with a null window rather than an
+ * error, because the history file is append-only and never rewritten.
+ */
+export function computeWindowCalibration(events) {
+    const pairs = [];
+    for (const event of events) {
+        const kind = event.kind ?? 'dispatch';
+        if (kind === 'observed') {
+            // Attach to the most recent dispatch still waiting for a measurement.
+            for (let i = pairs.length - 1; i >= 0; i -= 1) {
+                const candidate = pairs[i];
+                if (candidate.observedRatio !== null || typeof event.afterRatio !== 'number')
+                    continue;
+                const observedTokens = candidate.windowTokens === null ? null : event.afterRatio * candidate.windowTokens;
+                pairs[i] = {
+                    ...candidate,
+                    observedRatio: event.afterRatio,
+                    observedTokens,
+                    driftTokens: observedTokens === null || candidate.requestedTokens === null
+                        ? null
+                        : observedTokens - candidate.requestedTokens,
+                    measured: true
+                };
+                break;
+            }
+            continue;
+        }
+        const windowTokens = typeof event.windowTokens === 'number' ? event.windowTokens : null;
+        pairs.push({
+            dispatchedAt: event.ts,
+            windowTokens,
+            windowSource: event.windowSource ?? null,
+            requestedRatio: event.beforeRatio,
+            requestedTokens: windowTokens === null ? null : event.beforeRatio * windowTokens,
+            observedRatio: null,
+            observedTokens: null,
+            driftTokens: null,
+            measured: false
+        });
+    }
+    return {
+        pairs,
+        unmeasured: pairs.filter((p) => !p.measured).length,
+        lastWindowTokens: pairs.length === 0 ? null : pairs[pairs.length - 1].windowTokens
+    };
+}
 export function readCompactHistory(input) {
     const path = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'compact-history.jsonl');
     if (!existsSync(path)) {

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 };
 }

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

@@ -15,7 +15,12 @@ export function planRollback() {
 export function executeRollback(opts) {
     const plan = planRollback();
     if (!plan.available) {
-        throw new Error('NO_BACKUP: ~/.peaks/config.json.1.x.bak not found');
+        // rid 2026-09-13-two-decisions ①: a machine that never migrated has no
+        // `.bak`, and that is its normal state — `--apply` on such a machine is
+        // "nothing to roll back", not a failure. Returned instead of thrown so the
+        // exit status and the `available` key agree on every path; see
+        // `config-restore.ts` for the full rationale and the accepted cost.
+        return { ...plan, applied: false };
     }
     if (!opts.apply) {
         return { ...plan, applied: false };

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

@@ -51,6 +51,58 @@ export declare class InvalidProjectRootError extends Error {
     constructor(reason: 'empty' | 'nul-byte' | 'non-existent' | 'non-canonical', input: string);
 }
 export declare function resolveCanonicalProjectRootStrict(startPath: string): string;
+/**
+ * True when `projectRoot` IS the user's home directory itself.
+ *
+ * Exact match, NOT `isInsidePath`: `~/my-project` is an ordinary project and
+ * must keep working — the guard exists for the one directory that is never a
+ * project.
+ *
+ * `projectRootsMatch` rather than `===` because the two strings reach this
+ * function from different sources: a `--project .` argument arrives in the
+ * caller's spelling while `homedir()` yields the OS form (`C:\Users\x` vs
+ * `C:/Users/x`, and differing case on win32/darwin).
+ *
+ * This is the ONE definition of "the user's home" in the codebase; the
+ * harness-window writer's own guard delegates here so the two cannot drift.
+ */
+export declare function isUserHomeProjectRoot(projectRoot: string): boolean;
+/**
+ * Thrown by `assertWritableProjectRoot` / `resolveWritableProjectRoot` when a
+ * write would land in the user's home directory. Distinct from
+ * `InvalidProjectRootError` (which is about a malformed/absent path): this path
+ * is perfectly valid — it is just not a project.
+ */
+export declare class UnsafeProjectRootError extends Error {
+    readonly projectRoot: string;
+    constructor(projectRoot: string);
+}
+/**
+ * Refuse a project root that IS the user's home directory.
+ *
+ * The hazard this closes: a fresh terminal starts in `$HOME`, and
+ * `peaks workspace init --project .` there resolved to `$HOME` (via
+ * `resolveCanonicalProjectRoot`'s fail-open fallback, which returns the start
+ * path when it can find no project marker) and then materialized a whole
+ * project tree INTO the user's home — `.claude/settings.local.json` above all,
+ * which is a live config file shared with every other project on the machine.
+ *
+ * Deliberately NOT enforced inside `resolveCanonicalProjectRoot`. That helper
+ * is called from 85 sites across 32 files, most of them READS (`peaks status`,
+ * `peaks dashboard`, `peaks memory`, the observability commands). Refusing
+ * there would break every one of them the moment a user runs a read command
+ * from their home directory, and its fail-open contract is documented and
+ * depended on. The hazard is a WRITE to `$HOME/.claude/`, so the guard belongs
+ * on write paths — this function, plus `resolveWritableProjectRoot` so a
+ * writer only has to make one call.
+ */
+export declare function assertWritableProjectRoot(projectRoot: string): void;
+/**
+ * `resolveCanonicalProjectRoot` for a path that is about to be WRITTEN to:
+ * same git-root-then-heuristic promotion, plus the home-directory refusal.
+ * Read paths keep using the fail-open helper.
+ */
+export declare function resolveWritableProjectRoot(startPath: string): string;
 export declare function getProjectConfigPath(projectRoot: string | null): string | null;
 export declare function getProjectBootstrapConfigPath(projectRoot: string): string;
 export declare function validateProjectBootstrapConfigPathForWrite(projectRoot: string, configPath: string): void;