@flame0510/project-aether 1.3.0 → 1.4.1

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

@@ -6,83 +6,19 @@ import * as path from 'path';
 import { patchRev4aProvider } from '../../gateway/sync';
 import { extractProviderAndModel } from '@/app/api/provider/upstream';
 import { DB_FILE, AGENTS_TOKEN_FILE, PROVIDER_KEYS_FILE, templatesDir } from '@/lib/rev4a-paths';
-import { getMountFlags, applyRuntimeConfig } from '@/lib/agent-setup';
+import { getMountFlags, applyRuntimeConfig, withControlUiPolicy } from '@/lib/agent-setup';
+import { listLocalAgentImages, newestLocalSupportedVersion } from '@/lib/agent-images';
+import { localImageRef } from '@/lib/agent-versions';
 import { isModelOffered } from '@/lib/model-catalogue';
+import { findAvailablePortBlock, portMappingArgs, validatePortInput, DEFAULT_BLOCK_SIZE } from '@/lib/agent-ports';
+import { getUsedHostPorts } from '@/lib/agent-ports-server';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
 import { waitForGatewayReady } from '@/lib/agent-readiness';
 
 
 
-/**
- * Find an available host port block starting from 3700.
- */
-const REV4A_PORT = 3740;
-const DEFAULT_BLOCK_SIZE = 10;
-
-function getUsedHostPorts(): Set<number> {
-  try {
-    // Parse host ports in JS rather than piping through grep. The previous
-    // form used `grep -oP '\d+(?=->)'` inside a template literal, where \d
-    // loses its backslash — the shell received `d+(?=->)`, which never
-    // matches Docker's `0.0.0.0:3700->3000/tcp`, so this always returned an
-    // empty set and every agent was offered port 3700. `grep -P` is also
-    // GNU-only and absent on macOS. This mirrors the client-side parser in
-    // app/agents/create/page.tsx.
-    const raw = execSync(
-      `docker ps --format '{{.Ports}}'`,
-      { encoding: 'utf-8', timeout: 3000 },
-    );
-    const used = new Set<number>();
-    for (const [, port] of raw.matchAll(/(\d+)->/g)) {
-      const n = Number(port);
-      if (Number.isInteger(n)) used.add(n);
-    }
-    return used;
-  } catch {
-    return new Set();
-  }
-}
-
-function findAvailablePortBlock(blockSize = DEFAULT_BLOCK_SIZE): number {
-  const usedPorts = getUsedHostPorts();
-  for (let base = 3700; base + blockSize - 1 <= 3799; base += DEFAULT_BLOCK_SIZE) {
-    if (base <= REV4A_PORT && REV4A_PORT <= base + blockSize - 1) continue;
-    const block = Array.from({ length: blockSize }, (_, i) => base + i);
-    if (block.every((p) => !usedPorts.has(p))) return base;
-  }
-  let base = 3800;
-  while (true) {
-    const block = Array.from({ length: blockSize }, (_, i) => base + i);
-    if (block.every((p) => !usedPorts.has(p))) return base;
-    base += DEFAULT_BLOCK_SIZE;
-  }
-}
-
-function validatePortInput(input: string): { valid: true; isBlock: boolean; start: number; end: number } | { valid: false; error: string } {
-  const trimmed = input.trim();
-  if (trimmed.includes('-')) {
-    const m = trimmed.match(/^(\d{1,5})-(\d{1,5})$/);
-    if (!m) return { valid: false, error: 'Invalid format. Use e.g. 3700-3709' };
-    const start = parseInt(m[1], 10);
-    const end = parseInt(m[2], 10);
-    if (start < 1 || end > 65535) return { valid: false, error: 'Ports must be between 1 and 65535' };
-    if (end <= start) return { valid: false, error: 'End port must be greater than start port' };
-    if (start <= REV4A_PORT && REV4A_PORT <= end) return { valid: false, error: `Port ${REV4A_PORT} is reserved for Rev4a` };
-    const usedPorts = getUsedHostPorts();
-    const conflicts: number[] = [];
-    for (let p = start; p <= end; p++) { if (usedPorts.has(p)) conflicts.push(p); }
-    if (conflicts.length > 0) return { valid: false, error: `Ports already in use: ${conflicts.join(', ')}` };
-    return { valid: true, isBlock: true, start, end };
-  }
-  const m = trimmed.match(/^(\d{1,5})$/);
-  if (!m) return { valid: false, error: 'Use a number (e.g. 3700) or a range (e.g. 3700-3709)' };
-  const port = parseInt(m[1], 10);
-  if (port < 1 || port > 65535) return { valid: false, error: 'Port must be between 1 and 65535' };
-  if (port === REV4A_PORT) return { valid: false, error: `Port ${REV4A_PORT} is reserved for Rev4a` };
-  const usedPorts = getUsedHostPorts();
-  if (usedPorts.has(port)) return { valid: false, error: `Port ${port} is already in use` };
-  return { valid: true, isBlock: false, start: port, end: port };
-}
+// Port block discovery and validation are shared with the edit (rename/ports) flow, so
+// both offer the same ranges and the same error messages (lib/agent-ports.ts).
 
 export const dynamic = 'force-dynamic';
 export const maxDuration = 180; // docker run (60s) + startup wait (60s) + seeding (60s)
