@raidiant/notifai 4.0.0 → 5.0.0

package/src/install-hooks.test.ts

@@ -32,6 +32,8 @@ import {
   codexProjectRoot,
   findInstallations,
   codexHookIdentityHash,
+  codexCoexistenceNotes,
+  codexHomeNote,
   codexRepresentationProblems,
   codexTrustKey,
   codexTrustProblems,
@@ -270,7 +272,13 @@ describe('settings locations', () => {
     expect(settingsFile('codex', false, repo, {})).toBe(path.join(repo, '.codex', 'hooks.json'))
   })
 
-  it('stays on hooks.json when it alone has hooks, even if config.toml already exists', () => {
+  /**
+   * A `hooks.json` nobody has proven is Notifai's is not Notifai's to write.
+   * Joining it would avoid Codex's dual-representation warning, but a hook
+   * entry carries no owner, so the file may belong to a tool that regenerates
+   * it wholesale and would drop our handlers without a word.
+   */
+  it('writes config.toml rather than joining a hooks.json that is not ours', () => {
     const repo = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-foreign-json-'))
     const layer = path.join(repo, '.codex')
     mkdirSync(layer, { recursive: true })
@@ -284,7 +292,7 @@ describe('settings locations', () => {
       },
     })
 
-    expect(settingsFile('codex', false, repo, {})).toBe(path.join(layer, 'hooks.json'))
+    expect(settingsFile('codex', false, repo, {})).toBe(path.join(layer, 'config.toml'))
   })
 
   it('does not migrate our hooks when both representations already exist', () => {
@@ -557,25 +565,120 @@ describe('finding what is installed', () => {
     expect(codex?.handlers[0]?.groupIndex).toBe(1)
   })
 
-  it('names a Codex layer that loads both representations', () => {
+  /**
+   * The shape a session manager leaves behind: it owns `hooks.json` for its own
+   * agent lifecycle, Notifai sits in `config.toml`, and every handler fires
+   * exactly once. Reported as a Notifai failure for a whole release, it sent
+   * users to hand-edit a file another program regenerates — for nothing.
+   */
+  it('says nothing when the other representation holds only foreign hooks', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-foreign-rep-'))
+    const layer = path.join(cwd, '.codex')
+    mkdirSync(layer, { recursive: true })
+    applyPlan(path.join(layer, 'hooks.json'), {
+      hooks: {
+        Stop: [{ hooks: [{ type: 'command', command: '/bin/sh /opt/other-tool/hook.sh' }] }],
+        UserPromptSubmit: [
+          { hooks: [{ type: 'command', command: '/bin/sh /opt/other-tool/hook.sh' }] },
+        ],
+      },
+    })
+    writeFileSync(
+      path.join(layer, 'config.toml'),
+      stringifyToml({ hooks: ours() as unknown as Record<string, unknown> }),
+    )
+
+    expect(codexRepresentationProblems(cwd, { HOME: path.join(cwd, 'isolated-home') })).toEqual([])
+  })
+
+  it('names the foreign file and says Notifai will not touch it', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-coexist-'))
+    const layer = path.join(cwd, '.codex')
+    mkdirSync(layer, { recursive: true })
+    applyPlan(path.join(layer, 'hooks.json'), {
+      hooks: {
+        Stop: [{ hooks: [{ type: 'command', command: '/bin/sh /opt/other-tool/hook.sh' }] }],
+      },
+    })
+    writeFileSync(
+      path.join(layer, 'config.toml'),
+      stringifyToml({ hooks: ours() as unknown as Record<string, unknown> }),
+    )
+
+    const notes = codexCoexistenceNotes(cwd, { HOME: path.join(cwd, 'isolated-home') })
+    expect(notes).toHaveLength(1)
+    expect(notes[0]).toContain(path.join(layer, 'hooks.json'))
+    expect(notes[0]).toContain('Notifai will not modify it')
+    expect(notes[0]).toContain('not a Notifai fault')
+    expect(notes[0]).toContain("can end a turn before Notifai's answer arrives")
+  })
+
+  it('says nothing when Notifai is the only thing in the layer', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-coexist-alone-'))
+    const layer = path.join(cwd, '.codex')
+    mkdirSync(layer, { recursive: true })
+    writeFileSync(
+      path.join(layer, 'config.toml'),
+      stringifyToml({ hooks: ours() as unknown as Record<string, unknown> }),
+    )
+
+    expect(codexCoexistenceNotes(cwd, { HOME: path.join(cwd, 'isolated-home') })).toEqual([])
+  })
+
+  it('names the events a Notifai copy in each file would notify twice for', () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-dual-rep-'))
     const layer = path.join(cwd, '.codex')
     mkdirSync(layer, { recursive: true })
     applyPlan(path.join(layer, 'hooks.json'), { hooks: ours() })
     writeFileSync(
       path.join(layer, 'config.toml'),
-      ['[[hooks.Stop]]', '', '[[hooks.Stop.hooks]]', 'type = "command"', 'command = "gdh-stop"', ''].join(
-        '\n',
-      ),
+      stringifyToml({ hooks: ours() as unknown as Record<string, unknown> }),
     )
 
     const problems = codexRepresentationProblems(cwd, { HOME: path.join(cwd, 'isolated-home') })
     expect(problems).toHaveLength(1)
-    expect(problems[0]).toContain('loading hooks from both')
     expect(problems[0]).toContain(path.join(layer, 'hooks.json'))
     expect(problems[0]).toContain(path.join(layer, 'config.toml'))
-    expect(problems[0]).toMatch(/prefer a single representation for this layer/)
     expect(problems[0]).toMatch(/Stop/)
+    expect(problems[0]).toMatch(/notifies twice per turn for UserPromptSubmit, Stop, SessionEnd/)
+    expect(problems[0]).toMatch(/notifai hooks uninstall --harness codex/)
+    expect(problems[0]).not.toMatch(/--global/)
+  })
+
+  it('reports Notifai split across both files, where only one copy stays current', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-split-rep-'))
+    const layer = path.join(cwd, '.codex')
+    mkdirSync(layer, { recursive: true })
+    const { Stop, ...rest } = ours()
+    applyPlan(path.join(layer, 'hooks.json'), { hooks: { Stop: Stop! } })
+    writeFileSync(
+      path.join(layer, 'config.toml'),
+      stringifyToml({ hooks: rest as unknown as Record<string, unknown> }),
+    )
+
+    const problems = codexRepresentationProblems(cwd, { HOME: path.join(cwd, 'isolated-home') })
+    expect(problems).toHaveLength(1)
+    expect(problems[0]).toMatch(/split between them/)
+    expect(problems[0]).toMatch(/Stop/)
+    expect(problems[0]).toMatch(/UserPromptSubmit/)
+    expect(problems[0]).not.toMatch(/twice per turn/)
+  })
+
+  it('scopes the remedy to the global layer it found the duplicate in', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-global-rep-'))
+    const home = path.join(cwd, 'isolated-home')
+    const layer = path.join(home, '.codex')
+    mkdirSync(layer, { recursive: true })
+    applyPlan(path.join(layer, 'hooks.json'), { hooks: ours() })
+    writeFileSync(
+      path.join(layer, 'config.toml'),
+      stringifyToml({ hooks: ours() as unknown as Record<string, unknown> }),
+    )
+
+    const problems = codexRepresentationProblems(cwd, { HOME: home })
+    expect(problems).toHaveLength(1)
+    expect(problems[0]).toMatch(/notifai hooks uninstall --harness codex --global/)
+    expect(problems[0]).toMatch(/notifai hooks install --harness codex --global/)
   })
 
   it('reports handlers from either harness with their positions', () => {
@@ -725,16 +828,21 @@ describe('the OpenCode adapter', () => {
     expect(source).not.toContain('"permission.ask"')
   })
 
-  it('injects collected late answers into the next OpenCode user message', () => {
-    expect(source).toContain('hookSpecificOutput?.additionalContext')
-    expect(source).toContain('synthetic: true')
+  it('publishes the session pointer on a user message without injecting content', () => {
+    // The CLI has never emitted `hookSpecificOutput.additionalContext`, so the
+    // injection this used to assert could not fire. The handler earns its place
+    // by publishing the pointer that lets `notifai ask` find this session.
+    expect(source).toContain('"chat.message"')
+    expect(source).toContain('hook_event_name: "UserPromptSubmit"')
+    expect(source).not.toContain('additionalContext')
+    expect(source).not.toContain('synthetic: true')
   })
 
   it('injects an exact active-harness and session marker into OpenCode shells', () => {
     expect(source).toContain('"shell.env"')
     expect(source).toContain('NOTIFAI_ACTIVE_HARNESS')
     expect(source).toContain('NOTIFAI_ACTIVE_SESSION_ID')
-    expect(source).toContain('input.sessionID')
+    expect(source).toContain('input?.sessionID')
   })
 
   it('carries the ownership marker so a second checkout replaces it', () => {
@@ -960,3 +1068,115 @@ describe('Windows hook commands and discovery', () => {
     })
   })
 })
+
+/**
+ * `CODEX_HOME` replaces the Codex home rather than shadowing it: `codex doctor`
+ * with the variable set resolves every path inside it and never reads
+ * `~/.codex`. Installing to the account default anyway would write hooks the
+ * running agent cannot see, so Notifai follows the variable — and says so,
+ * because the same divergence is what makes a correct install look absent.
+ */
+describe('codex home note', () => {
+  it('is silent when CODEX_HOME is unset', () => {
+    expect(codexHomeNote({ HOME: '/home/someone' }, 'linux')).toBeNull()
+  })
+
+  it('is silent when CODEX_HOME names the account default', () => {
+    expect(
+      codexHomeNote({ HOME: '/home/someone', CODEX_HOME: '/home/someone/.codex' }, 'linux'),
+    ).toBeNull()
+  })
+
+  it('names both homes and why the other one is not read', () => {
+    const note = codexHomeNote({ HOME: '/home/someone', CODEX_HOME: '/runtime/home' }, 'linux')
+    expect(note).toContain('/runtime/home')
+    expect(note).toContain('/home/someone/.codex')
+    expect(note).toContain('not read by Codex in this shell')
+    expect(note).toContain('trust by absolute file path')
+  })
+})
+
+/**
+ * `config.toml` is the user's file and usually hand-written. Notifai adds three
+ * handlers to it and must hand back everything else exactly as it arrived —
+ * comments, ordering, and spacing included.
+ */
+describe('writing config.toml around what is already there', () => {
+  const layerFor = (name: string): string => {
+    const repo = mkdtempSync(path.join(os.tmpdir(), name))
+    const layer = path.join(repo, '.codex')
+    mkdirSync(layer, { recursive: true })
+    return layer
+  }
+
+  it('leaves every byte outside the hooks tables untouched', () => {
+    const layer = layerFor('notifai-toml-comments-')
+    const file = path.join(layer, 'config.toml')
+    const original = [
+      '# why this model, in the user\'s own words',
+      'model = "gpt-5.6"   # trailing note',
+      '',
+      '[mcp_servers.linear]',
+      '# a comment nobody but the user cares about',
+      'command = "npx"',
+      'args = ["-y", "linear-mcp"]',
+      '',
+    ].join('\n')
+    writeFileSync(file, original)
+
+    applyPlan(file, { ...loadSettings(file), hooks: ours() })
+
+    const after = readFileSync(file, 'utf8')
+    expect(after).toContain(original.trimEnd())
+    expect(after).toContain("# why this model, in the user's own words")
+    expect(after).toContain('# trailing note')
+    expect(after).toContain('# a comment nobody but the user cares about')
+    expect(parseToml(after)).toMatchObject({ model: 'gpt-5.6' })
+    expect(after).toContain('[[hooks.Stop]]')
+  })
+
+  it('replaces the hooks tables rather than appending a second copy', () => {
+    const layer = layerFor('notifai-toml-replace-')
+    const file = path.join(layer, 'config.toml')
+    writeFileSync(file, '# keep me\nmodel = "gpt-5.6"\n')
+
+    applyPlan(file, { ...loadSettings(file), hooks: ours() })
+    const once = readFileSync(file, 'utf8')
+    applyPlan(file, { ...loadSettings(file), hooks: ours() })
+    const twice = readFileSync(file, 'utf8')
+
+    expect(twice).toBe(once)
+    expect(twice).toContain('# keep me')
+    expect(twice.match(/\[\[hooks\.Stop\]\]/g) ?? []).toHaveLength(1)
+  })
+
+  it('carries the Codex trust store across a write', () => {
+    const layer = layerFor('notifai-toml-trust-')
+    const file = path.join(layer, 'config.toml')
+    writeFileSync(
+      file,
+      `model = "gpt-5.6"\n\n[hooks.state."${layer}/config.toml:stop:0:0"]\ntrusted_hash = "sha256:abc"\n`,
+    )
+
+    const existing = loadSettings(file)
+    applyPlan(file, { ...existing, hooks: { ...existing.hooks, ...ours() } })
+
+    const after = parseToml(readFileSync(file, 'utf8')) as {
+      hooks: { state: Record<string, { trusted_hash: string }> }
+    }
+    expect(after.hooks.state[`${layer}/config.toml:stop:0:0`]?.trusted_hash).toBe('sha256:abc')
+  })
+
+  it('falls back to a whole-file write when the splice cannot be trusted', () => {
+    const layer = layerFor('notifai-toml-inline-')
+    const file = path.join(layer, 'config.toml')
+    // An inline top-level `hooks` key cannot be spliced around, only rewritten.
+    writeFileSync(file, '# this comment is lost, and that is the safe outcome\nhooks = {}\n')
+
+    applyPlan(file, { hooks: ours() })
+
+    const after = readFileSync(file, 'utf8')
+    expect(after).toContain('[[hooks.Stop]]')
+    expect(after).not.toContain('hooks = {}')
+  })
+})

package/src/install-hooks.ts

@@ -42,8 +42,9 @@ const OPENCODE_EVENTS = [
  * location and the event set differ. Codex supports either a dedicated
  * `hooks.json` or inline `[hooks]` tables in the same layer's `config.toml`.
  * We default a hook-empty layer to inline config and preserve whichever single
- * representation a populated layer already uses. One representation per layer,
- * never both.
+ * representation a populated layer already uses. Notifai lives in one of them,
+ * never both — a layer whose other file holds someone else's hooks is that
+ * other tool's arrangement, and stays untouched.
  *
  * Cursor's native format is flat and lower-camel-cased, while OpenCode's
  * extension point is a JavaScript plugin module. Each therefore has a bounded
@@ -200,6 +201,22 @@ export const CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS = 3600
  */
 export const BLOCKING_STOP_TIMEOUT_SECONDS = 540
 
+/**
+ * Whether this harness's Stop handler runs detached from the turn.
+ *
+ * Three places decide this — the installer that declares `async: true`, the
+ * hook runtime that picks the waiter's wall clock, and doctor's check that the
+ * installed definition still has the right shape — and they must agree or the
+ * waiter outlives a turn nobody left open. They were three separate spellings
+ * of the same condition with nothing tying them together.
+ */
+export function stopHandlerIsDetached(
+  harness: Harness | undefined,
+  platform?: Parameters<typeof hookHostPlatform>[0],
+): boolean {
+  return harness === 'claude-code' && hookHostPlatform(platform) === 'posix'
+}
+
 /**
  * The turn-end handler, whose shape is the whole per-harness difference.
  *
@@ -216,7 +233,7 @@ function stopHandler(
   options: HookCommandOptions,
 ): HookHandler {
   const command = hookCommand(adapterPath, 'stop', harness, options)
-  if (harness === 'claude-code' && hookHostPlatform(options.platform) === 'posix') {
+  if (stopHandlerIsDetached(harness, options.platform)) {
     return { type: 'command', command, timeout: CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS, async: true }
   }
   if (harness === 'codex') return { type: 'command', command }
@@ -455,7 +472,19 @@ export function configHome(
   return path.join(home, fallback)
 }
 
-/** User-global Codex config directory for the active Codex installation. */
+/**
+ * User-global Codex config directory for the *running* Codex installation.
+ *
+ * `CODEX_HOME` replaces the home; it does not shadow it. `codex doctor` with
+ * the variable set reports that directory for every path it resolves and never
+ * consults `~/.codex` at all. So a session manager that points Codex at its own
+ * home makes `~/.codex` inert for those sessions, and installing there would
+ * write hooks the running agent never reads while reporting success.
+ *
+ * Following the variable is therefore correct even though it means install and
+ * doctor resolve different homes when run from different shells. Doctor names
+ * the home it inspected for exactly that reason — see `codexHomeNote`.
+ */
 export function codexGlobalDir(
   env: NodeJS.ProcessEnv = process.env,
   platform: NodeJS.Platform | HookHostPlatform = process.platform,
@@ -488,47 +517,56 @@ export function codexLayerPaths(
 
 export interface CodexLayerInspection {
   paths: CodexLayerPaths
+  /** Every event this file defines a handler for, whoever owns it. */
   jsonEvents: string[]
   tomlEvents: string[]
+  /** The subset of those events whose handlers are Notifai's own. */
+  ourJsonEvents: string[]
+  ourTomlEvents: string[]
   writeTarget: string
-  dual: boolean
-  overlappingEvents: string[]
 }
 
 /**
- * Which representation this Codex layer already uses.
+ * Where Notifai writes in this Codex layer: wherever Notifai already is, and
+ * inline `config.toml` otherwise.
+ *
+ * Codex supports `hooks.json` and inline `[hooks]` side by side, loads both,
+ * and runs every matching handler. The tempting rule is to join whichever
+ * representation the layer already uses, so Notifai never adds Codex's "prefer
+ * one representation per layer" startup warning. Notifai must not do that,
+ * because a hook entry carries no marker saying who owns it: a `hooks.json`
+ * full of foreign handlers may be one a person wrote by hand or one a tool
+ * regenerates wholesale, and those two look identical from here. Appending to
+ * the second kind gets Notifai's handlers deleted the next time that tool
+ * rewrites its file — silently, on a product whose entire job is reaching
+ * someone who is not at the keyboard to notice it stopped.
  *
- * Codex supports `hooks.json` and inline `[hooks]` side by side, but loads both
- * and runs every matching handler. Use inline config for a hook-empty layer and
- * preserve an existing single representation so installing Notifai never
- * invents a dual layer. When the layer is already dual, keep our handlers in
- * the representation that already contains them instead of silently migrating
- * them. `[hooks.state]` is the trust store, not a hook definition, so it does
- * not count as a representation.
+ * So Notifai only ever writes a file it owns. The warning it may cause is
+ * Codex accurately reporting that two handler sets merge and all of them fire;
+ * it is noise, and `codexCoexistenceNotes` explains it. That trade is
+ * deliberate: visible noise over silent non-delivery.
+ *
+ * Staying put where Notifai already is also keeps reinstalls idempotent and
+ * preserves the `[hooks.state]` trust hash, which Codex keys by file path and
+ * handler index. `[hooks.state]` is the trust store, not a hook definition, so
+ * it does not count as a representation.
  */
 export function inspectCodexLayer(paths: CodexLayerPaths): CodexLayerInspection {
   const jsonDocument = tryLoadSettings(paths.hooksJson)
   const tomlDocument = tryLoadSettings(paths.configToml)
   const jsonEvents = hookEventNames(jsonDocument?.hooks)
   const tomlEvents = hookEventNames(tomlDocument?.hooks)
-  const dual = jsonEvents.length > 0 && tomlEvents.length > 0
-  let writeTarget = paths.configToml
-  if (jsonEvents.length > 0 && tomlEvents.length === 0) {
-    writeTarget = paths.hooksJson
-  } else if (dual) {
-    const jsonOurs = documentHasOurHandlers(jsonDocument)
-    const tomlOurs = documentHasOurHandlers(tomlDocument)
-    if (jsonOurs && !tomlOurs) writeTarget = paths.hooksJson
-  }
+  const ourJsonEvents = ourHandlerEvents(jsonDocument)
+  const ourTomlEvents = ourHandlerEvents(tomlDocument)
+  const writeTarget =
+    ourJsonEvents.length > 0 && ourTomlEvents.length === 0 ? paths.hooksJson : paths.configToml
   return {
     paths,
     jsonEvents,
     tomlEvents,
+    ourJsonEvents,
+    ourTomlEvents,
     writeTarget,
-    dual,
-    overlappingEvents: dual
-      ? jsonEvents.filter((event) => tomlEvents.includes(event))
-      : [],
   }
 }
 
@@ -556,6 +594,23 @@ export function hookDefinitionFiles(
   return [paths.hooksJson, paths.configToml]
 }
 
+/**
+ * Layers where *Notifai* is installed in both Codex representations.
+ *
+ * A layer that uses `hooks.json` and inline `[hooks]` at once is not by itself
+ * a Notifai fault: Codex supports both, loads both, runs every matching
+ * handler, and already prints its own "prefer a single representation" warning
+ * at startup. Foreign handlers in the other file are the user's — often written
+ * by another tool that manages that file — and repeating Codex's warning as a
+ * Notifai failure demanded an edit to configuration Notifai does not own, for a
+ * condition where every handler still fires exactly once.
+ *
+ * What is ours to diagnose is Notifai in both files. Then one event really does
+ * send two Notification Requests per turn, and the copy outside the write
+ * target keeps firing an older definition after the next install refreshes only
+ * the other one. Uninstall strips Notifai from both files, so the remedy is
+ * exact — and it never touches a foreign handler.
+ */
 export function codexRepresentationProblems(
   cwd: string,
   env: NodeJS.ProcessEnv = process.env,
@@ -563,17 +618,71 @@ export function codexRepresentationProblems(
 ): string[] {
   return [false, true].flatMap((global) => {
     const layer = inspectCodexLayer(codexLayerPaths(global, cwd, env, platform))
-    if (!layer.dual) return []
-    const overlap =
-      layer.overlappingEvents.length > 0
-        ? ` Matching handlers from both files all run — this layer's ${layer.overlappingEvents.join(', ')} handlers will both fire.`
-        : ' Matching handlers from both files all run.'
+    if (layer.ourJsonEvents.length === 0 || layer.ourTomlEvents.length === 0) return []
+    const doubled = layer.ourJsonEvents.filter((event) => layer.ourTomlEvents.includes(event))
+    const consequence =
+      doubled.length > 0
+        ? `Codex runs every matching handler, so this layer notifies twice per turn for ${doubled.join(', ')}`
+        : `Codex runs both files, so this layer's Notifai handlers are split between them (${[...new Set([...layer.ourJsonEvents, ...layer.ourTomlEvents])].join(', ')}) and the next install refreshes only one file`
+    const scope = global ? ' --global' : ''
     return [
-      `loading hooks from both ${layer.paths.hooksJson} and ${layer.paths.configToml}; prefer a single representation for this layer.${overlap} Notifai preserves existing representations instead of migrating them automatically.`,
+      `Notifai hooks are installed in both ${layer.paths.hooksJson} and ${layer.paths.configToml}; ${consequence}. Run \`notifai hooks uninstall --harness codex${scope}\` and then \`notifai hooks install --harness codex${scope}\` to leave exactly one copy; foreign hooks in either file are left alone.`,
     ]
   })
 }
 
+/**
+ * Layers where Notifai and someone else each own one Codex representation.
+ *
+ * This is not a fault and never fails a check. Codex loads `hooks.json` and
+ * inline `[hooks]` together and runs every matching handler, so both sets fire
+ * exactly once — but Codex also prints "prefer one representation per layer"
+ * at startup, and a user who sees that warning deserves to know which file is
+ * Notifai's, which is not, and that Notifai will not touch the one it does not
+ * own. Saying nothing here is what made the warning look like Notifai's bug.
+ */
+export function codexCoexistenceNotes(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform | HookHostPlatform = process.platform,
+): string[] {
+  return [false, true].flatMap((global) => {
+    const layer = inspectCodexLayer(codexLayerPaths(global, cwd, env, platform))
+    const inJson = layer.ourJsonEvents.length > 0
+    const inToml = layer.ourTomlEvents.length > 0
+    if (inJson === inToml) return []
+    const ours = inJson ? layer.paths.hooksJson : layer.paths.configToml
+    const theirs = inJson ? layer.paths.configToml : layer.paths.hooksJson
+    const theirEvents = inJson ? layer.tomlEvents : layer.jsonEvents
+    if (theirEvents.length === 0) return []
+    const stop = theirEvents.includes('Stop')
+      ? " That file's Stop handler can end a turn before Notifai's answer arrives, because Codex lets any Stop handler stop continuation."
+      : ''
+    return [
+      `Notifai's Codex hooks are in ${ours}. ${theirs} defines hooks Notifai does not own (${theirEvents.join(', ')}) and Notifai will not modify it. Codex loads both files and runs every matching handler, so each set fires exactly once; its "prefer one representation per layer" startup warning is reporting that, not a Notifai fault.${stop}`,
+    ]
+  })
+}
+
+/**
+ * What `CODEX_HOME` is doing to this shell, when it is doing anything.
+ *
+ * Codex replaces its whole home when the variable is set, so hooks installed
+ * from a shell without it are simply absent here, and its trust store is keyed
+ * by absolute file path — a config copied between homes arrives untrusted.
+ * Both facts turn into "Notifai is not wired" reports that look like a bug in
+ * the installer, so doctor names the home it actually inspected.
+ */
+export function codexHomeNote(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform | HookHostPlatform = process.platform,
+): string | null {
+  const effective = codexGlobalDir(env, platform)
+  const accountDefault = path.join(harnessAccountHome(env, platform), '.codex')
+  if (effective === accountDefault) return null
+  return `CODEX_HOME points Codex at ${effective}, so ${accountDefault} is not read by Codex in this shell at all. Global hooks installed from a shell without CODEX_HOME live there and are invisible here; Codex also keys hook trust by absolute file path, so hooks copied between homes need approving again in each one.`
+}
+
 function tryLoadSettings(file: string): SettingsDocument | null {
   if (!existsSync(file)) return null
   try {
@@ -589,9 +698,10 @@ function hookEventNames(hooks: SettingsDocument['hooks']): string[] {
     .map(([event]) => event)
 }
 
-function documentHasOurHandlers(document: SettingsDocument | null): boolean {
-  if (document === null) return false
-  return locateHandlers(document).length > 0
+/** Events this document defines a Notifai handler for, by their event key. */
+function ourHandlerEvents(document: SettingsDocument | null): string[] {
+  if (document === null) return []
+  return [...new Set(locateHandlers(document).map((handler) => handler.event))]
 }
 
 /** Best-effort detection so `hooks install` usually needs no flags. */
@@ -868,13 +978,107 @@ export function removeHooks(existing: SettingsDocument, scriptPath: string): Mer
  */
 export function applyPlan(file: string, document: SettingsDocument | CursorSettingsDocument): void {
   const body = isTomlSettingsPath(file)
-    ? `${stringifyToml(document)}\n`
+    ? tomlBody(file, document as SettingsDocument)
     : `${JSON.stringify(document, null, 2)}\n`
   atomicWriteFileSync(file, body, {
     requireCurrentUserOwner: true,
   })
 }
 
+/**
+ * A TOML file rewritten around its `[hooks]` tables, not over them.
+ *
+ * `config.toml` is the user's, and for most of them it is hand-written: model
+ * choices, sandbox settings, MCP servers, and the comments explaining why. A
+ * parse-and-restringify write returns all of that as data and none of it as
+ * the document they wrote — comments gone, order normalized, spacing theirs no
+ * longer. Notifai adds three hook handlers; it has no business reflowing the
+ * rest.
+ *
+ * So everything outside `[hooks...]` is carried across as the exact bytes it
+ * came in as, and only the hooks tables are regenerated — re-emitted at the end
+ * of the file, because TOML does not care where a table sits and splicing into
+ * the middle would mean reasoning about a region line by line. If the result
+ * cannot be proven to parse back to the document asked for, this falls back to
+ * the whole-file rewrite rather than risk a file it half-understood.
+ */
+function tomlBody(file: string, document: SettingsDocument): string {
+  const whole = `${stringifyToml(document)}\n`
+  if (!existsSync(file)) return whole
+  let previous: string
+  try {
+    previous = readOwnedRegularFile(file)
+  } catch {
+    return whole
+  }
+  return spliceTomlHooks(previous, document) ?? whole
+}
+
+/** A TOML table header line, e.g. `[hooks.state."…"]` or `[[hooks.Stop]]`. */
+const TOML_TABLE_HEADER = /^\s*\[\[?([^[\]]+)\]\]?\s*(?:#.*)?$/
+
+/**
+ * The first key in a dotted TOML key path, unquoting it if it is quoted.
+ * `hooks.state."/a/b:stop:0:0"` is rooted at `hooks`, and so is `hooks.Stop`.
+ */
+function firstTomlKey(keyPath: string): string {
+  const trimmed = keyPath.trim()
+  const quote = trimmed[0]
+  if (quote === '"' || quote === "'") {
+    const end = trimmed.indexOf(quote, 1)
+    return end === -1 ? trimmed.slice(1) : trimmed.slice(1, end)
+  }
+  const dot = trimmed.indexOf('.')
+  return (dot === -1 ? trimmed : trimmed.slice(0, dot)).trim()
+}
+
+/**
+ * `source` with its hooks tables replaced by `document`'s, or null when that
+ * cannot be done safely — an inline top-level `hooks` key, or a result that
+ * does not parse back to exactly the document asked for.
+ */
+function spliceTomlHooks(source: string, document: SettingsDocument): string | null {
+  const kept: string[] = []
+  let inHooks = false
+  for (const line of source.split('\n')) {
+    const header = TOML_TABLE_HEADER.exec(line)
+    if (header !== null) inHooks = firstTomlKey(header[1] ?? '') === 'hooks'
+    // A root-level `hooks = …` or `hooks.x = …` would survive the splice and
+    // then collide with the tables appended below.
+    if (!inHooks && /^\s*hooks\s*[.=]/.test(line)) return null
+    if (!inHooks) kept.push(line)
+  }
+
+  const hooks = document.hooks
+  const body = hooks === undefined ? '' : stringifyToml({ hooks })
+  const head = kept.join('\n').trimEnd()
+  const spliced =
+    body === '' ? `${head}\n` : head === '' ? `${body}\n` : `${head}\n\n${body}\n`
+
+  try {
+    if (!sameTomlValue(parseToml(spliced), document)) return null
+  } catch {
+    return null
+  }
+  return spliced
+}
+
+/** Structural equality for parsed TOML, which carries dates as well as data. */
+function sameTomlValue(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime()
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false
+    return a.every((item, index) => sameTomlValue(item, b[index]))
+  }
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false
+  const left = a as Record<string, unknown>
+  const right = b as Record<string, unknown>
+  const keys = Object.keys(left)
+  if (keys.length !== Object.keys(right).length) return false
+  return keys.every((key) => key in right && sameTomlValue(left[key], right[key]))
+}
+
 export function loadSettings(file: string): SettingsDocument {
   return isTomlSettingsPath(file) ? readTomlSettings(file) : readSettings(file)
 }