sluice

#!/usr/bin/env bash
# sluice - run any project in a sandboxed, egress-firewalled container.
# Drop a sluice.config.sh in a project (or run `sluice` to scaffold one); `sluice help` lists the
# commands. Per-project image/container, auto-rebuilt when the config or core changes.
#
# GENERATED FILE - do not edit directly. Assembled from src/*.sh by `make build`
# (the slices concatenate in order; a CI gate fails if this file drifts from src/).
set -euo pipefail

# resolve our install dir (bin/sluice is symlinked onto PATH; follow the chain)
SELF="$0"
while [ -h "$SELF" ]; do
  link="$(readlink "$SELF")"
  case "$link" in /*) SELF="$link";; *) SELF="$(dirname "$SELF")/$link";; esac
done
ROOT="$(cd "$(dirname "$SELF")/.." && pwd)"
CORE="$ROOT/core"

die() { echo "${E_RED:-}[sluice]${E_RST:-} $*" >&2; exit 1; }

# minimal JSON emit (host jq is not assumed; fields here are short/flat)
# Escape a string for a JSON value: backslash + doublequote, flatten tab/newline, then DELETE every
# remaining C0 control byte + DEL (ESC/BEL/OSC) so a box-controlled value (e.g. a logged SNI) can't
# smuggle a terminal-escape sequence through `--json`/persisted receipts when they're later cat'd.
_json_esc() { local s="$1"; s="${s//\\/\\\\}"; s="${s//\"/\\\"}"; s="${s//$'\t'/ }"; s="${s//$'\n'/ }"; s="${s//$'\r'/}"; printf '%s' "$s" | LC_ALL=C tr -d '\000-\037\177'; }
# Sanitize a box-controlled string for safe display on a TERMINAL: flatten whitespace and DELETE every
# C0 control byte + DEL (ESC/BEL/OSC). Unlike _json_esc it leaves \ and " intact (this is for humans, not
# JSON), so a crafted filename / symlink target can't inject escapes or forge a line of `doctor` output.
_term_esc() { local s="$1"; s="${s//$'\t'/ }"; s="${s//$'\n'/ }"; s="${s//$'\r'/ }"; printf '%s' "$s" | LC_ALL=C tr -d '\000-\037\177'; }
# Emit a JSON array of strings from newline-separated stdin (blank lines skipped; a final line
# without a trailing newline still counts - base_domains emits one).
_json_arr() { local first=1 line; printf '['; while IFS= read -r line || [ -n "$line" ]; do [ -n "$line" ] || continue; [ "$first" = 1 ] && first=0 || printf ','; printf '"%s"' "$(_json_esc "$line")"; done; printf ']'; }

# Home-relative display form of a path (~/...), for HUMAN output only - ls already renders paths
# this way; doctor/learn share it via this helper. JSON output keeps raw absolute paths.
_tilde() { case "$1" in "$HOME"/*) printf '~%s' "${1#"$HOME"}";; "$HOME") printf '~';; *) printf '%s' "$1";; esac; }

# color: gated on a stdout TTY + NO_COLOR, so piped/redirected output stays plain ASCII
# (the --json paths print no color regardless; the TTY gate also blanks these when piped.)
if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
  C_GRN=$'\033[32m'; C_RED=$'\033[31m'; C_YEL=$'\033[33m'; C_DIM=$'\033[2m'; C_BLD=$'\033[1m'; C_RST=$'\033[0m'
else
  C_GRN=''; C_RED=''; C_YEL=''; C_DIM=''; C_BLD=''; C_RST=''
fi
# Parallel stderr-gated set: lines printed to >&2 use E_* (not C_*) so color tracks fd 2's TTY - no
# escape leak into a redirected stderr, and color still shows when only stderr is a terminal.
if [ -t 2 ] && [ -z "${NO_COLOR:-}" ]; then
  E_GRN=$'\033[32m'; E_RED=$'\033[31m'; E_YEL=$'\033[33m'; E_DIM=$'\033[2m'; E_RST=$'\033[0m'
else
  E_GRN=''; E_RED=''; E_YEL=''; E_DIM=''; E_RST=''
fi

# version + help
SLUICE_VERSION="0.9.0"   # fallback when not a git checkout
sluice_version() {       # git tag if $ROOT is our own checkout, else the baked constant
  local v
  if [ -e "$ROOT/.git" ] && v="$(git -C "$ROOT" describe --tags --always --dirty 2>/dev/null)" && [ -n "$v" ]; then
    printf '%s' "${v#v}"
  else
    printf '%s' "$SLUICE_VERSION"
  fi
}
# Passive "you're behind" notice for `sluice version`. Best-effort 2s GitHub check; silent on any
# failure/offline/opt-out (SLUICE_NO_UPDATE_CHECK=1), never aborts. Field-numeric compare (BSD sort
# has no -V); a dev build (X.Y.Z-N-g...) compares by its X.Y.Z base, so it won't nag.
check_update_notice() {
  [ -z "${SLUICE_NO_UPDATE_CHECK:-}" ] || return 0
  command -v curl >/dev/null 2>&1 || return 0
  local cur_base latest newest
  cur_base="$(sluice_version | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+' || true)"
  [ -n "$cur_base" ] || return 0
  latest="$(curl -fsS --max-time 2 https://api.github.com/repos/Pyronewbic/Sluice/releases/latest 2>/dev/null \
            | grep -oE '"tag_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 \
            | sed -E 's/.*"([^"]*)"$/\1/' 2>/dev/null || true)"
  latest="${latest#v}"
  [ -n "$latest" ] || return 0
  newest="$(printf '%s\n%s\n' "$cur_base" "$latest" | sort -t. -k1,1n -k2,2n -k3,3n | tail -1)"
  [ "$newest" = "$latest" ] && [ "$latest" != "$cur_base" ] \
    && printf '  update   v%s available (you have v%s) - update sluice: brew upgrade sluice (see README)\n' "$latest" "$cur_base"
  return 0
}
usage() {
  cat <<EOF
sluice $(sluice_version) - run any project in a sandboxed, egress-firewalled container.

Usage: sluice [-b <name>] [command]

  -b, --box <name>  target any box by name from anywhere (before the command; see 'sluice ls')

Common:
  (no command)     build (if needed) + run SLUICE_RUN_CMD; scaffold a config if there's none
  agent [name] [args]  run a coding agent; trailing args run it one-shot; no name lists them
  init [--force|--update]  scaffold a sluice.config.sh by detecting the project's stack
                   (--update re-detects but keeps your allowlist/env/hardening; confirms)
  learn            review the hosts the proxy blocked and allowlist the ones you pick, live
                   (per-host, last run by default; offers .domain wildcards; no rebuild)
                   --all everything since boot; --print emits the list; --apply allows all;
                   --audit opens egress for one trusted run to discover every reached host
  shell            a bash shell in the sandbox (as the non-root sluice user)
  run <cmd...>     an ad-hoc command instead of SLUICE_RUN_CMD

Protected workspace (SLUICE_WORKSPACE=overlay - host repo mounted read-only, box works on a copy):
  diff             show what the box changed vs your repo (unified diff, .git excluded)
  apply            write the box's changes back onto your repo (confirms first)

Build & lifecycle:
  build            build the image (if missing or the config changed)
  rebuild          build + recreate the container - apply config/allowlist edits
  update           rebuild from scratch (re-resolve packages to latest) + refresh sluice.lock
  stop             remove the project's container
  rm               remove the project's container AND image
  prune            remove every sluice container + image (or only orphans: --orphans); confirms

Inspect:
  doctor           health check: engine, image, allowlist, blocked egress (--json)
  ls               list all boxes + posture (status, stack, allow/ports/lock, path); --running/--orphans/--stack <name>/--egress/--json
  egress           show what this box reached vs. was blocked (--json | --export | --verify)
                   --verify/--export accept --all to span every box's audit log (fleet-wide, no engine)
  logs             follow firewall + readiness logs
  lock             record installed apk+npm+pip+gem+go+cargo versions to sluice.lock (supply-chain audit)
                   --check fails on drift (CI gate, --json); --enforce is the strict variant; --diff shows it;
                   --sbom emits CycloneDX (--format spdx for SPDX); --scan vuln-checks via a host Grype/Trivy (--fail-on <sev>);
                   --pin writes sluice.pin (base digest + exact versions) for a SLUICE_PIN=1 replay build
  smoke            build (if needed) + run the image smoke test

Meta:
  version          show version + host runtime (engine, OS)
  help             show this help

Env: SLUICE_ENGINE  SLUICE_RUNTIME=kata  SLUICE_NO_BANNER  SLUICE_YES  SLUICE_NO_UPDATE_CHECK  NO_COLOR
     SLUICE_PIDS_LIMIT (default 4096)  SLUICE_MEMORY (e.g. 4g; unset = no cap)
     SLUICE_SECCOMP=hardened|browser|audit (extra syscall filter; hardened >= engine default)
     SLUICE_READONLY_ROOT=1 (immutable rootfs; tmpfs + anon-volume the writable paths)
     SLUICE_WORKSPACE=overlay (host repo read-only; box edits a copy - see 'diff'/'apply')
     SLUICE_EGRESS_HARD_CAP_BYTES=N (preventive in-box egress cap)  SLUICE_PIN=1 (verified pinned replay)
     Config knobs (sluice.config.sh): see sluice.config.example.sh + docs/configuration.md
Docs: https://github.com/Pyronewbic/Sluice
EOF
}
# Per-command help (sluice <cmd> --help). Synopses mirror usage(); keeps `sluice run --help` etc. useful.
help_for() {
  case "$1" in
    run)     echo "sluice run <cmd...>     - run an ad-hoc command in the sandbox (builds/starts if needed)." ;;
    shell)   echo "sluice shell            - a bash shell in the sandbox (non-root sluice user)." ;;
    agent)   echo "sluice agent [name] [args] - scaffold + run a coding-agent preset; args after the name run it one-shot; no name lists them." ;;
    init)    echo "sluice init [--force|--update] - scaffold a sluice.config.sh by detecting the stack (--update re-detects, keeping your edits)." ;;
    learn)   echo "sluice learn [--all] [--print|--apply|--audit] - review blocked hosts, allowlist your picks." ;;
    build)   echo "sluice build            - build the image if missing or the config changed." ;;
    rebuild) echo "sluice rebuild          - build + recreate the container (apply config/allowlist edits)." ;;
    update)  echo "sluice update           - rebuild from scratch (re-resolve packages) + refresh sluice.lock." ;;
    diff)    echo "sluice diff             - (SLUICE_WORKSPACE=overlay) show what the box changed vs your repo." ;;
    apply)   echo "sluice apply            - (SLUICE_WORKSPACE=overlay) write the box's changes back onto your repo (confirms; SLUICE_YES=1 non-interactive, SLUICE_APPLY_NO_DELETE=1 keeps deleted host files)." ;;
    stop)    echo "sluice stop             - remove the project's container." ;;
    rm)      echo "sluice rm               - remove the project's container AND image." ;;
    prune)   echo "sluice prune [--orphans] - remove every sluice container + image (or only orphans); confirms." ;;
    doctor)  echo "sluice doctor [--json]  - health check: engine, image, allowlist, blocked egress." ;;
    ls)      echo "sluice ls [--running|--orphans|--stack <name>|--egress|--json] - list boxes + posture (allow/ports/lock; --egress adds live blocked counts). Posture populates after rebuild." ;;
    egress)  echo "sluice egress [--json | --export [--all] | --verify [--all] [--json]]  - reached vs. blocked; --export the append-only audit log (JSONL), --verify its hash chain; --all spans every box (fleet-wide, no engine needed)." ;;
    logs)    echo "sluice logs             - follow firewall + readiness logs." ;;
    lock)    echo "sluice lock [--check [--json] | --diff [--json] | --enforce [--json] | --sbom [--format cyclonedx|spdx] | --scan [--json] [--fail-on <sev>] | --pin] - record/verify/vuln-scan the supply-chain inventory; --pin writes a replay manifest." ;;
    smoke)   echo "sluice smoke            - build (if needed) + run the image smoke test." ;;
    version) echo "sluice version [--json] - show version + host runtime." ;;
    *)       usage ;;
  esac
}
cmd_version() {
  [ "${1:-}" = --json ] && { cmd_version_json; return 0; }
  printf 'sluice %s\n' "$(sluice_version)"
  local eng=""
  if   [ -n "${SLUICE_ENGINE:-}" ]; then eng="$SLUICE_ENGINE"
  elif command -v docker >/dev/null 2>&1; then eng=docker
  elif command -v podman >/dev/null 2>&1; then eng=podman; fi
  if [ -n "$eng" ] && command -v "$eng" >/dev/null 2>&1; then
    printf '  engine   %s\n' "$("$eng" --version 2>/dev/null | head -1)"
  else
    printf '  engine   %snone%s (install docker or podman)\n' "$C_RED" "$C_RST"
  fi
  printf '  os       %s %s\n' "$(uname -s)" "$(uname -m)"
  printf '  install  %s\n' "$ROOT"
  check_update_notice
}
# Machine-readable version/runtime for scripts + the control plane.
cmd_version_json() {
  local eng=""
  if   [ -n "${SLUICE_ENGINE:-}" ]; then eng="$SLUICE_ENGINE"
  elif command -v docker >/dev/null 2>&1; then eng=docker
  elif command -v podman >/dev/null 2>&1; then eng=podman; fi
  [ -n "$eng" ] && command -v "$eng" >/dev/null 2>&1 && eng="$("$eng" --version 2>/dev/null | head -1)"
  printf '{"schema":"sluice.version/v1","version":"%s","engine":"%s","os":"%s","install":"%s"}\n' \
    "$(_json_esc "$(sluice_version)")" "$(_json_esc "$eng")" "$(_json_esc "$(uname -s) $(uname -m)")" "$(_json_esc "$ROOT")"
}

# naming + diagnostics helpers (shared by run, learn, doctor)
derive_names() {
  slug="$(printf '%s' "${SLUICE_NAME:-$(basename "$PROJECT_DIR")}" | tr '[:upper:]' '[:lower:]' | tr -C 'a-z0-9' '-')"
  tag="sluice-$slug"; container="$tag"
}

# Always-on egress hosts (registries + GitHub); core/entrypoint.sh keeps its own in-container copy.
base_domains() { printf '%s' "github.com api.github.com codeload.github.com objects.githubusercontent.com registry.npmjs.org registry.yarnpkg.com"; }

# Public suffixes where the registrable domain sits one label below the last two - common second-level
# ccTLDs + dev-platform hosts that show up in allowlists. Not the full PSL (that'd be vendored data);
# the _collapsible guard makes an unlisted multi-part suffix fail "don't offer the wildcard", not over-allow.
# ccTLD second-levels + flat app/dev platforms + cloud storage at its true (deeper) suffix, so a
# multi-tenant host like a.s3.amazonaws.com collapses to a.s3... not the tenant-shared apex.
_PUBLIC_SUFFIXES="co.uk org.uk gov.uk ac.uk me.uk net.uk com.au net.au org.au gov.au edu.au co.nz net.nz org.nz co.jp ne.jp or.jp co.kr co.in co.za com.br com.cn com.mx com.sg com.tr github.io gitlab.io pages.dev workers.dev r2.dev vercel.app netlify.app web.app firebaseapp.com herokuapp.com azurewebsites.net cloudfront.net s3.amazonaws.com blob.core.windows.net storage.googleapis.com"

# Registrable parent (eTLD+1) of a host, public-suffix aware: the label just below the longest matching
# suffix. Returns the host unchanged when it IS a suffix / has nothing below one, so `learn` never
# offers a `.wildcard` equal to a public suffix. Wildcards stay offered, never forced.
parent_of() {
  local host="$1" s head
  for s in $_PUBLIC_SUFFIXES; do
    case "$host" in
      "$s")  printf '%s\n' "$host"; return 0 ;;
      *.$s)  head="${host%.$s}"; printf '%s.%s\n' "${head##*.}" "$s"; return 0 ;;
    esac
  done
  printf '%s\n' "$host" | awk -F. 'NF>=2{print $(NF-1)"."$NF; next}{print}'
}

# True when collapsing to ".$1" is safe to offer: at least two labels AND not itself a public suffix.
_collapsible() {
  local p="$1" s
  case "$p" in *.*) ;; *) return 1 ;; esac
  for s in $_PUBLIC_SUFFIXES; do [ "$p" = "$s" ] && return 1; done
  return 0
}

# Hash of config + core (+ base image ref), baked as an image label; rebuild when it changes.
# SLUICE_ALLOW_DOMAINS is excluded - applied at runtime (SLUICE_RUNTIME_ALLOW), so an allowlist edit
# (e.g. `sluice learn`) needs no rebuild.
config_hash() {
  { printf 'base=%s\n' "${SLUICE_BASE_IMAGE:-}"; grep -vE '^[[:space:]]*SLUICE_ALLOW_DOMAINS=' "$PROJECT_CONFIG"; \
    find "$CORE" -type f | LC_ALL=C sort | while read -r f; do cat "$f"; done; \
    for f in ${SLUICE_PREFETCH_FILES:-}; do [ -f "$PROJECT_DIR/$f" ] && cat "$PROJECT_DIR/$f"; done; \
    printf 'pin=%s\n' "${SLUICE_PIN:-}"; \
    if [ "${SLUICE_PIN:-}" = 1 ] && [ -f "$PROJECT_DIR/sluice.pin" ]; then cat "$PROJECT_DIR/sluice.pin"; fi; } \
    | shasum | awk '{print $1}' | cut -c1-12
}

# ps-filter (not `inspect .State.Running`) so it works on both docker and nerdctl - nerdctl's native
# inspect has no docker-style .State key. grep -qx pins the exact name (not the -audit sibling).
running() { "$RUNNER" ps --filter "name=$container" --filter status=running --format '{{.Names}}' 2>/dev/null | grep -qx "$container"; }

# True when the HOST enforces SELinux (Fedora/RHEL/CentOS default). On such a host a bind mount is
# inaccessible to the box without a label, so sluice runs it label=disable (see the run paths).
selinux_enforcing() { [ -r /sys/fs/selinux/enforce ] && [ "$(cat /sys/fs/selinux/enforce 2>/dev/null)" = 1 ]; }

# Root-context maintenance execs (receipt/learn/apply) run as the container's root - NOT --user sluice.
# The image PATH must never let a uid-1000-writable dir (/home/sluice/.npm-global/bin) shadow a system
# tool here, or a planted ~/.npm-global/bin/tail runs as root. Force a clean system PATH on every such
# exec. Session execs (_exec_args) stay --user sluice and keep the full PATH for the workload's tools.
_ROOT_PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
_root_exec() { "$RUNNER" exec -e "PATH=$_ROOT_PATH" "$@"; }

# True when the box's in-container audit log is actually READABLE. A uid-1000 workload can exhaust the
# pids cgroup so `<engine> exec` can't fork - _squid_log would then return empty (a FAILED read), which
# would misread as zero egress. Callers gate on this to record `unavailable` / fail the byte gate closed.
_audit_readable() { _root_exec "$container" true >/dev/null 2>&1; }

# squid access log. From _RCPT_OFFSET bytes when set (the run-scoped receipt); otherwise the last
# _SQUID_LOG_CAP bytes - a ceiling so an attacker can't inflate host CPU/IO by spamming the log and
# forcing an unbounded `cat | awk` on the box-level audit paths (egress/doctor/learn --all). 16 MiB
# holds far more than any real session; a truncated first line just gets skipped by the awk parsers.
_SQUID_LOG_CAP=16777216
_squid_log() {
  if [ -n "${_RCPT_OFFSET:-}" ]; then
    _root_exec "${1:-$container}" sh -c "tail -c +$(( _RCPT_OFFSET + 1 )) /var/log/squid/access.log" 2>/dev/null
  else
    _root_exec "${1:-$container}" sh -c "tail -c $_SQUID_LOG_CAP /var/log/squid/access.log" 2>/dev/null
  fi
}

# Hostnames the proxy BLOCKED (SNI for HTTPS, Host for HTTP), from the running container's log.
blocked_hosts() {
  _squid_log | awk '
    { sni="";
      for (i=1;i<=NF;i++) if ($i ~ /^ssl_sni=/) sni=substr($i,9);
      status=$3; url=$5;
      if (status !~ /NONE_NONE/ && status !~ /TCP_DENIED/ && status !~ /\/000/) next;
      host="";
      if (sni != "" && sni != "-") host=sni;
      else if (url ~ /^http:\/\//) { h=url; sub(/^http:\/\//,"",h); sub(/\/.*/,"",h); sub(/:.*/,"",h); host=h }
      if (host == "" || host ~ /^[0-9.]+$/) next;
      if (host !~ /^\.?[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$/) next;   # drop non-hostname chars: a raw SNI/Host carries $(),",ESC -> config-write RCE + terminal-escape injection
      print host
    }' | sort -u
}

# Hostnames the proxy ALLOWED (reached). reached_hosts_raw = one line per request (for counts);
# reached_hosts = unique. Optional $1 = container (learn --audit opens egress, so every host logs as a success).
reached_hosts_raw() {
  _squid_log "$@" | awk '
    { sni="";
      for (i=1;i<=NF;i++) if ($i ~ /^ssl_sni=/) sni=substr($i,9);
      status=$3; url=$5;
      if (status ~ /NONE_NONE/ || status ~ /TCP_DENIED/ || status ~ /\/000/) next;
      host="";
      if (sni != "" && sni != "-") host=sni;
      else if (url ~ /^http:\/\//) { h=url; sub(/^http:\/\//,"",h); sub(/\/.*/,"",h); sub(/:.*/,"",h); host=h }
      if (host == "" || host ~ /^[0-9.]+$/) next;
      if (host !~ /^\.?[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$/) next;   # drop non-hostname chars: a raw SNI/Host carries $(),",ESC -> config-write RCE + terminal-escape injection
      print host
    }'
}
reached_hosts()  { reached_hosts_raw "$@" | sort -u; }

# Per-host egress rows for the receipt + `sluice egress`: one awk pass over the (offset-aware) proxy
# log -> "<class>\t<host>\t<count>\t<bytes>". class=reached if the host ever got through, else blocked
# (reached-precedence wins on mixed lines); count = successes (reached) or denials (blocked); bytes =
# tx+rx. The example.* boot canary + already-allowlisted /000-race hosts are dropped (matches blocked_new).
egress_rows() {
  _squid_log "$@" | awk -v allow=" $(allowed_domains) " '
    # Is host h allowlisted? Exact match, or covered by a leading-dot wildcard (.x matches x + *.x),
    # mirroring squid dstdomain - so learn never re-proposes a host a `.domain` entry already covers.
    function allowed(h,   n,i,t,tl,toks) {
      if (index(allow, " " h " ")) return 1;
      n = split(allow, toks, " ");
      for (i=1;i<=n;i++) { t=toks[i]; if (substr(t,1,1)==".") { tl=length(t);
        if (h==substr(t,2) || (length(h)>tl && substr(h,length(h)-tl+1)==t)) return 1; } }
      return 0;
    }
    { sni=""; tx=0; rx=0;
      for (i=1;i<=NF;i++) {
        if      ($i ~ /^ssl_sni=/) sni=substr($i,9);
        else if ($i ~ /^tx=/)      tx=substr($i,4)+0;
        else if ($i ~ /^rx=/)      rx=substr($i,4)+0;
      }
      status=$3; url=$5; host="";
      if (sni != "" && sni != "-") host=sni;
      else if (url ~ /^http:\/\//) { h=url; sub(/^http:\/\//,"",h); sub(/\/.*/,"",h); sub(/:.*/,"",h); host=h }
      if (host == "" || host ~ /^[0-9.]+$/) next;
      if (host !~ /^\.?[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$/) next;   # drop non-hostname chars: a raw SNI/Host carries $(),",ESC -> config-write RCE + terminal-escape injection
      bytes[host] += tx + rx; seen[host]=1;
      if (status ~ /NONE_NONE/ || status ~ /TCP_DENIED/ || status ~ /\/000/) deny[host]++; else succ[host]++;
    }
    END {
      for (h in seen) {
        if (h ~ /^example\.(com|net|org)$/) continue;
        if (succ[h] > 0)        printf "reached\t%s\t%d\t%d\n", h, succ[h], bytes[h];
        else if (!allowed(h))   printf "blocked\t%s\t%d\t%d\n", h, deny[h], bytes[h];
      }
    }'
}

# bytes -> human (B / KB / MB, one decimal for KB+).
_human_bytes() {
  awk -v b="${1:-0}" 'BEGIN{ if (b<1024) printf "%d B", b; else if (b<1048576) printf "%.1f KB", b/1024; else printf "%.1f MB", b/1048576 }'
}

# Total bytes the box SENT OUT to hosts it actually reached (tx=%>st, the upload/request side) - the
# exfil-relevant volume for the SLUICE_EGRESS_MAX_BYTES budget. Blocked requests never left the proxy,
# so they don't count. Offset-aware via _squid_log (scoped to the run for the receipt).
egress_tx_total() {
  _squid_log | awk '
    { tx=0; status=$3;
      if (status ~ /NONE_NONE/ || status ~ /TCP_DENIED/ || status ~ /\/000/) next;   # blocked: did not leave
      for (i=1;i<=NF;i++) if ($i ~ /^tx=/) tx=substr($i,4)+0;
      total += tx;
    } END { print total+0 }'
}

# Bytes SENT OUT keyed by reached host: "<host>\t<tx>". Same exfil-direction measure as egress_tx_total
# (tx only; blocked requests never left the proxy), grouped by host for the SLUICE_EGRESS_HOST_BUDGETS
# per-host gate. Offset-aware via _squid_log (scoped to the run for the receipt). Mirrors egress_rows'
# host + hostname-charset parsing.
egress_tx_by_host() {
  _squid_log | awk '
    { sni=""; tx=0; status=$3; url=$5;
      if (status ~ /NONE_NONE/ || status ~ /TCP_DENIED/ || status ~ /\/000/) next;   # blocked: did not leave
      for (i=1;i<=NF;i++) { if ($i ~ /^ssl_sni=/) sni=substr($i,9); else if ($i ~ /^tx=/) tx=substr($i,4)+0; }
      host="";
      if (sni != "" && sni != "-") host=sni;
      else if (url ~ /^http:\/\//) { h=url; sub(/^http:\/\//,"",h); sub(/\/.*/,"",h); sub(/:.*/,"",h); host=h }
      if (host == "" || host ~ /^[0-9.]+$/) next;
      if (host !~ /^\.?[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$/) next;   # drop non-hostname chars (SNI/Host can carry $(),",ESC)
      tot[host] += tx;
    }
    END { for (h in tot) printf "%s\t%d\n", h, tot[h] }'
}

# Resolve a host to its SLUICE_EGRESS_HOST_BUDGETS cap in bytes (empty = no budget for this host).
# Tokens are "host=bytes" (exact) or ".wildcard=bytes" (.x matches x + *.x, squid dstdomain style).
# Exact match wins outright; among wildcards the longest (most specific) wins. set -f so the unquoted
# split can't glob a value.
_host_budget_for() {
  local host="$1" tok thost tbytes bare best="" bestlen=-1
  set -f
  for tok in ${SLUICE_EGRESS_HOST_BUDGETS:-}; do
    case "$tok" in *=*) ;; *) continue ;; esac
    thost="${tok%%=*}"; tbytes="${tok#*=}"
    case "$tbytes" in ''|*[!0-9]*) continue ;; esac
    if [ "$thost" = "$host" ]; then best="$tbytes"; break; fi   # exact beats any wildcard
    case "$thost" in
      .*) bare="${thost#.}"
          if [ "$host" = "$bare" ] || case "$host" in *"$thost") true ;; *) false ;; esac; then
            [ "${#thost}" -gt "$bestlen" ] && { best="$tbytes"; bestlen="${#thost}"; }
          fi ;;
    esac
  done
  set +f
  printf '%s' "$best"
}

# Per-entry SLUICE_ALLOW_IPS accounting: read the OUTPUT chain's counters (the direct-egress jumps route
# through SLUICE-ALLOWIPS), emitting "<entry>\t<packets>\t<bytes>" per entry - the first visibility into
# the direct-IP escape hatch, which bypasses squid and was invisible to the receipt. Root-side iptables
# read (NET_ADMIN kept; /sbin on _ROOT_PATH). Empty read is gated by _audit_readable at the call site.
# Note: these count ATTEMPTED wire bytes (headers included; packets a budget DROP later ate are counted);
# entries on :80/:443 are dead (the NAT REDIRECT wins) and show 0.
allowips_rows() {
  _root_exec "$container" iptables -nvxL OUTPUT 2>/dev/null | awk '
    $3=="SLUICE-ALLOWIPS" {
      dst=$9; port="";
      for (i=10;i<=NF;i++) if ($i ~ /^dpt:/) port=substr($i,5);
      entry=(port=="") ? dst : dst":"port;
      printf "%s\t%d\t%d\n", entry, $1, $2;
    }'
}

# Firewall-dropped total: parse the OUTPUT chain's policy-DROP counter ("Chain OUTPUT (policy DROP N
# packets, M bytes)") - the first visibility into non-HTTP blocked egress attempts. Emits "<packets>\t<bytes>".
fw_dropped() {
  _root_exec "$container" iptables -nvxL OUTPUT 2>/dev/null | awk '
    /^Chain OUTPUT / {
      p=0; b=0;
      for (i=1;i<=NF;i++) { if ($i ~ /^packets,?$/) p=$(i-1); if ($i ~ /^bytes\)?$/) b=$(i-1); }
      printf "%d\t%d\n", p, b; exit;
    }'
}

# DNS query audit (SLUICE_DNS_AUDIT=1): read dnsmasq's query log and group by immediate parent domain,
# emitting "<parent>\t<queries>\t<unique_names>". A DNS tunnel concentrates MANY unique leftmost labels
# under one parent (exfil as DNS labels), so a high unique-name count per parent is the signal. Queried
# names are attacker-controlled bytes -> the same hostname charset gate as SNI (drops $(),",ESC). Reuses
# the _SQUID_LOG_CAP DoS ceiling. Empty read gated by _audit_readable at the call site.
dns_rows() {
  _root_exec "$container" sh -c "tail -c $_SQUID_LOG_CAP /var/log/squid/dns.log" 2>/dev/null | awk '
    /query\[/ {
      name="";
      for (i=1;i<=NF;i++) if ($i ~ /^query\[/) { name=$(i+1); break }
      if (name=="" || name !~ /^[A-Za-z0-9._-]+$/) next;   # non-hostname bytes: skip (RCE/escape guard)
      n=split(name, L, ".");
      if (n<=2) parent=name; else { parent=L[2]; for (j=3;j<=n;j++) parent=parent"."L[j] }
      cnt[parent]++;
      key=parent SUBSEP name;
      if (!(key in seen)) { seen[key]=1; uniq[parent]++ }
    }
    END { for (p in cnt) printf "%s\t%d\t%d\n", p, cnt[p], uniq[p] }'
}

# Packets the SLUICE_ALLOW_IPS shared budget DROP'd (SLUICE_ALLOW_IPS_MAX_BYTES exhausted mid-run). A
# non-zero count means the box hit the direct-IP cap during the run -> `sluice egress` fails the gate.
# Empty when the chain/budget isn't present (no SLUICE-ALLOWIPS DROP rule).
allowips_dropped() {
  _root_exec "$container" iptables -nvxL SLUICE-ALLOWIPS 2>/dev/null | awk '
    $3=="DROP" { print $1+0; found=1; exit } END { if (!found) print "" }'
}

# ",\"allow_ips\":[...],\"fw_dropped\":{...}" for the receipt + `sluice egress --json`, or "" when
# SLUICE_ALLOW_IPS is unset. One iptables read each for the per-entry counters and the policy-DROP total.
_allowips_json_fields() {
  [ -n "${SLUICE_ALLOW_IPS:-}" ] || { printf ''; return 0; }
  local TAB e p b aij="" first=1 fwd fp fb; TAB="$(printf '\t')"
  while IFS="$TAB" read -r e p b; do
    [ -n "$e" ] || continue
    [ "$first" = 1 ] && first=0 || aij="$aij,"
    aij="$aij{\"entry\":\"$(_json_esc "$e")\",\"packets\":${p:-0},\"bytes\":${b:-0}}"
  done <<EOF
$(allowips_rows 2>/dev/null || true)
EOF
  fwd="$(fw_dropped 2>/dev/null || true)"; fp="${fwd%%"$TAB"*}"; fb="${fwd#*"$TAB"}"
  case "$fp" in ''|*[!0-9]*) fp=0 ;; esac
  case "$fb" in ''|*[!0-9]*) fb=0 ;; esac
  printf ',"allow_ips":[%s],"fw_dropped":{"packets":%s,"bytes":%s}' "$aij" "$fp" "$fb"
}

# ",\"dns\":{...}" when SLUICE_DNS_AUDIT=1, else "". Sums dns_rows for totals + flags tunnel parents
# (unique names >= SLUICE_DNS_TUNNEL_THRESHOLD, default 500).
_dns_json_fields() {
  [ "${SLUICE_DNS_AUDIT:-}" = 1 ] || { printf ''; return 0; }
  local TAB p q u tq=0 tu=0 fl="" ffirst=1 thr; TAB="$(printf '\t')"
  thr="${SLUICE_DNS_TUNNEL_THRESHOLD:-500}"; case "$thr" in ''|*[!0-9]*) thr=500 ;; esac
  while IFS="$TAB" read -r p q u; do
    [ -n "$p" ] || continue
    tq=$((tq + q)); tu=$((tu + u))
    if [ "$u" -ge "$thr" ]; then
      [ "$ffirst" = 1 ] && ffirst=0 || fl="$fl,"
      fl="$fl{\"parent\":\"$(_json_esc "$p")\",\"unique\":$u}"
    fi
  done <<EOF
$(dns_rows 2>/dev/null || true)
EOF
  printf ',"dns":{"queries":%s,"unique":%s,"flagged":[%s]}' "$tq" "$tu" "$fl"
}

# The proxy-log byte offset captured at the start of the last `sluice` run (written to /run by the run
# arms). Lets `sluice learn` scope to that run instead of the whole boot; empty if no run / box rebooted.
# `|| true` on the cat: a missing offset file -> empty offset (callers' full-log fallback), never a
# pipefail that would abort the bare-assignment call sites (learn/doctor/ls) under set -e.
last_run_offset() { { _root_exec "$container" cat /run/sluice-run-offset 2>/dev/null || true; } | tr -dc 0-9; }
mark_run_start()  { _root_exec "$container" sh -c 'wc -c < /var/log/squid/access.log | tr -dc 0-9 > /run/sluice-run-offset' 2>/dev/null || true; }

# sha256 of stdin (hex only). shasum ships on macOS + the Linux runners (config_hash already uses it).
_sha256() { shasum -a 256 2>/dev/null | awk '{print $1}'; }

# Arm the at-exit egress receipt for a session: snapshot the proxy-log position so the receipt is
# scoped to THIS run (not the box's whole boot), mark the run start so a later `learn` can scope to it,
# and trap the receipt on EXIT (fires on normal exit, die, or Ctrl-C). Shared by run-default/shell/run.
arm_receipt() {
  _RCPT_OFFSET="$(_root_exec "$container" sh -c 'wc -c < /var/log/squid/access.log' 2>/dev/null | tr -dc 0-9)"
  mark_run_start
  trap show_egress_receipt EXIT
}

# This project's effective egress allowlist: config domains + the always-on base.
allowed_domains() { printf '%s %s' "${SLUICE_ALLOW_DOMAINS:-}" "$(base_domains)"; }

# True if a host is a known shared/public endpoint an attacker could also WRITE to - so data can be
# laundered out through it even though it's allowlisted (THREAT_MODEL "allowed-host laundering"; we
# splice, never decrypt). Heuristic + non-exhaustive; doctor nudges, never blocks.
laundering_host() {
  set -- "${1#.}"   # a leading-dot wildcard (.host, what `sluice learn` writes) covers the bare host
  case "$1" in
    *s3.amazonaws.com|*.s3.*.amazonaws.com|storage.googleapis.com|*.blob.core.windows.net|*.r2.cloudflarestorage.com|*.digitaloceanspaces.com) return 0 ;;
    gist.github.com|gist.githubusercontent.com|raw.githubusercontent.com|*pastebin.com|paste.*|transfer.sh|0x0.st|file.io|*.tmpfiles.org) return 0 ;;
    webhook.site|*.ngrok.io|*.ngrok-free.app|hooks.slack.com|*.requestbin.com|*.pipedream.net) return 0 ;;
    api.openai.com|api.anthropic.com|generativelanguage.googleapis.com|api.cohere.ai) return 0 ;;
  esac
  return 1
}

# True if $host is on the baked DoH/DoT denylist (core/doh-endpoints.txt, the single source squid
# also reads). dstdomain semantics: a leading-dot entry matches the domain + subdomains; else exact.
doh_listed() {
  # Match case-insensitively (squid dstdomain / dnsmasq are; the SNI regex accepts uppercase). $1 may be
  # a leading-dot WILDCARD. Reject when the candidate IS a DoH endpoint, sits UNDER a DoH wildcard, OR is
  # a wildcard that COVERS a DoH endpoint host - e.g. `.adguard.com` would re-allow the listed
  # dns.adguard.com. The denylist is lowercase.
  local cand ch entry eh
  cand="$(printf '%s' "$1" | tr 'A-Z' 'a-z')"; ch="${cand#.}"
  [ -f "$CORE/doh-endpoints.txt" ] || return 1
  while IFS= read -r entry; do
    case "$entry" in ''|\#*) continue ;; esac
    eh="${entry#.}"
    case "$entry" in
      .*) case ".$ch" in *"$entry") return 0 ;; esac ;;   # candidate is, or sits under, a DoH wildcard
      *)  [ "$ch" = "$entry" ] && return 0 ;;              # candidate is the exact DoH host
    esac
    case "$cand" in .*) case ".$eh" in *"$cand") return 0 ;; esac ;; esac   # wildcard candidate covers it
  done < "$CORE/doh-endpoints.txt"
  return 1
}

