dsh-continual-evolve 0.7.0 → 0.7.2

package/lib/command.d.ts

@@ -17,6 +17,11 @@ export interface CommandRuntimeOptions {
     autoCase: boolean;
     /** Mechanical promotion guards for wrapup/fate (2026-08-22 policy). */
     promotionPolicy: PromotionPolicy;
+    /**
+     * Initial auto-review default from plugin config. The listener is always
+     * registered; this is not a registration gate.
+     */
+    autoReview?: boolean;
 }
 export declare function registerEvolveCommand(ctx: Context, engine: EvolutionEngine, opts: CommandGateOptions, runtime: CommandRuntimeOptions): void;
 /**

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";
@@ -14,8 +15,10 @@ import { executeMountCommand, executeUnmountCommand } from "./mount-command.js";
 import { executeBenchmarkCommand } from "./benchmark-command.js";
 import { executeWrapupCommand } from "./wrapup-command.js";
 import { projectKeyOf } from "./project.js";
-import { loadUsage } from "./usage.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 [project|global]    list entries (default local staging; "project" = this project's cross-session store, "global" = cross-project store)
@@ -40,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",
@@ -323,6 +329,14 @@ 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}`);
             }
@@ -338,6 +352,12 @@ 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"),
                 });
@@ -354,6 +374,31 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
             case "wrapup": {
                 return await executeWrapupCommand(ctx, engine, invocation, runtime.promotionPolicy);
             }
+            case "pause":
+            case "resume": {
+                // The switch is independent of the static registration flag. A
+                // resume explicitly enables automatic snapshots; a pause leaves
+                // the enable bit intact so status explains the paused state.
+                const pausing = sub === "pause";
+                const defaultEnabled = runtime.autoReview ?? false;
+                const current = loadGateRuntime(engine.baseDir, defaultEnabled);
+                if (pausing && current.paused) {
+                    return success("auto-review gate is already paused (no change).");
+                }
+                if (!pausing && current.enabled && !current.paused) {
+                    return success("auto-review gate is already running (no change).");
+                }
+                saveGateRuntime(engine.baseDir, pausing, pausing ? current.enabled : true);
+                return success(pausing
+                    ? "auto-review gate paused: no automatic snapshots, fate assessments, or gate LLM calls until /evolve resume. Manual evolve_* tools and /evolve commands keep working."
+                    : "auto-review gate resumed: successful turns will produce incremental snapshots immediately.");
+            }
+            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);
             }
@@ -412,6 +457,99 @@ function demoteEntry(engine, id, sessionId, projectKey) {
     }
     return error(`entry ${id} not found in the global, project, or local store`);
 }
+/**
+ * Status answers whether the always-registered listener is enabled at runtime
+ * and what stores/retention it currently sees.
+ */
+function renderGateStatus(engine, sessionId, projectKey, runtime) {
+    const configuredDefault = runtime.autoReview === undefined ? "unknown" : runtime.autoReview ? "on" : "off";
+    const current = loadGateRuntime(engine.baseDir, runtime.autoReview ?? false);
+    const effective = current.paused ? "PAUSED (resume with /evolve resume)" : current.enabled ? "running" : "off (enable with /evolve resume)";
+    const gateLine = `gate: listener registered · config default ${configuredDefault} · runtime ${effective}`;
+    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);
     const failed = 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.d.ts

@@ -119,7 +119,7 @@ export interface FateApplyResult {
 export declare function applyLocalFates(engine: EvolutionEngine, sessionId: string, plan: FatePlan, localState: HarnessState, mode: FateApplyMode): FateApplyResult;
 /**
  * The gate's local-fate phase. Runs after the review phase on every gate
- * trigger (turn_interval / compact), subject to cadence and cooldown. All
+ * trigger (turn_snapshot / compact), subject to cadence and cooldown. All
  * failures are contained and recorded — a broken fate dimension never
  * disturbs the agent loop.
  */

package/lib/fate.js

@@ -192,7 +192,7 @@ export function applyLocalFates(engine, sessionId, plan, localState, mode) {
 }
 /**
  * The gate's local-fate phase. Runs after the review phase on every gate
- * trigger (turn_interval / compact), subject to cadence and cooldown. All
+ * trigger (turn_snapshot / compact), subject to cadence and cooldown. All
  * failures are contained and recorded — a broken fate dimension never
  * disturbs the agent loop.
  */
@@ -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);
@@ -249,7 +255,7 @@ export async function runLocalFatePhase(ctx, engine, agent, config, state, reaso
             rationale: `fate: ${assessment.rationale} (${applied.join("; ")})`,
             refinementId: results.map((result) => result.id).join(","),
         });
