feat(shell): add --exec flag; fix broken firmware-ping just recipe

`just firmware-ping` was invoking `cargo run -- ping` which fails
immediately because `ping` was removed as a CLI subcommand in #51
(the shell became a discovery-driven REPL).  This PR fixes that by
adding `--exec <COMMAND>` to telepath-shell for non-interactive
single-command execution, and rewiring firmware-ping to use it with
a sentinel grep so wire-format skew fails loudly.

AGENTS.md is updated to prompt the developer to run `just firmware-ping`
on PRs touching wire / macros / server / client / shell / nrf52840-ping.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: tarotene

AGENTS.md

@@ -140,6 +140,14 @@ Changes to the macro MUST NOT break existing callers on stable toolchain.
 - Feature branches MUST be created before any code change.
 - PRs MUST reference the corresponding GitHub Issue.
 - `examples/nrf52840-ping/` changes SHOULD be a separate commit from workspace changes.
+- PRs that touch any of the following SHOULD be smoke-tested with `just firmware-ping`
+  against a connected nRF52840-DK before requesting review, and the result recorded in
+  the PR description's Test plan section:
+  - `telepath-wire/`, `telepath-macros/`, `telepath-server/`, `telepath-client/`
+  - `tools/telepath-shell/`
+  - `examples/nrf52840-ping/`
+
+  This catches FW/host wire-format skew that `just ci` alone cannot detect without hardware.
 
 ## Toolchain
 
@@ -158,3 +166,5 @@ git config --local core.hooksPath .githooks
 - `pre-commit` → `just fmt-check` (sub-second; runs on every commit)
 - `pre-push` → `just clippy` + `just test` (~30 s; runs before every push)
 - `just ci` (fmt-check + clippy + test + emulator) SHOULD be run before opening a PR.
+- `just firmware-ping` SHOULD additionally be run when the PR touches wire / macros /
+  server / client / shell / nrf52840-ping (see "Commit and PR Rules" above).

Justfile

@@ -38,9 +38,11 @@ cli-build:
 cli *ARGS:
     cd tools/telepath-shell && cargo run -- {{ARGS}}
 
-# End-to-end smoke test: flash then ping
+# Local end-to-end smoke: rebuild FW, flash, run `ping` once, assert sentinel.
+# Requires nRF52840-DK connected.  Catches wire-format skew between FW and host.
 firmware-ping: firmware-flash
-    cd tools/telepath-shell && cargo run -- ping
+    cd tools/telepath-shell && cargo run -- --exec ping | tee /tmp/telepath-firmware-ping.out
+    grep -qF "ping -> 0xDEADBEEF" /tmp/telepath-firmware-ping.out
 
 # Build telepath-mcp-server
 mcp-build:

tools/telepath-shell/src/main.rs

@@ -68,6 +68,13 @@ struct Cli {
     /// By default, telepath-shell issues a soft reset and retries the attach once.
     #[arg(long)]
     no_reset: bool,
+
+    /// Execute a single command non-interactively and exit.
+    /// The argument uses the same syntax as the interactive REPL prompt:
+    /// `ping`, `add 1 2`, `led_set 1 true`, etc.
+    /// Exit code is non-zero if discovery or the command itself fails.
+    #[arg(long, value_name = "COMMAND")]
+    exec: Option<String>,
 }
 
 fn parse_hex_u64(s: &str) -> Result<u64, String> {
@@ -122,6 +129,16 @@ fn main() -> anyhow::Result<()> {
         )
     })?;
     client.transport_mut().clear_read_deadline();
+
+    if let Some(line) = cli.exec.as_deref() {
+        let line = line.trim();
+        let mut parts = line.splitn(2, char::is_whitespace);
+        let name = parts.next().unwrap_or("");
+        let rest = parts.next().unwrap_or("").trim();
+        dispatch_command(&mut client, name, rest)?;
+        return Ok(());
+    }
+
     println!("{n} command(s) discovered  (Ctrl-D / Ctrl-C to exit)");
 
     let mut commands: Vec<String> = client