@tjamescouch/niki 0.3.0 → 0.5.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 James Couch
+Copyright (c) 2026 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

package/bin/niki

@@ -8,6 +8,7 @@
  *   - Wall-clock timeout (kill if exceeded)
  *   - Tool-call rate limiting (kill if agent floods)
  *   - Diagnostics logging
+ *   - Automatic restart on exit (optional)
  *
  * Usage:
  *   niki [options] -- <command> [args...]
@@ -42,14 +43,20 @@ Options:
   --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
+  --log-level <level>     Minimum log level: debug, info, warn, error (default: info)
+  --log-json              Emit logs as JSON lines (for machine parsing)
   --state <file>          Write state JSON on exit (budget used, reason, etc.)
   --cooldown <seconds>    Grace period after SIGTERM before SIGKILL (default: 5)
   --abort-file <path>     Poll this file for external abort signal
   --poll-interval <ms>    Base poll interval in ms for abort file (default: 1000)
+  --restart               Restart the child process when it exits (default: off)
+  --max-restarts <n>      Max restart attempts, 0=unlimited (default: 0)
+  --restart-delay <secs>  Delay between restarts with ±30% jitter (default: 5)
 
 Examples:
   niki --budget 500000 -- claude -p "your prompt" --verbose
-  niki --timeout 1800 --max-sends 5 -- claude -p "..." --model sonnet --verbose`);
+  niki --timeout 1800 --max-sends 5 -- claude -p "..." --model sonnet --verbose
+  niki --restart --max-restarts 10 -- gro --model gpt-5.2 "your prompt"`);
   process.exit(1);
 }
 
@@ -69,10 +76,15 @@ const { values: opts } = parseArgs({
     'dead-air-timeout': { type: 'string', default: '5' },
     'max-nudges':    { type: 'string', default: '3' },
     log:             { type: 'string' },
+    'log-level':     { type: 'string', default: 'info' },
+    'log-json':      { type: 'boolean', default: false },
     state:           { type: 'string' },
     cooldown:        { type: 'string', default: '5' },
     'abort-file':    { type: 'string' },
     'poll-interval': { type: 'string', default: '1000' },
+    restart:         { type: 'boolean', default: false },
+    'max-restarts':  { type: 'string', default: '0' },
+    'restart-delay': { type: 'string', default: '5' },
   },
 });
 
@@ -89,7 +101,15 @@ const ABORT_FILE    = opts['abort-file'] ? resolve(opts['abort-file']) : null;
 const POLL_INTERVAL = parseInt(opts['poll-interval'], 10);
 const LOG_FILE      = opts.log;
 const STATE_FILE    = opts.state;
+const RESTART       = opts.restart;
+const MAX_RESTARTS  = parseInt(opts['max-restarts'], 10);
+const RESTART_DELAY_S = parseFloat(opts['restart-delay']);
+const LOG_JSON      = opts['log-json'];
 
