fix: report effective sandbox workspace in explain by ZengWen-DT · Pull Request #100439 · openclaw/openclaw

ZengWen-DT · 2026-07-05T19:14:51Z

What Problem This Solves

Fixes an issue where users running openclaw sandbox explain --agent <id> with workspaceAccess: "rw" would see workspaceRoot reported as the configured sandbox root even though sandbox commands write through the agent workspace mounted at /workspace.

Why This Change Was Made

The sandbox workspace path selection is now shared between runtime setup and sandbox explain, and the explain output includes the effective host workspace, configured sandbox root, container workdir, workspace source, and Docker mount table. This is a diagnostics-only change; it does not change sandbox creation or mount behavior.

User Impact

Users can now rely on sandbox explain to find where files actually land for rw workspaces instead of looking under the configured sandbox root by mistake.

Evidence

Before: on upstream/main, src/commands/sandbox-explain.ts set sandbox.workspaceRoot directly from sandboxCfg.workspaceRoot, while src/agents/sandbox/context.ts selected the agent workspace as workspaceDir when workspaceAccess === "rw".

After, with an isolated config using workspaceAccess: "rw", workspaceRoot: "/tmp/openclaw-sandboxes", and agent workspace "/tmp/openclaw-agent-workspace":

{
  "workspaceAccess": "rw",
  "workspaceRoot": "/tmp/openclaw-agent-workspace",
  "configuredWorkspaceRoot": "/tmp/openclaw-sandboxes",
  "sandboxWorkspaceRoot": "/tmp/openclaw-sandboxes/agent-builder-c4974941",
  "agentWorkspaceRoot": "/tmp/openclaw-agent-workspace",
  "containerWorkdir": "/workspace",
  "workspaceMounts": [
    {
      "hostRoot": "/tmp/openclaw-agent-workspace",
      "containerRoot": "/workspace",
      "writable": true,
      "source": "workspace"
    }
  ],
  "workspaceSource": "agent"
}

Commands run:

node scripts/run-vitest.mjs src/commands/sandbox-explain.test.ts src/agents/sandbox/workspace-mounts.test.ts
node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core.tsbuildinfo
node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test.tsbuildinfo
node scripts/run-oxlint.mjs src/agents/sandbox/shared.ts src/agents/sandbox/context.ts src/commands/sandbox-explain.ts src/commands/sandbox-explain.test.ts
pnpm build

Real agent proof also ran locally with deepseek/deepseek-v4-pro through openclaw agent --local; the run returned sandbox explain proof ok with provider deepseek, model deepseek-v4-pro, and stopReason=stop.

AI-assisted.

clawsweeper · 2026-07-05T19:25:46Z

Codex review: needs maintainer review before merge. Reviewed July 5, 2026, 3:29 PM ET / 19:29 UTC.

Summary
The branch factors sandbox workspace layout resolution into a shared helper and expands openclaw sandbox explain output/tests to report the effective workspace and Docker mount table.

PR surface: Source +76, Tests +47. Total +123 across 4 files.

Reproducibility: yes. source-level. Current main reports the configured sandbox root while runtime layout and Docker mount helpers use the agent workspace for workspaceAccess: rw; I did not run a live Docker repro in this read-only pass.

Review metrics: 1 noteworthy metric.

Diagnostic output shape: 6 fields added, 1 field semantics changed. The JSON/text output now distinguishes configured and effective sandbox paths, so reviewers should notice the public diagnostic shape change before merge.

Stored data model
Persistent data-model change detected: serialized state: src/commands/sandbox-explain.test.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #100423
Summary: This PR is a candidate fix for the open canonical sandbox explain effective-workspace mismatch; a narrower alternate PR exists but is not the safer canonical landing path.

Members:

canonical: sandbox explain reports same workspaceRoot regardless of effective workspaceAccess mode (misleading in rw mode) #100423 - The PR body closes the open issue that reports the exact misleading workspaceRoot behavior.
partial_overlap: fix(cli): show effective workspace root in sandbox explain when rw #100435 - This open alternate PR targets the same issue but only adds a narrower effective-root field and already has review concerns for non-rw modes.
partial_overlap: workspaceAccess: "rw" updates Docker bind mount but leaves gateway read proxy workspaceRoot pointing at stale sandboxes/ snapshot #63971 - The closed older issue included the same workspaceRoot symptom, but its primary stale-read runtime bug was already resolved separately.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

none.

Next step before merge

No ClawSweeper repair lane is needed; the remaining action is ordinary maintainer review and merge gating.

Security
Cleared: The diff reports existing sandbox layout and mount facts and does not change sandbox creation, permissions, secrets, dependencies, CI, or package resolution.

Review details

Best possible solution:

Land a diagnostic-only fix that reuses the runtime workspace layout and reports configured root plus effective mounts without changing sandbox creation semantics.

Do we have a high-confidence way to reproduce the issue?

Yes, source-level. Current main reports the configured sandbox root while runtime layout and Docker mount helpers use the agent workspace for workspaceAccess: rw; I did not run a live Docker repro in this read-only pass.

