These are the remaining checks and repairs apus doctor performs, beyond the postures and maintenance modes documented on the other pages.

• In Nix mode (APUS_NIX_MODE=1), read-only doctor checks still work, but doctor --fix, doctor --repair, doctor --yes, and doctor --generate-gateway-token are disabled because apus.json is immutable. Edit the Nix source for this install instead; for nix-apus, use the agent-first Quick Start.
• Interactive prompts (keychain/OAuth fixes, etc.) only run when stdin is a TTY and --non-interactive is not set. Headless runs (cron, Telegram, no terminal) skip prompts.
• Standalone non-interactive mode skips prompts, not full provider-catalog or runtime-tool validation. Update-time optional checks can be deferred with warnings. Built checkout runs reuse available compiled plugin entries for these checks; intentional source overrides still execute source. See Development debugging.
• --lint is stricter than --non-interactive: always read-only, never prompts, never applies safe migrations. Use doctor --fix or doctor --repair when you want doctor to make changes.
• Doctor does not execute exec SecretRefs while checking secrets by default. Use --allow-exec (with or without --lint) only when you intentionally want doctor to run those configured secret resolvers.

Config writes and backups

Update-history inspection and reconciliation are best-effort maintenance. A failure prints a warning and allows independent Doctor repairs and plugin registry mutations to continue. Writable passes also try to save the warning on the latest existing SQLite update run, without changing its outcome or activity timestamps or creating a new run. Read-only passes do not write history. Database integrity, migration, and unsettled process cleanup checks still protect mutations.

Snapshot workers use the runtime executing the CLI. Native workers inherit an unchanged working directory, avoiding a redundant directory change that can fail after sudo -u switches users. A spawn refusal names the runtime and working directory; check executable permissions and directory access for the service user. Disk-space or XDG_CACHE_HOME guidance applies to snapshot storage failures, not runtime launch permissions.

After its checks finish, doctor --fix settles its own inspection workers while retaining maintenance ownership, then checks whether abandoned updater runtimes can be removed. Independent Apus processes, Worker threads, and shared-broker work still prevent removal. Doctor reports the holder PIDs and asks you to let their work finish before rerunning apus doctor --fix.

• On npm global installs, Doctor reports retained .apus.package-backup-*.databases directories (and .apus-package-backup-*.databases, the name a failed cleanup retires them under) beside the installed package, with their total regular-file size in bytes and human-readable units and a quoted removal command for each directory. The scan is bounded; incomplete sizes are lower bounds. If inspection is incomplete before any snapshot is found, Doctor warns and asks you to list the npm global root manually, including hidden entries. A missing global root produces no warning. This is warning-only, including with --fix: confirm no update is in progress and no recovery needs the snapshots before removing them manually. Updater-driven Doctor passes defer this check so they do not report the active update's snapshots; run standalone Doctor after the update settles.
• Any config write (including a --fix repair) rotates a backup to ~/.apus/apus.json.bak (with a numbered .bak.1...bak.4 ring). --fix also drops unknown config keys reported by schema validation, listing each removal; it skips this while an update is in progress so partially written upgrade state is not stripped before its migration finishes.
• If apus.json cannot be parsed and no last-known-good config can be recovered, doctor --fix leaves the file unchanged and exits with an error instead of writing a partial replacement. The error points to apus config validate for the exact parse position and explains how to edit or regenerate the config.

Gateway and service repairs

