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
@@ -0,0 +1,149 @@
1
+ // The `peaks compact harness-window` REPORTS and their sentences — split out of
2
+ // `compact-harness-window-command.ts` so that file keeps the registrar and the
3
+ // dispatch only. Every body below is the original one, moved.
4
+ import { ok } from 'peaks-loop-shared/result';
5
+ import { printResult } from '../cli-helpers.js';
6
+ import { readHarnessWindowState, resolveHarnessWindowLocation } from '../../services/context/auto-compact-reader.js';
7
+ import { resetHarnessWindow } from '../../services/context/harness-window-config.js';
8
+ import { resolveHarnessCompactThresholdLocation } from '../../services/context/harness-compact-threshold-config.js';
9
+ import { describePercentHalf, readPercentReport } from './compact-harness-window-percent.js';
10
+ // The two verbs that EDIT the opt-out row moved to their own module when this
11
+ // file crossed the 300-raw-line cap; re-exported so the dispatcher's import path
12
+ // and every existing caller stay put.
13
+ export { reportDisableHarnessWindow, reportReenableHarnessWindow } from './compact-harness-window-opt-out.js';
14
+ import { describeHarnessThresholdReset, resetHarnessThreshold } from '../../services/context/harness-compact-threshold-reset.js';
15
+ export function reportUnmanagedHarnessWindow(io, project, json) {
16
+ printResult(io, ok('compact.harness-window', {
17
+ projectRoot: project,
18
+ managed: false,
19
+ message: 'The active IDE adapter declares no auto-compact window key, so peaks-loop cannot tie ' +
20
+ 'the harness window to its own ratio. Nothing was written and there is nothing to roll back.'
21
+ }), json);
22
+ }
23
+ /**
24
+ * The rollback over the PAIR: `--reset` must undo BOTH knobs, because an orphaned
25
+ * percent moves the trigger EARLIER while the opt-out claims nothing is managed.
26
+ * Returns `null` when the adapter declares no percent knob — refusing there would
27
+ * take away the only way back it ever had.
28
+ */
29
+ function runResetHarnessThreshold(project) {
30
+ const thresholdLocation = resolveHarnessCompactThresholdLocation({
31
+ projectRoot: project,
32
+ env: process.env
33
+ });
34
+ return thresholdLocation === null ? null : resetHarnessThreshold({ thresholdLocation });
35
+ }
36
+ function buildResetWindowActions(result, location) {
37
+ return [
38
+ result.action === 'removed'
39
+ ? `Removed ${location.envVar} from ${result.settingsPath} and opted this project out, so later probes stop writing it. Undo with \`peaks compact harness-window --reenable\`.`
40
+ : `Nothing to remove — ${location.envVar} was already absent from ${result.settingsPath}, so nothing was written and no opt-out row was recorded: if a probe writes a window here later, run --reset again to remove it. To say "never manage this key here" WITHOUT waiting for that first write, run \`peaks compact harness-window --disable\`.`
41
+ ];
42
+ }
43
+ /**
44
+ * The envelope's `action` for a threshold reset. A refusal is neither `removed`
45
+ * nor `absent`: it is `refused`, so a consumer reading `action` cannot mistake a
46
+ * write that was DECLINED for one that found nothing to do.
47
+ *
48
+ * `removed` when EITHER knob was removed. Keying off `window.action` alone
49
+ * reported `absent` beside `percent.action: 'removed'` for a percent-only
50
+ * removal (a file whose window was deleted by hand), and — worse — reported
51
+ * `removed` on a REFUSAL whose snapshot was taken before the refusal was
52
+ * decided, because ownership is computed from the file regardless of whether a
53
+ * write follows. A refusal reports no removals at all.
54
+ */
55
+ function thresholdResetAction(threshold) {
56
+ if (threshold.refusal !== undefined)
57
+ return 'refused';
58
+ const removed = threshold.window.action === 'removed' || threshold.percent.action === 'removed';
59
+ return removed ? 'removed' : 'absent';
60
+ }
61
+ /** The threshold half of the reset envelope — both knobs plus the refusal. */
62
+ function buildThresholdResetData(project, location, threshold) {
63
+ // A REFUSAL REMOVED NOTHING. The snapshot's per-knob actions are computed from
64
+ // the file whether or not a write follows, so reporting them as `removed` on
65
+ // a refused call would describe a removal this call declined to perform.
66
+ const refused = threshold.refusal !== undefined;
67
+ return {
68
+ projectRoot: project,
69
+ action: thresholdResetAction(threshold),
70
+ ...(threshold.refusal === undefined ? {} : { reason: threshold.refusal }),
71
+ key: location.envVar,
72
+ settingsPath: threshold.settingsPath,
73
+ previousTokens: threshold.window.previousTokens,
74
+ // The window half is REPORTED too: a rollback that kept a human's window
75
+ // would otherwise look identical to one that removed it.
76
+ window: {
77
+ key: threshold.window.key,
78
+ action: refused ? 'absent' : threshold.window.action,
79
+ ownership: threshold.window.ownership
80
+ },
81
+ // The percent half is REPORTED, not just acted on: a rollback that silently
82
+ // kept a human's value would look identical to one that failed. Its
83
+ // `ownership` is what distinguishes `kept-human` from `absent` on `none`,
84
+ // so a consumer does not have to infer it from the action.
85
+ percent: {
86
+ key: threshold.percent.key,
87
+ action: refused ? 'absent' : threshold.percent.action,
88
+ ownership: threshold.percent.ownership,
89
+ previousPercent: threshold.percent.previousPercent
90
+ },
91
+ optedOut: threshold.optedOut
92
+ };
93
+ }
94
+ export function reportResetHarnessWindow(io, project, location, json) {
95
+ const threshold = runResetHarnessThreshold(project);
96
+ if (threshold === null) {
97
+ // Adapter declares no percent knob — the window is the whole pair.
98
+ const result = resetHarnessWindow({ location, env: process.env });
99
+ printResult(io, ok('compact.harness-window', {
100
+ projectRoot: project,
101
+ action: result.action,
102
+ key: location.envVar,
103
+ settingsPath: result.settingsPath,
104
+ previousTokens: result.previousTokens
105
+ }, [], buildResetWindowActions(result, location)), json);
106
+ return;
107
+ }
108
+ printResult(io, ok('compact.harness-window', buildThresholdResetData(project, location, threshold), [], [describeHarnessThresholdReset(threshold)]), json);
109
+ }
110
+ function buildHarnessWindowStateActions(state, percent) {
111
+ return [
112
+ state?.tokens === null || state?.tokens === undefined
113
+ ? 'No window is set yet. The next `peaks code context-now` probe materializes the window it computes its ratio against.'
114
+ : `peaks-loop computes its context ratio against ${state.tokens} tokens; the harness fires near the end of that window. ${state.peakWritten
115
+ ? 'peaks-loop wrote this value; it may raise it if a session outgrows it.'
116
+ : "This value is not peaks-loop's own write, so peaks-loop will not raise it — it is treated as your setting."}`,
117
+ describePercentHalf(percent),
118
+ 'Rollback: `peaks compact harness-window --reset`.',
119
+ 'Intent-vs-observed calibration: `peaks compact history --json` → windowCalibration.'
120
+ ];
121
+ }
122
+ function buildHarnessWindowStateData(project, location, state, percent) {
123
+ return {
124
+ projectRoot: project,
125
+ managed: true,
126
+ key: location.envVar,
127
+ settingsPath: location.settingsPath,
128
+ tokens: state?.tokens ?? null,
129
+ // Bounded at the service layer's source (MED-2); carry the note through.
130
+ rawNote: state?.rawNote ?? null,
131
+ source: state?.source ?? null,
132
+ optedOut: state?.optedOut ?? false,
133
+ // Provenance: whether this value is peaks-loop's own write or
134
+ // one the user set by hand. It decides whether the late 1M
135
+ // rescue may override it, so it is not just diagnostics.
136
+ peakWritten: state?.peakWritten ?? false,
137
+ // The OTHER half of the pair — the state report is about both knobs.
138
+ percent
139
+ };
140
+ }
141
+ export function reportHarnessWindowState(io, project, location, json) {
142
+ const state = readHarnessWindowState({ projectRoot: project, env: process.env });
143
+ const percent = readPercentReport(project);
144
+ printResult(io, ok('compact.harness-window', buildHarnessWindowStateData(project, location, state, percent), [], buildHarnessWindowStateActions(state, percent)), json);
145
+ }
146
+ /** The one place the command's location is resolved, so the reports share it. */
147
+ export function resolveCommandLocation(project) {
148
+ return resolveHarnessWindowLocation({ projectRoot: project, env: process.env });
149
+ }
@@ -1,10 +1,12 @@
1
1
  import type { WorkspaceInitContext } from './init-context.js';
