peaks-loop 4.0.45 → 4.0.47

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;

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

@@ -14,22 +14,28 @@
  *                                toolkit is "ready to use" so the
  *                                LLM doesn't lose context to a
  *                                last-second `/compact` panic.
- *   - 95%  RED LINE           — peaks-loop refuses to dispatch any
- *                                further sub-agent and synchronously
- *                                triggers IDE-side compact. At 95%+
- *                                the context window is too tight to
- *                                continue safely; the LLM cannot
- *                                opt out. This is the compact red
- *                                line that guarantees the LLM-runner
- *                                keeps working with context < 95%.
+ *   - 95%  RED LINE           — peaks-loop asks the harness to
+ *                                compact and says it is waiting.
+ *                                Nothing is blocked: peaks-loop has
+ *                                no executor for a running session,
+ *                                so it cannot gate dispatch — and
+ *                                claiming to was the deadlock. See
+ *                                the correction note below.
  *
  * Why 0.85 / 0.95 split: the LLM uses the 0.85–0.95 zone to do
  * intelligent convergence — wait for in-flight sub-agents, finish
  * the current todo row, persist a checkpoint, then compact. peaks-loop
- * provides the toolkit; the LLM picks the moment. At 0.95 the window
- * is gone and peaks-loop takes over synchronously to keep the runner
- * alive.
+ * provides the toolkit; the LLM picks the moment. At 0.95 peaks-loop
+ * requests the compact outright and says it is waiting.
+ *
+ * Slice 2026-09-13-auto-compact-trigger-ownership corrected two claims that
+ * used to head this file: the red line does NOT "refuse to dispatch any
+ * further sub-agent" (peaks-loop has no way to compact a running session, so
+ * such a refusal gated nothing and deadlocked the runner), and the window
+ * these ratios divide by is now the same one peaks-loop configures for the
+ * harness — see `harness-window-config.ts`.
  */
+import type { HarnessWindowSyncResult } from './harness-window-config.js';
 export declare const AUTO_COMPACT_SOFT_WARN_RATIO = 0.5;
 export declare const AUTO_COMPACT_AUTO_FIRE_RATIO = 0.8;
 export declare const AUTO_COMPACT_PRE_COMPACT_RATIO = 0.85;
@@ -67,7 +73,10 @@ export type CompactTrigger = {
     message: string;
     toolkitReady: true;
 }
