@raidiant/notifai 0.2.1 → 0.4.0

package/dist/commands.js

@@ -1,19 +1,38 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 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, } from './client.js';
-import { BOOLEAN_CONFIG_KEYS, CONFIG_KEYS, NUMERIC_CONFIG_KEYS, configBounds, findProjectConfigPath, findProjectLocalConfigPath, globalConfigPath, loadConfig, sessionConfigPath, } from './config.js';
-import { firstBlocker, openItems } from './readiness.js';
-import { handleSessionEnd, handleStop, handleUserPromptSubmit, parseHookInput, pruneAbandonedSessions, readProjectSession, readProjectSessionPointer, readSessionState, registerQuestion, } from './hooks.js';
+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 { 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 { HARNESSES, applyPlan, blockingHookTimeoutSeconds, buildCursorHookConfig, buildHookConfig, codexLayerDir, codexProjectRoot, detectHarness, findInstallations, handlerEvent, loadCursorSettings, loadSettings, mergeCursorHooks, mergeHooks, removeCursorHooks, removeHooks, settingsFile, } from './install-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 { 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. */
+export function log(deps) {
+    return deps.logger ?? nullLogger();
+}
+function loadLoggedConfig(deps, options) {
+    const config = loadConfig(options);
+    const logger = log(deps);
+    logger.adopt(logSettingsFrom(config));
+    logger.bind({ project: config.project.value });
+    logConfigResolved(logger, config);
+    return config;
+}
 export const EXIT = {
     ok: 0,
     failed: 1,
@@ -23,7 +42,7 @@ export const EXIT = {
     network: 5,
 };
 function makeClient(deps, baseUrl, bearer, options) {
-    return (deps.clientFactory ?? createClient)(baseUrl, bearer, options);
+    return (deps.clientFactory ?? createClient)(baseUrl, bearer, { ...options, logger: log(deps) });
 }
 function resolvedBaseUrl(config, credential) {
     return config.base_url.source === 'default' && credential ? credential.baseUrl : config.base_url.value;
@@ -31,6 +50,10 @@ function resolvedBaseUrl(config, credential) {
 function authedClient(deps, config) {
     const credential = deps.store.load();
     if (!credential) {
+        // The commonest reason a command does nothing, and one that leaves no other
+        // trace: it returns before any request is made, so without this the log
+        // shows an exit code and no cause.
+        log(deps).error('cli.error', { kind: 'auth', message: 'not signed in', store: deps.store.describe() });
         deps.io.err('Not signed in. Run `notifai login` first.');
         return null;
     }
@@ -40,7 +63,18 @@ function authedClient(deps, config) {
         baseUrl,
     };
 }
-function reportError(deps, err) {
+function reportError(deps, err, context = {}) {
+    // Recorded before it is printed: stderr from an agent's shell call is often
+    // the one thing that does not survive into the next turn, and this is exactly
+    // the line someone comes back looking for.
+    log(deps).error('cli.error', {
+        ...context,
+        ...(err instanceof ApiCallError
+            ? { kind: 'api', status: err.status, code: err.code, message: err.message, next_action: err.nextAction, details: err.details }
+            : err instanceof NetworkError
+                ? { kind: 'network', message: err.message }
+                : { kind: 'unknown', message: String(err) }),
+    });
     if (err instanceof ApiCallError) {
         deps.io.err(`${err.code}: ${err.message}`);
         if (err.nextAction)
@@ -60,7 +94,7 @@ function reportError(deps, err) {
 // login / logout / auth status
 // ---------------------------------------------------------------------------
 export async function loginCommand(deps, flags) {
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env, flags: { base_url: flags.baseUrl } });
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env, flags: { base_url: flags.baseUrl } });
     const baseUrl = config.base_url.value;
     const machineName = flags.name ?? os.hostname();
     const secret = randomBytes(32).toString('base64url');
@@ -178,7 +212,7 @@ export function authStatusCommand(deps, flags) {
 }
 /** Show the server's account access decision without attempting a product mutation. */
 export async function accessStatusCommand(deps, flags) {
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     const authed = authedClient(deps, config);
     if (!authed)
         return EXIT.auth;
@@ -206,7 +240,7 @@ export async function accessStatusCommand(deps, flags) {
 // devices / capabilities
 // ---------------------------------------------------------------------------
 export async function devicesCommand(deps, flags) {
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     const authed = authedClient(deps, config);
     if (!authed)
         return EXIT.auth;
@@ -237,8 +271,35 @@ export async function devicesCommand(deps, flags) {
         return reportError(deps, err);
     }
 }
+/**
+ * Devices as data, for surfaces that render them themselves.
+ *
+ * `devicesCommand` prints and returns an exit code, which is the right shape
+ * for a command and the wrong one for a menu that wants to show names beside
+ * checkboxes. Silent on every failure by design: the interactive app already
+ * shows the credential and connectivity state on its status card, so a second
+ * error line here would be reporting the same fault twice.
+ */
+export async function deviceInventory(deps) {
+    if (!deps.store.load())
+        return null;
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
+    const authed = authedClient(deps, config);
+    if (!authed)
+        return null;
+    try {
+        return (await authed.client.listDevices()).devices;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether a device is in a state where a notification would actually arrive. */
+export function canDeviceReceive(device) {
+    return deviceCanReceive(device);
+}
 export async function capabilitiesCommand(deps, flags) {
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     const credential = deps.store.load();
     const baseUrl = resolvedBaseUrl(config, credential);
     const client = makeClient(deps, baseUrl, null);
@@ -303,7 +364,7 @@ export async function sendCommand(deps, flags) {
         deps.io.err(`--reply-window must be an integer from 60 to ${REPLY_MAX_WINDOW_SECONDS} seconds.`);
         return EXIT.usage;
     }
-    const config = loadConfig({
+    const config = loadLoggedConfig(deps, {
         cwd: deps.cwd,
         env: deps.env,
         flags: { base_url: flags.baseUrl, wait_seconds: flags.wait },
@@ -342,33 +403,67 @@ export async function sendCommand(deps, flags) {
     }
     const waitSeconds = flags.noWait ? 0 : config.wait_seconds.value;
     const idempotencyKey = flags.idempotencyKey ?? `cli-${randomBytes(12).toString('base64url')}`;
+    let receipt;
     try {
-        const receipt = await authed.client.submit({ idempotency_key: idempotencyKey, draft: build.draft }, waitSeconds);
-        const receiptExit = receiptExitCode(receipt);
-        if (!flags.json)
-            deps.io.out(formatReceipt(receipt));
-        else if (flags.reply)
-            deps.io.out(JSON.stringify({ type: 'receipt', receipt }));
-        // A zero wait can no longer reach here: --reply guarantees a positive one.
-        if (!flags.reply || receiptExit !== EXIT.ok) {
-            if (flags.json) {
-                deps.io.out(flags.reply
-                    ? JSON.stringify({
-                        type: 'reply_result',
-                        request_id: receipt.request_id,
-                        replies: [],
-                        degraded: false,
-                    })
-                    : JSON.stringify(receipt, null, 2));
-            }
-            return receiptExit;
+        receipt = await authed.client.submit({ idempotency_key: idempotencyKey, draft: build.draft }, waitSeconds);
+    }
+    catch (err) {
+        return reportError(deps, err);
+    }
+    const receiptExit = receiptExitCode(receipt);
+    // The single most useful line in the log: it ties the local invocation to
+    // the server-side request id, which is what every later question about this
+    // notification ("did it arrive?", "which device?") is asked in terms of.
+    log(deps).info('send.submitted', {
+        request_id: receipt.request_id,
+        kind: flags.reply ? 'question' : (flags.kind ?? 'update'),
+        title: flags.title,
+        overall: receipt.overall,
+        replayed: receipt.replayed,
+        deliveries: receipt.deliveries.length,
+        wait_seconds: waitSeconds,
+        exit: receiptExit,
+    });
+    log(deps).info('send.outcome', {
+        request_id: receipt.request_id,
+        overall: receipt.overall,
+        // Per device, because "it said accepted but nothing arrived" is answered
+        // by which device reached which state and why the provider said so.
+        devices: receipt.deliveries.map((delivery) => ({
+            device: delivery.device_name,
+            state: delivery.state,
+            attempts: delivery.attempts,
+            provider_status: delivery.provider_status,
+            provider_reason: delivery.provider_reason,
+        })),
+        ...(receipt.warnings.length > 0 ? { warnings: receipt.warnings } : {}),
+    });
+    if (!flags.json)
+        deps.io.out(formatReceipt(receipt));
+    else if (flags.reply)
+        deps.io.out(JSON.stringify({ type: 'receipt', receipt }));
+    // A zero wait can no longer reach here: --reply guarantees a positive one.
+    if (!flags.reply || receiptExit !== EXIT.ok) {
+        if (flags.json) {
+            deps.io.out(flags.reply
+                ? JSON.stringify({
+                    type: 'reply_result',
+                    request_id: receipt.request_id,
+                    replies: [],
+                    degraded: false,
+                })
+                : JSON.stringify(receipt, null, 2));
         }
+        return receiptExit;
+    }
+    try {
         const result = await waitForReply(authed.client, receipt.request_id, {
             timeoutSeconds: replyTimeout,
             afterSeq: 0,
             now: deps.now,
             sleep: deps.sleep,
         });
+        recordReplies(deps, receipt.request_id, result.response.replies);
         if (flags.json) {
             deps.io.out(JSON.stringify({
                 type: 'reply_result',
@@ -382,16 +477,46 @@ export async function sendCommand(deps, flags) {
         else
             printNoReply(deps, receipt.request_id, result.response.reply_expires_at);
         if (result.degraded) {
-            deps.io.err(DEGRADED_WAIT_WARNING);
+            log(deps).error('cli.error', {
+                kind: 'network',
+                operation: 'reply_wait',
+                request_id: receipt.request_id,
+                degraded: true,
+                message: 'the reply wait ended while the server was unreachable or faulting',
+            });
+            deps.io.err(degradedWaitWarning(receipt.request_id));
             return EXIT.network;
         }
         if (result.timedOut) {
             deps.io.err(`No reply yet. Retrieve it with \`notifai replies ${receipt.request_id}\` or retire the question with ` +
-                `\`notifai close ${receipt.request_id}\`.`);
+                `\`notifai close ${receipt.request_id}\`. ` +
+                `This is a reply-wait timeout, not a Delivery or Companion Receipt failure — check with \`notifai status ${receipt.request_id}\`.`);
         }
         return result.timedOut ? EXIT.noReply : EXIT.ok;
     }
     catch (err) {
+        // Receipt already printed; a wait fault must not read as "send failed".
+        // Permanent poll errors (auth, closed window, not found) still surface, but
+        // always name the durable request and point at recovery.
+        if (err instanceof ApiCallError || err instanceof NetworkError) {
+            log(deps).error('cli.error', {
+                kind: err instanceof ApiCallError ? 'api' : 'network',
+                operation: 'reply_wait',
+                request_id: receipt.request_id,
+                ...(err instanceof ApiCallError ? { status: err.status, code: err.code } : {}),
+                message: err.message,
+            });
+            deps.io.err(`notifai: reply wait failed for ${receipt.request_id} (${err instanceof ApiCallError ? err.code : 'network'}: ${err.message}). ` +
+                `Delivery and Companion Receipt are independent — check with \`notifai status ${receipt.request_id}\` and retry with \`notifai replies ${receipt.request_id}\`.`);
+            if (err instanceof ApiCallError) {
+                if (err.code === 'auth_required' || err.code === 'machine_revoked')
+                    return EXIT.auth;
+                return err.status >= 500 || err.status === 429 || err.status === 408
+                    ? EXIT.network
+                    : EXIT.failed;
+            }
+            return EXIT.network;
+        }
         return reportError(deps, err);
     }
 }
@@ -455,44 +580,55 @@ export async function repliesCommand(deps, requestedId, flags) {
         deps.io.err('Pass a request id or --pending.');
         return EXIT.usage;
     }
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     const authed = authedClient(deps, config);
     if (!authed)
         return EXIT.auth;
     try {
         let anyReplies = false;
-        let anyDegraded = false;
+        const degradedRequestIds = [];
         let allTimedOut = true;
         const jsonBodies = [];
         for (const requestId of requestIds) {
-            const result = await waitForReply(authed.client, requestId, {
-                timeoutSeconds: waitSeconds,
-                afterSeq,
-                now: deps.now,
-                sleep: deps.sleep,
-            });
-            if (flags.json) {
-                jsonBodies.push({ ...result.response, degraded: result.degraded });
-            }
-            else if (result.response.replies.length > 0) {
-                if (flags.pending === true)
-                    deps.io.out(`pending request ${requestId}`);
-                printReplies(deps, result.response.replies);
+            try {
+                const result = await waitForReply(authed.client, requestId, {
+                    timeoutSeconds: waitSeconds,
+                    afterSeq,
+                    now: deps.now,
+                    sleep: deps.sleep,
+                });
+                recordReplies(deps, requestId, result.response.replies);
+                if (flags.json) {
+                    jsonBodies.push({ ...result.response, degraded: result.degraded });
+                }
+                else if (result.response.replies.length > 0) {
+                    if (flags.pending === true)
+                        deps.io.out(`pending request ${requestId}`);
+                    printReplies(deps, result.response.replies);
+                }
+                else {
+                    printNoReply(deps, requestId, result.response.reply_expires_at);
+                }
+                anyReplies ||= result.response.replies.length > 0;
+                if (result.degraded)
+                    degradedRequestIds.push(requestId);
+                allTimedOut &&= result.timedOut;
             }
-            else {
-                printNoReply(deps, requestId, result.response.reply_expires_at);
+            catch (err) {
+                recordDegradedReplyWaits(deps, degradedRequestIds);
+                return reportError(deps, err, { operation: 'reply_wait', request_id: requestId });
             }
-            anyReplies ||= result.response.replies.length > 0;
-            anyDegraded ||= result.degraded;
-            allTimedOut &&= result.timedOut;
         }
         if (flags.json) {
             // One request keeps the response shape agents already parse; several
             // (only possible via --pending) arrive as an array in queue order.
             deps.io.out(JSON.stringify(jsonBodies.length === 1 ? jsonBodies[0] : jsonBodies, null, 2));
         }
-        if (anyDegraded) {
-            deps.io.err(DEGRADED_WAIT_WARNING);
+        if (degradedRequestIds.length > 0) {
+            recordDegradedReplyWaits(deps, degradedRequestIds);
+            // Name a request whose polls actually degraded, not merely the first item
+            // in a multi-request queue that may have completed cleanly.
+            deps.io.err(degradedWaitWarning(degradedRequestIds[0]));
             return EXIT.network;
         }
         if (anyReplies)
@@ -509,8 +645,8 @@ export async function waitForReply(client, requestId, options) {
     const sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
     const deadline = now() + options.timeoutSeconds * 1000;
     let lastResponse = null;
-    let lastNetworkError = null;
-    let consecutiveNetworkErrors = 0;
+    let lastTransientError = null;
+    let consecutiveTransientErrors = 0;
     let firstPoll = true;
     while (firstPoll || now() < deadline) {
         firstPoll = false;
@@ -522,8 +658,8 @@ export async function waitForReply(client, requestId, options) {
                 afterSeq: options.afterSeq,
             });
             lastResponse = response;
-            lastNetworkError = null;
-            consecutiveNetworkErrors = 0;
+            lastTransientError = null;
+            consecutiveTransientErrors = 0;
             if (response.replies.length > 0)
                 return { response, timedOut: false, degraded: false };
             const pauseMs = Math.min(250, Math.max(0, deadline - now()));
@@ -531,19 +667,22 @@ export async function waitForReply(client, requestId, options) {
                 await sleep(pauseMs);
         }
         catch (err) {
-            if (!(err instanceof NetworkError))
+            if (!isRetryableReplyPollError(err))
                 throw err;
-            lastNetworkError = err;
-            consecutiveNetworkErrors += 1;
+            lastTransientError = err instanceof Error ? err : new Error(String(err));
+            consecutiveTransientErrors += 1;
             const remainingAfterError = Math.max(0, deadline - now());
             if (remainingAfterError === 0)
                 break;
-            const backoffMs = Math.min(250 * 2 ** (consecutiveNetworkErrors - 1), 2_000, remainingAfterError);
+            const backoffMs = Math.min(250 * 2 ** (consecutiveTransientErrors - 1), 2_000, remainingAfterError);
             await sleep(backoffMs);
         }
     }
-    if (!lastResponse && lastNetworkError)
-        throw lastNetworkError;
+    // Never saw a successful poll: surface the fault so callers get EXIT.network
+    // rather than a fake empty silence. The durable request is still on the
+    // server; the typed recovery is `notifai replies <id>`.
+    if (!lastResponse && lastTransientError)
+        throw lastTransientError;
     return {
         response: lastResponse ??
             { request_id: requestId, reply_expires_at: null, replies: [] },
@@ -551,19 +690,50 @@ export async function waitForReply(client, requestId, options) {
         // A poll succeeded at some point, so we do not throw — but the last thing
         // we know is that we could not reach the server. Reporting that as a plain
         // "no reply" would let an agent treat an unseen refusal as consent.
-        degraded: lastNetworkError !== null,
+        degraded: lastTransientError !== null,
     };
 }
+function recordDegradedReplyWaits(deps, requestIds) {
+    if (requestIds.length === 0)
+        return;
+    log(deps).error('cli.error', {
+        kind: 'network',
+        operation: 'reply_wait',
+        request_ids: requestIds,
+        degraded: true,
+        message: 'the reply wait ended while the server was unreachable or faulting',
+    });
+}
 /**
  * Shared by every surface that waits: "the user did not answer" and "I could
  * not find out" must not look the same, because agents branch on the exit code
  * and one of those two branches is safe to proceed from.
+ *
+ * Delivery / Companion Receipt / OS presentation are separate facts — a wait
+ * fault is not evidence that the push failed.
  */
-const DEGRADED_WAIT_WARNING = 'notifai: the wait ended during a network outage, so this is "could not find out", ' +
-    'not "no answer" — the reply may already be waiting. Retry with `notifai replies <id>`.';
+function degradedWaitWarning(requestId) {
+    return (`notifai: the wait for ${requestId} ended while the server was unreachable or faulting, ` +
+        `so this is "could not find out", not "no answer" — the request is still durable and the ` +
+        `reply may already be waiting (Provider Acceptance and Companion Receipt are independent). ` +
+        `Retry with \`notifai replies ${requestId}\`.`);
+}
 function isNonNegativeInteger(value) {
     return Number.isInteger(value) && value >= 0;
 }
+function recordReplies(deps, requestId, replies) {
+    const logger = log(deps);
+    for (const reply of replies) {
+        logger.info('reply.received', {
+            request_id: requestId,
+            sequence: reply.seq,
+            device: reply.device_name,
+            text: reply.text,
+            answers: reply.answers,
+            source: reply.source,
+        });
+    }
+}
 function printReplies(deps, replies) {
     for (const reply of replies)
         deps.io.out(`reply from ${reply.device_name}: ${reply.text}`);
@@ -604,7 +774,7 @@ function printNoReply(deps, requestId, expiresAt) {
         : `no reply yet for request ${requestId}; the reply window remains open`);
 }
 export async function statusCommand(deps, requestId, flags) {
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     const authed = authedClient(deps, config);
     if (!authed)
         return EXIT.auth;
@@ -615,6 +785,7 @@ export async function statusCommand(deps, requestId, flags) {
             return EXIT.ok;
         }
         deps.io.out(`request ${snapshot.request_id} (${snapshot.event ?? 'no event'}) — ${snapshot.overall}`);
+        let anyReplyReceived = false;
         for (const d of snapshot.deliveries) {
             deps.io.out(`  ${d.device_name}:`);
             deps.io.out(`    Delivery: ${d.state} after ${d.attempts} attempt(s)`);
@@ -627,10 +798,24 @@ export async function statusCommand(deps, requestId, flags) {
             else {
                 deps.io.out("    Companion Receipt (the app's delivery confirmation): unknown — not observed; this is not a failure or proof of non-receipt");
             }
+            // Notifai never learns whether the OS painted a banner; saying so stops
+            // a reply-wait fault from being misread as "the phone never showed it".
+            deps.io.out('    OS presentation: not observed by Notifai — Provider Acceptance and Companion Receipt do not prove a banner was shown');
+            const replyEvent = d.events.find((e) => e.stage === 'reply_received');
+            if (replyEvent) {
+                anyReplyReceived = true;
+                deps.io.out(`    Reply received: yes (first at ${replyEvent.occurred_at})`);
+            }
+            else {
+                deps.io.out('    Reply received: not yet recorded on this delivery');
+            }
             for (const e of d.events) {
                 deps.io.out(`      ${e.occurred_at}  ${e.stage}${e.reason ? ` (${e.reason})` : ''}`);
             }
         }
+        deps.io.out(anyReplyReceived
+            ? `  Reply wait: answers are on the server — collect with \`notifai replies ${snapshot.request_id}\` (a local wait fault does not erase them)`
+            : `  Reply wait: no answer stored yet — a blocking wait failure is independent of Delivery above; retry with \`notifai replies ${snapshot.request_id}\``);
         return EXIT.ok;
     }
     catch (err) {
@@ -693,6 +878,10 @@ async function uploadImage(deps, client, source) {
 // hook / ask / close — harness integration
 // ---------------------------------------------------------------------------
 export const HOOK_EVENTS = ['user-prompt-submit', 'stop', 'session-end'];
+/** SessionEnd cleanup must precede every diagnostic that can wait on a file lock. */
+export function hookDefersDiagnosticsUntilAfterCleanup(event) {
+    return event === 'session-end';
+}
 /**
  * Runs one harness hook. Contract with every harness: hook JSON arrives on
  * stdin, the decision (if any) goes to stdout, diagnostics go to stderr, and
@@ -707,54 +896,128 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
         deps.io.err(`Unknown hook event "${event}". Valid: ${HOOK_EVENTS.join(', ')}`);
         return EXIT.usage;
     }
-    let envelope;
+    // One clock owns the complete Stop invocation, including stdin, config,
+    // credentials, and client construction. Starting this inside `handleStop`
+    // 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 logger = log(deps);
+    logger.bind({ cmd: `hook ${event}` });
+    let started = false;
+    const start = (data = {}) => {
+        if (started)
+            return;
+        started = true;
+        logger.info('hook.start', { hook: event, harness: harness ?? 'unknown', ...data });
+    };
+    const failureData = (err) => err instanceof ApiCallError
+        ? { status: err.status, code: err.code, message: err.message, details: err.details }
+        : { message: err instanceof Error ? err.message : String(err) };
+    let raw;
     try {
-        const raw = await readStdin();
-        if (raw.trim() !== '') {
-            try {
-                const parsed = JSON.parse(raw);
-                if (typeof parsed !== 'object' || parsed === null)
-                    throw new Error('not an object');
-            }
-            catch {
-                deps.io.err('notifai: ignored malformed or truncated hook input; no routing action was taken');
-                return EXIT.ok;
-            }
+        raw = await readStdin();
+    }
+    catch (err) {
+        start({ input: 'unavailable' });
+        logger.error('hook.end', {
+            hook: event,
+            outcome: 'ignored',
+            reason: 'input-read-failed',
+            ...failureData(err),
+        });
+        return EXIT.ok;
+    }
+    if (raw.trim() !== '') {
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== 'object' || parsed === null)
+                throw new Error('not an object');
         }
-        envelope = parseHookInput(raw);
-        if (harness === 'cursor') {
-            const sessionId = envelope.session_id ?? envelope.conversation_id;
-            const cwd = envelope.cwd ?? envelope.workspace_roots?.[0];
-            envelope = {
-                ...envelope,
-                ...(sessionId === undefined ? {} : { session_id: sessionId }),
-                ...(cwd === undefined ? {} : { cwd }),
-                stop_hook_active: envelope.stop_hook_active ??
-                    (typeof envelope.loop_count === 'number' && envelope.loop_count > 0),
-            };
+        catch {
+            start({ input: 'malformed' });
+            logger.error('hook.end', { hook: event, outcome: 'ignored', reason: 'malformed-input' });
+            deps.io.err('notifai: ignored malformed or truncated hook input; no routing action was taken');
+            return EXIT.ok;
         }
     }
-    catch {
-        return EXIT.ok;
+    let envelope = parseHookInput(raw);
+    if (harness === 'cursor') {
+        const sessionId = envelope.session_id ?? envelope.conversation_id;
+        const cwd = envelope.cwd ?? envelope.workspace_roots?.[0];
+        envelope = {
+            ...envelope,
+            ...(sessionId === undefined ? {} : { session_id: sessionId }),
+            ...(cwd === undefined ? {} : { cwd }),
+            stop_hook_active: envelope.stop_hook_active ??
+                (typeof envelope.loop_count === 'number' && envelope.loop_count > 0),
+        };
+    }
+    const cwd = envelope.cwd ?? deps.cwd;
+    const sessionEnd = hookDefersDiagnosticsUntilAfterCleanup(event);
+    logger.bind({ session: envelope.session_id ?? null });
+    let config = null;
+    let configFailure;
+    try {
+        config = loadConfig({ cwd, env: deps.env, sessionId: envelope.session_id });
+        // The hook's project is the session's, not this process's, and the log
+        // settings that apply are that project's too. Keeping a mutable bootstrap
+        // logger lets this more-specific layer turn logging back on.
+        logger.adopt(logSettingsFrom(config));
+        logger.bind({ project: config.project.value });
+        if (!sessionEnd) {
+            start({ cwd, stop_hook_active: envelope.stop_hook_active ?? null });
+            logConfigResolved(logger, config);
+        }
+    }
+    catch (err) {
+        configFailure = err;
+        if (!sessionEnd) {
+            start({ cwd, stop_hook_active: envelope.stop_hook_active ?? null });
+            logger.error('hook.end', {
+                hook: event,
+                outcome: 'failed',
+                reason: 'config-failed',
+                ...failureData(err),
+            });
+            for (const line of describeHookFailure(err))
+                deps.io.err(`notifai: ${line}`);
+            return EXIT.ok;
+        }
     }
-    // Everything below is inside one fail-open boundary. Config parsing,
-    // credential loading and client construction can all throw, and a hook that
-    // exits non-zero makes the harness report a failure — strictly worse for the
-    // user than not having installed the hook at all.
+    // Everything below is inside one fail-open boundary. Credential loading,
+    // client construction and hook handling can all throw, and a hook that exits
+    // non-zero makes the harness report a failure — strictly worse than skipping.
     try {
-        if (event === 'session-end') {
+        if (sessionEnd) {
+            // Codex gives SessionEnd one second total. Do every durable cleanup write
+            // before lifecycle diagnostics: the log lock is deliberately allowed to
+            // wait that long, and a busy log must never preserve ended-session state
+            // or its inherited configuration. The resolved config above is retained
+            // in memory so logging still uses the ending session's settings afterwards.
             const outcome = handleSessionEnd(deps.env, envelope, (deps.now ?? Date.now)());
+            start({ cwd, stop_hook_active: envelope.stop_hook_active ?? null });
+            if (config !== null)
+                logConfigResolved(logger, config);
+            const data = { hook: event, decided: false, ...outcome.log };
+            if (configFailure === undefined)
+                logger.info('hook.end', data);
+            else {
+                logger.error('hook.end', {
+                    ...data,
+                    reason: 'config-failed',
+                    config_error: failureData(configFailure),
+                });
+            }
             for (const note of outcome.notes)
                 deps.io.err(`notifai: ${note}`);
             return EXIT.ok;
         }
-        // Resolve config against the session's project rather than our own working
-        // directory. `cwd` is in the payload precisely because which project a
-        // session belongs to is the harness's business, not ours.
-        const cwd = envelope.cwd ?? deps.cwd;
-        const config = loadConfig({ cwd, env: deps.env, sessionId: envelope.session_id });
+        // Non-SessionEnd hooks cannot reach here without resolved configuration.
+        const resolved = config;
         const credential = deps.store.load();
         if (!credential) {
+            logger.error('hook.end', { hook: event, outcome: 'not-paired' });
             deps.io.err('notifai: hook skipped: this machine is not paired; run `notifai login`');
             return EXIT.ok;
         }
@@ -762,17 +1025,24 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
         // repository can commit `.notifai/config.toml`, and honouring a base_url
         // from it would hand this machine's bearer token to whatever host it names.
         const baseUrl = credential.baseUrl;
-        if (config.base_url.source !== 'default' && config.base_url.value !== baseUrl) {
-            deps.io.err(`notifai: ignoring base_url from ${config.base_url.source}; hooks only talk to ${baseUrl}`);
+        if (resolved.base_url.source !== 'default' && resolved.base_url.value !== baseUrl) {
+            deps.io.err(`notifai: ignoring base_url from ${resolved.base_url.source}; hooks only talk to ${baseUrl}`);
         }
         // UserPromptSubmit runs in front of the user's own prompt under a 15s
         // harness ceiling and can make two calls, so each gets a small slice of it;
         // 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 });
-        const now = deps.now ?? Date.now;
+        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,
+                }
+                : {}),
+        });
         const ctx = {
             client,
-            config,
+            config: resolved,
             env: deps.env,
             now,
             idleSeconds: deps.idleSeconds ?? (() => readIdleSeconds()),
@@ -790,22 +1060,38 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
                     degraded: result.degraded,
                 };
             },
+            log: logger,
             ...(harness === undefined ? {} : { harness }),
         };
         // Real clock, deliberately, not `deps.now`. This compares against file
         // mtimes, which are wall-clock facts — handing it a virtual or skewed clock
         // would have it delete live session state as "abandoned".
-        // Rate-limited to once a day by its own stamp file, so the common cost is
-        // one stat on a hook that sits on the critical path of every turn.
-        pruneAbandonedSessions(deps.env);
+        // Daily state pruning is housekeeping, not part of the Stop delivery
+        // contract. Its directory scan has no useful bound, so keep it on the
+        // short prompt path and never spend the answer owner's finite budget on it.
+        if (event !== 'stop')
+            pruneAbandonedSessions(deps.env);
         const outcome = event === 'user-prompt-submit'
             ? await handleUserPromptSubmit(ctx, envelope)
-            : await handleStop(ctx, envelope);
+            : await handleStop(ctx, envelope, processDeadlineAt);
+        // 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));
+        logger.info('hook.end', {
+            hook: event,
+            // A hook that returns stdout has taken over the turn; one that does not
+            // has handed the terminal back. That distinction is the whole contract.
+            decided: outcome.stdout !== undefined,
+            ...(notes.length === 0 ? {} : { notes }),
+            ...outcome.log,
+        });
         for (const note of outcome.notes)
             deps.io.err(`notifai: ${note}`);
         if (outcome.stdout !== undefined) {
             let stdout = outcome.stdout;
-            if (harness === 'cursor' && event === 'stop') {
+            if (harness !== undefined &&
+                event === 'stop' &&
+                HARNESS_CAPABILITIES[harness].stopContinuation === 'followup-message') {
                 const decision = JSON.parse(outcome.stdout);
                 if (decision.decision === 'block' && typeof decision.reason === 'string') {
                     stdout = JSON.stringify({ followup_message: decision.reason });
@@ -816,6 +1102,18 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
         return EXIT.ok;
     }
     catch (err) {
+        // SessionEnd defers its start record until after cleanup; if cleanup itself
+        // fails, begin the after-the-fact lifecycle here before recording why.
+        if (sessionEnd)
+            start({ cwd, stop_hook_active: envelope.stop_hook_active ?? null });
+        // The hook still exits 0 — handing the terminal back is always right. What
+        // this adds is that the reason survives, including the server's own words.
+        logger.error('hook.end', {
+            hook: event,
+            outcome: 'failed',
+            reason: 'execution-failed',
+            ...failureData(err),
+        });
         for (const line of describeHookFailure(err))
             deps.io.err(`notifai: ${line}`);
         return EXIT.ok;
@@ -945,28 +1243,36 @@ 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. With the
- * default presence gate, recent keyboard or mouse activity keeps it local;
- * `require_idle = false` intentionally permits a push while the user is active.
+ * 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.
  */
 export function askCommand(deps, question, flags) {
+    // Validate before route discovery. A malformed question belongs to the
+    // caller and should not be hidden behind whichever harness setup issue
+    // happens to exist on this machine.
+    const built = buildQuestions(flags, question);
+    if (!built.ok) {
+        deps.io.err(built.error);
+        return EXIT.usage;
+    }
+    const routingConfig = loadConfig({ cwd: deps.cwd, env: deps.env });
+    if (!routingConfig.ask_notifications.value) {
+        deps.io.err('Question routing is disabled by ask_notifications=false; enable it or use a blocking `notifai send --reply` question.');
+        return EXIT.usage;
+    }
+    if (deps.store.load() === null) {
+        deps.io.err('Question routing is not paired on this machine; run `notifai login` before registering an asynchronous question.');
+        return EXIT.usage;
+    }
     // An agent calling this gets no hook payload. Harness-native environment
-    // markers identify the active owner, while the UserPromptSubmit hook leaves
-    // a pointer keyed on the project directory with the hook's canonical id.
-    // The pointer outranks the
-    // NOTIFAI_SESSION fallback deliberately: the exported id is often a chosen
-    // label rather than the harness's own id, and the hooks key state by the
-    // latter — the env var is only trusted when no hook has spoken.
+    // 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 projectPointer = readProjectSessionPointer(deps.cwd, deps.env, now);
-    const pointer = projectPointer?.sessionId ?? null;
     const active = activeHarnessSession(deps.env);
     let sessionId;
-    if (flags.session !== undefined) {
-        sessionId = flags.session;
-    }
-    else if (active !== null) {
-        const installations = findInstallations(deps.cwd, deps.env);
+    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)) {
@@ -974,35 +1280,44 @@ export function askCommand(deps, question, flags) {
             }
             return EXIT.usage;
         }
+        if (active.sessionId === undefined) {
+            for (const problem of activeQuestionRouteProblems(deps, active, installations)) {
+                deps.io.err(`Question routing is not ready: ${problem}`);
+            }
+            return EXIT.usage;
+        }
+        const projectPointer = readMatchingProjectSessionPointer(deps.cwd, deps.env, now, active.sessionId, active.harness);
         if (projectPointer === null) {
             for (const line of diagnoseActiveHarnessSession(active, 'not-fired', installations)) {
                 deps.io.err(line);
             }
             return EXIT.usage;
         }
-        if (projectPointer.harness !== active.harness ||
-            (active.sessionId !== undefined && projectPointer.sessionId !== active.sessionId)) {
-            for (const line of diagnoseActiveHarnessSession(active, 'different-session', installations)) {
-                deps.io.err(line);
-            }
+        if (flags.session !== undefined && flags.session !== active.sessionId) {
+            deps.io.err(`Question routing is not ready: --session ${flags.session} does not match the exact active ${active.label} session ${active.sessionId}; refusing cross-session routing.`);
+            return EXIT.usage;
+        }
+        const routeProblems = activeQuestionRouteProblems(deps, active, installations);
+        if (routeProblems.length > 0) {
+            for (const problem of routeProblems)
+                deps.io.err(`Question routing is not ready: ${problem}`);
+            return EXIT.usage;
+        }
+        if (readSessionState(projectPointer.sessionId, deps.env).last_stop_at === undefined) {
+            deps.io.err(`Question routing is not ready: this ${active.label} session has fired UserPromptSubmit, but its Stop hook has not been observed. End one harmless turn, send a new prompt, then run \`notifai doctor\`.`);
             return EXIT.usage;
         }
         sessionId = projectPointer.sessionId;
     }
     else {
-        sessionId = pointer ?? deps.env['NOTIFAI_SESSION'] ?? undefined;
-    }
-    if (!sessionId) {
         for (const line of diagnoseMissingSession(deps))
             deps.io.err(line);
+        deps.io.err('Could not prove which live harness session owns this command, so Notifai will not register a question that could be delivered to the wrong or already-ended agent. Run it from a supported harness with exact session identity, or use a blocking `notifai send --reply` question.');
         return EXIT.usage;
     }
-    // Validate here, not at push time. The push happens inside a hook, where a
-    // rejection becomes a stderr note the agent never reads — so a malformed
-    // question set would look like it registered fine and then silently never ask.
-    const built = buildQuestions(flags, question);
-    if (!built.ok) {
-        deps.io.err(built.error);
+    if (!sessionId) {
+        for (const line of diagnoseMissingSession(deps))
+            deps.io.err(line);
         return EXIT.usage;
     }
     try {
@@ -1013,9 +1328,20 @@ export function askCommand(deps, question, flags) {
         }, (deps.now ?? Date.now)());
     }
     catch (err) {
+        log(deps).error('ask.registered', { ok: false, session: sessionId, message: String(err) });
         deps.io.err(`Could not register the question: ${err instanceof Error ? err.message : String(err)}`);
         return EXIT.failed;
     }
+    // `ask` returns immediately and the push happens later inside a hook, so this
+    // is the only local evidence that the question was ever registered — the
+    // starting point for "the agent asked, and nothing ever reached my phone".
+    log(deps).info('ask.registered', {
+        ok: true,
+        session: sessionId,
+        questions: built.questions.length,
+        text: built.questions[0].text,
+        choices: built.questions[0].choices?.length ?? 0,
+    });
     for (const [index, entry] of built.questions.entries()) {
         const prefix = built.questions.length > 1 ? `${index + 1}. ` : '';
         if (entry.choices !== undefined) {
@@ -1057,6 +1383,52 @@ function activeHarnessSession(env) {
         return { harness: 'cursor', label: 'Cursor' };
     return null;
 }
+/**
+ * One fail-closed admission gate shared by every active harness route.
+ * Finding a file is not readiness: the exact session, one current definition,
+ * the stable adapter, a long enough Stop owner, and (for Codex) trust must all
+ * be true before `ask` is allowed to create an answerable notification.
+ */
+function activeQuestionRouteProblems(deps, active, installations) {
+    const problems = [];
+    if (active.sessionId === undefined) {
+        problems.push(`the active ${active.label} shell does not expose an exact session id; a project-level last-writer pointer can cross-wire two sessions. Use a blocking \`notifai send --reply\` question`);
+    }
+    const capability = HARNESS_CAPABILITIES[active.harness];
+    if (capability.stopContinuation === 'unsupported') {
+        problems.push(`${active.label}: ${capability.deliveryContract}`);
+    }
+    const matching = installations.filter((installation) => installation.harness === active.harness);
+    if (matching.length > 1) {
+        problems.push(`${matching.length} ${active.label} definitions are active (${matching.map((entry) => entry.file).join(', ')}); keep either project or global routing`);
+    }
+    for (const installation of matching) {
+        for (const problem of installation.problems ?? []) {
+            problems.push(`${installation.file}: ${problem}`);
+        }
+        for (const handler of installation.handlers) {
+            const event = handlerEvent(handler.command);
+            if (event !== null && !HOOK_EVENTS.includes(event)) {
+                problems.push(`${handler.event} in ${installation.file} names the unsupported event ${event}; reinstall the ${active.label} hooks`);
+            }
+        }
+    }
+    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`);
+                }
+            }
+        }
+    }
+    problems.push(...codexTrustProblems(matching, deps.env));
+    return [...new Set(problems)];
+}
 function diagnoseActiveHarnessSession(active, problem, installations) {
     if (problem === 'not-installed') {
         const others = installations.map((installation) => installation.harness);
@@ -1094,7 +1466,7 @@ function diagnoseActiveHarnessSession(active, problem, installations) {
  * checked after a prompt before assuming that a new session is required.
  */
 function diagnoseMissingSession(deps) {
-    const installations = findInstallations(deps.cwd, deps.env);
+    const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome);
     if (installations.length === 0) {
         return [
             'Could not tell which harness session this is: no Notifai hooks are installed for this project.',
@@ -1106,7 +1478,7 @@ function diagnoseMissingSession(deps) {
         `Could not tell which harness session this is. Notifai hooks are installed (${where}),`,
         'but no usable session pointer from the last 24 hours exists here.',
         hookActivationAdvice(installations),
-        'To ask from this session anyway, pass --session <id>.',
+        'Do not bypass this with a guessed session id; run from the exact active harness session or use a blocking `notifai send --reply` question.',
     ];
 }
 /** The least disruptive verified way to make each installed adapter run once. */
@@ -1129,13 +1501,13 @@ function hookActivationAdvice(installations) {
         advice.push('Codex: send one prompt, then run `notifai doctor`; start a new session only if it still has not fired');
     }
     if (harnesses.has('opencode')) {
-        advice.push('OpenCode: restart it, then send one prompt; plugins load at startup, and a device answer is delivered on the next prompt');
+        advice.push('OpenCode: restart it, then send one prompt; plugins load at startup, but non-blocking question continuation is intentionally unsupported');
     }
     return `${advice.join('. ')}.`;
 }
 /** Retire a question so a late answer is rejected rather than silently lost. */
 export async function closeCommand(deps, requestId) {
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     const authed = authedClient(deps, config);
     if (!authed)
         return EXIT.auth;
@@ -1154,35 +1526,36 @@ export function hooksInstallCommand(deps, flags) {
         return EXIT.usage;
     const execPath = flags.execPath ?? process.execPath;
     const scriptPath = flags.scriptPath ?? process.argv[1] ?? 'notifai';
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    let adapterPath;
+    try {
+        adapterPath = installHookAdapter({ execPath, scriptPath }, 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, {
-            execPath,
-            scriptPath,
-            timeoutSeconds: blockingHookTimeoutSeconds(config.ask_grace_seconds.value, config.hook_reply_timeout_seconds.value),
+            adapterPath,
+            timeoutSeconds: blockingHookTimeoutSeconds(),
         });
     }
     if (harness === 'cursor') {
-        let document;
+        let merged;
         try {
-            document = loadCursorSettings(file);
-        }
-        catch (err) {
-            deps.io.err(String(err));
-            return EXIT.failed;
-        }
-        const merged = mergeCursorHooks(document, buildCursorHookConfig({
-            execPath,
-            scriptPath,
-            replyTimeoutSeconds: config.hook_reply_timeout_seconds.value,
-            graceSeconds: config.ask_grace_seconds.value,
-            harness: 'cursor',
-        }), scriptPath);
-        try {
-            applyPlan(file, merged.document);
+            merged = withTargetFileLock(file, () => {
+                const document = loadCursorSettings(file);
+                const result = mergeCursorHooks(document, buildCursorHookConfig({
+                    adapterPath,
+                    harness: 'cursor',
+                }), scriptPath);
+                applyPlan(file, result.document);
+                return result;
+            });
         }
         catch (err) {
             deps.io.err(String(err));
@@ -1201,27 +1574,22 @@ export function hooksInstallCommand(deps, flags) {
             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('A companion-device answer is submitted as one follow-up user message.');
-        deps.io.out('loop_limit = 3 permits bounded chained questions without an unbounded loop.');
+        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.');
         return EXIT.ok;
     }
-    let document;
+    let merged;
     try {
-        document = loadSettings(file);
-    }
-    catch (err) {
-        deps.io.err(String(err));
-        return EXIT.failed;
-    }
-    const merged = mergeHooks(document, buildHookConfig({
-        execPath,
-        scriptPath,
-        replyTimeoutSeconds: config.hook_reply_timeout_seconds.value,
-        graceSeconds: config.ask_grace_seconds.value,
-        harness,
-    }), scriptPath);
-    try {
-        applyPlan(file, merged.document);
+        merged = withTargetFileLock(file, () => {
+            const document = loadSettings(file);
+            const result = mergeHooks(document, buildHookConfig({
+                adapterPath,
+                harness,
+            }), scriptPath);
+            applyPlan(file, result.document);
+            return result;
+        });
     }
     catch (err) {
         deps.io.err(String(err));
@@ -1236,16 +1604,19 @@ export function hooksInstallCommand(deps, flags) {
         deps.io.out(`  removed: ${merged.removed.join(', ')} (this build no longer serves them)`);
     }
     deps.io.out('');
-    deps.io.out(config.require_idle.value
-        ? `While keyboard or mouse idle time stays below ${config.away_after_seconds.value}s, ` +
-            `nothing is pushed. A question registered with \`notifai ask\` stays in the terminal ` +
-            `until its ${config.ask_grace_seconds.value}s grace window, counted from registration, ` +
-            `has elapsed; it goes to your devices only while the machine also meets the idle threshold. ` +
-            `Run \`notifai config set require_idle false\` to be notified even while you are working.`
-        : `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 ` +
-            `(\`notifai config set require_idle false\` is already in effect).`);
+    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.');
     }
@@ -1286,16 +1657,21 @@ export function hooksInstallCommand(deps, flags) {
  * the same reason command hooks are.
  */
 function installOpencodePlugin(deps, file, options) {
-    if (existsSync(file)) {
-        const existing = readFileSync(file, 'utf8');
-        if (!isOurOpencodePlugin(existing)) {
-            deps.io.err(`${file} exists and was not written by Notifai; move it aside first.`);
-            return EXIT.failed;
-        }
-    }
     try {
-        mkdirSync(path.dirname(file), { recursive: true });
-        writeFileSync(file, opencodePluginSource(options), { mode: 0o644 });
+        withTargetFileLock(file, () => {
+            if (existsSync(file)) {
+                assertOwnedRegularFile(file);
+                const existing = readFileSync(file, 'utf8');
+                if (!isOurOpencodePlugin(existing)) {
+                    throw new Error(`${file} exists and was not written by Notifai; move it aside first.`);
+                }
+            }
+            atomicWriteFileSync(file, opencodePluginSource(options), {
+                mode: 0o600,
+                preserveMode: false,
+                requireCurrentUserOwner: true,
+            });
+        });
     }
     catch (err) {
         deps.io.err(String(err));
@@ -1306,9 +1682,9 @@ function installOpencodePlugin(deps, file, options) {
     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 pushes without holding its idle event open; the next user prompt');
-    deps.io.out('collects a device answer and adds it to the agent context. Use `notifai');
-    deps.io.out('send --reply` only when the answer must return before another prompt.');
+    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.');
     return EXIT.ok;
@@ -1319,63 +1695,88 @@ export function hooksUninstallCommand(deps, flags) {
         return EXIT.usage;
     const scriptPath = flags.scriptPath ?? process.argv[1] ?? 'notifai';
     const file = settingsFile(harness, flags.global ?? false, deps.cwd, deps.env);
-    if (!existsSync(file)) {
-        deps.io.out(`Nothing to remove: ${file} does not exist.`);
-        return EXIT.ok;
-    }
     if (harness === 'opencode') {
-        // We own the whole file, but only if we wrote it.
-        if (!isOurOpencodePlugin(readFileSync(file, 'utf8'))) {
-            deps.io.out(`Left ${file} alone: Notifai did not write it.`);
-            return EXIT.ok;
-        }
-        rmSync(file, { force: true });
-        deps.io.out(`Removed the Notifai OpenCode plugin at ${file}`);
-        return EXIT.ok;
-    }
-    if (harness === 'cursor') {
-        let document;
         try {
-            document = loadCursorSettings(file);
+            return withTargetFileLock(file, () => {
+                if (!existsSync(file)) {
+                    deps.io.out(`Nothing to remove: ${file} does not exist.`);
+                    return EXIT.ok;
+                }
+                assertOwnedRegularFile(file);
+                // We own the whole file, but only if we wrote it.
+                if (!isOurOpencodePlugin(readFileSync(file, 'utf8'))) {
+                    deps.io.out(`Left ${file} alone: Notifai did not write it.`);
+                    return EXIT.ok;
+                }
+                rmSync(file, { force: true });
+                deps.io.out(`Removed the Notifai OpenCode plugin at ${file}`);
+                return EXIT.ok;
+            });
         }
         catch (err) {
             deps.io.err(String(err));
             return EXIT.failed;
         }
-        const stripped = removeCursorHooks(document, scriptPath);
+    }
+    if (harness === 'cursor') {
+        let stripped;
         try {
-            applyPlan(file, stripped.document);
+            stripped = withTargetFileLock(file, () => {
+                if (!existsSync(file))
+                    return null;
+                const document = loadCursorSettings(file);
+                const result = removeCursorHooks(document, scriptPath);
+                applyPlan(file, result.document);
+                return result;
+            });
         }
         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;
+        }
         deps.io.out(stripped.replaced.length > 0
             ? `Removed Notifai hooks (${stripped.replaced.join(', ')}) from ${file}`
             : `No Notifai hooks found in ${file}`);
         return EXIT.ok;
     }
-    let document;
+    let stripped;
     try {
-        document = loadSettings(file);
+        stripped = withTargetFileLock(file, () => {
+            if (!existsSync(file))
+                return null;
+            const document = loadSettings(file);
+            const result = removeHooks(document, scriptPath);
+            applyPlan(file, result.document);
+            return result;
+        });
     }
     catch (err) {
         deps.io.err(String(err));
         return EXIT.failed;
     }
-    const stripped = removeHooks(document, scriptPath);
-    try {
-        applyPlan(file, stripped.document);
-    }
-    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;
     }
     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) {
+    const stat = lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error(`${file} is not a regular file; refusing to read or replace it.`);
+    }
+    const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+    if (uid !== undefined && stat.uid !== uid) {
+        throw new Error(`${file} is owned by uid ${stat.uid}, not the current user.`);
+    }
+}
 function resolveHarness(deps, requested) {
     if (requested !== undefined) {
         if (HARNESSES.includes(requested))
@@ -1391,50 +1792,175 @@ function resolveHarness(deps, requested) {
     return detected;
 }
 // ---------------------------------------------------------------------------
-// config show / set
+// config show / set / unset
 // ---------------------------------------------------------------------------
 export function configShowCommand(deps, flags) {
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    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 }]));
         deps.io.out(JSON.stringify(output, null, 2));
         return EXIT.ok;
     }
-    for (const key of CONFIG_KEYS) {
-        const entry = config[key];
-        const provenance = flags.explain ? `  [${entry.source}]` : '';
-        deps.io.out(`${key} = ${JSON.stringify(entry.value)}${provenance}`);
+    // Anything that is not a person at a terminal keeps the flat `key = value`
+    // form it has always had. Scripts parse this, and a prettier layout for an
+    // audience that cannot see it would only be a breaking change.
+    if (deps.io.interactive !== true || flags.plain === true) {
+        for (const line of renderConfigPlain(config, flags.explain === true))
+            deps.io.out(line);
+        return EXIT.ok;
+    }
+    for (const line of renderConfigList(config, { showAdvanced: flags.explain === true })) {
+        deps.io.out(line);
     }
     return EXIT.ok;
 }
-export async function configSetCommand(deps, key, rawValue, flags) {
+/**
+ * One setting, explained in full.
+ *
+ * The gap this closes: `config show` prints a value and provenance but that is
+ * not enough to explain the setting's consequences. Every key already had a
+ * careful explanation — in a TypeScript comment, read by everyone except the
+ * person who needed it.
+ */
+export function configExplainCommand(deps, key, flags = {}) {
     if (!CONFIG_KEYS.includes(key)) {
-        deps.io.err(`Unknown key "${key}". Valid keys: ${CONFIG_KEYS.join(', ')}`);
+        deps.io.err(`Unknown setting "${key}".`);
+        deps.io.err(`Valid settings: ${CONFIG_KEYS.join(', ')}`);
         return EXIT.usage;
     }
+    const configKey = key;
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
+    const info = configInfo(configKey);
+    const entry = config[configKey];
+    if (flags.json) {
+        deps.io.out(JSON.stringify({
+            key: configKey,
+            label: info.label,
+            group: info.group,
+            kind: info.kind,
+            summary: info.summary,
+            detail: info.detail,
+            accepts: acceptedValues(configKey),
+            ...(info.choices !== undefined ? { choices: info.choices } : {}),
+            value: entry.value,
+            source: entry.source,
+        }, null, 2));
+        return EXIT.ok;
+    }
+    if (deps.io.interactive !== true) {
+        deps.io.out(`${configKey} = ${JSON.stringify(entry.value)}  [${entry.source}]`);
+        deps.io.out(info.detail.replace(/\n\n/g, '\n'));
+        deps.io.out(`accepts: ${acceptedValues(configKey)}`);
+        return EXIT.ok;
+    }
+    for (const line of renderConfigExplain(configKey, config))
+        deps.io.out(line);
+    return EXIT.ok;
+}
+/**
+ * Closest config key by edit distance, or null when nothing is close.
+ *
+ * The threshold matters more than the algorithm: suggesting a key that shares
+ * three letters with the typo sends the reader to the wrong setting with
+ * confidence, which is worse than listing all fourteen and letting them look.
+ */
+function nearestKey(input) {
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of CONFIG_KEYS) {
+        const distance = editDistance(input.toLowerCase(), candidate);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    return best !== null && bestDistance <= Math.max(2, Math.floor(best.length / 3)) ? best : null;
+}
+function editDistance(a, b) {
+    const previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        let diagonal = previous[0];
+        previous[0] = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const above = previous[j];
+            previous[j] = Math.min(previous[j] + 1, previous[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return previous[b.length];
+}
+export async function configSetCommand(deps, key, rawValue, flags) {
+    const configKey = configMutationKey(deps, key);
+    if (configKey === null)
+        return EXIT.usage;
+    const info = configInfo(configKey);
     let value = rawValue;
-    if (NUMERIC_CONFIG_KEYS.includes(key)) {
+    if (NUMERIC_CONFIG_KEYS.includes(configKey)) {
         const numeric = Number(rawValue);
         if (!Number.isInteger(numeric)) {
-            deps.io.err(`"${rawValue}" is not an integer.`);
+            deps.io.err(`${key} takes ${acceptedValues(configKey)}, not "${rawValue}".`);
             return EXIT.usage;
         }
-        const bounds = configBounds(key);
+        const bounds = configBounds(configKey);
         if (bounds !== undefined && (numeric < bounds.min || numeric > bounds.max)) {
             deps.io.err(`${key} must be between ${bounds.min} and ${bounds.max}.`);
             return EXIT.usage;
         }
         value = numeric;
     }
-    if (BOOLEAN_CONFIG_KEYS.includes(key)) {
+    if (BOOLEAN_CONFIG_KEYS.includes(configKey)) {
         if (rawValue !== 'true' && rawValue !== 'false') {
             deps.io.err(`${key} is a toggle — pass "true" or "false", not "${rawValue}".`);
             return EXIT.usage;
         }
         value = rawValue === 'true';
     }
+    // Enum keys were accepted unchecked, so `config set sound whatever` wrote a
+    // value the sender would later reject — a typo that only surfaces at the
+    // moment a notification fails to carry the sound you asked for.
+    if (info.kind === 'enum' && info.choices !== undefined && !info.choices.includes(rawValue)) {
+        deps.io.err(`${key} takes one of: ${info.choices.join(', ')} — not "${rawValue}".`);
+        return EXIT.usage;
+    }
     if (key === 'devices')
         value = rawValue.split(',').map((s) => s.trim()).filter(Boolean);
+    const target = await configMutationTarget(deps, flags);
+    if (target === null)
+        return EXIT.usage;
+    if (target.layer === 'global' && Object.is(value, configDefaultValue(configKey))) {
+        deps.io.err(`${key} is already the shipped default (${JSON.stringify(value)}).`);
+        deps.io.err(`Run \`notifai config unset ${key} --yes\` to remove a redundant override instead of creating one.`);
+        return EXIT.usage;
+    }
+    if (!flags.yes) {
+        const confirmed = await deps.io.confirm(`Set ${key} = ${JSON.stringify(value)} in ${target.path}?`);
+        if (!confirmed) {
+            deps.io.err('Not confirmed. Pass --yes to skip the confirmation gate.');
+            return EXIT.usage;
+        }
+    }
+    const existing = existsSync(target.path)
+        ? parseToml(readFileSync(target.path, 'utf8'))
+        : {};
+    existing[key] = value;
+    mkdirSync(path.dirname(target.path), { recursive: true });
+    writeFileSync(target.path, `${stringifyToml(existing)}\n`);
+    deps.io.out(`Wrote ${key} to ${target.path}`);
+    return EXIT.ok;
+}
+function configMutationKey(deps, key) {
+    if (!CONFIG_KEYS.includes(key)) {
+        deps.io.err(`Unknown setting "${key}".`);
+        const near = nearestKey(key);
+        if (near !== null)
+            deps.io.err(`Did you mean "${near}"?`);
+        deps.io.err(`Valid settings: ${CONFIG_KEYS.join(', ')}`);
+        deps.io.err('Run `notifai config explain <key>` to see what one of them does.');
+        return null;
+    }
+    return key;
+}
+async function configMutationTarget(deps, flags) {
     let layer = flags.local ? 'local' : flags.project ? 'project' : 'global';
     if (flags.session === undefined &&
         flags.local !== true &&
@@ -1449,7 +1975,7 @@ export async function configSetCommand(deps, key, rawValue, flags) {
         ]);
         if (selected === null) {
             deps.io.err('No configuration layer selected.');
-            return EXIT.usage;
+            return null;
         }
         layer = selected;
     }
@@ -1460,20 +1986,236 @@ export async function configSetCommand(deps, key, rawValue, flags) {
             : layer === 'project'
                 ? (findProjectConfigPath(deps.cwd) ?? path.join(deps.cwd, '.notifai', 'config.toml'))
                 : globalConfigPath(deps.env);
+    return {
+        path: targetPath,
+        layer: flags.session ? 'session' : layer,
+    };
+}
+export async function configUnsetCommand(deps, key, flags) {
+    const configKey = configMutationKey(deps, key);
+    if (configKey === null)
+        return EXIT.usage;
+    const target = await configMutationTarget(deps, flags);
+    if (target === null)
+        return EXIT.usage;
+    const existing = existsSync(target.path)
+        ? parseToml(readFileSync(target.path, 'utf8'))
+        : {};
+    if (!Object.prototype.hasOwnProperty.call(existing, configKey)) {
+        deps.io.out(`${configKey} is not set in ${target.path}`);
+        return EXIT.ok;
+    }
     if (!flags.yes) {
-        const confirmed = await deps.io.confirm(`Set ${key} = ${JSON.stringify(value)} in ${targetPath}?`);
+        const confirmed = await deps.io.confirm(`Remove ${configKey} from ${target.path}?`);
         if (!confirmed) {
             deps.io.err('Not confirmed. Pass --yes to skip the confirmation gate.');
             return EXIT.usage;
         }
     }
-    const existing = existsSync(targetPath)
-        ? parseToml(readFileSync(targetPath, 'utf8'))
-        : {};
-    existing[key] = value;
-    mkdirSync(path.dirname(targetPath), { recursive: true });
-    writeFileSync(targetPath, `${stringifyToml(existing)}\n`);
-    deps.io.out(`Wrote ${key} to ${targetPath}`);
+    delete existing[configKey];
+    if (Object.keys(existing).length === 0) {
+        rmSync(target.path, { force: true });
+    }
+    else {
+        writeFileSync(target.path, `${stringifyToml(existing)}\n`);
+    }
+    deps.io.out(`Removed ${configKey} from ${target.path}; the inherited value now applies.`);
+    return EXIT.ok;
+}
+const LOG_RECORD_OPTIONS = [
+    ['limit', '--limit'],
+    ['all', '--all'],
+    ['since', '--since'],
+    ['level', '--level'],
+    ['event', '--event'],
+    ['run', '--run'],
+    ['request', '--request'],
+    ['session', '--session'],
+    ['project', '--project'],
+    ['allProjects', '--all-projects'],
+    ['grep', '--grep'],
+];
+/**
+ * Deliberately small. The reader is usually a model with a finite context, and
+ * a log command whose default answer is ten thousand lines gets used once.
+ * Everything beyond this is reachable by asking for it.
+ */
+const DEFAULT_LOG_LIMIT = 30;
+/** Even `--all` stops somewhere; an unbounded dump is never the useful answer. */
+const MAX_LOG_LIMIT = 2_000;
+/** `10m`, `2h`, `1d`, or an ISO 8601 instant. */
+export function parseSince(raw, now) {
+    const relative = /^(\d+)([smhd])$/.exec(raw.trim());
+    if (relative !== null) {
+        const amount = Number(relative[1]);
+        const unit = relative[2];
+        const seconds = { s: 1, m: 60, h: 3600, d: 86400 }[unit];
+        return now - amount * seconds * 1000;
+    }
+    const absolute = Date.parse(raw);
+    return Number.isNaN(absolute) ? null : absolute;
+}
+/**
+ * What this machine recorded about itself.
+ *
+ * The retrieval half of the local log, and the half that decides whether the
+ * log is worth having. Three things make it usable by an agent rather than
+ * merely available to one: the default is bounded and scoped to this project,
+ * the filters match the questions actually asked ("that run", "that
+ * notification", "just the failures"), and `--json` gives the machine the
+ * records untouched on stdout while every word of explanation goes to stderr.
+ */
+export function logsCommand(deps, flags) {
+    const selectedRetrievalOptions = LOG_RECORD_OPTIONS
+        .filter(([key]) => {
+        const value = flags[key];
+        return Array.isArray(value) ? value.length > 0 : value !== undefined && value !== false;
+    })
+        .map(([, name]) => name);
+    if (flags.path === true && flags.clear === true) {
+        deps.io.err('Pass --path or --clear, not both.');
+        return EXIT.usage;
+    }
+    if (flags.path === true && selectedRetrievalOptions.length > 0) {
+        deps.io.err(`--path cannot be combined with record options: ${selectedRetrievalOptions.join(', ')}.`);
+        return EXIT.usage;
+    }
+    if (flags.clear === true && selectedRetrievalOptions.length > 0) {
+        deps.io.err(`--clear cannot be combined with record options: ${selectedRetrievalOptions.join(', ')}.`);
+        return EXIT.usage;
+    }
+    if (flags.project !== undefined && flags.allProjects === true) {
+        deps.io.err('Pass --project or --all-projects, not both.');
+        return EXIT.usage;
+    }
+    if (flags.limit !== undefined && flags.all === true) {
+        deps.io.err('Pass --limit or --all, not both.');
+        return EXIT.usage;
+    }
+    if (flags.limit !== undefined && (!Number.isInteger(flags.limit) || flags.limit <= 0)) {
+        deps.io.err('--limit must be a positive integer.');
+        return EXIT.usage;
+    }
+    if (flags.limit !== undefined && flags.limit > MAX_LOG_LIMIT) {
+        deps.io.err(`--limit cannot exceed ${MAX_LOG_LIMIT}; narrow the result with --since or filters.`);
+        return EXIT.usage;
+    }
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
+    const now = (deps.now ?? Date.now)();
+    if (flags.path === true) {
+        const usage = logsDiskUsage(deps.env);
+        const archives = archiveLogPaths(deps.env);
+        if (flags.json === true) {
+            deps.io.out(JSON.stringify({
+                active: activeLogPath(deps.env),
+                archives,
+                files: usage.files,
+                bytes: usage.bytes,
+                level: config.log_level.value,
+                max_bytes: config.log_max_bytes.value,
+                max_files: config.log_max_files.value,
+                local_only: true,
+            }, null, 2));
+            return EXIT.ok;
+        }
+        deps.io.out(activeLogPath(deps.env));
+        for (const archive of archives)
+            deps.io.out(archive);
+        deps.io.err(`${usage.files} file(s), ${Math.round(usage.bytes / 1024)} KB, level ${config.log_level.value}. These stay on this machine.`);
+        return EXIT.ok;
+    }
+    if (flags.clear === true) {
+        let removed = 0;
+        for (const file of [activeLogPath(deps.env), ...archiveLogPaths(deps.env)]) {
+            try {
+                unlinkSync(file);
+                removed += 1;
+            }
+            catch {
+                // Absent, or not ours to remove; either way there is nothing to report.
+            }
+        }
+        deps.io.out(flags.json === true
+            ? JSON.stringify({ cleared_files: removed })
+            : `Cleared ${removed} log file${removed === 1 ? '' : 's'}.`);
+        return EXIT.ok;
+    }
+    const query = {
+        limit: flags.limit ?? (flags.all === true ? MAX_LOG_LIMIT : DEFAULT_LOG_LIMIT),
+    };
+    if (flags.since !== undefined) {
+        const since = parseSince(flags.since, now);
+        if (since === null) {
+            deps.io.err(`Could not read "${flags.since}" as a time. Use 10m, 2h, 1d, or an ISO 8601 instant.`);
+            return EXIT.usage;
+        }
+        query.since = since;
+    }
+    if (flags.level !== undefined) {
+        if (!LOG_LEVELS.includes(flags.level)) {
+            deps.io.err(`--level takes one of: ${LOG_LEVELS.join(', ')} — not "${flags.level}".`);
+            return EXIT.usage;
+        }
+        query.level = flags.level;
+    }
+    if (flags.event !== undefined && flags.event.length > 0) {
+        const unknown = flags.event.filter((name) => !LOG_EVENTS.includes(name));
+        if (unknown.length > 0) {
+            deps.io.err(`Unknown event ${unknown.join(', ')}. Valid: ${LOG_EVENTS.join(', ')}`);
+            return EXIT.usage;
+        }
+        query.event = flags.event;
+    }
+    if (flags.run !== undefined)
+        query.run = flags.run;
+    if (flags.session !== undefined)
+        query.session = flags.session;
+    if (flags.request !== undefined)
+        query.request = flags.request;
+    if (flags.grep !== undefined)
+        query.contains = flags.grep;
+    // Scoped to this project by default. A machine commonly runs several agents
+    // in several worktrees at once, and the answer to "what just happened" is
+    // useless if three other projects are interleaved through it.
+    const scope = flags.project ?? (flags.allProjects === true ? undefined : (config.project.value ?? undefined));
+    if (scope !== undefined)
+        query.project = scope;
+    const result = readLogRecords(deps.env, query);
+    if (flags.json === true) {
+        for (const record of result.records)
+            deps.io.out(JSON.stringify(record));
+    }
+    else {
+        for (const record of result.records)
+            deps.io.out(renderRecord(record));
+    }
+    if (result.records.length === 0) {
+        if (config.log_level.value === 'off') {
+            deps.io.err('Nothing is being recorded: log_level is off.');
+            deps.io.err('Turn it on with `notifai config set log_level info --yes`.');
+        }
+        else if (logsDiskUsage(deps.env).files === 0) {
+            deps.io.err('No log yet. It is written the next time a notifai command or harness hook runs.');
+        }
+        else {
+            deps.io.err('No records matched. Widen it with --all-projects, --since 1d, or --all.');
+        }
+        return EXIT.ok;
+    }
+    // Everything explanatory goes to stderr so `--json` leaves stdout as clean
+    // JSONL for whatever is parsing it.
+    const notes = [];
+    if (scope !== undefined)
+        notes.push(`project ${scope} (--all-projects for every project)`);
+    if (result.more) {
+        notes.push(query.limit < MAX_LOG_LIMIT
+            ? `more history behind this (-n ${Math.min(query.limit * 4, MAX_LOG_LIMIT)} or --all)`
+            : `more history exists beyond the ${MAX_LOG_LIMIT}-record safety cap; narrow with --since or filters`);
+    }
+    if (config.log_level.value !== 'debug')
+        notes.push('`log_level = debug` records request detail');
+    if (notes.length > 0)
+        deps.io.err(`— ${result.records.length} records; ${notes.join('; ')}`);
     return EXIT.ok;
 }
 // ---------------------------------------------------------------------------
@@ -1484,7 +2226,7 @@ export async function configSetCommand(deps, key, rawValue, flags) {
  * 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.
  */
-export const SKILLS_SOURCE = 'Raidiant-io/notifai#v0.2.1';
+export const SKILLS_SOURCE = 'Raidiant-io/notifai#v0.4.0';
 function skillSourceParts() {
     const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE);
     return match === null ? null : { source: match[1], ref: match[2] };
@@ -1709,7 +2451,7 @@ async function waitForReadyDevice(deps, state) {
     const remedy = state.remedy;
     if (deps.io.interactive !== true || remedy?.by !== 'user-elsewhere')
         return 'pending';
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     const authed = authedClient(deps, config);
     if (!authed) {
         deps.io.err('Could not start the companion-device wait: this machine is not signed in.');
@@ -1827,7 +2569,7 @@ async function submitSetupProof(deps, client, config, device) {
  * the push, not that a companion process received it.
  */
 async function runSetupProof(deps) {
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     const authed = authedClient(deps, config);
     if (!authed)
         return 'failed';
@@ -2160,7 +2902,7 @@ async function contractCheck(client) {
  * looking like a broken install.
  */
 export async function assessReadiness(deps, options = {}) {
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     const states = [];
     let accountClient = null;
     let accountDevices = null;
@@ -2449,8 +3191,13 @@ export async function doctorCommand(deps, flags) {
     // costs nothing.
     if (deps.io.interactive === true && deps.io.check) {
         await deps.io.intro?.('Notifai doctor');
-        for (const s of readiness.states)
-            await deps.io.check(s.status !== 'gap', line(s));
+        for (const s of readiness.states) {
+            // Four states, not two. Rendering `optional-gap` and `unknown` as
+            // successes made a green report that had never checked half of what it
+            // listed, and put a tick beside things the reader had deliberately
+            // declined.
+            await deps.io.check(s.status !== 'gap', line(s), doctorTone(s.status));
+        }
         await deps.io.outro?.(ok ? 'Everything looks good' : `Start with: ${remedyLine(blocker)}`);
     }
     else {
@@ -2469,6 +3216,19 @@ export async function doctorCommand(deps, flags) {
     }
     return ok ? EXIT.ok : EXIT.failed;
 }
+/** Readiness status as a report tone. */
+function doctorTone(status) {
+    switch (status) {
+        case 'ready':
+            return 'ok';
+        case 'gap':
+            return 'bad';
+        case 'optional-gap':
+            return 'warn';
+        case 'unknown':
+            return 'pending';
+    }
+}
 /** One line telling the reader what to actually do about a state. */
 function remedyLine(state) {
     const remedy = state.remedy;
@@ -2498,23 +3258,21 @@ function remedyLine(state) {
  *
  * Not everything failed is in the way. A pointer that has never been
  * published is the normal condition of an install thirty seconds old — the
- * next prompt fixes it and no command can — and OpenCode's inability to
- * resume an idle turn is a property of that harness rather than a fault in
- * this setup. Treating those as blocking would mean `init` could never
- * finish for an OpenCode user, or could only finish after a session had
- * already run — so they report as things worth knowing rather than things to
+ * next prompt fixes it and no command can. Treating that as blocking would
+ * mean `init` could only finish after a session had already run — so it
+ * reports as something worth knowing rather than something to
  * fix, and `init` walks on to the states it can actually close, delivery
  * proof included. Which failures are informational, and what the true remedy
  * is, is each check's own call (`HookCheck`).
  */
 function hookStates(deps) {
-    const installations = findInstallations(deps.cwd, deps.env);
+    const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome);
     const active = activeHarnessSession(deps.env);
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     const settings = {
         id: 'question-routing-settings',
         title: 'Question routing settings',
-        status: 'ready',
+        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})`,
@@ -2522,6 +3280,15 @@ function hookStates(deps) {
             `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
+            ? {}
+            : {
+                remedy: {
+                    by: 'cli',
+                    summary: 'enable asynchronous question routing',
+                    command: 'notifai config set ask_notifications true',
+                },
+            }),
     };
     if (installations.length === 0) {
         return [
@@ -2544,7 +3311,7 @@ function hookStates(deps) {
         ];
     }
     /** Real but not in the way; see the note above. */
-    const informational = new Set(['hooks (opencode continuation)']);
+    const informational = new Set();
     return [
         ...hookChecks(deps).map((check) => ({
             id: check.name.replace(/[ ()]+/g, '-').replace(/-$/, ''),
@@ -2577,7 +3344,7 @@ function hookStates(deps) {
 }
 function hookChecks(deps) {
     const checks = [];
-    const installations = findInstallations(deps.cwd, deps.env);
+    const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome);
     // Not having hooks is a setup someone chose, not a fault: `send` works
     // without them. A setup that cannot work is what deserves to go red.
     if (installations.length === 0) {
@@ -2616,7 +3383,9 @@ function hookChecks(deps) {
                 }),
         });
         if (activeInstallations.length > 0) {
-            const pointer = readProjectSessionPointer(deps.cwd, deps.env, (deps.now ?? Date.now)());
+            const pointer = active.sessionId === undefined
+                ? null
+                : readMatchingProjectSessionPointer(deps.cwd, deps.env, (deps.now ?? Date.now)(), active.sessionId, active.harness);
             if (pointer === null) {
                 // The normal condition of hooks installed moments ago: the pointer
                 // appears when the harness next fires a hook, and no command can
@@ -2634,22 +3403,10 @@ function hookChecks(deps) {
                 });
             }
             else {
-                const matches = pointer.harness === active.harness &&
-                    (active.sessionId === undefined || pointer.sessionId === active.sessionId);
                 checks.push({
                     name: 'hooks (active session)',
-                    ok: matches,
-                    detail: matches
-                        ? `the project pointer belongs to the active ${active.label} session`
-                        : `the project pointer belongs to another ${active.label} session or harness; refusing cross-session routing`,
-                    ...(matches
-                        ? {}
-                        : {
-                            remedy: {
-                                summary: `send one ${active.label} prompt in this session so the pointer belongs to it`,
-                                command: 'notifai doctor',
-                            },
-                        }),
+                    ok: true,
+                    detail: `the concurrent project index contains the active ${active.label} session`,
                 });
             }
         }
@@ -2670,16 +3427,37 @@ function hookChecks(deps) {
             : `${stale.join('; ')} — rerun \`notifai hooks install\` to drop ${stale.length === 1 ? 'it' : 'them'}`,
     });
     const adapterProblems = installations.flatMap((installation) => (installation.problems ?? []).map((problem) => `${installation.file}: ${problem}`));
+    const sharedAdapter = inspectHookAdapter(deps.hookAdapterHome);
+    adapterProblems.push(...sharedAdapter.problems);
     if (adapterProblems.length > 0) {
         checks.push({
             name: 'hooks (adapter)',
             ok: false,
+            // A machine-global install for a harness that is not active in this
+            // project is useful diagnosis, but it must not block unrelated init.
+            informational: active === null && installations.every((installation) => installation.global),
             detail: adapterProblems.join('; '),
         });
     }
-    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
-    const requiredTimeout = blockingHookTimeoutSeconds(config.ask_grace_seconds.value, config.hook_reply_timeout_seconds.value);
+    const trustProblems = codexTrustProblems(installations, deps.env);
+    checks.push({
+        name: 'hooks (trust)',
+        ok: trustProblems.length === 0,
+        detail: trustProblems.length === 0
+            ? 'best-effort check matches current persisted Codex approvals; Notifai never writes the trust store, and `/hooks` is authoritative'
+            : `best-effort check only; Notifai never writes the trust store and \`/hooks\` is authoritative. ${trustProblems.join('; ')}`,
+        ...(trustProblems.length === 0
+            ? {}
+            : {
+                remedy: {
+                    summary: 'open `/hooks` in Codex and approve the changed Notifai handlers',
+                    command: '/hooks',
+                },
+            }),
+    });
+    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' : ''}\``));
@@ -2687,60 +3465,85 @@ function hookChecks(deps) {
         name: 'hooks (timeout)',
         ok: shortTimeouts.length === 0,
         detail: shortTimeouts.length === 0
-            ? `installed Stop timeouts cover the current ${requiredTimeout}s grace/reply budget`
+            ? `declared Stop timeouts match the fixed ${requiredTimeout}s process budget where required; Codex uses host defaults`
             : shortTimeouts.join('; '),
     });
-    // Two checkouts each installing hooks means both fire for the same event, and
-    // the user gets every question twice.
-    //
-    // Compared *within* a harness, not across. Only one harness runs a given
-    // session, so having Claude Code and OpenCode both set up is the ordinary
-    // case and not a duplicate — comparing them turned a healthy machine red.
+    // Project and global definitions for one harness both fire. Stable adapter
+    // identity deliberately makes their command bytes equal, so comparing
+    // command targets would now hide this duplicate rather than diagnose it.
+    // Different harnesses remain independent: only the active one runs.
     const duplicated = [...new Set(installations.map((i) => i.harness))]
         .map((harness) => ({
         harness,
-        scripts: new Set(installations
-            .filter((i) => i.harness === harness)
-            .flatMap((i) => i.handlers.map((h) => h.command.split(' hook ')[0] ?? ''))),
+        installations: installations.filter((i) => i.harness === harness),
     }))
-        .filter((entry) => entry.scripts.size > 1);
+        .filter((entry) => entry.installations.length > 1);
     if (duplicated.length > 0) {
         checks.push({
             name: 'hooks (duplicates)',
             ok: false,
             detail: duplicated
-                .map((entry) => `${entry.harness}: ${entry.scripts.size} different Notifai builds are installed, so each event will fire all of them. Uninstall the ones you do not want: ${[...entry.scripts].join(', ')}`)
+                .map((entry) => `${entry.harness}: ${entry.installations.length} hook definitions are active, so each event will fire all of them. Keep either project or global routing and uninstall the other: ${entry.installations.map((installation) => installation.file).join(', ')}`)
                 .join('; '),
         });
     }
-    const firedPointer = readProjectSessionPointer(deps.cwd, deps.env, (deps.now ?? Date.now)());
-    const fired = firedPointer !== null;
+    if (active !== null && activeInstallations.length > 0) {
+        const admissionProblems = activeQuestionRouteProblems(deps, active, installations);
+        checks.push({
+            name: 'hooks (question admission)',
+            ok: admissionProblems.length === 0,
+            detail: admissionProblems.length === 0
+                ? `the active ${active.label} route is exact, current, singular, trusted where applicable, and bounded by a live owner`
+                : admissionProblems.join('; '),
+        });
+    }
+    const firedPointer = active?.sessionId === undefined
+        ? readProjectSessionPointer(deps.cwd, deps.env, (deps.now ?? Date.now)())
+        : 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;
     checks.push({
         name: 'hooks (fired)',
         ok: fired,
-        // Never-fired is evidence about the past, not a fault in the setup, and
-        // the cure is a prompt no command can send.
-        informational: true,
+        // A wholly fresh install is informational. Once UserPromptSubmit has fired,
+        // a missing Stop is a broken route, not missing historical evidence.
+        informational: firedPointer === null,
         detail: fired
-            ? 'a session in this directory has run them'
-            : `no session pointer from the last 24 hours — ${hookActivationAdvice(activationInstallations)}`,
+            ? 'a session in this directory has run UserPromptSubmit and Stop'
+            : firedPointer === null
+                ? `no session pointer from the last 24 hours — ${hookActivationAdvice(activationInstallations)}`
+                : `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: 'send one prompt in a session here, then re-check',
+                    summary: firedPointer === null
+                        ? 'send one prompt in a session here, then re-check'
+                        : 'end one harmless turn, send a new prompt, then re-check',
                     command: 'notifai doctor',
                 },
             }),
     });
-    if (installations.some((installation) => installation.harness === 'opencode')) {
-        checks.push({
-            name: 'hooks (opencode continuation)',
-            ok: false,
-            detail: 'question routing is installed; OpenCode cannot resume an idle turn automatically, but its next user prompt collects the answer',
-        });
-    }
+    const continuationInstallations = active !== null ? activeInstallations : installations;
+    const continuationHarnesses = [
+        ...new Set(continuationInstallations.map((installation) => installation.harness)),
+    ];
+    checks.push({
+        name: 'hooks (answer continuation)',
+        ok: continuationHarnesses.length > 0 &&
+            continuationHarnesses.every((harness) => HARNESS_CAPABILITIES[harness].stopContinuation !== 'unsupported'),
+        informational: active === null,
+        detail: continuationHarnesses.length === 0
+            ? active === null
+                ? 'no installed harness route to assess'
+                : `the active ${active.label} session has no matching continuation adapter`
+            : continuationHarnesses
+                .map((harness) => `${harness}: ${HARNESS_CAPABILITIES[harness].deliveryContract}`)
+                .join('; '),
+    });
     const stray = codexStrayWorktreeCheck(deps);
     if (stray !== null)
         checks.push(stray);
@@ -2853,14 +3656,22 @@ export function realIo(env = process.env) {
                 error: (next) => progress.error(next),
             };
         },
-        check: async (ok, message) => {
+        check: async (ok, message, tone) => {
             if (!interactive())
                 return;
             const { log } = await clack();
-            if (ok)
-                log.success(message);
-            else
-                log.error(message);
+            switch (tone ?? (ok ? 'ok' : 'bad')) {
+                case 'ok':
+                    return log.success(message);
+                case 'warn':
+                    return log.warn(message);
+                case 'pending':
+                    // Never checked. `log.info` reads as neutral, which is the honest
+                    // rendering for a state no evidence was gathered about.
+                    return log.info(message);
+                case 'bad':
+                    return log.error(message);
+            }
         },
         openUrl: (url) => {
             try {