@raidiant/notifai 9.2.2 → 10.0.0

package/dist/sound-ref.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 declare function isCliSoundRef(value: string): boolean;
+export declare function unknownSoundMessage(sound: string): string;
+/** Shipped names plus the CLI silent spelling, with User-facing labels. */
+export declare const SHIPPED_SOUND_LISTING: readonly [{
+    readonly ref: "default";
+    readonly name: "Device default";
+}, {
+    readonly ref: "done";
+    readonly name: "completion chime";
+}, {
+    readonly ref: "attention";
+    readonly name: "attention tone";
+}, {
+    readonly ref: "alert";
+    readonly name: "most insistent tone";
+}, {
+    readonly ref: "none";
+    readonly name: "silent";
+}];

package/dist/sound-ref.js

@@ -0,0 +1,28 @@
+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) {
+    if (CLI_SOUNDS.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) {
+    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' },
+];
+//# sourceMappingURL=sound-ref.js.map

package/dist/sound-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sound-ref.js","sourceRoot":"","sources":["../src/sound-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,GAChB,MAAM,4BAA4B,CAAA;AAEnC;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAK,UAAgC,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAClE,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,oBAAoB;QAAE,OAAO,KAAK,CAAA;IACzE,IAAI,eAAe,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACvC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC5B,OAAO,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,OAAO,CAAC,MAAM,IAAI,qBAAqB,CAAA;AACvE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,OAAO,CACL,kBAAkB,KAAK,2BAA2B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;QAC5E,qGAAqG,CACtG,CAAA;AACH,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,gBAAgB,EAAE;IAC1C,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,EAAE;IACzC,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,gBAAgB,EAAE;IAC5C,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,qBAAqB,EAAE;IAC7C,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE;CACvB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raidiant/notifai",
-  "version": "9.2.2",
+  "version": "10.0.0",
   "type": "module",
   "description": "Send native device notifications from agents and local programs",
   "bin": {
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@raidiant/notifai-protocol": "5.0.1",
+    "@raidiant/notifai-protocol": "6.0.0",
     "commander": "^14.0.0",
     "picocolors": "^1.1.1",
     "smol-toml": "^1.4.0"
@@ -31,7 +31,7 @@
     "vitest": "^3.2.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "license": "Apache-2.0",
   "author": "Rafael Vidaurre",

package/src/claude-wake.test.ts

@@ -76,6 +76,7 @@ const event = {
   remaining: 0,
   request_ids: ['req_test'],
   journal_recorded_at: STARTED_AT,
+  commitDelivery: () => true,
 }
 
 describe('Claude session observation', () => {

package/src/claude-wake.ts

@@ -357,6 +357,7 @@ export function claudeWakeRoute(options: {
             acknowledgement: 'held',
           }
         }
+        if (!event.commitDelivery()) return cancelledDelivery()
         await adapters.resume(options.sessionId, sourceDescriptor.cwd, event.context)
         return {
           notes: ['cold-resumed the stopped Claude session with its accepted answer'],
@@ -376,6 +377,7 @@ export function claudeWakeRoute(options: {
           acknowledgement: 'held',
         }
       }
+      if (!event.commitDelivery()) return cancelledDelivery()
       await adapters.sendSocket(
         observation.descriptor.messagingSocketPath,
         socketLine(event.context),
@@ -400,6 +402,14 @@ export function claudeWakeRoute(options: {
   }
 }
 
+function cancelledDelivery(): DeliveryOutcome {
+  return {
+    notes: ['the Agent Session ended before answer delivery; stopping this observer'],
+    log: { route: 'hold-for-next-turn', stage: 'queued', reason: 'session-ended' },
+    acknowledgement: 'held',
+  }
+}
+
 function runClaude(args: string[], options: { cwd?: string; env?: NodeJS.ProcessEnv } = {}): Promise<string> {
   return new Promise((resolve, reject) => {
     const child = spawn('claude', args, {

package/src/client.test.ts

@@ -110,6 +110,18 @@ describe('a server that never answers', () => {
     ])
   })
 
+  it('lists Account custom sounds from the catalog endpoint', async () => {
+    let seen: string | undefined
+    const baseUrl = await serving((request, response) => {
+      seen = `${request.method} ${request.url}`
+      response.setHeader('content-type', 'application/json')
+      response.end(JSON.stringify({ sounds: [] }))
+    })
+    const result = await createClient(baseUrl, 'Bearer test').listSounds()
+    expect(seen).toBe('GET /api/v1/sounds')
+    expect(result).toEqual({ sounds: [] })
+  })
+
   it('refuses redirects on bearer-authenticated calls', async () => {
     let followed = false
     const baseUrl = await serving((request, response) => {

package/src/client.ts

@@ -9,6 +9,7 @@ import type {
   EvidenceSnapshot,
   GetAgentAcknowledgementResponse,
   ListDevicesResponse,
+  ListSoundsResponse,
   ClientCapability,
   CompatibilityResponse,
   RecoveryAction,
@@ -17,6 +18,8 @@ import type {
   PollPairingResponse,
   PutAgentAcknowledgementRequestT,
   PutAgentAcknowledgementResponse,
+  PutAgentSessionLabelRequestT,
+  AgentSessionView,
   SubmissionReceipt,
   SubmitNotificationRequestT,
 } from '@raidiant/notifai-protocol'
@@ -76,6 +79,7 @@ export interface ApiClient {
   pollPairing(pairingId: string, pollVerifier: string): Promise<PollPairingResponse>
   accessStatus(): Promise<AccountAccessResponse>
   listDevices(): Promise<ListDevicesResponse>
+  listSounds(): Promise<ListSoundsResponse>
   capabilities(
     platform?: Platform,
     appVersion?: string,
@@ -94,6 +98,7 @@ export interface ApiClient {
     requestId: string,
     body: PutAgentAcknowledgementRequestT,
   ): Promise<PutAgentAcknowledgementResponse>
+  putAgentSessionLabel(body: PutAgentSessionLabelRequestT): Promise<AgentSessionView>
   agentAcknowledgement(
     requestId: string,
     options: { waitSeconds: number },
@@ -250,6 +255,7 @@ export function createClient(
       }),
     accessStatus: () => call('GET', '/api/v1/account/access'),
     listDevices: () => call('GET', '/api/v1/devices'),
+    listSounds: () => call('GET', '/api/v1/sounds'),
     capabilities: (platform = 'ios', appVersion, appBuild) => {
       const query = new URLSearchParams()
       if (appVersion !== undefined) query.set('app_version', appVersion)
@@ -279,6 +285,8 @@ export function createClient(
         `/api/v1/notifications/${encodeURIComponent(requestId)}/agent-acknowledgement`,
         body,
       ),
+    putAgentSessionLabel: (body) =>
+      call<AgentSessionView>('PUT', '/api/v1/agent-sessions/label', body),
     agentAcknowledgement: (requestId, { waitSeconds }) =>
       call<GetAgentAcknowledgementResponse>(
         'GET',

package/src/codex-wake.test.ts

@@ -21,6 +21,7 @@ const event = {
   remaining: 0,
   request_ids: ['req_test'],
   journal_recorded_at: 1_800_000_000_000,
+  commitDelivery: () => true,
 }
 
 const temporaries: string[] = []

package/src/codex-wake.ts

@@ -156,6 +156,7 @@ export function codexWakeRoute(options: {
       const raced = holdForNextTurn(confirmed)
       if (raced !== null) return raced
 
+      if (!event.commitDelivery()) return cancelledDelivery()
       await adapters.resume(options.threadId, options.cwd, event.context)
       return {
         notes: ['cold-resumed the stopped Codex thread with its accepted answer'],
@@ -168,6 +169,14 @@ export function codexWakeRoute(options: {
   }
 }
 
+function cancelledDelivery(): DeliveryOutcome {
+  return {
+    notes: ['the Agent Session ended before answer delivery; stopping this observer'],
+    log: { route: 'hold-for-next-turn', stage: 'queued', reason: 'session-ended' },
+    acknowledgement: 'held',
+  }
+}
+
 /** The journal, with the exact reason the thread could not be resumed. */
 function holdForNextTurn(observation: CodexWakeObservation): DeliveryOutcome | null {
   if (observation.state === 'stopped') return null

package/src/commands-agent-sessions.ts

@@ -0,0 +1,72 @@
+import { resolveActiveHarness } from './commands-harness-context.js'
+import {
+  authedClient,
+  EXIT,
+  loadLoggedConfig,
+  reportError,
+  type CommandDeps,
+} from './commands-core.js'
+import {
+  normalizeExplicitSessionLabel,
+  renameStoredSessionLabel,
+} from './session-labels.js'
+
+export interface AgentSessionRenameFlags {
+  json?: boolean
+}
+
+/** Rename only the exact harness-owned Agent Session running this command. */
+export async function agentSessionRenameCommand(
+  deps: CommandDeps,
+  label: string,
+  flags: AgentSessionRenameFlags = {},
+): Promise<number> {
+  const now = deps.now?.() ?? Date.now()
+  const resolution = resolveActiveHarness(deps.env, deps.cwd, now)
+  const active = resolution.active
+  if (resolution.contested.length > 0 || active?.sessionId === undefined) {
+    deps.io.err(
+      'No exact active Agent Session can be proven here. Run this command inside the Agent Session you intend to rename.',
+    )
+    return EXIT.usage
+  }
+
+  const normalized = normalizeExplicitSessionLabel({
+    env: deps.env,
+    sessionId: active.sessionId,
+    label,
+  })
+  if (!normalized.ok) {
+    deps.io.err(normalized.error)
+    return EXIT.usage
+  }
+
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  const auth = authedClient(deps, config)
+  if (!auth) return EXIT.auth
+  try {
+    const renamed = await auth.client.putAgentSessionLabel({
+      session_id: active.sessionId,
+      label: normalized.label,
+    })
+    const local = renameStoredSessionLabel({
+      env: deps.env,
+      sessionId: active.sessionId,
+      label: renamed.label,
+      harness: active.harness,
+      now,
+    })
+    if (!local.ok) {
+      deps.io.err(local.error)
+      return EXIT.failed
+    }
+    deps.io.out(
+      flags.json
+        ? JSON.stringify(renamed)
+        : `Agent Session renamed to "${renamed.label}" across your Notifai account.`,
+    )
+    return EXIT.ok
+  } catch (err) {
+    return reportError(deps, err, { operation: 'agent_session_rename' })
+  }
+}

package/src/commands-config.ts

@@ -26,6 +26,7 @@ import {
 import { normalizeOrigin } from './url-policy.js'
 import { renderConfigExplain, renderConfigList, renderConfigPlain } from './ui/config-view.js'
 import { EXIT, loadLoggedConfig, type CommandDeps } from './commands-core.js'
+import { isCliSoundRef } from './sound-ref.js'
 
 // ---------------------------------------------------------------------------
 // config show / set / unset
@@ -186,10 +187,15 @@ export async function configSetCommand(
     }
     value = rawValue === 'true'
   }
-  // Enum keys were accepted unchecked, so `config set sound whatever` wrote a
-  // value the sender would later reject — a typo that only surfaces at the
-  // moment a notification fails to carry the sound you asked for.
-  if (info.kind === 'enum' && info.choices !== undefined && !info.choices.includes(rawValue)) {
+  // Sound is listed as an enum of shipped names so the interactive picker has
+  // choices, but it also accepts an Account custom name or id. Other enum keys
+  // stay closed: an unrecognised value used to be written and only fail at send.
+  if (configKey === 'sound') {
+    if (!isCliSoundRef(rawValue)) {
+      deps.io.err(`${key} takes ${acceptedValues(configKey)} — not "${rawValue}".`)
+      return EXIT.usage
+    }
+  } else if (info.kind === 'enum' && info.choices !== undefined && !info.choices.includes(rawValue)) {
     deps.io.err(`${key} takes one of: ${info.choices.join(', ')} — not "${rawValue}".`)
     return EXIT.usage
   }

package/src/commands-core.ts

@@ -82,7 +82,7 @@ export interface CommandDeps {
   codexSourcePid?: number
   /** Test seam and production adapter for the external native skills installer. */
   nativeSkills?: NativeSkills
-  /** Test seam for Orca's exact-worktree semantic title lookup. */
+  /** Test seam for Orca's exact-worktree task/session title lookup. */
   orcaSessionTitle?: OrcaSessionTitleLookup
   /** Test seam for registry reads; production uses fetch. */
   fetchImpl?: typeof fetch

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,
@@ -13,8 +18,8 @@ import {
   readSessionState,
 } from './hooks.js'
 import {
-  BLOCKING_STOP_TIMEOUT_SECONDS,
-  CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS,
+  NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS,
+  QUESTION_STOP_TIMEOUT_SECONDS,
   codexCoexistenceNotes,
   codexHomeNote,
   codexLayerDir,
@@ -52,7 +57,6 @@ import {
 } from './commands-core.js'
 import { deviceInstallRemedy, readyCompanionDevices, supportPageUrl } from './commands-devices.js'
 import {
-  activeHarnessSession,
   claudeSessionPid,
   resolveActiveHarness,
   type ActiveHarnessSession,
@@ -80,6 +84,7 @@ import {
   setupProofApplies,
 } from './commands-setup-proof.js'
 import { skillReadiness } from './commands-skill.js'
+import { projectBinding, projectEnabled } from './project-enablement.js'
 
 // ---------------------------------------------------------------------------
 // doctor
@@ -229,6 +234,37 @@ function projectReadiness(deps: CommandDeps, config: CliConfig): ReadinessState
   }
 }
 
+function projectEnablementReadiness(deps: CommandDeps, config: CliConfig): ReadinessState {
+  const binding = projectBinding(deps.cwd, deps.env, config.project.value)
+  if (binding === null) {
+    return {
+      id: 'project-enablement',
+      title: 'Project enablement',
+      status: 'optional-gap',
+      detail: 'no Project is available here; lifecycle hooks stay silent',
+    }
+  }
+  if (projectEnabled(binding)) {
+    return {
+      id: 'project-enablement',
+      title: 'Project enablement',
+      status: 'ready',
+      detail: `enabled by the User for Project "${binding.project}"`,
+    }
+  }
+  return {
+    id: 'project-enablement',
+    title: 'Project enablement',
+    status: 'optional-gap',
+    detail: `disabled for Project "${binding.project}"; installed lifecycle hooks will emit no model guidance`,
+    remedy: {
+      by: 'cli',
+      summary: 'enable Notifai lifecycle behavior for this Project',
+      command: 'notifai project enable',
+    },
+  }
+}
+
 function remoteStatesFrom(previous: Readiness): {
   credential: ReadinessState
   server: ReadinessState
@@ -303,6 +339,7 @@ export async function assessReadiness(
       return {
         states: [
           cliBinReadiness(deps.env, deps.hookPlatform ?? process.platform),
+          projectEnablementReadiness(deps, config),
           projectReadiness(deps, config),
           reused.credential,
           reused.server,
@@ -322,6 +359,7 @@ export async function assessReadiness(
   let accountDevices: RoutableDevice[] | null = null
 
   states.push(cliBinReadiness(deps.env, deps.hookPlatform ?? process.platform))
+  states.push(projectEnablementReadiness(deps, config))
   states.push(projectReadiness(deps, config))
 
   states.push(
@@ -727,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',
@@ -748,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',
@@ -838,7 +902,11 @@ interface HookCheck {
   /** Real but not in the way: worth a line, never a blocker. */
   informational?: boolean
   /** A remedy truer than the generic `notifai hooks install`. */
-  remedy?: { summary: string; command: string }
+  remedy?: {
+    summary: string
+    command: string
+    user_action?: { code: string; harness: string; action: string; message: string }
+  }
 }
 
 function hookChecks(deps: CommandDeps): HookCheck[] {
@@ -887,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,
@@ -995,6 +1077,12 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
           remedy: {
             summary: 'open `/hooks` in Codex and approve the changed Notifai handlers',
             command: '/hooks',
+            user_action: {
+              code: 'codex_hook_approval_required',
+              harness: 'codex',
+              action: 'approve_or_enable_notifai_hooks',
+              message: 'Open `/hooks` in Codex, approve or enable the Notifai handlers, then tell me when it is done. I will finish setup and verify a fresh session.',
+            },
           },
         }),
   })
@@ -1010,7 +1098,7 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
     ok: shapeProblems.length === 0,
     detail:
       shapeProblems.length === 0
-        ? `every installed Stop handler declares the shape its harness needs: Claude Code async with an explicit ${CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS}s waiter budget, blocking hosts ${BLOCKING_STOP_TIMEOUT_SECONDS}s, Codex host-owned`
+        ? `every installed Stop handler declares the shape its harness needs: Claude Code async and Codex blocking with an explicit ${QUESTION_STOP_TIMEOUT_SECONDS}s full-window budget; non-routing blocking hosts ${NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS}s`
         : shapeProblems.join('; '),
   })
 

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.
  *