pi-lens 4.3.0 → 4.4.1

package/dist/chunk-3PNFWVHT.js

@@ -0,0 +1,201 @@
+import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
+import {
+  createNdjsonLogger,
+  getGlobalPiLensLogDir,
+  getMaxLogSizeMB,
+  getTurnId,
+  isTestMode
+} from "./chunk-VSMJK3ZJ.js";
+import {
+  normalizeLoggedPath
+} from "./chunk-G3RLJYA2.js";
+
+// dist/clients/latency-logger.js
+import * as path from "node:path";
+var LATENCY_LOG_DIR = getGlobalPiLensLogDir();
+var LATENCY_LOG_FILE = path.join(LATENCY_LOG_DIR, "latency.log");
+var writer = createNdjsonLogger({
+  filePath: LATENCY_LOG_FILE,
+  maxBytes: getMaxLogSizeMB() * 1024 * 1024
+});
+var RECENT_PHASE_CAP = 5;
+var recentPhases = [];
+var LAST_PHASE_EXCLUDED = /* @__PURE__ */ new Set([
+  "loop_block",
+  "lsp_typescript_project_identity",
+  "advisory_provenance_decision",
+  "authoritative_content_attachment_decision",
+  "agent_end_deferred_mutation_drain",
+  "agent_end_deferred_mutation_requeue",
+  "session_end_bus_rollup",
+  "cache_usage_summary",
+  "test_runner_failed_target_state",
+  "turn_end_test_selection",
+  "lsp_aux_wait_outcome",
+  "tool_set_mutation",
+  "availability_decision",
+  "finding_dead_path_drop",
+  "finding_stale_line_demote",
+  "finding_path_stat_budget_exhausted",
+  "lsp_scanner_coverage_gap",
+  "lsp_notify_resync_deferred",
+  "lsp_notify_write_late_landed",
+  "lsp_notify_stall_cpu_busy",
+  "degradation_ledger",
+  "path_attribution_verified_rollup",
+  "concurrent_session_bind_rollup",
+  "auxiliary_readiness",
+  "lsp_empty_first_publish_held",
+  "lsp_diagnostics_fence",
+  "lsp_rules_refreshed",
+  "read_guard_conversation_read",
+  "read_widening_note",
+  "session_handoff_slot",
+  "session_handoff_adopt",
+  "session_store_action",
+  "session_end_fence_rollup",
+  "format_late_resync_chained"
+]);
+var liveBrackets = /* @__PURE__ */ new Map();
+var closedBrackets = [];
+function phaseStarted(phase) {
+  const token = { phase, startedAt: (/* @__PURE__ */ new Date()).toISOString() };
+  liveBrackets.set(token, true);
+  return token;
+}
+function phaseFinished(token) {
+  if (!liveBrackets.delete(token))
+    return;
+  closedBrackets = [
+    {
+      phase: token.phase,
+      startedAt: token.startedAt,
+      closedAt: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    ...closedBrackets
+  ].slice(0, RECENT_PHASE_CAP);
+}
+var oncePerSessionPhases = /* @__PURE__ */ new Set();
+var sessionRecordSeq = 0;
+function mintSessionRecordId() {
+  sessionRecordSeq += 1;
+  return `${process.pid.toString(36)}-${Date.now().toString(36)}-${sessionRecordSeq.toString(36)}`;
+}
+var sessionRecordId = mintSessionRecordId();
+function currentSessionRecordId() {
+  return sessionRecordId;
+}
+function claimKey(phase, scope) {
+  return `${phase}\0${scope}`;
+}
+function claimPhaseOncePerSession(phase, scope) {
+  const key = claimKey(phase, scope);
+  if (oncePerSessionPhases.has(key))
+    return false;
+  oncePerSessionPhases.add(key);
+  return true;
+}
+function releasePhaseClaim(phase, scope) {
+  oncePerSessionPhases.delete(claimKey(phase, scope));
+}
+function logLatency(entry) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString();
+  if (entry.type === "phase" && entry.phase && !LAST_PHASE_EXCLUDED.has(entry.phase)) {
+    recentPhases = [
+      { phase: entry.phase, ts, metadata: entry.metadata },
+      ...recentPhases
+    ].slice(0, RECENT_PHASE_CAP);
+  }
+  if (isTestMode()) {
+    return;
+  }
+  writer.log({
+    ...entry,
+    ts,
+    pid: process.pid,
+    turnId: entry.turnId ?? getTurnId(),
+    filePath: normalizeLoggedPath(entry.filePath)
+  });
+}
+
+// dist/clients/config-diagnostic-codes.js
+var STABILITY_TIER_KEY = "x-stability";
+var CONFIG_SCHEMA_ID = "https://raw.githubusercontent.com/apmantza/pi-lens/master/docs/schema/pi-lens-config-v1.json";
+var CONFIG_SCHEMA_ANCHOR_KEY = "$schema";
+function configDiagnosticMarker(code) {
+  return `[${code}]`;
+}
+function withConfigDiagnosticCode(message, code) {
+  const marker = configDiagnosticMarker(code);
+  return message.includes(marker) ? message : `${message} ${marker}`;
+}
+var LSP_DEPRECATION_WINDOW = {
+  deprecatedSince: "4.1.4",
+  removeNotBefore: "5.0.0"
+};
+var LEGACY_KEY = {
+  kind: "key",
+  code: "PILENS_CFG_0002",
+  ...LSP_DEPRECATION_WINDOW
+};
+var LEGACY_FILE = {
+  kind: "file",
+  code: "PILENS_CFG_0003",
+  ...LSP_DEPRECATION_WINDOW
+};
+var DEPRECATED_CONFIG_SURFACES = [
+  {
+    ...LEGACY_KEY,
+    surface: "servers",
+    reason: "custom-server definitions move to the unified catalog schema; the bare string command + args form is replaced by the trust-gated ProcessSpec (#2416)."
+  },
+  {
+    ...LEGACY_KEY,
+    surface: "serverOverrides",
+    reason: "per-server initializationOptions overrides fold into the catalog's field-wise merge, keyed by the same public server IDs (#2416)."
+  },
+  {
+    ...LEGACY_KEY,
+    surface: "disabledServers",
+    reason: "replaced by the catalog's per-entry `enabled: false`, which carries monotonic deny precedence (#1416/#2415)."
+  },
+  {
+    ...LEGACY_KEY,
+    surface: "warmFiles",
+    reason: "session warm-up seeds become a per-server catalog field rather than a config-root list (#2416)."
+  },
+  {
+    ...LEGACY_FILE,
+    surface: ".pi-lens/lsp.json",
+    reason: "project LSP settings consolidate into `.pi-lens.json` under the unified envelope (#2426)."
+  },
+  {
+    ...LEGACY_FILE,
+    surface: "pi-lsp.json",
+    reason: "pre-rename project location; superseded by `.pi-lens.json` (#2426)."
+  },
+  {
+    ...LEGACY_FILE,
+    surface: "pi-lens.json",
+    reason: "undotted project-config basename; superseded by `.pi-lens.json` (#2426)."
+  },
+  {
+    ...LEGACY_FILE,
+    surface: "~/.pi-lens/lsp.json",
+    reason: "global LSP settings consolidate into `~/.pi-lens/config.json` (#2426)."
+  }
+];
+
+export {
+  STABILITY_TIER_KEY,
+  CONFIG_SCHEMA_ID,
+  CONFIG_SCHEMA_ANCHOR_KEY,
+  withConfigDiagnosticCode,
+  DEPRECATED_CONFIG_SURFACES,
+  phaseStarted,
+  phaseFinished,
+  currentSessionRecordId,
+  claimPhaseOncePerSession,
+  releasePhaseClaim,
+  logLatency
+};

