PR #62804: fix(tools): expand tilde in host edit/write paths (non-workspace mode)

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

Description (problem / solution / changelog)

Summary

• Problem: The edit and write tools fail when given tilde paths (e.g. ~/.openclaw/workspace/memory/2026-04-07.md) in non-workspace mode. path.resolve("~/foo") treats ~ as a literal directory name, resolving to <cwd>/~/foo instead of expanding to the user's home directory.
• Why it matters: Users on Telegram (and other channels) see ⚠️ 📝 Edit: in ~/.openclaw/workspace/memory/... failed errors when the agent tries to edit files via tilde paths. Reported as a regression in #62517.
• What changed: Added expandHomePrefix() (already used in 13 other files) before path.resolve() in the 5 non-workspace host edit/write call sites in pi-tools.read.ts.
• What did NOT change (scope boundary): The workspace-only (workspaceOnly: true) code path already expands tilde correctly via readFileWithinRoot/writeFileWithinRoot in fs-safe.ts. That path is untouched. Sandbox edit operations are also 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 #62517
• Related #30669
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: createHostEditOperations and createHostWriteOperations in src/agents/pi-tools.read.ts use bare path.resolve(absolutePath) in the non-workspace branch. Node's path.resolve treats ~ as a literal directory character, not a home directory alias. The workspace-only branch already calls expandHomePrefix() via fs-safe.ts, but the non-workspace branch was missed.
• Missing detection / guardrail: No test covered tilde-prefixed paths through the non-workspace host edit/write operations.
• Contributing context: The workspace-only path was fixed in commit 645d963954 which added expandRelativePathWithHome() to fs-safe.ts, but the parallel non-workspace path in pi-tools.read.ts was not updated at the same time.

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-tools.read.host-tilde-expansion.test.ts
• Scenario the test should lock in: Tilde-prefixed paths passed to non-workspace host edit (readFile, access) and write (writeFile, mkdir) operations resolve to the correct absolute path under $HOME.
• Why this is the smallest reliable guardrail: Unit tests on the captured operations objects directly verify tilde expansion without needing a full agent/gateway setup.
• Existing test that already covers this: pi-tools.read.host-edit-access.test.ts covers access mapping but not tilde expansion.

User-visible / Behavior Changes

• Edit and write tools now correctly handle tilde paths (~/...) in non-workspace mode, matching the existing behavior of workspace-only mode.
• Users will no longer see ⚠️ 📝 Edit: in ~/.openclaw/... failed errors when the agent uses tilde paths.

Diagram (if applicable)

Before:
[agent edit ~/foo.md] -> path.resolve("~/foo.md") -> "<cwd>/~/foo.md" -> ENOENT

After:
[agent edit ~/foo.md] -> expandHomePrefix("~/foo.md") -> "/home/user/foo.md" -> path.resolve -> success

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No — same file paths are accessed, just resolved correctly.
• Data access scope changed? No — tilde paths already resolve to the user's home directory in workspace-only mode; this makes non-workspace mode consistent.

Repro + Verification

Environment

• OS: Linux (reported), macOS (tested)
• Runtime/container: Node 22+
• Model/provider: Any (model-independent)
• Integration/channel: Telegram (reported), any channel
• Relevant config: workspaceOnly: false (non-workspace mode)

Steps

1. Run OpenClaw with an agent in non-workspace mode
2. Agent attempts to edit a file using a tilde path (e.g. ~/.openclaw/workspace/memory/2026-04-07.md)
3. Observe the edit fails with ENOENT

Expected

• File is edited successfully at the expanded path under $HOME

Actual

• path.resolve treats ~ as literal, file not found, error broadcasted

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers

4 new regression tests pass:

• edit readFile expands ~ to home directory
• edit access expands ~ to home directory
• write writeFile expands ~ to home directory
• write mkdir expands ~ to home directory

Human Verification (required)

• Verified scenarios: All 4 new tests pass. Existing pi-tools.read.host-edit-access.test.ts still passes. pnpm build and pnpm lint pass cleanly.
• Edge cases checked: Non-tilde paths remain unaffected (expandHomePrefix returns them unchanged). Paths not under $HOME are handled (test skips gracefully on systems where tmpdir is not under home).
• What I did not verify: End-to-end Telegram message flow (no Telegram setup available). Windows tilde behavior (tested on macOS only, but expandHomePrefix handles both / and \ separators).

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: A caller intentionally passing a literal ~ directory name (not meaning home) would now have it expanded.
  • Mitigation: This matches the behavior of every other path-handling code path in the codebase (13 files use expandHomePrefix). No code intentionally uses literal ~ as a directory name.

AI-assisted: This PR was developed with AI assistance. All code was reviewed, understood, and tested by the author.

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/agents/pi-tools.host-edit.ts (modified, +3/-6)
• src/agents/pi-tools.read.host-edit-recovery.test.ts (modified, +57/-0)
• src/agents/pi-tools.read.host-tilde-expansion.test.ts (added, +171/-0)
• src/agents/pi-tools.read.ts (modified, +10/-4)