peaks-loop 4.0.46 → 4.0.48

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

@@ -3,6 +3,7 @@ import { execFileSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { homedir } from 'node:os';
+import { projectRootsMatch } from '../../shared/path-utils.js';
 export function getUserConfigPath() {
     return resolve(homedir(), '.peaks', 'config.json');
 }
@@ -202,7 +203,8 @@ function resolveProjectRootFromGit(startPath) {
         const stdout = execFileSync('git', ['rev-parse', '--show-toplevel'], {
             cwd: startPath,
             encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore']
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true
         });
         const trimmed = stdout.trim();
         if (trimmed.length === 0)
@@ -227,6 +229,78 @@ function resolveProjectRootFromGit(startPath) {
         return rawRoot;
     }
 }
+/**
+ * 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 function isUserHomeProjectRoot(projectRoot) {
+    try {
+        return projectRootsMatch(projectRoot, homedir());
+    }
+    catch {
+        // A path that cannot be resolved is not a claim about the home directory.
+        return false;
+    }
+}
+/**
+ * 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 class UnsafeProjectRootError extends Error {
+    projectRoot;
+    constructor(projectRoot) {
+        super(`Refusing to write into the user's home directory: "${projectRoot}" is not a project root.`);
+        this.projectRoot = projectRoot;
+        this.name = 'UnsafeProjectRootError';
+    }
+}
+/**
+ * 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 function assertWritableProjectRoot(projectRoot) {
+    if (isUserHomeProjectRoot(projectRoot)) {
+        throw new UnsafeProjectRootError(projectRoot);
+    }
+}
+/**
+ * `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 function resolveWritableProjectRoot(startPath) {
+    const root = resolveCanonicalProjectRoot(startPath);
+    assertWritableProjectRoot(root);
+    return root;
+}
 export function getProjectConfigPath(projectRoot) {
     if (!projectRoot)
         return null;

package/dist/services/context/auto-compact-dispatcher.d.ts

@@ -1,37 +1,3 @@
-/**
- * AC-3 — IDE-aware compact dispatcher.
- *
- * Reads the active IDE's `IdeAdapter.compact` profile and dispatches
- * compact via the adapter-declared pathway. No hard-coded IDE names
- * — Claude Code is the MVP that fills `compact`; other adapters
- * register their own `compact` profile as L2-dogfood verifies
- * each IDE's actual compact surface.
- *
- * Pathway dispatch:
- *
- *   - `ide-native`     — peaks-loop writes the compact intent to
- *                        the IDE's hook file (per
- *                        `IdeSettingsLocation`). Used when the IDE
- *                        requires a registered hook rather than a
- *                        runtime command.
- *   - `llm-self-compress` — peaks-loop records the intent and
- *                        returns `ok: true` with `pathway` echoed.
- *                        The LLM does its own context summarization
- *                        on the next turn. Always available; least
- *                        precise fallback.
- *   - `noop`           — adapter explicitly opted out. peaks-loop
- *                        returns `ok: false` with `message: 'noop'`.
- *                        Used by legacy / unverified adapters.
- *
- * rid-031 (2026-07-28): `shell-exec` pathway is DEPRECATED. The
- * `case 'shell-exec':` branch remains reachable only to keep the
- * 2 currently-passing tests in `tests/unit/context/auto-compact-main-target.test.ts:58`
- * + `tests/unit/services/context/auto-compact-dispatcher-ide-native.test.ts:102`
- * passing (they assert `pathway: 'shell-exec'`). Real callers must
- * use `ide-native` (main session) or `llm-self-compress`. No host
- * CLI spawn occurs; the case logs a deprecation warning and returns
- * the same envelope shape.
- */
 import type { CompactDispatchResult } from './auto-compact-types.js';
 export type CompactTarget = 'main' | 'sub-agent';
 export interface DispatchIdeCompactInput {
@@ -48,14 +14,18 @@ export interface DispatchIdeCompactInput {
      * shells that spawn their own `peaks code auto-compact` flow pass
      * `'sub-agent'` to preserve the legacy shell-spawn behaviour.
      *
-     * Behaviour matrix (claude-code MVP):
+     * Behaviour matrix, keyed on the ADAPTER'S DECLARED pathway only
+     * — never on the adapter's name (slice
+     * 2026-09-12-auto-compact-vendor-neutrality):
      *   - target='main'     → llm-self-compress (write intent; main LLM
-     *                          fires `/compact` on its next turn).
+     *                          fires its compact command on its next turn).
      *   - target='sub-agent'→ shell-exec stub (DEPRECATED — no host
      *                          CLI spawn; returns envelope with
      *                          `pathway: 'shell-exec'` for legacy
      *                          contract only — see rid-031).
-     * Non-claude-code IDEs + target='main' return noop + warning.
+     * An adapter with no registered `compact` profile returns noop for
+     * BOTH targets; an adapter whose profile serves the main session is
+     * dispatched regardless of which IDE it is.
      */
     readonly target?: CompactTarget | undefined;
 }

