jishushell 0.4.2 → 0.4.17

package/dist/services/nomad-manager.js

@@ -3,14 +3,14 @@
  * Communicates with Nomad via its HTTP API.
  */
 import { execFile as execFileCb, execFileSync } from "child_process";
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs";
-import { homedir, platform, userInfo } from "os";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, symlinkSync } from "fs";
+import { homedir, userInfo } from "os";
 import { dirname } from "path";
 import { join } from "path";
 import { promisify } from "util";
-import { getNomadAddr, getNomadDriver, getNomadToken, getOpenclawDockerImage, isOfficialImage, JISHUSHELL_HOME } from "../config.js";
-import { TtlCache } from "../utils/ttl-cache.js";
-import { findInstancesSharingGatewayPort, findInstancesSharingOpenclawHome, getGatewayPort, getInstanceRuntime, getOpenclawConfigPath, getOpenclawHome, getRuntimeEnv } from "./instance-manager.js";
+import { getNomadAddr, getNomadDriver, getNomadToken, getOpenclawDockerImage } from "../config.js";
+import { ensureDirContainer, writeConfigFile } from "../utils/fs.js";
+import { findInstancesSharingOpenclawHome, getGatewayPort, getInstanceRuntime, getOpenclawConfigPath, getOpenclawHome, getRuntimeEnv, isPortInUse, reallocateGatewayPort, } from "./instance-manager.js";
 import { getLegacyStatus, stopInstance as stopLegacyInstance } from "./process-manager.js";
 // Docker image names must match this pattern to prevent command injection.
 export const DOCKER_IMAGE_RE = /^[a-zA-Z0-9][a-zA-Z0-9\-_.:/@]*$/;
@@ -31,7 +31,7 @@ function patchJsproxyBaseUrl(configPath) {
         const raw = readFileSync(configPath, "utf-8");
         const patched = raw.replace(/http:\/\/127\.0\.0\.1:(\d+)\/proxy/g, `http://host.docker.internal:$1/proxy`);
         if (patched !== raw) {
-            writeFileSync(configPath, patched, "utf-8");
+            writeConfigFile(configPath, patched);
             console.log(`[nomad] Patched jsproxy baseUrl in ${configPath} (127.0.0.1 → host.docker.internal)`);
         }
     }
