@raidiant/notifai 10.0.0 → 10.1.1

package/src/openclaw-plugin.ts

@@ -0,0 +1,409 @@
+import path from 'node:path'
+import { hookHostPlatform, type HookHostPlatform } from './hook-adapter.js'
+import { harnessAccountHome } from './install-hooks.js'
+import {
+  MISSING_LIFECYCLE_GUIDANCE_CONTEXT,
+  WORKER_ACTIVATION_CONTEXT,
+} from './session-activation.js'
+
+/**
+ * The OpenClaw adapter.
+ *
+ * OpenClaw's extension point is an in-process Gateway plugin, not a command
+ * hook. The generated module shells out to the same `notifai hook <event>`
+ * commands every other harness invokes, so presence, activation, and
+ * retirement stay in the CLI.
+ *
+ *   before_prompt_build -> session-start / subagent-start  (first owner/worker)
+ *   message_received    -> user-prompt-submit              (User is present)
+ *   agent_end           -> stop                            (the turn ended)
+ *   session_end         -> session-end                     (retire local state)
+ *   resolve_exec_env    -> NOTIFAI_ACTIVE_* markers        (exact Source Context)
+ *
+ * `command:stop` is a User abort and is deliberately not wired. Asynchronous
+ * ask is unsupported until a live continuation probe.
+ */
+
+export const OPENCLAW_PLUGIN_MARKER = '// notifai managed openclaw plugin'
+export const OPENCLAW_PLUGIN_ID = 'notifai'
+export const OPENCLAW_PLUGIN_FILENAME = 'index.js'
+export const OPENCLAW_PLUGIN_MANIFEST = 'openclaw.plugin.json'
+export const OPENCLAW_PLUGIN_PACKAGE = 'package.json'
+
+const OPENCLAW_ADAPTER_VERSION = 1
+
+export const OPENCLAW_EVENTS = [
+  ['SessionStart', 'session-start'],
+  ['SubagentStart', 'subagent-start'],
+  ['UserPromptSubmit', 'user-prompt-submit'],
+  ['Stop', 'stop'],
+  ['SessionEnd', 'session-end'],
+] as const
+
+export function openclawStateDir(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform | HookHostPlatform = process.platform,
+): string {
+  const override = env['OPENCLAW_STATE_DIR']
+  if (override !== undefined && override !== '') return override
+  const homeOverride = env['OPENCLAW_HOME']
+  if (homeOverride !== undefined && homeOverride !== '') {
+    return path.join(homeOverride, '.openclaw')
+  }
+  return path.join(harnessAccountHome(env, platform), '.openclaw')
+}
+
+export function openclawConfigPath(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform | HookHostPlatform = process.platform,
+): string {
+  const override = env['OPENCLAW_CONFIG_PATH']
+  if (override !== undefined && override !== '') return override
+  return path.join(openclawStateDir(env, platform), 'openclaw.json')
+}
+
+export function openclawPluginDir(
+  global: boolean,
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform | HookHostPlatform = process.platform,
+): string {
+  return global
+    ? path.join(openclawStateDir(env, platform), 'extensions', OPENCLAW_PLUGIN_ID)
+    : path.join(cwd, '.openclaw', 'extensions', OPENCLAW_PLUGIN_ID)
+}
+
+export function openclawPluginPath(
+  global: boolean,
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform | HookHostPlatform = process.platform,
+): string {
+  return path.join(openclawPluginDir(global, cwd, env, platform), OPENCLAW_PLUGIN_FILENAME)
+}
+
+export interface OpenclawPluginOptions {
+  adapterPath: string
+  timeoutSeconds: number
+  platform?: NodeJS.Platform | HookHostPlatform
+  nodePath?: string
+}
+
+export function openclawPluginManifest(): string {
+  return `${JSON.stringify(
+    {
+      id: OPENCLAW_PLUGIN_ID,
+      name: 'Notifai',
+      description: 'Notifai lifecycle activation, Source Context, and session observation.',
+      activation: { onStartup: true },
+      configSchema: { type: 'object', additionalProperties: false },
+    },
+    null,
+    2,
+  )}\n`
+}
+
+export function openclawPluginPackage(): string {
+  return `${JSON.stringify(
+    {
+      name: 'notifai-openclaw',
+      version: '1.0.0',
+      type: 'module',
+      openclaw: { extensions: [`./${OPENCLAW_PLUGIN_FILENAME}`] },
+    },
+    null,
+    2,
+  )}\n`
+}
+
+export function openclawPluginSource(options: OpenclawPluginOptions): string {
+  const { adapterPath, timeoutSeconds } = options
+  const win32 = hookHostPlatform(options.platform) === 'win32'
+  const nodeConstant = win32
+    ? `const NODE = ${JSON.stringify(options.nodePath ?? process.execPath)}\n`
+    : ''
+  const spawnArguments = win32
+    ? 'NODE, [ADAPTER, "hook", event, "--owner", "notifai", "--harness", "openclaw"]'
+    : 'ADAPTER, ["hook", event, "--owner", "notifai", "--harness", "openclaw"]'
+  const windowsHide = win32 ? '\n        windowsHide: true,' : ''
+  return `${OPENCLAW_PLUGIN_MARKER}
+// Generated by \`notifai hooks install --harness openclaw\`. Edits are lost on
+// the next install; change the CLI instead, which is where the logic lives.
+import { spawn } from "node:child_process"
+
+${nodeConstant}const ADAPTER = ${JSON.stringify(adapterPath)}
+const TIMEOUT_MS = ${timeoutSeconds * 1000}
+const ADAPTER_VERSION = ${OPENCLAW_ADAPTER_VERSION}
+const MISSING_LIFECYCLE_GUIDANCE_CONTEXT = ${JSON.stringify(MISSING_LIFECYCLE_GUIDANCE_CONTEXT)}
+const WORKER_ACTIVATION_CONTEXT = ${JSON.stringify(WORKER_ACTIVATION_CONTEXT)}
+
+function runHook(event, envelope) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn(${spawnArguments}, {
+        env: process.env,
+        shell: false,${windowsHide}
+        stdio: ["pipe", "pipe", "pipe"],
+      })
+    } catch {
+      resolve(null)
+      return
+    }
+
+    let stdout = ""
+    let settled = false
+    const finish = (value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(value)
+    }
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM")
+      finish(null)
+    }, TIMEOUT_MS)
+
+    child.stdout?.setEncoding("utf-8")
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk
+    })
+    child.stderr?.resume()
+    child.on("error", () => finish(null))
+    child.on("close", () => finish(stdout))
+
+    try {
+      child.stdin?.end(JSON.stringify(envelope))
+    } catch {
+      finish(null)
+    }
+  })
+}
+
+function sessionKeyOf(event, ctx) {
+  const key = ctx?.sessionKey ?? event?.sessionKey ?? event?.context?.sessionKey
+  return typeof key === "string" ? key.trim() : ""
+}
+
+function workspaceDirOf(event, ctx) {
+  const dir = ctx?.workspaceDir ?? event?.workspaceDir ?? event?.context?.workspaceDir
+  return typeof dir === "string" && dir.length > 0 ? dir : process.cwd()
+}
+
+function isWorkerSession(sessionKey, ctx) {
+  if (sessionKey === "") return true
+  if (sessionKey.includes(":subagent:")) return true
+  if (sessionKey.includes(":acp:")) return true
+  if (ctx?.targetKind === "acp" || ctx?.dispatchKind === "acp") return true
+  if (typeof ctx?.parentSessionKey === "string" && ctx.parentSessionKey.length > 0) return true
+  return false
+}
+
+function isUserMessage(event, ctx) {
+  const from = event?.from ?? event?.context?.from ?? ctx?.senderId
+  if (typeof from !== "string" || from.trim().length === 0) return false
+  const trigger = ctx?.trigger ?? event?.trigger
+  if (trigger === "cron" || trigger === "heartbeat") return false
+  return true
+}
+
+function register(api) {
+  const activated = new Set()
+  api.on("before_prompt_build", async (event, ctx) => {
+    const sessionKey = sessionKeyOf(event, ctx)
+    if (sessionKey === "") return { prependContext: WORKER_ACTIVATION_CONTEXT }
+    if (activated.has(sessionKey)) return
+    const worker = isWorkerSession(sessionKey, ctx)
+    const resolved = await runHook(worker ? "subagent-start" : "session-start", {
+      session_id: sessionKey,
+      cwd: workspaceDirOf(event, ctx),
+      hook_event_name: worker ? "SubagentStart" : "SessionStart",
+    })
+    const context = typeof resolved === "string" && resolved.trim().length > 0
+      ? resolved.trim()
+      : worker ? WORKER_ACTIVATION_CONTEXT : MISSING_LIFECYCLE_GUIDANCE_CONTEXT
+    activated.add(sessionKey)
+    return { prependContext: context }
+  })
+
+  api.on("message_received", async (event, ctx) => {
+    if (!isUserMessage(event, ctx)) return
+    const sessionKey = sessionKeyOf(event, ctx)
+    if (sessionKey === "") return
+    await runHook("user-prompt-submit", {
+      session_id: sessionKey,
+      cwd: workspaceDirOf(event, ctx),
+      hook_event_name: "UserPromptSubmit",
+    })
+  })
+
+  api.on("agent_end", async (event, ctx) => {
+    const sessionKey = sessionKeyOf(event, ctx)
+    if (sessionKey === "") return
+    await runHook("stop", {
+      session_id: sessionKey,
+      cwd: workspaceDirOf(event, ctx),
+      hook_event_name: "Stop",
+    })
+  })
+
+  api.on("session_end", async (event, ctx) => {
+    const sessionKey = sessionKeyOf(event, ctx)
+    if (sessionKey === "") return
+    activated.delete(sessionKey)
+    await runHook("session-end", {
+      session_id: sessionKey,
+      cwd: workspaceDirOf(event, ctx),
+      hook_event_name: "SessionEnd",
+    })
+  })
+
+  api.on("resolve_exec_env", (event, ctx) => {
+    const sessionKey = sessionKeyOf(event, ctx)
+    if (sessionKey === "") return
+    return {
+      NOTIFAI_ACTIVE_HARNESS: "openclaw",
+      NOTIFAI_ACTIVE_SESSION_ID: sessionKey,
+    }
+  })
+}
+
+export default {
+  id: ${JSON.stringify(OPENCLAW_PLUGIN_ID)},
+  name: "Notifai",
+  register,
+}
+`
+}
+
+export function isOurOpenclawPlugin(contents: string): boolean {
+  return contents.includes(OPENCLAW_PLUGIN_MARKER)
+}
+
+export function openclawPluginTarget(
+  contents: string,
+): { adapter: string; current: boolean; timeoutSeconds?: number; nodePath?: string } | null {
+  if (!isOurOpenclawPlugin(contents)) return null
+  const adapter = /^const ADAPTER = (".*")$/m.exec(contents)?.[1]
+  const node = /^const NODE = (".*")$/m.exec(contents)?.[1]
+  const version = Number(/^const ADAPTER_VERSION = (\d+)$/m.exec(contents)?.[1] ?? 0)
+  const timeoutMs = Number(/^const TIMEOUT_MS = (\d+)$/m.exec(contents)?.[1] ?? Number.NaN)
+  if (adapter === undefined) return null
+  try {
+    return {
+      adapter: JSON.parse(adapter) as string,
+      current: version === OPENCLAW_ADAPTER_VERSION,
+      ...(Number.isFinite(timeoutMs) ? { timeoutSeconds: timeoutMs / 1000 } : {}),
+      ...(node === undefined ? {} : { nodePath: JSON.parse(node) as string }),
+    }
+  } catch {
+    return null
+  }
+}
+
+export function parseOpenclawConfig(source: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(source)
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>
+    }
+  } catch {
+    const stripped = source
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/^\s*\/\/.*$/gm, '')
+      .replace(/,(\s*[}\]])/g, '$1')
+    const parsed: unknown = JSON.parse(stripped)
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>
+    }
+  }
+  throw new Error('OpenClaw config is not a JSON object')
+}
+
+export function mergeOpenclawNotifaiEntry(
+  config: Record<string, unknown>,
+  pluginDir: string,
+  global: boolean,
+): Record<string, unknown> {
+  const plugins =
+    config.plugins !== null && typeof config.plugins === 'object' && !Array.isArray(config.plugins)
+      ? { ...(config.plugins as Record<string, unknown>) }
+      : {}
+  const entries =
+    plugins.entries !== null && typeof plugins.entries === 'object' && !Array.isArray(plugins.entries)
+      ? { ...(plugins.entries as Record<string, unknown>) }
+      : {}
+  const existing =
+    entries[OPENCLAW_PLUGIN_ID] !== null &&
+    typeof entries[OPENCLAW_PLUGIN_ID] === 'object' &&
+    !Array.isArray(entries[OPENCLAW_PLUGIN_ID])
+      ? { ...(entries[OPENCLAW_PLUGIN_ID] as Record<string, unknown>) }
+      : {}
+  const hooks =
+    existing.hooks !== null && typeof existing.hooks === 'object' && !Array.isArray(existing.hooks)
+      ? { ...(existing.hooks as Record<string, unknown>) }
+      : {}
+  entries[OPENCLAW_PLUGIN_ID] = {
+    ...existing,
+    enabled: true,
+    hooks: { ...hooks, allowConversationAccess: true },
+  }
+  plugins.entries = entries
+  if (!global) {
+    const load =
+      plugins.load !== null && typeof plugins.load === 'object' && !Array.isArray(plugins.load)
+        ? { ...(plugins.load as Record<string, unknown>) }
+        : {}
+    const paths = Array.isArray(load.paths) ? [...load.paths] : []
+    if (!paths.includes(pluginDir)) paths.push(pluginDir)
+    load.paths = paths
+    plugins.load = load
+  }
+  return { ...config, plugins }
+}
+
+export function removeOpenclawNotifaiEntry(
+  config: Record<string, unknown>,
+  pluginDir: string,
+): Record<string, unknown> {
+  const plugins =
+    config.plugins !== null && typeof config.plugins === 'object' && !Array.isArray(config.plugins)
+      ? { ...(config.plugins as Record<string, unknown>) }
+      : {}
+  const entries =
+    plugins.entries !== null && typeof plugins.entries === 'object' && !Array.isArray(plugins.entries)
+      ? { ...(plugins.entries as Record<string, unknown>) }
+      : {}
+  delete entries[OPENCLAW_PLUGIN_ID]
+  if (Object.keys(entries).length > 0) plugins.entries = entries
+  else delete plugins.entries
+  const load =
+    plugins.load !== null && typeof plugins.load === 'object' && !Array.isArray(plugins.load)
+      ? { ...(plugins.load as Record<string, unknown>) }
+      : {}
+  if (Array.isArray(load.paths)) {
+    const paths = load.paths.filter((value) => value !== pluginDir)
+    if (paths.length > 0) load.paths = paths
+    else delete load.paths
+  }
+  if (Object.keys(load).length > 0) plugins.load = load
+  else delete plugins.load
+  if (Object.keys(plugins).length > 0) return { ...config, plugins }
+  const next = { ...config }
+  delete next.plugins
+  return next
+}
+
+/** Config-directory presence is not ownership. These files mean OpenClaw is actually configured. */
+export function openclawHasGlobalEvidence(
+  exists: (file: string) => boolean,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform | HookHostPlatform = process.platform,
+): boolean {
+  const state = openclawStateDir(env, platform)
+  return (
+    exists(openclawConfigPath(env, platform)) ||
+    exists(path.join(state, 'agents')) ||
+    exists(path.join(state, 'workspace'))
+  )
+}

