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): refuse unsafe relay persistence and preserve deferred intent

review970240c16b04
diff --git a/CLAUDE.md b/CLAUDE.md
index 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`, which
uses `deliverCommand`: echo verification, bounded Ctrl-U repair, platform kill-line and overlong
line 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 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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6d21fdad5..174032d3c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -663,6 +663,10 @@ Desktop and Server save `attempted:true` before input. Never-attempted warm `--a
proceed after shell verification; attempted/legacy-unknown intent requires Run now. Only confirmed
submission 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 cost
memory). 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.tsx
index 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.ts
index 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 au
expect(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.ts
index 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.tsx
index 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
<button
className="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.ts
index 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 ne
expect(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.ts
index 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.ts
index 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 attempt
expect(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.ts
index 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: DeliveryIo
shellReady(manual: boolean): Promise<boolean>
killLine: string
@@ -30,17 +32,19 @@ export function createLaunchWriter(opts: {
}): Writer {
let attempted = false
let submitted = false
- let inFlight: Promise<DeliveryOutcome> | undefined
+ let inFlight: Promise<LaunchOutcome> | undefined
let disposed = false
opts.cleanup(() => { disposed = true })
return (command, manual) => {
if (submitted) return Promise.resolve('submitted') // stale UI/save; never paste twice
if (inFlight) return inFlight
if (disposed || (!manual && attempted)) return Promise.resolve('cancelled')
- attempted = true
inFlight = (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 const
return 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 intent
opts.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.ts
index 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)