2
2
  import type { CodegraphAutoStakeOutcome, FirstTimeHooksInstallOutcome } from './init-options.js';
3
+ import type { HarnessCompactThresholdResult } from '../../../services/context/harness-compact-threshold-ensure.js';
3
4
  export type InitEnvelopeParts = {
4
5
  nextActions: string[];
5
6
  warnings: string[];
6
7
  hooksOutcome: FirstTimeHooksInstallOutcome;
7
8
  codegraphAutoOutcome: CodegraphAutoStakeOutcome | null;
9
+ harnessThresholdOutcome: HarnessCompactThresholdResult | null;
8
10
  };
9
11
  /** Collect the envelope's nextActions + warnings in the original push order. */
10
12
  export declare function collectInitEnvelope(ctx: WorkspaceInitContext): Promise<InitEnvelopeParts>;
@@ -3,6 +3,7 @@ import { gcStalePresenceLeases } from '../../../services/skills/presence-lease-s
3
3
  import { hasStandardsCheckedMarker, markStandardsChecked } from '../../../services/standards/missing-standards-detector.js';
4
4
  import { getErrorMessage } from '../../cli-helpers.js';
5
5
  import { stakeCodegraphForInit } from './init-codegraph-stake.js';
6
+ import { ensureInitHarnessThreshold, reportThresholdDespiteNoHooks } from './init-harness-threshold.js';
6
7
  import { resolveFirstTimeHooksInstall } from './init-hooks-decision.js';
