peaks-loop 4.0.28 → 4.0.30

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.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>;