peaks-loop 4.0.34 → 4.0.36

package/dist/services/context/memory-index-reader.d.ts

@@ -1,8 +1,34 @@
 import type { MemoryIndexEntry } from '../memory/memory-search-service.js';
+/**
+ * Slice 2026-09-09-memory-retrieval: the two tiers the orchestrator
+ * preflight ranks over.
+ *
+ * - `hot`  — standing rules / feedback / decisions. Always eligible.
+ * - `warm` — project / reference memos. Injected only on task relevance.
+ *
+ * `cold` is deep storage and is deliberately NOT surfaced here.
+ */
+export interface MemoryTieredSelection {
+    hot: MemoryIndexEntry[];
+    warm: MemoryIndexEntry[];
+}
 export declare class MemoryIndexReader {
     private readonly projectRoot;
     private cache;
     constructor(projectRoot: string);
+    /**
+     * Flatten the whole index (all tiers, all buckets). Kept for
+     * back-compat with the pre-2026-09-09 callers.
+     */
     loadIfStale(): MemoryIndexEntry[];
+    /**
+     * Slice 2026-09-09-memory-retrieval: read the index as tiers.
+     *
+     * Returns `null` when `.peaks/memory/index.json` is absent or
+     * unreadable — the caller distinguishes "no index" from "index with
+     * zero entries" for its fail-soft reason code. Never throws.
+     */
+    selectTiered(): MemoryTieredSelection | null;
     selectFeedbackLayerA(cap: number): MemoryIndexEntry[];
+    private loadSnapshot;
 }

package/dist/services/context/memory-index-reader.js

