peaks-loop 4.0.26 → 4.0.28

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/doctor/doctor-service/checks/codegraph-capability.d.ts

@@ -6,12 +6,11 @@
  * Fails when the version drifts, when the binary is missing, or
  * when the package is not resolvable at all.
  *
- * Slice rid-CG-003 (spike follow-up #3): also detects which managed
- * codegraph directory is in use — `.peaks/.codegraph/` (preferred)
- * or root `.codegraph/` (legacy) — via the injected `managedPathProbe`.
+ * The check also reports the managed codegraph data directory in use —
+ * always the root `.codegraph/` — via the injected `managedPathProbe`.
  * The CG-007 yarn-pnp fallback is preserved as the package-resolution
- * default; the managed-path probe defaults to the same fs-walk-style
- * helper and is independently injectable for tests.
+ * default; the managed-path probe defaults to the same root-only
+ * resolver and is independently injectable for tests.
  *
  * The probe is injected so tests do not depend on the real
  * `node_modules` resolution; the default probe uses

package/dist/services/doctor/doctor-service/checks/codegraph-capability.js

@@ -6,12 +6,11 @@
  * Fails when the version drifts, when the binary is missing, or
  * when the package is not resolvable at all.
  *
- * Slice rid-CG-003 (spike follow-up #3): also detects which managed
- * codegraph directory is in use — `.peaks/.codegraph/` (preferred)
- * or root `.codegraph/` (legacy) — via the injected `managedPathProbe`.
+ * The check also reports the managed codegraph data directory in use —
+ * always the root `.codegraph/` — via the injected `managedPathProbe`.
  * The CG-007 yarn-pnp fallback is preserved as the package-resolution
- * default; the managed-path probe defaults to the same fs-walk-style
- * helper and is independently injectable for tests.
+ * default; the managed-path probe defaults to the same root-only
+ * resolver and is independently injectable for tests.
  *
  * The probe is injected so tests do not depend on the real
  * `node_modules` resolution; the default probe uses
@@ -100,45 +99,30 @@ function defaultCodegraphProbe() {
         version,
         binaryPath,
         binaryExists,
-        // Slice rid-CG-003 — resolve the managed codegraph directory
-        // relative to the cwd the doctor itself was invoked from.
-        // Best-effort: when the operator ran `peaks doctor` outside a
-        // project (cwd has neither `.peaks/.codegraph/` nor
-        // `.codegraph/`) we still report `fresh-preferred` so the check
-        // message names the canonical future location.
+        // Resolve the managed codegraph directory relative to the cwd the
+        // doctor itself was invoked from. Root-only: always names
+        // `<cwd>/.codegraph/`.
         managedPath: detectManagedCodegraphPath(process.cwd())
     };
     return result;
 }
 /**
- * Slice rid-CG-003 — pure wrapper over `resolveCodegraphProjectRoot`
- * that returns a probe-shaped managed-path payload (or null when
- * the cwd does not look like a peaks project root).
+ * Pure wrapper over `resolveCodegraphProjectRoot` that returns a
+ * probe-shaped managed-path payload for the root `.codegraph/`.
  */
 function detectManagedCodegraphPath(cwd) {
-    try {
-        const location = resolveCodegraphProjectRoot(cwd);
-        return {
-            source: location.source,
-            codegraphDir: location.codegraphDir,
-            cwd: location.cwd
-        };
-    }
-    catch {
-        return null;
-    }
+    const location = resolveCodegraphProjectRoot(cwd);
+    return {
+        source: location.source,
+        codegraphDir: location.codegraphDir,
+        cwd: location.cwd
+    };
 }
 function renderManagedPathSuffix(managedPath) {
     if (!managedPath) {
         return '';
     }
-    if (managedPath.source === 'preferred') {
-        return `; managed path: ${managedPath.codegraphDir} (preferred .peaks/.codegraph/)`;
-    }
-    if (managedPath.source === 'legacy') {
-        return `; managed path: ${managedPath.codegraphDir} (legacy root .codegraph/ — consider moving to .peaks/.codegraph/)`;
-    }
-    return `; managed path: ${managedPath.codegraphDir} (fresh-preferred — no codegraph dir yet; next init will create it)`;
+    return `; managed path: ${managedPath.codegraphDir}`;
 }
 function runCheck(probe, managedPathProbe) {
     try {

package/dist/services/doctor/doctor-service/types.d.ts

@@ -57,7 +57,7 @@ export type DoctorReport = {
     };
 };
 export type CodegraphManagedPathInfo = {
-    source: 'preferred' | 'legacy' | 'fresh-preferred';
+    source: 'root';
     codegraphDir: string;
     cwd: string;
 };
@@ -67,14 +67,11 @@ export type CodegraphCapabilityProbe = {
     binaryPath: string;
     binaryExists: boolean;
     /**
-     * Slice rid-CG-003 — preferred-path resolution result. When the
-     * probe can detect `.peaks/.codegraph/` or `.codegraph/` inside
-     * `process.cwd()` it sets `managedPath`; otherwise null (e.g.
-     * when the operator invoked `peaks doctor` outside a project).
-     *
-     * `source: 'preferred'`     — `.peaks/.codegraph/` exists
-     * `source: 'legacy'`        — only `.codegraph/` exists
-     * `source: 'fresh-preferred'` — neither exists; defaults to preferred
+     * Root-only managed-path resolution result. The check resolves the
+     * single codegraph data directory, `<cwd>/.codegraph/`, relative to
+     * the cwd the doctor was invoked from; null only when resolution is
+     * unavailable (e.g. the operator invoked `peaks doctor` outside a
+     * resolvable directory).
      */
     managedPath: CodegraphManagedPathInfo | null;
 };
@@ -207,12 +204,11 @@ export type DoctorOptions = {
     skillsBaseDir?: string;
     codegraphProbe?: () => CodegraphCapabilityProbe;
     /**
-     * Slice rid-CG-003 — optional override for the managed-codegraph
-     * path detection inside the `capability:codegraph` check. When
-     * omitted, the check uses the default fs helper
-     * (`resolveCodegraphProjectRoot(process.cwd())`). Tests inject a
-     * custom probe to drive preferred / legacy / fresh-preferred
-     * outcomes without monkey-patching `process.cwd()`.
+     * Optional override for the managed-codegraph path detection inside
+     * the `capability:codegraph` check. When omitted, the check uses
+     * the default resolver (`resolveCodegraphProjectRoot(process.cwd())`).
+     * Tests inject a custom probe without monkey-patching
+     * `process.cwd()`.
      */
     codegraphManagedPathProbe?: () => CodegraphManagedPathInfo | null;
     skillPresenceProbe?: () => DoctorSkillPresence | null;

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

@@ -1,18 +1,25 @@
 import type { IdeAdapter } from '../ide-types.js';
 /**
- * Claude Code adapter —— peaks-loop 的"起源 IDE"。
- *
- * 该 adapter 从原 `src/services/skills/hooks-settings-service.ts` 提取,保持
- * 字节级兼容:用户在 Claude Code 环境下跑 `peaks hooks install` 产出的
- * `.claude/settings.json` 与 refactor 前逐字节相同。
+ * Resolve the currently-active Claude Code model id from a runtime env map.
+ * Returns the first non-empty `CLAUDE_CODE_MODEL_ENV_VARS` value (trimmed), or
+ * `undefined` when none is present. Pure + exported for tests; the caller falls
+ * back to the transcript `message.model` when this returns undefined.
+ */
+export declare function resolveClaudeModelFromEnv(env: NodeJS.ProcessEnv | undefined): string | undefined;
+/**
+ * Model-aware context-window size in tokens.
  *
- * 字段解释(见 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 字段
+ * 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).
  *
- * 不可消除的 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,346 @@ 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'];
+/**
+ * Claude Code runtime env vars that may carry the currently-active model id,
+ * in documented precedence order (first non-empty value wins):
+ *   1. ANTHROPIC_MODEL                — explicit per-run model override
+ *   2. ANTHROPIC_DEFAULT_OPUS_MODEL   — default Opus fallback
+ *   3. ANTHROPIC_DEFAULT_SONNET_MODEL — default Sonnet fallback
+ *   4. ANTHROPIC_DEFAULT_HAIKU_MODEL  — default Haiku fallback
+ *   5. ANTHROPIC_DEFAULT_FABLE_MODEL  — default Fable fallback
+ *   6. CLAUDE_CODE_SUBAGENT_MODEL     — sub-agent model (used when the others
+ *                                       are absent, e.g. a sub-agent-only env)
+ *
+ * Why env-first: the transcript's `message.model` often drops Claude Code's
+ * `[1M]` / `[200K]` suffix marker (observed: `deepseek-v4-flash`), while the
+ * runtime env vars above carry it (`deepseek-v4-flash[1M]`). Reading them
+ * first lets the window resolver see the true context window. This family is
+ * vendor-specific, so it lives ONLY in the claude-code adapter.
+ */
+const CLAUDE_CODE_MODEL_ENV_VARS = [
+    'ANTHROPIC_MODEL',
+    'ANTHROPIC_DEFAULT_OPUS_MODEL',
+    'ANTHROPIC_DEFAULT_SONNET_MODEL',
+    'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+    'ANTHROPIC_DEFAULT_FABLE_MODEL',
+    'CLAUDE_CODE_SUBAGENT_MODEL',
+];
+/**
+ * Resolve the currently-active Claude Code model id from a runtime env map.
+ * Returns the first non-empty `CLAUDE_CODE_MODEL_ENV_VARS` value (trimmed), or
+ * `undefined` when none is present. Pure + exported for tests; the caller falls
+ * back to the transcript `message.model` when this returns undefined.
+ */
+export function resolveClaudeModelFromEnv(env) {
+    if (!env)
+        return undefined;
+    for (const name of CLAUDE_CODE_MODEL_ENV_VARS) {
+        const value = env[name];
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            if (trimmed.length > 0)
+                return trimmed;
+        }
+    }
+    return undefined;
+}
+/**
+ * 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.
+ *
+ * Window model resolution is env-first: when `envModel` is present, its id
+ * (which Claude Code stamps with the `[1M]` / `[200K]` suffix) drives the
+ * window; otherwise the transcript `message.model` is used.
+ */
+function readClaudeTranscriptEstimate(outerSessionId, envModel) {
+    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 model = envModel !== undefined && envModel.trim().length > 0 ? envModel : latest.model;
+    const contextWindowTokens = resolveContextWindowTokens(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). The window model
+ *      resolves env-first via `resolveClaudeModelFromEnv(input.env)` (which
+ *      carries the `[1M]` suffix the transcript often drops), falling back to
+ *      the transcript `message.model` when env is empty.
+ * 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 envModel = resolveClaudeModelFromEnv(input.env);
+        const estimate = readClaudeTranscriptEstimate(input.outerSessionId, envModel);
+        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 +412,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