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
fix(canvas): a workspace save that fails says so, and retries
Howard Youngdahlc1aa59e544d4
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex b77cca41e..5a5b038e6 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -144,6 +144,12 @@ import { markMobileLaunchSeen, shouldShowMobileLaunch } from '../lib/mobileLauncimport type { DictationTarget } from '../components/DictationOverlay'import { describeOs, REPO_URL } from '../lib/bugReport'import { shouldReleasePaneFocus } from '../lib/paneFocus'+import {+ autosaveDelay,+ nextSaveDelivery,+ type SaveDelivery+} from '../lib/savePersistence'+import { SaveFailureBar } from '../components/SaveFailureBar'import {adoptedNodesNotice,decideExternalChange,@@ -884,6 +890,11 @@ export function Canvas() {// give the debounced-autosave effect a dependency that CHANGES in that case — `dirty` stays true// throughout, so without it the effect would never re-arm. Rare, so a re-render costs nothing.const [resaveTick, setResaveTick] = useState(0)+ // What the last whole-workspace save did, when it did not land. `undefined` is the ordinary+ // state. It is a dep of the autosave effect BECAUSE a refusal must re-arm the debounce: `dirty`+ // never goes false on a failed save, so nothing else in that dep list can change and the timer+ // would never be scheduled again (the 2026-09-02 silent freeze).+ const [saveDelivery, setSaveDelivery] = useState<SaveDelivery | undefined>(undefined)// The active project's .nodeterm file changed on disk while we have unsaved local edits AND it// changed something we also hold (the user must pick a side for that half). `added` counts the// nodes that arrived with it and were already adopted onto the canvas — they are never part of@@ -2196,8 +2207,13 @@ export function Canvas() {// persists the conversion, so the next load is a no-op.const projects = ws.projects.map(migrateProjectTags)useProjects.getState().hydrate({ ...ws, projects })- // Upgrade the on-disk format (e.g. v1 -> v2 migration) right away.- void api.workspace.save(useProjects.getState().toWorkspace())+ // Upgrade the on-disk format (e.g. v1 -> v2 migration) right away. Reported like every+ // other save: a `void` here used to make the very first write of the session the one write+ // that could fail with no signal at all — including the format migration.+ api.workspace.save(useProjects.getState().toWorkspace()).catch((err: unknown) => {+ console.warn('[canvas] initial workspace save failed', err)+ setSaveDelivery((prev) => nextSaveDelivery(prev, Date.now()))+ })})return () => {cancelled = true@@ -2513,7 +2529,20 @@ export function Canvas() {// takes seconds — and clearing `dirty` unconditionally afterwards marked edits made DURING the// await as saved, which let the watcher's not-dirty branch clobber them (field bug 2026-08-10).const gen = dirtyGenRef.current- await api.workspace.save(useProjects.getState().toWorkspace())+ try {+ await api.workspace.save(useProjects.getState().toWorkspace())+ } catch (err) {+ // The save was refused, or the socket carrying it closed (the ws bridge synthesises+ // E_DISCONNECTED so an await fails rather than hanging). Both used to be thrown away by the+ // `void persist()` that called us, and BOTH ended persistence for the life of the tab: with+ // `dirty` still true, no dep of the autosave effect changes, so its 800 ms timer is never+ // scheduled again. Record the refusal (it is a dep, so this re-arms the effect at the+ // backoff delay) and let the strip say so. Never clear `dirty` — nothing reached disk.+ console.warn('[canvas] workspace save failed', err)+ setSaveDelivery((prev) => nextSaveDelivery(prev, Date.now()))+ return+ }+ setSaveDelivery(undefined)if (canClearDirty(gen, dirtyGenRef.current)) {setDirty(false)return@@ -2692,11 +2721,16 @@ export function Canvas() {// (overwrite the external disk version) before the user can choose. `conflict` is a dep so// resolving it (either button clears it) re-arms the save.useEffect(() => {- if (!dirty || conflict) return- const t = setTimeout(() => void persist(), 800)+ // One rule, in `autosaveDelay`: null = do not arm (nothing to save, or the user owes a+ // conflict decision), a number = wait that long. After a refused save it returns the BACKOFF+ // delay rather than null, which is what turns a dead timer into a bounded retry.+ const delay = autosaveDelay(dirty, !!conflict, saveDelivery)+ if (delay === null) return+ const t = setTimeout(() => void persist(), delay)return () => clearTimeout(t)- // `resaveTick` re-arms the timer after a save that could NOT clear dirty (an edit raced it).- }, [dirty, conflict, persist, resaveTick])+ // `resaveTick` re-arms the timer after a save that could NOT clear dirty (an edit raced it);+ // `saveDelivery` re-arms it after one that could not be written at all.+ }, [dirty, conflict, persist, resaveTick, saveDelivery])// ---- remote canvas mirror (phone host side) ----// While phone access is on, push the serialized active-project canvas to main (debounced ~120ms)@@ -12366,6 +12400,16 @@ export function Canvas() {</button></div>)}+ {saveDelivery && (+ <SaveFailureBar+ delivery={saveDelivery}+ onRetry={() => {+ // Clearing the delivery is the re-arm: it is a dep of the autosave effect, and with+ // `dirty` still true the timer comes back at the ordinary debounce.+ setSaveDelivery(undefined)+ }}+ />+ )}{conflict && (<ConflictBaraddedCount={conflict.added}diff --git a/src/renderer/components/SaveFailureBar.tsx b/src/renderer/components/SaveFailureBar.tsxnew file mode 100644index 000000000..2879e5da9--- /dev/null+++ b/src/renderer/components/SaveFailureBar.tsx@@ -0,0 +1,26 @@+import { saveFailureMessage, type SaveDelivery } from '../lib/savePersistence'++/** Non-blocking strip shown when the whole-workspace save did NOT land.+ *+ * It exists because the alternative shipped for months: `void api.workspace.save(...)` threw its+ * rejection away, so a canvas that had stopped being written to disk looked exactly like one that+ * was up to date. The strip states the consequence rather than a cause it cannot know, and — once+ * the bounded retry schedule is spent — offers the only thing left, another attempt.+ *+ * `Retry now` clears the delivery state, which is what re-arms the debounce. */+export function SaveFailureBar({+ delivery,+ onRetry+}: {+ delivery: SaveDelivery+ onRetry(): void+}): JSX.Element | null {+ const text = saveFailureMessage(delivery)+ if (!text) return null+ return (+ <div className="conflict-bar save-failure-bar">+ <span>{text}</span>+ {delivery.kind === 'failed' && <button onClick={onRetry}>Retry now</button>}+ </div>+ )+}diff --git a/src/renderer/lib/externalChange.test.ts b/src/renderer/lib/externalChange.test.tsindex f60e2b383..1cf500d33 100644--- a/src/renderer/lib/externalChange.test.ts+++ b/src/renderer/lib/externalChange.test.ts@@ -182,7 +182,18 @@ describe('mergeIncomingNodes', () => {describe('conflict copy', () => {it('keeps the historical sentence when nothing was added', () => {- expect(conflictBarMessage(0)).toBe('Project file changed on disk (git pull or another machine).')+ expect(conflictBarMessage(0)).toContain(+ 'Project file changed on disk (git pull or another machine).'+ )+ })+ it('always says the autosave is suspended — in every wording', () => {+ // The bar SUSPENDS the debounced whole-workspace save for as long as it is up (Canvas's+ // autosaveDelay returns null on a conflict), and it is cleared only by its own two buttons or+ // a project switch. A user who read this strip as an FYI about someone else's git pull had no+ // way to know their own canvas had stopped being written — 2026-09-02: two and a half hours,+ // eight session cards opened and never persisted, no signal anywhere.+ for (const n of [0, 1, 2])+ expect(conflictBarMessage(n)).toContain('not being saved until you choose')})it('names what arrived, and says it is already on the canvas', () => {const msg = conflictBarMessage(1)diff --git a/src/renderer/lib/externalChange.ts b/src/renderer/lib/externalChange.tsindex e60524910..abcfb1060 100644--- a/src/renderer/lib/externalChange.ts+++ b/src/renderer/lib/externalChange.ts@@ -106,13 +106,21 @@ export function mergeIncomingNodes<T extends { id: string }>(current: T[], incom/** The conflict strip's sentence. Derived from what actually arrived so the bar cannot claim* something vague while a real session sits on the canvas behind it. */export function conflictBarMessage(addedCount: number): string {- if (addedCount <= 0) return 'Project file changed on disk (git pull or another machine).'+ // Every wording ends on the same clause, because the bar's most important fact is not what+ // changed on disk — it is that the autosave is SUSPENDED until one of the two buttons is+ // pressed, and stays suspended for as long as the bar is ignored. A user who read this strip as+ // an FYI about someone else's git pull had no way to know their own canvas had stopped being+ // written (the 2026-09-02 silent freeze: two and a half hours, eight unsaved cards).+ const paused = ' Your canvas is not being saved until you choose.'+ if (addedCount <= 0)+ return 'Project file changed on disk (git pull or another machine).' + pausedconst s = addedCount === 1 ? '' : 's'const verb = addedCount === 1 ? 'was' : 'were'return (`${addedCount} new session${s} registered from another device (your phone, or another machine) ` +`${verb} added to this canvas. Other parts of the project file also changed on disk — ` +- `choose which version of those to keep.`+ `choose which version of those to keep.` ++ paused)}diff --git a/src/renderer/lib/savePersistence.test.ts b/src/renderer/lib/savePersistence.test.tsnew file mode 100644index 000000000..07c51ec93--- /dev/null+++ b/src/renderer/lib/savePersistence.test.ts@@ -0,0 +1,144 @@+import fs from 'fs'+import path from 'path'+import { describe, expect, it } from 'vitest'+import {+ autosaveDelay,+ nextSaveDelivery,+ saveFailureMessage,+ saveRetryDelay,+ SAVE_DEBOUNCE_MS,+ SAVE_RETRY_ATTEMPTS,+ type SaveDelivery+} from './savePersistence'+import { decideExternalChange } from './externalChange'+import type { CanvasNodeState, Project } from '@shared/types'++const node = (id: string): CanvasNodeState =>+ ({ id, kind: 'terminal', position: { x: 0, y: 0 }, data: {} }) as unknown as CanvasNodeState++const project = (nodes: CanvasNodeState[]): Project =>+ ({ id: 'p1', name: 'p', color: '#fff', nodes }) as unknown as Project++describe('autosaveDelay — the one rule the debounce effect asks', () => {+ it('does not arm with nothing to save', () => {+ expect(autosaveDelay(false, false, undefined)).toBeNull()+ })++ it('does not arm while a conflict bar owes the user a decision', () => {+ // Unchanged from before the fix: firing here would silently "keep mine".+ expect(autosaveDelay(true, true, undefined)).toBeNull()+ })++ it('arms at the ordinary debounce when nothing has failed', () => {+ expect(autosaveDelay(true, false, undefined)).toBe(SAVE_DEBOUNCE_MS)+ })++ it('RE-ARMS after a refused save, at the backoff delay', () => {+ // The regression this whole module exists for. Before the fix a refusal left `dirty` true with+ // no dep change anywhere, so the timer was never scheduled again and the canvas stopped being+ // written for the life of the tab, silently.+ const first = nextSaveDelivery(undefined, 1)+ expect(first).toEqual({ kind: 'retrying', attempts: 1, at: 1 })+ expect(autosaveDelay(true, false, first)).toBe(saveRetryDelay(1))+ expect(autosaveDelay(true, false, first)).toBeGreaterThan(0)+ })++ it('stops arming once the bounded schedule is spent', () => {+ // Bounded on purpose: a whole-canvas last-writer-wins write must not be retried forever at a+ // destination we already know refuses it. The strip's Retry button is the way back.+ let d: SaveDelivery | undefined+ for (let i = 0; i < SAVE_RETRY_ATTEMPTS; i++) d = nextSaveDelivery(d, i)+ expect(d).toMatchObject({ kind: 'retrying', attempts: SAVE_RETRY_ATTEMPTS })+ const spent = nextSaveDelivery(d, 99)+ expect(spent).toEqual({ kind: 'failed', attempts: SAVE_RETRY_ATTEMPTS + 1, at: 99 })+ expect(autosaveDelay(true, false, spent)).toBeNull()+ })++ it('a cleared delivery (the Retry button) brings the ordinary debounce back', () => {+ expect(autosaveDelay(true, false, undefined)).toBe(SAVE_DEBOUNCE_MS)+ })+})++describe('the failure is stated, not swallowed', () => {+ it('says nothing while there is nothing to report', () => {+ expect(saveFailureMessage(undefined)).toBeNull()+ })++ it('names the consequence and what still holds, in both states', () => {+ const retrying = saveFailureMessage({ kind: 'retrying', attempts: 1, at: 0 })!+ expect(retrying).toContain('not being saved')+ expect(retrying).toContain('Retrying')+ // A card is not its tmux session, and telling the user their terminals died would be a lie.+ expect(retrying).toContain('terminals keep running')+ const failed = saveFailureMessage({ kind: 'failed', attempts: 6, at: 0 })!+ expect(failed).toContain('nothing will retry')+ expect(failed).not.toContain('Retrying.')+ })+})++describe('the trigger: an external change that REMOVES a node freezes the save', () => {+ // This is the 2026-09-02 shape reduced to its two seams. The server published a project whose+ // node list had shrunk (a reap, a git pull, another machine); the renderer was mid-edit.+ const before = project([node('a'), node('b')])+ const after = project([node('a')])++ it('classifies a removal as a conflict while dirty', () => {+ const decision = decideExternalChange({+ dirty: true,+ base: before,+ incoming: after,+ liveNodeIds: ['a', 'b']+ })+ expect(decision.kind).toBe('conflict')+ })++ it('and a conflict is what stops the autosave arming', () => {+ // The two halves joined: conflict ⇒ no timer ⇒ nothing is written until the user answers the+ // bar. Correct as a policy; catastrophic as a SILENT one, which is why the bar now says so.+ expect(autosaveDelay(true, true, undefined)).toBeNull()+ })+})++describe('the call site still honours the rule', () => {+ // Canvas is a monolith with no render harness (see canvas-wiring.test.tsx), so the wiring is+ // pinned by reading it. A source read is weak in general and the only thing standing between a+ // one-character deletion and a silently reintroduced two-and-a-half-hour data freeze here.+ // Normalized: the assertions below slice on '\n' literals and a Windows checkout hands us+ // '\r\n' (issue #578 — line-endings.guard.test.ts enforces this).+ const SRC = fs+ .readFileSync(path.join(__dirname, '..', 'canvas', 'Canvas.tsx'), 'utf8')+ .replace(/\r\n/g, '\n')++ it('drives the debounce through autosaveDelay, not an inline condition', () => {+ expect(SRC).toContain('const delay = autosaveDelay(dirty, !!conflict, saveDelivery)')+ expect(SRC).not.toContain('if (!dirty || conflict) return')+ })++ it('keeps saveDelivery in the effect deps, or a refusal never re-arms', () => {+ expect(SRC).toContain('}, [dirty, conflict, persist, resaveTick, saveDelivery])')+ })++ it('catches the save rejection instead of letting `void` eat it', () => {+ expect(SRC).toContain('setSaveDelivery((prev) => nextSaveDelivery(prev, Date.now()))')+ expect(SRC).toContain('[canvas] workspace save failed')+ })++ it('clears the delivery only on a save that actually landed', () => {+ // `setSaveDelivery(undefined)` must sit AFTER the await's catch, never before it: clearing it+ // first would hide the very failure the strip exists to show.+ const catchAt = SRC.indexOf('[canvas] workspace save failed')+ const clearAt = SRC.indexOf('setSaveDelivery(undefined)\n if (canClearDirty')+ expect(catchAt).toBeGreaterThan(0)+ expect(clearAt).toBeGreaterThan(catchAt)+ })++ it('renders the strip', () => {+ expect(SRC).toContain('<SaveFailureBar')+ })++ it('leaves no bare `void api.workspace.save(` anywhere', () => {+ // That spelling IS the bug: it discards the rejection AND the exception. Every save must+ // either be awaited by a caller that reports, or carry its own .catch.+ expect(SRC).not.toContain('void api.workspace.save(')+ })+})diff --git a/src/renderer/lib/savePersistence.ts b/src/renderer/lib/savePersistence.tsnew file mode 100644index 000000000..56a71a8d5--- /dev/null+++ b/src/renderer/lib/savePersistence.ts@@ -0,0 +1,101 @@+/** Pure rules for the renderer's whole-workspace autosave: when the debounce may be armed, how+ * long it waits, and what the user is told when a save does not land.+ *+ * Shaped after `pendingLaunch`'s launch-delivery states for the same reason they exist there: a+ * persistence path whose only failure report is a swallowed promise is one the user cannot act+ * on, and cannot even know about.+ *+ * The bug this closes (field report, Server Edition, 2026-09-02): the canvas stopped being+ * written to disk for two and a half hours while eight session cards were opened and several+ * closed, and nothing anywhere said so. `void api.workspace.save(...)` threw its rejection away,+ * and — worse — the debounce that would have retried was armed by an effect whose only deps are+ * `dirty`, the conflict bar, a stable callback and a tick. A save that rejects leaves `dirty`+ * TRUE, so every later edit's `setDirty(true)` is a no-op, no dep changes, the effect never+ * re-runs, and the 800 ms timer is never scheduled again. One refused save ended persistence for+ * the life of the tab. Nothing retried it and nothing reported it.+ */++/** The ordinary debounce: how long canvas edits settle before the whole workspace is written. */+export const SAVE_DEBOUNCE_MS = 800++/**+ * Backoff between retries of a REFUSED save, indexed by the number of attempts already made.+ * `null` = the schedule is exhausted; nothing will retry on its own.+ *+ * Bounded on purpose. A workspace save is a whole-canvas, last-writer-wins write, so a retry loop+ * with no end is not a safety net — it is an unattended writer hammering a destination we already+ * know refuses it. Roughly 46 s across five attempts covers a server restart or a browser tab+ * that lost its socket and reconnected; past that the honest move is to say so and hand the user+ * a button.+ */+const SAVE_RETRY_SCHEDULE_MS = [500, 1500, 4000, 10_000, 30_000] as const++/** Total attempts a refused save gets before it is reported as failed. */+export const SAVE_RETRY_ATTEMPTS = SAVE_RETRY_SCHEDULE_MS.length++export function saveRetryDelay(attemptsMade: number): number | null {+ return SAVE_RETRY_SCHEDULE_MS[attemptsMade - 1] ?? null+}++/**+ * What the save loop has to say about a canvas that is NOT on disk. `undefined` is the ordinary+ * state — either everything is saved, or a save is simply pending behind the debounce.+ */+export type SaveDelivery =+ /** The last save was refused; another attempt is scheduled. */+ | { kind: 'retrying'; attempts: number; at: number }+ /** The retry schedule is exhausted. Nothing will try again without the user. */+ | { kind: 'failed'; attempts: number; at: number }++/** Fold one refusal into the delivery state. Crossing the end of the schedule is what turns a+ * retry into a failure — the two are one counter, so the banner and the timer cannot disagree+ * about whether anything is still coming. */+export function nextSaveDelivery(prev: SaveDelivery | undefined, at: number): SaveDelivery {+ const attempts = (prev?.attempts ?? 0) + 1+ return { kind: saveRetryDelay(attempts) === null ? 'failed' : 'retrying', attempts, at }+}++/**+ * How long the autosave effect should wait before firing, or `null` for "do not arm".+ *+ * `null` has exactly two meanings and both are deliberate: there is nothing to save, or the user+ * has to decide something first. It is never "a save failed", because that is the state that used+ * to stop the timer forever by accident — a refused save arms the NEXT attempt at its backoff+ * delay, and only an exhausted schedule stops the loop.+ *+ * `conflictOpen` keeps its original meaning: the conflict bar only ever appears while dirty, so+ * without this gate the timer would fire and silently "keep mine", overwriting the external disk+ * version before the user could choose.+ */+export function autosaveDelay(+ dirty: boolean,+ conflictOpen: boolean,+ delivery: SaveDelivery | undefined+): number | null {+ if (!dirty || conflictOpen) return null+ if (!delivery) return SAVE_DEBOUNCE_MS+ return saveRetryDelay(delivery.attempts)+}++/**+ * The sentence the save-failure strip shows, or `null` while there is nothing to report.+ *+ * Says what was observed and never a cause that was not measured: from the renderer a refused+ * save, a dropped socket and a server that threw all look identical, so the text names the+ * CONSEQUENCE (the canvas is not on disk) and what still holds (the terminals are untouched —+ * a card is not its tmux session). That distinction is the difference between "I lost my work"+ * and "I lost the map of my work", and only the second one is true here.+ */+export function saveFailureMessage(delivery: SaveDelivery | undefined): string | null {+ if (!delivery) return null+ const tries = `${delivery.attempts} attempt${delivery.attempts === 1 ? '' : 's'}`+ if (delivery.kind === 'retrying')+ return (+ `Canvas changes are not being saved — ${tries} refused so far. Retrying. ` ++ 'Your terminals keep running either way.'+ )+ return (+ `Canvas changes are NOT being saved — ${tries} refused and nothing will retry on its own. ` ++ 'Cards opened since then will be gone on reload; your terminals keep running either way.'+ )+}diff --git a/src/renderer/styles.css b/src/renderer/styles.cssindex d1bd53f35..4577c7a4a 100644--- a/src/renderer/styles.css+++ b/src/renderer/styles.css@@ -3800,6 +3800,21 @@ body,background: rgba(255, 159, 10, 0.18);}+/* The whole-workspace save did not land. Red, not amber: the conflict bar asks a question, this+ one reports that the canvas on screen is not the canvas on disk. */+.save-failure-bar {+ background: rgba(255, 69, 58, 0.15);+ border-color: rgba(255, 69, 58, 0.45);+}++.save-failure-bar button {+ border-color: rgba(255, 69, 58, 0.6);+}++.save-failure-bar button:hover {+ background: rgba(255, 69, 58, 0.18);+}+/* Direct children only — the presence facepile's face buttons are nested inside .presence-facepileand must keep their own round, peer-colored styling, not the toolbar button chrome. */.controls-cluster > button {