@raidiant/notifai 3.0.1 → 5.0.0

package/dist/commands.js

@@ -3,25 +3,26 @@ 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';
 import { inspectHookAdapter, installHookAdapter, isNpxAdapterTarget, } from './hook-adapter.js';
 import { isOurOpencodePlugin, opencodePluginSource, } from './opencode-plugin.js';
-import { CHOICE_USAGE, buildDraft, formatReceipt, parseChoices, receiptExitCode, slugify, } from './send.js';
+import { CHOICE_USAGE, buildDraft, formatReceipt, parseChoices, receiptExitCode, slugify, validateMediaInputs, } from './send.js';
+import { buildSourceContext, inferInvocationContext, projectSlugFrom as inferredProjectSlugFrom, } from './invocation-context.js';
 import { openUrl } from './platform.js';
 /** The invocation's logger, or one that discards everything. */
 export function log(deps) {
@@ -79,6 +80,20 @@ function reportError(deps, err, context = {}) {
     });
     if (err instanceof ApiCallError) {
         deps.io.err(`${err.code}: ${err.message}`);
+        // The server's field-level details were already being logged above, but
+        // stderr is the one surface an agent's next turn actually reads — so the
+        // diagnosis has to be on it, the same way the hook path prints it.
+        const paths = rejectedPaths(err.details);
+        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.
+        // 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`');
+        }
         if (err.nextAction)
             deps.io.err(`next: ${err.nextAction}`);
         if (err.code === 'auth_required' || err.code === 'machine_revoked')
@@ -301,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);
@@ -324,12 +346,51 @@ export async function capabilitiesCommand(deps, flags) {
 // ---------------------------------------------------------------------------
 // send / status
 // ---------------------------------------------------------------------------
+function resolveDraftInvocation(deps, flags, active) {
+    const inferred = inferInvocationContext(deps.cwd);
+    const source = buildSourceContext({
+        env: deps.env,
+        invocation: inferred,
+        ...(flags.sessionId !== undefined ? { sessionId: flags.sessionId } : {}),
+        ...(flags.sessionLabel !== undefined ? { sessionLabel: flags.sessionLabel } : {}),
+        ...(active === null
+            ? {}
+            : {
+                activeHarness: {
+                    harness: active.harness,
+                    ...(active.sessionId === undefined ? {} : { sessionId: active.sessionId }),
+                },
+            }),
+    });
+    if (!source.ok)
+        return source;
+    return {
+        ok: true,
+        invocation: {
+            inferredProject: inferred.project,
+            ...(source.source === undefined ? {} : { source: source.source }),
+        },
+    };
+}
 export async function sendCommand(deps, flags) {
     const hasReplyChoice = Array.isArray(flags.replyChoice)
         ? flags.replyChoice.length > 0
         : flags.replyChoice !== undefined;
-    if (flags.reply && flags.kind === 'done') {
-        deps.io.err('--kind done cannot be combined with --reply; a reply request is a question.');
+    if (flags.reply && flags.kind !== undefined && flags.kind !== 'question') {
+        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;
     }
     if (!flags.reply &&
@@ -361,9 +422,14 @@ 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);
+    if (mediaInputError !== null) {
+        deps.io.err(mediaInputError);
         return EXIT.usage;
     }
     const config = loadLoggedConfig(deps, {
@@ -371,18 +437,30 @@ export async function sendCommand(deps, flags) {
         env: deps.env,
         flags: { base_url: flags.baseUrl, wait_seconds: flags.wait },
     });
+    const source = resolveDraftInvocation(deps, flags, activeHarnessSession(deps.env, deps.cwd, (deps.now ?? Date.now)()));
+    if (!source.ok) {
+        deps.io.err(source.error);
+        return EXIT.usage;
+    }
     const authed = authedClient(deps, config);
     if (!authed)
         return EXIT.auth;
-    if (flags.image !== undefined && !flags.image.startsWith('med_')) {
-        const uploaded = await uploadImage(deps, authed.client, flags.image);
+    const mediaIds = [];
+    for (const image of flags.image ?? []) {
+        if (image.startsWith('med_')) {
+            mediaIds.push(image);
+            continue;
+        }
+        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;
         }
-        flags = { ...flags, image: uploaded.mediaId };
+        mediaIds.push(uploaded.mediaId);
     }
-    const build = buildDraft(config, flags);
+    flags = { ...flags, image: mediaIds };
+    const build = buildDraft(config, flags, source.invocation);
     if (!build.ok) {
         deps.io.err(build.error);
         return EXIT.usage;
@@ -454,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,
@@ -529,12 +608,8 @@ function emitSendWarnings(deps, flags, config) {
     if (flags.title.length > 40) {
         deps.io.err(`Heads up: this title is ${flags.title.length} characters; notification titles work best around 40 characters or fewer.`);
     }
-    if (looksLikeMarkdown(flags.body)) {
-        deps.io.err('Heads up: --body looks like Markdown, but banners show plain text. Put long-form Markdown in --detail or --detail-file.');
-    }
-    const effectiveKind = flags.reply ? 'question' : (flags.kind ?? 'update');
-    if (effectiveKind === 'update' && /^(done|failed)\b/i.test(flags.title.trim())) {
-        deps.io.err(`Heads up: this title announces completion but the notification kind is update. Use --kind done for finished work.`);
+    if (/^(?:update|done|question|failed|blocked)\s*(?:[·:—-]|$)/i.test(flags.title.trim())) {
+        deps.io.err('Heads up: keep the title to the specific substance. Put notification type in --kind; project identity is inferred separately.');
     }
     if (flags.collapseKey === undefined &&
         config.collapse_key.value !== null &&
@@ -545,9 +620,6 @@ function emitSendWarnings(deps, flags, config) {
         deps.io.err('Heads up: this explicit --ttl is longer than 72 hours; stale notifications may arrive after they are useful.');
     }
 }
-function looksLikeMarkdown(value) {
-    return /(?:^|\n)\s{0,3}(?:#{1,6}\s|[-+*]\s|>\s|\d+\.\s|```)|(?:\*\*|__|~~|`)[^\n]+(?:\*\*|__|~~|`)|\[[^\]]+\]\([^)]+\)/m.test(value);
-}
 export async function repliesCommand(deps, requestedId, flags) {
     const waitSeconds = flags.wait ?? 0;
     const afterSeq = flags.after ?? 0;
@@ -577,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;
         }
     }
@@ -696,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: [],
             },
@@ -734,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) {
@@ -747,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,
     };
 }
@@ -756,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.');
@@ -917,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) };
     }
 }
 // ---------------------------------------------------------------------------