@@ -187,25 +123,27 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
       );
     }
 
-    // Check if name is already in use by a running container
+    // Check if name is already in use by a container, running or not: a stopped agent
+    // keeps its name and its port block, so both would clash on start.
     const existing = execSync(
-      `docker ps --filter "label=AGENT_ID=${containerName}" --format '{{.Names}}'`,
+      `docker ps -a --filter "label=AGENT_ID=${containerName}" --format '{{.Names}}'`,
       { encoding: 'utf-8', timeout: 5000 },
     ).trim();
     if (existing) {
       return NextResponse.json(
-        { success: false, error: `Agent '${displayName}' is already running (container: ${existing})` },
+        { success: false, error: `Agent '${displayName}' already exists (container: ${existing})` },
         { status: 409 },
       );
     }
 
-    // Resolve port range
+    // Resolve port range. One lookup, shared by both paths below.
+    const usedPorts = await getUsedHostPorts();
     let isBlock = false;
     let portStart: number = 0;
     let portEnd: number = 0;
 
     if (portInput) {
-      const v = validatePortInput(portInput);
+      const v = validatePortInput(portInput, usedPorts);
       if (!v.valid) {
         return NextResponse.json(
           { success: false, error: v.error },
@@ -216,7 +154,7 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
       portStart = v.start;
       portEnd = v.end;
     } else {
-      portStart = findAvailablePortBlock();
+      portStart = findAvailablePortBlock(usedPorts);
       portEnd = portStart + DEFAULT_BLOCK_SIZE - 1;
       isBlock = true;
     }
@@ -225,7 +163,20 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
     const mountFlags = getMountFlags();
 
     // Build docker run command
-    const image = 'openclaw-agent-base:latest';
+    // The newest supported OpenClaw version downloaded here (lib/agent-images.ts).
+    let newestLocal: string | null = null;
+    try {
+      newestLocal = newestLocalSupportedVersion(await listLocalAgentImages());
+    } catch {
+      // Docker listed nothing usable: handled below as no image.
+    }
+    if (!newestLocal) {
+      return NextResponse.json(
+        { success: false, error: 'No supported agent image is downloaded. Download it from the Agents page first.' },
+        { status: 409 },
+      );
+    }
+    const image = localImageRef(newestLocal);
     const network = getNetwork();
 
     // Read agents token for new containers
@@ -241,9 +192,9 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
     // not ready yet; without it `docker run --network` fails. Idempotent.
     ensureNetworkExists(network);
 
-    // Every agent gets a host port range for direct access. The URL is composed
-    // by the browser from `port` + `controlToken` in the response — only the
-    // browser knows a hostname that actually reaches this machine.
+    // Every agent gets a host port range for direct access. The Control UI link
+    // is built per click by /api/agents/[id]/open-control-ui, from the host the
+    // dashboard is reached on.
     //
     // There used to be an AGENT_HOSTNAME env var here, holding `<detected-ip>:<port>`.
     // Nothing ever read it: verified across this repo and across the whole
@@ -263,9 +214,7 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
 
     const labelOpts = labels.map((l) => `-l ${shellQuote(l)}`).join(' ');
     const envOpts = envVars.map((e) => `-e ${shellQuote(e)}`).join(' ');
-    const portOpt = isBlock
-      ? `-p ${portStart}-${portEnd}:3000-${3000 + (portEnd - portStart)}`
-      : `-p ${portStart}:3000`;
+    const portOpt = portMappingArgs(portStart, portEnd).join(' ');
 
     // Template files that will be copied into the container workspace.
     // Files that don't exist in the template dir are silently skipped —
@@ -370,14 +319,11 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
 
       // Merge all required sections in one pass (single write, single restart)
 
-      // controlUi — allow browser Control UI access.
-      // deviceAuth is disabled because agent containers are only reachable
-      // on the internal Docker network; the gateway token is the sole auth barrier.
+      // controlUi — keep what the image and OpenClaw wrote, and apply the browser-origin
+      // policy so the Control UI opens on whatever host the agent is reached on.
+      // Recreate re-applies the same policy through applyRuntimeConfig.
       const gatewaySection = (config.gateway || {}) as Record<string, unknown>;
-      gatewaySection.controlUi = {
-        allowedOrigins: ['*'],
-        dangerouslyDisableDeviceAuth: true,
-      };
+      gatewaySection.controlUi = withControlUiPolicy(gatewaySection.controlUi);
       config.gateway = gatewaySection;
 
       // Model reference (primary + fallbacks)
@@ -426,7 +372,7 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
     // create-specific config so they're always present regardless of
     // what was in the persistent volume.
     try {
-      applyRuntimeConfig(containerName);
+      await applyRuntimeConfig(containerName);
 
       // Also guarantee models.providers.rev4a (host-dependent, not in base image).
       // This patch needs no restart; the earlier one follows a full-file rewrite

package/app/api/agents/devices-summary/route.ts

@@ -0,0 +1,37 @@
+/**
+ * GET /api/agents/devices-summary
+ *
+ * Browsers waiting for approval, per running agent — the "browser waiting" badge on
+ * the agent cards. Agents whose config disables device auth (2026.7.x) are answered
+ * from the config alone, without the CLI. One agent that cannot be read reports
+ * `error: true` and does not blank the others.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { mapWithConcurrency } from '@/lib/docker-exec';
+import { listBrowserAccess, listRunningAgentContainers } from '@/lib/agent-devices';
+
+export const dynamic = 'force-dynamic';
+
+const CONCURRENCY = 3;
+
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+
+  let containers: { agentId: string; name: string }[];
+  try {
+    containers = await listRunningAgentContainers();
+  } catch (e) {
+    return NextResponse.json({ agents: [], error: `Docker is unreachable: ${(e as Error).message}` }, { status: 503 });
+  }
+
+  const agents = await mapWithConcurrency(containers, CONCURRENCY, async ({ agentId, name }) => {
+    try {
+      const access = await listBrowserAccess(name);
+      return { agentId, requiresApproval: access.requiresApproval, pending: access.pending.length };
+    } catch {
+      return { agentId, requiresApproval: null, pending: 0, error: true };
+    }
+  });
+  return NextResponse.json({ agents });
+}

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

@@ -2,15 +2,16 @@ import { type NextRequest } from "next/server";
 /**
  * POST /api/agents/download-image
  *
- * Triggers a fresh download (pull) of the openclaw-agent-base image.
- * Returns 202 Accepted immediately — the operation runs in the background.
- * Poll GET /api/agents/download-progress and
- * GET /api/agents/image-status for completion.
+ * Downloads one OpenClaw version of the agent base image in the background.
+ * Body (optional): `{ "version": "2026.9.3" }` — a supported version; without it, the
+ * newest supported version the registry publishes. Returns 202 with the version;
+ * poll GET /api/agents/image-status for completion.
  *
- * Requires auth. Returns 409 if a download is already running.
+ * Requires auth. 400 for an unsupported version, 409 if a download is already running.
  */
 import { NextResponse } from 'next/server';
-import { downloadAgentImage, getIsDownloading } from '@/lib/buildAgentImage';
+import { defaultDownloadVersion, downloadAgentImage, getIsDownloading } from '@/lib/buildAgentImage';
+import { isSupportedVersion } from '@/lib/agent-versions';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
 
 export const dynamic = 'force-dynamic';
@@ -25,10 +26,16 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
     );
   }
 
+  const body = (await request.json().catch(() => null)) as { version?: unknown } | null;
+  if (body?.version !== undefined && !isSupportedVersion(body.version)) {
+    return NextResponse.json({ error: 'version must be an OpenClaw version this Rev4a supports' }, { status: 400 });
+  }
+  const version = (body?.version as string | undefined) ?? (await defaultDownloadVersion());
+
   // Start download in background — fire and forget
-  downloadAgentImage({ force: true }).catch(() => {
-    // Errors are logged to the download log file
+  downloadAgentImage({ version }).catch((e: unknown) => {
+    console.error(`[download-image] OpenClaw ${version}:`, (e as Error).message);
   });
 
-  return NextResponse.json({ started: true }, { status: 202 });
+  return NextResponse.json({ started: true, version }, { status: 202 });
 }

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' },