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
import type { TextDeliveryResult } from '../shared/text-delivery'
import { isLaunchShell } from '../shared/agents/pane'
import { randomBytes, randomUUID } from 'node:crypto'
import path from 'node:path'
import { publishCanvasMutation } from '../core/canvas-sync'
import { contentOf, diffContent, type CanvasContent } from '../shared/canvas-content'
import { groupsFirst } from '../shared/node-order'
import { launchHeadless } from '../core/headless-launch'
import { gateProjectTarget, GRANT_CAP } from '../core/project-grants'
import {
LINK_ENDPOINT_NOT_FOUND,
LINK_PROJECT_ONLY,
planBridges,
type LinkEndpoint
} from '../shared/canvas-link'
import {
invalidNodeColorMessage,
resolveNodeColor,
SYSTEM_NODE_COLORS,
type NodeColor
} from '../shared/node-colors'
import { applyStickyWrite, parseStickyArgs, resolveStickyRef } from '../shared/sticky-write'
import type { HeadlessLaunchFailure, HeadlessLaunchResult } from '../shared/headless-launch'
import { localNodePtyOptions } from '../shared/node-pty-options'
import type { WorkspaceStore } from '../core/workspace-store'
import {
AGENT_CONFIG,
canContextLink,
canControlCanvas,
gatePermissionMode,
hasHooks,
resolvePermissionMode,
supportsSessionIdFlag,
type AgentId,
type BuiltinAgentId
} from '../shared/agents/config'
import { assembleLaunchCommand } from '../shared/agents/launch'
import { ownedAccountId } from '../shared/agents/account-binding'
import type { AgentState, NormalizedAgentEvent } from '../shared/agents/normalize'
import { oneLine } from '../shared/one-line'
import { rootPositionWith } from '../shared/root-position'
import { RUN_NOW_AFTER_REFUSAL, runNowRequested } from '../shared/control-verbs'
import {
RUN_NOW_AFTER_SUCCESS_REFUSAL,
normalizeSuccessWaitHold,
parseAfterSuccessArg,
parseSuccessDeadlineArg,
successDepRefusal,
successWaitSatisfied,
type StationOutcomeRecord,
type SuccessDepFacts,
type SuccessWaitHold
} from '../shared/station-outcome'
import { isRemoteSessionNode } from '../shared/worktree'
import { issueLaunchPrompt, resolveIssueArg, type IssueRef } from '../shared/github-issue-ref'
import { runEndedEvent, runStartedEvent } from '../shared/issue-runs'
import type { BoardLogEntry } from '../shared/types'
import { UNKNOWN_CODEX_CLI_CAPS } from '../shared/types'
import type {
BridgeLink,
CanvasMutation,
CanvasNodeState,
ClaudeCliCaps,
CodexCliCaps,
GrokCliCaps,
Project,
PtyCreateOptions,
PtyCreateResult,
Settings,
Workspace
} from '../shared/types'
import {
NODE_SIZE_MAX,
STICKY_NODE_MIN_SIZE,
STICKY_NODE_SIZE,
TERMINAL_NODE_SIZE_MIN,
resolveDefaultNodeSize
} from '../shared/default-node-size'
export interface ServerControlReply {
ok: boolean
message?: string
result?: unknown
error?: string
}
/** The PtyManager surface the headless factory uses, kept narrow for deterministic tests. */
export interface HeadlessPty {
createHeadless(options: PtyCreateOptions): Promise<PtyCreateResult>
/** Probe only. Boot reconciliation must never turn absence into a fresh session. */
paneCommand(persistKey: string): Promise<string | null>
sessionExists(persistKey: string): Promise<boolean>
sendText(nodeId: string, text: string, opts?: { enter?: boolean }): Promise<TextDeliveryResult>
persistentSpawnAvailable(): boolean
writeHeadless(persistKey: string, data: string): boolean
onOutput(persistKey: string, cb: (chunk: string) => void): () => void
releaseHeadless(persistKey: string): void
destroySession(
clientId: number | null,
persistKey: string,
opts?: { everySocket?: boolean }
): Promise<void>
}
/** WorkspaceStore's mutation surface, also narrow so tests can use the real store or a fake. */
export type HeadlessWorkspace = Pick<WorkspaceStore, 'load' | 'save'>
export interface HeadlessNodeFactoryDeps {
workspaceStore: HeadlessWorkspace
ptyManager: HeadlessPty
settings(): Settings
cliCaps(): Promise<ClaudeCliCaps>
/**
* grok's OWN `--session-id` probe. Separate from `cliCaps` because the two CLIs are installed and
* upgraded independently, so claude's answer is not evidence about grok (CLAUDE.md rule 9: a gate
* fed by a version probe belongs to the agent it probes). Wired even though `SERVER_AGENTS` does
* not yet include grok: `supportsSessionIdFlag`'s third argument is required precisely so a caller
* cannot forget the probe and silently get "grok never mints", and a hard-coded `false` here would
* be that forgotten probe, waiting for the day grok joins the set.
*/
grokCaps(): Promise<GrokCliCaps>
/**
* codex's OWN `--help` probe, and separate from `cliCaps`/`grokCaps` for the same reason they are
* separate from each other. It answers which values this host's `codex` accepts for
* `--ask-for-approval`: the set changed between releases (`untrusted` was removed in 0.149.0) and
* clap EXITS on a value it does not know, so a launch line built from a table rather than from
* the binary is a dead session, not a degraded one — issue #785.
*/
codexCaps(): Promise<CodexCliCaps>
/** Whether this host's Codex launcher + shared app-server identity spine are ready. */
codexSharedIdentity(): Promise<boolean>
/** Hook-mirror lookups. A stored agentId wins; these cover a plain terminal running an agent. */
stateOf(nodeId: string): AgentState | undefined
agentIdOf?(nodeId: string): string | undefined
/** A station's latest task report (`report-outcome`, core's store) — what `--after-success` waits
* on. Absent = no report is ever known, so a success wait never releases on its own. */
outcomeOf?(nodeId: string): StationOutcomeRecord | undefined
/** Has this station been handed new work (a `send` / `reply` queued or landed, a `run`) that no
* turn since has finished? core/station-handover.ts — while it has, plain `--after` on it is not
* satisfied, whatever its state reads: its `done` is the PREVIOUS task's. Absent = nothing is
* ever handed over (the pre-tracker behaviour). */
handedOver?(nodeId: string): boolean
env?: Record<string, string | undefined>
now?: () => number
/**
* Cast one content op (node, edge or board) to every client. Default: the reflector
* (`publishCanvasMutation`), whose listener is the canvas authority. Every op is cast BEFORE the
* save that persists it (`castAndSave`): on a governed project the save is overlaid with the
* authority's content, which holds only what it heard as ops.
*/
publishMutation?: (projectId: string, m: CanvasMutation) => void
/** The whole project, to browsers, on `workspace:server-change` (merged, never a conflict bar). */
publishProject?: (project: Project) => void
/** Injectable only so tests can seed creator facts; production uses a fresh process-local ledger. */
ownership?: HeadlessNodeOwnership
/** Test seam for the launch settle; production uses core's SETTLE_* defaults. */
launchTiming?: { quietMs: number; capMs: number }
/**
* The `owner/repo` a project's kanban board syncs with — what `open-agent --issue #N` means. The
* GitHub host controller's answer (configured, else detected from the project's git remote), the
* same one the issue lane uses. Absent/throwing/null = only the board's explicitly configured
* repository counts, and a `#N` against a board with none is refused — never guessed.
*/
issueRepository?: (projectId: string) => Promise<string | null>
/** Append to a project's board log (the issue card's run history). Absent = no history is
* written; the session still opens. */
appendBoardLog?: (projectId: string, entry: BoardLogEntry) => Promise<boolean>
}
/** The author of a run-history line this factory writes: the app acting on an agent's request. */
const RUN_LOG_AUTHOR = { name: 'nodeterm', color: '#8b8b8b' } as const
export interface HeadlessNodeOwner {
sourceNodeId: string
projectId: string
}
export interface HeadlessNodeOwnership {
ownerOf(nodeId: string): HeadlessNodeOwner | undefined
record(nodeId: string, owner: HeadlessNodeOwner): void
forget(nodeId: string): void
clear(): void
}
/**
* Creator proof for Server Edition canvas mutations. Deliberately process-local: after a service
* restart, a git-shared/hand-editable project file cannot reassert who created a node. Unknown
* ownership therefore fails closed until this server run records a fresh agent-requested spawn.
*/
export function createHeadlessNodeOwnership(): HeadlessNodeOwnership {
const owners = new Map<string, HeadlessNodeOwner>()
return {
ownerOf: (nodeId) => owners.get(nodeId),
record: (nodeId, owner) => owners.set(nodeId, owner),
forget: (nodeId) => owners.delete(nodeId),
clear: () => owners.clear()
}
}
/** One node an `open-*` persisted but could not start. */
export interface OpenLaunchFailure {
id: string
reason: HeadlessLaunchFailure
/** The node still holds its launch (manualOnly), so the user's Run now can deliver it. */
retained: boolean
}
/**
* The `open-*` failure reply (#925). Each failed node is named with its own reason, grouped, so a
* caller can tell a failure Run now may get past from one it repeats: `line-too-long` fails the
* same way on every attempt, and this edition has no `--prompt-file` (the open flag allowlist),
* so the only way past it is a shorter prompt or command. "Do not repeat the open request" holds
* for every reason: the nodes are persisted, so the same request would open duplicates.
*/
export function launchFailedError(
failures: readonly OpenLaunchFailure[],
verb: 'open-terminal' | 'open-agent'
): string {
const groups = new Map<string, OpenLaunchFailure & { ids: string[] }>()
for (const f of failures) {
const key = `${f.reason}:${f.retained}`
const group = groups.get(key) ?? { ...f, ids: [] }
group.ids.push(f.id)
groups.set(key, group)
}
const what = (g: OpenLaunchFailure): string =>
g.reason === 'line-too-long'
? 'the launch line is longer than a terminal line takes, so Run now will fail the same way; ' +
`shorten the ${verb === 'open-terminal' ? 'command' : 'prompt'}`
: g.retained
? 'launch retained for Run now in the node'
: 'no launch was held'
const clauses = [...groups.values()].map((g) => `${g.reason}: ${g.ids.join(', ')} (${what(g)})`)
return (
`launch-failed: node(s) ${failures.map((f) => f.id).join(', ')} were persisted but their PTY or ` +
`initial command could not be delivered — ${clauses.join('; ')}; do not repeat the open request`
)
}
const TERMINAL_LIMIT = 8
const AGENT_LIMIT = 5
const TERMINAL_COLS = 120
const TERMINAL_ROWS = 36
const TERMINAL_SIZE = { width: 640, height: 440 }
const H_GAP = 80
const V_GAP = 36
const GROUP_PAD = 28
const GROUP_HEADER = 34
const SERVER_AGENTS: ReadonlySet<string> = new Set(['claude', 'codex', 'gemini'])
function token(): string {
return randomBytes(4).toString('hex')
}
function nextId(prefix: 'term' | 'sticky' | 'group'): string {
return `${prefix}-${Date.now().toString(36)}-${token()}`
}
function edgeId(prefix: string, source: string, target: string): string {
return `${prefix}-${source}-${target}-${token()}`
}
function parseCount(raw: string | undefined, max: number): number {
return Math.max(1, Math.min(max, Number.parseInt(raw || '1', 10) || 1))
}
function terminalSize(settings: Settings): { width: number; height: number } {
const clamp = (value: unknown, min: number, max: number, fallback: number): number => {
const n = typeof value === 'number' && Number.isFinite(value) ? Math.round(value) : fallback
return Math.min(max, Math.max(min, n))
}
return {
width: clamp(settings.defaultNodeWidth, TERMINAL_NODE_SIZE_MIN.width, NODE_SIZE_MAX.width, TERMINAL_SIZE.width),
height: clamp(settings.defaultNodeHeight, TERMINAL_NODE_SIZE_MIN.height, NODE_SIZE_MAX.height, TERMINAL_SIZE.height)
}
}
function unsupportedFlags(
args: Record<string, string>,
allowed: ReadonlySet<string>
): string | undefined {
const unknown = Object.keys(args).find((key) => !allowed.has(key))
return unknown ? `--${unknown} is not supported by Server Edition canvas control` : undefined
}
function sourceProject(workspace: Workspace, nodeId: string): { project: Project; node: CanvasNodeState } | null {
const matches: Array<{ project: Project; node: CanvasNodeState }> = []
for (const project of workspace.projects) {
const node = project.nodes.find((candidate) => candidate.id === nodeId)
if (node) matches.push({ project, node })
}
return matches.length === 1 ? matches[0] : null
}
function effectiveAgentId(
node: CanvasNodeState,
runtimeAgentId: ((nodeId: string) => string | undefined) | undefined
): AgentId | undefined {
const id = node.agentId || runtimeAgentId?.(node.id)
return id ? (id as AgentId) : undefined
}
function sourceCanControl(
node: CanvasNodeState,
runtimeAgentId: ((nodeId: string) => string | undefined) | undefined
): boolean {
const agentId = effectiveAgentId(node, runtimeAgentId)
return !!agentId && canControlCanvas(agentId)
}
function placeRight(
project: Project,
source: CanvasNodeState,
size: { width: number; height: number },
reserved: readonly CanvasNodeState[] = []
): { x: number; y: number } {
const origin = rootPosition(project.nodes, source)
const sourceWidth = source.size?.width || TERMINAL_SIZE.width
const occupied = [...project.nodes, ...reserved].map((node) => {
const position = rootPosition(project.nodes, node)
return {
x: position.x,
y: position.y,
width: Math.max(1, node.size?.width || TERMINAL_SIZE.width),
height: Math.max(1, node.size?.height || TERMINAL_SIZE.height)
}
})
// Keep the existing compact three-row grid, but scan it rather than assuming this request's
// local index is globally free. Repeated requests therefore continue into the first available
// row/column instead of returning to slot zero and stacking nodes on top of one another.
for (let slot = 0; ; slot++) {
const column = Math.floor(slot / 3)
const row = slot % 3
const candidate = {
x: origin.x + sourceWidth + H_GAP + column * (size.width + H_GAP),
y: origin.y + row * (size.height + V_GAP),
width: size.width,
height: size.height
}
const collides = occupied.some((rect) =>
candidate.x < rect.x + rect.width &&
candidate.x + candidate.width > rect.x &&
candidate.y < rect.y + rect.height &&
candidate.y + candidate.height > rect.y
)
if (!collides) return { x: candidate.x, y: candidate.y }
}
}
function addEdge(list: BridgeLink[], source: string, target: string, prefix: string): void {
if (source === target) return
if (list.some((edge) =>
(edge.source === source && edge.target === target) ||
(edge.source === target && edge.target === source))) return
list.push({ id: edgeId(prefix, source, target), source, target })
}
/** One node edit a verb re-applies to a fresh read (`savePatches`). Idempotent. */
interface NodePatch {
projectId: string
nodeId: string
/** Apply to the fresh node. true = it LANDED: the node was in the state this patch is for (see
* each patch for which). A caller that delivers on the strength of a patch asks this, because the
* fresh read can find the node deleted, or re-armed, by a teammate since the verb looked. */
apply(node: CanvasNodeState): boolean
}
/** What `savePatches` did: whether the save landed, and per patch whether it applied to the fresh
* read. A patch LANDED only when both are true. */
interface PatchSave {
saved: boolean
applied: boolean[]
}
/** The held launch this verb owns, by its command: a patch never touches a launch someone replaced. */
const ownLaunch = (node: CanvasNodeState, command: string): boolean => node.pendingLaunch?.command === command
/** The launch was delivered: the hold is gone. Lands when the hold was still this verb's own. */
function clearLaunch(projectId: string, nodeId: string, command: string): NodePatch {
return {
projectId,
nodeId,
apply: (node) => {
if (!ownLaunch(node, command)) return false
delete node.pendingLaunch
return true
}
}
}
/** The launch is claimed (or failed): only an explicit Run now may deliver it now. Lands only when
* THIS patch claimed it: the hold was this verb's own AND nobody had claimed it yet (a launch already
* `manualOnly` on the fresh read was claimed by someone else, and delivering it again would type the
* command twice). */
function claimLaunch(projectId: string, nodeId: string, command: string, attempted: boolean): NodePatch {
return {
projectId,
nodeId,
apply: (node) => {
if (!ownLaunch(node, command)) return false
const unclaimed = node.pendingLaunch!.manualOnly !== true
node.pendingLaunch = { ...node.pendingLaunch!, manualOnly: true, ...(attempted ? { attempted: true } : {}) }
return unclaimed
}
}
}
/** A dependency this arm waited for has had its first real working turn. */
function dropAwaitWorking(projectId: string, nodeId: string, command: string, depId: string): NodePatch {
return {
projectId,
nodeId,
apply: (node) => {
const held = node.pendingLaunch
if (!held || !ownLaunch(node, command) || !held.awaitWorking?.includes(depId)) return false
const rest = held.awaitWorking.filter((id) => id !== depId)
const { awaitWorking: _awaitWorking, ...kept } = held
node.pendingLaunch = rest.length ? { ...kept, awaitWorking: rest } : kept
return true
}
}
}
/** A project absent from a baseline: all of its content is new. */
const EMPTY_CONTENT: CanvasContent = { nodes: [], bridges: [], ropes: [] }
/** Every project's content, deep-copied: a verb edits its workspace in place (`node.pendingLaunch =
* …`), so a baseline that shared those objects would diff as unchanged. */
function snapshotContent(workspace: Workspace): Map<string, CanvasContent> {
return new Map(workspace.projects.map((p) => [p.id, structuredClone(contentOf(p))]))
}
function nodeProjects(workspace: Workspace, nodeId: string): Project[] {
return workspace.projects.filter((project) => project.nodes.some((node) => node.id === nodeId))
}
function headlessLinkEndpoint(
node: CanvasNodeState,
runtimeAgentId: ((nodeId: string) => string | undefined) | undefined
): LinkEndpoint {
const agentId = node.kind === 'terminal' ? node.agentId ?? runtimeAgentId?.(node.id) : undefined
return {
kind: node.kind,
contextCapable: !!agentId && canContextLink(agentId as AgentId)
}
}
function isDescendant(
nodes: readonly CanvasNodeState[],
candidateId: string,
ancestorId: string
): boolean {
const byId = new Map(nodes.map((node) => [node.id, node]))
const seen = new Set<string>()
let current = byId.get(candidateId)
while (current?.parentId && !seen.has(current.parentId)) {
if (current.parentId === ancestorId) return true
seen.add(current.parentId)
current = byId.get(current.parentId)
}
return false
}
/** Re-fit one persisted group around its direct children without moving them in parent space. */
function fitGroupToChildren(
nodes: CanvasNodeState[],
groupId: string
): CanvasNodeState[] {
const group = nodes.find((node) => node.id === groupId)
if (!group || group.kind !== 'group') return nodes
const children = nodes.filter((node) => node.parentId === groupId)
if (!children.length) return nodes
const absoluteX = (child: CanvasNodeState): number => group.position.x + child.position.x
const absoluteY = (child: CanvasNodeState): number => group.position.y + child.position.y
const minX = Math.min(...children.map(absoluteX))
const minY = Math.min(...children.map(absoluteY))
const maxX = Math.max(...children.map((child) => absoluteX(child) + child.size.width))
const maxY = Math.max(...children.map((child) => absoluteY(child) + child.size.height))
const x = minX - GROUP_PAD
const y = minY - GROUP_PAD - GROUP_HEADER
const size = {
width: maxX - minX + GROUP_PAD * 2,
height: maxY - minY + GROUP_PAD * 2 + GROUP_HEADER
}
return nodes.map((node) => {
if (node.id === groupId) return { ...node, position: { x, y }, size }
if (node.parentId === groupId) {
return {
...node,
position: { x: absoluteX(node) - x, y: absoluteY(node) - y }
}
}
return node
})
}
function fitAncestorChain(
nodes: CanvasNodeState[],
groupId: string | undefined
): CanvasNodeState[] {
let next = nodes
let currentId = groupId
const seen = new Set<string>()
while (currentId && !seen.has(currentId)) {
seen.add(currentId)
next = fitGroupToChildren(next, currentId)
currentId = next.find((node) => node.id === currentId)?.parentId
}
return next
}
function groupPersistedNodes(
nodes: CanvasNodeState[],
ids: string[],
groupIndex: number,
label: string | undefined,
color: NodeColor | undefined
): { nodes: CanvasNodeState[]; groupId: string; changed: CanvasNodeState[] } | null {
const selected = new Set(ids)
const members = nodes.filter((node) => selected.has(node.id))
if (!members.length || new Set(members.map((node) => node.parentId ?? null)).size !== 1) {
return null
}
if (
members.some((member) =>
members.some(
(other) => other.id !== member.id && isDescendant(nodes, other.id, member.id)
)
)
) {
return null
}
const minX = Math.min(...members.map((node) => node.position.x))
const minY = Math.min(...members.map((node) => node.position.y))
const maxX = Math.max(...members.map((node) => node.position.x + node.size.width))
const maxY = Math.max(...members.map((node) => node.position.y + node.size.height))
const x = minX - GROUP_PAD
const y = minY - GROUP_PAD - GROUP_HEADER
const parentId = members[0].parentId
const group: CanvasNodeState = {
id: nextId('group'),
kind: 'group',
position: { x, y },
size: {
width: maxX - minX + GROUP_PAD * 2,
height: maxY - minY + GROUP_PAD * 2 + GROUP_HEADER
},
title: label || `Group ${groupIndex + 1}`,
color: color ?? SYSTEM_NODE_COLORS[groupIndex % SYSTEM_NODE_COLORS.length],
group: null,
...(parentId ? { parentId } : {})
}
const before = new Map(nodes.map((node) => [node.id, node]))
const updated = nodes.map((node) =>
selected.has(node.id)
? {
...node,
parentId: group.id,
position: { x: node.position.x - x, y: node.position.y - y }
}
: node
)
const next = groupsFirst(fitAncestorChain(groupsFirst([group, ...updated]), parentId))
return {
nodes: next,
groupId: group.id,
changed: next.filter((node) => !before.has(node.id) || before.get(node.id) !== node)
}
}
function rootPosition(
nodes: readonly CanvasNodeState[],
node: CanvasNodeState
): { x: number; y: number } {
const byId = new Map(nodes.map((candidate) => [candidate.id, candidate]))
return rootPositionWith(node, (id) => byId.get(id))
}
/** Desktop `ungroupNodes` semantics over persisted nodes: direct children move up one level. */
function ungroupPersistedNodes(
nodes: CanvasNodeState[],
groupId: string
): { nodes: CanvasNodeState[]; promoted: CanvasNodeState[] } {
const frame = nodes.find((node) => node.id === groupId)
if (!frame || frame.kind !== 'group') return { nodes, promoted: [] }
const parentId = frame.parentId
const parent = parentId ? nodes.find((node) => node.id === parentId && node.kind === 'group') : undefined
const parentRoot = parent ? rootPosition(nodes, parent) : { x: 0, y: 0 }
const promoted: CanvasNodeState[] = []
const moved = nodes.map((node) => {
if (node.parentId !== groupId) return node
const root = rootPosition(nodes, node)
const next: CanvasNodeState = {
...node,
position: { x: root.x - parentRoot.x, y: root.y - parentRoot.y }
}
if (parent) next.parentId = parent.id
else delete next.parentId
promoted.push(next)
return next
})
return {
nodes: groupsFirst(moved.filter((node) => node.id !== groupId)),
promoted
}
}
function ptyOptions(project: Project, node: CanvasNodeState): PtyCreateOptions {
return localNodePtyOptions(project, node, { cols: TERMINAL_COLS, rows: TERMINAL_ROWS })
}
/**
* Server-side canvas authoring and launch scheduler.
*
* Every workspace read/modify/save transaction is serialized. That is important even on one
* Node event loop: WorkspaceStore.load/save both await filesystem operations, so two simultaneous
* `/control/open-agent` calls would otherwise read the same snapshot and the later save would
* erase the earlier node. PTY creation happens after the node is durable, matching the renderer's
* recoverable failure direction: a spawn error leaves a visible, reopenable node instead of an
* invisible tmux session.
*/
export class HeadlessNodeFactory {
private serial: Promise<unknown> = Promise.resolve()
private attached = new Set<string>()
/** Process-local proof that a caller created a node during THIS Server Edition run. */
private ownership: HeadlessNodeOwnership
/** Fresh server-spawned agents that have not emitted their first real working turn yet. */
private awaitingFirstWorking = new Set<string>()
/** Stations whose LAST turn ended on an API/model error (#521, the `errored` flag on a `done`),
* from this edition's own event stream — the desktop's `lastTurnError`, kept here so a success
* wait holds on an errored turn on both editions. Cleared by the next genuine new turn. */
private lastTurnErrored = new Set<string>()
/**
* Server-local `open-project` grants. The browser shell's grant ledger is process-local too,
* but Server Edition has its own process and handler. A service restart deliberately clears
* this map; `openProject()` can re-establish a grant only for an exact, already-saved local
* project path, so a surviving agent session is never stranded after that restart.
*/
private projectGrants = new Map<string, Set<string>>()
private stopped = false
/** Per loaded workspace copy: every project's content as last loaded or saved (`castAndSave`). */
private baselines = new WeakMap<Workspace, Map<string, CanvasContent>>()
constructor(private readonly deps: HeadlessNodeFactoryDeps) {
this.ownership = deps.ownership ?? createHeadlessNodeOwnership()
}
private runExclusive<T>(work: () => Promise<T>): Promise<T> {
const run = this.serial.then(work, work)
this.serial = run.then(
() => undefined,
() => undefined
)
return run
}
/** THE ONE READ of the store. A read-only view: never edited, never saved. */
private readWorkspace(): Promise<Workspace> {
return this.deps.workspaceStore.load({ sideline: false })
}
/**
* The load a verb EDITS. A private copy of the workspace, so no verb ever edits an object the store
* or the canvas authority still holds (a governed project's nodes come from the authority's own
* state), and the content of every project as loaded: `castAndSave` diffs against it.
*/
private async loadForEdit(): Promise<Workspace> {
const workspace = structuredClone(await this.readWorkspace())
this.baselines.set(workspace, snapshotContent(workspace))
return workspace
}
/**
* THE ONE SAVE. Diff every project's whole content against what was last loaded or saved, cast
* every op, THEN save. Nothing is hand-listed per verb, and that is the point: on a project the
* canvas authority governs, the save is overlaid with the authority's content, which holds only
* what it heard as ops, so any change a verb made that is not cast here is dropped from disk
* (docs/hosted-team-relay.md). The reflector hands each op to the authority synchronously, so
* every one is in its state before the overlay reads it. The ops are cast from a copy, never from
* the workspace a verb keeps editing, so nobody downstream holds an object that changes later.
*
* Refused once canvas control has stopped: the shell detaches the authority from the store right
* after, and a verb still mid-launch would otherwise write its copy un-overlaid over the
* authority's final flush. `onlyIfChanged` skips a save that would carry no op. Answers whether it
* saved.
*/
private async castAndSave(workspace: Workspace, opts: { onlyIfChanged?: boolean } = {}): Promise<boolean> {
if (this.stopped) {
console.warn('[headless-node-factory] canvas control stopped: a pending canvas write was skipped')
return false
}
const before = this.baselines.get(workspace)
const after = snapshotContent(workspace)
const cast = this.deps.publishMutation ?? ((projectId: string, m: CanvasMutation) => {
publishCanvasMutation(projectId, m)
})
const ops: Array<[string, CanvasMutation]> = []
for (const project of workspace.projects) {
const next = after.get(project.id)
if (!next) continue
for (const m of diffContent(before?.get(project.id) ?? EMPTY_CONTENT, next, project.id)) ops.push([project.id, m])
}
if (opts.onlyIfChanged && !ops.length) return false
for (const [projectId, m] of ops) cast(projectId, m)
this.baselines.set(workspace, after)
await this.deps.workspaceStore.save(workspace)
return true
}
/**
* A SECOND phase's save: the launch between the two phases can take seconds, and the copy the
* verb loaded before it predates whatever a teammate did meanwhile (a move, a rename, a deletion).
* So re-read, re-apply ONLY this verb's own patches to the nodes that still exist (a node deleted
* meanwhile stays deleted), and save only if that changed anything. The patches must be idempotent:
* every call re-applies all of them, so a later save still carries an earlier one.
*
* Answers per patch whether it applied to the fresh read, and whether the save landed: a caller
* that delivers on the strength of a claim must see BOTH (a stopping factory refuses the save, and
* the node may be gone or re-armed since the verb looked).
*/
private async savePatches(patches: readonly NodePatch[]): Promise<PatchSave> {
if (!patches.length) return { saved: false, applied: [] }
const workspace = await this.loadForEdit()
const applied = patches.map((patch) => {
const node = workspace.projects.find((p) => p.id === patch.projectId)?.nodes.find((n) => n.id === patch.nodeId)
return node ? patch.apply(node) : false
})
return { saved: await this.castAndSave(workspace, { onlyIfChanged: true }), applied }
}
/** The PERSISTED projects to browsers (`workspace:server-change`), re-read after the save — never
* a verb's own copy, which can predate a teammate's edit and would undo it on every client that
* merges it. Their content already travelled as ops in `castAndSave`. */
private async publishPersisted(projectIds: Iterable<string>): Promise<void> {
if (!this.deps.publishProject || this.stopped) return
const wanted = new Set(projectIds)
if (!wanted.size) return
for (const project of (await this.readWorkspace()).projects) {
if (wanted.has(project.id)) this.deps.publishProject(project)
}
}
/** Who opened `nodeId` during THIS server run (and into which project), or undefined — the
* station-failure notice's recipient rule on this edition (src/core/agents/station-notice.ts). */
openerOf(nodeId: string): HeadlessNodeOwner | undefined {
return this.ownership.ownerOf(nodeId)
}
/** Literal creator ownership: a caller may act only on nodes it freshly spawned this run. */
ownsSpawn(sourceNodeId: string, nodeId: string): boolean {
return this.ownership.ownerOf(nodeId)?.sourceNodeId === sourceNodeId
}
/** A verified caller may mutate only a node it freshly created during this server run. */
private ownsMutation(sourceNodeId: string, nodeId: string): boolean {
return this.ownsSpawn(sourceNodeId, nodeId)
}
/** All-or-nothing ownership gate: validate every id before any canvas or session mutation. */
private unownedMutation(sourceNodeId: string, nodeIds: readonly string[]): string | undefined {
return nodeIds.find((nodeId) => !this.ownsMutation(sourceNodeId, nodeId))
}
private ownershipRefusal(verb: string, sourceNodeId: string, nodeId: string): ServerControlReply {
return {
ok: false,
error:
`${verb}-not-owner: ${sourceNodeId} may modify only nodes it spawned during this server ` +
`run; ${nodeId} was not spawned by this caller`
}
}
private projectGranted(sourceNodeId: string, projectId: string): boolean {
return this.projectGrants.get(sourceNodeId)?.has(projectId) ?? false
}
private grantProject(sourceNodeId: string, projectId: string): boolean {
const grants = this.projectGrants.get(sourceNodeId) ?? new Set<string>()
if (!grants.has(projectId) && grants.size >= GRANT_CAP) return false
grants.add(projectId)
this.projectGrants.set(sourceNodeId, grants)
return true
}
private async attach(project: Project, node: CanvasNodeState): Promise<PtyCreateResult> {
if (this.attached.has(node.id)) {
return { sessionId: node.id, fresh: false }
}
const result = await this.deps.ptyManager.createHeadless(ptyOptions(project, node))
if (result.sessionId) this.attached.add(node.id)
return result
}
/**
* Spawn-or-attach `node` and deliver `command` through the shared echo-verified launcher (#925).
* - `release:false` keeps the server's synthetic client attached, as it always has.
* - `requirePersistent:false`, because that attached client is what keeps even a plain-shell
* session reachable here. (The desktop releases its client, so it refuses a plain shell instead.)
* - `createHeadless` goes through `attach()` so the `attached` ledger stays authoritative.
*/
private launch(project: Project, node: CanvasNodeState, command: string): Promise<HeadlessLaunchResult> {
const pty = this.deps.ptyManager
return launchHeadless(
{
persistentSpawnAvailable: () => pty.persistentSpawnAvailable(),
createHeadless: () => this.attach(project, node),
paneCommand: (key) => pty.paneCommand(key),
writeHeadless: (key, data) => pty.writeHeadless(key, data),
onOutput: (key, cb) => pty.onOutput(key, cb),
releaseHeadless: (key) => pty.releaseHeadless(key),
timing: this.deps.launchTiming
},
{ ptyOptions: ptyOptions(project, node), command, release: false, requirePersistent: false }
)
}
private resolveTarget(
workspace: Workspace,
source: { project: Project; node: CanvasNodeState },
verb: string,
args: Record<string, string>,
verified: boolean
): Project | ServerControlReply {
const targetId = args.project || source.project.id
const target = workspace.projects.find((project) => project.id === targetId)
const gate = gateProjectTarget({
verified,
verb,
targetProjectId: args.project || undefined,
callerProjectId: source.project.id,
targetIsSsh: target ? !!target.ssh : undefined,
granted: this.projectGranted(source.node.id, targetId)
})
if (gate !== 'allow') return { ok: false, error: gate.refuse }
if (!target) return { ok: false, error: 'project-target-refused: target project is unavailable' }
if (target.ssh) {
return {
ok: false,
error: 'project-target-ssh-unsupported: Server Edition v1 only creates local sessions'
}
}
return target
}
private now(): number {
return this.deps.now?.() ?? Date.now()
}
private handedOver(depId: string): boolean {
return this.deps.handedOver?.(depId) === true
}
/** What a success wait knows about one station, from the same facts this edition's `--after`
* reads (the mirror's `done`, the `awaitWorking` fresh-spawn rule), the errored-turn rule (#521,
* `lastTurnErrored`, which this edition's plain `--after` does not apply), and its report. */
private successFacts(
project: Project,
depId: string,
observed?: Pick<NormalizedAgentEvent, 'nodeId' | 'state'>
): SuccessDepFacts {
const exists = project.nodes.some((candidate) => candidate.id === depId)
const state = observed?.nodeId === depId ? observed.state : this.deps.stateOf(depId)
const reported = this.deps.outcomeOf?.(depId)
return {
exists,
turnDone:
exists &&
!this.awaitingFirstWorking.has(depId) &&
!this.lastTurnErrored.has(depId) &&
!this.handedOver(depId) &&
state === 'done',
...(reported ? { outcome: reported } : {})
}
}
private resolveAfter(
project: Project,
raw: string | undefined,
verb: string
): string[] | ServerControlReply {
if (!raw) return []
const ids = [...new Set(raw.split(',').map((id) => id.trim()).filter(Boolean))]
for (const id of ids) {
const node = project.nodes.find((candidate) => candidate.id === id)
if (!node) return { ok: false, error: `${verb}: --after names no existing node (${id})` }
const agentId = effectiveAgentId(node, this.deps.agentIdOf)
if (!agentId || !hasHooks(agentId)) {
return {
ok: false,
error: `${verb}: --after ${id} is not an agent session that reports when it is done`
}
}
}
return ids
}
async openTerminal(
sourceNodeId: string,
args: Record<string, string>,
verified: boolean
): Promise<ServerControlReply> {
return this.open(sourceNodeId, 'open-terminal', args, verified)
}
/**
* Re-open one exact local project that is already present in the Server workspace and mint a
* process-local targeting grant for this verified caller. Server Edition still cannot create,
* add, rename, recolor, or focus projects: those operations require the browser UI's explicit
* confirmation. This narrow existing-only form is the restart recovery path for long-lived
* agent nodes whose tmux sessions survive the Server process.
*/
openProject(
sourceNodeId: string,
args: Record<string, string>,
verified: boolean
): Promise<ServerControlReply> {
return this.runExclusive(async () => {
const flagError = unsupportedFlags(args, new Set(['cwd']))
if (flagError) return { ok: false, error: `open-project: ${flagError}` }
if (!verified) {
return {
ok: false,
error: 'open-project-identity-refused: Server Edition open-project requires verified node identity'
}
}
const workspace = await this.loadForEdit()
const source = sourceProject(workspace, sourceNodeId)
if (!source) return { ok: false, error: 'source node is not in exactly one saved project' }
if (!sourceCanControl(source.node, this.deps.agentIdOf)) {
return { ok: false, error: 'source node is not a control-capable agent' }
}
if (source.project.ssh) {
return {
ok: false,
error: 'open-project-local-only: open-project is not available from an SSH project — do not retry'
}
}
const rawCwd = args.cwd ?? ''
if (!path.isAbsolute(rawCwd)) {
return {
ok: false,
error: 'open-project-cwd-invalid: --cwd must be an absolute path to an existing saved local project'
}
}
const cwd = path.resolve(rawCwd)
const target = workspace.projects.find(
(project) => !project.ssh && !!project.cwd && path.resolve(project.cwd) === cwd
)
if (!target) {
return {
ok: false,
error:
'open-project-server-existing-only: Server Edition can only re-open an exact saved ' +
'local project path; add the project in the UI first — do not retry this path'
}
}
if (!this.grantProject(sourceNodeId, target.id)) {
return {
ok: false,
error: 'open-project-grant-cap: this session already holds the maximum number of project grants'
}
}
return {
ok: true,
message: `re-opened saved local project ${target.id}; cross-project grant restored`,
result: {
projectId: target.id,
name: target.name,
cwd,
created: false,
serverExistingOnly: true
}
}
})
}
async openAgent(
sourceNodeId: string,
args: Record<string, string>,
verified: boolean
): Promise<ServerControlReply> {
return this.open(sourceNodeId, 'open-agent', args, verified)
}
/** File one run-history line under the issue card. Never throws: history is a record of work,
* and a failed append must not fail the open or close it describes. */
private async logRun(
projectId: string,
run: { nodeId: string; event: BoardLogEntry['event'] } | null
): Promise<void> {
if (!run || !this.deps.appendBoardLog) return
await this.deps.appendBoardLog(projectId, {
id: randomUUID(),
ts: (this.deps.now ?? Date.now)(),
author: RUN_LOG_AUTHOR,
nodeId: run.nodeId,
kind: 'event',
event: run.event
}).catch(() => false)
}
close(
sourceNodeId: string,
args: Record<string, string>,
verified: boolean
): Promise<ServerControlReply> {
return this.runExclusive(async () => {
const flagError = unsupportedFlags(args, new Set(['node']))
if (flagError) return { ok: false, error: `close: ${flagError}` }
if (!verified) {
return {
ok: false,
error: 'close-identity-refused: Server Edition close requires verified node identity'
}
}
const workspace = await this.loadForEdit()
const source = sourceProject(workspace, sourceNodeId)
if (!source) return { ok: false, error: 'source node is not in exactly one saved project' }
if (!sourceCanControl(source.node, this.deps.agentIdOf)) {
return { ok: false, error: 'source node is not a control-capable agent' }
}
const ids = [...new Set((args.node ?? '').split(',').map((id) => id.trim()).filter(Boolean))]
if (!ids.length) return { ok: false, error: 'close requires --node <id>' }
// Validate the WHOLE list before killing anything. A mixed owned/unowned request is one
// refusal, never a partial destructive success whose surviving ids the caller must guess.
const frameIds = new Set<string>()
for (const id of ids) {
const ownership = this.ownership.ownerOf(id)
if (!ownership || ownership.sourceNodeId !== sourceNodeId) {
return {
ok: false,
error: `close-not-owner: ${sourceNodeId} did not spawn ${id} during this server run`
}
}
const project = workspace.projects.find((candidate) => candidate.id === ownership.projectId)
const target = project?.nodes.find((node) => node.id === id)
if (target?.kind === 'group') {
const unownedChild = this.unownedMutation(
sourceNodeId,
project!.nodes.filter((node) => node.parentId === id).map((node) => node.id)
)
if (unownedChild) return this.ownershipRefusal('close', sourceNodeId, unownedChild)
frameIds.add(id)
}
}
// Each id's project, read NOW: a factory stopped while the panes die clears the ownership
// ledger, and the steps below must still know where each node lives.
const ownerProject = new Map(ids.map((id) => [id, this.ownership.ownerOf(id)!.projectId]))
// Kill terminal panes first: the durable canvas must never lose a session whose outcome is
// unknown. Frames have no PTY; closing one is the desktop `ungroup` transform followed by
// removal of the frame alone, regardless of who owns its members.
await Promise.all(
ids
.filter((id) => !frameIds.has(id))
.map((id) => this.deps.ptyManager.destroySession(null, id, { everySocket: true }))
)
// Run history first (it awaits), from the read the checks above used.
for (const id of ids) {
const projectId = ownerProject.get(id)!
const target = workspace.projects.find((p) => p.id === projectId)?.nodes.find((node) => node.id === id)
if (!target?.issueRef) continue
// A run ends when its node is CLOSED — never when a turn ends.
await this.logRun(projectId, runEndedEvent(target.issueRef, {
id: target.id,
title: target.title,
agentId: target.agentId,
agentSessionId: target.agentSessionId
}, { state: this.deps.stateOf(target.id) }))
}
// The kills and the history took time: the removals go onto a FRESH read, so an edit a
// teammate made meanwhile is never written back from the copy loaded before them. What
// changed (removals, promoted frame members, pruned edges) is cast by `castAndSave`.
const current = await this.loadForEdit()
const touched = new Set<string>()
for (const id of ids) {
const projectId = ownerProject.get(id)!
const project = current.projects.find((candidate) => candidate.id === projectId)
const target = project?.nodes.find((node) => node.id === id)
if (!project || !target) continue
if (target.kind === 'group') {
project.nodes = ungroupPersistedNodes(project.nodes, id).nodes
} else {
project.nodes = project.nodes.filter((node) => node.id !== id)
}
if (project.ropes) {
project.ropes = project.ropes.filter((edge) => edge.source !== id && edge.target !== id)
}
if (project.bridges) {
project.bridges = project.bridges.filter((edge) => edge.source !== id && edge.target !== id)
}
touched.add(project.id)
}
// A refused save (canvas control is stopping) removed nothing from the canvas: say so, rather
// than report a close whose nodes are still on disk.
const saved = touched.size ? await this.castAndSave(current) : true
if (saved && touched.size) await this.publishPersisted(touched)
for (const id of ids) {
this.ownership.forget(id)
this.attached.delete(id)
this.awaitingFirstWorking.delete(id)
}
if (!saved) {
return {
ok: false,
error:
`close-not-saved: the sessions of ${ids.join(', ')} were ended, but the canvas could not be ` +
'written (canvas control is stopping); the nodes stay on the canvas'
}
}
return {
ok: true,
message: `closed ${ids.length} owned node(s): ${ids.join(', ')}`,
result: { ids, id: ids[0] }
}
})
}
link(
sourceNodeId: string,
args: Record<string, string>,
verified: boolean
): Promise<ServerControlReply> {
return this.runExclusive(async () => {
const flagError = unsupportedFlags(args, new Set(['from', 'to', 'one-way']))
if (flagError) return { ok: false, error: `link: ${flagError}` }
if (!verified) {
return {
ok: false,
error: 'link-identity-refused: Server Edition link requires verified node identity'
}
}
const workspace = await this.loadForEdit()
const source = sourceProject(workspace, sourceNodeId)
if (!source) return { ok: false, error: 'source node is not in exactly one saved project' }
if (!sourceCanControl(source.node, this.deps.agentIdOf)) {
return { ok: false, error: 'source node is not a control-capable agent' }
}
const from = (args.from ?? sourceNodeId).trim()
const targets = (args.to ?? '').split(',').map((id) => id.trim()).filter(Boolean)
if (!targets.length) return { ok: false, error: 'link requires --to <id,id>' }
// An arbitrary `--from` is allowed, but every endpoint still belongs to the caller's one
// project. Refuse the whole request before appending anything if a named id resolves across
// that boundary (or ambiguously in more than one saved project).
for (const id of [from, ...targets]) {
const projects = nodeProjects(workspace, id)
if (projects.length && (projects.length !== 1 || projects[0].id !== source.project.id)) {
return {
ok: false,
error: `link-project-refused: ${id} is not exclusively in the caller's project; ${LINK_PROJECT_ONLY}`
}
}
}
const unowned = this.unownedMutation(sourceNodeId, [from, ...targets])
if (unowned) return this.ownershipRefusal('link', sourceNodeId, unowned)
const byId = new Map(source.project.nodes.map((node) => [node.id, node]))
if (!byId.has(from)) {
return { ok: false, error: `link: --from ${from}: ${LINK_ENDPOINT_NOT_FOUND}` }
}
const existing = [...(source.project.bridges ?? [])]
const plan = planBridges(
from,
targets,
(id) => {
const node = byId.get(id)
return node ? headlessLinkEndpoint(node, this.deps.agentIdOf) : null
},
existing,
// Valueless flag: the shim sends `arg.one-way=` (present, empty).
{ oneWay: 'one-way' in args }
)
if (!plan.edges.length) {
return {
ok: false,
error: `link: nothing linked — ${plan.skipped
.map((skipped) => `${skipped.id}: ${skipped.why}`)
.join('; ')}`
}
}
source.project.bridges = [...existing, ...plan.edges]
await this.castAndSave(workspace)
await this.publishPersisted([source.project.id])
const note = plan.skipped.length
? ` (skipped ${plan.skipped.map((skipped) => `${skipped.id}: ${skipped.why}`).join('; ')})`
: ''
return {
ok: true,
message: 'one-way' in args
? `linked one-way: ${from} reads ${plan.linked.join(', ')}${note}`
: `linked ${from} ↔ ${plan.linked.join(', ')}${note}`,
result: { from, linked: plan.linked, skipped: plan.skipped }
}
})
}
group(sourceNodeId: string, args: Record<string, string>): Promise<ServerControlReply> {
return this.runExclusive(async () => {
const flagError = unsupportedFlags(args, new Set(['nodes', 'label', 'color']))
if (flagError) return { ok: false, error: `group: ${flagError}` }
let color: NodeColor | undefined
if (args.color !== undefined) {
// Names and mixed-case hex resolve to the one canonical palette value; anything else is
// the same refusal as before. Only the resolved value is persisted.
color = resolveNodeColor(args.color)
if (color === undefined) return { ok: false, error: invalidNodeColorMessage() }
}
const workspace = await this.loadForEdit()
const source = sourceProject(workspace, sourceNodeId)
if (!source) return { ok: false, error: 'source node is not in exactly one saved project' }
if (!sourceCanControl(source.node, this.deps.agentIdOf)) {
return { ok: false, error: 'source node is not a control-capable agent' }
}
const ids = (args.nodes ?? '').split(',').map((id) => id.trim()).filter(Boolean)
const unowned = this.unownedMutation(sourceNodeId, ids)
if (unowned) return this.ownershipRefusal('group', sourceNodeId, unowned)
const resolvable = ids.filter((id) => source.project.nodes.some((node) => node.id === id))
if (!resolvable.length) {
return { ok: false, error: 'group: none of the given node ids exist' }
}
const grouped = groupPersistedNodes(
source.project.nodes,
resolvable,
source.project.nodes.filter((node) => node.kind === 'group').length,
args.label ? oneLine(args.label) : undefined,
color
)
if (!grouped) {
return {
ok: false,
error:
'group: nodes must be siblings in one container and may not include an ancestor with its descendant'
}
}
source.project.nodes = grouped.nodes
await this.castAndSave(workspace)
this.ownership.record(grouped.groupId, {
sourceNodeId,
projectId: source.project.id
})
await this.publishPersisted([source.project.id])
const skipped = ids.length - resolvable.length
const note = skipped ? ` (${skipped} unknown id(s) skipped)` : ''
return {
ok: true,
message: `grouped ${resolvable.length} node(s) into ${grouped.groupId}${note}`,
result: { groupId: grouped.groupId, grouped: resolvable, skipped }
}
})
}
rename(sourceNodeId: string, args: Record<string, string>): Promise<ServerControlReply> {
return this.runExclusive(async () => {
const flagError = unsupportedFlags(args, new Set(['node', 'title']))
if (flagError) return { ok: false, error: `rename: ${flagError}` }
const workspace = await this.loadForEdit()
const source = sourceProject(workspace, sourceNodeId)
if (!source) return { ok: false, error: 'source node is not in exactly one saved project' }
if (!sourceCanControl(source.node, this.deps.agentIdOf)) {
return { ok: false, error: 'source node is not a control-capable agent' }
}
const id = (args.node ?? '').trim()
const projects = nodeProjects(workspace, id)
if (projects.length && (projects.length !== 1 || projects[0].id !== source.project.id)) {
return {
ok: false,
error: `rename-project-refused: ${id} is not exclusively in the caller's project`
}
}
const target = source.project.nodes.find((node) => node.id === id)
if (!target) return { ok: false, error: `rename: no node with id ${id}` }
if (!this.ownsMutation(sourceNodeId, id)) {
return this.ownershipRefusal('rename', sourceNodeId, id)
}
const title = oneLine(args.title ?? '')
const renamed = { ...target, title, titleAuto: false }
source.project.nodes = source.project.nodes.map((node) =>
node.id === id ? renamed : node
)
await this.castAndSave(workspace)
// Metadata only. In particular, Server Edition never mirrors `/rename` into the pane.
await this.publishPersisted([source.project.id])
return { ok: true, message: `renamed ${id} to "${title}"` }
})
}
/** `run --node <id>` (#925): deliver a node's retained launch now. Server v1 ownership applies:
* only nodes the caller spawned during this server run. */
run(sourceNodeId: string, args: Record<string, string>, verified: boolean): Promise<ServerControlReply> {
return this.runExclusive(async () => {
if (!verified) {
return { ok: false, error: 'run-identity-refused: Server Edition canvas control requires verified node identity' }
}
const flagError = unsupportedFlags(args, new Set(['node', 'project']))
if (flagError) return { ok: false, error: `run: ${flagError}` }
const id = (args.node ?? '').trim()
if (!this.ownsSpawn(sourceNodeId, id)) return this.ownershipRefusal('run', sourceNodeId, id)
// Resolve through the ownership record, never by first id match: node ids repeat across
// projects (a committed project.json opened from a second folder), and `attach()` is keyed
// by id alone, so a stranger copy sorting first would be claimed while the owned session is
// typed into. `close` resolves the same way. A `--project` naming any other project is the
// desktop's lookup inside the named project coming up empty.
const owner = this.ownership.ownerOf(id)!
const noNode: ServerControlReply = { ok: false, error: `run: no node with id ${id}` }
if (args.project !== undefined && args.project !== owner.projectId) return noNode
const workspace = await this.loadForEdit()
const project = workspace.projects.find((p) => p.id === owner.projectId)
const node = project?.nodes.find((n) => n.id === id)
if (!project || !node) return noNode
const held = node.pendingLaunch
if (!held?.command) return { ok: false, error: `run-nothing-queued: ${id} has no queued launch` }
// A remote node is NEVER spawned locally, and this launcher only spawns locally. Refuse
// before the claim, leaving the held launch untouched (the desktop's startHeadless guard).
if (isRemoteSessionNode(node)) {
return {
ok: false,
error: `run-remote-unsupported: ${id} is an SSH node; the Server Edition cannot start it`
}
}
// Write-ahead, exactly as open() does before its own delivery. Nothing is started unless the
// claim landed: a refused save (canvas control is stopping) leaves the launch queued as it was.
node.pendingLaunch = { ...held, attempted: true, manualOnly: true }
if (!(await this.castAndSave(workspace))) {
return {
ok: false,
error: `run-not-saved: ${id} was not started: the canvas could not be written (canvas control is stopping); its launch stays queued`
}
}
const launched = await this.launch(project, node, held.command)
// As open() does: an agent this spawned fresh has not had its first real turn yet, so a
// later `--after` on it must not be released by the CLI's boot `done` blip.
if (node.agentId && launched.fresh) this.awaitingFirstWorking.add(id)
// The launch took time: only its outcome is written, onto a fresh read (`savePatches`).
await this.savePatches(launched.outcome === 'delivered' ? [clearLaunch(project.id, id, held.command)] : [])
await this.publishPersisted([project.id])
return launched.outcome === 'delivered'
? {
ok: true,
message: `started ${id}; agent startup is not confirmed`,
result: { ids: [id], id, started: true, startedIds: [id], queued: false, queuedIds: [] }
}
: {
ok: true,
message: `${id} stays queued (${launched.reason}); launch retained for Run now`,
result: { ids: [id], id, started: false, startedIds: [], queued: true, queuedIds: [id], reason: launched.reason }
}
})
}
color(sourceNodeId: string, args: Record<string, string>): Promise<ServerControlReply> {
return this.runExclusive(async () => {
const flagError = unsupportedFlags(args, new Set(['node', 'color']))
if (flagError) return { ok: false, error: `color: ${flagError}` }
const color = resolveNodeColor(args.color)
if (color === undefined) return { ok: false, error: invalidNodeColorMessage() }
const workspace = await this.loadForEdit()
const source = sourceProject(workspace, sourceNodeId)
if (!source) return { ok: false, error: 'source node is not in exactly one saved project' }
if (!sourceCanControl(source.node, this.deps.agentIdOf)) {
return { ok: false, error: 'source node is not a control-capable agent' }
}
const ids = [...new Set((args.node ?? '').split(',').map((id) => id.trim()).filter(Boolean))]
const unowned = this.unownedMutation(sourceNodeId, ids)
if (unowned) return this.ownershipRefusal('color', sourceNodeId, unowned)
const changed = ids
.map((id) => source.project.nodes.find((node) => node.id === id))
.filter((node): node is CanvasNodeState => !!node)
.map((node) => ({ ...node, color }))
if (!changed.length) {
return { ok: false, error: 'color: none of the given node ids exist in the caller project' }
}
const byId = new Map(changed.map((node) => [node.id, node]))
source.project.nodes = source.project.nodes.map((node) => byId.get(node.id) ?? node)
await this.castAndSave(workspace)
await this.publishPersisted([source.project.id])
const skipped = ids.length - changed.length
const note = skipped ? ` (${skipped} unknown id(s) skipped)` : ''
return {
ok: true,
message: `colored ${changed.length} node(s) ${color}${note}`,
result: { colored: changed.map((node) => node.id), skipped, color }
}
})
}
private open(
sourceNodeId: string,
verb: 'open-terminal' | 'open-agent',
args: Record<string, string>,
verified: boolean
): Promise<ServerControlReply> {
return this.runExclusive(async () => {
const flagError = unsupportedFlags(
args,
// `run-now` (#925) is a no-op, since a server open already delivers immediately; only its
// pairing with `--after` is refused, just below.
verb === 'open-terminal'
? new Set(['count', 'cwd', 'cmd', 'after', 'after-success', 'success-deadline', 'project', 'run-now'])
: new Set([
'agent',
'count',
'cwd',
'prompt',
'after',
'after-success',
'success-deadline',
'project',
'model',
'issue',
'run-now'
])
)
if (flagError) return { ok: false, error: `${verb}: ${flagError}` }
// "Start now" and "start when X is done" contradict each other: refused in the desktop's
// words, before anything is created, rather than silently opening an armed node.
if (runNowRequested(args) && args.after) return { ok: false, error: RUN_NOW_AFTER_REFUSAL }
if (runNowRequested(args) && args['after-success'] !== undefined) {
return { ok: false, error: RUN_NOW_AFTER_SUCCESS_REFUSAL }
}
// `--after-success` (@shared/station-outcome): the shape was checked in `parseControlRequest`;
// re-parsed here with the same grammar. The ids are folded into `after` — a success wait is
// `--after` plus the station's report — so the existence, status-reporting and creator checks
// below apply to them unchanged; the hold adds the report.
const successParsed =
args['after-success'] !== undefined ? parseAfterSuccessArg(args['after-success']) : undefined
if (successParsed && !successParsed.ok) return { ok: false, error: `${verb}: ${successParsed.error}` }
const successIds = successParsed?.ok ? successParsed.ids : []
const successDeadline = parseSuccessDeadlineArg(args['success-deadline'])
if (!successDeadline.ok) return { ok: false, error: `${verb}: ${successDeadline.error}` }
const afterArg = successIds.length
? [
...new Set([
...(args.after ?? '').split(',').map((id) => id.trim()).filter(Boolean),
...successIds
])
].join(',')
: args.after
if (!verified) {
return {
ok: false,
error: `${verb}-identity-refused: Server Edition ${verb} requires verified node identity`
}
}
const workspace = await this.loadForEdit()
const source = sourceProject(workspace, sourceNodeId)
if (!source) return { ok: false, error: 'source node is not in exactly one saved project' }
if (!sourceCanControl(source.node, this.deps.agentIdOf)) {
return { ok: false, error: 'source node is not a control-capable agent' }
}
const target = this.resolveTarget(workspace, source, verb, args, verified)
if ('ok' in target) return target
const after = this.resolveAfter(target, afterArg, verb)
if (!Array.isArray(after)) return after
const unownedAfter = this.unownedMutation(sourceNodeId, after)
if (unownedAfter) return this.ownershipRefusal(verb, sourceNodeId, unownedAfter)
// A success wait is only as good as the station's ability to REPORT: only an agent with canvas
// control has `report-outcome`, so waiting on anything else could only end at the deadline.
for (const depId of successIds) {
const dep = target.nodes.find((candidate) => candidate.id === depId)
if (!dep || !sourceCanControl(dep, this.deps.agentIdOf)) {
return { ok: false, error: successDepRefusal(verb, depId) }
}
}
const successHold: SuccessWaitHold | undefined = successIds.length
? { deps: successIds, deadlineAt: this.now() + successDeadline.ms }
: undefined
// `--issue`: resolved against the project the node OPENS IN, before anything is written. The
// shape gate already ran in `parseControlRequest`; this re-parses with the same grammar.
let issueRef: IssueRef | undefined
if (verb === 'open-agent' && args.issue !== undefined) {
const board = target.kanban?.github
const repository = board
? (await this.deps.issueRepository?.(target.id).catch(() => null)) ?? board.repository ?? null
: null
const issue = resolveIssueArg(args.issue, repository)
if (!issue.ok) return { ok: false, error: `open-agent: ${issue.error}` }
issueRef = issue.ref
}
const settings = this.deps.settings()
const nodeSize = terminalSize(settings)
const caps = verb === 'open-agent' ? await this.deps.cliCaps() : null
const grokCaps = verb === 'open-agent' ? await this.deps.grokCaps() : null
const agentId = args.agent as BuiltinAgentId | undefined
if (verb === 'open-agent' && (!agentId || !SERVER_AGENTS.has(agentId))) {
return {
ok: false,
error: 'open-agent: Server Edition v1 supports --agent claude|codex|gemini'
}
}
// The Server shell owns the same shared Codex app-server spine as desktop. Ask its boot-time
// capability probe at the launch boundary: true routes through `nodeterm-codex`; every
// unavailable/failed case stays on the safe bare command supplied by the shared assembler.
const codexSharedIdentity =
verb === 'open-agent' && agentId === 'codex'
? await this.deps.codexSharedIdentity().catch(() => false)
: false
// Which `--ask-for-approval` values this host's codex has. Asked only where it can matter,
// right beside the other codex question. Every failure answers `null` = unknown = the
// baseline vocabulary, which is the launch line this factory has always produced for Auto
// and Bypass; only `untrusted` (gone since 0.149.0) depends on a real answer.
const codexCaps =
verb === 'open-agent' && agentId === 'codex'
? await this.deps.codexCaps().catch(() => UNKNOWN_CODEX_CLI_CAPS)
: UNKNOWN_CODEX_CLI_CAPS
const count = parseCount(args.count, verb === 'open-terminal' ? TERMINAL_LIMIT : AGENT_LIMIT)
const created: CanvasNodeState[] = []
const commands = new Map<string, string>()
const ropes = [...(target.ropes ?? [])]
const bridges = [...(target.bridges ?? [])]
const startIndex = target.nodes.length
const cwd = args.cwd || (target.id === source.project.id ? source.node.cwd : undefined) || target.cwd
// Snapshot dependency state at the arm boundary. A `working` state is already positive
// evidence that this fresh process made it through its boot composer; a later `done` may
// release it. An unknown/waiting fresh spawn needs a working event after this snapshot.
const afterStates = new Map(after.map((depId) => [depId, this.deps.stateOf(depId)]))
for (const [depId, state] of afterStates) {
if (state === 'working') this.awaitingFirstWorking.delete(depId)
}
const mustWait =
// A `done` from before new work was handed over is not this wait's `done`
// (core/station-handover.ts): the creation shortcut must not start the node on it.
after.some((depId) => afterStates.get(depId) !== 'done' || this.handedOver(depId)) ||
(!!successHold &&
!successWaitSatisfied(successHold, (d) => this.successFacts(target, d), this.now()))
const awaitWorking = after.filter((depId) =>
afterStates.get(depId) !== 'done' &&
afterStates.get(depId) !== 'working' &&
this.awaitingFirstWorking.has(depId)
)
for (let i = 0; i < count; i++) {
let command = args.cmd
let title = `Terminal ${startIndex + i + 1}`
let color: string = SYSTEM_NODE_COLORS[(startIndex + i) % SYSTEM_NODE_COLORS.length]
let mintedSessionId: string | undefined
let permissionMode
if (verb === 'open-agent') {
const config = AGENT_CONFIG[agentId as BuiltinAgentId]
title = config.label
color = config.color
const resolvedMode = resolvePermissionMode(target, settings)
permissionMode = agentId === 'claude'
? gatePermissionMode(resolvedMode, caps?.autoPermissionMode === true)
: resolvedMode
const sessionIdFlagSupported = supportsSessionIdFlag(
agentId as AgentId,
caps?.sessionIdFlag === true,
grokCaps?.sessionIdFlag === true
)
mintedSessionId = sessionIdFlagSupported ? randomUUID() : undefined
command = assembleLaunchCommand(
{
agentId: agentId as AgentId,
// An issue-bound session's first prompt is the REFERENCE line, never the issue's text.
initialPrompt: issueRef ? issueLaunchPrompt(issueRef, args.prompt) : args.prompt,
permissionMode,
sessionId: mintedSessionId,
sessionIdFlagSupported,
launchCmdOverride: settings.agentLaunchCommands?.[agentId as BuiltinAgentId],
sharedIdentity: codexSharedIdentity,
approvalCaps: {
codexApprovalValues: codexCaps.approvalValues,
codexNoDaemon: codexCaps.noDaemon ?? null
},
model: args.model
},
this.deps.env ?? process.env
).command
}
const id = nextId('term')
// Persist before attempting delivery, including launches whose gates are already open.
// A failed attach/send must leave the command available to the user's Run now action.
const pendingLaunch = command
? {
after,
command,
executor: 'server' as const,
attempted: !mustWait,
...(!mustWait ? { manualOnly: true } : {}),
...(awaitWorking.length ? { awaitWorking: [...awaitWorking] } : {}),
...(successHold ? { afterSuccess: successHold } : {})
}
: undefined
// The opener's account, when the new agent's PROVIDER owns it. The node carries one
// `accountId` for either builtin, so a Claude opener used to hand its Claude account id to
// a Codex node, which the Codex scope gate then refused at spawn (issue #1423).
const inheritedAccountId =
verb === 'open-agent'
? ownedAccountId(source.node.accountId, agentId, (accountId) =>
(settings.codexAccounts ?? []).some((a) => a.id === accountId)
)
: undefined
const node: CanvasNodeState = {
id,
kind: 'terminal',
position: placeRight(target, source.node, nodeSize, created),
size: { ...nodeSize },
title,
...(verb === 'open-agent' ? { titleAuto: true } : {}),
color,
group: null,
tags: [],
cwd,
...(verb === 'open-agent' ? { agentId: agentId as AgentId } : {}),
...(args.model && verb === 'open-agent' ? { agentModel: args.model } : {}),
...(issueRef && verb === 'open-agent' ? { issueRef } : {}),
...(mintedSessionId ? { agentSessionId: mintedSessionId } : {}),
...(inheritedAccountId ? { accountId: inheritedAccountId } : {}),
...(pendingLaunch ? { pendingLaunch } : {})
}
created.push(node)
if (command && !mustWait) commands.set(id, command)
addEdge(ropes, source.node.id, id, 'ctrl')
if (verb === 'open-agent') {
const sourceAgent = effectiveAgentId(source.node, this.deps.agentIdOf)
if (sourceAgent && canContextLink(sourceAgent) && canContextLink(agentId as AgentId)) {
addEdge(bridges, source.node.id, id, 'link')
}
for (const depId of after) {
const dep = target.nodes.find((candidate) => candidate.id === depId)
const depAgent = dep ? effectiveAgentId(dep, this.deps.agentIdOf) : undefined
if (depAgent && canContextLink(depAgent) && canContextLink(agentId as AgentId))
addEdge(bridges, id, depId, 'link')
}
}
}
target.nodes.push(...created)
target.ropes = ropes
target.bridges = bridges
// Creation is written BEFORE anything is launched, and a refused save (canvas control is
// stopping) is a failure here: a launch into a node that is not on the canvas is an orphan
// agent session nobody can see.
if (!(await this.castAndSave(workspace))) {
return {
ok: false,
error: `${verb}-not-saved: nothing was opened: the canvas could not be written (canvas control is stopping)`
}
}
for (const node of created) {
this.ownership.record(node.id, { sourceNodeId, projectId: target.id })
}
await this.publishPersisted([target.id])
if (issueRef) {
for (const node of created) {
await this.logRun(target.id, runStartedEvent(issueRef, {
id: node.id,
title: node.title,
agentId: node.agentId,
agentSessionId: node.agentSessionId
}))
}
}
const failed: string[] = []
// Why each one failed, reported per id (#925): a reply that says only "retained for Run now"
// hides the reason Run now would repeat (`line-too-long`).
const reasons: Record<string, HeadlessLaunchFailure> = {}
const fail = (id: string, reason: HeadlessLaunchFailure): void => {
failed.push(id)
reasons[id] = reason
}
for (const node of created) {
try {
const command = commands.get(node.id)
if (!command) {
// Nothing to deliver now (a plain terminal, or a launch held for `--after`): spawn only.
const result = await this.attach(target, node)
if (!result.sessionId) fail(node.id, 'spawn-failed')
else if (verb === 'open-agent' && result.fresh) this.awaitingFirstWorking.add(node.id)
continue
}
const launched = await this.launch(target, node, command)
if (verb === 'open-agent' && launched.fresh) this.awaitingFirstWorking.add(node.id)
if (launched.outcome === 'delivered') node.pendingLaunch = undefined
else fail(node.id, launched.reason)
} catch {
// The launcher answers its own failures; only the spawn-only `attach` above throws.
fail(node.id, 'spawn-failed')
}
}
// Creation and delivery are separate transactions. A refused/throwing send retains the
// exact command for the user's Run now action; boot still cannot adopt persisted nodes.
// The launches took time, so their outcomes are written onto a fresh read, never this copy.
const outcomes: NodePatch[] = []
for (const node of created) {
const command = commands.get(node.id)
if (failed.includes(node.id) && node.pendingLaunch) {
node.pendingLaunch.manualOnly = true
outcomes.push(claimLaunch(target.id, node.id, node.pendingLaunch.command, false))
} else if (command && !node.pendingLaunch) {
outcomes.push(clearLaunch(target.id, node.id, command))
}
}
await this.savePatches(outcomes)
await this.publishPersisted([target.id])
const ids = created.map((node) => node.id)
const queuedIds = created
.filter((node) => node.pendingLaunch && !failed.includes(node.id))
.map((node) => node.id)
const deliveredIds = created
.filter((node) => commands.has(node.id) && !node.pendingLaunch && !failed.includes(node.id))
.map((node) => node.id)
const launchResult = { queued: queuedIds.length > 0, queuedIds, deliveredIds, failed }
if (failed.length) {
return {
ok: false,
error: launchFailedError(
created
.filter((node) => failed.includes(node.id))
.map((node) => ({ id: node.id, reason: reasons[node.id], retained: !!node.pendingLaunch })),
verb
),
result: { ids, id: ids[0], after, ...launchResult, reasons, ...(successHold ? { afterSuccess: successHold.deps } : {}) }
}
}
return {
ok: true,
message:
`opened ${count} ${verb === 'open-agent' ? `${agentId} session` : 'terminal'}(s): ` +
ids.join(', ') +
(queuedIds.length ? `; queued: ${queuedIds.join(', ')}` : '') +
(deliveredIds.length ? '; launch delivered; agent startup is not confirmed' : '') +
(successHold ? `; waits for a reported success from: ${successHold.deps.join(', ')}` : ''),
result: {
ids,
id: ids[0],
after,
...launchResult,
...(issueRef ? { issue: `${issueRef.owner}/${issueRef.repo}#${issueRef.number}` } : {}),
...(successHold ? { afterSuccess: successHold.deps } : {})
}
}
})
}
sticky(sourceNodeId: string, args: Record<string, string>): Promise<ServerControlReply> {
return this.runExclusive(async () => {
const parsed = parseStickyArgs(args)
if ('error' in parsed) return { ok: false, error: `sticky: ${parsed.error}` }
const workspace = await this.loadForEdit()
const source = sourceProject(workspace, sourceNodeId)
if (!source) return { ok: false, error: 'source node is not in exactly one saved project' }
if (!sourceCanControl(source.node, this.deps.agentIdOf)) {
return { ok: false, error: 'source node is not a control-capable agent' }
}
const candidates = source.project.nodes.map((node) => ({
id: node.id,
sticky: node.kind === 'sticky',
title: node.title
}))
const resolved = resolveStickyRef(candidates, parsed.ref)
if ('error' in resolved) return { ok: false, error: `sticky: ${resolved.error}` }
let node: CanvasNodeState | undefined
let created = false
if ('id' in resolved) node = source.project.nodes.find((candidate) => candidate.id === resolved.id)
else if (parsed.create) {
created = true
const stickySize = resolveDefaultNodeSize(
this.deps.settings().defaultNodeSizes?.sticky,
STICKY_NODE_SIZE,
STICKY_NODE_MIN_SIZE
)
node = {
id: nextId('sticky'),
kind: 'sticky',
position: placeRight(source.project, source.node, stickySize),
size: stickySize,
title: oneLine(parsed.ref) || 'Note',
color: '#ffd60a',
group: null,
text: ''
}
source.project.nodes.push(node)
const ropes = [...(source.project.ropes ?? [])]
addEdge(ropes, source.node.id, node.id, 'ctrl')
source.project.ropes = ropes
} else {
return {
ok: false,
error: `sticky: no note named "${parsed.ref}"; pass --create yes to create it`
}
}
if (!node) return { ok: false, error: 'sticky: note disappeared while resolving it' }
if (!created && !this.ownsMutation(sourceNodeId, node.id)) {
return this.ownershipRefusal('sticky', sourceNodeId, node.id)
}
const write = applyStickyWrite(node.text ?? '', parsed.write)
if ('error' in write) return { ok: false, error: `sticky: ${write.error}` }
node.text = write.text
node.textUpdatedAt = (this.deps.now ?? Date.now)()
node.textUpdatedBy = source.node.title || source.node.id
await this.castAndSave(workspace)
if (created) {
this.ownership.record(node.id, { sourceNodeId, projectId: source.project.id })
}
await this.publishPersisted([source.project.id])
return {
ok: true,
message: `${created ? 'created' : 'updated'} sticky ${node.id} (${write.mode})`,
result: { id: node.id, created, mode: write.mode }
}
})
}
/**
* Boot is intentionally inert. Creator proof is process-local and empty after restart, so even
* sending a persisted command would control a session this process cannot attribute. Owner opens
* and browser views are the only cold-spawn authority; current-run agent events drive arms below.
*/
start(): Promise<void> {
return Promise.resolve()
}
onAgentEvent(event: Pick<NormalizedAgentEvent, 'nodeId' | 'state' | 'errored' | 'newTurn'>): void {
if (this.stopped || !event?.nodeId) return
if (event.state === 'done' && event.errored === true) this.lastTurnErrored.add(event.nodeId)
else if (event.newTurn === true) this.lastTurnErrored.delete(event.nodeId)
if (event.state === 'working') this.awaitingFirstWorking.delete(event.nodeId)
if (event.state === 'working' || event.state === 'done') void this.refreshArmed(event)
}
refreshArmed(observed?: Pick<NormalizedAgentEvent, 'nodeId' | 'state'>): Promise<void> {
return this.runExclusive(async () => {
if (this.stopped) return
// A READ-ONLY look: every working/done hook event lands here, and most find nothing armed or
// nothing ready. Nothing is copied or saved until an arm actually moves; then each save goes
// through `savePatches`, a fresh read with only this pass's own patches re-applied, because a
// delivery below can take seconds and must never write back the view it started from.
const view = await this.readWorkspace()
const patches: NodePatch[] = []
const changedProjects = new Set<string>()
let unsaved = false
const patch = (p: NodePatch): void => {
patches.push(p)
changedProjects.add(p.projectId)
unsaved = true
}
for (const project of view.projects) {
for (const node of project.nodes) {
const pending = node.pendingLaunch
if (!pending || pending.executor !== 'server' || !pending.command || pending.manualOnly) continue
// A persisted arm surviving a restart is data, not creator proof. Only a node freshly
// spawned for this caller during the current run may receive automatic input.
if (!this.ownership.ownerOf(node.id)) continue
const command = pending.command
let awaitWorking = pending.awaitWorking
if (observed?.state === 'working' && awaitWorking?.includes(observed.nodeId)) {
const depId = observed.nodeId
const rest = awaitWorking.filter((id) => id !== depId)
awaitWorking = rest.length ? rest : undefined
// Persist the evidence even if the dependent PTY is temporarily unavailable. Losing
// this mutation would strand the arm when the next event is the legitimate `done`.
patch(dropAwaitWorking(project.id, node.id, command, depId))
}
for (const depId of awaitWorking ?? []) {
if (!(observed?.state === 'working' && observed.nodeId === depId))
this.awaitingFirstWorking.add(depId)
}
const ready = pending.after.every((depId) => {
const stillExists = project.nodes.some((candidate) => candidate.id === depId)
if (!stillExists) return true
if (awaitWorking?.includes(depId)) return false
if (this.handedOver(depId)) return false
return observed?.nodeId === depId
? observed.state === 'done'
: this.deps.stateOf(depId) === 'done'
})
if (!ready) continue
// `--after-success`: every named station also REPORTED success. The persisted hold is
// hand-editable input, so it is re-validated here — a malformed one never fires.
const successHold = normalizeSuccessWaitHold(pending.afterSuccess)
if (
successHold &&
!successWaitSatisfied(
successHold,
(d) => this.successFacts(project, d, observed),
this.now()
)
)
continue
// `sessionExists` is a probe, whereas `createHeadless` is attach-or-create. Never call
// the latter from boot/event reconciliation: a dead node stays dormant until its owner
// explicitly opens it or a user views it. A probe failure also stays dormant because an
// unreadable backend is not proof that delivery is safe.
const live = this.attached.has(node.id) ||
await this.deps.ptyManager.sessionExists(node.id).catch(() => false)
if (!live) continue
// Persist the attempt BEFORE input. A failed/uncertain send (or a crash before its
// acknowledgement save) must never be replayed by an unrelated hook.
patch(claimLaunch(project.id, node.id, command, true))
const claim = await this.savePatches(patches)
unsaved = false
// Type ONLY what this pass claimed on disk: the save landed (a stopping factory refuses it)
// and the claim applied to the fresh read (a teammate may have deleted the node, re-armed it
// with another command, or claimed it, since the look above).
if (!claim.saved || !claim.applied[patches.length - 1]) continue
if (!isLaunchShell(await this.deps.ptyManager.paneCommand(node.id).catch(() => null))) continue
if ((await this.deps.ptyManager.sendText(node.id, command).catch(() => false)) !== true) continue
patch(clearLaunch(project.id, node.id, command))
}
}
// A working event is definitive for every pending launch in this transaction. Keep the
// process-local fresh-spawn index aligned even when several arms named the same dependency.
if (observed?.state === 'working') this.awaitingFirstWorking.delete(observed.nodeId)
if (unsaved) await this.savePatches(patches)
if (changedProjects.size) await this.publishPersisted(changedProjects)
})
}
stop(): void {
this.stopped = true
this.ownership.clear()
this.projectGrants.clear()
}
}