# Blocked hosts NOT already allowed - the genuinely-missing ones. Drops the transient
# startup-race /000 on allowlisted hosts (e.g. registry.npmjs.org), so it never proposes them.
blocked_new() {
  local cur h
  cur=" $(allowed_domains) "
  blocked_hosts 2>/dev/null | while IFS= read -r h; do
    [ -n "$h" ] || continue
    case "$h" in example.com|example.net|example.org) continue;; esac   # boot deny-canary, not an app host
    case "$cur" in *" $h "*) ;; *) printf '%s\n' "$h";; esac
  done
}

# Count of genuinely-denied hosts for a running box, WITHOUT sourcing its config (for `ls --egress`).
# Reuses blocked_new wholesale: a subshell overrides the two globals it reads - $container (which
# box's log to exec) and $SLUICE_ALLOW_DOMAINS (the box's live allowlist, read from the container).
# base_domains() is still added by allowed_domains(), so base hosts never count as blocked.
# Fail-closed: a zero is only trusted after _audit_readable confirms the exec path still works; an
# unreadable box (e.g. pids exhausted) emits EMPTY (unknown) - ls renders ? / null, never a false 0.
box_blocked_count() {
  local al n
  al="$(_root_exec "$1" cat /etc/squid/allowlist.txt 2>/dev/null | tr '\n' ' ' || true)"
  n="$( ( container="$1"; SLUICE_ALLOW_DOMAINS="$al"; blocked_new 2>/dev/null | grep -c . ) || true )"
  [ "${n:-0}" -gt 0 ] || ( container="$1"; _audit_readable ) || return 0   # a 0 may be a FAILED read - confirm it
  printf '%s\n' "$n"
}

# `sluice egress [--json]`: the box's egress audit record (reached vs. blocked)
# reached_hosts = what the box actually reached; blocked_new = genuinely-denied hosts (not in the
# allowlist, and minus the transient startup-race noise doctor also filters). A control-plane feed.
cmd_egress() {
  local mode="${1:-}" rows TAB
  running || die "no running sandbox. Start it ('sluice'), exercise it, then run 'sluice egress'."
  rows="$(egress_rows 2>/dev/null || true)"
  # Empty rows mean "no egress" OR a FAILED in-box read (uid 1000 filled the pids cgroup so the audit
  # exec couldn't fork). Never let a failed read pass as a clean zero - fail closed so a CI byte gate
  # can't go green on an un-audited run.
  if [ -z "$rows" ] && ! _audit_readable; then
    if [ "$mode" = --json ]; then
      printf '{"schema":"sluice.egress/v1","box":"%s","unavailable":true}\n' "$(_json_esc "$container")"
    else
      echo "[sluice] ${E_YEL:-}egress audit unavailable${E_RST:-} - could not read the in-box log (pids limit?); failing closed." >&2
    fi
    return 2
  fi
  TAB="$(printf '\t')"
  # SLUICE_EGRESS_MAX_BYTES: a volume budget on what LEFT the box (tx to reached hosts). Over the cap,
  # this command exits non-zero so CI can gate it - bounds how much can be laundered through an
  # allowed host. Unset -> no gate (always exit 0, unchanged).
  local cap="${SLUICE_EGRESS_MAX_BYTES:-}" tx over=0
  case "$cap" in *[!0-9]*) cap="";; esac   # non-numeric (or empty) -> no budget
  tx="$(egress_tx_total 2>/dev/null || echo 0)"; case "$tx" in ''|*[!0-9]*) tx=0;; esac
  [ -n "$cap" ] && [ "$tx" -gt "$cap" ] && over=1
  # SLUICE_EGRESS_HOST_BUDGETS: a PER-HOST tx budget (bounds laundering through one allowed host more
  # tightly than the whole-box cap). Any single reached host over its cap makes this command exit
  # non-zero too - the same CI gate. Detective, boot-scoped (like the total cap). hb_tx_table is the
  # per-host tx tally, computed once and reused by the human + JSON renders below.
  local hb_over=0 hb_tx_table="" hb_host hb_tx hb_cap
  if [ -n "${SLUICE_EGRESS_HOST_BUDGETS:-}" ]; then
    hb_tx_table="$(egress_tx_by_host 2>/dev/null || true)"
    while IFS="$TAB" read -r hb_host hb_tx; do
      [ -n "$hb_host" ] || continue
      hb_cap="$(_host_budget_for "$hb_host")"; [ -n "$hb_cap" ] || continue
      case "$hb_tx" in ''|*[!0-9]*) hb_tx=0 ;; esac
      [ "$hb_tx" -gt "$hb_cap" ] && hb_over=1
    done <<EOF
$hb_tx_table
EOF
  fi
  [ "$hb_over" = 1 ] && over=1
  # SLUICE_ALLOW_IPS_MAX_BYTES: the shared direct-IP budget DROPs packets once exhausted; a non-zero
  # DROP counter means the run hit the cap -> fail the gate (bounds direct-IP exfil by volume).
  if [ -n "${SLUICE_ALLOW_IPS:-}" ] && [ -n "${SLUICE_ALLOW_IPS_MAX_BYTES:-}" ]; then
    local _aid; _aid="$(allowips_dropped 2>/dev/null || true)"; case "$_aid" in ''|*[!0-9]*) _aid=0 ;; esac
    [ "$_aid" -gt 0 ] && over=1
  fi
  if [ "$mode" = --json ]; then
    # Back-compat host arrays + a detailed hosts array (class/requests/bytes) for the control plane.
    local allowed blocked hosts_json="" first=1 cls host cnt byt over_json=false
    [ "$over" = 1 ] && over_json=true
    allowed="$(printf '%s\n' "$rows" | awk -F"$TAB" '$1=="reached"{print $2}')"
    blocked="$(printf '%s\n' "$rows" | awk -F"$TAB" '$1=="blocked"{print $2}')"
    local _bud _ovb _htx
    while IFS="$TAB" read -r cls host cnt byt; do
      [ -n "$host" ] || continue
      [ "$first" = 1 ] && first=0 || hosts_json="$hosts_json,"
      _bud=null; _ovb=false
      if [ -n "$hb_tx_table" ] && [ "$cls" = reached ]; then
        _bud="$(_host_budget_for "$host")"
        if [ -n "$_bud" ]; then
          _htx="$(printf '%s\n' "$hb_tx_table" | awk -F"$TAB" -v h="$host" '$1==h{print $2; exit}')"
          case "$_htx" in ''|*[!0-9]*) _htx=0 ;; esac
          [ "$_htx" -gt "$_bud" ] && _ovb=true
        else _bud=null; fi
      fi
      hosts_json="$hosts_json{\"host\":\"$(_json_esc "$host")\",\"class\":\"$cls\",\"requests\":$cnt,\"bytes\":$byt,\"budget\":$_bud,\"over_budget\":$_ovb}"
    done <<EOF
$rows
EOF
    # window=boot: unlike the at-exit receipt (run-scoped), this command reads the whole-boot egress
    # window - so does its SLUICE_EGRESS_MAX_BYTES gate. Surfaced for the control plane (see docs/operations.md).
    local _aipf _dnsf; _aipf="$(_allowips_json_fields)"; _dnsf="$(_dns_json_fields)"
    printf '{"schema":"sluice.egress/v1","box":"%s","window":"boot","allowed":%s,"blocked":%s,"tx_bytes":%s,"budget":%s,"over_budget":%s,"hosts":[%s]%s%s}\n' \
      "$(_json_esc "$container")" \
      "$(printf '%s\n' "$allowed" | _json_arr)" "$(printf '%s\n' "$blocked" | _json_arr)" \
      "$tx" "${cap:-null}" "$over_json" "$hosts_json" "$_aipf" "$_dnsf"
    return "$over"
  fi
  if [ -n "$rows" ]; then
    # Summary header (reached/blocked tally + total bytes) then host | verdict | requests | bytes
    # (reached): reached first (by bytes desc), then blocked. Counts/total computed in the same awk pass.
    local nblocked; nblocked="$(printf '%s\n' "$rows" | awk -F"$TAB" '$1=="blocked"' | grep -c . || true)"
    printf '%s\n' "$rows" | sort -t"$TAB" -k1,1r -k4,4nr -k2,2 \
      | awk -F"$TAB" -v box="$container" -v grn="$C_GRN" -v red="$C_RED" -v dim="$C_DIM" -v bld="$C_BLD" -v rst="$C_RST" '
          function human(b){ if(b<1024) return b" B"; else if(b<1048576) return sprintf("%.1f KB",b/1024); else return sprintf("%.1f MB",b/1048576) }
          { c[NR]=$1; h[NR]=$2; n[NR]=$3; b[NR]=$4; total+=$4; if($1=="reached") nr++; else nb++; if(length($2)>w) w=length($2) }
          END { printf "%s%s egress%s   %d reached, %d blocked, %s\n", bld, box, rst, nr, nb, human(total);
                for(i=1;i<=NR;i++){
                  if(c[i]=="reached") printf "  %-*s  %s[reached]%s  %3d req   %s\n", w, h[i], grn, rst, n[i], human(b[i]);
                  else                printf "  %-*s  %s[blocked]%s  %3d req\n",        w, h[i], red, rst, n[i];
                } }'
    # C1: blocked rows carry no next step here (unlike the receipt's per-row annotation) - one trailing nudge.
    [ "${nblocked:-0}" -gt 0 ] && echo "  ${C_DIM}${nblocked} host(s) blocked - allow with 'sluice learn'${C_RST}"
  else
    echo "${C_BLD}$container egress${C_RST}"
    echo "  ${C_DIM}(nothing yet - exercise the app, then re-run)${C_RST}"
  fi
  if [ -n "$cap" ]; then
    if [ "$tx" -gt "$cap" ]; then echo "  ${C_RED}egress budget EXCEEDED${C_RST}: $(_human_bytes "$tx") sent > $(_human_bytes "$cap") cap (SLUICE_EGRESS_MAX_BYTES)"
    else echo "  ${C_DIM}egress budget: $(_human_bytes "$tx") sent / $(_human_bytes "$cap") cap${C_RST}"; fi
  fi
  # Per-host budget breaches (SLUICE_EGRESS_HOST_BUDGETS): one line per host over its own cap.
  if [ "$hb_over" = 1 ]; then
    printf '%s\n' "$hb_tx_table" | while IFS="$TAB" read -r hb_host hb_tx; do
      [ -n "$hb_host" ] || continue
      hb_cap="$(_host_budget_for "$hb_host")"; [ -n "$hb_cap" ] || continue
      case "$hb_tx" in ''|*[!0-9]*) hb_tx=0 ;; esac
      [ "$hb_tx" -gt "$hb_cap" ] && echo "  ${C_RED}host budget EXCEEDED${C_RST}: $hb_host sent $(_human_bytes "$hb_tx") > $(_human_bytes "$hb_cap") cap (SLUICE_EGRESS_HOST_BUDGETS)"
    done
  fi
  # SLUICE_ALLOW_IPS direct-egress accounting (the escape hatch that bypasses squid - now metered).
  if [ -n "${SLUICE_ALLOW_IPS:-}" ]; then
    local _e _p _b _fwd _fp _fb
    allowips_rows 2>/dev/null | while IFS="$TAB" read -r _e _p _b; do
      [ -n "$_e" ] || continue
      echo "  ${C_DIM}direct-ip${C_RST} $_e  $_p pkt  $(_human_bytes "${_b:-0}")"
    done
    _fwd="$(fw_dropped 2>/dev/null || true)"; _fp="${_fwd%%"$TAB"*}"; _fb="${_fwd#*"$TAB"}"
    case "$_fp" in ''|*[!0-9]*) _fp=0 ;; esac
    [ "$_fp" -gt 0 ] && echo "  ${C_DIM}firewall dropped $_fp non-HTTP/off-allowlist packet(s)${C_RST}"
    if [ -n "${SLUICE_ALLOW_IPS_MAX_BYTES:-}" ]; then
      local _aid2; _aid2="$(allowips_dropped 2>/dev/null || true)"; case "$_aid2" in ''|*[!0-9]*) _aid2=0 ;; esac
      [ "$_aid2" -gt 0 ] && echo "  ${C_RED}direct-ip budget EXCEEDED${C_RST}: $_aid2 pkt dropped (SLUICE_ALLOW_IPS_MAX_BYTES)"
    fi
  fi
  # DNS query audit (SLUICE_DNS_AUDIT=1): volume + tunnel-pattern flags.
  if [ "${SLUICE_DNS_AUDIT:-}" = 1 ]; then
    local _dp _dq _du _dtq=0 _dtu=0 _thr; _thr="${SLUICE_DNS_TUNNEL_THRESHOLD:-500}"; case "$_thr" in ''|*[!0-9]*) _thr=500 ;; esac
    while IFS="$TAB" read -r _dp _dq _du; do
      [ -n "$_dp" ] || continue; _dtq=$((_dtq + _dq)); _dtu=$((_dtu + _du))
      [ "$_du" -ge "$_thr" ] && echo "  ${C_RED}possible DNS-tunnel pattern${C_RST} under $_dp ($_du unique names)"
    done <<EOF
$(dns_rows 2>/dev/null || true)
EOF
    echo "  ${C_DIM}dns: $_dtq queries, $_dtu unique names${C_RST}"
  fi
  # C2: make the tamper-evident audit log discoverable (has-rows human path only; the empty case stays quiet).
  [ -n "$rows" ] && echo "  ${C_DIM}audit log: sluice egress --export | --verify${C_RST}"
  return "$over"
}

# `sluice egress --export`: emit the append-only egress audit log (JSONL, one record per run with
# egress) for SIEM/CI ingestion. Reads the host-side store, so it works even when the box is down.
cmd_egress_export() {
  local log="${XDG_STATE_HOME:-$HOME/.local/state}/sluice/$slug/egress-log.jsonl"
  [ -f "$log" ] || { echo "[sluice] no egress log yet at $(_tilde "$log") - run the box first." >&2; return 0; }
  cat "$log"
}

# Walk ONE egress-log.jsonl hash chain. Sets _VCF_RECORDS / _VCF_BROKEN / _VCF_REASON and returns 0 if
# intact, 1 on the first break (self-hash / prev-link) or an unreadable file. Byte-identical chain
# semantics to the old inline loop - the `|| [ -n "$line" ]` unterminated-tail catch and the blank-line
# continue are both pinned by test/verify-receipt-unit.bats (which must pass unmodified). Shared by the
# single-box `egress --verify` and the fleet `egress --verify --all`; M3's rotation adds a `rotation-link`
# reason on top of this walker.
_verify_chain_file() {
  local log="$1"
  _VCF_RECORDS=0; _VCF_BROKEN=""; _VCF_REASON=""
  # A file we cannot read (perms) reports unreadable, never a silent pass (fail closed, like the audit reads).
  [ -r "$log" ] || { _VCF_REASON=unreadable; return 1; }
  local n=0 prev="0000000000000000000000000000000000000000000000000000000000000000" line payload self pfield
  while IFS= read -r line || [ -n "$line" ]; do
    [ -n "$line" ] || continue   # tolerate blank lines (don't hash "" into a bogus TAMPERED); count only real records
    n=$((n+1))
    self="$(printf '%s' "$line"   | sed -n 's/.*,"self":"\([0-9a-f]*\)"}$/\1/p')"
    payload="$(printf '%s' "$line" | sed 's/,"self":"[0-9a-f]*"}$/}/')"
    pfield="$(printf '%s' "$line"  | sed -n 's/.*,"prev":"\([0-9a-f]*\)".*/\1/p')"
    if [ -z "$self" ] || [ "$(printf '%s' "$payload" | _sha256)" != "$self" ]; then
      _VCF_RECORDS="$n"; _VCF_BROKEN="$n"; _VCF_REASON="self-hash"; return 1
    fi
    if [ "$pfield" != "$prev" ]; then
      _VCF_RECORDS="$n"; _VCF_BROKEN="$n"; _VCF_REASON="prev-link"; return 1
    fi
    prev="$self"
  done < "$log"
  _VCF_RECORDS="$n"; return 0
}

# `sluice egress --verify`: walk the hash chain of the egress audit log; OK only if every line's
# self-hash recomputes and its prev links to the previous line's self (genesis = 64 zeros). Exits
# non-zero on the first break (tamper / reorder / truncation) - a CI integrity gate on the receipts.
cmd_egress_verify() {
  # Parse the one optional flag strictly (mirrors cmd_scan/_drift_report): a typo'd gate flag must die,
  # not silently downgrade to the human path at exit 0 (a CI 'egress --verify --jsonn' would lose its JSON).
  local json=0
  case "${1:-}" in
    --json) json=1 ;;
    "")     ;;
    *)      die "usage: sluice egress --verify [--json]" ;;
  esac
  local log="${XDG_STATE_HOME:-$HOME/.local/state}/sluice/$slug/egress-log.jsonl"
  # No log = an empty chain: trivially intact (0 records), exit 0 - unchanged.
  if [ ! -f "$log" ]; then
    if [ "$json" = 1 ]; then echo '{"schema":"sluice.egress-verify/v1","verified":true,"records":0,"broken_line":null,"reason":null}'
    else echo "[sluice] no egress log yet at $(_tilde "$log")." >&2; fi
    return 0
  fi
  if _verify_chain_file "$log"; then
    if [ "$json" = 1 ]; then printf '{"schema":"sluice.egress-verify/v1","verified":true,"records":%d,"broken_line":null,"reason":null}\n' "$_VCF_RECORDS"
    else echo "[sluice] ${C_GRN}egress log verified${C_RST}: $_VCF_RECORDS record(s), hash chain intact ($(_tilde "$log"))"; fi
    return 0
  fi
  if [ "$json" = 1 ]; then
    local _bl="$_VCF_BROKEN"; [ -n "$_bl" ] || _bl=null
    printf '{"schema":"sluice.egress-verify/v1","verified":false,"records":%d,"broken_line":%s,"reason":"%s"}\n' "$_VCF_RECORDS" "$_bl" "$_VCF_REASON"
  else
    case "$_VCF_REASON" in
      prev-link) echo "[sluice] ${E_RED}egress log TAMPERED${E_RST}: line $_VCF_BROKEN prev-link broken - reordered or dropped ($(_tilde "$log"))" >&2 ;;
      unreadable) echo "[sluice] ${E_RED}egress log unreadable${E_RST}: $(_tilde "$log")" >&2 ;;
      *)          echo "[sluice] ${E_RED}egress log TAMPERED${E_RST}: line $_VCF_BROKEN self-hash mismatch ($(_tilde "$log"))" >&2 ;;
    esac
  fi
  return 1
}

# `sluice egress --verify --all [--json]`: walk EVERY box's egress chain in one pass - the fleet-wide
# integrity gate. Pure host-side file reads (no engine, no per-box config), so it covers orphaned boxes
# and runs with the daemon down. Exit 1 if any chain is broken/unreadable, 0 on an intact or empty fleet.
cmd_egress_verify_all() {
  local json=0
  case "${1:-}" in --json) json=1 ;; "") ;; *) die "usage: sluice egress --verify --all [--json]" ;; esac
  local store="${XDG_STATE_HOME:-$HOME/.local/state}/sluice" logs
  # LC_ALL=C slug order; the */ glob skips the dot-prefixed .policy-cache dir + the .mask-empty stub.
  logs="$(for _l in "$store"/*/egress-log.jsonl; do [ -f "$_l" ] && printf '%s\n' "$_l"; done | LC_ALL=C sort)"
  if [ -z "$logs" ]; then
    if [ "$json" = 1 ]; then echo '{"schema":"sluice.fleet-verify/v1","verified":true,"boxes_total":0,"boxes_broken":0,"boxes":[]}'
    else echo "[sluice] no egress logs yet under $(_tilde "$store")." >&2; fi
    return 0
  fi
  local total=0 broken=0 first=1 boxes_json="" log s bslug bok bl reason
  while IFS= read -r log; do
    [ -n "$log" ] || continue
    s="${log%/egress-log.jsonl}"; bslug="${s##*/}"
    total=$((total+1))
    if _verify_chain_file "$log"; then bok=true; bl=null; reason=null
    else bok=false; broken=$((broken+1)); bl="$_VCF_BROKEN"; [ -n "$bl" ] || bl=null; reason="\"$_VCF_REASON\""; fi
    if [ "$json" = 1 ]; then
      [ "$first" = 1 ] && first=0 || boxes_json="$boxes_json,"
      boxes_json="$boxes_json{\"box\":\"sluice-$(_json_esc "$bslug")\",\"slug\":\"$(_json_esc "$bslug")\",\"state_dir\":\"$(_json_esc "$s")\",\"records\":$_VCF_RECORDS,\"verified\":$bok,\"broken_line\":$bl,\"reason\":$reason}"
    elif [ "$bok" = true ]; then
      printf '  %-24s  %s record(s)  %sintact%s\n' "sluice-$bslug" "$_VCF_RECORDS" "$C_GRN" "$C_RST"
    elif [ "$_VCF_REASON" = unreadable ]; then
      printf '  %-24s  %sunreadable%s\n' "sluice-$bslug" "$C_RED" "$C_RST"
    else
      printf '  %-24s  %sTAMPERED%s  line %s (%s)\n' "sluice-$bslug" "$C_RED" "$C_RST" "$_VCF_BROKEN" "$_VCF_REASON"
    fi
  done <<EOF
$logs
EOF
  if [ "$json" = 1 ]; then
    local verified=true; [ "$broken" -gt 0 ] && verified=false
    printf '{"schema":"sluice.fleet-verify/v1","verified":%s,"boxes_total":%d,"boxes_broken":%d,"boxes":[%s]}\n' "$verified" "$total" "$broken" "$boxes_json"
  elif [ "$broken" -gt 0 ]; then
    echo "[sluice] ${E_RED}$broken of $total box(es) TAMPERED / unreadable${E_RST}" >&2
  else
    echo "[sluice] ${C_GRN}all $total box(es) intact${C_RST}"
  fi
  if [ "$broken" -gt 0 ]; then return 1; fi
  return 0
}

# `sluice egress --export --all`: concatenate every box's append-only JSONL log, slug-sorted, for a
# SIEM/CI to ingest the whole fleet at once. Each record carries its own `box`, so a consumer regroups
# by `.box` regardless of order. Host-side reads only (works with the daemon down / on orphans).
cmd_egress_export_all() {
  local store="${XDG_STATE_HOME:-$HOME/.local/state}/sluice" logs log
  logs="$(for _l in "$store"/*/egress-log.jsonl; do [ -f "$_l" ] && printf '%s\n' "$_l"; done | LC_ALL=C sort)"
  [ -n "$logs" ] || { echo "[sluice] no egress logs yet under $(_tilde "$store")." >&2; return 0; }
  while IFS= read -r log; do [ -n "$log" ] && cat "$log"; done <<EOF
$logs
EOF
}

