dsh-continual-evolve 0.7.0 → 0.7.1

package/lib/review.js

@@ -1,6 +1,9 @@
 import { extractJsonObject } from "./plan.js";
 import { formatHarnessStateForPrompt, historyForPrompt } from "./render.js";
+import { sessionEventsOf } from "./inject.js";
+import { buildPrefixMessages, detectPlannerRoute, resolvePrefixCache } from "./prefix-cache.js";
 import { streamText } from "./llm-text.js";
+import { createTokenUsageObserver } from "./token-usage.js";
 export const AUTO_REVIEW_SYSTEM_PROMPT = `You are the automatic /evolve review gate.
 
 Decide whether this checkpoint should run /evolve. Auto /evolve writes local
@@ -96,13 +99,29 @@ export async function reviewAutoRefine(ctx, options) {
     if (!options.trajectory || options.trajectory.length === 0) {
         throw new Error("evolve: review gate has no trajectory to judge");
     }
+    // Route A carries the judged conversation as a session-derived message
+    // prefix and drops the flat block; an empty prefix falls back to B.
+    const events = sessionEventsOf(agent);
+    const routing = resolvePrefixCache(options.prefixCache);
+    const route = detectPlannerRoute(events, routing.mode);
+    let prefixMessages = [];
+    if (route === "A") {
+        prefixMessages = buildPrefixMessages(events, {
+            ...(provider ? { provider } : {}),
+            ...(model ? { model } : {}),
+            maxChars: routing.maxChars,
+        });
+    }
+    const conversationBlock = prefixMessages.length > 0 ? "" : `<conversation>\n${options.trajectory}\n</conversation>`;
     const userPrompt = [
         `<trigger>\n${options.context.reason}; ${options.context.turnsSinceLastReview} turns since the last review\n</trigger>`,
         `<current_harness_state>\n${formatHarnessStateForPrompt(state)}\n</current_harness_state>`,
         `<refinement_history>\n${historyForPrompt(history)}\n</refinement_history>`,
-        `<conversation>\n${options.trajectory}\n</conversation>`,
+        conversationBlock,
         "Return shouldRefine=true when the trajectory contains evidence useful to this session's future turns. Prefer local edits; do not ask for global refinement here.",
-    ].join("\n\n");
+    ]
+        .filter(Boolean)
+        .join("\n\n");
     const text = await streamText(ctx, {
         provider,
         model,
@@ -110,6 +129,8 @@ export async function reviewAutoRefine(ctx, options) {
         prompt: userPrompt,
         maxTokens: options.budgetTokens ?? 8000,
         signal: options.signal,
+        ...(prefixMessages.length > 0 ? { prefixMessages } : {}),
+        ...(options.tokenUsage ? { onUsage: createTokenUsageObserver(options.tokenUsage, "review", provider, model) } : {}),
     });
     return parseAutoRefineReview(text);
 }

package/lib/runtime.d.ts

@@ -0,0 +1,24 @@
+export interface GateRuntime {
+    version: 1;
+    /** True while the human paused the automatic review gate. */
+    paused: boolean;
+    /** ISO timestamp of the last pause/resume write. */
+    updatedAt: string;
+}
+/** Full path of the runtime switch file. */
+export declare function runtimePath(baseDir: string): string;
+/**
+ * Load the runtime switch; fail open to "running" on any unreadable or
+ * malformed content (called on every gate trigger, so it must never throw
+ * for a bad file).
+ */
+export declare function loadGateRuntime(baseDir: string): GateRuntime;
+/**
+ * Persist the pause switch atomically (temp file + rename). Never throws
+ * for a bad file — callers (pause/resume commands) surface real IO errors
+ * through the command's own error path instead.
+ */
+export declare function saveGateRuntime(baseDir: string, paused: boolean): string;
+/** True while the human paused the automatic review gate (fail-open). */
+export declare function isGatePaused(baseDir: string): boolean;
+//# sourceMappingURL=runtime.d.ts.map

package/lib/runtime.js

@@ -0,0 +1,83 @@
+/**
+ * Runtime gate switch (#21 P2): a tiny human-owned file that pauses the
+ * automatic review gate without touching the plugin config or restarting.
+ *
+ * - file: `<baseDir>/evolve/runtime.json` (`{version, paused, updatedAt}`)
+ * - `/evolve pause` sets paused, `/evolve resume` clears it, `/evolve
+ *   status` shows it alongside the static patch config.
+ * - the gate consults it on every trigger (turn-interval AND compaction)
+ *   and stays dormant while paused — manual tools/commands keep working.
+ * - fail-open: a missing or corrupt file means "running". Pausing is the
+ *   exceptional state; a broken file must never silently wedge the gate
+ *   shut (the next save rewrites it cleanly).
+ */
+import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { EVOLVE_DIR } from "./store.js";
+const RUNTIME_FILE = "runtime.json";
+/** Full path of the runtime switch file. */
+export function runtimePath(baseDir) {
+    return join(baseDir, EVOLVE_DIR, RUNTIME_FILE);
+}
+function running() {
+    return { version: 1, paused: false, updatedAt: new Date(0).toISOString() };
+}
+/**
+ * Load the runtime switch; fail open to "running" on any unreadable or
+ * malformed content (called on every gate trigger, so it must never throw
+ * for a bad file).
+ */
+export function loadGateRuntime(baseDir) {
+    const path = runtimePath(baseDir);
+    if (!existsSync(path)) {
+        return running();
+    }
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            return running();
+        }
+        const record = raw;
+        return {
+            version: 1,
+            paused: record["paused"] === true,
+            updatedAt: typeof record["updatedAt"] === "string" ? record["updatedAt"] : new Date(0).toISOString(),
+        };
+    }
+    catch {
+        return running();
+    }
+}
+/**
+ * Persist the pause switch atomically (temp file + rename). Never throws
+ * for a bad file — callers (pause/resume commands) surface real IO errors
+ * through the command's own error path instead.
+ */
+export function saveGateRuntime(baseDir, paused) {
+    const path = runtimePath(baseDir);
+    mkdirSync(join(baseDir, EVOLVE_DIR), { recursive: true });
+    const tempPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const payload = { version: 1, paused, updatedAt: new Date().toISOString() };
+    writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    try {
+        renameSync(tempPath, path);
+    }
+    finally {
+        if (existsSync(tempPath)) {
+            unlinkSync(tempPath);
+        }
+    }
+    return path;
+}
+/** True while the human paused the automatic review gate (fail-open). */
+export function isGatePaused(baseDir) {
+    try {
+        return loadGateRuntime(baseDir).paused;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/lib/service.d.ts

@@ -5,6 +5,7 @@
  */
 import type { EntrySource, HarnessScope, RefinementProposal, RefinementResult } from "./types.js";
 import { applyRefinementProposal } from "./apply.js";
+import type { HistoryRetention } from "./store.js";
 export interface ApplyContext {
     scope: HarnessScope;
     sessionId?: string;
@@ -19,12 +20,21 @@ export interface EvolutionHooks {
     /** Called after every applied refinement (side-effect boundary: skills sync, etc.). */
     onApplied?: (result: RefinementResult) => void;
 }
-export declare function createEvolutionEngine(baseDir: string, hooks?: EvolutionHooks): {
+export interface EvolutionEngineOptions {
+    /**
+     * Storage-hygiene retention (#20): how many snapshots / JSONL tail
+     * lines each apply keeps. Resolved with generous defaults — rollback
+     * only needs recent snapshots and readers need a working window.
+     */
+    historyRetain?: Partial<HistoryRetention>;
+}
+export declare function createEvolutionEngine(baseDir: string, hooks?: EvolutionHooks, opts?: EvolutionEngineOptions): {
     load: (scope: HarnessScope, sessionId: string | undefined) => import("./types.js").HarnessState;
     apply: (scope: HarnessScope, sessionId: string | undefined, proposal: RefinementProposal, context?: ApplyContext) => RefinementResult;
     rollback: (scope: HarnessScope, sessionId: string | undefined, refinementId: string) => RefinementResult;
     history: (scope: HarnessScope, sessionId: string | undefined) => RefinementResult[];
     baseDir: string;
+    retention: HistoryRetention;
 };
 export type EvolutionEngine = ReturnType<typeof createEvolutionEngine>;
 //# sourceMappingURL=service.d.ts.map

package/lib/service.js

@@ -3,9 +3,10 @@ import { applyRefinementProposal } from "./apply.js";
 import { randomUUID } from "node:crypto";
 import { rollbackProposal } from "./rollback.js";
 import { loadHarnessState, saveHarnessState } from "./state.js";
-import { appendResult, loadResults, snapshotBefore, storePaths } from "./store.js";
+import { appendResult, loadResults, pruneJsonlFile, pruneSnapshots, resolveHistoryRetention, snapshotBefore, storePaths } from "./store.js";
 import { CONFLICT_BLOCK_SCORE, CONFLICT_WARN_SCORE, buildConflictNotice, mostSimilarEntry, secretLeakReason } from "./promotion.js";
-export function createEvolutionEngine(baseDir, hooks = {}) {
+export function createEvolutionEngine(baseDir, hooks = {}, opts = {}) {
+    const retention = resolveHistoryRetention(opts.historyRetain);
     /**
      * Load a scope's state. For `project` the `sessionId` parameter carries
      * the project key (see `resolveProjectKey` in project.ts); callers
@@ -100,6 +101,21 @@ export function createEvolutionEngine(baseDir, hooks = {}) {
         }
         saveHarnessState(paths.stateDir, state);
         appendResult(paths, result);
+        // Storage hygiene (#20): bound the append-only past at write time —
+        // snapshots keep the newest N, the per-store history keeps its tail.
+        // Best-effort (never throws): a prune failure must not fail the apply.
+        try {
+            pruneSnapshots(paths.snapshotsDir, retention.snapshots);
+        }
+        catch {
+            // ignored — the next apply retries
+        }
+        try {
+            pruneJsonlFile(paths.resultsPath, retention.refinements);
+        }
+        catch {
+            // ignored — the next apply retries
+        }
         hooks.onApplied?.(result);
         return result;
     }
@@ -119,6 +135,6 @@ export function createEvolutionEngine(baseDir, hooks = {}) {
     function history(scope, sessionId) {
         return loadResults(storePaths(baseDir, scope, sessionId));
     }
-    return { load, apply, rollback, history, baseDir };
+    return { load, apply, rollback, history, baseDir, retention };
 }
 //# sourceMappingURL=service.js.map

package/lib/store.d.ts

@@ -1,5 +1,29 @@
 import type { HarnessScope, RefinementResult } from "./types.js";
 export declare const EVOLVE_DIR = "evolve";
+/**
+ * Storage-hygiene defaults (#20): history used to grow append-only without
+ * bound (dozens of full-state snapshot copies, unbounded JSONL). Retention
+ * is count-based and generous — rollback only ever needs recent snapshots
+ * and readers (`failures.ts` over reviews) need a working window, not the
+ * full past. Tunable via the `historyRetain` plugin config.
+ */
+export declare const DEFAULT_SNAPSHOT_RETAIN = 20;
+export declare const DEFAULT_REFINEMENTS_RETAIN = 500;
+export declare const DEFAULT_REVIEWS_RETAIN = 500;
+export declare const DEFAULT_TOKEN_USAGE_RETAIN = 500;
+/** Resolved retention set: how many snapshots / JSONL tail lines to keep. */
+export interface HistoryRetention {
+    /** Full-state snapshots kept per store (oldest pruned first). */
+    snapshots: number;
+    /** Tail lines kept in each store's refinements.jsonl. */
+    refinements: number;
+    /** Tail lines kept in the shared reviews.jsonl audit trail. */
+    reviews: number;
+    /** Tail lines kept in the direct-call token-usage.jsonl ledger. */
+    tokenUsage: number;
+}
+/** Defaults applied for absent / non-positive retention fields (fail loud never: clamp, don't throw). */
+export declare function resolveHistoryRetention(raw?: Partial<HistoryRetention>): HistoryRetention;
 export interface StorePaths {
     /** Directory holding harness_state.json. */
     stateDir: string;
@@ -19,6 +43,20 @@ export declare function storePaths(baseDir: string, scope: HarnessScope, session
 export declare function snapshotBefore(paths: StorePaths, refinementId: string): void;
 /** Append an applied result to the store's JSONL history. */
 export declare function appendResult(paths: StorePaths, result: RefinementResult): void;
+/**
+ * Prune a store's snapshots to the newest `retain` files (by mtime, oldest
+ * first). Best-effort: a missing directory or an unlink failure never breaks
+ * the apply path — the next apply retries.
+ */
+export declare function pruneSnapshots(snapshotsDir: string, retain: number): void;
+/**
+ * Truncate a JSONL file to its last `retain` non-empty lines. No-op when the
+ * file is missing or already within budget — the common case costs one
+ * read and no write.
+ */
+export declare function pruneJsonlFile(path: string, retain: number): void;
+/** Reviews audit-trail path shared by the gate, fate, and tool events. */
+export declare function reviewsPath(baseDir: string): string;
 /** Read the applied results history; malformed lines are skipped, never fatal. */
 export declare function loadResults(paths: StorePaths): RefinementResult[];
 //# sourceMappingURL=store.d.ts.map

package/lib/store.js

@@ -13,11 +13,32 @@
  * pre-apply state is copied to `snapshots/<refinementId>.json`. The model has
  * no way to skip it — it runs inside the service, not in a prompt.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { sanitizeProjectKey } from "./project.js";
 import { stateFilePath } from "./state.js";
 export const EVOLVE_DIR = "evolve";
+/**
+ * Storage-hygiene defaults (#20): history used to grow append-only without
+ * bound (dozens of full-state snapshot copies, unbounded JSONL). Retention
+ * is count-based and generous — rollback only ever needs recent snapshots
+ * and readers (`failures.ts` over reviews) need a working window, not the
+ * full past. Tunable via the `historyRetain` plugin config.
+ */
+export const DEFAULT_SNAPSHOT_RETAIN = 20;
+export const DEFAULT_REFINEMENTS_RETAIN = 500;
+export const DEFAULT_REVIEWS_RETAIN = 500;
+export const DEFAULT_TOKEN_USAGE_RETAIN = 500;
+/** Defaults applied for absent / non-positive retention fields (fail loud never: clamp, don't throw). */
+export function resolveHistoryRetention(raw) {
+    const pick = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+    return {
+        snapshots: pick(raw?.snapshots, DEFAULT_SNAPSHOT_RETAIN),
+        refinements: pick(raw?.refinements, DEFAULT_REFINEMENTS_RETAIN),
+        reviews: pick(raw?.reviews, DEFAULT_REVIEWS_RETAIN),
+        tokenUsage: pick(raw?.tokenUsage, DEFAULT_TOKEN_USAGE_RETAIN),
+    };
+}
 /**
  * Resolve store paths for a scope. For `project` the `sessionId` parameter
  * carries the project key (see {@link resolveProjectKey} in project.ts) —
@@ -49,6 +70,72 @@ export function appendResult(paths, result) {
     mkdirSync(paths.stateDir, { recursive: true });
     writeFileSync(paths.resultsPath, `${JSON.stringify(result)}\n`, { encoding: "utf8", flag: "a" });
 }
+/**
+ * Prune a store's snapshots to the newest `retain` files (by mtime, oldest
+ * first). Best-effort: a missing directory or an unlink failure never breaks
+ * the apply path — the next apply retries.
+ */
+export function pruneSnapshots(snapshotsDir, retain) {
+    const keep = Math.floor(retain);
+    if (!(keep > 0) || !existsSync(snapshotsDir))
+        return;
+    let files;
+    try {
+        files = readdirSync(snapshotsDir).filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return; // unreadable directory — leave it for the next attempt
+    }
+    if (files.length <= keep)
+        return;
+    const withTime = [];
+    for (const file of files) {
+        try {
+            withTime.push({ file, mtime: statSync(join(snapshotsDir, file)).mtimeMs });
+        }
+        catch {
+            // unstatable file — keep it rather than delete blindly
+        }
+    }
+    withTime.sort((a, b) => a.mtime - b.mtime);
+    for (const victim of withTime.slice(0, Math.max(0, withTime.length - keep))) {
+        try {
+            unlinkSync(join(snapshotsDir, victim.file));
+        }
+        catch {
+            // one bad unlink must not stop the sweep or the apply path
+        }
+    }
+}
+/**
+ * Truncate a JSONL file to its last `retain` non-empty lines. No-op when the
+ * file is missing or already within budget — the common case costs one
+ * read and no write.
+ */
+export function pruneJsonlFile(path, retain) {
+    const keep = Math.floor(retain);
+    if (!(keep > 0) || !existsSync(path))
+        return;
+    let lines;
+    try {
+        lines = readFileSync(path, "utf8").split("\n").filter((l) => l.trim().length > 0);
+    }
+    catch {
+        return; // unreadable file — leave it for the next attempt
+    }
+    if (lines.length <= keep)
+        return;
+    try {
+        writeFileSync(path, `${lines.slice(-keep).join("\n")}\n`, "utf8");
+    }
+    catch {
+        // truncation failure must not break the write path that called it
+    }
+}
+/** Reviews audit-trail path shared by the gate, fate, and tool events. */
+export function reviewsPath(baseDir) {
+    return join(baseDir, EVOLVE_DIR, "reviews.jsonl");
+}
 /** Read the applied results history; malformed lines are skipped, never fatal. */
 export function loadResults(paths) {
     if (!existsSync(paths.resultsPath)) {

package/lib/token-usage.d.ts

@@ -0,0 +1,68 @@
+import type { TokenUsage } from "@deepseek-ai/dsh-llm";
+import type { StreamTextObservation, StreamTextUsageObserver } from "./llm-text.js";
+export declare const TOKEN_USAGE_LEDGER_VERSION = 1;
+/** Plugin-owned direct call paths represented in the ledger. */
+export declare const TOKEN_USAGE_PHASES: readonly ["review", "planner", "wrapup", "fate"];
+export type TokenUsagePhase = (typeof TOKEN_USAGE_PHASES)[number];
+/** Whether the provider supplied a usage sample; missing is never treated as zero. */
+export type TokenUsageStatus = "reported" | "missing";
+/** How the exact full-call total was obtained. */
+export type TokenTotalSource = "provider" | "derived" | "unavailable";
+/** One retained direct-call observation. */
+export interface TokenUsageRecord {
+    version: typeof TOKEN_USAGE_LEDGER_VERSION;
+    timestamp: string;
+    sessionId: string;
+    phase: TokenUsagePhase;
+    provider: string;
+    model: string;
+    outcome: StreamTextObservation["outcome"];
+    usageStatus: TokenUsageStatus;
+    /** Absent exactly when {@link usageStatus} is `missing`. */
+    usage?: TokenUsage;
+    totalSource: TokenTotalSource;
+}
+/** Caller-owned destination and failure hook; phase/provider/model are supplied by the call site. */
+export interface TokenUsageTarget {
+    baseDir: string;
+    sessionId: string;
+    retain: number;
+    onError?: (cause: unknown) => void;
+}
+/** Loaded retained window plus corrupt-line count for honest coverage reporting. */
+export interface LoadedTokenUsage {
+    records: TokenUsageRecord[];
+    corruptLines: number;
+}
+/** Aggregate provider-reported buckets over a retained ledger window. */
+export interface TokenUsageTotals {
+    calls: number;
+    reportedCalls: number;
+    missingUsageCalls: number;
+    uncachedInputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    totalTokens: number;
+}
+/** Absolute path of the direct-call token ledger. */
+export declare function tokenUsagePath(baseDir: string): string;
+/** Exact full-call total, with the old-peer fallback only when `totalTokens` is absent. */
+export declare function exactTokenTotal(usage: TokenUsage): number;
+/** Build the observer attached to one `streamText` call. Errors are diagnostic-only. */
+export declare function createTokenUsageObserver(target: TokenUsageTarget, phase: TokenUsagePhase, provider: string, model: string): StreamTextUsageObserver;
+/**
+ * Append one call and enforce the dedicated tail budget. Append + conditional
+ * prune stay in one synchronous block, so concurrent async callers in one DSH
+ * process cannot interleave the read/truncate/write. Multiple DSH processes
+ * sharing one baseDir are outside the plugin's storage contract.
+ */
+export declare function appendTokenUsage(target: TokenUsageTarget, record: TokenUsageRecord): void;
+/** Load valid records from the retained ledger; malformed lines never break `/evolve usage`. */
+export declare function loadTokenUsage(baseDir: string): LoadedTokenUsage;
+/** Sum exact provider-reported buckets without double-counting reasoning or cache fields. */
+export declare function aggregateTokenUsage(records: readonly TokenUsageRecord[]): TokenUsageTotals;
+/** Render the human-facing direct-call ledger section. */
+export declare function renderTokenUsageReport(ledger: LoadedTokenUsage, retain: number): string[];
+//# sourceMappingURL=token-usage.d.ts.map

package/lib/token-usage.js

@@ -0,0 +1,211 @@
+/**
+ * Provider-reported token accounting for plugin-owned direct LLM calls.
+ *
+ * The review gate, planner, wrap-up command, and local-fate classifier all use
+ * the shared `streamText` helper. These calls do not belong to an Agent turn
+ * (they pass no sessionId), so the host session token-meter cannot attribute
+ * them. This ledger records the exact `TokenUsage` emitted by the adapter at
+ * the one shared stream boundary instead.
+ *
+ * Storage: `<baseDir>/evolve/token-usage.jsonl`. The file contains route and
+ * count metadata only — never prompts, responses, or tool arguments — and is
+ * trimmed to its dedicated retention budget after each synchronous append.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { EVOLVE_DIR, pruneJsonlFile } from "./store.js";
+const TOKEN_USAGE_FILE = "token-usage.jsonl";
+export const TOKEN_USAGE_LEDGER_VERSION = 1;
+/** Plugin-owned direct call paths represented in the ledger. */
+export const TOKEN_USAGE_PHASES = ["review", "planner", "wrapup", "fate"];
+/** Absolute path of the direct-call token ledger. */
+export function tokenUsagePath(baseDir) {
+    return join(baseDir, EVOLVE_DIR, TOKEN_USAGE_FILE);
+}
+/** Exact full-call total, with the old-peer fallback only when `totalTokens` is absent. */
+export function exactTokenTotal(usage) {
+    if (usage.totalTokens !== undefined)
+        return usage.totalTokens;
+    return usage.inputTokens + usage.outputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0);
+}
+/** Build the observer attached to one `streamText` call. Errors are diagnostic-only. */
+export function createTokenUsageObserver(target, phase, provider, model) {
+    return (observation) => {
+        try {
+            appendTokenUsage(target, {
+                version: TOKEN_USAGE_LEDGER_VERSION,
+                timestamp: new Date().toISOString(),
+                sessionId: target.sessionId,
+                phase,
+                provider,
+                model,
+                outcome: observation.outcome,
+                usageStatus: observation.usage ? "reported" : "missing",
+                ...(observation.usage ? { usage: observation.usage } : {}),
+                totalSource: observation.usage
+                    ? observation.usage.totalTokens !== undefined
+                        ? "provider"
+                        : "derived"
+                    : "unavailable",
+            });
+        }
+        catch (cause) {
+            target.onError?.(cause);
+        }
+    };
+}
+/**
+ * Append one call and enforce the dedicated tail budget. Append + conditional
+ * prune stay in one synchronous block, so concurrent async callers in one DSH
+ * process cannot interleave the read/truncate/write. Multiple DSH processes
+ * sharing one baseDir are outside the plugin's storage contract.
+ */
+export function appendTokenUsage(target, record) {
+    if (!isTokenUsageRecord(record)) {
+        throw new Error("evolve: refusing to append an invalid token-usage record");
+    }
+    const dir = join(target.baseDir, EVOLVE_DIR);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(tokenUsagePath(target.baseDir), `${JSON.stringify(record)}\n`, {
+        encoding: "utf8",
+        flag: "a",
+        mode: 0o600,
+    });
+    pruneJsonlFile(tokenUsagePath(target.baseDir), target.retain);
+}
+/** Load valid records from the retained ledger; malformed lines never break `/evolve usage`. */
+export function loadTokenUsage(baseDir) {
+    const path = tokenUsagePath(baseDir);
+    if (!existsSync(path))
+        return { records: [], corruptLines: 0 };
+    let lines;
+    try {
+        lines = readFileSync(path, "utf8").split("\n");
+    }
+    catch {
+        return { records: [], corruptLines: 0 };
+    }
+    const records = [];
+    let corruptLines = 0;
+    for (const line of lines) {
+        if (line.trim().length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (isTokenUsageRecord(parsed))
+                records.push(parsed);
+            else
+                corruptLines += 1;
+        }
+        catch {
+            corruptLines += 1;
+        }
+    }
+    return { records, corruptLines };
+}
+/** Sum exact provider-reported buckets without double-counting reasoning or cache fields. */
+export function aggregateTokenUsage(records) {
+    const totals = {
+        calls: records.length,
+        reportedCalls: 0,
+        missingUsageCalls: 0,
+        uncachedInputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        outputTokens: 0,
+        reasoningTokens: 0,
+        totalTokens: 0,
+    };
+    for (const record of records) {
+        if (record.usageStatus === "missing" || !record.usage) {
+            totals.missingUsageCalls += 1;
+            continue;
+        }
+        totals.reportedCalls += 1;
+        totals.uncachedInputTokens += record.usage.inputTokens;
+        totals.cacheReadTokens += record.usage.cacheReadTokens ?? 0;
+        totals.cacheWriteTokens += record.usage.cacheWriteTokens ?? 0;
+        totals.outputTokens += record.usage.outputTokens;
+        totals.reasoningTokens += record.usage.reasoningTokens ?? 0;
+        totals.totalTokens += exactTokenTotal(record.usage);
+    }
+    return totals;
+}
+/** Render the human-facing direct-call ledger section. */
+export function renderTokenUsageReport(ledger, retain) {
+    const { records, corruptLines } = ledger;
+    if (records.length === 0) {
+        const corrupt = corruptLines > 0 ? ` ${corruptLines} corrupt line(s) ignored.` : "";
+        return [
+            `direct LLM token usage: no valid calls in the retained tail.${corrupt}`,
+            `window: last ${retain} call(s), not a lifetime total.`,
+            "scope: review/planner/wrapup/fate only; host benchmark subagents, their agent-loop calls, and per-entry injection cost are excluded.",
+        ];
+    }
+    const totals = aggregateTokenUsage(records);
+    const lines = [
+        `direct LLM token usage: ${totals.calls} valid calls (${totals.reportedCalls} reported usage, ${totals.missingUsageCalls} missing)${corruptLines > 0 ? `; ${corruptLines} corrupt line(s) ignored` : ""}`,
+        `  uncached input: ${totals.uncachedInputTokens}`,
+        `  cache read:     ${totals.cacheReadTokens}`,
+        `  cache write:    ${totals.cacheWriteTokens}`,
+        `  output:         ${totals.outputTokens}`,
+        `  reasoning:      ${totals.reasoningTokens}${records.some((record) => record.usageStatus === "reported" && record.usage?.reasoningTokens === undefined) ? " (partial provider reports)" : ""}`,
+        `  exact total:    ${totals.totalTokens} (reported calls only)`,
+        `window: last ${retain} call(s), not a lifetime total.`,
+        "by phase:",
+    ];
+    for (const phase of TOKEN_USAGE_PHASES) {
+        const phaseRecords = records.filter((record) => record.phase === phase);
+        if (phaseRecords.length === 0)
+            continue;
+        const phaseTotals = aggregateTokenUsage(phaseRecords);
+        lines.push(`  ${phase.padEnd(7)} ${phaseTotals.calls} calls · ${phaseTotals.totalTokens} tokens`);
+    }
+    const last = records.at(-1);
+    if (last) {
+        const lastTotal = last.usage ? exactTokenTotal(last.usage) : "usage unavailable";
+        lines.push(`last: ${last.phase} ${last.provider}/${last.model} · ${last.outcome} · ${lastTotal} tokens · ${last.timestamp}`);
+    }
+    lines.push("scope: review/planner/wrapup/fate only; host benchmark subagents, their agent-loop calls, and per-entry injection cost are excluded.");
+    return lines;
+}
+function isTokenUsageRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    if (record["version"] !== TOKEN_USAGE_LEDGER_VERSION ||
+        typeof record["timestamp"] !== "string" ||
+        typeof record["sessionId"] !== "string" ||
+        typeof record["provider"] !== "string" ||
+        typeof record["model"] !== "string" ||
+        typeof record["outcome"] !== "string" ||
+        !TOKEN_USAGE_PHASES.includes(record["phase"]) ||
+        !["success", "max-tokens", "error", "aborted", "empty"].includes(record["outcome"]) ||
+        !["reported", "missing"].includes(record["usageStatus"]) ||
+        !["provider", "derived", "unavailable"].includes(record["totalSource"])) {
+        return false;
+    }
+    if (record["usageStatus"] === "missing") {
+        return record["usage"] === undefined && record["totalSource"] === "unavailable";
+    }
+    if (!isTokenUsage(record["usage"]))
+        return false;
+    const expectedSource = record["usage"]["totalTokens"] !== undefined ? "provider" : "derived";
+    return record["totalSource"] === expectedSource;
+}
+function isCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isTokenUsage(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const usage = value;
+    if (!isCount(usage["inputTokens"]) || !isCount(usage["outputTokens"]))
+        return false;
+    for (const key of ["totalTokens", "cacheReadTokens", "cacheWriteTokens", "reasoningTokens"]) {
+        if (usage[key] !== undefined && !isCount(usage[key]))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=token-usage.js.map