fix(sandbox): start a stopped container during probe-only recovery

docs/manage-sandboxes/recover-rebuild-sandboxes.mdx

@@ -51,8 +51,15 @@ When the OpenClaw gateway is healthy, rerun `shields up`.
 
 ## Recover the Agent Runtime
 
+<AgentOnly variant="openclaw,hermes">
+`recover` can start an existing stopped Docker-driver container before it repairs the agent runtime.
+It starts only a non-paused container that Docker still associates with the registered sandbox.
+It leaves a running or paused container unchanged.
+If Docker cannot start the container, recovery continues to the OpenShell readiness check and reports the resulting failure.
+</AgentOnly>
+
 <AgentOnly variant="openclaw">
-If `$$nemoclaw <name> status` reports the sandbox is alive but the gateway is not running, run the recover command instead of opening a shell.
+If `$$nemoclaw <name> status` reports the sandbox container or gateway is not running, run the recover command instead of opening a shell.
 
 ```bash
 $$nemoclaw <sandbox-name> recover
@@ -75,7 +82,7 @@ Refer to [`$$nemoclaw <name> recover`](../../reference/commands#$$nemoclaw-name-
 </AgentOnly>
 
 <AgentOnly variant="hermes">
-If `$$nemoclaw <name> status` reports the sandbox is alive but the Hermes gateway is not running, run the recover command instead of opening a shell.
+If `$$nemoclaw <name> status` reports the sandbox container or Hermes gateway is not running, run the recover command instead of opening a shell.
 
 ```bash
 $$nemoclaw <sandbox-name> recover

docs/reference/commands.mdx

@@ -1522,7 +1522,11 @@ A surviving server keeps its recorded endpoint and address pins while its policy
 ### `$$nemoclaw <name> recover`
 
 Repair a stopped in-sandbox gateway and re-establish host-side forwards without opening an SSH session.
-Use this after a direct sandbox container restart, a sandbox crash, or whenever `$$nemoclaw <name> status` reports the gateway is not running but the sandbox is alive.
+Use this after a sandbox crash or whenever `$$nemoclaw <name> status` reports that the sandbox container or agent gateway is not running.
+
+For a stopped, non-paused Docker-driver container, `recover` starts the existing container before it waits for OpenShell readiness.
+It leaves a running or paused container unchanged.
+If Docker cannot start the container, `recover` continues to the readiness check and reports the resulting failure.
 
 `recover` waits up to 30 seconds to acquire the per-sandbox lifecycle lock.
 After acquisition, it holds the lock until gateway recovery and forward repair finish.

docs/reference/troubleshooting.mdx

@@ -1561,30 +1561,39 @@ Use the lightest recovery path first instead of rebuilding immediately.
    docker ps -a --filter "label=openshell.ai/sandbox-name=<name>"
    ```
 
-   If a container is listed, start it:
+1. Run recovery from the host.
+
+<AgentOnly variant="openclaw,hermes">
 
    ```bash
-   docker start <container-name>
+   $$nemoclaw <name> recover
    ```
 
-1. Run status recovery from the host.
+   For a stopped, non-paused Docker-driver container, `recover` starts the existing container before it waits for OpenShell readiness.
+   It leaves a running or paused container unchanged.
+   If Docker cannot start the container, the command continues to the readiness check and reports the resulting failure.
+
+</AgentOnly>
+
+<AgentOnly variant="deepagents">
 
    ```bash
    $$nemoclaw <name> status
    ```
 
-   On Docker-driver hosts, status also attempts non-destructive recovery when OpenShell reports the sandbox as missing but Docker still has a stopped `openshell.ai/sandbox-name=<name>` container or the latest GPU-backup sibling.
-   A successful recovery prints that the sandbox was recovered from Docker and then shows the refreshed OpenShell state.
+   Deep Agents Code does not provide the `recover` command.
+   Use `$$nemoclaw <name> start` to start its existing container.
 
-<AgentOnly variant="openclaw,hermes">
+</AgentOnly>
 
-1. If the sandbox is running but the agent gateway or dashboard forward is still down, recover the in-sandbox gateway and forwards:
+1. Check status from the host.
 
    ```bash
