@@ -21,7 +21,7 @@ scripts/t3x/auto-build-desktop.sh --install --dry-run
2121# build + actually install (replaces the app in /Applications)
2222scripts/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
2525scripts/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
202211launchctl 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
223237path, 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+
274326In ` --watch` mode the script re-execs itself under ` caffeinate -s` so the Mac won' t sleep
275327mid-build; the re-exec forwards every flag, so `--watch --install --dry-run` stays a dry
276328run. A failed build logs and the loop keeps polling (with backoff) — it never crashes
0 commit comments