@flame0510/project-aether 1.3.0 → 1.4.0

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

@@ -1,135 +1,55 @@
-import { type NextRequest } from "next/server";
 /**
  * GET /api/agents/image-status
  *
- * Reports whether the openclaw-agent-base image is present, whether a download
- * is in flight, and whether a newer image exists in the registry.
+ * Which OpenClaw versions of the agent base image are downloaded, whether the
+ * registry publishes a newer supported version, and whether a download is running.
  *
- * The four fields cost wildly different amounts, which is what makes this route
- * worth structuring carefully. ImageDownloadBanner polls it every 2s to animate
- * download progress, so anything slow in here is paid over and over:
- *
- *   downloading   in-memory flag                          free
- *   error         local                                   free
- *   exists        one `docker image inspect`              ~0.5s
- *   needsUpdate   `docker manifest inspect` over the net  ~3.4s
- *
- * The route used to compute all of them, synchronously, on every poll — a 2s
- * interval driving a ~5s blocking call, so the whole server sat frozen for as
- * long as the agents page stayed open. It also ran `docker version` three times
- * per request (once inside each helper) just to ask whether Docker was up, at
- * ~2s a call, and inspected the same image three times over.
- *
- * Now: Docker liveness comes from the socket check in lib/docker-socket (a
- * cached filesystem stat), the image is inspected once, everything is async, and
- * the registry lookup — the only genuinely expensive part — is cached. The base
- * image changes when a release is published, not every two seconds.
+ * ImageDownloadBanner polls this every 2 s. The local part is two Docker API calls;
+ * the registry lookup is cached for ten minutes and shared by concurrent requests
+ * (lib/agent-images.ts), so polling does not hit the network.
  */
-import { NextResponse } from 'next/server';
-import { execFile } from 'child_process';
-import { promisify } from 'util';
-import { getIsDownloading } from '@/lib/buildAgentImage';
+import { NextResponse, type NextRequest } from 'next/server';
+import { getDownloadingVersion, getIsDownloading } from '@/lib/buildAgentImage';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
 import { dockerAvailable } from '@/lib/docker-socket';
-
-const execFileAsync = promisify(execFile);
+import { listLocalAgentImages, localSupportedVersions, remoteSupportedVersions, type LocalAgentImage } from '@/lib/agent-images';
+import { compareVersions } from '@/lib/agent-versions';
 
 export const dynamic = 'force-dynamic';
 
