@raidiant/notifai 0.5.0 → 1.0.0

package/dist/commands.js

@@ -7,18 +7,20 @@ import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
 import { CAPABILITIES_V1, QUESTION_TEXT_MAX_LENGTH, REPLY_MAX_QUESTIONS, REPLY_MAX_WINDOW_SECONDS, validateDraft, } from '@raidiant/notifai-protocol';
 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 { BOOLEAN_CONFIG_KEYS, CONFIG_KEYS, LOG_LEVELS, NUMERIC_CONFIG_KEYS, configBounds, configDefaultValue, findProjectConfigPath, personalProjectConfigPath, globalConfigPath, loadConfig, sessionConfigPath, } from './config.js';
 import { acceptedValues, configInfo } from './config-schema.js';
+import { packageVersion, 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 { firstBlocker, } from './readiness.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 { inspectHookAdapter, installHookAdapter, } from './hook-adapter.js';
+import { BLOCKING_STOP_TIMEOUT_SECONDS, CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS, HARNESSES, applyPlan, buildCursorHookConfig, buildHookConfig, collapseUnusedCodexRepresentation, codexLayerDir, codexLayerPaths, codexRepresentationProblems, codexTrustProblems, codexProjectRoot, detectHarness, detectedHarnesses, findInstallations, handlerEvent, hookDefinitionFiles, inspectCodexLayer, loadCursorSettings, loadSettings, mergeCursorHooks, mergeHooks, removeCursorHooks, removeHooks, settingsFile, } from './install-hooks.js';
+import { HARNESS_CAPABILITIES, HARNESS_LABELS } from './harnesses.js';
+import { claudeWakeRoute, inspectClaudeInbox, systemClaudeWakeAdapters, } from './claude-wake.js';
+import { codexWakeRoute, inspectCodexResume, } from './codex-wake.js';
+import { inspectHookAdapter, installHookAdapter, isNpxAdapterTarget, } from './hook-adapter.js';
 import { isOurOpencodePlugin, opencodePluginSource, } from './opencode-plugin.js';
 import { CHOICE_USAGE, buildDraft, formatReceipt, parseChoices, receiptExitCode, slugify, } from './send.js';
 /** The invocation's logger, or one that discards everything. */
@@ -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.`,
     ];
@@ -1520,34 +1628,85 @@ export async function closeCommand(deps, requestId) {
         return reportError(deps, err);
     }
 }
+/** True when this process is `npx` / `npm exec`, not a global or linked install. */
+export function runningViaNpx(env, scriptPath) {
+    if (env['npm_command'] === 'exec')
+        return true;
+    return scriptPath.includes(`${path.sep}_npx${path.sep}`);
+}
+function fileHookInstallTarget(target) {
+    if (target === undefined || isNpxAdapterTarget(target))
+        return undefined;
+    return target;
+}
+function resolveHookAdapterTarget(deps, flags) {
+    if (deps.hookInstallTarget !== undefined && isNpxAdapterTarget(deps.hookInstallTarget)) {
+        return deps.hookInstallTarget;
+    }
+    const fileTarget = fileHookInstallTarget(deps.hookInstallTarget);
+    const execPath = flags.execPath ?? fileTarget?.execPath ?? process.execPath;
+    const scriptPath = flags.scriptPath ?? fileTarget?.scriptPath ?? process.argv[1] ?? 'notifai';
+    if (runningViaNpx(deps.env, scriptPath)) {
+        const version = packageVersion();
+        const npmCli = deps.env['npm_execpath'];
+        if (version === null) {
+            throw new Error('Could not read this CLI version, so an npx hook target cannot be pinned. Install `@raidiant/notifai` globally and rerun `notifai hooks install`.');
+        }
+        if (typeof npmCli !== 'string' || npmCli === '') {
+            throw new Error('This process looks like npx but npm_execpath is missing. Install `@raidiant/notifai` globally and rerun `notifai hooks install`.');
+        }
+        return { kind: 'npx', execPath, npmCli, spec: `@raidiant/notifai@${version}` };
+    }
+    return { execPath, scriptPath };
+}
+function printHooksInstallClose(deps, harness, file) {
+    const label = HARNESS_LABELS[harness];
+    if (deps.io.interactive === true && deps.io.note) {
+        void deps.io.note(`${file}\nSend one ${label} prompt, then run \`notifai doctor\`.`, `${label} hooks installed`);
+        return;
+    }
+    deps.io.out(`Installed ${harness} hooks in ${file}`);
+    deps.io.out(`Send one ${label} prompt, then check \`notifai doctor\`.`);
+}
 export function hooksInstallCommand(deps, flags) {
+    if (flags.harness === undefined) {
+        const detected = detectedHarnesses(deps.cwd, deps.env);
+        if (detected.length === 0) {
+            deps.io.err(`Could not tell which harness to install for — pass --harness <${HARNESSES.join('|')}>.`);
+            return EXIT.usage;
+        }
+        let ok = true;
+        for (const harness of detected) {
+            if (hooksInstallCommand(deps, { ...flags, harness }) !== EXIT.ok)
+                ok = false;
+        }
+        return ok ? EXIT.ok : EXIT.failed;
+    }
     const harness = resolveHarness(deps, flags.harness);
     if (!harness)
         return EXIT.usage;
-    const execPath = flags.execPath ?? process.execPath;
-    const scriptPath = flags.scriptPath ?? process.argv[1] ?? 'notifai';
+    const adapterTarget = resolveHookAdapterTarget(deps, flags);
+    const scriptPath = flags.scriptPath ?? fileHookInstallTarget(adapterTarget)?.scriptPath ?? process.argv[1] ?? 'notifai';
     let adapterPath;
     try {
-        adapterPath = installHookAdapter({ execPath, scriptPath }, deps.hookAdapterHome).path;
+        adapterPath = installHookAdapter(adapterTarget, deps.hookAdapterHome).path;
     }
     catch (err) {
         deps.io.err(`Could not prepare the stable hook adapter: ${String(err)}`);
         return EXIT.failed;
     }
-    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     const file = settingsFile(harness, flags.global ?? false, deps.cwd, deps.env);
     // OpenCode's adapter is a generated plugin module rather than a handler
     // merged into a settings document, so it owns the whole file.
     if (harness === 'opencode') {
         return installOpencodePlugin(deps, file, {
             adapterPath,
-            timeoutSeconds: blockingHookTimeoutSeconds(),
+            timeoutSeconds: BLOCKING_STOP_TIMEOUT_SECONDS,
         });
     }
     if (harness === 'cursor') {
-        let merged;
         try {
-            merged = withTargetFileLock(file, () => {
+            withTargetFileLock(file, () => {
                 const document = loadCursorSettings(file);
                 const result = mergeCursorHooks(document, buildCursorHookConfig({
                     adapterPath,
@@ -1561,28 +1720,15 @@ export function hooksInstallCommand(deps, flags) {
             deps.io.err(String(err));
             return EXIT.failed;
         }
-        deps.io.out(`Installed ${harness} hooks in ${file}`);
-        if (merged.replaced.length > 0)
-            deps.io.out(`  replaced: ${merged.replaced.join(', ')}`);
-        if (merged.added.length > 0)
-            deps.io.out(`  added: ${merged.added.join(', ')}`);
-        if (flags.global) {
-            deps.io.out('Send one Cursor prompt, then check `notifai doctor`. If the hook has not fired,');
-            deps.io.out('start a new Cursor session and try one prompt again.');
-        }
-        else {
-            deps.io.out('Send one Cursor prompt, then check `notifai doctor`. If the hook has not fired,');
-            deps.io.out('start a new Cursor session and try one prompt again.');
-        }
-        deps.io.out('Cursor hooks can emit a native follow-up, but its agent shell does not expose');
-        deps.io.out('the exact conversation id needed to register safely. `notifai ask` therefore');
-        deps.io.out('fails closed; use blocking `notifai send --reply` for questions.');
+        printHooksInstallClose(deps, harness, file);
         return EXIT.ok;
     }
-    let merged;
+    let foreignStopCount = 0;
+    let collapsedFrom = null;
     try {
-        merged = withTargetFileLock(file, () => {
+        withTargetFileLock(file, () => {
             const document = loadSettings(file);
+            foreignStopCount = foreignStopHandlers(document).length;
             const result = mergeHooks(document, buildHookConfig({
                 adapterPath,
                 harness,
@@ -1590,67 +1736,41 @@ export function hooksInstallCommand(deps, flags) {
             applyPlan(file, result.document);
             return result;
         });
+        if (harness === 'codex') {
+            collapsedFrom = collapseUnusedCodexRepresentation(file, scriptPath, codexLayerPaths(flags.global ?? false, deps.cwd, deps.env));
+        }
     }
     catch (err) {
         deps.io.err(String(err));
         return EXIT.failed;
     }
-    deps.io.out(`Installed ${harness} hooks in ${file}`);
-    if (merged.replaced.length > 0)
-        deps.io.out(`  replaced: ${merged.replaced.join(', ')}`);
-    if (merged.added.length > 0)
-        deps.io.out(`  added: ${merged.added.join(', ')}`);
-    if (merged.removed.length > 0) {
-        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.');
-    }
     if (harness === 'codex') {
         const layer = flags.global ? null : codexLayerDir(deps.cwd);
-        if (layer !== null) {
-            // Codex reads project hooks from the main repository but only looks when
-            // a `.codex` directory sits at or above cwd, so a worktree install has to
-            // write one file and create one directory in two different places. Doing
-            // it silently would leave the next person deriving this the hard way
-            //.
+        if (layer !== null)
             mkdirSync(layer, { recursive: true });
-            deps.io.out('');
-            deps.io.out('You are in a worktree. Codex reads project hooks from the main repository,');
-            deps.io.out(`so they were written to ${file}. ${layer} was created so this`);
-            deps.io.out('worktree discovers that file. Each other worktree needs its own `.codex`');
-            deps.io.out('directory; rerun this installer from that worktree to create it.');
-        }
     }
-    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.');
+    printHooksInstallClose(deps, harness, file);
+    if (collapsedFrom !== null) {
+        deps.io.out(`Collapsed ${collapsedFrom} onto ${file} so this layer has one representation.`);
     }
-    else if (harness === 'claude-code') {
-        deps.io.out('Send one new Claude Code prompt, then check `notifai doctor`. If the hook has');
-        deps.io.out('not fired, start a new Claude Code session and try one prompt again.');
+    if (foreignStopCount > 0) {
+        deps.io.out("This layer already has a Stop handler. Codex runs every matching handler, so Notifai's Stop and the existing one will both fire.");
     }
-    else {
-        deps.io.out('Send one Codex prompt, then check `notifai doctor`. If the hook has not fired,');
-        deps.io.out('start a new Codex session and try one prompt again.');
+    if (harness === 'codex') {
+        for (const problem of codexRepresentationProblems(deps.cwd, deps.env)) {
+            deps.io.out(problem);
+        }
     }
     return EXIT.ok;
 }
+function foreignStopHandlers(document) {
+    const groups = document.hooks?.['Stop'];
+    if (!Array.isArray(groups))
+        return [];
+    return groups
+        .flatMap((group) => group.hooks ?? [])
+        .filter((handler) => !/ hook (user-prompt-submit|stop|session-end)\b/.test(handler.command));
+}
 /**
  * Writes the OpenCode plugin, replacing any Notifai plugin already there —
  * including one a different checkout wrote, matched on the managed marker for
@@ -1677,16 +1797,7 @@ function installOpencodePlugin(deps, file, options) {
         deps.io.err(String(err));
         return EXIT.failed;
     }
-    deps.io.out(`Installed the OpenCode plugin at ${file}`);
-    deps.io.out('');
-    deps.io.out('It maps chat.message to presence, session.idle to question escalation, and');
-    deps.io.out('session.deleted to local cleanup through the same `notifai hook` commands');
-    deps.io.out('the other harnesses run. Permission prompts stay in OpenCode.');
-    deps.io.out('OpenCode does not expose a proven exactly-once continuation after session.idle,');
-    deps.io.out('so `notifai ask` fails closed there. Use blocking `notifai send --reply` when');
-    deps.io.out('the answer must return to the agent without another human prompt.');
-    deps.io.out('');
-    deps.io.out('Restart OpenCode: it loads plugins once at start.');
+    printHooksInstallClose(deps, 'opencode', file);
     return EXIT.ok;
 }
 export function hooksUninstallCommand(deps, flags) {
@@ -1743,28 +1854,34 @@ export function hooksUninstallCommand(deps, flags) {
             : `No Notifai hooks found in ${file}`);
         return EXIT.ok;
     }
-    let stripped;
+    const files = hookDefinitionFiles(harness, flags.global ?? false, deps.cwd, deps.env);
+    const existing = files.filter((candidate) => existsSync(candidate));
+    if (existing.length === 0) {
+        deps.io.out(`Nothing to remove: ${file} does not exist.`);
+        return EXIT.ok;
+    }
+    let removedAny = false;
     try {
-        stripped = withTargetFileLock(file, () => {
-            if (!existsSync(file))
-                return null;
-            const document = loadSettings(file);
-            const result = removeHooks(document, scriptPath);
-            applyPlan(file, result.document);
-            return result;
-        });
+        for (const candidate of existing) {
+            const stripped = withTargetFileLock(candidate, () => {
+                const document = loadSettings(candidate);
+                const result = removeHooks(document, scriptPath);
+                applyPlan(candidate, result.document);
+                return result;
+            });
+            if (stripped.replaced.length > 0) {
+                removedAny = true;
+                deps.io.out(`Removed Notifai hooks (${stripped.replaced.join(', ')}) from ${candidate}`);
+            }
+        }
     }
     catch (err) {
         deps.io.err(String(err));
         return EXIT.failed;
     }
-    if (stripped === null) {
-        deps.io.out(`Nothing to remove: ${file} does not exist.`);
-        return EXIT.ok;
+    if (!removedAny) {
+        deps.io.out(`No Notifai hooks found in ${existing.join(', ')}`);
     }
-    deps.io.out(stripped.replaced.length > 0
-        ? `Removed Notifai hooks (${stripped.replaced.join(', ')}) from ${file}`
-        : `No Notifai hooks found in ${file}`);
     return EXIT.ok;
 }
 function assertOwnedRegularFile(file) {
@@ -1777,6 +1894,12 @@ function assertOwnedRegularFile(file) {
         throw new Error(`${file} is owned by uid ${stat.uid}, not the current user.`);
     }
 }
+const HARNESS_LABEL = {
+    'claude-code': 'Claude Code',
+    codex: 'Codex',
+    cursor: 'Cursor',
+    opencode: 'OpenCode',
+};
 function resolveHarness(deps, requested) {
     if (requested !== undefined) {
         if (HARNESSES.includes(requested))
@@ -1784,20 +1907,61 @@ function resolveHarness(deps, requested) {
         deps.io.err(`Unknown harness "${requested}". Supported: ${HARNESSES.join(', ')}.`);
         return null;
     }
-    const detected = detectHarness(deps.cwd);
+    const detected = detectHarness(deps.cwd, deps.env);
     if (!detected) {
         deps.io.err(`Could not tell which harness to install for — pass --harness <${HARNESSES.join('|')}>.`);
         return null;
     }
     return detected;
 }
+/**
+ * Which harnesses to wire. An explicit `--harness` still wins as a singleton.
+ * Otherwise: every detected harness, or a human picker when detection is empty
+ * or names more than one.
+ */
+async function pickHarnessesToInstall(deps, requested) {
+    if (requested !== undefined) {
+        const harness = resolveHarness(deps, requested);
+        return harness === null ? null : [harness];
+    }
+    const detected = detectedHarnesses(deps.cwd, deps.env);
+    if (detected.length === 1)
+        return detected;
+    if (deps.io.interactive === true && deps.io.multiselect) {
+        const picked = await deps.io.multiselect('Which agent harnesses should Notifai wire here?', HARNESSES.map((name) => ({
+            value: name,
+            label: HARNESS_LABEL[name],
+            ...(detected.includes(name) ? { hint: 'detected on this machine' } : {}),
+        })), detected);
+        if (picked === null)
+            return null;
+        const unknown = picked.filter((name) => !HARNESSES.includes(name));
+        if (unknown.length > 0) {
+            deps.io.err(`Unknown harness "${unknown[0]}". Supported: ${HARNESSES.join(', ')}.`);
+            return null;
+        }
+        return picked;
+    }
+    if (detected.length === 0) {
+        deps.io.err(`Could not tell which harness to wire. Run: notifai hooks install --harness <${HARNESSES.join('|')}>`);
+        return null;
+    }
+    return detected;
+}
 // ---------------------------------------------------------------------------
 // config show / set / unset
 // ---------------------------------------------------------------------------
 export function configShowCommand(deps, flags) {
     const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     if (flags.json) {
-        const output = Object.fromEntries(CONFIG_KEYS.map((key) => [key, { value: config[key].value, source: config[key].source }]));
+        const output = Object.fromEntries(CONFIG_KEYS.map((key) => [
+            key,
+            {
+                value: config[key].value,
+                source: config[key].source,
+                summary: configInfo(key).summary,
+            },
+        ]));
         deps.io.out(JSON.stringify(output, null, 2));
         return EXIT.ok;
     }
@@ -1971,7 +2135,7 @@ async function configMutationTarget(deps, flags) {
         const selected = await deps.io.select('Where should this setting live?', [
             { value: 'global', label: 'This machine', hint: 'applies across projects' },
             { value: 'project', label: 'This project (shared)', hint: '.notifai/config.toml' },
-            { value: 'local', label: 'This project (personal)', hint: 'keep config.local.toml gitignored' },
+            { value: 'local', label: 'This project (personal)', hint: 'stored on this machine, not in the repo' },
         ]);
         if (selected === null) {
             deps.io.err('No configuration layer selected.');
@@ -1982,7 +2146,7 @@ async function configMutationTarget(deps, flags) {
     const targetPath = flags.session
         ? sessionConfigPath(flags.session, deps.env)
         : layer === 'local'
-            ? (findProjectLocalConfigPath(deps.cwd) ?? path.join(deps.cwd, '.notifai', 'config.local.toml'))
+            ? personalProjectConfigPath(deps.cwd, deps.env)
             : layer === 'project'
                 ? (findProjectConfigPath(deps.cwd) ?? path.join(deps.cwd, '.notifai', 'config.toml'))
                 : globalConfigPath(deps.env);
@@ -2222,12 +2386,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 = 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.
  */
-export const SKILLS_SOURCE = 'Raidiant-io/notifai#v0.4.0';
+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 +2430,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 +2443,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',
@@ -2380,23 +2553,27 @@ async function closeGap(deps, state, flags) {
         return 'closed';
     }
     if (state.id === 'hooks') {
-        let harness = detectHarness(deps.cwd);
-        if (harness === null && deps.io.interactive === true && deps.io.select) {
-            const picked = await deps.io.select('Which agent harness do you use here?', HARNESSES.map((name) => ({ value: name, label: name })));
-            if (picked !== null)
-                harness = picked;
-        }
-        if (harness === null) {
-            deps.io.err(`Could not tell which harness to wire. Run: notifai hooks install --harness <${HARNESSES.join('|')}>`);
+        const harnesses = await pickHarnessesToInstall(deps);
+        if (harnesses === null || harnesses.length === 0)
             return 'failed';
+        let ok = true;
+        for (const harness of harnesses) {
+            if (hooksInstallCommand(deps, { harness }) !== EXIT.ok)
+                ok = false;
         }
-        return hooksInstallCommand(deps, { harness }) === EXIT.ok ? 'closed' : 'failed';
+        return ok ? 'closed' : 'failed';
     }
     if (state.id === 'skill') {
         if (deps.nativeSkills === undefined) {
             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 = {
@@ -2673,6 +2850,12 @@ async function runSetupProof(deps) {
         'Proof may still arrive — re-run `notifai init` and it will re-check this same notification.');
     return 'pending';
 }
+/** Closing a local gap cannot have changed the service, the keychain, or devices. */
+function refreshAfterClose(id) {
+    return id === 'project' || id === 'hooks' || id === 'skill' || id === 'question-routing-settings'
+        ? ['local']
+        : undefined;
+}
 /** Whether an optional gap should be closed, given flags and who is watching. */
 function wantsOptional(deps, state, flags) {
     // Naming the project is init's whole reason to touch the filesystem, costs
@@ -2726,8 +2909,12 @@ export async function initCommand(deps, flags) {
         return EXIT.usage;
     }
     await deps.io.intro?.('Notifai setup');
-    const reassess = () => assessReadiness(deps, flags.skillsScope === undefined ? {} : { skillScope: flags.skillsScope });
-    let readiness = await reassess();
+    const skillOpts = flags.skillsScope === undefined ? {} : { skillScope: flags.skillsScope };
+    let readiness = await assessReadiness(deps, skillOpts);
+    const reassess = (refresh) => assessReadiness(deps, {
+        ...skillOpts,
+        ...(refresh === undefined ? {} : { previous: readiness, refresh }),
+    });
     let failed = false;
     const attempted = new Set();
     // Re-assess after every successful action. This is how a browser approval or
@@ -2759,7 +2946,7 @@ export async function initCommand(deps, flags) {
                 if (result === 'failed')
                     failed = true;
                 if (result === 'failed' && state.status === 'optional-gap') {
-                    readiness = await reassess();
+                    readiness = await reassess(refreshAfterClose(state.id));
                     advanced = true;
                     break;
                 }
@@ -2767,7 +2954,7 @@ export async function initCommand(deps, flags) {
                     stop = true;
                     break;
                 }
-                readiness = await reassess();
+                readiness = await reassess(refreshAfterClose(state.id));
                 advanced = true;
                 break;
             }
@@ -2780,7 +2967,7 @@ export async function initCommand(deps, flags) {
                     stop = true;
                     break;
                 }
-                readiness = await reassess();
+                readiness = await reassess(refreshAfterClose(state.id));
                 advanced = true;
                 break;
             }
@@ -2822,34 +3009,74 @@ export async function initCommand(deps, flags) {
         if (stop || !advanced)
             break;
     }
-    readiness = await reassess();
-    for (const state of readiness.states.filter((s) => s.status === 'ready')) {
-        deps.io.out(`${state.title}: ${state.detail}`);
+    await printInitClose(deps, readiness, flags);
+    const blocker = firstBlocker(readiness);
+    if (blocker === null)
+        return failed ? EXIT.failed : EXIT.ok;
+    return failed || deps.io.interactive !== true ? EXIT.failed : EXIT.ok;
+}
+function isHookSubstate(id) {
+    return id === 'hooks' || id.startsWith('hooks-') || id === 'question-routing-settings';
+}
+function leftoverOptionals(readiness, flags) {
+    return readiness.states.filter((state) => {
+        if (state.status !== 'optional-gap')
+            return false;
+        if (isHookSubstate(state.id))
+            return false;
+        if (state.id === 'skill' && flags.skills === false)
+            return false;
+        return true;
+    });
+}
+function printOptionalLeftovers(deps, leftovers) {
+    for (const state of leftovers) {
+        deps.io.out(`Optional, not set up — ${remedyLine(state)}`);
     }
+}
+function questionsWillRoute(readiness) {
+    const hooks = readiness.states.find((state) => state.id === 'hooks');
+    const settings = readiness.states.find((state) => state.id === 'question-routing-settings');
+    return hooks?.status === 'ready' && settings?.status !== 'gap';
+}
+async function printInitClose(deps, readiness, flags) {
     const blocker = firstBlocker(readiness);
+    const canSend = readiness.states.find((state) => state.id === 'devices')?.status === 'ready';
+    const questions = questionsWillRoute(readiness);
+    const leftovers = leftoverOptionals(readiness, flags);
+    if (deps.io.interactive === true) {
+        if (blocker === null) {
+            const lines = [
+                canSend ? 'You can send notifications.' : 'You are signed in.',
+                questions
+                    ? 'Questions will reach your devices.'
+                    : 'Questions stay in the terminal until hooks are installed.',
+            ];
+            await deps.io.note?.(lines.join('\n'), 'Ready');
+            printOptionalLeftovers(deps, leftovers);
+            deps.io.out('All set. Agents in this project can notify you and ask questions.');
+            await deps.io.outro?.('All set ✨');
+            return;
+        }
+        await deps.io.note?.(`${blocker.title} — ${blocker.detail}\n${remedyLine(blocker)}`, 'Next');
+        deps.io.out(`Next: ${blocker.title} — ${blocker.detail}`);
+        deps.io.out(`  ${remedyLine(blocker)}`);
+        if (blocker.remedy?.by === 'user-elsewhere' || blocker.remedy?.by === 'user-here') {
+            deps.io.out('  Then re-run `notifai init` and it will pick up from here.');
+        }
+        await deps.io.outro?.('One step remains (above)');
+        return;
+    }
     if (blocker === null) {
-        const skipped = openItems(readiness).filter((state) => !(state.id === 'skill' && flags.skills === false));
-        for (const state of skipped)
-            deps.io.out(`Optional, not set up — ${remedyLine(state)}`);
+        printOptionalLeftovers(deps, leftovers);
         deps.io.out('All set. Agents in this project can notify you and ask questions.');
-        await deps.io.outro?.('All set ✨');
-        return failed ? EXIT.failed : EXIT.ok;
+        return;
     }
-    // Exactly one. Everything else waits until this is done, because the next
-    // gap is frequently a consequence of this one and naming it now would send
-    // the reader off to fix something that is not actually wrong.
-    deps.io.out('');
     deps.io.out(`Next: ${blocker.title} — ${blocker.detail}`);
     deps.io.out(`  ${remedyLine(blocker)}`);
-    // Both "do it here" and "do it elsewhere" leave setup mid-journey; re-run is
-    // how the rest is recovered either way.
     if (blocker.remedy?.by === 'user-elsewhere' || blocker.remedy?.by === 'user-here') {
         deps.io.out('  Then re-run `notifai init` and it will pick up from here.');
     }
-    await deps.io.outro?.('One step remains (above)');
-    // An agent must be able to branch on setup being blocked without parsing
-    // prose. A present human may deliberately leave and resume later.
-    return failed || deps.io.interactive !== true ? EXIT.failed : EXIT.ok;
 }
 // ---------------------------------------------------------------------------
 // doctor
@@ -2892,23 +3119,10 @@ async function contractCheck(client) {
         };
     }
 }
-/**
- * Read the whole setup once, in dependency order.
- *
- * Descent stops where a prerequisite is missing: without a credential there is
- * nothing to ask the server with, and without a reachable server a contract
- * mismatch is unknowable rather than absent. Those downstream states report
- * `unknown`, which is the honest answer and keeps a network outage from
- * looking like a broken install.
- */
-export async function assessReadiness(deps, options = {}) {
-    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
-    const states = [];
-    let accountClient = null;
-    let accountDevices = null;
+function projectReadiness(deps, config) {
     const configPath = path.join(deps.cwd, '.notifai', 'config.toml');
     const projectSlug = config.project.value;
-    states.push(projectSlug !== null
+    return projectSlug !== null
         ? {
             id: 'project',
             title: 'Project identity',
@@ -2928,7 +3142,73 @@ export async function assessReadiness(deps, options = {}) {
                 summary: 'name this project after its directory',
                 command: 'notifai init',
             },
-        });
+        };
+}
+function remoteStatesFrom(previous) {
+    const pick = (id) => previous.states.find((state) => state.id === id);
+    const credential = pick('credential');
+    const server = pick('server');
+    const contract = pick('contract');
+    const auth = pick('auth');
+    const devices = pick('devices');
+    const proof = pick('proof');
+    if (credential === undefined ||
+        server === undefined ||
+        contract === undefined ||
+        auth === undefined ||
+        devices === undefined ||
+        proof === undefined) {
+        return null;
+    }
+    return { credential, server, contract, auth, devices, proof };
+}
+function remoteInvalidatedByConfig(previous, config) {
+    if (config.base_url.source === 'default')
+        return false;
+    const server = previous.states.find((state) => state.id === 'server');
+    return server === undefined || !server.detail.includes(config.base_url.value);
+}
+/**
+ * Read the whole setup once, in dependency order.
+ *
+ * Descent stops where a prerequisite is missing: without a credential there is
+ * nothing to ask the server with, and without a reachable server a contract
+ * mismatch is unknowable rather than absent. Those downstream states report
+ * `unknown`, which is the honest answer and keeps a network outage from
+ * looking like a broken install.
+ */
+export async function assessReadiness(deps, options = {}) {
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
+    const previous = options.previous;
+    const refresh = options.refresh;
+    if (previous !== undefined && refresh !== undefined && refresh.length === 0)
+        return previous;
+    const reuseRemote = previous !== undefined &&
+        refresh !== undefined &&
+        !refresh.includes('remote') &&
+        !remoteInvalidatedByConfig(previous, config);
+    if (reuseRemote) {
+        const reused = remoteStatesFrom(previous);
+        if (reused !== null) {
+            return {
+                states: [
+                    projectReadiness(deps, config),
+                    reused.credential,
+                    reused.server,
+                    reused.contract,
+                    reused.auth,
+                    ...hookStates(deps),
+                    await skillReadiness(deps, options.skillScope),
+                    reused.devices,
+                    reused.proof,
+                ],
+            };
+        }
+    }
+    const states = [];
+    let accountClient = null;
+    let accountDevices = null;
+    states.push(projectReadiness(deps, config));
     const credential = deps.store.load();
     states.push(credential
         ? {
@@ -2967,10 +3247,10 @@ export async function assessReadiness(deps, options = {}) {
             id: 'server',
             title: 'Service',
             status: 'gap',
-            detail: `cannot reach ${baseUrl} (${config.base_url.source})`,
+            detail: `cannot reach ${baseUrl}`,
             remedy: {
                 by: 'user-here',
-                summary: 'check your network, or the base_url shown above',
+                summary: 'check your network',
                 command: 'notifai doctor',
             },
         });
@@ -3176,8 +3456,8 @@ async function setupProofState(deps, config, client, devices) {
         };
     }
 }
-export async function doctorCommand(deps, flags) {
-    const readiness = await assessReadiness(deps);
+export async function doctorCommand(deps, flags, options = {}) {
+    const readiness = options.readiness ?? (await assessReadiness(deps));
     const blocker = firstBlocker(readiness);
     const ok = blocker === null;
     if (flags.json) {
@@ -3267,7 +3547,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 +3555,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 +3619,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 +3674,21 @@ function hookChecks(deps) {
             .map((i) => `${i.harness} ${i.global ? 'global' : 'project'} (${i.file})`)
             .join(', '),
     });
-    const active = activeHarnessSession(deps.env);
+    const wired = new Set(installations.map((installation) => installation.harness));
+    const unwired = detectedHarnesses(deps.cwd, deps.env).filter((harness) => !wired.has(harness));
+    if (unwired.length > 0) {
+        checks.push({
+            name: 'hooks (detected)',
+            ok: false,
+            informational: true,
+            detail: `${unwired.map((harness) => HARNESS_LABEL[harness]).join(', ')} detected on this machine but not wired`,
+            remedy: {
+                summary: 'install hooks for every detected harness',
+                command: 'notifai hooks install',
+            },
+        });
+    }
+    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 +3781,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
@@ -3477,7 +3798,8 @@ function hookChecks(deps) {
         harness,
         installations: installations.filter((i) => i.harness === harness),
     }))
-        .filter((entry) => entry.installations.length > 1);
+        .filter((entry) => entry.installations.some((installation) => installation.global) &&
+        entry.installations.some((installation) => !installation.global));
     if (duplicated.length > 0) {
         checks.push({
             name: 'hooks (duplicates)',
@@ -3487,6 +3809,25 @@ function hookChecks(deps) {
                 .join('; '),
         });
     }
+    const representationProblems = codexRepresentationProblems(deps.cwd, deps.env);
+    if (representationProblems.length > 0) {
+        const collapseCommand = representationProblems.some((problem) => problem.includes('--global'))
+            ? 'notifai hooks install --harness codex --global'
+            : 'notifai hooks install --harness codex';
+        checks.push({
+            name: 'hooks (codex representation)',
+            ok: false,
+            detail: representationProblems.join('; '),
+            ...(representationProblems.some((problem) => problem.includes('to collapse onto'))
+                ? {
+                    remedy: {
+                        summary: 'collapse this Codex layer onto a single hook file',
+                        command: collapseCommand,
+                    },
+                }
+                : {}),
+        });
+    }
     if (active !== null && activeInstallations.length > 0) {
         const admissionProblems = activeQuestionRouteProblems(deps, active, installations);
         checks.push({
@@ -3497,14 +3838,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 +3876,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 +3916,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.
  *
@@ -3562,15 +3992,20 @@ function codexStrayWorktreeCheck(deps) {
     if (layer === null)
         return null;
     const root = codexProjectRoot(deps.cwd);
-    const stray = path.join(path.dirname(layer), '.codex', 'hooks.json');
-    if (!existsSync(path.join(root, '.codex', 'hooks.json')))
+    const project = inspectCodexLayer(codexLayerPaths(false, deps.cwd, deps.env));
+    if (project.jsonEvents.length === 0 && project.tomlEvents.length === 0)
         return null;
+    const strayJson = path.join(path.dirname(layer), '.codex', 'hooks.json');
+    const strayToml = path.join(path.dirname(layer), '.codex', 'config.toml');
     const problems = [];
     if (!existsSync(layer)) {
         problems.push(`${layer} is missing, so Codex never looks for project hooks here`);
     }
-    if (existsSync(stray)) {
-        problems.push(`${stray} is never read — Codex reads ${root}/.codex/hooks.json instead`);
+    if (existsSync(strayJson) && path.resolve(strayJson) !== path.resolve(project.paths.hooksJson)) {
+        problems.push(`${strayJson} is never read — Codex reads ${project.writeTarget} instead`);
+    }
+    if (existsSync(strayToml) && path.resolve(strayToml) !== path.resolve(project.paths.configToml)) {
+        problems.push(`${strayToml} is never read — Codex reads ${project.writeTarget} instead`);
     }
     return {
         name: 'hooks (codex worktree)',
@@ -3630,6 +4065,18 @@ export function realIo(env = process.env) {
             const answer = await p.select({ message, options });
             return p.isCancel(answer) ? null : answer;
         },
+        multiselect: async (message, options, initial) => {
+            if (!interactive())
+                return null;
+            const p = await clack();
+            const answer = await p.multiselect({
+                message,
+                options,
+                required: true,
+                ...(initial !== undefined && initial.length > 0 ? { initialValues: initial } : {}),
+            });
+            return p.isCancel(answer) ? null : answer;
+        },
         intro: async (title) => {
             if (!interactive())
                 return;