@flame0510/project-aether 1.2.0 → 1.4.0

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

@@ -1,118 +1,38 @@
 import { NextResponse, type NextRequest } from 'next/server';
-import { execSync } from 'child_process';
+import { execSync, execFileSync } from 'child_process';
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { buildRev4aProviderConfig } from '../../gateway/sync';
+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 { loadModelsConfig } from '@/lib/model-catalogue';
+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';
-
-/**
- * Wait for a Docker container gateway to be ready.
- * Checks that the gateway is responding on port 3000 inside the container.
- * Polls every 2s, gives up after timeoutMs.
- * Returns true if the gateway is reachable, false on timeout.
- */
-function waitForContainerReady(name: string, timeoutMs = 60000): boolean {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    try {
-      execSync(
-        `docker exec ${name} sh -c 'curl -sf http://127.0.0.1:3000/health >/dev/null 2>&1 || wget -qO- http://127.0.0.1:3000/health >/dev/null 2>&1'`,
-        { timeout: 5000 },
-      );
-      return true;
-    } catch {
-      // gateway not ready yet
-    }
-    // Sleep 2s
-    execSync('sleep 2', { timeout: 3000 });
-  }
-  return false;
-}
+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) + health check (60s) + seeding (60s)
+export const maxDuration = 180; // docker run (60s) + startup wait (60s) + seeding (60s)
 
 const TEMPLATES_DIR = templatesDir(process.cwd());
 const AGENTS_TOKEN_PATH = AGENTS_TOKEN_FILE;
 const DEFAULT_NETWORK = 'rev4a-network';
 
+/**
+ * Used when the request names no model. The full id: the agent cards compare the
+ * primary against catalogue ids, and the two-segment alias matches none of them.
+ */
+const DEFAULT_MODEL = 'rev4a/deepseek/deepseek-flash';
+
 function isDockerCompatibleName(name: string): boolean {
   return /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
 }
@@ -191,9 +111,14 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
     }
 
     // Validate model (if provided) exists in models.config.json
-    if (model && !isValidModel(model)) {
+    // A request without a model used to create an agent with no primary at all —
+    // the config write below was skipped — while the event log recorded a default
+    // the agent never had. The default is now applied for real, and validated like
+    // any other model, so it cannot produce an agent the proxy refuses.
+    const effectiveModel: string = typeof model === 'string' && model ? model : DEFAULT_MODEL;
+    if (!isValidModel(effectiveModel)) {
       return NextResponse.json(
-        { success: false, error: `Model '${model}' not found in models.config.json` },
+        { success: false, error: `Model '${effectiveModel}' is not offered by this deployment: it is not in the catalogue, is disabled, or its provider has no API key.` },
         { status: 400 },
       );
     }
@@ -216,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 },
@@ -227,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;
     }
@@ -236,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
@@ -248,9 +186,13 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
       );
     }
 
-    // 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.
+    // `rev4a serve` creates this network at start-up, but skips it when Docker was
+    // not ready yet; without it `docker run --network` fails. Idempotent.
+    ensureNetworkExists(network);
+
+    // 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
@@ -270,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 —
@@ -310,7 +250,7 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
           port: portStart,
           portEnd,
           isBlock,
-          model: model || 'rev4a/deepseek-v4-flash',
+          model: effectiveModel,
           fallbacks,
           containerId,
           containerName,
@@ -321,14 +261,14 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
       // DB logging is optional, ignore failures
     }
 
-    // Wait for container to be ready (HTTP health check, up to 60s).
-    // If it doesn't come up, remove the container and return an error —
-    // a zombie agent with no config is worse than an explicit failure.
-    const ready = waitForContainerReady(containerName);
+    // Wait for startup to complete (/startupz, up to 60s). Not /health, which
+    // answers as soon as the HTTP server listens. If it does not come up, remove
+    // the container: a zombie agent with no config is worse than an explicit failure.
+    const ready = await waitForGatewayReady(containerName);
     if (!ready) {
       try { execSync(`docker rm -f ${containerName}`, { timeout: 10000 }); } catch { /* best-effort */ }
       return NextResponse.json(
-        { success: false, error: `Container started but gateway did not become healthy within 60s. Container removed — try again.` },
+        { success: false, error: `Container started but its gateway did not finish starting within 60s. Container removed — try again.` },
         { status: 500 },
       );
     }
