@alumbwe/anvil 1.0.0

package/src/__tests__/rerender-perf.integration.test.ts

@@ -0,0 +1,283 @@
+import { spawn } from 'child_process'
+import path from 'path'
+
+import { describe, test, expect, beforeAll } from 'bun:test'
+
+import {
+  isTmuxAvailable,
+  isSDKBuilt,
+  sleep,
+  ensureCliTestEnv,
+  getDefaultCliEnv,
+  parseRerenderLogs,
+  analyzeRerenders,
+  clearCliDebugLog,
+} from './test-utils'
+
+const CLI_PATH = path.join(__dirname, '../index.tsx')
+const DEBUG_LOG_PATH = path.join(__dirname, '../../../debug/cli.jsonl')
+const TIMEOUT_MS = 45000
+const tmuxAvailable = isTmuxAvailable()
+const sdkBuilt = isSDKBuilt()
+
+ensureCliTestEnv()
+
+/**
+ * Re-render performance thresholds.
+ * These values are based on observed behavior after optimization.
+ * If these thresholds are exceeded, it likely indicates a performance regression.
+ */
+const RERENDER_THRESHOLDS = {
+  /** Maximum total re-renders across all messages for a simple prompt */
+  maxTotalRerenders: 20,
+
+  /** Maximum re-renders for any single message */
+  maxRerenderPerMessage: 12,
+
+  /**
+   * Props that should NEVER appear in changedProps after memoization fixes.
+   * If these appear, it means callbacks are not properly memoized.
+   */
+  forbiddenChangedProps: [
+    'onOpenFeedback',
+    'onToggleCollapsed',
+    'onBuildFast',
+    'onBuildMax',
+    'onBuildLite',
+    'onCloseFeedback',
+  ],
+
+  /**
+   * Maximum times streamingAgents should appear in changedProps.
+   * After Set stabilization, this should be very low.
+   */
+  maxStreamingAgentChanges: 5,
+}
+
+// Utility to run tmux commands
+function tmux(args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('tmux', args, { stdio: 'pipe' })
+    let stdout = ''
+    let stderr = ''
+
+    proc.stdout?.on('data', (data) => {
+      stdout += data.toString()
+    })
+
+    proc.stderr?.on('data', (data) => {
+      stderr += data.toString()
+    })
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        resolve(stdout)
+      } else {
+        reject(new Error(`tmux command failed: ${stderr}`))
+      }
+    })
+  })
+}
+
+/**
+ * Send input to the CLI using bracketed paste mode.
+ * Standard send-keys doesn't work with OpenTUI - see tmux.knowledge.md
+ */
+async function sendCliInput(sessionName: string, text: string): Promise<void> {
+  await tmux([
+    'send-keys',
+    '-t',
+    sessionName,
+    '-l',
+    `\x1b[200~${text}\x1b[201~`,
+  ])
+}
+
+describe.skipIf(!tmuxAvailable || !sdkBuilt)(
+  'Re-render Performance Tests',
+  () => {
+    beforeAll(async () => {
+      if (!tmuxAvailable) {
+        console.log('\n⚠️  Skipping re-render perf tests - tmux not installed')
+        console.log(
+          '📦 Install with: brew install tmux (macOS) or sudo apt-get install tmux (Linux)\n',
+        )
+      }
+      if (!sdkBuilt) {
+        console.log('\n⚠️  Skipping re-render perf tests - SDK not built')
+        console.log('🔨 Build SDK: cd sdk && bun run build\n')
+      }
+      if (tmuxAvailable && sdkBuilt) {
+        const envVars = getDefaultCliEnv()
+        const entries = Object.entries(envVars)
+        // Propagate environment into tmux server
+        await Promise.all(
+          entries.map(([key, value]) =>
+            tmux(['set-environment', '-g', key, value]),
+          ),
+        )
+        // Enable performance testing
+        await tmux(['set-environment', '-g', 'ANVIL_PERF_TEST', 'true'])
+      }
+    })
+
+    test(
+      'MessageBlock re-renders stay within acceptable limits',
+      async () => {
+        const sessionName = 'anvil-perf-test-' + Date.now()
+
+        // Clear the debug log before test
+        clearCliDebugLog(DEBUG_LOG_PATH)
+
+        try {
+          // Start CLI with perf testing enabled
+          await tmux([
+            'new-session',
+            '-d',
+            '-s',
+            sessionName,
+            '-x',
+            '120',
+            '-y',
+            '30',
+            `ANVIL_PERF_TEST=true bun run ${CLI_PATH}`,
+          ])
+
+          // Wait for CLI to initialize
+          await sleep(5000)
+
+          // Send a simple prompt that will trigger streaming response
+          await sendCliInput(sessionName, 'what is 2+2')
+          await tmux(['send-keys', '-t', sessionName, 'Enter'])
+
+          // Wait for response to complete (longer wait for API response)
+          await sleep(15000)
+
+          // Parse and analyze the re-render logs
+          const entries = parseRerenderLogs(DEBUG_LOG_PATH)
+          const analysis = analyzeRerenders(entries)
+
+          // Log analysis for debugging
+          console.log('\n📊 Re-render Analysis:')
+          console.log(`   Total re-renders: ${analysis.totalRerenders}`)
+          console.log(`   Max per message: ${analysis.maxRerenderPerMessage}`)
+          console.log(
+            `   Messages tracked: ${analysis.rerendersByMessage.size}`,
+          )
+          if (analysis.propChangeFrequency.size > 0) {
+            console.log('   Prop change frequency:')
+            for (const [prop, count] of analysis.propChangeFrequency) {
+              console.log(`     - ${prop}: ${count}`)
+            }
+          }
+
+          // Assert total re-renders within threshold
+          expect(analysis.totalRerenders).toBeLessThanOrEqual(
+            RERENDER_THRESHOLDS.maxTotalRerenders,
+          )
+
+          // Assert max re-renders per message within threshold
+          expect(analysis.maxRerenderPerMessage).toBeLessThanOrEqual(
+            RERENDER_THRESHOLDS.maxRerenderPerMessage,
+          )
+
+          // Assert forbidden props don't appear (memoization check)
+          for (const forbiddenProp of RERENDER_THRESHOLDS.forbiddenChangedProps) {
+            const count = analysis.propChangeFrequency.get(forbiddenProp) || 0
+            if (count > 0) {
+              console.log(
+                `\n❌ Forbidden prop '${forbiddenProp}' changed ${count} times - callback not memoized!`,
+              )
+            }
+            expect(count).toBe(0)
+          }
+
+          // Assert streamingAgents changes within threshold
+          const streamingAgentChanges =
+            analysis.propChangeFrequency.get('streamingAgents') || 0
+          expect(streamingAgentChanges).toBeLessThanOrEqual(
+            RERENDER_THRESHOLDS.maxStreamingAgentChanges,
+          )
+
+          console.log('\n✅ Re-render performance within acceptable limits')
+        } finally {
+          // Cleanup tmux session
+          try {
+            await tmux(['kill-session', '-t', sessionName])
+          } catch {
+            // Session may have already exited
+          }
+        }
+      },
+      TIMEOUT_MS,
+    )
+
+    test(
+      'Forbidden callback props are properly memoized',
+      async () => {
+        const sessionName = 'anvil-memo-test-' + Date.now()
+
+        clearCliDebugLog(DEBUG_LOG_PATH)
+
+        try {
+          await tmux([
+            'new-session',
+            '-d',
+            '-s',
+            sessionName,
+            '-x',
+            '120',
+            '-y',
+            '30',
+            `ANVIL_PERF_TEST=true bun run ${CLI_PATH}`,
+          ])
+
+          await sleep(5000)
+
+          // Send multiple rapid prompts to stress test memoization
+          await sendCliInput(sessionName, 'hi')
+          await tmux(['send-keys', '-t', sessionName, 'Enter'])
+          await sleep(8000)
+
+          const entries = parseRerenderLogs(DEBUG_LOG_PATH)
+          const analysis = analyzeRerenders(entries)
+
+          // Check that none of the callback props appear in changed props
+          const forbiddenPropsFound: string[] = []
+          for (const prop of RERENDER_THRESHOLDS.forbiddenChangedProps) {
+            const count = analysis.propChangeFrequency.get(prop) || 0
+            if (count > 0) {
+              forbiddenPropsFound.push(`${prop} (${count}x)`)
+            }
+          }
+
+          if (forbiddenPropsFound.length > 0) {
+            console.log(
+              `\n❌ Unmemoized callbacks detected: ${forbiddenPropsFound.join(', ')}`,
+            )
+          }
+
+          expect(forbiddenPropsFound).toHaveLength(0)
+        } finally {
+          try {
+            await tmux(['kill-session', '-t', sessionName])
+          } catch {}
+        }
+      },
+      TIMEOUT_MS,
+    )
+  },
+)
+
+// Show helpful message when tests are skipped
+if (!tmuxAvailable) {
+  describe('Re-render Performance - tmux Required', () => {
+    test.skip('Install tmux for performance tests', () => {})
+  })
+}
+
+if (!sdkBuilt) {
+  describe('Re-render Performance - SDK Required', () => {
+    test.skip('Build SDK: cd sdk && bun run build', () => {})
+  })
+}