package/src/program.test.ts

@@ -4,6 +4,7 @@ import path from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { buildProgram, type ProgramRunners } from './program.js'
 import type { CommandDeps } from './commands.js'
+import { QUESTION_SETTLEMENT_INPUT_ENV } from './question-settlement-process.js'
 
 /**
  * The layer these tests own is the argv boundary: what a real command line
@@ -125,6 +126,30 @@ describe('program argv parsing', () => {
     expect(label).toBe('Hermes Support')
   })
 
+  it('hands the detached settlement input to the internal hook owner', async () => {
+    const deps = makeDeps()
+    const input = JSON.stringify({ session_id: 'session-1', cwd: '/tmp/project' })
+    deps.env[QUESTION_SETTLEMENT_INPUT_ENV] = input
+    let seen:
+      | { event: string; input: string; harness: string | undefined }
+      | undefined
+
+    const result = await parse(
+      ['hook', 'question-settlement', '--owner', 'notifai', '--harness', 'codex'],
+      {
+        hookRun: (async (_deps, event, readInput, harness) => {
+          seen = { event, input: await readInput(), harness }
+          return 0
+        }) as ProgramRunners['hookRun'],
+      },
+      deps,
+    )
+
+    expect(result.exitCode).toBe(0)
+    expect(seen).toEqual({ event: 'question-settlement', input, harness: 'codex' })
+    expect(deps.env[QUESTION_SETTLEMENT_INPUT_ENV]).toBeUndefined()
+  })
+
   it('dispatches sounds --json onto soundsCommand', async () => {
     let seen: Record<string, unknown> | undefined
     const result = await parse(['sounds', '--json'], {
@@ -166,6 +191,16 @@ describe('program argv parsing', () => {
     expect(seen).toMatchObject({ skills: true, setupScope: 'global', hooks: false })
   })
 
+  it('dispatches update --json onto the local CLI recovery', async () => {
+    let seen: Record<string, unknown> | undefined
+    const { exitCode } = await parse(
+      ['update', '--json'],
+      { update: ((_deps, flags) => ((seen = flags as Record<string, unknown>), 0)) as ProgramRunners['update'] },
+    )
+    expect(exitCode).toBe(0)
+    expect(seen).toEqual({ json: true })
+  })
+
   it('disentangles --no-wait and --wait from their shared commander flag', async () => {
     const capture = (sink: Record<string, unknown>[]): ProgramRunners['send'] =>
       (async (_deps, flags) => (sink.push(flags as Record<string, unknown>), 0)) as ProgramRunners['send']

package/src/program.ts

@@ -8,6 +8,7 @@ import {
   authStatusCommand,
   capabilitiesCommand,
   closeCommand,
+  cliUpdateCommand,
   configExplainCommand,
   configSetCommand,
   configShowCommand,
@@ -42,6 +43,7 @@ import type { SkillScope } from './native-skills.js'
 import { GROUP, SEND_GROUP, helpConfiguration, rootHelpFooter } from './ui/help.js'
 import { readStdinWithTimeout } from './hook-input.js'
 import { argvFlagNames } from './logging.js'
+import { QUESTION_SETTLEMENT_INPUT_ENV } from './question-settlement-process.js'
 
 /**
  * One source of truth for the version: the manifest npm actually published.
@@ -80,6 +82,7 @@ function commandPath(command: Command): string {
 const defaultRunners = {
   init: initCommand,
   doctor: doctorCommand,
+  update: cliUpdateCommand,
   login: loginCommand,
   logout: logoutCommand,
   authStatus: authStatusCommand,
@@ -180,11 +183,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
@@ -260,6 +264,16 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
       exit(await runners.doctor(deps, opts))
     })
 
+  program
+    .command('update')
+    .helpGroup(GROUP.start)
+    .summary('Update the Notifai command this shell uses')
+    .description('Update the effective global Notifai installation and keep Question Routing on it')
+    .option('--json', 'machine-readable installation and adapter result')
+    .action((opts: { json?: boolean }) => {
+      exit(runners.update(deps, opts))
+    })
+
   const project = program
     .command('project')
     .helpGroup(GROUP.daily)
@@ -292,7 +306,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
 
   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)')
@@ -499,10 +513,10 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     })
 
   program
-    .command('status <request_id>')
+    .command('status <question_or_request_id>')
     .helpGroup(GROUP.agent)
-    .summary('Show the evidence trail for a request')
-    .description('Show the evidence trail for a notification request')
+    .summary('Show question state or request evidence')
+    .description('Show local question state and, once submitted, the notification request evidence trail')
     .option('--json', 'machine-readable output')
     .action(async (requestId: string, opts: { json?: boolean }) => {
       exit(await runners.status(deps, requestId, opts))
@@ -628,7 +642,18 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .option('--harness <name>', 'internal harness output adapter')
     .action(async (event: string, opts: { harness?: string }) => {
       const harness = HOOK_INSTALLABLE_HARNESSES.find((candidate) => candidate === opts.harness)
-      exit(await runners.hookRun(deps, event, () => readStdinWithTimeout(), harness))
+      const settlementInput = deps.env[QUESTION_SETTLEMENT_INPUT_ENV]
+      if (event === 'question-settlement') {
+        delete deps.env[QUESTION_SETTLEMENT_INPUT_ENV]
+      }
+      exit(await runners.hookRun(
+        deps,
+        event,
+        event === 'question-settlement' && settlementInput !== undefined
+          ? async () => settlementInput
+          : () => readStdinWithTimeout(),
+        harness,
+      ))
     })
 
   const hooks = program
@@ -641,7 +666,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 }) => {
@@ -650,7 +675,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/question-settlement-process.ts

@@ -0,0 +1,47 @@
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import type { HookInstallableHarness } from './harnesses.js'
+import type { HookEnvelope } from './hooks.js'
+
+/** Private handoff from the short prompt hook to its detached question owner. */
+export const QUESTION_SETTLEMENT_INPUT_ENV = 'NOTIFAI_INTERNAL_QUESTION_SETTLEMENT_INPUT'
+
+export interface QuestionSettlementLaunch {
+  envelope: Pick<HookEnvelope, 'session_id' | 'cwd'>
+  harness: HookInstallableHarness
+}
+
+/**
+ * Launch the exact installed CLI build as a detached owner.
+ *
+ * UserPromptSubmit sits in front of the User's new turn, so it may only pay the
+ * process-spawn cost. The child owns submission and the complete answer window.
+ */
+export function spawnQuestionSettlement(launch: QuestionSettlementLaunch): void {
+  const child = spawn(
+    process.execPath,
+    [
+      fileURLToPath(new URL('./main.js', import.meta.url)),
+      'hook',
+      'question-settlement',
+      '--owner',
+      'notifai',
+      '--harness',
+      launch.harness,
+    ],
+    {
+      cwd: launch.envelope.cwd ?? process.cwd(),
+      detached: true,
+      env: {
+        ...process.env,
+        [QUESTION_SETTLEMENT_INPUT_ENV]: JSON.stringify(launch.envelope),
+      },
+      stdio: 'ignore',
+      windowsHide: true,
+    },
+  )
+  // Spawn failures are diagnosed by the next ordinary lifecycle hook, which
+  // still owns the durable registration. Never turn one into a prompt delay.
+  child.once('error', () => undefined)
+  child.unref()
+}

