dsh-ptc-plus 0.5.1 → 0.5.3

package/internal/session-runtime.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto'
 import { isAbsolute } from 'node:path'
 import { isDeepStrictEqual } from 'node:util'
 import { diagnostic, renderDiagnostic } from './diagnostic.js'
@@ -12,10 +13,13 @@ import {
 import {
   foldSessionTimeline,
   pathToHead,
+  bindingNamesOfOperations,
   recoveryBoundaryForHistory,
   recoverJournal,
   visibleExecutableCallSeqs,
 } from './session-journal-recovery.js'
+import { sessionEvents } from './session-events.js'
+import { REPL_TOOL_NAMES } from './session-journal-schema.js'
 import { valueLimitsFromConfig } from './value-wire-schema.js'
 import { encodeValueAtBoundary, valueWiresEqual } from './value-wire.js'
 import { normalizeBindingDescriptors } from './binding-descriptors.js'
@@ -24,6 +28,7 @@ import { WorkerClient } from './worker-client.js'
 import { compilerWorkerCache } from './compiler-service.js'
 import { BindingCatalog, durabilityState, transitionDurability } from './session-state.js'
 import { SessionCellExecutor } from './session-cell-executor.js'
+import { CellAdmissionBlocked } from './cell-error.js'
 import { executionPolicies } from './binding-update-policy.js'
 import {
   createReplMemorySnapshot,
@@ -35,6 +40,22 @@ import {
 const WORKER_URL = new URL('./kernel-worker.js', import.meta.url)
 const UNAVAILABLE_SURFACE_GENERATION = Symbol('unavailableSurfaceGeneration')
 
+/**
+ * Tell "the surface proves this call is gone" apart from "the surface cannot be
+ * read right now".
+ *
+ * A queued message, a mid-flight surface replacement or any transient host
+ * state can leave `session.surface.nodes` unreadable for one request. Reading
+ * that as an empty visible set made every live binding look contracted, so the
+ * worker was reset and the journal replayed; a replay that cannot reproduce an
+ * old completion then contracted the whole suffix and the user lost the REPL.
+ * Only a readable surface may decide that a live binding lost its provenance.
+ */
+function surfaceReadable(session) {
+  if (!Array.isArray(session?.surface?.nodes)) return false
+  return Array.isArray(session?.events)
+}
+
 function surfaceGeneration(session, provenanceRequired = true) {
   try {
     const surface = session?.surface
@@ -48,12 +69,186 @@ function surfaceGeneration(session, provenanceRequired = true) {
   }
 }
 
-function recoveryDiagnostic(count) {
+/**
+ * Per-call source digest of the visible surface.
+ *
+ * A surface republish appends or re-renders; a history change removes a call or
+ * rewrites its source. Distinguishing the two needs the call set plus each
+ * call's own bytes, not the whole message tree: digests stay cheap, and an
+ * unchanged call keeps its digest across a re-render.
+ */
+/**
+ * Reduce a visible call set to the seqs both sides of the recovery comparison can
+ * name: `run_code` and `edit_run_code` call records.
+ *
+ * `visibleExecutableCallSeqs` also carries the record a derived execution starts
+ * from, which can be a `tool/result` or a nested `tool/ptc-dispatch` rather than a
+ * `tool/call`. The kernel never tracks those as live calls, so keeping them in the
+ * comparison made a vanished non-call look like a rewritten history and reset the
+ * worker for nothing.
+ *
+ * @param {readonly {seq: number, type: string, data?: object}[]} events
+ * @param {Set<number>} visibleSeqs
+ * @returns {{seqs: Set<number>, sources: Map<number, string>}}
+ */
+export function comparableVisibleCalls(events, visibleSeqs) {
+  const calls = new Set()
+  const sources = new Map()
+  for (const event of events ?? []) {
+    if (!visibleSeqs.has(event?.seq) || event?.type !== 'tool/call') continue
+    if (typeof event.data?.name === 'string' && !REPL_TOOL_NAMES.has(event.data.name)) continue
+    calls.add(event.seq)
+    const source = typeof event.data?.arguments === 'string' ? event.data.arguments : ''
+    sources.set(event.seq, createHash('sha256').update(source).digest('hex'))
+  }
+  return { seqs: calls, sources }
+}
+
+
+
+/**
+ * Wording of the contraction notice.
+ *
+ * A count of cells tells the model nothing it can act on; the binding names are
+ * what it must stop referencing. When no journal names them, the notice
+ * describes the contraction without pretending to know which bindings went away.
+ */
+export function recoveryDiagnosticMessage(bindings, count) {
+  const names = [...new Set(bindings ?? [])].filter(name => typeof name === 'string' && name !== '')
+  if (names.length === 0) {
+    return `Restored the durable head and skipped ${count ?? 1} unreconstructable historical cell(s); their source remains in the session log.`
+  }
+  return `Restored the durable head and dropped ${names.length} binding(s) (${names.join(', ')}) that no recorded value proves; their source remains in the session log.`
+}
+
+/**
+ * Notice for a replay whose completions diverged.
+ *
+ * The bindings exist because the replay produced them; what cannot be certified
+ * is the recorded completion payload. Saying so keeps the model from trusting a
+ * recorded result while leaving the live bindings in place.
+ */
+/**
+ * Notice for cells restored from their recorded values.
+ *
+ * A volatile cell cannot be replayed: running it again would redispatch the
+ * ambient source that made it volatile. Recovery installs the values it
+ * recorded instead, so the bindings are live while the recorded completions
+ * were never re-derived.
+ */
+export function restoredFromRecordDiagnostic(count, live, failed, continuation = false) {
+  // The cell count and the binding names describe different things: one cell can
+  // install several bindings, and an install can fail. Saying "restored N cells
+  // (a, b)" invites the model to read the names as the count and to trust a name
+  // that never made it into the worker, so the two facts stay separate and a
+  // failed name is never called live.
+  const livePart = live.length === 0
+    ? 'no binding was live'
+    : `${live.length} binding(s) live: ${live.join(', ')}`
+  const failedPart = failed.length === 0
+    ? ''
+    : `; ${failed.length} could not be installed and are NOT live: ${failed.join(', ')}`
+  return diagnostic({
+    code: 'PTC-R004',
+    severity: 'warning',
+    phase: 'recover',
+    message: `Restored ${continuation ? 'another ' : ''}${count} cell(s) from recorded values; ${livePart}${failedPart}. The recorded completions were not replayed.`,
+    stateEffect: 'unchanged',
+    help: [
+      'continue from the bindings listed as live',
+      'do not assume the recorded cells ran again; external effects they performed were not repeated',
+    ],
+  })
+}
+
+/**
+ * Notice for a binding that was announced as live and then stopped existing.
+ *
+ * Reporting it when it happens keeps the model from reading a later
+ * `x is not defined` as its own mistake: the binding went away outside the
+ * cell that names it.
+ */
+export function vanishedBindingDiagnostic(names) {
+  const list = names.join(', ')
+  return diagnostic({
+    code: 'PTC-R006',
+    severity: 'warning',
+    phase: 'recover',
+    message: `${names.length} binding(s) reported live earlier are no longer available: ${list}. The REPL state lost them without a cell asking for it.`,
+    stateEffect: 'unchanged',
+    help: [`redeclare ${list} before using them again`],
+  })
+}
+
+/**
+ * Notice for bindings a recorded revision superseded.
+ *
+ * A revision that rewrites its target puts the target off the recorded path, so
+ * the target's declarations stop building the environment. They are not missing:
+ * the log says which revision replaced them, and reporting that relation keeps
+ * the model from reading a later `x is not defined` as its own mistake.
+ */
+export function supersededDiagnostic(bindings, supersessions = []) {
+  const names = bindings.length === 0 ? '' : ` (${bindings.join(', ')})`
+  const relations = supersessions.map(item =>
+    `cell ${item.supersededCallSeq} by cell ${item.supersedingCallSeq}`).join('; ')
+  return diagnostic({
+    code: 'PTC-R007',
+    severity: 'warning',
+    phase: 'recover',
+    message: (bindings.length === 0
+      ? 'A recorded revision replaced the cell it edited'
+      : `Superseded ${bindings.length} binding(s)${names} because a recorded revision replaced the cell that declared them`)
+      + `${relations === '' ? '' : ` (${relations})`}. The replaced cell stays in the session log but no longer builds this environment.`,
+    stateEffect: 'rolled-back',
+    help: [
+      'this is not a recovery failure: an accepted edit rewrote the cell that declared these bindings, and the revision does not declare them',
+      'redeclare a superseded name in a new cell before using it again',
+    ],
+  })
+}
+
+function unverifiedCompletionDiagnostic(count) {
+  return diagnostic({
+    code: 'PTC-R003',
+    severity: 'warning',
+    phase: 'recover',
+    message: `Replayed ${count} historical cell(s) whose completion differs from the record; their bindings are live and their recorded results stay unverified.`,
+    stateEffect: 'unchanged',
+    help: [
+      'continue from the restored bindings',
+      'do not rely on the recorded result values of the cells named here',
+    ],
+  })
+}
+
+/**
+ * Notice for bindings a recorded rewind ended.
+ *
+ * They are not missing: the record says they are gone, because the cell that
+ * restored an earlier durable state abandoned them. Reporting them apart from a
+ * genuine loss keeps the two costs distinguishable.
+ */
+export function rewindEndedDiagnostic(bindings) {
+  const names = bindings.length === 0 ? '' : ` (${bindings.join(', ')})`
+  return diagnostic({
+    code: 'PTC-R005',
+    severity: 'warning',
+    phase: 'recover',
+    message: `Dropped ${bindings.length} binding(s)${names} because a recorded rewind ended them.`,
+    stateEffect: 'rolled-back',
+    help: [
+      'this is not a recovery failure: the cell that restored an earlier durable state ended these bindings on purpose',
+    ],
+  })
+}
+
+function recoveryDiagnostic(bindings, count) {
   return diagnostic({
     code: 'PTC-R002',
     severity: 'warning',
     phase: 'recover',
-    message: `Restored the durable head and skipped ${count} unreconstructable historical cell(s); their source remains in the session log.`,
+    message: recoveryDiagnosticMessage(bindings, count),
     stateEffect: 'rolled-back',
     help: [
       'continue from the restored bindings',
@@ -62,6 +257,25 @@ function recoveryDiagnostic(count) {
   })
 }
 
+/** Every binding name the folded history no longer proves. */
+function droppedBindingNames(history) {
+  const names = []
+  for (const item of history?.volatileSuffix ?? []) {
+    for (const name of item.bindings ?? []) names.push(name)
+  }
+  return names
+}
+
+/**
+ * A replayed cell whose completion no longer matches its record.
+ *
+ * The bindings the replay produced are real; only the recorded completion
+ * payload cannot be certified. Contracting here used to drop every later
+ * binding the log still proves, so a divergence is recorded and the replay
+ * continues instead.
+ */
+class ReplayDivergence extends Error {}
+
 function resolvedRuntimeConfig(config) {
   return Object.freeze(resolveConfig(config))
 }
@@ -70,6 +284,21 @@ function emptyHistory() {
   return { nodes: [], head: undefined, checkpoints: new Map(), volatileSuffix: [], available: true }
 }
 
+/**
+ * How many historical REPL cells a disposed identity leaves behind.
+ *
+ * A disposed owner's environment is not resumed, so the count only sizes the
+ * one notice that tells the model how much history is gone. Prefer the proven
+ * executable calls and fall back to one so the notice is never silent.
+ */
+function disposedHistoryCells(sessionLog, callSeq) {
+  const visible = visibleExecutableCallSeqs(sessionLog)
+  if (!(visible instanceof Set)) return 1
+  // The submitted cell already appears in the log; it is not history.
+  const historical = [...visible].filter(seq => seq !== callSeq)
+  return historical.length > 0 ? historical.length : 1
+}
+
 class ReplayFailure extends Error {
   constructor(node, cause) {
     super(messageOf(cause))
@@ -77,6 +306,18 @@ class ReplayFailure extends Error {
   }
 }
 
+/**
+ * Fallback for `unmeasuredCellLimit`: consecutive cells that may end before
+ * they reach the runtime while the live worker is kept.
+ *
+ * One such cell is not evidence about the worker: the host may simply have been
+ * unable to observe it. The configured limit (default two) ends the sequence, so
+ * a worker that never becomes dispatchable cannot stay in charge of every later
+ * cell; reaching it drops the live worker and lets the next cell replay the
+ * proved frontier.
+ */
+const UNMEASURED_CELL_LIMIT = 2
+
 class ReplayCancelled extends Error {
   constructor(result) {
     super(result.error?.message ?? 'session replay cancelled')
@@ -84,8 +325,21 @@ class ReplayCancelled extends Error {
   }
 }
 
+/**
+ * A recorded cell whose execution could not be measured.
+ *
+ * The cell never ran, so the recorded history remains exactly as proved and the
+ * replay may be attempted again through a fresh worker.
+ */
+class ReplayUnmeasured extends Error {
+  constructor(result) {
+    super(result.error?.message ?? 'session replay could not be measured')
+    this.result = result
+  }
+}
+
 class SessionKernel {
-  constructor({ config, history, cwd, session, surfaceProvenanceRequired, userBindingsCwd, withInitiator, observeValues }) {
+  constructor({ config, history, cwd, session, surfaceProvenanceRequired, userBindingsCwd, withInitiator, observeValues, disposedCells = 0 }) {
     this.config = config
     this.history = history
     this.initialRecoveryBoundary = recoveryBoundaryForHistory(history)
@@ -99,11 +353,27 @@ class SessionKernel {
     this.durability = durabilityState()
     this.bindingCatalog = new BindingCatalog()
     this.replayed = false
+    this.unmeasuredCells = 0
     this.liveCallSeqs = new Set()
-    this.recoveryNotice = history.volatileSuffix.length === 0
-      ? undefined
-      : recoveryDiagnostic(history.volatileSuffix.length)
-    this.recoveryNoticeShown = false
+    this.unverifiedCompletions = []
+    this.restoredFromRecord = []
+    this.recoveryNotices = disposedCells > 0
+      // A kernel whose owning agent or session was disposed must not resurrect
+      // the disposed environment: the history is gone by contract, and a later
+      // cell starts from an empty REPL with the loss reported once.
+      ? [recoveryDiagnostic([], disposedCells)]
+      : history.volatileSuffix.length === 0
+        ? []
+        : [recoveryDiagnostic(droppedBindingNames(history), history.volatileSuffix.length)]
+    // Bindings a recovery told the model were live, and the last help pair that
+    // explained a recovery. Both exist to keep one event from being reported
+    // twice and to notice a binding that stops existing afterwards.
+    this.announcedLive = new Set()
+    // A recorded supersession is a durable fact; announcing it once per runtime
+    // keeps later folds from repeating a relation the model already read.
+    this.announcedSupersessions = new Set()
+    this.recoveryHelpSignature = undefined
+    this.recoveryEventCount = 0
     this.active = undefined
     this.sequence = 0
     this.tail = Promise.resolve()
@@ -167,10 +437,29 @@ class SessionKernel {
     return attempt
   }
 
+  /**
+   * Start the session worker with the bounds the kernel holds now.
+   *
+   * The worker serves later cells as well as the one that starts it, so its
+   * close rule and startup bound follow the kernel's current configuration even
+   * when the starting cell was admitted before a settings change. Calibrating
+   * the transport after ensure covers a worker that already existed.
+   */
+  async ensureWorker(maxOldGenerationSizeMb) {
+    // A live worker already took its bounds at creation and reconfigure keeps it
+    // current. The client reads this projection only when it actually starts a
+    // worker, after its scratch wait, so a settings change in that window still
+    // reaches the startup and close bounds.
+    return this.client.ensure(maxOldGenerationSizeMb, () => ({
+      reclaimBoundMs: this.config.workerReclaimMs,
+      startupProbeMs: this.config.startupProbeMs,
+    }))
+  }
+
   async prepareWorker() {
     await Promise.all([...this.reclamationAttempts])
     const failures = [...this.reclamationRecords.values()].filter(record => record.failed).map(record => record.reason)
-    if (failures.length) throw new AggregateError(failures, 'previous computation helper reclamation failed; dispose the session before continuing')
+    if (failures.length) throw new CellAdmissionBlocked(failures)
   }
 
   valueLimits(config = this.config) {
@@ -189,6 +478,13 @@ class SessionKernel {
   reconfigure(config) {
     this.assertReconfigurationAllowed(config)
     this.config = config
+    // The close path reads the bound the transport carries, and a live worker can
+    // be dropped outside resetWorker (idle disposal, owner auto-close), so the
+    // current configuration has to reach the transport as soon as it is applied.
+    const worker = this.client.worker
+    if (worker !== undefined && Number.isSafeInteger(config.workerReclaimMs)) {
+      worker.reclaimBoundMs = config.workerReclaimMs
+    }
   }
 
   reserveWorkerConfiguration(config) {
@@ -273,54 +569,141 @@ class SessionKernel {
     if (this.surfaceProvenanceRequired
       && (currentGeneration !== this.surfaceGeneration || hasLiveState)) {
       this.surfaceGeneration = currentGeneration
-      const visibleCallSeqs = visibleExecutableCallSeqs(observedSession)
-      const contractsLiveState = [...this.liveCallSeqs].some(callSeq => (
-        !(visibleCallSeqs instanceof Set) || !visibleCallSeqs.has(callSeq)
-      ))
-      if ((config.durableReplay && !this.replayed) || contractsLiveState) {
+      // An unreadable surface is undecidable, not proof of contraction: keep the
+      // worker and its bindings instead of dropping them on a transient read.
+      const surfaceIsReadable = surfaceReadable(observedSession)
+      const visibleCallSeqs = surfaceIsReadable ? visibleExecutableCallSeqs(observedSession) : undefined
+      // The surface is a view, not the authority over a live worker. A re-render,
+      // a windowed republish, a working-directory change or an edit the runtime
+      // appended never costs the user bindings the worker still holds: this block
+      // rebuilds only when the worker is gone, the kernel was disposed, an explicit
+      // rewind or head cut was applied, or the first replay after a restart runs.
+      const workerAlive = this.client.worker !== undefined
+      const initialReplay = config.durableReplay && !this.replayed
+      if (!workerAlive || initialReplay) {
+
         const worker = this.client.worker
-        if (worker !== undefined) await this.client.reset(worker)
+        // A refused stop stays recorded here, so the later admission check in
+        // prepareWorker() blocks computation beside an unreclaimed helper.
+        if (worker !== undefined) await this.resetWorker(worker)
         this.rollbackToDurable()
         if (config.durableReplay) {
-          this.recoveryNotice = undefined
+          this.recoveryNotices = []
           try {
             this.history = recoverJournal(observedSession, request.callSeq, {
               visibleCallSeqs,
+              editRewritesHistory: config.editRewritesHistory === true,
             })
           } catch (error) {
+            /* c8 ignore start -- the fold reports damaged history as data, so no supported session reaches this catch */
             const boundary = recoveryBoundaryForHistory(this.history, undefined, { reset: true })
             if (boundary !== undefined) recoveryBoundaries.push(boundary)
             this.history = emptyHistory()
-            this.recoveryNotice = recoveryDiagnostic(1)
+            this.recoveryNotices = [recoveryDiagnostic([], 1)]
             this.initialRecoveryBoundary = undefined
+            /* c8 ignore stop */
           }
+          /* c8 ignore start -- volatile suffix on the first fold; no case settles a volatile suffix before the first replay */
           if (this.history.volatileSuffix.length > 0) {
-            this.recoveryNotice = recoveryDiagnostic(this.history.volatileSuffix.length)
+            this.recoveryNotices = [recoveryDiagnostic(
+              droppedBindingNames(this.history), this.history.volatileSuffix.length)]
           }
+          /* c8 ignore stop */
           this.initialRecoveryBoundary = recoveryBoundaryForHistory(this.history)
+          /* c8 ignore start -- first-fold recovery boundary; no case makes the first replay record one */
           if (this.initialRecoveryBoundary !== undefined) {
             recoveryBoundaries.push(this.initialRecoveryBoundary)
             this.initialRecoveryBoundary = undefined
+          /* c8 ignore stop */
           }
         } else {
           this.history = emptyHistory()
           this.replayed = true
-          this.recoveryNotice = recoveryDiagnostic(1)
+          this.recoveryNotices = [recoveryDiagnostic([], 1)]
         }
       }
     }
     if (!this.replayed && config.durableReplay) {
       let skipped = 0
+      let recoveryAttempted = false
+      // A replay pass can end before the loop settles either because it was
+      // cancelled or because a recorded cell could not be measured; a front it
+      // already contracted still has to reach the model in those cases.
+      const leavingReplay = result => {
+        if (skipped === 0) return result
+        const notice = recoveryDiagnostic([], skipped)
+        if (request.journal !== undefined) request.journal.diagnostics.push(notice)
+        return { ...result, logs: [...result.logs, renderDiagnostic(notice, request.program)] }
+      }
       while (!this.replayed) {
         try {
           await this.replayHistory(request, config)
           this.replayed = true
         } catch (error) {
+          // Reclamation goes through the kernel's owner so a refused stop stays
+          // recorded: prepareWorker() then blocks later computation until that
+          // failure is handled, instead of admitting it beside a live helper.
+          const retainedReasons = () => [...this.reclamationRecords.values()]
+            .filter(record => record.failed)
+            .map(record => record.reason)
           const worker = this.client.worker
-          if (worker !== undefined) await this.client.reset(worker)
+          // A refusal may predate this catch: the abandoned cell that ended the
+          // previous attempt already reset its worker, so no worker is reachable
+          // here while the failure stays recorded. A retained refusal keeps the
+          // helper until disposal, so a second attempt would record the same
+          // refusal again; the guidance below follows the retained outcome, which
+          // is also what the admission gate enforces.
+          if (worker !== undefined && retainedReasons().length === 0) await this.resetWorker(worker)
+          const reasons = retainedReasons()
+          const unreclaimed = reasons.length === 0
+            ? ''
+            : `; helper reclamation failed: ${String(reasons[0]?.message ?? reasons[0])}`
+          if (error instanceof CellAdmissionBlocked) {
+            // The replay could not start because an earlier helper was not
+            // reclaimed. That says nothing about the recorded cells, so the
+            // frontier keeps what this pass proved, including a contraction it
+            // already performed, whose notice therefore still has to be reported.
+            const blocked = { logs: [], error: { kind: 'worker-exit', message: error.message } }
+            this.completeJournal(request.journal, 'discarded', blocked)
+            return finishResult(leavingReplay(blocked))
+          }
           if (error instanceof ReplayCancelled) {
             this.completeJournal(request.journal, 'noop', error.result)
-            return finishResult(error.result)
+            return finishResult(leavingReplay(error.result))
+          }
+          // A historical cell that could not be measured never ran, so it proves
+          // nothing against the recorded frontier. The reset above left an empty
+          // worker, so the replay is retried once; a second unmeasured replay
+          // through a fresh worker still says nothing about the recorded history,
+          // which therefore stays intact for the next cell to replay again.
+          if (error instanceof ReplayUnmeasured) {
+            if (!recoveryAttempted && unreclaimed === '') {
+              recoveryAttempted = true
+              this.durability = durabilityState()
+              continue
+            }
+            this.rollbackToDurable()
+            const blocked = unreclaimed !== ''
+            // The sampled cell's own message tells the model to retry that cell and
+            // may already carry the refusal. Neither holds here: the admission gate
+            // will refuse the retry, and one refusal must not be reported twice.
+            const facts = blocked ? messageOf(error).replace('; retry the cell', '') : messageOf(error)
+            const repeated = blocked && facts.includes(unreclaimed)
+            const unmeasured = {
+              logs: error.result.logs,
+              error: {
+                kind: 'budget-unavailable',
+                // A refusal leaves later computation blocked, so the result must
+                // not promise a replay that the admission gate will refuse.
+                message: `${facts}; ${skipped === 0
+                  ? 'the recorded frontier is unchanged'
+                  : 'the recorded frontier contracted as the recovery notice reports'}, ${blocked
+                  ? 'later computation stays blocked until the session is disposed'
+                  : 'the kernel worker was reset, and the next cell replays the remaining frontier'}${repeated ? '' : unreclaimed}`,
+              },
+            }
+            this.completeJournal(request.journal, 'noop', unmeasured)
+            return finishResult(leavingReplay(unmeasured))
           }
           try {
             if (!(error instanceof ReplayFailure)) throw error
@@ -329,6 +712,7 @@ class SessionKernel {
             const recovered = recoverJournal(observedSession, request.callSeq, {
               extraBoundaries: [boundary],
               visibleCallSeqs: visibleExecutableCallSeqs(observedSession),
+              editRewritesHistory: config.editRewritesHistory === true,
             })
             const nextPathLength = pathToHead(recovered).length
             if (nextPathLength >= previousPathLength) throw new Error('recovery did not contract the historical frontier')
@@ -347,23 +731,145 @@ class SessionKernel {
           this.durability = durabilityState()
         }
       }
-      if (skipped > 0) this.recoveryNotice = recoveryDiagnostic(skipped)
+      // One recovery event produces one report. The facts below describe the same
+      // event, so each one that holds is collected instead of overwriting the ones
+      // already found: an earlier overwrite dropped the restored-name list whenever
+      // a later fact arrived, and a relation dropped that way was then cleared
+      // without ever reaching the model. The facts never name the same binding, so
+      // collecting them states the event once per fact rather than twice per name.
+      const restoredCount = this.restoredFromRecord.length
+      const allLive = [...new Set(this.restoredFromRecord.flatMap(item => item.bindings))]
+      // Report only what this recovery added. A later recovery that installs
+      // nothing new (same bindings, same count) would otherwise repeat a sentence
+      // the model already acted on.
+      const liveNames = allLive.filter(name => !this.announcedLive.has(name))
+      // The executor reports `{ name, reason }` for a refused install; a notice that
+// printed the entry itself used to render `[object Object]` where the binding
+// name belongs.
+const failedNames = [...new Set(this.restoredFromRecord
+  .flatMap(item => item.failed.map(entry => typeof entry === 'string' ? entry : entry?.name))
+  .filter(name => typeof name === 'string'))]
+      const droppedNames = this.missingBindings === undefined ? [] : [...new Set(this.missingBindings)]
+      const endedNames = this.rewindEndedBindings === undefined ? [] : [...new Set(this.rewindEndedBindings)]
+      const supersededNames = this.supersededEndedBindings === undefined
+        ? [] : [...new Set(this.supersededEndedBindings)]
+      const alreadyReported = this.recoveryEventCount > 0
+      // A complete restore is invisible to the model. Every recorded binding was
+      // installed, nothing was dropped or ended, and the next cell behaves exactly
+      // as it would have without the recovery, so a notice would only report plugin
+      // mechanics: in the audited session one such line cost two reasoning blocks of
+      // source-code investigation and changed no decision. The names stay tracked so
+      // that a later disappearance can still be named; only the announcement goes.
+      const completeRestore = failedNames.length === 0
+        && droppedNames.length === 0
+        && endedNames.length === 0
+        && supersededNames.length === 0
+      if (restoredCount > 0 && completeRestore) {
+        this.restoredFromRecord = []
+      /* c8 ignore start -- needs a rewind that ended an announced name after a reported recovery; no case does */
+      } else if (restoredCount > 0 && liveNames.length === 0 && failedNames.length === 0 && alreadyReported) {
+        this.restoredFromRecord = []
+      /* c8 ignore stop */
+      } else if (restoredCount > 0) {
+        this.recoveryEventCount += 1
+        this.recoveryNotices.push(restoredFromRecordDiagnostic(
+          restoredCount,
+          liveNames,
+          failedNames,
+          alreadyReported,
+        ))
+      }
+      /* c8 ignore start -- needs a proven name the replay never visits; no case records one */
+      if (droppedNames.length > 0) {
+        this.recoveryNotices.push(recoveryDiagnostic(droppedNames, droppedNames.length))
+      /* c8 ignore stop */
+      } else if (restoredCount === 0 && skipped > 0) {
+        this.recoveryNotices.push(recoveryDiagnostic([], skipped))
+      }
+      // A rewind that ended a binding is recorded, not a loss: report it only when
+      // the replay installed nothing under that name anywhere (path, off-path or
+      // catalog), so a correct value never carries a "dropped" notice. A revision
+      // that superseded a cell is the other recorded ending: the environment it
+      // built differs from the cells the log still lists, so the relation is
+      // reported once per runtime instead of on every later fold.
+      const freshSupersessions = (this.supersessions ?? [])
+        .filter(item => !this.announcedSupersessions.has(item.supersedingCallSeq))
+      // A restored cell and a superseded one are two facts about the same recovery,
+      // not alternatives: the names this relation withdrew are excluded from the
+      // missing and rewind lists, so a report that chose the restore notice over it
+      // left a withdrawn name reported nowhere.
+      if (freshSupersessions.length > 0 || supersededNames.length > 0) {
+        this.recoveryNotices.push(supersededDiagnostic(supersededNames, freshSupersessions))
+        for (const item of freshSupersessions) this.announcedSupersessions.add(item.supersedingCallSeq)
+      }
+      if (endedNames.length > 0) {
+        this.recoveryNotices.push(rewindEndedDiagnostic(endedNames))
+      }
+      // A completion the replay could not certify is not a lost binding: the
+      // replay established them, and only the recorded payload stays unproved.
+      if (this.unverifiedCompletions.length > 0) {
+        this.recoveryNotices.push(unverifiedCompletionDiagnostic(this.unverifiedCompletions.length))
+      }
+      if (this.recoveryNotices.length > 0) {
+        // Remember what was promised as live, so a binding that disappears later
+        // is reported by name instead of surfacing as an unexplained ReferenceError.
+        for (const name of liveNames) this.announcedLive.add(name)
+        // The help pair explains the recovery once. Repeating it on every later
+        // recovery in the same session is noise the model cannot act on twice.
+        const signature = this.recoveryNotices.map(item => item.message).join('\n')
+        if (this.recoveryHelpSignature === signature) {
+          this.recoveryNotices = this.recoveryNotices.map(item => ({ ...item, help: [] }))
+        } else {
+          this.recoveryHelpSignature = signature
+        }
+      }
+      this.restoredFromRecord = []
+      this.missingBindings = undefined
+      this.rewindEndedBindings = undefined
+      this.supersededEndedBindings = undefined
+      this.supersessions = undefined
     }
-    const leadingDiagnostics = this.recoveryNotice === undefined || this.recoveryNoticeShown
-      ? [] : [this.recoveryNotice]
-    this.recoveryNoticeShown = this.recoveryNotice !== undefined
-    this.recoveryNotice = undefined
+    // Every recovery reports the facts it established. Suppressing a later recovery's
+    // notice hid a relation the runtime had already marked as announced, so a name the
+    // revision withdrew was reported nowhere; what is deduplicated is the explanation
+    // (below) and each name or relation this runtime already stated.
+    const leadingDiagnostics = this.recoveryNotices
+    this.recoveryNotices = []
     if (request.journal !== undefined) request.journal.diagnostics.push(...leadingDiagnostics)
-    const result = await this.cellExecutor.executeCell(request, undefined, config)
+    let result
+    try {
+      result = await this.cellExecutor.executeCell(request, undefined, config)
+    } catch (error) {
+      // The kernel refused to admit this cell because an earlier helper was not
+      // reclaimed. Nothing ran and nothing about the recorded history changed, so
+      // the cell settles on its own terms instead of blaming the source; the
+      // recovery notice prepared above is still attached below.
+      if (!(error instanceof CellAdmissionBlocked)) throw error
+      result = { logs: [], error: { kind: 'worker-exit', message: error.message } }
+      this.completeJournal(request.journal, 'discarded', result)
+    }
     if (result.error === undefined) {
       this.failures.reset()
     } else {
       const primary = request.journal?.diagnostics.find(item => item.severity === 'error')
-      const hint = this.failures.hint(result.error, primary?.stateEffect)
+      // A no-op journal is this cell's own record that nothing it could have done
+      // is in the REPL state, so a repeated-failure hint must not describe that
+      // state as unknown.
+      const stateEffect = primary?.stateEffect
+        ?? (request.journal?.status === 'noop' ? 'unchanged' : undefined)
+      const hint = this.failures.hint(result.error, stateEffect)
       if (hint !== undefined) {
         result.logs = [...result.logs, renderDiagnostic(hint, request.program)]
         if (request.journal !== undefined) request.journal.diagnostics.push(hint)
       }
+      // A binding announced as live by a recovery, now reported missing by the
+      // engine itself, went away outside this cell. Naming it here keeps the
+      // model from reading its own correct reference as a mistake it made.
+      const vanished = this.vanishedAnnouncedBindings(result.error, request.program)
+      if (vanished.length > 0) {
+        result.logs = [...result.logs, renderDiagnostic(vanished[0], request.program)]
+        if (request.journal !== undefined) request.journal.diagnostics.push(...vanished)
+      }
     }
     if (leadingDiagnostics.length > 0) {
       const rendered = leadingDiagnostics.map(item => renderDiagnostic(item, request.program))
@@ -373,15 +879,68 @@ class SessionKernel {
     return finishResult(result)
   }
 
+  /**
+   * Bindings a recovery promised as live that the engine now reports missing.
+   *
+   * Each name is reported once: the set is drained when it is named, so a later
+   * cell repeating the same reference does not repeat the notice.
+   */
+  vanishedAnnouncedBindings(error, program) {
+    if (this.announcedLive.size === 0) return []
+    const message = String(error?.message ?? '')
+    const match = /(?:ReferenceError:\s*)?([A-Za-z_$][\w$]*) is not defined/.exec(message)
+    if (match === null) return []
+    const name = match[1]
+    if (!this.announcedLive.has(name)) return []
+    this.announcedLive.delete(name)
+    void program
+    return [vanishedBindingDiagnostic([name])]
+  }
+
   async replayHistory(request, config) {
     this.bindingCatalog = new BindingCatalog()
     const limits = this.valueLimits(config)
     const emptyArgsWire = encodeValueAtBoundary({}, limits, 'parameter')
     const path = pathToHead(this.history)
+    // Every binding the session log proves has to come back or be named. A node
+    // that is not on the path to the head never replays, so its bindings would
+    // otherwise disappear without a diagnostic.
+    const replayedNames = new Set()
+    for (const node of path) {
+      for (const value of node.journal.values ?? []) replayedNames.add(value.name)
+      for (const name of bindingNamesOfOperations(node.journal.operations)) replayedNames.add(name)
+    }
+    // A recorded rewind ended these bindings on purpose: they are gone by record,
+    // not by omission, so they are reported apart from the ones recovery failed to
+    // install. Nothing else may report them as missing.
+    const endedBindings = new Set(this.history.deletedBindings ?? [])
     for (const node of path) {
       const bindings = replayBindingNamespaces(request.bindings, node.journal, limits, emptyArgsWire)
       const bindingDescriptors = bindings === request.bindings
         ? request.bindingDescriptors : normalizeBindingDescriptors(bindings)
+      // A cell the journal recorded as volatile keeps the values it produced.
+      // Installing them is the only replay that does not redispatch the ambient
+      // source that made the cell volatile, so its completion stays unverified
+      // while its bindings stay live.
+      if (node.restoredFromRecord === true) {
+        const restored = await this.cellExecutor.executeCell(
+          {
+            ...request,
+            bindings: bindingDescriptors.namespaces,
+            bindingDescriptors,
+            program: node.code,
+            journal: undefined,
+            restoreValues: node.journal.values,
+            ...(node.userBindings === undefined ? { userBindings: undefined } : { userBindings: node.userBindings }),
+          },
+          node.journal,
+          config,
+        )
+        if (restored.error !== undefined) throw new ReplayFailure(node, new Error(restored.error.message))
+        this.restoredFromRecord.push({ callSeq: node.callSeq,
+          bindings: restored.restored ?? [], failed: restored.failed ?? [] })
+        continue
+      }
       try {
         const result = await this.cellExecutor.executeCell(
           {
@@ -398,26 +957,58 @@ class SessionKernel {
         const completion = node.journal.completion
         if (result.error !== undefined && !['exception', 'invalid-output'].includes(result.error.kind)) {
           if (result.error.kind === 'abort') throw new ReplayCancelled(result)
+          // An unmeasured cell never ran: it disproves nothing about the recorded
+          // frontier, and the replay can be attempted again through a fresh worker.
+          if (result.error.kind === 'budget-unavailable') throw new ReplayUnmeasured(result)
           throw new Error(`cell replay infrastructure failed (${result.error.kind}): ${result.error.message}`)
         }
         if (completion.kind === 'return' && result.error !== undefined) {
-          throw new Error(`cell replay failed: ${result.error.message}`)
+          throw new ReplayDivergence(`recorded cell returned a value and the replay failed: ${result.error.message}`)
         }
         if (completion.kind === 'throw') {
           if (result.error === undefined) throw new Error('cell replay succeeded where the recorded cell failed')
           if (result.error.kind !== completion.error.kind || result.error.message !== completion.error.message) {
-            throw new Error('cell replay produced a different semantic failure')
+            throw new ReplayDivergence('cell replay produced a different semantic failure')
           }
         }
       } catch (error) {
-        if (error instanceof ReplayCancelled) throw error
+        // A blocked admission is not a fact about this recorded cell, so it is
+        // rethrown unchanged and never wrapped as a replay failure.
+        if (error instanceof ReplayCancelled || error instanceof ReplayUnmeasured
+          || error instanceof CellAdmissionBlocked) throw error
+        // The replay produced real bindings and a different completion. Contracting
+        // here dropped every later binding the log still proves, which is how a
+        // diverging completion cost the user the whole REPL; certify the divergence
+        // and keep replaying from the bindings the replay established.
+        if (error instanceof ReplayDivergence) {
+          this.unverifiedCompletions.push({ callSeq: node.callSeq, reason: error.message })
+          continue
+        }
         throw new ReplayFailure(node, error)
       }
     }
     for (const node of path) this.liveCallSeqs.add(node.callSeq)
+    // Names the replay installed include the ones the binding catalog supplies: a
+    // binding can come back through the catalog without any cell executing, so the
+    // arithmetic below counts that evidence too. Without it a rewound branch whose
+    // binding returned through the catalog was reported as ended while its value was
+    // correct.
+    const installed = new Set(replayedNames)
+    for (const name of this.bindingCatalog.inputs().knownBindings) installed.add(name)
+    // A superseded name is ended by the record that replaced its cell, so it is
+    // reported apart from a rewind and never as a binding recovery failed to
+    // install: the log says which revision replaced it.
+    const supersededEnded = new Set((this.history.supersededBindings ?? [])
+      .filter(name => !installed.has(name)))
+    this.rewindEndedBindings = [...endedBindings]
+      .filter(name => !installed.has(name) && !supersededEnded.has(name))
+    this.supersededEndedBindings = [...supersededEnded]
+    this.supersessions = this.history.supersessions ?? []
+    this.missingBindings = (this.history.provenBindings ?? [])
+      .filter(name => !installed.has(name) && !endedBindings.has(name) && !supersededEnded.has(name))
   }
 
-  completeJournal(journal, status, result, volatileReason, diagnostics = [], completion = undefined) {
+  completeJournal(journal, status, result, volatileReason, diagnostics = [], completion = undefined, values = undefined) {
     if (journal === undefined) return
     journal.status = status
     journal.completion = result.error === undefined
@@ -428,6 +1019,13 @@ class SessionKernel {
         }
       : { kind: 'throw', error: { kind: result.error.kind, message: result.error.message } }
     if (volatileReason !== undefined) journal.volatileReason = volatileReason
+    // A volatile cell keeps the values it produced so recovery can install them
+    // without running the cell again; a value the codec could not transfer is
+    // named instead of being omitted silently.
+    if (values !== undefined && (values.values.length > 0 || values.unrecorded.length > 0)) {
+      journal.values = values.values
+      if (values.unrecorded.length > 0) journal.unrecordedBindings = values.unrecorded
+    }
     if (diagnostics.length > 0) journal.diagnostics.push(...diagnostics)
     if (status === 'volatile') {
       journal.operations = journal.operations.filter(operation => operation.action !== 'save')
@@ -443,14 +1041,72 @@ class SessionKernel {
     this.workerObservation = undefined
     this.durability = durabilityState()
     this.replayed = false
+    // Every path that drops the live worker replaces it, so the next cell starts
+    // its own sequence of unmeasured cells on a worker that has not failed yet.
+    this.unmeasuredCells = 0
     this.bindingCatalog = new BindingCatalog()
     this.liveCallSeqs.clear()
   }
 
+  /**
+   * Settle a cell that never reached the runtime.
+   *
+   * A cell that was never dispatched has nothing to discard, no binding to roll
+   * back and no reason to rebuild the worker, so its journal records a no-op
+   * outcome and the live worker keeps the state earlier cells proved. Consecutive
+   * such cells are the evidence that this worker does not become dispatchable:
+   * the live worker is then dropped while the proved frontier stays, and the next
+   * cell replays it. Budgets and the cancellation listener end with the cell
+   * exactly as they do on any other settlement.
+   */
+  abandonCell(active, result) {
+    if (this.active !== active) return
+    active.settled = true
+    clearInterval(active.computeTimer)
+    clearTimeout(active.wallTimer)
+    active.request.signal?.removeEventListener('abort', active.onAbort)
+    this.active = undefined
+    this.completeJournal(active.journal, 'noop', result)
+    this.unmeasuredCells += 1
+    // The cell was submitted under its own configuration snapshot, and that
+    // snapshot decides its settlement even if the setting changed while it ran.
+    // `admission.config` is the runtime configuration object itself (`beginSubmission`
+    // stores `this.config` by reference), so a second lookup on `this.config` could only
+    // repeat the first answer. The shipped constant is the real fallback.
+    const limit = Number.isSafeInteger(active.config?.unmeasuredCellLimit)
+      ? active.config.unmeasuredCellLimit
+      : UNMEASURED_CELL_LIMIT
+    if (this.unmeasuredCells < limit) {
+      active.finish(result)
+      return
+    }
+    this.rollbackToDurable()
+    // The model has to learn that the state this worker held is gone; only the
+    // proved frontier survives for the next cell to replay.
+    result = { ...result, error: { ...result.error,
+      message: `${result.error?.message ?? 'cell could not be measured'}; this worker was dropped after consecutive unmeasured cells, so bindings outside the proved recovery frontier are no longer available` } }
+    this.completeJournal(active.journal, 'noop', result)
+    // A refused reclamation stays recorded on this kernel instead of becoming an
+    // unhandled rejection; the kernel keeps the worker until dispose.
+    void this.resetWorker(active.worker).then(record => {
+      if (record.failed) {
+        result = { ...result, error: { ...result.error,
+          message: `${result.error?.message ?? 'cell could not be measured'}; helper reclamation failed: ${String(record.reason?.message ?? record.reason)}` } }
+        if (active.journal !== undefined && active.replay === undefined) {
+          this.completeJournal(active.journal, 'noop', result)
+        }
+      }
+      active.finish(result)
+    })
+  }
+
   settleCell(active, result, terminate = false) {
     /* c8 ignore next */
     if (this.active !== active) return
     active.settled = true
+    // Any cell that settles on a normal path disproves the sequence of cells that
+    // never reached the runtime, whichever way it ended.
+    this.unmeasuredCells = 0
     const { request, journal, replay, worker } = active
     clearInterval(active.computeTimer)
     clearTimeout(active.wallTimer)
@@ -477,6 +1133,7 @@ class SessionKernel {
         const status = active.durability.status
         this.completeJournal(
           journal, status, result, active.durability.reason, active.diagnostics, active.completion,
+          active.bindingValues,
         )
         this.tentatives.set(journal, {
           callSeq: request.callSeq,
@@ -495,7 +1152,8 @@ class SessionKernel {
       // A live cell establishes this worker's timeline even when historical
       // replay was disabled. Only a reset may reopen its recovery boundary.
       this.replayed = true
-      this.liveCallSeqs.add(request.callSeq ?? request.sourceCallSeq)
+      const ownSeq = request.callSeq ?? request.sourceCallSeq
+      this.liveCallSeqs.add(ownSeq)
     }
     this.active = undefined
     if (terminate) {
@@ -671,7 +1329,7 @@ function sessionOf(sessionContext) {
  * and contract the durable frontier. Zero-argument calls keep their recorded
  * empty-object form so the args wire still matches the journal.
  */
-function replayBindingNamespaces(namespaces, journal, limits, emptyArgsWire) {
+export function replayBindingNamespaces(namespaces, journal, limits, emptyArgsWire) {
   const calls = journal?.calls ?? []
   let changed = false
   const next = namespaces.map(namespace => {
@@ -702,6 +1360,15 @@ export class SessionRuntime {
   constructor(config = {}, options = {}) {
     this.config = resolvedRuntimeConfig(config)
     this.kernels = new Map()
+    // Identities whose owning session was disposed. Their environment is gone by
+    // contract, so a later cell in the same identity must start empty instead of
+    // replaying bindings the disposed owner once held.
+    this.disposedSessions = new Set()
+    // Identities whose Agent was disposed. An Agent owns the live environment,
+    // not the session's durable journal: releasing it ends the worker and every
+    // live-only (volatile) value it observed, while the durable computation the
+    // log proves still replays for the identity that continues the session.
+    this.releasedAgents = new Set()
     this.pendingNoops = new Map()
     this.settlements = new WeakSet()
     this.preparingCells = new Set()
@@ -770,7 +1437,8 @@ export class SessionRuntime {
         kernel.surfaceGeneration = surfaceGeneration(session)
       } else {
         const timeline = foldSessionTimeline(observed.events)
-        const history = recoverJournal(observed, undefined, { visibleCallSeqs: visible })
+        const history = recoverJournal(observed, undefined, { visibleCallSeqs: visible,
+          editRewritesHistory: this.config.editRewritesHistory === true })
         const head = history.nodes[history.head]
         if (head === undefined) return unavailableReplMemorySnapshot()
         // A cold inventory can describe a proved recorded frontier without
@@ -850,21 +1518,40 @@ export class SessionRuntime {
     }
     let kernel = this.kernels.get(sessionId)
     if (kernel === undefined) {
+      // A disposed session loses its environment by contract: the next cell in
+      // that identity starts empty and is told how many historical cells the
+      // disposed environment held. Replaying them would hand the disposed
+      // owner's bindings to whoever runs next in the same identity.
+      const disposedCells = this.disposedSessions.has(sessionId)
+        ? disposedHistoryCells(sessionLog, callSeq)
+        : 0
+      // A released Agent owns only the live environment, so the durable journal
+      // still replays; the live-only values that environment observed do not.
+      const liveOnlyLost = this.releasedAgents.has(sessionId)
       let history
       try {
-        history = cellConfig.durableReplay
-          ? recoverJournal(sessionLog, callSeq, {
+        history = disposedCells > 0 || !cellConfig.durableReplay
+          ? emptyHistory()
+          : recoverJournal(sessionLog, callSeq, {
             visibleCallSeqs: visibleExecutableCallSeqs(sessionLog),
+            editRewritesHistory: cellConfig.editRewritesHistory === true,
+            ...(liveOnlyLost ? { liveOnlyLost: true } : {}),
           })
-          : emptyHistory()
       } catch (error) {
         // Malformed PTC metadata is contracted by the ordered recovery owner.
         // Failure to read DSH's session source cannot prove a reset boundary.
         return completed({ logs: [], error: { kind: 'recovery', message: `cannot reconstruct REPL from session log: ${messageOf(error)}` } })
       }
+      // One release is one fact about the environment that held it: the
+      // environment built below owns its own live values again.
+      if (liveOnlyLost) this.releasedAgents.delete(sessionId)
       kernel = new SessionKernel({
-        config: cellConfig,
+        // The kernel owns the worker and the sessions it serves, so it takes the
+        // configuration current when the session starts; this cell's own budgets
+        // still come from the submitted snapshot passed to run().
+        config: this.config,
         history,
+        disposedCells,
         cwd,
         session,
         surfaceProvenanceRequired,
@@ -938,6 +1625,27 @@ export class SessionRuntime {
 
   async disposeSession(sessionId) {
     const id = String(sessionId)
+    // Recorded before the early return: an identity whose owning session was
+    // disposed has no environment to resume, whether or not a kernel still
+    // existed here.
+    this.disposedSessions.add(id)
+    return this.#releaseKernel(id)
+  }
+
+  /**
+   * End the live environment of one Agent while keeping the session's journal.
+   *
+   * The Agent, not the session, owns the worker: a replaced Agent in the same
+   * session continues the computation the log proves, and loses only the
+   * live-only values its predecessor observed.
+   */
+  async disposeAgent(sessionId) {
+    const id = String(sessionId)
+    this.releasedAgents.add(id)
+    return this.#releaseKernel(id)
+  }
+
+  async #releaseKernel(id) {
     for (const admission of this.preparingCells) {
       if (admission.sessionId === id) {
         admission.cancelled = true