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.
Files changed (51) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +109 -0
  3. package/dist/cli/commands/code-context-now-command.js +8 -3
  4. package/dist/cli/commands/code-context-now-envelope.d.ts +27 -2
  5. package/dist/cli/commands/code-context-now-envelope.js +47 -2
  6. package/dist/cli/commands/compact-harness-window-command.js +19 -111
  7. package/dist/cli/commands/compact-harness-window-opt-out.d.ts +4 -0
  8. package/dist/cli/commands/compact-harness-window-opt-out.js +76 -0
  9. package/dist/cli/commands/compact-harness-window-percent.d.ts +39 -0
  10. package/dist/cli/commands/compact-harness-window-percent.js +78 -0
  11. package/dist/cli/commands/compact-harness-window-reports.d.ts +8 -0
  12. package/dist/cli/commands/compact-harness-window-reports.js +149 -0
  13. package/dist/cli/commands/workspace/init-actions.d.ts +2 -0
  14. package/dist/cli/commands/workspace/init-actions.js +15 -1
  15. package/dist/cli/commands/workspace/init-command.js +1 -1
  16. package/dist/cli/commands/workspace/init-envelope.d.ts +2 -1
  17. package/dist/cli/commands/workspace/init-envelope.js +18 -1
  18. package/dist/cli/commands/workspace/init-harness-threshold.d.ts +30 -0
  19. package/dist/cli/commands/workspace/init-harness-threshold.js +134 -0
  20. package/dist/services/context/auto-compact-reader.d.ts +6 -5
  21. package/dist/services/context/auto-compact-reader.js +24 -27
  22. package/dist/services/context/harness-compact-threshold-config.d.ts +178 -0
  23. package/dist/services/context/harness-compact-threshold-config.js +166 -0
  24. package/dist/services/context/harness-compact-threshold-ensure.d.ts +90 -0
  25. package/dist/services/context/harness-compact-threshold-ensure.js +158 -0
  26. package/dist/services/context/harness-compact-threshold-refusal.d.ts +39 -0
  27. package/dist/services/context/harness-compact-threshold-refusal.js +122 -0
  28. package/dist/services/context/harness-compact-threshold-reset-types.d.ts +59 -0
  29. package/dist/services/context/harness-compact-threshold-reset-types.js +9 -0
  30. package/dist/services/context/harness-compact-threshold-reset.d.ts +48 -0
  31. package/dist/services/context/harness-compact-threshold-reset.js +215 -0
  32. package/dist/services/context/harness-compact-threshold-verdict.d.ts +71 -0
  33. package/dist/services/context/harness-compact-threshold-verdict.js +124 -0
  34. package/dist/services/context/harness-percent-gates.d.ts +35 -0
  35. package/dist/services/context/harness-percent-gates.js +102 -0
  36. package/dist/services/context/harness-percent-ownership.d.ts +126 -0
  37. package/dist/services/context/harness-percent-ownership.js +200 -0
  38. package/dist/services/context/harness-settings-file.d.ts +70 -0
  39. package/dist/services/context/harness-settings-file.js +83 -0
  40. package/dist/services/context/harness-window-config.d.ts +53 -141
  41. package/dist/services/context/harness-window-config.js +58 -296
  42. package/dist/services/context/harness-window-opt-out.d.ts +67 -0
  43. package/dist/services/context/harness-window-opt-out.js +241 -0
  44. package/dist/services/context/harness-window-ownership.d.ts +49 -0
  45. package/dist/services/context/harness-window-ownership.js +130 -0
  46. package/dist/services/ide/adapters/claude-code-adapter.d.ts +9 -9
  47. package/dist/services/ide/adapters/claude-code-adapter.js +5 -5
  48. package/dist/services/ide/ide-compact-types.d.ts +23 -4
  49. package/dist/services/ide/shared/safe-path.d.ts +18 -0
  50. package/dist/services/ide/shared/safe-path.js +34 -1
  51. 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 of the fix: the harness itself accepts a
16
- * window override (`IdeCompactProfile.autoCompactWindowEnvVar`, declared per
17
- * adapter — no IDE names here), so peaks-loop writes the very number it
18
- * computes the ratio against into the harness's own machine-local settings
19
- * file. Reader and writer then reference one artifact instead of two
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
- * in by the caller, resolved from the IDE adapter's declarations. There is
25
- * no IDE id, no `.claude` literal, and no registry import in this file.
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 (E1, rid
71
- *
72
- * THE BAND IS A PROPERTY OF THE KEY, NOT OF peaks-loop. `autoCompactWindow` —
73
- * and the `CLAUDE_CODE_AUTO_COMPACT_WINDOW` env var that shadows it — is
74
- * documented as "how full the context window gets before Claude Code compacts
75
- * automatically, in tokens from 100000 to 1000000", and a value outside that
76
- * band is not the window the harness compacts on: below the minimum the value
77
- * is ignored, above the maximum it is reduced to the model's own context size
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
- fileRaw
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 `previousRawValue`
395
- // travel with the outcome rather than being re-derived by each consumer.
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
- previousRawValue: fileRaw,
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
- * Record the opt-out WITHOUT removing anything: "stop managing this key",
534
- * expressible at any moment — including before peaks-loop has ever written it.
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 function disableHarnessWindowSync(input) {
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
- * Undo the opt-out (the companion of `resetHarnessWindow`) so peaks-loop
608
- * resumes owning the harness window.
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 function reenableHarnessWindowSync(input) {
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;