Health check

The health check certifies the install: the runtime, the settings and the release channel are checked live and rolled into one verdict. It runs interactively as /health and headless as mercury health. The home screen's Health Check row opens the same certificate. Configured MCP servers are validated without being started.

The report is read-only against Mercury: it consults gate helpers, snapshots, small local artifacts and operating-system metrics, echoes no credential, and its only write is the last-certificate summary.

Certificate verdicts

Every check carries a mandatory evidence string naming the artifact, probe or value consulted, and fixes are ranked worst-first.

certified (OK badge in /health): No check reads fail, warn, stale or unknown.
caution (ATTENTION badge in /health): At least one check reads warn, stale or unknown, and none reads fail.
fault (FAILED badge in /health): At least one check reads fail.

A check's status is one of ok, warn, fail, stale, unknown, off or info. A check without evidence reads unknown; evidence that predates what it certifies reads stale. off and info are neutral and stay out of the verdict.

A fast run certifies sixteen sections: IDENTITY, PROOFS, GIT, CREW & DAEMONS, MEMORY & CONTEXT, SETTINGS & FLAGS, AUTH, INTERFACE, RUNTIME, DURABILITY, TERMINAL RUNTIME, PROFILE, CODING LOOP, TERMINAL FLUIDITY, TOOL CAPABILITY and ARCHITECTURE PRIMITIVES.

Run a health check

Run mercury health from the command line to print the certificate: the verdict, the sections with their checks and evidence, and the ranked fixes.

Open the interactive certificate

Enter /health in a session (or select Health Check on the home screen) to open the health popup with the install's certificate and fixes: the verdict badge beside the title, the provenance and counts under it, every check as a row with its status in one scrolling list, and the key legend when the window fits. ↑, ↓, the mouse wheel and PageUp/PageDown move through the list, Enter or → opens a row's evidence and detail in place, ← closes it, f opens the fix card on a fixable row, r and d re-run the check, and Esc or a click outside closes the popup.

Inspection options

--json: Prints the certificate as one JSON document.
--deep: Runs the deep inventory in addition to the fast checks.
--only <id>: Limits the plain report, --json or --fix to one check.

A piped or redirected run is not the host's interactive terminal, so the terminal-profile row reads as environmental and stays out of the verdict.

Notable checks

