fix(workspace files API): EIC parity for ListFiles + DeleteFile (#2999 PR-A)

[HongmingWang-Rabbit]

User-visible bug

Canvas Files tab returns "0 files / No config files yet" for every SaaS workspace, every root (/configs, /home, /workspace, /plugins). Reported by user (canvas screenshot, hongming.moleculesai.app, "Hongming Personal Brand Agent" — claude-code, T4, online). See #2999 for the umbrella issue + the four follow-up PRs.

Root cause

ListFiles in templates.go was missing the SSH-via-EIC branch that ReadFile (PR #2785) and WriteFile (PR #1702) already have. On SaaS, dockerCli is nil → findContainer returns "" → falls through to resolveTemplateDir which only matches baked-in template names. For a user-named workspace it matches nothing, so the handler silently returns []fileEntry{}.

DeleteFile had the same gap — right-click delete (introduced in PR-C of this issue) would silently no-op once #1 was fixed.

Fix

1. Extracted the EIC tunnel dance into a single withEICTunnel(ctx, instanceID, fn) SSOT. Refactored existing writeFileViaEIC + readFileViaEIC to use it. Added listFilesViaEIC + deleteFileViaEIC on the same scaffold. The LogLevel=ERROR fix from PR fix(files-eic): silence ssh known-hosts warning that 500'd Hermes config load #2822 now lives in one eicSSHSession.sshArgs() helper instead of being duplicated per op.

2. Factored remote shell strings into pure functions (buildInstallShell / buildCatShell / buildRmShell / buildFindShell / parseFindOutput) so the wire shape is testable without a real EIC tunnel.

3. Refactored resolveWorkspaceFilePath(runtime, root, relPath) to honor ?root=. New rule: /configs (or empty / unrecognized) → runtime managed-config dir via workspaceFilePathPrefix (preserves the existing config.yaml round-trip on hermes/claude-code); /home / /workspace / /plugins → literal absolute path on the EC2 host. List/Read/Write/Delete now agree on what file a tree row points to — pre-fix List would say "/home contents" but Read/Write would route to /configs.

4. ListFiles + DeleteFile dispatch on instance_id != "" → EIC helper. Errors from the EIC path produce 500 (not silent fall-through to local-Docker, which would mask the failure as "0 files" — the exact user-visible symptom).

5. Added ?root= validation gate to WriteFile + DeleteFile so an out-of-allowlist root is rejected before the resolver runs.

Test coverage (≥4 new test files, ≥17 new tests)

Test	Pins
TestResolveWorkspaceFilePath_RuntimeIndirection	/configs → runtime prefix per-runtime
TestResolveWorkspaceFilePath_LiteralRoots	/home, /workspace, /plugins literal
TestResolveWorkspaceRootPath	directory-only translation used by listFilesViaEIC
TestSSHArgs_HardenedFlags	centralised ssh option set
TestEicSSHSessionSingleSourceForSSHFlags	behaviour-based AST gate — no copy-pasted ssh args
TestBuildInstallShell / TestBuildCatShell / TestBuildRmShell / TestBuildFindShell	remote shell shape
TestBuildFindShell_DepthForwarding	depth not hard-coded
TestParseFindOutput / TestParseFindOutput_EmptyInput	parser symmetry with container path
TestListFiles_EICDispatch_Success / Error	sqlmock dispatch on instance_id != ""
TestListFiles_EICBranch_NotTakenForSelfHosted	back-compat — instance_id == "" stays on Docker path
TestDeleteFile_EICDispatch_Success / Error	same shape for delete
TestListFiles_RootValidation / TestDeleteFile_RootValidation	?root=/etc → 400 before any DB / EIC

Verification

• go build ./... clean
• go test ./... clean (full workspace-server suite)
• Will be live-verified against staging on hongming.moleculesai.app after merge: open Files tab → expect populated /home + /configs + /workspace listings (not "0 files"); right-click delete on /configs/old.yaml → expect file removed on the EC2 host.

Three weakest spots (hostile self-review)

1. TestEicSSHSessionSingleSourceForSSHFlags counts source occurrences of LogLevel=ERROR. A future refactor that legitimately moves the literal (e.g. into a constant) would trigger a false positive. Failure message points to the load-bearing constraint (must appear in sshArgs); operator can adjust. Acceptable — the alternative (no gate) is what let PR fix(files-eic): silence ssh known-hosts warning that 500'd Hermes config load #2822's regression slip in originally.

2. eicFileWriteTimeout constant kept as a back-compat alias for prior tests. Documented + safe to remove on the next pass.

3. The resolver tests pin runtime → prefix map values (/home/ubuntu/.hermes, /configs, etc.). A future runtime addition that ships a new prefix needs the test updated. Intentional — silent prefix changes orphan saved files, so a test failure on map edit IS the right signal.

Rollout / rollback

• Rollout: standard staging → main auto-promote; live-verify on hongming.moleculesai.app once deployed.
• Rollback: revert this commit. All four pre-existing self-hosted code paths (local-Docker, ephemeral-volume, host template-dir) are unchanged.

Follow-ups (separate PRs against #2999)

• PR-B: External-runtime "not available" placeholder for FilesTab.
• PR-C: Right-click context menu (Download / Delete).
• PR-D: Drag-drop upload to target folder.
• RFC RFC: replace Docker-exec handlers with HTTP-forward to workspace's own URL (chat upload + 5 follow-ons) #2312 subtask 2 (long-term): replace EIC entirely with HTTP-forward to workspace's own URL. Out of scope here — that's a 5-surface refactor.

Refs #2999.

🤖 Generated with Claude Code