package/dist/chunk-3TTPKMEF.js

@@ -0,0 +1,162 @@
+import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
+import {
+  GRAPH_PERSIST_MAX_ELEMENTS_DEFAULT,
+  REVIEW_GRAPH_VERSION,
+  _getReviewGraphCacheStateForTests,
+  _getReviewGraphRebuildCountersForTests,
+  _getReviewGraphWorkspaceCacheKeysForTests,
+  _getReviewGraphWorkspaceGraphForTests,
+  _persistedCoverageForTests,
+  _readReviewGraphCheckpointForTests,
+  _resetCwdWorktreeMismatchLogForTests,
+  _resetReviewGraphBuildAttemptsForTests,
+  _resetReviewGraphRebuildCountersForTests,
+  _resetReviewGraphSizeSkipTtlForTests,
+  _resetReviewGraphSizeSkipVerdictsForTests,
+  _resetReviewGraphSourcePathMemoForTests,
+  _resetReviewGraphStageSweepForTests,
+  _setLastGraphBuildInfoForTests,
+  _setReviewGraphBuildGateForTests,
+  _setReviewGraphEntryBudgetForTests,
+  _setReviewGraphEntryCounterForTests,
+  _setReviewGraphWorkspaceEntryForTests,
+  _setSessionReviewGraphFactForTests,
+  buildOrUpdateGraph,
+  captureReviewGraphStructuralIr,
+  clearGraphCache,
+  clearReviewGraphWorkspaceCache,
+  estimateReviewGraphStoreBytes,
+  extractSymbolsAndRefsFromGraph,
+  flushReviewGraphPersist,
+  flushReviewGraphPersistsForExitForTests,
+  flushReviewGraphPersistsForTests,
+  formatReviewGraphRevisionDriftNote,
+  getCachedReviewGraph,
+  getCheckpointOffloadCountForTests,
+  getGraphBuildInfoForGraph,
+  getGraphImportChanges,
+  getGraphSourceFiles,
+  getLastGraphBuildInfo,
+  getLastReviewGraphBuildAttempt,
+  getReviewGraphCacheIdentity,
+  getReviewGraphPersistWorkerHeapStatistics,
+  getReviewGraphRevisionDrift,
+  getReviewGraphSizeSkipVerdict,
+  getReviewGraphWorkerFallbackReasonForTests,
+  getReviewGraphWorkspaceCacheSnapshot,
+  graphBuildInfoIsTrustworthy,
+  graphWasmTrapDetail,
+  isGraphBuildInFlight,
+  isReviewGraphMigrationNeeded,
+  mapKindToTreeSitterLanguage,
+  refreshReviewGraphPersistWorkerHeapStatistics,
+  resetReviewGraphPersistWorkerForTests,
+  reviewGraphCachePath,
+  terminateReviewGraphPersistWorkerForTests,
+  waitForReviewGraphPersistsForTests
+} from "./chunk-V5MEBST3.js";
+import "./chunk-3MED75HT.js";
+import "./chunk-IMSQR4WO.js";
+import "./chunk-MTDRLSI7.js";
+import "./chunk-OZJINN4O.js";
+import "./chunk-3JSEWUWI.js";
+import "./chunk-XIMYZ3JA.js";
+import "./chunk-IQZXOZ7S.js";
+import "./chunk-LNOMA3MP.js";
+import "./chunk-U52SAGRM.js";
+import "./chunk-5W3R6LFT.js";
+import "./chunk-UEAHAMEI.js";
+import "./chunk-Z54ZSOBZ.js";
+import "./chunk-KJCWXUUS.js";
+import "./chunk-QOZXJ4NA.js";
+import "./chunk-6XX5HCLK.js";
+import "./chunk-S6AMWKPC.js";
+import "./chunk-F5VLZHUW.js";
+import "./chunk-AXKPQ6ZI.js";
+import "./chunk-7BX5DWSA.js";
+import "./chunk-IUKPRZER.js";
+import "./chunk-Z3CCVDUB.js";
+import "./chunk-XGUL4SLQ.js";
+import "./chunk-2BEMIWEW.js";
+import "./chunk-LD7WFTRX.js";
+import "./chunk-IUR76K6A.js";
+import "./chunk-T4QZ6FEH.js";
+import "./chunk-D6YF5HKX.js";
+import "./chunk-CMU4RMJB.js";
+import "./chunk-O7HZX7CA.js";
+import "./chunk-VYKKMYVT.js";
+import "./chunk-BNKLYOOO.js";
+import "./chunk-USHG4DLH.js";
+import "./chunk-H5EV3VMF.js";
+import "./chunk-T54VJRAD.js";
+import "./chunk-BW5KFIQC.js";
+import "./chunk-QYF5S6P6.js";
+import "./chunk-64LU2OVH.js";
+import "./chunk-N2IRDBZI.js";
+import "./chunk-Z6BB4JLQ.js";
+import "./chunk-2EECBNC5.js";
+import "./chunk-7ELY2CSM.js";
+import "./chunk-34OCDWOS.js";
+import "./chunk-3PNFWVHT.js";
+import "./chunk-VSMJK3ZJ.js";
+import "./chunk-LJDODBBZ.js";
+import "./chunk-UGSMCQ4D.js";
+import "./chunk-ABBOA7UD.js";
+import "./chunk-G3RLJYA2.js";
+import "./chunk-NXL4FFQQ.js";
+export {
+  GRAPH_PERSIST_MAX_ELEMENTS_DEFAULT,
+  REVIEW_GRAPH_VERSION,
+  _getReviewGraphCacheStateForTests,
+  _getReviewGraphRebuildCountersForTests,
+  _getReviewGraphWorkspaceCacheKeysForTests,
+  _getReviewGraphWorkspaceGraphForTests,
+  _persistedCoverageForTests,
+  _readReviewGraphCheckpointForTests,
+  _resetCwdWorktreeMismatchLogForTests,
+  _resetReviewGraphBuildAttemptsForTests,
+  _resetReviewGraphRebuildCountersForTests,
+  _resetReviewGraphSizeSkipTtlForTests,
+  _resetReviewGraphSizeSkipVerdictsForTests,
+  _resetReviewGraphSourcePathMemoForTests,
+  _resetReviewGraphStageSweepForTests,
+  _setLastGraphBuildInfoForTests,
+  _setReviewGraphBuildGateForTests,
+  _setReviewGraphEntryBudgetForTests,
+  _setReviewGraphEntryCounterForTests,
+  _setReviewGraphWorkspaceEntryForTests,
+  _setSessionReviewGraphFactForTests,
+  buildOrUpdateGraph,
+  captureReviewGraphStructuralIr,
+  clearGraphCache,
+  clearReviewGraphWorkspaceCache,
+  estimateReviewGraphStoreBytes,
+  extractSymbolsAndRefsFromGraph,
+  flushReviewGraphPersist,
+  flushReviewGraphPersistsForExitForTests,
+  flushReviewGraphPersistsForTests,
+  formatReviewGraphRevisionDriftNote,
+  getCachedReviewGraph,
+  getCheckpointOffloadCountForTests,
+  getGraphBuildInfoForGraph,
+  getGraphImportChanges,
+  getGraphSourceFiles,
+  getLastGraphBuildInfo,
+  getLastReviewGraphBuildAttempt,
+  getReviewGraphCacheIdentity,
+  getReviewGraphPersistWorkerHeapStatistics,
+  getReviewGraphRevisionDrift,
+  getReviewGraphSizeSkipVerdict,
+  getReviewGraphWorkerFallbackReasonForTests,
+  getReviewGraphWorkspaceCacheSnapshot,
+  graphBuildInfoIsTrustworthy,
+  graphWasmTrapDetail,
+  isGraphBuildInFlight,
+  isReviewGraphMigrationNeeded,
+  mapKindToTreeSitterLanguage,
+  refreshReviewGraphPersistWorkerHeapStatistics,
+  resetReviewGraphPersistWorkerForTests,
+  reviewGraphCachePath,
+  terminateReviewGraphPersistWorkerForTests,
+  waitForReviewGraphPersistsForTests
+};

