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: where a folder project kept in app data keeps its whiteboards

reviewed97417ef21c
diff --git a/CLAUDE.md b/CLAUDE.md
index e9f2c9bb7..aaab96970 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -327,8 +327,12 @@ Persistence has two layers:
opens it as a plain inline canvas instead of writing a fresh file into the folder. Its side files
follow it: settings.json and the board log under `userData/project-files/<id>/.nodeterm/`
(`appDataProjectRoot`; settings still load as `'shared'`; removed with the project when it is
- deleted, kept when it moves back into its folder), canvas images to the existing
- `userData/canvas-images` fallback (`sideFilesFolderForProject`). `localCwdForProject` still answers
+ deleted, kept when it moves back into its folder), whiteboards in the same root
+ (`whiteboardLocationForProject`; the folder's boards, drawn before the move, are read after it and
+ never written, and a move back copies the app-data boards over the folder's older files —
+ `carryWhiteboards` in `prepareFolderStorage`; not the shared `userData/whiteboards`, which is
+ keyed by node id, and two folders holding one committed canvas share node ids), canvas images to
+ the existing `userData/canvas-images` fallback (`sideFilesFolderForProject`). `localCwdForProject` still answers
the folder, because it means where terminals run and what a relay seat is jailed to. Moving
between the two is the tab menu's "Store canvas in app data / in folder"
(`lib/projectStorageMove.ts`): into app data = save, then `releaseFolderFiles` (refused until the
@@ -353,7 +357,10 @@ Persistence has two layers:
still there (a tracked file the user kept) keys its watcher, its phone writer and `readLocalRef`
on the entry's `cwd`, so until it next saves its index it can adopt that file as the project
(after which the entry is a plain folder ref there and the data file is orphaned). Images and a
- board log stay on the side they were written on when a project moves, in either direction.
+ board log stay on the side they were written on when a project moves, in either direction; so do
+ a folder's whiteboard files after a move into app data (read, never removed). A board edited in
+ app data replaces the folder's file on the move back, including a teammate's newer version of a
+ tracked board pulled in the meantime (git still has it).
Handoff files from Transfer still write `<node cwd>/.nodeterm/`. The iOS app does not know the
kind: over direct SSH it reads the entry's `project` cache, which has no `cwd`, so it shows a
project without a folder (it never reads or writes the folder file, and its board and label
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 54cc7b73a..64b57672c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1156,7 +1156,9 @@ folder-data-ref (issue #1145: a folder project whose canvas lives in app data):
inline one, `writeDataFile`'s rule decides between instances, and the rev continues across a move
between the folder and app data. Anything that reads or writes `<cwd>/.nodeterm/` must ask
`folderFileCwd(e)` (or the side-file accessors), never `e.cwd` alone — a project can have a cwd and
-nothing in its folder. And `lastWritten` is a record, not evidence that a file is on disk: a file
+nothing in its folder. Such a project's side files keyed by node id (whiteboards) go under its own
+app-data root, never into a folder every project shares: two folders holding one committed canvas
+share node ids. And `lastWritten` is a record, not evidence that a file is on disk: a file
can leave a folder behind the store's back (`git rm`, a checkout), so nothing may be deleted
because the store remembers writing its replacement. The data-file sweep asks what THIS save wrote.
diff --git a/docs/whiteboard-node.md b/docs/whiteboard-node.md
index ce8f0dc3b..ea2c7ae9d 100644
--- a/docs/whiteboard-node.md
+++ b/docs/whiteboard-node.md
@@ -57,6 +57,18 @@ falling back to `<userData>/whiteboards/` for a cwd-less canvas, an SSH project
read-only project folder (the `canvas-images.ts` rules). Writes are atomic (`writeFileAtomic`; the
PNG through `tempNameFor` + `renameAtomic`, since `writeFileAtomic` writes text).
+A folder project whose canvas is kept in app data (issue #1145) writes nothing into its folder: its
+boards go to the same layout under its own app-data root,
+`<userData>/project-files/<projectId>/.nodeterm/whiteboards/`, which is deleted with the project
+(`WorkspaceStore.whiteboardLocationForProject`, wired into both shells as `whiteboardLocation`). Not
+the shared `<userData>/whiteboards/`: that folder is keyed by node id, and two folders holding the
+same committed canvas share node ids, so two such projects would read and overwrite each other's
+boards. The folder's boards, drawn before the move, are read after every place a save can land and
+never written, so a board still opens after the move and its next save lands in app data. A move
+back into the folder first copies the app-data boards over the folder's older files
+(`carryWhiteboards`), since the folder is read first again; a folder project reads its app-data
+root after its folder for a board that did not copy.
+
**The core derives the path from (project, node id); it never accepts one.** Node data comes from
the git-shared `project.json`, which anyone with commit access can edit — a path taken from it
could aim a read or an overwrite anywhere. A node id must be a `string` passing `isSafeNodeId`