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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs: make the file-manager bullet true, and fix a stale relay claim
albaneselorenzoaa44fd959d5b
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 SSHproject's host over the ControlMaster; otherwise the node's own SESSION api, which is the localcore for a local project and the PEER's for a relay tab. Reading it off `useSession()` ratherthan `window.nodeTerminal` is the entire reason a relay tab browses the right machine.- **Opening is delegated, never reimplemented**: a file dispatches `nodeterm:open-file`, soeditor-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'ssession 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** cwdvia `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 andhas 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 thehost). 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 thesessions sidebar (`lib/explorerPin.ts`, `nodeterm.explorerPinned`, default off): overlay