Fleet Doctor: incident-mode detection with preservation-first fixes

[aarontrowbridge]

Important

Scope. Slice 5 of Managed Fleet (#283 — read it first). The Fleet Doctor: one command that diagnoses the incident-observed failure modes and offers their one-click fixes — the automated form of the runbook a human executed by hand on 2026-08-07. Also the migration path: it detects legacy duct tape (a guard-shim configured as the server binary, a hand-rolled launchd tunnel agent, ssh-config Match blocks) and offers replacement with product primitives.

Acceptance Criteria

1. The Doctor detects all five incident modes — foreign process bound on the attach port, stray local store, tunnel down, identity mismatch, and unmerged Local-fallback data — each rendered with its one-click fix.
2. The stray-store fix is quarantine (move to a recovery dir), never deletion, and is gated on the store's merge state: an unmerged fallback store reports as its own incident mode instead.
3. Legacy duct tape on the author's fleet (guard shim in settings, launchd tunnel agent, ssh-config edits) is detected and a migration to slices 2–4 primitives is offered.
4. A healthy fleet reports healthy — no finding is ever a false positive (each detector has a negative test).

Testing Decisions

One test per detector per mode (positive + negative), with fixture filesystems/process stubs; the quarantine fix tested for preservation semantics (bytes moved, never unlinked); migration detection tested against fixtures mirroring the author's recorded legacy configuration. New doctor test surface; reuse the extension's exec/probe test idioms.

Key Decisions & Constraints

• The Doctor consumes the slice-4 state machine and adds diagnosis, not monitoring: it runs on demand, reports, and offers fixes — it is not a background watcher.
• Every fix is reversible or preservation-first (quarantine over delete) — a repair tool must not be able to destroy evidence.
• Parent constraints apply; slice-local: detectors are pure probes returning findings; fixes are separate, confirm-gated actions.

Source

Part of #283 · Design: docs/adr/0005-managed-fleet.md (PR #282) · Blocked by #287 (consumes the state machine's states).