From c6c6247409651633495a510dbaad1210c50c0cdc Mon Sep 17 00:00:00 2001 From: fujibee Date: Fri, 7 Aug 2026 14:54:16 -0700 Subject: [PATCH 1/2] docs: cover doctor on the human-facing surfaces (README, README.ja, llms.txt) scripts/doctor.sh shipped (#640/#654) with the agent-facing surfaces handled separately, but the three human-facing files that describe the other subcommands never mention it: README.md and README.ja.md have per-subcommand sections (spawn, despawn, actas) and no doctor section, and llms.txt enumerates scripts/*.sh under "Key source files" without scripts/doctor.sh. Add a doctor section to README.md matching the granularity of the surrounding subcommand sections: bare doctor as the normal form (whole-installation default), --project/--type/--team as freely combinable narrowing filters, --redacted as the paste-into-an-issue form, read-only stance, and the 0/1/2 exit codes. README.ja.md gets the same section as a translation of the English text. llms.txt gets one doctor.sh line in the existing list format. Descriptions were checked against doctor.sh --help, the script, and tests/test_doctor.bats rather than restated from memory. --- README.ja.md | 14 ++++++++++++++ README.md | 14 ++++++++++++++ llms.txt | 1 + 3 files changed, 29 insertions(+) diff --git a/README.ja.md b/README.ja.md index 772f945e4..e66dad73a 100644 --- a/README.ja.md +++ b/README.ja.md @@ -225,6 +225,20 @@ codex: despawnは指定されたメンバーにのみ作用する — `despawn` を実行しているセッション自体は決して終了させられず、広い購読範囲を持つウォッチャーは別のロール宛の `ctrl:despawn` を無視する。 +### 誰が何を持っているかを見る（`doctor`） + +配信が沈黙したり、ロールがどうしても取得できないとき、`doctor` はインストール全体の状態を1画面にまとめて表示する: (project, type) ごとにグループ化された全登録、各actasロックとその所有者（まだ生きているかどうかも）、ウォッチャーとブリッジのプロセス、プロジェクトごとの配信モード — そして stale なものを名指しする warnings セクション。 + +``` +/agmsg doctor # インストール全体 — すべてのチーム、プロジェクト、タイプ +/agmsg doctor --team myteam # 1つのチームに絞る +/agmsg doctor --redacted # パスと名前を伏せた同じレポート — そのままissueに貼れる +``` + +素の `doctor` が通常形だ: `claude doctor` や `brew doctor` と同じく、スコープを取らず全体を報告する。`--project `・`--type `・`--team ` はレポートを絞り込むもので、自由に組み合わせられる — 疑わしい箇所に当たりがついているときに使うのであって、doctorが要求するものではない。`--redacted` はプロジェクトパスとチーム/エージェント名を一貫した仮名（``、`team1/agent2`）に置き換えるので、マシンのレイアウトを漏らさずにバグ報告へ添付できる。 + +doctorは**読み取り専用**だ: staleなロックや死んだウォッチャーのpidfileは報告されるだけで、決して掃除されない — 証拠はその場に残る。終了コードでスクリプトからも扱える — `0` は問題なし、`1` は1つ以上の警告、`2` は使い方または解決のエラー（未知の `--type`/`--team`、または明示したフィルタに何もマッチしない場合）。シェルやCIからは `~/.agents/skills//scripts/doctor.sh` として呼び出す。 + ## 配信モード 受信メッセージがエージェントにどう届くか。初回参加時のプロンプトで1つ選ぶか、後で `/agmsg mode ` で変更する。 diff --git a/README.md b/README.md index c3c3393b2..c2f845d0c 100644 --- a/README.md +++ b/README.md @@ -239,6 +239,20 @@ See **[docs/session-resurrect.md](docs/session-resurrect.md)** for the tmux-resu setup, how it resolves each pane, what does and doesn't come back automatically, and the manual fallback. +### See who holds what (`doctor`) + +When delivery goes quiet or a role refuses to be claimed, `doctor` puts the state of the whole installation on one screen: every registration grouped by (project, type), each actas lock with its owner and whether that owner is still alive, watcher and bridge processes, the delivery mode per project — and a warnings section naming anything stale. + +``` +/agmsg doctor # the whole installation — every team, project, type +/agmsg doctor --team myteam # narrow to one team +/agmsg doctor --redacted # same report with paths and names masked — paste it into an issue +``` + +Bare `doctor` is the normal form: like `claude doctor` or `brew doctor`, it takes no scope and reports on everything. `--project `, `--type `, and `--team ` narrow the report and combine freely — reach for them when you already suspect a corner, not because doctor requires them. `--redacted` replaces project paths and team/agent names with consistent pseudonyms (``, `team1/agent2`), so the report can go into a bug report without leaking your machine's layout. + +Doctor is **read-only**: a stale lock or dead watcher pidfile is reported, never cleaned up, so the evidence stays in place. The exit code makes it scriptable — `0` clean, `1` one or more warnings, `2` usage or resolution error (an unknown `--type`/`--team`, or an explicit filter that matches nothing). From a shell or CI, invoke it as `~/.agents/skills//scripts/doctor.sh`. + ## Delivery modes How incoming messages reach your agent. Pick one at first join via the prompt, or change it later with `/agmsg mode `. diff --git a/llms.txt b/llms.txt index b887f03ca..55fd69a02 100644 --- a/llms.txt +++ b/llms.txt @@ -72,6 +72,7 @@ directly-invokable commands; `scripts/drivers//` holds axis drivers and - [scripts/join.sh](scripts/join.sh): join or create a team. - [scripts/whoami.sh](scripts/whoami.sh): resolve this project's agent identity. - [scripts/delivery.sh](scripts/delivery.sh): get/set the delivery mode. +- [scripts/doctor.sh](scripts/doctor.sh): report who holds what — registrations, locks, watchers, delivery — read-only. - [scripts/spawn.sh](scripts/spawn.sh) / [scripts/despawn.sh](scripts/despawn.sh): launch / tear down a peer agent. - [scripts/history.sh](scripts/history.sh): replay a room's history. - [SKILL.md](SKILL.md): the agent-facing skill definition (full command reference). From 32f3721a5488343e145f0d1dfeb4e28cd7d2fdef Mon Sep 17 00:00:00 2001 From: fujibee Date: Fri, 7 Aug 2026 15:12:34 -0700 Subject: [PATCH 2/2] docs(doctor): state exactly what --redacted hides instead of promising no leaks _redact_project collapses a $HOME-prefixed path to ~ and pseudonymizes only paths outside $HOME (doctor.sh line 261; fixed by tests/test_doctor.bats lines 317/346). The username disappears, but the directory structure below $HOME stays visible -- and most projects live under $HOME. "Without leaking your machine's layout" promised more than the majority case delivers, and the sentence sits exactly on the paste-into-a-public-issue path. Say what is hidden ($HOME prefix, outside-$HOME paths, team/agent names) and what remains (path segments below $HOME), and tell the reader to skim the output before posting. Same change in README.ja.md, translated from the corrected English. --- README.ja.md | 4 ++-- README.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.ja.md b/README.ja.md index e66dad73a..9d4907587 100644 --- a/README.ja.md +++ b/README.ja.md @@ -232,10 +232,10 @@ despawnは指定されたメンバーにのみ作用する — `despawn` を実 ``` /agmsg doctor # インストール全体 — すべてのチーム、プロジェクト、タイプ /agmsg doctor --team myteam # 1つのチームに絞る -/agmsg doctor --redacted # パスと名前を伏せた同じレポート — そのままissueに貼れる +/agmsg doctor --redacted # 共有用に伏せたレポート — 何が隠れるかは下記参照 ``` -素の `doctor` が通常形だ: `claude doctor` や `brew doctor` と同じく、スコープを取らず全体を報告する。`--project `・`--type `・`--team ` はレポートを絞り込むもので、自由に組み合わせられる — 疑わしい箇所に当たりがついているときに使うのであって、doctorが要求するものではない。`--redacted` はプロジェクトパスとチーム/エージェント名を一貫した仮名（``、`team1/agent2`）に置き換えるので、マシンのレイアウトを漏らさずにバグ報告へ添付できる。 +素の `doctor` が通常形だ: `claude doctor` や `brew doctor` と同じく、スコープを取らず全体を報告する。`--project `・`--type `・`--team ` はレポートを絞り込むもので、自由に組み合わせられる — 疑わしい箇所に当たりがついているときに使うのであって、doctorが要求するものではない。`--redacted` は共有用にレポートを伏せる — 何が隠れて何が残るかは正確に: ホームディレクトリの前置部分は `~` に畳まれ（ユーザ名は消えるが、`$HOME` **配下**のパスはそのまま見える）、`$HOME` の**外**のプロジェクトパスは一貫した仮名（``）に置き換わり、チーム/エージェント名は `team1`/`agent2` になる。`$HOME` 配下のプロジェクトはディレクトリ名がそのまま出るので、公開 issue に貼る前に、出力に見られたくないものが残っていないか一度目を通すこと。 doctorは**読み取り専用**だ: staleなロックや死んだウォッチャーのpidfileは報告されるだけで、決して掃除されない — 証拠はその場に残る。終了コードでスクリプトからも扱える — `0` は問題なし、`1` は1つ以上の警告、`2` は使い方または解決のエラー（未知の `--type`/`--team`、または明示したフィルタに何もマッチしない場合）。シェルやCIからは `~/.agents/skills//scripts/doctor.sh` として呼び出す。 diff --git a/README.md b/README.md index c2f845d0c..fbd5c7dc1 100644 --- a/README.md +++ b/README.md @@ -246,10 +246,10 @@ When delivery goes quiet or a role refuses to be claimed, `doctor` puts the stat ``` /agmsg doctor # the whole installation — every team, project, type /agmsg doctor --team myteam # narrow to one team -/agmsg doctor --redacted # same report with paths and names masked — paste it into an issue +/agmsg doctor --redacted # masked report for sharing — see below for what is hidden ``` -Bare `doctor` is the normal form: like `claude doctor` or `brew doctor`, it takes no scope and reports on everything. `--project `, `--type `, and `--team ` narrow the report and combine freely — reach for them when you already suspect a corner, not because doctor requires them. `--redacted` replaces project paths and team/agent names with consistent pseudonyms (``, `team1/agent2`), so the report can go into a bug report without leaking your machine's layout. +Bare `doctor` is the normal form: like `claude doctor` or `brew doctor`, it takes no scope and reports on everything. `--project `, `--type `, and `--team ` narrow the report and combine freely — reach for them when you already suspect a corner, not because doctor requires them. `--redacted` masks the report for sharing — be precise about what it hides and what it keeps: your home directory prefix is collapsed to `~` (the username disappears, but the path *below* `$HOME` stays visible), project paths **outside** `$HOME` are replaced with consistent pseudonyms (``), and team/agent names become `team1`/`agent2`. A project under `$HOME` still shows its directory names, so skim the output for anything you consider sensitive before pasting it into a public issue. Doctor is **read-only**: a stale lock or dead watcher pidfile is reported, never cleaned up, so the evidence stays in place. The exit code makes it scriptable — `0` clean, `1` one or more warnings, `2` usage or resolution error (an unknown `--type`/`--team`, or an explicit filter that matches nothing). From a shell or CI, invoke it as `~/.agents/skills//scripts/doctor.sh`.