@flame0510/project-aether 1.5.1 → 1.5.2

package/app/agents/ChannelManager.tsx

@@ -52,6 +52,7 @@ export default function ChannelManager({ agentId, displayName, open, onClose }:
 
   const [pending, setPending] = useState<PendingPairing[]>([]);
   const [approved, setApproved] = useState<ApprovedPairing[]>([]);
+  const [pairingError, setPairingError] = useState<string | null>(null);
   const pollRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const pairingsAbortRef = useRef<AbortController | null>(null);
   const channelsAbortRef = useRef<AbortController | null>(null);
@@ -85,6 +86,7 @@ export default function ChannelManager({ agentId, displayName, open, onClose }:
         const data = await res.json();
         setPending(data.pending ?? []);
         setApproved(data.approved ?? []);
+        setPairingError(data.error ?? null);
       }
     } catch (e: any) {
       if (e?.name !== 'AbortError') { /* ignore aborted */ }
@@ -288,6 +290,7 @@ export default function ChannelManager({ agentId, displayName, open, onClose }:
           restarting={restarting}
           pending={pending}
           approved={approved}
+          pairingError={pairingError}
           approvingCode={approvingCode}
           revokingId={revokingId}
           onConnect={handleTelegramConnect}
@@ -305,7 +308,7 @@ export default function ChannelManager({ agentId, displayName, open, onClose }:
 
 function TelegramTab({
   tg, tgToken, setTgToken, loading, disconnecting, pairingsLoading, restarting,
-  pending, approved, approvingCode, revokingId,
+  pending, approved, pairingError, approvingCode, revokingId,
   onConnect, onDisconnect, onRestart, onApprove, onRevoke,
 }: {
   tg: TelegramChannel | null;
@@ -317,6 +320,7 @@ function TelegramTab({
   restarting: boolean;
   pending: PendingPairing[];
   approved: ApprovedPairing[];
+  pairingError: string | null;
   approvingCode: string | null;
   revokingId: string | null;
   onConnect: () => void;
@@ -343,6 +347,7 @@ function TelegramTab({
         <PairingSection
           pending={pending}
           approved={approved}
+          pairingError={pairingError}
           pairingsLoading={pairingsLoading}
           approvingCode={approvingCode}
           revokingId={revokingId}
@@ -389,11 +394,12 @@ function TelegramTab({
 // ── Pairing Section ──────────────────────────
 
 function PairingSection({
-  pending, approved, pairingsLoading, approvingCode, revokingId,
+  pending, approved, pairingError, pairingsLoading, approvingCode, revokingId,
   onApprove, onRevoke,
 }: {
   pending: PendingPairing[];
   approved: ApprovedPairing[];
+  pairingError: string | null;
   pairingsLoading: boolean;
   approvingCode: string | null;
   revokingId: string | null;
@@ -462,9 +468,15 @@ function PairingSection({
           )}
 
           {approved.length === 0 && (
-            <div style={{ fontSize: 10, color: 'var(--text-dim)' }}>
-              No approved senders
-            </div>
+            pairingError ? (
+              <div style={{ fontSize: 10, color: 'var(--red, #ef4444)' }}>
+                {pairingError}
+              </div>
+            ) : (
+              <div style={{ fontSize: 10, color: 'var(--text-dim)' }}>
+                No approved senders
+              </div>
+            )
           )}
         </>
       )}

package/app/agents/PageClient.tsx

@@ -343,9 +343,19 @@ export default function AgentsPageClient() {
       const res = await fetch('/api/agents/devices-summary');
       if (!res.ok || seq !== dvSummarySeq.current) return;
       const payload = await res.json();
-      const byId: Record<string, { pending: number }> = {};
-      for (const row of payload.agents ?? []) byId[row.agentId] = { pending: row.pending ?? 0 };
-      setDvSummary(byId);
+      // A row whose read failed carries `error: true` and no count: keep the previous
+      // value instead of writing zero, which would hide a request that is really waiting.
+      setDvSummary((prev) => {
+        const next: Record<string, { pending: number }> = {};
+        for (const row of payload.agents ?? []) {
+          if (row.error === true) {
+            if (prev[row.agentId]) next[row.agentId] = prev[row.agentId];
+            continue;
+          }
+          next[row.agentId] = { pending: row.pending ?? 0 };
+        }
+        return next;
+      });
     } catch { /* badges are optional */ }
   }, []);
 

package/app/api/agents/download-image/route.ts

@@ -32,6 +32,14 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
   }
   const version = (body?.version as string | undefined) ?? (await defaultDownloadVersion());
 
+  // Checked again here, next to the start: the first check and this one are separated by
+  // awaits, so two requests can pass it together. The loser of the race is refused inside
+  // downloadAgentImage, and that rejection would be swallowed by the catch below — the
+  // route would answer 202 for a download it never started.
+  if (getIsDownloading()) {
+    return NextResponse.json({ error: 'A download is already in progress' }, { status: 409 });
+  }
+
   // Start download in background — fire and forget
   downloadAgentImage({ version }).catch((e: unknown) => {
     console.error(`[download-image] OpenClaw ${version}:`, (e as Error).message);

package/bin/rev4a.js

@@ -428,7 +428,9 @@ function seedAgentToken() {
 function build() {
   log('BUILD', 'Building Next.js app…');
   try {
-    execSync('npx next build', { stdio: 'inherit', cwd: ROOT, timeout: 120_000 });
+    // Generous on purpose: a build is the slowest step of an install, and killing it
+    // because it passed two minutes takes the server down over slowness alone.
+    execSync('npx next build', { stdio: 'inherit', cwd: ROOT, timeout: 30 * 60_000 });
     log('BUILD', 'Build complete');
   } catch (err) {
     log('BUILD', `Build failed: ${err.message}`);
@@ -754,13 +756,14 @@ if (cmd === 'update') {
       console.log('Detected git repo — pulling and building…');
       execSync(`cd ${root} && git pull && npm install && npm run build`, {
         stdio: 'inherit',
-        timeout: 120_000,
+        // npm install + a full build: minutes, not two.
+        timeout: 30 * 60_000,
       });
     } else {
       console.log('Using npm global install…');
       execSync(`npm install -g ${PKG_NAME}@latest`, {
         stdio: 'inherit',
-        timeout: 120_000,
+        timeout: 20 * 60_000,
       });
       // Wipe old build so rev4a serve rebuilds with the new version
       const nextDir = join(ROOT, '.next');

package/daemon.js

@@ -28,7 +28,7 @@ const MODEL_PRICING = {
   'default':          { in: 3.00,  out: 15.00 },
 };
 
-// Alias diretti per modelli che non matchano per substring
+// Direct aliases for models that do not match by substring
 const MODEL_ALIASES = {
   'cheap': 'flash',
   'fast':  'claude-sonnet-4',
@@ -69,7 +69,7 @@ try {
 process.on('uncaughtException', (err) => {
   console.error(`[UNCAUGHT] ${err.message}\n${err.stack}`);
   console.error('Daemon will attempt restart via watchdog cron');
-  // NON uscire — il watchdog lo vede da healthcheck
+  // Do NOT exit — the watchdog reads this from the healthcheck
 });
 
 db.exec(`
@@ -749,7 +749,7 @@ function pollSessions() {
     }
   }
 
-  // WAL checkpoint FULL ogni 10 poll
+  // FULL WAL checkpoint every 10 polls
   pollCount = (pollCount || 0) + 1;
   if (pollCount % 10 === 0) {
     db.pragma('wal_checkpoint(FULL)');

package/docs/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # Rev4a Architecture — Design & Vision
 
 > **Status:** Active — `main` branch
-> **Last updated:** 2026-09-15
+> **Last updated:** 2026-09-22
 > **Goal:** Transform Rev4a from a monitoring dashboard into a central orchestrator for a distributed multi-container agency.
 
 ---
@@ -207,8 +207,17 @@ The central container, running the Next.js dashboard + orchestration API.
   table (`lib/agent-restore-state.ts`): the archive replaces the volume (stop, clear,
   extract, start), up to 30 minutes. Same 202-and-background shape as a recreate, and the
   same guarantees — a reload or a Rev4a restart does not lose the job, a second restore
-  is refused, an interrupted one starts the container again. The extract has no
-  percentage (it is a single `tar xzf`); the panel and the agent card show `RESTORING`.
+  is refused, and an interrupted one is **run again from the same archive** at startup: a
+  half-written volume must never be presented as a restore, and the archive was already
+  checked before the job started (when it is gone the container is started on whatever the
+  volume holds, and the row says so). The extract has no percentage (it is a single
+  `tar xzf`); the panel and the agent card show `RESTORING`.
+- **The four job tables share one implementation**: `lib/agent-job-state.ts` builds the
+  insert/update/latest/active/`markInterrupted` machinery for `agent_upgrades`,
+  `agent_recreates`, `agent_restores` and `agent_edits`; each `lib/agent-*-state.ts` keeps
+  only its table's types and function names. They were four near-identical copies that had
+  started to drift. At startup `lib/agent-jobs-maintenance.ts` prunes each table to the
+  newest 20 rows per agent — the panel reads the latest row only, so the rest is history.
 - **Browser access** to an agent's Control UI goes through `lib/agent-devices.ts`:
   `openclaw devices list | approve | reject | rename | remove` and
   `openclaw dashboard --json`, run inside the container with the async `dockerExec`.
@@ -279,6 +288,19 @@ the rules for anything you touch, not as a description of the whole tree:
 `promisify(exec)` silently ignores an `input` option: the process starts, stdin
 is never written, and the command hangs with no error to point at.
 
+- **The process model and self-update.** `rev4a serve` (the systemd unit's process) is a
+  supervisor: it spawns `rev4a _run <port>`, which in turn runs Next, the daemon and the
+  terminal WebSocket. `rev4a update` installs the new version, then `rev4a restart` writes
+  `.restart-flag` in the data directory; `_run` sees it, stops its children, waits for the
+  port to come free and exits with code **42**, and the supervisor relaunches `_run` on the
+  new code — so the supervisor itself never goes down (the unit's `NRestarts` stays 0).
+  The dashboard's **Update now** is only a detached `rev4a update` (`POST
+  /api/update-check`): it must not try to restart anything itself, because the update
+  stops the very process that spawned it, and the CLI's own flag is the mechanism that
+  matters. Its output goes to `update.log` in the data directory, since nothing else can
+  report the outcome: the banner records what it asked for, waits for the installed
+  version to change and only then reloads (see `VersionBanner`).
+
 ### 3.2 Agent Container Template (`openclaw-agent-base`)
 
 Docker image for every agent container.

package/docs/FRONTEND-ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Rev4a Frontend Architecture
 
-> **Last updated:** 2026-09-15
+> **Last updated:** 2026-09-22
 
 ## Layering
 
@@ -46,8 +46,9 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `BackupSection` | inline in `app/agents/PageClient.tsx` | BACKUP section of the agent detail panel, on the cold backup and the restore. **Backup Now** starts `POST /api/agents/[id]/cold-backup`; while the job runs a banner shows the file and its live percent with **Cancel** (`DELETE /cold-backup`). **Restore** (after a confirm) starts `POST /restore` and a banner shows `Restoring <file>…` (no percent: the extract is a single `tar xzf`, and there is no Cancel). Both sections poll their `GET` every 2 s while running, and on mount pick up a job that is already running — a backup lives in a Docker helper, a restore in `agent_restores`, so reloading the page or navigating away never loses them nor allows a second one (the server answers 409 anyway). Delete per row; all actions disabled while one runs; keyed busy state `{ kind, file }` so only the row in action shows the spinner. On the agent list, an activity Badge (fed by `/api/agents/activity-summary`, polled at 2 s only while something runs, otherwise riding the 15 s list poll) reads `BACKUP nn%`, `RESTORING`, `RECREATING`, `EDITING` or `UPDATING`. |
 | `RecreateSection` | inline in `app/agents/PageClient.tsx` | RECREATE section of the agent detail panel. **Recreate Container** starts `POST /api/agents/[id]/recreate` (202) after a confirm; a banner then shows the phase — *Backing up … nn%* while the cold backup runs, *Recreating container…* while the container is rebuilt and the gateway starts. The section polls `GET /recreate` every 2 s, and on mount picks up a recreate that is already running, so a reload or navigation never loses it; it refetches the agent once the job reports `done`. |
 | `ImageDownloadBanner` | `app/agents/ImageDownloadBanner.tsx` | Agent image banner on the Agents page. Polls `/api/agents/image-status` every 2 s; offers **Download Image** when no supported version is downloaded, **Download <version>** when the registry publishes a newer one, and shows the download in progress and its completion. Downloading changes no agent. |
+| `VersionBanner` | `app/components/VersionBanner.tsx` | "Update available" banner for Rev4a itself, when `GET /api/update-check?check=1` reports a newer published version (dismissable per version, remembered in `localStorage`). **Update now** starts `POST /api/update-check`; because that update restarts the server, the banner cannot be told the outcome by the response: it records what it asked for in `sessionStorage`, polls `/api/update-check` until the installed version moves (two minutes at most) and reloads, then on the next mount either confirms "Updated to vX" or reports that the update did not complete and points at `update.log` (the update's own output). It never reloads blindly onto the same version. |
 | `BrowserAccessSection` / `OpenControlUiButton` | `app/agents/BrowserAccessSection.tsx` | Browser access to one agent's Control UI, in its detail panel: requests waiting for approval (Approve / Reject) and approved browsers (Rename / Revoke), refreshed every 5 s while mounted. A successful approve, reject, rename or revoke updates the list at once, since the refresh behind it runs the OpenClaw CLI and takes seconds; a read started before the mutation is discarded. On agents that require approval, "Invite link" fetches `/api/agents/[id]/invite-link` and shows the link in a read-only field with Copy, which uses the Clipboard API in a secure context and the field's selection over plain HTTP, plus a warning when the link uses localhost. `OpenControlUiButton` opens `/api/agents/[id]/open-control-ui` in a new tab inside the click; that route redirects to a one-time link that pairs the browser with no approval, or to the plain token link when none can be issued. Used on the agent cards and in the panel. |
-| `ChannelManager` / `ChannelSection` | `app/agents/ChannelManager.tsx`, `ChannelSection` inline in `app/agents/PageClient.tsx` | Telegram, in the agent detail panel (`ChannelSection` is the card that opens the modal; the modal title is the agent's display name). Reads `GET /channels`; lists pending pairing requests with **Approve** (`POST /channels/pairing`) and approved senders with **Revoke** after a confirm (`DELETE /channels/pairing?senderId=`). Pending comes from `openclaw pairing list`, approved from OpenClaw's pairing store (`lib/channelManager.ts`). Polls pairings every 5 s while open; one keyed busy state per action. |
+| `ChannelManager` / `ChannelSection` | `app/agents/ChannelManager.tsx`, `ChannelSection` inline in `app/agents/PageClient.tsx` | Telegram, in the agent detail panel (`ChannelSection` is the card that opens the modal; the modal title is the agent's display name). Reads `GET /channels`; lists pending pairing requests with **Approve** (`POST /channels/pairing`) and approved senders with **Revoke** after a confirm (`DELETE /channels/pairing?senderId=`). Pending comes from `openclaw pairing list`, approved from OpenClaw's pairing store (`lib/channelManager.ts`). When that store cannot be read the panel shows the reason instead of "No approved senders" (`PairingState.error`), so an empty list is never a guess. Polls pairings every 5 s while open; one keyed busy state per action. |
 | `EditAgentModal` / `EditBanner` | `app/agents/PageClient.tsx` | Rename/ports editing. The modal has **Display Name** and **Host Port** (same input and validation messages as the create wizard, from `lib/agent-ports.ts`), sends `PATCH /api/agents/[id]` and closes on `202`; `EditBanner` (top of the agent detail) polls `GET /api/agents/[id]` every 2 s while an edit is `rebuilding`, resumes on mount, and refetches the agent once it finishes, so a reload or a navigation shows the running edit instead of allowing a second (the server answers 409). No backup is taken: the volume is untouched. The port range is validated **as it is typed**: the modal fetches `GET /api/agents/ports` when it opens (the same set the create form uses, every container, running or stopped) and excludes the agent's own block, so an occupied range shows the API's message inline and the Save button stays disabled — the create wizard does the same with the same endpoint. |
 | `ModelSection` | `app/agents/ModelSection.tsx` | Primary model and fallbacks for one agent, in its detail panel. Explicit save, no restart. The model is a property of the agent, not of the gateway. Tags models the catalogue marks `deprecated`. |
 | `ModelsProvider` / `useModels` | `app/lib/models-context.tsx` | The client's single model list, from `/api/models`. Whatever changes what is offered calls `refresh()`: the Gateway page after a toggle, a key save or removal, or a sync, and the first-run wizard after saving keys. Everything else only reads, PulseChat included. |

package/docs/REV4A.md

@@ -201,6 +201,23 @@ If the daemon never answers, `serve` starts anyway, skips the network and image
 checks, and says so in the log. The startup sync then reaches no agent, and logs
 that too; run Sync All Agents once Docker is up.
 
+### Memory (a host that runs several agents)
+
+`rev4a update` installs the new version and the server rebuilds Next before it comes
+back (`rev4a` wipes `.next`, so the build always runs). That build is the memory peak
+of the whole installation: with several agent Gateways resident (roughly 0.5-0.8 GB
+each) a host with no swap can hit the kernel OOM killer during the update — it killed
+`next-server` on a 7.7 GB VPS, which then stayed unreachable until a reboot.
+
+Give such a host swap (4-8 GB is enough for the build) and a conservative
+`vm.swappiness`:
+
+```bash
+fallocate -l 4G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile
+echo '/swapfile none swap sw 0 0' >> /etc/fstab
+echo 'vm.swappiness=10' > /etc/sysctl.d/99-rev4a-swap.conf
+```
+
 ### Systemd environment override
 
 File: `/etc/systemd/system/rev4a-next.service` (EnvironmentFile)

package/docs/dev/API-REFERENCE.md

@@ -1339,7 +1339,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": [

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;
+}