peaks-loop 4.0.46 → 4.0.48

package/dist/services/evidence/evidence-generator.js

@@ -7,22 +7,34 @@
  * gates plus the verify-pipeline, so the orchestrator no longer hand-writes
  * them per mechanical file-split (or similar) slice.
  *
- * The content markers emitted here are the exact strings the CLI gates +
- * verify-pipeline mechanically check — see
- * `src/services/artifacts/artifact-prerequisites.ts` (mustContain /
- * mustContainAny / headingMustContain) and
- * `src/services/workflow/pipeline-verify-gate-support.ts` +
- * `src/services/workflow/artifact-paths.ts` (suffixed security/performance
- * findings). Do NOT reword the marker lines.
+ * The content markers emitted here are the exact strings the CLI gates
+ * mechanically check — see `src/services/artifacts/artifact-prerequisites.ts`
+ * (mustContain / mustContainAny / headingMustContain — the authoritative
+ * table). `peaks workflow verify-pipeline` reads that same table for both the
+ * evidence paths it probes and the markers it enforces
+ * (`src/services/workflow/pipeline-verify-gate-support.ts#contractEvidencePaths`).
+ * Do NOT reword the marker lines.
+ *
+ * This paragraph used to send editors to `src/services/workflow/artifact-paths.ts`
+ * as the checker of "suffixed security/performance findings". That is no longer
+ * true: the `security-findings-<rid>.md` / `performance-findings-<rid>.md` gates
+ * were removed in rid `2026-09-14-verify-pipeline-contract-drift` (no
+ * `qa:verdict-issued` table names those paths; security and perf evidence is
+ * resolved on the RD side at `audit/security-<rid>.md` / `audit/perf-<rid>.md`),
+ * and `artifact-paths.ts` has had zero code consumers since. It is not a marker
+ * authority, so it is not a pointer worth keeping.
  *
  * Karpathy §2 (Simplicity First): a single generator function + a handful of
  * pure body builders. No speculative options, no validation beyond what the
  * reference prototype performs.
  */
