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
// Canvas-control headless start (#925): `open-* --run-now` and `run --node`. Pure planners plus
// one orchestrator with injected effects, so Canvas.tsx only wires. See the spec (§4) for the flow:
// write-ahead claim → launch through main → patch the node wherever it lives NOW.
// Headless starts are local-only: a remote (SSH) node is refused here, before any claim
// (`remote-unsupported`, the primary fence), and `headlessPtyOptions` sets `requireRemote` for an
// SSH-project node as core's belt behind it.
import type { CanvasNodeState, PendingLaunch, Project, PtyCreateOptions } from '@shared/types'
import type { HeadlessLaunchFailure, HeadlessLaunchResult } from '@shared/headless-launch'
import { HEADLESS_COLS, HEADLESS_ROWS, localNodePtyOptions } from '@shared/node-pty-options'
import { countOpenProjects, decideOpen, type ProjectLimitState } from '@shared/project-limit'
import { COLD_OPEN_RUN_HINT } from './coldOpen'
export type RunVerbPlan =
| 'nothing-queued'
| 'already-starting'
| 'mounted'
| 'wait-for-mount'
| 'refuse-not-mounted'
| 'headless'
/** What `run --node` does. A project on screen never starts headless: its node either has a
* mounted writer (the ▶ path) or starts through the ordinary path when its terminal next mounts.
* That ordinary path only fires a plain, never-attempted launch with no dependencies: a
* `manualOnly` launch waits for an explicit Run now and an `--after` launch waits for its deps.
* Telling the caller either one "starts when mounted" would promise a start that never comes, so
* those are refused instead (`refuse-not-mounted`). */
export function planRunVerb(input: {
pending?: PendingLaunch
inFlight: boolean
projectActive: boolean
hasWriter: boolean
}): RunVerbPlan {
if (!input.pending?.command) return 'nothing-queued'
if (input.inFlight) return 'already-starting'
if (input.projectActive) {
if (input.hasWriter) return 'mounted'
// `after` is required by the type, but the launch comes out of hand-editable project JSON.
// A pull request wait (`--after-pr`) is a dependency too: the mount does not fire it. So is a
// success wait (`--after-success`), whose stations are normally in `after` as well — checked on
// its own because a hand-edited file need not keep the two in step.
const waitsOnDeps =
(input.pending.after?.length ?? 0) > 0 || !!input.pending.afterPr || !!input.pending.afterSuccess
return input.pending.manualOnly || waitsOnDeps ? 'refuse-not-mounted' : 'wait-for-mount'
}
return 'headless'
}
/** The write-ahead claim, saved before any spawn: a crash mid-start can never auto-start twice
* (`launchesToFire` skips manualOnly, on every build). */
export function claimForHeadless(p: PendingLaunch): PendingLaunch {
return { ...p, executor: 'core', attempted: true, manualOnly: true }
}
export function headlessStartNoticeText(projectName: string, count: number): string {
const what = count === 1 ? 'a session' : `${count} sessions`
return `An agent started ${what} in "${projectName}". That project is not on screen.`
}
/**
* The PtyCreateOptions of a headless start: the shared local builder at the headless size, plus
* `requireRemote` for an SSH-project node. `startHeadless` refuses such a node before any claim
* (`remote-unsupported`) — that is the primary fence. This is core's belt behind it: if a remote
* node ever reached the launcher, core's `spawnNew` refuses it (`unavailable:'ssh'`) instead of
* starting a LOCAL `nt-<id>` wearing the remote node's identity. `desktopHeadlessRequest` keeps
* the flag. Set here and not in `localNodePtyOptions`, whose key set is pinned and which the
* Server Edition shares.
*/
export function headlessPtyOptions(
project: Pick<Project, 'id' | 'cwd'>,
node: CanvasNodeState
): PtyCreateOptions {
return {
...localNodePtyOptions(project, node, { cols: HEADLESS_COLS, rows: HEADLESS_ROWS }),
...(node.sshRemoteTmux ? { requireRemote: true } : {})
}
}
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: 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 !== ''
}
/**
* `unhidesForHeadlessStart`, under the free-tier project limit (docs/project-limit.md). Restoring a
* closed tab makes a project open, so at the limit the tab simply stays in Recently closed: the
* session still starts, nothing is refused and no dialog is shown (nobody pressed anything), and
* the reply keeps its "reopen it from the welcome screen" hint — exactly the branch where the
* predicate says no. A claim still due is a no as well: a headless start never claims. While the
* limit is off, `decideOpen` always allows, so this answers what the predicate answers. A relay tab
* never counts as open (docs/project-limit.md, Definitions), so un-closing one is not an open the
* limit has a say in.
*/
export function shouldUnhideForHeadlessStart(
project: { closed?: boolean; ssh?: Project['ssh']; remote?: Project['remote'] },
activeProjectId: string,
limit: ProjectLimitState,
projects: readonly { closed?: boolean; remote?: boolean }[]
): boolean {
if (!unhidesForHeadlessStart(project, activeProjectId)) return false
return !!project.remote || decideOpen(limit, countOpenProjects(projects)) === 'allow'
}
export interface HeadlessStartDeps {
launch(req: { ptyOptions: PtyCreateOptions; command: string }): Promise<HeadlessLaunchResult>
/** Persist `pending` (undefined = cleared) on the node wherever it lives NOW; true = on disk. */
savePending(nodeId: string, pending: PendingLaunch | undefined): Promise<boolean>
markStarting(nodeId: string): void
markFailed(nodeId: string): void
clearDelivery(nodeId: string): void
/** Shared across calls: one start per node at a time. */
inFlight: Set<string>
}
export async function startHeadless(
deps: HeadlessStartDeps,
input: { project: Pick<Project, 'id' | 'cwd' | 'ssh'>; node: CanvasNodeState }
): Promise<HeadlessStartOutcome> {
const { node, project } = input
const id = node.id
const original = node.pendingLaunch
if (!original?.command) return { id, started: false, reason: 'nothing-queued' }
// A remote node is NEVER spawned locally. The launcher only spawns locally, so refuse before
// touching anything (the primary fence): the untouched pending launch starts on view, over SSH.
// The project is asked too, not only the node's flags: a node of an SSH project that carries
// neither flag is still remote. `headlessPtyOptions` also sets `requireRemote` for a node with
// `sshRemoteTmux`, core's belt behind this.
if (project.ssh || node.ssh || node.sshRemoteTmux) {
return { id, started: false, reason: 'remote-unsupported' }
}
if (deps.inFlight.has(id)) return { id, started: false, reason: 'already-starting' }
deps.inFlight.add(id)
try {
if (!(await deps.savePending(id, claimForHeadless(original)))) {
// Never spawn on an unsaved claim: a crash would re-deliver on the next view.
await deps.savePending(id, original)
return { id, started: false, reason: 'claim-not-saved' }
}
deps.markStarting(id)
let result: HeadlessLaunchResult
try {
result = await deps.launch({
ptyOptions: headlessPtyOptions(project, node),
command: original.command
})
} catch {
result = { outcome: 'failed', reason: 'spawn-failed' }
}
if (result.outcome === 'delivered') {
deps.clearDelivery(id)
await deps.savePending(id, undefined)
return { id, started: true }
}
if (result.reason === 'not-persistent') {
// Nothing was typed and no session survives. Normally nothing was spawned at all (refused
// before the spawn); in the race where the backend went away between core's probe and the
// spawn, the plain shell it got was released, which kills it. Hand the node back exactly as
// it was, so a cold open starts on view and an already-attempted node keeps its manual Run now.
deps.clearDelivery(id)
await deps.savePending(id, original)
} else {
deps.markFailed(id)
}
return { id, started: false, reason: result.reason }
} finally {
deps.inFlight.delete(id)
}
}
export interface PendingStoreEnv {
activeProjectId(): string
patchLive(nodeId: string, pending: PendingLaunch | undefined): boolean
patchStored(projectId: string, nodeId: string, pending: PendingLaunch | undefined): boolean
writeDisk(): Promise<boolean>
markDirty(): void
}
/** React Flow is the truth for the ACTIVE project, the store for every other one. Decided at the
* moment of each write, because the user may switch projects while a start is in flight. */
export async function savePendingAnywhere(
env: PendingStoreEnv,
projectId: string,
nodeId: string,
pending: PendingLaunch | undefined
): Promise<boolean> {
if (env.activeProjectId() === projectId) {
if (!env.patchLive(nodeId, pending)) return false
env.markDirty()
return true
}
if (!env.patchStored(projectId, nodeId, pending)) return false
return env.writeDisk()
}
const STARTS_ON_VIEW = ' — queued; starts when that project is next viewed' + COLD_OPEN_RUN_HINT
const CLOSED_HINT = / \(that project is closed — reopen it from the welcome screen\)/
/** 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,
batch: HeadlessStartBatch
): T {
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 =
head +
(startedIds.length ? ` — started: ${startedIds.join(', ')}` : '') +
[...byReason].map(([r, ids]) => ` — queued (${r}): ${ids.join(', ')}`).join('')
return {
...base,
message,
result: {
...base.result,
started: startedIds.length > 0,
startedIds,
queued: queuedIds.length > 0,
queuedIds,
...(reason ? { reason } : {}),
reasons
}
}
}