peaks-loop 4.2.3 → 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 +47 -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,18 +12,19 @@
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
  */
26
+ import { isLinkedSettingsFile } from '../ide/shared/safe-path.js';
27
+ export { isLinkedSettingsFile };
27
28
  /**
28
29
  * Peaks-owned opt-out flag, read from the SAME machine-local `env` block the
29
30
  * window key is written to.
@@ -64,34 +65,19 @@ export declare const HARNESS_WINDOW_SYNC_OPTOUT_VALUE = "off";
64
65
  */
65
66
  export declare const HARNESS_WINDOW_WRITTEN_KEY = "PEAKS_HARNESS_WINDOW_WRITTEN";
66
67
  /**
67
- * The harness's OWN accepted band for its auto-compact window (E1, rid
68
- *
69
- * THE BAND IS A PROPERTY OF THE KEY, NOT OF peaks-loop. `autoCompactWindow` —
70
- * and the `CLAUDE_CODE_AUTO_COMPACT_WINDOW` env var that shadows it — is
71
- * documented as "how full the context window gets before Claude Code compacts
72
- * automatically, in tokens from 100000 to 1000000", and a value outside that
73
- * band is not the window the harness compacts on: below the minimum the value
74
- * is ignored, above the maximum it is reduced to the model's own context size
75
- * (`Math.min(native, override)`; no Claude model's window exceeds 1000000, so
76
- * above the maximum the reduction is certain).
77
- *
78
- * Either way the outcome is the failure this whole module exists to prevent:
79
- * peaks-loop divides its ratio by a number the harness is not using, so
80
- * "85%" names a point the harness will never fire at. A positive integer is
81
- * therefore NOT sufficient — the band is part of what the value means.
82
- *
83
- * Clamping instead was rejected. A clamped write would put a DIFFERENT number
84
- * in the file from the one the probe just divided by, restoring the
85
- * two-resolutions drift inside the single write that is supposed to delete it.
86
- * Refusing keeps the disagreement in one place, reportable, and reported.
68
+ * The harness's OWN accepted band for its auto-compact window (`autoCompactWindow`
69
+ * / its `CLAUDE_CODE_AUTO_COMPACT_WINDOW` shadow: "in tokens from 100000 to
70
+ * 1000000"). Outside it the value is not the window the harness compacts on —
71
+ * below the minimum it is ignored, above it the harness caps it to the model's
72
+ * own window — so peaks-loop would divide its ratio by a number the harness is
73
+ * not using. A positive integer is therefore NOT sufficient; the band is part of
74
+ * what the value means. Clamping was rejected: a clamped write would put a
75
+ * DIFFERENT number in the file from the one the probe divided by.
87
76
  */
88
77
  export declare const HARNESS_WINDOW_MIN_TOKENS = 100000;
89
78
  /** See `HARNESS_WINDOW_MIN_TOKENS`. */
90
79
  export declare const HARNESS_WINDOW_MAX_TOKENS = 1000000;
91
- /**
92
- * True when `tokens` is a window the harness will actually compact on.
93
- * `null` (absent / unparseable) is NOT in band — there is no window at all.
94
- */
80
+ /** True when `tokens` is a window the harness will actually compact on. */
95
81
  export declare function isHarnessWindowInRange(tokens: number | null): boolean;
96
82
  /** Where the harness key lives + which key it is. Both caller-supplied. */
