dsh-continual-evolve 0.6.1 → 0.7.1

package/lib/command.js

@@ -5,7 +5,8 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { requireGlobalApproval } from "./approval.js";
 import { saveHarnessState } from "./state.js";
-import { appendResult, storePaths } from "./store.js";
+import { appendResult, pruneJsonlFile, storePaths } from "./store.js";
+import { DEFAULT_REFINEMENTS_RETAIN } from "./store.js";
 import { entrySourceOf } from "./source.js";
 import { filterLogBySession, formatLogLine, pluginLogFilePath } from "./logfile.js";
 import { collectFailureSummary, formatFailureSummary } from "./failures.js";
@@ -13,11 +14,14 @@ 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 { projectKeyOf } from "./project.js";
+import { loadUsage, getUsageCount } from "./usage.js";
+import { loadGateRuntime, saveGateRuntime } from "./runtime.js";
 import { planConsolidation } from "./consolidate.js";
+import { loadTokenUsage, renderTokenUsageReport } from "./token-usage.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)
+  /evolve list [project|global]    list entries (default local staging; "project" = this project's cross-session store, "global" = cross-project store)
   /evolve history [global] show applied refinements (rollback ids)
   /evolve rollback <id> [global]  deterministically revert a refinement
   /evolve plan [msg]       run the LLM planner against the current store
@@ -39,7 +43,10 @@ const USAGE = `Usage:
   /evolve unmount <id>       remove a hot-mounted plugin
   /evolve goal               show the evolution goal (round-driven auto-review)
   /evolve goal <objective>   create/update the evolution goal
-  /evolve goal done          complete the evolution goal`;
+  /evolve goal done          complete the evolution goal
+  /evolve pause | resume     pause/resume the auto-review gate (manual tools and commands keep working)
+  /evolve status             gate state (patch flag + runtime switch) plus store entry counts
+  /evolve usage              injection counts + exact direct-call token usage (benchmark subagents excluded)`;
 export function registerEvolveCommand(ctx, engine, opts, runtime) {
     ctx.commands.register({
         name: "evolve",
@@ -52,8 +59,29 @@ function scopeArg(tokens) {
     if (tokens[0] === "global") {
         return { scope: "global", rest: tokens.slice(1) };
     }
+    if (tokens[0] === "project") {
+        return { scope: "project", rest: tokens.slice(1) };
+    }
     return { scope: "local", rest: tokens };
 }
+/**
+ * The store id a scope reads/writes from the human command: live session id
+ * for local, derived project key for project, undefined for global. Throws
+ * for project when the session cwd is unavailable.
+ */
+function storeIdForCommand(scope, invocation) {
+    if (scope === "local") {
+        return invocation.agent.id;
+    }
+    if (scope === "project") {
+        const key = projectKeyOf(invocation.agent);
+        if (!key) {
+            throw new Error("project scope needs the session cwd (unavailable here) — use local or global instead");
+        }
+        return key;
+    }
+    return undefined;
+}
 /**
  * Tokenize a command's raw input with shell-like quoting:
  * - a `#` outside quotes starts a comment (rest of the line is dropped);
@@ -129,11 +157,11 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                 return success(`${USAGE}\n\n${formatHarnessStateForPrompt(engine.load("local", sessionId))}`);
             case "list": {
                 const { scope } = scopeArg(rest);
-                return success(formatHarnessStateForPrompt(engine.load(scope, sessionId)));
+                return success(formatHarnessStateForPrompt(engine.load(scope, storeIdForCommand(scope, invocation))));
             }
             case "history": {
                 const { scope } = scopeArg(rest);
-                const history = engine.history(scope, sessionId);
+                const history = engine.history(scope, storeIdForCommand(scope, invocation));
                 return success(historyForPrompt(history) || "(no refinements yet)");
             }
             case "rollback": {
@@ -142,7 +170,7 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                 if (!id) {
                     return error(`rollback requires a refinement id.\n${USAGE}`);
                 }
-                const result = engine.rollback(scope, sessionId, id);
+                const result = engine.rollback(scope, storeIdForCommand(scope, invocation), id);
                 return success(renderResult(result));
             }
             case "archive":
@@ -154,9 +182,9 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                     return error(`${sub} requires an entry id.\n${USAGE}`);
                 }
                 if (sub === "demote") {
-                    return demoteEntry(engine, id, sessionId);
+                    return demoteEntry(engine, id, sessionId, projectKeyOf(invocation.agent));
                 }
