@@ -47,6 +47,14 @@
   check-tools {:doc  "Verify the local toolchain against tools.json"
                :task (run "bin/check-tools")}
 
+  ensure-npm  {:doc  "Materialize node_modules (the dev-loop assembler, 0026/0029) when absent"
+               :task (when (and (fs/exists? "package.json")
+                                (not (fs/exists? "node_modules/binaryen")))
+                       (run "npm" "ci" "--no-audit" "--no-fund"))}
+
+  repl        {:doc  "The ClojureWit nREPL server (0029): evals compile to Wasm, run in the engine child"
+               :task (run "clojure" "-M:repl")}
+
   test        {:doc  "Unit tests (JVM)"
                :task (if (and (fs/exists? "test") (seq (fs/glob "test" "**.clj")))
                        (run "clojure" "-X:test")
@@ -195,6 +203,6 @@
   ;; push-time hook stops being a good trade — and this is how that becomes
   ;; visible, without a rule anyone has to remember to read.
   check       {:doc     "The gate. Everything a change must pass; CI runs exactly this."
-               :depends [check-tools lint fmt-check reflection test]
+               :depends [check-tools ensure-npm lint fmt-check reflection test]
                :task    (println (format "\n✓ gate green (%.1fs)"
                                          (/ (- (System/currentTimeMillis) start-ms) 1000.0)))}}}
@@ -12,7 +12,11 @@
    "wasm-tools" ["wasm-tools" "--version"]
    "wasmtime"   ["wasmtime" "--version"]
    "binaryen"   ["wasm-opt" "--version"]
