@raidiant/notifai 4.0.0 → 5.0.0

package/src/config.test.ts

@@ -191,20 +191,32 @@ describe('draft building', () => {
       presentation: { title: 'T', body: 'B' },
       targets: { mode: 'all' },
       delivery: { ttl_seconds: 86400, collapse_key: null },
+      // An unlabelled draft is ordinary news, and news has a sound.
+      platform: { ios: { sound: 'default' }, macos: { sound: 'default' } },
     })
   })
 
   it.each([
-    {},
-    { kind: 'done' },
-    { kind: 'failed' },
-    { kind: 'blocked' },
-    { reply: true },
-  ])('never derives sound or interruption level from kind: %j', (flags) => {
+    { flags: {}, sound: 'default' },
+    { flags: { kind: 'update' }, sound: 'default' },
+    { flags: { kind: 'done' }, sound: 'done' },
+    { flags: { kind: 'failed' }, sound: 'alert' },
+    { flags: { kind: 'blocked' }, sound: 'attention' },
+    { flags: { kind: 'question' }, sound: 'attention' },
+    { flags: { reply: true }, sound: 'attention' },
+  ])('gives $flags the $sound sound when nobody chose one', ({ flags, sound }) => {
     const config = loadConfig({ cwd: base.cwd, env: base.env })
     const build = buildDraft(config, { title: 'T', body: 'B', ...flags })
     if (!build.ok) throw new Error(build.error)
-    expect(build.draft.platform).toBeUndefined()
+    expect(build.draft.platform?.ios?.sound).toBe(sound)
+    expect(build.draft.platform?.ios?.interruption_level).toBeUndefined()
+  })
+
+  it('lets an explicit sound outrank the kind it would have derived', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    const explicit = buildDraft(config, { title: 'T', body: 'B', kind: 'failed', sound: 'none' })
+    if (!explicit.ok) throw new Error(explicit.error)
+    expect(explicit.draft.platform?.ios?.sound).toBeNull()
   })
 
   it('orders explicit flags over saved user config', () => {
@@ -233,12 +245,32 @@ describe('draft building', () => {
     })
   })
 
