Settles a question the campaign has worked around for three sessions:
rpi_nc_install.sh's 11.36% is an instrument failure, not a testing gap.
Measured against an independent instrument. Driving the lib under
PS4='+PS4:${BASH_SOURCE##*/}:${LINENO} ' with set -x traces 55 distinct lines
as executed, and 45 of them are lines kcov reports as UNCOVERED -- including
61, 62, 63, 66, 68, 102, 118 and 146. The lines run; kcov does not record
them.
That splits the problem in two, and they need different fixes:
(a) WRONG DENOMINATOR -- continuation lines of a multi-line quoted argument
counted as statements, which bash -x never calls executable at all.
Fixable in shell_coverage_report.py. Holds dwm_config.sh down.
(b) WRONG NUMERATOR -- ordinary statements executing unrecorded. Caps
rpi_nc_install.sh, and no test can move it.
The distinction is the point. A denominator filter is the obvious fix and I
nearly built one last session; it would have done nothing for (b).
Also confirmed no test can raise rpi_nc_install.sh: the file is one 227-line
function called twice, an `exit 88` sentinel proves the suite runs to
completion, and its assertions on save_config (line 219) and the password
message (line 227) PASS while kcov calls both lines uncovered.
kcov 43 is the current release, so upgrading is not an available fix.
The kcov material moved to docs/kcov-under-report.md (the 250-line cap), and
NEXT_SESSION_PROMPT.md now leads with the instrument work rather than the
next lib -- 201 in-scope libs, 98 passing, 103 exempt, and the instrument is
the bottleneck.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016sxxsDHWgdRhmdmzNMA6XM
The previous commit attributed rpi_nc_ca.sh's 72/73 to a heredoc BODY being
counted in the denominator. That was wrong. Line 141 is `cat <<'EOF'` -- the
heredoc's OPENING line, an ordinary statement. The body starts at 142.
The real cause is that the kcov under-report is contagious across processes
sharing one jail. Bisected over the five sibling suites: run
test_dwm_config.sh before test_rpi_nc_ca.sh and line 141 is lost; run
test_aw_autostart.sh or test_dot_resolver_install.sh first and it is kept.
Alone the CA suite reports 73/73 = 100.00%; through run_all.sh it reports
72/73 = 98.63%. Both figures reproduce twice, so this is deterministic
contamination rather than flakiness.
Nothing is untested: with dwm_config running first, the CA suite still exits
0 with every assertion passing, show_help included. The line executes and is
not traced.
A heredoc-body detector was prototyped and deleted once it showed line 141 is
not a body line -- a fix aimed at the wrong defect.
The operational rule this implies is now written down: is_covered() measures
through run_all.sh, so the runner's number is the lib's coverage, and a
suite's own single-file figure must never be reported in its place.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016sxxsDHWgdRhmdmzNMA6XM
A 27-assertion suite for dwm_config.sh, the highest-scored remaining
allowlisted lib. It drives the lib for real inside the jail: rewriting dwm.c
with perl, appending to config.h, compiling with cc and installing into
/usr/local/bin. The generated content is asserted, not just the call.
LATENT BUG, found by writing the test: apply_fullscreen_confine_hook does
`on=$(grep -c 'pconfine-auto on' "$src")`, and grep -c exits 1 when the count
is zero. The caller runs `set -euo pipefail`, so the function aborted at that
line exactly when the count was zero -- which is precisely when the
"setfullscreen/unmanage were likely refactored upstream" warning three lines
below was the thing needed. The warn branch was dead code in the only
situation it exists for. Both call sites now use `|| true`, and the suite
asserts the warning fires.
Measured: dwm_config.sh 35/73 = 47.95%. It STAYS on the allowlist -- the bar
is 100% and it is measured, not asserted.
That number is an under-report. An `exit 43` sentinel proves build_install,
build_pointer_confine, write_session_files and verify all execute inside the
jail while kcov reports their bodies at zero hits. One kcov artifact is now
CONFIRMED against a minimal repro: continuation lines inside a multi-line
quoted argument (the `perl -0777 -pe '...'` blocks) are counted as
statements that never run, which is the wrong denominator. A sixth
hypothesis -- that the exec-ing sudo shim or a pipeline loses the trace --
was tested and disproven. The two-strike time-box on this hunt is spent;
docs/shell-split-verification.md records what is known, including the
exit-sentinel technique for telling a tracing failure from an aborted suite.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016sxxsDHWgdRhmdmzNMA6XM
The previous commit added kcov to the shell-tests apt step on the assumption
it was packaged for Ubuntu. It is not -- CI went red in 34s on "E: Unable to
locate package kcov" -- and upstream ships no prebuilt binary either, so it
would have to be built from source on every run.
CI now skips jail_args-marked suites with a printed reason, the same trade
the arch-tests job already makes for Arch-only tests: declare what this
runner cannot do rather than pretend to check it. Enforcement is not lost --
ci_mirror.sh runs those suites through the real jail on every push, and that
gate is already proven to fail on a broken assertion. An empty jail_args is
still a hard failure.
Simulated over all six discovered runners: 5 PASS, 1 SKIP, none dropped.
Committed with CI_GREEN_SKIP=1, the ci-baseline-green hook's documented
escape hatch for a commit that IS the fix for the red baseline.
Also records the kcov instrument defect in docs/shell-split-verification.md.
rpi_nc_install.sh measures 11.36% while its 29 assertions pass and its writes
land on disk. Five hypotheses are now disproven against minimal
reproductions -- the three from the previous session, plus `cd`-relocation
and a heredoc piped into a stubbed external. The cause is still unknown, so
the rule is documented instead: a suspicious percentage means re-measure, not
re-write the test. The failure only ever under-reports, so it can keep a lib
on the allowlist but can never promote an untested one.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016sxxsDHWgdRhmdmzNMA6XM
clean_audio.sh 419 -> 230 + 204
enforce_vbox_hosts.sh 443 -> 220 + 236
migrate_hosts_guard.sh 444 -> 167 + 162 + 141
migrate_hosts_guard needed two libraries: with all ten work functions moved
the single lib was 295 lines, so migrate and rollback were separated.
The extractor's brace matcher required index > start and so silently skipped
one-line `warn() { ...; }` definitions. Fixed, and regression-checked against
the committed fresh-install/main.sh split byte-for-byte.
The harness earned its keep on a fourth file: adding `export` to libre_translate
to satisfy SC2034 changed two function bodies, and verify_shell_split.sh caught
what lint had accepted. Those exports were reverted, and libre_translate.sh is
parked - what remains after its clean seams both assigns and reads the same
globals, so getting it under the cap needs parse_args restructured rather than
relocated, which is a refactor rather than a verbatim move.
That cost is now written down: a lib must contain the readers of every global
it assigns. The precedent at install_pacman_wrapper.sh:29 is about
definitions-only libs, not about assignments as such, and the pre-commit hook
runs shellcheck with no -x, so a source= directive will not make it follow the
link. This is the shell analogue of the monkeypatch-target trap.
Verified: all 8, 13 and 19 functions verbatim; all four libraries source with
no side effects; shellcheck passes standalone on every file with no
suppression; bash -n passes on all seven. None of the three was executed -
they drive ffmpeg over real media, mutate VirtualBox guest disks, and rewrite
systemd units.
Over-cap files 29 -> 26.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
The five Python splits this session were made safe by a throwaway ast
identity check. There is no ast for bash, so meta/scripts/verify_shell_split.sh
does the same job with shfmt -mn (minify: strips comments and indentation,
keeps logic), hashing each top-level function and naming the one that differs.
shfmt is already a REQUIRED_TOOLS binary, so this adds no dependency.
Validated in all three directions before trusting it: an unchanged copy is
IDENTICAL, a copy with blank lines inserted is IDENTICAL, and a one-character
logic change ($1 -> $2) is caught and named. The first mutation attempt used
sed 's/exit 1/exit 2/' on a file with no 'exit 1' and reported IDENTICAL - the
harness was fine, the test was vacuous. That trap is now documented, because a
normalizer that silently passes everything is worse than none.
Also triaged all 29 over-cap shell scripts for deployed copies, which the
trace harness cannot see. The finding that changes the plan: deploy.sh copies
a hardcoded per-file list into /data/local/tmp/focus_mode and never deploys
lib/, so an entry+lib seam would break focus mode on the phone at its first
source - for 8 of the 29, not the 2 the brief named. Those scripts source only
config.sh, which is on the copy list, so a sibling-file seam works provided
deploy.sh's list grows in the same commit.
16 scripts have no deployed copy and are safe to split conventionally.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
The file hit the same 250-line cap it exists to serve, for the second time --
it was itself split out of shell-split-recipes.md for that reason.
Kept the split along the same why/how line: shell-split-verification.md (78)
keeps the hazards that decide whether a green run means anything, and the new
shell-split-harness.md (211) takes trace_shell_split.sh, --prefix, the
regression fixtures and the two traps.
The filename stays put because six files reference it, including
meta/scripts/trace_shell_split.sh and refactor_claude_todo_resume.md. Added a
pointer to the new file from shell-split-recipes.md so it is reachable.
Docs only -- no behaviour to verify.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
Probing found a blocker the trace structurally cannot see: a script that some
OTHER script copies elsewhere and runs from there cannot take an entry+lib/
shape, because the deployed entry's SCRIPT_DIR has no lib/ and dies on its
first source under set -e. The trace stays green because it runs the repo copy.
install_leechblock.sh is blocked on exactly this, and it is live, not
theoretical: install_pacman_wrapper.sh cp's it to
/usr/local/share/digital_wellbeing/, pacman_wrapper.sh:831 PREFERS that copy,
and auto_install_leechblock runs on every pacman invocation. It is otherwise
the best-conditioned target left (exit 0, 93 files, all hashes stable), which
is exactly why it needed the check rather than the trace.
setup_thorium_startup.sh is mechanically splittable — exit 0, all 8 steps
covered, no deployed copy — but should not be split, because what it configures
is dead. Thorium was removed in favour of chromium/librewolf;
/usr/local/bin/thorium-browser is now a leftover symlink to
browser-preexec-wrapper, which cannot resolve /usr/bin/thorium-browser and so
treats the URL as the binary. The enabled thorium-fitatu-startup.service has
been failing at every boot while reporting status=0/SUCCESS:
thorium-browser: line 33: /https://www.fitatu.com/app/planner: No such file
Also recorded: process spawning escapes --prefix the same way pkill does.
setup_thorium_startup.sh launches a browser mid-run; check ps after tracing
anything that starts a program.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
Probed the two remaining candidates at HEAD instead of guessing:
nvidia_troubleshoot.sh is ruled OUT. Its trace dies at step 3 because
backup_file writes /etc/profile.backup.<stamp>, a new SIBLING in unbound /etc
— a file bind cannot cover siblings and bare /etc is refused. 239 of its 336
lines never execute, so keeping the unproven ones in the entry (the rule the
pacman split established) leaves the entry at ~265, still over the cap. The
file cannot satisfy both the rule and the goal.
install_leechblock.sh is the best-conditioned target left: exit 0, 93 files
written, and all 93 hashes byte-identical across two consecutive runs. Only
the echoed prefix path and curl's progress meter vary.
But it fires an unstubbed `pkill` at every Chromium-family browser. pkill is
not in the stub set and --prefix cannot contain it, because signals are not
filesystem writes. Two probe runs fired it, harmless only because no browser
happened to be open. That is now documented as its own trap, and the brief
tells the next session to pass --stub pkill and check for a live victim first.
Also recorded: for a target embedding $(date), diff the written files' CONTENTS
with the date normalized rather than falling back to comparing sizes — that
still catches a dropped line, which a size comparison does not.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
`--bind-abs /usr/bin` overlays the directory bwrap needs to exec anything, so
the run dies with `execvp bash: No such file or directory` before the script
starts. A target whose last act replaces a binary there traces fine with every
other path bound and stops at that line with exit 1 on EPERM — usable as a
baseline (it is deterministic across runs), but blind to statements at or
after the failure, which is a constraint on where the seams can go.
Also noted: the absolute-path scanner misses a literal `ln -sf` target,
because it follows variables into `cat >`/`cp`.
The brief now targets install_pacman_wrapper.sh (316) with its baseline
already captured: 16 file hashes, one stubbed call, exit 1 at line 304.
Checked ahead of time that its source.sha256 drift manifest hashes only the
seven copied source files, not the installer, so a split leaves it stable.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
All three were found by review and reproduced before fixing. Each let a run
report success while proving nothing -- the shape this harness exists to
prevent.
A reused prefix defeated dropped-write detection entirely. Run 1's files were
still there when run 2's manifest was taken, so the manifest reported writes
that never happened and the fixture pair diffed CLEAN. The doc's own examples
demonstrated that workflow. A non-empty prefix is now refused -- not deleted,
since the path is user-supplied -- and the examples use distinct prefixes.
A missing bwrap was swallowed. trace_prefix_bwrap_argv returned 1, but the
caller reads it through `mapfile < <(...)` and a process substitution's status
is discarded, so runner ended up empty and the run continued with no sandbox
and no uid 0. Same swallow as the grep-status one fixed earlier, one layer up.
bwrap is now probed in validate_requirements, before anything runs.
The absolute-path scan only fired when no --bind-abs was given at all, so
binding one path and missing three produced no warning. It now runs whenever
--prefix is given and reports only what is not already covered. Fixing that
surfaced a second defect: --bind-abs on a FILE aborted with "Can't mkdir
/etc/profile: Not a directory", and binding its parent reintroduced the
wholesale /etc shadowing this change had already measured as harmful ($SUDO_USER
collapsing to /home//, the real /etc/profile unreadable). Files are now bound
file-over-file, seeded with a copy so a script that greps before appending sees
real content.
Also measured rather than argued: the XDG redirect. A new fixture run with a
real XDG_DATA_HOME pointing at a decoy shows all four writes landing in the
prefix and the decoy empty -- the rsync --delete data-loss path, proven closed
without running install_leechblock.sh. And no-prefix output was diffed against
cdf2a55 from a detached worktree: byte-identical, so existing baselines hold.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
Shell redirections are builtins, so no PATH stub can intercept
`cat > /etc/modprobe.d/x.conf`. That left installer scripts unverifiable:
stub cp/chmod/ln and the trace is nearly empty, don't and the run rewrites
the live system.
--prefix redirects HOME and every XDG_* base into a temp tree. XDG_DATA_HOME
is exported explicitly, not left to default off HOME: install_leechblock.sh
reads it directly and then runs `rsync -a --delete` at it.
--bind-abs binds hardcoded absolutes via bwrap --unshare-user --uid 0, leaf
directories only. uid 0 is load-bearing beyond permissions: common.sh's
require_root does `exec sudo "$0"`, and under the sudo stub that truncated
the whole run to one recorded call -- a trace that diffs clean against any
split. Binding /etc wholesale was measured to shadow /etc/passwd, collapse
$SUDO_USER to /home//, and mask a nested bind, so the scanner never emits it.
The trace gains a manifest of every file written, with content hashes. That
section is the point: with it, a dropped write in the fixture pair is a
one-line diff; with it stripped, the two traces are identical, i.e. the old
harness passed that broken split. Hashes normalize the prefix to @PREFIX@
because install_usage_monitoring.sh writes an unquoted heredoc that bakes
$HOME into the artifact.
Verified: ~/.config/systemd/user, ~/.local/bin, ~/.local/share and
/etc/modprobe.d byte-identical before and after; usage-report units still 2.
The three prior regressions are now committed fixtures rather than ad-hoc --
one was silently neutered mid-change when a trailing echo added for SC2034
became the function's last statement and turned exit 1 into exit 0.
Stub generation moved to lib/ because --prefix pushed the harness to 252
lines, over the cap it exists to serve.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
The previous commit broke `./lint_python.sh` from the repo root. That path
is a symlink into meta/, and `dirname` does not resolve symlinks, so
SCRIPT_DIR became the repo root and the new `source "$SCRIPT_DIR/lib/..."`
line pointed at a lib/ that does not exist -- an instant exit under
set -euo pipefail.
The bug was latent before the split: the same unresolved SCRIPT_DIR only
fed PROJECT_ROOT, so a root-path run degraded quietly. Adding a source
line is what turned a wrong value into a hard failure.
It was invisible because every check I ran used `bash meta/lint_python.sh`
-- the one entry point that could not fail. Both paths are now verified:
`./lint_python.sh` exits 0 through the symlink, and the direct invocation
still diffs byte-identical against the pre-split baseline. No CI job, hook
or wrapper calls it, so nothing automated was broken in the interim.
Recorded in docs/shell-split-verification.md as its own trap, with the
commands to enumerate a script's other entry points before splitting it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
A stub that prints nothing makes `size=$(du -sk x)` empty, so every
`((size > 0))` is false and the trace walks past every guarded branch.
Two such traces compare identical while exercising none of the changed
code -- a green check that proves nothing, which is the exact failure
mode this harness exists to prevent.
--stub now takes `name=output`. Measured on a fixture whose `sudo rm -rf`
is guarded by a size test: the silent stub gives `size=[]` / "branch
skipped" and never records the rm; `--stub 'du=4096\t/some/dir'` gives
`size=[4096]` / "BRANCH TAKEN" and captures it.
This weakens the earlier disk_cleanup_check.sh trace, which used a silent
du stub: that trace only proved the empty-size path identical. The real
run from /tmp is what covered the populated path. Noted in the evidence.
Docs also record two limits found while surveying: file-placement
installers are not yet traceable (stub cp/chmod/ln and the trace is
empty; don't and it rewrites the live system), and baselines for scripts
reading relative paths must run from the script's own directory.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
Adding it to the handoff pushed that file to 280 lines -- the handoff is
not exempt from the cap it exists to enforce. The usage, the two caveats
(stubs always exit 0; unstubbed binaries run for real) and the proof it
catches both bug classes now live in docs/shell-split-verification.md,
which is the file dedicated to exactly this. The handoff keeps a pointer.
Also dropped the per-directory count table, which carried a "do not work
from this table" warning and went stale every session, and compressed the
co-agent narrative to the diagnostic commands worth keeping. 280 -> 246.
Recorded there too: the harness needs no main(), which matters because
none of the remaining near-miss shell targets have one, so
verify_shell_split.sh cannot check any of them.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
The prettier hook is pre-push only, so this only surfaced when the push
ran. Two list-continuation lines rewrapped.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
Three new sections, each earned this session:
- A --skip-install flag is not evidence a script is safe to run.
shell_check.sh gates only the pacman branch on it; the AUR branch runs
regardless, and a "baseline" run installed four packages before I
killed it. Grep the flag's variable and read every hit first.
- A stubbed run cannot reach a bug in a seam that passes state. It
sources the libs and never calls them. analyze_repo.sh passed bash -n,
shellcheck, both diffs and the stub, and still aborted at runtime --
set -e turning a function's last conditional into its return value,
and a self-referencing nameref warning into the script's own output.
- Do not make a clean file shfmt-dirty, and re-count comment banners
after shfmt -w, which deletes ones it thinks are stray.
Adding them pushed the doc to 285, so it is split: recipes.md keeps how
to make a split (231), the new verification.md holds how to find out it
is wrong (70). The recipe doc now points at it from the stubbed-run
bullet, where someone about to trust the stub will actually read it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
