@flame0510/project-aether 1.4.0 → 1.4.1

package/app/agents/create/page.tsx

@@ -2,6 +2,8 @@ import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { DB_FILE, AGENTS_TOKEN_FILE, templatesDir } from '@/lib/rev4a-paths';
+import { REV4A_PORT } from '@/lib/agent-ports';
+import { getUsedHostPorts } from '@/lib/agent-ports-server';
 import { loadOfferedModels } from '@/lib/model-catalogue';
 import CreatePageClient from './PageClient';
 
@@ -45,19 +47,21 @@ async function getModels(): Promise<ModelInfo[]> {
 async function getUsedNames(): Promise<string[]> {
   try {
     const raw = execSync(
-      `docker ps --filter "label=AGENT_ID" --format '{{.Names}}'`,
+      `docker ps -a --filter "label=AGENT_ID" --format '{{.Names}}'`,
       { encoding: 'utf-8', timeout: 5000 },
     ).trim();
     if (!raw) return [];
 
-    // Read AGENT_NAME env from each container (display name)
+    // Read AGENT_NAME from each container's inspect: a stopped agent still owns its
+    // display name, and `docker exec` cannot reach a stopped container.
     const names: string[] = [];
     for (const name of raw.split('\n').filter(Boolean)) {
       try {
-        const displayName = execSync(
-          `docker exec ${name} sh -c 'echo $AGENT_NAME'`,
+        const env = execSync(
+          `docker inspect ${name} --format '{{range .Config.Env}}{{println .}}{{end}}'`,
           { encoding: 'utf-8', timeout: 3000 },
-        ).trim();
+        );
+        const displayName = env.match(/^AGENT_NAME=(.*)$/m)?.[1]?.trim();
         if (displayName) names.push(displayName);
       } catch { /* skip */ }
     }
@@ -68,29 +72,11 @@ async function getUsedNames(): Promise<string[]> {
 }
 
 async function getUsedPorts(): Promise<number[]> {
-  try {
-    const raw = execSync(
-      `docker ps --format '{{.Ports}}'`,
-      { encoding: 'utf-8', timeout: 5000 },
-    ).trim();
-    const ports: number[] = [];
-    if (raw) {
-      for (const line of raw.split('\n')) {
-        const matches = line.match(/(\d+)->/g);
-        if (matches) {
-          matches.forEach((m) => {
-            const p = parseInt(m.replace('->', ''), 10);
-            if (!isNaN(p)) ports.push(p);
-          });
-        }
-      }
-    }
-    // Add Rev4a port as reserved so the client won't suggest it
-    ports.push(3740);
-    return [...new Set(ports)];
-  } catch {
-    return [3740];
-  }
+  // One source for port occupancy (lib/agent-ports-server.ts): it reads every
+  // container's bindings, so the block of a stopped agent is offered to nobody.
+  const ports = await getUsedHostPorts();
+  ports.add(REV4A_PORT);
+  return [...ports];
 }
 
 export default async function CreateAgentPage() {

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

@@ -123,25 +123,27 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
       );
     }
 
-    // Check if name is already in use by a running container
+    // Check if name is already in use by a container, running or not: a stopped agent
+    // keeps its name and its port block, so both would clash on start.
     const existing = execSync(
-      `docker ps --filter "label=AGENT_ID=${containerName}" --format '{{.Names}}'`,
+      `docker ps -a --filter "label=AGENT_ID=${containerName}" --format '{{.Names}}'`,
       { encoding: 'utf-8', timeout: 5000 },
     ).trim();
     if (existing) {
       return NextResponse.json(
-        { success: false, error: `Agent '${displayName}' is already running (container: ${existing})` },
+        { success: false, error: `Agent '${displayName}' already exists (container: ${existing})` },
         { status: 409 },
       );
     }
 
-    // Resolve port range
+    // Resolve port range. One lookup, shared by both paths below.
+    const usedPorts = await getUsedHostPorts();
     let isBlock = false;
     let portStart: number = 0;
     let portEnd: number = 0;
 
     if (portInput) {
-      const v = validatePortInput(portInput, getUsedHostPorts());
+      const v = validatePortInput(portInput, usedPorts);
       if (!v.valid) {
         return NextResponse.json(
           { success: false, error: v.error },
@@ -152,7 +154,7 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
       portStart = v.start;
       portEnd = v.end;
     } else {
-      portStart = findAvailablePortBlock(getUsedHostPorts());
+      portStart = findAvailablePortBlock(usedPorts);
       portEnd = portStart + DEFAULT_BLOCK_SIZE - 1;
       isBlock = true;
     }

package/app/api/version/route.ts

@@ -15,7 +15,8 @@ export const dynamic = 'force-dynamic';
  * GET /api/version
  *
  * Returns the installed Rev4a version from package.json.
- * No auth required.
+ *
+ * Auth: the rev4a_token cookie or Authorization: Bearer <REV4A_TOKEN>.
  */
 export async function GET(request: NextRequest): Promise<NextResponse> {
   const denied = await requireAuthJWT(request); if (denied) return denied as any;

package/docs/ARCHITECTURE.md

@@ -170,13 +170,25 @@ The central container, running the Next.js dashboard + orchestration API.
   `prerecreate` archives are pruned to the newest two. The same `recreateAgentContainer()`
   serves the edit route (`PATCH` → 202, no backup) and the Update action.
   `agentBusyReason()` (`lib/agent-busy.ts`) covers it for every route that changes an agent.
-- **Host ports** are shared between creation and the edit flow by `lib/agent-ports.ts`
-  (pure: `validatePortInput`, `findAvailablePortBlock`, `portMappingArgs`) and
-  `lib/agent-ports-server.ts` (`getUsedHostPorts()`, the Docker lookup, server-only since
-  client components cannot import `child_process`). One block maps to the container's
-  gateway port 3000 (`3700-3709` → `3700-3709:3000-3009`); both flows produce the same
-  validation messages, and the edit excludes the agent's own ports so its block never
-  conflicts with itself.
+- **Host ports** have one source of truth: `lib/agent-ports.ts` holds the pure rules
+  (`validatePortInput`, `findAvailablePortBlock`, `portMappingArgs`,
+  `hostPortsFromBindings`, `hostPortsFromArgs`) and `lib/agent-ports-server.ts` answers
+  which ports are taken (`getHostPortHolders()`, `getUsedHostPorts()`; server-only, it
+  talks to the Docker socket). Creation, the create form, the edit flow and every
+  container rebuild (update, recreate, rollback) read their numbers from there. One block
+  maps to the container's gateway port 3000 (`3700-3709` → `3700-3709:3000-3009`); all
+  flows produce the same validation messages, and a flow rebuilding a container excludes
+  that container's own ports, so its block never conflicts with itself.
+  **A stopped container still holds its block**, but neither `docker ps -a --format
+  '{{.Ports}}'` nor the Docker API's container list reports its ports (verified on Docker
+  29: both return nothing). The lookup therefore reads each container's
+  `HostConfig.PortBindings` — the only source covering the stopped ones. Without that, a
+  new agent could be handed the block of a stopped agent, and the clash only surfaced
+  later, when that agent was started again (`Bind for 0.0.0.0:3730 failed: port is
+  already allocated`), after the container it was replacing had been removed.
+  `recreateAgentContainer()` refuses such a clash **before** removing anything, naming the
+  container that holds each port, so the agent stays up and the operator changes the range
+  from the Edit panel; a failed `docker run` no longer leaves a container behind.
 - **Agent edits** are `lib/agent-edit.ts`, with their state in the `agent_edits` table
   (`lib/agent-edit-state.ts`): the display name (`AGENT_NAME`) and/or the port range are
   applied by rebuilding the container on the image it already runs — **no backup**, the

package/docs/dev/API-REFERENCE.md

@@ -795,7 +795,7 @@ Create a new agent container from a template.
 |---|---|---|
 | `name` | yes | Display name (`AGENT_NAME`); the container name and `AGENT_ID` are generated (`agent_<hex>`) |
 | `template` | yes | Template name (directory in `agent-templates/`) |
-| `portRange` | no | Optional port range (e.g. `3700-3709`) or single port (e.g. `3700`). Default: auto-assigned 10-port block |
+| `portRange` | no | Optional port range (e.g. `3700-3709`) or single port (e.g. `3700`). Default: auto-assigned 10-port block, chosen by `findAvailablePortBlock()` |
 | `model` | no | Primary model id. Must be offered by this deployment (in the catalogue, enabled, provider has a key), in any form the proxy accepts; otherwise `400`. Defaults to `rev4a/deepseek/deepseek-flash`, validated the same way |
 | `fallbacks` | no | Array of fallback model IDs |
 
@@ -804,6 +804,9 @@ Create a new agent container from a template.
 - Single port: `-p <port>:3000` — maps a single host port to container port 3000
 - Control UI: the wizard's Open button goes through `GET /api/agents/[id]/open-control-ui`, like the Agents page
 - Port 3740 is reserved for Rev4a
+- A port held by any container, running or stopped, is refused (`400`): the shared lookup
+  reads every container's bindings (`lib/agent-ports-server.ts`), because a stopped
+  container keeps its allocation while `docker ps -a` and the API's list report none
 - Image: `openclaw-agent-base:<version>`, the newest supported OpenClaw version downloaded here; `409` when none is
 
 **Response:**
@@ -886,12 +889,23 @@ touch the agent answers `409`.
 
 `portRange` is `"<start>"` or `"<start>-<end>"`, mapped onto the gateway port 3000
 (`3700-3709` → `3700-3709:3000-3009`). It is validated with the same rules and messages as
-agent creation (`lib/agent-ports.ts`): a range that holds Rev4a's port `3740`, an invalid
-format, or a port already published by **another** agent answers `400`
+agent creation (`lib/agent-ports.ts`) against the shared lookup
+(`getUsedHostPorts()`, `lib/agent-ports-server.ts`): a range that holds Rev4a's port
+`3740`, an invalid format, or a port already held by **another** container answers `400`
 (`Ports already in use: 3711, 3712`) before anything is rebuilt. The agent's own published
 ports are excluded, so keeping or shifting its block is not a conflict with itself.
+A port held by a **stopped** container counts as in use: the lookup reads every
+container's `HostConfig.PortBindings`, because both `docker ps -a --format '{{.Ports}}'`
+and the API's container list report nothing for a container that is not running.
 At least one field is required; an empty `displayName` is rejected.
 
+The rebuild itself (`recreateAgentContainer()`) re-checks the ports it is about to
+publish against every other container and refuses **before removing anything** when one
+is taken, naming the holder: `Port 3700 is already published by agent_24a68ac9 (Drill
+Wake). Change this agent's port range in the Edit panel, then retry: nothing was
+changed.` The row lands in `failed` with that message and the agent keeps running. The
+same guard protects Update and Rollback, whose rows record the same text.
+
 **Response (202):**
 ```json
 { "started": true, "id": 4 }
@@ -2102,16 +2116,16 @@ Update audio or timezone config in `openclaw.json`.
 ## Version & WebSocket
 
 ### `GET /api/version`
-Return the installed OpenClaw CLI version.
+Return the installed Rev4a version, read from `package.json`.
 
-**Auth:** browser cookie
+**Auth:** `rev4a_token` cookie or `Authorization: Bearer <REV4A_TOKEN>`
 
 **Response:**
 ```json
-{ "version": "openclaw x.y.z" }
+{ "version": "1.4.0" }
 ```
 
-**Fallback:** `{ "version": "unknown" }` if the command fails.
+**Fallback:** `{ "version": "0.0.0" }` if `package.json` cannot be read.
 
 ### Terminal WebSocket
 

package/lib/agent-edit.ts

@@ -8,10 +8,10 @@
  * 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 { hostPortsFromBindings, 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 { resolveRecreateImage } from '@/lib/agent-images';
+import { inspectAgentContainer, recreateAgentContainer, startAndVerifyContainer } from '@/lib/agent-recreate';
 import { agentBusyReason } from '@/lib/agent-busy';
 import { waitForGatewayReady } from '@/lib/agent-readiness';
 import { applyRuntimeConfig } from '@/lib/agent-setup';
@@ -29,22 +29,14 @@ export class EditRefusedError extends Error {}
  * 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();
+async function parsePortArgs(portRange: string, ownPorts: number[]): Promise<string[]> {
+  const used = await 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>();
 
@@ -74,7 +66,7 @@ export async function startAgentEdit(agentId: string, opts: EditOptions): Promis
     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 portArgs = opts.portRange ? await parsePortArgs(opts.portRange, hostPortsFromBindings(container)) : undefined;
 
     const id = insertEdit(agentId, displayName ?? null, portRange);
     void runEdit(id, agentId, container, displayName ?? null, portArgs).finally(() => running.delete(agentId));
@@ -149,9 +141,9 @@ export async function recoverInterruptedEdits(): Promise<number> {
   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(() => {});
-    }
+    if (!name || container?.State?.Running) continue;
+    const started = await startAndVerifyContainer(agentId, name);
+    if (!started.ok) console.warn(`[agent:edit] ${agentId} did not come back after an interrupted edit: ${started.error}`);
   }
   return interrupted;
 }

package/lib/agent-ports-server.ts

@@ -1,27 +1,78 @@
 /**
- * Server-side host-port lookup for lib/agent-ports.ts. Split out because it uses
- * `child_process`, which client components cannot import.
+ * Server-side host-port lookup for lib/agent-ports.ts. Split out because it uses the
+ * Docker socket, which client components cannot reach.
+ *
+ * This is the only place that answers "which host ports are taken": agent creation,
+ * the create form, the edit (rename/ports) flow and every container rebuild (update,
+ * recreate, rollback) all read their numbers from here.
+ *
+ * The numbers come from each container's `HostConfig.PortBindings`, the only source
+ * that also covers containers that are not running. Neither
+ * `docker ps -a --format '{{.Ports}}'` nor the API's container list reports ports for
+ * a stopped container (verified on Docker 29: both return nothing), while the
+ * allocation is still held — starting that container again fails with "port is
+ * already allocated". Reading the bindings is what stops a new agent from being given
+ * the block of a stopped one.
  */
-import { execSync } from 'child_process';
+import { dockerFetch } from '@/lib/docker-socket';
+
+export interface HostPortHolder {
+  /** Container name; agent containers are named after their id. */
+  name: string;
+  /** The container's `AGENT_NAME`, the name the panel shows; null for non-agent containers. */
+  displayName: string | null;
+}
+
+interface ContainerInspect {
+  Id?: string;
+  Name?: string;
+  Config?: { Env?: string[] };
+  HostConfig?: { PortBindings?: Record<string, { HostPort?: string }[] | null> };
+}
 
 /**
- * Host ports published by any container, running or not: a stopped container keeps its
- * port allocations, so `docker run -p` on them fails just the same.
+ * Host ports held by containers, running or stopped, each mapped to the container that
+ * holds it. `excludeContainerId` drops one container from the result: the block of the
+ * container a rebuild is about to replace is not a conflict with itself.
  *
- * Parsed in JS rather than piping through grep: the old `grep -oP '\d+(?=->)'` form lost
- * its backslash inside a template literal, matched nothing, and offered port 3700 to
- * every agent; `grep -P` is also GNU-only and absent on macOS.
+ * Best-effort: an unreachable daemon yields an empty map, as the previous shell-based
+ * lookup did, rather than failing the caller.
  */
-export function getUsedHostPorts(): Set<number> {
+export async function getHostPortHolders(opts: { excludeContainerId?: string } = {}): Promise<Map<number, HostPortHolder>> {
+  const holders = new Map<number, HostPortHolder>();
+  let list: { Id?: string }[];
   try {
-    const raw = execSync(`docker ps -a --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;
+    list = await dockerFetch<{ Id?: string }[]>('GET', '/containers/json?all=true');
   } catch {
-    return new Set();
+    return holders;
   }
+  const ids = (Array.isArray(list) ? list : [])
+    .map((c) => c.Id)
+    .filter((id): id is string => typeof id === 'string' && id !== opts.excludeContainerId);
+  const infos = await Promise.all(
+    ids.map((id) => dockerFetch<ContainerInspect>('GET', `/containers/${id}/json`).catch(() => null)),
+  );
+  for (const info of infos) {
+    if (!info) continue;
+    const name = (info.Name ?? '').replace(/^\//, '') || (info.Id ?? '').slice(0, 12);
+    const agentName = (info.Config?.Env ?? []).find((entry) => entry.startsWith('AGENT_NAME='));
+    const holder: HostPortHolder = { name, displayName: agentName ? agentName.slice('AGENT_NAME='.length) : null };
+    for (const bindings of Object.values(info.HostConfig?.PortBindings ?? {})) {
+      for (const binding of bindings ?? []) {
+        const port = Number(binding?.HostPort);
+        if (Number.isInteger(port)) holders.set(port, holder);
+      }
+    }
+  }
+  return holders;
+}
+
+/** The port set the validators in lib/agent-ports.ts take. */
+export async function getUsedHostPorts(opts: { excludeContainerId?: string } = {}): Promise<Set<number>> {
+  return new Set((await getHostPortHolders(opts)).keys());
+}
+
+/** How a holder reads in an error: `agent_24a68ac9 (Drill Wake)`, or the name alone. */
+export function describeHolder(holder: HostPortHolder): string {
+  return holder.displayName ? `${holder.name} (${holder.displayName})` : holder.name;
 }

package/lib/agent-ports.ts

@@ -66,3 +66,26 @@ export function validatePortInput(input: string, usedPorts: ReadonlySet<number>
 export function portMappingArgs(start: number, end: number): string[] {
   return ['-p', end === start ? `${start}:3000` : `${start}-${end}:3000-${3000 + (end - start)}`];
 }
+
+/** The host ports a container publishes, from its inspect (`HostConfig.PortBindings`). */
+export function hostPortsFromBindings(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));
+}
+
+/** The host ports a `docker run` argument list publishes: `3700:3000` or `3700-3709:3000-3009`. */
+export function hostPortsFromArgs(portArgs: readonly string[]): number[] {
+  const ports: number[] = [];
+  for (let i = 0; i < portArgs.length - 1; i++) {
+    if (portArgs[i] !== '-p') continue;
+    const host = (portArgs[i + 1] ?? '').split(':')[0];
+    const [start, end] = host.split('-').map(Number);
+    if (!Number.isInteger(start)) continue;
+    for (let p = start; p <= (Number.isInteger(end) ? end : start); p++) ports.push(p);
+  }
+  return ports;
+}

package/lib/agent-recreate.ts

@@ -12,6 +12,8 @@
  */
 import { dockerFetch } from '@/lib/docker-socket';
 import { runDocker, resolveRecreateImage } from '@/lib/agent-images';
+import { hostPortsFromArgs } from '@/lib/agent-ports';
+import { getHostPortHolders, describeHolder, type HostPortHolder } from '@/lib/agent-ports-server';
 import { getMountFlags, applyRuntimeConfig } from '@/lib/agent-setup';
 import { isValidAgentId } from '@/lib/container';
 import { BACKUP_VOLUME, coldBackupStatus, isColdBackupRunning, startColdBackup, waitForColdBackup } from '@/lib/cold-backup';
@@ -30,12 +32,13 @@ const RECREATE_READY_TIMEOUT_MS = 5 * 60 * 1000;
 const COLD_BACKUP_WAIT_TIMEOUT_MS = 30 * 60 * 1000;
 
 export interface AgentContainerInspect {
+  Id?: string;
   Name?: string;
   Image?: string;
   Config?: { Image?: string; Env?: string[]; Labels?: Record<string, string> };
   State?: { Running?: boolean; Status?: string };
   HostConfig?: { NetworkMode?: string; PortBindings?: Record<string, { HostPort?: string }[] | null> };
-  NetworkSettings?: { Networks?: Record<string, unknown> };
+  NetworkSettings?: { Networks?: Record<string, unknown>; Ports?: Record<string, unknown> };
 }
 
 /** The container carrying `AGENT_ID=<agentId>`, inspected; null when there is none. */
@@ -48,6 +51,31 @@ export async function inspectAgentContainer(agentId: string): Promise<AgentConta
   return typeof info?.Id === 'string' ? info : null;
 }
 
+/**
+ * Start the container and confirm it really came back. A container can report
+ * `running` while its network endpoint failed to attach — the state a failed port bind
+ * leaves behind — which would otherwise pass as a successful start.
+ */
+export async function startAndVerifyContainer(agentId: string, name: string): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    await runDocker(['start', name], { timeoutMs: 60_000 });
+  } catch (e) {
+    return { ok: false, error: shortDockerError(e) };
+  }
+  const after = await inspectAgentContainer(agentId).catch(() => null);
+  if (!after?.State?.Running) return { ok: false, error: 'the container is not running' };
+  if (Object.keys(after.NetworkSettings?.Networks ?? {}).length === 0) {
+    return { ok: false, error: 'the container came up without a network (one of its ports is taken by another container)' };
+  }
+  return { ok: true };
+}
+
+/** A docker failure carries a whole stack trace; the first line is the useful part. */
+function shortDockerError(e: unknown): string {
+  const message = (e as Error)?.message ?? String(e);
+  return message.split('\n').map((l) => l.trim()).filter(Boolean)[0] ?? message;
+}
+
 /**
  * Remove the container and run a new one on `image` with the same parameters. The new
  * container is named after the agent id, as the create route names it. `opts.env`
@@ -88,6 +116,23 @@ export async function recreateAgentContainer(
     return ['-p', `${hostPort}:${containerPort.replace(/\/.*$/, '')}${proto}`];
   });
 
+  // Refuse on a port clash before anything is removed: the old container is the
+  // fallback the caller restarts, so a recreate refused here leaves the agent up. A
+  // clash cannot be recovered from by retrying, so it must not reach `docker run`.
+  const wanted = hostPortsFromArgs(portArgs);
+  if (wanted.length && container.Id) {
+    const held = await getHostPortHolders({ excludeContainerId: container.Id }).catch(() => new Map<number, HostPortHolder>());
+    const conflicts = wanted.filter((p) => held.has(p));
+    if (conflicts.length) {
+      const holders = [...new Set(conflicts.map((p) => describeHolder(held.get(p)!)))];
+      const many = conflicts.length > 1;
+      throw new Error(
+        `${many ? 'Ports' : 'Port'} ${conflicts.join(', ')} ${many ? 'are' : 'is'} already published by ${holders.join(', ')}. `
+        + 'Change this agent\'s port range in the Edit panel, then retry: nothing was changed.',
+      );
+    }
+  }
+
   const oldName = (container.Name ?? '').replace(/^\//, '') || agentId;
   await runDocker(['rm', '-f', oldName], { timeoutMs: 60_000 });
 
@@ -115,7 +160,16 @@ export async function recreateAgentContainer(
     console.warn(`[agent:recreate] docker run failed for ${agentId}, retrying:`, (first as Error).message);
     await runDocker(['rm', '-f', agentId], { timeoutMs: 60_000 }).catch(() => {});
     const retryImage = await resolveRecreateImage(container).catch(() => image);
-    await runDocker(runArgs(retryImage), { timeoutMs: 120_000, env });
+    try {
+      await runDocker(runArgs(retryImage), { timeoutMs: 120_000, env });
+    } catch (second) {
+      // `docker run` creates the container before its network step, so a failed start
+      // leaves a container behind — one that reports `running` with no network and
+      // would be picked up as if it were the agent. Remove it, so the state the caller
+      // reports matches reality.
+      await runDocker(['rm', '-f', agentId], { timeoutMs: 60_000 }).catch(() => {});
+      throw second;
+    }
   }
 }
 
@@ -267,9 +321,9 @@ async function finishInterruptedRecreate(agentId: string): Promise<void> {
   if (running) await waitForColdBackup(agentId).catch(() => null);
   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(() => {});
-  }
+  if (!name || container?.State?.Running) return;
+  const started = await startAndVerifyContainer(agentId, name);
+  if (!started.ok) console.warn(`[agent:recreate] ${agentId} did not come back after an interrupted recreate: ${started.error}`);
 }
 
 // ── Prerecreate retention ────────────────────────────────────────────────────

package/lib/agent-restore.ts

@@ -10,7 +10,7 @@
 import { isValidAgentId } from '@/lib/container';
 import { runDocker } from '@/lib/agent-images';
 import { BACKUP_VOLUME } from '@/lib/cold-backup';
-import { inspectAgentContainer } from '@/lib/agent-recreate';
+import { inspectAgentContainer, startAndVerifyContainer } from '@/lib/agent-recreate';
 import { activeRestoreAgentIds, insertRestore, isRestoreActive, latestRestore, markInterruptedRestores, updateRestoreRow, type AgentRestoreRow } from '@/lib/agent-restore-state';
 import { agentBusyReason } from '@/lib/agent-busy';
 
@@ -60,6 +60,7 @@ export async function startAgentRestore(agentId: string, file: string): Promise<
 async function runRestore(id: number, agentId: string, file: string): Promise<void> {
   const container = await inspectAgentContainer(agentId).catch(() => null);
   const name = container?.Name?.replace(/^\//, '');
+  let failure: string | null = null;
   try {
     if (name && container?.State?.Running) {
       await runDocker(['stop', '-t', '30', name], { timeoutMs: 45_000 }).catch(() => {});
@@ -77,16 +78,21 @@ async function runRestore(id: number, agentId: string, file: string): Promise<vo
       ],
       { timeoutMs: EXTRACT_TIMEOUT_MS, env: { FILE: file } },
     );
-
-    updateRestoreRow(id, { status: 'done' });
   } catch (e) {
-    updateRestoreRow(id, { status: 'failed', error: (e as Error)?.message ?? String(e) });
+    failure = (e as Error)?.message ?? String(e);
   } finally {
     // The container is started again even when the extract failed, so the agent never
-    // stays down. A volume with no container (volume-only agent) has nothing to start.
+    // stays down. The row is only `done` when it really came back: a container can
+    // report running while its network never attached, which is not a usable agent.
     if (name) {
-      await runDocker(['start', name], { timeoutMs: 60_000 }).catch(() => {});
+      const started = await startAndVerifyContainer(agentId, name);
+      if (!started.ok) {
+        const note = `the container did not come back: ${started.error}`;
+        failure = failure ? `${failure}; ${note}` : `the volume was restored, but ${note}`;
+      }
     }
+    if (failure) updateRestoreRow(id, { status: 'failed', error: failure });
+    else updateRestoreRow(id, { status: 'done' });
   }
 }
 
@@ -127,9 +133,9 @@ export async function recoverInterruptedRestores(): Promise<number> {
   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(() => {});
-    }
+    if (!name || container?.State?.Running) continue;
+    const started = await startAndVerifyContainer(agentId, name);
+    if (!started.ok) console.warn(`[agent:restore] ${agentId} did not come back after an interrupted restore: ${started.error}`);
   }
   return interrupted;
 }

package/lib/agent-update.ts

@@ -32,7 +32,7 @@ import {
   runDocker,
 } from '@/lib/agent-images';
 import { BACKUP_VOLUME, coldBackupStatus, isColdBackupRunning, startColdBackup, waitForColdBackup } from '@/lib/cold-backup';
-import { inspectAgentContainer, recreateAgentContainer, type AgentContainerInspect } from '@/lib/agent-recreate';
+import { inspectAgentContainer, recreateAgentContainer, startAndVerifyContainer, type AgentContainerInspect } from '@/lib/agent-recreate';
 import { applyRuntimeConfig } from '@/lib/agent-setup';
 import { waitForGatewayReady } from '@/lib/agent-readiness';
 import { patchRev4aProvider } from '@/app/api/gateway/sync';
@@ -251,12 +251,20 @@ async function runUpdate(id: number, agentId: string, name: string, fromVersion:
       .catch((err: unknown) => console.warn('[agent:update] image cleanup failed:', (err as Error).message));
   } catch (e) {
     // A failure before the recreate leaves the old container stopped by the backup:
-    // start it again, so a failed update never leaves the agent down.
+    // start it again, so a failed update never leaves the agent down. When it does not
+    // come back the failure text says so — a container that is "running" with no network
+    // is not an agent the operator can use.
     if (stopped) {
       const container = await inspectAgentContainer(agentId).catch(() => null);
       const containerName = container?.Name?.replace(/^\//, '');
       if (containerName && !container?.State?.Running) {
-        await runDocker(['start', containerName], { timeoutMs: 60_000 }).catch(() => {});
+        const started = await startAndVerifyContainer(agentId, containerName);
+        if (!started.ok) {
+          const note = `the previous container did not come back: ${started.error}`;
+          const message = shortError(e);
+          updateRow(id, { status: 'failed', error: `${message}; ${note}` });
+          return;
+        }
       }
     }
     updateRow(id, { status: 'failed', error: shortError(e) });
@@ -285,9 +293,9 @@ export async function recoverInterruptedUpdates(): Promise<number> {
   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(() => {});
-    }
+    if (!name || container?.State?.Running) continue;
+    const started = await startAndVerifyContainer(agentId, name);
+    if (!started.ok) console.warn(`[agent:update] ${agentId} did not come back after an interrupted update: ${started.error}`);
   }
   return interrupted;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flame0510/project-aether",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Rev4a — Revolution for Agents. OpenClaw agent fleet orchestrator.",
   "keywords": [
     "openclaw",