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(canvas-control): the limit guidance rides the refusal, not the verb help
review6d448ddd40f6
diff --git a/docs/project-limit.md b/docs/project-limit.mdindex 5f3602d6d..c265ea4ab 100644--- a/docs/project-limit.md+++ b/docs/project-limit.md@@ -159,8 +159,11 @@ if (g !== true && !(await g)) return- **The agent `open-project` verb** goes through `checkAgentProjectOpen` (early, before the folderprobe) and `finishAgentProjectOpen` (the final decision and `registerProject` in one tick). Arefusal is the plain sentence `free plan: N of N projects are open; the user has been shown the- options`, and the user sees the dialog at most once per minute of refusals. The agent-facing verb- help says not to retry. A headless start of a node in a CLOSED project at the limit starts the+ options — do not retry`, and the user sees the dialog at most once per minute of refusals. The+ guidance rides the refusal: the agent-facing verb help (`buildCanvasSkillBody` /+ `buildCanvasControlInstructions`) says nothing about the limit, so nothing about it is printed to+ agents while it is off, and the refusal — which exists only while it is on — is its documentation+ (the agent-text-in-sync rule is met by the outcome text itself). A headless start of a node in a CLOSED project at the limit starts thesession but does not unhide the project (the existing "reopen it from the welcome screen" reply).- A new way to open a project must call the gate. `src/renderer/canvas/project-limit-opens.source.test.ts`pins the five call sites.diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.tsindex cb948ffc4..d7c21f885 100644--- a/src/core/canvas-control-core.ts+++ b/src/core/canvas-control-core.ts@@ -989,7 +989,6 @@ export function buildCanvasControlInstructions(shimPath: string): string {' a denial is final, do not retry it. The user may have turned that dialog off for agents in',' your project, in which case it simply applies. Local only (refused from an SSH project), and it never',' focuses the new project\'s tab. The returned id is what `--project` accepts.',- ' On the free plan this can be refused when the open-project limit is reached. Do not retry: the user has already been shown the options.',' Server Edition is narrower: it can only re-open an exact local project already saved in its',' workspace (pass `--cwd` only); it never creates, adds, renames, recolors, or focuses one.','- `show-image <path>` / `show-video <path>` — open a media file as a node.',@@ -1583,7 +1582,6 @@ ${reportOutcomeDocLines().join('\n')}it. The user may have turned that dialog off for agents in your project, in which case it simplyapplies. Local only (refused from an SSH project), and it never focuses the new project's tab: usethe returned id with \`--project\` to open sessions there.- On the free plan this can be refused when the open-project limit is reached. Do not retry: the user has already been shown the options.On Server Edition this is a restart-recovery operation only: pass \`--cwd\` for an exact localproject already saved in that Server workspace. It never creates, adds, renames, recolors, orfocuses a project; register a missing project in the UI first.diff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.tsindex 7168edee7..3cc4890f6 100644--- a/src/main/canvas-control-core.test.ts+++ b/src/main/canvas-control-core.test.ts@@ -1706,30 +1706,19 @@ describe('open-project --name limit in the agent-facing text (issue #940)', () =})})-describe('open-project at the free-tier project limit (project-limit plan, Task 19)', () => {- // Verbatim from the plan. The renderer refuses the verb at the limit with `free plan: N of N- // projects are open; the user has been shown the options` and has already shown the user the- // limit dialog, so an agent that retries only re-reads the same refusal.- const SENTENCE =- ' On the free plan this can be refused when the open-project limit is reached. Do not retry: the user has already been shown the options.'-+describe('open-project and the free-tier project limit — agent-facing docs', () => {+ // The verb help says nothing about the limit: it is installed into every agent's config on launch,+ // and while the limit is off there must be nothing about it for an agent to read. The guidance+ // rides the refusal itself (`refuseAgent` in renderer/lib/projectLimitGate.ts: `free plan: N of N+ // projects are open; the user has been shown the options — do not retry`), which only exists while+ // the limit is on — so the outcome text IS the documentation, and it cannot drift from the code.it.each([['skill', buildCanvasSkillBody('/x/shim.sh')],['instructions', buildCanvasControlInstructions('/x/shim.sh')]- ])('%s body: the open-project entry says a limit refusal is final', (name, body) => {- expect(body, name).toContain('open-project limit')- expect(body, name).toContain('Do not retry')- const lines = body.split('\n')- const entry = lines.findIndex((l) => l.startsWith('- `open-project --cwd'))- expect(entry, `${name}: the open-project entry`).toBeGreaterThan(-1)- const nextEntry = lines.findIndex((l, i) => i > entry && l.startsWith('- '))- // The Server Edition never limits (its state is permanently inactive, spec §10), so the- // sentence sits in the desktop half of the entry, ahead of the Server Edition paragraph.- const serverEdition = lines.findIndex((l, i) => i > entry && l.includes('Server Edition'))- const at = lines.indexOf(SENTENCE)- expect(at, `${name}: the sentence, verbatim, on a line of its own`).toBeGreaterThan(entry)- expect(at, `${name}: inside the open-project entry`).toBeLessThan(nextEntry)- expect(at, `${name}: before the Server Edition paragraph`).toBeLessThan(serverEdition)+ ])('%s body: says nothing about the limit', (name, body) => {+ for (const phrase of ['open-project limit', 'free plan', 'free-project', 'allowance', 'shown the options']) {+ expect(body, `${name}: ${phrase}`).not.toContain(phrase)+ }})})diff --git a/src/renderer/lib/projectLimitGate.test.ts b/src/renderer/lib/projectLimitGate.test.tsindex 48933c5c1..c23531948 100644--- a/src/renderer/lib/projectLimitGate.test.ts+++ b/src/renderer/lib/projectLimitGate.test.ts@@ -350,7 +350,7 @@ describe('DO_NOT_TRACK installs re-claim at a known allowance (the undo has no o// would never hear `not_active` (an undo), an epoch bump or a raised FREE.const DNT_CLAIMED_5: ProjectLimitState = { ...CLAIMED_5, dnt: true }const DNT_OFF: ProjectLimitState = { ...INACTIVE, dnt: true }- const MESSAGE = 'free plan: 5 of 5 projects are open; the user has been shown the options'+ const MESSAGE = 'free plan: 5 of 5 projects are open; the user has been shown the options — do not retry'it('person: one claim at the limit, and a not_active answer opens with no dialog', async () => {const t = harness(DNT_CLAIMED_5, 5)@@ -480,7 +480,7 @@ describe('DO_NOT_TRACK installs re-claim at a known allowance (the undo has no o})describe('checkAgentProjectOpen — the agent open-project verb', () => {- const MESSAGE = 'free plan: 5 of 5 projects are open; the user has been shown the options'+ const MESSAGE = 'free plan: 5 of 5 projects are open; the user has been shown the options — do not retry'it('allows when the open would be allowed for a person, without any dialog', async () => {const t = harness(INACTIVE, 9)@@ -545,13 +545,13 @@ describe('checkAgentProjectOpen — the agent open-project verb', () => {const gate = createProjectOpenGate(t.deps)await expect(gate.checkAgentProjectOpen()).resolves.toEqual({ok: false,- message: 'free plan: 7 of 7 projects are open; the user has been shown the options'+ message: 'free plan: 7 of 7 projects are open; the user has been shown the options — do not retry'})})})describe('finishAgentProjectOpen — the final decision and the agent registration, in one tick', () => {- const MESSAGE = 'free plan: 5 of 5 projects are open; the user has been shown the options'+ const MESSAGE = 'free plan: 5 of 5 projects are open; the user has been shown the options — do not retry'const CLAIMED_12: ProjectLimitState = { ...AT_LIMIT, allowance: 12 }/** A register callback that counts its calls and, like registerProject, adds an open project. */@@ -676,7 +676,7 @@ describe('finishAgentProjectOpen — the final decision and the agent registratiawait expect(a).resolves.toEqual({ ok: true, value: 'registered #6' })await expect(b).resolves.toEqual({ok: false,- message: 'free plan: 6 of 6 projects are open; the user has been shown the options'+ message: 'free plan: 6 of 6 projects are open; the user has been shown the options — do not retry'})expect(register).toHaveBeenCalledTimes(1)})diff --git a/src/renderer/lib/projectLimitGate.ts b/src/renderer/lib/projectLimitGate.tsindex 25764f167..46fc12aa9 100644--- a/src/renderer/lib/projectLimitGate.ts+++ b/src/renderer/lib/projectLimitGate.ts@@ -189,12 +189,14 @@ export function createProjectOpenGate(deps: ProjectOpenGateDeps): ProjectOpenGat}/** Every agent refusal, from either check: the user is shown the dialog (under showForAgent's- * rules) and the agent gets the one sentence (spec §7.5), so the two checks cannot word it twice. */+ * rules) and the agent gets the one sentence, so the two checks cannot word it twice. The sentence+ * is also the agent's only documentation of the limit — the canvas-control verb help says nothing+ * about it, so nothing reaches an agent while the limit is off — hence the "do not retry". */function refuseAgent(state: ProjectLimitState): Extract<AgentOpenCheck, { ok: false }> {showForAgent()return {ok: false,- message: `free plan: ${deps.openCount()} of ${effectiveLimit(state)} projects are open; the user has been shown the options`+ message: `free plan: ${deps.openCount()} of ${effectiveLimit(state)} projects are open; the user has been shown the options — do not retry`}}