-                const state = engine.load(scope, sessionId);
+                const state = engine.load(scope, storeIdForCommand(scope, invocation));
                 const found = findEntryById(state, id);
                 if (!found) {
                     return error(`entry ${id} not found in the ${scope} store`);
@@ -170,7 +198,7 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                     delete metadata[ARCHIVED_AT_KEY];
                 }
                 const archived = sub === "archive";
-                const result = engine.apply(scope, sessionId, {
+                const result = engine.apply(scope, storeIdForCommand(scope, invocation), {
                     summary: `${archived ? "Archive" : "Unarchive"} entry ${kind}:${id}`,
                     rationale: "Human-invoked archive/unarchive via the /evolve command.",
                     expectedOutcome: `Entry ${archived ? "is hidden from injection (data kept, restorable)" : "is injected again"}.`,
@@ -260,8 +288,8 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                 if (!path) {
                     return error(`export requires an output path.\n${USAGE}`);
                 }
-                const state = engine.load(scope, sessionId);
-                const history = engine.history(scope, sessionId);
+                const state = engine.load(scope, storeIdForCommand(scope, invocation));
+                const history = engine.history(scope, storeIdForCommand(scope, invocation));
                 const payload = {
                     version: 1,
                     scope,
@@ -293,7 +321,7 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                     },
                     refinements: Array.isArray(payload["refinements"]) ? payload["refinements"] : [],
                 };
-                const paths = storePaths(engine.baseDir, scope, sessionId);
+                const paths = storePaths(engine.baseDir, scope, storeIdForCommand(scope, invocation));
                 saveHarnessState(paths.stateDir, state);
                 if (Array.isArray(payload["history"])) {
                     for (const result of payload["history"]) {
@@ -301,14 +329,22 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                             appendResult(paths, result);
                         }
                     }
+                    // Storage hygiene (#20): an imported history obeys the
+                    // same tail budget as a live one.
+                    try {
+                        pruneJsonlFile(paths.resultsPath, engine.retention?.refinements ?? DEFAULT_REFINEMENTS_RETAIN);
+                    }
+                    catch {
+                        // ignored — the next apply retries
+                    }
                 }
                 return success(`imported ${scope} store from ${path}`);
             }
             case "plan": {
                 const { scope, rest: after } = scopeArg(rest);
                 const instructions = after.length > 0 ? after.join(" ") : undefined;
-                const state = engine.load(scope, sessionId);
-                const history = engine.history(scope, sessionId);
+                const state = engine.load(scope, storeIdForCommand(scope, invocation));
+                const history = engine.history(scope, storeIdForCommand(scope, invocation));
                 const proposal = await planWithLlm(ctx, {
                     agent: invocation.agent,
                     state,
@@ -316,13 +352,19 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                     ...(instructions ? { instructions } : {}),
                     global: scope === "global",
                     signal: invocation.signal,
+                    tokenUsage: {
+                        baseDir: engine.baseDir,
+                        sessionId,
+                        retain: engine.retention.tokenUsage,
+                        onError: (cause) => ctx.logger("continual-evolve").warn(`token-usage ledger failed for ${sessionId}: ${cause instanceof Error ? cause.message : String(cause)}`),
+                    },
                     // skill-creator template facts (fallback: builtin guide).
                     skillsRoot: join(engine.baseDir, "skills"),
                 });
-                if (scope === "global" && opts.requireGlobalApproval && proposal.edits.length > 0) {
-                    await requireGlobalApproval(ctx, invocation.agent, invocation.signal, `/evolve plan global 将应用 ${proposal.edits.length} 条编辑到跨会话 store：${proposal.summary}`);
+                if ((scope === "global" || scope === "project") && opts.requireGlobalApproval && proposal.edits.length > 0) {
+                    await requireGlobalApproval(ctx, invocation.agent, invocation.signal, `/evolve plan ${scope} 将应用 ${proposal.edits.length} 条编辑到${scope === "project" ? "本项目" : "跨会话"} store：${proposal.summary}`);
                 }
-                const result = engine.apply(scope, sessionId, proposal, {
+                const result = engine.apply(scope, storeIdForCommand(scope, invocation), proposal, {
                     scope,
                     baselineState: state,
                     ...(entrySourceOf(invocation.agent, sessionId) ? { source: entrySourceOf(invocation.agent, sessionId) } : {}),
@@ -332,6 +374,27 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
             case "wrapup": {
                 return await executeWrapupCommand(ctx, engine, invocation, runtime.promotionPolicy);
             }
+            case "pause":
+            case "resume": {
+                // #21 P2 runtime switch: pause the AUTOMATIC gate only. Manual
+                // evolve_* tools and /evolve commands keep working — the human
+                // is acting explicitly there, so no gate is being bypassed.
+                const pausing = sub === "pause";
+                const current = loadGateRuntime(engine.baseDir);
+                if (current.paused === pausing) {
+                    return success(`auto-review gate is already ${pausing ? "paused" : "running"} (no change).`);
+                }
+                saveGateRuntime(engine.baseDir, pausing);
+                return success(pausing
+                    ? "auto-review gate paused: no automatic reviews, fate assessments, or gate LLM calls until /evolve resume. Manual evolve_* tools and /evolve commands keep working."
+                    : "auto-review gate resumed: automatic reviews run again on their configured cadence.");
+            }
+            case "status": {
+                return success(renderGateStatus(engine, sessionId, projectKeyOf(invocation.agent), runtime));
+            }
+            case "usage": {
+                return success(renderUsageReport(engine, sessionId, projectKeyOf(invocation.agent)));
+            }
             case "goal": {
                 return executeGoalCommand(ctx, invocation, rest);
             }
@@ -354,18 +417,23 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
 }
 /**
  * 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.
+ * the one-command remedy for store pollution. Searches the global store
+ * first (the primary target: cross-project noise), then the project store,
+ * 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);
+function demoteEntry(engine, id, sessionId, projectKey) {
+    const targets = [
+        { scope: "global", storeId: undefined },
+        ...(projectKey ? [{ scope: "project", storeId: projectKey }] : []),
+        { scope: "local", storeId: sessionId },
+    ];
+    for (const { scope, storeId } of targets) {
+        const state = engine.load(scope, storeId);
         const found = findEntryById(state, id);
         if (!found)
             continue;
         const [kind, entry] = found;
-        const result = engine.apply(scope, sessionId, {
+        const result = engine.apply(scope, storeId, {
             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.",
@@ -380,10 +448,105 @@ function demoteEntry(engine, id, sessionId) {
                 },
             ],
         }, { scope });
-        const restoreScope = scope === "global" ? " global" : "";
+        const restoreScope = scope === "global" ? " global" : scope === "project" ? " project" : "";
         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`);
+    return error(`entry ${id} not found in the global, project, or local store`);
+}
+/**
+ * #21 status: one screen answering "is the gate on, and what is in the
+ * stores". The patch flag says whether the gate was registered at boot;
+ * the runtime switch says whether the human paused it since.
+ */
+function renderGateStatus(engine, sessionId, projectKey, runtime) {
+    const paused = loadGateRuntime(engine.baseDir).paused;
+    const patch = runtime.autoReview === undefined ? "unknown" : runtime.autoReview ? "on" : "off";
+    const gateLine = patch === "off"
+        ? "gate: disabled in patch config (autoReview off — /evolve pause has nothing to pause)"
+        : `gate: ${patch === "unknown" ? "patch flag unknown" : "enabled in patch config"} · ${paused ? "PAUSED by /evolve pause (resume with /evolve resume)" : "running"}`;
+    const countEntries = (state) => Object.values(state.entries).reduce((n, byKind) => n + Object.keys(byKind).length, 0);
+    const lines = [gateLine];
+    lines.push(`stores: global ${countEntries(engine.load("global", undefined))} entries · local(${sessionId}) ${countEntries(engine.load("local", sessionId))} entries`);
+    if (projectKey) {
+        try {
+            lines[lines.length - 1] += ` · project ${countEntries(engine.load("project", projectKey))} entries`;
+        }
+        catch {
+            lines[lines.length - 1] += " · project (unavailable)";
+        }
+    }
+    const retention = engine.retention;
+    if (retention) {
+        lines.push(`retention: snapshots ${retention.snapshots} · refinements ${retention.refinements} · reviews ${retention.reviews} · token usage ${retention.tokenUsage} (historyRetain)`);
+    }
+    return lines.join("\n");
+}
+/**
+ * #21 P0 usage ledger: injection counts per entry across the stores the
+ * human can see (global + this session + this project). Counts are
+ * per-session since the v2 usage shape — "in how many sessions did this
+ * entry surface" — the exposure half of the #18a归零实验 verdict.
+ */
+function renderUsageReport(engine, sessionId, projectKey) {
+    const store = loadUsage(engine.baseDir);
+    const rows = [];
+    const seen = new Set();
+    const collect = (state) => {
+        for (const kind of Object.keys(state.entries)) {
+            for (const entry of Object.values(state.entries[kind])) {
+                const key = `${kind}:${entry.id}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                const count = getUsageCount(store, kind, entry.id);
+                rows.push({
+                    key,
+                    title: entry.title,
+                    count,
+                    ...(store.lastSession?.[`${kind}:${entry.id}`] ? { lastSession: store.lastSession[`${kind}:${entry.id}`] } : {}),
+                });
+            }
+        }
+    };
+    collect(engine.load("global", undefined));
+    collect(engine.load("local", sessionId));
+    if (projectKey) {
+        try {
+            collect(engine.load("project", projectKey));
+        }
+        catch {
+            // project store unavailable here — global+local still report
+        }
+    }
+    const liveKeys = new Set(rows.map((r) => r.key));
+    const orphaned = Object.keys(store.counts).filter((k) => !liveKeys.has(k)).length;
+    const total = rows.reduce((n, r) => n + r.count, 0);
+    const injected = rows.filter((r) => r.count > 0).sort((a, b) => b.count - a.count || (a.key < b.key ? -1 : 1));
+    const stale = rows.filter((r) => r.count === 0).sort((a, b) => (a.key < b.key ? -1 : 1));
+    const lines = [`injected entries: ${total} injections across ${injected.length} of ${rows.length} stored entries${orphaned > 0 ? ` (+${orphaned} historical key(s) for deleted entries)` : ""}`];
+    if (injected.length > 0) {
+        lines.push("injected (top 15):");
+        for (const row of injected.slice(0, 15)) {
+            lines.push(`  ${row.key} — ${row.count}× · ${row.title}${row.lastSession ? ` (last in ${row.lastSession})` : ""}`);
+        }
+        if (injected.length > 15) {
+            lines.push(`  … and ${injected.length - 15} more`);
+        }
+    }
+    else {
+        lines.push("injected: (none yet — nothing has surfaced into a session prompt)");
+    }
+    if (stale.length > 0) {
+        lines.push(`never injected (${stale.length}):`);
+        for (const row of stale.slice(0, 20)) {
+            lines.push(`  ${row.key} · ${row.title}`);
+        }
+        if (stale.length > 20) {
+            lines.push(`  … and ${stale.length - 20} more`);
+        }
+    }
+    lines.push("", ...renderTokenUsageReport(loadTokenUsage(engine.baseDir), engine.retention.tokenUsage));
+    return lines.join("\n");
 }
 function renderResult(result) {
     const applied = result.appliedEdits.filter((e) => e.applied);

package/lib/evolve-event.d.ts

@@ -32,7 +32,9 @@ export declare function buildEvolveCompleteEvent(result: RefinementResult, trigg
 /**
  * Emit an evolve_complete event to the reviews.jsonl audit trail. The event
  * is JSONL-formatted (one line) so consumers can tail and parse it. This is
- * a best-effort write — failure never blocks the refinement path.
+ * a best-effort write — failure never blocks the refinement path. Storage
+ * hygiene (#20): the trail is truncated to its tail after the append so the
+ * audit file cannot grow without bound; readers only need a recent window.
  */
-export declare function emitEvolveComplete(baseDir: string, event: EvolveCompleteEvent): void;
+export declare function emitEvolveComplete(baseDir: string, event: EvolveCompleteEvent, reviewsRetain?: number): void;
 //# sourceMappingURL=evolve-event.d.ts.map

package/lib/evolve-event.js

@@ -11,6 +11,7 @@
  */
 import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { DEFAULT_REVIEWS_RETAIN, pruneJsonlFile, reviewsPath } from "./store.js";
 /** Build a structured evolve-complete event from a refinement result. */
 export function buildEvolveCompleteEvent(result, trigger, sessionId) {
     return {
@@ -34,9 +35,11 @@ export function buildEvolveCompleteEvent(result, trigger, sessionId) {
 /**
  * Emit an evolve_complete event to the reviews.jsonl audit trail. The event
  * is JSONL-formatted (one line) so consumers can tail and parse it. This is
- * a best-effort write — failure never blocks the refinement path.
+ * a best-effort write — failure never blocks the refinement path. Storage
+ * hygiene (#20): the trail is truncated to its tail after the append so the
+ * audit file cannot grow without bound; readers only need a recent window.
  */
-export function emitEvolveComplete(baseDir, event) {
+export function emitEvolveComplete(baseDir, event, reviewsRetain = DEFAULT_REVIEWS_RETAIN) {
     try {
         const dir = join(baseDir, "evolve");
         mkdirSync(dir, { recursive: true });
@@ -44,6 +47,13 @@ export function emitEvolveComplete(baseDir, event) {
     }
     catch {
         // Event emission is diagnostic; never interrupt the refinement path.
+        return;
+    }
+    try {
+        pruneJsonlFile(reviewsPath(baseDir), reviewsRetain);
+    }
+    catch {
+        // ignored — the next emission retries
     }
 }
 //# sourceMappingURL=evolve-event.js.map

package/lib/fate.js

@@ -26,7 +26,7 @@ export function planLocalFates(items, candidates, globalState, policy = DEFAULT_
             splitSkipped.push({ key: item.key, reason: "not in the audited candidate list" });
             continue;
         }
-        const blocked = splitPromoteBlocked(item, globalState, candidate.kind, policy);
+        const blocked = splitPromoteBlocked(item, globalState, candidate.kind, policy, candidate.metadata);
         if (blocked) {
             splitSkipped.push({ key: item.key, reason: blocked });
             continue;
@@ -201,6 +201,12 @@ export async function runLocalFatePhase(ctx, engine, agent, config, state, reaso
         return;
     const logger = ctx.logger("continual-evolve");
     const sessionId = agent.id;
+    const tokenUsage = {
+        baseDir: engine.baseDir,
+        sessionId,
+        retain: engine.retention.tokenUsage,
+        onError: (cause) => logger.warn(`token-usage ledger failed for ${sessionId}: ${cause instanceof Error ? cause.message : String(cause)}`),
+    };
     const localState = engine.load("local", sessionId);
     const globalState = engine.load("global", undefined);
     const candidates = listLocalCandidates(localState, globalState, engine.baseDir);
@@ -218,7 +224,7 @@ export async function runLocalFatePhase(ctx, engine, agent, config, state, reaso
     state.lastFateAt = state.turns;
     let assessment;
     try {
-        assessment = await assessLocalEntries(ctx, agent, candidates);
+        assessment = await assessLocalEntries(ctx, agent, candidates, { tokenUsage, tokenUsagePhase: "fate" });
     }
     catch (cause) {
         const message = cause instanceof Error ? cause.message : String(cause);

package/lib/index.d.ts

@@ -18,6 +18,15 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     maxReviewInputChars: z<number, number, "defined">;
     /** Output budget for the cheap gate call. */
     reviewBudgetTokens: z<number, number, "defined">;
+    /**
+     * Planner prefix-cache routing for the gate and planner inputs: `auto`
+     * prepends a session-derived message prefix when the session shows
+     * cache-read evidence (dropping the redundant flat trajectory text),
+     * `session` always prefixes, `off` keeps the legacy flat-text input.
+     */
+    plannerPrefixCache: z<"session" | "off" | "auto", "session" | "off" | "auto", "defined">;
+    /** Session-prefix budget for Route A planning inputs, in characters. */
+    plannerPrefixMaxChars: z<number, number, "defined">;
     /** After an approved gate run with applied edits, queue a visible follow-up notice. */
     notifyOnAutoReview: z<boolean, boolean, "defined">;
     /** Cross-session (global) edits require an explicit human approval. */
@@ -74,6 +83,25 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     promotionMinChars: z<number, number, "defined">;
     /** Entry-directory lines injected per build before folding into a counter. */
     injectionDirectoryLines: z<number, number, "defined">;
+    /**
+     * Storage hygiene (#20): how much append-only past each write keeps.
+     * `snapshots` = full-state copies per store, `refinements` = tail lines
+     * per store history, `reviews` = tail lines of the shared audit trail,
+     * `tokenUsage` = tail lines of the direct-call token ledger.
+     * Absent fields fall back to the store defaults (20 / 500 / 500 / 500) —
+     * rollback needs recent snapshots, readers need a recent window.
+     */
+    historyRetain: z<Schemastery.ObjectS<NoInfer<{
+        snapshots: z<number, number, "plain">;
+        refinements: z<number, number, "plain">;
+        reviews: z<number, number, "plain">;
+        tokenUsage: z<number, number, "plain">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        snapshots: z<number, number, "plain">;
+        refinements: z<number, number, "plain">;
+        reviews: z<number, number, "plain">;
+        tokenUsage: z<number, number, "plain">;
+    }>>, "plain">;
 }>>, Schemastery.ObjectT<NoInfer<{
     /** Root for evolution stores; defaults to the resolved DSH home. */
     baseDir: z<string, string, "plain">;
@@ -87,6 +115,15 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     maxReviewInputChars: z<number, number, "defined">;
     /** Output budget for the cheap gate call. */
     reviewBudgetTokens: z<number, number, "defined">;
+    /**
+     * Planner prefix-cache routing for the gate and planner inputs: `auto`
+     * prepends a session-derived message prefix when the session shows
+     * cache-read evidence (dropping the redundant flat trajectory text),
+     * `session` always prefixes, `off` keeps the legacy flat-text input.
+     */
+    plannerPrefixCache: z<"session" | "off" | "auto", "session" | "off" | "auto", "defined">;
+    /** Session-prefix budget for Route A planning inputs, in characters. */
+    plannerPrefixMaxChars: z<number, number, "defined">;
     /** After an approved gate run with applied edits, queue a visible follow-up notice. */
     notifyOnAutoReview: z<boolean, boolean, "defined">;
     /** Cross-session (global) edits require an explicit human approval. */
@@ -143,6 +180,25 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     promotionMinChars: z<number, number, "defined">;
     /** Entry-directory lines injected per build before folding into a counter. */
     injectionDirectoryLines: z<number, number, "defined">;
+    /**
+     * Storage hygiene (#20): how much append-only past each write keeps.
+     * `snapshots` = full-state copies per store, `refinements` = tail lines
+     * per store history, `reviews` = tail lines of the shared audit trail,
+     * `tokenUsage` = tail lines of the direct-call token ledger.
+     * Absent fields fall back to the store defaults (20 / 500 / 500 / 500) —
+     * rollback needs recent snapshots, readers need a recent window.
+     */
+    historyRetain: z<Schemastery.ObjectS<NoInfer<{
+        snapshots: z<number, number, "plain">;
+        refinements: z<number, number, "plain">;
+        reviews: z<number, number, "plain">;
+        tokenUsage: z<number, number, "plain">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        snapshots: z<number, number, "plain">;
+        refinements: z<number, number, "plain">;
+        reviews: z<number, number, "plain">;
+        tokenUsage: z<number, number, "plain">;
+    }>>, "plain">;
 }>>, "plain">;
 /**
  * Structurally typed resolved config (loader passes the validated object).

package/lib/index.js

@@ -37,6 +37,15 @@ export const Config = z.object({
     maxReviewInputChars: z.natural().default(40000),
     /** Output budget for the cheap gate call. */
     reviewBudgetTokens: z.natural().default(4096),
+    /**
+     * Planner prefix-cache routing for the gate and planner inputs: `auto`
+     * prepends a session-derived message prefix when the session shows
+     * cache-read evidence (dropping the redundant flat trajectory text),
+     * `session` always prefixes, `off` keeps the legacy flat-text input.
+     */
+    plannerPrefixCache: z.union([z.const("auto"), z.const("session"), z.const("off")]).default("auto"),
+    /** Session-prefix budget for Route A planning inputs, in characters. */
+    plannerPrefixMaxChars: z.natural().default(12000),
     /** After an approved gate run with applied edits, queue a visible follow-up notice. */
     notifyOnAutoReview: z.boolean().default(true),
     /** Cross-session (global) edits require an explicit human approval. */
@@ -93,6 +102,20 @@ export const Config = z.object({
     promotionMinChars: z.natural().default(100),
     /** Entry-directory lines injected per build before folding into a counter. */
     injectionDirectoryLines: z.natural().default(15),
+    /**
+     * Storage hygiene (#20): how much append-only past each write keeps.
+     * `snapshots` = full-state copies per store, `refinements` = tail lines
+     * per store history, `reviews` = tail lines of the shared audit trail,
+     * `tokenUsage` = tail lines of the direct-call token ledger.
+     * Absent fields fall back to the store defaults (20 / 500 / 500 / 500) —
+     * rollback needs recent snapshots, readers need a recent window.
+     */
+    historyRetain: z.object({
+        snapshots: z.natural(),
+        refinements: z.natural(),
+        reviews: z.natural(),
+        tokenUsage: z.natural(),
+    }),
 });
 export function apply(ctx, config) {
     const baseDir = resolveDshHome(config.baseDir);
@@ -111,12 +134,12 @@ export function apply(ctx, config) {
                     .warn(`skill materialization failed for ${result.id}: ${cause instanceof Error ? cause.message : String(cause)}`);
             }
         },
-    });
+    }, config.historyRetain ? { historyRetain: { ...config.historyRetain } } : {});
     ctx.provide(EVOLUTION_SERVICE, { engine, baseDir });
     ctx.systemPrompt.section({
         name: "tool:continual-evolve",
         order: config.sectionOrder ?? 118,
-        text: "You have a continual harness: versioned, persistent prompt notes, memories, skills, and subagent specs. Prompt notes and delegation specs are injected below; use evolve_list for the full state. Create an entry (evolve_add) after a repeated failure, a reusable tactic, a durable fact or preference, a repeated procedure, or a repeated delegation role. Keep edits small and evidence-backed; prefer local scope, use global: true only for stable cross-session lessons. Update or delete (evolve_update / evolve_delete) when an entry is wrong or obsolete; roll back faulty refinements with evolve_rollback. Every edit is snapshotted, versioned, and recorded — no edit can be silently lost.",
+        text: "You have a continual harness: versioned, persistent prompt notes, memories, skills, and subagent specs. Memories are ONE FACT per entry, typed user/feedback/project/reference (feedback = pitfall + Why + How to apply). Stores: local (this session's staging), project (this project's cross-session store), global (cross-project). Prompt notes and delegation specs are injected below; use evolve_list for the full state. Create an entry (evolve_add) after a repeated failure, a reusable tactic, a durable fact or preference, a repeated procedure, or a repeated delegation role. Keep edits small and evidence-backed; prefer local scope, use project for repo-specific lessons, global: true only for stable cross-project lessons. Update or delete (evolve_update / evolve_delete) when an entry is wrong or obsolete; roll back faulty refinements with evolve_rollback. Every edit is snapshotted, versioned, and recorded — no edit can be silently lost.",
     });
     // Phase 2: make prompt entries real system-prompt content and subagent
     // entries real delegation specs. The text is a provider evaluated at every
@@ -139,6 +162,7 @@ export function apply(ctx, config) {
         autoRollbackOnReject: config.autoRollbackOnReject ?? true,
         autoCase: config.autoCase ?? true,
         promotionPolicy,
+        ...(config.autoReview !== undefined ? { autoReview: config.autoReview } : {}),
     });
     // Plugin-owned file logging: every cordis log message lands in
     // <baseDir>/evolve/plugin.log regardless of how dsh web was launched —
@@ -165,7 +189,10 @@ export function apply(ctx, config) {
             promotionPolicy,
             autoCase: config.autoCase ?? true,
             rubricKey,
+            ...(config.historyRetain?.reviews !== undefined ? { reviewsRetain: config.historyRetain.reviews } : {}),
             ...(config.reviewModel ? { reviewModel: config.reviewModel } : {}),
+            ...(config.plannerPrefixCache ? { prefixCacheMode: config.plannerPrefixCache } : {}),
+            ...(config.plannerPrefixMaxChars !== undefined ? { prefixMaxChars: config.plannerPrefixMaxChars } : {}),
         });
         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)`);
     }