@@ -7,24 +7,25 @@ export class MemoryIndexReader {
     constructor(projectRoot) {
         this.projectRoot = projectRoot;
     }
+    /**
+     * Flatten the whole index (all tiers, all buckets). Kept for
+     * back-compat with the pre-2026-09-09 callers.
+     */
     loadIfStale() {
-        const indexPath = join(this.projectRoot, '.peaks', 'memory', 'index.json');
-        if (!existsSync(indexPath))
-            return [];
-        const { mtimeMs } = statSync(indexPath);
-        if (this.cache && this.cache.mtimeMs === mtimeMs)
-            return this.cache.entries;
-        let raw;
-        try {
-            raw = JSON.parse(readFileSync(indexPath, 'utf8'));
-        }
-        catch {
-            this.cache = null;
-            return [];
-        }
-        const entries = flattenIndex(raw);
-        this.cache = { mtimeMs, entries };
-        return entries;
+        return this.loadSnapshot()?.entries ?? [];
+    }
+    /**
+     * Slice 2026-09-09-memory-retrieval: read the index as tiers.
+     *
+     * Returns `null` when `.peaks/memory/index.json` is absent or
+     * unreadable — the caller distinguishes "no index" from "index with
+     * zero entries" for its fail-soft reason code. Never throws.
+     */
+    selectTiered() {
+        const snapshot = this.loadSnapshot();
+        if (snapshot === null)
+            return null;
+        return snapshot.tiers;
     }
     selectFeedbackLayerA(cap) {
         const all = this.loadIfStale();
@@ -33,24 +34,55 @@ export class MemoryIndexReader {
             .filter((e) => LAYER_A_RE.test(e.description))
             .slice(0, Math.max(1, Math.trunc(cap)));
     }
+    loadSnapshot() {
+        const indexPath = join(this.projectRoot, '.peaks', 'memory', 'index.json');
+        try {
+            if (!existsSync(indexPath))
+                return null;
+            const { mtimeMs } = statSync(indexPath);
+            if (this.cache && this.cache.mtimeMs === mtimeMs)
+                return this.cache;
+            const raw = JSON.parse(readFileSync(indexPath, 'utf8'));
+            const tiers = {
+                hot: flattenBucket(raw, 'hot'),
+                warm: flattenBucket(raw, 'warm'),
+            };
+            const entries = [
+                ...tiers.hot,
+                ...tiers.warm,
+                ...flattenBucket(raw, 'cold'),
+            ];
+            this.cache = { mtimeMs, entries, tiers };
+            return this.cache;
+        }
+        catch {
+            // Fail-soft: a missing / unreadable / malformed index degrades to
+            // "no memory available" rather than throwing into a dispatch.
+            this.cache = null;
+            return null;
+        }
+    }
 }
-function flattenIndex(raw) {
+function bucketOf(raw, layer) {
     if (!raw || typeof raw !== 'object')
+        return null;
+    const bucket = raw[layer];
+    return bucket && typeof bucket === 'object'
+        ? bucket
+        : null;
+}
+function flattenBucket(raw, layer) {
+    const bucket = bucketOf(raw, layer);
+    if (!bucket)
         return [];
     const out = [];
-    const obj = raw;
-    for (const layer of ['hot', 'warm', 'cold']) {
-        const bucket = obj[layer];
-        if (!bucket || typeof bucket !== 'object')
+    for (const key of Object.keys(bucket)) {
+        const list = bucket[key];
+        if (!Array.isArray(list))
             continue;
-        for (const k of ['feedback', 'project', 'reference', 'user']) {
-            const list = bucket[k];
-            if (!Array.isArray(list))
-                continue;
-            for (const item of list) {
-                if (item && typeof item === 'object')
-                    out.push(item);
-            }
+        for (const item of list) {
+            if (item && typeof item === 'object')
+                out.push(item);
         }
     }
     return out;

package/dist/services/context/memory-preflight-config.d.ts

@@ -1,9 +1,42 @@
 import type { ProjectPreferences } from '../preferences/preferences-types.js';
 export interface MemoryPreflightConfig {
     readonly enabled: boolean;
+    /**
+     * Back-compat (slice 2026-07-22): the original single budget knob.
+     * Semantics are unchanged — it is the *token* cap, converted to bytes
+     * as `maxTokens * 4` when `maxBytes` is not set. Do NOT drop this key:
+     * existing `.peaks/preferences.json` files set it.
+     */
     readonly maxTokens: number;
+    /** Back-compat: hot-tier item cap fallback when `hotItemCap` is absent. */
     readonly listCap: number;
     readonly contentCacheBytes: number;
+    /** Hard byte cap on the composed block. Defaults to `maxTokens * 4`. */
+    readonly maxBytes: number;
+    /** Max hot (standing rule / feedback) items injected. Default 10. */
+    readonly hotItemCap: number;
+    /** Max warm (project / reference) items injected; 0 disables warm. Default 4. */
+    readonly warmItemCap: number;
+    /**
+     * Warm relevance gate: minimum number of distinct task-title tokens
+     * (length >= 4, stopwords removed) that must literally occur in the memo
+     * text before it is warm-eligible. 1 (default) means "at least one task
+     * word appears in the memo"; raise it to tighten the gate. Hot entries
+     * ignore this gate — they are always eligible.
+     */
+    readonly warmMinTokenHits: number;
+    /**
+     * Soft wall-clock budget (ms) for the whole selection step. When exceeded
+     * the preflight degrades to hot-only (or unranked hot) rather than
+     * blocking a dispatch. 0 forces the hot-only path deterministically.
+     */
+    readonly selectionTimeBudgetMs: number;
+    /**
+     * Gate for inlining memo *bodies* (via `cacheMemoContent`). Off by
+     * default: the preflight emits a compact index and the sub-agent drills
+     * down with `Read` against `sourcePath`.
+     */
+    readonly includeBodies: boolean;
 }
 /**
  * Loose input type for `resolveMemoryPreflightConfig`. Accepts either a

package/dist/services/context/memory-preflight-config.js

@@ -3,23 +3,53 @@ const DEFAULTS = Object.freeze({
     maxTokens: 1200,
     listCap: 12,
     contentCacheBytes: 6000,
+    hotItemCap: 10,
+    warmItemCap: 4,
+    warmMinTokenHits: 1,
+    selectionTimeBudgetMs: 200,
+    includeBodies: false,
 });
 const LIST_CAP_MIN = 1;
 const LIST_CAP_MAX = 50;
+const ITEM_CAP_MAX = 100;
 function asFiniteInt(value, fallback) {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0
         ? Math.trunc(value)
         : fallback;
 }
+function asFiniteNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? value
+        : fallback;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
 export function resolveMemoryPreflightConfig(prefs) {
     const m = prefs.memoryPreflight ?? {};
     const listCapRaw = asFiniteInt(m.listCap, DEFAULTS.listCap);
+    const listCap = clamp(listCapRaw, LIST_CAP_MIN, LIST_CAP_MAX);
+    const maxTokens = m.maxTokens && m.maxTokens > 0 ? m.maxTokens : DEFAULTS.maxTokens;
     return {
         enabled: m.enabled === false ? false : DEFAULTS.enabled,
-        maxTokens: m.maxTokens && m.maxTokens > 0 ? m.maxTokens : DEFAULTS.maxTokens,
-        listCap: Math.min(LIST_CAP_MAX, Math.max(LIST_CAP_MIN, listCapRaw)),
+        maxTokens,
+        listCap,
         contentCacheBytes: m.contentCacheBytes && m.contentCacheBytes > 0
             ? m.contentCacheBytes
             : DEFAULTS.contentCacheBytes,
+        // `maxBytes` wins when explicitly set; otherwise the legacy token cap
+        // is preserved verbatim (maxTokens * 4 bytes).
+        maxBytes: m.maxBytes && m.maxBytes > 0 ? Math.trunc(m.maxBytes) : maxTokens * 4,
+        // `hotItemCap` falls back to the legacy `listCap` only when the caller
+        // explicitly set `listCap`; otherwise the tiered default (10) applies.
+        hotItemCap: clamp(m.hotItemCap !== undefined
+            ? asFiniteInt(m.hotItemCap, DEFAULTS.hotItemCap)
+            : m.listCap !== undefined
+                ? listCap
+                : DEFAULTS.hotItemCap, LIST_CAP_MIN, ITEM_CAP_MAX),
+        warmItemCap: clamp(asFiniteInt(m.warmItemCap, DEFAULTS.warmItemCap), 0, ITEM_CAP_MAX),
+        warmMinTokenHits: clamp(asFiniteInt(m.warmMinTokenHits, DEFAULTS.warmMinTokenHits), 1, ITEM_CAP_MAX),
+        selectionTimeBudgetMs: clamp(asFiniteNumber(m.selectionTimeBudgetMs, DEFAULTS.selectionTimeBudgetMs), 0, 10_000),
+        includeBodies: m.includeBodies === true ? true : DEFAULTS.includeBodies,
     };
 }

package/dist/services/context/memory-preflight-service.d.ts

@@ -2,11 +2,22 @@ import { type MemoryPreflightPrefsInput } from './memory-preflight-config.js';
 export interface MemoryPreflightResult {
     available: boolean;
     block?: string;
+    /** Back-compat: total items emitted (hot + warm). */
     feedbackListItems?: number;
     cachedItemCount?: number;
     reason?: string;
     truncated?: boolean | undefined;
     droppedCount?: number | undefined;
+    /** Slice 2026-09-09: hot items emitted. */
+    hotSelected?: number | undefined;
+    /** Slice 2026-09-09: warm items emitted. */
+    warmSelected?: number | undefined;
+    /** Slice 2026-09-09: bytes of the emitted block (utf8). */
+    bytesEmitted?: number | undefined;
+    /** Slice 2026-09-09: true when ANY budget (items / bytes / time) cut content. */
+    budgetTruncated?: boolean | undefined;
+    /** Slice 2026-09-09: true when the soft selection time budget was hit. */
+    timedOut?: boolean | undefined;
 }
 export declare class MemoryPreflightService {
     private readonly reader;
@@ -15,5 +26,13 @@ export declare class MemoryPreflightService {
     private readonly cachedMemoContents;
     constructor(projectRoot: string, prefs: MemoryPreflightPrefsInput);
     cacheMemoContent(path: string, content: string): void;
-    fetchBlock(_taskTitle: string): Promise<MemoryPreflightResult>;
+    fetchBlock(taskTitle: string): Promise<MemoryPreflightResult>;
+    private selectAndCompose;
 }
+/**
+ * Slice 2026-09-09-memory-retrieval: the query the dispatch site feeds
+ * `fetchBlock`. The bare role ("rd") carries almost no relevance signal,
+ * so the first line of the task brief is appended (truncated) to give the
+ * fuzzy kernel something to rank against. Pure and fail-soft.
+ */
+export declare function deriveMemoryQuery(role: string, taskBody: string | undefined): string;

package/dist/services/context/memory-preflight-service.js

@@ -3,25 +3,81 @@
  * "Orchestrator Memory Preflight" slice (see
  * docs/superpowers/specs/2026-07-22-orchestrator-memory-preflight-design.md).
  *
+ * Slice 2026-09-09-memory-retrieval (this revision) makes the preflight
+ * task-relevant and tiered:
+ *   - selection is ranked against `taskTitle` with the deterministic fuzzy
+ *     kernel (no network, no embeddings);
+ *   - hot entries (standing rules / feedback) are ALWAYS eligible, ranked
+ *     so the most relevant lead; warm entries (project / reference) are
+ *     gated on relevance and capped well below hot;
+ *   - three independent budgets are enforced — max items, max bytes, and a
+ *     soft wall-clock budget for the selection step;
+ *   - the emitted block stays a compact index (name + path + one-line) so
+ *     the sub-agent drills down with `Read` on demand instead of receiving
+ *     memo bodies wholesale (body inlining is opt-in via `includeBodies`).
+ *
  * Consumes:
  *   - resolveMemoryPreflightConfig (Task 1) — merged defaults + per-project overlay
- *   - MemoryIndexReader (Task 3)            — reads .peaks/memory/index.json + layer=A filter
- *   - MemoryLruCache (Task 2)               — constructed for capacity parity, but NOT used
- *                                            for memo content (see deviation note below)
+ *   - MemoryIndexReader (Task 3)            — reads .peaks/memory/index.json
+ *   - fuzzyMatchWithKey                     — deterministic relevance kernel
  *   - truncateToCap                         — byte-cap truncation of the composed block
  *
- * Deviation from brief — controller-accepted (pre-task 4):
- *   The brief mandated use of `MemoryLruCache` for memo content caching. The
- *   orchestrator dispatch flow only ever has at most a handful of explicit
- *   `cacheMemoContent` calls per task (typically 0-3), and ordering / explicit
- *   invalidation is preferred over LRU eviction by recency. To keep the
- *   semantic obvious and the byte budget check trivial, this implementation
- *   uses a plain `Map<path, body>` for memo path -> body content. The
- *   `MemoryLruCache` class remains as a separate, reusable LRU primitive
- *   (Task 2) and is not consumed by this service.
+ * Fail-soft contract: any selection error returns `available: false` with a
+ * reason; it never throws and never blocks a dispatch.
  */
+import { performance } from 'node:perf_hooks';
+import { fuzzyMatchWithKey } from '../fuzzy-matching/fuzzy-match-service.js';
 import { MemoryIndexReader } from './memory-index-reader.js';
 import { resolveMemoryPreflightConfig, } from './memory-preflight-config.js';
+/** Function words carry no selection signal. */
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'with', 'from', 'that', 'this', 'not', 'are', 'was',
+    'but', 'you', 'all', 'any', 'can', 'has', 'its', 'our', 'out', 'use', 'via',
+    'per', 'into', 'when', 'then', 'than', 'they', 'their', 'should', 'must',
+]);
+/**
+ * Tokens shorter than 4 chars are too promiscuous for literal containment
+ * ("add" is a substring of "padding"), so they rank but do not gate.
+ */
+const MIN_TOKEN_LENGTH = 4;
+const CJK_RE = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
+function queryTokens(query) {
+    const seen = new Set();
+    const out = [];
+    for (const raw of query.toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+        if (raw.length < MIN_TOKEN_LENGTH || STOPWORDS.has(raw) || seen.has(raw))
+            continue;
+        seen.add(raw);
+        out.push(raw);
+    }
+    return out;
+}
+/**
+ * Absolute relevance gate: does the token literally occur in the entry?
+ *
+ * The fuzzy kernel's score is normalized per batch (best match = 1.0), so
+ * it cannot distinguish a strong match from the best of a bad lot — an
+ * absolute check is required for the warm gate. CJK titles have no word
+ * boundaries, so those tokens fall back to 2-char gram overlap.
+ */
+function tokenHits(text, tokens) {
+    let hits = 0;
+    for (const token of tokens) {
+        if (text.includes(token)) {
+            hits += 1;
+            continue;
+        }
+        if (!CJK_RE.test(token))
+            continue;
+        for (let i = 0; i + 2 <= token.length; i += 1) {
+            if (text.includes(token.slice(i, i + 2))) {
+                hits += 1;
+                break;
+            }
+        }
+    }
+    return hits;
+}
 function truncateToCap(text, capBytes) {
     if (Buffer.byteLength(text, 'utf8') <= capBytes) {
         return { text, truncated: false };
@@ -48,44 +104,155 @@ export class MemoryPreflightService {
         }
         this.cachedMemoContents.set(path, content);
     }
-    async fetchBlock(_taskTitle) {
+    async fetchBlock(taskTitle) {
         if (!this.config.enabled)
             return { available: false, reason: 'DISABLED' };
-        const selected = this.reader.selectFeedbackLayerA(this.config.listCap);
-        if (selected.length === 0) {
-            const any = this.reader.loadIfStale();
-            if (any.length === 0)
-                return { available: false, reason: 'MEMORY_INDEX_MISSING' };
-            return { available: false, reason: 'NO_FEEDBACK_LAYER_A' };
+        try {
+            return this.selectAndCompose(taskTitle ?? '');
+        }
+        catch (err) {
+            // Fail-soft: a selection failure must never block a dispatch.
+            return {
+                available: false,
+                reason: `SELECTION_ERROR: ${err.message ?? String(err)}`,
+            };
+        }
+    }
+    selectAndCompose(taskTitle) {
+        const startedAt = performance.now();
+        const tiered = this.reader.selectTiered();
+        if (tiered === null)
+            return { available: false, reason: 'MEMORY_INDEX_MISSING' };
+        // Rank the union once (one fuzzy pass per token over all candidates),
+        // then split by tier — cheaper than ranking each tier separately and
+        // order-preserving for both.
+        const hotSet = new Set(tiered.hot);
+        const tokens = queryTokens(taskTitle);
+        const rankedAll = rankByRelevance(taskTitle, [...tiered.hot, ...tiered.warm]);
+        // Hot is ALWAYS eligible — ranked so the most task-relevant lead, with
+        // unmatched standing rules appended in index order.
+        const hotRanked = rankedAll.filter((r) => hotSet.has(r.entry));
+        const hotSelected = hotRanked.slice(0, this.config.hotItemCap);
+        let timedOut = performance.now() - startedAt >= this.config.selectionTimeBudgetMs;
+        const warmSelected = [];
+        let warmEligibleCount = 0;
+        if (!timedOut && this.config.warmItemCap > 0) {
+            const warmRanked = rankedAll
+                .filter((r) => !hotSet.has(r.entry))
+                .filter((r) => tokenHits(`${r.entry.name} ${r.entry.description}`.toLowerCase(), tokens) >=
+                this.config.warmMinTokenHits);
+            warmEligibleCount = warmRanked.length;
+            for (const candidate of warmRanked) {
+                if (warmSelected.length >= this.config.warmItemCap)
+                    break;
+                if (performance.now() - startedAt >=
+                    this.config.selectionTimeBudgetMs) {
+                    timedOut = true;
+                    break;
+                }
+                warmSelected.push(candidate);
+            }
+        }
+        if (hotSelected.length === 0 && warmSelected.length === 0) {
+            return { available: false, reason: 'NO_RELEVANT_MEMORY' };
+        }
+        const sections = [];
+        if (hotSelected.length > 0) {
+            sections.push('### Standing memory (always applied)');
+            for (const r of hotSelected)
+                sections.push(renderEntry(r.entry));
+        }
+        if (warmSelected.length > 0) {
+            sections.push('### Task-relevant memory (drill down with Read)');
+            for (const r of warmSelected)
+                sections.push(renderEntry(r.entry));
         }
-        const listLines = selected
-            .map((e) => `- * ${e.name}\n    Path: ${e.sourcePath}\n    One-line: ${summarize(e.description)}`)
-            .join('\n');
         let tail = '\n';
         let cachedCount = 0;
-        if (this.cachedMemoContents.size > 0) {
-            const sections = [];
+        if (this.config.includeBodies && this.cachedMemoContents.size > 0) {
+            const bodies = [];
             for (const [path, body] of this.cachedMemoContents) {
-                sections.push(`### ${path}\n\n${body}`);
+                bodies.push(`### ${path}\n\n${body}`);
                 cachedCount += 1;
             }
-            tail = `\n\n## Requested memory details:\n${sections.join('\n\n')}\n`;
+            tail = `\n\n## Requested memory details:\n${bodies.join('\n\n')}\n`;
         }
         const header = '## Project memory relevant to this task\n';
-        const composed = `${header}${listLines}${tail}`;
-        const capBytes = Math.max(64, this.config.maxTokens * 4);
-        const { text, truncated } = truncateToCap(composed, capBytes);
-        const droppedCount = truncated ? selected.length - countItemsInBlock(text) : 0;
+        const composed = `${header}${sections.join('\n')}\n${tail}`;
+        const { text, truncated } = truncateToCap(composed, this.config.maxBytes);
+        const selectedCount = hotSelected.length + warmSelected.length;
+        const droppedByItemCap = hotRanked.length - hotSelected.length + (warmEligibleCount - warmSelected.length);
+        const droppedByBytes = truncated
+            ? Math.max(0, selectedCount - countItemsInBlock(text))
+            : 0;
+        const droppedCount = droppedByItemCap + droppedByBytes;
         return {
             available: true,
             block: text,
-            feedbackListItems: selected.length,
+            feedbackListItems: selectedCount,
             cachedItemCount: cachedCount,
+            hotSelected: hotSelected.length,
+            warmSelected: warmSelected.length,
+            bytesEmitted: Buffer.byteLength(text, 'utf8'),
+            budgetTruncated: truncated || droppedByItemCap > 0 || timedOut,
+            timedOut,
             truncated,
             droppedCount: droppedCount > 0 ? droppedCount : undefined,
         };
     }
 }
+/**
+ * Slice 2026-09-09-memory-retrieval: the query the dispatch site feeds
+ * `fetchBlock`. The bare role ("rd") carries almost no relevance signal,
+ * so the first line of the task brief is appended (truncated) to give the
+ * fuzzy kernel something to rank against. Pure and fail-soft.
+ */
+export function deriveMemoryQuery(role, taskBody) {
+    const firstLine = (taskBody ?? '').split('\n', 1)[0]?.trim() ?? '';
+    const trimmed = firstLine.length > 160 ? firstLine.slice(0, 160) : firstLine;
+    return trimmed === '' ? role : `${role} ${trimmed}`;
+}
+/**
+ * Rank entries against the task title with the deterministic fuzzy kernel.
+ *
+ * The kernel is invoked once PER TOKEN rather than once for the whole
+ * title: a whole-title query is a single fzf subsequence and realistic
+ * task titles match almost nothing that way (measured: 0 warm hits on
+ * the real 131-entry warm tier). Per-token accumulation keeps the kernel
+ * deterministic and gives a graded score — entries matching more task
+ * words, more strongly, rank higher.
+ *
+ * Every entry is returned: matched entries lead by score desc, unmatched
+ * entries follow in index order with score 0 — this is what keeps hot
+ * entries "always eligible". An empty/token-less task title degrades to
+ * index order.
+ */
+function rankByRelevance(query, entries) {
+    if (entries.length === 0)
+        return [];
+    const tokens = queryTokens(query);
+    if (tokens.length === 0) {
+        return entries.map((entry) => ({ entry, score: 0 }));
+    }
+    const accumulated = new Map();
+    for (const token of tokens) {
+        const matches = fuzzyMatchWithKey(token, entries, {
+            keyFn: (e) => `${e.name} ${e.description}`,
+            limit: entries.length,
+            caseSensitive: false,
+        });
+        for (const match of matches) {
+            accumulated.set(match.item, (accumulated.get(match.item) ?? 0) + match.score);
+        }
+    }
+    // Array#sort is stable (ES2019), so equal scores keep index order.
+    return entries
+        .map((entry) => ({ entry, score: accumulated.get(entry) ?? 0 }))
+        .sort((a, b) => b.score - a.score);
+}
+function renderEntry(entry) {
+    return `- * ${entry.name}\n    Path: ${entry.sourcePath}\n    One-line: ${summarize(entry.description)}`;
+}
 function summarize(description) {
     // Drop the <!-- peaks-feedback-promoted: layer=A --> marker, take the next 1 line.
     const cleaned = description.replace(/<!--[^>]*-->/g, '').trim();

package/dist/services/context/summary-view.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `--summary` — bounded, additive views of large CLI envelopes.
+ *
+ * Slice 2026-09-10-context-audit-and-discipline (Slice B, part 1).
+ *
+ * Rationale (measured, session 2026-09-07-session-245530): dumping a full
+ * `peaks memory reindex --json` array four times cost ≈ 160 KB ≈ 40K tokens
+ * of orchestrator context — roughly 4% of a 1M window for ONE command
+ * repeated. The default envelopes stay exactly as they are (back-compat);
+ * `--summary` is an OPT-IN view that keeps counts + names-of-first-N and
+ * drops the per-entry bodies, which remain on disk and are re-readable with
+ * the full command. No information is destroyed — only the in-context copy
+ * shrinks.
+ *
+ * Byte bound: every summary object is passed through `fitSummaryToBytes`,
+ * which shrinks string arrays (longest first) until the JSON serialization is
+ * ≤ `SUMMARY_DATA_MAX_BYTES` (2 KB minus a small envelope reserve, so the
+ * PRINTED envelope stays ≤ `SUMMARY_MAX_BYTES`). Scalars are never touched,
+ * so counts and paths stay exact.
+ */
+/** Hard ceiling for the PRINTED `--summary` envelope, in UTF-8 bytes. */
+export declare const SUMMARY_MAX_BYTES = 2048;
+/**
+ * Reserve for the envelope wrapper (`ok`/`command`/`warnings`/`nextActions`/
+ * error fields) that the CLI adds around `data`. The builders cap `data` at
+ * `SUMMARY_DATA_MAX_BYTES` so the whole printed envelope stays ≤ 2 KB.
+ */
+export declare const SUMMARY_ENVELOPE_RESERVE_BYTES = 512;
+/** Cap applied to the summary `data` object itself (pretty-printed size). */
+export declare const SUMMARY_DATA_MAX_BYTES: number;
+/** Per-name character cap — a name is a label, not a document. */
+export declare const SUMMARY_NAME_MAX_CHARS = 120;
+/** How many names each command asks for before the byte fitter trims. */
+export declare const SUMMARY_INITIAL_NAMES = 40;
+/** A bounded `{count, names}` view: `count` is the true total, `names` a prefix. */
+export interface BoundedNames {
+    readonly count: number;
+    readonly names: readonly string[];
+}
+/**
+ * Build a `{count, names}` view. `count` is always the full length; `names`
+ * carries the first `SUMMARY_INITIAL_NAMES` (clipped) entries — the byte
+ * fitter may trim further.
+ */
+export declare function boundedNames(names: readonly string[]): BoundedNames;
+/**
+ * Shrink `data` (in place on a clone) until its JSON form fits `maxBytes`.
+ *
+ * Algorithm: repeatedly find the LONGEST nested array and drop its last
+ * element. Scalars are never modified, so `count` fields stay truthful; the
+ * `names` arrays simply show fewer names. Returns the input unchanged when it
+ * already fits or when there is no array left to trim.
+ */
+export declare function fitSummaryToBytes<T extends Record<string, unknown>>(data: T, maxBytes?: number): T;