agent-sanitizer 2.43.12 → 2.44.0

package/claude-hooks/lib/reveal.mjs

@@ -21,8 +21,11 @@
  */
 import { createHash } from "node:crypto";
 import {
+  existsSync,
   mkdirSync,
   lstatSync,
+  readdirSync,
+  unlinkSync,
   openSync,
   readFileSync,
   closeSync,
@@ -30,7 +33,7 @@ import {
 } from "node:fs";
 import { tmpdir, userInfo } from "node:os";
 import { join, resolve, sep } from "node:path";
-import { writeFileNoFollow } from "./hook-io.mjs";
+import { PROJECT_HASH, writeFileNoFollow } from "./hook-io.mjs";
 
 /**
  * Where reveal sidecars are stored. Exported so the PreToolUse placeholder
@@ -39,12 +42,56 @@ import { writeFileNoFollow } from "./hook-io.mjs";
  * @returns {string}
  */
 export function revealDir() {
+  // Project-keyed like every other $TMPDIR store: one unkeyed directory is shared
+  // by every project on the machine, so one project's sweep ages out another's
+  // spans and a rehydration that should have restored a placeholder fails closed
+  // instead. The 12-hex span KEY inside the directory is untouched — it is the
+  // published placeholder grammar, not a path detail.
   return (
     process.env._AGENT_SANITIZER_REVEAL_DIR ||
-    join(tmpdir(), "agent-sanitizer-layer2-reveal")
+    join(tmpdir(), `agent-sanitizer-layer2-reveal-${PROJECT_HASH}`)
   );
 }
 
+/**
+ * How long a reveal sidecar or span file is kept before a later session sweeps it.
+ * It must outlast the longest session that could still rehydrate a placeholder the
+ * model is holding, so it is generous rather than tight — these files are small,
+ * and the cost of sweeping one too early is a rehydration that fails closed.
+ */
+export const REVEAL_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Delete this project's reveal sidecars and spans older than {@link REVEAL_TTL_MS}.
+ *
+ * Nothing else removes them: every entry is content-addressed, so a store that is
+ * never swept grows for the life of the machine. Called from SessionStart, the one
+ * touchpoint that runs once per session rather than once per tool call.
+ * @returns {void}
+ */
+export function sweepStaleReveals() {
+  const dir = revealDir();
+  // existsSync first: revealDirIsSafe CREATES the directory, and a sweep run on
+  // every session start must not leave an empty store behind for a project that
+  // never spliced anything.
+  if (!existsSync(dir) || !revealDirIsSafe(dir)) return;
+  const cutoff = Date.now() - REVEAL_TTL_MS;
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    try {
+      // lstat, not stat: a squatted symlink at a precomputable path is judged on
+      // ITSELF, and unlink removes the link rather than its target.
+      if (lstatSync(path).mtimeMs < cutoff) unlinkSync(path);
+    } catch (err) {
+      // ENOENT: a parallel session swept this entry between readdir and lstat.
+      // EPERM/EACCES: a co-tenant's entry, which is not ours to remove. 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;
+    }
+  }
+}
+
 /**
  * Content-addressed path the pre-splice text of `content` is stored at.
  * @param {string} content

package/claude-hooks/lib/secret-drop-guard.mjs

@@ -28,12 +28,16 @@
  * pass costs only what today's behavior already allows.
  */
 import { createHash } from "node:crypto";
