fengming 0.3.10 → 0.3.12

package/docs/gateway/doctor.md

@@ -1,575 +0,0 @@
----
-summary: "Doctor command: health checks, config migrations, and repair steps"
-read_when:
-  - Adding or modifying doctor migrations
-  - Introducing breaking config changes
-title: "Doctor"
-sidebarTitle: "Doctor"
----
-
-`fengming doctor` is the repair + migration tool for FengMing. It fixes stale config/state, checks health, and provides actionable repair steps.
-
-## Quick start
-
-```bash
-fengming doctor
-```
-
-### Headless and automation modes
-
-<Tabs>
-  <Tab title="--yes">
-    ```bash
-    fengming doctor --yes
-    ```
-
-    Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).
-
-  </Tab>
-  <Tab title="--fix">
-    ```bash
-    fengming doctor --fix
-    ```
-
-    Apply recommended repairs without prompting (repairs + restarts where safe).
-
-  </Tab>
-  <Tab title="--lint">
-    ```bash
-    fengming doctor --lint
-    fengming doctor --lint --json
-    ```
-
-    Run structured health checks for CI or preflight automation. This mode is
-    read-only: it does not prompt, repair, migrate config, restart services, or
-    touch state.
-
-  </Tab>
-  <Tab title="--fix --force">
-    ```bash
-    fengming doctor --fix --force
-    ```
-
-    Apply aggressive repairs too (overwrites custom supervisor configs).
-
-  </Tab>
-  <Tab title="--non-interactive">
-    ```bash
-    fengming doctor --non-interactive
-    ```
-
-    Run without prompts and only apply safe migrations (config normalization + on-disk state moves). Skips restart/service/sandbox actions that require human confirmation. Legacy state migrations run automatically when detected.
-
-  </Tab>
-  <Tab title="--deep">
-    ```bash
-    fengming doctor --deep
-    ```
-
-    Scan system services for extra gateway installs (launchd/systemd/schtasks).
-
-  </Tab>
-</Tabs>
-
-If you want to review changes before writing, open the config file first:
-
-```bash
-cat ~/.fengming/fengming.json
-```
-
-## Read-only lint mode
-
-`fengming doctor --lint` is the automation-friendly sibling of
-`fengming doctor --fix`. Both use doctor health checks, but their posture is
-different:
-
-| Mode                     | Prompts   | Writes config/state     | Output                 | Use it for                      |
-| ------------------------ | --------- | ----------------------- | ---------------------- | ------------------------------- |
-| `fengming doctor`        | yes       | no                      | friendly health report | a human checking status         |
-| `fengming doctor --fix`  | sometimes | yes, with repair policy | friendly repair log    | applying approved repairs       |
-| `fengming doctor --lint` | no        | no                      | structured findings    | CI, preflight, and review gates |
-
-Modernized health checks may provide an optional `repair()` implementation.
-`doctor --fix` applies those repairs when they exist and continues to use the
-existing doctor repair flow for checks that have not migrated yet.
-The structured repair contract also separates repair reporting from detection:
-`detect()` reports current findings, while `repair()` can report changes,
-config/file diffs, and non-file side effects. That keeps the migration path open
-for future `doctor --fix --dry-run` and diff output without making lint checks
-plan mutations.
-
-Examples:
-
-```bash
-fengming doctor --lint
-fengming doctor --lint --severity-min warning
-fengming doctor --lint --json
-fengming doctor --lint --only core/doctor/gateway-config --json
-```
-
-JSON output includes:
-
-- `ok`: whether any visible finding met the selected severity threshold
-- `checksRun`: number of health checks executed
-- `checksSkipped`: checks skipped by `--only` or `--skip`
-- `findings`: structured diagnostics with `checkId`, `severity`, `message`, and
-  optional `path`, `line`, `column`, `ocPath`, and `fixHint`
-
-Exit codes:
-
-- `0`: no findings at or above the selected threshold
-- `1`: one or more findings met the selected threshold
-- `2`: command/runtime failure before lint findings could be emitted
-
-Use `--severity-min info|warning|error` to control both what is printed and what
-causes a non-zero lint exit. Use `--only <id>` for narrow preflight gates and
-`--skip <id>` to temporarily exclude a noisy check while keeping the rest of the
-lint run active.
-Lint-output options such as `--json`, `--severity-min`, `--only`, and `--skip`
-must be paired with `--lint`; regular doctor and repair runs reject them.
-
-## What it does (summary)
-
-<AccordionGroup>
-  <Accordion title="Health, UI, and updates">
-    - Optional pre-flight update for git installs (interactive only).
-    - UI protocol freshness check (rebuilds Control UI when the protocol schema is newer).
-    - Health check + restart prompt.
-    - Skills status summary (eligible/missing/blocked) and plugin status.
-
-  </Accordion>
-  <Accordion title="Config and migrations">
-    - Config normalization for legacy values.
-    - Talk config migration from legacy flat `talk.*` fields into `talk.provider` + `talk.providers.<provider>`.
-    - Browser migration checks for legacy Chrome extension configs and Chrome MCP readiness.
-    - OpenCode provider override warnings (`models.providers.opencode` / `models.providers.opencode-go`).
-    - Legacy OpenAI Codex provider/profile migration (`openai-codex` → `openai`) and shadowing warnings for stale `models.providers.openai-codex`.
-    - OAuth TLS prerequisites check for OpenAI Codex OAuth profiles.
-    - Plugin/tool allowlist warnings when `plugins.allow` is restrictive but tool policy still asks for wildcard or plugin-owned tools.
-    - Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
-    - Legacy plugin manifest contract key migration (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
-    - Legacy cron store migration (`jobId`, `schedule.cron`, top-level delivery/payload fields, payload `provider`, simple `notify: true` webhook fallback jobs).
-    - Legacy whole-agent runtime-policy cleanup; provider/model runtime policy is the active route selector.
-    - Stale plugin config cleanup when plugins are enabled; when `plugins.enabled=false`, stale plugin references are treated as inert containment config and are preserved.
-
-  </Accordion>
-  <Accordion title="State and integrity">
-    - Session lock file inspection and stale lock cleanup.
-    - Session transcript repair for duplicated prompt-rewrite branches created by affected 2026.4.24 builds.
-    - Wedged subagent restart-recovery tombstone detection, with `--fix` support for clearing stale aborted recovery flags so startup does not keep treating the child as restart-aborted.
-    - State integrity and permissions checks (sessions, transcripts, state dir).
-    - Config file permission checks (chmod 600) when running locally.
-    - Model auth health: checks OAuth expiry, can refresh expiring tokens, and reports auth-profile cooldown/disabled states.
-    - Extra workspace dir detection (`~/fengming`).
-
-  </Accordion>
-  <Accordion title="Gateway, services, and supervisors">
-    - Sandbox image repair when sandboxing is enabled.
-    - Legacy service migration and extra gateway detection.
-    - Matrix channel legacy state migration (in `--fix` / `--repair` mode).
-    - Gateway runtime checks (service installed but not running; cached launchd label).
-    - Channel status warnings (probed from the running gateway).
-    - Channel-specific permission checks live under `fengming channels capabilities`; for example, Discord voice channel permissions are audited with `fengming channels capabilities --channel discord --target channel:<channel-id>`.
-    - WhatsApp responsiveness checks for degraded Gateway event-loop health with local TUI clients still running; `--fix` stops only verified local TUI clients.
-    - Codex route repair for legacy `openai-codex/*` model refs in primary models, fallbacks, image/video generation models, heartbeat/subagent/compaction overrides, hooks, channel model overrides, and session route pins; `--fix` rewrites them to `openai/*`, migrates `openai-codex:*` auth profiles/order to `openai:*`, removes stale session/whole-agent runtime pins, and leaves canonical OpenAI agent refs on the default Codex harness.
-    - Supervisor config audit (launchd/systemd/schtasks) with optional repair.
-    - Embedded proxy environment cleanup for gateway services that captured shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` values during install or update.
-    - Gateway runtime best-practice checks (Node vs Bun, version-manager paths).
-    - Gateway port collision diagnostics (default `18789`).
-
-  </Accordion>
-  <Accordion title="Auth, security, and pairing">
-    - Security warnings for open DM policies.
-    - Gateway auth checks for local token mode (offers token generation when no token source exists; does not overwrite token SecretRef configs).
-    - Device pairing trouble detection (pending first-time pair requests, pending role/scope upgrades, stale local device-token cache drift, and paired-record auth drift).
-
-  </Accordion>
-  <Accordion title="Workspace and shell">
-    - systemd linger check on Linux.
-    - Workspace bootstrap file size check (truncation/near-limit warnings for context files).
-    - Skills readiness check for the default agent; reports allowed skills with missing bins, env, config, or OS requirements, and `--fix` can disable unavailable skills in `skills.entries`.
-    - Shell completion status check and auto-install/upgrade.
-    - Memory search embedding provider readiness check (local model, remote API key, or QMD binary).
-    - Source install checks (pnpm workspace mismatch, missing UI assets, missing tsx binary).
-    - Writes updated config + wizard metadata.
-
-  </Accordion>
-</AccordionGroup>
-
-## Dreams UI backfill and reset
-
-The Control UI Dreams scene includes **Backfill**, **Reset**, and **Clear Grounded** actions for the grounded dreaming workflow. These actions use gateway doctor-style RPC methods, but they are **not** part of `fengming doctor` CLI repair/migration.
-
-What they do:
-
-- **Backfill** scans historical `memory/YYYY-MM-DD.md` files in the active workspace, runs the grounded REM diary pass, and writes reversible backfill entries into `DREAMS.md`.
-- **Reset** removes only those marked backfill diary entries from `DREAMS.md`.
-- **Clear Grounded** removes only staged grounded-only short-term entries that came from historical replay and have not accumulated live recall or daily support yet.
-
-What they do **not** do by themselves:
-
-- they do not edit `MEMORY.md`
-- they do not run full doctor migrations
-- they do not automatically stage grounded candidates into the live short-term promotion store unless you explicitly run the staged CLI path first
-
-If you want grounded historical replay to influence the normal deep promotion lane, use the CLI flow instead:
-
-```bash
-fengming memory rem-backfill --path ./memory --stage-short-term
-```
-
-That stages grounded durable candidates into the short-term dreaming store while keeping `DREAMS.md` as the review surface.
-
-## Detailed behavior and rationale
-
-<AccordionGroup>
-  <Accordion title="0. Optional update (git installs)">
-    If this is a git checkout and doctor is running interactively, it offers to update (fetch/rebase/build) before running doctor.
-  </Accordion>
-  <Accordion title="1. Config normalization">
-    If the config contains legacy value shapes (for example `messages.ackReaction` without a channel-specific override), doctor normalizes them into the current schema.
-
-    That includes legacy Talk flat fields. Current public Talk speech config is `talk.provider` + `talk.providers.<provider>`, and realtime voice config is `talk.realtime.*`. Doctor rewrites old `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` shapes into the provider map, and rewrites legacy top-level realtime selectors (`talk.mode`, `talk.transport`, `talk.brain`, `talk.model`, `talk.voice`) into `talk.realtime`.
-
-    Doctor also warns when `plugins.allow` is non-empty and tool policy uses
-    wildcard or plugin-owned tool entries. `tools.allow: ["*"]` only matches tools
-    from plugins that actually load; it does not bypass the exclusive plugin
-    allowlist.
-
-  </Accordion>
-  <Accordion title="2. Legacy config key migrations">
-    When the config contains deprecated keys, other commands refuse to run and ask you to run `fengming doctor`.
-
-    Doctor will:
-
-    - Explain which legacy keys were found.
-    - Show the migration it applied.
-    - Rewrite `~/.fengming/fengming.json` with the updated schema.
-
-    Gateway startup refuses legacy config formats and asks you to run `fengming doctor --fix`; it does not rewrite `fengming.json` on startup. Cron job store migrations are also handled by `fengming doctor --fix`.
-
-    Current migrations:
-
-    - `routing.allowFrom` → `channels.whatsapp.allowFrom`
-    - `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
-    - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
-    - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
-    - `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention`
-    - `routing.queue` → `messages.queue`
-    - `routing.bindings` → top-level `bindings`
-    - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
-    - legacy `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
-    - legacy top-level realtime Talk selectors (`talk.mode`/`talk.transport`/`talk.brain`/`talk.model`/`talk.voice`) + `talk.provider`/`talk.providers` → `talk.realtime`
-    - `routing.agentToAgent` → `tools.agentToAgent`
-    - `routing.transcribeAudio` → `tools.media.audio.models`
-    - `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
-    - `messages.tts.provider: "edge"` and `messages.tts.providers.edge` → `messages.tts.provider: "microsoft"` and `messages.tts.providers.microsoft`
-    - TTS speaker selection fields (`voice`/`voiceName`/`voiceId`) → `speakerVoice`/`speakerVoiceId`
-    - `channels.discord.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.voice.tts.providers.<provider>`
-    - `channels.discord.accounts.<id>.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.accounts.<id>.voice.tts.providers.<provider>`
-    - `plugins.entries.voice-call.config.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `plugins.entries.voice-call.config.tts.providers.<provider>`
-    - `plugins.entries.voice-call.config.tts.provider: "edge"` and `plugins.entries.voice-call.config.tts.providers.edge` → `provider: "microsoft"` and `providers.microsoft`
-    - `plugins.entries.voice-call.config.provider: "log"` → `"mock"`
-    - `plugins.entries.voice-call.config.twilio.from` → `plugins.entries.voice-call.config.fromNumber`
-    - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
-    - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
-    - `bindings[].match.accountID` → `bindings[].match.accountId`
-    - For channels with named `accounts` but lingering single-account top-level channel values, move those account-scoped values into the promoted account chosen for that channel (`accounts.default` for most channels; Matrix can preserve an existing matching named/default target)
-    - `identity` → `agents.list[].identity`
-    - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
-    - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
-    - remove `agents.defaults.llm`; use `models.providers.<id>.timeoutSeconds` for slow provider/model timeouts, and keep the agent/run timeout above that value when the whole run must last longer
-    - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
-    - `browser.profiles.*.driver: "extension"` → `"existing-session"`
-    - remove `browser.relayBindHost` (legacy extension relay setting)
-    - legacy `models.providers.*.api: "openai"` → `"openai-completions"` (gateway startup also skips providers whose `api` is set to a future or unknown enum value rather than failing closed)
-    - remove `plugins.entries.codex.config.codexDynamicToolsProfile`; Codex app-server always keeps Codex-native workspace tools native
-
-    Doctor warnings also include account-default guidance for multi-account channels:
-
-    - If two or more `channels.<channel>.accounts` entries are configured without `channels.<channel>.defaultAccount` or `accounts.default`, doctor warns that fallback routing can pick an unexpected account.
-    - If `channels.<channel>.defaultAccount` is set to an unknown account ID, doctor warns and lists configured account IDs.
-
-  </Accordion>
-  <Accordion title="2b. OpenCode provider overrides">
-    If you've added `models.providers.opencode`, `opencode-zen`, or `opencode-go` manually, it overrides the built-in OpenCode catalog from `fengming/plugin-sdk/llm`. That can force models onto the wrong API or zero out costs. Doctor warns so you can remove the override and restore per-model API routing + costs.
-  </Accordion>
-  <Accordion title="2c. Browser migration and Chrome MCP readiness">
-    If your browser config still points at the removed Chrome extension path, doctor normalizes it to the current host-local Chrome MCP attach model:
-
-    - `browser.profiles.*.driver: "extension"` becomes `"existing-session"`
-    - `browser.relayBindHost` is removed
-
-    Doctor also audits the host-local Chrome MCP path when you use `defaultProfile: "user"` or a configured `existing-session` profile:
-
-    - checks whether Google Chrome is installed on the same host for default auto-connect profiles
-    - checks the detected Chrome version and warns when it is below Chrome 144
-    - reminds you to enable remote debugging in the browser inspect page (for example `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, or `edge://inspect/#remote-debugging`)
-
-    Doctor cannot enable the Chrome-side setting for you. Host-local Chrome MCP still requires:
-
-    - a Chromium-based browser 144+ on the gateway/node host
-    - the browser running locally
-    - remote debugging enabled in that browser
-    - approving the first attach consent prompt in the browser
-
-    Readiness here is only about local attach prerequisites. Existing-session keeps the current Chrome MCP route limits; advanced routes like `responsebody`, PDF export, download interception, and batch actions still require a managed browser or raw CDP profile.
-
-    This check does **not** apply to Docker, sandbox, remote-browser, or other headless flows. Those continue to use raw CDP.
-
-  </Accordion>
-  <Accordion title="2d. OAuth TLS prerequisites">
-    When an OpenAI Codex OAuth profile is configured, doctor probes the OpenAI authorization endpoint to verify that the local Node/OpenSSL TLS stack can validate the certificate chain. If the probe fails with a certificate error (for example `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, expired cert, or self-signed cert), doctor prints platform-specific fix guidance. On macOS with a Homebrew Node, the fix is usually `brew postinstall ca-certificates`. With `--deep`, the probe runs even if the gateway is healthy.
-  </Accordion>
-  <Accordion title="2e. Codex OAuth provider overrides">
-    If you previously added legacy OpenAI transport settings under `models.providers.openai-codex`, they can shadow the built-in Codex OAuth provider path that newer releases use automatically. Doctor warns when it sees those old transport settings alongside Codex OAuth so you can remove or rewrite the stale transport override and get the built-in routing/fallback behavior back. Custom proxies and header-only overrides are still supported and do not trigger this warning.
-  </Accordion>
-  <Accordion title="2f. Codex route repair">
-    Doctor checks for legacy `openai-codex/*` model refs. Native Codex harness routing uses canonical `openai/*` model refs; OpenAI agent turns go through the Codex app-server harness instead of the FengMing OpenAI provider path.
-
-    In `--fix` / `--repair` mode, doctor rewrites affected default-agent and per-agent refs, including primary models, fallbacks, image/video generation models, heartbeat/subagent/compaction overrides, hooks, channel model overrides, and stale persisted session route state:
-
-    - `openai-codex/gpt-*` becomes `openai/gpt-*`.
-    - Codex intent moves to provider/model-scoped `agentRuntime.id: "codex"` entries for repaired agent model refs.
-    - Stale whole-agent runtime config and persisted session runtime pins are removed because runtime selection is provider/model-scoped.
-    - Existing provider/model runtime policy is preserved unless the repaired legacy model ref needs Codex routing to keep the old auth path.
-    - Existing model fallback lists are preserved with their legacy entries rewritten; copied per-model settings move from the legacy key to the canonical `openai/*` key.
-    - Persisted session `modelProvider`/`providerOverride`, `model`/`modelOverride`, fallback notices, and auth-profile pins are repaired across all discovered agent session stores.
-    - `/codex ...` means "control or bind a native Codex conversation from chat."
-    - `/acp ...` or `runtime: "acp"` means "use the external ACP/acpx adapter."
-
-  </Accordion>
-  <Accordion title="2g. Session route cleanup">
-    Doctor also scans discovered agent session stores for stale auto-created route state after you move configured models or runtime away from a plugin-owned route such as Codex.
-
-    `fengming doctor --fix` can clear auto-created stale state such as `modelOverrideSource: "auto"` model pins, runtime model metadata, pinned harness ids, CLI session bindings, and auto auth-profile overrides when their owning route is no longer configured. Explicit user or legacy session model choices are reported for manual review and left untouched; switch them with `/model ...`, `/new`, or reset the session when that route is no longer intended.
-
-  </Accordion>
-  <Accordion title="3. Legacy state migrations (disk layout)">
-    Doctor can migrate older on-disk layouts into the current structure:
-
-    - Sessions store + transcripts:
-      - from `~/.fengming/sessions/` to `~/.fengming/agents/<agentId>/sessions/`
-    - Agent dir:
-      - from `~/.fengming/agent/` to `~/.fengming/agents/<agentId>/agent/`
-    - WhatsApp auth state (Baileys):
-      - from legacy `~/.fengming/credentials/*.json` (except `oauth.json`)
-      - to `~/.fengming/credentials/whatsapp/<accountId>/...` (default account id: `default`)
-
-    These migrations are best-effort and idempotent; doctor will emit warnings when it leaves any legacy folders behind as backups. The Gateway/CLI also auto-migrates the legacy sessions + agent dir on startup so history/auth/models land in the per-agent path without a manual doctor run. WhatsApp auth is intentionally only migrated via `fengming doctor`. Talk provider/provider-map normalization now compares by structural equality, so key-order-only diffs no longer trigger repeat no-op `doctor --fix` changes.
-
-  </Accordion>
-  <Accordion title="3a. Legacy plugin manifest migrations">
-    Doctor scans all installed plugin manifests for deprecated top-level capability keys (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). When found, it offers to move them into the `contracts` object and rewrite the manifest file in-place. This migration is idempotent; if the `contracts` key already has the same values, the legacy key is removed without duplicating the data.
-  </Accordion>
-  <Accordion title="3b. Legacy cron store migrations">
-    Doctor also checks the cron job store (`~/.fengming/cron/jobs.json` by default, or `cron.store` when overridden) for old job shapes that the scheduler still accepts for compatibility.
-
-    Current cron cleanups include:
-
-    - `jobId` → `id`
-    - `schedule.cron` → `schedule.expr`
-    - top-level payload fields (`message`, `model`, `thinking`, ...) → `payload`
-    - top-level delivery fields (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
-    - payload `provider` delivery aliases → explicit `delivery.channel`
-    - simple legacy `notify: true` webhook fallback jobs → explicit `delivery.mode="webhook"` with `delivery.to=cron.webhook`
-
-    The Gateway also sanitizes malformed cron rows at load time so valid jobs keep running. Raw malformed rows are copied to `jobs-quarantine.json` next to the active store before they are removed from `jobs.json`; doctor reports quarantined rows so you can review or repair them manually.
-
-    Doctor only auto-migrates `notify: true` jobs when it can do so without changing behavior. If a job combines legacy notify fallback with an existing non-webhook delivery mode, doctor warns and leaves that job for manual review.
-
-    On Linux, doctor also warns when the user's crontab still invokes legacy `~/.fengming/bin/ensure-whatsapp.sh`. That host-local script is not maintained by current FengMing and can write false `Gateway inactive` messages to `~/.fengming/logs/whatsapp-health.log` when cron cannot reach the systemd user bus. Remove the stale crontab entry with `crontab -e`; use `fengming channels status --probe`, `fengming doctor`, and `fengming gateway status` for current health checks.
-
-  </Accordion>
-  <Accordion title="3c. Session lock cleanup">
-    Doctor scans every agent session directory for stale write-lock files — files left behind when a session exited abnormally. For each lock file found it reports: the path, PID, whether the PID is still alive, lock age, and whether it is considered stale (dead PID, malformed owner metadata, older than 30 minutes, or a live PID that can be proven to belong to a non-FengMing process). In `--fix` / `--repair` mode it removes locks with dead, orphaned, recycled, malformed-old, or non-FengMing owners automatically. Old locks that are still owned by a live FengMing process are reported but left in place so doctor does not cut off an active transcript writer.
-  </Accordion>
-  <Accordion title="3d. Session transcript branch repair">
-    Doctor scans agent session JSONL files for the duplicated branch shape created by the 2026.4.24 prompt transcript rewrite bug: an abandoned user turn with FengMing internal runtime context plus an active sibling containing the same visible user prompt. In `--fix` / `--repair` mode, doctor backs up each affected file next to the original and rewrites the transcript to the active branch so gateway history and memory readers no longer see duplicate turns.
-  </Accordion>
-  <Accordion title="4. State integrity checks (session persistence, routing, and safety)">
-    The state directory is the operational brainstem. If it vanishes, you lose sessions, credentials, logs, and config (unless you have backups elsewhere).
-
-    Doctor checks:
-
-    - **State dir missing**: warns about catastrophic state loss, prompts to recreate the directory, and reminds you that it cannot recover missing data.
-    - **State dir permissions**: verifies writability; offers to repair permissions (and emits a `chown` hint when owner/group mismatch is detected).
-    - **macOS cloud-synced state dir**: warns when state resolves under iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) or `~/Library/CloudStorage/...` because sync-backed paths can cause slower I/O and lock/sync races.
-    - **Linux SD or eMMC state dir**: warns when state resolves to an `mmcblk*` mount source, because SD or eMMC-backed random I/O can be slower and wear faster under session and credential writes.
-    - **Session dirs missing**: `sessions/` and the session store directory are required to persist history and avoid `ENOENT` crashes.
-    - **Transcript mismatch**: warns when recent session entries have missing transcript files.
-    - **Main session "1-line JSONL"**: flags when the main transcript has only one line (history is not accumulating).
-    - **Multiple state dirs**: warns when multiple `~/.fengming` folders exist across home directories or when `FENGMING_STATE_DIR` points elsewhere (history can split between installs).
-    - **Remote mode reminder**: if `gateway.mode=remote`, doctor reminds you to run it on the remote host (the state lives there).
-    - **Config file permissions**: warns if `~/.fengming/fengming.json` is group/world readable and offers to tighten to `600`.
-
-  </Accordion>
-  <Accordion title="5. Model auth health (OAuth expiry)">
-    Doctor inspects OAuth profiles in the auth store, warns when tokens are expiring/expired, and can refresh them when safe. If the Anthropic OAuth/token profile is stale, it suggests an Anthropic API key or the Anthropic setup-token path. Refresh prompts only appear when running interactively (TTY); `--non-interactive` skips refresh attempts.
-
-    When an OAuth refresh fails permanently (for example `refresh_token_reused`, `invalid_grant`, or a provider telling you to sign in again), doctor reports that re-auth is required and prints the exact `fengming models auth login --provider ...` command to run.
-
-    Doctor also reports auth profiles that are temporarily unusable due to:
-
-    - short cooldowns (rate limits/timeouts/auth failures)
-    - longer disables (billing/credit failures)
-
-    Legacy Codex OAuth profiles whose tokens live in macOS Keychain (older onboarding before the file-based sidecar layout) are not picked up by the embedded runtime path — that path runs with `allowKeychainPrompt: false` and cannot trigger a Keychain prompt. Affected users will see a one-shot `log.warn` from the legacy sidecar loader naming `fengming doctor --fix` and macOS Keychain (instead of the credential silently falling through to a downstream `No API key found for provider "openai-codex"`). Run `fengming doctor --fix` once from an interactive terminal to migrate Keychain-backed legacy tokens inline into `auth-profiles.json`; after that, embedded turns (Telegram, cron, sub-agent dispatch) resolve them like any other inline OAuth profile.
-
-  </Accordion>
-  <Accordion title="6. Hooks model validation">
-    If `hooks.gmail.model` is set, doctor validates the model reference against the catalog and allowlist and warns when it won't resolve or is disallowed.
-  </Accordion>
-  <Accordion title="7. Sandbox image repair">
-    When sandboxing is enabled, doctor checks Docker images and offers to build or switch to legacy names if the current image is missing.
-  </Accordion>
-  <Accordion title="7b. Plugin install cleanup">
-    Doctor removes legacy FengMing-generated plugin dependency staging state in `fengming doctor --fix` / `fengming doctor --repair` mode. This covers stale generated dependency roots, old install-stage directories, package-local debris from earlier bundled-plugin dependency repair code, and orphaned or recovered managed npm copies of bundled `@fengming/*` plugins that can shadow the current bundled manifest. Doctor also relinks the host `fengming` package into managed npm plugins that declare `peerDependencies.fengming`, so package-local runtime imports such as `fengming/plugin-sdk/*` keep resolving after updates or npm repairs.
-
-    Doctor can also reinstall missing downloadable plugins when config references them but the local plugin registry cannot find them. Examples include material `plugins.entries`, configured channel/provider/search settings, and configured agent runtimes. During package updates, doctor avoids running package-manager plugin repair while the core package is being swapped; run `fengming doctor --fix` again after the update if a configured plugin still needs recovery. Gateway startup and config reload do not run package managers; plugin installs remain explicit doctor/install/update work.
-
-  </Accordion>
-  <Accordion title="8. Gateway service migrations and cleanup hints">
-    Doctor detects legacy gateway services (launchd/systemd/schtasks) and offers to remove them and install the FengMing service using the current gateway port. It can also scan for extra gateway-like services and print cleanup hints. Profile-named FengMing gateway services are considered first-class and are not flagged as "extra."
-
-    On Linux, if the user-level gateway service is missing but a system-level FengMing gateway service exists, doctor does not install a second user-level service automatically. Inspect with `fengming gateway status --deep` or `fengming doctor --deep`, then remove the duplicate or set `FENGMING_SERVICE_REPAIR_POLICY=external` when a system supervisor owns the gateway lifecycle.
-
-  </Accordion>
-  <Accordion title="8b. Startup Matrix migration">
-    When a Matrix channel account has a pending or actionable legacy state migration, doctor (in `--fix` / `--repair` mode) creates a pre-migration snapshot and then runs the best-effort migration steps: legacy Matrix state migration and legacy encrypted-state preparation. Both steps are non-fatal; errors are logged and startup continues. In read-only mode (`fengming doctor` without `--fix`) this check is skipped entirely.
-  </Accordion>
-  <Accordion title="8c. Device pairing and auth drift">
-    Doctor now inspects device-pairing state as part of the normal health pass.
-
-    What it reports:
-
-    - pending first-time pairing requests
-    - pending role upgrades for already paired devices
-    - pending scope upgrades for already paired devices
-    - public-key mismatch repairs where the device id still matches but the device identity no longer matches the approved record
-    - paired records missing an active token for an approved role
-    - paired tokens whose scopes drift outside the approved pairing baseline
-    - local cached device-token entries for the current machine that predate a gateway-side token rotation or carry stale scope metadata
-
-    Doctor does not auto-approve pair requests or auto-rotate device tokens. It prints the exact next steps instead:
-
-    - inspect pending requests with `fengming devices list`
-    - approve the exact request with `fengming devices approve <requestId>`
-    - rotate a fresh token with `fengming devices rotate --device <deviceId> --role <role>`
-    - remove and re-approve a stale record with `fengming devices remove <deviceId>`
-
-    This closes the common "already paired but still getting pairing required" hole: doctor now distinguishes first-time pairing from pending role/scope upgrades and from stale token/device-identity drift.
-
-  </Accordion>
-  <Accordion title="9. Security warnings">
-    Doctor emits warnings when a provider is open to DMs without an allowlist, or when a policy is configured in a dangerous way.
-  </Accordion>
-  <Accordion title="10. systemd linger (Linux)">
-    If running as a systemd user service, doctor ensures lingering is enabled so the gateway stays alive after logout.
-  </Accordion>
-  <Accordion title="11. Workspace status (skills, plugins, and legacy dirs)">
-    Doctor prints a summary of the workspace state for the default agent:
-
-    - **Skills status**: counts eligible, missing-requirements, and allowlist-blocked skills.
-    - **Legacy workspace dirs**: warns when `~/fengming` or other legacy workspace directories exist alongside the current workspace.
-    - **Plugin status**: counts enabled/disabled/errored plugins; lists plugin IDs for any errors; reports bundle plugin capabilities.
-    - **Plugin compatibility warnings**: flags plugins that have compatibility issues with the current runtime.
-    - **Plugin diagnostics**: surfaces any load-time warnings or errors emitted by the plugin registry.
-
-  </Accordion>
-  <Accordion title="11b. Bootstrap file size">
-    Doctor checks whether workspace bootstrap files (for example `AGENTS.md`, `CLAUDE.md`, or other injected context files) are near or over the configured character budget. It reports per-file raw vs. injected character counts, truncation percentage, truncation cause (`max/file` or `max/total`), and total injected characters as a fraction of the total budget. When files are truncated or near the limit, doctor prints tips for tuning `agents.defaults.bootstrapMaxChars` and `agents.defaults.bootstrapTotalMaxChars`.
-  </Accordion>
-  <Accordion title="11d. Stale channel plugin cleanup">
-    When `fengming doctor --fix` removes a missing channel plugin, it also removes the dangling channel-scoped config that referenced that plugin: `channels.<id>` entries, heartbeat targets that named the channel, and `agents.*.models["<channel>/*"]` overrides. This prevents Gateway boot loops where the channel runtime is gone but config still asks the gateway to bind to it.
-  </Accordion>
-  <Accordion title="11c. Shell completion">
-    Doctor checks whether tab completion is installed for the current shell (zsh, bash, fish, or PowerShell):
-
-    - If the shell profile uses a slow dynamic completion pattern (`source <(fengming completion ...)`), doctor upgrades it to the faster cached file variant.
-    - If completion is configured in the profile but the cache file is missing, doctor regenerates the cache automatically.
-    - If no completion is configured at all, doctor prompts to install it (interactive mode only; skipped with `--non-interactive`).
-
-    Run `fengming completion --write-state` to regenerate the cache manually.
-
-  </Accordion>
-  <Accordion title="12. Gateway auth checks (local token)">
-    Doctor checks local gateway token auth readiness.
-
-    - If token mode needs a token and no token source exists, doctor offers to generate one.
-    - If `gateway.auth.token` is SecretRef-managed but unavailable, doctor warns and does not overwrite it with plaintext.
-    - `fengming doctor --generate-gateway-token` forces generation only when no token SecretRef is configured.
-
-  </Accordion>
-  <Accordion title="12b. Read-only SecretRef-aware repairs">
-    Some repair flows need to inspect configured credentials without weakening runtime fail-fast behavior.
-
-    - `fengming doctor --fix` now uses the same read-only SecretRef summary model as status-family commands for targeted config repairs.
-    - Example: Telegram `allowFrom` / `groupAllowFrom` `@username` repair tries to use configured bot credentials when available.
-    - If the Telegram bot token is configured via SecretRef but unavailable in the current command path, doctor reports that the credential is configured-but-unavailable and skips auto-resolution instead of crashing or misreporting the token as missing.
-
-  </Accordion>
-  <Accordion title="13. Gateway health check + restart">
-    Doctor runs a health check and offers to restart the gateway when it looks unhealthy.
-  </Accordion>
-  <Accordion title="13b. Memory search readiness">
-    Doctor checks whether the configured memory search embedding provider is ready for the default agent. The behavior depends on the configured backend and provider:
-
-    - **QMD backend**: probes whether the `qmd` binary is available and startable. If not, prints fix guidance including the npm package and a manual binary path option.
-    - **Explicit local provider**: checks for a local model file or a recognized remote/downloadable model URL. If missing, suggests switching to a remote provider.
-    - **Explicit remote provider** (`openai`, `voyage`, etc.): verifies an API key is present in the environment or auth store. Prints actionable fix hints if missing.
-    - **Legacy auto provider**: treats `memorySearch.provider: "auto"` as OpenAI, checks OpenAI readiness, and `doctor --fix` rewrites it to `provider: "openai"`.
-
-    When a cached gateway probe result is available (gateway was healthy at the time of the check), doctor cross-references its result with the CLI-visible config and notes any discrepancy. Doctor does not start a fresh embedding ping on the default path; use the deep memory status command when you want a live provider check.
-
-    Use `fengming memory status --deep` to verify embedding readiness at runtime.
-
-  </Accordion>
-  <Accordion title="14. Channel status warnings">
-    If the gateway is healthy, doctor runs a channel status probe and reports warnings with suggested fixes.
-  </Accordion>
-  <Accordion title="15. Supervisor config audit + repair">
-    Doctor checks the installed supervisor config (launchd/systemd/schtasks) for missing or outdated defaults (e.g., systemd network-online dependencies and restart delay). When it finds a mismatch, it recommends an update and can rewrite the service file/task to the current defaults.
-
-    Notes:
-
-    - `fengming doctor` prompts before rewriting supervisor config.
-    - `fengming doctor --yes` accepts the default repair prompts.
-    - `fengming doctor --fix` applies recommended fixes without prompts (`--repair` is an alias).
-    - `fengming doctor --fix --force` overwrites custom supervisor configs.
-    - `FENGMING_SERVICE_REPAIR_POLICY=external` keeps doctor read-only for gateway service lifecycle. It still reports service health and runs non-service repairs, but skips service install/start/restart/bootstrap, supervisor config rewrites, and legacy service cleanup because an external supervisor owns that lifecycle.
-    - On Linux, doctor does not rewrite command/entrypoint metadata while the matching systemd gateway unit is active. It also ignores inactive non-legacy extra gateway-like units during the duplicate-service scan so companion service files do not create cleanup noise.
-    - If token auth requires a token and `gateway.auth.token` is SecretRef-managed, doctor service install/repair validates the SecretRef but does not persist resolved plaintext token values into supervisor service environment metadata.
-    - Doctor detects managed `.env`/SecretRef-backed service environment values that older LaunchAgent, systemd, or Windows Scheduled Task installs embedded inline and rewrites the service metadata so those values load from the runtime source instead of the supervisor definition.
-    - Doctor detects when the service command still pins an old `--port` after `gateway.port` changes and rewrites the service metadata to the current port.
-    - If token auth requires a token and the configured token SecretRef is unresolved, doctor blocks the install/repair path with actionable guidance.
-    - If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, doctor blocks install/repair until mode is set explicitly.
-    - For Linux user-systemd units, doctor token drift checks now include both `Environment=` and `EnvironmentFile=` sources when comparing service auth metadata.
-    - Doctor service repairs refuse to rewrite, stop, or restart a gateway service from an older FengMing binary when the config was last written by a newer version. See [Gateway troubleshooting](/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
-    - You can always force a full rewrite via `fengming gateway install --force`.
-
-  </Accordion>
-  <Accordion title="16. Gateway runtime + port diagnostics">
-    Doctor inspects the service runtime (PID, last exit status) and warns when the service is installed but not actually running. It also checks for port collisions on the gateway port (default `18789`) and reports likely causes (gateway already running, SSH tunnel).
-  </Accordion>
-  <Accordion title="17. Gateway runtime best practices">
-    Doctor warns when the gateway service runs on Bun or a version-managed Node path (`nvm`, `fnm`, `volta`, `asdf`, etc.). WhatsApp + Telegram channels require Node, and version-manager paths can break after upgrades because the service does not load your shell init. Doctor offers to migrate to a system Node install when available (Homebrew/apt/choco).
-
-    Newly installed or repaired macOS LaunchAgents use a canonical system PATH (`/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) instead of copying the interactive shell PATH, so Homebrew-managed system binaries remain available while Volta, asdf, fnm, pnpm, and other version-manager directories do not change which Node child processes resolve. Linux services still keep explicit environment roots (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) and stable user-bin directories, but guessed version-manager fallback directories are only written to the service PATH when those directories exist on disk.
-
-  </Accordion>
-  <Accordion title="18. Config write + wizard metadata">
-    Doctor persists any config changes and stamps wizard metadata to record the doctor run.
-  </Accordion>
-  <Accordion title="19. Workspace tips (backup + memory system)">
-    Doctor suggests a workspace memory system when missing and prints a backup tip if the workspace is not already under git.
-
-    See [/concepts/agent-workspace](/concepts/agent-workspace) for a full guide to workspace structure and git backup (recommended private GitHub or GitLab).
-
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-- [Gateway runbook](/gateway)
-- [Gateway troubleshooting](/gateway/troubleshooting)

package/docs/gateway/gateway-lock.md

@@ -1,37 +0,0 @@
----
-summary: "Gateway singleton guard using the WebSocket listener bind"
-read_when:
-  - Running or debugging the gateway process
-  - Investigating single-instance enforcement
-title: "Gateway lock"
----
-
-## Why
-
-- Ensure only one gateway instance runs per base port on the same host; additional gateways must use isolated profiles and unique ports.
-- Survive crashes/SIGKILL without leaving stale lock files.
-- Fail fast with a clear error when the control port is already occupied.
-
-## Mechanism
-
-- The gateway first acquires a per-config lock file under the state lock directory and probes the configured port for an existing listener.
-- If the recorded lock owner is gone, the port is free, or the lock is stale, startup reclaims the lock and continues.
-- The gateway then binds the HTTP/WebSocket listener (default `ws://127.0.0.1:18789`) using an exclusive TCP listener.
-- If the bind fails with `EADDRINUSE`, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
-- On shutdown the gateway closes the HTTP/WebSocket server and removes the lock file.
-
-## Error surface
-
-- If another process holds the port, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
-- Other bind failures surface as `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
-
-## Operational notes
-
-- If the port is occupied by _another_ process, the error is the same; free the port or choose another with `fengming gateway --port <port>`.
-- Under a service supervisor, a new gateway process that sees an existing healthy `/healthz` responder leaves that process in control. On systemd, the duplicate starter exits with code 78 so the default `RestartPreventExitStatus=78` stops `Restart=always` from looping on a lock or `EADDRINUSE` conflict. If the existing process never becomes healthy, retries are bounded and startup fails with a clear lock error instead of looping forever.
-- The macOS app still maintains its own lightweight PID guard before spawning the gateway; the runtime lock is enforced by the lock file plus HTTP/WebSocket bind.
-
-## Related
-
-- [Multiple Gateways](/gateway/multiple-gateways) — running multiple instances with unique ports
-- [Troubleshooting](/gateway/troubleshooting) — diagnosing `EADDRINUSE` and port conflicts