Module capability_probe 

Exact user/path capability probes for runtimes, toolchains, and targets (bd-session-history-remediation-ocv9i.12.2).

A capability probe runs as the configured remote user, using the exact executable paths RCH will actually invoke (not whatever a login shell’s PATH happens to resolve), so the facts reflect what an offloaded build will really see. The probe is a single shell script that prints RCH_FACT k=v lines; parse_capability_probe turns that output into ProbedFacts, and assess_admissibility decides whether the worker is admissible for a given CapabilityRequirement.

Crucially this distinguishes SSH reachability (did the script run at all?) from capability admissibility (it ran, but lacks a needed target / the binary at the exact path is broken / the protocol is stale) — the two failure classes operators kept conflating.

Structs

CapabilityRequirement

What a command needs from a worker before it is admissible.

NamedToolProbe

An operator-declared named tool probe: a FIXED argv, written in worker configuration, run as the configured remote user.

ProbeSpec

Exact paths/identity the probe must use (never PATH-resolved).

ProbedFacts

Structured facts parsed from probe output. Sub-facts are None/empty when the corresponding probe produced no line (i.e. the capability is absent).

WorkerLiveness

A worker’s live admission state, separate from its (structural) capability. Capability says can this worker ever run the command; liveness says is it usable right now. Keeping them distinct is what lets selection report a missing-capability reason instead of conflating it with an unhealthy or busy worker.

Enums

CapabilityVerdict

Outcome of an admissibility assessment. Reachability is the caller’s concern (did the SSH probe run?); this answers “it ran — is it usable?”.

EligibilityVerdict

The distinct eligibility outcomes selection must tell apart, each with its own incident reason — so an agent learns why a worker was not chosen (missing capability vs unhealthy vs busy vs stale facts) rather than a single opaque “no admissible workers”.

ToolProbeError

Why an operator-declared tool probe was refused before it ever ran.

Constants

FACT_PREFIX

Sentinel prefix every probe fact line carries, so probe output is easy to separate from incidental stdout.

Functions

assess_admissibility

Assess admissibility of probed facts against a requirement. Assumes the probe was reachable (non-empty facts); a fully empty parse should be treated as unreachable by the caller, not passed here.

assess_worker_eligibility

Assess a worker’s full eligibility for a command, distinguishing missing capability from an unhealthy or busy worker. Pure and total.

build_capability_probe_script

Build the capability-probe shell script. It is intentionally fail-soft: every probe that errors simply omits its fact line, so a missing rustup or a broken binary shows up as absent facts (capability), never as a script crash (reachability).

normalize_probed_os

Collapse the many shapes uname -s takes on Windows into plain windows.

parse_capability_probe

Parse RCH_FACT k=v probe output into ProbedFacts. Lines without the prefix are ignored, so incidental stdout never corrupts the parse.

remote_worker_binary_path

The canonical ABSOLUTE path to the deployed rch-wkr binary for a remote user and host OS. Unix workers use /root or /home/<user>; Windows workers run under Git Bash and use /c/Users/<user> plus the native .exe suffix. The probe script shell-quotes this path, so it MUST be absolute: a literal ~/.local/bin/... would be single-quoted and never expand, making [ -x ... ] fail and every worker look like it has a missing binary. Single source of truth for both the daemon bypass-recovery prober and the rch self-test --smoke capability scenario.