@raidiant/notifai 3.0.1 → 5.0.0

package/src/commands.test.ts

@@ -1,3 +1,4 @@
+import { REPLY_MAX_QUESTIONS } from '@raidiant/notifai-protocol'
 import {
   existsSync,
   mkdirSync,
@@ -11,6 +12,7 @@ import {
 import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { AGENT_ACKNOWLEDGEMENT_MAX_LENGTH } from '@raidiant/notifai-protocol'
 import type {
   CapabilityDocument,
   EvidenceSnapshot,
@@ -261,6 +263,7 @@ const receipt: SubmissionReceipt = {
   request_id: 'req_reply_test',
   reply_expires_at: '2026-08-02T18:00:00.000Z',
   agent_acknowledgement_required: true,
+  agent_acknowledgement_text_required: true,
   replayed: false,
   overall: 'provider_accepted_all',
   deliveries: [
@@ -293,6 +296,7 @@ function replyResponse(
   replies: ReplyView[] = [],
   options: {
     required?: boolean
+    textRequired?: boolean
     acknowledgement?: ListRepliesResponse['agent_acknowledgement']
   } = {},
 ): ListRepliesResponse {
@@ -300,6 +304,7 @@ function replyResponse(
     request_id: receipt.request_id,
     reply_expires_at: '2026-08-02T18:00:00.000Z',
     agent_acknowledgement_required: options.required ?? true,
+    agent_acknowledgement_text_required: options.textRequired ?? true,
     agent_acknowledgement: options.acknowledgement ?? null,
     replies,
   }
@@ -378,7 +383,7 @@ describe('command contracts', () => {
     } as unknown as ApiClient
 
     expect(
-      await sendCommand(makeDeps(io, client), {
+      await sendCommand(makeDeps(io, client), { kind: 'update',
         title: 'T',
         body: 'B',
         project: 'Invalid Project!',
@@ -388,6 +393,117 @@ describe('command contracts', () => {
     expect(io.errLines.join('\n')).toContain('project')
   })
 
+  it('infers Project and exact Claude Source Context without printing the opaque id', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'Notifai Project '))
+    const io = new CapturedIo()
+    let submitted: SubmitNotificationRequestT | undefined
+    const client = {
+      submit: async (body: SubmitNotificationRequestT) => {
+        submitted = body
+        return receipt
+      },
+    } as unknown as ApiClient
+    const deps = {
+      ...makeDeps(io, client),
+      cwd,
+      env: {
+        XDG_CONFIG_HOME: path.join(cwd, 'config'),
+        XDG_STATE_HOME: path.join(cwd, 'state'),
+        CLAUDECODE: '1',
+        CLAUDE_CODE_SESSION_ID: 'opaque-claude-session-42',
+      },
+    }
+
+    expect(
+      await sendCommand(deps, {
+        title: 'All checks passed',
+        body: '**42 checks** passed.',
+        kind: 'done',
+      }),
+    ).toBe(EXIT.ok)
+
+    expect(submitted?.draft.project).toMatch(/^notifai-project-/)
+    expect(submitted?.draft.source).toMatchObject({
+      session_id: 'opaque-claude-session-42',
+      harness: 'claude-code',
+    })
+    expect(submitted?.draft.source?.session_label).toMatch(/^[A-Z][a-z]+ [A-Z][a-z]+$/)
+    expect(io.outLines.join('\n')).not.toContain('opaque-claude-session-42')
+    expect(io.errLines.join('\n')).not.toContain('opaque-claude-session-42')
+  })
+
+  it('uploads repeatable images in order and sends only canonical media references', async () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-media-order-'))
+    const first = path.join(root, 'first.png')
+    const second = path.join(root, 'second.gif')
+    writeFileSync(first, 'first image')
+    writeFileSync(second, 'second image')
+    const uploaded: string[] = []
+    let grants = 0
+    let submitted: SubmitNotificationRequestT | undefined
+    const client = {
+      createMediaUpload: async () => {
+        grants += 1
+        return {
+          media_id: `med_uploaded_${grants}`,
+          upload_url: `https://upload.invalid/${grants}`,
+          upload_headers: {},
+          expires_at: new Date(Date.now() + 60_000).toISOString(),
+        }
+      },
+      uploadMedia: async (grant: { media_id: string }) => {
+        uploaded.push(grant.media_id)
+      },
+      submit: async (body: SubmitNotificationRequestT) => {
+        submitted = body
+        return receipt
+      },
+    } as unknown as ApiClient
+
+    expect(
+      await sendCommand(makeDeps(new CapturedIo(), client), { kind: 'update',
+        title: 'Visual comparison is ready',
+        body:
+          '![first](media:1) ![second](media:2) ![ready](media:med_existing)',
+        image: [first, second, 'med_attached_only'],
+        imageAlt: ['First state', 'Second state'],
+      }),
+    ).toBe(EXIT.ok)
+
+    expect(uploaded).toEqual(['med_uploaded_1', 'med_uploaded_2'])
+    expect(submitted?.draft.presentation.media).toEqual([
+      { media_id: 'med_uploaded_1', alt: 'First state' },
+      { media_id: 'med_uploaded_2', alt: 'Second state' },
+      { media_id: 'med_attached_only' },
+    ])
+    expect(submitted?.draft.presentation.body).toBe(
+      '![first](media:med_uploaded_1) ![second](media:med_uploaded_2) ![ready](media:med_existing)',
+    )
+    expect(submitted?.draft.presentation.body).not.toMatch(/media:[1-8](?!\d)/)
+  })
+
+  it('rejects media cardinality and alt pairing before any upload', async () => {
+    const io = new CapturedIo()
+    let uploads = 0
+    const client = {
+      createMediaUpload: async () => {
+        uploads += 1
+        throw new Error('must not upload')
+      },
+    } as unknown as ApiClient
+
+    expect(
+      await sendCommand(makeDeps(io, client), { kind: 'update',
+        title: 'Visual comparison',
+        body: 'See it.',
+        image: ['one.png'],
+        imageAlt: ['one', 'two'],
+      }),
+    ).toBe(EXIT.usage)
+    expect(uploads).toBe(0)
+    expect(io.errLines.join(' ')).toContain('2 --image-alt')
+  })
+
   it('rejects done plus reply before authentication or submission', async () => {
     const io = new CapturedIo()
     let submitCalls = 0
@@ -412,23 +528,19 @@ describe('command contracts', () => {
 
   it.each([
     {
-      flags: { title: 'A title that is deliberately longer than forty characters', body: 'Plain.' },
+      flags: { kind: 'update', title: 'A title that is deliberately longer than forty characters', body: 'Plain.' },
       warning: /titles work best around 40/i,
     },
     {
-      flags: { title: 'Details', body: '**bold Markdown**' },
-      warning: /--body looks like Markdown.*--detail/i,
+      flags: { kind: 'done', title: 'Done · build', body: 'All green.' },
+      warning: /keep the title to the specific substance/i,
     },
     {
-      flags: { title: 'Done · build', body: 'All green.' },
-      warning: /Use --kind done/i,
+      flags: { kind: 'failed', title: 'Failed · build', body: 'One integration test failed.' },
+      warning: /Put notification type in --kind/i,
     },
     {
-      flags: { title: 'Failed · build', body: 'One integration test failed.' },
-      warning: /Use --kind done/i,
-    },
-    {
-      flags: { title: 'Update', body: 'Still relevant.', ttl: 259_201 },
+      flags: { kind: 'update', title: 'Update', body: 'Still relevant.', ttl: 259_201 },
       warning: /longer than 72 hours/i,
     },
   ])('warns without rejecting a send: $warning', async ({ flags, warning }) => {
@@ -452,18 +564,31 @@ describe('command contracts', () => {
       cwd: root,
     }
 
-    expect(await sendCommand(deps, { title: 'Update', body: 'Still relevant.' })).toBe(EXIT.ok)
+    expect(await sendCommand(deps, { kind: 'update', title: 'Update', body: 'Still relevant.' })).toBe(EXIT.ok)
     expect(io.errLines.join('\n')).toMatch(/machine-global config/i)
   })
 
-  it('removes unmanaged provider fields from the public send flags', () => {
+  it('keeps only the current public notification-authoring flags', () => {
     const source = readFileSync(new URL('./main.ts', import.meta.url), 'utf8')
     expect(source).not.toContain(".option('--badge")
     expect(source).not.toContain(".option('--relevance")
     expect(source).not.toContain(".option('--target-content-id")
-    expect(source).toContain('Kind profiles apply automatically')
-    expect(source).toContain('Pass --sound or --level only to override')
-    expect(source).toContain('override kind profile / saved config')
+    const sendGrammar = source.slice(source.indexOf(".command('send')"), source.indexOf('send.addHelpText'))
+    const askGrammar = source.slice(source.indexOf(".command('ask [question]')"), source.indexOf(".command('close"))
+    for (const grammar of [sendGrammar, askGrammar]) {
+      expect(grammar).not.toContain(".option('--detail")
+      expect(grammar).not.toContain(".option('--session <")
+      expect(grammar).toContain(".option('--body-file")
+      expect(grammar).toContain(".option('--session-id")
+      expect(grammar).toContain(".option('--session-label")
+      expect(grammar).toContain("'--image <path|url|media_id>'")
+      expect(grammar).toContain("'--image-alt <text>'")
+    }
+    // Kind now selects the sound, so the help must say so — and must not carry
+    // the retired separation it replaced.
+    expect(source).toContain('Kind is required, and it selects the sound')
+    expect(source).not.toContain('it never chooses banner sound or interruption level')
+    expect(source).not.toContain('Kind profiles apply automatically')
   })
 
   it('rejects a question nobody will wait for', async () => {
@@ -542,8 +667,8 @@ describe('command contracts', () => {
   })
 
   it.each([
-    { title: 'Deploy?   ', body: 'Ready.' },
-    { title: 'Deployment', body: 'Should I deploy?\n' },
+    { kind: 'update', title: 'Deploy?   ', body: 'Ready.' },
+    { kind: 'update', title: 'Deployment', body: 'Should I deploy?\n' },
   ])('warns on stderr when $title / $body ends in a question after trimming', async (flags) => {
     const io = new CapturedIo()
     const client = { submit: async () => receipt } as unknown as ApiClient
@@ -583,7 +708,7 @@ describe('command contracts', () => {
     } as unknown as ApiClient
 
     expect(
-      await sendCommand(makeDeps(io, client), {
+      await sendCommand(makeDeps(io, client), { kind: 'update',
         title: 'Deploy?',
         body: 'Choose when ready.',
         replyChoice: ['Now', 'Later'],
@@ -600,7 +725,7 @@ describe('command contracts', () => {
     const client = { submit: async () => receipt } as unknown as ApiClient
 
     expect(
-      await sendCommand(makeDeps(io, client), {
+      await sendCommand(makeDeps(io, client), { kind: 'update',
         title: 'Deployment',
         body: 'Should I deploy?',
         json: true,
@@ -822,6 +947,7 @@ describe('command contracts', () => {
       reply_expires_at: '2026-08-02T18:00:00.000Z',
       replies: [],
       agent_acknowledgement_required: true,
+      agent_acknowledgement_text_required: true,
       agent_acknowledgement: null,
       acknowledgement_command: null,
       degraded: false,
@@ -855,6 +981,7 @@ describe('command contracts', () => {
       reply_expires_at: '2026-08-02T18:00:00.000Z',
       replies: [reply],
       agent_acknowledgement_required: true,
+      agent_acknowledgement_text_required: true,
       agent_acknowledgement: null,
       acknowledgement_command: `notifai acknowledge ${receipt.request_id} --text <text>`,
       degraded: false,
@@ -968,9 +1095,11 @@ describe('command contracts', () => {
   })
 
   it.each([
-    { text: undefined, message: '--text is required' },
-    { text: '   ', message: '--text is required' },
-    { text: 'x'.repeat(1001), message: 'at most 1000 characters' },
+    { text: '   ', message: 'must contain non-whitespace text' },
+    {
+      text: 'x'.repeat(AGENT_ACKNOWLEDGEMENT_MAX_LENGTH + 1),
+      message: `at most ${AGENT_ACKNOWLEDGEMENT_MAX_LENGTH} characters`,
+    },
   ])('rejects invalid acknowledgement text before network: $message', async ({ text, message }) => {
     const io = new CapturedIo()
     let calls = 0
@@ -988,6 +1117,60 @@ describe('command contracts', () => {
     expect(io.errLines.join('\n')).toContain(message)
   })
 
+  it('records an acknowledgement with no text at all', async () => {
+    const io = new CapturedIo()
+    let submitted: { requestId: string; body: { text?: string } } | undefined
+    const client = {
+      putAgentAcknowledgement: async (requestId: string, body: { text?: string }) => {
+        submitted = { requestId, body }
+        return {
+          status: 'recorded' as const,
+          agent_acknowledgement: { text: '', created_at: '2026-08-13T12:01:00.000Z' },
+        }
+      },
+    } as unknown as ApiClient
+
+    expect(await acknowledgeCommand(makeDeps(io, client), receipt.request_id, {})).toBe(EXIT.ok)
+    // No empty string either: an omitted field is what "no text" means on the
+    // wire, and the account's snapshot decides whether that was allowed.
+    expect(submitted).toEqual({ requestId: receipt.request_id, body: {} })
+    expect(io.outLines.join('\n')).toContain(`Agent Acknowledgement recorded for ${receipt.request_id}`)
+  })
+
+  it('names the missing text, not a contract mismatch, when the account requires it', async () => {
+    const io = new CapturedIo()
+    const client = {
+      putAgentAcknowledgement: async () => {
+        throw new ApiCallError(
+          422,
+          'acknowledgement_text_required',
+          'This account requires Agent Acknowledgement text.',
+          'Re-send the acknowledgement with text saying what you will do because of the reply.',
+        )
+      },
+    } as unknown as ApiClient
+
+    expect(await acknowledgeCommand(makeDeps(io, client), receipt.request_id, {})).toBe(EXIT.failed)
+    const err = io.errLines.join('\n')
+    expect(err).toContain('acknowledgement_text_required')
+    expect(err).toContain('next: Re-send the acknowledgement with text')
+    // The contract held; only this body fell short of the account's choice.
+    expect(err).not.toContain('disagree about the contract')
+  })
+
+  it('asks for a text-free acknowledgement when the account turned text off', async () => {
+    const io = new CapturedIo()
+    const client = {
+      replies: async () => replyResponse([reply], { textRequired: false }),
+    } as unknown as ApiClient
+
+    expect(await repliesCommand(makeDeps(io, client), receipt.request_id, {})).toBe(EXIT.ok)
+    const out = io.outLines.join('\n')
+    expect(out).toContain('Agent Acknowledgement required.')
+    expect(out).toContain(`notifai acknowledge ${receipt.request_id}\``)
+    expect(out).not.toContain('--text')
+  })
+
   it.each([
     [new ApiCallError(409, 'conflict', 'A different acknowledgement is already recorded.'), EXIT.failed, 'conflict'],
     [new ApiCallError(409, 'reply_not_enabled', 'Agent Acknowledgements are disabled.'), EXIT.failed, 'reply_not_enabled'],
@@ -1596,7 +1779,13 @@ describe('Codex hook representation', () => {
     expect(io.outLines.join('\n')).toMatch(/Stop and the existing one will both fire/i)
   })
 
-  it('installs into hooks.json when it alone already contains hooks', () => {
+  /**
+   * The foreign `hooks.json` stays byte-identical and Notifai lands inline.
+   * Codex will now warn that the layer uses both representations; the install
+   * output says why, because that warning is Codex reporting a merge, not a
+   * fault, and a silent one would read as Notifai's bug.
+   */
+  it('leaves a foreign hooks.json alone and installs inline instead', () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-json-install-'))
     const layer = path.join(cwd, '.codex')
     const json = path.join(layer, 'hooks.json')
@@ -1614,11 +1803,17 @@ describe('Codex hook representation', () => {
 
     expect(hooksInstallCommand(deps, { harness: 'codex', execPath, scriptPath })).toBe(EXIT.ok)
 
-    expect(readFileSync(toml, 'utf8')).toBe(beforeToml)
-    expect(readFileSync(json, 'utf8')).toContain('gdh-stop')
-    expect(readFileSync(json, 'utf8')).toContain('--owner notifai')
-    expect(io.outLines.join('\n')).toContain(json)
-    expect(io.outLines.join('\n')).not.toMatch(/loading hooks from both/i)
+    const beforeJson = readFileSync(json, 'utf8')
+    expect(beforeJson).toContain('gdh-stop')
+    expect(beforeJson).not.toContain('--owner notifai')
+    const after = readFileSync(toml, 'utf8')
+    // The user's file arrives back as the file they wrote, plus our hooks.
+    expect(after).toContain(beforeToml.trimEnd())
+    expect(after).toContain('--owner notifai')
+    expect(io.outLines.join('\n')).toContain(toml)
+    expect(io.outLines.join('\n')).toMatch(/Notifai will not modify it/)
+    expect(io.outLines.join('\n')).toMatch(/not a Notifai fault/)
+    expect(io.outLines.join('\n')).not.toMatch(/installed in both/i)
   })
 
   it('leaves config.toml byte-identical when uninstall finds no Notifai hooks', () => {
@@ -1635,8 +1830,14 @@ describe('Codex hook representation', () => {
     expect(io.outLines.join('\n')).toContain('No Notifai hooks found')
   })
 
-  it('does not migrate our hooks when both representations already exist', async () => {
-    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-dual-'))
+  /**
+   * Notifai in one file, someone else's hooks in the other: every handler
+   * fires once, so doctor has nothing to report and the foreign file is not
+   * ours to rewrite. Doctor used to fail here — the check read "two files" as
+   * "two Notifai copies" and pointed at configuration another program owns.
+   */
+  it('passes doctor when only the other representation is foreign', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-foreign-rep-'))
     const toml = writeInlineStop(cwd, 'gdh-stop')
     const json = path.join(cwd, '.codex', 'hooks.json')
     const env = isolatedEnv(cwd)
@@ -1656,12 +1857,12 @@ describe('Codex hook representation', () => {
     })
 
     io.outLines = []
-    expect(await doctorCommand(deps, {})).toBe(EXIT.failed)
-    const before = io.outLines.join('\n')
-    expect(before).toMatch(/hooks \(codex representation\)/)
-    expect(before).toMatch(/prefer a single representation/)
-    expect(before).toMatch(/Stop handlers will both (run|fire)/i)
-    expect(before).not.toContain('notifai hooks install --harness codex')
+    await doctorCommand(deps, {})
+    // Their assertions, this branch's check title.
+    const report = io.outLines.join('\n')
+    expect(report).not.toMatch(/FAIL {2}Codex hook representation/)
+    expect(report).toMatch(/ok {4}Codex hook representation/)
+    expect(report).toMatch(/Notifai will not modify it/)
 
     io.outLines = []
     expect(hooksInstallCommand(deps, { harness: 'codex', execPath, scriptPath })).toBe(EXIT.ok)
@@ -1669,7 +1870,7 @@ describe('Codex hook representation', () => {
     expect(readFileSync(json, 'utf8')).toContain('--owner notifai')
     expect(readFileSync(toml, 'utf8')).toContain('gdh-stop')
     expect(readFileSync(toml, 'utf8')).not.toContain('--owner notifai')
-    expect(io.outLines.join('\n')).toMatch(/loading hooks from both/i)
+    expect(io.outLines.join('\n')).not.toMatch(/installed in both/i)
     expect(io.outLines.join('\n')).not.toMatch(/collaps/i)
 
     const installations = findInstallations(cwd, env, deps.hookAdapterHome).filter(
@@ -1678,6 +1879,44 @@ describe('Codex hook representation', () => {
     expect(installations).toHaveLength(1)
     expect(installations[0]?.file).toBe(json)
   })
+
+  it('fails doctor when Notifai itself is installed in both representations', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-dual-'))
+    const json = path.join(cwd, '.codex', 'hooks.json')
+    const env = isolatedEnv(cwd)
+    const io = new CapturedIo()
+    const client = {
+      health: async () => false,
+      capabilities: async () => ({ schema_version: 1, platform: 'ios' }),
+      listDevices: async () => ({ devices: [] }),
+    } as unknown as ApiClient
+    const deps = { ...makeDeps(io, client), cwd, env }
+
+    expect(hooksInstallCommand(deps, { harness: 'codex', execPath, scriptPath })).toBe(EXIT.ok)
+    applyPlan(json, {
+      hooks: buildHookConfig({
+        adapterPath: hookAdapterPath(deps.hookAdapterHome),
+        harness: 'codex',
+      }),
+    })
+
+    io.outLines = []
+    expect(await doctorCommand(deps, {})).toBe(EXIT.failed)
+    const reported = io.outLines.join('\n')
+    expect(reported).toMatch(/Codex hook representation/)
+    expect(reported).toMatch(/installed in both/i)
+    expect(reported).toMatch(/notifies twice per turn/)
+    expect(reported).toMatch(/notifai hooks uninstall --harness codex/)
+
+    // The named remedy has to actually clear it, including the copy in the
+    // file Notifai would not have chosen to write.
+    io.outLines = []
+    expect(hooksUninstallCommand(deps, { harness: 'codex', scriptPath })).toBe(EXIT.ok)
+    expect(hooksInstallCommand(deps, { harness: 'codex', execPath, scriptPath })).toBe(EXIT.ok)
+    io.outLines = []
+    await doctorCommand(deps, {})
+    expect(io.outLines.join('\n')).not.toMatch(/Codex hook representation/)
+  })
 })
 
 describe('harness activation guidance', () => {
@@ -1793,14 +2032,14 @@ describe('harness activation guidance', () => {
 
     io.outLines = []
     expect(await doctorCommand(deps, {})).toBe(EXIT.failed)
-    expect(io.outLines.join('\n')).toContain('hooks (answer continuation)')
+    expect(io.outLines.join('\n')).toContain('How an answer returns')
     expect(io.outLines.join('\n')).toContain('no proven answer continuation')
-    expect(io.outLines.join('\n')).not.toContain('hooks (adapter)')
+    expect(io.outLines.join('\n')).not.toContain('Hook adapter')
 
     writeFileSync(pluginFile, plugin.replace(/^const ADAPTER_VERSION = .*\n/m, ''))
     io.outLines = []
     expect(await doctorCommand(deps, {})).toBe(EXIT.failed)
-    expect(io.outLines.join('\n')).toContain('hooks (adapter)')
+    expect(io.outLines.join('\n')).toContain('Hook adapter')
     expect(io.outLines.join('\n')).toContain('obsolete OpenCode event wiring')
   })
 
@@ -1899,7 +2138,7 @@ describe('stable hook installation', () => {
 
     io.outLines = []
     await doctorCommand(deps, {})
-    expect(io.outLines.join('\n')).not.toMatch(/hooks \(duplicates\)/)
+    expect(io.outLines.join('\n')).not.toMatch(/Duplicate hook installs/)
 
     expect(hooksUninstallCommand(deps, { harness: 'claude-code' })).toBe(EXIT.ok)
     expect(existsSync(hookAdapterPath(deps.hookAdapterHome))).toBe(true)
@@ -3732,6 +3971,74 @@ describe('asking before the hooks have ever run', () => {
     expect(io.outLines).toContain(
       'Question registered. Ask it in the conversation, state the concrete work you will resume when the answer arrives, then end your turn.',
     )
+    expect(readSessionState('codex-current-thread', env).pending?.[0]?.source).toMatchObject({
+      session_id: 'codex-current-thread',
+      harness: 'codex',
+    })
+    expect(
+      readSessionState('codex-current-thread', env).pending?.[0]?.source?.session_label,
+    ).toMatch(/^[A-Z][a-z]+ [A-Z][a-z]+$/)
+  })
+
+  it('uploads ask images before registration and freezes canonical body media', async () => {
+    const cwd = scratchDir('notifai-ask-media-')
+    const first = path.join(cwd, 'first.png')
+    const second = path.join(cwd, 'second.gif')
+    writeFileSync(first, 'first')
+    writeFileSync(second, 'second')
+    const io = new CapturedIo()
+    const env = {
+      XDG_CONFIG_HOME: path.join(cwd, 'config'),
+      XDG_STATE_HOME: path.join(cwd, 'state'),
+      HOME: path.join(cwd, 'home'),
+      CODEX_HOME: path.join(cwd, 'codex-home'),
+      CODEX_THREAD_ID: 'codex-media-thread',
+    }
+    let grant = 0
+    const uploaded: string[] = []
+    const client = {
+      createMediaUpload: async () => {
+        grant += 1
+        return {
+          media_id: `med_ask_${grant}`,
+          upload_url: `https://upload.invalid/${grant}`,
+          upload_headers: {},
+          expires_at: new Date(Date.now() + 60_000).toISOString(),
+        }
+      },
+      uploadMedia: async (value: { media_id: string }) => {
+        uploaded.push(value.media_id)
+      },
+    } as unknown as ApiClient
+    const deps = { ...makeDeps(io, client), cwd, env, now: () => 42 }
+
+    expect(hooksInstallCommand(deps, { harness: 'codex', execPath, scriptPath })).toBe(EXIT.ok)
+    trustInstalledCodexHooks(cwd, env)
+    writeSessionState('codex-media-thread', env, { last_prompt_at: 42, last_stop_at: 41 })
+    writeProjectSession(cwd, env, 'codex-media-thread', 42, 'codex')
+    io.outLines = []
+
+    expect(
+      await askCommand(deps, 'Which visual should I use?', {
+        body: 'Compare ![first](media:1) with ![second](media:2).',
+        image: [first, second],
+        imageAlt: ['First option', 'Second option'],
+      }),
+    ).toBe(EXIT.ok)
+
+    const pending = readSessionState('codex-media-thread', env).pending?.[0]
+    expect(uploaded).toEqual(['med_ask_1', 'med_ask_2'])
+    expect(pending?.body).toBe(
+      'Which visual should I use?\n\nCompare ![first](media:med_ask_1) with ![second](media:med_ask_2).',
+    )
+    expect(pending?.media).toEqual([
+      { media_id: 'med_ask_1', alt: 'First option' },
+      { media_id: 'med_ask_2', alt: 'Second option' },
+    ])
+    expect(pending?.source).toMatchObject({
+      session_id: 'codex-media-thread',
+      harness: 'codex',
+    })
   })
 
   // A harness exports its markers into everything it starts, so a nested
@@ -3763,7 +4070,10 @@ describe('asking before the hooks have ever run', () => {
     io.outLines = []
 
     expect(askCommand(deps, 'Ship it?', {})).toBe(EXIT.ok)
-    expect(readSessionState('codex-current-thread', env).pending?.[0]?.question).toBe('Ship it?')
+    expect(readSessionState('codex-current-thread', env).pending?.[0]).toMatchObject({
+      question: 'Ship it?',
+      source: { session_id: 'codex-current-thread', harness: 'codex' },
+    })
     expect(readSessionState('claude-orchestrator', env).pending).toBeUndefined()
   })
 
@@ -3792,7 +4102,10 @@ describe('asking before the hooks have ever run', () => {
     io.outLines = []
 
     expect(askCommand(deps, 'Ship it?', {})).toBe(EXIT.ok)
-    expect(readSessionState('claude-current', env).pending?.[0]?.question).toBe('Ship it?')
+    expect(readSessionState('claude-current', env).pending?.[0]).toMatchObject({
+      question: 'Ship it?',
+      source: { session_id: 'claude-current', harness: 'claude-code' },
+    })
     expect(readSessionState('codex-orchestrator', env).pending).toBeUndefined()
   })
 
@@ -3944,7 +4257,7 @@ describe('asking before the hooks have ever run', () => {
 
     io.outLines = []
     await doctorCommand(deps, {})
-    expect(io.outLines.join('\n')).toMatch(/FAIL\s+hooks \(trust\).*Stop/is)
+    expect(io.outLines.join('\n')).toMatch(/FAIL\s+Codex hook trust.*Stop/is)
     expect(io.outLines.join('\n')).toMatch(/best-effort.*never writes.*\/hooks/is)
   })
 
@@ -4197,7 +4510,7 @@ describe('asking before the hooks have ever run', () => {
     io.outLines = []
 
     expect(await doctorCommand(deps, {})).toBe(EXIT.failed)
-    expect(io.outLines.join('\n')).toMatch(/FAIL\s+Question routing:.*active Claude Code/is)
+    expect(io.outLines.join('\n')).toMatch(/FAIL\s+Routing for this harness.*active Claude Code/is)
   })
 
   it('treats an unfired pointer as informational, with a prompt as the remedy', async () => {
@@ -4266,7 +4579,7 @@ describe('asking before the hooks have ever run', () => {
     io.outLines = []
 
     await doctorCommand(deps, {})
-    expect(io.outLines.join('\n')).toMatch(/ok\s+hooks \(stop shape\)/)
+    expect(io.outLines.join('\n')).toMatch(/ok\s+Turn\-end hook shape/)
   })
 
   it('names an old blocking Claude Stop handler as the reason no wake can happen', async () => {
@@ -4295,7 +4608,7 @@ describe('asking before the hooks have ever run', () => {
 
     await doctorCommand(deps, {})
     const out = io.outLines.join('\n')
-    expect(out).toMatch(/FAIL\s+hooks \(stop shape\)/)
+    expect(out).toMatch(/FAIL\s+Turn\-end hook shape/)
     expect(out).toContain('needs `async: true`')
     expect(out).toContain('kills the backgrounded waiter at its 600s default')
   })
@@ -4338,7 +4651,7 @@ describe('asking before the hooks have ever run', () => {
 
     await doctorCommand(deps, {})
     const out = io.outLines.join('\n')
-    expect(out).toMatch(/ok\s+hooks \(wake route\)/)
+    expect(out).toMatch(/ok\s+Direct wake route/)
     expect(out).toContain(socket)
     expect(out).toContain('an answer can start a turn here without you')
     // Doctor never widens the user's inbound policy to make Notifai work: the
@@ -4355,10 +4668,10 @@ describe('asking before the hooks have ever run', () => {
     expect(await doctorCommand(deps, {})).toBe(EXIT.failed) // unreachable test server
     const out = io.outLines.join('\n')
     // Honest, and not a blocker: nothing is lost, it simply arrives later.
-    expect(out).toMatch(/--\s+hooks \(wake route\)/)
+    expect(out).toMatch(/--\s+Direct wake route/)
     expect(out).toContain('`--bare` binds no inbox socket')
     expect(out).toContain("at this session's next turn")
-    expect(out).not.toMatch(/FAIL\s+hooks \(wake route\)/)
+    expect(out).not.toMatch(/FAIL\s+Direct wake route/)
   })
 
   it('fails closed on an inbox protocol it does not recognise', async () => {
@@ -4406,7 +4719,7 @@ describe('asking before the hooks have ever run', () => {
     io.outLines = []
     await doctorCommand(deps, {})
     const out = io.outLines.join('\n')
-    expect(out).toMatch(/ok\s+hooks \(wake route\)/)
+    expect(out).toMatch(/ok\s+Direct wake route/)
     expect(out).toContain('can prove a stopped thread unowned before resuming it')
   })
 
@@ -4566,6 +4879,66 @@ describe('a server behind this CLI', () => {
   })
 })
 
+/**
+ * The same class of failure through the command path. A rejected `send` printed
+ * only "invalid_request: The draft was not accepted." while the server's
+ * details — naming the exact offending field — went to the local log alone.
+ * stderr is the one line an agent's next turn actually reads, so the diagnosis
+ * has to be on it. Direction-neutral on purpose: the mismatch has been seen
+ * with the server behind the CLI and with the CLI behind the server.
+ */
+describe('command failures carrying server details', () => {
+  const throwingClient = (status: number, details: unknown = null): ApiClient =>
+    ({
+      submit: async () => {
+        throw new ApiCallError(status, 'invalid_request', 'The draft was not accepted.', null, details)
+      },
+    }) as unknown as ApiClient
+
+  it('names the rejected field and the contract mismatch on a 422', async () => {
+    const io = new CapturedIo()
+    const client = throwingClient(422, [
+      { code: 'invalid_request', path: 'presentation.detail', message: 'Unexpected property' },
+    ])
+
+    expect(await sendCommand(makeDeps(io, client), { kind: 'update', title: 'Deploy finished', body: 'All green.' })).toBe(
+      EXIT.failed,
+    )
+
+    const said = io.errLines.join(' ')
+    expect(said).toContain('the server rejected: presentation.detail')
+    expect(said).toMatch(/sent a field the server did not accept/)
+    expect(said).toContain('notifai doctor')
+    expect(said).not.toMatch(/older than this CLI/)
+  })
+
+  it('prints the rejected paths without the contract line when the status is not 422', async () => {
+    const io = new CapturedIo()
+    const client = throwingClient(400, [
+      { code: 'invalid_request', path: 'presentation.detail', message: 'Unexpected property' },
+    ])
+
+    expect(await sendCommand(makeDeps(io, client), { kind: 'update', title: 'Deploy finished', body: 'All green.' })).toBe(
+      EXIT.failed,
+    )
+
+    const said = io.errLines.join(' ')
+    expect(said).toContain('the server rejected: presentation.detail')
+    expect(said).not.toContain('notifai doctor')
+    expect(said).not.toMatch(/did not accept/)
+  })
+
+  it('prints exactly the code and message when the error carries no details', async () => {
+    const io = new CapturedIo()
+
+    expect(await sendCommand(makeDeps(io, throwingClient(409)), { kind: 'update', title: 'Deploy finished', body: 'All green.' })).toBe(
+      EXIT.failed,
+    )
+
+    expect(io.errLines).toEqual(['invalid_request: The draft was not accepted.'])
+  })
+})
+
 describe('question sets', () => {
   it('maps --reply-multi into the single question', async () => {
     const io = new CapturedIo()
@@ -4595,26 +4968,76 @@ describe('question sets', () => {
     expect(submitted?.draft.reply?.questions?.[0]?.choices).toHaveLength(3)
   })
 
-  it('rejects a question body too long for the answering surface', async () => {
+  it('derives the answerable question from the first banner block', async () => {
     const io = new CapturedIo()
-    let submitCalls = 0
+    let submitted: SubmitNotificationRequestT | undefined
     const client = {
-      submit: async () => {
-        submitCalls += 1
+      submit: async (body: SubmitNotificationRequestT) => {
+        submitted = body
         return receipt
       },
+      replies: async () => replyResponse([reply]),
     } as unknown as ApiClient
 
+    const body = `Which environment?\n\n${'Long Markdown context. '.repeat(30)}`
     expect(
       await sendCommand(makeDeps(io, client), {
-        title: 'Question',
-        body: 'x'.repeat(501),
+        title: 'Choose the deployment environment',
+        body,
         reply: true,
         replyTimeout: 30,
       }),
-    ).toBe(EXIT.usage)
-    expect(submitCalls).toBe(0)
-    expect(io.errLines.join(' ')).toContain('--detail')
+    ).toBe(EXIT.ok)
+    expect(submitted?.draft.presentation.body).toBe(body)
+    expect(submitted?.draft.reply?.questions[0]?.text).toBe('Which environment?')
+  })
+
+  it('composes one question before optional Markdown context', () => {
+    expect(
+      buildQuestions(
+        { body: '## Why\nThe release window closes today.' },
+        'Which environment?',
+      ),
+    ).toMatchObject({
+      ok: true,
+      body: 'Which environment?\n\n## Why\nThe release window closes today.',
+      questions: [{ text: 'Which environment?' }],
+    })
+  })
+
+  it('composes numbered form questions before form context', () => {
+    expect(
+      buildQuestions(
+        {
+          form: JSON.stringify({
+            questions: [{ text: 'Deploy where?' }, { text: 'What should I monitor?' }],
+            body: '## Context\nTraffic is elevated.',
+          }),
+        },
+        undefined,
+      ),
+    ).toMatchObject({
+      ok: true,
+      body:
+        '1. Deploy where?\n2. What should I monitor?\n\n## Context\nTraffic is elevated.',
+    })
+  })
+
+  it('rejects the deleted form detail key instead of treating it as context', () => {
+    expect(
+      buildQuestions(
+        {
+          form: JSON.stringify({
+            questions: [{ text: 'Deploy?' }],
+            detail: 'legacy context',
+          }),
+        },
+        undefined,
+      ),
+    ).toMatchObject({
+      ok: false,
+      error: expect.stringContaining('Unknown --form key: detail'),
+    })
   })
 
   it('generates unique question ids when texts collide', () => {
@@ -4632,6 +5055,17 @@ describe('question sets', () => {
     }
   })
 
+  it('reports a registration as data, with the ids an agent must branch on', () => {
+    // The prose block is the densest guidance this CLI prints, but a choice id
+    // cannot be read back out of prose.
+    const built = buildQuestions(
+      { choice: ['Deploy now', 'Hold'] },
+      'Deploy migration 0007 to production?',
+    )
+    if (!built.ok) throw new Error(built.error)
+    expect(built.questions[0]?.choices?.map((choice) => choice.id)).toEqual(['deploy-now', 'hold'])
+  })
+
   it('rejects forms outside the documented shape', () => {
     expect(buildQuestions({ form: 'not json' }, undefined)).toMatchObject({ ok: false })
     expect(
@@ -4639,10 +5073,14 @@ describe('question sets', () => {
     ).toMatchObject({ ok: false })
     expect(
       buildQuestions(
-        { form: JSON.stringify({ questions: Array.from({ length: 5 }, (_, i) => ({ text: `Q${i}?` })) }) },
+        {
+          form: JSON.stringify({
+            questions: Array.from({ length: REPLY_MAX_QUESTIONS + 1 }, (_, i) => ({ text: `Q${i}?` })),
+          }),
+        },
         undefined,
       ),
-    ).toMatchObject({ ok: false, error: expect.stringContaining('1-4') })
+    ).toMatchObject({ ok: false, error: expect.stringContaining(`1-${REPLY_MAX_QUESTIONS}`) })
     expect(
       buildQuestions(
         { form: JSON.stringify({ questions: [{ text: 'Pick?', multi: true }] }) },