@flame0510/project-aether 1.3.0 → 1.4.0

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

@@ -3,11 +3,10 @@ import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { resolveAgentedContainer, isValidAgentId } from '@/lib/container';
-import { patchRev4aProvider } from '@/app/api/gateway/sync';
-import { getMountFlags, applyRuntimeConfig } from '@/lib/agent-setup';
+import { agentBusyReason } from '@/lib/agent-busy';
+import { agentEditView, EditRefusedError, startAgentEdit } from '@/lib/agent-edit';
 import { DB_FILE } from '@/lib/rev4a-paths';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
-import { waitForGatewayReady } from '@/lib/agent-readiness';
 
 const BACKUP_VOLUME = 'rev4a-backups';
 
@@ -30,6 +29,9 @@ export async function DELETE(request: Request,
       return NextResponse.json({ success: false, error: 'Invalid agent id' }, { status: 400 });
     }
 
+    const busy = await agentBusyReason(id);
+    if (busy) return NextResponse.json({ error: busy }, { status: 409 });
+
     // Only allow deletion of containers that have a matching AGENT_ID label
     const containerName = resolveAgentedContainer(id);
     if (!containerName) {
@@ -87,16 +89,14 @@ export async function DELETE(request: Request,
   }
 }
 
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-
 /**
  * PATCH /api/agents/[id]
  *
- * Update agent settings (display name, ports — future).
- * Recreates the container with updated env vars while preserving the
- * persistent volume, workspace, sessions, and all data.
+ * Edit an agent's display name and/or port range. The container is rebuilt on the image
+ * it already runs — **no backup**, the persistent volume is never touched — and the job
+ * runs in the background (`lib/agent-edit.ts`): `202` once it has started, then
+ * `GET /api/agents/[id]` reports the running or last edit so the panel can resume.
+ * While it runs, anything else that would touch the agent answers `409`.
  */
 export async function PATCH(
   request: Request,
@@ -115,149 +115,37 @@ export async function PATCH(
       return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 });
     }
 
-    const { displayName, portRange } = body;
-    if (!displayName && !portRange) {
-      return NextResponse.json({ error: 'No fields to update' }, { status: 400 });
-    }
-
-    if (displayName !== undefined && (!displayName || displayName.trim().length < 1)) {
-      return NextResponse.json({ error: 'Display name must not be empty' }, { status: 400 });
-    }
-
-    // Resolve the container
-    const containerName = resolveAgentedContainer(id);
-    if (!containerName) {
-      return NextResponse.json({ error: `No container found with AGENT_ID '${id}'` }, { status: 404 });
-    }
-
-    // Inspect existing container
-    let inspect: string;
-    try {
-      inspect = execSync(`docker inspect ${containerName}`, { timeout: 10000, encoding: 'utf-8' }).trim();
-    } catch {
-      return NextResponse.json({ error: `Container '${containerName}' not found` }, { status: 404 });
-    }
-
-    const info = JSON.parse(inspect);
-    const [container] = info;
-    const image = container.Config?.Image || 'openclaw-agent-base:latest';
-    const currentEnv: string[] = container.Config?.Env || [];
-
-    // Update AGENT_NAME in env vars
-    let env = [...currentEnv];
-    if (displayName) {
-      const idx = env.findIndex((e: string) => e.startsWith('AGENT_NAME='));
-      const newEntry = `AGENT_NAME=${displayName.trim()}`;
-      if (idx >= 0) {
-        env[idx] = newEntry;
-      } else {
-        env.push(newEntry);
-      }
-    }
-
-    // Keep only relevant env vars
-    const keepPrefixes = ['AGENT_', 'MODEL_', 'OPENCLAW_', 'TZ='];
-    const envOpts = env
-      .filter((e: string) => keepPrefixes.some((p) => e.startsWith(p)))
-      .map((e: string) => `-e ${shellQuote(e)}`)
-      .join(' ');
-
-    // Labels
-    const labels = container.Config?.Labels || {};
-    const keepLabelKeys = ['AGENT_ID', 'traefik.', 'description', 'maintainer'];
-    const labelOpts = Object.entries(labels)
-      .filter(([k]) => keepLabelKeys.some((p) => k === p || k.startsWith(p)))
-      .map(([k, v]) => `-l ${shellQuote(`${k}=${v}`)}`)
-      .join(' ');
-
-    // Network
-    const networks = container.NetworkSettings?.Networks || {};
-    const network = Object.keys(networks)[0];
-    if (!network) {
-      return NextResponse.json({ error: 'Cannot determine network' }, { status: 500 });
-    }
-
-    // Port mappings
-    const portBindings = (container.HostConfig?.PortBindings || {}) as Record<string, { HostPort: string }[]>;
-    let portOpts = Object.entries(portBindings)
-      .map(([containerPort, bindings]) => {
-        const hostPort = bindings[0]?.HostPort;
-        if (!hostPort) return '';
-        const proto = containerPort.includes('/udp') ? '/udp' : '';
-        return `-p ${hostPort}:${containerPort.replace(/\/.*$/, '')}${proto}`;
-      })
-      .filter(Boolean)
-      .join(' ');
-
-    // If portRange is provided, replace the port mapping
-    if (portRange) {
-      const parts = portRange.trim().split('-');
-      const start = parseInt(parts[0], 10);
-      const end = parts[1] ? parseInt(parts[1], 10) : start;
-      if (isNaN(start) || isNaN(end) || start < 1 || end > 65535 || end < start) {
-        return NextResponse.json({ error: 'Invalid port range' }, { status: 400 });
-      }
-      if (end === start) {
-        portOpts = `-p ${start}:3000`;
-      } else {
-        portOpts = `-p ${start}-${end}:3000-${3000 + (end - start)}`;
-      }
-    }
-
-    const volumeName = `agent-${id}-data`;
-
-    // Stop & remove old container (keep volume)
-    try {
-      execSync(`docker rm -f ${containerName}`, { timeout: 15000 });
-    } catch (rmErr) {
-      return NextResponse.json(
-        { error: `Failed to remove old container: ${(rmErr as Error).message}` },
-        { status: 500 },
-      );
-    }
-
-    // Run new container with same volume
-    const cmd = [
-      `docker run -d`,
-      `--name "${id}"`,
-      `--network "${network}"`,
-      `--restart unless-stopped`,
-      `--add-host host.docker.internal:host-gateway`,
-      `-v ${volumeName}:/root`,
-      ...getMountFlags(),
-      labelOpts,
-      envOpts,
-      portOpts,
-      `"${image}"`,
-    ].filter(Boolean).join(' \\\n  ');
-
-    execSync(cmd, { timeout: 60000, encoding: 'utf-8' });
-
-    // Wait for startup to complete — /startupz, not /health
-    const ready = await waitForGatewayReady(id);
-    if (!ready) {
-      return NextResponse.json(
-        { error: 'Container started but its gateway did not finish starting within 60s.' },
-        { status: 500 },
-      );
-    }
-
-    // Apply runtime config
-    try {
-      applyRuntimeConfig(id);
-      patchRev4aProvider(id);
-    } catch (e) {
-      // non-fatal, but a skipped patch must show up in the log
-      console.error('[agent:update] runtime config patch failed:', (e as Error).message);
-    }
-
-    return NextResponse.json({
-      success: true,
-      displayName: displayName?.trim() || null,
-    });
+    const rowId = await startAgentEdit(id, { displayName: body.displayName, portRange: body.portRange });
+    return NextResponse.json({ started: true, id: rowId }, { status: 202 });
   } catch (e: unknown) {
+    if (e instanceof EditRefusedError) {
+      const message = e.message;
+      // The shared port validator's messages (lib/agent-ports.ts) are validation errors:
+      // they answer 400, like the create route. Everything else is a busy refusal (409).
+      const status = /Invalid agent id|Display name must not be empty|No fields to update|Invalid format|Ports must be between|End port must be greater|reserved for Rev4a|already in use|Use a number/.test(message)
+        ? 400
+        : 409;
+      return NextResponse.json({ error: message }, { status });
+    }
     return NextResponse.json({ error: (e as Error).message }, { status: 500 });
   }
 }
 
