PR #67916: fix(ui): don't block local attachments before bootstrap roots load

• Repository: openclaw/openclaw
• Author: Conan-Scott
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/67916

Description (problem / solution / changelog)

Summary

• Problem: Local assistant media attachments (TTS audio, images, documents via MEDIA: lines) render as "Unavailable — Outside allowed folders" in Control UI even when the server config and meta endpoint confirm the path is valid.
• Why it matters: Users cannot play, preview, or download assistant-generated local media in the webchat UI — the primary interactive surface.
• What changed: Skip the client-side allowed-folder gate when localMediaPreviewRoots is empty (not yet loaded from bootstrap), falling through to the authoritative server-side meta check. Also harden bootstrap config caching on both client and server.
• What did NOT change (scope boundary): The isLocalAttachmentPreviewAllowed logic itself is untouched — it still blocks paths outside configured roots once roots are populated. The sendJson helper's default Cache-Control for other endpoints (no-cache) is unchanged.

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 #67915
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: resolveAssistantAttachmentAvailability() in ui/src/ui/chat/grouped-render.ts calls isLocalAttachmentPreviewAllowed(source, localMediaPreviewRoots) as a hard gate before the server-side meta check. When localMediaPreviewRoots is [] (bootstrap config fetch not yet complete), every local path fails this check and returns { status: "unavailable", reason: "Outside allowed folders" } without ever reaching the server.
• Missing detection / guardrail: No test covers the case where roots are empty (bootstrap still loading) and a valid local attachment is checked. The existing "blocked" test correctly provides non-empty roots with a path outside them.
• Contributing context (if known): The bootstrap config fetch is async and completes after first render. The allowed-folder check was designed as a client-side optimisation to avoid unnecessary server round-trips, but didn't account for the empty-roots bootstrap window.

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: ui/src/ui/views/chat.test.ts
• Scenario the test should lock in: A local MEDIA: attachment checked against an empty localMediaPreviewRoots array should fall through to the server meta check (status "checking"), not hard-deny as "Outside allowed folders".
• Why this is the smallest reliable guardrail: The render-level test already exercises resolveAssistantAttachmentAvailability through the full render path and can assert the absence of "Outside allowed folders" when roots are empty.
• Existing test that already covers this (if any): The existing "blocks local attachments outside preview roots" test covers the populated-roots case. No existing test covers the empty-roots case.
• If no new test is added, why not: Vitest execution is blocked in the current CI-adjacent pod environment by Error: No such built-in module: node: (Node v24 + Vitest environment incompatibility). The test scenario is documented above for addition once the environment issue is resolved or in CI.

User-visible / Behavior Changes

• Local assistant attachments that previously appeared as "Unavailable — Outside allowed folders" on page load will now show as "Checking..." briefly, then render correctly once the server-side meta check completes.
• No config or API changes. No new environment variables.

Diagram (if applicable)

Before:
[page load] -> [attachments render] -> [roots=[]] -> isLocalAttachmentPreviewAllowed() -> false -> "Outside allowed folders" (STUCK)

After:
[page load] -> [attachments render] -> [roots=[]] -> skip client gate -> server meta check -> "available" ✓
                                        [bootstrap loads roots] -> future checks use client gate normally

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No new calls. When roots are empty, attachments that previously hard-denied now fall through to the existing assistant-media?meta=1 server endpoint, which performs the authoritative access check server-side. This is the same endpoint used for all other attachment availability checks.
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Debian 12 (bookworm) / Linux 6.12.0 (OpenShift pod)
• Runtime/container: Node v24.14.0, OpenClaw 2026.4.12–2026.4.16
• Model/provider: Any (bug is in UI rendering path)
• Integration/channel (if any): Control UI webchat
• Relevant config (redacted): Default config with TTS enabled producing local media under ~/.openclaw/media/outbound/

Steps

1. Run OpenClaw with Control UI and TTS enabled.
2. Trigger an assistant response that includes a MEDIA:/path/to/local/file.mp3 line.
3. Observe the attachment card in webchat on initial page load.

Expected

• Attachment renders as playable audio with player controls and download link.

Actual

• Attachment renders as "Unavailable — Outside allowed folders" with a blocked status card, despite the server confirming {"available": true}.

Evidence

• Trace/log snippets

Server-side verification (all return expected results):

GET /__openclaw__/assistant-media?source=/home/node/.openclaw/media/outbound/8ad46428-7c81-412e-9df8-e1dbab658b57.mp3&meta=1
→ 200 {"available":true}

GET /__openclaw__/assistant-media?source=/home/node/.openclaw/media/outbound/8ad46428-7c81-412e-9df8-e1dbab658b57.mp3
→ 200 audio/mpeg

GET /__openclaw__/control-ui-config.json
→ 200 { "localMediaPreviewRoots": ["/home/node/.openclaw/media", ...] }

UI shows "Unavailable — Outside allowed folders" because the bootstrap config hadn't loaded when the attachment first rendered.

Human Verification (required)

• Verified scenarios: Traced the full code path from resolveAssistantAttachmentAvailability through isLocalAttachmentPreviewAllowed with empty vs populated roots. Confirmed server-side endpoints return correct results. Confirmed the sendJson default for other callers is unchanged.
• Edge cases checked: (1) Empty roots skips client gate → falls through to server check. (2) Populated roots with path outside them → still blocks as before. (3) Non-local sources (URLs) → still return available immediately. (4) sendJson callers other than bootstrap (availability, avatar meta) → unchanged no-cache default.
• What you did not verify: Full Vitest test suite execution (blocked by Node v24 environment issue in pod). CI should cover this.

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: During the bootstrap loading window, attachments now make server-side meta requests instead of being client-side denied. This adds a brief round-trip per local attachment on page load.
  • Mitigation: The meta endpoint is lightweight (JSON response, no file I/O beyond stat), the window is sub-second, and this is the same endpoint already used for all attachment checks that pass the client gate. The previous behavior (permanent false denial) is worse than a brief loading state.

Changed files

• src/gateway/control-ui.http.test.ts (modified, +10/-2)
• src/gateway/control-ui.ts (modified, +23/-18)
• ui/src/ui/chat/grouped-render.ts (modified, +7/-1)
• ui/src/ui/controllers/control-ui-bootstrap.test.ts (modified, +3/-3)
• ui/src/ui/controllers/control-ui-bootstrap.ts (modified, +1/-0)