@raidiant/notifai 4.0.0 → 5.0.0

package/src/interactive.ts

@@ -132,7 +132,7 @@ export function routingHookActions(input: {
   }
 
   options.push(
-    { value: 'settings', label: 'Change presence settings', hint: 'when a question may leave this terminal' },
+    { value: 'settings', label: 'Change question settings', hint: 'when a question may leave this terminal' },
     { value: 'back', label: '← Back' },
   )
   return options

package/src/logging-process-worker.test.ts

@@ -19,7 +19,10 @@ if (worker === undefined) {
       const maxBytes = Number(process.env['NOTIFAI_ROTATION_MAX_BYTES'])
       const maxFiles = Number(process.env['NOTIFAI_ROTATION_MAX_FILES'])
       writeFileSync(readyPath, 'ready')
-      const startDeadline = Date.now() + 10_000
+      // The parent's absolute deadline, not a countdown of this worker's own:
+      // the barrier fails for everyone at one instant, so a worker that started
+      // early cannot walk out on a parent still waiting for its last sibling.
+      const startDeadline = Number(process.env['NOTIFAI_ROTATION_DEADLINE'])
       while (!existsSync(startPath)) {
         if (Date.now() >= startDeadline) throw new Error('rotation parent never released the barrier')
         await new Promise((resolve) => setTimeout(resolve, 2))
@@ -33,7 +36,10 @@ if (worker === undefined) {
         logger.info('cli.end', { worker, sequence, pad: 'p'.repeat(140) })
         await new Promise((resolve) => setTimeout(resolve, 1))
       }
-      expect(logger.enabled).toBe(true)
+      // The sink switches itself off for the rest of a process the first time a
+      // write throws, so this is the whole point of the worker: every record it
+      // was given reached the shared file through the cross-process lock.
+      expect(logger.enabled, 'the shared-log sink switched itself off mid-run').toBe(true)
     })
   })
 }

package/src/logging.test.ts

@@ -35,22 +35,30 @@ function lines(env: NodeJS.ProcessEnv): LogRecord[] {
     .map((line) => JSON.parse(line) as LogRecord)
 }
 
