agent-sanitizer 2.44.0 → 2.45.0

package/README.md

@@ -374,7 +374,10 @@ second line reading `flock` (`SETUP_LOCK_DECLARATION`), and the hooks then judge
 liveness by the lock rather than the pid: the kernel releases an `flock` the
 instant its holder dies, so a killed setup is detected immediately instead of
 being read as alive for as long as a recycled pid keeps answering. A marker that
-declares nothing is judged by its pid, as before.
+declares nothing is judged by its pid. A writer must hold the lock BEFORE the
+declaring marker becomes visible: a marker that says `flock` while its writer
+has not yet locked reads as a free lock, so every waiter abandons an install
+that is still running.
 
 **A host's own remedy can replace the packaged one in every failure reason**
 (the fail-closed verdicts and the fail-open warning alike). Deep call sites (`lib/control-plane`'s missing-package throw) take no

package/claude-hooks/lib/invisible-alert.mjs

@@ -66,7 +66,7 @@ export function sessionPrefix(sessionId) {
   // The id becomes a path component, so anything outside this class — a `/` in
   // a hostile session id above all — is folded away rather than escaping
   // $TMPDIR. A host that exports no session id falls back to one shared name,
-  // where a marker can outlive its session.
+  // whose findings and ack are bounded by FALLBACK_TTL_MS instead.
   const key =
     (sessionId ?? "").replace(/[^A-Za-z0-9._-]/gu, "_") || "no-session";
   return `${ALERT_BASE}.s-${key}`;
@@ -128,6 +128,62 @@ export function instructionsLoadedSeen(sessionId) {
 /** How long a past session's artifacts are kept before a later session sweeps. */
 const MARKER_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 
+/**
+ * How long a finding or an ack recorded WITHOUT a session identity stays live.
+ *
+ * Session-keying is what stops one session inheriting another's answer, and the
+ * shared `no-session` prefix is the one place it is unavailable: a hook that
+ * faults before it can parse its payload has no id to key by, and nothing can
+ * clear its artifact when that session ends. Wall-clock is the only lifetime
+ * left. It is applied at READ time — not by a SessionStart clear, which would
+ * erase a fault recorded moments earlier by an InstructionsLoaded event that had
+ * only this prefix to reach — and again by the sweep, so the bytes go too.
+ *
+ * Wide enough to cover a launch-time fault reaching the session's first tool
+ * call, narrow enough that the next session does not re-arm the gate for a fault
+ * it cannot act on. Past it an INHERITED fallback finding is neither surfaced
+ * nor remembered, which is what makes REMEDY's "start a new session and the gate
+ * clears" true for these findings too.
+ *
+ * A host that exports no session id keeps its findings, because there the
+ * fallback is the session's OWN store: expiring it would stop telling a
+ * still-running session that its instruction files are unvetted, a silent loss
+ * of the signal this module exists to carry. The ack expires there regardless,
+ * so a suppression that outlives its session fails toward asking again — which
+ * is recoverable, where a silence is not.
+ */
+const FALLBACK_TTL_MS = 30 * 60 * 1000;
+
+/**
+ * Whether `path` was written inside the last `ttlMs`.
+ *
+ * A path a parallel session removed between the caller's markerIsTrusted and
+ * this `lstat` reads as expired, which is what every caller wants of a file that
+ * is no longer there: the sweep's unlink becomes a no-op, the gate's reader skips
+ * it, and an ack that vanished stops suppressing the ask. Propagating instead
+ * would abort recordInstructionsLoaded on a benign $TMPDIR race and render the
+ * false "instruction file was NOT scanned" fault.
+ *
+ * `lstat`, so a planted symlink is judged on itself.
+ * @param {string} path
+ * @param {number} ttlMs
+ * @returns {boolean}
+ */
+function withinTtl(path, ttlMs) {
+  try {
+    return lstatSync(path).mtimeMs >= Date.now() - ttlMs;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether `path` was written inside {@link FALLBACK_TTL_MS}.
+ * @param {string} path
+ * @returns {boolean}
+ */
+const withinFallbackTtl = (path) => withinTtl(path, FALLBACK_TTL_MS);
+
 /**
  * Whether `path` is a real directory this uid owns — the directory counterpart
  * of markerIsTrusted. `lstat`, so a symlink planted at the predictable alert-dir
@@ -185,6 +241,45 @@ export function sweepStaleSessions(sessionId) {
       if (code !== "ENOENT" && code !== "EPERM" && code !== "EACCES") throw err;
     }
   }
+  sweepStaleFallback(sessionId);
+}
+
+/**
+ * Remove the shared-prefix artifacts the reader has stopped honouring, so they
+ * stop occupying $TMPDIR too. The loop above cannot: it skips the current
+ * session's prefix, which on a host with no session id IS this one.
+ *
+ * Mirrors what {@link invisibleCharAlert} and {@link alertAcknowledged} read.
+ * The ack always expires; the findings only when this session has its own store
+ * and so merely INHERITED these.
+ *
+ * The two InstructionsLoaded markers under the same prefix answer "did a scan
+ * run at all", so FALLBACK_TTL_MS must never reach them: expiring one mid-session
+ * would render the gap notice on a session that WAS scanned. They still go, at
+ * MARKER_TTL_MS — the same age the loop above ages a real session's prefix out
+ * at, and far past any session's life — because the loop skips this prefix and
+ * would otherwise leave a session-less host's markers in $TMPDIR forever, with
+ * the gap notice suppressed on every later session.
+ * @param {string} [sessionId]
+ * @returns {void}
+ */
+function sweepStaleFallback(sessionId) {
+  const dir = alertDir();
+  const inherited = alertDir(sessionId) !== dir && dirIsTrusted(dir);
+  const entries = inherited
+    ? readdirSync(dir).map((name) => join(dir, name))
+    : [];
+  // markerIsTrusted absorbs an absent or foreign entry, and having confirmed this
+  // uid owns the file there is nothing left that can refuse the unlink; `force`
+  // covers only a parallel session removing it first.
+  /** @param {string} path */
+  const drop = (path) => {
+    if (markerIsTrusted(path)) rmSync(path, { force: true });
+  };
+  for (const path of [alertAckFile(), ...entries])
+    if (!withinFallbackTtl(path)) drop(path);
+  for (const path of [instructionsLoadedFile(), instructionsLoadedNoticeFile()])
+    if (!withinTtl(path, MARKER_TTL_MS)) drop(path);
 }
 
 /**
@@ -271,13 +366,18 @@ export function recordInstructionsLoadedNotice(sessionId) {
  * faults BEFORE it can parse its payload has no session identity to key by: its
  * finding lands in the fallback, and a strictly session-keyed read would leave
  * the one report of an unscanned instruction file unreachable. The ack stays
- * strictly session-keyed, so the gate still asks exactly once per session.
+ * strictly session-keyed, so the gate still asks exactly once per session. A
+ * fallback finding is read only while it is inside FALLBACK_TTL_MS, which is
+ * what keeps it from re-arming the gate for a later session.
  * @param {string} [sessionId]
  * @returns {string | null}
  */
 export function invisibleCharAlert(sessionId) {
-  const dirs = [alertDir(sessionId)];
-  if (dirs[0] !== alertDir()) dirs.push(alertDir());
+  const own = alertDir(sessionId);
+  // The second entry, when there is one, is a store belonging to no session,
+  // so only age says whether it is still this session's business. Where the
+  // fallback IS `own` there is nothing inherited and nothing to expire.
+  const dirs = own === alertDir() ? [own] : [own, alertDir()];
   const parts = [];
   for (const dir of dirs) {
     if (!dirIsTrusted(dir)) continue;
@@ -286,6 +386,7 @@ export function invisibleCharAlert(sessionId) {
     for (const name of readdirSync(dir).sort()) {
       const path = join(dir, name);
       if (!markerIsTrusted(path)) continue;
+      if (dir !== own && !withinFallbackTtl(path)) continue;
       const text = readFileSync(path, "utf-8").trim();
       if (text !== "") parts.push(text);
     }
@@ -334,11 +435,19 @@ export function appendAlert(text, sessionId) {
  * predictable $TMPDIR path to permanently suppress the one-time blocking ask down
  * to the passive reminder, so trust the marker only when it is a regular file
  * this uid wrote (markerIsTrusted), mirroring how acknowledgeAlert writes it.
+ *
+ * On a host that exports no session id every session shares the fallback prefix,
+ * so the ack has no session to end with and would suppress the one-time blocking
+ * ask down to the passive reminder for the life of the machine. There it expires
+ * with {@link FALLBACK_TTL_MS} like the findings it answers for.
  * @param {string} [sessionId]
  * @returns {boolean}
  */
 export function alertAcknowledged(sessionId) {
-  return markerIsTrusted(alertAckFile(sessionId));
+  const path = alertAckFile(sessionId);
+  if (!markerIsTrusted(path)) return false;
+  if (sessionPrefix(sessionId) !== sessionPrefix()) return true;
+  return withinFallbackTtl(path);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.44.0",
+  "version": "2.45.0",
   "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/invisible-alert.d.mts

@@ -123,7 +123,9 @@ export function recordInstructionsLoadedNotice(sessionId?: string): void;
  * faults BEFORE it can parse its payload has no session identity to key by: its
  * finding lands in the fallback, and a strictly session-keyed read would leave
  * the one report of an unscanned instruction file unreachable. The ack stays
- * strictly session-keyed, so the gate still asks exactly once per session.
+ * strictly session-keyed, so the gate still asks exactly once per session. A
+ * fallback finding is read only while it is inside FALLBACK_TTL_MS, which is
+ * what keeps it from re-arming the gate for a later session.
  * @param {string} [sessionId]
  * @returns {string | null}
  */
@@ -148,6 +150,11 @@ export function appendAlert(text: string, sessionId?: string): boolean;
  * predictable $TMPDIR path to permanently suppress the one-time blocking ask down
  * to the passive reminder, so trust the marker only when it is a regular file
  * this uid wrote (markerIsTrusted), mirroring how acknowledgeAlert writes it.
+ *
+ * On a host that exports no session id every session shares the fallback prefix,
+ * so the ack has no session to end with and would suppress the one-time blocking
+ * ask down to the passive reminder for the life of the machine. There it expires
+ * with {@link FALLBACK_TTL_MS} like the findings it answers for.
  * @param {string} [sessionId]
  * @returns {boolean}
  */