@flame0510/project-aether 1.3.0 → 1.4.1

package/lib/agent-setup.ts

@@ -8,9 +8,9 @@
  * one-file change.
  */
 
-import { execSync } from 'child_process';
 import * as fs from 'fs';
 import { SHARED_SKILLS_DIR, REV4A_RULES_DIR } from '@/lib/rev4a-paths';
+import { dockerExec, dockerExecWithInput } from '@/lib/docker-exec';
 
 // ── Volumes ──────────────────────────────────────────────────────────────────
 
@@ -103,27 +103,76 @@ const GUARANTEED_CONFIG_PATCHES: object[] = [
   },
 ];
 
+const CONFIG_PATCH_TIMEOUT_MS = 15_000;
+
+/** Exactly `["*"]`: the allow-all list earlier Rev4a versions wrote. */
+function isWildcardOnly(value: unknown): boolean {
+  return Array.isArray(value) && value.length === 1 && value[0] === '*';
+}
+
+/**
+ * `gateway.controlUi` with Rev4a's browser-origin policy applied.
+ *
+ * The Host-header fallback accepts a Control UI page served from the host the
+ * browser connected to — whatever address the agent is reached on — and refuses
+ * pages from any other origin. Without it, a public IP is refused; loopback and
+ * private hosts are accepted either way. An `allowedOrigins: ["*"]` list, which
+ * accepts every origin, is dropped; any other list an operator set is kept. The
+ * retired `dangerouslyDisableDeviceAuth` is dropped too.
+ */
+export function withControlUiPolicy(current: unknown): Record<string, unknown> {
+  const next: Record<string, unknown> = {
+    ...(current && typeof current === 'object' ? (current as Record<string, unknown>) : {}),
+  };
+  next.dangerouslyAllowHostHeaderOriginFallback = true;
+  delete next.dangerouslyDisableDeviceAuth;
+  if (isWildcardOnly(next.allowedOrigins)) delete next.allowedOrigins;
+  return next;
+}
+
+async function patchConfig(containerName: string, patch: object): Promise<void> {
+  await dockerExecWithInput(containerName, ['openclaw', 'config', 'patch', '--stdin'], JSON.stringify(patch), {
+    timeoutMs: CONFIG_PATCH_TIMEOUT_MS,
+  });
+}
+
+/**
+ * Apply the origin policy to a running container through merge patches.
+ *
+ * The fallback and the removal of `["*"]` go in one patch, so the Gateway reloads
+ * both together. The retired `dangerouslyDisableDeviceAuth` goes in a second patch:
+ * if the Gateway refuses it, the policy the Control UI needs is already in place.
+ */
+async function applyControlUiPolicy(containerName: string): Promise<void> {
+  const raw = await dockerExec(containerName, ['cat', '/root/.openclaw/openclaw.json'], { timeoutMs: CONFIG_PATCH_TIMEOUT_MS });
+  const current = (JSON.parse(raw) as { gateway?: { controlUi?: Record<string, unknown> } })?.gateway?.controlUi ?? {};
+
+  const policy: Record<string, unknown> = { dangerouslyAllowHostHeaderOriginFallback: true };
+  if (isWildcardOnly(current.allowedOrigins)) policy.allowedOrigins = null;
+  await patchConfig(containerName, { gateway: { controlUi: policy } });
+
+  if ('dangerouslyDisableDeviceAuth' in current) {
+    await patchConfig(containerName, { gateway: { controlUi: { dangerouslyDisableDeviceAuth: null } } });
+  }
+}
+
 /**
- * Apply all guaranteed config patches to a running container.
+ * Apply all guaranteed config patches to a running container, then the origin policy.
  * Uses `openclaw config patch --stdin` (deep-merge) so existing
- * user customizations are never overwritten.
+ * user customizations are never overwritten. Best-effort: a failed patch is logged
+ * and the others still run.
  */
