action handler: SSH executor target (B1) — arago ExecuteCommand-over-SSH

The native executor made remote. ogar-action-handler::SshExecutor shells out to
the system `ssh` binary (dep-free, exactly like NativeCommandExecutor shells to
`sh` — no SSH-library / C dep), non-interactive by construction (BatchMode=yes,
StrictHostKeyChecking=accept-new), and returns the same output/stderr/exitcode
resultParameters shape. An ssh connection failure surfaces as exitcode 255 (a
reported result), not an executor error — same convention as the native one for
a failed command. Clone, so it composes into Daemon / run_gated as a gated route.

- build_args is the pure, testable half: BatchMode=yes always, optional -i/-p,
  the target, then `--` so the remote command is never re-parsed as an ssh flag.
- 4 tests: argv is non-interactive + well-ordered; -i/-p threaded; missing
  command is an error before spawn (no host needed); unknown capability rejected.
  End-to-end remote exec needs a live sshd (absent in CI) — documented.

Executor family split: the Command-based dep-free executors (native + SSH) live
in OGAR ogar-action-handler; the library-based network executor (REST, ureq)
lives in rs-graph-llm. WinRM is the one executor target left.

Also recovers two doc commits orphaned when #123 merged before they landed
(B2-transport + REST scorecard reflections), and adds the SSH reflection:
ARAGO-ACTIONHANDLER-PARITY (SSH §3 bullet + scorecard row + verdict + cross-ref),
D-ACTIONHANDLER-SSH discovery row.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EYvNjD8M8LMNYbRy3gq2FP

Author: claude

crates/ogar-action-handler/src/lib.rs

@@ -141,6 +141,118 @@ impl CapabilityExecutor for NativeCommandExecutor {
     }
 }
 
