Skip to content

Commit 045c4f9

Browse files
radroidclaude
authored andcommitted
fix(t3x): derive and verify the autobuild agent's PATH, and correct the runbook interval (#41)
Two traps from #41 that bite before any of the install-race work, both fork-owned (`scripts/t3x/**`, `docs/t3x/**`), zero upstream seam. ## 1. Regenerating the plist would silently downgrade the toolchain `--print-launchd` hardcoded its PATH. The live agent's is wider — it carries the fnm node directory, which the generator never knew about — so anyone following the runbook to regenerate the agent would quietly hand it a different PATH than the one that has been building successfully. `c33e5a361` already back-ported the `~/.cargo/bin` half of that gap, and that is the half with a loud failure: no cargo means `spawn cargo ENOENT` every tick, backing off forever. The node half is worse precisely because it is quiet. On this machine the hardcoded list still resolves node — to Homebrew's, which is v26.7.0, while `package.json`'s `engines.node` is `^24.13.1`. The build does not break. It succeeds against a toolchain nobody chose, and installs the result. So the PATH is now derived and then proved: - `derive_agent_path` resolves node, pnpm, cargo and git, following each symlink to a stable directory. That matters: a version manager's shim lives in a per-shell directory (fnm's is `~/.local/state/fnm_multishells/<pid>_<stamp>/bin`) that is deleted when the shell exits, so a shim path baked into a plist is a PATH entry that stops existing. A directory is added only when nothing already on the list provides that tool — which is what keeps corepack's `pnpm`, whose symlink lands in `.../corepack/dist` rather than a bin dir, from contributing an ephemeral entry: the node installation's own bin holds the shim and is already there. - `verify_agent_path` then runs each tool from an EMPTY environment, because that is what launchd gives the job — a check that inherits this shell's PATH proves nothing. It refuses to emit (exit 2) if a tool is unreachable, or if node's major does not match `engines.node`. `--force` emits anyway. On this machine the derived PATH matches the live agent's entry-for-entry. `--diff-launchd` is the missing feedback loop: launchd keeps the copy it was bootstrapped with, so a fix to the emitter never reaches a running agent and nothing reports the gap. It compares settings and ignores comments, so the notes hand-written into the live plist do not read as differences. Also emits `COREPACK_ENABLE_DOWNLOAD_PROMPT=0`, which the live plist has and the generator did not: corepack provides pnpm here against a pinned `packageManager`, and with no tty a download prompt has nobody to answer it. ## 2. The runbook documented a 2-minute loop `--interval`'s default was written as `60` (it is `43200`), the TL;DR said "every 60s", and all three examples passed `--interval 120`. Following them installs a two-minute quit/replace/relaunch cycle on an app hosting live Claude sessions and serving `:3773`. Corrected, and the install examples now show the flags the agent actually runs with, including `--ref origin/main`. Verified under /bin/bash 3.2 (what the plist invokes, and where expanding an empty array under `set -u` is an error): clean emit with zero stderr, `plutil -lint` OK, both refusal paths exit 2 emitting nothing, `--force` overrides, and `--diff-launchd` reports only the differences that are real. Refs #41 Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 1a223dc commit 045c4f9

2 files changed

Lines changed: 272 additions & 21 deletions

File tree

‎docs/t3x/auto-build-runbook.md‎

Lines changed: 66 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ scripts/t3x/auto-build-desktop.sh --install --dry-run
2121
# build + actually install (replaces the app in /Applications)
2222
scripts/t3x/auto-build-desktop.sh --install
2323

24-
# poll HEAD every 60s and rebuild+install on every new commit
24+
# poll HEAD every 12h (the default) and rebuild+install when it has moved
2525
scripts/t3x/auto-build-desktop.sh --watch --install
2626
```
2727

@@ -119,16 +119,24 @@ checkout — script changes take effect after that checkout is updated.
119119

120120
## Flags
121121

122-
| Flag | Meaning |
123-
| ----------------- | ------------------------------------------------------------------- |
124-
| `--install` | After a successful build, install the `.app` into `/Applications`. |
125-
| `--relaunch` | With `--install`, `open` the app afterwards. |
126-
| `--watch` | Poll `HEAD` forever; build (and install, if asked) on each new SHA. |
127-
| `--interval N` | Poll interval in seconds for `--watch` (default `60`). |
128-
| `--ref R` | Build remote ref `R` (e.g. `origin/main`) in a dedicated worktree. |
129-
| `--dry-run` | Log every step; never build, never touch `/Applications`. |
130-
| `--force` | Build even if `HEAD` is unchanged. |
131-
| `--print-launchd` | Emit a ready-to-use LaunchAgent plist on stdout. |
122+
| Flag | Meaning |
123+
| ----------------- | ------------------------------------------------------------------------------------- |
124+
| `--install` | After a successful build, install the `.app` into `/Applications`. |
125+
| `--relaunch` | With `--install`, `open` the app afterwards. |
126+
| `--watch` | Poll `HEAD` forever; build (and install, if asked) on each new SHA. |
127+
| `--interval N` | Poll interval in seconds for `--watch` (default `43200`, i.e. 12h). |
128+
| `--ref R` | Build remote ref `R` (e.g. `origin/main`) in a dedicated worktree. |
129+
| `--dry-run` | Log every step; never build, never touch `/Applications`. |
130+
| `--force` | Build even if `HEAD` is unchanged; also emits a plist that failed verification. |
131+
| `--print-launchd` | Emit a ready-to-use LaunchAgent plist on stdout. |
132+
| `--diff-launchd` | Diff that plist against the installed one. `0` same, `1` differs, `2` none installed. |
133+
134+
> **The interval is 12 hours on purpose, and the examples below use it.** Installing a
135+
> tighter loop by copying an example is not a small mistake: `--install` force-quits the
136+
> running app, replaces the bundle and reopens it, so a two-minute interval is a
137+
> two-minute quit/replace/relaunch cycle on an app that is hosting live Claude sessions
138+
> and serving `:3773`. Use a short interval only in a terminal (Option 3), while watching
139+
> it, and never with `--install`.
132140
133141
## Where things land
134142

@@ -197,11 +205,17 @@ TCC-protected repo path.
197205
> all, since a terminal already has the grant.
198206
199207
```bash
200-
scripts/t3x/auto-build-desktop.sh --print-launchd --install --interval 120 \
208+
scripts/t3x/auto-build-desktop.sh --print-launchd \
209+
--ref origin/main --install --relaunch --interval 43200 \
201210
> ~/Library/LaunchAgents/dev.t3x.autobuild.plist
202211
launchctl bootstrap "gui/$UID" ~/Library/LaunchAgents/dev.t3x.autobuild.plist
203212
```
204213
214+
These are the flags the agent on this machine actually runs with, and they are the ones to
215+
copy. `--ref origin/main` builds a fetched remote ref in a dedicated worktree rather than
216+
whatever branch the checkout happens to be on, so an agent working in the repo cannot change
217+
what gets installed.
218+
205219
**Verify it actually runs** — a loaded agent is not a working one:
206220

207221
```bash
@@ -222,13 +236,48 @@ rm ~/Library/LaunchAgents/dev.t3x.autobuild.plist
222236
`--print-launchd` substitutes the real repo path, script path, interval and log
223237
path, and mirrors `--install` into the emitted `ProgramArguments`.
224238

