@jkwd/inbase 0.1.4 → 0.1.6

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

@@ -1,9 +1,10 @@
 import fs from 'node:fs'
-import os from 'node:os'
 import path from 'node:path'
+import { spawnSync } from 'node:child_process'
 import {
   accumulatePatchAdditions,
   applyUnifiedPatch,
+  applyUnifiedPatchToContents,
   collectCreateFolders,
   extractPatchImports,
   foldersFromFileIds,
@@ -11,6 +12,8 @@ import {
 } from './patch-lib.mjs'
 
 const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+const CONNECTED_TTL_MS = 15_000
+const STALLED_WAIT_MS = 2_000
 
 export function assertSessionId(value) {
   if (typeof value !== 'string' || !SESSION_ID.test(value) || value === '.' || value === '..') {
@@ -46,9 +49,48 @@ export function sessionPaths(dataDir, sessionId) {
     blueprint: path.join(root, 'blueprint.json'),
     baseline: path.join(root, 'baseline.json'),
     baselineFiles: path.join(root, 'baseline'),
+    stopped: path.join(dataDir, 'diff-sessions', `${safeId}.stopped`),
   }
 }
 
+export function sessionStoppedError(sessionId) {
+  return new Error(
+    `VISUAL_CODER_STOPPED Session ${assertSessionId(sessionId)} was stopped. Do not modify project files.`,
+  )
+}
+
+export function isSessionStopped(dataDir, sessionId) {
+  return fs.existsSync(sessionPaths(dataDir, sessionId).stopped)
+}
+
+export function isWorkflowStopped(dataDir, sessionId) {
+  const safeId = assertSessionId(sessionId)
+  const manifest = readManifest(dataDir, safeId)
+  if (manifest?.phase === 'stopped') return true
+  return !manifest && isSessionStopped(dataDir, safeId)
+}
+
+function writeStoppedMarker(dataDir, sessionId) {
+  const { stopped } = sessionPaths(dataDir, sessionId)
+  atomicWrite(
+    stopped,
+    `${JSON.stringify({ sessionId: assertSessionId(sessionId), stoppedAt: new Date().toISOString() }, null, 2)}\n`,
+  )
+}
+
+function clearStoppedMarker(dataDir, sessionId) {
+  const { stopped } = sessionPaths(dataDir, sessionId)
+  if (fs.existsSync(stopped)) fs.unlinkSync(stopped)
+}
+
+function requireManifest(dataDir, sessionId, missingMessage) {
+  const safeId = assertSessionId(sessionId)
+  const manifest = readManifest(dataDir, safeId)
+  if (manifest) return manifest
+  if (isSessionStopped(dataDir, safeId)) throw sessionStoppedError(safeId)
+  throw new Error(missingMessage ?? `Unknown session ${safeId}`)
+}
+
 export function resolveTargetFile(targetRoot, fileId) {
   if (typeof fileId !== 'string' || fileId.trim() === '') {
     throw new Error('fileId is required')
@@ -78,6 +120,147 @@ export function writeActiveSession(dataDir, sessionId) {
   )
 }
 
+function connectionFile(dataDir, sessionId) {
+  return path.join(sessionPaths(dataDir, sessionId).root, 'connected.json')
+}
+
+function isFreshTimestamp(value, now = Date.now()) {
+  if (typeof value !== 'string') return false
+  const at = Date.parse(value)
+  return Number.isFinite(at) && now - at >= 0 && now - at < CONNECTED_TTL_MS
+}
+
+export function touchSessionConnection(dataDir, sessionId) {
+  const safeId = assertSessionId(sessionId)
+  if (isSessionStopped(dataDir, safeId)) return
+  atomicWrite(
+    connectionFile(dataDir, safeId),
+    `${JSON.stringify({ sessionId: safeId, connectedAt: new Date().toISOString() }, null, 2)}\n`,
+  )
+}
+
+function waiterSessionIds() {
+  try {
+    const result = spawnSync('ps', ['-ax', '-o', 'command='], {
+      encoding: 'utf8',
+    })
+    if (result.status !== 0 || !result.stdout) return new Set()
+    const ids = new Set()
+    for (const line of result.stdout.split('\n')) {
+      if (
+        !line.includes('wait-for-blueprint') &&
+        !line.includes('wait-for-approval')
+      ) {
+        continue
+      }
+      const match = line.match(/--session\s+(\S+)/)
+      if (!match) continue
+      try {
+        ids.add(assertSessionId(match[1]))
+      } catch {
+        // Ignore process command lines with invalid session ids.
+      }
+    }
+    return ids
+  } catch {
+    return new Set()
+  }
+}
+
+function isGeneratingPhase(phase) {
+  return phase === 'preparing' || phase === 'working' || phase === 'replanning'
+}
+
+function isStalledWorking(manifest, waiterIds, sessionId, now = Date.now()) {
+  if (manifest.phase !== 'working') return false
+  if (!waiterIds.has(sessionId)) return false
+  const started = Date.parse(manifest.workStartedAt)
+  return Number.isFinite(started) && now - started >= STALLED_WAIT_MS
+}
+
+export function isSessionConnected(
+  dataDir,
+  sessionId,
+  waiterIds = waiterSessionIds(),
+) {
+  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
+  const connected = readJson(connectionFile(dataDir, safeId), null)
+  if (isFreshTimestamp(connected?.connectedAt)) return true
+  return isFreshTimestamp(manifest.updatedAt) || isFreshTimestamp(manifest.createdAt)
+}
+
+function diffSessionsRoot(dataDir) {
+  return path.join(dataDir, 'diff-sessions')
+}
+
+export function listStoredSessionIds(dataDir) {
+  const root = diffSessionsRoot(dataDir)
+  if (!fs.existsSync(root)) return []
+  const ids = new Set()
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (entry.name === '.gitkeep') continue
+    const name =
+      entry.isFile() && entry.name.endsWith('.stopped')
+        ? entry.name.slice(0, -'.stopped'.length)
+        : entry.name
+    try {
+      ids.add(assertSessionId(name))
+    } catch {
+      // Skip files that are not valid session ids.
+    }
+  }
+  return [...ids]
+}
+
+export function listOpenSessionIds(dataDir, waiterIds = waiterSessionIds()) {
+  const root = diffSessionsRoot(dataDir)
+  if (!fs.existsSync(root)) return []
+  const sessions = []
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    try {
+      const sessionId = assertSessionId(entry.name)
+      if (!isSessionConnected(dataDir, sessionId, waiterIds)) continue
+      const manifest = readManifest(dataDir, sessionId)
+      if (!manifest) continue
+      sessions.push({
+        sessionId,
+        createdAt: typeof manifest.createdAt === 'string' ? manifest.createdAt : '',
+      })
+    } catch {
+      // Skip folders that are not valid session ids.
+    }
+  }
+  sessions.sort((left, right) => {
+    if (left.createdAt !== right.createdAt) {
+      return left.createdAt.localeCompare(right.createdAt)
+    }
+    return left.sessionId.localeCompare(right.sessionId)
+  })
+  return sessions.map((item) => item.sessionId)
+}
+
+export function listSessionIntents(dataDir, knownFileIds = []) {
+  const waiters = waiterSessionIds()
+  return listOpenSessionIds(dataDir, waiters)
+    .map((sessionId) =>
+      sessionIntent(dataDir, sessionId, knownFileIds, undefined, waiters),
+    )
+    .filter(Boolean)
+}
+
 export function readBlueprintSession(dataDir) {
   const value = readJson(path.join(dataDir, 'blueprint-session.json'), null)
   return value?.sessionId ? assertSessionId(value.sessionId) : null
@@ -140,6 +323,7 @@ export function readManifest(dataDir, sessionId) {
     value.pendingInstruction ??= null
     value.workStartedAt ??= null
   }
+  if (typeof value.stepByStep !== 'boolean') value.stepByStep = true
   return value
 }
 
@@ -244,7 +428,13 @@ export function previewPatchChain(patches, knownFileIds = []) {
   }
 }
 
