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(launch): the launch write-ahead save no longer waits on SSH; no QUEUED chip on a first open

review6a446b47d792
diff --git a/CLAUDE.md b/CLAUDE.md
index d964d18eb..e709d4a0a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2736,7 +2736,13 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
omit that initial command rather than converting it to durable intent. A parked-project deferral before any input
retains never-attempted intent and can proceed on activation without a retry timer.
New intent has `attempted:false`; the writer awaits a workspace save of
- `attempted:true, manualOnly:true` before input, then rechecks the shell after that save. A warm
+ `attempted:true, manualOnly:true` before input, then rechecks the shell after that save. That
+ save is **`localOnly`** (`WorkspaceStore.save`): durable in this machine's index, with no SSH
+ read/reconcile/mirror — a changed entry is marked `unmirrored` and the next ordinary save pushes
+ it. Awaiting the mirror put two SSH round trips in front of every new agent on an SSH project.
+ A node's own first-open delivery (live `initialCommand`, no deps, no failure record) shows NO
+ QUEUED chip: its `pendingLaunch` is only the write-ahead record, and it carries `manualOnly`
+ from the claim until Enter lands, which painted "⚠ QUEUED" on every freshly opened agent. A warm
attach may automatically deliver never-attempted intent, preserving long-running `--after`
graphs through project switches/park expiry. Attempted/legacy-unknown intent stays manual: its
clearing autosave may have been lost after Enter. Explicit Run now rechecks the foreground shell and
diff --git a/src/core/workspace-store.test.ts b/src/core/workspace-store.test.ts
index 02aa55621..1134d4b2a 100644
--- a/src/core/workspace-store.test.ts
+++ b/src/core/workspace-store.test.ts
@@ -2145,3 +2145,49 @@ describe('ssh mirror: an optimistically-acked write that never lands must not re
})
}
})
+
+describe('localOnly save (the launch write-ahead barrier)', () => {
+ const sshConn = { server: { host: 'h', user: 'u' } as any, remoteCwd: '~/app' }
+ const makeIo = () => {
+ const remote: Record<string, string> = {}
+ const calls: string[] = []
+ const io = {
+ read: async (id: string) => (calls.push(`read:${id}`),
+ remote[id] != null ? { status: 'ok' as const, content: remote[id] } : { status: 'absent' as const }),
+ write: async (id: string, _s: any, c: string) => (calls.push(`write:${id}`), (remote[id] = c), true)
+ }
+ return { io, remote, calls }
+ }
+ const withNodes = (ids: string[]) => project({
+ id: 'ps', ssh: sshConn, cwd: undefined,
+ nodes: ids.map((id) => ({ id, kind: 'terminal' as const, position: { x: 0, y: 0 }, size: { width: 1, height: 1 }, title: 't', color: '#fff', group: null }))
+ })
+
+ it('touches no ssh host, persists the cache to the local index, and the next ordinary save mirrors it', async () => {
+ const { io, remote, calls } = makeIo()
+ const store = new WorkspaceStore(io)
+ await store.save(ws([withNodes(['term-1'])])) // reconciled + mirrored
+ calls.length = 0
+
+ await store.save(ws([withNodes(['term-1', 'term-2'])]), { localOnly: true })
+ expect(calls).toEqual([])
+ const index = JSON.parse(await fs.readFile(path.join(userData, 'workspace.json'), 'utf-8'))
+ const entry = index.entries.find((e: { id: string }) => e.id === 'ps')
+ expect(entry.cache.nodes.map((n: { id: string }) => n.id)).toEqual(['term-1', 'term-2'])
+ expect(JSON.parse(remote['ps']).nodes.map((n: { id: string }) => n.id)).toEqual(['term-1'])
+
+ // Unchanged content — only the owed mirror can make this save write.
+ await store.save(ws([withNodes(['term-1', 'term-2'])]))
+ expect(calls.some((c) => c === 'write:ps')).toBe(true)
+ expect(JSON.parse(remote['ps']).nodes.map((n: { id: string }) => n.id)).toEqual(['term-1', 'term-2'])
+ })
+
+ it('never blind-writes an unreconciled entry: it is left for the next ordinary save to read first', async () => {
+ const { io, calls } = makeIo()
+ const store = new WorkspaceStore(io)
+ await store.save(ws([withNodes(['term-1'])]), { localOnly: true })
+ expect(calls).toEqual([])
+ await store.save(ws([withNodes(['term-1'])]))
+ expect(calls[0]).toBe('read:ps')
+ })
+})
diff --git a/src/core/workspace-store.ts b/src/core/workspace-store.ts
index 133fcc9e6..5b86ef471 100644
--- a/src/core/workspace-store.ts
+++ b/src/core/workspace-store.ts
@@ -6,7 +6,7 @@ import { IPC } from '../shared/ipc'
import { platform } from './platform'
import {
DEFAULT_PROJECT_ID, EMPTY_WORKSPACE,
- type BridgeLink, type CanvasNodeState, type KanbanColumn, type KanbanLabel, type Project, type Workspace,
+ type BridgeLink, type CanvasNodeState, type KanbanColumn, type KanbanLabel, type Project, type Workspace, type WorkspaceSaveOptions,
type WorkspaceV1
} from '../shared/types'
import {
@@ -206,7 +206,8 @@ export class WorkspaceStore {
registerIpc(): void {
platform().handle(IPC.workspaceLoad, () => this.load())
- platform().handle(IPC.workspaceSave, (workspace: Workspace) => this.save(workspace))
+ platform().handle(IPC.workspaceSave, (workspace: Workspace, opts?: WorkspaceSaveOptions) =>
+ this.save(workspace, { localOnly: opts?.localOnly === true }))
platform().handle(IPC.workspaceProbeFolder, (folder: string) => this.probeFolder(folder))
platform().handle(IPC.workspaceProjectFileState, (cwd: unknown) =>
typeof cwd === 'string' && cwd ? this.projectFileState(cwd) : 'unreadable')
@@ -933,13 +934,22 @@ export class WorkspaceStore {
* projects went blank after tab switching" wipe. */
private saveChain: Promise<unknown> = Promise.resolve()
- save(workspace: Workspace): Promise<void> {
- const run = this.saveChain.then(() => this.saveNow(workspace))
+ /**
+ * `localOnly` makes the save durable on THIS machine only: every local file and the index (which
+ * carries each SSH project's cache) are written, but no SSH project is read, reconciled or
+ * mirrored — a changed, already-reconciled entry is marked `unmirrored` instead, so the next
+ * ordinary save pushes it. It exists for the launch write-ahead barrier (`commitLaunchAttempt`):
+ * that save must be on disk before a command is typed, and waiting on two SSH round trips per
+ * save made every new agent node on an SSH project sit on QUEUED for seconds. It still runs on
+ * the FIFO chain, so ordering against every other save is unchanged.
+ */
+ save(workspace: Workspace, opts: WorkspaceSaveOptions = {}): Promise<void> {
+ const run = this.saveChain.then(() => this.saveNow(workspace, opts.localOnly === true))
this.saveChain = run.catch(() => {})
return run
}
- private async saveNow(workspace: Workspace): Promise<void> {
+ private async saveNow(workspace: Workspace, localOnly = false): Promise<void> {
if (!workspace.projects.length && !this.index) {
// A store that never read the index may not replace a populated one with "no projects":
// that is the boot-save wipe — load() failed transiently, the renderer hydrated zero
@@ -1070,6 +1080,12 @@ export class WorkspaceStore {
// Without that record the re-read would hand every just-deleted node straight back on the very
// write that was supposed to remove it, and no node on an ssh project could ever be closed.
this.recordLocalDeletions(e.id, previousCache?.nodes, e.cache.nodes)
+ if (localOnly) {
+ // No network. An unreconciled entry is left for the next ordinary save to LOOK first (the
+ // never-blind-write rule is untouched); a reconciled one that changed now owes its mirror.
+ if (changedSinceLoad && this.reconciled.has(e.id)) this.unmirrored.add(e.id)
+ continue
+ }
if (!this.reconciled.has(e.id)) {
// Never blind-write a remote file we have not read yet: the first mirror of a fresh or
// re-added project must LOOK first — an existing lineage on the server may win (adopted,
diff --git a/src/preload/index.ts b/src/preload/index.ts
index cd48f2837..e81e246bc 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -17,6 +17,7 @@ import type {
UpdateInfo,
UpdateProgress,
Workspace,
+ WorkspaceSaveOptions,
WorkspaceMigrationKind
} from '../shared/types'
import type { ClientId, PeerDiff, PeerIdentity, PeerState } from '../shared/presence'
@@ -143,7 +144,7 @@ const api: NodeTerminalApi = {
},
workspace: {
load: () => ipcRenderer.invoke(IPC.workspaceLoad),
- save: (workspace: Workspace) => ipcRenderer.invoke(IPC.workspaceSave, workspace),
+ save: (workspace: Workspace, opts?: WorkspaceSaveOptions) => ipcRenderer.invoke(IPC.workspaceSave, workspace, opts),
probeFolder: (folder: string) => ipcRenderer.invoke(IPC.workspaceProbeFolder, folder),
projectFileState: (folder: string) => ipcRenderer.invoke(IPC.workspaceProjectFileState, folder),
onMigrated: (cb: (kind: WorkspaceMigrationKind) => void) => {
diff --git a/src/renderer/bridge/ws-bridge.ts b/src/renderer/bridge/ws-bridge.ts
index 5f6781cee..0124f92d1 100644
--- a/src/renderer/bridge/ws-bridge.ts
+++ b/src/renderer/bridge/ws-bridge.ts
@@ -61,7 +61,8 @@ import {
type TmuxStatus,
type TranscriptLine,
type Workspace,
- type WorkspaceApi
+ type WorkspaceApi,
+ type WorkspaceSaveOptions
} from '../../shared/types'
import type { PeerIdentity } from '../../shared/presence'
import type { PaneOwner } from '../../shared/agents/pane-owner-predicate'
@@ -305,7 +306,7 @@ export function buildRealApi(
const workspace: WorkspaceApi = {
load: () => client.request(IPC.workspaceLoad) as Promise<Workspace>,
- save: (ws: Workspace) => client.request(IPC.workspaceSave, ws) as Promise<void>,
+ save: (ws: Workspace, opts?: WorkspaceSaveOptions) => client.request(IPC.workspaceSave, ws, opts) as Promise<void>,
// REAL: WorkspaceStore (core) registers IPC.workspaceProbeFolder, so the server serves it.
// Stubbing it to `null` meant "Open folder…" on a repo that already carries a committed
// .nodeterm/project.json concluded there was no project there, created an EMPTY one, and the
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 05bcdc1e2..9caa2580a 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -2871,8 +2871,11 @@ export function Canvas() {
markDirty()
commitActiveToStore()
},
+ // Local durability is the whole barrier: a crash restarts from THIS machine's index, and the
+ // `markDirty` above already owes the SSH mirror to the next ordinary save. Awaiting the
+ // mirror here held every new agent on an SSH project on QUEUED for its round trips.
save: async () => {
- await api.workspace.save(useProjects.getState().toWorkspace())
+ await api.workspace.save(useProjects.getState().toWorkspace(), { localOnly: true })
}
})
}), [activeSession.api, api, commitActiveToStore, markDirty, setNodes])
diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsx
index 0387a59bc..bc01b59c3 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -1875,6 +1875,16 @@ export function TerminalNode({
const observedLaunchDelivery = useLaunchDelivery((s) => s.byId[id])
const launchDelivery = observedLaunchDelivery ?? (pendingLaunch?.manualOnly
? { kind: 'failed' as const, attempts: 1, at: 0 } : undefined)
+ // A node's own first-open launch is in flight: the live `initialCommand` alias is still set
+ // (it is cleared on every outcome) and nothing holds it. Its `pendingLaunch` is only the durable
+ // write-ahead record — and it carries `manualOnly` from the claim until Enter lands — so showing
+ // the chip here painted "⚠ QUEUED" on EVERY freshly opened agent for the length of its delivery.
+ // A real hold (deps, setup script) or a reported failure/stall still shows.
+ const firstOpenInFlight =
+ !!data.initialCommand &&
+ !observedLaunchDelivery &&
+ !(pendingLaunch?.after?.length) &&
+ !pendingLaunch?.awaitSetupGroup
const pendingWaitingOn = [
...(pendingLaunch?.after ?? []).map(
(depId) => ((getNode(depId) as CanvasNode | undefined)?.data.title as string) || depId
@@ -5595,7 +5605,7 @@ export function TerminalNode({
that simply failed to start — and it carries the manual escape, because agent state is
transient: after an app restart nothing will ever report `done` again, so without a
"run now" an armed node left over from before the restart would be a dead end. */}
- {pendingLaunch && (
+ {pendingLaunch && !firstOpenInFlight && (
<span
className={`term-node__status term-node__status--queued nodrag${
launchDelivery ? ' term-node__status--queued-warn' : ''
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 77a8c18f6..1258110c4 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1063,9 +1063,16 @@ export interface PtyApi {
export type WorkspaceMigrationKind = 'v2' | 'exec'
+export interface WorkspaceSaveOptions {
+ localOnly?: boolean
+}
+
export interface WorkspaceApi {
load(): Promise<Workspace>
- save(workspace: Workspace): Promise<void>
+ /** `localOnly`: return once this machine's disk holds the save, WITHOUT the SSH mirror
+ * round trips (the mirror is owed and rides the next ordinary save). For a write-ahead barrier
+ * that must be durable here but must not wait on a remote host — see WorkspaceStore.save. */
+ save(workspace: Workspace, opts?: WorkspaceSaveOptions): Promise<void>
/** Reads <folder>/.nodeterm/project.json and returns the assembled Project (cwd resolved), or null. */
probeFolder(folder: string): Promise<Project | null>
/** Whether <folder>/.nodeterm/project.json is `present`, definitely `absent`, or `unreadable`