Is this the best way to solve the issue?

Yes. This is the better fix shape because it shares the runtime layout helper and mount model with explain instead of adding a separate rw-only calculation.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against f141408e7749.

Label changes

Label changes:

add P2: This is a focused CLI diagnostics fix for misleading sandbox filesystem information with limited blast radius but real user confusion around sandbox boundaries.
add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes copied after-fix JSON output for an isolated rw config plus a real agent run result, which is acceptable live-output proof for this CLI diagnostics change.
add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes copied after-fix JSON output for an isolated rw config plus a real agent run result, which is acceptable live-output proof for this CLI diagnostics change.

Label justifications:

P2: This is a focused CLI diagnostics fix for misleading sandbox filesystem information with limited blast radius but real user confusion around sandbox boundaries.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes copied after-fix JSON output for an isolated rw config plus a real agent run result, which is acceptable live-output proof for this CLI diagnostics change.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes copied after-fix JSON output for an isolated rw config plus a real agent run result, which is acceptable live-output proof for this CLI diagnostics change.

Evidence reviewed

PR surface:

Source +76, Tests +47. Total +123 across 4 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	3	101	25	+76
Tests	1	47	0	+47
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	4	148	25	+123

What I checked:

Repository policy read: Root AGENTS.md and the scoped src/agents/AGENTS.md were read; the review applied the repo guidance to inspect the whole sandbox/explain path and treat sandbox diagnostics as security-boundary-sensitive. (AGENTS.md:1, f141408e7749)
Current-main mismatch: On current main, the explain payload still reports sandbox.workspaceRoot directly from sandboxCfg.workspaceRoot, which is the configured root rather than the effective rw workspace. (src/commands/sandbox-explain.ts:263, f141408e7749)
Runtime effective workspace: The runtime layout chooses agentWorkspaceDir when workspaceAccess === "rw" and only uses the scoped sandbox workspace for non-rw modes, matching the linked issue's reported mismatch. (src/agents/sandbox/context.ts:87, f141408e7749)
Mount contract: Docker workspace mounts bind the resolved workspaceDir at the container workdir and mark it writable only for rw, so explain should report that effective mount rather than only the configured parent root. (src/agents/sandbox/workspace-mounts.ts:147, f141408e7749)
PR implementation shape: The PR moves the workspace layout calculation into resolveSandboxWorkspaceLayoutPaths, uses it from both runtime setup and explain, and adds command coverage for rw agent workspace output. (src/agents/sandbox/shared.ts:57, fe162cfa207f)
Related canonical issue: The PR uses closing syntax for the open issue that reports the exact sandbox explain workspaceRoot mismatch; the older alternate PR for the same issue is still open but narrower and previously reviewed as inaccurate for non-rw modes.

Likely related people:

