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.

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.tsx
index b77cca41e..5a5b038e6 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -144,6 +144,12 @@ import { markMobileLaunchSeen, shouldShowMobileLaunch } from '../lib/mobileLaunc
import 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 && (
<ConflictBar
addedCount={conflict.added}
diff --git a/src/renderer/components/SaveFailureBar.tsx b/src/renderer/components/SaveFailureBar.tsx
new file mode 100644
index 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.ts
index 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.ts
index 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).' + paused
const 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.css
index 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-facepile
and must keep their own round, peer-colored styling, not the toolbar button chrome. */
.controls-cluster > button {