fix(shell): remove runtime early-exit pipe hazards (#1105)

Co-authored-by: f10-coder <[email protected]>

docs/reports/quality/1099-pipefail-sweep.md

@@ -0,0 +1,54 @@
+# #1099 pipefail + early-exit sweep
+
+Baseline: `df4c591ab42aa1ae62c12935fdc0e772684864a0`
+
+This is a site inventory, not a risk count. `FIXED` means the early-exiting consumer no longer has a piped upstream process whose SIGPIPE can become the result under `pipefail`. `NOT-LOAD-BEARING` means the pipeline status is explicitly discarded. `UNREACHABLE-AND-WHY` describes designed input, not a payload-size safety claim.
+
+## Tranche 1 — runtime and general scripts
+
+| Baseline site | Verdict | Construction / reason |
+| --- | --- | --- |
+| `tools/matrix-presence-harness/run.sh:38` | FIXED | nullglob array selects the first path; no pipeline |
+| `tools/e2e-install-test.sh:139` | FIXED | capture help completely, then grep via redirection |
+| `tools/install.sh:312` | FIXED | NUL `mapfile` reads all roots; count != 1 reaches the named malformed-archive diagnostic |
+| `scripts/analysis/reflect-board-history.sh:76` | FIXED | capture Git history completely, then grep via redirection |
+| `scripts/analysis/reflect-git-history.sh:67` | FIXED | grep reads from a here-string |
+| `scripts/analysis/reflect-git-history.sh:69` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/authentik/user-create.sh:72` | FIXED | jq `first(...)` reads the response directly |
+| `packages/mosaic/framework/tools/git/mutate-push-guard.sh:87` | FIXED | grep `-m1` reads the file directly; downstream `cut` consumes its complete scalar output |
+| `packages/mosaic/framework/tools/orchestrator/session-resume.sh:94` | FIXED | `mapfile` plus bounded indexed loop replaces `head` pipeline |
+| `packages/mosaic/framework/tools/prdy/prdy-status.sh:69` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:172` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:173` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:174` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:175` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:176` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:177` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:178` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/qa/typecheck-hook.sh:16` | FIXED | Bash regex extracts the first field without a pipeline |
+| `packages/mosaic/framework/tools/qa/typecheck-hook.sh:56` | FIXED | grep and bounded sed each read from a here-string |
+| `packages/mosaic/framework/tools/tmux/send-message.sh:113` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/tmux/send-message.sh:124` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/wake/detector.sh:126` | FIXED | one awk reads the manifest directly and exits after the first exact key |
+| `packages/mosaic/framework/tools/wake/detector.sh:270` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/wake/detector.sh:278` | FIXED | grep reads from a here-string |
+| `packages/mosaic/framework/tools/wake/digest.sh:647` | FIXED | capture complete locator output, then select first line by parameter expansion |
+| `packages/mosaic/framework/tools/wake/reconcile.sh:149` | FIXED | one awk reads the manifest directly and exits after the first exact key |
+
+## Explicit withdrawn / non-load-bearing sites
+
+| Baseline site | Verdict | Reason |
+| --- | --- | --- |
+| `tools/install.sh:182` | NOT-LOAD-BEARING | `|| true` explicitly discards lookup status |
+| `tools/install.sh:356` | UNREACHABLE-AND-WHY | `pnpm pack` writes one matching CLI tarball into a fresh directory immediately before lookup; citation withdrawn in #1099 |
+| `tools/install.sh:357` | UNREACHABLE-AND-WHY | same fresh-directory invariant for gateway tarball; citation withdrawn in #1099 |
+| `tools/install.sh:627` | NOT-LOAD-BEARING | `|| true` explicitly discards lookup status |
+| `scripts/agent/session-start.sh:70` | NOT-LOAD-BEARING | optional scratchpad lookup has `|| true` |
+| `packages/mosaic/framework/templates/repo/scripts/agent/session-start.sh:58` | NOT-LOAD-BEARING | optional scratchpad lookup has `|| true` |
+| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:25` | UNREACHABLE-AND-WHY | withdrawn in #1099 after designed-input reachability measurement; preserved without re-litigation |
+| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:27` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
+| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:30` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
+| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:32` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
+| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:34` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
+
+Remaining test and wake-validation sites are intentionally deferred to later review-sized tranches and are not yet assigned a safety verdict here.

docs/scratchpads/1099-pipefail-sweep.md

@@ -0,0 +1,33 @@
+# #1099 — pipefail + early-exit sweep
+
+## Scope and decisions
+
+- Baseline `df4c591ab42aa1ae62c12935fdc0e772684864a0`, after #1100 removed its 35 sites.
+- Split into review-sized non-closing tranches: runtime/general; tmux/git/quality tests; wake validation/tests.
+- Do not equate class membership with demonstrated risk. Do not use payload size or pipeline stage count as a safety proxy.
+- Preserve the issue's withdrawn findings for `qa-hook-stdin.sh` and the two fresh-directory `pnpm pack` lookups. Fix `install.sh:312` because malformed multi-root input must reach its named handler.
+
+## Tranche 1 TDD
+
+RED-first control: `node --test scripts/pipefail-early-exit.test.mjs` reported exactly 26 non-accepted runtime/general sites, including `install.sh:312`, and exited 1. A checked-in fixture generated from immutable baseline `df4c591a` records all 26 normalized sites; the control passes every fixture entry through the same scanner, asserts exact identity/count/uniqueness, and separately requires zero findings in the current tree. It also inventories accepted sites rather than silently excluding whole files.
+
+Construction choices:
+
+- here-string/file redirection for scalar grep assertions;
+- full capture then parameter expansion for first-line selection;
+- arrays/`mapfile` for complete populations;
+- direct jq/awk/grep selection where one tool can express the property;
+- no `|| true` added to a load-bearing assertion.
+
+Site-by-site verdicts: `docs/reports/quality/1099-pipefail-sweep.md`.
+
+## Verification so far
+
+- `bash -n` on every changed shell script: pass.
+- structural Node control: pass.
+- `test-mutate-push-guard.sh`: 8/8 pass.
+- `test-send-message-verdict.sh`: 3/3 pass.
+- `test-send-message-socket.sh`: pass.
+- Independent review 143 found two semantic regressions: a help-probe `|| true` changed the failure truth table, and an unguarded Git capture changed non-Git data-dir behavior from rc 0 + JSON to silent rc 128. Both received RED-first regressions before correction; help status is now separate and required, and Git status remains condition-guarded.
+- Wake detector/reconcile/digest/preimage suites terminate at their existing fail-closed #973 `BASH_LINENO` environment probe (exit 97, observed `[3 5]`, expected `[3 4]`) before subject tests. No bypass or skip was used; canonical CI remains required.
+- ShellCheck reports only pre-existing source-following, unused-variable, and untouched `ls | head` findings; no new diagnostic was introduced.

packages/mosaic/framework/tools/authentik/user-create.sh

@@ -69,7 +69,7 @@ if [[ -n "$GROUP" ]]; then
   group_response=$(curl -sk \
     -H "Authorization: Bearer $TOKEN" \
     "${AUTHENTIK_URL}/api/v3/core/groups/?search=${GROUP}")
-  group_pk=$(echo "$group_response" | jq -r ".results[] | select(.name == \"$GROUP\") | .pk" | head -1)
+  group_pk=$(jq -r "first(.results[] | select(.name == \"$GROUP\") | .pk) // empty" <<<"$group_response")
   if [[ -n "$group_pk" ]]; then
     payload=$(echo "$payload" | jq --arg gk "$group_pk" '. + {groups: [$gk]}')
   else

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

@@ -84,7 +84,7 @@ cp "$TARGET" "$BAK"
 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_LO="$(grep -n -m1 '^usage() {' "$BAK" | 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

packages/mosaic/framework/tools/orchestrator/session-resume.sh

@@ -91,10 +91,12 @@ fi
 
 if [[ -n "$dirty_files" ]]; then
   echo "  Modified files:"
-  echo "$dirty_files" | head -20 | while IFS= read -r line; do
+  mapfile -t dirty_lines <<<"$dirty_files"
-    echo "    $line"
+  file_count="${#dirty_lines[@]}"
+  display_count=$((file_count < 20 ? file_count : 20))
+  for ((i = 0; i < display_count; i++)); do
+    echo "    ${dirty_lines[$i]}"
   done
-  file_count="$(echo "$dirty_files" | wc -l)"
   if (( file_count > 20 )); then
     echo "    ... and $(( file_count - 20 )) more"
   fi

packages/mosaic/framework/tools/prdy/prdy-status.sh

@@ -66,7 +66,7 @@ present=0
 
 for entry in "${PRDY_REQUIRED_SECTIONS[@]}"; do
   pattern="${entry#*|}"
-  if echo "$PRD_CONTENT" | grep -qiE "$pattern"; then
+  if grep -qiE "$pattern" <<<"$PRD_CONTENT"; then
     present=$((present + 1))
   fi
 done

packages/mosaic/framework/tools/qa/reflect-stop-hook.sh

@@ -169,13 +169,13 @@ main() {
 # classify_surface PATH → surface name (highest-risk match wins, mirrors TS)
 classify_surface() {
   local p="$1"
-  if printf '%s' "$p" | grep -qiE 'auth|login|session|token|permission|rbac|credential|secret'; then echo auth; return; fi
+  if grep -qiE 'auth|login|session|token|permission|rbac|credential|secret' <<<"$p"; then echo auth; return; fi
-  if printf '%s' "$p" | grep -qiE 'migration|prisma|schema|\.sql|entity|repository|seed'; then echo data; return; fi
+  if grep -qiE 'migration|prisma|schema|\.sql|entity|repository|seed' <<<"$p"; then echo data; return; fi
-  if printf '%s' "$p" | grep -qiE 'docker|\.woodpecker|compose|traefik|deploy|helm|k8s|terraform'; then echo infra; return; fi
+  if grep -qiE 'docker|\.woodpecker|compose|traefik|deploy|helm|k8s|terraform' <<<"$p"; then echo infra; return; fi
-  if printf '%s' "$p" | grep -qiE 'package\.json|tsconfig|turbo\.json|pnpm-|\.config\.|eslint|vite'; then echo build; return; fi
+  if grep -qiE 'package\.json|tsconfig|turbo\.json|pnpm-|\.config\.|eslint|vite' <<<"$p"; then echo build; return; fi
-  if printf '%s' "$p" | grep -qE '\.tsx|\.css|components/|apps/web/'; then echo ui; return; fi
+  if grep -qE '\.tsx|\.css|components/|apps/web/' <<<"$p"; then echo ui; return; fi
-  if printf '%s' "$p" | grep -qE '\.spec\.|\.test\.|__tests__/'; then echo test; return; fi
+  if grep -qE '\.spec\.|\.test\.|__tests__/' <<<"$p"; then echo test; return; fi
-  if printf '%s' "$p" | grep -qE '\.md$|docs/'; then echo docs; return; fi
+  if grep -qE '\.md$|docs/' <<<"$p"; then echo docs; return; fi
   echo none
 }
 

packages/mosaic/framework/tools/qa/typecheck-hook.sh

@@ -13,7 +13,12 @@ JSON_INPUT=$(cat)
 if command -v jq &>/dev/null; then
   FILE_PATH=$(echo "$JSON_INPUT" | jq -r '.tool_input.file_path // .tool_response.filePath // .file_path // empty' 2>/dev/null || echo "")
 else
-  FILE_PATH=$(echo "$JSON_INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"\([^"]*\)"$/\1/' | head -1)
+  file_path_pattern='"file_path"[[:space:]]*:[[:space:]]*"([^"]*)"'
+  if [[ "$JSON_INPUT" =~ $file_path_pattern ]]; then
+    FILE_PATH="${BASH_REMATCH[1]}"
+  else
+    FILE_PATH=""
+  fi
 fi
 
 # Only check TypeScript files
@@ -53,7 +58,7 @@ OUTPUT=$(npx tsc --noEmit --pretty --maxNodeModuleJsDepth 0 2>&1) || STATUS=$?
 if [ "${STATUS:-0}" -ne 0 ]; then
   # Filter output to only show errors related to the edited file (if possible)
   BASENAME=$(basename "$FILE_PATH")
-  RELEVANT=$(echo "$OUTPUT" | grep -A2 "$BASENAME" 2>/dev/null || echo "$OUTPUT" | head -20)
+  RELEVANT=$(grep -A2 "$BASENAME" <<<"$OUTPUT" 2>/dev/null || sed -n '1,20p' <<<"$OUTPUT")
 
   echo "TypeScript type errors detected after editing $FILE_PATH:"
   echo "$RELEVANT"

packages/mosaic/framework/tools/tmux/send-message.sh

@@ -110,7 +110,7 @@ for attempt in $(seq 1 $((RETRIES + 1))); do
   sleep 1.2
   pane=$("${tmux_cmd[@]}" capture-pane -t "$EFFECTIVE_TARGET" -p 2>/dev/null)
 
-  if printf '%s' "$pane" | grep -qF "$QUEUED_RE"; then
+  if grep -qF "$QUEUED_RE" <<<"$pane"; then
     status="queued"; break
   fi
   # Locate the REPL input box (prompt glyph). If we cannot see it, we have NO
@@ -121,7 +121,7 @@ for attempt in $(seq 1 $((RETRIES + 1))); do
   fi
   # Input box located AND still carrying our tail => unsubmitted draft. Flush + retry.
   # (Submitted messages scroll up into history; a draft stays on the ❯ line.)
-  if [ -n "$snippet" ] && printf '%s' "$promptline" | grep -qF "$snippet"; then
+  if [ -n "$snippet" ] && grep -qF "$snippet" <<<"$promptline"; then
     status="draft"; continue
   fi
   # Input box located AND clear of our tail => positively submitted. This is the

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

@@ -123,7 +123,7 @@ _manifest_val() {
   # _manifest_val KEY — echo VALUE for KEY=VALUE in the manifest (blank if none).
   local key="$1"
   [ -f "$MANIFEST" ] || return 0
-  sed -n "s/^${key}=//p" "$MANIFEST" | head -n1 | tr -d '[:space:]'
+  awk -v key="$key" 'index($0, key "=") == 1 { sub(/^[^=]*=/, ""); gsub(/[[:space:]]/, ""); print; exit }' "$MANIFEST"
 }
 
 # _load_watchlist — validate the watch-list path + JSON + schema_version range.
@@ -267,7 +267,7 @@ _poll_source() {
     if snap_json="$(jq -ce '.' <<<"$rawmeta" 2>/dev/null)"; then
       snap_sha="$(jq -r 'if (.snapshot_sha|type) == "string" then .snapshot_sha else "" end' <<<"$snap_json")"
       snap_ts="$(jq -r 'if (.snapshot_ts|type) == "number" then (.snapshot_ts|floor|tostring) else "" end' <<<"$snap_json")"
-      if [ -n "$snap_sha" ] && ! printf '%s' "$snap_sha" | grep -Eq '^[0-9a-f]{7,64}$'; then
+      if [ -n "$snap_sha" ] && ! grep -Eq '^[0-9a-f]{7,64}$' <<<"$snap_sha"; then
         echo "detector.sh: source '$kind/$id' snapshot_sha rejected (not a 7-64 char lowercase-hex git sha) — snapshot metadata DROPPED, poll continues (#940)." >&2
         snap_sha=""
         snap_ts=""
@@ -275,7 +275,7 @@ _poll_source() {
       # A ts must be a sane positive epoch BEFORE any arithmetic touches it: a
       # negative or absurdly large value would make the shell integer comparison
       # below error out and silently KEEP the bad ts — validate first, compare after.
-      if [ -n "$snap_ts" ] && ! printf '%s' "$snap_ts" | grep -Eq '^[0-9]{1,12}$'; then
+      if [ -n "$snap_ts" ] && ! grep -Eq '^[0-9]{1,12}$' <<<"$snap_ts"; then
         echo "detector.sh: source '$kind/$id' snapshot_ts rejected (not a sane positive epoch) — snapshot_ts DROPPED, poll continues (#940)." >&2
         snap_ts=""
       fi

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

@@ -644,7 +644,8 @@ cmd_render() {
         oseq="$(jq -r '.observed_seq // "?"' <<<"$line")"
         oclass="$(jq -r '.class // "actionable"' <<<"$line")"
         oloc="$(jq -c '.locators // {}' <<<"$line")"
-        olabel="$(_locator_line "$oloc" | head -n1)"
+        olabel="$(_locator_line "$oloc")"
+        olabel="${olabel%%$'\n'*}"
         printf '  * seq %s [%s] %s\n' "$oseq" "$(_scrub_inline "$oclass")" "$olabel"
       done <<<"$pending"
     fi

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

@@ -146,7 +146,7 @@ EOF
 _manifest_val() {
   local key="$1"
   [ -f "$MANIFEST" ] || return 0
-  sed -n "s/^${key}=//p" "$MANIFEST" | head -n1 | tr -d '[:space:]'
+  awk -v key="$key" 'index($0, key "=") == 1 { sub(/^[^=]*=/, ""); gsub(/[[:space:]]/, ""); print; exit }' "$MANIFEST"
 }
 
 # _load_watchlist — validate path + JSON + shape + Gate B schema range (mirrors

scripts/analysis/reflect-board-history.sh

@@ -72,8 +72,9 @@ elif [[ -n "$DATA_DIR" ]]; then
   while IFS= read -r file; do
     [[ -z "$file" ]] && continue
     done_total=$((done_total + 1))
-    if git -C "$DATA_DIR" log --since="${WINDOW_DAYS} days ago" --pretty='%s' -- "$file" 2>/dev/null \
+    history_rc=0
-         | grep -qiE 'reopen|revert|fix|regression|wrong|incorrect|redo'; then
+    history="$(git -C "$DATA_DIR" log --since="${WINDOW_DAYS} days ago" --pretty='%s' -- "$file" 2>/dev/null)" || history_rc=$?
+    if [[ "$history_rc" -eq 0 ]] && grep -qiE 'reopen|revert|fix|regression|wrong|incorrect|redo' <<<"$history"; then
       detectable=$((detectable + 1))
     fi
   done < <(find "$DATA_DIR" -type f -name '*.json' 2>/dev/null)

scripts/analysis/reflect-git-history.sh

@@ -64,9 +64,9 @@ for line in "${LINES[@]}"; do
   #   - build/test/lint/type/ci signals → CI would have caught it
   #   - security/auth/permission/data/migration → human review would flag it
   #   - everything else (logic/UX/assumption/edge) → only-self-reflection bucket
-  if printf '%s' "$subj" | grep -qiE 'test|lint|type|build|ci|compile|typo'; then
+  if grep -qiE 'test|lint|type|build|ci|compile|typo' <<<"$subj"; then
     ci=$((ci + 1))
-  elif printf '%s' "$subj" | grep -qiE 'security|auth|permission|rbac|secret|migration|data|sql|injection'; then
+  elif grep -qiE 'security|auth|permission|rbac|secret|migration|data|sql|injection' <<<"$subj"; then
     human=$((human + 1))
   else
     selfonly=$((selfonly + 1))

scripts/fixtures/pipefail-early-exit-baseline.json

@@ -0,0 +1,28 @@
+[
+  "tools/matrix-presence-harness/run.sh:TSX_CLI=\"$(ls -d \"${REPO}\"/node_modules/.pnpm/tsx@*/node_modules/tsx/dist/cli.mjs 2>/dev/null | head -1)\"",
+  "tools/e2e-install-test.sh:if ! mosaic gateway --help 2>&1 | grep -q 'verify'; then",
+  "tools/install.sh:EXTRACTED_DIR=\"$(find \"$WORK_DIR\" -maxdepth 1 -mindepth 1 -type d | head -1)\"",
+  "scripts/analysis/reflect-board-history.sh:if git -C \"$DATA_DIR\" log --since=\"${WINDOW_DAYS} days ago\" --pretty='%s' -- \"$file\" 2>/dev/null  | grep -qiE 'reopen|revert|fix|regression|wrong|incorrect|redo'; then",
+  "scripts/analysis/reflect-git-history.sh:if printf '%s' \"$subj\" | grep -qiE 'test|lint|type|build|ci|compile|typo'; then",
+  "scripts/analysis/reflect-git-history.sh:elif printf '%s' \"$subj\" | grep -qiE 'security|auth|permission|rbac|secret|migration|data|sql|injection'; then",
+  "packages/mosaic/framework/tools/authentik/user-create.sh:group_pk=$(echo \"$group_response\" | jq -r \".results[] | select(.name == \\\"$GROUP\\\") | .pk\" | head -1)",
+  "packages/mosaic/framework/tools/git/mutate-push-guard.sh:PROSE_LO=\"$(grep -n '^usage() {' \"$BAK\" | head -1 | cut -d: -f1)\"",
+  "packages/mosaic/framework/tools/orchestrator/session-resume.sh:echo \"$dirty_files\" | head -20 | while IFS= read -r line; do",
+  "packages/mosaic/framework/tools/prdy/prdy-status.sh:if echo \"$PRD_CONTENT\" | grep -qiE \"$pattern\"; then",
+  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qiE 'auth|login|session|token|permission|rbac|credential|secret'; then echo auth; return; fi",
+  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qiE 'migration|prisma|schema|\\.sql|entity|repository|seed'; then echo data; return; fi",
+  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qiE 'docker|\\.woodpecker|compose|traefik|deploy|helm|k8s|terraform'; then echo infra; return; fi",
+  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qiE 'package\\.json|tsconfig|turbo\\.json|pnpm-|\\.config\\.|eslint|vite'; then echo build; return; fi",
+  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qE '\\.tsx|\\.css|components/|apps/web/'; then echo ui; return; fi",
+  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qE '\\.spec\\.|\\.test\\.|__tests__/'; then echo test; return; fi",
+  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qE '\\.md$|docs/'; then echo docs; return; fi",
+  "packages/mosaic/framework/tools/qa/typecheck-hook.sh:FILE_PATH=$(echo \"$JSON_INPUT\" | grep -o '\"file_path\"[[:space:]]*:[[:space:]]*\"[^\"]*\"' | sed 's/.*\"\\([^\"]*\\)\"$/\\1/' | head -1)",
+  "packages/mosaic/framework/tools/qa/typecheck-hook.sh:RELEVANT=$(echo \"$OUTPUT\" | grep -A2 \"$BASENAME\" 2>/dev/null || echo \"$OUTPUT\" | head -20)",
+  "packages/mosaic/framework/tools/tmux/send-message.sh:if printf '%s' \"$pane\" | grep -qF \"$QUEUED_RE\"; then",
+  "packages/mosaic/framework/tools/tmux/send-message.sh:if [ -n \"$snippet\" ] && printf '%s' \"$promptline\" | grep -qF \"$snippet\"; then",
+  "packages/mosaic/framework/tools/wake/detector.sh:sed -n \"s/^${key}=//p\" \"$MANIFEST\" | head -n1 | tr -d '[:space:]'",
+  "packages/mosaic/framework/tools/wake/detector.sh:if [ -n \"$snap_sha\" ] && ! printf '%s' \"$snap_sha\" | grep -Eq '^[0-9a-f]{7,64}$'; then",
+  "packages/mosaic/framework/tools/wake/detector.sh:if [ -n \"$snap_ts\" ] && ! printf '%s' \"$snap_ts\" | grep -Eq '^[0-9]{1,12}$'; then",
+  "packages/mosaic/framework/tools/wake/digest.sh:olabel=\"$(_locator_line \"$oloc\" | head -n1)\"",
+  "packages/mosaic/framework/tools/wake/reconcile.sh:sed -n \"s/^${key}=//p\" \"$MANIFEST\" | head -n1 | tr -d '[:space:]'"
+]

scripts/pipefail-early-exit.test.mjs

@@ -0,0 +1,135 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { chmod, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+const ROOT = new URL('../', import.meta.url);
+const EXPECTED_BASELINE_SITES = 26;
+const TARGETS = [
+  'tools/matrix-presence-harness/run.sh',
+  'tools/e2e-install-test.sh',
+  'tools/install.sh',
+  'scripts/agent/session-start.sh',
+  'scripts/analysis/reflect-board-history.sh',
+  'scripts/analysis/reflect-git-history.sh',
+  'packages/mosaic/framework/templates/repo/scripts/agent/session-start.sh',
+  'packages/mosaic/framework/tools/authentik/user-create.sh',
+  'packages/mosaic/framework/tools/git/mutate-push-guard.sh',
+  'packages/mosaic/framework/tools/orchestrator/session-resume.sh',
+  'packages/mosaic/framework/tools/prdy/prdy-status.sh',
+  'packages/mosaic/framework/tools/qa/reflect-stop-hook.sh',
+  'packages/mosaic/framework/tools/qa/typecheck-hook.sh',
+  'packages/mosaic/framework/tools/tmux/send-message.sh',
+  'packages/mosaic/framework/tools/wake/detector.sh',
+  'packages/mosaic/framework/tools/wake/digest.sh',
+  'packages/mosaic/framework/tools/wake/reconcile.sh',
+];
+
+// These statuses are explicitly non-load-bearing or unreachable at designed input.
+// They remain inventoried until the final #1099 tranche records every verdict.
+const ACCEPTED = [
+  ['tools/install.sh', 'mosaic-bak-', '|| true'],
+  ['tools/install.sh', 'mosaicstack-mosaic-*.tgz', 'head -1'],
+  ['tools/install.sh', 'mosaicstack-gateway-*.tgz', 'head -1'],
+  ['scripts/agent/session-start.sh', 'docs/scratchpads/*.md', '|| true'],
+  [
+    'packages/mosaic/framework/templates/repo/scripts/agent/session-start.sh',
+    'docs/scratchpads/*.md',
+    '|| true',
+  ],
+];
+
+const earlyExit =
+  /(?<!\|)\|(?!\|)[^;\n]*(?:grep\b[^;\n]*(?:-[A-Za-z]*q|--quiet|-m\s*1)|head\b(?:\s|$))/;
+
+function scan(sources) {
+  const found = [];
+  for (const [file, rawSource] of sources) {
+    const source = rawSource.replace(/\\\n\s*/g, ' ');
+    for (const rawLine of source.split('\n')) {
+      const line = rawLine.trim();
+      if (!earlyExit.test(line)) continue;
+      const accepted = ACCEPTED.some(
+        ([acceptedFile, ...fragments]) =>
+          acceptedFile === file && fragments.every((item) => line.includes(item)),
+      );
+      if (!accepted) found.push(`${file}:${line}`);
+    }
+  }
+  return found;
+}
+
+async function currentSources() {
+  return Promise.all(
+    TARGETS.map(async (file) => [file, await readFile(new URL(file, ROOT), 'utf8')]),
+  );
+}
+
+test('the registered baseline denominator is exactly 26 unsafe sites', async () => {
+  const baseline = JSON.parse(
+    await readFile(new URL('scripts/fixtures/pipefail-early-exit-baseline.json', ROOT), 'utf8'),
+  );
+  assert.equal(baseline.length, EXPECTED_BASELINE_SITES);
+  assert.equal(new Set(baseline).size, EXPECTED_BASELINE_SITES);
+  const fixtureSources = baseline.map((site) => {
+    const separator = site.indexOf(':');
+    assert.ok(separator > 0, `invalid baseline site: ${site}`);
+    return [site.slice(0, separator), site.slice(separator + 1)];
+  });
+  assert.deepEqual(scan(fixtureSources), baseline);
+});
+
+test('load-bearing pipefail paths do not pipe into early-exiting consumers', async () => {
+  assert.deepEqual(scan(await currentSources()), []);
+});
+
+test('gateway verify capability preserves the complete help-probe truth table', async () => {
+  const directory = await mkdtemp(path.join(tmpdir(), 'gateway-help-probe-'));
+  const mosaic = path.join(directory, 'mosaic');
+  const probe = new URL('tools/e2e-gateway-verify-supported.sh', ROOT).pathname;
+  try {
+    await writeFile(
+      mosaic,
+      '#!/usr/bin/env bash\nprintf \'%s\\n\' "${MOCK_HELP_OUTPUT:-}"\nexit "${MOCK_HELP_RC:-0}"\n',
+    );
+    await chmod(mosaic, 0o755);
+    const run = (rc, output) =>
+      spawnSync('bash', [probe], {
+        env: {
+          ...process.env,
+          PATH: `${directory}:${process.env.PATH}`,
+          MOCK_HELP_RC: String(rc),
+          MOCK_HELP_OUTPUT: output,
+        },
+      }).status;
+
+    assert.equal(run(0, 'commands: verify'), 0);
+    assert.equal(run(0, 'commands: install'), 1);
+    assert.equal(run(1, 'commands: verify'), 1);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test('board-history preserves non-git data-dir as a non-detectable result', async () => {
+  const directory = await mkdtemp(path.join(tmpdir(), 'reflect-board-non-git-'));
+  try {
+    await writeFile(path.join(directory, 'task.json'), '{}\n');
+    const result = spawnSync(
+      'bash',
+      [
+        new URL('scripts/analysis/reflect-board-history.sh', ROOT).pathname,
+        '--data-dir',
+        directory,
+      ],
+      { encoding: 'utf8' },
+    );
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /"done_tasks": 1/);
+    assert.match(result.stdout, /"detectable_outcomes": 0/);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});

tools/e2e-gateway-verify-supported.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Exit 0 only when the capability probe itself succeeds and advertises verify.
+# A failed help command and a successful response without verify are both
+# unsupported, matching the historical e2e-install-test.sh conditional.
+set -uo pipefail
+
+gateway_help_rc=0
+gateway_help="$(mosaic gateway --help 2>&1)" || gateway_help_rc=$?
+[[ "$gateway_help_rc" -eq 0 ]] || exit 1
+grep -q 'verify' <<<"$gateway_help"

tools/e2e-install-test.sh

@@ -136,7 +136,7 @@ fi
 echo "=== [inner] Running mosaic gateway verify ==="
 # `gateway verify` was added in feat/mosaic-first-run-ux.
 # If the installed version pre-dates this, skip gracefully.
-if ! mosaic gateway --help 2>&1 | grep -q 'verify'; then
+if ! bash /repo/tools/e2e-gateway-verify-supported.sh; then
   echo "[SKIP] 'mosaic gateway verify' not available in installed version ${INSTALLED_VERSION}."
   echo "[SKIP] This command was added in the feat/mosaic-first-run-ux release."
   echo "[SKIP] Re-run after the new version is published to validate this step."

tools/install.sh

@@ -308,13 +308,17 @@ ensure_monorepo() {
     exit 1
   fi
 
-  # Gitea archives extract to <repo-name>/ inside the work dir
+  # Gitea archives extract to exactly one <repo-name>/ inside the work dir.
-  EXTRACTED_DIR="$(find "$WORK_DIR" -maxdepth 1 -mindepth 1 -type d | head -1)"
+  # Read the complete population so a malformed multi-root archive reaches the
-  if [[ -z "$EXTRACTED_DIR" ]] || [[ ! -d "$EXTRACTED_DIR" ]]; then
+  # named diagnostic instead of aborting on an upstream SIGPIPE under pipefail.
-    fail "Could not locate extracted source in archive."
+  local -a extracted_dirs=()
+  mapfile -d '' -t extracted_dirs < <(find "$WORK_DIR" -maxdepth 1 -mindepth 1 -type d -print0)
+  if [[ "${#extracted_dirs[@]}" -ne 1 ]] || [[ ! -d "${extracted_dirs[0]:-}" ]]; then
+    fail "Could not locate exactly one extracted source directory in archive."
     ls -la "$WORK_DIR" >&2
     exit 1
   fi
+  EXTRACTED_DIR="${extracted_dirs[0]}"
 }
 
 # Build @mosaicstack/mosaic + @mosaicstack/gateway from source and install both

tools/matrix-presence-harness/run.sh

@@ -35,7 +35,10 @@ export DARK_THRESHOLD_MS="${DARK_THRESHOLD_MS:-6000}"
 export AGENT_SLUGS="${AGENT_SLUGS:-alpha,bravo,charlie}"
 export VICTIM_SLUG="${VICTIM_SLUG:-charlie}"
 
-TSX_CLI="$(ls -d "${REPO}"/node_modules/.pnpm/tsx@*/node_modules/tsx/dist/cli.mjs 2>/dev/null | head -1)"
+shopt -s nullglob
+TSX_CANDIDATES=("${REPO}"/node_modules/.pnpm/tsx@*/node_modules/tsx/dist/cli.mjs)
+shopt -u nullglob
+TSX_CLI="${TSX_CANDIDATES[0]:-}"
 if [[ -z "${TSX_CLI}" ]]; then
   echo "run.sh: tsx not found under node_modules — run pnpm install first" >&2
   exit 1