Remote (SSH) case: file preview / file-raw resolves against the local filesystem, not the remote host

[Randalix]

Summary

Clicking an absolute file path printed by an agent (or opening it in the File Viewer) in a remote (SSH) case does not open the file — the file simply isn't found, even though it exists on the remote host and the session is clearly working in that directory.

Repro

1. Create a Remote Case (New Case → Remote) pointing at a directory on a remote SSH host.
2. Run any agent mode (I used pi) that writes a file into that directory (e.g. a generated image in an output/ subfolder).
3. Click the absolute path the agent prints (or open the same path via the File Viewer panel).

Expected: image/file preview loads, same as for a local case.
Actual: the preview fails to open (behaves as if the file doesn't exist).

Root cause (from reading the source)

/api/sessions/:id/file-raw resolves purely against the local filesystem of the machine running the Codeman server:

const validated = validateSessionFilePath(session.workingDir, filePath);
...
const stat = await fs.stat(resolvedPath);

For a remote case, session.workingDir is a path that only exists on the remote host — there's no SSH-aware branch here, unlike the tmux/launch code path (buildSshConnectionArgs, buildRemoteLaunchCommand etc.), which is fully SSH-aware. A plain fs.stat against a remote-only path on the local server obviously fails.

I'd guess the sibling routes (file-content, file-preview, file-thumbnail, filesystem/browse, filesystem/preview) have the same gap, since they follow the same local-fs pattern — I didn't check all of them individually.

Suggested directions

• Proxy file reads for remote sessions through SSH (e.g. cat/sftp) reusing the existing buildSshConnectionArgs helper, gated behind the same size caps already used for local previews.
• At minimum, surface a clear "file preview isn't available for remote cases yet" state instead of a generic not-found, which currently looks like user/agent error rather than a known limitation.

Workaround in use

SSHFS-mounting the remote directory onto the identical absolute path on the Codeman-server host, so the existing local fs calls transparently succeed. Works, but obviously not a general solution (extra moving part, doesn't help anyone without root/mount access).

Environment

• Codeman installed via the official install script, self-hosted (not Docker case — a Remote/SSH case)
• Remote host: Linux, reached via a saved Remote Host + Remote Case
• Agent mode: pi
• Files: PNGs written by a process running on the remote host, in a subdirectory of the case's remotePath

[Ark0N]

Your reading of the cause is exactly right, including the guess at the end: file-content, file-preview, file-thumbnail and the attachment registration path all had the same gap, because they all end in a local realpathSync + fs.stat against a path that only exists on the other host.

#421 (from you, thank you) is the fix and it is in review now. For anyone finding this issue later, the shape of it:

• src/remote-files.ts is the one remote-read layer, built on the existing buildSshConnectionArgs() so the quoting rule for ssh lines stays in one place.
• Bodies stream over cat (or tail -c +N | head -c L for a Range), so a large remote file costs an ssh process, not server RAM.
• The guard order local reads use is kept, with realpath done on the host that can actually resolve it: ownership, then lexical containment (an escape is refused before a connection is opened), then remote realpath of file and workspace root, then containment, then the size cap against the remote size.
• An unreachable host answers 502 with the remote reason instead of the 404 that made infrastructure look like a bad path.
• Writes, office previews and generated thumbnails stay out of scope and now answer 400 with a real message, which is the "surface a clear state" half of your report.

On the sshfs workaround: the PR deliberately does not fall back to a local file of the same name, even when one exists. Serving the local twin would hand back a different filesystem's bytes under a name you believe is the remote file, and that failure is much worse than a 404. Your mount keeps working, it just stops being load-bearing.

Leaving this open until the PR lands.