@@ -947,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;
@@ -1127,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) {
@@ -1251,9 +1344,8 @@ function rejectedPaths(details) {
         .slice(0, 5);
 }
 /**
- * Turn ask input into the question set that will ride the push. Everything is
- * validated here, at registration, because the push happens inside a hook
- * where a rejection becomes a stderr note the agent never reads.
+ * Turn ask input into questions plus their canonical body. Everything is
+ * validated at registration because a later hook failure is easy to miss.
  */
 export function buildQuestions(flags, question) {
     if (flags.form !== undefined) {
@@ -1265,21 +1357,41 @@ export function buildQuestions(flags, question) {
             parsed = JSON.parse(flags.form);
         }
         catch {
-            return { ok: false, error: '--form must be JSON: {"questions": [{"text", "choices"?, "multi"?}], "detail"?}.' };
+            return {
+                ok: false,
+                error: '--form must be JSON: {"questions": [{"text", "choices"?, "multi"?}], "body"?}.',
+            };
         }
-        if (typeof parsed !== 'object' || parsed === null || !Array.isArray(parsed.questions)) {
-            return { ok: false, error: '--form needs a "questions" array (1-4 entries).' };
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            return { ok: false, error: `--form needs a "questions" array (1-${REPLY_MAX_QUESTIONS} entries).` };
         }
-        const form = parsed;
-        if (form.questions.length < 1 || form.questions.length > REPLY_MAX_QUESTIONS) {
-            return { ok: false, error: `A form asks 1-${REPLY_MAX_QUESTIONS} questions; this one has ${form.questions.length}.` };
+        const record = parsed;
+        const unknownKeys = Object.keys(record).filter((key) => key !== 'questions' && key !== 'body');
+        if (unknownKeys.length > 0) {
+            return {
+                ok: false,
+                error: `Unknown --form ${unknownKeys.length === 1 ? 'key' : 'keys'}: ${unknownKeys.join(', ')}. Use "body" for Markdown context.`,
+            };
+        }
+        if (!Array.isArray(record['questions'])) {
+            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) {
+            return {
+                ok: false,
+                error: `A form asks 1-${REPLY_MAX_QUESTIONS} questions; this one has ${formQuestions.length}.`,
+            };
         }
-        if (form.detail !== undefined && typeof form.detail !== 'string') {
-            return { ok: false, error: '"detail" must be a markdown string.' };
+        if (record['body'] !== undefined && typeof record['body'] !== 'string') {
+            return { ok: false, error: '"body" must be a Markdown string.' };
+        }
+        if (flags.body !== undefined && record['body'] !== undefined) {
+            return { ok: false, error: 'Pass form context in either --body or the form "body" key, not both.' };
         }
         const questions = [];
         const usedIds = new Set();
-        for (const [index, entry] of form.questions.entries()) {
+        for (const [index, entry] of formQuestions.entries()) {
             if (typeof entry !== 'object' || entry === null || typeof entry.text !== 'string') {
                 return { ok: false, error: `Question ${index + 1} needs a "text" string.` };
             }
@@ -1289,7 +1401,15 @@ export function buildQuestions(flags, question) {
                 return { ok: false, error: `Question ${index + 1}: ${built.error}` };
             questions.push(built.question);
         }
-        return { ok: true, questions, ...(form.detail !== undefined ? { detail: form.detail } : {}) };
+        const context = flags.body ?? record['body'];
+        const questionBlock = questions.map((entry, index) => `${index + 1}. ${entry.text}`).join('\n');
+        return {
+            ok: true,
+            questions,
+            body: context !== undefined && context.trim() !== ''
+                ? `${questionBlock}\n\n${context}`
+                : questionBlock,
+        };
     }
     if (question === undefined || question.trim() === '') {
         return { ok: false, error: 'The question cannot be empty.' };
@@ -1297,10 +1417,13 @@ export function buildQuestions(flags, question) {
     const built = buildOneQuestion(question, flags.choice, flags.multi === true, 0, new Set());
     if ('error' in built)
         return { ok: false, error: built.error };
+    const context = flags.body;
     return {
         ok: true,
         questions: [built.question],
-        ...(flags.detail !== undefined && flags.detail.trim() !== '' ? { detail: flags.detail } : {}),
+        body: context !== undefined && context.trim() !== ''
+            ? `${built.question.text}\n\n${context}`
+            : built.question.text,
     };
 }
 function buildOneQuestion(text, choiceLabels, multi, index, usedIds) {
@@ -1310,7 +1433,7 @@ function buildOneQuestion(text, choiceLabels, multi, index, usedIds) {
     if (trimmed.length > QUESTION_TEXT_MAX_LENGTH) {
         return {
             error: `a question must be readable where it is answered: keep it within ` +
-                `${QUESTION_TEXT_MAX_LENGTH} characters and put the longer context in detail.`,
+                `${QUESTION_TEXT_MAX_LENGTH} characters and put the longer context in --body.`,
         };
     }
     const choices = parseChoices(choiceLabels);
@@ -1332,6 +1455,131 @@ function buildOneQuestion(text, choiceLabels, multi, index, usedIds) {
         },
     };
 }
+function buildAskDraft(config, built, flags, invocation, mediaIds) {
+    const result = buildDraft(config, {
+        title: built.questions[0].text,
+        body: built.body,
+        ...(flags.project !== undefined ? { project: flags.project } : {}),
+        ...(mediaIds.length > 0 ? { image: mediaIds } : {}),
+        ...(flags.imageAlt !== undefined ? { imageAlt: flags.imageAlt } : {}),
+        reply: true,
+        questions: built.questions,
+    }, invocation);
+    if (!result.ok)
+        return result;
+    const capabilities = CAPABILITIES_V1.describe(result.platform);
+    if (capabilities === null)
+        return { ok: false, error: 'No iOS capability contract is available.' };
+    const validation = validateDraft(result.draft, capabilities);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            error: validation.errors.map((issue) => `${issue.path}: ${issue.message}`).join('\n'),
+        };
+    }
+    return { ok: true, draft: result.draft };
+}
+function recordRegisteredQuestion(deps, sessionId, built, draft, json = false) {
+    try {
+        registerQuestion(sessionId, deps.env, {
+            question: built.questions[0].text,
+            questions: built.questions,
+            body: draft.presentation.body,
+            ...(draft.project !== undefined ? { project: draft.project } : {}),
+            ...(draft.source !== undefined ? { source: draft.source } : {}),
+            ...(draft.presentation.media !== undefined ? { media: draft.presentation.media } : {}),
+        }, (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;
+    }
+    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,
+        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) {
+            const kind = entry.multi === true ? 'answers offered (several may be chosen)' : 'answers offered';
+            deps.io.out(`${prefix}${entry.text} — ${kind}: ${entry.choices.map((choice) => choice.label).join(' / ')}`);
+        }
+        else if (built.questions.length > 1) {
+            deps.io.out(`${prefix}${entry.text} — free text`);
+        }
+    }
+    deps.io.out(built.questions.length > 1
+        ? `${built.questions.length} questions registered as one form. Ask them in the conversation, state the concrete work you will resume for their answers, then end your turn.`
+        : 'Question registered. Ask it in the conversation, state the concrete work you will resume when the answer arrives, then end your turn.');
+    deps.io.out('Before ending this turn, pre-commit in your own words to the work you will resume:');
+    for (const [index, entry] of built.questions.entries()) {
+        const questionPrefix = built.questions.length > 1 ? `Question ${index + 1}, ` : '';
+        if (entry.choices !== undefined) {
+            for (const choice of entry.choices) {
+                deps.io.out(`- ${questionPrefix}If the answer is ${JSON.stringify(choice.label)}: state the concrete work you will resume.`);
+            }
+            deps.io.out(`- ${questionPrefix}For an unexpected typed answer: state how it will determine the concrete work you resume.`);
+        }
+        else {
+            deps.io.out(`- ${questionPrefix}For the free-text answer: state how its content will determine the concrete work you resume.`);
+        }
+    }
+    deps.io.out('When the answer arrives, resume the matching work without asking the user to confirm again. Frame this as work you will resume, not as approval you receive.');
+    deps.io.out('A Notifai answer cannot answer a harness permission prompt or interactive picker; leave those to the harness and user.');
+    return EXIT.ok;
+}
+async function uploadAskMedia(deps, config, sessionId, built, flags, invocation) {
+    const authed = authedClient(deps, config);
+    if (!authed)
+        return EXIT.auth;
+    const mediaIds = [];
+    for (const image of flags.image ?? []) {
+        if (image.startsWith('med_')) {
+            mediaIds.push(image);
+            continue;
+        }
+        const uploaded = await uploadImage(deps, authed.client, image);
+        if (!uploaded.ok) {
+            if (uploaded.error !== null)
+                deps.io.err(uploaded.error);
+            return uploaded.exit;
+        }
+        mediaIds.push(uploaded.mediaId);
+    }
+    const ready = buildAskDraft(config, built, flags, invocation, mediaIds);
+    if (!ready.ok) {
+        deps.io.err(ready.error);
+        return EXIT.usage;
+    }
+    return recordRegisteredQuestion(deps, sessionId, built, ready.draft, flags.json === true);
+}
 /**
  * Registers a question for turn-end routing. Returns immediately so the agent
  * can ask in prose and end its turn; the terminal keeps the question to itself
@@ -1346,6 +1594,11 @@ export function askCommand(deps, question, flags) {
         deps.io.err(built.error);
         return EXIT.usage;
     }
+    const mediaInputError = validateMediaInputs(flags.image, flags.imageAlt);
+    if (mediaInputError !== null) {
+        deps.io.err(mediaInputError);
+        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.');
@@ -1383,10 +1636,6 @@ export function askCommand(deps, question, flags) {
             }
             return EXIT.usage;
         }
-        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)
@@ -1410,57 +1659,27 @@ export function askCommand(deps, question, flags) {
             deps.io.err(line);
         return EXIT.usage;
     }
-    try {
-        registerQuestion(sessionId, deps.env, {
-            question: built.questions[0].text,
-            questions: built.questions,
-            ...(built.detail !== undefined ? { detail: built.detail } : {}),
-        }, (deps.now ?? Date.now)());
+    const source = resolveDraftInvocation(deps, flags, active);
+    if (!source.ok) {
+        deps.io.err(source.error);
+        return EXIT.usage;
     }
-    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;
+    if (source.invocation.source?.session_id !== sessionId) {
+        deps.io.err(`Question routing is not ready: --session-id or NOTIFAI_SESSION_ID does not match the exact active ${active.label} session; refusing cross-session routing.`);
+        return EXIT.usage;
     }
-    // `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) {
-            const kind = entry.multi === true ? 'answers offered (several may be chosen)' : 'answers offered';
-            deps.io.out(`${prefix}${entry.text} — ${kind}: ${entry.choices.map((choice) => choice.label).join(' / ')}`);
-        }
-        else if (built.questions.length > 1) {
-            deps.io.out(`${prefix}${entry.text} — free text`);
-        }
+    // Placeholders let every body, source, project, media, and payload limit fail
+    // before an upload starts. The real ids replace them only after this passes.
+    const placeholders = (flags.image ?? []).map((_, index) => `med_pending_${index + 1}`);
+    const preflight = buildAskDraft(routingConfig, built, flags, source.invocation, placeholders);
+    if (!preflight.ok) {
+        deps.io.err(preflight.error);
+        return EXIT.usage;
     }
-    deps.io.out(built.questions.length > 1
-        ? `${built.questions.length} questions registered as one form. Ask them in the conversation, state the concrete work you will resume for their answers, then end your turn.`
-        : 'Question registered. Ask it in the conversation, state the concrete work you will resume when the answer arrives, then end your turn.');
-    deps.io.out('Before ending this turn, pre-commit in your own words to the work you will resume:');
-    for (const [index, entry] of built.questions.entries()) {
-        const questionPrefix = built.questions.length > 1 ? `Question ${index + 1}, ` : '';
-        if (entry.choices !== undefined) {
-            for (const choice of entry.choices) {
-                deps.io.out(`- ${questionPrefix}If the answer is ${JSON.stringify(choice.label)}: state the concrete work you will resume.`);
-            }
-            deps.io.out(`- ${questionPrefix}For an unexpected typed answer: state how it will determine the concrete work you resume.`);
-        }
-        else {
-            deps.io.out(`- ${questionPrefix}For the free-text answer: state how its content will determine the concrete work you resume.`);
-        }
+    if ((flags.image?.length ?? 0) > 0) {
+        return uploadAskMedia(deps, routingConfig, sessionId, built, flags, source.invocation);
     }
-    deps.io.out('When the answer arrives, resume the matching work without asking the user to confirm again. Frame this as work you will resume, not as approval you receive.');
-    deps.io.out('A Notifai answer cannot answer a harness permission prompt or interactive picker; leave those to the harness and user.');
-    return EXIT.ok;
+    return recordRegisteredQuestion(deps, sessionId, built, preflight.draft, flags.json === true);
 }
 /**
  * Every harness marker present in this environment, in declared order.
@@ -1659,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);
@@ -1681,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,
@@ -1721,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 {
@@ -1779,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;
@@ -1888,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;
 }
@@ -2040,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))
@@ -2076,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)
@@ -2462,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;
@@ -2599,14 +2827,9 @@ async function skillReadiness(deps, selectedScope) {
         },
     };
 }
-/** Derive a contract-valid project slug from a directory name. */
+/** Derive a contract-valid project slug; init alone needs a non-empty fallback. */
 export function projectSlugFrom(name) {
-    const slug = name
-        .toLowerCase()
-        .replaceAll(/[^a-z0-9._-]+/g, '-')
-        .replaceAll(/^[^a-z0-9]+|[^a-z0-9._-]+$/g, '')
-        .slice(0, 64);
-    return slug.length > 0 && /^[a-z0-9]/.test(slug) ? slug : 'project';
+    return inferredProjectSlugFrom(name) ?? 'project';
 }
 /** Long enough for a first TestFlight install; keep-waiting extends another budget. */
 const DEVICE_BRIDGE_TIMEOUT_MS = 10 * 60 * 1000;
@@ -3199,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;
         }
@@ -3214,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}`);
@@ -3265,29 +3492,40 @@ async function contractCheck(client) {
     }
 }
 function projectReadiness(deps, config) {
-    const configPath = path.join(deps.cwd, '.notifai', 'config.toml');
-    const projectSlug = config.project.value;
-    return projectSlug !== null
-        ? {
+    const configured = config.project.value;
+    if (configured !== null) {
+        return {
             id: 'project',
             title: 'Project identity',
             status: 'ready',
-            detail: `"${projectSlug}" (${config.project.source})`,
-        }
-        : {
+            detail: `"${configured}" (${config.project.source})`,
+        };
+    }
+    const inferred = inferInvocationContext(deps.cwd).project;
+    if (inferred !== null) {
+        return {
             id: 'project',
             title: 'Project identity',
-            // Not a blocker: a send without a project simply carries no project
-            // identity. init always sets one because it is free and reversible,
-            // but an unlabelled setup works, so this must not go red.
             status: 'optional-gap',
-            detail: `not set in ${configPath} — sends from here carry no project identity`,
+            detail: `"${inferred}" is inferred for each send; init can stamp it into shared config`,
             remedy: {
                 by: 'cli',
-                summary: 'name this project after its directory',
+                summary: 'make the inferred Project identity explicit for every checkout',
                 command: 'notifai init',
             },
         };
+    }
+    return {
+        id: 'project',
+        title: 'Project identity',
+        status: 'optional-gap',
+        detail: 'the directory name has no characters a Project identifier can use',
+        remedy: {
+            by: 'cli',
+            summary: 'choose an explicit Project identifier',
+            command: 'notifai init --project-id my-project',
+        },
+    };
 }
 function remoteStatesFrom(previous) {
     const pick = (id) => previous.states.find((state) => state.id === id);
@@ -3732,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)
@@ -3784,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`);
             }
@@ -3826,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',
@@ -3962,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({