+// --- Log levels ---
+
+const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+const LOG_LEVEL = LOG_LEVELS[opts['log-level']] ?? LOG_LEVELS.info;
 // --- State ---
 
 const state = {
@@ -109,12 +129,17 @@ const state = {
   stallEvents: 0,
   nudges: 0,
   deadAirChecks: 0,
+  restarts: 0,
 };
 
 // Sliding window for per-minute rate limiting
 const toolCallTimestamps = [];
 const sendCallTimestamps = [];
 
+// Budget threshold tracking — warn once at each level
+const BUDGET_THRESHOLDS = [0.5, 0.75, 0.9];
+const budgetWarned = new Set();
+
 // --- Logging ---
 
 let logStream = null;
@@ -123,11 +148,24 @@ if (LOG_FILE) {
   logStream = createWriteStream(resolve(LOG_FILE), { flags: 'a' });
 }
 
-function log(msg) {
-  const line = `[${new Date().toISOString()}] ${msg}`;
-  if (logStream) logStream.write(line + '\n');
-  // Also write to stderr so supervisor can capture it
-  process.stderr.write(`[niki] ${line}\n`);
+function log(msg, level = 'info', fields = null) {
+  const numLevel = LOG_LEVELS[level] ?? LOG_LEVELS.info;
+  if (numLevel < LOG_LEVEL) return;
+
+  const ts = new Date().toISOString();
+
+  if (LOG_JSON) {
+    const entry = { ts, level, msg, ...state };
+    if (fields) Object.assign(entry, fields);
+    const json = JSON.stringify(entry);
+    if (logStream) logStream.write(json + '\n');
+    process.stderr.write(json + '\n');
+  } else {
+    const prefix = level === 'info' ? '' : `[${level.toUpperCase()}] `;
+    const line = `[${ts}] ${prefix}${msg}`;
+    if (logStream) logStream.write(line + '\n');
+    process.stderr.write(`[niki] ${line}\n`);
+  }
 }
 
 function writeState() {
@@ -141,6 +179,20 @@ function writeState() {
   }
 }
 
+// --- Budget threshold warnings ---
+
+function checkBudgetThresholds() {
+  if (BUDGET <= 0) return;
+  const pct = state.tokensTotal / BUDGET;
+  for (const threshold of BUDGET_THRESHOLDS) {
+    if (pct >= threshold && !budgetWarned.has(threshold)) {
+      budgetWarned.add(threshold);
+      const used = state.tokensTotal;
+      const remaining = BUDGET - used;
+      log(`Budget ${Math.round(threshold * 100)}% — ${used.toLocaleString()}/${BUDGET.toLocaleString()} tokens used, ${remaining.toLocaleString()} remaining`, 'warn');
+    }
+  }
+}
 // --- Token parsing from stderr ---
 
 // Claude --verbose outputs token usage in stderr. Patterns vary by version.
@@ -163,6 +215,7 @@ const TOKEN_PATTERNS = [
 ];
 
 function parseTokens(line) {
+  let changed = false;
   for (const { regex, field } of TOKEN_PATTERNS) {
     regex.lastIndex = 0;
     let match;
@@ -170,30 +223,39 @@ function parseTokens(line) {
       const count = parseInt(match[1], 10);
       if (isNaN(count) || count <= 0) continue;
       if (field === 'in') {
-        state.tokensIn = Math.max(state.tokensIn, count);
+        if (count > state.tokensIn) { state.tokensIn = count; changed = true; }
       } else {
-        state.tokensOut = Math.max(state.tokensOut, count);
+        if (count > state.tokensOut) { state.tokensOut = count; changed = true; }
       }
       state.tokensTotal = state.tokensIn + state.tokensOut;
     }
   }
+  if (changed) {
+    log(`Tokens — in: ${state.tokensIn.toLocaleString()} out: ${state.tokensOut.toLocaleString()} total: ${state.tokensTotal.toLocaleString()}/${BUDGET.toLocaleString()} (${Math.round(state.tokensTotal / BUDGET * 100)}%)`, 'debug');
+    checkBudgetThresholds();
+  }
 }
 
 // --- Tool call detection from stderr ---
 
 // Claude --verbose logs tool calls. We detect sends specifically.
-const TOOL_CALL_PATTERN = /(?:Using tool|Tool call|tool_use).*?(\w+)/i;
+const TOOL_CALL_PATTERN = /(?:Using tool|Tool call|tool_use)[:\s]*(\S+)/i;
 const SEND_PATTERN = /agentchat_send/i;
 
 function parseToolCall(line) {
-  if (TOOL_CALL_PATTERN.test(line)) {
+  const toolMatch = line.match(TOOL_CALL_PATTERN);
+  if (toolMatch) {
     const now = Date.now();
+    const toolName = toolMatch[1] || 'unknown';
     state.toolCalls++;
     toolCallTimestamps.push(now);
 
     if (SEND_PATTERN.test(line)) {
       state.sendCalls++;
       sendCallTimestamps.push(now);
+      log(`Tool call #${state.toolCalls}: ${toolName} (send #${state.sendCalls}, ${state.sendCallsThisMinute + 1}/${MAX_SENDS}/min)`, 'info');
+    } else {
+      log(`Tool call #${state.toolCalls}: ${toolName} (${state.toolCallsThisMinute + 1}/${MAX_TOOL_CALLS}/min)`, 'debug');
     }
   }
 }
@@ -214,6 +276,14 @@ function checkRateLimits() {
   state.toolCallsThisMinute = toolCallTimestamps.length;
   state.sendCallsThisMinute = sendCallTimestamps.length;
 
+  // Warn at 80% of rate limits
+  if (state.sendCallsThisMinute === Math.ceil(MAX_SENDS * 0.8)) {
+    log(`Rate warning — sends at ${state.sendCallsThisMinute}/${MAX_SENDS}/min (80% threshold)`, 'warn');
+  }
+  if (state.toolCallsThisMinute === Math.ceil(MAX_TOOL_CALLS * 0.8)) {
+    log(`Rate warning — tool calls at ${state.toolCallsThisMinute}/${MAX_TOOL_CALLS}/min (80% threshold)`, 'warn');
+  }
+
   if (sendCallTimestamps.length > MAX_SENDS) {
     return 'rate-sends';
   }
@@ -222,7 +292,6 @@ function checkRateLimits() {
   }
   return null;
 }
-
 // --- Kill logic ---
 
 let child = null;
@@ -232,7 +301,7 @@ function killChild(reason) {
   if (killed || !child) return;
   killed = true;
   state.killedBy = reason;
-  log(`KILL — reason: ${reason} | tokens: ${state.tokensTotal}/${BUDGET} | sends: ${state.sendCallsThisMinute}/min | tools: ${state.toolCallsThisMinute}/min`);
+  log(`KILL — reason: ${reason} | tokens: ${state.tokensTotal}/${BUDGET} | sends: ${state.sendCallsThisMinute}/min | tools: ${state.toolCallsThisMinute}/min`, 'error');
 
   child.kill('SIGTERM');
 
@@ -262,7 +331,7 @@ const PROMPT_PATTERNS = [
 function checkForPrompts(text) {
   for (const pattern of PROMPT_PATTERNS) {
     if (pattern.test(text)) {
-      log(`PROMPT detected in stdout: ${text.trim().substring(0, 100)}`);
+      log(`PROMPT detected in stdout: ${text.trim().substring(0, 100)}`, 'warn');
       state.stallEvents++;
       // Close stdin to dismiss the prompt
       closeStdin();
@@ -329,6 +398,13 @@ function hasConsumedCpu(pid) {
   return cpuMs > prev;
 }
 
+// --- Jitter utility ---
+
+function jitteredDelay(base) {
+  // ±30% jitter
+  const jitter = base * 0.3;
+  return base + (Math.random() * 2 * jitter - jitter);
+}
 // --- Dead air detection ---
 
 let deadAirStart = null;   // Timestamp when dead air began (null = not in dead air)
@@ -344,7 +420,7 @@ function checkDeadAir() {
   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`);
+      log(`Dead air cleared — CPU active after ${Math.round((Date.now() - deadAirStart) / 1000)}s of silence`, 'info');
       deadAirStart = null;
     }
     return;
@@ -353,17 +429,17 @@ function checkDeadAir() {
   // Zero CPU + zero output
   if (!deadAirStart) {
     deadAirStart = Date.now();
-    log(`Dead air started — zero CPU, ${silenceSec}s silence`);
+    log(`Dead air started — zero CPU, ${silenceSec}s silence`, 'warn');
   }
 
   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)`);
+    log(`DEAD AIR — zero CPU + zero output for ${Math.round(deadAirMin)}min (threshold: ${DEAD_AIR_TIMEOUT_M}min)`, 'error');
     killChild('dead-air');
     return;
   }
 
-  log(`Dead air check — zero CPU, ${Math.round(deadAirMin * 10) / 10}/${DEAD_AIR_TIMEOUT_M}min, ${silenceSec}s silence`);
+  log(`Dead air check — zero CPU, ${Math.round(deadAirMin * 10) / 10}/${DEAD_AIR_TIMEOUT_M}min, ${silenceSec}s silence`, 'debug');
 }
 
 // Poll interval: min(30s, threshold/3) — fast polls for short thresholds, 30s cap for production
@@ -391,12 +467,12 @@ 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`);
+    log(`Dead air cleared — received output after ${Math.round((Date.now() - deadAirStart) / 1000)}s`, 'info');
     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`);
+    log(`First output received after ${Math.round((Date.now() - new Date(state.startedAt).getTime()) / 1000)}s — switching to stall-timeout=${STALL_TIMEOUT_S}s`, 'info');
   }
   resetStallTimer();
 }
@@ -418,14 +494,14 @@ function closeStdin() {
   if (stdinClosed || !child) return;
   stdinClosed = true;
   try { child.stdin.end(); } catch { /* already closed */ }
-  log('Stdin: closed (EOF)');
+  log('Stdin: closed (EOF)', 'debug');
 }
 
 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})`);
+  log(`STALL — no output for ${silence}s (nudges: ${nudgeCount}/${MAX_NUDGES})`, 'warn');
 
   // Escalation: close stdin → nudge → check CPU → kill
   if (!stdinClosed) {
@@ -437,7 +513,7 @@ function onStallDetected() {
   if (nudgeCount < MAX_NUDGES && !child.stdin.writableEnded) {
     nudgeCount++;
     state.nudges = nudgeCount;
-    log(`Stall nudge #${nudgeCount}`);
+    log(`Stall nudge #${nudgeCount}`, 'info');
     resetStallTimer();
     return;
   }
