@raidiant/notifai 0.1.0 → 0.1.2

package/src/hooks.test.ts

@@ -523,6 +523,37 @@ describe('superseding a live question', () => {
     expect(readSessionState('sup2', h.env).retiring).toEqual([])
   })
 
+  it('keeps the original delivery targets when routing changes before retirement', async () => {
+    const h = harness([])
+    writeSessionState('sup-targets', h.env, { last_prompt_at: AWAY })
+    registerQuestion('sup-targets', h.env, { question: 'Ship it?' })
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'sup-targets' }))
+
+    const live = readSessionState('sup-targets', h.env).pending
+    expect(live).toMatchObject({
+      request_id: 'req_hook_1',
+      device_ids: ['dev_iphone', 'dev_mac'],
+    })
+
+    // The user changes their default routing before the agent supersedes the
+    // question. Retirement belongs to the Deliveries that actually carried the
+    // first question, not to whichever Device Installation is selected now.
+    const configDir = path.join(h.env['XDG_CONFIG_HOME'] as string, 'notifai')
+    mkdirSync(configDir, { recursive: true })
+    writeFileSync(path.join(configDir, 'config.toml'), 'devices = ["dev_iphone"]\n')
+    registerQuestion('sup-targets', h.env, { question: 'Deploy it?' })
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'sup-targets' }))
+
+    const retirement = h.recorder.submitted.find(
+      (submission) => submission.draft.event === 'question_retired',
+    )
+    expect(retirement?.draft.lifecycle?.retires_request_id).toBe('req_hook_1')
+    expect(retirement?.draft.targets).toEqual({
+      mode: 'selected',
+      device_ids: ['dev_iphone', 'dev_mac'],
+    })
+  })
+
   it('sweeps a queued retirement even on a turn continuing from an answer', async () => {
     // stop_hook_active short-circuits the escalation path, and a superseding
     // turn is very often exactly this turn.
@@ -641,7 +672,13 @@ describe('a question that outlives its session', () => {
     const h = harness([])
     orphanRetirements(
       h.env,
-      [{ request_id: 'req_old', collapse_key: 'ck_old', question: 'Old?', state: 'expired' }],
+      [{
+        request_id: 'req_old',
+        collapse_key: 'ck_old',
+        device_ids: ['dev_iphone'],
+        question: 'Old?',
+        state: 'expired',
+      }],
       undefined,
       NOW - 25 * 3600 * 1000,
     )
@@ -735,6 +772,23 @@ describe('ask registration', () => {
     expect(askCommand(h.deps, 'Ship it?', {})).toBe(EXIT.ok)
     expect(readSessionState('solo-session', h.env).pending?.question).toBe('Ship it?')
   })
+
+  it('fails explicitly instead of rerouting incomplete live state', () => {
+    const h = harness()
+    writeSessionState('incomplete', h.env, {
+      pending: {
+        question: 'Original?',
+        request_id: 'req_original',
+        collapse_key: 'collapse-original',
+      },
+    })
+
+    expect(askCommand(h.deps, 'Replacement?', { session: 'incomplete' })).toBe(EXIT.failed)
+    expect(h.io.errLines.join('\n')).toContain(
+      'refusing to retire it without request, collapse, and device identifiers',
+    )
+    expect(readSessionState('incomplete', h.env).pending?.question).toBe('Original?')
+  })
 })
 
 describe('user-prompt-submit hook', () => {
@@ -744,6 +798,59 @@ describe('user-prompt-submit hook', () => {
     expect(readSessionState('s10', h.env).last_prompt_at).toBe(NOW)
   })
 
+  it('preserves a delivered question through ask replacement and prompt transition', async () => {
+    const h = harness([], 900)
+    await hookRunCommand(
+      h.deps,
+      'user-prompt-submit',
+      stdin({ session_id: 'transition', cwd: h.deps.cwd }),
+    )
+    expect(askCommand(h.deps, 'Ship it?', { choice: ['Yes', 'No'] })).toBe(EXIT.ok)
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'transition', cwd: h.deps.cwd }))
+
+    const live = readSessionState('transition', h.env).pending
+    expect(live).toMatchObject({
+      question: 'Ship it?',
+      request_id: 'req_hook_1',
+      device_ids: ['dev_iphone', 'dev_mac'],
+    })
+    expect(live?.collapse_key).toMatch(/^notifai-hook-/)
+
+    // A second plain `ask` resolves through the project pointer and supersedes
+    // the live question. The next prompt then resets presence before another
+    // Stop can run — the transition that used to erase the retirement debt.
+    expect(askCommand(h.deps, 'Deploy it?', { choice: ['Staging', 'Production'] })).toBe(EXIT.ok)
+    expect(readSessionState('transition', h.env).retiring).toEqual([
+      {
+        request_id: live?.request_id,
+        collapse_key: live?.collapse_key,
+        device_ids: ['dev_iphone', 'dev_mac'],
+        question: 'Ship it?',
+        state: 'superseded',
+      },
+    ])
+
+    await hookRunCommand(
+      h.deps,
+      'user-prompt-submit',
+      stdin({ session_id: 'transition', cwd: h.deps.cwd }),
+    )
+
+    const retirement = h.recorder.submitted.find(
+      (submission) => submission.draft.event === 'question_retired',
+    )?.draft
+    expect(retirement?.delivery.collapse_key).toBe(live?.collapse_key)
+    expect(retirement?.lifecycle).toEqual({
+      tier: 'done',
+      state: 'superseded',
+      retires_request_id: live?.request_id,
+    })
+    expect(retirement?.targets).toEqual({
+      mode: 'selected',
+      device_ids: ['dev_iphone', 'dev_mac'],
+    })
+  })
+
   it('retires a question a real timed-out Stop left live on the devices', async () => {
     // Drives the actual flow rather than hand-writing state: the previous
     // version of this test fabricated a shape production never wrote, so it
@@ -832,6 +939,24 @@ describe('session-end hook', () => {
     expect(readSessionState('s12', h.env)).toEqual({})
     expect(h.recorder.closed).toEqual([])
   })
+
+  it('preserves incomplete live state and reports why it cannot retire it', async () => {
+    const h = harness()
+    writeSessionState('s-incomplete', h.env, {
+      pending: {
+        question: 'Still live?',
+        request_id: 'req_incomplete',
+        collapse_key: 'collapse-incomplete',
+      },
+    })
+
+    await hookRunCommand(h.deps, 'session-end', stdin({ session_id: 's-incomplete' }))
+
+    expect(readSessionState('s-incomplete', h.env).pending?.request_id).toBe('req_incomplete')
+    expect(h.io.errLines.join('\n')).toContain(
+      'refusing to retire it without request, collapse, and device identifiers',
+    )
+  })
 })
 
 describe('malformed input', () => {

package/src/hooks.ts

@@ -67,6 +67,8 @@ export interface SessionState {
 export interface RetiringQuestion {
   request_id: string
   collapse_key: string
+  /** The Device Installations that actually received the question. */
+  device_ids: string[]
   /** Shown if the companion has no history entry to correlate against. */
   question: string
   state: LifecycleEndState
@@ -118,6 +120,8 @@ export interface PendingQuestion {
   /** Set once the question has actually been pushed, so it can be retired. */
   request_id?: string
   collapse_key?: string
+  /** Exact fanout of the live question; routing config may change afterwards. */
+  device_ids?: string[]
 }
 
 /** How often the grace window rechecks whether the user has come back. */
@@ -649,24 +653,56 @@ export function parkForRetirement(
   pending: PendingQuestion,
   state: LifecycleEndState,
 ): void {
-  if (pending.request_id === undefined || pending.collapse_key === undefined) return
+  const retirement = retiringQuestion(pending, state)
+  if (retirement === null) return
   const current = readSessionState(sessionId, env)
   const already = current.retiring ?? []
-  if (already.some((entry) => entry.request_id === pending.request_id)) return
+  if (already.some((entry) => entry.request_id === retirement.request_id)) return
   writeSessionState(sessionId, env, {
     ...current,
-    retiring: [
-      ...already,
-      {
-        request_id: pending.request_id,
-        collapse_key: pending.collapse_key,
-        question: pending.question,
-        state,
-      },
-    ],
+    retiring: [...already, retirement],
   })
 }
 
+/**
+ * Convert live question state into a complete retirement instruction.
+ *
+ * A request/collapse pair without the original Delivery targets is not safe to
+ * send: re-resolving today's routing can miss a device that still shows the
+ * question or retire a device that never received it. Fail explicitly and keep
+ * the pending record instead of silently broadening or narrowing the fanout.
+ */
+function retiringQuestion(
+  pending: PendingQuestion,
+  state: LifecycleEndState,
+): RetiringQuestion | null {
+  const hasRequest = pending.request_id !== undefined
+  const hasCollapse = pending.collapse_key !== undefined
+  const hasDevices = pending.device_ids !== undefined && pending.device_ids.length > 0
+  if (!hasRequest && !hasCollapse && !hasDevices) return null
+  if (!hasRequest || !hasCollapse || !hasDevices) {
+    throw new Error(
+      'live question state is incomplete; refusing to retire it without request, collapse, and device identifiers',
+    )
+  }
+  return {
+    request_id: pending.request_id!,
+    collapse_key: pending.collapse_key!,
+    device_ids: [...pending.device_ids!],
+    question: pending.question,
+    state,
+  }
+}
+
+function retirementDeviceIds(entry: RetiringQuestion): string[] {
+  if (!Array.isArray(entry.device_ids) || entry.device_ids.length === 0) {
+    throw new Error(
+      `retirement for ${entry.request_id} is missing its device identifiers; refusing to re-resolve routing`,
+    )
+  }
+  return entry.device_ids
+}
+
 /**
  * Send every parked retirement, and forget the ones that landed. A failure
  * leaves the entry in place for the next hook rather than losing it, which is
@@ -692,7 +728,7 @@ export async function drainRetirements(
       entry.question,
       entry.state,
       entry.request_id,
-      undefined,
+      retirementDeviceIds(entry),
       session,
     )
     if (sent) retired.push(entry.request_id)
@@ -777,7 +813,7 @@ export async function drainOrphanRetirements(
       entry.question,
       entry.state,
       entry.request_id,
-      undefined,
+      retirementDeviceIds(entry),
       entry.session,
     )
     if (sent) done.push(entry.request_id)
@@ -811,18 +847,19 @@ export async function handleUserPromptSubmit(
 
   const state = readSessionState(sessionId, ctx.env)
   const pending = state.pending
-  // Deliberately drops `pending` — the user is here, so the question is the
-  // terminal's now. `retiring` is carried across: it is the only record of
-  // notifications still live on the devices, and this reset used to erase it.
+  // Park before dropping `pending`. If the process dies between these writes,
+  // the next hook sees both copies and dedupes them; the old order could die in
+  // the gap after erasing the only request/collapse/device identifiers.
+  if (pending !== undefined) parkForRetirement(sessionId, ctx.env, pending, 'answered_elsewhere')
+  const parked = readSessionState(sessionId, ctx.env)
   writeSessionState(sessionId, ctx.env, {
     last_prompt_at: ctx.now(),
-    ...(state.retiring !== undefined ? { retiring: state.retiring } : {}),
+    ...(parked.retiring !== undefined ? { retiring: parked.retiring } : {}),
   })
   // The bridge that lets a plain `notifai ask` find its own session: an agent
   // shell command gets no hook payload and no harness exports the id.
   if (envelope.cwd !== undefined) writeProjectSession(envelope.cwd, ctx.env, sessionId, ctx.now())
 
-  if (pending !== undefined) parkForRetirement(sessionId, ctx.env, pending, 'answered_elsewhere')
   const retired = await drainRetirements(ctx, sessionId, ctx.env, sessionLabel(ctx, envelope))
   const orphaned = await drainOrphanRetirements(ctx, ctx.env, ctx.now())
   const swept = [...retired, ...orphaned]
@@ -938,7 +975,12 @@ async function escalate(
       // snapshot in `state` predates it.
       writeSessionState(sessionId, ctx.env, {
         ...readSessionState(sessionId, ctx.env),
-        pending: { ...pending, request_id: live.requestId, collapse_key: live.collapseKey },
+        pending: {
+          ...pending,
+          request_id: live.requestId,
+          collapse_key: live.collapseKey,
+          device_ids: live.devices,
+        },
       })
     },
   })
@@ -962,7 +1004,12 @@ async function escalate(
     // set is also what stops the next Stop pushing the same question again.
     writeSessionState(sessionId, ctx.env, {
       ...carried,
-      pending: { ...pending, request_id: asked.requestId, collapse_key: asked.collapseKey },
+      pending: {
+        ...pending,
+        request_id: asked.requestId,
+        collapse_key: asked.collapseKey,
+        device_ids: asked.devices,
+      },
     })
     notes.push(
       asked.degraded
@@ -1023,13 +1070,16 @@ export function handleSessionEnd(
   const state = readSessionState(sessionId, env)
   const orphans: RetiringQuestion[] = [...(state.retiring ?? [])]
   const pending = state.pending
-  if (pending?.request_id !== undefined && pending.collapse_key !== undefined) {
-    orphans.push({
-      request_id: pending.request_id,
-      collapse_key: pending.collapse_key,
-      question: pending.question,
-      state: 'expired',
-    })
+  if (pending !== undefined) {
+    try {
+      const orphan = retiringQuestion(pending, 'expired')
+      if (orphan !== null) orphans.push(orphan)
+    } catch (err) {
+      notes.push(err instanceof Error ? err.message : String(err))
+      // Preserve the only identifiers instead of turning an explicit corrupt
+      // state into an unretirable question during SessionEnd cleanup.
+      return { notes }
+    }
   }
   if (orphans.length > 0) {
     const label = env['NOTIFAI_SESSION']

package/src/install-hooks.test.ts

@@ -22,6 +22,7 @@ import {
 import {
   HARNESSES,
   applyPlan,
+  detectHarness,
   buildHookConfig,
   codexLayerDir,
   codexProjectRoot,
@@ -498,3 +499,79 @@ describe('the OpenCode adapter', () => {
     expect(opencodePluginTarget(`${OPENCODE_PLUGIN_MARKER}\nconst EXEC = whatever\n`)).toBeNull()
   })
 })
+
+describe('detectHarness', () => {
+  function project(...entries: string[]): string {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'notifai-detect-'))
+    for (const entry of entries) {
+      if (entry.endsWith('.md')) writeFileSync(path.join(dir, entry), '# project\n')
+      else mkdirSync(path.join(dir, entry), { recursive: true })
+    }
+    return dir
+  }
+
+  it('detects Claude Code from a project .claude directory', () => {
+    expect(detectHarness(project('.claude'))).toBe('claude-code')
+  })
+
+  it('detects Claude Code from CLAUDE.md alone', () => {
+    // A repository worked in daily through Claude Code may never accumulate a
+    // .claude/ directory; its project file is the only marker there is.
+    expect(detectHarness(project('CLAUDE.md'))).toBe('claude-code')
+  })
+
+  it('detects Claude Code from .claude and CLAUDE.md together without double-counting', () => {
+    expect(detectHarness(project('.claude', 'CLAUDE.md'))).toBe('claude-code')
+  })
+
+  it('does not infer a harness from AGENTS.md', () => {
+    // AGENTS.md began as a Codex convention and is now read by most agent
+    // tooling, Claude Code included. Naming a harness from it would be a guess
+    // wearing detection's clothes. With no other project evidence this falls
+    // through to machine evidence, which on a multi-tool machine is ambiguous.
+    const dir = project('AGENTS.md')
+    const answer = detectHarness(dir)
+    expect(answer).not.toBe('codex')
+    expect(HARNESSES.includes(answer as never) || answer === null).toBe(true)
+  })
+
+  it('pairs AGENTS.md with CLAUDE.md as Claude Code, not Codex', () => {
+    // The shape this very repository has, and four of the five projects the
+    // release was verified in.
+    expect(detectHarness(project('CLAUDE.md', 'AGENTS.md'))).toBe('claude-code')
+  })
+
+  it('detects each harness from its own project directory', () => {
+    expect(detectHarness(project('.codex'))).toBe('codex')
+    expect(detectHarness(project('.cursor'))).toBe('cursor')
+    expect(detectHarness(project('.opencode'))).toBe('opencode')
+  })
+
+  it('returns null when the project itself names two harnesses', () => {
+    // Genuine ambiguity, and the caller must ask rather than pick. Not the
+    // same as having no evidence.
+    expect(detectHarness(project('.claude', '.codex'))).toBeNull()
+  })
+
+  it('prefers project evidence over anything installed on the machine', () => {
+    // The regression. Machine-global markers used to be OR-ed in per harness,
+    // so a developer with several agent tools installed got a candidate for
+    // every one of them, the "exactly one" test never passed, and detection
+    // returned null in every repository on that machine — including ones whose
+    // own contents named a single harness unambiguously.
+    //
+    // This asserts the ordering rather than the machine state, so it holds on
+    // a CI box with a bare home directory and on a developer laptop carrying
+    // all four.
+    expect(detectHarness(project('.cursor'))).toBe('cursor')
+    expect(detectHarness(project('CLAUDE.md'))).toBe('claude-code')
+  })
+
+  it('falls back to machine evidence only when the project offers none', () => {
+    const empty = mkdtempSync(path.join(os.tmpdir(), 'notifai-detect-empty-'))
+    // 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)
+  })
+})

package/src/install-hooks.ts

@@ -342,24 +342,63 @@ export function configHome(env: NodeJS.ProcessEnv, variable: string, fallback: s
 }
 
 /** Best-effort detection so `hooks install` usually needs no flags. */
-export function detectHarness(cwd: string): Harness | null {
+/**
+ * Harnesses this *project* shows evidence of, in the working directory only.
+ *
+ * `CLAUDE.md` counts because it is Claude Code's own project file and is
+ * frequently the only marker: a repository can be worked in daily through
+ * Claude Code and never accumulate a `.claude/` directory.
+ *
+ * `AGENTS.md` deliberately counts for nothing. It began as a Codex
+ * convention and is now read by most agent tooling — including Claude Code,
+ * and including this repository, where the two filenames are the same
+ * document. Treating it as evidence of any one harness would be a guess
+ * dressed up as detection.
+ */
+function localHarnessEvidence(cwd: string): Harness[] {
   const found: Harness[] = []
-  if (existsSync(path.join(cwd, '.claude')) || existsSync(path.join(os.homedir(), '.claude'))) {
+  if (existsSync(path.join(cwd, '.claude')) || existsSync(path.join(cwd, 'CLAUDE.md'))) {
     found.push('claude-code')
   }
-  if (existsSync(path.join(cwd, '.codex')) || existsSync(path.join(os.homedir(), '.codex'))) {
-    found.push('codex')
-  }
-  if (existsSync(path.join(cwd, '.cursor')) || existsSync(path.join(os.homedir(), '.cursor'))) {
-    found.push('cursor')
-  }
-  if (
-    existsSync(path.join(cwd, '.opencode')) ||
-    existsSync(path.join(os.homedir(), '.config', 'opencode'))
-  ) {
-    found.push('opencode')
-  }
-  return found.length === 1 ? found[0]! : null
+  if (existsSync(path.join(cwd, '.codex'))) found.push('codex')
+  if (existsSync(path.join(cwd, '.cursor'))) found.push('cursor')
+  if (existsSync(path.join(cwd, '.opencode'))) found.push('opencode')
+  return found
+}
+
+/** Harnesses installed anywhere on this machine — a much weaker signal. */
+function globalHarnessEvidence(): Harness[] {
+  const home = os.homedir()
+  const found: Harness[] = []
+  if (existsSync(path.join(home, '.claude'))) found.push('claude-code')
+  if (existsSync(path.join(home, '.codex'))) found.push('codex')
+  if (existsSync(path.join(home, '.cursor'))) found.push('cursor')
+  if (existsSync(path.join(home, '.config', 'opencode'))) found.push('opencode')
+  return found
+}
+
+/**
+ * Which harness to wire in this directory, or null when it is genuinely
+ * unclear.
+ *
+ * Project evidence decides, and machine evidence is consulted only when the
+ * project offers none. The two were previously OR-ed together per harness,
+ * which meant a developer with several agent tools installed could never get
+ * a detection at all: every `~/.<tool>` directory contributed a candidate, the
+ * "exactly one" test never passed, and the answer was null in every repository
+ * on the machine. Verified on a machine carrying all four — `notifai init
+ * --hooks` failed in five separate projects, each of which plainly used Claude
+ * Code.
+ *
+ * Having a tool installed says nothing about which one *this* project is
+ * worked in. Ambiguity within the project is still ambiguity, and returns
+ * null so the caller can ask rather than guess.
+ */
+export function detectHarness(cwd: string): Harness | null {
+  const local = localHarnessEvidence(cwd)
+  if (local.length > 0) return local.length === 1 ? local[0]! : null
+  const global = globalHarnessEvidence()
+  return global.length === 1 ? global[0]! : null
 }
 
 interface SettingsDocument {

package/src/main.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { Command } from 'commander'
 import {
   askCommand,
@@ -62,9 +64,30 @@ async function readStdin(timeoutMs = 2000, maxBytes = 1_000_000): Promise<string
   })
 }
 
+/**
+ * One source of truth for the version: the manifest npm actually published.
+ *
+ * It was hardcoded here as well, and the first patch release proved why that
+ * does not hold — `package.json` moved and `notifai --version` kept reporting
+ * the old number, which is exactly the string someone pastes into a bug report
+ * to say what they are running.
+ */
+function version(): string {
+  try {
+    const manifest = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json')
+    const parsed: unknown = JSON.parse(readFileSync(manifest, 'utf8'))
+    if (typeof parsed === 'object' && parsed !== null && typeof (parsed as { version?: unknown }).version === 'string') {
+      return (parsed as { version: string }).version
+    }
+  } catch {
+    // Fall through: an unreadable manifest must not stop the CLI running.
+  }
+  return 'unknown'
+}
+
 const program = new Command('notifai')
   .description('Send native device notifications from agents and local programs')
-  .version('0.1.0')
+  .version(version())
 
 program
   .command('login')
@@ -292,11 +315,11 @@ config
 program
   .command('init')
   .description(
-    'Set up NotifAI here, idempotently: sign-in, project id, hooks, device readiness. ' +
+    'Set up NotifAI here, idempotently: sign-in, project id, hooks, device readiness, live receipt proof. ' +
       'Interactive at a human terminal; never prompts otherwise (agents: pass flags)',
   )
   .option('--project-id <id>', 'project identifier slug (default: derived from the directory name)')
-  .option('--skills', 'reserved: this build has no published agent-skill source and exits with an error')
+  .option('--skills', 'install/update the agent skill from its pinned public release')
   .option('--no-skills', 'suppress the optional agent-skill status line')
   .option('--hooks', 'install harness hooks for registered-question routing')
   .option('--no-hooks', 'skip the hooks without being asked')
@@ -306,7 +329,7 @@ program
 
 program
   .command('doctor')
-  .description('Audit config, credential, server, contract, device, and hook readiness (no live send)')
+  .description('Audit config, credential, server, contract, device, hook, and saved receipt proof (no live send)')
   .option('--json', 'machine-readable output')
   .action(async (opts: { json?: boolean }) => {
     process.exit(await doctorCommand(deps, opts))

package/src/send.ts

@@ -196,6 +196,9 @@ export function formatReceipt(receipt: SubmissionReceipt): string {
     const detail = d.provider_reason ? ` (${d.provider_reason})` : ''
     lines.push(`  ${d.device_name}: ${d.state}${detail}`)
   }
+  lines.push(
+    `  device receipt is not assessed here; run notifai status ${receipt.request_id} for Companion Receipt evidence`,
+  )
   for (const w of receipt.warnings) lines.push(`  warning ${w.path}: ${w.message}`)
   return lines.join('\n')
 }