@flame0510/project-aether 1.2.0 → 1.4.0

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

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

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

@@ -0,0 +1,126 @@
+/**
+ * Browser access to one agent's Control UI.
+ *
+ *   GET     pending approvals and approved browsers
+ *   POST    { action: "approve" | "reject", requestId }
+ *   PATCH   { deviceId, name }            rename an approved browser
+ *   DELETE  ?deviceId=<id>                revoke: the browser needs approval again
+ *
+ * All operations run the OpenClaw CLI inside the container asynchronously; see
+ * `lib/agent-devices.ts`.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import {
+  approveBrowser,
+  cleanDeviceName,
+  findAgentContainer,
+  isDeviceId,
+  isRequestId,
+  listBrowserAccess,
+  rejectBrowser,
+  removeBrowser,
+  renameBrowser,
+  type AgentContainer,
+} from '@/lib/agent-devices';
+
+export const dynamic = 'force-dynamic';
+
+type Ctx = { params: Promise<{ id: string }> };
+
+/** The agent's container, or the response that explains why there is none to act on. */
+async function resolveAgent(id: string): Promise<AgentContainer | NextResponse> {
+  let agent: AgentContainer | null;
+  try {
+    agent = await findAgentContainer(id);
+  } catch (e) {
+    return NextResponse.json({ error: `Docker is unreachable: ${(e as Error).message}` }, { status: 503 });
+  }
+  if (!agent) return NextResponse.json({ error: `No agent '${id}'` }, { status: 404 });
+  return agent;
+}
+
+const failed = (e: unknown) => NextResponse.json({ error: (e as Error).message || 'OpenClaw command failed' }, { status: 502 });
+
+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;
+  const agent = await resolveAgent(id);
+  if (agent instanceof NextResponse) return agent;
+  if (!agent.running) return NextResponse.json({ running: false, requiresApproval: null, pending: [], approved: [] });
+  try {
+    return NextResponse.json({ running: true, ...(await listBrowserAccess(agent.name)) });
+  } catch (e) {
+    return failed(e);
+  }
+}
+
+async function runningAgent(id: string): Promise<AgentContainer | NextResponse> {
+  const agent = await resolveAgent(id);
+  if (agent instanceof NextResponse) return agent;
+  if (!agent.running) return NextResponse.json({ error: 'The agent is not running' }, { status: 409 });
+  return agent;
+}
+
+async function readBody(request: NextRequest): Promise<Record<string, unknown> | null> {
+  try {
+    const body = await request.json();
+    return body && typeof body === 'object' ? (body as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+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;
+  const body = await readBody(request);
+  if (!body || (body.action !== 'approve' && body.action !== 'reject')) {
+    return NextResponse.json({ error: 'action must be "approve" or "reject"' }, { status: 400 });
+  }
+  if (!isRequestId(body.requestId)) return NextResponse.json({ error: 'A valid requestId is required' }, { status: 400 });
+
+  const agent = await runningAgent(id);
+  if (agent instanceof NextResponse) return agent;
+  try {
+    if (body.action === 'approve') await approveBrowser(agent.name, body.requestId);
+    else await rejectBrowser(agent.name, body.requestId);
+    return NextResponse.json({ ok: true });
+  } catch (e) {
+    return failed(e);
+  }
+}
+
+export async function PATCH(request: NextRequest, { params }: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  const body = await readBody(request);
+  if (!body || !isDeviceId(body.deviceId)) return NextResponse.json({ error: 'A valid deviceId is required' }, { status: 400 });
+  const name = cleanDeviceName(body.name);
+  if (!name) return NextResponse.json({ error: 'name must be 1-64 printable characters' }, { status: 400 });
+
+  const agent = await runningAgent(id);
+  if (agent instanceof NextResponse) return agent;
+  try {
+    await renameBrowser(agent.name, body.deviceId, name);
+    return NextResponse.json({ ok: true });
+  } catch (e) {
+    return failed(e);
+  }
+}
+
+export async function DELETE(request: NextRequest, { params }: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  const deviceId = request.nextUrl.searchParams.get('deviceId');
+  if (!isDeviceId(deviceId)) return NextResponse.json({ error: 'A valid deviceId query parameter is required' }, { status: 400 });
+
+  const agent = await runningAgent(id);
+  if (agent instanceof NextResponse) return agent;
+  try {
+    await removeBrowser(agent.name, deviceId);
+    return NextResponse.json({ ok: true });
+  } catch (e) {
+    return failed(e);
+  }
+}

package/app/api/agents/[id]/invite-link/route.ts

@@ -0,0 +1,53 @@
+/**
+ * GET /api/agents/[id]/invite-link
+ *
+ * A Control UI link to send to someone else. It carries the gateway token, so the
+ * browser that opens it passes gateway auth and lands in the agent's "waiting for
+ * approval" list; nothing opens until an operator approves it.
+ *
+ * Refused on agents without browser approval, where the same link would open the
+ * Control UI directly. The host is the one this request reached Rev4a on, never a
+ * parameter.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { buildInviteLink, findAgentContainer, hostnameFromHostHeader, requiresBrowserApproval } from '@/lib/agent-devices';
+
+export const dynamic = 'force-dynamic';
+
+const noStore = { 'Cache-Control': 'no-store' };
+
+const fail = (status: number, error: string) => NextResponse.json({ error }, { status, headers: noStore });
+
+const isLoopback = (hostname: string) =>
+  hostname === 'localhost' || hostname.startsWith('127.') || hostname === '[::1]';
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  const hostname = hostnameFromHostHeader(request.headers.get('host'));
+  if (!hostname) return fail(400, 'Could not tell which address Rev4a is being reached on');
+
+  let agent;
+  try {
+    agent = await findAgentContainer(id);
+  } catch (e) {
+    return fail(503, `Docker is unreachable: ${(e as Error).message}`);
+  }
+  if (!agent) return fail(404, `No agent '${id}'`);
+  if (!agent.running || !agent.controlPort) return fail(409, 'The agent is not running or publishes no Control UI port');
+
+  const requiresApproval = await requiresBrowserApproval(agent.name);
+  if (requiresApproval === null) return fail(502, 'Could not tell whether this agent requires browser approval');
+  if (!requiresApproval) return fail(409, 'This agent does not require browser approval: anyone with the link would get in');
+
+  try {
+    const url = await buildInviteLink(agent.name, hostname, agent.controlPort);
+    return NextResponse.json({ url, loopbackHost: isLoopback(hostname) }, { headers: noStore });
+  } catch (e) {
+    return fail(502, (e as Error).message);
+  }
+}

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

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server';
 import { execSync } from 'child_process';
 import { resolveAgentedContainer, isValidAgentId, isLifecycleCoolingDown, markLifecycleCooldown } from '@/lib/container';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { agentBusyReason } from '@/lib/agent-busy';
 
 export const dynamic = 'force-dynamic';
 
@@ -23,6 +24,8 @@ export async function POST(
     const { id } = await params;
     if (!id) return NextResponse.json({ error: 'Agent ID required' }, { status: 400 });
     if (!isValidAgentId(id)) return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
+    const busy = await agentBusyReason(id);
+    if (busy) return NextResponse.json({ error: busy }, { status: 409 });
 
     const containerName = resolveAgentedContainer(id);
     if (!containerName) {

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

@@ -0,0 +1,113 @@
+/**
+ * GET /api/agents/[id]/model
+ *
+ * The model configuration of one agent: primary, fallbacks, and whether the
+ * primary is actually resolvable from the catalogue the agent was given.
+ *
+ * This replaced `GET /api/gateway`, which reported the same two fields but walked
+ * every container to do it — on a seven-agent host, seven `docker exec` calls at
+ * ~90ms each, paid to open one agent's detail panel. This reads one container.
+ *
+ * Writes still go to `PUT /api/gateway/agent`, which already handles the
+ * `rev4a/` prefixing and fallback de-duplication.
+ */
+import { NextResponse } from 'next/server';
+import { resolveAgentedContainer, isValidAgentId } from '@/lib/container';
+import { dockerExecNoFail } from '@/lib/docker-exec';
+import { catalogueStatus } from '@/lib/model-catalogue';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+
+export const dynamic = 'force-dynamic';
+
+interface ModelRef {
+  primary: string | null;
+  fallbacks: string[];
+}
+
+function readModelRef(config: Record<string, unknown>): ModelRef {
+  const agents = (config.agents ?? {}) as Record<string, unknown>;
+  const defaults = (agents.defaults ?? {}) as Record<string, unknown>;
+  const model = defaults.model;
+
+  // `model` accepts either a bare string or { primary, fallbacks }.
+  if (typeof model === 'string') return { primary: model, fallbacks: [] };
+  if (model && typeof model === 'object') {
+    const m = model as Record<string, unknown>;
+    return {
+      primary: typeof m.primary === 'string' ? m.primary : null,
+      fallbacks: Array.isArray(m.fallbacks) ? m.fallbacks.filter((f): f is string => typeof f === 'string') : [],
+    };
+  }
+  return { primary: null, fallbacks: [] };
+}
+
+/** Model ids the agent's own catalogue offers, as written by gateway/sync. */
+function readCatalogueIds(config: Record<string, unknown>): string[] {
+  const models = (config.models ?? {}) as Record<string, unknown>;
+  const providers = (models.providers ?? {}) as Record<string, unknown>;
+  const rev4a = (providers.rev4a ?? {}) as Record<string, unknown>;
+  const list = Array.isArray(rev4a.models) ? rev4a.models : [];
+  return list
+    .map((m) => (m && typeof m === 'object' ? (m as Record<string, unknown>).id : null))
+    .filter((id): id is string => typeof id === 'string');
+}
+
+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 (!id || !isValidAgentId(id)) {
+    return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
+  }
+
+  const container = resolveAgentedContainer(id);
+  if (!container) {
+    return NextResponse.json({ error: `No container found with AGENT_ID '${id}'` }, { status: 404 });
+  }
+
+  const raw = await dockerExecNoFail(container, ['cat', '/root/.openclaw/openclaw.json'], { timeoutMs: 8000 });
+  if (!raw) {
+    // A stopped container, or a read that timed out. `docker exec` exits 0 on
+    // the SIGTERM sent at the deadline, so an empty body is the only signal
+    // either way — report unknown rather than inventing an empty config.
+    return NextResponse.json({ agentId: id, reachable: false, primary: null, fallbacks: [], resolvable: null });
+  }
+
+  let config: Record<string, unknown>;
+  try {
+    config = JSON.parse(raw);
+  } catch {
+    return NextResponse.json({ error: 'Container config is not valid JSON' }, { status: 502 });
+  }
+
+  const { primary, fallbacks } = readModelRef(config);
+  const catalogue = readCatalogueIds(config);
+
+  // The primary is stored prefixed (`rev4a/<id>`); the catalogue stores bare ids.
+  const bare = primary ? primary.replace(/^rev4a\//, '') : null;
+
+  return NextResponse.json({
+    agentId: id,
+    reachable: true,
+    primary,
+    fallbacks,
+    /**
+     * False means the agent is configured for a model its own catalogue does not
+     * carry — it will fail on its next turn, and with no fallbacks it fails hard.
+     * This happens when a model is disabled in the Gateway while some agent still
+     * has it as primary.
+     */
+    resolvable: bare ? catalogue.includes(bare) : null,
+    catalogueSize: catalogue.length,
+    /**
+     * Why the primary would fail regardless of this container: `offered`,
+     * `disabled` (unchecked, or no provider key) or `missing` (no longer in the
+     * catalogue). Lets the panel name the right cause instead of guessing it.
+     */
+    primaryStatus: bare ? catalogueStatus(bare) : null,
+  });
+}

package/app/api/agents/[id]/open-control-ui/route.ts

@@ -0,0 +1,58 @@
+/**
+ * GET /api/agents/[id]/open-control-ui
+ *
+ * What the "Open" buttons navigate to, in a new tab. Redirects to the agent's Control
+ * UI: through a one-time link that pairs the browser with no approval on OpenClaw 9.x,
+ * or through the plain token link on 2026.7.x or when no one-time link can be issued.
+ *
+ * The target host is the one this request reached Rev4a on (the `Host` header), with
+ * the agent's published port. It is never a parameter: a page elsewhere that gets a
+ * signed-in browser to open this URL can at most open the Control UI in that same
+ * browser, never send the link to another host.
+ *
+ * A navigation rather than a fetch on purpose: the button opens this URL inside the
+ * click, so nothing is left to assign to a blank tab after an `await`, and there is
+ * no popup for the browser to block. See `lib/agent-devices.ts`.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { findAgentContainer, hostnameFromHostHeader, resolveControlUiUrl } from '@/lib/agent-devices';
+
+export const dynamic = 'force-dynamic';
+
+/** A plain-text page: this route is opened in a browser tab, not read by code. */
+function page(status: number, text: string): NextResponse {
+  return new NextResponse(`${text}\n`, {
+    status,
+    headers: { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store' },
+  });
+}
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const { id } = await params;
+  const host = hostnameFromHostHeader(request.headers.get('host'));
+  if (!host) return page(400, 'Could not tell which address Rev4a is being reached on.');
+
+  let agent;
+  try {
+    agent = await findAgentContainer(id);
+  } catch (e) {
+    return page(503, `Docker is unreachable: ${(e as Error).message}`);
+  }
+  if (!agent) return page(404, `No agent '${id}'.`);
+  if (!agent.running || !agent.controlPort) return page(409, 'The agent is not running or publishes no Control UI port.');
+
+  try {
+    const { url } = await resolveControlUiUrl(agent.name, host, agent.controlPort);
+    return new NextResponse(null, {
+      status: 302,
+      headers: { Location: url, 'Cache-Control': 'no-store', 'Referrer-Policy': 'no-referrer' },
+    });
+  } catch (e) {
+    return page(502, `Could not open the Control UI: ${(e as Error).message}.`);
+  }
+}

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

@@ -1,199 +1,45 @@
-import { NextResponse } from 'next/server';
-import { execSync } from 'child_process';
-import * as fs from 'fs';
-import * as path from 'path';
-import { resolveAgentedContainer, isValidAgentId } from '@/lib/container';
-import { buildRev4aProviderConfig } from '@/app/api/gateway/sync';
-import { getMountFlags, applyRuntimeConfig } from '@/lib/agent-setup';
+/**
+ * Recreate one agent's container on the image it already runs (lib/agent-recreate.ts).
+ *
+ *   POST    start: a cold backup is taken (the agent stops for it), then the container
+ *           is rebuilt and the gateway waited for. 202 once the job has started; the
+ *           steps continue in the background and are recorded in `agent_recreates`.
+ *   GET     `{ recreate }`: the running or last job, with backup progress; null when none.
+ *
+ * While it runs, anything else that would touch the agent answers 409 (lib/agent-busy.ts).
+ */
+import { NextResponse, type NextRequest } from 'next/server';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { isValidAgentId } from '@/lib/container';
+import { agentRecreateView, RecreateRefusedError, startAgentRecreate } from '@/lib/agent-recreate';
 
 export const dynamic = 'force-dynamic';
-export const maxDuration = 180; // docker run (60s) + health check (60s) + config patch (60s)
 
-const BACKUP_VOLUME = 'rev4a-backups';
-
-/** Timestamp YYYY-MM-DD_HHmmssSSS (ms precision avoids same-second collisions). */
-function ts(): string {
-  const d = new Date();
-  const pad = (n: number) => String(n).padStart(2, '0');
-  const ms = String(d.getMilliseconds()).padStart(3, '0');
-  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}${ms}`;
-}
+type Ctx = { params: Promise<{ id: string }> };
 
-/**
- * Wait for the container gateway to respond on port 3000.
- */
-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 { /* not ready */ }
-    execSync('sleep 2', { timeout: 3000 });
-  }
-  return false;
+async function agentId(ctx: Ctx): Promise<string | NextResponse> {
+  const { id } = await ctx.params;
+  return isValidAgentId(id) ? id : NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
 }
 
-/**
- * POST /api/agents/[id]/recreate
- * Stop -> backup -> rm -> run with same params + shared volumes.
- * Workspace data and state are preserved in the persistent volume.
- * Shared volumes (skills, repos) are always mounted.
- * After the container is up, guarantee extraDirs + provider config.
- */
-export async function POST(request: Request,
-  { params }: { params: Promise<{ id: string }> },
-): Promise<NextResponse> {
-  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+export async function POST(request: NextRequest, ctx: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const id = await agentId(ctx);
+  if (id instanceof NextResponse) return id;
   try {
-    const { id } = await params;
-    if (!id) return NextResponse.json({ error: 'Agent name required' }, { status: 400 });
-    if (!isValidAgentId(id)) return NextResponse.json({ error: 'Invalid agent id' }, { status: 400 });
-
-    // Resolve the actual container name via AGENT_ID label
-    const containerName = resolveAgentedContainer(id);
-    if (!containerName) {
-      return NextResponse.json({ error: `No container found with AGENT_ID '${id}'` }, { status: 404 });
-    }
-
-    // Inspect the existing container to capture its parameters
-    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 env: string[] = container.Config?.Env || [];
-
-    // Filter and reformat env vars (skip system vars, keep AGENT_*, MODEL_*, OPENCLAW_*, TZ)
-    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(' ');
-
-    // Extract labels (keep AGENT_ID, traefik.*, description, maintainer)
-    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(' ');
-
-    // Determine network (must exist on the container)
-    const networks = container.NetworkSettings?.Networks || {};
-    const network = Object.keys(networks)[0];
-    if (!network) {
-      return NextResponse.json({ error: 'Cannot determine network — container may have no networks attached' }, { status: 500 });
-    }
-
-    // Determine if there was a custom port mapping
-    const portMappings = (container.HostConfig?.PortBindings || {}) as Record<string, { HostPort: string }[]>;
-    const portOpts = Object.entries(portMappings)
-      .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(' ');
-
-    const volumeName = `agent-${id}-data`;
-
-    // Auto-backup the volume BEFORE destroying the container
-    const backupFile = `agent-${id}-prerecreate-${ts()}.tar.gz`;
-    try {
-      execSync(
-        `docker run --rm ` +
-        `-v ${volumeName}:/source:ro ` +
-        `-v ${BACKUP_VOLUME}:/backup ` +
-        `alpine sh -c 'tar czf /backup/${backupFile} --exclude=.npm/_cacache -C /source . && chmod 644 /backup/${backupFile}'`,
-        { timeout: 60000, stdio: 'pipe' },
-      );
-    } catch (backupErr) {
-      return NextResponse.json(
-        { error: `Pre-recreate backup failed, aborting: ${(backupErr as Error).message}` },
-        { status: 500 },
-      );
-    }
-
-    // Stop & remove the old container. If removal fails (Docker daemon
-    // overloaded, container stuck in "removal in progress"), abort — we
-    // can't run a new container with a conflicting name.
-    try {
-      execSync(`docker rm -f ${containerName}`, { timeout: 15000 });
-    } catch (rmErr) {
-      return NextResponse.json(
-        { error: `Failed to remove old container '${containerName}': ${(rmErr as Error).message}. The original container may still be running.` },
-        { status: 500 },
-      );
-    }
-
-    // Run the new container with all mounts (persistent volume + shared skills + shared repos + rev4a rules)
-    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 the new container to be healthy
-    const ready = waitForContainerReady(id);
-    if (!ready) {
-      return NextResponse.json(
-        { success: false, error: 'Container started but gateway did not become healthy within 60s.' },
-        { status: 500 },
-      );
-    }
-
-    // Guarantee Rev4a runtime config (hooks, shared-skills, provider).
-    // Uses config patch (deep-merge) — idempotent, preserves user customizations.
-    try {
-      applyRuntimeConfig(id);
-
-      // 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 ${id} sh -c 'openclaw config patch --stdin'`,
-        { timeout: 15000, stdio: 'pipe', input: providerJson },
-      );
-
-      // 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.
-    } catch {
-      // config patch is best-effort on recreate
-    }
-
-    return NextResponse.json({ success: true, name: id, image, network, backup: backupFile });
-  } catch (e: unknown) {
-    return NextResponse.json({ error: (e as Error).message }, { status: 500 });
+    const rowId = await startAgentRecreate(id);
+    return NextResponse.json({ started: true, id: rowId }, { status: 202 });
+  } catch (e) {
+    const status = e instanceof RecreateRefusedError
+      ? 409
+      : /No container|not available locally|Cannot tell which image/.test((e as Error).message) ? 404 : 500;
+    return NextResponse.json({ error: (e as Error).message }, { status });
   }
 }
 
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
+export async function GET(request: NextRequest, ctx: Ctx): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as NextResponse;
+  const id = await agentId(ctx);
+  if (id instanceof NextResponse) return id;
+  return NextResponse.json({ recreate: await agentRecreateView(id) }, { headers: { 'Cache-Control': 'no-store' } });
 }