@@ -447,7 +523,7 @@ function onStallDetected() {
   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`);
+      log(`Stall deferred — process has CPU activity, deferring to dead-air detection`, 'info');
       resetStallTimer();
       return;
     }
@@ -455,137 +531,195 @@ function onStallDetected() {
 
   killChild('stall');
 }
+// --- Restart logic ---
+
+// Reasons that should NOT trigger a restart (hard limits / operator intent)
+const NO_RESTART_REASONS = new Set(['budget', 'rate-sends', 'rate-tools', 'abort']);
+let nikiTerminated = false; // Set when niki itself receives SIGTERM/SIGINT
+
+function shouldRestart(code, signal) {
+  if (!RESTART) return false;
+  if (nikiTerminated) return false;
+  if (state.killedBy && NO_RESTART_REASONS.has(state.killedBy)) return false;
+  if (MAX_RESTARTS > 0 && state.restarts >= MAX_RESTARTS) return false;
+  return true;
+}
 
-// --- Spawn child process ---
-
-log(`Starting: ${childCmd} ${childArgs.join(' ').substring(0, 100)}...`);
-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: ['pipe', 'pipe', 'pipe'],  // All piped: niki controls stdin, monitors stdout+stderr
-  env: process.env,  // Inherit env (tokens stay in env, never logged)
-});
+function resetPerRunState() {
+  // Reset per-run flags but keep cumulative counters (tokens, toolCalls, etc.)
+  killed = false;
+  state.killedBy = null;
+  state.exitCode = null;
+  state.exitSignal = null;
+  state.gotFirstOutput = undefined;
+
+  // Reset stall/dead-air detection
+  nudgeCount = 0;
+  stdinClosed = false;
+  lastOutputTime = Date.now();
+  gotFirstOutput = false;
+  lastCpuMs = null;
+  deadAirStart = null;
+
+  // Clear rate limit windows (fresh session)
+  toolCallTimestamps.length = 0;
+  sendCallTimestamps.length = 0;
+  state.toolCallsThisMinute = 0;
+  state.sendCallsThisMinute = 0;
+
+  // Reset budget warnings for fresh run
+  budgetWarned.clear();
+}
 
-state.pid = child.pid;
+// --- Abort file polling ---
 
-// Close stdin immediately — claude -p should never need interactive input.
-// This prevents blocking on trust prompts, permission prompts, or stdin reads.
-closeStdin();
+let abortPollId = null;
 
-// --- Monitor stdout ---
+function scheduleAbortPoll() {
+  if (!ABORT_FILE || killed) return;
+  abortPollId = setTimeout(() => {
+    if (killed) return;
+    if (existsSync(ABORT_FILE)) {
+      log(`Abort file detected: ${ABORT_FILE}`, 'warn');
+      killChild('abort');
+      return;
+    }
+    scheduleAbortPoll();
+  }, jitteredDelay(POLL_INTERVAL));
+}
 
-child.stdout.on('data', (chunk) => {
-  // Forward to our stdout (preserves runner's | tee pipeline)
-  process.stdout.write(chunk);
-  onChildOutput();
-  checkForPrompts(chunk.toString());
-});
+// --- Spawn and monitor child ---
 
-// --- Monitor stderr ---
+let timeoutId = null;
 
-let stderrBuffer = '';
+function startChild() {
+  log(`Starting: ${childCmd} ${childArgs.join(' ').substring(0, 100)}...`, 'info');
+  log(`Budget: ${BUDGET.toLocaleString()} 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`, 'info');
+  if (RESTART) {
+    log(`Restart: enabled | max: ${MAX_RESTARTS || 'unlimited'} | delay: ${RESTART_DELAY_S}s ±30% | restarts so far: ${state.restarts}`, 'info');
+  }
 
-child.stderr.on('data', (chunk) => {
-  const text = chunk.toString();
+  child = spawn(childCmd, childArgs, {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: process.env,
+  });
 
-  // Always forward stderr to our stderr (so supervisor captures it)
-  process.stderr.write(chunk);
-  onChildOutput();
+  state.pid = child.pid;
+  log(`Child PID: ${child.pid}`, 'debug');
 
-  // Buffer and parse line by line
-  stderrBuffer += text;
-  const lines = stderrBuffer.split('\n');
-  stderrBuffer = lines.pop(); // Keep incomplete last line in buffer
+  // Close stdin immediately — claude -p should never need interactive input.
+  closeStdin();
 
-  for (const line of lines) {
-    parseTokens(line);
-    parseToolCall(line);
+  // --- Monitor stdout ---
 
-    // Check budget
-    if (state.tokensTotal > BUDGET) {
-      killChild('budget');
-      return;
-    }
+  child.stdout.on('data', (chunk) => {
+    process.stdout.write(chunk);
+    onChildOutput();
+    checkForPrompts(chunk.toString());
+  });
 
-    // Check rate limits
-    const rateViolation = checkRateLimits();
-    if (rateViolation) {
-      killChild(rateViolation);
-      return;
-    }
-  }
-});
+  // --- Monitor stderr ---
 
-// 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();
-}
+  let stderrBuffer = '';
 
-// 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();
-}
+  child.stderr.on('data', (chunk) => {
+    const text = chunk.toString();
+    process.stderr.write(chunk);
+    onChildOutput();
 
-// --- Abort file polling (with jitter) ---
+    stderrBuffer += text;
+    const lines = stderrBuffer.split('\n');
+    stderrBuffer = lines.pop();
 
-let abortPollId = null;
+    for (const line of lines) {
+      parseTokens(line);
+      parseToolCall(line);
 
-function jitteredDelay(base) {
-  // ±30% jitter
-  const jitter = base * 0.3;
-  return base + (Math.random() * 2 * jitter - jitter);
-}
+      if (state.tokensTotal > BUDGET) {
+        killChild('budget');
+        return;
+      }
 
-function scheduleAbortPoll() {
-  if (!ABORT_FILE || killed) return;
-  abortPollId = setTimeout(() => {
-    if (killed) return;
-    if (existsSync(ABORT_FILE)) {
-      log(`Abort file detected: ${ABORT_FILE}`);
-      killChild('abort');
-      return;
+      const rateViolation = checkRateLimits();
+      if (rateViolation) {
+        killChild(rateViolation);
+        return;
+      }
     }
-    scheduleAbortPoll();
-  }, jitteredDelay(POLL_INTERVAL));
-}
-
-if (ABORT_FILE) {
-  log(`Abort file: ${ABORT_FILE} (poll: ${POLL_INTERVAL}ms ±30% jitter)`);
-  scheduleAbortPoll();
-}
+  });
 
-// --- Timeout ---
+  // 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}`, 'info');
+    resetStallTimer();
+  }
 
