@raidiant/notifai 0.2.1 → 0.4.0

package/src/commands.ts

@@ -1,6 +1,6 @@
 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'
@@ -24,14 +24,17 @@ import {
   ApiCallError,
   NetworkError,
   createClient,
+  isRetryableReplyPollError,
   type ApiClient,
   type ClientOptions,
 } from './client.js'
 import {
   BOOLEAN_CONFIG_KEYS,
   CONFIG_KEYS,
+  LOG_LEVELS,
   NUMERIC_CONFIG_KEYS,
   configBounds,
+  configDefaultValue,
   findProjectConfigPath,
   findProjectLocalConfigPath,
   globalConfigPath,
@@ -40,24 +43,53 @@ import {
   type CliConfig,
   type ConfigKey,
   type FlagOverrides,
+  type LogLevel,
 } 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 type { CredentialStore, MachineCredential } from './credentials.js'
-import { firstBlocker, openItems, type Readiness, type ReadinessState } from './readiness.js'
+import {
+  firstBlocker,
+  openItems,
+  type Readiness,
+  type ReadinessState,
+  type StateStatus,
+} from './readiness.js'
+import type { Tone } from './ui/theme.js'
 import {
   handleSessionEnd,
   handleStop,
   handleUserPromptSubmit,
   parseHookInput,
   pruneAbandonedSessions,
+  readMatchingProjectSessionPointer,
   readProjectSession,
   readProjectSessionPointer,
   readSessionState,
   registerQuestion,
   type HookContext,
-  type HookEnvelope,
   type HookHarness,
 } from './hooks.js'
 import { readIdleSeconds } from './idle.js'
+import {
+  LOG_EVENTS,
+  activeLogPath,
+  archiveLogPaths,
+  logConfigResolved,
+  logSettingsFrom,
+  logsDiskUsage,
+  nullLogger,
+  readLogRecords,
+  renderRecord,
+  type LogQuery,
+  type Logger,
+} from './logging.js'
 import {
   HARNESSES,
   applyPlan,
@@ -65,6 +97,7 @@ import {
   buildCursorHookConfig,
   buildHookConfig,
   codexLayerDir,
+  codexTrustProblems,
   codexProjectRoot,
   detectHarness,
   findInstallations,
@@ -79,6 +112,11 @@ import {
   type Harness,
   type Installation,
 } from './install-hooks.js'
+import { HARNESS_CAPABILITIES, HOOK_TIMING } from './harnesses.js'
+import {
+  inspectHookAdapter,
+  installHookAdapter,
+} from './hook-adapter.js'
 import {
   isOurOpencodePlugin,
   opencodePluginSource,
@@ -113,7 +151,13 @@ export interface CommandIo {
   outro?(message: string): Promise<void>
   note?(message: string, title?: string): Promise<void>
   spinner?(message: string): Promise<CommandSpinner | null>
-  check?(ok: boolean, message: string): Promise<void>
+  /**
+   * A report line. `tone` distinguishes the two states that are neither pass
+   * nor fail — something optional the user declined, and something that was
+   * never evaluated — which a boolean has to round to one or the other.
+   * Optional so existing implementations keep type-checking.
+   */
+  check?(ok: boolean, message: string, tone?: Tone): Promise<void>
 }
 
 export interface CommandSpinner {
@@ -127,6 +171,8 @@ export interface CommandDeps {
   store: CredentialStore
   env: NodeJS.ProcessEnv
   cwd: string
+  /** Test seam; production fixes the hook adapter under os.homedir(). */
+  hookAdapterHome?: string
   /** Test seam; production uses fetch against base_url. */
   clientFactory?: (baseUrl: string, bearer: string | null, options?: ClientOptions) => ApiClient
   /** Test seam for bounded polling without wall-clock sleeps. */
@@ -137,6 +183,28 @@ export interface CommandDeps {
   idleSeconds?: () => number | null
   /** Test seam and production adapter for the external native skills installer. */
   nativeSkills?: NativeSkills
+  /**
+   * The local record of what this invocation did. Optional so a test fake need
+   * not carry one; `log(deps)` supplies a logger that records nothing.
+   */
+  logger?: Logger
+}
+
+/** The invocation's logger, or one that discards everything. */
+export function log(deps: CommandDeps): Logger {
+  return deps.logger ?? nullLogger()
+}
+
+function loadLoggedConfig(
+  deps: CommandDeps,
+  options: Parameters<typeof loadConfig>[0],
+): CliConfig {
+  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 = {
@@ -154,7 +222,7 @@ function makeClient(
   bearer: string | null,
   options?: ClientOptions,
 ): ApiClient {
-  return (deps.clientFactory ?? createClient)(baseUrl, bearer, options)
+  return (deps.clientFactory ?? createClient)(baseUrl, bearer, { ...options, logger: log(deps) })
 }
 
 function resolvedBaseUrl(config: CliConfig, credential: MachineCredential | null): string {
@@ -164,6 +232,10 @@ function resolvedBaseUrl(config: CliConfig, credential: MachineCredential | null
 function authedClient(deps: CommandDeps, config: CliConfig): { client: ApiClient; baseUrl: string } | null {
   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
   }
@@ -174,7 +246,22 @@ function authedClient(deps: CommandDeps, config: CliConfig): { client: ApiClient
   }
 }
 
-function reportError(deps: CommandDeps, err: unknown): number {
+function reportError(
+  deps: CommandDeps,
+  err: unknown,
+  context: Record<string, unknown> = {},
+): number {
+  // 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) deps.io.err(`next: ${err.nextAction}`)
@@ -197,7 +284,7 @@ export async function loginCommand(
   deps: CommandDeps,
   flags: { name?: string; baseUrl?: string; open?: boolean },
 ): Promise<number> {
-  const config = loadConfig({ cwd: deps.cwd, env: deps.env, flags: { base_url: flags.baseUrl } as FlagOverrides })
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env, flags: { base_url: flags.baseUrl } as FlagOverrides })
   const baseUrl = config.base_url.value
   const machineName = flags.name ?? os.hostname()
   const secret = randomBytes(32).toString('base64url')
@@ -326,7 +413,7 @@ export async function accessStatusCommand(
   deps: CommandDeps,
   flags: { json?: boolean },
 ): Promise<number> {
-  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 {
@@ -354,7 +441,7 @@ export async function accessStatusCommand(
 // ---------------------------------------------------------------------------
 
 export async function devicesCommand(deps: CommandDeps, flags: { json?: boolean }): Promise<number> {
-  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 {
@@ -387,11 +474,37 @@ export async function devicesCommand(deps: CommandDeps, flags: { json?: boolean
   }
 }
 
+/**
+ * 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: CommandDeps): Promise<RoutableDevice[] | null> {
+  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: RoutableDevice): boolean {
+  return deviceCanReceive(device)
+}
+
 export async function capabilitiesCommand(
   deps: CommandDeps,
   flags: { json?: boolean; platform?: Platform },
 ): Promise<number> {
-  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)
@@ -474,7 +587,7 @@ export async function sendCommand(
     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 } as FlagOverrides,
@@ -515,38 +628,71 @@ export async function sendCommand(
   }
   const waitSeconds = flags.noWait ? 0 : config.wait_seconds.value
   const idempotencyKey = flags.idempotencyKey ?? `cli-${randomBytes(12).toString('base64url')}`
+  let receipt: SubmissionReceipt
   try {
-    const receipt = await authed.client.submit(
+    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 }))
+  } 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
+  // 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({
@@ -559,17 +705,48 @@ export async function sendCommand(
     } else if (result.response.replies.length > 0) printReplies(deps, result.response.replies)
     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)
   }
 }
@@ -660,40 +837,49 @@ export async function repliesCommand(
     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: string[] = []
     let allTimedOut = true
     const jsonBodies: object[] = []
     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)
-      } else {
-        printNoReply(deps, requestId, result.response.reply_expires_at)
+      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
+      } 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) return EXIT.ok
@@ -730,8 +916,8 @@ export async function waitForReply(
   const sleep = options.sleep ?? ((milliseconds: number) => new Promise((resolve) => setTimeout(resolve, milliseconds)))
   const deadline = now() + options.timeoutSeconds * 1000
   let lastResponse: ListRepliesResponse | null = null
-  let lastNetworkError: NetworkError | null = null
-  let consecutiveNetworkErrors = 0
+  let lastTransientError: Error | null = null
+  let consecutiveTransientErrors = 0
   let firstPoll = true
 
   while (firstPoll || now() < deadline) {
@@ -744,24 +930,31 @@ export async function waitForReply(
         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()))
       if (pauseMs > 0) await sleep(pauseMs)
     } catch (err) {
-      if (!(err instanceof NetworkError)) throw err
-      lastNetworkError = err
-      consecutiveNetworkErrors += 1
+      if (!isRetryableReplyPollError(err)) throw err
+      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 ??
@@ -770,23 +963,55 @@ export async function waitForReply(
     // 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: CommandDeps, requestIds: readonly string[]): void {
+  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: string): string {
+  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: number): boolean {
   return Number.isInteger(value) && value >= 0
 }
 
+function recordReplies(deps: CommandDeps, requestId: string, replies: readonly ReplyView[]): void {
+  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: CommandDeps, replies: ReplyView[]): void {
   for (const reply of replies) deps.io.out(`reply from ${reply.device_name}: ${reply.text}`)
   const contradiction = contradictingAnswer(replies)
@@ -835,7 +1060,7 @@ export async function statusCommand(
   requestId: string,
   flags: { json?: boolean },
 ): Promise<number> {
-  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 {
@@ -845,6 +1070,7 @@ export async function statusCommand(
       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)`)
@@ -862,10 +1088,27 @@ export async function statusCommand(
           "    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) {
     return reportError(deps, err)
@@ -934,6 +1177,13 @@ async function uploadImage(deps: CommandDeps, client: ApiClient, source: string)
 export const HOOK_EVENTS = ['user-prompt-submit', 'stop', 'session-end'] as const
 export type HookEvent = (typeof HOOK_EVENTS)[number]
 
+/** SessionEnd cleanup must precede every diagnostic that can wait on a file lock. */
+export function hookDefersDiagnosticsUntilAfterCleanup(
+  event: unknown,
+): event is 'session-end' {
+  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
@@ -953,53 +1203,129 @@ export async function hookRunCommand(
     deps.io.err(`Unknown hook event "${event}". Valid: ${HOOK_EVENTS.join(', ')}`)
     return EXIT.usage
   }
-  let envelope: HookEnvelope
+
+  // 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: Record<string, unknown> = {}): void => {
+    if (started) return
+    started = true
+    logger.info('hook.start', { hook: event, harness: harness ?? 'unknown', ...data })
+  }
+  const failureData = (err: unknown): Record<string, unknown> =>
+    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: string
   try {
-    const raw = await readStdin()
-    if (raw.trim() !== '') {
-      try {
-        const parsed: unknown = 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: unknown = JSON.parse(raw)
+      if (typeof parsed !== 'object' || parsed === null) throw new Error('not an object')
+    } 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
     }
-    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),
-      }
+  }
+
+  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: CliConfig | null = null
+  let configFailure: unknown
+  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
     }
-  } catch {
-    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
     }
@@ -1007,9 +1333,9 @@ export async function hookRunCommand(
     // 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) {
+    if (resolved.base_url.source !== 'default' && resolved.base_url.value !== baseUrl) {
       deps.io.err(
-        `notifai: ignoring base_url from ${config.base_url.source}; hooks only talk to ${baseUrl}`,
+        `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
@@ -1019,12 +1345,20 @@ export async function hookRunCommand(
       deps,
       baseUrl,
       `Bearer nfm_${credential.machineId}.${credential.secret}`,
-      { timeoutMs: event === 'user-prompt-submit' ? 4_000 : 20_000 },
+      {
+        timeoutMs: event === 'user-prompt-submit' ? 4_000 : 20_000,
+        ...(event === 'stop'
+          ? {
+              deadlineAt:
+                processDeadlineAt - HOOK_TIMING.stdoutReserveSeconds * 1000,
+              now,
+            }
+          : {}),
+      },
     )
-    const now = deps.now ?? Date.now
     const ctx: HookContext = {
       client,
-      config,
+      config: resolved,
       env: deps.env,
       now,
       idleSeconds: deps.idleSeconds ?? (() => readIdleSeconds()),
@@ -1042,24 +1376,41 @@ export async function hookRunCommand(
           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) as { decision?: unknown; reason?: unknown }
         if (decision.decision === 'block' && typeof decision.reason === 'string') {
           stdout = JSON.stringify({ followup_message: decision.reason })
@@ -1069,6 +1420,17 @@ export async function hookRunCommand(
     }
     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
   }
@@ -1227,27 +1589,40 @@ function buildOneQuestion(
 
 /**
  * Registers a question for turn-end routing under the user's presence config.
- * Returns immediately so the agent can ask in prose and end its turn. 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: CommandDeps, question: string | undefined, flags: AskFlags): number {
+  // 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: string | undefined
-  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,
     )
@@ -1257,35 +1632,52 @@ export function askCommand(deps: CommandDeps, question: string | undefined, flag
       }
       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 {
@@ -1300,9 +1692,20 @@ export function askCommand(deps: CommandDeps, question: string | undefined, flag
       (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) {
@@ -1359,6 +1762,69 @@ function activeHarnessSession(env: NodeJS.ProcessEnv): ActiveHarnessSession | nu
   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: CommandDeps,
+  active: ActiveHarnessSession,
+  installations: Installation[],
+): string[] {
+  const problems: string[] = []
+  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 as readonly string[]).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)]
+}
+
 type ActiveHarnessProblem = 'not-installed' | 'not-fired' | 'different-session'
 
 function diagnoseActiveHarnessSession(
@@ -1403,7 +1869,7 @@ function diagnoseActiveHarnessSession(
  * checked after a prompt before assuming that a new session is required.
  */
 function diagnoseMissingSession(deps: CommandDeps): string[] {
-  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.',
@@ -1415,7 +1881,7 @@ function diagnoseMissingSession(deps: CommandDeps): string[] {
     `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.',
   ]
 }
 
@@ -1460,7 +1926,7 @@ function hookActivationAdvice(installations: Installation[]): string {
   }
   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',
+      'OpenCode: restart it, then send one prompt; plugins load at startup, but non-blocking question continuation is intentionally unsupported',
     )
   }
   return `${advice.join('. ')}.`
@@ -1468,7 +1934,7 @@ function hookActivationAdvice(installations: Installation[]): string {
 
 /** Retire a question so a late answer is rejected rather than silently lost. */
 export async function closeCommand(deps: CommandDeps, requestId: string): Promise<number> {
-  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 {
@@ -1493,43 +1959,41 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
   if (!harness) 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: string
+  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: ReturnType<typeof mergeCursorHooks>
     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))
       return EXIT.failed
@@ -1544,31 +2008,27 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
       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: ReturnType<typeof mergeHooks>
   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))
     return EXIT.failed
@@ -1581,18 +2041,22 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
     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.',
@@ -1636,18 +2100,23 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
 function installOpencodePlugin(
   deps: CommandDeps,
   file: string,
-  options: { execPath: string; scriptPath: string; timeoutSeconds: number },
+  options: { adapterPath: string; timeoutSeconds: number },
 ): number {
-  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))
     return EXIT.failed
@@ -1657,9 +2126,9 @@ function installOpencodePlugin(
   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
@@ -1670,35 +2139,46 @@ export function hooksUninstallCommand(deps: CommandDeps, flags: HooksInstallFlag
   if (!harness) 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: ReturnType<typeof removeCursorHooks> | null
     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}`
@@ -1706,19 +2186,22 @@ export function hooksUninstallCommand(deps: CommandDeps, flags: HooksInstallFlag
     )
     return EXIT.ok
   }
-  let document
+  let stripped: ReturnType<typeof removeHooks> | null
   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
@@ -1728,6 +2211,17 @@ export function hooksUninstallCommand(deps: CommandDeps, flags: HooksInstallFlag
   return EXIT.ok
 }
 
+function assertOwnedRegularFile(file: string): void {
+  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: CommandDeps, requested: string | undefined): Harness | null {
   if (requested !== undefined) {
     if ((HARNESSES as readonly string[]).includes(requested)) return requested as Harness
@@ -1745,14 +2239,14 @@ function resolveHarness(deps: CommandDeps, requested: string | undefined): Harne
 }
 
 // ---------------------------------------------------------------------------
-// config show / set
+// config show / set / unset
 // ---------------------------------------------------------------------------
 
 export function configShowCommand(
   deps: CommandDeps,
-  flags: { json?: boolean; explain?: boolean },
+  flags: { json?: boolean; explain?: boolean; plain?: boolean },
 ): number {
-  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 }]),
@@ -1760,47 +2254,198 @@ export function configShowCommand(
     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
 }
 
+/**
+ * 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: CommandDeps,
+  key: string,
+  flags: { json?: boolean } = {},
+): number {
+  if (!(CONFIG_KEYS as readonly string[]).includes(key)) {
+    deps.io.err(`Unknown setting "${key}".`)
+    deps.io.err(`Valid settings: ${CONFIG_KEYS.join(', ')}`)
+    return EXIT.usage
+  }
+  const configKey = key as ConfigKey
+  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: string): string | null {
+  let best: string | null = 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: string, b: string): number {
+  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: CommandDeps,
   key: string,
   rawValue: string,
   flags: { project?: boolean; local?: boolean; session?: string; yes?: boolean },
 ): Promise<number> {
-  if (!(CONFIG_KEYS as readonly string[]).includes(key)) {
-    deps.io.err(`Unknown key "${key}". Valid keys: ${CONFIG_KEYS.join(', ')}`)
-    return EXIT.usage
-  }
+  const configKey = configMutationKey(deps, key)
+  if (configKey === null) return EXIT.usage
+  const info = configInfo(configKey)
   let value: unknown = rawValue
-  if (NUMERIC_CONFIG_KEYS.includes(key as ConfigKey)) {
+  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 as ConfigKey)
+    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 as ConfigKey)) {
+  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')) as Record<string, unknown>)
+    : {}
+  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: CommandDeps, key: string): ConfigKey | null {
+  if (!(CONFIG_KEYS as readonly string[]).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 as ConfigKey
+}
+
+type ConfigMutationFlags = { project?: boolean; local?: boolean; session?: string; yes?: boolean }
+type ConfigMutationLayer = 'global' | 'project' | 'local' | 'session'
+
+async function configMutationTarget(
+  deps: CommandDeps,
+  flags: ConfigMutationFlags,
+): Promise<{ path: string; layer: ConfigMutationLayer } | null> {
   let layer = flags.local ? 'local' : flags.project ? 'project' : 'global'
   if (
     flags.session === undefined &&
@@ -1817,7 +2462,7 @@ export async function configSetCommand(
     ])
     if (selected === null) {
       deps.io.err('No configuration layer selected.')
-      return EXIT.usage
+      return null
     }
     layer = selected
   }
@@ -1829,22 +2474,273 @@ export async function configSetCommand(
       : layer === 'project'
         ? (findProjectConfigPath(deps.cwd) ?? path.join(deps.cwd, '.notifai', 'config.toml'))
         : globalConfigPath(deps.env)
+  return {
+    path: targetPath,
+    layer: flags.session ? 'session' : (layer as Exclude<ConfigMutationLayer, 'session'>),
+  }
+}
 
+export async function configUnsetCommand(
+  deps: CommandDeps,
+  key: string,
+  flags: ConfigMutationFlags,
+): Promise<number> {
+  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')) as Record<string, unknown>)
+    : {}
+  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')) as Record<string, unknown>)
-    : {}
-  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
+}
+
+// ---------------------------------------------------------------------------
+// logs
+// ---------------------------------------------------------------------------
+
+export interface LogsFlags {
+  json?: boolean
+  limit?: number
+  all?: boolean
+  since?: string
+  level?: string
+  event?: string[]
+  run?: string
+  request?: string
+  session?: string
+  project?: string
+  allProjects?: boolean
+  grep?: string
+  path?: boolean
+  clear?: boolean
+}
+
+const LOG_RECORD_OPTIONS: readonly (readonly [keyof LogsFlags, string])[] = [
+  ['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: string, now: number): number | null {
+  const relative = /^(\d+)([smhd])$/.exec(raw.trim())
+  if (relative !== null) {
+    const amount = Number(relative[1])
+    const unit = relative[2] as 's' | 'm' | 'h' | 'd'
+    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: CommandDeps, flags: LogsFlags): number {
+  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: LogQuery = {
+    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 as readonly string[]).includes(flags.level)) {
+      deps.io.err(`--level takes one of: ${LOG_LEVELS.join(', ')} — not "${flags.level}".`)
+      return EXIT.usage
+    }
+    query.level = flags.level as LogLevel
+  }
+  if (flags.event !== undefined && flags.event.length > 0) {
+    const unknown = flags.event.filter((name) => !(LOG_EVENTS as readonly string[]).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: string[] = []
+  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
 }
 
@@ -1857,7 +2753,7 @@ export async function configSetCommand(
  * 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(): { source: string; ref: string } | null {
   const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE)
@@ -2175,7 +3071,7 @@ async function waitForReadyDevice(deps: CommandDeps, state: ReadinessState): Pro
   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.')
@@ -2326,7 +3222,7 @@ async function submitSetupProof(
  * the push, not that a companion process received it.
  */
 async function runSetupProof(deps: CommandDeps): Promise<GapCloseResult> {
-  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'
 
@@ -2694,7 +3590,7 @@ export async function assessReadiness(
   deps: CommandDeps,
   options: { skillScope?: SkillScope } = {},
 ): Promise<Readiness> {
-  const config = loadConfig({ cwd: deps.cwd, env: deps.env })
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
   const states: ReadinessState[] = []
   let accountClient: ApiClient | null = null
   let accountDevices: RoutableDevice[] | null = null
@@ -3012,7 +3908,13 @@ export async function doctorCommand(deps: CommandDeps, flags: { json?: boolean }
   // 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 {
     for (const s of readiness.states) {
@@ -3031,6 +3933,20 @@ export async function doctorCommand(deps: CommandDeps, flags: { json?: boolean }
   return ok ? EXIT.ok : EXIT.failed
 }
 
+/** Readiness status as a report tone. */
+function doctorTone(status: StateStatus): Tone {
+  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: ReadinessState): string {
   const remedy = state.remedy
@@ -3059,23 +3975,21 @@ function remedyLine(state: ReadinessState): string {
  *
  * 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: CommandDeps): ReadinessState[] {
-  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: ReadinessState = {
     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})`,
@@ -3083,6 +3997,15 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
       `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' as const,
+            summary: 'enable asynchronous question routing',
+            command: 'notifai config set ask_notifications true',
+          },
+        }),
   }
   if (installations.length === 0) {
     return [
@@ -3108,7 +4031,7 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
   }
 
   /** Real but not in the way; see the note above. */
-  const informational = new Set(['hooks (opencode continuation)'])
+  const informational = new Set<string>()
   return [
     ...hookChecks(deps).map((check) => ({
       id: check.name.replace(/[ ()]+/g, '-').replace(/-$/, ''),
@@ -3153,7 +4076,7 @@ interface HookCheck {
 
 function hookChecks(deps: CommandDeps): HookCheck[] {
   const checks: HookCheck[] = []
-  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.
@@ -3196,7 +4119,16 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
           }),
     })
     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
@@ -3213,23 +4145,10 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
           },
         })
       } 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`,
         })
       }
     }
@@ -3257,21 +4176,41 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
   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(
@@ -3284,26 +4223,20 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
     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)',
@@ -3311,43 +4244,86 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
       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(', ')}`,
+            `${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)
@@ -3463,11 +4439,21 @@ export function realIo(env: NodeJS.ProcessEnv = process.env): CommandIo {
         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 {