package/src/readiness.ts

@@ -80,15 +80,48 @@ export function firstBlocker(readiness: Readiness): ReadinessState | null {
   return readiness.states.find((s) => s.status === 'gap') ?? null
 }
 
+/**
+ * Question Routing: what lets a question reach a phone when nobody is at the
+ * terminal. Hooks, their sub-states, and the setting that admits them.
+ *
+ * Separate from `isOptionalSetup` because these are also the states a human
+ * should not be handed as leftovers — "Optional, not set up" is a fair line
+ * about the agent skill and a confusing one about a session pointer.
+ */
+export function isOptionalAutomation(id: string): boolean {
+  return id === 'hooks' || id.startsWith('hooks-') || id === 'question-routing-settings'
+}
+
+/**
+ * Automation layered on top of a product that already sends: Question Routing
+ * and the agent guidance skill.
+ *
+ * Real, and reported. `doctor` is the report and judges it strictly. Anything
+ * whose job is to get a first notification delivered treats it as a line to
+ * print, never a gate — a hook diagnostic or a duplicate skill install in
+ * front of the delivery proof means a setup that can already send never proves
+ * that it can. The one that fires most often, a turn that has not ended yet,
+ * cannot be closed by the agent standing inside that turn at all.
+ */
+export function isOptionalSetup(id: string): boolean {
+  return id === 'skill' || isOptionalAutomation(id)
+}
+
+/** The first thing in the way that is not optional automation. */
+export function firstRequiredBlocker(readiness: Readiness): ReadinessState | null {
+  return readiness.states.find((s) => s.status === 'gap' && !isOptionalSetup(s.id)) ?? null
+}
+
 /**
  * Ready enough to be useful, which is not the same as every box ticked.
  *
  * Hooks and the agent skill are genuinely optional — `send` works without
  * them — so an install that declined both is finished, not half-done. Saying
- * otherwise trains people to ignore the summary line.
+ * otherwise trains people to ignore the summary line, and it is the summary
+ * line an agent branches on.
  */
 export function isReady(readiness: Readiness): boolean {
-  return firstBlocker(readiness) === null
+  return firstRequiredBlocker(readiness) === null
 }
 
 const SEND_PREREQUISITES = new Set([

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