-const timeoutId = setTimeout(() => {
-  killChild('timeout');
-}, TIMEOUT_S * 1000);
+  // 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`, 'info');
+    scheduleDeadAirPoll();
+  }
 
-// --- Clean exit ---
+  // Abort file polling
+  if (ABORT_FILE) {
+    log(`Abort file: ${ABORT_FILE} (poll: ${POLL_INTERVAL}ms ±30% jitter)`, 'info');
+    scheduleAbortPoll();
+  }
 
-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);
-
-  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();
-  process.exit(code ?? 1);
-});
+  // Per-run timeout
+  timeoutId = setTimeout(() => {
+    killChild('timeout');
+  }, TIMEOUT_S * 1000);
+
+  // --- Exit handler ---
+
+  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);
+    state.gotFirstOutput = gotFirstOutput;
+
+    const level = state.killedBy ? 'error' : (code === 0 ? 'info' : 'warn');
+    log(`Exit — code: ${code} signal: ${signal} | tokens: ${state.tokensTotal.toLocaleString()} | tools: ${state.toolCalls} | sends: ${state.sendCalls} | duration: ${state.duration}s | output: ${gotFirstOutput}${state.killedBy ? ` | killed: ${state.killedBy}` : ''} | restarts: ${state.restarts}`, level);
+    writeState();
+
+    if (shouldRestart(code, signal)) {
+      state.restarts++;
+      const delay = jitteredDelay(RESTART_DELAY_S * 1000);
+      log(`RESTART — attempt ${state.restarts}${MAX_RESTARTS > 0 ? `/${MAX_RESTARTS}` : ''} in ${Math.round(delay / 1000)}s`, 'warn');
+      resetPerRunState();
+      setTimeout(() => {
+        startChild();
+      }, delay);
+    } else {
+      if (RESTART && !shouldRestart(code, signal)) {
+        const reason = nikiTerminated ? 'niki received signal' :
+          (state.killedBy && NO_RESTART_REASONS.has(state.killedBy)) ? `hard kill (${state.killedBy})` :
+          (MAX_RESTARTS > 0 && state.restarts >= MAX_RESTARTS) ? `max restarts reached (${MAX_RESTARTS})` :
+          'restart not enabled';
+        log(`NOT RESTARTING — ${reason}`, 'warn');
+      }
+      if (logStream) logStream.end();
+      process.exit(code ?? 1);
+    }
+  });
+}
 
 // --- Signal forwarding ---
 
 for (const sig of ['SIGINT', 'SIGTERM']) {
   process.on(sig, () => {
-    log(`Received ${sig}, forwarding to child`);
+    log(`Received ${sig}, forwarding to child`, 'warn');
+    nikiTerminated = true;
     if (child) child.kill(sig);
   });
 }
