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(accounts): one binding rule behind data.accountId and the node color

Uri Bloch19da3a022dc5
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 raw
list, so a **pending** account or one **pinned to another machine's host** is never stamped
onto 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)** — a
per-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 SAME
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 that
The same applies to any hook-server signature change; this repo has shipped one to a single shell
three 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 alternate
screen. A previous design moved that into the emulator and failed structurally; `CLAUDE.md` explains
why in detail.
diff --git a/src/core/project-node-append.test.ts b/src/core/project-node-append.test.ts
index 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.ts
index 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) : undefined
const 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.ts
index 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.ts
index 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/agent
import { 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().settings
const 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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
+}