agent-sanitizer 2.58.1 → 2.58.3

package/claude-hooks/lib/hook-io.mjs

@@ -805,6 +805,51 @@ function markerLockHeld(markerPath) {
   return null;
 }
 
+/**
+ * Is a setup process DEMONSTRABLY running right now?
+ *
+ * The strict twin of {@link probeSetupAlive}, and the two differ only in which
+ * way they fall when the evidence runs out. That one decides whether to keep
+ * WAITING for a dependency, so every ambiguity — an unreadable marker, an
+ * unparseable pid, no project dir — reads as alive: waiting a moment longer is
+ * cheap and giving up early fails a hook closed. This one decides whether to
+ * stop charging a caller for time it spent, so the same ambiguity must read as
+ * NOT running: an absence of evidence that the machine was busy is not evidence
+ * that it was, and discounting a wait on that basis would hide the very
+ * slowdowns the caller is measuring for.
+ *
+ * Positive evidence is one of two things: the setup lock is held (the kernel
+ * drops an flock the instant its holder dies, so held means running), or the
+ * marker's pid names a live process. A marker this uid does not own is not
+ * evidence about our setup at all.
+ * @param {string | null} markerPath
+ * @returns {boolean}
+ */
+export function setupRunning(markerPath) {
+  if (!markerIsTrusted(markerPath)) return false;
+  let raw;
+  try {
+    raw = readFileSync(/** @type {string} */ (markerPath), "utf8");
+  } catch {
+    return false;
+  }
+  const lines = raw.split("\n").map((line) => line.trim());
+  if (lines.includes(SETUP_LOCK_DECLARATION)) {
+    const held = markerLockHeld(/** @type {string} */ (markerPath));
+    if (held !== null) return held;
+  }
+  const pid = parseInt(lines[0], 10);
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM: the pid exists but belongs to another uid. It is running, which is
+    // what this answers; whose it is is markerIsTrusted's question, asked above.
+    return /** @type {NodeJS.ErrnoException} */ (err).code === "EPERM";
+  }
+}
+
 /**
  * Is the setup process that wrote `markerPath` still alive?
  *

package/claude-hooks/lib/hook-timing.mjs

@@ -27,7 +27,12 @@
  *
  * ONE-TIME PROVISIONING is excluded (see {@link excludeProvisioning}): charging
  * an install to the hook that merely waited it out would make the FIRST call of
- * every session cry wolf, which is the alert fatigue this notice fights.
+ * every session cry wolf, which is the alert fatigue this notice fights. A
+ * provisioning step running in ANOTHER process is excluded the same way and for
+ * the same reason ({@link excludeConcurrentProvisioning}) — a launch hook's
+ * install saturates the machine every other hook is sharing, and a wait spent
+ * inside a window the caller can show was provisioning is no more this hook's
+ * cost than its own install is.
  *
  * Dependency-free on purpose: everything imports this, including hook-io, so a
  * back-import would close a cycle. The one emitter it needs is passed in. The
@@ -63,6 +68,19 @@ export const SLOW_HOOK_THRESHOLD_MS = 1000;
  */
 export const SLOW_PROVISION_THRESHOLD_MS = 60000;
 
+/**
+ * The longest window {@link excludeConcurrentProvisioning} will discount.
+ *
+ * Ten times the hook budget, because the discount's whole premise is that the
+ * hook's work is small and the machine is busy: an instruction scan is tens of
+ * milliseconds of work, so a wait this far past its budget is not a busy box any
+ * more, whatever else is installing. Past the ceiling the run is measured in
+ * full and reports — the founding case of this module is a SessionStart scan
+ * that blocked startup for 30 SECONDS, and a cold-start install running
+ * alongside it must not be what buys that silence.
+ */
+export const CONCURRENT_PROVISION_CEILING_MS = 10 * SLOW_HOOK_THRESHOLD_MS;
+
 /** Where a reader is asked to send the timing. */
 const ISSUE_URL =
   "https://github.com/AlexanderMattTurner/agent-sanitizer/issues/new";
