@raidiant/notifai 3.0.1 → 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,
@@ -13,6 +14,7 @@ import {
   type EvidenceSnapshot,
   type AccountAccessResponse,
   type ListRepliesResponse,
+  type NotificationDraftT,
   type Platform,
   type QuestionT,
   type ReplyView,
@@ -31,7 +33,6 @@ import {
 import {
   BOOLEAN_CONFIG_KEYS,
   CONFIG_KEYS,
-  LOG_LEVELS,
   NUMERIC_CONFIG_KEYS,
   configBounds,
   configDefaultValue,
@@ -65,7 +66,7 @@ import {
 } from './readiness.js'
 import type { Tone } from './ui/theme.js'
 import {
-  WAITER_CEILING_SECONDS,
+  waiterCeilingSeconds,
   clearAcknowledgementObligation,
   handleSessionEnd,
   handleStop,
@@ -81,6 +82,7 @@ import {
   type EscalationDeliveryRoute,
   type HookContext,
   type HookHarness,
+  MIN_REPLY_WINDOW_SECONDS,
 } from './hooks.js'
 import {
   LOG_EVENTS,
@@ -94,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,
@@ -104,6 +108,8 @@ import {
   buildHookConfig,
   codexLayerDir,
   codexLayerPaths,
+  codexCoexistenceNotes,
+  codexHomeNote,
   codexRepresentationProblems,
   codexTrustProblems,
   codexProjectRoot,
@@ -153,8 +159,15 @@ import {
   parseChoices,
   receiptExitCode,
   slugify,
+  validateMediaInputs,
+  type DraftInvocation,
   type SendFlags,
 } from './send.js'
+import {
+  buildSourceContext,
+  inferInvocationContext,
+  projectSlugFrom as inferredProjectSlugFrom,
+} from './invocation-context.js'
 import type { NativeSkill, NativeSkills, SkillScope } from './native-skills.js'
 import { openUrl } from './platform.js'
 
@@ -304,6 +317,21 @@ function reportError(
   })
   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') return EXIT.auth
     return err.status >= 500 ? EXIT.network : EXIT.failed
@@ -544,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)
@@ -568,6 +603,36 @@ export async function capabilitiesCommand(
 // send / status
 // ---------------------------------------------------------------------------
 
+function resolveDraftInvocation(
+  deps: CommandDeps,
+  flags: Pick<SendFlags, 'sessionId' | 'sessionLabel'>,
+  active: ActiveHarnessSession | null,
+): { ok: true; invocation: DraftInvocation } | { ok: false; error: string } {
+  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: CommandDeps,
   flags: SendFlags & {
@@ -583,8 +648,23 @@ export async function sendCommand(
   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 (
@@ -621,10 +701,17 @@ 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)
+  if (mediaInputError !== null) {
+    deps.io.err(mediaInputError)
     return EXIT.usage
   }
   const config = loadLoggedConfig(deps, {
@@ -632,17 +719,32 @@ export async function sendCommand(
     env: deps.env,
     flags: { base_url: flags.baseUrl, wait_seconds: flags.wait } as FlagOverrides,
   })
+  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: string[] = []
+  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
@@ -719,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,
@@ -805,15 +908,9 @@ function emitSendWarnings(
       `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())) {
+  if (/^(?:update|done|question|failed|blocked)\s*(?:[·:—-]|$)/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.`,
+      'Heads up: keep the title to the specific substance. Put notification type in --kind; project identity is inferred separately.',
     )
   }
   if (
@@ -832,12 +929,6 @@ function emitSendWarnings(
   }
 }
 
-function looksLikeMarkdown(value: string): boolean {
-  return /(?:^|\n)\s{0,3}(?:#{1,6}\s|[-+*]\s|>\s|\d+\.\s|```)|(?:\*\*|__|~~|`)[^\n]+(?:\*\*|__|~~|`)|\[[^\]]+\]\([^)]+\)/m.test(
-    value,
-  )
-}
-
 export async function repliesCommand(
   deps: CommandDeps,
   requestedId: string | undefined,
@@ -872,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
     }
   }
@@ -1008,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),
@@ -1050,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
 }
 
@@ -1069,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,
     ),
@@ -1084,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
   }
@@ -1233,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> {
@@ -1268,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) }
   }
 }
 
@@ -1311,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}` })
@@ -1504,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
@@ -1637,14 +1749,20 @@ 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
-  /** Long-form markdown context; shown in the app, never on the banner. */
-  detail?: string
+  /** Optional Markdown context appended after the question block. */
+  body?: string
   /** Raw JSON for a multi-question form; replaces the positional question. */
   form?: string
-  session?: string
+  image?: string[]
+  imageAlt?: string[]
+  project?: string
+  sessionId?: string
+  sessionLabel?: string
 }
 
 /** The `--form` document: what an agent writes to ask several things at once. */
@@ -1654,15 +1772,20 @@ interface AskFormQuestion {
   multi?: boolean
 }
 
+export interface BuiltQuestions {
+  questions: QuestionT[]
+  /** Canonical Markdown body: question block first, optional context second. */
+  body: string
+}
+
 /**
- * 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: AskFlags,
   question: string | undefined,
-): { ok: true; questions: QuestionT[]; detail?: string } | { ok: false; error: string } {
+): { ok: true; questions: QuestionT[]; body: string } | { ok: false; error: string } {
   if (flags.form !== undefined) {
     if (question !== undefined || flags.choice?.length || flags.multi) {
       return { ok: false, error: '--form replaces the positional question, --choice, and --multi.' }
@@ -1671,21 +1794,41 @@ export function buildQuestions(
     try {
       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)) {
+      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')
+    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).` }
     }
