halton-meter rescue

halton-meter rescue is the nuclear-but-recoverable option. Use it when halton-meter doctor --fix --apply doesn’t fix the problem, when the supervisor is in a respawn loop you can’t break, or when a partial upgrade left LaunchAgent state half-rewritten.

Rescue preserves:

• ~/.halton-meter/db.sqlite — your captured data
• ~/.halton-meter/config.toml — your config
• ~/.mitmproxy/mitmproxy-ca-cert.pem — the CA cert
• macOS Keychain trust state for the CA
• ~/.halton-meter/cloud-credentials.json — your cloud pairing (if any)

Rescue rebuilds:

• All four LaunchAgent plists (com.haltonlabs.meter, meter.watchdog, meter.edge, meter.userenv)
• The launchctl user-domain env block
• The shell rc block (.zshrc / .bashrc) — re-written from scratch
• The certifi patch inside the daemon’s venv
• The sentinel files under ~/.halton-meter/ that describe install mode

Synopsis

halton-meter rescue [--apps|--full|--no-apps]

If no flag is given, rescue reads the prior install mode from the sentinels and reuses it. If no prior install is detected (fresh laptop, clean home directory), rescue refuses and asks you to run halton-meter init instead.

What rescue does, step by step

The reference is daemon/halton_meter/cli.py::rescue().

1. Boot out every LaunchAgent. launchctl bootout gui/$UID/com.haltonlabs.meter (and the three siblings). Ignores errors — if the agent isn’t loaded, that’s fine.
2. SIGKILL any orphan processes. pkill -9 -f "halton-meter (daemon|edge|watchdog)". Catches the processes whose plists were removed but whose runtime survived (launchctl unload followed by pkill is the safe pattern).
3. Wait 2 seconds for ports to release.
4. Run halton-meter init --clean with the resolved mode. --clean tells init to discard prior plists rather than diff against them — the trust state for the cert is preserved, but every other piece of supervisor state is rebuilt fresh.
5. Run a self-test with a 30-second budget. If the self-test fails, rescue exits non-zero and prints the daemon log tail.

The sequence is intentionally aggressive. It does not consult the prior state for decisions about what to keep — by the time you reach rescue, “the prior state” is what’s broken.

When to use rescue vs init --clean vs uninstall

• doctor --fix --apply — first line. Fixes the named, safe failures without changing supervisor topology.
• init (no flag) — second line. Idempotent and reconciles state in place. Most “I changed mode” situations don’t need rescue.
• init --clean — when init is reporting that prior state is inconsistent and you want to discard it. Less aggressive than rescue because it doesn’t boot out + SIGKILL first.
• halton-meter rescue — when the supervisor itself is broken (respawn loops, plists in a half-written state, processes whose plists were removed but who keep restarting).
• halton-meter uninstall — when you want Halton Meter off the machine. Restores the prior system proxy from snapshot. Optionally also --purge --include-logs to remove ~/.halton-meter/.

What rescue does not do

• It does not delete db.sqlite. If you want a clean slate including captured data, run halton-meter uninstall --purge --include-logs and then init from scratch.
• It does not regenerate the CA cert. A re-issued cert would invalidate every shell, app, and Spotlight-launched process’s certifi patch — too destructive for a rescue.
• It does not re-pair the cloud. The token survives.
• It is not implemented on Linux or Windows yet. On Linux, the manual sequence is documented in Troubleshooting → Linux. On Windows, the equivalent is halton-meter init --clean.

Sample run

$ halton-meter rescue --apps
⚠  Rescue: aggressive reset. Preserves db.sqlite, config, cert. Rebuilds supervisor.
  1/5  Booting out LaunchAgents…
✓       com.haltonlabs.meter           bootout ok
✓       com.haltonlabs.meter.watchdog  bootout ok
✓       com.haltonlabs.meter.edge      bootout ok
✓       com.haltonlabs.meter.userenv   bootout ok
  2/5  SIGKILL'ing orphan processes…
✓       2 processes terminated
  3/5  Waiting 2s for ports to release…
  4/5  Running halton-meter init --clean --apps…
✓       launchd registered (4/4 plists)
✓       shell rc updated  ~/.zshrc
✓       certifi patched
  5/5  Self-test…
✓       daemon healthy    edge: 127.0.0.1:8081  api: 127.0.0.1:8765
✓       Rescue complete.

Exit codes

See also

• halton-meter doctor — diagnose before you nuke
• halton-meter init — the idempotent first-line reset
• halton-meter uninstall — when you want Halton Meter gone
• Troubleshooting — symptom-driven recovery before reaching for rescue
• Troubleshooting → Daemon won’t start — the most common rescue trigger