commit 3d9bc4d32183ef541f447c15f9b6ae7641815f31
parent 1aa818bb580cd8aff4a6f5e6a2ce6b8ead176a30
Author: I Mean I'm Just Saying <imeanimjustsaying@kiwifarms.st>
Date: Sat, 19 Sep 2026 15:41:20 -0400
docs: the root `pnpm e2e` is the editor's, whatever spec you name it
`pnpm run e2e clip-bench.spec.ts` looks like it runs one umtool spec. It is
`pnpm --filter editor run e2e`, so the name is handed to the editor's
playwright, matches nothing, and the ~24-minute editor suite runs behind the
machine-global lock instead — the most expensive possible way to run no test
at all.
Records the per-package commands, and why umtool's needs SONG_DIR: the suite
never runs against the real song dir, but make-fixture.mjs READS it to derive
the empty-state copy and symlink the heavy audio, and its default is the
job-temp path that data was mined into and has since left.
Also corrects the queued-suites list, which omitted homepage and umtool.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Diffstat:
2 files changed, 42 insertions(+), 5 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
@@ -17,6 +17,21 @@ suite is ~24 minutes. A run that wins the lock but finds its ports already bound
names the offending pid, instead of silently driving another session's server. Bypasses:
`E2E_QUEUE=0`, `E2E_PORT_CHECK=0`, `E2E_QUEUE_TIMEOUT=<seconds>`.
+**`pnpm e2e` at the root is the EDITOR suite**, whatever spec name you append to it: the
+script is `pnpm --filter editor run e2e`, so `pnpm run e2e clip-bench.spec.ts` takes the
+global lock for ~24 minutes of somebody else's tests and never runs the spec you named. A
+package's own suite is run through its own filter — umtool's is:
+
+```sh
+SONG_DIR=~/reports/quartering-uh-song/data pnpm --filter umtool run e2e clip-bench.spec.ts
+```
+
+`SONG_DIR` is read by `umtool/song/paths.mjs` when `e2e/fixtures/make-fixture.mjs` builds
+the fixture. The suite never *runs* against the real song dir — it reads it to derive an
+empty-state copy and to symlink the heavy audio — but without it the fixture build looks
+for that data at its original job-temp path and fails. umtool's suite is queued like every
+other.
+
See [WORKTREES.md](WORKTREES.md) for the port scheme, the queue, and the shared-data caveat.
# Working this repo with no local corpus
diff --git a/WORKTREES.md b/WORKTREES.md
@@ -87,11 +87,33 @@ queue-lock: still waiting (5m00s)
**A long wait here is normal, not a hang** — the serial suite is ~24 minutes.
-Queued: `pnpm e2e`, `pnpm e2e:sharded` (including its `docker build`), and export's `e2e`,
-`e2e:hub`, `e2e:2origin`. Wrapping is at the *package* level, so `pnpm --filter editor run
-e2e` is covered too, and a nested invocation passes through instead of deadlocking. Not
-queued on purpose: a raw `pnpm --filter editor exec playwright test`, the escape hatch for
-debugging a single spec, and the `e2e:ui` interactive sessions.
+Queued: `pnpm e2e`, `pnpm e2e:sharded` (including its `docker build`), export's `e2e`,
+`e2e:hub`, `e2e:2origin`, and homepage's and umtool's `e2e`. Wrapping is at the *package*
+level, so `pnpm --filter editor run e2e` is covered too, and a nested invocation passes
+through instead of deadlocking. Not queued on purpose: a raw `pnpm --filter editor exec
+playwright test`, the escape hatch for debugging a single spec, and the `e2e:ui`
+interactive sessions.
+
+### Root `pnpm e2e` is the editor's, and only the editor's
+
+The root script is `pnpm --filter editor run e2e`, so a spec name appended to it goes to
+the **editor's** playwright: `pnpm run e2e clip-bench.spec.ts` matches nothing there, holds
+the machine-global lock for the whole ~24-minute editor suite, and never runs the spec you
+meant. Every other package's suite goes through its own filter:
+
+| Suite | Command |
+|---|---|
+| editor | `pnpm e2e [spec…]` |
+| export | `pnpm --filter export run e2e` (also `e2e:hub`, `e2e:2origin`) |
+| homepage | `pnpm --filter homepage run e2e` |
+| umtool | `SONG_DIR=~/reports/quartering-uh-song/data pnpm --filter umtool run e2e [spec…]` |
+
+umtool needs `SONG_DIR` because `e2e/fixtures/make-fixture.mjs` builds its fixture *from*
+the song project's bulk data (`umtool/song/paths.mjs` resolves it, and its default is the
+job-temp path that data was mined into, which no longer exists). The suite itself never
+runs against that directory — the fixture is an empty-state copy with the heavy audio
+symlinked in — but the fixture build reads it, so a run without `SONG_DIR` fails before the
+test server starts.
The lock lives at `<git-common-dir>/e2e-queue.lock`, which resolves to the same file from
every worktree. The kernel releases it when the holding process's fd closes, so a `kill -9`
