peaks-loop 4.0.3 → 4.0.4

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 4.0.4 — 2026-07-31 (Mac auto-compact silent failure + user-driven override)
+
+### Bug fixes
+
+- **Mac auto-compact silent failure closed** (rid-001-r1, commit `22debcb`): `readClaudeTranscriptFallback` now recurses into `~/.claude/projects/**/<hash>/` (was: flat readdir of `<hash>/<sid>.jsonl`). On Mac Claude Code, where the transcript can sit under a nested layout the previous flat walk could not predict, the probe was returning `ratio: 0` and the auto-compact orchestrator stayed in `none` zone — `/compact` never fired. New source tag `transcript-estimate` distinguishes this real signal from the no-signal `conservative-fallback` so the CLI can label it correctly. No orchestrator threshold change; no new dependency; works on win32 / darwin / linux. Files: `src/services/context/auto-compact-reader.ts` (surgical: +`findTranscriptJsonl` recursive helper), `src/services/context/auto-compact-types.ts` (JSDoc only), `tests/unit/context/auto-compact-reader.test.ts` (new, 6 cases). Acceptance: `peaks code context-now --json` on Mac returns `ratio >= 0.5` when `<sid>.jsonl` is ~200KB. **Plus a 2-line ESM-compatibility fix** (commit `22debcb`): the original `findTranscriptJsonl` used `require('node:fs')` inside the function body, which threw `ReferenceError: require is not defined` under pure Node 22 ESM and was silently swallowed by the outer `try/catch` — vitest's esbuild shim masked the bug. Moved `readdirSync` to top-level import.
+
+### Features
+
+- Add: `peaks code context-now --prompt-size <bytes>` user-driven override (rid-002, commit `fa98502`). Mac escape hatch when `CLAUDE_CONTEXT_USAGE_PERCENT` is absent. New `source: 'user-overridden'` value at P0 above env / statusline / transcript / fallback. Example: `--prompt-size 200000` → `ratio ≈ 0.762`, `source: 'user-overridden'`. Files: `src/cli/commands/code-runtime-commands.ts`, `src/services/context/auto-compact-reader.ts` (+P0 short-circuit), `src/services/context/auto-compact-types.ts` (JSDoc), `tests/unit/context/auto-compact-reader.test.ts` (+4 cases).
+
+### Documentation
+
+- Add: `docs/mac-auto-compact.md` (78 lines) — Mac user-facing verify + escape hatch doc (rid-003, commit `18f4d68`). 5 sections: TL;DR, Why Mac was broken, How to verify, The escape hatch, Hook integration, Caveats, Related.
+- Add: `CLAUDE.md` line 20 callout linking Mac users to the new doc.
+- Add: 2 project memory entries (`.peaks/memory/2026-07-31-mac-auto-compact-{no-env-injection,esm-fake-green-and-fix}.md`) for future maintainer reference (rid-003-r1, commit `03be94f0`).
+
+### Sub-package lockstep (4.0.4)
+
+- peaks-loop@4.0.4 / peaks-loop-shared@0.0.32 / peaks-loop-mut@0.1.6 / peaks-loop-shared-channel@0.0.11
+- `peaks-loop-shared/dist/version.js` CLI_VERSION bumped to "4.0.4" (publish gate-cli-version reads on-disk, not the packed tarball — both checked)
+
 ## 4.0.3 — 2026-07-30 (GA release, 4.0.2 tombstone skip)
 
 This is the cutover to the in-flight 4.0.3 GA, replacing the prior `## 4.0.1` GA header. 4.0.3 lands because 4.0.2 is a permanent npm tombstone (published-then-unpublished on 2026-07-22; see `.peaks/memory/2026-07-30-4-0-1-published-tombstone-resolution.md` table row 4.0.2: ABSENT in versions[] but time entry `2026-07-22T01:53:48.127Z` still present = tombstoned). The byte-for-byte manifest is identical to 4.0.1; the only diff is the package.json version + the visual README rework (see "Visual / text" below). The 4.0.1 GA section below is preserved as the historical record of the actual `peaks-loop@4.0.1` published at `dist-tags.latest` on 2026-07-30T14:55:22Z; it is NOT the 4.0.3 release body.

package/dist/cli/commands/code-runtime-commands.js