7
8
  function pushBindingReplacedAction(nextActions, report) {
8
9
  if (report.previousSessionId !== null && report.bound) {
@@ -199,6 +200,19 @@ export async function collectInitEnvelope(ctx) {
199
200
  pushStandardsActions(nextActions, warnings, ctx);
200
201
  pushProjectScanActions(nextActions, warnings, ctx);
201
202
  markStandardsCheckedIfMissing(ctx);
203
+ // The harness threshold is reconciled AFTER the settings materializer above
204
+ // (that writer owns `hooks`, this one owns two `env` rows) and BEFORE the
205
+ // codegraph stake, so its notice lands next to the other settings news.
206
+ // `--no-claude-hooks` suppresses it: the rows live in the very file that flag
207
+ // tells init not to touch.
208
+ const harnessThresholdOutcome = ensureInitHarnessThreshold(nextActions, warnings, ctx.projectRoot, ctx.options);
209
+ reportThresholdDespiteNoHooks(nextActions, ctx.options);
202
210
  const codegraphAutoOutcome = await stakeCodegraphForInit(nextActions, warnings, ctx.projectRoot);
203
- return { nextActions, warnings, hooksOutcome, codegraphAutoOutcome };
211
+ return {
212
+ nextActions,
213
+ warnings,
214
+ hooksOutcome,
215
+ codegraphAutoOutcome,
216
+ harnessThresholdOutcome
217
+ };
204
218
  }
@@ -50,7 +50,7 @@ async function runWorkspaceInit(options, io) {
50
50
  projectScanError: scan.error
51
51
  };
52
52
  const parts = await collectInitEnvelope(ctx);
53
- printResult(io, ok('workspace.init', buildInitEnvelopeData(ctx, parts.hooksOutcome, parts.codegraphAutoOutcome), parts.warnings, parts.nextActions), options.json);
53
+ printResult(io, ok('workspace.init', buildInitEnvelopeData(ctx, parts.hooksOutcome, parts.codegraphAutoOutcome, parts.harnessThresholdOutcome), parts.warnings, parts.nextActions), options.json);
54
54
  }
55
55
  catch (error) {
56
56
  reportWorkspaceInitFailure(io, error, options);
@@ -1,3 +1,4 @@
1
1
  import type { WorkspaceInitContext } from './init-context.js';
2
2
  import type { CodegraphAutoStakeOutcome, FirstTimeHooksInstallOutcome } from './init-options.js';
3
- export declare function buildInitEnvelopeData(ctx: WorkspaceInitContext, hooksOutcome: FirstTimeHooksInstallOutcome, codegraphAutoOutcome: CodegraphAutoStakeOutcome | null): Record<string, unknown>;
3
+ import type { HarnessCompactThresholdResult } from '../../../services/context/harness-compact-threshold-ensure.js';
4
+ export declare function buildInitEnvelopeData(ctx: WorkspaceInitContext, hooksOutcome: FirstTimeHooksInstallOutcome, codegraphAutoOutcome: CodegraphAutoStakeOutcome | null, harnessThresholdOutcome?: HarnessCompactThresholdResult | null): Record<string, unknown>;
@@ -1,4 +1,4 @@
1
- export function buildInitEnvelopeData(ctx, hooksOutcome, codegraphAutoOutcome) {
1
+ export function buildInitEnvelopeData(ctx, hooksOutcome, codegraphAutoOutcome, harnessThresholdOutcome = null) {
2
2
  const { report, rotation, projectScanEnvelope, projectScanError } = ctx;
3
3
  return {
4
4
  ...report,
@@ -19,6 +19,23 @@ export function buildInitEnvelopeData(ctx, hooksOutcome, codegraphAutoOutcome) {
19
19
  ...(hooksOutcome.reason !== undefined ? { reason: hooksOutcome.reason } : {})
20
20
  },
21
21
  ...(codegraphAutoOutcome !== null ? { codegraphAutoStake: codegraphAutoOutcome } : {}),
22
+ // The harness pair (window + percent) `init` just reconciled. Omitted, not
23
+ // null, when the adapter declares no such knobs ("not applicable" and "tried
24
+ // and failed" differ; the failure half rides `warnings`).
25
+ //
26
+ // Carried AS IS: the service layer bounds every settings-file value at its
27
+ // source (MED-2), so each half already holds `previousRawNote`. No mapping
28
+ // here — a result that never holds the plaintext cannot leak it, even to a
29
+ // consumer that logs the returned object itself.
30
+ ...(harnessThresholdOutcome !== null
31
+ ? {
32
+ harnessThreshold: {
33
+ settingsPath: harnessThresholdOutcome.settingsPath,
34
+ window: harnessThresholdOutcome.window,
35
+ percent: harnessThresholdOutcome.percent
36
+ }
37
+ }
38
+ : {}),
22
39
  // for the .peaks/project-scan/ bootstrap. Always present
23
40
  // (even when skipped / errored) so downstream readers can
24
41
  // rely on the shape.
@@ -0,0 +1,30 @@
1
+ import { type HarnessCompactThresholdResult } from '../../../services/context/harness-compact-threshold-ensure.js';
2
+ /**
3
+ * Reconcile the project's harness compact threshold and report it.
4
+ *
5
+ * Returns the value the envelope carries (`null` when the active adapter
6
+ * declares no pair of knobs), so a consumer can read the outcome rather than
7
+ * parse the prose.
8
+ *
9
+ * `--no-claude-hooks` SUPPRESSES THE WRITE ENTIRELY. That flag promises init
10
+ * will not touch the harness settings file, and `.claude/settings.local.json`
11
+ * IS that file (`tests/integration/five-new-rids-e2e.test.ts` pins it: after an init
12
+ * with the flag, the file does not exist). An earlier shape of this reconcile
13
+ * wrote the two `env` rows anyway and merely SAID so — honest prose around a
14
+ * write the flag forbids, which is still the flag being broken. The rows are
15
+ * written by the next plain init instead, so nothing is lost.
16
+ */
17
+ export declare function ensureInitHarnessThreshold(nextActions: string[], warnings: string[], projectRoot: string, options?: {
18
+ readonly claudeHooks?: boolean | undefined;
19
+ }): HarnessCompactThresholdResult | null;
20
+ /**
21
+ * Say what `--no-claude-hooks` did to the threshold reconcile.
22
+ *
23
+ * The flag SUPPRESSES the write (see `ensureInitHarnessThreshold`), so silence
24
+ * here would leave the envelope's `harnessThreshold: null` reading as "the
25
+ * adapter declares no knobs" rather than "you asked init not to touch the
26
+ * settings file". Named so the omission is a stated fact.
27
+ */
28
+ export declare function reportThresholdDespiteNoHooks(nextActions: string[], options: {
29
+ readonly claudeHooks?: boolean | undefined;
30
+ }): void;
@@ -0,0 +1,134 @@
1
+ // Split out of `workspace/init-actions.ts`: the harness auto-compact threshold
2
+ // reconciliation `peaks workspace init` performs, so that installing peaks-loop
3
+ // in a downstream project leaves that project configured for early compaction
4
+ // (window + percent, in the project's own `.claude/settings.local.json`).
5
+ //
6
+ // FAIL-SOFT, ALWAYS. An init must not abort because a settings file is
7
+ // unreadable or an adapter declares no knob: every outcome lands in
8
+ // `nextActions` (a write) or `warnings` (a refusal worth seeing), and nothing
9
+ // thrown escapes this module. The one thing it never does is write to the
10
+ // user's global `~/.claude/settings.json` — the location it is handed is the
11
+ // project's, and the shared home-directory guard refuses `$HOME` as a root.
12
+ import { describeHarnessCompactThreshold, describeHarnessThresholdRefusal, describeHarnessThresholdWindowRefusal, describeWindowOnly, ensureHarnessCompactThreshold } from '../../../services/context/harness-compact-threshold-ensure.js';
13
+ import { resolveHarnessCompactThresholdLocation } from '../../../services/context/harness-compact-threshold-config.js';
14
+ import { getErrorMessage } from '../../cli-helpers.js';
15
+ /**
16
+ * Reconcile the project's harness compact threshold and report it.
17
+ *
18
+ * Returns the value the envelope carries (`null` when the active adapter
19
+ * declares no pair of knobs), so a consumer can read the outcome rather than
20
+ * parse the prose.
21
+ *
22
+ * `--no-claude-hooks` SUPPRESSES THE WRITE ENTIRELY. That flag promises init
23
+ * will not touch the harness settings file, and `.claude/settings.local.json`
24
+ * IS that file (`tests/integration/five-new-rids-e2e.test.ts` pins it: after an init
25
+ * with the flag, the file does not exist). An earlier shape of this reconcile
26
+ * wrote the two `env` rows anyway and merely SAID so — honest prose around a
27
+ * write the flag forbids, which is still the flag being broken. The rows are
28
+ * written by the next plain init instead, so nothing is lost.
29
+ */
30
+ export function ensureInitHarnessThreshold(nextActions, warnings, projectRoot, options = {}) {
31
+ if (options.claudeHooks === false)
32
+ return null;
33
+ try {
34
+ const location = resolveHarnessCompactThresholdLocation({
35
+ projectRoot,
36
+ env: process.env
37
+ });
38
+ if (location === null)
39
+ return null;
40
+ const result = ensureHarnessCompactThreshold({ location, env: process.env });
41
+ const notice = describeHarnessCompactThreshold(result);
42
+ // ROUTED BY OUTCOME, ON TWO CHANNELS. The old shape had one predicate
43
+ // (`written || skipped`) and pushed ONE string, so a refusal travelled as a
44
+ // warning that could open with "WROTE <windowKey>=<n>".
45
+ //
46
+ // - `written` (either knob) changed the project's own harness settings, and
47
+ // the harness reports its threshold only through `/autocompact`, so it is
48
+ // news: `nextActions`.
49
+ // - `unchanged` is SILENT, including a hand pin. The file already holds the
50
+ // value this call would write, so "already in force" is the honest answer
51
+ // and repeating it on every re-init is noise — not a refusal, because
52
+ // nothing is unconfigured.
53
+ // - `skipped` is a REFUSAL: the project is NOT configured, which is what
54
+ // this slice promises on install, so it goes to `warnings` as a refusal
55
+ // sentence of its own.
56
+ //
57
+ // THE WINDOW HALF COUNTS AS A WRITE. The two knobs are two separate writes,
58
+ // so a project with a hand-set percent and no window gets the window written
59
+ // while the percent reports `unchanged`; gating on the percent alone swallowed
60
+ // that write and said nothing about it.
61
+ //
62
+ // AND THE WINDOW HALF CAN BE REFUSED ON ITS OWN. Routing only the percent's
63
+ // `skipped` left a project whose window was refused (an out-of-band `50000`,
64
+ // say) with NO warning at all — and with a hand-set percent it produced
65
+ // complete silence about a project that is not configured. So BOTH halves are
66
+ // checked, and the notices are composed once, here, so a write announcement
67
+ // and a refusal can never be printed as two competing paragraphs.
68
+ const windowWritten = result.window.action === 'written';
69
+ const percentWritten = result.percent.action === 'written';
70
+ // THE WRITE CHANNEL, one line for whichever half wrote. When BOTH wrote, the
71
+ // combined describer folds the window clause into the percent write; when a
72
+ // half was REFUSED the combined sentence carries no clause about it (the
73
+ // describer only mentions a window that WROTE), so it can never open with a
74
+ // write under a refusal — the refusal travels on its own channel below.
75
+ const refusal = thresholdRefusal(result);
76
+ if (percentWritten) {
77
+ nextActions.push(notice);
78
+ }
79
+ else if (windowWritten) {
80
+ nextActions.push(describeWindowOnly(result));
81
+ }
82
+ // THE REFUSAL CHANNEL: one warning that names WHICH half failed and why.
83
+ // "Harness threshold not managed: …" alone can read as one knob's footnote
84
+ // rather than the install's outcome, so the init-level frame says the thing
85
+ // a reader of `warnings` has to act on: the install left this project NOT
86
+ // fully configured. It never carries a write clause — the write is announced
87
+ // on `nextActions`, so the warning cannot open with `WROTE …`.
88
+ if (refusal !== null) {
89
+ warnings.push(`harness auto-compact threshold: the project is NOT fully configured — ${refusal}`);
90
+ }
91
+ return result;
92
+ }
93
+ catch (err) {
94
+ warnings.push(`harness auto-compact threshold not configured: ${getErrorMessage(err)}`);
95
+ return null;
96
+ }
97
+ }
98
+ /**
99
+ * The refusal sentence for whichever half was refused, or null when neither was.
100
+ *
101
+ * BOTH HALVES are checked. Routing only the percent's `skipped` (the shape this
102
+ * slice shipped) left a project whose WINDOW was refused — an out-of-band
103
+ * `50000`, say — with no notice at all, and with a hand-set percent it produced
104
+ * complete silence about a project that is not configured.
105
+ */
106
+ function thresholdRefusal(result) {
107
+ const clauses = [];
108
+ if (result.percent.action === 'skipped') {
109
+ // The percent describer already opens with its own "Harness threshold not
110
+ // managed" frame, so it is used as-is.
111
+ clauses.push(describeHarnessThresholdRefusal(result));
112
+ }
113
+ if (result.window.action === 'skipped') {
114
+ // The window describer is CLAUSE-ONLY (no frame), so the one frame is
115
+ // supplied here and the two halves cannot stack "not managed" twice.
116
+ clauses.push(`Harness window not managed — ${describeHarnessThresholdWindowRefusal(result)}`);
117
+ }
118
+ return clauses.length === 0 ? null : clauses.join(' ');
119
+ }
120
+ /**
121
+ * Say what `--no-claude-hooks` did to the threshold reconcile.
122
+ *
123
+ * The flag SUPPRESSES the write (see `ensureInitHarnessThreshold`), so silence
124
+ * here would leave the envelope's `harnessThreshold: null` reading as "the
125
+ * adapter declares no knobs" rather than "you asked init not to touch the
126
+ * settings file". Named so the omission is a stated fact.
127
+ */
128
+ export function reportThresholdDespiteNoHooks(nextActions, options) {
129
+ if (options.claudeHooks !== false)
130
+ return;
131
+ nextActions.push('The harness auto-compact threshold (window + percent) was NOT written: ' +
132
+ '--no-claude-hooks skips .claude/settings.local.json entirely, and those rows live ' +
133
+ 'in the same file. A later `peaks workspace init` without the flag configures them.');
134
+ }
@@ -29,7 +29,7 @@ export declare function readHarnessWindowState(input: {
29
29
  readonly env?: NodeJS.ProcessEnv | undefined;
30
30
  }): HarnessWindowReadResult | null;
31
31
  /**
32
- * The RAW window peaks-loop's context ratio must divide by — T1's number.
32
+ * The window peaks-loop's context ratio must divide by — T1's number, PARSED.
33
33
  *
34
34
  * The SETTINGS FILE is the source of truth, so its value wins whenever it has
35
35
  * one; the env-first read is consulted only when the file is silent (no key
@@ -45,11 +45,12 @@ export declare function readHarnessWindowState(input: {
45
45
  * configured window one number BY CONSTRUCTION, with no write required. The
46
46
  * write is then free to be gated on provenance (see `syncHarnessWindow`).
47
47
  *
48
- * Falls back to `undefined` (no harness layer at all) when the adapter
49
- * declares no knob or neither side carries the key — the adapter then resolves
50
- * its own window exactly as it did before this slice.
48
+ * `null` (no harness layer) when the adapter declares no knob, neither side
49
+ * carries the key, or the value is not a plain in-band count. A PARSED number
50
+ * is what the adapter's `harness-env` layer consumes — never the raw text,
51
+ * which could be anything the user typed (MED-2).
51
52
  */
52
- export declare function resolveHarnessRatioWindow(state: HarnessWindowReadResult | null): unknown;
53
+ export declare function resolveHarnessRatioWindow(state: HarnessWindowReadResult | null): number | null;
53
54
  /**
54
55
  * Materialize a window into the harness's own settings, so the number
55
56
  * peaks-loop divides by and the number the harness compacts against are one
@@ -29,7 +29,7 @@ import { join } from 'node:path';
29
29
  import { detectIdeFromEnv } from './ide-detect.js';
30
30
  import { getAdapter } from '../ide/ide-registry.js';
31
31
  import { readContextWindowTokensOverride } from '../config/config-service.js';
32
- import { isHarnessWindowInRange, parseHarnessWindowTokens, readHarnessWindow, syncHarnessWindow } from './harness-window-config.js';
32
+ import { isHarnessWindowInRange, readHarnessWindow, syncHarnessWindow } from './harness-window-config.js';
33
33
  /**
34
34
  * Resolve WHERE the harness auto-compact window lives, for the IDE the
35
35
  * current env selects. Returns `null` when either half is undeclared:
@@ -73,7 +73,7 @@ export function readHarnessWindowState(input) {
73
73
  return readHarnessWindow({ location, env: input.env ?? process.env });
74
74
  }
75
75
  /**
76
- * The RAW window peaks-loop's context ratio must divide by — T1's number.
76
+ * The window peaks-loop's context ratio must divide by — T1's number, PARSED.
77
77
  *
78
78
  * The SETTINGS FILE is the source of truth, so its value wins whenever it has
79
79
  * one; the env-first read is consulted only when the file is silent (no key
@@ -89,30 +89,27 @@ export function readHarnessWindowState(input) {
89
89
  * configured window one number BY CONSTRUCTION, with no write required. The
90
90
  * write is then free to be gated on provenance (see `syncHarnessWindow`).
91
91
  *
92
- * Falls back to `undefined` (no harness layer at all) when the adapter
93
- * declares no knob or neither side carries the key — the adapter then resolves
94
- * its own window exactly as it did before this slice.
92
+ * `null` (no harness layer) when the adapter declares no knob, neither side
93
+ * carries the key, or the value is not a plain in-band count. A PARSED number
94
+ * is what the adapter's `harness-env` layer consumes — never the raw text,
95
+ * which could be anything the user typed (MED-2).
95
96
  */
96
97
  export function resolveHarnessRatioWindow(state) {
97
98
  if (state === null)
98
- return undefined;
99
+ return null;
99
100
  // is not a window, however well-formed an integer it is — the harness ignores
100
101
  // or caps it, so handing it over here would make the ratio's denominator a
101
- // number the harness is not compacting on. This is the read half of the same
102
- // guard the writer applies before planting one; without it, a value already on
103
- // disk (hand-planted, or written by a release that predates the band) would
104
- // keep poisoning the ratio on every probe.
105
- //
106
- // The two NULLs are deliberate and different: an out-of-band value is refused
107
- // here (the adapter falls through to its own resolution and the writer's
108
- // notice names the skipped number), while an UNPARSEABLE one is still handed
109
- // over — the adapter validates it and warns about a hand-edited `500k`, which
110
- // is a closer reading of the user's intent than silently ignoring it.
111
- const raw = state.fileRaw !== undefined ? state.fileRaw : state.raw;
112
- const tokens = parseHarnessWindowTokens(raw);
113
- if (tokens !== null && !isHarnessWindowInRange(tokens))
114
- return undefined;
115
- return raw;
102
+ // number the harness is not compacting on. The read half of the same guard the
103
+ // writer applies before planting one; without it, a value already on disk
104
+ // (hand-planted, or from a release predating the band) keeps poisoning the
105
+ // ratio. Handing over the PARSED number also keeps user-writable text off the
106
+ // probe (MED-2): an unparseable value is simply no harness layer.
107
+ const tokens = state.fileTokens ?? state.tokens;
108
+ if (tokens === null)
109
+ return null;
110
+ if (!isHarnessWindowInRange(tokens))
111
+ return null;
112
+ return tokens;
116
113
  }
117
114
  /**
118
115
  * Materialize a window into the harness's own settings, so the number
@@ -196,10 +193,9 @@ export function readContextPercent(input) {
196
193
  // path + key. `null` (no knob declared, or the key absent) leaves the
197
194
  // adapter's chain byte-identical to before this slice.
198
195
  //
199
- // The RAW value is handed over, not the parsed one: the adapter validates
200
- // it (`parseContextWindowOverride`) and warns on a bad hand-edited value,
201
- // so parsing here too would be a second, silently-disagreeing parser —
202
- // exactly the duplicated-resolution shape this slice exists to delete.
196
+ // PARSED, never the raw text (MED-2): a settings key can hold anything, and
197
+ // this probe's result reaches logs. An unparseable hand edit is `null` and
198
+ // leaves the adapter's chain unchanged; the writer's notice names the typo.
203
199
  const harnessWindowState = readHarnessWindowState({ projectRoot: input.projectRoot, env });
204
200
  const harnessWindowTokens = resolveHarnessRatioWindow(harnessWindowState);
205
201
  // Primary: read the adapter-declared env-var (no hard-coded IDE names).
@@ -219,7 +215,8 @@ export function readContextPercent(input) {
219
215
  //
220
216
  // hands the adapter the raw `context.windowTokens` config override, so
221
217
  // the adapter's window resolver can prefer an explicit user value over
222
- // its model-name heuristics (the env override arrives via `env`).
218
+ // its model-name heuristics (the env override arrives via `env`). The
219
+ // harness window below travels PARSED — never the settings file's text.
223
220
  const fallback = adapter.compact.readContextPercentFallback?.({
224
221
  projectRoot: input.projectRoot,
225
222
  sessionId: input.sessionId,
@@ -230,7 +227,7 @@ export function readContextPercent(input) {
230
227
  // divides by the very number the harness compacts against — plus whether
231
228
  // peaks-loop is the one that wrote it, so the adapter may self-correct
232
229
  // its own earlier resolution without ever overruling a human's pin.
233
- ...(harnessWindowTokens !== undefined
230
+ ...(harnessWindowTokens !== null
234
231
  ? {
235
232
  harnessWindowTokens,
236
233
  harnessWindowPeakWritten: harnessWindowState?.peakWritten === true