test(download): write the yt-dlp stub under ForkLock

The kernel refuses to exec a file that is open for writing anywhere in
the process, and these tests are parallel: a sibling's fork duplicates
stubYtDlp's write descriptor in the moment it is open and carries it
past our close, so the exec a moment later fails with ETXTBSY. That is
the flake seen once locally and once in CI, both times on a tree with
no Go in its diff.

Closing sooner is not available -- os.WriteFile has already closed the
file before anything execs it -- and O_CLOEXEC does not help, because
the window is between another goroutine's fork and its own exec.
syscall.ForkLock is the lock forkExec takes across that fork, so
holding it over the write means no child can exist while the
descriptor does.

Measured on the helper itself under 12 concurrent writers: 176-189 of
2400 execs refused before, 0 of 2400 after, three runs each.

Closes #146

CLAUDE.md

@@ -161,7 +161,7 @@ make ui-test          # Vitest component/store suite in a real browser (no app)
 make ui-visual        # Same, including toMatchScreenshot comparisons
 make ui-setup         # Install the Vitest provider's own Chromium (once)
 make bindings-check   # Fail if frontend/bindings is stale vs the Go bindings
-make skill-check      # Fail if a doc names a make target that doesn't exist
+make skill-check      # Fail if .pi/ documents a make target that doesn't exist
 make commit-check     # Fail if a commit subject is not a Conventional Commit
 make lint             # golangci-lint v2 (strict), all three build configurations
 make test             # All tests with race detector, all three build configurations

Makefile

@@ -192,7 +192,7 @@ css-check: ## Fail on a css`` literal ended early by a backtick, or a nested rul
 # Every command in them is a make target on purpose, so this is
 # checkable.  It also asserts AGENTS.md is a symlink to CLAUDE.md, so the
 # two harnesses cannot drift onto two descriptions of one project.
-skill-check: ## Fail if the docs name a missing make target, or AGENTS.md is not a symlink
+skill-check: ## Fail if the agent docs name a missing make target, or AGENTS.md is not a symlink
 	@./scripts/skill-check.sh
 
 # Conventional Commits, which CLAUDE.md claimed CI enforced for a long

backend/download/provider_ytdlp_test.go

@@ -7,6 +7,7 @@ import (
 	"path/filepath"
 	"runtime"
 	"strings"
+	"syscall"
 	"testing"
 )
 