package/src/__tests__/terminal-reset-sequences.test.ts

@@ -0,0 +1,36 @@
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+import { describe, expect, test } from 'bun:test'
+
+import { TERMINAL_RESET_SEQUENCES } from '../utils/terminal-reset-sequences'
+
+/**
+ * The npm wrapper release scripts are standalone published JS that can't
+ * import the TS constant, so each carries its own copy of the reset
+ * sequences (split into EXIT_ALTERNATE_SCREEN_SEQUENCE +
+ * SAFE_TERMINAL_RESET_SEQUENCES). This guard turns silent drift into a test
+ * failure: every sequence in the TS constant must appear in the standalone
+ * launcher source bundled into each release package.
+ */
+const REPO_ROOT = join(import.meta.dir, '..', '..', '..')
+
+const WRAPPER_PATHS = ['cli/release-core/launcher.js']
+
+/** Split the runtime constant into per-sequence source literals ('\x1b…'). */
+function sequenceSourceLiterals(): string[] {
+  return TERMINAL_RESET_SEQUENCES.split('\x1b')
+    .filter(Boolean)
+    .map((rest) => `'\\x1b${rest}'`)
+}
+
+describe('terminal reset sequence copies stay in sync', () => {
+  for (const wrapperPath of WRAPPER_PATHS) {
+    test(wrapperPath, () => {
+      const source = readFileSync(join(REPO_ROOT, wrapperPath), 'utf8')
+      for (const literal of sequenceSourceLiterals()) {
+        expect(source).toContain(literal)
+      }
+    })
+  }
+})

