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(integrations): never grandfather a fresh install on a later boot (#1226)

eneskirca725ac9ef43fd
diff --git a/CLAUDE.md b/CLAUDE.md
index 7ee045310..4d9a371d4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3032,10 +3032,21 @@ else, and its context links must keep classifying across restarts).
file is KEPT and listed in Settings, bounded at 20 — legacy blocks, our hook scripts);
**undecided** = nothing either way. Server `installHooks: false` is a hard veto. Rules a refactor
must not undo:
- - **Grandfathering is decided at boot from OUR files only** (non-empty `~/.nodeterm/agent-hooks/`
- or the userData shims), before `settingsStore.registerIpc()` and before any install: an existing
- install gets every agent + `hostDefault` enabled and a one-time notice; a new install gets NO
- record and a banner (Enable all / Choose… / Not now — "Not now" declines all, so it asks once).
+ - **Grandfathering is decided at boot from OUR files only** (a non-empty `~/.nodeterm/agent-hooks/`),
+ before `settingsStore.registerIpc()` and before any install: an existing install gets every
+ agent + `hostDefault` enabled and a one-time notice; a new install gets NO record and a banner
+ (Enable all / Choose… / Not now — "Not now" declines all, so it asks once). **Evidence must be a
+ file only a pre-consent build wrote** — the userData canvas/context shims are written on EVERY
+ boot, consent or not, and counting them grandfathered every fresh install on its second boot
+ (issue #1149: a systemd restart, the update timer, a desktop quit before the banner was
+ answered — 11 hook entries in `~/.claude/settings.json`, Codex `trusted_hash` pre-approvals).
+ And the decision is made ONCE: the first boot that finds no evidence writes
+ `<userData>/integration-consent-fresh-install` (`FRESH_INSTALL_MARKER`), after which no boot of
+ that install grandfathers — so a sibling install sharing `~/.nodeterm` (desktop + Server Edition)
+ enabling ITS hooks cannot grandfather this one either. A marker FILE, not a settings key:
+ `SettingsStore.init` reads an unreadable settings.json as the defaults, and a boot-time save of
+ a "not answered yet" record would overwrite the user's file. Same function, same call, both
+ shells.
- **No caller reaches an installer by omission.** `installManagedAgentHooks(agents)` takes a
REQUIRED set; `RemoteHooks` takes a REQUIRED plan (`NO_REMOTE_INTEGRATION` = fail-closed);
account add/link asks `currentIntegrationLifecycle()` and writes nothing when none is registered.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0ccb26e1e..a26a36a28 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1236,7 +1236,10 @@ for an agent the user ENABLED in `settings.agentIntegrations`, removed when they
alone while they have not answered. Do not add a direct call to an installer; add the artifact to
the lifecycle (local) or to the `RemoteHooks` artifact plan (SSH), and give it a removal that
deletes only what nodeterm wrote. `src/core/agent-integrations-wiring.test.ts` fails on a new call
-site. Do not merge text into `AGENTS.md` / `GEMINI.md` — agents get skills (progressive disclosure)
+site. **A file nodeterm writes at every boot is never evidence of a pre-consent install** — the
+grandfathering check (`detectExistingIntegrations`) counted the always-written userData shims and
+silently enabled every agent on a fresh install's second boot (#1149). Only a non-empty
+`~/.nodeterm/agent-hooks/` counts, and only on an install's first boot (the fresh-install marker). Do not merge text into `AGENTS.md` / `GEMINI.md` — agents get skills (progressive disclosure)
instead; the old blocks crowded codex's 32 KiB instruction budget.
Claude/Gemini settings must go through the guarded transactions in
diff --git a/docs/agent-integration-consent.md b/docs/agent-integration-consent.md
index 0f6fbc846..5ef1a4cc8 100644
--- a/docs/agent-integration-consent.md
+++ b/docs/agent-integration-consent.md
@@ -37,7 +37,11 @@ The Server Edition's `installHooks: false` is a hard veto that outranks every ch
## Default for existing vs new installs (product decision — confirm)
- **Existing installs are grandfathered as enabled.** Evidence is our own files only: a non-empty
- `~/.nodeterm/agent-hooks/` or the canvas/context shims under userData. The record is written at
+ `~/.nodeterm/agent-hooks/`. The canvas/context shims under userData are NOT evidence — every boot
+ writes them, consent or not, which grandfathered fresh installs on their second boot (#1149). The
+ decision is taken once: the first boot without evidence writes
+ `<userData>/integration-consent-fresh-install`, and no later boot of that install grandfathers
+ (not even when a sibling install sharing `~/.nodeterm` enabled its own hooks). The record is written at
boot, before the renderer loads settings and before any install, with every agent enabled and
`hostDefault: enabled`, so nobody's badges or canvas control stop on upgrade. A one-time
dismissible notice says integrations are now a choice and links to Settings → Agents.
diff --git a/src/core/agent-integrations.test.ts b/src/core/agent-integrations.test.ts
index f464b13b5..4f901d754 100644
--- a/src/core/agent-integrations.test.ts
+++ b/src/core/agent-integrations.test.ts
@@ -17,6 +17,7 @@ import {
createIntegrationLifecycle,
skillsFor,
detectExistingIntegrations,
+ FRESH_INSTALL_MARKER,
resolveIntegrationConsentAtBoot
} from './agent-integrations'
import { buildCanvasSkillBody, frameCanvasControlBlock } from './canvas-control-core'
@@ -296,6 +297,47 @@ describe('the existing-vs-new default', () => {
it('a new install (nothing of ours on disk) is NOT grandfathered — it is asked', () => {
expect(detectExistingIntegrations(userData, home)).toBe(false)
expect(resolveIntegrationConsentAtBoot(DEFAULT_SETTINGS, false)).toBeNull()
+ expect(existsSync(path.join(userData, FRESH_INSTALL_MARKER))).toBe(true)
+ })
+
+ // Issue #1149: our canvas/context shims are written on EVERY boot, consent or not, so they say
+ // nothing about a pre-consent install. Counting them grandfathered every fresh install on its
+ // second boot (a systemd restart, the update timer, a desktop quit before the prompt was answered).
+ it('our always-written shims are never evidence of an existing install', () => {
+ mkdirSync(path.join(userData, 'canvas-control'), { recursive: true })
+ mkdirSync(path.join(userData, 'context-links'), { recursive: true })
+ writeFileSync(path.join(userData, 'canvas-control', 'nodeterm.sh'), '#!/bin/sh\n')
+ writeFileSync(path.join(userData, 'context-links', 'context.sh'), '#!/bin/sh\n')
+ expect(detectExistingIntegrations(userData, home)).toBe(false)
+ })
+
+ it('the issue #1149 sequence: boot 1 writes the shims, boot 2 still asks', () => {
+ // Boot 1: nothing of ours on disk.
+ expect(resolveIntegrationConsentAtBoot(DEFAULT_SETTINGS, detectExistingIntegrations(userData, home))).toBeNull()
+ // …then the shells write the shims, as every boot does.
+ mkdirSync(path.join(userData, 'context-links'), { recursive: true })
+ writeFileSync(path.join(userData, 'context-links', 'context.sh'), '#!/bin/sh\n')
+ mkdirSync(path.join(userData, 'canvas-control'), { recursive: true })
+ writeFileSync(path.join(userData, 'canvas-control', 'nodeterm.sh'), '#!/bin/sh\n')
+ // Boot 2: the record is still empty and must stay so.
+ expect(resolveIntegrationConsentAtBoot(DEFAULT_SETTINGS, detectExistingIntegrations(userData, home))).toBeNull()
+ })
+
+ it('a fresh install is never grandfathered on a LATER boot, even once hook scripts appear', () => {
+ expect(detectExistingIntegrations(userData, home)).toBe(false)
+ // A sibling install sharing ~/.nodeterm (desktop + Server Edition) enabled its integrations.
+ mkdirSync(path.join(home, '.nodeterm', 'agent-hooks'), { recursive: true })
+ writeFileSync(path.join(home, '.nodeterm', 'agent-hooks', 'claude.sh'), '#!/bin/sh\n')
+ expect(detectExistingIntegrations(userData, home)).toBe(false)
+ expect(resolveIntegrationConsentAtBoot(DEFAULT_SETTINGS, false)).toBeNull()
+ })
+
+ it('an existing install is not marked fresh, so a failed grandfather save is retried next boot', () => {
+ mkdirSync(path.join(home, '.nodeterm', 'agent-hooks'), { recursive: true })
+ writeFileSync(path.join(home, '.nodeterm', 'agent-hooks', 'claude.sh'), '#!/bin/sh\n')
+ expect(detectExistingIntegrations(userData, home)).toBe(true)
+ expect(existsSync(path.join(userData, FRESH_INSTALL_MARKER))).toBe(false)
+ expect(detectExistingIntegrations(userData, home)).toBe(true)
})
it('an answered record is never rewritten at boot', () => {
diff --git a/src/core/agent-integrations.ts b/src/core/agent-integrations.ts
index b011e6149..a0b3aaf7e 100644
--- a/src/core/agent-integrations.ts
+++ b/src/core/agent-integrations.ts
@@ -12,7 +12,7 @@
// undecided → nothing at all, in either direction. A new install writes nothing until asked.
//
// The Server Edition's `installHooks: false` is a hard veto that outranks every choice.
-import { existsSync, readdirSync, rmSync } from 'fs'
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'fs'
import os from 'os'
import path from 'path'
import {
@@ -59,23 +59,57 @@ export function agentHooksDir(home: string = os.homedir()): string {
}
/**
- * Did a build from before this feature already integrate with this machine's agents? Evidence is
- * our OWN files only (never a guess from the user's config): the managed hook scripts dir every
- * install created, or our canvas/context shims under userData. True ⇒ grandfather as enabled.
+ * Written to userData by the first boot that found no evidence of an existing install. Its
+ * presence means "this install was new to nodeterm when it started", so no later boot may
+ * grandfather it — whatever has appeared on disk since (issue #1149). A marker FILE rather than a
+ * settings key: `SettingsStore.init` answers an unreadable settings.json with the defaults, and a
+ * boot-time save of a "not answered yet" record would then overwrite the user's file on every such
+ * boot.
+ */
+export const FRESH_INSTALL_MARKER = 'integration-consent-fresh-install'
+
+/**
+ * Did a build from before this feature already integrate with this machine's agents? Called once
+ * per boot, before any install, and DECIDES that once: the first boot that finds no evidence
+ * leaves `FRESH_INSTALL_MARKER` in userData, and every later boot of that install answers false.
+ *
+ * Evidence is our OWN files only (never a guess from the user's config): the managed hook scripts
+ * dir, which every pre-consent install filled at boot and which nothing now writes without an
+ * `'enabled'` choice. True ⇒ grandfather as enabled.
+ *
+ * NOT evidence: the canvas/context shims under userData (`canvas-control/nodeterm.sh`,
+ * `context-links/context.sh`). Both shells write them on EVERY boot, consent or not, so counting
+ * them grandfathered every fresh install on its second boot (issue #1149: a systemd restart, the
+ * update timer, a desktop quit before the first-run question was answered). The marker also
+ * covers hook scripts a SIBLING install (the desktop and the Server Edition share
+ * `~/.nodeterm/agent-hooks`) wrote under its own consent after this install's first boot.
*/
export function detectExistingIntegrations(userDataDir: string, home: string = os.homedir()): boolean {
- const nonEmpty = (d: string): boolean => {
- try {
- return readdirSync(d).length > 0
- } catch {
- return false
+ const marker = path.join(userDataDir, FRESH_INSTALL_MARKER)
+ let evidence = false
+ try {
+ evidence = readdirSync(agentHooksDir(home)).length > 0
+ } catch {
+ evidence = false
+ }
+ if (evidence) return !existsSync(marker)
+ // No evidence: the answer is false whether or not an earlier boot already left the marker, so the
+ // exclusive create is the only check needed (an existing marker is EEXIST).
+ try {
+ mkdirSync(userDataDir, { recursive: true })
+ writeFileSync(
+ marker,
+ `First boot ${new Date().toISOString()}: no earlier nodeterm agent integration was found, so ` +
+ 'this install is never grandfathered into one. Agent integrations are enabled only from ' +
+ 'the first-run question or Settings → Agents (issue #1149).\n',
+ { flag: 'wx', mode: 0o600 }
+ )
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
+ console.warn('[integrations] could not record the fresh-install marker', error)
}
}
- return (
- nonEmpty(agentHooksDir(home)) ||
- existsSync(path.join(userDataDir, 'canvas-control', 'nodeterm.sh')) ||
- existsSync(path.join(userDataDir, 'context-links', 'context.sh'))
- )
+ return false
}
/**
diff --git a/src/main/index.ts b/src/main/index.ts
index fff53dd72..63ba867d1 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -1652,8 +1652,9 @@ app.whenReady().then(async () => {
console.warn('[model-gateway] could not migrate the legacy API key to secret storage', error)
}
// Agent-integration consent (issue #744): an install from before this feature (our own hook
- // scripts / shims are on disk) is grandfathered as enabled, so nobody's badges or canvas control
- // silently stop on upgrade. Decided BEFORE the renderer can load settings and before any install.
+ // scripts are on disk) is grandfathered as enabled, so nobody's badges or canvas control silently
+ // stop on upgrade. Decided BEFORE the renderer can load settings and before any install, and once
+ // per install: a first boot without evidence is marked fresh and never grandfathered later (#1149).
try {
const grandfathered = resolveIntegrationConsentAtBoot(
settingsStore.get(),
diff --git a/src/server/index.ts b/src/server/index.ts
index 9edb87fe8..3c2153d5f 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -275,7 +275,8 @@ export async function startServer(
console.warn('[model-gateway] could not migrate the legacy API key to secret storage', error)
}
// Agent-integration consent (issue #744): grandfather an install from before this feature (our own
- // hook scripts / shims are on disk) as enabled, before any browser can load settings.
+ // hook scripts are on disk) as enabled, before any browser can load settings. Decided once per
+ // install: a first boot without evidence is marked fresh and never grandfathered later (#1149).
if (config.installHooks !== false) {
try {
const grandfathered = resolveIntegrationConsentAtBoot(