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: state the folder-data-ref's move rules and known limits as the code now has them
reviewafe76525e3ec
diff --git a/CLAUDE.md b/CLAUDE.mdindex 99ca1007f..c1d393611 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -326,16 +326,40 @@ Persistence has two layers:a teammate's canvas); and the cache's missing `cwd` is the downgrade contract — an older buildopens it as a plain inline canvas instead of writing a fresh file into the folder. Its side filesfollow it: settings.json and the board log under `userData/project-files/<id>/.nodeterm/`- (`appDataProjectRoot`; settings still load as `'shared'`), canvas images to the existing+ (`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 answersthe folder, because it means where terminals run and what a relay seat is jailed to. Movingbetween 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 thedata file holds the canvas; files git tracks are kept unless the user confirms); into the folder =- `prepareFolderStorage` (refuses an occupied folder, like "Set folder…"), then save; the sweep- deletes the departed side's copy only once the folder file has landed, and keeps the rev. New- folder projects follow `settings.newProjectStorage`; a folder that already has a project.json is- adopted as it is, in its folder.+ `prepareFolderStorage` (refuses an occupied folder, like "Set folder…"), then save, then+ `projectStorage` (where the store has the canvas now). New folder projects follow+ `settings.newProjectStorage`; a folder that already has a project.json is adopted as it is, in its+ folder. Rules the moves rest on:+ - **The data file goes only when THIS save wrote the folder file** (`sweepRemovedDataFiles`'+ `folderFilesWritten`), never because `lastWritten` remembers one: a file can leave the folder+ behind the store's back (`git rm`, a branch checkout) while the record stays, an unchanged+ canvas then skipped the write as "unchanged", and the sweep deleted the only copy. For the same+ reason the record of a folder file is dropped when its project moves into app data (kept file+ or not) and when an entry takes a folder over from a data file ("Set folder…", a move back).+ - **A move into the folder whose folder write fails stays in app data, index included**: the+ folder leg swallows a failed write, so the save keeps that entry a folder-data-ref for that save+ (`appDataCanvas`, the one builder of its cache). The menu reads `projectStorage` after the save,+ puts the flag back and says the move failed; it never reads a landed save as a landed move.+ - The rev continues across a move (the sweep keeps it for an id that is still live).++ **Known limits:** an older build that opens a folder-data-ref while a folder `project.json` is+ 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.+ 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+ writers refuse with no write path; the relay verbs are handled here), and its repo scan finds no+ `project.json` in that folder, so it can offer the folder as a new project and write one there.+ SSH projects and Server `team bootstrap` cannot use the kind.In all three the file carries CONTENT and the entry carries the machine-local half — project`id`, `viewport`, `defaultAccountId`, `breadcrumbs`, `closedSessions`, `localApprovalId`,diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 7c7baee5f..07c27ffd6 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1119,7 +1119,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 movebetween 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.+nothing in its folder. 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.**A project with no folder is a real project — degrade explicitly, never silently.** "New project"creates a cwd-less canvas, so every folder-shaped feature meets one. Keep the affordance and