-  it('keeps a blocking reply answerable for one hour by default', () => {
+  it('keeps a question answerable for a day by default', () => {
+    // A question asked before someone steps away should still be theirs to
+    // answer when they come back; the CLI used to cut the wire contract's own
+    // default down to an hour.
     const config = loadConfig({ cwd: base.cwd, env: base.env })
     const build = buildDraft(config, { title: 'Question', body: 'Deploy?', reply: true })
     if (!build.ok) throw new Error(build.error)
 
-    expect(build.draft.reply?.expires_in_seconds).toBe(3_600)
+    expect(build.draft.reply?.expires_in_seconds).toBe(86_400)
+  })
+
+  it('lets the user shorten or lengthen how long an answer is accepted', () => {
+    const { env, cwd } = setup({ projectToml: 'reply_window_seconds = 7200\n' })
+    const config = loadConfig({ cwd, env })
+    const build = buildDraft(config, { title: 'Question', body: 'Deploy?', reply: true })
+    if (!build.ok) throw new Error(build.error)
+    expect(build.draft.reply?.expires_in_seconds).toBe(7_200)
+
+    const explicit = buildDraft(config, {
+      title: 'Question',
+      body: 'Deploy?',
+      reply: true,
+      replyWindow: 600,
+    })
+    if (!explicit.ok) throw new Error(explicit.error)
+    expect(explicit.draft.reply?.expires_in_seconds).toBe(600)
   })
 
   it('orders explicit and configured Project identity over inference', () => {

package/src/config.ts

@@ -1,3 +1,4 @@
+import { REPLY_MAX_WINDOW_SECONDS } from '@raidiant/notifai-protocol'
 import { createHash } from 'node:crypto'
 import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import path from 'node:path'
@@ -87,6 +88,8 @@ export interface CliConfig {
    * usefulness.
    */
   log_max_bytes: ResolvedValue<number>
+  /** How long the server keeps accepting an answer to a question. */
+  reply_window_seconds: ResolvedValue<number>
   /** Log files kept in total, the active one included. */
   log_max_files: ResolvedValue<number>
 }
@@ -102,6 +105,7 @@ export const CONFIG_KEYS = [
   'notify_criteria',
   'ask_notifications',
   'ask_grace_seconds',
+  'reply_window_seconds',
   'log_level',
   'log_max_bytes',
   'log_max_files',
@@ -116,6 +120,7 @@ export const NUMERIC_CONFIG_KEYS: readonly ConfigKey[] = [
   'wait_seconds',
   'ttl_seconds',
   'ask_grace_seconds',
+  'reply_window_seconds',
   'log_max_bytes',
   'log_max_files',
 ]
@@ -149,6 +154,9 @@ const DEFAULTS = {
   // Questions reach devices as soon as the turn ends. A terminal-first grace
   // window is an opt-in delay on top of that.
   ask_grace_seconds: 0,
+  // A day. The wire contract's own default, and long enough that a question
+  // asked before someone steps away is still answerable when they come back.
+  reply_window_seconds: 86_400,
   // On by default: the log is the only account of what a headless hook did, and
   // a diagnostic nobody switched on before the thing went wrong is not one.
   log_level: 'info',
@@ -302,6 +310,10 @@ const NUMERIC_BOUNDS: Partial<Record<ConfigKey, { min: number; max: number }>> =
   // longest window a user can choose still leaves an answer window the server
   // will accept — with room to spare for a timer that wakes late.
   ask_grace_seconds: { min: 0, max: 360 },
+  // The floor is the shortest window the wire contract accepts; the ceiling is
+  // the point past which a question would outlive the retained content it
+  // refers to.
+  reply_window_seconds: { min: 60, max: REPLY_MAX_WINDOW_SECONDS },
   // The floor keeps rotation from thrashing (a file smaller than a handful of
   // records would rotate on nearly every write); the ceiling is the point past
   // which "local diagnostics" has become "a database on your disk".
@@ -413,6 +425,7 @@ export function loadConfig(options: {
     notify_criteria: resolve('notify_criteria'),
     ask_notifications: resolve('ask_notifications'),
     ask_grace_seconds: resolve('ask_grace_seconds'),
+    reply_window_seconds: resolve('reply_window_seconds'),
     log_level: resolve('log_level'),
     log_max_bytes: resolve('log_max_bytes'),
     log_max_files: resolve('log_max_files'),

package/src/file-lock.test.ts

@@ -206,6 +206,47 @@ describe('cross-process file lock', () => {
   }, 30_000)
 })
 
+describe('rendezvous contention', () => {
+  // The last contender out removes the rendezvous directory, so a contender
+  // registering at that instant races the removal. Both tests drive that race
+  // from the registering observation, which is the window the racing releaser
+  // would otherwise have to hit by luck — on a loaded machine it does.
+  function raceAtRegistration(interfere: (lock: string) => void): void {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-rendezvous-'))
+    const lock = path.join(root, 'shared.lock')
+    let raced = false
+    let entered = 0
+
+    withFileLock(lock, () => { entered += 1 }, {
+      observe(observation) {
+        if (observation.phase !== 'registering' || raced) return
+        raced = true
+        interfere(lock)
+      },
+    })
+
+    expect(raced).toBe(true)
+    expect(entered).toBe(1)
+    // Release still cleans up after itself, whichever rendezvous it ended in.
+    expect(existsSync(lock)).toBe(false)
+    rmSync(root, { recursive: true, force: true })
+  }
+
+  it('registers again when a releasing contender removed the rendezvous', () => {
+    raceAtRegistration((lock) => rmSync(lock, { recursive: true }))
+  })
+
+  it('holds the rendezvous it landed in, not the one it scanned', () => {
+    // A third contender recreates the directory before this one publishes, so
+    // the entry lands in a directory whose identity nobody has recorded yet.
+    // Treating that as tampering used to break the caller outright.
+    raceAtRegistration((lock) => {
+      rmSync(lock, { recursive: true })
+      mkdirSync(lock, { mode: 0o700 })
+    })
+  })
+})
+
 describe('target file transaction lock', () => {
   it('refuses a symlinked target parent before publishing a contender', () => {
     const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-target-lock-'))

package/src/file-lock.ts

@@ -22,6 +22,14 @@ import path from 'node:path'
  * process cannot remove a later owner's entry; because process liveness, rather
  * than age, decides recovery, a delayed holder is never mistaken for a dead one.
  *
+ * The rendezvous directory lives only as long as it has entries: the last
+ * contender out removes it, so an idle machine keeps no lock state. That makes
+ * the directory itself a contended resource. A contender registering while
+ * another releases can find it gone, half-deleted, or already replaced by a
+ * third contender, and none of those is a broken lock — so publication retries
+ * within the caller's deadline and pins its rendezvous only once its own entry
+ * is in the directory, which is the moment removal becomes impossible.
+ *
  * Acquisition is deliberately bounded because both harness hooks and logging
  * must fail open rather than hold an agent turn indefinitely.
  */
@@ -32,6 +40,8 @@ const ENTRY_PATTERN = /^(choosing|ticket-(\d+))-(\d+)-([0-9a-f]+)$/
 const lockSleep = new Int32Array(new SharedArrayBuffer(4))
 
 export type FileLockObservation =
+  /** The rendezvous has been scanned and this contender is about to publish. */
+  | { phase: 'registering'; entry: string }
   | { phase: 'choosing-published'; entry: string }
   | { phase: 'stale-entry'; entry: string }
   | { phase: 'waiting'; blockers: string[] }
@@ -125,6 +135,16 @@ function assertOwnedDirectory(directory: string): FileIdentity {
   return { dev: stat.dev, ino: stat.ino }
 }
 
+/**
+ * The rendezvous a contender was using is no longer the directory at that path.
+ *
+ * Fatal once an entry is published — a contender's own entry makes the
+ * directory non-empty, so no cooperating releaser can remove it. Before
+ * publication it means only that a releaser removed an empty rendezvous while
+ * this contender was registering in it, which is ordinary contention.
+ */
+class RendezvousReplaced extends Error {}
+
 function assertSameDirectory(directory: string, expected: FileIdentity): void {
   const current = lstatSync(directory)
   if (
@@ -133,7 +153,7 @@ function assertSameDirectory(directory: string, expected: FileIdentity): void {
     current.dev !== expected.dev ||
     current.ino !== expected.ino
   ) {
-    throw new Error(`${directory} changed while the file lock was active.`)
+    throw new RendezvousReplaced(`${directory} changed while the file lock was active.`)
   }
 }
 
@@ -207,6 +227,24 @@ function publishEmpty(file: string): EntryIdentity {
   }
 }
 
+/**
+ * True when a publication attempt lost its rendezvous rather than found a
+ * broken one.
+ *
+ * A releaser removes an empty rendezvous directory the moment the last entry
+ * goes, so a contender registering at that instant sees the removal from
+ * whichever side it reached first. All three are the same event: `ENOENT` when
+ * the directory is already gone, `EINVAL` when APFS reports a directory that is
+ * still being deleted, and a replaced identity when a third contender recreated
+ * it first. None of them says anything about the lock's integrity, because a
+ * contender with no published entry owns nothing yet.
+ */
+function lostTheRendezvous(err: unknown): boolean {
+  if (err instanceof RendezvousReplaced) return true
+  const code = (err as NodeJS.ErrnoException).code
+  return code === 'ENOENT' || code === 'EINVAL'
+}
+
 function publishChoosing(
   directory: string,
   name: string,
@@ -217,21 +255,33 @@ function publishChoosing(
   for (;;) {
     try {
       mkdirSync(directory, { recursive: true, mode: 0o700 })
-      const directoryIdentity = assertOwnedDirectory(directory)
+      const registrar = assertOwnedDirectory(directory)
       chmodSync(directory, 0o700)
       // Recover before registration so a delayed stale cleanup can only name an
       // old owner's unique path, never this contender's future one.
-      liveEntries(directory, directoryIdentity, observe)
+      liveEntries(directory, registrar, observe)
+      observe?.({ phase: 'registering', entry: name })
       const fileIdentity = publishEmpty(file)
-      assertSameDirectory(directory, directoryIdentity)
+      // Pin the rendezvous that holds the entry, not the one scanned before it
+      // existed. `open` resolves the path atomically, so the entry lands in
+      // whichever directory the path named at that instant — and from then on
+      // that directory is non-empty, so no cooperating releaser can remove it.
+      // Reading the identity here therefore names the contender's real
+      // rendezvous even when the scanned one was removed and recreated
+      // underneath it.
+      const directoryIdentity = assertOwnedDirectory(directory)
+      if (!sameEntryIdentity(file, fileIdentity)) {
+        throw new RendezvousReplaced(`${directory} no longer holds ${name}.`)
+      }
       return { file, fileIdentity, directoryIdentity }
     } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
-      // The previous holder removed an empty rendezvous directory between our
-      // mkdir and publication. Recreate it; once our entry exists, no cooperating
-      // releaser can remove the non-empty directory underneath us.
+      if (!lostTheRendezvous(err)) throw err
+      // Recreate it and register again; the deadline, not the number of losses,
+      // decides when contention becomes a failure.
       if (Date.now() >= deadline) {
-        throw new Error(`timed out publishing file lock contender in ${directory}`)
+        throw new Error(
+          `timed out publishing file lock contender in ${directory}: ${(err as Error).message}`,
+        )
       }
       Atomics.wait(lockSleep, 0, 0, FILE_LOCK_POLL_MS)
     }

package/src/harnesses.test.ts

@@ -1,34 +1,42 @@
 import { describe, expect, it } from 'vitest'
-import { HARNESS_CAPABILITIES, HARNESSES } from './harnesses.js'
+import { HARNESS_CAPABILITIES, HARNESS_LABELS, HARNESSES } from './harnesses.js'
 
-describe('harness continuation contract', () => {
-  it('requires one explicit native delivery contract for every shipped harness', () => {
+/**
+ * This file used to hold a verbatim copy of the table below it, which meant
+ * changing a harness contract required changing the same words twice and the
+ * test could never disagree with the code — only with whoever forgot the second
+ * edit. What is worth asserting is the shape the rest of the CLI assumes.
+ */
+describe('harness contract', () => {
+  it('describes every shipped harness, and only those', () => {
     expect(Object.keys(HARNESS_CAPABILITIES).sort()).toEqual([...HARNESSES].sort())
-    expect(HARNESS_CAPABILITIES).toEqual({
-      'claude-code': {
-        stopContinuation: 'decision-block',
-        deliveryRoutes: ['hook-continuation', 'inbox-socket', 'cold-resume', 'hold-for-next-turn'],
-        deliveryContract:
-          'the Stop hook returns at once and waits out of band, then posts the answer into this same session over its own inbox socket; a session that has stopped is resumed only once a liveness probe proves it stopped',
-      },
-      codex: {
-        stopContinuation: 'decision-block',
-        deliveryRoutes: ['hook-continuation', 'cold-resume', 'hold-for-next-turn'],
-        deliveryContract:
-          'live Stop continuation while the turn is held; once it returns, a stopped thread is resumed behind its writer lock and anything else waits for the next turn',
-      },
-      cursor: {
-        stopContinuation: 'unsupported',
-        deliveryRoutes: ['unsupported'],
-        deliveryContract:
-          'the hook can return a live follow-up, but the invoking shell exposes no exact conversation id; asynchronous ask is unsupported',
-      },
-      opencode: {
-        stopContinuation: 'unsupported',
-        deliveryRoutes: ['unsupported'],
-        deliveryContract:
-          'no proven answer continuation after session.idle; use a blocking reply command',
-      },
-    })
+    expect(Object.keys(HARNESS_LABELS).sort()).toEqual([...HARNESSES].sort())
+  })
+
+  it('gives a harness that cannot continue a turn no route to pretend with', () => {
+    // `ask` fails closed on these, and the reason it can is that the two facts
+    // agree. A harness claiming a delivery route while declaring it cannot
+    // continue would accept an answer into a void.
+    for (const [harness, capability] of Object.entries(HARNESS_CAPABILITIES)) {
+      if (capability.stopContinuation !== 'unsupported') continue
+      expect(capability.deliveryRoutes, harness).toEqual(['unsupported'])
+    }
+  })
+
+  it('gives a harness that can continue a turn at least one real route', () => {
+    for (const [harness, capability] of Object.entries(HARNESS_CAPABILITIES)) {
+      if (capability.stopContinuation === 'unsupported') continue
+      expect(capability.deliveryRoutes.length, harness).toBeGreaterThan(0)
+      expect(capability.deliveryRoutes, harness).not.toContain('unsupported')
+      // The journal is the floor under every supported route: without it an
+      // answer that misses its turn has nowhere to wait.
+      expect(capability.deliveryRoutes, harness).toContain('hold-for-next-turn')
+    }
+  })
+
+  it('explains each harness in prose an operator can act on', () => {
+    for (const [harness, capability] of Object.entries(HARNESS_CAPABILITIES)) {
+      expect(capability.deliveryContract.length, harness).toBeGreaterThan(40)
+    }
   })
 })

package/src/harnesses.ts

@@ -18,10 +18,7 @@ export type DeliveryRoute =
   | 'hold-for-next-turn'
   | 'unsupported'
 
-export type StopContinuation =
-  | 'decision-block'
-  | 'followup-message'
-  | 'unsupported'
+export type StopContinuation = 'decision-block' | 'unsupported'
 
 export interface HarnessCapability {
   /** How an answer is admitted to another turn in the already-open session. */