97
83
  export interface HarnessWindowLocation {
@@ -123,8 +109,6 @@ export type HarnessWindowValueSource = 'process-env' | 'settings-file';
123
109
  export interface HarnessWindowReadResult {
124
110
  /** Parsed window in tokens, or null when absent / not a positive integer. */
125
111
  readonly tokens: number | null;
126
- /** The raw on-disk / in-env value, for diagnostics. */
127
- readonly raw: unknown;
128
112
  /** Where the value came from; null when neither side carries it. */
129
113
  readonly source: HarnessWindowValueSource | null;
130
114
  /**
@@ -140,15 +124,18 @@ export interface HarnessWindowReadResult {
140
124
  */
141
125
  readonly fileTokens: number | null;
142
126
  /**
143
- * The settings file's raw value, `undefined` when the file carries no such
144
- * key. Presence-detection only; use `fileTokens` for the number.
127
+ * A BOUNDED note about the source's value, present only when that source
128
+ * carried the key — never the raw string (MED-2).
145
129
  *
146
130
  * Needed because "the file says 150000" and "the file says something
147
131
  * unparseable" must both be distinguishable from "the file is silent": the
148
132
  * first two are values peaks-loop must not overwrite, the third is an empty
149
- * slot it may fill.
133
+ * slot it may fill. `tokens` cannot express that (a typo parses to null,
134
+ * exactly like an absent key), so the note's PRESENCE is the missing bit.
150
135
  */
151
- readonly fileRaw: unknown;
136
+ readonly rawNote?: string;
137
+ /** The SAME bounded note for the settings file's value. */
138
+ readonly fileRawNote?: string;
152
139
  /** True when `settings.local.json` opts out of peaks-loop managing it. */
153
140
  readonly optedOut: boolean;
154
141
  /**
@@ -192,6 +179,9 @@ export interface HarnessWindowSyncResult {
192
179
  * without it a stale process env (or any
193
180
  * re-resolution) silently reverts a human's
194
181
  * hand-edited window and re-claims ownership.
182
+ * - `symlinked-settings` — the file, or the `.claude` directory holding it,
183
+ * is a symlink or junction, so a write would
184
+ * follow it into whatever it points at.
195
185
  * - `unsafe-project-root` — the resolved project root IS the user's home
196
186
  * directory, so this write would land in their
197
187
  * personal `~/.claude/settings.local.json`
@@ -226,16 +216,16 @@ export interface HarnessWindowSyncResult {
226
216
  */
227
217
  readonly requestedTokens: number | null;
228
218
  /**
229
- * The file's RAW value for the key before the call; `undefined` when the
230
- * file carried no such key.
219
+ * A BOUNDED description of the file's value before the call (MED-2), present
220
+ * only when the file carried the key — never the raw string, not a prefix.
231
221
  *
232
- * The one case `previousTokens` cannot express: a hand-typed `500k` parses
233
- * to `null`, exactly like an absent key, yet the two need opposite notices —
234
- * an absent key is a slot peaks-loop may fill, a typo is a value it must not
235
- * touch. Only the raw text can be quoted back to the user, so it travels
236
- * with the result.
222
+ * The one case `previousTokens` cannot express: a hand-typed `500k` parses to
223
+ * `null`, exactly like an absent key, yet the two need opposite notices — an
224
+ * absent key is a slot peaks-loop may fill, a typo is a value it must not
225
+ * touch. The note's PRESENCE tells them apart; its text is what the notices
226
+ * print.
237
227
  */
238
- readonly previousRawValue: unknown;
228
+ readonly previousRawNote?: string;
239
229
  /**
240
230
  * True when the window in the file after the call is peaks-loop's own write
241
231
  * (its value matches the provenance marker).
@@ -257,38 +247,6 @@ export type HarnessWindowResetResult = {
257
247
  readonly action: 'removed' | 'absent';
258
248
  readonly previousTokens: number | null;
259
249
  };
260
- /**
261
- * The ONE wording of "what the harness-window sync just did", for both
262
- * commands that sync (`peaks code context-now`, `peaks code auto-compact`).
263
- *
264
- * Why it lives here rather than inline at each call site: peaks-loop rewrites
265
- * a file in the user's own harness settings on every probe, and the user
266
- * accepted that write on one condition — 要告知 (tell me). Two copies of the
267
- * sentence would mean a future edit tells half the users. This is the only
268
- * definition; the CLI renders whatever it returns.
269
- *
270
- * The `written` branch is the load-bearing one: it names the key, the value,
271
- * the file, what the value was before, and the exact rollback command, because
272
- * the harness itself reports an override only through `/autocompact` — if
273
- * peaks-loop does not say it here, nobody says it.
274
- *
275
- * The `skipped` branch is the one that is easy to get wrong, and did: it used
276
- * to end at the reason token (`Harness window not managed (not-peaks-owned).`),
277
- * which is true and tells the reader nothing. A refusal can be the exact
278
- * moment the two sides came apart — the ratio divided by one number while the
279
- * file pins another — so it is composed from the reason, the two numbers when
280
- * they disagree, and the raw value when the file's value is not a number at
281
- * all. See `harnessWindowConflictClause` / `unreadableWindowValueClause`.
282
- */
283
- export declare function describeHarnessWindowSync(result: HarnessWindowSyncResult | null): string;
284
- /**
285
- * The same disagreement as `harnessWindowConflictClause`, reduced to one line
286
- * for the `warnings` channel — the machine-readable half of 要告知, so a
287
- * consumer reading the JSON envelope (or a human reading stderr) sees it even
288
- * if it never renders `nextActions`. Returns `null` when there is nothing to
289
- * warn about, which is the ordinary case.
290
- */
291
- export declare function harnessWindowSyncWarning(result: HarnessWindowSyncResult | null): string | null;
292
250
  /**
293
251
  * Parse a candidate window value. Positive finite integers only — a number,
294
252
  * or a numeric string (the env block is JSON, so the value on disk is always
@@ -298,6 +256,16 @@ export declare function harnessWindowSyncWarning(result: HarnessWindowSyncResult
298
256
  * ignored downstream.
299
257
  */
300
258
  export declare function parseHarnessWindowTokens(raw: unknown): number | null;
259
+ export interface SettingsFileShape {
260
+ readonly env?: Record<string, unknown>;
261
+ }
262
+ /**
263
+ * Read the settings file as a JSON object. Returns null when the file is
264
+ * absent, unparseable, or not an object — the caller treats that as "cannot
265
+ * manage" rather than throwing, because a corrupt local settings file must
266
+ * never break a context probe.
267
+ */
268
+ export declare function readSettingsObject(settingsPath: string): SettingsFileShape | null;
301
269
  /**
302
270
  * Read the window the harness is currently using for auto-compact.
303
271
  *
@@ -341,68 +309,12 @@ export declare function resetHarnessWindow(input: {
341
309
  readonly env?: NodeJS.ProcessEnv | undefined;
342
310
  }): HarnessWindowResetResult;
343
311
  /**
344
- * Record the opt-out WITHOUT removing anything: "stop managing this key",
345
- * expressible at any moment — including before peaks-loop has ever written it.
346
- *
347
- * WHY THIS IS A SEPARATE ENTRY POINT AND NOT A FALLBACK OF `resetHarnessWindow`
348
- *
349
- * "Remove what is there" and "never write it again" are two different
350
- * intentions. `--reset` on a file holding no peaks row is deliberately a no-op
351
- * (see the file-litter note in `resetHarnessWindow`), so a user whose project
352
- * peaks-loop has never touched had NO command for the second intention at all:
353
- * they had to wait for a probe to write the key and then remove it — the order
354
- * backwards. Folding the opt-out into `--reset` would fix that by making one
355
- * verb mean "delete" or "don't write", depending on whether the file happened
356
- * to hold a row, which is a verb whose effect the user cannot predict from its
357
- * name. Two verbs, two intentions, each predictable.
358
- *
359
- * WHAT IT DOES NOT DO
360
- * - it does not touch the window key: a hand-set value stays exactly as it
361
- * was (peaks-loop would not have overwritten it anyway — see the B1 guard);
362
- * - it does not write a provenance marker, so it claims no ownership of a
363
- * value it did not write.
364
- * The next probe reports `skipped / opted-out` and writes nothing.
365
- *
366
- *
367
- * This function used to exempt itself, on the argument that `--disable` is an
368
- * explicit instruction and "the location's own file is the only place the
369
- * opt-out can be recorded for it to mean anything". The first half is true and
370
- * was never the problem; the second half does not hold at `$HOME`:
371
- *
372
- * - the location is NOT usually explicit. `--project` is optional, and a
373
- * fresh terminal starts in `$HOME`, so the ordinary invocation resolves the
374
- * root to the user's home directory without them naming it — the very
375
- * trigger the H1 guard was written for;
376
- * - the opt-out has NOTHING to mean there. `syncHarnessWindow` already
377
- * refuses to write the window at that root (`unsafe-project-root`), so the
378
- * only thing a recorded opt-out changes is which sentence the refusal uses.
379
- * Nothing is made expressible; a visible refusal is traded for a quieter one;
380
- * - what IS added is a durable peaks-loop row in `~/.claude/settings.local.json`
381
- * — a file outside every repo. `--reset`'s exemption does not transfer to
382
- * this verb: `--reset` REMOVES (and is a no-op when there is nothing of
383
- * peaks-loop's to remove), while `--disable` only ever ADDS.
384
- *
385
- * So the guard fires here exactly as it does in `syncHarnessWindow`: the same
386
- * exact-home comparison, before any `mkdir` and before any read-modify-write.
387
- * `~/my-project` is unaffected, and a user who really does carry a stale
388
- * peaks-loop window key in `$HOME` still has `--reset`, which is allowed there
389
- * for the reason its own note gives.
390
- *
391
- * Idempotent: a second call reports `already-opted-out` and rewrites nothing.
312
+ * The OPT-OUT verbs live in `harness-window-opt-out.ts` — split out when this
313
+ * file's gated excess grew again. Re-exported so every import path stays put.
392
314
  */
393
- export declare function disableHarnessWindowSync(input: {
394
- readonly location: HarnessWindowLocation;
395
- }): {
396
- readonly settingsPath: string;
397
- readonly action: 'disabled' | 'already-opted-out' | 'unreadable-settings' | 'refused-unsafe-project-root';
398
- };
315
+ export { disableHarnessWindowSync, reenableHarnessWindowSync } from './harness-window-opt-out.js';
399
316
  /**
400
- * Undo the opt-out (the companion of `resetHarnessWindow`) so peaks-loop
401
- * resumes owning the harness window.
317
+ * The WINDOW notices live in `harness-window-opt-out.ts` — the same file-size
318
+ * cause as the verbs there. Re-exported so every import path stays put.
402
319
  */
403
- export declare function reenableHarnessWindowSync(input: {
404
- readonly location: HarnessWindowLocation;
405
- }): {
406
- readonly settingsPath: string;
407
- readonly action: 'reenabled' | 'absent';
408
- };
320
+ export { describeHarnessWindowSync, harnessWindowSyncWarning } from './harness-window-opt-out.js';