# sluice.lock: a committable inventory of the built image. base ref + every apk
# (name/version/checksum) + global npm pkg, introspected from the image (awk/jq run in-image via a
# heredoc), sorted for stable diffs. Defined above cmd_doctor for the early `doctor` dispatch.
current_inventory() {
  local baseref bdig
  baseref="${SLUICE_BASE_IMAGE:-cgr.dev/chainguard/wolfi-base}"
  bdig="$("$ENGINE" image inspect "$baseref" --format '{{ if .RepoDigests }}{{ index .RepoDigests 0 }}{{ end }}' 2>/dev/null || true)"
  printf 'base  %s\n' "${bdig:-$baseref}"
  "$ENGINE" run --rm -i --entrypoint sh "$tag" 2>/dev/null <<'INTROSPECT' | LC_ALL=C sort -u
awk 'BEGIN{RS="";FS="\n"}{p=v=c="";for(i=1;i<=NF;i++){t=substr($i,1,2);if(t=="P:")p=substr($i,3);else if(t=="V:")v=substr($i,3);else if(t=="C:")c=substr($i,3)}if(p!="")printf "apk  %s %s %s\n",p,v,c}' /lib/apk/db/installed
npm ls -g --depth=0 --json 2>/dev/null | jq -r '(.dependencies // {})|to_entries[]|"npm  \(.key) \(.value.version)"' 2>/dev/null
command -v pip3 >/dev/null 2>&1 && su -s /bin/sh sluice -c 'HOME=/home/sluice pip3 list --format=json 2>/dev/null' 2>/dev/null | jq -r '.[]|"pip  \(.key//.name|ascii_downcase) \(.value//.version)"' 2>/dev/null   # as sluice: system + the project's --user site (root pip3 misses it)
command -v pipx >/dev/null 2>&1 && su -s /bin/sh sluice -c 'HOME=/home/sluice pipx list --json 2>/dev/null' 2>/dev/null | jq -r '(.venvs//{})|to_entries[]|.value.metadata.main_package|"pip  \(.package|ascii_downcase) \(.package_version)"' 2>/dev/null   # pipx apps live in isolated venvs
command -v gem  >/dev/null 2>&1 && gem list --local --quiet 2>/dev/null | awk '{name=$1;rest=$0;sub(/^[^(]*\(/,"",rest);sub(/\).*$/,"",rest);n=split(rest,vs,/, */);for(i=1;i<=n;i++){v=vs[i];sub(/^default: */,"",v);if(v!="")printf "gem  %s %s\n",name,v}}'
command -v go   >/dev/null 2>&1 && { gb=""; for d in "$(go env GOBIN 2>/dev/null)" "$(go env GOPATH 2>/dev/null)/bin" /home/sluice/go/bin; do [ -n "$d" ] && [ -d "$d" ] || continue; case " $gb " in *" $d "*) ;; *) gb="$gb $d";; esac; done; for d in $gb; do for f in "$d"/*; do [ -f "$f" ] && [ -x "$f" ] || continue; go version -m "$f" 2>/dev/null | awk '$1=="mod"{print "go  "$2" "$3; exit}'; done; done; }
command -v cargo >/dev/null 2>&1 && { for ch in "${CARGO_HOME:-$HOME/.cargo}" /home/sluice/.cargo /root/.cargo; do [ -f "$ch/.crates2.json" ] || continue; jq -r '.installs|keys[]|split(" ")|"cargo  \(.[0]) \(.[1])"' "$ch/.crates2.json" 2>/dev/null; break; done; }
true
INTROSPECT
}

# Build (if needed) and write ./sluice.lock from the image inventory.
write_lock() {
  maybe_build
  local lock="$PROJECT_DIR/sluice.lock" inv na nn np ng ngo nc parts deltarows="" had_lock=0
  inv="$(current_inventory)"
  # Fail CLOSED: current_inventory's in-image read is masked by a `sort -u` pipe and consumed via a
  # command substitution, so a failed engine read can't trip set -e - it returns base-ref only. A real
  # Wolfi box always has apks, so a missing apk line means the read failed; refuse to write a hollow lock
  # (a base-only artifact reported as success, then --check flags every real package as drift).
  printf '%s\n' "$inv" | grep -q '^apk ' || die "could not read the image inventory - refusing to write a hollow sluice.lock"
  # Capture the supply-chain delta vs the existing lock BEFORE overwriting (reuse $inv; no re-introspect).
  [ -f "$lock" ] && { had_lock=1; deltarows="$(classify_drift "$(lock_drift "$inv")")"; }
  {
    printf "# sluice.lock - inventory of the built sandbox image (%s).\n" "$tag"
    printf "# Audit/drift artifact, NOT a reproducibility guarantee (Wolfi apk is a rolling repo).\n"
    printf "# Generated by 'sluice lock'; refresh with 'sluice update'.\n"
    printf '%s\n' "$inv"
  } > "$lock"
  na="$(printf '%s\n' "$inv" | grep -c '^apk ' || true)"   # grep -c exits 1 on zero matches; tolerate
  nn="$(printf '%s\n' "$inv" | grep -c '^npm ' || true)"   # (a box with no global npm packages)
  np="$(printf '%s\n' "$inv" | grep -c '^pip ' || true)"
  ng="$(printf '%s\n' "$inv" | grep -c '^gem ' || true)"
  ngo="$(printf '%s\n' "$inv" | grep -c '^go ' || true)"
  nc="$(printf '%s\n' "$inv" | grep -c '^cargo ' || true)"
  parts="$na apk"
  [ "$nn" -gt 0 ]  && parts="$parts + $nn npm"
  [ "$np" -gt 0 ]  && parts="$parts + $np pip"
  [ "$ng" -gt 0 ]  && parts="$parts + $ng gem"
  [ "$ngo" -gt 0 ] && parts="$parts + $ngo go"
  [ "$nc" -gt 0 ]  && parts="$parts + $nc cargo"
  echo "[sluice] wrote $lock ($parts packages)"
  if [ "$had_lock" = 1 ] && [ -n "$deltarows" ]; then
    echo "[sluice] supply-chain delta since last lock: +$(printf '%s\n' "$deltarows" | grep -c '^add' || true) -$(printf '%s\n' "$deltarows" | grep -c '^del' || true) ~$(printf '%s\n' "$deltarows" | grep -c '^chg' || true)"
    printf '%s\n' "$deltarows" | render_drift_human
  elif [ "$had_lock" = 1 ]; then
    # C4: an unchanged re-lock is silent otherwise - confirm it, mirroring --check's "lock in sync".
    echo "[sluice] ${C_GRN}no supply-chain change since last lock${C_RST}"
  fi
}

# Pin inventory: current_inventory's package set (apk/npm/pip/gem/go/cargo, with the frozen
# `apk name ver checksum` shape) but with the base line replaced by a DIGEST-checked one. The pin's
# whole point is a rebuildable coordinate, so it fails closed if the base can't be resolved to a
# @sha256 digest - pulling the base once if the local engine has no RepoDigests yet.
_pin_inventory() {
  local baseref bdig
  baseref="${SLUICE_BASE_IMAGE:-cgr.dev/chainguard/wolfi-base}"
  bdig="$("$ENGINE" image inspect "$baseref" --format '{{ if .RepoDigests }}{{ index .RepoDigests 0 }}{{ end }}' 2>/dev/null || true)"
  if [ -z "$bdig" ]; then
    echo "[sluice] resolving the base image digest (pulling $baseref) ..." >&2
    "$ENGINE" pull "$baseref" >/dev/null 2>&1 || true
    bdig="$("$ENGINE" image inspect "$baseref" --format '{{ if .RepoDigests }}{{ index .RepoDigests 0 }}{{ end }}' 2>/dev/null || true)"
  fi
  printf 'base  %s\n' "${bdig:-$baseref}"
  current_inventory | grep -v '^base '   # drop current_inventory's own (maybe-digestless) base line
}

# `sluice lock --pin`: write ./sluice.pin, a committable replay manifest - the base pinned by digest
# plus every apk/npm/pip/gem/go/cargo name+version. `SLUICE_PIN=1` (M2) rebuilds converging on exactly
# these versions. Also refreshes sluice.lock from the same built image (they read one image, so they
# never disagree; the extra introspection is a no-op build + a second read). Fails closed on a hollow
# inventory or an unresolvable base digest - a pin that can't freeze its base is worse than none.
write_pin() {
  maybe_build
  local pin="$PROJECT_DIR/sluice.pin" inv base na
  inv="$(_pin_inventory)"
  printf '%s\n' "$inv" | grep -q '^apk ' || die "could not read the image inventory - refusing to write a hollow sluice.pin"
  base="$(printf '%s\n' "$inv" | awk '$1=="base"{print $2; exit}')"
  case "$base" in *@sha256:*) ;; *) die "could not resolve a base image digest - refusing to write a pin that cannot freeze its base (is the base image pullable?)" ;; esac
  {
    printf "# sluice.pin - pinned replay manifest for %s.\n" "$tag"
    printf "# Rebuild with SLUICE_PIN=1 to converge on these exact versions. Honest scope: an apk pin\n"
    printf "# fails CLOSED once Wolfi stops serving that version (rolling repo) - see docs/supply-chain.md.\n"
    printf "# 'base' pins the image by @sha256 digest; each '<eco>  <name>  <version>' line pins a package.\n"
    printf 'base  %s\n' "$base"
    printf '%s\n' "$inv" | grep -v '^base ' | LC_ALL=C sort
  } > "$pin"
  na="$(printf '%s\n' "$inv" | grep -c '^apk ' || true)"
  echo "[sluice] wrote $pin (base pinned by digest + $na apk + npm/pip/gem/go/cargo versions)"
  write_lock   # keep sluice.lock in lockstep (same image, so the two agree)
}

# Drifted lines between ./sluice.lock and the live image inventory ("< lock / > current"); empty =
# in sync. Optional $1 = a pre-computed inventory (so doctor doesn't introspect the image twice).
lock_drift() {
  local inv="${1:-$(current_inventory 2>/dev/null || true)}"
  diff <(grep -vE '^#' "$PROJECT_DIR/sluice.lock" 2>/dev/null || true) \
       <(printf '%s\n' "$inv") 2>/dev/null | grep -E '^[<>]' || true
}

# Classify raw lock_drift ("< old" / "> new") into sorted structured rows:
# "<op>\t<type>\t<name>\t<old>\t<new>", op = add|del|chg. $1 = pre-computed raw drift (else read fresh).
# Key = type+name+version so one name at two versions is del+add, not a bogus single chg (A7); apk
# carries its checksum into the value so a same-version rebuild renders a legible chg, not "1.0 -> 1.0" (A6).
classify_drift() {
  local raw TAB; TAB="$(printf '\t')"
  if [ $# -ge 1 ]; then raw="$1"; else raw="$(lock_drift)"; fi
  [ -n "$raw" ] || return 0
  printf '%s\n' "$raw" | awk '
    { type=$2;
      if (type=="base")    { key="base"; name="base"; val=$3 }
      else if (type=="apk"){ key=type SUBSEP $3 SUBSEP $4; name=$3; val=$4 ($5==""?"":" " $5) }
      else                 { key=type SUBSEP $3 SUBSEP $4; name=$3; val=$4 }
      if ($1=="<") { oldv[key]=val; haveo[key]=1 } else { newv[key]=val; haven[key]=1 }
      t[key]=type; nm[key]=name; seen[key]=1 }
    END{ for (k in seen) {
      if (haveo[k] && !haven[k])      printf "del\t%s\t%s\t%s\t\n",  t[k],nm[k],oldv[k];
      else if (!haveo[k] && haven[k]) printf "add\t%s\t%s\t\t%s\n",  t[k],nm[k],newv[k];
      else                            printf "chg\t%s\t%s\t%s\t%s\n",t[k],nm[k],oldv[k],newv[k] } }' \
  | LC_ALL=C sort -t"$TAB" -k2,2 -k3,3 -k4,4 -k5,5
}

# Render structured drift rows (stdin) as aligned, colored +/-/~ lines. $1=err -> stderr-gated colors
# (the --check path renders to stderr; write_lock/--diff render to stdout).
render_drift_human() {
  local g="$C_GRN" r="$C_RED" y="$C_YEL" x="$C_RST"
  [ "${1:-}" = err ] && { g="$E_GRN"; r="$E_RED"; y="$E_YEL"; x="$E_RST"; }
  awk -F"$(printf '\t')" -v g="$g" -v r="$r" -v y="$y" -v x="$x" '
    { op[NR]=$1; ty[NR]=$2; nm[NR]=$3; ov[NR]=$4; nv[NR]=$5;
      if(length($2)>wt)wt=length($2); if(length($3)>wn)wn=length($3) }
    END{ for(i=1;i<=NR;i++){
      sym=(op[i]=="add")?"+":(op[i]=="del")?"-":"~";
      col=(op[i]=="add")?g:(op[i]=="del")?r:y;
      if(op[i]=="chg")      printf "  %s%s%s %-*s %-*s %s  ->  %s\n", col,sym,x, wt,ty[i], wn,nm[i], ov[i], nv[i];
      else if(op[i]=="add") printf "  %s%s%s %-*s %-*s %s\n",          col,sym,x, wt,ty[i], wn,nm[i], nv[i];
      else                  printf "  %s%s%s %-*s %-*s %s\n",          col,sym,x, wt,ty[i], wn,nm[i], ov[i] } }'
}

# Render structured drift rows (stdin) as {in_sync,added,removed,changed[]} for CI.
render_drift_json() {
  awk -F"$(printf '\t')" '
    function j(s){ gsub(/\\/,"\\\\",s); gsub(/"/,"\\\"",s); return s }
    { if($1=="add")      a=a (a==""?"":",") sprintf("{\"type\":\"%s\",\"name\":\"%s\",\"version\":\"%s\"}",j($2),j($3),j($5));
      else if($1=="del") d=d (d==""?"":",") sprintf("{\"type\":\"%s\",\"name\":\"%s\",\"version\":\"%s\"}",j($2),j($3),j($4));
      else               c=c (c==""?"":",") sprintf("{\"type\":\"%s\",\"name\":\"%s\",\"from\":\"%s\",\"to\":\"%s\"}",j($2),j($3),j($4),j($5));
      n++ }
    END{ printf "{\"in_sync\":%s,\"added\":[%s],\"removed\":[%s],\"changed\":[%s]}\n", (n==0?"true":"false"), a, d, c }'
}

# Shared drift report for --check (exit 1 on drift), --diff (exit 0), and --enforce (strict). $1 =
# exit-on-drift, $2 = strict|"" (refuse to build/tolerate a stale image - a pure verifier); the REST are
# the user's flags (only --json), parsed strictly so a typo'd gate flag can't silently run a plain check.
_drift_report() {
  local on_drift="$1" strict=0 json=0; [ "${2:-}" = strict ] && strict=1; shift 2
  while [ "$#" -gt 0 ]; do
    case "$1" in
      --json) json=1 ;;
      *)      die "usage: sluice lock [--check|--diff|--enforce] [--json]" ;;
    esac
    shift
  done
  [ -f "$PROJECT_DIR/sluice.lock" ] || die "no sluice.lock to check against - run 'sluice lock' first"
  # A check verifies the artifact as built: build only if no image exists; if the image predates a
  # config edit, note it (on stderr, so --json stays clean) but still report against what's built -
  # a gate shouldn't silently rebuild (that's `sluice build`/`sluice lock`). --enforce is stricter
  # still: it refuses to build or to report against a stale image (a CI gate must not mutate).
  if image_missing; then [ "$strict" = 1 ] && die "no built image to enforce against - run 'sluice build' first"; build
  elif image_stale; then [ "$strict" = 1 ] && die "image predates config edits - rebuild before 'sluice lock --enforce'"; echo "[sluice] ${E_YEL}note${E_RST}: image predates config edits - run 'sluice build' to refresh" >&2; fi
  local rows; rows="$(classify_drift)"
  if [ "$json" = 1 ]; then
    [ -z "$rows" ] && { echo '{"in_sync":true,"added":[],"removed":[],"changed":[]}'; return 0; }
    printf '%s\n' "$rows" | render_drift_json; return "$on_drift"
  fi
  [ -z "$rows" ] && { echo "[sluice] ${C_GRN}lock in sync${C_RST}"; return 0; }
  if [ "$on_drift" = 1 ]; then
    echo "[sluice] ${E_RED}DRIFT${E_RST}: the built image differs from sluice.lock (+added -removed ~changed):" >&2
    printf '%s\n' "$rows" | render_drift_human err >&2
    # C2: don't dead-end on the rows - point at the fix (re-record the intended state, or rebuild if the image drifted).
    echo "[sluice] ${E_DIM}remedy${E_RST}: re-record with 'sluice lock' (accept this image), or 'sluice build' then re-check (rebuild to the locked state)." >&2
  else
    echo "[sluice] drift from sluice.lock (+added -removed ~changed):"
    printf '%s\n' "$rows" | render_drift_human
  fi
  return "$on_drift"
}

# `sluice lock --check [--json]`: fail (exit 1) if the built image drifted from the committed sluice.lock.
cmd_lock_check() { _drift_report 1 "" "$@"; }
# `sluice lock --diff [--json]`: same drift view, read-only (exit 0) - a local review, not a CI gate.
cmd_lock_diff()  { _drift_report 0 "" "$@"; }
# `sluice lock --enforce [--json]`: a strict CI gate - like --check, but refuses to build or to tolerate
# a stale image (verify the committed lock against the image as-built, no side effects). Gates against
# the committed lock, not bit-reproducibility (Wolfi apk is a rolling repo).
cmd_lock_enforce() { _drift_report 1 strict "$@"; }

# `sluice lock --sbom [--format cyclonedx|spdx]`: a deterministic SBOM (apk + npm + pip + gem + go +
# cargo purls) to stdout. Assembled in-image (jq lives there); apk components carry their SHA-1 integrity
# hash (the db's Q1 checksum, hex-decoded). No timestamp/serial + purl-sorted so it's byte-stable;
# base/toolver/tag via env. Default CycloneDX 1.6; --format spdx emits the same package set as SPDX 2.3.
cmd_sbom() {
  local fmt=cyclonedx
  while [ "$#" -gt 0 ]; do
    case "$1" in
      --format)   fmt="${2:-}"; [ -n "$fmt" ] || die "usage: sluice lock --sbom [--format cyclonedx|spdx]"; shift ;;
      --format=*) fmt="${1#--format=}" ;;
      *)          die "usage: sluice lock --sbom [--format cyclonedx|spdx]" ;;
    esac
    shift
  done
  case "$fmt" in cyclonedx|spdx) ;; *) die "invalid --sbom format '$fmt' (cyclonedx|spdx)" ;; esac
  maybe_build; _sbom_for "$tag" "$fmt"
}

# Emit the CycloneDX SBOM for an arbitrary image ref (introspected in-image). cmd_sbom passes the built
# project $tag; the hidden __sbom arm passes the base ref (so CI can attest the base's own SBOM).
_sbom_for() {
  local img="$1" baseref bdig
  baseref="${SLUICE_BASE_IMAGE:-cgr.dev/chainguard/wolfi-base}"
  bdig="$("$ENGINE" image inspect "$baseref" --format '{{ if .RepoDigests }}{{ index .RepoDigests 0 }}{{ end }}' 2>/dev/null || true)"
  "$ENGINE" run --rm -i -e "SBOM_BASE=${bdig:-$baseref}" -e "SBOM_TOOLVER=$SLUICE_VERSION" -e "SBOM_IMAGE=$img" \
    -e "SBOM_FORMAT=${2:-cyclonedx}" --entrypoint sh "$img" 2>/dev/null <<'SBOM'
SBOM_ARCH="$(apk --print-arch 2>/dev/null || uname -m)"; export SBOM_ARCH
{
  # apk: name, version, and the Q1<base64-sha1> checksum decoded to hex (4th field; empty if undecodable).
  awk 'BEGIN{RS="";FS="\n"}{p=v=c="";for(i=1;i<=NF;i++){t=substr($i,1,2);if(t=="P:")p=substr($i,3);else if(t=="V:")v=substr($i,3);else if(t=="C:")c=substr($i,3)}if(p!="")printf "%s\t%s\t%s\n",p,v,c}' /lib/apk/db/installed \
  | while IFS="$(printf '\t')" read -r p v c; do
      h=""; case "$c" in Q1*) h="$(printf '%s' "${c#Q1}" | base64 -d 2>/dev/null | od -An -tx1 2>/dev/null | tr -d ' \n')";; esac
      printf 'apk\t%s\t%s\t%s\n' "$p" "$v" "$h"
    done
  npm ls -g --depth=0 --json 2>/dev/null | jq -r '(.dependencies // {})|to_entries[]|"npm\t\(.key)\t\(.value.version)\t"' 2>/dev/null
  command -v pip3 >/dev/null 2>&1 && su -s /bin/sh sluice -c 'HOME=/home/sluice pip3 list --format=json 2>/dev/null' 2>/dev/null | jq -r '.[]|"pip\t\(.key//.name|ascii_downcase)\t\(.value//.version)\t"' 2>/dev/null   # as sluice: system + --user site
  command -v pipx >/dev/null 2>&1 && su -s /bin/sh sluice -c 'HOME=/home/sluice pipx list --json 2>/dev/null' 2>/dev/null | jq -r '(.venvs//{})|to_entries[]|.value.metadata.main_package|"pip\t\(.package|ascii_downcase)\t\(.package_version)\t"' 2>/dev/null   # pipx venvs
  command -v gem  >/dev/null 2>&1 && gem list --local --quiet 2>/dev/null | awk '{name=$1;rest=$0;sub(/^[^(]*\(/,"",rest);sub(/\).*$/,"",rest);n=split(rest,vs,/, */);for(i=1;i<=n;i++){v=vs[i];sub(/^default: */,"",v);if(v!="")printf "gem\t%s\t%s\t\n",name,v}}'
  command -v go   >/dev/null 2>&1 && { gb=""; for d in "$(go env GOBIN 2>/dev/null)" "$(go env GOPATH 2>/dev/null)/bin" /home/sluice/go/bin; do [ -n "$d" ] && [ -d "$d" ] || continue; case " $gb " in *" $d "*) ;; *) gb="$gb $d";; esac; done; for d in $gb; do for f in "$d"/*; do [ -f "$f" ] && [ -x "$f" ] || continue; go version -m "$f" 2>/dev/null | awk '$1=="mod"{printf "go\t%s\t%s\t\n",$2,$3; exit}'; done; done; }
  command -v cargo >/dev/null 2>&1 && { for ch in "${CARGO_HOME:-$HOME/.cargo}" /home/sluice/.cargo /root/.cargo; do [ -f "$ch/.crates2.json" ] || continue; jq -r '.installs|keys[]|split(" ")|"cargo\t\(.[0])\t\(.[1])\t"' "$ch/.crates2.json" 2>/dev/null; break; done; }
  true
} | jq -R -s '
  ( [ split("\n")[] | select(length>0) | split("\t")
      | { eco:.[0], name:.[1], version:.[2], hash:.[3] }
      | .purl = ( if   .eco=="apk"   then "pkg:apk/wolfi/"+.name+"@"+.version+"?arch="+env.SBOM_ARCH+"&distro=wolfi"
                  elif .eco=="npm"   then "pkg:npm/"+.name+"@"+.version
                  elif .eco=="pip"   then "pkg:pypi/"+.name+"@"+.version
                  elif .eco=="go"    then "pkg:golang/"+.name+"@"+.version
                  elif .eco=="cargo" then "pkg:cargo/"+.name+"@"+.version
                  else                    "pkg:gem/"+.name+"@"+.version end ) ]
    | unique_by(.purl) ) as $pkgs
  | if env.SBOM_FORMAT=="spdx"
    then { spdxVersion:"SPDX-2.3", dataLicense:"CC0-1.0", SPDXID:"SPDXRef-DOCUMENT",
           name:env.SBOM_IMAGE, documentNamespace:("https://sluice.invalid/"+env.SBOM_IMAGE),
           creationInfo:{ created:"1970-01-01T00:00:00Z", creators:[ "Tool: sluice-"+env.SBOM_TOOLVER ] },
           annotations:[ { annotationType:"OTHER", annotationDate:"1970-01-01T00:00:00Z",
                           annotator:("Tool: sluice-"+env.SBOM_TOOLVER), comment:("sluice:base "+env.SBOM_BASE) } ],
           packages:[ $pkgs[] | { SPDXID:("SPDXRef-Package-"+(.purl|gsub("[^A-Za-z0-9.-]";"-"))),
                                  name:.name, versionInfo:.version, downloadLocation:"NOASSERTION",
                                  externalRefs:[ { referenceCategory:"PACKAGE-MANAGER", referenceType:"purl", referenceLocator:.purl } ] }
                              + ( if (.hash // "") != "" then { checksums:[ { algorithm:"SHA1", checksumValue:.hash } ] } else {} end ) ],
           relationships:[ $pkgs[] | { spdxElementId:"SPDXRef-DOCUMENT", relationshipType:"DESCRIBES",
                                       relatedSpdxElement:("SPDXRef-Package-"+(.purl|gsub("[^A-Za-z0-9.-]";"-"))) } ] }
    else { bomFormat:"CycloneDX", specVersion:"1.6", version:1,
           metadata:{
             tools:{ components:[ { type:"application", name:"sluice", version:env.SBOM_TOOLVER } ] },
             component:{ type:"container", name:env.SBOM_IMAGE,
                         properties:[ { name:"sluice:base", value:env.SBOM_BASE } ] } },
           components: [ $pkgs[] | { type:"library", "bom-ref":.purl, name:.name, version:.version, purl:.purl }
                                   + ( if (.hash // "") != "" then { hashes:[ { alg:"SHA-1", content:.hash } ] } else {} end ) ] }
    end'
SBOM
}

# `sluice lock --scan [--json] [--fail-on <sev>]`: vuln-scan the box's SBOM with a HOST scanner (grype,
# else trivy - never baked, same as cosign-verify). Report-only by default; --fail-on <severity>
# (negligible|low|medium|high|critical) makes it a CI gate.
# Exit contract (normalized across scanners, since grype/trivy disagree on raw codes - grype exits 2 on
# a gated finding but 1 on a DB error, trivy exits 1 on a gated finding): 0 = clean, 3 = gate tripped
# (a finding at/above --fail-on), 4 = scanner failed to run (DB/catalog/parse error). Documented in
# docs/supply-chain.md.
cmd_scan() {
  local json=0 failon=""
  while [ "$#" -gt 0 ]; do
    case "$1" in
      --json)      json=1 ;;
      --fail-on)   failon="${2:-}"; [ -n "$failon" ] || die "usage: sluice lock --scan [--json] [--fail-on <severity>]"; shift ;;
      --fail-on=*) failon="${1#--fail-on=}" ;;
      *)           die "usage: sluice lock --scan [--json] [--fail-on <negligible|low|medium|high|critical>]" ;;
    esac
    shift
  done
  if [ -n "$failon" ]; then
    case "$failon" in negligible|low|medium|high|critical) ;; *) die "invalid --fail-on '$failon' (negligible|low|medium|high|critical)" ;; esac
  fi

  # Prefer grype (CycloneDX-native); trivy had a 2026 supply-chain compromise, so only as a fallback.
  local scanner=""
  if   command -v grype >/dev/null 2>&1; then scanner=grype
  elif command -v trivy >/dev/null 2>&1; then scanner=trivy; fi
  if [ -z "$scanner" ]; then
    if [ -n "$failon" ]; then die "no vulnerability scanner found but --fail-on was given - install grype to gate on CVEs (https://github.com/anchore/grype)"; fi
    echo "[sluice] ${E_YEL}note${E_RST}: no scanner found - install grype to enable 'lock --scan' (https://github.com/anchore/grype)" >&2
    return 0
  fi

  maybe_build
  local tmp rc; tmp="$(mktemp)"
  # A8: trap the temp NOW so a cmd_sbom failure under pipefail (which aborts before the trailing rm)
  # can't leak it - the lock arm arms no receipt, so this EXIT trap has nothing to clobber.
  # shellcheck disable=SC2064  # expand $tmp NOW: the local is gone when the trap fires
  trap "rm -f '$tmp'" EXIT
  cmd_sbom > "$tmp"   # reuse the CycloneDX SBOM; the inner maybe_build is a no-op now, so $tmp is clean
  # C3: report-only (no --fail-on) prints the bare scanner table with nothing signalling it did NOT gate;
  # frame it on stderr (exit 0 regardless; --fail-on <sev> turns it into a gate). --json stays a clean passthrough.
  if [ -z "$failon" ] && [ "$json" = 0 ]; then
    echo "[sluice] ${E_DIM}report-only scan (exit 0 regardless) - add --fail-on <negligible|low|medium|high|critical> to gate the build.${E_RST}" >&2
  fi
  if [ "$scanner" = grype ]; then
    local ga=(sbom:"$tmp")
    if [ "$json" = 1 ]; then ga+=(-o json); else ga+=(-o table); fi
    if [ -n "$failon" ]; then ga+=(--fail-on "$failon"); fi
    grype "${ga[@]}" && rc=0 || rc=$?
  else
    local sev=""
    case "$failon" in
      critical)   sev=CRITICAL ;;
      high)       sev=HIGH,CRITICAL ;;
      medium)     sev=MEDIUM,HIGH,CRITICAL ;;
      low)        sev=LOW,MEDIUM,HIGH,CRITICAL ;;
      negligible) sev=UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL ;;
    esac
    local ta=(sbom)
    if [ "$json" = 1 ]; then ta+=(--format json); else ta+=(--format table); fi
    # --exit-code 3 (not 1) so trivy's gate-trip is distinguishable from its generic error exit (1).
    if [ -n "$failon" ]; then ta+=(--severity "$sev" --exit-code 3); fi
    trivy "${ta[@]}" "$tmp" && rc=0 || rc=$?
  fi
  rm -f "$tmp"
  # Normalize the raw scanner rc to the sluice contract: 0 clean, 3 gate tripped, 4 scanner failed.
  # grype: 2 = fail-on matched. trivy: 3 = our --exit-code on a finding. Any OTHER non-zero = the
  # scanner broke (DB/catalog/parse), which must read differently from "a CVE gate tripped".
  case "$scanner/$rc" in
    */0)     rc=0 ;;
    grype/2) rc=3 ;;
    trivy/3) rc=3 ;;
    *)       rc=4 ;;
  esac
  return "$rc"
}

# `sluice doctor`: one-shot health + why-egress-is-blocked report
# --- in-repo protection scans (SLUICE_MASK; read by doctor here and mounted by the run path) ------

# Expand SLUICE_MASK (space-separated, project-root-relative globs) to the paths matching RIGHT NOW,
# one per line. Plain shell glob semantics: a slash-less pattern matches root-level entries only
# ("packages/*/.env" reaches deeper). Symlink matches are skipped - a mount over a link would shadow
# its TARGET, not the link. Invalid patterns (absolute, ..) are skipped here so doctor still reports
# the rest; the run path dies on them (mask_validate).
mask_matches() {
  [ -n "${SLUICE_MASK:-}" ] || return 0
  ( cd "$PROJECT_DIR" 2>/dev/null || exit 0
    set -f   # keep the PATTERNS literal while splitting; glob only in the inner loop
    for pat in ${SLUICE_MASK}; do
      case "$pat" in /*|*..*) continue ;; esac
      set +f
      for m in $pat; do
        [ -L "$m" ] && continue
        if [ -f "$m" ] || [ -d "$m" ]; then printf '%s\n' "$m"; fi
      done
      set -f
    done ) | sort -u
}

# True when some SLUICE_MASK pattern covers $1 (a project-relative path), mirroring the launch
# semantics above: a slash-less pattern only ever matches a root-level entry.
mask_covers() {
  local rel="$1" pat rc=1
  set -f   # the patterns must stay literal (case still glob-MATCHES under set -f)
  for pat in ${SLUICE_MASK:-}; do
    # shellcheck disable=SC2254  # $pat IS a glob - unquoted on purpose
    case "$pat" in
      /*|*..*) continue ;;
      */*) case "$rel" in $pat) rc=0; break ;; esac ;;
      *)   case "$rel" in */*) ;; $pat) rc=0; break ;; esac ;;
    esac
  done
  set +f
  return "$rc"
}

# Secret-looking files in the mount that no SLUICE_MASK pattern covers - doctor warns on these.
# Bounded so doctor stays fast: depth 3, vendor dirs pruned, first 50 WARNED (unmasked) hits.
# .example/.sample/.template variants are scaffolding, not secrets. The mask filter runs BEFORE the
# cap - capping raw find output (filesystem order) would let masked files eat the slots and hide a
# genuinely-unmasked secret past the cap (a false pass). The find is depth-limited + vendor-pruned,
# so the candidate set is small.
unmasked_secrets() {
  find "$PROJECT_DIR" -maxdepth 3 \
      \( -name .git -o -name node_modules -o -name vendor -o -name .venv -o -name venv \) -prune \
      -o -type f \( -name '.env*' -o -name '*.pem' -o -name '*key*.json' -o -name 'id_rsa*' \
                    -o -name 'id_ed25519*' -o -name '*.p12' -o -name '*.pfx' \) \
      ! -name '*.example' ! -name '*.sample' ! -name '*.template' -print 2>/dev/null \
    | while IFS= read -r f; do
        f="${f#"$PROJECT_DIR"/}"
        mask_covers "$f" || printf '%s\n' "$f"
      done | head -50
}

# Squash //, /./ and resolve .. TEXTUALLY (no symlink deref - the target may not exist). Enough to
# decide inside-vs-outside the mount; set -f keeps odd path segments from globbing.
_canon_path() {
  local p="$1" out="" seg oldIFS="$IFS"
  set -f; IFS=/
  for seg in $p; do
    case "$seg" in ''|.) ;; ..) out="${out%/*}" ;; *) out="$out/$seg" ;; esac
  done
  IFS="$oldIFS"; set +f
  printf '%s' "${out:-/}"
}

# Symlinks in the project dir whose target resolves OUTSIDE the mounted scope (the project dir, plus
# the git common dir when this is a worktree) - they work on the host but are broken inside the box
# (real case: .claude/CLAUDE.md -> ~/.claude/shared/... dangled silently and the agent ran without
# its instructions). Emits "rel<TAB>target". Bounded so doctor stays fast: depth 6, .git/vendor dirs
# pruned, first 200 links considered.
symlinks_outside_scope() {
  local proj common="" l tgt abs d TAB; TAB="$(printf '\t')"
  # Compare PHYSICAL paths throughout - on macOS /var is itself a symlink, and git reports the
  # common dir in physical form while $PROJECT_DIR/link targets may be logical.
  proj="$(cd "$PROJECT_DIR" 2>/dev/null && pwd -P || printf '%s' "$PROJECT_DIR")"
  if command -v git >/dev/null 2>&1 && git -C "$PROJECT_DIR" rev-parse --git-common-dir >/dev/null 2>&1; then
    common="$(git -C "$PROJECT_DIR" rev-parse --git-common-dir)"
    case "$common" in /*) ;; *) common="$PROJECT_DIR/$common";; esac
    common="$(cd "$common" 2>/dev/null && pwd -P || true)"
    case "$common/" in "$proj"/*) common="" ;; esac   # inside the project: already in scope
  fi
  find "$PROJECT_DIR" -maxdepth 6 \
      \( -name .git -o -name node_modules -o -name vendor -o -name .venv -o -name venv \
         -o -name target -o -name dist -o -name build -o -name .next -o -name __pycache__ \) -prune \
      -o -type l -print 2>/dev/null \
    | head -200 | while IFS= read -r l; do
        tgt="$(readlink "$l" 2>/dev/null)" || continue
        [ -n "$tgt" ] || continue
        case "$tgt" in /*) abs="$tgt" ;; *) abs="$(dirname "$l")/$tgt" ;; esac
        # physical resolution when the target's parent exists; textual squash for dangling targets
        if d="$(cd "$(dirname "$abs")" 2>/dev/null && pwd -P)"; then abs="$d/$(basename "$abs")"
        else abs="$(_canon_path "$abs")"; fi
        case "$abs/" in "$proj"/*|"$PROJECT_DIR"/*) continue ;; esac
        if [ -n "$common" ]; then case "$abs/" in "$common"/*) continue ;; esac; fi
        printf '%s%s%s\n' "${l#"$PROJECT_DIR"/}" "$TAB" "$tgt"
      done
}

_doc() { printf '  %-10s %s\n' "$1" "$2"; }

# Render a newline-separated list (stdin) as indented doctor bullets, capped at the first 10 with a
# "(+ N more)" tail - the shape the secret/symlink/blocked-host lists share. $1 = the SGR color for
# each item (e.g. $C_RED), default none. Items are run through _term_esc (control chars stripped) so a
# crafted hostname can't smuggle escapes into the readout. PURE: reads stdin, writes stdout, touches no
# globals/engine - so it's unit-testable in the no-Docker gate. Blank lines drop from the count + output.
_doctor_bullets() {
  local col="${1:-}" rst="" list n line
  [ -n "$col" ] && rst="$C_RST"
  list="$(cat)"                                   # slurp stdin once, then count + iterate from it
  n="$(printf '%s\n' "$list" | grep -c . || true)"
  [ "${n:-0}" -gt 0 ] || return 0
  printf '%s\n' "$list" | grep . | head -10 | while IFS= read -r line; do
    printf '             %s%s%s\n' "$col" "$(_term_esc "$line")" "$rst"
  done
  [ "$n" -gt 10 ] && printf '             %s(+ %s more)%s\n' "$C_DIM" "$((n - 10))" "$C_RST"
  return 0
}

# --- central egress policy (v2): deny-capable, ceiling-setting ------------------------------------
# Defined HERE (not next to apply_policy in the run-path slice) so the machinery exists before the
# early `doctor` dispatch can call policy_evaluate report-only. Sources, lowest trust first (a
# deny/forbid from ANY source is final): $SLUICE_POLICY_URL (env, per user/CI),
# ~/.config/sluice/policy.conf (user), /etc/sluice/policy.conf (root-owned - the org's MANAGED policy;
# tamper-resistant ONLY because a dev can't edit it without root, and the org pushes it). OSS ships the
# enforcement; the can't-remove-it property is the org's root-owned-file deployment. Line directives (a
# bare host = allow, back-compat): allow H | deny H | deny-ip CIDR | forbid SLUICE_X | forbid-laundering
# | max-allow-ips N. Host-side final gate BEFORE build/run (apply_policy): effective allowlist = (local
# + allow) - deny; a forbidden loosening knob / laundering host / denied or over-cap ALLOW_IPS makes us
# DIE. Inert when no policy is configured. A URL-fetched policy can be authenticated
# (SLUICE_POLICY_SIG/_IDENTITY cosign, or SLUICE_POLICY_SHA256 pin; _REQUIRE fails closed).
policy_configured() { [ -n "${SLUICE_POLICY_URL:-}" ] || [ -f "$HOME/.config/sluice/policy.conf" ] || [ -f /etc/sluice/policy.conf ]; }

# Authenticate the URL-fetched policy body (the untrusted source; the root-owned /etc file is
# filesystem-trusted). Fails CLOSED. SLUICE_POLICY_SHA256 pins the body hash (no cosign needed);
# SLUICE_POLICY_SIG (a cosign sign-blob bundle, path or URL) + SLUICE_POLICY_IDENTITY (expected signer
# regexp, + SLUICE_POLICY_ISSUER) verifies the signature; SLUICE_POLICY_REQUIRE=1 makes an unverifiable
# policy fatal even if neither is set.
_verify_policy_sig() {
  local body="$1" tmp sig sf got issuer="${SLUICE_POLICY_ISSUER:-https://token.actions.githubusercontent.com}"
  if [ -n "${SLUICE_POLICY_SHA256:-}" ]; then
    got="$(printf '%s' "$body" | _sha256)"
    [ "$got" = "$SLUICE_POLICY_SHA256" ] || die "policy body sha256 ($got) != pinned SLUICE_POLICY_SHA256 - refusing."
  fi
  if [ -n "${SLUICE_POLICY_SIG:-}" ]; then
    command -v cosign >/dev/null 2>&1 || die "SLUICE_POLICY_SIG is set but cosign is not installed - can't verify the policy signature."
    [ -n "${SLUICE_POLICY_IDENTITY:-}" ] || die "SLUICE_POLICY_SIG is set but SLUICE_POLICY_IDENTITY (expected signer) is not - refusing to verify against any identity."
    tmp="$(mktemp)"; printf '%s' "$body" > "$tmp"; sig="$SLUICE_POLICY_SIG"
    case "$sig" in http://*|https://*|file://*)
      sf="$(mktemp)"; curl -fsSL --max-time 10 "$SLUICE_POLICY_SIG" > "$sf" 2>/dev/null || { rm -f "$tmp" "$sf"; die "could not fetch SLUICE_POLICY_SIG=$SLUICE_POLICY_SIG"; }; sig="$sf" ;;
    esac
    if cosign verify-blob "$tmp" --bundle "$sig" \
         --certificate-identity-regexp "$SLUICE_POLICY_IDENTITY" --certificate-oidc-issuer "$issuer" >/dev/null 2>&1; then
      rm -f "$tmp"; [ -n "${sf:-}" ] && rm -f "$sf"
    else
      rm -f "$tmp"; [ -n "${sf:-}" ] && rm -f "$sf"
      die "policy signature verification failed (expected signer $SLUICE_POLICY_IDENTITY) - refusing."
    fi
  fi
  if [ "${SLUICE_POLICY_REQUIRE:-}" = 1 ] && [ -z "${SLUICE_POLICY_SIG:-}" ] && [ -z "${SLUICE_POLICY_SHA256:-}" ]; then
    die "SLUICE_POLICY_REQUIRE=1 but no SLUICE_POLICY_SIG / SLUICE_POLICY_SHA256 is configured - the policy is unverifiable."
  fi
  return 0
}

# Merged policy text from all sources (low->high precedence). A configured-but-unfetchable URL is fatal
# (a managed policy must never silently fall back to local-only); a URL body is authenticated before use.
_policy_raw() {
  local url="${SLUICE_POLICY_URL:-}" uf="$HOME/.config/sluice/policy.conf" sf="/etc/sluice/policy.conf" chunk
  if [ -n "$url" ]; then
    chunk="$(curl -fsSL --max-time 10 "$url" 2>/dev/null)" \
      || die "SLUICE_POLICY_URL=$url could not be fetched - refusing to run without the configured policy (make it reachable, or unset it)."
    _verify_policy_sig "$chunk"
    printf '%s\n' "$chunk"
  fi
  [ -f "$uf" ] && { cat "$uf"; echo; }
  [ -f "$sf" ] && { cat "$sf"; echo; }
  return 0   # a false final [ -f ] test would otherwise abort body=$(_policy_raw) under set -e
}

_ip2int() {
  local a b c d; IFS=. read -r a b c d <<<"${1:-0.0.0.0}"
  printf '%s' "$(( ((a&255)<<24)|((b&255)<<16)|((c&255)<<8)|(d&255) ))"
}
# 0 if IPv4 $1 is within $2 (ip or ip/bits).
_ip_in_cidr() {
  local ip="$1" base bits a b mask
  case "$2" in */*) base="${2%/*}"; bits="${2#*/}" ;; *) base="$2"; bits=32 ;; esac
  case "$bits" in ''|*[!0-9]*) bits=32 ;; esac
  a="$(_ip2int "$ip")"; b="$(_ip2int "$base")"
  [ "$bits" -le 0 ] && return 0
  [ "$bits" -ge 32 ] && { [ "$a" = "$b" ]; return; }
  mask=$(( 0xFFFFFFFF ^ ((1 << (32 - bits)) - 1) ))
  [ "$(( a & mask ))" -eq "$(( b & mask ))" ]
}
# 0 if host $1 is denied by the space-list $2 (exact, or a leading-dot wildcard matching subdomains).
_policy_denied_host() {
  local h="$1" d
  for d in $2; do
    [ "$h" = "$d" ] && return 0
    case "$d" in .*) case ".$h" in *"$d") return 0 ;; esac ;; esac
  done
  return 1
}

# 0 if the leading-dot allow wildcard $1 COVERS any deny token in the space-list $2 - i.e. allowing it
# would silently re-admit a host the policy denies (deny is host-granular; a .parent allow swallows it).
# Only meaningful for a leading-dot wildcard; an exact allow host is handled by _policy_denied_host.
_allow_covers_denied() {
  local w="$1" d db
  case "$w" in .*) ;; *) return 1 ;; esac
  for d in $2; do
    db="${d#.}"                          # a deny wildcard .x denies x + subs; covering x suffices
    case ".$db" in *"$w") return 0 ;; esac
  done
  return 1
}

# PURE policy evaluator: parse the merged policy, compute the effective allowlist + wildcard conflicts,
# and COLLECT every violation (with the exact human reason apply_policy dies with) into output globals -
# in the same order apply_policy refuses. It does NOT die (except via _policy_raw, whose fail-closed die
# on an UNREACHABLE policy URL is correct + shared), NOT mutate SLUICE_ALLOW_DOMAINS, NOT export, NOT
# echo. Both the run path (apply_policy, die-mode) and doctor (report-only) call it. Outputs:
#   _PEVAL_EFFECTIVE  effective allowlist = (local + allow) - deny  (the value apply_policy assigns)
#   _PEVAL_REFUSALS   newline-separated refusal reasons, in run-path die order (empty = clean)
#   _PEVAL_RSBASE     1 if require-signed-base (apply_policy exports SLUICE_REQUIRE_SIGNED)
#   _PEVAL_SRC        policy source label;  _PEVAL_SUMMARY  "N allow, N deny, N forbid"
#   _PEVAL_UNKNOWNS   unknown directive tokens;  _PEVAL_STRICT  1 if strict-unknown
policy_evaluate() {
  local body allow="" deny="" denyip="" forbid="" maxips="" maxhardcap="" launder=0 strict=0 rsbase=0 unknowns="" line verb arg
  body="$(_policy_raw)"
  while IFS= read -r line; do
    line="${line%%#*}"; line="$(printf '%s' "$line" | awk '{$1=$1};1')"; [ -n "$line" ] || continue
    verb="${line%% *}"; arg="${line#"$verb"}"; arg="$(printf '%s' "$arg" | awk '{$1=$1};1')"
    case "$verb" in
      allow)               allow="$allow $arg" ;;
      deny)                deny="$deny $arg" ;;
      deny-ip)             denyip="$denyip $arg" ;;
      forbid)              forbid="$forbid $arg" ;;
      forbid-laundering)   launder=1 ;;
      max-allow-ips)       maxips="$arg" ;;
      max-hard-cap-bytes)  maxhardcap="$arg" ;;
      strict-unknown)      strict=1 ;;
      require-signed-base) rsbase=1 ;;
      *) if [ -z "$arg" ] && printf '%s' "$verb" | grep -qE '^\.?[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$'; then allow="$allow $verb"
         else unknowns="$unknowns $verb"; fi ;;
    esac
  done <<EOF
$body
EOF
  _PEVAL_UNKNOWNS="$unknowns"; _PEVAL_STRICT="$strict"; _PEVAL_RSBASE="$rsbase"
  local refusals=""
  # Refusals are collected in the SAME order apply_policy dies on them, so dying on the first non-empty
  # line reproduces the run-path verdict exactly. (1) unknown directive(s) under strict-unknown.
  if [ -n "$unknowns" ] && [ "$strict" = 1 ]; then
    refusals="$refusals""policy: unknown directive(s):$unknowns - refusing (strict-unknown)."$'\n'
  fi
  # (2) forbidden loosening knobs: the org said no - the local config must not set one. Same per-knob
  # reason + same order as the run-path loop.
  local k
  for k in $forbid; do
    case "$k" in
      SLUICE_DNS_OPEN|SLUICE_ALLOW_DOH) if [ "${!k:-}" = 1 ]; then refusals="$refusals""policy forbids ${k}=1 (your config sets it) - remove it to run under this policy."$'\n'; fi ;;
      *) if [ -n "${!k:-}" ]; then refusals="$refusals""policy forbids setting ${k} (your config sets it) - remove it to run under this policy."$'\n'; fi ;;
    esac
  done
  # effective allowlist = (local + policy allow) - policy deny. (3) a leading-dot allow wildcard that
  # COVERS a deny token would silently re-admit a denied host - a conflict refusal.
  local merged eff="" h conflict=""
  merged="$(printf '%s %s' "${SLUICE_ALLOW_DOMAINS:-}" "$allow" | tr ' ' '\n' | sed '/^$/d' | sort -u)"
  set -f   # entries are not globs - keep a wildcard (e.g. *.s3.amazonaws.com) literal, no $PWD expansion (the case-based matchers below still glob-MATCH under set -f); spans all three split loops to the IPS loop
  for h in $merged; do
    if _policy_denied_host "$h" "$deny"; then continue
    elif _allow_covers_denied "$h" "$deny"; then conflict="$conflict $h"
    else eff="$eff $h"; fi
  done
  if [ -n "$conflict" ]; then refusals="$refusals""policy: allowlist wildcard(s)$conflict would re-admit a host the policy denies - narrow them to exact hosts to run under this policy (deny is final)."$'\n'; fi
  _PEVAL_EFFECTIVE="$(printf '%s' "$eff" | awk '{$1=$1};1')"
  # (4) forbid-laundering: any laundering-capable host left on the EFFECTIVE allowlist (matches the
  # run path, which checks the post-deny list).
  if [ "$launder" = 1 ]; then
    local risky=""; for h in $_PEVAL_EFFECTIVE; do if laundering_host "$h"; then risky="$risky $h"; fi; done
    if [ -n "$risky" ]; then refusals="$refusals""policy forbids laundering-capable allowlisted host(s):$risky"$'\n'; fi
  fi
  # (5) SLUICE_ALLOW_IPS matching a deny-ip, then (6) over the max-allow-ips cap. Same order, same count.
  local ipn=0 e ipp d
  for e in ${SLUICE_ALLOW_IPS:-}; do
    ipn=$((ipn+1)); ipp="${e%%:*}"; ipp="${ipp%%/*}"
    for d in $denyip; do if _ip_in_cidr "$ipp" "$d"; then refusals="$refusals""policy denies SLUICE_ALLOW_IPS '$e' (matches deny-ip $d)"$'\n'; fi; done
  done
  set +f
  case "$maxips" in ''|*[!0-9]*) ;; *) if [ "$ipn" -gt "$maxips" ]; then refusals="$refusals""policy caps SLUICE_ALLOW_IPS at $maxips (your config has $ipn)"$'\n'; fi ;; esac
  # (7) max-hard-cap-bytes N: the org mandates a PREVENTIVE egress ceiling <= N. Refuse if the box sets
  # none, sets a non-numeric one, or exceeds N - so a developer can't opt out of the volume bound.
  case "$maxhardcap" in
    ''|*[!0-9]*) ;;
    *) case "${SLUICE_EGRESS_HARD_CAP_BYTES:-}" in
         '')       refusals="$refusals""policy requires SLUICE_EGRESS_HARD_CAP_BYTES <= $maxhardcap (your config sets none)"$'\n' ;;
         *[!0-9]*) refusals="$refusals""policy requires a numeric SLUICE_EGRESS_HARD_CAP_BYTES <= $maxhardcap"$'\n' ;;
         *)        [ "$SLUICE_EGRESS_HARD_CAP_BYTES" -gt "$maxhardcap" ] && refusals="$refusals""policy caps SLUICE_EGRESS_HARD_CAP_BYTES at $maxhardcap (your config sets $SLUICE_EGRESS_HARD_CAP_BYTES)"$'\n' ;;
       esac ;;
  esac
  _PEVAL_REFUSALS="$refusals"
  # source + counts for visibility (banner/run line / doctor).
  _PEVAL_SRC="$([ -f /etc/sluice/policy.conf ] && echo /etc/sluice/policy.conf || { [ -f "$HOME/.config/sluice/policy.conf" ] && echo "$HOME/.config/sluice/policy.conf" || echo "${SLUICE_POLICY_URL:-}"; })"
  _PEVAL_SUMMARY="$(printf '%s allow, %s deny, %s forbid' "$(printf '%s' "$allow" | wc -w | tr -d ' ')" "$(printf '%s' "$deny" | wc -w | tr -d ' ')" "$(printf '%s' "$forbid" | wc -w | tr -d ' ')")"
}

