peaks-loop 4.0.46 → 4.0.47

package/dist/services/ide/adapters/claude-code-adapter.d.ts

@@ -47,11 +47,16 @@ export declare const CONTEXT_WINDOW_TOKENS_ENV_VAR = "PEAKS_CONTEXT_WINDOW_TOKEN
 /**
  * Which layer produced a resolved context window:
  *   - `env-override`     — `PEAKS_CONTEXT_WINDOW_TOKENS`
+ *   - `harness-env`      — the window peaks-loop itself wrote into the
+ *                          harness's machine-local settings
+ *                          (`CLAUDE_CODE_AUTO_COMPACT_WINDOW`, declared by
+ *                          the adapter as `autoCompactWindowEnvVar`); see
+ *                          `harness-window-config.ts`
  *   - `config`           — `context.windowTokens` (`peaks config set`)
  *   - `model-heuristic`  — `[1M]` suffix / `ONE_MILLION_CONTEXT_MODELS`
  *   - `default`          — 200K safe default
  */
-export type ContextWindowSource = 'env-override' | 'config' | 'model-heuristic' | 'default';
+export type ContextWindowSource = 'env-override' | 'harness-env' | 'config' | 'model-heuristic' | 'default';
 export interface ContextWindowResolution {
     readonly tokens: number;
     readonly source: ContextWindowSource;
@@ -61,9 +66,78 @@ export interface ContextWindowOverrides {
     readonly env?: NodeJS.ProcessEnv | undefined;
     /** Raw `context.windowTokens` value (unvalidated — validated here). */
     readonly configWindowTokens?: unknown;
+    /**
+     * The window peaks-loop itself configured for the harness — raw value read
+     * from the harness's machine-local settings `env` block (or the process env
+     * the harness populated from it). Resolved by the caller
+     * (`auto-compact-reader.ts` via `harness-window-config.ts`), NOT here: the
+     * settings path and the key name are per-IDE declarations.
+     *
+     * Slice 2026-09-13-auto-compact-trigger-ownership: this layer is what makes
+     * the ratio peaks-loop computes and the window the harness compacts against
+     * THE SAME NUMBER. Without it they are two independent resolutions that can
+     * drift 5× apart on a 1M-window model the model-name heuristic misses.
+     */
+    readonly harnessWindowTokens?: unknown;
+    /**
+     * Provenance of `harnessWindowTokens`: true when peaks-loop wrote that value
+     * itself, false/omitted when a human set it. Only a peaks-written value may
+     * be overruled by the late 1M rescue — see `resolveContextWindowTokens`.
+     */
+    readonly harnessWindowPeakWritten?: boolean;
     /** Warning sink for an invalid override (defaults to `console.warn`). */
     readonly onInvalidOverride?: ((message: string) => void) | undefined;
+    /**
+     * Warning sink for the E2 notice: a HUMAN pin (`env-override` / `config`)
+     * larger than peaks-loop's own model-window estimate. Deliberately separate
+     * from `onInvalidOverride` — that sink means "your value could not be read",
+     * this one means "your value was read, and peaks-loop cannot promise the
+     * harness will use it". Two meanings, two sinks. Defaults to `console.warn`.
+     *
+     * See `describeWindowAboveModelEstimate` for what the notice does and does
+     * not claim, and why it is a notice rather than a refusal.
+     */
+    readonly onAboveModelEstimate?: ((message: string) => void) | undefined;
 }
+/**
+ * E2 (rid 2026-09-13-defects-e) — the notice for a pin larger than
+ * peaks-loop's model-window estimate. `null` when there is nothing to say.
+ *
+ * WHY THIS EXISTS. The harness does not take its auto-compact window on faith:
+ * it reduces the configured value with `Math.min(native, override)`, where
+ * `native` is the model's own context size. A pin ABOVE `native` is therefore
+ * accepted by peaks-loop, written to the harness's settings, and silently
+ * reduced by the harness — so peaks-loop's ratio divides by a window the
+ * harness is not compacting on. That is the A1 drift (two independent
+ * resolutions, one number meaning two things), arriving from the other side
+ * from E1: E1 is a value the harness refuses, E2 a value it quietly lowers.
+ *
+ * CAN WE READ THE NATIVE WINDOW? No, and the notice does not pretend otherwise.
+ * There is no API for it and no environment variable that carries it; the only
+ * local knowledge is `modelContextWindowTokens`'s NAME HEURISTIC (200_000, or
+ * 1_000_000 when the id says `1m` or matches the allowlist) — the very layer
+ * this slice demoted, because it is wrong for precisely the proxied /
+ * third-party models the pin exists for. It is used here ONLY as a disagreement
+ * DETECTOR, never as an authority, and the uncertainty that buys is one-sided:
+ * this notice means "peaks-loop's best guess of your model is smaller than the
+ * window you pinned", which a genuinely larger model ALSO produces. It cannot
+ * mean "the harness will definitely cap you" — only the harness knows that.
+ *
+ * WHY A NOTICE AND NOT A REFUSAL. The pin is the documented escape hatch for a
+ * model id the heuristic cannot see, so refusing would delete the feature. The
+ * notice keeps it and states the risk.
+ *
+ * WHY ONLY THE HUMAN PINS. The `harness-env` layer is a value peaks-loop FOUND
+ * in the harness's own file, not one this call is setting; its disagreements are
+ * already reported by the writer (`harnessWindowSyncWarning`), and warning here
+ * would fire on every probe of a project whose file legitimately says 1000000.
+ */
+export declare function describeWindowAboveModelEstimate(input: {
+    readonly model: string;
+    readonly tokens: number;
+    /** Human-readable name of the pin, e.g. `PEAKS_CONTEXT_WINDOW_TOKENS="500000"`. */
+    readonly pin: string;
+}): string | null;
 /**
  * Parse an explicit context-window override. Accepts a positive finite
  * integer only (number, or a numeric string so an env var works); anything
@@ -76,11 +150,41 @@ export declare function parseContextWindowOverride(raw: unknown): number | null;
  * (first hit wins):
  *   1. env `PEAKS_CONTEXT_WINDOW_TOKENS`
  *   2. config `context.windowTokens`
- *   3. model-name heuristic (`modelContextWindowTokens`)
- *   4. `DEFAULT_CONTEXT_WINDOW_TOKENS` (200_000)
+ *   3. `harnessWindowTokens` — the window peaks-loop configured for the
+ *      harness (`autoCompactWindowEnvVar`)
+ *   4. model-name heuristic (`modelContextWindowTokens`)
+ *   5. `DEFAULT_CONTEXT_WINDOW_TOKENS` (200_000)
  *
  * An invalid explicit override is ignored with a warning and falls through
  * to the next layer — a typo must never crash or silently win the probe.
+ *
+ * Slice 2026-09-13-auto-compact-trigger-ownership — why layer 3 exists:
+ *   The hard constraint is that the window peaks-loop divides by must BE the
+ *   window it configured for the harness. Layer 3 is peaks-loop's own output
+ *   read back from the harness's settings file, so the two sides reference one
+ *   artifact rather than two independent resolutions. It sits ABOVE the model
+ *   heuristic because a heuristic contradicting the number both sides already
+ *   use is precisely how the 5× drift arose (a 1M-window model measured
+ *   against a 200K guess).
+ *
+ *   Why it sits BELOW the two explicit pins. Both are human declarations of
+ *   intent, and a pin that loses to a value peaks-loop wrote earlier is a
+ *   silently ignored setting: the user changes `context.windowTokens`, the
+ *   stale harness key shadows it, and nothing appears to happen. Conflict is
+ *   instead resolved by PROPAGATION — the probe that resolves the pin also
+ *   syncs it into the harness (`syncHarnessWindowForProject`), so peaks-loop's
+ *   ratio and the harness's window are back on one number before that command
+ *   returns. The conflict is therefore transient and self-healing rather than
+ *   either silent shadowing or permanent drift.
+ *
+ *   Why layer 3 is not simply authoritative (the ratchet). Reading back a value
+ *   peaks-loop wrote makes peaks-loop trust its own earlier resolution, so a
+ *   first-time mis-resolution (an unrecognised model defaulting to 200_000)
+ *   would be written to disk and then believed forever: the ratio stays
+ *   saturated at 1.0 while the session grows past the pin, and the correction
+ *   that exists for exactly that case — the late 1M rescue — was disabled for
+ *   this layer. Self-locking. See `resolveContextWindowTokens` for how the
+ *   rescue is let back in without letting it overwrite a human's own setting.
  */
 export declare function resolveContextWindow(model: string, overrides?: ContextWindowOverrides): ContextWindowResolution;
 export declare const CLAUDE_CODE_ADAPTER: IdeAdapter;

package/dist/services/ide/adapters/claude-code-adapter.js

@@ -200,6 +200,50 @@ export function modelContextWindowTokens(model) {
  * machine-wide `peaks config set --key context.windowTokens` twin.
  */
 export const CONTEXT_WINDOW_TOKENS_ENV_VAR = 'PEAKS_CONTEXT_WINDOW_TOKENS';
+/**
+ * E2 (rid 2026-09-13-defects-e) — the notice for a pin larger than
+ * peaks-loop's model-window estimate. `null` when there is nothing to say.
+ *
+ * WHY THIS EXISTS. The harness does not take its auto-compact window on faith:
+ * it reduces the configured value with `Math.min(native, override)`, where
+ * `native` is the model's own context size. A pin ABOVE `native` is therefore
+ * accepted by peaks-loop, written to the harness's settings, and silently
+ * reduced by the harness — so peaks-loop's ratio divides by a window the
+ * harness is not compacting on. That is the A1 drift (two independent
+ * resolutions, one number meaning two things), arriving from the other side
+ * from E1: E1 is a value the harness refuses, E2 a value it quietly lowers.
+ *
+ * CAN WE READ THE NATIVE WINDOW? No, and the notice does not pretend otherwise.
+ * There is no API for it and no environment variable that carries it; the only
+ * local knowledge is `modelContextWindowTokens`'s NAME HEURISTIC (200_000, or
+ * 1_000_000 when the id says `1m` or matches the allowlist) — the very layer
+ * this slice demoted, because it is wrong for precisely the proxied /
+ * third-party models the pin exists for. It is used here ONLY as a disagreement
+ * DETECTOR, never as an authority, and the uncertainty that buys is one-sided:
+ * this notice means "peaks-loop's best guess of your model is smaller than the
+ * window you pinned", which a genuinely larger model ALSO produces. It cannot
+ * mean "the harness will definitely cap you" — only the harness knows that.
+ *
+ * WHY A NOTICE AND NOT A REFUSAL. The pin is the documented escape hatch for a
+ * model id the heuristic cannot see, so refusing would delete the feature. The
+ * notice keeps it and states the risk.
+ *
+ * WHY ONLY THE HUMAN PINS. The `harness-env` layer is a value peaks-loop FOUND
+ * in the harness's own file, not one this call is setting; its disagreements are
+ * already reported by the writer (`harnessWindowSyncWarning`), and warning here
+ * would fire on every probe of a project whose file legitimately says 1000000.
+ */
+export function describeWindowAboveModelEstimate(input) {
+    const estimate = modelContextWindowTokens(input.model);
+    if (input.tokens <= estimate)
+        return null;
+    return (`[peaks] ${input.pin} is larger than peaks-loop's model-window estimate for ` +
+        `"${input.model}" (${estimate} tokens). peaks-loop cannot read a model's native context window — this ` +
+        `estimate is a name heuristic and may be wrong — and the harness caps its auto-compact window at that ` +
+        `native size, so if the estimate is right the harness will compact at ${estimate} while this ratio ` +
+        `divides by ${input.tokens}. If your model really does have the larger window this is expected; ` +
+        `otherwise set the value to the model's real window so the two stay in step.`);
+}
 /**
  * Parse an explicit context-window override. Accepts a positive finite
  * integer only (number, or a numeric string so an env var works); anything
@@ -219,27 +263,82 @@ export function parseContextWindowOverride(raw) {
  * (first hit wins):
  *   1. env `PEAKS_CONTEXT_WINDOW_TOKENS`
  *   2. config `context.windowTokens`
- *   3. model-name heuristic (`modelContextWindowTokens`)
- *   4. `DEFAULT_CONTEXT_WINDOW_TOKENS` (200_000)
+ *   3. `harnessWindowTokens` — the window peaks-loop configured for the
+ *      harness (`autoCompactWindowEnvVar`)
+ *   4. model-name heuristic (`modelContextWindowTokens`)
+ *   5. `DEFAULT_CONTEXT_WINDOW_TOKENS` (200_000)
  *
  * An invalid explicit override is ignored with a warning and falls through
  * to the next layer — a typo must never crash or silently win the probe.
+ *
+ * Slice 2026-09-13-auto-compact-trigger-ownership — why layer 3 exists:
+ *   The hard constraint is that the window peaks-loop divides by must BE the
+ *   window it configured for the harness. Layer 3 is peaks-loop's own output
+ *   read back from the harness's settings file, so the two sides reference one
+ *   artifact rather than two independent resolutions. It sits ABOVE the model
+ *   heuristic because a heuristic contradicting the number both sides already
+ *   use is precisely how the 5× drift arose (a 1M-window model measured
+ *   against a 200K guess).
+ *
+ *   Why it sits BELOW the two explicit pins. Both are human declarations of
+ *   intent, and a pin that loses to a value peaks-loop wrote earlier is a
+ *   silently ignored setting: the user changes `context.windowTokens`, the
+ *   stale harness key shadows it, and nothing appears to happen. Conflict is
+ *   instead resolved by PROPAGATION — the probe that resolves the pin also
+ *   syncs it into the harness (`syncHarnessWindowForProject`), so peaks-loop's
+ *   ratio and the harness's window are back on one number before that command
+ *   returns. The conflict is therefore transient and self-healing rather than
+ *   either silent shadowing or permanent drift.
+ *
+ *   Why layer 3 is not simply authoritative (the ratchet). Reading back a value
+ *   peaks-loop wrote makes peaks-loop trust its own earlier resolution, so a
+ *   first-time mis-resolution (an unrecognised model defaulting to 200_000)
+ *   would be written to disk and then believed forever: the ratio stays
+ *   saturated at 1.0 while the session grows past the pin, and the correction
+ *   that exists for exactly that case — the late 1M rescue — was disabled for
+ *   this layer. Self-locking. See `resolveContextWindowTokens` for how the
+ *   rescue is let back in without letting it overwrite a human's own setting.
  */
 export function resolveContextWindow(model, overrides = {}) {
     const warn = overrides.onInvalidOverride ?? ((message) => console.warn(message));
+    // E2: the second sink, for a value that IS valid but that the harness may
+    // reduce. Kept separate so neither notice can be mistaken for the other.
+    const warnAboveEstimate = overrides.onAboveModelEstimate ?? ((message) => console.warn(message));
     const envRaw = overrides.env?.[CONTEXT_WINDOW_TOKENS_ENV_VAR];
     if (envRaw !== undefined) {
         const parsed = parseContextWindowOverride(envRaw);
-        if (parsed !== null)
+        if (parsed !== null) {
+            const above = describeWindowAboveModelEstimate({
+                model,
+                tokens: parsed,
+                pin: `${CONTEXT_WINDOW_TOKENS_ENV_VAR}="${String(envRaw)}"`
+            });
+            if (above !== null)
+                warnAboveEstimate(above);
             return { tokens: parsed, source: 'env-override' };
+        }
         warn(`[peaks] ${CONTEXT_WINDOW_TOKENS_ENV_VAR}="${String(envRaw)}" is not a positive integer — ignoring the override`);
     }
     if (overrides.configWindowTokens !== undefined) {
         const parsed = parseContextWindowOverride(overrides.configWindowTokens);
-        if (parsed !== null)
+        if (parsed !== null) {
+            const above = describeWindowAboveModelEstimate({
+                model,
+                tokens: parsed,
+                pin: `config context.windowTokens=${parsed}`
+            });
+            if (above !== null)
+                warnAboveEstimate(above);
             return { tokens: parsed, source: 'config' };
+        }
         warn(`[peaks] config context.windowTokens=${JSON.stringify(overrides.configWindowTokens)} is not a positive integer — ignoring the override`);
     }
+    if (overrides.harnessWindowTokens !== undefined) {
+        const parsed = parseContextWindowOverride(overrides.harnessWindowTokens);
+        if (parsed !== null)
+            return { tokens: parsed, source: 'harness-env' };
+        warn(`[peaks] harness auto-compact window ${JSON.stringify(overrides.harnessWindowTokens)} is not a positive integer — ignoring the override`);
+    }
     const heuristic = modelContextWindowTokens(model);
     return heuristic === DEFAULT_CONTEXT_WINDOW_TOKENS
         ? { tokens: heuristic, source: 'default' }
@@ -354,11 +453,37 @@ function findLatestTranscriptUsage(filePath) {
  * when the observed token count contradicts the heuristic window (tokens
  * exceed it), the model must be ≥1M, so bump to the 1M window (the late
  * rescue; it keeps the heuristic source tag, only the tokens change).
+ *
+ * `env-override` and `config` are in the no-bump list because a human pinned
+ * them: a pin the probe silently overrules is a setting that does not work.
+ *
+ * `harness-env` is the interesting one, and is decided by PROVENANCE:
+ *
+ *   - peaks-written (`harnessWindowPeakWritten === true`): may be bumped. This
+ *     is the ratchet fix. The value is peaks-loop's own earlier resolution, so
+ *     believing it forever makes a first-time mis-resolution PERMANENT — a
+ *     200_000 default written to disk, re-read as the window, and exempt from
+ *     the very rescue that exists to correct it, leaving the ratio saturated at
+ *     1.0 while the session grows past the pin. Evidence must be able to
+ *     overrule peaks-loop's own output.
+ *   - human-set (false/omitted): NOT bumpable. Here the key is a person's
+ *     explicit declaration — the documented Claude Code variable, hand-edited.
+ *     Overruling it would not be self-correction, it would be peaks-loop
+ *     silently rewriting a setting the user chose (and persisting the rewrite).
+ *
+ * Both branches keep the single-source rule: the resolution this function
+ * returns becomes `probe.capacityTokens`, and the caller syncs exactly that
+ * back into the harness key (`syncHarnessWindowForProject`). When the rescue
+ * fires, the key is refreshed to the bumped number in the same command, so
+ * peaks-loop's ratio and the harness window are one number again — the rescue
+ * never leaves the two sides apart.
  */
 function resolveContextWindowTokens(model, contextTokens, overrides = {}) {
     const resolved = resolveContextWindow(model, overrides);
     if (resolved.source === 'env-override' || resolved.source === 'config')
         return resolved;
+    if (resolved.source === 'harness-env' && overrides.harnessWindowPeakWritten !== true)
+        return resolved;
     return contextTokens > resolved.tokens
         ? { tokens: ONE_MILLION_CONTEXT_TOKENS, source: resolved.source }
         : resolved;
@@ -376,8 +501,9 @@ function resolveContextWindowTokens(model, contextTokens, overrides = {}) {
  * Window model resolution is env-first: when `envModel` is present, its id
  * (which Claude Code stamps with the `[1M]` / `[200K]` suffix) drives the
  * window; otherwise the transcript `message.model` is used. Explicit
- * overrides (env `PEAKS_CONTEXT_WINDOW_TOKENS` / config `context.windowTokens`)
- * sit above both and are reported via `capacitySource`.
+ * overrides (env `PEAKS_CONTEXT_WINDOW_TOKENS` / the harness key peaks-loop
+ * wrote / config `context.windowTokens`) sit above both and are reported via
+ * `capacitySource`.
  */
 function readClaudeTranscriptEstimate(outerSessionId, envModel, overrides = {}) {
     const projectsDir = join(homedir(), '.claude', 'projects');
@@ -426,7 +552,15 @@ function readContextPercentFallback(input) {
         const envModel = resolveClaudeModelFromEnv(input.env);
         const estimate = readClaudeTranscriptEstimate(input.outerSessionId, envModel, {
             env: input.env,
-            configWindowTokens: input.configWindowTokens
+            configWindowTokens: input.configWindowTokens,
+            // Slice 2026-09-13-auto-compact-trigger-ownership: the window
+            // peaks-loop configured for the harness outranks config + heuristic
+            // (see `resolveContextWindow`). The generic reader resolved it from the
+            // adapter's own declarations — this module never names the key.
+            ...(input.harnessWindowTokens !== undefined ? { harnessWindowTokens: input.harnessWindowTokens } : {}),
+            // ...and whether that value is peaks-loop's own output (bumpable) or a
+            // human's pin (not) — see `resolveContextWindowTokens`.
+            ...(input.harnessWindowPeakWritten !== undefined ? { harnessWindowPeakWritten: input.harnessWindowPeakWritten } : {})
         });
         if (estimate !== null) {
             return {
@@ -448,6 +582,11 @@ export const CLAUDE_CODE_ADAPTER = {
     settings: {
         dirName: '.claude',
         settingsFileName: 'settings.json',
+        // The machine-local layer Claude Code merges on top of settings.json.
+        // Declared here so the auto-compact `ide-native` hook writer reads the
+        // path off the adapter instead of assuming a Claude-specific filename —
+        // see `IdeSettingsLocation.localSettingsFileName`.
+        localSettingsFileName: 'settings.local.json',
         resolveSettingsFile: (scope, projectRoot) => {
             const root = scope === 'global' ? homedir() : resolve(projectRoot ?? homedir());
             return join(root, '.claude', 'settings.json');
@@ -497,6 +636,14 @@ export const CLAUDE_CODE_ADAPTER = {
         compactCommand: 'claude --compact',
         compactPathway: 'ide-native',
         postCompactDetectCommand: 'peaks code auto-compact --json',
+        // Slice 2026-09-13-auto-compact-trigger-ownership: the key Claude Code
+        // reads its auto-compact WINDOW from, in the machine-local `env` block.
+        // Claude Code documents it as taking precedence "over the command, the
+        // flag, and the setting", and as accepting the plain token count only
+        // (no `500k` suffix). peaks-loop writes the window it computes the ratio
+        // against here so the two sides cannot drift; see
+        // `harness-window-config.ts`.
+        autoCompactWindowEnvVar: 'CLAUDE_CODE_AUTO_COMPACT_WINDOW',
         readContextPercentFallback,
         // Slice 2026-09-10-context-audit-and-discipline (Slice A): the vendor
         // layout knowledge (`~/.claude/projects/**/<outerSessionId>.jsonl`)

package/dist/services/ide/ide-registry.d.ts

@@ -1,6 +1,18 @@
 import type { IdeAdapter, IdeId } from './ide-types.js';
 /** Get the adapter for a given IDE id. Throws on unsupported IDE. */
 export declare function getAdapter(ide: IdeId): IdeAdapter;
+/**
+ * Non-throwing twin of `getAdapter`. Returns `undefined` for an id with
+ * no registered adapter instead of raising.
+ *
+ * For callers that hold an IDE-shaped string which is NOT guaranteed to
+ * be an `IdeId`: `detectIdeFromEnv` returns `IdeKind` (`'claude-code' |
+ * 'trae' | 'opencode' | 'unknown'`), and `'opencode'` has no adapter
+ * registered. Casting to `IdeId` and calling `getAdapter` would throw
+ * inside a pure formatting/threshold path — the caller wants "no
+ * adapter → fall back", not an exception.
+ */
+export declare function tryGetAdapter(ide: string): IdeAdapter | undefined;
 /** All registered adapter ids (insertion order). */
 export declare function listAdapterIds(): readonly IdeId[];
 /** All registered adapters (insertion order). */

package/dist/services/ide/ide-registry.js

@@ -39,6 +39,20 @@ export function getAdapter(ide) {
     }
     return adapter;
 }
+/**
+ * Non-throwing twin of `getAdapter`. Returns `undefined` for an id with
+ * no registered adapter instead of raising.
+ *
+ * For callers that hold an IDE-shaped string which is NOT guaranteed to
+ * be an `IdeId`: `detectIdeFromEnv` returns `IdeKind` (`'claude-code' |
+ * 'trae' | 'opencode' | 'unknown'`), and `'opencode'` has no adapter
+ * registered. Casting to `IdeId` and calling `getAdapter` would throw
+ * inside a pure formatting/threshold path — the caller wants "no
+ * adapter → fall back", not an exception.
+ */
+export function tryGetAdapter(ide) {
+    return ADAPTERS.get(ide);
+}
 /** All registered adapter ids (insertion order). */
 export function listAdapterIds() {
     return Array.from(ADAPTERS.keys());

package/dist/services/ide/ide-types.d.ts

@@ -25,6 +25,20 @@ export interface IdeSettingsLocation {
     readonly dirName: string;
     /** settings 文件名(部分 IDE 叫 settings.json / mcp.json) */
     readonly settingsFileName: string;
+    /**
+     * 该 IDE 的**机器本地** settings 层文件名(Claude Code = `settings.local.json`),
+     * 与 `settingsFileName` 同目录、通常被 gitignore,IDE 读取时叠加在其上。
+     * `undefined` = 该 IDE 没有这一层;调用方此时回落到自己的默认值。
+     *
+     * peaks-loop 只在"写进去的东西是机器相关"时用这一层 —— 例如 per-OS 的
+     * hook shell shim —— 绝不写进共享的 `settingsFileName`。写 hook 的调用方
+     * (auto-compact 的 `ide-native` 通路)因此不需要知道任何 IDE 的目录/文件名,
+     * 只读适配器声明的这两个字段。
+     *
+     * 可选:既有适配器无需改动;声明了 `compactPathway: 'ide-native'` 的适配器
+     * 应当一并声明此字段,否则会落到调用方的 claude-code 默认路径。
+     */
+    readonly localSettingsFileName?: string;
     /** 解析出 settings.json 绝对路径 */
     resolveSettingsFile(scope: 'project' | 'global', projectRoot: string | undefined): string;
     /** 该 IDE 是否支持此 scope(用于清晰报错) */
@@ -178,6 +192,13 @@ export interface IdeCompactProfile {
      * Slash command or shell-call to invoke compact. The orchestrator
      * spawns this via `child_process.spawn` (shell-exec pathway) or
      * writes it to an IDE hook file (ide-native pathway).
+     *
+     * ZERO EXECUTOR as of slice 2026-09-13-auto-compact-trigger-ownership: every
+     * `shell-exec` branch now only REPORTS that it will not spawn (see
+     * `auto-compact-dispatcher.ts`), and the `ide-native` branch registers a
+     * harness-side trigger instead. The field is retained because the sibling
+     * work (A2, harness-side state re-injection) still needs it; nothing in this
+     * slice deletes it. Do not read it as a capability peaks-loop has.
      */
     readonly compactCommand: string;
     /**
@@ -195,6 +216,19 @@ export interface IdeCompactProfile {
      *          adapters still on the v2.11.x model).
      */
     readonly compactPathway: 'shell-exec' | 'ide-native' | 'llm-self-compress' | 'noop';
+    /**
+     * Optional settings key / env var the IDE reads its AUTO-COMPACT WINDOW
+     * from — i.e. the window the harness itself compacts against. When
+     * declared, peaks-loop writes the window it computes its ratio against
+     * into the adapter's machine-local settings `env` block, under this key,
+     * so both sides reference one number instead of two independent
+     * resolutions (slice 2026-09-13-auto-compact-trigger-ownership).
+     *
+     * `undefined` = this IDE exposes no such knob. peaks-loop then cannot
+     * close the drift; `peaks compact harness-window` reports that instead of
+     * pretending. Adapters that do not opt in are unchanged.
+     */
+    readonly autoCompactWindowEnvVar?: string;
     /**
      * Optional command the runner invokes post-compact to confirm
      * ratio dropped (e.g. `peaks code auto-compact --json`). When omitted,
@@ -263,6 +297,31 @@ export interface ContextPercentFallbackInput {
      * Slice 2026-09-09-context-window-override.
      */
     readonly configWindowTokens?: unknown;
+    /**
+     * Raw value of the adapter's `autoCompactWindowEnvVar`, resolved by the
+     * generic reader from the adapter's own declarations (settings path +
+     * key name) — the window peaks-loop configured for the harness. Feeds the
+     * `harness-env` layer of `resolveContextWindow`.
+     *
+     * Slice 2026-09-13-auto-compact-trigger-ownership.
+     */
+    readonly harnessWindowTokens?: unknown;
+    /**
+     * True when `harnessWindowTokens` is a value peaks-loop ITSELF wrote (the
+     * harness settings carry the provenance marker matching it), false when a
+     * human set the key by hand.
+     *
+     * The `harness-env` layer outranks the model heuristic either way — that is
+     * what keeps peaks-loop's ratio and the harness's trigger on one number. The
+     * flag decides only whether the late 1M rescue may OVERRULE that layer when
+     * the observed context proves it too small: peaks-loop's own earlier
+     * resolution is self-correcting, whereas a human's explicit pin must not be
+     * silently rewritten (and, since it is persisted, permanently so).
+     *
+     * Omitted = treated as not peaks-written (the safe direction: do not touch
+     * what you did not write).
+     */
+    readonly harnessWindowPeakWritten?: boolean;
 }
 /**
  * Per-IDE standards-file location + format profile. Used by the

package/dist/services/lint/detect-eslint.js

@@ -20,7 +20,7 @@ function packageNameFor(key) {
 }
 function probeNpx() {
     const { command, args, baseEnv } = resolveNpxInvocation(['--version']);
-    const probe = spawnSync(command, args, { encoding: 'utf8', env: baseEnv });
+    const probe = spawnSync(command, args, { encoding: 'utf8', env: baseEnv, windowsHide: true });
     return probe.status === 0;
 }
 /** Named code for "npm itself could not be launched" — distinct from a registry miss. */
@@ -35,7 +35,7 @@ function probePackage(key) {
     // own JS entry and this runs it through `process.execPath`. Same shape as the
     // npx probe above and as `eslint-runner.ts`.
     const { command, args, baseEnv } = resolveNpmInvocation(['view', `${pkg}@${pin}`, 'version']);
-    const result = spawnSync(command, args, { encoding: 'utf8', env: baseEnv });
+    const result = spawnSync(command, args, { encoding: 'utf8', env: baseEnv, windowsHide: true });
     return {
         ok: result.status === 0,
         error: result.error === undefined || result.error === null ? null : result.error.message

package/dist/services/lint/eslint-runner.js

@@ -91,7 +91,8 @@ function loadDiffRanges(cwd) {
         const result = spawnSync('git', ['diff', 'HEAD', '--unified=0', '--no-color'], {
             cwd,
             encoding: 'utf8',
-            maxBuffer: DIFF_BUFFER_BYTES
+            maxBuffer: DIFF_BUFFER_BYTES,
+            windowsHide: true
         });
         if (result.status !== 0 || typeof result.stdout !== 'string')
             return [];
@@ -260,6 +261,7 @@ export function runEslint(options) {
     const spawnOptions = {
         cwd: projectRoot,
         encoding: 'utf8',
+        windowsHide: true,
         timeout: options.timeoutMs ?? ESLINT_DEFAULT_TIMEOUT_MS,
         maxBuffer: OUTPUT_BUFFER_BYTES
     };

package/dist/services/loop/evaluator-dispatcher.js

@@ -60,7 +60,8 @@ function execPeaks(args, cwd, peaksBin) {
         const stdout = execFileSync(cmd[0], [...cmd.slice(1), ...args], {
             cwd,
             stdio: ['ignore', 'pipe', 'ignore'],
-            encoding: 'utf8'
+            encoding: 'utf8',
+            windowsHide: true
         });
         return { stdout, exitCode: 0 };
     }

package/dist/services/memory/project-memory-service/index/kind-dispatch.js

@@ -136,7 +136,7 @@ export function executeProjectMemoryBackup(options) {
         const safeMemoryDir = assertSafeProjectMemoryDir(plan.projectRoot);
         mkdirSync(plan.backupMemoryDir, { recursive: true });
         for (const copy of plan.plannedCopies) {
-            const sourcePath = realPathOrThrow(copy.sourcePath, 'Project memory source must stay inside the project memory directory');
+            const sourcePath = realPathOrThrow(copy.sourcePath, 'Project memory source must stay inside the project memory directory', 'Project memory source does not exist');
             if (!isInsidePath(sourcePath, stableRealPath(safeMemoryDir))) {
                 throw new Error('Project memory source must stay inside the project memory directory');
             }

package/dist/services/memory/project-memory-service/store/paths.d.ts

@@ -1,6 +1,14 @@
 export declare function normalizeRoot(path: string): string;
 export declare function normalizeRealRoot(path: string): string;
-export declare function realPathOrThrow(path: string, errorMessage: string): string;
+/**
+ * Resolve `path` to its realpath, refusing missing paths and symlinks.
+ *
+ * `missingPathMessage` is required because the two refusals mean different
+ * things to the user: "there is nothing at this path" is a caller typo, while
+ * "this path is a symlink" is an escape attempt. A single shared message made
+ * `peaks memory extract --artifact <typo>` report a sandbox-escape warning.
+ */
+export declare function realPathOrThrow(path: string, errorMessage: string, missingPathMessage: string): string;
 export declare function resolveProjectPath(path: string, projectRoot: string): string;
 export declare function assertInsideProject(path: string, projectRoot: string): string;
 export declare function assertSafeProjectMemoryDir(projectRoot: string): string;

package/dist/services/memory/project-memory-service/store/paths.js

@@ -8,8 +8,9 @@
 //     canonical form the rest of the codebase expects (handles input-path
 //     quirks from the path-utils layer).
 //   - `realPathOrThrow` — refuses symlinks and missing paths. Throws with
-//     a stable message so callers can distinguish "missing" from "escape
-//     attempt".
+//     a stable, path-free message, and takes ONE MESSAGE PER REASON, so
+//     callers can distinguish "missing" from "escape attempt" by the
+//     message they supplied.
 //   - `assertInsideProject` — confirms an artifact path resolves inside
 //     the project root after realpath, throwing the same kind of error
 //     message realPathOrThrow uses.
@@ -32,9 +33,17 @@ export function normalizeRoot(path) {
 export function normalizeRealRoot(path) {
     return stableRealPath(path);
 }
-export function realPathOrThrow(path, errorMessage) {
+/**
+ * Resolve `path` to its realpath, refusing missing paths and symlinks.
+ *
+ * `missingPathMessage` is required because the two refusals mean different
+ * things to the user: "there is nothing at this path" is a caller typo, while
+ * "this path is a symlink" is an escape attempt. A single shared message made
+ * `peaks memory extract --artifact <typo>` report a sandbox-escape warning.
+ */
+export function realPathOrThrow(path, errorMessage, missingPathMessage) {
     if (!existsSync(path)) {
-        throw new Error(errorMessage);
+        throw new Error(missingPathMessage);
     }
     const stats = lstatSync(path);
     if (stats.isSymbolicLink()) {
@@ -53,8 +62,8 @@ export function resolveProjectPath(path, projectRoot) {
 export function assertInsideProject(path, projectRoot) {
     const resolvedRoot = normalizeRoot(projectRoot);
     const resolvedPath = resolveProjectPath(path, resolvedRoot);
-    const realProjectRoot = realPathOrThrow(resolvedRoot, 'Project root is not accessible');
-    const realArtifactPath = realPathOrThrow(resolvedPath, 'Artifact path must stay inside the project root');
+    const realProjectRoot = realPathOrThrow(resolvedRoot, 'Project root is not accessible', 'Project root does not exist');
+    const realArtifactPath = realPathOrThrow(resolvedPath, 'Artifact path must stay inside the project root', 'Artifact path does not exist');
     if (!isInsidePath(realArtifactPath, realProjectRoot)) {
         throw new Error('Artifact path must stay inside the project root');
     }

package/dist/services/prd/best-practice-auto-trigger.js

@@ -105,6 +105,7 @@ export async function triggerBestPracticeScan(opts) {
             cwd: opts.projectRoot,
             stdio: 'ignore',
             detached: true,
+            windowsHide: true,
             env: { ...process.env, PEAKS_BEST_PRACTICE_STDIN: '' }
         });
         child.once('error', (err) => {

package/dist/services/release/version-precheck-service.d.ts

@@ -34,7 +34,8 @@ export interface PrecheckOptions {
 export interface PrecheckEnvelope {
     readonly ok: boolean;
     readonly overall: LayerStatus;
-    readonly rootVersion: string;
+    /** `null` when the root `package.json` is missing or unreadable — see `rootVsShared`. */
+    readonly rootVersion: string | null;
     readonly strict: boolean;
     readonly snapshotAt: string;
     readonly layers: {