agent-sanitizer 2.43.12 → 2.44.1

package/README.md

@@ -368,6 +368,17 @@ hook module, and every consumer waits on that path instead. `lib/control-plane`
 resolves the marker at module scope, so a call that lands after that import
 warns on stderr — it cannot steer the wait that already started.
 
+The marker's first line is the setup process's pid. A writer that also holds an
+exclusive `flock` on the marker file for the whole install says so by adding a
+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. 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
 remedy argument, so by default they can only say `pnpm install`. A host whose

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

@@ -8,6 +8,7 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { userInfo } from "node:os";
 import { createHash } from "node:crypto";
 import { pathToFileURL } from "node:url";
@@ -692,6 +693,19 @@ export function emitHookResponse(hookEventName, fields) {
   );
 }
 
+/**
+ * The project the hooks are guarding. Every per-project $TMPDIR store is keyed to
+ * it, so it lives here — beside the other shared identity these hooks agree on —
+ * rather than in whichever store happened to need it first.
+ */
+export const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+/** Short project digest keying this project's $TMPDIR store names. */
+export const PROJECT_HASH = createHash("sha256")
+  .update(PROJECT_DIR)
+  .digest("hex")
+  .slice(0, 8);
+
 /** The marker filename stem; the project directory is appended to it. */
 const HOOKGATE_MARKER_STEM = "agent-sanitizer-hookgate-inflight-";
 
