dsh-continual-evolve 0.3.0 → 0.5.0

package/lib/command.js

@@ -13,6 +13,8 @@ import { executeGoalCommand } from "./goal-command.js";
 import { executeMountCommand, executeUnmountCommand } from "./mount-command.js";
 import { executeBenchmarkCommand } from "./benchmark-command.js";
 import { executeWrapupCommand } from "./wrapup-command.js";
+import { loadUsage } from "./usage.js";
+import { planConsolidation } from "./consolidate.js";
 const USAGE = `Usage:
   /evolve                  show this help and the current local store
   /evolve list [global]    list entries (add "global" for the cross-session store)
@@ -23,6 +25,9 @@ const USAGE = `Usage:
                            to the global store (approval required), archive one-offs
   /evolve archive <id> [global]   hide an entry from injection (data kept, restorable)
   /evolve unarchive <id> [global] restore an archived entry
+  /evolve demote <id>             hide a (global) entry from injection, keep data
+  /evolve consolidate [apply]     report (or apply) a batch archive of conflict-hinted
+                                  and stale zero-use global entries
   /evolve log [tail N]            show the recent plugin log (default 50 lines)
   /evolve failures               aggregated failure counts (gate + benchmark, by class)
   /evolve export [global] <path>  backup a store to a JSON file
@@ -139,12 +144,16 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                 return success(renderResult(result));
             }
             case "archive":
-            case "unarchive": {
+            case "unarchive":
+            case "demote": {
                 const { scope, rest: after } = scopeArg(rest);
                 const id = stripAngleBrackets(after[0] ?? "");
                 if (!id) {
                     return error(`${sub} requires an entry id.\n${USAGE}`);
                 }
+                if (sub === "demote") {
+                    return demoteEntry(engine, id, sessionId);
+                }
                 const state = engine.load(scope, sessionId);
                 const found = findEntryById(state, id);
                 if (!found) {
@@ -167,6 +176,28 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                 }, { scope });
                 return success(renderResult(result));
             }
+            case "consolidate": {
+                // R3: deterministic global-store hygiene. Report by default;
+                // `apply` re-scans fresh state and lands the whole batch as ONE
+                // refinement (single snapshot + audit record, fully rollback-able).
+                const apply = rest[0] === "apply";
+                const state = engine.load("global", undefined);
+                const { candidates, edits } = planConsolidation(state, loadUsage(engine.baseDir));
+                if (candidates.length === 0) {
+                    return success("global store is already consolidated — no conflict-hinted or stale zero-use entries.");
+                }
+                const report = candidates.map((candidate, index) => `${index + 1}. [${candidate.kind}:${candidate.id}] ${candidate.title}\n   ${candidate.reason}`).join("\n");
+                if (!apply) {
+                    return success(`consolidation plan — ${candidates.length} archive candidate(s):\n${report}\n(run "/evolve consolidate apply" to archive all of them in one refinement)`);
+                }
+                const result = engine.apply("global", undefined, {
+                    summary: `Consolidate global store: archive ${candidates.length} entries`,
+                    rationale: "Human-invoked batch consolidation via /evolve consolidate apply.",
+                    expectedOutcome: "Candidate entries are hidden from injection (data kept; restorable via /evolve unarchive).",
+                    edits,
+                }, { scope: "global" });
+                return success(`${report}\n\napplied:\n${renderResult(result)}`);
+            }
             case "failures": {
                 // /evolve failures — failure-signature aggregation (D1 observation):
                 // failed review-gate records + failed benchmark cells, counted by class.
@@ -289,7 +320,7 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                 return success(renderResult(result));
             }
             case "wrapup": {
-                return await executeWrapupCommand(ctx, engine, invocation);
+                return await executeWrapupCommand(ctx, engine, invocation, runtime.promotionPolicy);
             }
             case "goal": {
                 return executeGoalCommand(ctx, invocation, rest);
@@ -311,6 +342,39 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
         return error(cause instanceof Error ? cause.message : String(cause));
     }
 }
