peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/context/headroom-client.js

@@ -0,0 +1,117 @@
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MODEL = 'claude-sonnet-4-5-20250929';
+// Approximate 1 token = 4 bytes for English text. This is a rough
+// heuristic; the SDK does its own tokenization internally.
+const BYTES_PER_TOKEN = 4;
+/**
+ * Compress a prompt via headroom-ai. The `fallback: true` option is
+ * non-negotiable: if the proxy daemon is unavailable, the SDK returns
+ * `result.compressed = false` and the original messages; we surface
+ * that as `HEADROOM_UNAVAILABLE` warning + G7 metadata-only fallback.
+ */
+export async function compressPrompt(prompt, mode = 'balanced') {
+    const originalSize = Buffer.byteLength(prompt, 'utf8');
+    let compressFn = null;
+    try {
+        const mod = await import('headroom-ai');
+        if (typeof mod.compress === 'function') {
+            compressFn = mod.compress;
+        }
+    }
+    catch {
+        return fallback(originalSize, mode);
+    }
+    if (compressFn === null) {
+        return fallback(originalSize, mode);
+    }
+    const messages = [
+        { role: 'user', content: prompt }
+    ];
+    const opts = {
+        model: DEFAULT_MODEL,
+        timeout: DEFAULT_TIMEOUT_MS,
+        fallback: true, // CRITICAL: return original messages if proxy is down
+        retries: 1
+    };
+    if (mode === 'aggressive') {
+        opts.tokenBudget = Math.max(1, Math.floor(originalSize * 0.20 / BYTES_PER_TOKEN));
+    }
+    else if (mode === 'conservative') {
+        opts.tokenBudget = Math.max(1, Math.floor(originalSize * 0.70 / BYTES_PER_TOKEN));
+    }
+    else {
+        // balanced: target ~60% reduction
+        opts.tokenBudget = Math.max(1, Math.floor(originalSize * 0.40 / BYTES_PER_TOKEN));
+    }
+    let result;
+    try {
+        result = await compressFn(messages, opts);
+    }
+    catch {
+        return fallback(originalSize, mode);
+    }
+    if (result.compressed === false) {
+        return {
+            compressed: false,
+            originalSize,
+            compressedSize: originalSize,
+            compressionRatio: 1.0,
+            mode,
+            warning: 'HEADROOM_UNAVAILABLE',
+            compressedPrompt: null,
+            tokensSaved: 0
+        };
+    }
+    const compressedContent = extractContent(result.messages);
+    if (compressedContent === null) {
+        return fallback(originalSize, mode);
+    }
+    const compressedSize = Buffer.byteLength(compressedContent, 'utf8');
+    return {
+        compressed: true,
+        originalSize,
+        compressedSize,
+        compressionRatio: compressedSize / originalSize,
+        mode,
+        warning: null,
+        compressedPrompt: compressedContent,
+        tokensSaved: result.tokensSaved ?? 0
+    };
+}
+function fallback(originalSize, mode) {
+    return {
+        compressed: false,
+        originalSize,
+        compressedSize: originalSize,
+        compressionRatio: 1.0,
+        mode,
+        warning: 'HEADROOM_UNAVAILABLE',
+        compressedPrompt: null,
+        tokensSaved: 0
+    };
+}
+function extractContent(messages) {
+    if (!Array.isArray(messages) || messages.length === 0) {
+        return null;
+    }
+    const last = messages[messages.length - 1];
+    if (typeof last.content === 'string') {
+        return last.content;
+    }
+    return null;
+}
+/**
+ * Bridge interface: when `--use-headroom` is set, share entries written
+ * via `peaks sub-agent share` MAY also flow through headroom's
+ * `SharedContext`. Slice #010 implements a peak-internal shared channel
+ * (see `shared-channel.ts`); the headroom-side `SharedContext` is a
+ * separate concept that future slices can layer on. For now this
+ * function is a stub that returns the peak-internal channel ID, which
+ * is enough to demonstrate the bridge contract.
+ */
+export function buildSharedContextBridge(batchId) {
+    return {
+        peakChannelId: batchId,
+        headroomContextId: `headroom-ctx-${batchId}`
+    };
+}

