Add agmsg doctor and viewer/status dashboard

[orangewk]

Motivation

While dogfooding agmsg across Codex Desktop and Claude Desktop on Windows, the hardest part was not only message delivery itself. It was knowing what was alive, what was configured, and where delivery was stuck.

agmsg already has useful pieces such as delivery.sh status, version.sh, config.sh, check-inbox.sh, readiness signals, and watcher/bridge liveness checks. But there does not seem to be a single user-facing command or viewer that answers the operational question:

Is this agmsg team healthy right now, and where should I look if it is not?

This became especially visible on Windows, where an old scheduled watcher/probe left many stale watch-once.sh / shell processes behind. A doctor/viewer would have made that much easier to spot.

Request

Add a small, official health/status surface. I think this is really two related features:

1. agmsg doctor

   • diagnostic, action-oriented
   • checks dependencies and runtime health
   • reports warnings and suggested next actions

2. agmsg viewer or agmsg status --team <team>

   • daily operational view
   • shows who is on the team, who appears live, delivery modes, unread counts, and recent delivery state

Useful checks

Possible doctor checks:

• installed version and whether it is from a release or git checkout
• bash, sqlite3, node, and relevant agent CLI availability
• whoami.sh resolves quickly for the current project/type
• current delivery mode: off, turn, monitor, etc.
• delivery.sh status result
• watch-once.sh --timeout 0 exits quickly and predictably
• stale watcher/bridge pidfiles or stale lock files
• stale runtime processes where detectable, especially watch-once.sh / bridge processes
• Windows-specific checks: Git Bash path, sqlite path/shim, .sh execution route, Codex bridge/watch route

Possible viewer/status fields:

• team members
• agent name, type, project path
• delivery mode per agent/project
• unread count per agent
• last check / last seen / last delivery when available
• watcher / bridge / monitor state
• stale process or stale lock warnings
• recent message flow summary

Relationship to existing features

This is not meant to replace delivery.sh status. It would sit above the existing pieces and give users one place to understand the system.

delivery.sh status answers part of the delivery configuration/liveness question. The requested doctor/viewer would answer the broader operational question across identity, team, delivery, unread state, dependencies, and stale runtime artifacts.

Why this matters

When agmsg is used as a real multi-agent workspace, users need confidence that:

• messages are not silently stuck
• the expected receiver is actually live or at least configured
• a delivery mode is active and healthy
• old experiments or stale monitors are not still running

Without this, failures feel like invisible mail routing problems. A lightweight doctor/viewer would make agmsg much easier to operate and debug.

[fujibee]

@orangewk

Thank you for this, and apologies that it sat unanswered for so long. We are going to build a doctor command, and your list of checks is what we are starting from — it is more thought-through than anything we would have written cold.

The first cut focuses on the operational-state half rather than the dependency sweep. For a given project it will show the registrations, which roles hold an actas lock and whether that lock's owner is actually alive, which have a live watcher or bridge, and the delivery mode — plus warnings for the states that are silently wrong. Two of those have bitten people this week and are invisible today: a lock whose owner is no longer live, and several registrations under one project and type, where turn mode only ever delivers to the first of them.

We are starting with a single command rather than a separate viewer. The state listing you described is most of what a daily view would show anyway, and one command is easier to point people at — the goal is to be able to answer a bug report with "please run agmsg doctor". If a daily-use surface turns out to want something different, we can add it once we know what people actually look at.

Two things we took from how claude doctor and codex doctor are shaped: it will be read-only, with anything that repairs state kept separate, so that running it never destroys the evidence you ran it to collect; and it will offer a redacted mode, since the output is meant to be pasted into issues and you should not have to censor paths and session ids by hand.

Dependency and Windows-path checks are not in the first cut, but they stay on the list.

[orangewk]

Closing this issue as completed for the current scope.

The read-only doctor command requested here shipped in v1.2.0, and it provides the operational visibility we needed for registrations, locks, watchers, bridges, and delivery warnings. We are not pursuing a separate viewer/dashboard at this time; if that becomes useful later, it should be opened as a narrower follow-up based on actual usage.

The remaining human-facing documentation work can proceed independently in #660 and #661.