@wrongstack/tools 0.284.0 → 0.285.0

package/dist/circuit-breaker.d.ts

@@ -15,7 +15,7 @@
  * resource pool; isolating them would let the model route around the
  * breaker by alternating which tool it uses.
  */
-interface CircuitBreakerConfig {
+export interface CircuitBreakerConfig {
     /**
      * Consecutive failures before trip. Default: 5.
      * A single success resets this counter to 0.
@@ -47,7 +47,7 @@ interface CircuitBreakerConfig {
      */
     cooldownMs?: number | undefined;
 }
-interface CircuitBreakerSnapshot {
+export interface CircuitBreakerSnapshot {
     state: 'closed' | 'open' | 'half-open';
     consecutiveFailures: number;
     slowCallsInWindow: number;
@@ -57,7 +57,7 @@ interface CircuitBreakerSnapshot {
     lastFailureAt: number | null;
     lastSlowAt: number | null;
 }
-declare class CircuitBreaker {
+export declare class CircuitBreaker {
     private readonly maxConsecutiveFailures;
     private readonly slowCallThresholdMs;
     private readonly maxSlowCalls;
@@ -132,5 +132,4 @@ declare class CircuitBreaker {
     private _checkStateTransition;
     private _pruneWindow;
 }
-
-export { CircuitBreaker, type CircuitBreakerConfig, type CircuitBreakerSnapshot };
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAsBD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACvC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,UAAU,CAAuB;IACzC,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAuB;IAEvC;;;;;OAKG;IACH,OAAO,CAAC,OAAO,CAAQ;IAEvB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IAEnC,YAAY,MAAM,GAAE,oBAAyB,EAO5C;IAED,4EAA4E;IAC5E,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAIjC;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;;OAIG;IACH,IAAI,UAAU,IAAI,OAAO,CAIxB;IAED;;OAEG;IACH,QAAQ,IAAI,sBAAsB,CAkBjC;IAED;;;;;;;;OAQG;IACH,UAAU,CAAC,MAAM,UAAQ,GAAG,OAAO,CAKlC;IAED;;;;;;;;OAQG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAQ,GAAG,IAAI,CAiDnE;IAED,8DAA8D;IAC9D,SAAS,IAAI,IAAI,CAEhB;IAED,8DAA8D;IAC9D,UAAU,IAAI,IAAI,CAEjB;IAED,OAAO,CAAC,KAAK;IAmBb,OAAO,CAAC,MAAM;IAiBd,8DAA8D;IAC9D,OAAO,CAAC,qBAAqB;IAS7B,OAAO,CAAC,YAAY;CAIrB"}

package/dist/circuit-breaker.js

@@ -189,7 +189,7 @@ var CircuitBreaker = class {
     this.window = this.window.filter((c) => c.at >= cutoff);
   }
 };
-
-export { CircuitBreaker };
+export {
+  CircuitBreaker
+};
 //# sourceMappingURL=circuit-breaker.js.map
-//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit-breaker.js.map

@@ -1 +1,7 @@
-{"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 | undefined;\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 | undefined;\n  /**\n   * Max slow calls before trip (within the sliding window). Default: 3.\n   */\n  maxSlowCalls?: number | undefined;\n  /**\n   * Sliding window for rate-limit and slow-call counting, in ms.\n   * Default: 60_000 (1 minute).\n   */\n  windowMs?: number | undefined;\n  /**\n   * Max calls within the sliding window. Default: 30.\n   * Burst exceeding this trips the breaker immediately.\n   */\n  maxCallsPerWindow?: number | undefined;\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 | undefined;\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 = 180_000;\n// 3 minutes — balanced against the 5-minute bash timeout. Commands\n// running <3min are normal; 3-5min are \"slow\" and count toward the\n// breaker. 3 consecutive slow calls trip the circuit.\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  /**\n   * Master enable flag. When false the breaker is bypassed: `beforeCall`\n   * always returns true and `afterCall` records nothing. The class itself\n   * defaults to enabled (so the standalone unit tests exercise tripping); the\n   * ProcessRegistry flips this off until the user opts in via `/settings`.\n   */\n  private enabled = true;\n\n  /**\n   * Fired (best-effort) when the breaker transitions into the `open` state.\n   * The registry uses this to arm its auto kill/reset countdown.\n   */\n  onTrip?: (() => void) | undefined;\n  /**\n   * Fired (best-effort) when the breaker returns to `closed` after having been\n   * open/half-open. The registry uses this to cancel a pending kill/reset.\n   */\n  onReset?: (() => void) | undefined;\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  /** Toggle the master enable. Disabling resets to a clean `closed` state. */\n  setEnabled(enabled: boolean): void {\n    if (this.enabled === enabled) return;\n    this.enabled = enabled;\n    if (!enabled) this._reset();\n  }\n\n  get isEnabled(): boolean {\n    return this.enabled;\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    if (!this.enabled) return true;\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   * @param bypass - If true, skip the circuit breaker check entirely.\n   *                  Use for background/fire-and-forget processes that should\n   *                  not affect breaker state.\n   */\n  beforeCall(bypass = false): boolean {\n    if (bypass || !this.enabled) return true;\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   * @param bypass - If true, do not update breaker state.\n   *                  Use for background/fire-and-forget processes.\n   */\n  afterCall(durationMs: number, failed: boolean, bypass = false): void {\n    if (bypass || !this.enabled) return;\n\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    // P3 #23 (before-release.md): clear the window on trip. Old records are\n    // irrelevant once tripped — the breaker starts fresh after cooldown\n    // (half-open → closed resets the counters). Without this the window array\n    // holds onto CallRecord entries for its lifetime if no new afterCall()\n    // arrives (which is the case when the breaker stays open and no new calls\n    // are attempted).\n    this.window = [];\n    // Best-effort: never let a listener failure corrupt breaker state.\n    try {\n      this.onTrip?.();\n    } catch {\n      /* ignored — observability hook only */\n    }\n  }\n\n  private _reset(): void {\n    const wasRecovering = this.state !== 'closed';\n    this.state = 'closed';\n    this.consecutiveFailures = 0;\n    this.window = [];\n    this.openedAt = null;\n    // Only notify on a real recovery (open/half-open → closed), not on the\n    // initial closed state or an idempotent re-reset.\n    if (wasRecovering) {\n      try {\n        this.onReset?.();\n      } catch {\n        /* ignored — observability hook only */\n      }\n    }\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"],
+  "sourcesContent": ["/**\n * CircuitBreaker \u2014 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 \u2014 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 | undefined;\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 | undefined;\n  /**\n   * Max slow calls before trip (within the sliding window). Default: 3.\n   */\n  maxSlowCalls?: number | undefined;\n  /**\n   * Sliding window for rate-limit and slow-call counting, in ms.\n   * Default: 60_000 (1 minute).\n   */\n  windowMs?: number | undefined;\n  /**\n   * Max calls within the sliding window. Default: 30.\n   * Burst exceeding this trips the breaker immediately.\n   */\n  maxCallsPerWindow?: number | undefined;\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 | undefined;\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 = 180_000;\n// 3 minutes \u2014 balanced against the 5-minute bash timeout. Commands\n// running <3min are normal; 3-5min are \"slow\" and count toward the\n// breaker. 3 consecutive slow calls trip the circuit.\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  /**\n   * Master enable flag. When false the breaker is bypassed: `beforeCall`\n   * always returns true and `afterCall` records nothing. The class itself\n   * defaults to enabled (so the standalone unit tests exercise tripping); the\n   * ProcessRegistry flips this off until the user opts in via `/settings`.\n   */\n  private enabled = true;\n\n  /**\n   * Fired (best-effort) when the breaker transitions into the `open` state.\n   * The registry uses this to arm its auto kill/reset countdown.\n   */\n  onTrip?: (() => void) | undefined;\n  /**\n   * Fired (best-effort) when the breaker returns to `closed` after having been\n   * open/half-open. The registry uses this to cancel a pending kill/reset.\n   */\n  onReset?: (() => void) | undefined;\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  /** Toggle the master enable. Disabling resets to a clean `closed` state. */\n  setEnabled(enabled: boolean): void {\n    if (this.enabled === enabled) return;\n    this.enabled = enabled;\n    if (!enabled) this._reset();\n  }\n\n  get isEnabled(): boolean {\n    return this.enabled;\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    if (!this.enabled) return true;\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   * @param bypass - If true, skip the circuit breaker check entirely.\n   *                  Use for background/fire-and-forget processes that should\n   *                  not affect breaker state.\n   */\n  beforeCall(bypass = false): boolean {\n    if (bypass || !this.enabled) return true;\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   * @param bypass - If true, do not update breaker state.\n   *                  Use for background/fire-and-forget processes.\n   */\n  afterCall(durationMs: number, failed: boolean, bypass = false): void {\n    if (bypass || !this.enabled) return;\n\n    const now = Date.now();\n\n    if (this.state === 'half-open') {\n      // First call through after cooldown \u2014 if it failed, go back to open.\n      if (failed) {\n        this._trip();\n        return;\n      }\n      // Success in half-open \u2192 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 \u2014 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    // P3 #23 (before-release.md): clear the window on trip. Old records are\n    // irrelevant once tripped \u2014 the breaker starts fresh after cooldown\n    // (half-open \u2192 closed resets the counters). Without this the window array\n    // holds onto CallRecord entries for its lifetime if no new afterCall()\n    // arrives (which is the case when the breaker stays open and no new calls\n    // are attempted).\n    this.window = [];\n    // Best-effort: never let a listener failure corrupt breaker state.\n    try {\n      this.onTrip?.();\n    } catch {\n      /* ignored \u2014 observability hook only */\n    }\n  }\n\n  private _reset(): void {\n    const wasRecovering = this.state !== 'closed';\n    this.state = 'closed';\n    this.consecutiveFailures = 0;\n    this.window = [];\n    this.openedAt = null;\n    // Only notify on a real recovery (open/half-open \u2192 closed), not on the\n    // initial closed state or an idempotent re-reset.\n    if (wasRecovering) {\n      try {\n        this.onReset?.();\n      } catch {\n        /* ignored \u2014 observability hook only */\n      }\n    }\n  }\n\n  /** Transition from open \u2192 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}"],
+  "mappings": "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",
+  "names": []
+}

package/dist/codebase-index/background-indexer.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Index host — the main-thread coordinator for all codebase-index operations.
+ *
+ * Production mode runs every operation (full scans, per-file reindexes,
+ * searches, stats) in a dedicated worker thread (`worker.ts`), so the
+ * synchronous `node:sqlite` calls and the TypeScript parser can never block
+ * the main event loop — the failure mode that used to freeze terminals is
+ * structurally impossible. When the built worker file is not present (tests
+ * run from source, exotic runtimes) or `WRONGSTACK_INDEX_INLINE=1` is set,
+ * operations fall back to running inline through the same service layer.
+ *
+ * Concerns owned here, in front of either execution mode:
+ *
+ * 1. **Serialization** — every write run (startup scan, per-edit incremental,
+ *    external file-watch, manual reindex) goes through one process-wide
+ *    promise-chain mutex so two runs never race the same `index.db` writer.
+ * 2. **Debounce** — rapid successive edits to the same file coalesce into a
+ *    single reindex, keyed per `(indexDir, file)`.
+ * 3. **Watchdog** — every operation is raced against a timeout. In worker
+ *    mode a timeout hard-terminates the worker (it respawns lazily on the
+ *    next request); inline it aborts the run's signal. Either way the mutex
+ *    chain always advances and the promise always settles.
+ * 4. **Circuit breaker** — repeated failures/timeouts pause indexing instead
+ *    of queuing more work behind a wedged pipeline. See circuit-breaker.ts.
+ * 5. **State tracking** — ready/indexing/progress flags + change listeners
+ *    for the TUI status chip and the search/stats tools' gating.
+ */
+import { type CircuitSnapshot } from './circuit-breaker.js';
+import type { IndexResult, IndexStats } from './schema.js';
+import type { SearchOpArgs, SearchOpResult, StatsOpArgs } from './worker-protocol.js';
+/** True once the first full-project index has completed (success or failure). */
+export declare function isIndexReady(): boolean;
+/**
+ * Mark the index as ready so downstream tools (codebase-search, codebase-stats)
+ * don't gate on a startup index that never ran.
+ */
+export declare function setIndexReady(): void;
+/** True while an index build is actively running. */
+export declare function isIndexing(): boolean;
+/** Current indexing progress: { currentFile, totalFiles, ready, indexing, circuit }. */
+export declare function getIndexState(): {
+    ready: boolean;
+    indexing: boolean;
+    currentFile: number;
+    totalFiles: number;
+    lastError: string | null;
+    /** Circuit-breaker state — `open` means indexing is paused after repeated failures. */
+    circuit: CircuitSnapshot;
+};
+/**
+ * Optional callback fired on every lifecycle transition (started, progress,
+ * completed, failed). Plug into the event bus or a TUI dispatcher to surface
+ * the indexing state in real time.
+ */
+type IndexStateListener = (state: ReturnType<typeof getIndexState>) => void;
+export declare function onIndexStateChange(listener: IndexStateListener): () => void;
+/**
+ * Tear down the index host (worker + pending debounces). Call on process
+ * shutdown; safe to call when nothing is running.
+ */
+export declare function shutdownCodebaseIndexHost(): void;
+/** True when the file's extension maps to a language the indexer can parse. */
+export declare function isIndexableFile(filePath: string): boolean;
+export declare function runStartupIndex(opts: {
+    projectRoot: string;
+    indexDir?: string | undefined;
+    force?: boolean | undefined;
+    langs?: string[] | undefined;
+    signal?: AbortSignal | undefined;
+    /** Watchdog timeout for the whole run. Default: 120s. */
+    timeoutMs?: number | undefined;
+}): Promise<IndexResult>;
+/**
+ * Debounced, fire-and-forget incremental reindex of specific files. Used by the
+ * per-edit toolCall middleware and the external file watcher. Non-indexable
+ * paths are dropped. Errors are reported via the optional `onError` callback and
+ * never thrown to the caller (background work must not crash a turn).
+ */
+export declare function enqueueReindex(opts: {
+    projectRoot: string;
+    files: string[];
+    indexDir?: string | undefined;
+    debounceMs?: number | undefined;
+    /** Watchdog timeout per file. Default: 30s. */
+    timeoutMs?: number | undefined;
+    onError?: ((err: unknown) => void) | undefined;
+}): void;
+/** Cancel all pending debounced reindexes. For teardown / tests. */
+export declare function cancelPendingReindexes(): void;
+/**
+ * Ranked symbol search against the index. The query runs in the index worker
+ * (or inline in fallback mode) — the main thread never opens SQLite. Reads
+ * don't take the write mutex (WAL readers don't block the writer) and don't
+ * feed the circuit breaker; a wedged read still trips the watchdog, which
+ * recycles the worker.
+ */
+export declare function searchCodebaseIndex(args: SearchOpArgs, opts?: {
+    timeoutMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+}): Promise<SearchOpResult>;
+/** Index health/statistics, fetched off the main thread like searches. */
+export declare function codebaseIndexStats(args: StatsOpArgs, opts?: {
+    timeoutMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+}): Promise<IndexStats>;
+/**
+ * Reset all process-global indexing state for test isolation.
+ *
+ * Vitest runs test files in parallel within the same process, so module-level
+ * state (`_indexing`, `_ready`, `chain`, `indexCircuitBreaker`) leaks between
+ * tests. Call this in `beforeEach` to ensure each test starts with a clean
+ * slate. Production code should NEVER call this.
+ */
+export declare function resetIndexStateForTesting(): void;
+export {};
+//# sourceMappingURL=background-indexer.d.ts.map

package/dist/codebase-index/background-indexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-indexer.d.ts","sourceRoot":"","sources":["../../src/codebase-index/background-indexer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,KAAK,EAKV,YAAY,EACZ,cAAc,EACd,WAAW,EAEZ,MAAM,sBAAsB,CAAC;AA2B9B,iFAAiF;AACjF,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED,qDAAqD;AACrD,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED,wFAAwF;AACxF,wBAAgB,aAAa,IAAI;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uFAAuF;IACvF,OAAO,EAAE,eAAe,CAAC;CAC1B,CASA;AAED;;;;GAIG;AACH,KAAK,kBAAkB,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,KAAK,IAAI,CAAC;AAG5E,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAK3E;AAoGD;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAIhD;AAuJD,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AAmBD,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC7B,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,GAAG,OAAO,CAAC,WAAW,CAAC,CA2DvB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAChD,GAAG,IAAI,CAmCP;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,YAAY,EAClB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;CAAO,GAC9E,OAAO,CAAC,cAAc,CAAC,CAKzB;AAED,0EAA0E;AAC1E,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,WAAW,EACjB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;CAAO,GAC9E,OAAO,CAAC,UAAU,CAAC,CAKrB;AAID;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAchD"}

package/dist/codebase-index/bm25.d.ts

@@ -0,0 +1,40 @@
+/**
+ * BM25 ranking implementation — no external dependencies.
+ *
+ * Algorithm: Okapi BM25 with standard parameters (k1=1.5, b=0.75).
+ */
+interface Bm25Doc {
+    id: number;
+    tokens: string[];
+    raw: string;
+    len: number;
+}
+/** Tokenise a string into lowercase word tokens. */
+export declare function tokenise(text: string): string[];
+export interface IndexableDoc {
+    id: number;
+    text: string;
+}
+/**
+ * Build indexable text for BM25 from a symbol's fields.
+ * The name is split into camelCase/SnakeCase words so that queries
+ * like "complex" match "complexOperation". The verbatim name is
+ * also included for exact-match queries.
+ */
+export declare function buildIndexableText(name: string, signature: string, docComment: string): string;
+export declare function buildBm25Index(docs: IndexableDoc[]): Bm25Index;
+export declare class Bm25Index {
+    private documents;
+    private df;
+    private N;
+    private readonly safeAvgLen;
+    constructor(documents: Bm25Doc[], df: Record<string, number>, N: number, avgLen: number);
+    score(query: string, filter?: (id: number) => boolean): Array<{
+        id: number;
+        score: number;
+    }>;
+    getDoc(id: number): Bm25Doc | undefined;
+    extractSnippet(docId: number, queryTokens: string[], radius?: number): string;
+}
+export {};
+//# sourceMappingURL=bm25.d.ts.map

package/dist/codebase-index/bm25.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bm25.d.ts","sourceRoot":"","sources":["../../src/codebase-index/bm25.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,UAAU,OAAO;IACf,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,oDAAoD;AACpD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/C;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAgBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE9F;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,SAAS,CAsB9D;AAED,qBAAa,SAAS;IAIlB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,CAAC;IALX,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,YACU,SAAS,EAAE,OAAO,EAAE,EACpB,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1B,CAAC,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EAGf;IAED,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GAAG,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CA+B3F;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAEtC;IAED,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,MAAM,SAAK,GAAG,MAAM,CAexE;CACF"}

package/dist/codebase-index/circuit-breaker.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Circuit breaker for the codebase indexer.
+ *
+ * The indexer can wedge: a hung filesystem, a parser pathology, or another
+ * wstack process holding the SQLite write lock (several surfaces — TUI, WebUI,
+ * parallel terminals — share one per-project `index.db`). Without protection,
+ * every queued reindex piles up behind the process-wide mutex, `isIndexing()`
+ * stays true forever, and anything that awaits an index run (the startup scan,
+ * `/codebase-reindex`) locks its terminal.
+ *
+ * Standard three-state breaker:
+ *
+ *   closed    — normal operation; consecutive failures are counted.
+ *   open      — after `failureThreshold` consecutive failures, every request
+ *               is rejected fast ({@link CircuitOpenError}) for `cooldownMs`.
+ *   half-open — after the cooldown exactly one probe run is admitted;
+ *               success closes the circuit, failure re-opens it.
+ *
+ * Watchdog timeouts ({@link IndexTimeoutError}) count as failures;
+ * caller-initiated aborts (session teardown) do not — the background indexer
+ * makes that distinction before recording.
+ *
+ * Lock conflicts ({@link LockError}) do NOT count as failures — they are expected
+ * transient conditions when multiple wstack surfaces share the same `index.db`.
+ * The index store retries automatically; a LockError only reaches the circuit
+ * breaker when all retries are exhausted.
+ */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export interface CircuitSnapshot {
+    state: CircuitState;
+    consecutiveFailures: number;
+    lastFailure: string | null;
+    /** ms until an open circuit admits a half-open probe (0 unless open). */
+    cooldownRemainingMs: number;
+}
+/** Thrown when a run is rejected because the circuit is open. */
+export declare class CircuitOpenError extends Error {
+    readonly name = "CircuitOpenError";
+}
+/** Thrown by the background indexer's watchdog when a run exceeds its timeout. */
+export declare class IndexTimeoutError extends Error {
+    readonly name = "IndexTimeoutError";
+}
+/**
+ * Thrown when an SQLite operation fails with a lock conflict (SQLITE_BUSY or
+ * SQLITE_LOCKED) even after all retry attempts are exhausted.
+ *
+ * The circuit breaker does **not** count `LockError` as a failure — a lock
+ * conflict means another writer is active, not that this indexer is broken.
+ * The caller should treat it as a transient failure and retry later.
+ */
+export declare class LockError extends Error {
+    readonly name = "LockError";
+}
+export interface CircuitBreakerOptions {
+    /** Consecutive failures before the circuit opens. Default: 3. */
+    failureThreshold?: number | undefined;
+    /** How long an open circuit rejects requests before allowing a probe. Default: 60s. */
+    cooldownMs?: number | undefined;
+    /** Injectable clock for tests. Default: Date.now. */
+    now?: (() => number) | undefined;
+}
+export declare class IndexCircuitBreaker {
+    private readonly failureThreshold;
+    private readonly cooldownMs;
+    private readonly now;
+    private state;
+    private consecutiveFailures;
+    private openedAt;
+    private lastFailure;
+    private probeInFlight;
+    constructor(opts?: CircuitBreakerOptions);
+    /**
+     * True when a run may proceed. An open circuit transitions to half-open once
+     * the cooldown has elapsed, admitting exactly one probe; further requests
+     * are rejected until that probe settles via recordSuccess/recordFailure.
+     */
+    allowRequest(): boolean;
+    recordSuccess(): void;
+    recordFailure(err: unknown): void;
+    /** Force-close the circuit (manual recovery: `/codebase-reindex`). */
+    reset(): void;
+    snapshot(): CircuitSnapshot;
+}
+/**
+ * Process-wide breaker shared by every index path (startup scan, per-edit
+ * incremental, external watcher, the `codebase-index` tool). Module-level for
+ * the same reason the mutex is: there is one `index.db` per project and one
+ * indexing pipeline per process.
+ */
+export declare const indexCircuitBreaker: IndexCircuitBreaker;
+/** Reset the shared breaker — used by `/codebase-reindex` and tests. */
+export declare function resetIndexCircuitBreaker(): void;
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/codebase-index/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/codebase-index/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yEAAyE;IACzE,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,iEAAiE;AACjE,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAkB,IAAI,sBAAsB;CAC7C;AAED,kFAAkF;AAClF,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,IAAI,uBAAuB;CAC9C;AAED;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,SAAkB,IAAI,eAAe;CACtC;AAED,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,uFAAuF;IACvF,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,qDAAqD;IACrD,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAClC;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,aAAa,CAAS;IAE9B,YAAY,IAAI,GAAE,qBAA0B,EAI3C;IAED;;;;OAIG;IACH,YAAY,IAAI,OAAO,CAYtB;IAED,aAAa,IAAI,IAAI,CAKpB;IAED,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAehC;IAED,sEAAsE;IACtE,KAAK,IAAI,IAAI,CAMZ;IAED,QAAQ,IAAI,eAAe,CAQ1B;CACF;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,qBAA4B,CAAC;AAE7D,wEAAwE;AACxE,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}

package/dist/codebase-index/codebase-index-tool.d.ts

@@ -0,0 +1,17 @@
+import type { Tool } from '@wrongstack/core';
+export declare const codebaseIndexTool: Tool<CodebaseIndexInput, CodebaseIndexOutput>;
+interface CodebaseIndexInput {
+    force?: boolean | undefined;
+    langs?: string[] | undefined;
+}
+interface CodebaseIndexOutput {
+    filesIndexed: number;
+    symbolsIndexed: number;
+    langStats: Record<string, number>;
+    durationMs: number;
+    errors: string[];
+    /** Advisory note when the indexer was skipped (e.g. another index in progress). */
+    note?: string | undefined;
+}
+export {};
+//# sourceMappingURL=codebase-index-tool.d.ts.map

package/dist/codebase-index/codebase-index-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebase-index-tool.d.ts","sourceRoot":"","sources":["../../src/codebase-index/codebase-index-tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAK7C,eAAO,MAAM,iBAAiB,EAAE,IAAI,CAAC,kBAAkB,EAAE,mBAAmB,CAyE3E,CAAC;AAIF,UAAU,kBAAkB;IAC1B,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAC9B;AAED,UAAU,mBAAmB;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B"}

package/dist/codebase-index/codebase-search-tool.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `codebase-search` tool — search the symbol index with BM25 ranking.
+ *
+ * Usage: codebase-search({
+ *   query: string,        // search terms
+ *   kind?: string,       // class|function|interface|method|const|...
+ *   lang?: string,       // ts|tsx|js|jsx|go|py|rs
+ *   file?: string,       // filter to a specific file path (substring match)
+ *   limit?: number,      // max results (default 20, max 100)
+ * })
+ *
+ * Returns: [{ name, kind, lang, file, line, signature, snippet, score }, ...]
+ *
+ * The query executes in the index worker via FTS5 (`MATCH` + native `bm25()`)
+ * — the main thread never opens SQLite, so a contended or wedged index can
+ * slow this tool down but can never freeze the terminal.
+ */
+import type { Tool } from '@wrongstack/core';
+import type { SearchResult } from './schema.js';
+export declare const codebaseSearchTool: Tool<CodebaseSearchInput, CodebaseSearchOutput>;
+interface CodebaseSearchInput {
+    query: string;
+    kind?: string | undefined;
+    lang?: string | undefined;
+    file?: string | undefined;
+    limit?: number | undefined;
+    lspKind?: number | undefined;
+    /**
+     * When true, hints that LSP-based search should be preferred over the index.
+     * The built-in tool ignores this (index-only), but when the LSP plugin is
+     * active it intercepts the tool and provides live LSP workspaceSymbol results.
+     */
+    preferLsp?: boolean | undefined;
+}
+interface CodebaseSearchOutput {
+    results: SearchResult[];
+    total: number;
+    query: string;
+    /** Non-empty when the index blocked the search (not ready, indexing, failed). */
+    indexStatus?: string | undefined;
+}
+export {};
+//# sourceMappingURL=codebase-search-tool.d.ts.map

package/dist/codebase-index/codebase-search-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebase-search-tool.d.ts","sourceRoot":"","sources":["../../src/codebase-index/codebase-search-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,kBAAkB,EAAE,IAAI,CAAC,mBAAmB,EAAE,oBAAoB,CA8G9E,CAAC;AAIF,UAAU,mBAAmB;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACjC;AAED,UAAU,oBAAoB;IAC5B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC"}

package/dist/codebase-index/codebase-stats-tool.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `codebase-stats` tool — report index health and statistics.
+ *
+ * Usage: codebase-stats({})
+ *
+ * Returns: { totalSymbols, totalFiles, byLang, byKind, lastIndexed, sizeBytes, version }
+ */
+import type { Tool } from '@wrongstack/core';
+export declare const codebaseStatsTool: Tool<Record<string, never>, CodebaseStatsOutput>;
+interface CodebaseStatsOutput {
+    totalSymbols: number;
+    totalFiles: number;
+    byLang: Record<string, number>;
+    byKind: Record<string, number>;
+    lastIndexed: number | null;
+    sizeBytes: number;
+    indexPath: string;
+    version: number;
+    /** Non-empty when the index is not ready or is still building. */
+    indexStatus?: string | undefined;
+}
+export {};
+//# sourceMappingURL=codebase-stats-tool.d.ts.map

package/dist/codebase-index/codebase-stats-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebase-stats-tool.d.ts","sourceRoot":"","sources":["../../src/codebase-index/codebase-stats-tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAK7C,eAAO,MAAM,iBAAiB,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,mBAAmB,CAwE9E,CAAC;AAEF,UAAU,mBAAmB;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC"}

package/dist/codebase-index/gitignore.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Minimal but faithful `.gitignore` matcher for the indexer.
+ *
+ * Supports the parts of the gitignore spec that matter for skipping source
+ * files: comments / blanks, `!` negation (last match wins), trailing-slash
+ * directory-only rules, leading-slash / embedded-slash anchoring, and the
+ * `*` / `**` / `?` / `[...]` globs (via core's {@link compileGlob}).
+ *
+ * Only the project-root `.gitignore` is read. Nested `.gitignore` files are not
+ * walked — the common build/dependency dirs that would live deeper are already
+ * covered by the indexer's always-on `DEFAULT_IGNORE`.
+ *
+ * Known limitation: a `!negated` file inside an ignored directory will not be
+ * re-included, because the indexer prunes ignored directories before descending
+ * (a large performance win). This matches most lightweight implementations.
+ */
+export type IgnoreMatcher = (relPath: string, isDir: boolean) => boolean;
+/** Compile a list of raw `.gitignore` lines into a matcher. */
+export declare function compileGitignore(lines: string[]): IgnoreMatcher;
+/** Read `<projectRoot>/.gitignore` and compile it. Missing file → matches nothing. */
+export declare function loadGitignoreMatcher(projectRoot: string): Promise<IgnoreMatcher>;
+//# sourceMappingURL=gitignore.d.ts.map

package/dist/codebase-index/gitignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignore.d.ts","sourceRoot":"","sources":["../../src/codebase-index/gitignore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAgBzE,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,aAAa,CAgD/D;AAED,sFAAsF;AACtF,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAStF"}

package/dist/codebase-index/go-parser.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Go source symbol extraction using `go/parser`.
+ *
+ * Spawns a `go run -` child process that parses the file with go/ast and
+ * emits JSON. Falls back to empty results on any error.
+ *
+ * Extracts: package, func, type, const, var
+ */
+import type { FileSymbols, SymbolLang } from './schema.js';
+export declare function parseSymbols(opts: {
+    file: string;
+    content: string;
+    lang: SymbolLang;
+}): Promise<FileSymbols>;
+export { detectLang } from './ts-parser.js';
+//# sourceMappingURL=go-parser.d.ts.map

package/dist/codebase-index/go-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"go-parser.d.ts","sourceRoot":"","sources":["../../src/codebase-index/go-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAyB,UAAU,EAAE,MAAM,aAAa,CAAC;AAIlF,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;CAClB,GAAG,OAAO,CAAC,WAAW,CAAC,CAavB;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/codebase-index/index-service.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Execution-location-agnostic index operations.
+ *
+ * One implementation, two callers: the index worker thread (production —
+ * synchronous SQLite and the TypeScript parser can never block the main
+ * thread / terminal UI there) and the inline fallback inside the host (tests,
+ * `WRONGSTACK_INDEX_INLINE=1`, or runtimes where the worker file is missing).
+ *
+ * Every operation opens its own short-lived IndexStore, exactly like the old
+ * per-call code paths did — there is no connection state to share, which keeps
+ * multi-project usage trivially correct and crash recovery simple.
+ */
+import type { IndexResult, IndexStats } from './schema.js';
+import type { IndexOpArgs, SearchOpArgs, SearchOpResult, StatsOpArgs } from './worker-protocol.js';
+export interface ServiceHooks {
+    signal?: AbortSignal | undefined;
+    onProgress?: ((current: number, total: number) => void) | undefined;
+}
+/** Full or per-file index run. */
+export declare function indexService(args: IndexOpArgs, hooks?: ServiceHooks): Promise<IndexResult>;
+/** Ranked symbol search (FTS5 inside SQLite; BM25 fallback without FTS5). */
+export declare function searchService(args: SearchOpArgs): SearchOpResult;
+/** Index health and statistics. */
+export declare function statsService(args: StatsOpArgs): IndexStats;
+//# sourceMappingURL=index-service.d.ts.map

package/dist/codebase-index/index-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-service.d.ts","sourceRoot":"","sources":["../../src/codebase-index/index-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAA0B,MAAM,aAAa,CAAC;AACnF,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAenG,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACrE;AAED,kCAAkC;AAClC,wBAAsB,YAAY,CAChC,IAAI,EAAE,WAAW,EACjB,KAAK,GAAE,YAAiB,GACvB,OAAO,CAAC,WAAW,CAAC,CAWtB;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,cAAc,CAgBhE;AAED,mCAAmC;AACnC,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAO1D"}