peaks-loop 4.2.4 → 4.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "metadata": {
3
3
  "pluginRoot": ".",
4
- "version": "4.2.4"
4
+ "version": "4.2.6"
5
5
  },
6
6
  "plugins": [
7
7
  {
8
8
  "name": "peaks-loop",
9
9
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
10
- "version": "4.2.4",
10
+ "version": "4.2.6",
11
11
  "author": {
12
12
  "name": "SquabbyZ"
13
13
  },
package/CHANGELOG.md CHANGED
@@ -1,5 +1,88 @@
1
1
  # Changelog
2
2
 
3
+ ## 4.2.6 — 2026-11-22(默认压缩窗口 250K → 1M:交给 harness 按模型上下文钳制)
4
+
5
+ **版本级别**:**patch**(只改一个默认常量及其文档注释;无新能力,无 schema 变更,无门禁阈值放宽)。
6
+
7
+ **一句话:`workspace init` 的默认窗口从 `250000` 改成 `1000000`——这是 harness 接受的上限,会被 harness 钳制到模型的真实上下文,因此同一个默认对 1M 模型等于 800K 触发,对 200K 模型等于 160K。**
8
+
9
+ ### 1. 为什么改
10
+
11
+ Claude Code 会把 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 钳制到模型自身的上下文。本机实测结果:
12
+
13
+ | 模型 | 配置窗口 | `effectiveWindow` | 80% 触发阈值 |
14
+ |---|---|---|---|
15
+ | 1M(默认) | 1,000,000 | 980,000 | **800,000** |
16
+ | 200K(`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`) | 1,000,000 | 180,000 | **160,000** |
17
+
18
+ 也就是说 `window = 1,000,000` 对**任何**模型都表现为「真实容量的 80%」,而旧默认 `250,000` 把 1M 模型硬压在 25%、在 200,000 就触发压缩——远早于用户预期。1,000,000 正是 harness 文档波段(100,000..1,000,000)的上限,所以它才是最中性的默认值。
19
+
20
+ ### 2. 改了什么
21
+
22
+ - `DEFAULT_HARNESS_COMPACT_WINDOW_TOKENS`:`250_000` → `1_000_000`(`src/services/context/harness-compact-threshold-config.ts`)。
23
+ - `DEFAULT_HARNESS_COMPACT_PERCENT` 保持 `80`。
24
+ - 常量文档注释写明钳制实测与上表数值。
25
+
26
+ ### 3. 影响面
27
+
28
+ - 全新项目跑 `peaks workspace init`,`.claude/settings.local.json` 现在写入 `CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000` 与 `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80`(各带 provenance 标记)。
29
+ - 已有项目不会被改写:init 只在槽位为空时填默认值。本仓库自己的 `.claude/settings.local.json` 已是 `1000000`,实测 init 后文件字节不变。
30
+ - 仍需固定窗口的项目照旧直接编辑该文件。
31
+
32
+ ### 4. 验证
33
+
34
+ | 项 | 结果 |
35
+ |---|---|
36
+ | `tsc -p tsconfig.json --noEmit` | 0 |
37
+ | `node .husky/peaks-gate.mjs repo` | 0 |
38
+ | 单元测试(`tests/unit/` 全量) | 705 文件 / 7623 通过 / 0 失败 |
39
+ | 变异(6 模块) | 90.57%,`passed: true`(最低单模块 85.66%) |
40
+ | 全新 git 项目 `workspace init` | 写入 `CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000` 与 `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80` |
41
+ | 本仓库现有 settings 上重跑 init | 文件字节不变 |
42
+
43
+ ## 4.2.5 — 2026-11-22(修 4.2.4 的严重缺陷:探针会把项目窗口覆盖回 1M)
44
+
45
+ **版本级别**:**patch**(只修缺陷,无新能力,无 schema 变更,无门禁阈值放宽)。
46
+
47
+ **一句话:4.2.4 配好的 250K 窗口,会被一次普通的 `peaks code context-now` 悄悄改回 1M——因为"晚到 1M 救援"把观察值当成了配置。**
48
+
49
+ ### 1. 缺陷是什么
50
+
51
+ 4.2.4 发布当天的验收测试里发现:
52
+
53
+ ```
54
+ 干净环境 peaks workspace init → 文件 250000 ✅
55
+ 同一项目,会话上下文已超过 250K,跑 context-now → 文件 1000000 ❌
56
+ ```
57
+
58
+ **触发条件比预想的常见**:不是"环境变量不一致",而是**任何一个上下文已经超过配置窗口的会话**,在该项目里跑 peaks 命令都会触发。
59
+
60
+ 机制:当探测到的上下文 token 数超过文件里配置的窗口、且文件是 peaks 自己写的,adapter 会把**计算比例用的分母**抬到 1,000,000(这是既有的"晚到 1M 救援",用来防止比例 > 1 的自锁)。旧代码把这个**观察值也持久化**进了项目文件,于是配置被观察覆盖。
61
+
62
+ ### 2. 修法
63
+
64
+ **文件即配置,探针只是观察。**
65
+
66
+ - `syncHarnessWindowForProject` 传入 `onlyFillEmptySlot`
67
+ - 文件里已有窗口值时,同步以 `file-configures-window` 拒绝写入
68
+ - **救援继续抬比分母**(自锁仍然被打破、比例仍然诚实),只是不再落盘
69
+ - 空槽仍会被首次探针填入;人工设定的值仍不动;显式调用方仍可写
70
+
71
+ **行为变化(需要知道)**:要改项目的窗口,现在是**编辑那个文件**(或删掉该键),而不是靠跑命令。相关提示语已改成这么说。
72
+
73
+ ### 3. 验证
74
+
75
+ | 项 | 结果 |
76
+ |---|---|
77
+ | 单元测试 | 705 文件 / 7623 通过 |
78
+ | `tsc --noEmit` | 0 |
79
+ | `peaks-gate repo` | 0 |
80
+ | 变异(6 模块) | **90.57%**,每个模块 ≥ 80% |
81
+
82
+ ### 4. 另外发现的一个守卫盲区(未在本版修)
83
+
84
+ 子 agent 测试时用非 git 临时目录,工具把根解析成了真实主目录,往 `~/.claude/settings.local.json` 写了两行(已清除并核实)。原因是那次 `USERPROFILE` 被改过,`homedir()` 指向临时目录,而根路径走的是另一条规则——**H1 主目录守卫没有触发**。正常 shell 下会拒绝,但这是一个真实盲区,记入遗留。
85
+
3
86
  ## 4.2.4 — 2026-11-22(下游项目装完即用早期自动压缩,配置只落项目级)
4
87
 
5
88
  **版本级别**:**minor**(新增能力:项目级压缩阈值配置 + `harnessThreshold` 如实上报;无 schema 变更,无门禁阈值放宽)。
@@ -112,7 +112,7 @@ function buildHarnessWindowStateActions(state, percent) {
112
112
  state?.tokens === null || state?.tokens === undefined
113
113
  ? 'No window is set yet. The next `peaks code context-now` probe materializes the window it computes its ratio against.'
114
114
  : `peaks-loop computes its context ratio against ${state.tokens} tokens; the harness fires near the end of that window. ${state.peakWritten
115
- ? 'peaks-loop wrote this value; it may raise it if a session outgrows it.'
115
+ ? 'peaks-loop wrote this value, and it is the project’s configuration: a context probe will not replace it (only an empty slot is filled), so a session that outgrows it is reported, not rewritten.'
116
116
  : "This value is not peaks-loop's own write, so peaks-loop will not raise it — it is treated as your setting."}`,
117
117
  describePercentHalf(percent),
118
118
  'Rollback: `peaks compact harness-window --reset`.',
@@ -54,12 +54,15 @@ export declare function resolveHarnessRatioWindow(state: HarnessWindowReadResult
54
54
  /**
55
55
  * Materialize a window into the harness's own settings, so the number
56
56
  * peaks-loop divides by and the number the harness compacts against are one
57
- * value rather than two resolutions (slice
57
+ * value rather than two resolutions.
58
58
  *
59
- * The caller passes the denominator it JUST USED (`probe.capacityTokens`), not
60
- * a re-derived one — that is what makes the two sides structurally identical.
61
- * `tokens: null` (a percent-only probe carries no token window) is a
62
- * deliberate no-op: peaks-loop never invents a window it did not measure.
59
+ * A PROBE MAY ONLY FILL AN EMPTY SLOT. The project's settings file is its
60
+ * configuration; the probe's window is an observation (it may be shaped by an
61
+ * ambient process env or by a transcript inherited from another session), so a
62
+ * value the file already carries is never replaced — see
63
+ * `syncHarnessWindow`'s `onlyFillEmptySlot` and the `file-configures-window`
64
+ * result. `tokens: null` (a percent-only probe carries no token window) is
65
+ * likewise a no-op: peaks-loop never invents a window it did not measure.
63
66
  *
64
67
  * Returns `null` when the active adapter declares no window knob at all.
65
68
  */
@@ -114,12 +114,15 @@ export function resolveHarnessRatioWindow(state) {
114
114
  /**
115
115
  * Materialize a window into the harness's own settings, so the number
116
116
  * peaks-loop divides by and the number the harness compacts against are one
117
- * value rather than two resolutions (slice
117
+ * value rather than two resolutions.
118
118
  *
119
- * The caller passes the denominator it JUST USED (`probe.capacityTokens`), not
120
- * a re-derived one — that is what makes the two sides structurally identical.
121
- * `tokens: null` (a percent-only probe carries no token window) is a
122
- * deliberate no-op: peaks-loop never invents a window it did not measure.
119
+ * A PROBE MAY ONLY FILL AN EMPTY SLOT. The project's settings file is its
120
+ * configuration; the probe's window is an observation (it may be shaped by an
121
+ * ambient process env or by a transcript inherited from another session), so a
122
+ * value the file already carries is never replaced — see
123
+ * `syncHarnessWindow`'s `onlyFillEmptySlot` and the `file-configures-window`
124
+ * result. `tokens: null` (a percent-only probe carries no token window) is
125
+ * likewise a no-op: peaks-loop never invents a window it did not measure.
123
126
  *
124
127
  * Returns `null` when the active adapter declares no window knob at all.
125
128
  */
@@ -127,7 +130,12 @@ export function syncHarnessWindowForProject(input) {
127
130
  const location = resolveHarnessWindowLocation(input);
128
131
  if (location === null)
129
132
  return null;
130
- return syncHarnessWindow({ location, tokens: input.tokens, env: input.env ?? process.env });
133
+ return syncHarnessWindow({
134
+ location,
135
+ tokens: input.tokens,
136
+ env: input.env ?? process.env,
137
+ onlyFillEmptySlot: true
138
+ });
131
139
  }
132
140
  /**
133
141
  * Read env-var-based context percentage. Returns `null` when the env
@@ -34,17 +34,18 @@ import { type HarnessPercentOwnership } from './harness-percent-ownership.js';
34
34
  /**
35
35
  * The window peaks-loop configures when nobody has said otherwise.
36
36
  *
37
- * 250_000 is the value the user calibrated on 2026-11-20
38
- * (`CLAUDE_CODE_AUTO_COMPACT_WINDOW=250000` + 80% → a 200_000-token trigger),
39
- * and it is the one the harness accepts as a plain token count inside its
40
- * documented 100_000..1_000_000 band. A fresh downstream project gets THIS
41
- * rather than an unset slot, because an unset slot means "no early compaction
42
- * at all" — the state this slice exists to end.
37
+ * 1_000_000 is the harness's accepted MAXIMUM (band 100_000..1_000_000), and
38
+ * that is why it is the neutral default: the harness CLAMPS the window to the
39
+ * model's own context, so the maximum means "as much as this model holds".
40
+ * Measured 2026-11-22: a 1M model gets effectiveWindow 980_000 → threshold
41
+ * 800_000; a 200K model given the same window is clamped to 180_000 → 160_000.
42
+ * The old 250_000 default capped a 1M model at 25% and fired at 200_000. A
43
+ * fresh project gets THIS rather than an unset slot ("no early compaction").
43
44
  */
44
- export declare const DEFAULT_HARNESS_COMPACT_WINDOW_TOKENS = 250000;
45
+ export declare const DEFAULT_HARNESS_COMPACT_WINDOW_TOKENS = 1000000;
45
46
  /**
46
47
  * The percent peaks-loop configures when nobody has said otherwise — 80% of
47
- * the window above, i.e. a 200_000-token trigger on a 250_000 window.
48
+ * the window above, i.e. an 800_000-token trigger on the 1_000_000 default.
48
49
  *
49
50
  * The single named default, exported here and nowhere else.
50
51
  */
@@ -39,17 +39,18 @@ import { HARNESS_PERCENT_WRITTEN_KEY, boundedRawNote, isHarnessPercentPeaksOwned
39
39
  /**
40
40
  * The window peaks-loop configures when nobody has said otherwise.
41
41
  *
42
- * 250_000 is the value the user calibrated on 2026-11-20
43
- * (`CLAUDE_CODE_AUTO_COMPACT_WINDOW=250000` + 80% → a 200_000-token trigger),
44
- * and it is the one the harness accepts as a plain token count inside its
45
- * documented 100_000..1_000_000 band. A fresh downstream project gets THIS
46
- * rather than an unset slot, because an unset slot means "no early compaction
47
- * at all" — the state this slice exists to end.
42
+ * 1_000_000 is the harness's accepted MAXIMUM (band 100_000..1_000_000), and
43
+ * that is why it is the neutral default: the harness CLAMPS the window to the
44
+ * model's own context, so the maximum means "as much as this model holds".
45
+ * Measured 2026-11-22: a 1M model gets effectiveWindow 980_000 → threshold
46
+ * 800_000; a 200K model given the same window is clamped to 180_000 → 160_000.
47
+ * The old 250_000 default capped a 1M model at 25% and fired at 200_000. A
48
+ * fresh project gets THIS rather than an unset slot ("no early compaction").
48
49
  */
49
- export const DEFAULT_HARNESS_COMPACT_WINDOW_TOKENS = 250_000;
50
+ export const DEFAULT_HARNESS_COMPACT_WINDOW_TOKENS = 1_000_000;
50
51
  /**
51
52
  * The percent peaks-loop configures when nobody has said otherwise — 80% of
52
- * the window above, i.e. a 200_000-token trigger on a 250_000 window.
53
+ * the window above, i.e. an 800_000-token trigger on the 1_000_000 default.
53
54
  *
54
55
  * The single named default, exported here and nowhere else.
55
56
  */
@@ -30,9 +30,10 @@ export interface HarnessCompactThresholdResult {
30
30
  * resolves to the value already in the file when there is one and to the
31
31
  * default only when the slot is empty. Init carries no new MEASUREMENT, so
32
32
  * rewriting an existing value from it would be peaks-loop overruling its own
33
- * probe with a policy constant — this repository's own file holds a
34
- * peaks-written 1M window that a 250_000 default must not cut down on every
35
- * init. An explicit argument (`number`), or `null` for "do not manage this one
33
+ * probe with a policy constant — an existing peaks-written value stands even
34
+ * when the current default differs, and this repository's own file is the
35
+ * shape that rule protects. An explicit argument (`number`), or `null` for
36
+ * "do not manage this one
36
37
  * on this call", is passed through as given (the provenance and band gates
37
38
  * still apply).
38
39
  *
@@ -40,9 +40,10 @@ function resolveEnsured(arg, fileRaw, parse, fallback) {
40
40
  * resolves to the value already in the file when there is one and to the
41
41
  * default only when the slot is empty. Init carries no new MEASUREMENT, so
42
42
  * rewriting an existing value from it would be peaks-loop overruling its own
43
- * probe with a policy constant — this repository's own file holds a
44
- * peaks-written 1M window that a 250_000 default must not cut down on every
45
- * init. An explicit argument (`number`), or `null` for "do not manage this one
43
+ * probe with a policy constant — an existing peaks-written value stands even
44
+ * when the current default differs, and this repository's own file is the
45
+ * shape that rule protects. An explicit argument (`number`), or `null` for
46
+ * "do not manage this one
46
47
  * on this call", is passed through as given (the provenance and band gates
47
48
  * still apply).
48
49
  *
@@ -1,27 +1,16 @@
1
1
  /**
2
2
  * Harness auto-compact window ownership
3
3
  *
4
- * The goal (user's words): *when* to trigger auto-compact must be
5
- * peaks-loop's decision; *how* to compact stays the harness's capability.
6
- *
7
- * That only holds if the two sides agree on ONE number. Before this slice
8
- * they each resolved a window independently: Claude Code used the window it
9
- * knows for the model, while peaks-loop divided by `resolveContextWindow()`
10
- * (env → config → model-name heuristic → 200_000 default). A 1M-window model
11
- * whose id the heuristic does not recognise made peaks-loop's "95%" land at
12
- * 190K while the harness waited for ~967K — a 5× early trigger, and (before
13
- * T3) a deadlock, because nothing could lower the ratio.
14
- *
15
- * This module owns the OTHER half: the harness itself accepts a window override
16
- * (`IdeCompactProfile.autoCompactWindowEnvVar`, declared per adapter — no IDE
17
- * names here), so peaks-loop writes the very number it computes the ratio
18
- * against into the harness's own machine-local settings file. Reader and writer
19
- * reference one artifact, not two resolutions that must "remember" to agree.
4
+ * The two sides must agree on ONE number. The harness accepts a window override
5
+ * (`IdeCompactProfile.autoCompactWindowEnvVar`, declared per adapter), so
6
+ * peaks-loop writes the very number it computes its ratio against into the
7
+ * harness's own machine-local settings file. Reader and writer reference one
8
+ * artifact, not two resolutions that must "remember" to agree.
20
9
  *
21
10
  * Vendor neutrality: this module knows about a JSON file with an `env` block
22
11
  * and nothing else. The settings path and the env-var name are BOTH passed in
23
- * by the caller, resolved from the IDE adapter's declarations: no IDE id, no
24
- * `.claude` literal, no registry import.
12
+ * by the caller, from the IDE adapter's declarations: no IDE id, no `.claude`
13
+ * literal, no registry import.
25
14
  */
26
15
  import { isLinkedSettingsFile } from '../ide/shared/safe-path.js';
27
16
  export { isLinkedSettingsFile };
@@ -43,25 +32,13 @@ export declare const HARNESS_WINDOW_SYNC_OPTOUT_VALUE = "off";
43
32
  * Provenance marker: the window value peaks-loop ITSELF last wrote, recorded
44
33
  * in the same `env` block as the window key.
45
34
  *
46
- * Why it must exist. The window key is a SHARED artifact — the harness reads
47
- * it, the user may set it by hand (it is a documented Claude Code variable),
48
- * and peaks-loop writes it. Two rules collide on it:
49
- *
50
- * - the ratio peaks-loop reports must divide by the key (the single-source
51
- * rule), so the key outranks the model heuristic; and
52
- * - a first-time mis-resolution must not become PERMANENT.
53
- *
54
- * The second rule needs the late 1M rescue to be able to overrule the key when
55
- * the observed context proves the key too small. Applied to a value a HUMAN
56
- * pinned, that same rescue would silently destroy an explicit setting — the
57
- * user asks for an early compact, a long session outgrows the pin, and
58
- * peaks-loop rewrites the file to 1M, permanently. Applied to peaks-loop's own
59
- * earlier output it is simply self-correction.
60
- *
61
- * This marker is what tells the two apart: it records what peaks-loop wrote,
62
- * so a mismatch means the human has taken the key over and the rescue must
63
- * stand down. It travels in the same write as the value it describes, so the
64
- * two can never disagree about which write they belong to.
35
+ * The window key is shared — the harness reads it, the user may hand-edit it,
36
+ * and peaks-loop writes it. This marker records what peaks-loop wrote, so a
37
+ * mismatch means the human has taken the key over and the late 1M rescue must
38
+ * stand down. Applied to a human's pin that rescue would silently destroy an
39
+ * explicit setting; applied to peaks-loop's own earlier output it is
40
+ * self-correction. It travels in the same write as the value, so the two can
41
+ * never disagree about which write they belong to.
65
42
  */
66
43
  export declare const HARNESS_WINDOW_WRITTEN_KEY = "PEAKS_HARNESS_WINDOW_WRITTEN";
67
44
  /**
@@ -179,6 +156,13 @@ export interface HarnessWindowSyncResult {
179
156
  * without it a stale process env (or any
180
157
  * re-resolution) silently reverts a human's
181
158
  * hand-edited window and re-claims ownership.
159
+ * - `file-configures-window` — a PROBE-driven call (`onlyFillEmptySlot`)
160
+ * found the file already carrying a value it may
161
+ * not replace. The file is the project's
162
+ * configuration; a probe is an observation and
163
+ * may only FILL an empty slot. Nothing was
164
+ * written; `requestedTokens` vs `previousTokens`
165
+ * names the disagreement the caller must report.
182
166
  * - `symlinked-settings` — the file, or the `.claude` directory holding it,
183
167
  * is a symlink or junction, so a write would
184
168
  * follow it into whatever it points at.
@@ -232,10 +216,10 @@ export interface HarnessWindowSyncResult {
232
216
  *
233
217
  * Reported because "the file already holds the number we wanted" has two very
234
218
  * different meanings and only this flag tells them apart: peaks-loop's own
235
- * earlier output, which it may raise when a session outgrows it, versus a
236
- * value a human pinned, which it never will. Without it, `unchanged` reads as
237
- * "all good" for a key peaks-loop has permanently stopped managing — the
238
- * state a user upgrading from a pre-marker release is silently in.
219
+ * earlier output, which the ratio rescue may use to raise the DENOMINATOR,
220
+ * versus a value a human pinned, which it never will. Without it, `unchanged`
221
+ * reads as "all good" for a key peaks-loop has permanently stopped managing —
222
+ * the state a user upgrading from a pre-marker release is silently in.
239
223
  *
240
224
  * Always `true` for `action: 'written'`: the write that produced the result
241
225
  * is what sets the marker.
@@ -272,8 +256,9 @@ export declare function readSettingsObject(settingsPath: string): SettingsFileSh
272
256
  * Order: the process env FIRST (that is the value the RUNNING session
273
257
  * captured at start-up, so it is what the harness is actually compacting
274
258
  * against right now), then the settings file (what the next session will
275
- * read). When the two disagree, the file is what the sync updates — the
276
- * process env cannot be changed from inside a running session.
259
+ * read). When the two disagree, the FILE is the configured value; a probe
260
+ * reports the disagreement rather than replacing it, and the process env
261
+ * cannot be changed from inside a running session.
277
262
  */
278
263
  export declare function readHarnessWindow(input: {
279
264
  readonly location: HarnessWindowLocation;
@@ -294,6 +279,12 @@ export declare function syncHarnessWindow(input: {
294
279
  readonly location: HarnessWindowLocation;
295
280
  readonly tokens: number | null;
296
281
  readonly env?: NodeJS.ProcessEnv | undefined;
282
+ /**
283
+ * True for a PROBE-driven call: fill an empty slot, never replace a value the
284
+ * file already configures. The observed window is an observation, so it must
285
+ * not become the project's configuration. Omitted by explicit callers (init).
286
+ */
287
+ readonly onlyFillEmptySlot?: boolean;
297
288
  }): HarnessWindowSyncResult;
298
289
  /**
299
290
  * Rollback: remove the window key and record the opt-out so the next sync
@@ -1,27 +1,16 @@
1
1
  /**
2
2
  * Harness auto-compact window ownership
3
3
  *
4
- * The goal (user's words): *when* to trigger auto-compact must be
5
- * peaks-loop's decision; *how* to compact stays the harness's capability.
6
- *
7
- * That only holds if the two sides agree on ONE number. Before this slice
8
- * they each resolved a window independently: Claude Code used the window it
9
- * knows for the model, while peaks-loop divided by `resolveContextWindow()`
10
- * (env → config → model-name heuristic → 200_000 default). A 1M-window model
11
- * whose id the heuristic does not recognise made peaks-loop's "95%" land at
12
- * 190K while the harness waited for ~967K — a 5× early trigger, and (before
13
- * T3) a deadlock, because nothing could lower the ratio.
14
- *
15
- * This module owns the OTHER half: the harness itself accepts a window override
16
- * (`IdeCompactProfile.autoCompactWindowEnvVar`, declared per adapter — no IDE
17
- * names here), so peaks-loop writes the very number it computes the ratio
18
- * against into the harness's own machine-local settings file. Reader and writer
19
- * reference one artifact, not two resolutions that must "remember" to agree.
4
+ * The two sides must agree on ONE number. The harness accepts a window override
5
+ * (`IdeCompactProfile.autoCompactWindowEnvVar`, declared per adapter), so
6
+ * peaks-loop writes the very number it computes its ratio against into the
7
+ * harness's own machine-local settings file. Reader and writer reference one
8
+ * artifact, not two resolutions that must "remember" to agree.
20
9
  *
21
10
  * Vendor neutrality: this module knows about a JSON file with an `env` block
22
11
  * and nothing else. The settings path and the env-var name are BOTH passed in
23
- * by the caller, resolved from the IDE adapter's declarations: no IDE id, no
24
- * `.claude` literal, no registry import.
12
+ * by the caller, from the IDE adapter's declarations: no IDE id, no `.claude`
13
+ * literal, no registry import.
25
14
  */
26
15
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
27
16
  import { dirname } from 'node:path';
@@ -52,25 +41,13 @@ export const HARNESS_WINDOW_SYNC_OPTOUT_VALUE = 'off';
52
41
  * Provenance marker: the window value peaks-loop ITSELF last wrote, recorded
53
42
  * in the same `env` block as the window key.
54
43
  *
55
- * Why it must exist. The window key is a SHARED artifact — the harness reads
56
- * it, the user may set it by hand (it is a documented Claude Code variable),
57
- * and peaks-loop writes it. Two rules collide on it:
58
- *
59
- * - the ratio peaks-loop reports must divide by the key (the single-source
60
- * rule), so the key outranks the model heuristic; and
61
- * - a first-time mis-resolution must not become PERMANENT.
62
- *
63
- * The second rule needs the late 1M rescue to be able to overrule the key when
64
- * the observed context proves the key too small. Applied to a value a HUMAN
65
- * pinned, that same rescue would silently destroy an explicit setting — the
66
- * user asks for an early compact, a long session outgrows the pin, and
67
- * peaks-loop rewrites the file to 1M, permanently. Applied to peaks-loop's own
68
- * earlier output it is simply self-correction.
69
- *
70
- * This marker is what tells the two apart: it records what peaks-loop wrote,
71
- * so a mismatch means the human has taken the key over and the rescue must
72
- * stand down. It travels in the same write as the value it describes, so the
73
- * two can never disagree about which write they belong to.
44
+ * The window key is shared — the harness reads it, the user may hand-edit it,
45
+ * and peaks-loop writes it. This marker records what peaks-loop wrote, so a
46
+ * mismatch means the human has taken the key over and the late 1M rescue must
47
+ * stand down. Applied to a human's pin that rescue would silently destroy an
48
+ * explicit setting; applied to peaks-loop's own earlier output it is
49
+ * self-correction. It travels in the same write as the value, so the two can
50
+ * never disagree about which write they belong to.
74
51
  */
75
52
  export const HARNESS_WINDOW_WRITTEN_KEY = 'PEAKS_HARNESS_WINDOW_WRITTEN';
76
53
  /**
@@ -158,8 +135,9 @@ function envString(settings, key) {
158
135
  * Order: the process env FIRST (that is the value the RUNNING session
159
136
  * captured at start-up, so it is what the harness is actually compacting
160
137
  * against right now), then the settings file (what the next session will
161
- * read). When the two disagree, the file is what the sync updates — the
162
- * process env cannot be changed from inside a running session.
138
+ * read). When the two disagree, the FILE is the configured value; a probe
139
+ * reports the disagreement rather than replacing it, and the process env
140
+ * cannot be changed from inside a running session.
163
141
  */
164
142
  export function readHarnessWindow(input) {
165
143
  const settings = readSettingsObject(input.location.settingsPath);
@@ -289,6 +267,15 @@ export function syncHarnessWindow(input) {
289
267
  if (!peakOwned) {
290
268
  return { ...base, action: 'skipped', reason: 'not-peaks-owned', tokens: current.tokens };
291
269
  }
270
+ // THE FILE WINS OVER A PROBE. `onlyFillEmptySlot` marks the calls a context
271
+ // probe makes: they may FILL an absent key (the write below) but never
272
+ // replace a value the file already configures — the file is the project's
273
+ // configuration and the probe is an observation. Placed AFTER the B1 guard
274
+ // so a human pin still reports `not-peaks-owned`; this reason is only for a
275
+ // peaks-owned value the probe would otherwise have replaced.
276
+ if (input.onlyFillEmptySlot === true && fileRaw !== undefined) {
277
+ return { ...base, action: 'skipped', reason: 'file-configures-window', tokens: current.tokens };
278
+ }
292
279
  const settings = fileSettings ?? {};
293
280
  const env = typeof settings.env === 'object' && settings.env !== null && !Array.isArray(settings.env)
294
281
  ? settings.env
@@ -192,6 +192,8 @@ function skippedHarnessWindowClause(result) {
192
192
  return `Harness window not managed: ${result.settingsPath} is a symlink (or a Windows junction), or the directory holding it is, so writing would follow the link and overwrite the file it points at. Replace the link with a real file (or directory) and the window lands here.`;
193
193
  case 'not-peaks-owned':
194
194
  return `Harness window not managed: ${result.settingsPath} already carries a window that peaks-loop did not write, and peaks-loop never overwrites (or claims) a value it did not write.`;
195
+ case 'file-configures-window':
196
+ return `Harness window not managed: ${result.settingsPath} already configures a window, and the project file wins over a probe — peaks-loop only fills an empty slot. Change ${result.key} in that file (or remove it and let the next probe fill it) if you want a different window.`;
195
197
  default:
196
198
  return `Harness window not managed (${String(result.reason)}).`;
197
199
  }
@@ -82,7 +82,7 @@ function isPlainWindowSpelling(raw) {
82
82
  * as 1000000, and a value of `1e6` equals a marker of `1000000` only because the
83
83
  * parser is lenient. Neither is evidence of ownership, so the pair is `human`
84
84
  * and is KEPT. An UNPARSEABLE value beside a plain, valid marker still proves
85
- * corruption of peaks-loop's own write (`500k` beside `250000`) and stays
85
+ * corruption of peaks-loop's own write (`500k` beside `1000000`) and stays
86
86
  * removable — that recovery is the feature.
87
87
  */
88
88
  function isWindowRemovable(input) {
@@ -133,13 +133,13 @@ export declare function parseContextWindowOverride(raw: unknown): number | null;
133
133
  *
134
134
  * Why it sits BELOW the two explicit pins. Both are human declarations of
135
135
  * intent, and a pin that loses to a value peaks-loop wrote earlier is a
136
- * silently ignored setting: the user changes `context.windowTokens`, the
137
- * stale harness key shadows it, and nothing appears to happen. Conflict is
138
- * instead resolved by PROPAGATION — the probe that resolves the pin also
139
- * syncs it into the harness (`syncHarnessWindowForProject`), so peaks-loop's
140
- * ratio and the harness's window are back on one number before that command
141
- * returns. The conflict is therefore transient and self-healing rather than
142
- * either silent shadowing or permanent drift.
136
+ * silently ignored setting. A probe cannot rewrite a non-empty file (the
137
+ * probe sync fills an empty slot only), so the writer REPORTS the
138
+ * disagreement instead of overwriting the project's own configuration. The
139
+ * conflict is therefore visible rather than silent, and the remedy is a
140
+ * deliberate one: edit the key in the file (or remove it and let the next
141
+ * probe fill the slot), or change `context.windowTokens` so a new project
142
+ * starts from a different value.
143
143
  *
144
144
  * Why layer 3 is not simply authoritative (the ratchet). Reading back a value
145
145
  * peaks-loop wrote makes peaks-loop trust its own earlier resolution, so a
@@ -116,13 +116,13 @@ export function parseContextWindowOverride(raw) {
116
116
  *
117
117
  * Why it sits BELOW the two explicit pins. Both are human declarations of
118
118
  * intent, and a pin that loses to a value peaks-loop wrote earlier is a
119
- * silently ignored setting: the user changes `context.windowTokens`, the
120
- * stale harness key shadows it, and nothing appears to happen. Conflict is
121
- * instead resolved by PROPAGATION — the probe that resolves the pin also
122
- * syncs it into the harness (`syncHarnessWindowForProject`), so peaks-loop's
123
- * ratio and the harness's window are back on one number before that command
124
- * returns. The conflict is therefore transient and self-healing rather than
125
- * either silent shadowing or permanent drift.
119
+ * silently ignored setting. A probe cannot rewrite a non-empty file (the
120
+ * probe sync fills an empty slot only), so the writer REPORTS the
121
+ * disagreement instead of overwriting the project's own configuration. The
122
+ * conflict is therefore visible rather than silent, and the remedy is a
123
+ * deliberate one: edit the key in the file (or remove it and let the next
124
+ * probe fill the slot), or change `context.windowTokens` so a new project
125
+ * starts from a different value.
126
126
  *
127
127
  * Why layer 3 is not simply authoritative (the ratchet). Reading back a value
128
128
  * peaks-loop wrote makes peaks-loop trust its own earlier resolution, so a
@@ -309,12 +309,12 @@ function findLatestTranscriptUsage(filePath) {
309
309
  * Overruling it would not be self-correction, it would be peaks-loop
310
310
  * silently rewriting a setting the user chose (and persisting the rewrite).
311
311
  *
312
- * Both branches keep the single-source rule: the resolution this function
313
- * returns becomes `probe.capacityTokens`, and the caller syncs exactly that
314
- * back into the harness key (`syncHarnessWindowForProject`). When the rescue
315
- * fires, the key is refreshed to the bumped number in the same command, so
316
- * peaks-loop's ratio and the harness window are one number again — the rescue
317
- * never leaves the two sides apart.
312
+ * The resolution this function returns becomes `probe.capacityTokens`, so the
313
+ * rescue keeps the RATIO honest. It does NOT persist the bump: a probe may
314
+ * only fill an empty harness slot (`syncHarnessWindowForProject`), so a file
315
+ * that already configures a window keeps it, and every later probe re-derives
316
+ * the same correction from the same evidence — the correction is a property
317
+ * of the observation, not a rewrite of the project's configuration.
318
318
  */
319
319
  function resolveContextWindowTokens(model, contextTokens, overrides = {}) {
320
320
  const resolved = resolveContextWindow(model, overrides);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.2.4",
3
+ "version": "4.2.6",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -133,11 +133,11 @@
133
133
  "picomatch": "4.0.7",
134
134
  "yaml": "^2.9.1",
135
135
  "zod": "^4.6.7",
136
- "peaks-loop-internal-runtime": "0.0.71",
137
- "peaks-loop-shared": "0.0.120",
138
- "peaks-loop-shared-channel": "0.0.88",
139
- "peaks-loop-workspace-runtime": "0.0.5",
140
- "peaks-loop-mut": "0.1.85"
136
+ "peaks-loop-internal-runtime": "0.0.73",
137
+ "peaks-loop-mut": "0.1.87",
138
+ "peaks-loop-shared": "0.0.122",
139
+ "peaks-loop-workspace-runtime": "0.0.7",
140
+ "peaks-loop-shared-channel": "0.0.90"
141
141
  },
142
142
  "devDependencies": {
143
143
  "@changesets/cli": "2.31.1",