@flame0510/project-aether 1.3.0 → 1.4.0

package/app/agents/UpdateSection.tsx

@@ -0,0 +1,300 @@
+'use client';
+
+/**
+ * The OpenClaw version of one agent, the Update action and its Rollback, in the
+ * agent's detail panel.
+ *
+ * An update stops the agent, takes a cold backup, recreates it on the newer version
+ * (which migrates its data one way), then checks that no transcript events or cron jobs
+ * went missing. A rollback restores that backup on the previous version. Data comes from
+ * `/api/agents/[id]/update`, polled every 2 s while either runs. See lib/agent-update.ts.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Badge, Button, ConfirmModal } from '../components/ui';
+import { SkeletonLines } from '../components/Skeleton';
+
+type UpdateStatus =
+  | 'pending' | 'backing_up' | 'migrating' | 'verifying' | 'done'
+  | 'failed' | 'interrupted' | 'rolling_back' | 'rolled_back' | 'rollback_failed';
+
+interface Verification {
+  sessions: number;
+  lostEvents: { session: string; before: number; after: number }[];
+  missingCronJobs: string[] | null;
+  ok: boolean;
+}
+
+interface UpdateView {
+  id: number;
+  status: UpdateStatus;
+  fromVersion: string | null;
+  toVersion: string;
+  backupFile: string | null;
+  backupPercent: number | null;
+  verification: Verification | null;
+  error: string | null;
+  startedAtMs: number;
+  finishedAtMs: number | null;
+}
+
+interface UpdateInfo {
+  currentVersion: string | null;
+  candidate: { fromVersion: string; toVersion: string } | null;
+  update: UpdateView | null;
+}
+
+type Action = 'update' | 'rollback';
+
+const ACTIVE: UpdateStatus[] = ['pending', 'backing_up', 'migrating', 'verifying', 'rolling_back'];
+const ROLLBACK_FROM: UpdateStatus[] = ['done', 'failed', 'interrupted', 'rollback_failed'];
+const POLL_MS = 2_000;
+
+const STEPS: { status: UpdateStatus; label: string }[] = [
+  { status: 'backing_up', label: 'Cold backup' },
+  { status: 'migrating', label: 'Start on the new version' },
+  { status: 'verifying', label: 'Check transcripts and cron jobs' },
+];
+
+const metaStyle: React.CSSProperties = { fontSize: 11, color: 'var(--text-dim)', wordBreak: 'break-word' };
+
+function when(ms: number | null): string {
+  return ms ? new Date(ms).toLocaleString() : '';
+}
+
+export default function UpdateSection({
+  agentId,
+  running,
+  onChanged,
+  onStarted,
+}: {
+  agentId: string;
+  running: boolean;
+  /** An update or rollback finished: the parent reloads the agent (new image, new version). */
+  onChanged?: () => void;
+  /** The update or rollback started — show the UPDATING chip at once. */
+  onStarted?: () => void;
+}) {
+  const [info, setInfo] = useState<UpdateInfo | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [busy, setBusy] = useState<Action | null>(null);
+  const busyRef = useRef<Action | null>(null);
+  const [confirming, setConfirming] = useState<Action | null>(null);
+  const [actionError, setActionError] = useState<string | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+  const lastStatus = useRef<UpdateStatus | null>(null);
+
+  const load = useCallback(async () => {
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    try {
+      const res = await fetch(`/api/agents/${encodeURIComponent(agentId)}/update`, { signal: controller.signal, cache: 'no-store' });
+      if (abortRef.current !== controller) return;
+      const data = (await res.json().catch(() => null)) as (UpdateInfo & { error?: string }) | null;
+      if (abortRef.current !== controller) return;
+      if (!res.ok || !data) {
+        setLoadError(data?.error ?? `Could not load the update state (HTTP ${res.status})`);
+        return;
+      }
+      setInfo(data);
+      setLoadError(null);
+      const status = data.update?.status ?? null;
+      if (lastStatus.current && ACTIVE.includes(lastStatus.current) && status && !ACTIVE.includes(status)) onChanged?.();
+      lastStatus.current = status;
+    } catch (e) {
+      if ((e as Error)?.name !== 'AbortError' && abortRef.current === controller) setLoadError('Could not load the update state');
+    }
+  }, [agentId, onChanged]);
+
+  const update = info?.update ?? null;
+  const active = !!update && ACTIVE.includes(update.status);
+
+  useEffect(() => {
+    setInfo(null);
+    setLoadError(null);
+    lastStatus.current = null;
+    void load();
+    return () => abortRef.current?.abort();
+  }, [load]);
+
+  useEffect(() => {
+    if (!active) return;
+    const timer = setInterval(() => { void load(); }, POLL_MS);
+    return () => clearInterval(timer);
+  }, [active, load]);
+
+  const run = async (action: Action) => {
+    setConfirming(null);
+    if (busyRef.current) return;
+    busyRef.current = action;
+    setBusy(action);
+    setActionError(null);
+    try {
+      const res = action === 'update'
+        ? await fetch(`/api/agents/${encodeURIComponent(agentId)}/update`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ version: info?.candidate?.toVersion }),
+        })
+        : await fetch(`/api/agents/${encodeURIComponent(agentId)}/update/rollback`, { method: 'POST' });
+      if (!res.ok) {
+        const data = (await res.json().catch(() => null)) as { error?: string } | null;
+        setActionError(data?.error ?? `Could not start the ${action} (HTTP ${res.status})`);
+      } else {
+        onStarted?.();
+      }
+    } catch {
+      setActionError(`Could not start the ${action}`);
+    }
+    busyRef.current = null;
+    setBusy(null);
+    void load();
+  };
+
+  if (!info && !loadError) return <SkeletonLines count={2} />;
+
+  const candidate = info?.candidate ?? null;
+  const stepIndex = update ? STEPS.findIndex((s) => s.status === update.status) : -1;
+  const canRollBack = !!update && !active && ROLLBACK_FROM.includes(update.status) && !!update.backupFile && !!update.fromVersion;
+
+  return (
+    <div>
+      {loadError && (
+        <div style={{ margin: '0 0 6px' }}>
+          <Badge tone="danger"><span style={{ fontSize: 10 }}>{loadError}</span></Badge>
+        </div>
+      )}
+
+      <div style={{ fontSize: 12, color: 'var(--text)', marginBottom: 6 }}>
+        OpenClaw {info?.currentVersion ?? 'version unknown'}
+      </div>
+
+      {update && active && update.status !== 'rolling_back' && (
+        <div style={{ margin: '6px 0 10px' }}>
+          <div style={metaStyle}>Updating OpenClaw {update.fromVersion} → {update.toVersion}. The agent is offline until it finishes.</div>
+          {STEPS.map((step, i) => {
+            const state = update.status === 'pending' ? 'waiting' : i < stepIndex ? 'done' : i === stepIndex ? 'running' : 'waiting';
+            return (
+              <div key={step.status} style={{ display: 'flex', gap: 8, alignItems: 'center', padding: '3px 0', fontSize: 11 }}>
+                <span style={{ width: 14, color: state === 'done' ? 'var(--green)' : state === 'running' ? 'var(--violet)' : 'var(--text-dim)' }}>
+                  {state === 'done' ? '✓' : state === 'running' ? '●' : '○'}
+                </span>
+                <span style={{ color: state === 'waiting' ? 'var(--text-dim)' : 'var(--text)' }}>
+                  {step.label}
+                  {state === 'running' && step.status === 'backing_up' && update.backupPercent !== null ? ` — ${update.backupPercent}%` : ''}
+                </span>
+              </div>
+            );
+          })}
+        </div>
+      )}
+
+      {update && update.status === 'rolling_back' && (
+        <div style={{ margin: '6px 0 10px', ...metaStyle }}>
+          Rolling back to OpenClaw {update.fromVersion}: restoring {update.backupFile}. The agent is offline until it finishes.
+        </div>
+      )}
+
+      {update && update.status === 'done' && (
+        <div style={{ margin: '6px 0 10px' }}>
+          <Badge tone="success"><span style={{ fontSize: 10 }}>Updated from OpenClaw {update.fromVersion} to {update.toVersion}</span></Badge>
+          <div style={metaStyle}>
+            {when(update.finishedAtMs)}
+            {update.verification ? ` · ${update.verification.sessions} session(s) checked` : ''}
+            {update.backupFile ? ` · pre-update backup ${update.backupFile}` : ''}
+          </div>
+        </div>
+      )}
+
+      {update && (update.status === 'failed' || update.status === 'interrupted') && (
+        <div style={{ margin: '6px 0 10px' }}>
+          <Badge tone="danger">
+            <span style={{ fontSize: 10 }}>
+              Update to OpenClaw {update.toVersion} {update.status === 'interrupted' ? 'was interrupted' : 'failed'}
+            </span>
+          </Badge>
+          {update.error && <div style={metaStyle}>{update.error}</div>}
+          {update.verification && update.verification.lostEvents.length > 0 && (
+            <div style={metaStyle}>
+              {update.verification.lostEvents.map((l) => `${l.session}: ${l.before} → ${l.after}`).join(' · ')}
+            </div>
+          )}
+          {update.backupFile && <div style={metaStyle}>Pre-update backup: {update.backupFile}</div>}
+        </div>
+      )}
+
+      {update && update.status === 'rolled_back' && (
+        <div style={{ margin: '6px 0 10px' }}>
+          <Badge tone="warning"><span style={{ fontSize: 10 }}>Rolled back to OpenClaw {update.fromVersion}</span></Badge>
+          <div style={metaStyle}>{when(update.finishedAtMs)} · restored {update.backupFile}</div>
+        </div>
+      )}
+
+      {update && update.status === 'rollback_failed' && (
+        <div style={{ margin: '6px 0 10px' }}>
+          <Badge tone="danger"><span style={{ fontSize: 10 }}>Rollback to OpenClaw {update.fromVersion} failed</span></Badge>
+          {update.error && <div style={metaStyle}>{update.error}</div>}
+        </div>
+      )}
+
+      <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', marginTop: 6 }}>
+        {candidate && !active && (
+          <Button
+            variant="primary"
+            size="sm"
+            loading={busy === 'update'}
+            disabled={busy !== null || !running}
+            title={running ? undefined : 'Start the agent first: its data is counted while it runs'}
+            onClick={() => setConfirming('update')}
+          >
+            {busy === 'update' ? 'Starting…' : `Update to ${candidate.toVersion}`}
+          </Button>
+        )}
+        {canRollBack && update && (
+          <Button
+            variant="secondary"
+            size="sm"
+            loading={busy === 'rollback'}
+            disabled={busy !== null}
+            onClick={() => setConfirming('rollback')}
+          >
+            {busy === 'rollback' ? 'Starting…' : `Roll back to ${update.fromVersion}`}
+          </Button>
+        )}
+      </div>
+
+      {actionError && (
+        <div style={{ margin: '6px 0' }}>
+          <Badge tone="danger"><span style={{ fontSize: 10 }}>{actionError}</span></Badge>
+        </div>
+      )}
+
+      <ConfirmModal
+        open={confirming === 'update'}
+        onClose={() => setConfirming(null)}
+        onConfirm={() => { void run('update'); }}
+        title={candidate ? `Update to OpenClaw ${candidate.toVersion}?` : 'Update?'}
+        message={
+          'The agent goes offline, its volume is backed up while stopped, and it starts again on the new version, ' +
+          'which migrates its data. The migration cannot be undone in place: going back restores this backup, ' +
+          'and anything the agent does after the update is lost.'
+        }
+        confirmLabel="Update"
+        cancelLabel="Cancel"
+      />
+      <ConfirmModal
+        open={confirming === 'rollback'}
+        onClose={() => setConfirming(null)}
+        onConfirm={() => { void run('rollback'); }}
+        title={update?.fromVersion ? `Roll back to OpenClaw ${update.fromVersion}?` : 'Roll back?'}
+        message={
+          `The agent goes offline, its volume is replaced by the pre-update backup ${update?.backupFile ?? ''} ` +
+          'and it starts again on the previous version. Everything the agent did after that backup is lost.'
+        }
+        confirmLabel="Roll back"
+        cancelLabel="Cancel"
+        tone="danger"
+      />
+    </div>
+  );
+}

