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
docs(accounts): state the invariant instead of citing a plan nobody can open
freshjuicez46bf59611770
diff --git a/CLAUDE.md b/CLAUDE.mdindex 3111273fe..3b82fc765 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1870,8 +1870,7 @@ else, and its context links must keep classifying across restarts).correct (their credentials aren't on the host) but read as "multi-account is broken on SSH".- **Remote accounts** — selection + login + env injection, plus **usage** (below); noper-account transcript readers beyond env.- - **Linked accounts** (`ClaudeAccount.configDir`, design:- `docs/superpowers/plans/2026-09-01-claude-account-tracking.md`) — a PRE-EXISTING local config+ - **Linked accounts** (`ClaudeAccount.configDir`) — a PRE-EXISTING local configdir the user already drives themselves (`export CLAUDE_CONFIG_DIR=~/.claude-2; claude …` in aplain terminal) adopted as a first-class account without a login node. Settings → Accounts →**Link existing config dir…** (or one click on a **Detected** dir) calls `claude-accounts:link`diff --git a/src/core/agent-status-mirror.test.ts b/src/core/agent-status-mirror.test.tsindex b4adf8f1b..57dee189f 100644--- a/src/core/agent-status-mirror.test.ts+++ b/src/core/agent-status-mirror.test.ts@@ -2327,7 +2327,7 @@ describe('hibernated flag (Eco × phone — SLEEPING on external readers)', () =})})-// ---- The observed Claude account (design D3/D4) ---------------------------------------------+// ---- The observed Claude account (which account a RUNNING session is on) ---------------------//// For a HAND-LAUNCHED claude (a plain terminal running `CLAUDE_CONFIG_DIR=~/.claude-2 claude`)// the node's `data.accountId` is undefined forever, so this label is the only record of whichdiff --git a/src/core/agents/hook-account-label.test.ts b/src/core/agents/hook-account-label.test.tsindex 128acdf48..b3987df95 100644--- a/src/core/agents/hook-account-label.test.ts+++ b/src/core/agents/hook-account-label.test.ts@@ -1,6 +1,7 @@/**- * `/hook/*` learns a THIRD label: which Claude account the posting session is actually on- * (design D1/D3 of the claude-account-tracking plan).+ * `/hook/*` learns a THIRD label: which Claude account the posting session is actually on,+ * derived from the payload's `transcript_path` and attached in the hook server so ONE+ * implementation serves both shells.** Driven through the REAL server — a POST over the socket, not a call to a helper — because the* property under test is that the label is attached where `verified` / `clientRevision` are, i.e.@@ -28,8 +29,8 @@ import type { NormalizedAgentEvent } from '../../shared/agents/normalize'import type { ClaudeAccount } from '../../shared/types'let dir = ''-// The linked dir is a plain PATH here — nothing on disk is required, and that is itself the point-// (D7): classification is string work, so a forged POST cannot make the server open anything.+// The linked dir is a plain PATH here — nothing on disk is required, and that is itself the point:+// classification is string work, so a forged POST cannot make the server open anything.const LINKED_DIR = '/home/test-user/.claude-2'const LINKED: ClaudeAccount = { id: 'linked-acct-1', label: 'second', configDir: LINKED_DIR, createdAt: 0 }@@ -136,7 +137,7 @@ describe('hook server: the observed-account label on /hook/claude', () => {expect(events[0].account).toBeUndefined()})- it('leaves the RAW listener contract untouched (D3: neither raw listener changes)', async () => {+ it('leaves the RAW listener contract untouched — neither raw listener changes', async () => {await post('claude', `${LINKED_DIR}/projects/-repo/s1.jsonl`)expect(raws).toHaveLength(1)expect('account' in raws[0].payload).toBe(false)diff --git a/src/core/agents/hook-server.ts b/src/core/agents/hook-server.tsindex 169e8b454..685ef777d 100644--- a/src/core/agents/hook-server.ts+++ b/src/core/agents/hook-server.ts@@ -150,7 +150,7 @@ function parseClientRevision(raw: string | string[] | undefined): number | undef}/**- * The `account` LABEL for a claude hook payload (design D1/D2): `transcript_path` →+ * The `account` LABEL for a claude hook payload: `transcript_path` →* `<configDir>/projects/…` → which account that dir is. Undefined for every other agent and for a* payload with no usable `transcript_path` — "we did not observe an account" and "the system* account" are different facts and must stay distinguishable (CONTRIBUTING: a failed read is never@@ -158,7 +158,7 @@ function parseClientRevision(raw: string | string[] | undefined): number | undef** NEVER throws: this sits on the 204 path, and a classification failure — a settings store mid-* write, a platform seam not yet initialized in an odd boot order — must cost the label, not the- * event. NO filesystem access happens here (D7): the dir is classified as a string, so a forged+ * event. NO filesystem access happens here: the dir is classified as a string, so a forged* POST naming `~/.ssh/projects/x.jsonl` gets a `known: false` label and nothing is opened.*/function observedClaudeAccount(@@ -754,7 +754,7 @@ class HookServer {// Raw listener first: it drives the transcript-tailing features (which need// transcript_path). Inside the try so a throwing raw listener still ends 204.this.rawListener?.(agentId, nodeId, payload, { verified })- // WHICH CLAUDE ACCOUNT this session is on (design D1/D3). A third LABEL alongside+ // WHICH CLAUDE ACCOUNT this session is on. A third LABEL alongside// `verified`/`clientRevision`, computed HERE so ONE implementation serves both shells —// the "both raw listeners change together" rule is sidestepped rather than violated,// because neither raw listener changes. Claude only: `transcript_path` means a configdiff --git a/src/core/claude-accounts-core.test.ts b/src/core/claude-accounts-core.test.tsindex 7f69dffdc..d4aee72dd 100644--- a/src/core/claude-accounts-core.test.ts+++ b/src/core/claude-accounts-core.test.ts@@ -258,7 +258,7 @@ describe('isSafeRemoteTranscriptPath', () => {})})-// ---- Observed accounts (design D1/D2) --------------------------------------------------------+// ---- Observed accounts (deriving a session's account from its transcript path) ----------------//// The whole feature turns on these three pure functions, so each is driven with BOTH path// dialects: the desktop that classifies an SSH node's POSIX `transcript_path` may itself be@@ -421,8 +421,10 @@ describe('classifyClaudeConfigDir', () => {accountId: null,known: true})- // D2 is host-agnostic on purpose: an SSH node's `<remoteHome>/.claude` is that host's system- // account, and the observed dir is a label — nothing branches on it for permission.+ // The classifier is host-agnostic on purpose: an SSH node's `<remoteHome>/.claude` is that+ // host's system account, and the observed dir is a label — nothing branches on it for+ // permission. (Which MACHINE the dir is on is the renderer's to record; see+ // `ObservedClaudeAccount.remote`.)expect(at('/home/enes/.claude')).toEqual({configDir: '/home/enes/.claude',accountId: null,diff --git a/src/core/claude-accounts-core.ts b/src/core/claude-accounts-core.tsindex 311e9fdda..8187559c9 100644--- a/src/core/claude-accounts-core.ts+++ b/src/core/claude-accounts-core.ts@@ -49,7 +49,7 @@ export function remoteAccountConfigDirAbs(remoteHome: string, accountId: string)return `${remoteHome.replace(/\/+$/, '')}/.nodeterm/claude-accounts/${accountId}`}-// ---- Observed config dirs (D1/D2: which account a RUNNING session is actually on) -----------+// ---- Observed config dirs (which account a RUNNING session is actually on) ------------------//// The hook payload's `transcript_path` is the only account signal that exists for a session// nodeterm did not launch — a hand-run `CLAUDE_CONFIG_DIR=~/.claude-2 claude` in a plain terminal@@ -163,7 +163,7 @@ function linkedDirOf(acct: ClaudeAccount): string | null {}/**- * Classify an observed config dir into an `ObservedClaudeAccount` (design D2). PURE string+ * Classify an observed config dir into an `ObservedClaudeAccount`. PURE string* matching — no fs, and deliberately host-agnostic, because the same classification has to answer* for a remote path an SSH node's hooks posted:* 1. `<userData>/claude-accounts/<id>` — this app's own managed root on THIS machine.@@ -171,7 +171,7 @@ function linkedDirOf(acct: ClaudeAccount): string | null {* 3. a settings row's linked `configDir` — the user declared this dir an account.* 4. any `…/.claude` — the system default, on this machine or on the host (`accountId: null`).* 5. anything else — `known: false`; the UI labels it by its last path segment and offers to- * link it. NOTHING reads such a dir (D7): a forged POST must not make us open a file.+ * link it. NOTHING reads such a dir: a forged POST must not make us open a file.** (1) and (2) answer with the id WITHOUT consulting settings: the path IS nodeterm's own root, so* the id in it is the id nodeterm minted — including for an account still `pending` its login,diff --git a/src/core/claude-accounts-service.test.ts b/src/core/claude-accounts-service.test.tsindex 5757ab79b..e8b668b7b 100644--- a/src/core/claude-accounts-service.test.ts+++ b/src/core/claude-accounts-service.test.ts@@ -188,7 +188,7 @@ describe('installHooksIntoLocalAccounts', () => {})})-// ---- Linked accounts (design D4 / §3) --------------------------------------------------------+// ---- Linked accounts (adopting a config dir the user already drives) -------------------------//// A linked account is a config dir the USER already owns (`~/.claude-2` driven by their own// `CLAUDE_CONFIG_DIR` shell function). Two properties matter more than the rest and are pinneddiff --git a/src/core/claude-accounts-service.ts b/src/core/claude-accounts-service.tsindex b0a33d69d..3c2b6ad65 100644--- a/src/core/claude-accounts-service.ts+++ b/src/core/claude-accounts-service.ts@@ -163,7 +163,7 @@ export function registerClaudeAccountsIpc(deps: ClaudeAccountsDeps = {}): void {await remote.r.remove(remote.projectId, id)return}- // LINKED account (design D4/§3): the directory is the USER's — `~/.claude-2` with their real+ // LINKED account: the directory is the USER's — `~/.claude-2` with their real// login in it — and removing the account only forgets the settings row (the renderer owns the// list). Forgetting is the whole operation here; `rm -rf` would delete a second Claude// identity the app never created.@@ -177,8 +177,8 @@ export function registerClaudeAccountsIpc(deps: ClaudeAccountsDeps = {}): void {})/**- * Link a PRE-EXISTING Claude config dir as an account (design D4; validation is §3 verbatim).- * The renderer owns the settings list, so this returns the record and appends nothing itself.+ * Link a PRE-EXISTING Claude config dir as an account. The renderer owns the settings list, so+ * this returns the record and appends nothing itself.** Every refusal is a distinct `Error` message because the Settings UI shows it: "that path does* not exist" and "that is already linked" need different fixes from the user, and one generic@@ -198,9 +198,9 @@ export function registerClaudeAccountsIpc(deps: ClaudeAccountsDeps = {}): void {if (!configDir) {throw new Error(`Not an absolute path: ${typed}`)}- // The three STRING refusals run before the fs is touched at all. §3 lists exists/isDirectory- // first, but the order here is deliberate: a path we are going to refuse on its shape alone is- // a path we should not be stat'ing, and refusing `~/.claude` needs to say so even on a machine+ // The three STRING refusals run before the fs is touched at all, and that ORDER is+ // deliberate rather than incidental: a path we are going to refuse on its shape alone is a+ // path we should not be stat'ing, and refusing `~/.claude` needs to say so even on a machine// where the dir has not been created yet ("no such directory" would be a misleading answer to// "why can't I link my system account?").if (configDir === normalizeLinkedConfigDir(path.join(homedir(), '.claude'))) {@@ -233,7 +233,7 @@ export function registerClaudeAccountsIpc(deps: ClaudeAccountsDeps = {}): void {}if (!isDir) throw new Error(`Not a directory: ${configDir}`)// The ONLY read of the dir's contents, and only after the user asked for this dir by name.- // Missing / not-logged-in is `email: null`, NOT a failure (§3): linking a dir the user has not+ // Missing / not-logged-in is `email: null`, NOT a failure: linking a dir the user has not// signed into yet is legitimate — the CLI writes the email when they do.let email: string | null = nulltry {diff --git a/src/core/claude-config-dir.test.ts b/src/core/claude-config-dir.test.tsindex 8989056a8..e9ca9b373 100644--- a/src/core/claude-config-dir.test.ts+++ b/src/core/claude-config-dir.test.ts@@ -52,7 +52,7 @@ describe('claudeConfigDirFor', () => {})})-// ---- Linked accounts (design D4) ------------------------------------------------------------+// ---- Linked accounts (a config dir the user already owns) ------------------------------------//// `claudeConfigDirFor` is THE resolver: env injection at spawn, the usage reader, the transcript// roots and the mirror's account list all call it and nothing else. So the linked branch is addeddiff --git a/src/core/claude-config-dir.ts b/src/core/claude-config-dir.tsindex 3b087e3f4..fefdc3870 100644--- a/src/core/claude-config-dir.ts+++ b/src/core/claude-config-dir.ts@@ -1,5 +1,5 @@// Resolve a Claude account's config dir under this app's persistent state root — or, for a LINKED-// account, the pre-existing dir the user already owns (`ClaudeAccount.configDir`, design D4).+// account, the pre-existing dir the user already owns (`ClaudeAccount.configDir`).// The account LIST + login lifecycle live in main/claude-accounts.ts; this is just the// impure path resolution (needs the platform seam for userDataDir) split out so core// modules (pty-manager, etc.) can use it without importing electron.@@ -49,7 +49,7 @@ export function claudeAccountsSnapshot(): readonly ClaudeAccount[] {* A linked account's validated config dir, or null when the id names no linked account. The value* is re-validated (absolute, normalized, no `..`) at THIS point of use — it comes from a* hand-editable settings.json — and an unusable one yields null, which sends every caller back to- * the managed path (§3: "never something more destructive than the default").+ * the managed path — never something more destructive than the default.*/export function linkedClaudeConfigDirFor(accountId: string): string | null {for (const a of claudeAccountsSnapshot()) {diff --git a/src/core/transcript-index.ts b/src/core/transcript-index.tsindex 5096c3a29..7c30ecbba 100644--- a/src/core/transcript-index.ts+++ b/src/core/transcript-index.ts@@ -37,7 +37,7 @@ function projectsRoots(): string[] {for (const acct of accountsGetter?.() ?? []) {if (acct.host || acct.pending) continuetry {- // A LINKED account indexes the user's OWN dir (design D4). Re-validated here rather than+ // A LINKED account indexes the user's OWN dir. Re-validated here rather than// trusted — settings.json is hand-editable — and an unusable value falls back to the managed// path, which simply contributes an absent root.const dir = normalizeLinkedConfigDir(acct.configDir) ?? accountConfigDir(userData, acct.id)diff --git a/src/main/index.ts b/src/main/index.tsindex a6b4e773e..e0611006e 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -1227,7 +1227,7 @@ app.whenReady().then(async () => {})settingsStore.init()- // The linked-account resolver's one source of truth on this shell (design D4). Registered as+ // The linked-account resolver's one source of truth on this shell. Registered as// soon as settings exist — not down beside `initTranscriptIndex`, where the other account wiring// sits — because EVERY config-dir resolution has to be able to see it, including the earliest:// the mirror settings provider is a lazy callback and an agent-status flush can fire from thediff --git a/src/renderer/components/AccountChip.test.tsx b/src/renderer/components/AccountChip.test.tsxindex 9c5a22f05..cb854b820 100644--- a/src/renderer/components/AccountChip.test.tsx+++ b/src/renderer/components/AccountChip.test.tsx@@ -63,7 +63,7 @@ afterEach(() => {useSettings.setState({ settings: DEFAULT_SETTINGS })})-describe('AccountChip (D6 visibility through the live stores)', () => {+describe('AccountChip (chip visibility through the live stores)', () => {it('renders nothing for a system pane while it is the only identity in play', () => {useAgentStatus.setState({ byId: { n1: { unread: false, account: SYSTEM } } })const { host, root } = render({ observed: SYSTEM })diff --git a/src/renderer/components/AccountChip.tsx b/src/renderer/components/AccountChip.tsxindex 7c9a33971..91937b54a 100644--- a/src/renderer/components/AccountChip.tsx+++ b/src/renderer/components/AccountChip.tsx@@ -35,8 +35,9 @@ export function AccountChip({}/**- * The chip for one node, resolved against live settings + agent status. `null` = render nothing- * (D6: the system account with only one identity in play is the unremarkable case).+ * The chip for one node, resolved against live settings + agent status. `null` = render nothing:+ * the system account with only one identity in play is the unremarkable case, and a chip on every+ * pane would say nothing.** Reads the DEFAULT agent-status store on purpose: it is the store Canvas's `agent:status`* listener writes and the store every one of these surfaces already reads its `status` from, sodiff --git a/src/renderer/components/kanban/ModalTerminal.tsx b/src/renderer/components/kanban/ModalTerminal.tsxindex 57651aeb3..75c81e17b 100644--- a/src/renderer/components/kanban/ModalTerminal.tsx+++ b/src/renderer/components/kanban/ModalTerminal.tsx@@ -101,8 +101,8 @@ export function ModalTerminal({ nodeId, spawn, searchOpen, onCloseSearch }: Modaconst fitRef = useRef<FitAddon | null>(null)const transportRef = useRef<LocalTransport | null>(null)const agentSessionId = useAgentStatus((s) => s.byId[nodeId]?.sessionId)- // MIRROR TerminalNode: transcript READS go to the account the session is actually running as- // (D5), which for a plain terminal is only ever the observed one. The spawn below keeps+ // MIRROR TerminalNode: transcript READS go to the account the session is actually running as,+ // which for a plain terminal is only ever the observed one. The spawn below keeps// `spawn.accountId` — launch identity stays creation-time.const observedAccount = useAgentStatus((s) => s.byId[nodeId]?.account)// …resolved against the live account list, so linking the dir repoints the reader at once.diff --git a/src/renderer/components/settings/sections/AccountsSection.tsx b/src/renderer/components/settings/sections/AccountsSection.tsxindex 0dfb4c24f..b55853171 100644--- a/src/renderer/components/settings/sections/AccountsSection.tsx+++ b/src/renderer/components/settings/sections/AccountsSection.tsx@@ -232,7 +232,7 @@ export function AccountsSection({ isActive }: { isActive: boolean }): React.JSX.// the path still works, which is why Browse is a convenience and never the only way in.const [browseUnsupported, setBrowseUnsupported] = useState(false)/**- * Config dirs SEEN running on this core that we have no account for (D7) — the one-click Link+ * Config dirs SEEN running on this core that we have no account for — the one-click Link* candidates. A primitive selector (newline-joined) so the settings page does not re-render on* every hook event of every node just to discover the same list again.*/@@ -845,7 +845,7 @@ export function AccountsSection({ isActive }: { isActive: boolean }): React.JSX.</div>)}- {/* LINK an existing config dir (D4). The other half of "several Claude logins": a user+ {/* LINK an existing config dir. The other half of "several Claude logins": a userwho already keeps `~/.claude-2` and drives it from their own shell function does notwant a new managed dir — they want THIS one to have an id, so the chip, the transcriptreaders and the pickers stop treating their second login as a stranger. Local only:diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsxindex d9cffe70e..823932b95 100644--- a/src/renderer/nodes/TerminalNode.tsx+++ b/src/renderer/nodes/TerminalNode.tsx@@ -1517,7 +1517,7 @@ export function TerminalNode({(data.cwd as string | undefined) !== parentWtPathconst status = useAgentStatus((s) => s.byId[id])/**- * Which Claude account this node is ACTUALLY on (D5). `data.accountId` is what nodeterm launched+ * Which Claude account this node is ACTUALLY on. `data.accountId` is what nodeterm launched* it as and is immutable; `status.account` is what the session's hooks reported — the only* identity a plain terminal running `CLAUDE_CONFIG_DIR=~/.claude-2 claude` ever has.*@@ -1802,7 +1802,7 @@ export function TerminalNode({sessionId: status?.sessionId,cwd: data.cwd as string | undefined,// A READER: the search hits the transcript index under whichever account the session is- // actually running as (D5), not the one the node was created with.+ // actually running as, not the one the node was created with.accountId: accountForReads,// The transcript index reads claude's JSONL through the same resolver, so it is gated on the// claude-transcript fact, NOT on the meter's `showUsage` — see lib/transcriptGates.ts.@@ -4603,8 +4603,9 @@ export function TerminalNode({// gemini's update_topic tool call. It is resolved at node creation and immutable thereafter, so// it does not belong in the dep array.//- // The ACCOUNT does not get that treatment any more: it is the effective one (D5), which for a- // plain terminal arrives with the first hook event, i.e. AFTER this effect mounted. It rides a+ // The ACCOUNT does not get that treatment any more: it is the EFFECTIVE one (the account the+ // session is observed running as), which for a plain terminal arrives with the first hook event,+ // i.e. AFTER this effect mounted. It rides a// ref (`accountForReadsRef`, refreshed every render) rather than the deps so a late observation// is picked up by the very next poll instead of tearing down and restarting the timer chain.useEffect(() => {diff --git a/src/server/agent-status.test.ts b/src/server/agent-status.test.tsindex b84421b31..41d6556fd 100644--- a/src/server/agent-status.test.ts+++ b/src/server/agent-status.test.ts@@ -269,7 +269,7 @@ describe('wireAgentStatus', () => {})})-// The transcript jail on THIS shell, and the linked half of it (design D4 / §3). Both raw+// The transcript jail on THIS shell, and the LINKED half of it. Both raw// listeners have to learn the same widening or the Server Edition silently keeps the pre-fix// behavior for a pane running the user's own `CLAUDE_CONFIG_DIR` — the "both raw listeners change// together" rule, which this repo has broken three times.diff --git a/src/server/index.ts b/src/server/index.tsindex d6f2db932..210ae64d5 100644--- a/src/server/index.ts+++ b/src/server/index.ts@@ -186,7 +186,7 @@ export async function startServer(const workspaceStore = new WorkspaceStore()settingsStore.init()- // The linked-account resolver's one source of truth on this shell (design D4). Registered as+ // The linked-account resolver's one source of truth on this shell. Registered as// soon as settings exist and BEFORE anything that resolves a config dir — the mirror settings// provider, `installHooksIntoLocalAccounts`, the transcript jail — because an unregistered// source means "no linked accounts", i.e. a linked row would resolve to a managed dir that does