# Doctor-only, REPORT-ONLY policy evaluation: run policy_evaluate WITHOUT dying or mutating anything,
# so doctor can show the post-deny effective allowlist + the refusals a run/build would hit. It runs in
# a child subshell so policy_evaluate's global writes don't leak into the rest of doctor's report. The
# subshell FIRST probes the policy source with a plain _policy_raw call: a `|| exit` makes an unreachable
# URL an honest non-zero subshell exit (relying on the body=$(_policy_raw) assignment inside
# policy_evaluate to propagate the die is unsafe - set -e is suppressed for a command whose status is
# being captured, which would silently yield an empty body). On success it prints the effective
# allowlist (line 1) then the refusal reasons (one per line); on an unreachable source it exits non-zero
# and we surface "unreachable" so doctor still COMPLETES. (The probe + policy_evaluate's own fetch means
# a URL policy is fetched twice on the doctor path - benign for a one-shot diagnostic.) Caller guards
# with policy_configured. Sets doctor-local: _DPE_STATUS (ok|unreachable), _DPE_EFF, _DPE_REFUSALS.
_doctor_policy_eval() {
  local blob rc
  blob="$( _policy_raw >/dev/null 2>&1 || exit 1
           policy_evaluate
           printf '%s\n' "$_PEVAL_EFFECTIVE"; printf '%s' "$_PEVAL_REFUSALS" )" && rc=0 || rc=$?
  if [ "${rc:-0}" -ne 0 ]; then _DPE_STATUS=unreachable; _DPE_EFF=""; _DPE_REFUSALS=""; return 0; fi
  _DPE_STATUS=ok
  _DPE_EFF="$(printf '%s' "$blob" | sed -n '1p')"
  _DPE_REFUSALS="$(printf '%s' "$blob" | sed '1d')"
}

# Run a command with a wall-clock bound so doctor never hangs on a black-hole engine (a wedged
# DOCKER_HOST makes `info`/`image inspect` block for 20s+). Uses timeout/gtimeout when present;
# stock macOS has neither, so fall back to a background pid + a killer that SIGKILLs it past the
# bound. Returns the command's status, or 124 on timeout (matching coreutils `timeout`). The killer
# is itself reaped so the fallback can't hang. bash-3.2 safe (no associative arrays, no `wait -n`).
_with_timeout() {
  local secs="$1"; shift
  if command -v timeout  >/dev/null 2>&1; then timeout  "$secs" "$@"; return $?; fi
  if command -v gtimeout >/dev/null 2>&1; then gtimeout "$secs" "$@"; return $?; fi
  local pid kpid rc
  "$@" & pid=$!
  ( sleep "$secs"; kill -KILL "$pid" 2>/dev/null ) & kpid=$!
  if wait "$pid" 2>/dev/null; then rc=$?; else rc=$?; fi
  kill -KILL "$kpid" 2>/dev/null; wait "$kpid" 2>/dev/null || true
  # 137 = 128+SIGKILL: the killer fired (timed out) -> normalize to coreutils' 124.
  [ "$rc" -eq 137 ] && rc=124
  return "$rc"
}

cmd_doctor() {
  [ "${1:-}" = --json ] && { cmd_doctor_json; return $?; }
  local eng="" v blocked _attn=0   # _attn: count of attention/warning sites, for the trailing verdict
  printf '%ssluice doctor%s\n' "$C_BLD" "$C_RST"
  if   [ -n "${SLUICE_ENGINE:-}" ]; then eng="$SLUICE_ENGINE"
  elif command -v docker >/dev/null 2>&1; then eng=docker
  elif command -v podman >/dev/null 2>&1; then eng=podman; fi
  if [ -n "$eng" ] && command -v "$eng" >/dev/null 2>&1; then
    ENGINE="$eng"; resolve_runner lenient
    if _with_timeout 5 "$eng" info >/dev/null 2>&1; then   # bound the probe: a black-hole DOCKER_HOST blocks 20s+
      _doc engine "$("$eng" --version 2>/dev/null | head -1)"
    else
      _doc engine "${C_RED}$("$eng" --version 2>/dev/null | head -1) - daemon not responding${C_RST} (is $eng running?)"
      eng=""; _attn=$((_attn+1))   # daemon down (or wedged/timed out): skip the engine-dependent checks below
    fi
  elif [ -n "${SLUICE_ENGINE:-}" ]; then
    # Explicitly named but absent: "install docker or podman" is the wrong remedy. Mirror resolve_engine's die.
    eng=""; _attn=$((_attn+1)); _doc engine "${C_RED}none${C_RST} - SLUICE_ENGINE='$SLUICE_ENGINE' not found on PATH"
  else
    eng=""; _attn=$((_attn+1)); _doc engine "${C_RED}none${C_RST} - install docker or podman"
  fi

  if ! PROJECT_CONFIG="$(find_config)"; then
    _attn=$((_attn+1)); _doc config "${C_RED}none${C_RST} - run 'sluice init' to scaffold one"
    _doctor_verdict "$_attn"; return 0
  fi
  PROJECT_DIR="$(cd "$(dirname "$PROJECT_CONFIG")" && pwd)"
  # Doctor is the command you run BECAUSE the config is broken, so a broken config must not abort it.
  # bash -n catches syntax errors; relaxing errexit around the source keeps a non-zero top-level line
  # from killing doctor. A literal top-level `exit` in the config still escapes (it can't be contained
  # without a subshell that would drop the vars derive_names + the report below need) - known limit.
  if bash -n "$PROJECT_CONFIG" 2>/dev/null; then
    _doc config "$(_tilde "$PROJECT_CONFIG")"
  else
    _attn=$((_attn+1))
    _doc config "${C_RED}$(_tilde "$PROJECT_CONFIG") (parse error)${C_RST} - 'bash -n' it; report continues with partial config"
  fi
  # shellcheck disable=SC1090
  set +e; . "$PROJECT_CONFIG" 2>/dev/null; set -e
  derive_names
  [ -n "${SLUICE_DESC:-}" ] && _doc desc "$SLUICE_DESC"
  if [ -n "${SLUICE_MOUNTS:-}" ]; then
    _doc mount "$(_tilde "$PROJECT_DIR") ${C_DIM}(+ extra mounts)${C_RST}"
    # List each extra bind + warn on a missing absolute host source (the engine errors on it at run).
    local _m _src
    set -f   # keep mount specs literal while splitting - no pathname expansion against $PWD
    for _m in ${SLUICE_MOUNTS}; do
      set +f
      _src="${_m%%:*}"
      case "$_src" in
        /*) if [ ! -e "$_src" ]; then _attn=$((_attn+1)); _doc "" "${C_DIM}$(_term_esc "$_m")${C_RST} ${C_YEL}host path not found - run will fail${C_RST}"
            else _doc "" "${C_DIM}$(_term_esc "$_m")${C_RST}"; fi ;;
        *)  _doc "" "${C_DIM}$(_term_esc "$_m")${C_RST}" ;;
      esac
      set -f
    done
    set +f
  else _doc mount "$(_tilde "$PROJECT_DIR")"; fi

  # SLUICE_MASK posture: what's shadowed now, and secret-looking files the box CAN still read.
  if [ -n "${SLUICE_MASK:-}" ]; then
    local _nm; _nm="$(mask_matches 2>/dev/null | grep -c . || true)"
    _doc mask "$SLUICE_MASK ${C_DIM}($_nm path(s) masked at launch)${C_RST}"
  fi
  local _unm _nu _uf
  _unm="$(unmasked_secrets 2>/dev/null || true)"
  if [ -n "$_unm" ]; then
    _attn=$((_attn+1))
    _nu="$(printf '%s\n' "$_unm" | grep -c . || true)"
    _doc "" "${C_YEL}note${C_RST}: $_nu secret-looking file(s) readable in the box - shadow them: SLUICE_MASK=\".env*\" (sluice.config.example.sh)"
    printf '%s\n' "$_unm" | head -10 | while IFS= read -r _uf; do
      printf '             %s\n' "$(_term_esc "$_uf")"
    done
    [ "$_nu" -gt 10 ] && _doc "" "${C_DIM}(+ $((_nu - 10)) more)${C_RST}"
  fi

  # Symlinks that leave the mounted scope work on the host but dangle inside the box - warn.
  local _links _nl _lp _lt _TAB; _TAB="$(printf '\t')"
  _links="$(symlinks_outside_scope 2>/dev/null || true)"
  if [ -n "$_links" ]; then
    _attn=$((_attn+1))
    _nl="$(printf '%s\n' "$_links" | grep -c . || true)"
    _doc symlinks "${C_YEL}$_nl link(s) point outside the box mount${C_RST} - will be broken inside the box:"
    printf '%s\n' "$_links" | head -10 | while IFS="$_TAB" read -r _lp _lt; do
      printf '             %s -> %s\n' "$(_term_esc "$_lp")" "$(_term_esc "$_lt")"
    done
    [ "$_nl" -gt 10 ] && _doc "" "${C_DIM}(+ $((_nl - 10)) more)${C_RST}"
  fi

  # Rootless podman can't enforce some knobs the way docker does - surface the caveats (see hardening.md).
  if [ -n "$eng" ] && _rootless_podman; then
    _doc podman "${C_DIM}rootless - pids/memory caps need cgroups-v2 + systemd delegation; needs netfilter modules loaded${C_RST}"
    { [ -n "${SLUICE_PIDS_LIMIT:-}" ] || [ -n "${SLUICE_MEMORY:-}" ]; } && { _attn=$((_attn+1)); _doc "" "${C_YEL}a pids/memory cap is set but may silently not apply under rootless podman${C_RST}"; }
    local _dp
    set -f   # split the ports list on whitespace, not glob it against $PWD
    for _dp in ${SLUICE_PORTS:-}; do
      set +f
      case "$_dp" in ''|*[!0-9]*) ;; *) [ "$_dp" -lt 1024 ] && { _attn=$((_attn+1)); _doc ports "${C_YEL}rootless podman can't publish host port $_dp (<1024)${C_RST}"; } ;; esac
      set -f
    done
    set +f
  fi

  if [ -n "$eng" ]; then
    if _with_timeout 5 "$eng" image inspect "$tag" >/dev/null 2>&1; then
      if [ "$(_with_timeout 5 "$eng" image inspect -f '{{ index .Config.Labels "sluice.confighash" }}' "$tag" 2>/dev/null || true)" = "$(config_hash)" ]; then
        _doc image "$tag built (${C_GRN}config current${C_RST})"
      else
        _attn=$((_attn+1))
        _doc image "$tag built (${C_YEL}config stale${C_RST} - run 'sluice rebuild')"
      fi
    else
      _doc image "$tag ${C_DIM}not built${C_RST} - run 'sluice build'"
    fi
  fi

  if [ -f "$PROJECT_DIR/sluice.lock" ]; then
    if [ -n "$eng" ] && _with_timeout 5 "$eng" image inspect "$tag" >/dev/null 2>&1; then
      local curinv drift npkgs
      curinv="$(current_inventory 2>/dev/null || true)"
      drift="$(lock_drift "$curinv")"
      npkgs="$(printf '%s\n' "$curinv" | grep -cE '^(apk|npm|pip|gem|go|cargo) ' || true)"
      if [ -z "$drift" ]; then
        _doc lock "${C_GRN}in sync${C_RST} ($npkgs pkgs)"
      else
        _attn=$((_attn+1))
        _doc lock "${C_YEL}drifted${C_RST} - $(printf '%s\n' "$drift" | grep -c .) line(s) changed since sluice.lock (run 'sluice update')"
      fi
    else
      _doc lock "${C_DIM}sluice.lock present - build to compare${C_RST}"
    fi
  else
    _doc lock "${C_DIM}none${C_RST} - run 'sluice lock' to record installed versions"
  fi

  # Pinned replay (SLUICE_PIN=1 + sluice.pin): show the pin state next to the lock rows.
  if [ -f "$PROJECT_DIR/sluice.pin" ]; then
    if [ "${SLUICE_PIN:-}" = 1 ]; then _doc pin "${C_GRN}SLUICE_PIN=1${C_RST} - build replays sluice.pin (verified against sluice.lock)"
    else _doc pin "${C_DIM}sluice.pin present${C_RST} - set SLUICE_PIN=1 to build from it (pinned replay)"; fi
  elif [ "${SLUICE_PIN:-}" = 1 ]; then
    _attn=$((_attn+1)); _doc pin "${C_RED}SLUICE_PIN=1 but no sluice.pin${C_RST} - run 'sluice lock --pin' first"
  fi

  if [ -n "${SLUICE_STATE_DIRS:-}" ]; then
    local nsd=0 _sd
    set -f   # dir names are not globs - count them, don't expand against $PWD
    for _sd in ${SLUICE_STATE_DIRS}; do nsd=$((nsd+1)); done
    set +f
    _doc state "$nsd dir(s) persisted at $(_tilde "${XDG_STATE_HOME:-$HOME/.local/state}/sluice/$slug")"
  fi

  [ -n "${SLUICE_OVERLAY_DIRS:-}" ] && _doc overlays "$SLUICE_OVERLAY_DIRS ${C_DIM}(box-local volume per dir, host contents untouched; 'sluice rm' deletes)${C_RST}"

  [ -n "${SLUICE_BASE_IMAGE:-}" ] && _doc base "$SLUICE_BASE_IMAGE ${C_DIM}(signed-base build; SLUICE_REQUIRE_SIGNED=${SLUICE_REQUIRE_SIGNED:-0})${C_RST}"
  # Active hardening posture (only the opt-ins that are on), so it's visible at a glance.
  local _hard=""
  [ -n "${SLUICE_SECCOMP:-}" ]          && _hard="$_hard seccomp=$SLUICE_SECCOMP"
  [ "${SLUICE_READONLY_ROOT:-}" = 1 ]   && _hard="$_hard readonly-root"
  [ "${SLUICE_WORKSPACE:-}" = overlay ] && _hard="$_hard workspace=overlay"
  [ -n "${SLUICE_RUNTIME:-}" ]          && _hard="$_hard runtime=$SLUICE_RUNTIME"
  [ -n "${SLUICE_MEMORY:-}" ]           && _hard="$_hard memory=$SLUICE_MEMORY"
  [ -n "${SLUICE_BUMP_DOMAINS:-}" ]     && _hard="$_hard tls-bump"
  [ -n "${SLUICE_EGRESS_HARD_CAP_BYTES:-}" ] && _hard="$_hard hard-cap=$SLUICE_EGRESS_HARD_CAP_BYTES"
  [ -n "${SLUICE_ALLOW_IPS_MAX_BYTES:-}" ]   && _hard="$_hard allow-ips-budget=$SLUICE_ALLOW_IPS_MAX_BYTES"
  [ "${SLUICE_DNS_AUDIT:-}" = 1 ]       && _hard="$_hard dns-audit"
  # Always show a harden row: opt-ins when on, else the effective default posture the run path applies.
  if [ -n "$_hard" ]; then _doc harden "${_hard# }"
  else _doc harden "${C_DIM}defaults (seccomp=default, root rw, workspace=bind)${C_RST}"; fi
  # Bump upload controls are a no-op without a bumped host to filter - flag the misconfig.
  if [ -z "${SLUICE_BUMP_DOMAINS:-}" ] && { [ -n "${SLUICE_BUMP_METHODS:-}" ] || [ -n "${SLUICE_BUMP_MAX_BODY:-}" ]; }; then
    _attn=$((_attn+1)); _doc "" "${C_YEL}note${C_RST}: SLUICE_BUMP_METHODS/SLUICE_BUMP_MAX_BODY set but SLUICE_BUMP_DOMAINS is empty - the bump controls are a no-op (nothing is decrypted to filter)"
  fi

  [ -n "${SLUICE_PORTS:-}" ] && _doc ports "$SLUICE_PORTS ${C_DIM}(published on 127.0.0.1)${C_RST}"
  # Under a managed policy, the live allowlist is (local + allow) - deny: show what would ACTUALLY be
  # allowed, plus any refusal a run/build would die on - report-only, doctor never dies or mutates.
  local _eff_allow="${SLUICE_ALLOW_DOMAINS:-}" _pol_unreachable=""
  if policy_configured; then
    _doctor_policy_eval
    if [ "$_DPE_STATUS" = unreachable ]; then
      _pol_unreachable=1; _attn=$((_attn+1))
      _doc allowlist "${SLUICE_ALLOW_DOMAINS:-(none beyond base)} ${C_DIM}(pre-policy; policy unreachable)${C_RST}"
    else
      _eff_allow="$_DPE_EFF"
      _doc allowlist "${_eff_allow:-(none beyond base)} ${C_DIM}(effective, post-policy deny/wildcard)${C_RST}"
      if [ -n "$_DPE_REFUSALS" ]; then
        local _nr; _nr="$(printf '%s\n' "$_DPE_REFUSALS" | grep -c . || true)"
        _attn=$((_attn+_nr))   # each refusal line is an attention site
        printf '%s\n' "$_DPE_REFUSALS" | while IFS= read -r _r; do
          [ -n "$_r" ] && _doc "" "${C_RED}policy would refuse:${C_RST} $_r"
        done
      fi
    fi
  else
    _doc allowlist "${SLUICE_ALLOW_DOMAINS:-(none beyond base)}"
  fi
  local _risky="" _doh="" _h
  set -f   # the allowlist entries are not globs - keep a wildcard (e.g. *.s3.amazonaws.com) literal
  for _h in ${_eff_allow:-}; do
    laundering_host "$_h" && _risky="$_risky $_h"
    doh_listed "$_h" && _doh="$_doh $_h"
  done
  set +f
  # Hazard notes by severity: the genuinely exfil-capable ones lead (DoH-allowed, then laundering);
  # the informational lines (base:, benign still-blocked DoH, ips:, policy) come after.
  if [ -n "$_doh" ] && [ "${SLUICE_ALLOW_DOH:-}" = 1 ]; then
    _attn=$((_attn+1)); _doc "" "${C_YEL}note${C_RST}: DoH resolver(s) allowed AND SLUICE_ALLOW_DOH=1 -${_doh} - DNS-over-HTTPS exfil is possible"
  fi
  if [ -n "$_risky" ]; then
    _attn=$((_attn+1)); _doc "" "${C_YEL}note${C_RST}: shared host(s) an attacker can also write to -${_risky} - data can be laundered out (splice, not decrypt); keep the allowlist tight"
  fi
  _doc "" "base: $(base_domains)"
  if [ -n "$_doh" ] && [ "${SLUICE_ALLOW_DOH:-}" != 1 ]; then
    _doc "" "${C_DIM}note: DoH resolver(s) on the allowlist -${_doh} - still BLOCKED (DoH exfil channel); SLUICE_ALLOW_DOH=1 to permit${C_RST}"
  fi
  [ -n "${SLUICE_ALLOW_IPS:-}" ] && _doc ips "$SLUICE_ALLOW_IPS ${C_DIM}(direct egress, bypasses the hostname filter; bare ip = any port, ip:port scopes it)${C_RST}"
  if [ -n "${SLUICE_POLICY_URL:-}" ]; then
    if [ -n "$_pol_unreachable" ]; then _doc policy "${C_RED}$SLUICE_POLICY_URL - unreachable${C_RST} (run/build would refuse to start)"
    else _doc policy "$SLUICE_POLICY_URL"; fi
  fi

  if [ -n "${SLUICE_ENV:-}" ]; then
    set -f   # var names are not globs - keep them literal, no $PWD expansion
    for v in $SLUICE_ENV; do
      if [ -n "${!v:-}" ]; then _doc auth "$v ${C_GRN}set${C_RST}"; else _doc auth "$v ${C_RED}unset${C_RST} - export it on the host"; fi
    done
    set +f
  fi

  if [ -n "$eng" ] && running; then
    local _RCPT_OFFSET; _RCPT_OFFSET="$(last_run_offset)"   # scope to last run (matches 'sluice learn'); empty -> full log
    blocked="$(blocked_new 2>/dev/null || true)"
    if [ -n "$blocked" ]; then
      _attn=$((_attn+1))
      _doc egress "${C_RED}$(printf '%s\n' "$blocked" | grep -c .) host(s) blocked${C_RST} (last run) - run 'sluice learn' to allow:"
      printf '%s\n' "$blocked" | _doctor_bullets "$C_RED"
    elif ! _audit_readable; then
      _attn=$((_attn+1))
      _doc egress "${C_YEL}egress audit unavailable${C_RST} - could not read the in-box log (pids limit?); can't confirm nothing was blocked"
    else
      _doc egress "${C_GRN}no blocked egress needs allowing${C_RST}"
    fi
  else
    _doc egress "${C_DIM}sandbox not running${C_RST} - start it, exercise the app, re-run 'sluice doctor'"
  fi

  _doctor_verdict "$_attn"
}

# Trailing one-line verdict for the human readout: $1 = the attention/warning count accumulated by
# cmd_doctor. Zero -> a green all-clear; otherwise a yellow "N item(s) need attention" (singular/plural
# correct). PURE (reads its arg, writes one line) so the verdict copy is unit-testable without an engine.
_doctor_verdict() {
  local n="${1:-0}"
  if [ "$n" -eq 0 ]; then
    printf '  %sok%s: ready - no action needed\n' "$C_GRN" "$C_RST"
  elif [ "$n" -eq 1 ]; then
    printf '  %s1 item needs attention%s\n' "$C_YEL" "$C_RST"
  else
    printf '  %s%s items need attention%s\n' "$C_YEL" "$n" "$C_RST"
  fi
}

# `sluice doctor --json`: the machine-readable posture (kept separate so the human path above is
# untouched; only one branch runs per invocation, so the shared gathering isn't double-work).
cmd_doctor_json() {
  local eng="" engine_ver="" daemon=false engine_found=true
  if   [ -n "${SLUICE_ENGINE:-}" ]; then eng="$SLUICE_ENGINE"
  elif command -v docker >/dev/null 2>&1; then eng=docker
  elif command -v podman >/dev/null 2>&1; then eng=podman; fi
  if [ -n "$eng" ] && command -v "$eng" >/dev/null 2>&1; then
    ENGINE="$eng"; resolve_runner lenient; engine_ver="$("$eng" --version 2>/dev/null | head -1)"
    # Bound the probe (A3): a wedged DOCKER_HOST otherwise blocks doctor 20s+. timeout -> daemon:false.
    _with_timeout 5 "$eng" info >/dev/null 2>&1 && daemon=true || eng=""
  else eng=""; [ -z "${SLUICE_ENGINE:-}" ] || engine_found=false; fi   # explicit-but-missing engine: A9

  if ! PROJECT_CONFIG="$(find_config)"; then
    printf '{"engine":"%s","engine_found":%s,"daemon":%s,"config":null}\n' "$(_json_esc "$engine_ver")" "$engine_found" "$daemon"; return 0
  fi
  PROJECT_DIR="$(cd "$(dirname "$PROJECT_CONFIG")" && pwd)"
  # A broken config must not abort doctor: bash -n catches syntax errors; relaxed errexit around the
  # source keeps a non-zero top-level line from killing it. A literal `exit` in the config still
  # escapes (can't be contained without a subshell that drops the vars below) - known limit. Either
  # way this path ALWAYS prints one valid JSON object (config_error carries the signal), never empty.
  local config_error=false
  bash -n "$PROJECT_CONFIG" 2>/dev/null || config_error=true
  # shellcheck disable=SC1090
  set +e; . "$PROJECT_CONFIG" 2>/dev/null; set -e
  derive_names

  local img_built=false img_stale=false
  if [ -n "$eng" ] && _with_timeout 5 "$eng" image inspect "$tag" >/dev/null 2>&1; then
    img_built=true
    [ "$(_with_timeout 5 "$eng" image inspect -f '{{ index .Config.Labels "sluice.confighash" }}' "$tag" 2>/dev/null || true)" = "$(config_hash)" ] || img_stale=true
  fi

  local lock="none"
  if [ -f "$PROJECT_DIR/sluice.lock" ]; then
    if [ -n "$eng" ] && _with_timeout 5 "$eng" image inspect "$tag" >/dev/null 2>&1; then
      [ -z "$(lock_drift 2>/dev/null || true)" ] && lock="in-sync" || lock="drifted"
    else lock="present-unbuilt"; fi
  fi

  local running_b=false blocked="" egress_unavail=false
  if [ -n "$eng" ] && running; then
    running_b=true; local _RCPT_OFFSET; _RCPT_OFFSET="$(last_run_offset)"
    blocked="$(blocked_new 2>/dev/null || true)"
    # Empty may mean "nothing blocked" or a failed read; distinguish so blocked isn't a false [].
    [ -z "$blocked" ] && ! _audit_readable && egress_unavail=true
  fi

  local nsd=0 _sd; set -f; for _sd in ${SLUICE_STATE_DIRS:-}; do nsd=$((nsd+1)); done; set +f   # dir names aren't globs

  local auth_json="[" first=1 v setv
  set -f   # var names are not globs - keep them literal, no $PWD expansion
  for v in ${SLUICE_ENV:-}; do
    [ "$first" = 1 ] && first=0 || auth_json="$auth_json,"
    setv=false; [ -n "${!v:-}" ] && setv=true
    auth_json="$auth_json{\"var\":\"$(_json_esc "$v")\",\"set\":$setv}"
  done
  set +f
  auth_json="$auth_json]"

  local mask_pats mask_hits mask_unm links_json
  # tr (not word-splitting) keeps the glob patterns literal - no pathname expansion against $PWD
  mask_pats="$(printf '%s' "${SLUICE_MASK:-}" | tr ' \t' '\n\n' | _json_arr)"
  mask_hits="$(mask_matches 2>/dev/null | _json_arr || true)"
  mask_unm="$(unmasked_secrets 2>/dev/null | _json_arr || true)"
  links_json="$(symlinks_outside_scope 2>/dev/null | cut -f1 | _json_arr || true)"
  local overlays_json
  overlays_json="$(printf '%s' "${SLUICE_OVERLAY_DIRS:-}" | tr ' \t' '\n\n' | _json_arr)"

  # Hardening posture: which opt-in layers are active (pure config reads, no engine calls).
  local _ro=false _ws=false _bump=false
  [ "${SLUICE_READONLY_ROOT:-}" = 1 ]   && _ro=true
  [ "${SLUICE_WORKSPACE:-}" = overlay ] && _ws=true
  [ -n "${SLUICE_BUMP_DOMAINS:-}" ]     && _bump=true
  local _pinned=false; [ "${SLUICE_PIN:-}" = 1 ] && _pinned=true
  local _dnsaudit=false; [ "${SLUICE_DNS_AUDIT:-}" = 1 ] && _dnsaudit=true
  local hardening_json
  hardening_json="$(printf '{"seccomp":"%s","readonly_root":%s,"workspace_overlay":%s,"runtime":"%s","memory":"%s","pids_limit":"%s","tls_bump":%s,"hard_cap_bytes":"%s","allow_ips_max_bytes":"%s","dns_audit":%s,"bump_methods":"%s","bump_max_body":"%s","pinned":%s}' \
    "$(_json_esc "${SLUICE_SECCOMP:-default}")" "$_ro" "$_ws" "$(_json_esc "${SLUICE_RUNTIME:-}")" \
    "$(_json_esc "${SLUICE_MEMORY:-}")" "$(_json_esc "${SLUICE_PIDS_LIMIT:-4096}")" "$_bump" \
    "$(_json_esc "${SLUICE_EGRESS_HARD_CAP_BYTES:-}")" "$(_json_esc "${SLUICE_ALLOW_IPS_MAX_BYTES:-}")" "$_dnsaudit" \
    "$(_json_esc "${SLUICE_BUMP_METHODS:-}")" "$(_json_esc "${SLUICE_BUMP_MAX_BODY:-}")" "$_pinned")"

  # Exfil-surface risk: allowlisted hosts that are writable laundering channels or DoH resolvers.
  local _risky="" _doh="" _h _allowdoh=false
  set -f   # entries are not globs - keep a wildcard (e.g. *.s3.amazonaws.com) literal, no expansion
  for _h in ${SLUICE_ALLOW_DOMAINS:-}; do
    laundering_host "$_h" && _risky="$_risky$_h
"
    doh_listed "$_h" && _doh="$_doh$_h
"
  done
  set +f
  [ "${SLUICE_ALLOW_DOH:-}" = 1 ] && _allowdoh=true
  local risk_json
  risk_json="$(printf '{"laundering_hosts":%s,"doh_hosts":%s,"allow_doh":%s}' \
    "$(printf '%s' "$_risky" | _json_arr)" "$(printf '%s' "$_doh" | _json_arr)" "$_allowdoh")"

  # Managed-policy posture: the post-deny effective allowlist + the refusals a run/build would die on
  # (report-only - _doctor_policy_eval never dies/mutates). null when no policy is configured; a
  # configured-but-unfetchable URL surfaces as reachable:false (doctor still completes).
  local policy_json=null
  if policy_configured; then
    _doctor_policy_eval
    if [ "$_DPE_STATUS" = unreachable ]; then
      policy_json='{"reachable":false,"effective_allowlist":[],"refusals":[]}'
    else
      policy_json="$(printf '{"reachable":true,"effective_allowlist":%s,"refusals":%s}' \
        "$(printf '%s' "$_DPE_EFF" | tr ' ' '\n' | _json_arr)" \
        "$(printf '%s' "$_DPE_REFUSALS" | _json_arr)")"
    fi
  fi

  # Extra binds as objects, each carrying whether its host source exists (a missing absolute source
  # passes doctor today but errors the engine at run - A7). set -f keeps a glob-y spec literal (A5).
  local mounts_json="[" _mf=1 _m _src _ex
  set -f
  for _m in ${SLUICE_MOUNTS:-}; do
    set +f
    _src="${_m%%:*}"; _ex=true
    case "$_src" in /*) [ -e "$_src" ] || _ex=false ;; esac
    [ "$_mf" = 1 ] && _mf=0 || mounts_json="$mounts_json,"
    mounts_json="$mounts_json{\"spec\":\"$(_json_esc "$_m")\",\"exists\":$_ex}"
    set -f
  done
  set +f
  mounts_json="$mounts_json]"

  # A5: build these arrays via the tr-split idiom (mask/overlay use it) - NOT `printf '%s\n' $unquoted`,
  # which pathname-expands a glob metachar in config (e.g. SLUICE_ALLOW_IPS="1.2.3.4 *") against $PWD.
  local allow_json ports_json ips_json blocked_json
  allow_json="$(printf '%s'   "${SLUICE_ALLOW_DOMAINS:-}" | tr ' \t' '\n\n' | _json_arr)"
  ports_json="$(printf '%s'   "${SLUICE_PORTS:-}"         | tr ' \t' '\n\n' | _json_arr)"
  ips_json="$(printf '%s'     "${SLUICE_ALLOW_IPS:-}"     | tr ' \t' '\n\n' | _json_arr)"
  blocked_json="$(printf '%s' "$blocked"                  | tr ' \t' '\n\n' | _json_arr)"
  [ "$egress_unavail" = true ] && blocked_json=null

  # rootless podman can't enforce pids/memory caps or bind ports <1024 the way docker does (additive field).
  local rootless_podman=false; [ -n "$eng" ] && _rootless_podman && rootless_podman=true

  printf '{"schema":"sluice.doctor/v1","engine":"%s","engine_found":%s,"daemon":%s,"rootless_podman":%s,"config":"%s","config_error":%s,"project_dir":"%s","name":"%s","desc":"%s","image":{"tag":"%s","built":%s,"stale":%s},"lock":"%s","allowlist":%s,"base":%s,"ports":%s,"allow_ips":%s,"base_image":"%s","policy_url":"%s","policy":%s,"state_dirs":%s,"overlay_dirs":%s,"mounts":%s,"auth":%s,"hardening":%s,"mask":{"patterns":%s,"masked":%s,"unmasked_secrets":%s},"risk":%s,"broken_symlinks":%s,"egress":{"running":%s,"blocked":%s}}\n' \
    "$(_json_esc "$engine_ver")" "$engine_found" "$daemon" "$rootless_podman" "$(_json_esc "$PROJECT_CONFIG")" "$config_error" "$(_json_esc "$PROJECT_DIR")" "$(_json_esc "$tag")" "$(_json_esc "${SLUICE_DESC:-}")" \
    "$(_json_esc "$tag")" "$img_built" "$img_stale" "$lock" \
    "$allow_json" "$(base_domains | tr ' ' '\n' | _json_arr)" \
    "$ports_json" "$ips_json" "$(_json_esc "${SLUICE_BASE_IMAGE:-}")" \
    "$(_json_esc "${SLUICE_POLICY_URL:-}")" "$policy_json" "$nsd" "$overlays_json" "$mounts_json" "$auth_json" "$hardening_json" \
    "$mask_pats" "$mask_hits" "$mask_unm" "$risk_json" "$links_json" \
    "$running_b" "$blocked_json"
}

# Verbatim-embed a box's latest egress-receipt.json into `ls --json` (a fleet<->audit join, so a
# dashboard reads posture + last egress in one call), or `null`. The file is sluice's own single-line
# JSON (_persist_receipt, src/80), so a guarded raw embed needs no parsing and stays valid JSON: it must
# be one line, open with the known schema, close with `}`, and carry no control byte - else null. Fail
# closed on anything malformed so `ls --json` never emits broken JSON. Its integrity is attested by
# `egress --verify`, not by ls (documented in docs/operations.md).
_last_receipt_json() {
  local f="$1/egress-receipt.json" line nl
  [ -f "$f" ] || { printf 'null'; return 0; }
  nl="$(wc -l < "$f" 2>/dev/null | tr -d ' ')"; case "$nl" in ''|*[!0-9]*) nl=2 ;; esac
  [ "$nl" -le 1 ] || { printf 'null'; return 0; }           # multi-line = not our single-line receipt
  line="$(head -1 "$f" 2>/dev/null)"
  case "$line" in '{"schema":"sluice.egress/v1"'*'}') ;; *) printf 'null'; return 0 ;; esac
  printf '%s' "$line" | LC_ALL=C grep -q '[[:cntrl:]]' && { printf 'null'; return 0; }
  printf '%s' "$line"
}

# `sluice ls`: a derived, read-only table of every built sluice box on this machine
# Boxes are identified by the sluice.confighash label (baked since early versions); path/stack/desc
# come from labels baked at build, so nothing is sourced here. The box matching $PWD is marked '*'.
cmd_ls() {
  local mode="" only_running="" only_orphans="" stack_filter="" egress="" imgs here=""
  while [ "$#" -gt 0 ]; do
    case "$1" in
      --json)    mode=--json ;;
      --running) only_running=1 ;;
      --orphans) only_orphans=1 ;;
      --egress)  egress=1 ;;
      --stack)   [ -n "${2:-}" ] || die "usage: sluice ls --stack <name>"; stack_filter="$2"; shift ;;
      --stack=*) stack_filter="${1#--stack=}" ;;
      *)         die "usage: sluice ls [--running] [--orphans] [--stack <name>] [--egress] [--json]" ;;
    esac
    shift
  done

  # sed strips podman's localhost/ prefix so the name matches the canonical sluice-<slug> everywhere
  # downstream (ps filter, box_blocked_count, the ${#sluice-} slug); grep exits 1 on no-match, tolerated
  # so the empty-state branch stays reachable under set -e.
  imgs="$("$ENGINE" image ls --filter label=sluice.confighash --format '{{.Repository}}' 2>/dev/null | sed 's,^localhost/,,' | grep -v '^<none>$' | sort -u || true)"
  if [ -z "$imgs" ]; then
    if ! "$ENGINE" info >/dev/null 2>&1; then   # binary exists (dispatch checked), so empty == daemon down
      [ "$mode" = --json ] && { echo '[]'; return 0; }
      echo "[sluice] ${C_RED}${ENGINE} daemon not responding${C_RST} - is it running?"
      return 0
    fi
    [ "$mode" = --json ] && { echo '[]'; return 0; }
    echo "[sluice] no sluice boxes built yet - run 'sluice' in a project."
    return 0
  fi
  # Current box = the project dir for $PWD's config (no sourcing), matched on the sluice.project label.
  if here="$(find_config 2>/dev/null)"; then here="$(cd "$(dirname "$here")" && pwd)"; else here=""; fi

  # Gather labels + container state into parallel arrays, applying filters as we go. (Kept as a plain
  # while-loop, NOT a $(...) capture: a case pattern's ) inside command substitution mis-parses on bash 3.2.)
  local names=() stats=() projs=() stacks=() descs=() curs=() orphs=() allows=() ports_=() locks=() blocks=() ovls=() chashes=()
  local name proj stack desc status cur orphan allowcount portslbl lock blocked ovl chash
  while IFS= read -r name; do
    [ -n "$name" ] || continue
    proj="$( "$ENGINE" image inspect -f '{{ index .Config.Labels "sluice.project" }}' "$name" 2>/dev/null || true)"
    stack="$("$ENGINE" image inspect -f '{{ index .Config.Labels "sluice.stack" }}'   "$name" 2>/dev/null || true)"
    desc="$( "$ENGINE" image inspect -f '{{ index .Config.Labels "sluice.desc" }}'    "$name" 2>/dev/null || true)"
    allowcount="$("$ENGINE" image inspect -f '{{ index .Config.Labels "sluice.allowcount" }}' "$name" 2>/dev/null || true)"
    portslbl="$(  "$ENGINE" image inspect -f '{{ index .Config.Labels "sluice.ports" }}'      "$name" 2>/dev/null || true)"
    ovl="$(       "$ENGINE" image inspect -f '{{ index .Config.Labels "sluice.overlays" }}'   "$name" 2>/dev/null || true)"
    chash="$(     "$ENGINE" image inspect -f '{{ index .Config.Labels "sluice.confighash" }}' "$name" 2>/dev/null || true)"
    case "$proj"       in "<no value>") proj=""       ;; esac
    case "$stack"      in "<no value>") stack=""      ;; esac
    case "$desc"       in "<no value>") desc=""       ;; esac
    case "$allowcount" in "<no value>") allowcount="" ;; esac
    case "$portslbl"   in "<no value>") portslbl=""   ;; esac
    case "$ovl"        in "<no value>") ovl=""        ;; esac
    case "$chash"      in "<no value>") chash=""      ;; esac
    orphan=false; [ -n "$proj" ] && [ ! -d "$proj" ] && orphan=true
    if   "$RUNNER" ps    --filter "name=$name" --filter status=running --format '{{.Names}}' 2>/dev/null | grep -qx "$name"; then status=running
    elif "$RUNNER" ps -a --filter "name=$name" --format '{{.Names}}' 2>/dev/null | grep -qx "$name"; then status=stopped
    elif [ "$orphan" = true ]; then status=orphan
    else status=built; fi
    cur=false; [ -n "$here" ] && [ "$proj" = "$here" ] && cur=true
    [ -n "$only_running" ] && [ "$status" != running ] && continue
    [ -n "$only_orphans" ] && [ "$orphan" != true ]    && continue
    [ -n "$stack_filter" ] && case "$stack" in *"$stack_filter"*) ;; *) continue ;; esac
    lock="-"; [ -n "$proj" ] && [ -f "$proj/sluice.lock" ] && lock=locked
    blocked=""; [ -n "$egress" ] && [ "$status" = running ] && blocked="$(box_blocked_count "$name")"   # opt-in: execs into the box
    names+=("$name"); stats+=("$status"); projs+=("$proj"); stacks+=("$stack"); descs+=("$desc"); curs+=("$cur"); orphs+=("$orphan")
    allows+=("$allowcount"); ports_+=("$portslbl"); locks+=("$lock"); blocks+=("$blocked"); ovls+=("$ovl"); chashes+=("$chash")
  done <<EOF
$imgs
EOF

  if [ "${#names[@]}" -eq 0 ]; then
    [ "$mode" = --json ] && { echo '[]'; return 0; }
    echo "[sluice] no sluice boxes match the given filters."
    return 0
  fi

  # Render order: current first, then running, then name. Build "ckey<TAB>rkey<TAB>name<TAB>idx",
  # sort, read the indices back (this $(...) holds no case pattern, so it's bash-3.2-safe).
  local TAB; TAB="$(printf '\t')"
  local order=() ckey rkey idx sorted
  sorted="$(
    for idx in "${!names[@]}"; do
      ckey=1; [ "${curs[$idx]}" = true ]     && ckey=0
      rkey=1; [ "${stats[$idx]}" = running ] && rkey=0
      printf '%s\t%s\t%s\t%s\n' "$ckey" "$rkey" "${names[$idx]}" "$idx"
    done | sort -t"$TAB" -k1,1 -k2,2 -k3,3
  )"
  while IFS="$TAB" read -r ckey rkey name idx; do
    [ -n "$idx" ] && order+=("$idx")
  done <<EOF
$sorted
EOF

  local i j ac lk pjson ojson bjson _slug _sdir _lr _chjson
  if [ "$mode" = --json ]; then
    printf '['
    for j in "${!order[@]}"; do
      i="${order[$j]}"
      [ "$j" -gt 0 ] && printf ','
      ac="${allows[$i]}"; [ -n "$ac" ] || ac=null              # null = un-rebuilt box (label absent), not 0
      lk=false; [ "${locks[$i]}" = locked ] && lk=true
      # tr-split (like overlays) keeps a glob metachar in the label literal - no pathname expansion against $PWD
      pjson="$(printf '%s' "${ports_[$i]}" | tr ' \t' '\n\n' | _json_arr)"
      ojson="$(printf '%s' "${ovls[$i]}" | tr ' \t' '\n\n' | _json_arr)"
      # confighash (null on an un-rebuilt/pre-posture image) + state_dir + last egress receipt (a
      # fleet<->audit join): all pure file/label reads, so the ls "nothing sourced here" invariant holds.
      _chjson=null; [ -n "${chashes[$i]}" ] && _chjson="\"$(_json_esc "${chashes[$i]}")\""
      _slug="${names[$i]#sluice-}"
      _sdir="${XDG_STATE_HOME:-$HOME/.local/state}/sluice/$_slug"
      _lr="$(_last_receipt_json "$_sdir")"
      bjson=""; if [ -n "$egress" ]; then
        # null = not running OR audit unreadable (unknown) - never a defaulted 0 over a failed read
        if [ "${stats[$i]}" = running ] && [ -n "${blocks[$i]}" ]; then bjson=",\"blocked\":${blocks[$i]}"; else bjson=',"blocked":null'; fi
      fi
      printf '{"schema":"sluice.box/v1","name":"%s","status":"%s","stack":"%s","path":"%s","description":"%s","current":%s,"orphan":%s,"allow_count":%s,"ports":%s,"overlay_dirs":%s,"locked":%s,"confighash":%s,"state_dir":"%s","last_receipt":%s%s}' \
        "$(_json_esc "${names[$i]}")" "$(_json_esc "${stats[$i]}")" "$(_json_esc "${stacks[$i]}")" \
        "$(_json_esc "${projs[$i]}")" "$(_json_esc "${descs[$i]}")" "${curs[$i]}" "${orphs[$i]}" \
        "$ac" "$pjson" "$ojson" "$lk" "$_chjson" "$(_json_esc "$_sdir")" "$_lr" "$bjson"
    done
    printf ']\n'; return 0
  fi

  # human table: compute display values + column widths (indexed by original position)
  local wname=4 wstat=6 wstack=5 wallow=5 wports=5 wlock=4 wblk=7 wpath=4
  local vpaths=() cpaths=() dstacks=() ddescs=() marks=() dallows=() dports=() dlocks=() dblks=()
  local dpath vpath cpath dstack ddesc mark dallow dport dlock dblk
  for i in "${!names[@]}"; do
    dpath="${projs[$i]}"; case "$dpath" in "$HOME"/*) dpath="~${dpath#"$HOME"}";; "$HOME") dpath="~";; esac
    [ -n "$dpath" ] || dpath="-"
    if [ "${orphs[$i]}" = true ]; then vpath="$dpath (gone)"; cpath="$dpath ${C_DIM}(gone)${C_RST}"; else vpath="$dpath"; cpath="$dpath"; fi
    dstack="${stacks[$i]}"; [ -n "$dstack" ] || dstack="-"
    ddesc="${descs[$i]}";   [ -n "$ddesc" ]  || ddesc="-"
    dallow="${allows[$i]}"; [ -n "$dallow" ] || dallow="-"
    dport="${ports_[$i]}";  [ -n "$dport" ]  || dport="-"
    dlock="${locks[$i]}"
    dblk="${blocks[$i]}"    # ? = running but audit unreadable (unknown); - = not running / not asked
    if [ -z "$dblk" ]; then dblk="-"; [ -n "$egress" ] && [ "${stats[$i]}" = running ] && dblk="?"; fi
    mark=" "; [ "${curs[$i]}" = true ] && mark="*"
    vpaths[$i]="$vpath"; cpaths[$i]="$cpath"; dstacks[$i]="$dstack"; ddescs[$i]="$ddesc"; marks[$i]="$mark"
    dallows[$i]="$dallow"; dports[$i]="$dport"; dlocks[$i]="$dlock"; dblks[$i]="$dblk"
    [ ${#names[$i]} -gt "$wname"  ] && wname=${#names[$i]}
    [ ${#stats[$i]} -gt "$wstat"  ] && wstat=${#stats[$i]}
    [ ${#dstack}    -gt "$wstack" ] && wstack=${#dstack}
    [ ${#dallow}    -gt "$wallow" ] && wallow=${#dallow}
    [ ${#dport}     -gt "$wports" ] && wports=${#dport}
    [ ${#dlock}     -gt "$wlock"  ] && wlock=${#dlock}
    [ ${#dblk}      -gt "$wblk"   ] && wblk=${#dblk}
    [ ${#vpath}     -gt "$wpath"  ] && wpath=${#vpath}
  done

  echo "${C_BLD}sluice boxes${C_RST}"
  printf '  %s' "$C_DIM"
  printf '%-*s  %-*s  %-*s  %-*s  %-*s  %-*s' "$wname" NAME "$wstat" STATUS "$wstack" STACK "$wallow" ALLOW "$wports" PORTS "$wlock" LOCK
  [ -n "$egress" ] && printf '  %-*s' "$wblk" BLOCKED
  printf '  %-*s  %s%s\n' "$wpath" PATH DESCRIPTION "$C_RST"
  local st sc stcol pad pcell
  for j in "${!order[@]}"; do
    i="${order[$j]}"
    st="${stats[$i]}"; case "$st" in running) sc="$C_GRN";; *) sc="$C_DIM";; esac
    stcol="${sc}$(printf '%-*s' "$wstat" "$st")${C_RST}"   # pad first, then color, so columns stay aligned
    pad=$(( wpath - ${#vpaths[$i]} )); [ "$pad" -lt 0 ] && pad=0
    pcell="${cpaths[$i]}$(printf '%*s' "$pad" '')"         # color the (gone) suffix, then pad on visible width
    printf '%s %-*s  %s  %-*s  %-*s  %-*s  %-*s' "${marks[$i]}" \
      "$wname" "${names[$i]}" "$stcol" "$wstack" "${dstacks[$i]}" "$wallow" "${dallows[$i]}" "$wports" "${dports[$i]}" "$wlock" "${dlocks[$i]}"
    [ -n "$egress" ] && printf '  %-*s' "$wblk" "${dblks[$i]}"
    printf '  %s  %s\n' "$pcell" "${ddescs[$i]}"
  done
}

# sluice-gate mark on human entries; stderr + TTY-only + SLUICE_NO_BANNER-suppressible.
# The banner's second line, computed live when a config is in scope: engine, allowlist size, the
# active hardening, and whether in-repo secrets are masked - so the launch moment doubles as a
# one-glance "what's the cage" check. Sets _POSTURE_TEXT + _POSTURE_RISK (risk = an allowlisted
# laundering host, or a DoH resolver allowed with SLUICE_ALLOW_DOH=1). Fast: no find/engine calls.
# $1 = separator (UTF-8 dot or ASCII dash).
_banner_posture() {
  local sep="$1" h hard=""
  _POSTURE_TEXT="$(basename "${RUNNER:-${ENGINE:-${SLUICE_ENGINE:-docker}}}")"
  _POSTURE_TEXT="$_POSTURE_TEXT${sep}$(allowed_domains | wc -w | tr -d ' ') hosts"
  [ -n "${SLUICE_SECCOMP:-}" ]          && hard="${hard:+$hard+}seccomp"
  [ "${SLUICE_READONLY_ROOT:-}" = 1 ]   && hard="${hard:+$hard+}readonly"
  [ "${SLUICE_WORKSPACE:-}" = overlay ] && hard="${hard:+$hard+}overlay"
  [ "${SLUICE_RUNTIME:-}" = kata ]      && hard="${hard:+$hard+}kata"
  [ -n "$hard" ]            && _POSTURE_TEXT="$_POSTURE_TEXT${sep}$hard"
  [ -n "${SLUICE_MASK:-}" ] && _POSTURE_TEXT="$_POSTURE_TEXT${sep}masked"
  _POSTURE_RISK=""
  for h in ${SLUICE_ALLOW_DOMAINS:-}; do laundering_host "$h" && { _POSTURE_RISK=1; break; }; done
  [ -z "$_POSTURE_RISK" ] && [ "${SLUICE_ALLOW_DOH:-}" = 1 ] && \
    for h in ${SLUICE_ALLOW_DOMAINS:-}; do doh_listed "$h" && { _POSTURE_RISK=1; break; }; done
  return 0
}

banner() {
  [ -z "${_BANNER_SHOWN:-}" ] || return 0
  [ -t 2 ] || return 0
  [ -z "${SLUICE_NO_BANNER:-}" ] || return 0
  _BANNER_SHOWN=1
  local d="" r="" gn="" yl="" ver utf sep line2 pc cols
  ver="v$(sluice_version)"
  [ -z "${NO_COLOR:-}" ] && { d=$'\033[2m'; r=$'\033[0m'; gn=$'\033[32m'; yl=$'\033[33m'; }
  case "${LC_ALL:-${LC_CTYPE:-${LANG:-}}}" in *UTF-8*|*utf8*|*UTF8*) utf=1; sep=" · " ;; *) utf=""; sep=" - " ;; esac

  # Second line: the live posture when a config is sourced (run/shell), else the static tagline.
  if [ -n "${PROJECT_CONFIG:-}" ]; then
    _banner_posture "$sep"; line2="$_POSTURE_TEXT"; pc="$gn"
    [ -n "$_POSTURE_RISK" ] && { pc="$yl"; line2="$line2${sep}exfil risk"; }   # word, not just color (NO_COLOR/colorblind)
  else
    line2="sandboxed, firewalled, non-root"; pc="$d"
  fi

  # Narrow terminal (Option A): one compact line, no art.
  cols="${COLUMNS:-$(tput cols 2>/dev/null || echo 80)}"
  case "$cols" in ''|*[!0-9]*) cols=80 ;; esac
  if [ "$cols" -lt 34 ]; then
    printf '%ssluice %s%s %s%s%s\n' "$d" "$ver" "$r" "$pc" "$line2" "$r" >&2
    return 0
  fi

  if [ -n "$utf" ]; then
    printf '%s   ◯\n ┌─┴─┐\n │ █ │   sluice %s\n │≈≈≈│   %s%s%s\n └───┘\n%s' \
      "$d" "$ver" "$pc" "$line2" "$d" "$r" >&2
  else
    printf '%s   o\n +-+-+\n | # |   sluice %s\n |~~~|   %s%s%s\n +---+\n%s' \
      "$d" "$ver" "$pc" "$line2" "$d" "$r" >&2
  fi
}

# container engine (docker, else podman; override SLUICE_ENGINE). $ENGINE always BUILDS the image; $RUNNER
# runs/execs the box. They're the same binary unless SLUICE_RUNTIME asks for an own-kernel micro-VM (Kata),
# which Docker can't drive - then the box runs under nerdctl/containerd while $ENGINE still builds it and
# the image is loaded across. Default (unset SLUICE_RUNTIME): RUNNER==ENGINE, so every run path is unchanged.
resolve_engine() {
  ENGINE="${SLUICE_ENGINE:-}"
  if [ -z "$ENGINE" ]; then
    if command -v docker >/dev/null 2>&1; then ENGINE=docker
    elif command -v podman >/dev/null 2>&1; then ENGINE=podman
    else die "no container engine found - install docker or podman, or set SLUICE_ENGINE"; fi
  fi
  command -v "$ENGINE" >/dev/null 2>&1 || die "SLUICE_ENGINE=$ENGINE not found on PATH"
  # SLUICE_RUNTIME=kata: preflight the containerd/nerdctl/Kata stack (run commands need it working).
  if [ "${SLUICE_RUNTIME:-}" = kata ]; then
    command -v nerdctl >/dev/null 2>&1 || die "SLUICE_RUNTIME=kata needs nerdctl (containerd) on PATH - install nerdctl + Kata Containers (Linux only)"
    nerdctl info >/dev/null 2>&1 || die "SLUICE_RUNTIME=kata: nerdctl/containerd is not reachable - is containerd running, and do you have privileges? (Kata wants a rootful containerd; try running sluice as root)"
    command -v containerd-shim-kata-v2 >/dev/null 2>&1 || echo "[sluice] note: containerd-shim-kata-v2 not on PATH - SLUICE_RUNTIME=kata needs the Kata shim installed for containerd" >&2
  fi
  resolve_runner
}

# $RUNNER (the run/exec engine) + Kata run opts from SLUICE_RUNTIME, given $ENGINE (the build engine).
# Shared by resolve_engine (which preflights first) and the lenient `doctor` probe. Default -> RUNNER==ENGINE.
# $1=lenient: warn + fall back to RUNNER==ENGINE on an unknown value instead of dying, so `doctor` -
# the command you run BECAUSE the runtime is misconfigured - still reports.
resolve_runner() {
  RUNNER="$ENGINE"; RUNTIME_RUN_OPTS=()
  case "${SLUICE_RUNTIME:-}" in
    kata) RUNNER=nerdctl; RUNTIME_RUN_OPTS=(--runtime io.containerd.kata.v2) ;;
    ""|docker|podman|"$ENGINE") ;;
    *) if [ "${1:-}" = lenient ]; then
         echo "${E_YEL:-}[sluice] note:${E_RST:-} SLUICE_RUNTIME='${SLUICE_RUNTIME}' is not supported - falling back to $ENGINE (use 'kata' or leave it unset)." >&2
       else
         die "SLUICE_RUNTIME='${SLUICE_RUNTIME:-}' is not supported (use 'kata', or leave it unset for docker/podman)"
       fi ;;
  esac
}

# Rootless podman maps the host user to container-root, so the entrypoint's chown of the bind-mounted
# repo to the uid-1000 sluice user lands host-side as a SUBUID - the host user then can't write their
# own repo. keep-id:uid=1000,gid=1000 maps the host user straight onto the sluice uid: the mount reads
# as uid 1000 in the box (writable, and the entrypoint chown then no-ops on it, so the host repo stays
# host-owned), while container-internal overlay/state volumes are still chowned as before. Needs podman
# >= 4.3 (the keep-id uid/gid options); older podman gets a warning + the recovery command. Appends to
# RUNTIME_RUN_OPTS so it composes with the Kata opt. Docker and rootful podman are unaffected (no-op).
# Call from the box-start path only, not the lenient doctor probe (avoids the extra calls + warning).
# True iff $RUNNER is rootless podman (basename-strip so a full path still matches). One `podman info`.
_rootless_podman() { [ "${RUNNER##*/}" = podman ] && [ "$(podman info --format '{{.Host.Security.Rootless}}' 2>/dev/null)" = true ]; }
resolve_podman_userns() {
  _rootless_podman || return 0
  local v maj min
  v="$(podman version --format '{{.Client.Version}}' 2>/dev/null)"
  maj="${v%%.*}"; min="${v#*.}"; min="${min%%.*}"
  case "$maj" in ''|*[!0-9]*) maj=0 ;; esac
  case "$min" in ''|*[!0-9]*) min=0 ;; esac
  if [ "$maj" -gt 4 ] || { [ "$maj" -eq 4 ] && [ "$min" -ge 3 ]; }; then
    RUNTIME_RUN_OPTS+=("--userns=keep-id:uid=1000,gid=1000")
  else
    echo "${E_YEL:-}[sluice] WARNING:${E_RST:-} rootless podman ${v:-<unknown>} lacks keep-id:uid= (needs >= 4.3); the box will chown the mounted repo to a subuid on the host. Recover write access with: podman unshare chown -R 0:0 \"\$PWD\"" >&2
  fi
}

