@wrongstack/tools 0.9.19 → 0.10.0

package/dist/circuit-breaker.d.ts

@@ -71,8 +71,6 @@ declare class CircuitBreaker {
     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.

package/dist/circuit-breaker.js

@@ -19,8 +19,6 @@ var CircuitBreaker = class {
   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;
@@ -78,7 +76,6 @@ var CircuitBreaker = class {
    */
   afterCall(durationMs, failed) {
     const now = Date.now();
-    this.lastCallAt = now;
     if (this.state === "half-open") {
       if (failed) {
         this._trip();

package/dist/circuit-breaker.js.map

@@ -1 +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}"]}
+{"version":3,"sources":["../src/circuit-breaker.ts"],"names":[],"mappings":";AA6DA,IAAM,gCAAA,GAAmC,CAAA;AACzC,IAAM,8BAAA,GAAiC,GAAA;AACvC,IAAM,sBAAA,GAAyB,CAAA;AAC/B,IAAM,iBAAA,GAAoB,GAAA;AAC1B,IAAM,4BAAA,GAA+B,EAAA;AACrC,IAAM,mBAAA,GAAsB,GAAA;AAarB,IAAM,iBAAN,MAAqB;AAAA,EACT,sBAAA;AAAA,EACA,mBAAA;AAAA,EACA,YAAA;AAAA,EACA,QAAA;AAAA,EACA,iBAAA;AAAA,EACA,UAAA;AAAA,EAET,KAAA,GAAsB,QAAA;AAAA,EACtB,mBAAA,GAAsB,CAAA;AAAA,EACtB,SAAuB,EAAC;AAAA,EACxB,aAAA,GAA+B,IAAA;AAAA,EAC/B,UAAA,GAA4B,IAAA;AAAA;AAAA,EAE5B,QAAA,GAA0B,IAAA;AAAA,EAElC,WAAA,CAAY,MAAA,GAA+B,EAAC,EAAG;AAC7C,IAAA,IAAA,CAAK,sBAAA,GAAyB,OAAO,sBAAA,IAA0B,gCAAA;AAC/D,IAAA,IAAA,CAAK,mBAAA,GAAsB,OAAO,mBAAA,IAAuB,8BAAA;AACzD,IAAA,IAAA,CAAK,YAAA,GAAe,OAAO,YAAA,IAAgB,sBAAA;AAC3C,IAAA,IAAA,CAAK,QAAA,GAAW,OAAO,QAAA,IAAY,iBAAA;AACnC,IAAA,IAAA,CAAK,iBAAA,GAAoB,OAAO,iBAAA,IAAqB,4BAAA;AACrD,IAAA,IAAA,CAAK,UAAA,GAAa,OAAO,UAAA,IAAc,mBAAA;AAAA,EACzC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAI,UAAA,GAAsB;AACxB,IAAA,IAAA,CAAK,qBAAA,EAAsB;AAC3B,IAAA,OAAO,KAAK,KAAA,KAAU,MAAA;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA,EAKA,QAAA,GAAmC;AACjC,IAAA,IAAA,CAAK,qBAAA,EAAsB;AAC3B,IAAA,MAAM,GAAA,GAAM,KAAK,GAAA,EAAI;AACrB,IAAA,IAAI,iBAAA,GAAmC,IAAA;AACvC,IAAA,IAAI,IAAA,CAAK,QAAA,KAAa,IAAA,IAAQ,IAAA,CAAK,UAAU,MAAA,EAAQ;AACnD,MAAA,MAAM,OAAA,GAAU,MAAM,IAAA,CAAK,QAAA;AAC3B,MAAA,iBAAA,GAAoB,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,IAAA,CAAK,aAAa,OAAO,CAAA;AAAA,IAC3D;AACA,IAAA,OAAO;AAAA,MACL,OAAO,IAAA,CAAK,KAAA;AAAA,MACZ,qBAAqB,IAAA,CAAK,mBAAA;AAAA,MAC1B,iBAAA,EAAmB,KAAK,MAAA,CAAO,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,IAAI,CAAA,CAAE,MAAA;AAAA,MACrD,aAAA,EAAe,KAAK,MAAA,CAAO,MAAA;AAAA,MAC3B,UAAU,IAAA,CAAK,QAAA;AAAA,MACf,mBAAA,EAAqB,iBAAA;AAAA,MACrB,eAAe,IAAA,CAAK,aAAA;AAAA,MACpB,YAAY,IAAA,CAAK;AAAA,KACnB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,UAAA,GAAsB;AACpB,IAAA,IAAA,CAAK,qBAAA,EAAsB;AAC3B,IAAA,IAAI,IAAA,CAAK,KAAA,KAAU,MAAA,EAAQ,OAAO,KAAA;AAClC,IAAA,OAAO,IAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,SAAA,CAAU,YAAoB,MAAA,EAAuB;AACnD,IAAA,MAAM,GAAA,GAAM,KAAK,GAAA,EAAI;AAErB,IAAA,IAAI,IAAA,CAAK,UAAU,WAAA,EAAa;AAE9B,MAAA,IAAI,MAAA,EAAQ;AACV,QAAA,IAAA,CAAK,KAAA,EAAM;AACX,QAAA;AAAA,MACF;AAEA,MAAA,IAAA,CAAK,MAAA,EAAO;AACZ,MAAA;AAAA,IACF;AAGA,IAAA,IAAA,CAAK,aAAa,GAAG,CAAA;AAErB,IAAA,MAAM,IAAA,GAAO,cAAc,IAAA,CAAK,mBAAA;AAChC,IAAA,IAAA,CAAK,OAAO,IAAA,CAAK,EAAE,IAAI,GAAA,EAAK,MAAA,EAAQ,MAAM,CAAA;AAE1C,IAAA,IAAI,MAAA,EAAQ;AACV,MAAA,IAAA,CAAK,mBAAA,EAAA;AACL,MAAA,IAAA,CAAK,aAAA,GAAgB,GAAA;AACrB,MAAA,IAAI,IAAA,CAAK,mBAAA,IAAuB,IAAA,CAAK,sBAAA,EAAwB;AAC3D,QAAA,IAAA,CAAK,KAAA,EAAM;AAAA,MACb;AACA,MAAA;AAAA,IACF;AAGA,IAAA,IAAA,CAAK,mBAAA,GAAsB,CAAA;AAE3B,IAAA,IAAI,IAAA,EAAM;AACR,MAAA,IAAA,CAAK,UAAA,GAAa,GAAA;AAClB,MAAA,MAAM,SAAA,GAAY,KAAK,MAAA,CAAO,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,IAAI,CAAA,CAAE,MAAA;AACpD,MAAA,IAAI,SAAA,IAAa,KAAK,YAAA,EAAc;AAClC,QAAA,IAAA,CAAK,KAAA,EAAM;AAAA,MACb;AAAA,IACF;AAEA,IAAA,MAAM,SAAA,GAAY,KAAK,MAAA,CAAO,MAAA;AAC9B,IAAA,IAAI,SAAA,IAAa,KAAK,iBAAA,EAAmB;AAIvC,MAAA,IAAA,CAAK,KAAA,EAAM;AAAA,IACb;AAAA,EACF;AAAA;AAAA,EAGA,SAAA,GAAkB;AAChB,IAAA,IAAA,CAAK,KAAA,EAAM;AAAA,EACb;AAAA;AAAA,EAGA,UAAA,GAAmB;AACjB,IAAA,IAAA,CAAK,MAAA,EAAO;AAAA,EACd;AAAA,EAEQ,KAAA,GAAc;AACpB,IAAA,IAAI,IAAA,CAAK,UAAU,MAAA,EAAQ;AAC3B,IAAA,IAAA,CAAK,KAAA,GAAQ,MAAA;AACb,IAAA,IAAA,CAAK,QAAA,GAAW,KAAK,GAAA,EAAI;AAAA,EAC3B;AAAA,EAEQ,MAAA,GAAe;AACrB,IAAA,IAAA,CAAK,KAAA,GAAQ,QAAA;AACb,IAAA,IAAA,CAAK,mBAAA,GAAsB,CAAA;AAC3B,IAAA,IAAA,CAAK,SAAS,EAAC;AACf,IAAA,IAAA,CAAK,QAAA,GAAW,IAAA;AAAA,EAClB;AAAA;AAAA,EAGQ,qBAAA,GAA8B;AACpC,IAAA,IAAI,IAAA,CAAK,KAAA,KAAU,MAAA,IAAU,IAAA,CAAK,aAAa,IAAA,EAAM;AACrD,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,GAAA,EAAI,GAAI,IAAA,CAAK,QAAA;AAClC,IAAA,IAAI,OAAA,IAAW,KAAK,UAAA,EAAY;AAC9B,MAAA,IAAA,CAAK,KAAA,GAAQ,WAAA;AACb,MAAA,IAAA,CAAK,QAAA,GAAW,IAAA;AAAA,IAClB;AAAA,EACF;AAAA,EAEQ,aAAa,GAAA,EAAmB;AACtC,IAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,QAAA;AAC1B,IAAA,IAAA,CAAK,MAAA,GAAS,KAAK,MAAA,CAAO,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,MAAM,MAAM,CAAA;AAAA,EACxD;AACF","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\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\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/codebase-index/index.d.ts

@@ -1,18 +1,38 @@
-import { d as Symbol, F as FileMeta, e as SymbolKind, f as SymbolLang, c as SearchResult, b as IndexStats, R as Ref } from '../codebase-stats-tool-BLhQmPNc.js';
-export { a as FileSymbols, I as IndexResult, S as SCHEMA_VERSION, g as codebaseIndexTool, h as codebaseSearchTool, i as codebaseStatsTool } from '../codebase-stats-tool-BLhQmPNc.js';
+import { d as Symbol, F as FileMeta, e as SymbolKind, f as SymbolLang, c as SearchResult, b as IndexStats, R as Ref } from '../codebase-stats-tool-C8ApERbn.js';
+export { a as FileSymbols, I as IndexResult, S as SCHEMA_VERSION, g as codebaseIndexTool, h as codebaseSearchTool, i as codebaseStatsTool } from '../codebase-stats-tool-C8ApERbn.js';
 import '@wrongstack/core';
 
 /**
  * SQLite storage layer for the codebase index.
  *
  * Uses `node:sqlite` (synchronous API — DatabaseSync class).
- * Database file: {projectRoot}/.codebase-index/index.db
+ * Database file: ~/.wrongstack/projects/<hash>/codebase-index/index.db — kept
+ * out of the repo so it never clutters the working tree or needs gitignoring.
  */
 
+/**
+ * Resolve the per-project index directory. By default it lives under the
+ * global project dir (`~/.wrongstack/projects/<hash>/codebase-index`),
+ * matching every other piece of per-project state. Callers may pass an
+ * explicit `override` (used by tests and any wiring that already resolved the
+ * path) to avoid touching the real home directory.
+ */
+declare function resolveIndexDir(projectRoot: string, override?: string): string;
+/**
+ * Optional index-directory override carried on the run context's `meta` bag.
+ * Production leaves it unset (the index resolves to the global per-project
+ * dir); tests and bespoke wiring set `meta.codebaseIndexDir` to redirect it.
+ */
+declare function codebaseIndexDirOverride(ctx: {
+    meta?: Record<string, unknown>;
+}): string | undefined;
 declare class IndexStore {
-    private projectRoot;
     private db;
-    constructor(projectRoot: string);
+    /** Absolute path to this project's index directory. */
+    private readonly indexDir;
+    constructor(projectRoot: string, opts?: {
+        indexDir?: string;
+    });
     private initSchema;
     insertSymbols(symbols: Symbol[], nextId: number): number;
     deleteSymbolsForFile(file: string): void;
@@ -117,4 +137,4 @@ declare function lspKindToInternalKind(k: number): SymbolKind | null;
  */
 declare function internalKindToLspKind(k: SymbolKind): number | null;
 
-export { FileMeta, IndexStats, IndexStore, SearchResult, Symbol, SymbolKind, SymbolLang, buildBm25Index, buildIndexableText, internalKindToLspKind, lspKindToInternalKind, tokenise };
+export { FileMeta, IndexStats, IndexStore, SearchResult, Symbol, SymbolKind, SymbolLang, buildBm25Index, buildIndexableText, codebaseIndexDirOverride, internalKindToLspKind, lspKindToInternalKind, resolveIndexDir, tokenise };

package/dist/codebase-index/index.js

@@ -1,6 +1,6 @@
 import * as fs2 from 'node:fs/promises';
 import * as path4 from 'node:path';
-import { compileGlob } from '@wrongstack/core';
+import { resolveWstackPaths, compileGlob } from '@wrongstack/core';
 import { createRequire } from 'node:module';
 import * as fs from 'node:fs';
 import { mkdirSync, writeFileSync } from 'node:fs';
@@ -81,8 +81,14 @@ function internalKindToLspKind(k) {
 }
 
 // src/codebase-index/writer.ts
-var INDEX_DIR = ".codebase-index";
 var DB_FILE = "index.db";
+function resolveIndexDir(projectRoot, override) {
+  return override ?? resolveWstackPaths({ projectRoot }).projectCodebaseIndex;
+}
+function codebaseIndexDirOverride(ctx) {
+  const v = ctx.meta?.["codebaseIndexDir"];
+  return typeof v === "string" ? v : void 0;
+}
 var warningSilenced = false;
 function silenceSqliteExperimentalWarning() {
   if (warningSilenced) return;
@@ -110,16 +116,16 @@ function loadDatabaseSync() {
   return DatabaseSyncCtor;
 }
 var IndexStore = class {
-  constructor(projectRoot) {
-    this.projectRoot = projectRoot;
-    const dir = path4.join(projectRoot, INDEX_DIR);
-    fs.mkdirSync(dir, { recursive: true });
+  db;
+  /** Absolute path to this project's index directory. */
+  indexDir;
+  constructor(projectRoot, opts = {}) {
+    this.indexDir = resolveIndexDir(projectRoot, opts.indexDir);
+    fs.mkdirSync(this.indexDir, { recursive: true });
     const Database = loadDatabaseSync();
-    this.db = new Database(path4.join(dir, DB_FILE));
+    this.db = new Database(path4.join(this.indexDir, DB_FILE));
     this.initSchema();
   }
-  projectRoot;
-  db;
   initSchema() {
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS metadata (
@@ -310,7 +316,7 @@ var IndexStore = class {
       totalFiles,
       byLang,
       byKind,
-      indexPath: path4.join(this.projectRoot, INDEX_DIR),
+      indexPath: this.indexDir,
       lastIndexed,
       sizeBytes,
       version: SCHEMA_VERSION
@@ -403,7 +409,7 @@ var IndexStore = class {
     }));
   }
   sizeBytes() {
-    const dbPath = path4.join(this.projectRoot, INDEX_DIR, DB_FILE);
+    const dbPath = path4.join(this.indexDir, DB_FILE);
     try {
       return fs.statSync(dbPath).size;
     } catch {
@@ -1213,7 +1219,7 @@ function regexParse(opts) {
     }
     return lo + 1;
   }
-  function extractDeclaration(lineIdx, match) {
+  function extractDeclaration(lineIdx, _match) {
     const line = lines[lineIdx] ?? "";
     return line.trim().slice(0, 500);
   }
@@ -1678,9 +1684,9 @@ async function parseFile(file, content, lang) {
       return { file, lang, symbols: [], mtimeMs: Date.now() };
   }
 }
-async function runIndexer(ctx, opts) {
-  const { projectRoot, force = false, langs, ignore = [] } = opts;
-  const store = new IndexStore(projectRoot);
+async function runIndexer(_ctx, opts) {
+  const { projectRoot, force = false, langs, ignore = [], indexDir } = opts;
+  const store = new IndexStore(projectRoot, { indexDir });
   const startMs = Date.now();
   const errors = [];
   const langStats = {};
@@ -1797,8 +1803,8 @@ async function runIndexer(ctx, opts) {
 var codebaseIndexTool = {
   name: "codebase-index",
   category: "Project",
-  description: "Build or update the symbol index for the project. Runs incrementally by default \u2014 only re-indexes files that changed since the last run.",
-  usageHint: "Call with `force: true` to wipe and rebuild the index from scratch. Use `langs` to limit to specific languages. First call without arguments to do an incremental index.",
+  description: "Build or incrementally update the project-wide symbol index. This powers fast codebase search and understanding. By default it only processes files that have changed since the last indexing run.",
+  usageHint: "IMPORTANT FOR LARGE CODEBASES:\n\n- First run (or after major changes): consider `force: true` for a clean rebuild.\n- Normal usage: call without arguments for fast incremental updates.\n- Use `langs` to restrict to specific languages if you only care about certain parts of the project.\nThis tool is relatively expensive \u2014 do not call it on every turn. Use it when the index is stale or before heavy codebase-search sessions.",
   permission: "auto",
   mutating: true,
   timeoutMs: 12e4,
@@ -1820,7 +1826,8 @@ var codebaseIndexTool = {
     const result = await runIndexer(ctx, {
       projectRoot: ctx.projectRoot,
       force: input.force ?? false,
-      langs: input.langs
+      langs: input.langs,
+      indexDir: codebaseIndexDirOverride(ctx)
     });
     return result;
   }
@@ -1918,10 +1925,11 @@ var Bm25Index = class {
 var codebaseSearchTool = {
   name: "codebase-search",
   category: "Project",
-  description: "Search indexed code symbols by name, signature, or doc comment. Uses BM25 ranking for relevance.",
-  usageHint: "Pass `query` for keyword search. Filter with `kind` (class/function/interface/etc), `lang` (ts/js/etc), `file` (substring). `limit` caps results (default 20).",
+  description: "Semantic/keyword search over the indexed codebase symbols (functions, classes, interfaces, etc.). Uses BM25 ranking. Much more powerful and structured than raw `grep` for finding code by name or concept.",
+  usageHint: "PREFERRED FOR CODE UNDERSTANDING:\n\n- Use when you need to find where something is defined or used by name.\n- `kind` filter is very useful (e.g. only functions or only interfaces).\n- Combine with `file` filter to scope to a specific directory or module.\nThis is generally better than `grep` when you are looking for symbols rather than arbitrary text patterns.",
   permission: "auto",
   mutating: false,
+  capabilities: ["fs.read"],
   timeoutMs: 1e4,
   inputSchema: {
     type: "object",
@@ -1956,7 +1964,7 @@ var codebaseSearchTool = {
     required: ["query"]
   },
   async execute(input, ctx) {
-    const store = new IndexStore(ctx.projectRoot);
+    const store = new IndexStore(ctx.projectRoot, { indexDir: codebaseIndexDirOverride(ctx) });
     try {
       const limit = Math.min(input.limit ?? 20, 100);
       const candidates = store.search(input.query, {
@@ -2001,10 +2009,11 @@ var codebaseSearchTool = {
 var codebaseStatsTool = {
   name: "codebase-stats",
   category: "Project",
-  description: "Return statistics about the symbol index: total symbols, files, breakdown by language and kind, index size, and last update time.",
-  usageHint: "No arguments needed. Use to check if the index is stale or healthy before running a search.",
+  description: "Return health and statistics about the current symbol index (total symbols, files, language/kind breakdown, size, last update). Useful to decide whether to re-index.",
+  usageHint: "CALL BEFORE HEAVY CODEBASE-SEARCH WORK:\n\n- Use to see if the index is up-to-date or needs a refresh.\n- No arguments required.\n- Helps avoid wasting tokens on searches against a stale index.\nLightweight and safe to call frequently.",
   permission: "auto",
   mutating: false,
+  capabilities: ["fs.read"],
   timeoutMs: 5e3,
   inputSchema: {
     type: "object",
@@ -2012,7 +2021,7 @@ var codebaseStatsTool = {
     additionalProperties: false
   },
   async execute(_input, ctx) {
-    const store = new IndexStore(ctx.projectRoot);
+    const store = new IndexStore(ctx.projectRoot, { indexDir: codebaseIndexDirOverride(ctx) });
     try {
       const stats = store.getStats();
       return {
@@ -2031,6 +2040,6 @@ var codebaseStatsTool = {
   }
 };
 
-export { IndexStore, SCHEMA_VERSION, buildBm25Index, buildIndexableText, codebaseIndexTool, codebaseSearchTool, codebaseStatsTool, internalKindToLspKind, lspKindToInternalKind, tokenise };
+export { IndexStore, SCHEMA_VERSION, buildBm25Index, buildIndexableText, codebaseIndexDirOverride, codebaseIndexTool, codebaseSearchTool, codebaseStatsTool, internalKindToLspKind, lspKindToInternalKind, resolveIndexDir, tokenise };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map