| name | lingtai-doctor |
| description | Read-only health diagnostics for LingTai agents and bots. Use when an agent appears offline or unreachable, when a machine migration may have left stale MCP/addon command paths, when heartbeat/status/process/notification/log surfaces disagree, or before deciding whether to mail, refresh, CPR, or edit persistent configuration. Includes a bundled doctor.py script for layered local checks without exposing secrets.
|
| version | 0.1.0 |
| tags | ["doctor","diagnostics","mcp","addons","heartbeat","migration","recovery"] |
| last_changed_at | "2026-07-19T00:00:00.000Z" |
| related_files | ["src/lingtai/intrinsic_skills/lingtai-doctor/scripts/doctor.py"] |
| maintenance | Tracks the tool/capability behavior it teaches; update when that tool's behavior changes.
|
LingTai Doctor
lingtai-doctor is the first stop when a LingTai agent or bot looks dead but
the evidence is mixed: Telegram/Feishu/WeChat cannot reach it, the TUI says it
is offline, a heartbeat is fresh, MCP configuration points at an old runtime, or
logs/notifications/status files disagree.
Diagnosis before repair. The bundled script is read-only: it summarizes local
evidence, redacts secrets, and suggests next steps. It never edits init.json,
touches mailboxes, refreshes agents, or kills processes. Repairs belong to the
owning manuals routed below.
Run it
python3 src/lingtai/intrinsic_skills/lingtai-doctor/scripts/doctor.py \
--agent-dir /path/to/project/.lingtai/mimo-1
python3 .library/intrinsic/capabilities/lingtai-doctor/scripts/doctor.py
What it checks
Layered so one broken surface is not mistaken for a dead agent:
- Identity / lifecycle files —
.agent.json, .status.json, and
.agent.heartbeat freshness.
- Process evidence — best-effort
ps scan for lingtai-agent run <agent-dir> / python -m lingtai run <agent-dir>.
- Notifications and logs — channel files plus common logs such as
logs/events.jsonl, logs/agent.log, and token ledgers, by mtime/size only.
- Internal mail footprint — inbox/outbox counts without message bodies.
- MCP/addon configuration —
init.json top-level mcp entries and
mcp_registry.jsonl stdio commands, checked for existence and executability
(or PATH resolution). Environment values are redacted; only path-like
existence facts are reported.
- Migration drift hints — stale Linux
/home/... paths on macOS-style
hosts, stale macOS /Users/... paths on Linux-style hosts, and likely
~/.lingtai-tui/runtime/venv/bin/python replacements.
- First-party MCP server imports — if a configured stdio command points at a
usable Python executable, tries importing the configured LingTai curated MCP
modules (
lingtai.mcp_servers. telegram/feishu/wechat/whatsapp/imap)
without reading credentials.
Reading the result
Top-level severity is OK (no obvious local mismatch), WARN (at least one
surface looks stale, missing, or inconsistent), or FAIL (a critical local
file/config/path is missing or broken).
The report ends with the same next steps summarized here. Triage in this order,
then follow the owning manual rather than improvising a repair:
| Doctor evidence | Do | Owner |
|---|
.agent.heartbeat is fresh | The agent is probably alive; internal email should wake it even if an external addon is broken. | email-manual |
| Heartbeat and process are both dead | CPR may be appropriate. If the process is alive but status/logs are stale, investigate before CPR. | substrate-manual |
| An MCP stdio command points at a missing runtime | Back up init.json and mcp_registry.jsonl first, then replace the stale command path and refresh the agent. | mcp-manual troubleshooting |
| Notifications are stale while the agent is healthy | Clear the producer channel after reading/handling it; generic dismiss only clears a mirror, so do not use it for producer state unless you know it is stale. | notification-manual dismissal safety |
Scope
Doctor is the shared diagnostic foundation and covers the whole agent footprint,
not only MCP registry syntax — mcp(action="info") validates the registry, not
lifecycle, process, log, or mail evidence. TUI /doctor should call these
scripts instead of maintaining a separate copy of the logic.
