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
fix(link): explain project-scoped endpoint refusals
review659abcdbe1d3
diff --git a/CLAUDE.md b/CLAUDE.mdindex f108819c7..0cd23aa40 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -2498,6 +2498,8 @@ else, and its context links must keep classifying across restarts).would inject a prompt into every session an agent just spawned — the exact intrusion that pushwas reverted for. Links are pull-based, so nothing is lost. The refusal matrix is the pure`planBridges` (`renderer/lib/noteLink.ts`, unit-tested); Canvas only wraps it in setState.+ A missing endpoint is only absent from the calling project: report that scope and the+ unsupported cross-project boundary, without probing other projects or exposing their metadata.Callers that create and link nodes **in the same tick** must pass their own `lookup` — `setNodes`is async, so resolving fresh nodes off `nodesRef` would skip every one as "no such node".**Dependency edges (`--after`, 2026-07):** `open-terminal`/`open-claude`/`open-agent` acceptdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 0223794bd..1b6b285ba 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -301,6 +301,10 @@ lane unaffected.These are the ones that come up in review most often. Each exists because its absence caused a realbug.+**A project-scoped lookup cannot prove a node does not exist elsewhere.** Link refusals must+name the project boundary and explain that cross-project linking is unsupported; do not scan other+projects just to improve a missing-endpoint diagnostic.+**A failed read is never evidence of absence.** "Could not measure" and "there is nothing" aredifferent facts and must stay distinguishable at every layer. Collapsing them is how a panel ends upreporting "no sessions" on a host running thirty. When something ACTS on the negative, give it threediff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.tsindex 61d41670b..ff95d495e 100644--- a/src/core/canvas-control-core.ts+++ b/src/core/canvas-control-core.ts@@ -1,3 +1,4 @@+import { LINK_ENDPOINT_NOT_FOUND } from '../shared/canvas-link'// Pure core for agent canvas control: the verb model, request validation, and the standalone// CLI source. No electron imports, so this module + CONTROL_CLI_SCRIPT are unit-testable.// Electron/ipc/server wiring lives in canvas-control.ts + index.ts + hook-server.ts.@@ -504,6 +505,8 @@ export function buildCanvasControlInstructions(shimPath: string): string {' on demand (nodeterm linked-context CLI). `--from` defaults to you; nothing is pushed into the',' linked sessions. Agent sessions you open, and the stations you name in `--after`, are already',' linked — nothing to `link`. Use `link` only for nodes you did not open, or to link two OTHER nodes.',+ ` Both endpoints must be in your project. A missing endpoint reports: ${LINK_ENDPOINT_NOT_FOUND}.`,+ ' This does not reveal whether the id exists in another project.',' On Server Edition the ownership rule is stricter: every endpoint must be a node you opened',' during this server run.','- `verify --node <id> [--lenses correctness,security,tests] [--focus "..."] [--synthesis off]` — open a',@@ -995,6 +998,8 @@ Verbs:Agent sessions you open (\`open-claude\`/\`open-agent\`/\`spawn-team\`) and the stations you name in\`--after\` are already linked — nothing to \`link\`. Use \`link\` only for nodes you did not open,or to link two OTHER nodes together.+ Both endpoints must be in your project. A missing endpoint reports: ${LINK_ENDPOINT_NOT_FOUND}.+ This does not reveal whether the id exists in another project.On Server Edition the ownership rule is stricter: every endpoint must be a node you openedduring this server run.- \`verify --node <id> [--lenses correctness,security,tests] [--focus "..."] [--agent <id>] [--synthesis off] [--label L]\` —diff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.tsindex ab352d29c..827ca3ebf 100644--- a/src/main/canvas-control-core.test.ts+++ b/src/main/canvas-control-core.test.ts@@ -972,3 +972,12 @@ describe('the --project clause tells the truth about travel (review #363 I-1 + Mfor (const v of answered) expect(offScreenDisposition(v).kind, v).not.toBe('refuse')})})++describe('link project boundary guidance', () => {+ it('explains the scoped refusal in both generated agent instructions', () => {+ for (const body of [buildCanvasControlInstructions('/shim'), buildCanvasSkillBody('/shim')]) {+ expect(body).toContain('node not found in this project; cross-project linking is not supported')+ expect(body).toContain('This does not reveal whether the id exists in another project.')+ }+ })+})diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex 9cbed6b7a..db275cb6d 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -1,3 +1,4 @@+import { LINK_ENDPOINT_NOT_FOUND } from '@shared/canvas-link'import { useCallback, useEffect, useMemo, useRef, useState } from 'react'import { useShallow } from 'zustand/react/shallow'import { playSfx, primeSfx } from '@renderer/lib/sfx'@@ -11203,7 +11204,7 @@ export function Canvas() {return}if (!ctlLinkEndpointOf(from)) {- reply({ ok: false, error: `link: --from names no existing node (${from})` })+ reply({ ok: false, error: `link: --from ${from}: ${LINK_ENDPOINT_NOT_FOUND}` })return}const { linked, skipped } = bridgeTo(from, targets)diff --git a/src/renderer/lib/noteLink.test.ts b/src/renderer/lib/noteLink.test.tsindex 6e800d3c4..99878240e 100644--- a/src/renderer/lib/noteLink.test.ts+++ b/src/renderer/lib/noteLink.test.ts@@ -67,7 +67,21 @@ describe('planBridges', () => {expect(plan.edges).toEqual([])expect(plan.skipped).toEqual([{ id: 'n1', why: 'same node' },- { id: 'ghost', why: 'no such node' }+ { id: 'ghost', why: 'node not found in this project; cross-project linking is not supported' }+ ])+ })++ it('refuses an outside-project id without claiming it does not exist or granting a link', () => {+ // The target is known to the caller (e.g. returned by open-agent --project), but lookup+ // is deliberately scoped to the calling project, for both live and stored canvases.+ const projects = { caller: canvas, elsewhere: { remote: term(true) } }+ const plan = planBridges('n1', ['remote', 'ghost', 'n2'],+ (id) => projects.caller[id] ?? null, [])+ expect(plan.linked).toEqual(['n2'])+ expect(plan.edges).toEqual([{ id: 'bridge-n1-n2', source: 'n1', target: 'n2' }])+ expect(plan.skipped).toEqual([+ { id: 'remote', why: 'node not found in this project; cross-project linking is not supported' },+ { id: 'ghost', why: 'node not found in this project; cross-project linking is not supported' }])})@@ -93,7 +107,7 @@ describe('planBridges', () => {it('refuses everything when the source node does not exist', () => {const plan = planBridges('ghost', ['n2'], lookup, [])expect(plan.edges).toEqual([])- expect(plan.skipped).toEqual([{ id: 'n2', why: 'no such node' }])+ expect(plan.skipped).toEqual([{ id: 'n2', why: 'node not found in this project; cross-project linking is not supported' }])})})diff --git a/src/server/headless-node-factory.test.ts b/src/server/headless-node-factory.test.tsindex 55768d6bf..3d33ea2a1 100644--- a/src/server/headless-node-factory.test.ts+++ b/src/server/headless-node-factory.test.ts@@ -514,7 +514,7 @@ describe('HeadlessNodeFactory', () => {factory.link('term-source', { to: 'term-upstream,term-other-project' }, true)).resolves.toMatchObject({ok: false,- error: expect.stringContaining('link-project-refused')+ error: "link-project-refused: term-other-project is not exclusively in the caller's project; cross-project linking is not supported"})expect((await store.load({ sideline: false })).projects[0].bridges).toEqual([])expect(publishedProjects).toEqual([])diff --git a/src/server/headless-node-factory.ts b/src/server/headless-node-factory.tsindex 8bfb8454c..daffcff46 100644--- a/src/server/headless-node-factory.ts+++ b/src/server/headless-node-factory.ts@@ -3,7 +3,12 @@ import path from 'node:path'import { publishCanvasMutation } from '../core/canvas-sync'import { gateProjectTarget, GRANT_CAP } from '../core/project-grants'-import { planBridges, type LinkEndpoint } from '../shared/canvas-link'+import {+ LINK_ENDPOINT_NOT_FOUND,+ LINK_PROJECT_ONLY,+ planBridges,+ type LinkEndpoint+} from '../shared/canvas-link'import {invalidNodeColorMessage,resolveNodeColor,@@ -881,7 +886,7 @@ export class HeadlessNodeFactory {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`+ error: `link-project-refused: ${id} is not exclusively in the caller's project; ${LINK_PROJECT_ONLY}`}}}@@ -890,7 +895,7 @@ export class HeadlessNodeFactory {const byId = new Map(source.project.nodes.map((node) => [node.id, node]))if (!byId.has(from)) {- return { ok: false, error: `link: --from names no existing node (${from})` }+ return { ok: false, error: `link: --from ${from}: ${LINK_ENDPOINT_NOT_FOUND}` }}const existing = [...(source.project.bridges ?? [])]const plan = planBridges(diff --git a/src/shared/canvas-link.ts b/src/shared/canvas-link.tsindex 1c8546235..cc4ab7d88 100644--- a/src/shared/canvas-link.ts+++ b/src/shared/canvas-link.ts@@ -13,6 +13,11 @@ export interface LinkEndpoint {contextCapable: boolean}+// A project-scoped miss says nothing about existence elsewhere. Do not probe other projects+// just to improve this diagnostic: that would turn a refusal into an existence oracle.+export const LINK_PROJECT_ONLY = 'cross-project linking is not supported'+export const LINK_ENDPOINT_NOT_FOUND = `node not found in this project; ${LINK_PROJECT_ONLY}`+export type LinkKind = 'context' | 'note'/** Decide what kind of link (if any) a new edge between two nodes forms. */@@ -68,7 +73,7 @@ export function planBridges(}const te = lookup(targetId)if (!se || !te) {- skipped.push({ id: targetId, why: 'no such node' })+ skipped.push({ id: targetId, why: LINK_ENDPOINT_NOT_FOUND })continue}const kind = classifyLink(se, te)