package/dist/services/context/headroom-fetcher.d.ts

@@ -0,0 +1,6 @@
+import type { DocFetcher } from './doc-retriever.js';
+export interface HeadroomFetcherOptions {
+    readonly cacheDir: string;
+    readonly remoteFetcher?: DocFetcher;
+}
+export declare function createHeadroomFetcher(opts: HeadroomFetcherOptions): DocFetcher;

package/dist/services/context/headroom-fetcher.js

@@ -0,0 +1,28 @@
+/**
+ * Production DocFetcher. Uses existing headroom-ai dependency for remote
+ * fetch; local cache (per-session, per-dep markdown) preferred when version matches.
+ *
+ * Hard constraint H2 (locked version): never returns a doc whose version
+ * differs from the requested locked version.
+ *
+ * Cache path (per pre-flight fix #2): .peaks/_runtime/<sid>/doc-cache/<dep>@<version>.md
+ *   - Per-session (NOT cross-session shared at ~/.peaks/cache/docs/)
+ *   - Reason: spec §4.1 keeps everything under _runtime which is gitignored
+ *     and ephemeral; cross-session caching is a future-slice optimization.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export function createHeadroomFetcher(opts) {
+    return async (dep, version) => {
+        const cachePath = join(opts.cacheDir, `${dep}@${version}.md`);
+        try {
+            const content = await readFile(cachePath, 'utf8');
+            return { version, excerpt: content };
+        }
+        catch {
+            if (!opts.remoteFetcher)
+                return null;
+            return opts.remoteFetcher(dep, version);
+        }
+    };
+}

package/dist/services/context/headroom-prefs.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Headroom preferences resolver (slice 2026-06-14-fzf-headroom-rollout).
+ *
+ * Pure functions that turn `ProjectPreferences.headroom.*` + CLI
+ * overrides into a single decision the dispatch path can act on.
+ * No IO. No side effects. Easy to test in isolation.
+ *
+ * Two distinct decisions:
+ *  1. `resolveHeadroomOptions` — should we compress the dispatch prompt?
+ *     Used by `peaks sub-agent dispatch`. Returns one of:
+ *       - `{ mode: <m>, blocked: null }`   → compress with mode <m>
+ *       - `{ mode: null, blocked: null }`  → skip compression (no --use-headroom)
+ *       - `{ mode: null, blocked: 'HEADROOM_DISABLED_BY_PREFERENCE' }` → hard fail
+ *  2. `shouldCompressResults` — should we compress search-result text?
+ *     Used by `peaks memory search` / `peaks retrospective search`.
+ *     Non-blocking: returns a `reason` instead of a `blocked` code.
+ *
+ * Precedence (dispatch):
+ *   1. `headroom.enabled = false`  → hard block (regardless of --use-headroom)
+ *   2. `headroom.enabled = true` + `--headroom-mode <m>` → use <m>
+ *   3. `headroom.enabled = true` + `--use-headroom` (no --headroom-mode) →
+ *      use `perTouchpoint.subAgentDispatch` (preferred) else `defaultMode`
+ *   4. no `--use-headroom` → mode = null (compression skipped)
+ */
+import type { HeadroomMode, ProjectPreferences } from '../preferences/preferences-types.js';
+export type HeadroomTouchpoint = keyof ProjectPreferences['headroom']['perTouchpoint'];
+export type HeadroomBlockCode = 'HEADROOM_DISABLED_BY_PREFERENCE';
+export interface ResolvedHeadroomOptions {
+    /** The mode to use for compression, or null if not compressing. */
+    readonly mode: HeadroomMode | null;
+    /** Hard-block reason; null when compression is allowed (or simply not requested). */
+    readonly blocked: HeadroomBlockCode | null;
+}
+export interface ResolveCliOverrides {
+    readonly useHeadroom: boolean;
+    readonly headroomMode?: string;
+}
+export declare function isHeadroomMode(value: string | undefined): value is HeadroomMode;
+export declare function resolveHeadroomOptions(prefs: ProjectPreferences['headroom'], cliOverrides: ResolveCliOverrides): ResolvedHeadroomOptions;
+export interface ShouldCompressDecision {
+    readonly compress: boolean;
+    readonly mode: HeadroomMode;
+    /** Non-null reason if not compressing. */
+    readonly reason: 'DISABLED' | 'BELOW_THRESHOLD' | null;
+}
+export declare function shouldCompressResults(prefs: ProjectPreferences['headroom'], joinedBytes: number, touchpoint: HeadroomTouchpoint): ShouldCompressDecision;

