peaks-loop 4.0.53 → 4.1.0

package/dist/services/context/context-audit.js

@@ -25,234 +25,47 @@
  * summary* of the tool input — the Bash command line, the file path tail, the
  * grep pattern — so "4 × the same 40KB reindex dump" collapses into ONE row
  * with `count: 4` instead of four anonymous entries.
+ *
+ * Split note (wave 3, eslint-family sweep): the public envelope types live
+ * in `./context-audit-types.ts`, the limits constants and `--top` clamp in
+ * `./context-audit-limits.ts`, the group-key builders in
+ * `./context-audit-keys.ts`, and the streaming scan / fold / ranking /
+ * fail-soft assembly in `./context-audit-scan.ts`. Those bodies were moved
+ * VERBATIM — control flow copied, nothing improved — so this module keeps
+ * its whole public surface (every name re-exported below) and stays under
+ * the 300 raw-line cap.
  */
-import { closeSync, openSync, readSync, statSync } from 'node:fs';
 import { getAdapter } from '../ide/ide-registry.js';
 import { detectIdeFromEnv } from './ide-detect.js';
-/** Default number of top entries emitted. */
-export const CONTEXT_AUDIT_DEFAULT_TOP = 15;
-/** Hard ceiling for `--top` — the envelope must stay small by construction. */
-export const CONTEXT_AUDIT_MAX_TOP = 100;
-/** Transcripts larger than this are reported `available:false` (fail-soft). */
-export const CONTEXT_AUDIT_MAX_TRANSCRIPT_BYTES = 256 * 1024 * 1024;
-/** Streaming chunk size (bounded memory on multi-MB transcripts). */
-const SCAN_CHUNK_BYTES = 1024 * 1024;
-/** Max characters kept in a group key — keys are labels, not payloads. */
-const KEY_MAX_CHARS = 100;
-/** Clamp a caller-supplied `--top` into the documented range. */
-export function normalizeTopN(value) {
-    const n = typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : CONTEXT_AUDIT_DEFAULT_TOP;
-    if (n < 1)
-        return CONTEXT_AUDIT_DEFAULT_TOP;
-    return Math.min(n, CONTEXT_AUDIT_MAX_TOP);
-}
-function clip(text, max) {
-    const collapsed = text.replace(/\s+/g, ' ').trim();
-    return collapsed.length <= max ? collapsed : `${collapsed.slice(0, max - 1)}…`;
-}
-/** Last `n` path segments — keeps `Read` / `Edit` keys short but identifiable. */
-function tailPath(value, n) {
-    const parts = value.split(/[\\/]/).filter((p) => p.length > 0);
-    return parts.slice(Math.max(0, parts.length - n)).join('/');
-}
+import { CONTEXT_AUDIT_MAX_TRANSCRIPT_BYTES, normalizeTopN } from './context-audit-limits.js';
+import { auditTranscriptFile, emptyResult } from './context-audit-scan.js';
+export { CONTEXT_AUDIT_DEFAULT_TOP, CONTEXT_AUDIT_MAX_TOP, CONTEXT_AUDIT_MAX_TRANSCRIPT_BYTES, normalizeTopN } from './context-audit-limits.js';
+export { contextAuditKey } from './context-audit-keys.js';
 /**
- * Build the stable group key for one tool call. Unknown tools fall back to a
- * clipped JSON rendering of their input so the group is still recognizable.
+ * Vendor-neutral: the adapter owns the on-disk layout. Mirrors
+ * `readContextPercent`'s narrowing of the detected kind to a
+ * registered adapter id ('unknown' → claude-code default). Both the
+ * registry lookup and the locator call are guarded — an unregistered
+ * detected id (e.g. an IDE without a peaks adapter yet) or an adapter
+ * bug must degrade, never throw.
  */
