peaks-loop 4.0.25 → 4.0.27

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 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**:
+
+- `3d8c911a` refactor(context): remove headroom-ai half-baked integration
+- `2086074b` perf(dispatch): stabilize sub-agent prompt prefix for prompt-cache alignment
+
+**Highlights**:
+
+1. **移除 headroom-ai 半成品集成** — headroom-ai 的 TS SDK 已接但 Python proxy 后端（N-7）从未集成，`--use-headroom` / `--compress-results` 是静默 no-op。删除依赖 + headroom-client/prefs + G7.7 opt-in 路径 + HeadroomPreferences；保留 G7 metadata-only + auto-compact + prompt-cache 对齐作为省 token 主杠杆。通用 DocFetcher 保留为 doc-cache-fetcher.ts。42 文件，+100/−909。
+
+2. **dispatch 前缀稳定化（prompt-cache 对齐）** — 把 LIFECYCLE_RULES 从 prompt 尾部挪到 L1 worktree 块之后，让所有稳定 boilerplate 连续排在最前，最大化 Anthropic prompt-cache 前缀复用（缓存读价约 90% 折扣）。变量块（context % / project memory / task）留在最后。
+
 ## 4.0.25 — 2026-09-01 (codegraph hint fix + post-slice re-index + frontend ACL)
 
 **1 atomic commit from session 2026-09-01-session-fdd7aa** (user feedback batch):

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/core/memory-command.js