package/dist/services/context/auto-compact-dispatcher.js

@@ -1,3 +1,48 @@
+/**
+ * AC-3 — IDE-aware compact dispatcher.
+ *
+ * Reads the active IDE's `IdeAdapter.compact` profile and dispatches
+ * compact via the adapter-declared pathway. No hard-coded IDE names
+ * — Claude Code is the MVP that fills `compact`; other adapters
+ * register their own `compact` profile as L2-dogfood verifies
+ * each IDE's actual compact surface.
+ *
+ * Pathway dispatch:
+ *
+ *   - `ide-native`     — peaks-loop writes the compact intent to
+ *                        the IDE's hook file (per
+ *                        `IdeSettingsLocation`). Used when the IDE
+ *                        requires a registered hook rather than a
+ *                        runtime command.
+ *   - `llm-self-compress` — peaks-loop records the intent and
+ *                        returns `ok: true` with `pathway` echoed.
+ *                        The LLM does its own context summarization
+ *                        on the next turn. Always available; least
+ *                        precise fallback.
+ *   - `noop`           — adapter explicitly opted out. peaks-loop
+ *                        returns `ok: false` with `message: 'noop'`.
+ *                        Used by legacy / unverified adapters.
+ *
+ * rid-031 (2026-07-28): `shell-exec` pathway is DEPRECATED. Real
+ * callers must use `ide-native` (main session) or
+ * `llm-self-compress`. No host CLI spawn occurs; the `case
+ * 'shell-exec':` branch logs a deprecation warning and returns the
+ * same envelope shape.
+ *
+ * Slice 2026-09-12-auto-compact-vendor-neutrality (defect #2 of the QA
+ * pass): the paragraph above used to justify keeping that branch with
+ * "the 2 currently-passing tests" it named by path and line (`:58` of
+ * one file, `:102` of another, asserting `pathway: 'shell-exec'`).
+ * That justification ROTTED and is false as of today: both files were
+ * deleted by `f17aa377 test(rebuild): delete 559 legacy unit tests and
+ * reset vitest config`, and `grep -rn "shell-exec" tests/` now returns
+ * nothing — no test in this repo asserts `pathway: 'shell-exec'`. The
+ * branch is retained for the rid-031 ENVELOPE CONTRACT itself
+ * (`pathway` is part of `CompactDispatchResult` and is echoed to
+ * `peaks code auto-compact` callers), not for a test. Deleting it is a
+ * contract change, deliberately out of this slice.
+ */
+import { join } from 'node:path';
 import { detectIdeFromEnv } from './ide-detect.js';
 import { getAdapter } from '../ide/ide-registry.js';
 /**
@@ -21,21 +66,28 @@ export async function dispatchIdeCompact(input) {
     // the main-session context. The orchestrator passes `'sub-agent'`
     // explicitly when a sub-agent shell dispatches the call.
     const target = input.target ?? 'main';
-    // Slice 2026-06-28: when targeting the MAIN session, refuse
-    // up-front for adapters we cannot dispatch a main-session compact
-    // against. We DO this before the `!adapter.compact` short-circuit
-    // so the test message reflects the operational cause (target vs
-    // adapter capability). Even non-claude-code adapters without a
-    // registered `compact` profile should report "main-session target
-    // unsupported" rather than the generic "no compact profile" line.
-    if (target === 'main' && ideId !== 'claude-code') {
-        return {
-            ok: false,
-            ide: ideId,
-            pathway: 'noop',
-            message: `main-session target unsupported on adapter '${ideId}'; only claude-code supports in-band main-session compact.`
-        };
-    }
+    // Slice 2026-09-12-auto-compact-vendor-neutrality — the up-front
+    // `target === 'main' && ideId !== 'claude-code'` refusal is GONE.
+    //
+    // It decided by adapter NAME what the adapter's own profile already
+    // declares, contradicting this file's contract ("No hard-coded IDE
+    // names", :5-8): any adapter that filled in `compact` was still
+    // rejected for not being called `claude-code`.
+    //
+    // It was also redundant. Every pathway below owns its own
+    // main-session semantics — `ide-native` installs the hook against the
+    // caller's own window; `shell-exec` is explicitly degraded to
+    // `llm-self-compress` for a main target; `llm-self-compress` and
+    // `noop` behave identically for both targets (so `noop` still returns
+    // `ok: false` on main); an UNKNOWN pathway falls through to the
+    // default noop. An adapter with no `compact` profile keeps its own
+    // explicit refusal immediately below. No remaining capability test
+    // would have been anything but a duplicate of one of those branches,
+    // so the check was deleted rather than re-keyed. The two candidate
+    // re-keyings were both rejected: `pathway !== 'ide-native'` would
+    // refuse `shell-exec` and `llm-self-compress` adapters that the
+    // switch already serves, and `pathway === 'noop'` IS the branch
+    // immediately below.
     // Adapters that don't declare `compact` (legacy / unverified) →
     // explicit noop so the caller can distinguish "IDE doesn't support
     // compact" from "IDE supports but dispatch failed".
@@ -53,12 +105,13 @@ export async function dispatchIdeCompact(input) {
     switch (pathway) {
         case 'shell-exec':
             // rid-031 (2026-07-28): `shell-exec` pathway is DEPRECATED.
-            // No host CLI spawn occurs. The case marker is preserved so
-            // 2 currently-passing tests in
-            //   tests/unit/context/auto-compact-main-target.test.ts:58
-            //   tests/unit/services/context/auto-compact-dispatcher-ide-native.test.ts:102
-            // continue to assert `pathway: 'shell-exec'`. Real callers must
-            // use `ide-native` (main session) or `llm-self-compress`.
+            // No host CLI spawn occurs. The case marker is preserved for the
+            // rid-031 envelope contract (callers read `pathway`), NOT for a
+            // test — see this file's header, defect #2 of the 2026-09-12 QA
+            // pass: the tests the previous comment named were deleted by
+            // f17aa377 and no test asserts `pathway: 'shell-exec'` now.
+            // Real callers must use `ide-native` (main session) or
+            // `llm-self-compress`.
             console.warn(`compact: shell-exec pathway is deprecated on adapter '${ideId}' (target='${target}'); no host CLI spawn — use ide-native instead.`);
             if (target === 'main') {
                 return {
@@ -76,12 +129,14 @@ export async function dispatchIdeCompact(input) {
             };
         case 'ide-native':
             // Slice 2026-07-02-auto-compact-zero-pause: write the auto-compact
-            // PreToolUse hook into `.claude/settings.local.json`. The hook
-            // command (`peaks code auto-compact`) reads
-            // `CLAUDE_CONTEXT_USAGE_PERCENT` on every subsequent Bash/Task
-            // tool call from the runner and, at ratio ≥ 0.95, in-band spawns
-            // `claude --compact` against the CURRENT runner (not a child
-            // process — the bug documented in
+            // PreToolUse hook into the IDE's MACHINE-LOCAL settings layer,
+            // resolved from the adapter (`settings.dirName` +
+            // `settings.localSettingsFileName`) — never from a path literal
+            // here. The hook command (`peaks code auto-compact`) reads the
+            // adapter-declared `envVarForContextPercent` on every subsequent
+            // Bash/Task tool call from the runner and, at ratio ≥ 0.95,
+            // in-band spawns the adapter-declared `compactCommand` against the
+            // CURRENT runner (not a child process — the bug documented in
             // `.peaks/memory/2026-06-27-auto-compact-design.md:139-152`).
             //
             // `ide-native` is ONLY for the main-session runner. When the
@@ -93,10 +148,11 @@ export async function dispatchIdeCompact(input) {
             if (target === 'sub-agent') {
                 // rid-031 (2026-07-28): legacy shell-spawn fallback is
                 // DEPRECATED. No host CLI spawn occurs. The envelope is
-                // returned with `pathway: 'shell-exec'` to preserve the
-                // contract asserted by
-                //   tests/unit/services/context/auto-compact-dispatcher-ide-native.test.ts:102
-                // (sub-agent shells historically relied on this path).
+                // returned with `pathway: 'shell-exec'` to preserve the rid-031
+                // contract for callers that read `pathway` (sub-agent shells
+                // historically relied on this path). The test the previous
+                // comment named was deleted by f17aa377 — see this file's
+                // header, defect #2 of the 2026-09-12 QA pass.
                 console.warn(`compact: sub-agent shell-exec fallback is deprecated on adapter '${ideId}'; no host CLI spawn for '${profile.compactCommand}'.`);
                 return {
                     ok: true,
@@ -111,7 +167,9 @@ export async function dispatchIdeCompact(input) {
             return await dispatchIdeNativeHook({
                 projectRoot: input.projectRoot,
                 sessionId: input.sessionId,
-                target
+                target,
+                adapter,
+                profile
             });
         case 'llm-self-compress':
             return {
@@ -141,11 +199,18 @@ export async function dispatchIdeCompact(input) {
 /**
  * Slice 2026-07-02-auto-compact-zero-pause: implement the
  * `ide-native` pathway. Writes the auto-compact PreToolUse hook
- * into `.claude/settings.local.json` (idempotent; the install
- * service is a no-op if the hook is already present). On the next
- * Bash/Task tool call from the runner, the hook fires
- * `peaks code auto-compact` which in-band spawns
- * `claude --compact` against the CURRENT runner session.
+ * into the IDE's MACHINE-LOCAL settings file (idempotent; the
+ * install service is a no-op if the hook is already present). On
+ * the next Bash/Task tool call from the runner, the hook fires
+ * `peaks code auto-compact` which in-band spawns the adapter's
+ * declared compact command against the CURRENT runner session.
+ *
+ * Slice 2026-09-12-auto-compact-vendor-neutrality: the settings path
+ * AND the echoed `ide` are read off the adapter, so this function no
+ * longer names a vendor. An adapter that declares
+ * `compactPathway: 'ide-native'` and its own `settings` location gets
+ * its own hook file — the `.claude/settings.local.json` value survives
+ * only as the installer's default for callers with no adapter in hand.
  *
  * Returns `ok: true, pathway: 'ide-native'` regardless of install
  * action (`installed` vs `already-installed`) — both states
@@ -158,13 +223,21 @@ async function dispatchIdeNativeHook(input) {
     // avoids a static cycle if future slices add cross-imports
     // between dispatcher and hook-install.
     const { installAutoCompactHook } = await import('../hooks/auto-compact-hook-install.js');
-    const result = installAutoCompactHook({ projectRoot: input.projectRoot });
+    // Resolve the local settings file from the adapter's declared
+    // location. `undefined` means "this IDE declares no machine-local
+    // layer" → the installer's documented default applies.
+    const localFileName = input.adapter.settings.localSettingsFileName;
+    const settingsPath = localFileName === undefined
+        ? undefined
+        : join(input.projectRoot, input.adapter.settings.dirName, localFileName);
+    const result = installAutoCompactHook({ projectRoot: input.projectRoot, settingsPath });
+    const envVar = input.profile.envVarForContextPercent;
     return {
         ok: true,
-        ide: 'claude-code',
+        ide: input.adapter.id,
         pathway: 'ide-native',
         message: result.action === 'installed'
-            ? `Auto-compact PreToolUse hook installed at ${result.settingsPath}. Next Bash/Task tool call will read CLAUDE_CONTEXT_USAGE_PERCENT and compact in-band at ratio ≥ 95%.`
+            ? `Auto-compact PreToolUse hook installed at ${result.settingsPath}. Next Bash/Task tool call will read ${envVar} and compact in-band at ratio ≥ 95%.`
             : result.action === 'updated'
                 ? `Auto-compact PreToolUse hook REPAIRED at ${result.settingsPath} — the installed entry carried a stale command and was rewritten.`
                 : `Auto-compact PreToolUse hook already installed at ${result.settingsPath}; next Bash/Task tool call will trigger compact in-band at ratio ≥ 95%.`

package/dist/services/context/auto-compact-reader.d.ts

@@ -1,32 +1,5 @@
-/**
- * AC-1 — auto context-percent probe.
- *
- * Reads the current AI CLI context-fill ratio without requiring the
- * LLM to pass `--prompt-size <bytes>` manually. Strategy: ask the
- * registered `IdeAdapter.compact` profile which env-var to read and,
- * when that misses, ask the adapter for a vendor-specific fallback —
- * no hard-coded IDE names. Per-adapter:
- *
- *   - claude-code: its adapter-declared env-var (MVP) + a
- *     `readContextPercentFallback` that polls the statusline /
- *     transcript (see claude-code-adapter.ts).
- *   - trae / codex / cursor / qoder / tongyi-lingma / hermes /
- *     openclaw / zcode: each adapter fills its own env-var; until
- *     L2-dogfood verifies each surface, adapters may omit `compact`
- *     and the probe returns `source: 'conservative-fallback'`.
- *
- * Resolution order (user-overridden → env-var → adapter fallback →
- * conservative-fallback):
- *   1. `promptSizeBytes` (P0 `--prompt-size <bytes>` escape hatch) →
- *      `source: 'user-overridden'`.
- *   2. `adapter.compact.envVarForContextPercent` env-var →
- *      `source: '<ideId>-env'`.
- *   3. `adapter.compact.readContextPercentFallback?.(input)` — the
- *      adapter owns any vendor-specific statusline / transcript probe.
- *   4. `ratio: 0` with `source: 'conservative-fallback'` — the
- *      orchestrator MUST NOT auto-fire compact on this signal.
- */
 import type { ContextPercentProbe } from './auto-compact-types.js';
