@flame0510/project-aether 1.3.0 → 1.4.0

package/lib/agent-devices.ts

@@ -0,0 +1,361 @@
+/**
+ * Browser access to an agent's Control UI: requests waiting for approval, the
+ * browsers already approved, and the one-time link that opens the Control UI
+ * without an approval.
+ *
+ * Everything goes through the OpenClaw CLI inside the container, called with the
+ * async `dockerExec`, so a slow agent never holds the event loop. The CLI talks to
+ * the agent's own Gateway on port 3000. The token is resolved inside the container
+ * with the entrypoint's precedence — `/root/.agent-token`, then the container's
+ * `OPENCLAW_GATEWAY_TOKEN` — so it never reaches argv on the host.
+ *
+ * Browser approval exists from OpenClaw 9.x. Agents created on 2026.7.x carry
+ * `gateway.controlUi.dangerouslyDisableDeviceAuth: true`: they open with the token
+ * alone and have nothing to approve, so `requiresApproval` is false for them and
+ * the CLI is not called. `openclaw dashboard --json` does not exist on 2026.7.x
+ * either, so `resolveControlUiUrl` gives those agents the plain token link.
+ */
+import { dockerExec, dockerExecNoFail } from '@/lib/docker-exec';
+import { dockerFetch } from '@/lib/docker-socket';
+import { isValidAgentId } from '@/lib/container';
+
+const CLI_TIMEOUT_MS = 20_000;
+const LINK_TIMEOUT_MS = 30_000;
+const CONFIG_TIMEOUT_MS = 8_000;
+
+/**
+ * Runs `openclaw "$@"` against the agent's own Gateway. Arguments stay positional
+ * (`sh -c <script> sh <args…>`): nothing a caller passes is interpolated into the
+ * script.
+ */
+const GATEWAY_CLI = [
+  'export OPENCLAW_GATEWAY_PORT=3000',
+  'if [ -f /root/.agent-token ]; then OPENCLAW_GATEWAY_TOKEN=$(head -1 /root/.agent-token | tr -d "[:space:]"); export OPENCLAW_GATEWAY_TOKEN; fi',
+  'exec openclaw "$@"',
+].join('; ');
+
+const REQUEST_ID_RE = /^[A-Za-z0-9-]{8,80}$/;
+const DEVICE_ID_RE = /^[A-Za-z0-9_-]{8,128}$/;
+const HOSTNAME_RE = /^(\[[0-9A-Fa-f:.]+\]|[0-9A-Fa-f:.]{2,45}|[A-Za-z0-9.-]{1,253})$/;
+const MAX_NAME_LENGTH = 64;
+
+export const isRequestId = (v: unknown): v is string => typeof v === 'string' && REQUEST_ID_RE.test(v);
+export const isDeviceId = (v: unknown): v is string => typeof v === 'string' && DEVICE_ID_RE.test(v);
+export const isHostname = (v: unknown): v is string => typeof v === 'string' && HOSTNAME_RE.test(v);
+
+/** A device label: trimmed, printable, at most 64 characters. Null when unusable. */
+export function cleanDeviceName(v: unknown): string | null {
+  if (typeof v !== 'string') return null;
+  const name = v.trim();
+  if (!name || name.length > MAX_NAME_LENGTH || /[\u0000-\u001f\u007f]/.test(name)) return null;
+  return name;
+}
+
+export interface AgentContainer {
+  name: string;
+  running: boolean;
+  /** Host port published for the Gateway's port 3000, if any. */
+  controlPort: string | null;
+}
+
+interface DockerContainer {
+  Names?: string[];
+  State?: string;
+  Labels?: Record<string, string>;
+  Ports?: { PrivatePort?: number; PublicPort?: number }[];
+}
+
+/** The container carrying `AGENT_ID=<agentId>`, through the Docker API rather than a blocking `docker ps`. */
+export async function findAgentContainer(agentId: string): Promise<AgentContainer | null> {
+  if (!isValidAgentId(agentId)) return null;
+  const filters = encodeURIComponent(JSON.stringify({ label: [`AGENT_ID=${agentId}`] }));
+  const list = await dockerFetch<DockerContainer[]>('GET', `/containers/json?all=true&filters=${filters}`);
+  const c = Array.isArray(list) ? list[0] : undefined;
+  if (!c) return null;
+  const port = (c.Ports ?? []).find((p) => p.PrivatePort === 3000 && p.PublicPort)?.PublicPort;
+  return {
+    name: (c.Names?.[0] ?? '').replace(/^\//, ''),
+    running: c.State === 'running',
+    controlPort: port ? String(port) : null,
+  };
+}
+
+/** Running agent containers, for the fleet summary. */
+export async function listRunningAgentContainers(): Promise<{ agentId: string; name: string }[]> {
+  const filters = encodeURIComponent(JSON.stringify({ label: ['AGENT_ID'] }));
+  const list = await dockerFetch<DockerContainer[]>('GET', `/containers/json?filters=${filters}`);
+  return (Array.isArray(list) ? list : [])
+    .filter((c) => c.State === 'running' && c.Labels?.AGENT_ID)
+    .map((c) => ({ agentId: c.Labels!.AGENT_ID, name: (c.Names?.[0] ?? '').replace(/^\//, '') }));
+}
+
+/**
+ * The JSON document in the CLI's output. `docker exec` resolves with partial output
+ * when it hits its deadline, so a document that does not parse is treated as a
+ * failure, never as an empty answer.
+ */
+function parseCliJson(output: string): unknown {
+  const start = output.search(/[{[]/);
+  const end = Math.max(output.lastIndexOf('}'), output.lastIndexOf(']'));
+  if (start === -1 || end < start) throw new Error('OpenClaw returned no JSON');
+  try {
+    return JSON.parse(output.slice(start, end + 1));
+  } catch {
+    throw new Error('OpenClaw returned incomplete JSON');
+  }
+}
+
+async function runCli(container: string, args: string[], timeoutMs = CLI_TIMEOUT_MS): Promise<unknown> {
+  const out = await dockerExec(container, ['sh', '-c', GATEWAY_CLI, 'sh', ...args], { timeoutMs });
+  return parseCliJson(out);
+}
+
+/** True when the Gateway answers `/startupz` with JSON carrying its version, which only OpenClaw 9.x does. */
+async function answersStartupzWithVersion(container: string): Promise<boolean> {
+  const probe = await dockerExecNoFail(container, ['curl', '-s', '--max-time', '3', 'http://127.0.0.1:3000/startupz'], { timeoutMs: CONFIG_TIMEOUT_MS });
+  try {
+    return typeof (JSON.parse(probe) as { version?: unknown })?.version === 'string';
+  } catch {
+    // Not JSON: the 2026.7.x web UI answers every unknown path with HTML.
+    return false;
+  }
+}
+
+/**
+ * Whether browsers need approval on this agent.
+ *
+ * The OpenClaw version decides first. 9.x answers `/startupz` with a JSON document
+ * carrying its version, and there approval always applies: it ignores
+ * `dangerouslyDisableDeviceAuth`, which an agent created on 2026.7.x may still carry.
+ * Anything else is 2026.7.x, where that key does disable approval. Null when neither
+ * can be read.
+ */
+export async function requiresBrowserApproval(container: string): Promise<boolean | null> {
+  if (await answersStartupzWithVersion(container)) return true;
+  try {
+    const raw = await dockerExec(container, ['cat', '/root/.openclaw/openclaw.json'], { timeoutMs: CONFIG_TIMEOUT_MS });
+    const cfg = JSON.parse(raw) as { gateway?: { controlUi?: { dangerouslyDisableDeviceAuth?: unknown } } };
+    return cfg?.gateway?.controlUi?.dangerouslyDisableDeviceAuth !== true;
+  } catch {
+    return null;
+  }
+}
+
+const str = (v: unknown): string | null => (typeof v === 'string' && v.trim() ? v.trim() : null);
+const num = (v: unknown): number | null => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const strings = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : []);
+
+export interface PendingBrowser {
+  requestId: string;
+  deviceId: string;
+  displayName: string | null;
+  platform: string | null;
+  clientId: string | null;
+  clientMode: string | null;
+  roles: string[];
+  scopes: string[];
+  remoteIp: string | null;
+  browserOrigin: string | null;
+  /** A known device asking for a broader role or scope set. */
+  isRepair: boolean;
+  requestedAtMs: number | null;
+}
+
+export interface ApprovedBrowser {
+  deviceId: string;
+  /** Operator label, else the name the client reported. */
+  label: string | null;
+  platform: string | null;
+  clientId: string | null;
+  clientMode: string | null;
+  roles: string[];
+  scopes: string[];
+  remoteIp: string | null;
+  /** `silent` (local auto-approval), `owner` (approved by an operator), `bootstrap` (one-time link), … */
+  approvedVia: string | null;
+  createdAtMs: number | null;
+  approvedAtMs: number | null;
+  lastUsedAtMs: number | null;
+}
+
+export interface BrowserAccess {
+  requiresApproval: boolean | null;
+  pending: PendingBrowser[];
+  approved: ApprovedBrowser[];
+}
+
+function toPending(r: Record<string, unknown>): PendingBrowser | null {
+  const requestId = str(r.requestId);
+  const deviceId = str(r.deviceId);
+  if (!requestId || !deviceId) return null;
+  return {
+    requestId,
+    deviceId,
+    displayName: str(r.displayName),
+    platform: str(r.platform),
+    clientId: str(r.clientId),
+    clientMode: str(r.clientMode),
+    roles: strings(r.roles).length ? strings(r.roles) : strings([r.role]),
+    scopes: strings(r.scopes),
+    remoteIp: str(r.remoteIp),
+    browserOrigin: str(r.browserOrigin),
+    isRepair: r.isRepair === true,
+    requestedAtMs: num(r.ts),
+  };
+}
+
+function toApproved(d: Record<string, unknown>): ApprovedBrowser | null {
+  const deviceId = str(d.deviceId);
+  if (!deviceId) return null;
+  const tokenUse = (Array.isArray(d.tokens) ? d.tokens : [])
+    .map((t) => num((t as Record<string, unknown>)?.lastUsedAtMs))
+    .filter((t): t is number => t !== null);
+  return {
+    deviceId,
+    label: str(d.operatorLabel) ?? str(d.displayName),
+    platform: str(d.platform),
+    clientId: str(d.clientId),
+    clientMode: str(d.clientMode),
+    roles: strings(d.roles).length ? strings(d.roles) : strings([d.role]),
+    scopes: strings(d.scopes),
+    remoteIp: str(d.remoteIp),
+    approvedVia: str(d.approvedVia),
+    createdAtMs: num(d.createdAtMs),
+    approvedAtMs: num(d.approvedAtMs),
+    lastUsedAtMs: tokenUse.length ? Math.max(...tokenUse) : num(d.lastSeenAtMs) ?? num(d.lastConnectedAtMs),
+  };
+}
+
+/** Pending requests and approved browsers of one running agent. Throws when the CLI fails. */
+export async function listBrowserAccess(container: string): Promise<BrowserAccess> {
+  const requiresApproval = await requiresBrowserApproval(container);
+  if (requiresApproval === false) return { requiresApproval, pending: [], approved: [] };
+  const raw = (await runCli(container, ['devices', 'list', '--json'])) as { pending?: unknown; paired?: unknown };
+  const rows = (v: unknown) => (Array.isArray(v) ? v.filter((x): x is Record<string, unknown> => !!x && typeof x === 'object') : []);
+  return {
+    requiresApproval,
+    pending: rows(raw?.pending).map(toPending).filter((x): x is PendingBrowser => x !== null),
+    approved: rows(raw?.paired).map(toApproved).filter((x): x is ApprovedBrowser => x !== null),
+  };
+}
+
+export async function approveBrowser(container: string, requestId: string): Promise<void> {
+  await runCli(container, ['devices', 'approve', requestId, '--json']);
+}
+
+export async function rejectBrowser(container: string, requestId: string): Promise<void> {
+  await runCli(container, ['devices', 'reject', requestId, '--json']);
+}
+
+/** Removes the pairing: that browser needs approval again on its next connection. */
+export async function removeBrowser(container: string, deviceId: string): Promise<void> {
+  await runCli(container, ['devices', 'remove', deviceId, '--json']);
+}
+
+export async function renameBrowser(container: string, deviceId: string, name: string): Promise<void> {
+  await runCli(container, ['devices', 'rename', '--device', deviceId, '--name', name, '--json']);
+}
+
+/**
+ * A one-time Control UI link that pairs the browser opening it, with no approval.
+ *
+ * `openclaw dashboard --json` issues a ten-minute, single-use bootstrap token and
+ * returns `browserUrl` aimed at the Gateway's own listener (`127.0.0.1:3000`), with
+ * the WebSocket destination in the `gatewayUrl` fragment parameter. Both are
+ * rewritten to the address the dashboard is being reached on and the agent's
+ * published port, which is where the browser can actually connect.
+ */
+export async function issueControlUiLink(
+  container: string,
+  hostname: string,
+  port: string,
+): Promise<{ url: string; expiresAtMs: number | null }> {
+  const data = (await runCli(container, ['dashboard', '--json'], LINK_TIMEOUT_MS)) as Record<string, unknown>;
+  const browserUrl = str(data?.browserUrl);
+  if (data?.ok !== true || !browserUrl) throw new Error(str(data?.reason) ?? 'OpenClaw did not issue a browser link');
+
+  const host = hostForUrl(hostname);
+  const [base, fragment = ''] = browserUrl.split('#');
+  const url = new URL(base);
+  url.hostname = host;
+  url.port = port;
+
+  const params = new URLSearchParams(fragment);
+  const gatewayUrl = params.get('gatewayUrl');
+  if (gatewayUrl) {
+    const ws = new URL(gatewayUrl);
+    ws.hostname = host;
+    ws.port = port;
+    params.set('gatewayUrl', ws.toString().replace(/\/$/, ''));
+  }
+  return { url: `${url.toString()}#${params.toString()}`, expiresAtMs: num(data.browserBootstrapExpiresAtMs) };
+}
+
+/** An IPv6 literal needs brackets inside a URL. */
+function hostForUrl(hostname: string): string {
+  return hostname.includes(':') && !hostname.startsWith('[') ? `[${hostname}]` : hostname;
+}
+
+/** The hostname in a `Host` header value — the address the dashboard was reached on. */
+export function hostnameFromHostHeader(host: string | null): string | null {
+  if (!host) return null;
+  try {
+    const hostname = new URL(`http://${host}`).hostname;
+    return isHostname(hostname) ? hostname : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The token the Gateway was started with, read inside the container with the entrypoint's precedence. */
+const READ_GATEWAY_TOKEN =
+  'if [ -f /root/.agent-token ]; then head -1 /root/.agent-token | tr -d "[:space:]"; else printf %s "$OPENCLAW_GATEWAY_TOKEN"; fi';
+
+/**
+ * The token a plain Control UI link carries, read from the container rather than from
+ * Rev4a's copy, so it is the one the Gateway checks even after the shared token changed
+ * while the agent was stopped.
+ */
+async function readGatewayToken(container: string): Promise<string | null> {
+  try {
+    const token = (await dockerExec(container, ['sh', '-c', READ_GATEWAY_TOKEN], { timeoutMs: CONFIG_TIMEOUT_MS })).trim();
+    return token && token !== 'undefined' ? token : null;
+  } catch {
+    return null;
+  }
+}
+
+const plainLink = (hostname: string, port: string, token: string) =>
+  `http://${hostForUrl(hostname)}:${port}/#token=${encodeURIComponent(token)}`;
+
+/**
+ * Where "Open" should take the browser: the one-time link on OpenClaw 9.x, which pairs
+ * the browser with no approval, else the plain token link — on 2026.7.x, which has no
+ * `dashboard --json` and needs no approval, or when no one-time link could be issued.
+ */
+export async function resolveControlUiUrl(
+  container: string,
+  hostname: string,
+  port: string,
+): Promise<{ url: string; kind: 'one-time' | 'token' }> {
+  if (await answersStartupzWithVersion(container)) {
+    try {
+      return { url: (await issueControlUiLink(container, hostname, port)).url, kind: 'one-time' };
+    } catch {
+      // Fall back to the plain link below.
+    }
+  }
+  const token = await readGatewayToken(container);
+  if (!token) throw new Error('no one-time link could be issued and no gateway token is available');
+  return { url: plainLink(hostname, port, token), kind: 'token' };
+}
+
+/**
+ * A Control UI link for someone else: the plain token link. On an agent that requires
+ * browser approval it gets past gateway auth only; the browser then waits for approval.
+ */
+export async function buildInviteLink(container: string, hostname: string, port: string): Promise<string> {
+  const token = await readGatewayToken(container);
+  if (!token) throw new Error('The agent has no readable gateway token');
+  return plainLink(hostname, port, token);
+}

package/lib/agent-edit-state.ts

@@ -0,0 +1,108 @@
+/**
+ * Persisted state of agent edits: the `agent_edits` table (lib/db-bootstrap.mjs).
+ *
+ * Kept apart from lib/agent-edit.ts so busy checks (lib/agent-busy.ts) can ask which
+ * agents are being edited without importing the edit action.
+ */
+import { openDb } from '@/lib/db';
+
+export type EditStatus = 'rebuilding' | 'done' | 'failed' | 'interrupted';
+
+/** Statuses during which the agent must not be touched by anything else. */
+export const ACTIVE_EDIT_STATUSES: readonly EditStatus[] = ['rebuilding'];
+
+export interface AgentEditRow {
+  id: number;
+  agent_id: string;
+  status: EditStatus;
+  display_name: string | null;
+  port_range: string | null;
+  error: string | null;
+  started_at: number;
+  updated_at: number;
+  finished_at: number | null;
+}
+
+const FINAL: readonly EditStatus[] = ['done', 'failed', 'interrupted'];
+
+export function insertEdit(agentId: string, displayName: string | null, portRange: string | null): number {
+  const db = openDb(false);
+  try {
+    const now = Date.now();
+    const info = db.prepare(
+      `INSERT INTO agent_edits (agent_id, status, display_name, port_range, started_at, updated_at)
+       VALUES (?, 'rebuilding', ?, ?, ?, ?)`,
+    ).run(agentId, displayName, portRange, now, now);
+    return Number(info.lastInsertRowid);
+  } finally {
+    db.close();
+  }
+}
+
+type Writable = Partial<Pick<AgentEditRow, 'status' | 'error'>>;
+
+export function updateEditRow(id: number, fields: Writable): void {
+  const entries = Object.entries(fields).filter(([, v]) => v !== undefined);
+  const now = Date.now();
+  const sets = [...entries.map(([k]) => `${k} = ?`), 'updated_at = ?'];
+  const values: unknown[] = [...entries.map(([, v]) => v), now];
+  if (fields.status && FINAL.includes(fields.status)) {
+    sets.push('finished_at = ?');
+    values.push(now);
+  } else if (fields.status) {
+    sets.push('finished_at = NULL');
+  }
+  const db = openDb(false);
+  try {
+    db.prepare(`UPDATE agent_edits SET ${sets.join(', ')} WHERE id = ?`).run(...values, id);
+  } finally {
+    db.close();
+  }
+}
+
+export function latestEdit(agentId: string): AgentEditRow | null {
+  const db = openDb(true);
+  try {
+    return (db.prepare('SELECT * FROM agent_edits WHERE agent_id = ? ORDER BY id DESC LIMIT 1').get(agentId) as AgentEditRow | undefined) ?? null;
+  } finally {
+    db.close();
+  }
+}
+
+export function isEditActive(agentId: string): boolean {
+  const row = latestEdit(agentId);
+  return !!row && ACTIVE_EDIT_STATUSES.includes(row.status);
+}
+
+/** AGENT_IDs with an edit in an active status. */
+export function activeEditAgentIds(): Set<string> {
+  const db = openDb(true);
+  try {
+    const placeholders = ACTIVE_EDIT_STATUSES.map(() => '?').join(', ');
+    const rows = db.prepare(`SELECT DISTINCT agent_id FROM agent_edits WHERE status IN (${placeholders})`).all(...ACTIVE_EDIT_STATUSES) as { agent_id: string }[];
+    return new Set(rows.map((r) => r.agent_id));
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * At startup no edit job can be running: a row still active was cut off by the restart.
+ * It becomes `interrupted`, keeping the name and port it was applying.
+ */
+export function markInterruptedEdits(): number {
+  const db = openDb(false);
+  try {
+    const placeholders = ACTIVE_EDIT_STATUSES.map(() => '?').join(', ');
+    const now = Date.now();
+    const info = db.prepare(
+      `UPDATE agent_edits
+         SET error = COALESCE(error, 'Rev4a restarted while this step was running: ' || status),
+             status = 'interrupted', updated_at = ?, finished_at = ?
+       WHERE status IN (${placeholders})`,
+    ).run(now, now, ...ACTIVE_EDIT_STATUSES);
+    return info.changes;
+  } finally {
+    db.close();
+  }
+}

package/lib/agent-edit.ts

@@ -0,0 +1,157 @@
+/**
+ * Editing an agent's display name and/or port range.
+ *
+ * The container is rebuilt on the image it already runs, with the new environment value
+ * (`AGENT_NAME`) and/or port bindings — no cold backup, because the persistent volume is
+ * never touched. The job is recorded in `agent_edits` and runs in the background, so a
+ * page reload or a Rev4a restart never loses track of it and a second edit (or a backup)
+ * cannot start on top of the first (lib/agent-busy.ts answers 409 while one runs).
+ */
+import { isValidAgentId } from '@/lib/container';
+import { portMappingArgs, validatePortInput } from '@/lib/agent-ports';
+import { getUsedHostPorts } from '@/lib/agent-ports-server';
+import { resolveRecreateImage, runDocker } from '@/lib/agent-images';
+import { inspectAgentContainer, recreateAgentContainer } from '@/lib/agent-recreate';
+import { agentBusyReason } from '@/lib/agent-busy';
+import { waitForGatewayReady } from '@/lib/agent-readiness';
+import { applyRuntimeConfig } from '@/lib/agent-setup';
+import { patchRev4aProvider } from '@/app/api/gateway/sync';
+import { activeEditAgentIds, insertEdit, isEditActive, latestEdit, markInterruptedEdits, updateEditRow, type AgentEditRow } from '@/lib/agent-edit-state';
+
+const EDIT_READY_TIMEOUT_MS = 5 * 60 * 1000;
+
+export class EditRefusedError extends Error {}
+
+/**
+ * Port bindings for a range, validated with the same rules and messages as agent
+ * creation. `ownPorts` are the agent's own published host ports: they are excluded from
+ * the "already in use" check, so keeping or shifting its own block is not a conflict
+ * with itself — while a conflict with another agent still fails **before** the container
+ * is removed.
+ */
+function parsePortArgs(portRange: string, ownPorts: number[]): string[] {
+  const used = getUsedHostPorts();
+  for (const p of ownPorts) used.delete(p);
+  const result = validatePortInput(portRange, used);
+  if (!result.valid) throw new EditRefusedError(result.error);
+  return portMappingArgs(result.start, result.end);
+}
+
+/** The agent's own published host ports, from its container inspect. */
+function ownHostPorts(container: { HostConfig?: { PortBindings?: Record<string, { HostPort?: string }[] | null> } }): number[] {
+  return Object.values(container.HostConfig?.PortBindings ?? {})
+    .flatMap((bindings) => bindings ?? [])
+    .map((b) => Number(b?.HostPort))
+    .filter((n) => Number.isInteger(n));
+}
+
+/** Edit jobs running in this process, so a second start for the same agent is refused. */
+const running = new Set<string>();
+
+export interface EditOptions {
+  displayName?: string;
+  portRange?: string;
+}
+
+/** Start an edit. Returns once the job is recorded; the rebuild continues in the background. */
+export async function startAgentEdit(agentId: string, opts: EditOptions): Promise<number> {
+  if (!isValidAgentId(agentId)) throw new EditRefusedError('Invalid agent id');
+
+  const displayName = opts.displayName === undefined ? undefined : (opts.displayName.trim() || null);
+  if (opts.displayName !== undefined && !displayName) throw new EditRefusedError('Display name must not be empty');
+  if (!displayName && !opts.portRange) throw new EditRefusedError('No fields to update');
+  const portRange = opts.portRange?.trim() || null;
+
+  if (running.has(agentId) || isEditActive(agentId)) throw new EditRefusedError('An edit of this agent is already running');
+  // Claimed synchronously, before the first await, so two requests cannot both pass.
+  running.add(agentId);
+  try {
+    // One source for every long operation: an update, recreate, restore, edit or backup.
+    const busy = await agentBusyReason(agentId);
+    if (busy) throw new EditRefusedError(busy);
+
+    const container = await inspectAgentContainer(agentId);
+    if (!container) throw new EditRefusedError(`No container found with AGENT_ID '${agentId}'`);
+    // A bad range is refused before any state is written, and before the container is
+    // removed — the only failure mode that could leave the agent without one.
+    const portArgs = opts.portRange ? parsePortArgs(opts.portRange, ownHostPorts(container)) : undefined;
+
+    const id = insertEdit(agentId, displayName ?? null, portRange);
+    void runEdit(id, agentId, container, displayName ?? null, portArgs).finally(() => running.delete(agentId));
+    return id;
+  } catch (e) {
+    running.delete(agentId);
+    throw e;
+  }
+}
+
+async function runEdit(id: number, agentId: string, container: Awaited<ReturnType<typeof inspectAgentContainer>>, displayName: string | null, portArgs?: string[]): Promise<void> {
+  try {
+    if (!container) throw new Error(`No container found with AGENT_ID '${agentId}'`);
+    const image = await resolveRecreateImage(container);
+
+    await recreateAgentContainer(agentId, container, image, {
+      env: displayName ? { AGENT_NAME: displayName } : undefined,
+      portArgs,
+    });
+
+    if (!(await waitForGatewayReady(agentId, EDIT_READY_TIMEOUT_MS))) {
+      throw new Error(`The gateway did not finish starting within ${EDIT_READY_TIMEOUT_MS / 60_000} minutes`);
+    }
+    await applyRuntimeConfig(agentId);
+    try {
+      patchRev4aProvider(agentId);
+    } catch (e) {
+      console.error('[agent:edit] provider patch failed:', (e as Error).message);
+    }
+
+    updateEditRow(id, { status: 'done' });
+  } catch (e) {
+    updateEditRow(id, { status: 'failed', error: (e as Error)?.message ?? String(e) });
+  }
+}
+
+export interface AgentEditView {
+  id: number;
+  agentId: string;
+  status: AgentEditRow['status'];
+  displayName: string | null;
+  portRange: string | null;
+  error: string | null;
+  startedAtMs: number;
+  finishedAtMs: number | null;
+}
+
+/** The latest edit of an agent, so the panel can resume after a reload. */
+export function agentEditView(agentId: string): AgentEditView | null {
+  const row = latestEdit(agentId);
+  if (!row) return null;
+  return {
+    id: row.id,
+    agentId: row.agent_id,
+    status: row.status,
+    displayName: row.display_name,
+    portRange: row.port_range,
+    error: row.error,
+    startedAtMs: row.started_at,
+    finishedAtMs: row.finished_at,
+  };
+}
+
+/**
+ * At startup no edit job can be running: rows still active were cut off by the restart.
+ * They become `interrupted`; a container left stopped is started again, best-effort.
+ */
+export async function recoverInterruptedEdits(): Promise<number> {
+  const ids = activeEditAgentIds();
+  if (ids.size === 0) return 0;
+  const interrupted = markInterruptedEdits();
+  for (const agentId of ids) {
+    const container = await inspectAgentContainer(agentId).catch(() => null);
+    const name = container?.Name?.replace(/^\//, '');
+    if (name && !container?.State?.Running) {
+      await runDocker(['start', name], { timeoutMs: 60_000 }).catch(() => {});
+    }
+  }
+  return interrupted;
+}