@raidiant/notifai 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -8,6 +8,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
+## [5.0.0](https://github.com/Raidiant-io/notifai/compare/v4.0.0...v5.0.0) (2026-08-16)
+
+
+### ⚠ BREAKING CHANGES
+
+* `notifai send` now requires --kind. The account preference `agent_acknowledgements_enabled` is renamed to `agent_acknowledgement_text_enabled` and governs only the written reply.
+
+### Features
+
+* **cli:** report an ask registration as data, and stop init promising routing it lacks ([156159b](https://github.com/Raidiant-io/notifai/commit/156159b4d39b249a1be65ac86a9f7452ee9720d2))
+* keep a question answerable for a day, and let the user choose ([ace207e](https://github.com/Raidiant-io/notifai/commit/ace207e04cfdc3a0ccda14dffc79a882a663034c))
+* make kind required and carry attention, and always acknowledge an answer ([07e7c21](https://github.com/Raidiant-io/notifai/commit/07e7c216d52f3041e50ce5c7ec1ce4a3f8491e64))
+
+
+### Bug Fixes
+
+* clean up what the help, the README and a test comment were saying ([221ca6b](https://github.com/Raidiant-io/notifai/commit/221ca6b1d04a80cbd8473d54cd50a6024dcf6c50))
+* **cli:** retire drafts the server rejects as invalid ([4023e42](https://github.com/Raidiant-io/notifai/commit/4023e42e3aeb9f8674239ab0516ccf2527b1428c))
+* **cli:** retire drafts the server rejects as invalid ([d676726](https://github.com/Raidiant-io/notifai/commit/d6767265e4718102f7c97c6ee939073e79b038a2))
+* **cli:** stop --reply-window advertising the default it no longer has ([b9eeabc](https://github.com/Raidiant-io/notifai/commit/b9eeabcbafd9a8e84d2aa86f44b04ca4ece237f2))
+* give the detached waiter the wall clock its host already allows ([3d4b111](https://github.com/Raidiant-io/notifai/commit/3d4b111afb4d35bd8c04121deee82b849dd0ade1))
+* **hooks:** never write a Codex hooks.json Notifai does not own ([8fdd00c](https://github.com/Raidiant-io/notifai/commit/8fdd00c6018915fe2164800c5797a9c3cb92da68))
+* **hooks:** never write a Codex hooks.json Notifai does not own ([8948519](https://github.com/Raidiant-io/notifai/commit/894851942db6283ff856025e7f7d2dd86695013d))
+* **hooks:** read the duplicate-representation warning as a sentence ([e0d041f](https://github.com/Raidiant-io/notifai/commit/e0d041f729e75a4c909f41c5dfafe6602f88edeb))
+* **hooks:** read the duplicate-representation warning as a sentence ([936f068](https://github.com/Raidiant-io/notifai/commit/936f068d2587d56fc10a89a7d87c81c37ef50e2d))
+* **hooks:** report a Codex dual representation only when Notifai is in both ([f4426dc](https://github.com/Raidiant-io/notifai/commit/f4426dc6e3876ac0a75f31ce5fb81c4ec2f4719d))
+* **hooks:** report a Codex dual representation only when Notifai is in both ([2bab419](https://github.com/Raidiant-io/notifai/commit/2bab41987bf9fa251f71785b9881e3c8418be1bb))
+* **hooks:** stop rewriting the whole of a user's Codex config.toml ([e037e22](https://github.com/Raidiant-io/notifai/commit/e037e227646178a0cbc08e7a00ab47129b3b435f))
+* **hooks:** stop rewriting the whole of a user's Codex config.toml ([92ff189](https://github.com/Raidiant-io/notifai/commit/92ff1891c3f42092758af257ec3be8b68e51c0f1))
+* let a question outlive the waiter that pushed it ([de242e7](https://github.com/Raidiant-io/notifai/commit/de242e753434dda87f665de6474491320fbc7365))
+* **lock:** survive losing the rendezvous while registering ([2b5d46d](https://github.com/Raidiant-io/notifai/commit/2b5d46d5221b843fc2db5a803da561e3dbb3b7b0))
+* **lock:** survive losing the rendezvous while registering ([efb8bd6](https://github.com/Raidiant-io/notifai/commit/efb8bd6f718f9f5e7e9bda1471cb88db0a77ef4c))
+* reject an unknown --platform locally, the way send already does ([7ba7678](https://github.com/Raidiant-io/notifai/commit/7ba7678214cc3c98919ece2f533ed40f080951f3))
+* report a failed image upload like every other API failure ([be76c48](https://github.com/Raidiant-io/notifai/commit/be76c4808e6c37bb97d64b14b018b148c4887d94))
+* stop a busy session discarding the answer it was too busy to take ([13ce700](https://github.com/Raidiant-io/notifai/commit/13ce7003c393741b82886910cb51b18d0a9f1065))
+* stop a turn-ending question expiring with the waiter that pushed it ([dd2cda6](https://github.com/Raidiant-io/notifai/commit/dd2cda6a339d711bc4c6723b93ccf940207565a7))
+* stop a typed prompt erasing an outstanding acknowledgement ([ed15e18](https://github.com/Raidiant-io/notifai/commit/ed15e18fffd893ef0c5ad27bc17d4f78b0a88b6c))
+* stop several surfaces stating things that are not true ([56402b9](https://github.com/Raidiant-io/notifai/commit/56402b98b763bdce2fb75c79f8502a92968a0abb))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @raidiant/notifai-protocol bumped from 1.0.0 to 2.0.0
+
 ## [4.0.0](https://github.com/Raidiant-io/notifai/compare/v3.0.1...v4.0.0) (2026-08-15)
 
 

package/README.md

@@ -54,6 +54,11 @@ By default a question reaches your devices when the agent turn ends, whether or
 not you are at the keyboard (`ask_grace_seconds = 0`). Set a positive grace
 period for a terminal-only answer window first.
 
+When you answer, the agent acknowledges it before it does anything else, so you
+find out your reply landed and what it set in motion — not just that you sent
+it. Answering from your phone and wondering whether anything happened is the
+whole problem this solves.
+
 For a harness that cannot resume an idle agent turn, `notifai send
 --reply` blocks and waits for the answer instead.
 

package/dist/commands.d.ts

@@ -202,6 +202,8 @@ export declare function hookRunCommand(deps: CommandDeps, event: string, readStd
  */
 export declare function describeHookFailure(err: 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;
@@ -238,7 +240,14 @@ export declare function buildQuestions(flags: AskFlags, question: string | undef
  * for `ask_grace_seconds` before it reaches any device.
  */
 export declare function askCommand(deps: CommandDeps, question: string | undefined, flags: AskFlags): number | Promise<number>;
-/** 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 declare function acknowledgeCommand(deps: CommandDeps, requestId: string, flags: {
     text?: string;
     json?: boolean;

package/dist/commands.js

@@ -3,19 +3,19 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, u
 import os from 'node:os';
 import path from 'node:path';
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
-import { AGENT_ACKNOWLEDGEMENT_MAX_LENGTH, CAPABILITIES_V1, QUESTION_TEXT_MAX_LENGTH, REPLY_MAX_QUESTIONS, REPLY_MAX_WINDOW_SECONDS, validateDraft, } from '@raidiant/notifai-protocol';
+import { AGENT_ACKNOWLEDGEMENT_MAX_LENGTH, CAPABILITIES_V1, PLATFORMS, QUESTION_TEXT_MAX_LENGTH, REPLY_MAX_QUESTIONS, REPLY_MAX_WINDOW_SECONDS, validateDraft, } from '@raidiant/notifai-protocol';
 import { sha256Hex } from '@raidiant/notifai-protocol/node';
 import { ApiCallError, NetworkError, createClient, isRetryableReplyPollError, } from './client.js';
-import { BOOLEAN_CONFIG_KEYS, CONFIG_KEYS, LOG_LEVELS, NUMERIC_CONFIG_KEYS, configBounds, configDefaultValue, findProjectConfigPath, personalProjectConfigPath, globalConfigPath, loadConfig, sessionConfigPath, stateDir, } from './config.js';
+import { BOOLEAN_CONFIG_KEYS, CONFIG_KEYS, NUMERIC_CONFIG_KEYS, configBounds, configDefaultValue, findProjectConfigPath, personalProjectConfigPath, globalConfigPath, loadConfig, sessionConfigPath, stateDir, } from './config.js';
 import { acceptedValues, configInfo } from './config-schema.js';
 import { packageVersion, skillsSource } from './release.js';
 import { atomicWriteFileSync } from './atomic-file.js';
 import { withTargetFileLock } from './file-lock.js';
 import { renderConfigExplain, renderConfigList, renderConfigPlain, } from './ui/config-view.js';
 import { firstBlocker, } from './readiness.js';
-import { WAITER_CEILING_SECONDS, clearAcknowledgementObligation, handleSessionEnd, handleStop, handleUserPromptSubmit, parseHookInput, pruneAbandonedSessions, readLiveProjectSessionPointers, readMatchingProjectSessionPointer, readProjectSession, readProjectSessionPointer, readSessionState, registerQuestion, } from './hooks.js';
-import { LOG_EVENTS, activeLogPath, archiveLogPaths, logConfigResolved, logSettingsFrom, logsDiskUsage, nullLogger, readLogRecords, renderRecord, } from './logging.js';
-import { BLOCKING_STOP_TIMEOUT_SECONDS, CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS, HARNESSES, applyPlan, buildCursorHookConfig, buildHookConfig, codexLayerDir, codexLayerPaths, codexRepresentationProblems, codexTrustProblems, codexProjectRoot, detectHarness, detectedHarnesses, findInstallations, handlerEvent, hookDefinitionFiles, inspectCodexLayer, loadCursorSettings, loadSettings, mergeCursorHooks, mergeHooks, removeCursorHooks, removeHooks, settingsFile, withCodexLayerTransaction, } from './install-hooks.js';
+import { waiterCeilingSeconds, clearAcknowledgementObligation, handleSessionEnd, handleStop, handleUserPromptSubmit, parseHookInput, pruneAbandonedSessions, readLiveProjectSessionPointers, readMatchingProjectSessionPointer, readProjectSession, readProjectSessionPointer, readSessionState, registerQuestion, MIN_REPLY_WINDOW_SECONDS, } from './hooks.js';
+import { LOG_EVENTS, activeLogPath, archiveLogPaths, logConfigResolved, logSettingsFrom, logsDiskUsage, nullLogger, readLogRecords, renderRecord, RECORD_LEVELS, } from './logging.js';
+import { BLOCKING_STOP_TIMEOUT_SECONDS, stopHandlerIsDetached, CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS, HARNESSES, applyPlan, buildCursorHookConfig, buildHookConfig, codexLayerDir, codexLayerPaths, codexCoexistenceNotes, codexHomeNote, codexRepresentationProblems, codexTrustProblems, codexProjectRoot, detectHarness, detectedHarnesses, findInstallations, handlerEvent, hookDefinitionFiles, inspectCodexLayer, loadCursorSettings, loadSettings, mergeCursorHooks, mergeHooks, removeCursorHooks, removeHooks, settingsFile, withCodexLayerTransaction, } from './install-hooks.js';
 import { HARNESS_CAPABILITIES, HARNESS_LABELS } from './harnesses.js';
 import { claudeWakeRoute, inspectClaudeInbox, systemClaudeWakeAdapters, } from './claude-wake.js';
 import { codexWakeRoute, inspectCodexResume, } from './codex-wake.js';
@@ -88,7 +88,9 @@ function reportError(deps, err, context = {}) {
             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`');
         }
@@ -314,6 +316,13 @@ export function canDeviceReceive(device) {
     return deviceCanReceive(device);
 }
 export async function capabilitiesCommand(deps, flags) {
+    // 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.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);
@@ -371,6 +380,15 @@ export async function sendCommand(deps, flags) {
         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;
@@ -404,9 +422,9 @@ export async function sendCommand(deps, flags) {
     if (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);
@@ -435,7 +453,8 @@ export async function sendCommand(deps, flags) {
         }
         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);
@@ -513,6 +532,7 @@ export async function sendCommand(deps, flags) {
                     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,
@@ -629,7 +649,15 @@ export async function repliesCommand(deps, requestedId, flags) {
             .map((entry) => entry.request_id)
             .filter((id) => 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;
         }
     }
@@ -748,6 +776,7 @@ export async function waitForReply(client, requestId, options) {
                 request_id: requestId,
                 reply_expires_at: null,
                 agent_acknowledgement_required: false,
+                agent_acknowledgement_text_required: false,
                 agent_acknowledgement: null,
                 replies: [],
             },
@@ -786,9 +815,14 @@ function degradedWaitWarning(requestId) {
 function isNonNegativeInteger(value) {
     return Number.isInteger(value) && value >= 0;
 }
-function acknowledgementCommand(requestId, required, acknowledgement, hasReply = true) {
-    return required && acknowledgement === null && hasReply
+function acknowledgeInvocation(requestId, textRequired) {
+    return textRequired
         ? `notifai acknowledge ${requestId} --text <text>`
+        : `notifai acknowledge ${requestId}`;
+}
+function acknowledgementCommand(requestId, required, textRequired, acknowledgement, hasReply = true) {
+    return required && acknowledgement === null && hasReply
+        ? acknowledgeInvocation(requestId, textRequired)
         : null;
 }
 function replyResultJson(response, degraded) {
@@ -799,7 +833,8 @@ function replyResultJson(response, degraded) {
         replies: response.replies,
         agent_acknowledgement_required: response.agent_acknowledgement_required,
         agent_acknowledgement: response.agent_acknowledgement,
-        acknowledgement_command: acknowledgementCommand(response.request_id, response.agent_acknowledgement_required, response.agent_acknowledgement, response.replies.length > 0),
+        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),
         degraded,
     };
 }
@@ -808,13 +843,19 @@ function printAcknowledgementStatus(deps, response) {
         deps.io.out('Agent Acknowledgement: not required for this request.');
         return;
     }
+    const textRequired = response.agent_acknowledgement_text_required;
     if (response.agent_acknowledgement !== null) {
-        deps.io.out(`Agent Acknowledgement: recorded at ${response.agent_acknowledgement.created_at}: ${response.agent_acknowledgement.text}`);
+        const recorded = `Agent Acknowledgement: recorded at ${response.agent_acknowledgement.created_at}`;
+        deps.io.out(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.`);
+        deps.io.out(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;
     }
     deps.io.out('Agent Acknowledgement: required after a user reply; no reply is recorded yet.');
@@ -969,7 +1010,13 @@ async function uploadImage(deps, client, source) {
         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) };
     }
 }
 // ---------------------------------------------------------------------------
@@ -999,7 +1046,11 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
     // would grant slow setup a second budget and let the harness kill us before
     // an accepted answer is journaled or written to stdout.
     const now = deps.now ?? Date.now;
-    const processDeadlineAt = now() + 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}` });
     let started = false;
@@ -1179,18 +1230,8 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
         });
         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);
-                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) {
@@ -1322,7 +1363,7 @@ export function buildQuestions(flags, question) {
             };
         }
         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;
         const unknownKeys = Object.keys(record).filter((key) => key !== 'questions' && key !== 'body');
@@ -1333,7 +1374,7 @@ export function buildQuestions(flags, question) {
             };
         }
         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) {
@@ -1438,7 +1479,7 @@ function buildAskDraft(config, built, flags, invocation, mediaIds) {
     }
     return { ok: true, draft: result.draft };
 }
-function recordRegisteredQuestion(deps, sessionId, built, draft) {
+function recordRegisteredQuestion(deps, sessionId, built, draft, json = false) {
     try {
         registerQuestion(sessionId, deps.env, {
             question: built.questions[0].text,
@@ -1462,6 +1503,28 @@ function recordRegisteredQuestion(deps, sessionId, built, draft) {
         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) {
@@ -1504,7 +1567,8 @@ async function uploadAskMedia(deps, config, sessionId, built, flags, invocation)
         }
         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);
@@ -1514,7 +1578,7 @@ async function uploadAskMedia(deps, config, sessionId, built, flags, invocation)
         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);
 }
 /**
  * Registers a question for turn-end routing. Returns immediately so the agent
@@ -1615,7 +1679,7 @@ export function askCommand(deps, question, flags) {
     if ((flags.image?.length ?? 0) > 0) {
         return uploadAskMedia(deps, routingConfig, sessionId, built, flags, source.invocation);
     }
-    return recordRegisteredQuestion(deps, sessionId, built, preflight.draft);
+    return recordRegisteredQuestion(deps, sessionId, built, preflight.draft, flags.json === true);
 }
 /**
  * Every harness marker present in this environment, in declared order.
@@ -1814,15 +1878,22 @@ function hookActivationAdvice(installations) {
     }
     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, requestId, flags) {
     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.`);
+        deps.io.err(`--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;
     }
     const logger = log(deps);
@@ -1836,7 +1907,7 @@ export async function acknowledgeCommand(deps, requestId, flags) {
     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,
@@ -1876,7 +1947,7 @@ export async function closeCommand(deps, requestId, flags = {}) {
         if (flags.json) {
             deps.io.out(JSON.stringify({
                 ...response,
-                acknowledgement_command: acknowledgementCommand(response.request_id, response.agent_acknowledgement_required, response.agent_acknowledgement, response.replies.length > 0),
+                acknowledgement_command: acknowledgementCommand(response.request_id, response.agent_acknowledgement_required, response.agent_acknowledgement_text_required, response.agent_acknowledgement, response.replies.length > 0),
             }, null, 2));
         }
         else {
@@ -1934,7 +2005,7 @@ export function hooksInstallCommand(deps, flags) {
     if (flags.harness === undefined) {
         const detected = detectedHarnesses(deps.cwd, deps.env);
         if (detected.length === 0) {
-            deps.io.err(`Could not tell which harness to install for — pass --harness <${HARNESSES.join('|')}>.`);
+            deps.io.err(`Could not tell which harness you mean — pass --harness <${HARNESSES.join('|')}>.`);
             return EXIT.usage;
         }
         let ok = true;
@@ -2043,6 +2114,14 @@ export function hooksInstallCommand(deps, flags) {
         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;
 }
@@ -2195,12 +2274,6 @@ function assertOwnedRegularFile(file) {
         throw new Error(`${file} is owned by uid ${stat.uid}, not the current user.`);
     }
 }
-const HARNESS_LABEL = {
-    'claude-code': 'Claude Code',
-    codex: 'Codex',
-    cursor: 'Cursor',
-    opencode: 'OpenCode',
-};
 function resolveHarness(deps, requested) {
     if (requested !== undefined) {
         if (HARNESSES.includes(requested))
@@ -2231,7 +2304,7 @@ async function pickHarnessesToInstall(deps, requested) {
     if (deps.io.interactive === true && deps.io.multiselect) {
         const picked = await deps.io.multiselect('Which agent harnesses should Notifai wire here?', HARNESSES.map((name) => ({
             value: name,
-            label: HARNESS_LABEL[name],
+            label: HARNESS_LABELS[name],
             ...(detected.includes(name) ? { hint: 'detected on this machine' } : {}),
         })), detected);
         if (picked === null)
@@ -2617,8 +2690,8 @@ export function logsCommand(deps, flags) {
         query.since = since;
     }
     if (flags.level !== undefined) {
-        if (!LOG_LEVELS.includes(flags.level)) {
-            deps.io.err(`--level takes one of: ${LOG_LEVELS.join(', ')} — not "${flags.level}".`);
+        if (!RECORD_LEVELS.includes(flags.level)) {
+            deps.io.err(`--level takes one of: ${RECORD_LEVELS.join(', ')} — not "${flags.level}".`);
             return EXIT.usage;
         }
         query.level = flags.level;
@@ -3349,7 +3422,9 @@ async function printInitClose(deps, readiness, flags) {
             ];
             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;
         }
@@ -3364,7 +3439,9 @@ async function printInitClose(deps, readiness, flags) {
     }
     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}`);
@@ -3893,14 +3970,39 @@ function hookStates(deps) {
             settings,
         ];
     }
+    /**
+     * 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 = {
+        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) {
+        return CHECK_TITLES[name] ?? name;
+    }
     /** Real but not in the way; see the note above. */
     const informational = new Set();
     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'
                 : check.informational === true || informational.has(check.name)
@@ -3945,7 +4047,7 @@ function stopShapeProblems(installation, platform = process.platform) {
         return [];
     const problems = [];
     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`);
             }
@@ -3987,7 +4089,7 @@ function hookChecks(deps) {
             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',
@@ -4123,6 +4225,20 @@ function hookChecks(deps) {
             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) {
         const admissionProblems = activeQuestionRouteProblems(deps, active, installations);
         checks.push({