feat(doctor): wire into the 9 per-type templates, the Windows dispatcher, and the plugin-path SKILL.md

SKILL.md

@@ -32,6 +32,8 @@ fi
 
 After this runs once, `~/.agents/skills/agmsg/` is populated and you can skip Step 0 on future invocations.
 
+**If the argument/intent is `doctor` (with or without further flags): do NOT run whoami.sh, do NOT enter the join flow (Steps 1-2a). Go straight to the `doctor.sh` line under Step 2b and stop there.** `doctor` reports the health of the whole installation and exists specifically for when registration or delivery is broken — it must work even before you have an identity, so it never goes through Steps 1-2a.
+
 ### Step 1: Check identity
 
 ```bash
@@ -155,6 +157,14 @@ Do NOT manually edit config files. Always use join.sh. If the name was recently
 #   --force              tear down from the recorded placement, no message
 #   --timeout N          seconds to wait for graceful teardown (default 30)
 ~/.agents/skills/agmsg/scripts/despawn.sh <team> <from> <name> [--force] [--timeout N]
+
+# Read-only health check: registrations, actas lock status, and delivery mode
+# per (project, type). Default (no flags) covers the WHOLE installation —
+# every team, project, and type — not just the current one; narrow with
+# --project/--type/--team (combinable) only when asked to. Exit codes: 0
+# clean, 1 one or more warnings, 2 usage/resolution error. --redacted masks
+# paths and names, safe to paste into a report.
+~/.agents/skills/agmsg/scripts/doctor.sh [--project <path>] [--type <type>] [--team <team>] [--redacted]
 ```
 
 ## Permission prompts (Claude Code)

scripts/drivers/types/antigravity/template.md

@@ -7,6 +7,8 @@ Agent messaging command. **IMPORTANT: Always use the provided scripts. NEVER dir
 
 **Shell requirement:** All agmsg scripts are Bash scripts. Always execute them via `bash`, never via PowerShell or cmd directly. If your default shell is not Bash (e.g. PowerShell on Windows), wrap every command with `bash -lc '...'`. Example: `bash -lc '~/.agents/skills/__SKILL_NAME__/scripts/send.sh myteam alice bob "hello"'`. Do NOT construct DB paths manually — the scripts handle path resolution internally. If you need to redirect storage, use `AGMSG_STORAGE_PATH` (the supported override).
 
+**If the argument is "doctor" (with or without further flags): do NOT run whoami.sh, do NOT enter the join flow below. Go straight to the "doctor" entry under Execute and stop there.** `doctor` reports the health of the whole installation and exists specifically for when registration or delivery is broken — it must work even before you have an identity, so it never goes through the section below.
+
 ## Identity
 
 If you already know your AGENT and TEAMS from a previous `$__SKILL_NAME__` call in this session, skip to **Execute** below.
@@ -42,6 +44,7 @@ Four possible outputs:
   > - `$__SKILL_NAME__ send <agent> <message>` — send a message
   > - `$__SKILL_NAME__ team` — list team members
   > - `$__SKILL_NAME__ history` — message history
+  > - `$__SKILL_NAME__ doctor` — check registration/lock/delivery health across the installation
 
   5. **REQUIRED — Do NOT skip this step.** Ask the user to pick a delivery mode using exactly this prompt:
 
