@axlsdk/axl 0.26.0 → 0.27.0

package/dist/index.js

@@ -348,7 +348,7 @@ var sharedGuard = typeof installedGuard === "object" && installedGuard !== null
 var buildPath = typeof __AXL_BUILD_PATH__ === "string" ? __AXL_BUILD_PATH__ : "<source>";
 var thisCopy = {
   path: buildPath.startsWith("file:") ? fileURLToPath(buildPath) : buildPath,
-  version: true ? "0.26.0" : "unknown"
+  version: true ? "0.27.0" : "unknown"
 };
 function warnCrossCopy(other, joined) {
   if (other === thisCopy) return;
@@ -12615,8 +12615,17 @@ function detectDroppedRefinements(schema) {
 var DOCS_URL = "docs/observability.md#schema-diagnostics";
 var MAX_WARNED_KEYS = 2048;
 var warnedDiagnosticKeys = /* @__PURE__ */ new Set();
+var silencedDepth = 0;
+function withDiagnosticsSilenced(fn) {
+  silencedDepth++;
+  try {
+    return fn();
+  } finally {
+    silencedDepth--;
+  }
+}
 function warnDiagnosticOnce(key, message, silent, docs = DOCS_URL) {
-  if (silent || process.env.AXL_DIAGNOSTICS_SILENT === "true") return;
+  if (silent || silencedDepth > 0 || process.env.AXL_DIAGNOSTICS_SILENT === "true") return;
   if (warnedDiagnosticKeys.has(key)) return;
   if (warnedDiagnosticKeys.size >= MAX_WARNED_KEYS) warnedDiagnosticKeys.clear();
   warnedDiagnosticKeys.add(key);
@@ -18680,10 +18689,135 @@ import { AsyncLocalStorage as AsyncLocalStorage4 } from "async_hooks";
 import { appendFileSync, mkdirSync as mkdirSync2 } from "fs";
 import { dirname } from "path";
 
+// src/state/retention.ts
+var PRUNE_BATCH = 100;
+var DEFAULT_MEMORY_MAX_EXECUTIONS = 1e3;
+function warnExecutionRetentionUnset(storeName) {
+  warnDiagnosticOnce(
+    `execution_retention_unset\0${storeName}`,
+    `${storeName} keeps execution history forever because no retention is set; set ttls.executionHistory${storeName === "RedisStore" ? " (or defaultTtl)" : ""} to a number of seconds, or ttls.executionHistory to null to keep it forever without this warning.`,
+    void 0,
+    "docs/migration/execution-history-retention.md#silencing-the-retention-warning"
+  );
+}
+function resolveTtl(storeName, category, value) {
+  if (value === void 0 || value === null) return null;
+  if (typeof value !== "number") {
+    throw new AxlError(
+      "INVALID_CONFIG",
+      `${storeName}: ttls.${category} must be a positive number of seconds or null; got ${typeof value}`
+    );
+  }
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new AxlError(
+      "INVALID_CONFIG",
+      `${storeName}: ttls.${category} must be a positive number of seconds or null; got ${value}`
+    );
+  }
+  return value;
+}
+function resolveHistoryTtls(storeName, ttls) {
+  if (ttls !== void 0 && (ttls === null || typeof ttls !== "object")) {
+    throw new AxlError(
+      "INVALID_CONFIG",
+      `${storeName}: ttls must be an object; got ${ttls === null ? "null" : typeof ttls}`
+    );
+  }
+  return {
+    executionHistory: resolveTtl(storeName, "executionHistory", ttls?.executionHistory),
+    evalHistory: resolveTtl(storeName, "evalHistory", ttls?.evalHistory)
+  };
+}
+function expiryFrom(now, ttlSeconds) {
+  return ttlSeconds === null ? null : now + Math.round(ttlSeconds * 1e3);
+}
+function isExpired(expiresAt, now) {
+  return expiresAt !== null && now >= expiresAt;
+}
+var DEFAULT_RETENTION_BATCH_SIZE = 500;
+function resolveHistoryRetentionOptions(storeName, options) {
+  const method = `${storeName}.applyHistoryRetention()`;
+  if (options === null || typeof options !== "object") {
+    throw new AxlError("INVALID_ARGUMENT", `${method} options must be an object`);
+  }
+  const { kind, batchSize, cursor } = options;
+  if (kind !== "executions" && kind !== "evals") {
+    throw new AxlError(
+      "INVALID_ARGUMENT",
+      `${method} kind must be 'executions' or 'evals'; got ${String(kind)}`
+    );
+  }
+  if (batchSize !== void 0 && !(typeof batchSize === "number" && Number.isSafeInteger(batchSize) && batchSize > 0)) {
+    throw new AxlError(
+      "INVALID_ARGUMENT",
+      `${method} batchSize must be a positive integer; got ${String(batchSize)}`
+    );
+  }
+  let parsedCursor;
+  if (cursor !== void 0 && cursor !== null) {
+    const candidate = cursor;
+    if (typeof candidate !== "object" || typeof candidate.time !== "number" || !Number.isFinite(candidate.time) || typeof candidate.id !== "string") {
+      throw new AxlError(
+        "INVALID_ARGUMENT",
+        `${method} cursor must be the { time, id } cursor returned by the previous call`
+      );
+    }
+    parsedCursor = { time: candidate.time, id: candidate.id };
+  }
+  return {
+    kind,
+    batchSize: batchSize ?? DEFAULT_RETENTION_BATCH_SIZE,
+    cursor: parsedCursor
+  };
+}
+function retentionForUntimedRecord(lastSavedAt, ttlSeconds, now) {
+  const expiresAt = lastSavedAt + Math.round(ttlSeconds * 1e3);
+  return isExpired(expiresAt, now) ? { expired: true } : { expired: false, expiresAt };
+}
+function executionLastSavedAt(record) {
+  return typeof record.completedAt === "number" && Number.isFinite(record.completedAt) ? record.completedAt : record.startedAt;
+}
+function compareExecutionsNewestFirst(a, b) {
+  if (a.startedAt !== b.startedAt) return b.startedAt - a.startedAt;
+  return compareCodePoints(b.executionId, a.executionId);
+}
+function compareRetentionPositions(a, b) {
+  if (a.time !== b.time) return a.time - b.time;
+  return compareCodePoints(a.id, b.id);
+}
+function compareCodePoints(a, b) {
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const x = a.charCodeAt(i);
+    const y = b.charCodeAt(i);
+    if (x !== y) return codePointRank(x) - codePointRank(y);
+  }
+  return a.length - b.length;
+}
+function codePointRank(unit) {
+  if (unit >= 57344) return unit - 2048;
+  if (unit >= 55296) return unit + 8192;
+  return unit;
+}
+
 // src/state/memory.ts
 import { writeFileSync, readFileSync, existsSync, mkdirSync, unlinkSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
+function compareOldestFirst(a, b) {
+  return compareExecutionsNewestFirst(b, a);
+}
+function resolveMaxExecutions(value) {
+  if (value === void 0) return DEFAULT_MEMORY_MAX_EXECUTIONS;
+  if (value === Infinity) return Infinity;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw new AxlError(
+      "INVALID_CONFIG",
+      `MemoryStore: maxExecutions must be a positive integer or Infinity; got ${typeof value === "number" ? value : typeof value}`
+    );
+  }
+  return value;
+}
 var AWAIT_HUMAN_TEMP_DIR = join(tmpdir(), "axl-memory-store");
 var AWAIT_HUMAN_TEMP_FILE = join(AWAIT_HUMAN_TEMP_DIR, "await-human-state.json");
 var MemoryStore = class {
@@ -18693,9 +18827,32 @@ var MemoryStore = class {
   decisions = /* @__PURE__ */ new Map();
   executionStates = /* @__PURE__ */ new Map();
   memories = /* @__PURE__ */ new Map();
+  /**
+   * Iteration order is last-save order: a save deletes and re-inserts its key.
+   * With one retention per store and a clock that does not run backwards, that
+   * is also expiry order, which lets the prune stop at the first live record.
+   */
   executionHistory = /* @__PURE__ */ new Map();
+  /** Every key in `executionHistory`, sorted oldest first in listing order. */
+  executionOrder = [];
+  /**
+   * Iteration order is first-write order (a re-save keeps the key's position
+   * and its expiry), which is also expiry order for the same reason as above.
+   */
   evalHistory = /* @__PURE__ */ new Map();
-  constructor() {
+  ttls;
+  maxExecutions;
+  now;
+  constructor(options) {
+    this.ttls = resolveHistoryTtls("MemoryStore", options?.ttls);
+    this.maxExecutions = resolveMaxExecutions(options?.maxExecutions);
+    if (options?.now !== void 0 && typeof options.now !== "function") {
+      throw new AxlError(
+        "INVALID_CONFIG",
+        "MemoryStore: now must be a function returning epoch milliseconds"
+      );
+    }
+    this.now = options?.now ?? (() => Date.now());
     this.loadPersistedState();
   }
   async saveCheckpoint(executionId, name, data) {
@@ -18792,23 +18949,43 @@ var MemoryStore = class {
   }
   // ── Execution History ──────────────────────────────────────────────
   async saveExecution(execution) {
-    const normalized = normalizeStoredExecution({
-      ...execution,
-      eventSchemaVersion: getExecutionEventSchemaVersion(execution)
+    const now = this.now();
+    const normalized = structuredClone(
+      normalizeStoredExecution({
+        ...execution,
+        eventSchemaVersion: getExecutionEventSchemaVersion(execution)
+      })
+    );
+    this.removeExecutionRecord(normalized.executionId);
+    this.executionHistory.set(normalized.executionId, {
+      record: normalized,
+      expiresAt: expiryFrom(now, this.ttls.executionHistory)
     });
-    this.executionHistory.set(execution.executionId, structuredClone(normalized));
+    this.insertExecutionOrder(normalized);
+    this.pruneExpiredExecutions(now);
+    this.evictOverflowExecutions();
   }
   async getExecution(executionId) {
-    const exec = this.executionHistory.get(executionId);
-    return exec ? normalizeStoredExecution(structuredClone(exec)) : null;
-  }
-  async listExecutions(limit) {
-    const sorted = [...this.executionHistory.values()].sort((a, b) => b.startedAt - a.startedAt);
-    const result = limit ? sorted.slice(0, limit) : sorted;
-    return result.map((e) => normalizeStoredExecution(structuredClone(e)));
+    const stored = this.executionHistory.get(executionId);
+    if (!stored || isExpired(stored.expiresAt, this.now())) return null;
+    return normalizeStoredExecution(structuredClone(stored.record));
+  }
+  /** Supports `listExecutions(limit, { cursor })`. */
+  historyPaging = true;
+  async listExecutions(limit, options) {
+    const now = this.now();
+    const max = limit ? limit : Infinity;
+    const result = [];
+    const start = options?.cursor !== void 0 ? this.executionOrderLowerBound(options.cursor) - 1 : this.executionOrder.length - 1;
+    for (let i = start; i >= 0 && result.length < max; i--) {
+      const stored = this.executionHistory.get(this.executionOrder[i].executionId);
+      if (isExpired(stored.expiresAt, now)) continue;
+      result.push(normalizeStoredExecution(structuredClone(stored.record)));
+    }
+    return result;
   }
   async deleteExecution(executionId) {
-    const removedHistory = this.executionHistory.delete(executionId);
+    const removedHistory = this.removeExecutionRecord(executionId);
     const removedCheckpoints = this.checkpoints.delete(executionId);
     const removedState = this.executionStates.delete(executionId);
     const removedStreaming = this.streamingEvents.delete(executionId);
@@ -18819,26 +18996,193 @@ var MemoryStore = class {
     return removedHistory || removedCheckpoints || removedState || removedStreaming || removedDecision;
   }
   // ── Eval History ──────────────────────────────────────────────────
+  /**
+   * Write an eval history row. Retention counts from the row's first write:
+   * re-saving a live row keeps its expiry (and its position in expiry order).
+   * A row that has already expired is replaced as a new one.
+   */
   async saveEvalResult(entry) {
-    this.evalHistory.set(entry.id, structuredClone(entry));
+    const now = this.now();
+    const existing = this.evalHistory.get(entry.id);
+    if (existing && !isExpired(existing.expiresAt, now)) {
+      this.evalHistory.set(entry.id, {
+        entry: structuredClone(entry),
+        expiresAt: existing.expiresAt
+      });
+    } else {
+      this.evalHistory.delete(entry.id);
+      this.evalHistory.set(entry.id, {
+        entry: structuredClone(entry),
+        expiresAt: expiryFrom(now, this.ttls.evalHistory)
+      });
+    }
+    this.pruneExpiredEvals(now);
   }
-  /** Update-only write: see `StateStore.updateEvalResult`. */
+  /** Update-only write: see `StateStore.updateEvalResult`. Never changes retention. */
   async updateEvalResult(entry) {
-    if (!this.evalHistory.has(entry.id)) return false;
-    this.evalHistory.set(entry.id, structuredClone(entry));
+    const existing = this.evalHistory.get(entry.id);
+    if (!existing || isExpired(existing.expiresAt, this.now())) return false;
+    this.evalHistory.set(entry.id, {
+      entry: structuredClone(entry),
+      expiresAt: existing.expiresAt
+    });
     return true;
   }
   async listEvalResults(limit) {
-    const sorted = [...this.evalHistory.values()].sort((a, b) => b.timestamp - a.timestamp);
+    const now = this.now();
+    const sorted = [...this.evalHistory.values()].filter((stored) => !isExpired(stored.expiresAt, now)).map((stored) => stored.entry).sort((a, b) => b.timestamp - a.timestamp);
     const result = limit ? sorted.slice(0, limit) : sorted;
     return result.map((e) => structuredClone(e));
   }
   async deleteEvalResult(id) {
     return this.evalHistory.delete(id);
   }
-  /** In-memory history never expires on its own — only existence is meaningful. */
+  /** Existence plus the expiry stored at the row's first write, if any. */
   async getEvalRetention(id) {
-    return { exists: this.evalHistory.has(id) };
+    const stored = this.evalHistory.get(id);
+    if (!stored || isExpired(stored.expiresAt, this.now())) return { exists: false };
+    return stored.expiresAt === null ? { exists: true } : { exists: true, expiresAt: stored.expiresAt };
+  }
+  // ── History maintenance ───────────────────────────────────────────
+  /**
+   * See `StateStore.applyHistoryRetention`. Every record this store holds was
+   * saved under the retention it was constructed with, so in practice a run
+   * finds nothing to expire or arm; the method exists so the same maintenance
+   * code works against every built-in store. There is no separate index, so
+   * `indexed` and `deadIndexEntries` are always `0`.
+   *
+   * An armed record keeps its place in last-save order, which is also where
+   * its expiry (last save + retention) belongs, so the prune-on-save order
+   * still holds.
+   */
+  async applyHistoryRetention(options) {
+    const { kind, batchSize, cursor } = resolveHistoryRetentionOptions("MemoryStore", options);
+    const now = this.now();
+    let expired = 0;
+    let armed = 0;
+    let positions;
+    if (kind === "executions") {
+      let start = 0;
+      if (cursor !== void 0) {
+        const key = { startedAt: cursor.time, executionId: cursor.id };
+        start = this.executionOrderLowerBound(key);
+        const at = this.executionOrder[start];
+        if (at !== void 0 && compareOldestFirst(at, key) === 0) start++;
+      }
+      positions = this.executionOrder.slice(start, start + batchSize + 1).map((k) => ({ time: k.startedAt, id: k.executionId }));
+    } else {
+      positions = [...this.evalHistory.values()].map((stored) => ({ time: stored.entry.timestamp, id: stored.entry.id })).filter((p) => cursor === void 0 || compareRetentionPositions(cursor, p) < 0).sort(compareRetentionPositions).slice(0, batchSize + 1);
+    }
+    const batch = positions.slice(0, batchSize);
+    const ttl = kind === "executions" ? this.ttls.executionHistory : this.ttls.evalHistory;
+    if (ttl !== null) {
+      for (const { id } of batch) {
+        if (kind === "executions") {
+          const stored = this.executionHistory.get(id);
+          if (!stored || stored.expiresAt !== null) continue;
+          const decision = retentionForUntimedRecord(executionLastSavedAt(stored.record), ttl, now);
+          if (decision.expired) {
+            this.expireExecutionRecord(id);
+            expired++;
+          } else {
+            stored.expiresAt = decision.expiresAt;
+            armed++;
+          }
+        } else {
+          const stored = this.evalHistory.get(id);
+          if (!stored || stored.expiresAt !== null) continue;
+          const decision = retentionForUntimedRecord(stored.entry.timestamp, ttl, now);
+          if (decision.expired) {
+            this.evalHistory.delete(id);
+            expired++;
+          } else {
+            stored.expiresAt = decision.expiresAt;
+            armed++;
+          }
+        }
+      }
+    }
+    return {
+      expired,
+      armed,
+      indexed: 0,
+      deadIndexEntries: 0,
+      cursor: positions.length > batchSize ? batch[batch.length - 1] : null
+    };
+  }
+  // ── History retention internals ───────────────────────────────────
+  /** Index of the first order key not older than `key` (binary search). */
+  executionOrderLowerBound(key) {
+    let lo = 0;
+    let hi = this.executionOrder.length;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (compareOldestFirst(this.executionOrder[mid], key) < 0) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  }
+  insertExecutionOrder(record) {
+    const key = { startedAt: record.startedAt, executionId: record.executionId };
+    this.executionOrder.splice(this.executionOrderLowerBound(key), 0, key);
+  }
+  /** Remove a history record and its listing-index key. Returns whether one existed. */
+  removeExecutionRecord(executionId) {
+    const stored = this.executionHistory.get(executionId);
+    if (!stored) return false;
+    this.executionHistory.delete(executionId);
+    const index = this.executionOrderLowerBound(stored.record);
+    if (this.executionOrder[index]?.executionId === executionId) {
+      this.executionOrder.splice(index, 1);
+    }
+    return true;
+  }
+  /**
+   * A run leaving history through retention (expiry or `maxExecutions`) takes
+   * its leftover per-run data with it: checkpoints (kept today when a run
+   * fails), saved execution state and any streaming buffer. Pending decisions
+   * are not touched. The runtime never writes execution state, and a run is
+   * only saved to history once it has finished, so nothing still running
+   * depends on what is removed here.
+   */
+  expireExecutionRecord(executionId) {
+    this.removeExecutionRecord(executionId);
+    this.checkpoints.delete(executionId);
+    const state = this.executionStates.get(executionId);
+    this.executionStates.delete(executionId);
+    this.streamingEvents.delete(executionId);
+    if (state?.status === "waiting") this.persistAwaitHumanState();
+  }
+  /**
+   * Remove up to `PRUNE_BATCH` expired execution records, oldest save first.
+   * Stops at the first live record: Map order is last-save order, which is
+   * expiry order while the clock moves forward. If the clock steps back, a
+   * few expired records wait for a later save; reads still filter them.
+   */
+  pruneExpiredExecutions(now) {
+    if (this.ttls.executionHistory === null) return;
+    let removed = 0;
+    for (const [id, stored] of this.executionHistory) {
+      if (removed >= PRUNE_BATCH || !isExpired(stored.expiresAt, now)) break;
+      this.expireExecutionRecord(id);
+      removed++;
+    }
+  }
+  /** Evict the oldest records in listing order until the count bound holds. */
+  evictOverflowExecutions() {
+    while (this.executionHistory.size > this.maxExecutions) {
+      this.expireExecutionRecord(this.executionOrder[0].executionId);
+    }
+  }
+  /** Remove up to `PRUNE_BATCH` expired eval rows, oldest first write first. */
+  pruneExpiredEvals(now) {
+    if (this.ttls.evalHistory === null) return;
+    let removed = 0;
+    for (const [id, stored] of this.evalHistory) {
+      if (removed >= PRUNE_BATCH || !isExpired(stored.expiresAt, now)) break;
+      this.evalHistory.delete(id);
+      removed++;
+    }
   }
   // ── Sessions (Studio introspection) ─────────────────────────────────
   async listSessions() {
@@ -18916,6 +19260,7 @@ var MemoryStore = class {
 };
 
 // src/state/sqlite.ts
+var LIVE = "(expires_at IS NULL OR expires_at > ?)";
 function safeJsonParse(data) {
   try {
     return JSON.parse(data);
@@ -18952,7 +19297,17 @@ function rowToExecutionInfo(row) {
 }
 var SQLiteStore = class {
   db;
-  constructor(filePath) {
+  ttls;
+  now;
+  constructor(filePath, options) {
+    this.ttls = resolveHistoryTtls("SQLiteStore", options?.ttls);
+    if (options?.now !== void 0 && typeof options.now !== "function") {
+      throw new AxlError(
+        "INVALID_CONFIG",
+        "SQLiteStore: now must be a function returning epoch milliseconds"
+      );
+    }
+    this.now = options?.now ?? (() => Date.now());
     let BetterSqlite3;
     try {
       BetterSqlite3 = __require("better-sqlite3");
@@ -18965,6 +19320,7 @@ var SQLiteStore = class {
     this.db.pragma("journal_mode = WAL");
     this.migrate();
     this.initTables();
+    if (options?.ttls?.executionHistory === void 0) warnExecutionRetentionUnset("SQLiteStore");
   }
   /**
    * Idempotent schema migration. Tracks version via `PRAGMA user_version`
@@ -18992,6 +19348,11 @@ var SQLiteStore = class {
    *   Existing rows remain `NULL`, the documented v1 sentinel.
    * - v5 (observation completeness): add `execution_history.observation`.
    *   Existing rows remain `NULL`, meaning they predate the contract.
+   * - v6 (history retention): add nullable `expires_at` (epoch ms) to
+   *   `execution_history` and `eval_history`. Existing rows remain `NULL`
+   *   (never expire), so an upgrade deletes nothing. The single-column
+   *   `started_at` index is replaced by `(started_at, execution_id)`, which
+   *   serves the tie-safe listing order.
    *
    * Applied BEFORE `initTables()` so the subsequent `CREATE TABLE
    * IF NOT EXISTS` runs against the post-migration column name. Fresh
@@ -19009,7 +19370,7 @@ var SQLiteStore = class {
    * transactional re-read costs nothing.
    */
   migrate() {
-    const TARGET_VERSION = 5;
+    const TARGET_VERSION = 6;
     const current = this.db.pragma("user_version", { simple: true });
     if (current >= TARGET_VERSION) return;
     this.db.exec("BEGIN IMMEDIATE");
@@ -19049,6 +19410,15 @@ var SQLiteStore = class {
           this.db.exec("ALTER TABLE execution_history ADD COLUMN observation TEXT");
         }
       }
+      if (committed < 6) {
+        for (const table of ["execution_history", "eval_history"]) {
+          const cols = this.db.pragma(`table_info(${table})`);
+          if (cols.length > 0 && !cols.some((c) => c.name === "expires_at")) {
+            this.db.exec(`ALTER TABLE ${table} ADD COLUMN expires_at INTEGER`);
+          }
+        }
+        this.db.exec("DROP INDEX IF EXISTS idx_exec_history_started");
+      }
       this.db.pragma(`user_version = ${TARGET_VERSION}`);
       this.db.exec("COMMIT");
     } catch (err) {
@@ -19114,18 +19484,28 @@ var SQLiteStore = class {
         events TEXT NOT NULL,
         metadata TEXT,
         event_schema_version INTEGER,
-        observation TEXT
+        observation TEXT,
+        expires_at INTEGER
       );
 
       CREATE TABLE IF NOT EXISTS eval_history (
         id TEXT PRIMARY KEY,
         eval_name TEXT NOT NULL,
         timestamp INTEGER NOT NULL,
-        data TEXT NOT NULL
+        data TEXT NOT NULL,
+        expires_at INTEGER
       );
 
-      CREATE INDEX IF NOT EXISTS idx_exec_history_started ON execution_history (started_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_exec_history_started_id
+        ON execution_history (started_at DESC, execution_id DESC);
+      CREATE INDEX IF NOT EXISTS idx_exec_history_expires ON execution_history (expires_at);
       CREATE INDEX IF NOT EXISTS idx_eval_history_timestamp ON eval_history (timestamp DESC);
+      CREATE INDEX IF NOT EXISTS idx_eval_history_expires ON eval_history (expires_at);
+
+      -- Superseded by idx_exec_history_started_id in v6. Dropped here as well as in
+      -- migrate(): a pre-v6 process reopening a v6 file re-creates it, and
+      -- migrate() never runs again once user_version is 6.
+      DROP INDEX IF EXISTS idx_exec_history_started;
     `);
   }
   // ── Checkpoints ────────────────────────────────────────────────────────
@@ -19238,30 +19618,71 @@ var SQLiteStore = class {
       ...execution,
       eventSchemaVersion: getExecutionEventSchemaVersion(execution)
     });
+    const now = this.now();
+    this.db.transaction(() => {
+      this.db.prepare(
+        "INSERT OR REPLACE INTO execution_history (execution_id, workflow, status, total_cost, started_at, completed_at, duration, error, events, metadata, event_schema_version, observation, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"
+      ).run(
+        normalized.executionId,
+        normalized.workflow,
+        normalized.status,
+        normalized.totalCost,
+        normalized.startedAt,
+        normalized.completedAt ?? null,
+        normalized.duration,
+        normalized.error ?? null,
+        JSON.stringify(normalized.events),
+        normalized.metadata !== void 0 ? JSON.stringify(normalized.metadata) : null,
+        normalized.eventSchemaVersion,
+        normalized.observation !== void 0 ? JSON.stringify(normalized.observation) : null,
+        expiryFrom(now, this.ttls.executionHistory)
+      );
+      this.pruneExpiredExecutions(now);
+    })();
+  }
+  /**
+   * Remove up to `PRUNE_BATCH` expired execution-history rows, together with
+   * each run's leftover checkpoints and saved execution state, inside the
+   * caller's transaction. Pending decisions are not touched. The runtime
+   * never writes execution state, and a run is only saved to history once it
+   * has finished, so nothing still running depends on what is removed here.
+   */
+  pruneExpiredExecutions(now) {
+    const ids = this.db.prepare(
+      "SELECT execution_id FROM execution_history WHERE expires_at <= ? ORDER BY expires_at LIMIT ?"
+    ).all(now, PRUNE_BATCH).map((row) => row.execution_id);
+    if (ids.length === 0) return;
+    const idList = JSON.stringify(ids);
+    for (const table of ["execution_history", "checkpoints", "execution_state"]) {
+      this.db.prepare(`DELETE FROM ${table} WHERE execution_id IN (SELECT value FROM json_each(?))`).run(idList);
+    }
+  }
+  /** Remove up to `PRUNE_BATCH` expired eval-history rows (caller's transaction). */
+  pruneExpiredEvals(now) {
     this.db.prepare(
-      "INSERT OR REPLACE INTO execution_history (execution_id, workflow, status, total_cost, started_at, completed_at, duration, error, events, metadata, event_schema_version, observation) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"
-    ).run(
-      normalized.executionId,
-      normalized.workflow,
-      normalized.status,
-      normalized.totalCost,
-      normalized.startedAt,
-      normalized.completedAt ?? null,
-      normalized.duration,
-      normalized.error ?? null,
-      JSON.stringify(normalized.events),
-      normalized.metadata !== void 0 ? JSON.stringify(normalized.metadata) : null,
-      normalized.eventSchemaVersion,
-      normalized.observation !== void 0 ? JSON.stringify(normalized.observation) : null
-    );
+      "DELETE FROM eval_history WHERE rowid IN (SELECT rowid FROM eval_history WHERE expires_at <= ? ORDER BY expires_at LIMIT ?)"
+    ).run(now, PRUNE_BATCH);
   }
   async getExecution(executionId) {
-    const row = this.db.prepare("SELECT * FROM execution_history WHERE execution_id = ?").get(executionId);
+    const row = this.db.prepare(`SELECT * FROM execution_history WHERE execution_id = ? AND ${LIVE}`).get(executionId, this.now());
     return row ? rowToExecutionInfo(row) : null;
   }
-  async listExecutions(limit) {
-    const sql = limit ? "SELECT * FROM execution_history ORDER BY started_at DESC LIMIT ?" : "SELECT * FROM execution_history ORDER BY started_at DESC";
-    const rows = limit ? this.db.prepare(sql).all(limit) : this.db.prepare(sql).all();
+  /** Supports `listExecutions(limit, { cursor })`. */
+  historyPaging = true;
+  async listExecutions(limit, options) {
+    const cursor = options?.cursor;
+    const params = [this.now()];
+    let sql = `SELECT * FROM execution_history WHERE ${LIVE}`;
+    if (cursor !== void 0) {
+      sql += " AND (started_at < ? OR (started_at = ? AND execution_id < ?))";
+      params.push(cursor.startedAt, cursor.startedAt, cursor.executionId);
+    }
+    sql += " ORDER BY started_at DESC, execution_id DESC";
+    if (limit) {
+      sql += " LIMIT ?";
+      params.push(limit);
+    }
+    const rows = this.db.prepare(sql).all(...params);
     return rows.map(rowToExecutionInfo);
   }
   async deleteExecution(executionId) {
@@ -19275,24 +19696,38 @@ var SQLiteStore = class {
     return tx();
   }
   // ── Eval History ────────────────────────────────────────────────────────
+  /**
+   * Write an eval history row. Retention counts from the row's first write:
+   * re-saving a live row keeps its `expires_at` (including none, for a row
+   * written without retention). A row that has already expired is replaced
+   * as a new one.
+   */
   async saveEvalResult(entry) {
-    this.db.prepare(
-      "INSERT OR REPLACE INTO eval_history (id, eval_name, timestamp, data) VALUES (?, ?, ?, ?)"
-    ).run(entry.id, entry.eval, entry.timestamp, JSON.stringify(entry.data));
+    const now = this.now();
+    this.db.transaction(() => {
+      const existing = this.db.prepare(`SELECT expires_at FROM eval_history WHERE id = ? AND ${LIVE}`).get(entry.id, now);
+      const expiresAt = existing ? existing.expires_at : expiryFrom(now, this.ttls.evalHistory);
+      this.db.prepare(
+        "INSERT OR REPLACE INTO eval_history (id, eval_name, timestamp, data, expires_at) VALUES (?, ?, ?, ?, ?)"
+      ).run(entry.id, entry.eval, entry.timestamp, JSON.stringify(entry.data), expiresAt);
+      this.pruneExpiredEvals(now);
+    })();
   }
   /**
    * Update-only write: see `StateStore.updateEvalResult`. `UPDATE ... WHERE id`
-   * touches nothing when the row is gone, where `INSERT OR REPLACE` would
-   * resurrect it — and SQLite history has no expiry, so a resurrection here is
-   * permanent.
+   * touches nothing when the row is gone or expired, where `INSERT OR REPLACE`
+   * would resurrect it. `expires_at` is left as it was.
    */
   async updateEvalResult(entry) {
-    const result = this.db.prepare("UPDATE eval_history SET eval_name = ?, timestamp = ?, data = ? WHERE id = ?").run(entry.eval, entry.timestamp, JSON.stringify(entry.data), entry.id);
+    const result = this.db.prepare(
+      `UPDATE eval_history SET eval_name = ?, timestamp = ?, data = ? WHERE id = ? AND ${LIVE}`
+    ).run(entry.eval, entry.timestamp, JSON.stringify(entry.data), entry.id, this.now());
     return result.changes > 0;
   }
   async listEvalResults(limit) {
-    const sql = limit ? "SELECT * FROM eval_history ORDER BY timestamp DESC LIMIT ?" : "SELECT * FROM eval_history ORDER BY timestamp DESC";
-    const rows = limit ? this.db.prepare(sql).all(limit) : this.db.prepare(sql).all();
+    const base = `SELECT * FROM eval_history WHERE ${LIVE} ORDER BY timestamp DESC`;
+    const now = this.now();
+    const rows = limit ? this.db.prepare(`${base} LIMIT ?`).all(now, limit) : this.db.prepare(base).all(now);
     return rows.map((r) => ({
       id: r.id,
       eval: r.eval_name,
@@ -19304,10 +19739,75 @@ var SQLiteStore = class {
     const result = this.db.prepare("DELETE FROM eval_history WHERE id = ?").run(id);
     return result.changes > 0;
   }
-  /** SQLite history has no automatic expiry — only existence is meaningful. */
+  /** Existence plus the expiry stored at the row's first write, if any. */
   async getEvalRetention(id) {
-    const row = this.db.prepare("SELECT 1 FROM eval_history WHERE id = ?").get(id);
-    return { exists: row !== void 0 };
+    const row = this.db.prepare(`SELECT expires_at FROM eval_history WHERE id = ? AND ${LIVE}`).get(id, this.now());
+    if (!row) return { exists: false };
+    return row.expires_at === null ? { exists: true } : { exists: true, expiresAt: row.expires_at };
+  }
+  // ── History maintenance ─────────────────────────────────────────────────
+  /**
+   * See `StateStore.applyHistoryRetention`. One batch runs in one immediate
+   * transaction, so no other writer can change a row between this call
+   * reading it and acting on it. Only rows whose `expires_at` is `NULL` are
+   * touched. An expired execution takes its checkpoints and saved execution
+   * state with it, as a normal expiry does. There is no separate index, so
+   * `indexed` and `deadIndexEntries` are always `0`.
+   */
+  async applyHistoryRetention(options) {
+    const { kind, batchSize, cursor } = resolveHistoryRetentionOptions("SQLiteStore", options);
+    const ttl = kind === "executions" ? this.ttls.executionHistory : this.ttls.evalHistory;
+    const table = kind === "executions" ? { name: "execution_history", id: "execution_id", time: "started_at" } : { name: "eval_history", id: "id", time: "timestamp" };
+    const lastSaved = kind === "executions" ? "completed_at" : "NULL";
+    const now = this.now();
+    return this.db.transaction(() => {
+      const params = [];
+      let sql = `SELECT ${table.id} AS id, ${table.time} AS time, ${lastSaved} AS last_saved, expires_at FROM ${table.name}`;
+      if (cursor !== void 0) {
+        sql += ` WHERE ${table.time} > ? OR (${table.time} = ? AND ${table.id} > ?)`;
+        params.push(cursor.time, cursor.time, cursor.id);
+      }
+      sql += ` ORDER BY ${table.time}, ${table.id} LIMIT ?`;
+      params.push(batchSize + 1);
+      const rows = this.db.prepare(sql).all(...params);
+      const batch = rows.slice(0, batchSize);
+      const toExpire = [];
+      let armed = 0;
+      if (ttl !== null) {
+        const arm = this.db.prepare(
+          `UPDATE ${table.name} SET expires_at = ? WHERE ${table.id} = ? AND expires_at IS NULL`
+        );
+        for (const row of batch) {
+          if (row.expires_at !== null) continue;
+          const lastSavedAt = kind === "executions" ? executionLastSavedAt({ startedAt: row.time, completedAt: row.last_saved }) : row.time;
+          const decision = retentionForUntimedRecord(lastSavedAt, ttl, now);
+          if (decision.expired) toExpire.push(row.id);
+          else armed += arm.run(decision.expiresAt, row.id).changes;
+        }
+      }
+      let expired = 0;
+      if (toExpire.length > 0) {
+        const idList = JSON.stringify(toExpire);
+        expired = this.db.prepare(
+          `DELETE FROM ${table.name} WHERE expires_at IS NULL AND ${table.id} IN (SELECT value FROM json_each(?))`
+        ).run(idList).changes;
+        if (kind === "executions") {
+          for (const side of ["checkpoints", "execution_state"]) {
+            this.db.prepare(
+              `DELETE FROM ${side} WHERE execution_id IN (SELECT value FROM json_each(?))`
+            ).run(idList);
+          }
+        }
+      }
+      const last = batch[batch.length - 1];
+      return {
+        expired,
+        armed,
+        indexed: 0,
+        deadIndexEntries: 0,
+        cursor: rows.length > batchSize ? { time: last.time, id: last.id } : null
+      };
+    }).immediate();
   }
   // ── Sessions (Studio introspection) ────────────────────────────────────
   async listSessions() {
@@ -20656,6 +21156,9 @@ function hashInput(input) {
 }
 var DEFAULT_MAX_EVENTS_PER_EXECUTION = 5e4;
 var DEFAULT_STREAMING_BATCH_SIZE = 100;
+var DEFAULT_RECENT_EXECUTIONS_CACHE_SIZE = 1e3;
+var LARGE_EXECUTION_LISTING = 1e3;
+var EXECUTION_SCAN_PAGE_SIZE = 100;
 var DEFAULT_STREAMING_BATCH_INTERVAL = 1e3;
 var DEFAULT_ARTIFACT_SWEEP_MS = 6e4;
 var DEFAULT_ARTIFACT_LEASE_MS = 3e5;
@@ -20868,6 +21371,78 @@ function assertNoRemovedObservationCallbacks(options) {
     `runtime.createContext() no longer accepts ${removed.join(", ")}. Observe ctx.events or use runtime.stream() instead. See docs/migration/stream-first-observation.md.`
   );
 }
+var RecentRunsCache = class {
+  constructor(capacity) {
+    this.capacity = capacity;
+  }
+  entries = /* @__PURE__ */ new Map();
+  get size() {
+    return this.entries.size;
+  }
+  get(executionId) {
+    const entry = this.entries.get(executionId);
+    if (entry) {
+      this.entries.delete(executionId);
+      this.entries.set(executionId, entry);
+    }
+    return entry;
+  }
+  set(executionId, execution) {
+    this.entries.delete(executionId);
+    this.entries.set(executionId, execution);
+    while (this.entries.size > this.capacity) {
+      const oldest = this.entries.keys().next().value;
+      this.entries.delete(oldest);
+    }
+  }
+  delete(executionId) {
+    return this.entries.delete(executionId);
+  }
+  values() {
+    return [...this.entries.values()];
+  }
+};
+function resolveRecentExecutionsCacheSize(requested) {
+  if (requested === void 0) return DEFAULT_RECENT_EXECUTIONS_CACHE_SIZE;
+  if (typeof requested !== "number" || !Number.isInteger(requested) || requested < 0) {
+    throw new AxlError(
+      "INVALID_CONFIG",
+      `config.state.recentExecutionsCacheSize must be a non-negative integer; got ${String(requested)}`
+    );
+  }
+  return requested;
+}
+function parseGetExecutionsOptions(options) {
+  if (options === void 0) return {};
+  if (options === null || typeof options !== "object") {
+    throw new AxlError(
+      "INVALID_ARGUMENT",
+      `getExecutions() options must be an object; got ${options === null ? "null" : typeof options}`
+    );
+  }
+  const { limit, cursor } = options;
+  if (limit !== void 0 && limit !== Infinity && !(typeof limit === "number" && Number.isInteger(limit) && limit > 0)) {
+    throw new AxlError(
+      "INVALID_ARGUMENT",
+      `getExecutions() limit must be a positive integer; got ${String(limit)}`
+    );
+  }
+  let parsedCursor;
+  if (cursor !== void 0) {
+    const candidate = cursor;
+    if (candidate === null || typeof candidate !== "object" || typeof candidate.startedAt !== "number" || !Number.isFinite(candidate.startedAt) || typeof candidate.executionId !== "string") {
+      throw new AxlError(
+        "INVALID_ARGUMENT",
+        "getExecutions() cursor must be { startedAt: number; executionId: string }, built from the last item of the previous page"
+      );
+    }
+    parsedCursor = { startedAt: candidate.startedAt, executionId: candidate.executionId };
+  }
+  return {
+    ...limit === void 0 || limit === Infinity ? {} : { limit },
+    ...parsedCursor ? { cursor: parsedCursor } : {}
+  };
+}
 var costScopeStorage = new AsyncLocalStorage4();
 function forwardAbortSignal(external, internal) {
   if (!external) return () => {
@@ -20914,8 +21489,6 @@ var AxlRuntime = class extends EventEmitter2 {
   mcpManager;
   memoryManager;
   spanManager = new NoopSpanManager();
-  historicalExecutions = /* @__PURE__ */ new Map();
-  historicalExecutionsLoadPromise = null;
   /** Per-session in-process serialization. Each entry is a chain of pending
    *  work for that session id — `Session.send` / `Session.stream` await the
    *  prior entry before reading history, so concurrent calls produce a
@@ -20951,12 +21524,34 @@ var AxlRuntime = class extends EventEmitter2 {
    *  a delete from resurrecting the (intentionally-removed) row. Entries are
    *  removed once the would-be persist has been short-circuited. */
   pendingDeletedExecutions = /* @__PURE__ */ new Set();
-  /** In-flight `persistExecution` chains (save → finalize). `shutdown()`
-   *  awaits these before closing the StateStore so a workflow whose abort
+  /** In-flight `persistExecution` chains (save → finalize) and crash-
+   *  recovery saves. `shutdown()` awaits these before closing the StateStore so a workflow whose abort
    *  triggers a persist-during-shutdown isn't racing a closed connection.
    *  The Set is mutated by the chain's own `.finally` so entries clear as
    *  soon as the work settles. */
   persistInflight = /* @__PURE__ */ new Set();
+  /** Finished runs whose history save has not settled, keyed by execution
+   *  id. Reads serve the snapshot until the save lands, so a run is visible
+   *  the moment it finishes (read-your-writes). `deleteExecution()` awaits
+   *  the entry before deleting from the store, so a save that lands late
+   *  cannot re-create a deleted run. Each entry removes itself when its save
+   *  settles (success or failure), but only if it is still the current entry
+   *  for that id, so the map holds only in-flight saves. */
+  pendingSaves = /* @__PURE__ */ new Map();
+  /** Recently finished runs, kept only when the store cannot save, list, or
+   *  fetch execution history itself (and the cache size is not `0`).
+   *  `undefined` for every built-in store: execution history is read through
+   *  the store on every call and never cached here. */
+  recentRuns;
+  /** Execution ids `recoverIncompleteStreams()` is working on, each with a
+   *  promise that settles when recovery is done with that id.
+   *  `deleteExecution()` awaits it, so a recovered record cannot land after
+   *  the delete. */
+  recoveringExecutions = /* @__PURE__ */ new Map();
+  /** Execution ids with a `deleteExecution()` in progress, with a count of
+   *  concurrent deletes. Recovery skips them: their store sweep removes the
+   *  streaming buffer it would otherwise turn back into a record. */
+  deletingExecutions = /* @__PURE__ */ new Map();
   /** Resolved diagnostic artifact backend, when `diagnostics.artifacts` is set. */
   artifactStore;
   artifactLeaseMs = DEFAULT_ARTIFACT_LEASE_MS;
@@ -20990,6 +21585,13 @@ var AxlRuntime = class extends EventEmitter2 {
     this.providerRegistry = new ProviderRegistry();
     this.transcriptionProviderRegistry = new TranscriptionProviderRegistry();
     this.stateStore = this.createStateStore();
+    const recentRunsSize = resolveRecentExecutionsCacheSize(
+      this.config.state?.recentExecutionsCacheSize
+    );
+    const storeKeepsHistory = Boolean(
+      this.stateStore.saveExecution && this.stateStore.listExecutions
+    );
+    this.recentRuns = !storeKeepsHistory && recentRunsSize > 0 ? new RecentRunsCache(recentRunsSize) : void 0;
     const requested = this.config.state?.maxEventsPerExecution;
     if (requested === void 0) {
       this.maxEventsPerExecution = DEFAULT_MAX_EVENTS_PER_EXECUTION;
@@ -21395,11 +21997,15 @@ var AxlRuntime = class extends EventEmitter2 {
     const storeOption = this.config.state?.store ?? "memory";
     if (typeof storeOption !== "string") return storeOption;
     switch (storeOption) {
-      case "sqlite":
-        return new SQLiteStore(this.config.state?.sqlite?.path ?? "./data/axl.db");
+      case "sqlite": {
+        const create = () => new SQLiteStore(this.config.state?.sqlite?.path ?? "./data/axl.db", {
+          ttls: this.config.state?.sqlite?.ttls
+        });
+        return this.config.diagnostics?.silent ? withDiagnosticsSilenced(create) : create();
+      }
       case "memory":
       default:
-        return new MemoryStore();
+        return new MemoryStore(this.config.state?.memory);
     }
   }
   /**
@@ -21487,13 +22093,15 @@ var AxlRuntime = class extends EventEmitter2 {
   }
   /**
    * Persist a completed/failed execution to the state store (fire-and-forget)
-   * and move it from the active executions map to the historical cache.
+   * and remove it from the active executions map. Until the save settles the
+   * run is served from `pendingSaves`; afterwards from the store (or, for a
+   * store that cannot keep history, from `recentRuns`).
    *
    * Resurrection guard: if `runtime.deleteExecution(id)` was called while
    * this execution was still running, the id will be in
-   * `pendingDeletedExecutions`. In that case we skip the save AND the
-   * historical-cache write, and finalize the streaming buffer (if any) so
-   * the buffer doesn't outlive the delete.
+   * `pendingDeletedExecutions`. In that case we skip the save AND every
+   * in-process record of the run, and finalize the streaming buffer (if any)
+   * so the buffer doesn't outlive the delete.
    */
   persistExecution(execInfo) {
     const id = execInfo.executionId;
@@ -21524,14 +22132,19 @@ var AxlRuntime = class extends EventEmitter2 {
       }).catch(() => {
       }).then(() => void 0);
       this.persistInflight.add(chain);
-      chain.finally(() => this.persistInflight.delete(chain));
+      const pending = { snapshot, settled: chain };
+      this.pendingSaves.set(id, pending);
+      chain.finally(() => {
+        this.persistInflight.delete(chain);
+        if (this.pendingSaves.get(id) === pending) this.pendingSaves.delete(id);
+      });
     } else if (this.streamingFlusher) {
       const chain = this.streamingFlusher.finalize(id).catch(() => {
       });
       this.persistInflight.add(chain);
       chain.finally(() => this.persistInflight.delete(chain));
     }
-    this.historicalExecutions.set(id, snapshot);
+    this.recentRuns?.set(id, snapshot);
     this.executions.delete(id);
   }
   /** Register a workflow with the runtime. */
@@ -21657,7 +22270,6 @@ var AxlRuntime = class extends EventEmitter2 {
     }
     return result;
   }
-  /** Get all execution info (running + completed + historical). */
   /** Normalize an execution loaded from a `StateStore` so the
    *  historical event union holds for downstream consumers
    *  (Studio aggregators, REST routes, redaction). Custom or legacy stores
@@ -21677,27 +22289,78 @@ var AxlRuntime = class extends EventEmitter2 {
     }
     return normalizeStoredExecution(exec);
   }
-  async getExecutions() {
-    if (!this.historicalExecutionsLoadPromise && this.stateStore.listExecutions) {
-      this.historicalExecutionsLoadPromise = this.stateStore.listExecutions().then((stored) => {
-        for (const exec of stored) {
-          if (!this.executions.has(exec.executionId) && !this.historicalExecutions.has(exec.executionId)) {
-            this.historicalExecutions.set(exec.executionId, this.normalizeStoredExecution(exec));
-          }
-        }
-      }).catch((error) => {
-        this.historicalExecutionsLoadPromise = null;
-        throw error;
-      });
-    }
-    if (this.historicalExecutionsLoadPromise) {
-      await this.historicalExecutionsLoadPromise;
-    }
-    const merged = new Map(this.historicalExecutions);
-    for (const [id, exec] of this.executions) {
-      merged.set(id, exec);
+  /**
+   * List executions, newest first: running runs, runs whose save is still in
+   * flight, and the history the state store holds. Ordered by `startedAt`,
+   * then `executionId`, both descending.
+   *
+   * With no options, returns every retained run. Pass `limit` for one page,
+   * and `cursor` (built from the last item of the previous page) for the
+   * page after it. Each call reads through the store, so runs finished or
+   * deleted by other runtimes sharing the store are reflected immediately.
+   * A call without `limit` that returns more than 1 000 runs warns once per
+   * process (silenced by `diagnostics.silent`); pass `limit: Infinity` to ask
+   * for everything without the warning.
+   *
+   * @throws {AxlError} `INVALID_ARGUMENT` for a `limit` that is not a positive
+   *   integer (`Infinity` means no limit) or a malformed `cursor`.
+   */
+  async getExecutions(options) {
+    const { limit, cursor } = parseGetExecutionsOptions(options);
+    const isAfterCursor = (exec) => cursor === void 0 || compareExecutionsNewestFirst(exec, cursor) > 0;
+    const live = new Map(this.executions);
+    for (const [id, { snapshot }] of this.pendingSaves) {
+      if (!live.has(id)) live.set(id, snapshot);
+    }
+    const recent = this.recentRunsServeListing() ? this.recentRuns.values() : [];
+    const stored = await this.listStoredExecutions({
+      limit,
+      cursor,
+      overlap: live.size + recent.length
+    });
+    const merged = /* @__PURE__ */ new Map();
+    for (const [id, exec] of live) {
+      if (isAfterCursor(exec)) merged.set(id, exec);
+    }
+    for (const exec of stored) {
+      const id = exec.executionId;
+      if (!live.has(id) && !merged.has(id)) merged.set(id, exec);
+    }
+    for (const exec of recent) {
+      const id = exec.executionId;
+      if (!live.has(id) && !merged.has(id) && isAfterCursor(exec)) merged.set(id, exec);
+    }
+    const sorted = [...merged.values()].sort(compareExecutionsNewestFirst);
+    if (limit !== void 0) return sorted.slice(0, limit);
+    if (options?.limit === void 0 && sorted.length > LARGE_EXECUTION_LISTING) {
+      warnDiagnosticOnce(
+        "large_execution_listing",
+        `runtime.getExecutions() without a limit returned ${sorted.length} runs and reads the whole history on every call; pass { limit, cursor } to read it a page at a time.`,
+        this.config.diagnostics?.silent,
+        "docs/migration/execution-history-retention.md#page-through-large-histories"
+      );
     }
-    return [...merged.values()].sort((a, b) => b.startedAt - a.startedAt);
+    return sorted;
+  }
+  /**
+   * Read one page of execution history from the store: the records strictly
+   * after `cursor`, newest first, at least `limit + overlap` of them when the
+   * store holds that many (all of them when `limit` is unset).
+   *
+   * Only a store that declares `historyPaging` is handed the cursor. Any
+   * other store is listed in full and paged here: filtering the output of a
+   * store that ignored the cursor would return its first page again, and an
+   * empty page after that.
+   */
+  async listStoredExecutions(page) {
+    const store = this.stateStore;
+    if (!store.listExecutions) return [];
+    const wanted = page.limit === void 0 ? void 0 : page.limit + page.overlap;
+    const rows = store.historyPaging === true ? await store.listExecutions(wanted, { cursor: page.cursor }) : await store.listExecutions();
+    const cursor = page.cursor;
+    const after = cursor === void 0 ? rows : rows.filter((row) => compareExecutionsNewestFirst(row, cursor) > 0);
+    const window = wanted === void 0 ? after : [...after].sort(compareExecutionsNewestFirst).slice(0, wanted);
+    return window.map((row) => this.normalizeStoredExecution(row));
   }
   /**
    * Create a WorkflowContext for ad-hoc use (evals, tool testing, prototyping).
@@ -22128,20 +22791,25 @@ var AxlRuntime = class extends EventEmitter2 {
    * Recover executions whose process died mid-run when `state.persist:
    * 'streaming'` was configured. Synthesizes a partial `ExecutionInfo`
    * from the streaming buffer for each — `status: 'failed'`, error
-   * `'process terminated'` — registers them in the historical cache so
-   * they show up in `getExecutions()`, persists them via the store's
-   * `saveExecution`, and finalizes the streaming buffer.
+   * `'process terminated'` — persists them via the store's
+   * `saveExecution` (so they show up in `getExecutions()`), and finalizes
+   * the streaming buffer.
    *
    * Idempotent — if the streaming buffer is already gone (or
    * `listStreamingExecutions` is empty), this is a no-op. Returns the
    * list of recovered `ExecutionInfo`s for caller introspection.
    *
-   * Wire this into your process startup AFTER `runtime.getExecutions()`
-   * has lazy-loaded the historical cache. Order matters: completed
-   * executions already in the store should not be overwritten by a
-   * stale streaming buffer that the previous process didn't get to
-   * finalize. The implementation checks the historical store before
-   * synthesizing, so a re-run is safe.
+   * A run whose final record already exists is never recovered: for each
+   * buffered id this asks the store's `getExecution(id)` and, when a record
+   * is there, only drops the leftover buffer. It does not list history, so
+   * its cost does not grow with the size of the store. A store without
+   * `getExecution` cannot be checked, and every buffered run is recovered.
+   *
+   * Wire this into process startup, before the process accepts new work:
+   * a run live in another process looks the same as a crashed one.
+   * `deleteExecution(id)` called while recovery is working on that id waits
+   * for recovery to finish with it, so the recovered record cannot outlive
+   * the delete.
    */
   async recoverIncompleteStreams() {
     if (!this.stateStore.listStreamingExecutions || !this.stateStore.getStreamingEvents) {
@@ -22149,73 +22817,119 @@ var AxlRuntime = class extends EventEmitter2 {
     }
     const ids = await this.stateStore.listStreamingExecutions();
     if (ids.length === 0) return [];
-    await this.getExecutions();
     const recovered = [];
     for (const id of ids) {
       if (this.executions.has(id) || this.streamableExecutionIds.has(id)) {
         continue;
       }
-      const existing = this.historicalExecutions.get(id);
-      if (existing) {
-        await this.stateStore.finalizeStreamingEvents?.(id);
-        continue;
-      }
-      const events = await this.stateStore.getStreamingEvents(id);
-      if (events.length === 0) {
-        await this.stateStore.finalizeStreamingEvents?.(id);
-        continue;
-      }
-      const eventSchemaVersion = getEventSchemaVersion(events[0]);
-      for (const event of events) {
-        if (getEventSchemaVersion(event) !== eventSchemaVersion) {
-          throw new Error(`Streaming buffer ${id} contains mixed event schema versions`);
-        }
+      if (this.deletingExecutions.has(id) || this.recoveringExecutions.has(id)) continue;
+      let finishRecovery;
+      this.recoveringExecutions.set(
+        id,
+        new Promise((resolve2) => {
+          finishRecovery = resolve2;
+        })
+      );
+      try {
+        const result = await this.recoverStreamingExecution(id);
+        if (result) recovered.push(result);
+      } finally {
+        this.recoveringExecutions.delete(id);
+        finishRecovery();
       }
-      const boundedEvents = boundRecoveredEvents(events, this.maxEventsPerExecution);
-      const workflowStartEvent = boundedEvents.find((e) => e.type === "workflow_start");
-      const lastEvent = boundedEvents[boundedEvents.length - 1];
-      const startedAt = workflowStartEvent?.timestamp ?? boundedEvents[0]?.timestamp ?? Date.now();
-      const completedAt = lastEvent.timestamp ?? startedAt;
-      const workflowName = workflowStartEvent?.workflow ?? RECOVERED_UNKNOWN_WORKFLOW;
-      const totalCost = boundedEvents.reduce((sum, e) => sum + eventCostContribution(e), 0);
-      const unpriced = boundedEvents.some(isUnpricedLeaf);
-      const executionBase = {
-        executionId: id,
-        workflow: workflowName,
-        status: "failed",
-        events: boundedEvents,
-        totalCost,
-        unpriced,
-        startedAt,
-        completedAt,
-        duration: completedAt - startedAt,
-        error: "process terminated (recovered from streaming buffer)"
-      };
-      const synthesized = eventSchemaVersion === 2 ? {
-        ...executionBase,
-        eventSchemaVersion: 2,
-        events: boundedEvents,
-        observation: { complete: false, reason: "process_interrupted" }
-      } : {
-        ...executionBase,
-        eventSchemaVersion: 1,
-        events: boundedEvents
+    }
+    return recovered;
+  }
+  /** Recover one buffered execution. Returns the synthesized record, or
+   *  `undefined` when there was nothing to recover. */
+  async recoverStreamingExecution(id) {
+    if (!this.stateStore.getStreamingEvents) return void 0;
+    const existing = await this.stateStore.getExecution?.(id);
+    if (existing) {
+      await this.stateStore.finalizeStreamingEvents?.(id);
+      return void 0;
+    }
+    const events = await this.stateStore.getStreamingEvents(id);
+    if (events.length === 0) {
+      await this.stateStore.finalizeStreamingEvents?.(id);
+      return void 0;
+    }
+    const eventSchemaVersion = getEventSchemaVersion(events[0]);
+    for (const event of events) {
+      if (getEventSchemaVersion(event) !== eventSchemaVersion) {
+        throw new Error(`Streaming buffer ${id} contains mixed event schema versions`);
+      }
+    }
+    const boundedEvents = boundRecoveredEvents(events, this.maxEventsPerExecution);
+    const workflowStartEvent = boundedEvents.find((e) => e.type === "workflow_start");
+    const lastEvent = boundedEvents[boundedEvents.length - 1];
+    const startedAt = workflowStartEvent?.timestamp ?? boundedEvents[0]?.timestamp ?? Date.now();
+    const completedAt = lastEvent.timestamp ?? startedAt;
+    const workflowName = workflowStartEvent?.workflow ?? RECOVERED_UNKNOWN_WORKFLOW;
+    const totalCost = boundedEvents.reduce((sum, e) => sum + eventCostContribution(e), 0);
+    const unpriced = boundedEvents.some(isUnpricedLeaf);
+    const executionBase = {
+      executionId: id,
+      workflow: workflowName,
+      status: "failed",
+      events: boundedEvents,
+      totalCost,
+      unpriced,
+      startedAt,
+      completedAt,
+      duration: completedAt - startedAt,
+      error: "process terminated (recovered from streaming buffer)"
+    };
+    const synthesized = eventSchemaVersion === 2 ? {
+      ...executionBase,
+      eventSchemaVersion: 2,
+      events: boundedEvents,
+      observation: { complete: false, reason: "process_interrupted" }
+    } : {
+      ...executionBase,
+      eventSchemaVersion: 1,
+      events: boundedEvents
+    };
+    const saveExecution = this.stateStore.saveExecution;
+    if (saveExecution) {
+      const save = (async () => saveExecution.call(this.stateStore, synthesized))();
+      const pending = {
+        snapshot: synthesized,
+        settled: save.then(
+          () => void 0,
+          () => void 0
+        )
       };
-      if (this.stateStore.saveExecution) {
-        try {
-          await this.stateStore.saveExecution(synthesized);
-        } catch (err) {
-          console.error(
-            `[axl] recoverIncompleteStreams: failed to save synthesized execution ${id}: ${err instanceof Error ? err.message : String(err)}. Streaming buffer left in place for next recovery attempt.`
-          );
-          continue;
-        }
+      this.pendingSaves.set(id, pending);
+      this.persistInflight.add(pending.settled);
+      try {
+        await save;
+      } catch (err) {
+        console.error(
+          `[axl] recoverIncompleteStreams: failed to save synthesized execution ${id}: ${err instanceof Error ? err.message : String(err)}. Streaming buffer left in place for next recovery attempt.`
+        );
+        return void 0;
+      } finally {
+        this.persistInflight.delete(pending.settled);
+        if (this.pendingSaves.get(id) === pending) this.pendingSaves.delete(id);
       }
-      this.historicalExecutions.set(id, synthesized);
-      await this.stateStore.finalizeStreamingEvents?.(id);
-      recovered.push(synthesized);
     }
-    return recovered;
+    this.recentRuns?.set(id, synthesized);
+    const finalize = Promise.resolve(this.stateStore.finalizeStreamingEvents?.(id)).then(
+      () => void 0,
+      (err) => {
+        console.error(
+          `[axl] recoverIncompleteStreams: saved execution ${id} but failed to drop its streaming buffer: ${err instanceof Error ? err.message : String(err)}. The next recovery removes it.`
+        );
+      }
+    );
+    this.persistInflight.add(finalize);
+    try {
+      await finalize;
+    } finally {
+      this.persistInflight.delete(finalize);
+    }
+    return synthesized;
   }
   /** Abort a running execution by its ID. */
   abort(executionId) {
@@ -22225,21 +22939,57 @@ var AxlRuntime = class extends EventEmitter2 {
       this.abortControllers.delete(executionId);
     }
   }
-  /** Get execution details by ID. */
+  /**
+   * Get execution details by ID. Looks in order at running runs, runs whose
+   * save is still in flight, the state store (its `getExecution`, or a scan
+   * of its listing when it has `listExecutions` but no `getExecution`), and
+   * (only for a store that cannot list or save history) the recent-runs
+   * cache. Nothing read from the store is cached, so a run deleted or
+   * expired elsewhere is gone on the next call, and every run
+   * `getExecutions()` lists can be fetched here.
+   */
   async getExecution(executionId) {
-    const inMemory = this.executions.get(executionId);
-    if (inMemory) return inMemory;
-    const cached = this.historicalExecutions.get(executionId);
-    if (cached) return cached;
-    if (this.stateStore.getExecution) {
-      const stored = await this.stateStore.getExecution(executionId);
-      if (stored) {
-        const normalized = this.normalizeStoredExecution(stored);
-        this.historicalExecutions.set(executionId, normalized);
-        return normalized;
-      }
+    const active = this.executions.get(executionId);
+    if (active) return active;
+    const pending = this.pendingSaves.get(executionId);
+    if (pending) return pending.snapshot;
+    const stored = this.stateStore.getExecution ? await this.stateStore.getExecution(executionId) : await this.findInStoreListing(executionId);
+    if (stored) return this.normalizeStoredExecution(stored);
+    return this.recentRunsServeReads() ? this.recentRuns.get(executionId) : void 0;
+  }
+  /**
+   * By-id read for a store that lists but cannot fetch by id. A paging store
+   * is scanned page by page with the cursor, stopping at the match; any
+   * other store is listed once in full. Returns `null` when the store cannot
+   * list or does not hold the run.
+   */
+  async findInStoreListing(executionId) {
+    const store = this.stateStore;
+    if (!store.listExecutions) return null;
+    if (store.historyPaging !== true) {
+      return (await store.listExecutions()).find((e) => e.executionId === executionId) ?? null;
     }
-    return void 0;
+    let cursor;
+    for (; ; ) {
+      const page = await store.listExecutions(EXECUTION_SCAN_PAGE_SIZE, { cursor });
+      const found = page.find((e) => e.executionId === executionId);
+      if (found) return found;
+      if (page.length === 0) return null;
+      const last = [...page].sort(compareExecutionsNewestFirst)[page.length - 1];
+      if (cursor && compareExecutionsNewestFirst(last, cursor) <= 0) return null;
+      cursor = { startedAt: last.startedAt, executionId: last.executionId };
+    }
+  }
+  /** The recent-runs cache stands in for listing when the store cannot list
+   *  runs, or never receives them because it cannot save. */
+  recentRunsServeListing() {
+    return this.recentRuns !== void 0 && (!this.stateStore.saveExecution || !this.stateStore.listExecutions);
+  }
+  /** The recent-runs cache stands in for by-id reads when the store cannot
+   *  fetch or list runs (it exists only then), or never receives them because
+   *  it cannot save. */
+  recentRunsServeReads() {
+    return this.recentRuns !== void 0 && (!this.stateStore.saveExecution || !this.stateStore.getExecution);
   }
   /** Save an eval result to history. */
   async saveEvalResult(entry) {
@@ -22272,11 +23022,16 @@ var AxlRuntime = class extends EventEmitter2 {
   }
   /**
    * Delete an execution from history by id. Removes from the active map (if
-   * still running), the historical cache, the configured StateStore, AND
+   * still running), the recent-runs cache, the configured StateStore, AND
    * any execution-scoped side state — pending awaitHuman decisions,
    * resolver maps, streaming buffer registration, in-flight abort controller.
-   * Returns true if an entry was actually removed from any of the three
-   * primary surfaces (active map, historical cache, store).
+   * Returns true if the run was running, had a save in flight, or was
+   * removed from the recent-runs cache or the store.
+   *
+   * If the run has already finished but its history save has not landed
+   * yet, this method waits for that save (whether it succeeds or fails)
+   * before deleting, so the save cannot re-create the deleted record. It
+   * likewise waits for `recoverIncompleteStreams()` to finish with the id.
    *
    * In-flight handling: if the execution is still running, this method
    * **aborts** it (via the registered abort controller) AND marks the id for
@@ -22301,7 +23056,18 @@ var AxlRuntime = class extends EventEmitter2 {
    * (`defaultTtl` / `ttls.executionHistory`).
    */
   async deleteExecution(id) {
+    this.deletingExecutions.set(id, (this.deletingExecutions.get(id) ?? 0) + 1);
+    try {
+      return await this.deleteExecutionWhileMarked(id);
+    } finally {
+      const remaining = (this.deletingExecutions.get(id) ?? 1) - 1;
+      if (remaining > 0) this.deletingExecutions.set(id, remaining);
+      else this.deletingExecutions.delete(id);
+    }
+  }
+  async deleteExecutionWhileMarked(id) {
     const wasActive = this.executions.has(id);
+    const hadPendingSave = this.pendingSaves.has(id);
     const pendingDecisionResolver = this.pendingDecisionResolvers.get(id);
     const hadPendingDecision = pendingDecisionResolver !== void 0;
     if (wasActive) {
@@ -22319,22 +23085,25 @@ var AxlRuntime = class extends EventEmitter2 {
         this.pendingDecisionResolvers.delete(id);
       }
     }
+    await this.pendingSaves.get(id)?.settled;
+    await this.recoveringExecutions.get(id);
     const existing = await this.getExecution(id);
     const workflow2 = existing?.workflow;
     const removedFromActive = this.executions.delete(id);
-    const removedFromHistorical = this.historicalExecutions.delete(id);
+    const removedFromRecent = this.recentRuns?.delete(id) ?? false;
     let removedFromStore = false;
     if (this.stateStore.deleteExecution) {
       removedFromStore = await this.stateStore.deleteExecution(id);
     }
+    const removed = removedFromActive || hadPendingSave || removedFromRecent || removedFromStore;
     this.emit("execution_deleted", {
       executionId: id,
       workflow: workflow2,
       wasActive,
       hadPendingDecision,
-      removed: removedFromActive || removedFromHistorical || removedFromStore
+      removed
     });
-    return removedFromActive || removedFromHistorical || removedFromStore;
+    return removed;
   }
   /**
    * Delete an eval history entry by id. Removes from in-memory cache and
@@ -23752,12 +24521,57 @@ async function* stringStreamFromEvents(source, opts) {
 }
 
 // src/state/redis.ts
+var PRUNE_HISTORY_INDEX_SCRIPT = `
+local now = tonumber(ARGV[1])
+local removed = 0
+for i = 2, #ARGV do
+  local id = ARGV[i]
+  local pttl = redis.call('PTTL', KEYS[i + 2])
+  if pttl == -2 then
+    redis.call('SREM', KEYS[1], id)
+    redis.call('ZREM', KEYS[2], id)
+    redis.call('ZREM', KEYS[3], id)
+    removed = removed + 1
+  elseif pttl == -1 then
+    redis.call('ZREM', KEYS[3], id)
+  else
+    redis.call('ZADD', KEYS[3], string.format('%d', now + pttl), id)
+  end
+end
+return removed
+`;
+function compareMembers(a, b) {
+  return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+function compareNewestFirst(a, b) {
+  if (a.score !== b.score) return b.score - a.score;
+  return compareMembers(b.id, a.id);
+}
+function warnIfRedisExecutionRetentionUnset(opts) {
+  if (opts.ttls?.executionHistory === void 0 && typeof opts.defaultTtl !== "number") {
+    warnExecutionRetentionUnset("RedisStore");
+  }
+}
 var RedisStore = class _RedisStore {
   constructor(client, keyPrefix, ttls) {
     this.client = client;
     this.keyPrefix = keyPrefix;
     this.ttls = ttls;
   }
+  /**
+   * History kinds with a prune running in this process. A save skips its
+   * prune while another one of the same kind is in flight: the running one
+   * already covers the oldest expired entries. Created lazily so the
+   * instance needs no constructor state.
+   */
+  prunesInFlight;
+  /**
+   * Supports `listExecutions(limit, { cursor })`. A getter rather than a
+   * field so it lives on the prototype.
+   */
+  get historyPaging() {
+    return true;
+  }
   /**
    * Resolve the TTL for a given storage category. Returns `undefined` when
    * no TTL applies (category is `null` in resolved config, the value is
@@ -23836,6 +24650,7 @@ var RedisStore = class _RedisStore {
       streamingEvents: resolveStreamingEvents(opts.ttls?.streamingEvents)
     };
     const store = new _RedisStore(client, keyPrefix, effectiveTtls);
+    warnIfRedisExecutionRetentionUnset(opts);
     if (!opts.skipMigration) {
       await store.backfillExecutionIndex();
       await store.backfillEvalIndex();
@@ -23947,13 +24762,9 @@ var RedisStore = class _RedisStore {
   execHistoryKey(executionId) {
     return `${this.keyPrefix}exec-history:${executionId}`;
   }
-  // NOTE for future implementer of #3 (TTL config): when the executionHistory
-  // and evalHistory data blobs gain TTLs, eviction MUST be driven by
-  // ZREMRANGEBYSCORE on the ZSET below — NOT by SREM on these legacy ID sets.
-  // The slow-path fallback (`listHistoryByZset`) reads from the SET when
-  // `zsetCard < setCard`, so SET-based eviction would race with the fallback
-  // and surface dead IDs whose data has been TTL'd away. ZSET eviction +
-  // dual-write `SREM` is the clean path; doc the assumption then.
+  // The legacy id set and the sorted set below always change together (save,
+  // delete, prune), so the slow-path guard `ZCARD >= SCARD` in
+  // `listHistoryByZset` and backfill stays meaningful.
   execHistorySetKey() {
     return `${this.keyPrefix}exec-history-ids`;
   }
@@ -23976,6 +24787,36 @@ var RedisStore = class _RedisStore {
   evalHistoryZsetKey() {
     return `${this.keyPrefix}eval-history-z`;
   }
+  /** Keys and blob parsing for one kind of history. See {@link HistoryIndex}. */
+  historyIndex(kind) {
+    if (kind === "execution") {
+      return {
+        kind,
+        label: "execution-history",
+        ids: this.execHistorySetKey(),
+        time: this.execHistoryZsetKey(),
+        expiry: `${this.keyPrefix}exec-history-exp`,
+        dataKey: (id) => this.execHistoryKey(id),
+        lastSavedAtOf: (raw) => {
+          const record = JSON.parse(raw);
+          return typeof record.startedAt === "number" ? executionLastSavedAt(record) : null;
+        }
+      };
+    }
+    return {
+      kind,
+      label: "eval-history",
+      ids: this.evalHistorySetKey(),
+      time: this.evalHistoryZsetKey(),
+      expiry: `${this.keyPrefix}eval-history-exp`,
+      dataKey: (id) => this.evalHistoryKey(id),
+      // Eval retention counts from the first write, which is the row's timestamp.
+      lastSavedAtOf: (raw) => {
+        const timestamp = JSON.parse(raw).timestamp;
+        return typeof timestamp === "number" ? timestamp : null;
+      }
+    };
+  }
   memoryKey(scope) {
     return `${this.keyPrefix}memory:${scope}`;
   }
@@ -24147,31 +24988,35 @@ var RedisStore = class _RedisStore {
   async saveExecution(execution) {
     const ttl = this.ttlFor("executionHistory");
     const setOptions = ttl !== void 0 ? { EX: ttl } : void 0;
+    const index = this.historyIndex("execution");
+    const id = execution.executionId;
     const storedExecution = normalizeStoredExecution({
       ...execution,
       eventSchemaVersion: getExecutionEventSchemaVersion(execution)
     });
-    await this.client.multi().sAdd(this.execHistorySetKey(), execution.executionId).set(this.execHistoryKey(execution.executionId), JSON.stringify(storedExecution), setOptions).zAdd(this.execHistoryZsetKey(), {
-      score: execution.startedAt,
-      value: execution.executionId
-    }).exec();
+    const tx = this.client.multi().sAdd(index.ids, id).set(index.dataKey(id), JSON.stringify(storedExecution), setOptions).zAdd(index.time, { score: execution.startedAt, value: id });
+    if (ttl !== void 0) tx.zAdd(index.expiry, { score: Date.now() + ttl * 1e3, value: id });
+    else tx.zRem(index.expiry, id);
+    await tx.exec();
+    await this.pruneHistoryAfterSave(index);
   }
   async getExecution(executionId) {
     const raw = await this.client.get(this.execHistoryKey(executionId));
     return raw ? normalizeStoredExecution(JSON.parse(raw)) : null;
   }
-  async listExecutions(limit) {
+  async listExecutions(limit, options) {
+    const cursor = options?.cursor;
     const executions = await this.listHistoryByZset(
-      this.execHistorySetKey(),
-      this.execHistoryZsetKey(),
-      (id) => this.execHistoryKey(id),
-      (a, b) => b.startedAt - a.startedAt,
-      limit
+      this.historyIndex("execution"),
+      (e) => ({ score: e.startedAt, id: e.executionId }),
+      limit,
+      cursor !== void 0 ? { score: cursor.startedAt, id: cursor.executionId } : void 0
     );
     return executions.map(normalizeStoredExecution);
   }
   async deleteExecution(executionId) {
-    const results = await this.client.multi().sRem(this.execHistorySetKey(), executionId).del(this.execHistoryKey(executionId)).zRem(this.execHistoryZsetKey(), executionId).del(this.checkpointKey(executionId)).del(this.executionStateKey(executionId)).sRem(this.pendingExecSetKey(), executionId).del(this.streamingEventsKey(executionId)).sRem(this.streamingIdsKey(), executionId).hDel(this.decisionsKey(), executionId).exec();
+    const index = this.historyIndex("execution");
+    const results = await this.client.multi().sRem(index.ids, executionId).del(index.dataKey(executionId)).zRem(index.time, executionId).zRem(index.expiry, executionId).del(this.checkpointKey(executionId)).del(this.executionStateKey(executionId)).sRem(this.pendingExecSetKey(), executionId).del(this.streamingEventsKey(executionId)).sRem(this.streamingIdsKey(), executionId).hDel(this.decisionsKey(), executionId).exec();
     return results.some((result) => typeof result === "number" && result > 0);
   }
   // ── Eval History ────────────────────────────────────────────────────
@@ -24196,18 +25041,31 @@ var RedisStore = class _RedisStore {
    * lifetime, so the race costs at most one window's length, never the window
    * itself. It also carries no Redis version floor, where `KEEPTTL` needs 6.0.
    *
-   * The index entries carry no TTL and age out lazily, as with `saveExecution`.
+   * As with `saveExecution`, a timed row is also scored in the expiry sorted
+   * set (by the expiry it carries, so a re-save keeps its score), an untimed
+   * one is taken out of it, and a bounded prune follows the save.
    */
   async saveEvalResult(entry) {
     const ttl = this.ttlFor("evalHistory");
-    const key = this.evalHistoryKey(entry.id);
+    const index = this.historyIndex("eval");
+    const key = index.dataKey(entry.id);
     let setOptions;
+    let expiresAt;
     if (ttl !== void 0) {
       const remaining = await this.client.pTTL(key);
-      if (remaining === -2) setOptions = { EX: ttl };
-      else if (remaining > 0) setOptions = { PX: remaining };
+      if (remaining === -2) {
+        setOptions = { EX: ttl };
+        expiresAt = Date.now() + ttl * 1e3;
+      } else if (remaining > 0) {
+        setOptions = { PX: remaining };
+        expiresAt = Date.now() + remaining;
+      }
     }
-    await this.client.multi().sAdd(this.evalHistorySetKey(), entry.id).set(key, JSON.stringify(entry), setOptions).zAdd(this.evalHistoryZsetKey(), { score: entry.timestamp, value: entry.id }).exec();
+    const tx = this.client.multi().sAdd(index.ids, entry.id).set(key, JSON.stringify(entry), setOptions).zAdd(index.time, { score: entry.timestamp, value: entry.id });
+    if (expiresAt !== void 0) tx.zAdd(index.expiry, { score: expiresAt, value: entry.id });
+    else tx.zRem(index.expiry, entry.id);
+    await tx.exec();
+    await this.pruneHistoryAfterSave(index);
   }
   /**
    * Update-only write: see `StateStore.updateEvalResult`.
@@ -24247,15 +25105,14 @@ var RedisStore = class _RedisStore {
   }
   async listEvalResults(limit) {
     return this.listHistoryByZset(
-      this.evalHistorySetKey(),
-      this.evalHistoryZsetKey(),
-      (id) => this.evalHistoryKey(id),
-      (a, b) => b.timestamp - a.timestamp,
+      this.historyIndex("eval"),
+      (e) => ({ score: e.timestamp, id: e.id }),
       limit
     );
   }
   async deleteEvalResult(id) {
-    const [, deletedCount] = await this.client.multi().sRem(this.evalHistorySetKey(), id).del(this.evalHistoryKey(id)).zRem(this.evalHistoryZsetKey(), id).exec();
+    const index = this.historyIndex("eval");
+    const [, deletedCount] = await this.client.multi().sRem(index.ids, id).del(index.dataKey(id)).zRem(index.time, id).zRem(index.expiry, id).exec();
     const deleted = typeof deletedCount === "number" ? deletedCount : 0;
     return deleted > 0;
   }
@@ -24279,50 +25136,291 @@ var RedisStore = class _RedisStore {
     return { exists: true, expiresAt: Date.now() + ttl };
   }
   /**
-   * Shared list-by-sorted-set implementation. Uses ZREVRANGEBYSCORE +
-   * MGET when the ZSET is populated (post-migration). Falls back to the
-   * legacy SET + N×GET + JS-sort path when the ZSET is empty or smaller
-   * than the SET (covers users that constructed with `skipMigration: true`
-   * before calling backfill).
+   * Shared list-by-sorted-set implementation, newest first by
+   * `(score DESC, member DESC)`, starting strictly after `cursor` when given.
+   *
+   * Fast path (the time sorted set is at least as large as the id set): walk
+   * the sorted set in chunks and MGET each chunk's blobs. Index entries whose
+   * blob is gone (expired, or deleted before the prune caught up) are skipped,
+   * and the walk keeps reading until it has `limit` live records or the set
+   * runs out, however many dead entries are in the way. Each chunk restarts
+   * at the last member read, by score and member, rather than at an offset,
+   * so entries added or removed meanwhile cannot shift the walk.
+   *
+   * Slow path (the time sorted set is behind the id set: backfill has not
+   * run): read every id with GET, then sort and apply the cursor in process.
    */
-  async listHistoryByZset(setKey, zsetKey, dataKey, sortCmp, limit) {
-    const setSize = await this.client.sCard(setKey);
+  async listHistoryByZset(index, positionOf, limit, cursor) {
+    const setSize = await this.client.sCard(index.ids);
     if (setSize === 0) return [];
-    const zsetSize = await this.client.zCard(zsetKey);
-    if (zsetSize >= setSize) {
-      const fetchCount = limit !== void 0 ? Math.max(limit * 2, limit + 5) : void 0;
-      const ids2 = await this.client.zRange(zsetKey, "+inf", "-inf", {
+    const zsetSize = await this.client.zCard(index.time);
+    const max = limit ? limit : void 0;
+    if (zsetSize < setSize) {
+      const ids = await this.client.sMembers(index.ids);
+      const entries = [];
+      for (const id of ids) {
+        const raw = await this.client.get(index.dataKey(id));
+        if (raw == null) continue;
+        try {
+          entries.push(JSON.parse(raw));
+        } catch {
+        }
+      }
+      const ordered = entries.filter((e) => cursor === void 0 || compareNewestFirst(cursor, positionOf(e)) < 0).sort((a, b) => compareNewestFirst(positionOf(a), positionOf(b)));
+      return max !== void 0 ? ordered.slice(0, max) : ordered;
+    }
+    const results = [];
+    const seen = /* @__PURE__ */ new Set();
+    let bound = cursor;
+    let rangeMax = cursor !== void 0 ? cursor.score : "+inf";
+    let anchor;
+    let grow = 1;
+    const read = (offset, count2) => (
+      // ZRANGE BY SCORE REV: start is the highest score, stop the lowest.
+      this.client.zRangeWithScores(index.time, rangeMax, "-inf", {
         BY: "SCORE",
         REV: true,
-        ...fetchCount !== void 0 ? { LIMIT: { offset: 0, count: fetchCount } } : {}
+        ...count2 !== void 0 ? { LIMIT: { offset, count: count2 } } : {}
+      })
+    );
+    for (; ; ) {
+      const remaining = max !== void 0 ? max - results.length : void 0;
+      const want = remaining !== void 0 ? Math.max(remaining * 2, remaining + 5) * grow : void 0;
+      let offset = 0;
+      let count2 = want;
+      let members;
+      if (anchor !== void 0 && want !== void 0) {
+        offset = anchor.pos;
+        count2 = want + 1;
+        members = await read(offset, count2);
+        if (members[0]?.value !== anchor.id) {
+          offset = 0;
+          count2 = anchor.pos + 1 + want;
+          members = await read(offset, count2);
+        }
+      } else {
+        members = await read(offset, count2);
+      }
+      const fresh = members.filter(
+        (m) => !seen.has(m.value) && (bound === void 0 || compareNewestFirst(bound, { score: m.score, id: m.value }) < 0)
+      );
+      if (fresh.length > 0) {
+        const raws = await this.client.mGet(fresh.map((m) => index.dataKey(m.value)));
+        for (let i = 0; i < fresh.length; i++) {
+          seen.add(fresh[i].value);
+          const raw = raws[i];
+          if (raw == null) continue;
+          try {
+            results.push(JSON.parse(raw));
+          } catch {
+            continue;
+          }
+          if (max !== void 0 && results.length >= max) return results;
+        }
+        const lastFresh = fresh[fresh.length - 1];
+        bound = { score: lastFresh.score, id: lastFresh.value };
+        grow = 1;
+      } else {
+        grow *= 2;
+      }
+      if (count2 === void 0 || members.length < count2) return results;
+      const last = members[members.length - 1];
+      if (last.score === rangeMax) {
+        anchor = { id: last.value, score: last.score, pos: offset + members.length - 1 };
+      } else {
+        rangeMax = last.score;
+        const before = members.filter((m) => m.score === last.score).length - 1;
+        anchor = { id: last.value, score: last.score, pos: before };
+      }
+    }
+  }
+  // ── History index cleanup ──────────────────────────────────────────────
+  //
+  // Index members cannot carry a TTL, so when a history record expires its
+  // entries in the id set and the time sorted set stay behind. Every history
+  // save runs one bounded prune of its kind: it reads up to PRUNE_BATCH ids
+  // whose expiry has passed from the expiry sorted set, then runs
+  // PRUNE_HISTORY_INDEX_SCRIPT over them. The script checks each record's blob
+  // and updates the indexes in one atomic step, so a save or delete landing
+  // between the read and the script cannot be undone by it: a record saved
+  // again is seen live and stays listed, and a deleted one is already gone.
+  // The script only removes index entries and re-scores expiry entries; it
+  // never adds a listing entry or writes a blob, so it cannot bring back
+  // deleted data. Several instances pruning at once is safe.
+  /**
+   * Run one prune of `index`'s kind after a save. A prune failure does not
+   * fail the save, whose MULTI already committed the record: it is reported
+   * once per process and the next save of that kind tries again. That also
+   * covers a Redis user whose ACL denies `EVAL`.
+   */
+  async pruneHistoryAfterSave(index) {
+    const inFlight = this.prunesInFlight ??= /* @__PURE__ */ new Set();
+    if (inFlight.has(index.kind)) return;
+    inFlight.add(index.kind);
+    try {
+      await this.pruneHistory(index);
+    } catch (err) {
+      warnDiagnosticOnce(
+        `redis_history_prune_failed\0${index.kind}`,
+        `RedisStore: removing expired ${index.label} index entries failed (${err instanceof Error ? err.message : String(err)}). The record was saved; the next save retries the cleanup. Listings stay correct meanwhile. The cleanup runs a Lua script, so the Redis user needs permission to run EVAL.`,
+        void 0,
+        "docs/api-reference.md#redisstore-options"
+      );
+    } finally {
+      inFlight.delete(index.kind);
+    }
+  }
+  async pruneHistory(index) {
+    const candidates = await this.client.zRange(index.expiry, "-inf", Date.now(), {
+      BY: "SCORE",
+      LIMIT: { offset: 0, count: PRUNE_BATCH }
+    });
+    if (candidates.length > 0) await this.runPruneScript(index, candidates);
+  }
+  /**
+   * Run {@link PRUNE_HISTORY_INDEX_SCRIPT} over `ids`, at most PRUNE_BATCH
+   * per call so one script never blocks the server for long.
+   */
+  async runPruneScript(index, ids) {
+    for (let start = 0; start < ids.length; start += PRUNE_BATCH) {
+      const chunk = ids.slice(start, start + PRUNE_BATCH);
+      await this.client.eval(PRUNE_HISTORY_INDEX_SCRIPT, {
+        keys: [index.ids, index.time, index.expiry, ...chunk.map((id) => index.dataKey(id))],
+        arguments: [String(Date.now()), ...chunk]
       });
-      if (ids2.length === 0) return [];
-      const keys = ids2.map(dataKey);
-      const raws = await this.client.mGet(keys);
-      const entries2 = [];
-      for (const raw of raws) {
-        if (raw == null) continue;
+    }
+  }
+  // ── History maintenance ────────────────────────────────────────────────
+  /**
+   * See `StateStore.applyHistoryRetention`. One call:
+   *
+   * 1. On the first call of a walk (no cursor), backfills the time sorted
+   *    set from the id set if it is behind (see `backfillExecutionIndex`).
+   * 2. Reads the next `batchSize` ids from the time sorted set, oldest first
+   *    by `(score, member)`, strictly after the cursor. The read restarts at
+   *    the cursor's position by value, never by offset.
+   * 3. MGETs their blobs and reads each live blob's PTTL.
+   * 4. In one MULTI, for each live blob:
+   *    - a TTL (`PTTL > 0`): `ZADD NX` to the expiry set at now + PTTL. A
+   *      record already in the expiry set keeps its entry (`indexed` counts
+   *      only new entries).
+   *    - no TTL (`-1`), with a retention configured: `PEXPIREAT … NX` at last
+   *      save + retention. `NX` applies only to a key that still has no TTL,
+   *      so a record re-saved meanwhile keeps the fresh window its save gave
+   *      it. A window that has already passed uses a timestamp in the past,
+   *      which makes Redis delete the key, again only if it is still untimed.
+   * 5. Adds each newly armed record to the expiry set (`ZADD NX`).
+   * 6. Runs the prune script (`PRUNE_HISTORY_INDEX_SCRIPT`) over ids whose
+   *    blob is gone and ids just deleted in step 4. It checks each blob
+   *    atomically, so a record re-saved at any point stays listed and a
+   *    deleted one is never re-indexed.
+   *
+   * Blobs are never written. A record deleted while the call runs can leave
+   * an entry in the expiry set only; the next prune removes it.
+   */
+  async applyHistoryRetention(options) {
+    const { kind, batchSize, cursor } = resolveHistoryRetentionOptions("RedisStore", options);
+    const index = this.historyIndex(kind === "executions" ? "execution" : "eval");
+    const ttl = this.ttlFor(kind === "executions" ? "executionHistory" : "evalHistory");
+    if (cursor === void 0) {
+      if (kind === "executions") await this.backfillExecutionIndex();
+      else await this.backfillEvalIndex();
+    }
+    const positions = await this.readRetentionBatch(index, cursor, batchSize + 1);
+    const batch = positions.slice(0, batchSize);
+    const result = {
+      expired: 0,
+      armed: 0,
+      indexed: 0,
+      deadIndexEntries: 0,
+      cursor: positions.length > batchSize ? { time: batch[batch.length - 1].score, id: batch[batch.length - 1].value } : null
+    };
+    if (batch.length === 0) return result;
+    const ids = batch.map((m) => m.value);
+    const raws = await this.client.mGet(ids.map((id) => index.dataKey(id)));
+    const dead = ids.filter((_, i) => raws[i] == null);
+    const present = ids.flatMap((id, i) => {
+      const raw = raws[i];
+      return raw == null ? [] : [{ id, raw }];
+    });
+    const pttls = await Promise.all(present.map((r) => this.client.pTTL(index.dataKey(r.id))));
+    const now = Date.now();
+    const tx = this.client.multi();
+    const queued = [];
+    for (let i = 0; i < present.length; i++) {
+      const { id, raw } = present[i];
+      const pttl = pttls[i];
+      if (pttl === -2) {
+        dead.push(id);
+      } else if (pttl > 0) {
+        tx.zAdd(index.expiry, { score: now + pttl, value: id }, { condition: "NX" });
+        queued.push({ action: "index", id });
+      } else if (pttl === -1 && ttl !== void 0) {
+        let lastSavedAt;
         try {
-          entries2.push(JSON.parse(raw));
+          lastSavedAt = index.lastSavedAtOf(raw);
         } catch {
+          lastSavedAt = null;
+        }
+        if (lastSavedAt === null) continue;
+        const decision = retentionForUntimedRecord(lastSavedAt, ttl, now);
+        if (decision.expired) {
+          tx.pExpireAt(index.dataKey(id), 1, "NX");
+          queued.push({ action: "expire", id });
+        } else {
+          tx.pExpireAt(index.dataKey(id), decision.expiresAt, "NX");
+          queued.push({ action: "arm", id, expiresAt: decision.expiresAt });
         }
-        if (limit !== void 0 && entries2.length >= limit) break;
       }
-      return entries2;
     }
-    const ids = await this.client.sMembers(setKey);
-    if (ids.length === 0) return [];
-    const entries = [];
-    for (const id of ids) {
-      const raw = await this.client.get(dataKey(id));
-      if (raw == null) continue;
-      try {
-        entries.push(JSON.parse(raw));
-      } catch {
+    const expiredIds = [];
+    const armed = [];
+    if (queued.length > 0) {
+      const replies = await tx.exec();
+      for (let i = 0; i < queued.length; i++) {
+        if (Number(replies[i]) !== 1) continue;
+        const entry = queued[i];
+        if (entry.action === "index") result.indexed++;
+        else if (entry.action === "expire") expiredIds.push(entry.id);
+        else armed.push(entry);
       }
     }
-    entries.sort(sortCmp);
-    return limit ? entries.slice(0, limit) : entries;
+    if (armed.length > 0) {
+      const indexTx = this.client.multi();
+      for (const { id, expiresAt } of armed) {
+        indexTx.zAdd(index.expiry, { score: expiresAt, value: id }, { condition: "NX" });
+      }
+      await indexTx.exec();
+    }
+    result.armed = armed.length;
+    result.expired = expiredIds.length;
+    result.deadIndexEntries = dead.length;
+    if (dead.length > 0 || expiredIds.length > 0) {
+      await this.runPruneScript(index, [...dead, ...expiredIds]);
+    }
+    return result;
+  }
+  /**
+   * Up to `count` members of the time sorted set strictly after `cursor`,
+   * oldest first by `(score, member)`. The members sharing the cursor's score
+   * are read in full and filtered by member; the rest start just above that
+   * score. Neither read uses an offset, so entries removed or added
+   * meanwhile cannot shift the walk.
+   */
+  async readRetentionBatch(index, cursor, count2) {
+    if (cursor === void 0) {
+      return this.client.zRangeWithScores(index.time, "-inf", "+inf", {
+        BY: "SCORE",
+        LIMIT: { offset: 0, count: count2 }
+      });
+    }
+    const ties = (await this.client.zRangeWithScores(index.time, cursor.time, cursor.time, { BY: "SCORE" })).filter((m) => compareMembers(m.value, cursor.id) > 0);
+    if (ties.length >= count2) return ties.slice(0, count2);
+    const rest = await this.client.zRangeWithScores(index.time, `(${cursor.time}`, "+inf", {
+      BY: "SCORE",
+      LIMIT: { offset: 0, count: count2 - ties.length }
+    });
+    return [...ties, ...rest];
   }
   // ── Sessions (Studio introspection) ────────────────────────────────────
   async listSessions() {