-/** Red line (ratio ≥ 0.95): peaks-loop forces synchronous compact; LLM cannot opt out. */
+/**
+ * Red line (ratio ≥ 0.95): peaks-loop asks the harness to compact and says
+ * it is waiting. Dispatch is NOT blocked — see `redLineRequested`.
+ */
  | {
     kind: 'red-line';
     ratio: number;
@@ -97,6 +106,20 @@ export interface CompactDispatchResult {
     readonly pathway: 'ide-native' | 'llm-self-compress' | 'shell-exec' | 'noop';
     readonly message: string;
 }
+/**
+ * Old → new map of envelope fields that were renamed but are still emitted
+ * under their old name as deprecated aliases.
+ *
+ * One definition, used both as the `deprecatedFields` value the envelopes
+ * carry and as the registry the type's `@deprecated` tags describe, so the
+ * alias and its record cannot drift apart into two lists.
+ *
+ * `redLineGated` → `redLineRequested` (slice
+ * 2026-09-13-auto-compact-trigger-ownership): nothing was ever gated. See
+ * `redLineGated` on the dispatch branches for why the alias is kept rather
+ * than deleted.
+ */
+export declare const DEPRECATED_ENVELOPE_FIELDS: Readonly<Record<string, string>>;
 /** Final envelope returned by `runAutoCompact`. */
 export type AutoCompactResult = {
     readonly ok: false;
@@ -112,6 +135,13 @@ export type AutoCompactResult = {
         readonly ratio: number;
         readonly source: string;
         readonly decision: 'below-threshold' | 'in-flight-batch';
+        /**
+         * Slice 2026-09-13-auto-compact-trigger-ownership: what syncing the
+         * harness auto-compact window did on this probe. `null` = the active
+         * adapter declares no such knob. Present so the write is VISIBLE —
+         * the harness reports an override silently, so peaks-loop must not.
+         */
+        readonly harnessWindow?: HarnessWindowSyncResult | null;
     };
 } | {
     readonly ok: boolean;
@@ -139,7 +169,54 @@ export type AutoCompactResult = {
          * caller passes `--mode partial`.
          */
         readonly mode?: 'standard' | 'partial';
+        /**
+         * True when the ratio had crossed the red line and peaks-loop asked
+         * the harness to compact.
+         *
+         * Renamed from `redLineGated` in slice
+         * 2026-09-13-auto-compact-trigger-ownership: nothing is gated. The
+         * old name asserted a block peaks-loop cannot enforce (it has no
+         * executor for a running session), and acting on that assertion is
+         * what deadlocked the runner.
+         */
+        readonly redLineRequested?: boolean;
+        /**
+         * Deprecated alias of `redLineRequested` — same value, written by the
+         * same statement, so the two can never disagree.
+         *
+         * Kept because the old name SHIPPED: `redLineGated` is in every release
+         * from 2.13.0 through 4.0.46, so a script outside this repo that reads
+         * it exists in the wild. Dropping the key would hand that script
+         * `undefined` instead of the boolean it branches on — no error, no log,
+         * just a silently different branch. This is the same call this slice
+         * already made for `--bypass-red-line`: stop advertising a
+         * wrong-named surface, do not delete it out from under a published
+         * caller. That flag is likewise kept with nothing reading it.
+         *
+         * There is deliberately NO removal date here. A date would be a promise
+         * with no mechanism behind it; removing a published field is a MAJOR
+         * decision to be taken on purpose, not one this comment can schedule.
+         *
+         * `deprecatedFields` (below) is the part a runtime consumer can
+         * actually see — a `@deprecated` tag is not.
+         */
         readonly redLineGated?: boolean;
+        /**
+         * Old → new map of the envelope fields still emitted as deprecated
+         * aliases, so a consumer that parses JSON can discover the rename
+         * without reading this file.
+         *
+         * Why it has to exist: the consumers a rename breaks are precisely the
+         * ones that never read `auto-compact-types.ts`. A type comment reaches
+         * the compiler and the next editor, not a script parsing a CLI
+         * envelope, which is what made the rename silent in the first place.
+         * This puts the fact in the envelope they already read.
+         *
+         * Absent on the branches that carry no renamed field.
+         */
+        readonly deprecatedFields?: Readonly<Record<string, string>>;
+        /** See the `AUTO_COMPACT_SKIP` data shape above. */
+        readonly harnessWindow?: HarnessWindowSyncResult | null;
     };
 };
 /**

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

@@ -1,35 +1,3 @@
-/**
- * Auto-compact shared types (v2.13.0 AC-1..AC-4).
- *
- * Two-tier threshold model — peaks-loop is project-aware and the LLM
- * is the decision-maker:
- *
- *   - 50%  soft warn          — log a one-line info row; continue.
- *   - 85%  pre-compact zone   — peaks-loop prepares the convergence
- *                                toolkit (checkpoint + convergence
- *                                plan + auto-decisions log +
- *                                IDE-compact dispatcher). The LLM
- *                                DECIDES when (or whether) to fire
- *                                compact during this zone. The
- *                                toolkit is "ready to use" so the
- *                                LLM doesn't lose context to a
- *                                last-second `/compact` panic.
- *   - 95%  RED LINE           — peaks-loop refuses to dispatch any
- *                                further sub-agent and synchronously
- *                                triggers IDE-side compact. At 95%+
- *                                the context window is too tight to
- *                                continue safely; the LLM cannot
- *                                opt out. This is the compact red
- *                                line that guarantees the LLM-runner
- *                                keeps working with context < 95%.
- *
- * Why 0.85 / 0.95 split: the LLM uses the 0.85–0.95 zone to do
- * intelligent convergence — wait for in-flight sub-agents, finish
- * the current todo row, persist a checkpoint, then compact. peaks-loop
- * provides the toolkit; the LLM picks the moment. At 0.95 the window
- * is gone and peaks-loop takes over synchronously to keep the runner
- * alive.
- */
 export const AUTO_COMPACT_SOFT_WARN_RATIO = 0.5;
 // Part 22: auto-fire threshold (was 0.85 pre-compact zone where
 // the LLM had to decide; LLM misjudged 0.85–0.95 and only fired
@@ -41,3 +9,19 @@ export const AUTO_COMPACT_AUTO_FIRE_RATIO = 0.80;
 export const AUTO_COMPACT_PRE_COMPACT_RATIO = 0.85;
 export const AUTO_COMPACT_RED_LINE_RATIO = 0.95;
 export const AUTO_COMPACT_THRESHOLD_RATIO = AUTO_COMPACT_AUTO_FIRE_RATIO;
+/**
+ * Old → new map of envelope fields that were renamed but are still emitted
+ * under their old name as deprecated aliases.
+ *
+ * One definition, used both as the `deprecatedFields` value the envelopes
+ * carry and as the registry the type's `@deprecated` tags describe, so the
+ * alias and its record cannot drift apart into two lists.
+ *
+ * `redLineGated` → `redLineRequested` (slice
+ * 2026-09-13-auto-compact-trigger-ownership): nothing was ever gated. See
+ * `redLineGated` on the dispatch branches for why the alias is kept rather
+ * than deleted.
+ */
+export const DEPRECATED_ENVELOPE_FIELDS = {
+    redLineGated: 'redLineRequested'
+};