Verify Chmonitor

Verify chmonitor

Agent-facing control skill. Read this cold, then the matching file under features/. Primary surface is the standalone CLI (chm, alias chmonitor). The web dashboard is a second user surface — map it, do not require adding a host on dash.chmonitor.dev.

Helpers live in .cursor/skills/verify-chmonitor/scripts/ and are executable. Source of truth for commands is those scripts plus this file — not remembered flags.

Launch

There is no long-lived CLI server. Launch means build this checkout's binary once, then start each drive in an isolated process or tmux session.

.cursor/skills/verify-chmonitor/scripts/launch.sh

What it does:

1. Requires rustc/cargo >= 1.85 (workspace lockfile pulls edition-2024 crates; CI uses dtolnay/rust-toolchain@stable). This Cloud image shipped 1.83 — rustup toolchain install stable && rustup default stable first.
2. cargo build -p chmonitor --manifest-path rust/Cargo.toml (debug profile; release enables LTO/opt-level=z and is too slow for verification).
3. Installs rust/target/debug/chm and chmonitor to $VERIFY_PREFIX/bin/ (default /tmp/verify-chmonitor/prefix/bin/).
4. Writes $VERIFY_PREFIX/identity.json (bin, crate_version, target, git_head). Ready when chm --version prints <crate version> (<target>), e.g. chm 0.1.3 (x86_64-unknown-linux-gnu).

Teardown of the install is optional (scripts/cleanup.sh --purge). Scratch config and tmux sessions are removed by scripts/cleanup.sh without --purge.

Isolated config (required): every chm invocation in this skill uses --config $VERIFY_SCRATCH/config.toml. That parent dir is not ~/.config/chm, so the connection store does not touch the OS keyring. Do not set XDG_CONFIG_HOME to the scratch dir — that would make user_config_dir() match and enable keyring. Do not write to the operator's ~/.config/chm.

Env that must be unset unless a recipe passes an explicit --ch-host: CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, <!-- pragma: allowlist secret --> CLICKHOUSE_DATABASE, CHM_API_KEY, CHM_TOKEN, CI, GITHUB_ACTIONS, <!-- pragma: allowlist secret --> CHM_NO_TUI. Cloud agent shells often have TERM=dumb and a real CLICKHOUSE_HOST; both change CLI behavior (wants_tui is false when <!-- pragma: allowlist secret --> TERM=dumb / CI / --json / --no-tui; a set CLICKHOUSE_HOST turns <!-- pragma: allowlist secret --> chm doctor and bare chm into a direct cluster session).

Helpers already unset those. If you call chm by hand, wrap with the chm function in scripts/lib.sh or copy that env -u … block.

Default dashboard API: https://dash.chmonitor.dev (--base-url / VERIFY_BASE_URL). Local ClickHouse for cluster/TUI recipes: <!-- pragma: allowlist secret --> http://127.0.0.1:8123 (VERIFY_CH_HOST) when /ping returns 200. Never add a host on the hosted product.

Do not use git worktrees for this skill.

Doctor

.cursor/skills/verify-chmonitor/scripts/doctor.sh            # identity only (default)
.cursor/skills/verify-chmonitor/scripts/doctor.sh --http     # also dashboard HTTP (bounded)
.cursor/skills/verify-chmonitor/scripts/doctor.sh --cluster  # plus local CH scan

Run doctor before the first drive, on every fresh CLI session, and after any failed drive. If doctor cannot see a wedged TUI, kill that tmux session and start a new one — do not keep typing into a stuck pane.

Identity (fail closed). The binary on PATH for this run must be the launch install: realpath matches identity.json, --version contains rust/ch-monitor-cli/Cargo.toml's version and a compile-time target (env!("CHM_TARGET")), path is under $VERIFY_PREFIX. This is the "is this binary ours?" check. A crates.io or ~/.local/bin chm is not ours. Default doctor.sh is identity-only: it writes doctor-identity.json and doctor-version.txt and does not call dash.chmonitor.dev. Hosted GET /api/healthz is cluster-gated and can hang for minutes — it is not the prove. Connectivity is opt-in (--http / VERIFY_DOCTOR_HTTP=1) and wrapped in timeout --foreground --kill-after=1s (VERIFY_DOCTOR_HTTP_TIMEOUT, default 5s). Never wait on that HTTP.

Connectivity (chm doctor with CLICKHOUSE_* unset). JSON array of <!-- pragma: allowlist secret --> {check, ok, detail}:

chm doctor exits non-zero if any row is not ok. That does not mean the wrong binary. Identity can pass while cloud dashboard_health / credentials fail. Do not chm auth login unless the feature under test needs the dashboard API as a signed-in user. Never mint hosts on dash.chmonitor.dev.

Cluster (chm doctor --ch-host http://127.0.0.1:8123). Required before driving the live TUI or --no-tui snapshot against a CH HTTP interface. curl $VERIFY_CH_HOST/ping must be 200. The scan is read-only (readonly=2). --json prints score, grade, findings, version. Exit 1 only means a critical finding, not a bad binary.

Global --json and doctor --json both select JSON (args.json || cfg.json).