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): --run-now reply keeps the cold-open clauses that are still true (#925)

review37deb2e9eae6
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 6caca75b1..c935e31ed 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -586,7 +586,8 @@ import {
planRunVerb,
savePendingAnywhere,
startHeadless,
- type HeadlessStartOutcome
+ unhidesForHeadlessStart,
+ type HeadlessStartBatch
} from '../lib/headlessRun'
import {
SETTINGS_VERB_KEY_LIST,
@@ -6234,8 +6235,8 @@ export function Canvas() {
// assignment, for the same reason: the agent-control effect mounts ONCE.
const headlessInFlightRef = useRef(new Set<string>())
const startNodesHeadlessRef = useRef<
- (project: Project, nodes: CanvasNodeState[]) => Promise<HeadlessStartOutcome[]>
- >(async () => [])
+ (project: Project, nodes: CanvasNodeState[]) => Promise<HeadlessStartBatch>
+ >(async () => ({ outcomes: [], unhidden: false }))
const runQueuedNodeRef = useRef<(project: Project, nodeId: string) => Promise<ControlReply>>(
async () => ({ ok: false, error: 'run: canvas not ready' })
)
@@ -14342,19 +14343,14 @@ export function Canvas() {
inFlight: headlessInFlightRef.current
}
// A closed project gets its tab back, never the focus (#925 spec §2.5): unhide BEFORE the
- // claim's disk write, so the same write persists it. Not while no project is active (the
- // welcome screen): un-closing one there would flip `hasProjects` and render a canvas with no
- // active project. The session still starts; the project stays in Recently closed. Nor for
- // an SSH project: `startHeadless` refuses every one of its nodes (`remote-unsupported`)
- // before any claim, so nothing would start and no claim write would persist the tab.
+ // claim's disk write, so the same write persists it. When it does NOT (the welcome screen,
+ // an SSH project) is `unhidesForHeadlessStart`'s to say; the answer rides back in the batch,
+ // because the reply's "reopen it from the welcome screen" hint stays true unless it acted.
const projectsNow = useProjects.getState()
- if (
- projectsNow.getProject(project.id)?.closed &&
- !project.ssh &&
- projectsNow.activeProjectId !== ''
- ) {
- projectsNow.unhideProject(project.id)
- }
+ const storedProject = projectsNow.getProject(project.id)
+ const unhidden =
+ !!storedProject && unhidesForHeadlessStart(storedProject, projectsNow.activeProjectId)
+ if (unhidden) projectsNow.unhideProject(project.id)
const outcomes = await Promise.all(nodes.map((node) => startHeadless(deps, { project, node })))
const started = outcomes.filter((o) => o.started).map((o) => o.id)
if (started.length) {
@@ -14365,7 +14361,7 @@ export function Canvas() {
action: { label: 'Go there', run: () => travelToNodeRef.current(started[0]) }
})
}
- return outcomes
+ return { outcomes, unhidden }
}
runQueuedNodeRef.current = async (project, nodeId) => {
@@ -14433,7 +14429,9 @@ export function Canvas() {
// No await between the plan above and this call: the claim lands in the same tick, while
// the project is still off screen, which is what makes savePendingAnywhere's store+disk
// branch (not its non-durable live one) the one that records it.
- const [o] = await startNodesHeadlessRef.current(project, [stored!])
+ const {
+ outcomes: [o]
+ } = await startNodesHeadlessRef.current(project, [stored!])
return o.started ? one(true) : one(false, o.reason)
}
}
diff --git a/src/renderer/lib/headlessRun.test.ts b/src/renderer/lib/headlessRun.test.ts
index a5f47e568..d7fa2cc1c 100644
--- a/src/renderer/lib/headlessRun.test.ts
+++ b/src/renderer/lib/headlessRun.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it, vi } from 'vitest'
-import type { CanvasNodeState, PendingLaunch } from '@shared/types'
+import type { CanvasNodeState, PendingLaunch, Project } from '@shared/types'
import type { HeadlessLaunchResult } from '@shared/headless-launch'
import { coldOpenMessage } from './coldOpen'
import {
@@ -10,6 +10,7 @@ import {
planRunVerb,
savePendingAnywhere,
startHeadless,
+ unhidesForHeadlessStart,
type HeadlessStartDeps,
type PendingStoreEnv
} from './headlessRun'
@@ -18,6 +19,11 @@ const pending: PendingLaunch = { after: [], command: "claude 'go'", attempted: f
const node = (over: Partial<CanvasNodeState> = {}): CanvasNodeState =>
({ id: 'n1', kind: 'terminal', agentId: 'claude', pendingLaunch: pending, ...over }) as CanvasNodeState
const project = { id: 'p2', cwd: '/repo' }
+const sshProject = {
+ id: 'p3',
+ cwd: '/repo',
+ ssh: { server: { host: 'example.com' }, remoteCwd: '/srv/repo' } as unknown as NonNullable<Project['ssh']>
+}
function deps(result: HeadlessLaunchResult | (() => Promise<HeadlessLaunchResult>), save = true) {
const saved: Array<PendingLaunch | undefined> = []
@@ -240,23 +246,114 @@ describe('savePendingAnywhere', () => {
})
})
+describe('unhidesForHeadlessStart', () => {
+ it('restores only a closed, local project while some project is active', () => {
+ expect(unhidesForHeadlessStart({ closed: true }, 'p1')).toBe(true)
+ expect(unhidesForHeadlessStart({ closed: false }, 'p1')).toBe(false)
+ expect(unhidesForHeadlessStart({}, 'p1')).toBe(false)
+ // Every node of an SSH project is refused `remote-unsupported`, so its tab would be restored for nothing.
+ expect(unhidesForHeadlessStart({ closed: true, ssh: sshProject.ssh }, 'p1')).toBe(false)
+ // The welcome screen: un-closing a project there would render a canvas with no active project.
+ expect(unhidesForHeadlessStart({ closed: true }, '')).toBe(false)
+ })
+})
+
describe('mergeRunNow + notice', () => {
- it('rewrites the cold-open reply: no "starts when viewed", no welcome-screen hint, started ids listed', () => {
- const base = {
- ok: true as const,
- message: coldOpenMessage(2, 'claude', 'Repo', ['a', 'b'], { closed: true }),
- result: { ids: ['a', 'b'], id: 'a', projectId: 'p2', queued: true, queuedIds: ['a', 'b'] }
- }
- const r = mergeRunNow(base, [
- { id: 'a', started: true },
- { id: 'b', started: false, reason: 'no-shell' }
- ])
- expect(r.message).not.toMatch(/starts when that project is next viewed/)
- expect(r.message).not.toMatch(/welcome screen/)
+ const closedBase = (ids: string[]) => ({
+ ok: true as const,
+ message: coldOpenMessage(ids.length, 'claude', 'Repo', ids, { closed: true }),
+ result: { ids, id: ids[0], projectId: 'p2', queued: true, queuedIds: ids } as Record<string, unknown>
+ })
+ const STARTS_ON_VIEW = /queued; starts when that project is next viewed/
+ const WELCOME = /that project is closed — reopen it from the welcome screen/
+
+ it('some started and the project was unhidden: both clauses go, started ids listed', () => {
+ const r = mergeRunNow(closedBase(['a', 'b']), {
+ outcomes: [
+ { id: 'a', started: true },
+ { id: 'b', started: false, reason: 'no-shell' }
+ ],
+ unhidden: true
+ })
+ expect(r.message).not.toMatch(STARTS_ON_VIEW)
+ expect(r.message).not.toMatch(WELCOME)
expect(r.message).toMatch(/started: a/)
expect(r.message).toMatch(/queued \(no-shell\): b/)
- expect(r.result).toMatchObject({ started: true, startedIds: ['a'], queued: true, queuedIds: ['b'], reason: 'no-shell' })
+ expect(r.result).toMatchObject({
+ started: true,
+ startedIds: ['a'],
+ queued: true,
+ queuedIds: ['b'],
+ reason: 'no-shell',
+ reasons: { b: 'no-shell' }
+ })
+ })
+
+ it('nothing started and every launch was left as it was: both clauses are kept (they are still true)', () => {
+ // The SSH owner that stays closed: startHeadless refused each node before any claim.
+ const r = mergeRunNow(closedBase(['a', 'b']), {
+ outcomes: [
+ { id: 'a', started: false, reason: 'remote-unsupported' },
+ { id: 'b', started: false, reason: 'remote-unsupported' }
+ ],
+ unhidden: false
+ })
+ expect(r.message).toMatch(STARTS_ON_VIEW)
+ expect(r.message).toMatch(WELCOME)
+ expect(r.message).toMatch(/queued \(remote-unsupported\): a, b/)
+ expect(r.result).toMatchObject({ started: false, startedIds: [], queued: true, queuedIds: ['a', 'b'] })
+ // not-persistent and claim-not-saved hand the original launch back, so it still starts on view.
+ const back = mergeRunNow(closedBase(['a', 'b']), {
+ outcomes: [
+ { id: 'a', started: false, reason: 'not-persistent' },
+ { id: 'b', started: false, reason: 'claim-not-saved' }
+ ],
+ unhidden: false
+ })
+ expect(back.message).toMatch(STARTS_ON_VIEW)
+ expect(back.message).toMatch(WELCOME)
})
+
+ it('nothing started but a claimed launch failed: that node waits for Run now, so "starts when viewed" goes', () => {
+ const r = mergeRunNow(closedBase(['a']), {
+ outcomes: [{ id: 'a', started: false, reason: 'no-shell' }],
+ unhidden: true
+ })
+ expect(r.message).not.toMatch(STARTS_ON_VIEW)
+ // The tab WAS restored, so the welcome-screen hint is false too.
+ expect(r.message).not.toMatch(WELCOME)
+ expect(r.message).toMatch(/queued \(no-shell\): a/)
+ })
+
+ it('the project stayed closed (welcome screen): the closed hint is kept even though a node started', () => {
+ const r = mergeRunNow(closedBase(['a']), { outcomes: [{ id: 'a', started: true }], unhidden: false })
+ expect(r.message).not.toMatch(STARTS_ON_VIEW)
+ expect(r.message).toMatch(WELCOME)
+ expect(r.message).toMatch(/started: a/)
+ expect(r.result).toMatchObject({ started: true, startedIds: ['a'], queued: false, queuedIds: [], reasons: {} })
+ expect('reason' in r.result).toBe(false)
+ })
+
+ it('mixed reasons: every id is reported with its own reason, grouped; `reason` stays the first', () => {
+ const r = mergeRunNow(closedBase(['a', 'b', 'c', 'd']), {
+ outcomes: [
+ { id: 'a', started: true },
+ { id: 'b', started: false, reason: 'no-shell' },
+ { id: 'c', started: false, reason: 'line-too-long' },
+ { id: 'd', started: false, reason: 'no-shell' }
+ ],
+ unhidden: true
+ })
+ expect(r.message).toMatch(/started: a/)
+ expect(r.message).toMatch(/queued \(no-shell\): b, d/)
+ expect(r.message).toMatch(/queued \(line-too-long\): c/)
+ expect(r.result).toMatchObject({
+ queuedIds: ['b', 'c', 'd'],
+ reason: 'no-shell',
+ reasons: { b: 'no-shell', c: 'line-too-long', d: 'no-shell' }
+ })
+ })
+
it('names the project and the count', () => {
expect(headlessStartNoticeText('Repo', 1)).toBe('An agent started a session in "Repo". That project is not on screen.')
expect(headlessStartNoticeText('Repo', 3)).toBe('An agent started 3 sessions in "Repo". That project is not on screen.')
diff --git a/src/renderer/lib/headlessRun.ts b/src/renderer/lib/headlessRun.ts
index 997571d35..b3b15be1e 100644
--- a/src/renderer/lib/headlessRun.ts
+++ b/src/renderer/lib/headlessRun.ts
@@ -69,18 +69,40 @@ export function headlessPtyOptions(
}
}
+export type HeadlessStartReason =
+ | HeadlessLaunchFailure
+ | 'already-starting'
+ | 'claim-not-saved'
+ | 'nothing-queued'
+ | 'remote-unsupported'
+
export type HeadlessStartOutcome =
| { id: string; started: true }
- | {
- id: string
- started: false
- reason:
- | HeadlessLaunchFailure
- | 'already-starting'
- | 'claim-not-saved'
- | 'nothing-queued'
- | 'remote-unsupported'
- }
+ | { id: string; started: false; reason: HeadlessStartReason }
+
+/** One `startNodesHeadless` call: each node's outcome, plus whether the call restored the
+ * project's tab (`unhidesForHeadlessStart`). The reply needs the second fact: only a restored tab
+ * makes the cold open's "reopen it from the welcome screen" hint false. */
+export interface HeadlessStartBatch {
+ outcomes: HeadlessStartOutcome[]
+ unhidden: boolean
+}
+
+/**
+ * Whether a headless start restores a CLOSED project's tab (#925 spec §2.5): the tab comes back,
+ * never the focus. The one definition; Canvas acts on it and reports it back in the batch.
+ * - Not while no project is active (the welcome screen): un-closing one there flips `hasProjects`
+ * and renders a canvas with no active project. The session still starts; the project stays in
+ * Recently closed.
+ * - Not for an SSH project: `startHeadless` refuses every one of its nodes (`remote-unsupported`)
+ * before any claim, so nothing would start and no claim write would persist the tab.
+ */
+export function unhidesForHeadlessStart(
+ project: { closed?: boolean; ssh?: Project['ssh'] },
+ activeProjectId: string
+): boolean {
+ return !!project.closed && !project.ssh && activeProjectId !== ''
+}
export interface HeadlessStartDeps {
launch(req: { ptyOptions: PtyCreateOptions; command: string }): Promise<HeadlessLaunchResult>
@@ -172,21 +194,50 @@ export async function savePendingAnywhere(
const STARTS_ON_VIEW = / — queued; starts when that project is next viewed/
const CLOSED_HINT = / \(that project is closed — reopen it from the welcome screen\)/
-/** Turn a cold-open reply (`coldOpenMessage` + result) into the `--run-now` reply. */
+/** Failures after which the node's launch is exactly what the cold open left: never claimed
+ * (`remote-unsupported`), or handed back unchanged (`not-persistent`, `claim-not-saved`). Such a
+ * launch still starts when its project is next viewed. Every other failure keeps the write-ahead
+ * claim (manualOnly), so that node waits for Run now instead. */
+const LAUNCH_LEFT_AS_IS: ReadonlySet<HeadlessStartReason> = new Set([
+ 'remote-unsupported',
+ 'not-persistent',
+ 'claim-not-saved'
+])
+
+/**
+ * Turn a cold-open reply (`coldOpenMessage` + result) into the `--run-now` reply. Each clause of
+ * the cold-open sentence is dropped only when this batch made it false:
+ * - "queued; starts when that project is next viewed" goes once a node started, or once a node's
+ * launch now waits for Run now. It stays when every launch was left as it was.
+ * - The closed-project hint goes only when the tab was actually restored (`batch.unhidden`).
+ * Every queued id is reported with its own reason (`reasons`, grouped in the message); `reason`
+ * is the first one, kept for callers that read a single field.
+ */
export function mergeRunNow<T extends { ok: true; message: string; result: Record<string, unknown> }>(
base: T,
- outcomes: HeadlessStartOutcome[]
+ batch: HeadlessStartBatch
): T {
- const startedIds = outcomes.filter((o) => o.started).map((o) => o.id)
- const failed = outcomes.filter(
+ const startedIds = batch.outcomes.filter((o) => o.started).map((o) => o.id)
+ const failed = batch.outcomes.filter(
(o): o is Extract<HeadlessStartOutcome, { started: false }> => !o.started
)
const queuedIds = failed.map((o) => o.id)
const reason = failed[0]?.reason
+ const reasons: Record<string, HeadlessStartReason> = {}
+ const byReason = new Map<HeadlessStartReason, string[]>()
+ for (const o of failed) {
+ reasons[o.id] = o.reason
+ byReason.set(o.reason, [...(byReason.get(o.reason) ?? []), o.id])
+ }
+ const startsOnViewStillTrue =
+ startedIds.length === 0 && failed.every((o) => LAUNCH_LEFT_AS_IS.has(o.reason))
+ let head = base.message
+ if (!startsOnViewStillTrue) head = head.replace(STARTS_ON_VIEW, '')
+ if (batch.unhidden) head = head.replace(CLOSED_HINT, '')
const message =
- base.message.replace(STARTS_ON_VIEW, '').replace(CLOSED_HINT, '') +
+ head +
(startedIds.length ? ` — started: ${startedIds.join(', ')}` : '') +
- (queuedIds.length ? ` — queued (${reason}): ${queuedIds.join(', ')}` : '')
+ [...byReason].map(([r, ids]) => ` — queued (${r}): ${ids.join(', ')}`).join('')
return {
...base,
message,
@@ -196,7 +247,8 @@ export function mergeRunNow<T extends { ok: true; message: string; result: Recor
startedIds,
queued: queuedIds.length > 0,
queuedIds,
- ...(reason ? { reason } : {})
+ ...(reason ? { reason } : {}),
+ reasons
}
}
}