-import { createHash } from 'node:crypto';
 import { mkdir, readdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { serializeHandoffFrontmatter } from '../prd/handoff-frontmatter.js';
+import { handoffRelativePath, sha256OfBody } from '../prd/handoff-service.js';
 import { getSessionDir } from '../session/getSessionDir.js';
+import { REQUEST_ID_PATTERN } from '../artifacts/request-artifact-service.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
 /** Comma/space tolerant `--files` splitter. */
 export function parseFiles(raw) {
     return raw
@@ -235,40 +247,20 @@ function buildQaRequest(rid, sid, files) {
 `;
 }
 /**
- * Build the `prd/handoff.md` frontmatter + body and compute the sha256
- * fingerprint. The hash is computed over the frontmatter (with the
- * `handoffHash` line left empty — `sha256:`) concatenated with the body,
- * matching the reference prototype exactly.
+ * Build the `prd/handoff-<rid>.md` frontmatter + body. The frontmatter comes from the
+ * ONE canonical serializer and `handoffHash === sha256(body)` — the same
+ * pairing `handoff-service.initHandoff` and `handoff-auto-regen.ts` use, so
+ * this producer cannot drift from them.
+ *
+ * This function used to hand-roll a third, divergent frontmatter: a
+ * `handoffHash: sha256:<hex>` value with **no line beginning `sha256:`**, over
+ * a hash computed on `frontmatter + body` rather than the body. The
+ * `AUDIT_REQUIRES_HANDOFF` gate (a substring check) accepted that file while
+ * `readAndVerifyHandoff` in both audit skills returned `null` — the very
+ * producer/consumer divergence rid `2026-09-14-handoff-writer-gate-divergence`
+ * exists to remove, surviving in a function the same slice edited.
  */
 function buildHandoff(rid, sid, title, files, lineCounts) {
-    const bulletList = files.map((f) => `  - ${f}`).join('\n');
-    const frontmatter = `---
-requestId: ${rid}
-scope:
-${bulletList}
-files:
-${bulletList}
-handoffPath: .peaks/_runtime/${sid}/prd/handoff.md
-handoffHash: sha256:PLACEHOLDER
-decisions:
-  - id: D1
-    summary: "Mechanical verbatim module split"
-    rationale: "Satisfy the 800-line file-size gate."
-risks:
-  - id: R1
-    description: "Public exports may be imported elsewhere"
-    mitigation: "Import sites updated; tsc clean."
-nextActions:
-  - "peaks-qa validates the regression matrix"
-gateEvidence:
-  projectScan: .peaks/project-scan/project-scan.md
-  prdHandoff: .peaks/_runtime/${sid}/prd/handoff.md
-  codeReview: .peaks/_runtime/${sid}/rd/code-review.md
-  securityReview: .peaks/_runtime/${sid}/rd/security-review.md
-  perfBaseline: .peaks/_runtime/${sid}/audit/perf.md
-schemaVersion: 2
----
-`;
     const body = `# PRD Handoff — ${rid}
 
 ${title}. Mechanical verbatim module split; behavior-preserving.
@@ -279,10 +271,19 @@ ${filesMd(files)}
 Line counts:
 ${lineCountsMd(lineCounts)}
 `;
-    const hashInput = frontmatter.replace('sha256:PLACEHOLDER', 'sha256:') + body;
-    const hash = createHash('sha256').update(hashInput, 'utf8').digest('hex');
-    const content = frontmatter.replace('sha256:PLACEHOLDER', `sha256:${hash}`) + body;
-    return { content, hash };
+    const handoffHash = sha256OfBody(body);
+    const frontmatter = {
+        requestId: rid,
+        sessionId: sid,
+        schemaVersion: '2',
+        handoffHash,
+        writtenAt: new Date().toISOString(),
+        goals: [],
+        acceptanceCriteria: [],
+        preservedBehavior: [],
+        handoffPath: handoffRelativePath(sid, rid)
+    };
+    return { content: `${serializeHandoffFrontmatter(frontmatter)}${body}`, hash: handoffHash };
 }
 /** Find the existing numbered QA request file for `rid`, else the default. */
 async function resolveQaRequestPath(qaDir, rid) {
@@ -300,6 +301,21 @@ async function resolveQaRequestPath(qaDir, rid) {
 }
 export async function generateEvidence(options) {
     const { projectRoot, rid, title, files, lineCounts, sessionId } = options;
+    // Both values become path segments below — the rid as a filename, the sid as
+    // the session directory. Guard them BEFORE the first mkdir so a rejected run
+    // leaves nothing behind. `REQUEST_ID_PATTERN` is the repo's own request-id
+    // control (`request-artifact-service.ts`, F-1 slice 025 security); the sid
+    // gets the segment check because `--session-id` has no pinned format.
+    // Measured before these lines existed: `--rid '../../../pwned'` wrote
+    // `.peaks/_runtime/pwned.md`, outside the per-session evidence dir, and a
+    // deeper rid wrote above the project root with the string echoed into the
+    // artifact body.
+    if (!REQUEST_ID_PATTERN.test(rid)) {
+        throw new Error(`Invalid request id: ${rid} (expected letters, digits, dots, underscores, or dashes)`);
+    }
+    if (isUnsafePathInput(sessionId)) {
+        throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
+    }
     const sessionRoot = getSessionDir(projectRoot, sessionId);
     const rdDir = join(sessionRoot, 'rd');
     const qaDir = join(sessionRoot, 'qa');
@@ -319,18 +335,39 @@ export async function generateEvidence(options) {
     }
     const qaRequestPath = await resolveQaRequestPath(qaDir, rid);
     const handoff = buildHandoff(rid, sessionId, title, files, lineCounts);
+    // Four of these twelve paths carry the rid because the `rd:qa-handoff` gate
+    // requires `<rid>` in them: every slice in a session shares `rd/` and
+    // `audit/`, so writing the ridless name silently destroyed the previous
+    // slice's evidence on 2026-09-13 while the gate stayed green (slice
+    // `2026-09-14-audit-artifact-rid-scoping`).
     const writes = [
-        [join(rdDir, 'code-review.md'), buildCodeReview(rid, title, files, lineCounts)],
+        [join(rdDir, `code-review-${rid}.md`), buildCodeReview(rid, title, files, lineCounts)],
+        [join(auditDir, `security-${rid}.md`), buildSecurityReview(rid)],
+        // ...but the `config` type is the one whose `rd:qa-handoff` row is
+        // `SECURITY_REVIEW` — the genuinely ridless `rd/security-review.md` — and
+        // this generator is request-type-agnostic (no `--request-type`). So it
+        // writes BOTH names: the rid-scoped one the fanout types resolve
+        // (`AUDIT_SECURITY`) and the bare one `config` resolves. Nothing is lost
+        // by having both; a `config` slice has nothing else to fall back on, and
+        // dropping this write made a `config` slice fail its own gate while the
+        // generator reported success (repair round: measured `missing:
+        // ['rd/security-review.md']` with the real generator and the real gate).
         [join(rdDir, 'security-review.md'), buildSecurityReview(rid)],
-        [join(rdDir, 'karpathy-review.md'), buildKarpathyReview(rid, lineCounts)],
+        [join(rdDir, `karpathy-review-${rid}.md`), buildKarpathyReview(rid, lineCounts)],
+        // `rd/tech-doc.md` stays ridless on purpose: the TECH_DOC prereq was
+        // removed in v2.11.0, so nothing gates it and there is no rid-scoped
+        // sibling that anything reads.
         [join(rdDir, 'tech-doc.md'), buildTechDoc(rid, title, files, lineCounts)],
-        [join(auditDir, 'perf.md'), buildPerfAudit(rid)],
+        [join(auditDir, `perf-${rid}.md`), buildPerfAudit(rid)],
         [join(qaDir, 'test-cases', `${rid}.md`), buildTestCases(rid)],
         [join(qaDir, 'test-reports', `${rid}.md`), buildTestReport(rid)],
         [join(qaDir, `security-findings-${rid}.md`), buildSecurityFindings(rid)],
         [join(qaDir, `performance-findings-${rid}.md`), buildPerformanceFindings(rid)],
         [qaRequestPath, buildQaRequest(rid, sessionId, files)],
-        [join(prdDir, 'handoff.md'), handoff.content]
+        // The handoff capsule carries the rid for the same reason as the four
+        // above (slice `2026-09-14-prd-capsule-rid-scoping`): one slot per
+        // session means the second slice's capsule overwrites the first's.
+        [join(prdDir, `handoff-${rid}.md`), handoff.content]
     ];
     const writtenFiles = [];
     for (const [path, content] of writes) {
@@ -341,7 +378,7 @@ export async function generateEvidence(options) {
         rid,
         sessionId,
         sessionRoot,
-        handoffPath: join(prdDir, 'handoff.md'),
+        handoffPath: join(prdDir, `handoff-${rid}.md`),
         handoffHash: handoff.hash,
         writtenFiles,
         createdDirectories

package/dist/services/final-review/final-review-service.d.ts

@@ -252,6 +252,15 @@ interface EvidenceSource {
     readonly label: string;
     /** Path segments under `.peaks/_runtime/<sessionId>/`. */
     readonly segments: readonly string[];
+    /**
+     * An older location of the SAME artifact, tried only when `segments` is not
+     * on disk. Slice `2026-09-14-prd-capsule-rid-scoping` moved the PRD handoff
+     * capsule to `prd/handoff-<rid>.md`; sessions written before it hold only
+     * the bare `prd/handoff.md`, and this module's delivery gate keys on that
+     * source — so a source that goes missing does not fail the gate, it stops
+     * it (`enforceScopeContractDelivery` returns early on `missing`).
+     */
+    readonly legacySegments?: readonly string[];
     /** Dimensions this source can supply evidence for. */
     readonly supports: readonly DimensionKind[];
     /** What DELIVERED means for this source. See `isDelivered()` — every source

package/dist/services/final-review/final-review-service.js

@@ -474,7 +474,10 @@ function evidenceSourcesFor(rid, prePostDiffAvailable) {
         {
             key: SCOPE_CONTRACT_SOURCE_KEY,
             label: 'PRD handoff (approved scope + non-goals)',
-            segments: ['prd', 'handoff.md'],
+            // One capsule per slice since `2026-09-14-prd-capsule-rid-scoping`; the
+            // bare name is the pre-scoping tier and still lives on 3 sessions.
+            segments: ['prd', `handoff-${rid}.md`],
+            legacySegments: ['prd', 'handoff.md'],
             supports: ['functional-completeness', 'existing-functionality-intact'],
             delivery: { kind: 'whole' }
         }
@@ -508,22 +511,43 @@ function classifyReadFailure(error) {
 function readEvidence(projectRoot, sessionId, rid, prePostDiffAvailable) {
     const runtimeRoot = join(projectRoot, '.peaks', '_runtime', sessionId);
     return evidenceSourcesFor(rid, prePostDiffAvailable).map(source => {
-        const relativePath = ['.peaks', '_runtime', sessionId, ...source.segments].join('/');
-        const absolutePath = join(runtimeRoot, ...source.segments);
+        // The canonical location first; an older one is tried only when the
+        // canonical file is genuinely ABSENT (see `legacySegments`). A file that
+        // is present but unreadable stops the walk — falling through to an older
+        // copy would silently swap the evidence this run reports.
+        const attempts = [
+            source.segments,
+            ...(source.legacySegments !== undefined ? [source.legacySegments] : [])
+        ];
+        // The path reported when nothing resolved stays the CANONICAL one, so the
+        // operator is sent to where the artifact belongs, not to its old home.
+        let resolved = source.segments;
         let raw = null;
         let error = '';
-        let read = 'ok';
-        try {
-            raw = readFileSync(absolutePath);
-        }
-        catch (err) {
-            read = classifyReadFailure(err);
-            error = err instanceof Error ? err.message : String(err);
+        let read = 'missing';
+        for (const segments of attempts) {
+            try {
+                raw = readFileSync(join(runtimeRoot, ...segments));
+                read = 'ok';
+                resolved = segments;
+                break;
+            }
+            catch (err) {
+                read = classifyReadFailure(err);
+                error = err instanceof Error ? err.message : String(err);
+                // A file that exists but cannot be read IS this source's file, so it
+                // is also the path the report must name — walking on to an older copy
+                // would silently swap the evidence this run reports.
+                if (read === 'unreadable') {
+                    resolved = segments;
+                    break;
+                }
+            }
         }
         return {
             source,
-            relativePath,
-            absolutePath,
+            relativePath: ['.peaks', '_runtime', sessionId, ...resolved].join('/'),
+            absolutePath: join(runtimeRoot, ...resolved),
             raw,
             read,
             error,

package/dist/services/fuzzy-matching/fzf-pick-service.js

@@ -69,6 +69,7 @@ export async function pickFromList(options) {
                 input: fzfInput,
                 cwd: options.projectRoot,
                 stdio: ['pipe', 'pipe', 'pipe'],
+                windowsHide: true,
                 shell: false,
                 timeout: SPAWN_TIMEOUT_MS,
                 maxBuffer: MAX_BUFFER_BYTES
@@ -108,6 +109,7 @@ function checkFzfVersion(fzfBin) {
         stdout = execFileSync(fzfBin, ['--version'], {
             stdio: ['ignore', 'pipe', 'pipe'],
             shell: false,
+            windowsHide: true,
             timeout: 5_000
         }).toString('utf8');
     }

package/dist/services/hooks/auto-compact-hook-install.d.ts

@@ -67,6 +67,14 @@ export declare const AUTO_COMPACT_HOOK_MARKER = "peaks:auto-compact-hook-do-not-
  * Default on-disk location — kept here (not in claude-settings-template)
  * because the auto-compact hook is a separate install surface from
  * the fact-forcing gate bypass template.
+ *
+ * This is Claude Code's path, and it is a DEFAULT only. A caller that
+ * resolved an IDE adapter MUST pass the adapter-declared location as
+ * `settingsPath`:
+ * `join(projectRoot, adapter.settings.dirName, adapter.settings.localSettingsFileName)`.
+ * The default remains for callers with no adapter in hand (and keeps the
+ * claude-code byte-stability contract); it is not a claim that every IDE
+ * stores local settings at `.claude/settings.local.json`.
  */
 export declare const AUTO_COMPACT_HOOK_SETTINGS_PATH = ".claude/settings.local.json";
 /**
@@ -100,7 +108,7 @@ export type AutoCompactHookRemoveResult = {
  */
 export declare function installAutoCompactHook(input: {
     readonly projectRoot: string;
-    readonly settingsPath?: string;
+    readonly settingsPath?: string | undefined;
 }): AutoCompactHookInstallResult;
 /**
  * Remove the auto-compact PreToolUse hook. Idempotent: missing hook
@@ -112,5 +120,5 @@ export declare function installAutoCompactHook(input: {
  */
 export declare function removeAutoCompactHook(input: {
     readonly projectRoot: string;
-    readonly settingsPath?: string;
+    readonly settingsPath?: string | undefined;
 }): AutoCompactHookRemoveResult;

package/dist/services/hooks/auto-compact-hook-install.js

@@ -70,6 +70,14 @@ export const AUTO_COMPACT_HOOK_MARKER = 'peaks:auto-compact-hook-do-not-edit';
  * Default on-disk location — kept here (not in claude-settings-template)
  * because the auto-compact hook is a separate install surface from
  * the fact-forcing gate bypass template.
+ *
+ * This is Claude Code's path, and it is a DEFAULT only. A caller that
+ * resolved an IDE adapter MUST pass the adapter-declared location as
+ * `settingsPath`:
+ * `join(projectRoot, adapter.settings.dirName, adapter.settings.localSettingsFileName)`.
+ * The default remains for callers with no adapter in hand (and keeps the
+ * claude-code byte-stability contract); it is not a claim that every IDE
+ * stores local settings at `.claude/settings.local.json`.
  */
 export const AUTO_COMPACT_HOOK_SETTINGS_PATH = '.claude/settings.local.json';
 function isObject(value) {

package/dist/services/ide/adapters/claude-code-adapter.d.ts

@@ -47,11 +47,16 @@ export declare const CONTEXT_WINDOW_TOKENS_ENV_VAR = "PEAKS_CONTEXT_WINDOW_TOKEN
 /**
  * Which layer produced a resolved context window:
  *   - `env-override`     — `PEAKS_CONTEXT_WINDOW_TOKENS`
+ *   - `harness-env`      — the window peaks-loop itself wrote into the
+ *                          harness's machine-local settings
+ *                          (`CLAUDE_CODE_AUTO_COMPACT_WINDOW`, declared by
+ *                          the adapter as `autoCompactWindowEnvVar`); see
+ *                          `harness-window-config.ts`
  *   - `config`           — `context.windowTokens` (`peaks config set`)
  *   - `model-heuristic`  — `[1M]` suffix / `ONE_MILLION_CONTEXT_MODELS`
  *   - `default`          — 200K safe default
  */
-export type ContextWindowSource = 'env-override' | 'config' | 'model-heuristic' | 'default';
+export type ContextWindowSource = 'env-override' | 'harness-env' | 'config' | 'model-heuristic' | 'default';
 export interface ContextWindowResolution {
     readonly tokens: number;
     readonly source: ContextWindowSource;
@@ -61,9 +66,78 @@ export interface ContextWindowOverrides {
     readonly env?: NodeJS.ProcessEnv | undefined;
     /** Raw `context.windowTokens` value (unvalidated — validated here). */
     readonly configWindowTokens?: unknown;
+    /**
+     * The window peaks-loop itself configured for the harness — raw value read
+     * from the harness's machine-local settings `env` block (or the process env
+     * the harness populated from it). Resolved by the caller
+     * (`auto-compact-reader.ts` via `harness-window-config.ts`), NOT here: the
+     * settings path and the key name are per-IDE declarations.
+     *
+     * Slice 2026-09-13-auto-compact-trigger-ownership: this layer is what makes
+     * the ratio peaks-loop computes and the window the harness compacts against
+     * THE SAME NUMBER. Without it they are two independent resolutions that can
+     * drift 5× apart on a 1M-window model the model-name heuristic misses.
+     */
+    readonly harnessWindowTokens?: unknown;
+    /**
+     * Provenance of `harnessWindowTokens`: true when peaks-loop wrote that value
+     * itself, false/omitted when a human set it. Only a peaks-written value may
+     * be overruled by the late 1M rescue — see `resolveContextWindowTokens`.
+     */
+    readonly harnessWindowPeakWritten?: boolean;
     /** Warning sink for an invalid override (defaults to `console.warn`). */
     readonly onInvalidOverride?: ((message: string) => void) | undefined;
+    /**
+     * Warning sink for the E2 notice: a HUMAN pin (`env-override` / `config`)
+     * larger than peaks-loop's own model-window estimate. Deliberately separate
+     * from `onInvalidOverride` — that sink means "your value could not be read",
+     * this one means "your value was read, and peaks-loop cannot promise the
+     * harness will use it". Two meanings, two sinks. Defaults to `console.warn`.
+     *
+     * See `describeWindowAboveModelEstimate` for what the notice does and does
+     * not claim, and why it is a notice rather than a refusal.
+     */
+    readonly onAboveModelEstimate?: ((message: string) => void) | undefined;
 }
+/**
+ * E2 (rid 2026-09-13-defects-e) — the notice for a pin larger than
+ * peaks-loop's model-window estimate. `null` when there is nothing to say.
+ *
+ * WHY THIS EXISTS. The harness does not take its auto-compact window on faith:
+ * it reduces the configured value with `Math.min(native, override)`, where
+ * `native` is the model's own context size. A pin ABOVE `native` is therefore
+ * accepted by peaks-loop, written to the harness's settings, and silently
+ * reduced by the harness — so peaks-loop's ratio divides by a window the
+ * harness is not compacting on. That is the A1 drift (two independent
+ * resolutions, one number meaning two things), arriving from the other side
+ * from E1: E1 is a value the harness refuses, E2 a value it quietly lowers.
+ *
+ * CAN WE READ THE NATIVE WINDOW? No, and the notice does not pretend otherwise.
+ * There is no API for it and no environment variable that carries it; the only
+ * local knowledge is `modelContextWindowTokens`'s NAME HEURISTIC (200_000, or
+ * 1_000_000 when the id says `1m` or matches the allowlist) — the very layer
+ * this slice demoted, because it is wrong for precisely the proxied /
+ * third-party models the pin exists for. It is used here ONLY as a disagreement
+ * DETECTOR, never as an authority, and the uncertainty that buys is one-sided:
+ * this notice means "peaks-loop's best guess of your model is smaller than the
+ * window you pinned", which a genuinely larger model ALSO produces. It cannot
+ * mean "the harness will definitely cap you" — only the harness knows that.
+ *
+ * WHY A NOTICE AND NOT A REFUSAL. The pin is the documented escape hatch for a
+ * model id the heuristic cannot see, so refusing would delete the feature. The
+ * notice keeps it and states the risk.
+ *
+ * WHY ONLY THE HUMAN PINS. The `harness-env` layer is a value peaks-loop FOUND
+ * in the harness's own file, not one this call is setting; its disagreements are
+ * already reported by the writer (`harnessWindowSyncWarning`), and warning here
+ * would fire on every probe of a project whose file legitimately says 1000000.
+ */
+export declare function describeWindowAboveModelEstimate(input: {
+    readonly model: string;
+    readonly tokens: number;
+    /** Human-readable name of the pin, e.g. `PEAKS_CONTEXT_WINDOW_TOKENS="500000"`. */
+    readonly pin: string;
+}): string | null;
 /**
  * Parse an explicit context-window override. Accepts a positive finite
  * integer only (number, or a numeric string so an env var works); anything
@@ -76,11 +150,41 @@ export declare function parseContextWindowOverride(raw: unknown): number | null;
  * (first hit wins):
  *   1. env `PEAKS_CONTEXT_WINDOW_TOKENS`
  *   2. config `context.windowTokens`
- *   3. model-name heuristic (`modelContextWindowTokens`)
- *   4. `DEFAULT_CONTEXT_WINDOW_TOKENS` (200_000)
+ *   3. `harnessWindowTokens` — the window peaks-loop configured for the
+ *      harness (`autoCompactWindowEnvVar`)
+ *   4. model-name heuristic (`modelContextWindowTokens`)
+ *   5. `DEFAULT_CONTEXT_WINDOW_TOKENS` (200_000)
  *
  * An invalid explicit override is ignored with a warning and falls through
  * to the next layer — a typo must never crash or silently win the probe.
+ *
+ * Slice 2026-09-13-auto-compact-trigger-ownership — why layer 3 exists:
+ *   The hard constraint is that the window peaks-loop divides by must BE the
+ *   window it configured for the harness. Layer 3 is peaks-loop's own output
+ *   read back from the harness's settings file, so the two sides reference one
+ *   artifact rather than two independent resolutions. It sits ABOVE the model
+ *   heuristic because a heuristic contradicting the number both sides already
+ *   use is precisely how the 5× drift arose (a 1M-window model measured
+ *   against a 200K guess).
+ *
+ *   Why it sits BELOW the two explicit pins. Both are human declarations of
+ *   intent, and a pin that loses to a value peaks-loop wrote earlier is a
+ *   silently ignored setting: the user changes `context.windowTokens`, the
+ *   stale harness key shadows it, and nothing appears to happen. Conflict is
+ *   instead resolved by PROPAGATION — the probe that resolves the pin also
+ *   syncs it into the harness (`syncHarnessWindowForProject`), so peaks-loop's
+ *   ratio and the harness's window are back on one number before that command
+ *   returns. The conflict is therefore transient and self-healing rather than
+ *   either silent shadowing or permanent drift.
+ *
+ *   Why layer 3 is not simply authoritative (the ratchet). Reading back a value
+ *   peaks-loop wrote makes peaks-loop trust its own earlier resolution, so a
+ *   first-time mis-resolution (an unrecognised model defaulting to 200_000)
+ *   would be written to disk and then believed forever: the ratio stays
+ *   saturated at 1.0 while the session grows past the pin, and the correction
+ *   that exists for exactly that case — the late 1M rescue — was disabled for
+ *   this layer. Self-locking. See `resolveContextWindowTokens` for how the
+ *   rescue is let back in without letting it overwrite a human's own setting.
  */
 export declare function resolveContextWindow(model: string, overrides?: ContextWindowOverrides): ContextWindowResolution;
 export declare const CLAUDE_CODE_ADAPTER: IdeAdapter;