package/dist/services/context/headroom-prefs.js

@@ -0,0 +1,34 @@
+const VALID_MODES = new Set([
+    'balanced',
+    'aggressive',
+    'conservative'
+]);
+export function isHeadroomMode(value) {
+    return typeof value === 'string' && VALID_MODES.has(value);
+}
+export function resolveHeadroomOptions(prefs, cliOverrides) {
+    // (1) Hard block when preference disables headroom entirely.
+    if (cliOverrides.useHeadroom === true && prefs.enabled === false) {
+        return { mode: null, blocked: 'HEADROOM_DISABLED_BY_PREFERENCE' };
+    }
+    // (4) No --use-headroom → no compression.
+    if (cliOverrides.useHeadroom !== true) {
+        return { mode: null, blocked: null };
+    }
+    // (2) CLI --headroom-mode wins (even if preference is set, CLI overrides).
+    if (isHeadroomMode(cliOverrides.headroomMode)) {
+        return { mode: cliOverrides.headroomMode, blocked: null };
+    }
+    // (3) Preference path: perTouchpoint > defaultMode > 'balanced'.
+    const touchpointMode = prefs.perTouchpoint.subAgentDispatch;
+    return { mode: touchpointMode ?? prefs.defaultMode, blocked: null };
+}
+export function shouldCompressResults(prefs, joinedBytes, touchpoint) {
+    if (prefs.enabled === false) {
+        return { compress: false, mode: prefs.defaultMode, reason: 'DISABLED' };
+    }
+    if (joinedBytes < prefs.compressMinBytes) {
+        return { compress: false, mode: prefs.perTouchpoint[touchpoint], reason: 'BELOW_THRESHOLD' };
+    }
+    return { compress: true, mode: prefs.perTouchpoint[touchpoint], reason: null };
+}

package/dist/services/context/ide-detect.d.ts

@@ -0,0 +1,4 @@
+export type IdeKind = 'claude-code' | 'trae' | 'opencode' | 'unknown';
+export declare const IDE_KINDS: readonly IdeKind[];
+export declare function isIdeKind(value: string): value is IdeKind;
+export declare function detectIdeFromEnv(env?: NodeJS.ProcessEnv): IdeKind;

package/dist/services/context/ide-detect.js

@@ -0,0 +1,24 @@
+export const IDE_KINDS = [
+    'claude-code',
+    'trae',
+    'opencode',
+    'unknown'
+];
+export function isIdeKind(value) {
+    return IDE_KINDS.includes(value);
+}
+export function detectIdeFromEnv(env = process.env) {
+    if (typeof env['CLAUDE_CODE_ENTRYPOINT'] === 'string' && env['CLAUDE_CODE_ENTRYPOINT'].length > 0) {
+        return 'claude-code';
+    }
+    if (typeof env['CLAUDE_SESSION_ID'] === 'string' && env['CLAUDE_SESSION_ID'].length > 0) {
+        return 'claude-code';
+    }
+    if (typeof env['TRAE_CLI'] === 'string' && env['TRAE_CLI'].length > 0) {
+        return 'trae';
+    }
+    if (typeof env['OPENCODE'] === 'string' && env['OPENCODE'].length > 0) {
+        return 'opencode';
+    }
+    return 'unknown';
+}

package/dist/services/context/index.d.ts

