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(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.mdindex 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 mobileomit that initial command rather than converting it to durable intent. A parked-project deferral before any inputretains 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 warmattach may automatically deliver never-attempted intent, preserving long-running `--after`graphs through project switches/park expiry. Attempted/legacy-unknown intent stays manual: itsclearing autosave may have been lost after Enter. Explicit Run now rechecks the foreground shell anddiff --git a/src/core/workspace-store.test.ts b/src/core/workspace-store.test.tsindex 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.tsindex 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.tsindex 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.tsindex 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 thediff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex 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.tsxindex 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?.awaitSetupGroupconst 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 istransient: 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 && (<spanclassName={`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.tsindex 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`