-export function sessionIntent(dataDir, sessionId, knownFileIds = [], selectedDiffId) {
+export function sessionIntent(
+  dataDir,
+  sessionId,
+  knownFileIds = [],
+  selectedDiffId,
+  waiterIds = waiterSessionIds(),
+) {
   const manifest = readManifest(dataDir, sessionId)
   if (!manifest) return null
   const selectedId = selectedDiffId || manifest.activeDiffId
@@ -294,6 +484,7 @@ export function sessionIntent(dataDir, sessionId, knownFileIds = [], selectedDif
     feature: manifest.feature,
     steps: manifest.steps,
     step: activeView ? manifest.currentStep : selected?.step ?? manifest.currentStep,
+    stepByStep: isStepByStep(manifest),
     reason: activeView ? currentPlanStep?.title ?? null : selected?.title ?? null,
     sessionId,
     diffId: selected?.id ?? null,
@@ -312,6 +503,7 @@ export function sessionIntent(dataDir, sessionId, knownFileIds = [], selectedDif
       manifest.phase === 'preparing' ||
       manifest.phase === 'working' ||
       manifest.phase === 'replanning',
+    stalledWait: isStalledWorking(manifest, waiterIds, sessionId),
     creationMode: manifest.phase === 'blueprint' && ownsBlueprintLock,
     canEnterBlueprint,
     blueprintSessionId,
@@ -400,8 +592,51 @@ function replayPatches(dataDir, sessionId, targetRoot, entries) {
   }
 }
 
-function acceptedEntries(manifest) {
-  return manifest.diffs.filter((entry) => entry.status === 'applied')
+function gitTopLevel(fromDir) {
+  try {
+    const result = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: fromDir,
+      encoding: 'utf8',
+    })
+    if (result.status !== 0) return null
+    const root = result.stdout.trim()
+    return root ? fs.realpathSync(root) : null
+  } catch {
+    return null
+  }
+}
+
+function repoRelativePath(root, absolutePath) {
+  const resolved = path.resolve(absolutePath)
+  let candidate = resolved
+  try {
+    if (fs.existsSync(resolved)) candidate = fs.realpathSync(resolved)
+    else if (fs.existsSync(path.dirname(resolved))) {
+      candidate = path.join(fs.realpathSync(path.dirname(resolved)), path.basename(resolved))
+    }
+  } catch {
+    candidate = resolved
+  }
+  const relative = path.relative(root, candidate)
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null
+  return relative
+}
+
+function unstagePaths(fromDir, absolutePaths) {
+  if (!absolutePaths.length) return
+  const root = gitTopLevel(fromDir)
+  if (!root) return
+  const relative = [...new Set(absolutePaths)]
+    .map((item) => repoRelativePath(root, item))
+    .filter((item) => Boolean(item))
+  if (!relative.length) return
+  for (const item of relative) {
+    spawnSync('git', ['restore', '--staged', '--', item], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: 'ignore',
+    })
+  }
 }
 
 function liveEntries(manifest, diffId) {
@@ -409,8 +644,7 @@ function liveEntries(manifest, diffId) {
 }
 
 export function materializeDiff(dataDir, targetRoot, sessionId, diffId) {
-  const manifest = readManifest(dataDir, assertSessionId(sessionId))
-  if (!manifest) throw new Error(`Unknown session ${sessionId}`)
+  const manifest = requireManifest(dataDir, sessionId)
   const through = diffId || manifest.activeDiffId
   if (!through) return manifest
   restoreBaseline(dataDir, sessionId, targetRoot)
@@ -418,25 +652,47 @@ export function materializeDiff(dataDir, targetRoot, sessionId, diffId) {
   return manifest
 }
 
-function withSessionReplay(dataDir, sessionId, targetRoot, patches, action) {
-  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'visual-coder-chain-'))
-  try {
-    fs.cpSync(targetRoot, temporary, { recursive: true })
-    restoreBaseline(dataDir, sessionId, temporary)
-    for (const patchText of patches) applyUnifiedPatch(patchText, temporary)
-    return action(temporary)
-  } finally {
-    fs.rmSync(temporary, { recursive: true, force: true })
+function loadReplayContents(dataDir, sessionId, targetRoot, patches) {
+  const baseline = readBaseline(dataDir, sessionId)
+  const paths = sessionPaths(dataDir, sessionId)
+  const fileIds = new Set(Object.keys(baseline.files))
+  for (const patchText of patches) {
+    for (const entry of parseUnifiedPatch(patchText).entries) {
+      fileIds.add(entry.id)
+    }
   }
+
+  const files = new Map()
+  for (const fileId of fileIds) {
+    const info = baseline.files[fileId]
+    if (info) {
+      if (!info.existed) continue
+      const stored = resolveTargetFile(paths.baselineFiles, fileId).absolute
+      if (fs.existsSync(stored) && fs.statSync(stored).isFile()) {
+        files.set(fileId, fs.readFileSync(stored, 'utf8'))
+      }
+      continue
+    }
+    const { absolute } = resolveTargetFile(targetRoot, fileId)
+    if (fs.existsSync(absolute) && fs.statSync(absolute).isFile()) {
+      files.set(fileId, fs.readFileSync(absolute, 'utf8'))
+    }
+  }
+  return files
 }
 
 export function validateContinuation(dataDir, manifest, targetRoot, patchText) {
   const prior = manifest.diffs
     .filter((entry) => entry.status !== 'rejected')
     .map((entry) => readDiff(dataDir, manifest.sessionId, entry))
-  withSessionReplay(dataDir, manifest.sessionId, targetRoot, [...prior, patchText], () =>
-    undefined,
+  const patches = [...prior, patchText]
+  const files = loadReplayContents(
+    dataDir,
+    manifest.sessionId,
+    targetRoot,
+    patches,
   )
+  for (const next of patches) applyUnifiedPatchToContents(files, next)
 }
 
 export function inspectTargetFile(
@@ -471,8 +727,36 @@ function featureName(value) {
   return trimmed
 }
 
+export function isStepByStep(manifest) {
+  return manifest?.stepByStep !== false
+}
+
+export function autoAdvance(dataDir, sessionId, targetRoot = null) {
+  const manifest = readManifest(dataDir, sessionId)
+  if (!manifest || isStepByStep(manifest)) return manifest
+  if (manifest.phase === 'plan_ready') {
+    return invokeStep(dataDir, sessionId, manifest.currentStep, targetRoot)
+  }
+  if (manifest.phase === 'review') {
+    const active = manifest.diffs.at(-1)
+    if (!active || active.status !== 'pending') return manifest
+    if (active.step >= manifest.steps.length) return manifest
+    return invokeStep(dataDir, sessionId, active.step + 1, targetRoot)
+  }
+  return manifest
+}
+
+export function setStepByStep(dataDir, sessionId, enabled, targetRoot = null) {
+  const manifest = requireManifest(dataDir, sessionId)
+  manifest.stepByStep = Boolean(enabled)
+  writeManifest(dataDir, manifest)
+  if (isStepByStep(manifest)) return manifest
+  return autoAdvance(dataDir, sessionId, targetRoot)
+}
+
 export function startSession(dataDir, input) {
   const sessionId = assertSessionId(input.sessionId)
+  clearStoppedMarker(dataDir, sessionId)
   const existing = readManifest(dataDir, sessionId)
   if (existing) {
     focusSession(dataDir, sessionId)
@@ -487,6 +771,7 @@ export function startSession(dataDir, input) {
     steps: [],
     status: 'active',
     phase: 'blueprint_ask',
+    stepByStep: true,
     currentStep: 1,
     activeDiffId: null,
     pendingInstruction: null,
@@ -502,8 +787,7 @@ export function startSession(dataDir, input) {
 }
 
 export function answerBlueprint(dataDir, sessionId, enabled) {
-  const manifest = readManifest(dataDir, assertSessionId(sessionId))
-  if (!manifest) throw new Error(`Unknown session ${sessionId}`)
+  const manifest = requireManifest(dataDir, sessionId)
   if (manifest.phase !== 'blueprint_ask') {
     throw new Error(`Session ${sessionId} is not asking for a blueprint`)
   }
@@ -522,8 +806,7 @@ export function answerBlueprint(dataDir, sessionId, enabled) {
 
 export function updateBlueprint(dataDir, sessionId, input = {}) {
   const safeId = assertSessionId(sessionId)
-  const manifest = readManifest(dataDir, safeId)
-  if (!manifest) throw new Error(`Unknown session ${safeId}`)
+  const manifest = requireManifest(dataDir, safeId)
   if (manifest.phase !== 'blueprint') {
     throw new Error(`Session ${safeId} is not in blueprint mode`)
   }
@@ -544,8 +827,7 @@ export function updateBlueprint(dataDir, sessionId, input = {}) {
 
 export function sendBlueprint(dataDir, sessionId, input = {}) {
   const safeId = assertSessionId(sessionId)
-  const manifest = readManifest(dataDir, safeId)
-  if (!manifest) throw new Error(`Unknown session ${safeId}`)
+  const manifest = requireManifest(dataDir, safeId)
   if (manifest.phase !== 'blueprint') {
     throw new Error(`Session ${safeId} is not in blueprint mode`)
   }
@@ -570,6 +852,9 @@ export function sendBlueprint(dataDir, sessionId, input = {}) {
 export function reportPlan(dataDir, input) {
   const sessionId = assertSessionId(input.sessionId)
   const existing = readManifest(dataDir, sessionId)
+  if (!existing && isSessionStopped(dataDir, sessionId)) {
+    throw sessionStoppedError(sessionId)
+  }
   const now = new Date().toISOString()
 
   if (existing?.phase === 'blueprint_ask' || existing?.phase === 'blueprint') {
@@ -586,6 +871,7 @@ export function reportPlan(dataDir, input) {
       steps: [],
       status: 'active',
       phase: 'preparing',
+      stepByStep: true,
       currentStep: 1,
       activeDiffId: null,
       pendingInstruction: null,
@@ -602,7 +888,7 @@ export function reportPlan(dataDir, input) {
     manifest.workStartedAt = null
     writeManifest(dataDir, manifest)
     focusSession(dataDir, sessionId)
-    return manifest
+    return autoAdvance(dataDir, sessionId)
   }
 
   if (existing.phase !== 'replanning') {
@@ -619,12 +905,11 @@ export function reportPlan(dataDir, input) {
   existing.workStartedAt = null
   writeManifest(dataDir, existing)
   focusSession(dataDir, sessionId)
-  return existing
+  return autoAdvance(dataDir, sessionId)
 }
 
 export function invokeStep(dataDir, sessionId, step, targetRoot = null) {
-  const manifest = readManifest(dataDir, assertSessionId(sessionId))
-  if (!manifest) throw new Error(`Unknown session ${sessionId}`)
+  const manifest = requireManifest(dataDir, sessionId)
 
   if (manifest.phase === 'review') {
     if (!targetRoot) throw new Error('A target root is required to apply the current step')
@@ -665,8 +950,11 @@ export function invokeStep(dataDir, sessionId, step, targetRoot = null) {
 
 export function appendDiff(dataDir, targetRoot, input) {
   const sessionId = assertSessionId(input.sessionId)
-  const manifest = readManifest(dataDir, sessionId)
-  if (!manifest) throw new Error(`Report a plan for session ${sessionId} first`)
+  const manifest = requireManifest(
+    dataDir,
+    sessionId,
+    `Report a plan for session ${sessionId} first`,
+  )
   if (manifest.phase !== 'working') {
     throw new Error(`Step ${manifest.currentStep} has not been invoked`)
   }
@@ -721,7 +1009,14 @@ export function appendDiff(dataDir, targetRoot, input) {
   writeManifest(dataDir, manifest)
   materializeDiff(dataDir, targetRoot, sessionId, id)
   focusSession(dataDir, sessionId)
-  return { manifest, entry }
+  const advanced = autoAdvance(dataDir, sessionId, targetRoot)
+  if (!advanced) {
+    throw new Error(`Session ${sessionId} disappeared after publishing a diff`)
+  }
+  return {
+    manifest: advanced,
+    entry: advanced.diffs.find((item) => item.id === id) ?? entry,
+  }
 }
 
 function pendingActive(manifest, diffId) {
@@ -748,8 +1043,7 @@ function applyUnresolved(dataDir, targetRoot, manifest, diffId) {
 }
 
 export function continueDiff(dataDir, targetRoot, sessionId, diffId) {
-  const manifest = readManifest(dataDir, assertSessionId(sessionId))
-  if (!manifest) throw new Error(`Unknown session ${sessionId}`)
+  const manifest = requireManifest(dataDir, sessionId)
   const active = pendingActive(manifest, diffId)
   applyUnresolved(dataDir, targetRoot, manifest, diffId)
 
@@ -759,18 +1053,16 @@ export function continueDiff(dataDir, targetRoot, sessionId, diffId) {
     writeManifest(dataDir, manifest)
     finalizeFinishedSession(dataDir, sessionId)
     return manifest
-  } else {
-    manifest.currentStep = active.step + 1
-    manifest.phase = 'plan_ready'
-    manifest.workStartedAt = null
   }
+  manifest.currentStep = active.step + 1
+  manifest.phase = 'plan_ready'
+  manifest.workStartedAt = null
   writeManifest(dataDir, manifest)
-  return manifest
+  return autoAdvance(dataDir, sessionId, targetRoot)
 }
 
 export function requestReplan(dataDir, sessionId, diffId, instruction) {
-  const manifest = readManifest(dataDir, assertSessionId(sessionId))
-  if (!manifest) throw new Error(`Unknown session ${sessionId}`)
+  const manifest = requireManifest(dataDir, sessionId)
   const active = pendingActive(manifest, diffId)
   const guidance = typeof instruction === 'string' ? instruction.trim() : ''
   if (!guidance) throw new Error('An alternative instruction is required')
@@ -784,14 +1076,91 @@ export function requestReplan(dataDir, sessionId, diffId, instruction) {
   return manifest
 }
 
-export function stopSession(dataDir, sessionId, targetRoot = null) {
+function unstageDiffSessionArtifacts(dataDir, targetRoot, extraPaths = []) {
+  if (!targetRoot) return
+  unstagePaths(targetRoot, [
+    ...extraPaths,
+    diffSessionsRoot(dataDir),
+    path.join(dataDir, 'active-session.json'),
+    path.join(dataDir, 'blueprint-session.json'),
+  ])
+}
+
+function discardStoredSession(
+  dataDir,
+  sessionId,
+  targetRoot = null,
+  { restore = true, keepStoppedMarker = false } = {},
+) {
   const safeId = assertSessionId(sessionId)
-  const manifest = readManifest(dataDir, safeId)
-  if (manifest && targetRoot) {
-    restoreBaseline(dataDir, safeId, targetRoot)
-    replayPatches(dataDir, safeId, targetRoot, acceptedEntries(manifest))
+  const paths = sessionPaths(dataDir, safeId)
+  const fileIds = Object.keys(readBaseline(dataDir, safeId).files)
+  if (targetRoot && restore) {
+    try {
+      restoreBaseline(dataDir, safeId, targetRoot)
+    } catch {
+      // Incomplete session artifacts should still be deleted.
+    }
   }
-  finalizeFinishedSession(dataDir, safeId)
+  if (targetRoot) {
+    unstageDiffSessionArtifacts(
+      dataDir,
+      targetRoot,
+      fileIds.flatMap((id) => {
+        try {
+          return [resolveTargetFile(targetRoot, id).absolute]
+        } catch {
+          return []
+        }
+      }),
+    )
+  }
+  releaseBlueprintSession(dataDir, safeId)
+  if (fs.existsSync(paths.root)) {
+    fs.rmSync(paths.root, { recursive: true, force: true })
+  }
+  if (!keepStoppedMarker) clearStoppedMarker(dataDir, safeId)
+  const active = readActiveSession(dataDir)
+  if (active === safeId) writeActiveSession(dataDir, null)
+}
+
+export function discardInactiveDiffSessions(
+  dataDir,
+  targetRoot = null,
+  waiterIds = waiterSessionIds(),
+) {
+  const keep = new Set()
+  for (const value of waiterIds) {
+    try {
+      keep.add(assertSessionId(value))
+    } catch {
+      // Ignore process command lines with invalid session ids.
+    }
+  }
+
+  for (const sessionId of listStoredSessionIds(dataDir)) {
+    const live = keep.has(sessionId) && Boolean(readManifest(dataDir, sessionId))
+    const stopping = keep.has(sessionId) && isSessionStopped(dataDir, sessionId)
+    if (live || stopping) continue
+    discardStoredSession(dataDir, sessionId, targetRoot)
+  }
+
+  const liveIds = [...keep].filter((id) => readManifest(dataDir, id))
+  const active = readActiveSession(dataDir)
+  if (active && !liveIds.includes(active)) writeActiveSession(dataDir, null)
+  const locked = readBlueprintSession(dataDir)
+  if (locked && !liveIds.includes(locked)) writeBlueprintSession(dataDir, null)
+  unstageDiffSessionArtifacts(dataDir, targetRoot)
+  return liveIds
+}
+
+export function stopSession(dataDir, sessionId, targetRoot = null) {
+  const safeId = assertSessionId(sessionId)
+  writeStoppedMarker(dataDir, safeId)
+  discardStoredSession(dataDir, safeId, targetRoot, { keepStoppedMarker: true })
+  const waiters = waiterSessionIds()
+  waiters.add(safeId)
+  discardInactiveDiffSessions(dataDir, targetRoot, waiters)
   return null
 }
 
@@ -819,14 +1188,7 @@ export function closeSession(dataDir, sessionId) {
 }
 
 export function finalizeFinishedSession(dataDir, sessionId) {
-  const safeId = assertSessionId(sessionId)
-  const paths = sessionPaths(dataDir, safeId)
-  releaseBlueprintSession(dataDir, safeId)
-  if (fs.existsSync(paths.root)) {
-    fs.rmSync(paths.root, { recursive: true, force: true })
-  }
-  const active = readActiveSession(dataDir)
-  if (active === safeId) writeActiveSession(dataDir, null)
+  discardStoredSession(dataDir, sessionId, null, { restore: false })
 }
 
 export function emptyBlueprint() {