@flame0510/project-aether 1.2.0 → 1.4.0

package/lib/channelManager.ts

@@ -22,6 +22,7 @@
  *     - concepts/multi-agent.md (bindings)
  */
 import { execSync } from 'child_process';
+import { dockerExec, dockerExecShellNoFail } from '@/lib/docker-exec';
 
 // ── Types ────────────────────────────────────
 
@@ -134,19 +135,22 @@ export function getChannels(agentId: string): AgentChannels {
 
 // ── Telegram ─────────────────────────────────
 
-export function setTelegramConfig(
+export async function setTelegramConfig(
   agentId: string,
   params: {
     botToken: string;
     dmPolicy?: string;
     allowFrom?: string[];
   },
-): { success: boolean; error?: string } {
+): Promise<{ success: boolean; error?: string }> {
   const container = findContainerById(agentId);
   if (!container) return { success: false, error: `Agent container not found: ${agentId}` };
 
   try {
-    const config = readConfigJson(container) ?? {};
+    // A failed read is not an empty config: writing `{}` back would replace the agent's
+    // whole openclaw.json with the channel block (the historical defect this route had).
+    const config = readConfigJson(container);
+    if (!config) return { success: false, error: 'Could not read the agent configuration' };
 
     // Ensure channels.telegram structure
     if (!config.channels) config.channels = {};
@@ -161,10 +165,7 @@ export function setTelegramConfig(
     // If token changed, wipe old pairing data to avoid orphaned allowFrom entries
     const oldToken = existing.botToken as string | undefined;
     if (oldToken && oldToken !== params.botToken && (existing.dmPolicy as string) === 'pairing') {
-      containerExecNoFail(
-        container,
-        `rm -f ${pairingFiles('telegram')} 2>/dev/null`,
-      );
+      await clearChannelAllowlist(container, 'telegram');
     }
 
     // Merge channel config: preserve ALL existing keys (provider, etc.)
@@ -190,7 +191,7 @@ export function setTelegramConfig(
   }
 }
 
-export function removeTelegram(agentId: string): { success: boolean; error?: string } {
+export async function removeTelegram(agentId: string): Promise<{ success: boolean; error?: string }> {
   const container = findContainerById(agentId);
   if (!container) return { success: false, error: `Agent container not found: ${agentId}` };
 
@@ -210,11 +211,8 @@ export function removeTelegram(agentId: string): { success: boolean; error?: str
       }
     }
 
-    // Clean up pairing files — they belong to the disconnected bot
-    containerExecNoFail(
-      container,
-      `rm -f ${pairingFiles('telegram')} 2>/dev/null`,
-    );
+    // The approved senders belong to the disconnected bot: clear the pairing store.
+    await clearChannelAllowlist(container, 'telegram');
 
     removeBindings(config, agentId, 'telegram');
     writeConfigJson(container, config);
@@ -232,7 +230,7 @@ export function removeTelegram(agentId: string): { success: boolean; error?: str
  * The agentId in the binding MUST be "main" (OpenClaw's default agent)
  * so that sessions are created as `agent:main:main`.
  * Using the container name as agentId would create sessions like
- * `agent:NOMEAGENTE:main` which breaks model bindings that target
+ * `agent:<AGENT_NAME>:main` which breaks model bindings that target
  * `agent:main:*`.
  *
  * Per multi-agent.md: bindings route (channel, accountId) to agentId.
@@ -291,22 +289,125 @@ export interface PairingState {
   approved: ApprovedPairing[];
 }
 
-function pairingAllowFile(channel: string): string {
-  return `/root/.openclaw/credentials/${channel}-default-allowFrom.json`;
+/**
+ * Script run inside the container to read or edit OpenClaw's channel pairing store.
+ *
+ * On 2026.9.3 the approved senders live in `~/.openclaw/state/openclaw.sqlite`
+ * (`channel_pairing_allow_entries`), and no CLI, RPC or documented export reads or
+ * writes them: `openclaw pairing` covers pending requests only, `channels.pairing.*`
+ * has no remove, and the writers sit in `dist/pairing-store-<hash>.mjs` with minified
+ * export names. The function *names* are preserved, though, so the module is found by
+ * glob and its functions by `name` — no hash or minified symbol is hardcoded. The
+ * write goes through the same state transaction the CLI uses.
+ *
+ * `op`, `channel` and `entry` arrive as argv, never interpolated into the source.
+ * The sentinel lines are machine-readable: `docker exec` exits 0 even when killed by
+ * the timeout, so an empty result cannot be read as success (docs/ARCHITECTURE.md §3.1).
+ */
+const PAIRING_STORE_SCRIPT = `
+(async () => {
+  const fs = require('fs');
+  const path = require('path');
+  const { pathToFileURL } = require('url');
+  const [op, channel, entry] = process.argv.slice(1);
+  const dist = '/usr/local/lib/node_modules/openclaw/dist';
+  let remove, readSync;
+  try {
+    for (const f of fs.readdirSync(dist).filter((x) => /^pairing-store-.*\\.mjs$/.test(x))) {
+      const mod = await import(pathToFileURL(path.join(dist, f)).href);
+      for (const v of Object.values(mod)) {
+        if (typeof v !== 'function') continue;
+        if (v.name === 'removeChannelAllowFromStoreEntry') remove = v;
+        if (v.name === 'readChannelAllowFromStoreSync') readSync = v;
+      }
+    }
+  } catch (e) { console.log('pair:error ' + e.message); return; }
+  if (!remove || !readSync) { console.log('pair:unsupported'); return; }
+  // Entries are sender ids as strings today; anything else has a field to read. An
+  // unexpected shape is an error, never String(entry) — that would print
+  // "[object Object]" and then remove nothing while reporting success.
+  const normalize = (list) => (list || []).map((e) => {
+    if (typeof e === 'string') return e;
+    if (e && typeof e === 'object') { const v = e.id ?? e.senderId ?? e.entry; return typeof v === 'string' ? v : null; }
+    return null;
+  });
+  try {
+    if (op === 'read') {
+      const entries = normalize(readSync(channel));
+      if (entries.some((e) => e === null)) { console.log('pair:error unexpected allowlist entry shape'); return; }
+      console.log('pair:list ' + JSON.stringify(entries));
+    } else if (op === 'remove') {
+      const r = await remove({ channel, entry });
+      console.log(r && r.changed ? 'pair:ok' : 'pair:absent');
+    } else if (op === 'clear') {
+      const entries = normalize(readSync(channel));
+      if (entries.some((e) => e === null)) { console.log('pair:error unexpected allowlist entry shape'); return; }
+      for (const e of entries) await remove({ channel, entry: e });
+      console.log('pair:ok');
+    } else {
+      console.log('pair:error unknown op');
+    }
+  } catch (e) { console.log('pair:error ' + e.message); }
+})();
+`;
+
+interface StoreOpResult {
+  status: 'ok' | 'absent' | 'unsupported' | 'error';
+  entries?: string[];
+  error?: string;
+}
+
+/** Channel ids reach shell commands and the store API; keep them to OpenClaw's shape. */
+function isSafeChannel(channel: string): boolean {
+  return /^[a-z0-9_-]+$/.test(channel);
+}
+
+/** Run one pairing-store operation inside the container; see PAIRING_STORE_SCRIPT. */
+async function runPairingStore(container: string, op: 'read' | 'remove' | 'clear', channel: string, entry?: string): Promise<StoreOpResult> {
+  const argv = ['node', '-e', PAIRING_STORE_SCRIPT, op, channel];
+  if (entry !== undefined) argv.push(entry);
+  let out: string;
+  try {
+    // argv reaches docker as an array — the script, the op and the sender id are
+    // never shell syntax. Async: the script loads OpenClaw's own modules inside the
+    // container and takes a second, which must not freeze Rev4a's event loop while
+    // the panel polls it.
+    out = (await dockerExec(container, argv, { timeoutMs: 20_000 })).trim();
+  } catch (e) {
+    return { status: 'error', error: (e as Error).message };
+  }
+  const listLine = out.split('\n').find((l) => l.startsWith('pair:list '));
+  if (listLine) {
+    try {
+      return { status: 'ok', entries: JSON.parse(listLine.slice('pair:list '.length)) as string[] };
+    } catch {
+      return { status: 'error', error: 'Could not read the approved senders list' };
+    }
+  }
+  if (out.includes('pair:ok')) return { status: 'ok' };
+  if (out.includes('pair:absent')) return { status: 'absent' };
+  if (out.includes('pair:unsupported')) return { status: 'unsupported' };
+  const errLine = out.split('\n').find((l) => l.startsWith('pair:error '));
+  return { status: 'error', error: errLine ? errLine.slice('pair:error '.length) : (out || 'Pairing store command produced no output') };
 }
 
-function pairingFiles(channel: string): string {
-  return `/root/.openclaw/credentials/${channel}-pairing.json /root/.openclaw/credentials/${channel}-default-allowFrom.json`;
+/** Drop every approved sender of a channel — a different bot must not inherit them. */
+async function clearChannelAllowlist(container: string, channel: string): Promise<void> {
+  if (!isSafeChannel(channel)) return;
+  const result = await runPairingStore(container, 'clear', channel);
+  if (result.status === 'error') {
+    console.warn(`[channels] could not clear the ${channel} allowlist: ${result.error}`);
+  }
 }
 
 /** Get pending + approved pairings for a channel */
-export function getPairings(agentId: string, channel: string = 'telegram'): PairingState {
+export async function getPairings(agentId: string, channel: string = 'telegram'): Promise<PairingState> {
   const container = findContainerById(agentId);
   const fallback: PairingState = { pending: [], approved: [] };
-  if (!container) return fallback;
+  if (!container || !isSafeChannel(channel)) return fallback;
 
   // Pending
-  const pendingRaw = containerExecNoFail(container, `openclaw pairing list --channel ${channel} --json 2>/dev/null`);
+  const pendingRaw = await dockerExecShellNoFail(container, `openclaw pairing list --channel ${channel} --json 2>/dev/null`);
   const pending: PendingPairing[] = [];
   if (pendingRaw) {
     try {
@@ -320,33 +421,25 @@ export function getPairings(agentId: string, channel: string = 'telegram'): Pair
     } catch { /* ignore */ }
   }
 
-  // Approved: read from OpenClaw credentials file
-  const allowRaw = containerExecNoFail(container, `cat ${pairingAllowFile(channel)} 2>/dev/null`);
+  // Approved: OpenClaw's pairing store (2026.9.x keeps it in SQLite; the legacy
+  // credentials files it replaced are gone, so reading those returned nothing).
   const approved: ApprovedPairing[] = [];
-  if (allowRaw) {
-    try {
-      const parsed = JSON.parse(allowRaw);
-      const entries = parsed?.allowFrom ?? [];
-      for (const entry of entries) {
-        if (typeof entry === 'string') {
-          approved.push({ senderId: entry });
-        } else if (entry?.senderId || entry?.id) {
-          approved.push({ senderId: entry.senderId ?? entry.id });
-        }
-      }
-    } catch { /* ignore */ }
+  const store = await runPairingStore(container, 'read', channel);
+  if (store.status === 'ok') {
+    for (const entry of store.entries ?? []) approved.push({ senderId: String(entry) });
   }
 
   return { pending, approved };
 }
 
 /** Approve a pending pairing code */
-export function approvePairing(agentId: string, code: string, channel: string = 'telegram'): { success: boolean; error?: string } {
+export async function approvePairing(agentId: string, code: string, channel: string = 'telegram'): Promise<{ success: boolean; error?: string }> {
   const container = findContainerById(agentId);
   if (!container) return { success: false, error: `Agent container not found: ${agentId}` };
+  if (!isSafeChannel(channel)) return { success: false, error: 'Invalid channel id' };
 
   try {
-    const out = containerExecNoFail(container, `openclaw pairing approve ${channel} ${escapeShellArg(code)} 2>&1`);
+    const out = await dockerExecShellNoFail(container, `openclaw pairing approve ${channel} ${escapeShellArg(code)} 2>&1`);
     if (!out) {
       return { success: false, error: 'Command produced no output — pairing command may not be available' };
     }
@@ -360,34 +453,30 @@ export function approvePairing(agentId: string, code: string, channel: string =
   }
 }
 
-/** Revoke an approved sender from the allowlist */
-export function revokePairing(agentId: string, senderId: string, channel: string = 'telegram'): { success: boolean; error?: string } {
+/**
+ * Revoke an approved sender from the allowlist.
+ *
+ * There is no CLI or RPC for this: `openclaw pairing` exposes only `approve`, `list`
+ * and `help`, and `channels.pairing.*` has no remove (verified on 2026.9.3). The
+ * store's own writer is called instead (`removeChannelAllowFromStoreEntry`, found by
+ * name — see PAIRING_STORE_SCRIPT). On a release that no longer exposes it, the
+ * failure is explicit: nothing is silently left unchanged (which is what the old
+ * `openclaw pairing revoke` probe did).
+ */
+export async function revokePairing(agentId: string, senderId: string, channel: string = 'telegram'): Promise<{ success: boolean; error?: string }> {
   const container = findContainerById(agentId);
   if (!container) return { success: false, error: `Agent container not found: ${agentId}` };
-
-  try {
-    // Try native revoke command first, fall back to direct file manipulation
-    const nativeOut = containerExecNoFail(
-      container,
-      `openclaw pairing revoke ${channel} ${escapeShellArg(senderId)} 2>&1`,
-    );
-
-    if (nativeOut && !nativeOut.includes('Unknown command') && !nativeOut.includes('not found')) {
-      return { success: true };
-    }
-
-    // Fallback: remove from credentials file directly
-    const filePath = pairingAllowFile(channel);
-    const fallbackOut = containerExecNoFail(
-      container,
-      `node -e "const p='${filePath}';try{const d=JSON.parse(require('fs').readFileSync(p,'utf8'));d.allowFrom=(d.allowFrom||[]).filter(e=>e!=='${senderId.replace(/'/g, "'\\''")}');require('fs').writeFileSync(p,JSON.stringify(d,null,2),'utf8')}catch(e){console.error('revoke fallback error:',e.message)}"`,
-    );
-    if (fallbackOut && fallbackOut.includes('revoke fallback error:')) {
-      return { success: false, error: fallbackOut };
-    }
-
-    return { success: true };
-  } catch (e) {
-    return { success: false, error: (e as Error).message };
+  if (!isSafeChannel(channel)) return { success: false, error: 'Invalid channel id' };
+
+  const result = await runPairingStore(container, 'remove', channel, senderId);
+  if (result.status === 'ok') return { success: true };
+  if (result.status === 'absent') return { success: true }; // already gone — the desired state
+  if (result.status === 'unsupported') {
+    return {
+      success: false,
+      error: 'This OpenClaw release does not expose its pairing store to Rev4a. '
+           + 'Revoke the sender with `/allowlist remove` from the chat.',
+    };
   }
+  return { success: false, error: result.error ?? 'Revoke failed' };
 }

package/lib/cold-backup.ts

@@ -0,0 +1,354 @@
+/**
+ * Cold backup of an agent's volume.
+ *
+ * The agent is stopped, a detached helper container archives the volume, the archive
+ * is read back, and the agent is started again if it was running. A backup taken while
+ * OpenClaw runs can copy its SQLite files mid-write; this one cannot.
+ *
+ * The helper container is the job: `rev4a-backup-<agentId>`, labelled with the agent,
+ * the archive name, the kind and whether the agent was running. Everything needed to
+ * finish or clean up a job lives in Docker, not in Rev4a's memory, so a job survives a
+ * Rev4a restart: `reconcileColdBackups()` picks helpers up again at startup, and
+ * finishing is idempotent.
+ *
+ * The archive is written as `<file>.partial` and renamed only after `tar -tzf` has read
+ * all of it back and found `.openclaw/openclaw.json`, so a listed backup is complete.
+ * Design: plans/COLD-BACKUP-PLAN.md.
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { dockerFetch } from '@/lib/docker-socket';
+import { isValidAgentId } from '@/lib/container';
+import { runDocker } from '@/lib/agent-images';
+
+const execFileAsync = promisify(execFile);
+
+export const BACKUP_VOLUME = 'rev4a-backups';
+const HELPER_PREFIX = 'rev4a-backup-';
+const LABEL_AGENT = 'rev4a.backup.agent';
+const LABEL_FILE = 'rev4a.backup.file';
+const LABEL_KIND = 'rev4a.backup.kind';
+const LABEL_PREV = 'rev4a.backup.prev-state';
+const LABEL_STARTED = 'rev4a.backup.started-at';
+/** GNU tar counts checkpoints in records of 10 240 bytes of the uncompressed stream. */
+const TAR_RECORD_BYTES = 10_240;
+const CHECKPOINT_RECORDS = 2_000;
+const WATCH_MS = 3_000;
+
+export type ColdBackupKind = 'manual' | 'preupdate' | 'prerecreate';
+
+export interface ColdBackupState {
+  agentId: string;
+  status: 'running' | 'succeeded' | 'failed';
+  file: string;
+  kind: ColdBackupKind;
+  startedAtMs: number | null;
+  finishedAtMs: number | null;
+  /** Uncompressed bytes to archive, from `du`; null until measured. */
+  totalBytes: number | null;
+  /** Uncompressed bytes archived so far. */
+  doneBytes: number | null;
+  percent: number | null;
+  /** Archive size once complete. */
+  archiveBytes: number | null;
+  error: string | null;
+}
+
+export class ColdBackupBusyError extends Error {}
+
+const helperName = (agentId: string) => `${HELPER_PREFIX}${agentId}`;
+
+/**
+ * The helper script, run by `sh` inside the agent's own image, which carries GNU tar,
+ * coreutils and gzip. `FILE` comes in through the environment, never through the
+ * script text. Machine-readable lines start with `REV4A `.
+ */
+const SCRIPT = [
+  'set -u',
+  'P="/backup/$FILE.partial"',
+  'rm -f "$P"',
+  'TOTAL=$(du -sb --exclude=.npm/_cacache /source 2>/dev/null | cut -f1)',
+  'echo "REV4A total ${TOTAL:-0}"',
+  'AVAIL=$(( $(df -Pk /backup | awk \'NR==2 {print $4}\') * 1024 ))',
+  'NEED=$(( ${TOTAL:-0} * 6 / 10 ))',
+  'if [ "$AVAIL" -lt "$NEED" ]; then echo "REV4A error not enough space in rev4a-backups: about $NEED bytes needed, $AVAIL free"; exit 3; fi',
+  `if ! tar -czf "$P" --exclude=.npm/_cacache --checkpoint=${CHECKPOINT_RECORDS} --checkpoint-action=echo='REV4A progress %u' -C /source . ; then rm -f "$P"; echo "REV4A error tar failed"; exit 4; fi`,
+  'if ! tar -tzf "$P" > /tmp/rev4a-list || ! grep -qx "./.openclaw/openclaw.json" /tmp/rev4a-list; then rm -f "$P"; echo "REV4A error verification failed: the archive does not read back or holds no .openclaw/openclaw.json"; exit 5; fi',
+  'mv "$P" "/backup/$FILE" && chmod 644 "/backup/$FILE"',
+  'echo "REV4A done $(stat -c %s "/backup/$FILE")"',
+].join('\n');
+
+interface HelperInspect {
+  Id?: string;
+  State?: { Running?: boolean; ExitCode?: number; StartedAt?: string; FinishedAt?: string };
+  Config?: { Labels?: Record<string, string> };
+}
+
+async function inspectHelper(agentId: string): Promise<HelperInspect | null> {
+  try {
+    const info = await dockerFetch<HelperInspect>('GET', `/containers/${helperName(agentId)}/json`);
+    return typeof info?.Id === 'string' ? info : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether a cold backup of this agent is running (its helper exists). */
+export async function isColdBackupRunning(agentId: string): Promise<boolean> {
+  const helper = await inspectHelper(agentId);
+  return !!helper?.State?.Running;
+}
+
+async function helperLog(agentId: string): Promise<string> {
+  try {
+    const { stdout, stderr } = await execFileAsync('docker', ['logs', '--tail', '400', helperName(agentId)], {
+      encoding: 'utf-8',
+      timeout: 15_000,
+      maxBuffer: 4 * 1024 * 1024,
+    });
+    return `${stdout}\n${stderr}`;
+  } catch {
+    return '';
+  }
+}
+
+function parseLog(log: string) {
+  let totalBytes: number | null = null;
+  let doneBytes: number | null = null;
+  let archiveBytes: number | null = null;
+  let error: string | null = null;
+  for (const raw of log.split('\n')) {
+    const at = raw.indexOf('REV4A ');
+    if (at === -1) continue;
+    const [kind, ...rest] = raw.slice(at + 6).trim().split(' ');
+    const value = rest.join(' ');
+    if (kind === 'total') totalBytes = Number(value) || null;
+    else if (kind === 'progress') doneBytes = (Number(value) || 0) * TAR_RECORD_BYTES;
+    else if (kind === 'done') archiveBytes = Number(value) || null;
+    else if (kind === 'error') error = value;
+  }
+  const percent = totalBytes && doneBytes !== null ? Math.min(99, Math.round((doneBytes / totalBytes) * 100)) : null;
+  return { totalBytes, doneBytes, archiveBytes, error, percent };
+}
+
+function stateFrom(agentId: string, helper: HelperInspect, log: string, status: ColdBackupState['status']): ColdBackupState {
+  const labels = helper.Config?.Labels ?? {};
+  const parsed = parseLog(log);
+  const finished = helper.State?.FinishedAt && !helper.State.FinishedAt.startsWith('0001') ? Date.parse(helper.State.FinishedAt) : null;
+  return {
+    agentId,
+    status,
+    file: labels[LABEL_FILE] ?? '',
+    kind: labels[LABEL_KIND] === 'preupdate' ? 'preupdate' : labels[LABEL_KIND] === 'prerecreate' ? 'prerecreate' : 'manual',
+    startedAtMs: Number(labels[LABEL_STARTED]) || null,
+    finishedAtMs: status === 'running' ? null : finished,
+    totalBytes: parsed.totalBytes,
+    doneBytes: parsed.doneBytes,
+    percent: status === 'succeeded' ? 100 : parsed.percent,
+    archiveBytes: parsed.archiveBytes,
+    error: status === 'failed' ? parsed.error ?? `backup helper exited with code ${helper.State?.ExitCode ?? '?'}` : null,
+  };
+}
+
+/** Results of jobs finished since this process started, for status reads after the helper is gone. */
+const finished = new Map<string, ColdBackupState>();
+/** Finishing in flight, so concurrent status reads finish a job once. */
+const finishing = new Map<string, Promise<ColdBackupState>>();
+const watching = new Set<string>();
+
+async function startAgentIfItWasRunning(labels: Record<string, string>, agentId: string): Promise<void> {
+  if (labels[LABEL_PREV] !== 'running') return;
+  const container = await agentContainerName(agentId);
+  if (container) await runDocker(['start', container], { timeoutMs: 60_000 }).catch(() => {});
+}
+
+async function removePartial(file: string): Promise<void> {
+  if (!file) return;
+  await runDocker(
+    ['run', '--rm', '-v', `${BACKUP_VOLUME}:/backup`, '-e', `FILE=${file}`, 'alpine', 'sh', '-c', 'rm -f "/backup/$FILE.partial"'],
+    { timeoutMs: 60_000 },
+  ).catch(() => {});
+}
+
+/** Finish an exited job: record its result, start the agent if it was running, remove the helper. */
+async function finishJob(agentId: string, helper: HelperInspect): Promise<ColdBackupState> {
+  const inFlight = finishing.get(agentId);
+  if (inFlight) return inFlight;
+  const job = (async () => {
+    const log = await helperLog(agentId);
+    const ok = helper.State?.ExitCode === 0 && /REV4A done \d+/.test(log);
+    const state = stateFrom(agentId, helper, log, ok ? 'succeeded' : 'failed');
+    const labels = helper.Config?.Labels ?? {};
+    if (!ok) await removePartial(state.file);
+    await startAgentIfItWasRunning(labels, agentId);
+    await runDocker(['rm', '-f', helperName(agentId)], { timeoutMs: 30_000 }).catch(() => {});
+    finished.set(agentId, state);
+    return state;
+  })();
+  finishing.set(agentId, job);
+  try {
+    return await job;
+  } finally {
+    finishing.delete(agentId);
+  }
+}
+
+/** Current or last cold backup of an agent; finishes the job when its helper has exited. */
+export async function coldBackupStatus(agentId: string): Promise<ColdBackupState | null> {
+  const helper = await inspectHelper(agentId);
+  if (!helper) return finishing.get(agentId) ?? finished.get(agentId) ?? null;
+  if (helper.State?.Running) return stateFrom(agentId, helper, await helperLog(agentId), 'running');
+  return finishJob(agentId, helper);
+}
+
+/** Polls a running job until it finishes, so the agent restarts even when nobody reads its status. */
+function watch(agentId: string): void {
+  if (watching.has(agentId)) return;
+  watching.add(agentId);
+  const tick = async () => {
+    const state = await coldBackupStatus(agentId).catch(() => null);
+    if (state?.status === 'running') {
+      setTimeout(() => { void tick(); }, WATCH_MS);
+    } else {
+      watching.delete(agentId);
+    }
+  };
+  setTimeout(() => { void tick(); }, WATCH_MS);
+}
+
+interface ContainerInspect {
+  Name?: string;
+  Image?: string;
+  State?: { Running?: boolean };
+}
+
+async function agentContainerName(agentId: string): Promise<string | null> {
+  const filters = encodeURIComponent(JSON.stringify({ label: [`AGENT_ID=${agentId}`] }));
+  const list = await dockerFetch<{ Names?: string[] }[]>('GET', `/containers/json?all=true&filters=${filters}`).catch(() => null);
+  const name = Array.isArray(list) ? list[0]?.Names?.[0] : undefined;
+  return name ? name.replace(/^\//, '') : null;
+}
+
+function timestamp(): string {
+  const d = new Date();
+  const pad = (n: number, w = 2) => String(n).padStart(w, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}${pad(d.getMilliseconds(), 3)}`;
+}
+
+/**
+ * Start a cold backup. Returns once the helper runs; the archive is written in the
+ * background. `label` goes into the file name (the OpenClaw version, for a pre-update
+ * backup): `agent-<id>-preupdate-<label>-<ts>.tar.gz` or `agent-<id>-cold-<ts>.tar.gz`.
+ * Throws `ColdBackupBusyError` when a backup of this agent is already running.
+ */
+export async function startColdBackup(
+  agentId: string,
+  /** `leaveStopped`: do not start the agent afterwards — the Update action recreates it next. */
+  opts: { kind: ColdBackupKind; label?: string; leaveStopped?: boolean },
+): Promise<{ file: string }> {
+  if (!isValidAgentId(agentId)) throw new Error('Invalid agent id');
+  if (await inspectHelper(agentId)) {
+    const current = await coldBackupStatus(agentId);
+    if (current?.status === 'running') throw new ColdBackupBusyError('A backup of this agent is already running');
+  }
+
+  const name = await agentContainerName(agentId);
+  if (!name) throw new Error(`No container found with AGENT_ID '${agentId}'`);
+  const container = await dockerFetch<ContainerInspect>('GET', `/containers/${encodeURIComponent(name)}/json`);
+  if (!container?.Image) throw new Error(`Container '${name}' could not be inspected`);
+  const volume = `agent-${agentId}-data`;
+  const vol = await dockerFetch<{ Name?: string }>('GET', `/volumes/${volume}`).catch(() => null);
+  if (vol?.Name !== volume) throw new Error(`No persistent volume found for agent '${agentId}'`);
+
+  const label = (opts.label ?? '').replace(/[^A-Za-z0-9._-]/g, '');
+  const file = opts.kind === 'preupdate'
+    ? `agent-${agentId}-preupdate-${label || 'unknown'}-${timestamp()}.tar.gz`
+    : opts.kind === 'prerecreate'
+      ? `agent-${agentId}-prerecreate-${timestamp()}.tar.gz`
+      : `agent-${agentId}-cold-${timestamp()}.tar.gz`;
+
+  const wasRunning = container.State?.Running === true;
+  if (wasRunning) {
+    await runDocker(['stop', '-t', '30', name], { timeoutMs: 45_000 })
+      .catch(() => runDocker(['kill', name], { timeoutMs: 15_000 }));
+  }
+
+  try {
+    await runDocker([
+      'run', '-d', '--name', helperName(agentId),
+      '--label', `${LABEL_AGENT}=${agentId}`,
+      '--label', `${LABEL_FILE}=${file}`,
+      '--label', `${LABEL_KIND}=${opts.kind}`,
+      '--label', `${LABEL_PREV}=${wasRunning && !opts.leaveStopped ? 'running' : 'stopped'}`,
+      '--label', `${LABEL_STARTED}=${Date.now()}`,
+      '-e', `FILE=${file}`,
+      '-v', `${volume}:/source:ro`,
+      '-v', `${BACKUP_VOLUME}:/backup`,
+      '--entrypoint', 'sh',
+      container.Image,
+      '-c', SCRIPT,
+    ], { timeoutMs: 60_000 });
+  } catch (e) {
+    await runDocker(['rm', '-f', helperName(agentId)], { timeoutMs: 30_000 }).catch(() => {});
+    if (wasRunning) await runDocker(['start', name], { timeoutMs: 60_000 }).catch(() => {});
+    throw new Error(`Could not start the backup: ${(e as Error).message}`);
+  }
+
+  finished.delete(agentId);
+  watch(agentId);
+  return { file };
+}
+
+/** Cancel a running backup: the partial archive is removed and the agent restarted if it was running. */
+export async function cancelColdBackup(agentId: string): Promise<boolean> {
+  const helper = await inspectHelper(agentId);
+  if (!helper?.State?.Running) return false;
+  const labels = helper.Config?.Labels ?? {};
+  await runDocker(['rm', '-f', helperName(agentId)], { timeoutMs: 30_000 }).catch(() => {});
+  await removePartial(labels[LABEL_FILE] ?? '');
+  await startAgentIfItWasRunning(labels, agentId);
+  finished.set(agentId, { ...stateFrom(agentId, helper, '', 'failed'), error: 'cancelled', finishedAtMs: Date.now() });
+  return true;
+}
+
+/** Wait for a job to finish, reporting progress. Resolves with the final state. */
+export async function waitForColdBackup(
+  agentId: string,
+  opts: { onProgress?: (state: ColdBackupState) => void; pollMs?: number; timeoutMs?: number } = {},
+): Promise<ColdBackupState> {
+  const deadline = opts.timeoutMs ? Date.now() + opts.timeoutMs : null;
+  for (;;) {
+    const state = await coldBackupStatus(agentId);
+    if (!state) throw new Error('The backup job disappeared');
+    if (state.status !== 'running') return state;
+    opts.onProgress?.(state);
+    if (deadline && Date.now() >= deadline) {
+      // The helper is stuck: say so instead of hanging the caller (and the agent's
+      // busy lock) forever. The job is left alone — an operator can cancel it.
+      throw new Error(`The cold backup did not finish within ${Math.round(opts.timeoutMs! / 60_000)} minutes`);
+    }
+    await new Promise((r) => setTimeout(r, opts.pollMs ?? 2_000));
+  }
+}
+
+/** Agent ids with a backup helper, running or exited. */
+export async function listColdBackupHelpers(): Promise<string[]> {
+  const filters = encodeURIComponent(JSON.stringify({ label: [LABEL_AGENT] }));
+  const list = await dockerFetch<{ Labels?: Record<string, string> }[]>('GET', `/containers/json?all=true&filters=${filters}`).catch(() => null);
+  return (Array.isArray(list) ? list : []).map((c) => c.Labels?.[LABEL_AGENT] ?? '').filter(Boolean);
+}
+
+/** Agent ids with a cold backup currently running (helper container still running). */
+export async function listRunningColdBackups(): Promise<string[]> {
+  const filters = encodeURIComponent(JSON.stringify({ label: [LABEL_AGENT], status: ['running'] }));
+  const list = await dockerFetch<{ Labels?: Record<string, string> }[]>('GET', `/containers/json?all=true&filters=${filters}`).catch(() => null);
+  return (Array.isArray(list) ? list : []).map((c) => c.Labels?.[LABEL_AGENT] ?? '').filter(Boolean);
+}
+
+/** At startup: finish helpers that exited while Rev4a was down, and watch the ones still running. */
+export async function reconcileColdBackups(): Promise<void> {
+  for (const agentId of await listColdBackupHelpers()) {
+    const state = await coldBackupStatus(agentId).catch(() => null);
+    if (state?.status === 'running') watch(agentId);
+  }
+}