-async function waitUntil(predicate: () => boolean, timeoutMs = 10_000): Promise<void> {
-  const deadline = Date.now() + timeoutMs
+async function waitUntil(predicate: () => boolean, deadline: number): Promise<void> {
   while (!predicate()) {
     if (Date.now() >= deadline) throw new Error('timed out waiting for rotation workers')
     await new Promise((resolve) => setTimeout(resolve, 5))
   }
 }
 
-function rotationWorker(
-  env: NodeJS.ProcessEnv,
-  worker: number,
-  records: number,
-  maxBytes: number,
-  maxFiles: number,
-  startPath: string,
-): { readyPath: string; done: Promise<void> } {
+interface RotationRun {
+  env: NodeJS.ProcessEnv
+  worker: number
+  records: number
+  maxBytes: number
+  maxFiles: number
+  startPath: string
+  /**
+   * When the rendezvous has failed, as an absolute instant every participant
+   * reads the same way. A per-side countdown would let the first worker to
+   * report ready abandon a parent that is still waiting for the last one.
+   */
+  deadline: number
+}
+
+function rotationWorker(run: RotationRun): { readyPath: string; done: Promise<void> } {
+  const { env, worker } = run
   const readyPath = path.join(env['XDG_STATE_HOME']!, `rotation-ready-${worker}`)
   const vitest = path.join(process.cwd(), 'node_modules', 'vitest', 'vitest.mjs')
   const child = spawn(
@@ -62,11 +70,12 @@ function rotationWorker(
         ...process.env,
         ...env,
         NOTIFAI_ROTATION_WORKER: String(worker),
-        NOTIFAI_ROTATION_RECORDS: String(records),
-        NOTIFAI_ROTATION_MAX_BYTES: String(maxBytes),
-        NOTIFAI_ROTATION_MAX_FILES: String(maxFiles),
+        NOTIFAI_ROTATION_RECORDS: String(run.records),
+        NOTIFAI_ROTATION_MAX_BYTES: String(run.maxBytes),
+        NOTIFAI_ROTATION_MAX_FILES: String(run.maxFiles),
         NOTIFAI_ROTATION_READY: readyPath,
-        NOTIFAI_ROTATION_START: startPath,
+        NOTIFAI_ROTATION_START: run.startPath,
+        NOTIFAI_ROTATION_DEADLINE: String(run.deadline),
       },
       stdio: ['ignore', 'pipe', 'pipe'],
     },
@@ -263,11 +272,15 @@ describe('rotation', () => {
     const maxBytes = 4_000
     const maxFiles = 100
     const startPath = path.join(env['XDG_STATE_HOME']!, 'rotation-start')
+    // Four cold Vitest processes have to reach the barrier before any of them
+    // writes, and a busy CI host schedules them far apart. The budget is shared,
+    // so it bounds the whole rendezvous rather than each side of it.
+    const deadline = Date.now() + 20_000
     const children = Array.from({ length: workers }, (_, worker) =>
-      rotationWorker(env, worker, recordsPerWorker, maxBytes, maxFiles, startPath),
+      rotationWorker({ env, worker, records: recordsPerWorker, maxBytes, maxFiles, startPath, deadline }),
     )
 
-    await waitUntil(() => children.every(({ readyPath }) => existsSync(readyPath)))
+    await waitUntil(() => children.every(({ readyPath }) => existsSync(readyPath)), deadline)
     writeFileSync(startPath, 'go')
     await Promise.all(children.map(({ done }) => done))
 
@@ -293,8 +306,10 @@ describe('rotation', () => {
     // name race may lose or duplicate one.
     expect(retainedRecords).toBe(workers * recordsPerWorker)
     expect(seen.size).toBe(workers * recordsPerWorker)
-    expect([...seen.values()].every((count) => count === 1)).toBe(true)
-  })
+    // Name the offending records: a bare boolean would report a duplication bug
+    // as "expected false to be true" and leave the next reader nothing to go on.
+    expect([...seen].filter(([, count]) => count !== 1)).toEqual([])
+  }, 90_000)
 })
 
 describe('failure isolation', () => {

package/src/logging.ts

@@ -61,6 +61,17 @@ export const LOG_SCHEMA_VERSION = 1
 export { LOG_LEVELS, type LogLevel }
 export type RecordLevel = Exclude<LogLevel, 'off'>
 
+/**
+ * The levels a record can actually carry.
+ *
+ * `off` is a setting that stops writing, never a severity anything is written
+ * at — so offering it as a retrieval filter accepted a query that could only
+ * ever match nothing, and then blamed the result on too narrow a search.
+ */
+export const RECORD_LEVELS: readonly RecordLevel[] = LOG_LEVELS.filter(
+  (level): level is RecordLevel => level !== 'off',
+)
+
 const LEVEL_RANK: Record<LogLevel, number> = { off: 0, error: 1, info: 2, debug: 3 }
 
 /**

package/src/main.ts

@@ -124,8 +124,6 @@ const program = new Command('notifai')
   // it. Without this, adding that default would silently break
   // `notifai help send` for everyone who reaches for it before `--help`.
   .helpCommand(true)
-  // Where the implicit help command lands; every other command names its own.
-  .commandsGroup(GROUP.help)
   .hook('preAction', (_program, actionCommand) => {
     logger.bind({ cmd: commandPath(actionCommand) })
     // SessionEnd uses the hook policy shared with commands.ts: local cleanup
@@ -156,7 +154,40 @@ const program = new Command('notifai')
  * interactive tree cost nothing to the paths that never draw them — `send`,
  * `ask`, and the hook that runs in front of every prompt the user types.
  */
-program.action(async () => {
+/**
+ * Commander exits 1 for every usage error it detects itself, which contradicts
+ * the exit vocabulary this CLI documents and every hand-written usage error it
+ * returns. A caller branching on exit codes should not have to know which layer
+ * rejected it. Help and version stay successful.
+ */
+program.exitOverride((err) => {
+  process.exit(err.exitCode === 0 ? 0 : 2)
+})
+
+/**
+ * An unrecognised subcommand reaches the root as an excess argument, and
+ * "expected 0 arguments but got 1" tells a caller nothing about what it typed
+ * or what exists. Naming it — with the nearest real command when there is one —
+ * turns a dead end into one more try.
+ */
+program.usage('[options] [command]')
+program.argument('[command]').action(async (command?: string) => {
+  if (command !== undefined) {
+    const names = program.commands.map((cmd) => cmd.name())
+    const near = names.filter(
+      (name) =>
+        name.startsWith(command.slice(0, 2)) ||
+        command.startsWith(name.slice(0, 2)) ||
+        name.includes(command) ||
+        command.includes(name),
+    )
+    deps.io.err(
+      `Unknown command "${command}".` +
+        (near.length > 0 ? ` Did you mean: ${near.slice(0, 3).join(', ')}?` : '') +
+        ' Run notifai --help for the full list.',
+    )
+    process.exit(2)
+  }
   if (deps.io.interactive !== true) {
     program.outputHelp()
     return
@@ -269,19 +300,17 @@ const send = program
   .option(
     '--image <path|url|media_id>',
     'upload or attach an image in collection order (repeatable, maximum 8)',
-    (v: string, all: string[]) => [...all, v],
-    [],
+    (v: string, all: string[] = []) => [...all, v],
   )
   .option(
     '--image-alt <text>',
     'alt text paired with --image occurrences by position (repeatable)',
-    (v: string, all: string[]) => [...all, v],
-    [],
+    (v: string, all: string[] = []) => [...all, v],
   )
   .optionsGroup(SEND_GROUP.routing)
-  .option('--kind <kind>', 'what this is: update (default) | done | failed | blocked | question (requires --reply)')
+  .option('--kind <kind>', 'what this is (required): update | done | failed | blocked — question is set by --reply')
   .option('--project <id>', 'project identifier override (otherwise configured or inferred)')
-  .option('--device <id>', 'target a device id (repeatable)', (v: string, all: string[]) => [...all, v], [])
+  .option('--device <id>', 'target a device id (repeatable)', (v: string, all: string[] = []) => [...all, v])
   .option('--all', 'target all routable devices (overrides configured devices)')
   .option('--session-id <id>', 'opaque exact-session override (env: NOTIFAI_SESSION_ID)')
   .option('--session-label <text>', 'human session label override (env: NOTIFAI_SESSION_LABEL)')
@@ -294,11 +323,15 @@ const send = program
   .optionsGroup(SEND_GROUP.reply)
   .option('--reply', 'enable the inline reply action and block for the answer')
   .option('--reply-timeout <seconds>', 'how long to wait for a reply (default: 900)', (v: string) => Number(v))
-  .option('--reply-window <seconds>', 'how long the server accepts a reply (default: 3600)', (v: string) => Number(v))
+  .option(
+    '--reply-window <seconds>',
+    'how long an answer is still accepted, 60-259200 (default: reply_window_seconds, a day)',
+    (v: string) => Number(v),
+  )
   .option(
     '--reply-choice <label>',
     'with --reply, ask a closed question; repeat the flag once per answer (2-6)',
-    (v: string, all: string[]) => [...all, v], [],
+    (v: string, all: string[] = []) => [...all, v],
   )
   .option('--reply-multi', 'with --reply-choice, several answers may be selected')
   // Kept registered, and always a usage error with --reply, so the caller gets
@@ -309,7 +342,7 @@ const send = program
   .option('--level <level>', 'override saved interruption level: passive | active | time_sensitive')
   .option('--wait <seconds>', 'how long to wait for provider outcomes', (v: string) => Number(v))
   .option('--no-wait', 'return immediately after acceptance')
-  .option('--data <key=value>', 'custom data (repeatable)', (v: string, all: string[]) => [...all, v], [])
+  .option('--data <key=value>', 'custom data (repeatable)', (v: string, all: string[] = []) => [...all, v])
   .option('--idempotency-key <key>', 'safe-retry key (default: random)')
   .option('--base-url <url>', 'developer override for the service origin (also NOTIFAI_BASE_URL)')
   .option('--json', 'print the full submission receipt as JSON')
@@ -346,8 +379,8 @@ const send = program
 
 send.addHelpText(
   'after',
-  `\nKind describes status in the Companion Apps; it never chooses banner sound or interruption level.\nWithout --sound/--level or saved preferences, those fields are omitted for the destination to handle.\n`,
-)
+  `\nKind is required, and it selects the sound the notification arrives with: done rings the completion chime, failed the most insistent tone, blocked and question a distinct attention tone, update the standard one.\nAn explicit --sound or --level, and the user's saved preference, both outrank that default.\n`,
+ )
 
 program
   .command('replies [request_id]')
@@ -369,9 +402,9 @@ program
   .description(
     'Record the required Agent Acknowledgement for a replied-to notification request; never prompts',
   )
-  .requiredOption('--text <text>', 'concrete work you will do because of the reply')
+  .option('--text <text>', 'concrete work you will do because of the reply')
   .option('--json', 'machine-readable output')
-  .action(async (requestId: string, opts: { text: string; json?: boolean }) => {
+  .action(async (requestId: string, opts: { text?: string; json?: boolean }) => {
     process.exit(await acknowledgeCommand(deps, requestId, opts))
   })
 
@@ -389,27 +422,26 @@ program
   .command('ask [question]')
   .helpGroup(GROUP.agent)
   .summary('Register a question, then end the turn')
-  .description('Register a question for the turn-end hook to route under your presence settings')
+  .description('Register a question for the turn-end hook to route to your devices, subject to your question-routing settings')
   .option(
     '--choice <label>',
     'answers to offer instead of free text; repeat the flag once per answer (2-6)',
-    (v: string, all: string[]) => [...all, v], [],
+    (v: string, all: string[] = []) => [...all, v],
   )
   .option('--multi', 'with --choice, several answers may be selected')
+  .option('--json', 'machine-readable output')
   .option('--body <markdown>', 'optional Markdown context appended after the question block')
   .option('--body-file <path>', 'read optional Markdown context from a file (use - for stdin)')
   .option('--form <path>', 'ask several questions as one form; JSON file (use - for stdin)')
   .option(
     '--image <path|url|media_id>',
     'upload or attach an image in collection order (repeatable, maximum 8)',
-    (v: string, all: string[]) => [...all, v],
-    [],
+    (v: string, all: string[] = []) => [...all, v],
   )
   .option(
     '--image-alt <text>',
     'alt text paired with --image occurrences by position (repeatable)',
-    (v: string, all: string[]) => [...all, v],
-    [],
+    (v: string, all: string[] = []) => [...all, v],
   )
   .option('--project <id>', 'project identifier override (otherwise configured or inferred)')
   .option('--session-id <id>', 'opaque exact-session override (env: NOTIFAI_SESSION_ID)')
@@ -417,6 +449,7 @@ program
   .action(async (question: string | undefined, opts: {
     choice?: string[]
     multi?: boolean
+    json?: boolean
     body?: string
     bodyFile?: string
     form?: string
@@ -459,6 +492,7 @@ program
       ...(opts.project !== undefined ? { project: opts.project } : {}),
       ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
       ...(opts.sessionLabel !== undefined ? { sessionLabel: opts.sessionLabel } : {}),
+      ...(opts.json === true ? { json: true } : {}),
     }
     process.exit(await askCommand(deps, question, flags))
   })
@@ -528,7 +562,7 @@ program
   .option('--all', 'lift the default limit, up to a hard cap')
   .option('--since <when>', 'only records newer than this: 10m, 2h, 1d, or an ISO 8601 instant')
   .option('--level <level>', 'minimum severity: error | info | debug (error shows only failures)')
-  .option('--event <name>', 'only this event; repeatable', (v: string, all: string[]) => [...all, v], [])
+  .option('--event <name>', 'only this event; repeatable', (v: string, all: string[] = []) => [...all, v])
   .option('--run <id>', 'everything one command invocation did')
   .option('--request <id>', 'everything about one notification request')
   .option('--session <id>', 'only this harness session')

package/src/opencode-plugin.ts

@@ -31,7 +31,7 @@ export const OPENCODE_PLUGIN_MARKER = '// notifai managed opencode plugin'
 export const OPENCODE_PLUGIN_FILENAME = 'notifai.js'
 
 /** Bump when an installed generated file must be rewritten to remain functional. */
-const OPENCODE_ADAPTER_VERSION = 5
+const OPENCODE_ADAPTER_VERSION = 6
 
 export function opencodePluginDir(
   global: boolean,
@@ -75,150 +75,32 @@ export interface OpencodePluginOptions {
  * hand that to the CLI on stdin. It deliberately fails open: an adapter error
  * never changes OpenCode's own behavior.
  */
-export function opencodePluginSource(options: OpencodePluginOptions): string {
-  if (hookHostPlatform(options.platform) === 'win32') {
-    return win32OpencodePluginSource(options)
-  }
-  return posixOpencodePluginSource(options)
-}
-
-function posixOpencodePluginSource(options: OpencodePluginOptions): string {
-  const { adapterPath, timeoutSeconds } = options
-  return `${OPENCODE_PLUGIN_MARKER}
-// Generated by \`notifai hooks install --harness opencode\`. Edits are lost on
-// the next install; change the CLI instead, which is where the logic lives.
-import { spawn } from "node:child_process"
-
-const ADAPTER = ${JSON.stringify(adapterPath)}
-const TIMEOUT_MS = ${timeoutSeconds * 1000}
-const ADAPTER_VERSION = ${OPENCODE_ADAPTER_VERSION}
-
 /**
- * Runs \`notifai hook <event>\`, feeding it the same JSON envelope the other
- * harnesses send. Resolves to stdout, or null if anything at all went wrong.
+ * The plugin body, which is the same on every platform except for how it
+ * reaches the adapter.
+ *
+ * It was two near-identical copies — about a hundred and twenty lines each,
+ * differing only in the spawn call — so every fix to the plugin had to be made
+ * twice or silently apply to one platform.
  */
-function runHook(event, envelope) {
-  return new Promise((resolve) => {
-    let child
-    try {
-      child = spawn(ADAPTER, ["hook", event, "--owner", "notifai", "--harness", "opencode"], {
-        env: process.env,
-        shell: false,
-        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
-    })
-    // Hook stderr is diagnostics, not plugin output; discard it here.
-    child.stderr?.resume()
-    child.on("error", () => finish(null))
-    child.on("close", () => finish(stdout))
-
-    try {
-      child.stdin?.end(JSON.stringify(envelope))
-    } catch {
-      finish(null)
-    }
-  })
-}
-
-function additionalContext(stdout) {
-  if (typeof stdout !== "string" || stdout.trim() === "") return null
-  try {
-    const parsed = JSON.parse(stdout)
-    const context = parsed?.hookSpecificOutput?.additionalContext
-    return typeof context === "string" && context.length > 0 ? context : null
-  } catch {
-    return null
-  }
-}
-
-export const NotifAIPlugin = async ({ directory }) => {
-  const cwd = typeof directory === "string" && directory.length > 0 ? directory : process.cwd()
-
-  return {
-    /** Exact active-harness identity for shell commands such as \`notifai ask\`. */
-    "shell.env": async (input, output) => {
-      output.env.NOTIFAI_ACTIVE_HARNESS = "opencode"
-      const sessionID = input?.sessionID
-      if (typeof sessionID === "string" && sessionID.length > 0) {
-        output.env.NOTIFAI_ACTIVE_SESSION_ID = sessionID
-      }
-    },
-
-    /**
-     * Presence. The user typing is the signal every harness shares, and it is
-     * also what publishes the project -> session pointer \`notifai ask\` reads.
-     */
-    "chat.message": async (input, output) => {
-      const stdout = await runHook("user-prompt-submit", {
-        session_id: input?.sessionID ?? input?.info?.sessionID,
-        cwd,
-        hook_event_name: "UserPromptSubmit",
-      })
-      const context = additionalContext(stdout)
-      if (context !== null) {
-        output.parts.push({
-          id: "prt_notifai_" + Date.now(),
-          sessionID: input.sessionID,
-          messageID: output.message.id,
-          type: "text",
-          text: context,
-          synthetic: true,
-        })
-      }
-    },
-
-    /** Session lifecycle events are delivered through OpenCode's event bus. */
-    event: async ({ event }) => {
-      if (event?.type === "session.idle") {
-        await runHook("stop", {
-          session_id: event?.properties?.sessionID,
-          cwd,
-          hook_event_name: "Stop",
-        })
-      } else if (event?.type === "session.deleted") {
-        await runHook("session-end", {
-          session_id: event?.properties?.info?.id,
-          cwd,
-          hook_event_name: "SessionEnd",
-        })
-      }
-    },
-  }
-}
-`
-}
-
-function win32OpencodePluginSource(options: OpencodePluginOptions): string {
+export function opencodePluginSource(options: OpencodePluginOptions): string {
   const { adapterPath, timeoutSeconds } = options
-  const nodePath = options.nodePath ?? process.execPath
+  // Windows cannot execute the adapter script directly, so it goes through the
+  // registered Node executable and the console window is suppressed.
+  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", "opencode"]'
+    : 'ADAPTER, ["hook", event, "--owner", "notifai", "--harness", "opencode"]'
+  const windowsHide = win32 ? '\n        windowsHide: true,' : ''
   return `${OPENCODE_PLUGIN_MARKER}
 // Generated by \`notifai hooks install --harness opencode\`. Edits are lost on
 // the next install; change the CLI instead, which is where the logic lives.
 import { spawn } from "node:child_process"
 
-const NODE = ${JSON.stringify(nodePath)}
-const ADAPTER = ${JSON.stringify(adapterPath)}
+${nodeConstant}const ADAPTER = ${JSON.stringify(adapterPath)}
 const TIMEOUT_MS = ${timeoutSeconds * 1000}
 const ADAPTER_VERSION = ${OPENCODE_ADAPTER_VERSION}
 
@@ -230,10 +112,9 @@ function runHook(event, envelope) {
   return new Promise((resolve) => {
     let child
     try {
-      child = spawn(NODE, [ADAPTER, "hook", event, "--owner", "notifai", "--harness", "opencode"], {
+      child = spawn(${spawnArguments}, {
         env: process.env,
-        shell: false,
-        windowsHide: true,
+        shell: false,${windowsHide}
         stdio: ["pipe", "pipe", "pipe"],
       })
     } catch {
@@ -271,17 +152,6 @@ function runHook(event, envelope) {
   })
 }
 
-function additionalContext(stdout) {
-  if (typeof stdout !== "string" || stdout.trim() === "") return null
-  try {
-    const parsed = JSON.parse(stdout)
-    const context = parsed?.hookSpecificOutput?.additionalContext
-    return typeof context === "string" && context.length > 0 ? context : null
-  } catch {
-    return null
-  }
-}
-
 export const NotifAIPlugin = async ({ directory }) => {
   const cwd = typeof directory === "string" && directory.length > 0 ? directory : process.cwd()
 
@@ -299,23 +169,13 @@ export const NotifAIPlugin = async ({ directory }) => {
      * Presence. The user typing is the signal every harness shares, and it is
      * also what publishes the project -> session pointer \`notifai ask\` reads.
      */
-    "chat.message": async (input, output) => {
-      const stdout = await runHook("user-prompt-submit", {
+    /** Publishes the session pointer; the CLI returns no content to inject. */
+    "chat.message": async (input) => {
+      await runHook("user-prompt-submit", {
         session_id: input?.sessionID ?? input?.info?.sessionID,
         cwd,
         hook_event_name: "UserPromptSubmit",
       })
-      const context = additionalContext(stdout)
-      if (context !== null) {
-        output.parts.push({
-          id: "prt_notifai_" + Date.now(),
-          sessionID: input.sessionID,
-          messageID: output.message.id,
-          type: "text",
-          text: context,
-          synthetic: true,
-        })
-      }
     },
 
     /** Session lifecycle events are delivered through OpenCode's event bus. */

package/src/question-caps.test.ts

@@ -0,0 +1,49 @@
+import { mkdtempSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { MAX_LIVE_QUESTIONS, MAX_PENDING_QUESTIONS, registerQuestion } from './hooks.js'
+
+/**
+ * `registerQuestion` decides how many questions one session may hold, and these
+ * exercise it directly against a bare state directory — no harness, no server,
+ * no clock. They live apart from `hooks.test.ts` because nothing here needs
+ * what that file spends its setup on.
+ */
+const state = (): NodeJS.ProcessEnv => {
+  const dir = mkdtempSync(path.join(os.tmpdir(), 'notifai-caps-'))
+  return { HOME: dir, XDG_STATE_HOME: path.join(dir, 'state') } as NodeJS.ProcessEnv
+}
+
+describe('how many questions one session may hold', () => {
+  it('stops an agent registering a fifth question nobody has asked yet', () => {
+    const env = state()
+    for (let i = 0; i < MAX_PENDING_QUESTIONS; i += 1) {
+      registerQuestion('loop', env, { question: `Q${i}?` })
+    }
+    expect(() => registerQuestion('loop', env, { question: 'One more?' })).toThrow(
+      /already waiting to be asked/,
+    )
+  })
+
+  it('does not count a question the user simply has not answered yet', () => {
+    // An answer stays accepted for a day. Counting questions already on the
+    // user's devices against the loop guard would let a patient user stop the
+    // agent from asking anything at all.
+    const env = state()
+    for (let i = 0; i < MAX_PENDING_QUESTIONS; i += 1) {
+      registerQuestion('live', env, { question: `Asked ${i}?`, request_id: `req_${i}` })
+    }
+    expect(() => registerQuestion('live', env, { question: 'A new one?' })).not.toThrow()
+  })
+
+  it('still bounds what one session can put on the lock screen', () => {
+    const env = state()
+    for (let i = 0; i < MAX_LIVE_QUESTIONS; i += 1) {
+      registerQuestion('flood', env, { question: `Asked ${i}?`, request_id: `req_${i}` })
+    }
+    expect(() => registerQuestion('flood', env, { question: 'One too many?' })).toThrow(
+      /already open/,
+    )
+  })
+})