peaks-loop 4.0.29 → 4.0.31

package/dist/services/code/auto-compact-lifecycle.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Auto-compact lifecycle telemetry (v2.13.0 AC-2 + AC-3 + AC-4,
+ * slice 2026-08-01-compact-lifecycle Task 5).
+ *
+ * Extracted from `auto-compact-orchestrator.ts` to keep that file under
+ * the 800 LOC cap (mechanical verbatim move). Publishes the stages a
+ * compact attempt actually PROVED in-process (`queued` / `preparing` /
+ * `compacting`) plus the terminal `failed` stage, and settles an open
+ * `compacting` run using a real post-compact measurement. Telemetry is
+ * strictly subordinate to the compact itself: every write is best-effort
+ * and never changes the threshold decision, the dispatch, or the
+ * returned envelope.
+ */
+import { type CompactLifecycleRecord, type CompactLifecycleStage } from '../compact-statusline/compact-lifecycle-store.js';
+/**
+ * Stages a compact *attempt* can prove from inside the dispatching
+ * process. `verifying` / `completed` are deliberately absent — see
+ * `CompactLifecyclePublisher` and `settleOpenLifecycleRun` for why.
+ */
+type ObservableDispatchStage = Extract<CompactLifecycleStage, 'queued' | 'preparing' | 'compacting'>;
+/**
+ * One id per compact attempt. Timestamp-prefixed so a human reading
+ * the raw record can order runs by eye; the random suffix keeps two
+ * attempts inside the same millisecond distinct.
+ */
+export declare function newCompactRunId(now: Date): string;
+/**
+ * Slice 2026-08-01-compact-lifecycle (Task 5): the local transition
+ * builder. Carries `runId`, `triggerRatio` and `redLine` forward from
+ * the run that opened, and remembers the prior stage so a failure can
+ * name the stage it died in.
+ *
+ * TRUTHFULNESS: this publisher only ever emits a stage the calling
+ * process has actually PROVED. It never emits `verifying` or
+ * `completed` off the back of a successful dispatch — see
+ * `runAutoCompact` and `settleOpenLifecycleRun` for the reason.
+ *
+ * Telemetry is strictly subordinate to the compact itself: every write
+ * is best-effort, and a store failure must not change the threshold
+ * decision, the dispatch, or the returned envelope.
+ */
+export declare class CompactLifecyclePublisher {
+    private readonly ctx;
+    private lastStage;
+    constructor(ctx: {
+        readonly projectRoot: string;
+        readonly sessionId: string;
+        readonly runId: string;
+        readonly triggerRatio: number;
+        readonly redLine: boolean;
+        readonly onLifecycleStage?: ((stage: CompactLifecycleStage, record: CompactLifecycleRecord) => void) | undefined;
+        readonly failLifecycleWrite?: boolean | undefined;
+    });
+    /** Publish an active stage the process has proved. */
+    advance(stage: ObservableDispatchStage): void;
+    /** Publish the terminal failure, attributed to the last stage reached. */
+    fail(error: unknown): void;
+    private write;
+}
+/**
+ * Reduce an arbitrary thrown value to a single-line, bounded summary
+ * fit for a statusline. Stack frames are dropped (the record is a
+ * human-facing indicator, not a crash dump); the store clamps the
+ * result to its own 160-character cap as a second line of defence.
+ *
+ * `null` / `undefined` thrown values — a real possibility from
+ * `Promise.reject(null)` or a thrown `undefined` — must not collapse
+ * to the empty string, which the store would then reject as missing.
+ * They map to a fixed "unknown error" sentinel so the record always
+ * carries some diagnostic text.
+ */
+export declare function summarizeLifecycleError(error: unknown): string;
+/**
+ * Slice 2026-08-01-compact-lifecycle (Task 5, Step 4): close out an
+ * open compact run using a REAL measurement.
+ *
+ * This is the integration with the actual post-compact detection path.
+ * The claude-code adapter's `postCompactDetectCommand` is
+ * `peaks compact auto --json` — i.e. the next probe through this very
+ * function. So when a probe finds a run still sitting at `compacting`
+ * and MEASURES a ratio that has dropped below the auto-fire threshold,
+ * that measurement is the proof the compact landed. Only then do we
+ * emit `verifying` (we have a measurement in hand) followed by
+ * `completed` (it confirms the drop), carrying the measured
+ * `afterRatio`.
+ *
+ * We refuse to complete when:
+ *   - the probe could not measure anything (`conservative-fallback`
+ *     returns `ratio: 0`, which means "unknown", NOT "empty"). Writing
+ *     `afterRatio: 0` there would publish a fabricated number;
+ *   - the ratio is still at or above the auto-fire threshold — the
+ *     compact has not landed, so the run stays open.
+ */
+export declare function settleOpenLifecycleRun(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly measuredRatio: number;
+    readonly source: string;
+    readonly autoFireThreshold: number;
+    readonly onLifecycleStage?: ((stage: CompactLifecycleStage, record: CompactLifecycleRecord) => void) | undefined;
+}): void;
+export {};

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