@@ -0,0 +1,7 @@
+export { collectContext, type CollectInput } from './collector.js';
+export { retrieveDocs, type DocFetcher, type FetcherPayload, type RetrieveOptions } from './doc-retriever.js';
+export { tokenize } from './tokenizer.js';
+export { render, type RenderInput } from './renderer.js';
+export { ContextJsonSchema } from './context-schema.js';
+export { buildContext, type BuildInput } from './context-builder.js';
+export type { ContextJson, Audience, DepsMode, FileKind, CollectedFile, GitStatus, MemoryEntry, DepInfo, DocSection, FetchedDoc, SkippedDoc, TokenizedItem, CollectorOutput, DocRetrieverOutput, TokenizerOutput, RendererOutput, } from './types.js';

package/dist/services/context/index.js

@@ -0,0 +1,6 @@
+export { collectContext } from './collector.js';
+export { retrieveDocs } from './doc-retriever.js';
+export { tokenize } from './tokenizer.js';
+export { render } from './renderer.js';
+export { ContextJsonSchema } from './context-schema.js';
+export { buildContext } from './context-builder.js';

package/dist/services/context/main-session-monitor.d.ts

@@ -0,0 +1,86 @@
+/**
+ * v2.11.0 Group F (Tier 9) — D6: main-session context window monitor.
+ *
+ * Per `.peaks/memory/2026-06-26-v2-11-main-session-context-monitor.md`:
+ *
+ *   D6.a — IDE detection (`peaks ide detect --json`); env-var fallback.
+ *   D6.b — Main-session thresholds (50% warn / 75% user red line / 90% emergency)
+ *   D6.c — IDE-dependent trigger (claude-code → /compact; else LLM self-compress)
+ *   D6.d — Always log; never silently skip
+ *   D6.e — Do NOT auto-compact mid-tool-call-batch (in-flight deferral)
+ *   D6.f — Complements Step N periodic checkpoint (soft signal vs hard signal)
+ *
+ * Distinct from G7-G9 (sub-agent dispatch prompt governance). Same
+ * numbers, different scope. Extends `src/services/context/threshold.ts`
+ * rather than duplicating (D6.h).
+ *
+ * Karpathy §2: this module is the only place that decides
+ * "main-session context threshold" — the LLM-side caller probes via
+ * `evaluateMainSessionThreshold()` and `pickMainSessionTrigger()`.
+ * No inline `promptSize / 256K > 0.75` checks scattered across
+ * SKILL.md or other services.
+ */
+import { type IdeKind } from './ide-detect.js';
+export type MainSessionTier = 'ok' | 'soft-warn' | 'near-limit' | 'emergency';
+export declare const MAIN_SESSION_THRESHOLD_RATIOS: {
+    readonly [K in MainSessionTier]: number;
+};
+export type MainSessionTrigger = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'soft-warn';
+    readonly promptSize: number;
+    readonly ratio: number;
+} | {
+    readonly kind: 'compact';
+    readonly ide: IdeKind;
+    readonly path: 'ide-native' | 'llm-self-compress';
+    readonly promptSize: number;
+    readonly ratio: number;
+    readonly code: 'CONTEXT_NEAR_LIMIT' | 'PROMPT_EMERGENCY';
+} | {
+    readonly kind: 'defer';
+    readonly reason: 'in-flight-batch' | 'unsupported-ide';
+};
+export interface MainSessionEvaluation {
+    readonly tier: MainSessionTier;
+    readonly ratio: number;
+    readonly bytesUsed: number;
+    readonly capacityBytes: number;
+    readonly warnings: readonly string[];
+}
+/**
+ * Threshold check. Pure function (no IO). `capacityBytes` is injectable
+ * for tests and future per-IDE capacity overrides. Defaults to the
+ * G9 256K proxy (matches G9 for cognitive continuity).
+ *
+ * @deprecated Slice 2026-07-02-auto-compact-zero-pause: the
+ * 50/75/90 tier thresholds pre-date the v2.13.0 auto-compact
+ * design. The authoritative tier table for triggering compaction
+ * now lives in `evaluateCompactTrigger` (auto-compact-orchestrator.ts)
+ * with the 0.85 pre-compact / 0.95 red-line thresholds. New
+ * callers should call `evaluateCompactTrigger(ratio)` directly.
+ * This function is retained because legacy `peaks context check
+ * --prompt-size` still emits its 4-tier envelope for callers that
+ * need the soft signal (e.g. statusline display). Migration is
+ * scheduled for v2.15.0; the @deprecated tag flips callers'
+ * eslint warnings so the migration is mechanical.
+ */
+export declare function evaluateMainSessionThreshold(promptSize: number, capacityBytes?: number): MainSessionEvaluation;
+export interface InFlightBatchProbe {
+    readonly hasInFlightBatch: boolean;
+    readonly sharedChannelEntries: number;
+}
+export declare function pickMainSessionTrigger(opts: {
+    promptSize: number;
+    ide?: IdeKind | undefined;
+    capacityBytes?: number | undefined;
+    inFlightBatch?: InFlightBatchProbe | undefined;
+    /** Injectable env for IDE detection (test seam). */
+    env?: NodeJS.ProcessEnv | undefined;
+}): MainSessionTrigger;
+/**
+ * One-line audit log entry. Pure formatter; the LLM / CLI appends to
+ * `.peaks/_runtime/<sessionId>/txt/auto-decisions.md`. Matches D6.d.
+ */
+export declare function formatMainSessionTriggerLogLine(trigger: MainSessionTrigger, contextId: string): string;