• Set APUS_SERVICE_REPAIR_POLICY=external when another supervisor owns the gateway lifecycle. Have that owner stop the Gateway, run Doctor as the state-owning account, then restart through the owner. Doctor skips native maintenance inspection and service mutations, including install/start/restart/bootstrap and legacy service cleanup; it keeps Gateway/state coordinators and agent-database lease checks, reports service health, and applies non-service repairs. See Existing system LaunchDaemons.
• Doctor and gateway status --deep distinguish an unavailable launchd domain, a missing systemd user bus, and native check access denial. See Gateway and service recovery for runtime-environment, dbus-user-session, and external-supervisor guidance.
• Doctor reports the managed Gateway's applied heap limit and the adaptive derivation used for the current host or container memory limit. Use apus gateway status for the same report outside a repair pass.
• Doctor and apus gateway status skip systemd content repair advice when the manager reports a masked or otherwise unloaded unit. Loaded-unit checks, readable-file fallback after a failed manager query, and unrelated backup or credential diagnostics remain active.
• On Linux, doctor ignores inactive extra gateway-like systemd units and does not rewrite command/entrypoint metadata while a systemd gateway service is active; explicit repair stops an eligible service before reconciling installation drift. Use apus gateway install --force to rewrite the managed base unit. If a systemd drop-in overrides ExecStart= or WorkingDirectory=, inspect it with systemctl --user cat <unit>.service and update or remove that drop-in yourself; reinstalling the base does not replace it. Environment= drop-ins remain supported.
• doctor --fix --non-interactive preserves the installed launcher and environment except for eligible installation drift in a previously running service, including during update repair. Separately, Linux policy refresh backs up outdated Apus unit settings, confirms daemon-reload, and verifies the effective shutdown timeout before maintenance. Operator drop-ins remain unchanged. Short or unknown resident shutdown budgets use bounded lifecycle drain; reported write custody refuses the deadline stop, while interrupted turns produce a warning. Stopped services keep their launcher and stop state; their Linux policy can refresh without activation. Run apus gateway install for a missing service, or apus gateway install --force from the intended installation to replace its launcher and managed environment.

Session state and cron

• State integrity checks detect orphan transcript files in the sessions directory. Archiving them as .deleted.<timestamp> requires interactive confirmation; --fix, --yes, and headless runs leave them in place.
• Doctor scans historical ~/.apus/cron/jobs.json stores and previously configured legacy store locations for old cron job shapes, imports jobs and quarantine records into SQLite, and archives the migrated JSON files.
• Doctor reports cron jobs with an explicit payload.model override, including provider-namespace counts and mismatches against agents.defaults.model, so scheduled jobs that do not inherit the default model are visible during auth or billing investigations.
• Doctor reports cron jobs still marked in-flight (state.runningAtMs), which can make apus cron list show them as running. This check is read-only: if no Gateway is currently executing a marked job, the next cron service startup records the interrupted run and clears the marker.

Tool and channel policy

• Doctor inspects active tool schemas once per run, sharing plugin registration across the fleet while checking each agent's tool factories, policy, and selected model. Model preparation also shares provider registrations and config snapshots when agents resolve to the same plugin sources within one captured configuration generation; distinct plugin selections and explicit workspace registry owners remain separate. Failed plugin registrations and cleanup produce findings without hiding healthy agents' results. If a model needs live provider discovery, Doctor reports that its model-specific schema inspection was deferred; normal authenticated agent use performs that discovery. Standalone lint retains its read-only catalog checks. Update-time inspection can be deferred with a recorded warning.
• Doctor reports legacy image-inspection policy entries named image. apus doctor --fix rewrites supported config allow/deny surfaces and persisted automation toolsAllow entries to view_image; old-only wildcard patterns such as image* are preserved and gain an explicit view_image, while patterns that already cover both names remain unchanged. Runtime exposes only the canonical name.
• On Linux, doctor warns when the user's crontab still runs the unmaintained legacy ~/.apus/bin/ensure-whatsapp.sh, which can misreport Gateway inactive when cron lacks the systemd user-bus environment.
• When WhatsApp is enabled, doctor can report Gateway pressure and detected local TUI clients. These observations do not identify the cause or connect a client to that Gateway. Inspect Gateway diagnostics before deciding whether to close clients; Doctor does not stop them.
• When HTTP(S) proxy environment variables are present but tools.web.fetch.useTrustedEnvProxy is disabled, doctor explains that web_fetch still uses direct routing, runs a short direct TLS connectivity check, and names the explicit opt-in. It never enables proxy trust automatically.

Models and auth

