peaks-loop 4.0.27 → 4.0.29

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 4.0.29 — 2026-09-03 (codegraph 生命周期闭环 — pre-read + auto-refresh)
+
+**3 atomic commits from session 2026-09-03-session-d49394** (user feedback #3):
+
+- `7b9fe627` feat(codegraph): auto-refresh index after slice completion (CLI-internal trigger)
+- `b6599b56` feat(codegraph): preflight project structure into RD dispatch prompts
+- `dfbd229e` docs(memory): sediment codegraph lifecycle closure (pre-read + auto-refresh)
+
+**Highlights**:
+
+1. **slice/request 完成后自动刷新 codegraph** — `job checkpoint --state done` / `request transition --state qa-handoff` 成功后自动 `peaks codegraph index`。CLI-internal 触发（vendor-neutral、不可绕过、恰在 slice 边界 fire 一次），best-effort fail-silent（codegraph 失败不阻塞 checkpoint）。16 个新 BDD 测试。
+
+2. **RD 规划前强制读 codegraph 结构** — peaks-code dispatch RD 前 preflight：确保 index（无则 init+index，fresh 则跳过，foreign-schema fail-soft）+ 读有界 `codegraph files --json` 结构（cap 40 dirs / 12 root files）渲染 `## Codegraph structure` 块注入 RD prompt。codegraph 不可用 → 优雅降级 note，dispatch 照常。13 个新 BDD 测试。
+
+3. 闭环成型：规划前 pre-read（Slice B）→ 实现 → 完成后 auto-refresh（Slice A）→ 下一 slice 读到新图。
+
+## 4.0.28 — 2026-09-03 (codegraph 目录回根 + env-first 1M 窗口识别)
+
+**3 atomic commits from session 2026-09-03-session-d49394** (user feedback batch):
+
+- `c0721d3a` fix(codegraph): revert data dir to root `.codegraph/` — drop `.peaks/.codegraph` handling
+- `7011e64c` fix(context): env-first model window resolution — `[1M]`-suffixed model → 1M context
+- `5289a9b3` docs(memory): sediment codegraph root revert + env-first 1M window fix
+
+**Highlights**:
+
+1. **codegraph 数据目录完全回根** — rid-CG-003（4.0.20）引入的 `.peaks/.codegraph/` preferred 位置被移除，数据目录回到根 `.codegraph/`（上游默认语义）。删除 `PREFERRED_CODEGRAPH_DIR` + preferred/legacy/fresh-preferred 三态 union；`resolveCodegraphProjectRoot` 纯路径数学返回 root；doctor messaging / `.gitignore` / 3 测试同步。用户明确"完全回根，去掉 .peaks 路径"。
+
+2. **env-first 模型上下文窗口识别（1M vs 200K）** — 之前只从 transcript `message.model` 读模型 id，而 Claude Code / deepseek 等的 transcript 记录**裸模型名**（`deepseek-v4-flash`，不带 `[1M]`），导致 1M 上下文模型被误判为 200K 并在 ~50% 处 false soft-warn。新增 `resolveClaudeModelFromEnv` 优先读 env 模型标记（`ANTHROPIC_MODEL` → `ANTHROPIC_DEFAULT_OPUS/SONNET/HAIKU/FABLE_MODEL` → `CLAUDE_CODE_SUBAGENT_MODEL`，`[1M]`/`[1m]` 后缀即 1M），transcript 兜底。实测修复后 `context-now` 从 `capacityTokens: 200000, ratio 0.88` 变为 `capacityTokens: 1000000, ratio 0.19`。
+
 ## 4.0.27 — 2026-09-01 (auto-compact context probe fix)
 
 **1 atomic commit from session 2026-09-01-session-fdd7aa**:

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

@@ -371,6 +371,26 @@ export function registerDispatchCommand(parent, io) {
             // pure-function builder.
             const preflightService = new MemoryPreflightService(projectRoot, projectPrefs);
             const memoryBlock = await preflightService.fetchBlock(role);
+            // Slice 2026-09-03-codegraph-preread (Option A): pre-dispatch
+            // codegraph preflight for RD planning. BEFORE the RD sub-agent's
+            // prompt is composed, ensure the codegraph index exists (init +
+            // index best-effort when `.codegraph/` is absent; skip when already
+            // fresh) and read a BOUNDED project-structure summary. The block is
+            // only requested for the `rd` role — other roles keep the legacy
+            // prompt byte-identical. Fail-soft: any codegraph failure degrades
+            // to a null block (builder renders the "codegraph unavailable" note)
+            // and the dispatch proceeds; we never hard-block RD dispatch here.
+            let codegraphBlock;
+            if (role === 'rd') {
+                try {
+                    const { buildCodegraphPreflightBlock } = await import('../../services/codegraph/codegraph-preflight-service.js');
+                    const preflight = await buildCodegraphPreflightBlock(projectRoot);
+                    codegraphBlock = preflight.available ? preflight.block : null;
+                }
+                catch {
+                    codegraphBlock = null; // fail-soft: never block RD dispatch
+                }
+            }
             // Slice 2026-07-29-context-evaluation-accuracy: capture the
             // authoritative context-fill probe before composing the
             // dispatch prompt. The probe is token-counted (IDE adapter's
@@ -400,7 +420,11 @@ export function registerDispatchCommand(parent, io) {
                 taskTitle: role,
                 taskBody: options.prompt,
                 memoryBlock,
-                contextProbe
+                contextProbe,
+                // exactOptionalPropertyTypes: only set codegraphBlock when the rd
+                // preflight actually produced a value (null = attempted-unavailable,
+                // undefined = not requested → legacy prompt unchanged).
+                ...(codegraphBlock !== undefined ? { codegraphBlock } : {})
             });
             // Part 2.C: when --isolation worktree, prepend an isolation envelope
             // block so the sub-agent sees the lease id + worktree path. The block

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

@@ -13,6 +13,7 @@ import { JobInitInputSchema, JobCheckpointInputSchema, JobBlockInputSchema, } fr
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { buildCostCheckEnvelope, runKarpathyCostCheck, } from '../../services/karpathy-cost/karpathy-cost-check-service.js';
 import { read24hState } from '../../services/24h-mode/store.js';
+import { refreshCodegraphAfterSlice, } from '../../services/codegraph/codegraph-autorefresh.js';
 function projectRoot(opts) {
     // Reuse the workspace root resolver from peaks CLI; for now, CWD as a safe placeholder.
     return opts.project ?? process.cwd();
@@ -172,6 +173,10 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         const jobRoot = resolveJobStateRoot(opts);
         const store = new JobStateStore(jobRoot.rootDir);
         const orch = new JobOrchestrator(store);
+        // 2026-09-03-codegraph-autorefresh: set on --state done so the ok
+        // envelope carries a non-blocking `codegraph` result; null for
+        // failed/skipped (no slice-complete boundary).
+        let codegraph = null;
         if (parsed.data.state === 'done') {
             await orch.checkpointDone({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, ...(parsed.data.commitSha ? { commitSha: parsed.data.commitSha } : {}) });
             // v3.1.2: after each --state done, mirror slice progress to
@@ -188,6 +193,14 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
                 lastCommitSha: parsed.data.commitSha ?? null,
                 updatedAt: new Date().toISOString()
             });
+            // Auto codegraph refresh at the slice-complete boundary. Best-effort
+            // and fail-silent: a refresh failure must never fail the checkpoint.
+            try {
+                codegraph = await refreshCodegraphAfterSlice(project);
+            }
+            catch (e) {
+                codegraph = { refreshed: false, reason: 'unavailable', note: `auto codegraph refresh failed: ${e instanceof Error ? e.message : String(e)}` };
+            }
         }
         else if (parsed.data.state === 'skipped') {
             await orch.checkpointSkipped({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
@@ -195,7 +208,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         else {
             await orch.checkpointFailed({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
         }
-        printResult(io, ok('checkpoint', { sliceId: parsed.data.sliceId, status: parsed.data.state }), opts);
+        printResult(io, ok('checkpoint', { sliceId: parsed.data.sliceId, status: parsed.data.state, codegraph }), opts);
     });
     addJsonOption(job.commands.find(c => c.name() === 'checkpoint'));
     job

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

@@ -6,6 +6,7 @@ import { lintRequestArtifact } from '../../services/artifacts/artifact-lint-serv
 import { getRepairCycleStatus } from '../../services/artifacts/repair-cycle-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { triggerBestPracticeScan } from '../../services/prd/best-practice-auto-trigger.js';
+import { refreshCodegraphAfterSlice, } from '../../services/codegraph/codegraph-autorefresh.js';
 import { formatMdCompact } from '../../shared/format-md-compact.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 /**
@@ -353,6 +354,10 @@ export function registerRequestCommands(program, io) {
             // unchanged — the existing auto-compact orchestrator continues to
             // refuse dispatch at ratio ≥ 0.95.
             let preCompact = null;
+            // 2026-09-03-codegraph-autorefresh: auto codegraph re-index on the
+            // RD → QA slice-complete boundary. Set only for rd:qa-handoff; null
+            // otherwise. Best-effort and fail-silent — never blocks the transition.
+            let codegraphRefresh = null;
             if (role === 'rd' && newState === 'qa-handoff') {
                 try {
                     const { maybePreCompactCheckpoint } = await import('../../services/compact/request-transition-hook.js');
@@ -369,6 +374,13 @@ export function registerRequestCommands(program, io) {
                     // The hook is best-effort; never block the transition.
                     preCompact = null;
                 }
+                try {
+                    codegraphRefresh = await refreshCodegraphAfterSlice(options.project);
+                }
+                catch {
+                    // The refresh is best-effort; never block the transition.
+                    codegraphRefresh = { refreshed: false, reason: 'unavailable', note: 'auto codegraph refresh failed after transition' };
+                }
             }
             // v2.13.2 AC-4 — auto-regen prd/handoff.md on prd:handed-off success.
             // Only fires when the handoff is missing; existing handoffs are not overwritten.
@@ -410,7 +422,7 @@ export function registerRequestCommands(program, io) {
             // transition is not a slice boundary), preCompact is null and
             // we emit a `preCompactCheckpoint: null` field so LLM callers
             // can branch on it without re-deriving zone membership.
-            printResult(io, ok('request.transition', { ...result, preCompactCheckpoint: preCompact?.data ?? null }, preCompact !== null
+            printResult(io, ok('request.transition', { ...result, preCompactCheckpoint: preCompact?.data ?? null, codegraphRefresh }, preCompact !== null
                 ? [
                     `Pre-compact checkpoint written at ratio=${typeof preCompact.data === 'object' && preCompact.data !== null && 'ratio' in preCompact.data
                         ? String(preCompact.data.ratio)

package/dist/services/codegraph/codegraph-autorefresh.d.ts

@@ -0,0 +1,22 @@
+import { type CodegraphProcessRunner } from './codegraph-service.js';
+export type CodegraphAutorefreshResult = {
+    refreshed: true;
+} | {
+    refreshed: false;
+    reason: 'no-codegraph-dir' | 'index-failed' | 'unavailable';
+    note: string;
+};
+/**
+ * True when `<projectRoot>/.codegraph/` exists and is a directory.
+ * Pure fs probe; never throws.
+ */
+export declare function isCodegraphPresent(projectRoot: string): boolean;
+/**
+ * Run a best-effort `codegraph index` refresh for `projectRoot` after a
+ * slice-complete boundary. NEVER throws — every failure path returns a
+ * non-refreshed result so the caller keeps its ok envelope.
+ *
+ * The optional `runner` is a test seam mirroring
+ * `CodegraphProcessRunner`; when omitted the real process runner is used.
+ */
+export declare function refreshCodegraphAfterSlice(projectRoot: string, runner?: CodegraphProcessRunner): Promise<CodegraphAutorefreshResult>;

package/dist/services/codegraph/codegraph-autorefresh.js

@@ -0,0 +1,91 @@
+// src/services/codegraph/codegraph-autorefresh.ts
+//
+// Slice 2026-09-03-codegraph-autorefresh — Option 1: CLI-internal
+// auto codegraph refresh at the slice-complete boundary.
+//
+// `peaks codegraph index` is incremental + idempotent, so re-running it
+// after a slice that changed code is cheap and safe. Rather than rely on
+// the orchestrator LLM to remember the prose rule in
+// `skills/peaks-code/references/codegraph-orchestration.md` ("MUST
+// proactively run `peaks codegraph index --project <path>` after each
+// slice"), the checkpoint/transition command itself triggers the refresh
+// right before it returns its ok envelope. This is the vendor-neutral
+// CLI-internal form of "hook on slice-complete": it is un-bypassable
+// (fires even when the LLM dispatches the command through any IDE / no
+// hook install surface needed), fires exactly once at the true slice
+// boundary, and needs no IDE hook plumbing.
+//
+// The refresh is best-effort and FAIL-SILENT — it never throws and never
+// blocks the checkpoint/transition ok envelope:
+//   - No `<projectRoot>/.codegraph/` directory → skip (codegraph was
+//     never initialized for this project; `peaks codegraph init` is a
+//     one-time setup the orchestrator owns).
+//   - The upstream index exits non-zero → return `index-failed` with a
+//     human-readable note.
+//   - Any unexpected error → return `unavailable` with a note.
+//
+// We deliberately do NOT auto-init: `codegraph init` can prompt / take a
+// long time on first run, which would make the background side-effect
+// block the slice boundary. Projects that want auto-refresh first run
+// `peaks codegraph init` once (per the orchestration doc).
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { CODEGRAPH_DIR_NAME, createCodegraphInvocation, executeCodegraphInvocation, } from './codegraph-service.js';
+/**
+ * True when `<projectRoot>/.codegraph/` exists and is a directory.
+ * Pure fs probe; never throws.
+ */
+export function isCodegraphPresent(projectRoot) {
+    try {
+        return statSync(join(projectRoot, CODEGRAPH_DIR_NAME)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function firstMeaningfulLine(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return 'no upstream output';
+    const first = trimmed.split(/\r?\n/)[0];
+    return first !== undefined ? first.slice(0, 200) : 'no upstream output';
+}
+/**
+ * Run a best-effort `codegraph index` refresh for `projectRoot` after a
+ * slice-complete boundary. NEVER throws — every failure path returns a
+ * non-refreshed result so the caller keeps its ok envelope.
+ *
+ * The optional `runner` is a test seam mirroring
+ * `CodegraphProcessRunner`; when omitted the real process runner is used.
+ */
+export async function refreshCodegraphAfterSlice(projectRoot, runner) {
+    if (!isCodegraphPresent(projectRoot)) {
+        return {
+            refreshed: false,
+            reason: 'no-codegraph-dir',
+            note: `auto codegraph refresh skipped: no ${CODEGRAPH_DIR_NAME} directory at ${join(projectRoot, CODEGRAPH_DIR_NAME)}. Run \`peaks codegraph init\` once to enable post-slice auto-refresh.`,
+        };
+    }
+    try {
+        const invocation = createCodegraphInvocation({ subcommand: 'index', project: projectRoot, quiet: true });
+        const result = await executeCodegraphInvocation(invocation, runner);
+        if (result.exitCode !== 0) {
+            return {
+                refreshed: false,
+                reason: 'index-failed',
+                note: `auto codegraph refresh failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}`,
+            };
+        }
+        return { refreshed: true };
+    }
+    catch (error) {
+        return {
+            refreshed: false,
+            reason: 'unavailable',
+            note: `auto codegraph refresh unavailable: ${errorMessage(error)}`,
+        };
+    }
+}

package/dist/services/codegraph/codegraph-preflight-service.d.ts

@@ -0,0 +1,53 @@
+import { type CodegraphProcessRunner } from './codegraph-service.js';
+export type CodegraphPreflightResult = {
+    available: true;
+    block: string;
+    fileCount: number;
+    truncated: boolean;
+} | {
+    available: false;
+    note: string;
+};
+/** Cap for the directory histogram in the rendered structure block. */
+export declare const CODEGRAPH_STRUCTURE_MAX_DIRS = 40;
+/** Cap for bare root files listed in the rendered structure block. */
+export declare const CODEGRAPH_STRUCTURE_MAX_ROOT_FILES = 12;
+export interface CodegraphStructureFileEntry {
+    readonly path: string;
+}
+export interface CodegraphStructureRenderOptions {
+    readonly maxDirs?: number;
+    readonly maxRootFiles?: number;
+}
+export interface CodegraphStructureSummary {
+    /** Full `## Codegraph structure` markdown block, ending on its own paragraph. */
+    block: string;
+    total: number;
+    truncated: boolean;
+}
+/**
+ * Pure renderer: turn the codegraph `files --json` payload into a bounded
+ * `## Codegraph structure` block. Files are aggregated into a directory
+ * histogram (immediate parent dir; bare root files bucket separately),
+ * sorted by file count descending then name ascending, and capped at
+ * `maxDirs` rows / `maxRootFiles` root entries. Exported separately so the
+ * bounded-output contract is unit-testable without a filesystem.
+ */
+export declare function renderCodegraphStructureBlock(files: readonly CodegraphStructureFileEntry[], options?: CodegraphStructureRenderOptions): CodegraphStructureSummary;
+/**
+ * Pre-dispatch codegraph preflight. Returns a `## Codegraph structure`
+ * block when the index is (or becomes) readable; otherwise an
+ * `{ available: false, note }` result. NEVER throws — the caller must be
+ * able to degrade gracefully on every failure path.
+ *
+ * Behavior matrix (acceptance criteria):
+ * - `.codegraph/` absent  → init + index (best-effort), then read.
+ * - `.codegraph/` present with peaks-loop marker → skip init/index
+ *   (fresh), read directly. No redundant re-index on every dispatch.
+ * - `.codegraph/` present WITHOUT marker (foreign schema) → fail-soft;
+ *   never clobber a foreign store.
+ *
+ * The optional `runner` mirrors `CodegraphProcessRunner` and is the ONLY
+ * injected boundary (tests fake the upstream binary).
+ */
+export declare function buildCodegraphPreflightBlock(projectRoot: string, runner?: CodegraphProcessRunner): Promise<CodegraphPreflightResult>;

package/dist/services/codegraph/codegraph-preflight-service.js

@@ -0,0 +1,226 @@
+// src/services/codegraph/codegraph-preflight-service.ts
+//
+// Slice 2026-09-03-codegraph-preread (Option A) — pre-dispatch codegraph
+// preflight for RD planning. peaks-code's RD dispatch path calls
+// `buildCodegraphPreflightBlock` BEFORE composing the RD sub-agent prompt
+// (src/cli/commands/dispatch-commands.ts) so the RD plans against the real
+// module/file topology in the codegraph index, not LLM memory.
+//
+// The service does three things, all best-effort and fail-soft (it NEVER
+// throws — every failure returns `{ available: false, note }` so the caller
+// degrades to a "codegraph unavailable — proceeding on project-scan only"
+// note and dispatch proceeds):
+//
+//   1. Ensure the schema exists: when `<projectRoot>/.codegraph/` is
+//      absent, run `codegraph init` + `codegraph index` (best-effort).
+//   2. Skip-when-fresh: when `.codegraph/` already carries the
+//      peaks-loop marker, do NOT re-init / re-index on every dispatch
+//      (index is incremental; the sibling rid-2026-09-03-codegraph-autorefresh
+//      owns post-slice refresh). A foreign-schema `.codegraph/` is never
+//      clobbered — we fail-soft instead.
+//   3. Read a BOUNDED project-structure summary from the index
+//      (`codegraph files --json`) and render it as a `## Codegraph
+//      structure` markdown block.
+//
+// Bounded-output contract: the rendered block never exceeds a safe prompt
+// budget. The pure renderer `renderCodegraphStructureBlock` caps the
+// directory histogram at CODEGRAPH_STRUCTURE_MAX_DIRS rows and the root-file
+// listing at CODEGRAPH_STRUCTURE_MAX_ROOT_FILES entries; anything beyond
+// those caps is summarized with a "… and N more" line and a `truncated: true`
+// flag. Documented caps:
+//   - CODEGRAPH_STRUCTURE_MAX_DIRS        = 40  directory rows
+//   - CODEGRAPH_STRUCTURE_MAX_ROOT_FILES  = 12  bare root files
+import { mkdirSync } from 'node:fs';
+import { CODEGRAPH_DIR_NAME, createCodegraphInvocation, defaultCodegraphInitGuard, executeCodegraphInvocation, writeCodegraphMarker, } from './codegraph-service.js';
+import { defaultCodegraphProcessRunner } from './codegraph-process-runner.js';
+/** Cap for the directory histogram in the rendered structure block. */
+export const CODEGRAPH_STRUCTURE_MAX_DIRS = 40;
+/** Cap for bare root files listed in the rendered structure block. */
+export const CODEGRAPH_STRUCTURE_MAX_ROOT_FILES = 12;
+/** Strip a leading `./` (upstream codegraph paths may carry it). */
+function normalizeCodegraphPath(path) {
+    return path.startsWith('./') ? path.slice(2) : path;
+}
+/**
+ * Pure renderer: turn the codegraph `files --json` payload into a bounded
+ * `## Codegraph structure` block. Files are aggregated into a directory
+ * histogram (immediate parent dir; bare root files bucket separately),
+ * sorted by file count descending then name ascending, and capped at
+ * `maxDirs` rows / `maxRootFiles` root entries. Exported separately so the
+ * bounded-output contract is unit-testable without a filesystem.
+ */
+export function renderCodegraphStructureBlock(files, options = {}) {
+    const maxDirs = options.maxDirs ?? CODEGRAPH_STRUCTURE_MAX_DIRS;
+    const maxRootFiles = options.maxRootFiles ?? CODEGRAPH_STRUCTURE_MAX_ROOT_FILES;
+    const dirCounts = new Map();
+    const rootFiles = [];
+    let total = 0;
+    for (const file of files) {
+        const raw = normalizeCodegraphPath(file.path).replace(/\\/g, '/');
+        if (raw.length === 0)
+            continue;
+        total += 1;
+        const slash = raw.lastIndexOf('/');
+        if (slash === -1) {
+            rootFiles.push(raw);
+            continue;
+        }
+        const dir = raw.slice(0, slash);
+        dirCounts.set(dir, (dirCounts.get(dir) ?? 0) + 1);
+    }
+    const sortedDirs = [...dirCounts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    const shownDirs = sortedDirs.slice(0, maxDirs);
+    const truncatedDirs = sortedDirs.length > maxDirs;
+    const sortedRoot = [...rootFiles].sort((a, b) => a.localeCompare(b));
+    const shownRoot = sortedRoot.slice(0, maxRootFiles);
+    const truncatedRoot = sortedRoot.length > maxRootFiles;
+    const lines = ['## Codegraph structure', ''];
+    lines.push(total === 0
+        ? 'No files are indexed yet. Run `peaks codegraph index` before dispatching planning work for symbol-accurate structure.'
+        : `${total} file${total === 1 ? '' : 's'} indexed in the codegraph index:`);
+    for (const [dir, count] of shownDirs) {
+        lines.push(`- \`${dir}/\` — ${count} file${count === 1 ? '' : 's'}`);
+    }
+    if (truncatedDirs) {
+        lines.push(`- … and ${sortedDirs.length - maxDirs} more director${sortedDirs.length - maxDirs === 1 ? 'y' : 'ies'}`);
+    }
+    if (sortedRoot.length > 0) {
+        lines.push(`- (root) — ${shownRoot.map((f) => `\`${f}\``).join(', ')}${truncatedRoot ? ' …' : ''}`);
+    }
+    const block = lines.join('\n').replace(/\s+$/, '') + '\n\n';
+    return { block, total, truncated: truncatedDirs || truncatedRoot };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function firstMeaningfulLine(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return 'no upstream output';
+    const first = trimmed.split(/\r?\n/)[0];
+    return first !== undefined ? first.slice(0, 200) : 'no upstream output';
+}
+function parseFilesPayload(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        if (Array.isArray(parsed)) {
+            const entries = parsed
+                .filter((entry) => typeof entry === 'object' && entry !== null && 'path' in entry)
+                .map((entry) => ({ path: typeof entry.path === 'string' ? entry.path : '' }))
+                .filter((entry) => entry.path.length > 0);
+            return { ok: true, entries };
+        }
+        // JSON but not an array — not the shape we expect.
+        return { ok: false, entries: [] };
+    }
+    catch {
+        // Not JSON at all — e.g. the upstream text path ("No files indexed…").
+        return { ok: false, entries: [] };
+    }
+}
+async function readStructure(projectRoot, runner) {
+    let result;
+    try {
+        const invocation = createCodegraphInvocation({ subcommand: 'files', project: projectRoot, json: true });
+        result = await executeCodegraphInvocation(invocation, runner);
+    }
+    catch (error) {
+        return { available: false, note: `codegraph files unavailable: ${errorMessage(error)}` };
+    }
+    if (result.exitCode !== 0) {
+        return {
+            available: false,
+            note: `codegraph files failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}`,
+        };
+    }
+    const { ok, entries } = parseFilesPayload(result.stdout);
+    if (!ok) {
+        return {
+            available: false,
+            note: 'codegraph files returned no parseable structure — run `peaks codegraph index` before dispatch for symbol-accurate structure.',
+        };
+    }
+    if (entries.length === 0) {
+        return {
+            available: false,
+            note: 'codegraph index has no files — run `peaks codegraph index` before dispatch for symbol-accurate structure.',
+        };
+    }
+    const summary = renderCodegraphStructureBlock(entries);
+    return {
+        available: true,
+        block: summary.block,
+        fileCount: summary.total,
+        truncated: summary.truncated,
+    };
+}
+/**
+ * Pre-dispatch codegraph preflight. Returns a `## Codegraph structure`
+ * block when the index is (or becomes) readable; otherwise an
+ * `{ available: false, note }` result. NEVER throws — the caller must be
+ * able to degrade gracefully on every failure path.
+ *
+ * Behavior matrix (acceptance criteria):
+ * - `.codegraph/` absent  → init + index (best-effort), then read.
+ * - `.codegraph/` present with peaks-loop marker → skip init/index
+ *   (fresh), read directly. No redundant re-index on every dispatch.
+ * - `.codegraph/` present WITHOUT marker (foreign schema) → fail-soft;
+ *   never clobber a foreign store.
+ *
+ * The optional `runner` mirrors `CodegraphProcessRunner` and is the ONLY
+ * injected boundary (tests fake the upstream binary).
+ */
+export async function buildCodegraphPreflightBlock(projectRoot, runner) {
+    const processRunner = runner ?? defaultCodegraphProcessRunner;
+    const guard = defaultCodegraphInitGuard(projectRoot);
+    if (guard.status === 'conflict-foreign-schema') {
+        return {
+            available: false,
+            note: `codegraph unavailable: ${CODEGRAPH_DIR_NAME}/ exists with a non-peaks-loop schema and was not touched. Move or rename the foreign directory, then re-run \`peaks codegraph init\` to enable pre-dispatch structure reads.`,
+        };
+    }
+    if (guard.status === 'fresh') {
+        // 1. init (best-effort). Upstream creates the `.codegraph/` dir; we
+        //    stamp the peaks-loop marker afterwards so the NEXT dispatch hits
+        //    the noop (skip-when-fresh) branch.
+        try {
+            const initResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'init', project: projectRoot }), processRunner);
+            if (initResult.exitCode !== 0) {
+                return {
+                    available: false,
+                    note: `codegraph init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}`,
+                };
+            }
+            try {
+                // Upstream init creates `.codegraph/`; mkdir is a no-op in the real
+                // path and lets the marker write succeed even when the runner is
+                // faked (tests). Best-effort: failure must not undo the init.
+                mkdirSync(guard.codegraphDir, { recursive: true });
+                writeCodegraphMarker(guard.codegraphDir);
+            }
+            catch {
+                // Best-effort: a marker-write failure must not undo the init.
+            }
+        }
+        catch (error) {
+            return { available: false, note: `codegraph init unavailable: ${errorMessage(error)}` };
+        }
+        // 2. index (best-effort).
+        try {
+            const indexResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'index', project: projectRoot, quiet: true }), processRunner);
+            if (indexResult.exitCode !== 0) {
+                return {
+                    available: false,
+                    note: `codegraph index failed (exit ${String(indexResult.exitCode)}): ${firstMeaningfulLine(indexResult.stderr || indexResult.stdout)}`,
+                };
+            }
+        }
+        catch (error) {
+            return { available: false, note: `codegraph index unavailable: ${errorMessage(error)}` };
+        }
+    }
+    // guard.status === 'noop-already-peaks-loop' (or we just initialized):
+    // the schema exists — do NOT re-index, go straight to the bounded read.
+    return readStructure(projectRoot, processRunner);
+}

package/dist/services/codegraph/codegraph-service.d.ts

@@ -41,17 +41,13 @@ export type CodegraphProcessRunner = (invocation: CodegraphInvocation) => Promis
 export declare function createCodegraphInvocation(options: CodegraphInvocationOptions): CodegraphInvocation;
 export declare function executeCodegraphInvocation(invocation: CodegraphInvocation, runner?: CodegraphProcessRunner): Promise<CodegraphExecutionResult>;
 /**
- * Slice rid-CG-006 — root `.codegraph/` (legacy). peaks-loop still
- * reads from this location for back-compat with downstream consumers
- * whose projects pre-date the slice rid-CG-003 preferred-path move.
+ * Single managed codegraph data directory name, relative to the
+ * project root. peaks-loop always reads/writes
+ * `<projectRoot>/.codegraph/` and spawns the upstream binary with
+ * `cwd = <projectRoot>` so its default discovery lands on the same
+ * directory.
  */
 export declare const CODEGRAPH_DIR_NAME = ".codegraph";
-/**
- * Slice rid-CG-003 — preferred managed location. Going forward
- * peaks-loop writes here; legacy root `.codegraph/` is only used
- * when it pre-exists AND `.peaks/.codegraph/` does not.
- */
-export declare const PREFERRED_CODEGRAPH_DIR = ".peaks/.codegraph";
 /**
  * Marker file peaks-loop writes inside the resolved codegraph dir
  * after a successful upstream init. Its presence distinguishes
@@ -61,37 +57,18 @@ export declare const PREFERRED_CODEGRAPH_DIR = ".peaks/.codegraph";
 export declare const CODEGRAPH_MARKER_NAME = ".peaks-loop-marker";
 export declare const CODEGRAPH_INIT_CONFLICT_EXIT_CODE = 73;
 export type ResolvedCodegraphLocation = {
-    readonly source: 'preferred';
-    readonly cwd: string;
-    readonly codegraphDir: string;
-} | {
-    readonly source: 'legacy';
-    readonly cwd: string;
-    readonly codegraphDir: string;
-} | {
-    readonly source: 'fresh-preferred';
+    readonly source: 'root';
+    /** Absolute path the upstream binary should be spawned with. */
     readonly cwd: string;
+    /** Absolute path to the data directory codegraph reads/writes. */
     readonly codegraphDir: string;
 };
 /**
- * Slice rid-CG-003 — pure resolver that returns the cwd the
- * upstream codegraph binary should be spawned with and the
- * absolute path to the data directory it should read/write.
- *
- * Precedence:
- *   1. `<projectRoot>/.peaks/.codegraph/` exists → use it
- *      (cwd = `<projectRoot>/.peaks`, codegraphDir = preferred path)
- *   2. `<projectRoot>/.codegraph/` exists → fall back to legacy
- *      (cwd = `<projectRoot>`, codegraphDir = legacy path)
- *   3. neither exists → default to the preferred path so the next
- *      `peaks codegraph init` lands in `.peaks/.codegraph/`
- *      (cwd = `<projectRoot>/.peaks`, codegraphDir = preferred path,
- *       `source: 'fresh-preferred'`)
- *
- * The cwd is the directory the upstream binary treats as "project
- * root" — the binary's default codegraph discovery reads
- * `<cwd>/.codegraph/`, so we always set cwd to the PARENT of the
- * resolved codegraph dir. Pure fs check; no IO beyond `existsSync`.
+ * Root-only resolver: peaks-loop always manages
+ * `<projectRoot>/.codegraph/`. Returns the cwd the upstream codegraph
+ * binary should be spawned with (= project root, so the binary's
+ * default discovery reads `<projectRoot>/.codegraph/`) and the
+ * absolute data-dir path. Pure path computation; no fs IO.
  */
 export declare function resolveCodegraphProjectRoot(projectRoot: string): ResolvedCodegraphLocation;
 export type CodegraphInitGuardResult = {
@@ -112,12 +89,9 @@ export declare class CodegraphInitConflictError extends Error {
 }
 export type CodegraphInitGuard = (projectRoot: string) => CodegraphInitGuardResult;
 /**
- * Slice rid-CG-003 — preferred-path-first init guard.
- *
- * Looks at `.peaks/.codegraph/` first; falls back to `.codegraph/`
- * when the preferred path is absent. The 'fresh' case returns the
- * preferred path so the next `peaks codegraph init` lands inside
- * `.peaks/` instead of polluting the project root.
+ * Root-only init guard: probes `<projectRoot>/.codegraph/`. 'fresh'
+ * is returned when the directory does not exist yet, so the next
+ * `peaks codegraph init` creates the root `.codegraph/` directory.
  */
 export declare function defaultCodegraphInitGuard(projectRoot: string): CodegraphInitGuardResult;
 /**

package/dist/services/codegraph/codegraph-service.js

@@ -143,10 +143,8 @@ function buildCommandArgs(options, projectRoot) {
 export function createCodegraphInvocation(options) {
     assertSupportedSubcommand(options.subcommand);
     const projectRoot = resolveProjectRoot(options.project);
-    // Slice rid-CG-003 — spawn the upstream binary inside the
-    // resolved codegraph dir's PARENT so its default `.codegraph/`
-    // discovery lands on `.peaks/.codegraph/` (preferred) or
-    // `.codegraph/` (legacy fallback).
+    // Spawn the upstream binary with the project root as cwd so its
+    // default `.codegraph/` discovery reads `<projectRoot>/.codegraph/`.
     const location = resolveCodegraphProjectRoot(projectRoot);
     assertSupportedOptions(options);
     assertRequiredOptions(options);
@@ -165,21 +163,16 @@ export async function executeCodegraphInvocation(invocation, runner = defaultCod
     return runner(invocation);
 }
 /* ──────────────────────────────────────────────────────────────────────
- * Slice rid-CG-003 — preferred `.peaks/.codegraph/` lookup + legacy
- * root `.codegraph/` fallback (spike follow-up #1).
+ * codegraph data-directory resolution — root `.codegraph/` only.
  * ────────────────────────────────────────────────────────────────────── */
 /**
- * Slice rid-CG-006 — root `.codegraph/` (legacy). peaks-loop still
- * reads from this location for back-compat with downstream consumers
- * whose projects pre-date the slice rid-CG-003 preferred-path move.
+ * Single managed codegraph data directory name, relative to the
+ * project root. peaks-loop always reads/writes
+ * `<projectRoot>/.codegraph/` and spawns the upstream binary with
+ * `cwd = <projectRoot>` so its default discovery lands on the same
+ * directory.
  */
 export const CODEGRAPH_DIR_NAME = '.codegraph';
-/**
- * Slice rid-CG-003 — preferred managed location. Going forward
- * peaks-loop writes here; legacy root `.codegraph/` is only used
- * when it pre-exists AND `.peaks/.codegraph/` does not.
- */
-export const PREFERRED_CODEGRAPH_DIR = '.peaks/.codegraph';
 /**
  * Marker file peaks-loop writes inside the resolved codegraph dir
  * after a successful upstream init. Its presence distinguishes
@@ -189,46 +182,17 @@ export const PREFERRED_CODEGRAPH_DIR = '.peaks/.codegraph';
 export const CODEGRAPH_MARKER_NAME = '.peaks-loop-marker';
 export const CODEGRAPH_INIT_CONFLICT_EXIT_CODE = 73;
 /**
- * Slice rid-CG-003 — pure resolver that returns the cwd the
- * upstream codegraph binary should be spawned with and the
- * absolute path to the data directory it should read/write.
- *
- * Precedence:
- *   1. `<projectRoot>/.peaks/.codegraph/` exists → use it
- *      (cwd = `<projectRoot>/.peaks`, codegraphDir = preferred path)
- *   2. `<projectRoot>/.codegraph/` exists → fall back to legacy
- *      (cwd = `<projectRoot>`, codegraphDir = legacy path)
- *   3. neither exists → default to the preferred path so the next
- *      `peaks codegraph init` lands in `.peaks/.codegraph/`
- *      (cwd = `<projectRoot>/.peaks`, codegraphDir = preferred path,
- *       `source: 'fresh-preferred'`)
- *
- * The cwd is the directory the upstream binary treats as "project
- * root" — the binary's default codegraph discovery reads
- * `<cwd>/.codegraph/`, so we always set cwd to the PARENT of the
- * resolved codegraph dir. Pure fs check; no IO beyond `existsSync`.
+ * Root-only resolver: peaks-loop always manages
+ * `<projectRoot>/.codegraph/`. Returns the cwd the upstream codegraph
+ * binary should be spawned with (= project root, so the binary's
+ * default discovery reads `<projectRoot>/.codegraph/`) and the
+ * absolute data-dir path. Pure path computation; no fs IO.
  */
 export function resolveCodegraphProjectRoot(projectRoot) {
-    const preferredDir = join(projectRoot, PREFERRED_CODEGRAPH_DIR);
-    const legacyDir = join(projectRoot, CODEGRAPH_DIR_NAME);
-    if (existsSync(preferredDir)) {
-        return {
-            source: 'preferred',
-            cwd: join(projectRoot, '.peaks'),
-            codegraphDir: preferredDir
-        };
-    }
-    if (existsSync(legacyDir)) {
-        return {
-            source: 'legacy',
-            cwd: projectRoot,
-            codegraphDir: legacyDir
-        };
-    }
     return {
-        source: 'fresh-preferred',
-        cwd: join(projectRoot, '.peaks'),
-        codegraphDir: preferredDir
+        source: 'root',
+        cwd: projectRoot,
+        codegraphDir: join(projectRoot, CODEGRAPH_DIR_NAME)
     };
 }
 export class CodegraphInitConflictError extends Error {
@@ -264,23 +228,16 @@ function inspectCandidateCodegraphDir(codegraphDir) {
     return { status: 'conflict-foreign-schema', codegraphDir };
 }
 /**
- * Slice rid-CG-003 — preferred-path-first init guard.
- *
- * Looks at `.peaks/.codegraph/` first; falls back to `.codegraph/`
- * when the preferred path is absent. The 'fresh' case returns the
- * preferred path so the next `peaks codegraph init` lands inside
- * `.peaks/` instead of polluting the project root.
+ * Root-only init guard: probes `<projectRoot>/.codegraph/`. 'fresh'
+ * is returned when the directory does not exist yet, so the next
+ * `peaks codegraph init` creates the root `.codegraph/` directory.
  */
 export function defaultCodegraphInitGuard(projectRoot) {
-    const preferredDir = join(projectRoot, PREFERRED_CODEGRAPH_DIR);
-    const legacyDir = join(projectRoot, CODEGRAPH_DIR_NAME);
-    if (existsSync(preferredDir)) {
-        return inspectCandidateCodegraphDir(preferredDir);
-    }
-    if (existsSync(legacyDir)) {
-        return inspectCandidateCodegraphDir(legacyDir);
+    const codegraphDir = join(projectRoot, CODEGRAPH_DIR_NAME);
+    if (!existsSync(codegraphDir)) {
+        return { status: 'fresh', codegraphDir };
     }
-    return { status: 'fresh', codegraphDir: preferredDir };
+    return inspectCandidateCodegraphDir(codegraphDir);
 }
 /**
  * Pure-fs helper that stamps the peaks-loop marker AFTER a

package/dist/services/context/build-dispatch-system-prompt.d.ts

@@ -28,6 +28,20 @@ export interface DispatchPromptInput {
      * a byte-counted estimate.
      */
     contextProbe?: ContextPercentProbe | null;
+    /**
+     * Slice 2026-09-03-codegraph-preread (Option A): pre-composed
+     * `## Codegraph structure` markdown block, read from the codegraph
+     * index BEFORE the RD sub-agent's task body is composed so the RD
+     * plans against real module/file topology, not LLM memory.
+     *
+     * - `undefined` → no codegraph block (legacy callers unchanged).
+     * - `null` → codegraph was attempted but is unavailable; the composer
+     *   renders a fixed "codegraph unavailable — proceeding on project-scan
+     *   only" note (fail-soft; never hard-blocks a dispatch).
+     * - `string` → the block, rendered verbatim between the context window
+     *   and the memory/task content.
+     */
+    codegraphBlock?: string | null;
 }
 /**
  * Slice 2026-07-29-worktree-l1: Layer 1 of the 3-layer worktree governance
@@ -88,6 +102,10 @@ export declare const LIFECYCLE_RULES = "## Sub-agent lifecycle rules (locked 202
  * `${formatTestToolDetection()}\n\n${taskBody}`. Today's pre-change behavior
  * produced the same string from `src/cli/commands/dispatch-commands.ts:220`,
  * so the unavailable branch MUST return `taskBody` (NOT a `# title\n\n` wrap).
+ * The contract holds for callers that do not pass `codegraphBlock` (all
+ * non-RD roles). Slice 2026-09-03-codegraph-preread deliberately inserts a
+ * codegraph structure block (or its fail-soft unavailable note) for RD
+ * dispatches between the context window and the memory/task content.
  *
  * Available branch prepends the memory block before the `## Task` heading so
  * `## Project memory …` always sits above the task brief (never pushed below
@@ -99,3 +117,11 @@ export declare const LIFECYCLE_RULES = "## Sub-agent lifecycle rules (locked 202
  * refusal is in scope before any task-specific prose arrives.
  */
 export declare function buildDispatchSystemPrompt(input: DispatchPromptInput): string;
+/**
+ * Slice 2026-09-03-codegraph-preread: fixed degradation string emitted
+ * when the RD dispatch preflight requested a codegraph structure read but
+ * the index could not be resolved (absent + init failure, foreign schema,
+ * unparseable output). Kept as a constant so the unavailable branch is
+ * byte-stable and trivially testable.
+ */
+export declare const CODEGRAPH_UNAVAILABLE_BLOCK = "## Codegraph structure\n\ncodegraph unavailable \u2014 proceeding on project-scan only.\n";

package/dist/services/context/build-dispatch-system-prompt.js

@@ -83,6 +83,10 @@ export const LIFECYCLE_RULES = `## Sub-agent lifecycle rules (locked 2026-08-01)
  * `${formatTestToolDetection()}\n\n${taskBody}`. Today's pre-change behavior
  * produced the same string from `src/cli/commands/dispatch-commands.ts:220`,
  * so the unavailable branch MUST return `taskBody` (NOT a `# title\n\n` wrap).
+ * The contract holds for callers that do not pass `codegraphBlock` (all
+ * non-RD roles). Slice 2026-09-03-codegraph-preread deliberately inserts a
+ * codegraph structure block (or its fail-soft unavailable note) for RD
+ * dispatches between the context window and the memory/task content.
  *
  * Available branch prepends the memory block before the `## Task` heading so
  * `## Project memory …` always sits above the task brief (never pushed below
@@ -94,12 +98,40 @@ export const LIFECYCLE_RULES = `## Sub-agent lifecycle rules (locked 2026-08-01)
  * refusal is in scope before any task-specific prose arrives.
  */
 export function buildDispatchSystemPrompt(input) {
-    const { taskBody, memoryBlock, contextProbe } = input;
+    const { taskBody, memoryBlock, contextProbe, codegraphBlock } = input;
     const contextBlock = renderContextBlock(contextProbe ?? null);
+    const codegraphText = renderCodegraphBlock(codegraphBlock);
     if (memoryBlock.available === true && typeof memoryBlock.block === 'string') {
-        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${memoryBlock.block}\n## Task\n${taskBody}`;
+        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${memoryBlock.block}\n## Task\n${taskBody}`;
     }
-    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${taskBody}`;
+    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${taskBody}`;
+}
+/**
+ * Slice 2026-09-03-codegraph-preread: fixed degradation string emitted
+ * when the RD dispatch preflight requested a codegraph structure read but
+ * the index could not be resolved (absent + init failure, foreign schema,
+ * unparseable output). Kept as a constant so the unavailable branch is
+ * byte-stable and trivially testable.
+ */
+export const CODEGRAPH_UNAVAILABLE_BLOCK = '## Codegraph structure\n\ncodegraph unavailable — proceeding on project-scan only.\n';
+/**
+ * Render the codegraph insertion for a dispatch prompt.
+ *
+ * - `undefined` → empty (the composer is byte-identical to the legacy
+ *   shape for callers that did not opt into a codegraph pre-read).
+ * - `null` → the fixed CODEGRAPH_UNAVAILABLE_BLOCK note.
+ * - `string` → the pre-composed block from the codegraph preflight
+ *   service, verbatim.
+ *
+ * Every non-empty variant is normalized to end on its own paragraph
+ * (`\n\n`) so the following block (project memory or task body) starts
+ * cleanly regardless of the caller's trailing newline habits.
+ */
+function renderCodegraphBlock(codegraphBlock) {
+    if (codegraphBlock === undefined)
+        return '';
+    const text = codegraphBlock === null ? CODEGRAPH_UNAVAILABLE_BLOCK : codegraphBlock;
+    return `${text.replace(/\s+$/, '')}\n\n`;
 }
 /**
  * Slice 2026-07-29-context-evaluation-accuracy: emit a

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,4 +1,11 @@
 import type { IdeAdapter } from '../ide-types.js';
+/**
+ * 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.
  *

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

@@ -103,6 +103,50 @@ const TRANSCRIPT_SCAN_CHUNK_BYTES = 64 * 1024;
  * 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.
  *
@@ -251,8 +295,12 @@ function resolveContextWindowTokens(model, contextTokens) {
  * `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) {
+function readClaudeTranscriptEstimate(outerSessionId, envModel) {
     const projectsDir = join(homedir(), '.claude', 'projects');
     const path = findTranscriptJsonl(projectsDir, outerSessionId);
     if (path === null)
@@ -260,7 +308,8 @@ function readClaudeTranscriptEstimate(outerSessionId) {
     const latest = findLatestTranscriptUsage(path);
     if (latest === null)
         return null;
-    const contextWindowTokens = resolveContextWindowTokens(latest.model, latest.contextTokens);
+    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 };
 }
@@ -274,7 +323,10 @@ function readClaudeTranscriptEstimate(outerSessionId) {
  *      `~/.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).
+ *      `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`.
  */
@@ -291,7 +343,8 @@ function readContextPercentFallback(input) {
         return { ratio: statusline, source: 'statusline-poll', capacityBytes, ide, capturedAt };
     }
     if (typeof input.outerSessionId === 'string' && input.outerSessionId.length > 0) {
-        const estimate = readClaudeTranscriptEstimate(input.outerSessionId);
+        const envModel = resolveClaudeModelFromEnv(input.env);
+        const estimate = readClaudeTranscriptEstimate(input.outerSessionId, envModel);
         if (estimate !== null) {
             return {
                 ratio: estimate.ratio,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.27",
+  "version": "4.0.29",
   "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-mut": "0.1.25",
-    "peaks-loop-internal-runtime": "0.0.12",
-    "peaks-loop-shared": "0.0.61",
-    "peaks-loop-shared-channel": "0.0.29"
+    "peaks-loop-internal-runtime": "0.0.14",
+    "peaks-loop-mut": "0.1.27",
+    "peaks-loop-shared-channel": "0.0.31",
+    "peaks-loop-shared": "0.0.63"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",