-export function contextAuditKey(tool, input) {
-    const read = (v) => (typeof v === 'string' ? v : '');
-    if (typeof input !== 'object' || input === null)
-        return '';
-    const i = input;
-    switch (tool) {
-        case 'Bash':
-            return clip(read(i.command), KEY_MAX_CHARS);
-        case 'Read':
-        case 'Write':
-        case 'Edit':
-        case 'NotebookEdit':
-            return clip(tailPath(read(i.file_path), 2), KEY_MAX_CHARS);
-        case 'Grep':
-        case 'Glob':
-            return clip(`${read(i.pattern)} @ ${read(i.path) || '.'}`, KEY_MAX_CHARS);
-        case 'Task':
-        case 'Agent':
-            return clip(read(i.description) || read(i.subagent_type), 60);
-        default: {
-            let json;
-            try {
-                json = JSON.stringify(input) ?? '';
-            }
-            catch {
-                json = '';
-            }
-            return clip(json, 80);
-        }
-    }
-}
-/** UTF-8 size of a `tool_result.content` payload (string | array | object). */
-function toolResultBytes(content) {
-    if (typeof content === 'string')
-        return Buffer.byteLength(content, 'utf8');
-    if (Array.isArray(content)) {
-        let total = 0;
-        for (const part of content) {
-            if (typeof part === 'string') {
-                total += Buffer.byteLength(part, 'utf8');
-            }
-            else if (typeof part === 'object' && part !== null) {
-                const text = part.text;
-                total += typeof text === 'string'
-                    ? Buffer.byteLength(text, 'utf8')
-                    : Buffer.byteLength(JSON.stringify(part) ?? '', 'utf8');
-            }
-        }
-        return total;
-    }
-    if (content === undefined || content === null)
-        return 0;
+function resolveTranscriptViaAdapter(outerSessionId, env) {
     try {
-        return Buffer.byteLength(JSON.stringify(content) ?? '', 'utf8');
-    }
-    catch {
-        return 0;
-    }
-}
-function emptyResult(partial) {
-    return {
-        available: false,
-        reason: null,
-        transcriptPath: null,
-        totalBytes: 0,
-        entryCount: 0,
-        groupCount: 0,
-        topN: CONTEXT_AUDIT_DEFAULT_TOP,
-        entries: [],
-        ...partial,
-    };
-}
-/**
- * Stream the transcript once, folding every tool result into its
- * `(tool, key)` group. Pure bookkeeping — no content is retained.
- */
-function scanTranscript(filePath, topN) {
-    const toolUses = new Map();
-    const groups = new Map();
-    let totalBytes = 0;
-    let entryCount = 0;
-    const fd = openSync(filePath, 'r');
-    try {
-        const size = statSync(filePath).size;
-        let position = 0;
-        let carry = '';
-        while (position < size) {
-            const readLen = Math.min(SCAN_CHUNK_BYTES, size - position);
-            const buf = Buffer.alloc(readLen);
-            const bytesRead = readSync(fd, buf, 0, readLen, position);
-            if (bytesRead <= 0)
-                break;
-            position += bytesRead;
-            const lines = (carry + buf.toString('utf8', 0, bytesRead)).split('\n');
-            // The last element is a partial line (or the trailing empty string).
-            carry = lines.pop() ?? '';
-            for (const line of lines) {
-                if (line.length === 0)
-                    continue;
-                const folded = foldLine(line, toolUses, groups);
-                totalBytes += folded.bytes;
-                entryCount += folded.count;
-            }
+        const detected = detectIdeFromEnv(env ?? process.env);
+        const ideId = (detected === 'unknown' ? 'claude-code' : detected);
+        const locate = getAdapter(ideId).compact?.resolveTranscriptPath;
+        if (locate === undefined) {
+            return { reason: 'transcript-locator-unavailable' };
         }
-        if (carry.length > 0) {
-            const folded = foldLine(carry, toolUses, groups);
-            totalBytes += folded.bytes;
-            entryCount += folded.count;
-        }
-    }
-    finally {
-        try {
-            closeSync(fd);
-        }
-        catch {
-            /* best-effort close */
+        const transcriptPathOrNull = locate(outerSessionId);
+        if (transcriptPathOrNull === null) {
+            return { reason: 'transcript-not-found' };
         }
-    }
-    const entries = [...groups.values()]
-        .map((g) => ({
-        tool: g.tool,
-        key: g.key,
-        bytes: g.bytes,
-        // Percentage in [0, 100], one decimal — see ContextAuditEntry.pctOfTotal.
-        pctOfTotal: totalBytes > 0 ? Math.round((g.bytes / totalBytes) * 1000) / 10 : 0,
-        count: g.count,
-    }))
-        .sort((a, b) => b.bytes - a.bytes || a.tool.localeCompare(b.tool) || a.key.localeCompare(b.key));
-    return {
-        available: true,
-        reason: null,
-        transcriptPath: filePath,
-        totalBytes,
-        entryCount,
-        groupCount: entries.length,
-        topN,
-        entries: entries.slice(0, topN),
-    };
-}
-/**
- * Fold ONE jsonl line into the running state. Returns the byte/count delta
- * contributed by this line. Corrupt / non-JSON lines are skipped silently —
- * a truncated tail must not fail the audit.
- */
-function foldLine(line, toolUses, groups) {
-    let parsed;
-    try {
-        parsed = JSON.parse(line);
+        return { transcriptPath: transcriptPathOrNull };
     }
     catch {
-        return { bytes: 0, count: 0 };
-    }
-    if (typeof parsed !== 'object' || parsed === null)
-        return { bytes: 0, count: 0 };
-    const record = parsed;
-    const message = record.message;
-    if (typeof message !== 'object' || message === null)
-        return { bytes: 0, count: 0 };
-    const content = message.content;
-    if (!Array.isArray(content))
-        return { bytes: 0, count: 0 };
-    let bytes = 0;
-    let count = 0;
-    for (const part of content) {
-        if (typeof part !== 'object' || part === null)
-            continue;
-        const item = part;
-        if (item.type === 'tool_use') {
-            const id = item.id;
-            const name = item.name;
-            if (typeof id === 'string' && typeof name === 'string') {
-                toolUses.set(id, { name, input: item.input });
-            }
-            continue;
-        }
-        if (item.type !== 'tool_result')
-            continue;
-        const ref = typeof item.tool_use_id === 'string' ? toolUses.get(item.tool_use_id) : undefined;
-        const tool = ref?.name ?? 'unknown';
-        const key = ref === undefined ? '' : contextAuditKey(tool, ref.input);
-        const size = toolResultBytes(item.content);
-        const groupKey = `${tool}${key}`;
-        const group = groups.get(groupKey);
-        if (group === undefined) {
-            groups.set(groupKey, { tool, key, bytes: size, count: 1 });
-        }
-        else {
-            group.bytes += size;
-            group.count += 1;
-        }
-        bytes += size;
-        count += 1;
+        return { reason: 'transcript-locator-unavailable' };
     }
-    return { bytes, count };
 }
 /**
  * Audit the CURRENT session's transcript. Never throws.
@@ -278,45 +91,16 @@ export function auditContext(input = {}) {
         if (typeof outerSessionId !== 'string' || outerSessionId.length === 0) {
             return emptyResult({ reason: 'no-outer-session-id', topN });
         }
-        // Vendor-neutral: the adapter owns the on-disk layout. Mirrors
-        // `readContextPercent`'s narrowing of the detected kind to a
-        // registered adapter id ('unknown' → claude-code default). Both the
-        // registry lookup and the locator call are guarded — an unregistered
-        // detected id (e.g. an IDE without a peaks adapter yet) or an adapter
-        // bug must degrade, never throw.
-        let transcriptPathOrNull;
-        try {
-            const detected = detectIdeFromEnv(input.env ?? process.env);
-            const ideId = (detected === 'unknown' ? 'claude-code' : detected);
-            const locate = getAdapter(ideId).compact?.resolveTranscriptPath;
-            if (locate === undefined) {
-                return emptyResult({ reason: 'transcript-locator-unavailable', topN });
-            }
-            transcriptPathOrNull = locate(outerSessionId);
-        }
-        catch {
-            return emptyResult({ reason: 'transcript-locator-unavailable', topN });
-        }
-        if (transcriptPathOrNull === null) {
-            return emptyResult({ reason: 'transcript-not-found', topN });
+        const resolved = resolveTranscriptViaAdapter(outerSessionId, input.env);
+        if ('reason' in resolved) {
+            return emptyResult({ reason: resolved.reason, topN });
         }
-        transcriptPath = transcriptPathOrNull;
+        transcriptPath = resolved.transcriptPath;
     }
-    const maxBytes = typeof input.maxTranscriptBytes === 'number' && Number.isFinite(input.maxTranscriptBytes) && input.maxTranscriptBytes >= 0
+    const maxBytes = typeof input.maxTranscriptBytes === 'number' &&
+        Number.isFinite(input.maxTranscriptBytes) &&
+        input.maxTranscriptBytes >= 0
         ? input.maxTranscriptBytes
         : CONTEXT_AUDIT_MAX_TRANSCRIPT_BYTES;
-    try {
-        const size = statSync(transcriptPath).size;
-        if (size > maxBytes) {
-            return emptyResult({ reason: 'transcript-too-large', transcriptPath, topN });
-        }
-        return scanTranscript(transcriptPath, topN);
-    }
-    catch (err) {
-        const code = err.code;
-        const reason = code === 'ENOENT' ? 'transcript-not-found'
-            : code === 'EACCES' || code === 'EPERM' ? 'transcript-unreadable'
-                : 'audit-failed';
-        return emptyResult({ reason, transcriptPath, topN });
-    }
+    return auditTranscriptFile(transcriptPath, maxBytes, topN);
 }

package/dist/services/context/context-builder.js

@@ -21,7 +21,7 @@ const BuildInputSchema = z.object({
     depsMode: z.enum(['locked', 'latest']),
     docBudgetTokens: z.number().int().gt(0).default(8000),
     out: z.string().min(1),
-    fetcher: z.function(),
+    fetcher: z.function()
 });
 function sha256OfContent(content) {
     // Exclude `sha256` field from the hash (else chicken-and-egg).
@@ -36,7 +36,7 @@ export async function buildContext(rawInput) {
         goal: input.goal,
         project: input.project,
         depsMode: input.depsMode,
-        out: input.out,
+        out: input.out
     });
     const docs = await retrieveDocs(collected.collector.deps, { fetcher: input.fetcher });
     const tok = tokenize(collected.collector, docs);
@@ -46,7 +46,7 @@ export async function buildContext(rawInput) {
         docBudgetTokens: input.docBudgetTokens,
         collector: collected.collector,
         docRetriever: docs,
-        tokenizer: tok,
+        tokenizer: tok
     };
     const renderer = render(renderInput);
     // First pass: placeholder sha256 so we can hash the rest.
@@ -58,7 +58,7 @@ export async function buildContext(rawInput) {
         collector: collected.collector,
         docRetriever: docs,
         tokenizer: tok,
-        renderer,
+        renderer
     };
     const sha256 = sha256OfContent(partial);
     const finalCtx = { ...partial, sha256 };

package/dist/services/context/context-schema.d.ts

@@ -72,8 +72,8 @@ export declare const ContextJsonSchema: z.ZodObject<{
         metadata: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodEnum<{
-                git: "git";
                 code: "code";
+                git: "git";
                 doc: "doc";
                 memory: "memory";
             }>;

package/dist/services/context/context-schema.js

@@ -13,24 +13,24 @@ export const ContextJsonSchema = z.object({
             path: z.string(),
             kind: z.enum(['source', 'test', 'config', 'doc']),
             lines: z.number().int().gte(0),
-            hash: z.string(),
+            hash: z.string()
         })),
         gitStatus: z.object({
             branch: z.string(),
             lastCommit: z.string(),
-            dirty: z.boolean(),
+            dirty: z.boolean()
         }),
         memoryEntries: z.array(z.object({
             path: z.string(),
             title: z.string(),
             relevanceScore: z.number().min(0).max(1),
-            excerptHash: z.string(),
+            excerptHash: z.string()
         })),
         deps: z.record(z.string(), z.object({
             version: z.string(),
             source: z.enum(['package.json', 'pnpm-lock.yaml', 'yarn.lock']),
-            resolved: z.string(),
-        })),
+            resolved: z.string()
+        }))
     }),
     docRetriever: z.object({
         fetchedDocs: z.array(z.object({
@@ -43,14 +43,14 @@ export const ContextJsonSchema = z.object({
             sections: z.array(z.object({
                 title: z.string(),
                 tokenEstimate: z.number().int().gte(0),
-                excerpt: z.string(),
+                excerpt: z.string()
             })),
-            stale: z.boolean(),
+            stale: z.boolean()
         })),
         skipped: z.array(z.object({
             dep: z.string(),
-            reason: z.enum(['unconfigured', 'network_error', 'version_unknown']),
-        })),
+            reason: z.enum(['unconfigured', 'network_error', 'version_unknown'])
+        }))
     }),
     tokenizer: z.object({
         metadata: z.array(z.object({
@@ -60,14 +60,14 @@ export const ContextJsonSchema = z.object({
             blastRadius: z.array(z.string()),
             conflictScore: z.number().min(0).max(1),
             timeDecayScore: z.number().min(0).max(1),
-            tags: z.array(z.string()),
-        })),
+            tags: z.array(z.string())
+        }))
     }),
     renderer: z.object({
         audience: z.enum(['peaks-rd', 'peaks-qa', 'peaks-mut', 'all']),
         renderedAt: z.string().datetime(),
         sizeBytes: z.number().int().gte(0),
         truncated: z.boolean(),
-        truncatedReason: z.enum(['doc_budget_exceeded', 'section_count_exceeded']).optional(),
-    }),
+        truncatedReason: z.enum(['doc_budget_exceeded', 'section_count_exceeded']).optional()
+    })
 });

package/dist/services/context/doc-retriever.js

@@ -4,7 +4,7 @@ function makeSection(excerpt) {
     return {
         title: 'API Summary',
         tokenEstimate: Math.ceil(excerpt.length / 4),
-        excerpt,
+        excerpt
     };
 }
 function hashContent(content) {
@@ -40,7 +40,7 @@ export async function retrieveDocs(deps, options) {
                 fetchedAt: now().toISOString(),
                 contentHash: hashContent(payload.excerpt),
                 sections: [makeSection(payload.excerpt)],
-                stale: false,
+                stale: false
             });
         }
         catch {

package/dist/services/context/harness-context-witness.js

@@ -107,7 +107,11 @@ const FRACTION_MAX = 1;
 /** Upper bound of a sane percentage scale; above this the payload is not a percent. */
 const PERCENT_SCALE_MAX = 100;
 /** The three prompt-side components peaks-loop's own `rawTokens` sums. */
-const USAGE_TOKEN_KEYS = ['input_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens'];
+const USAGE_TOKEN_KEYS = [
+    'input_tokens',
+    'cache_read_input_tokens',
+    'cache_creation_input_tokens'
+];
 function finiteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }
@@ -284,7 +288,10 @@ export function writeHarnessWitness(input) {
     if (!existsSync(dirname(path)))
         return false;
     if (witness.usedPercentage === null) {
-        const existing = readHarnessWitness({ projectRoot: input.projectRoot, sessionId: input.sessionId });
+        const existing = readHarnessWitness({
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId
+        });
         if (existing.kind === 'valid' && existing.witness.usedPercentage !== null)
             return false;
     }
@@ -356,8 +363,8 @@ export function readHarnessWitness(input) {
  * ratio difference are the same number — see `compareHarnessWitness`.
  */
 export function witnessToleranceTokens(input) {
-    return WITNESS_PERCENT_ROUNDING_FRACTION * input.windowTokens
-        + WITNESS_NUMERATOR_FRACTION * input.usedTokens;
+    return (WITNESS_PERCENT_ROUNDING_FRACTION * input.windowTokens +
+        WITNESS_NUMERATOR_FRACTION * input.usedTokens);
 }
 /**
  * Whether this sample can support an `agree`.
@@ -382,7 +389,8 @@ export function witnessToleranceTokens(input) {
  * the one answer that was honest there could not be produced there.
  */
 function sampleSupportsAgreement(harnessPct, tolerance) {
-    const smallestGapSignal = (MIN_DETECTABLE_WINDOW_DIFFERENCE * Math.abs(harnessPct)) / (1 + MIN_DETECTABLE_WINDOW_DIFFERENCE);
+    const smallestGapSignal = (MIN_DETECTABLE_WINDOW_DIFFERENCE * Math.abs(harnessPct)) /
+        (1 + MIN_DETECTABLE_WINDOW_DIFFERENCE);
     return smallestGapSignal > 2 * tolerance;
 }
 /** Which of the three `absent` states applies, in the reader's own words. */
@@ -391,8 +399,8 @@ function absentReason(cause) {
         return 'this session has no runtime directory yet, so nothing has been captured for it';
     }
     if (cause === 'unreadable') {
-        return 'a witness file exists for this session but could not be read as a record — the statusline DID '
-            + 'render here, and its record is unreadable, malformed, or not the shape this reader expects';
+        return ('a witness file exists for this session but could not be read as a record — the statusline DID ' +
+            'render here, and its record is unreadable, malformed, or not the shape this reader expects');
     }
     return 'no render has been recorded for this session — the statusline has not rendered through peaks-loop here';
 }
@@ -402,12 +410,12 @@ function unusableReason(witness) {
         return 'the payload carried no `used_percentage`, so this render recorded nothing to compare';
     }
     if (witness.usedPercentageUnit === 'unestablished') {
-        return `the payload reported used_percentage ${witness.usedPercentageRaw} and carried no token snapshot `
-            + 'to settle whether that is a fraction or a percent; the raw value is recorded, and no comparison is '
-            + 'made from it';
+        return (`the payload reported used_percentage ${witness.usedPercentageRaw} and carried no token snapshot ` +
+            'to settle whether that is a fraction or a percent; the raw value is recorded, and no comparison is ' +
+            'made from it');
     }
-    return `the payload reported used_percentage ${witness.usedPercentageRaw}, which is on neither scale `
-        + '(a 0..1 fraction or a 0..100 percent); the raw value is recorded, and no comparison is made from it';
+    return (`the payload reported used_percentage ${witness.usedPercentageRaw}, which is on neither scale ` +
+        '(a 0..1 fraction or a 0..100 percent); the raw value is recorded, and no comparison is made from it');
 }
 /**
  * Compare peaks-loop's ratio with the harness's own percentage.
@@ -480,9 +488,9 @@ export function compareHarnessWitness(input) {
         return {
             ...base,
             verdict: 'unverifiable',
-            reason: `this witness was recorded under schema v${witness.schemaVersion} and this revision reads `
-                + `v${WITNESS_SCHEMA_VERSION}, which do not agree on what the recorded percentage means; it is not `
-                + 'compared, and the next render replaces it',
+            reason: `this witness was recorded under schema v${witness.schemaVersion} and this revision reads ` +
+                `v${WITNESS_SCHEMA_VERSION}, which do not agree on what the recorded percentage means; it is not ` +
+                'compared, and the next render replaces it',
             harnessPct: null,
             deviation: null,
             residual: null,
@@ -517,7 +525,10 @@ export function compareHarnessWitness(input) {
             tolerance: null
         };
     }
-    if (windowTokens === null || windowTokens <= 0 || peaksTokens === null || witnessTokens === null) {
+    if (windowTokens === null ||
+        windowTokens <= 0 ||
+        peaksTokens === null ||
+        witnessTokens === null) {
         return {
             ...base,
             verdict: 'unverifiable',
@@ -539,7 +550,15 @@ export function compareHarnessWitness(input) {
     // `disagree` only claims that SOME difference exists, and a residual past the
     // budget is exactly that claim — sound at any ratio, any witness age.
     if (Math.abs(residual) > tolerance) {
-        return { ...base, verdict: 'disagree', reason: null, harnessPct, deviation, residual, tolerance };
+        return {
+            ...base,
+            verdict: 'disagree',
+            reason: null,
+            harnessPct,
+            deviation,
+            residual,
+            tolerance
+        };
     }
     // `agree` claims there is no difference, which needs the sample to be sharp
     // enough to support it — see `sampleSupportsAgreement`.
@@ -576,13 +595,13 @@ export function describeHarnessWitness(comparison) {
     const readAs = comparison.witnessPercentageUnit === null
         ? ''
         : ` (raw ${comparison.witnessRawPercentage}, read as a ${comparison.witnessPercentageUnit})`;
-    return `Harness context witness disagrees: the harness reports ${pct(comparison.harnessPct ?? 0)} used${readAs}, `
-        + `peaks-loop computes ${pct(comparison.peaksRatio)} (deviation ${pct(Math.abs(comparison.deviation ?? 0))}`
-        + `${skew === null ? '' : `, of which the measured sampling skew explains ${pct(Math.abs(skew))}`}, `
-        + `leaving ${pct(Math.abs(comparison.residual ?? 0))} against a budget of ${pct(comparison.tolerance ?? 0)}). `
-        + 'The two ratios do not share a denominator: '
-        + 'peaks-loop\'s configured auto-compact window and the harness\'s effective auto-compact window are '
-        + 'different numbers. Nothing is blocked.';
+    return (`Harness context witness disagrees: the harness reports ${pct(comparison.harnessPct ?? 0)} used${readAs}, ` +
+        `peaks-loop computes ${pct(comparison.peaksRatio)} (deviation ${pct(Math.abs(comparison.deviation ?? 0))}` +
+        `${skew === null ? '' : `, of which the measured sampling skew explains ${pct(Math.abs(skew))}`}, ` +
+        `leaving ${pct(Math.abs(comparison.residual ?? 0))} against a budget of ${pct(comparison.tolerance ?? 0)}). ` +
+        'The two ratios do not share a denominator: ' +
+        "peaks-loop's configured auto-compact window and the harness's effective auto-compact window are " +
+        'different numbers. Nothing is blocked.');
 }
 /** Convenience for the CLI: read + compare in one call. */
 export function readAndCompareHarnessWitness(input) {

package/dist/services/context/harness-window-config.js

@@ -99,7 +99,7 @@ export const HARNESS_WINDOW_MAX_TOKENS = 1_000_000;
  * `null` (absent / unparseable) is NOT in band — there is no window at all.
  */
 export function isHarnessWindowInRange(tokens) {
-    return tokens !== null && tokens >= HARNESS_WINDOW_MIN_TOKENS && tokens <= HARNESS_WINDOW_MAX_TOKENS;
+    return (tokens !== null && tokens >= HARNESS_WINDOW_MIN_TOKENS && tokens <= HARNESS_WINDOW_MAX_TOKENS);
 }
 /**
  * The BAND SENTENCE, in one place: both the write refusal and the read
@@ -248,7 +248,9 @@ function harnessWindowConflictClause(result) {
  * different window and the disk keeps claiming `500k` on every probe after it.
  */
 function unreadableWindowValueClause(result) {
-    if (result.action !== 'skipped' || result.previousTokens !== null || result.previousRawValue === undefined)
+    if (result.action !== 'skipped' ||
+        result.previousTokens !== null ||
+        result.previousRawValue === undefined)
         return '';
     const raw = JSON.stringify(result.previousRawValue);
     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.`;
@@ -345,16 +347,34 @@ export function readHarnessWindow(input) {
     const fromEnv = input.env?.[input.location.envVar];
     if (fromEnv !== undefined) {
         return {
-            tokens: parseHarnessWindowTokens(fromEnv), raw: fromEnv, source: 'process-env',
-            optedOut, peakWritten, fileTokens, fileRaw
+            tokens: parseHarnessWindowTokens(fromEnv),
+            raw: fromEnv,
+            source: 'process-env',
+            optedOut,
+            peakWritten,
+            fileTokens,
+            fileRaw
         };
     }
     if (fileRaw !== undefined) {
-        return { tokens: fileTokens, raw: fileRaw, source: 'settings-file', optedOut, peakWritten, fileTokens, fileRaw };
+        return {
+            tokens: fileTokens,
+            raw: fileRaw,
+            source: 'settings-file',
+            optedOut,
+            peakWritten,
+            fileTokens,
+            fileRaw
+        };
     }
     return {
-        tokens: null, raw: undefined, source: null, optedOut, peakWritten: false,
-        fileTokens: null, fileRaw: undefined
+        tokens: null,
+        raw: undefined,
+        source: null,
+        optedOut,
+        peakWritten: false,
+        fileTokens: null,
+        fileRaw: undefined
     };
 }
 /**

package/dist/services/context/ide-detect.js

@@ -8,7 +8,8 @@ export function isIdeKind(value) {
     return IDE_KINDS.includes(value);
 }
 export function detectIdeFromEnv(env = process.env) {
-    if (typeof env['CLAUDE_CODE_ENTRYPOINT'] === 'string' && env['CLAUDE_CODE_ENTRYPOINT'].length > 0) {
+    if (typeof env['CLAUDE_CODE_ENTRYPOINT'] === 'string' &&
+        env['CLAUDE_CODE_ENTRYPOINT'].length > 0) {
         return 'claude-code';
     }
     if (typeof env['CLAUDE_SESSION_ID'] === 'string' && env['CLAUDE_SESSION_ID'].length > 0) {

package/dist/services/context/index.d.ts

@@ -4,4 +4,4 @@ export { tokenize } from './tokenizer.js';
 export { render, type RenderInput } from './renderer.js';
 export { ContextJsonSchema } from './context-schema.js';
 export { buildContext, type BuildInput } from './context-builder.js';
-export type { ContextJson, Audience, DepsMode, FileKind, CollectedFile, GitStatus, MemoryEntry, DepInfo, DocSection, FetchedDoc, SkippedDoc, TokenizedItem, CollectorOutput, DocRetrieverOutput, TokenizerOutput, RendererOutput, } from './types.js';
+export type { ContextJson, Audience, DepsMode, FileKind, CollectedFile, GitStatus, MemoryEntry, DepInfo, DocSection, FetchedDoc, SkippedDoc, TokenizedItem, CollectorOutput, DocRetrieverOutput, TokenizerOutput, RendererOutput } from './types.js';