@raidiant/notifai 0.5.1 → 1.0.0

package/src/config-schema.ts

@@ -25,7 +25,7 @@ export type ConfigKind = 'string' | 'url' | 'integer' | 'boolean' | 'enum' | 'li
  * Which surface a key belongs to. Grouping is the difference between a flat
  * list of keys and a few short ones a reader can hold in their head.
  */
-export type ConfigGroup = 'questions' | 'delivery' | 'project' | 'diagnostics' | 'connection'
+export type ConfigGroup = 'questions' | 'delivery' | 'project' | 'diagnostics'
 
 export const CONFIG_GROUPS: { id: ConfigGroup; title: string; blurb: string }[] = [
   {
@@ -48,11 +48,6 @@ export const CONFIG_GROUPS: { id: ConfigGroup; title: string; blurb: string }[]
     title: 'Local logs',
     blurb: 'What this machine records about its own activity, so an agent can find out afterwards what happened.',
   },
-  {
-    id: 'connection',
-    title: 'Connection',
-    blurb: 'Which Notifai service this machine talks to. Most people never change this.',
-  },
 ]
 
 export interface ConfigKeyInfo {
@@ -234,17 +229,6 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     advanced: true,
     example: '3',
   },
-
-  base_url: {
-    label: 'Service URL',
-    group: 'connection',
-    kind: 'url',
-    summary: 'Which Notifai service this machine talks to',
-    detail:
-      'Points the CLI at a Notifai service. The default is the hosted service, and signing in stores the URL the credential belongs to, so this rarely needs setting by hand.\n\nChanging it does not move your credential: a URL that does not match the one you paired against will not authenticate.',
-    advanced: true,
-    example: 'https://notifai.fly.dev',
-  },
 }
 
 export function configInfo(key: ConfigKey): ConfigKeyInfo {
@@ -309,6 +293,7 @@ export function formatValue(key: ConfigKey, value: unknown): string {
 export function describeSource(source: string): { label: string; path: string | null } {
   if (source === 'default') return { label: 'default', path: null }
   if (source === 'flag') return { label: 'this command', path: null }
+  if (source === 'env') return { label: 'environment', path: null }
   const separator = source.indexOf(':')
   if (separator === -1) return { label: source, path: null }
   const layer = source.slice(0, separator)

package/src/config.test.ts

@@ -2,7 +2,7 @@ import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { afterAll, describe, expect, it } from 'vitest'
-import { loadConfig, sessionConfigPath } from './config.js'
+import { loadConfig, personalProjectConfigPath, sessionConfigPath } from './config.js'
 import { buildDraft } from './send.js'
 
 const tmp = mkdtempSync(path.join(os.tmpdir(), 'notifai-cli-'))
@@ -29,8 +29,9 @@ function setup(options: {
     writeFileSync(path.join(projectDir, 'config.toml'), options.projectToml)
   }
   if (options.projectLocalToml !== undefined) {
-    mkdirSync(projectDir, { recursive: true })
-    writeFileSync(path.join(projectDir, 'config.local.toml'), options.projectLocalToml)
+    const localFile = personalProjectConfigPath(project, { XDG_CONFIG_HOME: home })
+    mkdirSync(path.dirname(localFile), { recursive: true })
+    writeFileSync(localFile, options.projectLocalToml)
   }
   const state = path.join(home, 'state')
   const env = { XDG_CONFIG_HOME: home, XDG_STATE_HOME: state } as NodeJS.ProcessEnv
@@ -70,7 +71,31 @@ describe('harness config layers', () => {
     })
     const config = loadConfig({ cwd, env })
     expect(config.ask_notifications.value).toBe(false)
-    expect(config.ask_notifications.source).toMatch(/config\.local\.toml$/)
+    expect(config.ask_notifications.source).toMatch(/\/projects\/[0-9a-f]{32}\.toml$/)
+  })
+
+  it('ignores an in-tree config.local.toml leftover', () => {
+    const { env, cwd } = setup({ projectToml: 'ask_notifications = true\n' })
+    mkdirSync(path.join(cwd, '..', '.notifai'), { recursive: true })
+    writeFileSync(path.join(cwd, '..', '.notifai', 'config.local.toml'), 'ask_notifications = false\n')
+    expect(loadConfig({ cwd, env }).ask_notifications).toEqual({ value: true, source: expect.stringMatching(/^project:/) })
+  })
+
+  it('takes the service origin from NOTIFAI_BASE_URL, not from a config file', () => {
+    const { env, cwd } = setup({
+      projectToml: 'base_url = "https://attacker.example"\n',
+    })
+    expect(loadConfig({ cwd, env }).base_url).toEqual({
+      value: 'https://notifai.fly.dev',
+      source: 'default',
+    })
+    expect(
+      loadConfig({ cwd, env: { ...env, NOTIFAI_BASE_URL: 'https://selfhost.example' } }).base_url,
+    ).toEqual({ value: 'https://selfhost.example', source: 'env' })
+    expect(loadConfig({ cwd, env, flags: { base_url: 'https://flag.example' } }).base_url).toEqual({
+      value: 'https://flag.example',
+      source: 'flag',
+    })
   })
 
   it('keeps hostile or colliding session ids inside their own file', () => {

package/src/config.ts

@@ -15,16 +15,16 @@ import type { CLI_SOUNDS, INTERRUPTION_LEVELS } from '@raidiant/notifai-protocol
  * than in the agent's context, because context is lost to compaction and a
  * preference that evaporates mid-session is worse than none.
  *
- * `project-local` is `.notifai/config.local.toml`, intended to be gitignored.
- * `.notifai/config.toml` is intended for committed, shared configuration, so it
- * must not be where a personal "route my questions to my devices" preference
- * lands. The CLI does not edit a repository's ignore rules or create commits.
+ * `project-local` is a personal file under the user's config directory, keyed
+ * by the project root so a checkout does not have to gitignore anything. Shared
+ * `.notifai/config.toml` stays in the tree for committed project identity.
  *
  * `config show --explain` surfaces the winning layer per key.
  */
 
 export type ConfigSource =
   | 'flag'
+  | 'env'
   | `session:${string}`
   | `project-local:${string}`
   | `project:${string}`
@@ -92,7 +92,6 @@ export interface CliConfig {
 }
 
 export const CONFIG_KEYS = [
-  'base_url',
   'wait_seconds',
   'ttl_seconds',
   'collapse_key',
@@ -132,8 +131,10 @@ export const ENUM_CONFIG_VALUES: Partial<Record<ConfigKey, readonly string[]>> =
   log_level: LOG_LEVELS,
 }
 
+/** Compiled service origin. Not a user-facing setting; override with `--base-url` or `NOTIFAI_BASE_URL`. */
+export const DEFAULT_BASE_URL = 'https://notifai.fly.dev'
+
 const DEFAULTS = {
-  base_url: 'https://notifai.fly.dev',
   wait_seconds: 10,
   ttl_seconds: 86400,
   collapse_key: null,
@@ -243,9 +244,46 @@ export function findProjectConfigPath(startDir: string): string | null {
   return findProjectFile(startDir, 'config.toml')
 }
 
-/** Personal sibling of the shared project config; callers should keep it gitignored. */
-export function findProjectLocalConfigPath(startDir: string): string | null {
-  return findProjectFile(startDir, 'config.local.toml')
+/** Walk up from cwd looking for a `.git` file or directory (worktree or checkout). */
+function findGitRoot(startDir: string): string | null {
+  let dir = path.resolve(startDir)
+  for (;;) {
+    if (existsSync(path.join(dir, '.git'))) return canonicalDir(dir)
+    const parent = path.dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/**
+ * Stable identity for personal project preferences.
+ *
+ * Prefer the directory that owns the shared `.notifai/config.toml`, then the
+ * git checkout root, then cwd. Subdirectories of one project therefore share
+ * one personal file, and nothing is written inside the repository.
+ */
+export function personalProjectIdentity(cwd: string): string {
+  const projectConfig = findProjectConfigPath(cwd)
+  const root =
+    projectConfig !== null ? path.dirname(path.dirname(projectConfig)) : (findGitRoot(cwd) ?? cwd)
+  return createHash('sha256').update(canonicalDir(root)).digest('hex').slice(0, 32)
+}
+
+/** Personal project layer: `$XDG_CONFIG_HOME/notifai/projects/<identity>.toml`. */
+export function personalProjectConfigPath(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(globalConfigDir(env), 'projects', `${personalProjectIdentity(cwd)}.toml`)
+}
+
+/** Existing personal project file, or null when this checkout has none. */
+export function findProjectLocalConfigPath(
+  startDir: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string | null {
+  const file = personalProjectConfigPath(startDir, env)
+  return existsSync(file) ? file : null
 }
 
 /**
@@ -306,6 +344,24 @@ export interface FlagOverrides {
   interruption_level?: CliInterruptionLevel
 }
 
+/**
+ * Service origin is not a user setting. Flag and env are developer/self-host
+ * overrides; signed-in traffic still pins to the credential origin elsewhere.
+ */
+function resolveServiceUrl(
+  flags: FlagOverrides,
+  env: NodeJS.ProcessEnv,
+): ResolvedValue<string> {
+  if (typeof flags.base_url === 'string' && flags.base_url !== '') {
+    return { value: flags.base_url, source: 'flag' }
+  }
+  const fromEnv = env['NOTIFAI_BASE_URL']
+  if (typeof fromEnv === 'string' && fromEnv !== '') {
+    return { value: fromEnv, source: 'env' }
+  }
+  return { value: DEFAULT_BASE_URL, source: 'default' }
+}
+
 export function loadConfig(options: {
   cwd?: string
   env?: NodeJS.ProcessEnv
@@ -320,7 +376,7 @@ export function loadConfig(options: {
   const cwd = options.cwd ?? process.cwd()
   const projectPath = findProjectConfigPath(cwd)
   const projectRaw = projectPath ? readTomlFile(projectPath) : {}
-  const projectLocalPath = findProjectLocalConfigPath(cwd)
+  const projectLocalPath = findProjectLocalConfigPath(cwd, env)
   const projectLocalRaw = projectLocalPath ? readTomlFile(projectLocalPath) : {}
   const sessionId = options.sessionId ?? env['NOTIFAI_SESSION']
   const sessionPath = sessionId ? sessionConfigPath(sessionId, env) : null
@@ -344,7 +400,7 @@ export function loadConfig(options: {
   }
 
   return {
-    base_url: resolve('base_url'),
+    base_url: resolveServiceUrl(flags, env),
     wait_seconds: resolve('wait_seconds'),
     ttl_seconds: resolve('ttl_seconds'),
     collapse_key: resolve('collapse_key'),

package/src/harnesses.ts

@@ -3,6 +3,13 @@ export const HARNESSES = ['claude-code', 'codex', 'cursor', 'opencode'] as const
 
 export type Harness = (typeof HARNESSES)[number]
 
+export const HARNESS_LABELS: Record<Harness, string> = {
+  'claude-code': 'Claude Code',
+  codex: 'Codex',
+  cursor: 'Cursor',
+  opencode: 'OpenCode',
+}
+
 export type DeliveryRoute =
   | 'hook-continuation'
   | 'inbox-socket'

package/src/hook-adapter.test.ts

@@ -16,6 +16,7 @@ import {
   hookAdapterPath,
   inspectHookAdapter,
   installHookAdapter,
+  isNpxAdapterTarget,
 } from './hook-adapter.js'
 import { buildHookConfig, codexHookIdentityHash, type InstalledHandler } from './install-hooks.js'
 
@@ -76,7 +77,48 @@ describe('stable hook adapter', () => {
     expect(after).toEqual(before)
     expect(afterSource).not.toBe(beforeSource)
     expect(codexHookIdentityHash(stop(after))).toBe(codexHookIdentityHash(stop(before)))
-    expect(inspectHookAdapter(homeDir).target?.scriptPath).toBe(second)
+    const inspected = inspectHookAdapter(homeDir).target
+    expect(inspected && !isNpxAdapterTarget(inspected) ? inspected.scriptPath : null).toBe(second)
+  })
+
+  it('executes a pinned npx spec through npm-cli.js without evaluating it', () => {
+    const { root, homeDir } = isolated()
+    const npmCli = path.join(root, 'npm-cli.js')
+    writeFileSync(
+      npmCli,
+      'process.stdout.write(JSON.stringify(process.argv.slice(2)))\n',
+    )
+    const installed = installHookAdapter(
+      {
+        kind: 'npx',
+        execPath: process.execPath,
+        npmCli,
+        spec: '@raidiant/notifai@0.5.1',
+      },
+      homeDir,
+    )
+    const run = spawnSync(installed.path, ['hook', 'stop', '--owner', 'notifai'], {
+      encoding: 'utf8',
+    })
+
+    expect(run.status).toBe(0)
+    expect(JSON.parse(run.stdout)).toEqual([
+      'exec',
+      '--yes',
+      '--package',
+      '@raidiant/notifai@0.5.1',
+      '--',
+      'notifai',
+      'hook',
+      'stop',
+      '--owner',
+      'notifai',
+    ])
+    const inspected = inspectHookAdapter(homeDir)
+    expect(inspected.problems).toEqual([])
+    expect(inspected.target && isNpxAdapterTarget(inspected.target) ? inspected.target.spec : null).toBe(
+      '@raidiant/notifai@0.5.1',
+    )
   })
 
   it('uses a fixed home-relative pathname with no XDG input surface', () => {

package/src/hook-adapter.ts

@@ -14,11 +14,25 @@ import { withTargetFileLock } from './file-lock.js'
 const ADAPTER_MARKER = '# notifai managed hook adapter'
 const ADAPTER_VERSION = 1
 
-export interface HookAdapterTarget {
+export interface HookAdapterFileTarget {
+  kind?: 'file'
   execPath: string
   scriptPath: string
 }
 
+export interface HookAdapterNpxTarget {
+  kind: 'npx'
+  execPath: string
+  npmCli: string
+  spec: string
+}
+
+export type HookAdapterTarget = HookAdapterFileTarget | HookAdapterNpxTarget
+
+export function isNpxAdapterTarget(target: HookAdapterTarget): target is HookAdapterNpxTarget {
+  return target.kind === 'npx'
+}
+
 export interface HookAdapterInspection {
   path: string
   target: HookAdapterTarget | null
@@ -73,6 +87,20 @@ function assertUsableTarget(target: HookAdapterTarget): void {
   if (!exec.isFile() || (exec.mode & 0o111) === 0) {
     throw new Error(`Hook adapter runtime ${target.execPath} is not executable.`)
   }
+  if (isNpxAdapterTarget(target)) {
+    if (target.spec.trim() === '') {
+      throw new Error('Hook adapter npx spec is empty.')
+    }
+    try {
+      if (!statSync(target.npmCli).isFile()) {
+        throw new Error(`Hook adapter npm CLI ${target.npmCli} is not a regular file.`)
+      }
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith('Hook adapter npm CLI ')) throw err
+      throw new Error(`Hook adapter npm CLI ${target.npmCli} does not exist.`)
+    }
+    return
+  }
   try {
     if (!statSync(target.scriptPath).isFile()) {
       throw new Error(`Hook adapter CLI ${target.scriptPath} is not a regular file.`)
@@ -133,18 +161,51 @@ export function inspectHookAdapter(
     } catch {
       problems.push(`registered runtime ${target.execPath} is missing`)
     }
-    try {
-      if (!statSync(target.scriptPath).isFile()) {
-        problems.push(`registered CLI ${target.scriptPath} is not a regular file`)
+    if (isNpxAdapterTarget(target)) {
+      if (target.spec.trim() === '') problems.push('registered npx spec is empty')
+      try {
+        if (!statSync(target.npmCli).isFile()) {
+          problems.push(`registered npm CLI ${target.npmCli} is not a regular file`)
+        }
+      } catch {
+        problems.push(`registered npm CLI ${target.npmCli} is missing`)
+      }
+    } else {
+      try {
+        if (!statSync(target.scriptPath).isFile()) {
+          problems.push(`registered CLI ${target.scriptPath} is not a regular file`)
+        }
+      } catch {
+        problems.push(`registered CLI ${target.scriptPath} is missing`)
       }
-    } catch {
-      problems.push(`registered CLI ${target.scriptPath} is missing`)
     }
   }
   return { path: file, target, problems }
 }
 
 function hookAdapterSource(target: HookAdapterTarget): string {
+  if (isNpxAdapterTarget(target)) {
+    return `#!/bin/sh
+${ADAPTER_MARKER}
+# adapter-version: ${ADAPTER_VERSION}
+# target-kind: npx
+# target-exec-json: ${JSON.stringify(target.execPath)}
+# target-npm-cli-json: ${JSON.stringify(target.npmCli)}
+# target-spec-json: ${JSON.stringify(target.spec)}
+set -eu
+
+registered_exec=${quote(target.execPath)}
+registered_npm_cli=${quote(target.npmCli)}
+registered_spec=${quote(target.spec)}
+
+if [ -x "$registered_exec" ] && [ -f "$registered_npm_cli" ]; then
+  exec "$registered_exec" "$registered_npm_cli" exec --yes --package "$registered_spec" -- notifai "$@"
+fi
+
+printf '%s\n' 'Notifai hook adapter target is stale; run notifai hooks install.' >&2
+exit 127
+`
+  }
   return `#!/bin/sh
 ${ADAPTER_MARKER}
 # adapter-version: ${ADAPTER_VERSION}
@@ -165,15 +226,26 @@ exit 127
 }
 
 function parseTarget(contents: string): HookAdapterTarget | null {
+  const kind = /^# target-kind: (.+)$/m.exec(contents)?.[1]
   const exec = /^# target-exec-json: (.+)$/m.exec(contents)?.[1]
-  const script = /^# target-script-json: (.+)$/m.exec(contents)?.[1]
-  if (exec === undefined || script === undefined) return null
+  if (exec === undefined) return null
   try {
     const execPath: unknown = JSON.parse(exec)
+    if (typeof execPath !== 'string') return null
+    if (kind === 'npx') {
+      const npmCliRaw = /^# target-npm-cli-json: (.+)$/m.exec(contents)?.[1]
+      const specRaw = /^# target-spec-json: (.+)$/m.exec(contents)?.[1]
+      if (npmCliRaw === undefined || specRaw === undefined) return null
+      const npmCli: unknown = JSON.parse(npmCliRaw)
+      const spec: unknown = JSON.parse(specRaw)
+      return typeof npmCli === 'string' && typeof spec === 'string'
+        ? { kind: 'npx', execPath, npmCli, spec }
+        : null
+    }
+    const script = /^# target-script-json: (.+)$/m.exec(contents)?.[1]
+    if (script === undefined) return null
     const scriptPath: unknown = JSON.parse(script)
-    return typeof execPath === 'string' && typeof scriptPath === 'string'
-      ? { execPath, scriptPath }
-      : null
+    return typeof scriptPath === 'string' ? { execPath, scriptPath } : null
   } catch {
     return null
   }

package/src/hooks.test.ts

@@ -35,6 +35,7 @@ import {
 import { EXIT, askCommand, buildQuestions, hookRunCommand, type CommandDeps, type CommandIo } from './commands.js'
 import {
   loadConfig,
+  personalProjectConfigPath,
   projectSessionPointerPath,
   sanitizeSessionId,
   sessionConfigPath,
@@ -770,11 +771,9 @@ describe('config resolution inside a hook', () => {
     const h = harness([reply({ choice_id: 'allow' })])
     // A project that has turned the feature off.
     const project = mkdtempSync(path.join(os.tmpdir(), 'notifai-proj-'))
-    mkdirSync(path.join(project, '.notifai'), { recursive: true })
-    writeFileSync(
-      path.join(project, '.notifai', 'config.local.toml'),
-      'ask_notifications = false\n',
-    )
+    const localFile = personalProjectConfigPath(project, h.env)
+    mkdirSync(path.dirname(localFile), { recursive: true })
+    writeFileSync(localFile, 'ask_notifications = false\n')
     writeSessionState('c1', h.env, { last_prompt_at: AWAY })
     registerQuestion('c1', h.env, { question: 'Ship it?' })
 

package/src/install-hooks.test.ts

@@ -23,15 +23,18 @@ import {
   HARNESSES,
   applyPlan,
   detectHarness,
+  detectedHarnesses,
   buildHookConfig,
   codexLayerDir,
   codexProjectRoot,
   findInstallations,
   codexHookIdentityHash,
+  codexRepresentationProblems,
   codexTrustKey,
   codexTrustProblems,
   handlerEvent,
   hookCommand,
+  loadSettings,
   mergeHooks,
   removeHooks,
   settingsFile,
@@ -229,6 +232,60 @@ describe('settings locations', () => {
       path.join(os.homedir(), '.codex', 'hooks.json'),
     )
   })
+
+  it('writes Codex hooks into an existing inline [hooks] instead of inventing hooks.json', () => {
+    const repo = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-toml-layer-'))
+    mkdirSync(path.join(repo, '.codex'), { recursive: true })
+    writeFileSync(
+      path.join(repo, '.codex', 'config.toml'),
+      [
+        'model = "gpt-5.6"',
+        '',
+        '[[hooks.PostToolUse]]',
+        'matcher = "Bash"',
+        '',
+        '[[hooks.PostToolUse.hooks]]',
+        'type = "command"',
+        'command = "gdh-guard"',
+        '',
+        '[[hooks.Stop]]',
+        '',
+        '[[hooks.Stop.hooks]]',
+        'type = "command"',
+        'command = "gdh-stop"',
+        '',
+      ].join('\n'),
+    )
+
+    expect(settingsFile('codex', false, repo, {})).toBe(path.join(repo, '.codex', 'config.toml'))
+  })
+
+  it('does not treat the Codex trust store as an inline hook representation', () => {
+    const home = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-trust-only-'))
+    writeFileSync(
+      path.join(home, 'config.toml'),
+      `[hooks.state."${home}/hooks.json:stop:0:0"]\ntrusted_hash = "sha256:abc"\n`,
+    )
+
+    expect(settingsFile('codex', true, '/repo', { CODEX_HOME: home })).toBe(
+      path.join(home, 'hooks.json'),
+    )
+  })
+
+  it('keeps writing to inline [hooks] when a leftover hooks.json only holds Notifai', () => {
+    const repo = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-both-'))
+    const layer = path.join(repo, '.codex')
+    mkdirSync(layer, { recursive: true })
+    writeFileSync(
+      path.join(layer, 'config.toml'),
+      ['[[hooks.Stop]]', '', '[[hooks.Stop.hooks]]', 'type = "command"', 'command = "gdh-stop"', ''].join(
+        '\n',
+      ),
+    )
+    applyPlan(path.join(layer, 'hooks.json'), { hooks: ours() })
+
+    expect(settingsFile('codex', false, repo, {})).toBe(path.join(layer, 'config.toml'))
+  })
 })
 
 /**
@@ -422,9 +479,96 @@ describe('writing the settings file', () => {
     applyPlan(file, { hooks: {} })
     expect(statSync(file).mode & 0o777).toBe(0o600)
   })
+
+  it('merges into Codex config.toml without dropping trust state or foreign hooks', () => {
+    const dir = scratch()
+    const file = path.join(dir, 'config.toml')
+    writeFileSync(
+      file,
+      [
+        'model = "gpt-5.6"',
+        '',
+        '[features]',
+        'hooks = true',
+        '',
+        `[hooks.state."${file}:stop:0:0"]`,
+        'trusted_hash = "sha256:abc"',
+        '',
+        '[[hooks.Stop]]',
+        '',
+        '[[hooks.Stop.hooks]]',
+        'type = "command"',
+        'command = "gdh-stop"',
+        '',
+      ].join('\n'),
+    )
+
+    const merged = mergeHooks(loadSettings(file), ours(), SCRIPT)
+    applyPlan(file, merged.document)
+
+    const text = readFileSync(file, 'utf8')
+    expect(text).toContain('model = "gpt-5.6"')
+    expect(text).toContain('trusted_hash = "sha256:abc"')
+    expect(text).toContain('gdh-stop')
+    expect(text).toContain('hook stop')
+    expect(text).toContain('[[hooks.UserPromptSubmit]]')
+    expect(text).toContain('[[hooks.SessionEnd]]')
+    expect(merged.document.hooks?.['Stop']?.flatMap((group) => group.hooks)).toHaveLength(2)
+  })
 })
 
 describe('finding what is installed', () => {
+  it('reports Notifai handlers written as inline Codex [hooks]', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-find-toml-'))
+    const file = path.join(cwd, '.codex', 'config.toml')
+    mkdirSync(path.dirname(file), { recursive: true })
+    writeFileSync(
+      file,
+      [
+        '[[hooks.Stop]]',
+        '',
+        '[[hooks.Stop.hooks]]',
+        'type = "command"',
+        'command = "gdh-stop"',
+        '',
+        '[[hooks.Stop]]',
+        '',
+        '[[hooks.Stop.hooks]]',
+        'type = "command"',
+        `command = "${hookCommand(ADAPTER, 'stop', 'codex')}"`,
+        '',
+      ].join('\n'),
+    )
+
+    const found = findInstallations(cwd, { CODEX_HOME: path.join(cwd, 'no-codex-here') })
+    const codex = found.find((installation) => installation.harness === 'codex' && !installation.global)
+    expect(codex?.file).toBe(file)
+    expect(codex?.handlers.map((handler) => handler.event)).toEqual(['Stop'])
+    expect(codex?.handlers[0]?.handlerIndex).toBe(0)
+    expect(codex?.handlers[0]?.groupIndex).toBe(1)
+  })
+
+  it('names a Codex layer that loads both representations', () => {
+    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',
+      ),
+    )
+
+    const problems = codexRepresentationProblems(cwd, { CODEX_HOME: path.join(cwd, 'no-codex-here') })
+    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/)
+  })
+
   it('reports handlers from either harness with their positions', () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-find-'))
     mkdirSync(path.join(cwd, '.claude'), { recursive: true })
@@ -666,11 +810,19 @@ describe('detectHarness', () => {
   })
 
   it('returns null when the project itself names two harnesses', () => {
-    // Genuine ambiguity, and the caller must ask rather than pick. Not the
-    // same as having no evidence.
+    // Genuine ambiguity for a single-harness caller. detectedHarnesses lists
+    // both so install can wire them together.
     expect(detectHarness(project('.claude', '.codex'))).toBeNull()
   })
 
+  it('lists every project-named harness in declared order', () => {
+    const isolated = { HOME: mkdtempSync(path.join(os.tmpdir(), 'notifai-detect-home-')) }
+    expect(detectedHarnesses(project('.codex', '.claude'), isolated)).toEqual([
+      'claude-code',
+      'codex',
+    ])
+  })
+
   it('prefers project evidence over anything installed on the machine', () => {
     // The regression. Machine-global markers used to be OR-ed in per harness,
     // so a developer with several agent tools installed got a candidate for