@raidiant/notifai 9.3.0 → 10.0.0

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|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', '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')
   })
 })