# SLUICE_RUNTIME=kata builds with $ENGINE but runs under nerdctl/containerd, which keeps its own image
# store; cross the built image over. No-op when builder == runner. $1=force reloads even if present (after
# a rebuild the runtime's copy is stale).
runtime_sync_image() {
  [ "$RUNNER" = "$ENGINE" ] && return 0
  if [ "${1:-}" != force ] && "$RUNNER" image inspect "$tag" >/dev/null 2>&1; then return 0; fi
  echo "[sluice] loading $tag into the $RUNNER runtime ..." >&2
  "$ENGINE" save "$tag" | "$RUNNER" load >/dev/null 2>&1 \
    || die "SLUICE_RUNTIME=${SLUICE_RUNTIME:-} - failed to load $tag into $RUNNER (check containerd privileges)"
}

# Launch a detached box under $RUNNER with the runtime's extra run flags (Kata's --runtime). Empty-array
# expansion is guarded so it stays set -u-safe on bash 3.2 (macOS), where SLUICE_RUNTIME is never kata.
runtime_run() {
  if [ "${#RUNTIME_RUN_OPTS[@]}" -gt 0 ]; then "$RUNNER" run -d "${RUNTIME_RUN_OPTS[@]}" "$@"; else "$RUNNER" run -d "$@"; fi
}

# Remove the box's per-dir overlay volumes (SLUICE_OVERLAY_DIRS; labeled sluice.box=<container> at
# creation, so no config sourcing is needed - prune and orphan rm work too). Echoes the count removed.
remove_box_volumes() {
  local v n=0
  for v in $("$RUNNER" volume ls -q --filter "label=sluice.box=$1" 2>/dev/null || true); do
    "$RUNNER" volume rm -f "$v" >/dev/null 2>&1 && n=$((n+1)) || true
  done
  echo "$n"
}

# Map a -b/--box <name> to a built box: accept the short slug (qwen) or the full image (sluice-qwen),
# verify it's a real sluice box, and stash its recorded project dir for the box-aware find_config below.
resolve_box_target() {
  local name="$1" img hash
  case "$name" in sluice-*) img="$name" ;; *) img="sluice-$name" ;; esac
  hash="$("$ENGINE" image inspect -f '{{ index .Config.Labels "sluice.confighash" }}' "$img" 2>/dev/null || true)"
  case "$hash" in ""|"<no value>") die "no sluice box named '$name' - run 'sluice ls'" ;; esac
  SLUICE_BOX_IMAGE="$img"
  SLUICE_BOX_SLUG="${img#sluice-}"
  BOX_PROJECT="$("$ENGINE" image inspect -f '{{ index .Config.Labels "sluice.project" }}' "$img" 2>/dev/null || true)"
  case "$BOX_PROJECT" in "<no value>") BOX_PROJECT="" ;; esac
}

# Leading global -b/--box <name>: explicit, per-invocation targeting of any box from anywhere. Parsed
# ONLY before the subcommand, so a --box that's an argument to `sluice run` is never swallowed.
SLUICE_BOX_TARGET=""
while [ "$#" -gt 0 ]; do
  case "$1" in
    -b|--box) [ -n "${2:-}" ] || die "--box needs a box name - run 'sluice ls'"; SLUICE_BOX_TARGET="$2"; shift 2 ;;
    --box=*)  SLUICE_BOX_TARGET="${1#--box=}"; [ -n "$SLUICE_BOX_TARGET" ] || die "--box needs a box name - run 'sluice ls'"; shift ;;
    *)        break ;;
  esac
done

# Per-command help (sluice <cmd> --help) + hidden helpers - before config (they need none).
case "${2:-}" in -h|--help) help_for "${1:-}"; exit 0 ;; esac
case "${1:-}" in
  __parent)      parent_of "${2:-}"; exit 0 ;;          # registrable parent (tests/completion)
  __collapsible) _collapsible "${2:-}" && echo yes || echo no; exit 0 ;;
  __sbom)        [ -n "${2:-}" ] || die "usage: sluice __sbom <image-ref>"; resolve_engine; _sbom_for "$2"; exit $? ;;
  __posture)     [ -f "$PWD/sluice.config.sh" ] && . "$PWD/sluice.config.sh"   # banner posture for $PWD's config (tests; no engine; find_config isn't defined this early)
                 _banner_posture ' - '; printf '%s%s\n' "$_POSTURE_TEXT" "${_POSTURE_RISK:+ [risk]}"; exit 0 ;;
esac

# init + info commands need no engine; resolve one only for the rest. `egress ... --all` is a
# host-side, file-only fleet audit (no engine, no config), so it must survive the daemon being down
# or absent - skip resolve_engine for it too, matching doctor's leniency.
case "${1:-}" in
  init|help|-h|--help|version|-v|--version|doctor) ;;
  egress) case " $* " in *" --all "*) ;; *) resolve_engine ;; esac ;;
  *) resolve_engine ;;
esac

# --box targeting: resolve the named box up front so every config lookup below routes to it. Reject
# the commands that have no single-box meaning; explicit by design - echo the target to stderr.
if [ -n "$SLUICE_BOX_TARGET" ]; then
  case "${1:-}" in
    init|help|-h|--help|version|-v|--version|ls|prune|agent) die "--box doesn't apply to '${1:-}'" ;;
    egress) case " $* " in *" --all "*) die "--box doesn't apply to 'egress --all' (it spans every box)" ;; esac ;;
  esac
  # doctor is the lenient path (reports, never dies, since it's what you run when the runtime is broken):
  # mirror line 22 and skip the strict resolve_engine. resolve_box_target still needs $ENGINE for its
  # image inspect, so set it leniently (docker/podman/SLUICE_ENGINE, no runtime preflight) - matching
  # cmd_doctor's own engine probe. Every other -b command keeps the strict resolve_engine.
  case "${1:-}" in
    doctor)
      if   [ -n "${SLUICE_ENGINE:-}" ]; then ENGINE="$SLUICE_ENGINE"
      elif command -v docker >/dev/null 2>&1; then ENGINE=docker
      elif command -v podman >/dev/null 2>&1; then ENGINE=podman
      else ENGINE="" ; fi ;;
    *) resolve_engine ;;   # idempotent; the line-22 case skipped it for doctor
  esac
  resolve_box_target "$SLUICE_BOX_TARGET"
  echo "${E_DIM}[sluice]${E_RST} targeting ${SLUICE_BOX_SLUG} (${BOX_PROJECT:-<dir gone>})" >&2
fi

# `sluice init` helpers: best-effort manifest parsing (no jq), each returns 0
_init_json_str()  { printf '%s' "$(grep -oE "\"$2\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" "$1" 2>/dev/null | head -1 | sed -E 's/^.*:[[:space:]]*"([^"]*)".*$/\1/')"; }
_init_port_from() { printf '%s' "$(printf '%s' "$1" | grep -oiE -- '(--port|--server\.port|-p|PORT)[ =]+[0-9]+' | grep -oE '[0-9]+' | head -1)"; }
_init_pkg_has()   { grep -qE "\"$2(\"|/)" "$1" 2>/dev/null; }          # dependency / scoped-pkg key
_init_has_script(){ grep -qE "\"$2\"[[:space:]]*:" "$1" 2>/dev/null; } # a package.json/deno.json script
_init_py_has()    { grep -qiE "(^|[^a-zA-Z0-9_.-])$1" "$dir/requirements.txt" "$dir/pyproject.toml" "$dir/Pipfile" 2>/dev/null; }
# Quote a config value for the generated config (host-sourced pre-container): single-quote and escape
# embedded quotes via the '\'' idiom, so every char ($, backtick, ", \, newline) is literal - no
# evaluation. The 4 backslashes are load-bearing: the double-quoted string collapses them to the sed
# program s/'/'\\''/g (don't "simplify" to 2 - that emits ''' and breaks values with a single quote).
_init_q()         { printf "'%s'" "$(printf '%s' "$1" | sed "s/'/'\\\\''/g")"; }
# A run command the project already declares (Procfile web line, or a Makefile/justfile run-ish target),
# so the generic fallback can propose something real instead of 'bash'. Echoes the command; rc 1 if none.
_init_runcmd_from_files() {
  if [ -f "$dir/Procfile" ]; then
    local w; w="$(sed -nE 's/^[a-zA-Z0-9_-]+:[[:space:]]*//p' "$dir/Procfile" 2>/dev/null | head -1)"
    [ -n "$w" ] && { printf '%s' "$w"; return 0; }
  fi
  local mf="" t
  [ -f "$dir/Makefile" ] && mf="$dir/Makefile"
  [ -f "$dir/makefile" ] && mf="$dir/makefile"
  if [ -n "$mf" ]; then
    for t in run dev start serve; do
      grep -qE "^$t:" "$mf" 2>/dev/null && { printf 'make %s' "$t"; return 0; }
    done
  fi
  local jf=""
  [ -f "$dir/justfile" ] && jf="$dir/justfile"
  [ -f "$dir/Justfile" ] && jf="$dir/Justfile"
  if [ -n "$jf" ]; then
    for t in run dev start serve; do
      grep -qE "^$t:" "$jf" 2>/dev/null && { printf 'just %s' "$t"; return 0; }
    done
  fi
  return 1
}

