@consiliency/agent-board-cli 1.27.1 → 1.29.0

package/keyslot/lib.sh

@@ -38,10 +38,33 @@ KEYSEAL_LEGACY_SET_SHA=8e7b771be5a461e4d6b032f518e4c790d91b315011ae2d96eda44bc69
 # pre-migration layout (legacy_loader_present, 2), not as a chain violation.
 KEYSEAL_LEGACY_LOAD_EXEC='%h/.local/libexec/agent-board/keyslot-load.sh %i'
 
-# IF-0-KEYSEAL-5: the scan scope, exactly. Roots are resolved at scan time.
+# IF-0-KEYSEAL-5 as amended by IF-552-1 (#552): the scan scope, exactly. Roots are resolved at
+# scan time. The prune entries are ONE source: the find expression, `pruned` and `pruned_dirs`
+# are all derived from these two arrays, in this order (names, then paths).
 KEYSEAL_SCAN_MAX_BYTES=1048576
-KEYSEAL_SCAN_PRUNE_NAMES=(node_modules .git .cache .npm)
-KEYSEAL_SCAN_PRUNE_PATHS=(.local/share/pnpm)
+KEYSEAL_SCAN_PRUNE_NAMES=(node_modules .git .cache .npm
+  site-packages dist-packages __pycache__ .venv venv env .tox .nox
+  pkgs
+  .rustup target)
+KEYSEAL_SCAN_PRUNE_PATHS=(.local/share/pnpm .pyenv/versions go/pkg/mod .cargo/registry .cargo/git
+  .ollama/models .local/share/containers .local/share/docker)
+# IF-552-2: the scan cache. Wall-clock bounds only; ordering never uses a timestamp.
+KEYSEAL_SCAN_CACHE_FORMAT=agent-board-keyslot-scan/1
+KEYSEAL_SCAN_CACHE_TTL_S=86400
+KEYSEAL_SCAN_CACHE_FUTURE_S=300
+KEYSEAL_SCAN_CACHE_INPUTS=(seam uid machine_id slot mode exempt pin_sha256 blob_sha256 scope_sha256 scanner_sha256)
+# The clean read and write lock wait (a write retries once), and a tombstone's longer wait.
+KEYSEAL_SCAN_LOCK_WAIT_S=10
+KEYSEAL_SCAN_TOMBSTONE_WAIT_S=300
+# The whole scan stage's default bound (status.sh --scan-timeout), and the progress cadence.
+KEYSEAL_SCAN_TIMEOUT_S=1800
+KEYSEAL_SCAN_PROGRESS_S=30
+KEYSEAL_SCAN_LIVENESS_S=5
+KEYSEAL_SCAN_KILL_AFTER_S=10
+KEYSEAL_BIN_TIMEOUT=/usr/bin/timeout
+KEYSEAL_BIN_DATE=/usr/bin/date
+KEYSEAL_BIN_REALPATH=/usr/bin/realpath
+KEYSEAL_BIN_MKFIFO=/usr/bin/mkfifo
 KEYSEAL_SCAN_HEADERS=('-----BEGIN OPENSSH PRIVATE KEY-----' '-----BEGIN PRIVATE KEY-----')
 # What the scan does not detect, by stable id (reported in every status JSON).
 KEYSEAL_SCAN_NOT_DETECTED=(pruned over_1mib not_owned re_encoded_or_encrypted outside_roots)
@@ -163,6 +186,8 @@ keyseal_enabled_slots() {
     s=${s%.service}
     [[ $s =~ $KEYSEAL_SLOT_RE && $link == "$dir/$KEYSEAL_BASE_UNIT@$s.service.wants/"* ]] && printf '%s\n' "$s"
   done
+  # Never the last link's test result: a caller under `set -e` must not stop on it (SC-21).
+  return 0
 }
 
 # Judge slot $1's loader against the running tooling in $2. Sets KEYSEAL_LOADER_STATE:
