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(integrations): never grandfather a fresh install on a later boot (#1226)
eneskirca725ac9ef43fd
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 refactormust 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 aREQUIRED 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.mdindex 0ccb26e1e..a26a36a28 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1236,7 +1236,10 @@ for an agent the user ENABLED in `settings.agentIntegrations`, removed when theyalone while they have not answered. Do not add a direct call to an installer; add the artifact tothe lifecycle (local) or to the `RemoteHooks` artifact plan (SSH), and give it a removal thatdeletes 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 indiff --git a/docs/agent-integration-consent.md b/docs/agent-integration-consent.mdindex 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 atboot, 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-timedismissible 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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(