package/dist/services/context/main-session-monitor.js

@@ -0,0 +1,119 @@
+/**
+ * v2.11.0 Group F (Tier 9) — D6: main-session context window monitor.
+ *
+ * Per `.peaks/memory/2026-06-26-v2-11-main-session-context-monitor.md`:
+ *
+ *   D6.a — IDE detection (`peaks ide detect --json`); env-var fallback.
+ *   D6.b — Main-session thresholds (50% warn / 75% user red line / 90% emergency)
+ *   D6.c — IDE-dependent trigger (claude-code → /compact; else LLM self-compress)
+ *   D6.d — Always log; never silently skip
+ *   D6.e — Do NOT auto-compact mid-tool-call-batch (in-flight deferral)
+ *   D6.f — Complements Step N periodic checkpoint (soft signal vs hard signal)
+ *
+ * Distinct from G7-G9 (sub-agent dispatch prompt governance). Same
+ * numbers, different scope. Extends `src/services/context/threshold.ts`
+ * rather than duplicating (D6.h).
+ *
+ * Karpathy §2: this module is the only place that decides
+ * "main-session context threshold" — the LLM-side caller probes via
+ * `evaluateMainSessionThreshold()` and `pickMainSessionTrigger()`.
+ * No inline `promptSize / 256K > 0.75` checks scattered across
+ * SKILL.md or other services.
+ */
+import { CONTEXT_CAPACITY_DEFAULT_BYTES, THRESHOLD_SOFT_WARN_RATIO, THRESHOLD_NEAR_LIMIT_RATIO, THRESHOLD_EMERGENCY_RATIO, evaluateThresholdTier } from './threshold.js';
+import { detectIdeFromEnv } from './ide-detect.js';
+export const MAIN_SESSION_THRESHOLD_RATIOS = {
+    ok: 0,
+    'soft-warn': THRESHOLD_SOFT_WARN_RATIO,
+    'near-limit': THRESHOLD_NEAR_LIMIT_RATIO,
+    emergency: THRESHOLD_EMERGENCY_RATIO
+};
+/**
+ * Threshold check. Pure function (no IO). `capacityBytes` is injectable
+ * for tests and future per-IDE capacity overrides. Defaults to the
+ * G9 256K proxy (matches G9 for cognitive continuity).
+ *
+ * @deprecated Slice 2026-07-02-auto-compact-zero-pause: the
+ * 50/75/90 tier thresholds pre-date the v2.13.0 auto-compact
+ * design. The authoritative tier table for triggering compaction
+ * now lives in `evaluateCompactTrigger` (auto-compact-orchestrator.ts)
+ * with the 0.85 pre-compact / 0.95 red-line thresholds. New
+ * callers should call `evaluateCompactTrigger(ratio)` directly.
+ * This function is retained because legacy `peaks context check
+ * --prompt-size` still emits its 4-tier envelope for callers that
+ * need the soft signal (e.g. statusline display). Migration is
+ * scheduled for v2.15.0; the @deprecated tag flips callers'
+ * eslint warnings so the migration is mechanical.
+ */
+export function evaluateMainSessionThreshold(promptSize, capacityBytes = CONTEXT_CAPACITY_DEFAULT_BYTES) {
+    const inner = evaluateThresholdTier(promptSize, capacityBytes);
+    // Map G9's 5 tiers down to the 4 main-session tiers (we collapse
+    // 'hard-reject' into 'near-limit' for the main-session: when
+    // dispatch is at 80% we still want a soft surface, not a hard block).
+    const tier = (() => {
+        switch (inner.tier) {
+            case 'ok':
+                return 'ok';
+            case 'soft-warn':
+                return 'soft-warn';
+            case 'near-limit':
+            case 'hard-reject':
+                return 'near-limit';
+            case 'emergency':
+                return 'emergency';
+        }
+    })();
+    return {
+        tier,
+        ratio: inner.ratio,
+        bytesUsed: inner.bytesUsed,
+        capacityBytes: inner.capacityBytes,
+        warnings: inner.warnings
+    };
+}
+export function pickMainSessionTrigger(opts) {
+    const ide = opts.ide ?? detectIdeFromEnv(opts.env);
+    const evaluation = evaluateMainSessionThreshold(opts.promptSize, opts.capacityBytes);
+    if (evaluation.tier === 'ok') {
+        return { kind: 'none' };
+    }
+    if (evaluation.tier === 'soft-warn') {
+        return {
+            kind: 'soft-warn',
+            promptSize: evaluation.bytesUsed,
+            ratio: evaluation.ratio
+        };
+    }
+    if (opts.inFlightBatch?.hasInFlightBatch === true) {
+        return { kind: 'defer', reason: 'in-flight-batch' };
+    }
+    if (ide === 'unknown') {
+        return { kind: 'defer', reason: 'unsupported-ide' };
+    }
+    const code = evaluation.tier === 'emergency' ? 'PROMPT_EMERGENCY' : 'CONTEXT_NEAR_LIMIT';
+    const path = ide === 'claude-code' ? 'ide-native' : 'llm-self-compress';
+    return {
+        kind: 'compact',
+        ide,
+        path,
+        promptSize: evaluation.bytesUsed,
+        ratio: evaluation.ratio,
+        code
+    };
+}
+/**
+ * One-line audit log entry. Pure formatter; the LLM / CLI appends to
+ * `.peaks/_runtime/<sessionId>/txt/auto-decisions.md`. Matches D6.d.
+ */
+export function formatMainSessionTriggerLogLine(trigger, contextId) {
+    switch (trigger.kind) {
+        case 'none':
+            return `context ${contextId}: ok (no trigger)`;
+        case 'soft-warn':
+            return `context ${contextId}: warning 50% threshold (ratio=${trigger.ratio.toFixed(2)})`;
+        case 'defer':
+            return `context ${contextId}: deferred (${trigger.reason})`;
+        case 'compact':
+            return `context ${contextId}: threshold=${(trigger.ratio * 100).toFixed(0)}% trigger=${trigger.path} ide=${trigger.ide} code=${trigger.code}`;
+    }
+}

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