package/dist/chunk-5JHXUETW.js

@@ -0,0 +1,326 @@
+import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
+import {
+  createAvailabilityProbeFlight,
+  probeToolAsync
+} from "./chunk-CMU4RMJB.js";
+import {
+  classifyProbeFailure,
+  createAvailabilityLatch,
+  describeInstallAttempt,
+  describeProbeEvidence,
+  logAvailabilityDecision,
+  startHostStallSampler
+} from "./chunk-O7HZX7CA.js";
+import {
+  createSingleFlight
+} from "./chunk-BW5KFIQC.js";
+import {
+  createSubsystemLogger
+} from "./chunk-34OCDWOS.js";
+
+// dist/clients/security-scan-client.js
+import * as path from "node:path";
+var securityProbeFlights = createAvailabilityProbeFlight();
+var SecurityScanClient = class {
+  toolName;
+  /**
+   * Availability memo, backed by the shared transient-aware latch (#1467).
+   *
+   * Assigning `false` still means "durable: this machine does not have the
+   * tool" — every existing subclass write keeps its meaning. A transient
+   * failure must expire instead: `probeVersion` latches its own transient
+   * verdicts (#1501), and any other transient failure (a scan or install
+   * timeout) goes through `markTransientlyUnavailable`, so the tool can come
+   * back without a host restart.
+   */
+  availabilityLatch = createAvailabilityLatch();
+  get available() {
+    return this.availabilityLatch.read();
+  }
+  set available(value) {
+    if (value === true) {
+      this.availabilityLatch.noteAvailable();
+      return;
+    }
+    if (value !== false) {
+      this.availabilityLatch.reset();
+      return;
+    }
+    this.availabilityLatch.noteUnavailable("missing", "not-found");
+    this.logDurableAbsence();
+  }
+  /**
+   * Latch a durable absence WITH the facts behind it. Prefer this over
+   * `available = false` wherever the call site knows what actually failed — a
+   * `missing` row carrying `install: "failed"` is a retry candidate, one
+   * carrying `install: "not-attempted"` is a policy decision, and a bare one is
+   * a plain absence. Only the record can tell them apart.
+   */
+  noteDurableAbsence(evidence, options = {}) {
+    this.availabilityLatch.noteUnavailable("missing", "not-found");
+    this.logDurableAbsence(evidence, options.elapsedMs);
+  }
+  /**
+   * One record per durable-absence ASSERTION, whether or not the call site had
+   * evidence. Before this, `available = false` after a failed install was a
+   * silent latch: the tool went quiet for the session with nothing in
+   * latency.log to audit (#1500). Bounded — the verdict latches, so at most one
+   * row per client per session.
+   *
+   * `elapsedMs` is whatever the caller measured (an install attempt's duration);
+   * there is no probe here, so it is 0 unless the caller has something real.
+   */
+  logDurableAbsence(evidence, elapsedMs = 0) {
+    logAvailabilityDecision({
+      tool: this.toolName,
+      producer: "security-scan",
+      verdict: "unavailable",
+      outcome: "missing",
+      cause: "not-found",
+      elapsedMs,
+      latched: true,
+      classifiedBy: "caller",
+      ...evidence !== void 0 && { evidence }
+    });
+  }
+  /** Outcome of the most recent `probeVersion` call. */
+  lastProbeOutcome = null;
+  /** Availability resolution is instance-owned; only its external probe is shared. */
+  ensureFlight = createSingleFlight();
+  inFlight = /* @__PURE__ */ new Map();
+  binaryPath = null;
+  log;
+  /**
+   * @param toolName binary / installer id used for probes, logs and auto-install
+   * @param verbose  when true, diagnostics are written to stderr
+   */
+  constructor(toolName, verbose = false) {
+    this.toolName = toolName;
+    this.log = verbose ? createSubsystemLogger(toolName) : () => {
+    };
+  }
+  /**
+   * Resolve (once) whether the scanner is usable, sharing the probe promise
+   * across concurrent first-time callers. The tool-specific probe + optional
+   * install lives in `doEnsureAvailable`.
+   */
+  async ensureAvailable() {
+    if (this.available !== null)
+      return this.available;
+    return this.ensureFlight.run("availability", () => this.doEnsureAvailable());
+  }
+  /**
+   * Spawn `toolName <versionArgs>` and report whether it answered cleanly.
+   * Classifies the failure (`lastProbeOutcome`) and emits one
+   * availability-decision record, so a probe that keeps timing out is visible
+   * in latency.log rather than inferred from silence (#1467).
+   *
+   * Latch ownership is split by outcome: success and durable failures leave
+   * `this.available` to the caller (a missing binary may still be
+   * auto-installed), while a TRANSIENT failure is latched by the seam itself
+   * with its cooldown — the retry schedule only exists once the latch owns
+   * the verdict, and the record is incomplete without it (#1501). Callers
+   * must not re-mark a probe transient (a second noteUnavailable would
+   * double-escalate the cooldown).
+   */
+  async probeVersion(versionArgs) {
+    const sampler = startHostStallSampler();
+    const startedAt = Date.now();
+    let probe;
+    let hostStallMs;
+    let resolvedBinaryPath = null;
+    let probeJoined = false;
+    try {
+      const shared = securityProbeFlights.run(`security:${this.toolName}|${versionArgs.join("|")}`, async () => {
+        const { findManagedToolBinary } = await import("./probes/installer.js");
+        const managed = await findManagedToolBinary(this.toolName);
+        return {
+          probe: await probeToolAsync(managed ?? this.toolName, versionArgs, {
+            timeout: 5e3
+          }),
+          binaryPath: managed ?? null
+        };
+      });
+      probeJoined = shared.joined;
+      const flightResult = await shared.promise;
+      probe = flightResult.probe;
+      resolvedBinaryPath = flightResult.binaryPath;
+      if (!probe.error && probe.status === 0 && flightResult.binaryPath) {
+        this.binaryPath = flightResult.binaryPath;
+      }
+    } finally {
+      hostStallMs = sampler.stop();
+    }
+    const elapsedMs = Date.now() - startedAt;
+    if (!probe.error && probe.status === 0) {
+      this.lastProbeOutcome = "success";
+      this.log(`${this.toolName} found: ${probe.stdout.trim().split("\n")[0]}`);
+      logAvailabilityDecision({
+        tool: this.toolName,
+        producer: "security-scan",
+        verdict: "available",
+        outcome: "success",
+        cause: "ok",
+        elapsedMs,
+        latched: true,
+        hostStallMs,
+        budgetMs: 5e3,
+        classifiedBy: probeJoined ? "joined" : "probe",
+        evidence: {
+          ...describeProbeEvidence(probe),
+          ...resolvedBinaryPath && {
+            binary: path.basename(resolvedBinaryPath),
+            source: "managed-dir"
+          }
+        }
+      });
+      return true;
+    }
+    const { outcome, cause, evidence } = classifyProbeFailure(probe, {
+      hostStallMs
+    });
+    this.lastProbeOutcome = outcome;
+    const retryAfterMs = outcome === "transient" ? this.availabilityLatch.noteUnavailable("transient", cause) : 0;
+    logAvailabilityDecision({
+      tool: this.toolName,
+      producer: "security-scan",
+      verdict: "unavailable",
+      outcome,
+      cause,
+      elapsedMs,
+      latched: outcome !== "transient",
+      hostStallMs,
+      ...retryAfterMs > 0 && { retryAfterMs },
+      budgetMs: 5e3,
+      classifiedBy: probeJoined ? "joined" : "probe",
+      evidence: {
+        ...evidence,
+        ...resolvedBinaryPath && {
+          binary: path.basename(resolvedBinaryPath),
+          source: "managed-dir"
+        }
+      }
+    });
+    return false;
+  }
+  /** True when the last probe failed for a reason that is not the tool's fault. */
+  probeWasTransient() {
+    return this.lastProbeOutcome === "transient";
+  }
+  /**
+   * Record a non-durable unavailability: the verdict expires after a cooldown
+   * and the next `ensureAvailable` re-probes.
+   *
+   * Returns that cooldown in ms so the caller can put it in its decision
+   * record. A latch you can read in `latency.log` without the retry schedule
+   * beside it only tells you the tool is off, not when it comes back.
+   *
+   * For NON-probe transient failures only (scan/install timeouts):
+   * `probeVersion` latches and logs its own transient verdicts (#1501), so
+   * re-marking one here would double-escalate the cooldown.
+   *
+   * Pass `opts.operationClass: "install"` when the failed operation was a
+   * network install/compile rather than a cheap probe (#1497): the retry
+   * escalates on the install-class schedule, on its OWN cooldown slot (a
+   * cheap probe failure can never shorten it), and latches for the session at
+   * the attempt ceiling, in which case the return is 0 (latched).
+   */
+  markTransientlyUnavailable(cause = "probe-timeout", opts) {
+    return this.availabilityLatch.noteUnavailable("transient", cause, opts);
+  }
+  /**
+   * The cause the LATCH settled on, which is not always the cause the caller
+   * passed in: at the install-class ceiling the latch rewrites it to
+   * `install-retry-exhausted` (#1497). A decision record built from the
+   * caller's own cause would say `probe-timeout` for a verdict that is no
+   * longer being retried, so the record reads it back from here.
+   */
+  latchedCause() {
+    return this.availabilityLatch.getCause();
+  }
+  /**
+   * #1623: public window onto the availability verdict for callers OUTSIDE
+   * the dispatch graph (mode=full's fresh-fetch) that need to say WHY
+   * `ensureAvailable()` most recently returned false — using the SAME
+   * `AvailabilityOutcome`/`AvailabilityCause` taxonomy every dispatch-side
+   * message is built from, rather than a re-guessed "binary unavailable"
+   * that can't tell a transient retry-cooldown probe from a durable absence.
+   * `latchedCause()`/`lastProbeOutcome` above stay `protected` for
+   * dispatch-internal callers; this is the one public seam for everyone
+   * else.
+   */
+  getAvailabilityVerdict() {
+    return {
+      outcome: this.availabilityLatch.getOutcome(),
+      cause: this.availabilityLatch.getCause(),
+      retryAtMs: this.availabilityLatch.getRetryAtMs()
+    };
+  }
+  /**
+   * Standard availability path for the GitHub-release tools (gitleaks, trivy):
+   * PATH probe first, then fall back to the pi-lens installer's `ensureTool`.
+   * Records the resolved binary path and sets `this.available`.
+   */
+  async ensureViaInstaller(versionArgs) {
+    if (await this.probeVersion(versionArgs)) {
+      this.available = true;
+      return true;
+    }
+    if (this.probeWasTransient()) {
+      this.log(`${this.toolName} availability probe timed out; not installing, will retry`);
+      return false;
+    }
+    this.log(`${this.toolName} not found, attempting auto-install`);
+    const { ensureTool, getInstallAttempt } = await import("./probes/installer.js");
+    const installStartedAt = Date.now();
+    const installed = await ensureTool(this.toolName);
+    if (!installed) {
+      const attempt = getInstallAttempt(this.toolName);
+      this.log(attempt?.outcome === "failed" ? `${this.toolName} auto-install failed: ${attempt.reason ?? "unknown reason"}` : `${this.toolName} auto-install did not run: ${attempt?.reason ?? "no attempt recorded"}`);
+      this.noteDurableAbsence(describeInstallAttempt(attempt), {
+        elapsedMs: Date.now() - installStartedAt
+      });
+      return false;
+    }
+    this.binaryPath = installed;
+    this.available = true;
+    this.log(`${this.toolName} auto-installed at ${installed}`);
+    logAvailabilityDecision({
+      tool: this.toolName,
+      verdict: "available",
+      outcome: "success",
+      cause: "ok",
+      elapsedMs: Date.now() - installStartedAt,
+      latched: true,
+      classifiedBy: "caller",
+      evidence: {
+        install: "succeeded",
+        binary: path.basename(installed),
+        source: "managed-dir"
+      }
+    });
+    return true;
+  }
+  /**
+   * Per-target scan re-entrancy: when a scan for `key` is already running, the
+   * concurrent caller shares the in-flight promise instead of spawning a second
+   * process. The entry is cleared when the run settles.
+   */
+  dedupeScan(key, run) {
+    const existing = this.inFlight.get(key);
+    if (existing) {
+      this.log(`Scan already in flight for ${key}; sharing result`);
+      return existing;
+    }
+    const promise = run().finally(() => {
+      if (this.inFlight.get(key) === promise)
+        this.inFlight.delete(key);
+    });
+    this.inFlight.set(key, promise);
+    return promise;
+  }
+};
+
+export {
+  SecurityScanClient
+};