@@ -765,24 +779,70 @@ export function hookgateMarkerPath(
 }
 
 /**
- * Is the setup process that wrote `markerPath` still alive? `process.kill(pid, 0)`
- * probes liveness without signalling: it throws ESRCH once the process is gone (a
- * killed setup → stale marker, so stop waiting) and EPERM when it exists but isn't
- * ours (still alive). An unreadable / not-yet-written marker is treated as alive —
- * favouring a brief wait over a premature give-up during setup's write race. A null
- * markerPath (no project dir → no setup to wait on) reads as alive so the caller's
- * own grace/ceiling bound governs.
+ * The line a cold-start marker carries on its own to declare that its writer holds
+ * an exclusive `flock` on the marker file for the whole install.
+ *
+ * This is the marker's PROTOCOL, and the reason it is declared in the data rather
+ * than assumed: a reader cannot tell "the writer released the lock because it died"
+ * from "the writer never took one" by looking at a free lock, so only a marker that
+ * says it locks may be judged by the lock.
+ */
+export const SETUP_LOCK_DECLARATION = "flock";
+
+/**
+ * Whether an exclusive lock is currently held on `markerPath`, or null when the
+ * question cannot be answered here (no `flock(1)` — it is util-linux, absent from a
+ * stock macOS — or an exit status neither "acquired" nor "busy").
+ * @param {string} markerPath
+ * @returns {boolean | null}
+ */
+function markerLockHeld(markerPath) {
+  const probe = spawnSync(
+    "flock",
+    ["--nonblock", "--exclusive", markerPath, "true"],
+    { stdio: "ignore" },
+  );
+  if (probe.error) return null;
+  if (probe.status === 0) return false; // acquired: nobody holds it
+  if (probe.status === 1) return true; // busy: the writer still holds it
+  return null;
+}
+
+/**
+ * Is the setup process that wrote `markerPath` still alive?
+ *
+ * A marker declaring {@link SETUP_LOCK_DECLARATION} is judged by the LOCK, and that
+ * answer has no aliasing: the kernel drops an flock the instant its holder dies, so
+ * held means alive and free means dead, with no third state and nothing to reuse. A
+ * marker that declares nothing carries only a pid, and `process.kill(pid, 0)` is all
+ * there is — it throws ESRCH once the process is gone (a killed setup → stale
+ * marker, so stop waiting) and EPERM when it exists but is not ours (still alive).
+ * That reading is the one this replaces where it can: a recycled pid reads as a live
+ * setup for as long as the caller's ceiling allows.
+ *
+ * An unreadable / not-yet-written marker is treated as alive — favouring a brief
+ * wait over a premature give-up during setup's write race. A null markerPath (no
+ * project dir → no setup to wait on) reads as alive so the caller's own
+ * grace/ceiling bound governs.
  * @param {string | null} markerPath
  * @returns {boolean}
  */
 export function probeSetupAlive(markerPath) {
   if (markerPath === null) return true;
-  let pid;
+  let raw;
   try {
-    pid = parseInt(readFileSync(markerPath, "utf8"), 10);
+    raw = readFileSync(markerPath, "utf8");
   } catch {
     return true;
   }
+  const lines = raw.split("\n").map((line) => line.trim());
+  if (lines.includes(SETUP_LOCK_DECLARATION)) {
+    const held = markerLockHeld(markerPath);
+    // null only: a host without flock(1) still gets the pid reading below rather
+    // than an answer this probe cannot support.
+    if (held !== null) return held;
+  }
+  const pid = parseInt(lines[0], 10);
   if (!Number.isInteger(pid) || pid <= 0) return true;
   try {
     process.kill(pid, 0);

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

@@ -10,19 +10,26 @@
  * Both hooks reach the state through this module so the paths and the trust rule
  * have one definition.
  */
-import { lstatSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
-import { createHash } from "node:crypto";
+import {
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { randomBytes } from "node:crypto";
 import { basename, join } from "node:path";
-import { tmpdir } from "node:os";
+import { tmpdir, userInfo } from "node:os";
 import {
   lazyImport,
   markerIsTrusted,
+  PROJECT_HASH,
   scrubUntrustedText,
   writeFileNoFollow,
   writeSentinelFile,
 } from "./hook-io.mjs";
 
-// Layer-1 scrubber for the untrusted ALERT_FILE contents the gate splices into a
+// Layer-1 scrubber for the untrusted alert-store contents the gate splices into a
 // permissionDecisionReason. Bound via lazyImport (see its doc for the fail-OPEN
 // hazard of a bare static npm import): a load failure leaves applyLayer1 undefined,
 // so scrubUntrustedText throws into the caller's fail-closed catch (→ ask) rather
@@ -31,50 +38,69 @@ const { applyLayer1 } = /** @type {typeof import("agent-sanitizer")} */ (
   await lazyImport("agent-sanitizer")
 );
 
-/** The project the hooks are guarding; the alert paths are keyed to it. */
-export const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-
-/** Short project digest keying this project's $TMPDIR marker names. */
-export const PROJECT_HASH = createHash("sha256")
-  .update(PROJECT_DIR)
-  .digest("hex")
-  .slice(0, 8);
-
-/** Findings the SessionStart scanner could not clean, for the PreToolUse gate. */
-export const ALERT_FILE = join(
+/**
+ * The path prefix every alert artifact of this PROJECT shares. Never a file
+ * itself — only {@link sessionPrefix} and the sweep read it — so that one
+ * `startsWith` covers every artifact the sweep must age out.
+ */
+export const ALERT_BASE = join(
   tmpdir(),
   `.claude-invisible-char-alert-${PROJECT_HASH}`,
 );
 
-// Companion marker the PreToolUse gate writes once it has surfaced the alert
-// this session, so the gate asks ONCE then degrades to a passive reminder
-// instead of prompting on every tool call. Cleared at SessionStart alongside
-// ALERT_FILE so each fresh session re-asks once.
-export const ALERT_ACK_FILE = `${ALERT_FILE}.acked`;
-
 /**
- * Marker the InstructionsLoaded scanner writes on every fire, so another hook
- * can tell whether that event is being scanned at all this session.
+ * The path prefix every alert artifact of ONE session under this project shares.
  *
- * Keyed by the SESSION, and never cleared at SessionStart like the alert pair
- * above (a later session sweeps it once it is older than the TTL):
- * nothing pins the order of SessionStart against the InstructionsLoaded events
- * Claude Code fires for the files it loads at launch, so a clear could erase a
- * marker written moments earlier and produce the notice on a session that IS
- * covered. Session-keyed, the question each session asks is answered by that
- * session's own file and no ordering matters. A host that exports no session id
- * falls back to one shared name — where the marker can outlive its session, and
- * a later session on a host that stopped emitting the event stays quiet.
- * @param {string} [sessionId]
+ * Session-keying is what makes the gate's one-time ask correct by construction.
+ * The store and its ack used to be keyed by PROJECT alone and reset by a
+ * destructive clear at SessionStart, which left two ways for a session to
+ * inherit the previous one's answer: an early-exiting scanner arm (a dep-load
+ * failure) returns before the clear, and nothing pins SessionStart against the
+ * InstructionsLoaded events fired for the files loaded at launch. A session that
+ * cannot see another session's files needs neither the clear nor the ordering —
+ * past sessions' artifacts simply age out through {@link sweepStaleSessions}.
+ * @param {string} [sessionId]  the harness's session identity
  * @returns {string}
  */
-export function instructionsLoadedFile(sessionId) {
+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.
+  // $TMPDIR. A host that exports no session id falls back to one shared name,
+  // whose findings and ack are bounded by FALLBACK_TTL_MS instead.
   const key =
     (sessionId ?? "").replace(/[^A-Za-z0-9._-]/gu, "_") || "no-session";
-  return `${ALERT_FILE}.instructions-loaded.${key}`;
+  return `${ALERT_BASE}.s-${key}`;
+}
+
+/**
+ * The directory holding this session's alert findings, one file per finding.
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function alertDir(sessionId) {
+  return `${sessionPrefix(sessionId)}.alerts`;
+}
+
+/**
+ * Companion marker the PreToolUse gate writes once it has surfaced the alert
+ * this session, so the gate asks ONCE then degrades to a passive reminder
+ * instead of prompting on every tool call. Session-keyed like the findings it
+ * answers for, so a fresh session cannot read an older session's answer.
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function alertAckFile(sessionId) {
+  return `${sessionPrefix(sessionId)}.acked`;
+}
+
+/**
+ * Marker the InstructionsLoaded scanner writes on every fire, so another hook
+ * can tell whether that event is being scanned at all this session.
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function instructionsLoadedFile(sessionId) {
+  return `${sessionPrefix(sessionId)}.instructions-loaded`;
 }
 
 /**
@@ -99,28 +125,161 @@ export function instructionsLoadedSeen(sessionId) {
   return markerIsTrusted(instructionsLoadedFile(sessionId));
 }
 
-/** How long a past session's marker is kept before the next session sweeps it. */
+/** How long a past session's artifacts are kept before a later session sweeps. */
 const MARKER_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 
 /**
- * Delete this project's session markers older than the TTL. Only PAST sessions'
- * files are candidates — the current session's was just written, so the sweep
- * cannot answer its own question wrong.
- * @param {string} keep  the marker path this session owns
+ * 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
+ * path is judged on ITSELF: followed, it would let a co-tenant aim the gate's
+ * reader at a directory of unrelated files this uid owns and splice their bytes
+ * into a permission prompt.
+ * @param {string} path
+ * @returns {boolean}
+ */
+function dirIsTrusted(path) {
+  let st;
+  try {
+    st = lstatSync(path);
+  } catch {
+    return false;
+  }
+  return st.isDirectory() && st.uid === userInfo().uid;
+}
+
+/**
+ * Delete this project's artifacts from OTHER sessions once they are older than
+ * the TTL. The current session's own prefix is skipped, so the sweep can never
+ * answer its own question wrong; every other session's files are past history
+ * that nothing reads.
+ *
+ * This replaces the destructive SessionStart clear: with the store session-keyed
+ * there is nothing to reset, only old state to age out.
+ * @param {string} [sessionId]  the session whose artifacts must be kept
  * @returns {void}
  */
-function sweepStaleMarkers(keep) {
+export function sweepStaleSessions(sessionId) {
   const dir = tmpdir();
-  const prefix = `${basename(ALERT_FILE)}.instructions-loaded.`;
+  const prefix = `${basename(ALERT_BASE)}.s-`;
+  const keep = basename(sessionPrefix(sessionId));
   const cutoff = Date.now() - MARKER_TTL_MS;
   for (const name of readdirSync(dir)) {
     if (!name.startsWith(prefix)) continue;
+    // Whole-segment match on the keep prefix, not a bare startsWith: session key
+    // "abc" must not claim (and so preserve) session key "abc2"'s artifacts.
+    if (name === keep || name.startsWith(`${keep}.`)) continue;
     const path = join(dir, name);
-    if (path === keep || path === `${keep}.noticed`) continue;
-    // lstat, not stat: a squatted symlink at a predictable $TMPDIR path must be
-    // judged on ITSELF, not on whatever it points at. unlink removes the link.
-    if (lstatSync(path).mtimeMs < cutoff) unlinkSync(path);
+    try {
+      // lstat, not stat: a squatted symlink at a predictable $TMPDIR path must
+      // be judged on ITSELF, not on whatever it points at.
+      if (lstatSync(path).mtimeMs >= cutoff) continue;
+      rmSync(path, { recursive: true, force: true });
+    } catch (err) {
+      // ENOENT: a parallel session swept this entry between readdir and lstat.
+      // EPERM/EACCES: a co-tenant's entry sharing the prefix, which is not ours
+      // to remove. Both are benign races on a shared $TMPDIR, and a throw here
+      // would abort recordInstructionsLoaded and render the "instruction file
+      // was NOT scanned" fault on a session that WAS scanned. Anything else is
+      // a bug in this sweep and propagates.
+      const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+      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);
 }
 
 /**
@@ -128,8 +287,8 @@ function sweepStaleMarkers(keep) {
  * write (see writeSentinelFile) at a predictable $TMPDIR path.
  *
  * The event fires once per instruction file loaded, so the already-recorded case
- * returns without a write — and the stale-marker sweep rides the FIRST fire of a
- * session, where one readdir is paid once rather than per loaded file.
+ * returns without a write — and the stale-session sweep rides the FIRST fire of
+ * a session, where one readdir is paid once rather than per loaded file.
  * @param {string} [sessionId]
  * @returns {void}
  */
@@ -137,14 +296,18 @@ export function recordInstructionsLoaded(sessionId) {
   const marker = instructionsLoadedFile(sessionId);
   if (markerIsTrusted(marker)) return;
   writeSentinelFile(marker);
-  sweepStaleMarkers(marker);
+  sweepStaleSessions(sessionId);
 }
 
 /**
  * The one-time context line for a session where no InstructionsLoaded scan ran,
  * or null when the scan has been seen or the notice was already surfaced this
- * session. Records the notice as it hands it out, so it rides on ONE tool call
- * rather than every one — the per-call repeat is what trains a reader to skip it.
+ * session.
+ *
+ * PURE: it does not record that the notice was handed out. The caller records
+ * separately, once the notice has actually landed in a response — a deny
+ * assembled after this call discards the notice, and a marker written here would
+ * have burned the session's one chance to report the loss.
  *
  * The loss it names is real and otherwise invisible: SessionStart scans the
  * instruction files that load at launch, and everything a subdirectory loads
@@ -162,9 +325,7 @@ export function recordInstructionsLoaded(sessionId) {
  */
 export function instructionsLoadedGapNotice(sessionId) {
   if (instructionsLoadedSeen(sessionId)) return null;
-  const noticeFile = instructionsLoadedNoticeFile(sessionId);
-  if (markerIsTrusted(noticeFile)) return null;
-  writeSentinelFile(noticeFile);
+  if (markerIsTrusted(instructionsLoadedNoticeFile(sessionId))) return null;
   return (
     "agent-sanitizer: no InstructionsLoaded scan has run this session, so " +
     "instruction files loaded from SUBDIRECTORIES (a nested CLAUDE.md, a " +
@@ -178,65 +339,128 @@ export function instructionsLoadedGapNotice(sessionId) {
   );
 }
 
+/**
+ * Record that the gap notice above was surfaced, so it rides on ONE tool call
+ * rather than every one — the per-call repeat is what trains a reader to skip it.
+ * Called only once the notice is in a response that is actually being returned.
+ * @param {string} [sessionId]
+ * @returns {void}
+ */
+export function recordInstructionsLoadedNotice(sessionId) {
+  writeSentinelFile(instructionsLoadedNoticeFile(sessionId));
+}
+
 /**
  * The alert findings if invisible-char injection was detected in instruction
- * files and couldn't be auto-cleaned, else null. ALERT_FILE lives at a predictable,
- * world-visible $TMPDIR path, so its contents are attacker-writable (a co-tenant can
- * plant a file/symlink there): trust it only when markerIsTrusted confirms a regular
- * file THIS uid owns (a squatted symlink/foreign file reads as no alert), then scrub
- * the bytes through Layer-1 before any caller splices them into a reason — the report
- * would otherwise carry ANSI/invisible spoofing into the model's context.
+ * files and couldn't be auto-cleaned, else null.
+ *
+ * The store is a DIRECTORY of one file per finding, all at predictable,
+ * world-visible $TMPDIR paths, so both the directory and every entry in it are
+ * attacker-plantable: trust the directory only when it is a real directory this
+ * uid owns (a symlink would let a co-tenant aim this reader at unrelated files),
+ * each entry only when markerIsTrusted confirms a regular file this uid owns,
+ * then scrub the bytes through Layer-1 before any caller splices them into a
+ * reason — the report would otherwise carry ANSI/invisible spoofing into the
+ * model's context.
+ * This session's store AND the shared `no-session` fallback, because a hook that
+ * 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. 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() {
-  if (!markerIsTrusted(ALERT_FILE)) return null;
-  const raw = readFileSync(ALERT_FILE, "utf-8").trim();
-  return scrubUntrustedText(raw, applyLayer1);
+export function invisibleCharAlert(sessionId) {
+  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;
+    // Sorted so a multi-finding report reads the same on every call; the names
+    // are random, so the order carries no meaning beyond being stable.
+    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);
+    }
+  }
+  if (parts.length === 0) return null;
+  return scrubUntrustedText(parts.join("\n"), applyLayer1);
 }
 
 /**
- * Add `text` to the alert the PreToolUse gate surfaces, keeping whatever is
- * already there.
+ * Add `text` to the alert the PreToolUse gate surfaces this session, keeping
+ * whatever is already there.
  *
- * Appending, where the SessionStart scanner TRUNCATES: that scan runs once and
- * owns the session's reset, while an instruction file loaded mid-session is one
- * more finding on top of whatever the launch scan left — a truncating write here
- * would silently drop the earlier report. Symlink-refusing (writeFileNoFollow)
- * and ownership-checked on read, because ALERT_FILE sits at a predictable,
- * world-visible $TMPDIR path; a foreign or squatted file reads as empty and is
- * replaced rather than appended to.
+ * One O_EXCL-created, randomly-named file per finding. The store used to be a
+ * single file appended through a read-modify-write, so two hooks recording a
+ * finding at once silently dropped one of them; a fresh file per finding has no
+ * shared cell to lose. Symlink-refusing (writeFileNoFollow) because the store
+ * sits at a predictable, world-visible $TMPDIR path.
  * @param {string} text
- * @returns {void}
+ * @param {string} [sessionId]
+ * @returns {boolean} whether the finding was recorded
  */
-export function appendAlert(text) {
-  const existing = markerIsTrusted(ALERT_FILE)
-    ? readFileSync(ALERT_FILE, "utf-8")
-    : "";
-  writeFileNoFollow(ALERT_FILE, existing + text + "\n");
+export function appendAlert(text, sessionId) {
+  const dir = alertDir(sessionId);
+  const path = join(dir, randomBytes(8).toString("hex"));
+  // Caught, not propagated: one caller is the fault handler that reports a hook
+  // crash, and a throw there would replace the report with a second crash. The
+  // loss is announced on stderr instead — never swallowed.
+  let usable;
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    usable = dirIsTrusted(dir);
+  } catch {
+    usable = false;
+  }
+  if (usable && writeFileNoFollow(path, text + "\n")) return true;
+  process.stderr.write(
+    "agent-sanitizer: could not record an instruction-file finding under " +
+      `${dir}; the PreToolUse gate will NOT surface it this session.\n`,
+  );
+  return false;
 }
 
 /**
  * True once the gate has surfaced its blocking ask this session. Validates
- * ownership (not mere existence): a co-tenant could pre-create ALERT_ACK_FILE at its
- * 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.
+ * ownership (not mere existence): a co-tenant could pre-create the ack at its
+ * 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() {
-  return markerIsTrusted(ALERT_ACK_FILE);
+export function alertAcknowledged(sessionId) {
+  const path = alertAckFile(sessionId);
+  if (!markerIsTrusted(path)) return false;
+  if (sessionPrefix(sessionId) !== sessionPrefix()) return true;
+  return withinFallbackTtl(path);
 }
 
 /**
  * Record that the gate has surfaced its blocking ask, so later tool calls get a
- * passive reminder instead of an ask on every call. Cleared at SessionStart by
- * the scanner so each fresh session re-asks once.
+ * passive reminder instead of an ask on every call. Session-keyed, so the next
+ * session re-asks once without anything having to clear this.
+ * @param {string} [sessionId]
  * @returns {void}
  */
-export function acknowledgeAlert() {
-  // Symlink-safe presence write: ALERT_ACK_FILE sits at a predictable $TMPDIR
-  // path a co-tenant could pre-plant a symlink at (see writeSentinelFile).
-  writeSentinelFile(ALERT_ACK_FILE);
+export function acknowledgeAlert(sessionId) {
+  // Symlink-safe presence write: the ack sits at a predictable $TMPDIR path a
+  // co-tenant could pre-plant a symlink at (see writeSentinelFile).
+  writeSentinelFile(alertAckFile(sessionId));
 }
 
 // What the operator can actually DO — one bullet per kind of report the alert