# `sluice init`: scaffold a config from $PWD's manifests (allowlist left to `learn`)
cmd_init() {
  local force=0 update=0
  while [ $# -gt 0 ]; do
    case "$1" in -f|--force) force=1 ;; -u|--update) update=1 ;; *) break ;; esac
    shift
  done
  local dir="$PWD" cfg pj
  cfg="$dir/sluice.config.sh"; pj="$dir/package.json"
  if [ "$update" -eq 1 ]; then
    [ -e "$cfg" ] || die "no sluice.config.sh to update here - run 'sluice init' to create one first."
  elif [ -e "$cfg" ] && [ "$force" -ne 1 ]; then
    die "$cfg already exists - edit it, remove it, re-run with --force, or --update to refresh detection."
  fi

  local stack="generic" detected="generic" extra_pkgs="" extra_npm="" setup="" \
        run_cmd="bash" ports="" allow="" note="" note2="" prefetch_files="" prefetch_cmd=""

  if [ -f "$pj" ]; then
    # node / bun
    stack="node"
    local pm="npm"
    if   [ -f "$dir/bun.lockb" ] || [ -f "$dir/bun.lock" ]; then pm="bun"
    elif [ -f "$dir/pnpm-lock.yaml" ];    then pm="pnpm"
    elif [ -f "$dir/yarn.lock" ];         then pm="yarn"
    elif [ -f "$dir/package-lock.json" ]; then pm="npm"
    else case "$(_init_json_str "$pj" packageManager)" in
           pnpm*) pm="pnpm" ;; yarn*) pm="yarn" ;; bun*) pm="bun" ;;
         esac
    fi
    case "$pm" in pnpm|yarn) extra_npm="$pm" ;; bun) extra_pkgs="bun" ;; esac

    # framework -> default port + the flag spelling that framework uses + preferred script
    local fw="" port=3000 hostflag="--host 0.0.0.0" portflag="--port" pref="dev"
    if   _init_pkg_has "$pj" '@angular/core'; then fw="angular";    port=4200; pref="start"
    elif _init_pkg_has "$pj" '@sveltejs/kit'; then fw="sveltekit";  port=5173
    elif _init_pkg_has "$pj" 'vitepress';     then fw="vitepress";  port=5173
    elif _init_pkg_has "$pj" 'nuxt';          then fw="nuxt";       port=3000
    elif _init_pkg_has "$pj" 'astro';         then fw="astro";      port=4321
    elif _init_pkg_has "$pj" '@remix-run';    then fw="remix";      port=3000
    elif _init_pkg_has "$pj" '@docusaurus';   then fw="docusaurus"; port=3000
    elif _init_pkg_has "$pj" 'gatsby';        then fw="gatsby";     port=8000; hostflag="-H 0.0.0.0"; portflag="-p"; pref="develop"
    elif _init_pkg_has "$pj" 'next';          then fw="next";       port=3000; hostflag="-H 0.0.0.0"; portflag="-p"
    elif _init_pkg_has "$pj" 'vite';          then fw="vite";       port=5173
    fi

    local script="" s noscript=""
    for s in "$pref" dev develop serve start; do
      if _init_has_script "$pj" "$s"; then script="$s"; break; fi
    done
    [ -z "$script" ] && { script="$pref"; noscript=1; }   # nothing matched - flag it (note set below)

    # honor a host/port the dev script already sets, rather than fighting it
    local sval ep
    sval="$(_init_json_str "$pj" "$script")"
    ep="$(_init_port_from "$sval")"; [ -n "$ep" ] && port="$ep"
    ports="$port"

    local inst run_script
    case "$pm" in
      npm)  inst="npm install";  run_script="npm run $script" ;;
      pnpm) inst="pnpm install"; run_script="pnpm run $script" ;;
      yarn) inst="yarn install"; run_script="yarn $script" ;;
      bun)  inst="bun install";  run_script="bun run $script" ;;
    esac
    case "$sval" in
      *0.0.0.0*|*--host*|*-H\ *)
        run_cmd="$inst && $run_script"
        note="the dev script already sets host/port; the egress allowlist is what's left - run 'sluice learn'." ;;
      *)
        run_cmd="$inst && $run_script -- $hostflag $portflag $port"
        note="npm/yarn registries are allowed; add runtime CDNs/APIs or run 'sluice learn'." ;;
    esac
    [ -n "$noscript" ] && note="package.json has no dev/start/serve script - '$run_script' is a guess; set SLUICE_RUN_CMD to your real start command."
    detected="node/$pm${fw:+ ($fw)}"

  elif [ -f "$dir/requirements.txt" ] || [ -f "$dir/pyproject.toml" ] || [ -f "$dir/Pipfile" ]; then
    # python
    stack="python"; allow="pypi.org files.pythonhosted.org"
    local pyver="3.12" v
    if [ -f "$dir/.python-version" ]; then
      v="$(grep -oE '3\.(11|12|13)' "$dir/.python-version" 2>/dev/null | head -1 || true)"; [ -n "$v" ] && pyver="$v"
    elif [ -f "$dir/pyproject.toml" ]; then
      v="$(grep -oE 'requires-python[^0-9]*3\.(11|12|13)' "$dir/pyproject.toml" 2>/dev/null | grep -oE '3\.(11|12|13)' | head -1 || true)"; [ -n "$v" ] && pyver="$v"
    fi
    local px="${pyver#3.}"
    extra_pkgs="python-$pyver py3.$px-pip"
    local pm="pip"
    if   [ -f "$dir/uv.lock" ]; then pm="uv"; extra_pkgs="$extra_pkgs uv"
    elif [ -f "$dir/poetry.lock" ] || _init_py_has 'tool\.poetry'; then pm="poetry"; extra_pkgs="$extra_pkgs poetry"
    elif [ -f "$dir/Pipfile" ]; then pm="pipenv"; setup="pip install --user pipenv"   # baked at build (free egress); no reliable Wolfi apk
    fi

    local entry="" f
    for f in app.py main.py server.py wsgi.py asgi.py run.py __main__.py; do
      [ -f "$dir/$f" ] && { entry="$f"; break; }
    done
    local mod="${entry%.py}"; [ -z "$mod" ] && mod="app"

    local fw="" fwcmd=""
    if   [ -f "$dir/manage.py" ] || _init_py_has 'django'; then fw="django"; fwcmd="python manage.py runserver 0.0.0.0:8000"; ports="8000"
    elif _init_py_has 'fastapi' || _init_py_has 'uvicorn';  then fw="fastapi"; fwcmd="uvicorn $mod:app --host 0.0.0.0 --port 8000"; ports="8000"
    elif _init_py_has 'flask';     then fw="flask";     fwcmd="flask --app $mod run --host 0.0.0.0 --port 5000"; ports="5000"
    elif _init_py_has 'streamlit'; then fw="streamlit"; fwcmd="streamlit run ${entry:-app.py} --server.address 0.0.0.0 --server.port 8501"; ports="8501"
    elif _init_py_has 'gradio';    then fw="gradio";    fwcmd="python ${entry:-app.py}"; ports="7860"; note="gradio must bind 0.0.0.0: launch(server_name='0.0.0.0', server_port=7860)."
    else fwcmd="python ${entry:-app.py}"; ports=""; note="SET YOUR ENTRY COMMAND - 'python ${entry:-app.py}' is a guess."
    fi

    local inst_target=""
    if   [ -f "$dir/requirements.txt" ]; then inst_target="-r requirements.txt"
    elif [ -f "$dir/pyproject.toml" ];   then inst_target="."
    fi
    case "$pm" in
      pip)
        if [ -f "$dir/requirements.txt" ]; then
          # F2: install deps at build (free egress, into ~/.local) so the runtime needs no pypi.
          prefetch_files="requirements.txt"; prefetch_cmd="export PATH=\"\$HOME/.local/bin:\$PATH\"; pip install --user -r requirements.txt"
          run_cmd="export PATH=\"\$HOME/.local/bin:\$PATH\"; $fwcmd"; allow=""
        elif [ -n "$inst_target" ]; then run_cmd="export PATH=\"\$HOME/.local/bin:\$PATH\"; pip install --user $inst_target && $fwcmd"
        else                             run_cmd="export PATH=\"\$HOME/.local/bin:\$PATH\"; $fwcmd"; fi ;;
      pipenv) run_cmd="export PATH=\"\$HOME/.local/bin:\$PATH\"; pipenv install && pipenv run $fwcmd" ;;
      poetry) run_cmd="poetry install && poetry run $fwcmd" ;;
      uv)     run_cmd="uv sync && uv run $fwcmd" ;;
    esac
    detected="python-$pyver/$pm${fw:+ ($fw)}"

  elif [ -f "$dir/deno.json" ] || [ -f "$dir/deno.jsonc" ]; then
    # deno
    stack="deno"; extra_pkgs="deno"
    allow="deno.land jsr.io registry.npmjs.org esm.sh cdn.jsdelivr.net"
    local dj="$dir/deno.json"; [ -f "$dj" ] || dj="$dir/deno.jsonc"
    if   _init_has_script "$dj" 'dev';   then run_cmd="deno task dev"
    elif _init_has_script "$dj" 'start'; then run_cmd="deno task start"
    else run_cmd="deno run -A main.ts"; fi
    ports=""; note="set SLUICE_PORTS to the port your server binds (Fresh defaults to 8000)."
    detected="deno"

  elif [ -f "$dir/Gemfile" ]; then
    # ruby (best-effort)
    # -dev + build-base + linux-headers so native-extension gems (puma/nokogiri/...) compile.
    stack="ruby"; extra_pkgs="ruby-3.3 ruby-3.3-dev build-base linux-headers"; detected="ruby-3.3"
    setup="mkdir -p \"\$HOME/.local/bin\" \"\$HOME/.gem/ruby\" && gem install --no-document --bindir \"\$HOME/.local/bin\" --install-dir \"\$HOME/.gem/ruby\" bundler"
    local rb="export GEM_HOME=\"\$HOME/.gem/ruby\"; export PATH=\"\$HOME/.local/bin:\$PATH\""
    local _rbserve _rails=""
    if grep -qE "gem ['\"]rails['\"]" "$dir/Gemfile" 2>/dev/null || [ -f "$dir/config/application.rb" ]; then _rails=1; fi
    if [ -n "$_rails" ]; then
      ports="3000"; _rbserve="bundle exec rails server -b 0.0.0.0 -p 3000"
    else
      local rbentry="app.rb"; [ -f "$dir/main.rb" ] && rbentry="main.rb"
      _rbserve="ruby $rbentry"; note="ruby is best-effort - set SLUICE_RUN_CMD/SLUICE_PORTS for your app."
    fi
    if [ -f "$dir/Gemfile.lock" ]; then
      # F2: install gems at build (free egress, into GEM_HOME) so the runtime needs no rubygems.
      prefetch_files="Gemfile Gemfile.lock"; prefetch_cmd="$rb; bundle install"; allow=""
      run_cmd="$rb; $_rbserve"; detected="ruby-3.3 (prefetched)"
    else
      allow="rubygems.org index.rubygems.org"; run_cmd="$rb; bundle install && $_rbserve"
    fi

  elif [ -f "$dir/Cargo.toml" ]; then
    # build-base provides the C linker (cc/ld) that rustc needs to link any binary.
    stack="rust"; detected="rust"; extra_pkgs="rust build-base"
    if [ -f "$dir/Cargo.lock" ]; then
      # F2: fetch crates at build (free egress) so the runtime needs no crates.io.
      prefetch_files="Cargo.toml Cargo.lock"; prefetch_cmd="cargo fetch"; run_cmd="cargo run --offline"; allow=""
      detected="rust (prefetched)"; note="deps are fetched at build (cargo fetch); runtime egress needs no crates.io. Edit Cargo.lock -> rebuild."
    else
      allow="static.crates.io index.crates.io"; run_cmd="cargo run"
    fi
  elif [ -f "$dir/go.mod" ]; then
    stack="go"; detected="go"; extra_pkgs="go"
    if [ -f "$dir/go.sum" ]; then
      # F2: download modules at build (free egress) so the runtime needs no go proxy.
      prefetch_files="go.mod go.sum"; prefetch_cmd="go mod download"; run_cmd="GOPROXY=off go run ."; allow=""
      detected="go (prefetched)"; note="deps are fetched at build (go mod download); runtime egress needs no go proxy. Edit go.sum -> rebuild."
    else
      allow="proxy.golang.org sum.golang.org"; run_cmd="go run ."
    fi

  elif [ -f "$dir/pom.xml" ] || [ -f "$dir/build.gradle" ] || [ -f "$dir/build.gradle.kts" ]; then
    # java/kotlin (best-effort): JDK + build tool; Spring Boot gets a server run cmd + port.
    # wolfi's openjdk-21 installs to /usr/lib/jvm/java-21-openjdk but sets neither JAVA_HOME nor PATH,
    # so mvn/gradle can't find the JDK - export both.
    stack="java"; allow="repo.maven.apache.org repo1.maven.org"
    local jh="export JAVA_HOME=/usr/lib/jvm/java-21-openjdk; export PATH=\"\$JAVA_HOME/bin:\$PATH\""
    local spring=""
    grep -qiE 'spring-boot' "$dir/pom.xml" "$dir/build.gradle" "$dir/build.gradle.kts" 2>/dev/null && { spring=1; ports="8080"; }
    if [ -f "$dir/pom.xml" ]; then
      extra_pkgs="openjdk-21 maven"
      if [ -n "$spring" ]; then run_cmd="$jh; mvn -q spring-boot:run"
      else run_cmd="$jh; mvn -q compile exec:java"; note="java/maven is best-effort - set SLUICE_RUN_CMD for your app."; fi
      detected="java/maven${spring:+ (spring-boot)}"
    else
      extra_pkgs="openjdk-21 gradle"; allow="$allow plugins.gradle.org services.gradle.org"
      local gw="gradle"; [ -f "$dir/gradlew" ] && gw="./gradlew"
      if [ -n "$spring" ]; then run_cmd="$jh; $gw bootRun"
      else run_cmd="$jh; $gw run"; note="java/gradle is best-effort - set SLUICE_RUN_CMD for your app."; fi
      detected="java/gradle${spring:+ (spring-boot)}"
    fi

  elif [ -f "$dir/composer.json" ]; then
    # php (best-effort): laravel gets artisan serve, else the built-in server.
    stack="php"; extra_pkgs="php composer"; allow="repo.packagist.org packagist.org"; ports="8000"
    if [ -f "$dir/artisan" ]; then
      run_cmd="composer install && php artisan serve --host 0.0.0.0 --port 8000"; detected="php/laravel"
    else
      run_cmd="composer install && php -S 0.0.0.0:8000"; detected="php"
      note="php is best-effort - set SLUICE_RUN_CMD/SLUICE_PORTS for your app."
    fi

  elif [ -n "$(ls "$dir"/*.csproj "$dir"/*.sln 2>/dev/null)" ]; then
    # .NET (best-effort): dotnet run, bound to 0.0.0.0 via the ASP.NET urls flag.
    stack="dotnet"; extra_pkgs="dotnet-10-sdk"; allow="api.nuget.org www.nuget.org"; ports="8080"
    run_cmd="dotnet run --urls http://0.0.0.0:8080"; detected="dotnet"
    note="dotnet is best-effort - confirm the port your app binds (ASPNETCORE_URLS)."

  elif [ -f "$dir/mix.exs" ]; then
    # elixir (best-effort): phoenix gets phx.server + 4000.
    stack="elixir"; extra_pkgs="elixir"; allow="repo.hex.pm builds.hex.pm"
    if grep -qiE 'phoenix' "$dir/mix.exs" 2>/dev/null; then
      ports="4000"; run_cmd="mix deps.get && mix phx.server"; detected="elixir/phoenix"
    else
      run_cmd="mix deps.get && mix run --no-halt"; detected="elixir"
      note="elixir is best-effort - set SLUICE_RUN_CMD/SLUICE_PORTS for your app."
    fi

  elif [ -f "$dir/pubspec.yaml" ]; then
    # dart (best-effort).
    stack="dart"; extra_pkgs="dart"; allow="pub.dev pub.dartlang.org"
    run_cmd="dart pub get && dart run"; detected="dart"
    note="dart is best-effort - set SLUICE_RUN_CMD/SLUICE_PORTS for your app."
  fi

  if [ "$stack" = generic ]; then
    local _grc
    if _grc="$(_init_runcmd_from_files)"; then
      run_cmd="$_grc"
      case "$_grc" in "make "*) extra_pkgs="make" ;; "just "*) extra_pkgs="just" ;; esac
      note="run command taken from a declared Procfile/Makefile/justfile target - add SLUICE_EXTRA_PKGS for your toolchain."
    else
      note="no known stack detected - set SLUICE_RUN_CMD and SLUICE_EXTRA_PKGS for your toolchain (or re-run from your project's root)."
    fi
  fi

  # secondary manifests (polyglot / monorepo): flag them, don't try to merge stacks
  local others=""
  [ "$stack" != node ]   && [ -f "$pj" ]             && others="$others node"
  [ "$stack" != python ] && { [ -f "$dir/requirements.txt" ] || [ -f "$dir/pyproject.toml" ] || [ -f "$dir/Pipfile" ]; } && others="$others python"
  [ "$stack" != ruby ]   && [ -f "$dir/Gemfile" ]    && others="$others ruby"
  [ "$stack" != go ]     && [ -f "$dir/go.mod" ]     && others="$others go"
  [ "$stack" != rust ]   && [ -f "$dir/Cargo.toml" ] && others="$others rust"
  [ "$stack" != java ]   && { [ -f "$dir/pom.xml" ] || [ -f "$dir/build.gradle" ] || [ -f "$dir/build.gradle.kts" ]; } && others="$others java"
  [ "$stack" != php ]    && [ -f "$dir/composer.json" ] && others="$others php"
  [ "$stack" != dotnet ] && [ -n "$(ls "$dir"/*.csproj "$dir"/*.sln 2>/dev/null)" ] && others="$others dotnet"
  [ -n "$others" ] && note2="also saw manifests for:$others - this config targets '$stack'; init each service in its own dir."

  # --update: refresh the detected fields, but keep the user's allowlist + any keys init doesn't manage
  # (SLUICE_ENV, hardening knobs, SLUICE_NAME, ...). Write to a temp, show a diff, confirm, then swap.
  local preserved_extra="" out="$cfg" _ea="" _a=""
  if [ "$update" -eq 1 ]; then
    _ea="$(grep -E '^SLUICE_ALLOW_DOMAINS=' "$cfg" 2>/dev/null | head -1 | sed -E 's/^SLUICE_ALLOW_DOMAINS=//; s/[[:space:]]+#.*$//; s/^"//; s/"$//')"
    [ -n "$_ea" ] && allow="$_ea"                          # keep the user's allowlist, not the detected base
    preserved_extra="$(grep -E '^SLUICE_[A-Z_]+=' "$cfg" 2>/dev/null | grep -vE '^SLUICE_(EXTRA_PKGS|EXTRA_NPM|SETUP_CMDS|PREFETCH_FILES|PREFETCH_CMD|PORTS|RUN_CMD|ALLOW_DOMAINS)=' || true)"
    out="$(mktemp)"
  fi

  {
    echo "# sluice config - scaffolded by 'sluice init' (detected: $detected)."
    echo "# Review the values, then run 'sluice' (or 'sluice learn' to discover the egress allowlist)."
    [ -n "$note" ]  && echo "# NOTE: $note"
    [ -n "$note2" ] && echo "# ALSO: $note2"
    echo ""
    [ -n "$extra_pkgs" ] && echo "SLUICE_EXTRA_PKGS=$(_init_q "$extra_pkgs")"
    [ -n "$extra_npm" ]  && echo "SLUICE_EXTRA_NPM=$(_init_q "$extra_npm")"
    [ -n "$setup" ]      && echo "SLUICE_SETUP_CMDS=$(_init_q "$setup")   # build-time, free egress, before the firewall"
    [ -n "$prefetch_files" ] && echo "SLUICE_PREFETCH_FILES=$(_init_q "$prefetch_files")   # manifests copied into the build for the prefetch"
    [ -n "$prefetch_cmd" ]   && echo "SLUICE_PREFETCH_CMD=$(_init_q "$prefetch_cmd")   # fetch deps at build (free egress) so runtime egress can drop the registry"
    echo "SLUICE_PORTS=$(_init_q "$ports")            # ports to publish (the app MUST bind 0.0.0.0)"
    echo "SLUICE_RUN_CMD=$(_init_q "$run_cmd")"
    echo "SLUICE_ALLOW_DOMAINS=$(_init_q "$allow")    # runtime egress hosts (or run 'sluice learn')"
    echo ""
    echo "# Hardening (opt-in - uncomment to enable; see THREAT_MODEL.md):"
    echo "# SLUICE_SECCOMP=hardened       # tighter syscall filter (>= engine default); 'browser' for Chromium/Playwright"
    echo "# SLUICE_READONLY_ROOT=1        # immutable rootfs (tmpfs + anon-volume the writable paths)"
    echo "# SLUICE_WORKSPACE=overlay      # mount the repo read-only; the box edits a copy (sluice diff | apply)"
    echo "# SLUICE_BUMP_DOMAINS=\"\"        # decrypt + inspect request URLs on these hosts (scoped TLS interception)"
    [ -n "$preserved_extra" ] && { echo ""; echo "# preserved from your previous config:"; printf '%s\n' "$preserved_extra"; }
  } > "$out"

  if [ "$update" -eq 1 ]; then
    if diff "$cfg" "$out" >/dev/null 2>&1; then
      rm -f "$out"; echo "[sluice] $cfg already matches detection - nothing to update."; return 0
    fi
    echo "[sluice] sluice init --update - proposed changes:"
    diff -u "$cfg" "$out" 2>/dev/null | sed 's/^/    /' || true
    if [ -t 0 ] && [ -t 1 ]; then
      printf '[sluice] apply? [y/N] '; read -r _a || _a=n
      case "$_a" in [yY]|[yY][eE][sS]) ;; *) rm -f "$out"; echo "[sluice] left $cfg unchanged."; return 0 ;; esac
    elif [ "${SLUICE_YES:-}" != 1 ]; then
      rm -f "$out"; echo "[sluice] non-interactive: re-run with SLUICE_YES=1 to apply these changes."; return 0
    fi
    mv "$out" "$cfg"; chmod 0644 "$cfg" 2>/dev/null || true   # mktemp is 0600; the build sources it
    echo "[sluice] updated $cfg (allowlist + non-detected keys preserved)"; return 0
  fi

  echo "[sluice] detected: $detected"
  echo "[sluice] wrote $cfg"
  [ -n "$note2" ] && echo "[sluice] note: $note2"
  [ -n "${SLUICE_INIT_QUIET:-}" ] || echo "[sluice] next: review it, then 'sluice'  (or 'sluice learn' to fill the allowlist)."
}
if [ "${1:-}" = init ]; then banner; shift; cmd_init "$@"; exit 0; fi

# info commands: no config/engine/banner.
case "${1:-}" in
  -h|--help|help) usage; exit 0 ;;
  -v|--version)   printf 'sluice %s\n' "$(sluice_version)"; exit 0 ;;
  version)        cmd_version "${2:-}"; exit 0 ;;
esac

# locate the project by walking cwd upward for sluice.config.sh
find_config() {
  if [ -n "${SLUICE_BOX_TARGET:-}" ]; then   # -b/--box: the targeted box's recorded dir, not $PWD's
    [ -n "${BOX_PROJECT:-}" ] && [ -f "$BOX_PROJECT/sluice.config.sh" ] && { echo "$BOX_PROJECT/sluice.config.sh"; return 0; }
    return 1   # config gone (orphan): the caller's no-config path fires
  fi
  d="$PWD"
  while [ "$d" != / ]; do
    [ -f "$d/sluice.config.sh" ] && { echo "$d/sluice.config.sh"; return 0; }
    d="$(dirname "$d")"
  done
  return 1
}

# `sluice doctor`: self-contained health report (resolves its own engine/config), runs anywhere.
if [ "${1:-}" = doctor ]; then
  case "${2:-}" in ""|--json) cmd_doctor "${2:-}"; exit 0 ;; *) die "usage: sluice doctor [--json]" ;; esac
fi

# `sluice ls`: global box listing (resolves its own engine above; no project config needed).
if [ "${1:-}" = ls ]; then shift; cmd_ls "$@"; exit $?; fi

# `sluice prune`: global cleanup - remove every sluice box (or only orphans with --orphans); confirms.
cmd_prune() {
  local only_orphans="" imgs i a proj kept
  [ "${1:-}" = --orphans ] && only_orphans=1
  imgs="$("$ENGINE" image ls --filter label=sluice.confighash --format '{{.Repository}}' 2>/dev/null | sed 's,^localhost/,,' | grep -v '^<none>$' | sort -u || true)"   # strip podman's localhost/ so names match the canonical sluice-<slug>
  [ -n "$imgs" ] || { echo "[sluice] no sluice boxes to prune."; return 0; }
  if [ -n "$only_orphans" ]; then   # keep only boxes whose recorded project dir is gone
    kept=""
    while IFS= read -r i; do
      [ -n "$i" ] || continue
      proj="$("$ENGINE" image inspect -f '{{ index .Config.Labels "sluice.project" }}' "$i" 2>/dev/null || true)"
      case "$proj" in "<no value>") proj="" ;; esac
      [ -n "$proj" ] && [ ! -d "$proj" ] && kept="$kept$i"$'\n'
    done <<EOF
$imgs
EOF
    imgs="$(printf '%s' "$kept" | grep -v '^$' || true)"
    [ -n "$imgs" ] || { echo "[sluice] no orphan boxes to prune (every box's project dir still exists)."; return 0; }
    echo "[sluice] orphan sluice images to remove (project dir gone):"
  else
    echo "[sluice] sluice images to remove (+ their containers):"
  fi
  # shellcheck disable=SC2086
  printf '  %s\n' $imgs
  if [ -t 0 ] && [ -t 1 ]; then
    printf '[sluice] remove all of these? [y/N] '; read -r a || a=""
    case "$a" in y|Y|yes|YES) ;; *) echo "[sluice] ${C_DIM}aborted.${C_RST}"; return 0 ;; esac
  elif [ "${SLUICE_YES:-}" != 1 ]; then
    echo "[sluice] non-interactive: re-run with SLUICE_YES=1 to confirm pruning."; return 0
  fi
  for i in $imgs; do
    "$RUNNER" rm -f "$i" >/dev/null 2>&1 || true; "$ENGINE" rmi -f "$i" >/dev/null 2>&1 || true
    remove_box_volumes "$i" >/dev/null   # per-box SLUICE_OVERLAY_DIRS volumes go with the box
  done
  echo "[sluice] ${C_GRN}pruned $(printf '%s\n' "$imgs" | grep -c .) box(es).${C_RST}"
  # Persisted state dirs (agent sessions/auth) live outside the boxes and are NOT removed by prune.
  _store="${XDG_STATE_HOME:-$HOME/.local/state}/sluice"
  [ -d "$_store" ] && [ -n "$(ls -A "$_store" 2>/dev/null)" ] && \
    echo "${C_DIM}[sluice] note: persisted session state remains under $_store (remove manually if no longer needed).${C_RST}"
}
if [ "${1:-}" = prune ]; then
  case "${2:-}" in ""|--orphans) cmd_prune "${2:-}"; exit $? ;; *) die "usage: sluice prune [--orphans]" ;; esac
fi

# `sluice egress --verify --all` / `--export --all`: fleet-wide audit over EVERY box's hash chain.
# Dispatched here, before find_config, so it needs neither a project config nor a running engine and
# reaches orphaned boxes (their chains outlive the box). Bare `egress --all` defaults to --verify.
# `-b ... egress --all` was already rejected in src/45.
if [ "${1:-}" = egress ]; then
  case " $* " in
    *" --all "*)
      _eg_mode="verify"; _eg_json=""
      for _eg_a in "$@"; do
        case "$_eg_a" in
          egress|--all|--verify) ;;
          --export) _eg_mode="export" ;;
          --json)   _eg_json="--json" ;;
          *)        die "usage: sluice egress [--verify | --export] --all [--json]" ;;
        esac
      done
      if [ "$_eg_mode" = export ]; then cmd_egress_export_all; else cmd_egress_verify_all "$_eg_json"; fi
      exit $?
      ;;
  esac
fi

# Package-registry hosts for the stack detected in $PWD (a manifest sniff mirroring cmd_init's
# per-stack allowlists - kept lean here, full detection lives in cmd_init). Always the full registry
# set: an agent installs deps at RUNTIME inside the box, so the init prefetch shortcut doesn't apply.
# Echoes "<label>|<hosts>"; nothing when no stack is recognized.
_stack_registry_hosts() {
  local dir="$PWD" pm
  if [ -f "$dir/package.json" ]; then
    pm="npm"
    if   [ -f "$dir/bun.lockb" ] || [ -f "$dir/bun.lock" ]; then pm="bun"
    elif [ -f "$dir/pnpm-lock.yaml" ]; then pm="pnpm"
    elif [ -f "$dir/yarn.lock" ];      then pm="yarn"; fi
    case "$pm" in
      yarn) echo "node/yarn|registry.yarnpkg.com" ;;
      *)    echo "node/$pm|registry.npmjs.org" ;;
    esac
  elif [ -f "$dir/requirements.txt" ] || [ -f "$dir/pyproject.toml" ] || [ -f "$dir/Pipfile" ]; then
    echo "python|pypi.org files.pythonhosted.org"
  elif [ -f "$dir/deno.json" ] || [ -f "$dir/deno.jsonc" ]; then
    echo "deno|deno.land jsr.io registry.npmjs.org esm.sh cdn.jsdelivr.net"
  elif [ -f "$dir/Gemfile" ]; then
    echo "ruby|rubygems.org index.rubygems.org"
  elif [ -f "$dir/Cargo.toml" ]; then
    echo "rust|static.crates.io index.crates.io"
  elif [ -f "$dir/go.mod" ]; then
    echo "go|proxy.golang.org sum.golang.org"
  elif [ -f "$dir/pom.xml" ]; then
    echo "java/maven|repo.maven.apache.org repo1.maven.org"
  elif [ -f "$dir/build.gradle" ] || [ -f "$dir/build.gradle.kts" ]; then
    echo "java/gradle|repo.maven.apache.org repo1.maven.org plugins.gradle.org services.gradle.org"
  elif [ -f "$dir/composer.json" ]; then
    echo "php|repo.packagist.org packagist.org"
  elif [ -n "$(ls "$dir"/*.csproj "$dir"/*.sln 2>/dev/null)" ]; then
    echo "dotnet|api.nuget.org www.nuget.org"
  elif [ -f "$dir/mix.exs" ]; then
    echo "elixir|repo.hex.pm builds.hex.pm"
  elif [ -f "$dir/pubspec.yaml" ]; then
    echo "dart|pub.dev pub.dartlang.org"
  fi
}

# `sluice agent [name] [args...]`: write the agents/<name>.config.sh preset, then build+run.
# Trailing args after the name are forwarded to the agent (one-shot), e.g. `sluice agent claude -p '...'`.
AGENT_EXTRA_ARGS=()
if [ "${1:-}" = agent ]; then
  banner
  shift
  agents_dir="$ROOT/agents"
  if [ -z "${1:-}" ]; then
    echo "[sluice] coding agents (use: sluice agent <name> [args...]):"
    for f in "$agents_dir"/*.config.sh; do
      [ -f "$f" ] || continue
      nm="$(basename "$f" .config.sh)"
      desc="$(. "$f"; printf '%s' "${SLUICE_DESC:-}")"
      vars="$(. "$f"; printf '%s' "${SLUICE_ENV:-}")"; v1="${vars%% *}" setvar=""
      for v in $vars; do [ -n "${!v:-}" ] && { setvar="$v"; break; }; done   # a preset may accept any of several
      if   [ -z "$v1" ];     then auth=""
      elif [ -n "$setvar" ]; then auth="$setvar ${C_GRN}(set)${C_RST}"
      else                        auth="$v1 ${C_DIM}(unset)${C_RST}"; fi
      printf "  %-10s %-26s %s\n" "$nm" "$desc" "$auth"
    done
    exit 0
  fi
  preset="$agents_dir/$1.config.sh"
  [ -f "$preset" ] || die "unknown agent '$1' - run 'sluice agent' to list available presets."
  agent_name="$1"; shift
  [ "$#" -gt 0 ] && AGENT_EXTRA_ARGS=("$@")   # forward trailing args to the agent (one-shot)
  if cfg="$(find_config)"; then
    # If that config came from a DIFFERENT agent's preset, the requested one is being ignored - the
    # box is keyed to the project dir, so a repo holds one agent at a time. Flag it (don't block).
    # Matched on the preset's first-line banner: a scaffolded config keeps it even after the stack-
    # host append below or a `sluice learn` edit (a verbatim cmp went blind on the first edit).
    h1="$(head -1 "$cfg" 2>/dev/null || true)"
    for af in "$agents_dir"/*.config.sh; do
      [ "$h1" = "$(head -1 "$af")" ] || continue
      other="$(basename "$af" .config.sh)"
      [ "$other" = "$agent_name" ] || echo "[sluice] ${E_YEL}note${E_RST}: this project is set up for the '$other' agent - to run '$agent_name', use a separate dir or 'git worktree add', or remove $cfg." >&2
      break
    done
    echo "[sluice] using existing config: $cfg"
  else
    cp "$preset" "$PWD/sluice.config.sh"
    # Union the detected stack's package-registry hosts into the scaffolded allowlist (the preset
    # FILE stays tool-only), so the agent's first install doesn't trip the firewall into a learn
    # cycle. One assignment line is kept - `sluice learn` rewrites the first SLUICE_ALLOW_DOMAINS=.
    stackreg="$(_stack_registry_hosts)"
    if [ -n "$stackreg" ]; then
      stacklbl="${stackreg%%|*}"; stackhosts="${stackreg#*|}"
      cfg_tmp="$(mktemp)"
      awk -v add="$stackhosts" -v lbl="$stacklbl" '
        /^SLUICE_ALLOW_DOMAINS="/ && !done { print "# from stack detection: " lbl; sub(/"[[:space:]]*$/, " " add "\""); done=1 }
        { print }
        END { if (!done) print "SLUICE_ALLOW_DOMAINS=\"" add "\"   # from stack detection: " lbl }
      ' "$PWD/sluice.config.sh" > "$cfg_tmp" && mv "$cfg_tmp" "$PWD/sluice.config.sh"
      chmod 0644 "$PWD/sluice.config.sh" 2>/dev/null || true   # mktemp is 0600; the build sources it
      echo "[sluice] allowlist += $stackhosts (stack detection: $stacklbl)"
    fi
    echo "[sluice] wrote $PWD/sluice.config.sh from the '$agent_name' agent preset."
    echo "[sluice] export the agent's auth env var on your host first (see the file's header)."
  fi
  set -- run-default     # continue into the normal build + run flow below
fi

if ! PROJECT_CONFIG="$(find_config)"; then
  # --box <orphan>: the project dir is gone, so there's no config to source and nothing to mount.
  # Teardown (stop/rm) still works by image/container name alone; everything else can't run.
  if [ -n "$SLUICE_BOX_TARGET" ]; then
    container="$SLUICE_BOX_IMAGE"; tag="$SLUICE_BOX_IMAGE"
    case "${1:-run-default}" in
      stop) "$RUNNER" rm -f -v "$container" >/dev/null 2>&1 || true; echo "[sluice] $container stopped"; exit 0 ;;
      rm)   "$RUNNER" rm -f -v "$container" >/dev/null 2>&1 || true; "$ENGINE" rmi -f "$tag" >/dev/null 2>&1 || true; remove_box_volumes "$container" >/dev/null; echo "[sluice] removed $container (container + image + overlay volumes)"; exit 0 ;;
      *)    die "box '$SLUICE_BOX_SLUG' is an orphan (project dir ${BOX_PROJECT:-?} is gone) - 'sluice -b $SLUICE_BOX_SLUG rm' to remove it" ;;
    esac
  fi
  # no config: scaffold for build/run commands; others have nothing to act on.
  case "${1:-run-default}" in
    run-default|build|rebuild|shell|run|smoke) ;;
    stop|logs|learn|egress|rm|diff|apply) die "no sluice.config.sh found in $PWD or any parent - nothing to ${1}." ;;
    *) die "unknown command: ${1:-} - run 'sluice help' for usage." ;;
  esac
  # zero-config: scaffold, preview, then confirm before build/run (CI stops unless SLUICE_YES=1).
  banner
  echo "[sluice] no sluice.config.sh found - scaffolding one from the detected stack:"
  SLUICE_INIT_QUIET=1 cmd_init
  grep -E '^SLUICE_(EXTRA_PKGS|RUN_CMD|PORTS|ALLOW_DOMAINS)=' "$PWD/sluice.config.sh" | sed 's/^/    /' || true
  if [ -t 0 ] && [ -t 1 ]; then
    printf '[sluice] build and run it now? [Y/n] '
    read -r _ans || _ans=n
    case "$_ans" in [nN]|[nN][oO]) echo "[sluice] kept sluice.config.sh - edit it, then run 'sluice'."; exit 0 ;; esac
  elif [ "${SLUICE_YES:-}" != 1 ]; then
    echo "[sluice] non-interactive: review sluice.config.sh, then run 'sluice' (or set SLUICE_YES=1 to auto-run)."
    exit 0
  fi
  PROJECT_CONFIG="$PWD/sluice.config.sh"
  _SCAFFOLDED=1   # F3: bare-sluice first-run nudge fires after the run completes
fi
PROJECT_DIR="$(cd "$(dirname "$PROJECT_CONFIG")" && pwd)"

# Source the config here (also baked into the image; keep it POSIX-sh-safe).
# shellcheck disable=SC1090
. "$PROJECT_CONFIG"

# per-project image + container names (SLUICE_NAME overrides the dir-name default)
derive_names

# Central egress policy v2 evaluation machinery (policy_configured / _policy_raw / _verify_policy_sig /
# the IP+host matchers / policy_evaluate) is defined up in src/30-doctor-ls.sh - it must exist BEFORE
# the early `doctor` dispatch (top of this slice) so `sluice doctor` can evaluate the policy report-only.
# Only apply_policy (the run-path die-mode gate) lives here, next to the dispatch that invokes it.

# Security-critical managed-egress gate ("deny is final"). Run path only (run-default/run/shell/build/
# rebuild/update). Evaluates the policy purely, then reproduces the original refuse/side-effect sequence:
# warn-or-die on unknowns, export require-signed-base, die on the FIRST refusal in run-path order, else
# mutate SLUICE_ALLOW_DOMAINS to the effective list and echo the policy line. Behavior is byte-identical
# to the pre-refactor inline version.
apply_policy() {
  policy_configured || return 0
  policy_evaluate
  # Unknown directives: warn + ignore (forward-compat) UNLESS strict-unknown (then it's a refusal below).
  if [ -n "$_PEVAL_UNKNOWNS" ] && [ "$_PEVAL_STRICT" != 1 ]; then
    echo "${E_YEL}[sluice] policy: ignoring unknown directive(s):$_PEVAL_UNKNOWNS${E_RST}" >&2
  fi
  # require-signed-base lets the policy mandate a signed base for every box under it. (Exported before
  # the die loop, as in the original; an immediate die exits anyway, so the order is not observable.)
  if [ "$_PEVAL_RSBASE" = 1 ]; then export SLUICE_REQUIRE_SIGNED=1; fi
  # Die on the first refusal in run-path order (the list is ordered to match the original die sequence).
  if [ -n "$_PEVAL_REFUSALS" ]; then
    local _r
    while IFS= read -r _r; do [ -n "$_r" ] && die "$_r"; done <<EOF
$_PEVAL_REFUSALS
EOF
  fi
  # Clean: apply the effective allowlist (ALLOW_IPS is NOT mutated - the firewall reads the BAKED list,
  # so a host-side drop wouldn't reach a running box; the cap/deny-ip refuse instead, above).
  SLUICE_ALLOW_DOMAINS="$_PEVAL_EFFECTIVE"
  _POLICY_SRC="$_PEVAL_SRC"; _POLICY_SUMMARY="$_PEVAL_SUMMARY"
  echo "${E_DIM}[sluice]${E_RST} managed egress policy: $(_tilde "$_POLICY_SRC") ($_POLICY_SUMMARY)" >&2
}
case "${1:-run-default}" in run-default|run|shell|build|rebuild|update) apply_policy ;; esac

# Advisory: in a monorepo it's easy to build/run against a config found by walking UP from a subdir
# without noticing. Name the source (like `-b` announces its target). Run/build paths only; skipped
# under `-b` (PROJECT_DIR is then the targeted box's dir, already echoed).
case "${1:-run-default}" in
  run-default|run|shell|build|rebuild)
    [ "$PROJECT_DIR" != "$PWD" ] && [ -z "${SLUICE_BOX_TARGET:-}" ] \
      && echo "${E_DIM}[sluice]${E_RST} config from $(_tilde "$PROJECT_CONFIG") (box for $(_tilde "$PROJECT_DIR"))" >&2 ;;
esac

# Pre-run nudge: a config that declares auth vars (SLUICE_ENV) with none set on the host and no
# persisted session will likely fail to authenticate (the key is forwarded from your shell, never
# baked; headless OAuth can't complete). Warn, don't block; run-default path only.
warn_auth_unset() {
  [ -n "${SLUICE_ENV:-}" ] || return 0
  local v; for v in $SLUICE_ENV; do [ -n "${!v:-}" ] && return 0; done
  local store="${XDG_STATE_HOME:-$HOME/.local/state}/sluice/$slug"
  [ -n "${SLUICE_STATE_DIRS:-}" ] && [ -d "$store" ] && return 0
  echo "${E_YEL}[sluice] note:${E_RST} none of [$SLUICE_ENV] are set on the host - export one before running." >&2
  echo "         the key is forwarded from your shell (never baked); a browser OAuth login can't complete in the sandbox." >&2
}
case "${1:-run-default}" in run-default) warn_auth_unset ;; esac

# Laundering-host gate: an allowlisted host an attacker can also write to (S3, gists, pastebins, LLM
# APIs) lets data leak out even though it's allowlisted - we splice, never decrypt, so a request body
# to an allowed host isn't inspected (THREAT_MODEL "allowed-host laundering"). Nudge at session start;
# SLUICE_LAUNDERING_OK=1 acknowledges + silences, SLUICE_STRICT_LAUNDERING=1 refuses to run.
warn_laundering() {
  local risky="" h
  for h in ${SLUICE_ALLOW_DOMAINS:-}; do laundering_host "$h" && risky="$risky $h"; done
  [ -n "$risky" ] || return 0
  [ "${SLUICE_LAUNDERING_OK:-}" = 1 ] && return 0
  if [ "${SLUICE_STRICT_LAUNDERING:-}" = 1 ]; then
    echo "${E_RED}[sluice] refusing:${E_RST} allowlisted host(s) an attacker can also write to -${risky}" >&2
    echo "         data can be laundered out through them (we splice, not decrypt). Drop them, or set SLUICE_LAUNDERING_OK=1 to allow." >&2
    exit 1
  fi
  echo "${E_YEL}[sluice] note:${E_RST} allowlisted host(s) an attacker can also write to -${risky} - data can be laundered out (splice, not decrypt)." >&2
  echo "         keep the allowlist tight; SLUICE_LAUNDERING_OK=1 to acknowledge (silences this), SLUICE_STRICT_LAUNDERING=1 to refuse." >&2
}
case "${1:-run-default}" in run-default|run|shell) warn_laundering ;; esac

# SLUICE_ALLOW_IPS is a direct-egress escape hatch that BYPASSES squid (init-firewall.sh ACCEPTs it
# raw), and unlike the other path-y knobs it had no floor: a /0 opened all direct egress yet a broader-
# than-/0-by-pieces cover (0.0.0.0/1 128.0.0.0/1) or any short prefix (/1../7) slipped through, as did
# an IPv6 literal (which then mis-parses in the firewall). Floor = /8: refuse a prefix below /8 and any
# 0.0.0.0/N; refuse IPv6 (we are IPv4-only); loudly warn on a port-less (all-ports) entry. A /8-or-longer
# prefix, a single IP, an ip:port, and a bare host still pass. Each entry is ip[/cidr][:port[/proto]].
_ALLOW_IPS_MIN_PREFIX=8   # documented floor: a CIDR shorter than this is too broad for a direct-egress hatch
validate_allow_ips() {
  local e hostcidr plen
  set -f                              # the split below is unquoted-on-purpose; don't glob a '*' in a value
  for e in ${SLUICE_ALLOW_IPS:-}; do
    # Literal catch-alls (0.0.0.0, any /0): all direct egress.
    case "$e" in
      0.0.0.0|0.0.0.0:*|*/0) die "SLUICE_ALLOW_IPS='$e' opens direct egress to everything - refusing. Scope it to a host and port, e.g. 10.0.0.5:5432" ;;
    esac
    # IPv4-only: '::' shorthand, or 2+ colons (a full-form IPv6 literal) - refuse rather than let the
    # single-colon host/port split below feed iptables a broken -d (opaque fail-closed boot abort).
    case "$e" in *::*) die "SLUICE_ALLOW_IPS='$e' is an IPv6 literal - SLUICE_ALLOW_IPS is IPv4-only (the box proxies/filters v4; IPv6 egress is default-closed). Drop it or use the IPv4 address." ;; esac
    case "${e#*:}" in *:*) die "SLUICE_ALLOW_IPS='$e' is an IPv6 literal - SLUICE_ALLOW_IPS is IPv4-only. Drop it or use the IPv4 address." ;; esac
    # Floor: a CIDR shorter than /_ALLOW_IPS_MIN_PREFIX (and any 0.0.0.0/N, caught above) is too broad
    # for a raw direct-egress ACCEPT. Strip a trailing :port first; a bare host / single IP has no '/'.
    hostcidr="${e%%:*}"
    case "$hostcidr" in
      */*) plen="${hostcidr##*/}"
           case "$plen" in
             ''|*[!0-9]*) ;;          # non-numeric prefix: not a broad cover; leave it to the firewall
             *) [ "$plen" -lt "$_ALLOW_IPS_MIN_PREFIX" ] && die "SLUICE_ALLOW_IPS='$e' is a /$plen - too broad (floor is /$_ALLOW_IPS_MIN_PREFIX) for a direct-egress hatch that bypasses the proxy. Narrow it to /$_ALLOW_IPS_MIN_PREFIX or longer, e.g. 10.0.0.5:5432" ;;
           esac ;;
    esac
    case "$e" in
      *:*) ;;   # ip:port - scoped, fine
      *)   echo "${E_YEL}[sluice] WARNING:${E_RST} SLUICE_ALLOW_IPS '$e' has no port - it opens EVERY port to that host, direct (bypasses the hostname filter). Scope it: ${e}:PORT" >&2 ;;
    esac
  done
  set +f
}
case "${1:-run-default}" in run-default|run|shell|build|rebuild|update) validate_allow_ips ;; esac

# SLUICE_EGRESS_HOST_BUDGETS: "host=bytes .wildcard=bytes ..." - a detective per-host tx budget (over
# any host's cap, `sluice egress` exits non-zero). Validate strictly and fail CLOSED: a malformed token
# dies rather than silently no-op. (SLUICE_EGRESS_MAX_BYTES is silently ignored when malformed - src/20;
# this stricter contract is intentional and noted in docs/configuration.md: a silently-void budget is
# worse than a stop.)
validate_host_budgets() {
  local tok host bytes
  set -f
  for tok in ${SLUICE_EGRESS_HOST_BUDGETS:-}; do
    case "$tok" in
      *=*) host="${tok%%=*}"; bytes="${tok#*=}" ;;
      *)   set +f; die "SLUICE_EGRESS_HOST_BUDGETS entry '$tok' must be host=bytes (e.g. .s3.amazonaws.com=1048576)" ;;
    esac
    case "$host"  in '') set +f; die "SLUICE_EGRESS_HOST_BUDGETS entry '$tok' has an empty host" ;;
                     *[!A-Za-z0-9.-]*) set +f; die "SLUICE_EGRESS_HOST_BUDGETS host '$host' has invalid characters" ;; esac
    case "$bytes" in ''|*[!0-9]*) set +f; die "SLUICE_EGRESS_HOST_BUDGETS '$tok': '$bytes' is not a byte count" ;; esac
  done
  set +f
}
case "${1:-run-default}" in run-default|run|shell|build|rebuild|update) validate_host_budgets ;; esac