-   "node"       ["node" "--version"]})
+   "node"       ["node" "--version"]
+   ;; npm-managed, resolved from the repo root's node_modules — the
+   ;; require of a package.json is CJS-safe where importing the ESM
+   ;; entry from -e is not.
+   "binaryen-js" ["node" "-p" "require('binaryen/package.json').version"]})
 
 (defn version-of [cmd]
   (let [{:keys [out err exit]} (apply sh cmd)]
 
@@ -2,7 +2,12 @@
  :deps {org.clojure/clojure {:mvn/version "1.12.4"}
         ;; The S3 front end: tools.analyzer core plus our own host layer
         ;; (doc/design/0022 E decided it, 0023 grows it into src/).
-        org.clojure/tools.analyzer {:mvn/version "1.2.2"}}
+        org.clojure/tools.analyzer {:mvn/version "1.2.2"}
+        ;; The S2 entry point: the compiler is itself the nREPL server
+        ;; (doc/design/0029) — the same trade shadow-cljs makes.
+        nrepl/nrepl {:mvn/version "1.4.0"}
+        ;; The engine-child protocol is JSON lines (0029).
+        org.clojure/data.json {:mvn/version "2.5.1"}}
 
  :aliases
  {;; --- development -------------------------------------------------------
@@ -23,6 +28,10 @@
   ;; session as the Wasm lanes for the comparison to mean anything.
   :bench {:extra-paths ["bench"]}
 
+  ;; `clj -M:repl` — the ClojureWit REPL server (doc/design/0029):
+  ;; evals compile to Wasm and run in the engine child, not on the JVM.
+  :repl {:main-opts ["-m" "cljwit.repl"]}
+
   ;; `clj -M:nrepl` — editor connection (CIDER / Calva / any nREPL client)
   :nrepl {:extra-deps {nrepl/nrepl {:mvn/version "1.4.0"}
                        cider/cider-nrepl {:mvn/version "0.57.0"}}
 
@@ -0,0 +1,81 @@
+// The REPL's engine child (doc/design/0029): one long-lived node
+// process holding one session — runtime instance, var ledger, and the
+// engine-side assembler (0026: binaryen.js, explicit features, never
+// Features.All). Speaks one JSON object per line on stdio:
+//
+//   in:  {"op":"init","runtime":"<wat>"}
+//        {"op":"eval","wat":"<wat>","statement":true|false}
+//   out: {"tag":"ok"}                          (init)
+//        {"tag":"result","value":"<printed>"}  (expression form)
+//        {"tag":"done"}                        (statement form, e.g. def)
+//        {"tag":"exn","class":<n>}             (uncaught Clojure throw)
+//        {"tag":"trap","message":"<engine>"}   (native trap)
+//        {"tag":"error","message":"..."}       (broken pipe-side invariant)
+//
+// corpus/session.mjs is this loop unrolled for one batch; keep their
+// classification identical.
+
+import { createInterface } from "node:readline";
+import binaryen from "binaryen";
+
+const F = binaryen.Features;
+const FEATS = F.GC | F.ReferenceTypes | F.TailCall | F.ExceptionHandling |
+              F.BulkMemory | F.Multivalue | F.SignExt | F.NontrappingFPToInt |
+              F.MutableGlobals;
+
+const assemble = (wat) => {
+  const mod = binaryen.parseText(wat);
+  mod.setFeatures(FEATS);
+  const bin = mod.emitBinary();
+  mod.dispose();
+  return bin;
+};
+
+let rt = null;
+const vars = {};
+
+const reply = (obj) => process.stdout.write(JSON.stringify(obj) + "\n");
+
+const handle = (msg) => {
+  if (msg.op === "init") {
+    rt = new WebAssembly.Instance(new WebAssembly.Module(assemble(msg.runtime)), {});
+    return { tag: "ok" };
+  }
+  if (msg.op !== "eval") return { tag: "error", message: `unknown op ${msg.op}` };
+  if (!rt) return { tag: "error", message: "eval before init" };
+  const inst = new WebAssembly.Instance(
+    new WebAssembly.Module(assemble(msg.wat)),
+    { rt: rt.exports, vars },
+  );
+  for (const [name, val] of Object.entries(inst.exports)) {
+    if (name === "entry") continue;
+    // 0028 §2: the first definer owns the canonical global forever; a
+    // duplicate export is a compiler bug made loud.
+    if (name in vars) return { tag: "error", message: `duplicate var export: ${name}` };
+    vars[name] = val;
+  }
+  try {
+    const v = inst.exports.entry();
+    return msg.statement ? { tag: "done" } : { tag: "result", value: String(v) };
+  } catch (e) {
+    const tag = rt.exports["clj-exn"];
+    if (e instanceof WebAssembly.Exception && e.is(tag))
+      return { tag: "exn", class: Number(rt.exports.exn_class(e.getArg(tag, 0))) };
+    if (e instanceof WebAssembly.RuntimeError || e instanceof RangeError)
+      return { tag: "trap", message: e.message };
+    throw e;
+  }
+};
+
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on("line", (line) => {
+  if (!line.trim()) return;
+  let out;
+  try {
+    out = handle(JSON.parse(line));
+  } catch (e) {
+    out = { tag: "error", message: String(e && e.message ? e.message : e) };
+  }
+  reply(out);
+});
+rl.on("close", () => process.exit(0));
@@ -122,9 +122,11 @@ TeaVM's WasmGC binary writer. This note examines them and decides.
   part of "done" for emitted-grammar changes.
 - **The version skew biting**: npm binaryen.js and the flake's binaryen
   are different builds of one project (131 vs 129 today). `tools.json`
-  gains the dev assembler's version when the nREPL unit lands; until
-  then the committed differential is also the skew watcher — the same
-  interim rule, named once *(review)*.
+  gains the dev assembler's version when the nREPL unit lands *(done —
+  `0029`'s commit added `binaryen-js` to `tools.json` with a node-side
+  probe, and `bb check` materializes `node_modules` via a guarded
+  `npm ci`)*; the committed differential remains the behavioural skew
+  watcher.
 - **The margin is a function of the runtime preamble** *(review)*:
   every per-form module re-parses the whole preamble, and assembly cost
   is linear in it — a 100 KB core-library preamble puts the per-form
 
@@ -0,0 +1,127 @@
+# 0029 — The nREPL entry point: the compiler is the server, the engine is a child
+
+**Status:** proposed · 2026-07-30 · adversarially reviewed the same day,
+before implementation. The review inspected the actual nrepl 1.4.0
+stack and changed five things, marked *(review)*: the handler is the
+default middleware stack with eval intercepted, not four hand-rolled
+ops; the session analysis API is a separate pair the corpus never
+imports; the child protocol's two framing pins; the `def` printing
+decision (a stable `user` presentation); and §6's hole is closed in
+this unit's own commit, because `0026`'s recorded trigger for closing
+it *is* this unit.
+
+## The question
+
+S2's remaining shape (`doc/roadmap.md`): the compiler runs on the JVM
+and *is itself* the nREPL server, so CIDER/Calva connect with no extra
+machinery. Every prerequisite is now decided — the assembler sits next
+to the engine (`0026`), forms link over one runtime (`0028`), throws
+classify (`0027`) — but nothing serves the protocol. What does the v0
+server do on `eval`, who holds which half of the session, and what is
+honestly out of scope?
+
+## The decision
+
+1. **One JVM process, `cljwit.repl`, serving nREPL as the default
+   middleware stack with `eval` intercepted** *(review — the first
+   draft said "a minimal clone/describe/eval/close handler", which
+   hand-rolls exactly the parts that break: `clone` is session
+   middleware behavior, not an op you implement, and a handler that
+   does not answer unknown ops with `unknown-op`+`done` hangs CIDER on
+   its first `lookup`)*. A `wrap-cljwit-eval` middleware declares it
+   handles `"eval"` ahead of `interruptible-eval` — piggieback's exact
+   shape — so session bookkeeping, `describe`, and unknown-op
+   semantics come from `nrepl/nrepl` protocol-correct and for free.
+   `clj -M:repl` starts it; the `-X` coordinate `0021` called
+   provisional is superseded by this. Verified with the nrepl client;
+   an editor connection is a manual check until someone performs it
+   *(review)*.
+2. **One long-lived node child, `dev/repl_engine.mjs`** — started by
+   the server, speaking one JSON line per message on stdio, strict
+   request→response alternation. Two framing pins *(review)*: **the
+   child's stdout carries protocol lines exclusively** — diagnostics go
+   to stderr, which the server inherits — and **the child exits on
+   stdin EOF**, which is also the whole orphaning story when the JVM
+   dies. It loads binaryen.js once (~170 ms, `0026`'s measured session
+   cost), instantiates the session runtime once, holds the var ledger
+   (`0028`'s instantiator half), and per form: assemble (explicit
+   features, never `Features.All`), instantiate, merge exports —
+   rejecting duplicate var exports loudly — call `entry`, answer
+   `{"tag":"result"|"exn"|"trap"|"error", …}` in the corpus vocabulary.
+   Crash recovery beyond EOF-exit is a named v0 hole.
+3. **The compiler half of the session lives in a separate session API**
+   *(review)*: `open-session`/`analyze-in-session!`/`close-session!`
+   keep one analysis namespace alive across eval messages, so form 2's
+   analysis resolves form 1's vars. **`analyze-forms` keeps its
+   create-and-discard semantics unchanged, and the corpus lanes use
+   only it** — the oracle's isolation rule (`0022` B.2) depends on the
+   discard, and routing corpus entries through the session API would
+   be the analysis-side version of the leak `0028`'s ledger makes
+   loud. The contract is in both docstrings.
+4. **What the REPL prints, v0**: an expression's value is a scalar and
+   prints as its number (`0022` B.3's boundary, surfaced honestly); a
+   `def` prints **`#'user/name`** — a *presentation* *(review)*: the
+   session's analysis namespace is internal and gensym'd, the user
+   never sees it, and the printed var is analysis state, not a JVM var
+   anyone can deref. Namespaces are global across nREPL sessions,
+   Clojure's own answer and the cheap parity choice. A classified
+   `exn`/`trap` prints as an error with the trap-table row's class
+   name. Anything the slice cannot express is the loud out-of-slice
+   compile error it already is.
+5. **Scope, named**: no watcher, no browser transport, no interrupt, no
+   pretty-printing, no wasmtime session lane (deferred in `0028` §5).
+   The engine child is node-only v0; the browser session reuses the
+   same protocol the day a transport exists for it.
+6. **The dev assembler enters the toolchain in this unit's commit**
+   *(review — `0026` recorded exactly this trigger: "`tools.json`
+   gains the dev assembler's version when the nREPL unit lands", and
+   this is that unit; deferring again would be two notes pointing at
+   each other forever)*. `tools.json` gains `binaryen-js` with a
+   node-side probe, and `bb check` materializes `node_modules` with a
+   guarded `npm ci` when it is absent — a network step only on first
+   run or lock change, the same class of need as `bb ref`. The
+   integration test still skips with a printed line if binaryen is
+   somehow absent (the FFM tests' trade), but on CI it runs: server
+   in-process, real nREPL client, eval through the whole pipe.
+
+## Why
+
+- The server/child split is `0026`'s decision made operational:
+  assembly *must* live engine-side for the browser anyway, so the node
+  child doing its own assembly keeps one code path for both targets.
+- The JSON-line protocol is the session runner (`corpus/session.mjs`)
+  turned resident — same instantiation, same ledger, same
+  classification, one loop around it.
+- nREPL rather than a bespoke socket because the roadmap's whole point
+  for S2 is that editors connect with zero new machinery.
+
+## Alternatives rejected
+
+- **Evaluating on the JVM and cross-compiling later** (a normal Clojure
+  nREPL now, wasm someday). Rejected because it is not this project: a
+  REPL whose semantics are the JVM's is `0002`'s incident waiting to
+  recur at the DX layer — every difference would be invisible until
+  batch compilation.
+- **piggieback middleware inside a host JVM REPL.** Right shape for
+  nesting, heavier dependency surface, and nothing nests yet; the
+  minimal handler serves the same editors today and does not preclude
+  it.
+- **JVM-side assembly (wasm-tools spawn) for the v0 child.** Works
+  everywhere the gate runs, but contradicts `0026`'s decided placement
+  and forks the code path the browser target needs; the 23 ms spawn is
+  also above the budget `0026` bought for 1.3 ms.
+- **A bespoke wire protocol to the editor.** nREPL exists; the child's
+  JSON lines are internal plumbing, not an editor surface.
+
+## What would falsify this
+
+- **An editor round-trip measurably dominated by something other than
+  the measured pieces** (analysis, 1.3 ms assembly, instantiation) —
+  the v0 makes no latency claim, but the first complaint gets measured
+  against `0026`'s numbers before anything is redesigned.
+- **Session growth**: hundreds of forms → hundreds of live instances
+  and an ever-longer ledger (`0028`'s named soak question). The nREPL
+  server is where a soak test becomes runnable at all.
+- **The CI hole biting** — a protocol regression landing while CI
+  cannot run the pipe. If that happens once, the assembler's
+  `tools.json` entry is due immediately, not eventually.
@@ -80,9 +80,23 @@ _Short by design, and printed at every session start — so findings live in
    cross-form fn values, so linked K is a session constant, 20 —
    Clojure's own ceiling (`0028` §2a, `0024` amended). The wasmtime
    linked lane is deferred on cost, not capability (`--preload` works;
-   recorded). Next unit: **S2's nREPL entry point** — the shadow-cljs
-   shape from `doc/roadmap.md`, every prerequisite now decided and
-   the session runner already the shape the server drives.
+   recorded). **S2's nREPL entry point is landed** (`0029`): `bb repl`
+   starts a JVM server — the default nrepl stack with eval
+   intercepted, piggieback's shape — whose evals analyze in a
+   persistent session, emit linked form modules, and run in a
+   long-lived node engine child holding the runtime and the var
+   ledger. A real client round-trips the whole pipe in the gate:
+   `(def x 5)` then `(+ x 37)` → 42 across evals, `(defn fib …)` and
+   `(fib 20)` → 6765, fn redefinition takes effect, overflow and traps
+   classify as errors, out-of-slice stays loud. The dev assembler
+   entered `tools.json` and `bb check` materializes it (guarded
+   `npm ci`) — `0026`'s promise kept on its named trigger. An editor
+   connection (CIDER/Calva) remains a manual check. Next: **entering
+   S4 starts with its survey** (`/next`'s stage rule; `0007` sized the
+   stage — lift/lower over linear memory, `cabi_realloc`, resource
+   tables — and `/survey`'s Kotlin sample is the closest prior art);
+   S2's watcher waits for namespace loading, post-S3 compiler work
+   either way.
 
 Done since the last update: `0016` `own<T>` handles, `0017` host imports
 (A–F), `0018` host-defined resources, `0012`'s `ex-data` contract shrunk to
 
@@ -40,25 +40,57 @@
             form))))
     form))
 