Client contract: In IDENTITY, names the client version Mercury presents on the Claude sign-in and where it came from. A too-old contract refusal causes Mercury to read the current version once and retry.
Refused models: In IDENTITY, keeps a model refused for a minimum client version, a subscription tier or a model-specific 403 or 404 visible with the same sentence as the chat and the picker. A successful request for that model on that route clears the refusal; with no recorded refusal the row reads info.
Browser: In INTERFACE, names the executable the Browser tool resolves. With no managed browser the row reads info and names /browser install, the one-time consented Chrome for Testing download.
Tools withheld: In TOOL CAPABILITY, names every built-in tool kept out of the model's catalogue because a machine dependency is absent, such as a debug adapter for Debug or the desktop driver for Computer, with the reason and the remedy.
Local media: In TOOL CAPABILITY, shows whether local media generation is off, the configured media folder when the folder and runtime binary exist (ok), or a warning when the folder or runtime is missing (with /imagesetup as the fix) or when default model slot keys were placed in Mercury's settings instead of <media.root>/config.json (Local images and video).
Env overrides: In SETTINGS & FLAGS, lists the registered flags set in the environment, with Mercury's own stamps and the boot's saved defaults named apart from your overrides. A retired setting still set turns the row to warn, and the fix says to unset it.
Store isolation: In CREW & DAEMONS, reports a config-home record written by another tool with its evidence line. Its remedy archives the foreign records into a dated directory inside the home, reversibly.
Store quarantines: Names a store file Mercury will not read. A global configuration field of the wrong shape is dropped and named on its own row, and the rest of the file is read.
Box lock: In RUNTIME, names the box lock's coordination directory from MERCURY_BOX_LOCK_DIR, the slots held and by whom, and the tickets waiting.
Session kind: In RUNTIME, reads the focused session's kind from its daemon record (Sessions). An oculus session belongs to a screen: its permission asks and questions wait without timing out until you answer them or end the session, including while you switch to another chat. A headless session is unattended: its unanswered asks expire on their clock, and an unanswered question ends the run as blocked. A record without a kind reads as headless until the session is resumed from the screen, and with no chat open the row says so. The row is info and leaves the verdict unchanged.
Sovereign mode: Shows the permission-posture record: whether Sovereign mode is on, what turned it on, and whether the consent dialog was shown. The record is kept per project, and the row names the folder it describes.
Artifact signature and Payload signature: Report the release signature verdict on the bundle's bytes, and with --deep on the whole payload tree.
Bash tool shell: Names the shell that serves the Bash tool and why (on Windows, the bundled brush shell engine is the default whenever its pack is present, while MERCURY_SHELL_ENGINE=system or shell.engine set to system keeps Git Bash's bash.exe; on macOS and Linux, the system shell is the default and brush is opt-in), alongside the Shell engine row (iface-shell-engine), and warns on Windows when neither the bundled engine nor Git Bash is available.
Terminal color: Reports the detected colour depth and the reason.
Default model: Says which model a fresh, unpinned session starts on and why.
Memory front page and Semantic embedder: In MEMORY & CONTEXT, report the memory front page's size, its topic lines and how full the pinned shelf is, and whether the on-device semantic embedding addon and model are present for meaning-ranked recall.
Model lists and Provider slots: In AUTH, Model lists judges every typed model identifier Mercury carries across all 21 typed-id provider families against the live model list this process has already read for that provider (lists read <n> of 21), and shows a lapsed or rejected stored sign-in as refused with the time until signed in again. A typed identifier the list lacks is a warning that names it, and a provider whose list was not read in this process says so. Provider slots (provider-slots) checks that every engine family either reads configured or names one of its unavailable codes (no-account:, no-api-key:, no-credential:, not-configured:, no-server: and the like), and that the Anthropic classes resolve to their own family's models. When a fresh client has read a newer model list than a running daemon's snapshot, daemon-sign-ins grades the difference as info. The 1-hour prompt-cache gate row names the condition that holds and reads live even while off, and a daemon-hosted session's requests are reported from its worker.
Web search: In AUTH, reports the search cascade available to the session's model, including native provider search, Brave or Tavily keys, the official APIs, configured SearXNG instances, and keyless DuckDuckGo page scraping. When no search source is available for the model, the row reads info and names BRAVE_API_KEY (or TAVILY_API_KEY) and /config to turn DuckDuckGo page scraping back on.
Transcript store and State cleanup: In DURABILITY, Transcript store probes the live session's own transcript file when one exists (opened for read and append without writing) and names the file and any refusal; when no session file exists yet, it probes the folder and states that the folder is writable. State cleanup reports <config-home>/file-history usage against its 500 MB limit alongside the configured retention window (Sessions).
Managed policy: Warns, with its fix, on an invalid lock value, an unknown surface name or an unreadable policy file.
Mercury constitution: In IDENTITY, reports the size of the short constitution that opens every session, headless run, crewmate and coordinator, with the sizes of the coordinator and crewmate contracts beside it.
Hidden characters: In SETTINGS & FLAGS, scans instruction files, skills and settings files for characters you cannot see but a model reads, such as zero-width characters and direction overrides, and names each file and line that carries one. Mercury loads the files as written and changes nothing; the fix is to delete what you did not write. A hidden character in an MCP tool definition is stripped when Mercury discovers the tool, and the row names the tool.
Crewmates & workflows: Reads the two delegation switches with their sources, as /crewmates and /workflows show them.
Mercury processes: In CREW & DAEMONS, lists Mercury's own local processes and classes each one as running, stale, cannot end or not Mercury's, by Mercury's own facts: a live terminal, a live session, a live window behind a daemon. Its remedy shows the stale ones with their pid, terminal, age and reason and ends them only after asking; the boot ends nothing, and a process in a kernel wait reads as needing a reboot. The bounded wait before the kill signal is MERCURY_PROCESS_SWEEP_WAIT_MS. Headless, mercury health processes prints the same listing as JSON and --end-stale ends the stale ones it lists.
Computer use, Voice input and Samples: In INTERFACE, name the desktop driver with its grants and access type, the voice backend with its transcriber and permission words, and which way the Samples switch stands.

AUTH's Anthropic row checks the claude.ai sign-in before it answers, and the OpenAI row does the same for a ChatGPT subscription: a sign-in whose access token has not reached its expiry is read locally and makes no request; one past its expiry is renewed through its refresh grant, the one request the check makes, and the row reads renewed on this check; a grant the provider refuses marks the sign-in expired, the row warns with sign-in expired and its fix is the same line the chat shows (/logins <family> reconnects). The same check runs once when Mercury opens, so an expired sign-in shows on the boot screen's Logins row (<Family> sign-in expired) before a first prompt is sent. When a prompt does meet an expired sign-in, its words come back to the composer under the error line and are sent again on their own once /logins lands a credential (or /model moves the session to a family that is signed in) while the composer still holds them unchanged.

Fix reported problems

Run mercury health --fix to apply the safe remedies and re-probe each one; the outcome shown is the re-probe's result.

A destructive remedy needs --yes on the command line: mercury health --fix --yes applies the process sweep's remedy like any other. In the interactive panel a fix goes through a consent card, and a destructive remedy renders its warning. A remedy is offered only for fail, warn and stale rows. Every applied fix writes an evolution-ledger row.

The health JSON

mercury health --json prints the certificate as one JSON document (certSchema 2) carrying verdict, ranAt, version, durationMs and depth; head, the repository state at issue time; nodeRuntime, the runtime contract with its verdict; sections[], each with its checks and their evidence, evidenceAt and status; and readiness[], the capability-readiness rows for tools, MCP servers, lanes, engines, extensions and skills.

Artifacts and switches

Certificate files live beside the project's transcripts under <config home>/projects/<project>/, in the health store. MERCURY_HEALTH_STATE_DIR selects the project root used to resolve the store.

health/last-cert.json: The summary written after each certificate. The certificate chip in the session chrome reads it, and a summary older than a day reads stale.
health/last-preflight.json: The boot preflight's summary. The preflight runs a cheap subset of /health after the interface mounts, notifies only on a fault, and writes no certificate.
gate/verdict.json: Written by the local check pool. The PROOFS section reads it as evidence and reports it stale when it predates the current HEAD.
MERCURY_HEALTH_CERT=0: Restores a plain install-diagnostics screen with no certificate and no artifact writes.
MERCURY_HEALTH_FIX=0: Makes /health diagnose-only.
MERCURY_BOOT_PREFLIGHT=0: Skips the boot preflight.

Install and update · Reporting a problem · Workspace trust and permissions · Local images and video · Command-line reference