@raidiant/notifai 4.0.0 → 6.0.0

package/src/commands.test.ts

@@ -1,3 +1,4 @@
+import { CAPABILITIES_V1, PLATFORMS, REPLY_MAX_QUESTIONS } from '@raidiant/notifai-protocol'
 import {
   existsSync,
   mkdirSync,
@@ -11,14 +12,19 @@ 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,
+  CompatibilityResponse,
   EvidenceSnapshot,
   ListRepliesResponse,
+  Platform,
   ReplyView,
   SubmissionReceipt,
   SubmitNotificationRequestT,
+  SupportAssessment,
 } from '@raidiant/notifai-protocol'
+import { parse as parseToml } from 'smol-toml'
 import { afterEach, describe, expect, it } from 'vitest'
 import { ApiCallError, NetworkError, type ApiClient } from './client.js'
 import type { ClaudeWakeAdapters } from './claude-wake.js'
@@ -83,6 +89,71 @@ const RELEASE_REF = `v${
   ).version
 }`
 
+const currentSupport: SupportAssessment = {
+  state: 'current',
+  reason: 'current',
+  affected_operation: null,
+  recovery_action: null,
+  current_version: '5.0.0',
+  current_build: null,
+  recommended_version: '5.0.0',
+  recommended_build: null,
+  minimum_version: null,
+  minimum_build: null,
+  deprecation: null,
+  sunset: null,
+}
+
+const currentCompatibility: CompatibilityResponse = {
+  cli: currentSupport,
+  platforms: [
+    {
+      platform: 'ios',
+      recommended_version: null,
+      recommended_build: null,
+      minimum_receive_build: null,
+      minimum_answer_build: null,
+      deprecation: null,
+      sunset: null,
+      replacement_available: false,
+      rollout_complete: false,
+    },
+    {
+      platform: 'macos',
+      recommended_version: null,
+      recommended_build: null,
+      minimum_receive_build: null,
+      minimum_answer_build: null,
+      deprecation: null,
+      sunset: null,
+      replacement_available: false,
+      rollout_complete: false,
+    },
+  ],
+  server_capabilities: ['answer', 'agent_acknowledgement'],
+}
+
+function compatibilityWithCli(
+  overrides: Partial<SupportAssessment>,
+): CompatibilityResponse {
+  return {
+    ...currentCompatibility,
+    cli: { ...currentSupport, ...overrides },
+  }
+}
+
+function withCompatibilityDefaults(client: ApiClient): ApiClient {
+  return {
+    capabilities: async (platform: Platform = 'ios') => {
+      const document = CAPABILITIES_V1.describe(platform)
+      if (document === null) throw new Error(`missing ${platform} capability document`)
+      return document
+    },
+    compatibility: async () => currentCompatibility,
+    ...client,
+  } as ApiClient
+}
+
 class CapturedIo implements CommandIo {
   outLines: string[] = []
   errLines: string[] = []
@@ -105,6 +176,10 @@ class CapturedIo implements CommandIo {
   }
 }
 
+class PlainInteractiveIo extends CapturedIo {
+  interactive = true
+}
+
 class InteractiveIo extends CapturedIo {
   interactive = true
   selectAnswer: string | null = 'global'
@@ -232,7 +307,7 @@ function makeDeps(io: CapturedIo, client: ApiClient): CommandDeps {
     },
     hookAdapterHome: path.join(testRoot, 'home'),
     cwd: os.tmpdir(),
-    clientFactory: () => client,
+    clientFactory: () => withCompatibilityDefaults(client),
   }
 }
 