@@ -377,22 +317,20 @@ 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)
-      if (model) {
-        const modelRef = model.startsWith('rev4a/') ? model : `rev4a/${model}`;
-        const fallbackRefs = (fallbacks || []).map((fb: string) =>
-          fb.startsWith('rev4a/') ? fb : `rev4a/${fb}`,
-        );
+      {
+        // Always the canonical `rev4a/<provider>/<model>`: the Agents chips and the
+        // Model panel look the primary up by catalogue id, so the alias form
+        // (`rev4a/deepseek-flash`) or a bare name would show as not in the catalogue.
+        const modelRef = toRev4aRef(effectiveModel);
+        const fallbackRefs = (fallbacks || []).map((fb: string) => toRev4aRef(fb));
         const agents = (config.agents || {}) as Record<string, unknown>;
         const defaults = (agents.defaults || {}) as Record<string, unknown>;
         defaults.model = {
@@ -432,21 +370,12 @@ 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);
-
-      // Also guarantee models.providers.rev4a (host-dependent, not in base image)
-      const providerConfig = buildRev4aProviderConfig();
-      const providerJson = JSON.stringify({ models: { providers: { rev4a: providerConfig } } });
-      execSync(
-        `docker exec -i ${containerName} sh -c 'openclaw config patch --stdin'`,
-        { timeout: 15000, stdio: 'pipe', input: providerJson },
-      );
+      await applyRuntimeConfig(containerName);
 
-      // No gateway restart: `config patch` reports "Change will apply without
-      // restarting the gateway" for a models-only patch, and the Gateway watches
-      // openclaw.json with gateway.reload defaulting to hybrid. The earlier
-      // restart in this route stays — that one follows a full-file rewrite that
-      // includes gateway.*, which is the one section that genuinely needs it.
+      // Also guarantee models.providers.rev4a (host-dependent, not in base image).
+      // This patch needs no restart; the earlier one follows a full-file rewrite
+      // that includes gateway.*, the one section that genuinely needs it.
+      patchRev4aProvider(containerName);
     } catch (e: unknown) {
       // runtime config patch is best-effort; log but don't fail the create
       console.error('[agent:create] runtime config patch failed:', (e as Error).message || String(e));
@@ -474,6 +403,12 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
   }
 }
 
+/** `rev4a/<provider>/<model>`, whatever form the request used. */
+function toRev4aRef(modelId: string): string {
+  const { provider, model } = extractProviderAndModel({ model: modelId });
+  return `rev4a/${provider}/${model}`;
+}
+
 function getAvailableTemplates(): string[] {
   try {
     return fs.readdirSync(TEMPLATES_DIR).filter((f) => {
@@ -485,12 +420,23 @@ function getAvailableTemplates(): string[] {
   }
 }
 
+/**
+ * The model must be one this deployment offers, in any form the proxy accepts.
+ * Checking the raw catalogue let the API create an agent on a disabled model, or
+ * one whose provider has no key, which the proxy then refuses on its first turn.
+ */
 function isValidModel(modelId: string): boolean {
+  const { provider, model } = extractProviderAndModel({ model: modelId });
+  return isModelOffered(provider, model);
+}
+
+function ensureNetworkExists(name: string): void {
   try {
-    const config = loadModelsConfig();
-    return config.some((m) => m.id === modelId);
+    execFileSync('docker', ['network', 'inspect', name], { stdio: 'ignore', timeout: 5000 });
   } catch {
-    return true; // skip on errors
+    try {
+      execFileSync('docker', ['network', 'create', name], { stdio: 'ignore', timeout: 10000 });
+    } catch { /* let docker run report it */ }
   }
 }
 

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,
   });
 }