# SLUICE_EGRESS_HARD_CAP_BYTES: a PREVENTIVE in-box byte ceiling (xt_quota). Numeric and >= 1 MiB - boot
# deny/allow probes + TLS handshakes consume the quota, so a sub-1MiB cap would brick the box at boot.
# SLUICE_ALLOW_IPS_MAX_BYTES: a shared direct-IP budget (any numeric size). Both fail closed.
validate_egress_hard_caps() {
  case "${SLUICE_EGRESS_HARD_CAP_BYTES:-}" in
    '') ;;
    *[!0-9]*) die "SLUICE_EGRESS_HARD_CAP_BYTES must be a byte count (got '${SLUICE_EGRESS_HARD_CAP_BYTES}')" ;;
    *) [ "$SLUICE_EGRESS_HARD_CAP_BYTES" -ge 1048576 ] || die "SLUICE_EGRESS_HARD_CAP_BYTES must be >= 1048576 (1 MiB) - boot probes + TLS handshakes consume the budget; a smaller cap bricks the box at boot" ;;
  esac
  case "${SLUICE_ALLOW_IPS_MAX_BYTES:-}" in
    '') ;;
    *[!0-9]*) die "SLUICE_ALLOW_IPS_MAX_BYTES must be a byte count (got '${SLUICE_ALLOW_IPS_MAX_BYTES}')" ;;
  esac
}
case "${1:-run-default}" in run-default|run|shell|build|rebuild|update) validate_egress_hard_caps ;; esac

# SLUICE_BUMP_METHODS / SLUICE_BUMP_MAX_BODY are sed'd into squid.conf in-box (H5), so their charset is
# security-critical (injection). Validate host-side; the entrypoint re-validates (defense in depth).
validate_bump_controls() {
  local _m
  set -f
  for _m in ${SLUICE_BUMP_METHODS:-}; do
    case "$_m" in *[!A-Za-z]*) set +f; die "SLUICE_BUMP_METHODS token '$_m' must be letters only (an HTTP method, e.g. GET HEAD POST)" ;; esac
  done
  set +f
  case "${SLUICE_BUMP_MAX_BODY:-}" in
    '') ;;
    *[!0-9]*) die "SLUICE_BUMP_MAX_BODY must be a byte count (got '${SLUICE_BUMP_MAX_BODY}')" ;;
  esac
}
case "${1:-run-default}" in run-default|run|shell|build|rebuild|update) validate_bump_controls ;; esac

# build: assemble a temp context (core + this project's config) and build
# Verify a published base image's cosign signature (keyless/OIDC). Soft by default: warn if
# cosign is absent or the image is unsigned; SLUICE_REQUIRE_SIGNED=1 makes either case fatal.
verify_base() {
  local img="$1" att
  # Only the official base carries a signature we know how to verify. For any other ref (a mirror, a
  # custom base) REQUIRE_SIGNED must FAIL rather than silently pass - else the knob is a no-op exactly
  # for the enterprise mirror case it's meant to protect.
  case "$img" in
    ghcr.io/*sluice-base*) ;;
    *) [ "${SLUICE_REQUIRE_SIGNED:-}" = 1 ] && die "SLUICE_REQUIRE_SIGNED=1 but '$img' is not the official signed base (ghcr.io/.../sluice-base) - sluice can't verify a mirrored/custom ref. Use the official base or unset SLUICE_REQUIRE_SIGNED."
       return 0 ;;
  esac
  if ! command -v cosign >/dev/null 2>&1; then
    [ "${SLUICE_REQUIRE_SIGNED:-}" = 1 ] && die "SLUICE_REQUIRE_SIGNED=1 but cosign is not installed"
    echo "[sluice] ${E_YEL}note${E_RST}: cosign not installed - skipping base signature check ($img)" >&2; return 0
  fi
  if cosign verify "$img" \
       --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
       --certificate-identity-regexp='^https://github\.com/Pyronewbic/Sluice/\.github/workflows/publish-base\.yml@refs/tags/v' >/dev/null 2>&1; then
    echo "[sluice] ${E_GRN}cosign-verified${E_RST} base image: $img" >&2
    # also confirm the signed CycloneDX SBOM attestation (soft; bases signed before this had none).
    cosign verify-attestation --type cyclonedx "$img" \
      --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
      --certificate-identity-regexp='^https://github\.com/Pyronewbic/Sluice/\.github/workflows/publish-base\.yml@refs/tags/v' >/dev/null 2>&1 && att=0 || att=$?
    if [ "$att" = 0 ]; then
      echo "[sluice] ${E_GRN}cosign-verified${E_RST} SBOM attestation: $img" >&2
    else
      [ "${SLUICE_REQUIRE_SIGNED:-}" = 1 ] && die "no verifiable SBOM attestation for $img"
      echo "[sluice] ${E_YEL}note${E_RST}: $img is signed but has no verifiable SBOM attestation (continuing)" >&2
    fi
  else
    [ "${SLUICE_REQUIRE_SIGNED:-}" = 1 ] && die "cosign verification failed for $img"
    echo "[sluice] ${E_YEL}WARNING:${E_RST} could not verify $img (continuing; SLUICE_REQUIRE_SIGNED=1 to enforce)" >&2
  fi
}

# Best-effort stack label for `sluice ls`: the `(detected: X)` note `sluice init` writes into a
# scaffolded config; empty for hand-written / agent configs.
config_stack() { grep -oE 'detected: [^)]+' "$PROJECT_CONFIG" 2>/dev/null | head -1 | sed 's/detected: //' || true; }

build() {
  local tmp; tmp="$(mktemp -d)"
  cp -R "$CORE"/. "$tmp"/
  cp "$PROJECT_CONFIG" "$tmp/sluice.config.sh"
  # F2 dep prefetch: drop the declared manifests into ./prefetch so the project stage can fetch deps
  # at build (free egress) into a $HOME cache the runtime mount won't shadow. Always present (a .keep
  # for non-prefetch builds) so the Dockerfile COPY never fails on a missing dir.
  mkdir -p "$tmp/prefetch"; : > "$tmp/prefetch/.keep"
  local _pf
  set -f   # split the config list on whitespace, not glob it against $PWD
  for _pf in ${SLUICE_PREFETCH_FILES:-}; do
    [ -f "$PROJECT_DIR/$_pf" ] && cp "$PROJECT_DIR/$_pf" "$tmp/prefetch/" 2>/dev/null || true
  done
  set +f
  # Pinned replay (SLUICE_PIN=1): the Dockerfile always COPY's pin/, so keep a .keep there; drop the real
  # sluice.pin in ONLY when pin mode is active (so an env-only SLUICE_PIN=1 still crosses into the build).
  # _SLUICE_PIN_SKIP is an internal, non-contract flag the `update` path sets to re-resolve fresh first.
  mkdir -p "$tmp/pin"; : > "$tmp/pin/.keep"
  local _pin_active=""
  if [ "${SLUICE_PIN:-}" = 1 ] && [ "${_SLUICE_PIN_SKIP:-}" != 1 ]; then
    [ -f "$PROJECT_DIR/sluice.pin" ] || { rm -rf "$tmp"; die "SLUICE_PIN=1 but no sluice.pin - run 'sluice lock --pin' first"; }
    cp "$PROJECT_DIR/sluice.pin" "$tmp/pin/sluice.pin"
    _pin_active=1
  fi
  # Self-describing labels (read by `sluice ls`; not part of config_hash, so no spurious rebuild).
  # Hoist the hash: `local args=($(config_hash))` masks its exit status (local returns 0), so a failing
  # config_hash (e.g. shasum rc 127) would silently bake an empty label under set -e; assigned alone it dies.
  local _chash; _chash="$(config_hash)"
  local args=(--label "sluice.confighash=$_chash"
    --label "sluice.project=$PROJECT_DIR"
    --label "sluice.stack=$(config_stack)"
    --label "sluice.allowcount=$(printf '%s' "${SLUICE_ALLOW_DOMAINS:-}" | wc -w | tr -d ' ')"
    --label "sluice.ports=${SLUICE_PORTS:-}"
    --label "sluice.overlays=${SLUICE_OVERLAY_DIRS:-}"
    --label "sluice.desc=${SLUICE_DESC:-}" "$@")   # extra flags, e.g. --no-cache
  if [ -n "${SLUICE_BASE_IMAGE:-}" ]; then
    verify_base "$SLUICE_BASE_IMAGE"
    args+=(--build-arg "BASE_IMAGE=$SLUICE_BASE_IMAGE")     # project layer FROM the signed base
  fi
  # Pin mode: build FROM the exact base digest recorded in sluice.pin and turn on the replay legs.
  if [ -n "$_pin_active" ]; then
    args+=(--build-arg SLUICE_PIN=1)
    local _pinbase; _pinbase="$(awk '$1=="base"{print $2; exit}' "$PROJECT_DIR/sluice.pin")"
    case "$_pinbase" in *@sha256:*) ;; *) rm -rf "$tmp"; die "sluice.pin has no @sha256 base digest - re-run 'sluice lock --pin'" ;; esac
    if [ -n "${SLUICE_BASE_IMAGE:-}" ]; then
      # Signed-base build: the pinned base must be the same repo as the configured one (else re-pin).
      local _pbrepo="${_pinbase%@*}" _birepo="${SLUICE_BASE_IMAGE%@*}"; _birepo="${_birepo%:*}"; _pbrepo="${_pbrepo%:*}"
      [ "$_pbrepo" = "$_birepo" ] || { rm -rf "$tmp"; die "config base ($SLUICE_BASE_IMAGE) changed since the pin ($_pinbase) - re-run 'sluice lock --pin'"; }
      args+=(--build-arg "BASE_IMAGE=$_pinbase")   # FROM the pinned digest (verify_base already ran above)
    else
      args+=(--build-arg "WOLFI_BASE=$_pinbase")   # local build: pin the wolfi base by digest
    fi
  fi
  # Quiet the engine's build transcript (layer/apk/npm chatter) to a per-box log; on failure replay
  # the tail so the error is visible. The full transcript is always one `cat` away at the logged path.
  local _blog="${XDG_STATE_HOME:-$HOME/.local/state}/sluice/$slug/build.log"
  mkdir -p "$(dirname "$_blog")" 2>/dev/null || _blog="$(mktemp)"
  echo "[sluice] building $tag ... (log: $(_tilde "$_blog"))" >&2
  # SLUICE_BUILD_RETRIES (default 0): retry the build a few times for a flaky registry/network. Off
  # by default so a deterministic build error still fails fast; set e.g. =2 in CI.
  local _retries="${SLUICE_BUILD_RETRIES:-0}"; case "$_retries" in ''|*[!0-9]*) _retries=0 ;; esac
  local _try=0 _ok=""
  while :; do
    if "$ENGINE" build "${args[@]}" -t "$tag" "$tmp" >"$_blog" 2>&1; then _ok=1; break; fi
    [ "$_try" -lt "$_retries" ] || break
    _try=$((_try+1)); echo "[sluice] ${E_YEL}build failed${E_RST} - retry $_try/$_retries ..." >&2; sleep 2
  done
  rm -rf "$tmp"
  if [ -z "$_ok" ]; then
    echo "[sluice] ${E_YEL}build failed${E_RST} - last lines of $(_tilde "$_blog"):" >&2
    tail -n 40 "$_blog" >&2 2>/dev/null || true
    [ -n "$_pin_active" ] && echo "[sluice] ${E_YEL}note${E_RST}: pinned build (SLUICE_PIN=1) - a pinned version may no longer be served (Wolfi is rolling); 'sluice update' re-resolves + re-pins." >&2
    die "image build failed (transient registry/network error? re-run, or set SLUICE_BUILD_RETRIES=N to auto-retry; full log: $_blog)"
  fi
  # Pinned replay: the CLAIM is earned by VERIFICATION, not by the replay legs alone. Assert the built
  # image's inventory matches sluice.lock (write_pin refreshed it from the same pinned closure); die on
  # any drift so a partial replay can never pass as a verified pin.
  if [ -n "$_pin_active" ]; then
    local _pdrift; _pdrift="$(classify_drift "$(lock_drift 2>/dev/null || true)" 2>/dev/null || true)"
    if [ -n "$_pdrift" ]; then
      echo "[sluice] ${E_RED}pinned build did NOT match sluice.lock${E_RST} - replay drift:" >&2
      printf '%s\n' "$_pdrift" | render_drift_human err >&2
      die "pinned replay verification failed - the built image drifted from sluice.lock (a pinned version may be unavailable; 'sluice update' re-resolves + re-pins)"
    fi
    echo "[sluice] ${E_GRN}pinned build verified${E_RST}: inventory matches sluice.lock" >&2
  fi
  "$RUNNER" rm -f -v "$container" >/dev/null 2>&1 || true   # rebuilt image -> fresh container
  runtime_sync_image force
}

# Build only if the image is missing or its baked config hash is stale.
maybe_build() {
  local have want
  want="$(config_hash)"
  have="$("$ENGINE" image inspect -f '{{ index .Config.Labels "sluice.confighash" }}' "$tag" 2>/dev/null || true)"
  [ "$have" = "$want" ] || build
}

# True when no built image exists at all (a check has nothing to verify against).
image_missing() { ! "$ENGINE" image inspect "$tag" >/dev/null 2>&1; }
# True when the image exists but its baked confighash predates the current config (edited since build).
image_stale() {
  local have want
  want="$(config_hash)"
  have="$("$ENGINE" image inspect -f '{{ index .Config.Labels "sluice.confighash" }}' "$tag" 2>/dev/null || true)"
  [ -n "$have" ] && [ "$have" != "$want" ]
}

# SLUICE_MASK launch wiring: validate the patterns (die early; the doctor-side expander skips bad
# ones), then build the mount flags that shadow each CURRENT match - an empty read-only bind for a
# file, a tmpfs for a dir. The box still sees the path exists; it cannot read the contents. The
# empty source file lives in the sluice state root (stable across reboots, unlike a mktemp).
mask_validate() {
  local pat
  set -f   # validate the PATTERNS, not whatever they happen to glob to in $PWD
  for pat in ${SLUICE_MASK:-}; do
    case "$pat" in /*|*..*) die "SLUICE_MASK pattern must be a relative glob inside the project (no leading /, no ..): $pat" ;; esac
  done
  set +f
}
# Fills MASK_ARGS (engine mount flags) + MASKED_PATHS (display list) from the current matches.
mask_build_args() {
  MASK_ARGS=(); MASKED_PATHS=""
  [ -n "${SLUICE_MASK:-}" ] || return 0
  mask_validate
  local matches mp empty
  matches="$(mask_matches 2>/dev/null || true)"
  [ -n "$matches" ] || return 0
  empty="${XDG_STATE_HOME:-$HOME/.local/state}/sluice/.mask-empty"
  mkdir -p "${empty%/*}" 2>/dev/null || true
  [ -f "$empty" ] || : > "$empty" 2>/dev/null || true
  chmod 0444 "$empty" 2>/dev/null || true
  while IFS= read -r mp; do
    [ -n "$mp" ] || continue
    # Overlay workspace: mask the read-only original too, or the entrypoint's seed copy reads it.
    if [ -d "$PROJECT_DIR/$mp" ]; then
      MASK_ARGS+=(--tmpfs "$PROJECT_DIR/$mp")
      [ "${SLUICE_WORKSPACE:-}" = overlay ] && MASK_ARGS+=(--tmpfs "/mnt/sluice-orig/$mp")
    else
      MASK_ARGS+=(-v "$empty":"$PROJECT_DIR/$mp":ro)
      [ "${SLUICE_WORKSPACE:-}" = overlay ] && MASK_ARGS+=(-v "$empty":"/mnt/sluice-orig/$mp":ro)
    fi
    MASKED_PATHS="$MASKED_PATHS $mp"
  done <<EOF
$matches
EOF
  MASKED_PATHS="${MASKED_PATHS# }"
}

# Echo the git common dir to rw-mount for a LINKED worktree - but only when the worktree linkage
# verifies bidirectionally. In non-overlay mode the box (uid 1000) owns $PROJECT_DIR/.git and can rewrite
# it to `gitdir: <other repo>`, which would otherwise steer sluice into rw-mounting + chown'ing an
# arbitrary host repo (cross-repo rewrite; git-hook RCE on Linux). We mount $common only when it is
# OUTSIDE the project AND the worktree's own git dir sits under $common/worktrees/ AND its backlink
# ($common/worktrees/<id>/gitdir) points back at THIS project's .git - a file the box cannot forge (it
# lives outside the box's writable mount). Otherwise warn and mount nothing (use SLUICE_MOUNTS to opt in).
_validated_git_common_dir() {
  git -C "$PROJECT_DIR" rev-parse --git-common-dir >/dev/null 2>&1 || return 0
  local pd common gd back proj_git
  pd="$(cd "$PROJECT_DIR" 2>/dev/null && pwd -P || true)"; [ -n "$pd" ] || return 0
  common="$(git -C "$PROJECT_DIR" rev-parse --git-common-dir 2>/dev/null)"
  case "$common" in /*) ;; *) common="$PROJECT_DIR/$common" ;; esac
  common="$(cd "$common" 2>/dev/null && pwd -P || true)"
  [ -n "$common" ] || return 0
  case "$common/" in "$pd"/*) return 0 ;; esac          # common dir already inside the project mount
  gd="$(git -C "$PROJECT_DIR" rev-parse --absolute-git-dir 2>/dev/null)"
  gd="$(cd "$gd" 2>/dev/null && pwd -P || true)"
  proj_git="$pd/.git"
  if [ -n "$gd" ] && [ -f "$gd/gitdir" ]; then
    case "$gd/" in "$common"/worktrees/*)
      back="$(tr -d '\r\n' < "$gd/gitdir" 2>/dev/null)"
      case "$back" in /*)
        back="$(cd "$(dirname "$back")" 2>/dev/null && pwd -P || true)/$(basename "$back")"
        [ "$back" = "$proj_git" ] && { printf '%s\n' "$common"; return 0; } ;;
      esac ;;
    esac
  fi
  echo "[sluice] ${E_YEL:-}not mounting the git common dir${E_RST:-} ($common) - its worktree linkage doesn't verify against this repo; mount it explicitly via SLUICE_MOUNTS if intended." >&2
  return 0
}

# start: run the idle container (firewall comes up in the entrypoint)
start() {
  "$RUNNER" rm -f -v "$container" >/dev/null 2>&1 || true

  # Optional host-side hook to stage credentials/secrets before launch.
  if [ -n "${SLUICE_PRELAUNCH:-}" ]; then
    command -v "$SLUICE_PRELAUNCH" >/dev/null 2>&1 \
      || die "SLUICE_PRELAUNCH=$SLUICE_PRELAUNCH is not a function/command defined in sluice.config.sh"
    echo "[sluice] running prelaunch hook: $SLUICE_PRELAUNCH"
    "$SLUICE_PRELAUNCH"
  fi

  # On rootless podman, map the host user onto the sluice uid so the box doesn't re-own the repo to a
  # subuid (no-op on docker / rootful podman). Appends to RUNTIME_RUN_OPTS before runtime_run reads it.
  resolve_podman_userns

  # route_localnet -> squid intercept; disable_ipv6 -> v4-only proxy (set at run; /proc/sys is ro).
  # cap-drop ALL then add only what the root entrypoint needs: chown the mounted dir (CHOWN/
  # DAC_OVERRIDE/FOWNER), drop squid to its uid (SETUID/SETGID), the firewall (NET_ADMIN/NET_RAW),
  # dnsmasq on :53 (NET_BIND_SERVICE), SIGHUP squid on live reload (KILL). Sessions still run uid
  # 1000 with no effective caps; this shrinks what a hypothetical in-box root could reach.
  # no-new-privileges: an unprivileged session can never gain privs via a setuid binary (defence in
  # depth). pids-limit: a runaway agent or build can't fork-bomb the host (override with
  # SLUICE_PIDS_LIMIT; SLUICE_MEMORY caps RAM).
  local run_args=(--cap-drop ALL
    --cap-add CHOWN --cap-add DAC_OVERRIDE --cap-add FOWNER --cap-add SETUID --cap-add SETGID
    --cap-add NET_ADMIN --cap-add NET_RAW --cap-add NET_BIND_SERVICE --cap-add KILL
    --security-opt no-new-privileges
    --pids-limit "${SLUICE_PIDS_LIMIT:-4096}"
    --sysctl net.ipv4.conf.all.route_localnet=1
    --sysctl net.ipv6.conf.all.disable_ipv6=1
    --sysctl net.ipv6.conf.default.disable_ipv6=1)
  [ -n "${SLUICE_MEMORY:-}" ] && run_args+=(--memory "$SLUICE_MEMORY")
  # SLUICE_SECCOMP: opt-in seccomp on top of the dropped caps (unset = the engine's own profile).
  #   hardened - denylist that is a strict superset of the engine default (adds userfaultfd, the
  #              ASLR-disable path, ...); breaks browser-engine userns sandboxes.
  #   browser  - hardened minus the namespace/mount calls Chromium/Playwright need for their own
  #              userns sandbox (ptrace/bpf/modules/userfaultfd/... stay blocked).
  #   audit    - hardened, log-only (SCMP_ACT_LOG): observe what WOULD be blocked, enforce nothing.
  local _sc=""
  case "${SLUICE_SECCOMP:-}" in
    hardened) run_args+=(--security-opt "seccomp=$CORE/seccomp.json") ;;
    browser)  run_args+=(--security-opt "seccomp=$CORE/seccomp-browser.json") ;;
    audit)    # Write the log-only profile to the stable per-box state dir and overwrite in place, so
              # repeated runs don't leak a /tmp file each (a bare mktemp had no reaper - run-default/shell
              # then arm the receipt EXIT trap, which would clobber any rm trap we set here).
              _sc="${XDG_STATE_HOME:-$HOME/.local/state}/sluice/$slug/seccomp-audit.json"
              mkdir -p "${_sc%/*}" 2>/dev/null || _sc="$(mktemp "${TMPDIR:-/tmp}/sluice-seccomp-audit.XXXXXX")"
              sed 's/SCMP_ACT_ERRNO/SCMP_ACT_LOG/g' "$CORE/seccomp.json" > "$_sc"
              run_args+=(--security-opt "seccomp=$_sc") ;;
    ""|default) : ;;
    *) die "SLUICE_SECCOMP must be hardened, browser, or audit (got '${SLUICE_SECCOMP}')" ;;
  esac
  # SLUICE_READONLY_ROOT=1: immutable rootfs. tmpfs the ephemeral system paths; the two dirs that mix
  # baked content with runtime writes (/etc/squid, /home/sluice) become anon volumes (pre-populated
  # from the image, writable). resolv.conf can't be rewritten under --read-only, so we set it via
  # --dns 127.0.0.1 (-> dnsmasq) and hand the real upstream(s) to the entrypoint via SLUICE_DNS_UPSTREAM
  # (probed from a throwaway run). Probe on $RUNNER, not $ENGINE: under SLUICE_RUNTIME=kata the box
  # runs on nerdctl/containerd, whose resolver differs from docker's 127.0.0.11 - probing $ENGINE there
  # would hand dnsmasq an upstream that doesn't exist and silently break all name resolution.
  if [ "${SLUICE_READONLY_ROOT:-}" = 1 ]; then
    local _ro_up
    _ro_up="$("$RUNNER" run --rm --entrypoint sh "$tag" -c 'awk "/^nameserver/{print \$2}" /etc/resolv.conf | grep -v : | tr "\n" " "' 2>/dev/null | sed 's/ *$//')"
    [ -n "$_ro_up" ] || _ro_up="127.0.0.11"
    # Pin mode + size on the system tmpfs: the default (1777, uncapped) would let uid 1000 write these
    # system scratch dirs and fill /var/log/squid to starve squid's access log. /tmp stays 1777 (world
    # scratch); /run + the squid dirs are root/squid-owned 0755 (the entrypoint chowns the squid dirs)
    # and size-capped so a runaway can't exhaust host RAM.
    run_args+=(--read-only
      --tmpfs "/tmp:mode=1777" --tmpfs "/run:mode=0755,size=16m"
      --tmpfs "/var/log/squid:mode=0755,size=64m" --tmpfs "/var/cache/squid:mode=0755,size=256m"
      -v /etc/squid -v /home/sluice
      --dns 127.0.0.1 -e "SLUICE_DNS_UPSTREAM=$_ro_up" -e SLUICE_READONLY_ROOT=1)
  fi
  # SELinux-enforcing hosts deny the box access to a bind mount without a label; run it unconfined for
  # SELinux only (non-root + caps + egress firewall + dir-only mount still confine it).
  selinux_enforcing && run_args+=(--security-opt label=disable)

  # Central policy (SLUICE_POLICY_URL + user/system policy.conf) is applied host-side in apply_policy
  # (slice 60): allow folds into SLUICE_ALLOW_DOMAINS, deny narrows it, forbid/ceilings already gated
  # the run. So the SLUICE_RUNTIME_ALLOW below carries the policy-effective list - no separate pass.

  # Pass the live allowlist at runtime (wins over the baked copy) so an edit (e.g. `sluice learn`) needs
  # no rebuild. Always set, even empty: a removed host takes effect, and the entrypoint can tell it's
  # sluice-launched, not a bare `docker run`.
  run_args+=(-e "SLUICE_RUNTIME_ALLOW=${SLUICE_ALLOW_DOMAINS:-}")

  # Scoped TLS interception (opt-in, default off): SLUICE_BUMP_DOMAINS hosts get decrypted for URL
  # filtering (SLUICE_BUMP_URLS); everything else splices. Passed like the allowlist (live edits, no
  # rebuild). When on, the box mints a per-container CA; the CA-trust env below points clients at it.
  run_args+=(-e "SLUICE_RUNTIME_BUMP=${SLUICE_BUMP_DOMAINS:-}" -e "SLUICE_RUNTIME_BUMP_URLS=${SLUICE_BUMP_URLS:-}")
  # Bumped-lane upload controls (opt-in, only meaningful with SLUICE_BUMP_DOMAINS): a method allowlist +
  # a request-body cap, passed like the other bump knobs (applied at container start, no image rebuild).
  run_args+=(-e "SLUICE_RUNTIME_BUMP_METHODS=${SLUICE_BUMP_METHODS:-}" -e "SLUICE_RUNTIME_BUMP_MAX_BODY=${SLUICE_BUMP_MAX_BODY:-}")
  if [ -n "${SLUICE_BUMP_DOMAINS:-}" ]; then
    run_args+=(-e "NODE_EXTRA_CA_CERTS=/etc/squid/ssl/squid-cert.pem" \
               -e "SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt" \
               -e "REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt")
  fi

  # Mount the project dir rw; SLUICE_WORKDIR tells the entrypoint to chown it to sluice (Linux uid).
  # SLUICE_WORKSPACE=overlay: protect the host repo - mount it READ-ONLY at /mnt/sluice-orig and give
  # the box a writable COPY at the same path (an anon volume the entrypoint fills from the orig). The
  # agent can't touch the host repo; review with `sluice diff`, write back with `sluice apply`.
  if [ "${SLUICE_WORKSPACE:-}" = overlay ]; then
    run_args+=(-v "$PROJECT_DIR":/mnt/sluice-orig:ro -v "$PROJECT_DIR" \
               -e "SLUICE_WORKDIR=$PROJECT_DIR" -e SLUICE_WORKSPACE=overlay)
  else
    run_args+=(-v "$PROJECT_DIR":"$PROJECT_DIR" -e "SLUICE_WORKDIR=$PROJECT_DIR")
  fi

  # git worktree: also mount the common dir (when outside the project) so refs resolve + write. Skipped
  # in overlay mode - an rw common-dir mount would let the agent escape the read-only protection. The
  # linkage is validated so a box-rewritten .git can't redirect the mount to an arbitrary repo (see helper).
  if [ "${SLUICE_WORKSPACE:-}" != overlay ]; then
    local common; common="$(_validated_git_common_dir)"
    [ -n "$common" ] && run_args+=(-v "$common":"$common" -e "SLUICE_GITDIR=$common")
  fi

  # Extra mounts (newline-separated host:container[:ro]).
  if [ -n "${SLUICE_MOUNTS:-}" ]; then
    while IFS= read -r m; do
      [ -n "$m" ] && run_args+=(-v "$m")
    done <<EOF
$SLUICE_MOUNTS
EOF
  fi

  # SLUICE_STATE_DIRS: bind-mount each home-relative dir from a per-project host store
  # ($XDG_STATE_HOME/sluice/<slug>) so agent sessions/auth survive recreation. Relative dirs only
  # (rejected below); never a baked path (.npm-global, cursor's .local).
  if [ -n "${SLUICE_STATE_DIRS:-}" ]; then
    local state_base="${XDG_STATE_HOME:-$HOME/.local/state}/sluice/$slug" sd state_paths=""
    set -f   # split the config list on whitespace, not glob it against $PWD
    for sd in ${SLUICE_STATE_DIRS}; do
      case "$sd" in /*|*..*) die "SLUICE_STATE_DIRS entry must be a relative path under the home dir: $sd";; esac
      mkdir -p "$state_base/$sd"
      run_args+=(-v "$state_base/$sd":"/home/sluice/$sd")
      state_paths="$state_paths /home/sluice/$sd"
    done
    set +f
    run_args+=(-e "SLUICE_STATE_PATHS=$state_paths")
  fi

  # SLUICE_OVERLAY_DIRS: a per-box named volume over each project-relative dir, so the box keeps its
  # own contents (e.g. Linux-built node_modules) while the host's stay untouched. The volume starts
  # EMPTY (install in the box), persists across container recreation, and is labeled for cleanup
  # ('sluice rm'/'prune'). The entrypoint chowns a fresh volume to the sluice user (SLUICE_OVERLAY_PATHS).
  if [ -n "${SLUICE_OVERLAY_DIRS:-}" ]; then
    local od ovol opaths="" odirs=""
    set -f   # split the config list on whitespace, not glob it against $PWD
    for od in ${SLUICE_OVERLAY_DIRS}; do
      case "$od" in /*|*..*) die "SLUICE_OVERLAY_DIRS entry must be a relative path inside the project (no leading /, no ..): $od" ;; esac
      od="${od%/}"
      ovol="sluice-$slug-ov-$(printf '%s' "$od" | tr '[:upper:]' '[:lower:]' | tr -C 'a-z0-9' '-')"
      "$RUNNER" volume create --label "sluice.box=$container" "$ovol" >/dev/null 2>&1 || true
      run_args+=(-v "$ovol":"$PROJECT_DIR/$od")
      opaths="$opaths $PROJECT_DIR/$od"; odirs="$odirs $od"
    done
    set +f
    run_args+=(-e "SLUICE_OVERLAY_PATHS=$opaths")
    echo "[sluice] overlay dirs (box-local volumes, host contents untouched):$odirs" >&2
  fi

  # SLUICE_MASK: shadow in-repo secrets (empty ro bind / tmpfs over each match). Evaluated NOW -
  # a file created later in the run is not masked (THREAT_MODEL.md).
  mask_build_args
  if [ "${#MASK_ARGS[@]}" -gt 0 ]; then
    run_args+=("${MASK_ARGS[@]}")
    _nmask="$(printf '%s' "$MASKED_PATHS" | wc -w | tr -d ' ')"
    echo "[sluice] masking $_nmask in-repo path(s) (unreadable in the box) - see 'sluice doctor'" >&2
  fi

  # Publish declared ports on host loopback only; init-firewall.sh opens the inbound ACCEPT.
  set -f   # split the config list on whitespace, not glob it against $PWD
  for p in ${SLUICE_PORTS:-}; do
    run_args+=(-p "127.0.0.1:$p:$p")
  done
  set +f

  echo "[sluice] starting $container ..."
  runtime_run --name "$container" "${run_args[@]}" "$tag" >/dev/null
  local tries=60; [ "$RUNNER" != "$ENGINE" ] && tries=120   # a Kata micro-VM takes longer to boot
  for _ in $(seq 1 "$tries"); do
    "$RUNNER" logs "$container" 2>&1 | grep -q "\[sluice\] ready" && break
    sleep 0.5
  done
  running || die "container failed to come up - see: sluice logs"
}

ensure_up() { maybe_build; runtime_sync_image; running || start; }

# Build the `<engine> exec` arg vector (sluice user, SLUICE_ENV forwarded, TTY only when attached).
_exec_args() {
  _EXEC_ARGS=(-i --user sluice -w "$PROJECT_DIR")
  [ -t 0 ] && [ -t 1 ] && _EXEC_ARGS+=(-t)
  set -f   # split the config list on whitespace, not glob it against $PWD
  for v in ${SLUICE_ENV:-}; do
    _EXEC_ARGS+=(-e "$v")
  done
  set +f
}
# exec_in replaces this process (shell/run); run_in waits so an EXIT trap can fire after (run-default).
exec_in() { _exec_args; exec "$RUNNER" exec "${_EXEC_ARGS[@]}" "$container" "$@"; }
run_in()  { _exec_args; "$RUNNER" exec "${_EXEC_ARGS[@]}" "$container" "$@"; }

# --- overlay workspace (SLUICE_WORKSPACE=overlay) -------------------------------------------------
# The host repo is mounted read-only at /mnt/sluice-orig; the box works on a writable copy at
# $SLUICE_WORKDIR (== $PROJECT_DIR). The agent can't touch the host repo; these compare/apply the copy.
workspace_is_overlay() { [ "${SLUICE_WORKSPACE:-}" = overlay ]; }

# Echo "added modified deleted" counts between the protected orig and the working copy (0 0 0 if down).
# The working-copy path is passed as $1 (docker exec does NOT inherit the run-time -e SLUICE_WORKDIR).
# Deletions are counted against the boot-time snapshot (/run/sluice-orig-manifest), matching what
# `sluice apply` removes - so a file the host added mid-session never inflates the deleted count.
workspace_counts() {
  running || { echo "0 0 0"; return 0; }
  _root_exec "$container" sh -c '
    O=/mnt/sluice-orig; W="$1"; [ -d "$O" ] || { echo "0 0 0"; exit 0; }
    d="$(diff -rq "$O" "$W" 2>/dev/null)"
    added="$(printf "%s\n" "$d" | grep -c "^Only in $W")"
    modified="$(printf "%s\n" "$d" | grep -c " differ$")"
    if [ -f /run/sluice-orig-manifest ]; then
      cd "$W" && find . -mindepth 1 | sort > /tmp/w
      deleted="$(comm -23 /run/sluice-orig-manifest /tmp/w | grep -c .)"
    else
      deleted="$(printf "%s\n" "$d" | grep -c "^Only in $O")"   # pre-snapshot box: legacy live compare
    fi
    printf "%s %s %s\n" "$added" "$modified" "$deleted"
  ' _ "$PROJECT_DIR" 2>/dev/null || echo "0 0 0"
}

# `sluice diff`: a unified diff of the working copy vs the protected original (.git excluded for signal).
cmd_workspace_diff() {
  workspace_is_overlay || die "sluice diff needs SLUICE_WORKSPACE=overlay (the protected-copy workspace)"
  ensure_up
  _root_exec "$container" sh -c 'diff -ruN --exclude=.git /mnt/sluice-orig "$1" 2>/dev/null' _ "$PROJECT_DIR" || true
}

# `sluice apply`: write the working copy back onto the host repo (adds/mods via tar, then deletions).
cmd_workspace_apply() {
  workspace_is_overlay || die "sluice apply needs SLUICE_WORKSPACE=overlay"
  running || die "the box isn't running - nothing to apply (run 'sluice' first)"
  local a m d; read -r a m d <<EOF
$(workspace_counts)
EOF
  if [ "$((a + m + d))" -eq 0 ]; then echo "[sluice] working copy matches the repo - nothing to apply"; return 0; fi
  # apply WRITES to the host repo - confirm interactively, and refuse non-interactively unless
  # SLUICE_YES=1 (matching 'sluice prune'). The old code fell through and applied on any non-tty.
  if [ -t 0 ] && [ -t 1 ] && [ "${SLUICE_YES:-}" != 1 ]; then
    printf '[sluice] write %s added, %s modified, %s deleted to %s? [y/N] ' "$a" "$m" "$d" "$PROJECT_DIR"
    local ans; read -r ans || ans=n
    case "$ans" in [yY]|[yY][eE][sS]) ;; *) echo "[sluice] not applied."; return 0 ;; esac
  elif [ "${SLUICE_YES:-}" != 1 ]; then
    echo "[sluice] non-interactive: re-run with SLUICE_YES=1 to write these changes to $PROJECT_DIR."
    return 0
  fi
  # Adds + modifications: tar the working copy over the host repo. Surface failures (no 2>/dev/null,
  # check the pipe status) instead of printing a false 'applied'.
  if ! _root_exec "$container" sh -c 'cd "$1" && tar -cf - .' _ "$PROJECT_DIR" | tar -C "$PROJECT_DIR" -xf -; then
    die "apply failed writing to $PROJECT_DIR (check permissions and free space; the host repo may be partially updated)"
  fi
  # Deletions: remove host files the box deleted, against the BOOT-TIME snapshot (not the live ro
  # mount), so a file the host created mid-session is never mistaken for a box deletion (B4).
  # SLUICE_APPLY_NO_DELETE=1 keeps them; a box built before the snapshot existed fails safe.
  local applied_del="$d"
  if [ "$d" -eq 0 ]; then :
  elif [ "${SLUICE_APPLY_NO_DELETE:-}" = 1 ]; then
    echo "[sluice] ${E_YEL}SLUICE_APPLY_NO_DELETE=1${E_RST} - keeping the $d host file(s) the box deleted." >&2
    applied_del=0
  elif _root_exec "$container" sh -c 'test -f /run/sluice-orig-manifest' 2>/dev/null; then
    _root_exec "$container" sh -c 'cd "$1" && find . -mindepth 1 | sort > /tmp/w; comm -23 /run/sluice-orig-manifest /tmp/w' _ "$PROJECT_DIR" 2>/dev/null \
      | while IFS= read -r p; do [ -n "$p" ] && rm -rf "${PROJECT_DIR:?}/${p#./}" 2>/dev/null; done
  else
    echo "[sluice] ${E_YEL}note:${E_RST} this box predates the apply-safety snapshot - skipping the $d deletion(s); 'sluice rebuild' then re-apply to propagate them." >&2
    applied_del=0
  fi
  echo "[sluice] applied $a added, $m modified, $applied_del deleted to $PROJECT_DIR."
}

# After a run-default session, print an egress receipt: hosts the box reached (hit counts, most-hit
# first) and hosts the firewall blocked (review these). stderr-only so it never pollutes the app's
# stdout; silent when there was no egress. Detailed per-host view: `sluice egress`.
# Persist one run's receipt host-side (outside the box the workload can reach): a "latest" snapshot
# (egress-receipt.json, back-compat) AND an append-only, hash-chained audit log (egress-log.jsonl).
# Each log line carries prev = the previous line's `self`, and self = sha256 of the line up to `self`
# (genesis prev = 64 zeros), so editing/reordering/dropping any line breaks the chain -> `sluice egress
# --verify`. $1 = the egress rows (may be empty), $2 = status (ok | unavailable).
_persist_receipt() {
  local rows="$1" rstatus="$2" TAB _dir _log _inner _hj="" _first=1 _cls _host _cnt _byt \
        _reached _blocked _tot _ts _run _prev _self _payload
  TAB="$(printf '\t')"
  _dir="${XDG_STATE_HOME:-$HOME/.local/state}/sluice/$slug"
  mkdir -p "$_dir" 2>/dev/null || return 0
  _log="$_dir/egress-log.jsonl"
  _ts="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null)"; _run="${_ts}-$$"
  while IFS="$TAB" read -r _cls _host _cnt _byt; do
    [ -n "$_host" ] || continue
    [ "$_first" = 1 ] && _first=0 || _hj="$_hj,"
    _hj="$_hj{\"host\":\"$(_json_esc "$_host")\",\"class\":\"$_cls\",\"requests\":$_cnt,\"bytes\":$_byt}"
  done <<EOF
$rows
EOF
  _reached="$(printf '%s\n' "$rows" | awk -F"$TAB" '$1=="reached"' | grep -c . || true)"
  _blocked="$(printf '%s\n' "$rows" | awk -F"$TAB" '$1=="blocked"' | grep -c . || true)"
  _tot="$(printf '%s\n' "$rows" | awk -F"$TAB" '{t+=$4} END{print t+0}')"
  # record body (no chain fields), versioned. box/totals/hosts/confighash/allowlist stay back-compat.
  _inner="$(printf '"schema":"sluice.egress/v1","run":"%s","ts":"%s","box":"%s","status":"%s","confighash":"%s","allowlist":%s,"totals":{"reached":%s,"blocked":%s,"bytes":%s},"hosts":[%s]' \
    "$_run" "$_ts" "$(_json_esc "$container")" "$rstatus" "$(config_hash 2>/dev/null || true)" \
    "$(allowed_domains | tr ' ' '\n' | _json_arr)" "${_reached:-0}" "${_blocked:-0}" "${_tot:-0}" "$_hj")"
  # Additive M2 sections, inserted BEFORE the trailing prev/self chain fields (the receipt-line invariant):
  # direct-IP (SLUICE_ALLOW_IPS) counters + firewall-dropped total, and the DNS audit summary. Empty
  # strings when the knobs are off, so an unchanged box keeps a byte-identical record. Only on a readable
  # box (a down box has no counters to read).
  if [ "$rstatus" = ok ]; then _inner="$_inner$(_allowips_json_fields)$(_dns_json_fields)"; fi
  printf '{%s}\n' "$_inner" > "$_dir/egress-receipt.json" 2>/dev/null || true
  # prev = the previous record's self (genesis = 64 zeros). Guard the read: a first-run tail on the
  # not-yet-existing log exits non-zero, which under the launcher's set -e/pipefail would abort here.
  _prev=""
  [ -f "$_log" ] && _prev="$(tail -n 1 "$_log" 2>/dev/null | sed -n 's/.*,"self":"\([0-9a-f]*\)"}$/\1/p')"
  [ -n "$_prev" ] || _prev="0000000000000000000000000000000000000000000000000000000000000000"
  _payload="{${_inner},\"prev\":\"${_prev}\"}"
  _self="$(printf '%s' "$_payload" | _sha256)"
  printf '%s,"self":"%s"}\n' "${_payload%\}}" "$_self" >> "$_log" 2>/dev/null || true
}

show_egress_receipt() {
  local rows TAB reached_rows blocked_rows ordered grn="" red="" dim="" bld="" rst=""
  rows="$(egress_rows 2>/dev/null || true)"
  if [ -z "$rows" ]; then
    # Box gone before capture (concurrent stop / crash / host OOM): record the gap explicitly so a
    # missing receipt can't read as a clean zero-egress run. A live box with no egress stays silent.
    if ! running; then
      _persist_receipt "" unavailable
      echo "[sluice] ${E_YEL:-}egress receipt unavailable${E_RST:-} - box exited before capture" >&2
    elif ! _audit_readable; then
      # Box is up but the in-box audit read couldn't run (pids cgroup exhausted): record the gap rather
      # than let an unreadable run look like clean zero egress.
      _persist_receipt "" unavailable
      echo "[sluice] ${E_YEL:-}egress receipt unavailable${E_RST:-} - could not read the in-box audit log (pids limit?)" >&2
    fi
    return 0
  fi
  TAB="$(printf '\t')"
  reached_rows="$(printf '%s\n' "$rows" | awk -F"$TAB" '$1=="reached"' | sort -t"$TAB" -k4,4nr)"
  blocked_rows="$(printf '%s\n' "$rows" | awk -F"$TAB" '$1=="blocked"' | sort -t"$TAB" -k2,2)"
  ordered="$(printf '%s\n%s\n' "$reached_rows" "$blocked_rows" | awk 'NF')"
  if [ -t 2 ] && [ -z "${NO_COLOR:-}" ]; then
    grn=$'\033[32m'; red=$'\033[31m'; dim=$'\033[2m'; bld=$'\033[1m'; rst=$'\033[0m'
  fi
  # Render summary header + aligned rows on stderr (so it never pollutes the app's stdout).
  printf '%s\n' "$ordered" | awk -F"$TAB" \
    -v box="$container" -v grn="$grn" -v red="$red" -v dim="$dim" -v bld="$bld" -v rst="$rst" '
    function human(b){ if(b<1024) return b" B"; else if(b<1048576) return sprintf("%.1f KB",b/1024); else return sprintf("%.1f MB",b/1048576) }
    { cls[NR]=$1; host[NR]=$2; cnt[NR]=$3; byt[NR]=$4; total+=$4;
      if($1=="reached"){ nr++; if(nr<=10 && length($2)>w) w=length($2) } else { nb++; if(length($2)>w) w=length($2) } }
    END {
      printf "%s[sluice] egress receipt: %s%s   %d reached, %d blocked, %s\n", bld, box, rst, nr, nb, human(total);
      sr=0;
      for(i=1;i<=NR;i++){
        if(cls[i]=="reached"){
          sr++;
          if(sr==11){ printf "  %s+%d more (sluice egress)%s\n", dim, nr-10, rst; }
          if(sr>10) continue;
          printf "  %sreached%s   %-*s  %3d req   %s\n", grn, rst, w, host[i], cnt[i], human(byt[i]);
        } else {
          printf "  %sblocked%s   %-*s  %3d req   %snot allowlisted (sluice learn)%s\n", red, rst, w, host[i], cnt[i], dim, rst;
        }
      }
      if(nb==0) printf "  %sall egress was allowlisted%s\n", grn, rst;
    }' >&2

  _persist_receipt "$rows" ok   # latest snapshot + append to the hash-chained audit log

  # SLUICE_ALLOW_IPS direct-egress (bypasses squid) + firewall-drop visibility; a busted shared budget flags loud.
  if [ -n "${SLUICE_ALLOW_IPS:-}" ]; then
    local _re _rp _rb; allowips_rows 2>/dev/null | while IFS="$TAB" read -r _re _rp _rb; do
      [ -n "$_re" ] || continue
      printf '  %sdirect-ip%s %s  %s pkt  %s\n' "$dim" "$rst" "$_re" "$_rp" "$(_human_bytes "${_rb:-0}")" >&2
    done
    if [ -n "${SLUICE_ALLOW_IPS_MAX_BYTES:-}" ]; then
      local _rad; _rad="$(allowips_dropped 2>/dev/null || true)"; case "$_rad" in ''|*[!0-9]*) _rad=0 ;; esac
      [ "$_rad" -gt 0 ] && printf '%s[sluice] direct-ip budget exceeded:%s %s pkt dropped - `sluice egress` will fail CI.\n' "$red" "$rst" "$_rad" >&2
    fi
  fi
  # DNS audit tunnel-pattern flags (SLUICE_DNS_AUDIT=1).
  if [ "${SLUICE_DNS_AUDIT:-}" = 1 ]; then
    local _sp _sq _su _stq=0 _stu=0 _sthr; _sthr="${SLUICE_DNS_TUNNEL_THRESHOLD:-500}"; case "$_sthr" in ''|*[!0-9]*) _sthr=500 ;; esac
    while IFS="$TAB" read -r _sp _sq _su; do
      [ -n "$_sp" ] || continue; _stq=$((_stq + _sq)); _stu=$((_stu + _su))
      [ "$_su" -ge "$_sthr" ] && printf '%s[sluice] possible DNS-tunnel pattern%s under %s (%s unique names)\n' "$red" "$rst" "$_sp" "$_su" >&2
    done <<EOF
$(dns_rows 2>/dev/null || true)
EOF
    printf '  %sdns: %s queries, %s unique names%s\n' "$dim" "$_stq" "$_stu" "$rst" >&2
  fi

  # SLUICE_EGRESS_MAX_BYTES: loud warning when this run sent more than the cap (bounds laundering
  # through an allowed host). `sluice egress` is the CI gate (exits non-zero); the receipt just nudges.
  case "${SLUICE_EGRESS_MAX_BYTES:-}" in
    ''|*[!0-9]*) ;;
    *) local _tx; _tx="$(egress_tx_total 2>/dev/null || echo 0)"; case "$_tx" in ''|*[!0-9]*) _tx=0;; esac
       [ "$_tx" -gt "$SLUICE_EGRESS_MAX_BYTES" ] && \
         printf '%s[sluice] egress budget exceeded:%s %s sent > %s cap - `sluice egress` will fail CI.\n' \
           "$red" "$rst" "$(_human_bytes "$_tx")" "$(_human_bytes "$SLUICE_EGRESS_MAX_BYTES")" >&2 ;;
  esac

  # SLUICE_EGRESS_HOST_BUDGETS: a run-scoped nudge per reached host over its own cap (`sluice egress`
  # is the CI gate that exits non-zero). Mirrors the total-budget warning above.
  if [ -n "${SLUICE_EGRESS_HOST_BUDGETS:-}" ]; then
    local _hbh _hbtx _hbcap
    egress_tx_by_host 2>/dev/null | while IFS="$TAB" read -r _hbh _hbtx; do
      [ -n "$_hbh" ] || continue
      _hbcap="$(_host_budget_for "$_hbh")"; [ -n "$_hbcap" ] || continue
      case "$_hbtx" in ''|*[!0-9]*) _hbtx=0 ;; esac
      [ "$_hbtx" -gt "$_hbcap" ] && \
        printf '%s[sluice] host budget exceeded:%s %s sent %s > %s cap - `sluice egress` will fail CI.\n' \
          "$red" "$rst" "$_hbh" "$(_human_bytes "$_hbtx")" "$(_human_bytes "$_hbcap")" >&2
    done
  fi
}

# Write/replace the SLUICE_ALLOW_DOMAINS line in the project config (interactive + --apply share this).
apply_allowlist() {
  local val="$1" tmp
  if grep -q '^SLUICE_ALLOW_DOMAINS=' "$PROJECT_CONFIG"; then
    tmp="$(mktemp)"
    awk -v v="$val" '/^SLUICE_ALLOW_DOMAINS=/ && !seen {print "SLUICE_ALLOW_DOMAINS=\"" v "\""; seen=1; next} {print}' \
      "$PROJECT_CONFIG" > "$tmp" && mv "$tmp" "$PROJECT_CONFIG"
  else
    printf 'SLUICE_ALLOW_DOMAINS="%s"\n' "$val" >> "$PROJECT_CONFIG"
  fi
  chmod 0644 "$PROJECT_CONFIG" 2>/dev/null || true   # mktemp is 0600; the build sources it as the sluice user
}

# Merged allowlist value: existing SLUICE_ALLOW_DOMAINS + the given (newline) entries, unique.
merge_allow() {
  printf '%s %s\n' "${SLUICE_ALLOW_DOMAINS:-}" "$(printf '%s' "$1" | tr '\n' ' ')" \
    | tr ' ' '\n' | sed '/^$/d' | sort -u | tr '\n' ' ' | sed 's/ *$//'
}

# Append entries to the box's squid allowlist + SIGHUP squid (reconfigure: re-reads the acl files) so
# picks go live with no rebuild. squid runs `squid -N` (no pid file, so `squid -k` can't signal it),
# hence pkill. Also regenerate the DNS servers-file from the new allowlist + SIGHUP dnsmasq, so a
# newly-allowed host resolves too (resolution is allowlist-scoped). Non-zero if the box is down or the
# reload fails; the DNS step is best-effort (no-op on SLUICE_DNS_OPEN boxes / older images).
reload_allowlist() {
  [ "$#" -gt 0 ] || return 0
  running || return 1
  printf '%s\n' "$@" | _root_exec -i "$container" sh -c \
    'cat >> /etc/squid/allowlist.txt && sort -u /etc/squid/allowlist.txt -o /etc/squid/allowlist.txt && pkill -HUP -x squid && { [ -x /usr/local/bin/sluice-dns-allow ] && /usr/local/bin/sluice-dns-allow && pkill -HUP -x dnsmasq; true; }' \
    >/dev/null 2>&1
}

# Persist chosen entries to the project config AND make them live on the running box (no rebuild).
# Before either, filter the picks the same way the boot path does (core/entrypoint.sh drop_doh):
# a DoH/DoT resolver is an exfil channel blocked even when allowlisted, so learn must NOT add it -
# to config or live - unless SLUICE_ALLOW_DOH=1. Without this the live squid reload (which appends
# straight to the post-filter allowlist) would re-open DoH while a rebuilt box re-blocks it, so the
# running box would silently diverge from its own config. Laundering hosts are allowed (boot allows
# them too) but warned, matching the session-start gate.
learn_apply() {   # $1 = newline-separated entries (hosts and/or .domains)
  local entries="$1" keep="" doh="" launder="" pden="" pdeny="" ptxt="" e h
  # A central policy can DENY a host; the live reload appends straight to the running box's allowlist,
  # so learn enforces the deny here too. Fetch the policy the same way apply_policy does (fail CLOSED):
  # if SLUICE_POLICY_URL is unreachable, _policy_raw dies and this aborts before we add/write/reload,
  # rather than apply without the deny list.
  if policy_configured; then ptxt="$(_policy_raw)"; pdeny="$(printf '%s\n' "$ptxt" | awk '$1=="deny"{print $2}')"; fi
  while IFS= read -r e; do
    [ -n "$e" ] || continue
    h="${e#.}"   # a .domain wildcard matches by its bare host
    if [ "${SLUICE_ALLOW_DOH:-}" != 1 ] && doh_listed "$e"; then doh="$doh $e"; continue; fi   # $e keeps the leading dot so a wildcard covering a DoH host is caught
    if [ -n "$pdeny" ] && { _policy_denied_host "$h" "$pdeny" || _allow_covers_denied "$e" "$pdeny"; }; then pden="$pden $e"; continue; fi
    laundering_host "$h" && launder="$launder $e"
    keep="$keep $e"
  done <<EOF
$entries
EOF
  keep="${keep# }"

  if [ -n "$pden" ]; then
    echo "[sluice] ${E_YEL}not allowing (denied by central policy):${E_RST}$pden" >&2
  fi
  if [ -n "$doh" ]; then
    echo "[sluice] ${E_YEL}not allowing DoH/DoT resolver(s):${E_RST}$doh" >&2
    echo "         these tunnel DNS over HTTPS past the SNI filter - blocked even when allowlisted." >&2
    echo "         set SLUICE_ALLOW_DOH=1 (weakens the guarantee) and re-run 'sluice learn' to permit." >&2
  fi
  if [ -z "$keep" ]; then
    echo "[sluice] ${C_DIM}nothing added.${C_RST}"
    return 0
  fi
  [ -n "$launder" ] && echo "[sluice] ${E_YEL}note:${E_RST} allowlisted host(s) an attacker can also write to -$launder - data can be laundered out (splice, not decrypt); keep the list tight." >&2

  apply_allowlist "$(merge_allow "$keep")"
  # shellcheck disable=SC2086
  echo "[sluice] ${C_GRN}allowing:${C_RST} $(printf '%s ' $keep | sed 's/  */ /g; s/ *$//')"
  echo "[sluice] wrote $(_tilde "$PROJECT_CONFIG")"
  # shellcheck disable=SC2086
  if reload_allowlist $keep; then
    echo "[sluice] reloaded the running box (squid reconfigure) - ${C_GRN}live now, no rebuild.${C_RST}"
  else
    echo "[sluice] config saved - run 'sluice rebuild' to apply (couldn't hot-reload)."
  fi
}

