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(server): require installAgentIntegrations, so no caller installs by omission
Howard Youngdahl88a885c69436
diff --git a/src/core/context-link.handler.test.ts b/src/core/context-link.handler.test.tsindex 3eaed956c..a2f89cda4 100644--- a/src/core/context-link.handler.test.ts+++ b/src/core/context-link.handler.test.ts@@ -38,7 +38,12 @@ function start(deps: ContextLinkDeps = {}): void {plat = fakePlatform({ userDataDir: dir })initPlatform(plat)captured = []- initContextLink(fakePty(), deps)+ // `false` is not incidental here: this file never redirects HOME, so before the flag became+ // required every run of this suite installed the get-linked-context skill into the developer's+ // own ~/.claude and merged nodeterm's marker block into their ~/.codex/AGENTS.md,+ // ~/.gemini/GEMINI.md and opencode AGENTS.md. Nothing under test needs those writes — the read+ // handler and the dataDir shim are registered regardless.+ initContextLink(fakePty(), deps, { installAgentIntegrations: false })}beforeEach(() => start())diff --git a/src/core/context-link.ts b/src/core/context-link.tsindex ea2bcd071..fb1084357 100644--- a/src/core/context-link.ts+++ b/src/core/context-link.ts@@ -279,10 +279,27 @@ export function setContextLinks(map: ContextLinkMap): Promise<void> {return writeChain}+/**+ * Boot Context Link: register the hook-server read handler, (re)write the shim under `dataDir`,+ * and — only when `options.installAgentIntegrations` says so — install the discovery surface into+ * the machine's REAL agent configuration directories (`~/.claude/skills/get-linked-context`, plus+ * the marker block in `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md` and opencode's `AGENTS.md`).+ *+ * `options` is REQUIRED and its flag is a plain `boolean`, deliberately: those instruction files+ * belong to the user and are loaded by every agent session on the machine, ours or not, so+ * writing them is a decision each caller owes an answer to (issue #490). The previous shape —+ * an optional options bag whose flag was read as `!== false` — meant the WRITE was what you got+ * by saying nothing, which is the wrong default direction for a filesystem effect outside our own+ * data dir, and it is exactly how a unit test that never thought about `HOME` came to rewrite the+ * developer's own `~/.codex/AGENTS.md` on every run. Same asymmetry as+ * `session-memory-service.ts`'s required `remote.isRemoteProject`: acting-without-knowing is a+ * compile error. `platformDeps` lost its default with it — every caller already passes one, and a+ * defaulted parameter in front of a required one is unreachable anyway.+ */export function initContextLink(ptyManager: PtyManager,- platformDeps: ContextLinkDeps = {},- options: { installAgentIntegrations?: boolean } = {}+ platformDeps: ContextLinkDeps,+ options: { installAgentIntegrations: boolean }): void {pty = ptyManagerdeps = platformDeps@@ -295,7 +312,7 @@ export function initContextLink(if (f.endsWith('.json')) fs.rmSync(path.join(d, f), { force: true })}writeCliFiles()- if (options.installAgentIntegrations !== false) {+ if (options.installAgentIntegrations) {installSkill()installAgentInstructions()}diff --git a/src/main/index.ts b/src/main/index.tsindex ec99195a9..0512496ad 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -3242,6 +3242,11 @@ app.whenReady().then(async () => {return null}}+ }, {+ // The desktop app is the surface Context Link's discovery was designed for, so it installs+ // the skill + instruction blocks. Stated rather than defaulted: the flag is required so no+ // caller can reach the write by omission (see initContextLink, issue #490).+ installAgentIntegrations: true})initCanvasControl()// Usage service + the mobile `usage` mirror block (mobile-usage-inbox): poll all local manageddiff --git a/src/server/canvas-control.ts b/src/server/canvas-control.tsindex 4f4852c67..d905a6313 100644--- a/src/server/canvas-control.ts+++ b/src/server/canvas-control.ts@@ -46,8 +46,27 @@ export interface ServerCanvasControlDeps {cliCaps?: () => Promise<ClaudeCliCaps>/** Test seam for the boot-populated shared Codex capability answer. */codexSharedIdentity?: () => Promise<boolean>- /** The server's installHooks gate. False keeps every real agent config directory untouched. */- installAgentIntegrations?: boolean+ /**+ * Whether to write this server's discovery surface into the machine's REAL agent configuration+ * directories: `~/.claude/skills/manage-nodeterm-canvas/SKILL.md`, the marker block in+ * `~/.codex/AGENTS.md` and `~/.gemini/GEMINI.md`, and the same skill in every managed Claude+ * account dir. `true` = the server's `installHooks` gate said yes; `false` = leave them alone.+ *+ * REQUIRED, and deliberately not defaulted. A service process editing files inside a user's+ * `$HOME` is a documented hazard in this repo — those instruction files are loaded by EVERY+ * agent session on the machine, nodeterm's or not, so a stray write follows the user into work+ * that has nothing to do with this server (issue #490). The previous shape was an OPTIONAL flag+ * read as `!== false`, which meant OMITTING the decision installed: the dangerous direction was+ * the one you got by saying nothing, and a new call site or a test that simply forgot the field+ * would rewrite the developer's own agent configuration with no diagnostic. Making it required+ * turns "I did not think about this" into a compile error — the same asymmetry+ * `session-memory-service.ts` uses for its `remote.isRemoteProject` dep, where+ * reading-without-knowing is likewise refused at the type level.+ *+ * Production passes `config.installHooks !== false`; every test must pass `false` unless it is+ * specifically exercising the install and has redirected `HOME` to a scratch directory first.+ */+ installAgentIntegrations: boolean}export interface ServerCanvasControl {@@ -130,7 +149,10 @@ export async function initServerCanvasControl(}}- if (deps.installAgentIntegrations !== false) {+ // Required field, so this is a plain read of a decision the caller had to make — never a+ // default. See ServerCanvasControlDeps.installAgentIntegrations for why omission must not+ // be spellable here.+ if (deps.installAgentIntegrations) {installSkillInto(path.join(os.homedir(), '.claude'))installInstructions(path.join(os.homedir(), '.codex', 'AGENTS.md'), instructions)installInstructions(path.join(os.homedir(), '.gemini', 'GEMINI.md'), instructions)diff --git a/src/server/context-link.test.ts b/src/server/context-link.test.tsindex b8e3ab7f8..e89b3c9a3 100644--- a/src/server/context-link.test.ts+++ b/src/server/context-link.test.ts@@ -152,7 +152,8 @@ describe('initServerContextLink', () => {nodes: [node('term-a', { title: 'Alpha' }), node('term-b', { title: 'Beta' })],bridges: [bridge('term-a', 'term-b')]}- ]+ ],+ installAgentIntegrations: false})// Without this registration the hook server answers every read with// "Context link is unavailable in this session." — the whole desktop-only symptom.@@ -168,7 +169,11 @@ describe('initServerContextLink', () => {})it('answers a node with no links, rather than pretending the feature is missing', async () => {- const { link, handler } = start({ ptyManager: fakePty(), canvases: () => [] })+ const { link, handler } = start({+ ptyManager: fakePty(),+ canvases: () => [],+ installAgentIntegrations: false+ })await link.refresh()const out = await handler({ verb: 'list', nodeId: 'term-a', args: {} })expect(out).toContain('No linked nodes')@@ -187,11 +192,30 @@ describe('initServerContextLink', () => {await link.stop()})+ // The other half of the pair. With the flag REQUIRED, every other case in this file says+ // `false`, so without this the install branch would have no coverage at all and "we stopped+ // writing into $HOME" would be indistinguishable from "we can no longer write into $HOME".+ // Safe to assert for real: `home` is a per-test scratch dir this suite points HOME at.+ it('installs the discovery surface into the agent config dirs when asked to', async () => {+ const { link, registered } = start({+ ptyManager: fakePty(),+ canvases: () => [],+ installAgentIntegrations: true+ })+ expect(registered).toBe(true)+ expect(existsSync(join(home, '.claude', 'skills', 'get-linked-context', 'SKILL.md'))).toBe(true)+ expect(readFileSync(join(home, '.codex', 'AGENTS.md'), 'utf8')).toContain(+ 'nodeterm:get-linked-context'+ )+ await link.stop()+ })+it('picks up a bridge drawn after boot', async () => {let bridges = [] as ReturnType<typeof bridge>[]const { link, handler } = start({ptyManager: fakePty(),- canvases: () => [{ id: 'p1', nodes: [node('term-a'), node('term-b', { title: 'Beta' })], bridges }]+ canvases: () => [{ id: 'p1', nodes: [node('term-a'), node('term-b', { title: 'Beta' })], bridges }],+ installAgentIntegrations: false})await link.refresh()expect(await handler({ verb: 'list', nodeId: 'term-a', args: {} })).toContain('No linked nodes')@@ -212,7 +236,11 @@ describe('initServerContextLink', () => {bridges: [bridge('term-a', 'term-b')]}]- const { link, handler } = start({ ptyManager: fakePty(), canvases })+ const { link, handler } = start({+ ptyManager: fakePty(),+ canvases,+ installAgentIntegrations: false+ })await link.refresh()expect(await handler({ verb: 'summary', nodeId: 'term-a', args: {} })).toContain('no conversation transcript yet'@@ -230,7 +258,8 @@ describe('initServerContextLink', () => {ptyManager: fakePty(),canvases: () => [{ id: 'p1', nodes: [node('term-a'), node('term-b')], bridges: [bridge('term-a', 'term-b')] }- ]+ ],+ installAgentIntegrations: false})// Neither the sweep nor onPersist awaits a refresh, so at close there is normally one in// flight. A stop that does not drain it lets link files land in a dataDir the caller is@@ -249,7 +278,8 @@ describe('initServerContextLink', () => {ptyManager: fakePty(),canvases: () => [{ id: 'p1', nodes: [node('term-a'), node('term-b')], bridges: [bridge('term-a', 'term-b')] }- ]+ ],+ installAgentIntegrations: false})await link.refresh()// The sweep runs every 15s for the life of the server: an unconditional rewrite would be adiff --git a/src/server/context-link.ts b/src/server/context-link.tsindex 2dad8e4e8..3a7e41e1d 100644--- a/src/server/context-link.ts+++ b/src/server/context-link.ts@@ -41,8 +41,22 @@ export interface ServerContextLinkDeps {/** nodeId → hook-fed transcript path; part of the change signature, not of the map. */transcriptOf?: (nodeId: string) => stringsweepMs?: number- /** Respect the server's installHooks gate for writes into agent configuration directories. */- installAgentIntegrations?: boolean+ /**+ * Whether to write the context-link discovery surface into the machine's REAL agent+ * configuration directories: `~/.claude/skills/get-linked-context/SKILL.md` and the marker+ * block in `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md` and opencode's `AGENTS.md`. `true` =+ * the server's `installHooks` gate said yes; `false` = leave them alone (the read handler and+ * the shim under `dataDir` are registered either way, so the feature still works for sessions+ * that already know about it).+ *+ * REQUIRED, and deliberately not defaulted — same reason as+ * `ServerCanvasControlDeps.installAgentIntegrations`: a service process writing into a user's+ * `$HOME` is a documented hazard (issue #490), those instruction files are read by every agent+ * session on the machine rather than only ours, and an OPTIONAL flag read as `!== false` made+ * the write the thing you got by saying nothing. Omission must be a compile error, not a+ * silent install.+ */+ installAgentIntegrations: boolean}/**