@@ -74,10 +74,9 @@ export function registerMemoryCommand(program, io) {
     });
     addJsonOption(memory
         .command('search <query>')
-        .description('Fuzzy-search the memory index (deterministic, local, zero-token). Default --limit 6. Pass --compress-results to also emit a headroom-compressed text view of the matches for LLM-side prompt assembly.')
+        .description('Fuzzy-search the memory index (deterministic, local, zero-token). Default --limit 6.')
         .option('--kind <kind>', 'filter by memory kind (one of: project, rule, decision, reference, feedback, convention, module, lesson)')
         .option('--limit <n>', 'maximum number of matches to return', (value) => Number(value))
-        .option('--compress-results', 'compress joined match text via headroom-ai (uses preferences.headroom.perTouchpoint.memorySearch mode)')
         .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((query, options) => {
         // Lazy import avoids a top-of-file import cycle (memory-commands.ts
         // imports services that the rest of this file may also touch).
@@ -86,7 +85,6 @@ export function registerMemoryCommand(program, io) {
                 query,
                 ...(options.kind !== undefined ? { kind: options.kind } : {}),
                 ...(options.limit !== undefined ? { limit: options.limit } : {}),
-                ...(options.compressResults === true ? { compressResults: true } : {}),
                 ...(options.project !== undefined ? { project: options.project } : {}),
                 ...(options.json !== undefined ? { json: options.json } : {}),
             });

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

@@ -27,15 +27,14 @@ 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 { compressPrompt } from '../../services/context/headroom-client.js';
-import { resolveHeadroomOptions } from '../../services/context/headroom-prefs.js';
 import { playwrightProfilePaths } from '../../services/worktree/playwright-profile.js';
 import { loadPreferences } from '../../services/preferences/preferences-service.js';
 import { DEFAULT_PREFERENCES } from '../../services/preferences/preferences-types.js';
 import { writeLogEntry } from '../../services/log/logger.js';
-import { HEADROOM_MODES, PROMPT_LIMIT_BYTES, RECOMMENDED_ROLES, validateRole } from './sub-agent-shared.js';
+import { PROMPT_LIMIT_BYTES, RECOMMENDED_ROLES, validateRole } from './sub-agent-shared.js';
 import { runDispatchFromDag } from './dispatch-from-dag.js';
 import { TEST_TOOL_DETECTION_BLOCK, formatTestToolDetection } from '../../services/dispatch/test-tool-detection.js';
 import { MemoryPreflightService } from '../../services/context/memory-preflight-service.js';
@@ -46,7 +45,7 @@ export function registerDispatchCommand(parent, io) {
         .command('dispatch')
         .description('Build an IDE-specific tool-call descriptor for a sub-agent dispatch. ' +
         'Dry-run by design; the LLM executes the returned toolCall in its own ' +
-        'environment. Flags: --write-artifact (G7), --use-headroom (G7.7), ' +
+        'environment. Flags: --write-artifact (G7), ' +
         '--force (G9 CLI 兜底). ' +
         'See skills/peaks-code/references/sub-agent-dispatch.md for the ' +
         'orchestrator contract.')
@@ -63,8 +62,6 @@ export function registerDispatchCommand(parent, io) {
         .option('--project <path>', 'target project root (defaults to cwd)')
         .option('--batch-id <uuid>', 'batch id for the dispatch (default: auto-generated UUID)')
         .option('--write-artifact <path>', 'G7: register an artifact file at <path>; CLI computes sha256 + size + writes ArtifactMeta to the dispatch record')
-        .option('--use-headroom', 'G7.7/G9: compress the prompt via headroom-ai before dispatch (opt-in; falls back to G7 metadata-only if headroom unavailable)')
-        .option('--headroom-mode <mode>', `G7.7: headroom mode (${HEADROOM_MODES.join(' | ')}); default balanced`)
         .option('--force', 'G9: override the 80% hard reject threshold at CLI (NOT allowed at hook layer per RL-30 strict)')
         .option('--from-dag <file>', '2.7.0 slice-dag-dispatcher MVP: read a SliceDag JSON file, dispatch one sub-agent per node in topological order; --batch-id overrides the auto-generated batch id (mutually exclusive with <role>)')
         .option('--isolation <mode>', 'slice 2026-07-29-worktree-l2-extended Part 2.C: isolation mode for the sub-agent. Accepts "worktree" (Part 2.C + Part 12 L2 surface), "container" (Part 8 contract + Part 12 L4 docker runtime), or "vm" (Part 25 contract; the VM runtime is a follow-up rid and fail-fasts with ISOLATION_VM_NOT_YET_IMPLEMENTED). Auto-spawns a lease + injects PEAKS_<MODE>_LEASE_ID into the dispatch envelope so the sub-agent can write to the isolated surface without a separate auth grant.')
@@ -351,35 +348,14 @@ export function registerDispatchCommand(parent, io) {
                     return;
                 }
             }
-            // G7.7 / G9: resolve headroom options from preferences + CLI overrides.
-            // Preferences hard-block when headroom.enabled=false (returns HEADROOM_DISABLED_BY_PREFERENCE).
-            // loadPreferences can throw on schema mismatch; we fall back to defaults to avoid
-            // breaking the dispatch on a stale preferences.json file.
+            // loadPreferences can throw on schema mismatch; we fall back to defaults
+            // to avoid breaking the dispatch on a stale preferences.json file.
             let projectPrefs = DEFAULT_PREFERENCES;
-            let headroomPrefs = DEFAULT_PREFERENCES.headroom;
             try {
                 projectPrefs = loadPreferences(projectRoot);
-                headroomPrefs = projectPrefs.headroom;
             }
             catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                // Keep default preferences; the user can re-run with explicit --headroom-mode
-                // if they want to override the fallback.
-            }
-            const headroomResolved = resolveHeadroomOptions(headroomPrefs, {
-                useHeadroom: options.useHeadroom === true,
-                ...(options.headroomMode !== undefined ? { headroomMode: options.headroomMode } : {})
-            });
-            if (headroomResolved.blocked !== null) {
-                printResult(io, fail('sub-agent.dispatch', headroomResolved.blocked, `headroom integration is disabled in preferences (headroom.enabled=false); pass --headroom-mode and update preferences first, or run without --use-headroom`, {
-                    role,
-                    toolCall: null,
-                    dispatchRecordPath: null
-                }, [
-                    'Edit .peaks/preferences.json: set headroom.enabled = true (per-touchpoint mode is headroom.perTouchpoint.subAgentDispatch).',
-                    'Or re-run without --use-headroom to dispatch without compression.'
-                ]), asJson);
-                process.exitCode = 1;
-                return;
+                // Keep default preferences.
             }
             const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
             const adapter = getAdapter(ide);
@@ -390,12 +366,9 @@ export function registerDispatchCommand(parent, io) {
                 process.exitCode = 1;
                 return;
             }
-            // G7.7 headroom compress (opt-in). If headroom fails or is unavailable,
-            // fall back to the original prompt + emit warning.
             // Slice 2026-07-22-orchestrator-memory-preflight (Task 5): prepend the
             // memory preflight block (or silently skip when unavailable) via the
-            // pure-function builder, BEFORE the headroom-ai compress step so the
-            // compressor sees the augmented payload.
+            // pure-function builder.
             const preflightService = new MemoryPreflightService(projectRoot, projectPrefs);
             const memoryBlock = await preflightService.fetchBlock(role);
             // Slice 2026-07-29-context-evaluation-accuracy: capture the
@@ -410,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
                 });
             }
