@consiliency/agent-board-cli 1.27.1 → 1.29.0

package/keyslot/status.sh

@@ -1,6 +1,27 @@
 #!/bin/bash
-# status.sh --harness <h> [--slot <s>] [--json]: what does slot <s> hold, measured, and is it
-# chained and loaded? (IF-0-KEYSEAL-3, IF-0-KEYSEAL-6). <s> defaults to <h>.
+# status.sh --harness <h> [--slot <s>] [--json] [--scan-cache fresh|use|only] [--scan-timeout <s>]
+#        or  status.sh --slots <a,b,...> --json [--scan-cache fresh|use|only] [--scan-timeout <s>]:
+# what does slot <s> hold, measured, and is it chained and loaded? (IF-0-KEYSEAL-3,
+# IF-0-KEYSEAL-6). <s> defaults to <h>.
+#
+# SCAN CACHE (IF-552-2, #552): check 6's result is cached per slot under
+# <state root>/agent-board/keyslot-scan/<slot>.json, valid for 24 h and only for the same seam,
+# uid, machine, slot, mode, exemption, pin, blob, scope and scanner. `fresh` (the default, a hand
+# run) never reads it and scans; `use` reads it and scans on a miss; `only` never scans, and a
+# miss is exit 2 `scan_not_cached`. A match is never cached: it writes a tombstone. The whole
+# scan stage runs under one `timeout` (--scan-timeout, default 1800 s); a scan that gives up is
+# exit 2 `scan_timed_out` and is never cached. Progress goes to stderr; stdout stays JSON.
+#
+# --slots <a,b,...> (#552-ONBOARD-SL3, IF-0-ONBOARD-1 "a key scan at most once per host"): judge N
+# slots in one run. Checks 1-5 run per slot, unchanged; check 6 walks the filesystem ONCE for
+# every slot named (one `find`/`xargs`/`grep` stage under one `timeout`), then classifies each
+# slot's candidates separately against that single walk's output, so N slots never cost N walks.
+# `--slots` requires --json and cannot combine with --harness/--slot; each name is both the
+# harness and the slot. Output is one JSON object per line, in the order given, each carrying its
+# own "exit"; the process exit is the worst of the per-slot exits (1 beats 2 beats 0, as below). A
+# single name behaves exactly as --harness <name>: N=1 is "N slots sharing one walk" with N=1, so
+# it is the SAME code path, not a special case, and its output and cache are byte-identical to
+# today's.
 #
 # MODE, from provenance only, never from what provision was asked (A1):
 #   sealed        <s>.cred + <s>.pub, the pin derives from a PIPED decrypt of the blob, no
@@ -34,6 +55,8 @@
 #   legacy_loader_present  flat-layout loader files (pre-A1) are present, or the installed
 #                          template still runs them
 #   nothing_committed, undeterminable
+#   scan_not_cached        --scan-cache only, and no valid cache (the scan is not judged)
+#   scan_timed_out         the scan stage hit --scan-timeout (the scan is not judged)
 # The remedy for the three loader causes is provision.sh --refresh-loader, which never re-keys.
 # The JSON carries hashes only: never the pin, the reference or any key byte.
 set -euo pipefail
