peaks-loop 4.0.45 → 4.0.47

package/dist/services/context/harness-window-config.js

@@ -0,0 +1,607 @@
+/**
+ * Harness auto-compact window ownership
+ * (slice 2026-09-13-auto-compact-trigger-ownership, rid
+ * 2026-09-13-auto-compact-trigger-ownership).
+ *
+ * The goal (user's words): *when* to trigger auto-compact must be
+ * peaks-loop's decision; *how* to compact stays the harness's capability.
+ *
+ * That only holds if the two sides agree on ONE number. Before this slice
+ * they each resolved a window independently: Claude Code used the window it
+ * knows for the model, while peaks-loop divided by `resolveContextWindow()`
+ * (env → config → model-name heuristic → 200_000 default). A 1M-window model
+ * whose id the heuristic does not recognise made peaks-loop's "95%" land at
+ * 190K while the harness waited for ~967K — a 5× early trigger, and (before
+ * T3) a deadlock, because nothing could lower the ratio.
+ *
+ * This module owns the OTHER half of the fix: the harness itself accepts a
+ * window override (`IdeCompactProfile.autoCompactWindowEnvVar`, declared per
+ * adapter — no IDE names here), so peaks-loop writes the very number it
+ * computes the ratio against into the harness's own machine-local settings
+ * file. Reader and writer then reference one artifact instead of two
+ * resolutions that must "remember" to agree.
+ *
+ * Vendor neutrality: this module knows about a JSON file with an `env` block
+ * and nothing else. The settings path and the env-var name are BOTH passed
+ * in by the caller, resolved from the IDE adapter's declarations. There is
+ * no IDE id, no `.claude` literal, and no registry import in this file.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { isUserHomeProjectRoot } from '../config/config-safety.js';
+/**
+ * Peaks-owned opt-out flag, read from the SAME machine-local `env` block the
+ * window key is written to.
+ *
+ * Why it exists: `resetHarnessWindow` must be a real rollback. Without a
+ * durable opt-out, the next context probe would simply write the key back
+ * and the user's "remove it" would last until the next tool call — a
+ * rollback in name only. Absent (or any value other than `off`) = sync is
+ * enabled, which keeps every project installed by an earlier release
+ * unchanged.
+ */
+export const HARNESS_WINDOW_SYNC_OPTOUT_KEY = 'PEAKS_HARNESS_WINDOW_SYNC';
+/** The one value that disables the sync. */
+export const HARNESS_WINDOW_SYNC_OPTOUT_VALUE = 'off';
+/**
+ * Provenance marker: the window value peaks-loop ITSELF last wrote, recorded
+ * in the same `env` block as the window key.
+ *
+ * Why it must exist. The window key is a SHARED artifact — the harness reads
+ * it, the user may set it by hand (it is a documented Claude Code variable),
+ * and peaks-loop writes it. Two rules collide on it:
+ *
+ *   - the ratio peaks-loop reports must divide by the key (the single-source
+ *     rule), so the key outranks the model heuristic; and
+ *   - a first-time mis-resolution must not become PERMANENT.
+ *
+ * The second rule needs the late 1M rescue to be able to overrule the key when
+ * the observed context proves the key too small. Applied to a value a HUMAN
+ * pinned, that same rescue would silently destroy an explicit setting — the
+ * user asks for an early compact, a long session outgrows the pin, and
+ * peaks-loop rewrites the file to 1M, permanently. Applied to peaks-loop's own
+ * earlier output it is simply self-correction.
+ *
+ * This marker is what tells the two apart: it records what peaks-loop wrote,
+ * so a mismatch means the human has taken the key over and the rescue must
+ * stand down. It travels in the same write as the value it describes, so the
+ * two can never disagree about which write they belong to.
+ */
+export const HARNESS_WINDOW_WRITTEN_KEY = 'PEAKS_HARNESS_WINDOW_WRITTEN';
+/**
+ * The harness's OWN accepted band for its auto-compact window (E1, rid
+ * 2026-09-13-defects-e).
+ *
+ * THE BAND IS A PROPERTY OF THE KEY, NOT OF peaks-loop. `autoCompactWindow` —
+ * and the `CLAUDE_CODE_AUTO_COMPACT_WINDOW` env var that shadows it — is
+ * documented as "how full the context window gets before Claude Code compacts
+ * automatically, in tokens from 100000 to 1000000", and a value outside that
+ * band is not the window the harness compacts on: below the minimum the value
+ * is ignored, above the maximum it is reduced to the model's own context size
+ * (`Math.min(native, override)`; no Claude model's window exceeds 1000000, so
+ * above the maximum the reduction is certain).
+ *
+ * Either way the outcome is the failure this whole module exists to prevent:
+ * peaks-loop divides its ratio by a number the harness is not using, so
+ * "85%" names a point the harness will never fire at. A positive integer is
+ * therefore NOT sufficient — the band is part of what the value means.
+ *
+ * Clamping instead was rejected. A clamped write would put a DIFFERENT number
+ * in the file from the one the probe just divided by, restoring the
+ * two-resolutions drift inside the single write that is supposed to delete it.
+ * Refusing keeps the disagreement in one place, reportable, and reported.
+ */
+export const HARNESS_WINDOW_MIN_TOKENS = 100_000;
+/** See `HARNESS_WINDOW_MIN_TOKENS`. */
+export const HARNESS_WINDOW_MAX_TOKENS = 1_000_000;
+/**
+ * True when `tokens` is a window the harness will actually compact on.
+ * `null` (absent / unparseable) is NOT in band — there is no window at all.
+ */
+export function isHarnessWindowInRange(tokens) {
+    return tokens !== null && tokens >= HARNESS_WINDOW_MIN_TOKENS && tokens <= HARNESS_WINDOW_MAX_TOKENS;
+}
+/**
+ * The BAND SENTENCE, in one place: both the write refusal and the read
+ * suppression have to say the same thing about the same numbers, and two
+ * copies would eventually disagree about the band.
+ */
+function harnessWindowBand() {
+    return `${HARNESS_WINDOW_MIN_TOKENS}..${HARNESS_WINDOW_MAX_TOKENS}`;
+}
+/**
+ * The ONE wording of "what the harness-window sync just did", for both
+ * commands that sync (`peaks code context-now`, `peaks code auto-compact`).
+ *
+ * Why it lives here rather than inline at each call site: peaks-loop rewrites
+ * a file in the user's own harness settings on every probe, and the user
+ * accepted that write on one condition — 要告知 (tell me). Two copies of the
+ * sentence would mean a future edit tells half the users. This is the only
+ * definition; the CLI renders whatever it returns.
+ *
+ * The `written` branch is the load-bearing one: it names the key, the value,
+ * the file, what the value was before, and the exact rollback command, because
+ * the harness itself reports an override only through `/autocompact` — if
+ * peaks-loop does not say it here, nobody says it.
+ *
+ * The `skipped` branch is the one that is easy to get wrong, and did: it used
+ * to end at the reason token (`Harness window not managed (not-peaks-owned).`),
+ * which is true and tells the reader nothing. A refusal can be the exact
+ * moment the two sides came apart — the ratio divided by one number while the
+ * file pins another — so it is composed from the reason, the two numbers when
+ * they disagree, and the raw value when the file's value is not a number at
+ * all. See `harnessWindowConflictClause` / `unreadableWindowValueClause`.
+ */
+export function describeHarnessWindowSync(result) {
+    if (result === null) {
+        return 'The active IDE adapter declares no auto-compact window key; this ratio cannot be tied to the harness trigger.';
+    }
+    if (result.action === 'written') {
+        return `WROTE ${result.key}=${String(result.tokens)} to ${result.settingsPath} (was ${result.previousTokens === null ? 'unset' : String(result.previousTokens)}) so the harness compacts at the same point this ratio measures. Rollback: \`peaks compact harness-window --reset\`.`;
+    }
+    if (result.action === 'skipped') {
+        // A refused write is NOT automatically a non-event. The two clauses below
+        // are the whole point of refusing to stop at the reason token: each names a
+        // concrete NUMBER the user can act on, because "not managed" alone left the
+        // reader unable to tell whether the two sides still agreed.
+        return `${skippedHarnessWindowClause(result)}${harnessWindowConflictClause(result)}${unreadableWindowValueClause(result)}`;
+    }
+    // `unchanged` — the file already holds exactly the window this probe divided
+    // by, so there is no disagreement to report. What can still be hidden is
+    // OWNERSHIP, and it decides what happens when the session outgrows the value.
+    // A user upgrading from a release that wrote the key before the provenance
+    // marker existed lands here (that is this repository's own state): the value
+    // is in force, peaks-loop computes against it, and nothing anywhere said it
+    // had become frozen — so "already in force" alone is not a full notice.
+    if (!result.peakWritten) {
+        return `Harness window ${result.key}=${String(result.tokens)} already in force, but it is NOT peaks-loop's own write: peaks-loop divides this ratio by it and will never raise it, so a session that outgrows ${String(result.tokens)} saturates the ratio at 1.0 instead of widening the window. To hand the key back to peaks-loop: \`peaks compact harness-window --reset\` (removes it), then \`peaks compact harness-window --reenable\` (the next probe fills it).`;
+    }
+    return `Harness window ${result.key} already in force; peaks-loop computes this ratio against it.`;
+}
+/**
+ * The same disagreement as `harnessWindowConflictClause`, reduced to one line
+ * for the `warnings` channel — the machine-readable half of 要告知, so a
+ * consumer reading the JSON envelope (or a human reading stderr) sees it even
+ * if it never renders `nextActions`. Returns `null` when there is nothing to
+ * warn about, which is the ordinary case.
+ */
+export function harnessWindowSyncWarning(result) {
+    if (result === null || result.action !== 'skipped')
+        return null;
+    // E1: the resolved window is not one the harness accepts, so this ratio's
+    // denominator is un-anchored no matter what the file holds. Reported FIRST —
+    // it is the more fundamental disagreement, and the two clauses below would
+    // read as "a different number" rather than "a number the harness cannot use".
+    if (result.reason === 'out-of-harness-range') {
+        return `harness window out of range: this probe divided by ${String(result.requestedTokens)} tokens, outside the ${harnessWindowBand()} band the harness accepts — the ratio does not describe the harness's own trigger`;
+    }
+    if (result.requestedTokens !== null &&
+        result.previousTokens !== null &&
+        result.requestedTokens !== result.previousTokens) {
+        return `harness window conflict: this probe divided by ${result.requestedTokens} tokens but ${result.settingsPath} pins ${result.previousTokens} — the ratio does not describe the harness's own trigger`;
+    }
+    if (result.previousTokens === null && result.previousRawValue !== undefined) {
+        return `harness window unreadable: ${result.settingsPath} carries ${JSON.stringify(result.previousRawValue)}, which is not a plain token count`;
+    }
+    return null;
+}
+/**
+ * WHY nothing was written, in words — one clause per `reason`.
+ *
+ * Every reason has its own sentence rather than falling through to
+ * `(${reason})`: the bare token was what the user actually saw for the two
+ * most common refusals, and it names no value, no file, and no next step.
+ * The trailing clause is unreachable for the reasons this module produces
+ * today; it exists so a future reason cannot silently degrade to a token.
+ */
+function skippedHarnessWindowClause(result) {
+    switch (result.reason) {
+        case 'opted-out':
+            return 'Harness window not managed (opted-out) — re-enable with `peaks compact harness-window --reenable`.';
+        case 'unsafe-project-root':
+            return `Harness window not managed: ${result.settingsPath} is the user's own home settings, not a project's, so peaks-loop left it alone. Re-run from inside a project (or point at one) and the window lands there instead.`;
+        case 'no-window-resolved':
+            return 'Harness window not managed: this probe measured a percentage and carried no token window, so there was no number to write — peaks-loop does not invent a window the adapter did not resolve.';
+        case 'out-of-harness-range':
+            return `Harness window not managed: the window this probe resolved (${String(result.requestedTokens)}) is outside the ${harnessWindowBand()} band the harness accepts, so writing it would put a number in ${result.settingsPath} that the harness does not compact on.`;
+        case 'unreadable-settings':
+            return `Harness window not managed: ${result.settingsPath} is not a JSON object peaks-loop can safely edit, so it was left exactly as found.`;
+        case 'not-peaks-owned':
+            return `Harness window not managed: ${result.settingsPath} already carries a window that peaks-loop did not write, and peaks-loop never overwrites (or claims) a value it did not write.`;
+        default:
+            return `Harness window not managed (${String(result.reason)}).`;
+    }
+}
+/**
+ * THE DISAGREEMENT SENTENCE — the one the user cannot get anywhere else.
+ *
+ * peaks-loop divided this probe's ratio by `requestedTokens`, while the
+ * harness's own settings file pins `previousTokens`. Neither side is wrong on
+ * its own, which is exactly why it went unnoticed: the file wins for the ratio
+ * (T1's single-source rule), the write that would have re-unified them was
+ * refused (B1's provenance guard), and the result was a percentage computed
+ * against a window the harness is not going to fire on. The harness reports an
+ * override only through its own `/autocompact`, so if peaks-loop does not name
+ * the two numbers here, nobody does.
+ *
+ * Both numbers and the file are named, and all three ways out are given,
+ * because this notice is the whole remedy for a state peaks-loop deliberately
+ * refuses to fix by writing.
+ */
+function harnessWindowConflictClause(result) {
+    const requested = result.requestedTokens;
+    const pinned = result.previousTokens;
+    if (result.action !== 'skipped' || requested === null || pinned === null || requested === pinned)
+        return '';
+    return ` CONFLICT: peaks-loop divided this ratio by ${requested} tokens, but ${result.settingsPath} pins ${pinned} — and the harness compacts on ITS own number, so this ratio does not describe when it fires. Nothing was written. Choose one: (1) make peaks-loop's number match the file (unset PEAKS_CONTEXT_WINDOW_TOKENS, or change \`context.windowTokens\`), (2) keep the file as your own setting and read this ratio as a share of ${requested}, or (3) \`peaks compact harness-window --reset\` to remove the key and hand it back to peaks-loop.`;
+}
+/**
+ * The OTHER way two numbers can fail to line up: the file's value is not a
+ * number at all (`500k`, a hand-typed typo).
+ *
+ * `previousTokens` is `null` here — indistinguishable, in the parsed result,
+ * from an absent key — so this clause is gated on the RAW value. The
+ * disagreement is stated but never "aligned": peaks-loop will not overwrite a
+ * value it did not write, and the value is unusable, so the only honest output
+ * is to name it and hand the user the two ways out. Silent here would be the
+ * worst option of all, because the caller has already fallen back to a
+ * different window and the disk keeps claiming `500k` on every probe after it.
+ */
+function unreadableWindowValueClause(result) {
+    if (result.action !== 'skipped' || result.previousTokens !== null || result.previousRawValue === undefined)
+        return '';
+    const raw = JSON.stringify(result.previousRawValue);
+    return ` The value in ${result.settingsPath} is ${raw}, which is not a plain token count: peaks-loop cannot read a window from it, so it resolved this ratio against its own fallback while the file keeps saying ${raw}. peaks-loop cannot align the two without overwriting a value it did not write — set the value to a plain token count, or run \`peaks compact harness-window --reset\` to remove the key and let the next probe write peaks-loop's number.`;
+}
+/**
+ * Parse a candidate window value. Positive finite integers only — a number,
+ * or a numeric string (the env block is JSON, so the value on disk is always
+ * a string there). The harness's own documentation is explicit that the
+ * variable "accepts only the plain token count" and NOT a `850k` suffix, so
+ * anything non-integral is refused here rather than written and silently
+ * ignored downstream.
+ */
+export function parseHarnessWindowTokens(raw) {
+    if (typeof raw !== 'number' && typeof raw !== 'string')
+        return null;
+    if (typeof raw === 'string' && raw.trim().length === 0)
+        return null;
+    const parsed = typeof raw === 'number' ? raw : Number(raw.trim());
+    return Number.isFinite(parsed) && Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+/**
+ * Read the settings file as a JSON object. Returns null when the file is
+ * absent, unparseable, or not an object — the caller treats that as "cannot
+ * manage" rather than throwing, because a corrupt local settings file must
+ * never break a context probe.
+ */
+function readSettingsObject(settingsPath) {
+    if (!existsSync(settingsPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when the file is absent (editable) or a parseable JSON object. */
+function isEditable(settingsPath) {
+    if (!existsSync(settingsPath))
+        return true;
+    return readSettingsObject(settingsPath) !== null;
+}
+/**
+ * True when `candidate` is the user's home directory itself.
+ *
+ * Delegates to the shared `isUserHomeProjectRoot` — this guard used to carry
+ * its own copy of the predicate, and `resolveWritableProjectRoot` /
+ * `assertWritableProjectRoot` now need the same answer on every write path. Two
+ * definitions of "the user's home" is one too many: they are compared against
+ * the same `homedir()` under the same case-folding rules or they disagree about
+ * some path eventually. Tolerating a probe of a *subdirectory* of `$HOME` is
+ * deliberate — `~/proj` is an ordinary project — so this is an exact match, not
+ * `isInsidePath`.
+ */
+function isUserHome(candidate) {
+    return isUserHomeProjectRoot(candidate);
+}
+function envString(settings, key) {
+    const env = settings?.env;
+    if (typeof env !== 'object' || env === null || Array.isArray(env))
+        return undefined;
+    return env[key];
+}
+/**
+ * Read the window the harness is currently using for auto-compact.
+ *
+ * Order: the process env FIRST (that is the value the RUNNING session
+ * captured at start-up, so it is what the harness is actually compacting
+ * against right now), then the settings file (what the next session will
+ * read). When the two disagree, the file is what the sync updates — the
+ * process env cannot be changed from inside a running session.
+ */
+export function readHarnessWindow(input) {
+    const settings = readSettingsObject(input.location.settingsPath);
+    const optedOut = envString(settings, HARNESS_WINDOW_SYNC_OPTOUT_KEY) === HARNESS_WINDOW_SYNC_OPTOUT_VALUE;
+    // Provenance is a property of the KEY — "is peaks-loop the current writer of
+    // this key?" — so it is decided by the FILE's value against the marker,
+    // never by whichever copy happens to be in force.
+    //
+    // That distinction is load-bearing. A running session freezes the process
+    // env at start-up, so after peaks-loop refreshes the file the env still
+    // carries the PREVIOUS value. Comparing the marker against the in-force copy
+    // would then report "a human set this" for peaks-loop's own superseded
+    // number, switch the late 1M rescue off, and re-pin the ratio at 1.0 on the
+    // very next probe — the self-lock, restored through the back door. Against
+    // the file value the answer is stable: still ours, so still correctable.
+    const marker = parseHarnessWindowTokens(envString(settings, HARNESS_WINDOW_WRITTEN_KEY));
+    const fileRaw = envString(settings, input.location.envVar);
+    const fileTokens = parseHarnessWindowTokens(fileRaw);
+    const peakWritten = fileTokens !== null && marker === fileTokens;
+    const fromEnv = input.env?.[input.location.envVar];
+    if (fromEnv !== undefined) {
+        return {
+            tokens: parseHarnessWindowTokens(fromEnv), raw: fromEnv, source: 'process-env',
+            optedOut, peakWritten, fileTokens, fileRaw
+        };
+    }
+    if (fileRaw !== undefined) {
+        return { tokens: fileTokens, raw: fileRaw, source: 'settings-file', optedOut, peakWritten, fileTokens, fileRaw };
+    }
+    return {
+        tokens: null, raw: undefined, source: null, optedOut, peakWritten: false,
+        fileTokens: null, fileRaw: undefined
+    };
+}
+/**
+ * Write `tokens` as the harness's auto-compact window. Idempotent: a re-run
+ * with the same value performs no write at all, so repeated calls (the sync
+ * runs on every context probe) cannot churn the file or duplicate the entry.
+ *
+ * Everything else in the file is preserved verbatim — the caller's own `env`
+ * entries, every `hooks` entry, and any unknown top-level key. This is the
+ * same read-modify-write discipline `auto-compact-hook-install.ts` already
+ * applies to this file; there are now two writers, and both must leave the
+ * other's rows alone.
+ */
+export function syncHarnessWindow(input) {
+    const settingsPath = input.location.settingsPath;
+    const current = readHarnessWindow({ location: input.location, env: input.env });
+    const fileSettings = readSettingsObject(settingsPath);
+    const fileRaw = envString(fileSettings, input.location.envVar);
+    const fileTokens = parseHarnessWindowTokens(fileRaw);
+    // Every branch spreads this, so `requestedTokens` and `previousRawValue`
+    // travel with the outcome rather than being re-derived by each consumer.
+    const base = {
+        settingsPath,
+        key: input.location.envVar,
+        previousTokens: fileTokens,
+        previousRawValue: fileRaw,
+        requestedTokens: input.tokens,
+        peakWritten: current.peakWritten
+    };
+    if (current.optedOut) {
+        return { ...base, action: 'skipped', reason: 'opted-out', tokens: current.tokens };
+    }
+    // The H1 guard: never target the user's own home directory. See
+    // `HarnessWindowLocation.projectRoot` for the trigger (`--project .` from a
+    // fresh terminal, whose cwd is `$HOME`). Refused here rather than by
+    // narrowing the shared project-root resolver: `findProjectRoot` deliberately
+    // stops below `$HOME` and `resolveCanonicalProjectRoot` is called from every
+    // command in the CLI, so a change there would move behaviour for all of them
+    // to close one writer's hazard. The check is exact-home only — `~/my-project`
+    // is a perfectly good project and is still written.
+    if (input.location.projectRoot !== undefined && isUserHome(input.location.projectRoot)) {
+        return { ...base, action: 'skipped', reason: 'unsafe-project-root', tokens: current.tokens };
+    }
+    if (input.tokens === null) {
+        return { ...base, action: 'skipped', reason: 'no-window-resolved', tokens: current.tokens };
+    }
+    // THE E1 BAND CHECK — before the idempotence and ownership gates, so an
+    // out-of-band request is refused whatever the file happens to hold. Writing it
+    // would be worse than useless: the harness ignores or caps it, so the file
+    // would carry a number that LOOKS managed while the ratio divides by a number
+    // the harness is not using. See `HARNESS_WINDOW_MIN_TOKENS`.
+    if (!isHarnessWindowInRange(input.tokens)) {
+        return { ...base, action: 'skipped', reason: 'out-of-harness-range', tokens: current.tokens };
+    }
+    if (!isEditable(settingsPath)) {
+        return { ...base, action: 'skipped', reason: 'unreadable-settings', tokens: current.tokens };
+    }
+    // Idempotence is a property of the FILE, not of the process env. A running
+    // session keeps the value it captured at start-up, so comparing against the
+    // read (env first) would report "changed" on every probe of that session and
+    // rewrite a byte-identical file each time.
+    if (fileTokens === input.tokens) {
+        return { ...base, action: 'unchanged', tokens: input.tokens };
+    }
+    // THE B1 GUARD. peaks-loop may update a value it wrote itself, and it may
+    // FILL an empty slot — but it must never overwrite a value it did not write.
+    //
+    // Round 2 decided this gate by comparing the file against the resolved
+    // window, and the resolved window is read env-first. So provenance gated the
+    // 1M *bump* but never the *write*: a human hand-edited the key from the
+    // 200000 peaks-loop wrote to 150000, a stale process env still said 200000,
+    // and the next probe reverted the human's edit and re-armed the marker — the
+    // marker then authorising the very rescue that raised the human's key to
+    // 1000000. No human was even needed: another session's stale env downgraded a
+    // 1M file the same way. Comparing the file against its own marker is the only
+    // question that has an answer stable across a frozen env.
+    const peakOwned = fileRaw === undefined || current.peakWritten;
+    if (!peakOwned) {
+        return { ...base, action: 'skipped', reason: 'not-peaks-owned', tokens: current.tokens };
+    }
+    const settings = fileSettings ?? {};
+    const env = typeof settings.env === 'object' && settings.env !== null && !Array.isArray(settings.env)
+        ? settings.env
+        : {};
+    const next = {
+        ...settings,
+        // A JSON env block is string-valued. `String(tokens)` is the plain token
+        // count the harness documents — never a `500k`-style suffix. The provenance
+        // marker is written in the SAME object, so value and provenance can never
+        // be split across two writes (see `HARNESS_WINDOW_WRITTEN_KEY`).
+        env: {
+            ...env,
+            [input.location.envVar]: String(input.tokens),
+            [HARNESS_WINDOW_WRITTEN_KEY]: String(input.tokens)
+        }
+    };
+    const dir = dirname(settingsPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    // 2-space JSON + trailing newline matches the other writer of this file
+    // (`.claude/settings.local.json`), so a diff after a sync stays minimal.
+    writeFileSync(settingsPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    // `peakWritten` describes the file AFTER this call, and this call is what
+    // armed the marker — the pre-write read necessarily said `false`, because a
+    // write only happens when the file did not already hold the wanted value
+    // under a matching marker.
+    return { ...base, action: 'written', tokens: input.tokens, peakWritten: true };
+}
+/**
+ * Rollback: remove the window key and record the opt-out so the next sync
+ * does not put it straight back. Both edits land in the same
+ * read-modify-write, so there is no window in which the key is gone but the
+ * opt-out is not yet on disk.
+ *
+ * Idempotent: a second call reports `action: 'absent'` and rewrites nothing
+ * unless the opt-out row is missing.
+ */
+export function resetHarnessWindow(input) {
+    const settingsPath = input.location.settingsPath;
+    const settings = readSettingsObject(settingsPath);
+    const previousTokens = parseHarnessWindowTokens(envString(settings, input.location.envVar));
+    const markerPresent = envString(settings, HARNESS_WINDOW_WRITTEN_KEY) !== undefined;
+    if (settings === null || !isEditable(settingsPath)) {
+        // Nothing to remove and nothing we can safely edit.
+        return { settingsPath, action: 'absent', previousTokens };
+    }
+    // NOTHING OF PEAKS-LOOP'S TO REMOVE → WRITE NOTHING.
+    //
+    // The old form short-circuited only when the opt-out was ALREADY recorded
+    // (`... && priorOptOut`), so `--reset` on a file peaks-loop had never touched
+    // still wrote `PEAKS_HARNESS_WINDOW_SYNC: "off"` into it. When that file is
+    // the user's PERSONAL `$HOME/.claude/settings.local.json` — a fresh terminal
+    // plus `--project .`, i.e. the ordinary case — the rollback inserted a
+    // peaks-loop row into a file with no peaks content at all: litter in the
+    // user's own settings, written by the command they ran to REMOVE something.
+    //
+    // A no-op is the honest outcome. There is no window to remove and no
+    // provenance marker to disarm, so there is nothing to make durable; the
+    // caller reports `absent` and says that nothing was written. A key the user
+    // deletes by hand but whose marker survives still falls through below, so the
+    // stale marker is still cleaned up — that is why the test is `markerPresent`
+    // and not `!priorOptOut`.
+    if (previousTokens === null && !markerPresent) {
+        return { settingsPath, action: 'absent', previousTokens };
+    }
+    const env = typeof settings.env === 'object' && settings.env !== null && !Array.isArray(settings.env)
+        ? { ...settings.env }
+        : {};
+    delete env[input.location.envVar];
+    // The provenance marker goes with the value it describes — a marker left
+    // behind would claim ownership of whatever the user writes next.
+    delete env[HARNESS_WINDOW_WRITTEN_KEY];
+    env[HARNESS_WINDOW_SYNC_OPTOUT_KEY] = HARNESS_WINDOW_SYNC_OPTOUT_VALUE;
+    const next = { ...settings, env };
+    writeFileSync(settingsPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    return { settingsPath, action: 'removed', previousTokens };
+}
+/**
+ * Record the opt-out WITHOUT removing anything: "stop managing this key",
+ * expressible at any moment — including before peaks-loop has ever written it.
+ *
+ * WHY THIS IS A SEPARATE ENTRY POINT AND NOT A FALLBACK OF `resetHarnessWindow`
+ *
+ * "Remove what is there" and "never write it again" are two different
+ * intentions. `--reset` on a file holding no peaks row is deliberately a no-op
+ * (see the file-litter note in `resetHarnessWindow`), so a user whose project
+ * peaks-loop has never touched had NO command for the second intention at all:
+ * they had to wait for a probe to write the key and then remove it — the order
+ * backwards. Folding the opt-out into `--reset` would fix that by making one
+ * verb mean "delete" or "don't write", depending on whether the file happened
+ * to hold a row, which is a verb whose effect the user cannot predict from its
+ * name. Two verbs, two intentions, each predictable.
+ *
+ * WHAT IT DOES NOT DO
+ *   - it does not touch the window key: a hand-set value stays exactly as it
+ *     was (peaks-loop would not have overwritten it anyway — see the B1 guard);
+ *   - it does not write a provenance marker, so it claims no ownership of a
+ *     value it did not write.
+ * The next probe reports `skipped / opted-out` and writes nothing.
+ *
+ * THE H1 HOME GUARD APPLIES HERE TOO (E4, rid 2026-09-13-defects-e).
+ *
+ * This function used to exempt itself, on the argument that `--disable` is an
+ * explicit instruction and "the location's own file is the only place the
+ * opt-out can be recorded for it to mean anything". The first half is true and
+ * was never the problem; the second half does not hold at `$HOME`:
+ *
+ *   - the location is NOT usually explicit. `--project` is optional, and a
+ *     fresh terminal starts in `$HOME`, so the ordinary invocation resolves the
+ *     root to the user's home directory without them naming it — the very
+ *     trigger the H1 guard was written for;
+ *   - the opt-out has NOTHING to mean there. `syncHarnessWindow` already
+ *     refuses to write the window at that root (`unsafe-project-root`), so the
+ *     only thing a recorded opt-out changes is which sentence the refusal uses.
+ *     Nothing is made expressible; a visible refusal is traded for a quieter one;
+ *   - what IS added is a durable peaks-loop row in `~/.claude/settings.local.json`
+ *     — a file outside every repo. `--reset`'s exemption does not transfer to
+ *     this verb: `--reset` REMOVES (and is a no-op when there is nothing of
+ *     peaks-loop's to remove), while `--disable` only ever ADDS.
+ *
+ * So the guard fires here exactly as it does in `syncHarnessWindow`: the same
+ * exact-home comparison, before any `mkdir` and before any read-modify-write.
+ * `~/my-project` is unaffected, and a user who really does carry a stale
+ * peaks-loop window key in `$HOME` still has `--reset`, which is allowed there
+ * for the reason its own note gives.
+ *
+ * Idempotent: a second call reports `already-opted-out` and rewrites nothing.
+ */
+export function disableHarnessWindowSync(input) {
+    const settingsPath = input.location.settingsPath;
+    // Checked FIRST, before `isEditable` and before any directory is created:
+    // a refusal that has already mkdir'd `$HOME/.claude` is not a refusal.
+    if (input.location.projectRoot !== undefined && isUserHome(input.location.projectRoot)) {
+        return { settingsPath, action: 'refused-unsafe-project-root' };
+    }
+    const settings = readSettingsObject(settingsPath);
+    if (!isEditable(settingsPath)) {
+        return { settingsPath, action: 'unreadable-settings' };
+    }
+    const env = typeof settings?.env === 'object' && settings.env !== null && !Array.isArray(settings.env)
+        ? { ...settings.env }
+        : {};
+    if (env[HARNESS_WINDOW_SYNC_OPTOUT_KEY] === HARNESS_WINDOW_SYNC_OPTOUT_VALUE) {
+        return { settingsPath, action: 'already-opted-out' };
+    }
+    env[HARNESS_WINDOW_SYNC_OPTOUT_KEY] = HARNESS_WINDOW_SYNC_OPTOUT_VALUE;
+    const dir = dirname(settingsPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(settingsPath, `${JSON.stringify({ ...(settings ?? {}), env }, null, 2)}\n`, 'utf8');
+    return { settingsPath, action: 'disabled' };
+}
+/**
+ * Undo the opt-out (the companion of `resetHarnessWindow`) so peaks-loop
+ * resumes owning the harness window.
+ */
+export function reenableHarnessWindowSync(input) {
+    const settingsPath = input.location.settingsPath;
+    const settings = readSettingsObject(settingsPath);
+    if (settings === null)
+        return { settingsPath, action: 'absent' };
+    const env = typeof settings.env === 'object' && settings.env !== null && !Array.isArray(settings.env)
+        ? { ...settings.env }
+        : {};
+    if (env[HARNESS_WINDOW_SYNC_OPTOUT_KEY] === undefined)
+        return { settingsPath, action: 'absent' };
+    delete env[HARNESS_WINDOW_SYNC_OPTOUT_KEY];
+    writeFileSync(settingsPath, `${JSON.stringify({ ...settings, env }, null, 2)}\n`, 'utf8');
+    return { settingsPath, action: 'reenabled' };
+}

package/dist/services/context/main-session-monitor.d.ts

@@ -71,6 +71,33 @@ export interface InFlightBatchProbe {
     readonly hasInFlightBatch: boolean;
     readonly sharedChannelEntries: number;
 }
+/**
+ * Which compact pathway serves this IDE, read from the ADAPTER'S OWN
+ * declaration (`IdeCompactProfile.compactPathway`) rather than from the
+ * IDE's name.
+ *
+ * Slice 2026-09-12-auto-compact-vendor-neutrality: this decision used to
+ * be the inline `ide === 'claude-code' ? 'ide-native' : 'llm-self-compress'`
+ * — an IDE identity branch in a module that is otherwise pure, reading the
+ * IDE's NAME where the adapter registry holds the CAPABILITY. An IDE that
+ * registered `compactPathway: 'ide-native'` was still told to
+ * self-compress.
+ *
+ * Pure + synchronous: `tryGetAdapter` is a Map lookup with no IO, so this
+ * module stays IO-free (same seam discipline as the `env?` parameter).
+ * `tryGetAdapter` (not `getAdapter`) because the input is an `IdeKind`,
+ * which includes ids — `opencode` — with no registered adapter; throwing
+ * from a suggestion-formatting path would be a regression.
+ *
+ * Only `'ide-native'` is in-band. Every other declared pathway
+ * (`shell-exec`, `llm-self-compress`, `noop`) reports the
+ * always-available `'llm-self-compress'` fallback, because the trigger
+ * union can only carry those two values. That under-reports a `noop`
+ * adapter — which the dispatcher would refuse outright — and callers
+ * therefore MUST NOT read this as a promise that a compact will happen;
+ * the dispatcher's `ok` remains the authority.
+ */
+export declare function compactPathwayForIde(ide: IdeKind): 'ide-native' | 'llm-self-compress';
 export declare function pickMainSessionTrigger(opts: {
     promptSize: number;
     ide?: IdeKind | undefined;