@raidiant/notifai 9.3.0 → 10.1.0

package/src/harnesses.test.ts

@@ -1,5 +1,26 @@
+import { readFileSync } from 'node:fs'
 import { describe, expect, it } from 'vitest'
-import { HARNESS_CAPABILITIES, HARNESS_LABELS, HARNESSES } from './harnesses.js'
+import {
+  HARNESS_CAPABILITIES,
+  HARNESS_LABELS,
+  HERMES_CLASSIC_CLI_LOCAL_CAPABILITY,
+  HERMES_QUESTION_ROUTING_UNAVAILABLE,
+  HOOK_INSTALLABLE_HARNESSES,
+  SOURCE_CONTEXT_HARNESSES,
+  hermesClassicCliLocalInstance,
+  isHookInstallableHarness,
+  questionRoutingCapability,
+} from './harnesses.js'
+
+const PINNED_HERMES_TRACE = JSON.parse(
+  readFileSync(new URL('./fixtures/hermes-0.20.6-classic-cli-local.json', import.meta.url), 'utf8'),
+) as {
+  instance: { harness: 'hermes'; surface: 'classic-cli'; terminalBackend: 'local' }
+  observedToolSubprocessEnv: { HERMES_SESSION_ID: string }
+  supported: string[]
+  unsupported: string[]
+  deferred: string[]
+}
 
 /**
  * This file used to hold a verbatim copy of the table below it, which meant
@@ -8,23 +29,42 @@ import { HARNESS_CAPABILITIES, HARNESS_LABELS, HARNESSES } from './harnesses.js'
  * edit. What is worth asserting is the shape the rest of the CLI assumes.
  */
 describe('harness contract', () => {
-  it('describes every shipped harness, and only those', () => {
-    expect(Object.keys(HARNESS_CAPABILITIES).sort()).toEqual([...HARNESSES].sort())
-    expect(Object.keys(HARNESS_LABELS).sort()).toEqual([...HARNESSES].sort())
+  it('describes every shipped Source Context harness, and only those', () => {
+    expect(Object.keys(HARNESS_LABELS).sort()).toEqual([...SOURCE_CONTEXT_HARNESSES].sort())
+  })
+
+  it('keeps managed hook installation a strict subset of Source Context', () => {
+    expect(HOOK_INSTALLABLE_HARNESSES).toEqual([
+      'claude-code',
+      'codex',
+      'cursor',
+      'opencode',
+      'openclaw',
+    ])
+    expect(SOURCE_CONTEXT_HARNESSES).toContain('hermes')
+    expect(HOOK_INSTALLABLE_HARNESSES).not.toContain('hermes')
+    expect(Object.keys(HARNESS_CAPABILITIES).sort()).toEqual([...HOOK_INSTALLABLE_HARNESSES].sort())
+    for (const harness of HOOK_INSTALLABLE_HARNESSES) {
+      expect(isHookInstallableHarness(harness)).toBe(true)
+    }
+    expect(isHookInstallableHarness('hermes')).toBe(false)
   })
 
   it('gives a harness that cannot continue a turn no route to pretend with', () => {
     // `ask` fails closed on these, and the reason it can is that the two facts
     // agree. A harness claiming a delivery route while declaring it cannot
     // continue would accept an answer into a void.
-    for (const [harness, capability] of Object.entries(HARNESS_CAPABILITIES)) {
+    for (const harness of HOOK_INSTALLABLE_HARNESSES) {
+      const capability = questionRoutingCapability(harness)
       if (capability.stopContinuation !== 'unsupported') continue
       expect(capability.deliveryRoutes, harness).toEqual(['unsupported'])
     }
+    expect(HERMES_QUESTION_ROUTING_UNAVAILABLE.deliveryRoutes).toEqual(['unsupported'])
   })
 
   it('gives a harness that can continue a turn at least one real route', () => {
-    for (const [harness, capability] of Object.entries(HARNESS_CAPABILITIES)) {
+    for (const harness of HOOK_INSTALLABLE_HARNESSES) {
+      const capability = HARNESS_CAPABILITIES[harness]
       if (capability.stopContinuation === 'unsupported') continue
       expect(capability.deliveryRoutes.length, harness).toBeGreaterThan(0)
       expect(capability.deliveryRoutes, harness).not.toContain('unsupported')
@@ -35,8 +75,75 @@ describe('harness contract', () => {
   })
 
   it('explains each harness in prose an operator can act on', () => {
-    for (const [harness, capability] of Object.entries(HARNESS_CAPABILITIES)) {
-      expect(capability.deliveryContract.length, harness).toBeGreaterThan(40)
+    for (const harness of HOOK_INSTALLABLE_HARNESSES) {
+      expect(questionRoutingCapability(harness).deliveryContract.length, harness).toBeGreaterThan(40)
+    }
+    expect(HERMES_QUESTION_ROUTING_UNAVAILABLE.deliveryContract.length).toBeGreaterThan(40)
+  })
+
+  it('keeps Claude Code, Codex, Cursor, and OpenCode continuation contracts unchanged', () => {
+    expect(HARNESS_CAPABILITIES['claude-code'].stopContinuation).toBe('decision-block')
+    expect(HARNESS_CAPABILITIES['claude-code'].deliveryRoutes).toEqual([
+      'hook-continuation',
+      'inbox-socket',
+      'cold-resume',
+      'hold-for-next-turn',
+    ])
+    expect(HARNESS_CAPABILITIES.codex.stopContinuation).toBe('decision-block')
+    expect(HARNESS_CAPABILITIES.codex.deliveryRoutes).toEqual([
+      'hook-continuation',
+      'cold-resume',
+      'hold-for-next-turn',
+    ])
+    expect(HARNESS_CAPABILITIES.cursor).toEqual({
+      stopContinuation: 'unsupported',
+      deliveryRoutes: ['unsupported'],
+      deliveryContract: HARNESS_CAPABILITIES.cursor.deliveryContract,
+    })
+    expect(HARNESS_CAPABILITIES.opencode.stopContinuation).toBe('unsupported')
+    expect(HARNESS_CAPABILITIES.opencode.deliveryRoutes).toEqual(['unsupported'])
+    expect(HARNESS_CAPABILITIES.openclaw.stopContinuation).toBe('unsupported')
+    expect(HARNESS_CAPABILITIES.openclaw.deliveryRoutes).toEqual(['unsupported'])
+  })
+
+  it('treats the pinned Hermes classic CLI/local trace as send-only', () => {
+    expect(HERMES_CLASSIC_CLI_LOCAL_CAPABILITY.instance).toEqual(PINNED_HERMES_TRACE.instance)
+    expect(PINNED_HERMES_TRACE.supported).toContain('deliberate-send')
+    expect(PINNED_HERMES_TRACE.unsupported).toContain('question-routing')
+    expect(PINNED_HERMES_TRACE.deferred).toContain('gateway')
+    expect(HERMES_CLASSIC_CLI_LOCAL_CAPABILITY.sourceContext).toBe(
+      'hermes-session-id-and-invocation-cwd',
+    )
+    expect(HERMES_QUESTION_ROUTING_UNAVAILABLE.stopContinuation).toBe('unsupported')
+    expect(HERMES_QUESTION_ROUTING_UNAVAILABLE.deliveryRoutes).toEqual(['unsupported'])
+  })
+
+  it('resolves only the pinned classic CLI/local marker envelope', () => {
+    expect(
+      hermesClassicCliLocalInstance({
+        HERMES_SESSION_ID: PINNED_HERMES_TRACE.observedToolSubprocessEnv.HERMES_SESSION_ID,
+      }),
+    ).toEqual(PINNED_HERMES_TRACE.instance)
+    expect(
+      hermesClassicCliLocalInstance({
+        HERMES_SESSION_ID: PINNED_HERMES_TRACE.observedToolSubprocessEnv.HERMES_SESSION_ID,
+        HERMES_SESSION_SOURCE: 'cli',
+        TERMINAL_ENV: 'local',
+      }),
+    ).toEqual(PINNED_HERMES_TRACE.instance)
+    for (const env of [
+      { HERMES_SESSION_KEY: 'gateway-key' },
+      { HERMES_SESSION_PLATFORM: 'api_server' },
+      { HERMES_SESSION_SOURCE: 'tui' },
+      { TERMINAL_ENV: 'docker' },
+      { TERMINAL_ENV: 'ssh' },
+    ]) {
+      expect(
+        hermesClassicCliLocalInstance({
+          HERMES_SESSION_ID: PINNED_HERMES_TRACE.observedToolSubprocessEnv.HERMES_SESSION_ID,
+          ...env,
+        }),
+      ).toBeNull()
     }
   })
 })

package/src/harnesses.ts

@@ -1,13 +1,43 @@
-/** Every harness Notifai ships. This is the sole source of the harness union. */
-export const HARNESSES = ['claude-code', 'codex', 'cursor', 'opencode'] as const
+/** Every harness Notifai can name in Source Context when authoritatively known. */
+export const SOURCE_CONTEXT_HARNESSES = [
+  'claude-code',
+  'codex',
+  'cursor',
+  'opencode',
+  'openclaw',
+  'hermes',
+] as const
 
-export type Harness = (typeof HARNESSES)[number]
+export type SourceContextHarness = (typeof SOURCE_CONTEXT_HARNESSES)[number]
 
-export const HARNESS_LABELS: Record<Harness, string> = {
+/**
+ * Harnesses whose lifecycle Notifai can install and manage.
+ *
+ * Source Context is the broader vocabulary. Managed hook installation is a
+ * narrower, independently proven cell: Hermes can appear in Source Context
+ * without being hook-installable.
+ */
+export const HOOK_INSTALLABLE_HARNESSES = [
+  'claude-code',
+  'codex',
+  'cursor',
+  'opencode',
+  'openclaw',
+] as const
+
+export type HookInstallableHarness = (typeof HOOK_INSTALLABLE_HARNESSES)[number]
+
+export function isHookInstallableHarness(value: string): value is HookInstallableHarness {
+  return (HOOK_INSTALLABLE_HARNESSES as readonly string[]).includes(value)
+}
+
+export const HARNESS_LABELS: Record<SourceContextHarness, string> = {
   'claude-code': 'Claude Code',
   codex: 'Codex',
   cursor: 'Cursor',
   opencode: 'OpenCode',
+  openclaw: 'OpenClaw',
+  hermes: 'Hermes',
 }
 
 export type DeliveryRoute =
@@ -29,33 +59,106 @@ export interface HarnessCapability {
   deliveryContract: string
 }
 
+const CLAUDE_CODE_CAPABILITY: HarnessCapability = {
+  stopContinuation: 'decision-block',
+  deliveryRoutes: ['hook-continuation', 'inbox-socket', 'cold-resume', 'hold-for-next-turn'],
+  deliveryContract:
+    'the Stop hook returns at once and waits out of band through the complete answer window, then posts the answer into this same session over its own inbox socket; a session that has stopped is resumed only once a liveness probe proves it stopped',
+}
+
+const CODEX_CAPABILITY: HarnessCapability = {
+  stopContinuation: 'decision-block',
+  deliveryRoutes: ['hook-continuation', 'cold-resume', 'hold-for-next-turn'],
+  deliveryContract:
+    'live Stop continuation while the turn is held through the complete answer window; crash recovery may resume only a stopped thread behind its writer lock',
+}
+
+const CURSOR_CAPABILITY: HarnessCapability = {
+  stopContinuation: 'unsupported',
+  deliveryRoutes: ['unsupported'],
+  deliveryContract:
+    'the hook can return a live follow-up, but the invoking shell exposes no exact conversation id; asynchronous ask is unsupported',
+}
+
+const OPENCODE_CAPABILITY: HarnessCapability = {
+  stopContinuation: 'unsupported',
+  deliveryRoutes: ['unsupported'],
+  deliveryContract:
+    'no proven answer continuation after session.idle; use a blocking reply command',
+}
+
+const OPENCLAW_CAPABILITY: HarnessCapability = {
+  stopContinuation: 'unsupported',
+  deliveryRoutes: ['unsupported'],
+  deliveryContract:
+    'no proven answer continuation after agent_end; use a blocking reply command',
+}
+
+export const HERMES_QUESTION_ROUTING_UNAVAILABLE: HarnessCapability = {
+  stopContinuation: 'unsupported',
+  deliveryRoutes: ['unsupported'],
+  deliveryContract:
+    'Hermes asynchronous ask has no proven continuation owner on this integration surface. Use a blocking `notifai send --reply` question',
+}
+
 /**
- * Exhaustive runtime contract. Adding a harness without deciding every
- * continuation joint is a type error, not a silently degraded notification.
+ * The one Hermes integration instance proven by the pinned vertical probe.
+ *
+ * This is evidence-bearing capability data, not an adapter. Unsupported and
+ * deferred surfaces intentionally have no empty implementation object here.
  */
-export const HARNESS_CAPABILITIES: Record<Harness, HarnessCapability> = {
-  'claude-code': {
-    stopContinuation: 'decision-block',
-    deliveryRoutes: ['hook-continuation', 'inbox-socket', 'cold-resume', 'hold-for-next-turn'],
-    deliveryContract:
-      'the Stop hook returns at once and waits out of band through the complete answer window, then posts the answer into this same session over its own inbox socket; a session that has stopped is resumed only once a liveness probe proves it stopped',
-  },
-  codex: {
-    stopContinuation: 'decision-block',
-    deliveryRoutes: ['hook-continuation', 'cold-resume', 'hold-for-next-turn'],
-    deliveryContract:
-      'live Stop continuation while the turn is held through the complete answer window; crash recovery may resume only a stopped thread behind its writer lock',
-  },
-  cursor: {
-    stopContinuation: 'unsupported',
-    deliveryRoutes: ['unsupported'],
-    deliveryContract:
-      'the hook can return a live follow-up, but the invoking shell exposes no exact conversation id; asynchronous ask is unsupported',
-  },
-  opencode: {
-    stopContinuation: 'unsupported',
-    deliveryRoutes: ['unsupported'],
-    deliveryContract:
-      'no proven answer continuation after session.idle; use a blocking reply command',
+export const HERMES_CLASSIC_CLI_LOCAL_CAPABILITY = {
+  instance: {
+    harness: 'hermes',
+    surface: 'classic-cli',
+    terminalBackend: 'local',
   },
+  setup: 'unsupported',
+  activation: 'unsupported',
+  sourceContext: 'hermes-session-id-and-invocation-cwd',
+  continuation: 'unsupported',
+} as const
+
+export type HermesClassicCliLocalInstance =
+  (typeof HERMES_CLASSIC_CLI_LOCAL_CAPABILITY)['instance']
+
+/**
+ * Resolve only the Hermes instance whose complete marker envelope was proven.
+ *
+ * `HERMES_SESSION_ID` is also bridged by deferred gateway, TUI, API, ACP, and
+ * remote-backend paths. Their first-party routing/source/backend markers keep
+ * those cells distinct. Missing source/backend values are the pinned classic
+ * CLI defaults; a gateway key is never part of that instance.
+ */
+export function hermesClassicCliLocalInstance(
+  env: NodeJS.ProcessEnv,
+): HermesClassicCliLocalInstance | null {
+  const sessionId = (env['HERMES_SESSION_ID'] ?? '').trim()
+  const sessionKey = (env['HERMES_SESSION_KEY'] ?? '').trim()
+  const platform = (env['HERMES_SESSION_PLATFORM'] ?? '').trim().toLowerCase()
+  const source = (env['HERMES_SESSION_SOURCE'] ?? '').trim().toLowerCase()
+  const terminalBackend = (env['TERMINAL_ENV'] ?? '').trim().toLowerCase()
+  if (sessionId === '' || sessionKey !== '' || platform !== '') return null
+  if (source !== '' && source !== 'cli') return null
+  if (terminalBackend !== '' && terminalBackend !== 'local') return null
+  return HERMES_CLASSIC_CLI_LOCAL_CAPABILITY.instance
+}
+
+/**
+ * Question-routing contract for hook-installable harnesses.
+ *
+ * Hermes is deliberately absent: a send-only surface must not occupy this
+ * table with a fake managed-hook continuation route.
+ */
+export const HARNESS_CAPABILITIES: Record<HookInstallableHarness, HarnessCapability> = {
+  'claude-code': CLAUDE_CODE_CAPABILITY,
+  codex: CODEX_CAPABILITY,
+  cursor: CURSOR_CAPABILITY,
+  opencode: OPENCODE_CAPABILITY,
+  openclaw: OPENCLAW_CAPABILITY,
+}
+
+/** Question-routing capability for the active harness integration. */
+export function questionRoutingCapability(harness: HookInstallableHarness): HarnessCapability {
+  return HARNESS_CAPABILITIES[harness]
 }

package/src/hooks.test.ts

@@ -561,8 +561,9 @@ describe('pushing a registered question', () => {
       title: 'Ship it?',
       body: 'Ship it?',
     })
-    // A pushed question is a question, and a question has an attention tone.
-    expect(h.recorder.submitted[0]?.draft.platform?.ios?.sound).toBe('attention')
+    // Kind default sounds are resolved server-side; stamping one here would
+    // skip Account and Project maps.
+    expect(h.recorder.submitted[0]?.draft.platform?.ios?.sound).toBeUndefined()
   })
 
   it('routes a registered question to an answer-capable Android installation', async () => {
@@ -594,7 +595,7 @@ describe('pushing a registered question', () => {
       mode: 'selected',
       device_ids: ['dev_android'],
     })
-    expect(h.recorder.submitted[0]?.draft.platform?.android?.sound).toBe('attention')
+    expect(h.recorder.submitted[0]?.draft.platform?.android?.sound).toBeUndefined()
   })
 
   it('keeps sparse alt text paired with its original media item', async () => {

package/src/hooks.ts

@@ -48,9 +48,9 @@ import { inferInvocationContext } from './invocation-context.js'
 import type { Logger } from './logging.js'
 import {
   HARNESS_CAPABILITIES,
-  HARNESSES,
+  HOOK_INSTALLABLE_HARNESSES,
   type DeliveryRoute,
-  type Harness,
+  type HookInstallableHarness,
 } from './harnesses.js'
 
 /**
@@ -896,7 +896,7 @@ function storedProjectSessionPointer(candidate: unknown): StoredProjectSessionPo
   }
   if (typeof entry.session_id !== 'string' || entry.session_id === '') return null
   if (typeof entry.updated_at !== 'number') return null
-  if (!(HARNESSES as readonly unknown[]).includes(entry.harness)) return null
+  if (!(HOOK_INSTALLABLE_HARNESSES as readonly unknown[]).includes(entry.harness)) return null
   return {
     sessionId: entry.session_id,
     updatedAt: entry.updated_at,
@@ -1135,7 +1135,7 @@ function gate(
   ctx.log?.info('hook.gate', { verdict, reason, stage: 'queued', ...data })
 }
 
-export type HookHarness = Harness
+export type HookHarness = HookInstallableHarness
 
 /**
  * One round of the waiter's reply poll. Short enough that several questions

package/src/install-hooks.test.ts

@@ -22,14 +22,25 @@ import {
   opencodePluginSource,
   opencodePluginTarget,
 } from './opencode-plugin.js'
+import {
+  OPENCLAW_PLUGIN_MARKER,
+  isOurOpenclawPlugin,
+  mergeOpenclawNotifaiEntry,
+  openclawHasGlobalEvidence,
+  openclawPluginPath,
+  openclawPluginSource,
+  openclawPluginTarget,
+  parseOpenclawConfig,
+  removeOpenclawNotifaiEntry,
+} from './openclaw-plugin.js'
 import {
   MISSING_LIFECYCLE_GUIDANCE_CONTEXT,
   WORKER_ACTIVATION_CONTEXT,
 } from './session-activation.js'
 import { hookAdapterPath, installHookAdapter } from './hook-adapter.js'
+import { HOOK_INSTALLABLE_HARNESSES } from './harnesses.js'
 import {
   QUESTION_STOP_TIMEOUT_SECONDS,
-  HARNESSES,
   applyPlan,
   detectHarness,
   detectedHarnesses,
@@ -1045,7 +1056,8 @@ describe('the OpenCode adapter', () => {
   })
 
   it('is a harness `hooks install` knows about', () => {
-    expect(HARNESSES).toContain('opencode')
+    expect(HOOK_INSTALLABLE_HARNESSES).toContain('opencode')
+    expect(HOOK_INSTALLABLE_HARNESSES).not.toContain('hermes')
     expect(settingsFile('opencode', false, '/repo', {})).toContain('notifai.js')
   })
 
@@ -1067,6 +1079,179 @@ describe('the OpenCode adapter', () => {
   })
 })
 
+describe('the OpenClaw adapter', () => {
+  const source = openclawPluginSource({
+    adapterPath: ADAPTER,
+    timeoutSeconds: 240,
+  })
+
+  async function loadPlugin() {
+    return (await import(
+      `data:text/javascript;base64,${Buffer.from(source).toString('base64')}`
+    )) as {
+      default: {
+        id: string
+        register(api: {
+          on(name: string, handler: (...args: never[]) => unknown): void
+        }): void
+      }
+    }
+  }
+
+  function handlersOf(mod: Awaited<ReturnType<typeof loadPlugin>>) {
+    const handlers = new Map<string, (...args: never[]) => unknown>()
+    mod.default.register({
+      on(name, handler) {
+        handlers.set(name, handler)
+      },
+    })
+    return handlers
+  }
+
+  it('shells out to the same hook commands the other harnesses run', () => {
+    expect(source).toContain('"hook", event')
+    expect(source).toContain('"--harness", "openclaw"')
+    expect(source).toContain(JSON.stringify(ADAPTER))
+    expect(source).not.toContain('command:stop')
+  })
+
+  it('wires current plugin joints and leaves user abort alone', () => {
+    expect(source).toContain('api.on("before_prompt_build"')
+    expect(source).toContain('api.on("message_received"')
+    expect(source).toContain('api.on("agent_end"')
+    expect(source).toContain('api.on("session_end"')
+    expect(source).toContain('api.on("resolve_exec_env"')
+    expect(source).not.toContain('command:stop')
+  })
+
+  it('classifies root, subagent, ACP, and missing identity safely', async () => {
+    const handlers = handlersOf(await loadPlugin())
+    const activate = handlers.get('before_prompt_build') as (
+      event: object,
+      ctx: object,
+    ) => Promise<{ prependContext?: string } | undefined>
+
+    const root = await activate({}, { sessionKey: 'agent:main:main', workspaceDir: '/ws' })
+    expect(root?.prependContext).toBe(MISSING_LIFECYCLE_GUIDANCE_CONTEXT)
+
+    const worker = await activate({}, { sessionKey: 'agent:main:subagent:abc', workspaceDir: '/ws' })
+    expect(worker?.prependContext).toBe(WORKER_ACTIVATION_CONTEXT)
+
+    const acp = await activate({}, { sessionKey: 'agent:main:acp-child', targetKind: 'acp' })
+    expect(acp?.prependContext).toBe(WORKER_ACTIVATION_CONTEXT)
+
+    const missing = await activate({}, {})
+    expect(missing?.prependContext).toBe(WORKER_ACTIVATION_CONTEXT)
+  })
+
+  it('does not treat heartbeat or cron traffic as User presence', async () => {
+    const handlers = handlersOf(await loadPlugin())
+    const presence = handlers.get('message_received') as (
+      event: object,
+      ctx: object,
+    ) => Promise<void>
+    await presence({ from: '' }, { sessionKey: 'agent:main:main' })
+    await presence({ from: 'cron' }, { sessionKey: 'agent:main:main', trigger: 'cron' })
+    await presence({ from: 'hb' }, { sessionKey: 'agent:main:main', trigger: 'heartbeat' })
+    expect(source).toContain('trigger === "cron" || trigger === "heartbeat"')
+  })
+
+  it('publishes exact sessionKey markers into exec without PATH', async () => {
+    const handlers = handlersOf(await loadPlugin())
+    const resolve = handlers.get('resolve_exec_env') as (
+      event: object,
+      ctx: object,
+    ) => Record<string, string> | undefined
+    expect(resolve({}, { sessionKey: 'agent:main:telegram:dm:1' })).toEqual({
+      NOTIFAI_ACTIVE_HARNESS: 'openclaw',
+      NOTIFAI_ACTIVE_SESSION_ID: 'agent:main:telegram:dm:1',
+    })
+    expect(resolve({}, {})).toBeUndefined()
+    expect(source).not.toContain('PATH:')
+  })
+
+  it('activates a parent session only once', async () => {
+    const handlers = handlersOf(await loadPlugin())
+    const activate = handlers.get('before_prompt_build') as (
+      event: object,
+      ctx: object,
+    ) => Promise<{ prependContext?: string } | undefined>
+    const first = await activate({}, { sessionKey: 'agent:main:main' })
+    const second = await activate({}, { sessionKey: 'agent:main:main' })
+    expect(first?.prependContext).toBe(MISSING_LIFECYCLE_GUIDANCE_CONTEXT)
+    expect(second).toBeUndefined()
+  })
+
+  it('carries the ownership marker so a second checkout replaces it', () => {
+    expect(source).toContain(OPENCLAW_PLUGIN_MARKER)
+    expect(isOurOpenclawPlugin(source)).toBe(true)
+    expect(isOurOpenclawPlugin('export default { id: "other" }')).toBe(false)
+  })
+
+  it('installs beside the OpenClaw config rather than into a hook document', () => {
+    const local = openclawPluginPath(false, '/repo', {})
+    expect(local).toBe(path.join('/repo', '.openclaw', 'extensions', 'notifai', 'index.js'))
+    const global = openclawPluginPath(true, '/repo', { OPENCLAW_STATE_DIR: '/cfg/openclaw' })
+    expect(global).toBe(path.join('/cfg/openclaw', 'extensions', 'notifai', 'index.js'))
+  })
+
+  it('is a harness `hooks install` knows about', () => {
+    expect(HOOK_INSTALLABLE_HARNESSES).toContain('openclaw')
+    expect(settingsFile('openclaw', false, '/repo', {})).toContain('index.js')
+  })
+
+  it('reports the same stable adapter identity as command-hook harnesses', () => {
+    expect(openclawPluginTarget(source)).toEqual({
+      adapter: ADAPTER,
+      current: true,
+      timeoutSeconds: 240,
+    })
+    expect(openclawPluginTarget(source.replace(/^const ADAPTER_VERSION = .*\n/m, ''))).toEqual({
+      adapter: ADAPTER,
+      current: false,
+      timeoutSeconds: 240,
+    })
+    expect(openclawPluginTarget('export default { id: "other" }')).toBeNull()
+  })
+
+  it('merges only the Notifai plugin entry into OpenClaw config', () => {
+    const merged = mergeOpenclawNotifaiEntry(
+      { gateway: { port: 18789 }, plugins: { entries: { memory: { enabled: true } } } },
+      '/repo/.openclaw/extensions/notifai',
+      false,
+    )
+    expect(merged).toMatchObject({
+      gateway: { port: 18789 },
+      plugins: {
+        entries: {
+          memory: { enabled: true },
+          notifai: { enabled: true, hooks: { allowConversationAccess: true } },
+        },
+        load: { paths: ['/repo/.openclaw/extensions/notifai'] },
+      },
+    })
+    const stripped = removeOpenclawNotifaiEntry(merged, '/repo/.openclaw/extensions/notifai')
+    expect(stripped).toEqual({
+      gateway: { port: 18789 },
+      plugins: { entries: { memory: { enabled: true } } },
+    })
+  })
+
+  it('parses JSON with comments without requiring a JSON5 dependency', () => {
+    expect(parseOpenclawConfig('{\n  // port\n  "gateway": { "port": 1 },\n}\n')).toEqual({
+      gateway: { port: 1 },
+    })
+  })
+
+  it('does not treat a skills-only ~/.openclaw tree as OpenClaw evidence', () => {
+    const home = mkdtempSync(path.join(os.tmpdir(), 'notifai-openclaw-skills-only-'))
+    mkdirSync(path.join(home, '.openclaw', 'skills'), { recursive: true })
+    expect(openclawHasGlobalEvidence(existsSync, { HOME: home })).toBe(false)
+    writeFileSync(path.join(home, '.openclaw', 'openclaw.json'), '{}\n')
+    expect(openclawHasGlobalEvidence(existsSync, { HOME: home })).toBe(true)
+  })
+})
+
 describe('detectHarness', () => {
   function project(...entries: string[]): string {
     const dir = mkdtempSync(path.join(os.tmpdir(), 'notifai-detect-'))
@@ -1099,7 +1284,7 @@ describe('detectHarness', () => {
     const dir = project('AGENTS.md')
     const answer = detectHarness(dir)
     expect(answer).not.toBe('codex')
-    expect(HARNESSES.includes(answer as never) || answer === null).toBe(true)
+    expect(HOOK_INSTALLABLE_HARNESSES.includes(answer as never) || answer === null).toBe(true)
   })
 
   it('pairs AGENTS.md with CLAUDE.md as Claude Code, not Codex', () => {
@@ -1112,6 +1297,7 @@ describe('detectHarness', () => {
     expect(detectHarness(project('.codex'))).toBe('codex')
     expect(detectHarness(project('.cursor'))).toBe('cursor')
     expect(detectHarness(project('.opencode'))).toBe('opencode')
+    expect(detectHarness(project('.openclaw'))).toBe('openclaw')
   })
 
   it('returns null when the project itself names two harnesses', () => {
@@ -1155,7 +1341,7 @@ describe('detectHarness', () => {
     // Whatever this machine has, an empty project must never crash and must
     // return either a single harness or null — never an arbitrary pick.
     const answer = detectHarness(empty)
-    expect(answer === null || HARNESSES.includes(answer)).toBe(true)
+    expect(answer === null || HOOK_INSTALLABLE_HARNESSES.includes(answer)).toBe(true)
   })
 })
 
@@ -1232,6 +1418,9 @@ describe('Windows hook commands and discovery', () => {
     expect(opencodePluginPath(true, '/repo', env, 'win32')).toBe(
       path.join('C:\\Users\\Ada', '.config', 'opencode', 'plugins', 'notifai.js'),
     )
+    expect(openclawPluginPath(true, '/repo', env, 'win32')).toBe(
+      path.join('C:\\Users\\Ada', '.openclaw', 'extensions', 'notifai', 'index.js'),
+    )
   })
 
   it('makes OpenCode spawn the adapter through Node on Windows with shell:false', () => {
@@ -1253,6 +1442,26 @@ describe('Windows hook commands and discovery', () => {
       nodePath: winNode,
     })
   })
+
+  it('makes OpenClaw spawn the adapter through Node on Windows with shell:false', () => {
+    const source = openclawPluginSource({
+      adapterPath: winAdapter,
+      timeoutSeconds: 240,
+      platform: 'win32',
+      nodePath: winNode,
+    })
+    expect(source).toContain(`const NODE = ${JSON.stringify(winNode)}`)
+    expect(source).toContain('spawn(NODE, [ADAPTER, "hook", event, "--owner", "notifai", "--harness", "openclaw"]')
+    expect(source).toContain('shell: false')
+    expect(source).toContain('windowsHide: true')
+    expect(source).not.toContain('spawn(ADAPTER,')
+    expect(openclawPluginTarget(source)).toEqual({
+      adapter: winAdapter,
+      current: true,
+      timeoutSeconds: 240,
+      nodePath: winNode,
+    })
+  })
 })
 
 /**