@wrongstack/tools 0.5.6 → 0.5.7

package/dist/circuit-breaker.d.ts

@@ -0,0 +1,111 @@
+/**
+ * CircuitBreaker — prevents runaway bash/exec tool chains by:
+ *
+ *   - Tripping on consecutive failures (models that keep repeating the
+ *     same failing command, e.g. `npm install` with wrong args in a loop)
+ *   - Tripping on slow call ratio (too many long-running commands suggest
+ *     a hung subprocess that the model doesn't know how to kill)
+ *   - Rate-limiting bursts (rapid succession of commands without reading
+ *     output suggests the model isn't processing results)
+ *   - Auto-recovering after a cooldown period so a fixed model can resume
+ *
+ * The breaker is owned by the ProcessRegistry so any tool that registers
+ * a process participates in the same circuit. "Per-tool" isolation is
+ * intentionally NOT implemented — the model treats bash/exec as one
+ * resource pool; isolating them would let the model route around the
+ * breaker by alternating which tool it uses.
+ */
+interface CircuitBreakerConfig {
+    /**
+     * Consecutive failures before trip. Default: 5.
+     * A single success resets this counter to 0.
+     */
+    maxConsecutiveFailures?: number;
+    /**
+     * Slow-call threshold in ms. A call that runs longer than this is
+     * counted as "slow". Default: 60_000 (1 minute).
+     */
+    slowCallThresholdMs?: number;
+    /**
+     * Max slow calls before trip (within the sliding window). Default: 3.
+     */
+    maxSlowCalls?: number;
+    /**
+     * Sliding window for rate-limit and slow-call counting, in ms.
+     * Default: 60_000 (1 minute).
+     */
+    windowMs?: number;
+    /**
+     * Max calls within the sliding window. Default: 30.
+     * Burst exceeding this trips the breaker immediately.
+     */
+    maxCallsPerWindow?: number;
+    /**
+     * Cooldown before auto-recovery attempt, in ms. Default: 30_000 (30s).
+     * After this the breaker enters "half-open" state and allows one call
+     * through to test whether the problem is resolved.
+     */
+    cooldownMs?: number;
+}
+interface CircuitBreakerSnapshot {
+    state: 'closed' | 'open' | 'half-open';
+    consecutiveFailures: number;
+    slowCallsInWindow: number;
+    callsInWindow: number;
+    windowMs: number;
+    cooldownRemainingMs: number | null;
+    lastFailureAt: number | null;
+    lastSlowAt: number | null;
+}
+declare class CircuitBreaker {
+    private readonly maxConsecutiveFailures;
+    private readonly slowCallThresholdMs;
+    private readonly maxSlowCalls;
+    private readonly windowMs;
+    private readonly maxCallsPerWindow;
+    private readonly cooldownMs;
+    private state;
+    private consecutiveFailures;
+    private window;
+    private lastFailureAt;
+    private lastSlowAt;
+    /** Timestamp when the breaker was opened (for cooldown calculation). */
+    private openedAt;
+    /** Timestamp when the last call ran (for half-open gate). */
+    private lastCallAt;
+    constructor(config?: CircuitBreakerConfig);
+    /**
+     * Returns true if the circuit allows a new call to proceed.
+     * When false, callers should abort the tool call and return a
+     * circuit-breaker error instead of spawning a process.
+     */
+    get canProceed(): boolean;
+    /**
+     * Snapshot of the current breaker state for observability (`/kill`).
+     */
+    snapshot(): CircuitBreakerSnapshot;
+    /**
+     * Call this BEFORE spawning a bash/exec process.
+     * Returns true if the call is allowed; false if the breaker is open.
+     * When false, callers MUST NOT spawn a process.
+     */
+    beforeCall(): boolean;
+    /**
+     * Call this AFTER a bash/exec process finishes (success or failure).
+     * `durationMs` is the wall-clock time the process ran.
+     * `failed` is true when the process returned a non-zero exit code or
+     * threw an exception before spawning.
+     */
+    afterCall(durationMs: number, failed: boolean): void;
+    /** Force the breaker open. Used by /kill force and Ctrl+C. */
+    forceOpen(): void;
+    /** Force a reset to closed. Used by tests and /kill reset. */
+    forceReset(): void;
+    private _trip;
+    private _reset;
+    /** Transition from open → half-open when cooldown elapses. */
+    private _checkStateTransition;
+    private _pruneWindow;
+}
+
+export { CircuitBreaker, type CircuitBreakerConfig, type CircuitBreakerSnapshot };

