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(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.ts
index 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.ts
index 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 = ptyManager
deps = 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.ts
index 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 managed
diff --git a/src/server/canvas-control.ts b/src/server/canvas-control.ts
index 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.ts
index 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 a
diff --git a/src/server/context-link.ts b/src/server/context-link.ts
index 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) => string
sweepMs?: 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
}
/**