Greptile Summary

This PR adds graceful handling for Docker daemon unavailability across docker.ts, browser.ts, and doctor-sandbox.ts so that sandbox.mode="off" sessions no longer crash on startup when Docker isn't running.

• P1 – incomplete fix for custom images: In ensureDockerImage, when a user configures a non-default sandbox image, dockerImageExists silently returns false on daemon unavailability, then the function falls through to throw new Error(\Sandbox image not found: ${image}`). The daemon guard only covers the DEFAULT_SANDBOX_IMAGE` pull branch, leaving custom-image users with the same startup crash.
• P2 – duplicated detection logic: isDockerDaemonUnavailable is defined twice as a named function (with different names in docker.ts vs browser.ts) and inlined a third time in doctor-sandbox.ts; a shared utility would keep drift from creeping in.

Confidence Score: 3/5

Not safe to merge as-is — the fix is incomplete and custom-image users will still see the crash it aims to prevent.

One P1 defect: the non-default image path in ensureDockerImage still throws when the Docker daemon is down, meaning the bug is only partially fixed. Two P2 issues (duplicated helper, broad heuristic string) are non-blocking but worth addressing.

src/agents/sandbox/docker.ts — the ensureDockerImage fallthrough for non-default images needs a daemon-unavailability guard matching the one added for the default image.

This is a comment left during a code review.
Path: src/agents/sandbox/docker.ts
Line: 326-327

Comment:
**Custom images still throw when daemon is unavailable**

When `image` is a user-configured (non-default) image, `dockerImageExists` returns `false` due to daemon unavailability, but then the function falls through to `throw new Error(\`Sandbox image not found: ${image}. Build or pull it first.\`)`. The daemon check only covers the `DEFAULT_SANDBOX_IMAGE` pull path, so any session that configures a custom sandbox image still surfaces the original crash when Docker is down and `sandbox.mode="off"`.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/agents/sandbox/browser.ts
Line: 126-135

Comment:
**Duplicated helper with a different name**

`isDockerDaemonUnavailableBrowser` is byte-for-byte identical to `isDockerDaemonUnavailable` in `docker.ts`, and the same logic is inlined a third time in `doctor-sandbox.ts`. Duplicating this across three files means any future change to the detection heuristics (e.g. adding a new Docker-Desktop-specific message) must be applied in all three places. Consider extracting to a shared utility, e.g. `src/agents/sandbox/docker-utils.ts`.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/agents/sandbox/docker.ts
Line: 279

Comment:
**Overly-broad heuristic string**

`"no such file or directory"` is a generic POSIX error string. In the context of `image inspect` it almost always means a missing socket, but on some systems it can appear in unrelated Docker error output (e.g. a bind-mount whose host path doesn't exist). Pairing it with the already-present `"dial unix"` check covers the missing-socket case; the standalone string can silently swallow real Docker errors. The `"dial unix"` and `"cannot connect to the docker daemon"` checks are sufficient for the stated goal.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "fix(sandbox): gracefully handle Docker d..." | Re-trigger Greptile}

Codex review: needs maintainer review before merge.

What this changes:

The PR exports a shared Docker-daemon-unavailable classifier, applies it to sandbox, browser, and doctor Docker image-inspect paths, and adds a default-image inspection regression test.

Maintainer follow-up before merge:

This is an active open implementation PR assigned to a maintainer, touches secops-owned sandbox failure semantics, and has an alternate open fix candidate; the remaining action is maintainer selection, review, and validation rather than an automated replacement PR.

Best possible solution:

Keep the PR open for maintainer and secops review, choose the intended fix shape for #73586, and land only after mode-off sessions are proven not to initialize Docker while sandbox-enabled sessions still surface Docker availability failures clearly.

Acceptance criteria:

• pnpm test src/agents/sandbox/docker.test.ts src/agents/sandbox.resolveSandboxContext.test.ts src/commands/doctor-sandbox.warns-sandbox-enabled-without-docker.test.ts
• Add or run focused regression coverage for browser sandbox image setup and the cron/heartbeat/sub-agent mode-off reproduction before merge.
• Run pnpm check:changed in Testbox before handoff if the PR is updated for merge.

What I checked:

• current_main_docker_probe_still_throws: On current main, dockerImageExists only treats 'No such image' as a nonfatal miss; other image-inspect stderr still throws 'Failed to inspect sandbox image', matching the daemon-unavailable failure class. (src/agents/sandbox/docker.ts:275, 0544c6d493ff)
• current_main_browser_probe_still_unguarded: ensureSandboxBrowserImage still throws the browser-image missing error for every nonzero docker image inspect result, with no daemon-unavailable classifier on main. (src/agents/sandbox/browser.ts:126, 0544c6d493ff)
• sandbox_off_contract_exists: The runtime-status path returns false for sandbox mode off, and resolveSandboxContext returns null before backend setup when the resolved runtime is not sandboxed; the expected end state is that mode-off sessions do not initialize Docker at all. (src/agents/sandbox/runtime-status.ts:16, 0544c6d493ff)
• cron_path_still_uses_run_key: The isolated cron executor still passes the run-scoped sessionKey into runEmbeddedPiAgent, while the embedded runner resolves sandbox policy from sandboxSessionKey or sessionKey, so current main still lacks the root-cause handoff covered by the related bug discussion. (src/cron/isolated-agent/run-executor.ts:174, 0544c6d493ff)
• live_pr_and_linked_bug_state: Unauthenticated GitHub API confirms this PR is open and unmerged at head 378851c, assigned to sallyom, and linked bug [Bug]: sandbox.mode: "off" still triggers Docker capability probe for cron/heartbeat/sub-agent sessions — causes failures when Docker daemon is unavailable #73586 is still open. (378851cf4053)
• latest_pr_diff_scope: The latest PR diff is limited to sandbox barrel export, sandbox Docker/browser image probes, doctor sandbox image checks, and one Docker image-inspect test; it does not touch cron/heartbeat/sub-agent handoff code. (378851cf4053)

Likely related people:

• sallyom: Live PR metadata shows sallyom is assigned, and the latest PR head was force-pushed by sallyom in the provided timeline, making them the current review and follow-up contact for this implementation candidate. (role: recent PR follow-up owner; confidence: medium; commits: 378851cf4053, d64463937045, 050b2f9a9fae; files: src/agents/sandbox/docker.ts, src/agents/sandbox/browser.ts, src/commands/doctor-sandbox.ts)
• Masato Hoshino: Current checkout blame attributes the visible Docker image-probe, browser image-probe, and doctor image-probe lines to commit 016f5ae; this is routing context, not fault attribution. (role: recent current-main maintainer; confidence: medium; commits: 016f5ae862e1; files: src/agents/sandbox/docker.ts, src/agents/sandbox/browser.ts, src/commands/doctor-sandbox.ts)
• steipete: The v2026.4.26 release commit contains the central sandbox Docker, browser, context, and doctor files that match the version named by the linked bug, so steipete is relevant for shipped-behavior provenance. (role: release snapshot maintainer; confidence: medium; commits: be8c24633aaa; files: src/agents/sandbox/docker.ts, src/agents/sandbox/browser.ts, src/agents/sandbox/context.ts)

Remaining risk / open question:

• The PR treats Docker-daemon-unavailable image inspection as success in ensureDockerImage, so maintainers should verify required sandbox runs still fail clearly when Docker is actually needed.
• Regression coverage is narrow: the PR adds one default-image inspection test but does not cover the cron, heartbeat, sub-agent mode-off path, browser image setup, doctor behavior, or custom images.
• There are two open fix shapes for the same linked bug, fix(sandbox): explicitly pass sandboxSessionKey to prevent Docker probes when mode is off (#73586) #73627 and this PR; maintainers should choose deliberately between the root-cause sandbox policy-key handoff and the broader Docker probe fallback.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 0544c6d493ff.

Merged in 2dadc82.

Prepared head: 378851c