package/dist/circuit-breaker.js

@@ -0,0 +1,150 @@
+// src/circuit-breaker.ts
+var DEFAULT_MAX_CONSECUTIVE_FAILURES = 5;
+var DEFAULT_SLOW_CALL_THRESHOLD_MS = 6e4;
+var DEFAULT_MAX_SLOW_CALLS = 3;
+var DEFAULT_WINDOW_MS = 6e4;
+var DEFAULT_MAX_CALLS_PER_WINDOW = 30;
+var DEFAULT_COOLDOWN_MS = 3e4;
+var CircuitBreaker = class {
+  maxConsecutiveFailures;
+  slowCallThresholdMs;
+  maxSlowCalls;
+  windowMs;
+  maxCallsPerWindow;
+  cooldownMs;
+  state = "closed";
+  consecutiveFailures = 0;
+  window = [];
+  lastFailureAt = null;
+  lastSlowAt = null;
+  /** Timestamp when the breaker was opened (for cooldown calculation). */
+  openedAt = null;
+  /** Timestamp when the last call ran (for half-open gate). */
+  lastCallAt = null;
+  constructor(config = {}) {
+    this.maxConsecutiveFailures = config.maxConsecutiveFailures ?? DEFAULT_MAX_CONSECUTIVE_FAILURES;
+    this.slowCallThresholdMs = config.slowCallThresholdMs ?? DEFAULT_SLOW_CALL_THRESHOLD_MS;
+    this.maxSlowCalls = config.maxSlowCalls ?? DEFAULT_MAX_SLOW_CALLS;
+    this.windowMs = config.windowMs ?? DEFAULT_WINDOW_MS;
+    this.maxCallsPerWindow = config.maxCallsPerWindow ?? DEFAULT_MAX_CALLS_PER_WINDOW;
+    this.cooldownMs = config.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+  }
+  /**
+   * Returns true if the circuit allows a new call to proceed.
+   * When false, callers should abort the tool call and return a
+   * circuit-breaker error instead of spawning a process.
+   */
+  get canProceed() {
+    this._checkStateTransition();
+    return this.state !== "open";
+  }
+  /**
+   * Snapshot of the current breaker state for observability (`/kill`).
+   */
+  snapshot() {
+    this._checkStateTransition();
+    const now = Date.now();
+    let cooldownRemaining = null;
+    if (this.openedAt !== null && this.state === "open") {
+      const elapsed = now - this.openedAt;
+      cooldownRemaining = Math.max(0, this.cooldownMs - elapsed);
+    }
+    return {
+      state: this.state,
+      consecutiveFailures: this.consecutiveFailures,
+      slowCallsInWindow: this.window.filter((c) => c.slow).length,
+      callsInWindow: this.window.length,
+      windowMs: this.windowMs,
+      cooldownRemainingMs: cooldownRemaining,
+      lastFailureAt: this.lastFailureAt,
+      lastSlowAt: this.lastSlowAt
+    };
+  }
+  /**
+   * Call this BEFORE spawning a bash/exec process.
+   * Returns true if the call is allowed; false if the breaker is open.
+   * When false, callers MUST NOT spawn a process.
+   */
+  beforeCall() {
+    this._checkStateTransition();
+    if (this.state === "open") return false;
+    return true;
+  }
+  /**
+   * Call this AFTER a bash/exec process finishes (success or failure).
+   * `durationMs` is the wall-clock time the process ran.
+   * `failed` is true when the process returned a non-zero exit code or
+   * threw an exception before spawning.
+   */
+  afterCall(durationMs, failed) {
+    const now = Date.now();
+    this.lastCallAt = now;
+    if (this.state === "half-open") {
+      if (failed) {
+        this._trip();
+        return;
+      }
+      this._reset();
+      return;
+    }
+    this._pruneWindow(now);
+    const slow = durationMs >= this.slowCallThresholdMs;
+    this.window.push({ at: now, failed, slow });
+    if (failed) {
+      this.consecutiveFailures++;
+      this.lastFailureAt = now;
+      if (this.consecutiveFailures >= this.maxConsecutiveFailures) {
+        this._trip();
+      }
+      return;
+    }
+    this.consecutiveFailures = 0;
+    if (slow) {
+      this.lastSlowAt = now;
+      const slowCount = this.window.filter((c) => c.slow).length;
+      if (slowCount >= this.maxSlowCalls) {
+        this._trip();
+      }
+    }
+    const callCount = this.window.length;
+    if (callCount >= this.maxCallsPerWindow) {
+      this._trip();
+    }
+  }
+  /** Force the breaker open. Used by /kill force and Ctrl+C. */
+  forceOpen() {
+    this._trip();
+  }
+  /** Force a reset to closed. Used by tests and /kill reset. */
+  forceReset() {
+    this._reset();
+  }
+  _trip() {
+    if (this.state === "open") return;
+    this.state = "open";
+    this.openedAt = Date.now();
+  }
+  _reset() {
+    this.state = "closed";
+    this.consecutiveFailures = 0;
+    this.window = [];
+    this.openedAt = null;
+  }
+  /** Transition from open → half-open when cooldown elapses. */
+  _checkStateTransition() {
+    if (this.state !== "open" || this.openedAt === null) return;
+    const elapsed = Date.now() - this.openedAt;
+    if (elapsed >= this.cooldownMs) {
+      this.state = "half-open";
+      this.openedAt = null;
+    }
+  }
+  _pruneWindow(now) {
+    const cutoff = now - this.windowMs;
+    this.window = this.window.filter((c) => c.at >= cutoff);
+  }
+};
+
+export { CircuitBreaker };
+//# sourceMappingURL=circuit-breaker.js.map
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"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","file":"circuit-breaker.js","sourcesContent":["/**\n * CircuitBreaker — prevents runaway bash/exec tool chains by:\n *\n *   - Tripping on consecutive failures (models that keep repeating the\n *     same failing command, e.g. `npm install` with wrong args in a loop)\n *   - Tripping on slow call ratio (too many long-running commands suggest\n *     a hung subprocess that the model doesn't know how to kill)\n *   - Rate-limiting bursts (rapid succession of commands without reading\n *     output suggests the model isn't processing results)\n *   - Auto-recovering after a cooldown period so a fixed model can resume\n *\n * The breaker is owned by the ProcessRegistry so any tool that registers\n * a process participates in the same circuit. \"Per-tool\" isolation is\n * intentionally NOT implemented — the model treats bash/exec as one\n * resource pool; isolating them would let the model route around the\n * breaker by alternating which tool it uses.\n */\n\nexport interface CircuitBreakerConfig {\n  /**\n   * Consecutive failures before trip. Default: 5.\n   * A single success resets this counter to 0.\n   */\n  maxConsecutiveFailures?: number;\n  /**\n   * Slow-call threshold in ms. A call that runs longer than this is\n   * counted as \"slow\". Default: 60_000 (1 minute).\n   */\n  slowCallThresholdMs?: number;\n  /**\n   * Max slow calls before trip (within the sliding window). Default: 3.\n   */\n  maxSlowCalls?: number;\n  /**\n   * Sliding window for rate-limit and slow-call counting, in ms.\n   * Default: 60_000 (1 minute).\n   */\n  windowMs?: number;\n  /**\n   * Max calls within the sliding window. Default: 30.\n   * Burst exceeding this trips the breaker immediately.\n   */\n  maxCallsPerWindow?: number;\n  /**\n   * Cooldown before auto-recovery attempt, in ms. Default: 30_000 (30s).\n   * After this the breaker enters \"half-open\" state and allows one call\n   * through to test whether the problem is resolved.\n   */\n  cooldownMs?: number;\n}\n\ninterface CallRecord {\n  at: number;\n  /** True if the call threw or returned an is_error result. */\n  failed: boolean;\n  /** True if elapsed time exceeded slowCallThresholdMs. */\n  slow: boolean;\n}\n\ntype BreakerState = 'closed' | 'open' | 'half-open';\n\nconst DEFAULT_MAX_CONSECUTIVE_FAILURES = 5;\nconst DEFAULT_SLOW_CALL_THRESHOLD_MS = 60_000;\nconst DEFAULT_MAX_SLOW_CALLS = 3;\nconst DEFAULT_WINDOW_MS = 60_000;\nconst DEFAULT_MAX_CALLS_PER_WINDOW = 30;\nconst DEFAULT_COOLDOWN_MS = 30_000;\n\nexport interface CircuitBreakerSnapshot {\n  state: 'closed' | 'open' | 'half-open';\n  consecutiveFailures: number;\n  slowCallsInWindow: number;\n  callsInWindow: number;\n  windowMs: number;\n  cooldownRemainingMs: number | null;\n  lastFailureAt: number | null;\n  lastSlowAt: number | null;\n}\n\nexport class CircuitBreaker {\n  private readonly maxConsecutiveFailures: number;\n  private readonly slowCallThresholdMs: number;\n  private readonly maxSlowCalls: number;\n  private readonly windowMs: number;\n  private readonly maxCallsPerWindow: number;\n  private readonly cooldownMs: number;\n\n  private state: BreakerState = 'closed';\n  private consecutiveFailures = 0;\n  private window: CallRecord[] = [];\n  private lastFailureAt: number | null = null;\n  private lastSlowAt: number | null = null;\n  /** Timestamp when the breaker was opened (for cooldown calculation). */\n  private openedAt: number | null = null;\n  /** Timestamp when the last call ran (for half-open gate). */\n  private lastCallAt: number | null = null;\n\n  constructor(config: CircuitBreakerConfig = {}) {\n    this.maxConsecutiveFailures = config.maxConsecutiveFailures ?? DEFAULT_MAX_CONSECUTIVE_FAILURES;\n    this.slowCallThresholdMs = config.slowCallThresholdMs ?? DEFAULT_SLOW_CALL_THRESHOLD_MS;\n    this.maxSlowCalls = config.maxSlowCalls ?? DEFAULT_MAX_SLOW_CALLS;\n    this.windowMs = config.windowMs ?? DEFAULT_WINDOW_MS;\n    this.maxCallsPerWindow = config.maxCallsPerWindow ?? DEFAULT_MAX_CALLS_PER_WINDOW;\n    this.cooldownMs = config.cooldownMs ?? DEFAULT_COOLDOWN_MS;\n  }\n\n  /**\n   * Returns true if the circuit allows a new call to proceed.\n   * When false, callers should abort the tool call and return a\n   * circuit-breaker error instead of spawning a process.\n   */\n  get canProceed(): boolean {\n    this._checkStateTransition();\n    return this.state !== 'open';\n  }\n\n  /**\n   * Snapshot of the current breaker state for observability (`/kill`).\n   */\n  snapshot(): CircuitBreakerSnapshot {\n    this._checkStateTransition();\n    const now = Date.now();\n    let cooldownRemaining: number | null = null;\n    if (this.openedAt !== null && this.state === 'open') {\n      const elapsed = now - this.openedAt;\n      cooldownRemaining = Math.max(0, this.cooldownMs - elapsed);\n    }\n    return {\n      state: this.state,\n      consecutiveFailures: this.consecutiveFailures,\n      slowCallsInWindow: this.window.filter((c) => c.slow).length,\n      callsInWindow: this.window.length,\n      windowMs: this.windowMs,\n      cooldownRemainingMs: cooldownRemaining,\n      lastFailureAt: this.lastFailureAt,\n      lastSlowAt: this.lastSlowAt,\n    };\n  }\n\n  /**\n   * Call this BEFORE spawning a bash/exec process.\n   * Returns true if the call is allowed; false if the breaker is open.\n   * When false, callers MUST NOT spawn a process.\n   */\n  beforeCall(): boolean {\n    this._checkStateTransition();\n    if (this.state === 'open') return false;\n    return true;\n  }\n\n  /**\n   * Call this AFTER a bash/exec process finishes (success or failure).\n   * `durationMs` is the wall-clock time the process ran.\n   * `failed` is true when the process returned a non-zero exit code or\n   * threw an exception before spawning.\n   */\n  afterCall(durationMs: number, failed: boolean): void {\n    const now = Date.now();\n    this.lastCallAt = now;\n\n    if (this.state === 'half-open') {\n      // First call through after cooldown — if it failed, go back to open.\n      if (failed) {\n        this._trip();\n        return;\n      }\n      // Success in half-open → reset to closed.\n      this._reset();\n      return;\n    }\n\n    // Prune old records outside the sliding window.\n    this._pruneWindow(now);\n\n    const slow = durationMs >= this.slowCallThresholdMs;\n    this.window.push({ at: now, failed, slow });\n\n    if (failed) {\n      this.consecutiveFailures++;\n      this.lastFailureAt = now;\n      if (this.consecutiveFailures >= this.maxConsecutiveFailures) {\n        this._trip();\n      }\n      return;\n    }\n\n    // Success: reset consecutive failure counter.\n    this.consecutiveFailures = 0;\n\n    if (slow) {\n      this.lastSlowAt = now;\n      const slowCount = this.window.filter((c) => c.slow).length;\n      if (slowCount >= this.maxSlowCalls) {\n        this._trip();\n      }\n    }\n\n    const callCount = this.window.length;\n    if (callCount >= this.maxCallsPerWindow) {\n      // Rate limit exceeded. This is a soft trip — we reset the window\n      // and let the next call try immediately (the caller will still see\n      // canProceed=false until the window drains naturally).\n      this._trip();\n    }\n  }\n\n  /** Force the breaker open. Used by /kill force and Ctrl+C. */\n  forceOpen(): void {\n    this._trip();\n  }\n\n  /** Force a reset to closed. Used by tests and /kill reset. */\n  forceReset(): void {\n    this._reset();\n  }\n\n  private _trip(): void {\n    if (this.state === 'open') return; // already open\n    this.state = 'open';\n    this.openedAt = Date.now();\n  }\n\n  private _reset(): void {\n    this.state = 'closed';\n    this.consecutiveFailures = 0;\n    this.window = [];\n    this.openedAt = null;\n  }\n\n  /** Transition from open → half-open when cooldown elapses. */\n  private _checkStateTransition(): void {\n    if (this.state !== 'open' || this.openedAt === null) return;\n    const elapsed = Date.now() - this.openedAt;\n    if (elapsed >= this.cooldownMs) {\n      this.state = 'half-open';\n      this.openedAt = null;\n    }\n  }\n\n  private _pruneWindow(now: number): void {\n    const cutoff = now - this.windowMs;\n    this.window = this.window.filter((c) => c.at >= cutoff);\n  }\n}"]}