@@ -392,14 +417,26 @@ if (mode === "derive") {
   // IF-0-KEYSEAL-5: candidates (NUL-separated file on args[0]) -> JSON. args[3], when set,
   // is the ONE exempt path (A1: an opted-in unsealed slot's <slot>.key, 0600, this uid's). It
   // is matched by path, never by inode, and never enters `seen`: a hard link elsewhere is a copy.
+  // args[4] is the prune-index file (one `<i>` line per pruned directory, IF-552-1) and
+  // args[5..] the prune entries in report order: `pruned_dirs` counts each, 0 included.
   const pin = process.env.KEYSEAL_SCAN_PIN || "";
   const uid = Number(args[1]);
   const max = Number(args[2]);
   const exempt = args[3] || "";
-  const raw = fs.readFileSync(args[0]).toString("utf8").split("\0").filter(Boolean);
+  const entries = args.slice(5);
+  const pruned_dirs = Object.fromEntries(entries.map((e) => [e, 0]));
+  for (const line of fs.readFileSync(args[4], "utf8").split("\n")) {
+    if (/^\d+$/.test(line) && Number(line) < entries.length) pruned_dirs[entries[Number(line)]]++;
+  }
+  // A test seam (bash sets it only while KEYSEAL_TEST_ROOT is set): wait per candidate.
+  const delay = Number(process.env.KEYSEAL_SCAN_DELAY_MS || 0);
+  const nap = (ms) => { if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); };
+  // A root named like a prune entry is started at `<root>/.` (keyseal_scan_start): report real paths.
+  const raw = fs.readFileSync(args[0]).toString("utf8").split("\0").filter(Boolean).map((p) => p.replace(/\/\.\//, "/"));
   const seen = new Set();
-  const res = { candidates: 0, plaintext_matches: [], encrypted_skipped: [], unverifiable: [], exempt: [] };
+  const res = { candidates: 0, plaintext_matches: [], encrypted_skipped: [], unverifiable: [], exempt: [], pruned_dirs };
   for (const p of raw) {
+    nap(delay);
     let st;
     try { st = fs.lstatSync(p); } catch { continue; }
     if (!st.isFile() || st.uid !== uid || st.size > max) continue;
@@ -430,6 +467,34 @@ if (mode === "derive") {
     if (verdicts.has("unverifiable")) res.unverifiable.push(p);
   }
   out(JSON.stringify(res) + "\n");
+} else if (mode === "count-matches") {
+  // A scan object on stdin -> how many plaintext matches it names (status.sh's done line).
+  out(`${JSON.parse(readStdin().toString("utf8")).plaintext_matches.length}\n`);
+} else if (mode === "cacheparse") {
+  // IF-552-2, compute only (bash reads, judges and writes). args[0] is a scan-cache file, args[1]
+  // the format tag and args[2..] the input names. Prints `format` for anything that is not a
+  // well-formed cache file; else `clean <generation> <scanned_at> <duration_s>` or
+  // `tombstone <generation> <cleared_at>`, one `input <name> <json>` line per input, and for a
+  // clean file `scan <json>`. A valid generation is a safe integer, 1..2^53-1.
+  const [file, format, ...names] = args;
+  let o;
+  try { o = JSON.parse(fs.readFileSync(file, "utf8")); } catch { out("format\n"); process.exit(0); }
+  const bad = () => { out("format\n"); process.exit(0); };
+  if (!o || typeof o !== "object" || Array.isArray(o) || o.format !== format) bad();
+  const g = o.generation;
+  if (!(Number.isSafeInteger(g) && g >= 1)) bad();
+  const inputs = o.inputs;
+  if (!inputs || typeof inputs !== "object" || Array.isArray(inputs) || names.some((n) => !(n in inputs))) bad();
+  if ("cleared_at" in o) {
+    if (!Number.isSafeInteger(o.cleared_at)) bad();
+    out(`tombstone\t${g}\t${o.cleared_at}\n`);
+  } else {
+    const okScan = o.scan && typeof o.scan === "object" && !Array.isArray(o.scan) && Array.isArray(o.scan.plaintext_matches);
+    if (!Number.isSafeInteger(o.scanned_at) || typeof o.duration_s !== "number" || !(o.duration_s >= 0) || !okScan) bad();
+    out(`clean\t${g}\t${o.scanned_at}\t${Math.round(o.duration_s)}\n`);
+  }
+  for (const n of names) out(`input\t${n}\t${JSON.stringify(inputs[n])}\n`);
+  if (!("cleared_at" in o)) out(`scan\t${JSON.stringify(o.scan)}\n`);
 } else {
   process.stderr.write(`keyseal node helper: unknown mode ${mode}\n`);
   process.exit(2);
@@ -560,40 +625,772 @@ keyseal_unsealed_check() {
   keyseal_unsealed_verify "$1" "$(keyseal_uid)" "$mid"
 }
 
-# IF-0-KEYSEAL-5. Prints the scan JSON (the `scan` object of status); rc 0 when it ran, 1
-# when it could not (a failed find/xargs/grep, not "found something"). $2, when set, is the
-# one exempt path: an opted-in unsealed slot's <slot>.key (A1).
-keyseal_scan() {
-  local pin=$1 exempt=${2-} uid list rc_find rc_xargs r json roots=() present=() prune=() h
-  uid=$(id -u)
-  roots=("$HOME" "$XDG_RUNTIME_DIR" "${TMPDIR:-/tmp}" /tmp /var/tmp)
-  for r in "${roots[@]}"; do [[ -d $r ]] && present+=("$r"); done
-  prune=(\()
-  for h in "${KEYSEAL_SCAN_PRUNE_NAMES[@]}"; do prune+=(-name "$h" -o); done
-  for h in "${KEYSEAL_SCAN_PRUNE_PATHS[@]}"; do prune+=(-path "*/$h" -o); done
-  unset 'prune[${#prune[@]}-1]'
-  prune+=(\))
-  local greps=()
+
+# ---------------------------------------------------------------------------
+# IF-0-KEYSEAL-5 as amended by #552: roots, positive prune reporting, the bounded scan stage,
+# the progress ticker, and the scan cache (IF-552-1, IF-552-2)
+# ---------------------------------------------------------------------------
+
+# Temp files and processes this run owns; status.sh's EXIT trap calls keyseal_scan_cleanup.
+declare -A KEYSEAL_CP_INPUT=() KEYSEAL_INPUT=()
+KEYSEAL_SCAN_TMPS=()
+KEYSEAL_SCAN_TPID=
+KEYSEAL_SCAN_TICKER=
+KEYSEAL_CACHE_TMP=
+KEYSEAL_CACHE_LFD=
+
+# Wall clock, epoch seconds. KEYSEAL_TEST_NOW (seam only): an integer, or a file inside the test
+# root holding one, so a stub can move the clock during a run.
+keyseal_now() {
+  local v
+  if seam_active && [[ -n ${KEYSEAL_TEST_NOW-} ]]; then
+    v=$KEYSEAL_TEST_NOW
+    if [[ $v == /* ]]; then
+      v=$(seam_resolve KEYSEAL_TEST_NOW "$v") || return 1
+      IFS= read -r v <"$v" || [[ -n $v ]] || return 1
+    fi
+    [[ $v =~ ^[0-9]+$ ]] || return 1
+    printf '%s' "$v"
+    return 0
+  fi
+  "$KEYSEAL_BIN_DATE" +%s
+}
+keyseal_iso() { "$KEYSEAL_BIN_DATE" -u -d "@$1" +%Y-%m-%dT%H:%M:%SZ; }
+
+# A seam-overridable wait, in whole seconds.
+keyseal_seam_seconds() {
+  local var=$1 default=$2
+  if seam_active && [[ ${!var-} =~ ^[0-9]+$ ]]; then printf '%s' "${!var}"; else printf '%s' "$default"; fi
+}
+
+# The declared roots, resolved (realpath -e) and de-duplicated, first occurrence scanned. Sets
+# KEYSEAL_ROOTS (what is scanned) and KEYSEAL_ROOTS_SKIPPED_JSON (the others, with a reason).
+keyseal_scan_roots() {
+  local r real skipped= seen
+  local -a declared
+  declared=("$HOME" "$XDG_RUNTIME_DIR" "${TMPDIR:-/tmp}" /tmp /var/tmp)
+  KEYSEAL_ROOTS=()
+  for r in "${declared[@]}"; do
+    if ! real=$("$KEYSEAL_BIN_REALPATH" -e -- "$r" 2>/dev/null) || [[ ! -d $real ]]; then
+      skipped+="${skipped:+,}{\"root\":$(keyseal_json_str "$r"),\"reason\":\"absent\"}"
+      continue
+    fi
+    for seen in ${KEYSEAL_ROOTS[@]+"${KEYSEAL_ROOTS[@]}"}; do
+      if [[ $seen == "$real" ]]; then
+        skipped+="${skipped:+,}{\"root\":$(keyseal_json_str "$r"),\"reason\":$(keyseal_json_str "duplicate_of:$real")}"
+        continue 2
+      fi
+    done
+    KEYSEAL_ROOTS+=("$real")
+  done
+  KEYSEAL_ROOTS_SKIPPED_JSON="[$skipped]"
+}
+
+# The starting point find is given for root $1. find applies -name/-path to a START POINT too, so a
+# root named like a prune entry ($HOME=/home/target, a TMPDIR ending in env or go/pkg/mod) would be
+# pruned whole and still read clean (#552 review r1). `<root>/.` has the basename `.`, which no
+# prune clause matches; the classifier strips the `/.` back out of every path it reports.
+keyseal_scan_start() {
+  local root=$1 h
+  for h in "${KEYSEAL_SCAN_PRUNE_NAMES[@]}"; do [[ ${root##*/} == "$h" ]] && { printf '%s/.' "$root"; return; }; done
+  for h in "${KEYSEAL_SCAN_PRUNE_PATHS[@]}"; do [[ $root == */"$h" ]] && { printf '%s/.' "$root"; return; }; done
+  printf '%s' "$root"
+}
+
+keyseal_json_list() {
+  local out= h
+  for h in "$@"; do out+="${out:+,}$(keyseal_json_str "$h")"; done
+  printf '[%s]' "$out"
+}
+
+# The scan's scope, canonical: what IF-552-2's scope_sha256 hashes. Needs keyseal_scan_roots.
+keyseal_scan_scope_json() {
+  printf '{"roots":%s,"roots_skipped":%s,"pruned":%s,"max_bytes":%s,"headers":%s}' \
+    "$(keyseal_json_list ${KEYSEAL_ROOTS[@]+"${KEYSEAL_ROOTS[@]}"})" "$KEYSEAL_ROOTS_SKIPPED_JSON" \
+    "$(keyseal_json_list "${KEYSEAL_SCAN_PRUNE_NAMES[@]}" "${KEYSEAL_SCAN_PRUNE_PATHS[@]}")" \
+    "$KEYSEAL_SCAN_MAX_BYTES" "$(keyseal_json_list "${KEYSEAL_SCAN_HEADERS[@]}")"
+}
+
+# `keyseal-scan.*` files already in the runtime dir: LISTED, never removed (AGENTS.md: a leftover
+# is not inferred to be ours). Call before this run creates its own.
+keyseal_scan_stale_temp() {
+  local f out=
+  for f in "${XDG_RUNTIME_DIR:-/tmp}"/keyseal-scan.*; do
+    [[ -e $f || -L $f ]] && out+="${out:+,}$(keyseal_json_str "$f")"
+  done
+  printf '[%s]' "$out"
+}
+
+# A temp file into variable $1, registered for the EXIT trap (never a command substitution: the
+# registration must happen in THIS shell).
+keyseal_scan_mktemp() {
+  local f dir=${XDG_RUNTIME_DIR:-/tmp}
+  # An absent runtime dir is a root reported `absent`, never a reason the scan cannot run.
+  [[ -d $dir ]] || dir=/tmp
+  f=$(mktemp "$dir/keyseal-scan.XXXXXX") || return 1
+  KEYSEAL_SCAN_TMPS+=("$f")
+  printf -v "$1" '%s' "$f"
+}
+
+# The parent pid of pid $1, from /proc (the field after the state). rc 1 when $1 is gone.
+keyseal_ppid_of() {
+  local s
+  s=$(cat -- "/proc/$1/stat" 2>/dev/null) || return 1
+  s=${s##*) }
+  # shellcheck disable=SC2086
+  set -- $s
+  printf '%s' "$2"
+}
+
+# The pgid of pid $1, from /proc (the fields after the command name: state ppid pgrp).
+keyseal_pgid_of() {
+  local s
+  s=$(cat -- "/proc/$1/stat" 2>/dev/null) || return 1
+  s=${s##*) }
+  # shellcheck disable=SC2086
+  set -- $s
+  printf '%s' "$3"
+}
+
+# The scan stage: ONE child of `timeout`, run as `bash -c` so the deadline covers find, xargs,
+# grep AND every slot's classifier (IF-552-2 "Self-bound"; extended by #552-ONBOARD-SL3 so N
+# slots share this ONE walk — the walk itself never depends on a pin or an exempt path). Args: rc
+# file, count file, pruned file, list file, uid, slot count n, then n groups of (json file, pin,
+# exempt path), then `--`, then the roots. It writes its results to files; status.sh reads them
+# only when the stage completed.
+keyseal_scan_stage() {
+  local rcf=$1 count=$2 pruned=$3 list=$4 uid=$5 n=$6 find grep i=0 h j
+  shift 6
+  local -a jsonfs=() pins=() exempts=() expr greps
+  for ((j = 0; j < n; j++)); do
+    jsonfs+=("$1"); pins+=("$2"); exempts+=("$3")
+    shift 3
+  done
+  [[ ${1-} == -- ]] || exit 3
+  shift
+  find=$(seam_resolve KEYSEAL_TEST_FIND "$KEYSEAL_BIN_FIND") || exit 3
+  grep=$(seam_resolve KEYSEAL_TEST_GREP "$KEYSEAL_BIN_GREP") || exit 3
+  # One clause per prune entry, in report order; each writes its INDEX, never the path. The
+  # first matching clause wins. Every directory that is entered writes one byte to the count.
+  expr=(\( -type d \()
+  for h in "${KEYSEAL_SCAN_PRUNE_NAMES[@]}"; do expr+=(\( -name "$h" -prune -fprintf "$pruned" "$i\\n" \) -o); ((++i)); done
+  for h in "${KEYSEAL_SCAN_PRUNE_PATHS[@]}"; do expr+=(\( -path "*/$h" -prune -fprintf "$pruned" "$i\\n" \) -o); ((++i)); done
+  unset 'expr[${#expr[@]}-1]'
+  expr+=(\) \) -o \( -type d -fprintf "$count" x \) -o \( -type f -user "$uid" -size -$((KEYSEAL_SCAN_MAX_BYTES + 1))c -print0 \))
   for h in "${KEYSEAL_SCAN_HEADERS[@]}"; do greps+=(-e "$h" -e "$h"$'\r'); done
-  list=$(mktemp "${XDG_RUNTIME_DIR:-/tmp}/keyseal-scan.XXXXXX") || return 1
-  "$KEYSEAL_BIN_FIND" -H "${present[@]}" -type d "${prune[@]}" -prune -o \
-    -type f -user "$uid" -size -$((KEYSEAL_SCAN_MAX_BYTES + 1))c -print0 2>/dev/null \
-    | "$KEYSEAL_BIN_XARGS" -0 -r "$KEYSEAL_BIN_GREP" -lsZ -x -F "${greps[@]}" -- >"$list"
-  rc_find=${PIPESTATUS[0]} rc_xargs=${PIPESTATUS[1]}
+  "$find" -H "$@" "${expr[@]}" 2>/dev/null \
+    | "$KEYSEAL_BIN_XARGS" -0 -r "$grep" -lsZ -x -F "${greps[@]}" -- >"$list"
+  local rc_find=${PIPESTATUS[0]} rc_xargs=${PIPESTATUS[1]}
+  local -a rc_nodes=()
   # find: 0, or 1 when some directory was unreadable. xargs: 0, or 123 when some grep found
-  # nothing. Anything else means the scan did not run to completion.
-  if ! { ((rc_find <= 1)) && ((rc_xargs == 0 || rc_xargs == 123)); }; then
-    rm -f -- "$list"
-    return 1
+  # nothing. Anything else means the scan did not run to completion, for every slot alike.
+  if ((rc_find <= 1)) && ((rc_xargs == 0 || rc_xargs == 123)); then
+    local delay=
+    seam_active && delay=${KEYSEAL_TEST_CLASSIFY_DELAY_MS-}
+    for ((j = 0; j < n; j++)); do
+      local rc_node
+      KEYSEAL_SCAN_DELAY_MS=$delay KEYSEAL_SCAN_PIN=${pins[j]} keyseal_node classify "$list" "$uid" "$KEYSEAL_SCAN_MAX_BYTES" "${exempts[j]}" "$pruned" \
+        "${KEYSEAL_SCAN_PRUNE_NAMES[@]}" "${KEYSEAL_SCAN_PRUNE_PATHS[@]}" >"${jsonfs[j]}" && rc_node=0 || rc_node=$?
+      rc_nodes+=("$rc_node")
+    done
+  else
+    for ((j = 0; j < n; j++)); do rc_nodes+=(-); done
+  fi
+  {
+    printf '%s %s' "$rc_find" "$rc_xargs"
+    for j in "${rc_nodes[@]}"; do printf ' %s' "$j"; done
+    printf '\n'
+  } >"$rcf"
+}
+
+# The stage group led by `timeout` (pid $1) is gone within the grace, else KILLed group-wide
+# (president follow-up 4: uutils' --kill-after reaches only timeout's direct child, so the
+# escalation never depends on timeout being alive).
+keyseal_stage_reap() {
+  local pg=$1 i
+  for ((i = 0; i < KEYSEAL_SCAN_KILL_AFTER_S * 10; i++)); do
+    kill -0 -- "-$pg" 2>/dev/null || return 0
+    "$SLEEP" 0.1
+  done
+  kill -KILL -- "-$pg" 2>/dev/null || true
+}
+
+# The progress ticker, in the background for the stage's lifetime. Every period it prints the
+# frozen progress line (the cli parses <N>). When status.sh's parent OR status.sh itself is gone
+# (president follow-up 3), in this order: it TERMs timeout (whose group forward ends a stage that
+# honours TERM), REAPS the stage group itself (grace, then a group KILL: no trap may be left to do
+# it, and uutils' --kill-after reaches only its direct child), and only then TERMs status.sh (its
+# whole group when status.sh leads one, as the cli's detached spawn makes it). When only the cli
+# died, status.sh is still alive while the stage is reaped: its `wait` returns and it records a
+# stage that did not complete (never a clean write), unless the TERM that follows ends it first.
+#
+# Residual (#552 review r3, S3): if status.sh is SIGKILLed in the microseconds after it reaped
+# `timeout` and before it stops the ticker, the ticker may signal a pid (or pgid) the kernel has
+# already reused. The window is between two adjacent statements; it is recorded, not closed.
+#
+# The PARENT watch is armed only when the cli spawned status.sh: its helper exports
+# KEYSEAL_SCAN_WATCH_PID=<its own pid>, and the watch applies only while that equals status.sh's
+# parent. A hand run (`nohup status.sh … & disown` over ssh, the fleet's pattern for long jobs) is
+# reparented when its shell exits, and must keep scanning (#552 review r1). The SELF watch is always
+# armed. $4 is the parent to watch, or empty.
+keyseal_scan_ticker() {
+  local period=$1 count=$2 tpid=$3 parent=$4 self=$5 pg n sp= me=$BASHPID
+  pg=$(keyseal_pgid_of "$self") || pg=
+  # Liveness is checked every KEYSEAL_SCAN_LIVENESS_S (a sub-tick), the progress line printed every
+  # period: a dead cli or status.sh ends the stage within seconds, not a whole progress period.
+  local step=$KEYSEAL_SCAN_LIVENESS_S elapsed=0
+  ((period < step)) && step=$period
+  trap '[[ -n $sp ]] && kill "$sp" 2>/dev/null; exit 0' TERM
+  while :; do
+    "$SLEEP" "$step" &
+    sp=$!
+    wait "$sp" || true
+    sp=
+    ((elapsed += step))
+    # The parent is gone when it no longer exists, OR when status.sh is no longer its child: a dead
+    # cli's pid can be a zombie (kill -0 succeeds) or reused, but status.sh has been reparented.
+    # status.sh is gone when it is not alive, OR when the ticker is no longer its child: a dead
+    # status.sh reparents the ticker at once, zombie or not, and a reused pid is not our parent
+    # (#552 review r4). The ticker is status.sh's own subshell, so its parent IS status.sh. Its pid
+    # is taken once, above: `$BASHPID` inside `$(…)` would name the substitution's own subshell.
+    if { [[ -n $parent ]] && { ! keyseal_alive "$parent" || [[ $(keyseal_ppid_of "$self") != "$parent" ]]; }; } ||
+      ! keyseal_alive "$self" || [[ $(keyseal_ppid_of "$me") != "$self" ]]; then
+      kill -TERM "$tpid" 2>/dev/null || true
+      # The escalation is ours to finish: a SIGKILLed status.sh runs no trap, and uutils timeout's
+      # --kill-after reaches only its direct child (#552 review r2, codex). Grace, then group KILL.
+      keyseal_stage_reap "$tpid"
+      if [[ $pg == "$self" ]]; then kill -TERM -- "-$pg" 2>/dev/null || true
+      else kill -TERM "$self" 2>/dev/null || true
+      fi
+      exit 0
+    fi
+    ((elapsed >= period)) || continue
+    elapsed=0
+    n=0
+    [[ -f $count ]] && n=$("$KEYSEAL_BIN_STAT" -c %s -- "$count" 2>/dev/null || printf 0)
+    printf 'status: scan: still scanning (%s folders so far)\n' "$n" >&2
+  done
+}
+
+# pid $1 is a live process: the ONE liveness test for the ticker's parent and self watches. A
+# zombie (Z) or dead (X) entry is gone, though `kill -0` still succeeds on it (#552 review r3,
+# codex: an unreaped SIGKILLed status.sh kept its ticker waiting). `kill -0` alone reads EPERM (a
+# process of another uid) as gone; /proc does not. Fallback, stated: where /proc/<pid>/stat cannot
+# be read (a `hidepid=` mount hiding another uid's processes) this falls back to `kill -0`, which
+# counts a zombie as alive. The ticker's self watch does not depend on it (the ticker's own parent).
+# And where /proc cannot be read at all, keyseal_ppid_of fails, so the ticker's own-parent check
+# fires on its first tick: the scan is stopped at once and never yields a clean result, which is
+# loud (every scan fails), never silent.
+keyseal_alive() {
+  local s
+  s=$(cat -- "/proc/$1/stat" 2>/dev/null) || { kill -0 "$1" 2>/dev/null; return; }
+  s=${s##*) }
+  [[ ${s:0:1} != [ZX] ]]
+}
+
+# status.sh's EXIT trap: the ticker, the stage (TERM forwarded to timeout, then group-wide KILL
+# after the grace), and every temp file this run made. A SIGKILL skips it: the stage is still
+# bounded by timeout, and the next cache write removes a dead run's .tmp.
+keyseal_scan_cleanup() {
+  if [[ -n $KEYSEAL_SCAN_TICKER ]]; then kill -TERM "$KEYSEAL_SCAN_TICKER" 2>/dev/null || true; fi
+  if [[ -n $KEYSEAL_SCAN_TPID ]]; then
+    kill -TERM "$KEYSEAL_SCAN_TPID" 2>/dev/null || true
+    keyseal_stage_reap "$KEYSEAL_SCAN_TPID"
+    KEYSEAL_SCAN_TPID=
+  fi
+  rm -f -- ${KEYSEAL_SCAN_TMPS[@]+"${KEYSEAL_SCAN_TMPS[@]}"}
+  if [[ -n $KEYSEAL_CACHE_TMP ]]; then rm -f -- "$KEYSEAL_CACHE_TMP"; fi
+}
+
+# Run the scan stage under one deadline, for every slot named in the caller's parallel arrays
+# KEYSEAL_SCAN_PINS[] / KEYSEAL_SCAN_EXEMPTS[] (at least one entry; #552-ONBOARD-SL3: N slots
+# share this ONE walk, never one walk per slot). $1 deadline (s). Sets KEYSEAL_SCAN_OUTCOME (ok |
+# incomplete | timed_out, for the whole stage: one deadline covers every slot alike),
+# KEYSEAL_SCAN_CLASSIFIED[] (index-parallel to the inputs: each slot's classifier JSON, only when
+# ok) and KEYSEAL_SCAN_FOLDERS (directories entered, from the count file's size).
+keyseal_scan_run() {
+  local deadline=$1 list count pruned rcf trc=0 period rcs n i pat
+  n=${#KEYSEAL_SCAN_PINS[@]}
+  KEYSEAL_SCAN_OUTCOME=incomplete KEYSEAL_SCAN_CLASSIFIED=() KEYSEAL_SCAN_FOLDERS=0
+  ((n >= 1)) || return 0
+  keyseal_scan_mktemp list && keyseal_scan_mktemp count && keyseal_scan_mktemp pruned &&
+    keyseal_scan_mktemp rcf || return 0
+  local -a jsonfs=()
+  for ((i = 0; i < n; i++)); do
+    local jf
+    keyseal_scan_mktemp jf || return 0
+    jsonfs+=("$jf")
+  done
+  if seam_active && [[ ${KEYSEAL_TEST_COUNT_FIFO-} == 1 ]]; then
+    # SC-16's seam: a FIFO with no reader, so the REAL find blocks opening it.
+    rm -f -- "$count" && "$KEYSEAL_BIN_MKFIFO" -m 0600 -- "$count" || return 0
+  fi
+  local -a starts=()
+  local root
+  for root in "${KEYSEAL_ROOTS[@]}"; do starts+=("$(keyseal_scan_start "$root")"); done
+  # No --foreground: timeout leads its own process group and signals all of it (IF-552-2). The
+  # seam KEYSEAL_TEST_TIMEOUT (test root only) substitutes a timeout with uutils' semantics, so a
+  # GNU runner can prove what only uutils would otherwise expose (#552 review r3).
+  local timeout_bin
+  timeout_bin=$(seam_resolve KEYSEAL_TEST_TIMEOUT "$KEYSEAL_BIN_TIMEOUT") || return 0
+  local -a stage_args=("$rcf" "$count" "$pruned" "$list" "$(id -u)" "$n")
+  for ((i = 0; i < n; i++)); do stage_args+=("${jsonfs[i]}" "${KEYSEAL_SCAN_PINS[i]}" "${KEYSEAL_SCAN_EXEMPTS[i]}"); done
+  stage_args+=(--)
+  "$timeout_bin" --kill-after="$KEYSEAL_SCAN_KILL_AFTER_S" "$deadline" \
+    /bin/bash -c '. "$0"; keyseal_scan_stage "$@"' "$keyseal_here/lib.sh" \
+    "${stage_args[@]}" "${starts[@]}" >/dev/null &
+  KEYSEAL_SCAN_TPID=$!
+  period=$(keyseal_seam_seconds KEYSEAL_TEST_SCAN_PROGRESS_S "$KEYSEAL_SCAN_PROGRESS_S")
+  local watch=
+  [[ ${KEYSEAL_SCAN_WATCH_PID-} =~ ^[0-9]+$ && $KEYSEAL_SCAN_WATCH_PID == "$PPID" ]] && watch=$PPID
+  keyseal_scan_ticker "$period" "$count" "$KEYSEAL_SCAN_TPID" "$watch" "$$" &
+  KEYSEAL_SCAN_TICKER=$!
+  wait "$KEYSEAL_SCAN_TPID" || trc=$?
+  # 137: timeout already waited --kill-after and KILLed its child; a survivor there gets no
+  # further grace. Otherwise a survivor has the grace, then a group-wide KILL.
+  if ((trc == 137)); then kill -KILL -- "-$KEYSEAL_SCAN_TPID" 2>/dev/null || true; fi
+  keyseal_stage_reap "$KEYSEAL_SCAN_TPID"
+  KEYSEAL_SCAN_TPID=
+  kill -TERM "$KEYSEAL_SCAN_TICKER" 2>/dev/null || true
+  wait "$KEYSEAL_SCAN_TICKER" 2>/dev/null || true
+  KEYSEAL_SCAN_TICKER=
+  [[ -f $count ]] && KEYSEAL_SCAN_FOLDERS=$("$KEYSEAL_BIN_STAT" -c %s -- "$count" 2>/dev/null || printf 0)
+  # 124: the deadline; 137: timeout's own KILL after --kill-after. Partial output is never read.
+  if ((trc == 124 || trc == 137)); then KEYSEAL_SCAN_OUTCOME=timed_out; return 0; fi
+  ((trc == 0)) || return 0
+  rcs=$(<"$rcf") || return 0
+  pat="^[01] (0|123)"
+  for ((i = 0; i < n; i++)); do pat+=" 0"; done
+  pat+='$'
+  [[ $rcs =~ $pat ]] || return 0
+  for ((i = 0; i < n; i++)); do
+    local c
+    c=$(<"${jsonfs[i]}") || return 0
+    [[ $c == \{* ]] || return 0
+    KEYSEAL_SCAN_CLASSIFIED[i]=$c
+  done
+  KEYSEAL_SCAN_OUTCOME=ok
+}
+
+# The scan object's fixed part for slot index $1: scope, positive prune report and verdicts. This
+# is what a cache stores, WITHOUT `headers`: the cache file lives under $HOME, and the PEM header
+# strings are never written there at all. scope_sha256 covers the headers, so a hit re-adds the
+# current ones (keyseal_scan_with_headers) and a cached report is shape-identical to a fresh one.
+keyseal_scan_core_json() {
+  local i=$1
+  printf '{"roots":%s,"roots_skipped":%s,"pruned":%s,"max_bytes":%s,"not_detected":%s,%s' \
+    "$(keyseal_json_list ${KEYSEAL_ROOTS[@]+"${KEYSEAL_ROOTS[@]}"})" "$KEYSEAL_ROOTS_SKIPPED_JSON" \
+    "$(keyseal_json_list "${KEYSEAL_SCAN_PRUNE_NAMES[@]}" "${KEYSEAL_SCAN_PRUNE_PATHS[@]}")" \
+    "$KEYSEAL_SCAN_MAX_BYTES" \
+    "$(keyseal_json_list "${KEYSEAL_SCAN_NOT_DETECTED[@]}")" "${KEYSEAL_SCAN_CLASSIFIED[i]#\{}"
+}
+keyseal_scan_with_headers() { printf '{"headers":%s,%s' "$(keyseal_json_list "${KEYSEAL_SCAN_HEADERS[@]}")" "${1#\{}"; }
+
+# ---- the cache: location and directory trust (#536 framed against PR #550) --------------------
+
+# The state root: XDG_STATE_HOME if set, else $HOME/.local/state. rc 2 when it is relative.
+keyseal_state_root() {
+  local root=${XDG_STATE_HOME-}
+  [[ -n ${root//[[:space:]]/} ]] || root=$HOME/.local/state
+  [[ $root == /* ]] || return 2
+  printf '%s' "$root"
+}
+
+# A decimal field as JS Number() reads the forms /etc/group and /etc/passwd hold: optional
+# surrounding blanks, digits only. Prints the value, rc 1 otherwise.
+keyseal_num_field() {
+  local v=$1
+  v=${v#"${v%%[![:space:]]*}"}
+  v=${v%"${v##*[![:space:]]}"}
+  [[ $v =~ ^[0-9]+$ ]] || return 1
+  printf '%s' "$((10#$v))"
+}
+
+# Split a line on ':' keeping empty and trailing fields (as JS split does) into KEYSEAL_FIELDS.
+keyseal_split_colon() {
+  local line=$1
+  KEYSEAL_FIELDS=()
+  while [[ $line == *:* ]]; do
+    KEYSEAL_FIELDS+=("${line%%:*}")
+    line=${line#*:}
+  done
+  KEYSEAL_FIELDS+=("$line")
+}
+
+# isPrivateGroup (claude_marketplace.ts), ported: gid $1 is the user's PRIVATE group. $2 the
+# process's primary gid, $3 the user name, $4 the uid. Proven only from /etc/group and
+# /etc/passwd (seams KEYSEAL_TEST_GROUP_FILE / KEYSEAL_TEST_PASSWD_FILE, under the test root):
+# exactly one group entry for the gid, named as the user, members a subset of {user}; exactly one
+# account with that primary gid, and it is this user, name and uid. rc 0 private.
+keyseal_private_group() {
+  local gid=$1 primary=$2 user=$3 uid=$4 groupf passwdf line n m members gname
+  local -a groups_ accounts
+  [[ -n $user && $gid =~ ^[0-9]+$ && $primary =~ ^[0-9]+$ ]] || return 1
+  ((10#$gid == 10#$primary)) || return 1
+  groupf=$(seam_resolve KEYSEAL_TEST_GROUP_FILE /etc/group) || return 1
+  passwdf=$(seam_resolve KEYSEAL_TEST_PASSWD_FILE /etc/passwd) || return 1
+  [[ -r $groupf && -r $passwdf ]] || return 1
+  groups_=()
+  while IFS= read -r line || [[ -n $line ]]; do
+    keyseal_split_colon "$line"
+    ((${#KEYSEAL_FIELDS[@]} >= 4)) && [[ -n ${KEYSEAL_FIELDS[2]} ]] || continue
+    n=$(keyseal_num_field "${KEYSEAL_FIELDS[2]}") || continue
+    if ((n == 10#$gid)); then groups_+=("${KEYSEAL_FIELDS[0]}:${KEYSEAL_FIELDS[3]}"); fi
+  # No `|| return 1` here: a loop's status is its LAST body command's, so a last line that is not
+  # the user's group made this "not private" (claw, SL-3.3: /etc/group ends `mbold:x:1002:`).
+  # The files were checked readable above; SC-21 forbids a loop status that leaks.
+  done <"$groupf"
+  ((${#groups_[@]} == 1)) || return 1
+  gname=${groups_[0]%%:*}
+  [[ $gname == "$user" ]] || return 1
+  members=${groups_[0]#*:}
+  IFS=, read -ra accounts <<<"$members"
+  for m in ${accounts[@]+"${accounts[@]}"}; do
+    m=${m#"${m%%[![:space:]]*}"}
+    m=${m%"${m##*[![:space:]]}"}
+    [[ -z $m || $m == "$user" ]] || return 1
+  done
+  accounts=()
+  while IFS= read -r line || [[ -n $line ]]; do
+    keyseal_split_colon "$line"
+    ((${#KEYSEAL_FIELDS[@]} >= 4)) && [[ -n ${KEYSEAL_FIELDS[3]} ]] || continue
+    n=$(keyseal_num_field "${KEYSEAL_FIELDS[3]}") || continue
+    if ((n == 10#$gid)); then accounts+=("${KEYSEAL_FIELDS[0]}:${KEYSEAL_FIELDS[2]}"); fi
+  done <"$passwdf"
+  ((${#accounts[@]} == 1)) || return 1
+  [[ ${accounts[0]%%:*} == "$user" ]] || return 1
+  n=$(keyseal_num_field "${accounts[0]#*:}") || return 1
+  [[ $uid =~ ^[0-9]+$ ]] && ((n == 10#$uid))
+}
+
+# Judge one directory the walk ENTERED ($1 path, $2 role: dir | parent | ancestor, $3 uid).
+# Prints the cause and returns 1 when it is not trusted.
+keyseal_trust_enter() {
+  local path=$1 role=$2 uid=$3 u g a mode own=no
+  [[ $role != ancestor ]] && own=yes
+  if [[ -L $path || ! -d $path ]]; then printf 'not_directory %s' "$path"; return 1; fi
+  read -r u g a < <("$KEYSEAL_BIN_STAT" -c '%u %g %a' -- "$path") || { printf 'not_directory %s' "$path"; return 1; }
+  if [[ $own == yes ]]; then
+    [[ $u == "$uid" ]] || { printf 'foreign_owner %s' "$path"; return 1; }
+  else
+    [[ $u == "$uid" || $u == 0 ]] || { printf 'foreign_owner %s' "$path"; return 1; }
+  fi
+  mode=$((8#$a))
+  ((mode & 8#022)) || return 0
+  if [[ $own == no && $u == 0 ]] && ((mode & 8#1000)); then return 0; fi
+  if [[ $own == no && $u == "$uid" ]] && ! ((mode & 8#002)) &&
+    keyseal_private_group "$g" "$(id -g)" "$(id -un)" "$uid"; then
+    return 0
+  fi
+  printf 'writable %s' "$path"
+  return 1
+}
+
+# resolveTrustChain (claude_marketplace.ts), ported: walk $1 from `/` one component at a time,
+# as the kernel does. The last two components (keyslot-scan/ and its agent-board/ parent) are
+# judged strictly and may never be symlinks; every other directory entered by the ancestor rule.
+# A symlinked ancestor is judged by its own owner (this uid or root) and its target spliced into
+# the remaining components; more than 40 hops is a loop. Stops at the first missing component.
+# rc 0 trusted; else prints `<cause> <path>` and returns 1. $2 is the uid.
+keyseal_cache_chain() {
+  local target=$1 uid=$2 current=/ name path role to u hops=0
+  local -a queue parts
+  [[ $target == /* ]] || { printf 'not_absolute %s' "$target"; return 1; }
+  keyseal_trust_enter / ancestor "$uid" || return 1
+  IFS=/ read -ra parts <<<"$target"
+  queue=()
+  for name in "${parts[@]}"; do [[ -n $name ]] && queue+=("$name"); done
+  while ((${#queue[@]})); do
+    name=${queue[0]}
+    queue=("${queue[@]:1}")
+    if ((${#queue[@]} == 0)); then role=dir; elif ((${#queue[@]} == 1)); then role=parent; else role=ancestor; fi
+    [[ $name == . ]] && continue
+    if [[ $name == .. ]]; then
+      current=${current%/*}
+      [[ -n $current ]] || current=/
+      continue
+    fi
+    if [[ $current == / ]]; then path=/$name; else path=$current/$name; fi
+    [[ -e $path || -L $path ]] || break
+    if [[ -L $path ]]; then
+      [[ $role == ancestor ]] || { printf 'symlink %s' "$path"; return 1; }
+      u=$("$KEYSEAL_BIN_STAT" -c %u -- "$path") || { printf 'not_directory %s' "$path"; return 1; }
+      [[ $u == "$uid" || $u == 0 ]] || { printf 'foreign_owner %s' "$path"; return 1; }
+      ((++hops > 40)) && { printf 'symlink_loop %s' "$path"; return 1; }
+      to=$(readlink -- "$path") || { printf 'not_directory %s' "$path"; return 1; }
+      [[ $to == /* ]] && current=/
+      IFS=/ read -ra parts <<<"$to"
+      local -a spliced=()
+      for name in ${parts[@]+"${parts[@]}"}; do [[ -n $name ]] && spliced+=("$name"); done
+      queue=(${spliced[@]+"${spliced[@]}"} ${queue[@]+"${queue[@]}"})
+      continue
+    fi
+    keyseal_trust_enter "$path" "$role" "$uid" || return 1
+    current=$path
+  done
+  return 0
+}
+
+# ---- the cache: tokens, lock, read and judge, commit -------------------------------------------
+
+# The start token: the file's CONTENT HASH (never its generation), or `absent`. A symlink or a
+# non-regular file is hashed by what it is, never read.
+keyseal_cache_token() {
+  local f=$1 h
+  if [[ -L $f ]]; then printf 'symlink:%s' "$(keyseal_sha256_str "$(readlink -- "$f")")"
+  elif [[ ! -e $f ]]; then printf absent
+  elif [[ -f $f ]]; then
+    if h=$(keyseal_sha256_file "$f"); then printf 'sha:%s' "$h"
+    else printf 'unreadable:%s' "$("$KEYSEAL_BIN_STAT" -c '%d:%i:%Y' -- "$f" 2>/dev/null)"
+    fi
+  else printf 'other:%s' "$("$KEYSEAL_BIN_STAT" -c '%d:%i:%F' -- "$f" 2>/dev/null)"
+  fi
+}
+
+# Take the slot's cache lock ($1 dir, $2 slot, $3 wait s): a 0600 lock file in the trusted dir.
+keyseal_cache_lock() {
+  local lock=$1/$2.lock
+  (umask 077 && : >>"$lock") 2>/dev/null || return 1
+  exec {KEYSEAL_CACHE_LFD}>>"$lock" || return 1
+  if "$FLOCK" -w "$3" "$KEYSEAL_CACHE_LFD"; then return 0; fi
+  exec {KEYSEAL_CACHE_LFD}>&-
+  KEYSEAL_CACHE_LFD=
+  return 1
+}
+keyseal_cache_unlock() {
+  if [[ -n $KEYSEAL_CACHE_LFD ]]; then exec {KEYSEAL_CACHE_LFD}>&-; fi
+  KEYSEAL_CACHE_LFD=
+}
+
+# The cache directory, into KEYSEAL_CACHE_DIR; rc 2 when the state root is relative.
+keyseal_cache_dir() {
+  local root
+  root=$(keyseal_state_root) || return 2
+  KEYSEAL_CACHE_DIR=$root/agent-board/keyslot-scan
+}
+
+# Parse a cache file into KEYSEAL_CP_KIND (format | clean | tombstone), KEYSEAL_CP_GEN,
+# KEYSEAL_CP_STAMP (scanned_at or cleared_at), KEYSEAL_CP_DURATION, KEYSEAL_CP_SCAN and
+# KEYSEAL_CP_INPUT[<name>] (compact JSON).
+keyseal_cache_parse() {
+  local line kind rest
+  KEYSEAL_CP_INPUT=()
+  KEYSEAL_CP_KIND=format KEYSEAL_CP_GEN=0 KEYSEAL_CP_STAMP= KEYSEAL_CP_DURATION= KEYSEAL_CP_SCAN=
+  while IFS= read -r line; do
+    kind=${line%%$'\t'*}
+    rest=${line#*$'\t'}
+    case $kind in
+      clean) KEYSEAL_CP_KIND=clean; IFS=$'\t' read -r KEYSEAL_CP_GEN KEYSEAL_CP_STAMP KEYSEAL_CP_DURATION <<<"$rest" ;;
+      tombstone) KEYSEAL_CP_KIND=tombstone; IFS=$'\t' read -r KEYSEAL_CP_GEN KEYSEAL_CP_STAMP <<<"$rest" ;;
+      input) KEYSEAL_CP_INPUT[${rest%%$'\t'*}]=${rest#*$'\t'} ;;
+      scan) KEYSEAL_CP_SCAN=$rest ;;
+      *) KEYSEAL_CP_KIND=format ;;
+    esac
+  done < <(keyseal_node cacheparse "$1" "$KEYSEAL_SCAN_CACHE_FORMAT" "${KEYSEAL_SCAN_CACHE_INPUTS[@]}" 2>/dev/null || printf 'format\n')
+  return 0
+}
+
+# The inputs object for this run, from KEYSEAL_INPUT[<name>] (compact JSON values).
+keyseal_cache_inputs_json() {
+  local n out=
+  for n in "${KEYSEAL_SCAN_CACHE_INPUTS[@]}"; do out+="${out:+,}\"$n\":${KEYSEAL_INPUT[$n]}"; done
+  printf '{%s}' "$out"
+}
+
+# Read and judge the slot's cache under the lock. $1 slot, $2 mode (fresh | use | only). Sets
+# KEYSEAL_CACHE_STATE / _REASON (IF-552-2's vocabulary), KEYSEAL_CACHE_TOKEN (the start token,
+# empty when none could be recorded) and, on a hit, KEYSEAL_CACHE_SCAN / _SCANNED_AT / _DURATION.
+keyseal_cache_read() {
+  keyseal_cache_judge "$@"
+  # `fresh` never reads the cache: whatever the judge found, the reported read is rescan_requested
+  # (the mode table), on the early-return paths too. The start token it recorded, or not, stands.
+  if [[ $2 == fresh ]]; then KEYSEAL_CACHE_STATE=miss KEYSEAL_CACHE_REASON=rescan_requested KEYSEAL_CACHE_SCAN=; fi
+}
+keyseal_cache_judge() {
+  local slot=$1 mode=$2 f now uid u a problem n
+  KEYSEAL_CACHE_STATE=miss KEYSEAL_CACHE_REASON= KEYSEAL_CACHE_TOKEN= KEYSEAL_CACHE_SCAN=
+  KEYSEAL_CACHE_SCANNED_AT= KEYSEAL_CACHE_DURATION= KEYSEAL_CACHE_LAST=
+  local judged_state judged_reason
+  if ! keyseal_cache_dir; then KEYSEAL_CACHE_STATE=unusable KEYSEAL_CACHE_REASON=state_root_relative; return 0; fi
+  if [[ ${KEYSEAL_INPUT[machine_id]} == null ]]; then KEYSEAL_CACHE_STATE=unusable KEYSEAL_CACHE_REASON=machine_id_unreadable; return 0; fi
+  f=$KEYSEAL_CACHE_DIR/$slot.json
+  if [[ ! -d $KEYSEAL_CACHE_DIR ]]; then
+    # Nothing to lock yet: a commit from this start needs the file still absent, under the lock.
+    KEYSEAL_CACHE_TOKEN=absent
+    judged_state=miss judged_reason=absent
+  else
+    uid=$(keyseal_uid)
+    if ! problem=$(keyseal_cache_chain "$KEYSEAL_CACHE_DIR" "$uid"); then
+      # An untrusted directory is never locked or read. The file's own lstat, when it names a
+      # problem, is the more specific reason.
+      KEYSEAL_CACHE_STATE=unusable KEYSEAL_CACHE_REASON=untrusted:ancestor
+      if [[ -L $f ]]; then KEYSEAL_CACHE_REASON=untrusted:symlink
+      elif [[ -e $f && ! -f $f ]]; then KEYSEAL_CACHE_REASON=untrusted:not_regular
+      elif [[ -f $f ]]; then
+        read -r u a < <("$KEYSEAL_BIN_STAT" -c '%u %a' -- "$f") || true
+        if [[ $u != "$uid" ]]; then KEYSEAL_CACHE_REASON=untrusted:owner
+        elif [[ $a != 600 ]]; then KEYSEAL_CACHE_REASON=untrusted:mode
+        fi
+      fi
+      return 0
+    fi
+    if ! keyseal_cache_lock "$KEYSEAL_CACHE_DIR" "$slot" "$(keyseal_seam_seconds KEYSEAL_TEST_LOCK_WAIT_S "$KEYSEAL_SCAN_LOCK_WAIT_S")"; then
+      KEYSEAL_CACHE_STATE=unusable KEYSEAL_CACHE_REASON=lock_busy
+      return 0
+    fi
+    KEYSEAL_CACHE_TOKEN=$(keyseal_cache_token "$f")
+    if [[ $KEYSEAL_CACHE_TOKEN == absent ]]; then judged_state=miss judged_reason=absent
+    elif [[ -L $f ]]; then judged_state=unusable judged_reason=untrusted:symlink
+    elif [[ ! -f $f ]]; then judged_state=unusable judged_reason=untrusted:not_regular
+    else
+      read -r u a < <("$KEYSEAL_BIN_STAT" -c '%u %a' -- "$f") || true
+      if [[ $u != "$uid" ]]; then judged_state=unusable judged_reason=untrusted:owner
+      elif [[ $a != 600 ]]; then judged_state=unusable judged_reason=untrusted:mode
+      else
+        keyseal_cache_parse "$f"
+        if [[ $KEYSEAL_CP_KIND == format ]]; then judged_state=miss judged_reason=format
+        elif [[ $KEYSEAL_CP_KIND == tombstone ]]; then judged_state=miss judged_reason=cleared
+        else
+          KEYSEAL_CACHE_LAST=$KEYSEAL_CP_STAMP
+          judged_state=hit judged_reason=
+          for n in "${KEYSEAL_SCAN_CACHE_INPUTS[@]}"; do
+            if [[ ${KEYSEAL_CP_INPUT[$n]-} != "${KEYSEAL_INPUT[$n]}" ]]; then
+              judged_state=miss judged_reason=input_changed:$n
+              break
+            fi
+          done
+          if [[ $judged_state == hit ]]; then
+            now=$(keyseal_now) || now=
+            if [[ -z $now ]]; then judged_state=miss judged_reason=format
+            elif ((KEYSEAL_CP_STAMP > now + KEYSEAL_SCAN_CACHE_FUTURE_S)); then judged_state=miss judged_reason=future
+            elif ((now - KEYSEAL_CP_STAMP >= KEYSEAL_SCAN_CACHE_TTL_S)); then judged_state=miss judged_reason=expired
+            else
+              KEYSEAL_CACHE_SCAN=$KEYSEAL_CP_SCAN KEYSEAL_CACHE_SCANNED_AT=$KEYSEAL_CP_STAMP
+              KEYSEAL_CACHE_DURATION=$KEYSEAL_CP_DURATION
+            fi
+          fi
+        fi
+      fi
+    fi
+    keyseal_cache_unlock
+  fi
+  if [[ $mode == fresh ]]; then
+    KEYSEAL_CACHE_STATE=miss KEYSEAL_CACHE_REASON=rescan_requested KEYSEAL_CACHE_SCAN=
+  else
+    KEYSEAL_CACHE_STATE=$judged_state KEYSEAL_CACHE_REASON=$judged_reason
+  fi
+}
+
+# Create the cache directory (0700 each) and judge its chain. rc 0 trusted.
+keyseal_cache_prepare_dir() {
+  keyseal_cache_dir || return 1
+  (umask 077 && mkdir -p -- "$KEYSEAL_CACHE_DIR") 2>/dev/null || return 1
+  keyseal_cache_chain "$KEYSEAL_CACHE_DIR" "$(keyseal_uid)" >/dev/null
+}
+
+# Under the lock: remove this slot's `.<slot>.json.<pid>.tmp` whose pid is not alive (ours by
+# name, owner and directory; a SIGKILLed run skipped its trap).
+keyseal_cache_sweep() {
+  local slot=$1 f pid uid
+  uid=$(keyseal_uid)
+  for f in "$KEYSEAL_CACHE_DIR/.$slot.json."*.tmp; do
+    [[ -f $f && ! -L $f ]] || continue
+    pid=${f##*/."$slot".json.}
+    pid=${pid%.tmp}
+    [[ $pid =~ ^[0-9]+$ ]] || continue
+    [[ $("$KEYSEAL_BIN_STAT" -c %u -- "$f" 2>/dev/null) == "$uid" ]] || continue
+    kill -0 "$pid" 2>/dev/null || rm -f -- "$f"
+  done
+  return 0
+}
+
+# Write one line atomically (mktemp-named by pid, 0600, then rename). rc 0 written.
+keyseal_cache_put() {
+  local slot=$1 line=$2
+  # Test seam only (a no-op without KEYSEAL_TEST_ROOT): a write that fails, as a full disk would.
+  if seam_active && [[ ${KEYSEAL_TEST_FAIL_AT-} == cache_put && ${KEYSEAL_TEST_FAIL_MODE-} == fail ]]; then return 1; fi
+  KEYSEAL_CACHE_TMP=$KEYSEAL_CACHE_DIR/.$slot.json.$$.tmp
+  (umask 077 && printf '%s\n' "$line" >"$KEYSEAL_CACHE_TMP") 2>/dev/null || return 1
+  chmod 0600 -- "$KEYSEAL_CACHE_TMP" || return 1
+  mv -f -- "$KEYSEAL_CACHE_TMP" "$KEYSEAL_CACHE_DIR/$slot.json" || return 1
+  KEYSEAL_CACHE_TMP=
+}
+
+# The stored valid generation, or 0 (absent, corrupt or not ours).
+keyseal_cache_generation() {
+  local f=$1
+  [[ -f $f && ! -L $f ]] || { printf 0; return 0; }
+  keyseal_cache_parse "$f"
+  if [[ $KEYSEAL_CP_KIND == format ]]; then printf 0; else printf '%s' "$KEYSEAL_CP_GEN"; fi
+}
+
+# A clean, completed scan: commit only when the file's token still equals the start token. $1
+# slot, $2 scanned_at (the START), $3 duration, $4 the scan core JSON. Sets KEYSEAL_CACHE_STATE /
+# _REASON to written or not_written:<reason>.
+keyseal_cache_commit_clean() {
+  local slot=$1 start=$2 duration=$3 core=$4 f cur gen wait
+  KEYSEAL_CACHE_STATE=not_written
+  if [[ ${KEYSEAL_INPUT[machine_id]} == null ]]; then KEYSEAL_CACHE_REASON=write_failed; return 0; fi
+  if ! keyseal_cache_prepare_dir; then KEYSEAL_CACHE_REASON=untrusted_dir; return 0; fi
+  # No start token (the read found the lock busy): nothing proves no commit happened meanwhile.
+  if [[ -z $KEYSEAL_CACHE_TOKEN ]]; then KEYSEAL_CACHE_REASON=lock_busy; return 0; fi
+  wait=$(keyseal_seam_seconds KEYSEAL_TEST_LOCK_WAIT_S "$KEYSEAL_SCAN_LOCK_WAIT_S")
+  # One retry: a completed 30-minute scan is dropped only after two waits of contention.
+  if ! keyseal_cache_lock "$KEYSEAL_CACHE_DIR" "$slot" "$wait" && ! keyseal_cache_lock "$KEYSEAL_CACHE_DIR" "$slot" "$wait"; then
+    KEYSEAL_CACHE_REASON=lock_busy
+    return 0
+  fi
+  f=$KEYSEAL_CACHE_DIR/$slot.json
+  cur=$(keyseal_cache_token "$f")
+  if [[ $cur != "$KEYSEAL_CACHE_TOKEN" ]]; then
+    keyseal_cache_unlock
+    KEYSEAL_CACHE_REASON=superseded
+    return 0
+  fi
+  keyseal_cache_sweep "$slot"
+  gen=$(keyseal_cache_generation "$f")
+  if keyseal_cache_put "$slot" "{\"format\":\"$KEYSEAL_SCAN_CACHE_FORMAT\",\"generation\":$((gen + 1)),\"inputs\":$(keyseal_cache_inputs_json),\"scanned_at\":$start,\"duration_s\":$duration,\"scan\":$core}"; then
+    KEYSEAL_CACHE_STATE=written KEYSEAL_CACHE_REASON=
+  else
+    KEYSEAL_CACHE_REASON=write_failed
+  fi
+  keyseal_cache_unlock
+}
+
+# A match: the tombstone commits UNCONDITIONALLY (whatever the file holds or the token was),
+# waiting far longer for the lock than a clean write. $1 slot, $2 the hard-error harness name.
+keyseal_cache_commit_tombstone() {
+  local slot=$1 harness=$2 f gen now wait
+  KEYSEAL_CACHE_STATE=not_written
+  # Unconditional, an unreadable machine id included (#552 review r1): every read treats a
+  # tombstone as miss:cleared before it compares inputs, so it outlives a transient failure.
+  if ! keyseal_cache_prepare_dir; then KEYSEAL_CACHE_REASON=untrusted_dir; return 0; fi
+  wait=$(keyseal_seam_seconds KEYSEAL_TEST_TOMBSTONE_WAIT_S "$KEYSEAL_SCAN_TOMBSTONE_WAIT_S")
+  if ! keyseal_cache_lock "$KEYSEAL_CACHE_DIR" "$slot" 0; then
+    printf 'status: scan: waiting for the scan-cache lock to record a found copy\n' >&2
+    if ! keyseal_cache_lock "$KEYSEAL_CACHE_DIR" "$slot" "$wait"; then
+      KEYSEAL_CACHE_REASON=tombstone_lock_busy
+      printf '%s: tombstone_lock_busy: a plaintext copy was found but could not be recorded in %s; until `agent-board doctor --harness %s --rescan` succeeds, a cached clean result for this slot must not be trusted\n' \
+        "${0##*/}" "$KEYSEAL_CACHE_DIR/$slot.lock" "$harness" >&2
+      return 0
+    fi
+  fi
+  f=$KEYSEAL_CACHE_DIR/$slot.json
+  keyseal_cache_sweep "$slot"
+  gen=$(keyseal_cache_generation "$f")
+  now=$(keyseal_now) || now=0
+  if keyseal_cache_put "$slot" "{\"format\":\"$KEYSEAL_SCAN_CACHE_FORMAT\",\"generation\":$((gen + 1)),\"cleared_at\":$now,\"inputs\":$(keyseal_cache_inputs_json)}"; then
+    KEYSEAL_CACHE_STATE=cleared KEYSEAL_CACHE_REASON=
+  else
+    # The tombstone could not be written (#552 review r6): the previous clean result must not
+    # survive a found copy, so remove it. The next read is then miss:absent and rescans. Only if
+    # that also fails does a clean result remain, and then we say so, as tombstone_lock_busy does.
+    KEYSEAL_CACHE_REASON=write_failed
+    rm -f -- "$KEYSEAL_CACHE_TMP" 2>/dev/null
+    if ! rm -f -- "$f" 2>/dev/null || [[ -e $f || -L $f ]]; then
+      printf '%s: tombstone_write_failed: a plaintext copy was found but neither recorded nor was the old result removed (%s); until `agent-board doctor --harness %s --rescan` succeeds, a cached clean result for this slot must not be trusted\n' \
+        "${0##*/}" "$f" "$harness" >&2
+    fi
   fi
-  json=$(KEYSEAL_SCAN_PIN=$pin keyseal_node classify "$list" "$uid" "$KEYSEAL_SCAN_MAX_BYTES" "$exempt") || { rm -f -- "$list"; return 1; }
-  rm -f -- "$list"
-  local jr=() jp=() jn=() jh=()
-  for r in "${roots[@]}"; do jr+=("$(keyseal_json_str "$r")"); done
-  for h in "${KEYSEAL_SCAN_PRUNE_NAMES[@]}" "${KEYSEAL_SCAN_PRUNE_PATHS[@]}"; do jp+=("$(keyseal_json_str "$h")"); done
-  for h in "${KEYSEAL_SCAN_NOT_DETECTED[@]}"; do jn+=("$(keyseal_json_str "$h")"); done
-  for h in "${KEYSEAL_SCAN_HEADERS[@]}"; do jh+=("$(keyseal_json_str "$h")"); done
-  local IFS=,
-  printf '{"roots":[%s],"pruned":[%s],"max_bytes":%s,"headers":[%s],"not_detected":[%s],%s\n' \
-    "${jr[*]}" "${jp[*]}" "$KEYSEAL_SCAN_MAX_BYTES" "${jh[*]}" "${jn[*]}" "${json#\{}"
+  keyseal_cache_unlock
 }