@@ -408,6 +426,57 @@ export async function excludeProvisioning(
   }
 }
 
+/**
+ * Run `work`, charging its duration to provisioning when a SESSION-LEVEL
+ * provisioning step was in flight for the whole of it — a neighbouring hook's
+ * dependency install, which saturates the machine this hook is only sharing.
+ * {@link excludeProvisioning} discounts the wait this process performs itself;
+ * this discounts the one it merely runs alongside.
+ *
+ * `setupAlive` is asked twice, before and after, and only a step alive at BOTH
+ * ends is charged. A step that started or finished mid-run leaves a window
+ * nothing here can apportion, and splitting it by guess would discount the
+ * hook's own work — so that run is measured in full and reports honestly.
+ *
+ * Wall-clock only, where {@link excludeProvisioning} charges CPU too: the
+ * install runs in ANOTHER process, so none of it lands in this one's CPU figure,
+ * and charging CPU here would discount the hook's own computing.
+ *
+ * Bounded by {@link CONCURRENT_PROVISION_CEILING_MS}, which is what stops the
+ * discount from hiding a wedged run: a window past the ceiling is charged to
+ * nobody but the hook, however busy the machine was, because at that magnitude
+ * the hook is the thing that is broken.
+ * @template T
+ * @param {() => Promise<T>} work
+ * @param {() => boolean} setupAlive  whether a session-level provisioning step
+ *   is running right now; the caller owns the evidence (a cold-start marker and
+ *   its PID), since this module reads no files of its own
+ * @param {() => number} [now]  injectable clock, for tests
+ * @returns {Promise<T>}
+ */
+export async function excludeConcurrentProvisioning(
+  work,
+  setupAlive,
+  now = Date.now,
+) {
+  const startedAlive = setupAlive();
+  const started = now();
+  try {
+    return await work();
+  } finally {
+    // In a `finally`, like every other charge here: a scan that THREW still
+    // waited out whatever the machine was doing, and the fault it reports is a
+    // separate matter from how long the wait was.
+    const elapsed = Math.max(0, now() - started);
+    if (
+      startedAlive &&
+      elapsed <= CONCURRENT_PROVISION_CEILING_MS &&
+      setupAlive()
+    )
+      provisioningMs += elapsed;
+  }
+}
+
 /**
  * Start measuring; each reader on the returned object reports what has elapsed
  * so far MINUS any provisioning charged in the meantime, and may be called more

package/claude-hooks/scan-invisible-chars.mjs

@@ -33,6 +33,7 @@ import {
   lazyImport,
   markerIsTrusted,
   probeSetupAlive,
+  setupRunning,
   PROJECT_DIR,
   readStdinJson,
 } from "./lib/hook-io.mjs";
@@ -52,7 +53,11 @@ import { formatReport } from "./lib/invisible-report.mjs";
 import { sweepStaleReveals } from "./lib/reveal.mjs";
 import { sweepStaleConfirms } from "./lib/secret-drop-guard.mjs";
 import { hookTrace, TraceEvent } from "./lib/trace.mjs";
-import { reportSlowHook, startHookTimer } from "./lib/hook-timing.mjs";
+import {
+  excludeConcurrentProvisioning,
+  reportSlowHook,
+  startHookTimer,
+} from "./lib/hook-timing.mjs";
 // Relative, not the `agent-sanitizer` specifier every other engine import uses:
 // this is the scan's SCOPE, which is hook policy, and package.json's exports map
 // deliberately does not publish it — routing it through the specifier would fail
@@ -404,7 +409,13 @@ export async function cliMain(opts = {}) {
   // into a bug report (see lib/hook-timing.mjs).
   const timer = startHookTimer();
   try {
-    await runScanCli(opts);
+    // Charged to provisioning when the session's setup is installing THROUGHOUT
+    // this run: that install saturates the machine, and a scan that merely
+    // waited it out has no per-call cost to report (see hook-timing.mjs).
+    await excludeConcurrentProvisioning(
+      () => runScanCli(opts),
+      () => setupRunning(hookgateMarkerPath()),
+    );
   } finally {
     reportSlowHook(
       HOOK_NAME,

package/claude-hooks/scan-loaded-instructions.mjs

@@ -21,12 +21,14 @@ import { readFileSync } from "node:fs";
 import {
   emitHookResponse,
   EmptyStdinError,
+  hookgateMarkerPath,
   HookEvent,
   isMain,
   lazyImport,
   PROJECT_DIR,
   readStdinJson,
   safeErrMessage,
+  setupRunning,
 } from "./lib/hook-io.mjs";
 import {
   registerFaultPolicy,
@@ -38,7 +40,11 @@ import {
   recordInstructionsLoaded,
 } from "./lib/invisible-alert.mjs";
 import { hookTrace, TraceEvent } from "./lib/trace.mjs";
-import { reportSlowHook, startHookTimer } from "./lib/hook-timing.mjs";
+import {
+  excludeConcurrentProvisioning,
+  reportSlowHook,
+  startHookTimer,
+} from "./lib/hook-timing.mjs";
 import { formatReport } from "./lib/invisible-report.mjs";
 import {
   contextScopeContradiction,
@@ -259,6 +265,41 @@ export { HOOK_NAME };
 export async function cliMain({ trace: sink } = {}) {
   const timer = startHookTimer();
   const emitTrace = hookTrace(sink);
+  try {
+    // Charged to provisioning when the session's setup is installing THROUGHOUT
+    // this run: that install saturates the machine, and a scan that merely
+    // waited it out has no per-call cost to report (see hook-timing.mjs).
+    await excludeConcurrentProvisioning(
+      () => runLoadedScanCli(emitTrace),
+      () => setupRunning(hookgateMarkerPath()),
+    );
+  } finally {
+    reportSlowHook(
+      HOOK_NAME,
+      timer.wallMs(),
+      HookEvent.INSTRUCTIONS_LOADED,
+      emitHookResponse,
+      undefined,
+      // All four windows, including the two this scan normally leaves empty: a
+      // measured 0 rules a window OUT, where an omitted one leaves the notice
+      // naming candidates it cannot separate.
+      {
+        cpuMs: timer.cpuMs(),
+        redactorMs: timer.redactorMs(),
+        hostMs: timer.hostMs(),
+      },
+    );
+  }
+}
+
+/**
+ * The scan itself. Split from {@link cliMain} so the timing wrapper above has a
+ * single call to bracket — every early return here is an exit that wrapper must
+ * still measure.
+ * @param {import("./lib/trace.mjs").TraceFn} emitTrace
+ * @returns {Promise<void>}
+ */
+async function runLoadedScanCli(emitTrace) {
   /** @type {string | undefined} */
   let sessionId;
   try {
@@ -314,22 +355,6 @@ export async function cliMain({ trace: sink } = {}) {
     // rather than in no store at all.
     if (outcome.armAlert)
       appendAlert(/** @type {string} */ (outcome.stderr), sessionId);
-  } finally {
-    reportSlowHook(
-      HOOK_NAME,
-      timer.wallMs(),
-      HookEvent.INSTRUCTIONS_LOADED,
-      emitHookResponse,
-      undefined,
-      // All four windows, including the two this scan normally leaves empty: a
-      // measured 0 rules a window OUT, where an omitted one leaves the notice
-      // naming candidates it cannot separate.
-      {
-        cpuMs: timer.cpuMs(),
-        redactorMs: timer.redactorMs(),
-        hostMs: timer.hostMs(),
-      },
-    );
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.58.1",
+  "version": "2.58.3",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {

package/types/claude-hooks/lib/hook-io.d.mts

@@ -329,6 +329,27 @@ export function configureHookgateMarker(path: string | null): void;
  * @returns {string | null}
  */
 export function hookgateMarkerPath(projectDir?: string | undefined, runtimeDir?: string | undefined): string | null;
+/**
+ * Is a setup process DEMONSTRABLY running right now?
+ *
+ * The strict twin of {@link probeSetupAlive}, and the two differ only in which
+ * way they fall when the evidence runs out. That one decides whether to keep
+ * WAITING for a dependency, so every ambiguity — an unreadable marker, an
+ * unparseable pid, no project dir — reads as alive: waiting a moment longer is
+ * cheap and giving up early fails a hook closed. This one decides whether to
+ * stop charging a caller for time it spent, so the same ambiguity must read as
+ * NOT running: an absence of evidence that the machine was busy is not evidence
+ * that it was, and discounting a wait on that basis would hide the very
+ * slowdowns the caller is measuring for.
+ *
+ * Positive evidence is one of two things: the setup lock is held (the kernel
+ * drops an flock the instant its holder dies, so held means running), or the
+ * marker's pid names a live process. A marker this uid does not own is not
+ * evidence about our setup at all.
+ * @param {string | null} markerPath
+ * @returns {boolean}
+ */
+export function setupRunning(markerPath: string | null): boolean;
 /**
  * Is the setup process that wrote `markerPath` still alive?
  *

package/types/claude-hooks/lib/hook-timing.d.mts

@@ -104,6 +104,35 @@ export function chargeHostExtensionSync<T>(work: () => T, now?: () => number, cp
  * @returns {Promise<T>}
  */
 export function excludeProvisioning<T>(work: () => Promise<T>, now?: () => number, cpuNow?: () => number): Promise<T>;
+/**
+ * Run `work`, charging its duration to provisioning when a SESSION-LEVEL
+ * provisioning step was in flight for the whole of it — a neighbouring hook's
+ * dependency install, which saturates the machine this hook is only sharing.
+ * {@link excludeProvisioning} discounts the wait this process performs itself;
+ * this discounts the one it merely runs alongside.
+ *
+ * `setupAlive` is asked twice, before and after, and only a step alive at BOTH
+ * ends is charged. A step that started or finished mid-run leaves a window
+ * nothing here can apportion, and splitting it by guess would discount the
+ * hook's own work — so that run is measured in full and reports honestly.
+ *
+ * Wall-clock only, where {@link excludeProvisioning} charges CPU too: the
+ * install runs in ANOTHER process, so none of it lands in this one's CPU figure,
+ * and charging CPU here would discount the hook's own computing.
+ *
+ * Bounded by {@link CONCURRENT_PROVISION_CEILING_MS}, which is what stops the
+ * discount from hiding a wedged run: a window past the ceiling is charged to
+ * nobody but the hook, however busy the machine was, because at that magnitude
+ * the hook is the thing that is broken.
+ * @template T
+ * @param {() => Promise<T>} work
+ * @param {() => boolean} setupAlive  whether a session-level provisioning step
+ *   is running right now; the caller owns the evidence (a cold-start marker and
+ *   its PID), since this module reads no files of its own
+ * @param {() => number} [now]  injectable clock, for tests
+ * @returns {Promise<T>}
+ */
+export function excludeConcurrentProvisioning<T>(work: () => Promise<T>, setupAlive: () => boolean, now?: () => number): Promise<T>;
 /**
  * Start measuring; each reader on the returned object reports what has elapsed
  * so far MINUS any provisioning charged in the meantime, and may be called more
@@ -262,6 +291,18 @@ export const SLOW_HOOK_THRESHOLD_MS: 1000;
  * re-provisioning every session), which is worth saying out loud.
  */
 export const SLOW_PROVISION_THRESHOLD_MS: 60000;
+/**
+ * The longest window {@link excludeConcurrentProvisioning} will discount.
+ *
+ * Ten times the hook budget, because the discount's whole premise is that the
+ * hook's work is small and the machine is busy: an instruction scan is tens of
+ * milliseconds of work, so a wait this far past its budget is not a busy box any
+ * more, whatever else is installing. Past the ceiling the run is measured in
+ * full and reports — the founding case of this module is a SessionStart scan
+ * that blocked startup for 30 SECONDS, and a cold-start install running
+ * alongside it must not be what buys that silence.
+ */
+export const CONCURRENT_PROVISION_CEILING_MS: number;
 /**
  * Debugging context a caller may already have in hand when a hook overruns its
  * budget, so the notice names WHAT was slow instead of just HOW slow — the gap