@raidiant/notifai 9.3.0 → 10.1.0

package/src/program.ts

@@ -4,6 +4,7 @@ import {
   acknowledgeCommand,
   askCommand,
   accessStatusCommand,
+  agentSessionRenameCommand,
   authStatusCommand,
   capabilitiesCommand,
   closeCommand,
@@ -30,11 +31,12 @@ import {
   repliesCommand,
   reportAskFailure,
   sendCommand,
+  soundsCommand,
   statusCommand,
   type CommandDeps,
 } from './commands.js'
 import { packageVersion } from './release.js'
-import { HARNESSES } from './install-hooks.js'
+import { HOOK_INSTALLABLE_HARNESSES } from './harnesses.js'
 import type { Platform } from '@raidiant/notifai-protocol'
 import type { SkillScope } from './native-skills.js'
 import { GROUP, SEND_GROUP, helpConfiguration, rootHelpFooter } from './ui/help.js'
@@ -83,10 +85,12 @@ const defaultRunners = {
   authStatus: authStatusCommand,
   accessStatus: accessStatusCommand,
   devices: devicesCommand,
+  sounds: soundsCommand,
   capabilities: capabilitiesCommand,
   projectEnable: projectEnableCommand,
   projectDisable: projectDisableCommand,
   projectStatus: projectStatusCommand,
+  agentSessionRename: agentSessionRenameCommand,
   send: sendCommand,
   replies: repliesCommand,
   acknowledge: acknowledgeCommand,
@@ -176,11 +180,12 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
   /**
    * Bare `notifai`.
    *
-   * At a human terminal this opens the interactive app; anywhere else it prints
-   * help exactly as before. The check is the same one every other prompt in this
-   * CLI is gated on — stdin and stdout both TTYs, not CI, `NOTIFAI_NO_INPUT`
-   * unset — because an agent that reaches a prompt does not fail, it hangs
-   * for ever waiting on a stdin nobody is typing into.
+   * At a human terminal this opens the interactive app, which enters `init`
+   * when the machine is not yet paired and otherwise offers daily actions.
+   * Anywhere else it prints help exactly as before. The check is the same one
+   * every other prompt in this CLI is gated on — stdin and stdout both TTYs,
+   * not CI, `NOTIFAI_NO_INPUT` unset — because an agent that reaches a prompt
+   * does not fail, it hangs for ever waiting on a stdin nobody is typing into.
    */
   /**
    * An unrecognised subcommand reaches the root as an excess argument, and
@@ -271,9 +276,24 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     exit(runners.projectStatus(deps, opts.json === true))
   })
 
+  const session = program
+    .command('session')
+    .helpGroup(GROUP.agent)
+    .summary('Inspect or rename the current Agent Session')
+    .description('Operate on the exact Agent Session owned by the active harness')
+  session
+    .command('rename <label>')
+    .description(
+      'Rename this exact Agent Session; agents use this only after its job changes completely enough that the old label would mislead',
+    )
+    .option('--json', 'machine-readable output')
+    .action(async (label: string, opts: { json?: boolean }) => {
+      exit(await runners.agentSessionRename(deps, label, opts))
+    })
+
   program
     .command('login')
-    .helpGroup(GROUP.start)
+    .helpGroup(GROUP.advanced)
     .summary('Sign in and pair this machine')
     .description('Pair this machine with your Notifai account via browser approval')
     .option('--name <name>', 'machine name shown in the dashboard (default: hostname)')
@@ -323,6 +343,18 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
       exit(await runners.devices(deps, opts))
     })
 
+  program
+    .command('sounds')
+    .helpGroup(GROUP.daily)
+    .summary('List shipped and Account custom sounds')
+    .description(
+      'List the sounds --sound and the saved sound key accept: shipped names and this Account\'s custom sounds',
+    )
+    .option('--json', 'machine-readable output')
+    .action(async (opts: { json?: boolean }) => {
+      exit(await runners.sounds(deps, opts))
+    })
+
   program
     .command('capabilities')
     .helpGroup(GROUP.advanced)
@@ -389,7 +421,10 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     )
     .option('--multi', 'with --choice, several answers may be selected')
     .optionsGroup(SEND_GROUP.advanced)
-    .option('--sound <sound>', 'override saved sound: default | done | attention | alert | none')
+    .option(
+      '--sound <sound>',
+      'override saved sound: default | done | attention | alert | none, or a custom name or id from notifai sounds',
+    )
     .option(
       '--level <level>',
       'Apple-only interruption level: passive | active | time_sensitive (unsupported with --platform android)',
@@ -435,7 +470,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
 
   send.addHelpText(
     'after',
-    `\nKind is required, and it selects the sound the notification arrives with: done rings the completion chime, failed the most insistent tone, blocked and question a distinct attention tone, update the standard one.\nAn explicit --sound or saved sound preference outranks that default. --level is Apple-only; Android attention is owned by kind, product channels, and device settings.\n`,
+    `\nKind is required, and it selects the sound the notification arrives with: done rings the completion chime, failed the most insistent tone, blocked and question a distinct attention tone, update Device default.\nAn explicit --sound or saved sound preference outranks that default. --sound accepts a shipped name, an Account custom sound name or id from \`notifai sounds\`, or none. --level is Apple-only; Android attention is owned by kind, product channels, and device settings.\n`,
   )
 
   program
@@ -593,7 +628,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .option('--owner <name>', 'internal ownership marker')
     .option('--harness <name>', 'internal harness output adapter')
     .action(async (event: string, opts: { harness?: string }) => {
-      const harness = HARNESSES.find((candidate) => candidate === opts.harness)
+      const harness = HOOK_INSTALLABLE_HARNESSES.find((candidate) => candidate === opts.harness)
       exit(await runners.hookRun(deps, event, () => readStdinWithTimeout(), harness))
     })
 
@@ -607,7 +642,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .description('Wire this harness to route registered questions to your devices')
     .option(
       '--harness <name>',
-      'claude-code | codex | cursor | opencode (default: every detected harness)',
+      'claude-code | codex | cursor | opencode | openclaw (default: every detected harness)',
     )
     .option('--global', 'install for every project instead of just this one')
     .action((opts: { harness?: string; global?: boolean }) => {
@@ -616,7 +651,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
   hooks
     .command('uninstall')
     .description('Remove the hooks this CLI installed')
-    .option('--harness <name>', 'claude-code | codex | cursor | opencode (default: detected)')
+    .option('--harness <name>', 'claude-code | codex | cursor | opencode | openclaw (default: detected)')
     .option('--global', 'remove the machine-wide install')
     .action((opts: { harness?: string; global?: boolean }) => {
       exit(runners.hooksUninstall(deps, opts))

package/src/send.ts

@@ -1,5 +1,4 @@
 import {
-  CLI_SOUNDS,
   COLLAPSE_KEY_MAX_BYTES,
   INTERRUPTION_LEVELS,
   MEDIA_MAX_ITEMS,
@@ -13,9 +12,6 @@ import {
   type MediaItemT,
   type NotificationDraftT,
   NOTIFICATION_KINDS,
-  DEFAULT_NOTIFICATION_KIND,
-  defaultSoundForKind,
-  type NotificationKind,
   PLATFORMS,
   type Platform,
   type QuestionT,
@@ -23,8 +19,7 @@ import {
   type SubmissionReceipt,
 } from '@raidiant/notifai-protocol'
 import type { CliConfig } from './config.js'
-
-type CliSound = (typeof CLI_SOUNDS)[number]
+import { isCliSoundRef, unknownSoundMessage } from './sound-ref.js'
 
 export interface SendFlags {
   title: string
@@ -217,18 +212,15 @@ export function buildDraft(
     }
   }
 
-  // Kind states what happened; the sound table turns that truth into the
-  // attention it deserves, so an honest sender gets the right sound without
-  // reasoning about audio. An explicit --sound and the user's saved preference
-  // both outrank it, and `none` still means silent.
-  const kindForSound: NotificationKind = flags.reply
-    ? 'question'
-    : ((flags.kind as NotificationKind | undefined) ?? DEFAULT_NOTIFICATION_KIND)
-  const sound = flags.sound ?? config.sound.value ?? defaultSoundForKind(kindForSound)
-  if (sound !== null && sound !== undefined && !CLI_SOUNDS.includes(sound as CliSound)) {
+  // Explicit --sound and the saved sound key outrank kind. The server is the
+  // one that applies kind, Project, and Account maps — stamping a kind default
+  // here would look like an explicit choice and skip those layers. `none` is
+  // still silent.
+  const sound = flags.sound !== undefined ? flags.sound : config.sound.value
+  if (sound !== null && sound !== undefined && !isCliSoundRef(sound)) {
     return {
       ok: false,
-      error: `Unknown sound "${sound}" — supported: ${CLI_SOUNDS.map((value) => `"${value}"`).join(', ')}.`,
+      error: unknownSoundMessage(sound),
     }
   }
   const level =
@@ -254,9 +246,8 @@ export function buildDraft(
     appleOptions.sound = null
     androidOptions.sound = null
   } else if (sound !== null && sound !== undefined) {
-    const semanticSound = sound as Exclude<(typeof CLI_SOUNDS)[number], 'none'>
-    appleOptions.sound = semanticSound
-    androidOptions.sound = semanticSound
+    appleOptions.sound = sound
+    androidOptions.sound = sound
   }
   if (flags.threadId !== undefined) {
     appleOptions.thread_id = flags.threadId

package/src/session-activation.ts

@@ -31,7 +31,7 @@ export function sessionActivationOutput(
   const context = hookEventName === 'SubagentStart'
     ? WORKER_ACTIVATION_CONTEXT
     : rootActivationContext(cwd, env)
-  if (harness === 'opencode') return context
+  if (harness === 'opencode' || harness === 'openclaw') return context
   if (harness === 'cursor') {
     return JSON.stringify({ additional_context: context })
   }

package/src/session-labels.test.ts

@@ -1,9 +1,20 @@
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { stateDir } from './config.js'
-import { formatSessionFirstSeen, resolveSessionLabel } from './session-labels.js'
+import {
+  formatSessionFirstSeen,
+  renameStoredSessionLabel,
+  resolveSessionLabel,
+} from './session-labels.js'
 
 function fixture(): { env: NodeJS.ProcessEnv; now: number } {
   const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-session-labels-'))
@@ -416,26 +427,64 @@ describe('semantic session labels', () => {
     })
   })
 
-  it('fails closed instead of replacing an unreadable name store', () => {
+  it('isolates an unreadable name store before creating a clean one', () => {
     const { env, now } = fixture()
     const file = path.join(stateDir(env), 'session-labels.json')
     mkdirSync(path.dirname(file), { recursive: true })
     writeFileSync(file, '{not json}\n')
 
-    const resolved = resolveSessionLabel({
+    expect(
+      resolveSessionLabel({
       env,
       now,
       sessionId: 'new-session',
       explicitLabel: 'Do not overwrite me',
-    })
-
-    expect(resolved.ok).toBe(false)
-    expect(!resolved.ok && resolved.error).toContain('session-name store is unreadable')
-    expect(readFileSync(file, 'utf8')).toBe('{not json}\n')
+      }),
+    ).toEqual({ ok: true, label: 'Do not overwrite me', source: 'explicit' })
+    expect(readFileSync(file, 'utf8')).not.toBe('{not json}\n')
+    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')).toBe('{not json}\n')
   })
 
   it('formats first seen using the machine local calendar', () => {
     const now = new Date(2026, 0, 2, 3, 4).getTime()
     expect(formatSessionFirstSeen(now)).toBe('Jan 2, 2026 03:04')
   })
+
+  it('explicitly replaces a semantic or fallback label after an authorized rename', () => {
+    const { env, now } = fixture()
+    resolveSessionLabel({
+      env,
+      now,
+      sessionId: 'rename-me',
+      harness: 'codex',
+      explicitLabel: 'Old job',
+    })
+
+    expect(
+      renameStoredSessionLabel({
+        env,
+        now: now + 1_000,
+        sessionId: 'rename-me',
+        harness: 'codex',
+        label: '  Completely   different job  ',
+      }),
+    ).toEqual({ ok: true, label: 'Completely different job', source: 'explicit' })
+    expect(
+      resolveSessionLabel({
+        env,
+        now: now + 2_000,
+        sessionId: 'rename-me',
+        harness: 'codex',
+        harnessLabel: 'Later task context',
+      }),
+    ).toEqual({
+      ok: true,
+      label: 'Completely different job',
+      source: 'explicit',
+    })
+  })
 })

package/src/session-labels.ts

@@ -1,12 +1,12 @@
 import { createHash } from 'node:crypto'
-import { existsSync, readFileSync } from 'node:fs'
+import { copyFileSync, existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { SESSION_LABEL_MAX_LENGTH } from '@raidiant/notifai-protocol'
 import { atomicWriteFileSync } from './atomic-file.js'
 import { stateDir } from './config.js'
 import { withFileLock } from './file-lock.js'
 import { generatedSessionLabel } from './generated-session-label.js'
-import { HARNESS_LABELS, type Harness } from './harnesses.js'
+import { HARNESS_LABELS, type SourceContextHarness } from './harnesses.js'
 
 const STORE_VERSION = 1
 const MONTHS = [
@@ -35,7 +35,7 @@ interface StoredSessionLabel {
   label: string
   source: SessionLabelSource
   first_seen_at: number
-  harness?: Harness
+  harness?: SourceContextHarness
 }
 
 interface SessionLabelStore {
@@ -46,13 +46,21 @@ interface SessionLabelStore {
 export interface SessionLabelInput {
   env: NodeJS.ProcessEnv
   sessionId: string
-  harness?: Harness
+  harness?: SourceContextHarness
   explicitLabel?: string
   harnessLabel?: string
   harnessLabelPending?: boolean
   now?: number
 }
 
+export interface SessionLabelRenameInput {
+  env: NodeJS.ProcessEnv
+  sessionId: string
+  label: string
+  harness?: SourceContextHarness
+  now?: number
+}
+
 export type SessionLabelResolution =
   | { ok: true; label: string; source: SessionLabelSource }
   | { ok: false; error: string }
@@ -70,6 +78,24 @@ function emptyStore(): SessionLabelStore {
   return { version: STORE_VERSION, sessions: {} }
 }
 
+function quarantineInvalidStore(file: string, raw: string): void {
+  const digest = createHash('sha256').update(raw).digest('hex')
+  const backup = path.join(path.dirname(file), `session-labels.invalid-${digest}.json`)
+  if (existsSync(backup)) {
+    if (readFileSync(backup, 'utf8') !== raw) {
+      throw new Error('the session-name store recovery backup does not match its content hash')
+    }
+    return
+  }
+  copyFileSync(file, backup)
+}
+
+function recoverInvalidStore(file: string, raw: string, store: SessionLabelStore): SessionLabelStore {
+  quarantineInvalidStore(file, raw)
+  writeStore(file, store)
+  return store
+}
+
 function storedRecord(candidate: unknown): StoredSessionLabel | null {
   if (typeof candidate !== 'object' || candidate === null) return null
   const value = candidate as Partial<StoredSessionLabel>
@@ -95,33 +121,42 @@ function storedRecord(candidate: unknown): StoredSessionLabel | null {
 
 function readStore(file: string): SessionLabelStore {
   if (!existsSync(file)) return emptyStore()
-  let parsed: unknown
+  let rawText: string
   try {
-    parsed = JSON.parse(readFileSync(file, 'utf8'))
+    rawText = readFileSync(file, 'utf8')
   } catch (err) {
     throw new Error(
       `the session-name store is unreadable: ${err instanceof Error ? err.message : String(err)}`,
     )
   }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(rawText)
+  } catch {
+    return recoverInvalidStore(file, rawText, emptyStore())
+  }
   if (typeof parsed !== 'object' || parsed === null) {
-    throw new Error('the session-name store is not a JSON object')
+    return recoverInvalidStore(file, rawText, emptyStore())
   }
   const raw = parsed as { version?: unknown; sessions?: unknown }
   if (raw.version !== STORE_VERSION) {
-    throw new Error(`unsupported session-name store version ${String(raw.version)}`)
+    return recoverInvalidStore(file, rawText, emptyStore())
   }
   if (typeof raw.sessions !== 'object' || raw.sessions === null) {
-    throw new Error('the session-name store has no sessions object')
+    return recoverInvalidStore(file, rawText, emptyStore())
   }
   const sessions: Record<string, StoredSessionLabel> = {}
+  let invalidRecordFound = false
   for (const [key, candidate] of Object.entries(raw.sessions)) {
     const record = storedRecord(candidate)
     if (!/^[a-f0-9]{64}$/.test(key) || record === null) {
-      throw new Error('the session-name store contains an invalid record')
+      invalidRecordFound = true
+      continue
     }
     sessions[key] = record
   }
-  return { version: STORE_VERSION, sessions }
+  const store = { version: STORE_VERSION, sessions } satisfies SessionLabelStore
+  return invalidRecordFound ? recoverInvalidStore(file, rawText, store) : store
 }
 
 function writeStore(file: string, store: SessionLabelStore): void {
@@ -203,6 +238,20 @@ function explicitCandidate(
   return { label: normalized, source: 'explicit' }
 }
 
+export function normalizeExplicitSessionLabel(
+  input: Pick<SessionLabelRenameInput, 'env' | 'sessionId' | 'label'>,
+): { ok: true; label: string } | { ok: false; error: string } {
+  const candidate = explicitCandidate(input.label, {
+    env: input.env,
+    sessionId: input.sessionId,
+  })
+  if (candidate === null) {
+    return { ok: false, error: '--session-label must not be empty.' }
+  }
+  if ('error' in candidate) return { ok: false, error: candidate.error }
+  return { ok: true, label: candidate.label }
+}
+
 function harnessLabelIsPending(
   value: string | undefined,
   input: SessionLabelInput,
@@ -260,7 +309,7 @@ function collisionKey(value: string): string {
 function uniqueLabel(
   base: string,
   source: SessionLabelSource,
-  harness: Harness | undefined,
+  harness: SourceContextHarness | undefined,
   now: number,
   used: ReadonlySet<string>,
 ): string {
@@ -389,3 +438,37 @@ export function resolveSessionLabel(input: SessionLabelInput): SessionLabelResol
     }
   }
 }
+
+/** Replace the local frozen label only after the Account-authoritative rename succeeds. */
+export function renameStoredSessionLabel(
+  input: SessionLabelRenameInput,
+): SessionLabelResolution {
+  const normalized = normalizeExplicitSessionLabel(input)
+  if (!normalized.ok) return normalized
+  const file = storePath(input.env)
+  const key = sessionKey(input.sessionId)
+  const now = input.now ?? Date.now()
+  try {
+    return withFileLock(`${file}.lock`, () => {
+      const store = readStore(file)
+      const existing = store.sessions[key]
+      store.sessions[key] = {
+        label: normalized.label,
+        source: 'explicit',
+        first_seen_at: existing?.first_seen_at ?? now,
+        ...(input.harness === undefined
+          ? existing?.harness === undefined
+            ? {}
+            : { harness: existing.harness }
+          : { harness: input.harness }),
+      }
+      writeStore(file, store)
+      return { ok: true, label: normalized.label, source: 'explicit' }
+    })
+  } catch (err) {
+    return {
+      ok: false,
+      error: `The Account label changed, but this machine could not save it locally: ${err instanceof Error ? err.message : String(err)}`,
+    }
+  }
+}

package/src/skill.test.ts

@@ -225,7 +225,7 @@ describe('Notifai agent skill', () => {
     expect(send).toMatch(/kind and the project travel as their own\s+fields, never in it/i)
   })
 
-  it('lets callers repeat one immutable semantic session name without supplying its id', () => {
+  it('keeps initial labels stable and teaches the narrow exact-session rename exception', () => {
     const send = section('## Send')
     expect(send).toContain('--session-label')
     expect(send).toMatch(/2-6 words/i)
@@ -239,6 +239,11 @@ describe('Notifai agent skill', () => {
     expect(send).toMatch(/generated fallback name[\s\S]*replaced by a later\s+semantic name/i)
     expect(send).toMatch(/never pass\s+`--session-id`/i)
     expect(send).toMatch(/identifier, hash, or\s+filesystem path/i)
+    expect(send).toContain('notifai session rename')
+    expect(send).toMatch(/job changed completely[\s\S]{0,100}current\s+name would now mislead/i)
+    expect(send).toMatch(/never rename for milestones, ordinary progress/i)
+    expect(send).toMatch(/accepts no Agent Session id/i)
+    expect(send).toMatch(/active harness proves the exact current Agent Session/i)
   })
 
   it('never teaches by enumerating environments the CLI can detect itself', () => {
@@ -247,7 +252,7 @@ describe('Notifai agent skill', () => {
     // Harness names may appear only in setup/routing material, where the
     // harness IS the subject.
     for (const heading of ['## Decide whether to notify', '## Send', '## Ask a question', '## When the answer arrives']) {
-      expect(section(heading), heading).not.toMatch(/OpenCode|Orca|Cursor|Codex/)
+      expect(section(heading), heading).not.toMatch(/OpenCode|OpenClaw|Orca|Cursor|Codex|Hermes/)
     }
   })
 
@@ -383,6 +388,7 @@ describe('Notifai agent skill', () => {
       'notifai guidance',
       'notifai logs',
       'notifai status',
+      'notifai sounds',
     ]) {
       expect(skill, `${command} is unreachable from the skill`).toContain(command)
     }
@@ -391,9 +397,14 @@ describe('Notifai agent skill', () => {
   it('moves per-harness mechanics into progressive disclosure', () => {
     expect(skill).toContain('[Harness setup and recovery](references/harness-setup.md)')
     expect(skill).toMatch(/read it when you are\s+installing hooks or diagnosing routing/i)
-    for (const harness of ['Claude Code', 'Codex', 'Cursor', 'OpenCode']) {
+    for (const harness of ['Claude Code', 'Codex', 'Cursor', 'OpenCode', 'OpenClaw', 'Hermes']) {
       expect(harnessReference).toContain(`**${harness}:**`)
     }
+    expect(harnessReference).toMatch(/exact `HERMES_SESSION_ID`/i)
+    expect(harnessReference).toMatch(/Do not run `notifai hooks install --harness hermes`/i)
+    expect(harnessReference).toMatch(/blocking `notifai send --reply`/i)
+    expect(harnessReference).toMatch(/npx skills/i)
+    expect(harnessReference).toMatch(/no Hermes plugin may vendor/i)
     // The agent runs what a process can run; the human only does the human part.
     expect(harnessReference).toMatch(/let init install and assess\s+the hooks/i)
     expect(harnessReference).toContain('--setup-scope <project|global>')

package/src/sound-ref.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { SOUND_NAME_MAX_LENGTH, SOUND_REF_MAX_LENGTH } from '@raidiant/notifai-protocol'
+import { isCliSoundRef, unknownSoundMessage } from './sound-ref.js'
+
+describe('isCliSoundRef', () => {
+  it('accepts shipped names and the silent spelling', () => {
+    for (const ref of ['default', 'done', 'attention', 'alert', 'none']) {
+      expect(isCliSoundRef(ref), ref).toBe(true)
+    }
+  })
+
+  it('accepts an Account custom sound id and a display name', () => {
+    expect(isCliSoundRef('snd_01HQTEST')).toBe(true)
+    expect(isCliSoundRef('Kitchen timer')).toBe(true)
+    expect(isCliSoundRef('airhorn')).toBe(true)
+  })
+
+  it('rejects empty, blank, and over-long values', () => {
+    expect(isCliSoundRef('')).toBe(false)
+    expect(isCliSoundRef('   ')).toBe(false)
+    expect(isCliSoundRef('n'.repeat(SOUND_NAME_MAX_LENGTH + 1))).toBe(false)
+    expect(isCliSoundRef(`snd_${'a'.repeat(SOUND_REF_MAX_LENGTH)}`)).toBe(false)
+  })
+})
+
+describe('unknownSoundMessage', () => {
+  it('points at the list command rather than only the shipped set', () => {
+    expect(unknownSoundMessage('nope')).toContain('notifai sounds')
+    expect(unknownSoundMessage('nope')).toContain('custom sound')
+  })
+})

package/src/sound-ref.ts

@@ -0,0 +1,34 @@
+import {
+  CLI_SOUNDS,
+  SOUND_NAME_MAX_LENGTH,
+  SOUND_REF_MAX_LENGTH,
+  isCustomSoundId,
+} from '@raidiant/notifai-protocol'
+
+/**
+ * What `--sound` and the saved `sound` key accept: shipped semantic names,
+ * the CLI silent spelling, an Account custom sound id, or a custom display name.
+ */
+export function isCliSoundRef(value: string): boolean {
+  if ((CLI_SOUNDS as readonly string[]).includes(value)) return true
+  if (value.length < 1 || value.length > SOUND_REF_MAX_LENGTH) return false
+  if (isCustomSoundId(value)) return true
+  const trimmed = value.trim()
+  return trimmed.length >= 1 && trimmed.length <= SOUND_NAME_MAX_LENGTH
+}
+
+export function unknownSoundMessage(sound: string): string {
+  return (
+    `Unknown sound "${sound}" — use a shipped name (${CLI_SOUNDS.join(', ')}), ` +
+    'a custom sound id, or a custom sound name. Run `notifai sounds` to list what this Account can play.'
+  )
+}
+
+/** Shipped names plus the CLI silent spelling, with User-facing labels. */
+export const SHIPPED_SOUND_LISTING = [
+  { ref: 'default', name: 'Device default' },
+  { ref: 'done', name: 'completion chime' },
+  { ref: 'attention', name: 'attention tone' },
+  { ref: 'alert', name: 'most insistent tone' },
+  { ref: 'none', name: 'silent' },
+] as const

package/src/ui/config-view.test.ts

@@ -85,5 +85,6 @@ describe('renderConfigExplain', () => {
       expect(text, choice).toContain(choice)
     }
     expect(text).toContain('the completion chime')
+    expect(text).toContain('Device default')
   })
 })

package/src/ui/help.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest'
+import { rootHelpFooter } from './help.js'
+
+function stripAnsi(text: string): string {
+  return text.replace(/\u001B\[[0-9;]*m/g, '')
+}
+
+describe('rootHelpFooter', () => {
+  it('leads first-run with init, not the interactive app', () => {
+    const footer = stripAnsi(rootHelpFooter())
+    const start = footer.slice(footer.indexOf('Start here'))
+    const firstCommand = start.match(/notifai(?: init)?/)?.[0]
+    expect(firstCommand).toBe('notifai init')
+    expect(start.indexOf('notifai init')).toBeLessThan(start.search(/notifai\s{2,}/))
+  })
+})