PR #60278: fix(agents): bypass loadWebMedia for media-uri refs to prevent WSL2 keyring deadlock (#59104)

• Repository: openclaw/openclaw
• Author: Syysean
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/60278

Description (problem / solution / changelog)

Summary

• Problem: loadImageFromRef passed a local filesystem path (returned by resolveMediaBufferPath) to loadWebMedia for media-uri refs.
• Why it matters: On WSL2 / Ubuntu 24.04, loadWebMedia launches Chromium, which attempts to access GNOME Keyring via libsecret. This causes a synchronous block, making the Gateway hang silently with no logs, no errors, and no response to SIGTERM.
• What changed: Bypassed the Chromium browser stack completely for media-uri refs. Replaced loadWebMedia(physicalPath) with a direct fs.readFile(physicalPath) call.
• What did NOT change (scope boundary): The handling of standard remote web URLs and inline image references remains untouched.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #59104
• Related #
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: Attempting to use a headless browser stack (Chromium) to load an already-validated and persisted local media file.
• Missing detection / guardrail: Missing differentiation in the loading strategy between remote URLs (which need browser rendering/fetching) and local Gateway-managed files.
• Prior context (git blame, prior PR, issue, or refactor if known): Unknown
• Why this regressed now: Unknown
• If unknown, what was ruled out: N/A

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/pi-embedded-runner/run/images.test.ts (or equivalent)
• Scenario the test should lock in: Assert that providing a media-uri ref calls fs.readFile and strictly does NOT invoke loadWebMedia.
• Why this is the smallest reliable guardrail: It prevents the heavy browser stack from being invoked for local files, which is the direct trigger for the OS-level keyring deadlock.
• Existing test that already covers this (if any): None
• If no new test is added, why not: N/A

User-visible / Behavior Changes

None. The Gateway will now successfully process images on WSL2 instead of silently crashing.

Diagram (if applicable)

Before:
[media-uri ref] -> [loadWebMedia(Chromium)] -> [libsecret / GNOME Keyring] -> [Deadlock / Gateway Hangs]

After:
[media-uri ref] -> [fs.readFile] -> [Base64 Image Data Returned]

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: WSL2 / Ubuntu 24.04
• Runtime/container: Node.js (Local)
• Model/provider: Any vision-capable model
• Integration/channel (if any): WebUI / Chat
• Relevant config (redacted): N/A

Steps

1. Run Gateway on WSL2 (Ubuntu 24.04).
2. Send a large image attachment (e.g., >2MB) in the chat to trigger the claim-check offload path (media-uri).
3. Observe Gateway behavior.

Expected

• The image is loaded, processed, and the model responds normally.

Actual

• Before this PR: Gateway hangs silently, consumes CPU/RAM without returning, ignores SIGTERM.
• After this PR: Gateway processes the image instantly via local filesystem read.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: Reproduced the deadlock on WSL2 with large images. Applied the fix and verified the image loads successfully via fs.readFile without launching Chromium.
• Edge cases checked: Verified small images (inline paths) are unaffected. Verified MIME type is correctly inferred from the persisted file extension.
• What you did not verify: Did not test on macOS/native Windows, as the keyring deadlock is specific to Linux/WSL2 desktop environments.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: MIME type inference now relies on the local file extension rather than browser headers.
  • Mitigation: The Gateway's saveMediaBuffer already strictly validates and assigns the correct extension during the initial offload/persist phase, making the file extension a reliable source of truth.

Changed files

• src/agents/pi-embedded-runner/run/images.test.ts (modified, +26/-0)
• src/agents/pi-embedded-runner/run/images.ts (modified, +55/-15)

PR #62873: fix(sandbox): prevent false-positive CDP readiness and add fail-fast

• Repository: openclaw/openclaw
• Author: Syysean
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/62873

Description (problem / solution / changelog)

Summary

Problem: In headless Docker/WSL2 environments, the sandbox Chromium silently hangs indefinitely while waiting for a non-existent system keyring (libsecret). The socat proxy was masking this failure by immediately keeping the TCP port open, causing the Node.js host to receive a "false-positive" readiness signal and wait endlessly.

Why it matters: This causes a permanent, silent deadlock in the image processing pipeline, wasting resources and defeating the system's self-healing (docker rm -f) capabilities.

What changed (Hotfix):

