fix(trace-recent): structured :bad-arg on non-integer window, no Java stack

Closes #16. trace-recent-op called Integer/parseInt on the first
positional arg outside any try/catch. Passing a stray flag (e.g.
trace-recent.sh --limit 25) leaked a NumberFormatException stack to
stderr — violating the skill's "every script returns structured EDN"
contract and giving agents nothing translatable to the user.

Now: parse is wrapped; on failure, dies with
{:reason :bad-arg :got <input> :hint "..."} explaining that the
window is in milliseconds (not a count, the natural mistake) and
showing the correct usage.

Adds a :bad-arg row to docs/skill/troubleshooting.md so agents have a
known mapping.

2 new deftests cover both branches: non-integer arg surfaces :bad-arg
via die; valid integer proceeds past parse without dying.

Note: 5 sibling parse sites have the same Integer/Long parseInt-without-
try shape (watch-op flags --window-ms / --count / --idle-ms / --hard-ms
/ --poll-ms; tail-build's --wait-ms; the predicate parser's --timing-ms
already handles bad input via parse-predicate-args). A sweep fixing
those is worth filing as a follow-up but out of scope for this bug
which was specifically against trace-recent.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mike-thompson-day8

docs/skill/troubleshooting.md

@@ -15,6 +15,7 @@ Every script returns structured edn like `{:ok? false :reason ...}`. Translate t
 | `:handler-error` | The user's handler threw. Point at `:handler/error` and stack details. |
 | `:timed-out? true` | The dispatch cascade did not settle. The tab may be backgrounded, debugger paused, or async chain continuing. |
 | `:connection :lost` | Reconnect with `scripts/discover-app.sh`. |
+| `:bad-arg` | A positional or flag arg failed to parse. The response carries `:got` (the offending input) and `:hint` (correct usage). Common cause: passing a flag where a positional integer is expected — e.g. `trace-recent.sh --limit 25` (the script takes `<window-ms>` as its only positional). |
 
 ## Multi-Build Setups
 

scripts/ops.clj

@@ -1386,7 +1386,15 @@
 (defn- trace-recent-op [args]
   (ensure-port!)
   (when (empty? args) (die :missing-window :hint "usage: trace-recent <ms>"))
-  (let [ms          (Integer/parseInt (first args))
+  (let [raw-ms      (first args)
+        ms          (try (Integer/parseInt raw-ms)
+                         (catch NumberFormatException _
+                           (die :bad-arg
+                                :got raw-ms
+                                :hint (str "trace-recent expects <window-ms> as a positive integer "
+                                           "(milliseconds, NOT epoch count). "
+                                           "Got non-integer: " (pr-str raw-ms) ". "
+                                           "Usage: trace-recent.sh <window-ms> [--build=<id>]"))))
         build-id    (build-id-from-args (rest args))
         reinjected? (ensure-injected! build-id)]
     (try

tests/ops_smoke.bb

@@ -1260,6 +1260,42 @@
         (is (str/includes? (:hint @emitted) "register-epoch-cb")
             ":hint mentions the native cb as an alternative to 10x")))))
 
+;; ---------------------------------------------------------------------------
+;; Tests for issue #16: trace-recent.sh must surface parse failures as
+;; structured EDN, not leak Java stack traces.
+;; ---------------------------------------------------------------------------
+
+(deftest trace-recent-non-integer-window-surfaces-bad-arg
+  (testing "trace-recent with a non-integer window emits :reason :bad-arg via die, not a NumberFormatException"
+    (let [die-args (atom nil)]
+      (with-redefs [ops/ensure-port! (fn [] true)
+                    ;; die is auto-throw-mocked by the :each fixture for safety;
+                    ;; this test additionally captures the args.
+                    ops/die          (fn [reason & {:as extra}]
+                                       (reset! die-args (assoc extra :reason reason))
+                                       (throw (ex-info "die" {:reason reason})))]
+        (try (#'ops/trace-recent-op ["--limit"])
+             (catch clojure.lang.ExceptionInfo _))
+        (is (= :bad-arg (:reason @die-args))
+            "structured :reason instead of bare NumberFormatException")
+        (is (= "--limit" (:got @die-args))
+            ":got carries the offending input verbatim")
+        (is (str/includes? (:hint @die-args) "milliseconds")
+            ":hint clarifies that the window is in ms, not a count (the natural mistake)")))))
+
+(deftest trace-recent-valid-integer-window-passes-through
+  (testing "trace-recent with a valid integer window proceeds past parse without die-ing"
+    (let [die-called? (atom false)]
+      (with-redefs [ops/ensure-port!     (fn [] true)
+                    ops/die              (fn [& _]
+                                           (reset! die-called? true)
+                                           (throw (ex-info "should-not-die" {})))
+                    ops/ensure-injected! (fn [_] false)
+                    ops/cljs-eval-value  (fn [& _] [])
+                    ops/emit             (fn [_] nil)]
+        (#'ops/trace-recent-op ["3000"])
+        (is (false? @die-called?) "valid integer arg does not trigger any die")))))
+
 ;; ---------------------------------------------------------------------------
 ;; Tests for issue #14: refuse non-shadow-cljs nREPLs early with a structured
 ;; :unsupported-build-tool, instead of crashing on the first call to