@flame0510/project-aether 1.5.1 → 1.6.0

package/docs/dev/API-REFERENCE.md

@@ -316,6 +316,38 @@ Rev4a Provider Gateway — proxy chat completions to the correct upstream.
 
 ---
 
+### `GET /api/models/details?id=<model id>`
+Everything the details modal shows for one model, and nothing more: fields the sources do
+not have are **absent**, never `null` and never a guess.
+
+**Auth:** browser cookie or bearer token
+
+**Response:**
+```json
+{
+  "id": "glm/glm-5.3-flash", "name": "GLM-5.3 Flash", "provider": "glm",
+  "modality": "text+image+video->text", "enabled": false, "deprecated": false,
+  "price": { "input": 0.15, "output": 0.5, "source": "vendor" },
+  "details": { "description": "…", "created": "2026-08-26", "context": 1310720,
+               "providerContext": 1048576, "maxOutput": 943718,
+               "reasoning": { "mandatory": true, "default_effort": "max", "supported_efforts": ["max","high","low"] },
+               "supportedParameters": ["tools","reasoning","…"],
+               "benchmarks": { "design_arena": [ … ], "artificial_analysis": { … } },
+               "huggingFaceId": "zai-org/GLM-5.3-Flash", "url": "https://openrouter.ai/…" },
+  "info": null,
+  "asOf": "2026-09-23T14:02:40.271Z",
+  "detailsSource": "openrouter"
+}
+```
+
+`price.source` is `openrouter` for an `openrouter/*` entry and `vendor` for a direct one,
+which keeps prices honest: the refresh script never writes a vendor price. `details` comes
+from the generated `model-details.json` (`npm run refresh:pricing`, see
+`docs/dev/GATEWAY.md`), `info` from the catalogue's hand-written block, and `asOf` is when
+the generated part was produced. An id the catalogue does not carry answers `404`.
+
+**Errors:** `400` missing `id`, `404` unknown model.
+
 ### `GET /api/models`
 Models eligible to be used: the catalogue filtered down to models that are enabled
 (after overrides) and whose provider has a key configured, grouped by provider. Feeds the model pickers in the agent's
@@ -1339,7 +1371,10 @@ releases used are gone, and reading those returned nothing).
 |---|---|---|
 | `channel` | no | Channel name (default: `telegram`) |
 
