`documents` symlinks rejected by gateway's workspace security boundary

[fredcy]

documents symlinks rejected by gateway's workspace security boundary

Summary

Workspace files created by the documents option (AGENTS.md, SOUL.md, TOOLS.md, etc.) are symlinks into /nix/store/. The OpenClaw gateway's workspace file loader has a security boundary check that rejects symlinks resolving outside ~/.openclaw/workspace/. This means all nix-managed documents silently fail to load into project context.

Reproduction

1. Configure programs.openclaw.documents = ./documents; with valid AGENTS.md, SOUL.md, TOOLS.md
2. Run home-manager switch
3. Confirm files are symlinks: ls -la ~/.openclaw/workspace/AGENTS.md → points to /nix/store/...
4. Start a session and ask the agent to check its project context — the files show as [MISSING]

Root Cause

The gateway resolves workspace file paths segment-by-segment. When it encounters a symlink, it calls isPathInside(rootCanonicalPath, linkCanonical) to verify the resolved target is within the workspace root. Nix store symlinks resolve to /nix/store/..., which is outside ~/.openclaw/workspace/, so the gateway treats them as a symlink escape and silently drops the file.

Relevant gateway code (minified, agent-scope module):

function applyResolvedSymlinkHop(params) {
    if (!isPathInside(params.rootCanonicalPath, params.linkCanonical))
        throw symlinkEscapeError({
            boundaryLabel: params.boundaryLabel,
            rootCanonicalPath: params.rootCanonicalPath,
            symlinkPath: params.state.lexicalCursor
        });
}

Impact

• All five document files (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md) fail to load
• No error in gateway logs, no user-facing warning — completely silent
• The agent loses its personality (SOUL.md), identity (IDENTITY.md), tool guidance (TOOLS.md), and user context (USER.md)
• We ran like this for weeks without noticing because MEMORY.md (a regular file, not nix-managed) compensated

Workaround

We removed documents from our config entirely and manage the workspace files as plain files. The ./documents/ directory remains in the nix-config repo for version control.

Suggested Fix

The nix-openclaw module could use home.file.<name>.text = builtins.readFile ... instead of home.file.<name>.source = ... for document files. This would cause home-manager to write the file contents directly rather than creating symlinks into the nix store.

Alternatively, a home.activation script could copy the files over the symlinks after home-manager creates them, though that's less clean.

Environment

• OpenClaw gateway: 2026.3.2
• nix-openclaw: current main branch (as of 2026-03-07)
• OS: Debian 12, home-manager standalone