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): refuse unsafe relay persistence and preserve deferred intent
review970240c16b04
diff --git a/CLAUDE.md b/CLAUDE.mdindex 0987bea10..31f3e39fc 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -2574,7 +2574,11 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile(4) Desktop automatic and manual launch delivery share `terminal/launch-command.ts`, whichuses `deliverCommand`: echo verification, bounded Ctrl-U repair, platform kill-line and overlongline refusal. The PTY-lifetime writer coalesces concurrent requests and remembers submission- across parked views. New intent has `attempted:false`; the writer awaits a workspace save of+ across parked views. Relay launch delivery, including Run now, is refused until a scoped durable+ claim API exists: a relay workspace load can be project-scoped, while save replaces the host+ index. Never use that load/save pair for a launch. 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 warmattach may automatically deliver never-attempted intent, preserving long-running `--after`graphs through project switches/park expiry. Attempted/legacy-unknown intent stays manual: itsdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 6d21fdad5..174032d3c 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -663,6 +663,10 @@ Desktop and Server save `attempted:true` before input. Never-attempted warm `--aproceed after shell verification; attempted/legacy-unknown intent requires Run now. Only confirmedsubmission clears intent. Desktop open replies use `createControlOpenBatch` for queued accounting;protect that contract and concurrent submission with behavior tests, never source-text pins.+Relay-owned launches (automatic and Run now) are refused until a scoped durable claim API exists.+Never round-trip a relay workspace load into save: the load can contain only one shared project,+while save replaces the entire host index. A pre-input parked-project deferral keeps intent+never-attempted; it must not poison the writer or trigger a retry timer.Held Desktop launches retain their attached transport even offscreen with tmux (large fan-outs costmemory). Server deferred delivery is one-shot: a failed probe/send needs explicit recovery.diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex b060eea42..a52eba429 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -1,5 +1,5 @@import { createControlOpenBatch } from '../lib/controlOpenBatch'-import { commitLaunchAttempt, registerLaunchCommit } from '../terminal/launch-attempt'+import { commitOwnedLaunchAttempt, registerLaunchCommit } from '../terminal/launch-attempt'import { launchCommand } from '../terminal/launch-command'import { useCallback, useEffect, useMemo, useRef, useState } from 'react'import { useShallow } from 'zustand/react/shallow'@@ -1952,6 +1952,12 @@ export function Canvas() {markDirty()return}+ if (outcome === 'deferred') {+ // No claim/input occurred while this project's canvas was parked. A later project+ // activation can retry; do not turn never-attempted intent into manual recovery.+ launchInFlight.current.delete(f.id)+ return+ }// The verified writer already exhausted its bounded echo repair. A failed launch// needs an explicit retry; unrelated hooks and remounts must never inject it later.setNodes((ns) => ns.map((n) => n.id === f.id && n.data.pendingLaunch@@ -2783,10 +2789,10 @@ export function Canvas() {// live source: update its ref synchronously before serializing, not after an async setNodes.useEffect(() => registerLaunchCommit(activeSession.api, async (nodeId, command, manual) => {const projectId = useProjects.getState().activeProjectId- if (!canCommitCanvas(nodesProjectIdRef.current, projectId)) return false+ if (!canCommitCanvas(nodesProjectIdRef.current, projectId)) return 'deferred'const node = nodesRef.current.find((n) => n.id === nodeId)- if (!node) return false- return commitLaunchAttempt({+ if (!node) return 'deferred'+ return commitOwnedLaunchAttempt(activeSession.api, api, {pending: node.data.pendingLaunch,command,manual,@@ -2799,18 +2805,7 @@ export function Canvas() {commitActiveToStore()},save: async () => {- if (activeSession.api === api) {- await api.workspace.save(useProjects.getState().toWorkspace())- } else {- // Relay projects are intentionally absent from the local workspace serializer.- // Save on the owning core, preserving its other projects and the node's full content.- const workspace = await activeSession.api.workspace.load()- const matches = workspace.projects.flatMap((p) => p.nodes).filter((n) => n.id === nodeId)- if (matches.length !== 1 || matches[0].pendingLaunch?.command !== command)- throw new Error('launch intent changed before persistence')- matches[0].pendingLaunch = { ...matches[0].pendingLaunch!, attempted: true, manualOnly: true }- await activeSession.api.workspace.save(workspace)- }+ await api.workspace.save(useProjects.getState().toWorkspace())}})}), [activeSession.api, api, commitActiveToStore, markDirty, setNodes])diff --git a/src/renderer/lib/pendingLaunch.test.ts b/src/renderer/lib/pendingLaunch.test.tsindex b318f9b29..6b4924cd7 100644--- a/src/renderer/lib/pendingLaunch.test.ts+++ b/src/renderer/lib/pendingLaunch.test.ts@@ -285,3 +285,10 @@ it('manual recovery does not promise that retrying an errored dependency will auexpect(tooltip).toContain('automatic retry is stopped')expect(tooltip).not.toContain('successful turn releases')})++it('a refused relay launch explains host recovery rather than promising a working retry', () => {+ const text = launchTooltip({ kind: 'failed', attempts: 1, at: 0 }, '', 'claude brief', undefined, true)+ expect(text).toContain('Open the host to run this command')+ expect(text).toContain('claude brief')+ expect(text).not.toContain('press ▶')+})diff --git a/src/renderer/lib/pendingLaunch.ts b/src/renderer/lib/pendingLaunch.tsindex e9f346ee3..2102f4804 100644--- a/src/renderer/lib/pendingLaunch.ts+++ b/src/renderer/lib/pendingLaunch.ts@@ -175,9 +175,11 @@ export function launchTooltip(delivery: LaunchDelivery | undefined,waitingOn: string,command: string,- erroredOn?: string+ erroredOn?: string,+ relay = false): string {const runs = `Runs:\n${command}`+ if (relay) return `Launch delivery from a relay tab is unavailable. Open the host to run this command.\n${runs}`if (delivery?.kind === 'failed')return ('Launch delivery is unconfirmed; automatic retry is stopped.\n' +diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsxindex 330184b49..cda41612c 100644--- a/src/renderer/nodes/TerminalNode.tsx+++ b/src/renderer/nodes/TerminalNode.tsx@@ -5533,13 +5533,14 @@ export function TerminalNode({className={`term-node__status term-node__status--queued nodrag${launchDelivery ? ' term-node__status--queued-warn' : ''}`}- title={launchTooltip(launchDelivery, pendingWaitingOn, pendingLaunch.command, pendingErroredOn)}+ title={launchTooltip(launchDelivery, pendingWaitingOn, pendingLaunch.command, pendingErroredOn, session.source === 'relay')}><span className="term-node__status-dot" />{launchDelivery ? '⚠ ' : ''}QUEUED<buttonclassName="term-node__queued-run"- title={pendingLaunch.manualOnly ? "Retry launch at a shell prompt" : "Run now without waiting"}+ disabled={session.source === 'relay'}+ title={session.source === 'relay' ? "Open the host to run this command" : pendingLaunch.manualOnly ? "Retry launch at a shell prompt" : "Run now without waiting"}onClick={(e) => {e.stopPropagation()// Disarm only on a delivery that actually landed. Dropping `pendingLaunch`diff --git a/src/renderer/terminal/launch-attempt.test.ts b/src/renderer/terminal/launch-attempt.test.tsindex 4933888ff..b7895675f 100644--- a/src/renderer/terminal/launch-attempt.test.ts+++ b/src/renderer/terminal/launch-attempt.test.ts@@ -1,6 +1,8 @@+import { scopeWorkspaceToProject } from '@shared/relay-workspace-scope'+import type { Workspace } from '@shared/types'import { expect, it, vi } from 'vitest'import type { PendingLaunch } from '@shared/types'-import { commitLaunch, commitLaunchAttempt, registerLaunchCommit } from './launch-attempt'+import { commitLaunch, commitLaunchAttempt, commitOwnedLaunchAttempt, registerLaunchCommit } from './launch-attempt'import { createLaunchWriter } from './launch-command'import { queueControlLaunch, launchesToFire } from '../lib/pendingLaunch'@@ -67,3 +69,38 @@ it('a saved --after launch survives park expiry, runs once on warm shell, and neexpect(await writer(ready.command, false)).toBe('submitted')expect(write.mock.calls).toEqual([[ready.command], ['\r']])})++it.each([false, true])('refuses scoped relay persistence (manual=%s) without replacing any host projects', async (manual) => {+ let host: Workspace = { version: 2, activeProjectId: 'shared', projects: ['shared', 'private-inline', 'other'].map((id) => ({+ id, name: id, color: '#fff', nodes: [], viewport: { x: 0, y: 0, zoom: 1 }+ })) }+ const before = JSON.stringify(host)+ const scoped = scopeWorkspaceToProject(host, 'shared')+ expect(scoped.projects.map((p) => p.id)).toEqual(['shared'])+ // This models the destructive whole-index save exposed by the existing relay API.+ const save = vi.fn(async () => { host = scoped })+ const update = vi.fn(), input = vi.fn()+ const relay = {}, local = {}+ const writer = createLaunchWriter({+ shellReady: async () => true, killLine: '\x15', cleanup: () => {},+ io: { write: input, onData: () => () => {} },+ claimAttempt: () => commitOwnedLaunchAttempt(relay, local, {+ pending: { command: 'claude brief', after: [], attempted: false },+ command: 'claude brief', manual, update, save+ })+ })+ expect(await writer('claude brief', manual)).toBe('cancelled')+ expect(save).not.toHaveBeenCalled()+ expect(update).not.toHaveBeenCalled()+ expect(input).not.toHaveBeenCalled()+ expect(JSON.stringify(host)).toBe(before)+})++it('acknowledges an owning local workspace only after its durable claim save', async () => {+ const owner = {}, update = vi.fn(), save = vi.fn(async () => {})+ expect(await commitOwnedLaunchAttempt(owner, owner, {+ pending: { after: [], command: 'cmd', attempted: false }, command: 'cmd', manual: false, update, save+ })).toBe(true)+ expect(update).toHaveBeenCalledWith({ after: [], command: 'cmd', attempted: true, manualOnly: true })+ expect(save).toHaveBeenCalledTimes(1)+})diff --git a/src/renderer/terminal/launch-attempt.ts b/src/renderer/terminal/launch-attempt.tsindex 322dc4e08..077765d38 100644--- a/src/renderer/terminal/launch-attempt.ts+++ b/src/renderer/terminal/launch-attempt.ts@@ -1,12 +1,13 @@import type { PendingLaunch } from '@shared/types'-type Commit = (id: string, command: string, manual: boolean) => Promise<boolean>+export type LaunchClaim = boolean | 'deferred'+type Commit = (id: string, command: string, manual: boolean) => Promise<LaunchClaim>const commits = new WeakMap<object, Commit>()export function registerLaunchCommit(scope: object, commit: Commit): () => void {commits.set(scope, commit)return () => { if (commits.get(scope) === commit) commits.delete(scope) }}-export function commitLaunch(scope: object, id: string, command: string, manual: boolean): Promise<boolean> {+export function commitLaunch(scope: object, id: string, command: string, manual: boolean): Promise<LaunchClaim> {return commits.get(scope)?.(id, command, manual) ?? Promise.resolve(false)}@@ -29,3 +30,11 @@ export async function commitLaunchAttempt(opts: {return false}}++/** A relay load may contain only one shared project; saving it would replace the host index.+ * Canvas mutation broadcasts have no durable acknowledgment. Refuse until a scoped durable+ * operation exists; this applies to explicit retry as well as automatic launch. */+export function commitOwnedLaunchAttempt(owner: object, local: object,+ opts: Parameters<typeof commitLaunchAttempt>[0]): Promise<boolean> {+ return owner === local ? commitLaunchAttempt(opts) : Promise.resolve(false)+}diff --git a/src/renderer/terminal/launch-command.test.ts b/src/renderer/terminal/launch-command.test.tsindex e57e7a3ca..e3dc98aee 100644--- a/src/renderer/terminal/launch-command.test.ts+++ b/src/renderer/terminal/launch-command.test.ts@@ -212,3 +212,29 @@ it.each([true, undefined])('a retained initialCommand alias cannot reset attemptexpect(whenReady).not.toHaveBeenCalled()expect(write).not.toHaveBeenCalled()})++it('a pre-input deferred claim preserves UI intent and the same parked writer can later deliver once', async () => {+ let ready!: () => void+ let echo!: (text: string) => void+ const write = vi.fn(), failure = vi.fn()+ const claimAttempt = vi.fn<() => Promise<boolean | 'deferred'>>()+ .mockResolvedValueOnce('deferred').mockResolvedValue(true)+ const writer = createLaunchWriter({ claimAttempt, shellReady: async () => true,+ killLine: KILL_LINE, cleanup: () => {},+ io: { write, onData: (cb) => { echo = cb; return () => {} } } })+ const state: { initialCommand?: string; pendingLaunch?: PendingLaunch } = { initialCommand: 'claude brief' }+ deliverInitialLaunch('claude brief', { write: writer, whenReady: (run) => { ready = run },+ update: (patch) => Object.assign(state, patch), onFailure: failure })+ ready()+ await tick()+ expect(state).toMatchObject({ initialCommand: 'claude brief', pendingLaunch: { attempted: false } })+ expect(write).not.toHaveBeenCalled()+ expect(failure).not.toHaveBeenCalled()+ const resumed = writer('claude brief', false)+ await tick()+ expect(write.mock.calls).toEqual([['claude brief']])+ echo('claude brief')+ expect(await resumed).toBe('submitted')+ expect(await writer('claude brief', false)).toBe('submitted')+ expect(write.mock.calls).toEqual([['claude brief'], ['\r']])+})diff --git a/src/renderer/terminal/launch-command.ts b/src/renderer/terminal/launch-command.tsindex 2110c8b65..e5e99cd20 100644--- a/src/renderer/terminal/launch-command.ts+++ b/src/renderer/terminal/launch-command.ts@@ -1,10 +1,12 @@+import type { LaunchClaim } from './launch-attempt'import type { PendingLaunch } from '@shared/types'import { deliverCommand, type DeliveryIo, type DeliveryOutcome } from './command-delivery'// A writer belongs to the PTY lifetime (including a parked view), not a Canvas render.// A durable write-ahead claim distinguishes a never-attempted warm launch from an uncertain// earlier submission whose clearing autosave may have been lost.-type Writer = (command: string, manual: boolean) => Promise<DeliveryOutcome>+type LaunchOutcome = DeliveryOutcome | 'deferred'+type Writer = (command: string, manual: boolean) => Promise<LaunchOutcome>const defaultScope = {}const scopedWriters = new WeakMap<object, Map<string, Writer>>()function writersFor(scope: object): Map<string, Writer> {@@ -17,12 +19,12 @@ export function registerLaunchWriter(id: string, writer: Writer, scope: object =writers.set(id, writer)return () => { if (writers.get(id) === writer) writers.delete(id) }}-export function launchCommand(id: string, command: string, manual = false, scope: object = defaultScope): Promise<DeliveryOutcome> {+export function launchCommand(id: string, command: string, manual = false, scope: object = defaultScope): Promise<LaunchOutcome> {return writersFor(scope).get(id)?.(command, manual) ?? Promise.resolve('cancelled')}export function createLaunchWriter(opts: {- claimAttempt(manual: boolean, command: string): Promise<boolean>+ claimAttempt(manual: boolean, command: string): Promise<LaunchClaim>io: DeliveryIoshellReady(manual: boolean): Promise<boolean>killLine: string@@ -30,17 +32,19 @@ export function createLaunchWriter(opts: {}): Writer {let attempted = falselet submitted = false- let inFlight: Promise<DeliveryOutcome> | undefined+ let inFlight: Promise<LaunchOutcome> | undefinedlet disposed = falseopts.cleanup(() => { disposed = true })return (command, manual) => {if (submitted) return Promise.resolve('submitted') // stale UI/save; never paste twiceif (inFlight) return inFlightif (disposed || (!manual && attempted)) return Promise.resolve('cancelled')- attempted = trueinFlight = (async () => {if (!(await opts.shellReady(manual)) || disposed) return 'cancelled' as const- if (!(await opts.claimAttempt(manual, command)) || disposed) return 'cancelled' as const+ const claim = await opts.claimAttempt(manual, command)+ if (claim === 'deferred' && !disposed) return 'deferred' as const+ if (!claim || disposed) return 'cancelled' as const+ attempted = true// Saving can take a remote round trip. Recheck after the barrier, before any input.if (!(await opts.shellReady(manual)) || disposed) return 'cancelled' as constreturn new Promise<DeliveryOutcome>((resolve) => {@@ -83,6 +87,7 @@ export function deliverInitialLaunch(command: string, opts: {opts.update({ pendingLaunch })opts.whenReady(() => {void opts.write(command, false).then((outcome) => {+ if (outcome === 'deferred') return // no input/claim; retain never-attempted intentopts.update({ initialCommand: undefined,pendingLaunch: outcome === 'submitted' ? undefined : { ...pendingLaunch, attempted: true, manualOnly: true } })if (outcome !== 'submitted') opts.onFailure(outcome)diff --git a/test/acceptance/open-project-chain.test.ts b/test/acceptance/open-project-chain.test.tsindex d5c19615e..0422585d1 100644--- a/test/acceptance/open-project-chain.test.ts+++ b/test/acceptance/open-project-chain.test.ts@@ -142,7 +142,7 @@ describe('the open-project → targeted-open chain', () => {.getState().getProject(r1.project.id)?.nodes.find((n) => n.id === 'term-target1')- expect(stored?.pendingLaunch).toEqual({ after: [], command: 'claude "work in repoA"' })+ expect(stored?.pendingLaunch).toEqual({ after: [], attempted: false, command: 'claude "work in repoA"' })// Still no travel.expect(useProjects.getState().activeProjectId).toBe(activeBefore)