@raidiant/notifai 0.2.1 → 0.4.0

package/src/config.ts

@@ -4,6 +4,7 @@ import os from 'node:os'
 import path from 'node:path'
 import { parse as parseToml } from 'smol-toml'
 import type { CLI_SOUNDS, INTERRUPTION_LEVELS } from '@raidiant/notifai-protocol'
+import { HOOK_TIMING } from './harnesses.js'
 
 /**
  * Layered configuration with provenance. Most specific wins:
@@ -39,6 +40,14 @@ export interface ResolvedValue<T> {
 type CliSound = (typeof CLI_SOUNDS)[number]
 type CliInterruptionLevel = (typeof INTERRUPTION_LEVELS)[number]
 
+/**
+ * How much the local log records. Defined here rather than in `logging.ts`
+ * because it is a configuration vocabulary first — `logging.ts` reads config,
+ * so the dependency has to point this way.
+ */
+export const LOG_LEVELS = ['off', 'error', 'info', 'debug'] as const
+export type LogLevel = (typeof LOG_LEVELS)[number]
+
 export interface CliConfig {
   base_url: ResolvedValue<string>
   wait_seconds: ResolvedValue<number>
@@ -81,8 +90,8 @@ export interface CliConfig {
   away_after_seconds: ResolvedValue<number>
   /**
    * How long a hook blocks waiting for a companion-device answer before falling through
-   * to the harness's own prompt. Must stay under the harness hook timeout
-   * (600s in both Claude Code and Codex) or the harness kills us mid-wait.
+   * to the harness's own prompt. Runtime arbitration keeps the complete Stop
+   * invocation inside its fixed 480s owner budget and 540s adapter ceiling.
    */
   hook_reply_timeout_seconds: ResolvedValue<number>
   /**
@@ -96,6 +105,24 @@ export interface CliConfig {
    * questions, and answering one should not answer the other.
    */
   ask_grace_seconds: ResolvedValue<number>
+  /**
+   * How much of what this CLI does is recorded to the local log.
+   *
+   * The log exists for agents: a hook runs headless and its most consequential
+   * act is usually a decision to do nothing, which leaves no other trace. `off`
+   * disables the sink entirely; `debug` adds config resolution and request
+   * detail, which is verbose enough to want a reason.
+   */
+  log_level: ResolvedValue<LogLevel>
+  /**
+   * Bytes the active log file may reach before it is rotated. With
+   * `log_max_files` this is the whole disk budget — nothing here grows without
+   * a ceiling, because a log that fills a disk is a bug that outlives its
+   * usefulness.
+   */
+  log_max_bytes: ResolvedValue<number>
+  /** Log files kept in total, the active one included. */
+  log_max_files: ResolvedValue<number>
 }
 
 export const CONFIG_KEYS = [
@@ -113,6 +140,9 @@ export const CONFIG_KEYS = [
   'away_after_seconds',
   'hook_reply_timeout_seconds',
   'ask_grace_seconds',
+  'log_level',
+  'log_max_bytes',
+  'log_max_files',
 ] as const
 export type ConfigKey = (typeof CONFIG_KEYS)[number]
 
@@ -129,8 +159,21 @@ export const NUMERIC_CONFIG_KEYS: readonly ConfigKey[] = [
   'away_after_seconds',
   'hook_reply_timeout_seconds',
   'ask_grace_seconds',
+  'log_max_bytes',
+  'log_max_files',
 ]
 
+/**
+ * Keys whose value must be one of a fixed set.
+ *
+ * Config is readable from a repository, so an unrecognised value is untrusted
+ * input rather than a typo — `coerce` drops it and the layer below wins, which
+ * is the same discipline the numeric bounds follow.
+ */
+export const ENUM_CONFIG_VALUES: Partial<Record<ConfigKey, readonly string[]>> = {
+  log_level: LOG_LEVELS,
+}
+
 const DEFAULTS = {
   base_url: 'https://notifai.fly.dev',
   wait_seconds: 10,
@@ -144,17 +187,29 @@ const DEFAULTS = {
   // Installing the hooks is the opt-in; these exist to switch the behaviour
   // back off for a project or a session without uninstalling anything.
   ask_notifications: true,
-  // On by default because it is the less surprising of the two: a question
-  // appearing on your phone while you are typing the answer into the terminal
-  // is worse as a default than one that waits for you to leave.
-  require_idle: true,
+  // Questions reach devices immediately by default. Both a terminal-first
+  // grace and presence gating remain independent opt-in controls.
+  require_idle: false,
   away_after_seconds: 120,
-  // 300 + 180 + the installer's 60s headroom = 540, inside the 600s
-  // command-hook ceiling both harnesses enforce.
-  hook_reply_timeout_seconds: 180,
-  ask_grace_seconds: 300,
+  // Runtime waits stay inside a 480s budget. Harnesses that require a declared
+  // Stop limit use a preference-stable 540s; Codex uses its host-owned Stop
+  // default. Neither definition changes when these preferences do.
+  hook_reply_timeout_seconds: 480,
+  ask_grace_seconds: 0,
+  // 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',
+  // 2 MB × 3 files caps the logs at roughly 6 MB, which is weeks of ordinary
+  // agent traffic and small enough that nobody has to think about it.
+  log_max_bytes: 2_000_000,
+  log_max_files: 3,
 } satisfies Record<ConfigKey, unknown>
 
+/** The shipped value beneath every user-controlled configuration layer. */
+export function configDefaultValue(key: ConfigKey): unknown {
+  return DEFAULTS[key]
+}
+
 export function globalConfigDir(env: NodeJS.ProcessEnv = process.env): string {
   const xdg = env['XDG_CONFIG_HOME']
   const base = xdg && xdg !== '' ? xdg : path.join(os.homedir(), '.config')
@@ -245,17 +300,24 @@ export function findProjectLocalConfigPath(startDir: string): string | null {
  * Ranges every layer is clamped to. Config is readable from a repository, so an
  * out-of-range value is attacker input, not a typo: `away_after_seconds = -1`
  * would make a user who just typed count as absent, and an oversized reply
- * timeout would push the generated hook past the harness's 600s ceiling so the
- * hook is killed after the user has already answered.
+ * timeout would exhaust the hook process budget and kill it after the user has
+ * already answered.
  */
 const NUMERIC_BOUNDS: Partial<Record<ConfigKey, { min: number; max: number }>> = {
   wait_seconds: { min: 0, max: 300 },
   ttl_seconds: { min: 0, max: 7 * 24 * 3600 },
   away_after_seconds: { min: 5, max: 24 * 3600 },
-  // 540 + the installer's 60s headroom stays inside the 600s command-hook
-  // budget shared by Claude Code and Codex.
-  hook_reply_timeout_seconds: { min: 10, max: 540 },
-  ask_grace_seconds: { min: 0, max: 540 },
+  // The runtime clamps grace + reply work below the host process ceiling; this
+  // maximum is never copied into the installed definition.
+  // The wire protocol's minimum reply window is 60s; matching it prevents the
+  // server from accepting an answer after a shorter local wait has returned.
+  hook_reply_timeout_seconds: { min: 60, max: 540 },
+  ask_grace_seconds: { min: 0, max: HOOK_TIMING.maxGraceSeconds },
+  // 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".
+  log_max_bytes: { min: 64_000, max: 100_000_000 },
+  log_max_files: { min: 1, max: 20 },
 }
 
 /** Drops values a layer must not be trusted to supply, rather than throwing. */
@@ -266,6 +328,10 @@ function coerce(key: ConfigKey, value: unknown): unknown | undefined {
     return Math.min(bounds.max, Math.max(bounds.min, Math.trunc(value)))
   }
   if (BOOLEAN_CONFIG_KEYS.includes(key)) return typeof value === 'boolean' ? value : undefined
+  const allowed = ENUM_CONFIG_VALUES[key]
+  if (allowed !== undefined) {
+    return typeof value === 'string' && allowed.includes(value) ? value : undefined
+  }
   return value
 }
 
@@ -343,5 +409,8 @@ export function loadConfig(options: {
     away_after_seconds: resolve('away_after_seconds'),
     hook_reply_timeout_seconds: resolve('hook_reply_timeout_seconds'),
     ask_grace_seconds: resolve('ask_grace_seconds'),
+    log_level: resolve('log_level'),
+    log_max_bytes: resolve('log_max_bytes'),
+    log_max_files: resolve('log_max_files'),
   }
 }

package/src/file-lock-process-worker.test.ts

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+import { withFileLock, type FileLockObservation } from './file-lock.js'
+
+const worker = process.env['NOTIFAI_FILE_LOCK_WORKER']
+const sleep = new Int32Array(new SharedArrayBuffer(4))
+
+function waitFor(file: string): void {
+  const deadline = Date.now() + 15_000
+  while (!existsSync(file)) {
+    if (Date.now() >= deadline) throw new Error(`timed out waiting for ${file}`)
+    Atomics.wait(sleep, 0, 0, 2)
+  }
+}
+
+if (worker === undefined) {
+  describe('file lock process worker', () => {
+    it('stays dormant outside the cross-process regressions', () => {
+      expect(worker).toBeUndefined()
+    })
+  })
+} else {
+  describe('file lock process worker', () => {
+    it('runs one instrumented lock contender', () => {
+      const pauseAt = process.env['NOTIFAI_FILE_LOCK_PAUSE_AT']
+      const pausePath = process.env['NOTIFAI_FILE_LOCK_PAUSED']!
+      const continuePath = process.env['NOTIFAI_FILE_LOCK_CONTINUE']!
+      const enteredPath = process.env['NOTIFAI_FILE_LOCK_ENTERED']!
+      const releasePath = process.env['NOTIFAI_FILE_LOCK_RELEASE']!
+      const waitPath = process.env['NOTIFAI_FILE_LOCK_WAITS']!
+      let waits = 0
+
+      withFileLock(
+        process.env['NOTIFAI_FILE_LOCK_PATH']!,
+        () => {
+          writeFileSync(enteredPath, worker)
+          if (process.env['NOTIFAI_FILE_LOCK_ACTION'] === 'crash') {
+            process.kill(process.pid, 'SIGKILL')
+            throw new Error('SIGKILL did not terminate the worker')
+          }
+          waitFor(releasePath)
+        },
+        {
+          waitMs: 15_000,
+          observe(observation: FileLockObservation) {
+            if (
+              observation.phase === 'choosing-published' ||
+              observation.phase === 'stale-entry'
+            ) {
+              writeFileSync(pausePath, observation.entry)
+              if (pauseAt === observation.phase) waitFor(continuePath)
+            }
+            if (observation.phase === 'waiting') {
+              waits += 1
+              writeFileSync(waitPath, String(waits))
+            }
+          },
+        },
+      )
+
+      expect(readFileSync(enteredPath, 'utf8')).toBe(worker)
+    })
+  })
+}

package/src/file-lock.test.ts

@@ -0,0 +1,279 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { withFileLock, withTargetFileLock } from './file-lock.js'
+
+interface LockWorker {
+  child: ChildProcess
+  done: Promise<void>
+  pausedPath: string
+  continuePath: string
+  enteredPath: string
+  releasePath: string
+  waitsPath: string
+}
+
+interface LockWorkerOptions {
+  pauseAt?: string
+  action?: 'hold' | 'crash'
+}
+
+function waitCount(file: string): number {
+  try {
+    return Number(readFileSync(file, 'utf8'))
+  } catch {
+    return 0
+  }
+}
+
+async function waitUntil(predicate: () => boolean, timeoutMs = 10_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error('timed out waiting for file-lock worker')
+    await new Promise((resolve) => setTimeout(resolve, 5))
+  }
+}
+
+function lockWorker(
+  root: string,
+  lockPath: string,
+  id: string,
+  options: LockWorkerOptions = {},
+): LockWorker {
+  const marker = (name: string): string => path.join(root, `${id}-${name}`)
+  const pausedPath = marker('paused')
+  const continuePath = marker('continue')
+  const enteredPath = marker('entered')
+  const releasePath = marker('release')
+  const waitsPath = marker('waits')
+  const vitest = path.join(process.cwd(), 'node_modules', 'vitest', 'vitest.mjs')
+  const child = spawn(
+    process.execPath,
+    [vitest, 'run', 'src/file-lock-process-worker.test.ts', '--reporter=dot', '--maxWorkers=1'],
+    {
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        NOTIFAI_FILE_LOCK_WORKER: id,
+        NOTIFAI_FILE_LOCK_PATH: lockPath,
+        NOTIFAI_FILE_LOCK_PAUSED: pausedPath,
+        NOTIFAI_FILE_LOCK_CONTINUE: continuePath,
+        NOTIFAI_FILE_LOCK_ENTERED: enteredPath,
+        NOTIFAI_FILE_LOCK_RELEASE: releasePath,
+        NOTIFAI_FILE_LOCK_WAITS: waitsPath,
+        NOTIFAI_FILE_LOCK_ACTION: options.action ?? 'hold',
+        ...(options.pauseAt === undefined
+          ? {}
+          : { NOTIFAI_FILE_LOCK_PAUSE_AT: options.pauseAt }),
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    },
+  )
+  const stdout: Buffer[] = []
+  const stderr: Buffer[] = []
+  child.stdout!.on('data', (chunk: Buffer) => stdout.push(chunk))
+  child.stderr!.on('data', (chunk: Buffer) => stderr.push(chunk))
+  const done = new Promise<void>((resolve, reject) => {
+    child.once('error', reject)
+    child.once('exit', (code, signal) => {
+      const expectedExit =
+        options.action === 'crash' ? code !== 0 || signal !== null : code === 0
+      if (expectedExit) resolve()
+      else {
+        reject(
+          new Error(
+            `file-lock worker ${id} exited ${String(code)}\n${Buffer.concat(stdout).toString()}\n${Buffer.concat(stderr).toString()}`,
+          ),
+        )
+      }
+    })
+  })
+  void done.catch(() => undefined)
+  return { child, done, pausedPath, continuePath, enteredPath, releasePath, waitsPath }
+}
+
+function stop(workers: LockWorker[]): void {
+  for (const worker of workers) {
+    if (worker.child.exitCode === null && worker.child.signalCode === null) worker.child.kill('SIGKILL')
+  }
+}
+
+describe('cross-process file lock', () => {
+  it('does not expose an ownerless publication window before acquisition is complete', async () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-file-lock-'))
+    const lockPath = path.join(root, 'shared.lock')
+    const workers: LockWorker[] = []
+    try {
+      const first = lockWorker(root, lockPath, 'first', { pauseAt: 'choosing-published' })
+      workers.push(first)
+      await waitUntil(() => existsSync(first.pausedPath))
+
+      const published = readdirSync(lockPath)
+      expect(published).toHaveLength(1)
+      expect(published[0]).toMatch(/^choosing-\d+-[0-9a-f]+$/)
+      expect(statSync(path.join(lockPath, published[0]!)).size).toBe(0)
+
+      const second = lockWorker(root, lockPath, 'second')
+      workers.push(second)
+      await waitUntil(() => existsSync(second.pausedPath) && waitCount(second.waitsPath) > 0)
+      expect(existsSync(first.enteredPath)).toBe(false)
+      expect(existsSync(second.enteredPath)).toBe(false)
+
+      writeFileSync(first.continuePath, 'continue')
+      await waitUntil(() => existsSync(first.enteredPath) !== existsSync(second.enteredPath))
+
+      const winner = existsSync(first.enteredPath) ? first : second
+      const loser = winner === first ? second : first
+      const waitsBefore = waitCount(loser.waitsPath)
+      await waitUntil(() => {
+        if (existsSync(loser.enteredPath)) throw new Error('both lock actions overlapped')
+        return waitCount(loser.waitsPath) > waitsBefore
+      })
+
+      writeFileSync(winner.releasePath, 'release')
+      await waitUntil(() => existsSync(loser.enteredPath))
+      writeFileSync(loser.releasePath, 'release')
+      await Promise.all(workers.map(({ done }) => done))
+      expect(existsSync(lockPath)).toBe(false)
+    } finally {
+      stop(workers)
+      await Promise.allSettled(workers.map(({ done }) => done))
+      rmSync(root, { recursive: true, force: true })
+    }
+  }, 30_000)
+
+  it('cannot reap a successor after observing a dead owner', async () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-file-lock-'))
+    const lockPath = path.join(root, 'shared.lock')
+    const workers: LockWorker[] = []
+    try {
+      const crashed = lockWorker(root, lockPath, 'crashed', { action: 'crash' })
+      workers.push(crashed)
+      await waitUntil(() => existsSync(crashed.enteredPath))
+      await crashed.done
+
+      const staleEntries = readdirSync(lockPath)
+      expect(staleEntries).toHaveLength(1)
+      expect(staleEntries[0]).toMatch(/^ticket-\d+-\d+-[0-9a-f]+$/)
+      const staleEntry = staleEntries[0]!
+
+      const delayedReaper = lockWorker(root, lockPath, 'delayed-reaper', {
+        pauseAt: 'stale-entry',
+      })
+      workers.push(delayedReaper)
+      await waitUntil(
+        () =>
+          existsSync(delayedReaper.pausedPath) &&
+          readFileSync(delayedReaper.pausedPath, 'utf8') === staleEntry,
+      )
+
+      const successor = lockWorker(root, lockPath, 'successor')
+      workers.push(successor)
+      await waitUntil(() => existsSync(successor.enteredPath))
+      const successorEntry = readdirSync(lockPath).find((entry) => entry.startsWith('ticket-'))
+      expect(successorEntry).toBeDefined()
+      expect(successorEntry).not.toBe(staleEntry)
+
+      writeFileSync(delayedReaper.continuePath, 'continue')
+      await waitUntil(() => {
+        if (existsSync(delayedReaper.enteredPath)) {
+          throw new Error('the delayed stale cleanup displaced the successor')
+        }
+        return waitCount(delayedReaper.waitsPath) > 0
+      })
+
+      writeFileSync(successor.releasePath, 'release')
+      await waitUntil(() => existsSync(delayedReaper.enteredPath))
+      writeFileSync(delayedReaper.releasePath, 'release')
+      await Promise.all([successor.done, delayedReaper.done])
+    } finally {
+      stop(workers)
+      await Promise.allSettled(workers.map(({ done }) => done))
+      rmSync(root, { recursive: true, force: true })
+    }
+  }, 30_000)
+})
+
+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-'))
+    const foreign = path.join(root, 'foreign')
+    const linked = path.join(root, 'linked')
+    mkdirSync(foreign)
+    symlinkSync(foreign, linked)
+
+    expect(() => withTargetFileLock(path.join(linked, 'settings.json'), () => {})).toThrow(
+      /not a regular directory/,
+    )
+    expect(existsSync(path.join(foreign, '.settings.json.notifai.lock'))).toBe(false)
+  })
+
+  it('refuses a symlink posing as the lock rendezvous', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-target-lock-'))
+    const foreign = path.join(root, 'foreign')
+    const lock = path.join(root, '.settings.json.notifai.lock')
+    mkdirSync(foreign)
+    symlinkSync(foreign, lock)
+
+    expect(() => withTargetFileLock(path.join(root, 'settings.json'), () => {})).toThrow(
+      /not a regular directory/,
+    )
+  })
+
+  it('does not remove a replacement at its unique owned entry', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-target-lock-'))
+    const target = path.join(root, 'settings.json')
+    const lock = path.join(root, '.settings.json.notifai.lock')
+    let replacement = ''
+
+    expect(() =>
+      withTargetFileLock(target, () => {
+        const entry = readdirSync(lock)[0]!
+        replacement = path.join(lock, entry)
+        rmSync(replacement)
+        writeFileSync(replacement, 'replacement')
+      }),
+    ).toThrow(/changed while held/)
+    expect(readFileSync(replacement, 'utf8')).toBe('replacement')
+  })
+
+  it('preserves the action error when release also finds a replacement', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-target-lock-'))
+    const target = path.join(root, 'settings.json')
+    const lock = path.join(root, '.settings.json.notifai.lock')
+    const actionError = new Error('merge failed')
+
+    expect(() =>
+      withTargetFileLock(target, () => {
+        const entry = path.join(lock, readdirSync(lock)[0]!)
+        rmSync(entry)
+        writeFileSync(entry, 'replacement')
+        throw actionError
+      }),
+    ).toThrow(actionError)
+  })
+
+  it('refuses a symlink masquerading as a protocol entry', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-target-lock-'))
+    const lock = path.join(root, 'shared.lock')
+    const foreign = path.join(root, 'foreign')
+    mkdirSync(lock)
+    writeFileSync(foreign, 'leave me')
+    symlinkSync(foreign, path.join(lock, 'ticket-1-999999-deadbeef'))
+
+    expect(() => withFileLock(lock, () => {})).toThrow(/regular file-lock entry/)
+    expect(readFileSync(foreign, 'utf8')).toBe('leave me')
+  })
+})