Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
  • Is something wrong?
#737 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
python, shell
Domain
devops, infrastructure, tooling

Research direction

Start by comparing scripts/launchd/* with the installed files under ~/.local/lib/brainlayer/, including the missing throughput-watchdog.py on locals-macbook-pro. Read the deployment context around the launchd jobs and the doctor subcommand, since CI cannot see this host. Done means a per-host check fails loudly for differing or missing files, and the watchdog fix is deployed before com.brainlayer.watch is re-enabled.

Written by the indexing model from the issue text.

Description

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

Dominant language
Python
Stars
9
Forks
7
Avg merge
4h 50m
Merged PRs (30d)
404

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from EtanHey/brainlayer

All issues in EtanHey/brainlayer

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.