steipete: Introduced sandbox explain, later refactored sandbox workspace layout setup, and current blame for the central explain/context lines traces through Peter-authored commits. (role: feature introducer and recent area contributor; confidence: high; commits: 9f9098406ccc, 182afe9f594d; files: src/commands/sandbox-explain.ts, src/agents/sandbox/context.ts)
vignesh07: Added the bind-aware filesystem mount resolver that models workspace, agent, bind, and protected-skill mounts used by this diagnostic surface. (role: adjacent owner; confidence: medium; commits: eafda6f52671; files: src/agents/sandbox/fs-paths.ts, src/agents/sandbox/workspace-mounts.ts)
flashosophy: A recent merged PR carried these files through the current tree shape, though the sandbox explain behavior predates that unrelated TUI change. (role: recent file mover; confidence: low; commits: 3f1dea78753b; files: src/commands/sandbox-explain.ts, src/agents/sandbox/context.ts, src/agents/sandbox/fs-paths.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Sources: #100435, #100439 Co-authored-by: Aniruddha Adak <[email protected]> Co-authored-by: ZengWen-DT <[email protected]>

* fix(agents): harden LSP process failures Source: #100450 Co-authored-by: morluto <[email protected]> * fix(sandbox): report effective workspace layout Sources: #100435, #100439 Co-authored-by: Aniruddha Adak <[email protected]> Co-authored-by: ZengWen-DT <[email protected]> * fix(security): fail install checks on stream errors Source: #100413 Co-authored-by: 陈宪彪0668000387 <[email protected]> * fix(android): normalize all-day calendar events Source: #100032 Co-authored-by: NianJiuZst <[email protected]> * fix(ios): serialize push-to-talk lifecycle Source: #99942 Co-authored-by: NianJiuZst <[email protected]> * fix(talk): reject inherited provider names Source: #99849 Co-authored-by: zenglingbiao <[email protected]> * fix(android): stop voice capture in background Source: #99840 Co-authored-by: xialonglee <[email protected]> * fix(cron): preserve fallback result classification Source: #99913 Co-authored-by: jincheng-xydt <[email protected]> * fix(google): bound Vertex response decompression Source: #99812 Co-authored-by: 黄剑雄0668001315 <[email protected]> * fix(plugins): report malformed discovery JSON Source: #99892 Co-authored-by: 陈宪彪0668000387 <[email protected]> * test(sandbox): configure non-default workspace fixture * test: fix small-fix batch validation --------- Co-authored-by: morluto <[email protected]> Co-authored-by: ZengWen-DT <[email protected]> Co-authored-by: 陈宪彪0668000387 <[email protected]> Co-authored-by: NianJiuZst <[email protected]> Co-authored-by: zenglingbiao <[email protected]> Co-authored-by: xialonglee <[email protected]> Co-authored-by: jincheng-xydt <[email protected]> Co-authored-by: 黄剑雄0668001315 <[email protected]>

steipete · 2026-07-05T23:10:16Z

Superseded by #100483, landed as aaf5ab9.

The landed rewrite preserves workspaceRoot, centralizes runtime/diagnostic layout ownership, reports the effective host workspace, backend workdir, and active Docker mounts, and adds coverage for direct/global sessions, agent mismatch, derived workspaces, and persisted spawned-session overrides. Exact-head proof passed 195 focused tests, changed-surface type/lint/guards, and hosted CI. Contributor credit from this PR is preserved in the landed commit.

Thank you @ZengWen-DT for identifying and implementing the core mismatch.

steipete · 2026-07-05T23:10:27Z

Thanks @ZengWen-DT — your effective-workspace implementation was incorporated into the canonical fix in #100483, landed as aaf5ab9. The landed version also preserves the existing workspaceRoot JSON contract, reports runtime workdir/mounts, and handles direct/global/spawned sessions. Contributor credit is preserved. Closing this superseded PR.

* fix(agents): harden LSP process failures Source: openclaw#100450 Co-authored-by: morluto <[email protected]> * fix(sandbox): report effective workspace layout Sources: openclaw#100435, openclaw#100439 Co-authored-by: Aniruddha Adak <[email protected]> Co-authored-by: ZengWen-DT <[email protected]> * fix(security): fail install checks on stream errors Source: openclaw#100413 Co-authored-by: 陈宪彪0668000387 <[email protected]> * fix(android): normalize all-day calendar events Source: openclaw#100032 Co-authored-by: NianJiuZst <[email protected]> * fix(ios): serialize push-to-talk lifecycle Source: openclaw#99942 Co-authored-by: NianJiuZst <[email protected]> * fix(talk): reject inherited provider names Source: openclaw#99849 Co-authored-by: zenglingbiao <[email protected]> * fix(android): stop voice capture in background Source: openclaw#99840 Co-authored-by: xialonglee <[email protected]> * fix(cron): preserve fallback result classification Source: openclaw#99913 Co-authored-by: jincheng-xydt <[email protected]> * fix(google): bound Vertex response decompression Source: openclaw#99812 Co-authored-by: 黄剑雄0668001315 <[email protected]> * fix(plugins): report malformed discovery JSON Source: openclaw#99892 Co-authored-by: 陈宪彪0668000387 <[email protected]> * test(sandbox): configure non-default workspace fixture * test: fix small-fix batch validation --------- Co-authored-by: morluto <[email protected]> Co-authored-by: ZengWen-DT <[email protected]> Co-authored-by: 陈宪彪0668000387 <[email protected]> Co-authored-by: NianJiuZst <[email protected]> Co-authored-by: zenglingbiao <[email protected]> Co-authored-by: xialonglee <[email protected]> Co-authored-by: jincheng-xydt <[email protected]> Co-authored-by: 黄剑雄0668001315 <[email protected]>

fix: report effective sandbox explain workspace

fe162cf

ZengWen-DT requested a review from a team as a code owner July 5, 2026 19:14

openclaw-barnacle Bot added commands Command implementations docker Docker and sandbox tooling agents Agent runtime and tooling size: S labels Jul 5, 2026

steipete self-assigned this Jul 5, 2026

steipete mentioned this pull request Jul 5, 2026

fix: land ten small reliability fixes #100483

Merged

steipete added a commit that referenced this pull request Jul 5, 2026

fix(sandbox): report effective workspace layout

c58c3eb

Sources: #100435, #100439 Co-authored-by: Aniruddha Adak <[email protected]> Co-authored-by: ZengWen-DT <[email protected]>

steipete closed this Jul 5, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix: report effective sandbox workspace in explain#100439

fix: report effective sandbox workspace in explain#100439
ZengWen-DT wants to merge 1 commit into
openclaw:mainfrom
ZengWen-DT:fix/100423-sandbox-explain-workspace-root

ZengWen-DT commented Jul 5, 2026

Uh oh!

clawsweeper Bot commented Jul 5, 2026 •

edited

Loading

Uh oh!

steipete commented Jul 5, 2026

Uh oh!

steipete commented Jul 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

ZengWen-DT commented Jul 5, 2026

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

steipete commented Jul 5, 2026

Uh oh!

steipete commented Jul 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

clawsweeper Bot commented Jul 5, 2026 •

edited

Loading