@raidiant/notifai 0.4.0 → 0.5.1

package/dist/commands.js

@@ -9,15 +9,17 @@ import { sha256Hex } from '@raidiant/notifai-protocol/node';
 import { ApiCallError, NetworkError, createClient, isRetryableReplyPollError, } from './client.js';
 import { BOOLEAN_CONFIG_KEYS, CONFIG_KEYS, LOG_LEVELS, NUMERIC_CONFIG_KEYS, configBounds, configDefaultValue, findProjectConfigPath, findProjectLocalConfigPath, globalConfigPath, loadConfig, sessionConfigPath, } 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 { renderConfigExplain, renderConfigList, renderConfigPlain, } from './ui/config-view.js';
 import { firstBlocker, openItems, } from './readiness.js';
-import { handleSessionEnd, handleStop, handleUserPromptSubmit, parseHookInput, pruneAbandonedSessions, readMatchingProjectSessionPointer, readProjectSession, readProjectSessionPointer, readSessionState, registerQuestion, } from './hooks.js';
-import { readIdleSeconds } from './idle.js';
+import { WAITER_CEILING_SECONDS, handleSessionEnd, handleStop, handleUserPromptSubmit, parseHookInput, pruneAbandonedSessions, readLiveProjectSessionPointers, readMatchingProjectSessionPointer, readProjectSession, readProjectSessionPointer, readSessionState, registerQuestion, } from './hooks.js';
 import { LOG_EVENTS, activeLogPath, archiveLogPaths, logConfigResolved, logSettingsFrom, logsDiskUsage, nullLogger, readLogRecords, renderRecord, } from './logging.js';
-import { HARNESSES, applyPlan, blockingHookTimeoutSeconds, buildCursorHookConfig, buildHookConfig, codexLayerDir, codexTrustProblems, codexProjectRoot, detectHarness, findInstallations, handlerEvent, loadCursorSettings, loadSettings, mergeCursorHooks, mergeHooks, removeCursorHooks, removeHooks, settingsFile, } from './install-hooks.js';
-import { HARNESS_CAPABILITIES, HOOK_TIMING } from './harnesses.js';
+import { BLOCKING_STOP_TIMEOUT_SECONDS, CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS, HARNESSES, applyPlan, buildCursorHookConfig, buildHookConfig, codexLayerDir, codexTrustProblems, codexProjectRoot, detectHarness, findInstallations, handlerEvent, loadCursorSettings, loadSettings, mergeCursorHooks, mergeHooks, removeCursorHooks, removeHooks, settingsFile, } from './install-hooks.js';
+import { HARNESS_CAPABILITIES } from './harnesses.js';
+import { claudeWakeRoute, inspectClaudeInbox, systemClaudeWakeAdapters, } from './claude-wake.js';
+import { codexWakeRoute, inspectCodexResume, } from './codex-wake.js';
 import { inspectHookAdapter, installHookAdapter, } from './hook-adapter.js';
 import { isOurOpencodePlugin, opencodePluginSource, } from './opencode-plugin.js';
 import { CHOICE_USAGE, buildDraft, formatReceipt, parseChoices, receiptExitCode, slugify, } from './send.js';
@@ -901,7 +903,7 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
     // 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}` });
     let started = false;
@@ -1033,19 +1035,13 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
         // Stop is allowed to block and keeps the ordinary budget.
         const client = makeClient(deps, baseUrl, `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 = {
             client,
             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, {
@@ -1073,7 +1069,7 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
             pruneAbandonedSessions(deps.env);
         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));
@@ -1119,6 +1115,55 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
         return EXIT.ok;
     }
 }
+/**
+ * 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, harness, sessionId, cwd) {
+    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) {
+    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.
  *
@@ -1242,10 +1287,9 @@ function buildOneQuestion(text, choiceLabels, multi, index, usedIds) {
     };
 }
 /**
- * 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, question, flags) {
     // Validate before route discovery. A malformed question belongs to the
@@ -1269,13 +1313,13 @@ export function askCommand(deps, question, flags) {
     // 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;
     if (active !== null) {
         const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome);
         const activeInstalled = installations.some((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;
@@ -1288,7 +1332,7 @@ export function askCommand(deps, question, flags) {
         }
         const projectPointer = readMatchingProjectSessionPointer(deps.cwd, deps.env, now, active.sessionId, 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;
@@ -1353,35 +1397,96 @@ export function askCommand(deps, question, flags) {
         }
     }
     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;
 }
-function activeHarnessSession(env) {
-    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) {
+    const candidates = [];
+    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;
+        candidates.push({ harness: 'cursor', label: 'Cursor' });
+    return candidates;
+}
+/**
+ * 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, cwd, now) {
+    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, cwd, now) {
+    return resolveActiveHarness(env, cwd, now).active;
 }
 /**
  * One fail-closed admission gate shared by every active harness route.
@@ -1416,24 +1521,25 @@ function activeQuestionRouteProblems(deps, active, installations) {
     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)];
 }
-function diagnoseActiveHarnessSession(active, problem, installations) {
+function diagnoseActiveHarnessSession(active, problem, installations, contested = []) {
+    // 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
                 ? []
                 : [
@@ -1446,12 +1552,14 @@ function diagnoseActiveHarnessSession(active, problem, installations) {
     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.`,
     ];
