Guard leak-path fix: read timeout's -- and post-duration options as uutils coreutils does - #685

Scope

• What this PR changes, in one or two sentences: a defensive leak-path fix for the command guard (scripts/hooks/secret_path_guard.py).
  • The guard took the word right after timeout's duration for the command. uutils timeout, the coreutils of Ubuntu 26.04, still reads an end-of-options -- and options at that position and runs the command after them, so the guard never examined that command.
  • Both word readings now step over that separator and those options.
  • The current reading also reads the launcher grammar the audit found open: long-option prefixes, env's value options and clusters, and the uutils multi-call binary.
• Base commit: f77a35eb2bf30bc4bf6f3b4ee51bc9ce5397b4c5
• Lane: lane:foundation. Re-registering hashes in manifests/evidence.json does not make it shared (docs/lanes.md, "Labels and PRs").
• Owned paths touched:
  • scripts/hooks/secret_path_guard.py and tests/test_secret_path_guard.py;
  • docs/decisions/2026-09-24-secret-storage.md (append-only dated addendum);
  • adoption/hooks/claude/SHA256SUMS (the guard's install pin, without which the profile installer refuses the changed guard);
  • manifests/evidence.json (hash re-registration, in the last commit).

SOTA sources

All sources were read on 2026-10-04 (UTC).

uutils coreutils (https://github.com/uutils/coreutils), at tags 0.8.0 (commit c4093734e2eb), 0.10.0 (28b6856d7b21) and 0.12.0 (dc1efd89948a):

• src/uu/timeout/src/timeout.rs uu_app: .trailing_var_arg(true) is at line 177 (0.8.0), 171 (0.10.0) and 173 (0.12.0), with .infer_long_args(true) on the next line. See https://github.com/uutils/coreutils/blob/0.8.0/src/uu/timeout/src/timeout.rs#L165-L178.
• uu_app in src/uu/env/src/env.rs (-a/--argv0, -f/--file, -C, -S, -u), nice.rs, stdbuf.rs and nohup.rs, at 0.8.0. env was also read at 0.12.0.
• src/bin/coreutils.rs main at 0.8.0: a binary named *utils takes the utility from its next argument.
• src/common/validation.rs binary_path at 0.8.0: on Linux the executed path names the utility, not argv[0].

GNU coreutils (mirror https://github.com/coreutils/coreutils of git.savannah.gnu.org/git/coreutils.git), at v9.7 (8e075ff8ee11) and v9.12 (c0f8514d9891):

• src/timeout.c: getopt_long (argc, argv, "+fk:ps:v", long_options, ...) and its long_options.
• src/env.c: shortopts "+a:C:iS:u:v0", and longopts with argv0, plus env0-from at v9.12.
• src/nice.c, src/stdbuf.c and src/nohup.c.
• The manual's source, doc/coreutils.texi at v9.12:
  • node "timeout invocation": synopsis timeout [option]… duration command [arg]…, and "Options must precede operands";
  • "Common options": "Most programs that accept long options recognize unambiguous abbreviations of those options".
• The rendered page is https://www.gnu.org/software/coreutils/manual/html_node/timeout-invocation.html. www.gnu.org timed out from the working host on 2026-10-04, so the Texinfo source the page is built from is cited instead.

glibc manual (mirror https://github.com/bminor/glibc), at glibc-2.42:

• manual/startup.texi Argument Syntax: "The argument -- terminates all options", and "Users can abbreviate the option names as long as the abbreviations are unique".
• manual/getopt.texi: a leading + in the option string stops option processing at the first non-option. "The option name may be abbreviated as long as the abbreviation is unique."
• The rendered page is https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html.

Ubuntu packaging: the resolute file list of rust-coreutils 0.8.0-0ubuntu3, which ships /usr/bin/coreutils: https://packages.ubuntu.com/resolute/amd64/rust-coreutils/filelist

sudo-rs (https://github.com/trifectatechfoundation/sudo-rs), at v0.2.15: src/sudo/cli/mod.rs normalize_arguments matches long options exactly and ends options at --. Audited; no change needed.

uutils 0.8.0 release binary: coreutils-0.8.0-x86_64-unknown-linux-gnu.tar.gz, sha256 ea8f0a4f6815c1da…, equal to the digest the release page publishes. It was run for the measurement below.

Evidence-class table

Replay summary: 6,582 distinct commands were checked against the base guard.

• Inputs: 1,500 test strings, 4,792 lines and whole blocks from 880 fenced shell blocks of tracked Markdown, and 290 launcher-matrix forms.
• Results: 159 newly refused (the 29 new test rows and 130 matrix rows, every one starting printenv, env, gdb or cat .env), 0 loosened, 0 reason changes, 0 errors.

Installer dry run: install_claude_profile.py --home <empty scratch> --only guard --hook secret_path_guard.py --dry-run reported "would install … (sha256 c6b8cfdc073d…)" and wrote nothing (exit 0).

Local commands run

All runs used TMPDIR=<scratch> nice -n 19.

$ python3 -m unittest tests.test_secret_path_guard
Ran 85 tests  FAILED (failures=1, skipped=2)  exit 1
  the only failure is test_host_profile_copy_is_verbatim: this host's installed guard is still the
  base guard (sha256 7b1ec8fa...), to be reinstalled after merge (not done here, by design)
$ HOME=<empty scratch> python3 -m unittest tests.test_secret_path_guard
Ran 85 tests  OK (skipped=3)  exit 0
$ python3 -m unittest tests.test_command_position_oracle
Ran 4 tests  OK  exit 0
$ python3 -m unittest tests.test_install_claude_profile tests.test_adoption_status tests.test_adoption_docs_consistency \
    tests.test_freeze_snapshot tests.test_new_wsl_client_config tests.test_credential_status \
    tests.test_credential_boot_receipt tests.test_canary_proof
Ran 765 tests  OK (skipped=5)  exit 0
$ python3 scripts/validate.py
{"components": 69, "hashed_files": 9864, "profiles": 4, "receipts": 195, "status": "passed"}  exit 0
$ python3 scripts/evidence_manifest.py --check
{"files": 9864, "status": "passed"}  exit 0
$ python3 scripts/component_matrix.py --check ; python3 scripts/new_host_grand_list.py --check
exit 0 ; exit 0
$ git diff --check origin/main...HEAD
exit 0
$ python3 -m unittest    (the whole suite)
Ran 10246 tests  FAILED (failures=2, skipped=871)  exit 1
  test_host_profile_copy_is_verbatim: expected, see above
  test_windows_terminal_defaults ... test_the_installed_client_knows_no_notification_type_without_a_decision:
  this host's installed client knows 'auth_storage_failure'; the test fails identically on a pristine
  origin/main export (6af8e55b), so it is environmental and not caused by this PR
$ main moved to 6af8e55b (#679, #681): git merge-tree --write-tree HEAD origin/main
clean, exit 0; on the merged tree validate.py and evidence_manifest --check exit 0 (9,878 hashed files),
and the guard, its tests and the pin are unchanged by the merge
$ failing first: the committed tests against the base guard (git archive HEAD, guard file from f77a35eb)
FAILED (failures=137)  exit 1
  test_launcher_grammar_of_gnu_and_uutils_coreutils 29, test_blocked_commands 29,
  test_every_rule_applies_behind_rtk_proxy 58, test_every_rule_applies_to_a_keyring_exec 6,
  test_both_readings_take_the_command_after_timeouts_duration 6,
  test_the_current_reading_reads_gnu_and_uutils_env_and_the_multicall_binary 9
$ the same tests with the head guard
OK  exit 0

Wrapper audit

Decision record

docs/decisions/2026-09-24-secret-storage.md, "Addendum 2026-10-04: launcher grammar of GNU and uutils coreutils". It covers the decision, sources, measurement, alternatives rejected, overturn conditions, open items and evidence class.

Residuals

• env -S STRING followed by more words (env -S 'CMD …' more): the split string becomes the command line. This is a different class (a string-splitting launcher) and is not fixed here.
• Long-option prefixes of the launchers outside coreutils (C sudo, xargs, time, ionice, the systemd launchers) were not audited.
• GNU's single-binary coreutils --coreutils-prog=NAME, and other multi-call binaries (busybox, toybox), are not read.
• examples/claude-native/workflows/child-usage.mjs (lane counting, not credential protection) reads timeout the GNU way, so on a uutils host it would not count the lane in timeout 5 -- LANE. It is outside this PR's paths, and its oracle passes on GNU hosts.
• Deliberate over-read: timeout -- 5 -- CMD is refused, although both implementations run -- there and exit 127. It errs toward refusal and no documented command uses it.
• The installed guard on each host must be reinstalled after merge (see below).

Host reinstall after merge (coordinator)

python3 tools/adoption/install_claude_profile.py --only guard --hook secret_path_guard.py
python3 -m unittest tests.test_secret_path_guard.SecretPathGuardTests.test_host_profile_copy_is_verbatim

Host evidence

Not applicable: no file under evidence/hosts/ changes.

Checklist

• New/changed GitHub Actions are pinned to a full commit SHA with a
  version comment (no floating tags). (None changed.)
• New/changed workflows declare top-level permissions: contents: read
  (or a narrower, explicitly justified addition). (None changed.)
• No secrets are printed, logged or committed; no new required secret was
  added without a documented owner. Test strings use placeholder names only.
• No new paid hosting, subscription or billing surface was introduced.
• Peer-owned untracked files and worktrees were preserved (not deleted,
  moved or overwritten).

🤖 Generated with Claude Code