@raidiant/notifai 0.4.0 → 0.5.1

package/src/commands.ts

@@ -46,6 +46,7 @@ import {
   type LogLevel,
 } from './config.js'
 import { acceptedValues, configInfo } from './config-schema.js'
+import { skillsSource } from './release.js'
 import { atomicWriteFileSync } from './atomic-file.js'
 import { withTargetFileLock } from './file-lock.js'
 import {
@@ -63,20 +64,22 @@ import {
 } from './readiness.js'
 import type { Tone } from './ui/theme.js'
 import {
+  WAITER_CEILING_SECONDS,
   handleSessionEnd,
   handleStop,
   handleUserPromptSubmit,
   parseHookInput,
   pruneAbandonedSessions,
+  readLiveProjectSessionPointers,
   readMatchingProjectSessionPointer,
   readProjectSession,
   readProjectSessionPointer,
   readSessionState,
   registerQuestion,
+  type EscalationDeliveryRoute,
   type HookContext,
   type HookHarness,
 } from './hooks.js'
-import { readIdleSeconds } from './idle.js'
 import {
   LOG_EVENTS,
   activeLogPath,
@@ -91,9 +94,10 @@ import {
   type Logger,
 } from './logging.js'
 import {
+  BLOCKING_STOP_TIMEOUT_SECONDS,
+  CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS,
   HARNESSES,
   applyPlan,
-  blockingHookTimeoutSeconds,
   buildCursorHookConfig,
   buildHookConfig,
   codexLayerDir,
@@ -112,7 +116,18 @@ import {
   type Harness,
   type Installation,
 } from './install-hooks.js'
-import { HARNESS_CAPABILITIES, HOOK_TIMING } from './harnesses.js'
+import { HARNESS_CAPABILITIES } from './harnesses.js'
+import {
+  claudeWakeRoute,
+  inspectClaudeInbox,
+  systemClaudeWakeAdapters,
+  type ClaudeWakeAdapters,
+} from './claude-wake.js'
+import {
+  codexWakeRoute,
+  inspectCodexResume,
+  type CodexWakeAdapters,
+} from './codex-wake.js'
 import {
   inspectHookAdapter,
   installHookAdapter,
@@ -179,8 +194,12 @@ export interface CommandDeps {
   now?: () => number
   /** Test seam for retry/backoff timing. */
   sleep?: (milliseconds: number) => Promise<void>
-  /** Test seam for the OS idle probe; production shells out to the platform. */
-  idleSeconds?: () => number | null
+  /** Test seams for Claude liveness, socket delivery, and cold resume. */
+  claudeWake?: ClaudeWakeAdapters
+  claudeSourcePid?: number
+  /** Test seams for the Codex thread-writer probe and cold resume. */
+  codexWake?: CodexWakeAdapters
+  codexSourcePid?: number
   /** Test seam and production adapter for the external native skills installer. */
   nativeSkills?: NativeSkills
   /**
@@ -1209,7 +1228,7 @@ export async function hookRunCommand(
   // would grant slow setup a second budget and let the harness kill us before
   // an accepted answer is journaled or written to stdout.
   const now = deps.now ?? Date.now
-  const processDeadlineAt = now() + HOOK_TIMING.totalSeconds * 1000
+  const processDeadlineAt = now() + WAITER_CEILING_SECONDS * 1000
 
   const logger = log(deps)
   logger.bind({ cmd: `hook ${event}` })
@@ -1347,13 +1366,7 @@ export async function hookRunCommand(
       `Bearer nfm_${credential.machineId}.${credential.secret}`,
       {
         timeoutMs: event === 'user-prompt-submit' ? 4_000 : 20_000,
-        ...(event === 'stop'
-          ? {
-              deadlineAt:
-                processDeadlineAt - HOOK_TIMING.stdoutReserveSeconds * 1000,
-              now,
-            }
-          : {}),
+        ...(event === 'stop' ? { deadlineAt: processDeadlineAt, now } : {}),
       },
     )
     const ctx: HookContext = {
@@ -1361,7 +1374,6 @@ export async function hookRunCommand(
       config: resolved,
       env: deps.env,
       now,
-      idleSeconds: deps.idleSeconds ?? (() => readIdleSeconds()),
       sleep: deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
       waitForFirstReply: async (requestId, timeoutSeconds) => {
         const result = await waitForReply(client, requestId, {
@@ -1391,7 +1403,12 @@ export async function hookRunCommand(
     const outcome =
       event === 'user-prompt-submit'
         ? await handleUserPromptSubmit(ctx, envelope)
-        : await handleStop(ctx, envelope, processDeadlineAt)
+        : await handleStop(
+            ctx,
+            envelope,
+            processDeadlineAt,
+            stopWakeRoute(deps, harness, envelope.session_id, cwd),
+          )
     // Answer diagnostics are already persisted once as hook.answer. Keep every
     // other note in the lifecycle record without duplicating the user's text.
     const notes = outcome.notes.filter((note) => !/^(?:late )?answer from /.test(note))
@@ -1436,6 +1453,61 @@ export async function hookRunCommand(
   }
 }
 
+/**
+ * The last meter for an answer this Stop hook accepted, chosen by harness.
+ *
+ * Both wake adapters need the harness process that invoked this hook: Claude's
+ * to prove exact own-child session ownership before it posts to the inbox
+ * socket, Codex's to know whether its own stdout is still a live continuation
+ * channel. Without an exact session id neither can prove anything, so the
+ * waiter falls back to the plain blocking Stop continuation.
+ */
+function stopWakeRoute(
+  deps: CommandDeps,
+  harness: Harness | undefined,
+  sessionId: string | undefined,
+  cwd: string,
+): EscalationDeliveryRoute | undefined {
+  if (sessionId === undefined) return undefined
+  if (harness === 'claude-code') {
+    return claudeWakeRoute({
+      sessionId,
+      cwd,
+      sourcePid: deps.claudeSourcePid ?? claudeSessionPid(deps.env),
+      ...(deps.claudeWake === undefined ? {} : { adapters: deps.claudeWake }),
+    })
+  }
+  if (harness === 'codex') {
+    return codexWakeRoute({
+      threadId: sessionId,
+      cwd,
+      sourcePid: deps.codexSourcePid ?? process.ppid,
+      env: deps.env,
+      ...(deps.codexWake === undefined ? {} : { adapters: deps.codexWake }),
+    })
+  }
+  return undefined
+}
+
+/**
+ * The pid of the Claude Code session this hook belongs to.
+ *
+ * Claude exports `CLAUDE_PID` to its hooks, and that is the authoritative
+ * answer. `process.ppid` agrees with it today — the hook command runs through
+ * a shell, but the shell `exec`s, so this process's parent *is* the session
+ * (probed against a live 2.1.228 session) — and it remains the fallback for a
+ * harness build that stops exporting the variable.
+ *
+ * Preferring the explicit value costs a line and removes a silent failure: if
+ * this ever resolved to a shell instead, no session descriptor would match, the
+ * route could not prove own-child ownership, and every answer would degrade to
+ * hold-for-next-turn with nothing reported as wrong.
+ */
+function claudeSessionPid(env: NodeJS.ProcessEnv): number {
+  const declared = Number(env['CLAUDE_PID'])
+  return Number.isInteger(declared) && declared > 0 ? declared : process.ppid
+}
+
 /**
  * What went wrong, in terms of what to do about it.
  *
@@ -1588,10 +1660,9 @@ function buildOneQuestion(
 }
 
 /**
- * Registers a question for turn-end routing under the user's presence config.
- * Returns immediately so the agent can ask in prose and end its turn. Presence
- * does not block the shipped default; `require_idle = true` intentionally keeps
- * the question local while the user is active.
+ * Registers a question for turn-end routing. Returns immediately so the agent
+ * can ask in prose and end its turn; the terminal keeps the question to itself
+ * for `ask_grace_seconds` before it reaches any device.
  */
 export function askCommand(deps: CommandDeps, question: string | undefined, flags: AskFlags): number {
   // Validate before route discovery. A malformed question belongs to the
@@ -1619,7 +1690,7 @@ export function askCommand(deps: CommandDeps, question: string | undefined, flag
   // markers identify the active owner, while UserPromptSubmit adds the hook's
   // canonical id to the directory's concurrent-session index.
   const now = (deps.now ?? Date.now)()
-  const active = activeHarnessSession(deps.env)
+  const { active, contested } = resolveActiveHarness(deps.env, deps.cwd, now)
   let sessionId: string | undefined
   if (active !== null) {
     const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome)
@@ -1627,7 +1698,12 @@ export function askCommand(deps: CommandDeps, question: string | undefined, flag
       (installation) => installation.harness === active.harness,
     )
     if (!activeInstalled) {
-      for (const line of diagnoseActiveHarnessSession(active, 'not-installed', installations)) {
+      for (const line of diagnoseActiveHarnessSession(
+        active,
+        'not-installed',
+        installations,
+        contested,
+      )) {
         deps.io.err(line)
       }
       return EXIT.usage
@@ -1646,7 +1722,12 @@ export function askCommand(deps: CommandDeps, question: string | undefined, flag
       active.harness,
     )
     if (projectPointer === null) {
-      for (const line of diagnoseActiveHarnessSession(active, 'not-fired', installations)) {
+      for (const line of diagnoseActiveHarnessSession(
+        active,
+        'not-fired',
+        installations,
+        contested,
+      )) {
         deps.io.err(line)
       }
       return EXIT.usage
@@ -1717,8 +1798,32 @@ export function askCommand(deps: CommandDeps, question: string | undefined, flag
   }
   deps.io.out(
     built.questions.length > 1
-      ? `${built.questions.length} questions registered as one form. Ask them in the conversation as usual and end your turn.`
-      : 'Question registered. Ask it in the conversation as usual and end your turn.',
+      ? `${built.questions.length} questions registered as one form. Ask them in the conversation, state the concrete work you will resume for their answers, then 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.',
+  )
+  deps.io.out('Before ending this turn, pre-commit in your own words to the work you will resume:')
+  for (const [index, entry] of built.questions.entries()) {
+    const questionPrefix = built.questions.length > 1 ? `Question ${index + 1}, ` : ''
+    if (entry.choices !== undefined) {
+      for (const choice of entry.choices) {
+        deps.io.out(
+          `- ${questionPrefix}If the answer is ${JSON.stringify(choice.label)}: state the concrete work you will resume.`,
+        )
+      }
+      deps.io.out(
+        `- ${questionPrefix}For an unexpected typed answer: state how it will determine the concrete work you resume.`,
+      )
+    } else {
+      deps.io.out(
+        `- ${questionPrefix}For the free-text answer: state how its content will determine the concrete work you resume.`,
+      )
+    }
+  }
+  deps.io.out(
+    'When the answer arrives, resume the matching work without asking the user to confirm again. Frame this as work you will resume, not as approval you receive.',
+  )
+  deps.io.out(
+    'A Notifai answer cannot answer a harness permission prompt or interactive picker; leave those to the harness and user.',
   )
   return EXIT.ok
 }
@@ -1736,30 +1841,96 @@ interface ActiveHarnessSession {
   sessionId?: string
 }
 
-function activeHarnessSession(env: NodeJS.ProcessEnv): ActiveHarnessSession | null {
-  const explicit = env['NOTIFAI_ACTIVE_HARNESS']
-  if (explicit === 'opencode') {
+/**
+ * Every harness marker present in this environment, in declared order.
+ *
+ * Order here is a last resort, not an answer. A harness exports its markers
+ * into every process it starts, so a nested harness inherits its parent's
+ * markers alongside its own and the environment alone cannot say which of them
+ * owns this shell; `resolveActiveHarness` settles that with live evidence.
+ */
+function harnessEnvCandidates(env: NodeJS.ProcessEnv): ActiveHarnessSession[] {
+  const candidates: ActiveHarnessSession[] = []
+  if (env['NOTIFAI_ACTIVE_HARNESS'] === 'opencode') {
     const sessionId = env['NOTIFAI_ACTIVE_SESSION_ID']
-    return {
+    candidates.push({
       harness: 'opencode',
       label: 'OpenCode',
       ...(sessionId === undefined || sessionId === '' ? {} : { sessionId }),
-    }
+    })
   }
   if (env['CLAUDECODE'] === '1') {
     const sessionId = env['CLAUDE_CODE_SESSION_ID']
-    return {
+    candidates.push({
       harness: 'claude-code',
       label: 'Claude Code',
       ...(sessionId === undefined || sessionId === '' ? {} : { sessionId }),
-    }
+    })
   }
   const codexSession = env['CODEX_THREAD_ID']
   if (codexSession !== undefined && codexSession !== '') {
-    return { harness: 'codex', label: 'Codex', sessionId: codexSession }
+    candidates.push({ harness: 'codex', label: 'Codex', sessionId: codexSession })
   }
-  if ((env['CURSOR_AGENT'] ?? '') !== '') return { harness: 'cursor', label: 'Cursor' }
-  return null
+  if ((env['CURSOR_AGENT'] ?? '') !== '') candidates.push({ harness: 'cursor', label: 'Cursor' })
+  return candidates
+}
+
+interface ActiveHarnessResolution {
+  active: ActiveHarnessSession | null
+  /**
+   * Markers of harnesses that could equally own this shell, present only when
+   * nothing here has fired yet and declared order had to pick. Whatever is
+   * reported then has to hold for every one of them.
+   */
+  contested: ActiveHarnessSession[]
+}
+
+/**
+ * Which harness session owns this shell, when several claim to.
+ *
+ * Nesting is ordinary: an orchestrator running inside Claude Code starts a
+ * Codex session, and that Codex process inherits `CLAUDECODE` and
+ * `CLAUDE_CODE_SESSION_ID` on top of its own `CODEX_THREAD_ID`. The mirror is
+ * just as ordinary, so no fixed precedence between two markers can be right —
+ * whichever one it favours is wrong in the opposite nesting, and the cost is
+ * silent: `ask` looks up a session that is not this one, and every remedy the
+ * agent is told to try addresses a harness that is not running here.
+ *
+ * The general rule is to prefer the most specific *live* signal over inherited
+ * environment. An inherited marker is a claim about some ancestor process; a
+ * session id that names an entry in this directory's live pointer index is
+ * evidence that that exact session fired a hook here and its state still
+ * exists. Live evidence therefore wins over declared order, and the most
+ * recently active pointer wins between two live candidates: the harness whose
+ * turn is running is the one that fired last, while its parent sits blocked on
+ * the child it started. Declared order decides only when nothing here has
+ * fired yet, and it says so — every route fails closed there anyway.
+ */
+function resolveActiveHarness(
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+  now: number,
+): ActiveHarnessResolution {
+  const candidates = harnessEnvCandidates(env)
+  const first = candidates[0]
+  if (first === undefined) return { active: null, contested: [] }
+  if (candidates.length === 1) return { active: first, contested: [] }
+  for (const pointer of readLiveProjectSessionPointers(cwd, env, now)) {
+    const owner = candidates.find(
+      (candidate) =>
+        candidate.harness === pointer.harness && candidate.sessionId === pointer.sessionId,
+    )
+    if (owner !== undefined) return { active: owner, contested: [] }
+  }
+  return { active: first, contested: candidates }
+}
+
+function activeHarnessSession(
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+  now: number,
+): ActiveHarnessSession | null {
+  return resolveActiveHarness(env, cwd, now).active
 }
 
 /**
@@ -1807,20 +1978,7 @@ function activeQuestionRouteProblems(
   for (const problem of inspectHookAdapter(deps.hookAdapterHome).problems) {
     problems.push(problem)
   }
-  if (active.harness !== 'codex') {
-    const required = blockingHookTimeoutSeconds()
-    for (const installation of matching) {
-      for (const handler of installation.handlers.filter(
-        (entry) => handlerEvent(entry.command) === 'stop',
-      )) {
-        if (handler.timeout === undefined || handler.timeout < required) {
-          problems.push(
-            `${installation.file} gives Stop ${handler.timeout ?? 'no'}s, but the live answer owner requires ${required}s`,
-          )
-        }
-      }
-    }
-  }
+  for (const installation of matching) problems.push(...stopShapeProblems(installation))
   problems.push(...codexTrustProblems(matching, deps.env))
   return [...new Set(problems)]
 }
@@ -1831,11 +1989,22 @@ function diagnoseActiveHarnessSession(
   active: ActiveHarnessSession,
   problem: ActiveHarnessProblem,
   installations: Installation[],
+  contested: ActiveHarnessSession[] = [],
 ): string[] {
+  // Naming one harness confidently is wrong when the environment carries the
+  // markers of several and none of them has fired here: whichever one the
+  // agent is told to prompt may not be the one it is running in.
+  const ambiguity =
+    contested.length > 1
+      ? [
+          `Several harness markers are present here (${contested.map((candidate) => candidate.label).join(', ')}) and none names a session that has fired in this directory, so ${active.label} is a guess from the environment. Send the prompt in the harness you are actually running.`,
+        ]
+      : []
   if (problem === 'not-installed') {
     const others = installations.map((installation) => installation.harness)
     return [
       `Could not register the question for the active ${active.label} session: Notifai ${active.label} hooks are not installed for this project.`,
+      ...ambiguity,
       ...(others.length === 0
         ? []
         : [
@@ -1848,12 +2017,14 @@ function diagnoseActiveHarnessSession(
   if (problem === 'different-session') {
     return [
       `Could not register the question for the active ${active.label} session: the project pointer belongs to another ${active.label} session or harness.`,
+      ...ambiguity,
       `Refusing to guess or cross-wire the question. Send one prompt in this ${active.label} session, then run \`notifai doctor\`.`,
       `Retry \`notifai ask\` only after doctor reports that this active ${active.label} session fired the hooks.`,
     ]
   }
   return [
     `Could not register the question for the active ${active.label} session: Notifai hooks are installed, but this session has not published its pointer.`,
+    ...ambiguity,
     `Send one ${active.label} prompt, then run \`notifai doctor\`.`,
     `Retry \`notifai ask\` only after doctor reports that the active ${active.label} session fired the hooks.`,
   ]
@@ -1974,7 +2145,7 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
   if (harness === 'opencode') {
     return installOpencodePlugin(deps, file, {
       adapterPath,
-      timeoutSeconds: blockingHookTimeoutSeconds(),
+      timeoutSeconds: BLOCKING_STOP_TIMEOUT_SECONDS,
     })
   }
 
@@ -2041,27 +2212,11 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
     deps.io.out(`  removed: ${merged.removed.join(', ')} (this build no longer serves them)`)
   }
   deps.io.out('')
-  if (config.require_idle.value) {
-    deps.io.out(
-      `While keyboard or mouse idle time stays below ${config.away_after_seconds.value}s, ` +
-        `nothing is pushed. A question registered with \`notifai ask\` goes to your devices ` +
-        (config.ask_grace_seconds.value === 0
-          ? 'as soon as the machine meets that idle threshold. '
-          : `once its ${config.ask_grace_seconds.value}s grace window, counted from registration, has elapsed and the machine meets that idle threshold. `) +
-        `Run \`notifai config set require_idle false\` to be notified even while you are working.`,
-    )
-  } else {
-    deps.io.out(
-      config.ask_grace_seconds.value === 0
-        ? 'A question registered with `notifai ask` goes to your devices immediately when the agent turn ends, whether or not you are at this machine.'
-        : `A question registered with \`notifai ask\` stays in the terminal for ${config.ask_grace_seconds.value}s from registration and then goes to your devices whether or not you are at this machine.`,
-    )
-  }
-  if (config.require_idle.value) {
-    deps.io.out(
-      'If this OS exposes no keyboard/mouse idle signal, the hook falls back to prompt silence and skips the blocking grace once it decides you are away.',
-    )
-  }
+  deps.io.out(
+    config.ask_grace_seconds.value === 0
+      ? 'A question registered with `notifai ask` goes to your devices immediately when the agent turn ends, whether or not you are at this machine.'
+      : `A question registered with \`notifai ask\` stays in the terminal for ${config.ask_grace_seconds.value}s from registration and then goes to your devices whether or not you are at this machine.`,
+  )
   if (harness === 'codex') {
     const layer = flags.global ? null : codexLayerDir(deps.cwd)
     if (layer !== null) {
@@ -2079,6 +2234,15 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
     }
   }
   deps.io.out('')
+  if (harness === 'claude-code') {
+    // Codex deliberately gets no counterpart line: its Stop definition is
+    // byte-identical to the one earlier builds wrote, so nothing about its
+    // trust state changed and saying so would invent a gate that is not there.
+    deps.io.out(
+      `The Stop handler is asynchronous: it returns at once, so your turn ends normally, and it waits for your answer out of band for up to ${CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS}s before delivering it back into this session. That timeout is written explicitly because Claude Code kills a background hook at its own 600s default and reports nothing when it does.`,
+    )
+    deps.io.out('')
+  }
   if (harness === 'claude-code' && flags.global !== true) {
     deps.io.out('Claude Code reloads project hook files without a restart. Send one new prompt,')
     deps.io.out('then check `notifai doctor` to confirm that the hook fired.')
@@ -2749,13 +2913,22 @@ export function logsCommand(deps: CommandDeps, flags: LogsFlags): number {
 // ---------------------------------------------------------------------------
 
 /**
- * Where `npx skills add` fetches the optional agent skill from. In skills CLI
- * 1.5.x, `owner/repo@name` selects a skill; a Git ref belongs after `#`.
- * Keep this immutable and public because the command is printed to users.
+ * Where `npx skills add` fetches the optional agent skill from, derived from
+ * this build's own version so the pin cannot drift from the release it names.
+ * Null when the build cannot establish its version; see `./release.js`.
  */
-export const SKILLS_SOURCE = 'Raidiant-io/notifai#v0.4.0'
+export const SKILLS_SOURCE: string | null = skillsSource()
+
+/**
+ * How to refer to the pin in user-facing text.
+ *
+ * Only reached in a corrupted install, where naming the tag is impossible but
+ * saying nothing would be worse — the sentence still has to read as English.
+ */
+const SKILLS_SOURCE_LABEL = SKILLS_SOURCE ?? 'the public release tag matching this CLI'
 
 function skillSourceParts(): { source: string; ref: string } | null {
+  if (SKILLS_SOURCE === null) return null
   const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE)
   return match === null ? null : { source: match[1]!, ref: match[2]! }
 }
@@ -2792,7 +2965,7 @@ async function skillReadiness(
       id: 'skill',
       title: 'Agent guidance skill',
       status: 'ready',
-      detail: `installed from ${SKILLS_SOURCE} in the ${installed.scope} scope`,
+      detail: `installed from ${SKILLS_SOURCE_LABEL} in the ${installed.scope} scope`,
     }
   }
 
@@ -2807,7 +2980,7 @@ async function skillReadiness(
     detail:
       errors.length > 0
         ? `could not verify installer-managed state in ${scopeText} (${errors.join('; ')})`
-        : `not installed from ${SKILLS_SOURCE} in ${scopeText}`,
+        : `not installed from ${SKILLS_SOURCE_LABEL} in ${scopeText}`,
     remedy: {
       by: 'cli',
       summary: 'install the skill agents follow when deciding to notify',
@@ -3008,6 +3181,14 @@ async function closeGap(
       deps.io.err('Skill installation failed — the native `npx skills` flow is unavailable.')
       return 'failed'
     }
+    // Refuse rather than reach for a mutable ref: installing the skill from a
+    // moving branch is the one outcome the pin exists to prevent.
+    if (SKILLS_SOURCE === null) {
+      deps.io.err(
+        'Skill installation failed — this build cannot determine its own version, so there is no release tag to install from.',
+      )
+      return 'failed'
+    }
     const scopeText = flags.skillsScope === undefined ? 'the scope you choose' : `${flags.skillsScope} scope`
     deps.io.out(`Starting the native npx skills setup for the notifai agent skill (${scopeText})...`)
     const addOptions = {
@@ -3984,7 +4165,7 @@ function remedyLine(state: ReadinessState): string {
  */
 function hookStates(deps: CommandDeps): ReadinessState[] {
   const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome)
-  const active = activeHarnessSession(deps.env)
+  const active = activeHarnessSession(deps.env, deps.cwd, (deps.now ?? Date.now)())
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
   const settings: ReadinessState = {
     id: 'question-routing-settings',
@@ -3992,10 +4173,7 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
     status: config.ask_notifications.value ? 'ready' : 'gap',
     detail: [
       `ask_notifications=${config.ask_notifications.value} (${config.ask_notifications.source})`,
-      `require_idle=${config.require_idle.value} (${config.require_idle.source})`,
-      `away_after_seconds=${config.away_after_seconds.value} (${config.away_after_seconds.source})`,
       `ask_grace_seconds=${config.ask_grace_seconds.value} (${config.ask_grace_seconds.source})`,
-      `hook_reply_timeout_seconds=${config.hook_reply_timeout_seconds.value} (${config.hook_reply_timeout_seconds.source})`,
     ].join(', '),
     ...(config.ask_notifications.value
       ? {}
@@ -4064,6 +4242,49 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
   ]
 }
 
+/**
+ * Whether an installed Stop handler declares the shape its harness needs.
+ *
+ * The three answers differ, and getting one wrong fails silently in a
+ * different way each time:
+ *
+ *   - Claude Code's handler must be `async: true`, or the waiter holds the
+ *     user's turn for its whole wait instead of returning at once. It must
+ *     also declare a `timeout`, because the harness default is 600 s and the
+ *     kill is silent — the backgrounded waiter vanishes and the answer the
+ *     user already gave is never delivered.
+ *   - Codex owns its Stop timeout. Declaring one changes the definition it
+ *     hashes into `trusted_hash`, and an untrusted handler is simply not run.
+ *   - Everything else blocks its turn and needs a ceiling above the wait.
+ */
+function stopShapeProblems(installation: Installation): string[] {
+  if (installation.harness === 'codex') return []
+  const problems: string[] = []
+  for (const handler of installation.handlers.filter(
+    (entry) => handlerEvent(entry.command) === 'stop',
+  )) {
+    if (installation.harness === 'claude-code') {
+      if (handler.async !== true) {
+        problems.push(
+          `${installation.file} declares a blocking Stop handler; the Claude Code wake route needs \`async: true\` so the turn ends while the waiter runs`,
+        )
+      }
+      if (handler.timeout === undefined || handler.timeout < CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS) {
+        problems.push(
+          `${installation.file} gives Stop ${handler.timeout ?? 'no'} declared seconds; Claude Code then kills the backgrounded waiter at its 600s default without reporting anything, so it needs an explicit ${CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS}s`,
+        )
+      }
+      continue
+    }
+    if (handler.timeout === undefined || handler.timeout < BLOCKING_STOP_TIMEOUT_SECONDS) {
+      problems.push(
+        `${installation.file} gives Stop ${handler.timeout ?? 'no'}s, but the blocking answer owner requires ${BLOCKING_STOP_TIMEOUT_SECONDS}s`,
+      )
+    }
+  }
+  return problems
+}
+
 interface HookCheck {
   name: string
   ok: boolean
@@ -4096,7 +4317,11 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
       .join(', '),
   })
 
-  const active = activeHarnessSession(deps.env)
+  const { active, contested } = resolveActiveHarness(
+    deps.env,
+    deps.cwd,
+    (deps.now ?? Date.now)(),
+  )
   const activeInstallations =
     active === null
       ? []
@@ -4207,24 +4432,19 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
         }),
   })
 
-  const requiredTimeout = blockingHookTimeoutSeconds()
-  const shortTimeouts = installations.flatMap((installation) =>
-    installation.handlers
-      .filter(() => installation.harness !== 'codex')
-      .filter((handler) => handlerEvent(handler.command) === 'stop')
-      .filter((handler) => handler.timeout === undefined || handler.timeout < requiredTimeout)
-      .map(
-        (handler) =>
-          `${installation.harness} declares ${handler.timeout ?? 'no'}s, needs ${requiredTimeout}s — run \`notifai hooks install --harness ${installation.harness}${installation.global ? ' --global' : ''}\``,
-      ),
+  const shapeProblems = installations.flatMap((installation) =>
+    stopShapeProblems(installation).map(
+      (problem) =>
+        `${problem} — run \`notifai hooks install --harness ${installation.harness}${installation.global ? ' --global' : ''}\``,
+    ),
   )
   checks.push({
-    name: 'hooks (timeout)',
-    ok: shortTimeouts.length === 0,
+    name: 'hooks (stop shape)',
+    ok: shapeProblems.length === 0,
     detail:
-      shortTimeouts.length === 0
-        ? `declared Stop timeouts match the fixed ${requiredTimeout}s process budget where required; Codex uses host defaults`
-        : shortTimeouts.join('; '),
+      shapeProblems.length === 0
+        ? `every installed Stop handler declares the shape its harness needs: Claude Code async with an explicit ${CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS}s waiter budget, blocking hosts ${BLOCKING_STOP_TIMEOUT_SECONDS}s, Codex host-owned`
+        : shapeProblems.join('; '),
   })
 
   // Project and global definitions for one harness both fire. Stable adapter
@@ -4262,22 +4482,51 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
     })
   }
 
+  // Which route this judges, and which remedy it prints, must both belong to
+  // the harness that is actually running here. A machine-global installation
+  // matches every directory, so picking whichever installation matched — or
+  // whichever session last wrote a pointer — reports on a harness the agent
+  // cannot influence: it is told to send a prompt in a harness that is not
+  // running, follows the fail-closed rule, and can never clear the check.
   const firedPointer =
-    active?.sessionId === undefined
+    active === null
       ? readProjectSessionPointer(deps.cwd, deps.env, (deps.now ?? Date.now)())
-      : readMatchingProjectSessionPointer(
-          deps.cwd,
-          deps.env,
-          (deps.now ?? Date.now)(),
-          active.sessionId,
-          active.harness,
-        )
+      : active.sessionId === undefined
+        ? (readLiveProjectSessionPointers(deps.cwd, deps.env, (deps.now ?? Date.now)()).find(
+            (pointer) => pointer.harness === active.harness,
+          ) ?? null)
+        : readMatchingProjectSessionPointer(
+            deps.cwd,
+            deps.env,
+            (deps.now ?? Date.now)(),
+            active.sessionId,
+            active.harness,
+          )
   const firedState = firedPointer === null ? null : readSessionState(firedPointer.sessionId, deps.env)
   const promptFired = firedState?.last_prompt_at !== undefined
   const stopFired = firedState?.last_stop_at !== undefined
   const fired = firedPointer !== null && promptFired && stopFired
-  const activationInstallations =
-    active !== null && activeInstallations.length > 0 ? activeInstallations : installations
+  // Installations for other harnesses are irrelevant to the active one, and an
+  // active harness with none of its own has nothing to activate: say that
+  // instead of advising a prompt in some other harness. When the environment
+  // is contested and nothing has fired, every candidate is still possible, so
+  // the advice covers all of them rather than betting on one.
+  const activationHarnesses = new Set(
+    contested.length > 1
+      ? contested.map((candidate) => candidate.harness)
+      : active === null
+        ? installations.map((installation) => installation.harness)
+        : [active.harness],
+  )
+  const activationInstallations = installations.filter((installation) =>
+    activationHarnesses.has(installation.harness),
+  )
+  const activationAdvice =
+    activationInstallations.length > 0
+      ? hookActivationAdvice(activationInstallations)
+      : active === null
+        ? hookActivationAdvice(installations)
+        : `${active.label}: no ${active.label} hook installation matches this project — run \`notifai hooks install --harness ${active.harness}\`.`
   checks.push({
     name: 'hooks (fired)',
     ok: fired,
@@ -4285,9 +4534,19 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
     // a missing Stop is a broken route, not missing historical evidence.
     informational: firedPointer === null,
     detail: fired
-      ? 'a session in this directory has run UserPromptSubmit and Stop'
+      ? active === null
+        ? 'a session in this directory has run UserPromptSubmit and Stop'
+        : `the active ${active.label} session has run UserPromptSubmit and Stop`
       : firedPointer === null
-        ? `no session pointer from the last 24 hours — ${hookActivationAdvice(activationInstallations)}`
+        ? `no ${
+            contested.length > 1
+              ? `session pointer for any harness whose markers are present here (${contested
+                  .map((candidate) => candidate.label)
+                  .join(', ')})`
+              : active === null
+                ? 'session pointer'
+                : `${active.label} session pointer`
+          } from the last 24 hours — ${activationAdvice}`
         : `the routed session has fired ${promptFired ? 'UserPromptSubmit' : 'neither required event'}, but Stop has not been observed — end one harmless turn, send a new prompt, then check again`,
     ...(fired
       ? {}
@@ -4295,7 +4554,7 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
           remedy: {
             summary:
               firedPointer === null
-                ? 'send one prompt in a session here, then re-check'
+                ? `send one ${active === null || contested.length > 1 ? '' : `${active.label} `}prompt in a session here, then re-check`
                 : 'end one harmless turn, send a new prompt, then re-check',
             command: 'notifai doctor',
           },
@@ -4325,12 +4584,77 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
             .join('; '),
   })
 
+  const wakeRoute = wakeRouteCheck(deps, active, activeInstallations)
+  if (wakeRoute !== null) checks.push(wakeRoute)
+
   const stray = codexStrayWorktreeCheck(deps)
   if (stray !== null) checks.push(stray)
 
   return checks
 }
 
+/**
+ * Whether an answer arriving after this turn ends could actually reach this
+ * exact session — the question `notifai ask` really turns on, and the one no
+ * other check answers.
+ *
+ * Read-only, and deliberately so: nothing here connects to a socket, takes a
+ * lock, or sends a message. A diagnostic that wakes the agent it is diagnosing
+ * would be its own bug report.
+ *
+ * Everything it can report negatively is a degradation rather than a failure —
+ * the accepted journal still replays the answer at the session's next turn —
+ * so this is never a blocker. What it buys is that the reason has a name
+ * before the user notices the silence.
+ *
+ * It never asks for `crossSessionInbound`. The poster is the session's own
+ * hook child and takes the privileged own-child path, verified to be delivered
+ * even against a `bypassPermissions` receiver while an unrelated process was
+ * held. Widening a user's general inbound policy to suit Notifai would be a
+ * real change to their machine's posture in exchange for nothing.
+ */
+function wakeRouteCheck(
+  deps: CommandDeps,
+  active: ActiveHarnessSession | null,
+  activeInstallations: Installation[],
+): HookCheck | null {
+  if (active === null || activeInstallations.length === 0) return null
+  if (active.harness === 'claude-code') {
+    const readiness = inspectClaudeInbox({
+      pid: deps.claudeSourcePid ?? claudeSessionPid(deps.env),
+      platform: process.platform,
+      readDescriptor:
+        deps.claudeWake?.readDescriptor ?? systemClaudeWakeAdapters(deps.env).readDescriptor,
+      socketExists: (socketPath) => existsSync(socketPath),
+    })
+    return {
+      name: 'hooks (wake route)',
+      ok: readiness.state === 'ready',
+      informational: true,
+      detail:
+        readiness.state === 'ready'
+          ? `this Claude Code ${readiness.version} session is listening on ${readiness.socketPath}, so an answer can start a turn here without you`
+          : `${readiness.reason}. Answers are still delivered, at this session's next turn rather than on their own`,
+    }
+  }
+  if (active.harness === 'codex') {
+    const readiness = inspectCodexResume(deps.env, {
+      platform: process.platform,
+      directoryExists: (directory) => existsSync(directory),
+    })
+    return {
+      name: 'hooks (wake route)',
+      ok: readiness.state === 'ready',
+      informational: true,
+      detail:
+        readiness.state === 'ready'
+          ? `the held Codex turn continues from its own hook, and after it returns ${readiness.lockDirectory} can prove a stopped thread unowned before resuming it`
+          : `the held Codex turn still continues from its own hook, but after it returns nothing can be resumed: ${readiness.reason}. Answers wait for the next turn`,
+    }
+  }
+  return null
+}
+
 /**
  * A Codex hooks file sitting in a worktree, which Codex will never read.
  *