@@ -115,9 +115,20 @@ export function registerCodeRuntimeCommands(code, io) {
         '≥0.95 emits action=red-line (forced hook fires next turn).')
         .requiredOption('--project <path>', 'target project root')
         .option('--session-id <sid>', 'override session id (default: read from active presence)')
-        .option('--enforce-job-mode', 'v3.1.2: treat ≥0.85 as MANDATORY auto-compact (not advisory). Auto-enabled when job-shape.json says isJob=true.')).action(async (opts) => {
+        .option('--enforce-job-mode', 'v3.1.2: treat ≥0.85 as MANDATORY auto-compact (not advisory). Auto-enabled when job-shape.json says isJob=true.')
+        .option('--prompt-size <bytes>', 'override the bytes-from-env path; takes priority over env / statusline / transcript. Useful when CLAUDE_CONTEXT_USAGE_PERCENT is absent (e.g. Mac Claude Code).')).action(async (opts) => {
         try {
             const { readContextPercent } = await import('../../services/context/auto-compact-reader.js');
+            // rid-002: parse --prompt-size <bytes> defensively. CLI-layer
+            // guard rejects non-finite / negative values; only finite
+            // non-negative numbers reach the reader. Undefined → no override.
+            let promptSizeBytes;
+            if (opts.promptSize !== undefined) {
+                const parsed = Number(opts.promptSize);
+                if (Number.isFinite(parsed) && parsed >= 0) {
+                    promptSizeBytes = parsed;
+                }
+            }
             // v3.1.2: detect Job mode from job-shape.json when --enforce-job-mode
             // is not explicitly passed. The LLM is the source of truth for
             // whether the request is Job-shaped; the recorded decision is.
@@ -140,7 +151,8 @@ export function registerCodeRuntimeCommands(code, io) {
             const probe = readContextPercent({
                 projectRoot: opts.project,
                 sessionId: opts.sessionId ?? readActiveSid(opts.project) ?? 'unknown',
-                env: process.env
+                env: process.env,
+                promptSizeBytes
             });
             const ratioPct = (probe.ratio * 100).toFixed(1);
             let action = 'ok';
@@ -179,6 +191,7 @@ export function registerCodeRuntimeCommands(code, io) {
                 ide: probe.ide,
                 capacityBytes: probe.capacityBytes,
                 rawBytes: probe.rawBytes ?? null,
+                bytesPrompt: promptSizeBytes ?? null,
                 capturedAt: probe.capturedAt
             }, [], [
                 action === 'red-line'

package/dist/services/context/auto-compact-reader.d.ts

@@ -3,6 +3,16 @@ export interface ReadContextPercentInput {
     readonly projectRoot: string;
     readonly sessionId: string;
     readonly env?: NodeJS.ProcessEnv | undefined;
+    /**
+     * Slice 2026-07-31-rid-002: explicit byte count from `--prompt-size <bytes>`.
+     * When set to a finite non-negative number, short-circuits the entire
+     * env / statusline / transcript chain with `source: 'user-overridden'`.
+     * Mac escape hatch — Claude Code Mac does NOT inject
+     * `CLAUDE_CONTEXT_USAGE_PERCENT` into PreToolUse sub-shells, so the
+     * user (or a hook wrapper) can inject the bytes they observed themselves.
+     * Priority P0 — above everything else.
+     */
+    readonly promptSizeBytes?: number | undefined;
 }
 /**
  * Read env-var-based context percentage. Returns `null` when the env
@@ -19,12 +29,30 @@ declare function readEnvPercent(env: NodeJS.ProcessEnv, varName: string): number
  */
 declare function readClaudeStatuslinePercent(): number | null;
 /**
- * Conservative transcript-size fallback. Walks
- * `~/.claude/projects/<hash>/<sid>.jsonl` and estimates
+ * Recursive search for `<sessionId>.jsonl` under `projectsDir`. Used by
+ * `readClaudeTranscriptFallback` and exported via `_internal` so unit
+ * tests can drive it without monkey-patching `os.homedir` (which is
+ * non-configurable in ESM module namespaces).
+ *
+ * The Mac layout encodes the cwd as a single hash directory; on Mac
+ * Claude Code nests the transcript under that hash with an extra level
+ * of subdirectory we cannot predict ahead of time. A flat readdir misses
+ * that branch and returns null — the silent-failure mode that this fix
+ * closes.
+ */
+declare function findTranscriptJsonl(projectsDir: string, sessionId: string): {
+    path: string;
+    bytes: number;
+} | null;
+/**
+ * Conservative transcript-size fallback. Recursively searches
+ * `~/.claude/projects/<hash>/<sid-or-nested>.jsonl` (Mac may nest
+ *  the jsonl under an
+ * extra directory we cannot predict ahead of time) and estimates
  * `ratio = bytesUsed / 256K`. Returns the bytes seen so the
  * orchestrator can show "estimated from 124KB of 256KB transcript"
- * in the envelope. Tagged `'conservative-fallback'` so callers
- * know NOT to treat this as a hard gate.
+ * in the envelope. Tagged `'transcript-estimate'` (v2.14.0) so callers
+ * know it is a real signal, NOT a hard gate.
  */
 declare function readClaudeTranscriptFallback(sessionId: string): {
     ratio: number;
@@ -47,5 +75,6 @@ export declare const _internal: {
     readEnvPercent: typeof readEnvPercent;
     readClaudeStatuslinePercent: typeof readClaudeStatuslinePercent;
     readClaudeTranscriptFallback: typeof readClaudeTranscriptFallback;
+    findTranscriptJsonl: typeof findTranscriptJsonl;
 };
 export {};

package/dist/services/context/auto-compact-reader.js

@@ -22,7 +22,7 @@
  *   3. `ratio: 0` with `source: 'conservative-fallback'` — the
  *      orchestrator MUST NOT auto-fire compact on this signal.
  */
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { detectIdeFromEnv } from './ide-detect.js';
@@ -70,25 +70,36 @@ function readClaudeStatuslinePercent() {
     return null;
 }
 /**
- * Conservative transcript-size fallback. Walks
- * `~/.claude/projects/<hash>/<sid>.jsonl` and estimates
- * `ratio = bytesUsed / 256K`. Returns the bytes seen so the
- * orchestrator can show "estimated from 124KB of 256KB transcript"
- * in the envelope. Tagged `'conservative-fallback'` so callers
- * know NOT to treat this as a hard gate.
+ * Recursive search for `<sessionId>.jsonl` under `projectsDir`. Used by
+ * `readClaudeTranscriptFallback` and exported via `_internal` so unit
+ * tests can drive it without monkey-patching `os.homedir` (which is
+ * non-configurable in ESM module namespaces).
+ *
+ * The Mac layout encodes the cwd as a single hash directory; on Mac
+ * Claude Code nests the transcript under that hash with an extra level
+ * of subdirectory we cannot predict ahead of time. A flat readdir misses
+ * that branch and returns null — the silent-failure mode that this fix
+ * closes.
  */
-function readClaudeTranscriptFallback(sessionId) {
-    const projectsDir = join(homedir(), '.claude', 'projects');
+function findTranscriptJsonl(projectsDir, sessionId) {
     if (!existsSync(projectsDir))
         return null;
     try {
-        const { readdirSync } = require('node:fs');
-        for (const hashDir of readdirSync(projectsDir)) {
-            const candidate = join(projectsDir, hashDir, `${sessionId}.jsonl`);
-            if (existsSync(candidate)) {
-                const bytes = statSync(candidate).size;
-                const ratio = Math.min(1, bytes / (256 * 1024));
-                return { ratio, bytes };
+        const stack = [projectsDir];
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            if (dir === undefined)
+                break;
+            const entries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const full = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(full);
+                }
+                else if (entry.isFile() && entry.name === `${sessionId}.jsonl`) {
+                    const bytes = statSync(full).size;
+                    return { path: full, bytes };
+                }
             }
         }
     }
@@ -97,6 +108,24 @@ function readClaudeTranscriptFallback(sessionId) {
     }
     return null;
 }
+/**
+ * Conservative transcript-size fallback. Recursively searches
+ * `~/.claude/projects/<hash>/<sid-or-nested>.jsonl` (Mac may nest
+ *  the jsonl under an
+ * extra directory we cannot predict ahead of time) and estimates
+ * `ratio = bytesUsed / 256K`. Returns the bytes seen so the
+ * orchestrator can show "estimated from 124KB of 256KB transcript"
+ * in the envelope. Tagged `'transcript-estimate'` (v2.14.0) so callers
+ * know it is a real signal, NOT a hard gate.
+ */
+function readClaudeTranscriptFallback(sessionId) {
+    const projectsDir = join(homedir(), '.claude', 'projects');
+    const hit = findTranscriptJsonl(projectsDir, sessionId);
+    if (hit === null)
+        return null;
+    const ratio = Math.min(1, hit.bytes / (256 * 1024));
+    return { ratio, bytes: hit.bytes };
+}
 /**
  * Probe the current AI CLI's context-fill ratio. Adapter-driven:
  * looks up the registered `IdeAdapter.compact` profile via
@@ -121,6 +150,24 @@ export function readContextPercent(input) {
     // through `unknown` to IdeId's wider 8-element set.
     const ideId = (detected === 'unknown' ? 'claude-code' : detected);
     const adapter = getAdapter(ideId);
+    // P0 user-overridden takes priority over env / statusline / transcript.
+    // Mac escape hatch: when the CLI/helper passes `--prompt-size <bytes>`,
+    // honor that number directly. Do NOT read env, statusline, or transcript
+    // — user intent always wins. Negative / non-finite values are ignored
+    // here (CLI layer validates >= 0); they fall through to the chain below.
+    if (input.promptSizeBytes !== undefined &&
+        Number.isFinite(input.promptSizeBytes) &&
+        input.promptSizeBytes >= 0) {
+        const ratio = Math.min(1, input.promptSizeBytes / capacityBytes);
+        return {
+            ratio,
+            source: 'user-overridden',
+            rawBytes: input.promptSizeBytes,
+            capacityBytes,
+            ide: ideId,
+            capturedAt
+        };
+    }
     // Primary: read the adapter-declared env-var (no hard-coded IDE names).
     if (adapter.compact) {
         const primary = readEnvPercent(env, adapter.compact.envVarForContextPercent);
@@ -147,7 +194,7 @@ export function readContextPercent(input) {
         if (fallback !== null) {
             return {
                 ratio: fallback.ratio,
-                source: 'conservative-fallback',
+                source: 'transcript-estimate',
                 rawBytes: fallback.bytes,
                 capacityBytes,
                 ide: ideId,
@@ -161,4 +208,4 @@ export function readContextPercent(input) {
     return { ratio: 0, source: 'conservative-fallback', capacityBytes, ide: ideId, capturedAt };
 }
 /** Re-export the env-var probe for unit tests. */
-export const _internal = { readEnvPercent, readClaudeStatuslinePercent, readClaudeTranscriptFallback };
+export const _internal = { readEnvPercent, readClaudeStatuslinePercent, readClaudeTranscriptFallback, findTranscriptJsonl };

package/dist/services/context/auto-compact-types.d.ts

@@ -152,10 +152,18 @@ export interface ContextPercentProbe {
     readonly ratio: number;
     /**
      * Adapter-driven source tag. Fixed values:
+     *   - `user-overridden`         (v2.14.0 rid-002: explicit `--prompt-size
+     *                                <bytes>` from the CLI / hook wrapper —
+     *                                takes priority P0 over EVERY other source.
+     *                                Mac escape hatch.)
      *   - `${ideId}-env`            (e.g. `claude-code-env`)
      *   - `statusline-poll`         (Claude Code MVP fallback)
-     *   - `conservative-fallback`   (transcript size estimate OR
-     *                                no signal available — caller
+     *   - `transcript-estimate`     (v2.14.0 Mac-aware: recursive
+     *                                readdir under ~/.claude/projects/
+     *                                finds <sid>.jsonl and reports
+     *                                bytes/256K; a real signal, NOT
+     *                                a hard gate)
+     *   - `conservative-fallback`   (no signal available — caller
      *                                MUST NOT treat as hard gate)
      * Future IDEs may add per-ide sources; the type accepts any
      * string to keep the schema forward-compatible.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.3",
+  "version": "4.0.4",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -98,9 +98,9 @@
     "headroom-ai": "0.22.4",
     "yaml": "^2.9.0",
     "zod": "^3.25.76",
-    "peaks-loop-mut": "0.1.6",
-    "peaks-loop-shared-channel": "0.0.11",
-    "peaks-loop-shared": "0.0.32"
+    "peaks-loop-mut": "0.1.7",
+    "peaks-loop-shared": "0.0.33",
+    "peaks-loop-shared-channel": "0.0.12"
   },
   "peerDependencies": {
     "@alibaba-group/open-code-review": "1.3.1"