@@ -17,6 +18,21 @@ import (
 
 // stubYtDlp writes an executable script that echoes the given stdout
 // and returns it as a provider config binary path.
+//
+// The write is held under syscall.ForkLock, and that is not tidiness:
+// the kernel refuses to exec a file that is open for writing anywhere
+// in the process, and these tests are parallel, so a *sibling* test's
+// fork can duplicate this descriptor in the moment it is open and
+// carry it past our close — the exec a moment later then fails with
+// ETXTBSY, "text file busy".  That is #146, seen once in CI and once
+// locally, on trees containing no Go at all.  Closing sooner is not
+// available (os.WriteFile has already closed the file before anything
+// execs it) and O_CLOEXEC does not help, because the window is between
+// another goroutine's fork and its own exec.  ForkLock is the lock
+// syscall.forkExec takes across that fork, so holding it here means no
+// child can exist while the descriptor does.  Measured on this helper
+// under 12 concurrent writers: 176-189 of 2400 execs refused without
+// it, 0 of 2400 with it.
 func stubYtDlp(t *testing.T, script string) string {
 	t.Helper()
 
@@ -26,9 +42,11 @@ func stubYtDlp(t *testing.T, script string) string {
 
 	path := filepath.Join(t.TempDir(), "yt-dlp")
 
-	if err := os.WriteFile(
-		path, []byte("#!/bin/sh\n"+script), 0o700,
-	); err != nil {
+	syscall.ForkLock.Lock()
+	err := os.WriteFile(path, []byte("#!/bin/sh\n"+script), 0o700)
+	syscall.ForkLock.Unlock()
+
+	if err != nil {
 		t.Fatalf("write stub: %v", err)
 	}
 

lefthook.yml

@@ -38,14 +38,10 @@ pre-commit:
       glob: "*.go"
       run: ./scripts/bindings-check.sh
 
-    # The docs document make targets; a stale one sends an agent — or a
-    # contributor reading CONTRIBUTING.md — off a cliff with total
-    # confidence.  The glob is the script's own scanned set, because a
-    # hook that does not fire on a file the check reads is the drift the
-    # check exists to prevent: it was `{Makefile,.pi/**/*.md}` while the
-    # script already read CLAUDE.md.  Instant.
+    # .pi/ documents make targets; a stale one sends an agent off a
+    # cliff with total confidence.  Instant.
     skill-check:
-      glob: "{Makefile,.pi/**/*.md,AGENTS.md,CLAUDE.md,README.md,CONTRIBUTING.md}"
+      glob: "{Makefile,.pi/**/*.md}"
       run: ./scripts/skill-check.sh
 
     frontend-typecheck:

scripts/skill-check.sh

@@ -14,11 +14,6 @@
 # missing: CLAUDE.md names 27 targets and nothing verified one of them,
 # so the file the agents trust most was the file least checked.
 #
-# README.md and CONTRIBUTING.md are in it too, and the header sentence
-# above is why: a person who has *not* read the Makefile goes looking in
-# the contributor-facing doc, so a renamed target sends them off the
-# same cliff it sends an agent off.  CONTRIBUTING.md names 21 targets.
-#
 # **AGENTS.md is a symlink to CLAUDE.md.**  This repo is worked on by
 # two agent harnesses that read different files by convention — Claude
 # Code reads CLAUDE.md, others read AGENTS.md — and two harnesses
@@ -48,19 +43,7 @@ if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
 	fi
 fi
 
-# The scan is over the docs that are actually there: a checkout without
-# .pi/ still has README.md and CONTRIBUTING.md to check, and gating the
-# whole run on .pi/ would have made the human-facing half conditional on
-# the agent-facing one.  This list is used twice — once to read the
-# mentions out and once to say which file a missing target came from —
-# because a second list is a second thing to forget.
-# `ls` exits non-zero when *any* of its arguments is missing while still
-# printing the ones that are there, and under `set -e` that would sink
-# the assignment rather than scanning what exists, so swallow it.
-docs="$({ find .pi -name '*.md' 2>/dev/null
-	ls CLAUDE.md README.md CONTRIBUTING.md 2>/dev/null || true; })"
-
-[ -n "$docs" ] || exit 0
+[ -d .pi ] || exit 0
 
 # `make -pq` prints the database including every rule, without running
 # anything.  It exits non-zero when a target is out of date, and under
@@ -85,7 +68,7 @@ targets="$({ make -pqRr 2>/dev/null || true; } |
 # AGENTS.md is deliberately not in this list: it is a symlink to
 # CLAUDE.md, asserted above, so scanning it would report every failure
 # twice under two names.
-mentioned="$(printf '%s\n' "$docs" |
+mentioned="$({ find .pi -name '*.md' 2>/dev/null; echo CLAUDE.md; } |
 	xargs awk '
 		FNR == 1 { fence = 0 }
 		/^```/   { fence = !fence; next }
@@ -110,10 +93,10 @@ for t in $mentioned; do
 done
 
 if [ -n "$missing" ]; then
-	echo "skill-check: the docs name make targets that do not exist:" >&2
+	echo "skill-check: the agent docs name make targets that do not exist:" >&2
 	for t in $missing; do
 		echo "  make $t" >&2
-		printf '%s\n' "$docs" | xargs grep -ln "make $t" | sed 's/^/      /' >&2
+		grep -rln "make $t" .pi CLAUDE.md --include='*.md' | sed 's/^/      /' >&2
 	done
 	echo "Fix the docs, or restore the target." >&2
 	exit 1