@raidiant/notifai 0.4.0 → 0.5.0

package/src/codex-wake.test.ts

@@ -0,0 +1,253 @@
+import { closeSync, mkdirSync, mkdtempSync, openSync, rmSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterAll, describe, expect, it, vi } from 'vitest'
+import {
+  CODEX_THREAD_LOCK_DIR,
+  codexThreadLockPath,
+  codexWakeRoute,
+  observeCodexThread,
+  systemCodexWakeAdapters,
+  type CodexWakeAdapters,
+  type CodexWakeObservation,
+} from './codex-wake.js'
+
+const THREAD_ID = '019ff69d-a07f-7161-ab6e-bd06b3b93c8e'
+
+const event = {
+  context:
+    'Notifai — question_id rollout-option, question "Which rollout option?"; the user answered "BETA".',
+  answers: 1,
+  remaining: 0,
+  request_ids: ['req_test'],
+  journal_recorded_at: 1_800_000_000_000,
+}
+
+const temporaries: string[] = []
+
+function codexHome(): string {
+  const home = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-wake-'))
+  temporaries.push(home)
+  mkdirSync(path.join(home, CODEX_THREAD_LOCK_DIR), { recursive: true })
+  return home
+}
+
+afterAll(() => {
+  for (const directory of temporaries) rmSync(directory, { recursive: true, force: true })
+})
+
+function adapters(
+  options: {
+    sourceAlive?: boolean
+    probes?: CodexWakeObservation[]
+    probe?: CodexWakeObservation
+  } = {},
+): CodexWakeAdapters & { resumed: Array<{ threadId: string; cwd: string; context: string }>; probed: string[] } {
+  const resumed: Array<{ threadId: string; cwd: string; context: string }> = []
+  const probed: string[] = []
+  const sequence = [...(options.probes ?? [])]
+  return {
+    resumed,
+    probed,
+    probeThreadWriter(lockPath) {
+      probed.push(lockPath)
+      return sequence.shift() ?? options.probe ?? { state: 'stopped' }
+    },
+    sourceAlive() {
+      return options.sourceAlive ?? false
+    },
+    async resume(threadId, cwd, context) {
+      resumed.push({ threadId, cwd, context })
+    },
+  }
+}
+
+function route(
+  wake: CodexWakeAdapters,
+  overrides: { threadId?: string; env?: NodeJS.ProcessEnv } = {},
+): ReturnType<typeof codexWakeRoute> {
+  return codexWakeRoute({
+    threadId: overrides.threadId ?? THREAD_ID,
+    cwd: '/tmp/notifai-codex-wake',
+    sourcePid: 4242,
+    env: overrides.env ?? { CODEX_HOME: '/tmp/notifai-codex-home' },
+    adapters: wake,
+  })
+}
+
+describe('Codex thread ownership', () => {
+  it('names the lock file Codex itself keys by thread id', () => {
+    expect(codexThreadLockPath(THREAD_ID, { CODEX_HOME: '/tmp/cx' })).toBe(
+      `/tmp/cx/${CODEX_THREAD_LOCK_DIR}/${THREAD_ID}.lock`,
+    )
+  })
+
+  it('refuses to derive a lock path from a session id that is not a thread id', () => {
+    const wake = adapters()
+
+    expect(observeCodexThread('../../etc/passwd', {}, wake)).toEqual({
+      state: 'unknown',
+      reason: 'the Codex session id is not a thread id',
+    })
+    expect(wake.probed).toEqual([])
+  })
+
+  it('reports a probe that throws as unknown rather than as an unowned thread', () => {
+    const observation = observeCodexThread(THREAD_ID, { CODEX_HOME: '/tmp/cx' }, {
+      probeThreadWriter() {
+        throw new Error('permission denied')
+      },
+    })
+
+    expect(observation).toEqual({
+      state: 'unknown',
+      reason: 'Codex thread-writer lock probe failed: permission denied',
+    })
+  })
+})
+
+describe('Codex writer-lock probe', () => {
+  const platform = process.platform
+  const supported = platform === 'darwin' || platform === 'freebsd' || platform === 'openbsd'
+
+  it.runIf(supported)('reads a kernel-held lock as a live writer and its release as stopped', () => {
+    const home = codexHome()
+    const lock = codexThreadLockPath(THREAD_ID, { CODEX_HOME: home })
+    writeFileSync(lock, '')
+    const probe = systemCodexWakeAdapters({ CODEX_HOME: home }).probeThreadWriter
+
+    // flock is held per open file description, so this process contends with
+    // itself exactly as a separate Codex process would.
+    const held = openSync(lock, 0x20 | 0x4)
+    try {
+      expect(probe(lock)).toEqual({ state: 'live' })
+    } finally {
+      closeSync(held)
+    }
+
+    expect(probe(lock)).toEqual({ state: 'stopped' })
+  })
+
+  it.runIf(supported)('treats a swept lock file inside a real lock directory as stopped', () => {
+    const home = codexHome()
+    const probe = systemCodexWakeAdapters({ CODEX_HOME: home }).probeThreadWriter
+
+    expect(probe(codexThreadLockPath(THREAD_ID, { CODEX_HOME: home }))).toEqual({
+      state: 'stopped',
+    })
+  })
+
+  it.runIf(supported)('never claims a thread is unowned when there is no lock directory', () => {
+    const home = mkdtempSync(path.join(os.tmpdir(), 'notifai-codex-nohome-'))
+    temporaries.push(home)
+    const probe = systemCodexWakeAdapters({ CODEX_HOME: home }).probeThreadWriter
+    const lock = codexThreadLockPath(THREAD_ID, { CODEX_HOME: home })
+
+    expect(probe(lock)).toMatchObject({ state: 'unknown' })
+  })
+
+  it.runIf(!supported)('fails closed where no non-blocking lock probe exists', () => {
+    const probe = systemCodexWakeAdapters({ CODEX_HOME: '/tmp/cx' }).probeThreadWriter
+
+    expect(probe(`/tmp/cx/${CODEX_THREAD_LOCK_DIR}/${THREAD_ID}.lock`)).toMatchObject({
+      state: 'unknown',
+    })
+  })
+})
+
+describe('Codex wake delivery', () => {
+  it('continues the live session through its own Stop hook without probing anything', async () => {
+    const wake = adapters({ sourceAlive: true })
+
+    const outcome = await route(wake).deliver(event)
+
+    expect(JSON.parse(outcome.stdout!)).toEqual({ decision: 'block', reason: event.context })
+    expect(wake.probed).toEqual([])
+    expect(wake.resumed).toEqual([])
+  })
+
+  it('cold-resumes a stopped thread only after two probes both find no writer', async () => {
+    const wake = adapters({ probes: [{ state: 'stopped' }, { state: 'stopped' }] })
+
+    const outcome = await route(wake).deliver(event)
+
+    expect(wake.probed).toEqual([
+      `/tmp/notifai-codex-home/${CODEX_THREAD_LOCK_DIR}/${THREAD_ID}.lock`,
+      `/tmp/notifai-codex-home/${CODEX_THREAD_LOCK_DIR}/${THREAD_ID}.lock`,
+    ])
+    expect(wake.resumed).toEqual([
+      { threadId: THREAD_ID, cwd: '/tmp/notifai-codex-wake', context: event.context },
+    ])
+    expect(outcome.stdout).toBeUndefined()
+    expect(outcome.log).toEqual({ route: 'cold-resume', stage: 'delivered' })
+  })
+
+  it('never resumes a thread a live writer owns', async () => {
+    const wake = adapters({ probe: { state: 'live' } })
+
+    const outcome = await route(wake).deliver(event)
+
+    expect(wake.resumed).toEqual([])
+    expect(outcome.stdout).toBeUndefined()
+    expect(outcome.log).toEqual({
+      route: 'hold-for-next-turn',
+      stage: 'queued',
+      reason: 'a live writer owns the Codex thread and this hook can no longer continue it',
+    })
+    expect(outcome.notes.join('\n')).toContain('holding the accepted answer for the next turn')
+  })
+
+  it('never resumes a thread whose writer took the lock between the two probes', async () => {
+    const wake = adapters({ probes: [{ state: 'stopped' }, { state: 'live' }] })
+
+    const outcome = await route(wake).deliver(event)
+
+    expect(wake.probed).toHaveLength(2)
+    expect(wake.resumed).toEqual([])
+    expect(outcome.log).toMatchObject({ route: 'hold-for-next-turn', stage: 'queued' })
+  })
+
+  it('journals the answer when ownership cannot be probed at all', async () => {
+    const wake = adapters({ probe: { state: 'unknown', reason: 'no lock directory' } })
+
+    const outcome = await route(wake).deliver(event)
+
+    expect(wake.resumed).toEqual([])
+    expect(outcome.log).toEqual({
+      route: 'hold-for-next-turn',
+      stage: 'queued',
+      reason: 'no lock directory',
+    })
+  })
+
+  it('journals the answer when the session id cannot name a thread lock', async () => {
+    const wake = adapters()
+
+    const outcome = await route(wake, { threadId: 'codex-session-7' }).deliver(event)
+
+    expect(wake.probed).toEqual([])
+    expect(wake.resumed).toEqual([])
+    expect(outcome.log).toMatchObject({
+      route: 'hold-for-next-turn',
+      reason: 'the Codex session id is not a thread id',
+    })
+  })
+
+  it('does not report delivery when the cold resume fails', async () => {
+    const wake = adapters()
+    wake.resume = vi.fn(async () => {
+      throw new Error('codex exec exited 1')
+    })
+
+    await expect(route(wake).deliver(event)).rejects.toThrow('codex exec exited 1')
+  })
+})
+
+describe('Codex system adapters', () => {
+  it('reads this process as a live source and PID 0 as no source at all', () => {
+    const wake = systemCodexWakeAdapters({})
+
+    expect(wake.sourceAlive(process.pid)).toBe(true)
+    expect(wake.sourceAlive(0)).toBe(false)
+  })
+})

