Fix: launchd re-pin needs bootout, and never fake a successful start

[vivekchand]

The bug

The sync daemon's LaunchAgent pins an absolute interpreter path at install time (python = sys.executable). When that interpreter stops being able to import clawmetry, the running daemon survives, because Python holds imported modules in memory. It dies at the next restart, and every relaunch after that fails instantly:

/usr/local/bin/python3: Error while finding module specification for
'clawmetry.sync' (ModuleNotFoundError: No module named 'clawmetry')

The documented repair, clawmetry sync --restart, could not fix it. _register_launchd wrote the corrected plist but never booted the job out first:

• launchctl bootstrap refuses a label that is already registered
• the legacy load -w fallback also fails, while still exiting 0, so no return code could see it

So the corrected plist landed on disk, launchd kept running the definition it already held in memory, and the command printed Running in the background. Your data is syncing to the cloud. over a crash-looping daemon.

Reproduced against a real registered job before changing any code:

$ launchctl bootstrap gui/501 ~/Library/LaunchAgents/com.clawmetry.sync.plist
Bootstrap failed: 5: Input/output error          # rc=5
$ launchctl load -w ~/Library/LaunchAgents/com.clawmetry.sync.plist
Load failed: 5: Input/output error               # rc=0  <- the lie

Found on a founder node on 2026-10-14. The daemon had been dead about five hours, launchctl print showed runs = 12, last exit code = 1, and the stale ~/.clawmetry/local_query.json still advertised a dead pid and a refused port. Assistant, Setup and every other view that reads through the daemon rendered an empty state with no indication why, while the sync strip sat on Step: starting.

The fix

• bootout before bootstrap. The only sequence that makes launchd re-read the file, and therefore the only one that can re-pin a stale interpreter.
• Retry the bootstrap briefly, since bootout is asynchronous and bootstrapping too eagerly loses the race with teardown.
• Confirm the legacy path with a real lookup (launchctl print) instead of a return code that lies.
• Stop faking success. If the job did not register, clawmetry sync --restart says so, points at the log, and exits non-zero.
• The dashboard registrar had the same defect with kickstart -k as its fallback, which restarts the definition launchd already holds and so can never re-pin either. It now shares the corrected helper.

The NemoClaw sandbox registrar already did this correctly (Unload first in case it was already registered) and is unchanged.

Verification

• 9 new tests in tests/test_launchd_repin_requires_bootout.py: call ordering, absence of kickstart as a fallback, the untrustworthy load -w exit code, and both success and failure reporting.
• They were run against a simulation of the old behaviour first, and 3 of them failed there, so they catch the bug rather than describe the fix.
• 105 pass across test_daemon_registration, test_launchd_*, test_status_daemon_truth, test_daemon_spawn_pid_lock, test_onboard_local_default, test_desktop_supervisor_resilience, test_cloud_cta_oauth, test_login_bare_namespace.
• Passes on Python 3.9 as well as 3.11 (the lint job's floor).
• Ruff on the changed file: 404 findings, down from 405 on origin/main, no new rule classes.
• Wired into the lint job, so the ratchet counts it as listed (375 listed, was 374).

Known limits

This makes the repair work and makes a failed start visible. It does not yet detect the broken state on its own: a daemon whose interpreter loses the package still dies at the next restart, and the user learns about it from clawmetry status or the dashboard banner. Only the macOS paths changed; systemd and the Windows scheduled task are untouched.

No-PRD: production bug fix for a founder-reported dead daemon; FLYWHEEL 0c scopes requirement-first to "any change bigger than a bug fix", and writing a record after implementing is the 2026-08-25 anti-pattern that section exists to prevent.

🤖 Generated with Claude Code

[8090-software-factory]

⚠️ Drift Bot (ClawMetry): 2 potential drift finding(s)

1. Blueprint: Installer Scripts

File: clawmetry/cli.py:1894

The blueprint does not document the new launchd re-registration logic (bootout → bootstrap with retries and verification via launchctl print) that is now implemented in _register_launchd(). The blueprint should be updated to reflect that daemon registration now includes re-pinning the interpreter path when registration is re-run.

2. Blueprint: Local Observability Service

File: clawmetry/cli.py:1722

The blueprint documents daemon registration but does not specify that daemon registration failure (when launchd refuses the job) must result in a non-zero exit code. The updated _start_daemon() now returns bool and _cmd_sync() exits with code 1 on failure, but the blueprint contains no requirement for failure reporting or exit code behavior.

[8090-software-factory]

⚠️ Drift Bot (ClawMetry) — Blueprint: Installer Scripts

The blueprint does not document the new launchd re-registration logic (bootout → bootstrap with retries and verification via launchctl print) that is now implemented in _register_launchd(). The blueprint should be updated to reflect that daemon registration now includes re-pinning the interpreter path when registration is re-run.

[8090-software-factory]

⚠️ Drift Bot (ClawMetry) — Blueprint: Local Observability Service

The blueprint documents daemon registration but does not specify that daemon registration failure (when launchd refuses the job) must result in a non-zero exit code. The updated _start_daemon() now returns bool and _cmd_sync() exits with code 1 on failure, but the blueprint contains no requirement for failure reporting or exit code behavior.

[8090-software-factory]

✅ Drift Bot (ClawMetry): no drift detected

Drift Bot analyzed the changed files against this project's blueprints and requirements and found no drift.