Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(link): explain project-scoped endpoint refusals

review659abcdbe1d3
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 push
was 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` accept
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 real
bug.
+**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" are
different facts and must stay distinguishable at every layer. Collapsing them is how a panel ends up
reporting "no sessions" on a host running thirty. When something ACTS on the negative, give it three
diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.ts
index 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 opened
during 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.ts
index 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 + M
for (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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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)