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.

docs(accounts): state the invariant instead of citing a plan nobody can open

freshjuicez46bf59611770
diff --git a/CLAUDE.md b/CLAUDE.md
index 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); no
per-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 config
dir the user already drives themselves (`export CLAUDE_CONFIG_DIR=~/.claude-2; claude …` in a
plain 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.ts
index 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 which
diff --git a/src/core/agents/hook-account-label.test.ts b/src/core/agents/hook-account-label.test.ts
index 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.ts
index 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 config
diff --git a/src/core/claude-accounts-core.test.ts b/src/core/claude-accounts-core.test.ts
index 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.ts
index 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.ts
index 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 pinned
diff --git a/src/core/claude-accounts-service.ts b/src/core/claude-accounts-service.ts
index 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 = null
try {
diff --git a/src/core/claude-config-dir.test.ts b/src/core/claude-config-dir.test.ts
index 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 added
diff --git a/src/core/claude-config-dir.ts b/src/core/claude-config-dir.ts
index 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.ts
index 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) continue
try {
- // 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.ts
index 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 the
diff --git a/src/renderer/components/AccountChip.test.tsx b/src/renderer/components/AccountChip.test.tsx
index 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.tsx
index 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, so
diff --git a/src/renderer/components/kanban/ModalTerminal.tsx b/src/renderer/components/kanban/ModalTerminal.tsx
index 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 }: Moda
const 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.tsx
index 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 user
who already keeps `~/.claude-2` and drives it from their own shell function does not
want a new managed dir — they want THIS one to have an id, so the chip, the transcript
readers 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.tsx
index 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) !== parentWtPath
const 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.ts
index 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.ts
index 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