-        if (config.notifyOnAutoReview && reason === "turn_interval" && applied.length > 0) {
+        if (config.notifyOnAutoReview && (reason === "turn_snapshot" || reason === "turn_interval") && applied.length > 0) {
             notifyFateApplied(ctx, agent, applied);
         }
         return;
@@ -303,7 +309,7 @@ export async function runLocalFatePhase(ctx, engine, agent, config, state, reaso
             rationale: `fate: ${assessment.rationale} (${applied.join("; ")})`,
             refinementId: results.map((result) => result.id).join(","),
         });
-        if (config.notifyOnAutoReview && reason === "turn_interval") {
+        if (config.notifyOnAutoReview && (reason === "turn_snapshot" || reason === "turn_interval")) {
             notifyFateApplied(ctx, agent, applied);
         }
         return;
@@ -327,7 +333,7 @@ export function buildFateNotice(applied) {
         "请用一句话简短确认即可，不要调用任何工具。",
     ].join("\n");
 }
-/** Queue the follow-up notice turn (turn_interval only, like the review notice). */
+/** Queue the follow-up notice turn (successful-turn path only). */
 function notifyFateApplied(ctx, agent, applied) {
     try {
         agent.followup(createUserMessage({

package/lib/index.d.ts

@@ -10,14 +10,23 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     baseDir: z<string, string, "plain">;
     /** System-prompt section order for the evolution guidance. */
     sectionOrder: z<number, number, "defined">;
-    /** Enable the automatic review gate (off by default: it costs model calls). */
+    /** Initial automatic-review default when no runtime switch exists (off by default: it costs model calls). */
     autoReview: z<boolean, boolean, "defined">;
-    /** Gate runs when this many turns have passed since the last review. */
+    /** Legacy/local-fate cadence fallback; successful-turn review is snapshot-driven. */
     reviewIntervalTurns: z<number, number, "defined">;
     /** Trajectory slice handed to the gate, in characters. */
     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,19 +83,47 @@ 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">;
     /** System-prompt section order for the evolution guidance. */
     sectionOrder: z<number, number, "defined">;
-    /** Enable the automatic review gate (off by default: it costs model calls). */
+    /** Initial automatic-review default when no runtime switch exists (off by default: it costs model calls). */
     autoReview: z<boolean, boolean, "defined">;
-    /** Gate runs when this many turns have passed since the last review. */
+    /** Legacy/local-fate cadence fallback; successful-turn review is snapshot-driven. */
     reviewIntervalTurns: z<number, number, "defined">;
     /** Trajectory slice handed to the gate, in characters. */
     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

@@ -3,9 +3,9 @@
  *
  * Mounts the evolution engine, registers the model-facing evolve_* tools,
  * the human-facing /evolve command, the system-prompt guidance section, and
- * (opt-in) the automatic review gate that runs the planner on a turn
- * interval. Store roots default under the resolved DSH home; a deployment
- * may override `baseDir` in the plugin config.
+ * the automatic review gate. The listener is always registered, while its
+ * effective state is controlled by the runtime switch. Successful turns feed
+ * incremental snapshots through a per-session serial scheduler.
  */
 import { join } from "node:path";
 import z from "@deepseek-ai/schemastery";
@@ -29,14 +29,23 @@ export const Config = z.object({
     baseDir: z.string(),
     /** System-prompt section order for the evolution guidance. */
     sectionOrder: z.natural().default(118),
-    /** Enable the automatic review gate (off by default: it costs model calls). */
+    /** Initial automatic-review default when no runtime switch exists (off by default: it costs model calls). */
     autoReview: z.boolean().default(false),
-    /** Gate runs when this many turns have passed since the last review. */
+    /** Legacy/local-fate cadence fallback; successful-turn review is snapshot-driven. */
     reviewIntervalTurns: z.natural().default(6),
     /** Trajectory slice handed to the gate, in characters. */
     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,7 +134,7 @@ 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",
@@ -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 —
@@ -153,22 +177,28 @@ export function apply(ctx, config) {
     void restoreMounted(ctx, baseDir).catch((cause) => {
         ctx.logger("continual-evolve").warn(`mount restore failed: ${cause instanceof Error ? cause.message : String(cause)}`);
     });
-    if (config.autoReview) {
-        registerAutoReview(ctx, engine, {
-            intervalTurns: config.reviewIntervalTurns ?? 6,
-            maxInputChars: config.maxReviewInputChars ?? 40000,
-            budgetTokens: config.reviewBudgetTokens ?? 4096,
-            notifyOnAutoReview: config.notifyOnAutoReview ?? true,
-            localFate: config.localFate ?? true,
-            fateIntervalTurns: config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6,
-            goalBlockedWrapupTurns: config.goalBlockedWrapupTurns ?? 3,
-            promotionPolicy,
-            autoCase: config.autoCase ?? true,
-            rubricKey,
-            ...(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)`);
-    }
+    // The listener is always registered. `autoReview` is only the initial
+    // runtime default; `/evolve resume` can enable it without a profile edit
+    // or process restart, while manual tools and commands stay independent.
+    registerAutoReview(ctx, engine, {
+        intervalTurns: config.reviewIntervalTurns ?? 6,
+        enabledByDefault: config.autoReview ?? false,
+        maxInputChars: config.maxReviewInputChars ?? 40000,
+        budgetTokens: config.reviewBudgetTokens ?? 4096,
+        notifyOnAutoReview: config.notifyOnAutoReview ?? true,
+        localFate: config.localFate ?? true,
+        fateIntervalTurns: config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6,
+        goalBlockedWrapupTurns: config.goalBlockedWrapupTurns ?? 3,
+        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 } : {}),
+    });
+    const runtimeDefault = config.autoReview ?? false;
+    ctx.logger("continual-evolve").info(`continual-evolve auto-review registered (default ${runtimeDefault ? "on" : "off"}; successful-turn snapshots; local-fate ${config.localFate ?? true ? "on" : "off"} every ${config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6} turns)`);
     ctx.logger("continual-evolve").info(`continual-evolve mounted (baseDir=${baseDir})`);
 }
 //# sourceMappingURL=index.js.map

package/lib/llm-text.d.ts

@@ -9,6 +9,16 @@
  * and JSON parsing.
  */
 import type { Context } from "@deepseek-ai/cordis";
+import { type Message, type TokenUsage } from "@deepseek-ai/dsh-llm";
+/** Terminal outcome of one shared direct LLM call. */
+export type StreamTextOutcome = "success" | "max-tokens" | "error" | "aborted" | "empty";
+/** Provider usage and terminal result observed after the stream settles. */
+export interface StreamTextObservation {
+    usage?: TokenUsage;
+    outcome: StreamTextOutcome;
+}
+/** Diagnostic observer invoked before streamText returns or throws. */
+export type StreamTextUsageObserver = (observation: StreamTextObservation) => void;
 export interface StreamTextOptions {
     provider: string;
     model: string;
@@ -16,6 +26,19 @@ export interface StreamTextOptions {
     prompt: string;
     maxTokens?: number;
     signal?: AbortSignal | undefined;
+    /**
+     * Route A session prefix: session-derived messages sent before the
+     * trailing caller message so providers with prompt caching can serve
+     * the shared context at cache-read price. Empty/omitted keeps the
+     * legacy single-message request.
+     */
+    prefixMessages?: readonly Message[];
+    /**
+     * Observe the provider-reported usage and terminal outcome after the
+     * stream settles. The callback runs before success/error return and is
+     * diagnostic-only: throwing from it never changes the model call result.
+     */
+    onUsage?: StreamTextUsageObserver;
 }
 /**
  * Stream a single-turn text completion through `ctx.llm`. Forces