-import { lstatSync, unlinkSync } from "node:fs";
+import { lstatSync, readdirSync, unlinkSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { spawnSync } from "node:child_process";
-import { lazyImport, markerIsTrusted, writeSentinelFile } from "./hook-io.mjs";
-import { PROJECT_HASH } from "./invisible-alert.mjs";
+import {
+  lazyImport,
+  markerIsTrusted,
+  PROJECT_HASH,
+  writeSentinelFile,
+} from "./hook-io.mjs";
 
 // Layer-1 view primitives, bound via lazyImport (see its doc for the fail-OPEN
 // hazard of a bare static npm import): a load failure leaves these undefined,
@@ -75,6 +79,37 @@ export function confirmMarkerPath(fingerprint) {
   return join(tmpdir(), `.claude-secret-drop-${PROJECT_HASH}-${fingerprint}`);
 }
 
+/**
+ * Delete this project's confirm sentinels older than {@link CONFIRM_TTL_MS}.
+ *
+ * consumeConfirm removes the sentinel it honors, but an abandoned confirmation —
+ * denied, never retried — is removed by nothing, so the store grows for the life
+ * of the machine. Called from SessionStart, the one touchpoint that runs once per
+ * session rather than once per tool call. A sentinel past the TTL is already inert
+ * (consumeConfirm refuses it), so this reclaims space without changing a verdict.
+ * @returns {void}
+ */
+export function sweepStaleConfirms() {
+  const dir = tmpdir();
+  const prefix = `.claude-secret-drop-${PROJECT_HASH}-`;
+  const cutoff = Date.now() - CONFIRM_TTL_MS;
+  for (const name of readdirSync(dir)) {
+    if (!name.startsWith(prefix)) continue;
+    const path = join(dir, name);
+    try {
+      // lstat, not stat: a squatted symlink at a predictable path is judged on
+      // ITSELF, and unlink removes the link rather than its target.
+      if (lstatSync(path).mtimeMs < cutoff) unlinkSync(path);
+    } catch (err) {
+      // ENOENT: a parallel session swept this entry between readdir and lstat.
+      // EPERM/EACCES: a co-tenant's entry, which is not ours to remove. 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;
+    }
+  }
+}
+
 /**
  * Whether git tracks `filePath`. Exit 0 is tracked; exit 1 (untracked) and 128
  * (not a repository) both mean "no git recovery exists", which is what the
@@ -165,6 +200,12 @@ export async function secretDropGuard(toolInput, io, opts = {}) {
   if (dropped.length === 0) return null;
 
   const fingerprint = dropFingerprint(filePath, content, dropped);
+  // THE INVARIANT THIS ENFORCES: a confirmation approves exactly one drop —
+  // the identical (path, bytes, drop-set) — and only for CONFIRM_TTL_MS. The
+  // window must outlive a model retry (the confirmation IS the retry, so a
+  // shorter one would deny forever) and must not outlive the session's working
+  // context, or a marker left by an abandoned attempt becomes a standing
+  // auto-approval for a Write the user never saw.
   if (confirmSeen(fingerprint)) return null;
   recordConfirm(fingerprint);
   return { deny: dropDeny(dropped.length, filePath) };

package/claude-hooks/plugin-hooks.mjs

@@ -154,11 +154,14 @@ const HOOKS = {
   "scan-invisible-chars": {
     event: HookEvent.SESSION_START,
     run: async () => {
-      const { cliMain } =
+      const { cliMain, sessionIdFromStdin } =
         /** @type {typeof import("./scan-invisible-chars.mjs")} */ (
           await import("./scan-invisible-chars.mjs")
         );
-      await cliMain();
+      // The SessionStart payload carries the session identity the alert store is
+      // keyed by; without it every session shares one store and inherits the
+      // previous one's gate acknowledgement.
+      await cliMain({ sessionId: await sessionIdFromStdin() });
     },
   },
   "scan-loaded-instructions": {

package/claude-hooks/pretooluse-sanitize.mjs

@@ -55,6 +55,7 @@ import {
   gateReminderContext,
   alertAcknowledged,
   acknowledgeAlert,
+  recordInstructionsLoadedNotice,
   instructionsLoadedGapNotice,
 } from "./lib/invisible-alert.mjs";
 import {
@@ -448,10 +449,10 @@ export async function buildPreToolUseResponse(
   // Layer 1: gate. Persists across the session until the injected files are
   // cleaned. It asks ONCE (a hard checkpoint, recorded once emitted) then
   // degrades to a passive reminder, so it doesn't prompt on every tool call.
-  const findings = invisibleCharAlert();
+  const findings = invisibleCharAlert(input.session_id);
   let pendingGateAck = false;
   if (findings) {
-    if (alertAcknowledged()) {
+    if (alertAcknowledged(input.session_id)) {
       contexts.push(gateReminderContext());
     } else {
       asks.push(gateAskReason(findings));
@@ -461,11 +462,11 @@ export async function buildPreToolUseResponse(
 
   const { tool_name: tool, tool_input: toolInput } = input;
 
-  // Coverage notice, once per session: with no InstructionsLoaded scan running,
-  // every instruction file loaded from a subdirectory reaches the model
-  // unscanned, and the SessionStart scan — which covers only what loads at
-  // launch — cannot see the loss. Reported here because this is the first hook
-  // that runs after the loads would have happened.
+  // Reported here because this is the first hook that runs after the launch-time
+  // loads would have happened. assembleResponse — not this call — records that
+  // the notice was surfaced: a rehydrate deny below returns before the response
+  // is assembled, and recording here would burn the session's one report on a
+  // call that never carried it.
   const gapNotice = instructionsLoadedGapNotice(input.session_id);
   if (gapNotice !== null) contexts.push(gapNotice);
 
@@ -504,15 +505,25 @@ export async function buildPreToolUseResponse(
   return emitTraced(
     emitTrace,
     input.tool_name,
-    assembleResponse({ changed, current, asks, contexts, pendingGateAck }),
+    assembleResponse({
+      changed,
+      current,
+      asks,
+      contexts,
+      pendingGateAck,
+      pendingGapNotice: gapNotice !== null,
+      sessionId: input.session_id,
+    }),
   );
 }
 
 /**
  * Assemble the hookSpecificOutput fields from the per-layer results, or null
  * for a clean no-op (nothing asked, changed, or annotated). Records the gate
- * acknowledgement only when an ask actually lands in the response.
- * @param {{ changed: boolean, current: any, asks: string[], contexts: string[], pendingGateAck: boolean }} parts
+ * acknowledgement and the coverage-gap notice only when they actually land in
+ * the response.
+ * @param {{ changed: boolean, current: any, asks: string[], contexts: string[],
+ *   pendingGateAck: boolean, pendingGapNotice: boolean, sessionId?: string }} parts
  * @returns {Record<string, unknown> | null}
  */
 function assembleResponse({
@@ -521,6 +532,8 @@ function assembleResponse({
   asks,
   contexts,
   pendingGateAck,
+  pendingGapNotice,
+  sessionId,
 }) {
   if (asks.length === 0 && !changed && contexts.length === 0) return null;
 
@@ -541,7 +554,8 @@ function assembleResponse({
   if (contexts.length > 0) fields.additionalContext = contexts.join(" ");
   // Record the gate ack only now that the ask is actually in the response — a
   // rehydrate deny above returns first, so a preempted ask is not marked seen.
-  if (pendingGateAck) acknowledgeAlert();
+  if (pendingGateAck) acknowledgeAlert(sessionId);
+  if (pendingGapNotice) recordInstructionsLoadedNotice(sessionId);
   return fields;
 }
 

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

@@ -21,7 +21,7 @@
  * false positive the SSOT had already fixed, and its clean path was a bare
  * `writeFileSync` with none of cleanFile's symlink/UTF-8/TOCTOU guards.
  */
-import { existsSync, readFileSync, globSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, globSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import {
   awaitLazyDependency,
@@ -33,7 +33,8 @@ import {
   lazyImport,
   markerIsTrusted,
   probeSetupAlive,
-  writeFileNoFollow,
+  PROJECT_DIR,
+  readStdinJson,
 } from "./lib/hook-io.mjs";
 import {
   registerFaultPolicy,
@@ -41,11 +42,14 @@ import {
   writeFaultOutcome,
 } from "./lib/hook-fault.mjs";
 import {
-  ALERT_FILE,
-  ALERT_ACK_FILE,
-  PROJECT_DIR,
+  alertAckFile,
+  alertDir,
+  appendAlert,
+  sweepStaleSessions,
 } from "./lib/invisible-alert.mjs";
 import { formatReport } from "./lib/invisible-report.mjs";
+import { sweepStaleReveals } from "./lib/reveal.mjs";
+import { sweepStaleConfirms } from "./lib/secret-drop-guard.mjs";
 import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
 import { reportSlowHook, startHookTimer } from "./lib/hook-timing.mjs";
 // Relative, not the `agent-sanitizer` specifier every other engine import uses:
@@ -181,19 +185,15 @@ function reportFault(err) {
 
 /**
  * Persist the accumulated alert text for the PreToolUse gate, or leave the alert
- * absent when there is nothing to surface.
- *
- * ALERT_FILE sits at a predictable, world-visible $TMPDIR path, so a plain
- * writeFileSync would follow a co-tenant-planted symlink and overwrite an
- * arbitrary file this uid owns. Create it symlink-refusingly (see
- * writeFileNoFollow); the gate treats an absent alert as "nothing to surface",
- * so a lost race degrades safely rather than to a hijacked write.
+ * absent when there is nothing to surface. One store entry per part, into THIS
+ * session's alert directory (see appendAlert), so a concurrent
+ * InstructionsLoaded finding cannot clobber the launch scan's report.
  * @param {string[]} parts
+ * @param {string} [sessionId]
  * @returns {void}
  */
-function persistAlert(parts) {
-  if (parts.length === 0) return;
-  writeFileNoFollow(ALERT_FILE, parts.join("\n") + "\n");
+function persistAlert(parts, sessionId) {
+  for (const part of parts) appendAlert(part, sessionId);
 }
 
 // Decoder
@@ -282,8 +282,8 @@ export {
   decodeRun,
   findInstructionFiles,
   scanFile,
-  ALERT_FILE,
-  ALERT_ACK_FILE,
+  alertAckFile,
+  alertDir,
   LONG_RUN_RE,
   LONG_RUN_THRESHOLD,
   TOTAL_INVISIBLE_THRESHOLD,
@@ -353,7 +353,7 @@ export function scanProject(dir = PROJECT_DIR) {
         continue;
       }
       // safeErrMessage, not errMessage: this reason is rendered into stderr and
-      // into ALERT_FILE, and an errno message embeds the absolute path globbed
+      // into the alert store, and an errno message embeds the absolute path globbed
       // out of a possibly-hostile repo — a filename carrying ANSI or invisible
       // bytes would otherwise reach the operator's terminal raw.
       skipped.push({ file: report(file), reason: safeErrMessage(err) });
@@ -399,12 +399,15 @@ export function formatSkipped(skipped) {
  * @param {{
  *   trace?: import("./lib/trace.mjs").TraceFn,
  *   scan?: () => ReturnType<typeof scanProject>,
+ *   sessionId?: string,
  * }} [opts]  `trace` is where this scan announces engagement; a host with its
  *   own trace channel passes its sink so the announcement lands where its
  *   detector reads (see lib/trace.mjs). `scan` is the scanner, injectable so the
  *   FAULT path below — a scanner that throws something other than an errno, i.e.
  *   a bug — is drivable end to end; no filesystem state can force it, and an
  *   untested fault path is how a posture goes missing in the first place.
+ *   `sessionId` keys the alert store this scan writes; the CLI entry reads it off
+ *   the SessionStart payload, and an in-process caller passes it directly.
  * @returns {Promise<void>}
  */
 export async function cliMain(opts = {}) {
@@ -434,10 +437,11 @@ export async function cliMain(opts = {}) {
  * @param {{
  *   trace?: import("./lib/trace.mjs").TraceFn,
  *   scan?: () => ReturnType<typeof scanProject>,
+ *   sessionId?: string,
  * }} opts  see {@link cliMain}
  * @returns {Promise<void>}
  */
-async function runScanCli({ trace: sink = trace, scan: runScan }) {
+async function runScanCli({ trace: sink = trace, scan: runScan, sessionId }) {
   // Bound best-effort: the announcements below run BEFORE the auto-clean and
   // the alert write, with no catch above them, so a throwing host sink would
   // abort the scan silently (see bestEffortTrace).
@@ -470,20 +474,22 @@ async function runScanCli({ trace: sink = trace, scan: runScan }) {
         ),
       ),
     );
-    persistAlert(alertParts);
+    persistAlert(alertParts, sessionId);
     process.exit(1);
   }
   /* c8 ignore stop */
 
-  // Clean up stale alert + its ack marker from a previous session so this
-  // session re-surfaces the gate once if injection is still present.
-  for (const stale of [ALERT_FILE, ALERT_ACK_FILE]) {
-    try {
-      unlinkSync(stale);
-    } catch {
-      // Doesn't exist or not writable
-    }
-  }
+  // No clear: the store is session-keyed, so this session starts empty by
+  // construction and cannot inherit a previous session's ack. Age out what past
+  // sessions left instead — SessionStart is the once-per-session touchpoint the
+  // sweep belongs on.
+  sweepStaleSessions(sessionId);
+  // The other two $TMPDIR stores these hooks own. Both are content- or
+  // fingerprint-addressed with no natural owner to delete them, so without a
+  // sweep they grow for the life of the machine; SessionStart is the only
+  // touchpoint that runs once per session rather than once per tool call.
+  sweepStaleReveals();
+  sweepStaleConfirms();
 
   // Only a non-errno throw reaches here — a bug in the scanner, not a file it
   // could not read (those are accounted for in `skipped`). It is a fault of THIS
@@ -495,7 +501,7 @@ async function runScanCli({ trace: sink = trace, scan: runScan }) {
   } catch (err) {
     emitTrace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, { outcome: "skipped" });
     alertParts.push(...reportFault(err));
-    persistAlert(alertParts);
+    persistAlert(alertParts, sessionId);
     return;
   }
   const { findings: allFindings, skipped, absent, scanned } = scan;
@@ -529,7 +535,7 @@ async function runScanCli({ trace: sink = trace, scan: runScan }) {
 
   if (allFindings.length > 0)
     alertParts.push(...autoCleanFindings(allFindings, PROJECT_DIR));
-  persistAlert(alertParts);
+  persistAlert(alertParts, sessionId);
 }
 
 /**
@@ -602,6 +608,27 @@ function autoCleanFindings(allFindings, dir) {
   return [report];
 }
 
+/**
+ * The session identity from the SessionStart payload on stdin, or undefined when
+ * the host sent none.
+ *
+ * Swallowing: the payload is read for ONE optional field, and a host that pipes
+ * nothing (or malformed JSON) must still get the scan — a session-start scan
+ * refused over an unparseable envelope is a strictly worse outcome than one
+ * keyed to the shared `no-session` fallback.
+ * @returns {Promise<string | undefined>}
+ */
+export async function sessionIdFromStdin() {
+  // A TTY is a human running this scan by hand, not a harness sending an event:
+  // reading it would block forever waiting for a payload nobody is going to send.
+  if (process.stdin.isTTY) return undefined;
+  try {
+    return (await readStdinJson())?.session_id;
+  } catch {
+    return undefined;
+  }
+}
+
 if (isMain(import.meta.url)) {
-  await cliMain();
+  await cliMain({ sessionId: await sessionIdFromStdin() });
 }

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

@@ -24,6 +24,7 @@ import {
   HookEvent,
   isMain,
   lazyImport,
+  PROJECT_DIR,
   readStdinJson,
   safeErrMessage,
 } from "./lib/hook-io.mjs";
@@ -34,7 +35,6 @@ import {
 } from "./lib/hook-fault.mjs";
 import {
   appendAlert,
-  PROJECT_DIR,
   recordInstructionsLoaded,
 } from "./lib/invisible-alert.mjs";
 import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
@@ -259,8 +259,11 @@ export { HOOK_NAME };
 export async function cliMain({ trace: sink = trace } = {}) {
   const timer = startHookTimer();
   const emitTrace = bestEffortTrace(sink);
+  /** @type {string | undefined} */
+  let sessionId;
   try {
     const payload = await readStdinJson();
+    sessionId = payload?.session_id;
     // Recorded before the scan, not after: the marker answers "is this event
     // being scanned", which is true the moment the hook is running, and a
     // faulting scan must not read as an unscanned event — that notice names a
@@ -289,7 +292,7 @@ export async function cliMain({ trace: sink = trace } = {}) {
     // A payload still on disk is the case the PreToolUse gate exists for: it
     // asks once, on the next tool call, rather than leaving the only report on a
     // channel that scrolls.
-    if (!result.cleaned) appendAlert(message);
+    if (!result.cleaned) appendAlert(message, sessionId);
     // systemMessage reaches the user, additionalContext the model. Both, because
     // this hook cannot block and the file is already loaded: the user is the one
     // who can act on it, and the model is the one currently reading it.
@@ -306,7 +309,11 @@ export async function cliMain({ trace: sink = trace } = {}) {
     emitTrace(TraceEvent.SCAN_LOADED_INSTRUCTIONS_RAN, { outcome: "skipped" });
     const outcome = hookFaultOutcome(HOOK_NAME, err);
     process.exitCode = writeFaultOutcome(outcome);
-    if (outcome.armAlert) appendAlert(/** @type {string} */ (outcome.stderr));
+    // `sessionId`, captured before the throw: a payload read that itself failed
+    // leaves it undefined, and the fault then lands in the shared fallback store
+    // rather than in no store at all.
+    if (outcome.armAlert)
+      appendAlert(/** @type {string} */ (outcome.stderr), sessionId);
   } finally {
     reportSlowHook(
       HOOK_NAME,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.43.12",
+  "version": "2.44.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/hook-io.d.mts

@@ -326,13 +326,21 @@ export function configureHookgateMarker(path: string | null): void;
  */
 export function hookgateMarkerPath(projectDir?: string | undefined, runtimeDir?: string | undefined): string | null;
 /**
- * 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.
+ * 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}
  */
@@ -503,6 +511,24 @@ export class EmptyStdinError extends Error {
  * command the reader should actually run.
  */
 export const DEFAULT_MISSING_PACKAGE_REMEDY: "reinstall the hook dependencies (pnpm install) and retry.";
+/**
+ * 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: string;
+/** Short project digest keying this project's $TMPDIR store names. */
+export const PROJECT_HASH: string;
+/**
+ * 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";
 /**
  * EVERY process-wide slot these helpers keep — the four a host can observe or
  * steer, so a second instance that adopts this object is steered in all four at