+/**
+ * GET /api/agents/[id]
+ *
+ * The running or last edit of an agent (`null` when it was never edited): what the edit
+ * panel polls to resume after a reload.
+ */
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+  const { id } = await params;
+  if (!isValidAgentId(id)) return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
+  return NextResponse.json({ edit: agentEditView(id) }, { headers: { 'Cache-Control': 'no-store' } });
+}
+
+
 

package/app/api/agents/[id]/update/rollback/route.ts

@@ -0,0 +1,30 @@
+/**
+ * POST /api/agents/[id]/update/rollback
+ *
+ * Roll back the agent's latest update (lib/agent-update.ts): its pre-update backup is
+ * restored and the container recreated on the version it ran before. Everything the
+ * agent did after that backup is lost. 202 with the update; the steps continue in the
+ * background, `GET /api/agents/[id]/update` follows them.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { isValidAgentId } from '@/lib/container';
+import { UpdateRefusedError, agentUpdateView, startAgentRollback } from '@/lib/agent-update';
+
+export const dynamic = 'force-dynamic';
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  if (!isValidAgentId(id)) return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
+  try {
+    await startAgentRollback(id);
+    return NextResponse.json({ update: await agentUpdateView(id) }, { status: 202 });
+  } catch (e) {
+    const status = e instanceof UpdateRefusedError ? 409 : 500;
+    return NextResponse.json({ error: (e as Error).message }, { status });
+  }
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Update one agent to a newer supported OpenClaw version (lib/agent-update.ts).
+ *
+ *   GET   `{ currentVersion, candidate, update }`: the version the agent runs, the
+ *         `{ fromVersion, toVersion }` an update would do (null when none is newer),
+ *         and the latest update with its status and live backup progress.
+ *   POST  `{ version? }` — start an update, by default to the newest supported version
+ *         downloaded. 202 with the new update; the steps continue in the background.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { isValidAgentId } from '@/lib/container';
+import { isSupportedVersion } from '@/lib/agent-versions';
+import { UpdateRefusedError, agentUpdateView, startAgentUpdate, updateCandidate } from '@/lib/agent-update';
+
+export const dynamic = 'force-dynamic';
+
+type Ctx = { params: Promise<{ id: string }> };
+
+export async function GET(request: NextRequest, { params }: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  if (!isValidAgentId(id)) return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
+  try {
+    const { currentVersion, candidate } = await updateCandidate(id);
+    return NextResponse.json(
+      { currentVersion, candidate, update: await agentUpdateView(id) },
+      { headers: { 'Cache-Control': 'no-store' } },
+    );
+  } catch (e) {
+    return NextResponse.json({ error: (e as Error).message }, { status: 503 });
+  }
+}
+
+export async function POST(request: NextRequest, { params }: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  if (!isValidAgentId(id)) return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
+  const body = (await request.json().catch(() => null)) as { version?: unknown } | null;
+  if (body?.version !== undefined && body.version !== null && !isSupportedVersion(body.version)) {
+    return NextResponse.json({ error: 'version must be an OpenClaw version this Rev4a supports' }, { status: 400 });
+  }
+  try {
+    await startAgentUpdate(id, (body?.version as string | undefined) ?? undefined);
+    return NextResponse.json({ update: await agentUpdateView(id) }, { status: 202 });
+  } catch (e) {
+    const status = e instanceof UpdateRefusedError ? 409 : 500;
+    return NextResponse.json({ error: (e as Error).message }, { status });
+  }
+}

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

@@ -0,0 +1,67 @@
+/**
+ * GET /api/agents/activity-summary
+ *
+ * The long operation each agent is in the middle of, if any — the chip on the agent
+ * cards: `BACKUP nn%`, `RESTORING`, `RECREATING`, `UPDATING`.
+ *
+ * One Docker list call plus, per running cold backup, its status read. Idle agents are
+ * not listed at all, so an idle system costs one call.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { coldBackupStatus, listRunningColdBackups } from '@/lib/cold-backup';
+import { activeRestoreAgentIds, latestRestore } from '@/lib/agent-restore-state';
+import { activeRecreateAgentIds, latestRecreate } from '@/lib/agent-recreate-state';
+import { activeUpdateAgentIds, latestUpdate } from '@/lib/agent-update-state';
+import { activeEditAgentIds, latestEdit } from '@/lib/agent-edit-state';
+
+export const dynamic = 'force-dynamic';
+
+export type AgentActivityKind = 'backup' | 'restore' | 'recreate' | 'update' | 'edit';
+
+interface AgentActivity {
+  agentId: string;
+  kind: AgentActivityKind;
+  file?: string | null;
+  version?: string | null;
+  percent?: number | null;
+}
+
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+
+  const byAgent = new Map<string, AgentActivity>();
+
+  // Update and recreate first: a running cold backup then overrides them, because while
+  // its helper archives the volume that is the phase actually in progress.
+  for (const agentId of activeUpdateAgentIds()) {
+    const row = latestUpdate(agentId);
+    if (row && (row.status === 'migrating' || row.status === 'verifying' || row.status === 'rolling_back')) {
+      byAgent.set(agentId, { agentId, kind: 'update', version: row.to_version });
+    }
+  }
+  for (const agentId of activeRecreateAgentIds()) {
+    const row = latestRecreate(agentId);
+    if (row && row.status === 'recreating') {
+      byAgent.set(agentId, { agentId, kind: 'recreate', version: row.image });
+    }
+  }
+  for (const agentId of activeRestoreAgentIds()) {
+    byAgent.set(agentId, { agentId, kind: 'restore', file: latestRestore(agentId)?.file ?? null });
+  }
+  for (const agentId of activeEditAgentIds()) {
+    const row = latestEdit(agentId);
+    if (row && row.status === 'rebuilding') {
+      byAgent.set(agentId, { agentId, kind: 'edit', file: row.display_name });
+    }
+  }
+
+  const backupIds = await listRunningColdBackups().catch(() => []);
+  await Promise.all(backupIds.map(async (agentId) => {
+    const job = await coldBackupStatus(agentId).catch(() => null);
+    if (!job || job.status !== 'running') return;
+    byAgent.set(agentId, { agentId, kind: 'backup', file: job.file, percent: job.percent });
+  }));
+
+  return NextResponse.json({ agents: [...byAgent.values()] }, { headers: { 'Cache-Control': 'no-store' } });
+}

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)
@@ -205,7 +141,7 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
     let portEnd: number = 0;
 
     if (portInput) {
-      const v = validatePortInput(portInput);
+      const v = validatePortInput(portInput, getUsedHostPorts());
       if (!v.valid) {
         return NextResponse.json(
           { success: false, error: v.error },
@@ -216,7 +152,7 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
       portStart = v.start;
       portEnd = v.end;
     } else {
-      portStart = findAvailablePortBlock();
+      portStart = findAvailablePortBlock(getUsedHostPorts());
       portEnd = portStart + DEFAULT_BLOCK_SIZE - 1;
       isBlock = true;
     }
@@ -225,7 +161,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 +190,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 +212,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 +317,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 +370,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 });
 }