+/**
+ * Demote (2026-08-22): hide an entry from injection WITHOUT deleting it —
+ * the one-command remedy for global-store pollution. Searches the global
+ * store first (the primary target: cross-project noise), then the session's
+ * local store. The data stays; `/evolve unarchive` restores it.
+ */
+function demoteEntry(engine, id, sessionId) {
+    for (const scope of ["global", "local"]) {
+        const state = engine.load(scope, sessionId);
+        const found = findEntryById(state, id);
+        if (!found)
+            continue;
+        const [kind, entry] = found;
+        const result = engine.apply(scope, sessionId, {
+            summary: `demote: archive ${kind}:${id} from the ${scope} store`,
+            rationale: "Human-invoked demote via the /evolve command.",
+            expectedOutcome: "The entry is hidden from injection in every scope it touched; data is kept and restorable.",
+            edits: [
+                {
+                    action: "update",
+                    kind,
+                    id,
+                    title: entry.title,
+                    content: entry.content,
+                    metadata: { ...entry.metadata, [ARCHIVED_AT_KEY]: new Date().toISOString() },
+                },
+            ],
+        }, { scope });
+        const restoreScope = scope === "global" ? " global" : "";
+        return success(`demoted ${kind}:${id} from the ${scope} store (archived — restore with /evolve unarchive ${id}${restoreScope})\n${renderResult(result)}`);
+    }
+    return error(`entry ${id} not found in the global or local store`);
+}
 function renderResult(result) {
     const applied = result.appliedEdits.filter((e) => e.applied);
     const failed = result.appliedEdits.filter((e) => !e.applied);

package/lib/consolidate.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Global-store consolidation (R3): turn the two hygiene signals — R2's
+ * `conflictHint` stamps and usage v2's zero-injection staleness — into one
+ * deterministic, human-approved batch of archive edits (`/evolve consolidate`).
+ *
+ * Design (ADR implemented/feature/2026-08-24-consolidation-command.md):
+ * - pure functions only; the command layer owns loading, reporting, and the
+ *   apply phase, and ALWAYS re-scans fresh state before applying (the report
+ *   and the apply are two separate invocations — prefer under-archiving over
+ *   mis-archiving when state moved in between);
+ * - archiving keeps data (ARCHIVED_AT_KEY stamp, restorable via
+ *   `/evolve unarchive`) and preserves every existing metadata key including
+ *   the conflictHint itself, so unarchived entries keep their trail;
+ * - no LLM call anywhere: code proposes, the human disposes.
+ */
+import type { HarnessState, RefinementEdit, RefinementKind } from "./types.js";
+import { type UsageStore } from "./usage.js";
+/** Zero-use entries at least this old are stale candidates (30d, matching the injection recency half-life scale). */
+export declare const STALE_MIN_AGE_MS: number;
+/** Parsed `<kind>:<id>:<score>` value of a {@link CONFLICT_HINT_KEY} stamp. */
+export interface ConflictHint {
+    kind: RefinementKind;
+    id: string;
+    score: number;
+}
+/**
+ * Parse one conflictHint metadata value. Returns undefined for anything that
+ * is not exactly `<kind>:<id>:<score>` with a known kind and a score in
+ * [0, 1] — foreign or legacy junk must never crash the scan.
+ */
+export declare function parseConflictHint(value: unknown): ConflictHint | undefined;
+/** One planned archive with its human-readable justification. */
+export interface ConsolidationCandidate {
+    kind: RefinementKind;
+    id: string;
+    title: string;
+    reason: string;
+}
+/**
+ * Entries stamped by the write-time conflict guard whose target still exists
+ * and is still active. The hinted (newer) entry is the archive candidate —
+ * the pointed-to original stays as the live copy.
+ */
+export declare function findConflictPairs(state: HarnessState): ConsolidationCandidate[];
+/**
+ * Active global entries never injected in any session and untouched for at
+ * least `minAgeMs`: prime staleness candidates. Operates on whatever state
+ * it is handed (callers pass the global store).
+ */
+export declare function findStaleEntries(state: HarnessState, store: UsageStore, now: number, minAgeMs?: number): ConsolidationCandidate[];
+/**
+ * Merge both scans (conflict reason wins on overlap), deduped by kind:id,
+ * and build the batch archive edits. Each edit preserves the entry's full
+ * content and existing metadata — only ARCHIVED_AT_KEY is added — so
+ * `/evolve unarchive` restores everything intact.
+ *
+ * @param now Epoch ms used for the archivedAt stamp (injected for tests).
+ */
+export declare function planConsolidation(state: HarnessState, store: UsageStore, now?: number, opts?: {
+    minAgeMs?: number;
+}): {
+    candidates: ConsolidationCandidate[];
+    edits: RefinementEdit[];
+};
+//# sourceMappingURL=consolidate.d.ts.map

package/lib/consolidate.js

@@ -0,0 +1,113 @@
+import { ARCHIVED_AT_KEY, CONFLICT_HINT_KEY, isArchived } from "./types.js";
+import { getUsageCount } from "./usage.js";
+/** Zero-use entries at least this old are stale candidates (30d, matching the injection recency half-life scale). */
+export const STALE_MIN_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const KINDS = ["prompt", "memory", "skill", "subagent"];
+/**
+ * Parse one conflictHint metadata value. Returns undefined for anything that
+ * is not exactly `<kind>:<id>:<score>` with a known kind and a score in
+ * [0, 1] — foreign or legacy junk must never crash the scan.
+ */
+export function parseConflictHint(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const parts = value.split(":");
+    if (parts.length !== 3) {
+        return undefined;
+    }
+    const [kind, id, rawScore] = parts;
+    if (!kind || !id || !rawScore || !KINDS.includes(kind)) {
+        return undefined;
+    }
+    const score = Number(rawScore);
+    if (!Number.isFinite(score) || score < 0 || score > 1) {
+        return undefined;
+    }
+    return { kind: kind, id, score };
+}
+/**
+ * Entries stamped by the write-time conflict guard whose target still exists
+ * and is still active. The hinted (newer) entry is the archive candidate —
+ * the pointed-to original stays as the live copy.
+ */
+export function findConflictPairs(state) {
+    const candidates = [];
+    for (const kind of KINDS) {
+        for (const entry of Object.values(state.entries[kind])) {
+            if (isArchived(entry))
+                continue;
+            const hint = parseConflictHint(entry.metadata[CONFLICT_HINT_KEY]);
+            if (!hint || hint.kind !== kind)
+                continue;
+            const target = state.entries[hint.kind]?.[hint.id];
+            if (!target || isArchived(target))
+                continue;
+            candidates.push({
+                kind,
+                id: entry.id,
+                title: entry.title,
+                reason: `near-duplicate of ${hint.id} 「${target.title}」 (${Math.round(hint.score * 100)}%) — keep the original`,
+            });
+        }
+    }
+    return candidates;
+}
+/**
+ * Active global entries never injected in any session and untouched for at
+ * least `minAgeMs`: prime staleness candidates. Operates on whatever state
+ * it is handed (callers pass the global store).
+ */
+export function findStaleEntries(state, store, now, minAgeMs = STALE_MIN_AGE_MS) {
+    const candidates = [];
+    for (const kind of KINDS) {
+        for (const entry of Object.values(state.entries[kind])) {
+            if (isArchived(entry))
+                continue;
+            if (getUsageCount(store, kind, entry.id) !== 0)
+                continue;
+            const updatedAt = Date.parse(entry.updated_at);
+            if (Number.isNaN(updatedAt) || now - updatedAt < minAgeMs)
+                continue;
+            candidates.push({
+                kind,
+                id: entry.id,
+                title: entry.title,
+                reason: `0 injections since ${entry.updated_at.slice(0, 10)} (stale)`,
+            });
+        }
+    }
+    return candidates;
+}
+/**
+ * Merge both scans (conflict reason wins on overlap), deduped by kind:id,
+ * and build the batch archive edits. Each edit preserves the entry's full
+ * content and existing metadata — only ARCHIVED_AT_KEY is added — so
+ * `/evolve unarchive` restores everything intact.
+ *
+ * @param now Epoch ms used for the archivedAt stamp (injected for tests).
+ */
+export function planConsolidation(state, store, now = Date.now(), opts) {
+    const byKey = new Map();
+    for (const candidate of [...findConflictPairs(state), ...findStaleEntries(state, store, now, opts?.minAgeMs)]) {
+        const key = `${candidate.kind}:${candidate.id}`;
+        if (!byKey.has(key)) {
+            byKey.set(key, candidate);
+        }
+    }
+    const candidates = [...byKey.values()];
+    const edits = candidates.map((candidate) => {
+        const entry = state.entries[candidate.kind][candidate.id];
+        const metadata = { ...entry?.metadata, [ARCHIVED_AT_KEY]: new Date(now).toISOString() };
+        return {
+            action: "update",
+            kind: candidate.kind,
+            id: candidate.id,
+            title: candidate.title,
+            content: entry?.content ?? "",
+            metadata,
+        };
+    });
+    return { candidates, edits };
+}
+//# sourceMappingURL=consolidate.js.map

package/lib/fate.d.ts

@@ -34,6 +34,7 @@ import type { HarnessState, RefinementResult } from "./types.js";
 import type { EvolutionEngine } from "./service.js";
 import type { AutoRefineReason } from "./review.js";
 import type { AutoReviewConfig, GateState, ReviewRecord } from "./auto.js";
+import { type PromotionPolicy } from "./promotion.js";
 import { type WrapupCandidate, type WrapupItem } from "./wrapup.js";
 /** Turns a declined local-fate proposal stays silent before being offered again. */
 export declare const FATE_CONSULT_COOLDOWN_TURNS = 10;
@@ -68,7 +69,7 @@ export interface FatePlan {
  * may have changed while the LLM call was in flight). Pure and unit-tested;
  * mirrors the partition step of the wrap-up command.
  */
-export declare function planLocalFates(items: readonly WrapupItem[], candidates: readonly WrapupCandidate[], globalState: HarnessState): FatePlan;
+export declare function planLocalFates(items: readonly WrapupItem[], candidates: readonly WrapupCandidate[], globalState: HarnessState, policy?: PromotionPolicy): FatePlan;
 /**
  * The cooldown key of a candidate set: the sorted `kind:id` list. The set is
  * the unit of consultation — a declined proposal is not offered again within

package/lib/fate.js

@@ -1,4 +1,5 @@
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { DEFAULT_PROMOTION_POLICY } from "./promotion.js";
 import { questionServiceOf } from "./approval.js";
 import { assessLocalEntries, candidateKey, filterPromotable, listLocalCandidates, splitArchiveGuards, splitPromoteBlocked, splitPromoteProposals, wholePromoteProposals, } from "./wrapup.js";
 /** Turns a declined local-fate proposal stays silent before being offered again. */
@@ -9,9 +10,9 @@ export const FATE_CONSULT_COOLDOWN_TURNS = 10;
  * may have changed while the LLM call was in flight). Pure and unit-tested;
  * mirrors the partition step of the wrap-up command.
  */