-export function applyRuntimeConfig(containerName: string): void {
+export async function applyRuntimeConfig(containerName: string): Promise<void> {
   for (const patch of GUARANTEED_CONFIG_PATCHES) {
-    const json = JSON.stringify(patch);
     try {
-      execSync(
-        `docker exec -i ${escapeShell(containerName)} sh -c 'openclaw config patch --stdin'`,
-        { timeout: 15_000, stdio: 'pipe', input: json },
-      );
-    } catch {
-      // config patch is best-effort — the image may already have it
+      await patchConfig(containerName, patch);
+    } catch (e) {
+      console.warn(`[agent-setup] config patch failed on ${containerName}:`, (e as Error).message);
     }
   }
-}
-
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-export function escapeShell(value: string): string {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
+  try {
+    await applyControlUiPolicy(containerName);
+  } catch (e) {
+    console.warn(`[agent-setup] Control UI origin policy not applied on ${containerName}:`, (e as Error).message);
+  }
 }

package/lib/agent-update-state.ts

@@ -0,0 +1,122 @@
+/**
+ * Persisted state of agent updates: the `agent_upgrades` table (lib/db-bootstrap.mjs).
+ *
+ * Kept apart from lib/agent-update.ts so the provider sync can ask which agents are
+ * being updated without importing the update action, which imports the sync.
+ */
+import { openDb } from '@/lib/db';
+
+export type UpdateStatus =
+  | 'pending'
+  | 'backing_up'
+  | 'migrating'
+  | 'verifying'
+  | 'done'
+  | 'failed'
+  | 'interrupted'
+  | 'rolling_back'
+  | 'rolled_back'
+  | 'rollback_failed';
+
+/** Statuses during which the agent must not be touched by anything else. */
+export const ACTIVE_STATUSES: readonly UpdateStatus[] = ['pending', 'backing_up', 'migrating', 'verifying', 'rolling_back'];
+
+export interface AgentUpdateRow {
+  id: number;
+  agent_id: string;
+  status: UpdateStatus;
+  from_version: string | null;
+  to_version: string;
+  backup_file: string | null;
+  baseline_json: string | null;
+  verify_json: string | null;
+  error: string | null;
+  started_at: number;
+  updated_at: number;
+  finished_at: number | null;
+}
+
+const FINAL: readonly UpdateStatus[] = ['done', 'failed', 'interrupted', 'rolled_back', 'rollback_failed'];
+
+export function insertUpdate(agentId: string, fromVersion: string | null, toVersion: string): number {
+  const db = openDb(false);
+  try {
+    const now = Date.now();
+    const info = db.prepare(
+      `INSERT INTO agent_upgrades (agent_id, status, from_version, to_version, started_at, updated_at)
+       VALUES (?, 'pending', ?, ?, ?, ?)`,
+    ).run(agentId, fromVersion, toVersion, now, now);
+    return Number(info.lastInsertRowid);
+  } finally {
+    db.close();
+  }
+}
+
+type Writable = Partial<Pick<AgentUpdateRow, 'status' | 'backup_file' | 'baseline_json' | 'verify_json' | 'error'>>;
+
+export function updateRow(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_upgrades SET ${sets.join(', ')} WHERE id = ?`).run(...values, id);
+  } finally {
+    db.close();
+  }
+}
+
+export function latestUpdate(agentId: string): AgentUpdateRow | null {
+  const db = openDb(true);
+  try {
+    return (db.prepare('SELECT * FROM agent_upgrades WHERE agent_id = ? ORDER BY id DESC LIMIT 1').get(agentId) as AgentUpdateRow | undefined) ?? null;
+  } finally {
+    db.close();
+  }
+}
+
+export function isUpdateActive(agentId: string): boolean {
+  const row = latestUpdate(agentId);
+  return !!row && ACTIVE_STATUSES.includes(row.status);
+}
+
+/** AGENT_IDs with an update in an active status. */
+export function activeUpdateAgentIds(): Set<string> {
+  const db = openDb(true);
+  try {
+    const placeholders = ACTIVE_STATUSES.map(() => '?').join(', ');
+    const rows = db.prepare(`SELECT DISTINCT agent_id FROM agent_upgrades WHERE status IN (${placeholders})`).all(...ACTIVE_STATUSES) as { agent_id: string }[];
+    return new Set(rows.map((r) => r.agent_id));
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * At startup, no update job can be running: any row still active was cut off by the
+ * restart. It becomes `interrupted`, keeping the step it was in, so the operator decides
+ * between Rollback and a new Update.
+ */
+export function markInterruptedUpdates(): number {
+  const db = openDb(false);
+  try {
+    const placeholders = ACTIVE_STATUSES.map(() => '?').join(', ');
+    const now = Date.now();
+    const info = db.prepare(
+      `UPDATE agent_upgrades
+         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_STATUSES);
+    return info.changes;
+  } finally {
+    db.close();
+  }
+}

