AtlatestRepositorysigil-doc

sigil-doc / tree / testgate-setsid-waits.sh

1#!/usr/bin/env bash
2#
3# No shell script in this repository may invoke the session wrapper without
4# 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 setsid
9# PROCESS is itself a process-group leader and the parent returns 0 at once while
10# the child runs on. Whether that happens is a property of the CALLING SHELL, not
11# of the command: bash puts every job in its own process group when job control
12# is on, so the same line waits inside a script and does NOT wait when a human
13# runs it at an interactive prompt. Measured on this host 2026-08-22, `bash -i`
14# over a pty:
16# bare exit=0 elapsed_ms=5 logbytes=0
17# -w exit=0 elapsed_ms=3011 logbytes=16
19# and in the `if ! ...` form the bare version reported SUCCESS for a child that
20# exited 1. Every gate in this repo is run by hand -- there is no CI here -- so
21# the interactive prompt is the normal case, not the exotic one.
23# A sweep fixes today's sites and cannot see tomorrow's. Every bare site this
24# repo ever had was written next to another one.
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 is
28# printed, because a scan that found zero files would otherwise look identical to
29# a clean one.
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" ...`). This
33# is a text scanner and that construct defeats it. It is not used anywhere in
34# this repo today; if it ever is, this gate will not notice, and that is a
35# genuine hole rather than a hypothetical one.
37# It DOES see invocations inside quoted strings -- `eval "..."`, `sh -c '...'`,
38# and lines that merely happen to contain an apostrophe. An earlier version
39# skipped anything with odd quote parity to its left, which meant one apostrophe
40# anywhere earlier on the line disarmed the check for a real, executed call. A
41# prose mention that gets flagged costs a rewording; a missed call site costs a
42# false green, so the strictness runs that way deliberately.
43set -euo pipefail
45repo_dir="$(cd "$(dirname "$0")/.." && pwd)"
46cd "$repo_dir"
48command -v awk >/dev/null || { echo "awk is required by this gate" >&2; exit 1; }
49command -v find >/dev/null || { echo "find is required by this gate" >&2; exit 1; }
51work=$(mktemp -d)
52trap 'rm -rf "$work"' EXIT INT TERM
54# The detector. An occurrence is ACCEPTED only when `-w`/`--wait` appears among
55# the option tokens that immediately follow it, before the command word. `-f` /
56# `--fork` alone is NOT acceptance: `-f` FORCES the racy branch. Anything the
57# parser cannot account for is REPORTED rather than waved through -- a detector
58# that fails open is the thing it exists to catch.
60# Comment lines are skipped, and only comment lines: a `#`-led line cannot
61# execute, and this gate's own prose has to spell the bad pattern out.
63# `\`-continuations are JOINED first, so an invocation whose options sit on the
64# next physical line is read as one logical line rather than reported as bare.
65cat >"$work/detect.awk" <<'AWK'
67 line = $0
68 while (line ~ /\\$/ && (getline nxt) > 0) {
69 sub(/\\$/, "", line)
70 sub(/^[[:space:]]+/, " ", nxt)
71 line = line nxt
72 }
73 stripped = line
74 sub(/^[ \t]*/, "", stripped)
75 if (substr(stripped, 1, 1) == "#") next
76 rest = line
77 while (match(rest, /(^|[^-A-Za-z0-9_])setsid[ \t]+/)) {
78 rest = substr(rest, RSTART + RLENGTH)
79 waits = 0
80 tail = rest
81 # Consume the leading option run. The trailing `[ \t]*$` alternative is what
82 # lets an option that ends the line count -- without it, `... -w` as the last
83 # 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 = 1
88 else if (opt !~ /^--/ && opt ~ /w/) waits = 1
89 tail = substr(tail, RLENGTH + 1)
90 }
91 if (!waits) { print FILENAME ":" FNR ":" line }
92 }
94AWK
96scan() { # scan <dir> -- one record per bare occurrence
97 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"; done
102# --------------------------------------------------------------- CONTROLS
103# Planted into a throwaway directory, NEVER into the working tree, so there is
104# no restore step that has to be reached.
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 and
108# reported as a real call site -- a check matching its own prose. Building the
109# lines through `$s` means the offending text does not appear anywhere in this
110# file outside a comment.
111ctl="$work/controls"
112mkdir -p "$ctl"
113s=setsid
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"
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 passes
137# over an empty file.
138bad_lines=9
139good_forms=8
140good_physical=9 # one form deliberately spans two physical lines
141test "$(grep -c . "$ctl/bad.sh")" = "$bad_lines" || { echo "bad.sh fixture is not $bad_lines lines" >&2; exit 1; }
142test "$(grep -c . "$ctl/good.sh")" = "$good_physical" || { echo "good.sh fixture is not $good_physical physical lines" >&2; exit 1; }
144ctl_bare=$(scan "$ctl" || true)
145ctl_bad=$(printf '%s\n' "$ctl_bare" | grep -c '/bad\.sh:' || true)
146ctl_good=$(printf '%s\n' "$ctl_bare" | grep -c '/good\.sh:' || true)
148# Nine planted bare forms: plain, `if !`, `-f` only, `--fork` only, indented in a
149# substitution, one hidden behind an apostrophe, one inside an `eval` string, one
150# inside an `sh -c` string, and one where `-w` sits AFTER the command word and so
151# is an argument to the command rather than an option to the wrapper.
152test "$ctl_bad" = "$bad_lines" || {
153 echo "POSITIVE CONTROL FAILED: detector flagged $ctl_bad of $bad_lines planted bare invocations" >&2
154 printf '%s\n' "$ctl_bare" | grep '/bad\.sh:' >&2 || true
155 exit 1; }
156# Eight waiting or inert forms, including `-w` as the final token and `-w` on a
157# continuation line -- both of which an earlier version reported as bare.
158test "$ctl_good" = "0" || {
159 echo "NEGATIVE CONTROL FAILED: detector flagged $ctl_good of $good_forms waiting/inert form(s) as bare" >&2
160 printf '%s\n' "$ctl_bare" | grep '/good\.sh:' >&2; exit 1; }
161echo "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# --------------------------------------------------------------- POPULATION
164files=$(find . -name '.git' -prune -o -type f -name '*.sh' -print | wc -l)
165test "$files" -ge 1 || { echo "scanned 0 shell scripts; the population derivation is broken" >&2; exit 1; }
166occurrences=$(grep -rn --include='*.sh' 'setsid' . 2>/dev/null | wc -l)
167echo "population: $files shell script(s); $occurrences line(s) mention it"
169bare=$(scan "." || true)
170if [ -n "$bare" ]; then
171 echo "BARE INVOCATION(S) that do not reliably wait:" >&2
172 printf '%s\n' "$bare" | sed 's/^/ /' >&2
173 echo >&2
174 echo "VERIFY THIS GATE'S OWN PRECONDITIONS BEFORE ACTING ON THIS MESSAGE:" >&2
175 echo " - the detector's controls passed above, so it sees what it claims to see;" >&2
176 echo " - the line quoted is the logical line, with continuations already joined;" >&2
177 echo " - an occurrence inside a quoted string is reported deliberately, because" >&2
178 echo " eval and sh -c strings are real invocations. If yours is prose, reword it." >&2
179 echo "Then: pass -w so it waits and propagates the child's exit status, or drop the" >&2
180 echo "wrapper entirely -- the sigil test runner does not need a new session." >&2
181 echo "See folio topics/setsid-does-not-reliably-wait." >&2
182 exit 1
183fi
185echo "SETSID_WAITS_GREEN 0 bare invocation(s) across $files shell script(s), $occurrences line(s) mentioning it"