-   $$nemoclaw <name> recover
+   $$nemoclaw <name> status
    ```
 
-</AgentOnly>
+   On Docker-driver hosts, status also attempts non-destructive recovery when OpenShell reports the sandbox as missing but Docker still has a stopped `openshell.ai/sandbox-name=<name>` container or the latest GPU-backup sibling.
+   A successful recovery prints that the sandbox was recovered from Docker and then shows the refreshed OpenShell state.
 
 1. Rebuild only if the sandbox cannot be restarted or status still cannot recover it while the local registry entry exists:
 

src/lib/actions/sandbox/connect-probe-observe.test.ts

@@ -123,6 +123,69 @@ describe("connectSandbox probe-only observe mode", () => {
     expect(harness.checkAndRecoverSpy).not.toHaveBeenCalled();
   });
 
+  it("starts a stopped container before readiness polling begins (#8967)", async () => {
+    const harness = createConnectHarness({
+      dockerRuntime: { containerName: "openshell-alpha", running: false, paused: false },
+    });
+
+    await expect(harness.connectSandbox("alpha", { probeOnly: true })).resolves.toBeUndefined();
+
+    expect(harness.dockerStartSpy).toHaveBeenCalledOnce();
+    expect(harness.dockerStartSpy).toHaveBeenCalledWith(
+      "openshell-alpha",
+      expect.objectContaining({ ignoreError: true }),
+    );
+    const listInvocations = harness.captureOpenshellSpy.mock.calls
+      .map((call, index) => ({
+        call,
+        order: harness.captureOpenshellSpy.mock.invocationCallOrder[index]!,
+      }))
+      .filter(
+        ({ call }) =>
+          Array.isArray(call?.[0]) &&
+          (call[0] as string[])[0] === "sandbox" &&
+          (call[0] as string[])[1] === "list",
+      );
+    expect(listInvocations.length).toBeGreaterThan(0);
+    // The container must be started before recovery starts polling for readiness,
+    // otherwise the wait loop observes a stopped container until it times out.
+    expect(harness.dockerStartSpy.mock.invocationCallOrder[0]!).toBeLessThan(
+      listInvocations[0]!.order,
+    );
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it("continues readiness polling when Docker cannot start a stopped container (#8967)", async () => {
+    const harness = createConnectHarness({
+      dockerRuntime: { containerName: "openshell-alpha", running: false, paused: false },
+      dockerStartStatus: 1,
+      listOutput: "alpha Ready",
+    });
+
+    await expect(harness.connectSandbox("alpha", { probeOnly: true })).resolves.toBeUndefined();
+
+    expect(harness.dockerStartSpy).toHaveBeenCalledOnce();
+    expect(harness.errorSpy.mock.calls.map(([line]) => String(line)).join("\n")).toContain(
+      "Docker could not start container 'openshell-alpha' (exit 1); continuing with readiness checks.",
+    );
+    expect(
+      harness.captureOpenshellSpy.mock.calls.some(
+        ([args]) => Array.isArray(args) && args[0] === "sandbox" && args[1] === "list",
+      ),
+    ).toBe(true);
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it("leaves a running container untouched on probe-only recovery (#8967)", async () => {
+    const harness = createConnectHarness({
+      dockerRuntime: { containerName: "openshell-alpha", running: true, paused: false },
+    });
+
+    await expect(harness.connectSandbox("alpha", { probeOnly: true })).resolves.toBeUndefined();
+
+    expect(harness.dockerStartSpy).not.toHaveBeenCalled();
+  });
+
   it("suggests a longer equivalent retry when probe-only readiness times out", async () => {
     vi.spyOn(Date, "now").mockReturnValueOnce(0).mockReturnValue(300_001);
     const harness = createConnectHarness({ listOutput: "alpha Starting" });

src/lib/actions/sandbox/connect.ts

@@ -76,6 +76,7 @@ import {
   ensureLiveSandboxOrExit,
   printGatewayLifecycleHint,
   recoverPortableDemoSandboxLifecycleForConnect,
+  startStoppedSandboxContainerForProbeRecovery,
 } from "./gateway-state";
 import { getSandboxTargetGatewayName } from "./gateway-target";
 import { printGatewayWedgeDiagnostics } from "./gateway-wedge-diagnostics";
@@ -1279,6 +1280,9 @@ export async function connectSandbox(
       const publicationRequest = publicationFromDecision(sandboxName, readiness);
       const gated = await withLaunchReadinessMutationGate(publicationRequest, async () => {
         await runConnectEntryPreflight(sandboxName, { probeOnly: true });
+        // Restart a stopped container before the readiness wait. Without this step,
+        // OpenShell keeps reporting the stopped sandbox until the wait expires (#8967).
+        startStoppedSandboxContainerForProbeRecovery(sandboxName);
         waitForSandboxReadyOrExit(sandboxName, {
           defaultTimeoutSec: 300,
           retryCommand: "connect --probe-only",

src/lib/actions/sandbox/gateway-state.ts

@@ -23,6 +23,7 @@ const { pruneKnownHostsEntries } = require("../../onboard/known-hosts") as {
   pruneKnownHostsEntries: (contents: string) => string;
 };
 
+import { dockerStart } from "../../adapters/docker/container";
 import { stripAnsi } from "../../adapters/openshell/client";
 import {
   detectOpenShellStateRpcPreflightIssue,
@@ -42,7 +43,7 @@ import {
   OPENSHELL_OPERATION_TIMEOUT_MS,
   OPENSHELL_PROBE_TIMEOUT_MS,
 } from "../../adapters/openshell/timeouts";
-import { D, R } from "../../cli/terminal-style";
+import { D, G, R } from "../../cli/terminal-style";
 import {
   type DockerDriverRecoveryResult,
   recoverDockerDriverSandbox,
@@ -617,6 +618,38 @@ export async function getReconciledSandboxGatewayState(
   return lookup;
 }
 
+const RECOVER_CONTAINER_START_TIMEOUT_MS = 30_000;
+
+/**
+ * Start a sandbox's Docker container when it exists but is stopped, before the
+ * probe-only readiness wait begins polling. `recover` and `connect --probe-only`
+ * both advertise that they restart a stopped sandbox, but the wait loop only
+ * observes readiness. A container in `exited` cannot reach Ready. A plain
+ * `docker start` can restore the same container with its workspace state and
+ * managed configuration preserved (#8967). A nonzero or missing `docker start`
+ * status continues to the readiness wait, which surfaces the existing
+ * stopped-container guidance. The function leaves an unresolved, running, or
+ * paused container unchanged. A paused container keeps its `docker unpause`
+ * guidance. A caller that reaches this function after container startup makes
+ * no change.
+ */
+export function startStoppedSandboxContainerForProbeRecovery(sandboxName: string): void {
+  const runtime = getSandboxDockerRuntime(sandboxName);
+  if (!runtime.containerName || runtime.running || runtime.paused) return;
+  console.error(`  Sandbox '${sandboxName}' container is stopped — starting it...`);
+  const result = dockerStart(runtime.containerName, {
+    ignoreError: true,
+    timeout: RECOVER_CONTAINER_START_TIMEOUT_MS,
+  });
+  if (result.status === 0) {
+    console.error(`  ${G}✓${R} Started container '${runtime.containerName}'.`);
+  } else {
+    console.error(
+      `  Docker could not start container '${runtime.containerName}' (exit ${result.status ?? "unknown"}); continuing with readiness checks.`,
+    );
+  }
+}
+
 export async function ensureLiveSandboxOrExit(
   sandboxName: string,
   {

test/support/connect-flow-test-harness.ts

@@ -32,6 +32,8 @@ export type ConnectHarness = {
   ensureOllamaAuthProxySpy: MockInstance;
   findReachableOllamaHostSpy: MockInstance;
   ensureLiveSandboxSpy: MockInstance;
+  getSandboxDockerRuntimeSpy: MockInstance;
+  dockerStartSpy: MockInstance;
   errorSpy: MockInstance;
   logSpy: MockInstance;
   inspectLaunchReadinessSpy: MockInstance;
@@ -79,6 +81,13 @@ export type ConnectHarnessOptions = {
     mcpReconciliationReason?: string;
   };
   portableRecoveryResult?: { kind: "not-installed" | "already-running" | "recovered" };
+  dockerRuntime?: {
+    health?: string;
+    paused?: boolean;
+    running?: boolean;
+    containerName?: string | null;
+  };
+  dockerStartStatus?: number | null;
   spawnSignal?: NodeJS.Signals | null;
   spawnStatus?: number | null;
   sttyThrows?: boolean;
@@ -136,6 +145,8 @@ export function createConnectHarness(options: ConnectHarnessOptions = {}): Conne
   const gatewayFailureClassifier = requireDist(
     "../../src/lib/actions/sandbox/gateway-failure-classifier.js",
   );
+  const dockerHealth = requireDist("../../src/lib/actions/sandbox/docker-health.js");
+  const dockerAdapter = requireDist("../../src/lib/adapters/docker/container.js");
   const localInference = requireDist("../../src/lib/inference/local.js");
   const ollamaProxy = requireDist("../../src/lib/inference/ollama/proxy.js");
   const platform = requireDist("../../src/lib/platform.js");
@@ -183,6 +194,17 @@ export function createConnectHarness(options: ConnectHarnessOptions = {}): Conne
     output: "Name: alpha\nPhase: Ready\n",
   });
   vi.spyOn(gatewayFailureClassifier, "isDockerRuntimeDown").mockReturnValue(false);
+  const getSandboxDockerRuntimeSpy = vi
+    .spyOn(dockerHealth, "getSandboxDockerRuntime")
+    .mockReturnValue({
+      health: options.dockerRuntime?.health ?? "healthy",
+      paused: options.dockerRuntime?.paused ?? false,
+      running: options.dockerRuntime?.running ?? true,
+      containerName: options.dockerRuntime?.containerName ?? null,
+    });
+  const dockerStartSpy = vi.spyOn(dockerAdapter, "dockerStart").mockReturnValue({
+    status: options.dockerStartStatus === undefined ? 0 : options.dockerStartStatus,
+  });
   const inferenceProbeResponses = [...(options.inferenceProbeResponses ?? [])];
   const listOutputs = [...(options.listOutputs ?? [])];
   const captureOpenshellSpy = vi
@@ -323,6 +345,8 @@ export function createConnectHarness(options: ConnectHarnessOptions = {}): Conne
     ensureOllamaAuthProxySpy,
     findReachableOllamaHostSpy,
     ensureLiveSandboxSpy,
+    getSandboxDockerRuntimeSpy,
+    dockerStartSpy,
     errorSpy,
     logSpy,
     inspectLaunchReadinessSpy,