-const REGISTRY_IMAGE = 'ghcr.io/flame0510/rev4a/openclaw-agent-base:latest';
-const LOCAL_IMAGE = 'openclaw-agent-base:latest';
-const REGISTRY_PREFIX = 'ghcr.io/flame0510/rev4a/openclaw-agent-base@';
-
-/**
- * How long a registry lookup is reused. Long enough that a 2s poll doesn't hit
- * the network, short enough that a freshly published base image surfaces on its
- * own. The cost of being stale here is a banner appearing a few minutes late.
- */
-const REMOTE_TTL_MS = 10 * 60 * 1000;
-
-let remoteCache: { digest: string | null; at: number } | null = null;
-/** Shared across concurrent requests so a burst of polls triggers one lookup. */
-let remoteInFlight: Promise<string | null> | null = null;
-
-/** The local image's ID and its registry digest, from a single inspect. */
-async function inspectLocalImage(): Promise<{ id: string; registryDigest: string | null } | null> {
-  try {
-    const { stdout } = await execFileAsync(
-      'docker',
-      ['image', 'inspect', LOCAL_IMAGE, '--format', '{{json .}}'],
-      { encoding: 'utf-8', timeout: 5000 },
-    );
-    const info = JSON.parse(stdout) as { Id?: string; RepoDigests?: string[] };
-    const fromRegistry = (info.RepoDigests ?? []).find((d) => d.startsWith(REGISTRY_PREFIX));
-    return {
-      id: info.Id ?? '',
-      registryDigest: fromRegistry ? fromRegistry.split('@')[1] ?? null : null,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/** Manifest digest of the published image, cached for REMOTE_TTL_MS. */
-async function getRemoteDigest(): Promise<string | null> {
-  if (remoteCache && Date.now() - remoteCache.at < REMOTE_TTL_MS) return remoteCache.digest;
-  if (remoteInFlight) return remoteInFlight;
-
-  remoteInFlight = (async () => {
-    try {
-      const { stdout } = await execFileAsync(
-        'docker',
-        ['manifest', 'inspect', REGISTRY_IMAGE, '--verbose'],
-        { encoding: 'utf-8', timeout: 15000 },
-      );
-      const manifest = JSON.parse(stdout) as { Descriptor?: { digest?: string } };
-      // The descriptor digest is what RepoDigests can be compared against;
-      // config.digest is a different hash entirely.
-      return manifest?.Descriptor?.digest ?? null;
-    } catch {
-      return null;
-    }
-  })();
-
-  try {
-    const digest = await remoteInFlight;
-    remoteCache = { digest, at: Date.now() };
-    return digest;
-  } finally {
-    remoteInFlight = null;
-  }
-}
-
 export async function GET(request: NextRequest): Promise<NextResponse> {
   const denied = await requireAuthJWT(request);
   if (denied) return denied;
 
-  const downloading = getIsDownloading();
+  const base = { downloading: getIsDownloading(), downloadingVersion: getDownloadingVersion() };
 
   if (!dockerAvailable()) {
-    return NextResponse.json({ exists: false, needsUpdate: true, downloading, localId: null });
+    return NextResponse.json({
+      ...base, exists: false, needsUpdate: true, localVersions: [], newestLocal: null, available: null, registryReachable: false,
+    });
   }
 
-  const local = await inspectLocalImage();
-  if (!local) {
-    return NextResponse.json({ exists: false, needsUpdate: true, downloading, localId: null });
+  let images: LocalAgentImage[] = [];
+  try {
+    images = await listLocalAgentImages();
+  } catch {
+    // Docker answered nothing usable: report no local image.
   }
+  const localVersions = localSupportedVersions(images);
+  const newestLocal = localVersions[0] ?? null;
 
-  // A cached registry digest answers immediately; a cold one costs a network
-  // round trip, but only once per TTL rather than once per poll.
-  const remoteDigest = await getRemoteDigest();
-
-  let needsUpdate = false;
-  if (remoteDigest) {
-    // No registry digest locally means the image was built here and never
-    // pulled, so it can't be compared — treat it as updatable.
-    needsUpdate = local.registryDigest ? local.registryDigest !== remoteDigest : true;
-  }
+  const remote = await remoteSupportedVersions();
+  const available = remote?.find(
+    (v) => !localVersions.includes(v) && (!newestLocal || compareVersions(v, newestLocal) > 0),
+  ) ?? null;
 
   return NextResponse.json({
-    exists: true,
-    needsUpdate,
-    downloading,
-    localId: local.id || null,
+    ...base,
+    exists: newestLocal !== null,
+    needsUpdate: newestLocal === null || available !== null,
+    localVersions,
+    newestLocal,
+    available,
+    registryReachable: remote !== null,
   });
 }

package/app/api/agents/route.ts

@@ -1,9 +1,8 @@
 import { NextResponse, type NextRequest } from 'next/server';
-import * as fs from 'fs';
-import * as path from 'path';
-import { AGENTS_TOKEN_FILE } from '@/lib/rev4a-paths';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
 import { dockerAvailable, dockerFetch } from '@/lib/docker-socket';
+import { containerOpenClawVersion, listLocalAgentImages, newestLocalSupportedVersion, type LocalAgentImage } from '@/lib/agent-images';
+import { LOCAL_IMAGE_REPOSITORY, compareVersions } from '@/lib/agent-versions';
 
 export const dynamic = 'force-dynamic';
 
@@ -21,14 +20,15 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
       '/containers/json?all=true&filters={"label":["AGENT_ID"]}',
     );
 
-    // Current image ID — used to detect outdated containers
-    let currentImageId = '';
+    // Local agent images: each container's OpenClaw version, and the newest supported
+    // version downloaded, which decides `updateAvailable`.
+    let images: LocalAgentImage[] = [];
     try {
-      const imageInspect = await dockerFetch('GET', '/images/openclaw-agent-base:latest/json');
-      currentImageId = imageInspect.Id || '';
+      images = await listLocalAgentImages();
     } catch {
-      // Image doesn't exist yet — all containers are fine
+      // No image list: versions come from inside running containers only.
     }
+    const newestLocal = newestLocalSupportedVersion(images);
 
     const agents = await Promise.all(
       containers.map(async (c: any) => {
@@ -36,7 +36,6 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
         let ip: string | null = null;
         let created: string | null = null;
         let env: string[] = [];
-        let authToken: string | null = null;
         let controlPort: string | null = null;
         let portBindings: Record<string, Array<{ HostIp: string; HostPort: string }>> | null = null;
 
@@ -59,42 +58,9 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
           // Ports from inspect (HostConfig) — works even when container is stopped
           portBindings = inspect.HostConfig?.PortBindings || null;
 
-          // Read auth token — always prefer the shared agents-token.json (user-managed)
-          try {
-            const tokenRaw = fs.readFileSync(
-              AGENTS_TOKEN_FILE,
-              'utf-8'
-            );
-            const tokenData = JSON.parse(tokenRaw);
-            if (tokenData.token) {
-              authToken = tokenData.token;
-            }
-          } catch {
-            // agents-token.json unavailable
-          }
-
-          // Fallback when the shared file is missing: the container's own token,
-          // taken from the inspect data already fetched above.
-          //
-          // This used to `docker exec … grep OPENCLAW_GATEWAY_TOKEN /root/….env`
-          // — a path containing a literal U+2026 ellipsis, so not a path at all.
-          // Correcting the character wouldn't have helped: agent containers have
-          // no .env file, and no file under /root/ holds that variable (verified
-          // across the production fleet). The token exists only in the container
-          // environment, which is right here in Config.Env. So the fallback spawned
-          // a blocking process per agent to read a file that cannot exist, failed
-          // silently, and left every "Open" button without its token — while the
-          // value sat in memory, already fetched.
-          if (!authToken) {
-            const fromEnv = ((inspect.Config?.Env || []) as string[])
-              .find((e) => e.startsWith('OPENCLAW_GATEWAY_TOKEN='));
-            const token = fromEnv?.slice('OPENCLAW_GATEWAY_TOKEN='.length).trim();
-            if (token && token !== 'undefined') authToken = token;
-          }
-
           // The host port mapped to the agent's Control UI (container port 3000).
-          // Only the port is returned: the browser composes the full URL, because
-          // only the browser knows which hostname actually reaches this machine.
+          // No link and no token are returned: the Open buttons go through
+          // /api/agents/[id]/open-control-ui, which builds the link server-side.
           // Read from portBindings (works on a stopped container) with a fallback
           // to c.Ports, which is only populated while running.
           const port3000Binding = portBindings?.['3000/tcp'];
@@ -109,7 +75,17 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
         // Falls back to 'custom' if not set (agent created before this feature).
         const image: string = c.Image || '';
         let template: string | null = null;
-        if (image.startsWith('openclaw-agent-base')) {
+        // Every container here carries AGENT_ID, so its version is looked up even when
+        // its image is not tagged `openclaw-agent-base` (an image left untagged, or
+        // pinned by id). The image name alone would miss those.
+        const openclawVersion = await containerOpenClawVersion(
+          { name: (c.Names?.[0] || '').replace(/^\//, ''), imageId: c.ImageID || '', running: c.State === 'running' },
+          images,
+        );
+        const isAgentBase = image.startsWith(LOCAL_IMAGE_REPOSITORY)
+          || images.some((img) => img.id === c.ImageID)
+          || openclawVersion !== null;
+        if (isAgentBase) {
           const templateLine = env.find((e: string) => e.startsWith('AGENT_TEMPLATE='));
           template = templateLine ? templateLine.split('=').slice(1).join('=') : 'custom';
         }
@@ -147,10 +123,10 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
           created,
           env,
           controlPort,
-          authToken,
-          // Flag as outdated when the container's image differs from the current base image.
-          // We compare raw ImageID digests — no fragile name-based filtering.
-          imageOutdated: currentImageId ? c.ImageID !== currentImageId : false,
+          openclawVersion,
+          // A newer supported OpenClaw version is downloaded. Recreate keeps the agent's
+          // version; moving to the newer one is a separate, backed-up update.
+          updateAvailable: !!(openclawVersion && newestLocal && compareVersions(newestLocal, openclawVersion) > 0),
         };
       }),
     );

package/app/api/agents/token/route.ts

@@ -3,6 +3,7 @@ import * as fs from 'fs';
 import { NextResponse, type NextRequest } from 'next/server';
 import { AGENTS_TOKEN_FILE } from '@/lib/rev4a-paths';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { agentBusyReason } from '@/lib/agent-busy';
 
 export const dynamic = 'force-dynamic';
 
@@ -57,37 +58,59 @@ export async function PUT(request: NextRequest): Promise<NextResponse> {
     fs.writeFileSync(AGENTS_TOKEN_FILE, JSON.stringify(payload, null, 2));
 
     let containersUpdated = 0;
-    let containerNames: string[] = [];
+    /** Containers left alone because an operation is running on them. */
+    const skipped: string[] = [];
+    /** Containers that could not be updated, with the reason. */
+    const failed: { container: string; error: string }[] = [];
+    let containers: { name: string; agentId: string }[] = [];
 
     try {
       const raw = execSync(
-        `docker ps --filter "label=AGENT_ID" --format "{{.Names}}"`,
+        `docker ps --filter "label=AGENT_ID" --format '{{.Names}} {{.Label "AGENT_ID"}}'`,
         { encoding: 'utf-8', timeout: 5000 },
       ).trim();
-      containerNames = raw ? raw.split('\n').map((name) => name.trim()).filter(Boolean) : [];
+      containers = raw
+        ? raw.split('\n').map((line) => {
+          const [name, agentId] = line.trim().split(/\s+/);
+          return { name: (name ?? '').trim(), agentId: (agentId ?? '').trim() };
+        }).filter((c) => c.name)
+        : [];
     } catch {
-      containerNames = [];
+      containers = [];
     }
 
-    for (const containerName of containerNames) {
+    for (const { name, agentId } of containers) {
       try {
+        // Restarting an agent mid-update, mid-recreate, mid-restore or mid-edit would cut
+        // the operation in half: leave it and say so.
+        if (agentId && (await agentBusyReason(agentId))) {
+          skipped.push(name);
+          continue;
+        }
         // Write token to /root/.agent-token (entrypoint reads this, overrides env var)
         execSync(
-          `docker exec ${shellQuote(containerName)} sh -c 'echo ${shellQuote(token)} > /root/.agent-token'`,
+          `docker exec ${shellQuote(name)} sh -c 'echo ${shellQuote(token)} > /root/.agent-token'`,
           { encoding: 'utf-8', timeout: 10000 },
         );
         // Restart to pick up new token
-        execSync(`docker restart ${shellQuote(containerName)}`, {
+        execSync(`docker restart ${shellQuote(name)}`, {
           encoding: 'utf-8',
           timeout: 20000,
         });
         containersUpdated += 1;
-      } catch {
-        // Skip failed containers and continue syncing the rest.
+      } catch (e) {
+        // Report the failure instead of swallowing it: a token that reached only some
+        // agents used to look like a full success.
+        failed.push({ container: name, error: (e as Error)?.message ?? String(e) });
       }
     }
 
-    return NextResponse.json({ success: true, containersUpdated });
+    return NextResponse.json({
+      success: failed.length === 0,
+      containersUpdated,
+      ...(skipped.length ? { skipped } : {}),
+      ...(failed.length ? { failed } : {}),
+    });
   } catch (e: unknown) {
     return NextResponse.json(
       { success: false, error: (e as Error).message || 'Unknown error' },

package/app/api/assistant/route.ts

@@ -25,8 +25,8 @@ const PAGE_CONTEXT: Record<string, PageContext> = {
   '/agents': {
     title: 'Agents',
     description: 'List of all Docker containers that run OpenClaw agents. Shows status (running/exited/paused), image, ports, IP, and creation time. Includes a top banner for the agent base image status: yellow warning when outdated or missing, animated progress bar when downloading from registry.',
-    actions: ['Filter by status: all, running, or exited', 'Click an agent to see its details (environment variables, auth token, backups, Telegram channels, and the Model section that sets its primary model and fallbacks)', 'Create a new agent using the "Create Agent" button', 'Download the agent base image when the banner shows it missing or outdated'],
-    hints: 'The status bullet tells you at a glance if an agent is running (green), exited (red), or paused (yellow). The base image banner shows when an updated version is available on the registry — download to pick up CLI updates.',
+    actions: ['Filter by status: all, running, or exited', 'Click an agent to see its details (environment variables, backups, Telegram channels, and the Model section that sets its primary model and fallbacks)', 'Create a new agent using the "Create Agent" button', 'Download the agent base image when the banner shows it missing or outdated'],
+    hints: 'The status bullet tells you at a glance if an agent is running (green), exited (red), or paused (yellow). The base image banner shows when a newer supported version is published on the registry — downloading makes it available to create and update agents on; it changes no agent by itself.',
   },
   '/agents/create': {
     title: 'Create Agent',

package/app/api/gateway/agent/route.ts

@@ -8,6 +8,7 @@
  *   { "containerName": "openclaw-atlas", "model": "rev4a/deepseek-flash", "fallbacks": ["rev4a/deepseek-v4-pro"] }
  */
 import { NextRequest, NextResponse } from 'next/server';
+import { agentBusyReason } from '@/lib/agent-busy';
 import { execSync } from 'child_process';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
 
@@ -90,6 +91,19 @@ export async function PUT(request: NextRequest) {
       return NextResponse.json({ status: 'error', error: 'model is required' }, { status: 400 });
     }
 
+    // Refuse while a long operation is running on this agent: the write would race the
+    // recreate/migration that is replacing the container underneath it.
+    try {
+      const agentId = execSync(
+        `docker inspect --format '{{index .Config.Labels "AGENT_ID"}}' ${safeContainer}`,
+        { encoding: 'utf-8', timeout: 5000 },
+      ).trim();
+      if (agentId) {
+        const busy = await agentBusyReason(agentId);
+        if (busy) return NextResponse.json({ status: 'error', error: busy }, { status: 409 });
+      }
+    } catch { /* no container or no label: the rest of the route reports it */ }
+
     // Read current config
     const raw = readFileFromContainer(safeContainer, '/root/.openclaw/openclaw.json');
     if (!raw) {

package/app/api/gateway/provider/balance/route.ts

@@ -7,7 +7,7 @@
  * Supported providers: deepseek, openrouter, glm
  */
 import { NextRequest, NextResponse } from 'next/server';
-import { fetchProviderBalance, type BalanceProvider } from '@/lib/provider-balance';
+import { fetchProviderBalance, BalanceUnsupportedError, type BalanceProvider } from '@/lib/provider-balance';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
 
 export const dynamic = 'force-dynamic';
@@ -33,6 +33,9 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
     return NextResponse.json({ provider, ...result });
   } catch (e: unknown) {
     const message = e instanceof Error ? e.message : String(e);
-    return NextResponse.json({ provider, error: message }, { status: 502 });
+    // A permanent "no balance API for this account" is reported distinctly, so
+    // the UI can hide the badge instead of offering a retry that never works.
+    const reason = e instanceof BalanceUnsupportedError ? 'no-balance-api' : undefined;
+    return NextResponse.json({ provider, error: message, ...(reason && { reason }) }, { status: 502 });
   }
 }

package/app/api/gateway/sync.ts

@@ -19,6 +19,11 @@ import { readProviderKeys } from './provider/keys';
 import { bundledCatalogueStatus, loadOfferedModels, type ModelConfigEntry } from '@/lib/model-catalogue';
 import { singleFileFromTar } from '@/lib/container-file';
 import { detectProviderGatewayUrl } from '@/lib/docker-utils';
+import { isSupportedVersion, modelInputFor, parseOpenClawVersion } from '@/lib/agent-versions';
+import { activeUpdateAgentIds } from '@/lib/agent-update-state';
+import { activeRecreateAgentIds } from '@/lib/agent-recreate-state';
+import { activeRestoreAgentIds } from '@/lib/agent-restore-state';
+import { activeEditAgentIds } from '@/lib/agent-edit-state';
 
 const PROVIDER_GATEWAY_BASE_URL = detectProviderGatewayUrl();
 
@@ -31,19 +36,57 @@ const PROVIDER_GATEWAY_BASE_URL = detectProviderGatewayUrl();
  * OpenClaw `input` array. Filters out values not in the allowed set
  * (text | image | video | audio).
  */
-const ALLOWED_INPUT = new Set(['text', 'image', 'video', 'audio']);
-
-function modalityToInput(modality: string): string[] {
+/**
+ * Model `input` values an agent's OpenClaw version accepts. The list is per version
+ * (lib/agent-versions.json): 7.1-2 knows only `text | image`, and one value it does not
+ * know invalidates the whole generated catalogue ("model catalog load issue").
+ */
+function modalityToInput(modality: string, version?: string | null): string[] {
+  const allowed = new Set(modelInputFor(version));
   const arrowIdx = modality.indexOf('->');
   const left = arrowIdx >= 0 ? modality.slice(0, arrowIdx) : modality;
-  return left.split('+').map((s) => s.trim()).filter((s) => ALLOWED_INPUT.has(s));
+  return left.split('+').map((s) => s.trim()).filter((s) => allowed.has(s));
+}
+
+/** Where the image entrypoint records the version an agent last started on. */
+const LAST_VERSION_PATH = '/root/.openclaw/.last-version';
+
+/**
+ * The OpenClaw version a container runs, for its model `input` list. Best-effort and
+ * synchronous: the image tag when it names a version, else the `.last-version` file the
+ * entrypoint writes (through `docker exec` when running, `docker cp` when stopped).
+ * Null when nothing says — the caller then falls back to the newest version's list.
+ */
+function containerVersionSync(name: string): string | null {
+  try {
+    const image = execFileSync('docker', ['inspect', '--format', '{{.Config.Image}}', name], {
+      timeout: 5000, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    const fromTag = parseOpenClawVersion(image);
+    if (fromTag && isSupportedVersion(fromTag)) return fromTag;
+  } catch { /* no such container or no image: fall through */ }
+  try {
+    const raw = execFileSync('docker', ['exec', name, 'cat', LAST_VERSION_PATH], {
+      timeout: 5000, maxBuffer: 64 * 1024, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const running = parseOpenClawVersion(raw);
+    if (running && isSupportedVersion(running)) return running;
+  } catch { /* not running or no file: try the stopped path */ }
+  try {
+    const file = singleFileFromTar(execFileSync('docker', ['cp', `${name}:${LAST_VERSION_PATH}`, '-'], {
+      timeout: 5000, maxBuffer: 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+    }));
+    const stopped = parseOpenClawVersion(file.body.toString('utf-8'));
+    if (stopped && isSupportedVersion(stopped)) return stopped;
+  } catch { /* nothing to read */ }
+  return null;
 }
 
-function getActiveRev4aModels(): { id: string; name: string; input?: string[] }[] {
+function getActiveRev4aModels(version?: string | null): { id: string; name: string; input?: string[] }[] {
   return loadOfferedModels()
     .map((m) => {
       const entry: { id: string; name: string; input?: string[] } = { id: m.id, name: m.name };
-      if (m.modality) entry.input = modalityToInput(m.modality);
+      if (m.modality) entry.input = modalityToInput(m.modality, version);
       return entry;
     });
 }
@@ -56,7 +99,23 @@ function firstLine(e: unknown): string {
 }
 
 /** A container carrying an AGENT_ID label, and whether it is running. */
-interface AgentContainer { name: string; running: boolean }
+interface AgentContainer { name: string; running: boolean; agentId: string }
+
+/**
+ * AGENT_IDs whose volume is being archived by a cold backup (lib/cold-backup.ts). Their
+ * config must not change while tar reads the volume; the next sync catches them up.
+ */
+function agentsUnderBackup(): Set<string> {
+  try {
+    const raw = execSync(
+      `docker ps --filter "label=rev4a.backup.agent" --format '{{.Label "rev4a.backup.agent"}}'`,
+      { timeout: 5000, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] },
+    ).trim();
+    return new Set(raw ? raw.split('\n').map((s) => s.trim()).filter(Boolean) : []);
+  } catch {
+    return new Set();
+  }
+}
 
 /**
  * Every container carrying an AGENT_ID label, running or stopped.
@@ -74,7 +133,7 @@ function getAgentContainers(): AgentContainer[] {
   let raw: string;
   try {
     raw = execSync(
-      `docker ps -a --filter "label=AGENT_ID" --format '{{.Names}}\t{{.State}}'`,
+      `docker ps -a --filter "label=AGENT_ID" --format '{{.Names}}\t{{.State}}\t{{.Label "AGENT_ID"}}'`,
       { timeout: 5000, maxBuffer: 64 * 1024, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] },
     ).trim();
   } catch (e) {
@@ -83,8 +142,8 @@ function getAgentContainers(): AgentContainer[] {
   if (!raw) return [];
   return raw.split('\n')
     .map((line) => {
-      const [name, state] = line.split('\t');
-      return { name: (name ?? '').trim(), running: (state ?? '').trim() === 'running' };
+      const [name, state, agentId] = line.split('\t');
+      return { name: (name ?? '').trim(), running: (state ?? '').trim() === 'running', agentId: (agentId ?? '').trim() };
     })
     .filter((c) => c.name);
 }
@@ -184,10 +243,10 @@ function writeContainerJson(container: AgentContainer, remotePath: string, data:
  * Shared between the create route and syncAllAgents — single source of truth
  * for the provider block injected into every agent container.
  */
-export function buildRev4aProviderConfig(): { baseUrl: string; apiKey: string; api: string; models: { id: string; name: string; input?: string[] }[] } {
+export function buildRev4aProviderConfig(version?: string | null): { baseUrl: string; apiKey: string; api: string; models: { id: string; name: string; input?: string[] }[] } {
   const providerKeys = readProviderKeys();
   const rev4aApiKey = providerKeys['rev4a'] || '';
-  const activeModels = getActiveRev4aModels();
+  const activeModels = getActiveRev4aModels(version);
   return {
     baseUrl: PROVIDER_GATEWAY_BASE_URL,
     apiKey: rev4aApiKey,
@@ -211,7 +270,8 @@ export function patchRev4aProvider(container: string): void {
   if (bundledCatalogueStatus() === 'unavailable') {
     throw new Error('models.config.json could not be read; models.providers.rev4a left unchanged');
   }
-  const input = JSON.stringify({ models: { providers: { rev4a: buildRev4aProviderConfig() } } });
+  // The agent's own version: an older release rejects `input` values it does not know.
+  const input = JSON.stringify({ models: { providers: { rev4a: buildRev4aProviderConfig(containerVersionSync(container)) } } });
   execFileSync('docker', ['exec', '-i', container, 'sh', '-c', 'openclaw config patch --stdin'], {
     timeout: 15000,
     stdio: 'pipe',
@@ -293,9 +353,32 @@ export function syncAllAgents(): SyncOutcome {
   }
 
   outcome.total = containers.length;
+  const underBackup = agentsUnderBackup();
+  // Any long operation replaces or rewrites the container/config: skip the agent.
+  let busyAgents = new Set<string>();
+  try {
+    busyAgents = new Set([
+      ...activeUpdateAgentIds(),
+      ...activeRecreateAgentIds(),
+      ...activeRestoreAgentIds(),
+      ...activeEditAgentIds(),
+    ]);
+  } catch {
+    // No operation state readable: nothing to skip on that account.
+  }
   for (const container of containers) {
+    if (busyAgents.has(container.agentId)) {
+      outcome.failed.push({ container: container.name, error: 'an operation of this agent is running; it applies Rev4a config itself' });
+      continue;
+    }
+    if (underBackup.has(container.agentId)) {
+      outcome.failed.push({ container: container.name, error: 'a cold backup of this agent is running; sync again once it finishes' });
+      continue;
+    }
     try {
-      syncContainer(container, rev4aProviderConfig);
+      // Per agent: the `input` list follows the version that agent runs, so a 7.x
+      // release never receives a modality value it would reject.
+      syncContainer(container, buildRev4aProviderConfig(containerVersionSync(container.name)));
       outcome.synced.push(container.name);
       if (!container.running) outcome.stopped.push(container.name);
     } catch (e: unknown) {