@flame0510/project-aether 1.5.0 → 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/app/api/update-check/route.ts

@@ -68,45 +68,56 @@ export async function GET(request: Request): Promise<NextResponse> {
     }
   }
 
-  return NextResponse.json({ installed, latest, updateAvailable, package: getPackageInfo().name });
+  return NextResponse.json({ installed, latest, updateAvailable, package: getPackageInfo().name, log: 'update.log' });
 }
 
 /**
  * POST /api/update-check
  *
- * Spawns rev4a update as a detached background process.
- * rev4a update installs the latest version and writes .restart-flag,
- * which rev4a serve detects and exits with code 42, then auto-restarts
- * with the newly installed binary. No systemd required.
+ * Spawns `rev4a update` as a detached background process: it installs the latest
+ * version, writes `.restart-flag` and lets `rev4a serve` restart the child (`rev4a
+ * _run`) with the new binary. Nothing here has to restart anything — the update kills
+ * this very process on its way in (`fuser -k <port>/tcp`), so any callback meant to run
+ * after it is dead code; the CLI's own flag is the only mechanism that has to work.
+ *
+ * The child's output goes to `update.log` in the data directory: since the update
+ * restarts this process mid-run, that file is the only record of what happened.
  */
 export async function POST(request: Request): Promise<NextResponse> {
   const denied = await requireAuthJWT(request);
   if (denied) return denied;
 
-  // Spawn rev4a update in background, then write restart flag directly
-  // from this process so rev4a serve detects it and restarts.
   const { spawn } = require('child_process');
   const { join } = require('path');
-  const { writeFileSync } = require('fs');
+  const { openSync, closeSync, appendFileSync } = require('fs');
 
   const dataDir = process.env.REV4A_DATA_DIR ||
     join(process.env.HOME || '/root', '.config', 'rev4a', 'data');
+  const logPath = join(dataDir, 'update.log');
+
+  let log: number | null = null;
+  try {
+    log = openSync(logPath, 'a');
+    appendFileSync(logPath, `\n[${new Date().toISOString()}] rev4a update, started from the dashboard\n`);
+  } catch {
+    // Unwritable log: run the update anyway, we just lose the record.
+  }
 
   const child = spawn('rev4a', ['update'], {
-    stdio: 'ignore',
+    stdio: log === null ? 'ignore' : ['ignore', log, log],
     detached: true,
+    cwd: dataDir,
   });
+  if (log !== null) closeSync(log);
 
-  // When rev4a update finishes, write the restart flag so rev4a serve
-  // picks it up and exits with code 42, triggering the auto-restart loop.
-  child.on('exit', () => {
-    try { writeFileSync(join(dataDir, '.restart-flag'), ''); } catch {}
+  child.on('error', (e: Error) => {
+    try { appendFileSync(logPath, `[dashboard] could not start the update: ${e.message}\n`); } catch {}
   });
-
   child.unref();
 
   return NextResponse.json({
     success: true,
-    message: 'Update started. The dashboard will restart once complete.',
+    message: 'Update started. Rev4a restarts itself once the new version is installed.',
+    log: 'update.log',
   });
 }

package/app/components/VersionBanner.tsx

@@ -1,14 +1,42 @@
 'use client';
 
+/**
+ * "Update available" banner for Rev4a itself.
+ *
+ * The update is spawned by `POST /api/update-check` and restarts the server, so this
+ * component cannot be told the outcome by the response. It records what it asked for,
+ * waits for the server to answer again, and on the next mount compares: if the
+ * installed version moved it was updated, and if the same update is still offered it
+ * did not complete (the log file says why).
+ */
 import { useEffect, useState } from 'react';
 
 interface VersionInfo {
   installed: string;
   latest: string | null;
   updateAvailable: boolean;
+  log?: string;
 }
 
 const DISMISS_KEY = 'rev4a-update-dismissed';
+/** What we asked for and from which version, so the next mount can judge the outcome. */
+const PENDING_KEY = 'rev4a-update-pending';
+
+/** How long to poll for the restart before reloading anyway. */
+const WAIT_MS = 120_000;
+
+interface Pending { target: string; from: string }
+
+function readPending(): Pending | null {
+  try {
+    const raw = sessionStorage.getItem(PENDING_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Pending;
+    return parsed && typeof parsed.target === 'string' && typeof parsed.from === 'string' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
 
 export default function VersionBanner() {
   const [info, setInfo] = useState<VersionInfo | null>(null);
@@ -18,17 +46,37 @@ export default function VersionBanner() {
   const [updateOk, setUpdateOk] = useState<string | null>(null);
 
   useEffect(() => {
+    let active = true;
     fetch('/api/update-check?check=1')
       .then((r) => r.json())
       .then((d: VersionInfo) => {
+        if (!active) return;
+        const pending = readPending();
+        // Back from an update: did the installed version actually move?
+        if (pending && d.installed !== pending.from) {
+          sessionStorage.removeItem(PENDING_KEY);
+          setUpdateOk(`Updated to v${d.installed}`);
+          setTimeout(() => { if (active) window.location.reload(); }, 2000);
+          return;
+        }
+        if (pending) {
+          sessionStorage.removeItem(PENDING_KEY);
+          setInfo(d);
+          setDismissed(false);
+          setUpdateError(
+            `The update to v${pending.target} did not complete: Rev4a is still on v${d.installed}.`
+            + ` See ${d.log ?? 'update.log'} in the Rev4a data directory.`,
+          );
+          return;
+        }
         if (d.updateAvailable) {
           setInfo(d);
           const saved = localStorage.getItem(DISMISS_KEY);
-          if (saved === d.latest) setDismissed(true);
-          else setDismissed(false);
+          setDismissed(saved === d.latest);
         }
       })
       .catch(() => {});
+    return () => { active = false; };
   }, []);
 
   function handleDismiss() {
@@ -39,6 +87,7 @@ export default function VersionBanner() {
   }
 
   async function handleUpdate() {
+    if (!info) return;
     setUpdating(true);
     setUpdateError(null);
     setUpdateOk(null);
@@ -49,21 +98,37 @@ export default function VersionBanner() {
         headers: { 'Content-Type': 'application/json' },
       });
       const data = await res.json();
-      if (data.success) {
-        setUpdateOk('Update started. Restarting\u2026');
-        localStorage.removeItem(DISMISS_KEY);
-        setTimeout(function() { window.location.reload(); }, 5000);
-      } else {
+      if (!data.success) {
         setUpdateError(data.error || 'Update failed');
         setUpdating(false);
+        return;
       }
+      sessionStorage.setItem(PENDING_KEY, JSON.stringify({ target: info.latest ?? '', from: info.installed }));
+      localStorage.removeItem(DISMISS_KEY);
+      setUpdateOk('Update started. Rev4a is restarting…');
+      // The server goes down and comes back on the new version: wait for its answer,
+      // then reload. A timeout reloads too — the next mount reports the outcome.
+      const deadline = Date.now() + WAIT_MS;
+      const poll = async () => {
+        if (Date.now() > deadline) { window.location.reload(); return; }
+        try {
+          const r = await fetch('/api/update-check', { cache: 'no-store' });
+          const d = (await r.json()) as VersionInfo;
+          if (d.installed !== info.installed) { window.location.reload(); return; }
+        } catch { /* the server is down for the update: expected */ }
+        setTimeout(poll, 3000);
+      };
+      setTimeout(poll, 3000);
     } catch (err) {
       setUpdateError(err instanceof Error ? err.message : 'Network error');
       setUpdating(false);
     }
   }
 
-  if (!info || dismissed) return null;
+  // The result states stand on their own (there may be no `info` when the update just
+  // succeeded); the "available" state needs the version info and no dismissal.
+  const show = Boolean(updateOk) || Boolean(updateError) || Boolean(info?.updateAvailable && !dismissed);
+  if (!show) return null;
 
   return (
     <div className="update-banner">
@@ -73,25 +138,25 @@ export default function VersionBanner() {
             <span className="update-banner__ok">{updateOk}</span>
           ) : updateError ? (
             <span className="update-banner__err">{updateError}</span>
-          ) : (
+          ) : info ? (
             <>
               <span className="update-banner__label">Update available</span>
               <span className="update-banner__sep">&mdash;</span>
               <span className="update-banner__version">v{info.latest}</span>
               <span className="update-banner__sep">(installed: v{info.installed})</span>
             </>
-          )}
+          ) : null}
         </span>
 
         {!updateOk && (
           <div className="update-banner__actions">
             {updateError ? (
               <button className="ui-btn ui-btn--primary ui-btn--sm" onClick={handleUpdate} disabled={updating}>
-                {updating ? 'Updating\u2026' : 'Retry'}
+                {updating ? 'Updating…' : 'Retry'}
               </button>
             ) : (
               <button className="ui-btn ui-btn--primary ui-btn--sm" onClick={handleUpdate} disabled={updating}>
-                {updating ? 'Updating\u2026' : 'Update now'}
+                {updating ? 'Updating…' : 'Update now'}
               </button>
             )}
             <button className="ui-btn ui-btn--ghost ui-btn--sm" onClick={handleDismiss}>

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": [
@@ -2559,14 +2562,28 @@ Installed version against the latest published one.
 **Query params:** `check=1` queries the registry; without it the answer comes
 from local state only.
 
-**Response:** `{ "installed": "1.1.15", "latest": "1.1.16", "updateAvailable": true, "package": "@flame0510/project-aether" }`
+**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.
 
 ### `POST /api/update-check`
-Run `rev4a update` as a detached background process. The dashboard restarts
-itself as part of the update, so the connection drops.
+Run `rev4a update` as a detached background process. Nothing here restarts anything:
+the update kills this process on its way in (`fuser -k <port>/tcp`) and `rev4a serve`
+brings the child back on the new binary via its `.restart-flag`, so the connection
+drops and the page has to wait for the server to answer again.
+
+The child's output goes to `update.log` in the data directory — the update restarts
+the process that spawned it, so that file is the only record of what happened.
 
 **Auth:** browser cookie or bearer token
 
+**Response:** `{ "success": true, "message": "...", "log": "update.log" }`
+
+The banner records what it asked for, polls `/api/version` until the installed version
+moves (or two minutes pass), reloads, and on the next mount either confirms
+"Updated to vX" or reports that the update did not complete and points at the log.
+
 ### `GET /api/alerts/smoke`
 Send a test alert, to verify the Telegram alerting path end to end.
 

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