@raidiant/notifai 9.3.0 → 10.0.0

package/src/commands.test.ts

@@ -1,4 +1,6 @@
 import { CAPABILITIES_V1, PLATFORMS, REPLY_MAX_QUESTIONS } from '@raidiant/notifai-protocol'
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
 import {
   existsSync,
   mkdirSync,
@@ -56,6 +58,7 @@ import {
   repliesCommand,
   sendCommand,
   statusCommand,
+  agentSessionRenameCommand,
   type CommandDeps,
   type CommandIo,
   type CommandSpinner,
@@ -763,6 +766,28 @@ describe('command contracts', () => {
     expect(io.errLines).toEqual([])
   })
 
+  it('sends an Account custom sound name on the draft', async () => {
+    const io = new CapturedIo()
+    let submitted: SubmitNotificationRequestT | undefined
+    const client = {
+      submit: async (body: SubmitNotificationRequestT) => {
+        submitted = body
+        return receipt
+      },
+    } as unknown as ApiClient
+
+    expect(
+      await sendCommand(makeDeps(io, client), {
+        kind: 'done',
+        title: 'Build finished',
+        body: 'All checks passed.',
+        sound: 'Kitchen timer',
+      }),
+    ).toBe(EXIT.ok)
+    expect(submitted?.draft.platform?.ios?.sound).toBe('Kitchen timer')
+    expect(submitted?.draft.platform?.android?.sound).toBe('Kitchen timer')
+  })
+
   it('prints Android downgrade warnings before submitting', async () => {
     const io = new CapturedIo()
     let submitCalls = 0
@@ -856,7 +881,7 @@ describe('command contracts', () => {
     expect(io.errLines.join('\n')).not.toContain('opaque-claude-session-42')
   })
 
-  it('never promotes an Orca worktree title into an Agent Session label', async () => {
+  it('uses trusted Orca task context for an active Claude Agent Session label', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-orca-claude-title-'))
     const io = new CapturedIo()
     let submitted: SubmitNotificationRequestT | undefined
@@ -879,6 +904,7 @@ describe('command contracts', () => {
       ...makeDeps(io, client),
       cwd,
       env,
+      orcaSessionTitle: () => 'Agent Session context labels',
     }
 
     expect(
@@ -891,13 +917,12 @@ describe('command contracts', () => {
 
     expect(submitted?.draft.source).toMatchObject({
       session_id: 'orca-claude-session',
+      session_label: 'Agent Session context labels',
       harness: 'claude-code',
     })
-    expect(submitted?.draft.source?.session_label).toMatch(/^[A-Z][a-z]+ [A-Z][a-z]+$/)
-    expect(submitted?.draft.source?.session_label).not.toBe('Worker - semantic session implementation')
   })
 
-  it('never treats an Orca worktree title as a Codex Agent Session label', async () => {
+  it('uses trusted Orca task context for an active Codex Agent Session label', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-orca-codex-title-'))
     const io = new CapturedIo()
     let submitted: SubmitNotificationRequestT | undefined
@@ -918,6 +943,7 @@ describe('command contracts', () => {
         TERM_PROGRAM: 'Orca',
         ORCA_WORKTREE_ID: worktreeId,
       },
+      orcaSessionTitle: () => 'Release verification',
     }
 
     expect(
@@ -930,9 +956,77 @@ describe('command contracts', () => {
 
     expect(submitted?.draft.source).toMatchObject({
       session_id: 'orca-codex-thread',
+      session_label: 'Release verification',
       harness: 'codex',
     })
-    expect(submitted?.draft.source?.session_label).toMatch(/^[A-Z][a-z]+ [A-Z][a-z]+$/)
+  })
+
+  it('sends after isolating an invalid session-name record without losing valid names', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-invalid-session-name-'))
+    const io = new CapturedIo()
+    const env = {
+      XDG_CONFIG_HOME: path.join(cwd, 'config'),
+      XDG_STATE_HOME: path.join(cwd, 'state'),
+      CODEX_THREAD_ID: 'current-session',
+    }
+    const file = path.join(stateDir(env), 'session-labels.json')
+    const validKey = createHash('sha256').update('unrelated-session').digest('hex')
+    mkdirSync(path.dirname(file), { recursive: true })
+    writeFileSync(
+      file,
+      `${JSON.stringify(
+        {
+          version: 1,
+          sessions: {
+            [validKey]: {
+              label: 'Unrelated work',
+              source: 'explicit',
+              first_seen_at: 1_777_777_777_000,
+              harness: 'codex',
+            },
+            obsolete: {
+              label: 'Old shape',
+              source: 'legacy',
+              first_seen_at: 'unknown',
+            },
+          },
+        },
+        null,
+        2,
+      )}\n`,
+    )
+
+    let submitted: SubmitNotificationRequestT | undefined
+    const client = {
+      submit: async (body: SubmitNotificationRequestT) => {
+        submitted = body
+        return receipt
+      },
+    } as unknown as ApiClient
+
+    expect(
+      await sendCommand(
+        { ...makeDeps(io, client), cwd, env },
+        { title: 'Store recovered', body: 'The valid Agent Session name survived.', kind: 'done' },
+      ),
+    ).toBe(EXIT.ok)
+    expect(submitted?.draft.source).toMatchObject({
+      session_id: 'current-session',
+      harness: 'codex',
+    })
+
+    const recovered = JSON.parse(readFileSync(file, 'utf8')) as {
+      sessions: Record<string, { label: string }>
+    }
+    expect(recovered.sessions[validKey]?.label).toBe('Unrelated work')
+    expect(recovered.sessions['obsolete']).toBeUndefined()
+    const backups = readdirSync(path.dirname(file)).filter((name) =>
+      /^session-labels\.invalid-[a-f0-9]{64}\.json$/u.test(name),
+    )
+    expect(backups).toHaveLength(1)
+    expect(readFileSync(path.join(path.dirname(file), backups[0]!), 'utf8')).toContain(
+      '"obsolete"',
+    )
   })
 
   it('falls back safely when Orca returns a private path as its title', async () => {
@@ -1041,6 +1135,113 @@ describe('command contracts', () => {
     expect(existsSync(path.join(cwd, 'state', 'notifai', 'session-labels.json'))).toBe(false)
   })
 
+  it('sends Hermes Source Context from HERMES_SESSION_ID and the invocation cwd', async () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-hermes-send-'))
+    const repo = path.join(root, 'notifai')
+    const worktree = path.join(root, 'hermes-topic')
+    mkdirSync(repo)
+    const git = (...args: string[]) => execFileSync('git', ['-C', repo, ...args], { stdio: 'ignore' })
+    git('init')
+    git('config', 'user.email', 'test@example.invalid')
+    git('config', 'user.name', 'Test')
+    git('config', 'commit.gpgsign', 'false')
+    writeFileSync(path.join(repo, 'file'), 'x')
+    git('add', 'file')
+    git('commit', '-m', 'fixture')
+    git('worktree', 'add', worktree, '-b', 'feature/hermes-send')
+
+    const io = new CapturedIo()
+    let submitted: SubmitNotificationRequestT | undefined
+    const client = {
+      submit: async (body: SubmitNotificationRequestT) => {
+        submitted = body
+        return receipt
+      },
+    } as unknown as ApiClient
+    const sessionId = '20260828_111302_29a404'
+    const deps = {
+      ...makeDeps(io, client),
+      cwd: worktree,
+      env: {
+        ...isolatedEnv(worktree),
+        HERMES_SESSION_ID: sessionId,
+      },
+    }
+
+    expect(
+      await sendCommand(deps, {
+        title: 'Hermes baseline landed',
+        body: 'Classic CLI send carries exact session identity.',
+        kind: 'done',
+      }),
+    ).toBe(EXIT.ok)
+
+    expect(submitted?.draft.source).toMatchObject({
+      session_id: sessionId,
+      harness: 'hermes',
+      branch: 'feature/hermes-send',
+      worktree: 'hermes-topic',
+    })
+    expect(io.outLines.join('\n')).not.toContain(sessionId)
+
+    submitted = undefined
+    expect(
+      await sendCommand(
+        {
+          ...deps,
+          env: {
+            ...deps.env,
+            HERMES_SESSION_KEY: 'gateway-route-key-must-not-be-session-id',
+          },
+        },
+        {
+          title: 'Hermes deferred surface sent',
+          body: 'The send stays universal while unproven Source Context is omitted.',
+          kind: 'done',
+        },
+      ),
+    ).toBe(EXIT.ok)
+    expect(submitted?.draft.source).toMatchObject({
+      branch: 'feature/hermes-send',
+      worktree: 'hermes-topic',
+    })
+    expect(submitted?.draft.source).not.toHaveProperty('session_id')
+    expect(submitted?.draft.source).not.toHaveProperty('harness')
+    expect(JSON.stringify(submitted?.draft.source)).not.toContain('gateway-route-key')
+  })
+
+  it('does not attribute Hermes Source Context when another harness marker is nested', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-hermes-nested-send-'))
+    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: {
+        ...isolatedEnv(cwd),
+        CLAUDECODE: '1',
+        CLAUDE_CODE_SESSION_ID: 'claude-orchestrator',
+        HERMES_SESSION_ID: '20260828_111302_29a404',
+      },
+    }
+
+    expect(
+      await sendCommand(deps, {
+        title: 'Nested send stays honest',
+        body: 'Ambiguous ownership omits harness identity.',
+        kind: 'update',
+      }),
+    ).toBe(EXIT.ok)
+    expect(submitted?.draft.source?.harness).toBeUndefined()
+    expect(submitted?.draft.source?.session_id).toBeUndefined()
+  })
+
   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')
@@ -1198,6 +1399,8 @@ describe('command contracts', () => {
     // 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).toContain('Device default')
+    expect(source).toContain('custom name or id')
     expect(source).not.toContain('it never chooses banner sound or interruption level')
     expect(source).not.toContain('Kind profiles apply automatically')
   })
@@ -3539,19 +3742,20 @@ describe('config surfaces', () => {
     expect(io.errLines[0]).toBe('Unknown setting "ask_notification".')
   })
 
-  it('refuses an enum value the sender would later reject', async () => {
-    // `config set sound whatever` used to be written straight to disk: the
-    // typo only surfaced when a notification failed to carry the sound.
+  it('refuses a sound that cannot be a shipped name, custom id, or custom name', async () => {
     const io = new CapturedIo()
-    expect(await configSetCommand(configDeps(io), 'sound', 'whatever', { yes: true })).toBe(
+    expect(await configSetCommand(configDeps(io), 'sound', 'n'.repeat(200), { yes: true })).toBe(
       EXIT.usage,
     )
-    expect(io.errLines[0]).toContain('default, done, attention, alert, none')
+    expect(io.errLines[0]).toContain('custom sound')
   })
 
-  it('still accepts a legal enum value', async () => {
+  it('accepts a shipped sound and an Account custom name', async () => {
     const io = new CapturedIo()
     expect(await configSetCommand(configDeps(io), 'sound', 'none', { yes: true })).toBe(EXIT.ok)
+    expect(await configSetCommand(configDeps(io), 'sound', 'Kitchen timer', { yes: true })).toBe(
+      EXIT.ok,
+    )
   })
 
   it('removes one machine setting, preserves its siblings, and restores default provenance', async () => {
@@ -6519,6 +6723,92 @@ describe('asking before the hooks have ever run', () => {
     expect(readSessionState('opencode-current', env).pending).toBeUndefined()
   })
 
+  it('refuses Hermes ask as unsupported rather than as missing hooks', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-hermes-ask-unsupported-'))
+    const io = new CapturedIo()
+    const env = {
+      ...isolatedEnv(cwd),
+      HERMES_SESSION_ID: '20260828_111302_29a404',
+    }
+    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env, now: () => 42 }
+
+    expect(askCommand(deps, 'Ship it?', { json: true })).toBe(EXIT.usage)
+    const payload = JSON.parse(io.outLines.join('\n')) as { code: string; message: string; remedy: string }
+    expect(payload.code).toBe('question_routing_unavailable')
+    expect(payload.message).toMatch(/no proven continuation owner/i)
+    expect(payload.message).not.toMatch(/hooks are not installed/i)
+    expect(payload.remedy).toMatch(/send --reply/)
+    expect(hooksInstallCommand(deps, { harness: 'hermes', execPath, scriptPath })).toBe(EXIT.usage)
+    expect(io.errLines.join('\n')).toMatch(/Unknown harness "hermes"/)
+  })
+
+  it('fails closed when Hermes nested markers leave session ownership ambiguous', () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-hermes-nested-ask-'))
+    const io = new CapturedIo()
+    const env = {
+      ...isolatedEnv(cwd),
+      CLAUDECODE: '1',
+      CLAUDE_CODE_SESSION_ID: 'claude-orchestrator',
+      HERMES_SESSION_ID: '20260828_111302_29a404',
+    }
+    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env, now: () => 42 }
+    expect(hooksInstallCommand(deps, { harness: 'claude-code', execPath, scriptPath })).toBe(EXIT.ok)
+    writeSessionState('claude-orchestrator', env, {
+      harness: 'claude-code',
+      last_prompt_at: 42,
+      last_stop_at: 41,
+    })
+    writeProjectSession(cwd, env, 'claude-orchestrator', 42, 'claude-code')
+    io.outLines = []
+    io.errLines = []
+
+    expect(askCommand(deps, 'Ship it?', { json: true })).toBe(EXIT.usage)
+    const payload = JSON.parse(io.outLines.join('\n')) as { code: string; message: string }
+    expect(payload.code).toBe('session_identity_ambiguous')
+    expect(payload.message).toMatch(/Several harness sessions could own this shell/i)
+    expect(payload.message).toMatch(/Hermes/)
+    expect(readSessionState('claude-orchestrator', env).pending).toBeUndefined()
+  })
+
+  it('does not attribute doctor readiness when Hermes nested markers are ambiguous', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-hermes-nested-doctor-'))
+    const io = new CapturedIo()
+    const env = {
+      ...isolatedEnv(cwd),
+      CLAUDECODE: '1',
+      CLAUDE_CODE_SESSION_ID: 'claude-orchestrator',
+      HERMES_SESSION_ID: '20260828_111302_29a404',
+    }
+    const readiness = await assessReadiness({
+      ...makeDeps(io, {} as ApiClient),
+      cwd,
+      env,
+      now: () => 42,
+    })
+    const hooks = readiness.states.find((state) => state.id === 'hooks')
+    expect(hooks?.status).toBe('optional-gap')
+    expect(hooks?.detail).toMatch(/Several harness sessions could own this shell/i)
+    expect(hooks?.detail).toMatch(/Claude Code, Hermes/)
+    expect(hooks?.remedy).toBeUndefined()
+    expect(JSON.stringify(hooks)).not.toContain('hooks install --harness claude-code')
+  })
+
+  it('does not tell an active Hermes session to install managed hooks', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-hermes-doctor-'))
+    const io = new CapturedIo()
+    const env = {
+      ...isolatedEnv(cwd),
+      HERMES_SESSION_ID: '20260828_111302_29a404',
+    }
+    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env, now: () => 42 }
+    const readiness = await assessReadiness(deps)
+    const hooks = readiness.states.find((state) => state.id === 'hooks')
+    expect(hooks?.status).toBe('optional-gap')
+    expect(hooks?.remedy).toBeUndefined()
+    expect(JSON.stringify(hooks)).not.toContain('hooks install --harness hermes')
+    expect(hooks?.detail).toMatch(/no proven continuation owner/i)
+  })
+
   it('refuses Cursor when its active-agent marker has no exact conversation id', () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-active-cursor-'))
     const io = new CapturedIo()
@@ -7314,3 +7604,46 @@ describe('a second device that disagrees', () => {
     expect(contradictingAnswer([])).toBeNull()
   })
 })
+
+describe('Agent Session rename command', () => {
+  it('renames only the exact active Agent Session and updates its local frozen label', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-session-rename-'))
+    const io = new CapturedIo()
+    const seen: { session_id: string; label: string }[] = []
+    const client = {
+      putAgentSessionLabel: async (body: { session_id: string; label: string }) => {
+        seen.push(body)
+        return {
+          ...body,
+          renamed_by: 'agent' as const,
+          updated_at: '2026-08-28T10:00:00.000Z',
+        }
+      },
+    } 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'),
+        CODEX_THREAD_ID: '01a04789-9589-76b2-82c8-bfe63062c867',
+      },
+    }
+
+    expect(await agentSessionRenameCommand(deps, '  Hermes   Runtime Support  ')).toBe(EXIT.ok)
+    expect(seen).toEqual([{
+      session_id: '01a04789-9589-76b2-82c8-bfe63062c867',
+      label: 'Hermes Runtime Support',
+    }])
+    expect(io.outLines.join('\n')).toContain('Hermes Runtime Support')
+  })
+
+  it('fails closed when the harness does not expose an exact current Agent Session', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-session-rename-none-'))
+    const io = new CapturedIo()
+    const deps = { ...makeDeps(io, {} as ApiClient), cwd, env: isolatedEnv(cwd) }
+
+    expect(await agentSessionRenameCommand(deps, 'A new job')).toBe(EXIT.usage)
+    expect(io.errLines.join('\n')).toMatch(/exact active Agent Session/i)
+  })
+})

package/src/commands.ts

@@ -17,6 +17,7 @@ export {
   deviceInventory,
   devicesCommand,
 } from './commands-devices.js'
+export { soundsCommand } from './commands-sounds.js'
 export {
   contradictingAnswer,
   repliesCommand,
@@ -67,4 +68,8 @@ export {
   projectEnableCommand,
   projectStatusCommand,
 } from './commands-project.js'
+export {
+  agentSessionRenameCommand,
+  type AgentSessionRenameFlags,
+} from './commands-agent-sessions.js'
 export { realIo } from './commands-io.js'

package/src/config-schema.test.ts

@@ -70,6 +70,7 @@ describe('acceptedValues', () => {
 
   it('lists the choices for an enum', () => {
     expect(acceptedValues('sound')).toContain('none')
+    expect(acceptedValues('sound')).toContain('custom sound')
   })
 
   it('names both values for a toggle', () => {

package/src/config-schema.ts

@@ -121,7 +121,7 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     kind: 'enum',
     choices: CLI_SOUNDS,
     choiceHints: {
-      default: 'the standard notification tone',
+      default: 'Device default',
       done: 'the completion chime',
       attention: 'a distinct attention tone',
       alert: 'the most insistent tone',
@@ -129,7 +129,7 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     },
     summary: 'Set the sound notifications from here use',
     detail:
-      'Setting this pins one sound for every notification sent from here, whatever kind it is.\n\nLeave it unset and each notification arrives with the sound its kind implies: the completion chime when work finished, the most insistent tone when it failed, a distinct attention tone for a question or blocked work, and the standard tone for ordinary news. A common explicit preference is `none`, to make a noisy project completely silent.',
+      'Setting this pins one sound for every notification sent from here, whatever kind it is. Shipped names are `default` (Device default), `done`, `attention`, `alert`, and `none`; an Account custom sound name or id from `notifai sounds` is accepted too.\n\nLeave it unset and each notification arrives with the sound its kind implies: the completion chime when work finished, the most insistent tone when it failed, a distinct attention tone for a question or blocked work, and Device default for ordinary news. A common explicit preference is `none`, to make a noisy project completely silent.',
     unsetMeans: 'not set; each kind brings its own sound',
   },
   interruption_level: {
@@ -281,6 +281,9 @@ export function boundsHint(key: ConfigKey): string | null {
 /** What a `config set` caller may legally pass, phrased for an error message. */
 export function acceptedValues(key: ConfigKey): string {
   const info = INFO[key]
+  if (key === 'sound') {
+    return `${CLI_SOUNDS.join(', ')}, a custom sound id, or a custom sound name`
+  }
   switch (info.kind) {
     case 'boolean':
       return 'true or false'

package/src/config.test.ts

@@ -177,14 +177,29 @@ describe('config precedence', () => {
     expect(config.wait_seconds.source).toBe('flag')
   })
 
-  it('uses the prior default when a newer CLI wrote an unknown enum value', () => {
+  it('uses the prior default when a newer CLI wrote an unknown interruption level', () => {
     const { env, cwd } = setup({
-      globalToml: 'sound = "future-sound"\ninterruption_level = "future-level"\n',
+      globalToml: 'interruption_level = "future-level"\n',
     })
     const config = loadConfig({ cwd, env })
-    expect(config.sound).toEqual({ value: null, source: 'default' })
     expect(config.interruption_level).toEqual({ value: null, source: 'default' })
   })
+
+  it('keeps a custom sound name written by the user', () => {
+    const { env, cwd } = setup({
+      globalToml: 'sound = "Kitchen timer"\n',
+    })
+    const config = loadConfig({ cwd, env })
+    expect(config.sound).toEqual({ value: 'Kitchen timer', source: expect.stringMatching(/^global:/) })
+  })
+
+  it('drops a sound value that cannot be a name or id', () => {
+    const { env, cwd } = setup({
+      globalToml: `sound = "${'n'.repeat(200)}"\n`,
+    })
+    const config = loadConfig({ cwd, env })
+    expect(config.sound).toEqual({ value: null, source: 'default' })
+  })
 })
 
 describe('draft building', () => {
@@ -199,29 +214,23 @@ describe('draft building', () => {
       presentation: { title: 'T', body: 'B' },
       targets: { mode: 'all' },
       delivery: { ttl_seconds: 86400, collapse_key: null },
-      // An unlabelled draft is ordinary news, and news has a sound.
-      platform: {
-        ios: { sound: 'default' },
-        macos: { sound: 'default' },
-        android: { sound: 'default' },
-      },
     })
   })
 
   it.each([
-    { flags: {}, sound: 'default' },
-    { flags: { kind: 'update' }, sound: 'default' },
-    { flags: { kind: 'done' }, sound: 'done' },
-    { flags: { kind: 'failed' }, sound: 'alert' },
-    { flags: { kind: 'blocked' }, sound: 'attention' },
-    { flags: { kind: 'question' }, sound: 'attention' },
-    { flags: { reply: true }, sound: 'attention' },
-  ])('gives $flags the $sound sound when nobody chose one', ({ flags, sound }) => {
+    { flags: {} },
+    { flags: { kind: 'update' } },
+    { flags: { kind: 'done' } },
+    { flags: { kind: 'failed' } },
+    { flags: { kind: 'blocked' } },
+    { flags: { kind: 'question' } },
+    { flags: { reply: true } },
+  ])('omits sound from the draft for $flags so the server can resolve it', ({ flags }) => {
     const config = loadConfig({ cwd: base.cwd, env: base.env })
     const build = buildDraft(config, { title: 'T', body: 'B', ...flags })
     if (!build.ok) throw new Error(build.error)
-    expect(build.draft.platform?.ios?.sound).toBe(sound)
-    expect(build.draft.platform?.android?.sound).toBe(sound)
+    expect(build.draft.platform?.ios?.sound).toBeUndefined()
+    expect(build.draft.platform?.android?.sound).toBeUndefined()
     expect(build.draft.platform?.ios?.interruption_level).toBeUndefined()
   })
 
@@ -551,9 +560,22 @@ describe('draft building', () => {
   it('rejects malformed inputs with usage errors', () => {
     const config = loadConfig({ cwd: base.cwd, env: base.env })
     expect(buildDraft(config, { title: '', body: 'B' }).ok).toBe(false)
-    expect(buildDraft(config, { title: 'T', body: 'B', sound: 'airhorn' }).ok).toBe(false)
+    expect(buildDraft(config, { title: 'T', body: 'B', sound: 'n'.repeat(200) }).ok).toBe(false)
     expect(buildDraft(config, { title: 'T', body: 'B', data: ['nokey'] }).ok).toBe(false)
     expect(buildDraft(config, { title: 'T', body: 'B', level: 'shouting' }).ok).toBe(false)
     expect(buildDraft(config, { title: 'T', body: 'B', platform: 'linux' }).ok).toBe(false)
   })
+
+  it('puts a custom sound name on the draft for the server to resolve', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    const byName = buildDraft(config, { title: 'T', body: 'B', sound: 'airhorn' })
+    if (!byName.ok) throw new Error(byName.error)
+    expect(byName.draft.platform?.ios?.sound).toBe('airhorn')
+    expect(byName.draft.platform?.android?.sound).toBe('airhorn')
+
+    const byId = buildDraft(config, { title: 'T', body: 'B', sound: 'snd_01HQTEST' })
+    if (!byId.ok) throw new Error(byId.error)
+    expect(byId.draft.platform?.ios?.sound).toBe('snd_01HQTEST')
+    expect(byId.draft.platform?.android?.sound).toBe('snd_01HQTEST')
+  })
 })

package/src/config.ts

@@ -1,5 +1,4 @@
 import {
-  CLI_SOUNDS,
   INTERRUPTION_LEVELS,
   REPLY_MAX_WINDOW_SECONDS,
 } from '@raidiant/notifai-protocol'
@@ -8,6 +7,7 @@ import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import path from 'node:path'
 import { parse as parseToml } from 'smol-toml'
 import { configHome, stateHome } from './platform.js'
+import { isCliSoundRef } from './sound-ref.js'
 import { normalizeOrigin } from './url-policy.js'
 
 /**
@@ -41,7 +41,6 @@ export interface ResolvedValue<T> {
   source: ConfigSource
 }
 
-type CliSound = (typeof CLI_SOUNDS)[number]
 type CliInterruptionLevel = (typeof INTERRUPTION_LEVELS)[number]
 
 /**
@@ -58,7 +57,7 @@ export interface CliConfig {
   ttl_seconds: ResolvedValue<number>
   collapse_key: ResolvedValue<string | null>
   devices: ResolvedValue<string[] | null>
-  sound: ResolvedValue<CliSound | null>
+  sound: ResolvedValue<string | null>
   interruption_level: ResolvedValue<CliInterruptionLevel | null>
   /** Project identifier stamped on sends; typically set in .notifai/config.toml. */
   project: ResolvedValue<string | null>
@@ -159,7 +158,6 @@ export const NUMERIC_CONFIG_KEYS: readonly ConfigKey[] = [
  * is the same discipline the numeric bounds follow.
  */
 export const ENUM_CONFIG_VALUES: Partial<Record<ConfigKey, readonly string[]>> = {
-  sound: CLI_SOUNDS,
   interruption_level: INTERRUPTION_LEVELS,
   log_level: LOG_LEVELS,
 }
@@ -365,6 +363,9 @@ function coerce(key: ConfigKey, value: unknown): unknown | undefined {
     const origins = value.map((entry) => (typeof entry === 'string' ? normalizeOrigin(entry) : null))
     return origins.every((origin): origin is string => origin !== null) ? origins : undefined
   }
+  if (key === 'sound') {
+    return typeof value === 'string' && isCliSoundRef(value) ? value : undefined
+  }
   const allowed = ENUM_CONFIG_VALUES[key]
   if (allowed !== undefined) {
     return typeof value === 'string' && allowed.includes(value) ? value : undefined
@@ -390,7 +391,7 @@ export interface FlagOverrides {
   ttl_seconds?: number
   collapse_key?: string | null
   devices?: string[]
-  sound?: CliSound
+  sound?: string
   interruption_level?: CliInterruptionLevel
 }