@@ -1541,7 +1649,7 @@ export function hooksInstallCommand(deps, flags) {
     if (harness === 'opencode') {
         return installOpencodePlugin(deps, file, {
             adapterPath,
-            timeoutSeconds: blockingHookTimeoutSeconds(),
+            timeoutSeconds: BLOCKING_STOP_TIMEOUT_SECONDS,
         });
     }
     if (harness === 'cursor') {
@@ -1604,22 +1712,9 @@ export function hooksInstallCommand(deps, flags) {
         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) {
@@ -1637,6 +1732,13 @@ export function hooksInstallCommand(deps, flags) {
         }
     }
     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.');
@@ -2222,12 +2324,21 @@ export function logsCommand(deps, flags) {
 // init
 // ---------------------------------------------------------------------------
 /**
- * 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 = 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() {
+    if (SKILLS_SOURCE === null)
+        return null;
     const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE);
     return match === null ? null : { source: match[1], ref: match[2] };
 }
@@ -2257,7 +2368,7 @@ async function skillReadiness(deps, selectedScope) {
             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`,
         };
     }
     const errors = results
@@ -2270,7 +2381,7 @@ async function skillReadiness(deps, selectedScope) {
         status: 'optional-gap',
         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',
@@ -2397,6 +2508,12 @@ async function closeGap(deps, state, flags) {
             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 = {
@@ -3267,7 +3384,7 @@ function remedyLine(state) {
  */
 function hookStates(deps) {
     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 = {
         id: 'question-routing-settings',
@@ -3275,10 +3392,7 @@ function hookStates(deps) {
         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
             ? {}
@@ -3342,6 +3456,41 @@ function hookStates(deps) {
         settings,
     ];
 }
+/**
+ * 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) {
+    if (installation.harness === 'codex')
+        return [];
+    const problems = [];
+    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;
+}
 function hookChecks(deps) {
     const checks = [];
     const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome);
@@ -3362,7 +3511,7 @@ function hookChecks(deps) {
             .map((i) => `${i.harness} ${i.global ? 'global' : 'project'} (${i.file})`)
             .join(', '),
     });
-    const active = activeHarnessSession(deps.env);
+    const { active, contested } = resolveActiveHarness(deps.env, deps.cwd, (deps.now ?? Date.now)());
     const activeInstallations = active === null
         ? []
         : installations.filter((installation) => installation.harness === active.harness);
@@ -3455,18 +3604,13 @@ function hookChecks(deps) {
                 },
             }),
     });
-    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,
-        detail: shortTimeouts.length === 0
-            ? `declared Stop timeouts match the fixed ${requiredTimeout}s process budget where required; Codex uses host defaults`
-            : shortTimeouts.join('; '),
+        name: 'hooks (stop shape)',
+        ok: shapeProblems.length === 0,
+        detail: 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
     // identity deliberately makes their command bytes equal, so comparing
@@ -3497,14 +3641,37 @@ function hookChecks(deps) {
                 : admissionProblems.join('; '),
         });
     }
-    const firedPointer = active?.sessionId === undefined
+    // 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 === 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,
@@ -3512,16 +3679,24 @@ function hookChecks(deps) {
         // 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
             ? {}
             : {
                 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',
                 },
@@ -3544,11 +3719,69 @@ function hookChecks(deps) {
                 .map((harness) => `${harness}: ${HARNESS_CAPABILITIES[harness].deliveryContract}`)
                 .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, active, activeInstallations) {
+    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.
  *