-**Response:**
+**Response:** `{ pending: [...], approved: [...], error: null }` — `error` carries why the
+approved list is empty when that is not simply "none" (the store could not be read); the
+panel shows it instead of "No approved senders". A missing store is not an error.
+
 ```json
 {
   "pending": [
@@ -2561,8 +2596,11 @@ from local state only.
 
 **Response:** `{ "installed": "1.4.2", "latest": "1.5.0", "updateAvailable": true, "package": "@flame0510/project-aether", "log": "update.log" }`
 
-`log` is the file name, in the Rev4a data directory, where the update's output is
-written.
+`installed` is `null` when `package.json` cannot be read — during an update npm rewrites
+it, and a transient failure must not look like a version. With `installed` unknown there
+is nothing to compare, so `latest` is `null` and `updateAvailable` false. `installed` is
+never a placeholder like `0.0.0`. `log` is the file name, in the Rev4a data directory,
+where the update's output is written.
 
 ### `POST /api/update-check`
 Run `rev4a update` as a detached background process. Nothing here restarts anything:

package/docs/dev/GATEWAY.md

@@ -148,6 +148,64 @@ for anyone cloning the project. It defines all known models across all providers
 Only enabled models for providers with a configured API key are synced to agent
 containers.
 
+Provider display names come from `lib/provider-labels.ts`: the Gateway's cards and the
+details modal read the same map, so a provider is never called two things in one page.
+
+### Model details (the details modal)
+
+The Gateway model row has a **⋯ Details** button opening `ModelDetailsModal`
+(`app/gateway/ModelDetailsModal.tsx`), fed by `GET /api/models/details?id=`. Three
+sources, each one labelled in the modal:
+
+| Source | File | Nature |
+|---|---|---|
+| Identity, enabled, modality, deprecation | `models.config.json` | curated by hand |
+| Price | `model-pricing.json` | refreshed for `openrouter/*`, hand for direct vendors |
+| Description, specs, benchmarks | `model-details.json` | **generated**, never hand-edited |
+
+`npm run refresh:pricing` (script `scripts/refresh-model-pricing.mjs`) fetches the
+OpenRouter catalogue once and writes both the prices and `model-details.json`:
+description, release date (`created`), context and the provider's own limit, max output,
+tokenizer, instruct type, knowledge cutoff, Hugging Face id, reasoning (mandatory, default
+and supported efforts), supported parameters, and the benchmarks OpenRouter publishes
+(design arenas with elo/rank/win-rate, Artificial Analysis indices).
+
+**Size and architecture** come from a second source: for every entry with a
+`hugging_face_id` the script asks the Hugging Face API (`safetensors.total` and the
+per-dtype breakdown, the task, the languages, downloads and likes) **and the model's
+`config.json`** — the API's summary config is reduced, the raw file is what carries the
+architecture. That covers the **open-weight** models (DeepSeek, GLM, Kimi, Qwen, Llama,
+StepFun…); a closed model has no card, so it gets no `params` and no `hf` block, and the
+modal hides those rows rather than estimating. `--no-hf` skips the lookups.
+
+Stored per model in an `hf` object: the architecture class and type, the mixture of
+experts (`experts`, per token, shared), layers, hidden size, attention heads (and KV
+heads, since MQA/GQA change what serving costs), vocabulary, the model's own max context,
+whether it has a **vision encoder** (multimodal models nest their language model under
+`text_config` and the encoder under `vision_config`), the precision (`fp8`,
+`compressed-tensors`…) and the weight mix by dtype, the task, the languages and the
+popularity. For a mixture-of-experts model the card's number is the **total**; an *active*
+count is a derivation, so the modal shows the facts (experts, per token) and the curated
+`info.params` free text can add the vendor's own "355B total, ~32B active". A direct entry is
+matched through the vendor alias map (`glm` → `z-ai`, `kimi` → `moonshotai`) for the data
+only — **its price stays the vendor's own**, and the modal says which is which.
+
+Anything OpenRouter does not publish is curated in the catalogue as an optional `info`
+block, and every number there carries its source:
+
+```json
+"info": {
+  "params": "~1.8T MoE (active ~40B)",
+  "docUrl": "https://docs.z.ai/guides/vlm/glm-5.3-flash",
+  "knowledgeCutoff": "2026-03",
+  "benchmarks": [ { "name": "SWE-bench Verified", "value": 78.4, "source": "https://…", "asOf": "2026-08-26" } ],
+  "notes": "Native multimodal; 3x the coding-plan quota."
+}
+```
+
+No generated field ever replaces a curated one silently: prices are separate files, and the
+modal shows the generated part's date (`asOf`).
+
 ---
 
 ## Per-agent model assignment

package/docs/rag/REV4A-OVERVIEW.md

@@ -1,6 +1,6 @@
 # What is Rev4a?
 
-> **Last updated:** 2026-09-15
+> **Last updated:** 2026-09-22
 
 Rev4a is the control panel for your AI agent infrastructure. It shows you everything your agents are doing, how much they cost, and whether the system is healthy — all in one dashboard.
 
@@ -36,6 +36,12 @@ The agent list also shows a compact TG chip next to each agent name (green = con
 
 **Browser access:** on agents running OpenClaw 9.x, every new browser has to be approved once before the agent's Control UI connects. The detail panel's "BROWSER ACCESS" section lists browsers waiting for approval, with Approve and Reject, and the browsers already approved, with Rename and Revoke. A yellow "BROWSER WAITING" chip on the agent card says a request is pending. The **Open** button tries a one-time link that lets the browser in without any approval; if the agent cannot issue one (it is stopped, or the link fails) it opens the normal link. To let someone else in, **Invite link** gives a link to send them: their browser appears under waiting for approval, and nothing opens until you approve it. The link contains the token all agents share; changing the agents token cancels every link already sent.
 
+Rev4a itself has an **"Update available"** banner: it starts `rev4a update` and the server
+restarts itself, so the dashboard drops briefly. The banner is only shown when a newer
+version is published; it waits for the restart and then confirms the new version, or
+reports that the update did not complete and points at `update.log` in the Rev4a data
+directory, where the update's output is written.
+
 The Agents page includes a banner for the **agent base image**, which is kept per
 OpenClaw version. It is hidden when a supported version is downloaded and nothing newer
 is published. When no image is downloaded it offers **Download Image**; when a newer

package/docs/rag/WHAT-I-CAN-ANSWER.md

@@ -1,6 +1,6 @@
 # What PULSE Can Answer
 
-> **Last updated:** 2026-09-15
+> **Last updated:** 2026-09-22
 
 PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she can and cannot answer.
 
@@ -102,6 +102,7 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 - "Why is the agent base image banner showing?"
 - "How do I fix 'image is outdated'?"
 - "How do agent image updates work?" — The banner on the Agents page runs a `docker pull`. It is a download, not a build: there is no modal, no live log, and no way to abort from the UI.
+- "How do I update Rev4a itself?" — The "Update available" banner starts `rev4a update` in the background (the same command as from a shell). It installs the new version and Rev4a restarts itself, so the dashboard drops for a short while; the banner waits for the new version and then confirms it, or says the update did not complete. The update's output is written to `update.log` in the Rev4a data directory (`~/.config/rev4a/data/update.log`) — the only place that says why an update failed.
 - "Why is my Telegram bot not connecting?"
 - "Why can't I approve a pairing code?"
 - "Why is the TG badge missing from my agent?"

package/instrumentation.ts

@@ -65,5 +65,16 @@ export async function register() {
     } catch {
       console.warn('[rev4a] Could not reconcile cold backups on startup');
     }
+    // Retention for the lifecycle job tables: the panel reads the latest row of each
+    // agent, so the history is trimmed to the newest rows per agent. Best-effort.
+    try {
+      const { pruneLifecycleRows } = await import('./lib/agent-jobs-maintenance');
+      const removed = pruneLifecycleRows().filter((r) => r.removed > 0);
+      if (removed.length) {
+        console.log(`[rev4a] Pruned job history: ${removed.map((r) => `${r.table} ${r.removed}`).join(', ')}`);
+      }
+    } catch {
+      console.warn('[rev4a] Could not prune the lifecycle job history');
+    }
   }
 }

package/lib/agent-edit-state.ts

@@ -2,9 +2,10 @@
  * Persisted state of agent edits: the `agent_edits` table (lib/db-bootstrap.mjs).
  *
  * Kept apart from lib/agent-edit.ts so busy checks (lib/agent-busy.ts) can ask which
- * agents are being edited without importing the edit action.
+ * agents are being edited without importing the edit action. The machinery is
+ * lib/agent-job-state.ts; this file holds the table's types and names.
  */
