@raidiant/notifai 0.4.0 → 0.5.0

package/src/install-hooks.test.ts

@@ -90,6 +90,7 @@ describe('hook config', () => {
   it('uses one fixed blocking process budget rather than accepting mutable timing inputs', () => {
     const config = buildHookConfig({ adapterPath: ADAPTER })
     expect(config['Stop']?.[0]?.hooks[0]?.timeout).toBe(540)
+    expect(config['Stop']?.[0]?.hooks[0]?.async).toBeUndefined()
     // Claude Code caps UserPromptSubmit at 30s; Codex gives SessionEnd 1-3s.
     expect(config['UserPromptSubmit']?.[0]?.hooks[0]?.timeout).toBe(15)
     expect(config['SessionEnd']?.[0]?.hooks[0]?.timeout).toBe(3)
@@ -110,12 +111,52 @@ describe('hook config', () => {
 
   it('lets Codex own Stop timeout while keeping short fixed lifecycle budgets', () => {
     const codex = buildHookConfig({ adapterPath: ADAPTER, harness: 'codex' })
-    const claude = buildHookConfig({ adapterPath: ADAPTER, harness: 'claude-code' })
 
     expect(codex['UserPromptSubmit']?.[0]?.hooks[0]?.timeout).toBe(15)
-    expect(codex['Stop']?.[0]?.hooks[0]?.timeout).toBeUndefined()
     expect(codex['SessionEnd']?.[0]?.hooks[0]?.timeout).toBe(3)
-    expect(claude['Stop']?.[0]?.hooks[0]?.timeout).toBe(540)
+    // Codex hashes the exact serialized definition into `trusted_hash`, so its
+    // Stop handler stays a bare blocking command: declaring a timeout would
+    // invalidate the user's approval and the handler would silently stop.
+    expect(codex['Stop']?.[0]?.hooks[0]).toEqual({
+      type: 'command',
+      command: hookCommand(ADAPTER, 'stop', 'codex'),
+    })
+  })
+
+  it('gives Claude Code an asynchronous Stop with an explicit waiter budget', () => {
+    const claude = buildHookConfig({ adapterPath: ADAPTER, harness: 'claude-code' })
+
+    // `async: true` is what frees the turn: the handler returns at once and the
+    // same process lives on as the waiter. The explicit timeout is what keeps
+    // that process alive — Claude kills a background hook at its own 600s
+    // default and reports nothing, so a wait near that boundary loses answers.
+    expect(claude['Stop']?.[0]?.hooks[0]).toEqual({
+      type: 'command',
+      command: hookCommand(ADAPTER, 'stop', 'claude-code'),
+      timeout: 3600,
+      async: true,
+    })
+    expect(claude['UserPromptSubmit']?.[0]?.hooks[0]?.async).toBeUndefined()
+    expect(claude['SessionEnd']?.[0]?.hooks[0]?.async).toBeUndefined()
+  })
+
+  it('leaves exactly one handler per event when an old blocking shape is reinstalled over', () => {
+    const old = mergeHooks({}, buildHookConfig({ adapterPath: ADAPTER }), SCRIPT)
+    const migrated = mergeHooks(
+      old.document,
+      buildHookConfig({ adapterPath: ADAPTER, harness: 'claude-code' }),
+      SCRIPT,
+    )
+
+    for (const event of ['UserPromptSubmit', 'Stop', 'SessionEnd']) {
+      const groups = migrated.document.hooks?.[event] ?? []
+      expect(groups.flatMap((group) => group.hooks)).toHaveLength(1)
+    }
+    expect(migrated.document.hooks?.['Stop']?.[0]?.hooks[0]).toMatchObject({
+      timeout: 3600,
+      async: true,
+    })
+    expect(migrated.replaced.sort()).toEqual(['SessionEnd', 'Stop', 'UserPromptSubmit'])
   })
 })
 

package/src/install-hooks.ts

@@ -12,7 +12,7 @@ import { parse as parseToml } from 'smol-toml'
 import { atomicWriteFileSync } from './atomic-file.js'
 import { hookAdapterPath } from './hook-adapter.js'
 import { opencodePluginPath, opencodePluginTarget } from './opencode-plugin.js'
-import { HARNESSES, HOOK_TIMING, type Harness } from './harnesses.js'
+import { HARNESSES, type Harness } from './harnesses.js'
 
 export { HARNESSES, type Harness } from './harnesses.js'
 
@@ -113,28 +113,54 @@ export interface BuildOptions {
   harness?: Harness
 }
 
-/** Generated blocking adapters grant the owner budget one fixed minute of host headroom. */
-const HOOK_CEILING_SECONDS = HOOK_TIMING.totalSeconds + HOOK_TIMING.hostHeadroomSeconds
+/**
+ * Claude Code's Stop handler returns instantly and the same process lives on
+ * out of band as the escalation waiter, so this `timeout` bounds a background
+ * process rather than the user's turn.
+ *
+ * It is always declared, and declared far above the longest wait a waiter can
+ * take. Claude's default is 600 s and the kill is **silent** — the backgrounded
+ * process simply vanishes, no error is reported anywhere, and the answer the
+ * user already gave is never delivered. Sitting anywhere near that boundary
+ * turns a slow reply into a lost one, so this does not: an explicit value
+ * raises the ceiling (verified against a 660 s wait under an hour-long
+ * declaration), and an hour is several times the waiter's own ceiling.
+ */
+export const CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS = 3600
+
+/**
+ * The declared process budget for a host that holds its turn while the waiter
+ * runs: the waiter's own ceiling plus a minute of host headroom, as one plain
+ * number rather than a budget carved into reserves.
+ *
+ * Codex is deliberately absent from this. It owns its Stop timeout today, and
+ * declaring one would change the serialized definition Codex hashes into
+ * `trusted_hash` — which silently stops every Notifai handler from running
+ * until the user re-approves them in `/hooks`.
+ */
+export const BLOCKING_STOP_TIMEOUT_SECONDS = 540
 
 /**
- * Stable process budget for a blocking turn-end adapter.
+ * The turn-end handler, whose shape is the whole per-harness difference.
  *
- * Codex trusts the exact serialized hook definition. Deriving this timeout
- * from mutable question preferences meant changing `ask_grace_seconds`
- * silently invalidated Stop trust while the other two handlers kept running.
- * The runtime already fits grace and reply waiting inside the harness ceiling;
- * the installed identity therefore stays at that ceiling across preferences.
+ * Claude Code takes the answer over its own inbox socket, so its Stop hook is
+ * `async: true`: it returns immediately, the terminal is never held, and the
+ * waiter finishes out of band. Every other host still delivers by printing a
+ * continuation to this process's stdout, so its Stop hook blocks and needs a
+ * declared ceiling above the wait — except Codex, which owns that number
+ * itself and whose definition must stay byte-stable for its trust store.
  */
-export function blockingHookTimeoutSeconds(): number {
-  return HOOK_CEILING_SECONDS
+function stopHandler(adapterPath: string, harness: Harness | undefined): HookHandler {
+  const command = hookCommand(adapterPath, 'stop', harness)
+  if (harness === 'claude-code') {
+    return { type: 'command', command, timeout: CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS, async: true }
+  }
+  if (harness === 'codex') return { type: 'command', command }
+  return { type: 'command', command, timeout: BLOCKING_STOP_TIMEOUT_SECONDS }
 }
 
 export function buildHookConfig(options: BuildOptions): HookConfig {
   const { adapterPath } = options
-  const hostOwnsStopTimeout = options.harness === 'codex'
-  // Runtime preferences fit inside this fixed process budget without becoming
-  // part of the serialized definition Codex asks the user to trust.
-  const blockingTimeout = blockingHookTimeoutSeconds()
   return {
     UserPromptSubmit: [
       {
@@ -149,17 +175,7 @@ export function buildHookConfig(options: BuildOptions): HookConfig {
         ],
       },
     ],
-    Stop: [
-      {
-        hooks: [
-          {
-            type: 'command',
-            command: hookCommand(adapterPath, 'stop', options.harness),
-            ...(hostOwnsStopTimeout ? {} : { timeout: blockingTimeout }),
-          },
-        ],
-      },
-    ],
+    Stop: [{ hooks: [stopHandler(adapterPath, options.harness)] }],
     SessionEnd: [
       {
         hooks: [
@@ -192,7 +208,6 @@ interface CursorSettingsDocument {
 
 /** Cursor's native schema is flat and uses lower-camel lifecycle event names. */
 export function buildCursorHookConfig(options: BuildOptions): CursorHookConfig {
-  const blockingTimeout = blockingHookTimeoutSeconds()
   return {
     beforeSubmitPrompt: [
       {
@@ -203,7 +218,7 @@ export function buildCursorHookConfig(options: BuildOptions): CursorHookConfig {
     stop: [
       {
         command: hookCommand(options.adapterPath, 'stop', 'cursor'),
-        timeout: blockingTimeout,
+        timeout: BLOCKING_STOP_TIMEOUT_SECONDS,
         // A continuation may register a real follow-up question. Match the
         // session-state cap so those chains are useful but never unbounded.
         loop_limit: 3,

package/src/interactive.ts

@@ -594,16 +594,11 @@ async function routingScreen(deps: CommandDeps, readiness: Readiness): Promise<b
   clack.note(
     'When an agent registers a question, it appears in your terminal first.\n' +
       'After the grace below, it goes to your phone and Mac as a notification\n' +
-      'with real answer buttons, and your answer comes back to the agent. Turn\n' +
-      'on “Only when away” if local activity should keep it here instead.\n\n' +
+      'with real answer buttons, and your answer comes back to the agent —\n' +
+      'whether or not you are still at this machine.\n\n' +
       [
         row('Wired to', wiringSummary(hooks)),
         row('Send', config.ask_notifications.value ? 'yes' : 'no — questions stay in the terminal'),
-        row(
-          'Only when away',
-          config.require_idle.value ? 'yes' : 'no — reach me even while I am working',
-        ),
-        row('Away after', formatValue('away_after_seconds', config.away_after_seconds.value)),
         row('Grace', formatValue('ask_grace_seconds', config.ask_grace_seconds.value)),
       ].join('\n'),
     'Question routing',

package/src/logging.test.ts

@@ -428,12 +428,12 @@ describe('rendering', () => {
       run: 'r_1',
       cmd: 'hook stop',
       pid: 1,
-      data: { verdict: 'held', reason: 'user-present', idle_seconds: 4 },
+      data: { verdict: 'held', reason: 'notifications-off', source: 'default' },
     })
     expect(line).toContain('2026-08-11 12:04:31')
     expect(line).toContain('hook.gate')
-    expect(line).toContain('reason=user-present')
-    expect(line).toContain('idle_seconds=4')
+    expect(line).toContain('reason=notifications-off')
+    expect(line).toContain('source=default')
   })
 
   it('stays on one line whatever the payload', () => {

package/src/skill.test.ts

@@ -34,6 +34,29 @@ describe('Notifai agent skill', () => {
     }
   })
 
+  it('turns a registered question into a same-turn work-resumption commitment', () => {
+    const askGuidance = skill.slice(
+      skill.indexOf('### Register a turn-ending question'),
+      skill.indexOf('## Verify delivery and readiness'),
+    )
+
+    for (const required of [
+      'same turn',
+      'each offered answer',
+      'unexpected typed answer',
+      'work you will resume',
+      'never as approval',
+      'permission prompt',
+      'interactive picker',
+      'question identity',
+      'question text',
+      "user's answer",
+    ]) {
+      expect(askGuidance).toContain(required)
+    }
+    expect(askGuidance).toMatch(/without asking the user to\s+confirm again/)
+  })
+
   it('tells the agent where to look when something did not happen', () => {
     // The log's whole value is diagnostic, so the skill has to name the case
     // that produces it — a question that was registered and never travelled.

package/src/ui/config-view.test.ts

@@ -45,7 +45,7 @@ describe('renderConfigList', () => {
       if (configInfo(key).advanced === true) continue
       expect(text, key).toContain(key)
     }
-    expect(text).toContain('Questions & presence')
+    expect(text).toContain('Questions')
     expect(text).toContain('notifai config explain')
   })
 
@@ -69,13 +69,13 @@ describe('renderConfigList', () => {
 
 describe('renderConfigExplain', () => {
   it('answers what it is, what it is now, and what it accepts', () => {
-    const text = renderConfigExplain('require_idle', config).join('\n')
-    expect(text).toContain('require_idle')
-    expect(text).toContain('Only when I have stepped away')
+    const text = renderConfigExplain('ask_notifications', config).join('\n')
+    expect(text).toContain('ask_notifications')
+    expect(text).toContain('Send questions to my devices')
     expect(text).toContain('Accepts')
     expect(text).toContain('true or false')
     // The copyable next step; the old output stopped at the value.
-    expect(text).toContain('notifai config set require_idle')
+    expect(text).toContain('notifai config set ask_notifications')
   })
 
   it('lists what each choice of an enum means', () => {

package/src/idle.test.ts

@@ -1,32 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { parseIdleSeconds, readIdleSeconds } from './idle.js'
-
-describe('OS idle probe', () => {
-  it('reads HIDIdleTime as nanoseconds', () => {
-    // Verbatim shape of `ioreg -c IOHIDSystem -r -k HIDIdleTime`.
-    const output = `+-o IOHIDSystem  <class IOHIDSystem, id 0x100000abc>
-    {
-      "HIDIdleTime" = 151627250
-      "HIDPointerAcceleration" = 6144
-    }
-`
-    expect(parseIdleSeconds(output)).toBeCloseTo(0.15, 2)
-  })
-
-  it('reads a long idle period', () => {
-    expect(parseIdleSeconds('"HIDIdleTime" = 900000000000')).toBe(900)
-  })
-
-  it('returns null rather than a wrong number when the key is absent or junk', () => {
-    // null degrades to the elapsed-time signal; a bogus 0 would instead pin the
-    // user "present" forever and silently disable escalation altogether.
-    expect(parseIdleSeconds('')).toBeNull()
-    expect(parseIdleSeconds('"HIDPointerAcceleration" = 6144')).toBeNull()
-    expect(parseIdleSeconds('"HIDIdleTime" = <ptr>')).toBeNull()
-  })
-
-  it('reports no signal on platforms without one, instead of throwing', () => {
-    expect(readIdleSeconds('linux')).toBeNull()
-    expect(readIdleSeconds('win32')).toBeNull()
-  })
-})

package/src/idle.ts

@@ -1,41 +0,0 @@
-import { execFileSync } from 'node:child_process'
-
-/**
- * Seconds since the user last touched the keyboard or mouse, or null when this
- * machine cannot say.
- *
- * The hooks need to know whether the user is at their desk, and the only signal
- * they had was silence since the last prompt — which includes the agent's own
- * turn, so a user watching a long build was indistinguishable from a user who
- * had left. This is the corroborating signal.
- *
- * null is a first-class answer, not a failure: on a machine with no idle source
- * the caller keeps its previous behaviour rather than guessing. That is why
- * every error path here returns null instead of throwing.
- */
-export function readIdleSeconds(platform: NodeJS.Platform = process.platform): number | null {
-  if (platform !== 'darwin') return null
-  try {
-    // -r -k narrows the dump to the one node carrying the key (~5KB), so this
-    // stays a ~20ms call on the hot path of every Stop hook.
-    const out = execFileSync('ioreg', ['-c', 'IOHIDSystem', '-r', '-k', 'HIDIdleTime'], {
-      encoding: 'utf8',
-      timeout: 2000,
-      maxBuffer: 1_000_000,
-      stdio: ['ignore', 'pipe', 'ignore'],
-    })
-    return parseIdleSeconds(out)
-  } catch {
-    // Missing binary, sandbox denial, timeout — all mean "no signal".
-    return null
-  }
-}
-
-/** Exported for tests: HIDIdleTime is nanoseconds since the last HID event. */
-export function parseIdleSeconds(ioregOutput: string): number | null {
-  const match = /"HIDIdleTime"\s*=\s*(\d+)/.exec(ioregOutput)
-  if (match?.[1] === undefined) return null
-  const nanos = Number(match[1])
-  if (!Number.isFinite(nanos) || nanos < 0) return null
-  return nanos / 1e9
-}