@flame0510/project-aether 1.4.0 → 1.4.2

package/app/agents/PageClient.tsx

@@ -770,6 +770,14 @@ function currentPortRange(ports: string): string {
   return min === max ? `${min}` : `${min}-${max}`;
 }
 
+/** The agent's own published host ports, from the `3700:3000, 3701:3001` string. */
+function ownHostPorts(ports: string): number[] {
+  return (ports || '')
+    .split(',')
+    .map((p) => parseInt(p.trim().split(':')[0] ?? '', 10))
+    .filter((n) => Number.isInteger(n));
+}
+
 function EditAgentModal({ agent, onClose, onSaved, onStarted }: {
   agent: Agent;
   onClose: () => void;
@@ -780,20 +788,37 @@ function EditAgentModal({ agent, onClose, onSaved, onStarted }: {
 }) {
   const initialName = agent.displayName || agent.name;
   const initialPorts = currentPortRange(agent.ports);
+  const ownPorts = useMemo(() => ownHostPorts(agent.ports), [agent.ports]);
   const [displayName, setDisplayName] = useState(initialName);
   const [portRange, setPortRange] = useState(initialPorts);
   const [saving, setSaving] = useState(false);
   const [error, setError] = useState('');
+  // The ports other containers hold, fetched when the panel opens: the same set the
+  // create form gets as a page prop, from the same lookup (`GET /api/agents/ports`).
+  const [usedPorts, setUsedPorts] = useState<Set<number> | null>(null);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    fetch('/api/agents/ports', { signal: controller.signal })
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data: { ports?: number[] } | null) => {
+        if (data && Array.isArray(data.ports)) setUsedPorts(new Set(data.ports));
+      })
+      .catch((e: unknown) => { if ((e as Error)?.name !== 'AbortError') setUsedPorts(null); });
+    return () => controller.abort();
+  }, []);
 
-  // Client-side shape checks (the same messages as the API). Whether a port is already
-  // published by another agent is checked by the server, which knows every container
-  // and excludes this agent's own block.
+  // The same rules and messages as agent creation (lib/agent-ports.ts). This agent's own
+  // block is excluded, so keeping or shifting it is not a conflict with itself; every
+  // other container counts, running or stopped.
   const nameError = displayName.trim() ? '' : 'Display name must not be empty';
   const portError = useMemo(() => {
     if (!portRange.trim()) return '';
-    const r = validatePortInput(portRange);
+    const others = new Set(usedPorts ?? []);
+    for (const p of ownPorts) others.delete(p);
+    const r = validatePortInput(portRange, others);
     return r.valid ? '' : r.error;
-  }, [portRange]);
+  }, [portRange, usedPorts, ownPorts]);
 
   const nameChanged = displayName.trim() !== initialName;
   const portsChanged = portRange.trim() !== initialPorts;
@@ -882,7 +907,7 @@ function EditAgentModal({ agent, onClose, onSaved, onStarted }: {
             {error && <div style={{ fontSize: 11, color: '#ef4444' }}>{error}</div>}
             <div style={{ display: 'flex', justifyContent: 'flex-end', gap: 8 }}>
               <Button variant="secondary" size="sm" onClick={onClose} disabled={saving}>Cancel</Button>
-              <Button variant="primary" size="sm" onClick={handleSave} disabled={saving}>
+              <Button variant="primary" size="sm" onClick={handleSave} disabled={saving || !!nameError || !!portError}>
                 {saving ? 'Saving...' : 'Save & Recreate'}
               </Button>
             </div>

package/app/agents/create/PageClient.tsx

@@ -60,6 +60,20 @@ export default function CreatePageClient({ templates, models, usedNames, usedPor
   const [selectedTemplate, setSelectedTemplate] = useState<string>('');
   const [agentName, setAgentName] = useState('');
   const [portRange, setPortRange] = useState<string>('');
+  // The server render seeds this; the same endpoint the Edit panel uses refreshes it, so
+  // both flows validate against the same numbers (every container, running or stopped).
+  const [usedPorts, setUsedPorts] = useState<number[]>(initialUsedPorts);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    fetch('/api/agents/ports', { signal: controller.signal })
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data: { ports?: number[] } | null) => {
+        if (data && Array.isArray(data.ports)) setUsedPorts(data.ports);
+      })
+      .catch(() => { /* the server still validates on submit */ });
+    return () => controller.abort();
+  }, []);
   const [selectedModel, setSelectedModel] = useState<string>(
     models.length > 0 ? models[0].id : ''
   );