@@ -66,7 +66,7 @@ function patchDockerBridgeGatewayBind(configPath) {
         const output = raw.endsWith("\n") ? `${next}\n` : next;
         if (output === raw)
             return;
-        writeFileSync(configPath, output, "utf-8");
+        writeConfigFile(configPath, output);
         console.log(`[nomad] Normalized gateway.bind to "lan" in ${configPath} for Docker bridge networking`);
     }
     catch (e) {
@@ -76,7 +76,80 @@ function patchDockerBridgeGatewayBind(configPath) {
 const DEFAULT_COMMAND = "/usr/bin/openclaw";
 const DEFAULT_PIDS_LIMIT = 512;
 export const VALID_LOG_TYPES = new Set(["stdout", "stderr"]);
-const memoryOversubscriptionCache = new TtlCache(30_000);
+// Path inside the openclaw-runtime Docker image where the baked-in openclaw
+// npm package lives. Referenced by the entrypoint shim as the fallback and
+// used by the control-UI "Update now" path through a pre-seeded symlink in
+// $HOME/.npm-global (see ensureOpenclawUpdateSeed below).
+const CONTAINER_IMAGE_PKG_ROOT = "/app/node_modules/openclaw";
+/**
+ * Pre-seed the per-instance npm global prefix with a symlink to the image's
+ * baked openclaw package so OpenClaw's in-gateway "Update now" handler can
+ * detect the install as an npm global install.
+ *
+ * Why this is needed: the control UI's Update now button fires `update.run`
+ * over the gateway WebSocket, which calls `runGatewayUpdate` in
+ * `openclaw/infra/update-runner`. That runner uses
+ * `detectGlobalInstallManagerForRoot`, which requires
+ * `realpath(<npm root -g>/openclaw) === realpath(pkgRoot)`. Inside our
+ * container pkgRoot resolves to `/app/node_modules/openclaw`, but
+ * `<npm root -g>/openclaw` (under $HOME/.npm-global because of
+ * `npm_config_prefix`) does not exist on first run — so the runner falls
+ * through to `status=skipped, reason=not-git-install` and the button
+ * appears to do nothing. Seeding a symlink
+ *   $HOME/.npm-global/lib/node_modules/openclaw -> /app/node_modules/openclaw
+ * makes the realpath comparison succeed, the runner takes the npm global
+ * branch, runs `npm i -g openclaw@latest`, and writes the upgraded package
+ * to the bind-mounted $HOME/.npm-global (replacing our symlink with a real
+ * directory). On the next container restart, the image entrypoint shim
+ * (/usr/local/bin/openclaw) picks up the upgraded openclaw.mjs from $HOME
+ * and execs it — matching OpenClaw's native upgrade UX end-to-end.
+ *
+ * The CLI path (`openclaw update` inside the container) is unaffected: it
+ * uses `updateStatus.installKind === "package"` → `runPackageInstallUpdate`,
+ * which never consults `detectGlobalInstallManagerForRoot`, so both the
+ * button and the CLI converge on the same `npm i -g openclaw@latest`.
+ *
+ * Idempotent: if the target path already exists (as a symlink or as a real
+ * upgraded directory) we leave it alone. Only runs for the docker driver.
+ */
+function ensureOpenclawUpdateSeed(instanceId) {
+    if (getNomadDriver() !== "docker")
+        return;
+    let home;
+    try {
+        home = getOpenclawHome(instanceId);
+    }
+    catch {
+        return;
+    }
+    if (!home)
+        return;
+    const linkDir = join(home, ".npm-global", "lib", "node_modules");
+    const linkPath = join(linkDir, "openclaw");
+    try {
+        lstatSync(linkPath);
+        // Already a symlink or real directory — leave alone.
+        return;
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT") {
+            console.warn(`[update-seed] lstat failed for ${linkPath}: ${err?.message ?? err}`);
+            return;
+        }
+    }
+    try {
+        mkdirSync(linkDir, { recursive: true });
+        // Target path is only resolvable inside the container's mount namespace.
+        // On the host it is a dead link; that is expected and harmless.
+        symlinkSync(CONTAINER_IMAGE_PKG_ROOT, linkPath);
+        console.log(`[update-seed] ${instanceId}: seeded ${linkPath} -> ${CONTAINER_IMAGE_PKG_ROOT}`);
+    }
+    catch (err) {
+        // Non-fatal: without the seed Update now falls back to today's "skipped"
+        // behavior, which is still no worse than current production.
+        console.warn(`[update-seed] ${instanceId}: failed to create seed: ${err?.message ?? err}`);
+    }
+}
 function nomadAuthHeaders() {
     const token = getNomadToken();
     return token ? { "X-Nomad-Token": token } : {};
@@ -142,23 +215,6 @@ async function nomadPut(path, body) {
         signal: AbortSignal.timeout(10000),
     });
 }
