@tjamescouch/niki 0.5.0 → 0.5.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+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

@@ -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...]
@@ -38,18 +39,24 @@ Options:
   --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=no stall until first output)
+  --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
+  --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();
 }
@@ -409,8 +485,6 @@ function currentStallTimeout() {
 
 function resetStallTimer() {
   if (stallTimer) clearTimeout(stallTimer);
-  // startup-timeout=0 means "wait indefinitely for first output"
-  if (!gotFirstOutput && STARTUP_TIMEOUT_S === 0) return;
   const timeout = currentStallTimeout();
   if (killed || timeout <= 0) return;
   stallTimer = setTimeout(onStallDetected, timeout * 1000);
@@ -420,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) {
@@ -439,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;
   }
@@ -449,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;
     }
@@ -457,138 +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) {
-  const startupMsg = STARTUP_TIMEOUT_S === 0 ? 'disabled (waiting for first output)' : `${STARTUP_TIMEOUT_S}s`;
-  log(`Stall detection: startup-timeout=${startupMsg}, 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/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@tjamescouch/niki",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Deterministic process supervisor for AI agents — token budgets, rate limits, and abort control",
   "bin": {
     "niki": "./bin/niki"
   },
+  "files": [
+    "bin/niki",
+    "README.md",
+    "LICENSE"
+  ],
   "type": "module",
   "license": "MIT",
   "repository": {

package/tests/test-niki.sh

@@ -1,275 +0,0 @@
-#!/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"