@@ -43,29 +66,59 @@ here=${BASH_SOURCE[0]%/*}
 # shellcheck source=lib.sh
 . "$here/lib.sh"
 
-harness= slot= json=no
+harness= slot= slots_arg= json=no scan_cache=fresh scan_timeout=$KEYSEAL_SCAN_TIMEOUT_S
+usage="usage: status.sh --harness <h> [--slot <s>] [--json] [--scan-cache fresh|use|only] [--scan-timeout <s>] | status.sh --slots <a,b,...> --json [--scan-cache fresh|use|only] [--scan-timeout <s>]"
 while (($#)); do
   case $1 in
     --harness) harness=${2-}; shift 2 || keyseal_die "usage: --harness <h>" ;;
     --slot) slot=${2-}; shift 2 || keyseal_die "usage: --slot <s>" ;;
+    --slots) slots_arg=${2-}; shift 2 || keyseal_die "usage: --slots <a,b,...>" ;;
     --json) json=yes; shift ;;
-    *) keyseal_die "usage: status.sh --harness <h> [--slot <s>] [--json]" ;;
+    --scan-cache) scan_cache=${2-}; shift 2 || keyseal_die "$usage" ;;
+    --scan-timeout) scan_timeout=${2-}; shift 2 || keyseal_die "$usage" ;;
+    *) keyseal_die "$usage" ;;
   esac
 done
-[[ $harness =~ $KEYSEAL_SLOT_RE ]] || keyseal_die "bad_harness"
-slot=${slot:-$harness}
-[[ $slot =~ $KEYSEAL_SLOT_RE ]] || keyseal_die "bad_slot"
-: "${XDG_RUNTIME_DIR:?status: XDG_RUNTIME_DIR unset}"
+
+slots=() harness_of=()
+if [[ -n $slots_arg ]]; then
+  [[ -z $harness && -z $slot ]] || keyseal_die "usage: --slots cannot combine with --harness/--slot"
+  [[ $json == yes ]] || keyseal_die "usage: --slots requires --json"
+  IFS=, read -ra slots <<<"$slots_arg"
+  ((${#slots[@]} >= 1)) || keyseal_die "usage: --slots <a,b,...>"
+  declare -A seen_slot=()
+  for s in "${slots[@]}"; do
+    [[ $s =~ $KEYSEAL_SLOT_RE ]] || keyseal_die "bad_slot: $s"
+    [[ -z ${seen_slot[$s]-} ]] || keyseal_die "duplicate_slot: $s"
+    seen_slot[$s]=1
+  done
+  harness_of=("${slots[@]}")
+else
+  [[ $harness =~ $KEYSEAL_SLOT_RE ]] || keyseal_die "bad_harness"
+  slot=${slot:-$harness}
+  [[ $slot =~ $KEYSEAL_SLOT_RE ]] || keyseal_die "bad_slot"
+  slots=("$slot")
+  harness_of=("$harness")
+fi
+n=${#slots[@]}
+[[ $scan_cache == fresh || $scan_cache == use || $scan_cache == only ]] || keyseal_die "bad_scan_cache: $usage"
+[[ $scan_timeout =~ ^[1-9][0-9]{0,6}$ ]] || keyseal_die "bad_scan_timeout: $usage"
+[[ -n ${XDG_RUNTIME_DIR-} ]] || keyseal_die "runtime_dir_unset: XDG_RUNTIME_DIR is unset, so the slot's agent socket cannot be located; run from a login session or export XDG_RUNTIME_DIR=/run/user/$(id -u)"
 : "${HOME:?status: HOME unset}"
 keyseal_resolve_bins || exit 1
+# The scan's cleanup (IF-552-2): the ticker, the stage group and every temp file, on any exit.
+trap keyseal_scan_cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
 
-K=$(keyseal_key_dir)
-cred=$K/$slot.cred pub=$K/$slot.pub key=$K/$slot.key optin=$K/$slot.unsealed-optin
-base_unit=$KEYSEAL_BASE_UNIT@$slot.service
-load_unit=$KEYSEAL_LOAD_UNIT@$slot.service
-declare -A ok detail
-exit2=()
 has() { [[ -e $1 || -L $1 ]]; }
+str_or_null() { if [[ -n $1 ]]; then keyseal_json_str "$1"; else printf null; fi; }
+bool() { if [[ $1 == yes ]]; then printf true; else printf false; fi; }
+state() { "$SYSTEMCTL" --user "$1" "$2" 2>/dev/null || true; }
+
+# ---- host-level, computed at most once per run (IF-0-ONBOARD-1) --------------------------------
+
+K=$(keyseal_key_dir)
 
 probe_out=$("$here/probe.sh" --json 2>/dev/null) && probe_rc=0 || probe_rc=$?
 outcome=error
@@ -73,182 +126,395 @@ outcome=error
 round_trip=unknown
 [[ $probe_out =~ \"round_trip\":\"([a-z_]+)\" ]] && round_trip=${BASH_REMATCH[1]}
 
-# 1 committed: the provenance table. The pin is read whatever the provenance, so a
-# contradiction still scans for copies of the pinned key (review round 1, Opus S3).
-contra=()
-mode=undetermined optin_json=null
-pin=$(keyseal_read_pin "$pub") || pin=
-has "$cred" && has "$key" && contra+=("a sealed blob and an unsealed key are both present")
-has "$cred" && has "$optin" && contra+=("an opt-in record beside a sealed blob")
-has "$optin" && ! has "$key" && contra+=("an opt-in record without $slot.key")
-if has "$optin"; then
-  optin_ok=true
-  optin_problems=$(keyseal_optin_check "$slot") || optin_ok=false
-  plist=
-  while IFS= read -r line; do [[ -n $line ]] && plist+="${plist:+,}$(keyseal_json_str "$line")"; done <<<"$optin_problems"
-  optin_json="{\"ok\":$optin_ok,\"problems\":[$plist]}"
-fi
-if has "$key" && ! has "$optin"; then contra+=("$slot.key without an opt-in record"); fi
-if has "$K/$slot.cred.staging" || has "$K/$slot.pub.staging" || has "$K/$slot.unsealed-optin.staging"; then
-  contra+=("staging file present")
-fi
-if ((${#contra[@]} == 0)); then
-  if ! has "$cred" && ! has "$pub" && ! has "$key" && ! has "$optin"; then
-    exit2+=(nothing_committed)
-  elif has "$key"; then
-    # The loader's own predicate (optin.sh): what it would refuse to load is a contradiction.
-    if problems=$(keyseal_unsealed_check "$slot"); then mode=unsealed
-    else contra+=("the unsealed slot does not verify: ${problems//$'\n'/; }")
-    fi
-  elif ! has "$cred"; then contra+=("blob missing")
-  elif [[ -z $pin ]]; then contra+=("pin missing or malformed")
-  else
-    drc=0
-    derived=$(keyseal_derive_pub "$slot") || drc=$?
-    if ((drc == 0)); then
-      if [[ $derived == "$pin" ]]; then mode=sealed; else contra+=("pin does not derive from the blob"); fi
-    elif [[ $outcome == capable ]]; then
-      contra+=("the blob does not decrypt to a key, though sealing works here")
+boot_id=$(</proc/sys/kernel/random/boot_id)
+machine_id=$(keyseal_machine_id) || machine_id=
+seam_j=$(keyseal_seam_json)
+host_j=$(keyseal_json_str "$(uname -n)")
+uid_j=$(keyseal_uid)
+machine_id_j=$(str_or_null "$machine_id")
+boot_id_j=$(keyseal_json_str "$boot_id")
+
+stale_temp=$(keyseal_scan_stale_temp)
+keyseal_scan_roots
+scope_sha_j=$(keyseal_json_str "$(keyseal_sha256_str "$(keyseal_scan_scope_json)")")
+scanner_sha_j=$(str_or_null "$(keyseal_files_sha "$here" lib.sh status.sh || true)")
+
+linger=$(keyseal_linger)
+if [[ $linger == yes ]]; then ok_linger=true detail_linger=""; else ok_linger=false detail_linger="linger is $linger"; fi
+
+# ---- phase A: checks 1-5 and the cache judge, per slot ------------------------------------------
+
+declare -a A_MODE=() A_PIN=() A_EXEMPT=() A_EXEMPT_J=() A_PINSHA_J=() A_BLOBSHA_J=()
+declare -a A_OK_COMMITTED=() A_DET_COMMITTED=()
+declare -a A_OK_CHAIN=() A_DET_CHAIN=() A_CHAIN_LEGACY=() A_LEGACY=() A_LOADER_STATE=() A_LOADER_REC=() A_LOADER_RUN=()
+declare -a A_OK_UNITS=() A_DET_UNITS=()
+declare -a A_OK_AGENT=() A_DET_AGENT=() A_AGENT_EMPTY=()
+declare -a A_OPTIN_J=() A_UPGRADE=() A_EXIT2=()
+declare -a A_CACHE_TOKEN=() A_CACHE_STATE=() A_CACHE_REASON=() A_CACHE_SCAN=() A_CACHE_SCANNED_AT=() A_CACHE_DURATION=() A_CACHE_LAST=()
+declare -a A_NEEDS_SCAN=()
+
+for i in "${!slots[@]}"; do
+  slot=${slots[i]}
+  cred=$K/$slot.cred pub=$K/$slot.pub key=$K/$slot.key optin=$K/$slot.unsealed-optin
+  base_unit=$KEYSEAL_BASE_UNIT@$slot.service
+  load_unit=$KEYSEAL_LOAD_UNIT@$slot.service
+
+  # 1 committed: the provenance table. The pin is read whatever the provenance, so a
+  # contradiction still scans for copies of the pinned key (review round 1, Opus S3).
+  contra=()
+  mode=undetermined optin_json=null
+  pin=$(keyseal_read_pin "$pub") || pin=
+  has "$cred" && has "$key" && contra+=("a sealed blob and an unsealed key are both present")
+  has "$cred" && has "$optin" && contra+=("an opt-in record beside a sealed blob")
+  has "$optin" && ! has "$key" && contra+=("an opt-in record without $slot.key")
+  if has "$optin"; then
+    optin_ok=true
+    optin_problems=$(keyseal_optin_check "$slot") || optin_ok=false
+    plist=
+    while IFS= read -r line; do [[ -n $line ]] && plist+="${plist:+,}$(keyseal_json_str "$line")"; done <<<"$optin_problems"
+    optin_json="{\"ok\":$optin_ok,\"problems\":[$plist]}"
+  fi
+  if has "$key" && ! has "$optin"; then contra+=("$slot.key without an opt-in record"); fi
+  if has "$K/$slot.cred.staging" || has "$K/$slot.pub.staging" || has "$K/$slot.unsealed-optin.staging"; then
+    contra+=("staging file present")
+  fi
+  exit2_i=()
+  if ((${#contra[@]} == 0)); then
+    if ! has "$cred" && ! has "$pub" && ! has "$key" && ! has "$optin"; then
+      exit2_i+=(nothing_committed)
+    elif has "$key"; then
+      # The loader's own predicate (optin.sh): what it would refuse to load is a contradiction.
+      if problems=$(keyseal_unsealed_check "$slot"); then mode=unsealed
+      else contra+=("the unsealed slot does not verify: ${problems//$'\n'/; }")
+      fi
+    elif ! has "$cred"; then contra+=("blob missing")
+    elif [[ -z $pin ]]; then contra+=("pin missing or malformed")
     else
-      exit2+=(undeterminable)
+      drc=0
+      derived=$(keyseal_derive_pub "$slot") || drc=$?
+      if ((drc == 0)); then
+        if [[ $derived == "$pin" ]]; then mode=sealed; else contra+=("pin does not derive from the blob"); fi
+      elif [[ $outcome == capable ]]; then
+        contra+=("the blob does not decrypt to a key, though sealing works here")
+      else
+        exit2_i+=(undeterminable)
+      fi
     fi
   fi
-fi
-if ((${#contra[@]})); then
-  mode=contradiction ok[committed]=false
-  detail[committed]=$(printf '%s; ' "${contra[@]}")
-  detail[committed]=${detail[committed]%; }
-else
-  ok[committed]=true detail[committed]=""
-fi
+  if ((${#contra[@]})); then
+    mode=contradiction ok_committed_i=false
+    detail_committed_i=$(printf '%s; ' "${contra[@]}")
+    detail_committed_i=${detail_committed_i%; }
+  else
+    ok_committed_i=true detail_committed_i=""
+  fi
 
-# 2 chain, including the slot's loader version
-if keyseal_chain_check "$slot" "$here"; then ok[chain]=true detail[chain]=""
-else ok[chain]=false detail[chain]=${KEYSEAL_CHAIN_PROBLEMS%$'\n'}
-fi
-legacy=no
-if [[ $KEYSEAL_CHAIN_LEGACY == yes ]] || keyseal_legacy_present; then legacy=yes exit2+=(legacy_loader_present); fi
-if [[ $KEYSEAL_CHAIN_LEGACY == no ]]; then
-  case $KEYSEAL_LOADER_STATE in
-    outdated) exit2+=(loader_outdated) ;;
-    unrecorded) exit2+=(loader_unrecorded) ;;
+  # 2 chain, including the slot's loader version
+  if keyseal_chain_check "$slot" "$here"; then ok_chain_i=true detail_chain_i=""
+  else ok_chain_i=false detail_chain_i=${KEYSEAL_CHAIN_PROBLEMS%$'\n'}
+  fi
+  legacy_i=no
+  if [[ $KEYSEAL_CHAIN_LEGACY == yes ]] || keyseal_legacy_present; then legacy_i=yes exit2_i+=(legacy_loader_present); fi
+  if [[ $KEYSEAL_CHAIN_LEGACY == no ]]; then
+    case $KEYSEAL_LOADER_STATE in
+      outdated) exit2_i+=(loader_outdated) ;;
+      unrecorded) exit2_i+=(loader_unrecorded) ;;
+    esac
+  fi
+
+  # 3 units
+  sub=$("$SYSTEMCTL" --user show -p SubState "$load_unit" 2>/dev/null || true)
+  if [[ $(state is-enabled "$base_unit") == enabled && $(state is-enabled "$load_unit") == enabled &&
+    $(state is-active "$base_unit") == active && $(state is-active "$load_unit") == active && $sub == SubState=exited ]]; then
+    ok_units_i=true detail_units_i=""
+  else
+    ok_units_i=false detail_units_i="base $(state is-enabled "$base_unit")/$(state is-active "$base_unit"), loader $(state is-enabled "$load_unit")/$(state is-active "$load_unit") ${sub#SubState=}"
+  fi
+
+  # 4 agent: exactly one identity, and it is the pin. `empty` is told apart from a wrong or
+  # extra key: an empty agent can be the CONSEQUENCE of an exit-2 cause (below).
+  agent_empty=no
+  if [[ -n $pin ]] && keyseal_agent_holds_exactly "$slot" "$pin"; then ok_agent_i=true detail_agent_i=""
+  else
+    held=$(keyseal_agent_keys "$slot" 2>/dev/null) || held="?"
+    if [[ -z $held ]]; then agent_empty=yes; fi
+    nheld=$(printf '%s' "$held" | "$KEYSEAL_BIN_GREP" -c . || true)
+    [[ $held == "?" ]] && nheld=
+    ok_agent_i=false detail_agent_i="the slot agent holds ${nheld:-an unreadable set of} identities, not exactly the pin"
+  fi
+
+  # 5 linger (shared, host-level), and capability for the measured mode
+  [[ $linger == yes ]] || exit2_i+=(linger_off)
+  upgrade_i=no
+  case $mode in
+    sealed) [[ $outcome == capable ]] || exit2_i+=("capability_$outcome") ;;
+    unsealed)
+      if [[ $outcome == capable ]]; then upgrade_i=yes exit2_i+=(upgrade_available)
+      elif [[ $outcome != incapable ]]; then exit2_i+=("capability_$outcome")
+      fi
+      ;;
   esac
-fi
 
-# 3 units
-state() { "$SYSTEMCTL" --user "$1" "$2" 2>/dev/null || true; }
-sub=$("$SYSTEMCTL" --user show -p SubState "$load_unit" 2>/dev/null || true)
-if [[ $(state is-enabled "$base_unit") == enabled && $(state is-enabled "$load_unit") == enabled &&
-  $(state is-active "$base_unit") == active && $(state is-active "$load_unit") == active && $sub == SubState=exited ]]; then
-  ok[units]=true detail[units]=""
-else
-  ok[units]=false detail[units]="base $(state is-enabled "$base_unit")/$(state is-active "$base_unit"), loader $(state is-enabled "$load_unit")/$(state is-active "$load_unit") ${sub#SubState=}"
-fi
+  pin_sha=null blob_sha=null
+  [[ -n $pin ]] && pin_sha=$(keyseal_json_str "$(keyseal_sha256_str "$pin")")
+  [[ -f $cred ]] && blob_sha=$(keyseal_json_str "$(keyseal_sha256_file "$cred")")
 
-# 4 agent: exactly one identity, and it is the pin. `empty` is told apart from a wrong or
-# extra key: an empty agent can be the CONSEQUENCE of an exit-2 cause (below).
-agent_empty=no
-if [[ -n $pin ]] && keyseal_agent_holds_exactly "$slot" "$pin"; then ok[agent]=true detail[agent]=""
-else
-  held=$(keyseal_agent_keys "$slot" 2>/dev/null) || held="?"
-  if [[ -z $held ]]; then agent_empty=yes; fi
-  n=$(printf '%s' "$held" | "$KEYSEAL_BIN_GREP" -c . || true)
-  [[ $held == "?" ]] && n=
-  ok[agent]=false detail[agent]="the slot agent holds ${n:-an unreadable set of} identities, not exactly the pin"
+  # 6 scan setup: the unsealed slot's own key file is the one exemption. Judge the cache now (IF-
+  # 552-2); the walk, shared across every slot needing one, runs once after this loop.
+  exempt=
+  [[ $mode == unsealed ]] && exempt=$key
+  exempt_j=$(if [[ -n $exempt ]]; then keyseal_json_str "$(keyseal_sha256_str "$exempt")"; else printf null; fi)
+  KEYSEAL_INPUT=(
+    [seam]=$seam_j
+    [uid]=$uid_j
+    [machine_id]=$machine_id_j
+    [slot]=$(keyseal_json_str "$slot")
+    [mode]=$(keyseal_json_str "$mode")
+    [exempt]=$exempt_j
+    [pin_sha256]=$pin_sha
+    [blob_sha256]=$blob_sha
+    [scope_sha256]=$scope_sha_j
+    [scanner_sha256]=$scanner_sha_j
+  )
+  keyseal_cache_read "$slot" "$scan_cache"
+
+  needs_scan=no
+  if [[ $KEYSEAL_CACHE_STATE != hit && $scan_cache != only ]]; then needs_scan=yes; fi
+  [[ $KEYSEAL_CACHE_STATE != hit && $scan_cache == only ]] && exit2_i+=(scan_not_cached)
+
+  A_MODE[i]=$mode A_PIN[i]=$pin A_EXEMPT[i]=$exempt A_EXEMPT_J[i]=$exempt_j
+  A_PINSHA_J[i]=$pin_sha A_BLOBSHA_J[i]=$blob_sha
+  A_OK_COMMITTED[i]=$ok_committed_i A_DET_COMMITTED[i]=$detail_committed_i
+  A_OK_CHAIN[i]=$ok_chain_i A_DET_CHAIN[i]=$detail_chain_i
+  A_CHAIN_LEGACY[i]=$KEYSEAL_CHAIN_LEGACY A_LEGACY[i]=$legacy_i
+  A_LOADER_STATE[i]=$KEYSEAL_LOADER_STATE A_LOADER_REC[i]=$KEYSEAL_LOADER_RECORDED A_LOADER_RUN[i]=$KEYSEAL_LOADER_RUNNING
+  A_OK_UNITS[i]=$ok_units_i A_DET_UNITS[i]=$detail_units_i
+  A_OK_AGENT[i]=$ok_agent_i A_DET_AGENT[i]=$detail_agent_i A_AGENT_EMPTY[i]=$agent_empty
+  A_OPTIN_J[i]=$optin_json A_UPGRADE[i]=$upgrade_i
+  A_EXIT2[i]="${exit2_i[*]-}"
+  A_CACHE_TOKEN[i]=$KEYSEAL_CACHE_TOKEN A_CACHE_STATE[i]=$KEYSEAL_CACHE_STATE A_CACHE_REASON[i]=$KEYSEAL_CACHE_REASON
+  A_CACHE_SCAN[i]=$KEYSEAL_CACHE_SCAN A_CACHE_SCANNED_AT[i]=$KEYSEAL_CACHE_SCANNED_AT
+  A_CACHE_DURATION[i]=$KEYSEAL_CACHE_DURATION A_CACHE_LAST[i]=$KEYSEAL_CACHE_LAST
+  A_NEEDS_SCAN[i]=$needs_scan
+done
+
+# ---- the ONE shared walk, for every slot phase A marked needs_scan=yes --------------------------
+
+scan_idx=()
+for i in "${!slots[@]}"; do
+  [[ ${A_NEEDS_SCAN[i]} == yes ]] && scan_idx+=("$i")
+done
+
+scan_start=0 scan_duration=0
+if ((${#scan_idx[@]})); then
+  KEYSEAL_SCAN_PINS=() KEYSEAL_SCAN_EXEMPTS=()
+  for k in "${!scan_idx[@]}"; do
+    i=${scan_idx[k]}
+    KEYSEAL_SCAN_PINS[k]=${A_PIN[i]}
+    KEYSEAL_SCAN_EXEMPTS[k]=${A_EXEMPT[i]}
+  done
+  # scanned_at is the scan's START: a file created after it may be missed.
+  scan_start=$(keyseal_now) || scan_start=0
+  for k in "${!scan_idx[@]}"; do
+    i=${scan_idx[k]}
+    if ((n > 1)); then
+      printf 'status: scan: starting (%s:%s) slot=%s\n' "${A_CACHE_STATE[i]}" "${A_CACHE_REASON[i]}" "${slots[i]}" >&2
+    else
+      printf 'status: scan: starting (%s:%s)\n' "${A_CACHE_STATE[i]}" "${A_CACHE_REASON[i]}" >&2
+    fi
+  done
+  keyseal_scan_run "$scan_timeout"
+  scan_end=$(keyseal_now) || scan_end=$scan_start
+  scan_duration=$((scan_end - scan_start))
+  ((scan_duration >= 0)) || scan_duration=0
 fi
 
-# 5 linger, and capability for the measured mode
-linger=$(keyseal_linger)
-if [[ $linger == yes ]]; then ok[linger]=true detail[linger]=""; else ok[linger]=false detail[linger]="linger is $linger"; exit2+=(linger_off); fi
-upgrade=no
-case $mode in
-  sealed) [[ $outcome == capable ]] || exit2+=("capability_$outcome") ;;
-  unsealed)
-    if [[ $outcome == capable ]]; then upgrade=yes exit2+=(upgrade_available)
-    elif [[ $outcome != incapable ]]; then exit2+=("capability_$outcome")
+# ---- phase B: interpret the scan, commit the cache and emit, per slot ---------------------------
+
+saw1=no saw2=no
+for i in "${!slots[@]}"; do
+  slot=${slots[i]} harness=${harness_of[i]} mode=${A_MODE[i]}
+  read -ra exit2_i <<<"${A_EXIT2[i]:-}"
+  cache_read_i="${A_CACHE_STATE[i]}:${A_CACHE_REASON[i]}"
+  cache_state=${A_CACHE_STATE[i]} cache_reason=${A_CACHE_REASON[i]}
+  base_unit=$KEYSEAL_BASE_UNIT@$slot.service
+  load_unit=$KEYSEAL_LOAD_UNIT@$slot.service
+
+  KEYSEAL_INPUT=(
+    [seam]=$seam_j
+    [uid]=$uid_j
+    [machine_id]=$machine_id_j
+    [slot]=$(keyseal_json_str "$slot")
+    [mode]=$(keyseal_json_str "$mode")
+    [exempt]=${A_EXEMPT_J[i]}
+    [pin_sha256]=${A_PINSHA_J[i]}
+    [blob_sha256]=${A_BLOBSHA_J[i]}
+    [scope_sha256]=$scope_sha_j
+    [scanner_sha256]=$scanner_sha_j
+  )
+
+  scan_source=none scan_scanned_at=null scan_age=null scan_dur=null scan_core=
+  scan_judged=yes scan_timed_out=no detail_scan=""
+  if [[ $cache_state == hit ]]; then
+    scan_source=cached scan_core=${A_CACHE_SCAN[i]}
+    scan_now=$(keyseal_now) || scan_now=${A_CACHE_SCANNED_AT[i]}
+    scan_scanned_at=$(keyseal_json_str "$(keyseal_iso "${A_CACHE_SCANNED_AT[i]}")")
+    scan_age=$((scan_now - A_CACHE_SCANNED_AT[i]))
+    scan_dur=${A_CACHE_DURATION[i]}
+  elif [[ ${A_NEEDS_SCAN[i]} == no ]]; then
+    scan_judged=no
+    detail_scan="not judged: no valid scan cache ($cache_state:$cache_reason)"
+  else
+    case $KEYSEAL_SCAN_OUTCOME in
+      ok)
+        k=-1
+        for kk in "${!scan_idx[@]}"; do [[ ${scan_idx[kk]} == "$i" ]] && k=$kk && break; done
+        scan_source=fresh scan_core=$(keyseal_scan_core_json "$k")
+        scan_scanned_at=$(keyseal_json_str "$(keyseal_iso "$scan_start")") scan_age=$scan_duration
+        scan_dur=$scan_duration
+        ;;
+      timed_out)
+        scan_judged=no scan_timed_out=yes
+        detail_scan="not judged: the scan gave up after $scan_timeout s (scan_timed_out)"
+        exit2_i+=(scan_timed_out)
+        cache_state=not_written cache_reason=timed_out
+        ;;
+      *)
+        detail_scan="the scan did not run to completion"
+        cache_state=not_written cache_reason=incomplete
+        ;;
+    esac
+  fi
+  if [[ -n $scan_core ]]; then
+    if [[ $scan_core == *'"plaintext_matches":[]'* ]]; then ok_scan=true detail_scan=""
+    else ok_scan=false detail_scan="plaintext copy of the slot key found"
+    fi
+  else
+    ok_scan=false
+  fi
+  # A match is never cached: it writes a tombstone. Only a clean, completed, fresh scan commits.
+  if [[ $scan_source == fresh ]]; then
+    KEYSEAL_CACHE_TOKEN=${A_CACHE_TOKEN[i]}
+    if [[ $ok_scan == true ]]; then keyseal_cache_commit_clean "$slot" "$scan_start" "$scan_duration" "$scan_core"
+    else keyseal_cache_commit_tombstone "$slot" "$harness"
+    fi
+    cache_state=$KEYSEAL_CACHE_STATE cache_reason=$KEYSEAL_CACHE_REASON
+  fi
+
+  if [[ $scan_source == fresh ]]; then
+    n_matches=0 n_candidates=0
+    [[ $scan_core =~ \"candidates\":([0-9]+) ]] && n_candidates=${BASH_REMATCH[1]}
+    [[ $ok_scan == true ]] || n_matches=$(printf '%s' "$scan_core" | keyseal_node count-matches 2>/dev/null || printf '?')
+    if ((n > 1)); then
+      printf 'status: scan: done in %s s (%s folders, %s candidates, %s matches) slot=%s\n' "$scan_duration" "$KEYSEAL_SCAN_FOLDERS" "$n_candidates" "$n_matches" "$slot" >&2
+    else
+      printf 'status: scan: done in %s s (%s folders, %s candidates, %s matches)\n' "$scan_duration" "$KEYSEAL_SCAN_FOLDERS" "$n_candidates" "$n_matches" >&2
+    fi
+  elif [[ $scan_source == none && $scan_judged == yes || $scan_timed_out == yes ]]; then
+    if ((n > 1)); then
+      printf 'status: scan: done in %s s (%s folders) slot=%s: %s\n' "$scan_duration" "$KEYSEAL_SCAN_FOLDERS" "$slot" "$detail_scan" >&2
+    else
+      printf 'status: scan: done in %s s (%s folders): %s\n' "$scan_duration" "$KEYSEAL_SCAN_FOLDERS" "$detail_scan" >&2
     fi
-    ;;
-esac
+  fi
 
-# 6 scan: the unsealed slot's own key file is the one exemption
-exempt=
-[[ $mode == unsealed ]] && exempt=$key
-if scan=$(keyseal_scan "$pin" "$exempt"); then
-  if [[ $scan == *'"plaintext_matches":[]'* ]]; then ok[scan]=true detail[scan]=""
-  else ok[scan]=false detail[scan]="plaintext copy of the slot key found"
+  cache_last=null
+  [[ -n ${A_CACHE_LAST[i]} ]] && cache_last=$(keyseal_json_str "$(keyseal_iso "${A_CACHE_LAST[i]}")")
+  scan_meta="\"source\":\"$scan_source\",\"scanned_at\":$scan_scanned_at,\"age_s\":$scan_age,\"duration_s\":$scan_dur,\"inputs\":$(keyseal_cache_inputs_json),\"stale_temp\":$stale_temp,\"cache\":{\"mode\":\"$scan_cache\",\"state\":\"$cache_state\",\"reason\":$(str_or_null "$cache_reason"),\"read\":$(keyseal_json_str "$cache_read_i"),\"last_scanned_at\":$cache_last}"
+  if [[ -n $scan_core ]]; then scan_json=$(keyseal_scan_with_headers "${scan_core%\}},$scan_meta}")
+  else scan_json="{\"roots\":$(keyseal_json_list ${KEYSEAL_ROOTS[@]+"${KEYSEAL_ROOTS[@]}"}),\"roots_skipped\":$KEYSEAL_ROOTS_SKIPPED_JSON,$scan_meta}"
   fi
-else
-  scan='{}' ok[scan]=false detail[scan]="the scan did not run to completion"
-fi
 
-# Nothing committed is 2 by the provenance table: there is no unit, agent or chain to judge.
-hard=(committed chain units agent scan)
-[[ ${exit2[*]} == *nothing_committed* ]] && hard=(committed scan)
-# committed, chain and scan are always hard. A loader that could not run, or an agent it left
-# EMPTY, is the consequence of a sealed slot's capability loss or an undeterminable blob, so it
-# is 2 while one is present (review round 1, Opus B2). A wrong or extra key stays 1.
-soft=no
-# Only causes that EXPLAIN an empty agent (review round 2, Opus N1): a sealed slot whose sealing
-# is gone, or a blob that could not be read. Linger off does not (status needs a running
-# manager), and an unsealed loader never uses sealing.
-for r in "${exit2[@]}"; do
-  case $r in
-    undeterminable) soft=yes ;;
-    # error or incapable: the decrypt itself is gone. incapable-for-keyslot is linger or the ssh
-    # tools, which alone do not stop a decrypt; but probe.sh reports a lost systemd-creds on a
-    # no-linger host as incapable-for-keyslot too, so it counts when the round trip failed.
-    capability_error | capability_incapable) [[ $mode == sealed ]] && soft=yes ;;
-    capability_incapable-for-keyslot) [[ $mode == sealed && $round_trip != equal ]] && soft=yes ;;
-  esac
-done
-if [[ $soft == yes ]]; then
-  still_hard=()
+  # Nothing committed is 2 by the provenance table: there is no unit, agent or chain to judge.
+  hard=(committed chain units agent scan)
+  [[ "${exit2_i[*]-}" == *nothing_committed* ]] && hard=(committed scan)
+  # A scan that was not judged (no valid cache under `only`, or the deadline) is 2, never 1.
+  if [[ $scan_judged == no ]]; then
+    judged=()
+    for c in "${hard[@]}"; do [[ $c == scan ]] || judged+=("$c"); done
+    hard=("${judged[@]}")
+  fi
+  soft=no
+  for r in "${exit2_i[@]}"; do
+    case $r in
+      undeterminable) soft=yes ;;
+      capability_error | capability_incapable) [[ $mode == sealed ]] && soft=yes ;;
+      capability_incapable-for-keyslot) [[ $mode == sealed && $round_trip != equal ]] && soft=yes ;;
+    esac
+  done
+  if [[ $soft == yes ]]; then
+    still_hard=()
+    for c in "${hard[@]}"; do
+      case $c in
+        agent) [[ ${A_OK_AGENT[i]} == true || ${A_AGENT_EMPTY[i]} == yes ]] || still_hard+=(agent) ;;
+        units)
+          [[ ${A_OK_UNITS[i]} == true ]] ||
+            { [[ $(state is-enabled "$base_unit") == enabled && $(state is-enabled "$load_unit") == enabled ]] || still_hard+=(units); }
+          ;;
+        *) still_hard+=("$c") ;;
+      esac
+    done
+    hard=("${still_hard[@]}")
+  fi
+  rc=0
   for c in "${hard[@]}"; do
     case $c in
-      agent) [[ ${ok[agent]} == true || $agent_empty == yes ]] || still_hard+=(agent) ;;
-      units)
-        [[ ${ok[units]} == true ]] ||
-          { [[ $(state is-enabled "$base_unit") == enabled && $(state is-enabled "$load_unit") == enabled ]] || still_hard+=(units); }
-        ;;
-      *) still_hard+=("$c") ;;
+      committed) v=${A_OK_COMMITTED[i]} ;;
+      chain) v=${A_OK_CHAIN[i]} ;;
+      units) v=${A_OK_UNITS[i]} ;;
+      agent) v=${A_OK_AGENT[i]} ;;
+      scan) v=$ok_scan ;;
     esac
+    [[ $v == true ]] || rc=1
   done
-  hard=("${still_hard[@]}")
-fi
-rc=0
-for c in "${hard[@]}"; do [[ ${ok[$c]} == true ]] || rc=1; done
-if ((rc == 0 && ${#exit2[@]})); then rc=2; fi
+  if ((rc == 0 && ${#exit2_i[@]})); then rc=2; fi
+  ((rc == 1)) && saw1=yes
+  ((rc == 2)) && saw2=yes
 
-pin_sha=null blob_sha=null
-[[ -n $pin ]] && pin_sha=$(keyseal_json_str "$(keyseal_sha256_str "$pin")")
-[[ -f $cred ]] && blob_sha=$(keyseal_json_str "$(keyseal_sha256_file "$cred")")
-boot_id=$(</proc/sys/kernel/random/boot_id)
-machine_id=$(keyseal_machine_id) || machine_id=
-bool() { if [[ $1 == yes ]]; then printf true; else printf false; fi; }
-reasons=
-for r in "${exit2[@]}"; do reasons+="${reasons:+,}$(keyseal_json_str "$r")"; done
-outdated=no
-[[ ${exit2[*]} == *loader_outdated* ]] && outdated=yes
-str_or_null() { if [[ -n $1 ]]; then keyseal_json_str "$1"; else printf null; fi; }
+  outdated_i=no
+  [[ "${exit2_i[*]-}" == *loader_outdated* ]] && outdated_i=yes
+  reasons=
+  for r in "${exit2_i[@]}"; do reasons+="${reasons:+,}$(keyseal_json_str "$r")"; done
 
-if [[ $json == yes ]]; then
-  checks=
-  for c in committed chain units agent linger scan; do
-    checks+="${checks:+,}\"$c\":{\"ok\":${ok[$c]},\"detail\":$(keyseal_json_str "${detail[$c]}")}"
-  done
-  printf '{"tool":"status","seam":%s,"host":%s,"uid":%s,"machine_id":%s,"harness":%s,"slot":%s,"mode":%s,"boot_id":%s,"pin_sha256":%s,"blob_sha256":%s,"capability_probe_exit":%s,"probe_outcome":%s,"optin":%s,"loader":{"recorded_sha256":%s,"running_sha256":%s,"state":%s},"upgrade_available":%s,"loader_outdated":%s,"legacy_loader_present":%s,"exit2_reasons":[%s],"checks":{%s},"scan":%s,"exit":%s}\n' \
-    "$(keyseal_seam_json)" "$(keyseal_json_str "$(uname -n)")" "$(keyseal_uid)" "$(str_or_null "$machine_id")" \
-    "$(keyseal_json_str "$harness")" "$(keyseal_json_str "$slot")" "$(keyseal_json_str "$mode")" \
-    "$(keyseal_json_str "$boot_id")" "$pin_sha" "$blob_sha" "$probe_rc" "$(keyseal_json_str "$outcome")" "$optin_json" \
-    "$(str_or_null "$KEYSEAL_LOADER_RECORDED")" "$(str_or_null "$KEYSEAL_LOADER_RUNNING")" \
-    "$(keyseal_json_str "$([[ $KEYSEAL_CHAIN_LEGACY == yes ]] && echo legacy || echo "$KEYSEAL_LOADER_STATE")")" \
-    "$(bool "$upgrade")" "$(bool "$outdated")" "$(bool "$legacy")" "$reasons" "$checks" "$scan" "$rc"
-else
-  for c in committed chain units agent linger scan; do
-    printf '%-9s %s %s\n' "$c" "$([[ ${ok[$c]} == true ]] && echo ok || echo FAIL)" "${detail[$c]}"
-  done
-  printf 'mode      %s\n' "$mode"
-  ((${#exit2[@]})) && printf 'exit 2    %s\n' "${exit2[*]}"
-  printf 'status: exit %s (seam=%s)\n' "$rc" "$(keyseal_seam_json)"
+  if [[ $json == yes ]]; then
+    checks=
+    for c in committed chain units agent linger scan; do
+      case $c in
+        committed) cok=${A_OK_COMMITTED[i]} cdet=${A_DET_COMMITTED[i]} ;;
+        chain) cok=${A_OK_CHAIN[i]} cdet=${A_DET_CHAIN[i]} ;;
+        units) cok=${A_OK_UNITS[i]} cdet=${A_DET_UNITS[i]} ;;
+        agent) cok=${A_OK_AGENT[i]} cdet=${A_DET_AGENT[i]} ;;
+        linger) cok=$ok_linger cdet=$detail_linger ;;
+        scan) cok=$ok_scan cdet=$detail_scan ;;
+      esac
+      checks+="${checks:+,}\"$c\":{\"ok\":$cok,\"detail\":$(keyseal_json_str "$cdet")}"
+    done
+    printf '{"tool":"status","seam":%s,"host":%s,"uid":%s,"machine_id":%s,"harness":%s,"slot":%s,"mode":%s,"boot_id":%s,"pin_sha256":%s,"blob_sha256":%s,"capability_probe_exit":%s,"probe_outcome":%s,"optin":%s,"loader":{"recorded_sha256":%s,"running_sha256":%s,"state":%s},"upgrade_available":%s,"loader_outdated":%s,"legacy_loader_present":%s,"exit2_reasons":[%s],"checks":{%s},"scan":%s,"exit":%s}\n' \
+      "$seam_j" "$host_j" "$uid_j" "$machine_id_j" \
+      "$(keyseal_json_str "$harness")" "$(keyseal_json_str "$slot")" "$(keyseal_json_str "$mode")" \
+      "$boot_id_j" "${A_PINSHA_J[i]}" "${A_BLOBSHA_J[i]}" "$probe_rc" "$(keyseal_json_str "$outcome")" "${A_OPTIN_J[i]}" \
+      "$(str_or_null "${A_LOADER_REC[i]}")" "$(str_or_null "${A_LOADER_RUN[i]}")" \
+      "$(keyseal_json_str "$([[ ${A_CHAIN_LEGACY[i]} == yes ]] && echo legacy || echo "${A_LOADER_STATE[i]}")")" \
+      "$(bool "${A_UPGRADE[i]}")" "$(bool "$outdated_i")" "$(bool "${A_LEGACY[i]}")" "$reasons" "$checks" "$scan_json" "$rc"
+  else
+    for c in committed chain units agent linger scan; do
+      case $c in
+        committed) cok=${A_OK_COMMITTED[i]} cdet=${A_DET_COMMITTED[i]} ;;
+        chain) cok=${A_OK_CHAIN[i]} cdet=${A_DET_CHAIN[i]} ;;
+        units) cok=${A_OK_UNITS[i]} cdet=${A_DET_UNITS[i]} ;;
+        agent) cok=${A_OK_AGENT[i]} cdet=${A_DET_AGENT[i]} ;;
+        linger) cok=$ok_linger cdet=$detail_linger ;;
+        scan) cok=$ok_scan cdet=$detail_scan ;;
+      esac
+      printf '%-9s %s %s\n' "$c" "$([[ $cok == true ]] && echo ok || echo FAIL)" "$cdet"
+    done
+    printf 'mode      %s\n' "$mode"
+    ((${#exit2_i[@]})) && printf 'exit 2    %s\n' "${exit2_i[*]}"
+    printf 'status: exit %s (seam=%s)\n' "$rc" "$seam_j"
+  fi
+done
+
+if [[ $saw1 == yes ]]; then exit 1
+elif [[ $saw2 == yes ]]; then exit 2
+else exit 0
 fi
-exit "$rc"