Accept uutils coreutils timeout in generated hooks, and check the shims against real implementations (#6561)

* Accept uutils coreutils timeout in generated hooks

The generated hook selects a timeout helper only when its --version
banner starts with "timeout (GNU coreutils) ". uutils coreutils reports
"timeout (uutils coreutils) " with the same command line and the same
exit 124 on expiry, so hosts that ship it (Ubuntu 25.10+, NixOS with
uutils-coreutils-noprefix) silently fell through to the Perl alarm, or
to the unbounded direct run when Perl is absent. Follow-up from #5522,
tracked in #5541.

- Widen the identity allowlist to uutils; the match stays by banner so
  Windows timeout.exe is still never probed (#5503).
- Add a backend-selection case using the GNU stub with the uutils
  banner: fails on the old shim (selects gtimeout), passes with the
  widening.
- Regenerate the managed sections in the tracked .githooks/* so
  TestTrackedManagedHookSectionsMatchGenerator stays green.
- Update the hook-timeout passages in docs/reference/git-integration.md
  and troubleshooting.md, which described the probe as GNU-only.

Verified on NixOS with uutils 0.10.0 as /run/current-system/sw/bin/timeout:
with Perl removed from PATH and a bd that hangs, the old shim runs
"without timeout" for the full duration; the new shim expires at
BEADS_HOOK_TIMEOUT and continues.

Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik

* Regenerate tracked .githooks managed sections with make githooks-regen

TestTrackedManagedHookSectionsMatchGenerator holds the managed section in
each tracked .githooks/* byte-equal to the cmd/bd/hooks.go generator, but
nothing regenerated them: after a generator change a contributor had to
splice the new section in by hand, and the failure only dumped both
texts. The v1.2.0 bump reddened main this way (ce20a64bb), and #6561 shipped
its first revision with the five hooks stale.

- BD_UPDATE_GOLDEN=1 makes the test rewrite the section in place, keeping
  everything around the markers (the project's own hook logic) untouched.
  Same switch the package's events golden already uses.
- `make githooks-regen` wraps it, next to `corpus-regen`.
- The drift failure now names that command.
- The exactly-one-section check runs before any rewrite.

Verified: drifting one byte inside .githooks/pre-push fails the test with
the hint; `make githooks-regen` restores the file to the same blob SHA;
the test is green again.

Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik

* Check the tracked hook shims against real timeout implementations

The Go tests pin the shim's helper selection with scripted stand-ins, so
they can only encode what the author believes each real `timeout` does.
That is where the last two defects lived: uutils prints a banner the
allowlist did not know (#5541), and busybox — which #5541 suggests
adding — exits 143 on expiry rather than 124, so allowlisting it would
turn every deadline into a failed hook and a blocked push.

checks.nix adds a flake check that runs the tracked .githooks/* managed
sections (held equal to the generator by
TestTrackedManagedHookSectionsMatchGenerator) against the binaries
themselves: GNU coreutils, uutils, busybox and toybox `timeout`, each
with and without perl, under dash, bash and busybox ash, for all five
hooks — 150 cases. Expectations come from a model of the contract (the
allowlist as data), so widening it is one line here and the binaries
either agree or they do not.

A fake bd on the shim's restricted PATH blocks on a held-open fifo until
a helper kills it, records the signal and re-raises it, so each case
asserts the backend that ran (TERM from timeout, ALRM from perl's alarm)
and not merely that the shim finished. No clock: a helper that fails to
kill the fake trips the harness's own `timeout 10`. Every case asserts
exit 0, since anything else blocks the user's push. Reading .githooks/*
instead of building bd keeps it at ~1 s and off the Go build's critical
path; CI's test-nix job runs it after its existing help-text smoke test.

Mutation-checked: restoring main's GNU-only sections fails all 30 uutils
cases (15 unbounded, 15 on the perl backend); allowlisting busybox with
a loosened probe fails all 30 busybox cases with hook exit 143.

Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik

* Run the hook-timeout check under the gtimeout candidate name too

The shim probes `timeout` and then `gtimeout`, but the matrix only ever
put a binary named `timeout` on PATH, so the second candidate was never
run against a real implementation. Whether a helper is accepted under
that name depends on what its banner does with argv[0].

Measured: the uutils multicall dispatches on the argv[0] SUFFIX
(src/bin/coreutils.rs, `binary_as_util.ends_with(util)`) and then prints
the canonical utility name — invoked as gtimeout it reports
"timeout (uutils coreutils) 0.8.0" (this flake's nixos-25.11 pin; 0.11.0
identical), which the allowlist accepts. busybox and toybox know no
gtimeout applet and fail the probe outright, rejected as before. GNU is
immune by construction: Homebrew's gtimeout is a separate binary whose
banner is the fixed "timeout (GNU coreutils) 9.11"; nixpkgs' coreutils
is a single-binary multicall that refuses a foreign name ("unknown
program 'gtimeout'"), so it gets no variant here.

Each multicall is now also installed on a case PATH as `gtimeout` ALONE
(`installs`, derived from `implementations`; `backendFor` stays keyed on
the implementation, so the model's claim is "uutils is allowlisted
whatever it is called"). 240 cases on Linux, 80 on darwin (no busybox or
toybox there, and no busybox-ash shell). The shadowed
`out=` inside run_case is `case_out` now: it only survived because every
case is a backgrounded subshell, and a de-backgrounded case would have
died on the final `touch "$out"`.

Mutation-checked: installing the variant as `xtimeout` (a name the shim
never probes) fails exactly the 30 uutils-as-gtimeout cases — 15 with
nothing killing the fake bd, 15 on the perl backend (ALRM) instead of
coreutils; restored, 240 of 240 pass. The busybox/toybox variants cannot
distinguish (their expectation is rejection either way); their weight is
that the probe does not blow up on a foreign name.

* Run the flake checks on main too, by nix flake check; docs wording

pr-risk.yml's test-nix job ran the hook-timeout check on PRs only; the
byte-identical job in main.yml never got the step, so post-merge main
never ran it. Both jobs now run `nix flake check -L`: no hardcoded
`x86_64-linux` (the step beside it, `nix run .#default`, was already
system-agnostic), and a check added to checks.nix runs without a
workflow edit. checks.aarch64-darwin and .x86_64-darwin evaluate.

Measured on ubuntu-latest with a cold Nix store (fork run 35700791032,
this tree, 240 cases): `nix flake check -L` 3.6 s including substitution
of uutils, busybox, toybox, dash and perl; 0.08 s warm — beside the
4 min 9 s the existing `nix run .#default` step spends building bd in
the same job. The 10-minute timeout is not in question.

git-integration.md: on Git for Windows the preferred deadline backend is
"a coreutils timeout (GNU or uutils)", not GNU alone, since both now
qualify. troubleshooting.md: reflow a ragged paragraph.

* review: close the duplicated contracts around the uutils timeout accept

Maintainer review fixes for #6561. No change to the shim's behavior or to the
generated/tracked hook sections.

- cmd/bd/hooks_timeout_process_test.go: the uutils fixture was built with
  strings.Replace, which returns its input unchanged when the pattern is
  absent, so a later edit to the GNU stub's banner would silently degenerate
  the uutils case into a second copy of the GNU one — still green, no longer
  testing the new accept. Hoist the derivation and fail loudly when the banner
  no longer matches.
- cmd/bd/hooks_timeout_process_test.go: findHookProcessGNUTimeout held a second,
  un-widened copy of the identity allowlist, so on exactly the hosts this PR
  exists for (uutils timeout, no gtimeout) the only Go test that drives a real
  timeout binary skipped with a reason the fix had just made false. Widen the
  probe's case, rename it findHookProcessCoreutilsTimeout, and reword the skip
  and the subtest. Measured against stub PATHs: uutils goes rc=1 -> rc=0, GNU
  stays rc=0, a busybox banner stays rc=1.
- cmd/bd/init_hooks_test.go: TestGenerateHookSection_Timeout asserted only the
  GNU alternative, so deleting the new uutils one from the generator left the
  structural contract green (verified: it passes under that mutation before
  this change, and reports "section missing uutils coreutils identity check"
  after). Add the companion assertion.
- cmd/bd/init_hooks_test.go, Makefile: the regen arm rewrites tracked source
  files, so give it its own BD_UPDATE_HOOKS_GOLDEN rather than the package's
  shared BD_UPDATE_GOLDEN — an unscoped `BD_UPDATE_GOLDEN=1 go test ./cmd/bd/`
  used to turn genuine hook drift into a silent working-tree rewrite that
  reported PASS.
- cmd/bd/init_hooks_test.go: locate the managed section by marker prefix
  instead of the versioned marker line. Tracked hooks drift both from generator
  content and from the release version stamp; the exact-line lookup made the
  second class fatal ("tracked hook missing ...") before the regen arm was
  reachable, so `make githooks-regen` failed at exactly the moment a release
  engineer reaches for it. The versioned markers are still verified — they are
  part of the byte compare.
- checks.nix: the `rc -eq 124` safety-net verdict discarded both $case_out and
  the already-captured $signal, so the one failure mode that is intermittent
  and not locally reproducible was also the only one with no diagnostics.
  Report them like the `rc -ne 0` branch below it.
- docs/reference/troubleshooting.md, docs/reference/git-integration.md: mirror
  the coreutils wording across both docs this PR touches, and generalize the
  re-install guidance in both. Managed sections are never reported Outdated
  (getHookVersion returns IsShim for them and computeHookStatuses gates on
  !IsShim), so nothing tells an existing install it is stale; the sentence was
  still scoped to the older name-only check (#5503).
- CHANGELOG.md: add the [Unreleased] entry for #5541, worded to the actual
  scope — with Perl installed the shim still reached the Perl alarm arm, so the
  lost deadline bit uutils hosts without Perl — say that existing installs must
  run `bd hooks install` once, and drop the claim that stock NixOS ships uutils
  (this PR's own checks.nix takes GNU from pkgs.coreutils).

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Tomasz Feliksik 2026-09-27 12:38:45 +02:00 • committed by GitHub
commit 33bed587e0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
17 changed files with 416 additions and 47 deletions

View file

@ -19,7 +19,7 @@ if command -v bd >/dev/null 2>&1; then
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
case "$_bd_timeout_version" in
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
"timeout (GNU coreutils) "*|"timeout (uutils coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
esac
fi
fi

View file

@ -19,7 +19,7 @@ if command -v bd >/dev/null 2>&1; then
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
case "$_bd_timeout_version" in
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
"timeout (GNU coreutils) "*|"timeout (uutils coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
esac
fi
fi

View file

@ -60,7 +60,7 @@ if command -v bd >/dev/null 2>&1; then
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
case "$_bd_timeout_version" in
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
"timeout (GNU coreutils) "*|"timeout (uutils coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
esac
fi
fi

View file

@ -59,7 +59,7 @@ if command -v bd >/dev/null 2>&1; then
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
case "$_bd_timeout_version" in
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
"timeout (GNU coreutils) "*|"timeout (uutils coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
esac
fi
fi

View file

@ -19,7 +19,7 @@ if command -v bd >/dev/null 2>&1; then
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
case "$_bd_timeout_version" in
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
"timeout (GNU coreutils) "*|"timeout (uutils coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
esac
fi
fi

View file

@ -1226,6 +1226,13 @@ jobs:
id: nix_help
run: |
nix run .#default -- --help > help.txt
# Every flake check for the runner's own system (today: hook-timeout-
# backends, checks.nix). `nix flake check` rather than a spelled-out
# `.#checks.x86_64-linux.<name>`: no hardcoded system, and a check added
# to checks.nix is run without a workflow edit.
- name: Run the flake checks
run: |
nix flake check -L
- name: Verify help text
if: steps.nix_help.outcome == 'success'
run: |

View file

@ -431,6 +431,13 @@ jobs:
id: nix_help
run: |
nix run .#default -- --help > help.txt
# Every flake check for the runner's own system (today: hook-timeout-
# backends, checks.nix). `nix flake check` rather than a spelled-out
# `.#checks.x86_64-linux.<name>`: no hardcoded system, and a check added
# to checks.nix is run without a workflow edit.
- name: Run the flake checks
run: |
nix flake check -L
- name: Verify help text
if: steps.nix_help.outcome == 'success'
run: |

View file

@ -26,6 +26,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
up, but it can flip auto-backup on or off for `-C` invocations whose launch
directory and target differ in remote configuration.
- **Generated git hooks accept uutils coreutils `timeout` as a deadline helper**
([#5541](https://github.com/gastownhall/beads/issues/5541)). The managed hook
section probes `timeout` and `gtimeout` with `--version` and accepted only the
GNU coreutils banner, so a host whose `timeout` is uutils coreutils
(Ubuntu 25.10+, or a distribution configured with `uutils-coreutils` in place
of GNU) failed the probe and fell through. Where Perl was
installed the shim still got a deadline from the Perl `alarm` arm — which Git
for Windows Perl does not guarantee across `exec` — so the missing deadline
bit uutils hosts *without* Perl, which ran `bd hooks run` unbounded (with the
documented warning). The probe now also accepts the
`timeout (uutils coreutils) ` banner; native Windows `timeout.exe` stays
rejected ([#5503](https://github.com/gastownhall/beads/issues/5503)). The
widened probe ships in the generated hook section, which is rewritten only by
`bd hooks install` — hosts that already installed hooks must run it once to
pick up the fix.
- **`bd close` now exits non-zero when any issue in a batch fails to close**
([#6648](https://github.com/gastownhall/beads/issues/6648)). A batch with one
refused id used to exit 0 as long as another id closed, so scripts could not

View file

@ -43,7 +43,7 @@ export PATH := $(GIT_WINDOWS_ROOT)/usr/bin;$(PATH)
endif
endif
.PHONY: all build doctor-build test test-icu-path test-full-cgo test-regression test-upgrade test-cross-version test-migration corpus-regen bench bench-quick clean clean-test-tmp install install-force help check-up-to-date fmt fmt-check check-testing-short
.PHONY: all build doctor-build test test-icu-path test-full-cgo test-regression test-upgrade test-cross-version test-migration corpus-regen githooks-regen bench bench-quick clean clean-test-tmp install install-force help check-up-to-date fmt fmt-check check-testing-short
.PHONY: ci-pr-core ci-pr-policy ci-pr-lint ci-complexity ci-complexity-diff ci-complexity-check ci-package-mcp ci-package-npm
.PHONY: api-gen api-check
@ -288,6 +288,15 @@ corpus-regen:
@echo "Regenerating contract corpus..."
go test -tags "$(BUILD_TAGS)" ./cmd/bd/protocol -run TestCorpusGolden -corpus.update -count=1
# The tracked .githooks/* carry the managed section cmd/bd/hooks.go generates;
# TestTrackedManagedHookSectionsMatchGenerator holds them byte-equal. Run this
# after changing the generator or after bumping Version in cmd/bd/version.go
# (the section markers carry the version), then commit the regenerated hooks
# alongside it.
githooks-regen:
@echo "Regenerating managed sections in .githooks/*..."
BD_UPDATE_HOOKS_GOLDEN=1 go test -tags "$(BUILD_TAGS)" ./cmd/bd -run TestTrackedManagedHookSectionsMatchGenerator -count=1
# Run performance benchmarks against Dolt storage backend
# Requires CGO and Dolt; generates CPU profile files

262
checks.nix Normal file
View file

@ -0,0 +1,262 @@
# Flake checks. Run all with `nix flake check`; one with
# `nix build .#checks.<system>.<name> -L`.
pkgs:
let
inherit (pkgs) lib;
# hook-timeout-backends: run the tracked hook shims against REAL timeout
# implementations.
#
# cmd/bd/hooks_timeout_process_test.go pins the shim's selection logic with
# scripted helpers, and TestTrackedManagedHookSectionsMatchGenerator holds
# the tracked .githooks/* byte-equal to the generator. This check closes the
# remaining gap — what the helpers on real hosts actually do — by running the
# tracked sections against the binaries themselves. That is where the
# surprises live: uutils prints a different banner (GH#5541); busybox exits
# 143 on expiry, not 124, so allowlisting it as-is would turn every timeout
# into a failed hook; toybox exits 125 from --version.
#
# The matrix is derived from a model of the contract, so a change to the
# allowlist is one line here and the binaries either agree or they do not.
# Reading .githooks/* rather than building bd keeps this at about one
# deadline of wall time and independent of the Go build.
#
# Each case: one hook, one shell (the `sh`s a `#!/usr/bin/env sh` hook meets
# in the wild), a PATH of exactly one timeout implementation — under the
# name `timeout`, or for the multicall ones also under `gtimeout` alone —
# plus optionally perl, BEADS_HOOK_TIMEOUT=1, and a fake `bd` that blocks on a held-open fifo
# until a helper kills it. The fake records the signal that killed it, which
# is how the check asserts the backend and not just "it finished":
# coreutils backend → TERM from timeout, shim reports the deadline, exit 0
# perl backend → ALRM from perl's alarm, same report, exit 0
# no backend → the fake returns at once; shim warns it is running
# without a deadline, exit 0
# A non-zero hook exit blocks the user's push, so every case asserts exit 0.
# No clock is involved: if nothing kills the fake, the harness's own
# `timeout 10` (on its full PATH, not the shim's) fails the case.
# The identity allowlist in cmd/bd/hooks.go, as data.
allowlisted = [
"gnu-coreutils"
"uutils-coreutils"
];
implementations = {
gnu-coreutils = pkgs.coreutils;
uutils-coreutils = pkgs.uutils-coreutils-noprefix;
none = null;
}
// lib.optionalAttrs pkgs.stdenv.isLinux {
busybox = pkgs.busybox;
toybox = pkgs.toybox;
};
# The shim probes `timeout` first and `gtimeout` second (Homebrew's prefixed
# GNU coreutils on macOS). Whether a helper is accepted under the second name
# depends on what its banner does with argv[0]. The multicall implementations
# dispatch on it and then print the CANONICAL utility name: uutils'
# src/bin/coreutils.rs matches `argv[0].ends_with(<util>)`, so `gtimeout`
# (or `mytimeout`) is `timeout` to it and reports "timeout (uutils
# coreutils) <version>" — accepted (measured on 0.8.0, this flake's
# nixos-25.11 pin, and on 0.11.0); busybox and toybox know no `gtimeout`
# applet and fail the probe outright — rejected either way. These variants put each multicall on PATH under the name `gtimeout`
# ONLY, so the second candidate is the one that runs. GNU has no variant:
# nixpkgs' coreutils is a single-binary multicall that refuses a name it does
# not know ("coreutils: unknown program 'gtimeout'"), while Homebrew's
# gtimeout is a separate binary whose banner is the fixed "timeout (GNU
# coreutils) 9.11" — GNU is immune by construction, not by measurement here.
asGtimeout =
impl: pkg:
pkgs.runCommand "${impl}-as-gtimeout" { } ''
mkdir -p "$out/bin"
ln -s ${pkg}/bin/timeout "$out/bin/gtimeout"
'';
# What goes on a case's PATH: every implementation as itself, and the
# multicalls once more under the other candidate name. `impl` is what the
# model reasons about; `label` is what the case is called.
installs = lib.concatLists (
lib.mapAttrsToList (
impl: pkg:
[
{
inherit impl;
label = impl;
dirs = lib.optional (pkg != null) "${pkg}/bin";
}
]
++ lib.optional (pkg != null && impl != "gnu-coreutils") {
inherit impl;
label = "${impl}-as-gtimeout";
dirs = [ "${asGtimeout impl pkg}/bin" ];
}
) implementations
);
shells = {
dash = "${pkgs.dash}/bin/dash";
bash = "${pkgs.bash}/bin/bash";
}
// lib.optionalAttrs pkgs.stdenv.isLinux {
busybox-ash = "${pkgs.busybox}/bin/sh";
};
hooks = [
"pre-commit"
"post-merge"
"pre-push"
"post-checkout"
"prepare-commit-msg"
];
backendFor =
impl: withPerl:
if lib.elem impl allowlisted then
"coreutils"
else if withPerl then
"perl"
else
"none";
# One `run_case` line per point in the matrix, all backgrounded.
cases = lib.concatMap (
install:
lib.concatMap
(
withPerl:
lib.concatLists (
lib.mapAttrsToList (
shellName: shell:
map (hook: {
name = "${hook}/${shellName}/${install.label}${lib.optionalString withPerl "+perl"}";
inherit hook shell;
backend = backendFor install.impl withPerl;
path = install.dirs ++ lib.optional withPerl "${pkgs.perl}/bin";
}) hooks
) shells
)
)
[
false
true
]
) installs;
caseLine =
c:
"run_case ${
lib.escapeShellArgs [
c.name
c.hook
c.backend
c.shell
]
} ${lib.escapeShellArgs c.path} &\n";
trackedHooks = lib.fileset.toSource {
root = ./.;
fileset = ./.githooks;
};
in
{
hook-timeout-backends =
pkgs.runCommand "bd-hook-timeout-backends"
{
# Only .githooks/* is an input: nothing else in the repo changes what
# this check measures.
githooks = "${trackedHooks}/.githooks";
}
''
# 1. Shims under test: the managed section of each tracked hook, as
# bd installs it into a fresh repo (shebang + section).
shims="$TMPDIR/shims"
mkdir -p "$shims"
for hook in ${lib.escapeShellArgs hooks}; do
{
echo '#!/usr/bin/env sh'
sed -n '/^# --- BEGIN BEADS INTEGRATION/,/^# --- END BEADS INTEGRATION/p' "$githooks/$hook"
} > "$shims/$hook"
grep -q 'bd hooks run' "$shims/$hook" || { echo "no managed section in .githooks/$hook"; exit 1; }
done
# 2. The fake bd the shim will find on its restricted PATH. It blocks
# until killed and records the signal, re-raising it so it dies the
# way a real bd would (143 / 142), not by a made-up exit code.
fake="$TMPDIR/fakebin"
mkdir -p "$fake"
cat > "$fake/bd" <<'FAKE'
#!/bin/sh
trap 'echo TERM > "$FAKE_BD_SIGNAL"; trap - TERM; kill -TERM $$' TERM
trap 'echo ALRM > "$FAKE_BD_SIGNAL"; trap - ALRM; kill -ALRM $$' ALRM
[ -n "$FAKE_BD_BLOCK" ] && read -r _
exit 0
FAKE
chmod +x "$fake/bd"
mkfifo "$TMPDIR/hang"
exec 3<> "$TMPDIR/hang"
# 3. The matrix.
results="$TMPDIR/results"
mkdir -p "$results"
run_case() {
name=$1 hook=$2 backend=$3 shell=$4
shift 4
case_dir="$TMPDIR/cases/$name"
mkdir -p "$case_dir/bin"
ln -s "$shell" "$case_dir/bin/sh"
path="$fake:$case_dir/bin"
for dir in "$@"; do path="$path:$dir"; done
block=1
[ "$backend" = none ] && block=
signal_file="$case_dir/signal"
# `|| rc=$?`: the builder runs under set -e, and a bare assignment
# from a failing command would end this subshell before it reports.
rc=0
case_out=$(timeout 10 env PATH="$path" BEADS_HOOK_TIMEOUT=1 \
FAKE_BD_BLOCK="$block" FAKE_BD_SIGNAL="$signal_file" \
"$case_dir/bin/sh" "$shims/$hook" origin https://example.invalid 2>&1 <&3) || rc=$?
signal=$(cat "$signal_file" 2>/dev/null || true)
verdict=ok
if [ "$rc" -eq 124 ]; then
# This is the one mode that is intermittent and not reproducible
# locally, so it needs the output most: report it like the branch
# below rather than as a bare string.
verdict="FAIL: nothing killed the fake bd (harness safety net fired), signal='$signal': $case_out"
elif [ "$rc" -ne 0 ]; then
verdict="FAIL: hook exit $rc (would block the push): $case_out"
else
case "$backend" in
coreutils)
case "$case_out" in *"timed out after 1s"*) ;; *) verdict="FAIL: no deadline report: $case_out" ;; esac
[ "$signal" = TERM ] || verdict="FAIL: expected coreutils timeout (TERM), fake saw '$signal'"
;;
perl)
case "$case_out" in *"timed out after 1s"*) ;; *) verdict="FAIL: no deadline report: $case_out" ;; esac
[ "$signal" = ALRM ] || verdict="FAIL: expected perl alarm (ALRM), fake saw '$signal'"
;;
none)
case "$case_out" in *"running without timeout"*) ;; *) verdict="FAIL: no unbounded warning: $case_out" ;; esac
;;
esac
fi
printf '%-52s %-10s %s\n' "$name" "$backend" "$verdict" > "$results/$(echo "$name" | tr / _)"
}
${lib.concatMapStrings caseLine cases}
wait
printf '%-52s %-10s %s\n' CASE BACKEND RESULT
sort "$results"/*
echo
reported=$(ls "$results" | wc -l)
echo "$reported of ${toString (lib.length cases)} cases reported, $(grep -l FAIL "$results"/* | wc -l) failed"
if [ "$reported" -ne ${toString (lib.length cases)} ]; then
echo "some cases never reported a verdict"
exit 1
fi
if grep -q FAIL "$results"/*; then
exit 1
fi
touch "$out"
'';
}

View file

@ -68,8 +68,14 @@ const hookTimeoutSeconds = 300
// - Helper argv is separated with -- so user input cannot become an option.
// - If no compatible helper exists, the direct fallback is explicitly
// unbounded rather than silently pretending to enforce a deadline.
// - Only GNU coreutils timeout implementations are selected; Windows
// - Only GNU coreutils timeout and uutils coreutils timeout (same command
// line, same exit 124; GH#5541) are selected, by --version banner; Windows
// timeout.exe has the same name but an incompatible command line (GH#5503).
// The banner match holds under the gtimeout candidate too: GNU prints a
// fixed program name (Homebrew's gtimeout reports "timeout (GNU
// coreutils) ..."), and the uutils multicall dispatches on the argv[0]
// suffix and then prints the canonical name ("timeout (uutils coreutils)
// ..." when invoked as gtimeout). checks.nix runs that case.
// - If the beads database is not initialized (exit code 3), the hook exits
// successfully with a warning so that git operations are not blocked.
func generateHookSection(hookName string) string {
@ -93,7 +99,7 @@ func generateHookSection(hookName string) string {
" if command -v \"$_bd_timeout_candidate\" >/dev/null 2>&1; then\n" +
" if _bd_timeout_version=\"$(\"$_bd_timeout_candidate\" --version 2>/dev/null)\"; then\n" +
" case \"$_bd_timeout_version\" in\n" +
" \"timeout (GNU coreutils) \"*) _bd_timeout_command=$_bd_timeout_candidate; break ;;\n" +
" \"timeout (GNU coreutils) \"*|\"timeout (uutils coreutils) \"*) _bd_timeout_command=$_bd_timeout_candidate; break ;;\n" +
" esac\n" +
" fi\n" +
" fi\n" +

View file

@ -128,12 +128,22 @@ func TestGeneratedHookTimeoutProcessBoundary(t *testing.T) {
t.Run("shell options preserve argv and status", testHookProcessShellOptions)
t.Run("POSIX sh preserves argv and status", testHookProcessPOSIXShell)
t.Run("reserved statuses are backend scoped", testHookProcessReservedStatuses)
t.Run("real GNU timeout expires a responsive child", testHookProcessRealTimeoutExpiry)
t.Run("real coreutils timeout expires a responsive child", testHookProcessRealTimeoutExpiry)
t.Run("real Perl alarm expires a responsive child", testHookProcessRealPerlExpiry)
t.Run("Windows checkout rejects System32 timeout", testHookProcessWindowsSystemTimeoutCheckout)
}
func testHookProcessBackendSelection(t *testing.T) {
// Derive the uutils helper from the GNU stub so the two differ only in the
// banner, but fail loudly if that banner ever moves: strings.Replace returns
// its input unchanged when the pattern is absent, which would silently turn
// the uutils case into a second copy of the GNU one.
const hookProcessGNUTimeoutBanner = "(GNU coreutils) 9.99"
uutilsTimeoutStub := strings.Replace(hookProcessGNUTimeoutStub, hookProcessGNUTimeoutBanner, "(uutils coreutils) 0.10.0", 1)
if uutilsTimeoutStub == hookProcessGNUTimeoutStub {
t.Fatalf("uutils fixture is a copy of the GNU stub: %q not found in hookProcessGNUTimeoutStub", hookProcessGNUTimeoutBanner)
}
tests := []struct {
name string
fixtures []hookProcessFixture
@ -148,6 +158,14 @@ func testHookProcessBackendSelection(t *testing.T) {
},
wantHelper: "helper=gtimeout",
},
{
name: "uutils coreutils timeout is selected like GNU",
fixtures: []hookProcessFixture{
{name: "timeout", body: uutilsTimeoutStub},
{name: "gtimeout", body: hookProcessGNUGtimeoutStub},
},
wantHelper: "helper=timeout",
},
{
name: "nonzero GNU-looking probe yields to gtimeout",
fixtures: []hookProcessFixture{
@ -322,7 +340,7 @@ func testHookProcessReservedStatuses(t *testing.T) {
}
func testHookProcessRealTimeoutExpiry(t *testing.T) {
helperName, helperDir := findHookProcessGNUTimeout(t)
helperName, helperDir := findHookProcessCoreutilsTimeout(t)
timeout := "1"
result := runGeneratedHookProcess(t, hookProcessCase{
bdBody: hookProcessLongRunningBDStub,
@ -513,13 +531,18 @@ shift
return hookProcessResult{output: string(output), exitCode: exitCode, elapsed: elapsed}
}
func findHookProcessGNUTimeout(t *testing.T) (string, string) {
// findHookProcessCoreutilsTimeout mirrors the generated shim's identity
// allowlist (cmd/bd/hooks.go generateHookSection). Keep the `case` here in step
// with the one the generator emits: this is the second copy of that contract,
// and a narrower copy silently skips the only test that drives a real timeout
// binary on exactly the hosts the wider allowlist exists for.
func findHookProcessCoreutilsTimeout(t *testing.T) (string, string) {
t.Helper()
probe := `for _bd_test_candidate in timeout gtimeout; do
if command -v "$_bd_test_candidate" >/dev/null 2>&1 &&
_bd_test_version="$("$_bd_test_candidate" --version 2>/dev/null)"; then
case "$_bd_test_version" in
"timeout (GNU coreutils) "*)
"timeout (GNU coreutils) "*|"timeout (uutils coreutils) "*)
_bd_test_path=$(command -v "$_bd_test_candidate")
printf '%s\n%s\n' "$_bd_test_candidate" "${_bd_test_path%/*}"
exit 0
@ -533,11 +556,11 @@ exit 1
cmd.Env = hookProcessEnv()
output, err := cmd.CombinedOutput()
if err != nil {
t.Skipf("compatible GNU timeout is unavailable: %s", strings.TrimSpace(string(output)))
t.Skipf("no compatible coreutils timeout is available: %s", strings.TrimSpace(string(output)))
}
lines := strings.Split(strings.TrimSpace(string(output)), "\n")
if len(lines) != 2 || lines[0] == "" || lines[1] == "" {
t.Fatalf("unexpected GNU timeout probe output: %q", string(output))
t.Fatalf("unexpected coreutils timeout probe output: %q", string(output))
}
return lines[0], lines[1]
}

View file

@ -226,6 +226,9 @@ func TestGenerateHookSection_Timeout(t *testing.T) {
if !strings.Contains(section, `"timeout (GNU coreutils) "*`) {
t.Error("section missing GNU coreutils identity check")
}
if !strings.Contains(section, `"timeout (uutils coreutils) "*`) {
t.Error("section missing uutils coreutils identity check")
}
if !strings.Contains(section, `"$_bd_timeout_command" -- "$_bd_timeout"`) {
t.Error("section missing GNU timeout argv separator")
}
@ -265,23 +268,49 @@ func TestTrackedManagedHookSectionsMatchGenerator(t *testing.T) {
}
tracked := string(content)
begin := strings.Index(tracked, hookSectionBeginLine())
if begin < 0 {
t.Fatalf("tracked hook missing %q", hookSectionBeginLine())
}
endMarker := hookSectionEndLine() + "\n"
relativeEnd := strings.Index(tracked[begin:], endMarker)
if relativeEnd < 0 {
t.Fatalf("tracked hook missing %q", hookSectionEndLine())
}
end := begin + relativeEnd + len(endMarker)
if got, want := tracked[begin:end], generateHookSection(hookName); got != want {
t.Fatalf("tracked managed section drifted from generator\nwant:\n%s\ngot:\n%s", want, got)
}
if strings.Count(tracked, hookSectionBeginPrefix) != 1 || strings.Count(tracked, hookSectionEndPrefix) != 1 {
t.Fatal("tracked hook must contain exactly one managed section")
}
// Locate the section by marker PREFIX, not by the versioned marker
// line. Tracked hooks drift for two reasons — generator content and
// the release version stamp — and a prefix scan makes the second one
// ordinary drift that the byte compare below reports and the regen
// arm repairs. Matching hookSectionBeginLine() here would instead
// fail with "missing marker" after a Version bump, before the regen
// arm is reachable. The versioned markers are still verified: they
// are part of `want`.
begin := strings.Index(tracked, hookSectionBeginPrefix)
if begin < 0 {
t.Fatalf("tracked hook missing %q", hookSectionBeginPrefix)
}
relativeEnd := strings.Index(tracked[begin:], hookSectionEndPrefix)
if relativeEnd < 0 {
t.Fatalf("tracked hook missing %q", hookSectionEndPrefix)
}
end := begin + relativeEnd
newline := strings.IndexByte(tracked[end:], '\n')
if newline < 0 {
t.Fatalf("tracked hook %q line is not newline-terminated", hookSectionEndPrefix)
}
end += newline + 1
got, want := tracked[begin:end], generateHookSection(hookName)
// A dedicated variable, not the package's shared BD_UPDATE_GOLDEN:
// this arm rewrites tracked SOURCE files, so an unscoped
// `BD_UPDATE_GOLDEN=1 go test ./cmd/bd/` must not silently convert
// real hook drift into a working-tree mutation that reports PASS.
if os.Getenv("BD_UPDATE_HOOKS_GOLDEN") == "1" {
if got == want {
return
}
if err := os.WriteFile(path, []byte(tracked[:begin]+want+tracked[end:]), 0o755); err != nil {
t.Fatalf("write tracked hook: %v", err)
}
t.Logf("regenerated managed section in %s", path)
return
}
if got != want {
t.Fatalf("tracked managed section drifted from generator (regenerate with `make githooks-regen`)\nwant:\n%s\ngot:\n%s", want, got)
}
})
}
}

View file

@ -130,12 +130,13 @@ hooks {
The hook shim applies a soft deadline to `bd hooks run` when a compatible
helper is available. It
uses `timeout` or `gtimeout` only after a successful GNU coreutils identity
probe, avoiding the incompatible `timeout.exe` that native Windows can place
on `PATH`. GNU timeout sends `TERM` at the configured deadline. On POSIX hosts,
uses `timeout` or `gtimeout` only after a successful identity probe for GNU
coreutils or uutils coreutils (same command line, same exit status), avoiding
the incompatible `timeout.exe` that native Windows can place on `PATH`. The
coreutils helper sends `TERM` at the configured deadline. On POSIX hosts,
the Perl fallback uses `SIGALRM` on the direct `bd` process at the deadline.
Git for Windows Perl does not guarantee that alarm across `exec`, so GNU
coreutils is the preferred deadline backend there.
Git for Windows Perl does not guarantee that alarm across `exec`, so a
coreutils `timeout` (GNU or uutils) is the preferred deadline backend there.
The default deadline is **300 seconds** (5 minutes), which accommodates chained
pre-commit pipelines (eslint, prettier, TypeScript compilation). Override it
@ -152,13 +153,15 @@ BEADS_HOOK_TIMEOUT=600 git commit -m "..."
The value must be a positive whole number of seconds. Invalid values and zero
produce a warning and use the 300-second default. These are soft process
deadlines, not process-tree containment: TERM-resistant work or descendants
can outlive them. If neither GNU timeout nor Perl is available, the hook warns
and runs directly without a deadline; that last-resort path can hang until the
hook itself returns.
can outlive them. If neither a coreutils timeout nor Perl is available, the hook
warns and runs directly without a deadline; that last-resort path can hang until
the hook itself returns.
After upgrading from a release whose generated hooks used a name-only timeout
check, run `bd hooks install` once to refresh already-installed canonical hook
sections. Automatic generated-policy adoption is tracked separately.
Already-installed hook sections are not refreshed automatically. After upgrading
to a release that changed the generated timeout probe — the name-only check, or
the uutils coreutils banner — run `bd hooks install` once to refresh
already-installed canonical hook sections. Automatic generated-policy adoption is
tracked separately.
When the timeout is reached, beads prints a warning and lets the git
operation proceed — the commit or push is not blocked.

View file

@ -535,16 +535,20 @@ export BEADS_HOOK_TIMEOUT=600 # 10 minutes (in seconds)
The value must be a positive whole number of seconds. Invalid values and zero
warn and fall back to 300 seconds. Beads accepts `timeout` or `gtimeout` only
when a successful version probe identifies GNU coreutils; native Windows
`timeout.exe` is not compatible. If neither GNU timeout nor Perl is available,
the hook warns that it is running directly without a deadline.
when a successful version probe identifies GNU coreutils or uutils coreutils;
native Windows `timeout.exe` is not compatible. If neither a coreutils timeout
nor Perl is available, the hook warns that it is running directly without a
deadline.
GNU timeout sends `TERM`; on POSIX hosts, Perl's alarm applies to the direct
`bd` process. Git for Windows Perl does not guarantee that alarm across
`exec`, so GNU coreutils is preferred there. TERM-resistant work and
descendant processes are not guaranteed to stop. After upgrading from a
version with the name-only timeout check, run `bd hooks install` once to
refresh existing canonical sections.
The coreutils helper sends `TERM`; on POSIX hosts, Perl's alarm applies to the
direct `bd` process. Git for Windows Perl does not guarantee that alarm across
`exec`, so a coreutils `timeout` (GNU or uutils) is preferred there.
TERM-resistant work and descendant processes are not guaranteed to stop.
Already-installed hook sections are not refreshed automatically. After upgrading
to a version that changed the timeout probe — the name-only check, or the uutils
coreutils banner — run `bd hooks install` once to refresh existing canonical
sections.
### Permission denied on git hooks

View file

@ -22,6 +22,7 @@ a unit test: use the real boundary when the defect could live there.
| Affected-package confidence | `./scripts/test.sh ./path/to/package/...` | After the focused test passes; include directly affected neighbors when their contract changed. |
| Final Go baseline | `make test` | Once after focused work on Go code is green. It applies the normal local build flags, coverage, and local skip handling. |
| Named CI wrapper | `make ci-pr-core`, `make ci-pr-policy`, or `make ci-pr-lint` | Run the wrapper whose risk or surface is affected, or use it to reproduce that CI check. Do not run all three routinely for every edit. |
| Hook shims against real timeout implementations | `nix flake check -L` (or `nix build .#checks.<system>.hook-timeout-backends -L`) | After changing the hook generator in `cmd/bd/hooks.go` (then `make githooks-regen`) or anything under `.githooks/`. Runs the tracked managed sections against GNU coreutils, uutils, busybox and toybox `timeout` — the multicalls also installed as `gtimeout` alone — with and without Perl, under dash, bash and busybox ash. About one deadline of wall time; needs no Go build. |
Do not replace the focused loop with repeated full-suite runs. Run the final
`make test` once the affected Go tests are green. For docs-only changes, use

View file

@ -38,6 +38,8 @@
packages = forAllSystems (import ./packages.nix);
checks = forAllSystems (import ./checks.nix);
apps = nixpkgs.lib.genAttrs systems (
system:
rec {