@@ -0,0 +1,235 @@
+/**
+ * Auto-compact lifecycle telemetry (v2.13.0 AC-2 + AC-3 + AC-4,
+ * slice 2026-08-01-compact-lifecycle Task 5).
+ *
+ * Extracted from `auto-compact-orchestrator.ts` to keep that file under
+ * the 800 LOC cap (mechanical verbatim move). Publishes the stages a
+ * compact attempt actually PROVED in-process (`queued` / `preparing` /
+ * `compacting`) plus the terminal `failed` stage, and settles an open
+ * `compacting` run using a real post-compact measurement. Telemetry is
+ * strictly subordinate to the compact itself: every write is best-effort
+ * and never changes the threshold decision, the dispatch, or the
+ * returned envelope.
+ */
+import { readCompactLifecycle, writeCompactLifecycle } from '../compact-statusline/compact-lifecycle-store.js';
+/**
+ * PRD-002b slice 2 — extract the few cross-cutting magic numbers
+ * that actually appear at runtime call sites in this orchestrator.
+ * Threshold ratios (0.85 / 0.95) live in `auto-compact-types.ts`
+ * and are NOT extracted here because they ARE the contract; comment
+ * + spec prose references must keep the literal value visible.
+ */
+const COLLAPSED_ERROR_MAX_CHARS = 160;
+/**
+ * One id per compact attempt. Timestamp-prefixed so a human reading
+ * the raw record can order runs by eye; the random suffix keeps two
+ * attempts inside the same millisecond distinct.
+ */
+export function newCompactRunId(now) {
+    const stamp = now.toISOString().replace(/[:.]/g, '-');
+    const suffix = Math.random().toString(16).slice(2, 8);
+    return `compact-${stamp}-${suffix}`;
+}
+/**
+ * Slice 2026-08-01-compact-lifecycle (Task 5): read an open compact
+ * record ignoring staleness.
+ *
+ * The lifecycle store classifies an active record as `stalled` after a
+ * caller-supplied `staleAfterMs` window. That classification exists for
+ * the statusline renderer (Task 2/3) — it tells the user "this run
+ * hasn't heartbeated for a while".
+ *
+ * For settling a run by measurement, staleness is irrelevant: if a
+ * record exists at `compacting`, a post-compact probe that measures a
+ * drop should still complete it, even if the probe itself ran hours
+ * later. Wrapping that unbounded read here keeps the magic number out
+ * of the settle path and makes the intent self-documenting.
+ *
+ * Returns `null` for any non-`valid` kind (missing / invalid /
+ * stalled). Errors from the underlying read are swallowed — settling
+ * is best-effort telemetry and must never bubble.
+ */
+function readOpenCompactLifecycle(input) {
+    let out;
+    try {
+        out = readCompactLifecycle({
+            projectRoot: input.projectRoot,
+            sessionId: input.sessionId,
+            nowMs: Date.now(),
+            // Number.MAX_SAFE_INTEGER disables the store's staleness gate
+            // for this call — see the doc comment above for why settling
+            // intentionally ignores staleness.
+            staleAfterMs: Number.MAX_SAFE_INTEGER
+        });
+    }
+    catch {
+        return null;
+    }
+    return out.kind === 'valid' ? out.record : null;
+}
+/**
+ * Slice 2026-08-01-compact-lifecycle (Task 5): the local transition
+ * builder. Carries `runId`, `triggerRatio` and `redLine` forward from
+ * the run that opened, and remembers the prior stage so a failure can
+ * name the stage it died in.
+ *
+ * TRUTHFULNESS: this publisher only ever emits a stage the calling
+ * process has actually PROVED. It never emits `verifying` or
+ * `completed` off the back of a successful dispatch — see
+ * `runAutoCompact` and `settleOpenLifecycleRun` for the reason.
+ *
+ * Telemetry is strictly subordinate to the compact itself: every write
+ * is best-effort, and a store failure must not change the threshold
+ * decision, the dispatch, or the returned envelope.
+ */
+export class CompactLifecyclePublisher {
+    ctx;
+    lastStage = 'queued';
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** Publish an active stage the process has proved. */
+    advance(stage) {
+        this.lastStage = stage;
+        this.write({
+            schemaVersion: 1,
+            runId: this.ctx.runId,
+            stage,
+            updatedAt: new Date().toISOString(),
+            triggerRatio: this.ctx.triggerRatio,
+            redLine: this.ctx.redLine
+        });
+    }
+    /** Publish the terminal failure, attributed to the last stage reached. */
+    fail(error) {
+        this.write({
+            schemaVersion: 1,
+            runId: this.ctx.runId,
+            stage: 'failed',
+            updatedAt: new Date().toISOString(),
+            triggerRatio: this.ctx.triggerRatio,
+            redLine: this.ctx.redLine,
+            failedAt: this.lastStage,
+            errorSummary: summarizeLifecycleError(error)
+        });
+    }
+    write(record) {
+        try {
+            if (this.ctx.failLifecycleWrite)
+                throw new Error('lifecycle store unavailable');
+            writeCompactLifecycle({
+                projectRoot: this.ctx.projectRoot,
+                sessionId: this.ctx.sessionId,
+                record
+            });
+        }
+        catch {
+            // Best-effort telemetry: a lifecycle write failure must never
+            // change the compact decision, the dispatch, or the envelope.
+            return;
+        }
+        try {
+            this.ctx.onLifecycleStage?.(record.stage, record);
+        }
+        catch {
+            // An observer is a passive listener; its failure is not ours.
+        }
+    }
+}
+/**
+ * Reduce an arbitrary thrown value to a single-line, bounded summary
+ * fit for a statusline. Stack frames are dropped (the record is a
+ * human-facing indicator, not a crash dump); the store clamps the
+ * result to its own 160-character cap as a second line of defence.
+ *
+ * `null` / `undefined` thrown values — a real possibility from
+ * `Promise.reject(null)` or a thrown `undefined` — must not collapse
+ * to the empty string, which the store would then reject as missing.
+ * They map to a fixed "unknown error" sentinel so the record always
+ * carries some diagnostic text.
+ */
+export function summarizeLifecycleError(error) {
+    let raw;
+    if (error instanceof Error)
+        raw = error.message;
+    else if (error === null || error === undefined)
+        raw = 'unknown error';
+    else
+        raw = String(error);
+    if (raw.length === 0)
+        raw = 'unknown error';
+    const firstLine = raw.split('\n')[0] ?? '';
+    const collapsed = firstLine.replace(/\s+/g, ' ').trim();
+    return collapsed.length === 0 ? 'unknown error' : (collapsed.length > COLLAPSED_ERROR_MAX_CHARS ? collapsed.slice(0, COLLAPSED_ERROR_MAX_CHARS) : collapsed);
+}
+/**
+ * Slice 2026-08-01-compact-lifecycle (Task 5, Step 4): close out an
+ * open compact run using a REAL measurement.
+ *
+ * This is the integration with the actual post-compact detection path.
+ * The claude-code adapter's `postCompactDetectCommand` is
+ * `peaks compact auto --json` — i.e. the next probe through this very
+ * function. So when a probe finds a run still sitting at `compacting`
+ * and MEASURES a ratio that has dropped below the auto-fire threshold,
+ * that measurement is the proof the compact landed. Only then do we
+ * emit `verifying` (we have a measurement in hand) followed by
+ * `completed` (it confirms the drop), carrying the measured
+ * `afterRatio`.
+ *
+ * We refuse to complete when:
+ *   - the probe could not measure anything (`conservative-fallback`
+ *     returns `ratio: 0`, which means "unknown", NOT "empty"). Writing
+ *     `afterRatio: 0` there would publish a fabricated number;
+ *   - the ratio is still at or above the auto-fire threshold — the
+ *     compact has not landed, so the run stays open.
+ */
+export function settleOpenLifecycleRun(input) {
+    // A `conservative-fallback` probe means no signal was available at
+    // all. Its `ratio: 0` is the absence of a measurement, so it can
+    // never be evidence that the context shrank.
+    if (input.source === 'conservative-fallback')
+        return;
+    if (input.measuredRatio >= input.autoFireThreshold)
+        return;
+    const prior = readOpenCompactLifecycle({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId
+    });
+    if (prior === null)
+        return;
+    // Only a run that was actually dispatched (`compacting`) can be
+    // completed by a post-compact measurement.
+    if (prior.stage !== 'compacting')
+        return;
+    const emit = (stage, withAfterRatio) => {
+        const record = {
+            schemaVersion: 1,
+            runId: prior.runId,
+            stage,
+            updatedAt: new Date().toISOString(),
+            triggerRatio: prior.triggerRatio,
+            redLine: prior.redLine,
+            ...(withAfterRatio ? { afterRatio: input.measuredRatio } : {})
+        };
+        try {
+            writeCompactLifecycle({
+                projectRoot: input.projectRoot,
+                sessionId: input.sessionId,
+                record
+            });
+        }
+        catch {
+            return;
+        }
+        try {
+            input.onLifecycleStage?.(stage, record);
+        }
+        catch {
+            // Observer failures are not ours to propagate.
+        }
+    };
+    // `verifying` = we hold a measurement and are checking it.
+    emit('verifying', false);
+    // `completed` = the measurement confirms the drop; publish it.
+    emit('completed', true);
+}