+(defn- fresh-genv [ns-sym]
+  (atom {:namespaces
+         {ns-sym        {:mappings (ns-map 'clojure.core)
+                         :aliases {} :ns ns-sym}
+          'clojure.core {:mappings (ns-map 'clojure.core)
+                         :aliases {} :ns 'clojure.core}}}))
+
+(defmacro ^:private with-host [& body]
+  `(binding [ana/macroexpand-1 macroexpand-1
+             ana/create-var    (fn [sym# var-env#]
+                                 (doto (intern (:ns var-env#) sym#)
+                                   (reset-meta! (meta sym#))))
+             ana/parse         ana/-parse
+             ana/var?          var?]
+     ~@body))
+
+(defn open-session
+  "A persistent analysis session (`0029`): one kept namespace — internal
+   and gensym'd, presented to the user as `user` — so a later form's
+   analysis resolves an earlier form's vars. The corpus lanes must NOT
+   use this: the oracle's isolation rule (`0022` B.2) depends on
+   `analyze-forms`' per-call discard, which is unchanged."
+  []
+  (let [ns-sym (gensym "cljwit.session")]
+    (create-ns ns-sym)
+    {:ns ns-sym :genv (fresh-genv ns-sym)}))
+
+(defn analyze-in-session!
+  "Analyzes one form in the session's kept environment; returns its AST."
+  [{:keys [ns genv]} form]
+  (with-host
+    (with-env genv
+      (run-passes (ana/analyze form {:context :ctx/expr :locals {} :ns ns})))))
+
+(defn close-session!
+  "Discards the session's analysis namespace."
+  [{:keys [ns]}]
+  (remove-ns ns))
+
 (defn analyze-forms
   "Analyzes top-level `forms` in order as one program — later forms see
-   earlier `def`s. Returns a vector of ASTs."
+   earlier `def`s. Returns a vector of ASTs. The namespace is created
+   and discarded per call — the corpus oracle's isolation rule
+   (`0022` B.2); sessions use `open-session` instead."
   [forms]
   (let [ns-sym (gensym "cljwit.analysis")]
     (create-ns ns-sym)
     (try
       (let [env  {:context :ctx/expr :locals {} :ns ns-sym}
-            genv (atom {:namespaces
-                        {ns-sym       {:mappings (ns-map 'clojure.core)
-                                       :aliases {} :ns ns-sym}
-                         'clojure.core {:mappings (ns-map 'clojure.core)
-                                        :aliases {} :ns 'clojure.core}}})]
-        (binding [ana/macroexpand-1 macroexpand-1
-                  ana/create-var    (fn [sym var-env]
-                                      (doto (intern (:ns var-env) sym)
-                                        (reset-meta! (meta sym))))
-                  ana/parse         ana/-parse
-                  ana/var?          var?]
+            genv (fresh-genv ns-sym)]
+        (with-host
           (with-env genv
             (mapv #(run-passes (ana/analyze % env)) forms))))
       (finally (remove-ns ns-sym)))))