@@ -0,0 +1,8 @@
+import type { MemoryIndexEntry } from '../memory/memory-search-service.js';
+export declare class MemoryIndexReader {
+    private readonly projectRoot;
+    private cache;
+    constructor(projectRoot: string);
+    loadIfStale(): MemoryIndexEntry[];
+    selectFeedbackLayerA(cap: number): MemoryIndexEntry[];
+}

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

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+const LAYER_A_RE = /peaks-feedback-promoted:\s*layer=A\b/;
+export class MemoryIndexReader {
+    projectRoot;
+    cache = null;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    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;
+    }
+    selectFeedbackLayerA(cap) {
+        const all = this.loadIfStale();
+        return all
+            .filter((e) => e.kind === 'feedback')
+            .filter((e) => LAYER_A_RE.test(e.description))
+            .slice(0, Math.max(1, Math.trunc(cap)));
+    }
+}
+function flattenIndex(raw) {
+    if (!raw || typeof raw !== 'object')
+        return [];
+    const out = [];
+    const obj = raw;
+    for (const layer of ['hot', 'warm', 'cold']) {
+        const bucket = obj[layer];
+        if (!bucket || typeof bucket !== 'object')
+            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);
+            }
+        }
+    }
+    return out;
+}

package/dist/services/context/memory-lru-cache.d.ts