+
+// --- Start ---
+
+startChild();

package/bin/niki.bak

@@ -0,0 +1,665 @@
+#!/usr/bin/env node
+
+/**
+ * niki — Deterministic process supervisor for AI agents.
+ *
+ * Wraps a child command (e.g. `claude -p`) and enforces:
+ *   - Token budget (kill if exceeded)
+ *   - Wall-clock timeout (kill if exceeded)
+ *   - Tool-call rate limiting (kill if agent floods)
+ *   - Diagnostics logging
+ *   - Automatic restart on exit (optional)
+ *
+ * Usage:
+ *   niki [options] -- <command> [args...]
+ *   niki --budget 500000 --timeout 3600 -- claude -p "..." --verbose
+ *
+ * Security:
+ *   - Never logs or exposes API tokens
+ *   - Inherits env from parent (tokens stay in env, never in CLI args)
+ *   - Diagnostics only contain counters, never message content
+ */
+
+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';
+
+// --- Argument parsing ---
+
+const SEPARATOR = process.argv.indexOf('--');
+if (SEPARATOR === -1 || SEPARATOR === process.argv.length - 1) {
+  console.error(`niki — deterministic agent supervisor
+
+Usage: niki [options] -- <command> [args...]
+
+Options:
+  --budget <tokens>       Max total tokens (input+output) before SIGTERM (default: 1000000)
+  --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)
+  --abort-file <path>     Poll this file for external abort signal
+  --poll-interval <ms>    Base poll interval in ms for abort file (default: 1000)
+  --restart               Restart the child process when it exits (default: off)
+  --max-restarts <n>      Max restart attempts, 0=unlimited (default: 0)
+  --restart-delay <secs>  Delay between restarts with ±30% jitter (default: 5)
+
+Examples:
+  niki --budget 500000 -- claude -p "your prompt" --verbose
+  niki --timeout 1800 --max-sends 5 -- claude -p "..." --model sonnet --verbose
+  niki --restart --max-restarts 10 -- gro --model gpt-5.2 "your prompt"`);
+  process.exit(1);
+}
+
+const nikiArgs = process.argv.slice(2, SEPARATOR);
+const childCmd = process.argv[SEPARATOR + 1];
+const childArgs = process.argv.slice(SEPARATOR + 2);
+
+const { values: opts } = parseArgs({
+  args: nikiArgs,
+  options: {
+    budget:          { type: 'string', default: '1000000' },
+    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' },
+    'abort-file':    { type: 'string' },
+    'poll-interval': { type: 'string', default: '1000' },
+    restart:         { type: 'boolean', default: false },
+    'max-restarts':  { type: 'string', default: '0' },
+    'restart-delay': { type: 'string', default: '5' },
+  },
+});
+
+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);
+const LOG_FILE      = opts.log;
+const STATE_FILE    = opts.state;
+const RESTART       = opts.restart;
+const MAX_RESTARTS  = parseInt(opts['max-restarts'], 10);
+const RESTART_DELAY_S = parseFloat(opts['restart-delay']);
+
+// --- State ---
+
+const state = {
+  startedAt: new Date().toISOString(),
+  pid: null,
+  tokensIn: 0,
+  tokensOut: 0,
+  tokensTotal: 0,
+  toolCalls: 0,
+  sendCalls: 0,
+  toolCallsThisMinute: 0,
+  sendCallsThisMinute: 0,
+  exitCode: null,
+  exitSignal: null,
+  killedBy: null,    // 'budget' | 'timeout' | 'rate-sends' | 'rate-tools' | 'abort' | 'stall' | 'dead-air' | null
+  duration: 0,
+  stallEvents: 0,
+  nudges: 0,
+  deadAirChecks: 0,
+  restarts: 0,
+};
+
+// Sliding window for per-minute rate limiting
+const toolCallTimestamps = [];
+const sendCallTimestamps = [];
+
+// --- Logging ---
+
+let logStream = null;
+if (LOG_FILE) {
+  mkdirSync(dirname(resolve(LOG_FILE)), { recursive: true });
+  logStream = createWriteStream(resolve(LOG_FILE), { flags: 'a' });
+}
+
+function log(msg) {
+  const line = `[${new Date().toISOString()}] ${msg}`;
+  if (logStream) logStream.write(line + '\n');
+  // Also write to stderr so supervisor can capture it
+  process.stderr.write(`[niki] ${line}\n`);
+}
+
+function writeState() {
+  if (!STATE_FILE) return;
+  try {
+    mkdirSync(dirname(resolve(STATE_FILE)), { recursive: true });
+    // Never include env, tokens, or message content — only counters
+    writeFileSync(resolve(STATE_FILE), JSON.stringify(state, null, 2) + '\n');
+  } catch {
+    // Best effort
+  }
+}
+
+// --- Token parsing from stderr ---
+
+// Claude --verbose outputs token usage in stderr. Patterns vary by version.
+// We look for common patterns and extract numbers.
+//
+// Known patterns:
+//   "input_tokens": 1234
+//   "output_tokens": 567
+//   tokens: { input: 1234, output: 567 }
+//   Input tokens: 1234
+//   Output tokens: 567
+
+const TOKEN_PATTERNS = [
+  // JSON-style: "input_tokens": 1234
+  { regex: /"input_tokens"\s*:\s*(\d+)/g, field: 'in' },
+  { regex: /"output_tokens"\s*:\s*(\d+)/g, field: 'out' },
+  // Human-readable: Input tokens: 1234
+  { regex: /Input tokens:\s*(\d+)/gi, field: 'in' },
+  { regex: /Output tokens:\s*(\d+)/gi, field: 'out' },
+];
+
+function parseTokens(line) {
+  for (const { regex, field } of TOKEN_PATTERNS) {
+    regex.lastIndex = 0;
+    let match;
+    while ((match = regex.exec(line)) !== null) {
+      const count = parseInt(match[1], 10);
+      if (isNaN(count) || count <= 0) continue;
+      if (field === 'in') {
+        state.tokensIn = Math.max(state.tokensIn, count);
+      } else {
+        state.tokensOut = Math.max(state.tokensOut, count);
+      }
+      state.tokensTotal = state.tokensIn + state.tokensOut;
+    }
+  }
+}
+
+// --- Tool call detection from stderr ---
+
+// Claude --verbose logs tool calls. We detect sends specifically.
+const TOOL_CALL_PATTERN = /(?:Using tool|Tool call|tool_use).*?(\w+)/i;
+const SEND_PATTERN = /agentchat_send/i;
+
+function parseToolCall(line) {
+  if (TOOL_CALL_PATTERN.test(line)) {
+    const now = Date.now();
+    state.toolCalls++;
+    toolCallTimestamps.push(now);
+
+    if (SEND_PATTERN.test(line)) {
+      state.sendCalls++;
+      sendCallTimestamps.push(now);
+    }
+  }
+}
+
+// --- Rate limit checking ---
+
+function pruneWindow(timestamps) {
+  const cutoff = Date.now() - 60_000; // 1 minute window
+  while (timestamps.length > 0 && timestamps[0] < cutoff) {
+    timestamps.shift();
+  }
+}
+
+function checkRateLimits() {
+  pruneWindow(toolCallTimestamps);
+  pruneWindow(sendCallTimestamps);
+
+  state.toolCallsThisMinute = toolCallTimestamps.length;
+  state.sendCallsThisMinute = sendCallTimestamps.length;
+
+  if (sendCallTimestamps.length > MAX_SENDS) {
+    return 'rate-sends';
+  }
+  if (toolCallTimestamps.length > MAX_TOOL_CALLS) {
+    return 'rate-tools';
+  }
+  return null;
+}
+
+// --- Kill logic ---
+
+let child = null;
+let killed = false;
+
+function killChild(reason) {
+  if (killed || !child) return;
+  killed = true;
+  state.killedBy = reason;
+  log(`KILL — reason: ${reason} | tokens: ${state.tokensTotal}/${BUDGET} | sends: ${state.sendCallsThisMinute}/min | tools: ${state.toolCallsThisMinute}/min`);
+
+  child.kill('SIGTERM');
+
+  // Grace period, then SIGKILL
+  setTimeout(() => {
+    try {
+      child.kill('SIGKILL');
+    } catch {
+      // Already dead
+    }
+  }, 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;
+}
+
+// --- Jitter utility ---
+
+function jitteredDelay(base) {
+  // ±30% jitter
+  const jitter = base * 0.3;
+  return base + (Math.random() * 2 * jitter - jitter);
+}
+
+// --- 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');
+}
+
+// --- Restart logic ---
+
+// Reasons that should NOT trigger a restart (hard limits / operator intent)
+const NO_RESTART_REASONS = new Set(['budget', 'rate-sends', 'rate-tools', 'abort']);
+let nikiTerminated = false; // Set when niki itself receives SIGTERM/SIGINT
+
+function shouldRestart(code, signal) {
+  if (!RESTART) return false;
+  if (nikiTerminated) return false;
+  if (state.killedBy && NO_RESTART_REASONS.has(state.killedBy)) return false;
+  if (MAX_RESTARTS > 0 && state.restarts >= MAX_RESTARTS) return false;
+  return true;
+}
+
+function resetPerRunState() {
+  // Reset per-run flags but keep cumulative counters (tokens, toolCalls, etc.)
+  killed = false;
+  state.killedBy = null;
+  state.exitCode = null;
+  state.exitSignal = null;
+  state.gotFirstOutput = undefined;
+
+  // Reset stall/dead-air detection
+  nudgeCount = 0;
+  stdinClosed = false;
+  lastOutputTime = Date.now();
+  gotFirstOutput = false;
+  lastCpuMs = null;
+  deadAirStart = null;
+
+  // Clear rate limit windows (fresh session)
+  toolCallTimestamps.length = 0;
+  sendCallTimestamps.length = 0;
+  state.toolCallsThisMinute = 0;
+  state.sendCallsThisMinute = 0;
+}
+
+// --- Abort file polling ---
+
+let abortPollId = null;
+
+function scheduleAbortPoll() {
+  if (!ABORT_FILE || killed) return;
+  abortPollId = setTimeout(() => {
+    if (killed) return;
+    if (existsSync(ABORT_FILE)) {
+      log(`Abort file detected: ${ABORT_FILE}`);
+      killChild('abort');
+      return;
+    }
+    scheduleAbortPoll();
+  }, jitteredDelay(POLL_INTERVAL));
+}
+
+// --- Spawn and monitor child ---
+
+let timeoutId = null;
+
+function startChild() {
+  log(`Starting: ${childCmd} ${childArgs.join(' ').substring(0, 100)}...`);
+  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`);
+  if (RESTART) {
+    log(`Restart: enabled | max: ${MAX_RESTARTS || 'unlimited'} | delay: ${RESTART_DELAY_S}s ±30% | restarts so far: ${state.restarts}`);
+  }
+
+  child = spawn(childCmd, childArgs, {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: process.env,
+  });
+
+  state.pid = child.pid;
+
+  // Close stdin immediately — claude -p should never need interactive input.
+  closeStdin();
+
+  // --- Monitor stdout ---
+
+  child.stdout.on('data', (chunk) => {
+    process.stdout.write(chunk);
+    onChildOutput();
+    checkForPrompts(chunk.toString());
+  });
+
+  // --- Monitor stderr ---
+
+  let stderrBuffer = '';
+
+  child.stderr.on('data', (chunk) => {
+    const text = chunk.toString();
+    process.stderr.write(chunk);
+    onChildOutput();
+
+    stderrBuffer += text;
+    const lines = stderrBuffer.split('\n');
+    stderrBuffer = lines.pop();
+
+    for (const line of lines) {
+      parseTokens(line);
+      parseToolCall(line);
+
+      if (state.tokensTotal > BUDGET) {
+        killChild('budget');
+        return;
+      }
+
+      const rateViolation = checkRateLimits();
+      if (rateViolation) {
+        killChild(rateViolation);
+        return;
+      }
+    }
+  });
+
+  // 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
+  if (ABORT_FILE) {
+    log(`Abort file: ${ABORT_FILE} (poll: ${POLL_INTERVAL}ms ±30% jitter)`);
+    scheduleAbortPoll();
+  }
+
+  // Per-run timeout
+  timeoutId = setTimeout(() => {
+    killChild('timeout');
+  }, TIMEOUT_S * 1000);
+
+  // --- Exit handler ---
+
+  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);
+    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}` : ''} | restarts: ${state.restarts}`);
+    writeState();
+
+    if (shouldRestart(code, signal)) {
+      state.restarts++;
+      const delay = jitteredDelay(RESTART_DELAY_S * 1000);
+      log(`RESTART — attempt ${state.restarts}${MAX_RESTARTS > 0 ? `/${MAX_RESTARTS}` : ''} in ${Math.round(delay / 1000)}s`);
+      resetPerRunState();
+      setTimeout(() => {
+        startChild();
+      }, delay);
+    } else {
+      if (RESTART && !shouldRestart(code, signal)) {
+        const reason = nikiTerminated ? 'niki received signal' :
+          (state.killedBy && NO_RESTART_REASONS.has(state.killedBy)) ? `hard kill (${state.killedBy})` :
+          (MAX_RESTARTS > 0 && state.restarts >= MAX_RESTARTS) ? `max restarts reached (${MAX_RESTARTS})` :
+          'restart not enabled';
+        log(`NOT RESTARTING — ${reason}`);
+      }
+      if (logStream) logStream.end();
+      process.exit(code ?? 1);
+    }
+  });
+}
+
+// --- Signal forwarding ---
+
+for (const sig of ['SIGINT', 'SIGTERM']) {
+  process.on(sig, () => {
+    log(`Received ${sig}, forwarding to child`);
+    nikiTerminated = true;
+    if (child) child.kill(sig);
+  });
+}
+
+// --- Start ---
+
+startChild();

package/package.json

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