package/src/__tests__/terminal-watchdog.test.ts

@@ -0,0 +1,388 @@
+import { spawn } from 'child_process'
+import { mkdtempSync, readdirSync, readFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+
+import { TERMINAL_RESET_SEQUENCES } from '../utils/terminal-reset-sequences'
+import { classifyTerminalWatchdogSpawnFailure } from '../utils/terminal-watchdog'
+import { sanitizeWindowsCliVersion } from '../utils/windows-terminal-health'
+
+import type { ChildProcess } from 'child_process'
+
+const IS_WINDOWS = process.platform === 'win32'
+const FIXTURE = join(import.meta.dir, 'helpers', 'terminal-watchdog-fixture.ts')
+const tempDir = mkdtempSync(join(tmpdir(), 'terminal-watchdog-'))
+
+afterAll(() => {
+  rmSync(tempDir, { recursive: true, force: true })
+})
+
+// Every fixture is spawned at once and killed at once, so these are one shared
+// budget for the whole file instead of a per-test cost. Windows pays for two
+// PowerShell hops (bootstrap + out-of-job watchdog) on a runner that is often
+// busy scanning them, hence the wide margin there.
+//
+// Ready is longer than the fixture's own arm deadline on purpose, so the
+// fixture is what reports a failure to arm (it names the marker it waited on);
+// this is only the backstop for a fixture that never speaks at all.
+const READY_TIMEOUT_MS = IS_WINDOWS ? 60_000 : 15_000
+const WRITE_TIMEOUT_MS = IS_WINDOWS ? 45_000 : 15_000
+const DISARM_TIMEOUT_MS = 10_000
+// "close" waits on the stdio pipes as well as the exit; this bounds that wait.
+const DRAIN_TIMEOUT_MS = 2_000
+// Ceiling on the settle described in beforeAll, so one slow control write can't
+// stretch the run.
+const MAX_SETTLE_MS = 5_000
+// Must exceed the sum of the waits above: a hook that times out takes the whole
+// describe down as one "(unnamed)" failure and stops the rest of the file from
+// running, which reads as deleted tests to scripts/ci/test-with-guard.ts.
+const SETUP_TIMEOUT_MS = IS_WINDOWS ? 150_000 : 60_000
+
+type Scenario = {
+  key: string
+  mode: 'hang' | 'clean' | 'spawn-failure'
+  env?: Record<string, string>
+  /** "hang" fixtures wait to be SIGKILLed; the others exit on their own. */
+  kill: boolean
+  /** Whether an armed watchdog should write the reset payload after death. */
+  expectWrite: boolean
+}
+
+const OPT_OUT_VALUES = ['1', 'true', 'TRUE']
+
+// POSIX uses a detached sh blocking on pipe EOF. Windows uses a PowerShell
+// grandchild (outside Bun's kill-on-close job object) blocking on Wait-Process.
+// Both then write the reset sequences to ttyPath.
+const SCENARIOS: Scenario[] = [
+  { key: 'unclean', mode: 'hang', kill: true, expectWrite: true },
+  // The Windows arm path spawns a PowerShell bootstrap that Start-Process's a
+  // second, longer-lived PowerShell — a shape EDR/AV scores as malicious. The
+  // opt-out lets an affected user keep running the CLI at the cost of the
+  // after-exit terminal repair, so "no watchdog at all" has to actually hold.
+  ...OPT_OUT_VALUES.map((value): Scenario => ({
+    key: `optout-${value}`,
+    mode: 'hang',
+    env: { ANVIL_NO_TERMINAL_WATCHDOG: value },
+    kill: true,
+    expectWrite: false,
+  })),
+  {
+    key: 'optout-noise',
+    mode: 'hang',
+    env: { ANVIL_NO_TERMINAL_WATCHDOG: '0' },
+    kill: true,
+    expectWrite: true,
+  },
+  { key: 'clean', mode: 'clean', kill: false, expectWrite: false },
+  // The PowerShell spawn-failure path only exists on Windows.
+  ...(IS_WINDOWS
+    ? [
+        {
+          key: 'spawn-failure',
+          mode: 'spawn-failure' as const,
+          kill: false,
+          expectWrite: false,
+        },
+      ]
+    : []),
+]
+
+type Run = {
+  scenario: Scenario
+  child: ChildProcess
+  pid: number | undefined
+  ttyPath: string
+  ready: boolean
+  stderr: string
+  exitCode: number | null
+  signal: NodeJS.Signals | null
+  /** Snapshotted once, after the barriers in beforeAll. */
+  content: string
+  disarmFiles: string[]
+  readyPromise: Promise<void>
+  closePromise: Promise<void>
+}
+
+function readTty(ttyPath: string): string {
+  try {
+    return readFileSync(ttyPath, 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+function listTmp(): string[] {
+  try {
+    return readdirSync(tmpdir())
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Disarm files a fixture left in the temp dir (Windows watchdog only; POSIX
+ * never creates one). Named anvil-watchdog-disarm-<pid>-<random>.
+ */
+function findDisarmFiles(pid: number | undefined, names = listTmp()): string[] {
+  return names.filter((name) =>
+    name.startsWith(`anvil-watchdog-disarm-${pid}-`),
+  )
+}
+
+async function waitUntil(
+  condition: () => boolean,
+  timeoutMs: number,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    if (condition()) return true
+    await new Promise((r) => setTimeout(r, 50))
+  }
+  return condition()
+}
+
+function startRun(scenario: Scenario, index: number): Run {
+  // Indexed because the keys are not unique on a case-insensitive filesystem:
+  // the "true" and "TRUE" opt-out variants would otherwise share one file (and
+  // one `.armed` marker) now that every fixture runs at the same time.
+  const ttyPath = join(tempDir, `${index}-${scenario.key}.out`)
+  const childEnv = { ...process.env }
+  delete childEnv.ANVIL_NO_TERMINAL_WATCHDOG
+  const child = spawn(process.execPath, [FIXTURE, scenario.mode, ttyPath], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...childEnv, ...scenario.env },
+  })
+
+  const run: Run = {
+    scenario,
+    child,
+    pid: child.pid,
+    ttyPath,
+    ready: false,
+    stderr: '',
+    exitCode: null,
+    signal: null,
+    content: '',
+    disarmFiles: [],
+    // Replaced below; the promise bodies need `run` to record into.
+    readyPromise: Promise.resolve(),
+    closePromise: Promise.resolve(),
+  }
+
+  child.stderr!.on('data', (chunk: Buffer) => {
+    run.stderr += chunk.toString()
+  })
+
+  // Prefer "close" over "exit" so the fixture's stdout/stderr are fully
+  // drained — a fixture that prints and exits immediately would otherwise lose
+  // them. "close" additionally waits on the stdio pipes, though, so fall back
+  // to "exit" on a timer: no watchdog inherits these pipes today (the POSIX one
+  // gets the tty fd, the Windows bootstrap gets all-ignore), but a future one
+  // that did would hang this hook, and a hung hook takes the describe with it.
+  run.closePromise = new Promise<void>((resolve) => {
+    child.on('exit', (code, signal) => {
+      run.exitCode = code
+      run.signal = signal
+      const drain = setTimeout(resolve, DRAIN_TIMEOUT_MS)
+      ;(drain as { unref?: () => void }).unref?.()
+      child.on('close', () => {
+        clearTimeout(drain)
+        resolve()
+      })
+    })
+    child.on('error', (error) => {
+      run.stderr += `spawn error: ${error.message}\n`
+      resolve()
+    })
+  })
+
+  /** Resolves once the fixture prints "ready" (watchdog policy applied). */
+  run.readyPromise = new Promise<void>((resolve) => {
+    let out = ''
+    const timer = setTimeout(resolve, READY_TIMEOUT_MS)
+    ;(timer as { unref?: () => void }).unref?.()
+    const finish = () => {
+      clearTimeout(timer)
+      resolve()
+    }
+    child.stdout!.on('data', (chunk: Buffer) => {
+      out += chunk.toString()
+      if (out.includes('ready')) {
+        run.ready = true
+        finish()
+      }
+    })
+    // "clean"/"spawn-failure" exit on their own; a fixture that died before
+    // arming also lands here, with ready left false for the diagnostics dump.
+    run.closePromise.then(finish)
+  })
+
+  return run
+}
+
+/**
+ * Whether a run wrote what its scenario called for. "spawn-failure" is the one
+ * scenario that legitimately writes something other than the reset payload (a
+ * JSON failure report), so it is only checked for having said anything at all.
+ */
+function matchesExpectation(run: Run): boolean {
+  if (run.scenario.expectWrite) return run.content === TERMINAL_RESET_SEQUENCES
+  if (run.scenario.mode === 'spawn-failure') return run.content !== ''
+  return run.content === '' && run.ready
+}
+
+function describeRun(run: Run): string {
+  const content = run.content
+  const shape =
+    content === TERMINAL_RESET_SEQUENCES
+      ? 'reset-sequences'
+      : content === ''
+        ? 'empty'
+        : `${content.length} bytes: ${JSON.stringify(content.slice(0, 120))}`
+  return [
+    `  ${run.scenario.key}: ready=${run.ready} exit=${run.exitCode} signal=${run.signal}`,
+    `    wrote: ${shape}`,
+    `    disarm files: ${JSON.stringify(run.disarmFiles)}`,
+    run.stderr.trim() ? `    stderr: ${run.stderr.trim()}` : null,
+  ]
+    .filter(Boolean)
+    .join('\n')
+}
+
+let runs: Run[] = []
+const runFor = (key: string): Run => {
+  const run = runs.find((r) => r.scenario.key === key)
+  if (!run) throw new Error(`no run recorded for scenario ${key}`)
+  return run
+}
+
+describe('terminal watchdog', () => {
+  test('bounds watchdog failure telemetry labels', () => {
+    expect(
+      classifyTerminalWatchdogSpawnFailure(
+        Object.assign(new Error('private path'), { code: 'ENOENT' }),
+      ),
+    ).toBe('enoent')
+    expect(
+      classifyTerminalWatchdogSpawnFailure(new Error('private text')),
+    ).toBe('unknown')
+    expect(sanitizeWindowsCliVersion('0.0.142')).toBe('0.0.142')
+    expect(sanitizeWindowsCliVersion('private/path')).toBe('unknown')
+  })
+})
+
+// Each scenario needs a real process to arm a real watchdog and then die, so
+// they all run at once and every test below asserts on the same snapshot:
+// wall clock is one fixture's cost, not the sum. Nothing here throws — a wait
+// that times out still snapshots, so the failing assertion names the scenario.
+describe('terminal watchdog (fixture processes)', () => {
+  beforeAll(async () => {
+    runs = SCENARIOS.map(startRun)
+    await Promise.all(runs.map((run) => run.readyPromise))
+
+    const killedAt = Date.now()
+    for (const run of runs) {
+      if (run.scenario.kill) run.child.kill('SIGKILL')
+    }
+    await Promise.all(runs.map((run) => run.closePromise))
+
+    // The scenarios that SHOULD write double as the clock for the ones that
+    // should not: once an armed watchdog has fired, a watchdog that was never
+    // armed has had at least as long to (incorrectly) fire. That beats a fixed
+    // sleep in both directions — it can't pass for the wrong reason on a slow
+    // runner, and it doesn't burn seconds on a fast one.
+    const writers = runs.filter((run) => run.scenario.expectWrite)
+    // A fixture that never printed "ready" never armed a watchdog (on Windows
+    // it gives up on the arm marker and exits non-zero), so there is nothing
+    // left to wait for — skip straight to the diagnostics rather than burning
+    // the full write budget on a run that has already lost.
+    if (writers.every((run) => run.ready)) {
+      const wrote = await waitUntil(
+        () =>
+          writers.every(
+            (run) => readTty(run.ttyPath) === TERMINAL_RESET_SEQUENCES,
+          ),
+        WRITE_TIMEOUT_MS,
+      )
+      // The control's write only proves the pipeline ran to the 50ms polling
+      // granularity, and a wrongly-armed watchdog wakes on the same death but
+      // need not win that race. Give it twice the latency the control just
+      // demonstrated — self-scaling, unlike the fixed sleep this replaced.
+      if (wrote) {
+        const settle = Math.min(
+          Math.max(250, 2 * (Date.now() - killedAt)),
+          MAX_SETTLE_MS,
+        )
+        await new Promise((r) => setTimeout(r, settle))
+      }
+    }
+    // Windows only: a disarmed watchdog deletes its disarm file when it wakes,
+    // which is the strongest available proof that it woke and chose silence.
+    await waitUntil(() => {
+      const names = listTmp()
+      return runs.every((run) => findDisarmFiles(run.pid, names).length === 0)
+    }, DISARM_TIMEOUT_MS)
+
+    const names = listTmp()
+    for (const run of runs) {
+      run.content = readTty(run.ttyPath)
+      run.disarmFiles = findDisarmFiles(run.pid, names)
+    }
+
+    // A missing write is the historical flake here, and a spurious one is the
+    // regression the opt-out scenarios exist to catch. Either way, dump every
+    // fixture's state so the CI log says which hop failed instead of just
+    // "expected reset sequences, got empty string".
+    if (runs.some((run) => !matchesExpectation(run))) {
+      console.error(
+        `terminal watchdog fixtures did not behave as expected:\n${runs
+          .map(describeRun)
+          .join('\n')}`,
+      )
+    }
+  }, SETUP_TIMEOUT_MS)
+
+  test('writes reset sequences to the tty when the process dies uncleanly', () => {
+    expect(runFor('unclean').ready).toBe(true)
+    expect(runFor('unclean').content).toBe(TERMINAL_RESET_SEQUENCES)
+  })
+
+  test.each(OPT_OUT_VALUES)(
+    'never arms when ANVIL_NO_TERMINAL_WATCHDOG=%s',
+    (value) => {
+      const run = runFor(`optout-${value}`)
+      expect(run.ready).toBe(true)
+      expect(run.content).toBe('')
+      expect(run.disarmFiles).toEqual([])
+    },
+  )
+
+  test('still arms when the opt-out is set to an unrelated value', () => {
+    expect(runFor('optout-noise').ready).toBe(true)
+    expect(runFor('optout-noise').content).toBe(TERMINAL_RESET_SEQUENCES)
+  })
+
+  test('stays silent when the process shuts down cleanly', () => {
+    const run = runFor('clean')
+    expect(run.exitCode).toBe(0)
+    expect(run.content).toBe('')
+    // The watchdog consumes (deletes) the disarm file when it wakes, so clean
+    // exits must not litter the temp dir.
+    expect(run.disarmFiles).toEqual([])
+  })
+
+  test.skipIf(!IS_WINDOWS)(
+    'reports a bounded failure when PowerShell cannot spawn',
+    () => {
+      const run = runFor('spawn-failure')
+      expect(run.exitCode).toBe(0)
+      expect(JSON.parse(run.content)).toEqual({
+        stage: 'spawn',
+        failureCode: 'enoent',
+      })
+      expect(run.disarmFiles).toEqual([])
+    },
+  )
+})