@@ -133,6 +136,15 @@ If argument is "hook off" (legacy alias):
 1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/delivery.sh set off antigravity "$(pwd)"`
 2. Tell the user: "Delivery mode set to 'off'."
 
+If argument is "doctor" (no further args):
+1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/doctor.sh`
+2. Show the output to the user. Exit code: 0 = clean, 1 = one or more warnings (the output still shows everything -- show it in full), 2 = usage/resolution error.
+
+If argument starts with "doctor" followed by flags (e.g. "doctor --project /path/to/project"):
+1. Pass the flags straight through: `~/.agents/skills/__SKILL_NAME__/scripts/doctor.sh <flags>`
+2. Supported flags, all optional and combinable: `--project <path>`, `--type <type>`, `--team <team>`, `--redacted` (masks paths and names, safe to paste into a report). Only use these when the user explicitly asks to narrow the scope -- bare `doctor` (no flags) already covers the whole installation and is the normal way to run it.
+3. Show the output to the user.
+
 If argument is "reset":
 1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/reset.sh "$(pwd)" antigravity`
 2. Tell the user the result.

scripts/drivers/types/claude-code/template.md

@@ -6,6 +6,8 @@ Agent messaging command. **IMPORTANT: Always use the provided scripts. NEVER dir
 
 **Shell requirement:** All agmsg scripts are Bash scripts. Always execute them via `bash`, never via PowerShell or cmd directly. If your default shell is not Bash (e.g. PowerShell on Windows), wrap every command with `bash -lc '...'`. Example: `bash -lc '~/.agents/skills/__SKILL_NAME__/scripts/send.sh myteam alice bob "hello"'`. Do NOT construct DB paths manually — the scripts handle path resolution internally. If you need to redirect storage, use `AGMSG_STORAGE_PATH` (the supported override).
 
+**If the argument is "doctor" (with or without further flags): do NOT run whoami.sh, do NOT enter the join flow below. Go straight to the "doctor" entry under Execute and stop there.** `doctor` reports the health of the whole installation and exists specifically for when registration or delivery is broken — it must work even before you have an identity, so it never goes through the section below.
+
 ## Identity
 
 If you already know your AGENT and TEAMS from a previous `/__SKILL_NAME__` call in this session, skip to **Execute** below.
@@ -46,6 +48,7 @@ Four possible outputs:
   > - `/__SKILL_NAME__ drop <name>` — remove a role from this project
   > - `/__SKILL_NAME__ spawn <type> <name>` — launch a new agent in a tmux pane / terminal and have it actas <name>
   > - `/__SKILL_NAME__ despawn <name>` — tear down a member you spawned (graceful, or `--force`)
+  > - `/__SKILL_NAME__ doctor` — check registration/lock/delivery health across the installation
 
   5. **REQUIRED — Do NOT skip this step.** Ask the user to pick a delivery mode using exactly this prompt:
 
@@ -232,6 +235,15 @@ If argument is "version":
 1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/version.sh`
 2. Show the output — the installed version (git-describe provenance recorded at install time).
 
+If argument is "doctor" (no further args):
+1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/doctor.sh`
+2. Show the output to the user. Exit code: 0 = clean, 1 = one or more warnings (the output still shows everything -- show it in full), 2 = usage/resolution error.
+
+If argument starts with "doctor" followed by flags (e.g. "doctor --project /path/to/project"):
+1. Pass the flags straight through: `~/.agents/skills/__SKILL_NAME__/scripts/doctor.sh <flags>`
+2. Supported flags, all optional and combinable: `--project <path>`, `--type <type>`, `--team <team>`, `--redacted` (masks paths and names, safe to paste into a report). Only use these when the user explicitly asks to narrow the scope -- bare `doctor` (no flags) already covers the whole installation and is the normal way to run it.
+3. Show the output to the user.
+
 If argument is "reset":
 1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/reset.sh "$(pwd)" claude-code`
 2. Tell the user the result.

scripts/drivers/types/codex/template.md

@@ -7,6 +7,8 @@ Agent messaging command. **IMPORTANT: Always use the provided scripts. NEVER dir
 
 **Shell requirement:** All agmsg scripts are Bash scripts. Always execute them via `bash`, never via PowerShell or cmd directly. If your default shell is not Bash (e.g. PowerShell on Windows), wrap every command with `bash -lc '...'`. Example: `bash -lc '~/.agents/skills/__SKILL_NAME__/scripts/send.sh myteam alice bob "hello"'`. Always single-quote the `bash -lc` payload; NEVER use a double-quoted wrapper with escaped inner quotes (e.g. `bash -lc "... \"$PWD\" ..."`) — PowerShell parses `\"` as a literal backslash that terminates the string, silently corrupting the command and dropping everything after it. Do NOT construct DB paths manually — the scripts handle path resolution internally. If you need to redirect storage, use `AGMSG_STORAGE_PATH` (the supported override).
 
+**If the argument is "doctor" (with or without further flags): do NOT run whoami.sh, do NOT enter the join flow below. Go straight to the "doctor" entry under Execute and stop there.** `doctor` reports the health of the whole installation and exists specifically for when registration or delivery is broken — it must work even before you have an identity, so it never goes through the section below.
+
 ## Identity
 
 If you already know your AGENT and TEAMS from a previous `$__SKILL_NAME__` call in this session, skip to **Execute** below.
@@ -48,6 +50,7 @@ Four possible outputs:
   > - `$__SKILL_NAME__ send <agent> <message>` — send a message
   > - `$__SKILL_NAME__ team` — list team members
   > - `$__SKILL_NAME__ history` — message history
+  > - `$__SKILL_NAME__ doctor` — check registration/lock/delivery health across the installation
 
   5. **REQUIRED — Do NOT skip this step.** Ask the user to pick a delivery mode using exactly this prompt:
 
