@raidiant/notifai 9.3.0 → 10.0.0

package/src/commands-doctor.ts

@@ -5,7 +5,12 @@ import { inspectClaudeInbox, systemClaudeWakeAdapters } from './claude-wake.js'
 import { ApiCallError, type ApiClient } from './client.js'
 import { inspectCodexResume } from './codex-wake.js'
 import { type CliConfig } from './config.js'
-import { HARNESS_CAPABILITIES, HARNESS_LABELS } from './harnesses.js'
+import {
+  HARNESS_CAPABILITIES,
+  HARNESS_LABELS,
+  HERMES_QUESTION_ROUTING_UNAVAILABLE,
+  isHookInstallableHarness,
+} from './harnesses.js'
 import { inspectHookAdapter } from './hook-adapter.js'
 import {
   readLiveProjectSessionPointers,
@@ -52,7 +57,6 @@ import {
 } from './commands-core.js'
 import { deviceInstallRemedy, readyCompanionDevices, supportPageUrl } from './commands-devices.js'
 import {
-  activeHarnessSession,
   claudeSessionPid,
   resolveActiveHarness,
   type ActiveHarnessSession,
@@ -761,7 +765,11 @@ export function remedyLine(state: ReadinessState): string {
  */
 function hookStates(deps: CommandDeps): ReadinessState[] {
   const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome, deps.hookPlatform)
-  const active = activeHarnessSession(deps.env, deps.cwd, (deps.now ?? Date.now)())
+  const { active, contested } = resolveActiveHarness(
+    deps.env,
+    deps.cwd,
+    (deps.now ?? Date.now)(),
+  )
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
   const settings: ReadinessState = {
     id: 'question-routing-settings',
@@ -782,6 +790,28 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
         }),
   }
   if (installations.length === 0) {
+    if (contested.length > 1) {
+      return [
+        {
+          id: 'hooks',
+          title: 'Question routing',
+          status: 'optional-gap',
+          detail: `Several harness sessions could own this shell (${contested.map((candidate) => candidate.label).join(', ')}); routing readiness is intentionally not attributed to either one`,
+        },
+        settings,
+      ]
+    }
+    if (active !== null && !isHookInstallableHarness(active.harness)) {
+      return [
+        {
+          id: 'hooks',
+          title: 'Question routing',
+          status: 'optional-gap',
+          detail: `${active.label}: ${HERMES_QUESTION_ROUTING_UNAVAILABLE.deliveryContract}`,
+        },
+        settings,
+      ]
+    }
     return [
       {
         id: 'hooks',
@@ -925,7 +955,21 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
     active === null
       ? []
       : installations.filter((installation) => installation.harness === active.harness)
-  if (active !== null) {
+  if (contested.length > 1) {
+    checks.push({
+      name: 'hooks (active harness)',
+      ok: false,
+      informational: true,
+      detail: `Several harness sessions could own this shell (${contested.map((candidate) => candidate.label).join(', ')}); routing readiness is intentionally not attributed to either one`,
+    })
+  } else if (active !== null && !isHookInstallableHarness(active.harness)) {
+    checks.push({
+      name: 'hooks (active harness)',
+      ok: true,
+      informational: true,
+      detail: `${active.label}: ${HERMES_QUESTION_ROUTING_UNAVAILABLE.deliveryContract}`,
+    })
+  } else if (active !== null) {
     checks.push({
       name: 'hooks (active harness)',
       ok: activeInstallations.length > 0,

package/src/commands-harness-context.ts

@@ -1,5 +1,10 @@
+import {
+  hermesClassicCliLocalInstance,
+  isHookInstallableHarness,
+  type HermesClassicCliLocalInstance,
+  type SourceContextHarness,
+} from './harnesses.js'
 import { readLiveProjectSessionPointers, readSessionState } from './hooks.js'
-import { type Harness } from './install-hooks.js'
 
 /**
  * Exact evidence that this shell command is running inside one supported
@@ -7,11 +12,17 @@ import { type Harness } from './install-hooks.js'
  * describe where a tool stores files, not which tool owns the current shell.
  * OpenCode's generated plugin supplies the Notifai-owned marker because its
  * plugin API exposes Agent Session identity but the ordinary environment does not.
+ *
+ * Hermes contributes `HERMES_SESSION_ID` only — the durable Agent Session id
+ * bridged into tool subprocesses. `HERMES_SESSION_KEY` is a gateway routing
+ * key and must never be treated as Agent Session identity.
  */
 export interface ActiveHarnessSession {
-  harness: Harness
+  harness: SourceContextHarness
   label: string
   sessionId?: string
+  /** Exact surface/backend cell proven for this marker envelope. */
+  integrationInstance?: HermesClassicCliLocalInstance
   /** Trusted human title published by this harness's managed adapter. */
   sessionLabel?: string
   /** The harness has only a temporary placeholder title so far. */
@@ -53,6 +64,16 @@ function harnessEnvCandidates(env: NodeJS.ProcessEnv): ActiveHarnessSession[] {
     candidates.push({ harness: 'codex', label: 'Codex', sessionId: codexSession })
   }
   if ((env['CURSOR_AGENT'] ?? '') !== '') candidates.push({ harness: 'cursor', label: 'Cursor' })
+  const hermesSession = env['HERMES_SESSION_ID']
+  if (hermesSession !== undefined && hermesSession !== '') {
+    const integrationInstance = hermesClassicCliLocalInstance(env)
+    candidates.push({
+      harness: 'hermes',
+      label: 'Hermes',
+      sessionId: hermesSession,
+      ...(integrationInstance === null ? {} : { integrationInstance }),
+    })
+  }
   return candidates
 }
 
@@ -97,6 +118,12 @@ export function resolveActiveHarness(
   if (first === undefined) return { active: null, contested: [] }
   if (candidates.length === 1) return { active: first, contested: [] }
 
+  // A send-only harness has no hook evidence, so live pointer/state of a
+  // hook-installable parent cannot prove which nested process owns this
+  // shell. Mixing Hermes with another marker therefore stays contested.
+  const mixedWithSendOnly = candidates.some((candidate) => !isHookInstallableHarness(candidate.harness))
+  if (mixedWithSendOnly) return { active: first, contested: candidates }
+
   // Exact lifecycle state is machine-global and survives a command moving to
   // another linked checkout. Prefer it before the checkout-local
   // pointer. A unique newest hook event proves which nested harness owns this
@@ -133,6 +160,25 @@ export function activeHarnessSession(
   return resolveActiveHarness(env, cwd, now).active
 }
 
+/**
+ * Source Context attribution. Hook-installable nesting still uses declared
+ * order when nothing has fired — that existing send behavior is preserved.
+ * A contested mix that includes a send-only harness (Hermes) fails closed:
+ * the wrong Agent Session would otherwise be named as the owner.
+ */
+export function sourceContextHarnessSession(
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+  now: number,
+): ActiveHarnessSession | null {
+  const { active, contested } = resolveActiveHarness(env, cwd, now)
+  if (contested.some((candidate) => !isHookInstallableHarness(candidate.harness))) {
+    return null
+  }
+  if (active?.harness === 'hermes' && active.integrationInstance === undefined) return null
+  return active
+}
+
 /**
  * The pid of the Claude Code session this hook belongs to.
  *

package/src/commands-hooks.ts

@@ -21,7 +21,14 @@ import { ApiCallError } from './client.js'
 import { codexWakeRoute } from './codex-wake.js'
 import { loadConfig, type CliConfig } from './config.js'
 import { withTargetFileLock } from './file-lock.js'
-import { HARNESS_CAPABILITIES, HARNESS_LABELS } from './harnesses.js'
+import {
+  HARNESS_LABELS,
+  HERMES_QUESTION_ROUTING_UNAVAILABLE,
+  HOOK_INSTALLABLE_HARNESSES,
+  isHookInstallableHarness,
+  questionRoutingCapability,
+  type HookInstallableHarness,
+} from './harnesses.js'
 import {
   inspectHookAdapter,
   installHookAdapter,
@@ -51,7 +58,6 @@ import {
 } from './hooks.js'
 import {
   NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS,
-  HARNESSES,
   applyPlan,
   buildCursorHookConfig,
   buildHookConfig,
@@ -75,7 +81,6 @@ import {
   removeHooks,
   settingsFile,
   withCodexLayerTransaction,
-  type Harness,
   type Installation,
 } from './install-hooks.js'
 import { QUESTION_WAITER_CEILING_SECONDS } from './question-timing.js'
@@ -138,7 +143,7 @@ export const HOOK_EVENTS = [
 export type HookEvent = (typeof HOOK_EVENTS)[number]
 
 /** Lifecycle handlers one installed harness must carry in this CLI build. */
-export function requiredHookEvents(harness: Harness): readonly HookEvent[] {
+export function requiredHookEvents(harness: HookInstallableHarness): readonly HookEvent[] {
   if (harness === 'opencode') return []
   return harness === 'cursor'
     ? ['session-start', 'activation-stop', 'user-prompt-submit', 'stop', 'session-end']
@@ -572,7 +577,7 @@ export async function hookRunCommand(
  */
 function stopWakeRoute(
   deps: CommandDeps,
-  harness: Harness | undefined,
+  harness: HookInstallableHarness | undefined,
   sessionId: string | undefined,
   cwd: string,
 ): EscalationDeliveryRoute | undefined {
@@ -1102,6 +1107,17 @@ export function askCommand(
         'run the ask from a shell with one exact active harness session',
       )
     }
+    if (!isHookInstallableHarness(active.harness)) {
+      const capability = HERMES_QUESTION_ROUTING_UNAVAILABLE
+      return askFailure(
+        deps,
+        flags,
+        'question_routing_unavailable',
+        'hook_contract',
+        `${active.label}: ${capability.deliveryContract}`,
+        'use a blocking `notifai send --reply` question',
+      )
+    }
     const exactState = active.sessionId === undefined
       ? null
       : readSessionState(active.sessionId, deps.env)
@@ -1253,7 +1269,9 @@ export function activeQuestionRouteProblems(
       `the active ${active.label} shell does not expose an exact session id; a project-level last-writer pointer can cross-wire two sessions. Use a blocking \`notifai send --reply\` question`,
     )
   }
-  const capability = HARNESS_CAPABILITIES[active.harness]
+  const capability = isHookInstallableHarness(active.harness)
+    ? questionRoutingCapability(active.harness)
+    : HERMES_QUESTION_ROUTING_UNAVAILABLE
   if (capability.stopContinuation === 'unsupported') {
     problems.push(`${active.label}: ${capability.deliveryContract}`)
   }
@@ -1683,7 +1701,7 @@ function resolveHookAdapterTarget(deps: CommandDeps, flags: HooksInstallFlags):
   return { execPath, scriptPath }
 }
 
-function printHooksInstallClose(deps: CommandDeps, harness: Harness, file: string): void {
+function printHooksInstallClose(deps: CommandDeps, harness: HookInstallableHarness, file: string): void {
   const label = HARNESS_LABELS[harness]
   const activation =
     harness === 'codex'
@@ -1705,7 +1723,7 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
   if (flags.harness === undefined) {
     const detected = detectedHarnesses(deps.cwd, deps.env)
     if (detected.length === 0) {
-      deps.io.err(`Could not tell which harness you mean — pass --harness <${HARNESSES.join('|')}>.`)
+      deps.io.err(`Could not tell which harness you mean — pass --harness <${HOOK_INSTALLABLE_HARNESSES.join('|')}>.`)
       return EXIT.usage
     }
     let ok = true
@@ -2049,17 +2067,17 @@ function assertOwnedRegularFile(file: string): void {
   }
 }
 
-function resolveHarness(deps: CommandDeps, requested: string | undefined): Harness | null {
+function resolveHarness(deps: CommandDeps, requested: string | undefined): HookInstallableHarness | null {
   if (requested !== undefined) {
-    if ((HARNESSES as readonly string[]).includes(requested)) return requested as Harness
+    if ((HOOK_INSTALLABLE_HARNESSES as readonly string[]).includes(requested)) return requested as HookInstallableHarness
     deps.io.err(
-      `Unknown harness "${requested}". Supported: ${HARNESSES.join(', ')}.`,
+      `Unknown harness "${requested}". Supported: ${HOOK_INSTALLABLE_HARNESSES.join(', ')}.`,
     )
     return null
   }
   const detected = detectHarness(deps.cwd, deps.env)
   if (!detected) {
-    deps.io.err(`Could not tell which harness to install for — pass --harness <${HARNESSES.join('|')}>.`)
+    deps.io.err(`Could not tell which harness to install for — pass --harness <${HOOK_INSTALLABLE_HARNESSES.join('|')}>.`)
     return null
   }
   return detected
@@ -2073,7 +2091,7 @@ function resolveHarness(deps: CommandDeps, requested: string | undefined): Harne
 export async function pickHarnessesToInstall(
   deps: CommandDeps,
   requested?: string,
-): Promise<Harness[] | null> {
+): Promise<HookInstallableHarness[] | null> {
   if (requested !== undefined) {
     const harness = resolveHarness(deps, requested)
     return harness === null ? null : [harness]
@@ -2083,7 +2101,7 @@ export async function pickHarnessesToInstall(
   if (deps.io.interactive === true && deps.io.multiselect) {
     const picked = await deps.io.multiselect(
       'Which agent harnesses should Notifai wire here?',
-      HARNESSES.map((name) => ({
+      HOOK_INSTALLABLE_HARNESSES.map((name) => ({
         value: name,
         label: HARNESS_LABELS[name],
         ...(detected.includes(name) ? { hint: 'detected on this machine' } : {}),
@@ -2091,16 +2109,16 @@ export async function pickHarnessesToInstall(
       detected,
     )
     if (picked === null) return null
-    const unknown = picked.filter((name) => !(HARNESSES as readonly string[]).includes(name))
+    const unknown = picked.filter((name) => !(HOOK_INSTALLABLE_HARNESSES as readonly string[]).includes(name))
     if (unknown.length > 0) {
-      deps.io.err(`Unknown harness "${unknown[0]}". Supported: ${HARNESSES.join(', ')}.`)
+      deps.io.err(`Unknown harness "${unknown[0]}". Supported: ${HOOK_INSTALLABLE_HARNESSES.join(', ')}.`)
       return null
     }
-    return picked as Harness[]
+    return picked as HookInstallableHarness[]
   }
   if (detected.length === 0) {
     deps.io.err(
-      `Could not tell which harness to wire. Run: notifai hooks install --harness <${HARNESSES.join('|')}>`,
+      `Could not tell which harness to wire. Run: notifai hooks install --harness <${HOOK_INSTALLABLE_HARNESSES.join('|')}>`,
     )
     return null
   }

package/src/commands-send-support.ts

@@ -5,16 +5,38 @@ import path from 'node:path'
 import { isRetryableReplyPollError, type ApiClient } from './client.js'
 import { fetchMediaUrl } from './url-policy.js'
 import { buildSourceContext, inferInvocationContext } from './invocation-context.js'
+import { readOrcaSessionTitle } from './orca-session-title.js'
 import { type DraftInvocation, type SendFlags } from './send.js'
 import { EXIT, reportError, type CommandDeps } from './commands-core.js'
 import type { ActiveHarnessSession } from './commands-harness-context.js'
 
+function managedSessionTitle(
+  deps: CommandDeps,
+  flags: Pick<SendFlags, 'sessionLabel'>,
+  active: ActiveHarnessSession | null,
+): string | undefined {
+  if (active?.sessionLabel !== undefined) return active.sessionLabel
+  if (
+    active?.sessionId === undefined ||
+    flags.sessionLabel !== undefined ||
+    deps.env['NOTIFAI_SESSION_LABEL'] !== undefined
+  ) {
+    return undefined
+  }
+  try {
+    return (deps.orcaSessionTitle ?? readOrcaSessionTitle)(deps.env)
+  } catch {
+    return undefined
+  }
+}
+
 export function resolveDraftInvocation(
   deps: CommandDeps,
   flags: Pick<SendFlags, 'sessionId' | 'sessionLabel'>,
   active: ActiveHarnessSession | null,
 ): { ok: true; invocation: DraftInvocation } | { ok: false; error: string } {
   const inferred = inferInvocationContext(deps.cwd)
+  const sessionTitle = managedSessionTitle(deps, flags, active)
   const source = buildSourceContext({
     env: deps.env,
     invocation: inferred,
@@ -26,7 +48,7 @@ export function resolveDraftInvocation(
           activeHarness: {
             harness: active.harness,
             ...(active.sessionId === undefined ? {} : { sessionId: active.sessionId }),
-            ...(active.sessionLabel === undefined ? {} : { sessionLabel: active.sessionLabel }),
+            ...(sessionTitle === undefined ? {} : { sessionLabel: sessionTitle }),
             ...(active.sessionLabelPending === true ? { sessionLabelPending: true } : {}),
           },
         }),

package/src/commands-send.ts

@@ -27,7 +27,7 @@ import {
   reportError,
   type CommandDeps,
 } from './commands-core.js'
-import { activeHarnessSession } from './commands-harness-context.js'
+import { sourceContextHarnessSession } from './commands-harness-context.js'
 import { resolveCommandSession } from './command-session.js'
 import {
   beginSendAttempt,
@@ -143,7 +143,7 @@ export async function sendCommand(
   const source = resolveDraftInvocation(
     deps,
     flags,
-    activeHarnessSession(deps.env, deps.cwd, (deps.now ?? Date.now)()),
+    sourceContextHarnessSession(deps.env, deps.cwd, (deps.now ?? Date.now)()),
   )
   if (!source.ok) {
     deps.io.err(source.error)

package/src/commands-sounds.test.ts

@@ -0,0 +1,106 @@
+import os from 'node:os'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import type { ApiClient } from './client.js'
+import { EXIT, type CommandDeps, type CommandIo } from './commands-core.js'
+import { soundsCommand } from './commands-sounds.js'
+
+class CapturedIo implements CommandIo {
+  readonly outLines: string[] = []
+  readonly errLines: string[] = []
+  out(line: string): void {
+    this.outLines.push(line)
+  }
+  err(line: string): void {
+    this.errLines.push(line)
+  }
+  async confirm(): Promise<boolean> {
+    return true
+  }
+  openUrl(): void {}
+}
+
+function makeDeps(io: CapturedIo, client: ApiClient): CommandDeps {
+  const testRoot = path.join(os.tmpdir(), 'notifai-cli-sounds-tests')
+  return {
+    io,
+    store: {
+      load: () => ({
+        machineId: 'mac_test',
+        secret: 'test-secret',
+        baseUrl: 'https://test.notifai.invalid',
+        machineName: 'test-machine',
+      }),
+      save: () => {},
+      clear: () => {},
+      describe: () => 'test credential store',
+    },
+    env: {
+      XDG_CONFIG_HOME: testRoot,
+      XDG_STATE_HOME: path.join(os.tmpdir(), 'notifai-cli-sounds-tests-state'),
+    },
+    cwd: os.tmpdir(),
+    clientFactory: () => client,
+  }
+}
+
+const kitchenTimer = {
+  sound_id: 'snd_kitchen',
+  name: 'Kitchen timer',
+  duration_ms: 2400,
+  content_hash: 'a'.repeat(64),
+  url: 'https://wav.example/kitchen.wav',
+}
+
+describe('soundsCommand', () => {
+  it('lists shipped names and Account custom sounds', async () => {
+    const io = new CapturedIo()
+    const client = {
+      listSounds: async () => ({ sounds: [kitchenTimer] }),
+    } as unknown as ApiClient
+
+    expect(await soundsCommand(makeDeps(io, client), {})).toBe(EXIT.ok)
+    expect(io.outLines[0]).toBe('default  Device default')
+    expect(io.outLines).toContain('done  completion chime')
+    expect(io.outLines).toContain('none  silent')
+    expect(io.outLines.at(-1)).toBe('snd_kitchen  Kitchen timer  2.4s')
+  })
+
+  it('prints the catalog as JSON when asked', async () => {
+    const io = new CapturedIo()
+    const client = {
+      listSounds: async () => ({ sounds: [kitchenTimer] }),
+    } as unknown as ApiClient
+
+    expect(await soundsCommand(makeDeps(io, client), { json: true })).toBe(EXIT.ok)
+    const parsed = JSON.parse(io.outLines.join('\n')) as {
+      shipped: { ref: string; name: string }[]
+      custom: typeof kitchenTimer[]
+    }
+    expect(parsed.shipped[0]).toEqual({ ref: 'default', name: 'Device default' })
+    expect(parsed.custom).toEqual([kitchenTimer])
+  })
+
+  it('refuses to list custom sounds when this machine is not signed in', async () => {
+    const io = new CapturedIo()
+    let calls = 0
+    const deps: CommandDeps = {
+      ...makeDeps(io, {
+        listSounds: async () => {
+          calls += 1
+          return { sounds: [] }
+        },
+      } as unknown as ApiClient),
+      store: {
+        load: () => null,
+        save: () => {},
+        clear: () => {},
+        describe: () => 'empty store',
+      },
+    }
+
+    expect(await soundsCommand(deps, {})).toBe(EXIT.auth)
+    expect(calls).toBe(0)
+    expect(io.errLines.join('\n')).toMatch(/not signed in/i)
+  })
+})

package/src/commands-sounds.ts

@@ -0,0 +1,49 @@
+import type { ListSoundsResponse, SoundView } from '@raidiant/notifai-protocol'
+import {
+  EXIT,
+  authedClient,
+  loadLoggedConfig,
+  reportError,
+  type CommandDeps,
+} from './commands-core.js'
+import { SHIPPED_SOUND_LISTING } from './sound-ref.js'
+
+export interface SoundsListing {
+  shipped: readonly { ref: string; name: string }[]
+  custom: SoundView[]
+}
+
+function formatSoundDuration(ms: number): string {
+  const seconds = ms / 1000
+  const text = Number.isInteger(seconds) ? String(seconds) : seconds.toFixed(1)
+  return `${text}s`
+}
+
+export async function soundsCommand(
+  deps: CommandDeps,
+  flags: { json?: boolean },
+): Promise<number> {
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  const authed = authedClient(deps, config)
+  if (!authed) return EXIT.auth
+  try {
+    const result: ListSoundsResponse = await authed.client.listSounds()
+    const listing: SoundsListing = {
+      shipped: SHIPPED_SOUND_LISTING,
+      custom: result.sounds,
+    }
+    if (flags.json) {
+      deps.io.out(JSON.stringify(listing, null, 2))
+      return EXIT.ok
+    }
+    for (const sound of listing.shipped) {
+      deps.io.out(`${sound.ref}  ${sound.name}`)
+    }
+    for (const sound of listing.custom) {
+      deps.io.out(`${sound.sound_id}  ${sound.name}  ${formatSoundDuration(sound.duration_ms)}`)
+    }
+    return EXIT.ok
+  } catch (err) {
+    return reportError(deps, err)
+  }
+}