+/// Reference executor for the **SSH** target: runs an `ExecuteCommand`
+/// capability's `command` on a remote host via the system `ssh` binary. This is
+/// arago's canonical ActionHandler shape (`ExecuteCommand`-over-SSH) — the
+/// [`NativeCommandExecutor`], remote.
+///
+/// Dependency-free by design: it shells out to `ssh` (like the native one shells
+/// out to `sh`), so it carries no SSH-library / C dependency and fits the same
+/// sync [`CapabilityExecutor`] seam. Non-interactive by construction
+/// (`BatchMode=yes` — never prompt for a password/passphrase; a connection that
+/// would prompt fails fast). Returns the same `output` / `stderr` / `exitcode`
+/// shape as the native executor — an `ssh` connection failure surfaces as a
+/// non-zero `exitcode` (255), the same way the native one reports a failed
+/// command, *not* an executor error.
+///
+/// **Trust model:** identical to the native executor — the gate
+/// (`commit_via<ClassRbac>`) runs upstream; this executor assumes its caller
+/// already authorized the action and runs the command verbatim on the target.
+#[derive(Debug, Clone)]
+pub struct SshExecutor {
+    target: String,
+    identity: Option<String>,
+    port: Option<u16>,
+}
+
+impl SshExecutor {
+    /// The single capability this executor implements (same verb as native —
+    /// it is remote execution of the same `ExecuteCommand`).
+    pub const CAPABILITY: &'static str = "ExecuteCommand";
+
+    /// An SSH executor for `target` (`user@host` or `host`).
+    pub fn new(target: impl Into<String>) -> Self {
+        Self {
+            target: target.into(),
+            identity: None,
+            port: None,
+        }
+    }
+
+    /// Use a specific identity file (`ssh -i`).
+    #[must_use]
+    pub fn with_identity(mut self, identity: impl Into<String>) -> Self {
+        self.identity = Some(identity.into());
+        self
+    }
+
+    /// Connect on a non-default port (`ssh -p`).
+    #[must_use]
+    pub fn with_port(mut self, port: u16) -> Self {
+        self.port = Some(port);
+        self
+    }
+
+    /// Build the `ssh` argument vector for `command` — the pure, testable half
+    /// (no spawn). Always non-interactive (`BatchMode=yes`); `--` terminates ssh
+    /// options so the remote command is never re-parsed as a flag.
+    fn build_args(&self, command: &str) -> Vec<String> {
+        let mut args = vec![
+            "-o".to_owned(),
+            "BatchMode=yes".to_owned(),
+            "-o".to_owned(),
+            "StrictHostKeyChecking=accept-new".to_owned(),
+        ];
+        if let Some(port) = self.port {
+            args.push("-p".to_owned());
+            args.push(port.to_string());
+        }
+        if let Some(identity) = &self.identity {
+            args.push("-i".to_owned());
+            args.push(identity.clone());
+        }
+        args.push(self.target.clone());
+        args.push("--".to_owned());
+        args.push(command.to_owned());
+        args
+    }
+}
+
+impl CapabilityExecutor for SshExecutor {
+    fn execute(
+        &self,
+        capability: &str,
+        bound: &[(String, String)],
+    ) -> Result<Vec<(String, String)>, String> {
+        if capability != Self::CAPABILITY {
+            return Err(format!(
+                "ssh executor implements only `{}`, not `{capability}`",
+                Self::CAPABILITY
+            ));
+        }
+        let command = bound
+            .iter()
+            .find(|(k, _)| k == "command")
+            .map(|(_, v)| v.as_str())
+            .ok_or_else(|| "missing `command` parameter".to_owned())?;
+
+        let output = Command::new("ssh")
+            .args(self.build_args(command))
+            .output()
+            .map_err(|e| format!("failed to spawn ssh to `{}`: {e}", self.target))?;
+
+        let trim = |b: &[u8]| String::from_utf8_lossy(b).trim_end().to_owned();
+        Ok(vec![
+            ("output".to_owned(), trim(&output.stdout)),
+            ("stderr".to_owned(), trim(&output.stderr)),
+            (
+                "exitcode".to_owned(),
+                output.status.code().unwrap_or(-1).to_string(),
+            ),
+        ])
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -294,4 +406,43 @@ mod tests {
             result.result
         );
     }
+
+    #[test]
+    fn ssh_builds_a_non_interactive_argv() {
+        // The pure half: the ssh argv is well-formed and non-interactive.
+        let args = SshExecutor::new("ops@node-1").build_args("uptime");
+        // BatchMode=yes is mandatory (never prompt).
+        assert!(args.windows(2).any(|w| w == ["-o", "BatchMode=yes"]));
+        // target, then `--`, then the remote command (never re-parsed as a flag).
+        let dashdash = args.iter().position(|a| a == "--").unwrap();
+        assert_eq!(args[dashdash - 1], "ops@node-1");
+        assert_eq!(args[dashdash + 1], "uptime");
+    }
+
+    #[test]
+    fn ssh_identity_and_port_are_threaded() {
+        let args = SshExecutor::new("host")
+            .with_identity("/keys/id_ed25519")
+            .with_port(2222)
+            .build_args("ls");
+        assert!(args.windows(2).any(|w| w == ["-p", "2222"]));
+        assert!(args.windows(2).any(|w| w == ["-i", "/keys/id_ed25519"]));
+    }
+
+    #[test]
+    fn ssh_missing_command_is_an_error_before_spawn() {
+        // No `command` → error without ever invoking ssh (no host needed).
+        let err = SshExecutor::new("host")
+            .execute("ExecuteCommand", &[])
+            .unwrap_err();
+        assert!(err.contains("command"), "got: {err}");
+    }
+
+    #[test]
+    fn ssh_unknown_capability_is_rejected() {
+        let err = SshExecutor::new("host")
+            .execute("RunScript", &[("command".to_owned(), "x".to_owned())])
+            .unwrap_err();
+        assert!(err.contains("ExecuteCommand"), "got: {err}");
+    }
 }

docs/ARAGO-ACTIONHANDLER-PARITY.md

@@ -194,9 +194,14 @@ downstream. The remaining bricks:
   `graph-flow-action-ogar::rest::RestExecutor` (`feature = "rest"`, pure-Rust
   `ureq`) POSTs the bound params to an HTTP endpoint and returns the response as
   `resultParameters` — the arago HTTP-callout shape — and runs only behind the
