Add a self-service doctor command

[MPIsaac-Per]

Goal

Provide one command that diagnoses the common causes of a bridge installation failing before the user has to inspect launchd logs or webhook traffic.

Proposed interface

npm run doctor

Checks

• Supported Node version
• Claude Code/runtime availability and login state where safely detectable
• Required Linear application configuration
• OAuth redirect URI consistency
• Refresh-token store presence, shape, and permissions
• KB_PATH existence and readability
• Session/inbox/outbox store writability
• Local health endpoint
• Public HTTPS webhook URL configuration
• Tailscale status when Tailscale is selected

Acceptance criteria

• Every check prints pass, warning, or fail with a remediation step.
• The command never prints access tokens, refresh tokens, client secrets, prompts, or issue contents.
• Exit status is nonzero for blocking failures.
• Checks are testable without contacting real Linear or Anthropic services.

---

Linear execution plan

GitHub remains the public source of truth. Private prioritization, dependencies, and agent execution are tracked in the Linear Agent Bridge OSS project.

Parent: MPI-1431

• MPI-1432 — Build a testable doctor command framework with safe output
• MPI-1433 — Add local runtime, OAuth, path, and store doctor checks
• MPI-1434 — Add health, webhook ingress, and Tailscale doctor checks

Implementation tickets are labeled agent-ready in Linear and include scope, acceptance criteria, dependencies, repository constraints, and required verification evidence. Public decisions and completion status should be mirrored back to this issue.

[MPIsaac-Per]

deploy/verify-ingress.sh now covers part of what the ingress check here would do, and the way it was wrong first is worth carrying into the doctor design.

The original script probed the webhook URL with plain curl. On the deployment host that resolves through MagicDNS to a private Tailscale address, so it verified the private path and reported public ingress healthy. The service was in fact unreachable from Linear. It now resolves the hostname through public resolvers (VERIFY_INGRESS_RESOLVERS, default 1.1.1.1,8.8.8.8), probes every returned address with curl --resolve, and reports split-horizon explicitly when the local answer differs from the public one.

Two design points for the doctor:

1. A network check that uses the host's own resolver proves nothing about reachability from outside. Force the address.
2. "Reports healthy" is not the same as "tested the thing you meant". This is worth an explicit test per check, asserting the check fails when the condition it guards is broken.

Also useful on this host, from a live migration: the public URL carried a non-default port (8443, because 443 was taken), and the failure mode of omitting it was a connection that hung rather than refused. A doctor check that compares the configured public URL against what is actually listening would have caught that in seconds.