1. Keyring Bypass: Bypassed the keyring deadlock via --password-store=basic, --use-mock-keychain, and DBUS_SESSION_BUS_ADDRESS=/dev/null.
2. Fail-Fast Watchdog: Added a strict curl health check loop. If CDP does not return a valid response within 30 seconds, the entrypoint triggers kill -9 and exit 1.
3. Socat Deferral (Core Fix): Moved the socat startup to after the CDP health check passes. This eliminates the false-positive readiness signal.
4. Lifecycle Binding: Replaced wait -n with wait "$CHROME_PID" to strictly bind the container's lifecycle to the Chromium main process instead of arbitrary background jobs.

What did NOT change: The socat proxy and CDP port offset logic remain in place for now to ensure architectural compatibility. (The complete removal of socat and transition to direct CDP routing will be addressed in a follow-up architectural PR). The downstream image optimization logic and media-uri handling remain untouched.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related #59104
• Related #60278
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: Chromium in a headless Debian/Docker environment blocks indefinitely on the D-Bus/Keyring daemon. The socat proxy returned a false-positive connection state to the host.
• Missing detection / guardrail: The sandbox-browser-entrypoint.sh curl loop failed silently instead of exiting. The Node.js waitForSandboxCdp lacked a mechanism to garbage-collect hung containers on timeout.
• Contributing context: WSL2 + Docker Desktop lacks native desktop GUI daemons (like gnome-keyring), easily triggering Chromium's blocking behavior.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/sandbox/browser.ts
• Scenario the test should lock in: Ensure docker rm -f is correctly executed when waitForSandboxCdp breaches its timeout threshold.
• Why this is the smallest reliable guardrail: Validates the host-boundary auto-recovery mechanism without requiring a full failing browser setup.
• Existing test that already covers this (if any): N/A
• If no new test is added, why not: This PR focuses on architectural hardening. E2E container tests are needed to simulate keyring deadlocks natively.

User-visible / Behavior Changes

None. System reliability and operator observability are significantly improved.

Diagram (if applicable)

Before (Silent Deadlock & False Positive): ❌ [Chromium hangs] ➔ [socat starts & holds port] ➔ [Node.js waits infinitely]

After (Fail-Fast & Auto-Recovery): ✅ [Chromium starts] ➔ [Health check loop 30s]     ┣━ (Fail) ➔ [exit 1] ➔ [Container dies] ➔ [docker rm -f]     ┗━ (Pass) ➔ [Start socat] ➔ [Node.js connects safely]

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? Yes
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation:
• Mitigation: Safe because container isolation remains intact; host access is strictly managed via Docker's port mapping (-p 127.0.0.1::CDP_PORT).

Repro + Verification

Environment

• OS: Windows (WSL2)
• Runtime/container: Docker Desktop / Debian slim
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): Standard local sandbox configuration.

Steps

1. Send an image payload to trigger the browser sandbox offload pipeline in a WSL2 Docker environment.
2. Observe the Chromium container startup phase.

Expected

• Chromium successfully exposes the CDP port and processes the image, or the container immediately dies if CDP fails, triggering a clean host-side timeout and container recreation.

Actual

• (Before this PR) The container silently hung, locking up the Node.js thread waiting for the sandbox indefinitely.

Evidence

• Trace/log snippets

Human Verification (required)

• Verified scenarios: 1. Manually crashing the CDP endpoint to verify the entrypoint script executes exit 1. 2. Forcing a timeout in waitForSandboxCdp to verify docker rm -f cleans up the dead container.
• Edge cases checked: Ensured noVnc and --no-sandbox configurations are still parsed and applied correctly without the socat layer.
• What you did not verify: Full regression on macOS/Linux native environments (relies on CI).

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: Hardcoding 0.0.0.0 in Chromium args could theoretically expose CDP if the Docker container is run with --network host.
  • Mitigation: The Sandbox runner inherently isolates networks and binds mapped ports exclusively to 127.0.0.1 on the host side.

Changed files

• scripts/sandbox-browser-entrypoint.sh (modified, +126/-46)
• src/agents/sandbox/browser.create.test.ts (modified, +36/-0)
• src/agents/sandbox/browser.ts (modified, +7/-7)
• src/agents/sandbox/config-hash.test.ts (modified, +4/-0)
• src/agents/sandbox/config-hash.ts (modified, +7/-1)