@jkwd/inbase 0.1.9 → 0.1.11

package/apps/explorer/scripts/session-store.mjs

@@ -1,5 +1,6 @@
 import fs from 'node:fs'
 import path from 'node:path'
+import crypto from 'node:crypto'
 import { spawnSync } from 'node:child_process'
 import {
   accumulatePatchAdditions,
@@ -10,6 +11,7 @@ import {
   foldersFromFileIds,
   parseUnifiedPatch,
 } from './patch-lib.mjs'
+import { diffSourceTrees, snapshotSourceTree } from './tree-diff.mjs'
 
 const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
 const CONNECTED_TTL_MS = 15_000
@@ -39,6 +41,19 @@ function atomicWrite(file, contents) {
   fs.renameSync(temporary, file)
 }
 
+function featureName(value) {
+  const trimmed = typeof value === 'string' ? value.trim() : ''
+  return trimmed
+}
+
+function sessionName(value) {
+  return featureName(value)
+}
+
+function resolvedSessionName(manifest) {
+  return sessionName(manifest?.name) || sessionName(manifest?.feature)
+}
+
 export function sessionPaths(dataDir, sessionId) {
   const safeId = assertSessionId(sessionId)
   const root = path.join(dataDir, 'diff-sessions', safeId)
@@ -49,6 +64,7 @@ export function sessionPaths(dataDir, sessionId) {
     blueprint: path.join(root, 'blueprint.json'),
     baseline: path.join(root, 'baseline.json'),
     baselineFiles: path.join(root, 'baseline'),
+    preStep: path.join(root, 'pre-step'),
     stopped: path.join(dataDir, 'diff-sessions', `${safeId}.stopped`),
   }
 }
@@ -124,6 +140,38 @@ function connectionFile(dataDir, sessionId) {
   return path.join(sessionPaths(dataDir, sessionId).root, 'connected.json')
 }
 
+function ackFile(dataDir, sessionId) {
+  return path.join(sessionPaths(dataDir, sessionId).root, 'ack.json')
+}
+
+export function recordSessionAck(dataDir, sessionId, kind, detail = '') {
+  const safeId = assertSessionId(sessionId)
+  if (isSessionStopped(dataDir, safeId) && kind !== 'stopped' && kind !== 'finished') {
+    return null
+  }
+  const payload = {
+    kind: String(kind),
+    detail: String(detail ?? ''),
+    at: new Date().toISOString(),
+  }
+  try {
+    atomicWrite(ackFile(dataDir, safeId), `${JSON.stringify(payload, null, 2)}\n`)
+  } catch {
+    return null
+  }
+  return payload
+}
+
+function readSessionAck(dataDir, sessionId) {
+  const value = readJson(ackFile(dataDir, sessionId), null)
+  if (!value || typeof value.kind !== 'string' || value.kind.trim() === '') return null
+  return {
+    kind: value.kind,
+    detail: typeof value.detail === 'string' ? value.detail : '',
+    at: typeof value.at === 'string' ? value.at : null,
+  }
+}
+
 function isFreshTimestamp(value, now = Date.now()) {
   if (typeof value !== 'string') return false
   const at = Date.parse(value)
@@ -137,6 +185,11 @@ export function touchSessionConnection(dataDir, sessionId) {
     connectionFile(dataDir, safeId),
     `${JSON.stringify({ sessionId: safeId, connectedAt: new Date().toISOString() }, null, 2)}\n`,
   )
+  const manifest = readManifest(dataDir, safeId)
+  if (manifest?.awaitingAttach) {
+    manifest.awaitingAttach = false
+    writeManifest(dataDir, manifest)
+  }
 }
 
 function waiterSessionIds() {
@@ -171,6 +224,16 @@ function isGeneratingPhase(phase) {
   return phase === 'preparing' || phase === 'working' || phase === 'replanning'
 }
 
+function isTerminalSession(manifest) {
+  return (
+    !manifest ||
+    manifest.phase === 'finished' ||
+    manifest.phase === 'stopped' ||
+    manifest.status === 'finished' ||
+    manifest.status === 'rejected'
+  )
+}
+
 function isStalledWorking(manifest, waiterIds, sessionId, now = Date.now()) {
   if (manifest.phase !== 'working') return false
   if (!waiterIds.has(sessionId)) return false
@@ -185,19 +248,13 @@ export function isSessionConnected(
 ) {
   const safeId = assertSessionId(sessionId)
   const manifest = readManifest(dataDir, safeId)
-  if (!manifest) return false
-  if (
-    manifest.phase === 'finished' ||
-    manifest.phase === 'stopped' ||
-    manifest.status === 'finished' ||
-    manifest.status === 'rejected'
-  ) {
-    return false
-  }
-  if (isGeneratingPhase(manifest.phase)) return true
-  if (waiterIds.has(safeId)) return true
+  if (isTerminalSession(manifest)) return false
   const connected = readJson(connectionFile(dataDir, safeId), null)
-  if (isFreshTimestamp(connected?.connectedAt)) return true
+  const heartbeat =
+    waiterIds.has(safeId) || isFreshTimestamp(connected?.connectedAt)
+  if (manifest.awaitingAttach) return heartbeat
+  if (isGeneratingPhase(manifest.phase)) return true
+  if (heartbeat) return true
   return isFreshTimestamp(manifest.updatedAt) || isFreshTimestamp(manifest.createdAt)
 }
 
@@ -232,9 +289,8 @@ export function listOpenSessionIds(dataDir, waiterIds = waiterSessionIds()) {
     if (!entry.isDirectory()) continue
     try {
       const sessionId = assertSessionId(entry.name)
-      if (!isSessionConnected(dataDir, sessionId, waiterIds)) continue
       const manifest = readManifest(dataDir, sessionId)
-      if (!manifest) continue
+      if (isTerminalSession(manifest)) continue
       sessions.push({
         sessionId,
         createdAt: typeof manifest.createdAt === 'string' ? manifest.createdAt : '',
@@ -273,32 +329,34 @@ export function writeBlueprintSession(dataDir, sessionId) {
   )
 }
 
-function assertBlueprintSessionAvailable(dataDir, sessionId) {
+function releaseBlueprintSession(dataDir, sessionId) {
   const safeId = assertSessionId(sessionId)
-  const locked = readBlueprintSession(dataDir)
-  if (locked && locked !== safeId) {
-    throw new Error(
-      `Blueprint edit mode is active in session ${locked}. Finish or stop it before starting another.`,
-    )
-  }
-  return safeId
+  if (readBlueprintSession(dataDir) === safeId) writeBlueprintSession(dataDir, null)
 }
 
-function claimBlueprintSession(dataDir, sessionId) {
-  const safeId = assertBlueprintSessionAvailable(dataDir, sessionId)
-  writeBlueprintSession(dataDir, safeId)
+export function focusSession(dataDir, sessionId) {
+  const safeId = assertSessionId(sessionId)
+  requireManifest(dataDir, safeId)
+  writeActiveSession(dataDir, safeId)
   return safeId
 }
 
-function releaseBlueprintSession(dataDir, sessionId) {
-  const safeId = assertSessionId(sessionId)
-  if (readBlueprintSession(dataDir) === safeId) writeBlueprintSession(dataDir, null)
+function sessionAllowsPlacement(manifest) {
+  return (
+    manifest.phase !== 'blueprint_ask' &&
+    manifest.phase !== 'finished' &&
+    manifest.phase !== 'stopped'
+  )
 }
 
-function focusSession(dataDir, sessionId) {
-  const safeId = assertSessionId(sessionId)
-  const locked = readBlueprintSession(dataDir)
-  if (!locked || locked === safeId) writeActiveSession(dataDir, safeId)
+function blueprintHasContent(blueprint) {
+  return (
+    (blueprint.userCreatedBlocks?.length ?? 0) > 0 ||
+    (blueprint.userCreatedIslands?.length ?? 0) > 0 ||
+    (blueprint.addedFunctions?.length ?? 0) > 0 ||
+    (blueprint.addedVariables?.length ?? 0) > 0 ||
+    (blueprint.addedImports?.length ?? 0) > 0
+  )
 }
 
 export function readManifest(dataDir, sessionId) {
@@ -324,6 +382,8 @@ export function readManifest(dataDir, sessionId) {
     value.workStartedAt ??= null
   }
   if (typeof value.stepByStep !== 'boolean') value.stepByStep = true
+  value.initialInstruction =
+    typeof value.initialInstruction === 'string' ? value.initialInstruction : null
   return value
 }
 
@@ -353,13 +413,34 @@ export function chainThrough(manifest, diffId = manifest.activeDiffId) {
   return manifest.diffs.slice(0, entryIndex(manifest, diffId) + 1)
 }
 
-function unresolvedEntries(manifest, diffId = manifest.activeDiffId) {
+function isSupersededPatch(entry) {
+  return (
+    entry.status === 'rejected' ||
+    entry.status === 'extend' ||
+    entry.status === 'extended'
+  )
+}
+
+function liveEntries(manifest, diffId) {
   const chain = chainThrough(manifest, diffId)
-  let lastApplied = -1
-  chain.forEach((entry, index) => {
-    if (entry.status === 'applied') lastApplied = index
+  if (chain.length === 0) return []
+  const selected = chain.at(-1)
+  const browsingHistory = selected.id !== manifest.activeDiffId
+  return chain.filter((entry) => {
+    if (entry.status === 'rejected') return false
+    if (entry.status === 'extended' || entry.status === 'extend') {
+      return browsingHistory && entry.id === selected.id
+    }
+    return true
   })
-  return chain.slice(lastApplied + 1).filter((entry) => entry.status !== 'rejected')
+}
+
+function workingPatchEntries(manifest) {
+  return manifest.diffs.filter((entry) => !isSupersededPatch(entry))
+}
+
+function unresolvedEntries(manifest, diffId = manifest.activeDiffId) {
+  return liveEntries(manifest, diffId).filter((entry) => entry.status !== 'applied')
 }
 
 export function previewPatchChain(patches, knownFileIds = []) {
@@ -444,10 +525,9 @@ export function sessionIntent(
   const patches =
     selectedIndex === null
       ? []
-      : manifest.diffs
-          .slice(0, selectedIndex + 1)
-          .filter((entry) => entry.status !== 'rejected')
-          .map((entry) => readDiff(dataDir, sessionId, entry))
+      : liveEntries(manifest, selectedId).map((entry) =>
+          readDiff(dataDir, sessionId, entry),
+        )
   const preview = previewPatchChain(patches, knownFileIds)
   const activeView = !selectedDiffId || selectedId === manifest.activeDiffId
   const phaseStatus = {
@@ -470,18 +550,19 @@ export function sessionIntent(
   )
   const previewVisible = patches.length > 0
   const blueprint = readBlueprint(dataDir, sessionId)
-  const blueprintSessionId = readBlueprintSession(dataDir)
-  const ownsBlueprintLock = blueprintSessionId === sessionId
-  const canEnterBlueprint =
-    manifest.phase === 'blueprint_ask' &&
-    (!blueprintSessionId || ownsBlueprintLock)
+  const canEnterBlueprint = manifest.phase === 'blueprint_ask'
 
   return {
     updatedAt: manifest.updatedAt,
     showMap: previewVisible,
     status: activeView ? phaseStatus ?? historicalStatus : historicalStatus,
     phase: manifest.phase,
+    name: resolvedSessionName(manifest) || null,
     feature: manifest.feature,
+    initialInstruction:
+      typeof manifest.initialInstruction === 'string'
+        ? manifest.initialInstruction
+        : null,
     steps: manifest.steps,
     step: activeView ? manifest.currentStep : selected?.step ?? manifest.currentStep,
     stepByStep: isStepByStep(manifest),
@@ -500,13 +581,20 @@ export function sessionIntent(
     isActiveDiff: Boolean(selected && selected.id === manifest.activeDiffId),
     preview: previewVisible,
     working:
-      manifest.phase === 'preparing' ||
-      manifest.phase === 'working' ||
-      manifest.phase === 'replanning',
+      !manifest.awaitingAttach &&
+      (manifest.phase === 'preparing' ||
+        manifest.phase === 'working' ||
+        manifest.phase === 'replanning'),
     stalledWait: isStalledWorking(manifest, waiterIds, sessionId),
-    creationMode: manifest.phase === 'blueprint' && ownsBlueprintLock,
+    llmIdle: !isSessionConnected(dataDir, sessionId, waiterIds),
+    awaitingAttach:
+      Boolean(manifest.awaitingAttach) &&
+      !isSessionConnected(dataDir, sessionId, waiterIds),
+    listening: waiterIds.has(sessionId),
+    lastAck: readSessionAck(dataDir, sessionId),
+    creationMode: sessionAllowsPlacement(manifest),
     canEnterBlueprint,
-    blueprintSessionId,
+    blueprintSessionId: null,
     userCreatedBlocks: blueprint.userCreatedBlocks,
     userCreatedIslands: blueprint.userCreatedIslands,
     ...preview,
@@ -639,10 +727,6 @@ function unstagePaths(fromDir, absolutePaths) {
   }
 }
 
-function liveEntries(manifest, diffId) {
-  return chainThrough(manifest, diffId).filter((entry) => entry.status !== 'rejected')
-}
-
 export function materializeDiff(dataDir, targetRoot, sessionId, diffId) {
   const manifest = requireManifest(dataDir, sessionId)
   const through = diffId || manifest.activeDiffId
@@ -682,9 +766,9 @@ function loadReplayContents(dataDir, sessionId, targetRoot, patches) {
 }
 
 export function validateContinuation(dataDir, manifest, targetRoot, patchText) {
-  const prior = manifest.diffs
-    .filter((entry) => entry.status !== 'rejected')
-    .map((entry) => readDiff(dataDir, manifest.sessionId, entry))
+  const prior = workingPatchEntries(manifest).map((entry) =>
+    readDiff(dataDir, manifest.sessionId, entry),
+  )
   const patches = [...prior, patchText]
   const files = loadReplayContents(
     dataDir,
@@ -722,11 +806,6 @@ function planSteps(titles, startAt = 1) {
   })
 }
 
-function featureName(value) {
-  const trimmed = typeof value === 'string' ? value.trim() : ''
-  return trimmed
-}
-
 export function isStepByStep(manifest) {
   return manifest?.stepByStep !== false
 }
@@ -758,7 +837,12 @@ export function startSession(dataDir, input) {
   const sessionId = assertSessionId(input.sessionId)
   clearStoppedMarker(dataDir, sessionId)
   const existing = readManifest(dataDir, sessionId)
+  const name = sessionName(input.name) || sessionName(input.feature)
   if (existing) {
+    if (name && existing.name !== name) {
+      existing.name = name
+      writeManifest(dataDir, existing)
+    }
     focusSession(dataDir, sessionId)
     return existing
   }
@@ -767,7 +851,8 @@ export function startSession(dataDir, input) {
   const manifest = {
     version: 2,
     sessionId,
-    feature: featureName(input.feature),
+    name,
+    feature: featureName(input.feature) || name,
     steps: [],
     status: 'active',
     phase: 'blueprint_ask',
@@ -775,6 +860,7 @@ export function startSession(dataDir, input) {
     currentStep: 1,
     activeDiffId: null,
     pendingInstruction: null,
+    initialInstruction: null,
     workStartedAt: null,
     createdAt: now,
     updatedAt: now,
@@ -786,12 +872,120 @@ export function startSession(dataDir, input) {
   return manifest
 }
 
+export function setupSession(dataDir, input = {}) {
+  const sessionId = input.sessionId
+    ? assertSessionId(input.sessionId)
+    : generateVisualizerSessionId(dataDir)
+  const existing = readManifest(dataDir, sessionId)
+  if (existing && !isTerminalSession(existing)) {
+    throw new Error(`Session ${sessionId} already exists`)
+  }
+  if (existing) {
+    discardStoredSession(dataDir, sessionId, null, { restore: false })
+  }
+  clearStoppedMarker(dataDir, sessionId)
+  const now = new Date().toISOString()
+  const name = sessionName(input.name)
+  const manifest = {
+    version: 2,
+    sessionId,
+    name,
+    feature: featureName(input.feature) || name,
+    steps: [],
+    status: 'active',
+    phase: 'blueprint',
+    awaitingAttach: true,
+    stepByStep: true,
+    currentStep: 1,
+    activeDiffId: null,
+    pendingInstruction: null,
+    initialInstruction: null,
+    workStartedAt: null,
+    createdAt: now,
+    updatedAt: now,
+    diffs: [],
+  }
+  writeManifest(dataDir, manifest)
+  writeBlueprint(dataDir, sessionId, {
+    ...emptyBlueprint(),
+    enabled: true,
+    sent: false,
+  })
+  focusSession(dataDir, sessionId)
+  return manifest
+}
+
+export function setInitialInstruction(dataDir, sessionId, instruction) {
+  const manifest = requireManifest(dataDir, sessionId)
+  if (isTerminalSession(manifest)) {
+    throw sessionStoppedError(sessionId)
+  }
+  const text = typeof instruction === 'string' ? instruction : ''
+  if (text.length > 4000) {
+    throw new Error('instruction must be a string up to 4000 characters')
+  }
+  const next = text.trim() === '' ? null : text
+  if ((manifest.initialInstruction ?? null) === next) return manifest
+  manifest.initialInstruction = next
+  writeManifest(dataDir, manifest)
+  return manifest
+}
+
+function generateVisualizerSessionId(dataDir) {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const sessionId = `viz-${crypto.randomBytes(6).toString('hex')}`
+    if (!readManifest(dataDir, sessionId) && !isSessionStopped(dataDir, sessionId)) {
+      return sessionId
+    }
+  }
+  throw new Error('Could not allocate a visualizer session id')
+}
+
+export function readAttachedSession(dataDir) {
+  for (const sessionId of listOpenSessionIds(dataDir)) {
+    const manifest = readManifest(dataDir, sessionId)
+    if (manifest?.awaitingAttach === false) return sessionId
+  }
+  return null
+}
+
+export function attachSession(dataDir, sessionId) {
+  const safeId = sessionId
+    ? assertSessionId(sessionId)
+    : readActiveSession(dataDir)
+  if (!safeId) {
+    throw new Error(
+      'No visualizer session is focused. Click Setup LLM session in the map, then /inbase.',
+    )
+  }
+  const manifest = requireManifest(
+    dataDir,
+    safeId,
+    `No visualizer session ${safeId}. Click Setup LLM session in the map, then /inbase.`,
+  )
+  if (isTerminalSession(manifest)) {
+    throw sessionStoppedError(safeId)
+  }
+  const attached = readAttachedSession(dataDir)
+  if (attached && attached !== safeId) {
+    const other = readManifest(dataDir, attached)
+    const label = resolvedSessionName(other) || attached
+    throw new Error(
+      `An LLM is already attached to ${label}. Stop that session before attaching another.`,
+    )
+  }
+  focusSession(dataDir, safeId)
+  touchSessionConnection(dataDir, safeId)
+  recordSessionAck(dataDir, safeId, 'attached', resolvedSessionName(manifest) || safeId)
+  maybeStartVisualizerHandshake(dataDir, safeId)
+  return readManifest(dataDir, safeId) ?? manifest
+}
+
 export function answerBlueprint(dataDir, sessionId, enabled) {
   const manifest = requireManifest(dataDir, sessionId)
   if (manifest.phase !== 'blueprint_ask') {
     throw new Error(`Session ${sessionId} is not asking for a blueprint`)
   }
-  if (enabled) claimBlueprintSession(dataDir, sessionId)
   const blueprint = {
     ...emptyBlueprint(),
     enabled: Boolean(enabled),
@@ -807,20 +1001,22 @@ export function answerBlueprint(dataDir, sessionId, enabled) {
 export function updateBlueprint(dataDir, sessionId, input = {}) {
   const safeId = assertSessionId(sessionId)
   const manifest = requireManifest(dataDir, safeId)
-  if (manifest.phase !== 'blueprint') {
-    throw new Error(`Session ${safeId} is not in blueprint mode`)
+  if (!sessionAllowsPlacement(manifest)) {
+    throw new Error(`Session ${safeId} is not accepting blueprint edits`)
   }
-  assertBlueprintSessionAvailable(dataDir, safeId)
   const current = readBlueprint(dataDir, safeId)
-  writeBlueprint(dataDir, safeId, {
+  const next = {
     ...current,
-    enabled: true,
-    sent: false,
     userCreatedBlocks: input.userCreatedBlocks ?? current.userCreatedBlocks,
     userCreatedIslands: input.userCreatedIslands ?? current.userCreatedIslands,
     addedFunctions: input.addedFunctions ?? current.addedFunctions,
     addedVariables: input.addedVariables ?? current.addedVariables,
     addedImports: input.addedImports ?? current.addedImports,
+  }
+  writeBlueprint(dataDir, safeId, {
+    ...next,
+    enabled: current.enabled || blueprintHasContent(next),
+    sent: manifest.phase === 'blueprint' ? false : current.sent,
   })
   return readBlueprint(dataDir, safeId)
 }
@@ -831,16 +1027,37 @@ export function sendBlueprint(dataDir, sessionId, input = {}) {
   if (manifest.phase !== 'blueprint') {
     throw new Error(`Session ${safeId} is not in blueprint mode`)
   }
-  assertBlueprintSessionAvailable(dataDir, safeId)
   const current = readBlueprint(dataDir, safeId)
-  writeBlueprint(dataDir, safeId, {
-    enabled: true,
-    sent: true,
+  const next = {
     userCreatedBlocks: input.userCreatedBlocks ?? current.userCreatedBlocks,
     userCreatedIslands: input.userCreatedIslands ?? current.userCreatedIslands,
     addedFunctions: input.addedFunctions ?? current.addedFunctions,
     addedVariables: input.addedVariables ?? current.addedVariables,
     addedImports: input.addedImports ?? current.addedImports,
+  }
+  writeBlueprint(dataDir, safeId, {
+    ...next,
+    enabled: blueprintHasContent(next),
+    sent: true,
+  })
+  manifest.phase = 'preparing'
+  manifest.workStartedAt = new Date().toISOString()
+  writeManifest(dataDir, manifest)
+  releaseBlueprintSession(dataDir, safeId)
+  return manifest
+}
+
+export function maybeStartVisualizerHandshake(dataDir, sessionId) {
+  const safeId = assertSessionId(sessionId)
+  const manifest = requireManifest(dataDir, safeId)
+  if (manifest.phase !== 'blueprint_ask' && manifest.phase !== 'blueprint') {
+    return manifest
+  }
+  const current = readBlueprint(dataDir, safeId)
+  writeBlueprint(dataDir, safeId, {
+    ...current,
+    enabled: blueprintHasContent(current),
+    sent: true,
   })
   manifest.phase = 'preparing'
   manifest.workStartedAt = new Date().toISOString()
@@ -867,6 +1084,7 @@ export function reportPlan(dataDir, input) {
     const manifest = existing ?? {
       version: 2,
       sessionId,
+      name: sessionName(input.name) || sessionName(input.feature),
       feature: input.feature,
       steps: [],
       status: 'active',
@@ -875,11 +1093,15 @@ export function reportPlan(dataDir, input) {
       currentStep: 1,
       activeDiffId: null,
       pendingInstruction: null,
+      initialInstruction: null,
       workStartedAt: null,
       createdAt: now,
       updatedAt: now,
       diffs: [],
     }
+    if (!sessionName(manifest.name)) {
+      manifest.name = sessionName(input.feature)
+    }
     manifest.feature = input.feature
     manifest.steps = planSteps(input.stepTitles)
     manifest.status = 'active'
@@ -888,7 +1110,13 @@ export function reportPlan(dataDir, input) {
     manifest.workStartedAt = null
     writeManifest(dataDir, manifest)
     focusSession(dataDir, sessionId)
-    return autoAdvance(dataDir, sessionId)
+    recordSessionAck(
+      dataDir,
+      sessionId,
+      'plan',
+      `${manifest.steps.length} step(s)`,
+    )
+    return autoAdvance(dataDir, sessionId, input.targetRoot)
   }
 
   if (existing.phase !== 'replanning') {
@@ -905,7 +1133,13 @@ export function reportPlan(dataDir, input) {
   existing.workStartedAt = null
   writeManifest(dataDir, existing)
   focusSession(dataDir, sessionId)
-  return autoAdvance(dataDir, sessionId)
+  recordSessionAck(
+    dataDir,
+    sessionId,
+    'plan',
+    `${existing.steps.filter((step) => step.index >= startAt).length} step(s)`,
+  )
+  return autoAdvance(dataDir, sessionId, input.targetRoot)
 }
 
 export function invokeStep(dataDir, sessionId, step, targetRoot = null) {
@@ -919,8 +1153,8 @@ export function invokeStep(dataDir, sessionId, step, targetRoot = null) {
     if (step !== expected) {
       throw new Error(
         last
-          ? `Run step ${active.step} to finish`
-          : `Run step ${expected} to continue`,
+          ? `Accept proposal on step ${active.step} to finish`
+          : `Accept proposal on step ${active.step} to continue`,
       )
     }
     applyUnresolved(dataDir, targetRoot, manifest, active.id)
@@ -945,9 +1179,33 @@ export function invokeStep(dataDir, sessionId, step, targetRoot = null) {
   manifest.phase = 'working'
   manifest.workStartedAt = new Date().toISOString()
   writeManifest(dataDir, manifest)
+  const title = manifest.steps.find((item) => item.index === step)?.title
+  recordSessionAck(
+    dataDir,
+    sessionId,
+    'invoke',
+    title ? `step ${step} — ${title}` : `step ${step}`,
+  )
+  if (targetRoot) snapshotPreStep(dataDir, sessionId, targetRoot)
   return manifest
 }
 
+export function snapshotPreStep(dataDir, sessionId, targetRoot) {
+  const { preStep } = sessionPaths(dataDir, sessionId)
+  snapshotSourceTree(targetRoot, preStep)
+  return preStep
+}
+
+export function readLiveDiff(dataDir, sessionId, targetRoot) {
+  const { preStep } = sessionPaths(dataDir, sessionId)
+  if (!fs.existsSync(preStep)) {
+    throw new Error(
+      `Step ${sessionId} has no invoke snapshot. Wait for VISUAL_CODER_EXECUTE before recording file changes.`,
+    )
+  }
+  return diffSourceTrees(preStep, targetRoot)
+}
+
 export function appendDiff(dataDir, targetRoot, input) {
   const sessionId = assertSessionId(input.sessionId)
   const manifest = requireManifest(
@@ -974,12 +1232,19 @@ export function appendDiff(dataDir, targetRoot, input) {
     throw new Error(`The next diff must implement step ${parent.step + 1}`)
   }
 
-  validateContinuation(dataDir, manifest, targetRoot, input.patchText)
+  const patchText = input.patchText ?? readLiveDiff(dataDir, sessionId, targetRoot)
+  if (!patchText.trim()) {
+    throw new Error('No file changes to record for this step')
+  }
+
+  const snapshotRoot = sessionPaths(dataDir, sessionId).preStep
+  const originRoot = fs.existsSync(snapshotRoot) ? snapshotRoot : targetRoot
+  validateContinuation(dataDir, manifest, originRoot, patchText)
   captureBaseline(
     dataDir,
     sessionId,
-    targetRoot,
-    parseUnifiedPatch(input.patchText).entries.map((entry) => entry.id),
+    originRoot,
+    parseUnifiedPatch(patchText).entries.map((entry) => entry.id),
   )
   if (parent?.status === 'extend') parent.status = 'extended'
 
@@ -1000,7 +1265,7 @@ export function appendDiff(dataDir, targetRoot, input) {
   fs.mkdirSync(paths.diffs, { recursive: true })
   atomicWrite(
     path.join(paths.root, file),
-    input.patchText.endsWith('\n') ? input.patchText : `${input.patchText}\n`,
+    patchText.endsWith('\n') ? patchText : `${patchText}\n`,
   )
   manifest.activeDiffId = id
   manifest.phase = 'review'
@@ -1061,7 +1326,13 @@ export function continueDiff(dataDir, targetRoot, sessionId, diffId) {
   return autoAdvance(dataDir, sessionId, targetRoot)
 }
 
-export function requestReplan(dataDir, sessionId, diffId, instruction) {
+export function requestReplan(
+  dataDir,
+  sessionId,
+  diffId,
+  instruction,
+  targetRoot = null,
+) {
   const manifest = requireManifest(dataDir, sessionId)
   const active = pendingActive(manifest, diffId)
   const guidance = typeof instruction === 'string' ? instruction.trim() : ''
@@ -1073,6 +1344,7 @@ export function requestReplan(dataDir, sessionId, diffId, instruction) {
   manifest.pendingInstruction = guidance
   manifest.workStartedAt = new Date().toISOString()
   writeManifest(dataDir, manifest)
+  if (targetRoot) materializeDiff(dataDir, targetRoot, sessionId, active.id)
   return manifest
 }
 
@@ -1139,13 +1411,16 @@ export function discardInactiveDiffSessions(
   }
 
   for (const sessionId of listStoredSessionIds(dataDir)) {
-    const live = keep.has(sessionId) && Boolean(readManifest(dataDir, sessionId))
+    const manifest = readManifest(dataDir, sessionId)
+    if (!isTerminalSession(manifest)) continue
     const stopping = keep.has(sessionId) && isSessionStopped(dataDir, sessionId)
-    if (live || stopping) continue
+    if (stopping) continue
     discardStoredSession(dataDir, sessionId, targetRoot)
   }
 
-  const liveIds = [...keep].filter((id) => readManifest(dataDir, id))
+  const liveIds = listStoredSessionIds(dataDir).filter(
+    (id) => !isTerminalSession(readManifest(dataDir, id)),
+  )
   const active = readActiveSession(dataDir)
   if (active && !liveIds.includes(active)) writeActiveSession(dataDir, null)
   const locked = readBlueprintSession(dataDir)
@@ -1170,6 +1445,12 @@ export function clearDiffSessions(dataDir, targetRoot = null) {
   unstageDiffSessionArtifacts(dataDir, targetRoot)
 }
 
+export function recoverOpenDiffSessions(dataDir, targetRoot = null) {
+  // Visualizer startup never reopens an LLM session.
+  clearDiffSessions(dataDir, targetRoot)
+  return []
+}
+
 export function stopSession(dataDir, sessionId, targetRoot = null) {
   const safeId = assertSessionId(sessionId)
   writeStoppedMarker(dataDir, safeId)
@@ -1192,7 +1473,7 @@ export function decideDiff(
     return continueDiff(dataDir, targetRoot, sessionId, diffId)
   }
   if (decision === 'extend') {
-    return requestReplan(dataDir, sessionId, diffId, instruction)
+    return requestReplan(dataDir, sessionId, diffId, instruction, targetRoot)
   }
   return stopSession(dataDir, sessionId, targetRoot)
 }