-  gate (`rest_executor_runs_only_behind_the_gate`). SSH / WinRM follow the same
-  `CapabilityExecutor` trait (SSH = arago's canonical `ExecuteCommand`-over-SSH);
-  rs-graph-llm hosts the production executors (the gate runs `commit_via`).
+  gate (`rest_executor_runs_only_behind_the_gate`). The **SSH target** is coded
+  too: `ogar-action-handler::SshExecutor` shells out to the system `ssh`
+  (dep-free, non-interactive `BatchMode=yes`) — arago's canonical
+  `ExecuteCommand`-over-SSH, the native executor made remote; its argv
+  construction + pre-spawn guards are tested, end-to-end exec needs a live host
+  (no sshd in CI). WinRM is the one executor target left. The native + SSH
+  (Command-based, dep-free) executors live in OGAR `ogar-action-handler`; the
+  network ones (REST, library-based) live in rs-graph-llm.
 - **B1-uplink — the hard gate before the executor (SHIPPED).** rs-graph-llm's
   `graph-flow-action-ogar` crate is the seam: `GatedOgarHandler` wraps an OGAR
   `CapabilityExecutor` as a `graph-flow-action::ActionHandler`, so the executor's
@@ -260,7 +265,8 @@ transport over them.
 | **Executor — native target (B1)** | ✅ `[G]` SHIPPED | `ogar-action-handler::NativeCommandExecutor` runs `ExecuteCommand` for real; `full_dispatch_runs_a_real_command` |
 | **Hard gate before executor (B1-uplink)** | ✅ `[G]` SHIPPED | rs-graph-llm `graph-flow-action-ogar::GatedOgarHandler` — `commit_via` (RBAC ∧ guard ∧ MUL) lands before `handle`; `take_result()` is `None` iff the gate refused (3 tests) |
 | **Executor — REST target (B1)** | ✅ `[G]` SHIPPED | rs-graph-llm `graph-flow-action-ogar::rest::RestExecutor` (`feature = "rest"`, ureq) POSTs bound params → resultParameters; runs only behind the gate (`rest_executor_runs_only_behind_the_gate`) |
-| **Executor — SSH/WinRM (B1)** | ⛔ `[H]` | further `CapabilityExecutor` impls (SSH = arago's canonical `ExecuteCommand`-over-SSH; needs an SSH client + a live host to test) |
+| **Executor — SSH target (B1)** | 🟡 `[G]` code / `[H]` live | `ogar-action-handler::SshExecutor` shells out to system `ssh` (non-interactive `BatchMode=yes`, same `output`/`stderr`/`exitcode` shape as native) — arago's canonical `ExecuteCommand`-over-SSH, dep-free. argv construction + pre-spawn guards tested; end-to-end needs a live host (no sshd in CI) |
+| **Executor — WinRM (B1)** | ⛔ `[H]` | a further `CapabilityExecutor` impl (Windows remote exec) |
 | **Live transport — daemon core + WebSocket (B2-transport)** | ✅ `[G]` SHIPPED | rs-graph-llm `graph-flow-action-ogar::daemon`: transport-agnostic `Daemon::react`/`serve` + `Transport` trait + `WsTransport` (action-ws), gate-driving; mock-server roundtrip. `Auth` ← OGIT `NTO/Auth/Configuration` |
 | **Live transport — Kafka edge (B2-transport)** | ⛔ `[H]` | `rdkafka` over the same `Transport` trait (action topic → result topic); core ready, needs the topic/record shape pinned |
 | **Instance config lift — capabilities (B2-lift)** | ✅ `[G]` SHIPPED | `registration::lift_registration` + `ogar-action-handler::parse_capabilities`: real `GET /capabilities` JSON → `ConcreteCapability` (`ActionParam[]`); `rest_registration_lifts_binds_and_runs` (JSON → lift → bind → run) |
@@ -280,17 +286,18 @@ end-to-end, `rest_registration_lifts_binds_and_runs`) and per-handler `StateGuar
 sets (`rest_applicabilities_lift_to_per_handler_guards`). And the **live daemon
 runs over a real socket** — `graph-flow-action-ogar::daemon` drives the gated
 dispatch through a `Transport` trait, with the `action-ws` WebSocket edge proven
-by a mock-server roundtrip. Two executor targets run gated — **native** (local
-command) and **REST** (HTTP callout). What's left for a **live** drop-in
-replacement of arago's Python daemon: the **Kafka transport edge** (HIRO's
-internal bus — `rdkafka` over the same `Transport` trait, needs the topic/record
-shape pinned) and the **SSH executor** (arago's canonical `ExecuteCommand`-over-SSH
-— an SSH client over the same `CapabilityExecutor` trait, needs a live host to
-test). Each is a single edge/runner impl over existing types — **no missing IR,
-no missing protocol mapping**. That is the honest state: OGAR *is* an ActionHandler
-that reads its own registration, gates every action, runs commands and HTTP
-callouts, and speaks `action-ws` over a live socket; a Kafka consumer + an SSH
-runner away from being arago's Python daemon, on any HIRO deployment.
+by a mock-server roundtrip. Three executor targets run gated — **native** (local
+command), **SSH** (remote command, arago's canonical shape — coded, live-host test
+pending) and **REST** (HTTP callout). The one thing left for a **live** drop-in
+replacement of arago's Python daemon that needs a real input: the **Kafka
+transport edge** (HIRO's internal bus — `rdkafka` over the same `Transport` trait,
+needs the topic/record shape pinned + a broker to test). WinRM is a further
+executor for completeness. Everything is a single edge/runner impl over existing
+types — **no missing IR, no missing protocol mapping**. That is the honest state:
+OGAR *is* an ActionHandler that reads its own registration, gates every action,
+runs commands locally / over SSH / as HTTP callouts, and speaks `action-ws` over a
+live socket; a Kafka consumer away from being arago's Python daemon, on a HIRO
+deployment that distributes over Kafka.
 
 ---
 
@@ -329,6 +336,8 @@ is replaceable; the parity claim is certified, not argued.
   `WsTransport` (action-ws WebSocket edge) + the OGIT-`Auth`-derived identity.
 - `rs-graph-llm/graph-flow-action-ogar/src/rest.rs` — the **REST executor**
   (`RestExecutor`, `feature = "rest"`): the arago HTTP-callout target, gated.
+- `crates/ogar-action-handler/src/lib.rs` — the **native** (`NativeCommandExecutor`)
+  + **SSH** (`SshExecutor`, shells out to `ssh`) executor targets, dep-free.
 - arago: `github.com/arago/ActionHandlers`,
   `arago/python-hiro-stonebranch-actionhandler`, HIRO 7 Action API tutorial.
 - **HIRO 7 Action API machine-readable specs (the authoritative harvest, §2a):**

docs/DISCOVERY-MAP.md

@@ -215,6 +215,7 @@ two halves of a cell. ADR‑026 names the cascade that ties them.
 | D‑ACTIONHANDLER‑B2LIFT | REST registration **instance lift** (B2-lift) — turns a deployed handler's `GET /capabilities` JSON (`MapOfCapabilities`) into the concrete signatures the *schema* half can't supply: `registration::{RegisteredCapability,ModelFilter}` (typed DTOs, `Deserialize` behind the `serde` feature) + the pure lift `lift_registration → ConcreteCapability` (concrete `ActionParam[]` with `(name,mandatory,default)`) and `model_filter_to_guard` (arago `ModelFilter{Var,Mode,Value}`→`KausalSpec::StateGuard`, field‑for‑field). Producer stays parser‑free; the runtime `ogar-action-handler::parse_capabilities` does the `serde_json` read (producer‑defines‑types / runtime‑does‑I/O split). Proven end‑to‑end: `rest_registration_lifts_binds_and_runs` (real JSON → lift → `bind_parameters` → `NativeCommandExecutor` runs the command). Remaining: the `GET /applicabilities` `MapOfApplicabilities` envelope read (the `ModelFilter→StateGuard` lift is done). **CORRECTION (canon‑pass 2026‑06‑24): applicabilities envelope now SHIPPED** — `registration::{RegisteredApplicability,lift_applicabilities}` + `ogar-action-handler::parse_applicabilities` lift a real `GET /applicabilities` JSON body into per‑handler `StateGuard` sets (`rest_applicabilities_lift_to_per_handler_guards`); inner filter‑list field name alias‑flexible (`modelFilters`/`model`/`filters`) pending a live response. Supersedes the "Remaining" note | G | CODED | `ogar-from-schema/src/registration.rs`, `ogar-action-handler/src/lib.rs` | D‑ACTIONHANDLER‑PARITY |
 | D‑ACTIONHANDLER‑TRANSPORT | The live action daemon (B2-transport), **transport-agnostic** by construction: rs‑graph‑llm `graph-flow-action-ogar::daemon::Daemon::react` turns one inbound `action-ws` JSON frame into the outbound frames it warrants (ack + `sendActionResult`, or nack), running the hard gate (`run_gated`) + executor in between — pure, no I/O. A `Transport` trait (`recv`/`send`) is the swappable edge; `Daemon::serve` is the loop; both the WebSocket and a future Kafka edge share it verbatim (HIRO distributes actions over BOTH wires — the wire differs, the dispatch doesn't). The `WsTransport` action-ws edge (`feature = "ws"`, tokio-tungstenite) presents the `token-$TOKEN` subprotocol and is proven by `ws_roundtrip_against_a_mock_server` (engine submitAction → ack → real command → result over a socket). Connection identity is an `Auth` type shaped after OGIT `NTO/Auth/Configuration` (`auth_store` 0x0B01): the principal the transport authenticates as (`accountId`) IS the actor the gate authorizes. Remaining: the Kafka edge (`rdkafka` over the same trait — core ready, needs topic/record shape) and SSH/REST executors | G (core + ws edge) / H (kafka edge) | CODED | `rs-graph-llm/graph-flow-action-ogar/src/daemon.rs` | D‑ACTIONHANDLER‑UPLINK, D‑ACTIONHANDLER‑B2LIFT |
 | D‑ACTIONHANDLER‑REST | REST executor target (B1) — the arago HTTP-callout handler shape: rs‑graph‑llm `graph-flow-action-ogar::rest::RestExecutor` (`feature = "rest"`, pure-Rust `ureq`, sync — fits the sync `CapabilityExecutor` trait) POSTs the bound params as a JSON body to a configured endpoint, returns the response `status`+`body` as `resultParameters`. Any completed HTTP response (incl. 4xx/5xx) is `resultParameters`; only a transport failure is an executor `Err` (mirrors arago reporting the callee's response). `Clone` (ureq Agent is Arc-backed) ⟹ composes into `Daemon`/`run_gated` as a gated route. Proven: `posts_params_and_returns_status_and_body` (mock HTTP) + `rest_executor_runs_only_behind_the_gate` (authorized → REST call fires; unauthorized → `Denied`, endpoint never hit). Completes the executor family with native; SSH/WinRM remain | G | CODED | `rs-graph-llm/graph-flow-action-ogar/src/rest.rs` | D‑ACTIONHANDLER‑UPLINK |
+| D‑ACTIONHANDLER‑SSH | SSH executor target (B1) — arago's canonical `ExecuteCommand`-over-SSH: `ogar-action-handler::SshExecutor` shells out to the system `ssh` binary (dep-free, like `NativeCommandExecutor` shells to `sh`), non-interactive by construction (`BatchMode=yes`), same `output`/`stderr`/`exitcode` resultParameters shape — the native executor made remote. `build_args` (pure argv construction with `-i`/`-p` + `--` command terminator) and the pre-spawn guards (missing-command / unknown-capability) are tested; end-to-end remote exec needs a live sshd (absent in CI). The two Command-based dep-free executors (native + SSH) live in OGAR; library-based network executors (REST) in rs-graph-llm | G (code) / H (live exec) | CODED | `ogar-action-handler/src/lib.rs` | D‑ACTIONHANDLER‑REST |
 | D‑OSM | `ogar-from-osm-pbf` — Node/Way/Relation; quadkey NiblePath from resolved geometry | H | IDEA | (queued) | D‑VOCAB, `[per rt]` D‑OSM‑3 |
 | D‑PATTERN | `ogar-pattern` — recognition library + confidence (FMA‑D/FIBO/SKR/PROV‑O) | H | IDEA | (queued) | D‑TTL |
 | D‑ACTION | `ogar-actionable` — lifecycle → `ActionDef`/`KausalSpec` | H | IDEA | (queued) | D‑PATTERN |