dsh-retrace 0.3.0 → 0.4.2

package/lib/http.js

@@ -12,6 +12,16 @@
  *     — one event + context window (sessionQuery.readEvent, lazy reads).
  *   GET  /api/plugins/retrace/surface?sessionId=
  *     — current model surface (sessionQuery.readSurface).
+ *   POST /api/plugins/retrace/rollback/preview
+ *     — dry-run: messages removed + artifact actions (no side effects).
+ *   POST /api/plugins/retrace/rollback
+ *     — execute the rollback ({sessionId, versionId, scope}).
+ *   GET  /api/plugins/retrace/git/status?sessionId=
+ *     — repo detection + HEAD + dirty (timeline git banner).
+ *   POST /api/plugins/retrace/git/init
+ *     — one-click git init for a non-repository workspace (user-confirmed).
+ *   GET  /api/plugins/retrace/snapshot?sessionId=&versionId=&path=
+ *     — read one version's snapshot content (rollback preview / detail).
  *
  * Per PLAN.md §4.6 the client carries its localStorage config on every
  * request as `x-retrace-config: {"versioning":bool,"git":bool,
@@ -24,7 +34,7 @@ export const ROUTE_PREFIX = '/api/plugins/retrace'
 const MAX_BODY_BYTES = 64 * 1024
 
 /** Default per-request config (client overrides via the header). */
-export const DEFAULT_CONFIG = { versioning: true, git: true, retentionLimit: 50 }
+export const DEFAULT_CONFIG = { versioning: true, git: true, retentionLimit: 50, prewrite: true }
 
 /** Parse the `x-retrace-config` request header (tolerant of garbage). */
 export function parseRetraceConfig(raw) {
@@ -37,6 +47,7 @@ export function parseRetraceConfig(raw) {
     if (Number.isInteger(parsed.retentionLimit) && parsed.retentionLimit > 0) {
       config.retentionLimit = parsed.retentionLimit
     }
+    if (typeof parsed.prewrite === 'boolean') config.prewrite = parsed.prewrite
   } catch {
     // malformed header → defaults
   }
@@ -64,7 +75,7 @@ function sendError(res, error) {
 }
 
 /** Route one request. `seam` is the versioning seam (lib/versioning.js). */
-export function createRetraceHttpHandler(ctx, { sessions, agents, seam, log = () => {} }) {
+export function createRetraceHttpHandler(ctx, { sessions, agents, seam, rollback, log = () => {} }) {
   const api = createEditorApi(ctx, sessions, agents, log)
 
   function handleVersions(req, res, sessionId, config) {
@@ -98,6 +109,79 @@ export function createRetraceHttpHandler(ctx, { sessions, agents, seam, log = ()
     }
   }
 
+  async function handleGitStatus(req, res, sessionId) {
+    try {
+      const value = await seam.gitStatus(sessionId)
+      sendJson(res, 200, { ok: true, value })
+    } catch (error) {
+      sendError(res, error)
+    }
+  }
+
+  async function handleSnapshot(req, res, searchParams) {
+    const sessionId = searchParams.get('sessionId') ?? ''
+    const versionId = searchParams.get('versionId') ?? ''
+    const path = searchParams.get('path') ?? ''
+    try {
+      const sha = await seam.resolveSnapshot(versionId, path)
+      if (!sha) {
+        sendJson(res, 200, { ok: true, value: { found: false } })
+        return
+      }
+      const bytes = await seam.readSnapshot(sha)
+      sendJson(res, 200, {
+        ok: true,
+        value: {
+          found: true,
+          sha256: sha,
+          sizeBytes: bytes.byteLength,
+          text: new TextDecoder().decode(bytes),
+        },
+      })
+    } catch (error) {
+      sendError(res, error)
+    }
+  }
+
+  /** POST body parse + dispatch shared by the rollback/git ops. */
+  function handleJsonPost(req, res, fn) {
+    let body = ''
+    req.setEncoding('utf8')
+    req.on('data', (chunk) => {
+      body += chunk
+      if (body.length > MAX_BODY_BYTES) {
+        sendJson(res, 413, {
+          ok: false,
+          error: { code: 'payload-too-large', message: 'payload exceeds 64 KiB' },
+        })
+        req.destroy()
+      }
+    })
+    req.on('error', () => { /* socket errors are terminal; nothing to send */ })
+    req.on('end', async () => {
+      let args = {}
+      if (body.length > 0) {
+        try {
+          args = JSON.parse(body)
+        } catch {
+          sendJson(res, 400, {
+            ok: false,
+            error: { code: 'bad-json', message: 'request body is not valid JSON' },
+          })
+          return
+        }
+      }
+      const sessionId = String(args?.sessionId ?? '')
+      if (sessionId) seam.setConfig(sessionId, parseRetraceConfig(req.headers['x-retrace-config']))
+      try {
+        const value = await fn(args)
+        sendJson(res, 200, { ok: true, value })
+      } catch (error) {
+        sendError(res, error)
+      }
+    })
+  }
+
   function handlePost(req, res, op) {
     let body = ''
     req.setEncoding('utf8')
@@ -146,7 +230,8 @@ export function createRetraceHttpHandler(ctx, { sessions, agents, seam, log = ()
 
   return (req, res) => {
     const url = new URL(req.url ?? '/', 'http://retrace.local')
-    const op = url.pathname.split('/').filter(Boolean).at(-1) ?? ''
+    const segments = url.pathname.split('/').filter(Boolean)
+    const op = segments.at(-1) ?? ''
     const searchParams = url.searchParams
     const sessionId = searchParams.get('sessionId') ?? ''
     const config = parseRetraceConfig(req.headers['x-retrace-config'])
@@ -168,6 +253,10 @@ export function createRetraceHttpHandler(ctx, { sessions, agents, seam, log = ()
           return void handleEvent(req, res, searchParams)
         case 'surface':
           return void handleSurface(req, res, sessionId)
+        case 'status':
+          return void handleGitStatus(req, res, sessionId)
+        case 'snapshot':
+          return void handleSnapshot(req, res, searchParams)
         default:
           return sendJson(res, 404, {
             ok: false,
@@ -181,6 +270,18 @@ export function createRetraceHttpHandler(ctx, { sessions, agents, seam, log = ()
         error: { code: 'method-not-allowed', message: 'POST or GET only' },
       })
     }
+    // P1 rollback/git POST ops (last segment discriminates).
+    if (segments.includes('rollback') && op === 'preview') {
+      if (!rollback) return sendJson(res, 503, { ok: false, error: { code: 'rollback-unavailable', message: 'rollback surface unavailable' } })
+      return handleJsonPost(req, res, (args) => rollback.preview(args))
+    }
+    if (segments.includes('rollback')) {
+      if (!rollback) return sendJson(res, 503, { ok: false, error: { code: 'rollback-unavailable', message: 'rollback surface unavailable' } })
+      return handleJsonPost(req, res, (args) => rollback.execute(args))
+    }
+    if (segments.includes('git') && op === 'init') {
+      return handleJsonPost(req, res, (args) => seam.gitInit(String(args?.sessionId ?? '')))
+    }
     return handlePost(req, res, op)
   }
 }

package/lib/index.js

@@ -22,9 +22,11 @@
 import { createEditorApi } from './host-core.js'
 import { createRetraceHttpHandler, ROUTE_PREFIX } from './http.js'
 import { createVersioningSeam } from './versioning.js'
+import { createRollbackExecutor } from './rollback.js'
+import { createMarkerGuard } from './prewrite-guard.js'
 
 export const name = 'dsh-retrace'
-export const inject = ['sessions', 'agents', 'webServer']
+export const inject = ['sessions', 'agents', 'webServer', 'fs', 'subprocess', 'sandboxPolicy']
 
 export function apply(ctx) {
   const log = (line) => ctx.logger?.info(line)
@@ -33,11 +35,22 @@ export function apply(ctx) {
   const seam = createVersioningSeam(ctx, log)
   seam.register()
 
-  const api = createEditorApi(ctx, ctx.sessions, ctx.agents, log)
+  // 写前校验守卫（8-25 事故闭环）：marker 落盘前过三层契约；依赖缺失自动降级。
+  const guard = createMarkerGuard({
+    log,
+    enabled: (sessionId) => seam.configFor(sessionId).prewrite !== false,
+  })
+  const hooks = { validateMarker: guard.validateMarkerAppend }
+
+  // P1 rollback executor: context/artifact restore over the seam (git + snapshots).
+  const rollback = createRollbackExecutor({ ctx, sessions: ctx.sessions, seam, validateMarker: hooks.validateMarker, log })
+
+  const api = createEditorApi(ctx, ctx.sessions, ctx.agents, log, hooks)
   const handler = createRetraceHttpHandler(ctx, {
     sessions: ctx.sessions,
     agents: ctx.agents,
     seam,
+    rollback,
     log,
   })
 

package/lib/prewrite-guard.js

@@ -0,0 +1,71 @@
+/**
+ * dsh-retrace — lib/prewrite-guard.js
+ *
+ * ★ 写前校验（pre-write validation）——8-25 会话修复事故的闭环。
+ *
+ * 事故（2026-08-25）第 1 轮失败就是"违约写入没被拦"：surface-replace 的
+ * `sourceEventSeqs` 被清空后写盘 → 会话加载抛 `SessionPersistenceCorruptionError`；
+ * 第 2 轮把 marker 改成 append → 客户端引擎崩溃（rt.js:6816）。如果写入前先校验，
+ * 会话根本不会被改坏。
+ *
+ * 本模块把 marker 写入（撤回/编辑/重发/重新生成/恢复 追加的替换型空 assistant
+ * 消息）接到 `dsh-log-contract` 的写前校验器上：`createPreWriter(...).validateAppend(...)`
+ * 与离线体检共用同一套判定（S5 覆盖 / M1 引擎 / P1/P2 marker 语义 / S8 foldSurface
+ * 终验），保证"体检看到的问题 = 写入前拦下的问题"。
+ *
+ * 设计约束：
+ * - host-core 保持零 import（动态插件 realm 可运行），校验器以
+ *   `hooks.validateMarker` 注入 `createEditorApi`（lib/host-core.js）；
+ * - 依赖 `dsh-log-contract` 在运行时**懒加载**（`await import`）——包缺失/加载失败
+ *   时守卫静默降级（仅日志），插件照常工作，绝不因守护件损坏主功能；
+ * - `prewriterFactory` 可注入（测试用 fake），默认指向 `createPreWriter`；
+ * - `enabled(sessionId)` 门控（默认全开）：写前校验可整体关闭（大会话的完整
+ *   重放校验有秒级成本，见 DEVLOG）。
+ *
+ * 失败语义：任何 error 级违规 → 抛 `marker-rejected`（op 包装层转为
+ * `{ ok: false, error: { code: 'marker-rejected', ... } }`），**不落盘**。
+ */
+import { editorError } from './host-core.js'
+
+/**
+ * 建立 marker 写前校验器。
+ * @param {object} [options]
+ * @param {(line: string) => void} [options.log] 拒绝/降级时的诊断日志
+ * @param {(input: {events: Array}) => { validateAppend(candidate: object): {ok: boolean, violations?: Array} }} [options.prewriterFactory]
+ *   默认 `dsh-log-contract` 的 `createPreWriter`；测试注入 fake。
+ * @param {(sessionId: string) => boolean} [options.enabled] 门控（默认恒 true）。
+ * @returns {{ validateMarkerAppend(session, envelope): Promise<void> }}
+ */
+export function createMarkerGuard({ log = () => {}, prewriterFactory, enabled = () => true } = {}) {
+  let factory = prewriterFactory ?? null
+  return {
+    /** 校验"即将追加的完整事件信封"；通过返回，违规则抛 `marker-rejected`。 */
+    async validateMarkerAppend(session, envelope) {
+      if (typeof enabled === 'function' && enabled(session?.id) === false) return
+      if (factory === null) {
+        try {
+          factory = (await import('dsh-log-contract')).createPreWriter
+        } catch (error) {
+          log(`retrace: prewrite guard unavailable (dsh-log-contract not loadable): ${String(error)}`)
+          factory = false // remember the failure; don't retry per write
+          return
+        }
+      }
+      if (factory === false) return
+      let verdict
+      try {
+        const prewriter = factory({ events: session.events })
+        verdict = prewriter.validateAppend(envelope)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        throw editorError('marker-rejected', `Marker pre-write validation failed: ${message}`)
+      }
+      if (verdict?.ok) return
+      const detail = Array.isArray(verdict?.violations)
+        ? verdict.violations.map((v) => `[${v.id}/${v.severity}] ${v.message}`).join(' | ')
+        : 'unknown violation'
+      log(`retrace: marker write rejected by contract guard: ${detail}`)
+      throw editorError('marker-rejected', `Marker write rejected by contract guard: ${detail}`)
+    },
+  }
+}

package/lib/projection/versions.js

@@ -7,15 +7,17 @@
  * cache, checkpoint persistence (`dsh-session-projection-cache`) and cold
  * reads; this unit contributes only the pure state machine:
  *
- *   - `init`   — empty fold state (see lib/version-index.js),
- *   - `apply`  — deterministic fold over one committed event (same reference
- *                when nothing changed — `Object.is` gates the change feed),
- *   - `view`   — the client-visible wire value (version list summary served
- *                in `session/projection` push frames and `snapshot()`).
+ *   - `stateSchema` — zod schema of the RAW fold state (plain JSON; the
+ *     durable checkpoint validates rows against it),
+ *   - `init` / `apply` — the deterministic fold (lib/version-index.js),
+ *   - `wire` — the client-visible view ({viewSchema, view}); a unit WITHOUT
+ *     `wire` registers as checkpoint-only and is never served in
+ *     `session/projection` push frames or `snapshot()` — the framework
+ *     contract that P0's original definition missed (found by the P1
+ *     real-harness smoke: every session's projection block lacked the key).
  *
- * The unit schema validates the VIEW value (the registry parses `view(state)`
- * before serving); the raw fold state is plain JSON so the projection cache
- * can persist it (`z.json()` at the durable boundary).
+ * `view` / `schema` top-level aliases stay for the unit tests, which drive
+ * the definition directly instead of through the registry.
  */
 import { z } from 'zod'
 import {
@@ -54,16 +56,36 @@ export const versionsViewSchema = z.object({
   versions: z.array(versionSummarySchema).max(VERSION_LIMIT),
 })
 
+/** Raw fold-state schema (durable checkpoint rows validate against it). */
+const windowEntrySchema = z.object({
+  intent: z.enum(['write', 'delete', 'unknown']),
+  lastSeq: z.number().int().nonnegative(),
+})
+
+export const versionIndexStateSchema = z.object({
+  versions: z.array(z.unknown()).max(VERSION_LIMIT),
+  windowFiles: z.record(z.string(), windowEntrySchema),
+  knownFiles: z.array(z.string()),
+  surface: z.array(z.number().int().nonnegative()),
+})
+
 /**
  * The `retrace/versions` unit — register via
  * `ctx.sessionProjections.register(versionsProjectionDefinition)`.
  */
 export const versionsProjectionDefinition = {
   key: 'retrace/versions',
-  schema: versionsViewSchema,
+  stateSchema: versionIndexStateSchema,
   init: () => createVersionIndexState(),
   apply: (state, event) => applyVersionIndex(state, event),
-  view: (state) => viewVersionIndex(state),
+  wire: {
+    viewSchema: versionsViewSchema,
+    view: (state) => viewVersionIndex(state),
+  },
   /** Bump when the serialized fold state or fold semantics change. */
   stateVersion: 1,
 }
+
+// Top-level aliases (unit tests drive the definition directly).
+versionsProjectionDefinition.schema = versionsProjectionDefinition.wire.viewSchema
+versionsProjectionDefinition.view = versionsProjectionDefinition.wire.view

package/lib/rollback.js

@@ -0,0 +1,283 @@
+/**
+ * dsh-retrace — Rollback executor (PLAN.md §4.5).
+ *
+ * Rolls a session (and optionally its artifacts) back to a recorded version:
+ *
+ *   scope 'context'   — append an invisible replacement marker shadowing every
+ *                       surface node added AFTER the version boundary, so the
+ *                       model-visible history rewinds to that point (git-checkout
+ *                       semantics: the rewound content stays in the durable log
+ *                       as a later version — non-destructive, auditable).
+ *   scope 'artifacts' — restore the files the version's window touched to their
+ *                       content at that version: git checkout when the workspace
+ *                       is a repository and the version recorded a HEAD, else
+ *                       content-addressed snapshot read-back through `ctx.fs`
+ *                       (CAS-guarded), with subprocess `rm` for files that were
+ *                       deleted in the version's window (realpath-in-workspace +
+ *                       in-manifest guards only).
+ *   scope 'both'      — context first, then artifacts.
+ *
+ * Every execution is dry-run-previewable first and records the restore as a new
+ * version (kind='restore') in the projection feed, so a rollback is itself a
+ * version and can be rolled back again (idempotent per-session lock included).
+ */
+import { isAbsolute, relative, resolve } from 'node:path'
+import { foldSurface } from '@deepseek-ai/dsh-session'
+import { appendEditorMarker, editorError } from './host-core.js'
+
+const VALID_SCOPES = ['context', 'artifacts', 'both']
+
+/**
+ * Create the rollback executor.
+ * @param {object} deps
+ * @param {object} deps.ctx            — host context (ctx.fs / ctx.subprocess / ctx.sandboxPolicy).
+ * @param {object} deps.sessions       — session registry (sessions.get / sessions.flush).
+ * @param {object} deps.seam           — versioning seam (snapshot / resolveSnapshot /
+ *                                       readSnapshot / gitStatus / gitHeadFor).
+ * @param {(line: string) => void} [deps.log]
+ */
+export function createRollbackExecutor({ ctx, sessions, seam, validateMarker, log = () => {} }) {
+  /** One in-flight rollback per session; later ops wait for the earlier one. */
+  const locks = new Map()
+
+  function locked(sessionId, fn) {
+    const previous = locks.get(sessionId) ?? Promise.resolve()
+    const next = previous.catch(() => {}).then(fn)
+    locks.set(sessionId, next)
+    void next.finally(() => {
+      if (locks.get(sessionId) === next) locks.delete(sessionId)
+    }).catch(() => {})
+    return next
+  }
+
+  function requireSession(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+      throw editorError('bad-request', 'sessionId must be a non-empty string')
+    }
+    const session = sessions.get(sessionId)
+    if (!session) throw editorError('session-not-found', `session "${sessionId}" not found`)
+    return session
+  }
+
+  function requireIdle(sessionId) {
+    const agent = seam.agentOf?.(sessionId)
+    if (agent && typeof agent.status === 'string' && agent.status === 'running') {
+      throw editorError('agent-busy', 'The agent is still responding; stop the current reply before rolling back.')
+    }
+  }
+
+  function versionOf(sessionId, versionId) {
+    const snap = seam.snapshot(sessionId)
+    const record = (snap.versions ?? []).find((v) => v.versionId === versionId)
+    if (!record) throw editorError('version-not-found', `version "${versionId}" not found in session "${sessionId}"`)
+    return record
+  }
+
+  function cwdOf(session) {
+    return typeof session.header?.cwd === 'string' ? session.header.cwd : null
+  }
+
+  /**
+   * The surface diff of "now" vs the version boundary: every current surface
+   * node absent from the version's folded surface. An empty diff means the
+   * session is already at (or before) that version.
+   */
+  function contextDiff(session, record) {
+    const events = session.events
+    const target = foldSurface(events.slice(0, record.boundarySeq + 1))
+    const targetNodes = new Set(target.nodes)
+    const current = session.surface.nodes
+    const diff = current.filter((seq) => !targetNodes.has(seq))
+    return {
+      messages: diff.length,
+      diff,
+      firstSeq: diff.length > 0 ? diff[0] : null,
+      lastSeq: diff.length > 0 ? diff[diff.length - 1] : null,
+    }
+  }
+
+  /** Realpath must stay inside the workspace and match a manifest path. */
+  async function workspaceRealpath(session, relPath) {
+    const cwd = cwdOf(session)
+    if (!cwd) return null
+    const target = await ctx.fs.resolve(relPath, { cwd })
+    const root = await ctx.fs.resolve('.', { cwd })
+    if (!ctx.fs.contains(root, target)) return null
+    return target
+  }
+
+  /** Artifact plan for one version: per file the action and the method. */
+  async function artifactPlan(session, record, git) {
+    const rows = []
+    const cwd = cwdOf(session)
+    const headHash = git?.headHash
+    for (const file of record.touchedFiles) {
+      if (file.mode === 'deleted') {
+        const target = cwd ? await workspaceRealpath(session, file.path) : null
+        rows.push({
+          path: file.path,
+          action: 'delete',
+          method: 'subprocess',
+          safe: target !== null,
+        })
+        continue
+      }
+      if (git && headHash) {
+        rows.push({ path: file.path, action: 'restore', method: 'git', safe: true })
+        continue
+      }
+      const sha = await seam.resolveSnapshot(record.versionId, file.path)
+      if (sha) {
+        rows.push({ path: file.path, action: 'restore', method: 'snapshot', safe: true })
+      } else {
+        rows.push({ path: file.path, action: 'skip', reason: 'no-snapshot' })
+      }
+    }
+    return { rows, git: git ? { enabled: true, headHash: git.headHash } : { enabled: false } }
+  }
+
+  /** Dry-run preview: what a rollback would remove / touch (no side effects). */
+  async function preview(args) {
+    const sessionId = String(args?.sessionId ?? '')
+    const versionId = String(args?.versionId ?? '')
+    const scope = String(args?.scope ?? 'both')
+    if (!VALID_SCOPES.includes(scope)) throw editorError('bad-scope', `scope must be one of ${VALID_SCOPES.join(', ')}`)
+    const session = requireSession(sessionId)
+    const record = versionOf(sessionId, versionId)
+    const context = contextDiff(session, record)
+    const git = seam.configFor(sessionId).git ? await seam.gitStatus(sessionId) : null
+    const artifacts = await artifactPlan(session, record, git)
+    return {
+      versionId,
+      kind: record.kind,
+      boundarySeq: record.boundarySeq,
+      scope,
+      context,
+      artifacts,
+      applicable: scope === 'context' ? context.messages > 0 : scope === 'artifacts' ? artifacts.rows.length > 0 : context.messages > 0 || artifacts.rows.length > 0,
+    }
+  }
+
+  /** Delete one manifest file via `rm`, after realpath-in-workspace verification. */
+  async function removeOne(session, file) {
+    const target = await workspaceRealpath(session, file.path)
+    if (!target) return { path: file.path, status: 'skipped', reason: 'outside-workspace' }
+    const cwd = cwdOf(session)
+    if (!cwd) return { path: file.path, status: 'skipped', reason: 'no-cwd' }
+    const handle = ctx.subprocess.spawn({
+      argv: ['rm', '--', relative(resolve(cwd), resolve(target))],
+      cwd,
+      stdio: { stdin: 'ignore', stdout: { maxBytes: 64 * 1024 }, stderr: { maxBytes: 64 * 1024 } },
+      graceMs: 15_000,
+      signal: undefined,
+      env: {},
+    })
+    const outcome = await handle.done
+    return { path: file.path, status: outcome.exitCode === 0 ? 'deleted' : 'failed' }
+  }
+
+  /** Restore one snapshot file through the sandboxed fs (CAS-guarded write). */
+  async function restoreSnapshot(session, file, sha) {
+    const cwd = cwdOf(session)
+    if (!cwd) return { path: file.path, status: 'skipped', reason: 'no-cwd' }
+    const bytes = await seam.readSnapshot(sha)
+    const text = new TextDecoder().decode(bytes)
+    const target = await ctx.fs.resolve(file.path, { cwd })
+    let expected
+    try {
+      const stat = await ctx.fs.stat(target)
+      if (stat && typeof stat.version === 'number') expected = { kind: 'replaceIfVersion', version: stat.version }
+    } catch { /* missing file: plain create */ }
+    const policy = ctx.sandboxPolicy?.resolve?.({ session, mode: 'workspace-write' })
+    await ctx.fs.writeText(target, text, expected, undefined, policy)
+    return { path: file.path, status: 'restored' }
+  }
+
+  /** Execute artifact rollback for one version (git first, snapshot fallback). */
+  async function rollbackArtifacts(session, record, git) {
+    const results = []
+    const cwd = cwdOf(session)
+    const gitPaths = []
+    const snapshotJobs = []
+    const deletes = []
+    const headHash = git?.headHash
+    for (const file of record.touchedFiles) {
+      if (file.mode === 'deleted') {
+        deletes.push(file)
+        continue
+      }
+      if (git && headHash) {
+        gitPaths.push(file.path)
+        continue
+      }
+      const sha = await seam.resolveSnapshot(record.versionId, file.path)
+      if (sha) snapshotJobs.push({ file, sha })
+      else results.push({ path: file.path, status: 'skipped', reason: 'no-snapshot' })
+    }
+    if (gitPaths.length > 0 && cwd && headHash) {
+      const outcome = await seam.gitCheckout(cwd, headHash, gitPaths)
+      for (const path of gitPaths) {
+        results.push({
+          path,
+          status: outcome.ok && outcome.checked.includes(path) ? 'restored' : outcome.ok ? 'unchanged' : 'failed',
+        })
+      }
+    }
+    for (const { file, sha } of snapshotJobs) {
+      try {
+        results.push(await restoreSnapshot(session, file, sha))
+      } catch (error) {
+        results.push({ path: file.path, status: 'failed', reason: String(error) })
+      }
+    }
+    for (const file of deletes) {
+      try {
+        results.push(await removeOne(session, file))
+      } catch (error) {
+        results.push({ path: file.path, status: 'failed', reason: String(error) })
+      }
+    }
+    return results
+  }
+
+  /** Execute a rollback (callers must preview first; the host enforces confirm). */
+  async function execute(args) {
+    const sessionId = String(args?.sessionId ?? '')
+    const versionId = String(args?.versionId ?? '')
+    const scope = String(args?.scope ?? 'both')
+    if (!VALID_SCOPES.includes(scope)) throw editorError('bad-scope', `scope must be one of ${VALID_SCOPES.join(', ')}`)
+    return locked(sessionId, async () => {
+      const session = requireSession(sessionId)
+      requireIdle(sessionId)
+      const record = versionOf(sessionId, versionId)
+      const git = seam.configFor(sessionId).git ? await seam.gitStatus(sessionId) : null
+      const outcome = { op: 'restore', versionId, scope, markerSeq: null, artifacts: [], context: { messages: 0 } }
+
+      if (scope === 'context' || scope === 'both') {
+        const { diff } = contextDiff(session, record)
+        if (diff.length > 0) {
+          const span = { start: diff[0], end: diff[diff.length - 1], shadowedSeqs: diff.slice() }
+          const markerEvent = await appendEditorMarker(session, span, 'restore', record.boundarySeq, '', validateMarker)
+          await flushSafely(session)
+          outcome.markerSeq = markerEvent.seq
+          outcome.context = { messages: diff.length }
+        }
+      }
+
+      if (scope === 'artifacts' || scope === 'both') {
+        outcome.artifacts = await rollbackArtifacts(session, record, git)
+      }
+      return outcome
+    })
+  }
+
+  async function flushSafely(session) {
+    try {
+      if (typeof sessions.flush === 'function') await sessions.flush(session)
+    } catch (error) {
+      log(`retrace: flush failed: ${String(error)}`)
+    }
+  }
+
+  return { preview, execute }
+}

package/lib/version-index.js

@@ -25,6 +25,15 @@
 
 export const MARKER_ID_PREFIX = 'retrace'
 
+/**
+ * Every marker-id prefix this build can classify. `MARKER_ID_PREFIX` is the
+ * prefix NEW markers are written with; the rest are LEGACY prefixes from
+ * earlier plugin names (dsh-message-editor). RENAME RULE: when the plugin
+ * changes identity again, keep the retired prefix here so markers written
+ * under the previous name keep classifying correctly.
+ */
+export const MARKER_ID_PREFIXES = [MARKER_ID_PREFIX, 'message-editor']
+
 /** Timeline keeps the most recent N versions; full history stays replayable from the log. */
 export const VERSION_LIMIT = 200
 
@@ -56,10 +65,12 @@ export function isCompactCheckpointSource(source) {
 /** Map a marker event id prefix to a user-facing version kind. */
 export function kindFromMarkerId(id) {
   if (typeof id !== 'string') return 'edit'
-  const prefix = `${MARKER_ID_PREFIX}-`
-  if (!id.startsWith(prefix)) return 'edit'
-  const op = id.slice(prefix.length).split('-')[0]
-  if (op === 'recall' || op === 'edit' || op === 'regenerate' || op === 'restore') return op
+  for (const p of MARKER_ID_PREFIXES) {
+    const prefix = `${p}-`
+    if (!id.startsWith(prefix)) continue
+    const op = id.slice(prefix.length).split('-')[0]
+    if (op === 'recall' || op === 'edit' || op === 'regenerate' || op === 'restore') return op
+  }
   return 'edit'
 }