package/dist/services/code/auto-compact-orchestrator.d.ts

@@ -1,7 +1,7 @@
 import { type CompactTrigger, type ConvergencePlan, type InFlightBatchProbe, type AutoCompactResult } from '../context/auto-compact-types.js';
 import type { CompactTarget } from '../context/auto-compact-dispatcher.js';
 import { type AutoCompactMode } from './auto-compact-modes.js';
-import { type CompactLifecycleRecord, type CompactLifecycleStage } from '../compact-statusline/compact-lifecycle-store.js';
+import type { CompactLifecycleRecord, CompactLifecycleStage } from '../compact-statusline/compact-lifecycle-store.js';
 export interface AutoCompactInput {
     /** Project root for context (default cwd). */
     readonly projectRoot: string;

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

@@ -35,16 +35,8 @@ 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';
-import { readCompactLifecycle, writeCompactLifecycle } from '../compact-statusline/compact-lifecycle-store.js';
+import { CompactLifecyclePublisher, newCompactRunId, settleOpenLifecycleRun, summarizeLifecycleError } from './auto-compact-lifecycle.js';
 const PRE_COMPACT_REASON = 'pre-compact-auto';
-/**
- * PRD-002b slice 2 — extract the few cross-cutting magic numbers
- * that actually appear at runtime call sites in this orchestrator.
- * Threshold ratios (0.85 / 0.95) live in `auto-compact-types.ts`
- * and are NOT extracted here because they ARE the contract; comment
- * + spec prose references must keep the literal value visible.
- */
-const COLLAPSED_ERROR_MAX_CHARS = 160;
 /**
  * Map a context ratio to a `CompactTrigger` action. Pure; the side
  * effects (checkpoint + IDE dispatch) live in `runAutoCompact`. Two
@@ -278,219 +270,6 @@ function resolveAutoCompactMode(projectRoot, sessionId) {
         return 'standard';
     }
 }
-/**
- * One id per compact attempt. Timestamp-prefixed so a human reading
- * the raw record can order runs by eye; the random suffix keeps two
- * attempts inside the same millisecond distinct.
- */
-function newCompactRunId(now) {
-    const stamp = now.toISOString().replace(/[:.]/g, '-');
-    const suffix = Math.random().toString(16).slice(2, 8);
-    return `compact-${stamp}-${suffix}`;
-}
-/**
- * Slice 2026-08-01-compact-lifecycle (Task 5): read an open compact
- * record ignoring staleness.
- *
- * The lifecycle store classifies an active record as `stalled` after a
- * caller-supplied `staleAfterMs` window. That classification exists for
- * the statusline renderer (Task 2/3) — it tells the user "this run
- * hasn't heartbeated for a while".
- *
- * For settling a run by measurement, staleness is irrelevant: if a
- * record exists at `compacting`, a post-compact probe that measures a
- * drop should still complete it, even if the probe itself ran hours
- * later. Wrapping that unbounded read here keeps the magic number out
- * of the settle path and makes the intent self-documenting.
- *
- * Returns `null` for any non-`valid` kind (missing / invalid /
- * stalled). Errors from the underlying read are swallowed — settling
- * is best-effort telemetry and must never bubble.
- */
-function readOpenCompactLifecycle(input) {
-    let out;
-    try {
-        out = readCompactLifecycle({
-            projectRoot: input.projectRoot,
-            sessionId: input.sessionId,
-            nowMs: Date.now(),
-            // Number.MAX_SAFE_INTEGER disables the store's staleness gate
-            // for this call — see the doc comment above for why settling
-            // intentionally ignores staleness.
-            staleAfterMs: Number.MAX_SAFE_INTEGER
-        });
-    }
-    catch {
-        return null;
-    }
-    return out.kind === 'valid' ? out.record : null;
-}
-/**
- * Slice 2026-08-01-compact-lifecycle (Task 5): the local transition
- * builder. Carries `runId`, `triggerRatio` and `redLine` forward from
- * the run that opened, and remembers the prior stage so a failure can
- * name the stage it died in.
- *
- * TRUTHFULNESS: this publisher only ever emits a stage the calling
- * process has actually PROVED. It never emits `verifying` or
- * `completed` off the back of a successful dispatch — see
- * `runAutoCompact` and `settleOpenLifecycleRun` for the reason.
- *
- * Telemetry is strictly subordinate to the compact itself: every write
- * is best-effort, and a store failure must not change the threshold
- * decision, the dispatch, or the returned envelope.
- */
-class CompactLifecyclePublisher {
-    ctx;
-    lastStage = 'queued';
-    constructor(ctx) {
-        this.ctx = ctx;
-    }
-    /** Publish an active stage the process has proved. */
-    advance(stage) {
-        this.lastStage = stage;
-        this.write({
-            schemaVersion: 1,
-            runId: this.ctx.runId,
-            stage,
-            updatedAt: new Date().toISOString(),
-            triggerRatio: this.ctx.triggerRatio,
-            redLine: this.ctx.redLine
-        });
-    }
-    /** Publish the terminal failure, attributed to the last stage reached. */
-    fail(error) {
-        this.write({
-            schemaVersion: 1,
-            runId: this.ctx.runId,
-            stage: 'failed',
-            updatedAt: new Date().toISOString(),
-            triggerRatio: this.ctx.triggerRatio,
-            redLine: this.ctx.redLine,
-            failedAt: this.lastStage,
-            errorSummary: summarizeLifecycleError(error)
-        });
-    }
-    write(record) {
-        try {
-            if (this.ctx.failLifecycleWrite)
-                throw new Error('lifecycle store unavailable');
-            writeCompactLifecycle({
-                projectRoot: this.ctx.projectRoot,
-                sessionId: this.ctx.sessionId,
-                record
-            });
-        }
-        catch {
-            // Best-effort telemetry: a lifecycle write failure must never
-            // change the compact decision, the dispatch, or the envelope.
-            return;
-        }
-        try {
-            this.ctx.onLifecycleStage?.(record.stage, record);
-        }
-        catch {
-            // An observer is a passive listener; its failure is not ours.
-        }
-    }
-}
-/**
- * Reduce an arbitrary thrown value to a single-line, bounded summary
- * fit for a statusline. Stack frames are dropped (the record is a
- * human-facing indicator, not a crash dump); the store clamps the
- * result to its own 160-character cap as a second line of defence.
- *
- * `null` / `undefined` thrown values — a real possibility from
- * `Promise.reject(null)` or a thrown `undefined` — must not collapse
- * to the empty string, which the store would then reject as missing.
- * They map to a fixed "unknown error" sentinel so the record always
- * carries some diagnostic text.
- */
-function summarizeLifecycleError(error) {
-    let raw;
-    if (error instanceof Error)
-        raw = error.message;
-    else if (error === null || error === undefined)
-        raw = 'unknown error';
-    else
-        raw = String(error);
-    if (raw.length === 0)
-        raw = 'unknown error';
-    const firstLine = raw.split('\n')[0] ?? '';
-    const collapsed = firstLine.replace(/\s+/g, ' ').trim();
-    return collapsed.length === 0 ? 'unknown error' : (collapsed.length > COLLAPSED_ERROR_MAX_CHARS ? collapsed.slice(0, COLLAPSED_ERROR_MAX_CHARS) : collapsed);
-}
-/**
- * Slice 2026-08-01-compact-lifecycle (Task 5, Step 4): close out an
- * open compact run using a REAL measurement.
- *
- * This is the integration with the actual post-compact detection path.
- * The claude-code adapter's `postCompactDetectCommand` is
- * `peaks compact auto --json` — i.e. the next probe through this very
- * function. So when a probe finds a run still sitting at `compacting`
- * and MEASURES a ratio that has dropped below the auto-fire threshold,
- * that measurement is the proof the compact landed. Only then do we
- * emit `verifying` (we have a measurement in hand) followed by
- * `completed` (it confirms the drop), carrying the measured
- * `afterRatio`.
- *
- * We refuse to complete when:
- *   - the probe could not measure anything (`conservative-fallback`
- *     returns `ratio: 0`, which means "unknown", NOT "empty"). Writing
- *     `afterRatio: 0` there would publish a fabricated number;
- *   - the ratio is still at or above the auto-fire threshold — the
- *     compact has not landed, so the run stays open.
- */
-function settleOpenLifecycleRun(input) {
-    // A `conservative-fallback` probe means no signal was available at
-    // all. Its `ratio: 0` is the absence of a measurement, so it can
-    // never be evidence that the context shrank.
-    if (input.source === 'conservative-fallback')
-        return;
-    if (input.measuredRatio >= input.autoFireThreshold)
-        return;
-    const prior = readOpenCompactLifecycle({
-        projectRoot: input.projectRoot,
-        sessionId: input.sessionId
-    });
-    if (prior === null)
-        return;
-    // Only a run that was actually dispatched (`compacting`) can be
-    // completed by a post-compact measurement.
-    if (prior.stage !== 'compacting')
-        return;
-    const emit = (stage, withAfterRatio) => {
-        const record = {
-            schemaVersion: 1,
-            runId: prior.runId,
-            stage,
-            updatedAt: new Date().toISOString(),
-            triggerRatio: prior.triggerRatio,
-            redLine: prior.redLine,
-            ...(withAfterRatio ? { afterRatio: input.measuredRatio } : {})
-        };
-        try {
-            writeCompactLifecycle({
-                projectRoot: input.projectRoot,
-                sessionId: input.sessionId,
-                record
-            });
-        }
-        catch {
-            return;
-        }
-        try {
-            input.onLifecycleStage?.(stage, record);
-        }
-        catch {
-            // Observer failures are not ours to propagate.
-        }
-    };
-    // `verifying` = we hold a measurement and are checking it.
-    emit('verifying', false);
-    // `completed` = the measurement confirms the drop; publish it.
-    emit('completed', true);
-}
 /**
  * Execute the auto-compact flow.
  *

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

@@ -20,17 +20,24 @@
 //   - No `<projectRoot>/.codegraph/` directory → skip (codegraph was
 //     never initialized for this project; `peaks codegraph init` is a
 //     one-time setup the orchestrator owns).
+//   - `.codegraph/` present WITH `codegraph.db` → `index` (incremental).
+//   - `.codegraph/` present with the peaks-loop marker but NO
+//     `codegraph.db` (dangling) → self-heal: `init` then `index`.
+//   - `.codegraph/` present without a marker and without `codegraph.db`
+//     (foreign schema) → skip; never touch a foreign store.
 //   - 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';
+// We do NOT auto-init a genuinely fresh (no `.codegraph/` dir) project:
+// the orchestrator owns that one-time setup. The dangling self-heal above
+// IS an auto-init, but `codegraph init` (WITHOUT `--index`) is fast (~1 s)
+// and offline-safe — it only `Parser.init()`s WASM grammars that resolve
+// from node_modules. The slow/offline concern applies to `index` (full
+// build), not `init`.
+import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { CODEGRAPH_DIR_NAME, createCodegraphInvocation, executeCodegraphInvocation, } from './codegraph-service.js';
+import { CODEGRAPH_DIR_NAME, CODEGRAPH_MARKER_NAME, createCodegraphInvocation, executeCodegraphInvocation, isCodegraphInitialized, } from './codegraph-service.js';
 /**
  * True when `<projectRoot>/.codegraph/` exists and is a directory.
  * Pure fs probe; never throws.
@@ -43,6 +50,14 @@ export function isCodegraphPresent(projectRoot) {
         return false;
     }
 }
+/**
+ * True when `<projectRoot>/.codegraph/` carries the peaks-loop marker
+ * (i.e. peaks-loop manages it, as opposed to a foreign tool). Pure fs
+ * probe; never throws.
+ */
+function isCodegraphPeaksLoopManaged(projectRoot) {
+    return existsSync(join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_MARKER_NAME));
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -70,6 +85,29 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
         };
     }
     try {
+        // A `.codegraph/` dir without a `codegraph.db` is uninitialized:
+        //   - NOT peaks-loop-managed → foreign schema, never touch it.
+        //   - peaks-loop-managed → the dangling state left by the pre-fix
+        //     rid-CG-001 auto-stake (marker stamped, no upstream init). Run
+        //     init (fast, offline-safe — no full index) so the subsequent
+        //     index has a schema to write into.
+        if (!isCodegraphInitialized(projectRoot)) {
+            if (!isCodegraphPeaksLoopManaged(projectRoot)) {
+                return {
+                    refreshed: false,
+                    reason: 'no-codegraph-dir',
+                    note: `auto codegraph refresh skipped: ${CODEGRAPH_DIR_NAME}/ exists without a codegraph.db and is not peaks-loop-managed. Run \`peaks codegraph init\` once to enable post-slice auto-refresh.`,
+                };
+            }
+            const initResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'init', project: projectRoot }), runner);
+            if (initResult.exitCode !== 0) {
+                return {
+                    refreshed: false,
+                    reason: 'index-failed',
+                    note: `auto codegraph refresh self-heal init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}`,
+                };
+            }
+        }
         const invocation = createCodegraphInvocation({ subcommand: 'index', project: projectRoot, quiet: true });
         const result = await executeCodegraphInvocation(invocation, runner);
         if (result.exitCode !== 0) {

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

@@ -42,8 +42,11 @@ export declare function renderCodegraphStructureBlock(files: readonly CodegraphS
  *
  * 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 with peaks-loop marker AND `codegraph.db` →
+ *   skip init/index (fresh), read directly. No redundant re-index on
+ *   every dispatch.
+ * - `.codegraph/` present with peaks-loop marker but NO `codegraph.db`
+ *   (dangling) → init + index (self-heal), then read.
  * - `.codegraph/` present WITHOUT marker (foreign schema) → fail-soft;
  *   never clobber a foreign store.
  *