+import { type HarnessWindowLocation, type HarnessWindowReadResult, type HarnessWindowSyncResult } from './harness-window-config.js';
 export interface ReadContextPercentInput {
     readonly projectRoot: string;
     readonly sessionId: string;
@@ -50,6 +23,73 @@ export interface ReadContextPercentInput {
      */
     readonly promptSizeBytes?: number | undefined;
 }
+/**
+ * Resolve WHERE the harness auto-compact window lives, for the IDE the
+ * current env selects. Returns `null` when either half is undeclared:
+ *   - the adapter exposes no `compact` profile, or
+ *   - the adapter's `compact` profile declares no
+ *     `autoCompactWindowEnvVar` (the IDE has no such knob), or
+ *   - the adapter declares no machine-local settings layer.
+ *
+ * Both the path and the key name come from the adapter's OWN declarations,
+ * so this module names no IDE and no settings literal — the vendor-neutrality
+ * guard's shape-3 rule applies to every registry consumer, and this is one.
+ *
+ * Slice 2026-09-13-auto-compact-trigger-ownership.
+ */
+export declare function resolveHarnessWindowLocation(input: {
+    readonly projectRoot: string;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+}): HarnessWindowLocation | null;
+/**
+ * Read the window peaks-loop last configured for the harness, plus whether
+ * the user has opted out of peaks-loop managing it. Returns `null` when the
+ * active adapter exposes no window knob at all.
+ */
+export declare function readHarnessWindowState(input: {
+    readonly projectRoot: string;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+}): HarnessWindowReadResult | null;
+/**
+ * The RAW window peaks-loop's context ratio must divide by — T1's number.
+ *
+ * The SETTINGS FILE is the source of truth, so its value wins whenever it has
+ * one; the env-first read is consulted only when the file is silent (no key
+ * yet, or the IDE injects the value from an outer layer).
+ *
+ * Why not "whatever the read returned" (the round-2 shape): the process env is
+ * a snapshot the harness froze at session start, so it is stale by exactly one
+ * write. Trusting it over the file is what let a stale env revert a human's
+ * hand-edited window (B1) and downgrade a 1M file to a 200K one (a second
+ * session's frozen env), and it is also what made T1's consistency depend on
+ * *rewriting the file* — the same unconditional write that destroyed the human's
+ * value. Dividing by the file instead makes peaks-loop's ratio and the harness's
+ * configured window one number BY CONSTRUCTION, with no write required. The
+ * write is then free to be gated on provenance (see `syncHarnessWindow`).
+ *
+ * Falls back to `undefined` (no harness layer at all) when the adapter
+ * declares no knob or neither side carries the key — the adapter then resolves
+ * its own window exactly as it did before this slice.
+ */
+export declare function resolveHarnessRatioWindow(state: HarnessWindowReadResult | null): unknown;
+/**
+ * Materialize a window into the harness's own settings, so the number
+ * peaks-loop divides by and the number the harness compacts against are one
+ * value rather than two resolutions (slice
+ * 2026-09-13-auto-compact-trigger-ownership).
+ *
+ * The caller passes the denominator it JUST USED (`probe.capacityTokens`), not
+ * a re-derived one — that is what makes the two sides structurally identical.
+ * `tokens: null` (a percent-only probe carries no token window) is a
+ * deliberate no-op: peaks-loop never invents a window it did not measure.
+ *
+ * Returns `null` when the active adapter declares no window knob at all.
+ */
+export declare function syncHarnessWindowForProject(input: {
+    readonly projectRoot: string;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    readonly tokens: number | null;
+}): HarnessWindowSyncResult | null;
 /**
  * Read env-var-based context percentage. Returns `null` when the env
  * is absent or unparseable. Adapter-driven: the caller passes the

package/dist/services/context/auto-compact-reader.js

@@ -1,6 +1,141 @@
+/**
+ * AC-1 — auto context-percent probe.
+ *
+ * Reads the current AI CLI context-fill ratio without requiring the
+ * LLM to pass `--prompt-size <bytes>` manually. Strategy: ask the
+ * registered `IdeAdapter.compact` profile which env-var to read and,
+ * when that misses, ask the adapter for a vendor-specific fallback —
+ * no hard-coded IDE names. Per-adapter:
+ *
+ *   - claude-code: its adapter-declared env-var (MVP) + a
+ *     `readContextPercentFallback` that polls the statusline /
+ *     transcript (see claude-code-adapter.ts).
+ *   - trae / codex / cursor / qoder / tongyi-lingma / hermes /
+ *     openclaw / zcode: each adapter fills its own env-var; until
+ *     L2-dogfood verifies each surface, adapters may omit `compact`
+ *     and the probe returns `source: 'conservative-fallback'`.
+ *
+ * Resolution order (user-overridden → env-var → adapter fallback →
+ * conservative-fallback):
+ *   1. `promptSizeBytes` (P0 `--prompt-size <bytes>` escape hatch) →
+ *      `source: 'user-overridden'`.
+ *   2. `adapter.compact.envVarForContextPercent` env-var →
+ *      `source: '<ideId>-env'`.
+ *   3. `adapter.compact.readContextPercentFallback?.(input)` — the
+ *      adapter owns any vendor-specific statusline / transcript probe.
+ *   4. `ratio: 0` with `source: 'conservative-fallback'` — the
+ *      orchestrator MUST NOT auto-fire compact on this signal.
+ */
+import { join } from 'node:path';
 import { detectIdeFromEnv } from './ide-detect.js';
 import { getAdapter } from '../ide/ide-registry.js';
 import { readContextWindowTokensOverride } from '../config/config-service.js';
+import { isHarnessWindowInRange, parseHarnessWindowTokens, readHarnessWindow, syncHarnessWindow } from './harness-window-config.js';
+/**
+ * Resolve WHERE the harness auto-compact window lives, for the IDE the
+ * current env selects. Returns `null` when either half is undeclared:
+ *   - the adapter exposes no `compact` profile, or
+ *   - the adapter's `compact` profile declares no
+ *     `autoCompactWindowEnvVar` (the IDE has no such knob), or
+ *   - the adapter declares no machine-local settings layer.
+ *
+ * Both the path and the key name come from the adapter's OWN declarations,
+ * so this module names no IDE and no settings literal — the vendor-neutrality
+ * guard's shape-3 rule applies to every registry consumer, and this is one.
+ *
+ * Slice 2026-09-13-auto-compact-trigger-ownership.
+ */
+export function resolveHarnessWindowLocation(input) {
+    const env = input.env ?? process.env;
+    const detected = detectIdeFromEnv(env);
+    const ideId = (detected === 'unknown' ? 'claude-code' : detected);
+    const adapter = getAdapter(ideId);
+    const envVar = adapter.compact?.autoCompactWindowEnvVar;
+    const fileName = adapter.settings.localSettingsFileName ?? adapter.settings.settingsFileName;
+    if (envVar === undefined || fileName === undefined)
+        return null;
+    return {
+        settingsPath: join(input.projectRoot, adapter.settings.dirName, fileName),
+        envVar,
+        // Carried so the writer can refuse to target the user's own home directory
+        // (`--project .` from a fresh terminal): the path alone cannot say which
+        // root it came from, and this is the only place a location is built.
+        projectRoot: input.projectRoot
+    };
+}
+/**
+ * Read the window peaks-loop last configured for the harness, plus whether
+ * the user has opted out of peaks-loop managing it. Returns `null` when the
+ * active adapter exposes no window knob at all.
+ */
+export function readHarnessWindowState(input) {
+    const location = resolveHarnessWindowLocation(input);
+    if (location === null)
+        return null;
+    return readHarnessWindow({ location, env: input.env ?? process.env });
+}
+/**
+ * The RAW window peaks-loop's context ratio must divide by — T1's number.
+ *
+ * The SETTINGS FILE is the source of truth, so its value wins whenever it has
+ * one; the env-first read is consulted only when the file is silent (no key
+ * yet, or the IDE injects the value from an outer layer).
+ *
+ * Why not "whatever the read returned" (the round-2 shape): the process env is
+ * a snapshot the harness froze at session start, so it is stale by exactly one
+ * write. Trusting it over the file is what let a stale env revert a human's
+ * hand-edited window (B1) and downgrade a 1M file to a 200K one (a second
+ * session's frozen env), and it is also what made T1's consistency depend on
+ * *rewriting the file* — the same unconditional write that destroyed the human's
+ * value. Dividing by the file instead makes peaks-loop's ratio and the harness's
+ * configured window one number BY CONSTRUCTION, with no write required. The
+ * write is then free to be gated on provenance (see `syncHarnessWindow`).
+ *
+ * Falls back to `undefined` (no harness layer at all) when the adapter
+ * declares no knob or neither side carries the key — the adapter then resolves
+ * its own window exactly as it did before this slice.
+ */
+export function resolveHarnessRatioWindow(state) {
+    if (state === null)
+        return undefined;
+    // E1 (rid 2026-09-13-defects-e): a value outside the band the harness accepts
+    // is not a window, however well-formed an integer it is — the harness ignores
+    // or caps it, so handing it over here would make the ratio's denominator a
+    // number the harness is not compacting on. This is the read half of the same
+    // guard the writer applies before planting one; without it, a value already on
+    // disk (hand-planted, or written by a release that predates the band) would
+    // keep poisoning the ratio on every probe.
+    //
+    // The two NULLs are deliberate and different: an out-of-band value is refused
+    // here (the adapter falls through to its own resolution and the writer's
+    // notice names the skipped number), while an UNPARSEABLE one is still handed
+    // over — the adapter validates it and warns about a hand-edited `500k`, which
+    // is a closer reading of the user's intent than silently ignoring it.
+    const raw = state.fileRaw !== undefined ? state.fileRaw : state.raw;
+    const tokens = parseHarnessWindowTokens(raw);
+    if (tokens !== null && !isHarnessWindowInRange(tokens))
+        return undefined;
+    return raw;
+}
+/**
+ * Materialize a window into the harness's own settings, so the number
+ * peaks-loop divides by and the number the harness compacts against are one
+ * value rather than two resolutions (slice
+ * 2026-09-13-auto-compact-trigger-ownership).
+ *
+ * The caller passes the denominator it JUST USED (`probe.capacityTokens`), not
+ * a re-derived one — that is what makes the two sides structurally identical.
+ * `tokens: null` (a percent-only probe carries no token window) is a
+ * deliberate no-op: peaks-loop never invents a window it did not measure.
+ *
+ * Returns `null` when the active adapter declares no window knob at all.
+ */
+export function syncHarnessWindowForProject(input) {
+    const location = resolveHarnessWindowLocation(input);
+    if (location === null)
+        return null;
+    return syncHarnessWindow({ location, tokens: input.tokens, env: input.env ?? process.env });
+}
 /**
  * Read env-var-based context percentage. Returns `null` when the env
  * is absent or unparseable. Adapter-driven: the caller passes the
@@ -61,6 +196,17 @@ export function readContextPercent(input) {
         };
     }
     if (adapter.compact) {
+        // Slice 2026-09-13-auto-compact-trigger-ownership: the window peaks-loop
+        // configured for the harness, read from the adapter's declared settings
+        // path + key. `null` (no knob declared, or the key absent) leaves the
+        // adapter's chain byte-identical to before this slice.
+        //
+        // The RAW value is handed over, not the parsed one: the adapter validates
+        // it (`parseContextWindowOverride`) and warns on a bad hand-edited value,
+        // so parsing here too would be a second, silently-disagreeing parser —
+        // exactly the duplicated-resolution shape this slice exists to delete.
+        const harnessWindowState = readHarnessWindowState({ projectRoot: input.projectRoot, env });
+        const harnessWindowTokens = resolveHarnessRatioWindow(harnessWindowState);
         // Primary: read the adapter-declared env-var (no hard-coded IDE names).
         const primary = readEnvPercent(env, adapter.compact.envVarForContextPercent);
         if (primary !== null) {
@@ -85,7 +231,15 @@ export function readContextPercent(input) {
             sessionId: input.sessionId,
             outerSessionId: input.outerSessionId,
             env,
-            configWindowTokens: readContextWindowTokensOverride(input.projectRoot)
+            configWindowTokens: readContextWindowTokensOverride(input.projectRoot),
+            // Slice 2026-09-13-auto-compact-trigger-ownership: hand the adapter the
+            // window peaks-loop configured for the harness, so the ratio it reports
+            // divides by the very number the harness compacts against — plus whether
+            // peaks-loop is the one that wrote it, so the adapter may self-correct
+            // its own earlier resolution without ever overruling a human's pin.
+            ...(harnessWindowTokens !== undefined
+                ? { harnessWindowTokens, harnessWindowPeakWritten: harnessWindowState?.peakWritten === true }
+                : {})
         });
         if (fallback)
             return fallback;