AtlatestRepositorysigil-doc
1
#!/usr/bin/env bash2
#3
# No shell script in this repository may invoke the session wrapper without4
# telling it to wait.5
#6
# WHY THIS IS A GATE AND NOT A ONE-TIME SWEEP.7
#8
# `setsid <cmd> > log` does not reliably block. util-linux forks when the setsid9
# PROCESS is itself a process-group leader and the parent returns 0 at once while10
# the child runs on. Whether that happens is a property of the CALLING SHELL, not11
# of the command: bash puts every job in its own process group when job control12
# is on, so the same line waits inside a script and does NOT wait when a human13
# runs it at an interactive prompt. Measured on this host 2026-08-22, `bash -i`14
# over a pty:15
#16
# bare exit=0 elapsed_ms=5 logbytes=017
# -w exit=0 elapsed_ms=3011 logbytes=1618
#19
# and in the `if ! ...` form the bare version reported SUCCESS for a child that20
# exited 1. Every gate in this repo is run by hand -- there is no CI here -- so21
# the interactive prompt is the normal case, not the exotic one.22
#23
# A sweep fixes today's sites and cannot see tomorrow's. Every bare site this24
# repo ever had was written next to another one.25
#26
# THE POPULATION IS DERIVED FROM THE ARTIFACT: every `*.sh` in the repository,27
# found by `find`, not a list anybody maintains. The number of files scanned is28
# printed, because a scan that found zero files would otherwise look identical to29
# a clean one.30
#31
# WHAT THIS CANNOT SEE, stated rather than left for someone to discover:32
# invocation through a variable or an alias (`S=setsid; $S "$sigil" ...`). This33
# is a text scanner and that construct defeats it. It is not used anywhere in34
# this repo today; if it ever is, this gate will not notice, and that is a35
# genuine hole rather than a hypothetical one.36
#37
# It DOES see invocations inside quoted strings -- `eval "..."`, `sh -c '...'`,38
# and lines that merely happen to contain an apostrophe. An earlier version39
# skipped anything with odd quote parity to its left, which meant one apostrophe40
# anywhere earlier on the line disarmed the check for a real, executed call. A41
# prose mention that gets flagged costs a rewording; a missed call site costs a42
# false green, so the strictness runs that way deliberately.43
set -euo pipefail45
repo_dir="$(cd "$(dirname "$0")/.." && pwd)"46
cd "$repo_dir"48
command -v awk >/dev/null || { echo "awk is required by this gate" >&2; exit 1; }49
command -v find >/dev/null || { echo "find is required by this gate" >&2; exit 1; }51
work=$(mktemp -d)52
trap 'rm -rf "$work"' EXIT INT TERM54
# The detector. An occurrence is ACCEPTED only when `-w`/`--wait` appears among55
# the option tokens that immediately follow it, before the command word. `-f` /56
# `--fork` alone is NOT acceptance: `-f` FORCES the racy branch. Anything the57
# parser cannot account for is REPORTED rather than waved through -- a detector58
# that fails open is the thing it exists to catch.59
#60
# Comment lines are skipped, and only comment lines: a `#`-led line cannot61
# execute, and this gate's own prose has to spell the bad pattern out.62
#63
# `\`-continuations are JOINED first, so an invocation whose options sit on the64
# next physical line is read as one logical line rather than reported as bare.65
cat >"$work/detect.awk" <<'AWK'66
{67
line = $068
while (line ~ /\\$/ && (getline nxt) > 0) {69
sub(/\\$/, "", line)70
sub(/^[[:space:]]+/, " ", nxt)71
line = line nxt72
}73
stripped = line74
sub(/^[ \t]*/, "", stripped)75
if (substr(stripped, 1, 1) == "#") next76
rest = line77
while (match(rest, /(^|[^-A-Za-z0-9_])setsid[ \t]+/)) {78
rest = substr(rest, RSTART + RLENGTH)79
waits = 080
tail = rest81
# Consume the leading option run. The trailing `[ \t]*$` alternative is what82
# lets an option that ends the line count -- without it, `... -w` as the last83
# token on a line was reported as bare.84
while (match(tail, /^-[^ \t]+([ \t]+|$)/)) {85
opt = substr(tail, RSTART, RLENGTH)86
sub(/[ \t]+$/, "", opt)87
if (opt == "--wait") waits = 188
else if (opt !~ /^--/ && opt ~ /w/) waits = 189
tail = substr(tail, RLENGTH + 1)90
}91
if (!waits) { print FILENAME ":" FNR ":" line }92
}93
}94
AWK96
scan() { # scan <dir> -- one record per bare occurrence97
find "$1" -name '.git' -prune -o -type f -name '*.sh' -print \98
| sort \99
| while IFS= read -r file; do awk -f "$work/detect.awk" "$file"; done100
}102
# --------------------------------------------------------------- CONTROLS103
# Planted into a throwaway directory, NEVER into the working tree, so there is104
# no restore step that has to be reached.105
#106
# THE FIXTURES ARE ASSEMBLED, NEVER SPELLED. This gate scans its own repository,107
# and a fixture written out literally here would be found by that scan and108
# reported as a real call site -- a check matching its own prose. Building the109
# lines through `$s` means the offending text does not appear anywhere in this110
# file outside a comment.111
ctl="$work/controls"112
mkdir -p "$ctl"113
s=setsid114
{115
printf '%s "$sigil" test suite.sgl >"$log" 2>&1\n' "$s"116
printf 'if ! %s "$sigil" eval -f probe.sgl >"$log"; then echo no; fi\n' "$s"117
printf 'out=$(%s -f "$sigil" eval "(display 1)")\n' "$s"118
printf '%s --fork "$sigil" build\n' "$s"119
printf ' indented=$(%s "$sigil" --version)\n' "$s"120
printf 'echo "the parser%ss output"; %s "$sigil" test suite.sgl\n' "'" "$s"121
printf 'eval "%s $sigil test >log"\n' "$s"122
printf "sh -c '%s \$sigil test'\n" "$s"123
printf '%s "$sigil" -w test suite.sgl\n' "$s"124
} >"$ctl/bad.sh"125
{126
printf '%s -w "$sigil" test suite.sgl >"$log" 2>&1\n' "$s"127
printf '%s -f --wait "${verify[@]}" --example timeout\n' "$s"128
printf '%s --wait "$sigil" build\n' "$s"129
printf 'FOO=bar %s -w "$sigil" eval -f probe.sgl\n' "$s"130
printf '%s -fw "$sigil" eval -f probe.sgl\n' "$s"131
printf '%s -w\n' "$s"132
printf '%s \\\n -w "$sigil" test suite.sgl\n' "$s"133
printf '# %s "$sigil" test suite.sgl <- a comment, and comments do not run\n' "$s"134
} >"$ctl/good.sh"136
# The fixtures must contain what they claim to, or every control below passes137
# over an empty file.138
bad_lines=9139
good_forms=8140
good_physical=9 # one form deliberately spans two physical lines141
test "$(grep -c . "$ctl/bad.sh")" = "$bad_lines" || { echo "bad.sh fixture is not $bad_lines lines" >&2; exit 1; }142
test "$(grep -c . "$ctl/good.sh")" = "$good_physical" || { echo "good.sh fixture is not $good_physical physical lines" >&2; exit 1; }144
ctl_bare=$(scan "$ctl" || true)145
ctl_bad=$(printf '%s\n' "$ctl_bare" | grep -c '/bad\.sh:' || true)146
ctl_good=$(printf '%s\n' "$ctl_bare" | grep -c '/good\.sh:' || true)148
# Nine planted bare forms: plain, `if !`, `-f` only, `--fork` only, indented in a149
# substitution, one hidden behind an apostrophe, one inside an `eval` string, one150
# inside an `sh -c` string, and one where `-w` sits AFTER the command word and so151
# is an argument to the command rather than an option to the wrapper.152
test "$ctl_bad" = "$bad_lines" || {153
echo "POSITIVE CONTROL FAILED: detector flagged $ctl_bad of $bad_lines planted bare invocations" >&2154
printf '%s\n' "$ctl_bare" | grep '/bad\.sh:' >&2 || true155
exit 1; }156
# Eight waiting or inert forms, including `-w` as the final token and `-w` on a157
# continuation line -- both of which an earlier version reported as bare.158
test "$ctl_good" = "0" || {159
echo "NEGATIVE CONTROL FAILED: detector flagged $ctl_good of $good_forms waiting/inert form(s) as bare" >&2160
printf '%s\n' "$ctl_bare" | grep '/good\.sh:' >&2; exit 1; }161
echo "detector armed: $bad_lines/$bad_lines planted bare invocations flagged (quoted, eval'd and post-command -w included), 0/$good_forms waiting or inert forms misflagged"163
# --------------------------------------------------------------- POPULATION164
files=$(find . -name '.git' -prune -o -type f -name '*.sh' -print | wc -l)165
test "$files" -ge 1 || { echo "scanned 0 shell scripts; the population derivation is broken" >&2; exit 1; }166
occurrences=$(grep -rn --include='*.sh' 'setsid' . 2>/dev/null | wc -l)167
echo "population: $files shell script(s); $occurrences line(s) mention it"169
bare=$(scan "." || true)170
if [ -n "$bare" ]; then171
echo "BARE INVOCATION(S) that do not reliably wait:" >&2172
printf '%s\n' "$bare" | sed 's/^/ /' >&2173
echo >&2174
echo "VERIFY THIS GATE'S OWN PRECONDITIONS BEFORE ACTING ON THIS MESSAGE:" >&2175
echo " - the detector's controls passed above, so it sees what it claims to see;" >&2176
echo " - the line quoted is the logical line, with continuations already joined;" >&2177
echo " - an occurrence inside a quoted string is reported deliberately, because" >&2178
echo " eval and sh -c strings are real invocations. If yours is prose, reword it." >&2179
echo "Then: pass -w so it waits and propagates the child's exit status, or drop the" >&2180
echo "wrapper entirely -- the sigil test runner does not need a new session." >&2181
echo "See folio topics/setsid-does-not-reliably-wait." >&2182
exit 1183
fi185
echo "SETSID_WAITS_GREEN 0 bare invocation(s) across $files shell script(s), $occurrences line(s) mentioning it"