@@ -261,6 +336,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 +369,7 @@ function replyResponse(
   replies: ReplyView[] = [],
   options: {
     required?: boolean
+    textRequired?: boolean
     acknowledgement?: ListRepliesResponse['agent_acknowledgement']
   } = {},
 ): ListRepliesResponse {
@@ -300,6 +377,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 +456,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!',
@@ -456,7 +534,7 @@ describe('command contracts', () => {
     } as unknown as ApiClient
 
     expect(
-      await sendCommand(makeDeps(new CapturedIo(), client), {
+      await sendCommand(makeDeps(new CapturedIo(), client), { kind: 'update',
         title: 'Visual comparison is ready',
         body:
           '![first](media:1) ![second](media:2) ![ready](media:med_existing)',
@@ -488,7 +566,7 @@ describe('command contracts', () => {
     } as unknown as ApiClient
 
     expect(
-      await sendCommand(makeDeps(io, client), {
+      await sendCommand(makeDeps(io, client), { kind: 'update',
         title: 'Visual comparison',
         body: 'See it.',
         image: ['one.png'],
@@ -523,19 +601,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: 'Done · build', body: 'All green.' },
+      flags: { kind: 'done', title: 'Done · build', body: 'All green.' },
       warning: /keep the title to the specific substance/i,
     },
     {
-      flags: { title: 'Failed · build', body: 'One integration test failed.' },
+      flags: { kind: 'failed', title: 'Failed · build', body: 'One integration test failed.' },
       warning: /Put notification type in --kind/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 }) => {
@@ -559,7 +637,7 @@ 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)
   })
 
@@ -579,11 +657,11 @@ describe('command contracts', () => {
       expect(grammar).toContain("'--image <path|url|media_id>'")
       expect(grammar).toContain("'--image-alt <text>'")
     }
-    expect(source).toContain('Kind describes status in the Companion Apps')
-    expect(source).toContain('it never chooses banner sound or interruption level')
-    expect(source).toContain('override saved sound')
+    // 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')
-    expect(source).not.toContain('sound alert      level active')
   })
 
   it('rejects a question nobody will wait for', async () => {
@@ -662,8 +740,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
@@ -703,7 +781,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'],
@@ -720,7 +798,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,
@@ -942,6 +1020,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,
@@ -975,6 +1054,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,
@@ -1088,9 +1168,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
@@ -1108,6 +1190,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'],
@@ -1609,7 +1745,7 @@ describe('Cursor hook commands', () => {
 
   it('reports a native Cursor installation through doctor', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-cursor-doctor-'))
-    const io = new CapturedIo()
+    const io = new PlainInteractiveIo()
     const client = {
       health: async () => true,
       capabilities: async () => ({ schema_version: 1, platform: 'ios' }),
@@ -1716,7 +1852,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')
@@ -1734,11 +1876,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', () => {
@@ -1755,12 +1903,18 @@ 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)
-    const io = new CapturedIo()
+    const io = new PlainInteractiveIo()
     const client = {
       health: async () => false,
       capabilities: async () => ({ schema_version: 1, platform: 'ios' }),
@@ -1776,12 +1930,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)
@@ -1789,7 +1943,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(
@@ -1798,6 +1952,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', () => {
@@ -1913,14 +2105,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')
   })
 
@@ -2019,7 +2211,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)
@@ -2315,6 +2507,39 @@ describe('config surfaces', () => {
     expect(resolved.sound.source).toMatch(/^global:/)
   })
 
+  it('round-trips unknown root and table keys through config set and unset', async () => {
+    const io = new CapturedIo()
+    const deps = configDeps(io)
+    const configFile = path.join(deps.env['XDG_CONFIG_HOME']!, 'notifai', 'config.toml')
+    mkdirSync(path.dirname(configFile), { recursive: true })
+    writeFileSync(
+      configFile,
+      [
+        'future_root = "keep-root"',
+        'wait_seconds = 20',
+        '',
+        '[future_table]',
+        'future_key = "keep-table"',
+        '',
+      ].join('\n'),
+    )
+
+    expect(await configSetCommand(deps, 'sound', 'done', { yes: true })).toBe(EXIT.ok)
+    expect(parseToml(readFileSync(configFile, 'utf8'))).toEqual({
+      future_root: 'keep-root',
+      wait_seconds: 20,
+      sound: 'done',
+      future_table: { future_key: 'keep-table' },
+    })
+
+    expect(await configUnsetCommand(deps, 'wait_seconds', { yes: true })).toBe(EXIT.ok)
+    expect(parseToml(readFileSync(configFile, 'utf8'))).toEqual({
+      future_root: 'keep-root',
+      sound: 'done',
+      future_table: { future_key: 'keep-table' },
+    })
+  })
+
   it('refuses to create a redundant machine override equal to the shipped default', async () => {
     const io = new CapturedIo()
     const deps = configDeps(io)
@@ -2519,7 +2744,7 @@ describe('interactive command UX', () => {
     expect(await doctorCommand(deps, {})).toBe(EXIT.failed)
     expect(io.intros).toEqual(['Notifai doctor'])
     expect(io.checks.some((check) => !check.ok && check.message.startsWith('This machine:'))).toBe(true)
-    expect(io.checks.some((check) => check.ok && check.message.startsWith('Protocol version:'))).toBe(true)
+    expect(io.checks.some((check) => check.message.startsWith('Notifai update:'))).toBe(false)
     expect(io.outLines).toEqual([])
 
     // Four tones, not two. A boolean has to round `optional-gap` and `unknown`
@@ -2528,7 +2753,6 @@ describe('interactive command UX', () => {
     const tone = (prefix: string): Tone | undefined =>
       io.checks.find((check) => check.message.startsWith(prefix))?.tone
     expect(tone('This machine:')).toBe('bad')
-    expect(tone('Protocol version:')).toBe('ok')
     // Never evaluated: the account cannot be checked without a credential.
     expect(tone('Account:')).toBe('pending')
     // Legitimately declined rather than broken.
@@ -2562,6 +2786,210 @@ describe('interactive command UX', () => {
   })
 })
 
+describe('compatibility-first update guidance', () => {
+  const cases: Array<{
+    name: string
+    support: Partial<SupportAssessment>
+    status: 'ready' | 'optional-gap' | 'gap'
+    detail: string
+    exit: number
+    humanLines: string[]
+  }> = [
+    {
+      name: 'current',
+      support: {},
+      status: 'ready',
+      detail: 'Notifai can send notifications.',
+      exit: EXIT.ok,
+      humanLines: [],
+    },
+    {
+      name: 'optional newer release',
+      support: {
+        state: 'update_available',
+        reason: 'newer_release',
+        recovery_action: 'update_cli',
+        recommended_version: '6.0.0',
+      },
+      status: 'optional-gap',
+      detail: 'A newer Notifai is available.',
+      exit: EXIT.ok,
+      humanLines: [
+        'A newer Notifai is available.',
+        'npm install -g @raidiant/notifai',
+      ],
+    },
+    {
+      name: 'scheduled Sunset',
+      support: {
+        state: 'update_available',
+        reason: 'sunset_scheduled',
+        recovery_action: 'update_cli',
+        recommended_version: '6.0.0',
+        deprecation: 'Tue, 18 Aug 2026 00:00:00 GMT',
+        sunset: 'Tue, 15 Sep 2026 00:00:00 GMT',
+      },
+      status: 'optional-gap',
+      detail: 'Update Notifai soon to keep sending notifications.',
+      exit: EXIT.ok,
+      humanLines: [
+        'Update Notifai soon to keep sending notifications.',
+        'npm install -g @raidiant/notifai',
+      ],
+    },
+    {
+      name: 'required update',
+      support: {
+        state: 'must_update',
+        reason: 'minimum_not_met',
+        affected_operation: 'send_notifications',
+        recovery_action: 'update_cli',
+        recommended_version: '6.0.0',
+        minimum_version: '6.0.0',
+      },
+      status: 'gap',
+      detail: "Notifai can't send notifications until you update.",
+      exit: EXIT.failed,
+      humanLines: [
+        "Notifai can't send notifications until you update.",
+        'npm install -g @raidiant/notifai',
+      ],
+    },
+  ]
+
+  it.each(cases)(
+    'maps $name policy to closed human copy and structured JSON',
+    async ({ support, status, detail, exit, humanLines }) => {
+      const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-update-guidance-'))
+      const client = {
+        health: async () => true,
+        compatibility: async () => compatibilityWithCli(support),
+        listDevices: async () => ({ devices: [] }),
+        accessStatus: async () => ({ email: 'user@example.test' }),
+      } as unknown as ApiClient
+      const humanIo = new PlainInteractiveIo()
+      const deps = {
+        ...makeDeps(humanIo, client),
+        cwd,
+        env: isolatedEnv(cwd),
+      }
+      const readiness = await assessReadiness(deps)
+      const contract = readiness.states.find((state) => state.id === 'contract')
+      expect(contract).toMatchObject({ status, detail })
+
+      expect(
+        await doctorCommand(deps, {}, { readiness: { states: [contract!] } }),
+      ).toBe(exit)
+      expect(humanIo.outLines).toEqual(humanLines)
+      expect(humanIo.errLines).toEqual([])
+
+      const jsonIo = new CapturedIo()
+      expect(
+        await doctorCommand(
+          { ...deps, io: jsonIo },
+          { json: true },
+          { readiness: { states: [contract!] } },
+        ),
+      ).toBe(exit)
+      expect(jsonIo.outLines).toHaveLength(1)
+      const payload = JSON.parse(jsonIo.outLines[0] ?? '{}') as {
+        ok: boolean
+        exit_code: number
+        states: Array<{
+          status: string
+          detail: string
+          remedy?: { command?: string }
+        }>
+      }
+      expect(payload).toMatchObject({
+        ok: exit === EXIT.ok,
+        exit_code: exit,
+        states: [{ status, detail }],
+      })
+      expect(payload.states[0]?.remedy?.command ?? null).toBe(
+        status === 'ready' ? null : 'npm install -g @raidiant/notifai',
+      )
+      expect(jsonIo.errLines).toEqual([])
+
+      const nonTtyIo = new CapturedIo()
+      expect(
+        await doctorCommand(
+          { ...deps, io: nonTtyIo },
+          {},
+          { readiness: { states: [contract!] } },
+        ),
+      ).toBe(exit)
+      expect(nonTtyIo.outLines).toHaveLength(1)
+      expect(JSON.parse(nonTtyIo.outLines[0] ?? '{}')).toEqual(payload)
+      expect(nonTtyIo.errLines).toEqual([])
+    },
+  )
+
+  it('reports a missing named CLI capability without blocking ordinary sends', async () => {
+    const requestedPlatforms: Platform[] = []
+    let submissions = 0
+    const client = {
+      health: async () => true,
+      compatibility: async (): Promise<CompatibilityResponse> => ({
+        ...currentCompatibility,
+        // This service can still accept baseline Notification Requests, but it
+        // cannot honor this CLI's Agent Acknowledgement feature yet.
+        server_capabilities: ['answer'],
+      }),
+      capabilities: async (platform: Platform = 'ios') => {
+        requestedPlatforms.push(platform)
+        const document = CAPABILITIES_V1.describe(platform)
+        if (document === null) throw new Error(`missing ${platform} capability document`)
+        return document
+      },
+      listDevices: async () => ({ devices: [] }),
+      accessStatus: async () => ({ email: 'user@example.test' }),
+      submit: async () => {
+        submissions += 1
+        return receipt
+      },
+    } as unknown as ApiClient
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-capability-guidance-'))
+    const io = new PlainInteractiveIo()
+    const deps = {
+      ...makeDeps(io, client),
+      cwd,
+      env: isolatedEnv(cwd),
+    }
+
+    const readiness = await assessReadiness(deps)
+    const contract = readiness.states.find((state) => state.id === 'contract')
+    expect(requestedPlatforms).toEqual([...PLATFORMS])
+    expect(contract).toMatchObject({
+      status: 'optional-gap',
+      detail: 'The service is being updated; try again later.',
+      technical: {
+        capability_documents: PLATFORMS.map((platform) => ({ platform, schema_version: 1 })),
+        cli_capability_intersection: {
+          available: [],
+          missing_on_server: ['agent_acknowledgement'],
+        },
+      },
+    })
+
+    expect(
+      await doctorCommand(deps, {}, { readiness: { states: [contract!] } }),
+    ).toBe(EXIT.ok)
+    expect(io.outLines).toEqual(['The service is being updated; try again later.'])
+    expect(io.outLines.join('\n')).not.toContain('npm install -g @raidiant/notifai')
+
+    const sendIo = new CapturedIo()
+    expect(
+      await sendCommand(
+        { ...deps, io: sendIo },
+        { kind: 'update', title: 'Build finished', body: 'All checks passed.' },
+      ),
+    ).toBe(EXIT.ok)
+    expect(submissions).toBe(1)
+    expect(sendIo.errLines).toEqual([])
+  })
+})
+
 describe('init', () => {
   const readyIphone = {
     device_id: 'dev_iphone',
@@ -2569,9 +2997,22 @@ describe('init', () => {
     platform: 'ios' as const,
     permission_status: 'authorized',
     registration_healthy: true,
-    reply_protocol_version: 2,
+    app_version: '0.1.0',
+    app_build: '42',
+    os_version: '19.0',
+    capabilities: ['answer'] as const,
+    support: currentSupport,
+    support_state: 'current' as const,
+    derived_status: 'working' as const,
+    status_message: null,
     last_seen_at: '2026-08-05T18:00:00.000Z',
   }
+  const readyMac = {
+    ...readyIphone,
+    device_id: 'dev_mac',
+    display_name: 'Mac',
+    platform: 'macos' as const,
+  }
 
   function setupEvidence(
     requestId: string,
@@ -2697,6 +3138,58 @@ describe('init', () => {
     expect(readFileSync(configPath, 'utf8')).toContain('project = "my-project-')
   })
 
+  it('resumes the same init after a required CLI update becomes current', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-init-update-resume-'))
+    const io = new CapturedIo()
+    let cliSupport = compatibilityWithCli({
+      state: 'must_update',
+      reason: 'minimum_not_met',
+      affected_operation: 'send_notifications',
+      recovery_action: 'update_cli',
+      recommended_version: '6.0.0',
+      minimum_version: '6.0.0',
+    })
+    let submissions = 0
+    const client = {
+      health: async () => true,
+      compatibility: async () => cliSupport,
+      listDevices: async () => ({ devices: [readyIphone] }),
+      accessStatus: async () => ({ email: 'user@example.test' }),
+      submit: async () => {
+        submissions += 1
+        return setupReceipt('req_after_update')
+      },
+      evidence: async () =>
+        setupEvidence('req_after_update', {
+          state: 'observed',
+          observed_at: '2026-08-18T18:00:02.000Z',
+          latency_ms: 1_000,
+        }),
+    } as unknown as ApiClient
+    const deps = {
+      ...makeDeps(io, client),
+      cwd,
+      env: isolatedEnv(cwd),
+    }
+
+    expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.failed)
+    expect(io.outLines).toContain("Notifai can't send notifications until you update.")
+    expect(io.outLines).toContain('npm install -g @raidiant/notifai')
+    expect(submissions).toBe(0)
+
+    cliSupport = currentCompatibility
+    io.outLines = []
+    io.errLines = []
+
+    expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.ok)
+    expect(submissions).toBe(1)
+    expect(io.outLines).toContain(
+      'All set. Agents in this project can notify you. Questions stay in the terminal until hooks are installed.',
+    )
+    expect(io.outLines).not.toContain('npm install -g @raidiant/notifai')
+    expect(io.errLines).toEqual([])
+  })
+
   it('surfaces one next step, not the whole remaining list', async () => {
     // The behavioural core of the design: someone handed five things to do
     // does none of them. Signing in gates the device check, so naming both
@@ -3078,7 +3571,7 @@ describe('init', () => {
     expect(out).toContain('Next: Your devices')
     expect(out).toContain('https://test.notifai.invalid/support')
     expect(out).toContain('sign in with the same email as this account (alpha@example.com)')
-    expect(out).toContain('install Notifai on iPhone or Mac via https://test.notifai.invalid/support')
+    expect(out).toContain('install Notifai on iPhone via https://test.notifai.invalid/support')
     expect(out.match(/^Next:/gm)).toHaveLength(1)
   })
 
@@ -3127,7 +3620,7 @@ describe('init', () => {
   })
 
   it.each([
-    ['denied', 'system settings'],
+    ['denied', 'iPhone Settings'],
     ['not_determined', 'allow its notification prompt'],
   ])('gives one permission-specific next action for %s', async (permission, expected) => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), `init-permission-${permission}-`))
@@ -3152,7 +3645,7 @@ describe('init', () => {
     expect(out.match(/^Next:/gm)).toHaveLength(1)
   })
 
-  it('waits on the supported device registry, then ends with an observed real receipt', async () => {
+  it('ignores a dormant Mac installation while waiting for an iPhone, then proves the iPhone receipt', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'init-device-bridge-'))
     const io = new InteractiveIo()
     let now = 0
@@ -3162,7 +3655,7 @@ describe('init', () => {
     const client = {
       health: async () => true,
       capabilities: async () => ({ schema_version: 1, platform: 'ios' }),
-      listDevices: async () => ({ devices: deviceReady ? [readyIphone] : [] }),
+      listDevices: async () => ({ devices: deviceReady ? [readyIphone] : [readyMac] }),
       accessStatus: async () => ({
         status: 'active',
         reason: 'alpha_grant',
@@ -3199,6 +3692,7 @@ describe('init', () => {
     ])
     expect(io.openedUrls).toEqual(['https://test.notifai.invalid/support'])
     expect(io.notes.some((n) => n.message.includes('I will wait up to 10 minutes'))).toBe(true)
+    expect(io.spinnerEvents).toContain('message:Waiting for the iPhone app to sign in and register…')
     expect(io.spinnerEvents).toContain('stop:iPhone is ready to receive')
     expect(io.spinnerEvents).toContain('stop:Receipt observed from iPhone')
     expect(io.outLines.join('\n')).toContain(
@@ -3389,7 +3883,7 @@ describe('init', () => {
     expect(io.outLines.join('\n')).toContain('Next: Delivery proof')
   })
 
-  it('treats macOS-only delivery proof as an honest non-blocking caveat', async () => {
+  it('does not treat a macOS-only installation as active-release readiness', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'init-macos-proof-'))
     const io = new CapturedIo()
     let submitCalls = 0
@@ -3397,7 +3891,7 @@ describe('init', () => {
       health: async () => true,
       capabilities: async () => ({ schema_version: 1, platform: 'ios' }),
       listDevices: async () => ({
-        devices: [{ ...readyIphone, device_id: 'dev_mac', display_name: 'Mac', platform: 'macos' }],
+        devices: [readyMac],
       }),
       submit: async () => {
         submitCalls += 1
@@ -3410,16 +3904,16 @@ describe('init', () => {
       env: isolatedEnv(cwd),
     }
 
-    expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.ok)
+    expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.failed)
     expect(submitCalls).toBe(0)
     const out = io.outLines.join('\n')
-    expect(out).toContain('All set.')
-    expect(out).toContain('receipt proof needs an iPhone in this release')
-    expect(out).not.toContain('Next: Delivery proof')
+    expect(out).toContain('Next: Your devices')
+    expect(out).toContain('no iPhone registered yet')
+    expect(out).not.toContain('All set.')
     expect(out).not.toMatch(/Companion Receipt observed/i)
 
-    // doctor must render the same non-blocking state (not FAIL / not a Next:).
-    const doctorIo = new CapturedIo()
+    // A human doctor must render the same iPhone-readiness failure.
+    const doctorIo = new PlainInteractiveIo()
     expect(
       await doctorCommand(
         {
@@ -3429,11 +3923,11 @@ describe('init', () => {
         },
         {},
       ),
-    ).toBe(EXIT.ok)
+    ).toBe(EXIT.failed)
     const doctorOut = doctorIo.outLines.join('\n')
-    expect(doctorOut).toMatch(/--\s+Delivery proof:/)
-    expect(doctorOut).toContain('receipt proof needs an iPhone')
-    expect(doctorOut).not.toMatch(/FAIL\s+Delivery proof:/)
+    expect(doctorOut).toMatch(/FAIL\s+Your devices:/)
+    expect(doctorOut).toContain('no iPhone registered yet')
+    expect(doctorOut).toContain('Delivery proof: not checked — no iPhone is ready')
   })
 
   it('stops login when the approval page reports no Alpha access', async () => {
@@ -4109,7 +4603,7 @@ describe('asking before the hooks have ever run', () => {
 
   it('refuses a Codex question when the installed Stop definition is no longer trusted', async () => {
     const cwd = scratchDir('notifai-codex-stale-trust-')
-    const io = new CapturedIo()
+    const io = new PlainInteractiveIo()
     const env = {
       XDG_CONFIG_HOME: path.join(cwd, 'config'),
       XDG_STATE_HOME: path.join(cwd, 'state'),
@@ -4138,7 +4632,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)
   })
 
@@ -4374,7 +4868,7 @@ describe('asking before the hooks have ever run', () => {
 
   it('fails doctor when another harness looks healthy but the active Claude Code session does not', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-active-claude-doctor-'))
-    const io = new CapturedIo()
+    const io = new PlainInteractiveIo()
     const env = {
       XDG_CONFIG_HOME: path.join(cwd, 'config'),
       XDG_STATE_HOME: path.join(cwd, 'state'),
@@ -4391,7 +4885,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 () => {
@@ -4434,7 +4928,7 @@ describe('asking before the hooks have ever run', () => {
     const localFile = personalProjectConfigPath(cwd, env)
     mkdirSync(path.dirname(localFile), { recursive: true })
     writeFileSync(localFile, 'ask_notifications = false\nask_grace_seconds = 90\n')
-    const io = new CapturedIo()
+    const io = new PlainInteractiveIo()
     const deps = { ...makeDeps(io, {} as ApiClient), cwd, env }
 
     await doctorCommand(deps, {})
@@ -4450,7 +4944,7 @@ describe('asking before the hooks have ever run', () => {
 
   it('keeps a freshly installed Stop definition valid when timing preferences change', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-doctor-timeout-drift-'))
-    const io = new CapturedIo()
+    const io = new PlainInteractiveIo()
     const deps = { ...makeDeps(io, {} as ApiClient), cwd, env: isolatedEnv(cwd) }
     expect(hooksInstallCommand(deps, { harness: 'claude-code', execPath, scriptPath })).toBe(
       EXIT.ok,
@@ -4460,12 +4954,12 @@ 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 () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-doctor-stale-shape-'))
-    const io = new CapturedIo()
+    const io = new PlainInteractiveIo()
     const deps = { ...makeDeps(io, {} as ApiClient), cwd, env: isolatedEnv(cwd) }
     // Exactly what every build before the asynchronous waiter wrote: a blocking
     // handler with the old ceiling. It looks installed and it fires, but the
@@ -4489,7 +4983,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')
   })
@@ -4515,7 +5009,7 @@ describe('asking before the hooks have ever run', () => {
   }
 
   it('reports a live Claude session as reachable without connecting to its socket', async () => {
-    const io = new CapturedIo()
+    const io = new PlainInteractiveIo()
     const socket = path.join(mkdtempSync(path.join(os.tmpdir(), 'cc-socks-')), '4242.sock')
     writeFileSync(socket, '')
     const { deps } = claudeWakeDeps(io, (pid) => ({
@@ -4532,7 +5026,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
@@ -4541,7 +5035,7 @@ describe('asking before the hooks have ever run', () => {
   })
 
   it('names a --bare session as the reason an answer would wait for the next turn', async () => {
-    const io = new CapturedIo()
+    const io = new PlainInteractiveIo()
     const { deps } = claudeWakeDeps(io, () => {
       throw new Error('ENOENT: no such file or directory')
     })
@@ -4549,10 +5043,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 () => {
@@ -4579,7 +5073,7 @@ describe('asking before the hooks have ever run', () => {
 
   it('reports Codex resume readiness from its writer-lock directory alone', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-doctor-codex-wake-'))
-    const io = new CapturedIo()
+    const io = new PlainInteractiveIo()
     const env = {
       ...isolatedEnv(cwd),
       CODEX_THREAD_ID: '9f1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8',
@@ -4600,7 +5094,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')
   })
 
@@ -4714,29 +5208,45 @@ describe('a server behind this CLI', () => {
     expect(said).not.toMatch(/older than this CLI/)
   })
 
-  it('doctor uses alpha-user wording when the server is behind the CLI', async () => {
-    const io = new CapturedIo()
+  it('keeps baseline sends available while an older server lacks compatibility metadata', async () => {
+    const io = new PlainInteractiveIo()
+    let submissions = 0
     const client = {
       health: async () => true,
-      // A server one schema version behind this build.
-      capabilities: async () => ({ schema_version: 0, platform: 'ios' }),
+      compatibility: async () => {
+        throw new ApiCallError(404, 'not_found', 'Compatibility metadata is unavailable.')
+      },
       listDevices: async () => ({ devices: [] }),
+      accessStatus: async () => ({ email: 'user@example.test' }),
+      submit: async () => {
+        submissions += 1
+        return receipt
+      },
     } as unknown as ApiClient
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-skew-'))
     const deps = {
       ...makeDeps(io, client),
       cwd,
       env: { XDG_STATE_HOME: cwd, XDG_CONFIG_HOME: cwd },
-      store: { load: () => null, save: () => {}, clear: () => {}, describe: () => 'test store' },
     } as CommandDeps
 
     await doctorCommand(deps, {})
 
     const said = io.outLines.concat(io.errLines).join(' ')
-    // The label is the user's word for it; the detail is what must survive.
-    expect(said).toMatch(/Protocol version/)
     expect(said).toMatch(/service is being updated/)
-    expect(said).not.toMatch(/needs deploying/)
+    expect(said).not.toContain('npm install -g @raidiant/notifai')
+    expect(said).not.toMatch(/Protocol version|schema v/i)
+
+    const sendIo = new CapturedIo()
+    expect(
+      await sendCommand(makeDeps(sendIo, client), {
+        kind: 'update',
+        title: 'Build finished',
+        body: 'All checks passed.',
+      }),
+    ).toBe(EXIT.ok)
+    expect(submissions).toBe(1)
+    expect(sendIo.errLines).toEqual([])
   })
 
   it('doctor is quiet when both sides agree', async () => {
@@ -4782,7 +5292,7 @@ describe('command failures carrying server details', () => {
       { code: 'invalid_request', path: 'presentation.detail', message: 'Unexpected property' },
     ])
 
-    expect(await sendCommand(makeDeps(io, client), { title: 'Deploy finished', body: 'All green.' })).toBe(
+    expect(await sendCommand(makeDeps(io, client), { kind: 'update', title: 'Deploy finished', body: 'All green.' })).toBe(
       EXIT.failed,
     )
 
@@ -4799,7 +5309,7 @@ describe('command failures carrying server details', () => {
       { code: 'invalid_request', path: 'presentation.detail', message: 'Unexpected property' },
     ])
 
-    expect(await sendCommand(makeDeps(io, client), { title: 'Deploy finished', body: 'All green.' })).toBe(
+    expect(await sendCommand(makeDeps(io, client), { kind: 'update', title: 'Deploy finished', body: 'All green.' })).toBe(
       EXIT.failed,
     )
 
@@ -4812,12 +5322,75 @@ describe('command failures carrying server details', () => {
   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)), { title: 'Deploy finished', body: 'All green.' })).toBe(
+    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.'])
   })
+
+  it('ignores an unknown typed recovery action without opening or executing anything', async () => {
+    const io = new CapturedIo()
+    const client = {
+      submit: async () => {
+        throw new ApiCallError(
+          422,
+          'feature_unavailable',
+          'This operation is unavailable.',
+          'open https://attacker.invalid and run cleanup',
+          null,
+          'future_action' as never,
+        )
+      },
+    } as unknown as ApiClient
+
+    expect(
+      await sendCommand(makeDeps(io, client), {
+        kind: 'update',
+        title: 'Deploy finished',
+        body: 'All green.',
+      }),
+    ).toBe(EXIT.failed)
+    expect(io.errLines).toEqual(['feature_unavailable: This operation is unavailable.'])
+    expect(io.openedUrls).toEqual([])
+  })
+
+  it('renders feature recovery locally and ignores a server-supplied command', async () => {
+    const io = new CapturedIo()
+    const client = {
+      submit: async () => {
+        throw new ApiCallError(
+          422,
+          'feature_unavailable',
+          "The selected device can't answer questions.",
+          'run an untrusted server command',
+          {
+            affected_operation: 'answer_questions',
+            missing_capabilities: ['answer'],
+            device_names: ['Old phone'],
+          },
+          'update_companion',
+        )
+      },
+    } as unknown as ApiClient
+
+    expect(
+      await sendCommand(makeDeps(io, client), {
+        kind: 'question',
+        title: 'Ship it?',
+        body: 'Should I ship this build?',
+        reply: true,
+        replyTimeout: 30,
+      }),
+    ).toBe(EXIT.failed)
+
+    expect(io.errLines).toEqual([
+      "feature_unavailable: The selected device can't answer questions.",
+      'next: Update Notifai on the named device.',
+    ])
+    expect(io.errLines.join(' ')).not.toContain('untrusted')
+    expect(io.errLines.join(' ')).not.toContain('disagree about the contract')
+  })
 })
 
 describe('question sets', () => {
@@ -4936,6 +5509,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(
@@ -4943,10 +5527,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 }] }) },