# Interactive review of candidate "<host>\t<count>\t<bytes>" rows: offer `.parent` wildcard collapses,
# then per-host allow/skip/domain, then persist + hot-reload. Shared by learn + learn --audit; falls
# back to a plain list when there's no tty.
_learn_review() {
  local rows="$1" label="$2" TAB; TAB="$(printf '\t')"
  if [ ! -t 0 ] && [ ! -t 1 ]; then
    echo "[sluice] $label:"
    printf '%s\n' "$rows" | while IFS="$TAB" read -r h c b; do [ -n "$h" ] && printf '    %s  (%s req, %s)\n' "$h" "$c" "$(_human_bytes "$b")"; done
    echo "[sluice] non-interactive: 'sluice learn --apply' to allow all, or '--print' to emit the list."
    return 0
  fi
  echo "[sluice] $label - allow which? ('s' leaves a host blocked)"; echo
  local hosts; hosts="$(printf '%s\n' "$rows" | cut -d"$TAB" -f1 | sed '/^$/d')"
  local -a selected=() handled=()
  # Wildcard offers: parents with >=2 blocked subdomains.
  local parents p subs ya; parents="$(printf '%s\n' "$hosts" | while read -r h; do [ -n "$h" ] && parent_of "$h"; done | sort | uniq -c | awk '$1>=2{print $2}')"
  for p in $parents; do
    _collapsible "$p" || continue   # never offer a wildcard equal to a public suffix (foo.github.io -> .github.io)
    subs="$(printf '%s\n' "$hosts" | while read -r h; do [ "$(parent_of "$h")" = "$p" ] && echo "$h"; done)"
    # shellcheck disable=SC2086
    printf '  %s subdomains of %s: %s\n' "$(printf '%s\n' "$subs" | awk 'END{print NR}')" "$p" "$(printf '%s ' $subs)"
    printf '  collapse to .%s (matches all its subdomains)? [y/N] ' "$p"
    read -r ya </dev/tty || ya=""
    # shellcheck disable=SC2206
    case "$ya" in y|Y|yes|YES) selected+=(".$p"); handled+=($subs); echo ;; *) echo ;; esac
  done
  # Per-host loop for anything not covered by an accepted wildcard.
  local h c b ans pd
  while IFS="$TAB" read -r h c b; do
    [ -n "$h" ] || continue
    case " ${handled[*]:-} " in *" $h "*) continue ;; esac
    printf '  %-28s %3s req %9s   [a]llow / [s]kip / [d]omain(.%s) / [q]uit? ' "$h" "$c" "$(_human_bytes "$b")" "$(parent_of "$h")"
    read -r ans </dev/tty || ans=""
    case "$ans" in
      a|A|y|Y) selected+=("$h") ;;
      d|D)     pd="$(parent_of "$h")"; if _collapsible "$pd"; then selected+=(".$pd"); else selected+=("$h"); fi ;;
      q|Q)     break ;;
      *)       ;;
    esac
  done <<EOF
$rows
EOF
  echo
  if [ "${#selected[@]}" -eq 0 ]; then
    echo "[sluice] ${C_DIM}nothing added - all hosts left blocked.${C_RST}"
    return 0
  fi
  learn_apply "$(printf '%s\n' "${selected[@]}")"
}

# `sluice learn [--all] [--print | --apply]`: review the hosts squid BLOCKED and allowlist the ones
# you choose. Scoped to the last run by default (--all = since boot). The example.* canary + raw IPs are
# already dropped by egress_rows. --print emits the merged list (CI); --apply allows all (no prompts).
cmd_learn() {
  local scope=run mode=interactive a
  for a in "$@"; do
    case "$a" in
      --all)   scope=all ;;
      --print) mode=print ;;
      --apply) mode=apply ;;
      *) die "usage: sluice learn [--all] [--print | --apply | --audit]" ;;
    esac
  done
  running || die "no running sandbox. Start your app ('sluice'), exercise it so it makes its network calls, then run 'sluice learn'."
  [ "$scope" = all ] || _RCPT_OFFSET="$(last_run_offset)"

  local TAB; TAB="$(printf '\t')"
  local rows; rows="$(egress_rows 2>/dev/null | awk -F"$TAB" '$1=="blocked"{print $2 FS $3 FS $4}' | sort -t"$TAB" -k3,3nr -k1,1 || true)"
  local label; [ "$scope" = all ] && label="blocked since the box booted" || label="blocked during the last run"

  # Empty rows mean "nothing blocked" OR a FAILED in-box read (pids cgroup exhausted so the audit
  # exec couldn't fork). Fail closed rather than present an unread log as a clean all-clear.
  if [ -z "$rows" ] && ! _audit_readable; then
    echo "[sluice] ${C_YEL:-}egress audit unavailable${C_RST} - could not read the in-box log (pids limit?); failing closed." >&2
    return 2
  fi

  if [ -z "$rows" ]; then
    echo "[sluice] ${C_GRN}nothing $label - every host your app reached is already allowed.${C_RST}"
    [ "$scope" = run ] && echo "[sluice] (try 'sluice learn --all' for everything since boot.)"
    return 0
  fi

  local hosts; hosts="$(printf '%s\n' "$rows" | cut -d"$TAB" -f1 | sed '/^$/d')"
  [ "$mode" = print ] && { printf '%s\n' "$(merge_allow "$hosts")"; return 0; }
  [ "$mode" = apply ] && { learn_apply "$hosts"; return 0; }
  _learn_review "$rows" "$label"
}

# `sluice learn --audit`: one-shot OPEN-egress discovery (the warned escape hatch). Runs SLUICE_RUN_CMD
# once in an ephemeral, credential-stripped container with egress opened to ALL HTTP/HTTPS hosts
# (non-HTTP + IPv6 stay blocked), then proposes the allowlist from every host it reached - for trusted
# code whose fetcher aborts on the first block. No creds forwarded, nothing to exfiltrate.
cmd_learn_audit() {
  cat >&2 <<EOF
[sluice] ${E_YEL}WARNING:${E_RST} 'learn --audit' opens egress to ALL HTTP/HTTPS hosts for one run.
         It runs SLUICE_RUN_CMD with NO forwarded credentials (SLUICE_ENV, prelaunch, and
         persisted auth are stripped) in a throwaway container, then tears it down - but while
         it runs, this project's code can reach any host. Use it only on code you trust.
EOF
  if [ -t 0 ] && [ -t 1 ]; then
    printf '[sluice] open egress and run SLUICE_RUN_CMD once to discover reached hosts? [y/N] '
    local a; read -r a 2>/dev/null || a=""
    case "$a" in y|Y|yes|YES) ;; *) echo "[sluice] ${C_DIM}aborted - egress not opened.${C_RST}"; return 0 ;; esac
  elif [ "${SLUICE_YES:-}" != 1 ]; then
    echo "[sluice] non-interactive: re-run with SLUICE_YES=1 to confirm opening egress for the audit pass."
    return 0
  fi

  maybe_build
  local audit_container="$container-audit"
  "$RUNNER" rm -f "$audit_container" >/dev/null 2>&1 || true
  # Bake the names into the trap now (the local is gone by the time EXIT fires) so the ephemeral
  # container is always torn down - normal exit, die, or Ctrl-C. It never leaves audit mode.
  # shellcheck disable=SC2064  # expand $audit_container/$RUNNER NOW: the local is gone when the trap fires
  trap "'$RUNNER' rm -f '$audit_container' >/dev/null 2>&1 || true" EXIT

  # Credential-stripped run args: project mount + git common dir + the proxy sysctls + SLUICE_AUDIT.
  # Deliberately NO prelaunch, state-dir mounts, SLUICE_ENV, or published ports (see start()).
  local run_args=(--cap-drop ALL
    --cap-add CHOWN --cap-add DAC_OVERRIDE --cap-add FOWNER --cap-add SETUID --cap-add SETGID
    --cap-add NET_ADMIN --cap-add NET_RAW --cap-add NET_BIND_SERVICE --cap-add KILL
    --security-opt no-new-privileges
    --pids-limit "${SLUICE_PIDS_LIMIT:-4096}"
    --sysctl net.ipv4.conf.all.route_localnet=1
    --sysctl net.ipv6.conf.all.disable_ipv6=1
    --sysctl net.ipv6.conf.default.disable_ipv6=1
    -e SLUICE_AUDIT=1
    -v "$PROJECT_DIR":"$PROJECT_DIR" -e "SLUICE_WORKDIR=$PROJECT_DIR")
  [ -n "${SLUICE_MEMORY:-}" ] && run_args+=(--memory "$SLUICE_MEMORY")
  selinux_enforcing && run_args+=(--security-opt label=disable)   # see the main run path
  # Validated worktree common-dir mount (see _validated_git_common_dir): refuse a box-rewritten .git
  # that would redirect us into an arbitrary repo. Skipped under overlay, matching the main run path.
  if [ "${SLUICE_WORKSPACE:-}" != overlay ]; then
    local common; common="$(_validated_git_common_dir)"
    [ -n "$common" ] && run_args+=(-v "$common":"$common" -e "SLUICE_GITDIR=$common")
  fi

  # Egress is OPEN for this run - keep SLUICE_MASK shadowing in force so in-repo secrets stay unreadable.
  mask_build_args
  if [ "${#MASK_ARGS[@]}" -gt 0 ]; then
    run_args+=("${MASK_ARGS[@]}")
    _nmask="$(printf '%s' "$MASKED_PATHS" | wc -w | tr -d ' ')"
    echo "[sluice] masking $_nmask in-repo path(s) (unreadable in the box) - see 'sluice doctor'" >&2
  fi

  echo "[sluice] starting ephemeral audit container $audit_container ..."
  runtime_sync_image
  runtime_run --name "$audit_container" "${run_args[@]}" "$tag" >/dev/null
  local up="" tries=60; [ "$RUNNER" != "$ENGINE" ] && tries=120
  for _ in $(seq 1 "$tries"); do
    "$RUNNER" logs "$audit_container" 2>&1 | grep -q "\[sluice\] ready" && { up=1; break; }
    sleep 0.5
  done
  [ -n "$up" ] || die "audit container failed to come up - see: $RUNNER logs $audit_container"

  # Run the command with NO credential forwarding (no -e for SLUICE_ENV vars).
  local exec_args=(-i --user sluice -w "$PROJECT_DIR")
  [ -t 0 ] && [ -t 1 ] && exec_args+=(-t)
  echo "[sluice] running SLUICE_RUN_CMD with egress open (discovering reached hosts)..."
  "$RUNNER" exec "${exec_args[@]}" "$audit_container" sh -lc "${SLUICE_RUN_CMD:-true}" || true

  # Review the hosts it reached (egress was open), minus base/allowlist + the example.* canary, with
  # per-host selection - then persist + hot-reload onto the real (enforcing) box.
  local TAB; TAB="$(printf '\t')"
  local rows; rows="$(egress_rows "$audit_container" 2>/dev/null \
    | awk -F"$TAB" -v allow=" $(allowed_domains) " '
        function allowed(h,   n,i,t,tl,toks){ if(index(allow," "h" "))return 1; n=split(allow,toks," "); for(i=1;i<=n;i++){t=toks[i]; if(substr(t,1,1)=="."){tl=length(t); if(h==substr(t,2)||(length(h)>tl&&substr(h,length(h)-tl+1)==t))return 1}} return 0 }
        $1=="reached" && !allowed($2){print $2 FS $3 FS $4}' \
    | sort -t"$TAB" -k3,3nr -k1,1 || true)"
  echo
  if [ -z "$rows" ]; then
    echo "[sluice] ${C_GRN}the audit run reached no new hosts beyond the base/allowlist - nothing to add.${C_RST}"
    return 0
  fi
  _learn_review "$rows" "reached during the audit run (egress was open)"
}

case "${1:-run-default}" in
  build)   build; exit 0 ;;
  diff)    cmd_workspace_diff; exit $? ;;
  apply)   cmd_workspace_apply; exit $? ;;
  rebuild) build; start; exit 0 ;;
  stop)    "$RUNNER" rm -f -v "$container" >/dev/null 2>&1 || true; echo "[sluice] $container removed (image kept - 'sluice' recreates it)"; exit 0 ;;
  rm)
    "$RUNNER" rm -f -v "$container" >/dev/null 2>&1 || true; "$ENGINE" rmi -f "$tag" >/dev/null 2>&1 || true
    _nov="$(remove_box_volumes "$container")"   # SLUICE_OVERLAY_DIRS volumes ride the box's lifecycle
    _ovmsg=""; [ "${_nov:-0}" -gt 0 ] && _ovmsg=" + $_nov overlay volume(s) (box-only contents, e.g. a built node_modules, are gone)"
    echo "[sluice] removed $container (container + image$_ovmsg)"
    # Persisted state dirs (agent sessions/auth) live in a host store and SURVIVE rm by default.
    # SLUICE_RM_PURGE_STATE=1 also deletes them (best-effort: box-chowned files may resist on Linux).
    _store="${XDG_STATE_HOME:-$HOME/.local/state}/sluice/$slug"
    if [ -n "${SLUICE_STATE_DIRS:-}" ] && [ -d "$_store" ]; then
      if [ "${SLUICE_RM_PURGE_STATE:-}" = 1 ]; then
        rm -rf "$_store" 2>/dev/null || true
        [ -d "$_store" ] && echo "[sluice] ${E_YEL}note${E_RST}: could not fully remove $(_tilde "$_store") (box-owned files) - remove it manually" >&2 \
                         || echo "[sluice] purged persisted state at $(_tilde "$_store")"
      else
        echo "${E_DIM}[sluice]${E_RST} kept persisted session state at $(_tilde "$_store") - SLUICE_RM_PURGE_STATE=1 to remove" >&2
      fi
    fi
    exit 0 ;;
  logs)    "$RUNNER" logs -f "$container" ;;
  smoke)
    maybe_build
    "$ENGINE" run --rm --user sluice --entrypoint bash "$tag" /usr/local/bin/smoke-test.sh
    exit $?
    ;;
  learn)
    shift
    for _a in "$@"; do [ "$_a" = --audit ] && { cmd_learn_audit; exit $?; }; done
    cmd_learn "$@"; exit $?
    ;;
  egress)
    shift
    case "${1:-}" in
      ""|--json) cmd_egress "${1:-}"; exit $? ;;
      --export)  cmd_egress_export; exit $? ;;
      --verify)  cmd_egress_verify "${2:-}"; exit $? ;;   # accepts a trailing --json (one verify object)
      *)         die "usage: sluice egress [--json | --export [--all] | --verify [--all] [--json]]" ;;   # --all is dispatched earlier (src/60), before config/engine
    esac
    ;;
  lock)
    shift
    case "${1:-}" in
      --check)   shift; cmd_lock_check   "$@"; exit $? ;;
      --diff)    shift; cmd_lock_diff    "$@"; exit $? ;;
      --enforce) shift; cmd_lock_enforce "$@"; exit $? ;;
      --sbom)    shift; cmd_sbom "$@"; exit $? ;;
      --scan)    shift; cmd_scan "$@"; exit $? ;;
      --pin)     shift; [ "$#" -eq 0 ] || die "usage: sluice lock --pin"; write_pin; exit 0 ;;
      "")        write_lock; exit 0 ;;
      *)         die "usage: sluice lock [--check [--json] | --diff [--json] | --enforce [--json] | --sbom [--format cyclonedx|spdx] | --scan [--json] [--fail-on <sev>] | --pin]" ;;
    esac
    ;;
  update)
    # Re-resolve packages to latest. _SLUICE_PIN_SKIP=1 (transient, function-scoped) skips pin mode for
    # THIS build so it re-resolves fresh instead of replaying the old pin, then refresh both artifacts.
    _SLUICE_PIN_SKIP=1 build --no-cache
    write_lock
    if [ "${SLUICE_PIN:-}" = 1 ]; then
      # A pinning project: re-pin to the fresh versions, then one more PINNED build (cache-warm, replay
      # legs no-op) so `update` ends with a verified pinned image (else 'lock --enforce' would fail after
      # a sanctioned update).
      write_pin
      build
      echo "${E_DIM}[sluice]${E_RST} re-resolved and re-pinned - the box is down; run 'sluice' to start it." >&2
    else
      echo "${E_DIM}[sluice]${E_RST} updated - the box is down; run 'sluice' to start it (or 'sluice rebuild' to rebuild + start)." >&2
    fi
    exit 0 ;;
  shell)
    # run_in (not exec_in) so the EXIT trap fires the receipt after the interactive session - the
    # "every run ends with a receipt" promise holds for `shell` too, not just run-default.
    banner; ensure_up; arm_receipt
    _rc=0; run_in bash || _rc=$?
    exit "$_rc"
    ;;
  run)
    shift
    [ "$#" -gt 0 ] || die "usage: sluice run <cmd...>"
    ensure_up; arm_receipt
    _rc=0; run_in "$@" || _rc=$?
    exit "$_rc"
    ;;
  run-default)
    banner
    # F2: snapshot image freshness BEFORE ensure_up may rebuild, so the plan line can say up-to-date vs rebuilt.
    _fresh=1
    [ "$("$ENGINE" image inspect -f '{{ index .Config.Labels "sluice.confighash" }}' "$tag" 2>/dev/null || true)" = "$(config_hash)" ] || _fresh=""
    ensure_up
    _nhosts="$(allowed_domains | wc -w | tr -d ' ')"
    _state="up-to-date"; [ -n "$_fresh" ] || _state="rebuilt"
    # (auth-unset warning already emitted once by warn_auth_unset above; state-aware, no duplicate here)
    # Snapshot the proxy log position so the receipt reports THIS run's egress, not the box's whole
    # boot. Then run SLUICE_RUN_CMD; the EXIT trap prints the receipt (reached + blocked). run_in
    # (not exec_in) so the trap fires after the session, even on Ctrl-C - which is why we capture and
    # re-propagate the command's status ourselves (the trailing hints would otherwise leave $? = 0).
    arm_receipt   # scope the receipt to this run, mark the start for `learn`, trap it on EXIT
    # F2: one-line plan so the implicit build/run is legible (the no-op case speaks via the status below).
    case "${SLUICE_RUN_CMD:-}" in
      true|:|/bin/true) ;;
      *)
        # A multi-line run_cmd would dump its whole body here, doubling the output; summarize it.
        _runlbl="${SLUICE_RUN_CMD:-bash}"; _runln="$(printf '%s\n' "$_runlbl" | grep -c .)"
        if [ "${_runln:-1}" -gt 1 ]; then _runlbl="a ${_runln}-line command"; fi
        echo "${E_DIM}[sluice]${E_RST} box ${_state} (${_nhosts} allowed hosts) - running: ${_runlbl}" >&2 ;;
    esac
    _rc=0
    if [ "${#AGENT_EXTRA_ARGS[@]}" -gt 0 ]; then
      # one-shot agent run: forward trailing args as positional params (no re-quoting needed)
      run_in sh -lc "${SLUICE_RUN_CMD:-bash} \"\$@\"" sh "${AGENT_EXTRA_ARGS[@]}" || _rc=$?
    else
      run_in sh -lc "${SLUICE_RUN_CMD:-bash}" || _rc=$?
    fi
    # F4: a no-op run-cmd (e.g. the lock demo's `true`) would dead-end on a one-line hint; show a
    # compact doctor-lite status instead (box up, image state, allowed-host count) + what to run.
    case "${SLUICE_RUN_CMD:-}" in
      true|:|/bin/true)
        _shell_hint="sluice shell"; [ -n "$SLUICE_BOX_TARGET" ] && _shell_hint="sluice -b $SLUICE_BOX_SLUG shell"
        echo "${E_DIM}[sluice]${E_RST} box ${container} is up (image ${_state}; ${_nhosts} allowed hosts); SLUICE_RUN_CMD='${SLUICE_RUN_CMD}' is a no-op - nothing to run." >&2
        echo "         try '$_shell_hint', 'sluice doctor', or a subcommand (e.g. sluice lock)." >&2 ;;
    esac
    # overlay workspace: nudge with the changeset; the host repo is untouched until `sluice apply`.
    if workspace_is_overlay; then
      _wsa=""; read -r _wsa _wsm _wsd <<EOF
$(workspace_counts)
EOF
      [ "$(( ${_wsa:-0} + ${_wsm:-0} + ${_wsd:-0} ))" -gt 0 ] && \
        echo "${E_DIM}[sluice]${E_RST} workspace: ${_wsa} added, ${_wsm} modified, ${_wsd} deleted (host repo untouched) - review: sluice diff | write back: sluice apply" >&2
    fi
    # F3: complete the onboarding arc on the very first run (config was just scaffolded this invocation).
    [ -n "${_SCAFFOLDED:-}" ] && echo "${E_DIM}[sluice]${E_RST} first run done - next: 'sluice learn' (lock egress to what it needed), 'sluice lock' (pin the supply chain)." >&2
    # F1: propagate SLUICE_RUN_CMD's status. The EXIT trap doesn't call exit, so bash exits with this
    # code; without it the trailing hints/nudges leave $? = 0 (a false green in CI / `sluice && ...`).
    exit "$_rc"
    ;;
  *) die "unknown command: $1 - run 'sluice help' for usage." ;;
esac