@@ -167,6 +170,15 @@ If argument is "version":
 1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/version.sh`
 2. Show the output — the installed version (git-describe provenance recorded at install time).
 
+If argument is "doctor" (no further args):
+1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/doctor.sh`
+2. Show the output to the user. Exit code: 0 = clean, 1 = one or more warnings (the output still shows everything -- show it in full), 2 = usage/resolution error.
+
+If argument starts with "doctor" followed by flags (e.g. "doctor --project /path/to/project"):
+1. Pass the flags straight through: `~/.agents/skills/__SKILL_NAME__/scripts/doctor.sh <flags>`
+2. Supported flags, all optional and combinable: `--project <path>`, `--type <type>`, `--team <team>`, `--redacted` (masks paths and names, safe to paste into a report). Only use these when the user explicitly asks to narrow the scope -- bare `doctor` (no flags) already covers the whole installation and is the normal way to run it.
+3. Show the output to the user.
+
 If argument is "reset":
 1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/reset.sh "$(pwd)" codex`
 2. Tell the user the result.

scripts/drivers/types/copilot/template.md

@@ -7,6 +7,8 @@ Agent messaging command. **IMPORTANT: Always use the provided scripts. NEVER dir
 
 **Shell requirement:** All agmsg scripts are Bash scripts. Always execute them via `bash`, never via PowerShell or cmd directly. If your default shell is not Bash (e.g. PowerShell on Windows), wrap every command with `bash -lc '...'`. Example: `bash -lc '~/.agents/skills/__SKILL_NAME__/scripts/send.sh myteam alice bob "hello"'`. Do NOT construct DB paths manually — the scripts handle path resolution internally. If you need to redirect storage, use `AGMSG_STORAGE_PATH` (the supported override).
 
+**If the argument is "doctor" (with or without further flags): do NOT run whoami.sh, do NOT enter the join flow below. Go straight to the "doctor" entry under Execute and stop there.** `doctor` reports the health of the whole installation and exists specifically for when registration or delivery is broken — it must work even before you have an identity, so it never goes through the section below.
+
 ## Identity
 
 If you already know your AGENT and TEAMS from a previous `/__SKILL_NAME__` call in this session, skip to **Execute** below.
@@ -42,6 +44,7 @@ Four possible outputs:
   > - `/__SKILL_NAME__ send <agent> <message>` — send a message
   > - `/__SKILL_NAME__ team` — list team members
   > - `/__SKILL_NAME__ history` — message history
+  > - `/__SKILL_NAME__ doctor` — check registration/lock/delivery health across the installation
 
   5. **REQUIRED — Do NOT skip this step.** Ask the user to pick a delivery mode using exactly this prompt:
 
@@ -133,6 +136,15 @@ If argument is "hook off" (legacy alias):
 1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/delivery.sh set off copilot "$(pwd)"`
 2. Tell the user: "Delivery mode set to 'off'."
 
+If argument is "doctor" (no further args):
+1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/doctor.sh`
+2. Show the output to the user. Exit code: 0 = clean, 1 = one or more warnings (the output still shows everything -- show it in full), 2 = usage/resolution error.
+
+If argument starts with "doctor" followed by flags (e.g. "doctor --project /path/to/project"):
+1. Pass the flags straight through: `~/.agents/skills/__SKILL_NAME__/scripts/doctor.sh <flags>`
+2. Supported flags, all optional and combinable: `--project <path>`, `--type <type>`, `--team <team>`, `--redacted` (masks paths and names, safe to paste into a report). Only use these when the user explicitly asks to narrow the scope -- bare `doctor` (no flags) already covers the whole installation and is the normal way to run it.
+3. Show the output to the user.
+
 If argument is "reset":
 1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/reset.sh "$(pwd)" copilot`
 2. Tell the user the result.

scripts/drivers/types/cursor/template.md

@@ -7,6 +7,8 @@ Agent messaging command. **IMPORTANT: Always use the provided scripts. NEVER dir
 
 **Shell requirement:** All agmsg scripts are Bash scripts. Always execute them via `bash`, never via PowerShell or cmd directly. If your default shell is not Bash (e.g. PowerShell on Windows), wrap every command with `bash -lc '...'`. Example: `bash -lc '~/.agents/skills/__SKILL_NAME__/scripts/send.sh myteam alice bob "hello"'`. Do NOT construct DB paths manually — the scripts handle path resolution internally. If you need to redirect storage, use `AGMSG_STORAGE_PATH` (the supported override).
 
