Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

docs: make the file-manager bullet true, and fix a stale relay claim

albaneselorenzoaa44fd959d5b
diff --git a/CLAUDE.md b/CLAUDE.md
index 0ea14aeaa..b9166fd31 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -859,33 +859,85 @@ session.
the folder shown (a `nodeterm:open-terminal` event, the sibling of `nodeterm:open-file`).
- **It adds NO new IPC.** Everything runs on the existing `FsApi` (`list`/`mkdir`/`exists`/
`write`) — which is why it works on Desktop, the Server Edition, an SSH project and a relay tab
- on day one. **Rename/move/delete are the deliberate v1 gap**: each needs a new leaf in
- `core/fs-ops`, an IPC channel, preload, the ws-bridge, `main/ssh-fs` (remote quoting) and the
- relay host-service, plus confirm dialogs and dangerous-path guards. That is a separate change
- with separate risk, not a corner to cut inside this one.
+ on day one; `mkdir`/`exists` are genuinely LIVE on a relay tab (see the Explorer bullet above —
+ that line used to claim otherwise), so "New folder…" works there too. **Rename/move/delete are
+ the deliberate v1 gap**: each needs a new leaf in `core/fs-ops`, an IPC channel, preload, the
+ ws-bridge, `main/ssh-fs` (remote quoting) and the relay host-service, plus confirm dialogs and
+ dangerous-path guards. That is a separate change with separate risk, not a corner to cut inside
+ this one.
- **Which filesystem** is `EditorNode`'s decision, read the same way: `data.sshFs` → the SSH
project's host over the ControlMaster; otherwise the node's own SESSION api, which is the local
core for a local project and the PEER's for a relay tab. Reading it off `useSession()` rather
than `window.nodeTerminal` is the entire reason a relay tab browses the right machine.
- **Opening is delegated, never reimplemented**: a file dispatches `nodeterm:open-file`, so
editor-vs-video-vs-image routing stays in Canvas's one `openFile` and this node never grows a
- second opinion about what a `.png` is. `fileOpenTarget` decides only canvas-vs-OS, and a
- REMOTE listing never reaches the OS branch — `shell.openPath` opens a path on THIS machine, so
- handing it a host path either does nothing or, if that path exists here too, opens an unrelated
- local file.
- - **Four empty states stay four** (loading / could not read / the folder is empty / the filter
- matches nothing). Collapsing any pair into one blank pane is the failure this file warns about
- elsewhere, and an empty filter matches everything so select-all+delete cannot blank the list.
+ second opinion about what a `.png` is. `fileOpenTarget` decides only canvas-vs-OS, and a REMOTE
+ listing never reaches the OS branch — `shell.openPath` opens a path on THIS machine. **The OS
+ branch is now also gated on being ABLE to open locally**, not just on remoteness: `shell.openPath`
+ is a documented `noop` in the Server Edition (`bridge/stubs.ts:180-186`), and a browser tab's own
+ session `source` is `'local'` — `SessionSource` declares `'server'` but nothing ever constructs
+ it (`session/session.ts:8`), so `source` alone can never tell you you're in a browser, only
+ `isBrowserRuntime()` can. Opening a `.zip`/`.dmg` was therefore a silent dead click; closed by
+ `canUseLocalShell` (`lib/download.ts`) — ONE predicate for every `shell.*` path action, with
+ `canRevealLocally` kept as its older reveal-specific name so existing callers are untouched.
+ Reveal was gated and openPath was not, and writing that rule twice is how they drifted.
+ - **Two state bugs, both fixed.** (a) A directory a removed worktree took with it used to render
+ as "This folder is empty." — not "Could not read this folder" — because `FsApi.list` is
+ fail-open by contract (`core/fs-ops.listDir`/`SshFs.listDir` both end `catch { return [] }`, and
+ the SSH IPC resolves `[]` even for a dead ControlMaster). `fs.exists` cannot disambiguate either:
+ it's `stat`-based (true for a dir you can stat but not `readdir`), and on SSH its `false` can't
+ separate "gone" from "the ControlMaster died" — the same conflation `SshFs.readTextChecked`
+ (`main/ssh-fs.ts:164-176`) refuses, on the rule "a failed read is never evidence of absence". Now
+ disambiguated by probing the PARENT's listing instead (`classifyEmptyListing`, pure,
+ `lib/filesNode.ts` — the idiom `SshProjectDialog.tsx:112-125` and `file-links.ts`'s
+ `makeDirListingLookup` already use), which answers `missing` / `empty` / `unknown`: an unreadable
+ parent answers `unknown`, and we keep saying "empty" rather than claim a deletion we can't prove.
+ (b) Nothing reset the list on navigation, so "Loading…" was reachable only on the very first
+ mount — every later directory change showed the PREVIOUS directory's rows. Fixed by storing the
+ listing WITH the cwd it belongs to, so a cwd change IS the loading state by construction; a
+ re-list after a create deliberately keeps its rows (same directory, re-read).
- The title tracks the folder only while `titleAuto` is unset — the same contract an agent node's
session name uses, so navigating never overwrites a name the user typed.
- A files node inside a REMOVED worktree is displaced like an editor, not like a terminal
- (`displacedByWorktree`): it has no session to disturb, so it is caught by path wherever it sits,
- and it gets its `cwd` re-pointed rather than an editor's `fileMissing` — a directory can be
- re-pointed, a dead file cannot. Left out, it would show "Could not read this folder" forever
- AND keep the dead path in `project.json`.
+ (`displacedByWorktree`): it has no session to disturb, so it is caught by path wherever it sits.
+ The patch is the pure `displacedFilesPatch` (`lib/filesNode.ts`), where `null` means LEAVE IT
+ ALONE on the dead path — the parent probe above then tells the truth — because
+ `resetDisplacedCwd`'s fallback can be `undefined` and `FilesNode` reads `data.cwd || '/'`:
+ writing `undefined` through would have silently listed the filesystem ROOT instead. The title
+ rewrites alongside when `titleAuto` holds — the ONE cwd write that does not go through `navigate`.
+ - **"New terminal here" was broken on BOTH remote kinds, and not by this node's own doing.**
+ `addTerminal` resolves the project from `activeProjectId` and `createTerminalNode` does
+ `cwd: ssh ? ssh.remoteCwd : cwd` (`state/workspace.ts`) — on an SSH project the folder on screen
+ was silently DISCARDED and the terminal opened at the project root, a pre-existing hole in
+ `addTerminal`'s `cwdOverride` contract affecting every caller, not just this one. Fixed by the
+ pure `sshBindingForCwd`, which rebinds `remoteCwd` to the named directory and keys on an EXPLICIT
+ override only — an SSH project can still carry a local `project.cwd`, and promoting that would
+ root remote terminals at a path from the wrong machine. On a RELAY tab there is no `ssh` to
+ rebind, so the row used to spawn a plain LOCAL terminal at the peer's remote path; it is now
+ withheld there instead — spawning onto a peer's core is a real feature, not a one-liner.
- Creation is gated on the project having a directory (`hasCwd`) on every surface — pane menu,
Dock, sidebar "+", ⌘K, and the group-frame menu, where it inherits a bound **worktree's** cwd
via `cwdForNewNodeIn`, so a frame per branch also means a file tree per branch.
+ - **A node kind not registered in `lib/reopenNode.ts` is a trap, and this one fell in it.** Every
+ kind must sit in exactly one of `UNRESTORABLE` or a `buildBase` `case` — `files` was in neither,
+ so ⇧⌘T recorded a snapshot (and a persisted `closedSessions` twin) that `buildBase`'s
+ `default: return null` could never restore: a dead, clickable entry that compiles, typechecks and
+ passes every test. `files` now has a `case` (it IS restorable — its whole state is the directory
+ it shows), unlike `trigger`, excluded for the same missing-case reason
+ (`reopenNode.ts:58-60`, the comment that made this findable). Two kinds have fallen in this trap
+ now; treat registration as a checklist item for the next one.
+ - **Kanban: deliberately not a card.** `canvas/toKanbanSession.ts` maps `browser`, `sticky` and
+ `terminal` and returns `null` for everything else — cards do not "derive from terminal nodes",
+ they derive from that explicit list. A files node has no session to co-attach and no text to
+ edit; its value is spatial adjacency to the terminals working in the directory, which a column
+ layout would discard.
+ - `folderTitle` lives in `lib/explorerCreate.ts` (a zero-import leaf), not `lib/filesNode.ts`:
+ `filesNode.ts` imports `isVideoFile` FROM `state/workspace`, so importing back would close a
+ cycle. `filesNode.ts` re-exports it, so call sites are unchanged.
+ - **The `/`-separator assumption is a KNOWN gap, shared with `explorerCreate`** (the Explorer
+ drawer and canvas "New file…" already run on the same helpers) — `C:\x\y` reads as one segment.
+ To be closed in ONE place for both, using the core-owns-the-dialect rule `terminal/file-links.ts`
+ already implements.
- **Mobile**: N/A — *nodeterm mobile* attaches to tmux sessions over the transport protocol and
has no canvas or file-browsing concept; adding one means extending that protocol.
- **dino** (`DinoNode.tsx`) — a small self-contained T-Rex-style runner on a canvas (no PTY);
@@ -2396,7 +2448,15 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
**New File… / New Folder…** (empty-area right-click targets the root; SSH projects create on the
host). Canvas pane right-click and ⌘K also expose **New file…** (creates under the project cwd,
opens an editor node). These use `mkdir` + `exists` added to `FsApi`/`SshFsApi` across
- desktop/server/SSH (`core/fs-ops.ts`, `main/ssh-fs.ts`; relay remote-fs degrades to `false`).
+ desktop/server/SSH (`core/fs-ops.ts`, `main/ssh-fs.ts`). **Relay tabs are NOT degraded**: a
+ relay tab's `fs` routes through `bridge/relay-api.ts:86` (`fs: files.fs`) → `buildFilesApi`'s
+ `IPC.fsMkdir`/`IPC.fsExists` (`bridge/ws-bridge.ts:474-475`) → `core/fs-handlers.ts:43-44` →
+ the real `fsOps.makeDir`/`fsOps.pathExists` on the peer's core, so both verbs are live there.
+ What genuinely still lacks them is the legacy PHONE vocabulary
+ (`main/remote/host-service.ts`), whose `handleFs` switches on `fs.list`/`read`/`readBinary`/
+ `write` and nothing else, so `fs.mkdir`/`fs.exists` fall through to the dispatcher's
+ `Unknown method` **rejection** (line 695) rather than degrading to `false` — a different
+ dispatch path (`relay-host.ts:22-24`) from the relay tab above.
Expanded dirs **persist per project** across drawer close + app restart (`state/explorer.ts`
zustand store, localStorage `nodeterm.explorerExpanded`). The header pin docks it like the
sessions sidebar (`lib/explorerPin.ts`, `nodeterm.explorerPinned`, default off): overlay