@ngockhoale/ukit 2.4.2 → 2.5.0

package/templates/.claude/ukit/runtime/hook-chain-budget.mjs

@@ -0,0 +1,92 @@
+// hook-chain-budget.mjs — single source of truth for the PreToolUse chain budget.
+//
+// TASK-018 review fix round 1. The chain has TWO deadlines and they must never
+// disagree:
+//   - INNER (hook-chain-runner.mjs): the chain's own total budget, plus the
+//     per-child budget every script may use.
+//   - OUTER (ukit-bridge.js): the `pi.exec` timeout that supervises the runner
+//     process itself.
+//
+// When the outer timeout was a separate hardcoded formula (10s/4s/16s under a
+// fixed 30s cap) while the runner honored UKIT_HOOK_CHAIN_BASE_MS /
+// UKIT_HOOK_CHILD_BUDGET_MS / UKIT_HOOK_CHAIN_CEILING_MS, a chain configured for
+// 60-120s was killed by the bridge at 14-20s. The killed runner produced no
+// verifiable per-script verdict, which is a transport failure — and for
+// Edit|Write that is fail-closed, so every edit was blocked until the operator
+// removed the env var. Both sides now resolve the same numbers here.
+//
+// The clamps are intentionally generous (up to 120s) because they are an
+// explicit operator/test affordance, not a default: an unconfigured chain still
+// resolves to the 10s/4s/16s defaults that keep a PreToolUse call inside omp's
+// own handler budget.
+
+export const CHAIN_BUDGET_SPECS = {
+  base: { name: 'UKIT_HOOK_CHAIN_BASE_MS', fallback: 10000, min: 500, max: 60000 },
+  child: { name: 'UKIT_HOOK_CHILD_BUDGET_MS', fallback: 4000, min: 100, max: 60000 },
+  ceiling: { name: 'UKIT_HOOK_CHAIN_CEILING_MS', fallback: 16000, min: 500, max: 120000 },
+};
+
+// Margin the outer timeout adds on top of the runner's own budget: enough to
+// cover the runner's TERM→KILL grace (hook-process.mjs KILL_GRACE_MS) plus its
+// hard-settle slack, so the runner always wins the race against its supervisor.
+export const CHAIN_EXEC_MARGIN_MS = 4000;
+
+// The largest budget the clamps above can produce: `min(max(base, n×child),
+// max(ceiling, base))` is bounded by the larger of the two maxima. Derived rather
+// than hardcoded so this bound cannot drift from the specs above.
+export const MAX_CHAIN_BUDGET_MS = Math.max(
+  CHAIN_BUDGET_SPECS.base.max,
+  CHAIN_BUDGET_SPECS.ceiling.max,
+);
+
+/**
+ * Read one budget env knob, clamped. A missing, non-finite, or non-positive value
+ * falls back to the default; anything else is clamped into [min, max] so a typo
+ * (or a hostile value) can never disable the deadline.
+ */
+export function envBudgetMs(spec, env = process.env) {
+  const raw = Number(env?.[spec.name]);
+  if (!Number.isFinite(raw) || raw <= 0) return spec.fallback;
+  return Math.min(spec.max, Math.max(spec.min, raw));
+}
+
+export function resolveChainBaseBudgetMs(env = process.env) {
+  return envBudgetMs(CHAIN_BUDGET_SPECS.base, env);
+}
+
+export function resolveChainChildBudgetMs(env = process.env) {
+  return envBudgetMs(CHAIN_BUDGET_SPECS.child, env);
+}
+
+export function resolveChainCeilingMs(env = process.env) {
+  return envBudgetMs(CHAIN_BUDGET_SPECS.ceiling, env);
+}
+
+/**
+ * The chain's total budget for `scriptCount` scripts. The floor guarantees every
+ * child can run its full per-child budget; the ceiling is the explicit
+ * critical-path cap that stops the old linear growth (n × 4s reached 24s for six
+ * hooks) from silently inflating PreToolUse latency.
+ */
+export function resolveChainBudgetMs(scriptCount, env = process.env) {
+  const count = Number.isFinite(scriptCount) && scriptCount > 0 ? scriptCount : 1;
+  const base = resolveChainBaseBudgetMs(env);
+  const ceiling = resolveChainCeilingMs(env);
+  return Math.min(
+    Math.max(base, count * resolveChainChildBudgetMs(env)),
+    Math.max(ceiling, base),
+  );
+}
+
+/**
+ * The outer `pi.exec` timeout for a chain of `scriptCount` scripts. Always
+ * strictly larger than resolveChainBudgetMs() for the same chain shape, so the
+ * bridge never kills a healthy runner mid-chain, and always bounded, so the
+ * bridge can never hang without a deadline.
+ */
+export function resolveChainExecTimeoutMs(scriptCount, env = process.env) {
+  return Math.min(
+    MAX_CHAIN_BUDGET_MS + CHAIN_EXEC_MARGIN_MS,
+    resolveChainBudgetMs(scriptCount, env) + CHAIN_EXEC_MARGIN_MS,
+  );
+}

