peaks-loop 4.0.26 → 4.0.27

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 4.0.27 — 2026-09-01 (auto-compact context probe fix)
+
+**1 atomic commit from session 2026-09-01-session-fdd7aa**:
+
+- `7f0f4ca2` perf(auto-compact): vendor-neutral context probe + token-based transcript calibration
+
+**Highlights**:
+
+1. **auto-compact 根因修复（三级链）** — context 比例探针之前永远返回 `conservative-fallback`（ratio 0），auto-compact 从不触发。三处修复：(a) vendor-neutral：Claude transcript/statusline fallback 收进 claude-code-adapter 的 `IdeCompactProfile.readContextPercentFallback`，通用 reader 不再硬编码 `~/.claude`；(b) session-id：transcript 查找改用 `outerSessionId`（Claude Code 真 UUID）而非 peaks `sessionId`；(c) 校准：`ratio = contextTokens / contextWindowTokens`，contextTokens 从最新 `message.usage`（input + cache_read + cache_creation）读取，contextWindowTokens 模型感知（1M vs 200K 默认），替换错误的 `bytes/256KB`（永远 100%）。
+
 ## 4.0.26 — 2026-09-01 (headroom removal + prompt-cache prefix alignment)
 
 **2 atomic commits from session 2026-09-01-session-fdd7aa**:

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

@@ -15,6 +15,7 @@ import { evaluateEmitHandoff, JOB_NOT_INITIALIZED, JOB_REMAINING_BLOCKED } from
 import { readJobShapeDecision, JobShapeDecisionError } from '../../services/code/job-shape-decision.js';
 import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
 import { probeInFlightBatch } from '../../services/workflow/workflow-inflight-probe.js';