@@ -0,0 +1,12 @@
+export declare class MemoryLruCache {
+    private readonly budgetBytes;
+    private readonly store;
+    private currentBytes;
+    constructor(budgetBytes: number);
+    set(key: string, body: string): void;
+    get(key: string): string | undefined;
+    delete(key: string): void;
+    size(): number;
+    private evictIfOver;
+    private evictAll;
+}

package/dist/services/context/memory-lru-cache.js

@@ -0,0 +1,60 @@
+export class MemoryLruCache {
+    budgetBytes;
+    store = new Map();
+    currentBytes = 0;
+    constructor(budgetBytes) {
+        this.budgetBytes = budgetBytes;
+    }
+    set(key, body) {
+        if (this.store.has(key))
+            this.delete(key);
+        const bytes = Buffer.byteLength(body, 'utf8');
+        if (bytes > this.budgetBytes) {
+            // Oversized insert: evict ALL existing entries (LRU order) so only
+            // the newly inserted key remains in the cache. This prevents the
+            // unbounded growth that a naive "single oversized exception" would
+            // allow when oversized values are inserted consecutively.
+            this.evictAll();
+            this.store.set(key, { body, bytes });
+            this.currentBytes += bytes;
+            return;
+        }
+        this.store.set(key, { body, bytes });
+        this.currentBytes += bytes;
+        this.evictIfOver();
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        // refresh recency
+        this.store.delete(key);
+        this.store.set(key, entry);
+        return entry.body;
+    }
+    delete(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return;
+        this.store.delete(key);
+        this.currentBytes -= entry.bytes;
+    }
+    size() {
+        return this.currentBytes;
+    }
+    evictIfOver() {
+        while (this.currentBytes > this.budgetBytes && this.store.size > 0) {
+            // Map preserves insertion order — first key is least-recently-touched
+            const oldestKey = this.store.keys().next().value;
+            if (oldestKey === undefined)
+                break;
+            this.delete(oldestKey);
+        }
+    }
+    evictAll() {
+        // Empty the store; called before an oversized insert so only the new
+        // entry remains, per the eviction contract documented above.
+        this.store.clear();
+        this.currentBytes = 0;
+    }
+}

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

@@ -0,0 +1,19 @@
+import type { ProjectPreferences } from '../preferences/preferences-types.js';
+export interface MemoryPreflightConfig {
+    readonly enabled: boolean;
+    readonly maxTokens: number;
+    readonly listCap: number;
+    readonly contentCacheBytes: number;
+}
+/**
+ * Loose input type for `resolveMemoryPreflightConfig`. Accepts either a
+ * full `ProjectPreferences` (e.g. the output of `loadPreferences()`) or
+ * any object that at minimum carries `memoryPreflight`. Lets callers
+ * pass a partial overlay literal — e.g. `{}` or `{ memoryPreflight: {...} }`
+ * — without having to construct a fully-populated preferences fixture.
+ *
+ * Downstream tasks (orchestrator service, dispatch hook) should import
+ * this alias rather than re-deriving the structural type.
+ */
+export type MemoryPreflightPrefsInput = ProjectPreferences | Pick<ProjectPreferences, 'memoryPreflight'>;
+export declare function resolveMemoryPreflightConfig(prefs: MemoryPreflightPrefsInput): MemoryPreflightConfig;