@tjamescouch/niki 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 James Couch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/niki

@@ -19,8 +19,8 @@
  *   - Diagnostics only contain counters, never message content
  */
 
-import { spawn } from 'node:child_process';
-import { createWriteStream, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { spawn, execSync } from 'node:child_process';
+import { createWriteStream, writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 
@@ -37,6 +37,10 @@ Options:
   --timeout <seconds>     Max wall-clock runtime before SIGTERM (default: 3600)
   --max-sends <n>         Max agentchat_send calls per minute (default: 10)
   --max-tool-calls <n>    Max total tool calls per minute (default: 30)
+  --stall-timeout <secs>  Kill after N seconds of no output (default: 60, 0=disabled)
+  --startup-timeout <s>   Longer stall timeout until first output (default: 180, 0=use stall-timeout)
+  --dead-air-timeout <m>  Minutes of zero CPU + zero output before kill (default: 5, 0=disabled)
+  --max-nudges <n>        Max stdin nudge attempts before kill on stall (default: 3)
   --log <file>            Write diagnostics log to file
   --state <file>          Write state JSON on exit (budget used, reason, etc.)
   --cooldown <seconds>    Grace period after SIGTERM before SIGKILL (default: 5)
@@ -60,6 +64,10 @@ const { values: opts } = parseArgs({
     timeout:         { type: 'string', default: '3600' },
     'max-sends':     { type: 'string', default: '10' },
     'max-tool-calls': { type: 'string', default: '30' },
+    'stall-timeout': { type: 'string', default: '60' },
+    'startup-timeout': { type: 'string', default: '180' },
+    'dead-air-timeout': { type: 'string', default: '5' },
+    'max-nudges':    { type: 'string', default: '3' },
     log:             { type: 'string' },
     state:           { type: 'string' },
     cooldown:        { type: 'string', default: '5' },
@@ -72,6 +80,10 @@ const BUDGET        = parseInt(opts.budget, 10);
 const TIMEOUT_S     = parseInt(opts.timeout, 10);
 const MAX_SENDS     = parseInt(opts['max-sends'], 10);
 const MAX_TOOL_CALLS = parseInt(opts['max-tool-calls'], 10);
+const STALL_TIMEOUT_S = parseInt(opts['stall-timeout'], 10);
+const STARTUP_TIMEOUT_S = parseInt(opts['startup-timeout'], 10);
+const DEAD_AIR_TIMEOUT_M = parseFloat(opts['dead-air-timeout']);
+const MAX_NUDGES    = parseInt(opts['max-nudges'], 10);
 const COOLDOWN_S    = parseInt(opts.cooldown, 10);
 const ABORT_FILE    = opts['abort-file'] ? resolve(opts['abort-file']) : null;
 const POLL_INTERVAL = parseInt(opts['poll-interval'], 10);
@@ -92,8 +104,11 @@ const state = {
   sendCallsThisMinute: 0,
   exitCode: null,
   exitSignal: null,
-  killedBy: null,    // 'budget' | 'timeout' | 'rate-sends' | 'rate-tools' | 'abort' | null
+  killedBy: null,    // 'budget' | 'timeout' | 'rate-sends' | 'rate-tools' | 'abort' | 'stall' | 'dead-air' | null
   duration: 0,
+  stallEvents: 0,
+  nudges: 0,
+  deadAirChecks: 0,
 };
 
 // Sliding window for per-minute rate limiting
@@ -231,18 +246,241 @@ function killChild(reason) {
   }, COOLDOWN_S * 1000);
 }
 
+// --- Prompt pattern detection ---
+
+const PROMPT_PATTERNS = [
+  /\(y\/n\)/i,
+  /\[Y\/n\]/i,
+  /\[y\/N\]/i,
+  /\(yes\/no\)/i,
+  /Do you want to trust/i,
+  /Do you want to allow/i,
+  /Press Enter to continue/i,
+  /Are you sure/i,
+];
+
+function checkForPrompts(text) {
+  for (const pattern of PROMPT_PATTERNS) {
+    if (pattern.test(text)) {
+      log(`PROMPT detected in stdout: ${text.trim().substring(0, 100)}`);
+      state.stallEvents++;
+      // Close stdin to dismiss the prompt
+      closeStdin();
+      return true;
+    }
+  }
+  return false;
+}
+
+// --- CPU liveness sampling ---
+
+// Reads cumulative CPU time (user+system) for a process tree.
+// Returns total CPU milliseconds, or -1 if unavailable.
+// On Linux: reads /proc/<pid>/stat (works in containers).
+// On macOS: uses ps command as fallback.
+let lastCpuMs = null;  // null = no prior sample taken yet
+
+function sampleCpuMs(pid) {
+  try {
+    // Linux: /proc/<pid>/stat fields 14 (utime) and 15 (stime) in clock ticks
+    const statPath = `/proc/${pid}/stat`;
+    if (existsSync(statPath)) {
+      const stat = readFileSync(statPath, 'utf8');
+      // Fields are space-separated, but comm (field 2) can contain spaces/parens.
+      // Find the closing paren, then split the rest.
+      const afterComm = stat.substring(stat.lastIndexOf(')') + 2);
+      const fields = afterComm.split(' ');
+      // fields[11] = utime (index 13 in original), fields[12] = stime (index 14)
+      const utime = parseInt(fields[11], 10) || 0;
+      const stime = parseInt(fields[12], 10) || 0;
+      // Also grab child times: fields[13] = cutime, fields[14] = cstime
+      const cutime = parseInt(fields[13], 10) || 0;
+      const cstime = parseInt(fields[14], 10) || 0;
+      // Convert clock ticks to ms (typically 100 ticks/sec on Linux)
+      const ticksPerSec = 100;
+      return ((utime + stime + cutime + cstime) / ticksPerSec) * 1000;
+    }
+
+    // macOS / fallback: use ps to get cumulative CPU time
+    const output = execSync(`ps -o cputime= -p ${pid} 2>/dev/null`, { encoding: 'utf8', timeout: 3000 }).trim();
+    if (!output) return -1;
+    // Format: HH:MM:SS or M:SS
+    const parts = output.split(':').map(Number);
+    if (parts.length === 3) return (parts[0] * 3600 + parts[1] * 60 + parts[2]) * 1000;
+    if (parts.length === 2) return (parts[0] * 60 + parts[1]) * 1000;
+    return -1;
+  } catch {
+    return -1;
+  }
+}
+
+// Returns true if the child process has consumed CPU since the last sample.
+function hasConsumedCpu(pid) {
+  const cpuMs = sampleCpuMs(pid);
+  if (cpuMs < 0) return true; // Can't measure → assume alive (safe default)
+
+  const prev = lastCpuMs;
+  lastCpuMs = cpuMs;
+
+  // First sample — no delta yet, assume alive
+  if (prev === null) return true;
+
+  // If CPU time increased at all, process is doing work
+  return cpuMs > prev;
+}
+
+// --- Dead air detection ---
+
+let deadAirStart = null;   // Timestamp when dead air began (null = not in dead air)
+let deadAirPollId = null;
+
+function checkDeadAir() {
+  if (killed || !child || DEAD_AIR_TIMEOUT_M <= 0) return;
+
+  state.deadAirChecks++;
+  const cpuActive = hasConsumedCpu(child.pid);
+  const silenceSec = Math.round((Date.now() - lastOutputTime) / 1000);
+
+  if (cpuActive) {
+    // Process is working — reset dead air, let it cook
+    if (deadAirStart) {
+      log(`Dead air cleared — CPU active after ${Math.round((Date.now() - deadAirStart) / 1000)}s of silence`);
+      deadAirStart = null;
+    }
+    return;
+  }
+
+  // Zero CPU + zero output
+  if (!deadAirStart) {
+    deadAirStart = Date.now();
+    log(`Dead air started — zero CPU, ${silenceSec}s silence`);
+  }
+
+  const deadAirMin = (Date.now() - deadAirStart) / 60_000;
+  if (deadAirMin >= DEAD_AIR_TIMEOUT_M) {
+    log(`DEAD AIR — zero CPU + zero output for ${Math.round(deadAirMin)}min (threshold: ${DEAD_AIR_TIMEOUT_M}min)`);
+    killChild('dead-air');
+    return;
+  }
+
+  log(`Dead air check — zero CPU, ${Math.round(deadAirMin * 10) / 10}/${DEAD_AIR_TIMEOUT_M}min, ${silenceSec}s silence`);
+}
+
+// Poll interval: min(30s, threshold/3) — fast polls for short thresholds, 30s cap for production
+const DEAD_AIR_POLL_MS = DEAD_AIR_TIMEOUT_M > 0
+  ? Math.min(30_000, Math.max(2_000, (DEAD_AIR_TIMEOUT_M * 60_000) / 3))
+  : 30_000;
+
+function scheduleDeadAirPoll() {
+  if (killed || DEAD_AIR_TIMEOUT_M <= 0) return;
+  deadAirPollId = setTimeout(() => {
+    checkDeadAir();
+    if (!killed) scheduleDeadAirPoll();
+  }, jitteredDelay(DEAD_AIR_POLL_MS));
+}
+
+// --- Stall detection ---
+
+let stallTimer = null;
+let nudgeCount = 0;
+let stdinClosed = false;
+let lastOutputTime = Date.now();
+let gotFirstOutput = false;
+
+function onChildOutput() {
+  lastOutputTime = Date.now();
+  // Reset dead air — got real output
+  if (deadAirStart) {
+    log(`Dead air cleared — received output after ${Math.round((Date.now() - deadAirStart) / 1000)}s`);
+    deadAirStart = null;
+  }
+  if (!gotFirstOutput) {
+    gotFirstOutput = true;
+    log(`First output received after ${Math.round((Date.now() - new Date(state.startedAt).getTime()) / 1000)}s — switching to stall-timeout=${STALL_TIMEOUT_S}s`);
+  }
+  resetStallTimer();
+}
+
+function currentStallTimeout() {
+  // Use startup timeout until first output, then normal stall timeout
+  if (!gotFirstOutput && STARTUP_TIMEOUT_S > 0) return STARTUP_TIMEOUT_S;
+  return STALL_TIMEOUT_S;
+}
+
+function resetStallTimer() {
+  if (stallTimer) clearTimeout(stallTimer);
+  const timeout = currentStallTimeout();
+  if (killed || timeout <= 0) return;
+  stallTimer = setTimeout(onStallDetected, timeout * 1000);
+}
+
+function closeStdin() {
+  if (stdinClosed || !child) return;
+  stdinClosed = true;
+  try { child.stdin.end(); } catch { /* already closed */ }
+  log('Stdin: closed (EOF)');
+}
+
+function onStallDetected() {
+  if (killed) return;
+  state.stallEvents++;
+  const silence = Math.round((Date.now() - lastOutputTime) / 1000);
+  log(`STALL — no output for ${silence}s (nudges: ${nudgeCount}/${MAX_NUDGES})`);
+
+  // Escalation: close stdin → nudge → check CPU → kill
+  if (!stdinClosed) {
+    closeStdin();
+    resetStallTimer();
+    return;
+  }
+
+  if (nudgeCount < MAX_NUDGES && !child.stdin.writableEnded) {
+    nudgeCount++;
+    state.nudges = nudgeCount;
+    log(`Stall nudge #${nudgeCount}`);
+    resetStallTimer();
+    return;
+  }
+
+  // If dead air detection is enabled, defer kill to the dead air poller.
+  // Only stall-kill if we can confirm zero CPU, or if dead air is disabled.
+  if (DEAD_AIR_TIMEOUT_M > 0 && child) {
+    const cpuActive = hasConsumedCpu(child.pid);
+    if (cpuActive) {
+      log(`Stall deferred — process has CPU activity, deferring to dead-air detection`);
+      resetStallTimer();
+      return;
+    }
+  }
+
+  killChild('stall');
+}
+
 // --- Spawn child process ---
 
 log(`Starting: ${childCmd} ${childArgs.join(' ').substring(0, 100)}...`);
-log(`Budget: ${BUDGET} tokens | Timeout: ${TIMEOUT_S}s | Max sends: ${MAX_SENDS}/min | Max tools: ${MAX_TOOL_CALLS}/min`);
+log(`Budget: ${BUDGET} tokens | Timeout: ${TIMEOUT_S}s | Startup: ${STARTUP_TIMEOUT_S}s | Stall: ${STALL_TIMEOUT_S}s | Dead air: ${DEAD_AIR_TIMEOUT_M}min | Max sends: ${MAX_SENDS}/min | Max tools: ${MAX_TOOL_CALLS}/min`);
 
 child = spawn(childCmd, childArgs, {
-  stdio: ['inherit', 'inherit', 'pipe'],  // stdin/stdout pass through, stderr captured
+  stdio: ['pipe', 'pipe', 'pipe'],  // All piped: niki controls stdin, monitors stdout+stderr
   env: process.env,  // Inherit env (tokens stay in env, never logged)
 });
 
 state.pid = child.pid;
 
+// Close stdin immediately — claude -p should never need interactive input.
+// This prevents blocking on trust prompts, permission prompts, or stdin reads.
+closeStdin();
+
+// --- Monitor stdout ---
+
+child.stdout.on('data', (chunk) => {
+  // Forward to our stdout (preserves runner's | tee pipeline)
+  process.stdout.write(chunk);
+  onChildOutput();
+  checkForPrompts(chunk.toString());
+});
+
 // --- Monitor stderr ---
 
 let stderrBuffer = '';
@@ -252,6 +490,7 @@ child.stderr.on('data', (chunk) => {
 
   // Always forward stderr to our stderr (so supervisor captures it)
   process.stderr.write(chunk);
+  onChildOutput();
 
   // Buffer and parse line by line
   stderrBuffer += text;
@@ -277,6 +516,18 @@ child.stderr.on('data', (chunk) => {
   }
 });
 
+// Start stall detection
+if (STALL_TIMEOUT_S > 0 || STARTUP_TIMEOUT_S > 0) {
+  log(`Stall detection: startup-timeout=${STARTUP_TIMEOUT_S}s, stall-timeout=${STALL_TIMEOUT_S}s, max-nudges=${MAX_NUDGES}`);
+  resetStallTimer();
+}
+
+// Start dead air detection
+if (DEAD_AIR_TIMEOUT_M > 0) {
+  log(`Dead air detection: ${DEAD_AIR_TIMEOUT_M}min threshold, ${Math.round(DEAD_AIR_POLL_MS / 1000)}s poll interval`);
+  scheduleDeadAirPoll();
+}
+
 // --- Abort file polling (with jitter) ---
 
 let abortPollId = null;
@@ -315,12 +566,15 @@ const timeoutId = setTimeout(() => {
 
 child.on('exit', (code, signal) => {
   clearTimeout(timeoutId);
+  if (stallTimer) clearTimeout(stallTimer);
   if (abortPollId) clearTimeout(abortPollId);
+  if (deadAirPollId) clearTimeout(deadAirPollId);
   state.exitCode = code;
   state.exitSignal = signal;
   state.duration = Math.round((Date.now() - new Date(state.startedAt).getTime()) / 1000);
 
-  log(`Exit — code: ${code} signal: ${signal} | tokens: ${state.tokensTotal} | tools: ${state.toolCalls} | sends: ${state.sendCalls} | duration: ${state.duration}s${state.killedBy ? ` | killed: ${state.killedBy}` : ''}`);
+  state.gotFirstOutput = gotFirstOutput;
+  log(`Exit — code: ${code} signal: ${signal} | tokens: ${state.tokensTotal} | tools: ${state.toolCalls} | sends: ${state.sendCalls} | duration: ${state.duration}s | output: ${gotFirstOutput}${state.killedBy ? ` | killed: ${state.killedBy}` : ''}`);
   writeState();
 
   if (logStream) logStream.end();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tjamescouch/niki",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Deterministic process supervisor for AI agents — token budgets, rate limits, and abort control",
   "bin": {
     "niki": "./bin/niki"

package/tests/test-niki.sh

@@ -0,0 +1,275 @@
+#!/bin/bash
+# test-niki.sh — Unit tests for niki process supervisor
+#
+# Tests stdin management, stdout forwarding, stall detection,
+# session handling, and prompt detection.
+#
+# Usage: ./tests/test-niki.sh [--verbose]
+
+set -euo pipefail
+
+NIKI="$(dirname "$0")/../bin/niki"
+PASSED=0
+FAILED=0
+VERBOSE="${1:-}"
+
+red()   { printf "\033[31m%s\033[0m" "$1"; }
+green() { printf "\033[32m%s\033[0m" "$1"; }
+bold()  { printf "\033[1m%s\033[0m" "$1"; }
+
+run_test() {
+    local name="$1"
+    shift
+    local expected_exit="$1"
+    shift
+
+    printf "  %-50s " "$name"
+
+    local output
+    local actual_exit=0
+    output=$("$@" 2>&1) || actual_exit=$?
+
+    if [ "$actual_exit" -eq "$expected_exit" ]; then
+        green "PASS"
+        echo " (exit $actual_exit)"
+        PASSED=$((PASSED + 1))
+        if [ "$VERBOSE" = "--verbose" ]; then
+            echo "$output" | sed 's/^/    | /'
+        fi
+    else
+        red "FAIL"
+        echo " (expected exit $expected_exit, got $actual_exit)"
+        FAILED=$((FAILED + 1))
+        echo "$output" | sed 's/^/    | /'
+    fi
+}
+
+run_test_output() {
+    local name="$1"
+    local expected_pattern="$2"
+    shift 2
+
+    printf "  %-50s " "$name"
+
+    local output
+    local actual_exit=0
+    output=$("$@" 2>&1) || actual_exit=$?
+
+    if echo "$output" | grep -qE "$expected_pattern"; then
+        green "PASS"
+        echo ""
+        PASSED=$((PASSED + 1))
+        if [ "$VERBOSE" = "--verbose" ]; then
+            echo "$output" | sed 's/^/    | /'
+        fi
+    else
+        red "FAIL"
+        echo " (pattern '$expected_pattern' not found)"
+        FAILED=$((FAILED + 1))
+        echo "$output" | sed 's/^/    | /'
+    fi
+}
+
+echo ""
+bold "=== niki unit tests ==="; echo ""
+echo ""
+
+# ---- Stdout forwarding ----
+
+bold "Stdout forwarding"; echo ""
+
+run_test_output \
+    "echo passes through stdout" \
+    "^hello from niki$" \
+    timeout 10 node "$NIKI" --stall-timeout 5 -- echo "hello from niki"
+
+run_test \
+    "echo exits cleanly (code 0)" \
+    0 \
+    timeout 10 node "$NIKI" --stall-timeout 5 -- echo "test"
+
+run_test_output \
+    "multi-line output preserved" \
+    "line2" \
+    timeout 10 node "$NIKI" --stall-timeout 5 -- sh -c 'echo line1; echo line2; echo line3'
+
+echo ""
+
+# ---- Stdin management ----
+
+bold "Stdin management"; echo ""
+
+run_test_output \
+    "stdin closed immediately on spawn" \
+    "Stdin: closed" \
+    timeout 10 node "$NIKI" --stall-timeout 5 -- echo "ok"
+
+run_test \
+    "cat exits on EOF (stdin closed)" \
+    0 \
+    timeout 10 node "$NIKI" --stall-timeout 5 -- cat
+
+echo ""
+
+# ---- Stall detection ----
+
+bold "Stall detection"; echo ""
+
+run_test_output \
+    "stall kills silent process" \
+    "STALL.*no output" \
+    timeout 10 node "$NIKI" --stall-timeout 2 --startup-timeout 0 --max-nudges 0 -- sleep 30
+
+run_test_output \
+    "stall kill reason logged" \
+    "KILL.*reason: stall" \
+    timeout 10 node "$NIKI" --stall-timeout 2 --startup-timeout 0 --max-nudges 0 -- sleep 30
+
+run_test \
+    "stall kill exits non-zero" \
+    1 \
+    timeout 10 node "$NIKI" --stall-timeout 2 --startup-timeout 0 --max-nudges 0 -- sleep 30
+
+run_test_output \
+    "stall disabled when timeout=0" \
+    "Exit.*code: 0" \
+    timeout 5 node "$NIKI" --stall-timeout 0 -- sh -c 'sleep 1; echo done'
+
+echo ""
+
+# ---- Stall timeout precision ----
+
+bold "Stall timing"; echo ""
+
+# Process that outputs then goes silent — stall should fire after the silence
+run_test_output \
+    "stall timer resets on output" \
+    "Exit.*code: 0" \
+    timeout 10 node "$NIKI" --stall-timeout 3 --startup-timeout 0 -- sh -c 'echo tick; sleep 1; echo tick; sleep 1; echo done'
+
+echo ""
+
+# ---- Startup timeout ----
+
+bold "Startup timeout"; echo ""
+
+# Startup timeout gives longer grace period before first output
+run_test_output \
+    "startup-timeout used before first output" \
+    "startup-timeout=5s" \
+    timeout 10 node "$NIKI" --stall-timeout 2 --startup-timeout 5 -- sh -c 'sleep 3; echo hello'
+
+# After first output, switches to stall-timeout
+run_test_output \
+    "switches to stall-timeout after first output" \
+    "switching to stall-timeout" \
+    timeout 10 node "$NIKI" --stall-timeout 3 --startup-timeout 10 -- sh -c 'echo first; sleep 1; echo done'
+
+echo ""
+
+# ---- Budget/timeout (existing features, regression) ----
+
+bold "Budget and timeout (regression)"; echo ""
+
+run_test_output \
+    "wall-clock timeout kills" \
+    "KILL.*reason: timeout" \
+    timeout 10 node "$NIKI" --timeout 2 --stall-timeout 0 -- sleep 30
+
+run_test \
+    "timeout kill exits non-zero" \
+    1 \
+    timeout 10 node "$NIKI" --timeout 2 --stall-timeout 0 -- sleep 30
+
+echo ""
+
+# ---- Exit code passthrough ----
+
+bold "Exit code passthrough"; echo ""
+
+run_test \
+    "child exit 0 → niki exit 0" \
+    0 \
+    timeout 10 node "$NIKI" --stall-timeout 5 -- sh -c 'exit 0'
+
+run_test \
+    "child exit 1 → niki exit 1" \
+    1 \
+    timeout 10 node "$NIKI" --stall-timeout 5 -- sh -c 'exit 1'
+
+run_test \
+    "child exit 42 → niki exit 42" \
+    42 \
+    timeout 10 node "$NIKI" --stall-timeout 5 -- sh -c 'exit 42'
+
+echo ""
+
+# ---- Abort file ----
+
+bold "Abort file"; echo ""
+
+ABORT_FILE=$(mktemp)
+rm -f "$ABORT_FILE"
+
+run_test_output \
+    "abort file kills process" \
+    "KILL.*reason: abort" \
+    timeout 10 sh -c "node $NIKI --stall-timeout 0 --abort-file $ABORT_FILE -- sh -c 'sleep 1; echo still here; sleep 30' & PID=\$!; sleep 2; touch $ABORT_FILE; wait \$PID 2>/dev/null; echo done"
+
+rm -f "$ABORT_FILE"
+
+echo ""
+
+# ---- SIGTERM forwarding ----
+
+bold "SIGTERM forwarding"; echo ""
+
+# niki should forward SIGTERM to child and exit
+run_test_output \
+    "SIGTERM forwarded to child" \
+    "Received SIGTERM" \
+    timeout 10 sh -c "node $NIKI --stall-timeout 0 -- sh -c 'echo started; sleep 30' & PID=\$!; sleep 1; kill -TERM \$PID; wait \$PID 2>/dev/null; echo done"
+
+echo ""
+
+# ---- Dead air detection ----
+
+bold "Dead air detection"; echo ""
+
+# Dead air kills silent process with zero CPU (sleep has ~zero CPU)
+run_test_output \
+    "dead air kills zero-CPU process" \
+    "DEAD AIR.*zero CPU" \
+    timeout 30 node "$NIKI" --stall-timeout 0 --dead-air-timeout 0.1 -- sleep 30
+
+run_test_output \
+    "dead air kill reason logged" \
+    "KILL.*reason: dead-air" \
+    timeout 30 node "$NIKI" --stall-timeout 0 --dead-air-timeout 0.1 -- sleep 30
+
+# Dead air defers for CPU-active processes (busy loop uses CPU)
+run_test_output \
+    "dead air defers when CPU active" \
+    "Exit.*code: 0" \
+    timeout 15 node "$NIKI" --stall-timeout 0 --dead-air-timeout 0.1 -- sh -c 'i=0; while [ $i -lt 2000000 ]; do i=$((i+1)); done; echo done'
+
+# Dead air disabled when timeout=0
+run_test_output \
+    "dead air disabled when timeout=0" \
+    "Exit.*code: 0" \
+    timeout 10 node "$NIKI" --stall-timeout 0 --dead-air-timeout 0 -- sh -c 'sleep 1; echo done'
+
+echo ""
+
+# ---- Summary ----
+
+echo "────────────────────────────────────────────────"
+TOTAL=$((PASSED + FAILED))
+if [ "$FAILED" -eq 0 ]; then
+    green "All $TOTAL tests passed"; echo ""
+else
+    red "$FAILED/$TOTAL tests failed"; echo ""
+fi
+echo ""
+
+exit "$FAILED"