+import { resolveOuterSessionId } from '../../services/session/binding-status-service.js';
 export function registerCodeRuntimeCommands(code, io) {
     addJsonOption(code
         .command('post-compact-detect')
@@ -175,9 +176,12 @@ export function registerCodeRuntimeCommands(code, io) {
                     // missing/malformed decision file is fine — fall back to advisory.
                 }
             }
+            const sessionId = opts.sessionId ?? readActiveSid(opts.project) ?? 'unknown';
+            const outerSessionId = resolveOuterSessionId(opts.project, sessionId);
             const probe = readContextPercent({
                 projectRoot: opts.project,
-                sessionId: opts.sessionId ?? readActiveSid(opts.project) ?? 'unknown',
+                sessionId,
+                outerSessionId,
                 env: process.env,
                 promptSizeBytes
             });
@@ -218,6 +222,8 @@ export function registerCodeRuntimeCommands(code, io) {
                 ide: probe.ide,
                 capacityBytes: probe.capacityBytes,
                 rawBytes: probe.rawBytes ?? null,
+                rawTokens: probe.rawTokens ?? null,
+                capacityTokens: probe.capacityTokens ?? null,
                 bytesPrompt: promptSizeBytes ?? null,
                 capturedAt: probe.capturedAt
             }, [], [

package/dist/cli/commands/dispatch-commands.js

@@ -27,6 +27,7 @@ import { noteDispatched, BATCH_LIMIT } from '../../services/dispatch/batch-count
 import { writeInitialDispatchRecord } from '../../services/dispatch/dispatch-record-writer.js';
 import { evaluatePromptSize } from '../../services/context/context-guard.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { resolveOuterSessionId } from '../../services/session/binding-status-service.js';
 import { buildArtifactMeta, buildContextImpact } from '../../services/context/artifact-meta.js';
 import { assertSafeArtifactPath } from 'peaks-loop-shared-channel';
 import { playwrightProfilePaths } from '../../services/worktree/playwright-profile.js';
@@ -382,9 +383,11 @@ export function registerDispatchCommand(parent, io) {
             let contextProbe = null;
             try {
                 const { readContextPercent } = await import('../../services/context/auto-compact-reader.js');
+                const outerSessionId = resolveOuterSessionId(projectRoot, sid);
                 contextProbe = readContextPercent({
                     projectRoot,
                     sessionId: sid,
+                    outerSessionId,
                     env: process.env
                 });
             }

package/dist/services/code/auto-compact-orchestrator.js

@@ -31,6 +31,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { getSessionIdCanonical } from '../session/session-manager.js';
+import { resolveOuterSessionId } from '../session/binding-status-service.js';
 import { AUTO_COMPACT_PRE_COMPACT_RATIO, AUTO_COMPACT_THRESHOLD_RATIO } from '../context/auto-compact-types.js';
 import { describeMode, thresholdFor } from './auto-compact-modes.js';
 import { read24hState } from '../24h-mode/store.js';
@@ -525,9 +526,11 @@ export async function runAutoCompact(input) {
     const mode = input.mode ?? resolveAutoCompactMode(input.projectRoot, sessionId);
     // Lazy import to avoid the AC-1 module depending on the orchestrator.
     const { readContextPercent } = await import('../context/auto-compact-reader.js');
+    const outerSessionId = resolveOuterSessionId(input.projectRoot, sessionId, input.env ?? process.env);
     const probe = readContextPercent({
         projectRoot: input.projectRoot,
         sessionId,
+        outerSessionId,
         env: input.env
     });
     const decision = evaluateAutoCompactDecision({

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

@@ -1,14 +1,50 @@
+/**
+ * AC-1 — auto context-percent probe.
+ *
+ * Reads the current AI CLI context-fill ratio without requiring the
+ * LLM to pass `--prompt-size <bytes>` manually. Strategy: ask the
+ * registered `IdeAdapter.compact` profile which env-var to read and,
+ * when that misses, ask the adapter for a vendor-specific fallback —
+ * no hard-coded IDE names. Per-adapter:
+ *
+ *   - claude-code: its adapter-declared env-var (MVP) + a
+ *     `readContextPercentFallback` that polls the statusline /
+ *     transcript (see claude-code-adapter.ts).
+ *   - trae / codex / cursor / qoder / tongyi-lingma / hermes /
+ *     openclaw / zcode: each adapter fills its own env-var; until
+ *     L2-dogfood verifies each surface, adapters may omit `compact`
+ *     and the probe returns `source: 'conservative-fallback'`.
+ *
+ * Resolution order (user-overridden → env-var → adapter fallback →
+ * conservative-fallback):
+ *   1. `promptSizeBytes` (P0 `--prompt-size <bytes>` escape hatch) →
+ *      `source: 'user-overridden'`.
+ *   2. `adapter.compact.envVarForContextPercent` env-var →
+ *      `source: '<ideId>-env'`.
+ *   3. `adapter.compact.readContextPercentFallback?.(input)` — the
+ *      adapter owns any vendor-specific statusline / transcript probe.
+ *   4. `ratio: 0` with `source: 'conservative-fallback'` — the
+ *      orchestrator MUST NOT auto-fire compact on this signal.
+ */
 import type { ContextPercentProbe } from './auto-compact-types.js';
 export interface ReadContextPercentInput {
     readonly projectRoot: string;
     readonly sessionId: string;
+    /**
+     * Outer (harness / IDE) session id — the id the IDE uses to name its
+     * transcript / session files. Resolved by the caller (env signal → bound
+     * session meta) and passed through to the adapter's
+     * `readContextPercentFallback`. Optional: when unresolved, the adapter
+     * fallback returns null → conservative-fallback.
+     */
+    readonly outerSessionId?: string | undefined;
     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
+     * Mac escape hatch — some IDEs (e.g. Claude Code on macOS) do NOT
+     * inject their context-percent env-var into PreToolUse sub-shells, so the
      * user (or a hook wrapper) can inject the bytes they observed themselves.
      * Priority P0 — above everything else.
      */
@@ -21,60 +57,20 @@ export interface ReadContextPercentInput {
  * so the function itself has no hard-coded IDE names.
  */
 declare function readEnvPercent(env: NodeJS.ProcessEnv, varName: string): number | null;
-/**
- * Read the IDE-specific statusline state. MVP path is Claude Code's
- * `~/.claude/statusline-state.json`; other IDEs are intentionally
- * left for future slices (each IDE will expose its own
- * `compact.postCompactDetectCommand` to drive this).
- */
-declare function readClaudeStatuslinePercent(): number | null;
-/**
- * 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 `'transcript-estimate'` (v2.14.0) so callers
- * know it is a real signal, NOT a hard gate.
- */
-declare function readClaudeTranscriptFallback(sessionId: string): {
-    ratio: number;
-    bytes: number;
-} | null;
 /**
  * Probe the current AI CLI's context-fill ratio. Adapter-driven:
  * looks up the registered `IdeAdapter.compact` profile via
- * `getIdeAdapter(detectIdeFromEnv(env))` and reads the
- * adapter-declared env-var. Falls back to statusline poll +
- * transcript estimate ONLY for adapters that opt in
- * (`adapter.id === 'claude-code'` for the MVP); other adapters
- * without an env-var hit return `source: 'conservative-fallback'`
- * with `ratio: 0` so the orchestrator never auto-fires on a
- * missing signal.
+ * `getAdapter(detectIdeFromEnv(env))` and reads the
+ * adapter-declared env-var. When that misses, delegates to the
+ * adapter's optional `readContextPercentFallback` (which owns any
+ * vendor-specific statusline / transcript probe). Adapters without a
+ * fallback (or a fallback that returns null) yield
+ * `source: 'conservative-fallback'` with `ratio: 0` so the
+ * orchestrator never auto-fires on a missing signal.
  */
 export declare function readContextPercent(input: ReadContextPercentInput): ContextPercentProbe;
 /** Re-export the env-var probe for unit tests. */
 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

@@ -1,30 +1,3 @@
-/**
- * AC-1 — auto context-percent probe.
- *
- * Reads the current AI CLI context-fill ratio without requiring the
- * LLM to pass `--prompt-size <bytes>` manually. Strategy: ask the
- * registered `IdeAdapter.compact` profile which env-var to read;
- * no hard-coded IDE names. Per-adapter:
- *
- *   - claude-code: `CLAUDE_CONTEXT_USAGE_PERCENT` (MVP)
- *   - trae / codex / cursor / qoder / tongyi-lingma / hermes /
- *     openclaw: each adapter fills its own env-var; until L2-dogfood
- *     verifies each surface, adapters may omit `compact` and the
- *     probe returns `source: 'conservative-fallback'`.
- *
- * Fallback chain (when adapter.compact is undefined OR the env-var
- * is missing):
- *   1. statusline poll (`~/.claude/statusline-state.json` for
- *      Claude Code MVP; other IDEs register their own poll path
- *      by exposing `compact.postCompactDetectCommand`).
- *   2. Conservative transcript-size estimate
- *      (`~/.claude/projects/<hash>/<sid>.jsonl` for Claude Code).
- *   3. `ratio: 0` with `source: 'conservative-fallback'` — the
- *      orchestrator MUST NOT auto-fire compact on this signal.
- */
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
 import { detectIdeFromEnv } from './ide-detect.js';
 import { getAdapter } from '../ide/ide-registry.js';
 /**
@@ -44,106 +17,16 @@ function readEnvPercent(env, varName) {
         return null;
     return Math.max(0, Math.min(1, parsed));
 }
-/**
- * Read the IDE-specific statusline state. MVP path is Claude Code's
- * `~/.claude/statusline-state.json`; other IDEs are intentionally
- * left for future slices (each IDE will expose its own
- * `compact.postCompactDetectCommand` to drive this).
- */
-function readClaudeStatuslinePercent() {
-    const path = join(homedir(), '.claude', 'statusline-state.json');
-    if (!existsSync(path))
-        return null;
-    try {
-        const json = JSON.parse(readFileSync(path, 'utf8'));
-        const candidates = ['contextPercent', 'context_usage_percent', 'contextPercentUsed'];
-        for (const key of candidates) {
-            const raw = json[key];
-            if (typeof raw === 'number' && Number.isFinite(raw)) {
-                return raw > 1.5 ? raw / 100 : Math.max(0, Math.min(1, raw));
-            }
-        }
-    }
-    catch (err) { // TODO(g2): legacy silent catch — now narrows to IO errors only (grace: 1 minor release, v2.14.0)
-        if (err instanceof ReferenceError)
-            throw err; // surface module-load bugs
-        if (err instanceof SyntaxError)
-            throw err; // surface parse bugs (e.g. broken statusline JSON)
-        return null; // only swallow IO errors
-    }
-    return null;
-}
-/**
- * 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 findTranscriptJsonl(projectsDir, sessionId) {
-    if (!existsSync(projectsDir))
-        return null;
-    try {
-        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 };
-                }
-            }
-        }
-    }
-    catch (err) { // TODO(g2): legacy silent catch — now narrows to IO errors only (grace: 1 minor release, v2.14.0)
-        if (err instanceof ReferenceError)
-            throw err; // surface module-load bugs
-        if (err instanceof SyntaxError)
-            throw err; // surface parse bugs
-        return null; // only swallow IO errors
-    }
-    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
- * `getIdeAdapter(detectIdeFromEnv(env))` and reads the
- * adapter-declared env-var. Falls back to statusline poll +
- * transcript estimate ONLY for adapters that opt in
- * (`adapter.id === 'claude-code'` for the MVP); other adapters
- * without an env-var hit return `source: 'conservative-fallback'`
- * with `ratio: 0` so the orchestrator never auto-fires on a
- * missing signal.
+ * `getAdapter(detectIdeFromEnv(env))` and reads the
+ * adapter-declared env-var. When that misses, delegates to the
+ * adapter's optional `readContextPercentFallback` (which owns any
+ * vendor-specific statusline / transcript probe). Adapters without a
+ * fallback (or a fallback that returns null) yield
+ * `source: 'conservative-fallback'` with `ratio: 0` so the
+ * orchestrator never auto-fires on a missing signal.
  */
 export function readContextPercent(input) {
     const env = input.env ?? process.env;
@@ -158,7 +41,7 @@ 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.
+    // P0 user-overridden takes priority over env / fallback / 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
@@ -176,8 +59,8 @@ export function readContextPercent(input) {
             capturedAt
         };
     }
-    // Primary: read the adapter-declared env-var (no hard-coded IDE names).
     if (adapter.compact) {
+        // Primary: read the adapter-declared env-var (no hard-coded IDE names).
         const primary = readEnvPercent(env, adapter.compact.envVarForContextPercent);
         if (primary !== null) {
             return {
@@ -188,27 +71,17 @@ export function readContextPercent(input) {
                 capturedAt
             };
         }
-    }
-    // MVP-only fallback chain: statusline poll + transcript estimate.
-    // Non-MVP adapters that don't fill `compact` skip this and return
-    // a conservative-zero probe (the orchestrator will stay in
-    // 'none' / 'soft-warn' zone and never auto-fire compact).
-    if (ideId === 'claude-code') {
-        const statusline = readClaudeStatuslinePercent();
-        if (statusline !== null) {
-            return { ratio: statusline, source: 'statusline-poll', capacityBytes, ide: ideId, capturedAt };
-        }
-        const fallback = readClaudeTranscriptFallback(input.sessionId);
-        if (fallback !== null) {
-            return {
-                ratio: fallback.ratio,
-                source: 'transcript-estimate',
-                rawBytes: fallback.bytes,
-                capacityBytes,
-                ide: ideId,
-                capturedAt
-            };
-        }
+        // Fallback: the adapter owns any vendor-specific statusline /
+        // transcript probe. When it returns a probe, honor it; otherwise
+        // fall through to conservative-fallback.
+        const fallback = adapter.compact.readContextPercentFallback?.({
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            outerSessionId: input.outerSessionId,
+            env
+        });
+        if (fallback)
+            return fallback;
     }
     // No signal available — return `ratio: 0` so the orchestrator
     // stays in `none` zone and the LLM can still pass `--prompt-size`
@@ -216,4 +89,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, findTranscriptJsonl };
+export const _internal = { readEnvPercent };

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

@@ -161,8 +161,10 @@ export interface ContextPercentProbe {
      *   - `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)
+     *                                contextTokens / contextWindowTokens
+     *                                from the LATEST message.usage entry —
+     *                                token-based + model-aware; 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
@@ -171,6 +173,19 @@ export interface ContextPercentProbe {
     readonly source: string;
     readonly rawBytes?: number;
     readonly capacityBytes?: number;
+    /**
+     * Token-based numerator for `transcript-estimate`: the observed
+     * `input_tokens + cache_read_input_tokens + cache_creation_input_tokens`
+     * from the LATEST transcript `message.usage` entry. Undefined for byte /
+     * percent sources (`user-overridden`, `${ideId}-env`, `statusline-poll`).
+     */
+    readonly rawTokens?: number;
+    /**
+     * Token-based denominator for `transcript-estimate`: the model's context
+     * window in tokens (`modelContextWindowTokens`). Undefined for byte /
+     * percent sources.
+     */
+    readonly capacityTokens?: number;
     readonly ide: string;
     readonly capturedAt: string;
 }

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

@@ -1,18 +1,18 @@
 import type { IdeAdapter } from '../ide-types.js';
 /**
- * Claude Code adapter —— peaks-loop 的"起源 IDE"。
+ * Model-aware context-window size in tokens.
  *
- * 该 adapter 从原 `src/services/skills/hooks-settings-service.ts` 提取,保持
- * 字节级兼容:用户在 Claude Code 环境下跑 `peaks hooks install` 产出的
- * `.claude/settings.json` 与 refactor 前逐字节相同。
+ * Detection rule (documented):
+ *   1. Empty / unknown model → DEFAULT_CONTEXT_WINDOW_TOKENS (200_000).
+ *   2. Suffix heuristic — a model id containing `1m` (case-insensitive) is
+ *      treated as 1M-context.
+ *   3. Explicit allowlist — known 1M Claude model ids
+ *      (ONE_MILLION_CONTEXT_MODELS).
+ *   4. Everything else → 200_000 (the safe default).
  *
- * 字段解释(见 PRD AC-1):
- *   - dirName = '.claude'           : Claude Code 项目根下的 settings 目录
- *   - settingsFileName = 'settings.json'
- *   - envVar = 'CLAUDE_PROJECT_DIR' : Claude Code 注入的 env 变量,用于 ${...} 占位
- *   - hookEvent = 'PreToolUse'      : Claude Code hook 数组 key
- *   - toolMatcher = 'Bash' | 'Task' : PreToolUse 数组元素的 matcher 字段
- *
- * 不可消除的 per-IDE 字段(见 tech-doc.md §1.3)。
+ * Callers MAY additionally infer ≥1M from the observed token count: if
+ * `contextTokens > DEFAULT_CONTEXT_WINDOW_TOKENS`, the model cannot be a
+ * 200K model and must be ≥1M (see `readClaudeTranscriptEstimate`).
  */
+export declare function modelContextWindowTokens(model: string): number;
 export declare const CLAUDE_CODE_ADAPTER: IdeAdapter;

package/dist/services/ide/adapters/claude-code-adapter.js

@@ -1,3 +1,4 @@
+import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { claudeCodeSubAgentDispatcher } from '../../dispatch/sub-agent-dispatcher.js';
@@ -17,6 +18,293 @@ import { claudeCodeSubAgentDispatcher } from '../../dispatch/sub-agent-dispatche
  *
  * 不可消除的 per-IDE 字段(见 tech-doc.md §1.3)。
  */
+/**
+ * Read Claude Code's statusline state file
+ * (`~/.claude/statusline-state.json`) and parse a context-percent key.
+ * Moved from the generic reader in slice
+ * 2026-09-02-vendor-neutral-context-probe — Claude-specific paths now live
+ * only in the Claude Code adapter.
+ */
+function readClaudeStatuslinePercent() {
+    const path = join(homedir(), '.claude', 'statusline-state.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        const json = JSON.parse(readFileSync(path, 'utf8'));
+        const candidates = ['contextPercent', 'context_usage_percent', 'contextPercentUsed'];
+        for (const key of candidates) {
+            const raw = json[key];
+            if (typeof raw === 'number' && Number.isFinite(raw)) {
+                return raw > 1.5 ? raw / 100 : Math.max(0, Math.min(1, raw));
+            }
+        }
+    }
+    catch (err) { // TODO(g2): legacy silent catch — now narrows to IO errors only (grace: 1 minor release, v2.14.0)
+        if (err instanceof ReferenceError)
+            throw err; // surface module-load bugs
+        if (err instanceof SyntaxError)
+            throw err; // surface parse bugs (e.g. broken statusline JSON)
+        return null; // only swallow IO errors
+    }
+    return null;
+}
+/**
+ * Recursive search for `<outerSessionId>.jsonl` under `projectsDir`. 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 this recursion closes.
+ *
+ * Moved from the generic reader in slice
+ * 2026-09-02-vendor-neutral-context-probe. The lookup key is the OUTER
+ * session id (Claude Code names its transcript by the outer session UUID),
+ * NOT the peaks session id.
+ */
+function findTranscriptJsonl(projectsDir, outerSessionId) {
+    if (!existsSync(projectsDir))
+        return null;
+    try {
+        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 === `${outerSessionId}.jsonl`) {
+                    return full;
+                }
+            }
+        }
+    }
+    catch (err) { // TODO(g2): legacy silent catch — now narrows to IO errors only (grace: 1 minor release, v2.14.0)
+        if (err instanceof ReferenceError)
+            throw err; // surface module-load bugs
+        if (err instanceof SyntaxError)
+            throw err; // surface parse bugs
+        return null; // only swallow IO errors
+    }
+    return null;
+}
+/** 1M-context window size in tokens (documented single choice: 1,000,000). */
+const ONE_MILLION_CONTEXT_TOKENS = 1_000_000;
+/** Safe-default (non-1M) context window size in tokens. */
+const DEFAULT_CONTEXT_WINDOW_TOKENS = 200_000;
+/** Reverse-scan chunk size in bytes (keeps memory bounded on multi-MB transcripts). */
+const TRANSCRIPT_SCAN_CHUNK_BYTES = 64 * 1024;
+/**
+ * Known 1M-context Claude model id prefixes whose ids do NOT carry a `1m`
+ * suffix (e.g. `claude-sonnet-4-5-20250929`). The substring match is
+ * intentionally generous — every `claude-sonnet-4*` / `claude-opus-4*`
+ * variant is 1M-context.
+ */
+const ONE_MILLION_CONTEXT_MODELS = ['claude-opus-4', 'claude-sonnet-4'];
+/**
+ * Model-aware context-window size in tokens.
+ *
+ * Detection rule (documented):
+ *   1. Empty / unknown model → DEFAULT_CONTEXT_WINDOW_TOKENS (200_000).
+ *   2. Suffix heuristic — a model id containing `1m` (case-insensitive) is
+ *      treated as 1M-context.
+ *   3. Explicit allowlist — known 1M Claude model ids
+ *      (ONE_MILLION_CONTEXT_MODELS).
+ *   4. Everything else → 200_000 (the safe default).
+ *
+ * Callers MAY additionally infer ≥1M from the observed token count: if
+ * `contextTokens > DEFAULT_CONTEXT_WINDOW_TOKENS`, the model cannot be a
+ * 200K model and must be ≥1M (see `readClaudeTranscriptEstimate`).
+ */
+export function modelContextWindowTokens(model) {
+    const m = model.trim().toLowerCase();
+    if (m.length === 0)
+        return DEFAULT_CONTEXT_WINDOW_TOKENS;
+    if (m.includes('1m'))
+        return ONE_MILLION_CONTEXT_TOKENS;
+    for (const known of ONE_MILLION_CONTEXT_MODELS) {
+        if (m.includes(known))
+            return ONE_MILLION_CONTEXT_TOKENS;
+    }
+    return DEFAULT_CONTEXT_WINDOW_TOKENS;
+}
+/** A non-negative finite number, or null when the value is not numeric. */
+function numericTokenCount(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+        return value;
+    return null;
+}
+/**
+ * Parse a single jsonl line into its token count + model id. Returns null
+ * when the line has no `message.usage` object with numeric token fields.
+ */
+function parseTranscriptUsageLine(line) {
+    if (line.length === 0)
+        return null;
+    let json;
+    try {
+        json = JSON.parse(line);
+    }
+    catch {
+        return null; // non-JSON line (blank / corrupt) — skip
+    }
+    if (typeof json !== 'object' || json === null)
+        return null;
+    const record = json;
+    const message = record.message;
+    if (typeof message !== 'object' || message === null)
+        return null;
+    const msg = message;
+    const usage = msg.usage;
+    if (typeof usage !== 'object' || usage === null)
+        return null;
+    const u = usage;
+    const inputTokens = numericTokenCount(u.input_tokens);
+    const cacheRead = numericTokenCount(u.cache_read_input_tokens);
+    const cacheCreation = numericTokenCount(u.cache_creation_input_tokens);
+    if (inputTokens === null && cacheRead === null && cacheCreation === null)
+        return null;
+    const contextTokens = (inputTokens ?? 0) + (cacheRead ?? 0) + (cacheCreation ?? 0);
+    // Model id lives at `message.model`, falling back to a top-level `model`.
+    const model = typeof msg.model === 'string'
+        ? msg.model
+        : typeof record.model === 'string' ? record.model : '';
+    return { contextTokens, model };
+}
+/**
+ * Reverse-scan the transcript jsonl (from the END) for the LATEST entry that
+ * carries a numeric `message.usage`. The file can be many MB; it is read in
+ * backward chunks of TRANSCRIPT_SCAN_CHUNK_BYTES — never fully into memory —
+ * and stops at the first (newest) usable entry.
+ */
+function findLatestTranscriptUsage(filePath) {
+    let fd = null;
+    try {
+        const size = statSync(filePath).size;
+        if (size === 0)
+            return null;
+        fd = openSync(filePath, 'r');
+        let position = size;
+        let carry = ''; // partial line head carried into the next (older) chunk
+        while (position > 0) {
+            const readLen = Math.min(TRANSCRIPT_SCAN_CHUNK_BYTES, position);
+            position -= readLen;
+            const buf = Buffer.alloc(readLen);
+            const bytesRead = readSync(fd, buf, 0, readLen, position);
+            if (bytesRead <= 0)
+                break;
+            const lines = (buf.toString('utf8', 0, bytesRead) + carry).split('\n');
+            carry = lines[0] ?? '';
+            for (let i = lines.length - 1; i >= 1; i--) {
+                const line = lines[i];
+                if (line === undefined)
+                    continue;
+                const parsed = parseTranscriptUsageLine(line);
+                if (parsed !== null)
+                    return parsed;
+            }
+        }
+        // The final carry is the first line of the file (complete, since it starts at byte 0).
+        if (carry.length > 0) {
+            const parsed = parseTranscriptUsageLine(carry);
+            if (parsed !== null)
+                return parsed;
+        }
+        return null;
+    }
+    catch (err) {
+        // Narrow: surface module-load / parse bugs, swallow IO errors only
+        // (mirrors the other adapter read helpers' catch discipline).
+        if (err instanceof ReferenceError)
+            throw err;
+        if (err instanceof SyntaxError)
+            throw err;
+        return null;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+}
+/**
+ * Resolve the context window for a transcript usage entry. Prefers the
+ * explicit `modelContextWindowTokens(model)` mapping; when the observed token
+ * count contradicts it (tokens exceed the mapped window), the model must be
+ * ≥1M, so bump to the 1M window.
+ */
+function resolveContextWindowTokens(model, contextTokens) {
+    const window = modelContextWindowTokens(model);
+    return contextTokens > window ? ONE_MILLION_CONTEXT_TOKENS : window;
+}
+/**
+ * Conservative transcript-estimate fallback. Recursively searches
+ * `~/.claude/projects/<hash>/<outerSessionId-or-nested>.jsonl` (Mac may nest
+ * the jsonl under an extra directory we cannot predict ahead of time) and
+ * estimates `ratio = contextTokens / contextWindowTokens` from the LATEST
+ * `message.usage` entry — token-based + model-aware, NOT the old
+ * `bytes / 256KB` (which over-fired because the transcript grows unboundedly).
+ * Tagged `'transcript-estimate'` (v2.14.0) so callers know it is a real
+ * signal, NOT a hard gate.
+ */
+function readClaudeTranscriptEstimate(outerSessionId) {
+    const projectsDir = join(homedir(), '.claude', 'projects');
+    const path = findTranscriptJsonl(projectsDir, outerSessionId);
+    if (path === null)
+        return null;
+    const latest = findLatestTranscriptUsage(path);
+    if (latest === null)
+        return null;
+    const contextWindowTokens = resolveContextWindowTokens(latest.model, latest.contextTokens);
+    const ratio = Math.min(1, latest.contextTokens / contextWindowTokens);
+    return { ratio, contextTokens: latest.contextTokens, contextWindowTokens };
+}
+/**
+ * Claude Code's vendor-specific context-percent fallback, exposed as
+ * `IdeCompactProfile.readContextPercentFallback`. The generic reader calls
+ * this only when the primary env-var probe misses; only the adapter knows the
+ * Claude-specific statusline + transcript paths. Resolution order:
+ *   1. statusline poll (`~/.claude/statusline-state.json`)
+ *   2. transcript estimate — looks up `<outerSessionId>.jsonl` under
+ *      `~/.claude/projects/<hash>/...` using the OUTER session id (Claude
+ *      names its transcript by the outer session UUID, not the peaks sid),
+ *      and estimates `contextTokens / contextWindowTokens` from the LATEST
+ *      `message.usage` entry (token-based + model-aware).
+ * Returns `null` when neither yields a signal → the reader emits
+ * `conservative-fallback`.
+ */
+function readContextPercentFallback(input) {
+    const capturedAt = new Date().toISOString();
+    // Byte-based capacity is carried only for the percent path (statusline-poll
+    // returns a 0..1 ratio; capacityBytes is metadata there). The
+    // transcript-estimate path is token-based and surfaces `capacityTokens`
+    // (the model window) instead — see readClaudeTranscriptEstimate.
+    const capacityBytes = 256 * 1024;
+    const ide = 'claude-code';
+    const statusline = readClaudeStatuslinePercent();
+    if (statusline !== null) {
+        return { ratio: statusline, source: 'statusline-poll', capacityBytes, ide, capturedAt };
+    }
+    if (typeof input.outerSessionId === 'string' && input.outerSessionId.length > 0) {
+        const estimate = readClaudeTranscriptEstimate(input.outerSessionId);
+        if (estimate !== null) {
+            return {
+                ratio: estimate.ratio,
+                source: 'transcript-estimate',
+                rawTokens: estimate.contextTokens,
+                capacityTokens: estimate.contextWindowTokens,
+                ide,
+                capturedAt
+            };
+        }
+    }
+    return null;
+}
 export const CLAUDE_CODE_ADAPTER = {
     id: 'claude-code',
     displayName: 'Claude Code',
@@ -71,7 +359,8 @@ export const CLAUDE_CODE_ADAPTER = {
         envVarForContextPercent: 'CLAUDE_CONTEXT_USAGE_PERCENT',
         compactCommand: 'claude --compact',
         compactPathway: 'ide-native',
-        postCompactDetectCommand: 'peaks compact auto --json'
+        postCompactDetectCommand: 'peaks compact auto --json',
+        readContextPercentFallback
     },
     // Slice #011: standards profile. Claude Code reads its constitution at
     // CLAUDE.md + module-level rules under .claude/rules/**. The values mirror

package/dist/services/ide/ide-types.d.ts

@@ -12,6 +12,7 @@
  * 其他全部归一化到 peaks 内部模型(见 hook-protocol.ts)。
  */
 import type { SubAgentDispatcher } from '../dispatch/sub-agent-dispatcher.js';
+import type { ContextPercentProbe } from '../context/auto-compact-types.js';
 export type IdeId = 'claude-code' | 'trae' | 'codex' | 'cursor' | 'qoder' | 'tongyi-lingma' | 'hermes' | 'openclaw' | 'zcode';
 export interface IdeCapabilities {
     /** peaks gate enforce 是否适用该 IDE(必备) */
@@ -200,6 +201,44 @@ export interface IdeCompactProfile {
      * the orchestrator polls `envVarForContextPercent` directly.
      */
     readonly postCompactDetectCommand?: string;
+    /**
+     * Optional vendor-specific fallback the generic `readContextPercent`
+     * reader calls when the primary env-var probe misses. Returns a
+     * completed `ContextPercentProbe` (e.g. `statusline-poll` /
+     * `transcript-estimate`) or `null` when the adapter has no signal —
+     * the reader then falls through to `conservative-fallback`.
+     *
+     * Keeps IDE-specific filesystem / env knowledge (Claude Code's
+     * `~/.claude/statusline-state.json` + `~/.claude/projects` transcript
+     * layout, etc.) inside the adapter, not the generic reader. Adapters
+     * that do not opt in simply omit the field; new IDEs are addable
+     * without touching the generic reader.
+     *
+     * Added in slice 2026-09-02-vendor-neutral-context-probe.
+     */
+    readonly readContextPercentFallback?: (input: ContextPercentFallbackInput) => ContextPercentProbe | null;
+}
+/**
+ * Input the generic `readContextPercent` reader passes to an adapter's
+ * optional `IdeCompactProfile.readContextPercentFallback` hook. The adapter
+ * owns the vendor-specific fallback logic (statusline poll, transcript
+ * lookup, etc.); the generic reader stays IDE-agnostic.
+ *
+ * Added in slice 2026-09-02-vendor-neutral-context-probe.
+ */
+export interface ContextPercentFallbackInput {
+    /** Project root (the probe's `--project` anchor). */
+    readonly projectRoot: string;
+    /** Peaks session id (NOT the harness / IDE transcript id). */
+    readonly sessionId: string;
+    /**
+     * Outer (harness / IDE) session id — the id the IDE uses to name its
+     * transcript / session files (e.g. a UUID). Optional: when unresolved,
+     * adapters whose fallback depends on it should return `null`.
+     */
+    readonly outerSessionId?: string | undefined;
+    /** Injectable env (defaults to process.env in the reader). */
+    readonly env?: NodeJS.ProcessEnv | undefined;
 }
 /**
  * Per-IDE standards-file location + format profile. Used by the

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

@@ -38,6 +38,17 @@ export type BindingStatusView = {
  * helper that does no filesystem writes; safe to call from any test.
  */
 export declare function loadBindingStatus(projectRoot: string): BindingStatusView;
+export declare function readOuterSessionId(): string;
+/**
+ * Resolve the outer (harness / IDE) session id for the auto-compact
+ * context-percent probe. Order: env signal first (PEAKS_OUTER_SESSION_ID /
+ * CLAUDE_CODE_SESSION_ID), then the bound peaks session's recorded
+ * `outerSessionId` (`session.json` meta). Returns `undefined` when neither is
+ * available — the caller passes `undefined` through and the adapter's fallback
+ * returns null → conservative-fallback. Vendor-neutral: this helper has no
+ * IDE-specific naming; the env-var read lives alongside the binding layer.
+ */
+export declare function resolveOuterSessionId(projectRoot: string, sessionId: string, env?: NodeJS.ProcessEnv): string | undefined;
 /**
  * Render the binding as a pipeable ASCII table. The columns are fixed
  * (no truncation, no wrapping) so a downstream `awk` / `cut` pipeline

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

@@ -22,6 +22,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { readBinding } from './binding-store.js';
+import { getSessionMeta } from './session-manager.js';
 /**
  * Read the binding from disk and assemble the read-only view. Pure
  * helper that does no filesystem writes; safe to call from any test.
@@ -37,14 +38,34 @@ export function loadBindingStatus(projectRoot) {
         : !Object.values(binding.instances).some((inst) => inst.callerId.startsWith(outerSessionId));
     return { binding, source, projectRoot, stale, outerSessionId };
 }
-function readOuterSessionId() {
-    const peaks = process.env.PEAKS_OUTER_SESSION_ID;
+export function readOuterSessionId() {
+    return readOuterSessionIdFromEnv(process.env) ?? 'unknown';
+}
+/** Pure env read (no process.env dependency) so callers can inject an env. */
+function readOuterSessionIdFromEnv(env) {
+    const peaks = env.PEAKS_OUTER_SESSION_ID;
     if (typeof peaks === 'string' && peaks.length > 0)
         return peaks;
-    const claude = process.env.CLAUDE_CODE_SESSION_ID;
+    const claude = env.CLAUDE_CODE_SESSION_ID;
     if (typeof claude === 'string' && claude.length > 0)
         return claude;
-    return 'unknown';
+    return undefined;
+}
+/**
+ * Resolve the outer (harness / IDE) session id for the auto-compact
+ * context-percent probe. Order: env signal first (PEAKS_OUTER_SESSION_ID /
+ * CLAUDE_CODE_SESSION_ID), then the bound peaks session's recorded
+ * `outerSessionId` (`session.json` meta). Returns `undefined` when neither is
+ * available — the caller passes `undefined` through and the adapter's fallback
+ * returns null → conservative-fallback. Vendor-neutral: this helper has no
+ * IDE-specific naming; the env-var read lives alongside the binding layer.
+ */
+export function resolveOuterSessionId(projectRoot, sessionId, env = process.env) {
+    const envOuter = readOuterSessionIdFromEnv(env);
+    if (envOuter !== undefined)
+        return envOuter;
+    const recorded = getSessionMeta(projectRoot, sessionId)?.outerSessionId;
+    return typeof recorded === 'string' && recorded.length > 0 ? recorded : undefined;
 }
 /**
  * Render the binding as a pipeable ASCII table. The columns are fixed

package/dist/services/skill/skill-search-service.d.ts

@@ -32,9 +32,9 @@ export declare const SkillSearchInputSchema: z.ZodObject<{
         status: "status";
         resume: "resume";
         audit: "audit";
+        ide: "ide";
         content: "content";
         test: "test";
-        ide: "ide";
         research: "research";
         doctor: "doctor";
         triage: "triage";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.26",
+  "version": "4.0.27",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -101,10 +101,10 @@
     "fzf": "^0.5.2",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.11",
-    "peaks-loop-shared": "0.0.60",
-    "peaks-loop-shared-channel": "0.0.28",
-    "peaks-loop-mut": "0.1.24"
+    "peaks-loop-mut": "0.1.25",
+    "peaks-loop-internal-runtime": "0.0.12",
+    "peaks-loop-shared": "0.0.61",
+    "peaks-loop-shared-channel": "0.0.29"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",