merge: origin/main into fix/1019-queue-guard-stdin (union on test:framework-shell)

Both sides edited the single `test:framework-shell` line additively and did not
overlap: main prepended the test-enumeration guard pair
(check-test-enumeration.sh, test-check-test-enumeration.sh); this branch inserted
test-ci-queue-wait-parse.sh after test-ci-queue-wait-branch-absent.sh.

Resolved as the union — main's line with this branch's one insertion restored.
Main's new guard makes that insertion mandatory rather than cosmetic: the test
file ships in this branch, so leaving it unenumerated would fail the guard.

Co-authored-by: mos-dt-0 <[email protected]>

.woodpecker/ci.yml

@@ -41,6 +41,11 @@ steps:
       # (Constitution + dispatcher + each RUNTIME.md slice). See DESIGN §7 / R9.
       - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh --self-test
       - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh
+      # Test-membership guard (#1017): also first link of test:framework-shell.
+      # Invoked from BOTH surfaces it audits (F2, PR #1018) — the guard is link
+      # [0] of the pnpm chain, so severing that chain would silence it together
+      # with everything it guards; this direct line keeps one instrument running.
+      - bash packages/mosaic/framework/tools/quality/scripts/check-test-enumeration.sh
 
   # Blocking gate (#791): a framework upgrade must never write or delete an
   # operator-owned path. The HARD GATE proves an unanticipated operator sentinel

packages/mosaic/framework/tools/git/ci-queue-wait.sh

@@ -34,12 +34,18 @@ EOF
 # get_remote_host and get_gitea_token are provided by detect-platform.sh
 
 get_state_from_status_json() {
-    python3 - <<'PY'
+    # Capture piped JSON BEFORE invoking `python3 - <<PY`. The heredoc binds
+    # stdin to the Python program text — so json.load(sys.stdin) inside would
+    # try to re-read stdin after `-` already consumed it for the program,
+    # yielding EOF and returning "unknown" every time. Pass payload via env.
+    local payload
+    payload=$(cat)
+    CI_QUEUE_STATUS_JSON="$payload" python3 - <<'PY'
 import json
-import sys
+import os
 
 try:
-    payload = json.load(sys.stdin)
+    payload = json.loads(os.environ.get("CI_QUEUE_STATUS_JSON", ""))
 except Exception:
     print("unknown")
     raise SystemExit(0)
@@ -83,12 +89,15 @@ PY
 }
 
 print_pending_contexts() {
-    python3 - <<'PY'
+    # Same stdin hazard as get_state_from_status_json above — pass payload via env.
+    local payload
+    payload=$(cat)
+    CI_QUEUE_STATUS_JSON="$payload" python3 - <<'PY'
 import json
-import sys
+import os
 
 try:
-    payload = json.load(sys.stdin)
+    payload = json.loads(os.environ.get("CI_QUEUE_STATUS_JSON", ""))
 except Exception:
     print("[ci-queue-wait] unable to decode status payload")
     raise SystemExit(0)

packages/mosaic/framework/tools/git/mutate-push-guard.sh

@@ -0,0 +1,241 @@
+#!/usr/bin/env bash
+# mutate-push-guard.sh -- regenerate the README's mutation table from MEASUREMENT.
+#
+# WHY THIS EXISTS. The README carried a hand-written mutation table quoting
+# "32/32" style results. Those numbers were true when typed and went stale in
+# silence as the suite grew. A README is what a reader trusts when the tool
+# misbehaves, so a confidently-wrong one is worse than none. Every number the
+# README prints about mutation now comes out of this script.
+#
+# ============================ WHAT THIS TOOL GOT WRONG ========================
+# Three defects, all found by review, all of the same shape: A TOOL WHOSE ENTIRE
+# OUTPUT IS A COVERAGE CLAIM MUST BE HARDER TO FOOL THAN THE CODE IT MEASURES.
+#
+#  1. IT REPORTED FULL COVERAGE ON A RED BASELINE. A mutant was "killed" whenever
+#     the suite reported any failure at all, and the baseline was run only at the
+#     END and never required to be green. So ONE pre-existing suite failure --
+#     changing no guard behaviour whatsoever -- satisfied EVERY mutant: 13 killed,
+#     0 survived, a confident table generated and pasted into the README, exit 0.
+#     Now: the baseline runs FIRST and must be exit-0 with zero failures, and a
+#     kill requires the mutant to break a case THE BASELINE PASSED, recorded BY
+#     NAME. A tally is not evidence; a named delta is.
+#
+#  2. IT MUTATED THE REVIEWED SOURCE IN PLACE. Restoration leaned on an EXIT trap.
+#     A TRAP IS CLEANUP, NOT ISOLATION -- SIGKILL cannot run it. An interrupted run
+#     left push-guard.sh mutated in the working tree, and the reviewer's NEXT
+#     suite run silently inherited it. A verification tool that alters its subject
+#     can leave the subject wrong in a way the next measurement believes.
+#     Now: the subject is copied into a temp dir and only the COPY is ever
+#     written to. The source is untouched BY CONSTRUCTION rather than by cleanup,
+#     which is the only version of this that survives kill -9.
+#
+#  3. ITS WORK DIR WAS SHARED. Concurrent runs interfered through the suite's
+#     default .work directory. Each run now gets its own.
+#
+# (Note the deliberate asymmetry with verify-clean-clone.sh, which forbids cp:
+# there the copy LAUNDERED the property under measurement, so measuring a copy
+# was the defect. Here mutation is destructive by design, so copying is what
+# PROTECTS the subject. The rule is not "never copy" -- it is "know whether the
+# copy preserves the property you are about to measure.")
+#
+# ================== THREE WAYS A MUTATION RUN LIES, AND THE GUARD FOR EACH ====
+#  A. THE ANCHOR NO LONGER MATCHES. The mutant is never applied, the suite is
+#     green, and the report says SURVIVED -- the same word a real coverage gap
+#     gets. Guarded: ANCHOR MISSING is a loud failure.
+#  B. THE ANCHOR MATCHES PROSE. This one landed on the first run: a mutant aimed
+#     at a branch matched inside the usage() heredoc, edited a help string,
+#     changed no behaviour, and duly reported SURVIVED. A documentation edit was
+#     one step from being recorded as an uncovered branch. A MUTATION THAT CANNOT
+#     CHANGE BEHAVIOUR IS NOT A SURVIVING MUTANT, IT IS A NON-MEASUREMENT.
+#     Guarded: anchors resolving inside usage() are refused.
+#  C. THE ANCHOR IS AMBIGUOUS. Two unrelated branches here are both the line
+#     `if (( status != 0 )); then`; a first-match replace would credit the kill
+#     to the wrong branch. Guarded: a match count != 1 refuses rather than guesses.
+set -uo pipefail
+
+SRC_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+while (( $# )); do
+    case "$1" in
+        # --dir exists so this tool can be pointed at a FIXTURE copy and tested.
+        --dir) SRC_DIR="$(cd "$2" && pwd)"; shift 2 ;;
+        *) printf 'usage error: unknown argument: %s\n' "$1" >&2; exit 64 ;;
+    esac
+done
+
+SRC_TARGET="$SRC_DIR/push-guard.sh"
+SRC_SUITE="$SRC_DIR/test-push-guard.sh"
+for f in "$SRC_TARGET" "$SRC_SUITE"; do
+    [[ -r "$f" ]] || { printf 'REFUSING: cannot read %s\n' "$f" >&2; exit 1; }
+done
+
+# --- ISOLATION, NOT CLEANUP --------------------------------------------------
+# Everything below writes only inside WORK. The trap is a courtesy for disk
+# space; correctness does not depend on it running.
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+install -m 755 "$SRC_TARGET" "$WORK/push-guard.sh"
+install -m 755 "$SRC_SUITE"  "$WORK/test-push-guard.sh"
+TARGET="$WORK/push-guard.sh"
+SUITE="$WORK/test-push-guard.sh"
+BAK="$WORK/push-guard.sh.orig"
+cp "$TARGET" "$BAK"
+# Per-run work dir: the suite otherwise defaults to a shared .work beside itself,
+# and two concurrent runs corrupt each other's fixtures.
+export MOSAIC_TEST_WORK_DIR="$WORK/.work"
+
+# --- where the prose lives: usage() { ... EOF ---------------------------------
+PROSE_LO="$(grep -n '^usage() {' "$BAK" | head -1 | cut -d: -f1)"
+PROSE_HI="$(awk -v lo="$PROSE_LO" 'NR > lo && /^EOF$/ { print NR; exit }' "$BAK")"
+if [[ -z "$PROSE_LO" || -z "$PROSE_HI" ]]; then
+    echo "!! cannot locate the usage() heredoc -- the prose guard would be inert; refusing" >&2
+    exit 1
+fi
+
+# passing_cases <output>  -- names of cases that PASSED, one per line
+passing_cases() { printf '%s\n' "$1" | sed -n 's/^  PASS  \[[^]]*\] \(.*\) (exit [0-9]*)$/\1/p'; }
+tally()         { printf '%s\n' "$1" | grep -E 'needles: [0-9]+ passed' | tail -1; }
+
+# --- THE BASELINE MUST BE GREEN, AND IT IS ESTABLISHED FIRST ------------------
+printf '=== baseline (must be exit 0 with zero failures) ===\n'
+BASE_OUT="$("$SUITE" 2>&1)"; BASE_RC=$?
+BASE_LINE="$(tally "$BASE_OUT")"
+BASE_FAILED="$(printf '%s\n' "$BASE_LINE" | sed -n 's/.*, \([0-9]*\) failed.*/\1/p')"
+if (( BASE_RC != 0 )) || [[ -z "$BASE_LINE" || "$BASE_FAILED" != "0" ]]; then
+    printf 'REFUSING: baseline is not green -- exit %s, tally: %s\n' \
+        "$BASE_RC" "${BASE_LINE:-<no tally emitted>}" >&2
+    printf '\nEvery mutant would be scored KILLED by the pre-existing failure, and this\n' >&2
+    printf 'tool would publish a confident coverage table that measured nothing. Fix the\n' >&2
+    printf 'suite first. NO TABLE IS EMITTED.\n' >&2
+    exit 1
+fi
+printf '  %s\n' "$BASE_LINE"
+mapfile -t BASE_PASSING < <(passing_cases "$BASE_OUT")
+printf '  %d named cases passing at baseline\n' "${#BASE_PASSING[@]}"
+if (( ${#BASE_PASSING[@]} == 0 )); then
+    printf 'REFUSING: could not parse any case names -- kills could not be attributed.\n' >&2
+    exit 1
+fi
+printf '  prose (usage heredoc) is lines %s-%s -- anchors there are refused, not scored\n\n' \
+    "$PROSE_LO" "$PROSE_HI"
+
+rc_all=0
+KILLED=0; SURVIVED=0
+declare -a ROWS=()
+
+mutate() {
+    local name="$1" find="$2" repl="$3"
+    # Count and locate in python so MULTI-LINE anchors work. They are required:
+    # two unrelated branches in this file are both the single line
+    # `if (( status != 0 )); then`, and a one-line anchor cannot say which one a
+    # result belongs to. Guessing would attribute a kill to the wrong branch.
+    local loc; loc="$(python3 - "$BAK" "$find" <<'LOCPY'
+import sys
+s = open(sys.argv[1]).read(); find = sys.argv[2]
+n = s.count(find)
+print(n, (s[:s.index(find)].count("\n") + 1) if n else 0)
+LOCPY
+)"
+    local n="${loc%% *}" ln="${loc##* }"
+    if (( n == 0 )); then
+        printf '  !! ANCHOR MISSING   %-46s NOT APPLIED -- result would be meaningless\n' "$name"
+        rc_all=1; return
+    fi
+    if (( n != 1 )); then
+        printf '  !! ANCHOR AMBIGUOUS %-46s %d matches -- refusing to guess which branch\n' "$name" "$n"
+        rc_all=1; return
+    fi
+    if (( ln >= PROSE_LO && ln <= PROSE_HI )); then
+        printf '  !! ANCHOR IS PROSE  %-46s line %d is inside usage() -- not a branch\n' "$name" "$ln"
+        rc_all=1; return
+    fi
+
+    python3 - "$BAK" "$TARGET" "$find" "$repl" <<'MUTPY'
+import sys
+src, dst, find, repl = sys.argv[1:5]
+open(dst, "w").write(open(src).read().replace(find, repl, 1))
+MUTPY
+    local out; out="$("$SUITE" 2>&1)"
+    cp "$BAK" "$TARGET"
+
+    local line; line="$(tally "$out")"
+    if [[ -z "$line" ]]; then
+        printf '  !! NO TALLY        %-46s suite produced no needle count\n' "$name"
+        rc_all=1; return
+    fi
+    # A KILL IS A NAMED DELTA, NOT A TALLY. Cases that passed at baseline and no
+    # longer pass are the evidence; anything else (a case that was already
+    # failing, a suite that died early) cannot be credited to this mutant.
+    local now; now="$(passing_cases "$out")"
+    local -a broke=()
+    local c
+    for c in "${BASE_PASSING[@]}"; do
+        grep -qxF -- "$c" <<<"$now" || broke+=("$c")
+    done
+    local total="${#BASE_PASSING[@]}"
+
+    if (( ${#broke[@]} > 0 )); then
+        printf '  KILLED   L%-5s %-46s %d/%d fail\n' "$ln" "$name" "${#broke[@]}" "$total"
+        printf '             by: %s\n' "${broke[0]}"
+        (( ${#broke[@]} > 1 )) && printf '             +%d more\n' "$(( ${#broke[@]} - 1 ))"
+        ROWS+=("| \`$name\` (L$ln) | ${#broke[@]}/$total fail | killed |")
+        KILLED=$(( KILLED + 1 ))
+    else
+        printf '  SURVIVED L%-5s %-46s 0/%d fail  <-- UNCOVERED BRANCH\n' "$ln" "$name" "$total"
+        ROWS+=("| \`$name\` (L$ln) | 0/$total fail | **SURVIVED** |")
+        SURVIVED=$(( SURVIVED + 1 )); rc_all=1
+    fi
+}
+
+echo "=== push-guard mutation run ==="
+# EVERY ANCHOR BELOW IS VERBATIM SOURCE TEXT OF THE GUARD, so the single quotes
+# are load-bearing: these strings must reach `mutate` as the CHARACTERS that
+# appear in push-guard.sh. Expanding them would search for THIS shell's (unset)
+# $rel, $cmode, $EX_CONFIG and match nothing -- which the anchor guards would
+# report as ANCHOR MISSING rather than silently, but the intent is still to
+# forbid expansion. The directive is scoped to this function so it cannot mask a
+# genuine unintended-literal anywhere else in the file.
+# shellcheck disable=SC2016
+run_mutants() {
+    mutate "json decision requirement bypassed" \
+        '    if (( ${#JSON_PATHS[@]} == 0 )); then' '    if false; then'
+    mutate "opt-out accepted with no written reason" \
+        'if not isinstance(reason, str) or not reason.strip():' 'if False:'
+    mutate "committed re-read of the opt-out skipped" \
+        '    [[ "$CFG_MODE" == "none" ]] || return 0' '    return 0'
+    mutate "untracked config honoured as an opt-out" \
+        '    if [[ -z "$rel" ]]; then' '    if false; then'
+    mutate "staged-but-uncommitted opt-out honoured" \
+        '    if [[ -z "$cmode" ]]; then' '    if false; then'
+    mutate "committed SYMLINK config honoured" \
+        '    if [[ "$cmode" == "120000" ]]; then' '    if false; then'
+    mutate "unparseable committed config ignored" \
+        '    if (( cstatus != 0 )); then' '    if false; then'
+    mutate "local-only opt-out (HEAD says ON) honoured" \
+        '    if [[ "$cmode_val" != "none" ]]; then' '    if false; then'
+    mutate "empty MERGE exempted" \
+        '        if [[ "$all_same" == yes ]]; then' '        if false; then'
+    mutate "empty ROOT exempted" \
+        'if [[ -z "$(git diff-tree --root -r --name-only --no-commit-id HEAD)" ]]; then' \
+        'if false; then'
+    mutate "--since-head ancestry check removed" \
+        'if ! git merge-base --is-ancestor "$since_head" "$head"; then' 'if false; then'
+    # guard's own source text, matched verbatim. Expanding them here would search for
+    # this shell's (empty) $EX_CONFIG instead of the characters in the file.
+    mutate "staged-file enumeration ignores git failure" \
+        "$(printf 'if (( status != 0 )); then\n        local msg')" \
+        "$(printf 'if false; then\n        local msg')"
+    mutate "malformed config degrades to absent instead of refusing" \
+        "$(printf 'if (( status != 0 )); then\n        fail "$EX_CONFIG"')" \
+        "$(printf 'if false; then\n        fail "$EX_CONFIG"')"
+}
+
+run_mutants
+
+printf '\nbaseline: %s\n' "$BASE_LINE"
+printf '%d killed, %d survived\n' "$KILLED" "$SURVIVED"
+
+printf '\n--- README TABLE (paste verbatim) ---\n'
+printf '| mutation | suite result | verdict |\n|---|---|---|\n'
+printf '| *unmodified* | %s | baseline |\n' "$(printf '%s' "$BASE_LINE" | sed 's/push-guard needles: //')"
+printf '%s\n' "${ROWS[@]}"
+exit "$rc_all"

packages/mosaic/framework/tools/git/pr-review.sh

@@ -109,6 +109,55 @@ else
     detect_platform >/dev/null
 fi
 
+# Render the provider's own explanation for a failed request, for appending to
+# an error message (#1004). Every HTTP arm in this file already has the response
+# body on disk; without this it was discarded unread at exactly the moment the
+# caller needed it, which pushes an operator toward re-issuing the request by
+# hand to find out what the server said. Gitea returns {"message": "..."} on a
+# refusal; anything unparseable falls back to a truncated raw first line so a
+# proxy's HTML error page still says something. Prints "" when there is nothing
+# to add, so callers can interpolate unconditionally.
+#
+# Args: $1 = path to the response body file.
+gitea_error_detail() {
+    local body_file="$1"
+    [[ -s "$body_file" ]] || return 0
+    python3 - "$body_file" <<'PY' 2>/dev/null || true
+import json
+import sys
+
+LIMIT = 300
+try:
+    with open(sys.argv[1], encoding="utf-8", errors="replace") as response:
+        raw = response.read().strip()
+except OSError:
+    raise SystemExit(0)
+if not raw:
+    raise SystemExit(0)
+detail = ""
+try:
+    parsed = json.loads(raw)
+    if isinstance(parsed, dict):
+        for key in ("message", "error", "errors"):
+            value = parsed.get(key)
+            if isinstance(value, str) and value.strip():
+                detail = value.strip()
+                break
+            if isinstance(value, list) and value:
+                detail = "; ".join(str(item) for item in value).strip()
+                break
+except ValueError:
+    pass
+if not detail:
+    detail = raw.splitlines()[0].strip()
+if not detail:
+    raise SystemExit(0)
+if len(detail) > LIMIT:
+    detail = detail[:LIMIT] + "..."
+print(f" — provider said: {detail}")
+PY
+}
+
 # Post a comment to a Gitea PR (PR comments ARE issue comments) via the
 # supported REST API and verify it against a PROVIDER-RETURNED created id. The
 # write is a direct POST that returns the created comment object, so we learn
@@ -150,7 +199,7 @@ print(json.dumps({"body": os.environ["COMMENT_BODY"]}))
         return 1
     fi
     if [[ "$write_status" != "201" ]]; then
-        echo "Error: Gitea comment write failed with HTTP $write_status" >&2
+        echo "Error: Gitea comment write failed with HTTP $write_status$(gitea_error_detail "$write_file")" >&2
         return 1
     fi
 
@@ -179,7 +228,7 @@ PY
         return 1
     fi
     if [[ "$readback_status" != "200" ]]; then
-        echo "Error: Gitea comment read-back failed with HTTP $readback_status" >&2
+        echo "Error: Gitea comment read-back failed with HTTP $readback_status$(gitea_error_detail "$readback_file")" >&2
         return 1
     fi
 
@@ -370,7 +419,7 @@ gitea_authenticated_login() {
         return 1
     fi
     if [[ "$status" != "200" ]]; then
-        echo "Error: Gitea authenticated-identity read failed with HTTP $status" >&2
+        echo "Error: Gitea authenticated-identity read failed with HTTP $status$(gitea_error_detail "$response_file")" >&2
         return 1
     fi
 
@@ -407,7 +456,7 @@ gitea_read_pr_head_into() {
         return 1
     fi
     if [[ "$status" != "200" ]]; then
-        echo "Error: Gitea PR head read failed with HTTP $status" >&2
+        echo "Error: Gitea PR head read failed with HTTP $status$(gitea_error_detail "$pr_file")" >&2
         return 1
     fi
     python3 - "$pr_file" <<'PY'
@@ -497,7 +546,7 @@ print(json.dumps({
     fi
     # Gitea returns 200 (occasionally 201) with the created review object.
     if [[ "$write_status" != "200" && "$write_status" != "201" ]]; then
-        echo "Error: Gitea review submit failed with HTTP $write_status (#865: no durable review created)" >&2
+        echo "Error: Gitea review submit failed with HTTP $write_status$(gitea_error_detail "$write_file")" >&2
         return 1
     fi
 
@@ -526,7 +575,7 @@ PY
         return 1
     fi
     if [[ "$readback_status" != "200" ]]; then
-        echo "Error: Gitea review read-back failed with HTTP $readback_status" >&2
+        echo "Error: Gitea review read-back failed with HTTP $readback_status$(gitea_error_detail "$readback_file")" >&2
         return 1
     fi
 

packages/mosaic/framework/tools/git/push-guard.README.md

@@ -0,0 +1,204 @@
+# push-guard
+
+Mechanical closure of one defect: **a verification that passes when the thing it verifies never happened.**
+
+Three incidents in one evening, three agents, no coordination, same shape:
+
+| #   | Incident                                                          | Why the check passed                                                |
+| --- | ----------------------------------------------------------------- | ------------------------------------------------------------------- |
+| 1   | `PUSH VERIFIED` reported after nothing was pushed                 | Commit had aborted, so local HEAD trivially equalled the remote ref |
+| 2   | An **empty commit** carrying another commit's message was pushed  | A push was chained after a _failed_ commit and ran on stale state   |
+| 3   | Conflict markers + invalid JSON committed into 70 generated files | Nothing asserted the generated output still parsed                  |
+
+Each is an assertion satisfied by the null case. `push-guard.sh` asserts the **positive** fact instead: a new object exists, the remote _moved_, the content _parses_.
+
+## Checks
+
+| Sub-command    | Asserts                                      | Exit on failure |
+| -------------- | -------------------------------------------- | --------------- |
+| `check-staged` | index has no unmerged paths                  | `2`             |
+|                | no conflict markers in staged content        | `2`             |
+|                | the conflict scan actually _completed_       | `2`             |
+|                | staged JSON under the nominated paths parses | `3`             |
+|                | **something is actually staged**             | `5`             |
+|                | **an explicit JSON decision exists**         | `6`             |
+| `push`         | HEAD advanced past `--since-head`            | `5`             |
+|                | HEAD is a non-empty commit                   | `5`             |
+|                | remote **moved**, and now equals local HEAD  | `4`             |
+
+## Usage
+
+```bash
+push-guard.sh check-staged --json-path 'data/**/*.json'
+
+BEFORE=$(git rev-parse HEAD)
+git commit -m "..."
+push-guard.sh push --remote origin --branch main --since-head "$BEFORE"
+```
+
+`--since-head` is what distinguishes "committed nothing" from "committed something", and capturing the remote ref _before_ pushing is what makes `remote == local` mean anything. Both were missing from the guard that produced incident 1.
+
+## Design decisions that measurement forced
+
+These are the interesting part; each one was wrong in the first draft.
+
+**A bare `=======` is deliberately NOT treated as a conflict marker.** It collides with reStructuredText underlines and ASCII rules. Every genuine conflict git writes also contains `<<<<<<<` and `>>>>>>>`, so requiring those loses no real detection. Measured against a real repository: **zero** false positives across the entire tracked tree.
+
+**The JSON check is opt-in by path, not on-by-default.** The first draft checked every staged `*.json`, on the reasoning that broader is strictly stronger. Measured against the same repository: **17 of 119** tracked `.json` files fail a strict parse, _all legitimately_ — every `tsconfig*.json` is JSONC (comments are legal there) and the CA templates are Go templates that merely carry a `.json` suffix. An on-by-default check fires on ~14% of the repo's JSON, and a guard that cries wolf gets routed around until the bypass is habitual — at which point the bypass covers the true positives too. Broader was **weaker**.
+
+**`--json-path` values are normalized to `:(glob)` magic.** Git's default pathspec matching makes `data/**/*.json` require at least one intermediate directory: it matches `data/sub/b.json` and _silently skips_ `data/a.json`. The obvious spelling would have delivered partial coverage with no warning.
+
+## Found by independent review, after the needles were already green
+
+An adversarial review (author ≠ reviewer) found two genuine fail-opens that 17 self-written needles, five mutation runs and a repo-wide false-positive measurement had all missed. Both were reproduced before being fixed, and both now have needles.
+
+**Renamed files were invisible to every content check.** Git detects renames by default (`diff.renames=true` since 2.9), so `git mv` plus a small edit is reported as a single `R` entry — which `--diff-filter=ACM` does not match. Reproduced at 97% similarity: the guard printed `staged content OK` and exited 0 with conflict markers in the staged blob. Fixed with `--no-renames`.
+
+There is a trap inside this one worth recording. With _only_ the renamed file staged, the guard exits 5 — the nothing-staged check fires because the file list came back empty. That looks like a catch and is pure accident; co-stage one ordinary file and the fail-open is total. The needle deliberately co-stages a clean file so it cannot pass for the wrong reason.
+
+**`-I` skipped files marked binary in `.gitattributes`,** while the summary still counted them as scanned — a clean pass _and_ a false count. Fixed with `-a`.
+
+The review also correctly identified one **vacuous control**: the positive `--since-head` case asserted only exit 0, which the push produces anyway, so deleting the entire `--since-head` block left it passing. It now asserts on output.
+
+Two reported findings did **not** reproduce and were not acted on: `:(glob)` does still match a bare directory pathspec, and my first rename repro failed only because the edit dropped similarity below the detection threshold — a badly built test, not an absent bug. Re-testing properly is what confirmed it.
+
+## The JSON decision is mandatory (`.push-guard.json`)
+
+The first release announced `JSON check NOT REQUESTED` and continued. That was _visible_ rather than silent, which is better — but it is still an **absence**, and an absence is not reviewable. Nobody reads a line that has printed correctly ten thousand times. A repo that needed the check and never wired it up stayed unprotected forever, and nothing ever failed.
+
+The decision is now required, from one of exactly two places:
+
+```jsonc
+// nominate generated JSON for parse-checking
+{"json_paths": ["data/**/*.json"], "allow_invalid_json": ["fixtures/*"]}
+
+// or opt out — the reason is REQUIRED and is printed on every run
+{"json_check": "none", "reason": "no generated JSON in this repo"}
+```
+
+`--json-path` on the command line also satisfies it. Saying nothing is refused (exit `6`).
+
+**The asymmetry is deliberate.** Turning the check _on_ is safe from anywhere, so a CLI flag suffices. Turning it _off_ is confined to a committed file, because that is the only form a human can review: you can read a reason in a diff, and you cannot review the fact that nobody typed a flag. An opt-out living in an ad-hoc command line is the old fail-open with extra steps.
+
+A **malformed** config is refused outright rather than treated as absent — that fallback would mean a typo silently disables the check the file was written to enable. A config that parses but _states nothing_ (`{}`) is refused too: valid JSON that says nothing is the original defect wearing a config file as a disguise.
+
+**Migration is a hard cutover, on purpose.** The tempting path is "warn for one release, then enforce" — but that warning phase _is_ the degrade-to-a-warning this tool forbids, and it leaves the fail-open open for exactly as long as the warning is ignored, which is indefinitely. Consumers add a config or the guard refuses. It breaks loudly, once. Two pre-existing cases in this repo's own harness were the first to pay that cost, which is the correct place to feel it.
+
+## Known limitations — stated, not hidden
+
+- `check-staged` inspects the index. Content added to the working tree _after_ it runs is not covered — it belongs in a `pre-commit` hook, where the window is smallest.
+- `push` hardcodes `HEAD:refs/heads/$branch`, so it cannot verify a commit built via plumbing on a different base. A `--sha` option would close this; it is deliberately not added without a needle.
+
+## Test harness
+
+`test-push-guard.sh` — 46 cases, each check in **both polarities**:
+
+- **NEEDLE** — a deliberately broken fixture that must trip the guard.
+- **CONTROL** — a clean fixture that must pass.
+
+Controls are not decoration. A guard that failed unconditionally would satisfy every needle and look fully covered. Several controls additionally assert on the guard's _output_ (`--out`), because exit 0 cannot distinguish "checked the files and they were fine" from "matched no files and had nothing to check" — two controls in an earlier revision were passing vacuously for exactly that reason.
+
+### Mutation results — the harness was itself tested by breaking the guard
+
+**Everything in this section is regenerated by `./mutate-push-guard.sh`, not typed.** The previous version of this table was hand-maintained: it was true when written, went stale as the suite grew, and ended up asserting `unmodified | 32/32 pass` against a 46-case suite. A README is what a reader consults when the tool misbehaves, so a confidently-wrong one is worse than none. Re-run the script and paste; do not edit the numbers.
+
+| mutation                                                         | suite result        | verdict  |
+| ---------------------------------------------------------------- | ------------------- | -------- |
+| _unmodified_                                                     | 46 passed, 0 failed | baseline |
+| `json decision requirement bypassed` (L482)                      | 3/43 fail           | killed   |
+| `opt-out accepted with no written reason` (L334)                 | 1/43 fail           | killed   |
+| `committed re-read of the opt-out skipped` (L405)                | 5/43 fail           | killed   |
+| `untracked config honoured as an opt-out` (L409)                 | 1/43 fail           | killed   |
+| `staged-but-uncommitted opt-out honoured` (L425)                 | 1/43 fail           | killed   |
+| `committed SYMLINK config honoured` (L433)                       | 1/43 fail           | killed   |
+| `unparseable committed config ignored` (L444)                    | 1/43 fail           | killed   |
+| `local-only opt-out (HEAD says ON) honoured` (L459)              | 1/43 fail           | killed   |
+| `empty MERGE exempted` (L704)                                    | 1/43 fail           | killed   |
+| `empty ROOT exempted` (L715)                                     | 1/43 fail           | killed   |
+| `--since-head ancestry check removed` (L665)                     | 1/43 fail           | killed   |
+| `staged-file enumeration ignores git failure` (L173)             | 1/43 fail           | killed   |
+| `malformed config degrades to absent instead of refusing` (L375) | 4/43 fail           | killed   |
+
+13 mutants, 0 survived.
+
+**Why the denominator is 43 while the suite reports 46.** The generator attributes kills only to cases it can parse by name, which is the `PASS [KIND] <name> (exit N)` form. Of the 46 passing assertions, 45 print `PASS` and 43 of those match that form. The three excluded lines are:
+
+```
+  PASS  [CONTROL] guard runs without emitting any interpreter warning
+  PASS  [NEEDLE ] the warning detector fires on a known warning string
+  ok    [e9-fixture    ] fixture is a merge (3 fields) with tree identical to both parents
+```
+
+The two `z1` warning assertions assert on a whole _class_ of output rather than an exit code, so they carry no `(exit N)`; `e9-fixture` is a fixture precondition and prints in the `ok` form. All three still run and still gate the suite — they are excluded from _attribution_, not from _execution_.
+
+An earlier revision of this paragraph named the excluded set as `w2-fixture`, `e9-fixture` and `g1-fixture`. **That was written from memory instead of from the output, and two of the three names were wrong:** `w2-fixture` belongs to `test-verify-clean-clone.sh` and `g1-fixture` to `test-mutate-push-guard.sh`, so neither runs in this suite at all and neither could contribute to its tally. A reader auditing the denominator would have gone looking for them in the wrong files. It is recorded rather than quietly corrected because a confidently-wrong provenance inside the section that exists to make a generated number auditable is the same defect as everything else on this page: **a claim that reads as measured and is not.** The set above was produced by running the suite and applying the generator's own parser to its output.
+
+Earlier mutants, run at the suite size of the day and kept as history rather than as a live claim: fail-open (9/16), always-fail (16/16 — controls catch it), revert `:(glob)` normalization (3/16, caught **only** by the `--out` assertions), drop the remote-did-not-move assertion (1/16), restore blanket `|| true` on the scan (1/17), revert `--no-renames` (1/19), revert `-a` to `-I` (1/19), delete the `--since-head` block (2/19, incl. the control that _was_ vacuous), stray-warning emission (1/32).
+
+A guard nobody has watched fail is not a guard. The same applies to the harness: the `:(glob)` mutant would have passed silently without the output assertions, so the assertions are load-bearing rather than ornamental.
+
+### Two branches were uncovered, and writing this table is what found them
+
+Building the generator turned up two mutants that survived a **46-case suite reporting 46/46 green**: `staged-but-uncommitted opt-out honoured` and `unparseable committed config ignored`. Neither branch had any case at all. Both are now needled, which is why they read _killed_ above.
+
+Both survivors share a shape worth naming: the mutant still exits `6`, because control falls through to a _sibling_ refusal that rejects for a different reason. **An exit-code-only assertion would have been satisfied by the wrong branch.** The new cases anchor on the distinguishing clause instead.
+
+The same audit found a live instance of that defect already in the suite. Three separate branches print the headline `OPT-OUT IS NOT REVIEWABLE` — untracked, staged-not-committed, and symlink — and the untracked needle was anchored on the shared headline. Delete the untracked branch and control reaches a sibling printing those same words, so **the needle would not fail; it would re-point.** A substring anchor does not fail when its subject is removed. It is now anchored on `is not tracked in git`.
+
+### The generator refuses three ways a mutation run can lie
+
+1. **The anchor no longer matches.** The mutant is never applied, the suite is green, and a naive report says _survived_ — the same word a real coverage gap gets. `ANCHOR MISSING` is a loud failure instead.
+2. **The anchor matches prose.** This one landed on the first run: a mutant aimed at the refuse-on-missing-config branch matched inside the `usage()` heredoc, edited a help string, changed no behaviour, and duly reported _survived_. A documentation edit was one step from being recorded as an uncovered branch. **A mutation that cannot change behaviour is not a surviving mutant, it is a non-measurement** — and a non-measurement reported as a result is the same defect as the vacuous test the harness exists to hunt. Anchors resolving inside `usage()` are now refused, and the heredoc's bounds are located at runtime rather than hardcoded.
+3. **The anchor is ambiguous.** Two unrelated branches here are both the single line `if (( status != 0 )); then`; a first-match replace would silently attribute the kill to whichever came first. Multi-line anchors are supported and a match count `!= 1` refuses rather than guesses.
+
+**A blanket `|| true` on the scan was a fail-open in the guard's own error handling.** `git grep` exits `1` for "no match" but `>=2` for a real failure. `|| true` collapsed the two, so a malformed pathspec or unreadable index would have been reported as "ok, no conflict markers" — a clean pass from a scan that never ran. The status is now discriminated, and a PATH-shim fault-injection needle proves the refusal.
+
+**A `<<'PY'` heredoc inside `$( )` made bash print a warning on every run — and 30 needles plus a clean linter all missed it.** The config parser started life as an inline heredoc inside a command substitution, so every invocation emitted `warning: command substitution: 1 unterminated here-document` to stderr. It executed correctly, every needle stayed green, and shellcheck reported nothing. The harness missed it because `expect` asserts _substrings it was told to look for_ — and nobody tells you to look for output you did not know existed. It surfaced only when the guard was run against a real repository.
+
+The fix moves the parser to a top-level constant. The lesson is encoded as case `z1`, which asserts the **absence of a whole output class** rather than the presence of an expected string, and is paired with a needle proving the detector can fire. A tool built to refuse quiet failures was quietly polluting stderr for its entire existence.
+
+**The `-E` flag on `git grep` is load-bearing and was caught by a needle, not by review.** `git grep` defaults to _basic_ regex, in which `(`, `|` and `{7}` are literal characters. Without `-E` the patterns match nothing and the check reports a clean pass over a file full of conflict markers — the exact defect this tool exists to prevent, shipped inside the tool itself.
+
+### Then the review turned on the harness, and found three more
+
+A second independent review ran everything from a fresh clone and reproduced three defects — **all of them in the tools written to prevent defects.** None was in `push-guard.sh`.
+
+**1. The clean-clone verifier could not verify the tree that ships it.** `verify-clean-clone.sh` resolved the repository top level correctly but then passed **bare basenames** to `git ls-tree`, which is a root-relative pathspec. These files really live at `packages/mosaic/framework/tools/git/`, so in place every artifact came back `NOT TRACKED at HEAD` and the verifier exited 1 without ever running. The tool built to stop packaging false-greens was unusable against its own packaging.
+
+Its suite could not see it, because **every fixture installed the artifacts at the fixture repository root.** 6/6 green proved flat-layout operation and said nothing about the deployed path. That is the third time on this tool that a control validated a _model_ instead of the _subject_: v1 of the verifier measured a `cp`'d scratch repo, and then v2's own tests measured a layout that does not exist. **A fixture is a claim about the world; an untested fixture is an unreviewed one.** The committed prefix now comes from `git rev-parse --show-prefix` and is threaded through `ls-tree`, the cloned `stat`, and the suite's working directory; `w6-nested` builds the real nested layout, `w6-prefix` asserts the verifier _reports_ that prefix (so a green `w6` cannot mean the prefix was harmlessly ignored), and `w7-nested-mode` proves the mode needle still bites down there.
+
+**2. Any pre-existing suite failure satisfied every mutant.** The generator called a mutant `KILLED` whenever `failed > 0`, and never required a green baseline. Inject one always-failing case that changes no guard behaviour whatsoever and the run reports _13 killed, 0 survived_, emits the table above, and exits 0. **A tally is not evidence; a named delta is.** The generator now refuses outright unless the unmodified baseline is exit-0 with zero failures — and emits no table when it refuses — then scores each mutant by the _named cases_ that stopped passing, printing the first one (`by: <case>`) beside every kill.
+
+**3. An interrupted run stranded a mutated `push-guard.sh` in the reviewed tree.** Restoration leaned on an `EXIT` trap. **A trap is cleanup, not isolation, and SIGKILL cannot run it.** It happened to the reviewer twice and contaminated the following suite run until the clone was discarded. Isolation is now by construction: the guard and suite are `install`ed into a temp dir and every mutation is applied to _that_ copy, so the reviewed file is never opened for writing at all.
+
+Note the deliberate asymmetry with `verify-clean-clone.sh`, which forbids `cp` anywhere in the file. The rule is not "never copy" — it is **know whether the copy preserves the property you are about to measure.** `cp` launders mode, so the verifier must not copy; mutation is destructive by design, so the generator must.
+
+`test-mutate-push-guard.sh` (8 cases) now covers all three: `g1-*` proves a red baseline is refused with no table, `g2-*` is the positive control plus an assertion that kills are attributed by name, and `g3-*` kills the generator mid-mutation and asserts the subject is byte-identical afterwards.
+
+That last one was **vacuous on its first attempt.** `timeout -s KILL 3` looked convincing and proved nothing: at three seconds the generator is still running its baseline, so no mutation has been applied and the subject is trivially unchanged — for the _unfixed_ in-place generator too, which I confirmed by rebuilding it and running it. The kill is now driven from inside the run (the fixture's suite counts its own invocations and kills the generator on the second, when mutant #1 is applied), and `g3-needle-bites` puts the reconstructed pre-fix mechanism through the identical kill to prove it _does_ strand a mutated file. A control written to close a blocker was itself a member of the vacuous family.
+
+Two smaller things fell out of building those cases, both worth recording because both read as the opposite of what they were:
+
+- **`grep -q` under `pipefail` turns a successful match into a failed assertion.** `grep -q` exits at the first match, the producer dies of SIGPIPE, and `pipefail` reports 141. This cost a red `w6-prefix` against a verifier that was printing the right prefix all along. Capture into a variable and test the variable.
+- **`$PPID` inside `$( )` is the subshell, not the caller.** Killing it merely ends the command substitution; the parent carries on and exits 0. The fixture uses `kill -9 0` (the process group) with the generator launched under `setsid --wait`.
+
+**Linting is measured at default severity, and the earlier claim was not.** "shellcheck clean on all five" was published on the strength of `shellcheck -S warning`, which exited 0 — while the default severity exited 1 with twelve `SC2016` findings. A filtered measurement reported as an unfiltered claim is the same shape as everything else on this page. Those literals genuinely must not expand, so `run_mutants()` carries one scoped, documented `SC2016` suppression; all six files are now clean at **default** severity. (A documented "this literal is intentionally unexpanded" is a different thing from a comment asserting a safety property nobody rechecks.)
+
+**Not independently reproduced here:** blocker 1's original repro ran against the real PR checkout, and this session has no credential for that remote. The `w6`/`w7` fixtures replicate the layout at the exact deployed prefix instead, which is a reconstruction, not the original observation. Stated rather than glossed.
+
+## Proposed framework path
+
+```
+framework/tools/git/push-guard.sh               # the guard
+framework/tools/git/test-push-guard.sh          # 46 needles and controls
+framework/tools/git/mutate-push-guard.sh        # regenerates the mutation table above
+framework/tools/git/test-mutate-push-guard.sh   # 8 needles for the generator
+framework/tools/git/verify-clean-clone.sh       # proves the COMMITTED artifact runs
+framework/tools/git/test-verify-clean-clone.sh  # 9 needles for the verifier
+```
+
+Matches the existing `tools/git/test-*.sh` convention. Dependencies: bash 4.4+, git, python3 — `python3` is already an accepted dependency of `ci-queue-wait.sh`.
+
+**All six must be committed mode `100755`.** They were once delivered `100644`, so a clone exited `126 Permission denied` for everyone who was not the author; `verify-clean-clone.sh` exists to make that unshippable and asserts the mode from `git ls-tree` of the source commit, never from the filesystem.
+
+Operator-agnostic: no hostnames, credentials, remotes, or operator-specific paths. Clean under the framework-PR firewall.

packages/mosaic/framework/tools/git/push-guard.sh

@@ -0,0 +1,793 @@
+#!/usr/bin/env bash
+# push-guard.sh - Mechanical guards against verifications that PASS when the
+# thing they verify never happened.
+#
+# WHY THIS EXISTS
+# ---------------
+# Three independent incidents, one shape:
+#   1. An agent's "PUSH VERIFIED" step compared local HEAD to the remote ref and
+#      reported success. The commit had ABORTED, so local trivially equalled
+#      remote. The guard could not distinguish "pushed" from "committed nothing".
+#   2. An agent chained a push after a FAILED commit, ran on stale state, and
+#      pushed an EMPTY commit carrying an unrelated commit's message.
+#   3. An agent committed unresolved conflict markers into 70 generated files and
+#      pushed invalid JSON to a default branch.
+#
+# All three are the same defect: a check whose success condition is satisfied by
+# the null case. This script asserts the POSITIVE fact (a new object exists, the
+# remote MOVED, the content parses) rather than the absence of an error.
+#
+# DESIGN RULES (do not relax these)
+#   * Every check exits NON-ZERO and names what failed. There is deliberately no
+#     --warn-only / --soft flag: a guard that can degrade to a warning is the
+#     fail-open we are trying to remove.
+#   * Checks are fail-CLOSED. `set -euo pipefail` means an unexpected git or
+#     network error aborts non-zero rather than falling through to "OK".
+#   * Nothing is skipped silently. A check with no applicable inputs says so on
+#     stdout instead of contributing a quiet green.
+#
+# EXIT CODES
+#   0   all requested checks passed
+#   2   conflict markers present, or the index has unmerged paths
+#   3   staged JSON does not parse
+#   4   push verification failed (remote did not move, or moved elsewhere)
+#   5   nothing staged / empty commit — the null case, refused
+#   6   NO JSON DECISION — no --json-path and no usable .push-guard.json
+#   64  usage error
+#
+# Dependencies: bash 4.4+, git, python3.
+
+set -euo pipefail
+
+readonly EX_OK=0
+readonly EX_CONFLICT=2
+readonly EX_JSON=3
+readonly EX_PUSH=4
+readonly EX_NULL=5
+readonly EX_CONFIG=6
+readonly EX_USAGE=64
+
+# Repo-level configuration. Its ABSENCE is refused, not defaulted — see
+# resolve_json_config() for why.
+readonly CONFIG_FILE=".push-guard.json"
+
+# Conflict-marker detection.
+#
+# We match `<<<<<<<`, `>>>>>>>` and the diff3 `|||||||` marker, each anchored at
+# column 0 and required to be followed by a space or end-of-line (real markers
+# are exactly seven characters plus an optional ref label).
+#
+# We deliberately do NOT match a bare `=======` line. It is the one marker that
+# collides with ordinary prose — reStructuredText section underlines and ASCII
+# rules use it constantly — and a guard that fires on documentation gets switched
+# off, which costs more than the miss. Every genuine conflict git writes contains
+# `<<<<<<<` and `>>>>>>>` as well, so requiring those loses no real detection.
+readonly MARKER_PATTERNS=(
+    -e '^<<<<<<<( |$)'
+    -e '^>>>>>>>( |$)'
+    -e '^[|]{7}( |$)'
+)
+
+log()  { printf '%s\n' "$*"; }
+fail() {
+    local code="$1"; shift
+    printf '\n' >&2
+    printf 'PUSH-GUARD FAILED: %s\n' "$1" >&2
+    shift
+    local line
+    for line in "$@"; do printf '  %s\n' "$line" >&2; done
+    printf '\n' >&2
+    exit "$code"
+}
+
+usage() {
+    cat <<'EOF'
+Usage:
+  push-guard.sh check-staged [--json-path <pathspec>]...
+                             [--allow-invalid-json <pathspec>]...
+  push-guard.sh push --remote <remote> --branch <branch> [--since-head <sha>]
+                     [-- <extra git push args>...]
+  push-guard.sh --help
+
+Subcommands:
+  check-staged   Run pre-commit content guards against the STAGED index:
+                   (a) no unmerged index paths, no conflict markers
+                   (c) staged JSON under the nominated paths parses
+                 Refuses to pass when nothing is staged (exit 5).
+                 Check (c) requires an EXPLICIT decision — either --json-path,
+                 or .push-guard.json. Saying nothing is refused (exit 6).
+
+  push           Perform a push and prove it HAPPENED:
+                   - HEAD is a non-empty commit (differs from its parent)
+                   - with --since-head: HEAD advanced past that sha
+                   - the remote ref MOVED, and now equals local HEAD
+                 Capturing the remote ref BEFORE the push is what makes
+                 "remote == local" meaningful; without it the assertion is
+                 satisfied by having pushed nothing.
+
+Options:
+  --json-path <pathspec>           Git pathspec of generated/serialized JSON to
+                                   parse-check, e.g. 'data/**/*.json'. Repeatable.
+                                   Opt-in on purpose: many real .json files are
+                                   JSONC (tsconfig) or templates and do NOT parse
+                                   strictly. Nominate the generated ones. Satisfies
+                                   the decision requirement on its own; overrides a
+                                   config opt-out (loudly).
+  --allow-invalid-json <pathspec>  Exempt a path from the JSON parse check
+                                   (for deliberate malformed-input fixtures).
+                                   Exemptions are printed, never silent.
+  --since-head <sha>               HEAD before your commit step. Asserts a new
+                                   commit object was actually created.
+  --remote <name>                  Remote to push to.
+  --branch <name>                  Branch to push.
+
+Repo config (.push-guard.json, at the repository root):
+  {"json_paths": ["data/**/*.json"], "allow_invalid_json": ["fixtures/*"]}
+    — nominate generated JSON for parse-checking.
+  {"json_check": "none", "reason": "no generated JSON in this repo"}
+    — opt out. The reason is REQUIRED and is printed on every run.
+
+An opt-out is only accepted from this file, never from a command-line flag: a
+committed reason can be read in a diff, an absent flag cannot be reviewed at all.
+An invalid config is refused outright rather than treated as absent.
+
+There is no flag to downgrade a failure to a warning. That is intentional.
+EOF
+}
+
+require_repo() {
+    git rev-parse --show-toplevel >/dev/null 2>&1 \
+        || fail "$EX_USAGE" "not inside a git repository"
+    cd "$(git rev-parse --show-toplevel)"
+}
+
+# ---------------------------------------------------------------- check-staged
+
+# staged_files_z <array-name> [pathspec...]
+#
+# THE FAIL-OPEN THIS FUNCTION EXISTS TO REMOVE:
+#   mapfile -d '' -t files < <(git diff ...)
+# observes MAPFILE's exit status, never the producer's. When git diff dies -- a
+# bad pathspec, a corrupt index -- mapfile cheerfully reads zero bytes and
+# succeeds, and the caller then reports that silence as "nothing to check".
+#
+# `set -o pipefail` does NOT cover this. pipefail applies to PIPELINES; a process
+# substitution is an asynchronous child whose status is never collected. That is
+# the precise reason every `cmd | cmd` in this file is safe and both `< <(cmd)`
+# constructs were not -- a distinction worth stating, because "we set pipefail"
+# reads like whole-file coverage and is not.
+#
+# Both callers now route through here, so the category is gone rather than the
+# two known instances being patched.
+staged_files_z() {
+    local -n _out="$1"; shift
+    local tmp err status=0
+    tmp="$(mktemp)"; err="$(mktemp)"
+    if (( $# )); then
+        git diff --cached --name-only --diff-filter=ACM --no-renames -z \
+            -- "$@" >"$tmp" 2>"$err" || status=$?
+    else
+        git diff --cached --name-only --diff-filter=ACM --no-renames -z \
+            >"$tmp" 2>"$err" || status=$?
+    fi
+    if (( status != 0 )); then
+        local msg; msg="$(tr '\n' ' ' <"$err")"
+        rm -f "$tmp" "$err"
+        fail "$EX_CONFIG" \
+            "CANNOT ENUMERATE STAGED FILES — git diff exited $status" \
+            "git said: ${msg:-(no message)}" \
+            "" \
+            "Refusing to report a result. An enumeration that failed returns no" \
+            "files, which is indistinguishable from a clean tree — reporting that" \
+            "as OK would be a silent pass on an unexamined index."
+    fi
+    _out=()
+    mapfile -d '' -t _out <"$tmp"
+    rm -f "$tmp" "$err"
+}
+
+check_unmerged() {
+    local unmerged
+    unmerged="$(git ls-files --unmerged | awk '{print $4}' | sort -u)"
+    if [[ -n "$unmerged" ]]; then
+        mapfile -t paths <<<"$unmerged"
+        fail "$EX_CONFLICT" \
+            "the index has UNMERGED paths — a merge/rebase is still in progress" \
+            "${paths[@]}" \
+            "" \
+            "Resolve the conflict and 'git add' the result. Do not commit past this."
+    fi
+    log "  ok  index has no unmerged paths"
+}
+
+check_conflict_markers() {
+    local -a files=("$@")
+    local hits
+    # git grep --cached searches the INDEX (what will actually be committed),
+    # not the working tree.
+    #
+    # -a (treat every blob as text), NOT -I (skip binary). -I honours git's
+    # binary classification, which includes an explicit `.gitattributes` `binary`
+    # attribute. A repo that marks a path binary would have its staged conflict
+    # markers silently skipped while the summary still counted the file as
+    # scanned — a clean pass AND a false count. Verified reproducible. The cost
+    # of -a is that a genuine binary blob could theoretically emit a noisy match
+    # line; a false alarm is recoverable, a silent miss is not.
+    # -E is load-bearing: git grep defaults to BASIC regex, in which '(', '|'
+    # and '{7}' are literal characters. Without it these patterns match nothing
+    # and the check reports a clean pass over a file full of markers. That
+    # failure was caught by the needle, not by review.
+    #
+    # Exit status is discriminated, NOT swallowed. git grep returns 1 for "no
+    # match" and >=2 for a real error (bad pathspec, unreadable index). A blanket
+    # '|| true' would turn a broken scan into "ok, no conflict markers" — the
+    # same fail-open in the guard's own error handling.
+    local status=0
+    hits="$(git grep --cached -a -n -E "${MARKER_PATTERNS[@]}" -- "${files[@]}")" || status=$?
+    if (( status > 1 )); then
+        fail "$EX_CONFLICT" \
+            "git grep FAILED (exit $status) — the conflict scan did not run" \
+            "Refusing to report a clean result from a scan that did not complete."
+    fi
+    if [[ -n "$hits" ]]; then
+        mapfile -t lines <<<"$hits"
+        fail "$EX_CONFLICT" \
+            "staged content contains unresolved CONFLICT MARKERS" \
+            "${lines[@]}" \
+            "" \
+            "These are staged and would be committed verbatim."
+    fi
+    log "  ok  no conflict markers in ${#files[@]} staged file(s)"
+}
+
+# JSON parse check.
+#
+# SCOPE IS OPT-IN, AND THAT IS A MEASURED DECISION, NOT LAZINESS.
+# The first draft checked every staged *.json. Run against a real repository that
+# turned out to be 17 of 119 tracked .json files failing a strict parse — all of
+# them legitimate: every tsconfig*.json is JSONC (comments are legal there) and
+# the CA templates are Go templates that merely carry a .json suffix. An
+# on-by-default check would have fired on ~14% of this repo's JSON, and a guard
+# that cries wolf gets routed around until the bypass is habitual — which is
+# worse than no guard, because the bypass then also covers the true positives.
+#
+# So the caller nominates the generated/serialized paths this check is FOR, as
+# git pathspecs (git, not bash, expands them — '**' works correctly).
+#
+# WHAT SAYING NOTHING NOW COSTS YOU
+# ---------------------------------
+# The first release announced "JSON check NOT REQUESTED" and continued. That was
+# visible rather than silent, which is better — but it is still an ABSENCE, and
+# an absence is not reviewable. Nobody reads a line that has printed correctly
+# ten thousand times. A repo that needed the check and never wired it up stayed
+# unprotected forever, and nothing ever failed.
+#
+# The decision is now MANDATORY and must come from one of two places:
+#   * turning the check ON  — --json-path on the command line, or "json_paths"
+#                             in .push-guard.json
+#   * turning the check OFF — ONLY "json_check": "none" in .push-guard.json,
+#                             which REQUIRES a non-empty "reason"
+# Saying nothing at all is refused (exit 6).
+#
+# The asymmetry is deliberate. Turning a check on is safe from anywhere. Turning
+# one OFF is confined to a committed file because that is the only form a human
+# can review: you can read a reason in a diff, and you cannot review the fact
+# that nobody typed a flag. An opt-out that lives in an ad-hoc command line is
+# just the old fail-open with extra steps.
+# The config parser, held as a string rather than an inline heredoc.
+#
+# A `<<'PY'` heredoc INSIDE a $( ) command substitution makes bash emit
+#   warning: command substitution: 1 unterminated here-document
+# on every single run. It still executed, every needle stayed green and the
+# static linter stayed clean — the warning goes to stderr and broke no
+# assertion. It surfaced only when the guard was run against a real
+# repository. A tool built to refuse quiet output was quietly polluting
+# stderr; needle 'z1' now asserts the guard emits no warnings at all.
+#
+# `read -d ''` returns non-zero at EOF without finding a NUL, which is the
+# NORMAL path when slurping a heredoc — hence `|| true`. That is the one
+# shape where it does not mask a real error, unlike the `git grep || true`
+# this codebase already removed once.
+IFS='' read -r -d '' CONFIG_PARSER <<'PY' || true
+import json, sys
+
+path = sys.argv[1]
+try:
+    with open(path) as fh:
+        cfg = json.load(fh)
+except Exception as exc:
+    sys.stderr.write("does not parse: %s" % exc)
+    sys.exit(2)
+
+if not isinstance(cfg, dict):
+    sys.stderr.write("must contain a JSON object, got %s" % type(cfg).__name__)
+    sys.exit(2)
+
+def clean_list(name, value):
+    if not isinstance(value, list):
+        sys.stderr.write('"%s" must be an array' % name)
+        sys.exit(2)
+    for item in value:
+        if not isinstance(item, str) or not item.strip():
+            sys.stderr.write('"%s" must contain only non-empty strings' % name)
+            sys.exit(2)
+        # Tabs/newlines would be mangled by the tab-delimited handoff below.
+        # Reject them explicitly rather than silently truncating a pathspec.
+        if "\t" in item or "\n" in item:
+            sys.stderr.write('"%s" entry contains a tab or newline: %r' % (name, item))
+            sys.exit(2)
+    return value
+
+mode = cfg.get("json_check")
+paths = cfg.get("json_paths")
+allow = cfg.get("allow_invalid_json", [])
+
+if mode is not None and mode != "none":
+    sys.stderr.write('"json_check" must be "none" if present, got %r' % (mode,))
+    sys.exit(2)
+
+if mode == "none":
+    if paths:
+        sys.stderr.write('"json_check": "none" and "json_paths" are mutually exclusive')
+        sys.exit(2)
+    reason = cfg.get("reason")
+    if not isinstance(reason, str) or not reason.strip():
+        sys.stderr.write('"json_check": "none" REQUIRES a non-empty "reason"')
+        sys.exit(2)
+    print("MODE\tnone")
+    print("REASON\t%s" % reason.strip().replace("\t", " ").replace("\n", " "))
+    sys.exit(0)
+
+if paths is None:
+    sys.stderr.write(
+        'states no decision — needs "json_paths", '
+        'or "json_check": "none" with a "reason"'
+    )
+    sys.exit(2)
+
+clean_list("json_paths", paths)
+if not paths:
+    sys.stderr.write('"json_paths" must not be empty')
+    sys.exit(2)
+clean_list("allow_invalid_json", allow)
+
+print("MODE\tcheck")
+for item in paths:
+    print("JPATH\t%s" % item)
+for item in allow:
+    print("ALLOW\t%s" % item)
+PY
+
+resolve_json_config() {
+    local cfg out status=0
+    cfg="$(git rev-parse --show-toplevel)/$CONFIG_FILE"
+
+    if [[ ! -f "$cfg" ]]; then
+        CFG_MODE="absent"
+        return 0
+    fi
+
+    # A malformed config must REFUSE, never degrade to "treat as absent". That
+    # fallback would rebuild precisely the fail-open this gate closes: a typo in
+    # the config would silently disable the check it was written to enable.
+    out="$(python3 -c "$CONFIG_PARSER" "$cfg" 2>&1)" || status=$?
+
+    if (( status != 0 )); then
+        fail "$EX_CONFIG" \
+            "$CONFIG_FILE is INVALID — $out" \
+            "" \
+            "Refusing to run. A config that does not parse is not the same as no" \
+            "config: treating it as absent would silently disable the very check" \
+            "this file was written to enable."
+    fi
+
+    local key val
+    while IFS=$'\t' read -r key val; do
+        case "$key" in
+            MODE)   CFG_MODE="$val" ;;
+            REASON) CFG_REASON="$val" ;;
+            JPATH)  CFG_PATHS+=("$val") ;;
+            ALLOW)  CFG_ALLOW+=("$val") ;;
+        esac
+    done <<<"$out"
+
+    # ------------------------------------------------------------------
+    # THE ASYMMETRY, ENFORCED RATHER THAN INTENDED.
+    # ON may come from anywhere: turning a check on needs no review.
+    # OFF must come from a COMMITTED object, because the entire argument for
+    # requiring a written reason was that a reason is reviewable in a diff
+    # while an absence is not. An opt-out honoured from an untracked
+    # working-tree file is not reviewable either -- it is an ad-hoc local
+    # bypass wearing a config file's clothes, and it defeats the design.
+    # So the OFF decision is re-read from HEAD and the working tree gets no
+    # vote in it. A committed ON flipped to OFF locally is likewise refused.
+    # ------------------------------------------------------------------
+    [[ "$CFG_MODE" == "none" ]] || return 0
+
+    local rel cmode cblob cout cstatus=0
+    rel="$(git ls-files --full-name --error-unmatch -- "$cfg" 2>/dev/null)" || rel=""
+    if [[ -z "$rel" ]]; then
+        fail "$EX_CONFIG" \
+            "OPT-OUT IS NOT REVIEWABLE — $CONFIG_FILE is not tracked in git" \
+            "recorded reason was: ${CFG_REASON:-(none)}" \
+            "" \
+            "The opt-out requires a written reason precisely so it shows up in a" \
+            "diff. An untracked file shows up in nobody's review, so honouring it" \
+            "would rebuild the unreviewable bypass this design exists to prevent." \
+            "" \
+            "Commit $CONFIG_FILE, then run again. Turning the check ON needs no" \
+            "commit; only turning it OFF does."
+    fi
+
+    # A COMMITTED SYMLINK (mode 120000) is a mutable target: the reviewed blob
+    # is a path, and what it points at can change without any diff at all.
+    cmode="$(git ls-tree HEAD -- "$rel" 2>/dev/null | awk '{print $1}')"
+    if [[ -z "$cmode" ]]; then
+        fail "$EX_CONFIG" \
+            "OPT-OUT IS NOT REVIEWABLE — $CONFIG_FILE is staged but not yet in HEAD" \
+            "recorded reason was: ${CFG_REASON:-(none)}" \
+            "" \
+            "A staged-but-uncommitted opt-out has not been through review either." \
+            "Commit it first."
+    fi
+    if [[ "$cmode" == "120000" ]]; then
+        fail "$EX_CONFIG" \
+            "OPT-OUT IS NOT REVIEWABLE — $CONFIG_FILE is a committed SYMLINK" \
+            "" \
+            "The reviewed object would be a path, not a decision: what it points" \
+            "at can be changed later without producing any diff. Commit the" \
+            "config as a regular file."
+    fi
+
+    cblob="$(git show "HEAD:$rel" 2>/dev/null)" || cblob=""
+    cout="$(printf '%s' "$cblob" | python3 -c "$CONFIG_PARSER" /dev/stdin 2>&1)" || cstatus=$?
+    if (( cstatus != 0 )); then
+        fail "$EX_CONFIG" \
+            "COMMITTED $CONFIG_FILE is INVALID — $cout" \
+            "" \
+            "The working tree opts out, but the committed version does not parse," \
+            "so there is no reviewable decision to honour."
+    fi
+    local cmode_val="" creason=""
+    while IFS=$'\t' read -r key val; do
+        case "$key" in
+            MODE)   cmode_val="$val" ;;
+            REASON) creason="$val" ;;
+        esac
+    done <<<"$cout"
+
+    if [[ "$cmode_val" != "none" ]]; then
+        fail "$EX_CONFIG" \
+            "LOCAL-ONLY OPT-OUT — the working tree turns the JSON check OFF but" \
+            "HEAD does not (committed decision: $cmode_val)" \
+            "working-tree reason: ${CFG_REASON:-(none)}" \
+            "" \
+            "An uncommitted edit that disables a committed check is exactly the" \
+            "unreviewable bypass this guard refuses. Commit the change if it is" \
+            "real; revert it if it was a local convenience."
+    fi
+
+    # Print the COMMITTED reason, never the working tree's: the reason anyone
+    # can actually review is the one in the object.
+    CFG_REASON="$creason"
+}
+
+check_staged_json() {
+    local -a checked=() skipped=()
+    local f err
+    local -a pathspec=()
+
+    resolve_json_config
+
+    if (( ${#JSON_PATHS[@]} == 0 )); then
+        case "$CFG_MODE" in
+            absent)
+                fail "$EX_CONFIG" \
+                    "NO JSON DECISION — no --json-path, and no $CONFIG_FILE" \
+                    "" \
+                    "This guard will not run without an explicit decision about" \
+                    "staged-JSON validation. Create $CONFIG_FILE with EITHER:" \
+                    "" \
+                    '  {"json_paths": ["data/**/*.json"]}' \
+                    "" \
+                    "or, if this repo genuinely has no generated JSON:" \
+                    "" \
+                    '  {"json_check": "none", "reason": "<why>"}' \
+                    "" \
+                    "The reason is mandatory so the opt-out is recorded and" \
+                    "reviewable in the diff, instead of being an absence nobody sees."
+                ;;
+            none)
+                log "  --  JSON check OPTED OUT in $CONFIG_FILE — recorded reason: $CFG_REASON"
+                return 0
+                ;;
+            check)
+                JSON_PATHS=(${CFG_PATHS[@]+"${CFG_PATHS[@]}"})
+                ALLOW_INVALID_JSON+=(${CFG_ALLOW[@]+"${CFG_ALLOW[@]}"})
+                log "  ..  JSON paths from $CONFIG_FILE: ${JSON_PATHS[*]}"
+                ;;
+        esac
+    else
+        # An explicit --json-path turns the check ON, so it satisfies the decision
+        # requirement by itself. If the config opted out, the nomination WINS and
+        # says so loudly — resolving a contradiction toward more checking is the
+        # only safe direction, but silently ignoring a committed opt-out would
+        # hide a real disagreement.
+        case "$CFG_MODE" in
+            none)
+                log "  !!  $CONFIG_FILE opts out of the JSON check, but --json-path was"
+                log "  !!  given — honouring the nomination and checking anyway."
+                ;;
+            check)
+                JSON_PATHS+=(${CFG_PATHS[@]+"${CFG_PATHS[@]}"})
+                ALLOW_INVALID_JSON+=(${CFG_ALLOW[@]+"${CFG_ALLOW[@]}"})
+                ;;
+        esac
+    fi
+
+    # Normalize to :(glob) magic. WITHOUT it, git's default pathspec matching
+    # makes 'data/**/*.json' require at least one intermediate directory, so it
+    # matches data/sub/b.json but SILENTLY SKIPS data/a.json. The obvious
+    # spelling would then deliver partial coverage with no warning — a
+    # quiet-underscan, which is the same family of defect as a quiet pass.
+    # Pathspecs that already carry explicit magic (leading ':') are left alone.
+    for f in "${JSON_PATHS[@]}"; do
+        [[ "$f" == :* ]] && pathspec+=("$f") || pathspec+=(":(glob)$f")
+    done
+    for f in ${ALLOW_INVALID_JSON[@]+"${ALLOW_INVALID_JSON[@]}"}; do
+        [[ "$f" == :* ]] && pathspec+=("$f") || pathspec+=(":(exclude,glob)$f")
+        skipped+=("$f")
+    done
+
+    local -a files=()
+    staged_files_z files "${pathspec[@]}"
+
+    for f in ${files[@]+"${files[@]}"}; do
+        [[ "$f" == *.json ]] || continue
+
+        if ! err="$(git show ":$f" | python3 -c '
+import json, sys
+try:
+    json.load(sys.stdin)
+except Exception as exc:
+    sys.stderr.write(str(exc))
+    sys.exit(1)
+' 2>&1)"; then
+            fail "$EX_JSON" \
+                "staged JSON does not parse: $f" \
+                "$err" \
+                "" \
+                "A serialization error from a generator is a STOP, not something to commit past."
+        fi
+        checked+=("$f")
+    done
+
+    for f in ${skipped[@]+"${skipped[@]}"}; do
+        log "  --  JSON check EXEMPTED by --allow-invalid-json: $f"
+    done
+    if (( ${#checked[@]} == 0 )); then
+        log "  --  no staged .json under ${JSON_PATHS[*]} — JSON check not applicable"
+    else
+        log "  ok  ${#checked[@]} staged .json file(s) under ${JSON_PATHS[*]} parse"
+    fi
+}
+
+cmd_check_staged() {
+    require_repo
+    log "push-guard: checking staged content"
+
+    check_unmerged
+
+    # --no-renames is load-bearing, NOT cosmetic. Git detects renames by default
+    # (diff.renames=true since 2.9), so a `git mv` plus a small edit is reported
+    # as ONE 'R' entry — which --diff-filter=ACM DOES NOT MATCH. The renamed file
+    # becomes invisible to every content check: staged conflict markers sail
+    # through and the guard prints "staged content OK". Verified reproducible at
+    # 97% similarity with an ordinary co-staged file present. --no-renames
+    # decomposes each rename back into D + A so the new path is always seen.
+    # (Adding R to the filter also works, but --name-only -z emits two paths for
+    # a rename and is ambiguous to parse — this removes the category instead.)
+    #
+    # SECOND INSTANCE OF THE SAME DEFECT, found by sweeping for the construct
+    # rather than fixing only the one that was reported. This one failed CLOSED
+    # (zero files hit "NOTHING IS STAGED"), so it was never a security hole --
+    # but it reported a confident WRONG DIAGNOSIS, sending anyone debugging it
+    # at their index instead of at the failing git invocation.
+    local -a files=()
+    staged_files_z files
+    if (( ${#files[@]} == 0 )); then
+        fail "$EX_NULL" \
+            "NOTHING IS STAGED" \
+            "About to commit, but the index is identical to HEAD." \
+            "" \
+            "This is the null case: a commit here is empty, and any later" \
+            "'verified' step would be asserting against content that does not exist."
+    fi
+
+    check_conflict_markers "${files[@]}"
+    check_staged_json "${files[@]}"
+
+    log "push-guard: staged content OK"
+}
+
+# ------------------------------------------------------------------------ push
+
+remote_sha() {
+    # Empty output means the branch does not exist on the remote yet.
+    # A network/auth failure makes ls-remote non-zero, which set -e turns into an
+    # abort — the guard never treats an unreachable remote as "unchanged".
+    git ls-remote "$1" "refs/heads/$2" | awk 'NR==1{print $1}'
+}
+
+cmd_push() {
+    require_repo
+    local remote="" branch="" since_head=""
+    local -a extra=()
+
+    while (( $# )); do
+        case "$1" in
+            --remote) remote="${2:-}"; shift 2 ;;
+            --branch) branch="${2:-}"; shift 2 ;;
+            --since-head) since_head="${2:-}"; shift 2 ;;
+            --) shift; extra=("$@"); break ;;
+            *) fail "$EX_USAGE" "unknown argument to push: $1" ;;
+        esac
+    done
+    [[ -n "$remote" && -n "$branch" ]] \
+        || fail "$EX_USAGE" "push requires --remote and --branch"
+
+    local head
+    head="$(git rev-parse HEAD)"
+    log "push-guard: verifying push of $head -> $remote/$branch"
+
+    # (1) Did a new commit actually get created?
+    if [[ -n "$since_head" ]]; then
+        git rev-parse --verify --quiet "${since_head}^{commit}" >/dev/null \
+            || fail "$EX_USAGE" \
+                "--since-head is not a commit in this repository: $since_head" \
+                "" \
+                "Cannot verify advancement against a start point that does not exist."
+
+        if [[ "$head" == "$since_head" ]]; then
+            fail "$EX_NULL" \
+                "HEAD DID NOT ADVANCE — no commit was created" \
+                "HEAD is still $head" \
+                "" \
+                "Your commit step failed and execution continued on stale state." \
+                "Pushing now would publish something you did not just build."
+        fi
+        # INEQUALITY IS NOT ADVANCEMENT. "different from where I started" is
+        # satisfied by checking out any unrelated commit -- including one that
+        # existed long before this session -- which would let pre-existing work
+        # be published as something just built. The claim being made is that new
+        # commits were created ON TOP OF the recorded start point, and only
+        # ancestry states that.
+        if ! git merge-base --is-ancestor "$since_head" "$head"; then
+            fail "$EX_NULL" \
+                "HEAD IS NOT A DESCENDANT of the recorded start point" \
+                "start: $since_head" \
+                "head : $head" \
+                "" \
+                "HEAD differs from the start point but does not build on it, so" \
+                "this is a checkout of other history rather than work you just" \
+                "created. Being different is not the same as having advanced."
+        fi
+        log "  ok  HEAD advanced ${since_head:0:9} -> ${head:0:9} (descendant)"
+    fi
+
+    # (2) Is that commit non-empty?
+    # EXEMPTING BY PARENT COUNT WAS A FAIL-OPEN. An empty root commit sailed
+    # through "emptiness check not applicable" and was then reported as a
+    # CONFIRMED PUSH -- directly contradicting the non-empty requirement this
+    # step exists to enforce. Root and merge commits do have well-defined
+    # emptiness; the original code declined to define it, which is not the same
+    # as it being undefined.
+    local parents
+    parents="$(git rev-list --parents -n 1 HEAD | wc -w)"
+    if (( parents == 2 )); then   # sha + exactly one parent
+        if git diff --quiet HEAD^ HEAD; then
+            fail "$EX_NULL" \
+                "HEAD IS AN EMPTY COMMIT — it changes nothing against its parent" \
+                "commit $head" \
+                "" \
+                "An empty commit carrying a real message is indistinguishable" \
+                "from real work in the log. Refusing to push it."
+        fi
+        log "  ok  HEAD is a non-empty commit"
+    elif (( parents > 2 )); then
+        # A merge is empty when its tree matches EVERY parent: it then carries
+        # no content of its own and no integration either.
+        local p all_same=yes
+        for p in $(git rev-list --parents -n 1 HEAD | cut -d' ' -f2-); do
+            git diff --quiet "$p" HEAD || { all_same=no; break; }
+        done
+        if [[ "$all_same" == yes ]]; then
+            fail "$EX_NULL" \
+                "HEAD IS AN EMPTY MERGE — its tree is identical to every parent" \
+                "commit $head" \
+                "" \
+                "It integrates nothing and introduces nothing. Refusing to push it."
+        fi
+        log "  ok  HEAD is a non-empty merge commit"
+    else
+        # A root commit has no parent, so emptiness is measured against the
+        # empty tree: it is empty when it adds no paths at all.
+        if [[ -z "$(git diff-tree --root -r --name-only --no-commit-id HEAD)" ]]; then
+            fail "$EX_NULL" \
+                "HEAD IS AN EMPTY ROOT COMMIT — it introduces no files" \
+                "commit $head" \
+                "" \
+                "A root commit is empty when it adds nothing against the empty" \
+                "tree. Refusing to push it."
+        fi
+        log "  ok  HEAD is a non-empty root commit"
+    fi
+
+    # (3) Capture the remote BEFORE. This is the step whose absence made the
+    #     original "PUSH VERIFIED" a false positive.
+    local before after
+    before="$(remote_sha "$remote" "$branch")"
+    log "  ..  remote before: ${before:-<branch does not exist>}"
+
+    git push "$remote" "HEAD:refs/heads/$branch" ${extra[@]+"${extra[@]}"}
+
+    after="$(remote_sha "$remote" "$branch")"
+    log "  ..  remote after:  ${after:-<absent>}"
+
+    # (4) The remote must now equal local HEAD...
+    if [[ "$after" != "$head" ]]; then
+        fail "$EX_PUSH" \
+            "REMOTE DOES NOT MATCH LOCAL HEAD after push" \
+            "local HEAD:    $head" \
+            "remote $branch: ${after:-<absent>}" \
+            "" \
+            "The push did not land what you are holding."
+    fi
+    # (5) ...AND it must have MOVED to get there. Without this, a push that
+    #     transferred nothing passes step (4) trivially.
+    if [[ "$after" == "$before" ]]; then
+        fail "$EX_PUSH" \
+            "REMOTE DID NOT MOVE — nothing was actually pushed" \
+            "remote was already at $after before this push ran" \
+            "" \
+            "'remote == local' is satisfied by having pushed nothing. That is" \
+            "the false positive this guard exists to catch: the work you think" \
+            "you just published was already there, or was never committed."
+    fi
+
+    log "push-guard: PUSH CONFIRMED ${before:0:9}${before:+ }-> ${after:0:9}"
+}
+
+# ------------------------------------------------------------------------ main
+
+ALLOW_INVALID_JSON=()
+JSON_PATHS=()
+
+CFG_MODE="absent"
+CFG_REASON=""
+CFG_PATHS=()
+CFG_ALLOW=()
+
+main() {
+    (( $# )) || { usage; exit "$EX_USAGE"; }
+    local sub="$1"; shift
+    case "$sub" in
+        check-staged)
+            while (( $# )); do
+                case "$1" in
+                    --json-path)          JSON_PATHS+=("${2:-}"); shift 2 ;;
+                    --allow-invalid-json) ALLOW_INVALID_JSON+=("${2:-}"); shift 2 ;;
+                    *) fail "$EX_USAGE" "unknown argument to check-staged: $1" ;;
+                esac
+            done
+            cmd_check_staged
+            ;;
+        push)        cmd_push "$@" ;;
+        -h|--help)   usage ;;
+        *)           usage; exit "$EX_USAGE" ;;
+    esac
+    # Explicit: the only way to reach here is with every requested check passed.
+    exit "$EX_OK"
+}
+
+main "$@"

packages/mosaic/framework/tools/git/test-ci-queue-wait-parse.sh

@@ -0,0 +1,205 @@
+#!/usr/bin/env bash
+# Regression suite for #1019: ci-queue-wait.sh's status parser must return a
+# state DERIVED FROM ITS INPUT.
+#
+# The defect this pins: both python sites piped a payload into `python3 - <<'PY'`.
+# The heredoc binds stdin to the Python program text, so json.load(sys.stdin) saw
+# EOF, the bare `except` fired, and the function returned "unknown" for every input
+# — success, pending and failure alike. "unknown" then reaches an `exit 0` arm, so
+# the gate-6 queue guard passed unconditionally on both the gitea and github paths.
+#
+# Every assertion below is on the RETURNED STATE STRING. A test that asserted only
+# `rc=0` would have passed against the broken build, which is why this bug survived.
+#
+# The functions are extracted from the shipped wrapper rather than reimplemented, so
+# this suite measures the code that actually runs.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Overridable so a mutation test can point the suite at a deliberately-broken copy
+# without touching the tracked file. The earlier version of this suite required
+# `git stash` + `git checkout` to do that, which left a repo-global stash entry
+# that any sibling worktree could have popped onto an unrelated branch.
+WRAPPER="${CI_QUEUE_WAIT_WRAPPER:-$SCRIPT_DIR/ci-queue-wait.sh}"
+
+PASS=0
+FAIL=0
+
+pass() { printf '  PASS  %s\n' "$1"; PASS=$((PASS + 1)); }
+fail() { printf '  FAIL  %s\n' "$1"; FAIL=$((FAIL + 1)); }
+
+if [[ ! -f "$WRAPPER" ]]; then
+    printf 'FATAL: wrapper not found at %s\n' "$WRAPPER" >&2
+    exit 1
+fi
+
+TMPDIR_T="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR_T"' EXIT
+
+extract_fn() {
+    # $1 = function name, $2 = source file, $3 = destination
+    sed -n "/^$1()/,/^}/p" "$2" > "$3"
+    [[ -s "$3" ]] || { printf 'FATAL: could not extract %s from %s\n' "$1" "$2" >&2; exit 1; }
+}
+
+extract_fn get_state_from_status_json "$WRAPPER" "$TMPDIR_T/state.sh"
+extract_fn print_pending_contexts     "$WRAPPER" "$TMPDIR_T/contexts.sh"
+
+state_of() {
+    # shellcheck disable=SC1091
+    ( source "$TMPDIR_T/state.sh"; printf '%s' "$1" | get_state_from_status_json )
+}
+
+expect_state() {
+    local label="$1" payload="$2" want="$3" got
+    got="$(state_of "$payload")"
+    if [[ "$got" == "$want" ]]; then
+        pass "$label -> $want"
+    else
+        fail "$label -> got '$got', want '$want'"
+    fi
+}
+
+echo "=== parser returns a state derived from its input (#1019) ==="
+
+expect_state "success payload" \
+    '{"state":"success","statuses":[{"status":"success","context":"ci/build"}]}' \
+    'terminal-success'
+
+expect_state "pending payload" \
+    '{"state":"pending","statuses":[{"status":"pending","context":"ci/build"}]}' \
+    'pending'
+
+expect_state "failure payload" \
+    '{"state":"failure","statuses":[{"status":"failure","context":"ci/build"}]}' \
+    'terminal-failure'
+
+expect_state "mixed success+pending is pending" \
+    '{"state":"pending","statuses":[{"status":"success"},{"status":"pending"}]}' \
+    'pending'
+
+expect_state "running counts as pending" \
+    '{"state":"pending","statuses":[{"status":"running"}]}' \
+    'pending'
+
+expect_state "error counts as failure" \
+    '{"state":"failure","statuses":[{"status":"error"}]}' \
+    'terminal-failure'
+
+expect_state "empty status set is no-status" \
+    '{"state":"","statuses":[]}' \
+    'no-status'
+
+# Control. This is the ONE input for which "unknown" is correct. Without it, a
+# regression that hardcoded "unknown" again would still fail the cases above but
+# the suite would give no signal that "unknown" remains reachable when it should be.
+expect_state "undecodable payload stays unknown" \
+    'not json at all' \
+    'unknown'
+
+expect_state "unrecognised status vocabulary is unknown" \
+    '{"state":"weird","statuses":[{"status":"weird"}]}' \
+    'unknown'
+
+echo "=== pending contexts are reported to the operator ==="
+
+contexts_of() {
+    # shellcheck disable=SC1091
+    ( source "$TMPDIR_T/contexts.sh"; printf '%s' "$1" | print_pending_contexts )
+}
+
+out="$(contexts_of '{"statuses":[{"status":"pending","context":"ci/alpha"},{"status":"pending","context":"ci/beta"}]}')"
+if grep -q 'ci/alpha' <<<"$out" && grep -q 'ci/beta' <<<"$out"; then
+    pass "both pending contexts emitted"
+else
+    fail "pending contexts not emitted; got: $out"
+fi
+
+out="$(contexts_of '{"statuses":[{"status":"success","context":"ci/alpha"}]}')"
+# Assert the POSITIVE message, not merely the absence of the context name. Absence
+# alone is satisfied by total silence — and the pre-fix build was silent, so an
+# absence-only assertion passed against the very defect this suite exists to catch.
+if grep -q 'ci/alpha' <<<"$out"; then
+    fail "a non-pending context was emitted; got: $out"
+elif grep -q 'no pending contexts' <<<"$out"; then
+    pass "non-pending context suppressed, and reported as 'no pending contexts'"
+else
+    fail "expected an explicit 'no pending contexts' report; got: $out"
+fi
+
+echo "=== needle: the broken construct is caught, not merely absent today ==="
+
+# Rebuild the pre-fix form and assert this suite would have failed against it.
+# Without this, the suite proves the current file is correct but not that it can
+# detect the defect returning.
+BROKEN="$TMPDIR_T/broken.sh"
+cat > "$BROKEN" <<'BROKEN_EOF'
+get_state_from_status_json() {
+    python3 - <<'PY'
+import json
+import sys
+
+try:
+    payload = json.load(sys.stdin)
+except Exception:
+    print("unknown")
+    raise SystemExit(0)
+print("terminal-success" if (payload.get("state") or "") == "success" else "pending")
+PY
+}
+BROKEN_EOF
+
+broken_got="$( ( source "$BROKEN"; printf '%s' '{"state":"success","statuses":[]}' | get_state_from_status_json ) )"
+if [[ "$broken_got" == "unknown" ]]; then
+    pass "[NEEDLE ] pre-fix construct reproduces the defect (returns 'unknown' for a success payload)"
+else
+    fail "[NEEDLE ] pre-fix construct did NOT reproduce the defect; got '$broken_got' — the needle no longer pins anything"
+fi
+
+# And assert the shipped wrapper does not contain that construct.
+#
+# The check must have HEREDOC SEMANTICS, not merely match the text. `json.load(sys.stdin)`
+# is perfectly correct under `python3 -c '...'` — there the program comes from argv, so
+# stdin really is the payload, and ci-queue-wait.sh uses that form legitimately in
+# gitea_get_branch_head_sha. Only `python3 - <<DELIM` is defective, because `-` has
+# already bound stdin to the program text.
+#
+# A flat `grep json\.load\(sys\.stdin\)` therefore fails on correct code. It did: the
+# first version of this needle flagged the innocent `python3 -c` site. Same shape as
+# #1018 F1 (a regex over raw text has no syntax semantics) reproduced inside the needle
+# written to pin a different instance of it.
+heredoc_stdin_sites() {
+    awk '
+        /python3[[:space:]]+-[[:space:]]*<</ {
+            d = $0
+            sub(/.*<<[[:space:]]*/, "", d)
+            gsub(/['"'"'"]/, "", d)
+            delim = d; inhd = 1; next
+        }
+        inhd && $0 == delim { inhd = 0; next }
+        inhd {
+            line = $0
+            sub(/[[:space:]]*#.*$/, "", line)
+            if (line ~ /sys\.stdin/) printf "%d: %s\n", FNR, $0
+        }
+    ' "$1"
+}
+
+# Positive control FIRST. An empty result from a broken scanner looks exactly like a
+# clean file, so the scanner is proven to fire before its silence is trusted.
+if [[ -n "$(heredoc_stdin_sites "$BROKEN")" ]]; then
+    pass "[NEEDLE ] scanner detects a stdin read inside a python3-heredoc"
+else
+    fail "[NEEDLE ] scanner did NOT fire on the known-broken form — its silence proves nothing"
+fi
+
+sites="$(heredoc_stdin_sites "$WRAPPER")"
+if [[ -n "$sites" ]]; then
+    fail "[NEEDLE ] wrapper reads stdin inside a python3-heredoc at: $sites"
+else
+    pass "[NEEDLE ] wrapper has no stdin read inside any python3-heredoc"
+fi
+
+printf '\nci-queue-wait parse: %d passed, %d failed\n' "$PASS" "$FAIL"
+[[ "$FAIL" -eq 0 ]] || exit 1

packages/mosaic/framework/tools/git/test-mutate-push-guard.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# test-mutate-push-guard.sh -- needles for the mutation generator.
+#
+# The generator's entire output is a COVERAGE CLAIM, and the README publishes it.
+# That makes it the most dangerous file here: when it is wrong it does not fail,
+# it reassures. Two of its three defects were found by review rather than by any
+# test, so these are the cases that had to exist.
+#
+#   g1  a RED BASELINE must be refused before any mutant runs. Previously ONE
+#       pre-existing suite failure -- changing no guard behaviour at all --
+#       satisfied every mutant: 13 killed, 0 survived, table emitted, exit 0.
+#   g3  an INTERRUPTED run must leave the subject byte-identical. Restoration
+#       used to lean on an EXIT trap, and A TRAP IS CLEANUP, NOT ISOLATION:
+#       SIGKILL cannot run it, so an interrupted run stranded a mutated
+#       push-guard.sh that the next suite run silently inherited.
+#   g2  is the positive control. Without it every case here could be passing
+#       because the generator refuses unconditionally, which is a wall, not a gate.
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+GEN="$HERE/mutate-push-guard.sh"
+PASS=0; FAIL=0
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+
+ok()   { printf '  ok    [%-16s] %s\n' "$1" "${2:-}"; PASS=$(( PASS + 1 )); }
+bad()  { printf '  FAIL  [%-16s] %s\n' "$1" "$2"; FAIL=$(( FAIL + 1 )); }
+
+# fixture <name> -- a directory holding an independent copy of guard + suite
+fixture() {
+    local d="$TMP/$1"; mkdir -p "$d"
+    install -m 755 "$HERE/push-guard.sh"      "$d/push-guard.sh"
+    install -m 755 "$HERE/test-push-guard.sh" "$d/test-push-guard.sh"
+    printf '%s\n' "$d"
+}
+
+echo "== g1: a RED BASELINE must be refused, with NO table emitted =="
+# The injected case asserts exit 99 from `true`. It fails always, and it changes
+# NO guard behaviour -- which is the whole point: a defect anywhere in the suite
+# used to be enough to certify every branch as covered.
+g1="$(fixture red)"
+python3 - "$g1/test-push-guard.sh" <<'PY'
+import sys
+p = sys.argv[1]; s = open(p).read()
+anchor = 'mkdir -p "$WORK_DIR"\n'
+assert s.count(anchor) == 1, "injection anchor not unique -- fixture would not be the red baseline"
+s = s.replace(anchor, anchor + '\nexpect NEEDLE 99 "injected always-failing case" -- true\n', 1)
+open(p, "w").write(s)
+PY
+# Prove the fixture really IS red before asserting the generator notices, or g1
+# could pass against a green suite and test nothing.
+if "$g1/test-push-guard.sh" >/dev/null 2>&1; then
+    bad g1-fixture "injected suite still passes -- fixture is not a red baseline"
+else
+    ok g1-fixture "fixture suite is red, as required"
+fi
+out="$("$GEN" --dir "$g1" 2>&1)"; rc=$?
+if (( rc != 0 )) && [[ "$out" == *"REFUSING: baseline is not green"* ]]; then
+    ok g1-refused "exit $rc, refused before mutating"
+else
+    bad g1-refused "wanted nonzero + refusal; got rc=$rc"
+fi
+if [[ "$out" != *"README TABLE"* && "$out" != *"killed,"* ]]; then
+    ok g1-no-table "no coverage table emitted from a red baseline"
+else
+    bad g1-no-table "a table or kill count was published despite the red baseline"
+fi
+
+echo
+echo "== g3: an INTERRUPTED run must not alter the subject =="
+# THE KILL MUST LAND INSIDE A MUTATION WINDOW OR THIS CASE PROVES NOTHING.
+# First attempt used `timeout -s KILL 3`. At three seconds the generator is still
+# running its BASELINE, so no mutation has been applied yet and the subject is
+# trivially unchanged -- for the ORIGINAL in-place generator too, which I
+# confirmed by running it. The control passed for a reason unrelated to the fix:
+# a vacuous control, in the control written for blocker 3.
+#
+# So the kill is now driven from INSIDE the run. The fixture's suite counts its
+# own invocations and SIGKILLs the generator on the second one -- invocation 1 is
+# the baseline, invocation 2 happens with mutant #1 APPLIED. That is exactly the
+# window where an in-place generator strands a mutated subject.
+instrument_kill_at_second_run() {
+    python3 - "$1" <<'PY'
+import sys
+p = sys.argv[1]; s = open(p).read()
+anchor = 'PASS=0\nFAIL=0\n'
+assert s.count(anchor) == 1, "instrumentation anchor not unique"
+inject = anchor + '''
+if [[ -n "${G3_COUNTER:-}" ]]; then
+    n=$(( $(cat "$G3_COUNTER" 2>/dev/null || echo 0) + 1 ))
+    printf '%s' "$n" > "$G3_COUNTER"
+    # Invocation 2 = first mutant applied. Kill the generator where it hurts.
+    # `kill -9 0` targets the whole PROCESS GROUP, not $PPID: the generator runs
+    # the suite inside $( ), which forks, so $PPID is that subshell and killing
+    # it merely ends the command substitution -- the generator carries on and
+    # exits 0. The caller puts the generator in its OWN group via setsid, so the
+    # group is exactly the generator and its children, and this harness is not
+    # in it.
+    (( n == 2 )) && kill -9 0
+fi
+'''
+open(p, "w").write(s.replace(anchor, inject, 1))
+PY
+}
+
+# run_killed <dir> -> echoes "<rc> <before> <after>"
+run_killed() {
+    local d="$1" gen="$2" before after rc
+    instrument_kill_at_second_run "$d/test-push-guard.sh"
+    before="$(sha256sum "$d/push-guard.sh" | cut -d' ' -f1)"
+    G3_COUNTER="$d/.count" setsid --wait "$gen" --dir "$d" >/dev/null 2>&1; rc=$?
+    after="$(sha256sum "$d/push-guard.sh" | cut -d' ' -f1)"
+    printf '%s %s %s\n' "$rc" "$before" "$after"
+}
+
+g3="$(fixture killed)"
+read -r krc before after <<<"$(run_killed "$g3" "$GEN")"
+if (( krc != 0 )); then
+    ok g3-was-killed "generator died mid-mutation (exit $krc)"
+else
+    bad g3-was-killed "generator exited 0 -- the kill never landed, so the check below is vacuous"
+fi
+if [[ "$before" == "$after" ]]; then
+    ok g3-subject-intact "push-guard.sh byte-identical after the kill"
+else
+    bad g3-subject-intact "SUBJECT MUTATED AND STRANDED: $before -> $after"
+fi
+
+# PROVE THE NEEDLE BITES. Reconstruct the pre-fix mechanism -- mutate the source
+# in place, restore from an EXIT trap -- and put it through the identical kill.
+# If this does NOT strand a mutated file, g3-subject-intact is measuring nothing
+# and the isolation fix is unevidenced.
+g3o="$(fixture killed-inplace)"
+python3 - "$GEN" "$g3o/gen-inplace.sh" <<'PY'
+import sys
+s = open(sys.argv[1]).read()
+old = '''install -m 755 "$SRC_TARGET" "$WORK/push-guard.sh"
+install -m 755 "$SRC_SUITE"  "$WORK/test-push-guard.sh"
+TARGET="$WORK/push-guard.sh"
+SUITE="$WORK/test-push-guard.sh"
+BAK="$WORK/push-guard.sh.orig"
+cp "$TARGET" "$BAK"'''
+new = '''TARGET="$SRC_TARGET"
+SUITE="$SRC_SUITE"
+BAK="$WORK/push-guard.sh.orig"
+cp "$TARGET" "$BAK"
+trap 'cp "$BAK" "$TARGET"; rm -rf "$WORK"' EXIT'''
+assert s.count(old) == 1, "cannot reconstruct the in-place mechanism -- bite proof would be fake"
+open(sys.argv[2], "w").write(s.replace(old, new, 1))
+PY
+chmod +x "$g3o/gen-inplace.sh"
+read -r _orc obefore oafter <<<"$(run_killed "$g3o" "$g3o/gen-inplace.sh")"
+if [[ "$obefore" != "$oafter" ]]; then
+    ok g3-needle-bites "in-place generator strands a mutated subject, as it must"
+else
+    bad g3-needle-bites "the OLD mechanism also left the subject intact -- g3 is vacuous"
+fi
+
+echo
+echo "== g2: POSITIVE CONTROL -- a clean subject must produce a full green run =="
+g2="$(fixture clean)"
+out2="$("$GEN" --dir "$g2" 2>&1)"; rc2=$?
+if (( rc2 == 0 )) && [[ "$out2" == *"0 survived"* ]]; then
+    ok g2-control "$(printf '%s' "$out2" | grep -E '^[0-9]+ killed')"
+else
+    bad g2-control "wanted exit 0 with 0 survived; got rc=$rc2"
+fi
+# A kill must be attributed to a NAMED case, not to a bare tally -- that is the
+# fix for blocker 2 and it needs its own assertion.
+if [[ "$out2" == *"             by: "* ]]; then
+    ok g2-attributed "kills name the case they broke"
+else
+    bad g2-attributed "no per-mutant case attribution in the output"
+fi
+
+echo
+printf '%d passed, %d failed\n' "$PASS" "$FAIL"
+(( FAIL == 0 ))

packages/mosaic/framework/tools/git/test-pr-review-gitea-comment.sh

@@ -58,6 +58,9 @@ CREDENTIALS_FILE="$WORK_DIR/credentials.json"
 # A dedicated scratch dir the wrapper is pointed at via TMPDIR, so the leak
 # check can assert every POST/GET body + metadata temp file is cleaned up.
 TMP_SCRATCH="$WORK_DIR/scratch"
+# Sandboxed HOME so nothing under the real $HOME (notably the per-slot Gitea token
+# store at ~/.config/mosaic/secrets/gitea-tokens/) is reachable from the wrapper.
+HOME_DIR="$WORK_DIR/home"
 
 cleanup() {
     rm -rf "$WORK_DIR"
@@ -78,9 +81,18 @@ OVERRIDE_TOKEN="override-token-placeholder"
 CROSS_HOST_LOGIN="foreign-host-reviewer"
 CROSS_HOST_TOKEN="cross-host-token-placeholder"
 
-mkdir -p "$REPO_DIR" "$BIN_DIR" "$XDG_DIR" "$STATE_DIR" "$TMP_SCRATCH"
+mkdir -p "$REPO_DIR" "$BIN_DIR" "$XDG_DIR" "$STATE_DIR" "$TMP_SCRATCH" "$HOME_DIR"
 git -C "$REPO_DIR" init -q
 git -C "$REPO_DIR" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
+# HERMETICITY: get_gitea_token() step 0 resolves a per-agent identity from
+# `git config --get mosaic.gitIdentity`, which on a provisioned agent seat is set
+# GLOBALLY and therefore leaks into this fresh repo. It then reads a REAL per-slot
+# token from $HOME and returns it WITHOUT ever consulting MOSAIC_CREDENTIALS_FILE,
+# so the fixture credentials below are silently ignored and the suite runs against
+# production credentials. An empty repo-local value shadows the global one and reads
+# back as empty at rc=0, restoring the shared-credential path this suite intends to
+# exercise. Paired with the sandboxed HOME in run_review().
+git -C "$REPO_DIR" config mosaic.gitIdentity ""
 
 # tea config: the override login carries its own token here. The default login
 # name ("mosaicstack") is deliberately absent, so the no-override default path
@@ -266,6 +278,24 @@ submitted = json.loads(os.environ["PR_REVIEW_PAYLOAD"])
 with open(state_path, encoding="utf-8") as handle:
     reviews = json.load(handle)
 
+# review-refused-422 (#1004): the server REFUSES the submit outright with a
+# definite, correct, machine-readable reason in the body — the shape Gitea
+# returns when the acting credential authored the PR. Nothing is created. The
+# wrapper must surface what the server said and must NOT relabel this as the
+# #865 silent-no-op defect class, which is precisely what it is not.
+if mode == "review-refused-422":
+    print("422")
+    print(json.dumps({"message": "Cannot approve your own pull request"}))
+    raise SystemExit(0)
+
+# review-refused-html (#1004): a non-JSON error body, as a fronting proxy or
+# gateway emits. The detail extraction must degrade to the first raw line rather
+# than silently dropping the only explanation available.
+if mode == "review-refused-html":
+    print("502")
+    print("<html><head><title>502 Bad Gateway</title></head>\n<body>nginx</body></html>")
+    raise SystemExit(0)
+
 # no-op-concurrent-review: the wrapper's own submit is SUPPRESSED (200, no
 # created object) even though a concurrent same-identity, same-state review at
 # the same head already exists. Nothing is persisted; no created id to verify.
@@ -517,6 +547,8 @@ run_review() {
         cd "$REPO_DIR"
         PATH="$BIN_DIR:$PATH" \
         TMPDIR="$TMP_SCRATCH" \
+        HOME="$HOME_DIR" \
+        MOSAIC_GIT_IDENTITY="" \
         XDG_CONFIG_HOME="$XDG_DIR" \
         MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
         PR_REVIEW_TEA_LOG="$TEA_LOG" \
@@ -940,4 +972,44 @@ if grep -q 'Approved and verified' "$OUTPUT_FILE"; then
 fi
 assert_no_temp_leak "review-body-null"
 
+# Case 19 (#1004): an outright server REFUSAL must report the provider's own
+# reason and must NOT be relabelled as the #865 silent-no-op defect class. The
+# old arm hardcoded "(#865: no durable review created)" for EVERY non-2xx, so a
+# 422/403/404 — all of them definite, correct refusals the server explained in
+# the discarded body — arrived at the caller wearing the name of the one defect
+# they are not. That misdirection is what makes an operator re-issue the request
+# by hand against the live object to find out what actually happened.
+if run_review review-refused-422 approve; then
+    echo "FAIL: approve reported success when the server refused the submit" >&2
+    cat "$OUTPUT_FILE" >&2
+    exit 1
+fi
+grep -q 'HTTP 422' "$OUTPUT_FILE"
+if ! grep -q 'Cannot approve your own pull request' "$OUTPUT_FILE"; then
+    echo "FAIL: the provider's stated reason was discarded (#1004)" >&2
+    cat "$OUTPUT_FILE" >&2
+    exit 1
+fi
+if grep -q '#865: no durable review created' "$OUTPUT_FILE"; then
+    echo "FAIL: a server refusal was misattributed to the #865 defect class (#1004)" >&2
+    cat "$OUTPUT_FILE" >&2
+    exit 1
+fi
+assert_no_temp_leak "review-refused-422"
+
+# Case 20 (#1004): a non-JSON error body (a fronting proxy's HTML page) must
+# still yield something the caller can act on, rather than a bare status code.
+if run_review review-refused-html approve; then
+    echo "FAIL: approve reported success on a 502" >&2
+    cat "$OUTPUT_FILE" >&2
+    exit 1
+fi
+grep -q 'HTTP 502' "$OUTPUT_FILE"
+if ! grep -q '502 Bad Gateway' "$OUTPUT_FILE"; then
+    echo "FAIL: a non-JSON error body was dropped instead of degrading to its first line (#1004)" >&2
+    cat "$OUTPUT_FILE" >&2
+    exit 1
+fi
+assert_no_temp_leak "review-refused-html"
+
 echo "pr-review.sh REST review + comment create/read-back regression passed"

packages/mosaic/framework/tools/git/test-push-guard.sh

@@ -0,0 +1,659 @@
+#!/usr/bin/env bash
+# test-push-guard.sh - Needle harness for push-guard.sh.
+#
+# Every check gets BOTH polarities:
+#   NEEDLE   a deliberately-broken fixture that MUST trip the guard.
+#   CONTROL  a clean fixture that MUST pass.
+#
+# The controls are not decoration. A guard that failed unconditionally would
+# satisfy every needle and look fully covered — which is the same class of defect
+# (an assertion satisfied by the null case) that push-guard.sh exists to prevent.
+# A needle set without controls cannot tell "working guard" from "broken guard".
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+GUARD="$SCRIPT_DIR/push-guard.sh"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$SCRIPT_DIR/.work}"
+
+PASS=0
+FAIL=0
+
+# Fresh repo + bare "remote" for each case, so no case can inherit another's state.
+new_repo() {
+    local name="$1"
+    local dir="$WORK_DIR/$name"
+    rm -rf "$dir"
+    mkdir -p "$dir"
+    git init -q -b main "$dir/repo"
+    git init -q --bare "$dir/remote.git"
+    git -C "$dir/repo" remote add origin "$dir/remote.git"
+    git -C "$dir/repo" config user.name "Needle Harness"
+    git -C "$dir/repo" config user.email "[email protected]"
+    printf 'seed\n' > "$dir/repo/seed.txt"
+    git -C "$dir/repo" add seed.txt
+    git -C "$dir/repo" commit -q -m "seed"
+    printf '%s' "$dir/repo"
+}
+
+# write_config <repo> <json-text>
+#
+# THIS HELPER USED TO WRITE THE CONFIG UNTRACKED, and the comment that lived here
+# justified it ("does not need to be staged"). That made every opt-out control in
+# this file assert the FORBIDDEN provenance and pass — a control that does not
+# merely test nothing, but tests the OPPOSITE of the requirement and goes green.
+# The whole design is: ON from anywhere, OFF only from a committed reviewable
+# artifact. A harness that opts out from an untracked file was proving the bypass
+# worked. It now COMMITS, so the opt-out controls exercise the supported path.
+write_config() {
+    printf '%s\n' "$2" > "$1/.push-guard.json"
+    git -C "$1" add .push-guard.json
+    git -C "$1" commit -q -m "push-guard config"
+}
+
+# write_config_untracked <repo> <json-text>
+# Deliberately NOT committed — used only where the untracked config is the thing
+# under test and the expected outcome is a REFUSAL.
+write_config_untracked() {
+    printf '%s\n' "$2" > "$1/.push-guard.json"
+}
+
+# expect <kind> <expected_exit> <description> [--out <substring>] -- <command...>
+#
+# --out asserts a substring of the guard's own output. It exists because exit 0
+# alone cannot distinguish "checked the files and they were fine" from "matched
+# no files and had nothing to check". Two controls in an earlier revision of this
+# harness were passing vacuously for exactly that reason — the pathspec silently
+# matched nothing. A control that cannot fail is not a control.
+expect() {
+    local kind="$1" want="$2" desc="$3"; shift 3
+    local need_out=""
+    while (( $# )); do
+        case "$1" in
+            --out) need_out="$2"; shift 2 ;;
+            --)    shift; break ;;
+            *)     break ;;
+        esac
+    done
+    local got=0 out
+    out="$("$@" 2>&1)" || got=$?
+
+    local why=""
+    [[ "$got" == "$want" ]] || why="wanted exit $want, got $got"
+    if [[ -z "$why" && -n "$need_out" && "$out" != *"$need_out"* ]]; then
+        why="exit $got as expected, but output never said: $need_out"
+    fi
+
+    if [[ -z "$why" ]]; then
+        printf '  PASS  [%-7s] %s (exit %s)\n' "$kind" "$desc" "$got"
+        PASS=$((PASS + 1))
+    else
+        printf '  FAIL  [%-7s] %s — %s\n' "$kind" "$desc" "$why"
+        printf '%s\n' "$out" | sed 's/^/          | /'
+        FAIL=$((FAIL + 1))
+    fi
+}
+
+rm -rf "$WORK_DIR"
+mkdir -p "$WORK_DIR"
+
+echo "=== (a) conflict markers / unmerged index ==="
+
+# NEEDLE: staged content carrying real conflict markers.
+R="$(new_repo a1)"
+cat > "$R/conflicted.txt" <<'EOF'
+intro line
+<<<<<<< HEAD
+ours
+=======
+theirs
+>>>>>>> feature/x
+tail line
+EOF
+git -C "$R" add conflicted.txt
+expect NEEDLE 2 "staged conflict markers are refused" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# NEEDLE: a genuine unmerged index (merge in progress).
+R="$(new_repo a2)"
+git -C "$R" checkout -q -b other
+printf 'from-other\n' > "$R/clash.txt"
+git -C "$R" add clash.txt && git -C "$R" commit -q -m other
+git -C "$R" checkout -q main
+printf 'from-main\n' > "$R/clash.txt"
+git -C "$R" add clash.txt && git -C "$R" commit -q -m main
+git -C "$R" merge other -q >/dev/null 2>&1 || true
+expect NEEDLE 2 "unmerged index paths are refused" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# CONTROL: ordinary staged content passes.
+# The config is REQUIRED as of the decision gate: this fixture has no generated
+# JSON, so it records that fact with a reason. This is the migration cost of the
+# hard cutover, paid here first — these two controls were the only pre-existing
+# cases that reached the JSON stage without nominating a path, and they are
+# exactly the "repo that never wired it up" the gate now refuses.
+R="$(new_repo a3)"
+write_config "$R" '{"json_check": "none", "reason": "fixture has no generated JSON"}'
+printf 'just some code\n' > "$R/clean.txt"
+git -C "$R" add clean.txt
+expect CONTROL 0 "clean staged content passes (1 file actually scanned)" \
+    --out "no conflict markers in 1 staged file(s)" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# CONTROL (false-positive guard): prose using ======= as an underline must NOT trip.
+# This is why the marker pattern deliberately ignores a bare '======='.
+R="$(new_repo a4)"
+write_config "$R" '{"json_check": "none", "reason": "fixture has no generated JSON"}'
+cat > "$R/README.rst" <<'EOF'
+Section Title
+=============
+
+Body text.
+
+Another Heading
+=======
+EOF
+git -C "$R" add README.rst
+expect CONTROL 0 "prose using ======= underlines does not trip the guard" \
+    --out "no conflict markers in 1 staged file(s)" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# NEEDLE (fault injection): if the scan itself ERRORS, the guard must refuse
+# rather than report a clean result. git grep exits 1 for "no match" but >=2 for
+# a real failure; a blanket '|| true' would collapse the two. We inject the
+# failure with a PATH shim rather than trying to corrupt an index.
+R="$(new_repo a5)"
+SHIM="$WORK_DIR/a5/bin"
+mkdir -p "$SHIM"
+REAL_GIT="$(command -v git)"
+cat > "$SHIM/git" <<SH
+#!/usr/bin/env bash
+if [[ "\$1" == "grep" ]]; then exit 2; fi
+exec "$REAL_GIT" "\$@"
+SH
+chmod +x "$SHIM/git"
+printf 'ordinary content\n' > "$R/thing.txt"
+git -C "$R" add thing.txt
+expect NEEDLE 2 "a conflict scan that ERRORS is refused, not reported clean" \
+    --out "did not run" -- \
+    bash -c "cd '$R' && export PATH=\"$SHIM:\$PATH\" && '$GUARD' check-staged"
+
+# NEEDLE: RENAME + MODIFY. Git reports a `git mv` plus a small edit as a single
+# 'R' entry, which --diff-filter=ACM does not match, making the file invisible to
+# every content check. A clean file is co-staged deliberately: without it the
+# file list is empty and the nothing-staged guard fires by ACCIDENT, which would
+# make this needle pass for the wrong reason and hide the real defect.
+R="$(new_repo a6)"
+mkdir -p "$R/data"
+seq 1 200 | sed 's/^/line /' > "$R/data/canon.txt"
+printf 'original\n' > "$R/other.txt"
+git -C "$R" add -A && git -C "$R" commit -q -m seed
+git -C "$R" mv data/canon.txt data/canon2.txt
+printf '<<<<<<< HEAD\nours\n=======\ntheirs\n>>>>>>> b\n' >> "$R/data/canon2.txt"
+printf 'an ordinary innocent change\n' > "$R/other.txt"
+git -C "$R" add -A
+expect NEEDLE 2 "conflict markers in a RENAMED file are refused (rename+modify)" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# NEEDLE: a path marked binary in .gitattributes. `git grep -I` honours that
+# classification and skips the blob entirely while the summary still counts the
+# file as scanned — a clean pass AND a false count. Hence -a, not -I.
+R="$(new_repo a7)"
+printf 'notes.txt binary\n' > "$R/.gitattributes"
+printf 'x\n<<<<<<< HEAD\nours\n=======\ntheirs\n>>>>>>> b\ny\n' > "$R/notes.txt"
+git -C "$R" add -A
+expect NEEDLE 2 "conflict markers in a .gitattributes-binary file are refused" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+echo "=== (c) staged JSON parses ==="
+
+# NEEDLE: malformed JSON, the shape a broken generator emits.
+R="$(new_repo c1)"
+mkdir -p "$R/data"
+printf '{"a": 1,\n' > "$R/data/broken.json"
+git -C "$R" add data/broken.json
+expect NEEDLE 3 "staged unparseable JSON under --json-path is refused" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged --json-path 'data/**/*.json'"
+
+# NEEDLE: conflict markers inside a generated JSON file — the 70-file incident.
+R="$(new_repo c2)"
+mkdir -p "$R/data"
+cat > "$R/data/canon.json" <<'EOF'
+{
+<<<<<<< HEAD
+  "v": 1
+=======
+  "v": 2
+>>>>>>> main
+}
+EOF
+git -C "$R" add data/canon.json
+expect NEEDLE 2 "conflict markers in generated JSON are refused" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# CONTROL: valid JSON passes.
+R="$(new_repo c3)"
+mkdir -p "$R/data"
+printf '{"a": 1, "b": [2, 3]}\n' > "$R/data/good.json"
+git -C "$R" add data/good.json
+expect CONTROL 0 "valid staged JSON passes (and was actually parsed)" \
+    --out "1 staged .json file(s)" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged --json-path 'data/**/*.json'"
+
+# CONTROL: an explicit exemption works (and is reported, never silent).
+R="$(new_repo c4)"
+mkdir -p "$R/fixtures"
+printf 'not json at all' > "$R/fixtures/malformed.json"
+git -C "$R" add fixtures/malformed.json
+expect CONTROL 0 "deliberate malformed fixture can be exempted (exemption announced)" \
+    --out "EXEMPTED by --allow-invalid-json" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged --json-path 'fixtures/*' --allow-invalid-json 'fixtures/*'"
+
+# CONTROL (false-positive regression): JSONC is the common real-world case.
+# tsconfig.json legally carries comments and does NOT parse strictly. Measured on
+# a real repo: 17 of 119 tracked .json files are like this. An on-by-default
+# check would fire on all of them; scoping by --json-path is what prevents it.
+R="$(new_repo c5)"
+cat > "$R/tsconfig.json" <<'EOF'
+{
+  // JSONC: comments are legal here and strict json.load() rejects them.
+  "compilerOptions": { "strict": true }
+}
+EOF
+mkdir -p "$R/data"
+printf '{"generated": true}\n' > "$R/data/view.json"
+git -C "$R" add tsconfig.json data/view.json
+expect CONTROL 0 "JSONC outside --json-path does not trip the JSON check" \
+    --out "1 staged .json file(s)" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged --json-path 'data/**/*.json'"
+
+# NEEDLE: the same tsconfig DOES fail if someone wrongly nominates it, proving
+# the check is genuinely running and the control above is not a vacuous pass.
+expect NEEDLE 3 "the same JSONC file fails when explicitly nominated" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged --json-path 'tsconfig.json'"
+
+echo "=== (d) the JSON decision is MANDATORY (.push-guard.json) ==="
+
+# NEEDLE: the fail-open this gate closes. No --json-path, no config: the previous
+# release printed "JSON check NOT REQUESTED" and exited 0, leaving the repo
+# unprotected forever with nothing ever failing.
+R="$(new_repo d1)"
+printf '{"a": 1}\n' > "$R/thing.json"
+git -C "$R" add thing.json
+expect NEEDLE 6 "no --json-path and no config is REFUSED (the closed fail-open)" \
+    --out "NO JSON DECISION" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# NEEDLE: config nominates paths, and the check genuinely runs off it.
+R="$(new_repo d2)"
+write_config "$R" '{"json_paths": ["data/**/*.json"]}'
+mkdir -p "$R/data"
+printf '{"a": 1,\n' > "$R/data/broken.json"
+git -C "$R" add data/broken.json
+expect NEEDLE 3 "broken JSON is caught via config-supplied json_paths" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# NEEDLE: opt-out WITHOUT a reason. An unexplained opt-out is the absence again,
+# merely relocated into a file.
+R="$(new_repo d3)"
+write_config "$R" '{"json_check": "none"}'
+printf 'code\n' > "$R/x.txt"
+git -C "$R" add x.txt
+expect NEEDLE 6 "json_check:none without a reason is refused" \
+    --out "REQUIRES a non-empty" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# NEEDLE: malformed config must REFUSE, never fall back to "treat as absent".
+# That fallback would mean a typo silently disables the check the file enables.
+R="$(new_repo d4)"
+write_config "$R" '{"json_paths": ["data/**/*.json",'
+printf 'code\n' > "$R/x.txt"
+git -C "$R" add x.txt
+expect NEEDLE 6 "an unparseable config is refused, not treated as absent" \
+    --out "INVALID" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# NEEDLE: a config that parses but states NO decision. Distinct from malformed —
+# this one is valid JSON and still says nothing, which is the original defect
+# wearing a config file as a disguise.
+R="$(new_repo d5)"
+write_config "$R" '{}'
+printf 'code\n' > "$R/x.txt"
+git -C "$R" add x.txt
+expect NEEDLE 6 "a valid config that states no decision is refused" \
+    --out "states no decision" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# NEEDLE: a bogus json_check value must not be read as an opt-out.
+R="$(new_repo d6)"
+write_config "$R" '{"json_check": "off", "reason": "typo for none"}'
+printf 'code\n' > "$R/x.txt"
+git -C "$R" add x.txt
+expect NEEDLE 6 'json_check with an unrecognised value is refused' \
+    --out 'must be "none"' -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# CONTROL: config nominates paths, JSON is clean.
+# --out is REQUIRED. Exit 0 alone cannot distinguish "read the config, resolved
+# the paths, parsed the files" from "matched nothing and had nothing to do" —
+# the vacuous-control trap that already caught this harness once.
+R="$(new_repo d7)"
+write_config "$R" '{"json_paths": ["data/**/*.json"]}'
+mkdir -p "$R/data"
+printf '{"generated": true}\n' > "$R/data/view.json"
+git -C "$R" add data/view.json
+expect CONTROL 0 "config-supplied json_paths pass and are reported as parsed" \
+    --out "1 staged .json file(s)" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# CONTROL: a recorded opt-out passes AND the reason is echoed. Asserting on the
+# reason is the whole point — an opt-out nobody can see is what we just removed.
+R="$(new_repo d8)"
+write_config "$R" '{"json_check": "none", "reason": "no generated JSON in this repo"}'
+printf 'code\n' > "$R/x.txt"
+git -C "$R" add x.txt
+expect CONTROL 0 "a recorded opt-out passes and PRINTS its reason" \
+    --out "recorded reason: no generated JSON in this repo" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# CONTROL: config-supplied exemptions still work through the config path.
+R="$(new_repo d9)"
+write_config "$R" '{"json_paths": ["fixtures/*"], "allow_invalid_json": ["fixtures/*"]}'
+mkdir -p "$R/fixtures"
+printf 'not json at all' > "$R/fixtures/malformed.json"
+git -C "$R" add fixtures/malformed.json
+expect CONTROL 0 "config-supplied allow_invalid_json exempts (and announces it)" \
+    --out "EXEMPTED by --allow-invalid-json" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# CONTROL: --json-path alone still satisfies the decision, with no config at all.
+# This is what keeps every pre-existing caller working: nominating a path IS an
+# explicit decision. Only saying nothing is refused.
+R="$(new_repo d10)"
+mkdir -p "$R/data"
+printf '{"a": 1}\n' > "$R/data/good.json"
+git -C "$R" add data/good.json
+expect CONTROL 0 "--json-path alone satisfies the decision with no config present" \
+    --out "1 staged .json file(s)" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged --json-path 'data/**/*.json'"
+
+# NEEDLE: a CLI nomination must WIN over a config opt-out, loudly. Resolving a
+# contradiction toward more checking is the only safe direction, but doing it
+# silently would hide a genuine disagreement between caller and repo.
+R="$(new_repo d11)"
+write_config "$R" '{"json_check": "none", "reason": "claims no generated JSON"}'
+mkdir -p "$R/data"
+printf '{"a": 1,\n' > "$R/data/broken.json"
+git -C "$R" add data/broken.json
+expect NEEDLE 3 "--json-path overrides a config opt-out and still catches bad JSON" \
+    --out "honouring the nomination" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged --json-path 'data/**/*.json'"
+
+echo "=== (z) the guard itself emits no stray output ==="
+
+# CONTROL: the guard must not print interpreter warnings.
+#
+# This case exists because a real one shipped: the config parser was an inline
+# `<<'PY'` heredoc inside a $( ) command substitution, so bash printed
+#   warning: command substitution: 1 unterminated here-document
+# on EVERY run. Thirty needles and a clean shellcheck all missed it — the
+# warning went to stderr, and no assertion in this harness looked at output it
+# had not already been told to expect. It was found only by running the guard
+# against a real repository.
+#
+# The lesson is narrow and worth encoding: asserting on what you EXPECT to see
+# cannot detect what you never thought to look for. This asserts on the absence
+# of a whole output class instead.
+R="$(new_repo z1)"
+write_config "$R" '{"json_paths": ["data/**/*.json"]}'
+mkdir -p "$R/data"
+printf '{"a": 1}\n' > "$R/data/view.json"
+git -C "$R" add data/view.json
+z_out="$(cd "$R" && "$GUARD" check-staged 2>&1)"
+if grep -qiE 'warning:|unterminated|command substitution' <<<"$z_out"; then
+    printf '  FAIL  [%-7s] %s\n' "CONTROL" "guard emits interpreter warnings"
+    printf '%s\n' "$z_out" | sed 's/^/          | /'
+    FAIL=$((FAIL + 1))
+else
+    printf '  PASS  [%-7s] %s\n' "CONTROL" "guard runs without emitting any interpreter warning"
+    PASS=$((PASS + 1))
+fi
+
+# NEEDLE for the case above: prove the detector can actually fire, otherwise it
+# is one more assertion that passes because it looked at nothing.
+if grep -qiE 'warning:|unterminated|command substitution' \
+        <<<"bash: warning: command substitution: 1 unterminated here-document"; then
+    printf '  PASS  [%-7s] %s\n' "NEEDLE" "the warning detector fires on a known warning string"
+    PASS=$((PASS + 1))
+else
+    printf '  FAIL  [%-7s] %s\n' "NEEDLE" "the warning detector is dead — it cannot fire"
+    FAIL=$((FAIL + 1))
+fi
+
+echo "=== null case: nothing staged ==="
+
+# NEEDLE: the index equals HEAD. Committing here produces the empty commit.
+R="$(new_repo n1)"
+expect NEEDLE 5 "empty index is refused before a commit happens" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+echo "=== (b) push actually happened ==="
+
+# CONTROL: a real push that moves the remote.
+R="$(new_repo b1)"
+printf 'work\n' > "$R/work.txt"
+git -C "$R" add work.txt && git -C "$R" commit -q -m "real work"
+expect CONTROL 0 "a push that moves the remote is confirmed" \
+    --out "PUSH CONFIRMED" -- \
+    bash -c "cd '$R' && '$GUARD' push --remote origin --branch main"
+
+# NEEDLE: THE ORIGINAL FALSE POSITIVE. Remote already equals local HEAD, so the
+# naive 'remote == local' assertion succeeds while nothing is transferred.
+R="$(new_repo b2)"
+printf 'work\n' > "$R/work.txt"
+git -C "$R" add work.txt && git -C "$R" commit -q -m "real work"
+git -C "$R" push -q origin HEAD:refs/heads/main
+expect NEEDLE 4 "second push transferring nothing is refused (remote did not move)" -- \
+    bash -c "cd '$R' && '$GUARD' push --remote origin --branch main"
+
+# NEEDLE: the commit step aborted, so HEAD never advanced.
+R="$(new_repo b3)"
+HEAD_BEFORE="$(git -C "$R" rev-parse HEAD)"
+expect NEEDLE 5 "push after an aborted commit is refused (HEAD did not advance)" -- \
+    bash -c "cd '$R' && '$GUARD' push --remote origin --branch main --since-head '$HEAD_BEFORE'"
+
+# NEEDLE: an empty commit carrying a real message.
+R="$(new_repo b4)"
+git -C "$R" commit -q --allow-empty -m "feat: important-sounding message"
+expect NEEDLE 5 "pushing an empty commit is refused" -- \
+    bash -c "cd '$R' && '$GUARD' push --remote origin --branch main"
+
+# CONTROL: --since-head is satisfied when a real commit was made.
+R="$(new_repo b5)"
+HEAD_BEFORE="$(git -C "$R" rev-parse HEAD)"
+printf 'work\n' > "$R/work.txt"
+git -C "$R" add work.txt && git -C "$R" commit -q -m "real work"
+# --out is required here. Without it this control is VACUOUS: deleting the whole
+# --since-head validation block would still yield exit 0, because the empty-commit
+# and remote-moved checks independently succeed. It would prove nothing about the
+# code path it names.
+expect CONTROL 0 "--since-head passes when a real commit was created" \
+    --out "HEAD advanced" -- \
+    bash -c "cd '$R' && '$GUARD' push --remote origin --branch main --since-head '$HEAD_BEFORE'"
+
+# ---------------------------------------------------------------------------
+# Needles for the five blockers rev-974 found from a clean checkout. Every one
+# of these was reproduced before it was fixed; none is a hypothesis.
+# ---------------------------------------------------------------------------
+
+echo
+echo "-- blocker 2: the enumerating producer's exit status --"
+# FAULT INJECTION. mapfile < <(git diff) reported MAPFILE's status, so a git diff
+# that died returned zero files and the guard published that silence as clean.
+R="$(new_repo e1)"
+mkdir -p "$R/data"; printf '{ not json' > "$R/data/bad.json"
+git -C "$R" add -f data/bad.json
+expect NEEDLE 6 "a failed file enumeration REFUSES instead of reporting clean" \
+    --out "CANNOT ENUMERATE STAGED FILES" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged --json-path ':(this-magic-does-not-exist)data/*.json'"
+# CONTROL: the same malformed file with a WORKING pathspec must still be caught,
+# so the needle above is not passing merely because everything now refuses.
+expect CONTROL 3 "a working pathspec still catches the malformed JSON" \
+    --out "data/bad.json" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged --json-path 'data/*.json'"
+
+echo
+echo "-- blocker 3: OFF must come from a committed, reviewable object --"
+R="$(new_repo e2)"
+write_config_untracked "$R" '{"json_check": "none", "reason": "local unreviewed bypass"}'
+mkdir -p "$R/data"; printf '{ not json' > "$R/data/bad.json"
+git -C "$R" add -f data/bad.json
+# The anchor is the DISTINGUISHING clause, not the shared headline. Three
+# separate branches print "OPT-OUT IS NOT REVIEWABLE" — untracked, staged-not-
+# committed, and symlink. Anchoring on the headline means this needle stays green
+# if the untracked branch is deleted and control falls through to a SIBLING that
+# prints the same words: a substring anchor does not fail when its subject is
+# removed, IT RE-POINTS. Anchor on the clause only this branch can produce.
+expect NEEDLE 6 "an UNTRACKED opt-out is refused as unreviewable" \
+    --out "is not tracked in git" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# STAGED BUT NOT COMMITTED. Found by mutation, not by review: `if [[ -z "$cmode" ]]`
+# survived `if false` against a 44/44 green suite, because no case ever built this
+# state. Note the mutant still exits 6 — control falls to the LOCAL-ONLY branch
+# below and refuses for a different reason. An exit-code-only assertion here would
+# be satisfied by the wrong branch, which is why --out carries the distinguishing
+# clause. `git add` puts the file in the index, so ls-files matches while HEAD
+# does not: staged review is not review.
+R="$(new_repo e2b)"
+write_config_untracked "$R" '{"json_check": "none", "reason": "staged, never committed"}'
+git -C "$R" add .push-guard.json
+mkdir -p "$R/data"; printf '{ not json' > "$R/data/bad.json"
+git -C "$R" add -f data/bad.json
+expect NEEDLE 6 "a STAGED-but-uncommitted opt-out is refused" \
+    --out "staged but not yet in HEAD" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# COMMITTED CONFIG DOES NOT PARSE while the working tree opts out cleanly. Also a
+# mutation survivor. The working-tree config is valid, so the early config check
+# passes and we reach the re-read; the committed object is what fails. Without
+# this branch an opt-out could be honoured on the strength of a HEAD blob nobody
+# can actually read a decision out of.
+R="$(new_repo e2c)"
+write_config "$R" '{ this is not json'
+printf '%s\n' '{"json_check": "none", "reason": "valid here, broken in HEAD"}' > "$R/.push-guard.json"
+mkdir -p "$R/data"; printf '{ not json' > "$R/data/bad.json"
+git -C "$R" add -f data/bad.json
+expect NEEDLE 6 "an UNPARSEABLE committed config cannot authorise an opt-out" \
+    --out "is INVALID" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# A committed ON silently flipped OFF in the working tree is the same bypass.
+R="$(new_repo e3)"
+write_config "$R" '{"json_paths": ["data/**/*.json"]}'
+printf '%s\n' '{"json_check": "none", "reason": "local convenience"}' > "$R/.push-guard.json"
+mkdir -p "$R/data"; printf '{ not json' > "$R/data/bad.json"
+git -C "$R" add -f data/bad.json
+expect NEEDLE 6 "a committed ON flipped OFF in the working tree is refused" \
+    --out "LOCAL-ONLY OPT-OUT" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# A committed SYMLINK is a mutable target: the reviewed blob is a path, and what
+# it points at can change with no diff at all.
+R="$(new_repo e4)"
+printf '%s\n' '{"json_check": "none", "reason": "via symlink"}' > "$R/real-config.json"
+ln -s real-config.json "$R/.push-guard.json"
+git -C "$R" add real-config.json .push-guard.json
+git -C "$R" commit -q -m "symlinked config"
+mkdir -p "$R/data"; printf '{ not json' > "$R/data/bad.json"
+git -C "$R" add -f data/bad.json
+expect NEEDLE 6 "a committed SYMLINK config is refused as a mutable target" \
+    --out "committed SYMLINK" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+# CONTROL: the supported path still works. Without this the whole opt-out feature
+# could be dead and every needle above would still pass — a gate that can never
+# say yes is not a gate.
+R="$(new_repo e5)"
+write_config "$R" '{"json_check": "none", "reason": "committed and reviewable"}'
+mkdir -p "$R/data"; printf '{ not json' > "$R/data/bad.json"
+git -C "$R" add -f data/bad.json
+expect CONTROL 0 "a COMMITTED opt-out is honoured and prints its committed reason" \
+    --out "recorded reason: committed and reviewable" -- \
+    bash -c "cd '$R' && '$GUARD' check-staged"
+
+echo
+echo "-- blocker 4: advancement is ancestry, not inequality --"
+R="$(new_repo e6)"
+git -C "$R" checkout -qb other
+printf 'o\n' > "$R/o.txt"; git -C "$R" add o.txt; git -C "$R" commit -q -m o
+OTHER="$(git -C "$R" rev-parse HEAD)"
+git -C "$R" checkout -q main 2>/dev/null || git -C "$R" checkout -q master
+printf 'm\n' > "$R/m.txt"; git -C "$R" add m.txt; git -C "$R" commit -q -m m
+MAINH="$(git -C "$R" rev-parse HEAD)"
+git -C "$R" checkout -q "$OTHER"
+expect NEEDLE 5 "a checkout of pre-existing diverged history is not 'advancement'" \
+    --out "NOT A DESCENDANT" -- \
+    bash -c "cd '$R' && '$GUARD' push --remote origin --branch other --since-head '$MAINH'"
+
+echo
+echo "-- blocker 5: root and merge commits have defined emptiness --"
+R="$(new_repo e7)"
+git -C "$R" checkout -q --orphan fresh
+git -C "$R" rm -q -rf . >/dev/null 2>&1 || true
+git -C "$R" commit -q --allow-empty -m "empty root"
+expect NEEDLE 5 "an EMPTY ROOT commit is refused, not exempted" \
+    --out "EMPTY ROOT COMMIT" -- \
+    bash -c "cd '$R' && '$GUARD' push --remote origin --branch fresh"
+
+# CONTROL: a real root commit must still push, or the fix is just a new wall.
+R="$(new_repo e8)"
+git -C "$R" checkout -q --orphan fresh2
+git -C "$R" rm -q -rf . >/dev/null 2>&1 || true
+printf 'real\n' > "$R/real.txt"; git -C "$R" add real.txt
+git -C "$R" commit -q -m "real root"
+expect CONTROL 0 "a NON-empty root commit still pushes" \
+    --out "non-empty root commit" -- \
+    bash -c "cd '$R' && '$GUARD' push --remote origin --branch fresh2"
+
+# THE MERGE BRANCH HAD NO NEEDLE AT ALL. It was defined, hand-verified, and
+# shipped -- and deleting the refusal left the suite at 41/41 green. Defining
+# semantics is not testing them, and an untested branch is indistinguishable
+# from an absent one to everyone downstream.
+# EMPTY MERGE: two branches that each change nothing, merged. The merge tree is
+# then identical to EVERY parent -- it integrates nothing and introduces nothing.
+R="$(new_repo e9)"
+git -C "$R" checkout -q -b mx
+git -C "$R" commit -q --allow-empty -m "x: no tree change"
+git -C "$R" checkout -q -b my HEAD~1 2>/dev/null || git -C "$R" checkout -q -b my
+git -C "$R" commit -q --allow-empty -m "y: no tree change"
+git -C "$R" checkout -q mx
+git -C "$R" merge -q --no-ff --no-edit my
+# PROVE THE FIXTURE IS ACTUALLY AN EMPTY MERGE before asserting on it, or the
+# needle passes for the wrong reason on a repo that never made a merge at all.
+np="$(git -C "$R" rev-list --parents -n 1 HEAD | wc -w)"
+if (( np > 2 )) && git -C "$R" diff --quiet HEAD^1 HEAD && git -C "$R" diff --quiet HEAD^2 HEAD; then
+    printf '  ok    [%-14s] fixture is a merge (%d fields) with tree identical to both parents\n' "e9-fixture" "$np"; PASS=$(( PASS + 1 ))
+else
+    printf '  FAIL  [%-14s] fixture is not an empty merge -- needle would be vacuous\n' "e9-fixture"; FAIL=$(( FAIL + 1 ))
+fi
+expect NEEDLE 5 "an EMPTY MERGE is refused, not exempted" \
+    --out "EMPTY MERGE" -- \
+    bash -c "cd '$R' && '$GUARD' push --remote origin --branch mx"
+
+# CONTROL: a merge that really integrates must still push. Both sides add a
+# distinct file, so the merge tree differs from BOTH parents.
+R="$(new_repo e10)"
+git -C "$R" checkout -q -b nx
+printf 'from x\n' > "$R/x.txt"; git -C "$R" add x.txt; git -C "$R" commit -q -m "x adds a file"
+git -C "$R" checkout -q -b ny HEAD~1
+printf 'from y\n' > "$R/y.txt"; git -C "$R" add y.txt; git -C "$R" commit -q -m "y adds a file"
+git -C "$R" checkout -q nx
+git -C "$R" merge -q --no-ff --no-edit ny
+expect CONTROL 0 "a NON-empty merge commit still pushes" \
+    --out "non-empty merge commit" -- \
+    bash -c "cd '$R' && '$GUARD' push --remote origin --branch nx"
+
+echo
+printf 'push-guard needles: %d passed, %d failed\n' "$PASS" "$FAIL"
+(( FAIL == 0 )) || exit 1

packages/mosaic/framework/tools/git/test-verify-clean-clone.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+# test-verify-clean-clone.sh -- needles for the verifier itself.
+#
+# v1 of the verifier passed while the real repository recorded 100644, because it
+# asserted a SCRATCH repo built by cp. There was no needle that could have caught
+# that: every case ran against a tree whose modes came off my filesystem.
+# So the load-bearing needle here is w2 -- SOURCE GIT MODE 100644, DISK MODE 755.
+# That is the exact contaminated state, and v1 exits 0 on it while v2 must refuse.
+# A verifier without this needle is the same shape as the defect it verifies.
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VERIFY="$HERE/verify-clean-clone.sh"
+ARTIFACTS=(push-guard.sh test-push-guard.sh verify-clean-clone.sh mutate-push-guard.sh
+           test-mutate-push-guard.sh
+           test-verify-clean-clone.sh)
+
+# THE REAL DEPLOYED LAYOUT. Every fixture in the first version of this file
+# installed the artifacts at the fixture ROOT, so 6/6 green proved flat-layout
+# operation and said NOTHING about the path these files actually ship at. The
+# verifier was unusable in place and the suite could not see it, because THE
+# FIXTURE ENCODED A LAYOUT THAT DOES NOT EXIST. A fixture is a claim about the
+# world; an untested fixture is an unreviewed one.
+readonly REAL_PREFIX="packages/mosaic/framework/tools/git"
+
+PASS=0; FAIL=0
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+
+# Build a source repo whose COMMITTED modes are 100755 and whose disk modes are
+# executable -- the honest state.
+# mkrepo <repo-root> [subdir]
+# With a subdir the artifacts are committed at repo/<subdir>/, which is how they
+# really ship. Echoes the directory the artifacts landed in -- that is what gets
+# passed as --repo, so the caller never has to reconstruct the path.
+mkrepo() {
+    local d="$1" sub="${2:-}"
+    local dest="$d${sub:+/$sub}"
+    mkdir -p "$dest"
+    local f
+    for f in "${ARTIFACTS[@]}"; do
+        install -m 755 "$HERE/$f" "$dest/$f"
+    done
+    git -C "$d" init -q .
+    git -C "$d" config user.email "[email protected]"
+    git -C "$d" config user.name "Verifier Needles"
+    git -C "$d" add -A
+    git -C "$d" commit -q -m "artifacts"
+    printf '%s\n' "$dest"
+}
+
+run_case() {
+    local name="$1" want_rc="$2" want_txt="$3" repo="$4"
+    local out rc
+    out="$("$VERIFY" --repo "$repo" 2>&1)"; rc=$?
+    if (( rc == want_rc )) && [[ "$out" == *"$want_txt"* ]]; then
+        printf '  ok    [%-14s]\n' "$name"; PASS=$(( PASS + 1 ))
+    else
+        printf '  FAIL  [%-14s] wanted rc=%d containing %q; got rc=%d\n%s\n' \
+            "$name" "$want_rc" "$want_txt" "$rc" "$out"; FAIL=$(( FAIL + 1 ))
+    fi
+}
+
+echo "== POSITIVE CONTROL: an honestly-committed artifact must PASS =="
+# Without this, every case below could be passing because the verifier always
+# refuses -- a wall, not a gate.
+mkrepo "$TMP/good" >/dev/null
+run_case w1-honest 0 "the COMMITTED artifact ran and passed" "$TMP/good"
+
+echo
+echo "== THE DEPLOYED LAYOUT: artifacts NESTED, not at the repository root =="
+# The blocker: ls-tree was given a bare basename, which is a ROOT-relative
+# pathspec, so in the real tree every artifact came back NOT TRACKED and the
+# verifier refused to run at all. This control fails against that version and
+# passes only when the committed PREFIX is threaded through ls-tree, the cloned
+# stat, and the suite's working directory.
+w6dir="$(mkrepo "$TMP/nested" "$REAL_PREFIX")"
+run_case w6-nested 0 "the COMMITTED artifact ran and passed" "$w6dir"
+# ...and prove the run actually happened DOWN THERE rather than at the root, or
+# a passing w6 would only mean the prefix was ignored harmlessly.
+#
+# Captured into a variable rather than piped into `grep -q` ON PURPOSE. grep -q
+# exits at the FIRST match, the verifier then dies of SIGPIPE, and under
+# `pipefail` the pipeline reports that 141 -- so A SUCCESSFUL MATCH READS AS A
+# FAILED ASSERTION. This cost me a red w6-prefix against a verifier that was
+# printing the right prefix all along. Same family as the pipefail/process-
+# substitution note already on record: the exit status being consulted is not
+# the status of the thing being asserted.
+w6out="$("$VERIFY" --repo "$w6dir" 2>&1)"
+if [[ "$w6out" == *"prefix $REAL_PREFIX/"* ]]; then
+    printf '  ok    [%-14s] verifier reported prefix %s/\n' "w6-prefix" "$REAL_PREFIX"; PASS=$(( PASS + 1 ))
+else
+    printf '  FAIL  [%-14s] verifier did not report the nested prefix -- it may have\n' "w6-prefix"
+    printf '        passed by looking at the root, which is the blocker unfixed\n'; FAIL=$(( FAIL + 1 ))
+fi
+# And the mode needle must ALSO bite in the nested layout: a prefix threaded
+# into the clone but not into ls-tree would silently stop checking modes.
+w7dir="$(mkrepo "$TMP/nested-laundered" "$REAL_PREFIX")"
+git -C "$TMP/nested-laundered" update-index --chmod=-x "$REAL_PREFIX/push-guard.sh"
+git -C "$TMP/nested-laundered" commit -q -m "drop exec bit in git only"
+run_case w7-nested-mode 1 "committed 100644, needs 100755" "$w7dir"
+
+echo
+echo "== THE B1 NEEDLE: source git mode 100644, DISK MODE STILL 755 =="
+# This is the reviewer's exact reproduction. v1 of the verifier exits 0 here.
+mkrepo "$TMP/laundered" >/dev/null
+git -C "$TMP/laundered" update-index --chmod=-x push-guard.sh test-push-guard.sh
+git -C "$TMP/laundered" commit -q -m "drop exec bit in git only"
+# PROVE THE FIXTURE IS THE CONTAMINATED STATE, not merely a broken repo: git must
+# say 100644 while the filesystem still says executable. If the disk bit were
+# gone too, the needle would be testing something easier than the real defect.
+src_mode="$(git -C "$TMP/laundered" ls-tree HEAD -- push-guard.sh | awk '{print $1}')"
+disk_mode="$(stat -c '%a' "$TMP/laundered/push-guard.sh")"
+if [[ "$src_mode" == "100644" && "$disk_mode" == "755" ]]; then
+    printf '  ok    [%-14s] fixture is git=%s disk=%s\n' "w2-fixture" "$src_mode" "$disk_mode"; PASS=$(( PASS + 1 ))
+else
+    printf '  FAIL  [%-14s] fixture wrong: git=%s disk=%s -- needle would not test the defect\n' \
+        "w2-fixture" "$src_mode" "$disk_mode"; FAIL=$(( FAIL + 1 ))
+fi
+run_case w2-laundered 1 "committed 100644, needs 100755" "$TMP/laundered"
+
+echo
+echo "== the artifact must be COMMITTED, or there is no mode to verify =="
+mkrepo "$TMP/untracked" >/dev/null
+git -C "$TMP/untracked" rm -q --cached push-guard.sh
+git -C "$TMP/untracked" commit -q -m "untrack the guard"
+run_case w3-untracked 1 "NOT TRACKED" "$TMP/untracked"
+
+echo
+echo "== a committed SYMLINK is a path, not the reviewed code =="
+mkrepo "$TMP/symlink" >/dev/null
+( cd "$TMP/symlink" && rm -f push-guard.sh && ln -s /dev/null push-guard.sh \
+  && git add push-guard.sh && git commit -q -m "symlink the guard" )
+run_case w4-symlink 1 "SYMLINK" "$TMP/symlink"
+
+echo
+echo "== not a repository at all: REFUSE, never pass =="
+mkdir -p "$TMP/bare"
+for f in "${ARTIFACTS[@]}"; do install -m 755 "$HERE/$f" "$TMP/bare/$f"; done
+run_case w5-norepo 1 "not inside a git repository" "$TMP/bare"
+
+echo
+printf '%d passed, %d failed\n' "$PASS" "$FAIL"
+(( FAIL == 0 ))

packages/mosaic/framework/tools/git/verify-clean-clone.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# verify-clean-clone.sh -- prove the COMMITTED artifact runs, from a clean clone.
+#
+# ================== THIS FILE IS THE SECOND VERSION. THE FIRST HAD B1. ========
+# B1 was: the delivered scripts were committed mode 100644, so the artifact
+# returned 126 Permission denied for anyone who cloned it. Two of us ran 32/32
+# because our local working copies had the exec bit set by hand at creation.
+#
+# I wrote v1 of this file to prevent exactly that. V1 COPIED THE WORKING-TREE
+# FILES INTO A SCRATCH REPOSITORY AND ASSERTED THE SCRATCH REPOSITORY'S INDEX.
+# cp preserves the local exec bit, so `git add` in the scratch repo recorded
+# 100755 NO MATTER WHAT THE REAL REPOSITORY STORED. Reviewer reproduction:
+#     git update-index --chmod=-x push-guard.sh test-push-guard.sh
+#     ./verify-clean-clone.sh   ->  EXIT 0, "CLEAN CLONE: suite ran and passed"
+# while the real index read 100644 -- the precise contaminated state B1 was.
+#
+#   THE CONTROL FOR THE DEFECT INHERITED THE DEFECT, BECAUSE IT MEASURED A COPY
+#   INSTEAD OF THE SUBJECT. cp LAUNDERS MODE.
+#
+# Both of v1's mechanisms were right -- assert the INDEX not the disk, execute
+# DIRECTLY not via `bash script`. They were applied to the wrong repository.
+# So v2 changes what is measured, not how:
+#   * mode is read from the SOURCE repository's COMMITTED TREE (git ls-tree),
+#     which no local chmod can influence;
+#   * the tree under test is produced by CLONING THAT COMMIT, so every mode
+#     comes out of the object store rather than off my filesystem.
+# There is no cp anywhere in this file, and that is deliberate.
+#
+# It also REFUSES rather than passes when the artifacts are untracked: an
+# artifact that is not committed has no mode to verify, and a verifier that
+# silently succeeds on nothing is the vacuous-absence failure all over again.
+
+set -euo pipefail
+
+readonly EX_FAIL=1
+readonly EX_USAGE=64
+
+REPO=""
+REV="HEAD"
+
+die() { printf 'usage error: %s\n' "$1" >&2; exit "$EX_USAGE"; }
+
+while (( $# )); do
+    case "$1" in
+        --repo) REPO="${2:-}"; shift 2 ;;
+        --rev)  REV="${2:-}";  shift 2 ;;
+        *) die "unknown argument: $1" ;;
+    esac
+done
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+[[ -n "$REPO" ]] || REPO="$HERE"
+
+ARTIFACTS=(push-guard.sh test-push-guard.sh verify-clean-clone.sh mutate-push-guard.sh
+           test-mutate-push-guard.sh
+           test-verify-clean-clone.sh)
+SUITE="test-push-guard.sh"
+
+# --- the subject must be a real repository, or there is nothing to verify -----
+if ! ROOT="$(git -C "$REPO" rev-parse --show-toplevel 2>/dev/null)"; then
+    printf 'REFUSING: %s is not inside a git repository.\n' "$REPO" >&2
+    printf 'This verifier checks the COMMITTED mode of the artifact. An uncommitted\n' >&2
+    printf 'artifact has no committed mode, and passing here would prove nothing.\n' >&2
+    exit "$EX_FAIL"
+fi
+if ! REV_SHA="$(git -C "$ROOT" rev-parse --verify --quiet "${REV}^{commit}")"; then
+    printf 'REFUSING: %s does not resolve to a commit in %s\n' "$REV" "$ROOT" >&2
+    exit "$EX_FAIL"
+fi
+
+# --- THE ARTIFACT'S COMMITTED PATH, NOT ITS BASENAME -------------------------
+# v2 asserted `git ls-tree HEAD -- push-guard.sh`, which is a ROOT-RELATIVE
+# pathspec. These files really live several directories down. Run in place and
+# every artifact came back "NOT TRACKED" -- the verifier built to stop packaging
+# false-greens could not verify the tree that ships it.
+#
+# The tests missed it because EVERY FIXTURE INSTALLED THE ARTIFACTS AT THE
+# FIXTURE ROOT. 6/6 green proved flat-layout operation and nothing about the
+# deployed path. THAT IS THE THIRD TIME ON THIS TOOL THAT A CONTROL VALIDATED A
+# MODEL INSTEAD OF THE SUBJECT: v1 measured a cp'd scratch repo, and then v2's
+# own tests measured a layout that does not exist. A fixture is a claim about
+# the world, and an untested fixture is an unreviewed one.
+#
+# --show-prefix answers "where is this directory inside its repository", so the
+# same prefix drives ls-tree, the cloned stat, and the suite's working dir.
+PREFIX="$(git -C "$REPO" rev-parse --show-prefix)"
+
+printf '=== subject ===\n'
+printf '  repo   %s\n  rev    %s (%s)\n  prefix %s\n\n' \
+    "$ROOT" "$REV" "$REV_SHA" "${PREFIX:-<repository root>}"
+
+# --- 1. MODE, FROM THE COMMITTED TREE OF THE SUBJECT -------------------------
+# git ls-tree reports what the COMMIT records. Nothing on my filesystem can
+# move this number -- which is the whole point, and what v1 got wrong.
+printf '=== committed modes (git ls-tree %s) ===\n' "$REV"
+rc=0
+for f in "${ARTIFACTS[@]}"; do
+    entry="$(git -C "$ROOT" ls-tree "$REV_SHA" -- "${PREFIX}${f}")"
+    if [[ -z "$entry" ]]; then
+        printf '  FAIL  %s is NOT TRACKED at %s -- nothing committed to verify\n' "$f" "$REV"
+        rc=1; continue
+    fi
+    mode="${entry%% *}"; rest="${entry#* }"; type="${rest%% *}"
+    if [[ "$type" != blob ]]; then
+        printf '  FAIL  %s is a %s at %s, not a regular file\n' "$f" "$type" "$REV"
+        rc=1; continue
+    fi
+    case "$mode" in
+        100755) printf '  ok    %s committed %s\n' "$f" "$mode" ;;
+        120000) printf '  FAIL  %s is a SYMLINK (%s) -- the reviewed blob is a path, not the code\n' "$f" "$mode"; rc=1 ;;
+        *)      printf '  FAIL  %s committed %s, needs 100755\n' "$f" "$mode"
+                printf '        fix with: git update-index --chmod=+x %s && commit\n' "$f"
+                rc=1 ;;
+    esac
+done
+if (( rc != 0 )); then
+    printf '\nREFUSING TO CONTINUE: the COMMITTED modes are wrong, whatever the disk says.\n'
+    printf 'A clone of this commit would exit 126 for the next person.\n'
+    exit "$EX_FAIL"
+fi
+
+# --- 2. RUN FROM A CLONE OF THAT COMMIT --------------------------------------
+# Cloning materialises every file from the object store, so the modes on disk
+# are the COMMITTED modes by construction. No cp, no local state, nothing this
+# machine can contribute.
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+printf '\n=== cloning %s (no local mode bits survive this) ===\n' "$REV_SHA"
+git clone -q --no-local --no-hardlinks "$ROOT" "$WORK/clone"
+git -C "$WORK/clone" -c advice.detachedHead=false checkout -q "$REV_SHA"
+
+for f in "${ARTIFACTS[@]}"; do
+    printf '  clone disk mode: %s %s\n' "$(stat -c '%a' "$WORK/clone/${PREFIX}${f}")" "${PREFIX}${f}"
+done
+
+printf '\n=== executing DIRECTLY (./%s), not via "bash %s" ===\n' "$SUITE" "$SUITE"
+# Invoking the interpreter explicitly masks a missing exec bit completely -- it
+# is how the original green was obtained. Direct execution is the thing under
+# test, so the mode has to be real for this line to succeed.
+cd "$WORK/clone/${PREFIX}"
+if ! "./$SUITE"; then
+    printf '\nCLEAN-CLONE RUN FAILED.\n'
+    exit "$EX_FAIL"
+fi
+
+printf '\n=== CLEAN CLONE: the COMMITTED artifact ran and passed ===\n'

packages/mosaic/framework/tools/quality/scripts/check-test-enumeration.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# check-test-enumeration.sh — CI test-membership guard (#1017).
+#
+# CI reaches shell suites through two hand-enumerated surfaces:
+#   S1  packages/mosaic/package.json  scripts."test:framework-shell"
+#   S2  .woodpecker/ci.yml            direct `bash packages/mosaic/framework/tools/...` commands
+#
+# A hand-enumerated allowlist re-arms its own gap: a new suite never auto-joins,
+# so the list silently under-runs the disk (17 of 39 suites were invisible when
+# #1017 was filed). This guard makes that under-run impossible to do silently:
+#
+#   FAIL when a suite-shaped file exists on disk and is neither enumerated on
+#        the UNION of both surfaces nor listed in the exclusions file.
+#        ("Enumerated", deliberately — F1/F2 on PR #1018 proved this guard sees
+#        NAMING, not reachability, and its words must not claim otherwise.)
+#   FAIL when either surface names a path that does not exist on disk
+#        (a rename manufactures a stale entry silently — checked BOTH directions).
+#   FAIL when an exclusion entry has no reason, names a path that is gone,
+#        names a path that is also enumerated (contradiction), or names a path
+#        outside the population (dead weight that looks like coverage).
+#
+# POPULATION PATTERN — a deliberate decision, stated per #1017's record:
+# basename matches *test*.sh (contains "test", ends ".sh"). Deliberately BROAD:
+# the strict `test-*.sh` prefix cannot even name three real boundary files
+# (tmux/agent-send.test.sh — CI-run; orchestrator/smoke-test.sh;
+# wake/validate-973/microtest-wake-assert.sh), and three independent censuses
+# handled that last file three different ways with no trace of the judgement.
+# The broad pattern makes such files MEMBERS, so their disposition must be a
+# signed exclusion, not an accident of the glob. The SAME pattern is applied to
+# both sides of the comparison (disk and enumeration) — a comparison globbed two
+# ways runs on two different populations. Scripts outside the pattern on both
+# sides symmetrically (e.g. check-resident-budget.sh, verify-sanitized.sh) are
+# check-scripts, not suites; their existence is still verified via the
+# both-directions rule because every surface-named path must exist on disk.
+#
+# The surfaces are PARSED, never line-ranged: three seats independently
+# mis-scoped hand-written line ranges against these files (#1017 thread). S1 is
+# read via JSON + command-chain tokenization; S2 by extracting every
+# packages/mosaic/framework/tools/ token wherever it appears in the file.
+#
+# Exclusions file format (framework/tools/quality/test-enumeration-exclusions.txt):
+#   <repo-relative-path> | <non-empty reason>
+# Lines starting with # and blank lines are ignored. An exclusion is a recorded
+# decision someone signed, not an omission nobody made.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/../../../../../.." && pwd)"
+while (( $# )); do
+    case "$1" in
+        --root) ROOT="$(cd "$2" && pwd)"; shift 2 ;;
+        *) echo "usage: check-test-enumeration.sh [--root <repo-root>]" >&2; exit 2 ;;
+    esac
+done
+
+PKG_JSON="$ROOT/packages/mosaic/package.json"
+CI_YML="$ROOT/.woodpecker/ci.yml"
+TOOLS_DIR="$ROOT/packages/mosaic/framework/tools"
+EXCLUSIONS="$TOOLS_DIR/quality/test-enumeration-exclusions.txt"
+
+for f in "$PKG_JSON" "$CI_YML"; do
+    [[ -f "$f" ]] || { echo "FAIL: required surface file missing: $f" >&2; exit 2; }
+done
+[[ -d "$TOOLS_DIR" ]] || { echo "FAIL: tools dir missing: $TOOLS_DIR" >&2; exit 2; }
+
+fail_count=0
+fail() { printf 'FAIL  %s\n' "$1"; fail_count=$(( fail_count + 1 )); }
+
+# in_population <repo-relative path> — the single pattern, used for BOTH sides.
+in_population() {
+    local base; base="$(basename "$1")"
+    [[ "$base" == *test*.sh ]]
+}
+
+# --- Surface 1: package.json test:framework-shell, parsed, repo-relative -----
+# Tokens are script paths iff they contain "/" and end .sh/.py; interpreter
+# names and flags are skipped. Paths are relative to packages/mosaic/.
+mapfile -t S1 < <(python3 - "$PKG_JSON" <<'PY'
+import json, shlex, sys
+cmd = json.load(open(sys.argv[1]))["scripts"].get("test:framework-shell", "")
+seen = []
+for seg in cmd.split("&&"):
+    for tok in shlex.split(seg):
+        if "/" in tok and (tok.endswith(".sh") or tok.endswith(".py")):
+            path = "packages/mosaic/" + tok
+            if path not in seen:
+                seen.append(path)
+print("\n".join(seen))
+PY
+)
+
+# --- Surface 2: ci.yml, every framework/tools token wherever it appears ------
+# Comment lines (first non-whitespace char is #) are skipped BEFORE matching:
+# commenting an invocation out is the most common way a suite actually gets
+# disabled, and a raw-text regex would keep calling it enumerated (F1, 20155 on
+# PR #1018 — demonstrated, not argued). Known residual limit: a path named only
+# in a TRAILING comment on a live line still matches; no such line exists today
+# and full fidelity would need a YAML parser the CI image does not ship.
+mapfile -t S2 < <(grep -vE '^[[:space:]]*#' "$CI_YML" \
+    | grep -oE 'packages/mosaic/framework/tools/[A-Za-z0-9_./-]+\.(sh|py)' | sort -u)
+
+# --- Union, and its population-restricted view -------------------------------
+declare -A ENUM=() ENUM_POP=()
+for p in "${S1[@]:-}" "${S2[@]:-}"; do
+    [[ -n "$p" ]] || continue
+    ENUM["$p"]=1
+    in_population "$p" && ENUM_POP["$p"]=1
+done
+
+# --- Direction B: every surface-named path must exist on disk ----------------
+for p in "${!ENUM[@]}"; do
+    [[ -f "$ROOT/$p" ]] || fail "STALE ENUMERATION: surfaces name '$p' but it does not exist on disk"
+done
+
+# --- Exclusions: parsed with the same rigor the enumeration gets -------------
+declare -A EXCLUDED=()
+if [[ -f "$EXCLUSIONS" ]]; then
+    lineno=0
+    while IFS= read -r line; do
+        lineno=$(( lineno + 1 ))
+        [[ "$line" =~ ^[[:space:]]*(#|$) ]] && continue
+        path="${line%%|*}"; reason="${line#*|}"
+        path="$(echo "$path" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')"
+        reason="$(echo "$reason" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')"
+        if [[ "$line" != *"|"* || -z "$reason" ]]; then
+            fail "EXCLUSION MISSING REASON: line $lineno ('$path') — an exclusion is a recorded decision someone signed"
+            continue
+        fi
+        if [[ ! -f "$ROOT/$path" ]]; then
+            fail "STALE EXCLUSION: line $lineno excludes '$path' which does not exist on disk"
+            continue
+        fi
+        if ! in_population "$path"; then
+            fail "EXCLUSION OUTSIDE POPULATION: line $lineno excludes '$path' which the population pattern does not name — dead weight that reads as coverage"
+            continue
+        fi
+        if [[ -n "${ENUM[$path]:-}" ]]; then
+            fail "CONTRADICTORY EXCLUSION: line $lineno excludes '$path' which the surfaces already enumerate"
+            continue
+        fi
+        EXCLUDED["$path"]=1
+    done < "$EXCLUSIONS"
+fi
+
+# --- Direction A: disk population must be enumerated or signed-excluded ------
+disk_total=0
+unlisted=0
+while IFS= read -r f; do
+    rel="${f#"$ROOT"/}"
+    in_population "$rel" || continue
+    disk_total=$(( disk_total + 1 ))
+    if [[ -z "${ENUM_POP[$rel]:-}" && -z "${EXCLUDED[$rel]:-}" ]]; then
+        fail "UNENUMERATED: '$rel' exists on disk but is neither enumerated on any CI surface nor signed in the exclusions file"
+        unlisted=$(( unlisted + 1 ))
+    fi
+done < <(find "$TOOLS_DIR" -type f -name '*.sh' | sort)
+
+if (( fail_count > 0 )); then
+    printf 'enumeration guard: %d failure(s) — population %d, enumerated (in-population) %d, excluded %d\n' \
+        "$fail_count" "$disk_total" "${#ENUM_POP[@]}" "${#EXCLUDED[@]}"
+    exit 1
+fi
+printf 'enumeration guard: OK — population %d, enumerated (in-population) %d, excluded (signed) %d, surfaces name %d path(s), all present on disk\n' \
+    "$disk_total" "${#ENUM_POP[@]}" "${#EXCLUDED[@]}" "${#ENUM[@]}"

packages/mosaic/framework/tools/quality/scripts/test-check-test-enumeration.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# test-check-test-enumeration.sh — needles for the enumeration guard (#1017).
+#
+# Every failure mode the guard promises gets BOTH polarities:
+#   NEEDLE   a fixture that MUST trip the guard, asserted on the guard's OWN
+#            words (--out) — exit 1 alone cannot distinguish "caught the rogue
+#            file" from "choked on the fixture".
+#   CONTROL  a fixture that MUST pass. A guard that failed unconditionally
+#            would satisfy every needle here — the null-case defect the guard's
+#            own subject matter (#1017) exists to make impossible.
+#
+# The needles encode the specific errors that produced #1017's thread:
+#   n6 is the 20124 boundary file (a suite the strict prefix cannot name);
+#   n2b proves surface 2 is PARSED, not line-ranged (three seats mis-scoped
+#       hand-written ranges against ci.yml);
+#   n5/n7 keep the exclusions file honest so it cannot become the next silent cap;
+#   n8/c4 are F1 (20155): a commented-out ci.yml line is NOT enumeration —
+#       commenting-out is the most common way a suite actually gets disabled,
+#       and it must fail loud in one direction without false-staling the other.
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+GUARD="$HERE/check-test-enumeration.sh"
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+PASS=0; FAIL=0
+
+# fixture <name> — a minimal repo root the guard accepts via --root:
+# one suite enumerated on S1 (plus a naming-outlier suite, so the S1 parser's
+# handling of non-prefix names is always exercised), one on S2, one check-script
+# named on S2 that is outside the population, and an empty exclusions file.
+fixture() {
+    local r="$TMP/$1"
+    mkdir -p "$r/packages/mosaic/framework/tools/git" \
+             "$r/packages/mosaic/framework/tools/tmux" \
+             "$r/packages/mosaic/framework/tools/quality/scripts" \
+             "$r/.woodpecker"
+    printf '#!/usr/bin/env bash\nexit 0\n' > "$r/packages/mosaic/framework/tools/git/test-a.sh"
+    printf '#!/usr/bin/env bash\nexit 0\n' > "$r/packages/mosaic/framework/tools/tmux/outlier.test.sh"
+    printf '#!/usr/bin/env bash\nexit 0\n' > "$r/packages/mosaic/framework/tools/quality/scripts/test-ci.sh"
+    printf '#!/usr/bin/env bash\nexit 0\n' > "$r/packages/mosaic/framework/tools/quality/scripts/verify-thing.sh"
+    cat > "$r/packages/mosaic/package.json" <<'JSON'
+{"scripts": {"test:framework-shell": "bash framework/tools/git/test-a.sh && bash framework/tools/tmux/outlier.test.sh"}}
+JSON
+    cat > "$r/.woodpecker/ci.yml" <<'YML'
+steps:
+  sanitize:
+    commands:
+      - bash packages/mosaic/framework/tools/quality/scripts/verify-thing.sh
+  guard:
+    commands:
+      - bash packages/mosaic/framework/tools/quality/scripts/test-ci.sh
+YML
+    : > "$r/packages/mosaic/framework/tools/quality/test-enumeration-exclusions.txt"
+    printf '%s' "$r"
+}
+
+# expect <kind> <want-exit> <desc> [--out <substring>] -- <root>
+expect() {
+    local kind="$1" want="$2" desc="$3"; shift 3
+    local need_out=""
+    while (( $# )); do
+        case "$1" in
+            --out) need_out="$2"; shift 2 ;;
+            --)    shift; break ;;
+        esac
+    done
+    local root="$1" got=0 out
+    out="$(bash "$GUARD" --root "$root" 2>&1)" || got=$?
+    local why=""
+    [[ "$got" == "$want" ]] || why="wanted exit $want, got $got"
+    if [[ -z "$why" && -n "$need_out" && "$out" != *"$need_out"* ]]; then
+        why="exit $got as expected, but output never said: $need_out"
+    fi
+    if [[ -z "$why" ]]; then
+        printf '  PASS  [%-7s] %s (exit %s)\n' "$kind" "$desc" "$got"
+        PASS=$(( PASS + 1 ))
+    else
+        printf '  FAIL  [%-7s] %s — %s\n' "$kind" "$desc" "$why"
+        printf '%s\n' "$out" | sed 's/^/          | /'
+        FAIL=$(( FAIL + 1 ))
+    fi
+}
+
+excl() { printf '%s\n' "$2" >> "$1/packages/mosaic/framework/tools/quality/test-enumeration-exclusions.txt"; }
+
+echo "=== c1: a fully consistent fixture passes ==="
+R="$(fixture c1)"
+expect CONTROL 0 "consistent tree: both surfaces enumerated, nothing unlisted" \
+    --out "enumeration guard: OK" -- "$R"
+
+echo "=== n1: an on-disk suite reachable from no surface must fail ==="
+R="$(fixture n1)"
+printf '#!/usr/bin/env bash\nexit 0\n' > "$R/packages/mosaic/framework/tools/git/test-rogue.sh"
+expect NEEDLE 1 "unlisted suite is named in the failure" \
+    --out "UNENUMERATED: 'packages/mosaic/framework/tools/git/test-rogue.sh'" -- "$R"
+
+echo "=== n6: the 20124 boundary file — a suite the strict prefix cannot name ==="
+R="$(fixture n6)"
+printf '#!/usr/bin/env bash\nexit 0\n' > "$R/packages/mosaic/framework/tools/git/rogue.test.sh"
+expect NEEDLE 1 "naming-outlier suite (*.test.sh) is a population member, not invisible" \
+    --out "UNENUMERATED: 'packages/mosaic/framework/tools/git/rogue.test.sh'" -- "$R"
+
+echo "=== c3: a non-suite script outside the pattern is outside it on BOTH sides ==="
+R="$(fixture c3)"
+printf '#!/usr/bin/env bash\nexit 0\n' > "$R/packages/mosaic/framework/tools/git/check-unrelated.sh"
+expect CONTROL 0 "check-script on disk, unlisted, outside population: not the guard's business" \
+    --out "enumeration guard: OK" -- "$R"
+
+echo "=== n2/n2b: a surface naming a path absent from disk must fail — both surfaces ==="
+R="$(fixture n2)"
+rm "$R/packages/mosaic/framework/tools/git/test-a.sh"
+expect NEEDLE 1 "S1 (package.json) stale entry" \
+    --out "STALE ENUMERATION: surfaces name 'packages/mosaic/framework/tools/git/test-a.sh'" -- "$R"
+R="$(fixture n2b)"
+rm "$R/packages/mosaic/framework/tools/quality/scripts/test-ci.sh"
+expect NEEDLE 1 "S2 (ci.yml) stale entry — proves ci.yml is parsed, not line-ranged" \
+    --out "STALE ENUMERATION: surfaces name 'packages/mosaic/framework/tools/quality/scripts/test-ci.sh'" -- "$R"
+
+echo "=== c2: a rogue suite with a SIGNED exclusion passes, and is counted ==="
+R="$(fixture c2)"
+printf '#!/usr/bin/env bash\nexit 0\n' > "$R/packages/mosaic/framework/tools/git/test-rogue.sh"
+excl "$R" "packages/mosaic/framework/tools/git/test-rogue.sh | non-hermetic pending fixture work (needle-suite specimen)"
+expect CONTROL 0 "signed exclusion is honoured and visible in the summary" \
+    --out "excluded (signed) 1" -- "$R"
+
+echo "=== n3: an exclusion with no reason is not a decision ==="
+R="$(fixture n3)"
+printf '#!/usr/bin/env bash\nexit 0\n' > "$R/packages/mosaic/framework/tools/git/test-rogue.sh"
+excl "$R" "packages/mosaic/framework/tools/git/test-rogue.sh |   "
+expect NEEDLE 1 "empty reason rejected" --out "EXCLUSION MISSING REASON" -- "$R"
+R="$(fixture n3b)"
+printf '#!/usr/bin/env bash\nexit 0\n' > "$R/packages/mosaic/framework/tools/git/test-rogue.sh"
+excl "$R" "packages/mosaic/framework/tools/git/test-rogue.sh"
+expect NEEDLE 1 "missing separator rejected (the path alone is not a signature)" \
+    --out "EXCLUSION MISSING REASON" -- "$R"
+
+echo "=== n4: an exclusion whose path is gone is stale, not satisfied ==="
+R="$(fixture n4)"
+excl "$R" "packages/mosaic/framework/tools/git/test-vanished.sh | was excluded once, then deleted"
+expect NEEDLE 1 "stale exclusion rejected" --out "STALE EXCLUSION" -- "$R"
+
+echo "=== n5: excluding an enumerated suite is a contradiction, not belt-and-braces ==="
+R="$(fixture n5)"
+excl "$R" "packages/mosaic/framework/tools/git/test-a.sh | already in CI but excluded anyway"
+expect NEEDLE 1 "contradictory exclusion rejected" --out "CONTRADICTORY EXCLUSION" -- "$R"
+
+echo "=== n8/c4: a commented-out ci.yml line is not enumeration (F1, 20155) ==="
+R="$(fixture n8)"
+printf '#!/usr/bin/env bash\nexit 0\n' > "$R/packages/mosaic/framework/tools/git/test-disabled.sh"
+printf '      # - bash packages/mosaic/framework/tools/git/test-disabled.sh\n' >> "$R/.woodpecker/ci.yml"
+expect NEEDLE 1 "suite named only in a commented-out invocation is UNENUMERATED" \
+    --out "UNENUMERATED: 'packages/mosaic/framework/tools/git/test-disabled.sh'" -- "$R"
+R="$(fixture c4)"
+printf '      # - bash packages/mosaic/framework/tools/git/test-vanished.sh\n' >> "$R/.woodpecker/ci.yml"
+expect CONTROL 0 "comment naming an absent path raises no false stale-enumeration" \
+    --out "enumeration guard: OK" -- "$R"
+
+echo "=== n7: excluding a file outside the population is dead weight, not coverage ==="
+R="$(fixture n7)"
+excl "$R" "packages/mosaic/framework/tools/quality/scripts/verify-thing.sh | not a suite but signing it anyway"
+expect NEEDLE 1 "out-of-population exclusion rejected" --out "EXCLUSION OUTSIDE POPULATION" -- "$R"
+
+echo
+printf 'enumeration-guard needles: %d passed, %d failed\n' "$PASS" "$FAIL"
+(( FAIL == 0 ))

packages/mosaic/framework/tools/quality/test-enumeration-exclusions.txt

@@ -0,0 +1,45 @@
+# test-enumeration-exclusions.txt — signed exclusions for check-test-enumeration.sh (#1017).
+#
+# Every entry is a recorded decision: a suite-shaped file that exists on disk,
+# is NOT reachable from any CI surface, and carries the reason someone signed
+# for that. The guard FAILS on an entry with no reason, a stale path, or a path
+# the surfaces already enumerate. Burning an entry down = making it CI-reachable
+# (package.json test:framework-shell or a ci.yml step) and deleting its line.
+#
+# Format: <repo-relative path> | <reason>
+# All entries below were signed at #1017's filing base (main 826a8b3b, 2026-07-31)
+# by pepper (sb-it-1-dt); measurements cited are one-run assertions from that seat.
+
+# --- tools/git: the #1007 five — non-hermetic, resolve real credentials ---
+packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix (git -C scoping)
+packages/mosaic/framework/tools/git/test-issue-create-interactive-auth.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix
+packages/mosaic/framework/tools/git/test-gitea-login-resolution.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix
+packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh | resolves real credentials (#1007 census, fourth entry via family-grep); joins CI after the wrapper-half hermeticity fix
+packages/mosaic/framework/tools/git/test-issue-comment-readback.sh | resolves real credentials (#1007 census, fifth entry); joins CI after the wrapper-half hermeticity fix
+
+# --- tools/git: push guards — measured green locally, CI-image fitness unverified ---
+packages/mosaic/framework/tools/git/test-push-guard.sh | measured green at 826a8b3b (46 passed / 0 failed, one run, 2026-07-31); CI-image fitness unverified; #1017 burndown
+packages/mosaic/framework/tools/git/test-mutate-push-guard.sh | measured green at 826a8b3b (8/0, 13 mutants killed 0 survived, one run, 2026-07-31); requires setsid (util-linux), absent from the alpine base image; #1017 burndown
+packages/mosaic/framework/tools/git/test-issue-create-body-safety.sh | hermeticity unaudited — the unprotected suite in #1007's protected/unprotected split; audit before CI; #1017 burndown
+
+# --- tools/git: unmeasured ---
+packages/mosaic/framework/tools/git/test-verify-clean-clone.sh | unmeasured in CI image; asserts git file-mode (100644/755) semantics that need verification on the CI filesystem first; #1017 burndown
+packages/mosaic/framework/tools/git/test-help-exit-code.sh | unmeasured in CI image; stub-based (#701 regression harness), likely CI-fit; #1017 burndown
+packages/mosaic/framework/tools/git/test-lane-brief-pr-linkage.sh | unmeasured in CI image; fixture-based (#546/#547 regression harness), likely CI-fit; #1017 burndown
+
+# --- tools/tmux: require a live tmux server ---
+packages/mosaic/framework/tools/tmux/test-send-message-socket.sh | requires a real tmux server on a throwaway socket; CI image ships no tmux; #1017 burndown (needs tmux in image or a signed permanent exclusion)
+packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh | requires real tmux-pane fixtures on a throwaway socket; CI image ships no tmux; #1017 burndown (same condition as its sibling)
+
+# --- single-suite directories: unmeasured in CI ---
+packages/mosaic/framework/tools/fleet/test-start-agent-session.sh | unmeasured in CI image; stubs tmux via a fake bin dir, likely CI-fit; #1017 burndown
+packages/mosaic/framework/tools/glpi/test-list-http-status.sh | unmeasured in CI image; stub-based (#807 regression harness), likely CI-fit; #1017 burndown
+packages/mosaic/framework/tools/orchestrator/test-board-roll.sh | unmeasured in CI image; file-fixture based, likely CI-fit; #1017 burndown
+packages/mosaic/framework/tools/woodpecker/test-ci-wait-exit-matrix.sh | unmeasured in CI image; drives ci-wait.sh against a stub pipeline-status.sh, likely CI-fit; #1017 burndown
+
+# --- naming-boundary files the strict test-*.sh prefix cannot even name ---
+# (#1017: three independent censuses handled the microtest file three different
+# ways — editorial drop, structural exclusion, accidental inclusion — with no
+# recorded judgement. These lines ARE that judgement, signed.)
+packages/mosaic/framework/tools/orchestrator/smoke-test.sh | behavior smoke checks for coord continue/run workflows, run manually by orchestrator seats; unmeasured in CI; #1017 burndown
+packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh | #973 instrument self-test, run as a precondition of the validate-973 evidence procedure rather than as a standing CI suite; #1017 burndown candidate

packages/mosaic/framework/tools/wake/_wake-common.sh

@@ -191,3 +191,177 @@ _wake_init_dir() {
   [ -f "$dir/pending.jsonl" ] || printf '' | _atomic_write "$dir/pending.jsonl"
   [ -f "$dir/ack-ledger.jsonl" ] || printf '' | _atomic_write "$dir/ack-ledger.jsonl"
 }
+
+# ---------------------------------------------------------------------------
+# #973 — three-valued grep assertion helpers for the wake test suites.
+#
+# grep's exit contract is three-valued: 0 = match, 1 = no match, >1 = ERROR
+# (bad file, bad pattern, resource failure). Every wake-suite assertion used
+# to read all non-zero as "absent", so a grep that COULD NOT LOOK wore the
+# colour of a verdict: OR-polarity sites (`|| fail`) went falsely red,
+# AND-polarity sites (`&& fail` — including the credential canaries) went
+# falsely green. The repair is to refuse to answer: rc 0 -> match, rc 1 -> no
+# match, anything else -> loud abort naming the call site, the raw exit code,
+# and the arguments. An error NEVER becomes a verdict.
+#
+# Production tools (store.sh, ack.sh) source this file but call none of the
+# helpers below; they are inert outside the suites.
+#
+# Suite integration contract:
+#   - Call `wake_assert_init` ONCE at suite top level, right after sourcing.
+#     It dups the suite's real stderr to a saved fd BEFORE any call-site
+#     redirect exists, so an abort stays loud even at sites that append
+#     `2>/dev/null` (the preimage credential canaries pre-swallow stderr —
+#     exactly where a silent abort would recreate the defect being fixed).
+#   - Assertion sites live inside `( ... ) && ok` subshell blocks, pipelines,
+#     and `$(...)` substitutions, where a plain `exit` dies one layer deep and
+#     the suite would carry on to emit a verdict. The abort therefore signals
+#     the suite's MAIN shell ($$ is the main PID in every subshell) and then
+#     exits the current context: the suite dies by signal, non-zero, with NO
+#     verdict line emitted.
+#
+# Validation instrumentation (#973 evidence, not part of the assertion fix):
+#   - WAKE_ASSERT_LEDGER=<file>: every helper call appends
+#     "<helper> <caller-file>:<caller-line>" to <file>. That is the ONLY
+#     divergence from production behaviour — the suite otherwise runs its
+#     normal arms, so a validate run exercises exactly the shipped paths.
+#   - WAKE_ASSERT_FORCE_GREP_ERROR_AT=<caller-file>:<caller-line>: at exactly
+#     that call site, the invocation is routed through a REAL grep driven onto
+#     its real error path (unknown option -> rc 2) — a genuinely executed
+#     failing process, not a stubbed return — to prove per-site that the abort
+#     fires. Unset in production; matching no site is a no-op.
+# ---------------------------------------------------------------------------
+
+# wake_assert_init — dup the suite's real stderr once, for abort loudness.
+# MUST be called at suite TOP LEVEL, immediately after sourcing and before any
+# test block: a lazy (first-call) dup could capture an already-redirected
+# stderr if the first executed helper call sat under a call-site 2>/dev/null,
+# silencing every abort thereafter. The fd is allocated dynamically (>= 10),
+# so it cannot collide with the wake lock fds (8) or the detector run-loop
+# lock (9).
+#
+# Init also PINS the BASH_LINENO convention the site coordinates depend on:
+# a helper call written across a backslash continuation must report at its
+# FIRST physical line (the denominator artifact's convention). That was
+# measured on a developer bash (5.3.x); CI runs whatever bash its base image
+# baked in, and that version floats silently between image rebuilds. A bash
+# that disagrees would shift every continuation-site coordinate by one line
+# UNDER the validation instead of in front of it — so the convention is
+# asserted at runtime, in the same bash binary that runs the suite, and a
+# disagreeing bash aborts the suite loudly instead of skewing coordinates.
+_wake_assert_lineno_pin() {
+  local _wa_pin_tmp _wa_pin_got
+  _wa_pin_tmp="$(mktemp)" || {
+    _wake_assert_err_note "WAKE-ASSERT INIT ABORT: mktemp failed; cannot pin the BASH_LINENO convention — a pin that silently does not run is not a pin (#973)"
+    exit 97
+  }
+  cat >"$_wa_pin_tmp" <<'WAKE_ASSERT_PIN'
+_wap() { printf '%s\n' "${BASH_LINENO[0]}"; }
+(
+  _wap simple
+  _wap \
+    continuation
+)
+WAKE_ASSERT_PIN
+  # WAKE_ASSERT_PIN_BASH: test-only interpreter override so the pin's abort
+  # arm can be PROVEN to fire (microtest C10) — bash resets $BASH at startup,
+  # so the real probe interpreter cannot be spoofed from the environment.
+  _wa_pin_got="$("${WAKE_ASSERT_PIN_BASH:-${BASH:-bash}}" "$_wa_pin_tmp" 2>/dev/null)"
+  rm -f "$_wa_pin_tmp"
+  if [ "$_wa_pin_got" != "$(printf '3\n4')" ]; then
+    _wake_assert_err_note "WAKE-ASSERT INIT ABORT: BASH_LINENO convention violated on bash ${BASH_VERSION}: probe reported [${_wa_pin_got:-<no output>}], expected [3 4] (simple call at own line, continuation call at FIRST physical line) — site coordinates are untrustworthy on this bash (#973)"
+    exit 97
+  fi
+}
+
+wake_assert_init() {
+  if [ -z "${_wake_assert_err_fd:-}" ]; then
+    exec {_wake_assert_err_fd}>&2
+    _wake_assert_lineno_pin
+  fi
+}
+
+# _wake_assert_err_note MSG — write MSG to the saved real-stderr fd, falling
+# back to the current stderr if init was never called.
+_wake_assert_err_note() {
+  if [ -n "${_wake_assert_err_fd:-}" ]; then
+    printf '%s\n' "$1" >&"$_wake_assert_err_fd" 2>/dev/null ||
+      printf '%s\n' "$1" >&2
+  else
+    printf '%s\n' "$1" >&2
+  fi
+}
+
+# _wake_assert_abort HELPER SITE RC ARGS... — refuse to answer, loudly.
+# Writes the named reason to the saved real-stderr fd (falling back to the
+# current stderr), signals the suite's main shell, and exits this context.
+_wake_assert_abort() {
+  local _wa_helper="$1" _wa_where="$2" _wa_code="$3"
+  shift 3
+  _wake_assert_err_note "WAKE-ASSERT ABORT: ${_wa_helper} at ${_wa_where}: grep exit ${_wa_code} is an error, not a verdict (args: $*) — refusing to answer (#973)"
+  if [ -n "${BASHPID:-}" ] && [ "$BASHPID" != "$$" ]; then
+    kill -TERM "$$" 2>/dev/null || true
+  fi
+  exit 97
+}
+
+# _wake_assert_armed SITE — true iff the forced-error arm targets SITE; on a
+# match it emits a positive confirmation FIRST, so "site did not abort" can
+# never conflate SITE NOT CONVERTED with ARM NEVER REACHED IT: an armed run
+# with no ARMED line means the arm matched nothing (typo/renumber/drift), and
+# an ARMED line with no abort means the site's error path is broken. The two
+# defects are separable on stderr alone.
+_wake_assert_armed() {
+  [ "${WAKE_ASSERT_FORCE_GREP_ERROR_AT:-}" = "$1" ] || return 1
+  _wake_assert_err_note "WAKE-ASSERT ARMED: forcing real grep error at $1 (#973)"
+  return 0
+}
+
+# has_match GREP_ARGS... — three-valued grep verdict.
+# Drop-in for verdict-bearing `grep` calls (flags, files, stdin all pass
+# through; stdout is not captured, so extract-form call sites may use it
+# inside a substitution). Returns 0 on match, 1 on no-match; any other grep
+# exit aborts the suite via _wake_assert_abort.
+has_match() {
+  local _wa_site="${BASH_SOURCE[1]##*/}:${BASH_LINENO[0]}" _wa_rc=0
+  if [ -n "${WAKE_ASSERT_LEDGER:-}" ]; then
+    printf 'has_match %s\n' "$_wa_site" >>"$WAKE_ASSERT_LEDGER"
+  fi
+  if _wake_assert_armed "$_wa_site"; then
+    command grep --wake-assert-forced-error -- /dev/null
+    _wa_rc=$?
+  else
+    command grep "$@"
+    _wa_rc=$?
+  fi
+  case "$_wa_rc" in
+  0) return 0 ;;
+  1) return 1 ;;
+  *) _wake_assert_abort has_match "$_wa_site" "$_wa_rc" "$@" ;;
+  esac
+}
+
+# count_lines GREP_ARGS... — `grep -c` with the same three-way discipline.
+# Call sites drop their `-c` (the helper supplies it) and keep every other
+# argument. Prints the count on rc 0 AND rc 1 (rc 1 is grep's "count is 0" —
+# a valid measurement, not an error); any other exit aborts. The abort still
+# kills the suite from inside a `$(...)` capture: the substitution subshell
+# cannot exit the suite, but the signal to the main shell can — a count from
+# a failed measurement is never printed.
+count_lines() {
+  local _wa_site="${BASH_SOURCE[1]##*/}:${BASH_LINENO[0]}" _wa_rc=0 _wa_out=""
+  if [ -n "${WAKE_ASSERT_LEDGER:-}" ]; then
+    printf 'count_lines %s\n' "$_wa_site" >>"$WAKE_ASSERT_LEDGER"
+  fi
+  if _wake_assert_armed "$_wa_site"; then
+    _wa_out="$(command grep --wake-assert-forced-error -c -- /dev/null)"
+    _wa_rc=$?
+  else
+    _wa_out="$(command grep -c "$@")"
+    _wa_rc=$?
+  fi
+  case "$_wa_rc" in
+  0 | 1) printf '%s\n' "$_wa_out" ;;
+  *) _wake_assert_abort count_lines "$_wa_site" "$_wa_rc" "$@" ;;
+  esac
+}

packages/mosaic/framework/tools/wake/ack.sh

@@ -54,6 +54,16 @@ Commands:
                                          Local-write only; a background sync
                                          ships it (never blocks on network).
                                          --no-sync suppresses the background ship.
+                                         --force-past-quarantine passes the #946
+                                         force flag through to store.sh consume:
+                                         the ONLY way to advance past a
+                                         QUARANTINED (dead-lettered, never
+                                         delivered) seq. The store's per-seq
+                                         step-over diagnostics are re-emitted on
+                                         stderr; no consumed-hash witness is
+                                         recorded for the quarantined entry.
+                                         Without the flag, a consume that would
+                                         cross a quarantined seq is REFUSED.
   embed --upto N [--wake-id ID] [--agent A]
                                          Print the copy-run ack line to EMBED in
                                          a digest (does not perform the ack).
@@ -169,7 +179,7 @@ cmd_received() {
 
 cmd_consumed() {
   _need_jq
-  local upto='' wake_id='' do_sync="1"
+  local upto='' wake_id='' do_sync="1" force="0"
   while [ $# -gt 0 ]; do
     case "$1" in
     --upto)
@@ -184,6 +194,10 @@ cmd_consumed() {
       do_sync="0"
       shift
       ;;
+    --force-past-quarantine)
+      force="1"
+      shift
+      ;;
     *)
       echo "ack.sh consumed: unknown option '$1'" >&2
       exit 2
@@ -200,11 +214,25 @@ cmd_consumed() {
   # Advance consumed_seq via the store. The store enforces the CONTIGUOUS
   # gapless-prefix rule and rejects a gap (cannot ack N while N-1 unconsumed).
   # This is a LOCAL-WRITE cursor advance — no network.
-  local new_cursor
-  if ! new_cursor="$("$STORE_SH" consume --upto "$upto" 2>&1)"; then
+  local new_cursor store_args
+  store_args=(consume --upto "$upto")
+  if [ "$force" = "1" ]; then
+    store_args+=(--force-past-quarantine)
+  fi
+  if ! new_cursor="$("$STORE_SH" "${store_args[@]}" 2>&1)"; then
     echo "ack.sh consumed: refused — $new_cursor" >&2
     exit 1
   fi
+  if [ "$force" = "1" ]; then
+    # #946: on the forced path the store's LOUD per-seq step-over diagnostics
+    # were captured together with the cursor line (2>&1 above). Re-emit them on
+    # OUR stderr — the loudness must survive the wrapper — and keep only the
+    # final line (the cursor) for the CONSUMED report below.
+    local cursor_line
+    cursor_line="$(printf '%s\n' "$new_cursor" | tail -n1)"
+    printf '%s\n' "$new_cursor" | sed '$d' | grep -v '^[[:space:]]*$' >&2 || true
+    new_cursor="$cursor_line"
+  fi
 
   # Record the CONSUMED ack in the local ledger (still no network).
   local record

packages/mosaic/framework/tools/wake/detector.sh

@@ -414,6 +414,22 @@ cmd_poll_once() {
   _wake_clean_stale_tmp "$STATE_DIR"
   mkdir -p "$DET_DIR"
 
+  local failed=0
+
+  # #958 preimage provenance: check the OPERATOR-SIDE preimage definition (the
+  # source adapter file, the watch-list, operator-declared extras) BEFORE
+  # observing any source. A changed preimage re-baselines EVERY source at once;
+  # running the check first means its first-class cause line is enqueued at a
+  # LOWER observed_seq than the N per-source deltas it explains, so the digest
+  # shows the cause, not just the flood. An infrastructure failure of the check
+  # is LOUD and marks this pass failed (G2a discipline — never read as "no
+  # change"), but source observation still proceeds: provenance must not be
+  # able to starve wake delivery.
+  if ! "$SCRIPT_DIR/preimage.sh" check --enqueue; then
+    echo "detector.sh: FAIL LOUD — preimage provenance check failed (see preimage.sh above); source observation continues but this pass exits non-zero." >&2
+    failed=1
+  fi
+
   # Iterate the DECLARED source-coverage inventory (§4/G3): only sources listed
   # in watches[].sources[] are polled. An omitted source is not observed (and so
   # cannot make anything pass vacuously); a referenced-but-undefined source is a
@@ -427,7 +443,7 @@ cmd_poll_once() {
     exit 2
   fi
 
-  local failed=0 kind id def class
+  local kind id def class
   while IFS=$'\t' read -r kind id; do
     [ -n "$kind" ] || continue
     # Resolve the source definition from its top-level collection by id.
@@ -513,7 +529,19 @@ cmd_run() {
         echo "detector.sh: WARN — off-host liveness beacon emit failed (see beacon.sh); the off-host absence check remains the authoritative dead-man." >&2
     fi
     [ "$once" -eq 1 ] && break
-    sleep "$interval"
+    # Close the detector lock fd in the sleep child; otherwise an orphaned sleep
+    # keeps the single-instance flock (fd 9, taken at exec 9> above) alive after
+    # the detector parent dies. The lock is non-blocking (`flock -n`, above), so
+    # for as long as that sleep survives a replacement instance is REFUSED and
+    # exits rather than queueing. This particular hold is BOUNDED by one poll
+    # interval (WAKE_DETECTOR_INTERVAL, default 30s): when the orphaned sleep
+    # exits its copy of fd 9 closes, ending this bounded sleep-child hold. It
+    # does NOT follow that the next start succeeds — other inheritors of fd 9
+    # (the M1 adapter, M2 sink grandchildren) are outside this patch's scope and
+    # can keep holding the flock. The cost this removes is a restart window in
+    # which every supervisor retry fails on the sleep child's account.
+    # `9>&-` closes ONLY the child's copy — the parent's lock is unaffected.
+    sleep "$interval" 9>&-
   done
 }
 

packages/mosaic/framework/tools/wake/digest.sh

@@ -112,6 +112,14 @@ Exit codes:
      diagnostic (#924/G2a) — it never wedges the whole render either.
      Reconciler enumerations (locators.reconciled==true) render ORIENTATION-tier,
      gate-exempt.
+     #946: quarantined entries are DISCLOSED in a QUARANTINED section (by
+     seq/class only — content stays excluded) and the embedded ack copy-run
+     line is CLAMPED below the lowest quarantined seq (the digest never
+     instructs the consumer to record a delivery that never happened; the
+     clamp is announced as an ACK CLAMPED note). A store-mode render also
+     REPLACES the store's quarantined.set (store.sh quarantine-sync) so the
+     consume path enforces the same clamp; --from-file/--stdin renders never
+     touch the set.
   2  usage error.
   3  jq is required but missing.
 
@@ -480,6 +488,19 @@ _dlq_alarm_offhost() {
 # A dead-letter write failure is itself alarmed (both legs) but never aborts the
 # drain — the good entries MUST still deliver (availability is the whole point of
 # #920).
+#
+# RETENTION IS LOAD-BEARING (#953) — read BEFORE adding rotation/pruning/caps:
+# this ledger is append-only history AND the SOLE evidence base for
+# store.sh quarantine-audit's conviction predicate (#946): a false
+# consumed-hashes witness row is provable ONLY while its matching entry
+# survives HERE. Any rotation, pruning, or size cap — however locally correct
+# — silently converts provable rows into unprovable ones, and the audit's
+# clean sweep reads IDENTICALLY before and after the evidence disappears (no
+# signal at either end; the audit never guesses, by design). If retention
+# limits ever become genuinely necessary, they MUST ship with (a) a loud
+# signal at prune time naming what evidence is being given up, and (b) the
+# audit's residual-class reporting updated IN THE SAME CHANGE. Until then:
+# nothing prunes this file, and that is a recorded decision, not an omission.
 _quarantine_entry() {
   local line="$1" seq="$2" dlq="$STATE_DIR/dead-letter.jsonl"
   if [ ! -f "$dlq" ] || ! grep -qxF "$line" "$dlq" 2>/dev/null; then
@@ -544,7 +565,7 @@ cmd_render() {
   # #920 head-of-line-blocking defect that exit-4'd the entire cumulative-state
   # drain). Reconciler enumerations (locators.reconciled==true) are ORIENTATION-
   # tier and gate-exempt, so they pass straight through to the deliverable set.
-  local line loc seq pending_ok='' quarantined=0
+  local line loc seq pending_ok='' quarantined=0 q_seqs='' q_disclose=''
   while IFS= read -r line; do
     [ -n "$line" ] || continue
     printf '%s' "$line" | jq -e . >/dev/null 2>&1 || continue
@@ -554,6 +575,17 @@ cmd_render() {
         seq="$(jq -r '.observed_seq // "?"' <<<"$line")"
         _quarantine_entry "$line" "$seq"
         quarantined=$((quarantined + 1))
+        # #946: collect the quarantined identity for DISCLOSURE + the ack
+        # CLAMP. Disclosure is by durable identity (observed_seq) + class ONLY:
+        # this entry failed the locator gate, so its content is exactly what
+        # this digest refuses to re-inject (the exclusion property Q1/Q4
+        # assert) — the consumer re-verifies via the dead-letter ledger, never
+        # via this line.
+        case "$seq" in
+        '' | *[!0-9]*) : ;; # an unnumbered entry cannot clamp the numeric cursor
+        *) q_seqs="$q_seqs$seq"$'\n' ;;
+        esac
+        q_disclose="$q_disclose  * seq $seq [$(_scrub_inline "$(jq -r '.class // "actionable"' <<<"$line")")] HELD — dead-lettered (no §2.1 hard locator); content withheld, NOT delivered."$'\n'
         continue
       fi
     fi
@@ -563,6 +595,33 @@ cmd_render() {
   pending="$(printf '%s' "$pending_ok" | grep -v '^[[:space:]]*$' || true)"
   depth="$(printf '%s\n' "$pending" | grep -c . || true)"
 
+  # --- #946: quarantine truth-sync + ack clamp ------------------------------
+  # (1) SYNC: an AUTHORITATIVE full-set render (src=store) REPLACES the store's
+  # quarantined.set with THIS render's quarantined seqs (possibly none — an
+  # empty replace IS the #944 recovery: once the gate is fixed and everything
+  # renders, the stale set clears and the store-side clamp self-heals). A
+  # foreign-data render (--from-file/--stdin) must NEVER rewrite lane truth.
+  if [ "$src" = "store" ]; then
+    if ! printf '%s' "$q_seqs" | "$STORE_SH" quarantine-sync; then
+      echo "digest.sh: WARN (#946) — store.sh quarantine-sync FAILED; the store-side consume clamp may be stale for this lane (the clamped ack line rendered below is still correct)." >&2
+    fi
+  fi
+  # (2) CLAMP: the embedded ack may advance AT MOST to just below the LOWEST
+  # quarantined seq — consume requires a contiguous prefix, so one held seq
+  # caps everything above it. With nothing quarantined this is the observed
+  # cursor unchanged. Render-local on purpose: it protects the copy-run line in
+  # EVERY mode, including hermetic --from-file renders.
+  local ack_upto="$observed" min_q='' qs q_list=''
+  while IFS= read -r qs; do
+    [ -n "$qs" ] || continue
+    if [ -z "$min_q" ] || [ "$qs" -lt "$min_q" ]; then min_q="$qs"; fi
+  done <<<"$q_seqs"
+  if [ -n "$min_q" ] && [ "$((min_q - 1))" -lt "$ack_upto" ]; then
+    ack_upto=$((min_q - 1))
+  fi
+  [ "$ack_upto" -ge 0 ] || ack_upto=0
+  q_list="$(printf '%s' "$q_seqs" | tr '\n' ' ' | sed -e 's/[[:space:]]*$//')"
+
   # --- render (all validated) ----------------------------------------------
   local n_actionable=0
   {
@@ -656,6 +715,16 @@ cmd_render() {
       printf '%s\n' "$hbody"
     fi
 
+    # #946: QUARANTINED disclosure — a held entry must be VISIBLE in the digest
+    # it was held from (five successive live digests each silently stepped the
+    # consumer past buried seq 68). Disclosure is by seq/class ONLY; the
+    # entry's content already failed the locator gate and stays EXCLUDED.
+    if [ -n "$q_disclose" ]; then
+      printf '\n-- QUARANTINED (dead-lettered; HELD — NOT delivered; the ack below does NOT cover these) --\n'
+      printf '%s' "$q_disclose"
+      printf '  disposition: see %s/dead-letter.jsonl — fix the source locator (re-delivery is automatic once the entry passes the gate), or step past EXPLICITLY with ack.sh consumed --force-past-quarantine.\n' "$STATE_DIR"
+    fi
+
     # Embedded ack copy-run line (W2). CONSUMED is a consumer act; this is the
     # exact local-write line the consumer runs after durable capture.
     #
@@ -670,12 +739,19 @@ cmd_render() {
     # itself was env-less (agent=="default"), baking "default" is no worse than
     # today — the fix wins the common case where WAKE_AGENT was set at render.
     printf '\n-- ACK (copy-run; local-write only, never blocks on network) --\n'
+    # #946: the embedded --upto is the CLAMPED cursor (ack_upto), never the raw
+    # observed cursor while a quarantined seq sits inside (consumed, observed] —
+    # the copy-run line itself must not instruct the consumer to record
+    # deliveries that never happened. The clamp is disclosed loudly.
+    if [ "$ack_upto" -ne "$observed" ]; then
+      printf '# ACK CLAMPED (#946): embedding --upto %s, not observed_seq %s — quarantined seq(s) %s were dead-lettered and NEVER delivered; an ordinary ack cannot step past them. Only ack.sh consumed ... --force-past-quarantine (loud) can.\n' "$ack_upto" "$observed" "$q_list"
+    fi
     local ack_line agent_scrubbed
     agent_scrubbed="$(_scrub_inline "$agent")"
     if [ -n "$wake_id" ]; then
-      ack_line="$("$ACK_SH" embed --upto "$observed" --agent "$agent_scrubbed" --wake-id "$wake_id" 2>/dev/null || true)"
+      ack_line="$("$ACK_SH" embed --upto "$ack_upto" --agent "$agent_scrubbed" --wake-id "$wake_id" 2>/dev/null || true)"
     else
-      ack_line="$("$ACK_SH" embed --upto "$observed" --agent "$agent_scrubbed" 2>/dev/null || true)"
+      ack_line="$("$ACK_SH" embed --upto "$ack_upto" --agent "$agent_scrubbed" 2>/dev/null || true)"
     fi
     printf '%s\n' "${ack_line:-# ack unavailable}"
   } | _redact_secrets

packages/mosaic/framework/tools/wake/manifest.txt

@@ -347,8 +347,144 @@
 #              "one targeted call, never a search" (NOT "pins the observed
 #              state") — sequenced AFTER the reseed so the edit itself is a
 #              live delivery test of the fixed gate.
+#   0.6.15 #946 the digest's embedded ack watermark covered quarantined
+#              entries: quarantine is a render-time filter (0.6.14), so the
+#              suggested `ack.sh consumed --upto <observed_seq>` stepped the
+#              cursor PAST dead-lettered seqs and _record_last_consumed then
+#              wrote consumed-hash witness rows for deliveries that never
+#              happened (live: mos-dt seq 68 buried under five digests;
+#              Finding A: a false 9d0f639f…@63 witness row). Fix — disclose
+#              AND clamp: (1) the rendered digest gains a QUARANTINED section
+#              (seq + class + HELD only; ids/locators stay withheld,
+#              preserving the exclusion property) and the embedded ack is
+#              clamped to min(observed_seq, min quarantined seq − 1);
+#              (2) store.sh consume REFUSES to cross an unconsumed
+#              quarantined seq — `--force-past-quarantine` (plumbed through
+#              ack.sh consumed) is the ONLY way past, loud per-seq on stderr,
+#              and even the forced path never writes a consumed-hash witness
+#              for a quarantined seq; (3) render --from-store syncs the
+#              store-owned quarantined.set via new `store.sh quarantine-sync`
+#              (full-replace, so a gate fix self-heals stale quarantine;
+#              --from-file/--stdin never touch the set); (4) new
+#              `store.sh quarantine-audit [--repair]` sweeps consumed-hashes
+#              for rows provably contradicted by the dead-letter ledger
+#              (report exits 1; --repair removes only provably-false rows;
+#              the ledger itself is history and is never modified; rows whose
+#              dead-letter evidence was pruned are unprovable and untouched).
+#              Changed: store.sh, digest.sh, ack.sh
+#              (+ test-wake-store-ack.sh T13-T16,
+#              test-wake-digest-quarantine.sh Q12-Q16).
+#   0.7.0  #958 A11 preimage.sh — durable provenance for the OPERATOR-SIDE
+#              preimage definition (wake-pilot finding: source-adapter.sh was
+#              unversioned, so the operator-owned bytes every observed_hash is
+#              computed FROM had thinner provenance than any hash they feed;
+#              attribution required an agent transcript). NEW tool + two
+#              pre-step integrations, ADDITIVE: (1) preimage.sh derives the
+#              preimage set from the RUNTIME env (the resolved
+#              WAKE_DETECTOR_SOURCE_CMD file, WAKE_WATCH_LIST, optional
+#              WAKE_PREIMAGE_EXTRA paths) and, per file, records
+#              {ts,path,sha256,size,mtime,prev} to an append-only ledger +
+#              captures the bytes CONTENT-ADDRESSED under
+#              $STATE_DIR/preimage/objects/<sha256> — prior bytes + change
+#              time are answerable from durable state alone, no transcript
+#              (acceptance a). A git-repo-in-operator-dir design was REJECTED:
+#              its who/why claim is false under shared-author fleets, and
+#              .gitignore is pattern-based where acceptance (b) demands
+#              fail-closed. (2) CREDENTIAL HARD GATE (acceptance b), FOUR
+#              LAYERS (#964 re-verdict: B2 cases C+D): (i) POLARITY — extras
+#              (WAKE_PREIMAGE_EXTRA) are RECORD-ONLY by default (ledger row +
+#              cause line, NO bytes); byte capture for an extra requires the
+#              path listed in WAKE_PREIMAGE_CAPTURE (colon-separated opt-in);
+#              only the core set (adapter, watch-list) is capture-eligible by
+#              default — a shape list can only refuse the secrets someone
+#              already enumerated, so safety may not rest on one (#964-D).
+#              (ii) PATH DENY evaluated on BOTH the raw and realpath-resolved
+#              candidate forms against BOTH unresolved and resolved
+#              mosaic-home anchors (credentials.json,
+#              tools/_lib/credentials.json, credentials/**, any basename
+#              credentials.json) — a deny list written in unresolved paths
+#              cannot match a path resolved before it arrived (#964-C), and a
+#              symlinked opt-in entry cannot smuggle a denied target (deny
+#              runs FIRST, independent of what the opt-in matched). (iii)
+#              CONTENT DENY on the opt-in path only, defense-in-depth NOT the
+#              safety mechanism: digest.sh's six scrub shapes + a
+#              named-assignment probe (key/token/secret/passw/hmac/credential/
+#              bearer = unbroken value >=16 chars); probe ERROR fails TOWARD
+#              refusal (an error exit is not a negative result); false
+#              positives are acceptable — a false match only withholds byte
+#              capture, never tracking. (iv) size cap WAKE_PREIMAGE_MAX_BYTES
+#              (default 1 MiB). Deny ALWAYS wins over the opt-in. A refused
+#              file still gets its hash/size/mtime row (captured:false +
+#              refused reason) so change TIME survives even when content must
+#              not. (3) FIRST-CLASS CAUSE LINE
+#              (acceptance c): on a change (or deletion — ABSENT is a state,
+#              not an error), one class=actionable entry is enqueued via the
+#              store allocator with locators {kind:preimage, path (§2.1 hard
+#              locator — never quarantined), observed_hash, prev_hash,
+#              preimage:true, reason:preimage-definition-changed}. Both
+#              detector.sh cmd_poll_once and reconcile.sh cmd_reconcile run
+#              the check as a PRE-step, so the cause line lands at a LOWER
+#              observed_seq than the N per-source deltas/enumerations it
+#              explains — "preimage definition changed" reads first, not N
+#              UNACCOUNTED lines. (4) FAIL-LOUD discipline (D2/#955 class):
+#              an unresolvable adapter, unreadable watch-list, corrupt ledger
+#              (REFUSES to compare or re-baseline over corrupt history), failed
+#              object/ledger write, or failed enqueue is a loud non-zero —
+#              never read as "no change"; in both integrations the pass exits
+#              non-zero but source observation still proceeds (no starvation).
+#              An ABSENT/EMPTY ledger with objects/ NON-empty is a loud
+#              non-zero REFUSAL to re-baseline (#964-B11: objects with no
+#              ledger cannot be a first install — history was deleted; the
+#              first-install path must not silently absorb it). First-seen on
+#              a genuinely clean state dir is a SILENT baseline (detector
+#              first-poll idiom).
+#              The installer is UNCHANGED — Gate A auto-enumerates the new
+#              file from the filesystem; the recording site is the runtime
+#              tick, which is where the env-derived preimage set exists.
+#              store.sh/digest.sh/beacon.sh UNCHANGED; watch-list schema
+#              UNTOUCHED ([1,1]). Changed: preimage.sh (new), detector.sh,
+#              reconcile.sh (+ test-wake-preimage.sh P1-P17; P13-P17 are the
+#              #964 re-verdict regression needles: symlinked store, live
+#              secret value, polarity, ledger deletion, allowlist-symlink).
+#   0.7.1  #952 quarantine-audit clean-sweep message named only ONE of the
+#              two unprovable residual classes ("rows without surviving
+#              dead-letter evidence"), so an operator reading the OK concluded
+#              NO evidence exists when evidence can exist and be UNUSABLE: a
+#              surviving dead-letter row whose locator extracts an empty
+#              observed_hash (live specimen: mos-dt seq 13,
+#              bench/malformed-locator-test, "deliberately non-conformant")
+#              can never satisfy the four-field conviction match, because
+#              _record_last_consumed only writes rows with a NON-empty hash.
+#              WORDING-ONLY fix (measurement defect, #951 review finding 1):
+#              THREE surfaces — the clean-sweep message, the PROVABILITY
+#              BOUND comment, and (second commit, author-side self-catch)
+#              the usage() help text — now name both classes; the
+#              conviction predicate is UNCHANGED.
+#              Test T17 drives the real writer flow and plants the verbatim
+#              live specimen (nested .locators.*, NO observed_hash key) —
+#              never a hand-built flat dead-letter row, which would make the
+#              audit's correct non-conviction look exactly like the defect
+#              under hunt (the #951 review's false-defect near-miss).
+#   0.7.2  #973 three-valued grep verdicts across ALL TEN wake test suites.
+#              grep's exit contract is three-valued (0 match / 1 no-match /
+#              >=2 ERROR); every suite assertion read non-zero as "absent",
+#              so a grep that COULD NOT LOOK wore the colour of a verdict —
+#              OR-polarity sites failed falsely RED, AND-polarity sites
+#              (including all 19 credential canaries) failed falsely GREEN
+#              under load. _wake-common.sh gains has_match/count_lines
+#              (rc 0/1 pass through; anything else LOUDLY ABORTS the whole
+#              suite naming file:line + raw rc — an error is never a
+#              verdict), wake_assert_init (saved-fd abort loudness that
+#              survives call-site 2>/dev/null + a runtime pin of the
+#              BASH_LINENO coordinate convention against CI bash drift),
+#              and 261 call sites converted mechanically from a frozen
+#              denominator artifact. Production tools source but never call
+#              the helpers; suite verdict semantics on rc 0/1 are UNCHANGED.
+#              Evidence chain in validate-973/ (microtest C1-C11, expected/
+#              static/trace set arithmetic, 21 forced-error arms, residual
+#              sweep with per-form plants).
 component=wake
-version=0.6.14
+version=0.7.2
 
 # Watch-list schema this component consumes, and the INCLUSIVE range of
 # schema_version values it supports. A wake-watch-list.json whose schema_version
@@ -419,6 +555,19 @@ schema_max=1
 #                    seed) instead of a bare source error, and LINKS the unit into
 #                    the user systemd search path + post-install-validates it
 #                    resolves (#913).                                       (W7, #913)
+#   preimage.sh A11 — operator-side PREIMAGE-DEFINITION provenance: derives the
+#                    preimage set from the runtime env (resolved adapter file,
+#                    watch-list, WAKE_PREIMAGE_EXTRA), appends
+#                    {ts,path,sha256,size,mtime,prev} rows to an append-only
+#                    ledger, captures bytes content-addressed under
+#                    preimage/objects/<sha256>, and enqueues a FIRST-CLASS
+#                    "preimage-definition-changed" actionable (path = §2.1 hard
+#                    locator) BEFORE the deltas it explains (detector +
+#                    reconcile pre-step). Credential HARD GATE: capture is
+#                    REFUSED (hash/mtime still recorded) for credential-store
+#                    paths, secret-shaped content, and oversized files —
+#                    refusal, never redaction. Fail-loud on any infra failure;
+#                    a corrupt ledger refuses re-baseline.        (#958)
 # Companion (framework subtree, not under tools/wake/): systemd/user/mosaic-wake.service
 #                    — the long-lived detector daemon unit (per-class SLO lives in
 #                    the daemon, NOT a systemd interval).                          (W7)

packages/mosaic/framework/tools/wake/preimage.sh

@@ -0,0 +1,571 @@
+#!/usr/bin/env bash
+# preimage.sh — A11 of the wake canon (#958): durable PROVENANCE for the
+# OPERATOR-SIDE preimage definition.
+#
+# THE GAP THIS CLOSES (#958): every observed_hash in the lane store is
+# sha256(adapter stdout) — the operator's source adapter (plus the watch-list
+# and any operator-declared preimage files) IS the preimage definition for
+# every hash the pipeline ever records. Those files live OUTSIDE the versioned
+# wake component, so a byte change to them was attributable only through agent
+# transcripts: provenance thinner than any hash it feeds. A changed preimage
+# also re-baselines EVERY source at once, which previously surfaced only as N
+# per-source deltas / UNACCOUNTED lines with no first-class cause.
+#
+# WHAT THIS TOOL DOES:
+#   - Derives the PREIMAGE SET generically (no operator paths baked in):
+#       * the resolved file behind WAKE_DETECTOR_SOURCE_CMD (first word),
+#       * the WAKE_WATCH_LIST file,
+#       * operator-declared extras via WAKE_PREIMAGE_EXTRA (colon-separated —
+#         e.g. sink/feed scripts). Extras are RECORD-ONLY by default (see the
+#         credential hard gate below); never list key-material files.
+#   - Records each file's (sha256, size, mtime, ts) as an APPEND-ONLY ledger
+#     row in <state>/preimage/preimage-ledger.jsonl and stores the full bytes
+#     CONTENT-ADDRESSED at <state>/preimage/objects/<sha256> — so a change is
+#     attributable (prior bytes + change time) from durable state alone, with
+#     no transcript required. Acceptance (a) of #958.
+#   - On a CHANGE (not first-seen), `check --enqueue` enqueues ONE first-class
+#     class=actionable entry per changed file via the store's single allocator
+#     (#908), carrying a §2.1 hard locator (`path`), BEFORE the per-source
+#     deltas it explains are observed — so the digest shows the cause line,
+#     not just N re-baselined sources. Acceptance (c).
+#
+# CREDENTIAL HARD GATE — acceptance (b): the mechanism must be UNABLE to
+# capture credential material even by operator error. Layered, every layer
+# fail-closed toward NOT capturing bytes (the hash/size/mtime row is still
+# written — change-time attribution survives, content capture does not;
+# a sha256 discloses nothing about the bytes):
+#   1. POLARITY (#964 review, case D): byte capture is DENY-BY-DEFAULT for
+#      operator extras. WAKE_PREIMAGE_EXTRA paths are RECORD-ONLY (rows +
+#      first-class change entries, no bytes) unless explicitly listed in
+#      WAKE_PREIMAGE_CAPTURE — a shape list can only refuse the secrets
+#      someone already enumerated, so arbitrary operator-pointed files must
+#      not default to capture. The CORE set (the resolved adapter file, the
+#      watch-list) is capture-eligible: it IS the preimage definition this
+#      tool exists to snapshot, and the deny layers below still apply to it.
+#   2. PATH deny: the mosaic credential store locations
+#      (<mosaic-home>/credentials.json, <mosaic-home>/tools/_lib/
+#      credentials.json, anything under <mosaic-home>/credentials/, and any
+#      file literally named credentials.json) are refused. Evaluated on BOTH
+#      the operator-supplied form AND the symlink-resolved form, against BOTH
+#      the unresolved and resolved forms of the mosaic-home anchor — a deny
+#      list written only in unresolved paths cannot match a path that was
+#      resolved before it arrived (#964 review, case C).
+#   3. CONTENT deny: a candidate whose bytes match the well-known secret-token
+#      shapes (same conservative set digest.sh redacts: PAT/Slack/AKIA/JWT/PEM)
+#      OR a named-assignment secret shape (key/token/secret/passw/hmac/
+#      credential/bearer = long unbroken value — catches prefix-less
+#      high-entropy keys, e.g. an HMAC key in an env file) is refused —
+#      refusal, not redaction: a redacted preimage would be a false witness,
+#      and secret bytes must never land in the object store. Deliberately
+#      conservative toward REFUSAL: a false match only withholds byte capture,
+#      never tracking.
+#   Plus a size cap (WAKE_PREIMAGE_MAX_BYTES, default 1 MiB) so a stray extra
+#   pointing at a large binary cannot turn provenance into data hoovering.
+#   Deny ALWAYS wins over the WAKE_PREIMAGE_CAPTURE opt-in.
+#
+# FAIL-LOUD DISCIPLINE (the D2/#955 class, both layers): an infrastructure
+# failure of THIS tool (unresolvable adapter, unreadable/corrupt ledger,
+# failed durable write, failed enqueue) exits NON-ZERO and is never read as
+# "no change". A corrupt ledger REFUSES to compare (and to re-baseline):
+# silently restarting history would erase the very attribution this exists
+# to provide. Likewise (#964 review, B11) an ABSENT/EMPTY ledger while
+# objects/ still holds prior captures is DELETED HISTORY, not a first
+# install — it refuses loudly instead of re-baselining, because a silent
+# restart would absorb the next real change as first-seen.
+#
+# Operator-agnostic (framework firewall): all state via XDG/env; the deny
+# list names only framework-defined credential locations, no operator hosts/
+# names/secrets. This tool never prints file CONTENT to any stream.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./_wake-common.sh disable=SC1091
+. "$SCRIPT_DIR/_wake-common.sh"
+
+STATE_DIR="$(wake_state_dir)"
+STORE_SH="$SCRIPT_DIR/store.sh"
+PRE_DIR="$STATE_DIR/preimage"
+LEDGER="$PRE_DIR/preimage-ledger.jsonl"
+OBJECTS="$PRE_DIR/objects"
+
+_need_jq() {
+  command -v jq >/dev/null 2>&1 || {
+    echo "preimage.sh: jq is required" >&2
+    exit 3
+  }
+}
+
+# _hash_stdin — sha256 of stdin, first field only (portable, same fallback
+# chain as detector.sh).
+_hash_stdin() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 | awk '{print $1}'
+  elif command -v openssl >/dev/null 2>&1; then
+    openssl dgst -sha256 | awk '{print $NF}'
+  else
+    echo "preimage.sh: no sha256 tool (sha256sum/shasum/openssl) available" >&2
+    exit 3
+  fi
+}
+
+usage() {
+  cat >&2 <<'EOF'
+Usage: preimage.sh <command>
+
+Commands:
+  check [--enqueue]   Compare every preimage-set file against the ledger head.
+                      A changed file gets a new ledger row (+ captured bytes
+                      when capture-eligible and not denied — see Environment);
+                      with --enqueue each change (not first-seen) also enqueues
+                      ONE first-class class=actionable store entry (hard
+                      locator: path). First-seen files baseline SILENTLY (row,
+                      no enqueue — same idiom as the detector's first-seen).
+                      Exit 0 whether or not changes were found; non-zero ONLY
+                      on infrastructure failure (never read as "no change").
+  record              Alias of `check` without enqueue (baseline/refresh).
+  set                 Print the derived preimage set, one resolved path per
+                      line (diagnostic).
+  status              Print the ledger head row for every tracked path.
+
+Environment:
+  WAKE_DETECTOR_SOURCE_CMD  Adapter command; its resolved file joins the set.
+  WAKE_WATCH_LIST           Watch-list path; joins the set when set.
+  WAKE_PREIMAGE_EXTRA       Colon-separated additional operator preimage files
+                            (e.g. sink/feed scripts). Extras are RECORD-ONLY
+                            by default: changes get a hash/size/mtime row and
+                            a first-class change entry, but their BYTES are
+                            never captured unless the path is also listed in
+                            WAKE_PREIMAGE_CAPTURE. A listed path that does not
+                            exist is tracked as ABSENT (deletion of a preimage
+                            file is a change, not an error).
+  WAKE_PREIMAGE_CAPTURE     Colon-separated allowlist of extras whose bytes
+                            MAY be captured. The credential deny rules ALWAYS
+                            win over this list. NEVER list files that can hold
+                            key material (env files with keys/HMACs, credential
+                            stores): the deny gate is a backstop, not a
+                            license.
+  WAKE_PREIMAGE_MAX_BYTES   Byte-capture cap (default 1048576). Larger files:
+                            hash/size/mtime recorded, bytes refused.
+  WAKE_STATE_HOME/WAKE_AGENT  store namespace (see store.sh).
+EOF
+}
+
+# --- preimage-set derivation (generic; no operator paths baked in) ----------
+
+# _realpath_or_self PATH — resolved form when resolvable, the input otherwise.
+_realpath_or_self() {
+  local p="$1"
+  if command -v realpath >/dev/null 2>&1; then
+    realpath -- "$p" 2>/dev/null || printf '%s' "$p"
+  else
+    printf '%s' "$p"
+  fi
+}
+
+# _resolve_cmd_file CMD — resolve the FIRST WORD of an adapter command string
+# to a real file; prints `raw<TAB>resolved`. Non-zero (loud) if it cannot be
+# resolved: an adapter the detector will invoke but provenance cannot see is
+# an infrastructure failure, not a smaller set. BOTH forms are kept: the deny
+# gate must see the pre-resolution form too (#964 review, case C).
+_resolve_cmd_file() {
+  local cmd="$1" word path
+  # shellcheck disable=SC2086
+  set -- $cmd
+  word="${1:-}"
+  [ -n "$word" ] || return 1
+  if [ -f "$word" ]; then
+    path="$word"
+  else
+    path="$(command -v -- "$word" 2>/dev/null)" || return 1
+    [ -f "$path" ] || return 1
+  fi
+  # realpath so the ledger keys on the actual file, not a symlink alias.
+  printf '%s\t%s' "$path" "$(_realpath_or_self "$path")"
+}
+
+# _preimage_set — print the derived set, one member per line as
+# `origin<TAB>raw<TAB>resolved` (origin: core|extra). BOTH path forms travel
+# with every member so the deny gate and the capture allowlist are evaluated
+# on the SAME candidate in BOTH its forms — resolving before denying is the
+# #964 case-C ordering defect. Paths from WAKE_PREIMAGE_EXTRA are printed
+# EVEN IF ABSENT (deletion is a tracked state); the adapter and watch-list
+# must resolve (loud failure otherwise — see _resolve_cmd_file rationale).
+_preimage_set() {
+  local failed=0
+  if [ -n "${WAKE_DETECTOR_SOURCE_CMD:-}" ]; then
+    local af
+    if af="$(_resolve_cmd_file "$WAKE_DETECTOR_SOURCE_CMD")"; then
+      printf 'core\t%s\n' "$af"
+    else
+      echo "preimage.sh: FAIL LOUD — WAKE_DETECTOR_SOURCE_CMD ('$WAKE_DETECTOR_SOURCE_CMD') does not resolve to a file; the preimage definition cannot be observed (NOT treated as 'no change')." >&2
+      failed=1
+    fi
+  fi
+  if [ -n "${WAKE_WATCH_LIST:-}" ]; then
+    if [ -f "$WAKE_WATCH_LIST" ]; then
+      printf 'core\t%s\t%s\n' "$WAKE_WATCH_LIST" "$(_realpath_or_self "$WAKE_WATCH_LIST")"
+    else
+      echo "preimage.sh: FAIL LOUD — WAKE_WATCH_LIST ('$WAKE_WATCH_LIST') is not a file; the preimage definition cannot be observed." >&2
+      failed=1
+    fi
+  fi
+  if [ -n "${WAKE_PREIMAGE_EXTRA:-}" ]; then
+    local IFS=':' p
+    for p in $WAKE_PREIMAGE_EXTRA; do
+      [ -n "$p" ] || continue
+      # Extras are tracked even when absent (ABSENT is a state). Resolve the
+      # realpath only when the file exists; otherwise track the literal path.
+      if [ -e "$p" ]; then
+        printf 'extra\t%s\t%s\n' "$p" "$(_realpath_or_self "$p")"
+      else
+        printf 'extra\t%s\t%s\n' "$p" "$p"
+      fi
+    done
+  fi
+  return "$failed"
+}
+
+# --- credential hard gate (acceptance (b)) ----------------------------------
+
+# _deny_path RAW RESOLVED — 0 (deny) iff EITHER form of the candidate names a
+# known credential-store location. Framework-defined locations only
+# (firewall): the mosaic credential store, the tools/_lib credential file the
+# framework-manifest itself carves out of tools/**, the credentials/ operator
+# subtree, and any file literally named credentials.json.
+#
+# Evaluated on BOTH the operator-supplied (raw) form and the symlink-resolved
+# form, against BOTH the unresolved and resolved forms of the mosaic-home
+# anchor: a deny list written only in unresolved paths cannot match a path
+# that was resolved before it arrived (#964 review, case C — a symlink whose
+# target was renamed slipped every path rule because the candidate had
+# already been realpath'd but the anchors never were).
+_deny_path() {
+  local raw="$1" resolved="$2"
+  local home="${MOSAIC_HOME:-$HOME/.config/mosaic}" rhome p a
+  rhome="$(_realpath_or_self "$home")"
+  for p in "$raw" "$resolved"; do
+    [ -n "$p" ] || continue
+    for a in "$home" "$rhome"; do
+      case "$p" in
+      "$a/credentials.json") return 0 ;;
+      "$a/tools/_lib/credentials.json") return 0 ;;
+      "$a/credentials/"*) return 0 ;;
+      esac
+    done
+    case "$(basename -- "$p")" in
+    credentials.json) return 0 ;;
+    esac
+  done
+  return 1
+}
+
+# _deny_content FILE — 0 (deny) iff FILE's bytes look secret-shaped.
+# Two probes: (a) the well-known vendor-token shapes digest.sh redacts
+# (PAT / Slack / AKIA / JWT / PEM — conservative: a 40-hex git sha never
+# matches); (b) a named-assignment shape (key/token/secret/passw/hmac/
+# credential/bearer = long unbroken value) that catches prefix-less
+# high-entropy keys, e.g. an HMAC key in an env file (#964 review, case D).
+#
+# (b) is defense-in-depth for the OPT-IN path only, NOT the thing that keeps
+# case D safe — polarity does that (extras are record-only unless allowlisted;
+# a shape list can only refuse the secrets someone already enumerated). It is
+# deliberately conservative toward REFUSAL: a false match (a checksum in a
+# config, a path that happens to be long and unbroken) only withholds byte
+# capture — the hash/size/mtime row and change entry still land. A variable
+# REFERENCE (token="$GITEA_TOKEN") never matches: `$` is not in the value
+# class — only literal secret values do.
+#
+# FAILS TOWARD REFUSAL: if a probe itself errors (unreadable file, grep
+# failure — rc >= 2), the answer is DENY, not capture. An error exit is not a
+# negative result.
+_deny_content() {
+  local rc
+  LC_ALL=C grep -Eq \
+    -e 'gh[pousr]_[A-Za-z0-9]{16,}' \
+    -e 'github_pat_[A-Za-z0-9_]{16,}' \
+    -e 'xox[baprs]-[A-Za-z0-9-]{10,}' \
+    -e 'AKIA[0-9A-Z]{16}' \
+    -e 'eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}' \
+    -e '-----BEGIN[A-Z ]*PRIVATE KEY-----' \
+    -- "$1" 2>/dev/null
+  rc=$?
+  [ "$rc" -eq 1 ] || return 0
+  LC_ALL=C grep -Eiq \
+    -e "[A-Za-z0-9_]*(key|token|secret|passw|hmac|credential|bearer)[A-Za-z0-9_]*[[:space:]]*[=:][[:space:]]*[\"']?[A-Za-z0-9+/=_-]{16,}" \
+    -- "$1" 2>/dev/null
+  rc=$?
+  [ "$rc" -eq 1 ] || return 0
+  return 1
+}
+
+# _capture_allowed ORIGIN RAW RESOLVED — 0 iff byte capture may even be
+# ATTEMPTED for this member (the deny gate still runs after, and wins).
+# POLARITY (#964 review, case D): core members (the adapter file, the
+# watch-list) are capture-eligible — they ARE the preimage definition this
+# tool exists to snapshot (acceptance (a)). Extras are RECORD-ONLY unless
+# listed in WAKE_PREIMAGE_CAPTURE.
+#
+# The allowlist is matched with the SAME both-forms discipline as the deny
+# list (entry raw/resolved vs candidate raw/resolved): two lists keyed on
+# different strings would let a symlink alias slip between them. "Deny wins
+# over opt-in" is a precedence rule, not a guarantee both lists see the same
+# path — the guarantee comes from _check_one running _deny_path on both forms
+# FIRST, independent of anything matched here.
+_capture_allowed() {
+  local origin="$1" raw="$2" resolved="$3"
+  [ "$origin" = "core" ] && return 0
+  [ -n "${WAKE_PREIMAGE_CAPTURE:-}" ] || return 1
+  local IFS=':' e er
+  for e in $WAKE_PREIMAGE_CAPTURE; do
+    [ -n "$e" ] || continue
+    er="$e"
+    [ -e "$e" ] && er="$(_realpath_or_self "$e")"
+    if [ "$e" = "$raw" ] || [ "$e" = "$resolved" ] ||
+      [ "$er" = "$raw" ] || [ "$er" = "$resolved" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# --- ledger primitives ------------------------------------------------------
+
+# _ledger_head PATH — print the LAST ledger row for PATH (empty if none).
+# Non-zero (loud) if the ledger exists but is unparseable: a corrupt ledger
+# must REFUSE to compare, never silently re-baseline (that would erase the
+# attribution history this tool exists to keep).
+_ledger_head() {
+  local path="$1"
+  [ -f "$LEDGER" ] || return 0
+  if [ -s "$LEDGER" ] && ! jq -cn 'inputs' <"$LEDGER" >/dev/null 2>&1; then
+    echo "preimage.sh: FAIL LOUD — preimage ledger $LEDGER is unparseable; REFUSING to compare or re-baseline over corrupt history. Investigate/restore the ledger." >&2
+    return 1
+  fi
+  jq -c --arg p "$path" 'select(.path == $p)' "$LEDGER" 2>/dev/null | tail -n 1
+}
+
+# _ledger_append ROW_JSON — append one row atomically (read + append + rename;
+# rows are small and the writer is serialized by the preimage lock).
+_ledger_append() {
+  local row="$1"
+  {
+    [ -f "$LEDGER" ] && cat "$LEDGER"
+    printf '%s\n' "$row"
+  } | _atomic_write "$LEDGER"
+}
+
+# --- the check itself -------------------------------------------------------
+
+# _check_one ORIGIN RAW PATH ENQUEUE — compare PATH (the resolved form; the
+# ledger keys on it) to its ledger head; on change record (+bytes only if
+# capture-eligible and not denied) and optionally enqueue. Prints nothing on
+# no-change. Returns: 0 ok (changed or not), 1 infrastructure failure.
+_check_one() {
+  local origin="$1" raw="$2" path="$3" enqueue="$4"
+  local cur_sha size mtime denied="" refused=""
+
+  if [ -f "$path" ]; then
+    cur_sha="$(_hash_stdin <"$path")" || return 1
+    [ -n "$cur_sha" ] || {
+      echo "preimage.sh: FAIL LOUD — could not hash $path" >&2
+      return 1
+    }
+    size="$(wc -c <"$path" | tr -d '[:space:]')"
+    # Portable mtime (GNU stat -c / BSD stat -f).
+    mtime="$(stat -c %Y -- "$path" 2>/dev/null || stat -f %m -- "$path" 2>/dev/null || echo 0)"
+    local cap="${WAKE_PREIMAGE_MAX_BYTES:-1048576}"
+    case "$cap" in '' | *[!0-9]*) cap=1048576 ;; esac
+    # Gate order matters: path deny FIRST, on BOTH forms, INDEPENDENT of the
+    # capture allowlist — so an allowlisted symlink whose target is denied
+    # refuses no matter what string the allowlist matched (a known credential
+    # store is refused without a content probe; the hash read above is
+    # deliberate: a sha256 discloses nothing about the bytes). Then polarity
+    # (record-only extras never reach the content probe — case D must be safe
+    # WITHOUT the shape list), then size cap (never content-grep an oversized
+    # file), content shape last.
+    if _deny_path "$raw" "$path"; then
+      denied="credential-store path (deny list)"
+    elif ! _capture_allowed "$origin" "$raw" "$path"; then
+      denied="extra is record-only by default (byte capture requires WAKE_PREIMAGE_CAPTURE; deny rules still win)"
+    elif [ "$size" -gt "$cap" ]; then
+      denied="exceeds WAKE_PREIMAGE_MAX_BYTES ($size > $cap)"
+    elif _deny_content "$path"; then
+      denied="secret-shaped content"
+    fi
+  else
+    # ABSENT is a state (deletion of a preimage file is a change to record).
+    cur_sha="ABSENT"
+    size=0
+    mtime=0
+  fi
+
+  local head prev_sha=""
+  head="$(_ledger_head "$path")" || return 1
+  [ -n "$head" ] && prev_sha="$(jq -r '.sha256 // ""' <<<"$head")"
+
+  if [ "$cur_sha" = "$prev_sha" ]; then
+    return 0 # unchanged — no row, no enqueue (idempotent)
+  fi
+
+  # --- capture bytes (content-addressed) unless the hard gate refuses -------
+  local captured=true
+  if [ "$cur_sha" != "ABSENT" ]; then
+    if [ -n "$denied" ]; then
+      captured=false
+      refused="$denied"
+      echo "preimage.sh: byte capture WITHHELD for $path ($denied) — hash/size/mtime recorded, content NOT stored (#958)." >&2
+    else
+      mkdir -p "$OBJECTS" || return 1
+      if [ ! -f "$OBJECTS/$cur_sha" ]; then
+        if ! _atomic_write "$OBJECTS/$cur_sha" <"$path"; then
+          echo "preimage.sh: FAIL LOUD — durable object write failed for $path ($OBJECTS/$cur_sha); NO ledger row recorded (a row whose bytes were never durably kept would be a false witness)." >&2
+          return 1
+        fi
+      fi
+    fi
+  fi
+
+  local ts row
+  ts="$(date +%s)"
+  row="$(jq -cn \
+    --arg path "$path" \
+    --arg sha "$cur_sha" \
+    --arg prev "$prev_sha" \
+    --argjson size "$size" \
+    --argjson mtime "$mtime" \
+    --argjson ts "$ts" \
+    --argjson captured "$captured" \
+    --arg refused "$refused" \
+    '{ts:$ts, path:$path, sha256:$sha, size:$size, mtime:$mtime, captured:$captured}
+       + (if $prev != "" then {prev:$prev} else {} end)
+       + (if $refused != "" then {refused:$refused} else {} end)')" || return 1
+  if ! _ledger_append "$row"; then
+    echo "preimage.sh: FAIL LOUD — durable ledger append failed ($LEDGER)" >&2
+    return 1
+  fi
+
+  if [ -z "$head" ]; then
+    # First-seen: baseline SILENTLY (row only, no enqueue) — the same idiom as
+    # the detector's first-seen source baseline.
+    return 0
+  fi
+
+  echo "preimage.sh: preimage definition CHANGED — $path ($prev_sha -> $cur_sha); prior bytes: $OBJECTS/$prev_sha" >&2
+
+  if [ "$enqueue" = "1" ]; then
+    # First-class cause line (acceptance (c)): ONE class=actionable entry per
+    # changed preimage file, allocated by the store's single allocator (#908).
+    # `path` is a §2.1 hard locator, so the digest renders it — never
+    # quarantined. Callers run this BEFORE polling sources, so this seq is
+    # LOWER than the per-source deltas the change explains.
+    local locators
+    locators="$(jq -cn \
+      --arg path "$path" \
+      --arg sha "$cur_sha" \
+      --arg prev "$prev_sha" \
+      '{kind:"preimage", id:$path, path:$path, observed_hash:$sha, prev_hash:$prev,
+        preimage:true, reason:"preimage-definition-changed"}')"
+    if ! "$STORE_SH" enqueue --class actionable --locators "$locators" --emit-ts "$(date +%s)" >/dev/null; then
+      echo "preimage.sh: FAIL LOUD — store enqueue of the preimage-change entry FAILED for $path (the change IS recorded in the ledger; the first-class wake line is NOT — treat as infrastructure failure)." >&2
+      return 1
+    fi
+  fi
+  return 0
+}
+
+cmd_check() {
+  local enqueue=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+    --enqueue)
+      enqueue=1
+      shift
+      ;;
+    *)
+      echo "preimage.sh check: unknown option '$1'" >&2
+      exit 2
+      ;;
+    esac
+  done
+  _need_jq
+
+  local set_list
+  if ! set_list="$(_preimage_set)"; then
+    exit 1
+  fi
+  if [ -z "$set_list" ]; then
+    # Nothing declared (no adapter/watch-list/extras in env) — an empty set is
+    # a no-op, not an error: standalone invocations outside a wake runtime
+    # must not fail loud for lacking one.
+    return 0
+  fi
+
+  mkdir -p "$PRE_DIR" || exit 1
+  # Serialize concurrent checks (detector tick vs reconcile vs manual) — the
+  # ledger append is read+rewrite, so two writers must not interleave.
+  if ! _wake_lock_acquire "$PRE_DIR/preimage.lock"; then
+    echo "preimage.sh: FAIL LOUD — cannot acquire preimage lock" >&2
+    exit 1
+  fi
+  # #964 review (B11): an ABSENT/EMPTY ledger while objects/ still holds
+  # prior captures is DELETED HISTORY, not a first install — the asymmetry is
+  # locally detectable and is the whole detection. Re-baselining here would
+  # silently absorb the next real change as first-seen (the exact erasure
+  # this tool exists to prevent). ABSENT is not CORRUPT: it must not take the
+  # first-install path either.
+  if [ ! -s "$LEDGER" ] && [ -d "$OBJECTS" ] && [ -n "$(ls -A -- "$OBJECTS" 2>/dev/null)" ]; then
+    echo "preimage.sh: FAIL LOUD — preimage ledger $LEDGER is ABSENT/EMPTY but $OBJECTS still holds prior objects: history was deleted; REFUSING to re-baseline over it (a silent restart would absorb the next real change as first-seen). Restore the ledger, or move objects/ aside explicitly after investigation." >&2
+    _wake_lock_release
+    exit 1
+  fi
+  local failed=0 origin raw resolved
+  while IFS=$'\t' read -r origin raw resolved; do
+    [ -n "$resolved" ] || continue
+    _check_one "$origin" "$raw" "$resolved" "$enqueue" || failed=1
+  done <<EOF
+$set_list
+EOF
+  _wake_lock_release
+  [ "$failed" -eq 0 ] || exit 1
+}
+
+cmd_status() {
+  _need_jq
+  [ -f "$LEDGER" ] || {
+    echo "preimage.sh: no ledger yet ($LEDGER)" >&2
+    return 0
+  }
+  # Head row per path (last wins).
+  jq -cs 'group_by(.path) | map(last) | .[]' "$LEDGER"
+}
+
+cmd_set() {
+  local s
+  s="$(_preimage_set)" || exit 1
+  [ -n "$s" ] && printf '%s\n' "$s" | cut -f3
+}
+
+main() {
+  [ $# -ge 1 ] || {
+    usage
+    exit 2
+  }
+  local cmd="$1"
+  shift
+  case "$cmd" in
+  check) cmd_check "$@" ;;
+  record) cmd_check ;;
+  set) cmd_set "$@" ;;
+  status) cmd_status "$@" ;;
+  -h | --help | help) usage ;;
+  *)
+    echo "preimage.sh: unknown command '$cmd'" >&2
+    usage
+    exit 2
+    ;;
+  esac
+}
+
+main "$@"

packages/mosaic/framework/tools/wake/reconcile.sh

@@ -440,6 +440,17 @@ cmd_reconcile() {
   : "$allow_enumerate"
 
   local pairs kind id failed=0 unaccounted=0 enumerated=0
+
+  # #958 preimage provenance: same pre-step as the detector's poll tick, for
+  # the path where the preimage changed while the detector was down — without
+  # it, a changed adapter surfaces here only as N UNACCOUNTED enumerations
+  # with no first-class cause line. Run BEFORE observing any source so the
+  # cause entry's observed_seq precedes the enumerations it explains. Loud
+  # infrastructure failure marks the reconcile failed but does not stop it.
+  if ! "$SCRIPT_DIR/preimage.sh" check --enqueue; then
+    echo "reconcile.sh: FAIL LOUD — preimage provenance check failed (see preimage.sh above); reconcile continues but exits non-zero." >&2
+    failed=1
+  fi
   pairs="$(printf '%s' "$json" | jq -r '[ .watches[].sources[] | "\(.kind)\t\(.id)" ] | unique | .[]')"
   if [ -z "$pairs" ]; then
     echo "reconcile.sh: watch-list declares no sources under watches[].sources[]" >&2

packages/mosaic/framework/tools/wake/store.sh

@@ -77,11 +77,46 @@ Commands:
                                          the actual paste is out of scope.
                                          If --require-idle-cmd is given and it
                                          exits non-zero, emit nothing (not idle).
-  consume --upto N                       Advance consumed_seq over the contiguous
+  consume --upto N [--force-past-quarantine]
+                                         Advance consumed_seq over the contiguous
                                          gapless prefix <=N; drop consumed
                                          entries. Rejects a gap (cannot ack N
                                          while N-1 is unconsumed). Cumulative &
-                                         idempotent.
+                                         idempotent. REFUSES to advance past a
+                                         QUARANTINED seq (#946): a quarantined
+                                         entry was dead-lettered at render and
+                                         never delivered in any digest, so an
+                                         ordinary ack may not record it consumed.
+                                         --force-past-quarantine is the ONLY way
+                                         past — loud per stepped-over seq, and
+                                         even then NO consumed-hash witness is
+                                         recorded for the quarantined entry.
+  quarantine-sync                        REPLACE the store-owned quarantined.set
+                                         with the observed_seqs read from stdin
+                                         (one per line; empty input CLEARS).
+                                         Called by digest.sh after each
+                                         authoritative store render — the set is
+                                         re-DERIVED per render, never accumulated,
+                                         so a fixed locator gate self-heals the
+                                         consume clamp (#944 recovery).
+  quarantine-audit [--repair]            Report consumed-hashes rows that are
+                                         PROVABLY FALSE: the row matches a
+                                         dead-letter ledger entry on
+                                         (kind,id,observed_seq,observed_hash) at
+                                         or below consumed_seq — i.e. the recorded
+                                         consumption was of a quarantined,
+                                         never-delivered entry (#946 Finding A).
+                                         Report-only by default (exit 1 when any
+                                         found); --repair removes exactly those
+                                         rows (atomic, loud). The dead-letter
+                                         ledger itself is NEVER modified (it is
+                                         history). TWO residual classes are
+                                         unprovable and never touched (#952):
+                                         rows whose dead-letter evidence was
+                                         pruned away, AND rows whose surviving
+                                         evidence extracts an empty
+                                         observed_hash (it can never satisfy
+                                         the four-field conviction match).
   cursors                                Print observed_seq / consumed_seq / depth.
 
 Environment:
@@ -354,10 +389,20 @@ cmd_drain() {
 # (the reconciler re-enumerates the consumed state once — no lost obligation),
 # never a failed consume.
 _record_last_consumed() {
-  local upto="$1" existing new_records merged
+  local upto="$1" existing new_records merged qjson
   [ -f "$STATE_DIR/pending.jsonl" ] || return 0
-  new_records="$(jq -c --argjson upto "$upto" '
-    select((.observed_seq // -1) <= $upto)
+  # #946: seqs in quarantined.set are EXCLUDED from the record — the trust
+  # boundary above says "existence implies durably enqueued+CONSUMED", but a
+  # quarantined entry was dead-lettered at render and NEVER delivered, so a row
+  # for it would witness a delivery that never happened. This holds even on the
+  # FORCED step-over path: the reconciler re-enumerating the state once is
+  # safe-but-noisy; a false witness silences it forever.
+  qjson="$(jq -nR -c '[inputs | select(length > 0) | tonumber? // empty]' "$STATE_DIR/quarantined.set" 2>/dev/null || true)"
+  [ -n "$qjson" ] || qjson='[]'
+  new_records="$(jq -c --argjson upto "$upto" --argjson quarantined "$qjson" '
+    (.observed_seq // -1) as $seq
+    | select($seq <= $upto)
+    | select(($quarantined | index($seq)) == null)
     | select((.locators.kind // "") != "" and (.locators.id // "") != "" and (.locators.observed_hash // "") != "")
     | {kind:.locators.kind, id:.locators.id, observed_hash:.locators.observed_hash, observed_seq:.observed_seq}
   ' "$STATE_DIR/pending.jsonl" 2>/dev/null || true)"
@@ -372,13 +417,17 @@ _record_last_consumed() {
 }
 
 cmd_consume() {
-  local upto=''
+  local upto='' force=0
   while [ $# -gt 0 ]; do
     case "$1" in
     --upto)
       upto="${2:-}"
       shift 2
       ;;
+    --force-past-quarantine)
+      force=1
+      shift
+      ;;
     *)
       echo "store.sh consume: unknown option '$1'" >&2
       exit 2
@@ -426,6 +475,33 @@ cmd_consume() {
     k=$((k + 1))
   done
 
+  # --- #946 quarantine CLAMP -------------------------------------------------
+  # A quarantined seq was DEAD-LETTERED at render (no §2.1 hard locator): it was
+  # never delivered in any digest, so advancing consumed_seq past it would record
+  # consumption of an entry the consumer has never seen. The ordinary path
+  # REFUSES; --force-past-quarantine is the ONLY way past, and it is loud per
+  # stepped-over seq. digest.sh re-derives the set at each authoritative store
+  # render (quarantine-sync REPLACE), so a fixed locator gate self-heals this
+  # clamp without operator action.
+  local qfile="$STATE_DIR/quarantined.set" blocked='' q
+  if [ -s "$qfile" ]; then
+    while IFS= read -r q; do
+      case "$q" in '' | *[!0-9]*) continue ;; esac
+      if [ "$q" -gt "$consumed" ] && [ "$q" -le "$upto" ]; then
+        blocked="$blocked $q"
+      fi
+    done <"$qfile"
+  fi
+  if [ -n "$blocked" ]; then
+    if [ "$force" -eq 0 ]; then
+      echo "store.sh consume: REFUSED (#946 quarantine clamp) — quarantined seq(s):$blocked inside (consumed_seq=$consumed, upto=$upto] were dead-lettered at render and NEVER delivered in any digest. Advancing past them would record consumption of entries the consumer has never seen. Disposition them (see $STATE_DIR/dead-letter.jsonl) or step over EXPLICITLY with --force-past-quarantine." >&2
+      exit 1
+    fi
+    for q in $blocked; do
+      echo "store.sh consume: FORCED PAST QUARANTINE (#946) — stepping consumed_seq over quarantined seq $q (dead-lettered, NEVER delivered). No consumed-hash witness is recorded for it; the obligation stays visible ONLY in $STATE_DIR/dead-letter.jsonl." >&2
+    done
+  fi
+
   # #932: record the last-consumed observed_hash per (kind,id) BEFORE the pending
   # prefix is dropped (this reads the entries about to be truncated), so the
   # reconciler can recognise an already-consumed state as ACCOUNTED instead of
@@ -439,9 +515,144 @@ cmd_consume() {
   awk -v c="$upto" 'NF && $1+0 > c' "$STATE_DIR/observed.set" 2>/dev/null |
     _atomic_write "$STATE_DIR/observed.set" || true
   printf '%s' "$upto" | _atomic_write "$STATE_DIR/consumed_seq"
+  # #946: on a forced step-over, PRUNE the stepped-over seqs from quarantined.set
+  # (they are inside the consumed prefix now; a stale entry would re-refuse the
+  # next consume forever). Mirrors the observed.set prune idiom above.
+  if [ -n "$blocked" ]; then
+    awk -v c="$upto" 'NF && $1+0 > c' "$qfile" 2>/dev/null |
+      _atomic_write "$qfile" || true
+  fi
   echo "$upto"
 }
 
+# cmd_quarantine_sync — #946: REPLACE the store-owned quarantined.set with the
+# observed_seqs read from stdin (one per line). Called by digest.sh after each
+# AUTHORITATIVE full-set render (src=store): the set is re-DERIVED per render,
+# never accumulated, so a fixed locator gate self-heals the consume clamp (the
+# #944 recovery case — a cumulative-forever set would keep refusing acks on
+# entries that now render). Empty input CLEARS the set. Foreign-data renders
+# (--from-file/--stdin) never call this. Atomic write; invalid input is refused
+# loudly with the set left untouched.
+cmd_quarantine_sync() {
+  [ $# -eq 0 ] || {
+    echo "store.sh quarantine-sync: takes no options (observed_seqs on stdin, one per line)" >&2
+    exit 2
+  }
+  local seq list=''
+  while IFS= read -r seq; do
+    [ -n "$seq" ] || continue
+    case "$seq" in
+    *[!0-9]*)
+      echo "store.sh quarantine-sync: invalid observed_seq '$seq' — one non-negative integer per line; set left untouched" >&2
+      exit 2
+      ;;
+    esac
+    list="$list$seq"$'\n'
+  done
+  _wake_init_dir "$STATE_DIR"
+  if ! { printf '%s' "$list" | grep -v '^[[:space:]]*$' || true; } | sort -n | uniq | _atomic_write "$STATE_DIR/quarantined.set"; then
+    echo "store.sh quarantine-sync: quarantined.set write FAILED — the consume clamp may be stale for this lane" >&2
+    exit 1
+  fi
+}
+
+# cmd_quarantine_audit — #946 Finding A: the pre-#946 consume recorded
+# consumed-hash rows for QUARANTINED (never-delivered) entries — false
+# witnesses that silence the reconciler for keys whose only "consumption" was a
+# dead-lettered entry (live: safe by population only where the key re-emitted
+# and a later seq won the per-key max_by merge; keys that never recurred keep
+# the false row forever).
+#
+# A row is PROVABLY FALSE iff the dead-letter ledger contains an entry matching
+# it on (kind, id, observed_seq, observed_hash) AND row.observed_seq <=
+# consumed_seq: the per-key max_by merge means the surviving row's provenance IS
+# that quarantined entry (a healed row differs in seq/hash and never matches).
+# PROVABILITY BOUND — TWO residual classes, both unprovable (#952): (1) a row
+# whose dead-letter evidence was pruned/rotated away — no evidence to convict
+# on; (2) a row whose dead-letter evidence SURVIVES but extracts an empty
+# observed_hash (e.g. a deliberately non-conformant locator: nested
+# .locators.* with no observed_hash key) — evidence exists but can never
+# satisfy the four-field match, because _record_last_consumed only ever writes
+# rows with a NON-empty hash. Neither class is touched — this audit only ever
+# removes what the ledger can convict, and the clean-sweep message names BOTH
+# classes: "no evidence" and "evidence unusable" are different operator
+# conclusions. The dead-letter ledger itself is history and is NEVER modified
+# here.
+cmd_quarantine_audit() {
+  local repair=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+    --repair)
+      repair=1
+      shift
+      ;;
+    *)
+      echo "store.sh quarantine-audit: unknown option '$1'" >&2
+      exit 2
+      ;;
+    esac
+  done
+  _need_jq
+  _wake_init_dir "$STATE_DIR"
+  local rec="$STATE_DIR/consumed-hashes.jsonl" dlf="$STATE_DIR/dead-letter.jsonl"
+  if [ ! -s "$rec" ]; then
+    echo "store.sh quarantine-audit: OK — no consumed-hashes record to audit"
+    return 0
+  fi
+  local dl
+  dl="$(jq -s -c '[.[] | {kind: (.locators.kind // ""), id: ((.locators.id // "") | tostring), observed_seq: (.observed_seq // -1), observed_hash: (.locators.observed_hash // "")}]' "$dlf" 2>/dev/null || true)"
+  [ -n "$dl" ] || dl='[]'
+  local consumed
+  consumed="$(_wake_read_int "$STATE_DIR/consumed_seq" 0)"
+  local false_rows
+  false_rows="$(jq -c --argjson dl "$dl" --argjson consumed "$consumed" '
+    . as $row
+    | select(($row.observed_seq // -1) <= $consumed)
+    | select(($dl | map(select(
+        .kind == ($row.kind // "")
+        and .id == (($row.id // "") | tostring)
+        and .observed_seq == ($row.observed_seq // -1)
+        and .observed_hash == ($row.observed_hash // "")
+      )) | length) > 0)
+  ' "$rec" 2>/dev/null || true)"
+  if [ -z "$false_rows" ]; then
+    echo "store.sh quarantine-audit: OK — no provably-false consumed-hash rows. Two residual classes are unprovable and were NOT judged: rows whose dead-letter evidence was pruned/rotated away (no evidence to convict on), and rows whose surviving dead-letter evidence extracts an empty observed_hash (evidence exists but can never satisfy the four-field conviction match)."
+    return 0
+  fi
+  local n row
+  n="$(printf '%s\n' "$false_rows" | grep -c . || true)"
+  while IFS= read -r row; do
+    [ -n "$row" ] || continue
+    if [ "$repair" -eq 1 ]; then
+      echo "store.sh quarantine-audit: REPAIR — removing FALSE WITNESS row $row (matches a dead-lettered, never-delivered entry at/below consumed_seq=$consumed)" >&2
+    else
+      echo "FALSE WITNESS — consumed-hashes row $row matches a dead-lettered, never-delivered entry at/below consumed_seq=$consumed (the recorded consumption never happened)"
+    fi
+  done <<<"$false_rows"
+  if [ "$repair" -eq 0 ]; then
+    echo "store.sh quarantine-audit: $n provably-false row(s) found — run with --repair to remove exactly these rows"
+    return 1
+  fi
+  local kept
+  kept="$(jq -c --argjson dl "$dl" --argjson consumed "$consumed" '
+    . as $row
+    | select(
+        (($row.observed_seq // -1) > $consumed)
+        or (($dl | map(select(
+          .kind == ($row.kind // "")
+          and .id == (($row.id // "") | tostring)
+          and .observed_seq == ($row.observed_seq // -1)
+          and .observed_hash == ($row.observed_hash // "")
+        )) | length) == 0)
+      )
+  ' "$rec" 2>/dev/null || true)"
+  if ! { printf '%s\n' "$kept" | grep -v '^[[:space:]]*$' || true; } | _atomic_write "$rec"; then
+    echo "store.sh quarantine-audit: consumed-hashes rewrite FAILED — record left untouched" >&2
+    exit 1
+  fi
+  echo "store.sh quarantine-audit: repaired — removed $n provably-false row(s); dead-letter ledger untouched (history)"
+}
+
 cmd_cursors() {
   _wake_init_dir "$STATE_DIR"
   local observed consumed depth
@@ -463,6 +674,8 @@ main() {
   enqueue) cmd_enqueue "$@" ;;
   drain) cmd_drain "$@" ;;
   consume) cmd_consume "$@" ;;
+  quarantine-sync) cmd_quarantine_sync "$@" ;;
+  quarantine-audit) cmd_quarantine_audit "$@" ;;
   cursors) cmd_cursors "$@" ;;
   -h | --help | help) usage ;;
   *)

packages/mosaic/framework/tools/wake/test-wake-beacon.sh

@@ -31,6 +31,13 @@
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# #973: three-valued grep assertion helpers (has_match/count_lines); init saves real stderr for abort loudness.
+# shellcheck disable=SC1091
+if ! . "$SCRIPT_DIR/_wake-common.sh"; then
+  echo "WAKE-ASSERT INIT ABORT: cannot source _wake-common.sh — suite ran ZERO wake assertions (#984)" >&2
+  exit 97
+fi
+wake_assert_init
 BEACON="$SCRIPT_DIR/beacon.sh"
 
 command -v jq >/dev/null 2>&1 || {
@@ -129,7 +136,7 @@ echo "== B2: beacon ABSENCE past SLO -> alarm FIRES + ROUTES =="
   out="$("$BEACON" check --slo-seconds 5 2>&1)"
   rc=$?
   [ "$rc" -eq 1 ] || fail_msg "B2: a stale-past-SLO beacon must FIRE the absence alarm (exit 1); got $rc [$out]"
-  echo "$out" | grep -qi 'ALARM FIRED' || fail_msg "B2: absence must announce the alarm fired [$out]"
+  echo "$out" | has_match -qi 'ALARM FIRED' || fail_msg "B2: absence must announce the alarm fired [$out]"
   [ -s "$ALARM_OUT" ] || fail_msg "B2: the alarm must actually ROUTE to the sink (payload not written)"
   jq -e '.kind == "beacon-absence-alarm"' "$ALARM_OUT" >/dev/null 2>&1 || fail_msg "B2: routed payload must be a beacon-absence-alarm [$(cat "$ALARM_OUT" 2>/dev/null)]"
   # NEVER-received is also an absence (depends on nothing the dying host does).
@@ -150,13 +157,13 @@ echo "== B3: unconfigured OR unreachable ALARM target -> FAIL LOUD =="
   out="$("$BEACON" check --slo-seconds 5 2>&1)"
   rc=$?
   [ "$rc" -eq 3 ] || fail_msg "B3a: unconfigured alarm target must FAIL LOUD (exit 3); got $rc [$out]"
-  echo "$out" | grep -qi 'silent no-alarm host' || fail_msg "B3a: the failure must name the silent-no-alarm-host hazard [$out]"
+  echo "$out" | has_match -qi 'silent no-alarm host' || fail_msg "B3a: the failure must name the silent-no-alarm-host hazard [$out]"
   # (b) UNREACHABLE alarm sink (non-zero exit).
   export WAKE_ALARM_SINK_CMD="false"
   out2="$("$BEACON" check --slo-seconds 5 2>&1)"
   rc2=$?
   [ "$rc2" -eq 3 ] || fail_msg "B3b: unreachable alarm target must FAIL LOUD (exit 3); got $rc2 [$out2]"
-  echo "$out2" | grep -qi 'UNREACHABLE' || fail_msg "B3b: the failure must name the unreachable target [$out2]"
+  echo "$out2" | has_match -qi 'UNREACHABLE' || fail_msg "B3b: the failure must name the unreachable target [$out2]"
 ) && ok
 
 echo "== B4: isolated host -> DEGRADED different-supervision-root beacon FLAGGED =="
@@ -169,8 +176,8 @@ echo "== B4: isolated host -> DEGRADED different-supervision-root beacon FLAGGED
   rc=$?
   err="$(cat "$TMP_ROOT/b4.err")"
   [ "$rc" -eq 0 ] || fail_msg "B4: a different-supervision-root emit must still succeed (exit 0); got $rc [$out][$err]"
-  echo "$err" | grep -qi 'DEGRADED' || fail_msg "B4: a different-supervision-root beacon must be FLAGGED degraded on stderr [$err]"
-  echo "$out" | grep -q 'degraded=true' || fail_msg "B4: emit must NOT silently present a degraded beacon as healthy (degraded=true expected) [$out]"
+  echo "$err" | has_match -qi 'DEGRADED' || fail_msg "B4: a different-supervision-root beacon must be FLAGGED degraded on stderr [$err]"
+  echo "$out" | has_match -q 'degraded=true' || fail_msg "B4: emit must NOT silently present a degraded beacon as healthy (degraded=true expected) [$out]"
 ) && ok
 
 echo "== B5: same-host-sibling -> REJECTED as non-independent, seq NOT advanced =="
@@ -182,7 +189,7 @@ echo "== B5: same-host-sibling -> REJECTED as non-independent, seq NOT advanced
   out="$("$BEACON" emit 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "B5: a same-host-sibling beacon must be REJECTED (non-zero exit) [$out]"
-  echo "$out" | grep -qi 'not an independent' || fail_msg "B5: the rejection must explain it is NOT an independent leg [$out]"
+  echo "$out" | has_match -qi 'not an independent' || fail_msg "B5: the rejection must explain it is NOT an independent leg [$out]"
   # A rejected emit must not have minted a seq (rejection precedes counter bump).
   seq_after="$("$BEACON" status 2>/dev/null | sed -n 's/^beacon_emitter_seq=//p')"
   [ "${seq_after:-0}" -eq 0 ] || fail_msg "B5: a rejected emit must NOT advance the monotonic seq (got $seq_after)"
@@ -201,10 +208,10 @@ echo "== B6: alarm target resolved BY NAME; beacon.sh inlines no endpoint/secret
   out="$("$BEACON" check --slo-seconds 5 2>&1)"
   rc=$?
   [ "$rc" -eq 1 ] || fail_msg "B6: absence via a by-name alarm adapter must fire (exit 1); got $rc [$out]"
-  head -n1 "$ALARM_OUT" 2>/dev/null | grep -qF "$SECRET_TARGET" || fail_msg "B6: the adapter must resolve+route to the BY-NAME target [$(cat "$ALARM_OUT" 2>/dev/null)]"
+  head -n1 "$ALARM_OUT" 2>/dev/null | has_match -qF "$SECRET_TARGET" || fail_msg "B6: the adapter must resolve+route to the BY-NAME target [$(cat "$ALARM_OUT" 2>/dev/null)]"
   # The framework file must NOT inline the endpoint/secret: it only knows a NAME.
-  grep -qF "$SECRET_TARGET" "$BEACON" && fail_msg "B6: beacon.sh must NOT inline the target endpoint/secret"
-  grep -qF "$SECRET_TARGET" "$WAKE_ALARM_SINK_CMD" && fail_msg "B6: even the adapter must resolve by-name, not inline the secret"
+  has_match -qF "$SECRET_TARGET" "$BEACON" && fail_msg "B6: beacon.sh must NOT inline the target endpoint/secret"
+  has_match -qF "$SECRET_TARGET" "$WAKE_ALARM_SINK_CMD" && fail_msg "B6: even the adapter must resolve by-name, not inline the secret"
   true
 ) && ok
 
@@ -218,7 +225,7 @@ echo "== B7: unconfigured OR unreachable BEACON sink on emit -> FAIL LOUD =="
   out="$("$BEACON" emit 2>&1)"
   rc=$?
   [ "$rc" -eq 3 ] || fail_msg "B7a: unconfigured beacon sink must FAIL LOUD (exit 3); got $rc [$out]"
-  echo "$out" | grep -qi 'silent no-alarm host' || fail_msg "B7a: the failure must name the silent-no-alarm-host hazard [$out]"
+  echo "$out" | has_match -qi 'silent no-alarm host' || fail_msg "B7a: the failure must name the silent-no-alarm-host hazard [$out]"
   # A refused emit (no sink) must not have minted a seq.
   seq_after="$("$BEACON" status 2>/dev/null | sed -n 's/^beacon_emitter_seq=//p')"
   [ "${seq_after:-0}" -eq 0 ] || fail_msg "B7a: an unconfigured-sink emit must NOT advance the seq (got $seq_after)"
@@ -227,7 +234,7 @@ echo "== B7: unconfigured OR unreachable BEACON sink on emit -> FAIL LOUD =="
   out2="$("$BEACON" emit 2>&1)"
   rc2=$?
   [ "$rc2" -eq 1 ] || fail_msg "B7b: unreachable beacon sink must FAIL LOUD (exit 1); got $rc2 [$out2]"
-  echo "$out2" | grep -qi 'UNREACHABLE' || fail_msg "B7b: the failure must name the unreachable sink [$out2]"
+  echo "$out2" | has_match -qi 'UNREACHABLE' || fail_msg "B7b: the failure must name the unreachable sink [$out2]"
 ) && ok
 
 echo "== B8: no invented SLO -> check --slo-seconds is REQUIRED (fail-loud) =="
@@ -238,7 +245,7 @@ echo "== B8: no invented SLO -> check --slo-seconds is REQUIRED (fail-loud) =="
   out="$("$BEACON" check 2>&1)"
   rc=$?
   [ "$rc" -eq 3 ] || fail_msg "B8: check without an SLO must fail loud (exit 3); got $rc [$out]"
-  echo "$out" | grep -qi 'slo' || fail_msg "B8: the usage error must name the missing SLO [$out]"
+  echo "$out" | has_match -qi 'slo' || fail_msg "B8: the usage error must name the missing SLO [$out]"
 ) && ok
 
 echo "== B9: capture-pane hint is a liveness HINT ONLY (does NOT suppress absence) =="
@@ -267,7 +274,7 @@ echo "== B10: fresh beacon within SLO -> ALIVE (exit 0, no alarm) =="
   out="$("$BEACON" check --slo-seconds 60 2>&1)"
   rc=$?
   [ "$rc" -eq 0 ] || fail_msg "B10: a fresh beacon within SLO must be ALIVE (exit 0); got $rc [$out]"
-  echo "$out" | grep -qi 'ALIVE' || fail_msg "B10: a fresh beacon must report ALIVE [$out]"
+  echo "$out" | has_match -qi 'ALIVE' || fail_msg "B10: a fresh beacon must report ALIVE [$out]"
   [ ! -s "$ALARM_OUT" ] || fail_msg "B10: a fresh beacon must NOT fire an alarm"
 ) && ok
 
@@ -291,7 +298,7 @@ echo "== B11: staleness from monitor ingested_ts -> a far-future emit_ts STILL g
   jq -c --argjson ing "$((now - 100))" '.ingested_ts = $ing' "$WAKE_BEACON_RECEIVED" >"$H/tmp" && mv "$H/tmp" "$WAKE_BEACON_RECEIVED"
   out="$("$BEACON" check --slo-seconds 5 2>&1)"; rc=$?
   [ "$rc" -eq 1 ] || fail_msg "B11: a far-future emit_ts must NOT defer staleness — receive-time governs (expected absence exit 1); got $rc [$out]"
-  echo "$out" | grep -qi 'ALARM FIRED' || fail_msg "B11: the receive-time-stale beacon must fire the absence alarm [$out]"
+  echo "$out" | has_match -qi 'ALARM FIRED' || fail_msg "B11: the receive-time-stale beacon must fire the absence alarm [$out]"
   jq -e '.age_seconds >= 100' "$ALARM_OUT" >/dev/null 2>&1 || fail_msg "B11: staleness age must be measured from ingested_ts (>=100s), not emit_ts [$(cat "$ALARM_OUT" 2>/dev/null)]"
 ) && ok
 
@@ -329,7 +336,7 @@ else
   jq -c '.beacon_seq = 99999 | .host_id = "attacker"' "$SHIPPED" >"$spoof"
   out="$("$BEACON" record <"$spoof" 2>&1)"; rc=$?
   [ "$rc" -ne 0 ] || fail_msg "B12: a spoofed beacon (altered fields) must be REJECTED at record; got rc=$rc [$out]"
-  echo "$out" | grep -qi 'spoofed beacon' || fail_msg "B12: the rejection must name the spoof [$out]"
+  echo "$out" | has_match -qi 'spoofed beacon' || fail_msg "B12: the rejection must name the spoof [$out]"
   [ ! -s "$WAKE_BEACON_RECEIVED" ] || fail_msg "B12: a rejected spoof must NOT be stored (dead-man clock not advanced)"
   # (c) an UNSIGNED beacon is rejected when signing is configured.
   unsigned="$H/unsigned.json"
@@ -337,14 +344,14 @@ else
   out2="$("$BEACON" record <"$unsigned" 2>&1)"; rc2=$?
   [ "$rc2" -ne 0 ] || fail_msg "B12: an unsigned beacon must be REJECTED when signing is configured; got rc=$rc2 [$out2]"
   # beacon.sh must not inline the key material.
-  grep -qF "test-beacon-hmac-key-do-not-echo" "$BEACON" && fail_msg "B12: beacon.sh must NOT inline the HMAC key"
+  has_match -qF "test-beacon-hmac-key-do-not-echo" "$BEACON" && fail_msg "B12: beacon.sh must NOT inline the HMAC key"
   true
 ) && ok
 fi
 
 echo
 if [ -s "$FAILFILE" ]; then
-  echo "wake beacon harness: FAILED ($(grep -c . "$FAILFILE") assertion(s))" >&2
+  echo "wake beacon harness: FAILED ($(count_lines . "$FAILFILE") assertion(s))" >&2
   exit 1
 fi
 echo "wake beacon harness: all invariants passed ($pass groups)"

packages/mosaic/framework/tools/wake/test-wake-detector.sh

@@ -29,6 +29,13 @@
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# #973: three-valued grep assertion helpers (has_match/count_lines); init saves real stderr for abort loudness.
+# shellcheck disable=SC1091
+if ! . "$SCRIPT_DIR/_wake-common.sh"; then
+  echo "WAKE-ASSERT INIT ABORT: cannot source _wake-common.sh — suite ran ZERO wake assertions (#984)" >&2
+  exit 97
+fi
+wake_assert_init
 DET="$SCRIPT_DIR/detector.sh"
 STORE="$SCRIPT_DIR/store.sh"
 
@@ -253,8 +260,8 @@ echo "== D5: watch-list schema_version out of manifest range -> FAIL LOUD =="
   err="$("$DET" poll-once 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "D5: an out-of-range schema_version must FAIL LOUD (non-zero exit)"
-  echo "$err" | grep -qi 'schema_version' || fail_msg "D5: the failure must name schema_version [$err]"
-  echo "$err" | grep -qi 'range' || fail_msg "D5: the failure must state it is out of the supported range [$err]"
+  echo "$err" | has_match -qi 'schema_version' || fail_msg "D5: the failure must name schema_version [$err]"
+  echo "$err" | has_match -qi 'range' || fail_msg "D5: the failure must state it is out of the supported range [$err]"
   # And nothing was enqueued / no cursor advance under a rejected watch-list.
   [ "$(depth)" = "0" ] || fail_msg "D5: a rejected watch-list must not enqueue, got depth $(depth)"
   [ "$(det_seq)" = "0" ] || fail_msg "D5: a rejected watch-list must not advance observed_seq, got $(det_seq)"
@@ -287,7 +294,7 @@ echo "== D6: source error / ambiguous-empty -> FAIL LOUD, observed_seq NOT advan
   err="$("$DET" poll-once 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "D6: a source error must FAIL LOUD (non-zero exit)"
-  echo "$err" | grep -qi 'FAIL LOUD' || fail_msg "D6: the source error must be loud [$err]"
+  echo "$err" | has_match -qi 'FAIL LOUD' || fail_msg "D6: the source error must be loud [$err]"
   [ "$(det_seq)" = "$seq_before" ] || fail_msg "D6: a source error must NOT advance observed_seq (got $(det_seq), was $seq_before)"
   [ "$(depth)" = "0" ] || fail_msg "D6: a source error must NOT enqueue, got depth $(depth)"
 
@@ -298,7 +305,7 @@ echo "== D6: source error / ambiguous-empty -> FAIL LOUD, observed_seq NOT advan
   err="$("$DET" poll-once 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "D6: an ambiguous-empty response must FAIL LOUD (non-zero exit)"
-  echo "$err" | grep -qi 'AMBIGUOUS-EMPTY' || fail_msg "D6: ambiguous-empty must be named in the loud failure [$err]"
+  echo "$err" | has_match -qi 'AMBIGUOUS-EMPTY' || fail_msg "D6: ambiguous-empty must be named in the loud failure [$err]"
   [ "$(det_seq)" = "$seq_before" ] || fail_msg "D6: ambiguous-empty must NOT advance observed_seq (got $(det_seq))"
   [ "$(depth)" = "0" ] || fail_msg "D6: ambiguous-empty must NOT enqueue, got depth $(depth)"
 
@@ -442,7 +449,7 @@ EOF
   write_fc_watchlist "$wl" 999
   err="$("$DET" poll-once 2>&1)"; rc=$?
   [ "$rc" -ne 0 ] || fail_msg "D9: the new field must NOT weaken Gate B — an out-of-range schema_version must still FAIL LOUD (rc=$rc)"
-  echo "$err" | grep -qi 'range' || fail_msg "D9: the out-of-range failure must still state it is out of the supported range [$err]"
+  echo "$err" | has_match -qi 'range' || fail_msg "D9: the out-of-range failure must still state it is out of the supported range [$err]"
 ) && ok
 
 echo "== D10: snapshot metadata (fd 3, #940) — adapter-attested sha/ts land in the enqueued locators =="
@@ -513,7 +520,7 @@ EOF
   printf 'SHA-BBB\n' >"$stub/repo_r1"
   err="$("$DET" poll-once 2>&1 >/dev/null)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D11: malformed metadata must NEVER fail the poll (rc=$rc)"
-  echo "$err" | grep -qi 'snapshot' || fail_msg "D11: dropping malformed metadata must be LOUD on stderr [$err]"
+  echo "$err" | has_match -qi 'snapshot' || fail_msg "D11: dropping malformed metadata must be LOUD on stderr [$err]"
   entry="$("$STORE" drain | tail -1)"
   echo "$entry" | jq -e '.locators | has("snapshot_sha") or has("snapshot_ts")' >/dev/null 2>&1 \
     && fail_msg "D11: malformed metadata must emit NO snapshot fields [$entry]"
@@ -522,7 +529,7 @@ EOF
   printf 'SHA-CCC\n' >"$stub/repo_r1"
   err="$("$DET" poll-once 2>&1 >/dev/null)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D11: rejected snapshot_sha must NEVER fail the poll (rc=$rc)"
-  echo "$err" | grep -qi 'snapshot' || fail_msg "D11: rejecting a bad snapshot_sha must be LOUD on stderr [$err]"
+  echo "$err" | has_match -qi 'snapshot' || fail_msg "D11: rejecting a bad snapshot_sha must be LOUD on stderr [$err]"
   entry="$("$STORE" drain | tail -1)"
   echo "$entry" | jq -e '.locators | has("snapshot_sha") or has("snapshot_ts")' >/dev/null 2>&1 \
     && fail_msg "D11: rejected metadata must emit NO snapshot fields [$entry]"
@@ -560,7 +567,7 @@ EOF
   printf 'SHA-BBB\n' >"$stub/repo_r1"
   err="$("$DET" poll-once 2>&1 >/dev/null)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D12: ts-without-sha must NEVER fail the poll (rc=$rc)"
-  echo "$err" | grep -qi 'without a valid snapshot_sha' || fail_msg "D12: dropping ts-without-sha must be LOUD on stderr [$err]"
+  echo "$err" | has_match -qi 'without a valid snapshot_sha' || fail_msg "D12: dropping ts-without-sha must be LOUD on stderr [$err]"
   entry="$("$STORE" drain | tail -1)"
   echo "$entry" | jq -e '.locators | has("snapshot_sha") or has("snapshot_ts")' >/dev/null 2>&1 \
     && fail_msg "D12: ts-without-sha must emit NO snapshot fields [$entry]"
@@ -571,7 +578,7 @@ EOF
   printf 'SHA-CCC\n' >"$stub/repo_r1"
   err="$("$DET" poll-once 2>&1 >/dev/null)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D12: future ts must NEVER fail the poll (rc=$rc)"
-  echo "$err" | grep -qi 'future-skew' || fail_msg "D12: dropping a future ts must be LOUD on stderr [$err]"
+  echo "$err" | has_match -qi 'future-skew' || fail_msg "D12: dropping a future ts must be LOUD on stderr [$err]"
   entry="$("$STORE" drain | tail -1)"
   echo "$entry" | jq -e --arg s "$goodsha" 'select(.locators.snapshot_sha==$s) | .locators | has("snapshot_ts") | not' >/dev/null 2>&1 \
     || fail_msg "D12: future ts must drop ts but KEEP the sha [$entry]"
@@ -581,7 +588,7 @@ EOF
   printf 'SHA-DDD\n' >"$stub/repo_r1"
   err="$("$DET" poll-once 2>&1 >/dev/null)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D12: absurd ts must NEVER fail the poll (rc=$rc)"
-  echo "$err" | grep -qi 'sane positive epoch' || fail_msg "D12: rejecting an absurd ts must be LOUD on stderr [$err]"
+  echo "$err" | has_match -qi 'sane positive epoch' || fail_msg "D12: rejecting an absurd ts must be LOUD on stderr [$err]"
   entry="$("$STORE" drain | tail -1)"
   echo "$entry" | jq -e --arg s "$goodsha" 'select(.locators.snapshot_sha==$s) | .locators | has("snapshot_ts") | not' >/dev/null 2>&1 \
     || fail_msg "D12: absurd ts must drop ts but KEEP the sha [$entry]"
@@ -621,7 +628,7 @@ EOF
   printf 'SHA-BBB\n' >"$stub/repo_r1"
   err="$(WAKE_SNAPSHOT_TS_FUTURE_SLACK='300s' "$DET" poll-once 2>&1 >/dev/null)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D13: SLACK='300s' must NEVER fail the poll (rc=$rc)"
-  echo "$err" | grep -qi 'falling back to 300' || fail_msg "D13: malformed slack must be LOUD on stderr [$err]"
+  echo "$err" | has_match -qi 'falling back to 300' || fail_msg "D13: malformed slack must be LOUD on stderr [$err]"
   entry="$("$STORE" drain | tail -1)"
   echo "$entry" | jq -e --arg s "$goodsha" 'select(.locators.snapshot_sha==$s) | .locators | has("snapshot_ts")' >/dev/null 2>&1 \
     || fail_msg "D13: valid metadata must SURVIVE a malformed knob (fallback, not drop) [$entry]"
@@ -630,7 +637,7 @@ EOF
   printf 'SHA-CCC\n' >"$stub/repo_r1"
   err="$(WAKE_SNAPSHOT_TS_FUTURE_SLACK='abc' "$DET" poll-once 2>&1 >/dev/null)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D13: SLACK='abc' must NEVER fail the poll (rc=$rc)"
-  echo "$err" | grep -qi 'falling back to 300' || fail_msg "D13: non-numeric slack must be LOUD on stderr [$err]"
+  echo "$err" | has_match -qi 'falling back to 300' || fail_msg "D13: non-numeric slack must be LOUD on stderr [$err]"
   entry="$("$STORE" drain | tail -1)"
   echo "$entry" | jq -e --arg s "$goodsha" 'select(.locators.snapshot_sha==$s) | .locators | has("snapshot_ts")' >/dev/null 2>&1 \
     || fail_msg "D13: valid metadata must SURVIVE a non-numeric knob [$entry]"
@@ -640,7 +647,7 @@ EOF
   printf 'SHA-DDD\n' >"$stub/repo_r1"
   err="$(WAKE_SNAPSHOT_TS_FUTURE_SLACK='-99999999' "$DET" poll-once 2>&1 >/dev/null)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D13: negative SLACK must NEVER fail the poll (rc=$rc)"
-  echo "$err" | grep -qi 'falling back to 300' || fail_msg "D13: negative slack must be LOUD on stderr [$err]"
+  echo "$err" | has_match -qi 'falling back to 300' || fail_msg "D13: negative slack must be LOUD on stderr [$err]"
   entry="$("$STORE" drain | tail -1)"
   echo "$entry" | jq -e --arg s "$goodsha" 'select(.locators.snapshot_sha==$s) | .locators | has("snapshot_ts")' >/dev/null 2>&1 \
     || fail_msg "D13: negative slack must NOT invert the guard into deny-all [$entry]"
@@ -652,7 +659,7 @@ EOF
   printf 'SHA-CC2\n' >"$stub/repo_r1"
   err="$(WAKE_SNAPSHOT_TS_FUTURE_SLACK=$'300\n8' "$DET" poll-once 2>&1 >/dev/null)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D13: multi-line SLACK (300\\n8) must NEVER fail the poll (rc=$rc) [$err]"
-  echo "$err" | grep -qi 'falling back to 300' || fail_msg "D13: multi-line slack must be LOUD on stderr [$err]"
+  echo "$err" | has_match -qi 'falling back to 300' || fail_msg "D13: multi-line slack must be LOUD on stderr [$err]"
   entry="$("$STORE" drain | tail -1)"
   echo "$entry" | jq -e --arg s "$goodsha" 'select(.locators.snapshot_sha==$s) | .locators | has("snapshot_ts")' >/dev/null 2>&1 \
     || fail_msg "D13: valid metadata must SURVIVE a multi-line knob [$entry]"
@@ -660,7 +667,7 @@ EOF
   printf 'SHA-CC3\n' >"$stub/repo_r1"
   err="$(WAKE_SNAPSHOT_TS_FUTURE_SLACK=$'300\nabc' "$DET" poll-once 2>&1 >/dev/null)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D13: multi-line SLACK (300\\nabc) must NEVER fail the poll (rc=$rc) [$err]"
-  echo "$err" | grep -qi 'falling back to 300' || fail_msg "D13: multi-line non-numeric slack must be LOUD on stderr [$err]"
+  echo "$err" | has_match -qi 'falling back to 300' || fail_msg "D13: multi-line non-numeric slack must be LOUD on stderr [$err]"
   entry="$("$STORE" drain | tail -1)"
   echo "$entry" | jq -e --arg s "$goodsha" 'select(.locators.snapshot_sha==$s) | .locators | has("snapshot_ts")' >/dev/null 2>&1 \
     || fail_msg "D13: valid metadata must SURVIVE a multi-line non-numeric knob [$entry]"
@@ -687,7 +694,7 @@ EOF
   printf 'SHA-EEE\n' >"$stub/repo_r1"
   err="$(WAKE_SNAPSHOT_TS_FUTURE_SLACK='0' "$DET" poll-once 2>&1 >/dev/null)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D13: valid SLACK=0 must not fail the poll (rc=$rc)"
-  echo "$err" | grep -qi 'future-skew' || fail_msg "D13: a valid tightened slack must still reject a future ts [$err]"
+  echo "$err" | has_match -qi 'future-skew' || fail_msg "D13: a valid tightened slack must still reject a future ts [$err]"
   entry="$("$STORE" drain | tail -1)"
   echo "$entry" | jq -e --arg s "$goodsha" 'select(.locators.snapshot_sha==$s) | .locators | has("snapshot_ts") | not' >/dev/null 2>&1 \
     || fail_msg "D13: valid SLACK=0 must drop the future ts but keep the sha [$entry]"
@@ -696,7 +703,7 @@ EOF
 
 echo
 if [ -s "$FAILFILE" ]; then
-  echo "wake detector harness: FAILED ($(grep -c . "$FAILFILE") assertion(s))" >&2
+  echo "wake detector harness: FAILED ($(count_lines . "$FAILFILE") assertion(s))" >&2
   exit 1
 fi
 echo "wake detector harness: all invariants passed ($pass groups)"

packages/mosaic/framework/tools/wake/test-wake-digest-hmac.sh

@@ -35,6 +35,13 @@
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# #973: three-valued grep assertion helpers (has_match/count_lines); init saves real stderr for abort loudness.
+# shellcheck disable=SC1091
+if ! . "$SCRIPT_DIR/_wake-common.sh"; then
+  echo "WAKE-ASSERT INIT ABORT: cannot source _wake-common.sh — suite ran ZERO wake assertions (#984)" >&2
+  exit 97
+fi
+wake_assert_init
 STORE="$SCRIPT_DIR/store.sh"
 DIGEST="$SCRIPT_DIR/digest.sh"
 SIGN="$SCRIPT_DIR/sign.sh"
@@ -102,13 +109,13 @@ echo "== D1: CUMULATIVE-STATE — two pending changes BOTH render (not just late
   "$STORE" enqueue --seq 1 --class actionable --locators '{"repo":"r","issue":11}' >/dev/null
   "$STORE" enqueue --seq 2 --class actionable --locators '{"repo":"r","issue":22}' >/dev/null
   out="$("$DIGEST" render)" || fail_msg "D1: render exited non-zero"
-  echo "$out" | grep -q 'issue=#11' || fail_msg "D1: OLDER change (issue #11) dropped — digest is a delta, not cumulative state"
-  echo "$out" | grep -q 'issue=#22' || fail_msg "D1: newer change (issue #22) missing"
-  echo "$out" | grep -q 'seq 1' || fail_msg "D1: seq 1 not listed in cumulative set"
-  echo "$out" | grep -q 'seq 2' || fail_msg "D1: seq 2 not listed in cumulative set"
+  echo "$out" | has_match -q 'issue=#11' || fail_msg "D1: OLDER change (issue #11) dropped — digest is a delta, not cumulative state"
+  echo "$out" | has_match -q 'issue=#22' || fail_msg "D1: newer change (issue #22) missing"
+  echo "$out" | has_match -q 'seq 1' || fail_msg "D1: seq 1 not listed in cumulative set"
+  echo "$out" | has_match -q 'seq 2' || fail_msg "D1: seq 2 not listed in cumulative set"
   # A coalescing digest-class entry is STATE (full), not a delta: a later digest
   # subsumes the earlier, but the cumulative unacked set (both actionables) stays.
-  echo "$out" | grep -q 'pending=2' || fail_msg "D1: cumulative pending count wrong (expected 2)"
+  echo "$out" | has_match -q 'pending=2' || fail_msg "D1: cumulative pending count wrong (expected 2)"
 ) && ok
 
 echo "== D2: HARD-LOCATOR enforcement — a malformed actionable claim is QUARANTINED (fail-loud PER-ENTRY, #920); never delivered as valid =="
@@ -127,9 +134,9 @@ echo "== D2: HARD-LOCATOR enforcement — a malformed actionable claim is QUARAN
   # but the unlocated claim is NEVER delivered as a valid CLAIM (fail-loud is
   # preserved, now per-entry). The old exit-4 wedged the entire drain (#920).
   [ "$rc" -eq 0 ] || fail_msg "D2: a malformed actionable must be quarantined (render exit 0, #920), got $rc"
-  printf '%s' "$out" | grep -q 'mergeable=true' && fail_msg "D2: an unlocated actionable claim must NOT be delivered as a valid CLAIM"
-  grep -q 'mergeable=true' "$h/default/dead-letter.jsonl" 2>/dev/null || fail_msg "D2: the malformed claim must be DEAD-LETTERED (fail-loud preserved, per-entry)"
-  grep -qi 'QUARANTINE' "$err" || fail_msg "D2: a LOUD per-entry alarm must fire for the malformed claim"
+  printf '%s' "$out" | has_match -q 'mergeable=true' && fail_msg "D2: an unlocated actionable claim must NOT be delivered as a valid CLAIM"
+  has_match -q 'mergeable=true' "$h/default/dead-letter.jsonl" 2>/dev/null || fail_msg "D2: the malformed claim must be DEAD-LETTERED (fail-loud preserved, per-entry)"
+  has_match -qi 'QUARANTINE' "$err" || fail_msg "D2: a LOUD per-entry alarm must fire for the malformed claim"
 
   # A present-but-imprecise sha (not 40 hex) does NOT satisfy the hard locator ->
   # quarantined, not delivered.
@@ -140,8 +147,8 @@ echo "== D2: HARD-LOCATOR enforcement — a malformed actionable claim is QUARAN
   rc=0
   out="$("$DIGEST" render 2>/dev/null)" || rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D2: imprecise-sha entry must be quarantined (render exit 0), got $rc"
-  printf '%s' "$out" | grep -q 'ci=green' && fail_msg "D2: imprecise sha (not 40-hex) must not satisfy the hard-locator gate (claim must not deliver)"
-  grep -q 'ci=green' "$h/default/dead-letter.jsonl" 2>/dev/null || fail_msg "D2: imprecise-sha claim must be dead-lettered"
+  printf '%s' "$out" | has_match -q 'ci=green' && fail_msg "D2: imprecise sha (not 40-hex) must not satisfy the hard-locator gate (claim must not deliver)"
+  has_match -q 'ci=green' "$h/default/dead-letter.jsonl" 2>/dev/null || fail_msg "D2: imprecise-sha claim must be dead-lettered"
 
   # The SAME claim WITH a precise 40-hex sha renders fine (delivered, not quarantined).
   h="$(fresh_state d2c)"
@@ -149,7 +156,7 @@ echo "== D2: HARD-LOCATOR enforcement — a malformed actionable claim is QUARAN
   export WAKE_STATE_HOME
   "$STORE" enqueue --seq 1 --class actionable --locators "$(jq -cn --arg s "$SHA40" '{claim:"ci=green",sha:$s}')" >/dev/null
   out="$("$DIGEST" render 2>/dev/null)" || fail_msg "D2: a well-located actionable claim must render"
-  printf '%s' "$out" | grep -q "$SHA40" || fail_msg "D2: a well-located actionable claim must be DELIVERED"
+  printf '%s' "$out" | has_match -q "$SHA40" || fail_msg "D2: a well-located actionable claim must be DELIVERED"
   [ -s "$h/default/dead-letter.jsonl" ] && fail_msg "D2: a well-located claim must NOT be quarantined"
   # --- #905 bypass-prevention (STILL enforced, now via quarantine): a NON-
   # CANONICAL entry with a TOP-LEVEL `.claim` (store.sh never emits this shape;
@@ -164,8 +171,8 @@ echo "== D2: HARD-LOCATOR enforcement — a malformed actionable claim is QUARAN
   rc=0
   out="$(printf '%s\n' "$toplevel_claim_entry" | "$DIGEST" render --stdin 2>/dev/null)" || rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D2(#905): top-level .claim must be quarantined via --stdin (exit 0), got $rc"
-  printf '%s' "$out" | grep -q 'mergeable=true' && fail_msg "D2(#905): --stdin top-level-.claim must NOT be delivered (gate not bypassed)"
-  grep -q 'mergeable=true' "$h/default/dead-letter.jsonl" 2>/dev/null || fail_msg "D2(#905): --stdin top-level .claim must be dead-lettered (gate enforced)"
+  printf '%s' "$out" | has_match -q 'mergeable=true' && fail_msg "D2(#905): --stdin top-level-.claim must NOT be delivered (gate not bypassed)"
+  has_match -q 'mergeable=true' "$h/default/dead-letter.jsonl" 2>/dev/null || fail_msg "D2(#905): --stdin top-level .claim must be dead-lettered (gate enforced)"
   ff="$TMP_ROOT/d2d-entry.jsonl"
   printf '%s\n' "$toplevel_claim_entry" >"$ff"
   h="$(fresh_state d2e)"
@@ -174,8 +181,8 @@ echo "== D2: HARD-LOCATOR enforcement — a malformed actionable claim is QUARAN
   rc=0
   out2="$("$DIGEST" render --from-file "$ff" 2>/dev/null)" || rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D2(#905): top-level .claim must be quarantined via --from-file (exit 0), got $rc"
-  printf '%s' "$out2" | grep -q 'mergeable=true' && fail_msg "D2(#905): --from-file top-level-.claim must NOT be delivered (gate not bypassed)"
-  grep -q 'mergeable=true' "$h/default/dead-letter.jsonl" 2>/dev/null || fail_msg "D2(#905): --from-file top-level .claim must be dead-lettered (gate enforced)"
+  printf '%s' "$out2" | has_match -q 'mergeable=true' && fail_msg "D2(#905): --from-file top-level-.claim must NOT be delivered (gate not bypassed)"
+  has_match -q 'mergeable=true' "$h/default/dead-letter.jsonl" 2>/dev/null || fail_msg "D2(#905): --from-file top-level .claim must be dead-lettered (gate enforced)"
 ) && ok
 
 echo "== D3: TWO-TIER — orientation no-op with ZERO tool calls; actionable = claim-to-verify =="
@@ -197,7 +204,7 @@ echo "== D3: TWO-TIER — orientation no-op with ZERO tool calls; actionable = c
   done
   # No pending obligations => no-op common case.
   out="$(PATH="$bin:$PATH" "$DIGEST" render --lane build)" || fail_msg "D3: no-op render failed"
-  echo "$out" | grep -q 'NO-OP' || fail_msg "D3: empty inbox must render an explicit NO-OP orientation"
+  echo "$out" | has_match -q 'NO-OP' || fail_msg "D3: empty inbox must render an explicit NO-OP orientation"
   [ -e "$WAKE_STATE_HOME/TOOL_CALLED" ] && fail_msg "D3: orientation no-op made a live tool call (must be ZERO)"
   # Now an actionable, consequential fact. It must be a CLAIM-TO-VERIFY, never
   # rendered as a trusted assertion or an auto-action.
@@ -206,14 +213,14 @@ echo "== D3: TWO-TIER — orientation no-op with ZERO tool calls; actionable = c
   out2="$(PATH="$bin:$PATH" "$DIGEST" render)" || fail_msg "D3: actionable render failed"
   # Rendering itself still makes ZERO live calls (it only lays out claims).
   [ -e "$WAKE_STATE_HOME/TOOL_CALLED" ] && fail_msg "D3: rendering an actionable claim made a live call (must defer to the consumer's gate)"
-  echo "$out2" | grep -q 'CLAIM@seq' || fail_msg "D3: consequential fact not framed as CLAIM@seq"
-  echo "$out2" | grep -qi 'VERIFY LIVE' || fail_msg "D3: claim not marked for live verification"
-  echo "$out2" | grep -qi 'do NOT act on this line' || fail_msg "D3: claim missing do-not-auto-action framing"
+  echo "$out2" | has_match -q 'CLAIM@seq' || fail_msg "D3: consequential fact not framed as CLAIM@seq"
+  echo "$out2" | has_match -qi 'VERIFY LIVE' || fail_msg "D3: claim not marked for live verification"
+  echo "$out2" | has_match -qi 'do NOT act on this line' || fail_msg "D3: claim missing do-not-auto-action framing"
   # The consequential fact must NOT appear as a bare trusted directive.
-  echo "$out2" | grep -qiE 'merge now|go ahead and (merge|deploy)|safe to merge' &&
+  echo "$out2" | has_match -qiE 'merge now|go ahead and (merge|deploy)|safe to merge' &&
     fail_msg "D3: digest auto-actioned a consequential fact (imperative present)"
   # And its hard locator + one-call re-verify hint are present.
-  echo "$out2" | grep -q "re-verify (ONE call)" || fail_msg "D3: actionable claim missing one-call re-verify locator"
+  echo "$out2" | has_match -q "re-verify (ONE call)" || fail_msg "D3: actionable claim missing one-call re-verify locator"
   true
 ) && ok
 
@@ -229,7 +236,7 @@ echo "== D4: SCRUB — secret-canary + ANSI/bidi/zero-width in source free-text
   "$STORE" enqueue --seq 1 --class actionable --locators "$loc" >/dev/null
   out="$("$DIGEST" render)" || fail_msg "D4: render failed"
   # ANSI escape / CSI must be gone.
-  printf '%s' "$out" | LC_ALL=C grep -q "$(printf '\x1b')" && fail_msg "D4: ANSI ESC survived the scrub"
+  printf '%s' "$out" | LC_ALL=C has_match -q "$(printf '\x1b')" && fail_msg "D4: ANSI ESC survived the scrub"
   # bidi/zero-width/BOM UTF-8 sequences must be gone.
   # #912: patterns are LITERAL bytes + `grep -E`, NOT PCRE `grep -P`. BusyBox
   # grep (Alpine/musl CI) has no `-P` — a `grep -qP` there errors
@@ -244,21 +251,21 @@ echo "== D4: SCRUB — secret-canary + ANSI/bidi/zero-width in source free-text
   _b8b="$(printf '%b' '\x8b')"; _b8f="$(printf '%b' '\x8f')"
   _baa="$(printf '%b' '\xaa')"; _bae="$(printf '%b' '\xae')"
   _bbom="$(printf '%b' '\xef\xbb\xbf')"
-  printf '%s' "$out" | LC_ALL=C grep -qE "${_b280}[${_b8b}-${_b8f}${_baa}-${_bae}]|${_bbom}" &&
+  printf '%s' "$out" | LC_ALL=C has_match -qE "${_b280}[${_b8b}-${_b8f}${_baa}-${_bae}]|${_bbom}" &&
     fail_msg "D4: bidi/zero-width/BOM survived the scrub"
   # C0 control bytes (except tab/newline) must be gone.
   _c00="$(printf '%b' '\x01')"; _c08="$(printf '%b' '\x08')"
   _c0e="$(printf '%b' '\x0e')"; _c1f="$(printf '%b' '\x1f')"; _c7f="$(printf '%b' '\x7f')"
-  printf '%s' "$out" | LC_ALL=C grep -qE "[${_c00}-${_c08}${_c0e}-${_c1f}${_c7f}]" &&
+  printf '%s' "$out" | LC_ALL=C has_match -qE "[${_c00}-${_c08}${_c0e}-${_c1f}${_c7f}]" &&
     fail_msg "D4: a C0 control byte survived the scrub"
   # Secret canaries must be redacted, never inlined.
-  printf '%s' "$out" | grep -q 'ghp_0123456789' && fail_msg "D4: GitHub-token canary LEAKED into the digest"
-  printf '%s' "$out" | grep -q 'AKIAIOSFODNN7EXAMPLE' && fail_msg "D4: AWS-key canary LEAKED into the digest"
-  printf '%s' "$out" | grep -q 'REDACTED-SECRET' || fail_msg "D4: secret redaction marker absent — canary may not have been scrubbed"
+  printf '%s' "$out" | has_match -q 'ghp_0123456789' && fail_msg "D4: GitHub-token canary LEAKED into the digest"
+  printf '%s' "$out" | has_match -q 'AKIAIOSFODNN7EXAMPLE' && fail_msg "D4: AWS-key canary LEAKED into the digest"
+  printf '%s' "$out" | has_match -q 'REDACTED-SECRET' || fail_msg "D4: secret redaction marker absent — canary may not have been scrubbed"
   # Free-text is quoted inside a DELIMITED untrusted block, framed as NOT instructions.
-  printf '%s' "$out" | grep -q 'BEGIN UNTRUSTED DATA' || fail_msg "D4: source free-text not placed in a delimited untrusted block"
+  printf '%s' "$out" | has_match -q 'BEGIN UNTRUSTED DATA' || fail_msg "D4: source free-text not placed in a delimited untrusted block"
   # The 40-hex git SHA locator must NOT be mangled by the secret scrubber.
-  printf '%s' "$out" | grep -q "$SHA40" || fail_msg "D4: legitimate 40-hex SHA locator was wrongly scrubbed"
+  printf '%s' "$out" | has_match -q "$SHA40" || fail_msg "D4: legitimate 40-hex SHA locator was wrongly scrubbed"
   true
 ) && ok
 
@@ -323,11 +330,11 @@ echo "== H2: KEY BY-NAME, never inline; no key leak; same-uid boundary documente
     fail_msg "H2: by-name key resolution failed"
   echo "$env1" | jq -e .wake_mac >/dev/null || fail_msg "H2: no MAC produced from by-name key"
   # The key VALUE must never appear in the signed output.
-  echo "$env1" | grep -q 'SUPERSECRET-KEYVALUE-XYZ' && fail_msg "H2: key material LEAKED into the signed envelope"
+  echo "$env1" | has_match -q 'SUPERSECRET-KEYVALUE-XYZ' && fail_msg "H2: key material LEAKED into the signed envelope"
   # A signed store-entry (hmac placeholder filled) must not leak the key either.
   entry="$(printf '{"observed_seq":1,"locators":{"repo":"r","issue":1},"class":"actionable","emit_ts":1700000000,"hmac":""}' |
     WAKE_HMAC_KEY_NAME=signing-key "$SIGN" sign-entry)"
-  echo "$entry" | grep -q 'SUPERSECRET-KEYVALUE-XYZ' && fail_msg "H2: key material LEAKED into the signed entry"
+  echo "$entry" | has_match -q 'SUPERSECRET-KEYVALUE-XYZ' && fail_msg "H2: key material LEAKED into the signed entry"
   echo "$entry" | jq -e '.hmac != "" and .hmac != null' >/dev/null || fail_msg "H2: sign-entry did not fill the hmac placeholder"
   # No flag may accept key MATERIAL inline — only a key NAME. An attempt to pass
   # a literal key must be rejected as an unknown option (never silently honored).
@@ -341,8 +348,8 @@ echo "== H2: KEY BY-NAME, never inline; no key leak; same-uid boundary documente
     fail_msg "H2: signing with an unresolvable key name must FAIL LOUD"
   fi
   # The same-uid threat boundary + off-uid follow-up must be DOCUMENTED in the tool.
-  grep -qi 'same-uid' "$SIGN" || fail_msg "H2: same-uid threat boundary not documented in sign.sh"
-  grep -qi 'off-uid' "$SIGN" || fail_msg "H2: off-uid future signer not named in sign.sh"
+  has_match -qi 'same-uid' "$SIGN" || fail_msg "H2: same-uid threat boundary not documented in sign.sh"
+  has_match -qi 'off-uid' "$SIGN" || fail_msg "H2: off-uid future signer not named in sign.sh"
 ) && ok
 
 echo "== D5 (#914a): EMBEDDED ACK NAMESPACE — env-less copy-run targets the RENDER-TIME agent, not 'default' =="
@@ -355,7 +362,7 @@ echo "== D5 (#914a): EMBEDDED ACK NAMESPACE — env-less copy-run targets the RE
   out="$(WAKE_AGENT=someagent "$DIGEST" render)" || fail_msg "D5: render (WAKE_AGENT=someagent) failed"
   ack_line="$(printf '%s\n' "$out" | awk '/^-- ACK/{f=1;next} f && NF {print; exit}')"
   [ -n "$ack_line" ] || fail_msg "D5: no embedded ack line extracted from the digest"
-  printf '%s' "$ack_line" | grep -q 'WAKE_AGENT=someagent' ||
+  printf '%s' "$ack_line" | has_match -q 'WAKE_AGENT=someagent' ||
     fail_msg "D5: embedded ack line has no explicit WAKE_AGENT=someagent prefix — an env-less copy-run silently resolves to 'default' [$ack_line]"
   # Actually RUN it with NO WAKE_AGENT in the environment (the real failure
   # mode: a consumer copy-pastes the line into a fresh shell).
@@ -401,12 +408,12 @@ echo "== D6 (#914b): DIGEST-CLASS LOCATOR THREADING — ORIENTATION pointer carr
   loc="$(jq -cn '{kind:"repo", id:"r1", observed_hash:"deadbeefcafe0123456789abcdef0123456789abcdef0123456789abcdef01", remote:"example/repo"}')"
   "$STORE" enqueue --seq 1 --class digest --locators "$loc" >/dev/null
   out="$("$DIGEST" render)" || fail_msg "D6: render failed"
-  orientline="$(printf '%s\n' "$out" | grep -E '^\s*\* seq 1 \[digest\]')"
+  orientline="$(printf '%s\n' "$out" | has_match -E '^\s*\* seq 1 \[digest\]')"
   [ -n "$orientline" ] || fail_msg "D6: no ORIENTATION line found for seq 1"
-  printf '%s' "$orientline" | grep -qE 'locator: *$' &&
+  printf '%s' "$orientline" | has_match -qE 'locator: *$' &&
     fail_msg "D6: digest-class ORIENTATION pointer rendered an EMPTY locator despite a populated .locators field [$orientline]"
   # Must surface something a consumer can act on to re-verify.
-  printf '%s' "$orientline" | grep -qE 'remote=example/repo|id=r1|kind=repo' ||
+  printf '%s' "$orientline" | has_match -qE 'remote=example/repo|id=r1|kind=repo' ||
     fail_msg "D6: digest-class ORIENTATION pointer does not carry a usable locator [$orientline]"
 
   # --- ACTIONABLE-tier hard-locator FAIL-LOUD must be PRESERVED (now PER-ENTRY
@@ -421,14 +428,14 @@ echo "== D6 (#914b): DIGEST-CLASS LOCATOR THREADING — ORIENTATION pointer carr
   rc=0
   out="$("$DIGEST" render 2>"$err")" || rc=$?
   [ "$rc" -eq 0 ] || fail_msg "D6: a malformed actionable is now per-entry quarantined (render exit 0, #920), got $rc"
-  printf '%s' "$out" | grep -q 'mergeable=true' && fail_msg "D6: a malformed actionable claim must NOT be delivered as valid (fail-loud preserved)"
-  grep -q 'mergeable=true' "$h/default/dead-letter.jsonl" 2>/dev/null || fail_msg "D6: a malformed actionable must be DEAD-LETTERED (fail-loud preserved, per-entry)"
-  grep -qi 'QUARANTINE' "$err" || fail_msg "D6: a malformed actionable must raise a loud per-entry alarm"
+  printf '%s' "$out" | has_match -q 'mergeable=true' && fail_msg "D6: a malformed actionable claim must NOT be delivered as valid (fail-loud preserved)"
+  has_match -q 'mergeable=true' "$h/default/dead-letter.jsonl" 2>/dev/null || fail_msg "D6: a malformed actionable must be DEAD-LETTERED (fail-loud preserved, per-entry)"
+  has_match -qi 'QUARANTINE' "$err" || fail_msg "D6: a malformed actionable must raise a loud per-entry alarm"
 ) && ok
 
 echo
 if [ -s "$FAILFILE" ]; then
-  echo "wake digest/hmac harness: FAILED ($(grep -c . "$FAILFILE") assertion(s))" >&2
+  echo "wake digest/hmac harness: FAILED ($(count_lines . "$FAILFILE") assertion(s))" >&2
   exit 1
 fi
 echo "wake digest/hmac harness: all invariants passed ($pass groups)"

packages/mosaic/framework/tools/wake/test-wake-digest-quarantine.sh

@@ -85,8 +85,31 @@
 #          digest.sh dead-letters (a) and (b) — an assertion nobody has seen
 #          succeed is as unproven as one nobody has seen fail.
 #
+# #946 (ack watermark passes quarantined entries): the rendered digest embedded
+# `ack.sh consumed --upto <observed>` even when entries in (consumed, observed]
+# were quarantined — the copy-run line itself instructed the consumer to record
+# deliveries that never happened (live: five successive digests each stepping
+# the consumer past buried seq 68). Fix = DISCLOSE + CLAMP + force-only-past:
+#   Q12    disclosure (by seq — content stays EXCLUDED per Q1/Q4) + the
+#          embedded ack CLAMPED below the lowest quarantined seq, hermetic
+#          --from-file; a foreign-data render must NOT write the store's
+#          quarantined.set.
+#   Q13    nothing quarantined -> unclamped ack at the observed cursor; no
+#          disclosure section, no clamp note.
+#   Q14    store-mode render SYNCS quarantined.set (REPLACE) -> the store's
+#          ordinary consume path refuses past the held seq END-TO-END.
+#   Q15    gate-fix RECOVERY: a stale quarantined.set is REPLACED (cleared) by
+#          a clean store-mode render — the clamp self-heals (#944 recovery
+#          invariant; a cumulative-forever set would keep blocking acks on
+#          entries a fixed gate now renders).
+#   Q16    (guard, green-by-design) Q2's ENUM-B fixture must STAY address-free
+#          so the reconciled exemption remains load-bearing at the gate
+#          (#944 F1); goes RED only if the fixture regresses.
+#
 # Hermetic: feeds controlled JSONL via `digest.sh render --from-file` — NO store,
 # NO network, NO openssl (so it runs identically under the CI openssl-mask).
+# (Q14/Q15 are the intentional exception: the #946 store sync is store-mode-only
+# behavior, so they drive store.sh enqueue/consume against a temp state home.)
 #
 # Each test runs in its own (..) subshell for env isolation; the per-subshell
 # WAKE_STATE_HOME export is intentional (mirrors test-wake-reconcile.sh).
@@ -94,6 +117,13 @@
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# #973: three-valued grep assertion helpers (has_match/count_lines); init saves real stderr for abort loudness.
+# shellcheck disable=SC1091
+if ! . "$SCRIPT_DIR/_wake-common.sh"; then
+  echo "WAKE-ASSERT INIT ABORT: cannot source _wake-common.sh — suite ran ZERO wake assertions (#984)" >&2
+  exit 97
+fi
+wake_assert_init
 DIGEST="$SCRIPT_DIR/digest.sh"
 
 command -v jq >/dev/null 2>&1 || {
@@ -153,12 +183,12 @@ echo "== Q1 (a): malformed address-free {kind,id,observed_hash} QUARANTINES; cle
   out="$("$DIGEST" render --from-file "$f" --agent default 2>"$err")"
   rc=$?
   [ "$rc" -eq 0 ] || fail_msg "Q1: render must EXIT 0 (per-entry quarantine, not whole-digest exit-4), got rc=$rc"
-  printf '%s' "$out" | grep -q "$SHA40" || fail_msg "Q1: the clean sibling (sha $SHA40) must STILL be delivered in the same drain [head-of-line block]"
-  printf '%s' "$out" | grep -q 'MALFORMED-Q' && fail_msg "Q1: the quarantined entry must be EXCLUDED from the rendered digest"
+  printf '%s' "$out" | has_match -q "$SHA40" || fail_msg "Q1: the clean sibling (sha $SHA40) must STILL be delivered in the same drain [head-of-line block]"
+  printf '%s' "$out" | has_match -q 'MALFORMED-Q' && fail_msg "Q1: the quarantined entry must be EXCLUDED from the rendered digest"
   [ -f "$(dlq "$home")" ] || fail_msg "Q1: a durable dead-letter file must be written"
-  grep -q 'MALFORMED-Q' "$(dlq "$home")" 2>/dev/null || fail_msg "Q1: the malformed entry must be DEAD-LETTERED (accounted-for, not silently dropped)"
-  grep -qi 'QUARANTINE' "$err" || fail_msg "Q1: a LOUD per-entry alarm must fire on stderr"
-  grep -q 'observed_seq=1' "$err" || fail_msg "Q1: the alarm must identify the offending entry (observed_seq=1)"
+  has_match -q 'MALFORMED-Q' "$(dlq "$home")" 2>/dev/null || fail_msg "Q1: the malformed entry must be DEAD-LETTERED (accounted-for, not silently dropped)"
+  has_match -qi 'QUARANTINE' "$err" || fail_msg "Q1: a LOUD per-entry alarm must fire on stderr"
+  has_match -q 'observed_seq=1' "$err" || fail_msg "Q1: the alarm must identify the offending entry (observed_seq=1)"
 ) && ok
 
 echo "== Q2 (b): reconciler enumeration (reconciled:true) renders ORIENTATION-tier, NO exit-4 =="
@@ -177,8 +207,8 @@ echo "== Q2 (b): reconciler enumeration (reconciled:true) renders ORIENTATION-ti
   out="$("$DIGEST" render --from-file "$f" --agent default 2>"$err")"
   rc=$?
   [ "$rc" -eq 0 ] || fail_msg "Q2: a reconciler enumeration must NOT exit-4 (it is ORIENTATION-tier), got rc=$rc"
-  printf '%s' "$out" | grep -q 'id=ENUM-B' || fail_msg "Q2: the enumeration must render as an ORIENTATION pointer (id=ENUM-B via _locator_line)"
-  printf '%s' "$out" | grep -q 'CLAIM@seq' && fail_msg "Q2: an enumeration must NOT render as an ACTIONABLE CLAIM@seq"
+  printf '%s' "$out" | has_match -q 'id=ENUM-B' || fail_msg "Q2: the enumeration must render as an ORIENTATION pointer (id=ENUM-B via _locator_line)"
+  printf '%s' "$out" | has_match -q 'CLAIM@seq' && fail_msg "Q2: an enumeration must NOT render as an ACTIONABLE CLAIM@seq"
   [ -s "$(dlq "$home")" ] && fail_msg "Q2: an ORIENTATION-tier enumeration must NOT be quarantined/dead-lettered"
   true
 ) && ok
@@ -197,10 +227,10 @@ echo "== Q3 (c): TWO DISTINCT enumerations BOTH survive as SEPARATE orientation
   out="$("$DIGEST" render --from-file "$f" --agent default 2>"$err")"
   rc=$?
   [ "$rc" -eq 0 ] || fail_msg "Q3: two enumerations must render (exit 0), got rc=$rc"
-  n="$(printf '%s\n' "$out" | grep -c 'id=ENUM-C[12]' || true)"
+  n="$(printf '%s\n' "$out" | count_lines 'id=ENUM-C[12]' || true)"
   [ "$n" = "2" ] || fail_msg "Q3: BOTH distinct enumerations must survive as SEPARATE orientation pointers (expected 2, got $n) — neither coalesced away"
-  printf '%s' "$out" | grep -q 'id=ENUM-C1' || fail_msg "Q3: enumeration ENUM-C1 must be present"
-  printf '%s' "$out" | grep -q 'id=ENUM-C2' || fail_msg "Q3: enumeration ENUM-C2 must be present"
+  printf '%s' "$out" | has_match -q 'id=ENUM-C1' || fail_msg "Q3: enumeration ENUM-C1 must be present"
+  printf '%s' "$out" | has_match -q 'id=ENUM-C2' || fail_msg "Q3: enumeration ENUM-C2 must be present"
   [ -s "$(dlq "$home")" ] && fail_msg "Q3: enumerations must NOT be quarantined"
   true
 ) && ok
@@ -216,10 +246,10 @@ echo "== Q4: PRESERVED — a genuine malformed ACTIONABLE claim is STILL loud (d
   out="$("$DIGEST" render --from-file "$f" --agent default 2>"$err")"
   rc=$?
   [ "$rc" -eq 0 ] || fail_msg "Q4: render must exit 0 (per-entry quarantine), got rc=$rc"
-  printf '%s' "$out" | grep -q 'CLAIM-KEEP' && fail_msg "Q4: a malformed actionable must NOT be delivered as if valid"
-  printf '%s' "$out" | grep -q '(none) — no consequential claims pending' || fail_msg "Q4: with the only claim quarantined, the ACTIONABLE section must show (none)"
-  grep -q 'CLAIM-KEEP' "$(dlq "$home")" 2>/dev/null || fail_msg "Q4: the malformed actionable must be DEAD-LETTERED (loudly surfaced, not silent)"
-  grep -qi 'QUARANTINE' "$err" || fail_msg "Q4: the malformed actionable must raise a LOUD alarm"
+  printf '%s' "$out" | has_match -q 'CLAIM-KEEP' && fail_msg "Q4: a malformed actionable must NOT be delivered as if valid"
+  printf '%s' "$out" | has_match -q '(none) — no consequential claims pending' || fail_msg "Q4: with the only claim quarantined, the ACTIONABLE section must show (none)"
+  has_match -q 'CLAIM-KEEP' "$(dlq "$home")" 2>/dev/null || fail_msg "Q4: the malformed actionable must be DEAD-LETTERED (loudly surfaced, not silent)"
+  has_match -qi 'QUARANTINE' "$err" || fail_msg "Q4: the malformed actionable must raise a LOUD alarm"
 ) && ok
 
 echo "== Q5: claim-precedence gated — a non-actionable-class entry carrying a claim (no hard locator) is STILL quarantined =="
@@ -235,8 +265,8 @@ echo "== Q5: claim-precedence gated — a non-actionable-class entry carrying a
   out="$("$DIGEST" render --from-file "$f" --agent default 2>"$err")"
   rc=$?
   [ "$rc" -eq 0 ] || fail_msg "Q5: render must exit 0, got rc=$rc"
-  grep -q 'CLAIMY' "$(dlq "$home")" 2>/dev/null || fail_msg "Q5: a claim-carrying entry with no hard locator must be quarantined (claim precedence, §2.1)"
-  printf '%s' "$out" | grep -q 'CI is green' && fail_msg "Q5: the un-verifiable claim must NOT be delivered"
+  has_match -q 'CLAIMY' "$(dlq "$home")" 2>/dev/null || fail_msg "Q5: a claim-carrying entry with no hard locator must be quarantined (claim precedence, §2.1)"
+  printf '%s' "$out" | has_match -q 'CI is green' && fail_msg "Q5: the un-verifiable claim must NOT be delivered"
   true
 ) && ok
 
@@ -255,11 +285,11 @@ echo "== Q6 (a): dead-lettered entry routes EXACTLY ONE off-host alarm (payload
   out="$("$DIGEST" render --from-file "$f" --agent default 2>"$err")"
   rc=$?
   [ "$rc" -eq 0 ] || fail_msg "Q6: render must still EXIT 0 (per-entry quarantine, not whole-drain wedge), got rc=$rc"
-  n="$(grep -c . "$ALARM_OUT" 2>/dev/null || true)"
+  n="$(count_lines . "$ALARM_OUT" 2>/dev/null || true)"
   [ "$n" = "1" ] || fail_msg "Q6: EXACTLY ONE off-host alarm must route for the dead-lettered entry (got $n) [$(cat "$ALARM_OUT" 2>/dev/null)]"
-  grep -q '"observed_seq":21' "$ALARM_OUT" 2>/dev/null || fail_msg "Q6: the routed alarm payload must name the entry's observed_seq (21)"
-  grep -qi 'QUARANTINE' "$err" || fail_msg "Q6: the existing #920 stderr diagnostic must STILL fire (local + off-host, not either/or)"
-  printf '%s' "$out" | grep -q 'DLQ-Q6' && fail_msg "Q6: the quarantined entry must still be EXCLUDED from the rendered digest"
+  has_match -q '"observed_seq":21' "$ALARM_OUT" 2>/dev/null || fail_msg "Q6: the routed alarm payload must name the entry's observed_seq (21)"
+  has_match -qi 'QUARANTINE' "$err" || fail_msg "Q6: the existing #920 stderr diagnostic must STILL fire (local + off-host, not either/or)"
+  printf '%s' "$out" | has_match -q 'DLQ-Q6' && fail_msg "Q6: the quarantined entry must still be EXCLUDED from the rendered digest"
   true
 ) && ok
 
@@ -277,9 +307,9 @@ echo "== Q7 (b): re-draining the SAME still-dead-lettered entry N times routes Z
   for i in 1 2 3 4; do
     "$DIGEST" render --from-file "$f" --agent default >/dev/null 2>"$TMP_ROOT/q7.err.$i"
   done
-  n="$(grep -c . "$ALARM_OUT" 2>/dev/null || true)"
+  n="$(count_lines . "$ALARM_OUT" 2>/dev/null || true)"
   [ "$n" = "1" ] || fail_msg "Q7: re-draining the SAME dead-lettered entry 4x must route ONLY ONE off-host alarm total (durable dedup by observed_seq); got $n [$(cat "$ALARM_OUT" 2>/dev/null)]"
-  grep -qi 'QUARANTINE' "$TMP_ROOT/q7.err.4" || fail_msg "Q7: the #920 stderr diagnostic must STILL fire on every re-drain (only the off-host route is deduped)"
+  has_match -qi 'QUARANTINE' "$TMP_ROOT/q7.err.4" || fail_msg "Q7: the #920 stderr diagnostic must STILL fire on every re-drain (only the off-host route is deduped)"
 ) && ok
 
 echo "== Q8 (c): a NEW distinct dead-lettered entry routes its OWN one alarm (dedup is per-entry, not a global latch) =="
@@ -298,10 +328,10 @@ echo "== Q8 (c): a NEW distinct dead-lettered entry routes its OWN one alarm (de
   "$DIGEST" render --from-file "$f1" --agent default >/dev/null 2>/dev/null
   "$DIGEST" render --from-file "$f1" --agent default >/dev/null 2>/dev/null # re-drain seq 31 -> must NOT re-alarm
   "$DIGEST" render --from-file "$f2" --agent default >/dev/null 2>/dev/null # NEW distinct seq 32 -> its own alarm
-  n="$(grep -c . "$ALARM_OUT" 2>/dev/null || true)"
+  n="$(count_lines . "$ALARM_OUT" 2>/dev/null || true)"
   [ "$n" = "2" ] || fail_msg "Q8: two DISTINCT dead-lettered entries must together route exactly 2 off-host alarms total (got $n) [$(cat "$ALARM_OUT" 2>/dev/null)]"
-  grep -q '"observed_seq":31' "$ALARM_OUT" 2>/dev/null || fail_msg "Q8: seq 31's alarm must be present"
-  grep -q '"observed_seq":32' "$ALARM_OUT" 2>/dev/null || fail_msg "Q8: seq 32's (the new distinct entry's) OWN alarm must be present"
+  has_match -q '"observed_seq":31' "$ALARM_OUT" 2>/dev/null || fail_msg "Q8: seq 31's alarm must be present"
+  has_match -q '"observed_seq":32' "$ALARM_OUT" 2>/dev/null || fail_msg "Q8: seq 32's (the new distinct entry's) OWN alarm must be present"
 ) && ok
 
 echo "== Q9 (d): WAKE_ALARM_SINK_CMD unconfigured OR unreachable -> FAIL LOUD (never silent no-alarm); per-entry, render still exits 0 =="
@@ -317,9 +347,9 @@ echo "== Q9 (d): WAKE_ALARM_SINK_CMD unconfigured OR unreachable -> FAIL LOUD (n
   out_a="$("$DIGEST" render --from-file "$f" --agent default 2>"$err_a")"
   rc_a=$?
   [ "$rc_a" -eq 0 ] || fail_msg "Q9a: per-entry quarantine must still exit 0 even when the off-host alarm sink is unconfigured (no whole-drain wedge), got rc=$rc_a"
-  grep -qi 'FAIL LOUD' "$err_a" || fail_msg "Q9a: an unconfigured off-host alarm target must FAIL LOUD on stderr [$(cat "$err_a")]"
-  grep -Eqi 'silent no-alarm|silent-miss|PERMANENTLY miss|permanent silent miss' "$err_a" || fail_msg "Q9a: the diagnostic must name the silent-miss hazard (G2a), mirroring beacon.sh's fail-closed wording [$(cat "$err_a")]"
-  printf '%s' "$out_a" | grep -q 'DLQ-Q9' && fail_msg "Q9a: the quarantined entry must still be EXCLUDED from the rendered digest"
+  has_match -qi 'FAIL LOUD' "$err_a" || fail_msg "Q9a: an unconfigured off-host alarm target must FAIL LOUD on stderr [$(cat "$err_a")]"
+  has_match -Eqi 'silent no-alarm|silent-miss|PERMANENTLY miss|permanent silent miss' "$err_a" || fail_msg "Q9a: the diagnostic must name the silent-miss hazard (G2a), mirroring beacon.sh's fail-closed wording [$(cat "$err_a")]"
+  printf '%s' "$out_a" | has_match -q 'DLQ-Q9' && fail_msg "Q9a: the quarantined entry must still be EXCLUDED from the rendered digest"
   true
 ) && ok
 (
@@ -332,9 +362,9 @@ echo "== Q9 (d): WAKE_ALARM_SINK_CMD unconfigured OR unreachable -> FAIL LOUD (n
   out_b="$("$DIGEST" render --from-file "$f" --agent default 2>"$err_b")"
   rc_b=$?
   [ "$rc_b" -eq 0 ] || fail_msg "Q9b: per-entry quarantine must still exit 0 even when the off-host alarm sink is unreachable, got rc=$rc_b"
-  grep -qi 'FAIL LOUD' "$err_b" || fail_msg "Q9b: an unreachable off-host alarm target must FAIL LOUD on stderr [$(cat "$err_b")]"
-  grep -qi 'UNREACHABLE' "$err_b" || fail_msg "Q9b: the diagnostic must name the unreachable target [$(cat "$err_b")]"
-  printf '%s' "$out_b" | grep -q 'DLQ-Q9' && fail_msg "Q9b: the quarantined entry must still be EXCLUDED from the rendered digest"
+  has_match -qi 'FAIL LOUD' "$err_b" || fail_msg "Q9b: an unreachable off-host alarm target must FAIL LOUD on stderr [$(cat "$err_b")]"
+  has_match -qi 'UNREACHABLE' "$err_b" || fail_msg "Q9b: the diagnostic must name the unreachable target [$(cat "$err_b")]"
+  printf '%s' "$out_b" | has_match -q 'DLQ-Q9' && fail_msg "Q9b: the quarantined entry must still be EXCLUDED from the rendered digest"
   true
 ) && ok
 
@@ -360,16 +390,16 @@ echo "== Q10: snapshot metadata (#940) — snapshot_sha/snapshot_ts render on th
   out="$("$DIGEST" render --from-file "$f" --agent default 2>/dev/null)"
   rc=$?
   [ "$rc" -eq 0 ] || fail_msg "Q10: render must succeed (rc=$rc)"
-  snapa_line="$(printf '%s\n' "$out" | grep 'id=SNAP-A' || true)"
-  printf '%s' "$snapa_line" | grep -q 'snapshot_sha=0123abc4567890def0123abc4567890def012345' \
+  snapa_line="$(printf '%s\n' "$out" | has_match 'id=SNAP-A' || true)"
+  printf '%s' "$snapa_line" | has_match -q 'snapshot_sha=0123abc4567890def0123abc4567890def012345' \
     || fail_msg "Q10: snapshot_sha must render on the ORIENTATION pointer line [$snapa_line]"
-  printf '%s' "$snapa_line" | grep -q 'snapshot_ts=1753850000' \
+  printf '%s' "$snapa_line" | has_match -q 'snapshot_ts=1753850000' \
     || fail_msg "Q10: snapshot_ts must render on the ORIENTATION pointer line (age = emit_ts - snapshot_ts, local arithmetic) [$snapa_line]"
-  printf '%s' "$out" | grep -q 'git show 0123abc4567890def0123abc4567890def012345:BOARD.md' \
+  printf '%s' "$out" | has_match -q 'git show 0123abc4567890def0123abc4567890def012345:BOARD.md' \
     || fail_msg "Q10: snapshot_sha+path must upgrade the actionable re-verify hint to a one-call git show"
   # The sibling without metadata must not grow empty snapshot_ fields.
-  snapb_line="$(printf '%s\n' "$out" | grep 'id=SNAP-B' || true)"
-  printf '%s' "$snapb_line" | grep -q 'snapshot_' \
+  snapb_line="$(printf '%s\n' "$out" | has_match 'id=SNAP-B' || true)"
+  printf '%s' "$snapb_line" | has_match -q 'snapshot_' \
     && fail_msg "Q10: an entry without metadata must render NO snapshot_ fields [$snapb_line]"
   true
 ) && ok
@@ -411,35 +441,151 @@ echo "== Q11 (#944): REAL detector-shape actionable RENDERS as CLAIM@seq; addres
   [ "$rc" -eq 0 ] || fail_msg "Q11: render must exit 0, got rc=$rc"
   # (a) POSITIVE: the live entry RENDERS as an actionable claim (not merely
   #     passes the predicate) with the one-call git-show re-verify hint.
-  printf '%s' "$out" | grep -q 'seq 68 — CLAIM@seq' || fail_msg "Q11a: the live seq-68 detector-shape entry must RENDER as CLAIM@seq (positive control)"
-  printf '%s' "$out" | grep -q 'git show 55d4909569d2b5fbccfec49ec9ca83db5049f3ce:docs/scratchpads/heartbeat-planning' \
+  printf '%s' "$out" | has_match -q 'seq 68 — CLAIM@seq' || fail_msg "Q11a: the live seq-68 detector-shape entry must RENDER as CLAIM@seq (positive control)"
+  printf '%s' "$out" | has_match -q 'git show 55d4909569d2b5fbccfec49ec9ca83db5049f3ce:docs/scratchpads/heartbeat-planning' \
     || fail_msg "Q11a: the rendered claim must carry the one-call re-verify hint git show <snapshot_sha>:<path>"
   # (b) POSITIVE: path arm alone suffices; hint degrades to one-call re-read.
-  printf '%s' "$out" | grep -q 'seq 69 — CLAIM@seq' || fail_msg "Q11b: a path-only detector-shape entry must RENDER as CLAIM@seq (path arm)"
-  printf '%s' "$out" | grep -q 're-read BOARD.md' || fail_msg "Q11b: the path-only claim must carry the one-call re-read <path> hint"
-  n_claims="$(printf '%s\n' "$out" | grep -c 'CLAIM@seq' || true)"
+  printf '%s' "$out" | has_match -q 'seq 69 — CLAIM@seq' || fail_msg "Q11b: a path-only detector-shape entry must RENDER as CLAIM@seq (path arm)"
+  printf '%s' "$out" | has_match -q 're-read BOARD.md' || fail_msg "Q11b: the path-only claim must carry the one-call re-read <path> hint"
+  n_claims="$(printf '%s\n' "$out" | count_lines 'CLAIM@seq' || true)"
   [ "$n_claims" = "2" ] || fail_msg "Q11: EXACTLY the two valid entries must render as CLAIM@seq (got $n_claims)"
   # (c)+(d) NEGATIVES retained: both quarantine, each with its OWN alarm.
-  printf '%s' "$out" | grep -q 'ADDR-FREE' && fail_msg "Q11c: the address-free entry must be EXCLUDED from the digest"
-  printf '%s' "$out" | grep -q 'SNAP-ONLY' && fail_msg "Q11d: no bare path-less snapshot_sha entry may appear in the digest (gate must not widen past board_file)"
-  grep -q 'ADDR-FREE' "$(dlq "$home")" 2>/dev/null || fail_msg "Q11c: the address-free entry must be DEAD-LETTERED"
+  printf '%s' "$out" | has_match -q 'ADDR-FREE' && fail_msg "Q11c: the address-free entry must be EXCLUDED from the digest"
+  printf '%s' "$out" | has_match -q 'SNAP-ONLY' && fail_msg "Q11d: no bare path-less snapshot_sha entry may appear in the digest (gate must not widen past board_file)"
+  has_match -q 'ADDR-FREE' "$(dlq "$home")" 2>/dev/null || fail_msg "Q11c: the address-free entry must be DEAD-LETTERED"
   for snap_id in SNAP-ONLY-40 SNAP-ONLY-7 SNAP-ONLY-64; do
-    grep -q "$snap_id" "$(dlq "$home")" 2>/dev/null || fail_msg "Q11d: the bare snapshot_sha entry ($snap_id) must be DEAD-LETTERED"
+    has_match -q "$snap_id" "$(dlq "$home")" 2>/dev/null || fail_msg "Q11d: the bare snapshot_sha entry ($snap_id) must be DEAD-LETTERED"
   done
-  grep -q 'heartbeat-planning' "$(dlq "$home")" 2>/dev/null && fail_msg "Q11a: the valid live entry must NOT be dead-lettered"
-  grep -q 'PILOT-LOCAL' "$(dlq "$home")" 2>/dev/null && fail_msg "Q11b: the valid path-only entry must NOT be dead-lettered"
-  n_alarms="$(grep -c . "$ALARM_OUT" 2>/dev/null || true)"
+  has_match -q 'heartbeat-planning' "$(dlq "$home")" 2>/dev/null && fail_msg "Q11a: the valid live entry must NOT be dead-lettered"
+  has_match -q 'PILOT-LOCAL' "$(dlq "$home")" 2>/dev/null && fail_msg "Q11b: the valid path-only entry must NOT be dead-lettered"
+  n_alarms="$(count_lines . "$ALARM_OUT" 2>/dev/null || true)"
   [ "$n_alarms" = "4" ] || fail_msg "Q11: exactly the four invalid entries must alarm (got $n_alarms) [$(cat "$ALARM_OUT" 2>/dev/null)]"
-  grep -q '"observed_seq":70' "$ALARM_OUT" 2>/dev/null || fail_msg "Q11c: seq 70's own alarm must be present"
+  has_match -q '"observed_seq":70' "$ALARM_OUT" 2>/dev/null || fail_msg "Q11c: seq 70's own alarm must be present"
   for snap_seq in 71 72 73; do
-    grep -q "\"observed_seq\":$snap_seq" "$ALARM_OUT" 2>/dev/null || fail_msg "Q11d: seq $snap_seq's own alarm must be present"
+    has_match -q "\"observed_seq\":$snap_seq" "$ALARM_OUT" 2>/dev/null || fail_msg "Q11d: seq $snap_seq's own alarm must be present"
   done
   true
 ) && ok
 
+echo "== Q12 (#946): quarantined entries are DISCLOSED (by seq, content withheld) and the embedded ack is CLAMPED below them =="
+(
+  home="$(fresh_home q12)"
+  export WAKE_STATE_HOME="$home"
+  unset WAKE_AGENT
+  mkdir -p "$home/default"
+  printf '2' >"$home/default/observed_seq"
+  f="$TMP_ROOT/q12.jsonl"
+  {
+    printf '{"observed_seq":1,"class":"actionable","locators":{"sha":"%s","file":"src/a.ts"},"emit_ts":1}\n' "$SHA40"
+    printf '%s\n' '{"observed_seq":2,"class":"actionable","locators":{"kind":"board_file","id":"ADDR-Q12","observed_hash":"qq12"},"emit_ts":1}'
+  } >"$f"
+  out="$("$DIGEST" render --from-file "$f" --agent default 2>/dev/null)"
+  rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "Q12: render must exit 0, got rc=$rc"
+  # DISCLOSURE: a held entry must be VISIBLE in the digest it was held from —
+  # a silent hold is how five successive digests each stepped past seq 68...
+  printf '%s' "$out" | has_match -q 'QUARANTINED' || fail_msg "Q12: the digest must carry a QUARANTINED disclosure section (no silent hold)"
+  printf '%s' "$out" | has_match -q 'seq 2 .*HELD' || fail_msg "Q12: the disclosure must name the held seq (2) as HELD"
+  # ...but WITHOUT re-injecting the refused content: disclosure is by seq only;
+  # the Q1/Q4/Q5/Q6/Q9/Q11 exclusion property stands.
+  printf '%s' "$out" | has_match -q 'ADDR-Q12' && fail_msg "Q12: the quarantined entry's content/locators must stay EXCLUDED from the digest"
+  # CLAMP: the embedded ack stops BELOW the quarantined seq, and says so loudly.
+  printf '%s' "$out" | has_match -Eq 'consumed --upto 1$' || fail_msg "Q12: the embedded ack must be CLAMPED to --upto 1 (below quarantined seq 2)"
+  printf '%s' "$out" | has_match -Eq 'consumed --upto 2( |$)' && fail_msg "Q12: the raw observed cursor (2) must NOT be embedded while seq 2 is quarantined"
+  printf '%s' "$out" | has_match -q 'ACK CLAMPED' || fail_msg "Q12: the clamp must be LOUDLY disclosed in the ACK section"
+  # A foreign-data render must NOT rewrite the lane's quarantine truth.
+  [ -e "$home/default/quarantined.set" ] && fail_msg "Q12: a --from-file render must NOT write the store's quarantined.set (lane truth is store-mode only)"
+  true
+) && ok
+
+echo "== Q13 (#946): nothing quarantined -> ack UNCLAMPED at the observed cursor; no disclosure section, no clamp note =="
+(
+  home="$(fresh_home q13)"
+  export WAKE_STATE_HOME="$home"
+  unset WAKE_AGENT
+  mkdir -p "$home/default"
+  printf '1' >"$home/default/observed_seq"
+  f="$TMP_ROOT/q13.jsonl"
+  printf '{"observed_seq":1,"class":"actionable","locators":{"sha":"%s","file":"src/a.ts"},"emit_ts":1}\n' "$SHA40" >"$f"
+  out="$("$DIGEST" render --from-file "$f" --agent default 2>/dev/null)"
+  rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "Q13: render must exit 0, got rc=$rc"
+  printf '%s' "$out" | has_match -Eq 'consumed --upto 1$' || fail_msg "Q13: with nothing quarantined the ack must embed the observed cursor (1) unchanged"
+  printf '%s' "$out" | has_match -q 'QUARANTINED' && fail_msg "Q13: no disclosure section when nothing is quarantined"
+  printf '%s' "$out" | has_match -q 'ACK CLAMPED' && fail_msg "Q13: no clamp note when nothing is quarantined"
+  true
+) && ok
+
+echo "== Q14 (#946): store-mode render SYNCS quarantine truth into the store — the clamp is enforced END-TO-END at consume =="
+(
+  home="$(fresh_home q14)"
+  export WAKE_STATE_HOME="$home"
+  unset WAKE_AGENT
+  STORE="$SCRIPT_DIR/store.sh"
+  "$STORE" enqueue --class actionable --locators "{\"sha\":\"$SHA40\",\"file\":\"src/a.ts\"}" >/dev/null
+  "$STORE" enqueue --class actionable --locators '{"kind":"board_file","id":"ADDR-Q14","observed_hash":"qq14"}' >/dev/null
+  out="$("$DIGEST" render --from-store --agent default 2>/dev/null)"
+  rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "Q14: render must exit 0, got rc=$rc"
+  printf '%s' "$out" | has_match -q 'QUARANTINED' || fail_msg "Q14: the store-mode digest must disclose the held entry"
+  printf '%s' "$out" | has_match -Eq 'consumed --upto 1$' || fail_msg "Q14: the embedded ack must clamp to 1 (below quarantined seq 2)"
+  qf="$home/default/quarantined.set"
+  [ "$(cat "$qf" 2>/dev/null)" = "2" ] || fail_msg "Q14: a store-mode render must sync quarantined.set to exactly {2}, got [$(cat "$qf" 2>/dev/null)]"
+  # END-TO-END: even a hand-typed upto past the held seq is refused at the
+  # store — the copy-run defect (#946) cannot re-land via a different path.
+  if "$STORE" consume --upto 2 >/dev/null 2>&1; then
+    fail_msg "Q14: store consume --upto 2 must be REFUSED after the render synced the quarantine"
+  fi
+  "$STORE" consume --upto 1 >/dev/null 2>&1 || fail_msg "Q14: consume --upto 1 (the clamped value) must succeed"
+) && ok
+
+echo "== Q15 (#946): gate-fix RECOVERY — a stale quarantined.set is REPLACED by a clean store-mode render; the clamp self-heals =="
+(
+  home="$(fresh_home q15)"
+  export WAKE_STATE_HOME="$home"
+  unset WAKE_AGENT
+  STORE="$SCRIPT_DIR/store.sh"
+  "$STORE" enqueue --class actionable --locators "{\"sha\":\"$SHA40\",\"file\":\"src/a.ts\"}" >/dev/null
+  "$STORE" enqueue --class actionable --locators '{"kind":"board_file","id":"OK-NOW","observed_hash":"h","path":"BOARD.md"}' >/dev/null
+  # A stale set from a broken-gate era: both seqs wrongly quarantined.
+  printf '1\n2\n' >"$home/default/quarantined.set"
+  out="$("$DIGEST" render --from-store --agent default 2>/dev/null)"
+  rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "Q15: render must exit 0, got rc=$rc"
+  printf '%s' "$out" | has_match -q 'QUARANTINED' && fail_msg "Q15: nothing quarantines under the fixed gate — no disclosure section"
+  printf '%s' "$out" | has_match -Eq 'consumed --upto 2$' || fail_msg "Q15: the ack must embed the full observed cursor (2) once the gate is fixed"
+  [ -s "$home/default/quarantined.set" ] && fail_msg "Q15: the clean render must REPLACE (clear) the stale quarantined.set — a cumulative-forever set would block acks on entries that now render, got [$(cat "$home/default/quarantined.set")]"
+  "$STORE" consume --upto 2 >/dev/null 2>&1 || fail_msg "Q15: the ordinary consume must succeed after the clamp self-heals"
+) && ok
+
+echo "== Q16 (guard): Q2's ENUM-B fixture must STAY address-free — the reconciled exemption must remain load-bearing at the gate (#944 F1) =="
+(
+  self="$SCRIPT_DIR/test-wake-digest-quarantine.sh"
+  # Token concatenated so THIS guard's own source lines never contain the
+  # literal fixture id and cannot self-match.
+  enum_id='ENUM''-B'
+  fixture_line="$(has_match -F "\"id\":\"$enum_id\"" "$self" | has_match -F '"observed_seq":5' | head -n1)"
+  [ -n "$fixture_line" ] || fail_msg "Q16: could not locate Q2's $enum_id fixture line (renamed/renumbered? update this guard)"
+  fixture_json="$(printf '%s' "$fixture_line" | sed "s/.*'\({.*}\)'.*/\1/")"
+  # Positive controls FIRST (blind-instrument rule): the extraction must yield
+  # the real fixture, and the predicate must be able to detect a hard locator.
+  printf '%s' "$fixture_json" | jq -e . >/dev/null 2>&1 || fail_msg "Q16: extracted fixture is not valid JSON [$fixture_json]"
+  printf '%s' "$fixture_json" | jq -e '.locators.reconciled == true' >/dev/null 2>&1 || fail_msg "Q16: fixture must carry reconciled:true (wrong line extracted?) [$fixture_json]"
+  hard_arms='.locators | ((.repo // "") != "" and (((.issue // "") | tostring) != "")) or (((.sha // "") | tostring) | test("^[0-9a-f]{40}$")) or ((.file // "") != "") or ((.path // "") != "")'
+  printf '%s' '{"locators":{"path":"BOARD.md"}}' | jq -e "$hard_arms" >/dev/null 2>&1 || fail_msg "Q16: positive control failed — the inline hard-locator predicate did not detect a path arm (instrument broken; re-sync it with digest.sh _has_hard_locator)"
+  # THE GUARD: the fixture must remain ADDRESS-FREE. If it ever gains a hard
+  # locator, Q2 passes the gate for the wrong reason and the reconciled
+  # exemption stops being exercised (#944 F1: an exemption nobody exercises is
+  # as unproven as a gate nobody has seen refuse).
+  if printf '%s' "$fixture_json" | jq -e "$hard_arms" >/dev/null 2>&1; then
+    fail_msg "Q16: Q2's $enum_id fixture has grown a hard-locator arm — restore an address-free fixture so the reconciled exemption stays load-bearing [$fixture_json]"
+  fi
+  true
+) && ok
+
 echo
 if [ -s "$FAILFILE" ]; then
-  echo "wake digest-quarantine harness: FAILED ($(grep -c . "$FAILFILE") assertion(s))" >&2
+  echo "wake digest-quarantine harness: FAILED ($(count_lines . "$FAILFILE") assertion(s))" >&2
   exit 1
 fi
 echo "wake digest-quarantine harness: all invariants passed ($pass groups)"

packages/mosaic/framework/tools/wake/test-wake-fn-oracle.sh

@@ -25,6 +25,13 @@
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# #973: three-valued grep assertion helpers (has_match/count_lines); init saves real stderr for abort loudness.
+# shellcheck disable=SC1091
+if ! . "$SCRIPT_DIR/_wake-common.sh"; then
+  echo "WAKE-ASSERT INIT ABORT: cannot source _wake-common.sh — suite ran ZERO wake assertions (#984)" >&2
+  exit 97
+fi
+wake_assert_init
 ORACLE="$SCRIPT_DIR/fn-oracle.sh"
 DET="$SCRIPT_DIR/detector.sh"
 
@@ -62,8 +69,8 @@ echo "== O1: healthy pipeline -> synthetic-canary FN-rate = 0 =="
   out="$("$ORACLE" run --slo-seconds 120 --count 3 2>&1)"
   rc=$?
   [ "$rc" -eq 0 ] || fail_msg "O1: a healthy pipeline must exit 0 (got $rc) [$out]"
-  echo "$out" | grep -q 'FN-RATE = 0/3' || fail_msg "O1: FN-rate must be 0/3 on a healthy pipeline [$out]"
-  echo "$out" | grep -q 'VERDICT = PASS' || fail_msg "O1: verdict must be PASS on a healthy pipeline [$out]"
+  echo "$out" | has_match -q 'FN-RATE = 0/3' || fail_msg "O1: FN-rate must be 0/3 on a healthy pipeline [$out]"
+  echo "$out" | has_match -q 'VERDICT = PASS' || fail_msg "O1: verdict must be PASS on a healthy pipeline [$out]"
 ) && ok
 
 echo "== O2: DISABLED detector (perfect no-op) -> FN-DETECTED (blindspot killer) =="
@@ -76,9 +83,9 @@ echo "== O2: DISABLED detector (perfect no-op) -> FN-DETECTED (blindspot killer)
   out="$("$ORACLE" run --slo-seconds 120 --count 3 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "O2: a detector that drops a KNOWN delta MUST fail the oracle (non-zero exit), even at a perfect no-op rate"
-  echo "$out" | grep -q 'FN-RATE = 3/3' || fail_msg "O2: every dropped canary must count as a false-negative (FN-RATE 3/3) [$out]"
-  echo "$out" | grep -q 'VERDICT = FN-DETECTED' || fail_msg "O2: verdict must be FN-DETECTED for a dropping detector [$out]"
-  echo "$out" | grep -qi 'never OBSERVED' || fail_msg "O2: the failure must name the dropped (never-observed) delta [$out]"
+  echo "$out" | has_match -q 'FN-RATE = 3/3' || fail_msg "O2: every dropped canary must count as a false-negative (FN-RATE 3/3) [$out]"
+  echo "$out" | has_match -q 'VERDICT = FN-DETECTED' || fail_msg "O2: verdict must be FN-DETECTED for a dropping detector [$out]"
+  echo "$out" | has_match -qi 'never OBSERVED' || fail_msg "O2: the failure must name the dropped (never-observed) delta [$out]"
 ) && ok
 
 echo "== O3: reached CONSUMED but too slow -> FN-DETECTED (within-SLO clause) =="
@@ -91,10 +98,10 @@ echo "== O3: reached CONSUMED but too slow -> FN-DETECTED (within-SLO clause) ==
   out="$("$ORACLE" run --slo-seconds 1 --count 1 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "O3: a canary that reaches CONSUMED past its SLO must be a false-negative (non-zero exit)"
-  echo "$out" | grep -qi 'per-class SLO' || fail_msg "O3: the failure must attribute to the per-class SLO, not a drop [$out]"
+  echo "$out" | has_match -qi 'per-class SLO' || fail_msg "O3: the failure must attribute to the per-class SLO, not a drop [$out]"
   # It must NOT be the 'never observed' branch: the delta WAS observed/delivered,
   # just too slowly. This proves O3 exercises the SLO clause specifically.
-  if echo "$out" | grep -qi 'never OBSERVED'; then
+  if echo "$out" | has_match -qi 'never OBSERVED'; then
     fail_msg "O3: an SLO breach must NOT be misreported as a dropped delta [$out]"
   fi
 ) && ok
@@ -110,7 +117,7 @@ echo "== O4: verdict is OFF-DOMAIN (from terminal consumed_seq, not detector sel
   out="$("$ORACLE" run --slo-seconds 120 --count 1 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "O4: a drive that exits 0 but delivers nothing must still be FN-DETECTED (verdict is off-domain)"
-  echo "$out" | grep -q 'VERDICT = FN-DETECTED' || fail_msg "O4: off-domain verdict must not be fooled by a clean exit code [$out]"
+  echo "$out" | has_match -q 'VERDICT = FN-DETECTED' || fail_msg "O4: off-domain verdict must not be fooled by a clean exit code [$out]"
 ) && ok
 
 echo "== O5: no invented SLO -> --slo-seconds is REQUIRED (fail-loud) =="
@@ -121,12 +128,12 @@ echo "== O5: no invented SLO -> --slo-seconds is REQUIRED (fail-loud) =="
   err="$("$ORACLE" run --count 1 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "O5: run without an SLO must fail loud (no invented default)"
-  echo "$err" | grep -qi 'slo' || fail_msg "O5: the usage error must name the missing SLO [$err]"
+  echo "$err" | has_match -qi 'slo' || fail_msg "O5: the usage error must name the missing SLO [$err]"
 ) && ok
 
 echo
 if [ -s "$FAILFILE" ]; then
-  echo "wake fn-oracle harness: FAILED ($(grep -c . "$FAILFILE") assertion(s))" >&2
+  echo "wake fn-oracle harness: FAILED ($(count_lines . "$FAILFILE") assertion(s))" >&2
   exit 1
 fi
 echo "wake fn-oracle harness: all invariants passed ($pass groups)"

packages/mosaic/framework/tools/wake/test-wake-install.sh

@@ -34,6 +34,13 @@
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# #973: three-valued grep assertion helpers (has_match/count_lines); init saves real stderr for abort loudness.
+# shellcheck disable=SC1091
+if ! . "$SCRIPT_DIR/_wake-common.sh"; then
+  echo "WAKE-ASSERT INIT ABORT: cannot source _wake-common.sh — suite ran ZERO wake assertions (#984)" >&2
+  exit 97
+fi
+wake_assert_init
 WI="$SCRIPT_DIR/wake-install.sh"
 BEACON="$SCRIPT_DIR/beacon.sh"
 FRAMEWORK_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
@@ -94,7 +101,7 @@ EOF
   export WAKE_INSTALL_MANIFEST="$BAD_MANIFEST"
   out="$(bash "$WI" install 2>&1)"; rc=$?
   [ "$rc" -ne 0 ] || fail_msg "I2: install must FAIL when a wake candidate is not framework-owned (got rc=$rc)"
-  echo "$out" | grep -qi 'Gate A VIOLATION' || fail_msg "I2: refusal must name the Gate A violation [$out]"
+  echo "$out" | has_match -qi 'Gate A VIOLATION' || fail_msg "I2: refusal must name the Gate A violation [$out]"
   # No partial write: the target must have received NO wake tool file.
   [ ! -e "$TGT/tools/wake/beacon.sh" ] || fail_msg "I2: a refused install must not have written any wake file (partial write leaked)"
   # And the positive control: with the REAL manifest, the same candidates install.
@@ -121,7 +128,7 @@ EOF
     || fail_msg "I3: blank-reset drop-in write failed"
   out="$(bash "$WI" verify-single "$UNIT" 2>&1)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "I3: blank-reset must resolve exactly one OnUnitActiveUSec (rc=$rc) [$out]"
-  echo "$out" | grep -qi 'EXACTLY ONE' || fail_msg "I3: verify must confirm exactly-one [$out]"
+  echo "$out" | has_match -qi 'EXACTLY ONE' || fail_msg "I3: verify must confirm exactly-one [$out]"
   # NEGATIVE CONTROL: a drop-in WITHOUT the reset line appends -> TWO values -> fail.
   cat >"$UD/$UNIT.d/interval.conf" <<'EOF'
 [Timer]
@@ -141,7 +148,7 @@ echo "== I4: snapshot-guard — reap without a snapshot is REFUSED; allowed afte
   # (a) reap WITHOUT snapshot -> refuse, unit still present.
   out="$(bash "$WI" reap-unit "$UNIT" 2>&1)"; rc=$?
   [ "$rc" -ne 0 ] || fail_msg "I4: reap without a snapshot must be REFUSED (rc=$rc)"
-  echo "$out" | grep -qi 'snapshot-guard' || fail_msg "I4: refusal must name the snapshot-guard [$out]"
+  echo "$out" | has_match -qi 'snapshot-guard' || fail_msg "I4: refusal must name the snapshot-guard [$out]"
   [ -f "$UD/$UNIT" ] || fail_msg "I4: a refused reap must NOT delete the unit"
   # (b) snapshot, then reap -> allowed, unit gone, snapshot retained.
   bash "$WI" snapshot-unit "$UNIT" >/dev/null 2>&1 || fail_msg "I4: snapshot-unit failed"
@@ -161,28 +168,28 @@ echo "== I5: fail-closed install-validate — unconfigured HMAC/alarm FAIL LOUD;
   export WAKE_HMAC_KEY_NAME="primary"
   out="$(bash "$WI" validate-hmac-key 2>&1)"; rc=$?
   [ "$rc" -ne 0 ] || fail_msg "I5: missing credential store must FAIL LOUD for the HMAC key (rc=$rc)"
-  echo "$out" | grep -qi 'UNSIGNED' || fail_msg "I5: HMAC failure must warn about unsigned wakes [$out]"
+  echo "$out" | has_match -qi 'UNSIGNED' || fail_msg "I5: HMAC failure must warn about unsigned wakes [$out]"
   # Now provide the key by-name -> pass, and the value must NEVER be echoed.
   jq -cn --arg k "$SECRET_KEY" '{wake:{hmac_keys:{"primary":$k}}}' >"$CRED"
   out2="$(bash "$WI" validate-hmac-key 2>&1)"; rc2=$?
   [ "$rc2" -eq 0 ] || fail_msg "I5: a by-name-resolvable HMAC key must pass (rc=$rc2) [$out2]"
-  echo "$out2" | grep -qF "$SECRET_KEY" && fail_msg "I5: validate must NEVER echo the HMAC key material"
+  echo "$out2" | has_match -qF "$SECRET_KEY" && fail_msg "I5: validate must NEVER echo the HMAC key material"
   # --- alarm target: unconfigured -> fail loud (silent no-alarm host).
   unset WAKE_ALARM_SINK_CMD
   out3="$(bash "$WI" validate-alarm-target 2>&1)"; rc3=$?
   [ "$rc3" -ne 0 ] || fail_msg "I5: unconfigured alarm target must FAIL LOUD (rc=$rc3)"
-  echo "$out3" | grep -qi 'silent no-alarm host' || fail_msg "I5: alarm failure must name the silent-no-alarm hazard [$out3]"
+  echo "$out3" | has_match -qi 'silent no-alarm host' || fail_msg "I5: alarm failure must name the silent-no-alarm hazard [$out3]"
   # unreachable -> fail loud.
   export WAKE_ALARM_SINK_CMD="false"
   out4="$(bash "$WI" validate-alarm-target 2>&1)"; rc4=$?
   [ "$rc4" -ne 0 ] || fail_msg "I5: unreachable alarm sink must FAIL LOUD (rc=$rc4)"
-  echo "$out4" | grep -qi 'UNREACHABLE' || fail_msg "I5: alarm failure must name the unreachable target [$out4]"
+  echo "$out4" | has_match -qi 'UNREACHABLE' || fail_msg "I5: alarm failure must name the unreachable target [$out4]"
   # reachable -> pass.
   export WAKE_ALARM_SINK_CMD="cat >/dev/null"
   bash "$WI" validate-alarm-target >/dev/null 2>&1 || fail_msg "I5: a configured+reachable alarm sink must pass"
   # The installer file must inline NO secret/endpoint.
-  grep -qF "$SECRET_ENDPOINT" "$WI" && fail_msg "I5: wake-install.sh must NOT inline any alarm endpoint"
-  grep -qE 'hmac_keys[^A-Za-z_].*=[^=].*[A-Za-z0-9]{8,}' "$WI" && fail_msg "I5: wake-install.sh must NOT inline key material"
+  has_match -qF "$SECRET_ENDPOINT" "$WI" && fail_msg "I5: wake-install.sh must NOT inline any alarm endpoint"
+  has_match -qE 'hmac_keys[^A-Za-z_].*=[^=].*[A-Za-z0-9]{8,}' "$WI" && fail_msg "I5: wake-install.sh must NOT inline key material"
   true
 ) && ok
 
@@ -204,7 +211,7 @@ echo "== I6: reset->verify->retire — overlap keeps legacy running; only §4-ve
   [ "$rc" -eq 0 ] || fail_msg "I6: overlap reset-verify must succeed (rc=$rc) [$out]"
   [ -f "$UD/$TIMER" ] || fail_msg "I6: overlap phase must LEAVE the legacy timer running (retire withheld)"
   [ -f "$SNAP/$TIMER" ] || fail_msg "I6: the legacy timer must be snapshotted before any retire"
-  echo "$out" | grep -qi 'LEFT RUNNING' || fail_msg "I6: overlap must announce retire is withheld [$out]"
+  echo "$out" | has_match -qi 'LEFT RUNNING' || fail_msg "I6: overlap must announce retire is withheld [$out]"
   # (b) §4-vector pass: retire LAST, snapshot-guarded (fallback proven live above).
   out2="$(bash "$WI" reset-verify-retire c --interval 30min --vector-passed 2>&1)"; rc2=$?
   [ "$rc2" -eq 0 ] || fail_msg "I6: vector-passed retire must succeed (rc=$rc2) [$out2]"
@@ -283,11 +290,11 @@ echo "== I9: dep-check — a host seed missing _lib/manifest.sh FAILS LOUD (name
   TGT="$(fresh i9-target)"
   out="$(WAKE_INSTALL_SOURCE="$FAKE" WAKE_INSTALL_TARGET="$TGT" bash "$WI_FAKE" install 2>&1)"; rc=$?
   [ "$rc" -ne 0 ] || fail_msg "I9: install MUST fail when _lib/manifest.sh is missing (rc=$rc)"
-  echo "$out" | grep -qi 'manifest.sh' || fail_msg "I9: the failure must NAME the missing library (manifest.sh) [$out]"
-  echo "$out" | grep -qiE 'REMEDY|mosaic update|re-seed|framework install' \
+  echo "$out" | has_match -qi 'manifest.sh' || fail_msg "I9: the failure must NAME the missing library (manifest.sh) [$out]"
+  echo "$out" | has_match -qiE 'REMEDY|mosaic update|re-seed|framework install' \
     || fail_msg "I9: the failure must give an actionable REMEDY, not just an error [$out]"
   # It must be a CLEAR fail-loud, NOT the obscure bare `source: No such file or directory`.
-  echo "$out" | grep -qi 'No such file or directory' \
+  echo "$out" | has_match -qi 'No such file or directory' \
     && fail_msg "I9: must not fail with a bare source error (obscure) [$out]"
   # Positive control: with the helper present (real framework root) install succeeds.
   TGT_OK="$(fresh i9-target-ok)"
@@ -313,10 +320,10 @@ echo "== I10: systemd search-path — install links mosaic-wake.service into the
   rm -f "$UD/mosaic-wake.service"
   out2="$(bash "$WI" validate-systemd-path 2>&1)"; rc2=$?
   [ "$rc2" -ne 0 ] || fail_msg "I10: validate must FAIL when the unit is not in the search path (rc=$rc2) [$out2]"
-  echo "$out2" | grep -qi 'search path' || fail_msg "I10: validate failure must name the search-path miss [$out2]"
+  echo "$out2" | has_match -qi 'search path' || fail_msg "I10: validate failure must name the search-path miss [$out2]"
   # (c) idempotent re-install: exactly one search-path entry, still resolvable.
   bash "$WI" install >/dev/null 2>&1 || fail_msg "I10: re-run install must succeed"
-  n="$(find "$UD" -maxdepth 1 -name 'mosaic-wake.service' | grep -c .)"
+  n="$(find "$UD" -maxdepth 1 -name 'mosaic-wake.service' | count_lines .)"
   [ "$n" -eq 1 ] || fail_msg "I10: re-install must not duplicate the search-path entry (found $n)"
   bash "$WI" validate-systemd-path >/dev/null 2>&1 || fail_msg "I10: re-install must keep the unit resolvable"
 ) && ok
@@ -334,12 +341,12 @@ echo "== I11: F7 — the legacy reap REFUSES unless the canon fallback wake is p
   #     it must REFUSE (schedulable floor not met).
   out0="$(bash "$WI" fallback-proven-live 2>&1)"; rc0=$?
   [ "$rc0" -ne 0 ] || fail_msg "I11: fallback-proven-live must FAIL when the fallback wake is not installed (rc=$rc0)"
-  echo "$out0" | grep -qi 'F7' || fail_msg "I11: the refusal must name the F7 precondition [$out0]"
+  echo "$out0" | has_match -qi 'F7' || fail_msg "I11: the refusal must name the F7 precondition [$out0]"
   # (b) NEGATIVE — vector-passed reap with NO live fallback must be REFUSED and the
   #     legacy timer LEFT RUNNING (never a coverage gap).
   out="$(bash "$WI" reset-verify-retire f --interval 30min --vector-passed 2>&1)"; rc=$?
   [ "$rc" -ne 0 ] || fail_msg "I11: reap must be REFUSED without a proven-live fallback (rc=$rc)"
-  echo "$out" | grep -qi 'FALLBACK WAKE is not proven live' || fail_msg "I11: refusal must name the un-proven fallback [$out]"
+  echo "$out" | has_match -qi 'FALLBACK WAKE is not proven live' || fail_msg "I11: refusal must name the un-proven fallback [$out]"
   [ -f "$UD/$TIMER" ] || fail_msg "I11: a refused reap must LEAVE the legacy timer running (F7 — no coverage gap)"
   # (c) POSITIVE — provision the fallback at the schedulable floor, then the reap
   #     proceeds (F7 satisfied) and the legacy timer is retired.
@@ -367,11 +374,11 @@ echo "== I12: fallback drain — a STALLED detector still gets delivery via the
   # even with no detector running — no starvation of the drain.
   out="$(bash "$DIGEST" render --from-store 2>/dev/null)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "I12: the canon fallback drain must exit 0 (rc=$rc)"
-  echo "$out" | grep -q 'STALLED-DRAIN-MARK' \
+  echo "$out" | has_match -q 'STALLED-DRAIN-MARK' \
     || fail_msg "I12: the fallback drain must DELIVER the pending obligation a stalled detector left (no delivery starvation) [$out]"
   # Bind the invariant to the SHIPPED unit: its ExecStart must be this canon drain.
   UNIT="$FRAMEWORK_ROOT/systemd/user/mosaic-wake-fallback.service"
-  grep -qE '^ExecStart=.*digest\.sh render --from-store' "$UNIT" \
+  has_match -qE '^ExecStart=.*digest\.sh render --from-store' "$UNIT" \
     || fail_msg "I12: mosaic-wake-fallback.service ExecStart must fire the canon drain (digest.sh render --from-store)"
 ) && ok
 
@@ -391,11 +398,11 @@ echo "== I13: install links + validates the canon fallback timer+service into th
   rm -f "$UD/mosaic-wake-fallback.timer"
   out="$(bash "$WI" validate-fallback-units 2>&1)"; rc=$?
   [ "$rc" -ne 0 ] || fail_msg "I13: validate must FAIL when a fallback unit is not in the search path (rc=$rc) [$out]"
-  echo "$out" | grep -qi 'search path' || fail_msg "I13: validate failure must name the search-path miss [$out]"
+  echo "$out" | has_match -qi 'search path' || fail_msg "I13: validate failure must name the search-path miss [$out]"
   # (c) idempotent re-install: exactly one entry per unit, still resolvable.
   bash "$WI" install >/dev/null 2>&1 || fail_msg "I13: re-run install must succeed"
-  nt="$(find "$UD" -maxdepth 1 -name 'mosaic-wake-fallback.timer' | grep -c .)"
-  ns="$(find "$UD" -maxdepth 1 -name 'mosaic-wake-fallback.service' | grep -c .)"
+  nt="$(find "$UD" -maxdepth 1 -name 'mosaic-wake-fallback.timer' | count_lines .)"
+  ns="$(find "$UD" -maxdepth 1 -name 'mosaic-wake-fallback.service' | count_lines .)"
   [ "$nt" -eq 1 ] && [ "$ns" -eq 1 ] || fail_msg "I13: re-install must not duplicate the fallback entries (timer=$nt service=$ns)"
   bash "$WI" validate-fallback-units >/dev/null 2>&1 || fail_msg "I13: re-install must keep the fallback units resolvable"
 ) && ok
@@ -407,17 +414,17 @@ echo "== I14: per-class fallback cadence — blank-reset yields EXACTLY ONE OnUn
   TIMER="mosaic-wake-fallback.timer"
   # The shipped timer carries the base OnUnitActiveSec placeholder (=1h).
   cp "$FRAMEWORK_ROOT/systemd/user/$TIMER" "$UD/$TIMER"
-  grep -q '^OnUnitActiveSec=1h' "$UD/$TIMER" || fail_msg "I14: shipped fallback timer must carry a base OnUnitActiveSec placeholder"
+  has_match -q '^OnUnitActiveSec=1h' "$UD/$TIMER" || fail_msg "I14: shipped fallback timer must carry a base OnUnitActiveSec placeholder"
   # write-fallback-cadence writes the per-class cadence in BLANK-RESET form.
   out="$(bash "$WI" write-fallback-cadence 30min 2>&1)"; rc=$?
   [ "$rc" -eq 0 ] || fail_msg "I14: write-fallback-cadence must succeed + verify single (rc=$rc) [$out]"
-  echo "$out" | grep -qi 'exactly one' || fail_msg "I14: the cadence write must confirm exactly-one OnUnitActiveUSec [$out]"
+  echo "$out" | has_match -qi 'exactly one' || fail_msg "I14: the cadence write must confirm exactly-one OnUnitActiveUSec [$out]"
   [ -f "$UD/$TIMER.d/cadence.conf" ] || fail_msg "I14: the per-class cadence drop-in must be written under <timer>.d/"
   # Assert the blank-reset FORM: an empty `OnUnitActiveSec=` reset line IMMEDIATELY
   # FOLLOWED by the new value. Portable across GNU and BusyBox grep (Alpine CI) —
   # `grep -z` (NUL-data) is a GNU-only extension BusyBox grep does NOT support, so
   # match the reset line and require the value on the very next line (-A1) instead.
-  grep -A1 '^OnUnitActiveSec=$' "$UD/$TIMER.d/cadence.conf" | grep -qx 'OnUnitActiveSec=30min' \
+  has_match -A1 '^OnUnitActiveSec=$' "$UD/$TIMER.d/cadence.conf" | has_match -qx 'OnUnitActiveSec=30min' \
     || fail_msg "I14: the drop-in must use the blank-reset form (empty reset line, then the value)"
   bash "$WI" verify-single "$TIMER" >/dev/null 2>&1 || fail_msg "I14: base(1h)+blank-reset(30min) must resolve exactly one OnUnitActiveUSec"
   # NEGATIVE CONTROL: a drop-in WITHOUT the reset line appends -> base 1h + 30min -> two -> fail.
@@ -428,7 +435,7 @@ echo "== I14: per-class fallback cadence — blank-reset yields EXACTLY ONE OnUn
 
 echo
 if [ -s "$FAILFILE" ]; then
-  echo "wake install harness: FAILED ($(grep -c . "$FAILFILE") assertion(s))" >&2
+  echo "wake install harness: FAILED ($(count_lines . "$FAILFILE") assertion(s))" >&2
   exit 1
 fi
 echo "wake install harness: all invariants passed ($pass groups)"

packages/mosaic/framework/tools/wake/test-wake-preimage.sh

@@ -0,0 +1,541 @@
+#!/usr/bin/env bash
+# test-wake-preimage.sh — RED-FIRST invariant harness for A11 (#958): durable
+# provenance for the OPERATOR-SIDE preimage definition (preimage.sh).
+#
+# Each test asserts ONE #958 invariant and is designed to go RED if it
+# regresses:
+#   P1  first-seen -> SILENT baseline (ledger rows, NO enqueue)   (detector idiom)
+#   P2  change -> attributable from durable state alone: new ledger row with
+#       prev, PRIOR BYTES retrievable content-addressed, first-class actionable
+#       enqueued with a §2.1 hard locator (path)                 (acceptance a+c)
+#   P3  detector ordering: the preimage cause line is enqueued at a LOWER
+#       observed_seq than the per-source delta it explains        (acceptance c)
+#   P4  credential-store PATH is refused — bytes NEVER captured, even when the
+#       operator lists it by error (hash/mtime row still written) (acceptance b)
+#   P5  secret-SHAPED content is refused — refusal, not redaction (acceptance b)
+#   P6  deletion of a preimage file is a tracked CHANGE (ABSENT), not an error
+#   P7  no-change is idempotent (no row growth, no enqueue)
+#   P8  unresolvable adapter command -> FAIL LOUD, never "no change" (D2/#955 class)
+#   P9  corrupt ledger -> REFUSE to compare/re-baseline (loud, no append)
+#   P10 oversized file -> bytes refused, hash still recorded (no data hoovering)
+#   P11 reconcile pre-step: a preimage change surfaces as a first-class line
+#       BEFORE the UNACCOUNTED enumerations it explains           (acceptance c)
+#   P12 detector: preimage infra failure is LOUD (pass exits non-zero) but does
+#       NOT starve source observation
+#
+# Regression needles from the #964 NOT-CLEAR review (decoy method: plant the
+# bytes, grep the WHOLE state dir — the decoy does not know what the code
+# believes):
+#   P13 case C: symlinked/renamed credential store (mosaic-home itself behind
+#       a symlink; a renamed target outside every path rule) — refused on BOTH
+#       path forms / by content, bytes grep-absent          (acceptance b)
+#   P14 case D: prefix-less high-entropy key (detector.env class) — safe
+#       WITHOUT opt-in by POLARITY alone (must hold with the shape list
+#       deleted), and refused WITH opt-in by the named-assignment shape
+#   P15 polarity: extras are RECORD-ONLY by default (change row + enqueue, no
+#       bytes); byte capture requires explicit WAKE_PREIMAGE_CAPTURE opt-in
+#   P16 case B11: ledger deleted while objects/ survives — LOUD refusal to
+#       re-baseline; the v2->v3 change is NOT absorbed as first-seen
+#   P17 allowlist symmetry: an allowlisted symlink whose TARGET is denied
+#       refuses (deny runs first, on both forms — precedence is not path
+#       agreement); a symlink to an ALLOWED target still captures (the fix
+#       must not close case C by breaking every symlinked path)
+#
+# Uses FAKE/STUB sources only (no live network). Isolated per test.
+# shellcheck disable=SC2030,SC2031
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# #973: three-valued grep assertion helpers (has_match/count_lines); init saves real stderr for abort loudness.
+# shellcheck disable=SC1091
+if ! . "$SCRIPT_DIR/_wake-common.sh"; then
+  echo "WAKE-ASSERT INIT ABORT: cannot source _wake-common.sh — suite ran ZERO wake assertions (#984)" >&2
+  exit 97
+fi
+wake_assert_init
+PRE="$SCRIPT_DIR/preimage.sh"
+STORE="$SCRIPT_DIR/store.sh"
+DET="$SCRIPT_DIR/detector.sh"
+RECON="$SCRIPT_DIR/reconcile.sh"
+
+command -v jq >/dev/null 2>&1 || {
+  echo "SKIP: jq not available" >&2
+  exit 0
+}
+
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMP_ROOT"' EXIT
+
+FAILFILE="$TMP_ROOT/failures"
+: >"$FAILFILE"
+pass=0
+fail_msg() {
+  echo "  FAIL: $*" >&2
+  echo "x" >>"$FAILFILE"
+}
+ok() { pass=$((pass + 1)); }
+
+fresh_state() {
+  local d="$TMP_ROOT/$1"
+  rm -rf "$d"
+  mkdir -p "$d"
+  printf '%s' "$d"
+}
+depth() { "$STORE" cursors | sed -n 's/pending_depth=//p'; }
+state_dir() { printf '%s/default' "$WAKE_STATE_HOME"; }
+ledger_rows() {
+  local f
+  f="$(state_dir)/preimage/preimage-ledger.jsonl"
+  [ -f "$f" ] && wc -l <"$f" | tr -d '[:space:]' || echo 0
+}
+
+# make_stub DIR — a source adapter reading $DIR/<kind>_<id> (same shape as the
+# reconcile harness stub).
+make_stub() {
+  local dir="$1"
+  cat >"$dir/adapter.sh" <<EOF
+#!/usr/bin/env bash
+set -u
+kind="\$1"; id="\$2"; base="$dir/\${kind}_\${id}"; rc=0
+[ -f "\$base.rc" ] && rc="\$(cat "\$base.rc")"
+[ -f "\$base" ] && cat "\$base"
+exit "\$rc"
+EOF
+  chmod +x "$dir/adapter.sh"
+}
+
+make_wl() { # make_wl FILE — one repo source r1
+  cat >"$1" <<'EOF'
+{ "schema_version": 1,
+  "repos": [ { "id": "r1" } ],
+  "watches": [ { "lane": "L", "sources": [ { "kind": "repo", "id": "r1" } ] } ] }
+EOF
+}
+
+echo "== P1: first-seen -> SILENT baseline (rows, no enqueue) =="
+(
+  WAKE_STATE_HOME="$(fresh_state p1)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p1fx"; mkdir -p "$fx"
+  make_stub "$fx"; make_wl "$fx/wl.json"
+  printf 'extra v1\n' >"$fx/extra.env"
+  export WAKE_DETECTOR_SOURCE_CMD="$fx/adapter.sh" WAKE_WATCH_LIST="$fx/wl.json" WAKE_PREIMAGE_EXTRA="$fx/extra.env"
+  out="$("$PRE" check --enqueue 2>&1)"; rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "P1: baseline check must exit 0 (rc=$rc) [$out]"
+  [ "$(ledger_rows)" -eq 3 ] || fail_msg "P1: expected 3 baseline rows (adapter, watch-list, extra), got $(ledger_rows)"
+  [ "$(depth)" = "0" ] || fail_msg "P1: first-seen must NOT enqueue (depth=$(depth))"
+) && ok
+
+echo "== P2: adapter change -> prior bytes + first-class hard-locator enqueue =="
+(
+  WAKE_STATE_HOME="$(fresh_state p2)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p2fx"; mkdir -p "$fx"
+  make_stub "$fx"; make_wl "$fx/wl.json"
+  # Acceptance (a) names the OPERATOR ADAPTER — a core member. Core members
+  # capture by default (they ARE the preimage definition); extras do not (P15).
+  export WAKE_DETECTOR_SOURCE_CMD="$fx/adapter.sh" WAKE_WATCH_LIST="$fx/wl.json"
+  unset WAKE_PREIMAGE_EXTRA WAKE_PREIMAGE_CAPTURE MOSAIC_HOME
+  "$PRE" check --enqueue >/dev/null 2>&1 || fail_msg "P2: baseline failed"
+  cp "$fx/adapter.sh" "$fx/adapter.v1"
+  old_sha="$(sha256sum "$fx/adapter.sh" | awk '{print $1}')"
+  printf '# adapter v2 CHANGED\n' >>"$fx/adapter.sh"
+  new_sha="$(sha256sum "$fx/adapter.sh" | awk '{print $1}')"
+  out="$("$PRE" check --enqueue 2>&1)"; rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "P2: change check must exit 0 (rc=$rc) [$out]"
+  sd="$(state_dir)"
+  row="$(jq -c --arg p "$(realpath "$fx/adapter.sh")" 'select(.path == $p)' "$sd/preimage/preimage-ledger.jsonl" | tail -n1)"
+  [ "$(jq -r '.prev // ""' <<<"$row")" = "$old_sha" ] || fail_msg "P2: new row must carry prev=<old sha> [$row]"
+  [ "$(jq -r '.sha256' <<<"$row")" = "$new_sha" ] || fail_msg "P2: new row sha mismatch [$row]"
+  # Acceptance (a): the PRIOR BYTES are retrievable from durable state alone.
+  cmp -s "$sd/preimage/objects/$old_sha" "$fx/adapter.v1" || fail_msg "P2: prior bytes missing or not byte-exact"
+  cmp -s "$sd/preimage/objects/$new_sha" "$fx/adapter.sh" || fail_msg "P2: current bytes object missing or mismatched"
+  # Acceptance (c): ONE first-class actionable with a §2.1 hard locator (path).
+  [ "$(depth)" = "1" ] || fail_msg "P2: exactly one enqueue expected (depth=$(depth))"
+  ent="$(tail -n1 "$sd/pending.jsonl")"
+  [ "$(jq -r '.class' <<<"$ent")" = "actionable" ] || fail_msg "P2: entry class must be actionable [$ent]"
+  [ "$(jq -r '.locators.kind' <<<"$ent")" = "preimage" ] || fail_msg "P2: locator kind must be preimage [$ent]"
+  [ -n "$(jq -r '.locators.path // ""' <<<"$ent")" ] || fail_msg "P2: locator must carry path (hard locator) [$ent]"
+  [ "$(jq -r '.locators.observed_hash' <<<"$ent")" = "$new_sha" ] || fail_msg "P2: locator observed_hash mismatch [$ent]"
+  [ "$(jq -r '.locators.prev_hash' <<<"$ent")" = "$old_sha" ] || fail_msg "P2: locator prev_hash mismatch [$ent]"
+) && ok
+
+echo "== P3: detector orders the cause line BEFORE the delta it explains =="
+(
+  WAKE_STATE_HOME="$(fresh_state p3)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p3fx"; mkdir -p "$fx"
+  make_stub "$fx"; make_wl "$fx/wl.json"
+  printf 'r1 state v1\n' >"$fx/repo_r1"
+  export WAKE_DETECTOR_SOURCE_CMD="$fx/adapter.sh" WAKE_WATCH_LIST="$fx/wl.json"
+  unset WAKE_PREIMAGE_EXTRA
+  "$DET" poll-once >/dev/null 2>&1 || fail_msg "P3: baseline poll failed"
+  [ "$(depth)" = "0" ] || fail_msg "P3: baseline poll must enqueue nothing (depth=$(depth))"
+  # Change the ADAPTER (preimage) and the source state in the same window.
+  printf '# comment: adapter changed\n' >>"$fx/adapter.sh"
+  printf 'r1 state v2\n' >"$fx/repo_r1"
+  "$DET" poll-once >/dev/null 2>&1 || fail_msg "P3: second poll failed"
+  sd="$(state_dir)"
+  pre_seq="$(jq -r 'select(.locators.kind == "preimage") | .observed_seq' "$sd/pending.jsonl" | head -n1)"
+  src_seq="$(jq -r 'select(.locators.kind == "repo") | .observed_seq' "$sd/pending.jsonl" | head -n1)"
+  [ -n "$pre_seq" ] || fail_msg "P3: no preimage cause entry enqueued"
+  [ -n "$src_seq" ] || fail_msg "P3: no source delta entry enqueued"
+  if [ -n "$pre_seq" ] && [ -n "$src_seq" ]; then
+    [ "$pre_seq" -lt "$src_seq" ] || fail_msg "P3: cause line must precede the delta (preimage seq=$pre_seq, source seq=$src_seq)"
+  fi
+) && ok
+
+echo "== P4: credential-store PATH refused — bytes never captured (acceptance b) =="
+(
+  WAKE_STATE_HOME="$(fresh_state p4)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p4fx"; mkdir -p "$fx"
+  export MOSAIC_HOME="$fx/mosaic-home"
+  mkdir -p "$MOSAIC_HOME"
+  secret='cred-value-P4-do-not-capture'
+  printf '{"svc":{"token":"%s"}}\n' "$secret" >"$MOSAIC_HOME/credentials.json"
+  # Operator error: the credential store listed as a preimage extra — AND
+  # explicitly opted in to capture. Deny must win over the opt-in (#964: a
+  # path both denied and allowlisted must refuse).
+  export WAKE_PREIMAGE_EXTRA="$MOSAIC_HOME/credentials.json"
+  export WAKE_PREIMAGE_CAPTURE="$MOSAIC_HOME/credentials.json"
+  unset WAKE_DETECTOR_SOURCE_CMD WAKE_WATCH_LIST
+  out="$("$PRE" check --enqueue 2>&1)"; rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "P4: refusal is not an infra failure (rc=$rc) [$out]"
+  sd="$(state_dir)"
+  row="$(tail -n1 "$sd/preimage/preimage-ledger.jsonl")"
+  [ "$(jq -r '.captured' <<<"$row")" = "false" ] || fail_msg "P4: row must record captured=false [$row]"
+  jq -r '.refused // ""' <<<"$row" | has_match -qi 'path' || fail_msg "P4: refusal must name the path deny [$row]"
+  # THE invariant: the secret bytes exist NOWHERE under the wake state dir.
+  if has_match -rq "$secret" "$sd" 2>/dev/null; then
+    fail_msg "P4: credential bytes leaked into the wake state dir"
+  fi
+) && ok
+
+echo "== P5: secret-SHAPED content refused (refusal, not redaction) =="
+(
+  WAKE_STATE_HOME="$(fresh_state p5)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p5fx"; mkdir -p "$fx"
+  tok='ghp_abcdefghijklmnop0123456789ABCDEF'
+  printf 'export MY_TOKEN=%s\n' "$tok" >"$fx/leaky.env"
+  # Opted in, so the CONTENT gate (not record-only polarity) is what refuses.
+  export WAKE_PREIMAGE_EXTRA="$fx/leaky.env" WAKE_PREIMAGE_CAPTURE="$fx/leaky.env"
+  unset WAKE_DETECTOR_SOURCE_CMD WAKE_WATCH_LIST MOSAIC_HOME
+  out="$("$PRE" check --enqueue 2>&1)"; rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "P5: refusal is not an infra failure (rc=$rc) [$out]"
+  sd="$(state_dir)"
+  row="$(tail -n1 "$sd/preimage/preimage-ledger.jsonl")"
+  [ "$(jq -r '.captured' <<<"$row")" = "false" ] || fail_msg "P5: row must record captured=false [$row]"
+  jq -r '.refused // ""' <<<"$row" | has_match -qi 'secret' || fail_msg "P5: refusal must name secret-shaped content [$row]"
+  if has_match -rq "$tok" "$sd" 2>/dev/null; then
+    fail_msg "P5: secret-shaped bytes leaked into the wake state dir"
+  fi
+) && ok
+
+echo "== P6: deletion is a tracked CHANGE (ABSENT), not an error =="
+(
+  WAKE_STATE_HOME="$(fresh_state p6)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p6fx"; mkdir -p "$fx"
+  printf 'to be deleted\n' >"$fx/gone.env"
+  export WAKE_PREIMAGE_EXTRA="$fx/gone.env"
+  unset WAKE_DETECTOR_SOURCE_CMD WAKE_WATCH_LIST MOSAIC_HOME
+  "$PRE" check --enqueue >/dev/null 2>&1 || fail_msg "P6: baseline failed"
+  rm -f "$fx/gone.env"
+  out="$("$PRE" check --enqueue 2>&1)"; rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "P6: deletion check must exit 0 (rc=$rc) [$out]"
+  sd="$(state_dir)"
+  row="$(tail -n1 "$sd/preimage/preimage-ledger.jsonl")"
+  [ "$(jq -r '.sha256' <<<"$row")" = "ABSENT" ] || fail_msg "P6: deletion must record sha256=ABSENT [$row]"
+  [ "$(depth)" = "1" ] || fail_msg "P6: deletion is a change and must enqueue (depth=$(depth))"
+) && ok
+
+echo "== P7: no-change is idempotent =="
+(
+  WAKE_STATE_HOME="$(fresh_state p7)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p7fx"; mkdir -p "$fx"
+  printf 'stable\n' >"$fx/stable.env"
+  export WAKE_PREIMAGE_EXTRA="$fx/stable.env"
+  unset WAKE_DETECTOR_SOURCE_CMD WAKE_WATCH_LIST MOSAIC_HOME
+  "$PRE" check --enqueue >/dev/null 2>&1 || fail_msg "P7: baseline failed"
+  r1="$(ledger_rows)"
+  "$PRE" check --enqueue >/dev/null 2>&1 || fail_msg "P7: second check failed"
+  [ "$(ledger_rows)" = "$r1" ] || fail_msg "P7: no-change must not append rows ($r1 -> $(ledger_rows))"
+  [ "$(depth)" = "0" ] || fail_msg "P7: no-change must not enqueue (depth=$(depth))"
+) && ok
+
+echo "== P8: unresolvable adapter -> FAIL LOUD, never 'no change' (D2 class) =="
+(
+  WAKE_STATE_HOME="$(fresh_state p8)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  export WAKE_DETECTOR_SOURCE_CMD="$TMP_ROOT/does-not-exist-adapter"
+  unset WAKE_WATCH_LIST WAKE_PREIMAGE_EXTRA MOSAIC_HOME
+  out="$("$PRE" check --enqueue 2>&1)"; rc=$?
+  [ "$rc" -ne 0 ] || fail_msg "P8: an unobservable preimage definition must FAIL LOUD (rc=0)"
+  echo "$out" | has_match -qi 'does not resolve' || fail_msg "P8: the failure must name the unresolvable adapter [$out]"
+) && ok
+
+echo "== P9: corrupt ledger -> REFUSE to compare/re-baseline =="
+(
+  WAKE_STATE_HOME="$(fresh_state p9)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p9fx"; mkdir -p "$fx"
+  printf 'v1\n' >"$fx/f.env"
+  export WAKE_PREIMAGE_EXTRA="$fx/f.env"
+  unset WAKE_DETECTOR_SOURCE_CMD WAKE_WATCH_LIST MOSAIC_HOME
+  "$PRE" check --enqueue >/dev/null 2>&1 || fail_msg "P9: baseline failed"
+  sd="$(state_dir)"
+  printf 'NOT-JSON-GARBAGE{{{\n' >>"$sd/preimage/preimage-ledger.jsonl"
+  r1="$(wc -l <"$sd/preimage/preimage-ledger.jsonl")"
+  printf 'v2 changed\n' >"$fx/f.env"
+  out="$("$PRE" check --enqueue 2>&1)"; rc=$?
+  [ "$rc" -ne 0 ] || fail_msg "P9: a corrupt ledger must FAIL LOUD (rc=0)"
+  echo "$out" | has_match -qi 'unparseable' || fail_msg "P9: the failure must name the corrupt ledger [$out]"
+  [ "$(wc -l <"$sd/preimage/preimage-ledger.jsonl")" = "$r1" ] || fail_msg "P9: nothing may be appended over corrupt history"
+) && ok
+
+echo "== P10: oversized file -> bytes refused, hash still recorded =="
+(
+  WAKE_STATE_HOME="$(fresh_state p10)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p10fx"; mkdir -p "$fx"
+  head -c 200 /dev/zero | tr '\0' 'A' >"$fx/big.bin"
+  # Opted in, so the SIZE gate (not record-only polarity) is what refuses.
+  export WAKE_PREIMAGE_EXTRA="$fx/big.bin" WAKE_PREIMAGE_MAX_BYTES=64
+  export WAKE_PREIMAGE_CAPTURE="$fx/big.bin"
+  unset WAKE_DETECTOR_SOURCE_CMD WAKE_WATCH_LIST MOSAIC_HOME
+  out="$("$PRE" check --enqueue 2>&1)"; rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "P10: size refusal is not an infra failure (rc=$rc) [$out]"
+  sd="$(state_dir)"
+  row="$(tail -n1 "$sd/preimage/preimage-ledger.jsonl")"
+  [ "$(jq -r '.captured' <<<"$row")" = "false" ] || fail_msg "P10: row must record captured=false [$row]"
+  jq -r '.refused // ""' <<<"$row" | has_match -qi 'MAX_BYTES' || fail_msg "P10: refusal must name the size cap [$row]"
+  sha="$(jq -r '.sha256' <<<"$row")"
+  [ "$sha" = "$(sha256sum "$fx/big.bin" | awk '{print $1}')" ] || fail_msg "P10: hash must still be recorded [$row]"
+  [ ! -f "$sd/preimage/objects/$sha" ] || fail_msg "P10: oversized bytes must NOT be stored"
+) && ok
+
+echo "== P11: reconcile surfaces the cause line before its enumerations =="
+(
+  WAKE_STATE_HOME="$(fresh_state p11)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p11fx"; mkdir -p "$fx"
+  make_stub "$fx"; make_wl "$fx/wl.json"
+  printf 'r1 state\n' >"$fx/repo_r1"
+  export WAKE_DETECTOR_SOURCE_CMD="$fx/adapter.sh" WAKE_WATCH_LIST="$fx/wl.json"
+  unset WAKE_PREIMAGE_EXTRA MOSAIC_HOME
+  # Baseline the preimage set, then change the adapter while "the detector is
+  # down" — the reconcile path must still produce the first-class cause line.
+  "$PRE" check >/dev/null 2>&1 || fail_msg "P11: preimage baseline failed"
+  printf '# adapter changed while detector down\n' >>"$fx/adapter.sh"
+  "$RECON" reconcile >/dev/null 2>&1 # rc 1 expected (unaccounted enumerated)
+  sd="$(state_dir)"
+  pre_seq="$(jq -r 'select(.locators.kind == "preimage") | .observed_seq' "$sd/pending.jsonl" | head -n1)"
+  enum_seq="$(jq -r 'select(.locators.reconciled == true) | .observed_seq' "$sd/pending.jsonl" | head -n1)"
+  [ -n "$pre_seq" ] || fail_msg "P11: reconcile must enqueue the preimage cause line"
+  [ -n "$enum_seq" ] || fail_msg "P11: reconcile must still enumerate the unaccounted source"
+  if [ -n "$pre_seq" ] && [ -n "$enum_seq" ]; then
+    [ "$pre_seq" -lt "$enum_seq" ] || fail_msg "P11: cause line must precede the enumeration (preimage seq=$pre_seq, enum seq=$enum_seq)"
+  fi
+) && ok
+
+echo "== P12: detector — preimage infra failure is LOUD but does not starve observation =="
+(
+  WAKE_STATE_HOME="$(fresh_state p12)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p12fx"; mkdir -p "$fx"
+  make_stub "$fx"; make_wl "$fx/wl.json"
+  printf 'r1 state\n' >"$fx/repo_r1"
+  export WAKE_DETECTOR_SOURCE_CMD="$fx/adapter.sh" WAKE_WATCH_LIST="$fx/wl.json"
+  unset WAKE_PREIMAGE_EXTRA MOSAIC_HOME
+  # Corrupt the ledger BEFORE the first poll: the preimage check fails loud,
+  # but the poll must still observe + baseline the source.
+  sd="$(state_dir)"
+  mkdir -p "$sd/preimage"
+  printf 'NOT-JSON-GARBAGE{{{\n' >"$sd/preimage/preimage-ledger.jsonl"
+  out="$("$DET" poll-once 2>&1)"; rc=$?
+  [ "$rc" -ne 0 ] || fail_msg "P12: the pass must exit non-zero on preimage infra failure"
+  echo "$out" | has_match -qi 'preimage' || fail_msg "P12: the failure must name the preimage check [$out]"
+  n="$(find "$sd/detector" -name 'watch-*.hash' 2>/dev/null | wc -l | tr -d '[:space:]')"
+  [ "$n" -ge 1 ] || fail_msg "P12: source observation must still proceed (no watch hash baselined)"
+) && ok
+
+echo "== P13: symlinked/renamed credential store refused on BOTH path forms (#964 C) =="
+(
+  WAKE_STATE_HOME="$(fresh_state p13)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p13fx"; mkdir -p "$fx"
+  # The mosaic home is ITSELF behind a symlink: a deny list written in
+  # unresolved paths cannot match a candidate that was realpath'd before the
+  # deny saw it — unless the anchors are resolved too.
+  mkdir -p "$fx/real-store/credentials"
+  ln -s "$fx/real-store" "$fx/mh"
+  export MOSAIC_HOME="$fx/mh"
+  s1='decoy-P13a-renamed-target-under-store'
+  printf 'x_token=%s\n' "$s1" >"$fx/mh/credentials/brain-creds.json"
+  # And a renamed target OUTSIDE every known store location, reached via a
+  # benign-looking symlink: no path rule can name it — the content gate must
+  # hold on the resolved file.
+  s2='0123456789abcdef0123456789abcdefP13b'
+  printf 'service_hmac_key=%s\n' "$s2" >"$fx/renamed-anywhere.cfg"
+  ln -s "$fx/renamed-anywhere.cfg" "$fx/link-b.env"
+  export WAKE_PREIMAGE_EXTRA="$fx/mh/credentials/brain-creds.json:$fx/link-b.env"
+  # Explicit opt-in for BOTH: deny must win over the allowlist.
+  export WAKE_PREIMAGE_CAPTURE="$fx/mh/credentials/brain-creds.json:$fx/link-b.env"
+  unset WAKE_DETECTOR_SOURCE_CMD WAKE_WATCH_LIST
+  out="$("$PRE" check --enqueue 2>&1)"; rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "P13: refusal is not an infra failure (rc=$rc) [$out]"
+  sd="$(state_dir)"
+  n="$(jq -r 'select(.captured == false) | .path' "$sd/preimage/preimage-ledger.jsonl" | wc -l | tr -d '[:space:]')"
+  [ "$n" = "2" ] || fail_msg "P13: both decoys must record captured=false (got $n)"
+  # THE invariant (decoy method): the planted bytes exist NOWHERE in state.
+  if has_match -rq "$s1" "$sd" 2>/dev/null; then
+    fail_msg "P13: renamed-target store bytes leaked into the wake state dir"
+  fi
+  if has_match -rq "$s2" "$sd" 2>/dev/null; then
+    fail_msg "P13: prefix-less key bytes leaked into the wake state dir"
+  fi
+) && ok
+
+echo "== P14: detector.env-class key — safe WITHOUT opt-in by polarity, refused WITH opt-in by shape (#964 D) =="
+(
+  WAKE_STATE_HOME="$(fresh_state p14)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p14fx"; mkdir -p "$fx"
+  hm='9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c'
+  printf 'WAKE_HMAC_KEY=%s\n' "$hm" >"$fx/detector.env"
+  export WAKE_PREIMAGE_EXTRA="$fx/detector.env"
+  unset WAKE_DETECTOR_SOURCE_CMD WAKE_WATCH_LIST MOSAIC_HOME WAKE_PREIMAGE_CAPTURE
+  # (a) NO opt-in: polarity alone keeps the bytes out. This leg must hold even
+  # with the content shape list deleted — the shape is defense-in-depth for
+  # the opt-in path, never the thing that makes case D read safe.
+  out="$("$PRE" check --enqueue 2>&1)"; rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "P14a: record-only tracking must succeed (rc=$rc) [$out]"
+  sd="$(state_dir)"
+  row="$(tail -n1 "$sd/preimage/preimage-ledger.jsonl")"
+  [ "$(jq -r '.captured' <<<"$row")" = "false" ] || fail_msg "P14a: extra must be record-only without opt-in [$row]"
+  if has_match -rq "$hm" "$sd" 2>/dev/null; then
+    fail_msg "P14a: key bytes leaked without any opt-in"
+  fi
+  # (b) The operator opts the env file in (the exact error the old usage text
+  # invited): the named-assignment shape must still refuse the bytes.
+  export WAKE_PREIMAGE_CAPTURE="$fx/detector.env"
+  printf 'WAKE_HMAC_KEY=%s\nrotated=1\n' "$hm" >"$fx/detector.env"
+  out="$("$PRE" check --enqueue 2>&1)"; rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "P14b: refusal is not an infra failure (rc=$rc) [$out]"
+  row="$(tail -n1 "$sd/preimage/preimage-ledger.jsonl")"
+  [ "$(jq -r '.captured' <<<"$row")" = "false" ] || fail_msg "P14b: opted-in key material must still refuse [$row]"
+  jq -r '.refused // ""' <<<"$row" | has_match -qi 'secret' || fail_msg "P14b: refusal must name secret-shaped content [$row]"
+  if has_match -rq "$hm" "$sd" 2>/dev/null; then
+    fail_msg "P14b: key bytes leaked despite refusal"
+  fi
+) && ok
+
+echo "== P15: extras are RECORD-ONLY by default; capture requires explicit opt-in =="
+(
+  WAKE_STATE_HOME="$(fresh_state p15)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p15fx"; mkdir -p "$fx"
+  printf 'plain v1\n' >"$fx/notes.cfg"
+  export WAKE_PREIMAGE_EXTRA="$fx/notes.cfg"
+  unset WAKE_DETECTOR_SOURCE_CMD WAKE_WATCH_LIST MOSAIC_HOME WAKE_PREIMAGE_CAPTURE
+  "$PRE" check --enqueue >/dev/null 2>&1 || fail_msg "P15: baseline failed"
+  printf 'plain v2\n' >"$fx/notes.cfg"
+  sha2="$(sha256sum "$fx/notes.cfg" | awk '{print $1}')"
+  "$PRE" check --enqueue >/dev/null 2>&1 || fail_msg "P15: change check failed"
+  sd="$(state_dir)"
+  row="$(tail -n1 "$sd/preimage/preimage-ledger.jsonl")"
+  [ "$(jq -r '.captured' <<<"$row")" = "false" ] || fail_msg "P15: default must be record-only [$row]"
+  [ ! -f "$sd/preimage/objects/$sha2" ] || fail_msg "P15: bytes captured without opt-in"
+  [ "$(depth)" = "1" ] || fail_msg "P15: record-only must still track the change (depth=$(depth))"
+  # Opt in -> the next change captures.
+  export WAKE_PREIMAGE_CAPTURE="$fx/notes.cfg"
+  printf 'plain v3\n' >"$fx/notes.cfg"
+  sha3="$(sha256sum "$fx/notes.cfg" | awk '{print $1}')"
+  "$PRE" check --enqueue >/dev/null 2>&1 || fail_msg "P15: opted-in change check failed"
+  row="$(tail -n1 "$sd/preimage/preimage-ledger.jsonl")"
+  [ "$(jq -r '.captured' <<<"$row")" = "true" ] || fail_msg "P15: opt-in must capture [$row]"
+  cmp -s "$sd/preimage/objects/$sha3" "$fx/notes.cfg" || fail_msg "P15: opted-in bytes missing or mismatched"
+) && ok
+
+echo "== P16: deleted ledger over surviving objects/ — REFUSE to re-baseline (#964 B11) =="
+(
+  WAKE_STATE_HOME="$(fresh_state p16)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p16fx"; mkdir -p "$fx"
+  make_stub "$fx"
+  export WAKE_DETECTOR_SOURCE_CMD="$fx/adapter.sh"
+  unset WAKE_WATCH_LIST WAKE_PREIMAGE_EXTRA WAKE_PREIMAGE_CAPTURE MOSAIC_HOME
+  "$PRE" check >/dev/null 2>&1 || fail_msg "P16: v1 baseline failed"
+  printf '# v2\n' >>"$fx/adapter.sh"
+  "$PRE" check >/dev/null 2>&1 || fail_msg "P16: v2 change failed"
+  sd="$(state_dir)"
+  nobj="$(ls "$sd/preimage/objects" | wc -l | tr -d '[:space:]')"
+  # Delete the ledger; objects/ survives. ABSENT is not CORRUPT — and it is
+  # not a first install either: that asymmetry is locally detectable.
+  rm -f "$sd/preimage/preimage-ledger.jsonl"
+  printf '# v3\n' >>"$fx/adapter.sh"
+  out="$("$PRE" check --enqueue 2>&1)"; rc=$?
+  [ "$rc" -ne 0 ] || fail_msg "P16: absent ledger over prior objects must FAIL LOUD (rc=0) [$out]"
+  echo "$out" | has_match -qi 'REFUSING to re-baseline' || fail_msg "P16: the failure must name the refusal [$out]"
+  [ ! -e "$sd/preimage/preimage-ledger.jsonl" ] || fail_msg "P16: the ledger must NOT be silently recreated over deleted history"
+  [ "$(ls "$sd/preimage/objects" | wc -l | tr -d '[:space:]')" = "$nobj" ] || fail_msg "P16: prior objects must remain untouched"
+  [ "$(depth)" = "0" ] || fail_msg "P16: the v2->v3 change must NOT be absorbed or enqueued from an unverifiable baseline (depth=$(depth))"
+) && ok
+
+echo "== P17: allowlist symmetry — symlink to a DENIED target refuses; symlink to an allowed target captures =="
+(
+  WAKE_STATE_HOME="$(fresh_state p17)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  fx="$TMP_ROOT/p17fx"; mkdir -p "$fx"
+  export MOSAIC_HOME="$fx/mh"
+  mkdir -p "$MOSAIC_HOME"
+  s='decoy-P17-cred-behind-benign-alias'
+  printf '{"svc":{"token":"%s"}}\n' "$s" >"$MOSAIC_HOME/credentials.json"
+  # A benign-looking alias whose TARGET is denied: the allowlist matches the
+  # alias string, but deny runs FIRST and on BOTH forms — "deny wins over
+  # opt-in" is a precedence rule, path agreement is what makes it hold.
+  ln -s "$MOSAIC_HOME/credentials.json" "$fx/settings.json"
+  # And a symlink to an ALLOWED target: the fix must not close case C by
+  # breaking every symlinked path outright.
+  printf 'benign payload v1\n' >"$fx/target.cfg"
+  ln -s "$fx/target.cfg" "$fx/alias.cfg"
+  export WAKE_PREIMAGE_EXTRA="$fx/settings.json:$fx/alias.cfg"
+  export WAKE_PREIMAGE_CAPTURE="$fx/settings.json:$fx/alias.cfg"
+  unset WAKE_DETECTOR_SOURCE_CMD WAKE_WATCH_LIST
+  out="$("$PRE" check --enqueue 2>&1)"; rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "P17: check must exit 0 (rc=$rc) [$out]"
+  sd="$(state_dir)"
+  crow="$(jq -c --arg p "$(realpath "$fx/settings.json")" 'select(.path == $p)' "$sd/preimage/preimage-ledger.jsonl" | tail -n1)"
+  [ "$(jq -r '.captured' <<<"$crow")" = "false" ] || fail_msg "P17: allowlisted symlink to a denied target must refuse [$crow]"
+  if has_match -rq "$s" "$sd" 2>/dev/null; then
+    fail_msg "P17: credential bytes leaked via an allowlisted alias"
+  fi
+  brow="$(jq -c --arg p "$(realpath "$fx/alias.cfg")" 'select(.path == $p)' "$sd/preimage/preimage-ledger.jsonl" | tail -n1)"
+  [ "$(jq -r '.captured' <<<"$brow")" = "true" ] || fail_msg "P17: symlink to an allowed target must still capture [$brow]"
+) && ok
+
+echo
+total=$((pass + $(wc -l <"$FAILFILE")))
+echo "== test-wake-preimage: $pass/$total passed =="
+[ -s "$FAILFILE" ] && exit 1
+exit 0

packages/mosaic/framework/tools/wake/test-wake-reconcile.sh

@@ -29,6 +29,13 @@
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# #973: three-valued grep assertion helpers (has_match/count_lines); init saves real stderr for abort loudness.
+# shellcheck disable=SC1091
+if ! . "$SCRIPT_DIR/_wake-common.sh"; then
+  echo "WAKE-ASSERT INIT ABORT: cannot source _wake-common.sh — suite ran ZERO wake assertions (#984)" >&2
+  exit 97
+fi
+wake_assert_init
 RECON="$SCRIPT_DIR/reconcile.sh"
 STORE="$SCRIPT_DIR/store.sh"
 DET="$SCRIPT_DIR/detector.sh"
@@ -87,7 +94,7 @@ EOF
   out="$("$RECON" inventory 2>&1)"
   rc=$?
   [ "$rc" -eq 0 ] || fail_msg "R1: a complete inventory must PASS (exit 0) [$out]"
-  echo "$out" | grep -qi 'COMPLETE' || fail_msg "R1: a complete inventory must report COMPLETE [$out]"
+  echo "$out" | has_match -qi 'COMPLETE' || fail_msg "R1: a complete inventory must report COMPLETE [$out]"
 ) && ok
 
 echo "== R2: OMITTED source -> FLAG (vacuous-pass prevented, not silently green) =="
@@ -106,8 +113,8 @@ EOF
   out="$("$RECON" inventory 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "R2: an omitted (declared-but-unwatched) source must FLAG (non-zero), not silently pass"
-  echo "$out" | grep -qi 'r2' || fail_msg "R2: the flag must name the omitted source r2 [$out]"
-  echo "$out" | grep -qi 'vacuous' || fail_msg "R2: the flag must state the vacuous-pass is prevented [$out]"
+  echo "$out" | has_match -qi 'r2' || fail_msg "R2: the flag must name the omitted source r2 [$out]"
+  echo "$out" | has_match -qi 'vacuous' || fail_msg "R2: the flag must state the vacuous-pass is prevented [$out]"
 ) && ok
 
 echo "== R3: required_sources omission -> FLAG =="
@@ -126,7 +133,7 @@ EOF
   out="$("$RECON" inventory 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "R3: a required_sources omission must FLAG (non-zero)"
-  echo "$out" | grep -qi "requires source 'r2'" || fail_msg "R3: the flag must name the required-but-omitted source r2 [$out]"
+  echo "$out" | has_match -qi "requires source 'r2'" || fail_msg "R3: the flag must name the required-but-omitted source r2 [$out]"
 ) && ok
 
 echo "== R4: dangling watch reference -> FLAG =="
@@ -144,7 +151,7 @@ EOF
   out="$("$RECON" inventory 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "R4: a dangling reference must FLAG (non-zero)"
-  echo "$out" | grep -qi 'dangling' || fail_msg "R4: the flag must state it is dangling [$out]"
+  echo "$out" | has_match -qi 'dangling' || fail_msg "R4: the flag must state it is dangling [$out]"
 ) && ok
 
 echo "== R5/R6: pre-existing state -> UNACCOUNTED flag + enumerated into store; re-run 0 =="
@@ -173,14 +180,14 @@ EOF
   out="$("$RECON" reconcile 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "R5: pre-existing unaccounted state must FLAG (non-zero) on first reconcile"
-  echo "$out" | grep -qi 'UNACCOUNTED=2' || fail_msg "R5: both pre-existing sources must be UNACCOUNTED [$out]"
+  echo "$out" | has_match -qi 'UNACCOUNTED=2' || fail_msg "R5: both pre-existing sources must be UNACCOUNTED [$out]"
   # R6: enumerated into the durable store — one entry per pre-existing source.
   [ "$(depth)" = "2" ] || fail_msg "R6: pre-existing state must be ENUMERATED into the store (depth 2), got $(depth)"
   # A follow-up reconcile now finds everything accounted -> 0 unaccounted.
   out2="$("$RECON" reconcile 2>&1)"
   rc2=$?
   [ "$rc2" -eq 0 ] || fail_msg "R6: a second reconcile must report 0 unaccounted (exit 0) [$out2]"
-  echo "$out2" | grep -qi 'UNACCOUNTED=0' || fail_msg "R6: second reconcile must be 0 unaccounted [$out2]"
+  echo "$out2" | has_match -qi 'UNACCOUNTED=0' || fail_msg "R6: second reconcile must be 0 unaccounted [$out2]"
   [ "$(depth)" = "2" ] || fail_msg "R6: a clean reconcile must NOT re-enumerate (depth still 2), got $(depth)"
 ) && ok
 
@@ -211,7 +218,7 @@ EOF
   out="$("$RECON" reconcile 2>&1)"
   rc=$?
   [ "$rc" -eq 0 ] || fail_msg "R7: state reflected in the inbox must be ACCOUNTED (exit 0) [$out]"
-  echo "$out" | grep -qi 'UNACCOUNTED=0' || fail_msg "R7: inbox-reflected state must be 0 unaccounted [$out]"
+  echo "$out" | has_match -qi 'UNACCOUNTED=0' || fail_msg "R7: inbox-reflected state must be 0 unaccounted [$out]"
   [ "$(depth)" = "1" ] || fail_msg "R7: reconciler must NOT double-enumerate inbox-reflected state (depth still 1), got $(depth)"
 ) && ok
 
@@ -236,7 +243,7 @@ EOF
   out="$("$RECON" reconcile 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "R8: a source error must FAIL LOUD (non-zero exit)"
-  echo "$out" | grep -qi 'FAIL LOUD' || fail_msg "R8: the source error must be loud [$out]"
+  echo "$out" | has_match -qi 'FAIL LOUD' || fail_msg "R8: the source error must be loud [$out]"
   [ "$(depth)" = "0" ] || fail_msg "R8: a failed observation must NOT enumerate anything, got depth $(depth)"
 ) && ok
 
@@ -278,7 +285,7 @@ EOF
   out="$("$RECON" reconcile 2>&1)"
   rc=$?
   [ "$rc" -ne 0 ] || fail_msg "R9: pre-existing beta is unaccounted on this pass -> must FLAG (non-zero) [$out]"
-  echo "$out" | grep -qi 'UNACCOUNTED=1' || fail_msg "R9: only beta should be unaccounted (alpha is inbox-accounted) [$out]"
+  echo "$out" | has_match -qi 'UNACCOUNTED=1' || fail_msg "R9: only beta should be unaccounted (alpha is inbox-accounted) [$out]"
   [ "$(depth)" = "2" ] || fail_msg "R9: reconciler must ENUMERATE beta into the co-fed store (depth 2), got $(depth)"
 
   # A further detector delta on beta must allocate 3 — the unified allocator
@@ -292,8 +299,8 @@ EOF
   # already used, so this set would contain a duplicate (alias).
   seqs="$("$STORE" drain | jq -r '.observed_seq' | sort -n | tr '\n' ' ')"
   [ "$seqs" = "1 2 3 " ] || fail_msg "R9: co-fed observed_seqs must be distinct+gapless '1 2 3', got '$seqs' (a duplicate = the aliasing #908 dissolved)"
-  ndistinct="$("$STORE" drain | jq -r '.observed_seq' | sort -nu | grep -c .)"
-  ntotal="$("$STORE" drain | jq -r '.observed_seq' | grep -c .)"
+  ndistinct="$("$STORE" drain | jq -r '.observed_seq' | sort -nu | count_lines .)"
+  ntotal="$("$STORE" drain | jq -r '.observed_seq' | count_lines .)"
   [ "$ndistinct" = "$ntotal" ] || fail_msg "R9: aliasing detected — $ntotal entries but only $ndistinct distinct observed_seq"
   # The contiguous-prefix CONSUMED contract holds over the co-fed seqs.
   "$STORE" consume --upto 3 >/dev/null 2>&1 || fail_msg "R9: CONSUMED 3 must succeed over the gapless co-fed prefix"
@@ -333,7 +340,7 @@ EOF
   out="$("$RECON" reconcile 2>&1)"
   rc=$?
   [ "$rc" -eq 0 ] || fail_msg "R10: a consumed state must be ACCOUNTED (exit 0, no spurious rc=1 CRITICAL) [$out]"
-  echo "$out" | grep -qi 'UNACCOUNTED=0' || fail_msg "R10: a consumed state must be 0 unaccounted (no re-enumeration) [$out]"
+  echo "$out" | has_match -qi 'UNACCOUNTED=0' || fail_msg "R10: a consumed state must be 0 unaccounted (no re-enumeration) [$out]"
   [ "$(depth)" = "0" ] || fail_msg "R10: reconciler must NOT re-enumerate a consumed state (depth still 0 = no duplicate wake), got $(depth)"
 ) && ok
 
@@ -372,7 +379,7 @@ EOF
   [ "$rc" -ne 0 ] || fail_msg "R11: a genuine gap (r2) must still FLAG (non-zero) [$out]"
   # After #932: ONLY r2 is unaccounted (r1 suppressed by the store record). On
   # BASE both r1 and r2 re-enumerate (UNACCOUNTED=2) -> this assertion is red-first.
-  echo "$out" | grep -qi 'UNACCOUNTED=1' || fail_msg "R11: exactly ONE source (the gap r2) must be unaccounted; the consumed r1 must be suppressed [$out]"
+  echo "$out" | has_match -qi 'UNACCOUNTED=1' || fail_msg "R11: exactly ONE source (the gap r2) must be unaccounted; the consumed r1 must be suppressed [$out]"
   # Prove precisely WHICH state re-enumerated: the gap r2 IS enumerated, the
   # consumed r1 is NOT. (base re-enumerates r1 too -> the r1-absent assertion is
   # red-first; the r2-present assertion holds both before and after = no over-suppression.)
@@ -383,7 +390,7 @@ EOF
 
 echo
 if [ -s "$FAILFILE" ]; then
-  echo "wake reconcile harness: FAILED ($(grep -c . "$FAILFILE") assertion(s))" >&2
+  echo "wake reconcile harness: FAILED ($(count_lines . "$FAILFILE") assertion(s))" >&2
   exit 1
 fi
 echo "wake reconcile harness: all invariants passed ($pass groups)"

packages/mosaic/framework/tools/wake/test-wake-store-ack.sh

@@ -19,11 +19,36 @@
 #   T10 concurrency: two concurrent enqueues get DISTINCT seqs (lock)  (#908)
 #   T12 consume records the last-consumed observed_hash per (kind,id) into the
 #      store-owned record (additive; monotonic last-seq wins; lazily created) (#932)
+#   T13 #946 quarantine CLAMP: ordinary consume (store + ack wrapper) REFUSES to
+#      advance past a quarantined seq; the refusal names the seq + the force flag
+#   T14 #946 forced step-over: --force-past-quarantine advances LOUDLY, prunes the
+#      set, and NEVER fabricates a consumed-hash row for the quarantined entry
+#   T15 #946 quarantine-sync: full REPLACE semantics (sorted/deduped; empty input
+#      CLEARS — the clamp self-heals once the gate is fixed; invalid input refused)
+#   T16 #946 quarantine-audit: consumed-hashes rows provably false against the
+#      dead-letter ledger are reported (exit 1) and removed only under --repair;
+#      healed rows and the ledger itself are untouched
+#   T17 #952 quarantine-audit clean sweep names BOTH unprovable residual
+#      classes: evidence pruned (no evidence) AND evidence surviving with an
+#      empty observed_hash (evidence unusable). Fixture is the VERBATIM live
+#      specimen (mos-dt lane dead-letter seq 13, bench/malformed-locator-test)
+#      — a nested .locators.* row with NO observed_hash key. Do NOT hand-build
+#      a FLAT dead-letter fixture here: consumed-hashes rows are genuinely
+#      flat, dead-letter rows are genuinely nested, and a flat fixture makes
+#      the audit's CORRECT non-conviction look exactly like the defect under
+#      hunt (this false-defect near-miss actually happened in the #951 review)
 #
 # Isolated: every test runs against a fresh WAKE_STATE_HOME temp dir.
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# #973: three-valued grep assertion helpers (has_match/count_lines); init saves real stderr for abort loudness.
+# shellcheck disable=SC1091
+if ! . "$SCRIPT_DIR/_wake-common.sh"; then
+  echo "WAKE-ASSERT INIT ABORT: cannot source _wake-common.sh — suite ran ZERO wake assertions (#984)" >&2
+  exit 97
+fi
+wake_assert_init
 STORE="$SCRIPT_DIR/store.sh"
 ACK="$SCRIPT_DIR/ack.sh"
 
@@ -78,14 +103,14 @@ echo "== T1: three-cursor advancement =="
   "$STORE" enqueue --seq 1 --class actionable --locators '{"repo":"r","issue":1}' >/dev/null
   "$STORE" enqueue --seq 2 --class actionable --locators '{"repo":"r","issue":2}' >/dev/null
   cur="$("$STORE" cursors)"
-  echo "$cur" | grep -q 'observed_seq=2' || fail_msg "T1: observed_seq should be 2 after enqueue 1,2 [$cur]"
-  echo "$cur" | grep -q 'consumed_seq=0' || fail_msg "T1: consumed_seq must NOT advance on enqueue (only on CONSUMED ack) [$cur]"
-  echo "$cur" | grep -q 'pending_depth=2' || fail_msg "T1: pending depth should be 2 [$cur]"
+  echo "$cur" | has_match -q 'observed_seq=2' || fail_msg "T1: observed_seq should be 2 after enqueue 1,2 [$cur]"
+  echo "$cur" | has_match -q 'consumed_seq=0' || fail_msg "T1: consumed_seq must NOT advance on enqueue (only on CONSUMED ack) [$cur]"
+  echo "$cur" | has_match -q 'pending_depth=2' || fail_msg "T1: pending depth should be 2 [$cur]"
   # consumed_seq advances only on CONSUMED.
   "$STORE" consume --upto 2 >/dev/null
   cur="$("$STORE" cursors)"
-  echo "$cur" | grep -q 'consumed_seq=2' || fail_msg "T1: consumed_seq should be 2 after CONSUMED 2 [$cur]"
-  echo "$cur" | grep -q 'pending_depth=0' || fail_msg "T1: pending drained after CONSUMED [$cur]"
+  echo "$cur" | has_match -q 'consumed_seq=2' || fail_msg "T1: consumed_seq should be 2 after CONSUMED 2 [$cur]"
+  echo "$cur" | has_match -q 'pending_depth=0' || fail_msg "T1: pending drained after CONSUMED [$cur]"
 ) && ok
 
 echo "== T2: digest coalesce-REPLACE vs actionable APPEND =="
@@ -98,16 +123,16 @@ echo "== T2: digest coalesce-REPLACE vs actionable APPEND =="
   "$STORE" enqueue --seq 3 --class digest --locators '{"head":"bbb"}' >/dev/null
   "$STORE" enqueue --seq 4 --class human --locators '{"from":"peer"}' >/dev/null
   out="$("$STORE" drain)"
-  ndigest="$(printf '%s\n' "$out" | jq -c 'select(.class=="digest")' | grep -c . || true)"
+  ndigest="$(printf '%s\n' "$out" | jq -c 'select(.class=="digest")' | count_lines . || true)"
   [ "$ndigest" = "1" ] || fail_msg "T2: digest must COALESCE to a single pending entry, got $ndigest"
   head="$(printf '%s\n' "$out" | jq -r 'select(.class=="digest") | .locators.head')"
   [ "$head" = "bbb" ] || fail_msg "T2: newest digest must REPLACE prior (expected bbb, got $head)"
-  nactionable="$(printf '%s\n' "$out" | jq -c 'select(.class=="actionable")' | grep -c . || true)"
-  nhuman="$(printf '%s\n' "$out" | jq -c 'select(.class=="human")' | grep -c . || true)"
+  nactionable="$(printf '%s\n' "$out" | jq -c 'select(.class=="actionable")' | count_lines . || true)"
+  nhuman="$(printf '%s\n' "$out" | jq -c 'select(.class=="human")' | count_lines . || true)"
   [ "$nactionable" = "1" ] || fail_msg "T2: actionable must APPEND (never replaced), got $nactionable"
   [ "$nhuman" = "1" ] || fail_msg "T2: human must APPEND / stay durable, got $nhuman"
   # Durability never bypassed: all classes present in the durable store.
-  total="$(printf '%s\n' "$out" | grep -c . || true)"
+  total="$(printf '%s\n' "$out" | count_lines . || true)"
   [ "$total" = "3" ] || fail_msg "T2: durable store should hold digest+actionable+human = 3, got $total"
 ) && ok
 
@@ -123,7 +148,7 @@ echo "== T3: contiguous-prefix CONSUMED (reject ack N while N-1 unconsumed) =="
     fail_msg "T3: CONSUMED 3 must be REJECTED while seq 2 is a gap (unconsumed)"
   fi
   cur="$("$STORE" cursors)"
-  echo "$cur" | grep -q 'consumed_seq=0' || fail_msg "T3: rejected CONSUMED must NOT advance the cursor [$cur]"
+  echo "$cur" | has_match -q 'consumed_seq=0' || fail_msg "T3: rejected CONSUMED must NOT advance the cursor [$cur]"
   # Also reject via the ack wrapper.
   if "$ACK" consumed --upto 3 --no-sync >/dev/null 2>&1; then
     fail_msg "T3: ack.sh CONSUMED 3 must be REJECTED over a gap"
@@ -132,11 +157,11 @@ echo "== T3: contiguous-prefix CONSUMED (reject ack N while N-1 unconsumed) =="
   "$STORE" enqueue --seq 2 --class actionable --locators '{}' >/dev/null
   "$ACK" consumed --upto 3 --no-sync >/dev/null 2>&1 || fail_msg "T3: CONSUMED 3 should succeed once gap at 2 is filled"
   cur="$("$STORE" cursors)"
-  echo "$cur" | grep -q 'consumed_seq=3' || fail_msg "T3: consumed_seq should be 3 after contiguous prefix filled [$cur]"
+  echo "$cur" | has_match -q 'consumed_seq=3' || fail_msg "T3: consumed_seq should be 3 after contiguous prefix filled [$cur]"
   # Cumulative + can't regress: CONSUMED 2 after 3 is an idempotent no-op.
   "$ACK" consumed --upto 2 --no-sync >/dev/null 2>&1 || fail_msg "T3: cumulative CONSUMED 2 (<=3) should be an idempotent success"
   cur="$("$STORE" cursors)"
-  echo "$cur" | grep -q 'consumed_seq=3' || fail_msg "T3: cursor must not regress below 3 [$cur]"
+  echo "$cur" | has_match -q 'consumed_seq=3' || fail_msg "T3: cursor must not regress below 3 [$cur]"
 ) && ok
 
 echo "== T4: wake_id DELIVERY-dedup (dup delivery = re-RECEIVE, never re-action) =="
@@ -151,7 +176,7 @@ echo "== T4: wake_id DELIVERY-dedup (dup delivery = re-RECEIVE, never re-action)
   [ "$r2" = "DUP" ] || fail_msg "T4: duplicate delivery of same wake_id should be DUP (re-RECEIVE), got '$r2'"
   # RECEIVED (delivery) must NEVER advance consumed_seq (delivery != consumption).
   cur="$("$STORE" cursors)"
-  echo "$cur" | grep -q 'consumed_seq=0' || fail_msg "T4: RECEIVED must not advance consumed_seq [$cur]"
+  echo "$cur" | has_match -q 'consumed_seq=0' || fail_msg "T4: RECEIVED must not advance consumed_seq [$cur]"
 ) && ok
 
 echo "== T5: atomic write-tmp+rename survives crash mid-write =="
@@ -171,7 +196,7 @@ echo "== T5: atomic write-tmp+rename survives crash mid-write =="
   drained="$("$STORE" drain)"
   printf '%s\n' "$drained" | jq -e . >/dev/null 2>&1 || fail_msg "T5: drain returned non-JSON — garbage temp corrupted the store"
   printf '%s\n' "$drained" | stream_any '.observed_seq==1' || fail_msg "T5: committed entry (seq 1) lost after simulated crash"
-  printf '%s\n' "$drained" | grep -q 999 && fail_msg "T5: uncommitted garbage (seq 999) leaked into the live store"
+  printf '%s\n' "$drained" | has_match -q 999 && fail_msg "T5: uncommitted garbage (seq 999) leaked into the live store"
   # A subsequent real mutation must succeed DESPITE the stale temp present.
   "$STORE" enqueue --seq 2 --class actionable --locators '{"issue":2}' >/dev/null || fail_msg "T5: enqueue after crash temp failed"
   # #927: the enqueue HOT PATH must NOT reap tmp files — an unconditional delete
@@ -180,7 +205,7 @@ echo "== T5: atomic write-tmp+rename survives crash mid-write =="
   # untouched by an enqueue; reaping it on the hot path is exactly the bug.
   [ -e "$STATE_DIR/.wake.tmp.crash12" ] || fail_msg "T5: the enqueue hot path must NOT delete tmp files off its own write (that hot-path reap was the #927 clobber)"
   d2="$("$STORE" drain)"
-  [ "$(printf '%s\n' "$d2" | grep -c .)" = "2" ] || fail_msg "T5: store not healthy after crash+recovery (expected 2 entries)"
+  [ "$(printf '%s\n' "$d2" | has_match -c .)" = "2" ] || fail_msg "T5: store not healthy after crash+recovery (expected 2 entries)"
   # Bounded accumulation is preserved via a MAINTENANCE reap (store.sh init /
   # detector tick), age-scoped so it only removes DEMONSTRABLY-orphaned tmps
   # (older than any plausible in-flight write) and never a live one. Age the
@@ -191,7 +216,7 @@ echo "== T5: atomic write-tmp+rename survives crash mid-write =="
   "$STORE" init >/dev/null 2>&1 || fail_msg "T5: store.sh init (maintenance) failed"
   [ -e "$STATE_DIR/.wake.tmp.crash12" ] && fail_msg "T5: maintenance reap (store.sh init) must remove a demonstrably-orphaned stale temp (bounded accumulation)"
   d3="$("$STORE" drain)"
-  [ "$(printf '%s\n' "$d3" | grep -c .)" = "2" ] || fail_msg "T5: store not healthy after maintenance reap (expected 2 entries)"
+  [ "$(printf '%s\n' "$d3" | has_match -c .)" = "2" ] || fail_msg "T5: store not healthy after maintenance reap (expected 2 entries)"
   printf '%s\n' "$d3" | jq -e . >/dev/null 2>&1 || fail_msg "T5: drain returned non-JSON after maintenance reap"
 ) && ok
 
@@ -236,12 +261,12 @@ echo "== T6: durability survives restart (retain until CONSUMED) =="
   # "Session 2": a brand-new process (this subshell invocation of store.sh) must
   # see the persisted entries — nothing was held in memory.
   d="$("$STORE" drain)"
-  [ "$(printf '%s\n' "$d" | grep -c .)" = "2" ] || fail_msg "T6: entries not retained across restart (expected 2)"
+  [ "$(printf '%s\n' "$d" | has_match -c .)" = "2" ] || fail_msg "T6: entries not retained across restart (expected 2)"
   printf '%s\n' "$d" | stream_any '.class=="human"' || fail_msg "T6: a human message was lost across restart (durability bypassed)"
   # Retained UNTIL consumed: after CONSUMED they are released.
   "$STORE" consume --upto 2 >/dev/null
   d2="$("$STORE" drain)"
-  n2="$(printf '%s\n' "$d2" | grep -c . || true)"
+  n2="$(printf '%s\n' "$d2" | count_lines . || true)"
   [ "$n2" = "0" ] || fail_msg "T6: entries should be released only AFTER CONSUMED (still $n2 pending)"
 ) && ok
 
@@ -278,7 +303,7 @@ EOF
   end="$(date +%s.%N)"
   elapsed_ms="$(awk -v s="$start" -v e="$end" 'BEGIN { printf "%d", (e - s) * 1000 }')"
   [ "$elapsed_ms" -lt 1500 ] || fail_msg "T7: ack path blocked ${elapsed_ms}ms — must return without waiting on the background sync"
-  echo "$out" | grep -q 'CONSUMED 1' || fail_msg "T7: CONSUMED not reported [$out]"
+  echo "$out" | has_match -q 'CONSUMED 1' || fail_msg "T7: CONSUMED not reported [$out]"
   # Local write is durable IMMEDIATELY (no network needed to record the ack).
   STATE_DIR="$WAKE_STATE_HOME/default"
   jq_any "$STATE_DIR/ack-ledger.jsonl" '.type=="CONSUMED" and .upto==1' ||
@@ -303,8 +328,8 @@ echo "== T8: SOLE store-side allocator — enqueue (no --seq) allocates contiguo
   [ "$s1" = "1" ] || fail_msg "T8: first store-allocated observed_seq must be 1, got '$s1'"
   [ "$s2" = "2" ] || fail_msg "T8: second store-allocated observed_seq must be 2 (contiguous), got '$s2'"
   cur="$("$STORE" cursors)"
-  echo "$cur" | grep -q 'observed_seq=2' || fail_msg "T8: observed_seq cursor should be 2 [$cur]"
-  echo "$cur" | grep -q 'pending_depth=2' || fail_msg "T8: both allocations must be durably enqueued [$cur]"
+  echo "$cur" | has_match -q 'observed_seq=2' || fail_msg "T8: observed_seq cursor should be 2 [$cur]"
+  echo "$cur" | has_match -q 'pending_depth=2' || fail_msg "T8: both allocations must be durably enqueued [$cur]"
   # ANTI-SWALLOW: consume the prefix, then a LEGACY explicit --seq inside the
   # consumed prefix must FAIL LOUD (never the old silent seq<=consumed no-op).
   "$STORE" consume --upto 2 >/dev/null
@@ -313,7 +338,7 @@ echo "== T8: SOLE store-side allocator — enqueue (no --seq) allocates contiguo
     fail_msg "T8: explicit --seq 1 <= consumed_seq 2 must FAIL LOUD (anti-swallow), not be a silent no-op"
   fi
   err="$("$STORE" enqueue --seq 1 --class actionable --locators '{}' 2>&1 || true)"
-  echo "$err" | grep -qi 'anti-swallow' || fail_msg "T8: the refusal must name the anti-swallow guarantee [$err]"
+  echo "$err" | has_match -qi 'anti-swallow' || fail_msg "T8: the refusal must name the anti-swallow guarantee [$err]"
   after_depth="$("$STORE" cursors | sed -n 's/pending_depth=//p')"
   [ "$before_depth" = "$after_depth" ] || fail_msg "T8: a refused enqueue must not mutate the store (depth $before_depth->$after_depth)"
   # And the NEXT real allocation is > consumed (2) — never inside the prefix.
@@ -425,8 +450,8 @@ if command -v flock >/dev/null 2>&1; then
     [ -n "$a" ] && [ -n "$b" ] || fail_msg "T10: both concurrent enqueues must print an allocated seq (got '$a','$b')"
     [ "$a" != "$b" ] || fail_msg "T10: two concurrent enqueues must get DISTINCT seqs, both got '$a' (aliasing / lost write without the lock)"
     cur="$("$STORE" cursors)"
-    echo "$cur" | grep -q 'observed_seq=2' || fail_msg "T10: observed_seq must reach 2 after two enqueues [$cur]"
-    echo "$cur" | grep -q 'pending_depth=2' || fail_msg "T10: both entries must be durably stored (no lost write) [$cur]"
+    echo "$cur" | has_match -q 'observed_seq=2' || fail_msg "T10: observed_seq must reach 2 after two enqueues [$cur]"
+    echo "$cur" | has_match -q 'pending_depth=2' || fail_msg "T10: both entries must be durably stored (no lost write) [$cur]"
     # The two allocated seqs are exactly {1,2} (distinct, contiguous, gapless).
     lo="$a"; hi="$b"; [ "$a" -gt "$b" ] && { lo="$b"; hi="$a"; }
     { [ "$lo" = "1" ] && [ "$hi" = "2" ]; } || fail_msg "T10: concurrent seqs must be {1,2}, got {$lo,$hi}"
@@ -474,7 +499,7 @@ echo "== T11: final observed_seq cursor write FAILURE — fail loud + observed.s
   # the _atomic_write failure and returns 0).
   [ "$rc" -ne 0 ] || fail_msg "T11: an enqueue whose FINAL cursor write fails must EXIT NON-ZERO (fail loud), got rc=$rc"
   # The loud diagnostic names the cursor write (not a generic error).
-  grep -qi 'cursor' "$errfile" || fail_msg "T11: the failure diagnostic must name the observed_seq cursor write [$(cat "$errfile")]"
+  has_match -qi 'cursor' "$errfile" || fail_msg "T11: the failure diagnostic must name the observed_seq cursor write [$(cat "$errfile")]"
 
   # (2) The cursor did NOT advance — the allocation is NOT committed.
   obs_after="$("$STORE" cursors | sed -n 's/^observed_seq=//p')"
@@ -518,12 +543,206 @@ echo "== T12: #932 — consume records the last-consumed observed_hash per (kind
   r2h="$(jq -sr '[ .[] | select(.kind=="repo" and .id=="r2") ] | .[0].observed_hash' "$rec" 2>/dev/null)"
   [ "$r2h" = "HASH-C" ] || fail_msg "T12: repo/r2 must record HASH-C, got '$r2h'"
   # ADDITIVE: existing on-disk state files are unchanged/consistent post-consume.
-  "$STORE" cursors | grep -q 'consumed_seq=3' || fail_msg "T12: consumed_seq must be 3 after CONSUMED 3"
+  "$STORE" cursors | has_match -q 'consumed_seq=3' || fail_msg "T12: consumed_seq must be 3 after CONSUMED 3"
+) && ok
+
+echo "== T13: #946 — ordinary consume REFUSES to advance past a quarantined seq (store + ack paths) =="
+(
+  WAKE_STATE_HOME="$(fresh_state t13)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  "$STORE" enqueue --class actionable --locators '{"kind":"repo","id":"a","observed_hash":"HA"}' >/dev/null
+  "$STORE" enqueue --class actionable --locators '{"kind":"repo","id":"b","observed_hash":"HB"}' >/dev/null
+  "$STORE" enqueue --class actionable --locators '{"kind":"repo","id":"c","observed_hash":"HC"}' >/dev/null
+  printf '2\n' | "$STORE" quarantine-sync || fail_msg "T13: quarantine-sync must accept a valid seq list"
+  # A quarantined seq was dead-lettered at render and NEVER delivered in any
+  # digest; the ordinary path must REFUSE to record it consumed (#946: a force
+  # flag the ordinary path can bypass is decoration).
+  if "$STORE" consume --upto 3 >/dev/null 2>&1; then
+    fail_msg "T13: ordinary consume --upto 3 must be REFUSED while seq 2 is quarantined"
+  fi
+  err="$("$STORE" consume --upto 3 2>&1 >/dev/null || true)"
+  echo "$err" | has_match -q 'quarantined seq(s): 2' || fail_msg "T13: the refusal must NAME the quarantined seq [$err]"
+  echo "$err" | has_match -q -- '--force-past-quarantine' || fail_msg "T13: the refusal must NAME the force flag [$err]"
+  cur="$("$STORE" cursors)"
+  echo "$cur" | has_match -q 'consumed_seq=0' || fail_msg "T13: a refused consume must NOT advance the cursor [$cur]"
+  # BELOW the quarantined seq the ordinary path is unaffected.
+  "$STORE" consume --upto 1 >/dev/null 2>&1 || fail_msg "T13: consume --upto 1 (below the quarantined seq) must succeed"
+  # The ack wrapper propagates the refusal — no ordinary-path bypass exists.
+  if "$ACK" consumed --upto 3 --no-sync >/dev/null 2>&1; then
+    fail_msg "T13: ack.sh consumed --upto 3 must be REFUSED while seq 2 is quarantined (ordinary-path bypass)"
+  fi
+  cur="$("$STORE" cursors)"
+  echo "$cur" | has_match -q 'consumed_seq=1' || fail_msg "T13: cursor must still be 1 after the refused ack [$cur]"
+) && ok
+
+echo "== T14: #946 — FORCED step-over is LOUD, prunes the set, and NEVER fabricates a consumed-hash row for the quarantined entry =="
+(
+  WAKE_STATE_HOME="$(fresh_state t14)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  rec="$WAKE_STATE_HOME/default/consumed-hashes.jsonl"
+  qf="$WAKE_STATE_HOME/default/quarantined.set"
+  "$STORE" enqueue --class actionable --locators '{"kind":"repo","id":"a","observed_hash":"HA"}' >/dev/null
+  "$STORE" enqueue --class actionable --locators '{"kind":"repo","id":"b","observed_hash":"HB"}' >/dev/null
+  "$STORE" enqueue --class actionable --locators '{"kind":"repo","id":"c","observed_hash":"HC"}' >/dev/null
+  printf '2\n' | "$STORE" quarantine-sync || fail_msg "T14: quarantine-sync failed"
+  errf="$TMP_ROOT/t14.err"
+  out="$("$STORE" consume --upto 3 --force-past-quarantine 2>"$errf")"
+  rc=$?
+  [ "$rc" -eq 0 ] || fail_msg "T14: forced consume must succeed (rc=$rc) [$(cat "$errf")]"
+  [ "$out" = "3" ] || fail_msg "T14: forced consume must print the new cursor 3, got '$out'"
+  has_match -q 'FORCED PAST QUARANTINE' "$errf" || fail_msg "T14: the forced path must be LOUD on stderr [$(cat "$errf")]"
+  has_match -q 'seq 2' "$errf" || fail_msg "T14: the forced-path diagnostic must name the stepped-over seq 2 [$(cat "$errf")]"
+  "$STORE" cursors | has_match -q 'consumed_seq=3' || fail_msg "T14: forced consume must advance the cursor to 3"
+  # NO FALSE WITNESS: the quarantined entry (repo/b) was NEVER delivered, so no
+  # consumed-hash row may exist for it — even on the forced path (the reconciler
+  # re-enumerating it once is safe-but-noisy; a false witness silences it
+  # forever). Its delivered siblings' rows must exist.
+  jq_any "$rec" '.kind=="repo" and .id=="a" and .observed_hash=="HA"' || fail_msg "T14: the delivered sibling repo/a must have its consumed-hash row"
+  jq_any "$rec" '.kind=="repo" and .id=="c" and .observed_hash=="HC"' || fail_msg "T14: the delivered sibling repo/c must have its consumed-hash row"
+  jq_any "$rec" '.kind=="repo" and .id=="b"' && fail_msg "T14: the quarantined entry repo/b must have NO consumed-hash row (a row would witness a delivery that never happened)"
+  # The stepped-over seq is PRUNED from the set (it is consumed now; a stale
+  # entry would re-refuse forever).
+  has_match -qxF '2' "$qf" 2>/dev/null && fail_msg "T14: seq 2 must be PRUNED from quarantined.set after the forced step-over"
+  # The ack wrapper's force flag passes through, stays LOUD on stderr, and
+  # still reports a CLEAN cursor line on stdout.
+  "$STORE" enqueue --class actionable --locators '{"kind":"repo","id":"d","observed_hash":"HD"}' >/dev/null
+  "$STORE" enqueue --class actionable --locators '{"kind":"repo","id":"e","observed_hash":"HE"}' >/dev/null
+  printf '5\n' | "$STORE" quarantine-sync || fail_msg "T14: quarantine-sync (2nd) failed"
+  errf2="$TMP_ROOT/t14b.err"
+  out2="$("$ACK" consumed --upto 5 --no-sync --force-past-quarantine 2>"$errf2")"
+  rc2=$?
+  [ "$rc2" -eq 0 ] || fail_msg "T14: forced ack must succeed (rc=$rc2) [$(cat "$errf2")]"
+  echo "$out2" | has_match -q '^CONSUMED 5$' || fail_msg "T14: forced ack must report a CLEAN cursor line 'CONSUMED 5', got '$out2'"
+  has_match -q 'FORCED PAST QUARANTINE' "$errf2" || fail_msg "T14: the forced-path loudness must survive the ack wrapper (stderr) [$(cat "$errf2")]"
+  jq_any "$rec" '.kind=="repo" and .id=="e"' && fail_msg "T14: the quarantined repo/e must have NO consumed-hash row via the forced ack path either"
+  true
+) && ok
+
+echo "== T15: #946 — quarantine-sync is a full REPLACE (sorted, deduped; empty input CLEARS; invalid input REFUSED) =="
+(
+  WAKE_STATE_HOME="$(fresh_state t15)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  qf="$WAKE_STATE_HOME/default/quarantined.set"
+  printf '3\n1\n3\n' | "$STORE" quarantine-sync || fail_msg "T15: sync of a valid list must succeed"
+  [ "$(cat "$qf" 2>/dev/null)" = "$(printf '1\n3')" ] || fail_msg "T15: set must be sorted+deduped {1,3}, got [$(cat "$qf" 2>/dev/null)]"
+  printf '2\n' | "$STORE" quarantine-sync || fail_msg "T15: re-sync must succeed"
+  [ "$(cat "$qf" 2>/dev/null)" = "2" ] || fail_msg "T15: sync must REPLACE, not merge — expected {2}, got [$(cat "$qf" 2>/dev/null)]"
+  # Empty input CLEARS the set: the set is re-DERIVED per authoritative render,
+  # never accumulated, so a fixed locator gate self-heals the clamp.
+  : | "$STORE" quarantine-sync || fail_msg "T15: empty sync (clear) must succeed"
+  [ ! -s "$qf" ] || fail_msg "T15: empty sync must CLEAR the set, got [$(cat "$qf")]"
+  # Invalid input is refused loudly and must not corrupt the set.
+  printf '1\n' | "$STORE" quarantine-sync || fail_msg "T15: re-seed failed"
+  if printf 'abc\n' | "$STORE" quarantine-sync >/dev/null 2>&1; then
+    fail_msg "T15: a non-integer line must be REFUSED"
+  fi
+  [ "$(cat "$qf" 2>/dev/null)" = "1" ] || fail_msg "T15: a refused sync must leave the set untouched, got [$(cat "$qf" 2>/dev/null)]"
+  # End-to-end: a cleared set stops clamping (the #944 recovery case).
+  "$STORE" enqueue --class actionable --locators '{"kind":"repo","id":"x","observed_hash":"H1"}' >/dev/null
+  if "$STORE" consume --upto 1 >/dev/null 2>&1; then
+    fail_msg "T15: consume --upto 1 must be refused while seq 1 is quarantined"
+  fi
+  : | "$STORE" quarantine-sync || fail_msg "T15: clear failed"
+  "$STORE" consume --upto 1 >/dev/null 2>&1 || fail_msg "T15: after the set is cleared (gate fixed), the ordinary consume must succeed — the clamp must self-heal"
+) && ok
+
+echo "== T16: #946 — quarantine-audit: a consumed-hash row matching a dead-letter entry on (kind,id,seq,hash) at/below consumed_seq is PROVABLY FALSE; --repair removes ONLY those rows =="
+(
+  WAKE_STATE_HOME="$(fresh_state t16)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  STATE_DIR="$WAKE_STATE_HOME/default"
+  rec="$STATE_DIR/consumed-hashes.jsonl"
+  dl="$STATE_DIR/dead-letter.jsonl"
+  # Rebuild the historical false-witness state via the REAL flow the defect
+  # used: X@1 was quarantined (dead-lettered) yet consumed under pre-#946 code;
+  # Y@2 is clean; Z re-emitted (dead-lettered at seq 3, healed by seq 4 winning
+  # the per-key max_by merge — Finding A's live-canary shape).
+  "$STORE" enqueue --class actionable --locators '{"kind":"repo","id":"X","observed_hash":"HX"}' >/dev/null
+  "$STORE" enqueue --class actionable --locators '{"kind":"repo","id":"Y","observed_hash":"HY"}' >/dev/null
+  "$STORE" enqueue --class actionable --locators '{"kind":"repo","id":"Z","observed_hash":"HZ-OLD"}' >/dev/null
+  "$STORE" enqueue --class actionable --locators '{"kind":"repo","id":"Z","observed_hash":"HZ-NEW"}' >/dev/null
+  {
+    printf '%s\n' '{"observed_seq":1,"locators":{"kind":"repo","id":"X","observed_hash":"HX"},"class":"actionable","emit_ts":1,"hmac":""}'
+    printf '%s\n' '{"observed_seq":3,"locators":{"kind":"repo","id":"Z","observed_hash":"HZ-OLD"},"class":"actionable","emit_ts":1,"hmac":""}'
+  } >"$dl"
+  # Pre-#946-shaped consume: NO quarantined.set exists, so this consume writes
+  # the false witness for X@1 exactly as the live defect did.
+  "$STORE" consume --upto 4 >/dev/null 2>&1 || fail_msg "T16: baseline consume failed"
+  jq_any "$rec" '.id=="X" and .observed_seq==1' || fail_msg "T16: fixture broken — the false X@1 row was not written"
+  # REPORT: exactly the X row is provably false; non-zero exit signals findings.
+  rep="$TMP_ROOT/t16.rep"
+  if "$STORE" quarantine-audit >"$rep" 2>&1; then
+    fail_msg "T16: report-mode audit must exit NON-ZERO when false rows exist"
+  fi
+  has_match -q 'FALSE WITNESS' "$rep" || fail_msg "T16: the audit must name the false row loudly [$(cat "$rep")]"
+  has_match -q '"id":"X"' "$rep" || fail_msg "T16: the audit must identify the false row (repo/X@1) [$(cat "$rep")]"
+  has_match -q '"id":"Y"' "$rep" && fail_msg "T16: the clean row repo/Y must NOT be flagged"
+  has_match -q '"id":"Z"' "$rep" && fail_msg "T16: the HEALED row repo/Z@4 must NOT be flagged (its dead-letter evidence is seq 3 with a different hash)"
+  # Report mode modifies nothing.
+  jq_any "$rec" '.id=="X"' || fail_msg "T16: report mode must not modify the record"
+  # REPAIR: exactly the false row is removed; the dead-letter LEDGER is history
+  # and must never be modified.
+  "$STORE" quarantine-audit --repair >"$TMP_ROOT/t16.fix" 2>&1 || fail_msg "T16: --repair must succeed [$(cat "$TMP_ROOT/t16.fix")]"
+  jq_any "$rec" '.id=="X"' && fail_msg "T16: --repair must REMOVE the provably-false X row"
+  jq_any "$rec" '.id=="Y" and .observed_hash=="HY"' || fail_msg "T16: --repair must keep the clean Y row"
+  jq_any "$rec" '.id=="Z" and .observed_hash=="HZ-NEW" and .observed_seq==4' || fail_msg "T16: --repair must keep the healed Z@4 row"
+  [ "$(has_match -c . "$dl")" = "2" ] || fail_msg "T16: the dead-letter LEDGER must be untouched by --repair"
+  # Clean re-audit: OK, exit 0.
+  "$STORE" quarantine-audit >"$TMP_ROOT/t16.ok" 2>&1 || fail_msg "T16: a clean audit must exit 0 [$(cat "$TMP_ROOT/t16.ok")]"
+  has_match -qi 'OK' "$TMP_ROOT/t16.ok" || fail_msg "T16: a clean audit must say OK [$(cat "$TMP_ROOT/t16.ok")]"
+) && ok
+
+echo "== T17: #952 — the clean-sweep message names BOTH unprovable residual classes; a surviving-but-empty-hash dead-letter row is correctly NOT convicted =="
+(
+  WAKE_STATE_HOME="$(fresh_state t17)"
+  export WAKE_STATE_HOME
+  unset WAKE_AGENT
+  STATE_DIR="$WAKE_STATE_HOME/default"
+  rec="$STATE_DIR/consumed-hashes.jsonl"
+  dl="$STATE_DIR/dead-letter.jsonl"
+  # Drive the REAL flow so the consumed-hashes row is produced by the actual
+  # writer (_record_last_consumed), not hand-built: 12 fillers, then the bench
+  # key lands at observed_seq 13 — the same seq as the live specimen below.
+  i=1
+  while [ "$i" -le 12 ]; do
+    "$STORE" enqueue --class actionable --locators "{\"kind\":\"filler\",\"id\":\"f$i\",\"observed_hash\":\"HF$i\"}" >/dev/null || fail_msg "T17: filler enqueue $i failed"
+    i=$((i + 1))
+  done
+  "$STORE" enqueue --class actionable --locators '{"kind":"bench","id":"malformed-locator-test","observed_hash":"H-REAL-CONSUMED"}' >/dev/null
+  "$STORE" consume --upto 13 >/dev/null 2>&1 || fail_msg "T17: baseline consume failed"
+  jq_any "$rec" '.kind=="bench" and .id=="malformed-locator-test" and .observed_seq==13 and .observed_hash=="H-REAL-CONSUMED"' ||
+    fail_msg "T17: fixture broken — the real writer did not record the bench@13 row"
+  # VERBATIM live specimen: mos-dt lane dead-letter.jsonl line 1 (2026-07-26).
+  # Copied byte-for-byte per the #952 fixture constraint — nested .locators.*
+  # with NO observed_hash key, so the audit's extraction yields "".
+  printf '%s\n' '{"observed_seq":13,"locators":{"kind":"bench","id":"malformed-locator-test","note":"deliberately non-conformant"},"class":"actionable","emit_ts":1785055610,"hmac":""}' >"$dl"
+  # Guard the near-miss trap: the specimen must be genuinely NESTED (no
+  # top-level kind) and must extract an EMPTY hash via the audit's own paths.
+  jq -e '(has("kind") | not) and .locators.kind=="bench" and ((.locators.observed_hash // "") == "")' "$dl" >/dev/null ||
+    fail_msg "T17: specimen fixture is not the genuine nested shape — rebuild it from the live lane, not the schema"
+  # Evidence SURVIVES (kind/id/seq all match the row) but extracts hash "";
+  # _record_last_consumed never writes an empty-hash row, so the four-field
+  # match can never fire: this is unprovable class 2, NOT a false witness.
+  rep="$TMP_ROOT/t17.rep"
+  "$STORE" quarantine-audit >"$rep" 2>&1 || fail_msg "T17: the audit must exit 0 — nothing here is provable [$(cat "$rep")]"
+  has_match -q 'FALSE WITNESS' "$rep" && fail_msg "T17: the empty-hash evidence must NOT convict (the predicate is correct and must not change) [$(cat "$rep")]"
+  # The wording under test (#952): BOTH residual classes, named.
+  has_match -qi 'pruned' "$rep" || fail_msg "T17: clean sweep must name residual class 1 — evidence pruned away [$(cat "$rep")]"
+  has_match -qi 'empty observed_hash' "$rep" || fail_msg "T17: clean sweep must name residual class 2 — surviving evidence with an empty observed_hash [$(cat "$rep")]"
+  # --repair on a clean sweep removes nothing: the unprovable row survives.
+  "$STORE" quarantine-audit --repair >"$TMP_ROOT/t17.fix" 2>&1 || fail_msg "T17: --repair on a clean sweep must exit 0 [$(cat "$TMP_ROOT/t17.fix")]"
+  jq_any "$rec" '.kind=="bench" and .observed_seq==13 and .observed_hash=="H-REAL-CONSUMED"' ||
+    fail_msg "T17: --repair must NOT remove the unprovable bench@13 row — the audit only removes what the ledger can convict"
+  [ "$(count_lines . "$dl")" = "1" ] || fail_msg "T17: the dead-letter LEDGER must be untouched"
 ) && ok
 
 echo
 if [ -s "$FAILFILE" ]; then
-  echo "wake store/ack harness: FAILED ($(grep -c . "$FAILFILE") assertion(s))" >&2
+  echo "wake store/ack harness: FAILED ($(count_lines . "$FAILFILE") assertion(s))" >&2
   exit 1
 fi
 echo "wake store/ack harness: all invariants passed ($pass groups)"

packages/mosaic/framework/tools/wake/test-wake-store-enqueue-race.sh

@@ -32,6 +32,13 @@
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# #973: three-valued grep assertion helpers (has_match/count_lines); init saves real stderr for abort loudness.
+# shellcheck disable=SC1091
+if ! . "$SCRIPT_DIR/_wake-common.sh"; then
+  echo "WAKE-ASSERT INIT ABORT: cannot source _wake-common.sh — suite ran ZERO wake assertions (#984)" >&2
+  exit 97
+fi
+wake_assert_init
 STORE="$SCRIPT_DIR/store.sh"
 
 command -v jq >/dev/null 2>&1 || {
@@ -147,7 +154,7 @@ EOF
     wait "$pa" 2>/dev/null || true
   else
     # Confirm the window is genuinely open: A holds a live in-flight tmp now.
-    n_tmp="$(find "$STATE_DIR" -maxdepth 1 -name '.wake.tmp.*' -type f | grep -c . || true)"
+    n_tmp="$(find "$STATE_DIR" -maxdepth 1 -name '.wake.tmp.*' -type f | count_lines . || true)"
     [ "$n_tmp" -ge 1 ] || fail_msg "T-RACE: expected A's live in-flight tmp to exist while A holds the lock (got $n_tmp)"
 
     # B: its PRE-LOCK _wake_init_dir runs now (pre-fix: deletes A's live tmp),
@@ -173,7 +180,7 @@ EOF
     if [ "$ra" -ne 0 ]; then
       fail_msg "T-RACE: enqueue A was SPURIOUSLY ABORTED (rc=$ra) — its live in-flight tmp was deleted by B's pre-lock cleanup [#927]. stderr: $(tr '\n' ' ' <"$a_err")"
     fi
-    if grep -q 'durable pending write FAILED' "$a_err" 2>/dev/null; then
+    if has_match -q 'durable pending write FAILED' "$a_err" 2>/dev/null; then
       fail_msg "T-RACE: enqueue A reported 'durable pending write FAILED' — the exact #927 spurious abort (its tmp was clobbered mid-write by a concurrent pre-lock cleanup)."
     fi
     [ "$rb" -eq 0 ] || fail_msg "T-RACE: enqueue B should also succeed (rc=$rb). stderr: $(tr '\n' ' ' <"$b_err")"
@@ -189,20 +196,20 @@ EOF
 
     # #908 store invariants: both durably landed, cursor reached 2, no burned seq.
     cur="$("$STORE" cursors)"
-    echo "$cur" | grep -q 'observed_seq=2' || fail_msg "T-RACE: observed_seq must reach 2 (both allocations committed) [$cur]"
-    echo "$cur" | grep -q 'pending_depth=2' || fail_msg "T-RACE: both entries must be durably stored — no lost/aborted write [$cur]"
-    echo "$cur" | grep -q 'consumed_seq=0' || fail_msg "T-RACE: enqueue must never advance consumed_seq [$cur]"
+    echo "$cur" | has_match -q 'observed_seq=2' || fail_msg "T-RACE: observed_seq must reach 2 (both allocations committed) [$cur]"
+    echo "$cur" | has_match -q 'pending_depth=2' || fail_msg "T-RACE: both entries must be durably stored — no lost/aborted write [$cur]"
+    echo "$cur" | has_match -q 'consumed_seq=0' || fail_msg "T-RACE: enqueue must never advance consumed_seq [$cur]"
     # Gapless: the contiguous prefix 1..2 is consumable (no interior gap/burn).
     "$STORE" consume --upto 2 >/dev/null 2>&1 || fail_msg "T-RACE: CONSUMED 2 must succeed — seqs {1,2} are gapless (no burned seq)"
     # No stale tmp left leaking either.
-    n_leak="$(find "$STATE_DIR" -maxdepth 1 -name '.wake.tmp.*' -type f | grep -c . || true)"
+    n_leak="$(find "$STATE_DIR" -maxdepth 1 -name '.wake.tmp.*' -type f | count_lines . || true)"
     [ "$n_leak" = "0" ] || fail_msg "T-RACE: $n_leak stale tmp file(s) leaked after both enqueues committed"
   fi
 ) && ok
 
 echo
 if [ -s "$FAILFILE" ]; then
-  echo "wake store enqueue-race harness: FAILED ($(grep -c . "$FAILFILE") assertion(s)) — #927 TOCTOU reproduced (RED)" >&2
+  echo "wake store enqueue-race harness: FAILED ($(count_lines . "$FAILFILE") assertion(s)) — #927 TOCTOU reproduced (RED)" >&2
   exit 1
 fi
 echo "wake store enqueue-race harness: all invariants passed ($pass group) — #927 race closed (GREEN)"

packages/mosaic/framework/tools/wake/validate-973/check-973.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""check-973.py — computation backend for the #973 validation harness.
+
+Everything here derives from exactly two inputs: the frozen denominator
+artifact (denominator-089615f.json) and the SOURCE TEXT of the ten converted
+suites at the current tree. It never reads the ledger — set arithmetic against
+the runtime trace belongs to validate-973.sh, so the two legs of the
+comparison come from independent code paths.
+
+Subcommands (all print sorted, stable output; non-zero exit on any failure):
+
+  expected   The expected coordinate set from the ARTIFACT: one
+             "<helper> <file>:<line+7>" row per denominator row (+7 = 3
+             converter header lines + 4 lines from the #984 source guard,
+             uniform across all ten suites).
+             Multi-grep lines stay ONE coordinate.
+
+  static     The converted-site inventory from the SOURCE TEXT at the current
+             tree: every non-comment line bearing a has_match/count_lines
+             token, as "<helper> <file>:<line>". Independent of the artifact
+             row list, so `expected == static` is a real check on the
+             conversion, not a tautology. (Amendment ONE, leg 1: the ledger is
+             an execution trace, not an inventory — the inventory must come
+             from the text.)
+
+  arms       The forced-error arm list: the 19 denominator canaries plus one
+             E-form arm (store-ack:733→740, a $(count_lines) capture compared
+             afterward — the A6 shape) plus one F-form arm (quarantine:560→567,
+             the multi-grep pipeline capture), as "<helper> <file>:<line+7>
+             <form>". Both extras are asserted to exist in the artifact with
+             the expected form — a renumber that moved them fails here, not
+             silently downstream.
+
+  sweep      Residual sweep: the denominator's own classifier (ported from the
+             frozen derivation) over the ten suites at the current tree must
+             find ZERO unconverted verdict-form grep sites; and, IN THE SAME
+             RUN, eight specimens (six per-form + two absorb-branch probes, #985)
+             planted into a temp copy of a real
+             suite must ALL be found with their correct forms — an instrument
+             that reports zero must first be seen finding what it claims to
+             find (A5).
+"""
+
+import json
+import re
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+WAKE = HERE.parent
+ART = HERE / "denominator-089615f.json"
+
+HEADER_SHIFT = 7  # 3 converter header lines after SCRIPT_DIR + 4 lines from the
+# #984 source guard (1-line `. _wake-common.sh && wake_assert_init` became a 5-line
+# guarded block) — both uniform across all ten suites, both above every site.
+
+# The two hand-picked extra arms (base coordinates; forms asserted at load).
+EXTRA_ARMS = [
+    ("test-wake-store-ack.sh", 733, "E-count-capture"),
+    ("test-wake-digest-quarantine.sh", 560, "F-extract-capture"),
+]
+
+RX_HELPER = re.compile(r"(^|[^A-Za-z0-9_.-])(has_match|count_lines)([^A-Za-z0-9_.-]|$)")
+
+# ---- classifier, ported verbatim in logic from the frozen denominator
+# ---- derivation (docs/journal/fleet/drift-derive-089615f__pepper.py)
+RX_FAIL_SAME = re.compile(r"(\|\||&&)\s*fail")
+RX_COUNT_SUB = re.compile(r"\$\(.*grep\s+[^)]*-c|\$\(\s*grep\s+-c")
+RX_ASSIGN_SUB = re.compile(r'=\s*"?\$\(.*grep')
+RX_IF = re.compile(r"^\s*(el)?if\s+.*grep")
+RX_GREP = re.compile(r"(^|[^A-Za-z0-9_.-])grep([^A-Za-z0-9_.-]|$)")
+
+# grep in COMMAND position: at line start or after a command separator / subshell
+# opener / shell keyword / `!`. Quote-unaware by design — a quoted "grep" after a
+# separator reads as a command and lands the line in residual, which fails LOUD;
+# the absorb direction (note) is the one that must never fire on a real verdict.
+RX_GREP_CMD = re.compile(
+    r"(?:^|[;|&(`]|\$\(|\bif\b|\belif\b|\bthen\b|\belse\b|\bdo\b|\bwhile\b|\buntil\b|!)"
+    r"\s*grep(?:\s|$)"
+)
+
+
+def classify(lines):
+    """Return (sites, dispo). Every line containing the word grep gets a row."""
+    sites, dispo = [], []
+    n = len(lines)
+    for i, raw in enumerate(lines):
+        line = raw
+        ln = i + 1
+        if not RX_GREP.search(line):
+            continue
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            dispo.append((ln, "comment", stripped))
+            continue
+        nxt = ""
+        for j in range(i + 1, min(i + 3, n)):
+            if lines[j].strip():
+                nxt = lines[j].strip()
+                break
+        if "$(" in line and RX_COUNT_SUB.search(line):
+            sites.append((ln, "E-count-capture", stripped))
+            continue
+        if RX_ASSIGN_SUB.search(line) and "grep -c" not in line:
+            sites.append((ln, "F-extract-capture", stripped))
+            continue
+        if RX_FAIL_SAME.search(line):
+            sites.append((ln, "A-same-line", stripped))
+            continue
+        if stripped.endswith("\\"):
+            k = i + 1
+            joined = stripped[:-1]
+            while k < n:
+                cont = lines[k].strip()
+                joined += " " + (cont[:-1] if cont.endswith("\\") else cont)
+                if not cont.endswith("\\"):
+                    break
+                k += 1
+            if re.search(r"(\|\||&&)\s*fail", joined) or (
+                joined.rstrip().endswith(("||", "&&"))
+                and k + 1 < n
+                and lines[k + 1].strip().startswith("fail")
+            ):
+                sites.append((ln, "C-cont-backslash", stripped))
+                continue
+            dispo.append((ln, "backslash-no-fail-continuation", stripped))
+            continue
+        if stripped.endswith(("||", "&&")) and nxt.startswith("fail"):
+            sites.append((ln, "B-cont-operator", stripped))
+            continue
+        if RX_IF.search(line):
+            window = " ".join(lines[j] for j in range(i, min(i + 5, n)))
+            if "fail" in window:
+                sites.append((ln, "D-if-form", stripped))
+                continue
+            dispo.append((ln, "if-grep-no-fail-window", stripped))
+            continue
+        win = " ".join(lines[j] for j in range(max(0, i - 2), min(i + 3, n)))
+        if re.search(r"fail", win, re.I):
+            dispo.append((ln, "BACKSTOP-HAND-REVIEW", stripped))
+        else:
+            dispo.append((ln, "no-verdict-context", stripped))
+    return sites, dispo
+
+
+def residual_sites(lines):
+    """classify() plus the absorb decision — the ONE path both sweep legs share.
+
+    A classified site is absorbed as a note only when its line carries a wake
+    helper token AND the line shows no grep in command position: a converted
+    line whose PATTERN argument merely contains the word grep. A helper line
+    that also runs a real grep verdict (has_match ... && grep -q SECRET ... &&
+    fail) stays residual (#985). Multi-line forms anchor the site at the line
+    containing grep, so a command-position grep on a continuation line never
+    shares its line with the helper token and stays residual by construction.
+    """
+    sites, dispo = classify(lines)
+    residual, notes = [], []
+    for ln, form, text in sites:
+        line = lines[ln - 1]
+        if RX_HELPER.search(line) and not RX_GREP_CMD.search(line):
+            notes.append((ln, form, text))
+        else:
+            residual.append((ln, form, text))
+    return residual, notes, dispo
+
+
+def load_art():
+    art = json.loads(ART.read_text())
+    assert art["total"] == 261 == len(art["rows"]), "artifact self-consistency"
+    return art
+
+
+def helper_for(row):
+    return "count_lines" if row["form"].startswith("E") else "has_match"
+
+
+def suite_files(art):
+    return sorted({r["file"] for r in art["rows"]})
+
+
+def cmd_expected():
+    art = load_art()
+    out = sorted(
+        f"{helper_for(r)} {r['file']}:{r['line'] + HEADER_SHIFT}" for r in art["rows"]
+    )
+    assert len(out) == len(set(out)) == 261, "expected set must be 261 distinct rows"
+    print("\n".join(out))
+    return 0
+
+
+def cmd_static():
+    art = load_art()
+    rows = []
+    for f in suite_files(art):
+        for i, line in enumerate((WAKE / f).read_text().split("\n"), start=1):
+            if line.strip().startswith("#"):
+                continue
+            m = RX_HELPER.search(line)
+            if not m:
+                continue
+            helper = (
+                "count_lines"
+                if RX_HELPER.search(line).group(2) == "count_lines"
+                else "has_match"
+            )
+            rows.append(f"{helper} {f}:{i}")
+    print("\n".join(sorted(rows)))
+    return 0
+
+
+def cmd_arms():
+    art = load_art()
+    by_key = {(r["file"], r["line"]): r for r in art["rows"]}
+    rows = []
+    canaries = [r for r in art["rows"] if r.get("canary")]
+    assert len(canaries) == 19, f"expected 19 canaries, artifact has {len(canaries)}"
+    for r in canaries:
+        rows.append(f"{helper_for(r)} {r['file']}:{r['line'] + HEADER_SHIFT} {r['form']}")
+    for f, ln, want_form in EXTRA_ARMS:
+        r = by_key.get((f, ln))
+        assert r is not None, f"extra arm {f}:{ln} not in artifact — renumbered?"
+        assert r["form"] == want_form, f"extra arm {f}:{ln} form {r['form']} != {want_form}"
+        rows.append(f"{helper_for(r)} {f}:{ln + HEADER_SHIFT} {r['form']}")
+    assert len(rows) == 21
+    print("\n".join(rows))
+    return 0
+
+
+# (expected classify form, expected disposition through residual_sites, snippet)
+PLANTS = [
+    ("A-same-line", "residual", ['grep -q needle haystack || fail "plant-A"']),
+    ("B-cont-operator", "residual", ["grep -q needle haystack ||", '  fail "plant-B"']),
+    ("C-cont-backslash", "residual", ["grep -q needle \\", '  haystack || fail "plant-C"']),
+    ("D-if-form", "residual", ["if ! grep -q needle haystack; then", '  fail "plant-D"', "fi"]),
+    ("E-count-capture", "residual", ['[ "$(grep -c needle haystack)" = "1" ] || fail "plant-E"']),
+    ("F-extract-capture", "residual", ['val="$(grep needle haystack)"']),
+    # G: a converted line that ALSO runs a raw grep verdict — the helper token
+    # must not absorb it (#985)
+    ("A-same-line", "residual", ['has_match -q needle "$F" && grep -q SECRET "$F" && fail "plant-G"']),
+    # H: negative control — helper whose PATTERN argument is the word grep;
+    # must be absorbed as a note, never residual
+    ("A-same-line", "note", ['has_match -q "grep" haystack || fail "plant-H"']),
+]
+
+
+def cmd_sweep():
+    art = load_art()
+    bad = 0
+
+    # leg 1: real suites at the current tree must be residual-free
+    for f in suite_files(art):
+        residual, notes, _dispo = residual_sites((WAKE / f).read_text().split("\n"))
+        for ln, form, text in notes:
+            # converted line whose PATTERN argument contains the word grep:
+            # not an unconverted site, but never silently absorbed either
+            print(f"SWEEP-NOTE {f}:{ln} converted line matches grep-token ({form}): {text[:80]}")
+        for ln, form, text in residual:
+            print(f"SWEEP-RESIDUAL {f}:{ln} {form}: {text[:100]}")
+            bad += 1
+        print(f"SWEEP {f}: {len(residual)} residual verdict site(s)")
+
+    # leg 2, SAME RUN, SAME PATH as leg 1: the instrument must find every plant
+    # with the right form AND the right absorb disposition — plants G/H exercise
+    # the absorb branch itself, so this leg must go through residual_sites(),
+    # not raw classify()
+    donor = suite_files(art)[0]
+    with tempfile.TemporaryDirectory() as td:
+        planted = Path(td) / donor
+        shutil.copy(WAKE / donor, planted)
+        base_lines = planted.read_text().split("\n")
+        offset = len(base_lines)
+        expect = {}
+        for form, dispo, snippet in PLANTS:
+            expect[offset + 1] = (form, dispo)  # first physical line of each plant
+            base_lines.extend(snippet)
+            offset = len(base_lines)
+        planted.write_text("\n".join(base_lines))
+        residual, notes, _ = residual_sites(planted.read_text().split("\n"))
+        found = {ln: (form, "residual") for ln, form, _t in residual}
+        found.update({ln: (form, "note") for ln, form, _t in notes})
+        unexpected = [(ln, form) for ln, form, _t in residual if ln not in expect]
+        hits = sum(1 for ln, want in expect.items() if found.get(ln) == want)
+        n_plants = len(PLANTS)
+        print(f"SWEEP-PLANTS found={hits}/{n_plants} in planted copy of {donor}")
+        if hits != n_plants:
+            for ln, want in sorted(expect.items()):
+                got = found.get(ln, ("<missed>", "<missed>"))
+                if got != want:
+                    print(f"SWEEP-PLANT-MISS line {ln}: expected {want}, got {got}")
+            bad += 1
+        if unexpected:
+            # the donor is a converted suite: any non-plant RESIDUAL site in the
+            # copy contradicts the zero leg 1 just reported on the original
+            # (non-plant notes mirror leg 1's treatment: printed there, not bad)
+            for ln, form in unexpected:
+                print(f"SWEEP-PLANT-UNEXPECTED {donor}(copy):{ln} {form}")
+            bad += 1
+
+    return 1 if bad else 0
+
+
+def main():
+    cmds = {
+        "expected": cmd_expected,
+        "static": cmd_static,
+        "arms": cmd_arms,
+        "sweep": cmd_sweep,
+    }
+    if len(sys.argv) != 2 or sys.argv[1] not in cmds:
+        sys.exit(f"usage: check-973.py {{{'|'.join(cmds)}}}")
+    sys.exit(cmds[sys.argv[1]]())
+
+
+if __name__ == "__main__":
+    main()

packages/mosaic/framework/tools/wake/validate-973/convert-973.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""convert-973.py — mechanical #973 site conversion, driven by the frozen
+denominator artifact (denominator-089615f.json), never by ad-hoc grepping.
+
+For every row in the artifact it FIRST verifies the worktree line still says
+what the artifact froze (exact match after whitespace strip, artifact-side
+truncation as prefix match, or the normalized suite-summary template), and
+aborts before touching anything on the first verification failure — a
+conversion applied to a line the denominator did not measure would be the
+umbrella defect wearing the converter's clothes.
+
+Transforms (behaviour-preserving; verdict semantics unchanged on grep rc 0/1):
+  E-count-capture   `grep -c ARGS`  -> `count_lines ARGS`  (helper adds -c)
+  all other forms   `grep ARGS`     -> `has_match ARGS`    (drop-in)
+  env prefixes (`LC_ALL=C grep`) are kept — the prefix reaches the grep child
+  through the function (microtest C8).
+
+The two multi-grep pipeline sites (digest-quarantine:560, install:420) convert
+BOTH greps: each is measurement-bearing, and under pipefail an rc=2 in the
+left element is masked by an rc=1 in the right — the same defect one pipe
+deeper. They stay ONE denominator site each (one coordinate); the ledger
+records helper calls, so those coordinates appear twice per execution and the
+equality check compares SETS of coordinates.
+
+Finally each suite gains three header lines directly after its SCRIPT_DIR
+assignment (source + wake_assert_init + comment), shifting every site by +3
+lines exactly; the validation harness maps base coordinates accordingly.
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+WAKE = HERE.parent
+ART = HERE / "denominator-089615f.json"
+
+RX_GREP_TOKEN = re.compile(r"(^|[^A-Za-z0-9_.-])grep([^A-Za-z0-9_.-]|$)")
+
+HEADER = [
+    "# #973: three-valued grep assertion helpers (has_match/count_lines); init saves real stderr for abort loudness.\n",
+    "# shellcheck disable=SC1091\n",
+    '. "$SCRIPT_DIR/_wake-common.sh" && wake_assert_init\n',
+]
+
+MULTI_GREP_CONVERT_BOTH = {
+    ("test-wake-digest-quarantine.sh", 560),
+    ("test-wake-install.sh", 420),
+}
+
+SUMMARY_TEMPLATE_MARK = '$(grep -c . "$FAILFILE")'
+
+
+def verify(row, actual):
+    a = actual.strip()
+    t = row["text"].strip()
+    if a == t:
+        return True
+    if t and a.startswith(t):  # artifact-side truncation
+        return True
+    # normalized suite-summary template rows
+    if t.startswith('echo "wake ') and SUMMARY_TEMPLATE_MARK in actual and a.startswith('echo "wake '):
+        return True
+    return False
+
+
+def convert_line(row, line):
+    key = (row["file"], row["line"])
+    n_grep = len(RX_GREP_TOKEN.findall(line))
+    if key in MULTI_GREP_CONVERT_BOTH:
+        assert n_grep == 2, f"{key}: expected 2 grep tokens, found {n_grep}"
+    else:
+        assert n_grep == 1, f"{key}: expected 1 grep token, found {n_grep}: {line!r}"
+
+    if row["form"].startswith("E"):
+        assert line.count("grep -c ") == 1, f"{key}: E row without single 'grep -c ': {line!r}"
+        return line.replace("grep -c ", "count_lines ", 1)
+
+    def repl(m):
+        return m.group(1) + "has_match" + m.group(2)
+
+    count = 2 if key in MULTI_GREP_CONVERT_BOTH else 1
+    return RX_GREP_TOKEN.sub(repl, line, count=count)
+
+
+def main():
+    art = json.loads(ART.read_text())
+    rows = art["rows"]
+    by_file = {}
+    for r in rows:
+        by_file.setdefault(r["file"], []).append(r)
+
+    # pass 1: verify every row before touching any file
+    bad = 0
+    texts = {}
+    for f, frs in by_file.items():
+        lines = (WAKE / f).read_text().split("\n")
+        texts[f] = lines
+        for r in frs:
+            if not verify(r, lines[r["line"] - 1]):
+                bad += 1
+                print(f"VERIFY-FAIL {f}:{r['line']}\n  artifact: {r['text']!r}\n  worktree: {lines[r['line'] - 1]!r}")
+    if bad:
+        sys.exit(f"ABORT: {bad} row(s) failed verification; nothing was modified.")
+
+    # pass 2: convert + insert header
+    total = {"has_match": 0, "count_lines": 0}
+    for f, frs in sorted(by_file.items()):
+        lines = texts[f]
+        for r in frs:
+            i = r["line"] - 1
+            new = convert_line(r, lines[i])
+            assert new != lines[i], f"{f}:{r['line']}: no-op conversion"
+            lines[i] = new
+            total["count_lines" if r["form"].startswith("E") else "has_match"] += 1
+        # header insertion after the SCRIPT_DIR= line
+        sd = [i for i, ln in enumerate(lines) if ln.startswith('SCRIPT_DIR="$(')]
+        assert len(sd) == 1, f"{f}: expected exactly one SCRIPT_DIR line, found {len(sd)}"
+        first_site = min(r["line"] for r in frs) - 1
+        assert sd[0] < first_site, f"{f}: SCRIPT_DIR line {sd[0] + 1} not before first site {first_site + 1}"
+        lines[sd[0] + 1 : sd[0] + 1] = [h.rstrip("\n") for h in HEADER]
+        (WAKE / f).write_text("\n".join(lines))
+        print(f"{f}: {len(frs)} sites converted, header at line {sd[0] + 2}")
+
+    print(f"TOTAL: {total['has_match']} has_match + {total['count_lines']} count_lines = {sum(total.values())} sites in {len(by_file)} files")
+    assert sum(total.values()) == art["total"] == 261, "site count mismatch vs artifact"
+
+
+if __name__ == "__main__":
+    main()

packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh

@@ -0,0 +1,299 @@
+#!/usr/bin/env bash
+# microtest-wake-assert.sh — #973 instrument self-test. Run BEFORE trusting any
+# validate-run evidence: it proves the counted ledger and the abort mechanics on
+# two generated mini-suites, so a defect in the instrument cannot silently wear
+# the colour of a clean validation.
+#
+# What it proves (each check named C1..C8 below):
+#   C1  green run: ledger set EQUALS a text-derived expected set spanning TWO
+#       files (file-field discrimination), row count > 1, both sentinels emitted,
+#       exit 0. Also pins the BASH_LINENO convention for backslash-continuation
+#       call sites against the first-physical-line convention the denominator
+#       artifact uses.
+#   C2  early-exit truncation: a suite that exits before its later site yields a
+#       SHORT ledger, and the expected-set comparison catches it — a counted
+#       ledger must report its own truncation, never a smaller total.
+#   C3  abort from inside a `( ... )` test subshell kills the WHOLE suite: no
+#       sentinel, non-zero exit, loud named reason (file:line + raw rc).
+#   C4  abort stays loud at a call site that appends 2>/dev/null (the preimage
+#       canary shape) — the saved-fd path.
+#   C5  abort escapes a `$( count_lines ... )` substitution (A6 shape): the
+#       count from a failed measurement is never compared and the suite dies.
+#   C6  abort escapes a pipeline tail (`printf | has_match`).
+#   C7  count_lines prints 0 on grep rc 1 (zero matches is a measurement, not an
+#       error) — implicit in C1's green run via the delta-count site.
+#   C8  an env-prefix on the helper (`LC_ALL=C has_match ...`) reaches the grep
+#       child — pins the conversion shape for the digest-hmac LC_ALL site.
+#   C9  an arm that matches NO site is loud about it by omission: green run,
+#       sentinel present, and NO "WAKE-ASSERT ARMED" line — so "did not abort"
+#       is separable into arm-never-matched (no ARMED line) vs error-path-
+#       broken (ARMED line, no abort). C3..C6 require the ARMED line AND the
+#       aborting site's ledger row (append lands BEFORE the grep runs, so an
+#       abort can never shorten the count it is part of).
+#   C10 the BASH_LINENO pin's abort arm fires: under a probe interpreter that
+#       misreports the continuation line, wake_assert_init aborts loudly and
+#       nothing past init executes — a pin whose failure arm was never seen
+#       firing is an undertaking, not a control.
+#   C11 the FAILED-summary template executes on the red path: a mini-suite
+#       driven deterministically red emits the exact converted summary shape
+#       (`FAILED ($(count_lines . "$FAILFILE") assertion(s))`) with the right
+#       count, exits 1, and the summary site's ledger row lands. The nine
+#       real-suite summary sites are structurally unreachable in a green run
+#       (guarded by [ -s "$FAILFILE" ]); their dispositions cite THIS check as
+#       the measured execution of the same template, so "unexecuted in the
+#       green run" never silently means "never executed anywhere".
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+export WAKE_COMMON="$HERE/../_wake-common.sh"
+[ -f "$WAKE_COMMON" ] || {
+  echo "microtest: _wake-common.sh not found at $WAKE_COMMON" >&2
+  exit 1
+}
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+fails=0
+check() { # check NAME COND-DESCRIPTION (pass/fail already decided by caller: $1=name $2=0|1 $3=detail)
+  if [ "$2" -eq 0 ]; then
+    echo "  PASS $1"
+  else
+    echo "  FAIL $1 — $3"
+    fails=$((fails + 1))
+  fi
+}
+
+# --- fixture data ----------------------------------------------------------
+printf 'alpha\nbeta\nbeta\ngamma-unused\n' >"$TMP/data.txt"
+
+# --- mini-suite A: six helper sites across every converted form ------------
+cat >"$TMP/mini-a.sh" <<'MINI_A'
+#!/usr/bin/env bash
+set -uo pipefail
+. "$WAKE_COMMON"
+wake_assert_init
+TMP="$1"
+FAILFILE="$TMP/failures-a"
+: >"$FAILFILE"
+fail_msg() { echo "  FAIL: $*" >&2; echo x >>"$FAILFILE"; }
+ok() { :; }
+(
+  has_match -q alpha "$TMP/data.txt" || fail_msg "alpha missing" # SITE:or-subshell
+) && ok
+(
+  has_match -q FORBIDDEN "$TMP/data.txt" 2>/dev/null && fail_msg "forbidden present" # SITE:and-swallow
+) && ok
+(
+  [ "$(count_lines beta "$TMP/data.txt")" = "2" ] || fail_msg "beta count" # SITE:count-capture
+) && ok
+(
+  printf 'gamma\n' | has_match -q gamma || fail_msg "gamma pipeline" # SITE:pipeline
+) && ok
+(
+  has_match -q \
+    alpha "$TMP/data.txt" || fail_msg "continuation" # SITE:continuation
+) && ok
+(
+  [ "$(count_lines delta "$TMP/data.txt")" = "0" ] || fail_msg "delta zero" # SITE:count-zero
+) && ok
+if [ -s "$FAILFILE" ]; then
+  echo "mini-a: FAILED" >&2
+  exit 1
+fi
+echo "mini-a: OK" >&2
+MINI_A
+
+# --- mini-suite B: second file, one site behind an early exit --------------
+cat >"$TMP/mini-b.sh" <<'MINI_B'
+#!/usr/bin/env bash
+set -uo pipefail
+. "$WAKE_COMMON"
+wake_assert_init
+TMP="$1"
+(
+  has_match -q alpha "$TMP/data.txt" || echo "b1 missing" >&2 # SITE:b-first
+)
+if [ "${MINI_B_EARLY_EXIT:-}" = "1" ]; then
+  exit 0
+fi
+(
+  has_match -q beta "$TMP/data.txt" || echo "b2 missing" >&2 # SITE:b-second
+)
+echo "mini-b: OK" >&2
+MINI_B
+chmod +x "$TMP/mini-a.sh" "$TMP/mini-b.sh"
+
+# Text-derived expected set: helper-name + basename:line for every SITE-marked
+# call, taken from the generated files' TEXT (independent of BASH_LINENO), with
+# the continuation site expected at its FIRST physical line — the denominator
+# artifact's convention.
+expected_set() { # expected_set FILE
+  local f="$1" base
+  base="$(basename "$f")"
+  awk '
+    /# SITE:/ {
+      line = NR
+      if ($0 !~ /has_match|count_lines/) line = NR - 1  # marker on the continuation tail
+      print line
+    }
+  ' "$f" | while read -r ln; do
+    txt="$(sed -n "${ln}p" "$f")"
+    case "$txt" in
+    *count_lines*) printf 'count_lines %s:%s\n' "$base" "$ln" ;;
+    *) printf 'has_match %s:%s\n' "$base" "$ln" ;;
+    esac
+  done
+}
+
+site_line() { # site_line FILE MARKER -> first physical line of that call
+  local f="$1" marker="$2" ln
+  ln="$(grep -n "# SITE:${marker}\$" "$f" | cut -d: -f1)"
+  # continuation marker sits on the tail line; the call starts one line up
+  if ! sed -n "${ln}p" "$f" | grep -Eq 'has_match|count_lines'; then
+    ln=$((ln - 1))
+  fi
+  printf '%s' "$ln"
+}
+
+# --- C1: green run, two files, set equality --------------------------------
+LEDGER="$TMP/ledger-c1"
+: >"$LEDGER"
+outA="$(WAKE_ASSERT_LEDGER="$LEDGER" bash "$TMP/mini-a.sh" "$TMP" 2>&1)"
+rcA=$?
+outB="$(WAKE_ASSERT_LEDGER="$LEDGER" bash "$TMP/mini-b.sh" "$TMP" 2>&1)"
+rcB=$?
+{ expected_set "$TMP/mini-a.sh"; expected_set "$TMP/mini-b.sh"; } | sort >"$TMP/expected-c1"
+sort "$LEDGER" >"$TMP/got-c1"
+n_expected="$(grep -c . "$TMP/expected-c1")"
+if [ "$rcA" -eq 0 ] && [ "$rcB" -eq 0 ] &&
+  printf '%s' "$outA" | grep -q 'mini-a: OK' &&
+  printf '%s' "$outB" | grep -q 'mini-b: OK' &&
+  [ "$n_expected" -gt 1 ] &&
+  cmp -s "$TMP/expected-c1" "$TMP/got-c1"; then
+  check C1 0 ""
+else
+  check C1 1 "rcA=$rcA rcB=$rcB expected($n_expected)/got diff: $(diff "$TMP/expected-c1" "$TMP/got-c1" 2>&1 | head -n 10 | tr '\n' ' ')"
+fi
+
+# --- C2: early exit -> short ledger, comparison catches it -----------------
+LEDGER="$TMP/ledger-c2"
+: >"$LEDGER"
+WAKE_ASSERT_LEDGER="$LEDGER" MINI_B_EARLY_EXIT=1 bash "$TMP/mini-b.sh" "$TMP" >/dev/null 2>&1
+expected_set "$TMP/mini-b.sh" | sort >"$TMP/expected-c2"
+sort "$LEDGER" >"$TMP/got-c2"
+if ! cmp -s "$TMP/expected-c2" "$TMP/got-c2" &&
+  grep -q "has_match mini-b.sh:$(site_line "$TMP/mini-b.sh" b-first)" "$TMP/got-c2" &&
+  ! grep -q "mini-b.sh:$(site_line "$TMP/mini-b.sh" b-second)" "$TMP/got-c2"; then
+  check C2 0 ""
+else
+  check C2 1 "truncated ledger was not detected as short"
+fi
+
+# --- C3..C6: per-shape abort proofs ----------------------------------------
+abort_case() { # abort_case NAME MARKER HELPER
+  local name="$1" marker="$2" helper="$3" ln site out rc ledger
+  ln="$(site_line "$TMP/mini-a.sh" "$marker")"
+  site="mini-a.sh:${ln}"
+  ledger="$TMP/ledger-${name}"
+  : >"$ledger"
+  out="$(WAKE_ASSERT_LEDGER="$ledger" WAKE_ASSERT_FORCE_GREP_ERROR_AT="$site" \
+    bash "$TMP/mini-a.sh" "$TMP" 2>&1)"
+  rc=$?
+  if [ "$rc" -ne 0 ] &&
+    ! printf '%s' "$out" | grep -q 'mini-a: OK' &&
+    ! printf '%s' "$out" | grep -q 'mini-a: FAILED' &&
+    printf '%s' "$out" | grep -q "WAKE-ASSERT ARMED: forcing real grep error at $site" &&
+    printf '%s' "$out" | grep -q "WAKE-ASSERT ABORT" &&
+    printf '%s' "$out" | grep -q "$site" &&
+    printf '%s' "$out" | grep -q "grep exit 2" &&
+    grep -q "^${helper} ${site}\$" "$ledger"; then
+    check "$name" 0 ""
+  else
+    check "$name" 1 "rc=$rc site=$site ledger=$(grep -c . "$ledger") out=$(printf '%s' "$out" | tail -n 3 | tr '\n' ' ')"
+  fi
+}
+abort_case C3 or-subshell has_match
+abort_case C4 and-swallow has_match
+abort_case C5 count-capture count_lines
+abort_case C6 pipeline has_match
+
+# --- C7: covered by C1 (delta-count site prints 0 on grep rc 1) ------------
+check C7 0 ""
+
+# --- C8: env-prefix on a function reaches the grep child -------------------
+envprobe() { command env | command grep -c '^LC_ALL=xx_wake_test$'; }
+got="$(LC_ALL=xx_wake_test envprobe 2>/dev/null)" # bash's setlocale warning about the fake locale is itself proof the prefix landed
+if [ "$got" = "1" ]; then check C8 0 ""; else check C8 1 "env-prefix did not reach child (got=$got)"; fi
+
+# --- C9: arm matching NO site -> green run, no ARMED line ------------------
+out="$(WAKE_ASSERT_FORCE_GREP_ERROR_AT="mini-a.sh:9999" bash "$TMP/mini-a.sh" "$TMP" 2>&1)"
+rc=$?
+if [ "$rc" -eq 0 ] &&
+  printf '%s' "$out" | grep -q 'mini-a: OK' &&
+  ! printf '%s' "$out" | grep -q 'WAKE-ASSERT ARMED'; then
+  check C9 0 ""
+else
+  check C9 1 "rc=$rc out=$(printf '%s' "$out" | tail -n 3 | tr '\n' ' ')"
+fi
+
+# --- C10: lineno pin aborts under an interpreter that breaks the convention -
+cat >"$TMP/fake-bash" <<'FAKE'
+#!/usr/bin/env bash
+# stand-in for a bash whose BASH_LINENO convention differs: misreports the
+# continuation call one line low (the exact skew the pin exists to catch)
+printf '3\n5\n'
+FAKE
+chmod +x "$TMP/fake-bash"
+out="$(WAKE_ASSERT_PIN_BASH="$TMP/fake-bash" bash -c '. "$WAKE_COMMON" && wake_assert_init && echo REACHED-PAST-INIT' 2>&1)"
+rc=$?
+if [ "$rc" -ne 0 ] &&
+  ! printf '%s' "$out" | grep -q 'REACHED-PAST-INIT' &&
+  printf '%s' "$out" | grep -q 'WAKE-ASSERT INIT ABORT: BASH_LINENO convention violated'; then
+  check C10 0 ""
+else
+  check C10 1 "rc=$rc out=$(printf '%s' "$out" | tail -n 2 | tr '\n' ' ')"
+fi
+
+# --- C11: red path executes the converted FAILED-summary template -----------
+cat >"$TMP/mini-c.sh" <<'MINI_C'
+#!/usr/bin/env bash
+set -uo pipefail
+. "$WAKE_COMMON"
+wake_assert_init
+TMP="$1"
+FAILFILE="$TMP/failures-c"
+: >"$FAILFILE"
+fail_msg() { echo "  FAIL: $*" >&2; echo x >>"$FAILFILE"; }
+ok() { :; }
+(
+  has_match -q alpha "$TMP/data.txt" && fail_msg "alpha present" # SITE:c-inverted (deterministically red: alpha IS in the fixture)
+) && ok
+echo
+if [ -s "$FAILFILE" ]; then
+  echo "wake mini-c harness: FAILED ($(count_lines . "$FAILFILE") assertion(s))" >&2 # SITE:c-summary
+  exit 1
+fi
+echo "wake mini-c harness: all invariants passed (1 group)"
+MINI_C
+chmod +x "$TMP/mini-c.sh"
+LEDGER="$TMP/ledger-c11"
+: >"$LEDGER"
+out="$(WAKE_ASSERT_LEDGER="$LEDGER" bash "$TMP/mini-c.sh" "$TMP" 2>&1)"
+rc=$?
+summary_ln="$(site_line "$TMP/mini-c.sh" c-summary)"
+if [ "$rc" -eq 1 ] &&
+  printf '%s' "$out" | grep -q 'wake mini-c harness: FAILED (1 assertion(s))' &&
+  ! printf '%s' "$out" | grep -q 'all invariants passed' &&
+  grep -q "^count_lines mini-c.sh:${summary_ln}\$" "$LEDGER"; then
+  check C11 0 ""
+else
+  check C11 1 "rc=$rc summary_ln=$summary_ln ledger=$(tr '\n' ' ' <"$LEDGER") out=$(printf '%s' "$out" | tail -n 2 | tr '\n' ' ')"
+fi
+
+echo
+if [ "$fails" -gt 0 ]; then
+  echo "microtest-wake-assert: FAILED ($fails check(s))" >&2
+  exit 1
+fi
+echo "microtest-wake-assert: OK (all checks passed)"

packages/mosaic/framework/tools/wake/validate-973/unexecuted-sites-dispositions.txt

@@ -0,0 +1,37 @@
+# unexecuted-sites-dispositions.txt — #973 validation, amendment ONE leg 3.
+#
+# The ledger is an execution trace, not an inventory: a green instrumented run
+# cannot execute a site that only lives on a suite's red path. Every converted
+# site that did NOT appear in the green-run trace is enumerated here with an
+# individual disposition; validate-973.sh fails if any unexecuted site lacks a
+# row here, and ALSO fails if a row here names a site that DID execute (stale
+# disposition). Key = first two whitespace-separated fields; text after "—" is
+# the adjudication.
+#
+# All nine sites below are the same structural shape, adjudicated one by one
+# from source text: the suite's FAILED-branch summary line,
+#   echo "wake <name> harness: FAILED ($(count_lines . "$FAILFILE") assertion(s))" >&2
+# guarded by `if [ -s "$FAILFILE" ]` — structurally unreachable while every
+# assertion passes, which is precisely the state a green validation run is
+# required to be in. (The tenth suite, test-wake-preimage.sh, uses its own
+# X/Y summary format with no grep in the red branch, so it has no row here.)
+#
+# The disposition is NOT "it would work": the exact template is EXECUTED red
+# in microtest C11 (deterministically failed mini-suite, same
+# count_lines-in-substitution summary shape → right count, exit 1, ledger row
+# at the summary coordinate), and the E-in-substitution abort path is proven
+# by microtest C5 plus the forced-error arm at test-wake-store-ack.sh:736.
+# Each site's conversion text is independently verified by the static
+# inventory (check-973.py static == expected, all 261 rows).
+#
+# Verified guard per site (line numbers at branch tip, +3 header shift):
+
+count_lines test-wake-beacon.sh:354 — red-path summary; guard `[ -s "$FAILFILE" ]` at line 353; template execution measured by microtest C11; text verified by static inventory
+count_lines test-wake-detector.sh:706 — red-path summary; guard `[ -s "$FAILFILE" ]` at line 705; template execution measured by microtest C11; text verified by static inventory
+count_lines test-wake-digest-hmac.sh:438 — red-path summary; guard `[ -s "$FAILFILE" ]` at line 437; template execution measured by microtest C11; text verified by static inventory
+count_lines test-wake-digest-quarantine.sh:588 — red-path summary; guard `[ -s "$FAILFILE" ]` at line 587; template execution measured by microtest C11; text verified by static inventory
+count_lines test-wake-fn-oracle.sh:136 — red-path summary; guard `[ -s "$FAILFILE" ]` at line 135; template execution measured by microtest C11; text verified by static inventory
+count_lines test-wake-install.sh:438 — red-path summary; guard `[ -s "$FAILFILE" ]` at line 437; template execution measured by microtest C11; text verified by static inventory
+count_lines test-wake-reconcile.sh:393 — red-path summary; guard `[ -s "$FAILFILE" ]` at line 392; template execution measured by microtest C11; text verified by static inventory
+count_lines test-wake-store-ack.sh:745 — red-path summary; guard `[ -s "$FAILFILE" ]` at line 744; template execution measured by microtest C11; text verified by static inventory
+count_lines test-wake-store-enqueue-race.sh:212 — red-path summary (with "#927 TOCTOU reproduced (RED)" tail); guard `[ -s "$FAILFILE" ]` at line 211; template execution measured by microtest C11; text verified by static inventory

packages/mosaic/framework/tools/wake/validate-973/validate-973.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+# validate-973.sh — #973 validation driver. One run produces the complete
+# evidence chain for the 261-site conversion:
+#
+#   0. instrument self-test (microtest) — no validate evidence is trusted
+#      before the instrument itself has been proven, including its abort arms.
+#   1. expected set: 261 coordinates from the FROZEN artifact (+7 header
+#      shift: 3 converter lines + 4 #984 guard lines), count asserted against the number declared below BEFORE any
+#      suite runs.
+#   2. static inventory: converted call sites re-derived from SOURCE TEXT,
+#      must equal the expected set exactly (amendment ONE, leg 1 — the
+#      inventory comes from the text, never from the ledger).
+#   3. green instrumented run: all ten suites with WAKE_ASSERT_LEDGER; each
+#      must exit 0 AND emit its own sentinel (per-suite formats differ and are
+#      pinned here — a suite that died early must never pass on another
+#      suite's output).
+#   4. trace arithmetic on coordinate SETS (loops re-execute sites and the
+#      multi-grep lines append twice per pass, so counts are meaningless;
+#      sets are not):
+#        trace − expected  MUST be empty (a helper ran at a coordinate the
+#                          denominator never measured);
+#        expected − trace  = converted-but-never-executed: enumerated, and
+#                          every entry must carry a disposition in the
+#                          committed unexecuted-sites-dispositions.txt, with
+#                          no stale dispositions the other way (amendment
+#                          ONE, legs 2+3 — the ledger is an execution trace,
+#                          not an inventory; the difference is enumerated and
+#                          individually dispositioned, never silently absent).
+#   5. forced-error arms: the 19 denominator canaries plus one E-form and one
+#      F-form site, each run with WAKE_ASSERT_FORCE_GREP_ERROR_AT: the suite
+#      must emit the ARMED line (the arm proved it fired), the ABORT line
+#      naming the site, exit non-zero, emit NO sentinel, and the aborting
+#      site's ledger row must already be present (the append lands before the
+#      grep).
+#   6. residual sweep: the denominator's own classifier finds zero unconverted
+#      verdict greps in the suites — and eight plants (six per-form + two
+#      absorb-branch probes, #985) in the same run.
+#
+# Output discipline (A10): every line that reports on a suite names the file
+# under test; exit codes are reported before failure counts.
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WAKE="$(cd "$HERE/.." && pwd)"
+CHECK="$HERE/check-973.py"
+DISPO="$HERE/unexecuted-sites-dispositions.txt"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+# Declared BEFORE any suite runs (A2): the run must produce THESE numbers,
+# not be described by whatever numbers it produced.
+EXPECTED_SUITES=10
+EXPECTED_SITES=261
+EXPECTED_ARMS=21
+
+fails=0
+flag() {
+  printf 'FAIL %s\n' "$*"
+  fails=$((fails + 1))
+}
+
+SUITES=(
+  test-wake-beacon.sh
+  test-wake-detector.sh
+  test-wake-digest-hmac.sh
+  test-wake-digest-quarantine.sh
+  test-wake-fn-oracle.sh
+  test-wake-install.sh
+  test-wake-preimage.sh
+  test-wake-reconcile.sh
+  test-wake-store-ack.sh
+  test-wake-store-enqueue-race.sh
+)
+[ "${#SUITES[@]}" -eq "$EXPECTED_SUITES" ] ||
+  flag "suite list has ${#SUITES[@]} entries, declared $EXPECTED_SUITES"
+
+# Per-suite sentinel patterns, pinned: nine suites share the harness template
+# (enqueue-race appends a tail after it); preimage uses its own format.
+sentinel_for() {
+  case "$1" in
+  test-wake-preimage.sh) printf '%s' '^== test-wake-preimage: 17/17 passed ==$' ;;
+  *) printf '%s' 'harness: all invariants passed' ;;
+  esac
+}
+
+# --- 0: instrument self-test ------------------------------------------------
+if bash "$HERE/microtest-wake-assert.sh" >"$TMP/microtest.out" 2>&1; then
+  echo "MICROTEST microtest-wake-assert.sh exit=0 (instrument proven)"
+else
+  rc=$?
+  echo "MICROTEST microtest-wake-assert.sh exit=$rc"
+  sed 's/^/  /' "$TMP/microtest.out" | tail -n 15
+  flag "instrument self-test failed — no validate evidence below is trustworthy"
+fi
+
+# --- 1+2: expected set (artifact) vs static inventory (source text) ---------
+python3 "$CHECK" expected | sort >"$TMP/expected.txt" ||
+  flag "check-973.py expected failed"
+n_expected="$(grep -c . "$TMP/expected.txt")"
+echo "EXPECTED-SET $n_expected coordinates (declared: $EXPECTED_SITES)"
+[ "$n_expected" -eq "$EXPECTED_SITES" ] ||
+  flag "expected set has $n_expected coordinates, declared $EXPECTED_SITES"
+
+python3 "$CHECK" static | sort >"$TMP/static.txt" ||
+  flag "check-973.py static failed"
+if cmp -s "$TMP/expected.txt" "$TMP/static.txt"; then
+  echo "STATIC-INVENTORY equals expected set ($(grep -c . "$TMP/static.txt") rows from source text)"
+else
+  flag "static inventory (source text) differs from expected set (artifact):"
+  diff "$TMP/expected.txt" "$TMP/static.txt" | head -n 20 | sed 's/^/  /'
+fi
+
+# --- 3: green instrumented run ----------------------------------------------
+LEDGER="$TMP/ledger"
+: >"$LEDGER"
+for s in "${SUITES[@]}"; do
+  out="$(WAKE_ASSERT_LEDGER="$LEDGER" bash "$WAKE/$s" 2>&1)"
+  rc=$?
+  if printf '%s\n' "$out" | grep -Eq "$(sentinel_for "$s")"; then
+    sent="present"
+  else
+    sent="ABSENT"
+  fi
+  echo "SUITE $s exit=$rc sentinel=$sent"
+  [ "$rc" -eq 0 ] || flag "$s exited $rc in the green instrumented run"
+  [ "$sent" = "present" ] || flag "$s did not emit its sentinel"
+done
+
+# --- 4: trace arithmetic on coordinate sets ---------------------------------
+sort -u "$LEDGER" >"$TMP/trace.txt"
+echo "TRACE $(grep -c . "$TMP/trace.txt") distinct coordinates from $(grep -c . "$LEDGER") ledger rows"
+
+comm -13 "$TMP/expected.txt" "$TMP/trace.txt" >"$TMP/rogue.txt"
+if [ -s "$TMP/rogue.txt" ]; then
+  flag "trace contains coordinates OUTSIDE the frozen denominator:"
+  sed 's/^/  ROGUE /' "$TMP/rogue.txt"
+else
+  echo "TRACE-MINUS-EXPECTED empty (no helper ran at an unmeasured coordinate)"
+fi
+
+comm -23 "$TMP/expected.txt" "$TMP/trace.txt" >"$TMP/unexec.txt"
+n_unexec="$(grep -c . "$TMP/unexec.txt" || true)"
+echo "UNEXECUTED $n_unexec of $EXPECTED_SITES converted sites did not execute in the green run"
+if [ ! -f "$DISPO" ]; then
+  flag "disposition file missing: $DISPO — every unexecuted site must be individually dispositioned"
+  sed 's/^/  UNDISPOSITIONED /' "$TMP/unexec.txt"
+else
+  awk '!/^#/ && NF >= 2 {print $1, $2}' "$DISPO" | sort -u >"$TMP/dispo-keys.txt"
+  comm -23 "$TMP/unexec.txt" "$TMP/dispo-keys.txt" >"$TMP/undispo.txt"
+  comm -13 "$TMP/unexec.txt" "$TMP/dispo-keys.txt" >"$TMP/stale-dispo.txt"
+  if [ -s "$TMP/undispo.txt" ]; then
+    flag "unexecuted sites WITHOUT a disposition:"
+    sed 's/^/  UNDISPOSITIONED /' "$TMP/undispo.txt"
+  fi
+  if [ -s "$TMP/stale-dispo.txt" ]; then
+    flag "dispositions for sites that DID execute (stale — the file no longer matches the run):"
+    sed 's/^/  STALE-DISPO /' "$TMP/stale-dispo.txt"
+  fi
+  if [ ! -s "$TMP/undispo.txt" ] && [ ! -s "$TMP/stale-dispo.txt" ]; then
+    echo "DISPOSITIONS all $n_unexec unexecuted sites individually dispositioned, none stale"
+  fi
+fi
+
+# --- 5: forced-error arms ---------------------------------------------------
+python3 "$CHECK" arms >"$TMP/arms.txt" || flag "check-973.py arms failed"
+n_arms="$(grep -c . "$TMP/arms.txt")"
+echo "ARMS $n_arms forced-error arms (declared: $EXPECTED_ARMS)"
+[ "$n_arms" -eq "$EXPECTED_ARMS" ] ||
+  flag "arm list has $n_arms entries, declared $EXPECTED_ARMS"
+
+while read -r helper site form; do
+  f="${site%%:*}"
+  aled="$TMP/ledger-arm"
+  : >"$aled"
+  out="$(WAKE_ASSERT_LEDGER="$aled" WAKE_ASSERT_FORCE_GREP_ERROR_AT="$site" \
+    bash "$WAKE/$f" 2>&1)"
+  rc=$?
+  bad=""
+  [ "$rc" -ne 0 ] || bad="$bad exit=0"
+  printf '%s\n' "$out" | grep -q "WAKE-ASSERT ARMED: forcing real grep error at $site" ||
+    bad="$bad no-ARMED-line"
+  printf '%s\n' "$out" | grep -q "WAKE-ASSERT ABORT: ${helper} at ${site}: grep exit" ||
+    bad="$bad no-ABORT-line"
+  # AND-polarity check (a match is the defect): a grep error (rc>=2) must be
+  # its own loud arm — it cannot fall through as "no sentinel = pass".
+  rc_sent=0
+  printf '%s\n' "$out" | grep -Eq "$(sentinel_for "$f")" || rc_sent=$?
+  case "$rc_sent" in
+  0) bad="$bad sentinel-emitted" ;;
+  1) : ;;
+  *) bad="$bad sentinel-grep-error-rc=$rc_sent" ;;
+  esac
+  grep -q "^${helper} ${site}\$" "$aled" ||
+    bad="$bad no-ledger-row"
+  if [ -z "$bad" ]; then
+    echo "ARM $site ($form) exit=$rc armed+abort+no-sentinel+ledger-row"
+  else
+    echo "ARM $site ($form) exit=$rc DEFECTS:$bad"
+    flag "arm $site ($form) failed:$bad"
+  fi
+done <"$TMP/arms.txt"
+
+# --- 6: residual sweep ------------------------------------------------------
+if python3 "$CHECK" sweep >"$TMP/sweep.out" 2>&1; then
+  echo "SWEEP exit=0"
+else
+  echo "SWEEP exit=$?"
+  flag "residual sweep failed"
+fi
+sed 's/^/  /' "$TMP/sweep.out"
+
+# --- summary (exit codes above, failure count last — A10) --------------------
+echo
+if [ "$fails" -gt 0 ]; then
+  echo "validate-973: FAILED ($fails failure(s))" >&2
+  exit 1
+fi
+echo "validate-973: OK — $EXPECTED_SUITES suites, $EXPECTED_SITES sites, $EXPECTED_ARMS arms, sweep clean"

packages/mosaic/package.json

@@ -25,7 +25,7 @@
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-install.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-parse.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",