package/src/codex-wake.ts

@@ -0,0 +1,288 @@
+import { spawn } from 'node:child_process'
+import { closeSync, constants, existsSync, openSync } from 'node:fs'
+import path from 'node:path'
+import { configHome } from './install-hooks.js'
+import {
+  hookContinuationRoute,
+  type ContinuationEvent,
+  type DeliveryOutcome,
+  type EscalationDeliveryRoute,
+} from './hooks.js'
+
+/** Codex's per-thread writer lock directory, relative to `$CODEX_HOME`. */
+export const CODEX_THREAD_LOCK_DIR = 'thread-writer-locks'
+
+/**
+ * BSD `open(2)` lock flags. Node does not surface them in `fs.constants`, and
+ * they are the only way to take a non-blocking `flock` from Node without a
+ * native addon: the kernel takes the lock at open and drops it at close.
+ */
+const O_EXLOCK = 0x20
+const O_NONBLOCK = 0x4
+
+/** Platforms whose `open(2)` implements `O_EXLOCK`. Everything else fails closed. */
+const LOCK_PROBE_PLATFORMS: ReadonlySet<string> = new Set(['darwin', 'freebsd', 'openbsd'])
+
+/** Codex thread ids are UUIDs, and the lock file is named by the exact id. */
+const THREAD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export type CodexWakeObservation =
+  /** A live writer owns this thread. Resuming it would create a divergent ghost. */
+  | { state: 'live' }
+  /** No process holds the thread's writer lock; a cold resume can own it. */
+  | { state: 'stopped' }
+  | { state: 'unknown'; reason: string }
+
+export interface CodexWakeAdapters {
+  /** Non-blocking writer-lock probe. Never holds the lock beyond the probe. */
+  probeThreadWriter(lockPath: string): CodexWakeObservation
+  /** Is the harness process that will read this hook's stdout still running? */
+  sourceAlive(pid: number): boolean
+  resume(threadId: string, cwd: string, context: string): Promise<void>
+}
+
+/**
+ * The one cross-process oracle for "who owns this Codex thread".
+ *
+ * Codex's thread store takes a non-blocking `flock(LOCK_EX)` on a zero-byte
+ * file per thread and holds it for as long as that process owns the thread —
+ * verified against both a hosted app-server thread sitting idle and an
+ * in-process `codex exec` run (2026-08-12). Because the kernel holds it, a
+ * crash, SIGKILL, or reboot releases it instantly, and the leftover file proves
+ * nothing: only the lock does. Codex fails closed itself with `-32600` when a
+ * second writer contends, but that is the backstop; this is the gate.
+ */
+export function observeCodexThread(
+  threadId: string,
+  env: NodeJS.ProcessEnv,
+  adapters: Pick<CodexWakeAdapters, 'probeThreadWriter'>,
+): CodexWakeObservation {
+  if (!THREAD_ID.test(threadId)) {
+    return { state: 'unknown', reason: 'the Codex session id is not a thread id' }
+  }
+  try {
+    return adapters.probeThreadWriter(codexThreadLockPath(threadId, env))
+  } catch (err) {
+    return {
+      state: 'unknown',
+      reason: `Codex thread-writer lock probe failed: ${err instanceof Error ? err.message : String(err)}`,
+    }
+  }
+}
+
+export function codexThreadLockPath(threadId: string, env: NodeJS.ProcessEnv): string {
+  return path.join(codexThreadLockDirectory(env), `${threadId}.lock`)
+}
+
+export function codexThreadLockDirectory(env: NodeJS.ProcessEnv): string {
+  return path.join(configHome(env, 'CODEX_HOME', '.codex'), CODEX_THREAD_LOCK_DIR)
+}
+
+export type CodexResumeReadiness =
+  | { state: 'ready'; lockDirectory: string }
+  | { state: 'unavailable'; reason: string }
+
+/**
+ * Whether a Codex thread whose Stop hook has already returned could still be
+ * cold-resumed, decided without taking any lock or spawning anything.
+ *
+ * Two things have to hold: this platform must implement the non-blocking
+ * `flock` the probe is built on, and `$CODEX_HOME` must actually have a
+ * thread-writer-lock directory — its absence is not evidence that a thread is
+ * unowned, so the gate fails closed and the answer waits for the next turn.
+ * Neither affects the ordinary path, where the hook's own stdout continues the
+ * held turn.
+ */
+export function inspectCodexResume(
+  env: NodeJS.ProcessEnv,
+  options: { platform: NodeJS.Platform; directoryExists: (directory: string) => boolean },
+): CodexResumeReadiness {
+  const lockDirectory = codexThreadLockDirectory(env)
+  if (!LOCK_PROBE_PLATFORMS.has(options.platform)) {
+    return {
+      state: 'unavailable',
+      reason: `no non-blocking thread-writer lock probe exists on ${options.platform}`,
+    }
+  }
+  if (!options.directoryExists(lockDirectory)) {
+    return {
+      state: 'unavailable',
+      reason: `no thread-writer-lock directory at ${lockDirectory}, so no thread can be proven unowned`,
+    }
+  }
+  return { state: 'ready', lockDirectory }
+}
+
+/**
+ * Codex's answer-delivery route: the blocking Stop hook, then nothing else.
+ *
+ * The default is the hook continuation itself. While the Codex process that
+ * invoked this hook is alive it is reading this process's stdout, and
+ * `{"decision":"block"}` there creates a real new user turn — no launch
+ * ownership, no control plane, no probe required. That path must never depend
+ * on the lock probe: printing to a dead pipe cannot ghost-write anything, so
+ * an unreadable `$CODEX_HOME` is not a reason to withhold a continuation.
+ *
+ * Only when that process is gone does the answer need another last meter, and
+ * then exactly one is safe: a cold `codex exec resume` of a thread no live
+ * writer owns. Anything else — a live writer, an unprobeable platform, a thread
+ * id we cannot name — is journaled and replayed at the session's next Stop.
+ * That accepted gap is the honest floor of the Codex adapter: a session that
+ * went idle after its Stop returned, which Notifai did not launch, cannot be
+ * woken in place.
+ */
+export function codexWakeRoute(options: {
+  threadId: string
+  cwd: string
+  sourcePid: number
+  env?: NodeJS.ProcessEnv
+  adapters?: CodexWakeAdapters
+}): EscalationDeliveryRoute {
+  const env = options.env ?? process.env
+  const adapters = options.adapters ?? systemCodexWakeAdapters(env)
+  const continuation = hookContinuationRoute()
+  return {
+    kind: 'hook-continuation',
+    async deliver(event: ContinuationEvent): Promise<DeliveryOutcome> {
+      if (adapters.sourceAlive(options.sourcePid)) return continuation.deliver(event)
+
+      // Probe immediately before the spawn, twice, and never trust the earlier
+      // answer: ownership is a kernel fact that can change between two syscalls,
+      // and resuming a thread someone else owns is the disqualifying failure.
+      const observed = observeCodexThread(options.threadId, env, adapters)
+      const held = holdForNextTurn(observed)
+      if (held !== null) return held
+      const confirmed = observeCodexThread(options.threadId, env, adapters)
+      const raced = holdForNextTurn(confirmed)
+      if (raced !== null) return raced
+
+      await adapters.resume(options.threadId, options.cwd, event.context)
+      return {
+        notes: ['cold-resumed the stopped Codex thread with its accepted answer'],
+        log: { route: 'cold-resume', stage: 'delivered' },
+        // The resume ran: the thread holds the answer, and no later hook of this
+        // session will report on a turn that started elsewhere.
+        acknowledgement: 'delivered',
+      }
+    },
+  }
+}
+
+/** The journal, with the exact reason the thread could not be resumed. */
+function holdForNextTurn(observation: CodexWakeObservation): DeliveryOutcome | null {
+  if (observation.state === 'stopped') return null
+  const reason =
+    observation.state === 'live'
+      ? 'a live writer owns the Codex thread and this hook can no longer continue it'
+      : observation.reason
+  return {
+    notes: [`holding the accepted answer for the next turn: ${reason}`],
+    log: { route: 'hold-for-next-turn', stage: 'queued', reason },
+    acknowledgement: 'held',
+  }
+}
+
+/**
+ * Take and release the writer lock in one open/close pair.
+ *
+ * The probe momentarily owns the lock when it is free, so it is held for
+ * microseconds and never across a spawn — a probe racing a legitimate resume
+ * must not be what makes that resume fail.
+ */
+function probeThreadWriterLock(lockPath: string): CodexWakeObservation {
+  if (!LOCK_PROBE_PLATFORMS.has(process.platform)) {
+    return {
+      state: 'unknown',
+      reason: `no non-blocking thread-writer lock probe exists on ${process.platform}`,
+    }
+  }
+  const directory = path.dirname(lockPath)
+  if (!existsSync(directory)) {
+    // No lock directory means this is not a Codex home that has ever opened a
+    // thread, so its silence is not evidence that nothing owns this one.
+    return { state: 'unknown', reason: `no Codex thread-writer lock directory at ${directory}` }
+  }
+  let handle: number
+  try {
+    handle = openSync(lockPath, constants.O_RDONLY | O_EXLOCK | O_NONBLOCK)
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code
+    if (code === 'EAGAIN' || code === 'EWOULDBLOCK') return { state: 'live' }
+    // Codex unlinks the lock file when its writer drops cleanly, so a missing
+    // file inside a real lock directory means the thread has no owner.
+    if (code === 'ENOENT') return { state: 'stopped' }
+    return {
+      state: 'unknown',
+      reason: `Codex thread-writer lock probe failed: ${err instanceof Error ? err.message : String(err)}`,
+    }
+  }
+  closeSync(handle)
+  return { state: 'stopped' }
+}
+
+function runCodex(
+  args: string[],
+  options: { cwd: string; env: NodeJS.ProcessEnv },
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('codex', args, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    const stdout: Buffer[] = []
+    const stderr: Buffer[] = []
+    child.stdout?.on('data', (chunk: Buffer | string) => stdout.push(Buffer.from(chunk)))
+    child.stderr?.on('data', (chunk: Buffer | string) => stderr.push(Buffer.from(chunk)))
+    child.once('error', reject)
+    child.once('exit', (code, signal) => {
+      if (code === 0) {
+        resolve(Buffer.concat(stdout).toString())
+        return
+      }
+      reject(
+        new Error(
+          `codex ${args[0] ?? ''} exited ${code === null ? `on ${String(signal)}` : String(code)}: ${Buffer.concat(stderr).toString().trim()}`,
+        ),
+      )
+    })
+  })
+}
+
+/**
+ * The resumed process must not inherit the ended session's identity, or it
+ * reports itself as that thread to every hook it fires. `CODEX_HOME` is the one
+ * exception: it names the thread store the resume has to open.
+ */
+function coldResumeEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const next = { ...env }
+  for (const key of Object.keys(next)) {
+    if (key.startsWith('CODEX_') && key !== 'CODEX_HOME') delete next[key]
+  }
+  return next
+}
+
+export function systemCodexWakeAdapters(
+  env: NodeJS.ProcessEnv = process.env,
+): CodexWakeAdapters {
+  return {
+    probeThreadWriter: probeThreadWriterLock,
+    sourceAlive(pid) {
+      if (!Number.isInteger(pid) || pid <= 1) return false
+      try {
+        process.kill(pid, 0)
+        return true
+      } catch (err) {
+        // Signalling a process we may not touch still proves it exists.
+        return (err as NodeJS.ErrnoException).code === 'EPERM'
+      }
+    },
+    async resume(threadId, cwd, context) {
+      if (!existsSync(cwd)) throw new Error(`Codex thread cwd no longer exists: ${cwd}`)
+      await runCodex(['exec', 'resume', threadId, context], {
+        cwd,
+        env: coldResumeEnvironment(env),
+      })
+    },
+  }
+}