feat: __selftest read-only probe (version, config validity, dependency reachability)

[rshade]

Overview

Add a reserved, auto-mounted, read-only __selftest command that reports tool
version, config validity, and auth/reachability of declared dependencies. It
lets an agent verify the tool actually works in THIS environment before
attempting real work — the operational, runtime form of grounding, and the
ground-truth partner of the F16 auth-preflight metadata claim.

User Story

As an LLM agent about to use an ax-go CLI in an unfamiliar environment, I want a
single read-only command that confirms the binary runs, its config parses, and
its declared dependencies are reachable/authenticated, So that I fail fast with
a clear diagnosis instead of discovering a broken environment mid-task.

Problem Statement

An agent can read __schema to learn what a tool can do, but has no cheap way
to learn whether the tool works here right now: is the config valid, is the
API token present and accepted, is the backend reachable? Without this, the
agent's first real command doubles as an environment probe, and failures surface
as ambiguous mid-operation errors. __selftest is cheap to build on existing
primitives (ResolveVersion, ParseConfig, HTTPClient/GRPCDial) and gives
agents a deterministic pre-flight. It is the runtime ground truth behind F16's
static auth-preflight claim: F16 declares which dependencies need auth;
__selftest + the exit-4 envelope verify it.

Proposed Solution

Mirror the __schema auto-mount pattern with a new reserved __selftest
command that runs a set of read-only checks and emits a structured, deterministic
result envelope.

Technical Approach

• Auto-mount __selftest exactly like __schema: add an ensureSelftestCommand
  helper in execute.go called from prepareCommand, guarded so an adopter
  that defines its own is not overridden (same idempotent pattern as
  ensureSchemaCommand, execute.go:172).
• Provide a builder (e.g. NewSelftestCommand, plus a public probe-registration
  API) so adopters declare checks: a version check (always, via ResolveVersion),
  config-validity checks (reusing ParseConfigFile), and dependency
  reachability/auth checks (using ax.HTTPClient/ax.GRPCDial with secure
  defaults — never InsecureSkipVerify).
• Define a SelftestResult envelope struct in contract/: per-check
  name/status(ok|fail|skip)/detail, overall pass/fail, and version.
  Deterministic shape (struct, not map); non-deterministic fields (latency,
  timestamps) documented as such.
• Exit-code mapping reuses the existing contract: auth failures → exit 4,
  network/timeout → exit 3, config invalid → exit 2, all-ok → exit 0. This is the
  runtime counterpart to F16's declared auth metadata.
• Checks are strictly read-only (no writes, honor --dry-run semantics as a
  no-op since it is already side-effect-free).

Files Likely Affected

• execute.go - ensureSelftestCommand auto-mount (model: ensureSchemaCommand)
• new selftest.go (root) + a public builder - NewSelftestCommand, probe registration API
• contract/ (new file) - SelftestResult envelope shape
• version.go - ResolveVersion reused for the version check
• config.go - ParseConfigFile reused for config-validity checks
• http.go - HTTPClient/GRPCDial reused for reachability/auth probes
• schema/ - reserve/surface __selftest alongside __schema
• examples/integration/main.go - demonstrate registered probes

Acceptance Criteria

• __selftest is auto-mounted on every ax-go CLI (like __schema) unless the adopter defines its own
• It reports version, config validity, and per-dependency reachability/auth as a structured deterministic envelope
• Exit codes follow the contract: 0 ok, 2 config-invalid, 3 network, 4 auth
• All checks are read-only (no side effects)
• Tests pass with adequate coverage (per AGENTS.md testing-first discipline)
• Documentation updated if needed

Out of Scope

• Continuous/background health monitoring (this is a one-shot probe)
• Remediation/auto-fix of failing checks (report only; actionable_fix hints allowed)
• The static F16 auth-preflight metadata declaration itself (separate feature; this is its runtime verifier)

Technical Notes

The SelftestResult shape lives in the CONTRACT packages so thin consumers pin
it. Additive (Constitution XI): a new reserved command + result shape, no change
to existing surfaces. Auto-mount reuses the __schema idempotent-guard pattern.
Deterministic output modulo documented non-deterministic fields (latency). Probes
must use the secure ax.HTTPClient/ax.GRPCDial defaults and must never log
tokens/PII. Routes through the Spec Kit workflow; coordinate the exit-4/auth
semantics with F16 so the claim and its ground truth stay consistent.

Testing Strategy

• Unit tests for each check type (version, config-valid/invalid, reachable/unreachable, authed/unauthed) and exit-code mapping
• Golden-file test for the SelftestResult envelope and for __selftest appearing in __schema
• Test that __selftest is auto-mounted and that an adopter-defined override is respected
• stdout/stderr separation and race checks

Related

• Related issues: Agent-acceptance test harness (drive CLI from __schema) #31 (agent-acceptance harness — external driver vs. this in-tool probe), Envelope runtime trust signals (side-effects/idempotency-replay/handoff) #30 (envelope trust signals)
• Partner feature: F16 (auth-preflight metadata) — __selftest + exit-4 envelope are its runtime ground truth
• Provenance: kimi-features.md feature F14, 2026-07-17 eight-agent evaluation