feat(nrepl): ADR-0170 am1 — cider/analyze-last-stacktrace (the *cider-error* buffer)

Smell-audited: 2: ADR-0170 amendment 1 with the mandatory DA fork; the DA's
Alt 2 adopted over the draft's parallel-capture channel — *e becomes the
single error channel (cider-nrepl's own model), closing a real F-011 gap.

- *e is set for EVERY caught REPL error (JVM clojure.main parity — catalog
  errors previously left it nil): the engine materializes the peeked Info
  via allocExceptionLoc (the VM catch-path shape) + a new ExInfo.phase byte,
  covering the reader-error branch too
- throw stamps the live call stack onto trace-less exceptions
  (stampTraceIfAbsent, both backends symmetric) so a user (throw (ex-info …))
  carries frames like a catalog raise
- the op walks *e's ex-cause chain: class/message/phase/data + frames
  innermost-first with clj/repl/project/dup flags + navigable file-url;
  phase maps to the clojure.error vocabulary so CIDER routes compile-phase
  errors to inline overlays, JVM style; bare alias advertised too
- FIXED en route: evalImpl fed the SCRATCH-owned request code into evals
  whose products outlive the message (use-after-free surfacing as garbage
  strings under scratch-reuse pressure) — the source is now duped onto the
  persistent arena, mirroring the CLI REPL's per-line dupe

Verified: e2e 4j (ex-info chain / catalog+reader phases / no-error) +
CLI *e pin (case 7) + the real nrepl 1.3.1 Java client driving the op.

Author: chaploud

.dev/decisions/0170_nrepl_rearchitecture_cider_fidelity.md

@@ -235,6 +235,86 @@ binding maps — the F-011 oracle; bb's global `set!` across id-tags is
 bb's simplification and would let tooling-session evals rotate the
 user's `*1`).
 
+## Amendment 1 — `cider/analyze-last-stacktrace` (the `*cider-error*` buffer)
+
+**Context** (user field report, 2026-07-14): CIDER's `*cider-error*`
+buffer renders "at [no stack trace available]" against cljw. CIDER's
+error handler is a 3-way decision (cider-compilation.el
+`cider-default-err-handler`): the op `cider/analyze-last-stacktrace`
+when advertised → the rich numbered-causes buffer with Show/Hide frame
+filters; else a `clojure.stacktrace` eval; else the bare print
+fallback cljw currently hits. The op's wire contract (cider-nrepl
+middleware/stacktrace.clj + orchard/stacktrace.clj + the
+cider-stacktrace.el renderer's `nrepl-dbind-response` bindings):
+
+- One response dict per CAUSE: `class` (string), `message`, optional
+  `phase` (clojure.error phase name), optional `data` (printed
+  ex-data), `stacktrace` = list of frame dicts; then `{status [done]}`.
+  No last error → `{status [no-error]}` then `{status [done]}`.
+- Frame keys the renderer binds: `name` `ns` `fn` `file` `file-url`
+  `line` `class` `method` `var` `flags`; `flags` (strings) drive the
+  Show/Hide filters (`clj` / `java` / `repl` / `tooling` / `project` /
+  `dup`).
+
+**Decision (DA Alt 2 — `*e` is the single channel).** cljw implements
+the op natively (no cider-nrepl), and the op **analyzes the session's
+`*e` on demand** — cider-nrepl's own model (`(@session #'*e)`) — rather
+than keeping a parallel capture channel:
+
+- **`*e` is set for EVERY caught REPL error, catalog errors included**
+  — closing a real F-011 gap: JVM `clojure.main/repl` sets `*e` for
+  compiler errors too, while cljw only did for thrown Values. The
+  engine materializes the peeked catalog Info (the existing
+  `peekLastError()` — the VM catch path's `allocExceptionLoc` shape)
+  into a GC-owned exception Value stamped with the error `phase`
+  (a new byte on `ExInfo`), and `stars.setE`s it. Covers the reader-
+  error branch too. Alloc failure leaves `*e` unset (honest
+  no-error degradation). `(ex-message *e)` after `hoge` now works in
+  BOTH REPLs (e2e-pinned).
+- **`throw` stamps the live call stack** onto a trace-less exception
+  (`ex_info.stampTraceIfAbsent`, both backends symmetric) so a user
+  `(throw (ex-info …))` carries frames exactly like a catalog raise.
+- The op walks `*e`'s `ex-cause` chain: one response dict per cause —
+  `class` (the stored host-class name, e.g. "RuntimeException" for a
+  name error — exactly what the JVM shows for unresolved symbols),
+  `message`, `phase` (mapped: `parse`→`read-source`,
+  `analysis`→`compile-syntax-check`, `macroexpand`→`macroexpansion`,
+  `eval`→`execution` — drives CIDER's buffer-vs-overlay routing),
+  `data` (printed at op time), `stacktrace` frames innermost-first.
+- Flags, cljw's take: every frame `clj` (there is no Java); `repl`
+  for `<…>`-labelled sources; `project` + `file-url` for on-disk
+  paths (navigable); `dup` per orchard's rule (same fn, or same
+  REAL file+line). `java` / `tooling` never fire — the filter
+  buttons degrade gracefully in CIDER.
+- The bare `analyze-last-stacktrace` alias is advertised too.
+- `inspect-last-exception` (the inspector) stays out of scope — and
+  the `*e`-Value model (vs string snapshots) deliberately keeps that
+  door open.
+- **Fixed en route**: the re-architecture's `evalImpl` fed the
+  SCRATCH-owned request `code` into evals whose products (defn'd
+  fns, forms) borrow source slices and outlive the message — a
+  use-after-free surfacing as garbage strings under scratch-reuse
+  pressure. The source is now duped onto the persistent arena
+  (mirroring the CLI REPL's per-line dupe).
+
+**Amendment alternatives considered** (fresh-context DA fork,
+2026-07-14): *Alt 1 smallest-diff* — sink-side gpa string-snapshot
+capture into `session.last_error`; rejected: fossilizes the `*e`
+F-011 divergence behind a second truth channel, forecloses the
+inspector, adds a free-on-close lifecycle and a two-channels-drift
+class. *Alt 2 (adopted)* — as above; the DA's factual corrections
+(peekLastError already existed; the reader branch bypassed
+handleEvalError; frame `name` is display-inert but `file-url`/`var`
+drive navigation; `phase` is routing, not decoration; the no-error
+shape is CIDER-safe byte-parity) are folded in. *Alt 3 wildcard* —
+implement the analysis in bootstrap `.clj` over `*e` + small
+primitives; right eventual direction (the ADR's existing lookup-op
+forward note), premature while the Value→bencode walker doesn't
+exist.
+
 ## Revision history
 
 - 2026-07-13: Proposed.
+- 2026-07-14: Amendment 1 — `cider/analyze-last-stacktrace` op +
+  per-session structured last-error capture (the `*cider-error*`
+  buffer); DA-fork alternatives reflected below.

src/app/eval_session.zig

@@ -29,6 +29,9 @@ const print = @import("../runtime/print.zig");
 const text_io = @import("../runtime/io/text_io.zig");
 const dispatch = @import("../runtime/dispatch.zig");
 const error_render = @import("error_render.zig");
+const error_mod = @import("../runtime/error/info.zig");
+const host_class = @import("../runtime/error/host_class.zig");
+const ex_info_mod = @import("../runtime/collection/ex_info.zig");
 
 /// REPL history state (`*1` `*2` `*3` `*e`) with the GC pin
 /// discipline built in.
@@ -147,7 +150,7 @@ pub fn evalSource(
     while (true) {
         const form_opt = reader.read() catch |err| {
             try flushCaptured(out_var, err_var, sink);
-            try renderAndEmit(scratch, opts, err, sink);
+            try handleEvalError(rt, opts, ve, err, scratch, sink);
             ok = false;
             break;
         };
@@ -160,14 +163,14 @@ pub fn evalSource(
 
         const node = analyzeForm(arena, rt, env, null, form, macro_table) catch |err| {
             try flushCaptured(out_var, err_var, sink);
-            try handleEvalError(opts, ve, err, scratch, sink);
+            try handleEvalError(rt, opts, ve, err, scratch, sink);
             ok = false;
             break;
         };
         var locals: [driver.MAX_LOCALS]Value = [_]Value{.nil_val} ** driver.MAX_LOCALS;
         const result = driver.evalForm(rt, env, &locals, arena, node) catch |err| {
             try flushCaptured(out_var, err_var, sink);
-            try handleEvalError(opts, ve, err, scratch, sink);
+            try handleEvalError(rt, opts, ve, err, scratch, sink);
             ok = false;
             break;
         };
@@ -225,6 +228,7 @@ fn rearmCapture(rt: *Runtime, out_var: ?*env_mod.Var, err_var: ?*env_mod.Var) !v
 }
 
 fn handleEvalError(
+    rt: *Runtime,
     opts: Options,
     ve: ?*env_mod.Var,
     err: anyerror,
@@ -239,14 +243,32 @@ fn handleEvalError(
             try stars.setE(t);
             if (ve) |v| _ = env_mod.setBinding(v, t);
         }
+    } else if (opts.stars != null) {
+        // JVM parity (ADR-0170 am1): clojure.main's REPL sets `*e` for
+        // EVERY caught error, compiler errors included — materialize
+        // the catalog Info into a GC-owned exception Value (the same
+        // shape the VM's catch path synthesizes), stamped with the
+        // phase so the nREPL stacktrace op can route compile-phase
+        // errors JVM-style. An uncatchable Kind still materializes for
+        // display ("Error"); an alloc failure leaves `*e` unset — the
+        // stacktrace op then reports no-error, an honest degradation.
+        if (error_mod.peekLastError()) |info| {
+            const class = host_class.kindToHostClass(info.kind) orelse "Error";
+            if (ex_info_mod.allocExceptionLoc(rt, info.message, class, info.location, info.trace)) |synth| {
+                ex_info_mod.setPhase(synth, info.phase);
+                if (opts.stars) |stars| {
+                    try stars.setE(synth);
+                    if (ve) |v| _ = env_mod.setBinding(v, synth);
+                }
+            } else |_| {
+                // OOM-class alloc failure: *e stays unset — the
+                // stacktrace op reports no-error, an honest degradation.
+            }
+        }
     }
     try renderAndEmitThrown(scratch, opts, err, thrown, sink);
 }
 
-fn renderAndEmit(scratch: std.mem.Allocator, opts: Options, err: anyerror, sink: anytype) !void {
-    try renderAndEmitThrown(scratch, opts, err, null, sink);
-}
-
 fn renderAndEmitThrown(scratch: std.mem.Allocator, opts: Options, err: anyerror, thrown: ?Value, sink: anytype) !void {
     var aw: Writer.Allocating = .init(scratch);
     error_render.renderError(&aw.writer, .{ .file = opts.source_label, .text = opts.source }, err) catch {};

src/app/nrepl/ops.zig

@@ -26,6 +26,7 @@ const Runtime = @import("../../runtime/runtime.zig").Runtime;
 const Env = @import("../../runtime/env.zig").Env;
 const env_mod = @import("../../runtime/env.zig");
 const print = @import("../../runtime/print.zig");
+const ex_info_mod = @import("../../runtime/collection/ex_info.zig");
 
 /// Everything a handler needs for one request.
 pub const Ctx = struct {
@@ -75,6 +76,8 @@ const op_table = [_]OpEntry{
     .{ .name = "lookup", .handler = opLookup },
     .{ .name = "info", .handler = opLookup },
     .{ .name = "eldoc", .handler = opLookup },
+    .{ .name = "cider/analyze-last-stacktrace", .handler = opAnalyzeLastStacktrace },
+    .{ .name = "analyze-last-stacktrace", .handler = opAnalyzeLastStacktrace },
 };
 
 const op_map = blk: {
@@ -197,10 +200,18 @@ const BencodeSink = struct {
 const Value = @import("../../runtime/value/value.zig").Value;
 
 fn evalImpl(ctx: *Ctx, code_key: []const u8, emit_each: bool) anyerror!void {
-    const code = ctx.str(code_key) orelse {
+    const code_scratch = ctx.str(code_key) orelse {
         try ctx.respondStatus(&.{ "error", "no-code", "done" });
         return;
     };
+    // The decoded request lives on the per-message SCRATCH arena, but
+    // eval products (defn'd Functions, forms, analysis nodes) borrow
+    // slices of the source text and outlive the message — dupe the
+    // source onto the persistent arena (exactly like the CLI REPL's
+    // per-line dupe). Without this, the next message's scratch reset
+    // leaves every borrowed slice dangling (caught as garbage frame
+    // strings in stamped traces under GC/scratch-reuse pressure).
+    const code = try ctx.persist.dupe(u8, code_scratch);
     const sess = try ctx.registry.getOrDefault(ctx.str("session"));
 
     // ns honoring: an explicit request `ns` must exist (spec:
@@ -359,6 +370,124 @@ fn opLookup(ctx: *Ctx) anyerror!void {
     }
 }
 
+// --- cider/analyze-last-stacktrace (ADR-0170 am1: the *cider-error* buffer) ---
+
+/// Analyze the session's `*e` on demand (the cider-nrepl model: the op
+/// reads the session's last exception, it does not keep a parallel
+/// error channel). One response dict per cause in the `ex-cause`
+/// chain, then `done`; no `*e` → `no-error` + `done`.
+fn opAnalyzeLastStacktrace(ctx: *Ctx) anyerror!void {
+    const sess = try ctx.registry.getOrDefault(ctx.str("session"));
+    const e = sess.stars.values[eval_session.StarState.idx_e];
+    if (e.isNil()) {
+        try ctx.respondStatus(&.{"no-error"});
+        try ctx.respondStatus(&.{"done"});
+        return;
+    }
+    var cur = e;
+    while (!cur.isNil()) {
+        try emitCause(ctx, cur);
+        cur = if (cur.tag() == .ex_info) ex_info_mod.cause(cur) else Value.nil_val;
+    }
+    try ctx.respondStatus(&.{"done"});
+}
+
+/// clojure.error phase vocabulary for a stamped cljw phase (drives
+/// CIDER's buffer-vs-overlay routing: compile phases render as an
+/// inline overlay, JVM style).
+fn phaseName(p: @import("../../runtime/error/info.zig").Phase) []const u8 {
+    return switch (p) {
+        .parse => "read-source",
+        .analysis => "compile-syntax-check",
+        .macroexpand => "macroexpansion",
+        .eval => "execution",
+    };
+}
+
+fn emitCause(ctx: *Ctx, v: Value) !void {
+    var entries: std.ArrayList(bencode.Decoded.Entry) = .empty;
+    if (v.tag() == .ex_info) {
+        const class = ex_info_mod.className(v) orelse "ExceptionInfo";
+        try entries.append(ctx.scratch, .{ .key = "class", .value = .{ .str = class } });
+        try entries.append(ctx.scratch, .{ .key = "message", .value = .{ .str = ex_info_mod.message(v) } });
+        if (ex_info_mod.phaseOf(v)) |p| {
+            try entries.append(ctx.scratch, .{ .key = "phase", .value = .{ .str = phaseName(p) } });
+        }
+        const d = ex_info_mod.data(v);
+        if (!d.isNil()) {
+            var aw: Writer.Allocating = .init(ctx.scratch);
+            if (print.printResult(ctx.rt, ctx.env, &aw.writer, d)) {
+                try entries.append(ctx.scratch, .{ .key = "data", .value = .{ .str = aw.written() } });
+            } else |_| {
+                // Unprintable ex-data: omit the key; the cause still renders.
+            }
+        }
+        try entries.append(ctx.scratch, .{ .key = "stacktrace", .value = try emitFrames(ctx, ex_info_mod.originTrace(v)) });
+    } else {
+        // A raw thrown Value (`(throw 42)`): render it as the message.
+        var aw: Writer.Allocating = .init(ctx.scratch);
+        print.printResult(ctx.rt, ctx.env, &aw.writer, v) catch {};
+        try entries.append(ctx.scratch, .{ .key = "class", .value = .{ .str = "Throwable" } });
+        try entries.append(ctx.scratch, .{ .key = "message", .value = .{ .str = aw.written() } });
+        try entries.append(ctx.scratch, .{ .key = "stacktrace", .value = .{ .list = &.{} } });
+    }
+    try ctx.respond(entries.items);
+}
+
+/// Emit the trace as CIDER frame dicts, innermost-FIRST (JVM
+/// getStackTrace order; cljw's trace is push-order = outermost-first,
+/// so iterate reversed). Flags, cljw's take: every frame `clj` (there
+/// is no Java); `repl` for REPL-ish sources (`<repl:N>` / `<nrepl>` /
+/// `<stdin>` / `<-e>`); `project` for on-disk paths; `dup` when a
+/// frame repeats its list predecessor's fn or file+line (orchard's
+/// rule). `file-url` (absolute path) makes the frame navigable.
+fn emitFrames(ctx: *Ctx, trace: ?[]const @import("../../runtime/error/info.zig").StackFrame) !bencode.Decoded {
+    const t = trace orelse return .{ .list = &.{} };
+    var items: std.ArrayList(bencode.Decoded) = .empty;
+    var prev_fn: ?[]const u8 = null;
+    var prev_file: ?[]const u8 = null;
+    var prev_line: u32 = 0;
+    var i: usize = t.len;
+    while (i > 0) {
+        i -= 1;
+        const fr = t[i];
+        const fn_name = fr.fn_name orelse "unknown";
+        const file = fr.file orelse "unknown";
+        const name = if (fr.ns) |ns|
+            try std.fmt.allocPrint(ctx.scratch, "{s}/{s}", .{ ns, fn_name })
+        else
+            fn_name;
+
+        var flags: std.ArrayList(bencode.Decoded) = .empty;
+        try flags.append(ctx.scratch, .{ .str = "clj" });
+        const replish = file.len > 0 and file[0] == '<';
+        const on_disk = file.len > 0 and file[0] == '/';
+        if (replish) try flags.append(ctx.scratch, .{ .str = "repl" });
+        if (on_disk) try flags.append(ctx.scratch, .{ .str = "project" });
+        // file+line dup only for REAL locations — "unknown"-file frames
+        // at the same line are distinct calls, not duplicates.
+        const dup = (prev_fn != null and std.mem.eql(u8, prev_fn.?, fn_name)) or
+            (on_disk and prev_file != null and std.mem.eql(u8, prev_file.?, file) and prev_line == fr.line and fr.line != 0);
+        if (dup) try flags.append(ctx.scratch, .{ .str = "dup" });
+        prev_fn = fn_name;
+        prev_file = file;
+        prev_line = fr.line;
+
+        var fe: std.ArrayList(bencode.Decoded.Entry) = .empty;
+        try fe.append(ctx.scratch, .{ .key = "name", .value = .{ .str = name } });
+        try fe.append(ctx.scratch, .{ .key = "fn", .value = .{ .str = fn_name } });
+        if (fr.ns) |ns| try fe.append(ctx.scratch, .{ .key = "ns", .value = .{ .str = ns } });
+        try fe.append(ctx.scratch, .{ .key = "var", .value = .{ .str = name } });
+        try fe.append(ctx.scratch, .{ .key = "file", .value = .{ .str = file } });
+        if (on_disk) try fe.append(ctx.scratch, .{ .key = "file-url", .value = .{ .str = file } });
+        try fe.append(ctx.scratch, .{ .key = "line", .value = .{ .int = fr.line } });
+        try fe.append(ctx.scratch, .{ .key = "flags", .value = .{ .list = flags.items } });
+        try fe.append(ctx.scratch, .{ .key = "type", .value = .{ .str = "clj" } });
+        try items.append(ctx.scratch, .{ .dict = fe.items });
+    }
+    return .{ .list = items.items };
+}
+
 fn lookupMiss(ctx: *Ctx, is_eldoc: bool) !void {
     if (is_eldoc) {
         try ctx.respondStatus(&.{ "done", "no-eldoc" });

src/eval/backend/tree_walk.zig

@@ -1061,6 +1061,9 @@ fn evalRecur(rt: *Runtime, env: *Env, locals: []Value, n: node_mod.RecurNode) an
 fn evalThrow(rt: *Runtime, env: *Env, locals: []Value, n: node_mod.ThrowNode) anyerror!Value {
     const v = try eval(rt, env, locals, n.expr);
     dispatch.last_thrown_exception = v;
+    // Stamp the live call stack onto a trace-less exception so the
+    // throw carries frames like a catalog raise (ADR-0170 am1).
+    ex_info_collection.stampTraceIfAbsent(rt, v, error_mod.currentStack());
     // Snapshot *error-context* now — the `binding` frame is still live
     // here, but is popped by `defer popFrame` as this error unwinds, so
     // the renderer cannot deref it later (ADR-0055 am2 / D-144).

src/eval/backend/vm.zig

@@ -979,6 +979,10 @@ inline fn stepOnce(
             if (sp == 0) return raiseInternal("vm: op_throw on empty stack");
             sp -= 1;
             dispatch.last_thrown_exception = stack[sp];
+            // Stamp the live call stack onto a trace-less exception so
+            // the throw carries frames like a catalog raise (ADR-0170
+            // am1) — symmetric with TreeWalk's evalThrow.
+            ex_info_mod.stampTraceIfAbsent(rt, stack[sp], error_mod.currentStack());
             // Snapshot *error-context* while the binding frame is
             // live (ADR-0055 am2 / D-144) — symmetric with TreeWalk's
             // evalThrow so the two backends agree at the throw edge.