+**If the argument is "doctor" (with or without further flags): do NOT run whoami.sh, do NOT enter the join flow below. Go straight to the "doctor" entry under Execute and stop there.** `doctor` reports the health of the whole installation and exists specifically for when registration or delivery is broken — it must work even before you have an identity, so it never goes through the section below.
+
 ## Identity
 
 If you already know your AGENT and TEAMS from a previous `$__SKILL_NAME__` call in this session, skip to **Execute** below.
@@ -42,6 +44,7 @@ Four possible outputs:
   > - `$__SKILL_NAME__ send <agent> <message>` — send a message
   > - `$__SKILL_NAME__ team` — list team members
   > - `$__SKILL_NAME__ history` — message history
+  > - `$__SKILL_NAME__ doctor` — check registration/lock/delivery health across the installation
 
   5. **REQUIRED — Do NOT skip this step.** Ask the user to pick a delivery mode using exactly this prompt:
 
@@ -136,6 +139,15 @@ If argument is "version":
 1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/version.sh`
 2. Show the output — the installed version (git-describe provenance recorded at install time).
 
+If argument is "doctor" (no further args):
+1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/doctor.sh`
+2. Show the output to the user. Exit code: 0 = clean, 1 = one or more warnings (the output still shows everything -- show it in full), 2 = usage/resolution error.
+
+If argument starts with "doctor" followed by flags (e.g. "doctor --project /path/to/project"):
+1. Pass the flags straight through: `~/.agents/skills/__SKILL_NAME__/scripts/doctor.sh <flags>`
+2. Supported flags, all optional and combinable: `--project <path>`, `--type <type>`, `--team <team>`, `--redacted` (masks paths and names, safe to paste into a report). Only use these when the user explicitly asks to narrow the scope -- bare `doctor` (no flags) already covers the whole installation and is the normal way to run it.
+3. Show the output to the user.
+
 If argument is "reset":
 1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/reset.sh "$(pwd)" cursor`
 2. Tell the user the result.

scripts/drivers/types/gemini/template.md

@@ -7,6 +7,8 @@ Agent messaging command. **IMPORTANT: Always use the provided scripts. NEVER dir
 
 **Shell requirement:** All agmsg scripts are Bash scripts. Always execute them via `bash`, never via PowerShell or cmd directly. If your default shell is not Bash (e.g. PowerShell on Windows), wrap every command with `bash -lc '...'`. Example: `bash -lc '~/.agents/skills/__SKILL_NAME__/scripts/send.sh myteam alice bob "hello"'`. Do NOT construct DB paths manually — the scripts handle path resolution internally. If you need to redirect storage, use `AGMSG_STORAGE_PATH` (the supported override).
 
+**If the argument is "doctor" (with or without further flags): do NOT run whoami.sh, do NOT enter the join flow below. Go straight to the "doctor" entry under Execute and stop there.** `doctor` reports the health of the whole installation and exists specifically for when registration or delivery is broken — it must work even before you have an identity, so it never goes through the section below.
+
 ## Identity
 
 If you already know your AGENT and TEAMS from a previous `$__SKILL_NAME__` call in this session, skip to **Execute** below.
@@ -42,6 +44,7 @@ Four possible outputs:
   > - `$__SKILL_NAME__ send <agent> <message>` — send a message
   > - `$__SKILL_NAME__ team` — list team members
   > - `$__SKILL_NAME__ history` — message history
+  > - `$__SKILL_NAME__ doctor` — check registration/lock/delivery health across the installation
 
   5. **REQUIRED — Do NOT skip this step.** Ask the user to pick a delivery mode using exactly this prompt:
 
@@ -133,6 +136,15 @@ If argument is "hook off" (legacy alias):
 1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/delivery.sh set off gemini "$(pwd)"`
 2. Tell the user: "Delivery mode set to 'off'."
 
+If argument is "doctor" (no further args):
+1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/doctor.sh`
+2. Show the output to the user. Exit code: 0 = clean, 1 = one or more warnings (the output still shows everything -- show it in full), 2 = usage/resolution error.
+
+If argument starts with "doctor" followed by flags (e.g. "doctor --project /path/to/project"):
+1. Pass the flags straight through: `~/.agents/skills/__SKILL_NAME__/scripts/doctor.sh <flags>`
+2. Supported flags, all optional and combinable: `--project <path>`, `--type <type>`, `--team <team>`, `--redacted` (masks paths and names, safe to paste into a report). Only use these when the user explicitly asks to narrow the scope -- bare `doctor` (no flags) already covers the whole installation and is the normal way to run it.
+3. Show the output to the user.
+
 If argument is "reset":
 1. Run: `~/.agents/skills/__SKILL_NAME__/scripts/reset.sh "$(pwd)" gemini`
 2. Tell the user the result.