package/lib/agent-update.ts

@@ -0,0 +1,456 @@
+/**
+ * The Update action: move one agent to a newer supported OpenClaw version.
+ *
+ * Each step is recorded in `agent_upgrades` before it starts:
+ *
+ *   pending     preflight: agent running, target downloaded, newer and supported,
+ *               no backup or update already running
+ *   (baseline)  transcript events per session and cron job names, read inside the agent
+ *   backing_up  cold backup `agent-<id>-preupdate-<from>-<ts>.tar.gz`; the agent stays stopped
+ *   migrating   container recreated on `openclaw-agent-base:<to>`; its entrypoint runs
+ *               `doctor --fix`; Rev4a waits for `/startupz` to report the target version,
+ *               then re-applies its own config
+ *   verifying   every session has at least as many events as before, every cron job is
+ *               still there
+ *   done | failed
+ *
+ * A version change migrates data one way: the previous version refuses the migrated
+ * database, so going back means restoring the pre-update backup on the previous image
+ * (Rollback). The job runs inside the Rev4a process; after a Rev4a restart an unfinished
+ * one is marked `interrupted` (lib/agent-update-state.ts).
+ */
+import { dockerExec, dockerExecNoFail } from '@/lib/docker-exec';
+import { isValidAgentId } from '@/lib/container';
+import { compareVersions, isSupportedVersion, localImageRef, parseOpenClawVersion } from '@/lib/agent-versions';
+import {
+  containerOpenClawVersion,
+  listLocalAgentImages,
+  localVersionExists,
+  newestLocalSupportedVersion,
+  pruneAgentImages,
+  pullAgentImage,
+  runDocker,
+} from '@/lib/agent-images';
+import { BACKUP_VOLUME, coldBackupStatus, isColdBackupRunning, startColdBackup, waitForColdBackup } from '@/lib/cold-backup';
+import { inspectAgentContainer, recreateAgentContainer, startAndVerifyContainer, type AgentContainerInspect } from '@/lib/agent-recreate';
+import { applyRuntimeConfig } from '@/lib/agent-setup';
+import { waitForGatewayReady } from '@/lib/agent-readiness';
+import { patchRev4aProvider } from '@/app/api/gateway/sync';
+import { activeUpdateAgentIds, insertUpdate, latestUpdate, markInterruptedUpdates, updateRow, type AgentUpdateRow } from '@/lib/agent-update-state';
+import { agentBusyReason } from '@/lib/agent-busy';
+
+/** A migration runs `doctor --fix` before the Gateway starts; allow for large state. */
+const MIGRATION_READY_TIMEOUT_MS = 10 * 60 * 1000;
+/** A cold backup of a 13 GB volume takes ~8 minutes; anything past this is stuck. */
+const COLD_BACKUP_WAIT_TIMEOUT_MS = 30 * 60 * 1000;
+
+export class UpdateRefusedError extends Error {}
+
+/**
+ * Counts transcript events per session, inside the agent: `.jsonl` lines on 2026.7.x,
+ * `transcript_events` rows in `openclaw-agent.sqlite` from 9.x. Keys are
+ * `<agent>/<session id>`; trajectory files are debug traces and are not counted.
+ */
+const COUNT_TRANSCRIPTS = `
+const fs = require('fs'), path = require('path');
+const out = {};
+const root = '/root/.openclaw/agents';
+for (const agent of fs.existsSync(root) ? fs.readdirSync(root) : []) {
+  const sessions = path.join(root, agent, 'sessions');
+  if (fs.existsSync(sessions)) {
+    for (const f of fs.readdirSync(sessions)) {
+      if (!f.endsWith('.jsonl') || f.endsWith('.trajectory.jsonl')) continue;
+      const n = fs.readFileSync(path.join(sessions, f), 'utf8').split('\\n').filter((l) => l.trim()).length;
+      const key = agent + '/' + f.slice(0, -'.jsonl'.length);
+      out[key] = Math.max(out[key] || 0, n);
+    }
+  }
+  const dbFile = path.join(root, agent, 'agent', 'openclaw-agent.sqlite');
+  if (fs.existsSync(dbFile)) {
+    const { DatabaseSync } = require('node:sqlite');
+    const db = new DatabaseSync(dbFile, { readOnly: true });
+    // 2026.7.x creates this database too, without the transcript table.
+    const hasEvents = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'transcript_events'").get();
+    if (hasEvents) {
+      for (const r of db.prepare('SELECT session_id, COUNT(*) AS n FROM transcript_events GROUP BY session_id').all()) {
+        const key = agent + '/' + r.session_id;
+        out[key] = Math.max(out[key] || 0, Number(r.n));
+      }
+    }
+    db.close();
+  }
+}
+process.stdout.write('REV4A-COUNTS ' + JSON.stringify(out) + '\\n');
+`;
+
+async function countTranscripts(container: string): Promise<Record<string, number>> {
+  const out = await dockerExec(container, ['node', '-e', COUNT_TRANSCRIPTS], { timeoutMs: 120_000 });
+  const line = out.split('\n').find((l) => l.startsWith('REV4A-COUNTS '));
+  if (!line) throw new Error('Could not count the transcript events');
+  return JSON.parse(line.slice('REV4A-COUNTS '.length)) as Record<string, number>;
+}
+
+const CRON_LIST = [
+  'export OPENCLAW_GATEWAY_PORT=3000',
+  'if [ -f /root/.agent-token ]; then OPENCLAW_GATEWAY_TOKEN=$(head -1 /root/.agent-token | tr -d "[:space:]"); export OPENCLAW_GATEWAY_TOKEN; fi',
+  'exec openclaw cron list --all --json',
+].join('; ');
+
+/** Names of the agent's cron jobs; null when the list cannot be read. */
+async function cronJobNames(container: string): Promise<string[] | null> {
+  const out = await dockerExecNoFail(container, ['sh', '-c', CRON_LIST], { timeoutMs: 120_000 });
+  const start = out.search(/[{[]/);
+  if (start === -1) return null;
+  try {
+    const data = JSON.parse(out.slice(start)) as unknown;
+    const jobs = Array.isArray(data) ? data : ((data as { jobs?: unknown[] })?.jobs ?? []);
+    return (jobs as { name?: string; id?: string }[]).map((j) => j.name ?? j.id ?? '').filter(Boolean).sort();
+  } catch {
+    return null;
+  }
+}
+
+async function runningVersion(container: string): Promise<string | null> {
+  const body = await dockerExecNoFail(container, ['curl', '-s', '--max-time', '3', 'http://127.0.0.1:3000/startupz'], { timeoutMs: 10_000 });
+  try {
+    return parseOpenClawVersion(String((JSON.parse(body) as { version?: unknown }).version ?? ''));
+  } catch {
+    return null;
+  }
+}
+
+interface Baseline {
+  transcripts: Record<string, number>;
+  cronJobs: string[] | null;
+}
+
+export interface Verification {
+  sessions: number;
+  /** Sessions with fewer events than before, or gone: `{ session, before, after }`. */
+  lostEvents: { session: string; before: number; after: number }[];
+  /** Cron jobs present before and missing after; null when either list could not be read. */
+  missingCronJobs: string[] | null;
+  ok: boolean;
+}
+
+export function verify(baseline: Baseline, transcripts: Record<string, number>, cronJobs: string[] | null): Verification {
+  const lostEvents = Object.entries(baseline.transcripts)
+    .filter(([session, before]) => (transcripts[session] ?? 0) < before)
+    .map(([session, before]) => ({ session, before, after: transcripts[session] ?? 0 }));
+  const missingCronJobs = baseline.cronJobs && cronJobs
+    ? baseline.cronJobs.filter((name) => !cronJobs.includes(name))
+    : null;
+  return {
+    sessions: Object.keys(baseline.transcripts).length,
+    lostEvents,
+    missingCronJobs,
+    ok: lostEvents.length === 0 && (missingCronJobs === null || missingCronJobs.length === 0),
+  };
+}
+
+/** Jobs running in this process, so a second start for the same agent is refused. */
+const running = new Set<string>();
+
+/**
+ * Start an update. Validates synchronously enough to refuse clearly (UpdateRefusedError),
+ * then runs the steps in the background. Returns the new row id.
+ */
+export async function startAgentUpdate(agentId: string, requestedVersion?: string): Promise<number> {
+  if (!isValidAgentId(agentId)) throw new UpdateRefusedError('Invalid agent id');
+  if (running.has(agentId)) throw new UpdateRefusedError('An update of this agent is already running');
+  // Claimed synchronously, before the first await, so two requests cannot both pass.
+  running.add(agentId);
+  try {
+    // One source for every long operation: an update, recreate, restore, edit or backup.
+    const busy = await agentBusyReason(agentId);
+    if (busy) throw new UpdateRefusedError(busy);
+
+    return await runUpdateStart(agentId, requestedVersion);
+  } catch (e) {
+    running.delete(agentId);
+    throw e;
+  }
+}
+
+async function runUpdateStart(agentId: string, requestedVersion?: string): Promise<number> {
+  const container = await inspectAgentContainer(agentId);
+  if (!container) throw new UpdateRefusedError(`No container found with AGENT_ID '${agentId}'`);
+  if (!container.State?.Running) throw new UpdateRefusedError('Start the agent before updating it: its data is counted while it runs');
+  const name = (container.Name ?? '').replace(/^\//, '');
+
+  const images = await listLocalAgentImages();
+  const fromVersion = await containerOpenClawVersion({ name, imageId: container.Image ?? '', running: true }, images);
+  if (!fromVersion) throw new UpdateRefusedError('The OpenClaw version this agent runs could not be read');
+
+  const toVersion = requestedVersion ?? newestLocalSupportedVersion(images);
+  if (!toVersion || !isSupportedVersion(toVersion)) throw new UpdateRefusedError('No supported OpenClaw version to update to is downloaded');
+  if (!(await localVersionExists(toVersion))) throw new UpdateRefusedError(`OpenClaw ${toVersion} is not downloaded`);
+  if (compareVersions(toVersion, fromVersion) <= 0) {
+    throw new UpdateRefusedError(`The agent already runs OpenClaw ${fromVersion}; ${toVersion} is not newer`);
+  }
+
+  const id = insertUpdate(agentId, fromVersion, toVersion);
+  void runUpdate(id, agentId, name, fromVersion, toVersion).finally(() => running.delete(agentId));
+  return id;
+}
+
+async function runUpdate(id: number, agentId: string, name: string, fromVersion: string, toVersion: string): Promise<void> {
+  let stopped = false;
+  try {
+    const baseline: Baseline = { transcripts: await countTranscripts(name), cronJobs: await cronJobNames(name) };
+    updateRow(id, { baseline_json: JSON.stringify(baseline), status: 'backing_up' });
+
+    const { file } = await startColdBackup(agentId, { kind: 'preupdate', label: fromVersion, leaveStopped: true });
+    stopped = true;
+    updateRow(id, { backup_file: file });
+    const backup = await waitForColdBackup(agentId, { timeoutMs: COLD_BACKUP_WAIT_TIMEOUT_MS });
+    if (backup.status !== 'succeeded') throw new Error(`The pre-update backup failed: ${backup.error ?? 'unknown error'}`);
+
+    updateRow(id, { status: 'migrating' });
+    const container = await inspectAgentContainer(agentId);
+    if (!container) throw new Error('The agent container disappeared during the update');
+    await recreateAgentContainer(agentId, container, localImageRef(toVersion));
+    stopped = false;
+
+    if (!(await waitForGatewayReady(agentId, MIGRATION_READY_TIMEOUT_MS))) {
+      throw new Error(`OpenClaw ${toVersion} did not finish starting within ${MIGRATION_READY_TIMEOUT_MS / 60_000} minutes`);
+    }
+    const version = await runningVersion(agentId);
+    if (version !== toVersion) throw new Error(`The agent reports OpenClaw ${version ?? 'no version'} instead of ${toVersion}`);
+
+    await applyRuntimeConfig(agentId);
+    try {
+      patchRev4aProvider(agentId);
+    } catch (e) {
+      console.error('[agent:update] provider patch failed:', (e as Error).message);
+    }
+
+    updateRow(id, { status: 'verifying' });
+    const transcriptsAfter = await countTranscripts(agentId);
+    const cronAfter = await cronJobNames(agentId);
+    if (baseline.cronJobs?.length && cronAfter === null) {
+      // Unreadable is not "no jobs": refuse to call the update verified rather than
+      // report `done` while cron loss would be undetectable.
+      throw new Error('The cron job list could not be read after the update, so the verification is incomplete');
+    }
+    const result = verify(baseline, transcriptsAfter, cronAfter);
+    updateRow(id, { verify_json: JSON.stringify(result) });
+    if (!result.ok) {
+      throw new Error(
+        result.lostEvents.length
+          ? `${result.lostEvents.length} session(s) have fewer transcript events than before the update`
+          : `Cron jobs missing after the update: ${(result.missingCronJobs ?? []).join(', ')}`,
+      );
+    }
+
+    updateRow(id, { status: 'done' });
+
+    // Retention: images nothing needs any more (lib/agent-images.ts). Best-effort.
+    pruneAgentImages()
+      .then((removed) => { if (removed.length) console.log(`[agent:update] removed unused agent images: ${removed.join(', ')}`); })
+      .catch((err: unknown) => console.warn('[agent:update] image cleanup failed:', (err as Error).message));
+  } catch (e) {
+    // A failure before the recreate leaves the old container stopped by the backup:
+    // start it again, so a failed update never leaves the agent down. When it does not
+    // come back the failure text says so — a container that is "running" with no network
+    // is not an agent the operator can use.
+    if (stopped) {
+      const container = await inspectAgentContainer(agentId).catch(() => null);
+      const containerName = container?.Name?.replace(/^\//, '');
+      if (containerName && !container?.State?.Running) {
+        const started = await startAndVerifyContainer(agentId, containerName);
+        if (!started.ok) {
+          const note = `the previous container did not come back: ${started.error}`;
+          const message = shortError(e);
+          updateRow(id, { status: 'failed', error: `${message}; ${note}` });
+          return;
+        }
+      }
+    }
+    updateRow(id, { status: 'failed', error: shortError(e) });
+  }
+}
+
+/** The useful part of an error for the panel: a `docker exec` failure carries a whole stack trace. */
+function shortError(e: unknown): string {
+  const message = (e as Error)?.message ?? String(e);
+  const lines = message.split('\n').map((l) => l.trim()).filter(Boolean);
+  const cause = lines.find((l) => /^(Error|[A-Z]\w*Error):/.test(l));
+  const text = cause && cause !== lines[0] ? `${lines[0]} ${cause}` : lines[0] ?? message;
+  return text.length > 400 ? `${text.slice(0, 400)}…` : text;
+}
+
+/**
+ * At startup no update can still be running: rows still active were cut off by the
+ * restart. They become `interrupted` and an agent the pre-update backup left stopped is
+ * started again, so a Rev4a restart during the backup window never leaves it down. The
+ * row stays `interrupted`, so the operator can still roll back.
+ */
+export async function recoverInterruptedUpdates(): Promise<number> {
+  const ids = activeUpdateAgentIds();
+  if (ids.size === 0) return 0;
+  const interrupted = markInterruptedUpdates();
+  for (const agentId of ids) {
+    const container = await inspectAgentContainer(agentId).catch(() => null);
+    const name = container?.Name?.replace(/^\//, '');
+    if (!name || container?.State?.Running) continue;
+    const started = await startAndVerifyContainer(agentId, name);
+    if (!started.ok) console.warn(`[agent:update] ${agentId} did not come back after an interrupted update: ${started.error}`);
+  }
+  return interrupted;
+}
+
+/** The agent's current version and the version an Update would move it to, if any. */
+export async function updateCandidate(agentId: string): Promise<{
+  currentVersion: string | null;
+  candidate: { fromVersion: string; toVersion: string } | null;
+}> {
+  const container = await inspectAgentContainer(agentId);
+  if (!container) return { currentVersion: null, candidate: null };
+  const images = await listLocalAgentImages();
+  const currentVersion = await containerOpenClawVersion(
+    { name: (container.Name ?? '').replace(/^\//, ''), imageId: container.Image ?? '', running: container.State?.Running === true },
+    images,
+  );
+  const newest = newestLocalSupportedVersion(images);
+  const candidate = currentVersion && newest && compareVersions(newest, currentVersion) > 0
+    ? { fromVersion: currentVersion, toVersion: newest }
+    : null;
+  return { currentVersion, candidate };
+}
+
+// ── Rollback ─────────────────────────────────────────────────────────────────
+
+const RESTORE_TIMEOUT_MS = 60 * 60 * 1000;
+const ROLLBACK_READY_TIMEOUT_MS = 5 * 60 * 1000;
+const ROLLBACK_FROM: readonly AgentUpdateRow['status'][] = ['done', 'failed', 'interrupted', 'rollback_failed'];
+
+async function backupFileExists(file: string): Promise<boolean> {
+  try {
+    await runDocker(
+      ['run', '--rm', '-v', `${BACKUP_VOLUME}:/backup`, 'alpine', 'sh', '-c', 'test -f "/backup/$FILE"'],
+      { timeoutMs: 60_000, env: { FILE: file } },
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Roll the latest update of an agent back: restore its pre-update backup on the version
+ * it ran before. Everything the agent did after that backup is lost. Refused
+ * (UpdateRefusedError) when there is nothing to roll back or the backup is gone.
+ */
+export async function startAgentRollback(agentId: string): Promise<number> {
+  if (!isValidAgentId(agentId)) throw new UpdateRefusedError('Invalid agent id');
+  if (running.has(agentId)) throw new UpdateRefusedError('An update of this agent is running');
+  // Claimed synchronously, then the same single busy source as the update.
+  running.add(agentId);
+  try {
+    const busy = await agentBusyReason(agentId);
+    if (busy) throw new UpdateRefusedError(busy);
+    return await runRollbackStart(agentId);
+  } catch (e) {
+    running.delete(agentId);
+    throw e;
+  }
+}
+
+async function runRollbackStart(agentId: string): Promise<number> {
+  const row = latestUpdate(agentId);
+  if (!row || !ROLLBACK_FROM.includes(row.status)) throw new UpdateRefusedError('There is no update of this agent to roll back');
+  if (!row.backup_file || !row.from_version) throw new UpdateRefusedError('This update has no pre-update backup to restore');
+  if (!(await backupFileExists(row.backup_file))) {
+    throw new UpdateRefusedError(`The pre-update backup ${row.backup_file} no longer exists`);
+  }
+  const container = await inspectAgentContainer(agentId);
+  if (!container) throw new UpdateRefusedError(`No container found with AGENT_ID '${agentId}'`);
+
+  updateRow(row.id, { status: 'rolling_back', error: null });
+  void runRollback(row, container).finally(() => running.delete(agentId));
+  return row.id;
+}
+
+/**
+ * Restore exactly the pre-update state: the volume from the backup, the container on the
+ * previous image. Rev4a's config is not re-applied — the restored `openclaw.json` is the
+ * one that version accepted.
+ */
+async function runRollback(row: AgentUpdateRow, container: AgentContainerInspect): Promise<void> {
+  const agentId = row.agent_id;
+  const fromVersion = row.from_version as string;
+  const file = row.backup_file as string;
+  try {
+    if (!(await localVersionExists(fromVersion))) {
+      if (!isSupportedVersion(fromVersion)) {
+        throw new Error(`The image for OpenClaw ${fromVersion} is not available locally and this Rev4a cannot download it`);
+      }
+      await pullAgentImage(fromVersion);
+    }
+
+    const name = (container.Name ?? '').replace(/^\//, '');
+    if (container.State?.Running) {
+      await runDocker(['stop', '-t', '30', name], { timeoutMs: 45_000 })
+        .catch(() => runDocker(['kill', name], { timeoutMs: 15_000 }));
+    }
+
+    await runDocker(
+      [
+        'run', '--rm',
+        '-v', `agent-${agentId}-data:/target`,
+        '-v', `${BACKUP_VOLUME}:/backup`,
+        'alpine', 'sh', '-c',
+        'rm -rf /target/* /target/.[!.]* /target/..?* 2>/dev/null; tar xzf "/backup/$FILE" -C /target',
+      ],
+      { timeoutMs: RESTORE_TIMEOUT_MS, env: { FILE: file } },
+    );
+
+    await recreateAgentContainer(agentId, container, localImageRef(fromVersion));
+    if (!(await waitForGatewayReady(agentId, ROLLBACK_READY_TIMEOUT_MS))) {
+      throw new Error(`OpenClaw ${fromVersion} did not finish starting within ${ROLLBACK_READY_TIMEOUT_MS / 60_000} minutes`);
+    }
+    const version = parseOpenClawVersion(await dockerExecNoFail(agentId, ['openclaw', '--version'], { timeoutMs: 60_000 }));
+    if (version !== fromVersion) throw new Error(`The agent reports OpenClaw ${version ?? 'no version'} instead of ${fromVersion}`);
+
+    updateRow(row.id, { status: 'rolled_back' });
+  } catch (e) {
+    updateRow(row.id, { status: 'rollback_failed', error: shortError(e) });
+  }
+}
+
+export interface AgentUpdateView {
+  id: number;
+  agentId: string;
+  status: AgentUpdateRow['status'];
+  fromVersion: string | null;
+  toVersion: string;
+  backupFile: string | null;
+  /** Cold backup progress while `backing_up`. */
+  backupPercent: number | null;
+  verification: Verification | null;
+  error: string | null;
+  startedAtMs: number;
+  finishedAtMs: number | null;
+}
+
+/** The latest update of an agent, with live backup progress. */
+export async function agentUpdateView(agentId: string): Promise<AgentUpdateView | null> {
+  const row = latestUpdate(agentId);
+  if (!row) return null;
+  let backupPercent: number | null = null;
+  if (row.status === 'backing_up') backupPercent = (await coldBackupStatus(agentId))?.percent ?? null;
+  return {
+    id: row.id,
+    agentId: row.agent_id,
+    status: row.status,
+    fromVersion: row.from_version,
+    toVersion: row.to_version,
+    backupFile: row.backup_file,
+    backupPercent,
+    verification: row.verify_json ? (JSON.parse(row.verify_json) as Verification) : null,
+    error: row.error,
+    startedAtMs: row.started_at,
+    finishedAtMs: row.finished_at,
+  };
+}