239+
#### The agent's `PATH` is derived, and verified before anything is emitted
240+
241+
A LaunchAgent does not inherit your shell's `PATH`. launchd starts jobs from a minimal
242+
environment with no login shell, so nothing `fnm`, `asdf`, `volta`, `nvm` or `rustup` writes
243+
into a shell profile is ever read — every directory the build needs has to be named in the
244+
plist. `--print-launchd` therefore resolves `node`, `pnpm`, `cargo` and `git` itself,
245+
following each symlink to a **stable** directory (a version manager's shim usually lives in a
246+
per-shell directory that is deleted when that shell exits, and baking one into a plist
247+
produces a `PATH` entry that quietly stops existing).
248+
249+
It then re-runs each tool from an _empty_ environment — the environment launchd will actually
250+
use — and **refuses to emit anything** if one is unreachable, or if `node` resolves to a
251+
different major version than `package.json`'s `engines.node` allows. Both refusals exit `2`
252+
and print what is wrong. `--force` emits anyway.
253+
254+
The version check earns its keep more than the missing-tool check does. A missing `cargo`
255+
fails loudly enough to find (`spawn cargo ENOENT`, every tick, backing off). A _wrong_ node
256+
does not fail at all: the system almost always has some other node, so the build succeeds and
257+
installs a binary built against a toolchain nobody chose.
258+
259+
Use `--diff-launchd` to see whether the installed agent still matches what the script would
260+
emit today. It compares settings and ignores comments, so hand-written notes in the live
261+
plist do not show up as differences:
262+
263+
```bash
264+
scripts/t3x/auto-build-desktop.sh --diff-launchd \
265+
--ref origin/main --install --relaunch --interval 43200
266+
```
267+
268+
Pass it the same flags the agent runs with — `launchctl print "gui/$UID/dev.t3x.autobuild"`
269+
shows what those were — or the only difference it reports will be the flags themselves.
270+
225271
> **A plist fix does not reach an already-installed agent.** launchd keeps the copy it was
226272
> bootstrapped with, so pulling a change to what `--print-launchd` emits — a new environment
227273
> variable, a wider `PATH` — leaves the running agent on the old one. Regenerate and reload:
228274
>
229275
> ```bash
276+
> scripts/t3x/auto-build-desktop.sh --diff-launchd \
277+
> --ref origin/main --install --relaunch --interval 43200 # see the gap first
230278
> launchctl bootout "gui/$UID/dev.t3x.autobuild"
231-
> scripts/t3x/auto-build-desktop.sh --print-launchd --install --interval 120 \
279+
> scripts/t3x/auto-build-desktop.sh --print-launchd \
280+
> --ref origin/main --install --relaunch --interval 43200 \
232281
> > ~/Library/LaunchAgents/dev.t3x.autobuild.plist
233282
> launchctl bootstrap "gui/$UID" ~/Library/LaunchAgents/dev.t3x.autobuild.plist
234283
> ```
@@ -268,9 +317,12 @@ rebase to trip over.
268317
### Option 3 — run the watcher in a terminal
269318
270319
```bash
271-
scripts/t3x/auto-build-desktop.sh --watch --install --interval 120
320+
scripts/t3x/auto-build-desktop.sh --watch --install --interval 43200
272321
```
273322
323+
A shorter `--interval` is reasonable here only _without_ `--install`: with it, every tick
324+
that finds a new SHA quits and replaces the running app.
325+
274326
In `--watch` mode the script re-execs itself under `caffeinate -s` so the Mac won't sleep
275327
mid-build; the re-exec forwards every flag, so `--watch --install --dry-run` stays a dry
276328
run. A failed build logs and the loop keeps polling (with backoff) — it never crashes

0 commit comments

Comments
 (0)