@@ -428,9 +403,8 @@ export function registerDispatchCommand(parent, io) {
                 contextProbe
             });
             // Part 2.C: when --isolation worktree, prepend an isolation envelope
-            // block so the sub-agent sees the lease id + worktree path BEFORE
-            // headroom-ai compress. The block is short (a few lines) and the
-            // compressor is expected to keep it. We deliberately do NOT set
+            // block so the sub-agent sees the lease id + worktree path. The block
+            // is short (a few lines). We deliberately do NOT set
             // process.env.PEAKS_WORKTREE_LEASE_ID here — sub-agents are spawned
             // by the LLM in its own environment, not as children of this CLI;
             // the lease id travels through the dispatch record + prompt body.
@@ -465,20 +439,8 @@ export function registerDispatchCommand(parent, io) {
                     `confirm the file exists. Anti-fake-green rule (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure §Lesson 1): ` +
                     `if the file does not exist, your verdict MUST be \`status: "blocked"\` with reason "must_ls_files_failed". Do NOT silently skip this step.\n`;
             }
-            let effectivePrompt = `${formatTestToolDetection()}\n\n${memoryAugmentedBody}${isolationBlock}${mustLsFilesBlock}`;
-            let headroomCompressed = false;
-            let headroomResult = null;
+            const effectivePrompt = `${formatTestToolDetection()}\n\n${memoryAugmentedBody}${isolationBlock}${mustLsFilesBlock}`;
             const warnings = [...decision.warnings];
-            if (headroomResolved.mode !== null) {
-                headroomResult = await compressPrompt(effectivePrompt, headroomResolved.mode);
-                if (headroomResult.warning !== null) {
-                    warnings.push(headroomResult.warning);
-                }
-                if (headroomResult.compressed && headroomResult.compressedPrompt !== null) {
-                    effectivePrompt = headroomResult.compressedPrompt;
-                    headroomCompressed = true;
-                }
-            }
             let toolCall;
             try {
                 toolCall = adapter.subAgentDispatcher.buildToolCall({ role, prompt: effectivePrompt, requestId: rid, sessionId: sid });
@@ -554,8 +516,7 @@ export function registerDispatchCommand(parent, io) {
                     detail: {
                         requestId: rid,
                         ide: adapter.subAgentDispatcher.label,
-                        promptBytes: effectivePrompt.length,
-                        headroomCompressed
+                        promptBytes: effectivePrompt.length
                     }
                 }, { projectRoot });
             }
