@raidiant/notifai 0.4.0 → 0.5.0

package/src/commands.test.ts

@@ -12,6 +12,7 @@ import type {
 } from '@raidiant/notifai-protocol'
 import { describe, expect, it } from 'vitest'
 import { ApiCallError, NetworkError, type ApiClient } from './client.js'
+import type { ClaudeWakeAdapters } from './claude-wake.js'
 import {
   askCommand,
   accessStatusCommand,
@@ -172,6 +173,26 @@ function makeDeps(io: CapturedIo, client: ApiClient): CommandDeps {
   }
 }
 
+/**
+ * An environment that cannot see the machine running the suite.
+ *
+ * Harness discovery walks the real home directory whenever the environment
+ * names no override, so a developer with Notifai's own global hooks installed
+ * was silently running these cases against their own settings file — and a
+ * check that failed on that file failed only for them. Every setup case that
+ * asserts on readiness therefore gets its own home.
+ */
+function isolatedEnv(cwd: string): NodeJS.ProcessEnv {
+  const home = path.join(cwd, 'home')
+  return {
+    HOME: home,
+    CLAUDE_CONFIG_DIR: path.join(home, '.claude'),
+    CODEX_HOME: path.join(home, '.codex'),
+    XDG_CONFIG_HOME: path.join(cwd, 'config'),
+    XDG_STATE_HOME: path.join(cwd, 'state'),
+  }
+}
+
 const receipt: SubmissionReceipt = {
   request_id: 'req_reply_test',
   replayed: false,
@@ -1573,8 +1594,8 @@ describe('config surfaces', () => {
     const io = new InteractiveIo()
     expect(configShowCommand(configDeps(io), {})).toBe(EXIT.ok)
     const text = io.outLines.join('\n')
-    expect(text).toContain('Questions & presence')
-    expect(text).toContain('Whether sitting at this keyboard holds a question back')
+    expect(text).toContain('Questions')
+    expect(text).toContain('Optional delay before a question may reach your devices')
   })
 
   it('keeps --plain available to a human who wants the parseable form', () => {
@@ -1585,18 +1606,18 @@ describe('config surfaces', () => {
 
   it('explains one setting, and says so in JSON when asked', () => {
     const io = new InteractiveIo()
-    expect(configExplainCommand(configDeps(io), 'require_idle', { json: true })).toBe(EXIT.ok)
+    expect(configExplainCommand(configDeps(io), 'ask_notifications', { json: true })).toBe(EXIT.ok)
     const parsed = JSON.parse(io.outLines.join('\n')) as Record<string, unknown>
-    expect(parsed['key']).toBe('require_idle')
+    expect(parsed['key']).toBe('ask_notifications')
     expect(parsed['accepts']).toBe('true or false')
-    expect(parsed['detail']).toContain('Off (the default)')
-    expect(parsed['detail']).toContain('Turn this on')
+    expect(parsed['detail']).toContain('The master switch')
+    expect(parsed['detail']).toContain('Turn it off')
   })
 
   it('rejects an unknown setting and points at the nearest real one', () => {
     const io = new CapturedIo()
-    expect(configExplainCommand(configDeps(io), 'require_idl')).toBe(EXIT.usage)
-    expect(io.errLines[0]).toBe('Unknown setting "require_idl".')
+    expect(configExplainCommand(configDeps(io), 'ask_notification')).toBe(EXIT.usage)
+    expect(io.errLines[0]).toBe('Unknown setting "ask_notification".')
   })
 
   it('refuses an enum value the sender would later reject', async () => {
@@ -1809,10 +1830,10 @@ describe('interactive command UX', () => {
       EXIT.usage,
     )
     expect(io.errLines).toEqual([
-      'ask_grace_seconds must be between 0 and 334.',
+      'ask_grace_seconds must be between 0 and 360.',
       // Names the key and its range: `"1.5" is not an integer` left the reader
       // to work out which of the two settings they had just mistyped.
-      'ask_grace_seconds takes a whole number from 0s–334s, not "1.5".',
+      'ask_grace_seconds takes a whole number from 0s–360s, not "1.5".',
     ])
     expect(existsSync(configFile)).toBe(false)
   })
@@ -1953,7 +1974,7 @@ describe('init', () => {
       source: 'Raidiant-io/notifai',
       sourceType: 'github',
       sourceUrl: 'https://github.com/Raidiant-io/notifai.git',
-      ref: 'v0.4.0',
+      ref: 'v0.5.0',
     }
   }
 
@@ -1981,7 +2002,7 @@ describe('init', () => {
     return {
       ...makeDeps(io, client),
       cwd,
-      env: { XDG_CONFIG_HOME: path.join(cwd, 'config'), XDG_STATE_HOME: path.join(cwd, 'state') },
+      env: isolatedEnv(cwd),
       nativeSkills,
     }
   }
@@ -2056,7 +2077,7 @@ describe('init', () => {
   })
 
   it('pins the skill installer to the tagged public release syntax', () => {
-    expect(SKILLS_SOURCE).toBe('Raidiant-io/notifai#v0.4.0')
+    expect(SKILLS_SOURCE).toBe('Raidiant-io/notifai#v0.5.0')
     expect(SKILLS_SOURCE).not.toContain('@v')
   })
 
@@ -2079,7 +2100,7 @@ describe('init', () => {
             source: 'Raidiant-io/notifai',
             sourceType: 'github',
             sourceUrl: 'https://github.com/Raidiant-io/notifai.git',
-            ref: 'v0.4.0',
+            ref: 'v0.5.0',
           },
         ],
       }),
@@ -2311,7 +2332,7 @@ describe('init', () => {
     const deps: CommandDeps = {
       ...makeDeps(io, { health: async () => true } as unknown as ApiClient),
       cwd,
-      env: { XDG_CONFIG_HOME: path.join(cwd, 'config'), XDG_STATE_HOME: path.join(cwd, 'state') },
+      env: isolatedEnv(cwd),
       store: { load: () => null, save: () => {}, clear: () => {}, describe: () => 'empty store' },
     }
 
@@ -2336,7 +2357,7 @@ describe('init', () => {
     const deps = {
       ...makeDeps(io, client),
       cwd,
-      env: { XDG_CONFIG_HOME: path.join(cwd, 'config'), XDG_STATE_HOME: path.join(cwd, 'state') },
+      env: isolatedEnv(cwd),
     }
 
     expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.failed)
@@ -2409,7 +2430,7 @@ describe('init', () => {
     const deps = {
       ...makeDeps(io, client),
       cwd,
-      env: { XDG_CONFIG_HOME: path.join(cwd, 'config'), XDG_STATE_HOME: path.join(cwd, 'state') },
+      env: isolatedEnv(cwd),
     }
 
     expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.failed)
@@ -2451,7 +2472,7 @@ describe('init', () => {
     const deps: CommandDeps = {
       ...makeDeps(io, client),
       cwd,
-      env: { XDG_CONFIG_HOME: path.join(cwd, 'config'), XDG_STATE_HOME: path.join(cwd, 'state') },
+      env: isolatedEnv(cwd),
       now: () => now,
       sleep: async (milliseconds) => {
         now += milliseconds
@@ -2517,7 +2538,7 @@ describe('init', () => {
     const deps: CommandDeps = {
       ...makeDeps(io, client),
       cwd,
-      env: { XDG_CONFIG_HOME: path.join(cwd, 'config'), XDG_STATE_HOME: path.join(cwd, 'state') },
+      env: isolatedEnv(cwd),
       now: () => now,
       sleep: async (milliseconds) => {
         now += milliseconds
@@ -2557,7 +2578,7 @@ describe('init', () => {
     const deps = {
       ...makeDeps(io, client),
       cwd,
-      env: { XDG_CONFIG_HOME: path.join(cwd, 'config'), XDG_STATE_HOME: path.join(cwd, 'state') },
+      env: isolatedEnv(cwd),
     }
 
     expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.failed)
@@ -2601,7 +2622,7 @@ describe('init', () => {
     const deps: CommandDeps = {
       ...makeDeps(io, client),
       cwd,
-      env: { XDG_CONFIG_HOME: path.join(cwd, 'config'), XDG_STATE_HOME: path.join(cwd, 'state') },
+      env: isolatedEnv(cwd),
       now: () => now,
       sleep: async (milliseconds) => {
         now += milliseconds
@@ -2647,7 +2668,7 @@ describe('init', () => {
     const deps = {
       ...makeDeps(io, client),
       cwd,
-      env: { XDG_CONFIG_HOME: path.join(cwd, 'config'), XDG_STATE_HOME: '/dev/null' },
+      env: { ...isolatedEnv(cwd), XDG_STATE_HOME: '/dev/null' },
     }
 
     await expect(initCommand(deps, { hooks: false, skills: false })).resolves.toBe(EXIT.failed)
@@ -2674,7 +2695,7 @@ describe('init', () => {
     const deps = {
       ...makeDeps(io, client),
       cwd,
-      env: { XDG_CONFIG_HOME: path.join(cwd, 'config'), XDG_STATE_HOME: path.join(cwd, 'state') },
+      env: isolatedEnv(cwd),
     }
 
     expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.ok)
@@ -2692,7 +2713,7 @@ describe('init', () => {
         {
           ...makeDeps(doctorIo, client),
           cwd,
-          env: { XDG_CONFIG_HOME: path.join(cwd, 'config'), XDG_STATE_HOME: path.join(cwd, 'state') },
+          env: isolatedEnv(cwd),
         },
         {},
       ),
@@ -2752,7 +2773,7 @@ describe('init', () => {
     const deps = {
       ...makeDeps(io, client),
       cwd,
-      env: { XDG_CONFIG_HOME: path.join(cwd, 'config'), XDG_STATE_HOME: path.join(cwd, 'state') },
+      env: isolatedEnv(cwd),
     }
 
     expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.failed)
@@ -2788,7 +2809,7 @@ describe('init', () => {
       const deps = {
         ...makeDeps(io, client),
         cwd,
-        env: { XDG_CONFIG_HOME: stateRoot, XDG_STATE_HOME: stateRoot },
+        env: { ...isolatedEnv(cwd), XDG_CONFIG_HOME: stateRoot, XDG_STATE_HOME: stateRoot },
       }
       expect(
         await initCommand(deps, { projectId: 'shared-project', hooks: false, skills: false }),
@@ -2973,7 +2994,184 @@ describe('asking before the hooks have ever run', () => {
 
     expect(askCommand(deps, 'Ship it?', {})).toBe(EXIT.ok)
     expect(io.outLines).toContain(
-      'Question registered. Ask it in the conversation as usual and end your turn.',
+      'Question registered. Ask it in the conversation, state the concrete work you will resume when the answer arrives, then end your turn.',
+    )
+  })
+
+  // A harness exports its markers into everything it starts, so a nested
+  // harness sees its parent's markers alongside its own. Neither order between
+  // two markers can be right, and both nestings are ordinary: an orchestrator
+  // running inside Claude Code starts Codex, and the reverse happens just as
+  // often. The environment cannot settle it; the pointer index can.
+  it('routes to the live Codex thread when a Claude Code orchestrator started it', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-under-claude-'))
+    const io = new CapturedIo()
+    const env = {
+      ...isolatedEnv(cwd),
+      // Inherited from the parent Claude Code process, and unstrippable.
+      CLAUDECODE: '1',
+      CLAUDE_CODE_SESSION_ID: 'claude-orchestrator',
+      CODEX_THREAD_ID: 'codex-current-thread',
+    }
+    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env, now: () => 42 }
+
+    expect(hooksInstallCommand(deps, { harness: 'codex', execPath, scriptPath })).toBe(EXIT.ok)
+    // The configuration that made this unrecoverable: Claude Code hooks
+    // installed machine-wide match every directory, including this one.
+    expect(
+      hooksInstallCommand(deps, { harness: 'claude-code', global: true, execPath, scriptPath }),
+    ).toBe(EXIT.ok)
+    trustInstalledCodexHooks(cwd, env)
+    writeSessionState('codex-current-thread', env, { last_prompt_at: 42, last_stop_at: 41 })
+    writeProjectSession(cwd, env, 'codex-current-thread', 42, 'codex')
+    io.outLines = []
+
+    expect(askCommand(deps, 'Ship it?', {})).toBe(EXIT.ok)
+    expect(readSessionState('codex-current-thread', env).pending?.[0]?.question).toBe('Ship it?')
+    expect(readSessionState('claude-orchestrator', env).pending).toBeUndefined()
+  })
+
+  it('routes to the live Claude Code session when a Codex orchestrator started it', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-claude-under-codex-'))
+    const io = new CapturedIo()
+    const env = {
+      ...isolatedEnv(cwd),
+      CODEX_THREAD_ID: 'codex-orchestrator',
+      CLAUDECODE: '1',
+      CLAUDE_CODE_SESSION_ID: 'claude-current',
+    }
+    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env, now: () => 42 }
+
+    expect(hooksInstallCommand(deps, { harness: 'claude-code', execPath, scriptPath })).toBe(
+      EXIT.ok,
+    )
+    expect(hooksInstallCommand(deps, { harness: 'codex', execPath, scriptPath })).toBe(EXIT.ok)
+    trustInstalledCodexHooks(cwd, env)
+    // Both sessions are live here. The parent fired when its own turn began;
+    // the child fired for the turn that is running this command.
+    writeSessionState('codex-orchestrator', env, { last_prompt_at: 40, last_stop_at: 39 })
+    writeProjectSession(cwd, env, 'codex-orchestrator', 40, 'codex')
+    writeSessionState('claude-current', env, { last_prompt_at: 42, last_stop_at: 41 })
+    writeProjectSession(cwd, env, 'claude-current', 42, 'claude-code')
+    io.outLines = []
+
+    expect(askCommand(deps, 'Ship it?', {})).toBe(EXIT.ok)
+    expect(readSessionState('claude-current', env).pending?.[0]?.question).toBe('Ship it?')
+    expect(readSessionState('codex-orchestrator', env).pending).toBeUndefined()
+  })
+
+  it('judges the fired check against the active harness, not a global installation of another', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-fired-active-harness-'))
+    const io = new CapturedIo()
+    const env = {
+      ...isolatedEnv(cwd),
+      CLAUDECODE: '1',
+      CLAUDE_CODE_SESSION_ID: 'claude-orchestrator',
+      CODEX_THREAD_ID: 'codex-current-thread',
+    }
+    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env, now: () => 42 }
+
+    expect(hooksInstallCommand(deps, { harness: 'codex', execPath, scriptPath })).toBe(EXIT.ok)
+    expect(
+      hooksInstallCommand(deps, { harness: 'claude-code', global: true, execPath, scriptPath }),
+    ).toBe(EXIT.ok)
+    trustInstalledCodexHooks(cwd, env)
+    writeSessionState('codex-current-thread', env, { last_prompt_at: 42, last_stop_at: 41 })
+    writeProjectSession(cwd, env, 'codex-current-thread', 42, 'codex')
+
+    const readiness = await assessReadiness(deps)
+    const fired = readiness.states.find((state) => state.id === 'hooks-fired')
+    // The Codex hooks fired. A missing Claude Code pointer says nothing about
+    // that, and telling this agent to send a Claude Code prompt is advice it
+    // cannot act on: it would refuse to ask, forever.
+    expect(fired?.status).toBe('ready')
+    expect(fired?.detail).toMatch(/active Codex session/i)
+    expect(fired?.detail).not.toMatch(/Claude Code/i)
+  })
+
+  it('advises every harness whose markers are present when none of them has fired here', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-fired-contested-'))
+    const io = new CapturedIo()
+    const env = {
+      ...isolatedEnv(cwd),
+      CLAUDECODE: '1',
+      CLAUDE_CODE_SESSION_ID: 'claude-orchestrator',
+      CODEX_THREAD_ID: 'codex-current-thread',
+    }
+    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env, now: () => 42 }
+
+    expect(hooksInstallCommand(deps, { harness: 'codex', execPath, scriptPath })).toBe(EXIT.ok)
+    expect(
+      hooksInstallCommand(deps, { harness: 'claude-code', global: true, execPath, scriptPath }),
+    ).toBe(EXIT.ok)
+    trustInstalledCodexHooks(cwd, env)
+
+    const readiness = await assessReadiness(deps)
+    const fired = readiness.states.find((state) => state.id === 'hooks-fired')
+    expect(fired?.status).toBe('optional-gap')
+    expect(fired?.detail).toMatch(/Claude Code/)
+    expect(fired?.detail).toMatch(/Codex: send one prompt/)
+
+    io.errLines = []
+    expect(askCommand(deps, 'Ship it?', {})).toBe(EXIT.usage)
+    expect(io.errLines.join(' ')).toMatch(/Several harness markers are present/i)
+  })
+
+  it('makes one work-resumption commitment per offered answer part of the asking turn', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-ask-commitment-'))
+    const io = new CapturedIo()
+    const env = {
+      XDG_CONFIG_HOME: path.join(cwd, 'config'),
+      XDG_STATE_HOME: path.join(cwd, 'state'),
+      CODEX_HOME: path.join(cwd, 'codex-home'),
+      CODEX_THREAD_ID: 'codex-commitment-thread',
+    }
+    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env, now: () => 42 }
+
+    expect(hooksInstallCommand(deps, { harness: 'codex', execPath, scriptPath })).toBe(EXIT.ok)
+    trustInstalledCodexHooks(cwd, env)
+    writeSessionState('codex-commitment-thread', env, { last_prompt_at: 42, last_stop_at: 41 })
+    writeProjectSession(cwd, env, 'codex-commitment-thread', 42, 'codex')
+    io.outLines = []
+
+    expect(
+      askCommand(deps, 'Which environment should I deploy to?', {
+        choice: ['Staging', 'Production', 'Cancel'],
+      }),
+    ).toBe(EXIT.ok)
+
+    const said = io.outLines.join('\n')
+    expect(said).toContain('Before ending this turn')
+    for (const answer of ['Staging', 'Production', 'Cancel']) {
+      expect(said).toContain(`If the answer is "${answer}"`)
+    }
+    expect(said).toContain('unexpected typed answer')
+    expect(said).toContain('work you will resume')
+    expect(said).toContain('without asking the user to confirm again')
+    expect(said).toContain('not as approval')
+    expect(said).toContain('cannot answer a harness permission prompt or interactive picker')
+  })
+
+  it('requires a concrete fallback for free-text answers before the turn ends', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-ask-free-text-'))
+    const io = new CapturedIo()
+    const env = {
+      XDG_CONFIG_HOME: path.join(cwd, 'config'),
+      XDG_STATE_HOME: path.join(cwd, 'state'),
+      CODEX_HOME: path.join(cwd, 'codex-home'),
+      CODEX_THREAD_ID: 'codex-free-text-thread',
+    }
+    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env, now: () => 42 }
+
+    expect(hooksInstallCommand(deps, { harness: 'codex', execPath, scriptPath })).toBe(EXIT.ok)
+    trustInstalledCodexHooks(cwd, env)
+    writeSessionState('codex-free-text-thread', env, { last_prompt_at: 42, last_stop_at: 41 })
+    writeProjectSession(cwd, env, 'codex-free-text-thread', 42, 'codex')
+    io.outLines = []
+
+    expect(askCommand(deps, 'What rollout adjustment should I make?', {})).toBe(EXIT.ok)
+    expect(io.outLines.join('\n')).toContain(
+      'For the free-text answer: state how its content will determine the concrete work you resume.',
     )
   })
 
@@ -3039,7 +3237,7 @@ describe('asking before the hooks have ever run', () => {
                   source: 'Raidiant-io/notifai',
                   sourceType: 'github',
                   sourceUrl: 'https://github.com/Raidiant-io/notifai.git',
-                  ref: 'v0.4.0',
+                  ref: 'v0.5.0',
                 },
               ]
             : [],
@@ -3295,7 +3493,7 @@ describe('asking before the hooks have ever run', () => {
     mkdirSync(path.join(cwd, '.notifai'), { recursive: true })
     writeFileSync(
       path.join(cwd, '.notifai', 'config.local.toml'),
-      'ask_notifications = false\nrequire_idle = false\naway_after_seconds = 45\nask_grace_seconds = 90\nhook_reply_timeout_seconds = 120\n',
+      'ask_notifications = false\nask_grace_seconds = 90\n',
     )
     const io = new CapturedIo()
     const deps = { ...makeDeps(io, {} as ApiClient), cwd, env: {} }
@@ -3305,29 +3503,167 @@ describe('asking before the hooks have ever run', () => {
     const said = io.outLines.join('\n')
     expect(said).toContain('Question routing settings:')
     expect(said).toContain('ask_notifications=false (project-local:')
-    expect(said).toContain('require_idle=false (project-local:')
-    expect(said).toContain('away_after_seconds=45 (project-local:')
     expect(said).toContain('ask_grace_seconds=90 (project-local:')
-    expect(said).toContain('hook_reply_timeout_seconds=120 (project-local:')
+    // Nothing about where the user is standing is listed, because nothing
+    // about where they are standing decides anything any more.
+    expect(said).not.toMatch(/require_idle|away_after_seconds|hook_reply_timeout_seconds/)
   })
 
-  it('keeps an installed Stop timeout valid when runtime timing preferences change', async () => {
+  it('keeps a freshly installed Stop definition valid when timing preferences change', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-doctor-timeout-drift-'))
     const io = new CapturedIo()
-    const env = { XDG_STATE_HOME: path.join(cwd, 'state'), CLAUDE_CONFIG_DIR: path.join(cwd, 'claude') }
-    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env }
+    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env: isolatedEnv(cwd) }
     expect(hooksInstallCommand(deps, { harness: 'claude-code', execPath, scriptPath })).toBe(
       EXIT.ok,
     )
     mkdirSync(path.join(cwd, '.notifai'), { recursive: true })
-    writeFileSync(path.join(cwd, '.notifai', 'config.local.toml'), 'ask_grace_seconds = 400\n')
+    writeFileSync(path.join(cwd, '.notifai', 'config.local.toml'), 'ask_grace_seconds = 300\n')
     io.outLines = []
 
     await doctorCommand(deps, {})
-    expect(io.outLines.join('\n')).toMatch(/ok\s+hooks \(timeout\)/)
-    expect(io.outLines.join('\n')).toContain(
-      'declared Stop timeouts match the fixed 540s process budget where required; Codex uses host defaults',
+    expect(io.outLines.join('\n')).toMatch(/ok\s+hooks \(stop shape\)/)
+  })
+
+  it('names an old blocking Claude Stop handler as the reason no wake can happen', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-doctor-stale-shape-'))
+    const io = new CapturedIo()
+    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env: isolatedEnv(cwd) }
+    // Exactly what every build before the asynchronous waiter wrote: a blocking
+    // handler with the old ceiling. It looks installed and it fires, but the
+    // waiter would hold the turn and then be killed at Claude's silent default.
+    mkdirSync(path.join(cwd, '.claude'), { recursive: true })
+    applyPlan(path.join(cwd, '.claude', 'settings.local.json'), {
+      hooks: {
+        Stop: [
+          {
+            hooks: [
+              {
+                type: 'command',
+                command: `'${path.join(cwd, 'home', '.notifai', 'bin', 'hook-adapter')}' hook stop --owner notifai --harness claude-code`,
+                timeout: 540,
+              },
+            ],
+          },
+        ],
+      },
+    })
+
+    await doctorCommand(deps, {})
+    const out = io.outLines.join('\n')
+    expect(out).toMatch(/FAIL\s+hooks \(stop shape\)/)
+    expect(out).toContain('needs `async: true`')
+    expect(out).toContain('kills the backgrounded waiter at its 600s default')
+  })
+
+  /** A configured Claude Code project with one live session claiming `pid`. */
+  function claudeWakeDeps(
+    io: CapturedIo,
+    descriptor: (pid: number) => unknown,
+  ): { deps: CommandDeps; cwd: string } {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-doctor-wake-'))
+    const base = {
+      ...makeDeps(io, {} as ApiClient),
+      cwd,
+      env: { ...isolatedEnv(cwd), CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 'sess-live' },
+      claudeSourcePid: 4242,
+      claudeWake: { readDescriptor: descriptor } as unknown as ClaudeWakeAdapters,
+    }
+    expect(hooksInstallCommand(base, { harness: 'claude-code', execPath, scriptPath })).toBe(
+      EXIT.ok,
     )
+    io.outLines = []
+    return { deps: base, cwd }
+  }
+
+  it('reports a live Claude session as reachable without connecting to its socket', async () => {
+    const io = new CapturedIo()
+    const socket = path.join(mkdtempSync(path.join(os.tmpdir(), 'cc-socks-')), '4242.sock')
+    writeFileSync(socket, '')
+    const { deps } = claudeWakeDeps(io, (pid) => ({
+      pid,
+      sessionId: 'sess-live',
+      cwd: '/tmp',
+      startedAt: 1,
+      procStart: 'x',
+      version: '2.1.228',
+      peerProtocol: 1,
+      messagingSocketPath: socket,
+      status: 'idle',
+    }))
+
+    await doctorCommand(deps, {})
+    const out = io.outLines.join('\n')
+    expect(out).toMatch(/ok\s+hooks \(wake route\)/)
+    expect(out).toContain(socket)
+    expect(out).toContain('an answer can start a turn here without you')
+    // Doctor never widens the user's inbound policy to make Notifai work: the
+    // poster is the session's own hook child and needs no such permission.
+    expect(out).not.toContain('crossSessionInbound')
+  })
+
+  it('names a --bare session as the reason an answer would wait for the next turn', async () => {
+    const io = new CapturedIo()
+    const { deps } = claudeWakeDeps(io, () => {
+      throw new Error('ENOENT: no such file or directory')
+    })
+
+    expect(await doctorCommand(deps, {})).toBe(EXIT.failed) // unreachable test server
+    const out = io.outLines.join('\n')
+    // Honest, and not a blocker: nothing is lost, it simply arrives later.
+    expect(out).toMatch(/--\s+hooks \(wake route\)/)
+    expect(out).toContain('`--bare` binds no inbox socket')
+    expect(out).toContain("at this session's next turn")
+    expect(out).not.toMatch(/FAIL\s+hooks \(wake route\)/)
+  })
+
+  it('fails closed on an inbox protocol it does not recognise', async () => {
+    const io = new CapturedIo()
+    const socket = path.join(mkdtempSync(path.join(os.tmpdir(), 'cc-socks-')), '4242.sock')
+    writeFileSync(socket, '')
+    const { deps } = claudeWakeDeps(io, (pid) => ({
+      pid,
+      sessionId: 'sess-live',
+      cwd: '/tmp',
+      startedAt: 1,
+      procStart: 'x',
+      version: '2.1.228',
+      peerProtocol: 7,
+      messagingSocketPath: socket,
+      status: 'idle',
+    }))
+
+    await doctorCommand(deps, {})
+    const out = io.outLines.join('\n')
+    expect(out).toContain('speaks inbox protocol 7')
+    expect(out).toContain('refusing to guess at an undocumented wire format')
+  })
+
+  it('reports Codex resume readiness from its writer-lock directory alone', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-doctor-codex-wake-'))
+    const io = new CapturedIo()
+    const env = {
+      ...isolatedEnv(cwd),
+      CODEX_THREAD_ID: '9f1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8',
+    }
+    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env }
+    expect(hooksInstallCommand(deps, { harness: 'codex', execPath, scriptPath })).toBe(EXIT.ok)
+
+    io.outLines = []
+    await doctorCommand(deps, {})
+    expect(io.outLines.join('\n')).toContain('nothing can be resumed: no thread-writer-lock')
+
+    mkdirSync(path.join(env['CODEX_HOME']!, 'thread-writer-locks'), { recursive: true })
+    io.outLines = []
+    await doctorCommand(deps, {})
+    const out = io.outLines.join('\n')
+    if (process.platform === 'darwin') {
+      expect(out).toMatch(/ok\s+hooks \(wake route\)/)
+      expect(out).toContain('can prove a stopped thread unowned before resuming it')
+    } else {
+      // Linux has no non-blocking `flock` through Node's `open(2)` flags, so
+      // the gate stays shut and doctor says so rather than implying a wake.
+      expect(out).toContain('nothing can be resumed')
+    }
   })
 
   it('documents the failing exit contract in doctor JSON', async () => {