fix(parse): surface :repl/exception! as structured :repl-exception failure

Closes #17. parse-cljs-eval-response was passing shadow's
:repl/exception! sentinel through as a value, producing
{:ok? true :value :repl/exception! :rfp.wire/value-fits? true} —
the same false-trust-signal class as #6, one layer down (#6 was
:value nil; this is :value :<sentinel>). A caller that trusts
:ok? true would treat the sentinel as a value and reason from it.

The sentinel fires when shadow-cljs's printer throws while
serialising the eval result. Most common trigger is forms touching
re-frame.core/dispatch or subscribe — re-frame internal types /
reagent reactions throw inside pr-str. The bug bites the eval-cljs
escape-hatch op specifically, forcing users into the dispatch.sh-only
workflow and losing programmatic re-frame interaction.

Fix: in parse-cljs-eval-response, when the parsed result equals
:repl/exception!, throw structured ex-info {:reason :repl-exception
:raw-response <res> :hint "..."}. eval-op's existing try/catch
surfaces it as {:ok? false :reason :repl-exception ...}.

Hint names workarounds — but only ones that actually work, per the
issue's own evidence (the (do ... :ok) wrap was tested in the issue
report and STILL surfaced :repl/exception!, so we don't suggest it):

- For dispatch flows: scripts/dispatch.sh (routes around the eval
  channel via the runtime's wire layer).
- For subscribe reads: deref the underlying ratom rather than the
  subscribe ratom directly.
- Notes the more robust wire/return! layer fix as a follow-up.

Adds a :repl-exception row to docs/skill/troubleshooting.md so
agents can translate the new reason.

2 new deftests cover the sentinel detection and the negative case
(a legitimate :ok keyword result still passes through, no
regression).

Out of scope: the deeper wire/return! fix that would pre-stringify
re-frame internal types so shadow's printer never sees them. The
issue itself flags this as the more robust direction; a separate
focused issue would track it. The parse-side detection is the
trust-signal fix that unblocks the eval-cljs escape hatch from
silently lying about success today.

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

Author: mike-thompson-day8

docs/skill/troubleshooting.md

@@ -16,6 +16,7 @@ Every script returns structured edn like `{:ok? false :reason ...}`. Translate t
 | `: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). |
+| `:repl-exception` | shadow-cljs's printer threw while serialising the eval result (sentinel `:repl/exception!`). Most common cause: `eval-cljs.sh` of a form that touches `re-frame.core/dispatch` or `subscribe` — re-frame internal types / reagent reactions throw inside `pr-str`. Workaround: route dispatches through `scripts/dispatch.sh` instead; for subscribe reads, deref the underlying ratom rather than the subscribe ratom directly. |
 
 ## Multi-Build Setups
 

scripts/ops.clj

@@ -548,7 +548,22 @@
             nil
 
             :else
-            (safe-edn (peek (:results outer)))))
+            (let [parsed (safe-edn (peek (:results outer)))]
+              ;; #17 — :repl/exception! is shadow's marker for a
+              ;; printer throw on the eval result. Most commonly:
+              ;; forms that touch re-frame.core/dispatch or subscribe
+              ;; return reagent reactions / re-frame internal types
+              ;; whose pr-str throws while shadow is serialising for
+              ;; the wire. Old behaviour passed the sentinel through
+              ;; as `{:value :repl/exception! :ok? true}` — a false
+              ;; trust signal of the same class as #6. Surface as a
+              ;; structured runtime exception instead.
+              (if (= :repl/exception! parsed)
+                (throw (ex-info "shadow returned :repl/exception! — eval result couldn't be serialised"
+                                {:reason :repl-exception
+                                 :raw-response res
+                                 :hint "shadow-cljs's printer threw while serialising the eval result. Most common cause: forms that touch re-frame.core/dispatch or subscribe — re-frame's internal types / reagent reactions throw inside pr-str. Workarounds: for dispatch flows use scripts/dispatch.sh (routes around the eval channel via the runtime's wire layer); for subscribe reads, pull the deref'd value out yourself before it crosses the wire (e.g. `(deref @some-ratom)` rather than the subscribe ratom directly). A more robust fix at the wire/return! layer is tracked separately."}))
+                parsed))))
 
         ;; Newer shadow may return {:err "..."} on cljs errors.
         (and (map? outer) (:err outer))

tests/ops_smoke.bb

@@ -1260,6 +1260,41 @@
         (is (str/includes? (:hint @emitted) "register-epoch-cb")
             ":hint mentions the native cb as an alternative to 10x")))))
 
+;; ---------------------------------------------------------------------------
+;; Tests for issue #17: parse-cljs-eval-response must surface
+;; :repl/exception! as a structured runtime exception, not pass it
+;; through as a value with :ok? true (the false-trust pattern).
+;; ---------------------------------------------------------------------------
+
+(deftest parse-surfaces-repl-exception-sentinel
+  (testing "shadow's :repl/exception! sentinel inside :results becomes :reason :repl-exception"
+    (let [res {:value (pr-str
+                        {:results [(pr-str :repl/exception!)]
+                         :out ""
+                         :err ""
+                         :ns 'cljs.user})}
+          thrown (try (#'ops/parse-cljs-eval-response res)
+                      (catch clojure.lang.ExceptionInfo e
+                        {:msg (.getMessage e) :data (ex-data e)}))]
+      (is (= :repl-exception (-> thrown :data :reason))
+          ":repl-exception is the structured failure")
+      (is (contains? (:data thrown) :raw-response)
+          ":raw-response carries shadow's response for debugging")
+      (is (str/includes? (-> thrown :data :hint) "dispatch.sh")
+          ":hint points at the dispatch.sh workaround")
+      (is (str/includes? (-> thrown :data :hint) "wire/return!")
+          ":hint mentions the more robust wire-layer fix as a follow-up"))))
+
+(deftest parse-still-returns-real-keyword-results
+  (testing "no regression: a legitimate keyword result (NOT :repl/exception!) passes through"
+    (let [res {:value (pr-str
+                        {:results [(pr-str :ok)]
+                         :out ""
+                         :err ""
+                         :ns 'cljs.user})}]
+      (is (= :ok (#'ops/parse-cljs-eval-response res))
+          "ordinary keyword results are unaffected by the sentinel detection"))))
+
 ;; ---------------------------------------------------------------------------
 ;; Tests for issue #18: tail-build's --probe must detect every
 ;; error↔value transition as a flip, not just value→value.