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
|
@@ -12,21 +12,28 @@
|
|
|
12
12
|
* 190K while the harness waited for ~967K — a 5× early trigger, and (before
|
|
13
13
|
* T3) a deadlock, because nothing could lower the ratio.
|
|
14
14
|
*
|
|
15
|
-
* This module owns the OTHER half
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
* resolutions that must "remember" to agree.
|
|
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.
|
|
21
20
|
*
|
|
22
21
|
* Vendor neutrality: this module knows about a JSON file with an `env` block
|
|
23
|
-
* and nothing else. The settings path and the env-var name are BOTH passed
|
|
24
|
-
*
|
|
25
|
-
*
|
|
22
|
+
* 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.
|
|
26
25
|
*/
|
|
27
26
|
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
28
27
|
import { dirname } from 'node:path';
|
|
29
28
|
import { isUserHomeProjectRoot } from '../config/config-safety.js';
|
|
29
|
+
// The link guard — the FILE and the DIRECTORY holding it — lives beside
|
|
30
|
+
// `assertSafeSettingsFile`, the module this slice already trusts for settings
|
|
31
|
+
// path safety. Imported for the write paths below and re-exported so every
|
|
32
|
+
// existing specifier still resolves.
|
|
33
|
+
import { isLinkedSettingsFile } from '../ide/shared/safe-path.js';
|
|
34
|
+
// The bounded vocabulary below (MED-2); one-way import, no cycle.
|
|
35
|
+
import { boundedRawNote } from './harness-percent-ownership.js';
|
|
36
|
+
export { isLinkedSettingsFile };
|
|
30
37
|
/**
|
|
31
38
|
* Peaks-owned opt-out flag, read from the SAME machine-local `env` block the
|
|
32
39
|
* window key is written to.
|
|
@@ -67,191 +74,22 @@ export const HARNESS_WINDOW_SYNC_OPTOUT_VALUE = 'off';
|
|
|
67
74
|
*/
|
|
68
75
|
export const HARNESS_WINDOW_WRITTEN_KEY = 'PEAKS_HARNESS_WINDOW_WRITTEN';
|
|
69
76
|
/**
|
|
70
|
-
* The harness's OWN accepted band for its auto-compact window (
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
* (`Math.min(native, override)`; no Claude model's window exceeds 1000000, so
|
|
79
|
-
* above the maximum the reduction is certain).
|
|
80
|
-
*
|
|
81
|
-
* Either way the outcome is the failure this whole module exists to prevent:
|
|
82
|
-
* peaks-loop divides its ratio by a number the harness is not using, so
|
|
83
|
-
* "85%" names a point the harness will never fire at. A positive integer is
|
|
84
|
-
* therefore NOT sufficient — the band is part of what the value means.
|
|
85
|
-
*
|
|
86
|
-
* Clamping instead was rejected. A clamped write would put a DIFFERENT number
|
|
87
|
-
* in the file from the one the probe just divided by, restoring the
|
|
88
|
-
* two-resolutions drift inside the single write that is supposed to delete it.
|
|
89
|
-
* Refusing keeps the disagreement in one place, reportable, and reported.
|
|
77
|
+
* The harness's OWN accepted band for its auto-compact window (`autoCompactWindow`
|
|
78
|
+
* / its `CLAUDE_CODE_AUTO_COMPACT_WINDOW` shadow: "in tokens from 100000 to
|
|
79
|
+
* 1000000"). Outside it the value is not the window the harness compacts on —
|
|
80
|
+
* below the minimum it is ignored, above it the harness caps it to the model's
|
|
81
|
+
* own window — so peaks-loop would divide its ratio by a number the harness is
|
|
82
|
+
* not using. A positive integer is therefore NOT sufficient; the band is part of
|
|
83
|
+
* what the value means. Clamping was rejected: a clamped write would put a
|
|
84
|
+
* DIFFERENT number in the file from the one the probe divided by.
|
|
90
85
|
*/
|
|
91
86
|
export const HARNESS_WINDOW_MIN_TOKENS = 100_000;
|
|
92
87
|
/** See `HARNESS_WINDOW_MIN_TOKENS`. */
|
|
93
88
|
export const HARNESS_WINDOW_MAX_TOKENS = 1_000_000;
|
|
94
|
-
/**
|
|
95
|
-
* True when `tokens` is a window the harness will actually compact on.
|
|
96
|
-
* `null` (absent / unparseable) is NOT in band — there is no window at all.
|
|
97
|
-
*/
|
|
89
|
+
/** True when `tokens` is a window the harness will actually compact on. */
|
|
98
90
|
export function isHarnessWindowInRange(tokens) {
|
|
99
91
|
return (tokens !== null && tokens >= HARNESS_WINDOW_MIN_TOKENS && tokens <= HARNESS_WINDOW_MAX_TOKENS);
|
|
100
92
|
}
|
|
101
|
-
/**
|
|
102
|
-
* The BAND SENTENCE, in one place: both the write refusal and the read
|
|
103
|
-
* suppression have to say the same thing about the same numbers, and two
|
|
104
|
-
* copies would eventually disagree about the band.
|
|
105
|
-
*/
|
|
106
|
-
function harnessWindowBand() {
|
|
107
|
-
return `${HARNESS_WINDOW_MIN_TOKENS}..${HARNESS_WINDOW_MAX_TOKENS}`;
|
|
108
|
-
}
|
|
109
|
-
/**
|
|
110
|
-
* The ONE wording of "what the harness-window sync just did", for both
|
|
111
|
-
* commands that sync (`peaks code context-now`, `peaks code auto-compact`).
|
|
112
|
-
*
|
|
113
|
-
* Why it lives here rather than inline at each call site: peaks-loop rewrites
|
|
114
|
-
* a file in the user's own harness settings on every probe, and the user
|
|
115
|
-
* accepted that write on one condition — 要告知 (tell me). Two copies of the
|
|
116
|
-
* sentence would mean a future edit tells half the users. This is the only
|
|
117
|
-
* definition; the CLI renders whatever it returns.
|
|
118
|
-
*
|
|
119
|
-
* The `written` branch is the load-bearing one: it names the key, the value,
|
|
120
|
-
* the file, what the value was before, and the exact rollback command, because
|
|
121
|
-
* the harness itself reports an override only through `/autocompact` — if
|
|
122
|
-
* peaks-loop does not say it here, nobody says it.
|
|
123
|
-
*
|
|
124
|
-
* The `skipped` branch is the one that is easy to get wrong, and did: it used
|
|
125
|
-
* to end at the reason token (`Harness window not managed (not-peaks-owned).`),
|
|
126
|
-
* which is true and tells the reader nothing. A refusal can be the exact
|
|
127
|
-
* moment the two sides came apart — the ratio divided by one number while the
|
|
128
|
-
* file pins another — so it is composed from the reason, the two numbers when
|
|
129
|
-
* they disagree, and the raw value when the file's value is not a number at
|
|
130
|
-
* all. See `harnessWindowConflictClause` / `unreadableWindowValueClause`.
|
|
131
|
-
*/
|
|
132
|
-
export function describeHarnessWindowSync(result) {
|
|
133
|
-
if (result === null) {
|
|
134
|
-
return 'The active IDE adapter declares no auto-compact window key; this ratio cannot be tied to the harness trigger.';
|
|
135
|
-
}
|
|
136
|
-
if (result.action === 'written') {
|
|
137
|
-
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\`.`;
|
|
138
|
-
}
|
|
139
|
-
if (result.action === 'skipped') {
|
|
140
|
-
// A refused write is NOT automatically a non-event. The two clauses below
|
|
141
|
-
// are the whole point of refusing to stop at the reason token: each names a
|
|
142
|
-
// concrete NUMBER the user can act on, because "not managed" alone left the
|
|
143
|
-
// reader unable to tell whether the two sides still agreed.
|
|
144
|
-
return `${skippedHarnessWindowClause(result)}${harnessWindowConflictClause(result)}${unreadableWindowValueClause(result)}`;
|
|
145
|
-
}
|
|
146
|
-
// `unchanged` — the file already holds exactly the window this probe divided
|
|
147
|
-
// by, so there is no disagreement to report. What can still be hidden is
|
|
148
|
-
// OWNERSHIP, and it decides what happens when the session outgrows the value.
|
|
149
|
-
// A user upgrading from a release that wrote the key before the provenance
|
|
150
|
-
// marker existed lands here (that is this repository's own state): the value
|
|
151
|
-
// is in force, peaks-loop computes against it, and nothing anywhere said it
|
|
152
|
-
// had become frozen — so "already in force" alone is not a full notice.
|
|
153
|
-
if (!result.peakWritten) {
|
|
154
|
-
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).`;
|
|
155
|
-
}
|
|
156
|
-
return `Harness window ${result.key} already in force; peaks-loop computes this ratio against it.`;
|
|
157
|
-
}
|
|
158
|
-
/**
|
|
159
|
-
* The same disagreement as `harnessWindowConflictClause`, reduced to one line
|
|
160
|
-
* for the `warnings` channel — the machine-readable half of 要告知, so a
|
|
161
|
-
* consumer reading the JSON envelope (or a human reading stderr) sees it even
|
|
162
|
-
* if it never renders `nextActions`. Returns `null` when there is nothing to
|
|
163
|
-
* warn about, which is the ordinary case.
|
|
164
|
-
*/
|
|
165
|
-
export function harnessWindowSyncWarning(result) {
|
|
166
|
-
if (result === null || result.action !== 'skipped')
|
|
167
|
-
return null;
|
|
168
|
-
// E1: the resolved window is not one the harness accepts, so this ratio's
|
|
169
|
-
// denominator is un-anchored no matter what the file holds. Reported FIRST —
|
|
170
|
-
// it is the more fundamental disagreement, and the two clauses below would
|
|
171
|
-
// read as "a different number" rather than "a number the harness cannot use".
|
|
172
|
-
if (result.reason === 'out-of-harness-range') {
|
|
173
|
-
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`;
|
|
174
|
-
}
|
|
175
|
-
if (result.requestedTokens !== null &&
|
|
176
|
-
result.previousTokens !== null &&
|
|
177
|
-
result.requestedTokens !== result.previousTokens) {
|
|
178
|
-
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`;
|
|
179
|
-
}
|
|
180
|
-
if (result.previousTokens === null && result.previousRawValue !== undefined) {
|
|
181
|
-
return `harness window unreadable: ${result.settingsPath} carries ${JSON.stringify(result.previousRawValue)}, which is not a plain token count`;
|
|
182
|
-
}
|
|
183
|
-
return null;
|
|
184
|
-
}
|
|
185
|
-
/**
|
|
186
|
-
* WHY nothing was written, in words — one clause per `reason`.
|
|
187
|
-
*
|
|
188
|
-
* Every reason has its own sentence rather than falling through to
|
|
189
|
-
* `(${reason})`: the bare token was what the user actually saw for the two
|
|
190
|
-
* most common refusals, and it names no value, no file, and no next step.
|
|
191
|
-
* The trailing clause is unreachable for the reasons this module produces
|
|
192
|
-
* today; it exists so a future reason cannot silently degrade to a token.
|
|
193
|
-
*/
|
|
194
|
-
function skippedHarnessWindowClause(result) {
|
|
195
|
-
switch (result.reason) {
|
|
196
|
-
case 'opted-out':
|
|
197
|
-
return 'Harness window not managed (opted-out) — re-enable with `peaks compact harness-window --reenable`.';
|
|
198
|
-
case 'unsafe-project-root':
|
|
199
|
-
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.`;
|
|
200
|
-
case 'no-window-resolved':
|
|
201
|
-
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.';
|
|
202
|
-
case 'out-of-harness-range':
|
|
203
|
-
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.`;
|
|
204
|
-
case 'unreadable-settings':
|
|
205
|
-
return `Harness window not managed: ${result.settingsPath} is not a JSON object peaks-loop can safely edit, so it was left exactly as found.`;
|
|
206
|
-
case 'not-peaks-owned':
|
|
207
|
-
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.`;
|
|
208
|
-
default:
|
|
209
|
-
return `Harness window not managed (${String(result.reason)}).`;
|
|
210
|
-
}
|
|
211
|
-
}
|
|
212
|
-
/**
|
|
213
|
-
* THE DISAGREEMENT SENTENCE — the one the user cannot get anywhere else.
|
|
214
|
-
*
|
|
215
|
-
* peaks-loop divided this probe's ratio by `requestedTokens`, while the
|
|
216
|
-
* harness's own settings file pins `previousTokens`. Neither side is wrong on
|
|
217
|
-
* its own, which is exactly why it went unnoticed: the file wins for the ratio
|
|
218
|
-
* (T1's single-source rule), the write that would have re-unified them was
|
|
219
|
-
* refused (B1's provenance guard), and the result was a percentage computed
|
|
220
|
-
* against a window the harness is not going to fire on. The harness reports an
|
|
221
|
-
* override only through its own `/autocompact`, so if peaks-loop does not name
|
|
222
|
-
* the two numbers here, nobody does.
|
|
223
|
-
*
|
|
224
|
-
* Both numbers and the file are named, and all three ways out are given,
|
|
225
|
-
* because this notice is the whole remedy for a state peaks-loop deliberately
|
|
226
|
-
* refuses to fix by writing.
|
|
227
|
-
*/
|
|
228
|
-
function harnessWindowConflictClause(result) {
|
|
229
|
-
const requested = result.requestedTokens;
|
|
230
|
-
const pinned = result.previousTokens;
|
|
231
|
-
if (result.action !== 'skipped' || requested === null || pinned === null || requested === pinned)
|
|
232
|
-
return '';
|
|
233
|
-
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.`;
|
|
234
|
-
}
|
|
235
|
-
/**
|
|
236
|
-
* The OTHER way two numbers can fail to line up: the file's value is not a
|
|
237
|
-
* number at all (`500k`, a hand-typed typo).
|
|
238
|
-
*
|
|
239
|
-
* `previousTokens` is `null` here — indistinguishable, in the parsed result,
|
|
240
|
-
* from an absent key — so this clause is gated on the RAW value. The
|
|
241
|
-
* disagreement is stated but never "aligned": peaks-loop will not overwrite a
|
|
242
|
-
* value it did not write, and the value is unusable, so the only honest output
|
|
243
|
-
* is to name it and hand the user the two ways out. Silent here would be the
|
|
244
|
-
* worst option of all, because the caller has already fallen back to a
|
|
245
|
-
* different window and the disk keeps claiming `500k` on every probe after it.
|
|
246
|
-
*/
|
|
247
|
-
function unreadableWindowValueClause(result) {
|
|
248
|
-
if (result.action !== 'skipped' ||
|
|
249
|
-
result.previousTokens !== null ||
|
|
250
|
-
result.previousRawValue === undefined)
|
|
251
|
-
return '';
|
|
252
|
-
const raw = JSON.stringify(result.previousRawValue);
|
|
253
|
-
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 saying ${raw}. 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.`;
|
|
254
|
-
}
|
|
255
93
|
/**
|
|
256
94
|
* Parse a candidate window value. Positive finite integers only — a number,
|
|
257
95
|
* or a numeric string (the env block is JSON, so the value on disk is always
|
|
@@ -274,7 +112,7 @@ export function parseHarnessWindowTokens(raw) {
|
|
|
274
112
|
* manage" rather than throwing, because a corrupt local settings file must
|
|
275
113
|
* never break a context probe.
|
|
276
114
|
*/
|
|
277
|
-
function readSettingsObject(settingsPath) {
|
|
115
|
+
export function readSettingsObject(settingsPath) {
|
|
278
116
|
if (!existsSync(settingsPath))
|
|
279
117
|
return null;
|
|
280
118
|
try {
|
|
@@ -341,38 +179,31 @@ export function readHarnessWindow(input) {
|
|
|
341
179
|
const fileRaw = envString(settings, input.location.envVar);
|
|
342
180
|
const fileTokens = parseHarnessWindowTokens(fileRaw);
|
|
343
181
|
const peakWritten = fileTokens !== null && marker === fileTokens;
|
|
182
|
+
// Bounded at the source (MED-2): no result here can carry the plaintext, and
|
|
183
|
+
// the note's presence is what says the file's slot was not empty.
|
|
184
|
+
const fileRawNote = fileRaw === undefined ? undefined : boundedRawNote(fileRaw);
|
|
344
185
|
const fromEnv = input.env?.[input.location.envVar];
|
|
345
|
-
if (fromEnv !== undefined)
|
|
186
|
+
if (fromEnv !== undefined)
|
|
346
187
|
return {
|
|
347
188
|
tokens: parseHarnessWindowTokens(fromEnv),
|
|
348
|
-
raw: fromEnv,
|
|
349
189
|
source: 'process-env',
|
|
350
190
|
optedOut,
|
|
351
191
|
peakWritten,
|
|
352
192
|
fileTokens,
|
|
353
|
-
|
|
193
|
+
...(fileRawNote === undefined ? {} : { fileRawNote }),
|
|
194
|
+
rawNote: boundedRawNote(fromEnv)
|
|
354
195
|
};
|
|
355
|
-
|
|
356
|
-
if (fileRaw !== undefined) {
|
|
196
|
+
if (fileRaw !== undefined)
|
|
357
197
|
return {
|
|
358
198
|
tokens: fileTokens,
|
|
359
|
-
raw: fileRaw,
|
|
360
199
|
source: 'settings-file',
|
|
361
200
|
optedOut,
|
|
362
201
|
peakWritten,
|
|
363
202
|
fileTokens,
|
|
364
|
-
fileRaw
|
|
203
|
+
fileRawNote: boundedRawNote(fileRaw),
|
|
204
|
+
rawNote: boundedRawNote(fileRaw)
|
|
365
205
|
};
|
|
366
|
-
}
|
|
367
|
-
return {
|
|
368
|
-
tokens: null,
|
|
369
|
-
raw: undefined,
|
|
370
|
-
source: null,
|
|
371
|
-
optedOut,
|
|
372
|
-
peakWritten: false,
|
|
373
|
-
fileTokens: null,
|
|
374
|
-
fileRaw: undefined
|
|
375
|
-
};
|
|
206
|
+
return { tokens: null, source: null, optedOut, peakWritten: false, fileTokens: null };
|
|
376
207
|
}
|
|
377
208
|
/**
|
|
378
209
|
* Write `tokens` as the harness's auto-compact window. Idempotent: a re-run
|
|
@@ -391,13 +222,13 @@ export function syncHarnessWindow(input) {
|
|
|
391
222
|
const fileSettings = readSettingsObject(settingsPath);
|
|
392
223
|
const fileRaw = envString(fileSettings, input.location.envVar);
|
|
393
224
|
const fileTokens = parseHarnessWindowTokens(fileRaw);
|
|
394
|
-
// Every branch spreads this, so `requestedTokens` and
|
|
395
|
-
// travel with the outcome
|
|
225
|
+
// Every branch spreads this, so `requestedTokens` and the bounded note about
|
|
226
|
+
// the file's previous value travel with the outcome. Bounded HERE (MED-2).
|
|
396
227
|
const base = {
|
|
397
228
|
settingsPath,
|
|
398
229
|
key: input.location.envVar,
|
|
399
230
|
previousTokens: fileTokens,
|
|
400
|
-
|
|
231
|
+
...(fileRaw === undefined ? {} : { previousRawNote: boundedRawNote(fileRaw) }),
|
|
401
232
|
requestedTokens: input.tokens,
|
|
402
233
|
peakWritten: current.peakWritten
|
|
403
234
|
};
|
|
@@ -426,6 +257,12 @@ export function syncHarnessWindow(input) {
|
|
|
426
257
|
if (!isHarnessWindowInRange(input.tokens)) {
|
|
427
258
|
return { ...base, action: 'skipped', reason: 'out-of-harness-range', tokens: current.tokens };
|
|
428
259
|
}
|
|
260
|
+
// THE LINK GUARD, before the editability test: a symlinked file — or a linked
|
|
261
|
+
// `.claude` directory above an ordinary one — parses fine, so `isEditable`
|
|
262
|
+
// would pass and the write below would follow the link.
|
|
263
|
+
if (isLinkedSettingsFile(settingsPath)) {
|
|
264
|
+
return { ...base, action: 'skipped', reason: 'symlinked-settings', tokens: current.tokens };
|
|
265
|
+
}
|
|
429
266
|
if (!isEditable(settingsPath)) {
|
|
430
267
|
return { ...base, action: 'skipped', reason: 'unreadable-settings', tokens: current.tokens };
|
|
431
268
|
}
|
|
@@ -494,6 +331,13 @@ export function resetHarnessWindow(input) {
|
|
|
494
331
|
const settings = readSettingsObject(settingsPath);
|
|
495
332
|
const previousTokens = parseHarnessWindowTokens(envString(settings, input.location.envVar));
|
|
496
333
|
const markerPresent = envString(settings, HARNESS_WINDOW_WRITTEN_KEY) !== undefined;
|
|
334
|
+
// THE LINK GUARD, before the editability test: a symlinked file — or a linked
|
|
335
|
+
// `.claude` directory above an ordinary one — parses fine, so `isEditable`
|
|
336
|
+
// would pass and the reset below would follow the link.
|
|
337
|
+
if (isLinkedSettingsFile(settingsPath)) {
|
|
338
|
+
// `absent` rather than a throw: the caller renders the `wrote`-nothing case.
|
|
339
|
+
return { settingsPath, action: 'absent', previousTokens };
|
|
340
|
+
}
|
|
497
341
|
if (settings === null || !isEditable(settingsPath)) {
|
|
498
342
|
// Nothing to remove and nothing we can safely edit.
|
|
499
343
|
return { settingsPath, action: 'absent', previousTokens };
|
|
@@ -530,94 +374,12 @@ export function resetHarnessWindow(input) {
|
|
|
530
374
|
return { settingsPath, action: 'removed', previousTokens };
|
|
531
375
|
}
|
|
532
376
|
/**
|
|
533
|
-
*
|
|
534
|
-
*
|
|
535
|
-
*
|
|
536
|
-
* WHY THIS IS A SEPARATE ENTRY POINT AND NOT A FALLBACK OF `resetHarnessWindow`
|
|
537
|
-
*
|
|
538
|
-
* "Remove what is there" and "never write it again" are two different
|
|
539
|
-
* intentions. `--reset` on a file holding no peaks row is deliberately a no-op
|
|
540
|
-
* (see the file-litter note in `resetHarnessWindow`), so a user whose project
|
|
541
|
-
* peaks-loop has never touched had NO command for the second intention at all:
|
|
542
|
-
* they had to wait for a probe to write the key and then remove it — the order
|
|
543
|
-
* backwards. Folding the opt-out into `--reset` would fix that by making one
|
|
544
|
-
* verb mean "delete" or "don't write", depending on whether the file happened
|
|
545
|
-
* to hold a row, which is a verb whose effect the user cannot predict from its
|
|
546
|
-
* name. Two verbs, two intentions, each predictable.
|
|
547
|
-
*
|
|
548
|
-
* WHAT IT DOES NOT DO
|
|
549
|
-
* - it does not touch the window key: a hand-set value stays exactly as it
|
|
550
|
-
* was (peaks-loop would not have overwritten it anyway — see the B1 guard);
|
|
551
|
-
* - it does not write a provenance marker, so it claims no ownership of a
|
|
552
|
-
* value it did not write.
|
|
553
|
-
* The next probe reports `skipped / opted-out` and writes nothing.
|
|
554
|
-
*
|
|
555
|
-
*
|
|
556
|
-
* This function used to exempt itself, on the argument that `--disable` is an
|
|
557
|
-
* explicit instruction and "the location's own file is the only place the
|
|
558
|
-
* opt-out can be recorded for it to mean anything". The first half is true and
|
|
559
|
-
* was never the problem; the second half does not hold at `$HOME`:
|
|
560
|
-
*
|
|
561
|
-
* - the location is NOT usually explicit. `--project` is optional, and a
|
|
562
|
-
* fresh terminal starts in `$HOME`, so the ordinary invocation resolves the
|
|
563
|
-
* root to the user's home directory without them naming it — the very
|
|
564
|
-
* trigger the H1 guard was written for;
|
|
565
|
-
* - the opt-out has NOTHING to mean there. `syncHarnessWindow` already
|
|
566
|
-
* refuses to write the window at that root (`unsafe-project-root`), so the
|
|
567
|
-
* only thing a recorded opt-out changes is which sentence the refusal uses.
|
|
568
|
-
* Nothing is made expressible; a visible refusal is traded for a quieter one;
|
|
569
|
-
* - what IS added is a durable peaks-loop row in `~/.claude/settings.local.json`
|
|
570
|
-
* — a file outside every repo. `--reset`'s exemption does not transfer to
|
|
571
|
-
* this verb: `--reset` REMOVES (and is a no-op when there is nothing of
|
|
572
|
-
* peaks-loop's to remove), while `--disable` only ever ADDS.
|
|
573
|
-
*
|
|
574
|
-
* So the guard fires here exactly as it does in `syncHarnessWindow`: the same
|
|
575
|
-
* exact-home comparison, before any `mkdir` and before any read-modify-write.
|
|
576
|
-
* `~/my-project` is unaffected, and a user who really does carry a stale
|
|
577
|
-
* peaks-loop window key in `$HOME` still has `--reset`, which is allowed there
|
|
578
|
-
* for the reason its own note gives.
|
|
579
|
-
*
|
|
580
|
-
* Idempotent: a second call reports `already-opted-out` and rewrites nothing.
|
|
377
|
+
* The OPT-OUT verbs live in `harness-window-opt-out.ts` — split out when this
|
|
378
|
+
* file's gated excess grew again. Re-exported so every import path stays put.
|
|
581
379
|
*/
|
|
582
|
-
export
|
|
583
|
-
const settingsPath = input.location.settingsPath;
|
|
584
|
-
// Checked FIRST, before `isEditable` and before any directory is created:
|
|
585
|
-
// a refusal that has already mkdir'd `$HOME/.claude` is not a refusal.
|
|
586
|
-
if (input.location.projectRoot !== undefined && isUserHome(input.location.projectRoot)) {
|
|
587
|
-
return { settingsPath, action: 'refused-unsafe-project-root' };
|
|
588
|
-
}
|
|
589
|
-
const settings = readSettingsObject(settingsPath);
|
|
590
|
-
if (!isEditable(settingsPath)) {
|
|
591
|
-
return { settingsPath, action: 'unreadable-settings' };
|
|
592
|
-
}
|
|
593
|
-
const env = typeof settings?.env === 'object' && settings.env !== null && !Array.isArray(settings.env)
|
|
594
|
-
? { ...settings.env }
|
|
595
|
-
: {};
|
|
596
|
-
if (env[HARNESS_WINDOW_SYNC_OPTOUT_KEY] === HARNESS_WINDOW_SYNC_OPTOUT_VALUE) {
|
|
597
|
-
return { settingsPath, action: 'already-opted-out' };
|
|
598
|
-
}
|
|
599
|
-
env[HARNESS_WINDOW_SYNC_OPTOUT_KEY] = HARNESS_WINDOW_SYNC_OPTOUT_VALUE;
|
|
600
|
-
const dir = dirname(settingsPath);
|
|
601
|
-
if (!existsSync(dir))
|
|
602
|
-
mkdirSync(dir, { recursive: true });
|
|
603
|
-
writeFileSync(settingsPath, `${JSON.stringify({ ...(settings ?? {}), env }, null, 2)}\n`, 'utf8');
|
|
604
|
-
return { settingsPath, action: 'disabled' };
|
|
605
|
-
}
|
|
380
|
+
export { disableHarnessWindowSync, reenableHarnessWindowSync } from './harness-window-opt-out.js';
|
|
606
381
|
/**
|
|
607
|
-
*
|
|
608
|
-
*
|
|
382
|
+
* The WINDOW notices live in `harness-window-opt-out.ts` — the same file-size
|
|
383
|
+
* cause as the verbs there. Re-exported so every import path stays put.
|
|
609
384
|
*/
|
|
610
|
-
export
|
|
611
|
-
const settingsPath = input.location.settingsPath;
|
|
612
|
-
const settings = readSettingsObject(settingsPath);
|
|
613
|
-
if (settings === null)
|
|
614
|
-
return { settingsPath, action: 'absent' };
|
|
615
|
-
const env = typeof settings.env === 'object' && settings.env !== null && !Array.isArray(settings.env)
|
|
616
|
-
? { ...settings.env }
|
|
617
|
-
: {};
|
|
618
|
-
if (env[HARNESS_WINDOW_SYNC_OPTOUT_KEY] === undefined)
|
|
619
|
-
return { settingsPath, action: 'absent' };
|
|
620
|
-
delete env[HARNESS_WINDOW_SYNC_OPTOUT_KEY];
|
|
621
|
-
writeFileSync(settingsPath, `${JSON.stringify({ ...settings, env }, null, 2)}\n`, 'utf8');
|
|
622
|
-
return { settingsPath, action: 'reenabled' };
|
|
623
|
-
}
|
|
385
|
+
export { describeHarnessWindowSync, harnessWindowSyncWarning } from './harness-window-opt-out.js';
|
|
@@ -0,0 +1,67 @@
|
|
|
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 { type HarnessWindowLocation, type HarnessWindowSyncResult } from './harness-window-config.js';
|
|
12
|
+
/**
|
|
13
|
+
* Record the opt-out WITHOUT removing anything: "stop managing this key",
|
|
14
|
+
* expressible at any moment — including before peaks-loop has ever written it.
|
|
15
|
+
*
|
|
16
|
+
* WHY THIS IS A SEPARATE ENTRY POINT, NOT A FALLBACK OF `resetHarnessWindow`.
|
|
17
|
+
* `--reset` on a file holding no peaks row is deliberately a no-op, so a project
|
|
18
|
+
* peaks-loop never touched had no command for the second intention; folding it
|
|
19
|
+
* into `--reset` would make one verb mean "delete" or "don't write" depending on
|
|
20
|
+
* whether a row happened to exist. Two verbs, two predictable intentions.
|
|
21
|
+
*
|
|
22
|
+
* WHAT IT DOES NOT DO: it does not touch the window key (a hand-set value stays,
|
|
23
|
+
* as the B1 guard would keep it anyway) and writes no provenance marker, so it
|
|
24
|
+
* claims no ownership. The next probe reports `skipped / opted-out`.
|
|
25
|
+
*
|
|
26
|
+
* Idempotent: a second call reports `already-opted-out` and rewrites nothing.
|
|
27
|
+
*/
|
|
28
|
+
export declare function disableHarnessWindowSync(input: {
|
|
29
|
+
readonly location: HarnessWindowLocation;
|
|
30
|
+
}): {
|
|
31
|
+
readonly settingsPath: string;
|
|
32
|
+
readonly action: 'disabled' | 'already-opted-out' | 'unreadable-settings' | 'refused-unsafe-project-root' | 'symlinked-settings';
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* Undo the opt-out (the companion of `resetHarnessWindow`) so peaks-loop
|
|
36
|
+
* resumes owning the harness window.
|
|
37
|
+
*
|
|
38
|
+
* It WRITES, so the same WHERE guards as `--disable` fire: at `$HOME` it would
|
|
39
|
+
* edit the user's personal settings, and through a link it would edit the
|
|
40
|
+
* victim. Both are reported, never thrown.
|
|
41
|
+
*/
|
|
42
|
+
export declare function reenableHarnessWindowSync(input: {
|
|
43
|
+
readonly location: HarnessWindowLocation;
|
|
44
|
+
}): {
|
|
45
|
+
readonly settingsPath: string;
|
|
46
|
+
readonly action: 'reenabled' | 'absent' | 'refused-unsafe-project-root' | 'symlinked-settings';
|
|
47
|
+
};
|
|
48
|
+
/**
|
|
49
|
+
* The ONE wording of "what the harness-window sync just did", for both commands
|
|
50
|
+
* that sync (`context-now`, `auto-compact`). ONE definition, so a future edit
|
|
51
|
+
* cannot tell half the users — see 要告知 in the module header.
|
|
52
|
+
*
|
|
53
|
+
* The `written` branch names the key, value, file, previous value and the exact
|
|
54
|
+
* rollback, because the harness reports its override only through
|
|
55
|
+
* `/autocompact`. The `skipped` branch is composed from the reason, the two
|
|
56
|
+
* numbers when they disagree, and the raw value when the file's value is not a
|
|
57
|
+
* number — see `harnessWindowConflictClause` / `unreadableWindowValueClause`.
|
|
58
|
+
*/
|
|
59
|
+
export declare function describeHarnessWindowSync(result: HarnessWindowSyncResult | null): string;
|
|
60
|
+
/**
|
|
61
|
+
* The same disagreement as `harnessWindowConflictClause`, reduced to one line
|
|
62
|
+
* for the `warnings` channel — the machine-readable half of 要告知, so a
|
|
63
|
+
* consumer reading the JSON envelope (or a human reading stderr) sees it even
|
|
64
|
+
* if it never renders `nextActions`. Returns `null` when there is nothing to
|
|
65
|
+
* warn about, which is the ordinary case.
|
|
66
|
+
*/
|
|
67
|
+
export declare function harnessWindowSyncWarning(result: HarnessWindowSyncResult | null): string | null;
|