@raidiant/notifai 4.0.0 → 5.0.0

package/src/commands.ts

@@ -6,6 +6,7 @@ import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
 import {
   AGENT_ACKNOWLEDGEMENT_MAX_LENGTH,
   CAPABILITIES_V1,
+  PLATFORMS,
   QUESTION_TEXT_MAX_LENGTH,
   REPLY_MAX_QUESTIONS,
   REPLY_MAX_WINDOW_SECONDS,
@@ -32,7 +33,6 @@ import {
 import {
   BOOLEAN_CONFIG_KEYS,
   CONFIG_KEYS,
-  LOG_LEVELS,
   NUMERIC_CONFIG_KEYS,
   configBounds,
   configDefaultValue,
@@ -66,7 +66,7 @@ import {
 } from './readiness.js'
 import type { Tone } from './ui/theme.js'
 import {
-  WAITER_CEILING_SECONDS,
+  waiterCeilingSeconds,
   clearAcknowledgementObligation,
   handleSessionEnd,
   handleStop,
@@ -82,6 +82,7 @@ import {
   type EscalationDeliveryRoute,
   type HookContext,
   type HookHarness,
+  MIN_REPLY_WINDOW_SECONDS,
 } from './hooks.js'
 import {
   LOG_EVENTS,
@@ -95,9 +96,11 @@ import {
   renderRecord,
   type LogQuery,
   type Logger,
+  RECORD_LEVELS,
 } from './logging.js'
 import {
   BLOCKING_STOP_TIMEOUT_SECONDS,
+  stopHandlerIsDetached,
   CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS,
   HARNESSES,
   applyPlan,
@@ -105,6 +108,8 @@ import {
   buildHookConfig,
   codexLayerDir,
   codexLayerPaths,
+  codexCoexistenceNotes,
+  codexHomeNote,
   codexRepresentationProblems,
   codexTrustProblems,
   codexProjectRoot,
@@ -319,7 +324,9 @@ function reportError(
     if (paths.length > 0) deps.io.err(`the server rejected: ${paths.join(', ')}`)
     // A 422 on a request this CLI built is not a user error: the two sides
     // disagree about the contract, in whichever direction. `doctor` says which.
-    if (err.status === 422) {
+    // Codes that name a policy the account chose are the exception — the
+    // contract held, the body simply did not satisfy that account.
+    if (err.status === 422 && err.code !== 'acknowledgement_text_required') {
       deps.io.err(
         'this build sent a field the server did not accept — the CLI and server ' +
           'disagree about the contract; check with `notifai doctor`',
@@ -565,6 +572,13 @@ export async function capabilitiesCommand(
   deps: CommandDeps,
   flags: { json?: boolean; platform?: Platform },
 ): Promise<number> {
+  // Locally, and with the same message `send` gives. Spending a round trip to
+  // have the server answer "Request validation failed" told the caller neither
+  // which flag was wrong nor what it accepts.
+  if (flags.platform !== undefined && !(PLATFORMS as readonly string[]).includes(flags.platform)) {
+    deps.io.err(`Unknown platform "${flags.platform}" — use ${PLATFORMS.join(' or ')}.`)
+    return EXIT.usage
+  }
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
   const credential = deps.store.load()
   const baseUrl = resolvedBaseUrl(config, credential)
@@ -638,6 +652,17 @@ export async function sendCommand(
     deps.io.err(`--kind ${flags.kind} cannot be combined with --reply; a reply request is a question.`)
     return EXIT.usage
   }
+  // Kind now decides the sound a notification arrives with, so it is asked for
+  // at the boundary rather than defaulted silently: an unlabelled send would
+  // reach the user as ordinary news whatever actually happened.
+  if (!flags.reply && flags.kind === undefined) {
+    deps.io.err(
+      '--kind is required: say what this notification is. ' +
+        'update (news) · done (finished) · failed (terminal failure) · blocked (cannot proceed). ' +
+        '--reply makes it a question without --kind.',
+    )
+    return EXIT.usage
+  }
   if (!flags.reply && flags.kind === 'question') {
     deps.io.err('--kind question requires --reply so the question can be answered.')
     return EXIT.usage
@@ -676,10 +701,12 @@ export async function sendCommand(
     flags.reply &&
     flags.replyWindow !== undefined &&
     (!Number.isInteger(flags.replyWindow) ||
-      flags.replyWindow < 60 ||
+      flags.replyWindow < MIN_REPLY_WINDOW_SECONDS ||
       flags.replyWindow > REPLY_MAX_WINDOW_SECONDS)
   ) {
-    deps.io.err(`--reply-window must be an integer from 60 to ${REPLY_MAX_WINDOW_SECONDS} seconds.`)
+    deps.io.err(
+      `--reply-window must be an integer from ${MIN_REPLY_WINDOW_SECONDS} to ${REPLY_MAX_WINDOW_SECONDS} seconds.`,
+    )
     return EXIT.usage
   }
   const mediaInputError = validateMediaInputs(flags.image, flags.imageAlt)
@@ -711,7 +738,7 @@ export async function sendCommand(
     }
     const uploaded = await uploadImage(deps, authed.client, image)
     if (!uploaded.ok) {
-      deps.io.err(uploaded.error)
+      if (uploaded.error !== null) deps.io.err(uploaded.error)
       return uploaded.exit
     }
     mediaIds.push(uploaded.mediaId)
@@ -794,6 +821,7 @@ export async function sendCommand(
               request_id: receipt.request_id,
               replies: [],
               agent_acknowledgement_required: receipt.agent_acknowledgement_required,
+              agent_acknowledgement_text_required: receipt.agent_acknowledgement_text_required,
               agent_acknowledgement: null,
               acknowledgement_command: null,
               degraded: false,
@@ -935,7 +963,14 @@ export async function repliesCommand(
       .map((entry) => entry.request_id)
       .filter((id): id is string => id !== undefined)
     if (requestIds.length === 0) {
-      deps.io.err(`Session ${sessionId} has no pushed question pending.`)
+      // `--json` is a promise about stdout, and an empty result is still a
+      // result: a caller that asked for machine-readable output must not have
+      // to parse an English sentence to learn there was nothing pending.
+      if (flags.json === true) {
+        deps.io.out(JSON.stringify({ session_id: sessionId, pending: [], replies: [] }, null, 2))
+      } else {
+        deps.io.err(`Session ${sessionId} has no pushed question pending.`)
+      }
       return EXIT.noReply
     }
   }
@@ -1071,6 +1106,7 @@ export async function waitForReply(
         request_id: requestId,
         reply_expires_at: null,
         agent_acknowledgement_required: false,
+        agent_acknowledgement_text_required: false,
         agent_acknowledgement: null,
         replies: [],
       } satisfies ListRepliesResponse),
@@ -1113,14 +1149,21 @@ function isNonNegativeInteger(value: number): boolean {
   return Number.isInteger(value) && value >= 0
 }
 
+function acknowledgeInvocation(requestId: string, textRequired: boolean): string {
+  return textRequired
+    ? `notifai acknowledge ${requestId} --text <text>`
+    : `notifai acknowledge ${requestId}`
+}
+
 function acknowledgementCommand(
   requestId: string,
   required: boolean,
+  textRequired: boolean,
   acknowledgement: ListRepliesResponse['agent_acknowledgement'],
   hasReply = true,
 ): string | null {
   return required && acknowledgement === null && hasReply
-    ? `notifai acknowledge ${requestId} --text <text>`
+    ? acknowledgeInvocation(requestId, textRequired)
     : null
 }
 
@@ -1132,9 +1175,11 @@ function replyResultJson(response: ListRepliesResponse, degraded: boolean): obje
     replies: response.replies,
     agent_acknowledgement_required: response.agent_acknowledgement_required,
     agent_acknowledgement: response.agent_acknowledgement,
+    agent_acknowledgement_text_required: response.agent_acknowledgement_text_required,
     acknowledgement_command: acknowledgementCommand(
       response.request_id,
       response.agent_acknowledgement_required,
+      response.agent_acknowledgement_text_required,
       response.agent_acknowledgement,
       response.replies.length > 0,
     ),
@@ -1147,16 +1192,22 @@ function printAcknowledgementStatus(deps: CommandDeps, response: ListRepliesResp
     deps.io.out('Agent Acknowledgement: not required for this request.')
     return
   }
+  const textRequired = response.agent_acknowledgement_text_required
   if (response.agent_acknowledgement !== null) {
+    const recorded = `Agent Acknowledgement: recorded at ${response.agent_acknowledgement.created_at}`
     deps.io.out(
-      `Agent Acknowledgement: recorded at ${response.agent_acknowledgement.created_at}: ${response.agent_acknowledgement.text}`,
+      response.agent_acknowledgement.text.length > 0
+        ? `${recorded}: ${response.agent_acknowledgement.text}`
+        : `${recorded}.`,
     )
     return
   }
   if (response.replies.length > 0) {
     deps.io.out('Agent Acknowledgement required.')
     deps.io.out(
-      `next: Run \`${acknowledgementCommand(response.request_id, true, null)}\` with concrete text saying what you will do because of the reply.`,
+      textRequired
+        ? `next: Run \`${acknowledgeInvocation(response.request_id, true)}\` with concrete text saying what you will do because of the reply.`
+        : `next: Run \`${acknowledgeInvocation(response.request_id, false)}\` so the user sees you read the reply; this account turned acknowledgement text off.`,
     )
     return
   }
@@ -1296,7 +1347,8 @@ const MEDIA_TYPES: Record<string, 'image/jpeg' | 'image/png' | 'image/gif'> = {
 
 type UploadResult =
   | { ok: true; mediaId: string }
-  | { ok: false; error: string; exit: number }
+  /** `error: null` means `reportError` already said it; do not print it twice. */
+  | { ok: false; error: string | null; exit: number }
 
 /** `--image` accepts a media id, a local file path, or an http(s) URL. */
 async function uploadImage(deps: CommandDeps, client: ApiClient, source: string): Promise<UploadResult> {
@@ -1331,7 +1383,13 @@ async function uploadImage(deps: CommandDeps, client: ApiClient, source: string)
     await client.uploadMedia(grant, bytes)
     return { ok: true, mediaId: grant.media_id }
   } catch (err) {
-    return { ok: false, error: err instanceof Error ? err.message : String(err), exit: EXIT.network }
+    // Every other API failure in this file goes through `reportError`, which
+    // maps a revoked credential to the auth code, a server fault to the network
+    // one and everything else to plain failure, and records it in the local
+    // log with whatever next step the server named. This used to answer
+    // `network` to all of them, so an image too large for the account exited
+    // the same way an unreachable server did, and nothing about it was logged.
+    return { ok: false, error: null, exit: reportError(deps, err) }
   }
 }
 
@@ -1374,7 +1432,11 @@ export async function hookRunCommand(
   // would grant slow setup a second budget and let the harness kill us before
   // an accepted answer is journaled or written to stdout.
   const now = deps.now ?? Date.now
-  const processDeadlineAt = now() + WAITER_CEILING_SECONDS * 1000
+  // The waiter may spend a long wall clock exactly when no turn is held open
+  // for it, which is the same condition the installer used to declare
+  // `async: true`. One predicate decides it for both.
+  const detachedWaiter = stopHandlerIsDetached(harness, deps.hookPlatform ?? process.platform)
+  const processDeadlineAt = now() + waiterCeilingSeconds(detachedWaiter) * 1000
 
   const logger = log(deps)
   logger.bind({ cmd: `hook ${event}` })
@@ -1567,20 +1629,7 @@ export async function hookRunCommand(
       ...outcome.log,
     })
     for (const note of outcome.notes) deps.io.err(`notifai: ${note}`)
-    if (outcome.stdout !== undefined) {
-      let stdout = outcome.stdout
-      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 })
-        }
-      }
-      deps.io.out(stdout)
-    }
+    if (outcome.stdout !== undefined) deps.io.out(outcome.stdout)
     return EXIT.ok
   } catch (err) {
     // SessionEnd defers its start record until after cleanup; if cleanup itself
@@ -1700,6 +1749,8 @@ function rejectedPaths(details: unknown): string[] {
 }
 
 export interface AskFlags {
+  /** Emit the registration and its turn obligation as one JSON object. */
+  json?: boolean
   choice?: string[]
   /** The single question is multi-select: several answers may be chosen. */
   multi?: boolean
@@ -1749,7 +1800,7 @@ export function buildQuestions(
       }
     }
     if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-      return { ok: false, error: '--form needs a "questions" array (1-4 entries).' }
+      return { ok: false, error: `--form needs a "questions" array (1-${REPLY_MAX_QUESTIONS} entries).` }
     }
     const record = parsed as Record<string, unknown>
     const unknownKeys = Object.keys(record).filter((key) => key !== 'questions' && key !== 'body')
@@ -1760,7 +1811,7 @@ export function buildQuestions(
       }
     }
     if (!Array.isArray(record['questions'])) {
-      return { ok: false, error: '--form needs a "questions" array (1-4 entries).' }
+      return { ok: false, error: `--form needs a "questions" array (1-${REPLY_MAX_QUESTIONS} entries).` }
     }
     const formQuestions = record['questions']
     if (formQuestions.length < 1 || formQuestions.length > REPLY_MAX_QUESTIONS) {
@@ -1886,6 +1937,7 @@ function recordRegisteredQuestion(
   sessionId: string,
   built: BuiltQuestions,
   draft: NotificationDraftT,
+  json = false,
 ): number {
   try {
     registerQuestion(
@@ -1914,6 +1966,37 @@ function recordRegisteredQuestion(
     choices: built.questions[0]!.choices?.length ?? 0,
     media: draft.presentation.media?.length ?? 0,
   })
+  // The block below is the densest guidance this CLI prints, and until now it
+  // was prose only: an agent could not read back the choice ids it must branch
+  // on without asking the server for them. The JSON form carries the same
+  // obligation as data.
+  if (json) {
+    deps.io.out(
+      JSON.stringify(
+        {
+          registered: true,
+          questions: built.questions.map((entry) => ({
+            id: entry.id,
+            text: entry.text,
+            ...(entry.choices === undefined ? {} : { choices: entry.choices }),
+            ...(entry.multi === true ? { multi: true } : {}),
+          })),
+          next: {
+            end_turn: true,
+            in_this_turn:
+              'Ask the question in the conversation and say what concrete work each possible answer will make you resume, then end the turn.',
+            route_neutral:
+              'Never say where the answer must arrive; it returns by whatever route the harness supports.',
+            on_answer:
+              'Acknowledge it, then resume the committed work without asking the user to confirm again.',
+          },
+        },
+        null,
+        2,
+      ),
+    )
+    return EXIT.ok
+  }
   for (const [index, entry] of built.questions.entries()) {
     const prefix = built.questions.length > 1 ? `${index + 1}. ` : ''
     if (entry.choices !== undefined) {
@@ -1973,7 +2056,7 @@ async function uploadAskMedia(
     }
     const uploaded = await uploadImage(deps, authed.client, image)
     if (!uploaded.ok) {
-      deps.io.err(uploaded.error)
+      if (uploaded.error !== null) deps.io.err(uploaded.error)
       return uploaded.exit
     }
     mediaIds.push(uploaded.mediaId)
@@ -1983,7 +2066,7 @@ async function uploadAskMedia(
     deps.io.err(ready.error)
     return EXIT.usage
   }
-  return recordRegisteredQuestion(deps, sessionId, built, ready.draft)
+  return recordRegisteredQuestion(deps, sessionId, built, ready.draft, flags.json === true)
 }
 
 /**
@@ -2121,7 +2204,7 @@ export function askCommand(
       source.invocation,
     )
   }
-  return recordRegisteredQuestion(deps, sessionId, built, preflight.draft)
+  return recordRegisteredQuestion(deps, sessionId, built, preflight.draft, flags.json === true)
 }
 
 /**
@@ -2399,20 +2482,27 @@ function hookActivationAdvice(installations: Installation[]): string {
   return `${advice.join('. ')}.`
 }
 
-/** Record the one Agent Acknowledgement associated with a replied-to request. */
+/**
+ * Record the one Agent Acknowledgement associated with a replied-to request.
+ *
+ * `--text` is optional here because the acknowledgement is not: an account may
+ * turn the agent's written reply off, and the receipt must still be recorded so
+ * the user sees that an agent read the answer. The service holds the account's
+ * snapshot, so it — not this process — decides whether text was owed.
+ */
 export async function acknowledgeCommand(
   deps: CommandDeps,
   requestId: string,
   flags: { text?: string; json?: boolean },
 ): Promise<number> {
   const text = flags.text?.trim() ?? ''
-  if (text.length === 0) {
-    deps.io.err('--text is required and must contain non-whitespace text.')
+  if (flags.text !== undefined && text.length === 0) {
+    deps.io.err('--text must contain non-whitespace text. Drop it to acknowledge without text.')
     return EXIT.usage
   }
   if (text.length > AGENT_ACKNOWLEDGEMENT_MAX_LENGTH) {
     deps.io.err(
-      `--text must be at most ${AGENT_ACKNOWLEDGEMENT_MAX_LENGTH} characters after trimming.`,
+      `--text must be at most ${AGENT_ACKNOWLEDGEMENT_MAX_LENGTH} characters after trimming. Shorten it: an acknowledgement is a receipt, not a report.`,
     )
     return EXIT.usage
   }
@@ -2427,7 +2517,10 @@ export async function acknowledgeCommand(
   const authed = authedClient(deps, config)
   if (!authed) return EXIT.auth
   try {
-    const result = await authed.client.putAgentAcknowledgement(requestId, { text })
+    const result = await authed.client.putAgentAcknowledgement(
+      requestId,
+      text.length > 0 ? { text } : {},
+    )
     const output = {
       request_id: requestId,
       outcome: result.status,
@@ -2476,6 +2569,7 @@ export async function closeCommand(
             acknowledgement_command: acknowledgementCommand(
               response.request_id,
               response.agent_acknowledgement_required,
+              response.agent_acknowledgement_text_required,
               response.agent_acknowledgement,
               response.replies.length > 0,
             ),
@@ -2554,7 +2648,7 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
   if (flags.harness === undefined) {
     const detected = detectedHarnesses(deps.cwd, deps.env)
     if (detected.length === 0) {
-      deps.io.err(`Could not tell which harness to install for — pass --harness <${HARNESSES.join('|')}>.`)
+      deps.io.err(`Could not tell which harness you mean — pass --harness <${HARNESSES.join('|')}>.`)
       return EXIT.usage
     }
     let ok = true
@@ -2679,6 +2773,13 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
     for (const problem of codexRepresentationProblems(deps.cwd, deps.env, hookPlatform)) {
       deps.io.out(problem)
     }
+    for (const note of codexCoexistenceNotes(deps.cwd, deps.env, hookPlatform)) {
+      deps.io.out(note)
+    }
+    if (flags.global) {
+      const home = codexHomeNote(deps.env, hookPlatform)
+      if (home !== null) deps.io.out(home)
+    }
   }
   return EXIT.ok
 }
@@ -2844,13 +2945,6 @@ function assertOwnedRegularFile(file: string): void {
   }
 }
 
-const HARNESS_LABEL: Record<Harness, string> = {
-  'claude-code': 'Claude Code',
-  codex: 'Codex',
-  cursor: 'Cursor',
-  opencode: 'OpenCode',
-}
-
 function resolveHarness(deps: CommandDeps, requested: string | undefined): Harness | null {
   if (requested !== undefined) {
     if ((HARNESSES as readonly string[]).includes(requested)) return requested as Harness
@@ -2887,7 +2981,7 @@ async function pickHarnessesToInstall(
       'Which agent harnesses should Notifai wire here?',
       HARNESSES.map((name) => ({
         value: name,
-        label: HARNESS_LABEL[name],
+        label: HARNESS_LABELS[name],
         ...(detected.includes(name) ? { hint: 'detected on this machine' } : {}),
       })),
       detected,
@@ -3360,8 +3454,8 @@ export function logsCommand(deps: CommandDeps, flags: LogsFlags): number {
     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}".`)
+    if (!(RECORD_LEVELS as readonly string[]).includes(flags.level)) {
+      deps.io.err(`--level takes one of: ${RECORD_LEVELS.join(', ')} — not "${flags.level}".`)
       return EXIT.usage
     }
     query.level = flags.level as LogLevel
@@ -4243,7 +4337,11 @@ async function printInitClose(
       ]
       await deps.io.note?.(lines.join('\n'), 'Ready')
       printOptionalLeftovers(deps, leftovers)
-      deps.io.out('All set. Agents in this project can notify you and ask questions.')
+      deps.io.out(
+      questions
+        ? 'All set. Agents in this project can notify you and ask you questions.'
+        : 'All set. Agents in this project can notify you. Questions stay in the terminal until hooks are installed.',
+    )
       await deps.io.outro?.('All set ✨')
       return
     }
@@ -4259,7 +4357,11 @@ async function printInitClose(
 
   if (blocker === null) {
     printOptionalLeftovers(deps, leftovers)
-    deps.io.out('All set. Agents in this project can notify you and ask questions.')
+    deps.io.out(
+      questions
+        ? 'All set. Agents in this project can notify you and ask you questions.'
+        : 'All set. Agents in this project can notify you. Questions stay in the terminal until hooks are installed.',
+    )
     return
   }
   deps.io.out(`Next: ${blocker.title} — ${blocker.detail}`)
@@ -4845,15 +4947,41 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
     ]
   }
 
+/**
+ * A human title per check.
+ *
+ * Three checks used to collapse onto "Question routing", so a reader could not
+ * tell which of them had failed, and the rest fell through to their internal
+ * name — `hooks (stale)` beside `Delivery proof`. The `id` stays the stable
+ * thing to branch on; this is only what a person reads.
+ */
+const CHECK_TITLES: Readonly<Record<string, string>> = {
+  hooks: 'Question routing',
+  'hooks (detected)': 'Harnesses detected',
+  'hooks (active harness)': 'Routing for this harness',
+  'hooks (active session)': 'Routing for this session',
+  'hooks (stale)': 'Hook definitions current',
+  'hooks (adapter)': 'Hook adapter',
+  'hooks (trust)': 'Codex hook trust',
+  'hooks (stop shape)': 'Turn-end hook shape',
+  'hooks (duplicates)': 'Duplicate hook installs',
+  'hooks (codex representation)': 'Codex hook representation',
+  'hooks (question admission)': 'Question admission',
+  'hooks (fired)': 'Hooks have run here',
+  'hooks (answer continuation)': 'How an answer returns',
+  'hooks (wake route)': 'Direct wake route',
+}
+
+function checkTitle(name: string): string {
+  return CHECK_TITLES[name] ?? name
+}
+
   /** Real but not in the way; see the note above. */
   const informational = new Set<string>()
   return [
     ...hookChecks(deps).map((check) => ({
       id: check.name.replace(/[ ()]+/g, '-').replace(/-$/, ''),
-      title:
-        check.name === 'hooks' || check.name.startsWith('hooks (active')
-          ? 'Question routing'
-          : check.name,
+      title: checkTitle(check.name),
       status: check.ok
         ? 'ready' as const
         : check.informational === true || informational.has(check.name)
@@ -4903,7 +5031,7 @@ function stopShapeProblems(
   for (const handler of installation.handlers.filter(
     (entry) => handlerEvent(entry.command) === 'stop',
   )) {
-    if (installation.harness === 'claude-code' && platform !== 'win32') {
+    if (stopHandlerIsDetached(installation.harness, platform)) {
       if (handler.async !== true) {
         problems.push(
           `${installation.file} declares a blocking Stop handler; the Claude Code wake route needs \`async: true\` so the turn ends while the waiter runs`,
@@ -4964,7 +5092,7 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
       name: 'hooks (detected)',
       ok: false,
       informational: true,
-      detail: `${unwired.map((harness) => HARNESS_LABEL[harness]).join(', ')} detected on this machine but not wired`,
+      detail: `${unwired.map((harness) => HARNESS_LABELS[harness]).join(', ')} detected on this machine but not wired`,
       remedy: {
         summary: 'install hooks for every detected harness',
         command: 'notifai hooks install',
@@ -5140,6 +5268,20 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
       ok: false,
       detail: representationProblems.join('; '),
     })
+  } else {
+    const coexistence = codexCoexistenceNotes(deps.cwd, deps.env, deps.hookPlatform)
+    if (coexistence.length > 0) {
+      checks.push({
+        name: 'hooks (codex representation)',
+        ok: true,
+        detail: coexistence.join('; '),
+      })
+    }
+  }
+
+  const codexHome = codexHomeNote(deps.env, deps.hookPlatform)
+  if (codexHome !== null) {
+    checks.push({ name: 'hooks (codex home)', ok: true, detail: codexHome })
   }
 
   if (active !== null && activeInstallations.length > 0) {

package/src/config-schema.test.ts

@@ -86,7 +86,7 @@ describe('formatValue', () => {
   it('explains what an unset value means instead of printing null', () => {
     // `sound = null` is accurate and tells the reader nothing about what will
     // happen; the whole complaint about the old output in one line.
-    expect(formatValue('sound', null)).toBe('not specified; the destination uses its normal behavior')
+    expect(formatValue('sound', null)).toBe('not set; each kind brings its own sound')
     expect(formatValue('devices', null)).toBe('every device that can receive')
   })
 

package/src/config-schema.ts

@@ -85,7 +85,7 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     kind: 'boolean',
     summary: 'Whether a registered question may reach your phone and Mac at all',
     detail:
-      'The master switch for question routing. When this is off, a question an agent registers with `notifai ask` stays in the terminal and never leaves this machine, whatever the presence settings say. Turn it off to stop being reached for a while without uninstalling the harness hooks.',
+      'The master switch for question routing. When this is off, a question an agent registers with `notifai ask` stays in the terminal and never leaves this machine, whatever else is configured. Turn it off to stop being reached for a while without uninstalling the harness hooks.',
     example: 'true',
   },
   ask_grace_seconds: {
@@ -99,6 +99,17 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     example: '0',
   },
 
+  reply_window_seconds: {
+    label: 'How long an answer is accepted',
+    group: 'questions',
+    kind: 'integer',
+    unit: 's',
+    summary: 'How long the service keeps accepting your answer to a question',
+    detail:
+      'A question stays answerable for this long after it is asked. The default is a day, so a question that arrives while you are away is still yours to answer when you come back.\n\nThis is not how long anything waits on you. The agent ends its turn immediately; if it is still running when you answer, the answer reaches it directly, and otherwise it is delivered at that session\'s next turn. Shortening this only makes an answer arrive too late to be accepted.',
+    example: '86400',
+  },
+
   sound: {
     label: 'Sound',
     group: 'delivery',
@@ -113,8 +124,8 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     },
     summary: 'Set the sound notifications from here use',
     detail:
-      'Setting this pins one sound for every notification sent from here. Kind remains semantic status metadata and never changes native-banner attention.\n\nLeave this unset to omit the sound field and let the destination use its normal behavior. A common explicit preference is `none`, to make a noisy project completely silent.',
-    unsetMeans: 'not specified; the destination uses its normal behavior',
+      'Setting this pins one sound for every notification sent from here, whatever kind it is.\n\nLeave it unset and each notification arrives with the sound its kind implies: the completion chime when work finished, the most insistent tone when it failed, a distinct attention tone for a question or blocked work, and the standard tone for ordinary news. A common explicit preference is `none`, to make a noisy project completely silent.',
+    unsetMeans: 'not set; each kind brings its own sound',
   },
   interruption_level: {
     label: 'Interruption level',
@@ -124,11 +135,11 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     choiceHints: {
       passive: 'no sound or wake — waits in the notification list',
       active: 'wakes the screen and plays the sound',
-      time_sensitive: 'may break through Focus modes',
+      time_sensitive: 'marks the notification urgent; Focus breakthrough is not available yet',
     },
     summary: 'Set how insistently notifications from here arrive',
     detail:
-      'How hard a notification tries to reach you, in the operating system\'s terms. Setting this pins one level for everything sent from here; kind never changes it.\n\nLeave this unset to omit the field and let the destination use its normal behavior. `time_sensitive` can pierce a Focus mode, so reserve it for cases that genuinely earn it.',
+      'How hard a notification tries to reach you, in the operating system\'s terms. Setting this pins one level for everything sent from here; kind chooses the sound, never this.\n\nLeave this unset to omit the field and let the destination use its normal behavior. `time_sensitive` is accepted and marks the notification urgent, but Focus breakthrough is not available yet — run `notifai capabilities` for what a platform actually honours.',
     unsetMeans: 'not specified; the destination uses its normal behavior',
   },
   devices: {