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 { isSafeNodeId } from '../remote-safety'
import type { NotPermittedReason } from './agent-message-decide'
/**
* WHO MAY BE ADDRESSED — the project boundary, resolved off the SERIALIZED store.
*
* A message crosses into another agent's session, so the question "is this target mine to write
* to?" has to be answered before anything else happens, and it has to be answered from a source of
* truth that covers every project rather than the one that happens to be on screen.
*
* ── WHY THE SERIALIZED STORE AND NOT THE LIVE CANVAS ────────────────────────────────────────────
*
* React Flow only ever holds the ACTIVE project's nodes (`nodesRef`), while the tmux sessions of
* every other open project keep running. Resolving a target against `nodesRef` therefore answers
* "not on the canvas" for every node outside the current tab — the same defect `routeControlSource`
* exists to fix on the source side, where it surfaced as a lost capability rather than as the wrong
* canvas answering.
*
* Nor is the fix to travel to the target's project, and THIS resolver is what makes that
* impossible: it takes the projects store and NOTHING else. There is no parameter for a live node
* list, so there is nothing to travel toward — a guarantee a test can check by running it, since a
* node the live canvas has but the store has not is refused rather than admitted.
*
* `needsLiveCanvas` is a different guarantee and must not be confused with this one: Canvas routes
* by SOURCE (`routeControlSource(projects, activeId, sourceNodeId)`), so declaring `send`/`reply`
* store-answered stops a travel to the SENDER's project — the one an off-canvas orchestrator would
* otherwise trigger on every message it sent. Both matter, for different halves of the pair, and
* either alone would leave a way for a background agent to yank the human's view and clear an
* unread badge on the way (G5).
*
* ── THREE SURFACES ──────────────────────────────────────────────────────────────────────────────
*
* - **Desktop (Electron):** the caller. It passes `useProjects.getState().projects`, the same
* serialized array `routeControlSource` and `storedNodeListing` already read.
* - **Server Edition:** ships, unused — messaging does not exist there (Task 5.3). Pure, with no
* electron or main-shell import, so it ships on both shells like everything else in `src/core`.
* - **Mobile (phone):** never a sender, so it never calls this. A phone-spawned node IS a valid
* target and is resolved exactly like any other: it is a node id in a persisted project.
*
* ── WHICH WAY IT FAILS ──────────────────────────────────────────────────────────────────────────
*
* CLOSED, because the thing being authorised is a write into someone else's terminal. Anything this
* cannot positively resolve to a single shared project is refused: an id outside `isSafeNodeId`, a
* source that belongs to no project the store knows, a target that resolves nowhere, a target in a
* project the store has but the sender does not share. `notPermitted` is not retryable, so a
* refusal here is terminal — which is correct for a boundary and would be wrong for a timing
* problem, and none of these are timing problems.
*/
/** The little this needs from a project — a structural subset of both `Project` and the store's
* serialized `ProjectFileV1`, so either can be passed without adaptation.
*
* `nodes` is required rather than optional on purpose, and the caller owns that: a synthesised
* array with `nodes` absent throws here instead of failing closed. Every real `Project` has it. */
export interface ScopeProject {
id: string
nodes: readonly { id: string }[]
}
export type ScopeRefusal = Extract<
NotPermittedReason,
'self-send' | 'cross-project' | 'unaddressable-node-id' | 'ambiguous-target-node-id'
>
export type DeliveryScope =
/** `projectId` is the target pane's UNIQUE owning project (which the sender provably shares) —
* the project whose `agentMessaging` grant authorizes the delivery. Uniqueness is part of the
* contract: a target id claimed by two projects never produces this arm. */
| { kind: 'same-project'; projectId: string }
| {
kind: 'refused'
reason: ScopeRefusal
/** Does this target id exist in ANY project the store knows? `false` separates "aimed at
* another project" from "aimed at nothing" — the same refusal, but only one of them is
* worth telling a human about. */
targetFound: boolean
}
/**
* Resolve a (source, target) pair to the project they share, or to the refusal that stops it.
*
* ── THE ID ITSELF IS CHECKED FIRST, AND NOTHING ELSE ON THIS PATH DOES IT ───────────────────────
*
* Node ids come out of `.nodeterm/project.json` and `fileToProject` validates NOTHING — the repo
* says so at `node-identity-policy.ts:128` and `hook-server.ts:282`. `isSafeNodeId` exists and is
* applied at `PtyManager.create()`, which is not the load path this resolver reads. Two concrete
* consequences, and both are why the check is here rather than deeper:
*
* - **The pair limiter's key stops being injective.** Its separator is a NUL, so an id CONTAINING
* one collides two different conversations and each throttles the other (`agent-message-flow.ts`
* spells out the shape). `isSafeNodeId`'s charset — `[A-Za-z0-9._-]` — is exactly what makes
* that impossible.
* - **tmux session names FOLD.** `sessionName()` sanitises rather than refuses, so declared ids
* `v/1` and `v_1` name ONE session. An id that cannot be sanitised into a different node's
* session is the only kind worth admitting.
*
* Refused as `unaddressable-node-id`, not as `cross-project`: such an id may be listed in the
* sender's own project, so the scope word would be a false statement about why it was refused.
*
* `self-send` is the same rule, in the same words, that the manual `onConnect` already applies to a
* canvas edge — a node may not be wired to itself. It is decided before project membership because
* it is true regardless of where either id lives, including when neither lives anywhere.
*
* Note that this is the OUTER guard, not the only one: `decidePreProbe` carries its own self-send
* backstop so that no future caller can forget this one. Both produce the identical
* `notPermitted{reason:'self-send'}`, which the test asserts by running them.
*
* ── A DUPLICATE TARGET ID IS REFUSED, NOT DISAMBIGUATED ─────────────────────────────────────────
*
* A session's only key is the bare node id (`PtyManager.byPersistKey`, `paneOwner(persistKey)`,
* tmux `nt-<nodeId>`); no project id appears anywhere in that namespace and nothing de-duplicates
* ids when a second project carrying them is opened (a cloned `project.json` — this repo has
* shipped that bug once). So a duplicate id across projects is ONE global pane with several
* claimed owners, and the messaging grant is PER PROJECT: a hostile file for granted project A
* that merely LISTS ungranted project B's node id would resolve "same-project" to A by node-set
* membership, pass A's switch, and land in B's running pane — the confused deputy PR #237's
* review proved by execution (I-1), live from the moment the user keeps A's clone notice.
*
* Therefore: the grant must gate the project that OWNS the target pane, and when the target id
* appears in more than one persisted project no single owner can be proved, so the pair is
* refused as `ambiguous-target-node-id` — never "pick the sender's". A unique target's owning
* project is by construction the same project the sender shares, which is what `projectId` names.
* The cost falls only on stores that already carry duplicate ids, which the id-repair path
* (re-adding a folder mints fresh ids) exists to fix.
*
* **PR 5's delivery call must run `isSafeNodeId(targetNodeId)` before `paneOwner`** — a direct
* caller that skips this resolver gets neither that guard nor this one.
*
* `closed` and `unavailable` projects are deliberately NOT filtered out. A closed project's tmux
* sessions keep running and are re-adopted on the next start — that is the whole premise of
* `routeControlSource` — and a delivery goes to a pane, not to a canvas. Filtering them would
* refuse a perfectly deliverable message on the grounds that a tab is shut.
*/
export function resolveDeliveryScope(
projects: readonly ScopeProject[],
sourceNodeId: string,
targetNodeId: string
): DeliveryScope {
const has = (p: ScopeProject, id: string): boolean => p.nodes.some((n) => n.id === id)
// Every project claiming the target id — the pane's POSSIBLE owners. The grant is evaluated
// against the pane's owning project, so this set deciding the answer is the point, not a detail.
const targetOwners = projects.filter((p) => has(p, targetNodeId))
const targetFound = targetOwners.length > 0
if (!isSafeNodeId(sourceNodeId) || !isSafeNodeId(targetNodeId))
return { kind: 'refused', reason: 'unaddressable-node-id', targetFound }
if (sourceNodeId === targetNodeId) return { kind: 'refused', reason: 'self-send', targetFound }
const owner = projects.find((p) => has(p, sourceNodeId))
if (owner && has(owner, targetNodeId)) {
// The id names panes in more than one project: ONE global tmux pane, several claimed owners,
// and the sender's grant must not speak for the others (PR #237 review I-1). Refused with its
// own word — "pick the sender's project" was exactly the confused-deputy hole.
if (targetOwners.length > 1)
return { kind: 'refused', reason: 'ambiguous-target-node-id', targetFound: true }
// Unique: the target's owning project, which the sender provably shares.
return { kind: 'same-project', projectId: targetOwners[0].id }
}
return { kind: 'refused', reason: 'cross-project', targetFound }
}
/** The `notPermitted` fact `decideDelivery` takes, or `undefined` when the pair may proceed.
* Keeping the mapping here means a caller cannot invent a third answer. */
export function scopeRefusal(scope: DeliveryScope): NotPermittedReason | undefined {
return scope.kind === 'refused' ? scope.reason : undefined
}
/**
* WHO A BOARD COMMENT MAY ADDRESS — sessions on the comment's own board, resolved off the same
* serialized store as `resolveDeliveryScope`.
*
* A board comment has no sender node (a person wrote it), so "the project the sender shares with the
* target" becomes "the project whose board the comment is on". Every other rule is the agent path's,
* for the same reasons: an unaddressable id is refused by its own word, a target id claimed by more
* than one project is refused as ambiguous (one global pane, several claimed owners — the per-project
* grant cannot be attributed), and a target that is not on this board is `cross-project` whether it
* is on another board or on none. `projectId` comes from the local renderer; it only NAMES the board,
* and the delivery still has to prove at runtime that this project spawned the target's pane.
*/
export function resolveBoardCommentScope(
projects: readonly ScopeProject[],
projectId: string,
targetNodeId: string
): DeliveryScope {
const has = (p: ScopeProject, id: string): boolean => p.nodes.some((n) => n.id === id)
const targetOwners = projects.filter((p) => has(p, targetNodeId))
const targetFound = targetOwners.length > 0
if (!isSafeNodeId(targetNodeId))
return { kind: 'refused', reason: 'unaddressable-node-id', targetFound }
if (!targetOwners.some((p) => p.id === projectId))
return { kind: 'refused', reason: 'cross-project', targetFound }
if (targetOwners.length > 1)
return { kind: 'refused', reason: 'ambiguous-target-node-id', targetFound: true }
return { kind: 'same-project', projectId }
}