-import { openDb } from '@/lib/db';
+import { createJobState } from '@/lib/agent-job-state';
 
 export type EditStatus = 'rebuilding' | 'done' | 'failed' | 'interrupted';
 
@@ -25,84 +26,42 @@ export interface AgentEditRow {
 
 const FINAL: readonly EditStatus[] = ['done', 'failed', 'interrupted'];
 
-export function insertEdit(agentId: string, displayName: string | null, portRange: string | null): number {
-  const db = openDb(false);
-  try {
-    const now = Date.now();
-    const info = db.prepare(
-      `INSERT INTO agent_edits (agent_id, status, display_name, port_range, started_at, updated_at)
-       VALUES (?, 'rebuilding', ?, ?, ?, ?)`,
-    ).run(agentId, displayName, portRange, now, now);
-    return Number(info.lastInsertRowid);
-  } finally {
-    db.close();
-  }
-}
+const state = createJobState({
+  table: 'agent_edits',
+  initialStatus: 'rebuilding',
+  activeStatuses: ACTIVE_EDIT_STATUSES,
+  finalStatuses: FINAL,
+  insertColumns: ['display_name', 'port_range'],
+  writableColumns: [],
+});
 
 type Writable = Partial<Pick<AgentEditRow, 'status' | 'error'>>;
 
+export function insertEdit(agentId: string, displayName: string | null, portRange: string | null): number {
+  return state.insert(agentId, displayName, portRange);
+}
+
 export function updateEditRow(id: number, fields: Writable): void {
-  const entries = Object.entries(fields).filter(([, v]) => v !== undefined);
-  const now = Date.now();
-  const sets = [...entries.map(([k]) => `${k} = ?`), 'updated_at = ?'];
-  const values: unknown[] = [...entries.map(([, v]) => v), now];
-  if (fields.status && FINAL.includes(fields.status)) {
-    sets.push('finished_at = ?');
-    values.push(now);
-  } else if (fields.status) {
-    sets.push('finished_at = NULL');
-  }
-  const db = openDb(false);
-  try {
-    db.prepare(`UPDATE agent_edits SET ${sets.join(', ')} WHERE id = ?`).run(...values, id);
-  } finally {
-    db.close();
-  }
+  state.update(id, fields);
 }
 
 export function latestEdit(agentId: string): AgentEditRow | null {
-  const db = openDb(true);
-  try {
-    return (db.prepare('SELECT * FROM agent_edits WHERE agent_id = ? ORDER BY id DESC LIMIT 1').get(agentId) as AgentEditRow | undefined) ?? null;
-  } finally {
-    db.close();
-  }
+  return state.latest<AgentEditRow>(agentId);
 }
 
 export function isEditActive(agentId: string): boolean {
-  const row = latestEdit(agentId);
-  return !!row && ACTIVE_EDIT_STATUSES.includes(row.status);
+  return state.isActive(agentId);
 }
 
-/** AGENT_IDs with an edit in an active status. */
 export function activeEditAgentIds(): Set<string> {
-  const db = openDb(true);
-  try {
-    const placeholders = ACTIVE_EDIT_STATUSES.map(() => '?').join(', ');
-    const rows = db.prepare(`SELECT DISTINCT agent_id FROM agent_edits WHERE status IN (${placeholders})`).all(...ACTIVE_EDIT_STATUSES) as { agent_id: string }[];
-    return new Set(rows.map((r) => r.agent_id));
-  } finally {
-    db.close();
-  }
+  return state.activeAgentIds();
 }
 
-/**
- * At startup no edit job can be running: a row still active was cut off by the restart.
- * It becomes `interrupted`, keeping the name and port it was applying.
- */
 export function markInterruptedEdits(): number {
-  const db = openDb(false);
-  try {
-    const placeholders = ACTIVE_EDIT_STATUSES.map(() => '?').join(', ');
-    const now = Date.now();
-    const info = db.prepare(
-      `UPDATE agent_edits
-         SET error = COALESCE(error, 'Rev4a restarted while this step was running: ' || status),
-             status = 'interrupted', updated_at = ?, finished_at = ?
-       WHERE status IN (${placeholders})`,
-    ).run(now, now, ...ACTIVE_EDIT_STATUSES);
-    return info.changes;
-  } finally {
-    db.close();
-  }
+  return state.markInterrupted();
+}
+
+/** Keep the newest `keepPerAgent` edits of each agent; the rest is history. */
+export function pruneEdits(keepPerAgent: number): number {
+  return state.prune(keepPerAgent);
 }

package/lib/agent-job-state.ts

@@ -0,0 +1,145 @@
+/**
+ * The four lifecycle job tables — `agent_upgrades`, `agent_recreates`, `agent_restores`,
+ * `agent_edits` — are the same machine: an insert that starts a row in one status, an
+ * update that stamps `updated_at` and `finished_at`, a latest lookup, an "is something
+ * running" check, an at-startup sweep that turns interrupted rows into `interrupted`, and
+ * a retention prune. They used to be four copies of that code, which drifted; this factory
+ * is the single implementation, and each table keeps its own types and function names.
+ *
+ * The table and column names come from this file's callers, never from a request, and
+ * `update` only writes the columns its spec allows: nothing user-supplied can reach the
+ * generated SQL.
+ */
+import { openDb } from '@/lib/db';
+
+export interface JobStateSpec {
+  /** Table name (created by lib/db-bootstrap.mjs). */
+  table: string;
+  /** The status an inserted row starts in. */
+  initialStatus: string;
+  /** Statuses during which the agent must not be touched by anything else. */
+  activeStatuses: readonly string[];
+  /** Statuses that end a job: `finished_at` is stamped when one is set. */
+  finalStatuses: readonly string[];
+  /** Extra columns `insert` writes, after agent_id/status/started_at/updated_at. */
+  insertColumns: readonly string[];
+  /** Extra columns `update` may set, besides status and error. */
+  writableColumns: readonly string[];
+}
+
+export interface JobState {
+  insert(agentId: string, ...values: (string | number | null)[]): number;
+  update(id: number, fields: Record<string, string | null | undefined>): void;
+  latest<T>(agentId: string): T | null;
+  isActive(agentId: string): boolean;
+  activeAgentIds(): Set<string>;
+  markInterrupted(): number;
+  /** Delete all but the newest `keepPerAgent` rows of each agent. Returns the count. */
+  prune(keepPerAgent: number): number;
+}
+
+export function createJobState(spec: JobStateSpec): JobState {
+  const { table, initialStatus, activeStatuses, finalStatuses } = spec;
+  const insertColumns = ['agent_id', 'status', ...spec.insertColumns, 'started_at', 'updated_at'];
+  const writable = new Set(['status', 'error', ...spec.writableColumns]);
+  const activePlaceholders = activeStatuses.map(() => '?').join(', ');
+
+  const latest = <T,>(agentId: string): T | null => {
+    const db = openDb(true);
+    try {
+      return (db.prepare(`SELECT * FROM ${table} WHERE agent_id = ? ORDER BY id DESC LIMIT 1`).get(agentId) as T | undefined) ?? null;
+    } finally {
+      db.close();
+    }
+  };
+
+  return {
+    insert(agentId, ...values) {
+      if (values.length !== spec.insertColumns.length) {
+        throw new Error(`${table}: insert expects ${spec.insertColumns.length} value(s), got ${values.length}`);
+      }
+      const db = openDb(false);
+      try {
+        const now = Date.now();
+        const info = db.prepare(
+          `INSERT INTO ${table} (${insertColumns.join(', ')})
+           VALUES (${insertColumns.map(() => '?').join(', ')})`,
+        ).run(agentId, initialStatus, ...values, now, now);
+        return Number(info.lastInsertRowid);
+      } finally {
+        db.close();
+      }
+    },
+
+    update(id, fields) {
+      const entries = Object.entries(fields).filter(([key, value]) => value !== undefined && writable.has(key));
+      const now = Date.now();
+      const sets = [...entries.map(([key]) => `${key} = ?`), 'updated_at = ?'];
+      const values: unknown[] = [...entries.map(([, value]) => value), now];
+      const status = fields.status;
+      if (status && finalStatuses.includes(status)) {
+        sets.push('finished_at = ?');
+        values.push(now);
+      } else if (status) {
+        sets.push('finished_at = NULL');
+      }
+      const db = openDb(false);
+      try {
+        db.prepare(`UPDATE ${table} SET ${sets.join(', ')} WHERE id = ?`).run(...values, id);
+      } finally {
+        db.close();
+      }
+    },
+
+    latest,
+
+    isActive(agentId) {
+      const row = latest<{ status: string }>(agentId);
+      return !!row && activeStatuses.includes(row.status);
+    },
+
+    activeAgentIds() {
+      const db = openDb(true);
+      try {
+        const rows = db.prepare(
+          `SELECT DISTINCT agent_id FROM ${table} WHERE status IN (${activePlaceholders})`,
+        ).all(...activeStatuses) as { agent_id: string }[];
+        return new Set(rows.map((r) => r.agent_id));
+      } finally {
+        db.close();
+      }
+    },
+
+    markInterrupted() {
+      const db = openDb(false);
+      try {
+        const now = Date.now();
+        const info = db.prepare(
+          `UPDATE ${table}
+              SET error = COALESCE(error, 'Rev4a restarted while this step was running: ' || status),
+                  status = 'interrupted', updated_at = ?, finished_at = ?
+            WHERE status IN (${activePlaceholders})`,
+        ).run(now, now, ...activeStatuses);
+        return info.changes;
+      } finally {
+        db.close();
+      }
+    },
+
+    prune(keepPerAgent) {
+      const db = openDb(false);
+      try {
+        const info = db.prepare(
+          `DELETE FROM ${table} WHERE id IN (
+             SELECT id FROM (
+               SELECT id, ROW_NUMBER() OVER (PARTITION BY agent_id ORDER BY id DESC) AS rn FROM ${table}
+             ) WHERE rn > ?
+           )`,
+        ).run(keepPerAgent);
+        return info.changes;
+      } finally {
+        db.close();
+      }
+    },
+  };
+}

package/lib/agent-jobs-maintenance.ts

@@ -0,0 +1,34 @@
+/**
+ * Retention for the lifecycle job tables (`agent_upgrades`, `agent_recreates`,
+ * `agent_restores`, `agent_edits`). They record every update, recreate, restore and edit
+ * an agent has been through, and nothing pruned them: the rows grew for the life of the
+ * installation while the panel only ever reads the latest one of each agent. Each table
+ * keeps the newest `KEEP_PER_AGENT` rows per agent; the rest is history.
+ *
+ * Best-effort: a failure is logged and does not stop the others or the startup.
+ */
+import { pruneUpdates } from '@/lib/agent-update-state';
+import { pruneRecreates } from '@/lib/agent-recreate-state';
+import { pruneRestores } from '@/lib/agent-restore-state';
+import { pruneEdits } from '@/lib/agent-edit-state';
+
+/** Rows kept per agent, per table. Enough to see the recent history of an agent. */
+const KEEP_PER_AGENT = 20;
+
+export function pruneLifecycleRows(keepPerAgent: number = KEEP_PER_AGENT): { table: string; removed: number }[] {
+  const prunes: [string, (keep: number) => number][] = [
+    ['agent_upgrades', pruneUpdates],
+    ['agent_recreates', pruneRecreates],
+    ['agent_restores', pruneRestores],
+    ['agent_edits', pruneEdits],
+  ];
+  const result: { table: string; removed: number }[] = [];
+  for (const [table, prune] of prunes) {
+    try {
+      result.push({ table, removed: prune(keepPerAgent) });
+    } catch (e) {
+      console.warn(`[rev4a] could not prune ${table}: ${(e as Error).message}`);
+    }
+  }
+  return result;
+}

package/lib/agent-recreate-state.ts

@@ -3,8 +3,9 @@
  *
  * Kept apart from lib/agent-recreate.ts so busy checks (lib/agent-busy.ts, the provider
  * sync) can ask which agents are being recreated without importing the recreate action.
+ * The machinery is lib/agent-job-state.ts; this file holds the table's types and names.
  */
-import { openDb } from '@/lib/db';
+import { createJobState } from '@/lib/agent-job-state';
 
 export type RecreateStatus = 'backing_up' | 'recreating' | 'done' | 'failed' | 'interrupted';
 
@@ -25,84 +26,42 @@ export interface AgentRecreateRow {
 
 const FINAL: readonly RecreateStatus[] = ['done', 'failed', 'interrupted'];
 
-export function insertRecreate(agentId: string, image: string): number {
-  const db = openDb(false);
-  try {
-    const now = Date.now();
-    const info = db.prepare(
-      `INSERT INTO agent_recreates (agent_id, status, image, started_at, updated_at)
-       VALUES (?, 'backing_up', ?, ?, ?)`,
-    ).run(agentId, image, now, now);
-    return Number(info.lastInsertRowid);
-  } finally {
-    db.close();
-  }
-}
+const state = createJobState({
+  table: 'agent_recreates',
+  initialStatus: 'backing_up',
+  activeStatuses: ACTIVE_RECREATE_STATUSES,
+  finalStatuses: FINAL,
+  insertColumns: ['image'],
+  writableColumns: ['backup_file'],
+});
 
 type Writable = Partial<Pick<AgentRecreateRow, 'status' | 'backup_file' | 'error'>>;
 
+export function insertRecreate(agentId: string, image: string): number {
+  return state.insert(agentId, image);
+}
+
 export function updateRecreateRow(id: number, fields: Writable): void {
-  const entries = Object.entries(fields).filter(([, v]) => v !== undefined);
-  const now = Date.now();
-  const sets = [...entries.map(([k]) => `${k} = ?`), 'updated_at = ?'];
-  const values: unknown[] = [...entries.map(([, v]) => v), now];
-  if (fields.status && FINAL.includes(fields.status)) {
-    sets.push('finished_at = ?');
-    values.push(now);
-  } else if (fields.status) {
-    sets.push('finished_at = NULL');
-  }
-  const db = openDb(false);
-  try {
-    db.prepare(`UPDATE agent_recreates SET ${sets.join(', ')} WHERE id = ?`).run(...values, id);
-  } finally {
-    db.close();
-  }
+  state.update(id, fields);
 }
 
 export function latestRecreate(agentId: string): AgentRecreateRow | null {
-  const db = openDb(true);
-  try {
-    return (db.prepare('SELECT * FROM agent_recreates WHERE agent_id = ? ORDER BY id DESC LIMIT 1').get(agentId) as AgentRecreateRow | undefined) ?? null;
-  } finally {
-    db.close();
-  }
+  return state.latest<AgentRecreateRow>(agentId);
 }
 
 export function isRecreateActive(agentId: string): boolean {
-  const row = latestRecreate(agentId);
-  return !!row && ACTIVE_RECREATE_STATUSES.includes(row.status);
+  return state.isActive(agentId);
 }
 
-/** AGENT_IDs with a recreate in an active status. */
 export function activeRecreateAgentIds(): Set<string> {
-  const db = openDb(true);
-  try {
-    const placeholders = ACTIVE_RECREATE_STATUSES.map(() => '?').join(', ');
-    const rows = db.prepare(`SELECT DISTINCT agent_id FROM agent_recreates WHERE status IN (${placeholders})`).all(...ACTIVE_RECREATE_STATUSES) as { agent_id: string }[];
-    return new Set(rows.map((r) => r.agent_id));
-  } finally {
-    db.close();
-  }
+  return state.activeAgentIds();
 }
 
-/**
- * At startup no recreate job can be running: any row still active was cut off by the
- * restart. It becomes `interrupted`, keeping the step it was in.
- */
 export function markInterruptedRecreates(): number {
-  const db = openDb(false);
-  try {
-    const placeholders = ACTIVE_RECREATE_STATUSES.map(() => '?').join(', ');
-    const now = Date.now();
-    const info = db.prepare(
-      `UPDATE agent_recreates
-         SET error = COALESCE(error, 'Rev4a restarted while this step was running: ' || status),
-             status = 'interrupted', updated_at = ?, finished_at = ?
-       WHERE status IN (${placeholders})`,
-    ).run(now, now, ...ACTIVE_RECREATE_STATUSES);
-    return info.changes;
-  } finally {
-    db.close();
-  }
+  return state.markInterrupted();
+}
+
+/** Keep the newest `keepPerAgent` recreates of each agent; the rest is history. */
+export function pruneRecreates(keepPerAgent: number): number {
+  return state.prune(keepPerAgent);
 }