@@ -73,11 +87,11 @@ export default function CreatePageClient({ templates, models, usedNames, usedPor
     setSelectedTemplate(id);
     setAgentName('');
     // Auto-assign port block: find first free 10-port block
-    if (initialUsedPorts.length === 0) {
+    if (usedPorts.length === 0) {
       setPortRange('3700-3709');
     } else {
-      // Simple client-side block finder
-      const block = initialUsedPorts.length ? findAvailablePortBlock(new Set(initialUsedPorts)) : null;
+      // Same block finder as the server: the first free 10-port block.
+      const block = findAvailablePortBlock(new Set(usedPorts));
       setPortRange(block ? `${block}-${block + 9}` : '');
     }
   };
@@ -91,9 +105,9 @@ export default function CreatePageClient({ templates, models, usedNames, usedPor
 
   const portError = useMemo(() => {
     if (!portRange.trim()) return '';
-    const res = validatePortInput(portRange, new Set(initialUsedPorts));
+    const res = validatePortInput(portRange, new Set(usedPorts));
     return res.valid ? '' : res.error;
-  }, [portRange, initialUsedPorts]);
+  }, [portRange, usedPorts]);
 
   const canProceed = (): boolean => {
     if (step === 'template') return selectedTemplate !== '';

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/agents/ports/route.ts

@@ -0,0 +1,19 @@
+import { NextResponse } from 'next/server';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { getUsedHostPorts } from '@/lib/agent-ports-server';
+
+export const dynamic = 'force-dynamic';
+
+/**
+ * GET /api/agents/ports
+ *
+ * The host ports held by any container, running or stopped — the set the port validators
+ * in lib/agent-ports.ts take. The create form receives it as a page prop; the Edit panel
+ * fetches it when it opens, so both flows validate a range against the same numbers and
+ * the same rules, and give the same message.
+ */
+export async function GET(request: Request): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+  const ports = await getUsedHostPorts();
+  return NextResponse.json({ ports: [...ports].sort((a, b) => a - b) });
+}

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,29 @@ 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.
+  The two forms validate a range **as it is typed** against that same set — the create
+  wizard through its page prop plus `GET /api/agents/ports`, the Edit panel through the
+  endpoint when it opens — so both show the same message and disable their action while
+  the range is refused, instead of letting the server refuse it on submit.
 - **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/FRONTEND-ARCHITECTURE.md

@@ -48,7 +48,7 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `ImageDownloadBanner` | `app/agents/ImageDownloadBanner.tsx` | Agent image banner on the Agents page. Polls `/api/agents/image-status` every 2 s; offers **Download Image** when no supported version is downloaded, **Download <version>** when the registry publishes a newer one, and shows the download in progress and its completion. Downloading changes no agent. |
 | `BrowserAccessSection` / `OpenControlUiButton` | `app/agents/BrowserAccessSection.tsx` | Browser access to one agent's Control UI, in its detail panel: requests waiting for approval (Approve / Reject) and approved browsers (Rename / Revoke), refreshed every 5 s while mounted. A successful approve, reject, rename or revoke updates the list at once, since the refresh behind it runs the OpenClaw CLI and takes seconds; a read started before the mutation is discarded. On agents that require approval, "Invite link" fetches `/api/agents/[id]/invite-link` and shows the link in a read-only field with Copy, which uses the Clipboard API in a secure context and the field's selection over plain HTTP, plus a warning when the link uses localhost. `OpenControlUiButton` opens `/api/agents/[id]/open-control-ui` in a new tab inside the click; that route redirects to a one-time link that pairs the browser with no approval, or to the plain token link when none can be issued. Used on the agent cards and in the panel. |
 | `ChannelManager` / `ChannelSection` | `app/agents/ChannelManager.tsx`, `ChannelSection` inline in `app/agents/PageClient.tsx` | Telegram, in the agent detail panel (`ChannelSection` is the card that opens the modal; the modal title is the agent's display name). Reads `GET /channels`; lists pending pairing requests with **Approve** (`POST /channels/pairing`) and approved senders with **Revoke** after a confirm (`DELETE /channels/pairing?senderId=`). Pending comes from `openclaw pairing list`, approved from OpenClaw's pairing store (`lib/channelManager.ts`). Polls pairings every 5 s while open; one keyed busy state per action. |
-| `EditAgentModal` / `EditBanner` | `app/agents/PageClient.tsx` | Rename/ports editing. The modal has **Display Name** and **Host Port** (same input and validation messages as the create wizard, from `lib/agent-ports.ts`), sends `PATCH /api/agents/[id]` and closes on `202`; `EditBanner` (top of the agent detail) polls `GET /api/agents/[id]` every 2 s while an edit is `rebuilding`, resumes on mount, and refetches the agent once it finishes, so a reload or a navigation shows the running edit instead of allowing a second (the server answers 409). No backup is taken: the volume is untouched. |
+| `EditAgentModal` / `EditBanner` | `app/agents/PageClient.tsx` | Rename/ports editing. The modal has **Display Name** and **Host Port** (same input and validation messages as the create wizard, from `lib/agent-ports.ts`), sends `PATCH /api/agents/[id]` and closes on `202`; `EditBanner` (top of the agent detail) polls `GET /api/agents/[id]` every 2 s while an edit is `rebuilding`, resumes on mount, and refetches the agent once it finishes, so a reload or a navigation shows the running edit instead of allowing a second (the server answers 409). No backup is taken: the volume is untouched. The port range is validated **as it is typed**: the modal fetches `GET /api/agents/ports` when it opens (the same set the create form uses, every container, running or stopped) and excludes the agent's own block, so an occupied range shows the API's message inline and the Save button stays disabled — the create wizard does the same with the same endpoint. |
 | `ModelSection` | `app/agents/ModelSection.tsx` | Primary model and fallbacks for one agent, in its detail panel. Explicit save, no restart. The model is a property of the agent, not of the gateway. Tags models the catalogue marks `deprecated`. |
 | `ModelsProvider` / `useModels` | `app/lib/models-context.tsx` | The client's single model list, from `/api/models`. Whatever changes what is offered calls `refresh()`: the Gateway page after a toggle, a key save or removal, or a sync, and the first-run wizard after saving keys. Everything else only reads, PulseChat included. |
 | `WizardPageClient` + step components | `app/wizard/PageClient.tsx` | Multi-step first-run wizard plus its frame shell, with mobile-first CSS. |

package/docs/dev/API-REFERENCE.md

@@ -704,6 +704,27 @@ List running agent containers (Docker containers with `AGENT_ID` label) with ful
 
 ---
 
+### `GET /api/agents/ports`
+The host ports held by any container, running or stopped: the set the validators in
+`lib/agent-ports.ts` take, sorted ascending. Backed by the shared lookup
+(`getUsedHostPorts()`, `lib/agent-ports-server.ts`), which reads every container's
+`HostConfig.PortBindings` — a stopped container keeps its block while `docker ps -a` and
+the API's container list report nothing for it.
+
+**Auth:** `rev4a_token` cookie or `Authorization: Bearer <REV4A_TOKEN>`
+
+**Response:**
+```json
+{ "ports": [3700, 3701, 3710, 3711, 3741, 5555] }
+```
+
+The Edit panel fetches it when it opens and the create form refreshes it on mount (the
+page also receives it as a prop), so both validate a range as the operator types, against
+the same numbers and with the same messages, and both disable their action while the range
+is refused.
+
+---
+
 ### `GET /api/agents/models-summary`
 One row per agent container, running or not: the model it runs and whether that
 model is still in good standing. Feeds the model chip on the agent cards. Running
@@ -795,7 +816,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 +825,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 +910,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 +2137,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.2",
   "description": "Rev4a — Revolution for Agents. OpenClaw agent fleet orchestrator.",
   "keywords": [
     "openclaw",