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(accounts): one binding rule behind data.accountId and the node color
Uri Bloch19da3a022dc5
diff --git a/CLAUDE.md b/CLAUDE.mdindex 57fb90429..8bda9fdc4 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1524,6 +1524,21 @@ else, and its context links must keep classifying across restarts).the project-default account), and validation runs against `accountsForProject`, not the rawlist, so a **pending** account or one **pinned to another machine's host** is never stampedonto a node it cannot run on (both used to reach the missing-dir fallback at spawn).+ - **`boundAccountId(accountId, agentId)` (`shared/agents/account-binding.ts`) is the ONE rule for+ whether a node is account-bound at all**, and it feeds `data.accountId` *and* the account color+ from a single decision — split them and a node carries an account it is not painted for, or is+ painted for one it does not carry. Two surfaces mint nodes and both ask it: `createAgentNode`+ (canvas) and `appendProjectNode` (the phone's `projects.registerNode`, which used to write+ whatever the wire sent, so a gemini node could come back bound to a Claude account). Managed+ accounts belong to the builtin **claude and codex** (S6); a **known** other agent — builtin or+ custom, since a custom agent inheriting one of those harnesses is still its own agent — never+ binds. **An UNSTATED agent keeps its binding** — the asymmetry is deliberate: the phone chooses+ `agentId` and `accountId` independently and is not known to always send the first+ (docs/ios-protocol-migration.md §6), dropping a real binding is the wrong-identity bug the+ field exists to prevent, while a stray one on an agent-less node only sets a config-home+ variable nothing reads. On the canvas `agentId` is always stated, so that path is bit-for-bit+ what it was. `main` resolves the color off the RAW id and lets the registrar refuse it, rather+ than re-deriving the gate at the call site.- **Account default node color (`ClaudeAccount.color` / `CodexAccount.color`, optional)** — aper-account default node color (Settings → Accounts) that beats the agent's own brand color in`createAgentNode`, so a second login is recognizable on the canvas. Read off the SAMEdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 28d235528..03accafd5 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -162,6 +162,15 @@ feature, and the boundary tests can only tell you an import is wrong, never thatThe same applies to any hook-server signature change; this repo has shipped one to a single shellthree times.+**A rule enforced at one mint site is enforced nowhere.** Nodes are created on two surfaces — the+canvas (`createAgentNode`) and the phone's `projects.registerNode` (`appendProjectNode`) — and a+constraint spelled out inline at one of them silently does not exist at the other. "Which agents+bind a managed account" lived as a ternary in the renderer while the phone leg wrote whatever the+wire sent.+Put the rule in one predicate under `src/shared` and have every mint site ask it, and derive the+things that follow from it (a node's color, say) from that same call rather than re-deriving the+condition per caller.+**Do not take scrolling away from tmux.** It owns the mouse, the scrollback and the alternatescreen. A previous design moved that into the emulator and failed structurally; `CLAUDE.md` explainswhy in detail.diff --git a/src/core/project-node-append.test.ts b/src/core/project-node-append.test.tsindex 605f4b23f..66c28d997 100644--- a/src/core/project-node-append.test.ts+++ b/src/core/project-node-append.test.ts@@ -1,5 +1,6 @@import { describe, it, expect } from 'vitest'import { appendProjectNode, removeProjectNode } from './project-node-append'+import { agentConfig } from '../shared/agents/config'const NOW = new Date('2026-07-16T10:00:00.000Z')@@ -102,6 +103,60 @@ describe('appendProjectNode', () => {expect(out.nodes[0].color).toBe('#d97757')})+ // Managed accounts belong to the builtin claude and codex (S6), and the canvas has always+ // refused to stamp one onto any other agent's node. This leg wrote whatever the phone sent, so a+ // gemini node could come back bound to a managed account — a config home and an account-scoped+ // reader root that mean nothing for it. The binding and the color are ONE decision, so both go.+ it('never binds a managed account to an agent that takes none, nor paints it that color', () => {+ const out = JSON.parse(+ appendProjectNode(+ baseFile([]),+ { id: 'term-c-1', agentId: 'gemini', accountId: 'acct1' },+ NOW,+ '#0a84ff'+ )!+ )+ expect(out.nodes[0].accountId).toBeUndefined()+ expect(out.nodes[0].color).toBe(agentConfig('gemini')!.color)+ })++ // Codex binds since S6 — the rule is "which agents take a managed account", not "claude".+ it('binds a managed account to a Codex registration, color and all', () => {+ const out = JSON.parse(+ appendProjectNode(+ baseFile([]),+ { id: 'term-c-1', agentId: 'codex', accountId: 'acct1' },+ NOW,+ '#0a84ff'+ )!+ )+ expect(out.nodes[0].accountId).toBe('acct1')+ expect(out.nodes[0].color).toBe('#0a84ff')+ })++ it('never binds one to a custom agent either, even one based on claude', () => {+ const out = JSON.parse(+ appendProjectNode(+ baseFile([]),+ { id: 'term-c-1', agentId: 'my-claude', accountId: 'acct1' },+ NOW,+ '#0a84ff'+ )!+ )+ expect(out.nodes[0].accountId).toBeUndefined()+ })++ // The phone sends `agentId` and `accountId` independently and is not known to always send the+ // first (docs/ios-protocol-migration.md §6). Dropping the binding here would be the wrong-identity+ // bug the field was added to fix, so an unstated agent keeps it — see `boundAccountId`.+ it('keeps the binding when the phone stated no agent', () => {+ const out = JSON.parse(+ appendProjectNode(baseFile([]), { id: 'term-c-1', accountId: 'acct1' }, NOW, '#0a84ff')!+ )+ expect(out.nodes[0].accountId).toBe('acct1')+ expect(out.nodes[0].color).toBe('#0a84ff')+ })+it('a custom/unknown agent and a plain terminal keep the mobile defaults', () => {const custom = JSON.parse(appendProjectNode(baseFile([]), { id: 'term-c-1', agentId: 'aider' }, NOW)!)expect(custom.nodes[0].color).toBe('#7aa2f7')diff --git a/src/core/project-node-append.ts b/src/core/project-node-append.tsindex d3e795ac2..c2e0f307c 100644--- a/src/core/project-node-append.ts+++ b/src/core/project-node-append.ts@@ -9,6 +9,7 @@// an unsafe id (it becomes a tmux session name).import { agentConfig } from '../shared/agents/config'+import { boundAccountId } from '../shared/agents/account-binding'import { isSafeAccountId } from './claude-accounts-core'/** What the phone is allowed to choose; everything else is host-derived. */@@ -105,10 +106,22 @@ export function appendProjectNode(// label as the starting title, and the bound account's default color where the host resolved// one, else the agent's — titleAuto then lets the agent's own session name take over, same as// desktop. `accountColor` is host-derived (the phone cannot choose it) and already resolved- // through the shared `accountNodeColor`, so a phone-started session under a colored account+ // through the shared `agentAccountColor`, so a phone-started session under a colored account// lands on the canvas in that color instead of the agent's. A plain terminal keeps the mobile// defaults.- const agent = typeof input.agentId === 'string' ? agentConfig(input.agentId) : undefined+ //+ // `boundAccountId` is the ONE decision behind both the stamp and the color, exactly as+ // `createAgentNode` reads them off one local: split them and a node can end up carrying an+ // account it is not painted for, or painted for one it does not carry. The caller may hand us a+ // color for an id we then refuse — that is fine and deliberate, because it keeps the rule in one+ // place instead of asking every caller to re-derive it.+ //+ // A non-string `agentId` reads as "no agent stated" here, the same way the config lookup below+ // has always treated it — a garbage value must not be mistaken for a known OTHER agent and cost+ // a real Claude node its binding.+ const agentId = typeof input.agentId === 'string' ? input.agentId : undefined+ const bound = boundAccountId(input.accountId, agentId)+ const agent = agentId !== undefined ? agentConfig(agentId) : undefinedconst node: Record<string, unknown> = {id: input.id,kind: 'terminal',@@ -119,15 +132,15 @@ export function appendProjectNode(? input.title.slice(0, TITLE_MAX): (agent?.label ?? 'Mobile session'),titleAuto: true,- color: accountColor ?? agent?.color ?? '#7aa2f7',+ color: (bound ? accountColor : undefined) ?? agent?.color ?? '#7aa2f7',group: null,tags: [],collapsed: false,// Sibling nodes carry the project's portable cwd (usually "./…").cwd: typeof sibling?.cwd === 'string' ? sibling.cwd : '.'}- if (typeof input.agentId === 'string') node.agentId = input.agentId- if (typeof input.accountId === 'string') node.accountId = input.accountId+ if (agentId !== undefined) node.agentId = agentId+ if (bound) node.accountId = bound// Desktop remote nodes carry the connection spec PER NODE — a sibling terminal in the same// project has the right values; copy verbatim. No genuine donor → a plain local node.//diff --git a/src/main/index.ts b/src/main/index.tsindex 3a2e9e127..20e16db3a 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -3394,7 +3394,10 @@ app.whenReady().then(async () => {// Host-derived, exactly as on the canvas: the account's default color beats the agent's,// so a phone-started session under a colored account is recognizable in the same way. The// agent decides WHICH account list answers (agentAccountColor) — the phone supplies both- // ids, and the two lists are keyed independently.+ // ids, and the two lists are keyed independently. Resolved off the RAW account id: whether+ // this node is account-bound at all is `boundAccountId`'s call, made once inside the+ // registrar, which ignores this color when it refuses the binding. Re-deriving that rule+ // here would be the second copy that drifts.agentAccountColor(node.agentId, node.accountId, {claude: settingsStore.get().claudeAccounts ?? [],codex: settingsStore.get().codexAccounts ?? []diff --git a/src/renderer/state/workspace.ts b/src/renderer/state/workspace.tsindex edceb2085..eb7190d86 100644--- a/src/renderer/state/workspace.ts+++ b/src/renderer/state/workspace.ts@@ -12,6 +12,7 @@ import type { AgentId, AgentPermissionMode, BuiltinAgentId } from '@shared/agentimport { agentConfig, supportsSessionIdFlag } from '@shared/agents/config'import { assembleLaunchCommand } from '@shared/agents/launch'import { agentAccountColor } from '@shared/agents/account-color'+import { boundAccountId } from '@shared/agents/account-binding'import { agentEnvSnapshot } from '../lib/agentEnv'import { uuid } from '@renderer/lib/uuid'import { claudeCliCapsNow } from './permissionMode'@@ -599,24 +600,21 @@ export function createAgentNode(promptFile?: string): CanvasNode {const { label, color: agentColor } = resolveAgent(agentId)- // Managed accounts bind to the builtin Claude and Codex agents (S6) — never to another builtin,- // and never to a custom agent even when it inherits one of those bases. A custom agent inheriting- // claude/codex is still its own agent; account binding stays with the builtin the account picker- // offered it for. The Codex spawn side honours `data.accountId` (resolveCodexSessionScope), the- // same field Claude uses. Extracted to one local so the stamped binding below and the account- // color resolved from it cannot drift apart.- const boundAccountId =- accountId && (agentId === 'claude' || agentId === 'codex') ? accountId : undefined+ // ONE binding decision, shared with the phone-registration path (core/project-node-append) so+ // "which agents bind a managed account" has a single definition instead of a ternary the canvas+ // enforces and the registrar does not. It feeds both `data.accountId` below and the color here,+ // which is what keeps the two from drifting apart.+ const bound = boundAccountId(accountId, agentId)// A managed account's default node color (Settings → Accounts) replaces the agent's brand color,- // so a second login of either builtin is recognizable on the canvas at a glance. `agentAccountColor`- // asks the list that OWNS this agent's accounts — the two are keyed independently, so a Claude- // account must never color a Codex node that happens to share its id.+ // so a second login of either builtin is recognizable on the canvas at a glance.+ // `agentAccountColor` asks the list that OWNS this agent's accounts — the two are keyed+ // independently, so a Claude account must never color a Codex node that happens to share its id.// `?? []` on both lists, matching the phone path in `src/main`: `mergeSettings` merges without// checking, so a hand-edited `"claudeAccounts": null` survives load and would throw on `.find`// one level ABOVE the `typeof color` guard — i.e. the very failure that guard exists to prevent.const settings = useSettings.getState().settingsconst color =- agentAccountColor(agentId, boundAccountId, {+ agentAccountColor(agentId, bound, {claude: settings.claudeAccounts ?? [],codex: settings.codexAccounts ?? []}) ?? agentColor@@ -699,8 +697,8 @@ export function createAgentNode(group: null,tags: [],agentId,- // See `boundAccountId` above for why this is claude/codex-only.- ...(boundAccountId ? { accountId: boundAccountId } : {}),+ // See `boundAccountId` (shared/agents/account-binding.ts) for which agents bind at all.+ ...(bound ? { accountId: bound } : {}),// Persisted alongside the node (unlike initialCommand, which is consumed on first open), so// a cold restore months later still knows which conversation this node owns....(mintedSessionId ? { agentSessionId: mintedSessionId } : {}),diff --git a/src/shared/agents/account-binding.test.ts b/src/shared/agents/account-binding.test.tsnew file mode 100644index 000000000..3cf7d168e--- /dev/null+++ b/src/shared/agents/account-binding.test.ts@@ -0,0 +1,39 @@+import { describe, it, expect } from 'vitest'+import { boundAccountId } from './account-binding'++describe('boundAccountId', () => {+ it('binds a managed account to a Claude node', () => {+ expect(boundAccountId('a1', 'claude')).toBe('a1')+ })++ it('binds a managed account to a Codex node — accounts are not Claude-only since S6', () => {+ expect(boundAccountId('c1', 'codex')).toBe('c1')+ })++ it('never binds one to a builtin that takes no managed account', () => {+ expect(boundAccountId('a1', 'gemini')).toBeUndefined()+ expect(boundAccountId('a1', 'grok')).toBeUndefined()+ })++ it('never binds one to a custom agent, even one based on claude or codex', () => {+ // A custom agent inheriting a builtin's harness is still its own agent; account binding stays+ // with the builtin the account picker offered it for, exactly as createAgentNode has always+ // had it.+ expect(boundAccountId('a1', 'my-claude')).toBeUndefined()+ expect(boundAccountId('c1', 'my-codex')).toBeUndefined()+ })++ it('keeps the binding when the agent is not stated at all', () => {+ // The phone chooses `agentId` and `accountId` independently and whether it always sends the+ // first alongside the second is an OPEN question (docs/ios-protocol-migration.md §6). Dropping+ // a real Claude binding is the severe direction — it is the wrong-identity bug the field+ // exists to prevent — while keeping a stray one on an agent-less node only sets a config-home+ // variable nothing reads.+ expect(boundAccountId('a1', undefined)).toBe('a1')+ })++ it('is undefined when no account is given', () => {+ expect(boundAccountId(undefined, 'claude')).toBeUndefined()+ expect(boundAccountId('', 'claude')).toBeUndefined()+ })+})diff --git a/src/shared/agents/account-binding.ts b/src/shared/agents/account-binding.tsnew file mode 100644index 000000000..b23969875--- /dev/null+++ b/src/shared/agents/account-binding.ts@@ -0,0 +1,32 @@+/**+ * Which managed account a node is actually BOUND to — the one rule behind both `data.accountId`+ * and the account's default node color.+ *+ * Managed accounts belong to the builtin **Claude and Codex** agents (S6). The id becomes a config+ * home path segment (`CLAUDE_CONFIG_DIR` / `CODEX_HOME`) and scopes every account-aware reader+ * (transcript, context meter, find-bar index, usage), none of which mean anything for another+ * agent. A custom agent inheriting one of those harnesses is still its own agent, so it does not+ * bind either — account binding stays with the builtin the account picker offered it for.+ *+ * **An UNSTATED agent keeps its binding.** The phone chooses `agentId` and `accountId`+ * independently over the relay (`projects.registerNode`), and whether it always sends the first+ * alongside the second is an open question — `docs/ios-protocol-migration.md` §6 lists exactly+ * that as unconfirmed. The two failure directions are not symmetric: dropping a real binding+ * resurrects the wrong-identity bug the field was added to fix (an off-LAN session under account X+ * comes back as the system account, every scoped reader resolves against the wrong root, and a+ * cold restore resumes it as the wrong identity), while keeping a stray binding on an agent-less+ * node only sets a config-home variable that nothing reads. So the gate refuses a KNOWN other+ * agent, not an unknown one. A non-string `agentId` reads as "no agent stated", the same way the+ * `agentConfig` lookup beside it has always treated one.+ *+ * On the canvas `agentId` is always stated (`createAgentNode` takes it as a required argument), so+ * that path is bit-for-bit what it was.+ */+export function boundAccountId(+ accountId: string | undefined,+ agentId: string | undefined+): string | undefined {+ if (!accountId) return undefined+ if (agentId !== undefined && agentId !== 'claude' && agentId !== 'codex') return undefined+ return accountId+}