peaks-loop 4.2.2 → 4.2.4
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.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +109 -0
- package/dist/cli/commands/code-context-now-command.js +8 -3
- package/dist/cli/commands/code-context-now-envelope.d.ts +27 -2
- package/dist/cli/commands/code-context-now-envelope.js +47 -2
- package/dist/cli/commands/compact-harness-window-command.js +19 -111
- package/dist/cli/commands/compact-harness-window-opt-out.d.ts +4 -0
- package/dist/cli/commands/compact-harness-window-opt-out.js +76 -0
- package/dist/cli/commands/compact-harness-window-percent.d.ts +39 -0
- package/dist/cli/commands/compact-harness-window-percent.js +78 -0
- package/dist/cli/commands/compact-harness-window-reports.d.ts +8 -0
- package/dist/cli/commands/compact-harness-window-reports.js +149 -0
- package/dist/cli/commands/workspace/init-actions.d.ts +2 -0
- package/dist/cli/commands/workspace/init-actions.js +15 -1
- package/dist/cli/commands/workspace/init-command.js +1 -1
- package/dist/cli/commands/workspace/init-envelope.d.ts +2 -1
- package/dist/cli/commands/workspace/init-envelope.js +18 -1
- package/dist/cli/commands/workspace/init-harness-threshold.d.ts +30 -0
- package/dist/cli/commands/workspace/init-harness-threshold.js +134 -0
- package/dist/services/context/auto-compact-reader.d.ts +6 -5
- package/dist/services/context/auto-compact-reader.js +24 -27
- package/dist/services/context/harness-compact-threshold-config.d.ts +178 -0
- package/dist/services/context/harness-compact-threshold-config.js +166 -0
- package/dist/services/context/harness-compact-threshold-ensure.d.ts +90 -0
- package/dist/services/context/harness-compact-threshold-ensure.js +158 -0
- package/dist/services/context/harness-compact-threshold-refusal.d.ts +39 -0
- package/dist/services/context/harness-compact-threshold-refusal.js +122 -0
- package/dist/services/context/harness-compact-threshold-reset-types.d.ts +59 -0
- package/dist/services/context/harness-compact-threshold-reset-types.js +9 -0
- package/dist/services/context/harness-compact-threshold-reset.d.ts +48 -0
- package/dist/services/context/harness-compact-threshold-reset.js +215 -0
- package/dist/services/context/harness-compact-threshold-verdict.d.ts +71 -0
- package/dist/services/context/harness-compact-threshold-verdict.js +124 -0
- package/dist/services/context/harness-percent-gates.d.ts +35 -0
- package/dist/services/context/harness-percent-gates.js +102 -0
- package/dist/services/context/harness-percent-ownership.d.ts +126 -0
- package/dist/services/context/harness-percent-ownership.js +200 -0
- package/dist/services/context/harness-settings-file.d.ts +70 -0
- package/dist/services/context/harness-settings-file.js +83 -0
- package/dist/services/context/harness-window-config.d.ts +53 -141
- package/dist/services/context/harness-window-config.js +58 -296
- package/dist/services/context/harness-window-opt-out.d.ts +67 -0
- package/dist/services/context/harness-window-opt-out.js +241 -0
- package/dist/services/context/harness-window-ownership.d.ts +49 -0
- package/dist/services/context/harness-window-ownership.js +130 -0
- package/dist/services/ide/adapters/claude-code-adapter.d.ts +9 -9
- package/dist/services/ide/adapters/claude-code-adapter.js +5 -5
- package/dist/services/ide/ide-compact-types.d.ts +23 -4
- package/dist/services/ide/shared/safe-path.d.ts +18 -0
- package/dist/services/ide/shared/safe-path.js +34 -1
- package/package.json +6 -6
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The OPT-OUT half of the harness window — `--disable` and `--reenable`.
|
|
3
|
+
*
|
|
4
|
+
* Split out of `harness-window-config.ts`, whose excess over the raw-line cap is
|
|
5
|
+
* gated: these two verbs are the only writers of the opt-out ROW, and both carry
|
|
6
|
+
* the link guard (a write through a symlink lands in the victim), so the pair is
|
|
7
|
+
* kept together. Nothing here is vendor-specific, and the only window-side
|
|
8
|
+
* helpers it needs are the reader, the marker constant and the shared
|
|
9
|
+
* `isEditable` predicate — all re-imported, never re-implemented.
|
|
10
|
+
*/
|
|
11
|
+
import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
|
|
12
|
+
import { dirname } from 'node:path';
|
|
13
|
+
import { isUserHomeProjectRoot } from '../config/config-safety.js';
|
|
14
|
+
import { HARNESS_WINDOW_MAX_TOKENS, HARNESS_WINDOW_MIN_TOKENS, HARNESS_WINDOW_SYNC_OPTOUT_KEY, HARNESS_WINDOW_SYNC_OPTOUT_VALUE } from './harness-window-config.js';
|
|
15
|
+
// The shared settings-file layer: one spelling of 'is this a link' and 'is this
|
|
16
|
+
// editable', never a second copy here.
|
|
17
|
+
import { isEditableSettingsFile, isLinkedSettingsFile, readSettingsObject } from './harness-settings-file.js';
|
|
18
|
+
/**
|
|
19
|
+
* The WHERE guards for a write of the opt-out row, in order, or `null` when the
|
|
20
|
+
* write may proceed. Shared by `--disable` and `--reenable`: both edit the same
|
|
21
|
+
* file, so both refuse the same placements. Home FIRST — a refusal that has
|
|
22
|
+
* already mkdir'd `$HOME/.claude` is not a refusal — then the link, before the
|
|
23
|
+
* editability test, because a symlinked file (or a linked `.claude` directory
|
|
24
|
+
* above an ordinary one) parses fine and the write would follow it into the victim.
|
|
25
|
+
*/
|
|
26
|
+
function optOutRefusal(location) {
|
|
27
|
+
if (location.projectRoot !== undefined && isUserHomeProjectRoot(location.projectRoot)) {
|
|
28
|
+
return 'refused-unsafe-project-root';
|
|
29
|
+
}
|
|
30
|
+
if (isLinkedSettingsFile(location.settingsPath))
|
|
31
|
+
return 'symlinked-settings';
|
|
32
|
+
if (!isEditableSettingsFile(location.settingsPath))
|
|
33
|
+
return 'unreadable-settings';
|
|
34
|
+
return null;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Record the opt-out WITHOUT removing anything: "stop managing this key",
|
|
38
|
+
* expressible at any moment — including before peaks-loop has ever written it.
|
|
39
|
+
*
|
|
40
|
+
* WHY THIS IS A SEPARATE ENTRY POINT, NOT A FALLBACK OF `resetHarnessWindow`.
|
|
41
|
+
* `--reset` on a file holding no peaks row is deliberately a no-op, so a project
|
|
42
|
+
* peaks-loop never touched had no command for the second intention; folding it
|
|
43
|
+
* into `--reset` would make one verb mean "delete" or "don't write" depending on
|
|
44
|
+
* whether a row happened to exist. Two verbs, two predictable intentions.
|
|
45
|
+
*
|
|
46
|
+
* WHAT IT DOES NOT DO: it does not touch the window key (a hand-set value stays,
|
|
47
|
+
* as the B1 guard would keep it anyway) and writes no provenance marker, so it
|
|
48
|
+
* claims no ownership. The next probe reports `skipped / opted-out`.
|
|
49
|
+
*
|
|
50
|
+
* Idempotent: a second call reports `already-opted-out` and rewrites nothing.
|
|
51
|
+
*/
|
|
52
|
+
export function disableHarnessWindowSync(input) {
|
|
53
|
+
const settingsPath = input.location.settingsPath;
|
|
54
|
+
const refusal = optOutRefusal(input.location);
|
|
55
|
+
if (refusal !== null)
|
|
56
|
+
return { settingsPath, action: refusal };
|
|
57
|
+
const settings = readSettingsObject(settingsPath);
|
|
58
|
+
const env = typeof settings?.env === 'object' && settings.env !== null && !Array.isArray(settings.env)
|
|
59
|
+
? { ...settings.env }
|
|
60
|
+
: {};
|
|
61
|
+
if (env[HARNESS_WINDOW_SYNC_OPTOUT_KEY] === HARNESS_WINDOW_SYNC_OPTOUT_VALUE) {
|
|
62
|
+
return { settingsPath, action: 'already-opted-out' };
|
|
63
|
+
}
|
|
64
|
+
env[HARNESS_WINDOW_SYNC_OPTOUT_KEY] = HARNESS_WINDOW_SYNC_OPTOUT_VALUE;
|
|
65
|
+
const dir = dirname(settingsPath);
|
|
66
|
+
if (!existsSync(dir))
|
|
67
|
+
mkdirSync(dir, { recursive: true });
|
|
68
|
+
writeFileSync(settingsPath, `${JSON.stringify({ ...(settings ?? {}), env }, null, 2)}\n`, 'utf8');
|
|
69
|
+
return { settingsPath, action: 'disabled' };
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Undo the opt-out (the companion of `resetHarnessWindow`) so peaks-loop
|
|
73
|
+
* resumes owning the harness window.
|
|
74
|
+
*
|
|
75
|
+
* It WRITES, so the same WHERE guards as `--disable` fire: at `$HOME` it would
|
|
76
|
+
* edit the user's personal settings, and through a link it would edit the
|
|
77
|
+
* victim. Both are reported, never thrown.
|
|
78
|
+
*/
|
|
79
|
+
export function reenableHarnessWindowSync(input) {
|
|
80
|
+
const settingsPath = input.location.settingsPath;
|
|
81
|
+
const refusal = optOutRefusal(input.location);
|
|
82
|
+
// `unreadable-settings` is the one opt-out refusal `--reenable` reports as
|
|
83
|
+
// `absent`: there is no opt-out it can see, and it writes nothing either way.
|
|
84
|
+
if (refusal === 'refused-unsafe-project-root' || refusal === 'symlinked-settings') {
|
|
85
|
+
return { settingsPath, action: refusal };
|
|
86
|
+
}
|
|
87
|
+
if (refusal === 'unreadable-settings')
|
|
88
|
+
return { settingsPath, action: 'absent' };
|
|
89
|
+
const settings = readSettingsObject(settingsPath);
|
|
90
|
+
if (settings === null)
|
|
91
|
+
return { settingsPath, action: 'absent' };
|
|
92
|
+
const env = typeof settings.env === 'object' && settings.env !== null && !Array.isArray(settings.env)
|
|
93
|
+
? { ...settings.env }
|
|
94
|
+
: {};
|
|
95
|
+
if (env[HARNESS_WINDOW_SYNC_OPTOUT_KEY] === undefined)
|
|
96
|
+
return { settingsPath, action: 'absent' };
|
|
97
|
+
delete env[HARNESS_WINDOW_SYNC_OPTOUT_KEY];
|
|
98
|
+
writeFileSync(settingsPath, `${JSON.stringify({ ...settings, env }, null, 2)}\n`, 'utf8');
|
|
99
|
+
return { settingsPath, action: 'reenabled' };
|
|
100
|
+
}
|
|
101
|
+
// ---- the window NOTICES, moved out of the over-cap config module -------
|
|
102
|
+
/** The band, in the ONE spelling every refusal and suppression quotes. */
|
|
103
|
+
function harnessWindowBand() {
|
|
104
|
+
return `${HARNESS_WINDOW_MIN_TOKENS}..${HARNESS_WINDOW_MAX_TOKENS}`;
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* The ONE wording of "what the harness-window sync just did", for both commands
|
|
108
|
+
* that sync (`context-now`, `auto-compact`). ONE definition, so a future edit
|
|
109
|
+
* cannot tell half the users — see 要告知 in the module header.
|
|
110
|
+
*
|
|
111
|
+
* The `written` branch names the key, value, file, previous value and the exact
|
|
112
|
+
* rollback, because the harness reports its override only through
|
|
113
|
+
* `/autocompact`. The `skipped` branch is composed from the reason, the two
|
|
114
|
+
* numbers when they disagree, and the raw value when the file's value is not a
|
|
115
|
+
* number — see `harnessWindowConflictClause` / `unreadableWindowValueClause`.
|
|
116
|
+
*/
|
|
117
|
+
export function describeHarnessWindowSync(result) {
|
|
118
|
+
if (result === null) {
|
|
119
|
+
return 'The active IDE adapter declares no auto-compact window key; this ratio cannot be tied to the harness trigger.';
|
|
120
|
+
}
|
|
121
|
+
if (result.action === 'written') {
|
|
122
|
+
return `WROTE ${result.key}=${String(result.tokens)} to ${result.settingsPath} (was ${result.previousTokens === null ? 'unset' : String(result.previousTokens)}) so the harness compacts at the same point this ratio measures. Rollback: \`peaks compact harness-window --reset\`.`;
|
|
123
|
+
}
|
|
124
|
+
if (result.action === 'skipped') {
|
|
125
|
+
// A refused write is NOT automatically a non-event. The two clauses below
|
|
126
|
+
// are the whole point of refusing to stop at the reason token: each names a
|
|
127
|
+
// concrete NUMBER the user can act on, because "not managed" alone left the
|
|
128
|
+
// reader unable to tell whether the two sides still agreed.
|
|
129
|
+
return `${skippedHarnessWindowClause(result)}${harnessWindowConflictClause(result)}${unreadableWindowValueClause(result)}`;
|
|
130
|
+
}
|
|
131
|
+
// `unchanged` — the file already holds exactly the window this probe divided
|
|
132
|
+
// by, so there is no disagreement to report. What can still be hidden is
|
|
133
|
+
// OWNERSHIP, and it decides what happens when the session outgrows the value.
|
|
134
|
+
// A user upgrading from a release that wrote the key before the provenance
|
|
135
|
+
// marker existed lands here (that is this repository's own state): the value
|
|
136
|
+
// is in force, peaks-loop computes against it, and nothing anywhere said it
|
|
137
|
+
// had become frozen — so "already in force" alone is not a full notice.
|
|
138
|
+
if (!result.peakWritten) {
|
|
139
|
+
return `Harness window ${result.key}=${String(result.tokens)} already in force, but it is NOT peaks-loop's own write: peaks-loop divides this ratio by it and will never raise it, so a session that outgrows ${String(result.tokens)} saturates the ratio at 1.0 instead of widening the window. To hand the key back to peaks-loop: \`peaks compact harness-window --reset\` (removes it), then \`peaks compact harness-window --reenable\` (the next probe fills it).`;
|
|
140
|
+
}
|
|
141
|
+
return `Harness window ${result.key} already in force; peaks-loop computes this ratio against it.`;
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* The same disagreement as `harnessWindowConflictClause`, reduced to one line
|
|
145
|
+
* for the `warnings` channel — the machine-readable half of 要告知, so a
|
|
146
|
+
* consumer reading the JSON envelope (or a human reading stderr) sees it even
|
|
147
|
+
* if it never renders `nextActions`. Returns `null` when there is nothing to
|
|
148
|
+
* warn about, which is the ordinary case.
|
|
149
|
+
*/
|
|
150
|
+
export function harnessWindowSyncWarning(result) {
|
|
151
|
+
if (result === null || result.action !== 'skipped')
|
|
152
|
+
return null;
|
|
153
|
+
// E1: the resolved window is not one the harness accepts, so this ratio's
|
|
154
|
+
// denominator is un-anchored no matter what the file holds. Reported FIRST —
|
|
155
|
+
// it is the more fundamental disagreement, and the two clauses below would
|
|
156
|
+
// read as "a different number" rather than "a number the harness cannot use".
|
|
157
|
+
if (result.reason === 'out-of-harness-range') {
|
|
158
|
+
return `harness window out of range: this probe divided by ${String(result.requestedTokens)} tokens, outside the ${harnessWindowBand()} band the harness accepts — the ratio does not describe the harness's own trigger`;
|
|
159
|
+
}
|
|
160
|
+
if (result.requestedTokens !== null &&
|
|
161
|
+
result.previousTokens !== null &&
|
|
162
|
+
result.requestedTokens !== result.previousTokens) {
|
|
163
|
+
return `harness window conflict: this probe divided by ${result.requestedTokens} tokens but ${result.settingsPath} pins ${result.previousTokens} — the ratio does not describe the harness's own trigger`;
|
|
164
|
+
}
|
|
165
|
+
if (result.previousTokens === null && result.previousRawNote !== undefined) {
|
|
166
|
+
return `harness window unreadable: ${result.settingsPath} carries ${result.previousRawNote}, which is not a plain token count`;
|
|
167
|
+
}
|
|
168
|
+
return null;
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* WHY nothing was written, in words — one clause per `reason`.
|
|
172
|
+
*
|
|
173
|
+
* Every reason has its own sentence rather than falling through to
|
|
174
|
+
* `(${reason})`: the bare token was what the user actually saw for the two
|
|
175
|
+
* most common refusals, and it names no value, no file, and no next step.
|
|
176
|
+
* The trailing clause is unreachable for the reasons this module produces
|
|
177
|
+
* today; it exists so a future reason cannot silently degrade to a token.
|
|
178
|
+
*/
|
|
179
|
+
function skippedHarnessWindowClause(result) {
|
|
180
|
+
switch (result.reason) {
|
|
181
|
+
case 'opted-out':
|
|
182
|
+
return 'Harness window not managed (opted-out) — re-enable with `peaks compact harness-window --reenable`.';
|
|
183
|
+
case 'unsafe-project-root':
|
|
184
|
+
return `Harness window not managed: ${result.settingsPath} is the user's own home settings, not a project's, so peaks-loop left it alone. Re-run from inside a project (or point at one) and the window lands there instead.`;
|
|
185
|
+
case 'no-window-resolved':
|
|
186
|
+
return 'Harness window not managed: this probe measured a percentage and carried no token window, so there was no number to write — peaks-loop does not invent a window the adapter did not resolve.';
|
|
187
|
+
case 'out-of-harness-range':
|
|
188
|
+
return `Harness window not managed: the window this probe resolved (${String(result.requestedTokens)}) is outside the ${harnessWindowBand()} band the harness accepts, so writing it would put a number in ${result.settingsPath} that the harness does not compact on.`;
|
|
189
|
+
case 'unreadable-settings':
|
|
190
|
+
return `Harness window not managed: ${result.settingsPath} is not a JSON object peaks-loop can safely edit, so it was left exactly as found.`;
|
|
191
|
+
case 'symlinked-settings':
|
|
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
|
+
case 'not-peaks-owned':
|
|
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
|
+
default:
|
|
196
|
+
return `Harness window not managed (${String(result.reason)}).`;
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
/**
|
|
200
|
+
* THE DISAGREEMENT SENTENCE — the one the user cannot get anywhere else.
|
|
201
|
+
*
|
|
202
|
+
* peaks-loop divided this probe's ratio by `requestedTokens`, while the
|
|
203
|
+
* harness's own settings file pins `previousTokens`. Neither side is wrong on
|
|
204
|
+
* its own, which is exactly why it went unnoticed: the file wins for the ratio
|
|
205
|
+
* (T1's single-source rule), the write that would have re-unified them was
|
|
206
|
+
* refused (B1's provenance guard), and the result was a percentage computed
|
|
207
|
+
* against a window the harness is not going to fire on. The harness reports an
|
|
208
|
+
* override only through its own `/autocompact`, so if peaks-loop does not name
|
|
209
|
+
* the two numbers here, nobody does.
|
|
210
|
+
*
|
|
211
|
+
* Both numbers and the file are named, and all three ways out are given,
|
|
212
|
+
* because this notice is the whole remedy for a state peaks-loop deliberately
|
|
213
|
+
* refuses to fix by writing.
|
|
214
|
+
*/
|
|
215
|
+
function harnessWindowConflictClause(result) {
|
|
216
|
+
const requested = result.requestedTokens;
|
|
217
|
+
const pinned = result.previousTokens;
|
|
218
|
+
if (result.action !== 'skipped' || requested === null || pinned === null || requested === pinned)
|
|
219
|
+
return '';
|
|
220
|
+
return ` CONFLICT: peaks-loop divided this ratio by ${requested} tokens, but ${result.settingsPath} pins ${pinned} — and the harness compacts on ITS own number, so this ratio does not describe when it fires. Nothing was written. Choose one: (1) make peaks-loop's number match the file (unset PEAKS_CONTEXT_WINDOW_TOKENS, or change \`context.windowTokens\`), (2) keep the file as your own setting and read this ratio as a share of ${requested}, or (3) \`peaks compact harness-window --reset\` to remove the key and hand it back to peaks-loop.`;
|
|
221
|
+
}
|
|
222
|
+
/**
|
|
223
|
+
* The OTHER way two numbers can fail to line up: the file's value is not a
|
|
224
|
+
* number at all (`500k`, a hand-typed typo).
|
|
225
|
+
*
|
|
226
|
+
* `previousTokens` is `null` here — indistinguishable, in the parsed result,
|
|
227
|
+
* from an absent key — so this clause is gated on the RAW value. The
|
|
228
|
+
* disagreement is stated but never "aligned": peaks-loop will not overwrite a
|
|
229
|
+
* value it did not write, and the value is unusable, so the only honest output
|
|
230
|
+
* is to name it and hand the user the two ways out. Silent here would be the
|
|
231
|
+
* worst option of all, because the caller has already fallen back to a
|
|
232
|
+
* different window and the disk keeps claiming `500k` on every probe after it.
|
|
233
|
+
*/
|
|
234
|
+
function unreadableWindowValueClause(result) {
|
|
235
|
+
if (result.action !== 'skipped' ||
|
|
236
|
+
result.previousTokens !== null ||
|
|
237
|
+
result.previousRawNote === undefined)
|
|
238
|
+
return '';
|
|
239
|
+
const raw = result.previousRawNote;
|
|
240
|
+
return ` The value in ${result.settingsPath} is ${raw}, which is not a plain token count: peaks-loop cannot read a window from it, so it resolved this ratio against its own fallback while the file keeps claiming a window it cannot parse. peaks-loop cannot align the two without overwriting a value it did not write — set the value to a plain token count, or run \`peaks compact harness-window --reset\` to remove the key and let the next probe write peaks-loop's number.`;
|
|
241
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* WHO owns the harness auto-compact WINDOW key — the rollback's classifier.
|
|
3
|
+
*
|
|
4
|
+
* The percent half has had this question answered in one place since the pair
|
|
5
|
+
* was introduced (`harness-percent-ownership.ts`). The window half did not: the
|
|
6
|
+
* rollback deleted `delete nextEnv[location.envVar]` unconditionally, so
|
|
7
|
+
* `--reset` removed a hand-set window even though its own documentation
|
|
8
|
+
* promised that a genuine human pin is always kept. This module is that
|
|
9
|
+
* promise, in the same five states and with the same shape as the percent's, so
|
|
10
|
+
* the two halves of one rollback cannot disagree about what "peaks-loop wrote
|
|
11
|
+
* this" means.
|
|
12
|
+
*
|
|
13
|
+
* It sits in its own module rather than in `harness-window-config.ts` because
|
|
14
|
+
* that file is already over the raw-line cap and its excess is gated; the
|
|
15
|
+
* predicate needs only the marker constant and the token parser from it.
|
|
16
|
+
*/
|
|
17
|
+
import { HARNESS_WINDOW_WRITTEN_KEY } from './harness-window-config.js';
|
|
18
|
+
export { HARNESS_WINDOW_WRITTEN_KEY };
|
|
19
|
+
/**
|
|
20
|
+
* WHO the window value on disk belongs to — the five states the percent half
|
|
21
|
+
* already names, so a reader who knows one knows the other.
|
|
22
|
+
*
|
|
23
|
+
* - `peaks` — the value parses and equals its provenance marker
|
|
24
|
+
* - `peaks-corrupt` — the marker parses while the VALUE does not (peaks-loop
|
|
25
|
+
* writes only `String(tokens)`, so a VALID numeric marker
|
|
26
|
+
* beside an unreadable value is its own write mangled
|
|
27
|
+
* afterwards)
|
|
28
|
+
* - `human` — a value with no marker, one that differs from its
|
|
29
|
+
* marker (a takeover), one whose MARKER does not parse,
|
|
30
|
+
* or one whose value or marker is in a spelling peaks-loop
|
|
31
|
+
* never writes (`1e6`, `00100000`, `+1000000`): an
|
|
32
|
+
* unreadable-or-unwritable marker is never evidence that
|
|
33
|
+
* peaks-loop wrote here, even when both raws are equal
|
|
34
|
+
* - `stale-marker` — the value was deleted by hand, the marker survived
|
|
35
|
+
* - `none` — neither the value nor a marker
|
|
36
|
+
*/
|
|
37
|
+
export type HarnessWindowOwnership = 'peaks' | 'peaks-corrupt' | 'human' | 'stale-marker' | 'none';
|
|
38
|
+
/**
|
|
39
|
+
* Classify one (value, marker) pair — the single answer to "may `--reset`
|
|
40
|
+
* remove this window, and what do we call it?".
|
|
41
|
+
*
|
|
42
|
+
* `markerRaw !== undefined` with no value is `stale-marker` rather than `none`:
|
|
43
|
+
* the marker IS peaks content and a rollback that left it behind would claim
|
|
44
|
+
* ownership of whatever the user writes into the key next.
|
|
45
|
+
*/
|
|
46
|
+
export declare function windowOwnershipOf(input: {
|
|
47
|
+
readonly fileRaw: unknown;
|
|
48
|
+
readonly markerRaw: unknown;
|
|
49
|
+
}): HarnessWindowOwnership;
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* WHO owns the harness auto-compact WINDOW key — the rollback's classifier.
|
|
3
|
+
*
|
|
4
|
+
* The percent half has had this question answered in one place since the pair
|
|
5
|
+
* was introduced (`harness-percent-ownership.ts`). The window half did not: the
|
|
6
|
+
* rollback deleted `delete nextEnv[location.envVar]` unconditionally, so
|
|
7
|
+
* `--reset` removed a hand-set window even though its own documentation
|
|
8
|
+
* promised that a genuine human pin is always kept. This module is that
|
|
9
|
+
* promise, in the same five states and with the same shape as the percent's, so
|
|
10
|
+
* the two halves of one rollback cannot disagree about what "peaks-loop wrote
|
|
11
|
+
* this" means.
|
|
12
|
+
*
|
|
13
|
+
* It sits in its own module rather than in `harness-window-config.ts` because
|
|
14
|
+
* that file is already over the raw-line cap and its excess is gated; the
|
|
15
|
+
* predicate needs only the marker constant and the token parser from it.
|
|
16
|
+
*/
|
|
17
|
+
import { HARNESS_WINDOW_WRITTEN_KEY, parseHarnessWindowTokens } from './harness-window-config.js';
|
|
18
|
+
export { HARNESS_WINDOW_WRITTEN_KEY };
|
|
19
|
+
/**
|
|
20
|
+
* THE SPELLING peaks-loop writes for this pair — a plain decimal with no leading
|
|
21
|
+
* zero beyond a lone `0`. This is the window's counterpart of the percent half's
|
|
22
|
+
* `PLAIN_PERCENT_SPELLING` (see `harness-percent-ownership.ts`) and it lives
|
|
23
|
+
* beside the window's ownership predicate for the same reason: it answers an
|
|
24
|
+
* OWNERSHIP question, not a parsing one.
|
|
25
|
+
*
|
|
26
|
+
* Why ownership needs it when the parser does not. `parseHarnessWindowTokens` is
|
|
27
|
+
* deliberately lenient — `Number()` accepts `1e6`, `00100000`, `+1000000` and
|
|
28
|
+
* `1000000.0`, and the reader needs that reach to compare a value the harness
|
|
29
|
+
* may hold — while the writer only ever emits `String(tokens)`, plain digits.
|
|
30
|
+
* Classifying by the lenient parse alone therefore treated a spelling peaks-loop
|
|
31
|
+
* could never have produced as its own, and `--reset` DELETED a value that was
|
|
32
|
+
* not peaks-loop's to remove (`1e6` beside marker `1000000` reproduced it).
|
|
33
|
+
*
|
|
34
|
+
* A value or a marker in any other spelling is not evidence of peaks-loop's
|
|
35
|
+
* ownership: the rollback keeps it. Its relation to the percent half is one
|
|
36
|
+
* asymmetry, stated rather than implied — a percent VALUE in an odd spelling is
|
|
37
|
+
* still `peaks-corrupt` (removable), because its parser refuses the spelling at
|
|
38
|
+
* all, so a readable marker beside it can only be a mangled peaks write. The
|
|
39
|
+
* window's parser accepts the spelling and then compares it, which is what made
|
|
40
|
+
* `1e6` equal `1000000` in the first place; the gate has to sit between those
|
|
41
|
+
* two steps, and the result is `human` (kept).
|
|
42
|
+
*/
|
|
43
|
+
const PLAIN_WINDOW_SPELLING = /^(?:0|[1-9]\d*)$/;
|
|
44
|
+
/**
|
|
45
|
+
* One raw value uses the plain spelling `String(tokens)` produces.
|
|
46
|
+
*
|
|
47
|
+
* A NUMBER has exactly one spelling `String()` can give it — the plain decimal
|
|
48
|
+
* of a positive integer — which is precisely what the token parser accepts, so
|
|
49
|
+
* delegating there keeps the two from drifting. The STRING branch is the one
|
|
50
|
+
* this gate exists for: a string can carry `1e6` or `00100000`, spellings no
|
|
51
|
+
* `String(tokens)` ever emits, and the parser would happily read them.
|
|
52
|
+
*
|
|
53
|
+
* The ORDER of the two tests is load-bearing. Applied to the WHOLE string, the
|
|
54
|
+
* regex would demand that the padding itself be digits, so `' 1000000 '` would
|
|
55
|
+
* be rejected even though the parser trims it; applied to the trimmed text it
|
|
56
|
+
* accepts the padded spelling, and that is the spelling the writer's own read
|
|
57
|
+
* path resolves to. The `typeof` test comes FIRST so a number is never handed
|
|
58
|
+
* to `RegExp.prototype.test` (`String(1_000_000)` would pass, but nothing
|
|
59
|
+
* proves the number was an integer).
|
|
60
|
+
*/
|
|
61
|
+
function isPlainWindowSpelling(raw) {
|
|
62
|
+
if (typeof raw === 'number')
|
|
63
|
+
return parseHarnessWindowTokens(raw) !== null;
|
|
64
|
+
const text = typeof raw === 'string' ? raw.trim() : '';
|
|
65
|
+
return PLAIN_WINDOW_SPELLING.test(text);
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* THE ROLLBACK'S RULE — what `--reset` may REMOVE.
|
|
69
|
+
*
|
|
70
|
+
* Deliberately the same asymmetry as `isHarnessPercentRemovable`: removing a
|
|
71
|
+
* value the user explicitly asked to roll back deserves a wider rule than
|
|
72
|
+
* overwriting one. A window with NO marker is the user's own pin and is never
|
|
73
|
+
* removed; a marker proves peaks-loop wrote here, so a mangled value beside it
|
|
74
|
+
* is a corruption of peaks-loop's own write rather than a human's setting.
|
|
75
|
+
*
|
|
76
|
+
* The proof must be a VALID marker: peaks-loop writes only `String(tokens)`, so
|
|
77
|
+
* an unparseable marker is not one of its writes and the window beside it is the
|
|
78
|
+
* user's — kept, even when both rows hold the same typo.
|
|
79
|
+
*
|
|
80
|
+
* The proof must also be in the SPELLING peaks-loop writes — on BOTH rows. A
|
|
81
|
+
* marker of `1e6` is not a write of this module even though `Number()` reads it
|
|
82
|
+
* as 1000000, and a value of `1e6` equals a marker of `1000000` only because the
|
|
83
|
+
* parser is lenient. Neither is evidence of ownership, so the pair is `human`
|
|
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
|
|
86
|
+
* removable — that recovery is the feature.
|
|
87
|
+
*/
|
|
88
|
+
function isWindowRemovable(input) {
|
|
89
|
+
// No absent-side guard: an absent `markerRaw` fails the spelling test below,
|
|
90
|
+
// and an absent `fileRaw` has already returned `stale-marker` in the caller.
|
|
91
|
+
// The guard that used to sit here could not fire, which is why it is gone.
|
|
92
|
+
// The marker is the only evidence that peaks-loop wrote here, so it must be
|
|
93
|
+
// both readable AND plain-spelled before it can authorise a removal.
|
|
94
|
+
if (!isPlainWindowSpelling(input.markerRaw))
|
|
95
|
+
return false;
|
|
96
|
+
const marker = parseHarnessWindowTokens(input.markerRaw);
|
|
97
|
+
// Plain-spelled yet unreadable (`0` — in the spelling, outside the positive
|
|
98
|
+
// band): still not a write of this module, so no ownership either.
|
|
99
|
+
if (marker === null)
|
|
100
|
+
return false;
|
|
101
|
+
const file = parseHarnessWindowTokens(input.fileRaw);
|
|
102
|
+
// Unreadable beside a plain, valid marker: peaks-loop's own write mangled
|
|
103
|
+
// afterwards — the documented `--reset` recovery (`peaks-corrupt`).
|
|
104
|
+
if (file === null)
|
|
105
|
+
return true;
|
|
106
|
+
// Readable but in a spelling this module cannot have written: not its value.
|
|
107
|
+
// UNLIKE the percent half, which cannot parse such a value at all and so
|
|
108
|
+
// reaches `peaks-corrupt` through the marker arm, the window's lenient parser
|
|
109
|
+
// reads it and would compare it equal — the decision is made one line later.
|
|
110
|
+
if (!isPlainWindowSpelling(input.fileRaw))
|
|
111
|
+
return false;
|
|
112
|
+
return marker === file;
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Classify one (value, marker) pair — the single answer to "may `--reset`
|
|
116
|
+
* remove this window, and what do we call it?".
|
|
117
|
+
*
|
|
118
|
+
* `markerRaw !== undefined` with no value is `stale-marker` rather than `none`:
|
|
119
|
+
* the marker IS peaks content and a rollback that left it behind would claim
|
|
120
|
+
* ownership of whatever the user writes into the key next.
|
|
121
|
+
*/
|
|
122
|
+
export function windowOwnershipOf(input) {
|
|
123
|
+
if (input.fileRaw === undefined && input.markerRaw === undefined)
|
|
124
|
+
return 'none';
|
|
125
|
+
if (input.fileRaw === undefined)
|
|
126
|
+
return 'stale-marker';
|
|
127
|
+
if (!isWindowRemovable(input))
|
|
128
|
+
return 'human';
|
|
129
|
+
return parseHarnessWindowTokens(input.fileRaw) === null ? 'peaks-corrupt' : 'peaks';
|
|
130
|
+
}
|
|
@@ -34,17 +34,17 @@ export interface ContextWindowOverrides {
|
|
|
34
34
|
/** Raw `context.windowTokens` value (unvalidated — validated here). */
|
|
35
35
|
readonly configWindowTokens?: unknown;
|
|
36
36
|
/**
|
|
37
|
-
* The window peaks-loop
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
* (
|
|
41
|
-
*
|
|
37
|
+
* The window peaks-loop configured for the harness, already PARSED to a
|
|
38
|
+
* positive token count by the caller (`auto-compact-reader.ts` via
|
|
39
|
+
* `harness-window-config.ts`). A NUMBER, never the settings file's text
|
|
40
|
+
* (MED-2): the value is user-writable and this layer's warnings reach
|
|
41
|
+
* stderr/logs. An unparseable value is `null` at the resolver.
|
|
42
42
|
*
|
|
43
|
-
*
|
|
44
|
-
* THE SAME NUMBER
|
|
45
|
-
*
|
|
43
|
+
* The ratio peaks-loop computes and the window the harness compacts against
|
|
44
|
+
* are then THE SAME NUMBER; without it they are two resolutions that drift
|
|
45
|
+
* 5× apart on a 1M-window model the model-name heuristic misses.
|
|
46
46
|
*/
|
|
47
|
-
readonly harnessWindowTokens?:
|
|
47
|
+
readonly harnessWindowTokens?: number | undefined;
|
|
48
48
|
/**
|
|
49
49
|
* Provenance of `harnessWindowTokens`: true when peaks-loop wrote that value
|
|
50
50
|
* itself, false/omitted when a human set it. Only a peaks-written value may
|
|
@@ -171,7 +171,7 @@ export function resolveContextWindow(model, overrides = {}) {
|
|
|
171
171
|
const parsed = parseContextWindowOverride(overrides.harnessWindowTokens);
|
|
172
172
|
if (parsed !== null)
|
|
173
173
|
return { tokens: parsed, source: 'harness-env' };
|
|
174
|
-
warn(`[peaks] harness auto-compact window ${
|
|
174
|
+
warn(`[peaks] harness auto-compact window ${String(overrides.harnessWindowTokens)} is not a positive integer — ignoring the override`);
|
|
175
175
|
}
|
|
176
176
|
const heuristic = modelContextWindowTokens(model);
|
|
177
177
|
return heuristic === DEFAULT_CONTEXT_WINDOW_TOKENS
|
|
@@ -518,11 +518,11 @@ export const CLAUDE_CODE_ADAPTER = {
|
|
|
518
518
|
postCompactDetectCommand: 'peaks code auto-compact --json',
|
|
519
519
|
// reads its auto-compact WINDOW from, in the machine-local `env` block.
|
|
520
520
|
// Claude Code documents it as taking precedence "over the command, the
|
|
521
|
-
// flag, and the setting", and as accepting the plain token count only
|
|
522
|
-
//
|
|
523
|
-
//
|
|
524
|
-
// `harness-window-config.ts`.
|
|
521
|
+
// flag, and the setting", and as accepting the plain token count only (no
|
|
522
|
+
// `500k` suffix). peaks-loop writes the window AND the percent knob so
|
|
523
|
+
// neither drifts (window × PCT%, measured 2026-11-20).
|
|
525
524
|
autoCompactWindowEnvVar: 'CLAUDE_CODE_AUTO_COMPACT_WINDOW',
|
|
525
|
+
autoCompactPercentEnvVar: 'CLAUDE_AUTOCOMPACT_PCT_OVERRIDE',
|
|
526
526
|
readContextPercentFallback,
|
|
527
527
|
// layout knowledge (`~/.claude/projects/**/<outerSessionId>.jsonl`)
|
|
528
528
|
// stays here; `peaks code context-audit` resolves it through the
|
|
@@ -55,6 +55,22 @@ export interface IdeCompactProfile {
|
|
|
55
55
|
* pretending. Adapters that do not opt in are unchanged.
|
|
56
56
|
*/
|
|
57
57
|
readonly autoCompactWindowEnvVar?: string;
|
|
58
|
+
/**
|
|
59
|
+
* Optional settings key / env var the IDE reads its AUTO-COMPACT THRESHOLD
|
|
60
|
+
* PERCENT from — the fraction of the window at which the harness itself
|
|
61
|
+
* compacts, expressed as a whole percentage (1..100).
|
|
62
|
+
*
|
|
63
|
+
* Why it is a separate declaration from the window: the two knobs answer
|
|
64
|
+
* different questions and live under different names in the harness, and the
|
|
65
|
+
* engine must not know either name. `harness-compact-threshold-config.ts`
|
|
66
|
+
* writes and reads this key through the adapter's declaration only, exactly
|
|
67
|
+
* as `harness-window-config.ts` does for the window, so a second IDE is
|
|
68
|
+
* addable without editing the engine.
|
|
69
|
+
*
|
|
70
|
+
* `undefined` = this IDE exposes no percent knob. peaks-loop then configures
|
|
71
|
+
* and reports the window alone; nothing here invents a key.
|
|
72
|
+
*/
|
|
73
|
+
readonly autoCompactPercentEnvVar?: string;
|
|
58
74
|
/**
|
|
59
75
|
* Optional command the runner invokes post-compact to confirm
|
|
60
76
|
* ratio dropped (e.g. `peaks code auto-compact --json`). When omitted,
|
|
@@ -120,13 +136,16 @@ export interface ContextPercentFallbackInput {
|
|
|
120
136
|
*/
|
|
121
137
|
readonly configWindowTokens?: unknown;
|
|
122
138
|
/**
|
|
123
|
-
*
|
|
124
|
-
*
|
|
125
|
-
*
|
|
139
|
+
* The window peaks-loop configured for the harness, resolved by the generic
|
|
140
|
+
* reader from the adapter's own declarations (settings path + key name) and
|
|
141
|
+
* PARSED to a positive token count before it gets here. Feeds the
|
|
126
142
|
* `harness-env` layer of `resolveContextWindow`.
|
|
127
143
|
*
|
|
144
|
+
* A NUMBER, never the settings file's text (MED-2): the key is
|
|
145
|
+
* user-writable and this layer's diagnostics reach logs. An unparseable
|
|
146
|
+
* value is `null` at the resolver, so it arrives as "no harness layer".
|
|
128
147
|
*/
|
|
129
|
-
readonly harnessWindowTokens?:
|
|
148
|
+
readonly harnessWindowTokens?: number | undefined;
|
|
130
149
|
/**
|
|
131
150
|
* True when `harnessWindowTokens` is a value peaks-loop ITSELF wrote (the
|
|
132
151
|
* harness settings carry the provenance marker matching it), false when a
|
|
@@ -9,3 +9,21 @@ export declare function isInsidePath(childPath: string, parentPath: string): boo
|
|
|
9
9
|
export declare function assertSafeSettingsFile(scope: HookScope, root: string, dirName: string, settingsFileName: string): {
|
|
10
10
|
settingsPath: string;
|
|
11
11
|
};
|
|
12
|
+
/**
|
|
13
|
+
* True when the settings file, or the DIRECTORY holding it, is a LINK — a
|
|
14
|
+
* symlink, or a Windows junction, which `lstat` also reports as one.
|
|
15
|
+
*
|
|
16
|
+
* The file-only form of this check could not see a linked directory: the file
|
|
17
|
+
* under it is ordinary, `lstat(file)` says `false`, and every write lands in the
|
|
18
|
+
* link target. `> settingsPath` follows a link, so this is what a writer must
|
|
19
|
+
* ask before it writes.
|
|
20
|
+
*
|
|
21
|
+
* `assertSafeSettingsFile` is the throwing, path-building form of the same
|
|
22
|
+
* question for the install paths; this is the boolean these callers need,
|
|
23
|
+
* because they REPORT a refusal in their result record rather than throw. It
|
|
24
|
+
* also decides the directory with `lstat` alone — `existsSync` follows a link,
|
|
25
|
+
* so a dangling directory link reads as absent there.
|
|
26
|
+
*
|
|
27
|
+
* An ABSENT file or directory answers `false`: that is the first write.
|
|
28
|
+
*/
|
|
29
|
+
export declare function isLinkedSettingsFile(settingsPath: string): boolean;
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { existsSync, lstatSync, realpathSync } from 'node:fs';
|
|
2
|
-
import { isAbsolute, join, relative } from 'node:path';
|
|
2
|
+
import { dirname, isAbsolute, join, relative } from 'node:path';
|
|
3
3
|
/** True iff `childPath` resolves to `parentPath` or any path nested inside it. */
|
|
4
4
|
export function isInsidePath(childPath, parentPath) {
|
|
5
5
|
const rel = relative(parentPath, childPath);
|
|
@@ -27,3 +27,36 @@ export function assertSafeSettingsFile(scope, root, dirName, settingsFileName) {
|
|
|
27
27
|
}
|
|
28
28
|
return { settingsPath };
|
|
29
29
|
}
|
|
30
|
+
/**
|
|
31
|
+
* True when `path` itself is a link; an ABSENT path is not one. `lstat`, never
|
|
32
|
+
* `stat`: `stat` follows the link and reports the victim's type. ENOENT (the
|
|
33
|
+
* ordinary first write, which must still happen) and EACCES are both `false`.
|
|
34
|
+
*/
|
|
35
|
+
function pathIsLink(path) {
|
|
36
|
+
try {
|
|
37
|
+
return lstatSync(path).isSymbolicLink();
|
|
38
|
+
}
|
|
39
|
+
catch {
|
|
40
|
+
return false;
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* True when the settings file, or the DIRECTORY holding it, is a LINK — a
|
|
45
|
+
* symlink, or a Windows junction, which `lstat` also reports as one.
|
|
46
|
+
*
|
|
47
|
+
* The file-only form of this check could not see a linked directory: the file
|
|
48
|
+
* under it is ordinary, `lstat(file)` says `false`, and every write lands in the
|
|
49
|
+
* link target. `> settingsPath` follows a link, so this is what a writer must
|
|
50
|
+
* ask before it writes.
|
|
51
|
+
*
|
|
52
|
+
* `assertSafeSettingsFile` is the throwing, path-building form of the same
|
|
53
|
+
* question for the install paths; this is the boolean these callers need,
|
|
54
|
+
* because they REPORT a refusal in their result record rather than throw. It
|
|
55
|
+
* also decides the directory with `lstat` alone — `existsSync` follows a link,
|
|
56
|
+
* so a dangling directory link reads as absent there.
|
|
57
|
+
*
|
|
58
|
+
* An ABSENT file or directory answers `false`: that is the first write.
|
|
59
|
+
*/
|
|
60
|
+
export function isLinkedSettingsFile(settingsPath) {
|
|
61
|
+
return pathIsLink(settingsPath) || pathIsLink(dirname(settingsPath));
|
|
62
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "peaks-loop",
|
|
3
|
-
"version": "4.2.
|
|
3
|
+
"version": "4.2.4",
|
|
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.
|
|
137
|
-
"peaks-loop-
|
|
138
|
-
"peaks-loop-shared": "0.0.
|
|
139
|
-
"peaks-loop-workspace-runtime": "0.0.
|
|
140
|
-
"peaks-loop-
|
|
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"
|
|
141
141
|
},
|
|
142
142
|
"devDependencies": {
|
|
143
143
|
"@changesets/cli": "2.31.1",
|