package/app/agents/create/PageClient.tsx

@@ -3,6 +3,8 @@
 import { useState, useMemo, useEffect } from 'react';
 import { useRouter } from 'next/navigation';
 import { Button, Input, TemplateOption } from '../../components/ui';
+import { OpenControlUiButton } from '../BrowserAccessSection';
+import { findAvailablePortBlock, validatePortInput } from '@/lib/agent-ports';
 
 interface TemplateInfo {
   id: string;
@@ -26,19 +28,6 @@ type Step = 'template' | 'config' | 'creating' | 'done' | 'error';
 
 const REV4A_PORT = 3740;
 
-function findFirstFreeBlock(usedPorts: number[]): number | null {
-  const used = new Set(usedPorts);
-  for (let base = 3700; base + 9 <= 3799; base += 10) {
-    if (base <= REV4A_PORT && REV4A_PORT <= base + 9) continue;
-    const block = Array.from({ length: 10 }, (_, i) => base + i);
-    if (block.every((p) => !used.has(p))) return base;
-  }
-  // Fallback beyond range
-  for (let base = 3800; ; base += 10) {
-    const block = Array.from({ length: 10 }, (_, i) => base + i);
-    if (block.every((p) => !used.has(p))) return base;
-  }
-}
 
 // ─── Toast ───
 function Toast({ message, type, onClose }: { message: string; type: 'success' | 'error'; onClose: () => void }) {
@@ -77,16 +66,9 @@ export default function CreatePageClient({ templates, models, usedNames, usedPor
   const [fallbacks] = useState<string[]>([]);
   const [submitting, setSubmitting] = useState(false);
   const [errorMsg, setErrorMsg] = useState('');
-  const [result, setResult] = useState<{ name: string; containerId: string; port: number; controlToken: string } | null>(null);
+  const [result, setResult] = useState<{ containerName: string; displayName: string; containerId: string; port: number } | null>(null);
   const [toast, setToast] = useState<{ message: string; type: 'success' | 'error' } | null>(null);
 
-  // The agent's Control UI URL, composed here rather than server-side: whatever
-  // hostname reached this dashboard is one that resolves and routes for this
-  // user, which the server can only guess at. Null until the create succeeds.
-  const controlUrl = result && typeof window !== 'undefined'
-    ? `http://${window.location.hostname}:${result.port}#token=${encodeURIComponent(result.controlToken)}`
-    : null;
-
   const handleSelectTemplate = (id: string) => {
     setSelectedTemplate(id);
     setAgentName('');
@@ -95,7 +77,7 @@ export default function CreatePageClient({ templates, models, usedNames, usedPor
       setPortRange('3700-3709');
     } else {
       // Simple client-side block finder
-      let block = findFirstFreeBlock(initialUsedPorts);
+      const block = initialUsedPorts.length ? findAvailablePortBlock(new Set(initialUsedPorts)) : null;
       setPortRange(block ? `${block}-${block + 9}` : '');
     }
   };
@@ -108,26 +90,9 @@ export default function CreatePageClient({ templates, models, usedNames, usedPor
   }, [agentName, usedNames]);
 
   const portError = useMemo(() => {
-    const v = portRange.trim();
-    if (!v) return '';
-    if (v.includes('-')) {
-      const m = v.match(/^(\d{1,5})-(\d{1,5})$/);
-      if (!m) return 'Use format: 3700-3709';
-      const start = parseInt(m[1], 10);
-      const end = parseInt(m[2], 10);
-      if (start < 1 || end > 65535) return 'Ports 1-65535';
-      if (end <= start) return 'End port must be greater than start';
-      for (let p = start; p <= end; p++) {
-        if (initialUsedPorts.includes(p)) return `Port ${p} is already in use`;
-        if (p === 3740) return 'Port 3740 is reserved';
-      }
-      return '';
-    }
-    const p = parseInt(v, 10);
-    if (isNaN(p) || p < 1 || p > 65535) return 'Port must be between 1 and 65535';
-    if (p === 3740) return 'Port 3740 is reserved';
-    if (initialUsedPorts.includes(p)) return 'Port is already in use';
-    return '';
+    if (!portRange.trim()) return '';
+    const res = validatePortInput(portRange, new Set(initialUsedPorts));
+    return res.valid ? '' : res.error;
   }, [portRange, initialUsedPorts]);
 
   const canProceed = (): boolean => {
@@ -394,14 +359,11 @@ export default function CreatePageClient({ templates, models, usedNames, usedPor
               Container: <span style={{ color: 'var(--text)', fontFamily: 'var(--font-mono-stack)' }}>{result.containerId}</span>
             </div>
             <div style={{ fontSize: 13, color: '#888', marginBottom: 4 }}>
-              Name: <span style={{ color: 'var(--text)' }}>{result.name}</span>
+              Name: <span style={{ color: 'var(--text)' }}>{result.displayName || result.containerName}</span>
+            </div>
+            <div style={{ marginTop: 8 }}>
+              <OpenControlUiButton agentId={result.containerName} label="Open Control UI ↗" />
             </div>
-            {controlUrl && (
-              <div style={{ fontSize: 13, color: '#888' }}>
-                Access: <a href={controlUrl} target="_blank" rel="noopener noreferrer"
-                  style={{ color: '#60a5fa', textDecoration: 'underline' }}>{controlUrl}</a>
-              </div>
-            )}
           </div>
           <div style={{ display: 'flex', gap: 12 }}>
             <Button variant="ghost" size="md" onClick={() => { setToast(null); router.push('/agents'); }} style={{ flex: 1 }}>

package/app/api/agents/[id]/backup/route.ts

@@ -1,36 +1,12 @@
 import { NextResponse } from 'next/server';
-import { execSync } from 'child_process';
 import { isValidAgentId } from '@/lib/container';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { runDocker } from '@/lib/agent-images';
 
 export const dynamic = 'force-dynamic';
 
 const BACKUP_VOLUME = 'rev4a-backups';
 
-/**
- * Determine the volume name for an agent by checking if it exists.
- */
-function agentVolumeName(agentName: string): string | null {
-  try {
-    const vols = execSync(
-      "docker volume ls --format '{{.Name}}'",
-      { encoding: 'utf-8', timeout: 5000 },
-    ).trim().split('\n').filter(Boolean);
-    const needle = `agent-${agentName}-data`;
-    return vols.includes(needle) ? needle : null;
-  } catch {
-    return null;
-  }
-}
-
-/** Format a timestamp as YYYY-MM-DD_HHmmssSSS (ms precision avoids same-second collisions). */
-function ts(): string {
-  const d = new Date();
-  const pad = (n: number) => String(n).padStart(2, '0');
-  const ms = String(d.getMilliseconds()).padStart(3, '0');
-  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}${ms}`;
-}
-
 /** Convert bytes to human-readable size. */
 function fmtSize(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
@@ -39,40 +15,6 @@ function fmtSize(bytes: number): string {
   return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
 }
 
-/**
- * POST /api/agents/[id]/backup
- * Create a backup of the agent's persistent volume.
- */
-export async function POST(request: Request,
-  { params }: { params: Promise<{ id: string }> },
-): Promise<NextResponse> {
-  const denied = await requireAuthJWT(request); if (denied) return denied as any;
-  try {
-    const { id } = await params;
-    if (!id) return NextResponse.json({ error: 'Agent name required' }, { status: 400 });
-    if (!isValidAgentId(id)) return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
-
-    const volume = agentVolumeName(id);
-    if (!volume) {
-      return NextResponse.json({ error: `No persistent volume found for agent '${id}'` }, { status: 404 });
-    }
-
-    const filename = `agent-${id}-${ts()}.tar.gz`;
-
-    execSync(
-      `docker run --rm ` +
-      `-v ${volume}:/source:ro ` +
-      `-v ${BACKUP_VOLUME}:/backup ` +
-      `alpine sh -c 'tar czf /backup/${filename} --exclude=.npm/_cacache -C /source . && chmod 644 /backup/${filename}'`,
-      { timeout: 60000, stdio: 'pipe' },
-    );
-
-    return NextResponse.json({ success: true, file: filename });
-  } catch (e: unknown) {
-    return NextResponse.json({ error: (e as Error).message }, { status: 500 });
-  }
-}
-
 interface BackupFile {
   name: string;
   size: string;
@@ -96,12 +38,22 @@ export async function GET(request: Request,
 
     const prefix = `agent-${id}-`;
 
-    const raw = execSync(
-      `docker run --rm -v ${BACKUP_VOLUME}:/backup alpine sh -c 'stat -c "%s %Y %n" /backup/${prefix}*.tar.gz 2>/dev/null || true'`,
-      { timeout: 10000, encoding: 'utf-8' },
-    ).trim();
+    // $PREFIX stays unquoted so the shell expands the glob; the id is validated, so
+    // the pattern carries no shell metacharacters. The archive name reaches the
+    // command through the environment, never as shell syntax.
+    const lines: string[] = [];
+    let failed: unknown = null;
+    await runDocker(
+      ['run', '--rm', '-v', `${BACKUP_VOLUME}:/backup`, 'alpine', 'sh', '-c',
+        'stat -c "%s %Y %n" /backup/$PREFIX*.tar.gz 2>/dev/null || true'],
+      { timeoutMs: 30_000, env: { PREFIX: prefix }, onLine: (line) => lines.push(line.trim()) },
+    ).catch((e) => { failed = e; });
+    // A failed list must not read as "no backups": under load the container start has
+    // been seen to pass 10 s, and an empty array would look like an empty volume.
+    if (failed) {
+      return NextResponse.json({ error: `Could not list backups: ${(failed as Error).message}` }, { status: 502 });
+    }
 
-    const lines = raw.split('\n').filter(Boolean);
     const backups: BackupFile[] = [];
 
     for (const line of lines) {
@@ -138,6 +90,10 @@ export async function GET(request: Request,
 /**
  * DELETE /api/agents/[id]/backup?file=agent-xxx-2026-07-11_2115.tar.gz
  * Remove a specific backup file.
+ *
+ * The file name reaches the container through its environment, never as shell
+ * syntax, and the name is validated against a strict character set first: only
+ * `agent-<id>-<timestamp>.tar.gz` shapes are accepted.
  */
 export async function DELETE(request: Request,
   { params }: { params: Promise<{ id: string }> },
@@ -152,14 +108,15 @@ export async function DELETE(request: Request,
     const file = url.searchParams.get('file');
     if (!file) return NextResponse.json({ error: 'file query param required' }, { status: 400 });
 
-    // Safety: only allow deleting agent-specific files, reject path traversal
-    if (!file.startsWith(`agent-${id}-`) || !file.endsWith('.tar.gz') || file.includes('/') || file.includes('..')) {
+    // Only this agent's archives, and only those shapes; no separators, no `..`,
+    // nothing that could carry shell syntax.
+    if (!file.startsWith(`agent-${id}-`) || !/^[A-Za-z0-9._-]+\.tar\.gz$/.test(file)) {
       return NextResponse.json({ error: 'Invalid backup file name' }, { status: 400 });
     }
 
-    execSync(
-      `docker run --rm -v ${BACKUP_VOLUME}:/backup alpine sh -c 'rm -f /backup/${file}'`,
-      { timeout: 10000, stdio: 'pipe' },
+    await runDocker(
+      ['run', '--rm', '-v', `${BACKUP_VOLUME}:/backup`, 'alpine', 'sh', '-c', 'rm -f "/backup/$FILE"'],
+      { timeoutMs: 30_000, env: { FILE: file } },
     );
 
     return NextResponse.json({ success: true });

package/app/api/agents/[id]/channels/pairing/route.ts

@@ -15,7 +15,7 @@ export async function GET(
   const denied = await requireAuthJWT(request); if (denied) return denied as any;
   const { id } = await params;
   const channel = getChannel(request);
-  const result = getPairings(id, channel);
+  const result = await getPairings(id, channel);
   return NextResponse.json(result);
 }
 
@@ -34,7 +34,7 @@ export async function POST(
       return NextResponse.json({ error: 'Pairing code is required' }, { status: 400 });
     }
 
-    const result = approvePairing(id, body.code.trim(), channel);
+    const result = await approvePairing(id, body.code.trim(), channel);
 
     if (!result.success) {
       return NextResponse.json({ error: result.error }, { status: 404 });
@@ -59,7 +59,7 @@ export async function DELETE(
     return NextResponse.json({ error: 'senderId query param is required' }, { status: 400 });
   }
 
-  const result = revokePairing(id, senderId, channel);
+  const result = await revokePairing(id, senderId, channel);
 
   if (!result.success) {
     return NextResponse.json({ error: result.error }, { status: 404 });

package/app/api/agents/[id]/channels/telegram/route.ts

@@ -18,7 +18,7 @@ export async function PUT(
       return NextResponse.json({ error: 'botToken is required' }, { status: 400 });
     }
 
-    const result = setTelegramConfig(id, {
+    const result = await setTelegramConfig(id, {
       botToken: body.botToken.trim(),
       dmPolicy: body.dmPolicy,
       allowFrom: body.allowFrom,
@@ -40,7 +40,7 @@ export async function DELETE(request: NextRequest,
   const denied = await requireAuthJWT(request); if (denied) return denied as any;
   const { id } = await params;
 
-  const result = removeTelegram(id);
+  const result = await removeTelegram(id);
 
   if (!result.success) {
     return NextResponse.json({ error: result.error }, { status: 404 });

package/app/api/agents/[id]/cold-backup/route.ts

@@ -0,0 +1,56 @@
+/**
+ * Cold backup of one agent's volume (lib/cold-backup.ts).
+ *
+ *   POST    start: the agent is stopped, archived, verified and started again if it
+ *           was running. 202 `{ started: true, file }`; the work continues in a helper container.
+ *   GET     `{ backup }`: the running or last job, with progress; null when none.
+ *   DELETE  cancel the running job: the partial archive is removed and the agent
+ *           restarted if it was running.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { isValidAgentId } from '@/lib/container';
+import { ColdBackupBusyError, cancelColdBackup, coldBackupStatus, startColdBackup } from '@/lib/cold-backup';
+import { agentBusyReason } from '@/lib/agent-busy';
+
+export const dynamic = 'force-dynamic';
+
+type Ctx = { params: Promise<{ id: string }> };
+
+async function agentId(ctx: Ctx): Promise<string | NextResponse> {
+  const { id } = await ctx.params;
+  return isValidAgentId(id) ? id : NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
+}
+
+export async function POST(request: NextRequest, ctx: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const id = await agentId(ctx);
+  if (id instanceof NextResponse) return id;
+  // One source for every long operation: an update, recreate, restore, edit or backup.
+  const busy = await agentBusyReason(id);
+  if (busy) return NextResponse.json({ error: busy }, { status: 409 });
+  try {
+    const { file } = await startColdBackup(id, { kind: 'manual' });
+    return NextResponse.json({ started: true, file }, { status: 202 });
+  } catch (e) {
+    const status = e instanceof ColdBackupBusyError ? 409 : /No container|No persistent volume/.test((e as Error).message) ? 404 : 500;
+    return NextResponse.json({ error: (e as Error).message }, { status });
+  }
+}
+
+export async function GET(request: NextRequest, ctx: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const id = await agentId(ctx);
+  if (id instanceof NextResponse) return id;
+  return NextResponse.json({ backup: await coldBackupStatus(id) }, { headers: { 'Cache-Control': 'no-store' } });
+}
+
+export async function DELETE(request: NextRequest, ctx: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const id = await agentId(ctx);
+  if (id instanceof NextResponse) return id;
+  const cancelled = await cancelColdBackup(id);
+  return cancelled
+    ? NextResponse.json({ cancelled: true })
+    : NextResponse.json({ error: 'No backup of this agent is running' }, { status: 409 });
+}