• Doctor rewrites legacy codex/* and openai-codex/* model refs to canonical openai/* refs across primary models, fallbacks, model allowlists, image/video generation models, heartbeat/subagent/compaction overrides, hooks, channel model overrides, cron payloads, and stale session/transcript route pins. --fix also merges legacy models.providers.codex and models.providers.openai-codex config when safe, migrates legacy openai-codex:* auth profiles and auth.order.openai-codex entries to openai:*, moves Codex intent onto provider/model-scoped agentRuntime.id: "codex" entries, removes stale whole-agent/session runtime pins, and keeps repaired OpenAI agent refs on Codex auth routing instead of direct OpenAI API-key auth.
• Doctor also repairs retired model names in preferred media selections and converts CLI-encoded model references across fallback lists, model maps, media slots, and session provider/model pairs. Migrated agent selections keep per-model runtime choices; explicit canonical runtimes and session runtime overrides win. Canonical entries win collisions while missing nested settings are retained. These reference repairs preserve account pins, custom namespaced model IDs, and session bindings.
• Doctor reports an info finding when an active model reference names a known provider but is missing from that provider's local catalog. Providers that contribute no catalog rows offline (for example OpenRouter, whose catalog is discovered at runtime) are skipped, because an unlisted id there is not evidence of a typo.
• doctor --fix moves the old Claude-only conversation ID into the provider-keyed session binding before removing the old field. Existing bindings and their resume metadata take precedence. Empty or ambiguous bindings stay saved with a reconciliation warning while safe sessions migrate. When Doctor clears stale Claude routing state outside the configured route, it also clears the old field so migration cannot restore that conversation. Run this repair after upgrading before resuming sessions that only have the old field; runtime lookup and normal saves use provider-keyed bindings.
• doctor --fix migrates retired auth provider and profile identifiers in existing shared and agent SQLite stores, as well as legacy JSON imports. It preserves credentials and account metadata, uses unused profile IDs for collisions, and updates config references and rotation state together. Existing migration receipts retain verified account mappings across an interrupted store pass or failed config write; a changed account is not adopted on retry. Explicit empty config orders stay empty. Unreadable stores and unresolved credential realms remain unchanged with diagnostics; independent safe stores can still migrate.
• Doctor reports nonempty auth.order.<provider> lists whose referenced profiles are all gone while compatible stored credentials exist. doctor --fix deletes only those stale overrides, restoring automatic per-agent credential selection; explicit empty orders, partially live lists, and orders without a compatible stored credential stay unchanged. If an active SQLite auth store is unreadable or malformed, doctor explains why it skipped this repair. Restart a running Gateway before rechecking auth status if its config reload mode does not apply the write automatically.
• When doctor --fix removes a stale agent-local OAuth copy so the agent inherits the shared account, it preserves that account's position in the agent's saved auth order. Local cooldown and success state for the removed copy are cleared; the shared credentials and other local accounts remain unchanged. This also applies when Doctor runs during an update.

Plugins and skills

• doctor --fix reclaims abandoned legacy plugin captures and retained updater runtimes during maintenance. Unfamiliar launcher syntax alone does not block cleanup when readable working-directory and package evidence establish that a process is unrelated. Absolute entrypoint paths still require readable foreign package identity. Apus identities, entrypoint and module references, capture/runtime paths, and native capture custody preserve live artifacts. The standard Linux systemd --user manager and its same-account PAM helper do not block reclamation when their protected working directories are unreadable. The manager changes to / before serving; its PAM helper only settles that login session. Readable working-directory and runtime references still protect live artifacts. Unreadable same-user arguments or other unresolved working-directory, script, package, or service-marker evidence leave cleanup skipped with a warning; failed evidence inspection is never treated as proof that a process is unrelated.
• First-write native session catalog privacy preferences do not enable plugins or expand plugins.allow. Doctor warns when an enabled Codex entry contains only the catalog opt-out and matches the possible accidental enablement from Apus 2026.9.3/9.4. This signature cannot distinguish the old automatic write from an intentional choice, so --fix preserves it. If you did not enable Codex, set plugins.entries.codex.enabled to false and remove codex from plugins.allow if present, preserving the other entries.
• Doctor preserves legacy shared plugin-runtime caches that another installation or profile may still use and removes only genuinely dangling plugin-runtime symlinks. It relinks the host apus package for managed npm plugins that declare it as a peer dependency. It also repairs missing downloadable plugins referenced by config (plugins.entries, configured channels, configured provider/search settings, configured agent runtimes). During package updates, doctor skips package-manager plugin repair until the package swap completes; rerun apus doctor --fix afterward if a configured plugin still needs recovery. If a download fails, doctor reports the install error and preserves the configured plugin entry for the next repair attempt.
• doctor --fix also updates drifted active official npm plugins from the Apus catalog to the installed Apus release, using the same plugin updater as apus update. Recorded non-default tags and pins newer than the release's plugin cohort keep their selected targets. It reports each outcome and rechecks restart readiness. A plugin that cannot be fetched remains a warning with the failure reason; other plugins can still be repaired and Doctor can finish. This repair leaves third-party plugins unchanged. The normal Gateway maintenance and restart policy applies; follow the printed restart command when Doctor does not restart the Gateway for you.
• Doctor repairs stale plugin config by removing missing plugin ids from plugins.allow/plugins.deny/plugins.entries, plus matching dangling channel config, heartbeat targets, and channel model overrides, when plugin discovery is healthy.
• Doctor quarantines invalid plugin config by disabling the affected plugins.entries.<id> entry and removing its invalid config payload. Gateway startup already skips only that bad plugin so other plugins and channels keep running.
• Doctor removes the retired plugins.entries.codex.config.codexDynamicToolsProfile; the Codex app-server always keeps Codex-native workspace tools native.
• Doctor auto-migrates legacy flat Talk config (talk.voiceId, talk.modelId, and friends) into talk.provider + talk.providers.<provider>. Repeat doctor --fix runs no longer report/apply Talk normalization when the only difference is object key order.
• Doctor includes a memory-search readiness check and can recommend apus configure --section model when embedding credentials are missing.
• Doctor warns when no command owner is configured. The command owner is the human operator account allowed to run owner-only commands and approve dangerous actions. DM pairing only lets someone talk to the bot; if you approved a sender before first-owner bootstrap existed, set commands.ownerAllowFrom explicitly.
• Doctor reports an info note when Codex-mode agents are configured and personal Codex CLI assets exist in the operator's Codex home. Local Codex app-server launches use isolated per-agent homes; install the Codex plugin first if needed, then use apus migrate plan codex to inventory assets that should be promoted deliberately.
• Doctor warns when skills allowed for the default agent are unavailable in the current runtime environment (missing bins, env vars, config, or OS requirements). doctor --fix can disable those unavailable skills with skills.entries.<skill>.enabled=false and lists the changes without asking you to repeat the repair. Updater-driven repair leaves optional skill enablement unchanged. Install/configure the missing requirement instead if you want to keep the skill active.
• If an older Doctor run disabled a working sag skill, re-enable it with apus config set skills.entries.sag.enabled true.

Sandbox

• If sandbox mode is enabled but Docker is unavailable, doctor reports a high-signal warning with remediation (install Docker or apus config set agents.defaults.sandbox.mode off).
• Doctor identifies per-agent agents.entries.<id>.sandbox Docker, browser, and prune overrides ignored under shared scope. It also warns when an agent's explicit primary model omits fallbacks and therefore disables the defaults' fallback chain; both diagnostics use canonical agent paths after legacy roster normalization.
• If retired sandbox registry files or shard directories are present (~/.apus/sandbox/containers.json, ~/.apus/sandbox/browsers.json, ~/.apus/sandbox/containers/, or ~/.apus/sandbox/browsers/), Doctor reports them and --fix refuses without changing their contents. Upgrade through 2026.9.7 and run apus doctor --fix on the original host first; see legacy state migration.

Secrets and channel credentials

• If gateway.auth.token/gateway.auth.password are SecretRef-managed and unavailable in the current command path, doctor reports a read-only warning and does not write plaintext fallback credentials. For exec-backed SecretRefs, doctor skips execution unless --allow-exec is present.
• If channel SecretRef inspection fails in a fix path, doctor continues and reports a warning instead of exiting early.
• After state-directory migrations, doctor warns when enabled default Telegram or Discord accounts depend on env fallback and TELEGRAM_BOT_TOKEN or DISCORD_BOT_TOKEN is unavailable to the doctor process.
• Telegram allowFrom username auto-resolution (doctor --fix) requires a resolvable Telegram token in the current command path. If token inspection is unavailable, doctor reports a warning and skips auto-resolution for that pass.