@@ -628,9 +589,6 @@ export function registerDispatchCommand(parent, io) {
             if (counter.warning) {
                 nextActions.push(`Batch is over the RL-1 limit (${BATCH_LIMIT}); consider splitting into multiple batches.`);
             }
-            if (headroomResult && headroomResult.warning === 'HEADROOM_UNAVAILABLE') {
-                nextActions.push('Headroom daemon unavailable; dispatched with G7 metadata-only fallback.');
-            }
             const expectedCompletionSeconds = 45;
             const artifactsPublicPaths = typeof options.writeArtifact === 'string' && options.writeArtifact.length > 0
                 ? [options.writeArtifact]
@@ -650,7 +608,7 @@ export function registerDispatchCommand(parent, io) {
                 // disk (gitignored under .peaks/_sub_agents/) keeps the prompt
                 // for the sub-agent to read; CLI stdout stays metadata-only.
                 // Surface promptSize + originalPromptSize so the LLM-side
-                // runner can still reason about headroom without seeing the
+                // runner can reason about the size delta without seeing the
                 // content.
                 originalPromptSize: options.prompt.length,
                 promptSize: effectivePrompt.length,
@@ -658,16 +616,6 @@ export function registerDispatchCommand(parent, io) {
                 dispatchRecordPath,
                 batchId,
                 dispatchedInBatch: counter.count,
-                headroomCompressed,
-                headroomResult: headroomResult
-                    ? {
-                        mode: headroomResult.mode,
-                        compressed: headroomResult.compressed,
-                        compressionRatio: headroomResult.compressionRatio,
-                        tokensSaved: headroomResult.tokensSaved,
-                        warning: headroomResult.warning
-                    }
-                    : null,
                 forcedAt: decision.forcedAt,
                 contextImpact,
                 artifactMetas: artifactMeta ? [artifactMeta] : [],
@@ -706,7 +654,6 @@ export function registerDispatchCommand(parent, io) {
                         role,
                         batchId,
                         dispatchedInBatch: counter.count,
-                        headroomCompressed,
                         forcedAt: decision.forcedAt
                     }
                 });

package/dist/cli/commands/memory-commands.d.ts

@@ -5,8 +5,6 @@ export interface MemorySearchCommandOptions {
     limit?: number;
     project?: string;
     json?: boolean;
-    /** When true, call headroom-ai to compress joined match text for LLM-side prompt assembly. */
-    compressResults?: boolean;
 }
 export interface MemoryListCommandOptions {
     kind?: string;

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

@@ -1,6 +1,6 @@
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
-import { loadMemoryIndex, searchMemoryWithResults } from '../../services/memory/memory-search-service.js';
+import { loadMemoryIndex, searchMemory } from '../../services/memory/memory-search-service.js';
 import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { getErrorMessage, printResult } from '../cli-helpers.js';
@@ -97,19 +97,16 @@ export async function runMemorySearch(io, options) {
         ? options.kind
         : undefined;
     try {
-        const out = await searchMemoryWithResults({
+        const matches = searchMemory({
             query: options.query,
             projectRoot,
             ...(options.limit !== undefined ? { limit: options.limit } : {}),
             ...(kindFilter !== undefined ? { kind: kindFilter } : {}),
-        }, {
-            ...(options.compressResults === true ? { compressResults: true } : {})
         });
         printResult(io, ok('memory.search', {
             query: options.query,
-            total: out.matches.length,
-            matches: out.matches,
-            ...(out.compressedResults !== null ? { compressedResults: out.compressedResults } : {}),
+            total: matches.length,
+            matches,
             warnings: [],
         }, []), options.json);
     }

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

@@ -8,7 +8,6 @@ const ALLOWED_KEYS = new Set([
     'agentShieldPrompt',
     'classifyConservatism',
     'classifyRules',
-    'headroom',
     'swarmSpeculative',
     'loopAutonomousEnabled',
 ]);

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

@@ -36,13 +36,13 @@ import { BROWSER_REUSE_HINT } from '../../services/qa/browser-reuse-hint.js';
 // Plan 1 / Task 9 — auto-build peaks-context before peaks-qa runs.
 import { buildContext } from '../../services/context/context-builder.js';
 // Plan 1 / Task 10 — production fetcher (replaces mockFetcher).
-import { createHeadroomFetcher } from '../../services/context/headroom-fetcher.js';
+import { createDocCacheFetcher } from '../../services/context/doc-cache-fetcher.js';
 // Plan 2 / Task 8 — consume MUT.sig from peaks-mut into verdict envelope.
 import { loadMutReport, mutReportPath } from 'peaks-loop-mut';
-function buildHeadroomFetcher(sid) {
-    return createHeadroomFetcher({
+function buildDocFetcher(sid) {
+    return createDocCacheFetcher({
         cacheDir: `.peaks/_runtime/${sid}/doc-cache`,
-        // remoteFetcher wired in a future slice (headroom-ai programmatic API).
+        // remoteFetcher wired in a future slice.
     });
 }
 async function ensureContextForQa(goal, project, sid) {
@@ -55,7 +55,7 @@ async function ensureContextForQa(goal, project, sid) {
             depsMode: 'locked',
             docBudgetTokens: 8000,
             out,
-            fetcher: buildHeadroomFetcher(sid),
+            fetcher: buildDocFetcher(sid),
         });
     }
     catch (error) {

package/dist/cli/commands/sub-agent-shared.d.ts

@@ -12,12 +12,10 @@
  * Everything else is internal to the `peaks sub-agent` group.
  */
 import type { SubAgentBatchResult } from '../../services/dispatch/sub-agent-dispatcher.js';
-import type { HeadroomMode } from '../../services/context/headroom-client.js';
 import type { HeartbeatStatus } from '../../services/dispatch/dispatch-record-writer.js';
 export { probeShell, type ShellProbeReport, type ShellProbeOptions } from '../../services/env/shell-probe.js';
 export declare const RECOMMENDED_ROLES = "rd | qa | ui | txt | qa-business | qa-perf | qa-security | qa-business-<*> | general-purpose";
 export declare const HEARTBEAT_STATUSES: readonly HeartbeatStatus[];
-export declare const HEADROOM_MODES: readonly HeadroomMode[];
 export declare const PROMPT_LIMIT_BYTES: number;
 export type DispatchOptions = {
     prompt?: string;
@@ -27,8 +25,6 @@ export type DispatchOptions = {
     project?: string;
     batchId?: string;
     writeArtifact?: string;
-    useHeadroom?: boolean;
-    headroomMode?: string;
     force?: boolean;
     fromDag?: string;
     /**

package/dist/cli/commands/sub-agent-shared.js

@@ -25,7 +25,6 @@ export const HEARTBEAT_STATUSES = [
     'never-started',
     'unreadable'
 ];
-export const HEADROOM_MODES = ['balanced', 'aggressive', 'conservative'];
 export const PROMPT_LIMIT_BYTES = 256 * 1024;
 /**
  * Validate a role string. Returns `null` when valid, otherwise the
@@ -75,16 +74,3 @@ export function summarizeBatchResults(results) {
     }
     return { total: results.length, done, failed, cancelled, timeout };
 }
-// Note: `isHeadroomMode` and `RegisterSubCommand` used to live here as
-// duplicate exports. Removed in slice 2026-06-23-audit-p0-cleanup:
-//   - `isHeadroomMode` is exported by `src/services/context/headroom-prefs.ts`
-//     and that is the canonical source — dispatch consumer imports from
-//     there directly.
-//   - `RegisterSubCommand` was never used as a type anywhere; the entry
-//     point (`sub-agent-commands.ts`) calls each register function with
-//     `(program, io)` directly.
-//   - `deriveProjectRoot` (audit-p0-reaudit) was removed in slice
-//     2026-06-23-audit-3rd: it trusted the record path's `.peaks` segment,
-//     letting a caller point `--record` at any project's record tree. The
-//     heartbeat command now trusts `--project` (or `process.cwd()`) and
-//     leaves the relative() backstop to the R-2 guard.

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

@@ -36,11 +36,11 @@ import { registerWorkflowLifecycleCommand } from './workflow-lifecycle-commands.
 // Plan 1 / Task 9 — auto-build peaks-context before peaks-rd runs.
 import { buildContext } from '../../services/context/context-builder.js';
 // Plan 1 / Task 10 — production fetcher (replaces mockFetcher).
-import { createHeadroomFetcher } from '../../services/context/headroom-fetcher.js';
-function buildHeadroomFetcher(sid) {
-    return createHeadroomFetcher({
+import { createDocCacheFetcher } from '../../services/context/doc-cache-fetcher.js';
+function buildDocFetcher(sid) {
+    return createDocCacheFetcher({
         cacheDir: `.peaks/_runtime/${sid}/doc-cache`,
-        // remoteFetcher wired in a future slice (headroom-ai programmatic API).
+        // remoteFetcher wired in a future slice.
     });
 }
 async function ensureContextForRd(goal, project, sid) {
@@ -53,7 +53,7 @@ async function ensureContextForRd(goal, project, sid) {
             depsMode: 'locked',
             docBudgetTokens: 8000,
             out,
-            fetcher: buildHeadroomFetcher(sid),
+            fetcher: buildDocFetcher(sid),
         });
     }
     catch (error) {

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 {};