peaks-loop 4.0.36 → 4.0.37

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

@@ -0,0 +1,150 @@
+/**
+ * Slice 2026-09-10-three-fixes (Slice 2) — proactive context-consumer hint.
+ *
+ * `peaks code context-audit` (Slice A, same day) already reports WHAT fills
+ * the window, but only when someone remembers to run it. The Step 0.8
+ * PreToolUse gate (`peaks code gate-step-08`) runs before every Bash call, so
+ * it is the natural place to surface the single largest consumer — provided
+ * that costs nothing measurable.
+ *
+ * Cost contract (the whole point of this module):
+ *   - The ratio probe is the cheap, adapter-driven `readContextPercent`
+ *     (env-var → statusline file read; the transcript fallback is a
+ *     bounded backwards scan, never a whole-file read).
+ *   - The expensive part — the transcript scan inside `auditContext` — runs
+ *     at most ONCE per TTL window. Its result is cached under
+ *     `.peaks/_runtime/<sid>/context-audit-hint.json`; a fresh entry
+ *     short-circuits the scan entirely.
+ *   - Every failure is fail-soft: a missing/corrupt cache, an unavailable
+ *     transcript, an adapter that cannot locate one — all yield `null`
+ *     (emit nothing). The gate never blocks and never gains more than ONE
+ *     line.
+ *
+ * The cache deliberately records FAILED audits too (with `available:false`),
+ * so a broken transcript cannot turn every Bash call back into a scan.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWriteJson } from '../ide/shared/atomic-json.js';
+import { readContextPercent } from './auto-compact-reader.js';
+import { auditContext } from './context-audit.js';
+/** Only surface a hint once the window is this full. */
+export const CONTEXT_HINT_RATIO_THRESHOLD = 0.7;
+/** Minimum cache TTL — a fresh entry must skip the transcript scan. */
+export const CONTEXT_HINT_CACHE_TTL_MS = 5 * 60 * 1000;
+/** Per-session cache file name (under `.peaks/_runtime/<sid>/`). */
+export const CONTEXT_HINT_CACHE_FILE_NAME = 'context-audit-hint.json';
+/**
+ * `<projectRoot>/.peaks/_runtime/<sid>/context/context-audit-hint.json`
+ * (gitignored). The `context/` bucket mirrors the existing `<sid>/txt/`
+ * convention so session-id artifacts stay under `.peaks/_runtime/<sid>/`.
+ */
+export function contextHintCachePath(projectRoot, sessionId) {
+    const safeSessionId = sessionId.replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '');
+    return join(projectRoot, '.peaks', '_runtime', safeSessionId.length > 0 ? safeSessionId : 'unknown', 'context', CONTEXT_HINT_CACHE_FILE_NAME);
+}
+/**
+ * The single line the gate may append. Names ONE consumer — the largest by
+ * tool-result bytes — plus the share and call count that justify the number.
+ */
+export function formatContextHintLine(entry) {
+    const ratioPct = (entry.ratio * 100).toFixed(1);
+    const sharePct = entry.pctOfTotal.toFixed(1);
+    const calls = entry.count === 1 ? '1 call' : `${entry.count} calls`;
+    return `Context ${ratioPct}% used — top consumer: ${entry.tool} \`${entry.key}\` (${sharePct}% of tool-result bytes, ${calls}). Run \`peaks code context-audit\` for the full breakdown.`;
+}
+function readCache(cachePath) {
+    if (!existsSync(cachePath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath, 'utf8'));
+        if (typeof parsed.cachedAt !== 'number' || !Number.isFinite(parsed.cachedAt))
+            return null;
+        if (typeof parsed.available !== 'boolean')
+            return null;
+        return {
+            cachedAt: parsed.cachedAt,
+            available: parsed.available,
+            ratio: typeof parsed.ratio === 'number' && Number.isFinite(parsed.ratio) ? parsed.ratio : 0,
+            tool: typeof parsed.tool === 'string' ? parsed.tool : null,
+            key: typeof parsed.key === 'string' ? parsed.key : null,
+            bytes: typeof parsed.bytes === 'number' && Number.isFinite(parsed.bytes) ? parsed.bytes : 0,
+            pctOfTotal: typeof parsed.pctOfTotal === 'number' && Number.isFinite(parsed.pctOfTotal) ? parsed.pctOfTotal : 0,
+            count: typeof parsed.count === 'number' && Number.isFinite(parsed.count) ? parsed.count : 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Never throws: an unavailable ratio probe degrades to "no hint". */
+function probeRatioSafe(input) {
+    if (input.probeRatio !== undefined) {
+        try {
+            const value = input.probeRatio();
+            return typeof value === 'number' && Number.isFinite(value) ? value : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        const probe = readContextPercent({
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            outerSessionId: input.outerSessionId ?? undefined,
+            env: input.env ?? process.env,
+        });
+        return Number.isFinite(probe.ratio) ? probe.ratio : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build the ONE optional hint line for the Step 0.8 gate.
+ *
+ * Returns `null` when: the ratio is unknown or below 0.70, the cache (fresh)
+ * says the audit was unavailable, the fresh audit found no groups, or
+ * anything throws. Never throws, never blocks.
+ */
+export function buildContextAuditHint(input) {
+    try {
+        const nowMs = input.nowMs ?? Date.now();
+        const ratio = probeRatioSafe(input);
+        if (ratio === null || ratio < CONTEXT_HINT_RATIO_THRESHOLD)
+            return null;
+        const cachePath = input.cachePath ?? contextHintCachePath(input.projectRoot, input.sessionId);
+        const cached = readCache(cachePath);
+        // Fresh entry → the transcript scan is skipped entirely (cost guard).
+        if (cached !== null && nowMs - cached.cachedAt < CONTEXT_HINT_CACHE_TTL_MS) {
+            return cached.available && cached.tool !== null ? formatContextHintLine(cached) : null;
+        }
+        // Cache miss / stale → at most one scan per TTL window.
+        const result = (input.runAudit ?? auditContext)({
+            outerSessionId: input.outerSessionId ?? null,
+            topN: 1,
+        });
+        const top = result.available ? (result.entries[0] ?? null) : null;
+        const entry = {
+            cachedAt: nowMs,
+            available: result.available,
+            ratio,
+            tool: top?.tool ?? null,
+            key: top?.key ?? null,
+            bytes: top?.bytes ?? 0,
+            pctOfTotal: top?.pctOfTotal ?? 0,
+            count: top?.count ?? 0,
+        };
+        try {
+            atomicWriteJson(cachePath, entry);
+        }
+        catch {
+            // Fail-soft: an unwritable cache must not lose this turn's hint.
+        }
+        return top !== null ? formatContextHintLine(entry) : null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -32,6 +32,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { resolveHookShell } from '../skills/hooks-codegate-superpowers.js';
 /**
  * Stable matcher for the auto-compact hook. Single source of truth
  * — `install` and `remove` both key off this constant so the
@@ -105,6 +106,13 @@ export function installAutoCompactHook(input) {
     if (alreadyInstalled) {
         return { action: 'already-installed', settingsPath };
     }
+    // The matcher is `Bash|Task`, so on Windows this runs on the same
+    // Git-Bash / MSYS2 shell-form path as the other peaks Bash hooks, which
+    // force-allocates a console window on every matching tool call. The
+    // entry is written only into the machine-local, gitignored
+    // `.claude/settings.local.json`, so a machine-specific `shell` cannot
+    // leak into a shared file. `undefined` on POSIX omits the key entirely.
+    const shell = resolveHookShell();
     const nextPreToolUse = [
         ...preToolUse,
         {
@@ -112,7 +120,8 @@ export function installAutoCompactHook(input) {
             hooks: [
                 {
                     type: 'command',
-                    command: AUTO_COMPACT_HOOK_COMMAND
+                    command: AUTO_COMPACT_HOOK_COMMAND,
+                    ...(shell !== undefined ? { shell } : {})
                 }
             ]
         }

package/dist/services/hooks/write-gate.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * write-gate.js — peaks Write|Edit|MultiEdit PreToolUse path gate.
+ *
+ * Slice c5-write-hook-exec-form (session 2026-09-10-session-528a63).
+ * VERBATIM RELOCATION: the predicate chain below was character-for-character
+ * the chain that used to be inlined into `claude-settings-template.ts` as a
+ * `node -e "<js>"` one-liner.
+ *
+ * Slice c5b-write-gate-polarity (same session) NARROWED the decision to match
+ * the contract `.claude/HOOKS.md` documents for this handler. The relocated
+ * chain read its eight directory names as an EXCLUSION list, so `_runtime`
+ * AND every other `.peaks/<slug>/` were allowed; it now allows only paths
+ * under `.peaks/_runtime/` and falls through on everything else. That earlier
+ * polarity also permitted a top-level `.peaks/<change-id>/` write, which
+ * `CLAUDE.md`'s hard ban forbids outright.
+ *
+ * Why it moved into a file: the inlined form was shell-dialect-coupled. Its
+ * escaping contract was defined in terms of bash reducing `\\` to `\` inside a
+ * `"..."` wrapper, which PowerShell does NOT do — so the handler could not take
+ * the platform `shell` pin its Bash siblings carry. `node <path>` has no inline
+ * payload, so there is nothing left to escape and no dialect to couple to.
+ *
+ * Why `.js` and not `.sh` (the convention for the other hook scripts here):
+ *   - `.sh` needs `bash`; on Windows that means Git Bash, so it is itself a
+ *     shell dependency and the escaping problem merely moves to the
+ *     `bash <script>` boundary.
+ *   - `node` is already a hard dependency — the previous form invoked it.
+ *   - A plain `.js` needs no compile step, so the SAME relative filename
+ *     exists in `src/` (used by `tsx` + vitest) and in `dist/` (copied by
+ *     `scripts/copy-templates.mjs`), which lets one emitted path string be
+ *     valid for both the repo and an installed consumer.
+ *
+ * Contract (`.claude/HOOKS.md`): exit 0 = allow, exit 1 = fall through to the
+ * gate — NOT a deny. Only exit 2 blocks a tool call, and this handler never
+ * returns it. This handler's job is to stay silent on the paths the gate is
+ * meant to skip.
+ *
+ * Path source: the hook payload arrives as JSON on STDIN (Claude Code's
+ * documented channel; it appends no argv). `process.argv[2]` is honoured as a
+ * fallback so a positional-arg invocation keeps working.
+ */
+
+/** First string found at any of the candidate keys of `root`. */
+function pathFrom(root) {
+  if (!root || typeof root !== 'object') return '';
+  for (const key of ['file_path', 'path', 'notebook_path']) {
+    if (typeof root[key] === 'string') return root[key];
+  }
+  return '';
+}
+
+/** Pull the candidate file path out of a parsed hook payload. */
+function candidatePath(payload) {
+  if (!payload || typeof payload !== 'object') return '';
+  return pathFrom(payload.tool_input) || pathFrom(payload);
+}
+
+/**
+ * The gate decision: allow (0) only for paths under `.peaks/_runtime/`;
+ * everything else falls through to the gate (1).
+ */
+function decide(p) {
+  return p.includes('.peaks/_runtime/') ? 0 : 1;
+}
+
+const ARGV_PATH = typeof process.argv[2] === 'string' ? process.argv[2] : '';
+
+// No stdin to read (a human running this by hand): decide on argv alone
+// instead of blocking forever waiting for an 'end' that never comes.
+if (process.stdin.isTTY) {
+  process.exit(decide(ARGV_PATH));
+}
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    // Malformed or empty payload → no path → deny, which is the same
+    // outcome the old form produced for an absent `process.argv[1]`.
+    payload = undefined;
+  }
+  process.exit(decide(candidatePath(payload) || ARGV_PATH));
+});

package/dist/services/lint/detect-eslint.d.ts

@@ -7,4 +7,6 @@ export type EslintDetectResult = {
     readonly warnings: readonly string[];
     readonly nextActions: readonly string[];
 };
+/** Named code for "npm itself could not be launched" — distinct from a registry miss. */
+export declare const NPM_PROBE_UNRESOLVED_CODE = "NPM_PROBE_UNRESOLVED";
 export declare function detectEslint(): EslintDetectResult;

package/dist/services/lint/detect-eslint.js

@@ -4,7 +4,7 @@
  * unified Gate B5 verdict.
  */
 import { spawnSync } from 'node:child_process';
-import { resolveNpxInvocation } from './npx-resolver.js';
+import { resolveNpmInvocation, resolveNpxInvocation } from './npx-resolver.js';
 import { ESLINT_PACKAGE_PINS } from './eslint-runner.js';
 const PACKAGES_TO_PROBE = [
     'eslint',
@@ -23,14 +23,23 @@ function probeNpx() {
     const probe = spawnSync(command, args, { encoding: 'utf8', env: baseEnv });
     return probe.status === 0;
 }
+/** Named code for "npm itself could not be launched" — distinct from a registry miss. */
+export const NPM_PROBE_UNRESOLVED_CODE = 'NPM_PROBE_UNRESOLVED';
 function probePackage(key) {
     const pkg = packageNameFor(key);
     const pin = ESLINT_PACKAGE_PINS[key];
-    // shell:true required on Windows because `npm` (like npx) is a `.cmd`
-    // shim; Node 22 refuses to invoke it without shell wrapper.
-    // 2026-08-06 lint-dogfood cycle-2 follow-up.
-    const result = spawnSync('npm', ['view', `${pkg}@${pin}`, 'version'], { encoding: 'utf8', shell: true });
-    return result.status === 0;
+    // 2026-09-10: `npm` on Windows is an `npm.cmd` shim, which Node >= 20 refuses
+    // to spawn at all without `shell: true` — and `shell: true` concatenates the
+    // argv unescaped (DEP0190 on every call, and any argument containing a space
+    // is split). So the shim is bypassed: `resolveNpmInvocation` resolves npm's
+    // own JS entry and this runs it through `process.execPath`. Same shape as the
+    // npx probe above and as `eslint-runner.ts`.
+    const { command, args, baseEnv } = resolveNpmInvocation(['view', `${pkg}@${pin}`, 'version']);
+    const result = spawnSync(command, args, { encoding: 'utf8', env: baseEnv });
+    return {
+        ok: result.status === 0,
+        error: result.error === undefined || result.error === null ? null : result.error.message
+    };
 }
 export function detectEslint() {
     const nextActions = [];
@@ -45,9 +54,14 @@ export function detectEslint() {
         };
     }
     for (const key of PACKAGES_TO_PROBE) {
-        if (!probePackage(key)) {
-            warnings.push(`npm registry cannot resolve ${packageNameFor(key)}@${ESLINT_PACKAGE_PINS[key]}`);
-        }
+        const probe = probePackage(key);
+        if (probe.ok)
+            continue;
+        const target = `${packageNameFor(key)}@${ESLINT_PACKAGE_PINS[key]}`;
+        warnings.push(probe.error === null
+            ? `npm registry cannot resolve ${target}`
+            : `${NPM_PROBE_UNRESOLVED_CODE}: could not launch npm to probe ${target} (${probe.error}). ` +
+                'Ensure Node.js >= 20 with its bundled npm is installed.');
     }
     if (warnings.length > 0) {
         nextActions.push('Re-run `peaks code lint --json` after npm connectivity is restored.');

package/dist/services/lint/npx-resolver.d.ts

@@ -4,3 +4,9 @@ export type NpxInvocation = {
     readonly baseEnv: NodeJS.ProcessEnv;
 };
 export declare function resolveNpxInvocation(npxArgs: readonly string[]): NpxInvocation;
+/**
+ * `npm` sibling of `resolveNpxInvocation`, same shim bypass: `node
+ * <npm-cli.js> <args>`. A caller must NOT reach for bare `npm` + `shell: true`
+ * instead — the shim is the defect, not the justification.
+ */
+export declare function resolveNpmInvocation(npmArgs: readonly string[]): NpxInvocation;

package/dist/services/lint/npx-resolver.js

@@ -1,26 +1,28 @@
 /**
- * Cross-platform `npx` resolver.
+ * Cross-platform `npm` / `npx` resolver.
  *
- * On Windows, `npm` installs `npx` as a `.cmd` shim; Node 22's
- * `child_process.spawnSync` refuses to invoke it unless `shell: true`
- * is set, and `shell: true` corrupts quoted `--package` arguments.
- * Rather than depend on shell quoting, this helper resolves the
- * npx script bundled with the user's `npm` install and invokes it
- * via `node <npx-cli.js>` with the same argv. macOS / Linux continue
- * to use the regular `npx` binary.
+ * On Windows, `npm` installs `npx` and `npm` as `.cmd` shims; Node's
+ * `child_process.spawnSync` refuses to invoke a `.cmd` unless `shell: true`
+ * is set, and `shell: true` concatenates (does not escape) the argv — it
+ * corrupts quoted `--package` arguments, splits any argument containing a
+ * space, and emits DEP0190 on every call. Rather than depend on shell
+ * quoting, these helpers resolve the CLI script bundled with the user's
+ * `npm` install and invoke it via `node <npm|npx>-cli.js` with the same
+ * argv. macOS / Linux continue to use the regular binaries.
  */
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import process from 'node:process';
-function locateNpxCliScript() {
+/** Locate `<npm install>/bin/<scriptFile>`, or `null` when not on disk. */
+function locateNpmCliScript(scriptFile) {
     const candidates = process.platform === 'win32'
         ? [
-            join(process.execPath, '..', '..', 'node_modules', 'npm', 'bin', 'npx-cli.js'),
-            'C:/nvm4w/nodejs/node_modules/npm/bin/npx-cli.js',
-            'C:/Program Files/nodejs/node_modules/npm/bin/npx-cli.js'
+            join(process.execPath, '..', '..', 'node_modules', 'npm', 'bin', scriptFile),
+            `C:/nvm4w/nodejs/node_modules/npm/bin/${scriptFile}`,
+            `C:/Program Files/nodejs/node_modules/npm/bin/${scriptFile}`
         ]
         : [
-            join(process.execPath, '..', '..', 'lib', 'node_modules', 'npm', 'bin', 'npx-cli.js')
+            join(process.execPath, '..', '..', 'lib', 'node_modules', 'npm', 'bin', scriptFile)
         ];
     for (const candidate of candidates) {
         if (existsSync(candidate))
@@ -30,7 +32,7 @@ function locateNpxCliScript() {
 }
 export function resolveNpxInvocation(npxArgs) {
     if (process.platform === 'win32') {
-        const cliScript = locateNpxCliScript();
+        const cliScript = locateNpmCliScript('npx-cli.js');
         if (cliScript !== null) {
             return {
                 command: process.execPath,
@@ -45,3 +47,25 @@ export function resolveNpxInvocation(npxArgs) {
         baseEnv: process.env
     };
 }
+/**
+ * `npm` sibling of `resolveNpxInvocation`, same shim bypass: `node
+ * <npm-cli.js> <args>`. A caller must NOT reach for bare `npm` + `shell: true`
+ * instead — the shim is the defect, not the justification.
+ */
+export function resolveNpmInvocation(npmArgs) {
+    if (process.platform === 'win32') {
+        const cliScript = locateNpmCliScript('npm-cli.js');
+        if (cliScript !== null) {
+            return {
+                command: process.execPath,
+                args: [cliScript, ...npmArgs],
+                baseEnv: process.env
+            };
+        }
+    }
+    return {
+        command: 'npm',
+        args: npmArgs,
+        baseEnv: process.env
+    };
+}

package/dist/services/release/version-precheck-service.js

@@ -114,9 +114,16 @@ export function runRootVsShared(opts) {
 export function runTagCollision(opts) {
     const rootVersion = readRootVersion(opts.projectRoot);
     const tagName = `v${rootVersion}`;
-    // Windows shell wrapping convention: 5 prior occurrences in tests/unit/release/.
+    // 2026-09-10: no shell. `git` is `git.exe` on Windows, so the wrapper bought
+    // nothing — and it actively broke this layer, because `projectRoot` is an
+    // ARGUMENT to git and a shell wraps the command line unescaped. On a project
+    // whose path contains a space the shell split it, git exited 128
+    // ("cannot change to '…'"), and the layer fell through to its
+    // "git tag --list exited with code 128; layer skipped" WARNING — so a real
+    // tag collision was reported as merely deferred. Reproduced on
+    // `…\Temp\peaks space demo` with tag v9.9.9 present: warning (should be
+    // blocker). It also emitted DEP0190 on every run, on every layer.
     const res = spawnSync('git', ['-C', opts.projectRoot, 'tag', '--list', tagName], {
-        shell: process.platform === 'win32',
         encoding: 'utf8',
         timeout: 5_000
     });

package/dist/services/scan/file-size-scan.d.ts

@@ -1,4 +1,29 @@
 export declare const DEFAULT_FILE_SIZE_THRESHOLD = 800;
+/**
+ * Paths exempt from the file-size cap. The cap is Karpathy's "Simplicity
+ * First": it exists to make a human *simplify* an over-long file. A path is
+ * therefore exempt exactly when no such simplification exists — which is two
+ * kinds of file, both listed below so the reason is visible next to the rule.
+ *
+ * Tool output (whole-cloth generated, nobody maintains it by hand):
+ * `.peaks/**` is Peaks-Loop's own state store and holds three derived indexes
+ * already over the cap (`memory/index.json`, `lint/baseline.json`,
+ * `retrospective/index.json`); exempting only `memory/` would leave the other
+ * two false positives intact. No source module lives there, and its largest
+ * hand-authored file is under 500 lines. Lockfiles are regenerated on every
+ * install.
+ *
+ * Append-only records: `CHANGELOG.md` is history, so its length is a function
+ * of how long the project has existed, not of anyone's design choices — the
+ * only way to "fix" a violation would be to delete the record. Left checked,
+ * this gate is reliably red on every release, precisely when it cannot be
+ * acted on, which trains people to ignore it. A nested changelog under
+ * `packages/` is the same kind of record.
+ *
+ * Declared once, here — do not add special-cases in the scan loop.
+ */
+export declare const SIZE_CAP_EXEMPT_PATTERNS: readonly string[];
+export declare function isSizeCapExempt(file: string): boolean;
 export type FileSizeViolation = {
     file: string;
     lines: number;
@@ -7,6 +32,10 @@ export type FileSizeScanResult = {
     ok: boolean;
     threshold: number;
     checkedFiles: number;
+    /** Paths skipped by SIZE_CAP_EXEMPT_PATTERNS (tool output + append-only
+     *  records). Reported so the exemption is auditable rather than a silent
+     *  skip. */
+    exemptFiles: string[];
     /** Files that appeared in `git diff` but no longer exist on disk (e.g.
      *  deleted in the working tree). Pre-#015 the scan crashed on these via
      *  ENOENT; now they are reported here as informational data. */

package/dist/services/scan/file-size-scan.js

@@ -2,6 +2,63 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 export const DEFAULT_FILE_SIZE_THRESHOLD = 800;
+/**
+ * Paths exempt from the file-size cap. The cap is Karpathy's "Simplicity
+ * First": it exists to make a human *simplify* an over-long file. A path is
+ * therefore exempt exactly when no such simplification exists — which is two
+ * kinds of file, both listed below so the reason is visible next to the rule.
+ *
+ * Tool output (whole-cloth generated, nobody maintains it by hand):
+ * `.peaks/**` is Peaks-Loop's own state store and holds three derived indexes
+ * already over the cap (`memory/index.json`, `lint/baseline.json`,
+ * `retrospective/index.json`); exempting only `memory/` would leave the other
+ * two false positives intact. No source module lives there, and its largest
+ * hand-authored file is under 500 lines. Lockfiles are regenerated on every
+ * install.
+ *
+ * Append-only records: `CHANGELOG.md` is history, so its length is a function
+ * of how long the project has existed, not of anyone's design choices — the
+ * only way to "fix" a violation would be to delete the record. Left checked,
+ * this gate is reliably red on every release, precisely when it cannot be
+ * acted on, which trains people to ignore it. A nested changelog under
+ * `packages/` is the same kind of record.
+ *
+ * Declared once, here — do not add special-cases in the scan loop.
+ */
+export const SIZE_CAP_EXEMPT_PATTERNS = [
+    // tool output
+    '.peaks/**',
+    '**/pnpm-lock.yaml',
+    '**/package-lock.json',
+    '**/yarn.lock',
+    // append-only records
+    '**/CHANGELOG.md'
+];
+/**
+ * Glob → RegExp for the shapes above only, in a single split pass (chained
+ * string replaces would re-expand the `.*` they had just produced). The
+ * directory-wildcard prefix matches zero directories, so a root-level
+ * lockfile still counts.
+ */
+function exemptPatternToRegExp(pattern) {
+    const body = pattern
+        .split(/(\*\*\/|\*\*|\*)/)
+        .map((part) => {
+        if (part === '**/')
+            return '(?:.*/)?';
+        if (part === '**')
+            return '.*';
+        if (part === '*')
+            return '[^/]*';
+        return part.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    })
+        .join('');
+    return new RegExp(`^${body}$`);
+}
+export function isSizeCapExempt(file) {
+    const normalized = file.replace(/\\/g, '/');
+    return SIZE_CAP_EXEMPT_PATTERNS.some((pattern) => exemptPatternToRegExp(pattern).test(normalized));
+}
 function getChangedFiles(projectRoot, baseRef) {
     try {
         // --diff-filter=AM keeps only Added + Modified entries. Deleted files
@@ -28,8 +85,13 @@ export function scanFileSize(options) {
     const files = getChangedFiles(options.projectRoot, baseRef);
     const violations = [];
     const deletedFiles = [];
+    const exemptFiles = [];
     let checkedFiles = 0;
     for (const file of files) {
+        if (isSizeCapExempt(file)) {
+            exemptFiles.push(file);
+            continue;
+        }
         const absolute = join(options.projectRoot, file);
         // Pre-#015: readFileSync threw ENOENT for files that appear in
         // `git diff --name-only` but no longer exist on disk (e.g. a refactor
@@ -62,6 +124,7 @@ export function scanFileSize(options) {
         ok: violations.length === 0,
         threshold,
         checkedFiles,
+        exemptFiles,
         deletedFiles,
         violations
     };

package/dist/services/session/caller-binding-service.d.ts

@@ -68,6 +68,30 @@ export declare function getCallerBinding(projectRoot: string, callerId: string):
  * documented 4.0.14 carry-forward micro-fix from QA's issue #1.
  */
 export declare function setCallerBinding(projectRoot: string, callerId: string, binding: CallerBinding): void;
+/**
+ * Repoint an EXISTING per-caller binding at a new peak session id.
+ *
+ * Slice 2026-09-10 (rid=rebind-must-update-caller-binding): an explicit
+ * `peaks workspace init --session-id <X> --allow-session-rebind` rewrites
+ * the project-global `.peaks/_runtime/session.json`. Without this call the
+ * per-caller file keeps shadowing it for `getSessionIdCanonical`, so the
+ * rebind silently did not take for every command that resolves through
+ * that variant (`peaks session checkpoint`, `peaks session 24h-mode`, ...)
+ * while `getCurrentSessionId` reported the new session.
+ *
+ * Only the binding of the caller that performed the rebind is repointed —
+ * a second caller keeps its own session, which is the multi-caller
+ * isolation the per-caller design exists for.
+ *
+ * Every other field is preserved: `createdAt` is the session creation
+ * stamp the legacy `session.json` dual-write reuses, and `skill` / `mode`
+ * / `gate` are live presence state.
+ *
+ * @returns `true` when a binding existed and was repointed, `false` when
+ *   the caller had no binding file (nothing was shadowing the rebind, and
+ *   we do not create one speculatively).
+ */
+export declare function updateCallerBindingSessionId(projectRoot: string, callerId: string, peakSessionId: string): boolean;
 /**
  * Enumerate the per-caller binding files under
  * `.peaks/_runtime/callers/`. Returns the parsed bindings plus the

package/dist/services/session/caller-binding-service.js

@@ -120,6 +120,40 @@ export function setCallerBinding(projectRoot, callerId, binding) {
     };
     atomicWriteJson(bindingPath, payload);
 }
+/**
+ * Repoint an EXISTING per-caller binding at a new peak session id.
+ *
+ * Slice 2026-09-10 (rid=rebind-must-update-caller-binding): an explicit
+ * `peaks workspace init --session-id <X> --allow-session-rebind` rewrites
+ * the project-global `.peaks/_runtime/session.json`. Without this call the
+ * per-caller file keeps shadowing it for `getSessionIdCanonical`, so the
+ * rebind silently did not take for every command that resolves through
+ * that variant (`peaks session checkpoint`, `peaks session 24h-mode`, ...)
+ * while `getCurrentSessionId` reported the new session.
+ *
+ * Only the binding of the caller that performed the rebind is repointed —
+ * a second caller keeps its own session, which is the multi-caller
+ * isolation the per-caller design exists for.
+ *
+ * Every other field is preserved: `createdAt` is the session creation
+ * stamp the legacy `session.json` dual-write reuses, and `skill` / `mode`
+ * / `gate` are live presence state.
+ *
+ * @returns `true` when a binding existed and was repointed, `false` when
+ *   the caller had no binding file (nothing was shadowing the rebind, and
+ *   we do not create one speculatively).
+ */
+export function updateCallerBindingSessionId(projectRoot, callerId, peakSessionId) {
+    const existing = getCallerBinding(projectRoot, callerId);
+    if (existing === null)
+        return false;
+    setCallerBinding(projectRoot, callerId, {
+        ...existing,
+        peakSessionId,
+        lastActivityAt: new Date().toISOString()
+    });
+    return true;
+}
 /**
  * Enumerate the per-caller binding files under
  * `.peaks/_runtime/callers/`. Returns the parsed bindings plus the