@wrongstack/tools 0.310.1 → 0.313.1

package/dist/process-registry.js

@@ -1,654 +1,11 @@
-// src/process-registry.ts
-import { spawn } from "node:child_process";
-import * as os from "node:os";
-
-// src/circuit-breaker.ts
-var DEFAULT_MAX_CONSECUTIVE_FAILURES = 5;
-var DEFAULT_SLOW_CALL_THRESHOLD_MS = 18e4;
-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;
-  /**
-   * Master enable flag. When false the breaker is bypassed: `beforeCall`
-   * always returns true and `afterCall` records nothing. The class itself
-   * defaults to enabled (so the standalone unit tests exercise tripping); the
-   * ProcessRegistry flips this off until the user opts in via `/settings`.
-   */
-  enabled = true;
-  /**
-   * Fired (best-effort) when the breaker transitions into the `open` state.
-   * The registry uses this to arm its auto kill/reset countdown.
-   */
-  onTrip;
-  /**
-   * Fired (best-effort) when the breaker returns to `closed` after having been
-   * open/half-open. The registry uses this to cancel a pending kill/reset.
-   */
-  onReset;
-  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;
-  }
-  /** Toggle the master enable. Disabling resets to a clean `closed` state. */
-  setEnabled(enabled) {
-    if (this.enabled === enabled) return;
-    this.enabled = enabled;
-    if (!enabled) this._reset();
-  }
-  get isEnabled() {
-    return this.enabled;
-  }
-  /**
-   * 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() {
-    if (!this.enabled) return true;
-    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.
-   *
-   * @param bypass - If true, skip the circuit breaker check entirely.
-   *                  Use for background/fire-and-forget processes that should
-   *                  not affect breaker state.
-   */
-  beforeCall(bypass = false) {
-    if (bypass || !this.enabled) return true;
-    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.
-   *
-   * @param bypass - If true, do not update breaker state.
-   *                  Use for background/fire-and-forget processes.
-   */
-  afterCall(durationMs, failed, bypass = false) {
-    if (bypass || !this.enabled) return;
-    const now = Date.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();
-    this.window = [];
-    try {
-      this.onTrip?.();
-    } catch {
-    }
-  }
-  _reset() {
-    const wasRecovering = this.state !== "closed";
-    this.state = "closed";
-    this.consecutiveFailures = 0;
-    this.window = [];
-    this.openedAt = null;
-    if (wasRecovering) {
-      try {
-        this.onReset?.();
-      } catch {
-      }
-    }
-  }
-  /** 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/_redact-command.ts
-import { expectDefined } from "@wrongstack/core/utils";
-var SENSITIVE_FLAG_PATTERNS = [
-  // --flag=value  or  --flag "value"  (value captured up to next space or comma)
-  /--(?:token|password|passwd|pwd|secret|api[-_]?key|api[-_]?secret|auth|credential|private[-_]?key|access[-_]?key|github[-_]?token|gh[-_]?token|bearer|jwt|oauth|pin|pincode|passphrase|access[-_]?token)(?:[=\s,][^\s]*)?/gi,
-  // -t short flag (token): attached (-tVALUE), separated (-t VALUE), or -t=VALUE.
-  // (?<![-\w]) anchors to a token start so we don't match the `-t` inside `--token`.
-  // The value must be token-like (>= 8 chars) so ordinary combined flags such
-  // as `tar -tf` / `ssh -tt` are not eaten. Global flag: EVERY occurrence is
-  // redacted, not just the first.
-  // NOTE: synced with @wrongstack/core observability/redact-command.ts.
-  /(?<![-\w])-t(?:[=\s]+)?[^\s,-]{8,}/g,
-  // -p|-password|-a (redis auth) short flags: attached + separated + =value.
-  // Same token-start anchor; over-redaction is an accepted tradeoff for a
-  // redaction function. Synced with core copy.
-  /(?<![-\w])-(?:password|p|a)(?:[=\s]+)?[^\s,-]+/gi,
-  // env var–style secrets: TOKEN=x, API_KEY=y, etc.
-  /(?:TOKEN|API_KEY|API_SECRET|AUTH_TOKEN|GITHUB_TOKEN|GH_TOKEN|BEARER|JWT|OAUTH|CREDENTIAL|SECRET|PRIVATE_KEY|PASSWORD|PASSWD|PASSPHRASE)\s*[=:]\s*[^\s,]+/gi,
-  // Generic high-entropy look: base64 strings >32 chars or hex strings >32 digits — but only
-  // when preceded by a flag name (e.g. --github-token=EyJ...). Global flag so
-  // every such flag in the command line is redacted, not just the first.
-  /--\w*(?:token|key|secret|password|passwd|auth|credential)\w*[=\s,][A-Za-z0-9+/=]{32,}/g
-];
-function redactCommand(cmd) {
-  let result = cmd;
-  for (const pattern of SENSITIVE_FLAG_PATTERNS) {
-    result = result.replace(pattern, (match) => {
-      const eq = match.indexOf("=");
-      const sp = match.search(/\s/);
-      const delim = eq !== -1 ? "=" : sp !== -1 ? match[sp] : null;
-      if (delim !== null) {
-        const flag = match.slice(0, match.indexOf(expectDefined(delim)) + 1);
-        return `${flag}[REDACTED]`;
-      }
-      if (match.startsWith("--")) {
-        return match;
-      }
-      return `${match.slice(0, 2)}[REDACTED]`;
-    });
-  }
-  return result;
-}
-
-// src/process-registry.ts
-var DEFAULT_GRACE_MS = 2e3;
-var WIN32_TASKKILL_TIMEOUT_MS = 5e3;
-function killWin32Tree(pid, opts = {}) {
-  try {
-    const child = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
-      stdio: "ignore",
-      windowsHide: true
-    });
-    let settled = false;
-    let timeout;
-    const settle = () => {
-      if (settled) return;
-      settled = true;
-      if (timeout) clearTimeout(timeout);
-      try {
-        opts.onSettled?.();
-      } catch {
-      }
-    };
-    child.on("error", settle);
-    child.on("close", settle);
-    timeout = setTimeout(
-      () => {
-        try {
-          child.kill();
-        } catch {
-        }
-        settle();
-      },
-      Math.max(1, opts.timeoutMs ?? WIN32_TASKKILL_TIMEOUT_MS)
-    );
-    timeout.unref?.();
-    child.unref();
-    return true;
-  } catch {
-    return false;
-  }
-}
-var ProcessRegistryImpl = class {
-  processes = /* @__PURE__ */ new Map();
-  breaker;
-  /**
-   * Auto kill/reset config. When the breaker trips and `autoKillResetMs > 0`,
-   * a countdown is armed; on expiry all tracked processes are killed and the
-   * breaker is reset to closed (forced recovery). Zero means manual recovery
-   * only (`/kill reset`).
-   */
-  autoKillResetMs = 0;
-  autoKillTimer = null;
-  autoKillArmedAt = null;
-  breakerCountdownListeners = [];
-  constructor(breakerConfig) {
-    this.breaker = new CircuitBreaker(breakerConfig);
-    this.breaker.onTrip = () => this._armAutoKillReset();
-    this.breaker.onReset = () => this._cancelAutoKillReset();
-    this.breaker.setEnabled(false);
-  }
-  register(info) {
-    this.processes.set(info.pid, {
-      ...info,
-      killed: false,
-      protected: info.protected ?? false,
-      background: info.background ?? false
-    });
-  }
-  _isSafeSignalPid(pid) {
-    return Number.isInteger(pid) && pid > 1 && pid !== process.pid && pid !== process.ppid;
-  }
-  _canSignalProcessGroup(p) {
-    return os.platform() !== "win32" && p.processGroupLeader === true && this._isSafeSignalPid(p.pid) && p.child !== null && typeof p.child.pid === "number" && p.child.pid === p.pid;
-  }
-  _killChildDirect(p, signal) {
-    try {
-      if (p.child) {
-        p.child.kill(signal);
-        return;
-      }
-      if (this._isSafeSignalPid(p.pid)) process.kill(p.pid, signal);
-    } catch {
-    }
-  }
-  _killPosix(p, signal) {
-    if (this._canSignalProcessGroup(p)) {
-      try {
-        process.kill(-p.pid, signal);
-        return;
-      } catch {
-      }
-    }
-    this._killChildDirect(p, signal);
-  }
-  /** Unregister a process by PID. Called on 'close' / 'exit' events. */
-  unregister(pid) {
-    this.processes.delete(pid);
-  }
-  /** Get a single process by PID. */
-  get(pid) {
-    this._pruneStale(pid);
-    return this.processes.get(pid);
-  }
-  /** Get all tracked processes. */
-  list() {
-    this._pruneAllStale();
-    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;
-  }
-  /** Count of active jobs explicitly launched in background mode. */
-  get activeBackgroundCount() {
-    let n = 0;
-    for (const p of this.processes.values()) {
-      if (p.background && !p.killed) n++;
-    }
-    return n;
-  }
-  /**
-   * Combined stats for observability — used by /ps and the TUI status bar.
-   */
-  stats() {
-    this._pruneAllStale();
-    return {
-      activeCount: this.activeCount,
-      backgroundCount: this.activeBackgroundCount,
-      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.
-   *
-   * @param bypass - If true, skip circuit breaker check (for background processes).
-   */
-  beforeCall(bypass = false) {
-    return this.breaker.beforeCall(bypass);
-  }
-  /**
-   * Called after a process finishes. `durationMs` is wall-clock time;
-   * `failed` is true for non-zero exit codes.
-   *
-   * @param bypass - If true, do not update circuit breaker state (for background processes).
-   */
-  afterCall(durationMs, failed, bypass = false) {
-    this.breaker.afterCall(durationMs, failed, bypass);
-  }
-  /** 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();
-  }
-  /**
-   * Configure circuit-breaker protection at runtime. Called from `/settings`
-   * (instant, all modes) and on TUI mount (applies persisted config).
-   *
-   * - `enabled` toggles whether the breaker gates `bash`/`exec`.
-   * - `autoKillResetMs` arms the auto kill/reset countdown when the breaker
-   *   trips (0 = manual recovery only).
-   *
-   * Re-applies cleanly on every call: cancels a pending countdown when the
-   * timeout is cleared or protection disabled, and re-arms if the breaker is
-   * currently open under the new settings.
-   */
-  setBreakerConfig(cfg) {
-    if (cfg.enabled !== void 0) this.breaker.setEnabled(cfg.enabled);
-    if (cfg.autoKillResetMs !== void 0) this.autoKillResetMs = Math.max(0, cfg.autoKillResetMs);
-    if (this.autoKillResetMs <= 0) {
-      this._cancelAutoKillReset();
-      return;
-    }
-    if (this.breaker.isEnabled && this.breaker.snapshot().state === "open") {
-      this._armAutoKillReset();
-    }
-  }
-  /**
-   * Live countdown to the next auto kill/reset, or null when nothing is armed.
-   * The TUI polls this on a 1s tick while armed so the statusline decrements.
-   */
-  getBreakerCountdown() {
-    if (this.autoKillArmedAt === null || this.autoKillResetMs <= 0) return null;
-    const elapsed = Date.now() - this.autoKillArmedAt;
-    return {
-      remainingMs: Math.max(0, this.autoKillResetMs - elapsed),
-      totalMs: this.autoKillResetMs
-    };
-  }
-  /**
-   * Subscribe to countdown arm/cancel events. Returns an unsubscribe function.
-   * Use {@link getBreakerCountdown} for the live ticking value between events.
-   */
-  onBreakerCountdownChange(listener) {
-    this.breakerCountdownListeners.push(listener);
-    return () => {
-      this.breakerCountdownListeners = this.breakerCountdownListeners.filter((l) => l !== listener);
-    };
-  }
-  _emitBreakerCountdown() {
-    const snap = this.getBreakerCountdown();
-    for (const l of this.breakerCountdownListeners) {
-      try {
-        l(snap);
-      } catch {
-      }
-    }
-  }
-  /**
-   * Arm the auto kill/reset countdown. Idempotent: re-arming resets the window
-   * (a fresh trip after a failed half-open probe restarts the clock). No-op
-   * when protection is off or no timeout is configured.
-   */
-  _armAutoKillReset() {
-    if (this.autoKillResetMs <= 0 || !this.breaker.isEnabled) return;
-    this._clearAutoKillTimer();
-    this.autoKillArmedAt = Date.now();
-    this.autoKillTimer = setTimeout(() => {
-      this.autoKillTimer = null;
-      this.autoKillArmedAt = null;
-      this.killAll({ force: false, preserveBackground: true });
-      this.breaker.forceReset();
-      this._emitBreakerCountdown();
-    }, this.autoKillResetMs);
-    this.autoKillTimer.unref?.();
-    this._emitBreakerCountdown();
-  }
-  _cancelAutoKillReset() {
-    const wasArmed = this.autoKillArmedAt !== null;
-    this._clearAutoKillTimer();
-    if (wasArmed) {
-      this.autoKillArmedAt = null;
-      this._emitBreakerCountdown();
-    }
-  }
-  _clearAutoKillTimer() {
-    if (this.autoKillTimer !== null) {
-      clearTimeout(this.autoKillTimer);
-      this.autoKillTimer = null;
-    }
-  }
-  /** 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 = {}) {
-    this._pruneStale(pid);
-    const p = this.processes.get(pid);
-    if (!p) return false;
-    if (p.killed && opts.force !== true) return true;
-    if (p.protected && opts.includeProtected !== true) return false;
-    if (opts.preserveBackground && p.background) return false;
-    const { force = false, graceMs = DEFAULT_GRACE_MS } = opts;
-    const isWin = os.platform() === "win32";
-    if (isWin) {
-      const liveRealChild = p.child === null || p.child.exitCode === null && typeof p.child.pid === "number";
-      const directFallback = () => {
-        if (p.child && p.child.exitCode === null) {
-          try {
-            p.child.kill("SIGKILL");
-          } catch {
-          }
-        }
-      };
-      if (liveRealChild && killWin32Tree(pid, {
-        timeoutMs: Math.max(graceMs, WIN32_TASKKILL_TIMEOUT_MS),
-        onSettled: directFallback
-      })) {
-      } else {
-        this._killChildDirect(p, force ? "SIGKILL" : "SIGTERM");
-      }
-      p.killed = true;
-      return true;
-    }
-    try {
-      if (force) {
-        this._killPosix(p, "SIGKILL");
-      } else {
-        this._killPosix(p, "SIGTERM");
-        const timer = setTimeout(() => {
-          if (this.processes.has(pid) && !p.child?.killed) {
-            this._killPosix(p, "SIGKILL");
-          }
-        }, 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 = [];
-    const includeProtected = opts.includeProtected === true;
-    for (const pid of pids) {
-      const p = this.processes.get(pid);
-      if (!p) continue;
-      if (p.protected && !includeProtected) continue;
-      if (opts.preserveBackground && p.background) continue;
-      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;
-  }
-  /**
-   * Check whether a tracked process entry is stale — the child has exited
-   * (exitCode !== null) AND it's been in the registry long enough that the
-   * OS may have reused the PID for a new, unrelated process.
-   *
-   * P3 #24 (before-release.md): on POSIX, PIDs are reused after process
-   * exit. If a tracked process exits but its 'close' event hasn't fired yet
-   * (or was missed), the registry still holds the entry. A new process
-   * gets the same PID, and PID-based lookups (get, kill, shouldBlockKill)
-   * may incorrectly protect or target the wrong process.
-   *
-   * The 60s threshold is conservative — the OS typically waits much longer
-   * before reusing a PID, but we want to clean up before that becomes a risk.
-   */
-  _isStaleEntry(entry) {
-    if (entry.child === null) {
-      if (Date.now() - entry.startedAt <= 6e4) return false;
-      if (os.platform() === "win32") return false;
-      try {
-        process.kill(entry.pid, 0);
-        return false;
-      } catch (err) {
-        return err.code !== "EPERM";
-      }
-    }
-    return entry.child.exitCode !== null && Date.now() - entry.startedAt > 6e4;
-  }
-  /**
-   * Remove a stale entry for a specific PID before any PID-based lookup.
-   * This prevents PID reuse from causing the registry to act on a dead
-   * process that has been replaced by a new one with the same PID.
-   */
-  _pruneStale(pid) {
-    const entry = this.processes.get(pid);
-    if (entry && this._isStaleEntry(entry)) {
-      this.processes.delete(pid);
-    }
-  }
-  /**
-   * Remove every stale entry, not just one PID. `list()`/`stats()` — the
-   * surfaces the TUI status bar and `/ps` poll — must prune too: a child
-   * whose 'close' event never fires (e.g. Windows grandchildren holding stdio
-   * open) would otherwise linger in the registry until someone looks up its
-   * exact PID, and PID reuse meanwhile makes `get()`/`kill()` target the
-   * wrong process. RAM-leak audit 2026-07-31, MEDIUM.
-   */
-  _pruneAllStale() {
-    for (const [pid, entry] of this.processes) {
-      if (this._isStaleEntry(entry)) this.processes.delete(pid);
-    }
-  }
-};
-var _registry;
-function getProcessRegistry() {
-  if (!_registry) {
-    _registry = new ProcessRegistryImpl();
-  }
-  return _registry;
-}
-function _resetProcessRegistry() {
-  _registry = void 0;
-}
+import {
+  ProcessRegistryImpl,
+  _resetProcessRegistry,
+  getProcessRegistry,
+  killWin32Tree,
+  redactCommand
+} from "./chunk-3PVYQFRQ.js";
+import "./chunk-HFXSNKCV.js";
 export {
   ProcessRegistryImpl,
   _resetProcessRegistry,