-async function getMemoryOversubscriptionState() {
-    const cached = memoryOversubscriptionCache.peek();
-    if (cached)
-        return cached;
-    try {
-        const resp = await nomadGet("/v1/operator/scheduler/configuration");
-        if (!resp.ok)
-            return "unknown";
-        const payload = await resp.json();
-        const state = payload?.SchedulerConfig?.MemoryOversubscriptionEnabled === true ? "enabled" : "disabled";
-        memoryOversubscriptionCache.set(state);
-        return state;
-    }
-    catch {
-        return "unknown";
-    }
-}
 // ── Nomad Variables (secrets) ──
 async function writeInstanceVariables(instanceId) {
     const jid = jobId(instanceId);
@@ -215,7 +271,12 @@ export async function purgeInstanceVariables(instanceId) {
     const varPath = `nomad/jobs/${jid}/openclaw/gateway`;
     const encodedPath = encodeURIComponent(varPath);
     try {
-        const resp = await nomadDelete(`/v1/var/${encodedPath}`);
+        // Match writeInstanceVariables symmetry: always pin the namespace on
+        // every Variables API call so the delete cannot drift into a different
+        // namespace if Nomad's default-namespace behaviour changes between
+        // minor versions. Without this, a schema tweak in a future 1.6.x point
+        // release could leave a stale secret behind after purge=true.
+        const resp = await nomadDelete(`/v1/var/${encodedPath}?namespace=default`);
         if (!resp.ok && resp.status !== 404) {
             console.warn(`[nomad] Failed to purge variables for ${instanceId}: HTTP ${resp.status}`);
         }
@@ -279,87 +340,72 @@ function buildRuntime(instanceId) {
         cwd: runtime.cwd || DEFAULT_CWD,
         env,
         resources,
+        image: runtime.image ?? null,
     };
 }
-function normalizeDockerResources(instanceId, runtime, oversubState) {
+function normalizeDockerResources(instanceId, runtime) {
     const requestedMemoryMB = Number(runtime.resources.MemoryMB ?? DEFAULT_RESOURCES.MemoryMB);
     let effectiveMemoryMB = requestedMemoryMB;
-    let effectiveMemoryMaxMB = Math.min(Number(runtime.resources.MemoryMaxMB ?? MAX_MEMORY_MAX_MB), MAX_MEMORY_MAX_MB);
+    let effectiveMemoryMaxMB = Math.min(Number(runtime.resources.MemoryMaxMB ?? requestedMemoryMB), MAX_MEMORY_MAX_MB);
     if (effectiveMemoryMaxMB < effectiveMemoryMB) {
         console.warn(`[nomad] ${instanceId}: MemoryMaxMB (${effectiveMemoryMaxMB}) is below MemoryMB (${effectiveMemoryMB}); clamping max to reservation.`);
         effectiveMemoryMaxMB = effectiveMemoryMB;
     }
-    if (oversubState === "disabled" && effectiveMemoryMaxMB > effectiveMemoryMB) {
-        console.warn(`[nomad] ${instanceId}: memory oversubscription is disabled; promoting MemoryMB ` +
-            `from ${effectiveMemoryMB}MB to ${effectiveMemoryMaxMB}MB so the Docker limit matches MemoryMaxMB.`);
-        effectiveMemoryMB = effectiveMemoryMaxMB;
-    }
     return {
         ...runtime.resources,
         MemoryMB: effectiveMemoryMB,
         MemoryMaxMB: effectiveMemoryMaxMB,
     };
 }
-function buildTaskDocker(instanceId, runtime, oversubState) {
+function buildTaskDocker(instanceId, runtime) {
     // Guard against Nomad Template injection: validate the job ID contains no
     // template metacharacters before interpolating it into EmbeddedTmpl.
     const safeJobId = jobId(instanceId);
     assertSafeTemplateId(safeJobId);
     const openclawHome = getOpenclawHome(instanceId);
-    const image = getOpenclawDockerImage();
-    // Image classification:
-    // - Official: ghcr.io/openclaw/openclaw:* — binary baked in, no bind-mount needed
-    // - Slim base: jishushell-base:* — binary bind-mounted from host npm package (legacy)
-    // - Local/other: openclaw:* or custom images
-    const _isOfficialImage = isOfficialImage(image);
-    const isSlimBaseImage = /^jishushell-base:/i.test(image);
-    // node_modules parent dir — contains openclaw package AND all its sibling dependencies
-    const openclawNmDir = join(JISHUSHELL_HOME, "packages", "openclaw", "node_modules");
-    const openclawAppDir = join(openclawHome, "app");
+    const image = runtime.image || getOpenclawDockerImage();
     const volumes = [
         `${openclawHome}:${openclawHome}:rw`,
-        // Only slim base needs the bind-mount; official and local images have the binary baked in.
-        ...(isSlimBaseImage ? [`${openclawNmDir}:/usr/lib/node_modules:ro`] : []),
-        // Official image: persist /app so OpenClaw can self-upgrade and install plugins.
-        ...(_isOfficialImage ? [`${openclawAppDir}:/app:rw`] : []),
     ];
     const containerEnv = { ...runtime.env };
-    containerEnv.PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
-    const isLocalImage = !image.includes("/"); // e.g. "openclaw:v1.0" vs "ghcr.io/..."
-    // Container runs as uid 1000 (node user in the image). Always set HOME to
-    // /home/node which exists in the image and is writable (npm cache, etc).
-    // The host HOME (/home/pi) does not exist inside the container.
-    containerEnv.HOME = "/home/node";
+    // Set HOME to the bind-mounted openclaw-home directory so that user-level
+    // installs (pip install --user, npm cache, etc.) persist across restarts.
+    containerEnv.HOME = openclawHome;
     // Plugins (e.g. openclaw-weixin) use OPENCLAW_STATE_DIR to find credentials.
-    // Inside Docker, HOME differs from the host, so set this explicitly.
     if (!containerEnv.OPENCLAW_STATE_DIR) {
         containerEnv.OPENCLAW_STATE_DIR = `${openclawHome}/.openclaw`;
     }
+    // State cohesion: redirect all user-level installs to HOME
+    containerEnv.npm_config_prefix = `${openclawHome}/.npm-global`;
+    containerEnv.PIP_USER = "1";
+    containerEnv.PYTHONUSERBASE = `${openclawHome}/.local`;
+    containerEnv.NODE_ENV = "production";
+    // Let plugins in the bind-mounted extensions dir resolve openclaw/plugin-sdk.
+    // Prefer user-upgraded openclaw (in HOME/.npm-global), fall back to container built-in.
+    containerEnv.NODE_PATH = [
+        `${openclawHome}/.npm-global/lib/node_modules`,
+        "/app/node_modules",
+    ].join(":");
+    // PATH: HOME bin dirs first (upgraded OpenClaw, pip, go, cargo), then system
+    containerEnv.PATH = [
+        `${openclawHome}/.npm-global/bin`,
+        `${openclawHome}/.local/bin`,
+        `${openclawHome}/go/bin`,
+        `${openclawHome}/.cargo/bin`,
+        "/usr/local/sbin",
+        "/usr/local/bin",
+        "/usr/sbin",
+        "/usr/bin",
+        "/sbin",
+        "/bin",
+    ].join(":");
     const runtimeArgs = [...(runtime.args || [])];
-    let commandConfig;
-    if (_isOfficialImage) {
-        // Official/custom image ENTRYPOINT is docker-entrypoint.sh (from node base).
-        // Prepend "openclaw" so the entrypoint execs: openclaw gateway run ...
-        commandConfig = { args: ["openclaw", ...runtimeArgs] };
-    }
-    else if (isSlimBaseImage) {
-        // Slim base image: ENTRYPOINT is ["node", "/usr/lib/node_modules/openclaw/openclaw.mjs"]
-        // which uses the bind-mounted binary. Just pass gateway args, no command override needed.
-        commandConfig = { args: runtimeArgs };
-    }
-    else if (isLocalImage) {
-        // Local image has /usr/local/bin/openclaw symlink baked in.
-        commandConfig = { command: "/usr/local/bin/openclaw", args: runtimeArgs };
-    }
-    else {
-        commandConfig = { command: "/usr/local/bin/openclaw", args: runtimeArgs };
-    }
     // Only the gateway port is published to the host; all other container ports stay
     // hidden. Bridge networking gives each container an isolated network namespace;
     // extra_hosts injects the host gateway IP so the container can still reach the
     // JishuShell LLM proxy on the host without needing host-mode networking.
     const gatewayPort = getGatewayPort(instanceId);
-    const normalizedResources = normalizeDockerResources(instanceId, runtime, oversubState);
+    const normalizedResources = normalizeDockerResources(instanceId, runtime);
     return {
         Name: "gateway",
         Driver: "docker",
@@ -367,33 +413,26 @@ function buildTaskDocker(instanceId, runtime, oversubState) {
         User: resolveUidGid(runtime.user),
         Config: {
             image,
-            // Local build: never force pull. Use local image cache.
             force_pull: false,
-            ...commandConfig,
+            args: runtimeArgs,
+            work_dir: openclawHome,
             volumes,
-            // Bridge mode (default): container gets an isolated network namespace.
-            // host.docker.internal resolves to the host's gateway IP on the bridge
-            // (172.17.0.1 or equivalent) so the container can call 127.0.0.1-bound
-            // host services via http://host.docker.internal:<port> instead.
             extra_hosts: ["host.docker.internal:host-gateway"],
             cap_drop: ["ALL"],
-            security_opt: ["no-new-privileges"], // block setuid/setgid escalation
-            pids_limit: DEFAULT_PIDS_LIMIT, // prevent fork bomb
-            // Official image: writable rootfs (users may install packages / upgrade inside the container).
-            // Other images: read-only rootfs for security.
-            readonly_rootfs: !_isOfficialImage,
+            security_opt: ["no-new-privileges"],
+            pids_limit: DEFAULT_PIDS_LIMIT,
+            readonly_rootfs: true,
             // Provide a writable /tmp via mount config (Nomad docker driver
             // doesn't support top-level "tmpfs" field in older versions).
-            mounts: [{ type: "tmpfs", target: "/tmp", tmpfs_options: { size: 67108864 } }],
+            mounts: [
+                { type: "tmpfs", target: "/tmp", tmpfs_options: { size: 536870912 } },
+                { type: "tmpfs", target: "/var/tmp", tmpfs_options: { size: 67108864 } },
+                { type: "tmpfs", target: "/run", tmpfs_options: { size: 52428800 } },
+            ],
         },
         Env: containerEnv,
         Resources: {
             ...normalizedResources,
-            // When memory oversubscription is enabled, MemoryMB is the scheduler
-            // reservation and MemoryMaxMB is the burst ceiling / container hard limit.
-            // When it is disabled, Nomad ignores MemoryMaxMB and enforces MemoryMB as
-            // the Docker limit, so normalizeDockerResources() promotes MemoryMB to the
-            // configured max to preserve user intent.
             // Statically reserve the gateway port on the host so Nomad can track it and
             // detect conflicts across instances before the container even starts.
             // In bridge mode Nomad maps this host port to the same container port.
@@ -416,11 +455,10 @@ async function buildJob(instanceId) {
     const jid = jobId(instanceId);
     const runtime = buildRuntime(instanceId);
     const driver = getNomadDriver();
-    const oversubState = await getMemoryOversubscriptionState();
     if (driver !== "docker") {
         throw new Error(`Unsupported Nomad driver: ${driver}. Only "docker" is supported.`);
     }
-    const task = buildTaskDocker(instanceId, runtime, oversubState);
+    const task = buildTaskDocker(instanceId, runtime);
     return {
         Job: {
             ID: jid,
@@ -489,7 +527,22 @@ export async function shouldAutoStart(instanceId) {
     const jid = jobId(instanceId);
     try {
         const resp = await nomadGet(`/v1/job/${jid}`);
-        if (!resp.ok || resp.status === 404)
+        // 404 = nomad has no record of this job. Two cases:
+        //   (a) Raft was wiped — e.g. Nomad 1.11.3 → 1.6.5 auto-migration
+        //       (install/jishu-install.sh:_migrate_nomad_to_target). The
+        //       on-disk instance config is still present and MUST be
+        //       resubmitted on the next jishushell startup, otherwise every
+        //       OpenClaw instance silently disappears after the upgrade.
+        //   (b) Brand-new instance created without a default_provider, never
+        //       started via /api/instances/.../service/start. Resubmitting it
+        //       here is a safe superset — the Nomad job is idempotent and the
+        //       container starts whether or not a provider is configured; the
+        //       user still needs to configure one to answer chat.
+        // Returning true on 404 covers (a); (b) is an accepted side effect and
+        // does not regress any user-facing behaviour.
+        if (resp.status === 404)
+            return true;
+        if (!resp.ok)
             return false;
         const job = await resp.json();
         // Stop=true means user explicitly stopped it; Stop=false means it was running.
@@ -597,18 +650,23 @@ export async function startInstance(instanceId) {
             error: `This instance shares OPENCLAW_HOME with running instance(s): ${homeConflicts.join(", ")}. Move it to its own instance directory before starting it.`,
         };
     }
-    const portConflicts = [];
-    for (const otherId of findInstancesSharingGatewayPort(instanceId)) {
-        const otherStatus = await getStatus(otherId);
-        if (otherStatus.status === "running")
-            portConflicts.push(otherId);
-    }
-    if (portConflicts.length) {
-        const port = getGatewayPort(instanceId);
-        return {
-            ok: false,
-            error: `Gateway port ${port} is already in use by running instance(s): ${portConflicts.join(", ")}. Assign a different port before starting this instance.`,
-        };
+    // Host port probe + self-heal. Replaces an older sibling-instance-only
+    // check with a real socket probe so we also catch host-side openclaw,
+    // unrelated services that grabbed the port at boot, and Docker port maps
+    // belonging to other jishushell instances. If the port we previously
+    // assigned is held now, we re-pick the next free port and rewrite this
+    // instance's runtime metadata in place; the Nomad job spec is rebuilt
+    // from metadata on every submit so no further patching is needed.
+    let portAllocation = null;
+    const desiredPort = getGatewayPort(instanceId);
+    if (await isPortInUse(desiredPort)) {
+        try {
+            const re = await reallocateGatewayPort(instanceId);
+            portAllocation = { from: re.from, to: re.to, reason: "host_port_busy" };
+        }
+        catch (e) {
+            return { ok: false, error: `Gateway port ${desiredPort} is held by another process and reallocation failed: ${e?.message ?? e}` };
+        }
     }
     const legacyStatus = await getLegacyStatus(instanceId);
     if (legacyStatus.status === "running") {
@@ -621,66 +679,52 @@ export async function startInstance(instanceId) {
     if (!existsSync(configPath)) {
         return { ok: false, error: "Config file not found" };
     }
-    mkdirSync(dirname(configPath), { recursive: true, mode: 0o750 });
-    // Ensure Docker image exists when using docker driver
     if (getNomadDriver() === "docker") {
-        // Docker Desktop on macOS uses virtio-fs: the container process isn't recognized
-        // as the file owner even when uid matches. The .openclaw dir needs 0o777 so the
-        // container can create .tmp files for atomic config writes. Files need 0o644 so
-        // the container can read the config. Applied here to fix existing instances too.
-        // On Linux/RPi 0o755 is sufficient — Docker maps the host uid correctly.
         const stateDir = dirname(configPath);
-        chmodSync(stateDir, platform() === "darwin" ? 0o777 : 0o750);
-        chmodSync(configPath, platform() === "darwin" ? 0o644 : 0o600);
-        // Bridge mode needs a non-loopback gateway bind inside the container.
+        ensureDirContainer(stateDir);
+        try {
+            for (const entry of readdirSync(stateDir, { withFileTypes: true })) {
+                if (entry.isDirectory()) {
+                    const sub = join(stateDir, entry.name);
+                    ensureDirContainer(sub);
+                    try {
+                        for (const child of readdirSync(sub, { withFileTypes: true })) {
+                            if (child.isDirectory())
+                                ensureDirContainer(join(sub, child.name));
+                        }
+                    }
+                    catch (_) { }
+                }
+            }
+        }
+        catch (_) { }
+        if (existsSync(configPath))
+            chmodSync(configPath, 0o644);
         patchDockerBridgeGatewayBind(configPath);
         // Bridge mode: rewrite 127.0.0.1 → host.docker.internal in jsproxy baseUrl
         // so the container can reach the JishuShell LLM proxy on the host.
         patchJsproxyBaseUrl(configPath);
+        // Seed $HOME/.npm-global so OpenClaw's in-gateway Update now handler can
+        // detect the install as an npm global package and run `npm i -g openclaw`.
+        ensureOpenclawUpdateSeed(instanceId);
         const image = getOpenclawDockerImage();
         // validate image name format and length.
         if (!DOCKER_IMAGE_RE.test(image) || image.length > MAX_DOCKER_IMAGE_NAME_LEN) {
             return { ok: false, error: `Invalid Docker image name: "${image}"` };
         }
-        // Initialize persistent /app directory for official images on first start.
-        // Copy the image's /app contents to the host so OpenClaw can self-upgrade.
-        if (isOfficialImage(image)) {
-            const appDir = join(getOpenclawHome(instanceId), "app");
-            mkdirSync(appDir, { recursive: true, mode: 0o755 });
-            const isEmpty = readdirSync(appDir).length === 0;
-            if (isEmpty) {
-                console.log(`[nomad] Initializing /app for ${instanceId} from image ${image}...`);
-                const tmpName = `jishushell-init-${instanceId}-${Date.now()}`;
-                try {
-                    execFileSync("docker", ["create", "--name", tmpName, image], { timeout: 30000, stdio: "ignore" });
-                    execFileSync("docker", ["cp", `${tmpName}:/app/.`, appDir], { timeout: 120000, stdio: "ignore" });
-                    execFileSync("docker", ["rm", tmpName], { timeout: 10000, stdio: "ignore" });
-                }
-                catch (e) {
-                    try {
-                        execFileSync("docker", ["rm", "-f", tmpName], { timeout: 10000, stdio: "ignore" });
-                    }
-                    catch { }
-                    console.error(`[nomad] Failed to initialize /app for ${instanceId}: ${e.message}`);
-                    return { ok: false, error: `Failed to initialize OpenClaw app directory: ${e.message}` };
-                }
-            }
-        }
         try {
             execFileSync("docker", ["image", "inspect", image], { timeout: 10000, stdio: "ignore" });
         }
         catch {
-            // Image not found locally — kick off a background build and return
-            // immediately so the API doesn't block for 5-10 minutes on RPi.
-            console.log(`[nomad] Docker image ${image} not found, starting background build...`);
+            // Image not found locally — kick off a background pull (with local build
+            // fallback) and return immediately so the API doesn't block.
+            console.log(`[nomad] Docker image ${image} not found, starting background pull...`);
             try {
                 const setupManager = await import("./setup-manager.js");
-                const result = isOfficialImage(image)
-                    ? setupManager.startBuildCustomOpenclawImage(image)
-                    : setupManager.startBuildOpenclawDockerImage(image);
+                const result = setupManager.startBuildSlimOpenclawImage(image);
                 return {
                     ok: false,
-                    error: `Docker image ${image} not found. Build started in background.`,
+                    error: `Docker image ${image} not found. Pull started in background.`,
                     building: true,
                     taskId: result.taskId,
                 };
@@ -699,19 +743,42 @@ export async function startInstance(instanceId) {
     catch (e) {
         return { ok: false, error: `Failed to store instance secrets in Nomad Variables: ${e.message}` };
     }
-    const jobDef = await buildJob(instanceId);
-    try {
-        const resp = await nomadPost("/v1/jobs", jobDef);
-        if (resp.ok) {
-            const data = await resp.json();
-            return { ok: true, eval_id: data.EvalID };
+    // Submit to Nomad with a single retry on port race: between our earlier
+    // host probe and Docker's actual bind, another process could have grabbed
+    // the port. On submit failure we re-probe; if the port is now busy we
+    // reallocate once and try again, otherwise we return the original error.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const jobDef = await buildJob(instanceId);
+        let submitError = null;
+        let netErr = false;
+        try {
+            const resp = await nomadPost("/v1/jobs", jobDef);
+            if (resp.ok) {
+                const data = await resp.json();
+                return {
+                    ok: true,
+                    eval_id: data.EvalID,
+                    ...(portAllocation ? { port_allocation: portAllocation } : {}),
+                };
+            }
+            submitError = await resp.text();
         }
-        return { ok: false, error: await resp.text() };
-    }
-    catch (e) {
-        const isNetErr = e?.message === "fetch failed" || e?.cause?.code === "ECONNREFUSED";
-        return { ok: false, error: isNetErr ? `Nomad 服务不可达 (${getNomadAddr()})，请先启动 Nomad` : e.message };
+        catch (e) {
+            netErr = e?.message === "fetch failed" || e?.cause?.code === "ECONNREFUSED";
+            submitError = netErr ? `Nomad 服务不可达 (${getNomadAddr()})，请先启动 Nomad` : e.message;
+        }
+        if (attempt === 0 && !netErr && (await isPortInUse(getGatewayPort(instanceId)))) {
+            try {
+                const re = await reallocateGatewayPort(instanceId);
+                portAllocation = { from: re.from, to: re.to, reason: "docker_race" };
+                console.log(`[nomad] ${instanceId}: retrying after docker port race (${re.from} -> ${re.to})`);
+                continue;
+            }
+            catch { /* fall through to error return */ }
+        }
+        return { ok: false, error: submitError ?? "unknown error" };
     }
+    return { ok: false, error: "start retry exhausted" };
 }
 export async function stopInstance(instanceId, purge = false) {
     const jid = jobId(instanceId);
@@ -782,6 +849,7 @@ export async function getLogs(instanceId, lines = 200, logType = "stderr") {
     }
     if (!alloc)
         return [];
+    // Primary: Nomad log API
     try {
         const params = new URLSearchParams({
             task: "gateway",
@@ -794,10 +862,46 @@ export async function getLogs(instanceId, lines = 200, logType = "stderr") {
         const resp = await nomadGet(`/v1/client/fs/logs/${alloc.ID}?${params}`);
         if (resp.ok) {
             const text = await resp.text();
-            return text.split("\n").slice(-lines);
+            const trimmed = text.trim();
+            if (trimmed)
+                return trimmed.split("\n").slice(-lines);
         }
     }
     catch { /* ignore */ }
+    // Fallback: fetch logs directly from Docker.
+    // Used when Nomad is configured with disable_log_collection=true.
+    const containerName = `gateway-${alloc.ID}`;
+    try {
+        const dockerArgs = [
+            "logs",
+            "--tail", String(lines),
+            ...(logType === "stderr" ? ["--stdout=false", "--stderr=true"]
+                : logType === "stdout" ? ["--stdout=true", "--stderr=false"]
+                    : []),
+            containerName,
+        ];
+        const { stdout, stderr } = await execFileAsync("docker", dockerArgs, { timeout: 10_000 });
+        const combined = (logType === "stdout" ? stdout : stderr || stdout).trim();
+        if (combined)
+            return combined.split("\n").slice(-lines);
+    }
+    catch { /* container may not exist, or docker unavailable */ }
+    // Last resort: sudo docker logs (user not in docker group)
+    try {
+        const dockerArgs = [
+            "-n", "docker", "logs",
+            "--tail", String(lines),
+            ...(logType === "stderr" ? ["--stdout=false", "--stderr=true"]
+                : logType === "stdout" ? ["--stdout=true", "--stderr=false"]
+                    : []),
+            containerName,
+        ];
+        const { stdout, stderr } = await execFileAsync("sudo", dockerArgs, { timeout: 10_000 });
+        const combined = (logType === "stdout" ? stdout : stderr || stdout).trim();
+        if (combined)
+            return combined.split("\n").slice(-lines);
+    }
+    catch { /* ignore */ }
     return [];
 }
 const execFileAsync = promisify(execFileCb);