package/templates/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -2,7 +2,21 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
+// TASK-016: children run through the process-tree runner instead of bare
+// spawnSync — a timed-out child is TERM→KILLed as a whole POSIX process group,
+// so a bash wrapper can no longer orphan the Node grandchildren it spawned.
+import { runHookProcess } from './hook-process.mjs';
+// TASK-019: chain rows and direct-hook rows share one versioned schema and one
+// append API (hook-telemetry.mjs) — including safeName for session files.
+import { appendTelemetryRow, TELEMETRY_VERSION } from './hook-telemetry.mjs';
+// TASK-018 review fix round 1: the chain budget is resolved by ONE shared module
+// so the runner's inner deadline and the bridge's outer pi.exec timeout can never
+// disagree. Kept as a per-run resolution (not module constants) so an operator's
+// env change is honored without a reimport.
+import {
+  resolveChainBudgetMs,
+  resolveChainChildBudgetMs,
+} from './hook-chain-budget.mjs';
 
 const FAIL_CLOSED_SCRIPTS = new Set([
   'protect-files.sh',
@@ -12,26 +26,40 @@ const FAIL_CLOSED_SCRIPTS = new Set([
   'block-dangerous.sh',
 ]);
 
-const TOTAL_BUDGET_MS = 10000;
-const CHILD_BUDGET_MS = 4000;
 const MAX_BUFFER_BYTES = 2 * 1024 * 1024;
 
-function safeName(value) {
-  return String(value || 'unknown').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'unknown';
+// TASK-018 failure taxonomy (chain level; distinct from hook-process.mjs's
+// process-level kinds). Overflow, timeout, signal, and exit-code failures are
+// distinct values so downstream consumers never have to guess:
+//   'ok'               — child exited 0 on its own
+//   'exit-code'        — child exited non-zero on its own (a verdict, possibly a block)
+//   'output-overflow'  — captured output exceeded maxBuffer; the tree was culled
+//   'timeout'          — this runner killed the child at its deadline
+//   'signal'           — the child died from a signal this runner did not send
+//   'error'            — the child never spawned (ENOENT and friends)
+//   'budget-exhausted' — the script never ran: the chain total budget was spent
+function chainFailureKind(processResult) {
+  switch (processResult?.failureKind) {
+    case 'overflow':
+      return 'output-overflow';
+    case 'deadline':
+      return 'timeout';
+    case 'signal':
+      return 'signal';
+    case 'error':
+      return 'error';
+    default:
+      return (processResult?.code ?? 1) === 0 ? 'ok' : 'exit-code';
+  }
 }
 
 function recordTiming(projectRoot, payload, timing) {
-  try {
-    const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-latency');
-    fs.mkdirSync(dir, { recursive: true });
-    const filePath = path.join(dir, `${safeName(payload?.session_id)}.jsonl`);
-    fs.appendFileSync(filePath, `${JSON.stringify(timing)}\n`, 'utf8');
-  } catch {
-    // Timing telemetry is advisory and must never delay or block a tool call.
-  }
+  // Timing telemetry is advisory and must never delay or block a tool call;
+  // appendTelemetryRow carries the same posture (and the per-session cap).
+  appendTelemetryRow(projectRoot, payload?.session_id, timing);
 }
 
-function run(payloadText, scriptPaths) {
+async function run(payloadText, scriptPaths) {
   const payload = JSON.parse(payloadText || '{}');
   const firstScript = scriptPaths[0] || '';
   const projectRoot = firstScript
@@ -40,10 +68,14 @@ function run(payloadText, scriptPaths) {
   const startedAt = Date.now();
   // The chain budget must always be able to run EVERY child at its full per-child
   // budget — a fixed total silently starves later scripts once a chain grows
-  // (UserPromptSubmit now carries 4 hooks). The floor keeps short chains at 10s.
-  const totalBudgetMs = Math.max(TOTAL_BUDGET_MS, scriptPaths.length * CHILD_BUDGET_MS);
+  // (UserPromptSubmit now carries 4 hooks). The floor keeps short chains at 10s,
+  // and TASK-018's explicit ceiling stops the per-chain growth from running away.
+  // Resolved per run (not at import) so an env change takes effect immediately.
+  const childBudgetMs = resolveChainChildBudgetMs();
+  const totalBudgetMs = resolveChainBudgetMs(scriptPaths.length);
   const deadline = startedAt + totalBudgetMs;
   const results = [];
+  let budgetExhausted = false;
 
   for (const scriptPath of scriptPaths) {
     const scriptName = path.basename(scriptPath);
@@ -54,29 +86,42 @@ function run(payloadText, scriptPaths) {
         code: 1,
         stdout: '',
         stderr: `hook chain exceeded its ${totalBudgetMs}ms total budget`,
+        failureKind: 'budget-exhausted',
         killed: true,
         elapsedMs: 0,
       });
+      budgetExhausted = true;
       break;
     }
 
     const childStartedAt = Date.now();
-    const result = spawnSync(scriptPath, [], {
-      cwd: projectRoot,
-      env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
+    const result = await runHookProcess({
+      command: scriptPath,
+      args: [],
       input: payloadText,
-      encoding: 'utf8',
-      timeout: Math.min(CHILD_BUDGET_MS, remainingMs),
+      deadlineMs: Math.min(childBudgetMs, remainingMs),
       maxBuffer: MAX_BUFFER_BYTES,
+      cwd: projectRoot,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
     });
-    const code = Number.isFinite(result.status) ? result.status : 1;
-    const killed = Boolean(result.signal || result.error?.code === 'ETIMEDOUT');
-    const stderr = [result.stderr, result.error?.message].filter(Boolean).join('\n');
+    const failureKind = chainFailureKind(result);
+    const code = Number.isFinite(result.code) ? result.code : 1;
+    // `killed` keeps its old meaning for the bridge: the child was stopped before
+    // a natural exit. The DISTINCT cause lives in failureKind — an overflowing
+    // child is no longer reported as a generic kill or a timeout.
+    const killed =
+      failureKind === 'output-overflow' ||
+      failureKind === 'timeout' ||
+      failureKind === 'signal';
     results.push({
       scriptName,
       code,
-      stdout: result.stdout || '',
-      stderr,
+      // TASK-018: an overflowed child's capture is truncated mid-stream and may
+      // embed anything (secrets included) — it never leaves this process. The
+      // emitting hook should keep its own output bounded; this is the backstop.
+      stdout: failureKind === 'output-overflow' ? '' : (result.stdout || ''),
+      stderr: result.stderr || '',
+      failureKind,
       killed,
       elapsedMs: Date.now() - childStartedAt,
     });
@@ -87,22 +132,32 @@ function run(payloadText, scriptPaths) {
   }
 
   const elapsedMs = Date.now() - startedAt;
+  // TASK-019: versioned rows shared with direct hooks. `outcome` reuses this
+  // runner's own failure taxonomy — the aggregate of the worst child result —
+  // so consumers never re-measure or guess across the two hook paths.
+  const firstFailure = results.find((result) => result.failureKind !== 'ok');
   recordTiming(projectRoot, payload, {
+    v: TELEMETRY_VERSION,
     ts: Date.now(),
+    hook: 'hook-chain-runner',
+    elapsedMs,
+    outcome: budgetExhausted ? 'budget-exhausted' : (firstFailure?.failureKind ?? 'ok'),
     hookEvent: payload?.hook_event_name || null,
     toolName: payload?.tool_name || null,
     toolUseId: payload?.tool_use_id || null,
     elapsedMs,
     budgetMs: totalBudgetMs,
-    scripts: results.map(({ scriptName, code, killed, elapsedMs: scriptElapsedMs }) => ({
+    budgetExhausted,
+    scripts: results.map(({ scriptName, code, killed, failureKind, elapsedMs: scriptElapsedMs }) => ({
       scriptName,
       code,
       killed,
+      failureKind,
       elapsedMs: scriptElapsedMs,
     })),
   });
 
-  return { results, elapsedMs, budgetMs: totalBudgetMs };
+  return { results, elapsedMs, budgetMs: totalBudgetMs, budgetExhausted };
 }
 
 try {
@@ -118,7 +173,7 @@ try {
       payloadText = '{}';
     }
   }
-  process.stdout.write(JSON.stringify(run(payloadText, scriptPaths)));
+  process.stdout.write(JSON.stringify(await run(payloadText, scriptPaths)));
 } catch (error) {
   process.stdout.write(JSON.stringify({
     results: [],

package/templates/.claude/ukit/runtime/hook-input.sh

@@ -5,6 +5,29 @@
 # through ukit_stage_hook_input, then hand UKIT_INPUT_FILE (a path, never
 # the payload) to Node or read a bounded view via command substitution.
 #
+# R4.5 fix (critical): staging itself is bounded. The previous version read the
+# capped prefix and then drained stdin with an unconditional `cat > /dev/null`,
+# so a producer that opens the pipe and never closes it held every migrated hook
+# — including the fail-closed security gate — open indefinitely, and the
+# security gate's deadline could not even start. Staging now:
+#   1. copies at most max_bytes + 1 bytes in the BACKGROUND, and
+#   2. waits for that copy with a hard staging bound (UKIT_HOOK_STAGE_MS,
+#      default 2000). At the bound the reader is killed, so the helper always
+#      returns inside the bound — a slow producer can never stall a hook. The
+#      default stays under the 3s hook-chain budget so even the fail-closed
+#      refusal returns before the harness gives up on this hook.
+#
+# Contract on a bounded stall (UKIT_HOOK_INPUT_STALLED=1, UKIT_INPUT_TRUNCATED=1):
+#   refuse              -> return 2 (fail-closed; an uninspected payload must
+#                          never be treated as a clean scan)
+#   truncate/temp-file  -> return 0 with a short/empty staged payload, which is
+#                          already the consumers' documented degrade path
+# An empty staged file must therefore never be interpreted as "no findings"
+# by a fail-closed hook — it is a refusal.
+#
+# The duplicating read descriptor is deliberately left OPEN for the producer:
+# we stop waiting on it, we never force a write-side EPIPE.
+#
 # Usage:
 #   source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh"
 #   trap ukit_cleanup_hook_input EXIT
@@ -20,15 +43,63 @@
 
 ukit_stage_hook_input() {
   local max_bytes="$1" policy="${2:-truncate}"
-  local dir file size
+  local dir file size stage_ms stage_s reader waiter rc
+  stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$stage_ms" in
+    ''|*[!0-9]*) stage_ms=2000 ;;
+  esac
+  [ "$stage_ms" -gt 0 ] 2>/dev/null || stage_ms=2000
+  # `sleep` counts in SECONDS, the bound is configured in milliseconds.
+  printf -v stage_s '%d.%03d' $((stage_ms / 1000)) $((stage_ms % 1000))
   dir="$(mktemp -d "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")" || return 1
   file="$dir/payload"
-  head -c $((max_bytes + 1)) > "$file" 2>/dev/null
-  # Drain the remainder so the producer never sees EPIPE; discarded bytes
-  # are never materialized.
-  cat > /dev/null 2>&1 || true
+  # Dedicated read descriptor: the background reader must not race with the
+  # wrapper's own stdin consumers, and it must stay open for the producer. With
+  # no stdin at all (invoked with fd 0 closed) the dup fails; fall back to the
+  # reader's own stdin, which then reads an empty payload — the documented
+  # "nothing to scan" posture, never a stall.
+  # (the redirection on `exec` itself keeps its "Bad file descriptor" off stderr)
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c $((max_bytes + 1)) <&8 > "$file" 2>/dev/null &
+    reader=$!
+  else
+    head -c $((max_bytes + 1)) > "$file" 2>/dev/null &
+    reader=$!
+  fi
+  # Watchdog in a subshell: `wait` on a non-child pid only errors, so this is
+  # the portable way to bound the reader on bash 3.2 (macOS). Its own stdio is
+  # redirected to the null device so it can never hold the hook's output pipes
+  # open (which would stall the harness's close-after-earliest-eof contract).
+  ( sleep "$stage_s" 2>/dev/null; kill -9 "$reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  waiter=$!
+  wait "$reader" 2>/dev/null
+  rc=$?
+  kill "$waiter" 2>/dev/null
+  wait "$waiter" 2>/dev/null
+  UKIT_HOOK_INPUT_STALLED=0
+  if [ "$rc" -ne 0 ]; then
+    UKIT_HOOK_INPUT_STALLED=1
+    if [ "$policy" = "refuse" ]; then
+      # Fail-closed: an unstaged payload was never inspected, and 1 is a
+      # *non-blocking* hook error — the gate would let unscannable input through.
+      exec 8<&-
+      rm -rf "$dir"
+      UKIT_INPUT_FILE=""
+      UKIT_INPUT_TRUNCATED=0
+      return 2
+    fi
+  fi
+  # Stop waiting on a producer that may hold the pipe open forever, and drop our
+  # read descriptor while the producer keeps its own write end (never an EPIPE).
+  exec 8<&-
   size="$(wc -c < "$file" | tr -d '[:space:]')"
+  # `rc != 0` here means the staged read was cut off by the staging bound before
+  # EOF: completeness cannot be proven, so the payload is flagged truncated even
+  # when the bytes that did arrive are under the cap. Consumers already degrade
+  # on a short payload; `refuse` never reaches this point.
   UKIT_INPUT_TRUNCATED=0
+  [ "$rc" -ne 0 ] && UKIT_INPUT_TRUNCATED=1
   if [ "$size" -gt "$max_bytes" ]; then
     case "$policy" in
       refuse)
@@ -51,10 +122,19 @@ ukit_stage_hook_input() {
 }
 
 ukit_cleanup_hook_input() {
+  # TASK-019: emit the telemetry finish marker while the staged payload file
+  # still exists (its mtime is the envelope start). Strictly advisory — the
+  # marker never touches the hook's exit status, stdout, or stderr. The hook's
+  # own exit status is captured BEFORE this function's conditionals reset $?.
+  local __ukit_tel_rc=$?
+  if [ "${UKIT_TEL_ARMED:-}" = "1" ] && command -v ukit_hook_telemetry_finish >/dev/null 2>&1; then
+    UKIT_TEL_RC="$__ukit_tel_rc" ukit_hook_telemetry_finish
+  fi
   if [ -n "${UKIT_INPUT_FILE:-}" ] && [ -f "$UKIT_INPUT_FILE" ]; then
     rm -f "$UKIT_INPUT_FILE"
     rmdir "$(dirname "$UKIT_INPUT_FILE")" 2>/dev/null || true
   fi
   UKIT_INPUT_FILE=""
   UKIT_INPUT_TRUNCATED=0
+  UKIT_HOOK_INPUT_STALLED=0
 }

package/templates/.claude/ukit/runtime/hook-payload-store.mjs

@@ -0,0 +1,160 @@
+// hook-payload-store.mjs — atomic payload lifecycle for hook chains (TASK-031, H24).
+//
+// The OMP bridge used to stage EVERY chain payload through a temp file and pay a
+// synchronous stale-file sweep (readdir + statSync per entry) before each exec —
+// unbounded filesystem work on the critical path, outside the runner's timeout
+// scope. This module keeps `@temp-file` transport (macOS ARG_MAX protection for
+// PostToolUse payloads that embed whole tool outputs) but makes the request path
+// O(1):
+//   - payloads at or under PAYLOAD_INLINE_MAX_BYTES never touch the filesystem;
+//   - over-cap payloads are written once, atomically (tmp + rename), owner-only;
+//   - stale sweeps are sampled (default 1/16 of file-mode chains), bounded
+//     (<= maxEntries entries of stat/rm work), and deferred off the request path
+//     by the caller;
+//   - probePayloadIntegrity lets the bridge verify, after a chain returns, that
+//     the file it staged is what the chain actually read.
+// Readers (hook-chain-runner.mjs) keep accepting the `@path` argv form unchanged.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// Comfortably under both macOS limits (256KB per argv entry, ~1MB total ARG_MAX
+// including environment), so a chain never fails exec before any hook runs.
+export const PAYLOAD_INLINE_MAX_BYTES = 64 * 1024;
+
+const SWEEP_PROBABILITY_DEFAULT = 1 / 16;
+const SWEEP_MAX_ENTRIES = 128;
+const SWEEP_MAX_AGE_MS = 60 * 60 * 1000;
+
+function sweepProbabilityFromEnv() {
+  const raw = Number(process.env.UKIT_HOOK_SWEEP_PROBABILITY);
+  if (!Number.isFinite(raw)) return SWEEP_PROBABILITY_DEFAULT;
+  return Math.min(1, Math.max(0, raw));
+}
+
+function inlineReference(payloadText, bytes) {
+  return {
+    mode: 'inline',
+    arg: payloadText,
+    text: payloadText,
+    path: null,
+    bytes,
+    cleanup() { /* nothing was staged — O(1) by construction */ },
+  };
+}
+
+// createPayloadReference(text, {maxBytes, deadlineMs, dir}) ->
+//   { mode: 'inline'|'file', arg, text, path, bytes, cleanup() }
+//
+// `arg` is what the bridge passes to the runner: the payload text itself for
+// inline mode (raw JSON never starts with '@', so the two forms stay
+// unambiguous), or `@<safe-temp-path>` for file mode. `cleanup()` removes a
+// staged file exactly once and is a no-op for inline mode. Any staging failure
+// (unwritable root, deadline exhausted) degrades to inline transport — the
+// bridge owns the policy for what an oversized argv then costs at exec.
+export function createPayloadReference(text, {
+  maxBytes = PAYLOAD_INLINE_MAX_BYTES,
+  deadlineMs = 250,
+  dir,
+} = {}) {
+  const payloadText = String(text ?? '');
+  const bytes = Buffer.byteLength(payloadText, 'utf8');
+  if (bytes <= maxBytes) return inlineReference(payloadText, bytes);
+  try {
+    const startedAt = Date.now();
+    if (!(deadlineMs > 0) || Date.now() - startedAt > deadlineMs) {
+      throw new Error('payload staging deadline exhausted');
+    }
+    if (!dir) throw new Error('payload staging dir is required for over-cap payloads');
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const name = `${Date.now().toString(36)}-${process.pid}-${crypto.randomBytes(6).toString('hex')}.json`;
+    const finalPath = path.join(dir, name);
+    const tmpPath = path.join(dir, `.${name}.tmp`);
+    // Atomic lifecycle: readers either see the complete previous state or the
+    // complete new file — never a partial write mid-stream.
+    fs.writeFileSync(tmpPath, payloadText, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(tmpPath, finalPath);
+    return {
+      mode: 'file',
+      arg: `@${finalPath}`,
+      text: payloadText,
+      path: finalPath,
+      bytes,
+      cleanup() {
+        try { fs.rmSync(finalPath, { force: true }); } catch { /* best effort */ }
+      },
+    };
+  } catch {
+    return inlineReference(payloadText, bytes);
+  }
+}
+
+// probePayloadIntegrity(reference) -> null | 'missing' | 'partial'
+//
+// O(1): one stat of the file this bridge staged. Called by the bridge after the
+// chain returns and before cleanup — if the file vanished or changed size
+// mid-flight, the scripts ran against something other than the host's payload
+// and their verdicts are void.
+export function probePayloadIntegrity(reference) {
+  if (!reference || reference.mode !== 'file' || !reference.path) return null;
+  try {
+    const stats = fs.statSync(reference.path);
+    return stats.size === reference.bytes ? null : 'partial';
+  } catch {
+    return 'missing';
+  }
+}
+
+// sweepStalePayloads(dir, {now, maxAgeMs, maxEntries}) -> {sampled, scanned, removed}
+//
+// Bounded: processes at most maxEntries directory entries regardless of how many
+// stale files accumulated (the crash-after-abandon scenario), so even an
+// unsampled sweep cannot stall a session on a huge directory. Fresh files and
+// non-payload entries are never removed.
+export function sweepStalePayloads(dir, {
+  now = Date.now,
+  maxAgeMs = SWEEP_MAX_AGE_MS,
+  maxEntries = SWEEP_MAX_ENTRIES,
+} = {}) {
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return { sampled: true, scanned: 0, removed: 0 };
+  }
+  const cutoff = now() - maxAgeMs;
+  let scanned = 0;
+  let removed = 0;
+  for (const name of names) {
+    if (scanned >= maxEntries) break;
+    scanned += 1;
+    if (!name.endsWith('.json') && !name.endsWith('.tmp')) continue;
+    const filePath = path.join(dir, name);
+    try {
+      if (fs.statSync(filePath).mtimeMs < cutoff) {
+        fs.rmSync(filePath, { force: true });
+        removed += 1;
+      }
+    } catch { /* raced away — fine */ }
+  }
+  return { sampled: true, scanned, removed };
+}
+
+// maybeSweepStalePayloads(dir, {probability, random, ...}) -> sweep report
+//
+// Sampled gate: by default only ~1 in 16 file-mode chain requests pays for a
+// (bounded) sweep at all. Probability comes from the caller, or from
+// UKIT_HOOK_SWEEP_PROBABILITY (clamped to [0,1]) so operators and tests can
+// disable or force sweeping without editing code.
+export function maybeSweepStalePayloads(dir, {
+  probability,
+  random = Math.random,
+  now,
+  maxAgeMs,
+  maxEntries,
+} = {}) {
+  const p = Number.isFinite(probability) ? Math.min(1, Math.max(0, probability)) : sweepProbabilityFromEnv();
+  if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
+  return sweepStalePayloads(dir, { now, maxAgeMs, maxEntries });
+}