-export function planLocalFates(items, candidates, globalState) {
+export function planLocalFates(items, candidates, globalState, policy = DEFAULT_PROMOTION_POLICY) {
     const byKey = new Map(candidates.map((candidate) => [candidateKey(candidate.kind, candidate.id), candidate]));
-    const { promotable, skipped } = filterPromotable(items, globalState, candidates);
+    const { promotable, skipped } = filterPromotable(items, globalState, candidates, policy);
     const promoteItems = promotable.filter((item) => item.verdict === "promote");
     const archiveItems = items.filter((item) => item.verdict === "archive");
     const splits = [];
@@ -24,7 +25,7 @@ export function planLocalFates(items, candidates, globalState) {
             splitSkipped.push({ key: item.key, reason: "not in the audited candidate list" });
             continue;
         }
-        const blocked = splitPromoteBlocked(item, globalState, candidate.kind);
+        const blocked = splitPromoteBlocked(item, globalState, candidate.kind, policy);
         if (blocked) {
             splitSkipped.push({ key: item.key, reason: blocked });
             continue;
@@ -230,7 +231,7 @@ export async function runLocalFatePhase(ctx, engine, agent, config, state, reaso
         });
         return;
     }
-    const plan = planLocalFates(assessment.items, candidates, globalState);
+    const plan = planLocalFates(assessment.items, candidates, globalState, config.promotionPolicy);
     const needsDialog = plan.promotable.length + plan.splits.length + plan.reviewArchives.length > 0;
     let consent = { approved: false, asked: false, reason: "nothing-to-ask" };
     if (reason !== "compact" && needsDialog) {

package/lib/index.d.ts

@@ -57,6 +57,17 @@ export declare const Config: z<Schemastery.ObjectS<{
      * assessment so the encounter is distilled. 0 disables.
      */
     goalBlockedWrapupTurns: z<number, number>;
+    /**
+     * Promotion policy (2026-08-22): regex sources whose match in a
+     * candidate's title/content marks it project-scoped — such entries are
+     * never promoted to the cross-session global store. Replaces the built-in
+     * defaults when set.
+     */
+    promotionBlockPatterns: z<string[], string[]>;
+    /** Whole promotions below this content length stay local (chars). */
+    promotionMinChars: z<number, number>;
+    /** Entry-directory lines injected per build before folding into a counter. */
+    injectionDirectoryLines: z<number, number>;
 }>, Schemastery.ObjectT<{
     /** Root for evolution stores; defaults to the resolved DSH home. */
     baseDir: z<string, string>;
@@ -109,6 +120,17 @@ export declare const Config: z<Schemastery.ObjectS<{
      * assessment so the encounter is distilled. 0 disables.
      */
     goalBlockedWrapupTurns: z<number, number>;
+    /**
+     * Promotion policy (2026-08-22): regex sources whose match in a
+     * candidate's title/content marks it project-scoped — such entries are
+     * never promoted to the cross-session global store. Replaces the built-in
+     * defaults when set.
+     */
+    promotionBlockPatterns: z<string[], string[]>;
+    /** Whole promotions below this content length stay local (chars). */
+    promotionMinChars: z<number, number>;
+    /** Entry-directory lines injected per build before folding into a counter. */
+    injectionDirectoryLines: z<number, number>;
 }>>;
 /**
  * Structurally typed resolved config (loader passes the validated object).

package/lib/index.js

@@ -19,6 +19,7 @@ import { entriesSectionText } from "./inject.js";
 import { resolveRubricKey } from "./rubric.js";
 import { restoreMounted } from "./mount.js";
 import { registerFileLogger } from "./logfile.js";
+import { resolvePromotionPolicy } from "./promotion.js";
 export const name = "continual-evolve";
 /** Service key under which the evolution engine is published. */
 export const EVOLUTION_SERVICE = "evolution";
@@ -75,6 +76,17 @@ export const Config = z.object({
      * assessment so the encounter is distilled. 0 disables.
      */
     goalBlockedWrapupTurns: z.natural().min(0).default(3),
+    /**
+     * Promotion policy (2026-08-22): regex sources whose match in a
+     * candidate's title/content marks it project-scoped — such entries are
+     * never promoted to the cross-session global store. Replaces the built-in
+     * defaults when set.
+     */
+    promotionBlockPatterns: z.array(z.string()),
+    /** Whole promotions below this content length stay local (chars). */
+    promotionMinChars: z.natural().default(100),
+    /** Entry-directory lines injected per build before folding into a counter. */
+    injectionDirectoryLines: z.natural().default(15),
 });
 export function apply(ctx, config) {
     const baseDir = resolveDshHome(config.baseDir);
@@ -107,13 +119,18 @@ export function apply(ctx, config) {
     ctx.systemPrompt.section({
         name: "tool:continual-evolve:entries",
         order: (config.sectionOrder ?? 118) + 1,
-        text: (context) => entriesSectionText(engine, context.agent),
+        text: (context) => entriesSectionText(engine, context.agent, undefined, { directoryLines: config.injectionDirectoryLines ?? 15 }),
     });
     const gate = { requireGlobalApproval: config.requireGlobalApproval ?? true };
+    const promotionPolicy = resolvePromotionPolicy({
+        blockPatterns: config.promotionBlockPatterns,
+        minPromoteChars: config.promotionMinChars,
+    });
     registerEvolveTools(ctx, engine, gate);
     registerEvolveCommand(ctx, engine, gate, {
         rubricKey: resolveRubricKey(baseDir, config.rubricKey, process.env, (m) => ctx.logger("continual-evolve").warn(m)),
         autoRollbackOnReject: config.autoRollbackOnReject ?? true,
+        promotionPolicy,
     });
     // Plugin-owned file logging: every cordis log message lands in
     // <baseDir>/evolve/plugin.log regardless of how dsh web was launched —
@@ -137,6 +154,7 @@ export function apply(ctx, config) {
             localFate: config.localFate ?? true,
             fateIntervalTurns: config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6,
             goalBlockedWrapupTurns: config.goalBlockedWrapupTurns ?? 3,
+            promotionPolicy,
             ...(config.reviewModel ? { reviewModel: config.reviewModel } : {}),
         });
         ctx.logger("continual-evolve").info(`continual-evolve auto-review enabled (every ${config.reviewIntervalTurns ?? 6} turns; local-fate ${config.localFate ?? true ? "on" : "off"} every ${config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6} turns)`);

package/lib/inject.d.ts

@@ -19,6 +19,9 @@
  */
 import type { HarnessEntry, HarnessState } from "./types.js";
 import type { EvolutionEngine } from "./service.js";
+import { tokenize } from "./search.js";
+/** CJK-bigram tokenizer re-exported for ranking consumers (see search.ts). */
+export { tokenize };
 /** Prompt sections render at most this many entries per kind. */
 export declare const MAX_INJECTED_ENTRIES_PER_KIND = 6;
 /** Per-entry content budget inside the injected block (matches render.ts). */
@@ -60,17 +63,6 @@ export interface AgentLike {
 export interface InjectContext {
     agent?: AgentLike;
 }
-/**
- * Lowercase tokenization for the keyword relevance scorer: runs of ASCII
- * alphanumerics and CJK characters become tokens (CJK is not split so whole
- * Chinese words/characters stay comparable), everything else is a separator.
- */
-export declare function tokenize(text: string): string[];
-/**
- * Keyword hit count of `query` tokens inside an entry: title hits weigh 2×,
- * content/path hits 1×. BM25-level relevance without any external service.
- */
-export declare function relevanceHits(entry: HarnessEntry, query: string): number;
 /**
  * Normalized recency in [0, 1]: 1 when the entry was just updated, decaying
  * linearly to 0 after {@link RECENCY_HALF_LIFE_MS}. Unparseable timestamps
@@ -79,11 +71,13 @@ export declare function relevanceHits(entry: HarnessEntry, query: string): numbe
 export declare function recencyScore(entry: HarnessEntry, now: number): number;
 /**
  * Rank entries for injection, best first. With no query the ranking is pure
- * recency (newest first). With a query, any entry with at least one keyword
- * hit outranks every hit-less entry (`hits * 2 + recency <= 1` for the
- * latter), and hits decide the order among relevant entries; recency then
- * breaks remaining ties, and the stable dictionary order is the final
- * tiebreak, so the result is deterministic.
+ * recency (newest first). With a query, entries are scored once against a
+ * per-call BM25 index (CJK bigrams; field-weighted title ×2 — see
+ * search.ts): any entry with a positive score (≥1 matched token) outranks
+ * every hit-less entry (score exactly 0), scores decide the order among
+ * relevant entries, recency breaks remaining ties, and the stable dictionary
+ * order is the final tiebreak, so the result is deterministic. The input is
+ * never mutated.
  */
 export declare function rankEntries(entries: readonly HarnessEntry[], query?: string, now?: number): HarnessEntry[];
 /**
@@ -109,8 +103,16 @@ export declare function formatSubagentSpecsSection(entries: readonly HarnessEntr
  * the model a zero-cost overview of what exists so it can ask for full text
  * via `evolve_list` or `/evolve list`. The directory is appended after the
  * curated top-N injection sections and adds minimal tokens.
+ *
+ * 2026-08-22 throttle: the directory is CAPPED at {@link DEFAULT_DIRECTORY_LINES}
+ * lines (oldest-sorted stable order) with the remainder folded into a single
+ * counter line — an uncapped directory across a polluted global store was
+ * measured at ~2K chars of every build in every project.
  */
+export declare const DEFAULT_DIRECTORY_LINES = 15;
 export declare function formatEntriesDirectory(...kindEntries: readonly HarnessEntry[][]): string;
+/** {@link formatEntriesDirectory} with an explicit cap (configurable). */
+export declare function formatEntriesDirectoryCapped(maxLines: number, ...kindEntries: readonly HarnessEntry[][]): string;
 /**
  * Walk the parent-session chain from `agent` upward and return the nearest
  * session whose local store is non-empty, if any. Children inherit their
@@ -127,6 +129,13 @@ export declare function nearestLocalStateWithEntries(engine: EvolutionEngine, ag
  * (relevance first, then recency; see {@link rankEntries}). Returns "" when
  * nothing is injectable — the prompt renderer then drops the section, so an
  * empty store adds zero tokens to every assembly.
+ *
+ * `opts.directoryLines` caps the entry-directory index (2026-08-22 throttle).
+ * Usage recording covers ALL kinds — memories and skills appear as directory
+ * lines, prompts/subagents as content — and is deduped per session so the
+ * counts read "how many sessions saw this", not "how many prompt builds".
  */
-export declare function entriesSectionText(engine: EvolutionEngine, agent: AgentLike | undefined, query?: string): string;
+export declare function entriesSectionText(engine: EvolutionEngine, agent: AgentLike | undefined, query?: string, opts?: {
+    directoryLines?: number;
+}): string;
 //# sourceMappingURL=inject.d.ts.map