package/dist/exec.js

@@ -1,9 +1,327 @@
 import { spawn } from 'child_process';
 import * as path from 'path';
 import { buildChildEnv } from '@wrongstack/core';
+import * as os from 'os';
 
 // src/exec.ts
 
+// src/circuit-breaker.ts
+var DEFAULT_MAX_CONSECUTIVE_FAILURES = 5;
+var DEFAULT_SLOW_CALL_THRESHOLD_MS = 6e4;
+var DEFAULT_MAX_SLOW_CALLS = 3;
+var DEFAULT_WINDOW_MS = 6e4;
+var DEFAULT_MAX_CALLS_PER_WINDOW = 30;
+var DEFAULT_COOLDOWN_MS = 3e4;
+var CircuitBreaker = class {
+  maxConsecutiveFailures;
+  slowCallThresholdMs;
+  maxSlowCalls;
+  windowMs;
+  maxCallsPerWindow;
+  cooldownMs;
+  state = "closed";
+  consecutiveFailures = 0;
+  window = [];
+  lastFailureAt = null;
+  lastSlowAt = null;
+  /** Timestamp when the breaker was opened (for cooldown calculation). */
+  openedAt = null;
+  /** Timestamp when the last call ran (for half-open gate). */
+  lastCallAt = null;
+  constructor(config = {}) {
+    this.maxConsecutiveFailures = config.maxConsecutiveFailures ?? DEFAULT_MAX_CONSECUTIVE_FAILURES;
+    this.slowCallThresholdMs = config.slowCallThresholdMs ?? DEFAULT_SLOW_CALL_THRESHOLD_MS;
+    this.maxSlowCalls = config.maxSlowCalls ?? DEFAULT_MAX_SLOW_CALLS;
+    this.windowMs = config.windowMs ?? DEFAULT_WINDOW_MS;
+    this.maxCallsPerWindow = config.maxCallsPerWindow ?? DEFAULT_MAX_CALLS_PER_WINDOW;
+    this.cooldownMs = config.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+  }
+  /**
+   * Returns true if the circuit allows a new call to proceed.
+   * When false, callers should abort the tool call and return a
+   * circuit-breaker error instead of spawning a process.
+   */
+  get canProceed() {
+    this._checkStateTransition();
+    return this.state !== "open";
+  }
+  /**
+   * Snapshot of the current breaker state for observability (`/kill`).
+   */
+  snapshot() {
+    this._checkStateTransition();
+    const now = Date.now();
+    let cooldownRemaining = null;
+    if (this.openedAt !== null && this.state === "open") {
+      const elapsed = now - this.openedAt;
+      cooldownRemaining = Math.max(0, this.cooldownMs - elapsed);
+    }
+    return {
+      state: this.state,
+      consecutiveFailures: this.consecutiveFailures,
+      slowCallsInWindow: this.window.filter((c) => c.slow).length,
+      callsInWindow: this.window.length,
+      windowMs: this.windowMs,
+      cooldownRemainingMs: cooldownRemaining,
+      lastFailureAt: this.lastFailureAt,
+      lastSlowAt: this.lastSlowAt
+    };
+  }
+  /**
+   * Call this BEFORE spawning a bash/exec process.
+   * Returns true if the call is allowed; false if the breaker is open.
+   * When false, callers MUST NOT spawn a process.
+   */
+  beforeCall() {
+    this._checkStateTransition();
+    if (this.state === "open") return false;
+    return true;
+  }
+  /**
+   * Call this AFTER a bash/exec process finishes (success or failure).
+   * `durationMs` is the wall-clock time the process ran.
+   * `failed` is true when the process returned a non-zero exit code or
+   * threw an exception before spawning.
+   */
+  afterCall(durationMs, failed) {
+    const now = Date.now();
+    this.lastCallAt = now;
+    if (this.state === "half-open") {
+      if (failed) {
+        this._trip();
+        return;
+      }
+      this._reset();
+      return;
+    }
+    this._pruneWindow(now);
+    const slow = durationMs >= this.slowCallThresholdMs;
+    this.window.push({ at: now, failed, slow });
+    if (failed) {
+      this.consecutiveFailures++;
+      this.lastFailureAt = now;
+      if (this.consecutiveFailures >= this.maxConsecutiveFailures) {
+        this._trip();
+      }
+      return;
+    }
+    this.consecutiveFailures = 0;
+    if (slow) {
+      this.lastSlowAt = now;
+      const slowCount = this.window.filter((c) => c.slow).length;
+      if (slowCount >= this.maxSlowCalls) {
+        this._trip();
+      }
+    }
+    const callCount = this.window.length;
+    if (callCount >= this.maxCallsPerWindow) {
+      this._trip();
+    }
+  }
+  /** Force the breaker open. Used by /kill force and Ctrl+C. */
+  forceOpen() {
+    this._trip();
+  }
+  /** Force a reset to closed. Used by tests and /kill reset. */
+  forceReset() {
+    this._reset();
+  }
+  _trip() {
+    if (this.state === "open") return;
+    this.state = "open";
+    this.openedAt = Date.now();
+  }
+  _reset() {
+    this.state = "closed";
+    this.consecutiveFailures = 0;
+    this.window = [];
+    this.openedAt = null;
+  }
+  /** Transition from open → half-open when cooldown elapses. */
+  _checkStateTransition() {
+    if (this.state !== "open" || this.openedAt === null) return;
+    const elapsed = Date.now() - this.openedAt;
+    if (elapsed >= this.cooldownMs) {
+      this.state = "half-open";
+      this.openedAt = null;
+    }
+  }
+  _pruneWindow(now) {
+    const cutoff = now - this.windowMs;
+    this.window = this.window.filter((c) => c.at >= cutoff);
+  }
+};
+
+// src/process-registry.ts
+var DEFAULT_GRACE_MS = 2e3;
+var ProcessRegistryImpl = class {
+  processes = /* @__PURE__ */ new Map();
+  breaker;
+  constructor(breakerConfig) {
+    this.breaker = new CircuitBreaker(breakerConfig);
+  }
+  register(info) {
+    this.processes.set(info.pid, { ...info, killed: false });
+  }
+  /** Unregister a process by PID. Called on 'close' / 'exit' events. */
+  unregister(pid) {
+    this.processes.delete(pid);
+  }
+  /** Get a single process by PID. */
+  get(pid) {
+    return this.processes.get(pid);
+  }
+  /** Get all tracked processes. */
+  list() {
+    return Array.from(this.processes.values());
+  }
+  /** Get processes filtered by name (e.g. 'bash', 'exec'). */
+  byName(name) {
+    return this.list().filter((p) => p.name === name);
+  }
+  /** Get processes filtered by session. */
+  bySession(sessionId) {
+    return this.list().filter((p) => p.sessionId === sessionId);
+  }
+  /** Count of active (non-killed) processes. */
+  get activeCount() {
+    let n = 0;
+    for (const p of this.processes.values()) {
+      if (!p.killed) n++;
+    }
+    return n;
+  }
+  /**
+   * Combined stats for observability — used by /ps and the TUI status bar.
+   */
+  stats() {
+    return {
+      activeCount: this.activeCount,
+      totalCount: this.processes.size,
+      breaker: this.breaker.snapshot()
+    };
+  }
+  /**
+   * Returns true if the circuit allows a new bash/exec call to proceed.
+   * When false, callers MUST NOT spawn a process.
+   */
+  get canProceed() {
+    return this.breaker.canProceed;
+  }
+  /**
+   * Called before spawning a process. Returns true if allowed; false if
+   * the circuit breaker is open.
+   */
+  beforeCall() {
+    return this.breaker.beforeCall();
+  }
+  /**
+   * Called after a process finishes. `durationMs` is wall-clock time;
+   * `failed` is true for non-zero exit codes.
+   */
+  afterCall(durationMs, failed) {
+    this.breaker.afterCall(durationMs, failed);
+  }
+  /** Force-open the circuit breaker (Ctrl+C, /kill force). */
+  forceBreakerOpen() {
+    this.breaker.forceOpen();
+  }
+  /** Force-reset the circuit breaker to closed (/kill reset). */
+  forceBreakerReset() {
+    this.breaker.forceReset();
+  }
+  /** Kill a single process by PID.
+   *
+   *  On POSIX: sends SIGTERM to the *process group* (-pid) so that
+   *  runaway grandchild processes (`sleep 9999 & disown`) are also killed.
+   *  After `graceMs` a SIGKILL is sent if the process hasn't exited.
+   *
+   *  On Windows: `child.kill()` maps to TerminateProcess — process groups
+   *  are not meaningfully supported. A second `force=true` call sends
+   *  SIGKILL (which maps to TerminateProcess again — the distinction is
+   *  in the exit code, not the signal).
+   *
+   *  Returns true if the process was found and kill was attempted.
+   */
+  kill(pid, opts = {}) {
+    const p = this.processes.get(pid);
+    if (!p) return false;
+    if (p.killed) return true;
+    const { force = false, graceMs = DEFAULT_GRACE_MS } = opts;
+    const isWin = os.platform() === "win32";
+    if (isWin) {
+      try {
+        p.child.kill(force ? "SIGKILL" : "SIGTERM");
+      } catch {
+      }
+      p.killed = true;
+      return true;
+    }
+    try {
+      if (force) {
+        try {
+          process.kill(-pid, "SIGKILL");
+        } catch {
+          p.child.kill("SIGKILL");
+        }
+      } else {
+        try {
+          process.kill(-pid, "SIGTERM");
+        } catch {
+          p.child.kill("SIGTERM");
+        }
+        const timer = setTimeout(() => {
+          if (this.processes.has(pid) && !p.child.killed) {
+            try {
+              process.kill(-pid, "SIGKILL");
+            } catch {
+              try {
+                p.child.kill("SIGKILL");
+              } catch {
+              }
+            }
+          }
+        }, graceMs);
+        timer.unref?.();
+      }
+    } catch {
+    }
+    p.killed = true;
+    return true;
+  }
+  /**
+   * Kill all tracked processes.
+   * Returns the PIDs that were kill()ed.
+   */
+  killAll(opts = {}) {
+    const pids = Array.from(this.processes.keys());
+    const killed = [];
+    for (const pid of pids) {
+      if (this.kill(pid, opts)) killed.push(pid);
+    }
+    return killed;
+  }
+  /**
+   * Kill all processes for a specific session.
+   * Returns the PIDs that were kill()ed.
+   */
+  killSession(sessionId, opts = {}) {
+    const pids = this.bySession(sessionId).map((p) => p.pid);
+    const killed = [];
+    for (const pid of pids) {
+      if (this.kill(pid, opts)) killed.push(pid);
+    }
+    return killed;
+  }
+};
+var _registry;
+function getProcessRegistry() {
+  if (!_registry) {
+    _registry = new ProcessRegistryImpl();
+  }
+  return _registry;
+}
+
 // src/exec.ts
 var ALLOWED_COMMANDS = {
   node: ["--version", "-r", "--input-type=module"],
@@ -102,6 +420,18 @@ var execTool = {
     required: ["command"]
   },
   async execute(input, ctx, opts) {
+    const registry = getProcessRegistry();
+    if (!registry.canProceed) {
+      return {
+        command: input.command,
+        args: input.args ?? [],
+        stdout: "",
+        stderr: "Circuit breaker is open \u2014 too many consecutive failures. Use /kill reset to recover.",
+        exitCode: 1,
+        truncated: false,
+        allowed: false
+      };
+    }
     const cmd = input.command.trim();
     if (!cmd)
       return {
@@ -161,15 +491,23 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
     let stdout = "";
     let stderr = "";
     let killed = false;
+    const startedAt = Date.now();
     const child = spawn(cmd, args, {
       cwd,
       signal,
       env: buildChildEnv(sessionId),
       stdio: ["ignore", "pipe", "pipe"]
     });
+    const registry = getProcessRegistry();
+    const pid = child.pid;
+    if (typeof pid === "number") {
+      const fullCommand = `${cmd} ${args.join(" ")}`;
+      registry.register({ pid, name: "exec", command: fullCommand, startedAt: Date.now(), sessionId, child });
+    }
     const timer = setTimeout(() => {
       killed = true;
-      child.kill("SIGTERM");
+      if (typeof pid === "number") registry.kill(pid);
+      else child.kill("SIGTERM");
     }, timeout);
     child.stdout?.on("data", (chunk) => {
       if (stdout.length < MAX_OUTPUT) stdout += chunk.toString();
@@ -179,18 +517,24 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
     });
     child.on("close", (code) => {
       clearTimeout(timer);
+      if (typeof pid === "number") registry.unregister(pid);
+      const durationMs = Date.now() - startedAt;
+      const exitCode = killed ? 124 : code ?? 1;
+      registry.afterCall(durationMs, exitCode !== 0);
       resolve2({
         command: cmd,
         args,
         stdout: stdout.slice(0, MAX_OUTPUT),
         stderr: stderr.slice(0, MAX_OUTPUT),
-        exitCode: killed ? 124 : code ?? 1,
+        exitCode,
         truncated: stdout.length >= MAX_OUTPUT || stderr.length >= MAX_OUTPUT,
         allowed: true
       });
     });
     child.on("error", (err) => {
       clearTimeout(timer);
+      if (typeof pid === "number") registry.unregister(pid);
+      registry.afterCall(Date.now() - startedAt, true);
       resolve2({
         command: cmd,
         args,