Deploy drift: ~/.local/lib/brainlayer helpers are never synced from scripts/launchd — a fix merged 2026-08-08 was still undeployed on 08-24 and killed the watcher 991 times

[EtanHey]

Problem

The launchd helper scripts in ~/.local/lib/brainlayer/ are not kept in sync with
scripts/launchd/, nothing detects it, and on 2026-08-24 that cost 991 process kills.

scripts/launchd/throughput-watchdog.py gained a starvation guard in
PR #667 "fix: prevent checkpoint starvation and watchdog freeze" — progress_slo_seconds: int = 180
plus operational progress tracking (offset_bytes / drain_cycles / drained_total), so a watcher
that is advancing its file offsets but slow to commit a chunk is not counted as stalled.

The copy that actually executes did not contain the string progress_slo_seconds at all:

installed  ~/.local/lib/brainlayer/throughput-watchdog.py   2026-07-18
repo       scripts/launchd/throughput-watchdog.py           2026-08-08   (PR #667)
$ grep -c progress_slo_seconds ~/.local/lib/brainlayer/throughput-watchdog.py
0

Merged 2026-08-08, still not deployed 2026-08-24. Meanwhile
~/.local/share/brainlayer/health-check-state.json recorded:

"restart_count": 991, "restart_attempt_count": 1071

That stale artifact launchctl kickstart -k'd (SIGKILL) the watcher 991 times, because it could
not tell "wedged" from "CPU-starved". The fix for that had been sitting in main for over two weeks.

It is not one file

file	installed	repo
throughput-watchdog.py	2026-07-18	2026-08-08	STALE
backup-daily.sh	2026-08-15	2026-08-17	STALE
jsonl-backup.sh	2026-06-26	2026-06-18	STALE
tier0-watchdog.sh	2026-07-10	2026-07-13	STALE
brainlayer-env-run.sh	—	—	same

The brainlayer CLI itself was fine (1.5.9 = repo main), so watch/drain ran current code. Only
these helpers drifted — which is exactly why nobody noticed.

Cross-machine: the M1 Pro has a different drift

Evidence-only probe of locals-macbook-pro (Apple M1 Pro) the same day:
~/.local/lib/brainlayer/ contains backup-daily.sh, brainlayer-env-run.sh,
hotlane_brainbar_daemon.py, jsonl-backup.sh — and throughput-watchdog.py is absent entirely
(no watchdog installed at all). Also note it does have an installed hotlane_brainbar_daemon.py,
where the M4 runs that daemon straight from the dev working tree (see #733 comment). So a drift check
must be per-host, and "installed" cannot be assumed to mean "the same set".

Acceptance criteria

• A check that diffs ~/.local/lib/brainlayer/* against scripts/launchd/* and fails loudly on
  drift, including missing files, not just different ones.
• It runs somewhere it will actually be seen (CI cannot see this host; a launchd job or a doctor
  subcommand can).
• Deploying the watchdog fix is a prerequisite for re-enabling com.brainlayer.watch — bringing the
  watcher back under the stale watchdog restarts the 991-kill loop.

Related: #675 (deployed binary pinned/stale — same "merged ≠ deployed" class, different artifact),
#733 (LaunchAgent interpreter drift), #734 / #611 / #672 / #732 (the loop this caused).

— brainlayerClaude (lead) · claude-code/claude-opus-5

[EtanHey]

Adding a property discovered today that any drift detector here must account for.

A plain pytest run on this repo shells out to the REAL scripts/launchd/install.sh with target="all".

install_launchd() defaults to target="all" and resolves get_launchd_dir() to the current checkout, so in a worktree the process line reads:

/Users/etanheyman/Gits/brainlayer/.worktrees/<name>/scripts/launchd/install.sh all

That is indistinguishable in ps from a real deploy off a feature branch — which is the exact anti-pattern this issue exists to catch (deployed ≠ merged).

It is safe today only because tests/test_installable_build.py sandboxes HOME to a tmp_path, and install.sh derives every target from $HOME:

scripts/launchd/install.sh:57   LAUNCH_DIR="$HOME/Library/LaunchAgents"
scripts/launchd/install.sh:60   BRAINLAYER_LIB_DIR="$HOME/.local/lib/brainlayer"

Verified on a live occurrence: find ~/Library/LaunchAgents ~/.local/lib/brainlayer -newermt "30 minutes ago" returned nothing, and no label was bootstrapped.

Two consequences for whoever builds the drift check:

1. Do not treat "install.sh is running" as evidence of a deploy — check for writes to the real paths, not for the process.
2. Conversely, do not let the sandboxed test invocation mask a genuine bad deploy. The distinguishing signal is the effective $HOME, not the script path.

Side observation: this test writes a full LaunchAgent + lib layout to disk on every full test run, which triggers an XProtect scan (observed: launchd ~15%, XprotectService ~20%) and is perceptible as UI lag on a loaded machine.

— brainlayerClaude (lead) · claude-code/claude-opus-5