@lkyhfx/dsh-bb-repl 0.1.1 → 0.2.0

package/bb-src/domain/runtime.clj

@@ -70,11 +70,30 @@
        (sort-by :name)
        vec))
 
+(def ^:private session-generation
+  "The interpreter generation the host assigned to this process. It counts the
+  (re)starts of this Agent's session, so an Agent can tell a reused interpreter
+  from a rebuilt one without seeing any nREPL session id or port."
+  (let [raw (System/getenv "DSH_BB_SESSION_GENERATION")]
+    (if (str/blank? raw) 0 (or (parse-long raw) 0))))
+
+(defn session
+  "Model-safe identity of this interpreter: its generation and how much state it
+  can be assumed to hold. :defs is the number of agent vars currently bound."
+  []
+  (let [generation (long session-generation)]
+    ;; generation 0 means the host did not stamp this process: report that
+    ;; instead of claiming a live session we cannot identify.
+    {:generation generation
+     :state (if (pos? generation) :live :unmanaged)
+     :defs (count (vars))}))
+
 (defn status
-  "One map with the workspace, the mounted domains, each domain's own counters,
-  and how many definitions this session currently holds. Read-only."
+  "One map with the workspace, the session generation, the mounted domains, each
+  domain's own counters, and how many definitions this session holds. Read-only."
   []
   {:workspace (str workspace-root)
+   :session (session)
    :domains (into (sorted-map)
                   (map (fn [[id d]] [id (if-let [f (:status d)] (f) {:version (:version d)})])
                        @registry))

package/cordis.patch.yml

@@ -16,6 +16,8 @@
 #   timeoutMs      120000   per-eval timeout; a timeout resets the session
 #   startupMs      12000    interpreter start budget
 #   maxOutputChars 16000    output clipping budget
+#   alwaysShowSession false also report 'session: reused' (created/rebuilt are
+#                           always reported)
 #   sandbox        inherit  'inherit' goes through ctx.sandbox under the
 #                           session's ctx.sandboxPolicy and fails closed when no
 #                           backend exists; 'off' runs unconfined (tests only)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lkyhfx/dsh-bb-repl",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "DSH Cordis plugin: owner-scoped persistent Babashka nREPL tool (bb_eval)",
   "type": "module",
   "main": "./src/index.js",
@@ -16,7 +16,7 @@
   "dsh": {"bundle": {"patch": "./cordis.patch.yml"}},
   "dependencies": {
     "@deepseek-ai/schemastery": "*",
-    "@lkyhfx/dsh-bb-domain-code": "^0.1.1"
+    "@lkyhfx/dsh-bb-domain-code": "^0.3.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "*",

package/src/env.js

@@ -24,12 +24,15 @@ export function scrubbedChildEnv(parent = process.env) {
 }
 
 /** Explicit, non-secret facts this runtime hands to its Babashka child. */
-export function runtimeChildEnv({ workspace, scratch, port }) {
+export function runtimeChildEnv({ workspace, scratch, port, generation }) {
   return {
     ...scrubbedChildEnv(),
     DSH_BB_WORKSPACE_ROOT: workspace,
     DSH_BB_SCRATCH: scratch,
     DSH_BB_NREPL_PORT: String(port),
+    // Session generation this interpreter belongs to: runtime-side observability
+    // only. It is a counter, never an nREPL session id or a host secret.
+    DSH_BB_SESSION_GENERATION: String(generation ?? 1),
     PAGER: 'cat',
     GIT_PAGER: 'cat',
     NO_COLOR: '1',

package/src/index.js

@@ -11,64 +11,126 @@ export const name = 'bb-repl'
 // array `inject` can only express required services.
 export const inject = ['tools', 'workingDirectory']
 
-const GUIDE = `Execute Clojure programs in a persistent Babashka REPL isolated to this Agent.
-
-PERSISTENCE:
-- Functions defined with defn and values defined with def persist across calls
-  in the same Agent session.
-- let bindings are local to one expression; they do not survive a call.
-- Use defonce and atoms when mutable persistent state is actually required.
-- Inspect existing definitions before recreating them: (domain/vars).
-- Ordinary Clojure evaluation errors do NOT reset the REPL: a var defined
-  before the error is still there, so fix the form and keep going.
-- Timeouts, cancellations, transport failures and incompatible domain updates
-  DO reset the session. The call result says "session reset" or "session
-  rebuilt" when that happened, and then nothing is left but domain state.
-- Inspect (domain/status) or (domain/vars) whenever state is uncertain.
-
-COMPOSITION:
-- Compose domain primitives with let, do, ->, ->>, map, filter, reduce and the
-  rest of clojure.core.
-- Prefer one evaluation for a predictable multi-step task; return a compact
-  final value, not bulk file content.
-- Reuse functions and intermediate results across calls instead of repeating
-  searches and reads.
-- Use domain primitives for workspace file operations; they carry the guards.
-
-DISCOVERY:
-- (domain/status) -> workspace, mounted domains, their counters, def count.
-- (domain/help) or (domain/help :code) -> the domain API guides.
-- (domain/vars) -> agent-defined vars with arglists and docstrings.
-- (code/status) -> code-domain counters and workspace.
-- (meta #'code/search) -> signature and docstring of one primitive.
-
-STATE RESET:
-- (domain/reset! "why") deliberately discards this session's definitions and
-  starts a fresh interpreter on the next call. Prefer it over working around
-  known-bad state.
-
-SAFETY:
-- Clojure is dynamically typed; type errors surface at runtime.
-- Code runs with the configured runtime permissions. Never perform
-  unauthorized destructive operations.`
+const GUIDE = `Execute Clojure in a persistent Babashka REPL owned by this Agent.
+
+ALREADY LOADED: \`domain\` (domain.runtime) and \`code\` (domain.code) are mounted
+before your first call. Call them directly; a repeated (require '[domain.code :as
+code]) is a no-op that only wastes a call. Require other built-ins when you need
+them, once. Domain API details: the DOMAIN code section below, or
+(domain/help :code) / (meta #'code/search).
+
+PERSIST ACROSS CALLS -- small calls that build on each other:
+  call 1: (def hits (:matches (code/search "authenticate")))
+  call 2: (count hits)
+  call 3: (->> hits (map :path) distinct vec)
+\`hits\` still exists in call 3; re-searching would repeat I/O for the same data.
+def keeps a value worth reusing later (search results, file text, target paths).
+defn keeps a reusable operation. let is for intermediates inside one form -- most
+work belongs there; do not def scratch values you will never read again.
+defonce + an atom is only for state you genuinely mutate across calls.
+
+TWO MODES: EXPLORE while the target is unknown -- one small call, read it, decide.
+EXECUTE once target and operations are known -- the whole batch in ONE call:
+    (->> (:matches (code/search "authenticate"))
+         (map :path) distinct (mapv #(code/inspect %)))
+A known path needs no second global search; read it: (code/read "src/a.ts" {:start 40 :limit 60}).
+Results stay structured: code/search returns a MAP -- take :matches once, keep it
+in a var, map over it; (:truncated true) means :limit cut it, so widen :limit or
+narrow :glob/:root instead of assuming you saw everything.
+
+PERSISTENCE SEMANTICS: def/defn/defonce persist while the session is reused. A
+result reports \`session: created|rebuilt|reset|quarantined, generation: N\`
+whenever the interpreter changed or is not what you assume; a plain reused call
+stays quiet. Same generation = your definitions are still there
+((domain/session) confirms). An ordinary Clojure error does NOT reset anything:
+vars defined before it stay bound, so fix the form and continue. Timeout, abort,
+transport failure or a domain change DO replace the interpreter; the result says
+so with a resetReason plus \`definitions lost\`. \`quarantined\` means cleanup could
+not be confirmed: the old interpreter may still hold your state.
+
+STATE AND DISCOVERY: (domain/status) -> workspace, session, domains, counters,
+defs. (domain/vars) -> your vars with arglists/docstrings; check before
+redefining. (domain/session) -> generation and def count. (domain/reset! "why")
+-> deliberately drop this session when its state is bad.
+
+OUTPUT: return a compact final value -- counts, paths, small maps, one short
+window. Never print a whole file or large collection; page with :start/:limit.
+
+SAFETY: Clojure is dynamic, so type errors surface at runtime for the form that
+ran. Workspace writes go through code/replace! and code/patch!, which carry the
+guards; never edit workspace sources through raw fs/spit calls.`
 
 export const Config = z.object({
   bbExecutable: z.string().default('bb'),
   timeoutMs: z.number().default(120000),
   startupMs: z.number().default(12000),
   maxOutputChars: z.number().default(16000),
+  // A reused session is the normal case; created/rebuilt/reset are always shown.
+  alwaysShowSession: z.boolean().default(false),
   sandbox: z.union([z.const('inherit'), z.const('off')]).default('inherit'),
   description: z.string().default(GUIDE),
 })
 
 const clip = (s, n) => s.length <= n ? s : `${s.slice(0, n)}\n[Output truncated; narrow your query]`
 
+/**
+ * Render a printed value for the model.
+ *
+ * A single Clojure string containing newlines arrives as one escaped line
+ * (`"    1 {\n    2 .."`), which is hard to read and easy to mis-edit. Only the
+ * *display* of a whole-string value is relaxed here: multi-line text is shown
+ * unescaped, so what the Agent sees equals what it would print. Data structures,
+ * numbers, keywords and string fragments inside collections keep the exact
+ * printed form, because there the quoting carries structure that must not change.
+ */
+const renderValue = text => {
+  const trimmed = text.trim()
+  if (trimmed.length < 2 || trimmed[0] !== '"' || trimmed.at(-1) !== '"' || !/\\n/.test(trimmed)) {
+    return `value:\n${text}`
+  }
+  try {
+    const parsed = JSON.parse(trimmed)
+    if (typeof parsed !== 'string') return `value:\n${text}`
+    return `value: (one string, unescaped for display; the value itself is still a string)\n${parsed}`
+  } catch {
+    return `value:\n${text}` // not a plain JSON-compatible literal: keep it verbatim
+  }
+}
+
+/**
+ * One model-facing line about the interpreter that served the call.
+ *
+ * Only a generation counter and a state word are exposed: the nREPL session id,
+ * the loopback port and the scratch path stay host-side. A rebuilt session is
+ * always reported (that is when definitions disappear); a reused one is only
+ * reported when `always` is configured, to keep ordinary results small.
+ */
+const sessionLine = (session, always = false) => {
+  if (!session) return null
+  const parts = [`session: ${session.sessionState}`, `generation: ${session.generation}`]
+  // Which interpreter ran this code is separate from whether it still exists.
+  if (session.interpreter && session.interpreter !== session.sessionState) {
+    parts.push(`interpreter: ${session.interpreter}`)
+  }
+  if (session.resetReason) parts.push(`resetReason: ${session.resetReason}`)
+  if (session.definitionsLost) parts.push('definitions lost: this interpreter is new; re-define what you need')
+  if (session.sessionState === 'reset') parts.push('the next call starts a fresh interpreter')
+  if (session.sessionState === 'quarantined') {
+    parts.push('cleanup was not confirmed: the old interpreter is still alive and still holds your definitions')
+  }
+  const line = parts.join(', ')
+  // Quiet only for the ordinary case: same interpreter, still alive and reused.
+  if (!always && session.sessionState === 'reused') return null
+  return line
+}
+
 export function apply(ctx, config = {}) {
   const cfg = {
     bbExecutable: config.bbExecutable ?? 'bb',
     timeoutMs: config.timeoutMs ?? 120000,
     startupMs: config.startupMs ?? 12000,
     maxOutputChars: config.maxOutputChars ?? 16000,
+    alwaysShowSession: config.alwaysShowSession ?? false,
     sandbox: config.sandbox ?? 'inherit',
     description: config.description ?? GUIDE,
   }
@@ -160,19 +222,33 @@ export function apply(ctx, config = {}) {
           const result = await sessions.evaluate(exec.agent, workspace, args.code, exec.signal)
           const notes = result.notes ?? []
           const body = [
+            sessionLine(result.session, cfg.alwaysShowSession),
             notes.length ? `runtime:\n${notes.join('\n')}` : '',
             result.out ? `stdout:\n${result.out}` : '',
-            result.value ? `value:\n${result.value}` : '',
+            result.value ? renderValue(result.value) : '',
             result.err ? `stderr:\n${result.err}` : '',
             result.exception ? `exception: ${result.exception}` : '',
-            result.error ? `error: ${result.error.code}` : '',
+            // A failure keeps its machine-readable identity instead of turning
+            // into an empty success the Agent cannot branch on.
+            result.error
+              ? `error: ${result.error.code}${result.exception ? '' : ` (${result.error.message})`}`
+              : '',
             `status: ${result.ok ? 'ok' : 'error'}`,
           ].filter(Boolean).join('\n')
           return clip(body, cfg.maxOutputChars)
         } catch (error) {
           if (exec.signal.aborted) return '' // Host handles ABORTED.
+          // Never promise a reset that did not happen: when cleanup could not be
+          // confirmed the old interpreter still holds the Agent's state.
+          const line = sessionLine(error.session, true) ?? 'session: unknown'
           const notes = error.notes?.length ? ` (${error.notes.join('; ')})` : ''
-          throw new Error(`Babashka runtime: ${error.message}${notes}. The session was reset; re-run with a fresh interpreter.`)
+          const fate = error.session?.sessionState === 'reset'
+            ? 'The previous interpreter is gone; the next call starts a fresh session.'
+            // generation 0: no interpreter was ever established, so nothing was lost.
+            : error.session?.generation === 0
+              ? 'No interpreter was running for this call; nothing was discarded.'
+              : 'Session cleanup was NOT confirmed: the previous interpreter and its state are still alive.'
+          throw new Error(`Babashka runtime: ${error.message}${notes}\n${line}\n${fate}`)
         }
       },
       presentCall: args => ({ card: 'terminal', title: args.code.slice(0, 160) }),

package/src/sessions.js

@@ -94,6 +94,25 @@ async function terminateTree(proc, onLog) {
     throw new Error('Babashka process group could not be terminated; refusing to start a new session')
   }
 }
+/**
+ * Survival verdict inputs after a cleanup attempt.
+ *
+ * The live map, not the promise, is the source of truth: a reset that reported
+ * success but left the session registered (quarantined) must never be described
+ * as gone, and a confirmed reset of an already-absent session is still a reset.
+ */
+function finalState(live, owner, cleaned) {
+  return { resetRequested: true, cleanupConfirmed: Boolean(cleaned) && !live.has(owner) }
+}
+
+/** Machine-safe reset reason for an evaluation that failed: never free text. */
+function abortReason(error, signal) {
+  if (signal?.aborted) return 'abort'
+  if (/timed out/i.test(error?.message ?? '')) return 'timeout'
+  if (error?.code === 'NREPL_OUTPUT_LIMIT') return 'output-limit'
+  return 'transport-failure'
+}
+
 const q = value => JSON.stringify(value) // strings use Clojure-compatible JSON escaping
 
 /** Stable identity of a mounted domain implementation, used to detect hot swaps. */
@@ -142,6 +161,13 @@ export class DomainSessions {
     // Owners already wired to a lifecycle cleanup; a rebuilt session must not
     // register a second disposer for the same Agent.
     this.owned = new WeakSet()
+    // Per-owner interpreter generation, so the Agent can tell a live session
+    // from a freshly rebuilt one. Never holds anything the model must not see
+    // (no nREPL session id, no port, no scratch path).
+    // Weak, so a finished Agent cannot be kept alive by bookkeeping.
+    this.generations = new WeakMap()
+    // Why the next interpreter for this owner was (re)started; consumed by start().
+    this.resetReasons = new WeakMap()
     this.disposed = false
   }
 
@@ -165,6 +191,15 @@ export class DomainSessions {
   async start(owner, workspace, signal, policy) {
     if (this.disposed) throw new Error('Babashka runtime disposed')
     signal?.throwIfAborted()
+    // Generation identity is decided before the process exists, but only
+    // published once the interpreter actually started: a failed start must not
+    // claim a generation the Agent never got.
+    const previous = this.generations.get(owner)
+    const generation = (previous?.generation ?? 0) + 1
+    const sessionState = previous?.generation ? 'rebuilt' : 'created'
+    const resetReason = previous?.generation
+      ? (this.resetReasons.get(owner) ?? 'interpreter-exit')
+      : undefined
     const scratch = await mkdtemp(join(tmpdir(), 'dsh-bb-'))
     const port = await freeLocalPort()
     const manifests = this.modules()
@@ -179,7 +214,7 @@ export class DomainSessions {
     }
     const proc = spawn(launched.argv[0], launched.argv.slice(1), {
       cwd: scratch,
-      env: runtimeChildEnv({ workspace: resolve(workspace), scratch, port }),
+      env: runtimeChildEnv({ workspace: resolve(workspace), scratch, port, generation }),
       stdio: ['ignore', 'pipe', 'pipe'],
       windowsHide: true,
       // Own process group, so termination reaches the JVM and every child it
@@ -232,6 +267,11 @@ export class DomainSessions {
         throw exitError ?? new Error('Babashka exited during session initialization')
       }
       this.live.set(owner, session)
+      session.generation = generation
+      session.sessionState = sessionState
+      session.resetReason = resetReason
+      this.generations.set(owner, { generation, state: sessionState, resetReason })
+      this.resetReasons.delete(owner)
       if (!this.owned.has(owner)) {
         this.owned.add(owner)
         owner.ctx?.effect?.(() => () => { void this.reset(owner).catch(error => this.onLog(String(error?.message ?? error))) }, 'dsh-bb owner session cleanup')
@@ -309,8 +349,16 @@ export class DomainSessions {
         || existing.proc.exitCode !== null || existing.proc.signalCode !== null
         || existing.workspace !== resolve(workspace)
         || existing.policyKey !== (policy?.key ?? 'unconfined')
-      if (mustStop) await this.stopSession(owner, existing)
-      else return existing
+      if (mustStop) {
+        // A workspace or grant change is not a timeout: name it so the rebuilt
+        // session explains why its definitions could not be kept.
+        const reason = existing.cleanupPromise || existing.proc.killed
+          || existing.proc.exitCode !== null || existing.proc.signalCode !== null
+          ? 'interpreter-exit'
+          : 'policy-change'
+        this.resetReasons.set(owner, reason)
+        await this.stopSession(owner, existing)
+      } else return existing
     }
     const pending = this.pending.get(owner)
     if (pending) return pending
@@ -368,12 +416,65 @@ export class DomainSessions {
     return /DSH_BB_RESET:/.test(text)
   }
 
+  /**
+   * Model-safe session identity for one owner, as of the END of a call.
+   *
+   * Two dimensions are kept apart on purpose, because a single word cannot say
+   * both "which interpreter ran this code" and "is there still an interpreter":
+   *
+   * - `sessionState` is the survival verdict and always wins. `reused` means the
+   *   same interpreter is alive; `reset` means it is gone (dropped or destroyed);
+   *   `quarantined` means a reset was requested and cleanup could NOT be
+   *   confirmed, so the old process may still hold the Agent's state.
+   * - `interpreter` says whether the interpreter that ran this call was `created`,
+   *   `rebuilt` or `reused` relative to `beforeGeneration`, so an Agent can tell
+   *   a brand-new process from one it was already using.
+   *
+   * Deriving the verdict from the generation delta alone is wrong: `(domain/reset!)`
+   * as the very first call creates generation 1 and then destroys it, which must
+   * report `reset`, not `created`. Nothing identifying the live transport (nREPL
+   * session id, port, scratch path) is ever exposed.
+   */
+  sessionSnapshot(owner, beforeGeneration = 0, { resetRequested = false, cleanupConfirmed = false } = {}) {
+    const info = this.generations.get(owner)
+    const generation = info?.generation ?? 0
+    const live = this.live.has(owner)
+    const started = generation > beforeGeneration
+    const interpreter = !started ? 'reused' : beforeGeneration === 0 ? 'created' : 'rebuilt'
+    let sessionState = interpreter
+    if (resetRequested && cleanupConfirmed && !live) sessionState = 'reset'
+    // A reset whose cleanup could not be confirmed leaves the old interpreter
+    // (and its bindings) alive: say so instead of reporting a clean reset. The
+    // same verdict covers a reset that was never confirmed because it threw.
+    else if (resetRequested) sessionState = 'quarantined'
+    // No reset was attempted but nothing is live: the interpreter died on its own.
+    else if (!live) sessionState = 'reset'
+    // No interpreter has ever run for this owner: nothing was lost, so do not
+    // pretend a session exists or that definitions disappeared.
+    if (generation === 0) {
+      return { generation: 0, sessionState: 'unavailable', interpreter, definitionsLost: false }
+    }
+    return {
+      generation,
+      sessionState,
+      interpreter,
+      ...(info?.resetReason && sessionState !== 'reused' ? { resetReason: info.resetReason } : {}),
+      // Only a session that is REALLY gone lost its definitions, and only if it
+      // had any: a fresh interpreter created and dropped inside one call had
+      // nothing to lose. A quarantined or still-live interpreter keeps its
+      // state, so claiming loss would make the Agent redo work still in memory.
+      definitionsLost: sessionState === 'rebuilt'
+        || (sessionState === 'reset' && beforeGeneration > 0),
+    }
+  }
+
   async evaluate(owner, workspace, code, signal, explicitPolicy) {
     const prior = this.queues.get(owner) ?? Promise.resolve()
     const work = prior.then(async () => {
       if (signal?.aborted) throw signal.reason ?? new Error('Cancelled')
       const policy = explicitPolicy ?? this.policyFor?.(owner, workspace)
       const notes = []
+      const beforeGeneration = this.generations.get(owner)?.generation ?? 0
       const syncOnce = async session => this.bounded(
         () => this.syncModules(session), this.moduleSyncMs, 'Domain synchronization', signal)
       let session
@@ -383,7 +484,7 @@ export class DomainSessions {
         sync = await syncOnce(session)
         if (sync.reset) {
           notes.push(`session rebuilt: ${sync.reset}`)
-          await this.reset(owner)
+          await this.reset(owner, 'domain-update')
           session = await this.ensure(owner, workspace, signal, policy)
           sync = await syncOnce(session)
         }
@@ -392,8 +493,7 @@ export class DomainSessions {
         // nREPL socket and killing the process group is the cancellation.
         let reset = false
         try {
-          await this.reset(owner)
-          reset = true
+          reset = await this.reset(owner, abortReason(error, signal))
         } catch (resetError) {
           error.message = `${error.message} (${resetError.message})`
         }
@@ -401,6 +501,12 @@ export class DomainSessions {
           ? 'session reset: domain synchronization failed'
           : 'session cleanup failed; owner quarantined')
         error.notes = notes
+        // Only a *confirmed* cleanup may claim a lost session; a quarantined
+        // owner still holds unknown state that the Agent must not assume gone.
+        error.session = {
+          ...this.sessionSnapshot(owner, beforeGeneration, finalState(this.live, owner, reset)),
+          sessionReset: reset,
+        }
         throw error
       }
       if (sync.added.length) notes.push(`domain hot-loaded: ${sync.added.join(', ')}`)
@@ -417,17 +523,36 @@ export class DomainSessions {
           }),
         ])
         if (!result.ok && DomainSessions.isResetRequest(result)) {
-          await this.reset(owner)
-          notes.push('session reset: requested by domain.runtime/reset!')
-          return { ...result, notes, sessionReset: true }
+          let reset = false
+          try {
+            reset = await this.reset(owner, 'manual-reset')
+          } catch (resetError) {
+            notes.push(`session reset failed; owner quarantined: ${resetError.message}`)
+          }
+          if (reset) notes.push('session reset: requested by domain.runtime/reset!')
+          return {
+            ...result,
+            notes,
+            sessionReset: reset,
+            // This call may have created generation 1 and then dropped it, so the
+            // verdict comes from what is alive now, not from the generation delta.
+            session: {
+              ...this.sessionSnapshot(owner, beforeGeneration, finalState(this.live, owner, reset)),
+              sessionReset: reset,
+            },
+          }
+        }
+        return {
+          ...result,
+          notes: [...notes, ...(result.notes ?? [])],
+          sessionReset: false,
+          session: { ...this.sessionSnapshot(owner, beforeGeneration), sessionReset: false },
         }
-        return { ...result, notes: [...notes, ...(result.notes ?? [])], sessionReset: false }
       } catch (error) {
         // Timeout, abort or any transport failure leaves unknown interpreter state.
         let reset = false
         try {
-          await this.reset(owner)
-          reset = true
+          reset = await this.reset(owner, abortReason(error, signal))
         } catch (resetError) {
           error.message = `${error.message} (${resetError.message})`
         }
@@ -435,6 +560,10 @@ export class DomainSessions {
           ? 'session reset: previous interpreter state discarded'
           : 'session cleanup failed; owner quarantined')
         error.notes = notes
+        error.session = {
+          ...this.sessionSnapshot(owner, beforeGeneration, finalState(this.live, owner, reset)),
+          sessionReset: reset,
+        }
         throw error
       } finally {
         clearTimeout(timeoutId)
@@ -455,9 +584,17 @@ export class DomainSessions {
    * next call start a fresh process: overlapping writers are the failure this
    * ordering exists to prevent.
    */
-  async reset(owner) {
+  async reset(owner, reason) {
+    // Remember *why* the next interpreter starts before anything can fail, so a
+    // rebuild is never reported as an unexplained 'rebuilt'.
+    if (reason) this.resetReasons.set(owner, reason)
     const session = this.live.get(owner)
-    if (!session) return
+    if (!session) {
+      // Nothing was running. That is a *satisfied* reset (the interpreter is
+      // confirmed gone), not a failure, so the caller can report it as such.
+      this.resetReasons.delete(owner)
+      return true
+    }
     try {
       await this.stopSession(owner, session)
     } catch (error) {
@@ -465,11 +602,12 @@ export class DomainSessions {
       this.onLog(String(error?.message ?? error))
       throw error
     }
+    return true
   }
 
   async close() {
     this.disposed = true
     await Promise.allSettled([...this.creating])
-    await Promise.allSettled([...new Set([...this.live.keys()])].map(owner => this.reset(owner)))
+    await Promise.allSettled([...new Set([...this.live.keys()])].map(owner => this.reset(owner, 'shutdown')))
   }
 }