-    if (typeof parsed !== 'object' || parsed === null || !Array.isArray((parsed as { questions?: unknown }).questions)) {
-      return { ok: false, error: '--form needs a "questions" array (1-4 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}.`,
+      }
     }
-    const form = parsed as { questions: unknown[]; detail?: unknown }
-    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}.` }
+    if (record['body'] !== undefined && typeof record['body'] !== 'string') {
+      return { ok: false, error: '"body" must be a Markdown string.' }
     }
-    if (form.detail !== undefined && typeof form.detail !== 'string') {
-      return { ok: false, error: '"detail" 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: QuestionT[] = []
     const usedIds = new Set<string>()
-    for (const [index, entry] of form.questions.entries()) {
+    for (const [index, entry] of formQuestions.entries()) {
       if (typeof entry !== 'object' || entry === null || typeof (entry as AskFormQuestion).text !== 'string') {
         return { ok: false, error: `Question ${index + 1} needs a "text" string.` }
       }
@@ -1694,7 +1837,16 @@ export function buildQuestions(
       if ('error' in built) 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'] as string | undefined)
+    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() === '') {
@@ -1702,10 +1854,14 @@ export function buildQuestions(
   }
   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,
   }
 }
 
@@ -1722,7 +1878,7 @@ function buildOneQuestion(
     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)
@@ -1743,12 +1899,186 @@ function buildOneQuestion(
   }
 }
 
+function buildAskDraft(
+  config: CliConfig,
+  built: BuiltQuestions,
+  flags: AskFlags,
+  invocation: DraftInvocation,
+  mediaIds: string[],
+): { ok: true; draft: NotificationDraftT } | { ok: false; error: string } {
+  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: CommandDeps,
+  sessionId: string,
+  built: BuiltQuestions,
+  draft: NotificationDraftT,
+  json = false,
+): number {
+  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: CommandDeps,
+  config: CliConfig,
+  sessionId: string,
+  built: BuiltQuestions,
+  flags: AskFlags,
+  invocation: DraftInvocation,
+): Promise<number> {
+  const authed = authedClient(deps, config)
+  if (!authed) return EXIT.auth
+  const mediaIds: string[] = []
+  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
  * for `ask_grace_seconds` before it reaches any device.
  */
-export function askCommand(deps: CommandDeps, question: string | undefined, flags: AskFlags): number {
+export function askCommand(
+  deps: CommandDeps,
+  question: string | undefined,
+  flags: AskFlags,
+): number | Promise<number> {
   // Validate before route discovery. A malformed question belongs to the
   // caller and should not be hidden behind whichever harness setup issue
   // happens to exist on this machine.
@@ -1757,6 +2087,11 @@ export function askCommand(deps: CommandDeps, question: string | undefined, flag
     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(
@@ -1816,12 +2151,6 @@ export function askCommand(deps: CommandDeps, question: string | undefined, flag
       }
       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) deps.io.err(`Question routing is not ready: ${problem}`)
@@ -1845,71 +2174,37 @@ export function askCommand(deps: CommandDeps, question: string | undefined, flag
     for (const line of diagnoseMissingSession(deps)) 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
+  }
+  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.`,
     )
-  } 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
+    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)
 }
 
 /**
@@ -2187,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
   }
@@ -2215,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,
@@ -2264,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,
             ),
@@ -2342,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
@@ -2467,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
 }
@@ -2632,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
@@ -2675,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,
@@ -3148,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
@@ -3294,14 +3600,9 @@ async function skillReadiness(
   }
 }
 
-/** 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: string): string {
-  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'
 }
 
 export interface InitFlags {
@@ -4036,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
     }
@@ -4052,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}`)
@@ -4106,29 +4415,40 @@ async function contractCheck(client: ApiClient): Promise<{ name: string; ok: boo
 }
 
 function projectReadiness(deps: CommandDeps, config: CliConfig): ReadinessState {
-  const configPath = path.join(deps.cwd, '.notifai', 'config.toml')
-  const projectSlug = config.project.value
-  return projectSlug !== null
-    ? {
-        id: 'project',
-        title: 'Project identity',
-        status: 'ready',
-        detail: `"${projectSlug}" (${config.project.source})`,
-      }
-    : {
-        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`,
-        remedy: {
-          by: 'cli',
-          summary: 'name this project after its directory',
-          command: 'notifai init',
-        },
-      }
+  const configured = config.project.value
+  if (configured !== null) {
+    return {
+      id: 'project',
+      title: 'Project identity',
+      status: 'ready',
+      detail: `"${configured}" (${config.project.source})`,
+    }
+  }
+  const inferred = inferInvocationContext(deps.cwd).project
+  if (inferred !== null) {
+    return {
+      id: 'project',
+      title: 'Project identity',
+      status: 'optional-gap',
+      detail: `"${inferred}" is inferred for each send; init can stamp it into shared config`,
+      remedy: {
+        by: 'cli',
+        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: Readiness): {
@@ -4627,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)
@@ -4685,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`,
@@ -4746,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',
@@ -4922,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) {