@raidiant/notifai 0.3.0 → 0.5.0

package/src/config-schema.test.ts

@@ -73,14 +73,14 @@ describe('acceptedValues', () => {
   })
 
   it('names both values for a toggle', () => {
-    expect(acceptedValues('require_idle')).toBe('true or false')
+    expect(acceptedValues('ask_notifications')).toBe('true or false')
   })
 })
 
 describe('formatValue', () => {
   it('renders toggles as words rather than JSON', () => {
-    expect(formatValue('require_idle', true)).toBe('yes')
-    expect(formatValue('require_idle', false)).toBe('no')
+    expect(formatValue('ask_notifications', true)).toBe('yes')
+    expect(formatValue('ask_notifications', false)).toBe('no')
   })
 
   it('explains what an unset value means instead of printing null', () => {

package/src/config-schema.ts

@@ -1,11 +1,11 @@
 /**
  * What every configuration key means, in the reader's words.
  *
- * `config.ts` already documented all fourteen keys carefully — but in TypeScript
+ * `config.ts` already documented every key carefully — but in TypeScript
  * comments, which is the one audience that never needed them. Someone running
- * `notifai config show` saw `require_idle = true` and had no way to learn what
- * it did short of reading the source, so this module is that knowledge moved to
- * where it can be printed.
+ * `notifai config show` saw `ask_grace_seconds = 0` and had no way to learn
+ * what it did short of reading the source, so this module is that knowledge
+ * moved to where it can be printed.
  *
  * It is the single source for `config show`, `config set`'s errors, `config
  * explain`, the help footer, and the interactive settings screen. One
@@ -13,25 +13,25 @@
  *
  * `summary` is the one-line form that fits beside a value in a list.
  * `detail` is the paragraph shown once the reader has asked for this key
- * specifically — progressive disclosure, so a list of fourteen settings stays
- * a list and not an essay.
+ * specifically — progressive disclosure, so the list of settings stays a list
+ * and not an essay.
  */
 import { CLI_SOUNDS, INTERRUPTION_LEVELS } from '@raidiant/notifai-protocol'
-import { configBounds, type ConfigKey } from './config.js'
+import { LOG_LEVELS, configBounds, type ConfigKey } from './config.js'
 
 export type ConfigKind = 'string' | 'url' | 'integer' | 'boolean' | 'enum' | 'list'
 
 /**
- * Which surface a key belongs to. Grouping is the difference between fourteen
- * flat keys and four short lists a reader can hold in their head.
+ * Which surface a key belongs to. Grouping is the difference between a flat
+ * list of keys and a few short ones a reader can hold in their head.
  */
-export type ConfigGroup = 'questions' | 'delivery' | 'project' | 'connection'
+export type ConfigGroup = 'questions' | 'delivery' | 'project' | 'diagnostics' | 'connection'
 
 export const CONFIG_GROUPS: { id: ConfigGroup; title: string; blurb: string }[] = [
   {
     id: 'questions',
-    title: 'Questions & presence',
-    blurb: 'When a question an agent registered is allowed to leave this terminal and reach your devices.',
+    title: 'Questions',
+    blurb: 'Whether a question an agent registered may leave this terminal and reach your devices, and how soon.',
   },
   {
     id: 'delivery',
@@ -43,6 +43,11 @@ export const CONFIG_GROUPS: { id: ConfigGroup; title: string; blurb: string }[]
     title: 'This project',
     blurb: 'How work in this directory identifies itself, and the house rules agents read before notifying.',
   },
+  {
+    id: 'diagnostics',
+    title: 'Local logs',
+    blurb: 'What this machine records about its own activity, so an agent can find out afterwards what happened.',
+  },
   {
     id: 'connection',
     title: 'Connection',
@@ -88,44 +93,15 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
       'The master switch for question routing. When this is off, a question an agent registers with `notifai ask` stays in the terminal and never leaves this machine, whatever the presence settings say. Turn it off to stop being reached for a while without uninstalling the harness hooks.',
     example: 'true',
   },
-  require_idle: {
-    label: 'Only when I have stepped away',
-    group: 'questions',
-    kind: 'boolean',
-    summary: 'Whether sitting at this keyboard holds a question back',
-    detail:
-      'On (the default), a question waits while you are using this machine, because you are right there and a push would be redundant. Off means notify me anyway — `ask_grace_seconds` still runs, so the terminal is still offered the question first; it just no longer needs you to walk away before it may leave.\n\nThis is separate from `ask_notifications`, which switches routing off altogether: wanting to be reached while working is the opposite of not wanting to be reached.',
-    example: 'true',
-  },
-  away_after_seconds: {
-    label: 'Away after',
-    group: 'questions',
-    kind: 'integer',
-    unit: 's',
-    summary: 'Keyboard and mouse idle time before this machine counts as unattended',
-    detail:
-      'How long the keyboard and mouse must be quiet before you count as away. Only consulted while `require_idle` is on.\n\nWhere the operating system exposes no idle signal, silence since your last prompt is used instead, which is the conservative reading.',
-    example: '120',
-  },
   ask_grace_seconds: {
     label: 'Terminal-first grace',
     group: 'questions',
     kind: 'integer',
     unit: 's',
-    summary: 'How long a question stays terminal-only before it may reach your devices',
+    summary: 'Optional delay before a question may reach your devices',
     detail:
-      'Measured from the moment the agent asked. The question appears in the terminal and a timer starts; only once it elapses may the question go to your devices.\n\nA timer and nothing more. It is honoured whether or not presence is consulted at all, because how long to wait and whether anyone is watching are separate questions, and answering one should not answer the other.',
-    example: '300',
-  },
-  hook_reply_timeout_seconds: {
-    label: 'Hook wait for an answer',
-    group: 'questions',
-    kind: 'integer',
-    unit: 's',
-    summary: 'How long the harness hook blocks waiting for your answer',
-    detail:
-      'After a question has gone out, the harness hook holds the agent for up to this long waiting for your answer before falling through to the harness\'s own prompt.\n\nThe ceiling exists because both Claude Code and Codex kill a command hook at 600 seconds. Grace plus this value plus the installer\'s headroom has to stay under that, or the hook is killed mid-wait — after you have already answered.',
-    example: '180',
+      'Zero (the default) sends the question to your devices as soon as the agent turn ends. Set a positive duration to offer the terminal an exclusive answer window first; the timer is measured from the moment the agent asked.\n\nA timer and nothing more. Whether you happen to be at this keyboard does not change it: waiting no longer holds your terminal, so there is nothing your being here would protect you from.',
+    example: '0',
   },
 
   sound: {
@@ -222,6 +198,43 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     example: 'Only failures and completed deploys',
   },
 
+  log_level: {
+    label: 'Log level',
+    group: 'diagnostics',
+    kind: 'enum',
+    choices: LOG_LEVELS,
+    choiceHints: {
+      off: 'record nothing',
+      error: 'only failures',
+      info: 'commands, notifications, and every question decision',
+      debug: 'adds config resolution and per-request detail',
+    },
+    summary: 'How much this machine records about what it did',
+    detail:
+      'Notifai keeps a local record of what it did — every command, every notification, and in particular every decision a harness hook made about whether a question could leave the terminal. Hooks run headless, so without this there is no account of them at all: `notifai logs` is how an agent finds out afterwards why a question never reached your phone.\n\nThe log never leaves this machine. It is not uploaded, and nothing sends it anywhere.\n\n`debug` also records which config layer won and the detail of each request, which is what to turn on when something is behaving in a way the ordinary log does not explain.',
+    example: 'info',
+  },
+  log_max_bytes: {
+    label: 'Log file size',
+    group: 'diagnostics',
+    kind: 'integer',
+    summary: 'How large the log grows before it is rotated',
+    detail:
+      'When the active log reaches this size it is renamed aside and a fresh one starts. Together with the number of files kept, this is the whole disk budget: nothing here grows without a ceiling.',
+    advanced: true,
+    example: '2000000',
+  },
+  log_max_files: {
+    label: 'Log files kept',
+    group: 'diagnostics',
+    kind: 'integer',
+    summary: 'How many rotated log files are kept before the oldest is deleted',
+    detail:
+      'Counts the active file. At the defaults — three files of two megabytes — the logs occupy about six megabytes, which is weeks of ordinary agent traffic.\n\nRaise it when you need to look further back than the log currently reaches; lower it to one to keep only the file being written.',
+    advanced: true,
+    example: '3',
+  },
+
   base_url: {
     label: 'Service URL',
     group: 'connection',

package/src/config.test.ts

@@ -45,22 +45,22 @@ function setup(options: {
 describe('harness config layers', () => {
   it('orders session over project-local over project over global', () => {
     const { env, cwd } = setup({
-      globalToml: 'away_after_seconds = 10\n',
-      projectToml: 'away_after_seconds = 20\n',
-      projectLocalToml: 'away_after_seconds = 30\n',
-      sessionToml: 'away_after_seconds = 40\n',
+      globalToml: 'ask_grace_seconds = 10\n',
+      projectToml: 'ask_grace_seconds = 20\n',
+      projectLocalToml: 'ask_grace_seconds = 30\n',
+      sessionToml: 'ask_grace_seconds = 40\n',
       sessionId: 'abc',
     })
-    expect(loadConfig({ cwd, env, sessionId: 'abc' }).away_after_seconds).toMatchObject({
+    expect(loadConfig({ cwd, env, sessionId: 'abc' }).ask_grace_seconds).toMatchObject({
       value: 40,
       source: expect.stringMatching(/^session:/),
     })
     // Same files, different session: the session layer simply does not apply.
-    expect(loadConfig({ cwd, env, sessionId: 'other' }).away_after_seconds).toMatchObject({
+    expect(loadConfig({ cwd, env, sessionId: 'other' }).ask_grace_seconds).toMatchObject({
       value: 30,
       source: expect.stringMatching(/^project-local:/),
     })
-    expect(loadConfig({ cwd, env }).away_after_seconds.value).toBe(30)
+    expect(loadConfig({ cwd, env }).ask_grace_seconds.value).toBe(30)
   })
 
   it('keeps a personal toggle out of the committed project file', () => {
@@ -75,28 +75,34 @@ describe('harness config layers', () => {
 
   it('keeps hostile or colliding session ids inside their own file', () => {
     const { env, cwd } = setup({
-      sessionToml: 'away_after_seconds = 99\n',
+      sessionToml: 'ask_grace_seconds = 99\n',
       sessionId: '../../etc/passwd',
     })
     // The id round-trips to its own state, and nothing escapes the directory.
-    expect(loadConfig({ cwd, env, sessionId: '../../etc/passwd' }).away_after_seconds.value).toBe(99)
+    expect(loadConfig({ cwd, env, sessionId: '../../etc/passwd' }).ask_grace_seconds.value).toBe(99)
     expect(sessionConfigPath('../../etc/passwd', env)).toContain('/notifai/sessions/')
     expect(sessionConfigPath('../../etc/passwd', env)).not.toContain('..')
     // Ids that a sanitiser would have collapsed together must stay distinct:
     // sharing a file meant sharing presence and pending questions.
     expect(sessionConfigPath('a/b', env)).not.toBe(sessionConfigPath('a?b', env))
-    expect(loadConfig({ cwd, env, sessionId: 'a/b' }).away_after_seconds.value).toBe(120)
+    expect(loadConfig({ cwd, env, sessionId: 'a/b' }).ask_grace_seconds.value).toBe(0)
   })
 
-  it('defaults the hook behaviour to on, gated by the presence check rather than a flag', () => {
+  it('defaults question routing to on and reaching the user straight away', () => {
     const { env, cwd } = setup({})
     const config = loadConfig({ cwd, env })
     expect(config.ask_notifications.value).toBe(true)
-    expect(config.away_after_seconds.value).toBe(120)
-    // 300 grace + 180 reply + 60 installer headroom = 540, inside the 600s
-    // ceiling both harnesses kill a command hook at.
-    expect(config.hook_reply_timeout_seconds.value).toBe(180)
-    expect(config.ask_grace_seconds.value).toBe(300)
+    // Nothing here asks where the user is standing. A question goes out when
+    // the turn ends unless they choose a terminal-first window.
+    expect(config.ask_grace_seconds).toEqual({ value: 0, source: 'default' })
+  })
+
+  it('bounds the terminal-first window so a reply window always survives it', () => {
+    // Config is readable from a repository, so an unbounded grace is hostile
+    // input: it would eat the waiter's whole ceiling and leave no window the
+    // server would accept an answer into.
+    const { env, cwd } = setup({ globalToml: 'ask_grace_seconds = 100000\n' })
+    expect(loadConfig({ cwd, env }).ask_grace_seconds.value).toBe(360)
   })
 })
 

package/src/config.ts

@@ -39,6 +39,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>
@@ -51,51 +59,36 @@ export interface CliConfig {
   project: ResolvedValue<string | null>
   /** Free-text notification criteria agents consult before sending. */
   notify_criteria: ResolvedValue<string | null>
-  /** Route a registered agent question to companion devices after the presence gate. */
+  /** Whether a registered agent question may reach companion devices at all. */
   ask_notifications: ResolvedValue<boolean>
   /**
-   * Whether being at this machine suppresses a question. Sitting at the
-   * keyboard is not the same as not wanting to be reached — needing to stop
-   * using the machine in order to be notified is its own kind of interruption.
-   *
-   * On, the default, is the original behaviour: a question stays in the
-   * terminal while the keyboard is in use, because the person is right there
-   * and a push would be redundant. Off says notify me anyway — the grace window
-   * still runs, so the question is still offered to the terminal first, it just
-   * no longer needs the user to walk away before it may leave.
+   * Terminal-first grace window, measured from the moment the question was
+   * sent: the agent asks in the terminal and starts a timer, and only once it
+   * elapses does the question reach companion devices.
    *
-   * This is deliberately separate from `ask_notifications`, which switches
-   * escalation off altogether. Wanting to be reached while working is the
-   * opposite of not wanting to be reached.
+   * A timer, and only a timer. Whether the user happens to be at this keyboard
+   * decides nothing — the waiter no longer holds their terminal, so there is
+   * nothing for their presence to protect them from.
    */
-  require_idle: ResolvedValue<boolean>
+  ask_grace_seconds: ResolvedValue<number>
   /**
-   * Keyboard/mouse idle time after which this machine counts as unattended.
-   * When the OS idle signal is unavailable, silence since the user's last prompt
-   * is the conservative fallback. Below the threshold the hooks stay out of the
-   * way entirely, because a blocking hook also blocks the terminal prompt the
-   * present user would use.
+   * How much of what this CLI does is recorded to the local log.
    *
-   * Only consulted while `require_idle` is on.
+   * 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.
    */
-  away_after_seconds: ResolvedValue<number>
+  log_level: ResolvedValue<LogLevel>
   /**
-   * 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.
+   * 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.
    */
-  hook_reply_timeout_seconds: ResolvedValue<number>
-  /**
-   * Terminal-first grace window, measured from the moment the question was
-   * sent: the agent asks in the terminal and starts a timer, and only once it
-   * elapses does the question reach companion devices.
-   *
-   * A timer, and only a timer. It is configured independently of
-   * `away_after_seconds` and honoured whether or not presence is consulted at
-   * all — how long to wait and whether anyone is watching are separate
-   * questions, and answering one should not answer the other.
-   */
-  ask_grace_seconds: ResolvedValue<number>
+  log_max_bytes: ResolvedValue<number>
+  /** Log files kept in total, the active one included. */
+  log_max_files: ResolvedValue<number>
 }
 
 export const CONFIG_KEYS = [
@@ -109,28 +102,36 @@ export const CONFIG_KEYS = [
   'project',
   'notify_criteria',
   'ask_notifications',
-  'require_idle',
-  '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]
 
 /** Keys whose TOML value must parse as a boolean; used by `config set`. */
-export const BOOLEAN_CONFIG_KEYS: readonly ConfigKey[] = [
-  'ask_notifications',
-  'require_idle',
-]
+export const BOOLEAN_CONFIG_KEYS: readonly ConfigKey[] = ['ask_notifications']
 
 /** Keys whose TOML value must parse as an integer within its configured bounds. */
 export const NUMERIC_CONFIG_KEYS: readonly ConfigKey[] = [
   'wait_seconds',
   'ttl_seconds',
-  '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 +145,23 @@ 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,
-  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,
+  // 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,
+  // 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')
@@ -243,19 +250,23 @@ 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.
+ * out-of-range value is attacker input, not a typo: an unbounded grace window
+ * would consume the waiter's whole ceiling and silently leave no time at all in
+ * which the user's answer could still be accepted.
  */
 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 },
+  // A plain number, no longer derived from a hook budget's leftovers. Six
+  // minutes leaves two clear minutes of the waiter's 480s ceiling, so the
+  // 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 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 +277,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
 }
 
@@ -339,9 +354,9 @@ export function loadConfig(options: {
     project: resolve('project'),
     notify_criteria: resolve('notify_criteria'),
     ask_notifications: resolve('ask_notifications'),
-    require_idle: resolve('require_idle'),
-    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)
+    })
+  })
+}