@xmoon76/dsh-pi-tui 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmoon76/dsh-pi-tui",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "The dsh-pi-tui bundle: a TUI surface for DeepSeek Harness profiles (dsh --profile pi-tui)",
   "license": "MIT",
   "author": "XMoon <xmoonox@gmail.com>",
@@ -39,6 +39,7 @@
   "files": [
     "dist",
     "config",
+    "scripts",
     "cordis.patch.yml",
     "README.md",
     "LICENSE"
@@ -60,31 +61,32 @@
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
-    "@deepseek-ai/dsh-cmdline": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-agent-default-model": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-cmdline": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-token-meter": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-plan-mode": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-subagent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-goal": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-tool-workflow": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-jobs": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-llm-retry": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-permission-presets": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-session-title": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-plan-mode": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-session-query": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-jobs": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session-title": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-shell": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-subagent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-token-meter": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-workflow": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.6",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
@@ -125,7 +127,7 @@
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node --test test/*.test.ts",
+    "test": "node --test test/*.test.ts test/*.test.mjs",
     "clean": "rm -rf dist"
   }
 }

package/scripts/repair-core.mjs

@@ -0,0 +1,324 @@
+/**
+ * @xmoon76/dsh-pi-tui/scripts/repair-core — pure session-log repair logic.
+ *
+ * dsh persists one session as a JSONL artifact where every event's `seq`
+ * must equal its position (`event.seq === index`), wrapped in concatenated
+ * Zstandard frames (one frame per write-behind flush). Two dsh processes
+ * writing one session concurrently can mint the same seq (each numbers from
+ * its own in-memory log length), which makes the artifact unreadable —
+ * `SessionLogScanner` throws `corrupt session log: seq gap in committed
+ * region`. This module repairs such logs:
+ *
+ * - duplicate seq (`got < expected`) — renumbers every event from the first
+ *   collision onward so `seq === index` again, remapping cross-references
+ *   (`sourceEventSeqs`, `messageSeqs`, `sourceEventSeq`) through the
+ *   old→new mapping;
+ * - missing seq / unparsable row (`got > expected` or unparsable JSON) —
+ *   truncates at the first broken event (the missing events cannot be
+ *   recreated) and reports the loss;
+ * - wrong frame layout (first frame is not exactly the header line, e.g. a
+ *   whole-log single frame) — re-frames the log into the dsh layout:
+ *   header line alone in the first frame, then one frame per line;
+ * - otherwise — no-op.
+ *
+ * The chunk packing rows (`*-chunks` with `seq0`) are expanded by
+ * `decodeStorageRecord` on read; the repaired log writes one event per line
+ * (no packing), which the same reader accepts.
+ *
+ * The decoder (`decodeStorageRecord`) and encoder (`packChunkRuns`) come
+ * from the installed dsh (`@deepseek-ai/dsh-session`) and are injected so
+ * the logic stays testable. The frame walker is vendored from
+ * `dsh-session-persistence-jsonl` (upstream commit 0ba0dcbd4d39) so the
+ * script needs no runtime import for it.
+ * @module repair-core
+ */
+
+import { constants } from 'node:zlib'
+
+/** Zstandard frame magic, little-endian (`\x28\xB5\x2F\xFD`). */
+export const ZSTD_MAGIC = 0xfd2fb528
+
+/**
+ * Compress with the same content-checksum flag the harness writer uses
+ * (`dsh-session-persistence-jsonl`'s `compressZstdFrame` passes
+ * `ZSTD_c_checksumFlag: 1`).
+ */
+const CHECKSUMMED_OPTIONS = {
+  params: { [constants.ZSTD_c_checksumFlag]: 1 },
+}
+
+/**
+ * Walk concatenated Zstandard frames and return each frame's byte range.
+ * Vendored from `dsh-session-persistence-jsonl/lib/index.js`
+ * (`scanZstdFrames`): parses the frame header (content-size flags) and block
+ * headers to find frame boundaries without trusting content sizes.
+ * @param buffer - the raw artifact bytes.
+ * @returns `{ frames, tornStart }` — `tornStart` when the tail is truncated.
+ */
+export function scanZstdFrames(buffer) {
+  const frames = []
+  let offset = 0
+  while (offset < buffer.length) {
+    const start = offset
+    if (buffer.length - offset < 4) return { frames, tornStart: start }
+    if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) throw new Error(`corrupt Zstandard session log: invalid frame magic at byte ${offset}`)
+    offset += 4
+    if (offset === buffer.length) return { frames, tornStart: start }
+    const descriptor = buffer.readUInt8(offset)
+    offset += 1
+    if ((descriptor & 24) !== 0) throw new Error(`corrupt Zstandard session log: reserved frame-header bit at byte ${offset - 1}`)
+    const contentSizeFlag = descriptor >>> 6
+    const singleSegment = (descriptor & 32) !== 0
+    const checksum = (descriptor & 4) !== 0
+    const dictionaryFlag = descriptor & 3
+    const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag
+    const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : 1 << contentSizeFlag
+    const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes
+    if (buffer.length - offset < remainingHeaderBytes) return { frames, tornStart: start }
+    offset += remainingHeaderBytes
+    for (;;) {
+      if (buffer.length - offset < 3) return { frames, tornStart: start }
+      const blockHeader = buffer.readUIntLE(offset, 3)
+      offset += 3
+      const lastBlock = (blockHeader & 1) !== 0
+      const blockType = blockHeader >>> 1 & 3
+      const blockSize = blockHeader >>> 3
+      if (blockType === 3) throw new Error(`corrupt Zstandard session log: reserved block type at byte ${offset - 3}`)
+      const payloadBytes = blockType === 1 ? 1 : blockSize
+      if (buffer.length - offset < payloadBytes) return { frames, tornStart: start }
+      offset += payloadBytes
+      if (lastBlock) break
+    }
+    if (checksum) {
+      if (buffer.length - offset < 4) return { frames, tornStart: start }
+      offset += 4
+    }
+    frames.push({ start, end: offset })
+  }
+  return { frames }
+}
+
+/**
+ * Decompress a complete concatenated-frame artifact into its JSONL text.
+ * @param buffer - raw artifact bytes.
+ * @param zstdDecompressSync - `node:zlib` zstd decompressor (one frame per call).
+ * @returns `{ text, frames }`.
+ */
+export function decompressFrames(buffer, zstdDecompressSync) {
+  const { frames } = scanZstdFrames(buffer)
+  if (frames.length === 0) throw new Error('empty or header-less Zstandard session log')
+  const parts = []
+  for (const frame of frames) {
+    parts.push(zstdDecompressSync(buffer.subarray(frame.start, frame.end)))
+  }
+  return { text: Buffer.concat(parts).toString('utf8'), frames: frames.length }
+}
+
+/**
+ * Validate the frame layout the dsh reader requires: the first frame must
+ * decompress to EXACTLY one newline-terminated header line (the harness's
+ * `assertZstdHeaderFrame`). The harness appends ONE zstd frame per flush
+ * batch, so a whole-log single-frame artifact is structurally valid zstd but
+ * rejected by dsh (`corrupt Zstandard session log: first frame is not
+ * exactly one header line`) — `session.list`, `load`, and `readFrom` all
+ * fail on it.
+ * @param buffer - raw artifact bytes.
+ * @param zstdDecompressSync - `node:zlib` zstd decompressor (one frame per call).
+ * @returns `{ ok: true }` or `{ ok: false, issue }`.
+ */
+export function scanZstdLayout(buffer, zstdDecompressSync) {
+  const { frames } = scanZstdFrames(buffer)
+  if (frames.length === 0) return { ok: false, issue: 'empty or header-less Zstandard session log' }
+  let plaintext
+  try {
+    plaintext = zstdDecompressSync(buffer.subarray(frames[0].start, frames[0].end))
+  } catch (error) {
+    return { ok: false, issue: `corrupt Zstandard session log: header frame failed validation (${error instanceof Error ? error.message : String(error)})` }
+  }
+  if (plaintext.length === 0 || plaintext.indexOf(0x0A) !== plaintext.length - 1) {
+    return { ok: false, issue: 'corrupt Zstandard session log: first frame is not exactly one header line' }
+  }
+  return { ok: true }
+}
+
+/**
+ * Compress a repaired log in the dsh frame layout: the header line alone in
+ * the first frame, then the remaining lines chunked into ~16 KiB plaintext
+ * frames. The harness reader requires the first frame to decode to exactly
+ * one header line, and appends one frame per flush batch; writing the whole
+ * log as one frame is the layout bug that made repaired logs unreadable.
+ * Chunking keeps the file near its original size (one frame per event
+ * balloons ~10x from per-frame zstd overhead) while keeping torn-tail
+ * recovery at sub-KiB-of-events granularity.
+ */
+export function compressLog(text, zstdCompressSync) {
+  const lines = text.split('\n')
+  const frames = []
+  // Frame one: exactly the header line (the reader's assertZstdHeaderFrame).
+  if (lines.length > 0 && lines[0] !== '') {
+    frames.push(zstdCompressSync(Buffer.from(`${lines[0]}\n`, 'utf8'), CHECKSUMMED_OPTIONS))
+  }
+  let chunk = []
+  let chunkBytes = 0
+  const flushChunk = () => {
+    if (chunk.length === 0) return
+    frames.push(zstdCompressSync(Buffer.from(`${chunk.join('\n')}\n`, 'utf8'), CHECKSUMMED_OPTIONS))
+    chunk = []
+    chunkBytes = 0
+  }
+  for (let index = 1; index < lines.length; index += 1) {
+    const line = lines[index]
+    if (line === '' && index === lines.length - 1) continue // trailing newline of the last record
+    chunk.push(line)
+    chunkBytes += line.length + 1
+    if (chunkBytes >= 16 * 1024) flushChunk()
+  }
+  flushChunk()
+  return frames.length > 0 ? Buffer.concat(frames) : zstdCompressSync(Buffer.alloc(0), CHECKSUMMED_OPTIONS)
+}
+
+/**
+ * Scan a JSONL session text with the storage-format reader semantics:
+ * header on line 0, every following line decodes (possibly expanding packed
+ * chunk rows) into events that must be contiguous (`event.seq === index`).
+ * Unlike the real scanner, ALL events are retained (renumber repair needs
+ * the tail) and every row is examined; the FIRST issue is reported.
+ * @param text - decompressed JSONL session text.
+ * @param decodeStorageRecord - `@deepseek-ai/dsh-session` row decoder.
+ * @returns `{ header, events, issue }`.
+ */
+export function scanEvents(text, decodeStorageRecord) {
+  const lines = text.split('\n')
+  const header = lines[0] ?? ''
+  const events = []
+  let issue
+  for (let lineIndex = 1; lineIndex < lines.length; lineIndex += 1) {
+    const raw = lines[lineIndex]
+    if (raw === '') continue
+    let decoded
+    try {
+      decoded = decodeStorageRecord(JSON.parse(raw))
+    } catch {
+      issue ??= {
+        kind: 'unparsable',
+        index: events.length,
+        line: lineIndex + 1,
+        message: `corrupt session log: unparsable committed event at line ${lineIndex + 1}`,
+      }
+      continue
+    }
+    for (const event of decoded) {
+      if (event.seq !== events.length) {
+        issue ??= {
+          kind: event.seq < events.length ? 'duplicate' : 'gap',
+          index: events.length,
+          line: lineIndex + 1,
+          expected: events.length,
+          got: event.seq,
+          message: `corrupt session log: seq gap in committed region at line ${lineIndex + 1} (expected ${events.length}, got ${event.seq})`,
+        }
+      }
+      events.push(event)
+    }
+  }
+  return { header, events, issue }
+}
+
+/** Keys whose array values are seq references in event `data`. */
+const SEQ_REF_ARRAY_KEYS = new Set(['sourceEventSeqs', 'messageSeqs'])
+
+/**
+ * Remap seq cross-references inside one event's `data` through the
+ * old→new mapping. Only values `>= threshold` are remapped: everything
+ * below the first collision is a pre-collision event whose seq is
+ * unchanged. Returns the number of remapped references.
+ */
+function remapReferences(event, threshold, map) {
+  let changed = 0
+  const walk = (node) => {
+    if (node === null || typeof node !== 'object') return
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item)
+      return
+    }
+    for (const key of Object.keys(node)) {
+      const value = node[key]
+      if (SEQ_REF_ARRAY_KEYS.has(key) && Array.isArray(value)) {
+        for (let i = 0; i < value.length; i += 1) {
+          const ref = value[i]
+          if (typeof ref === 'number' && ref >= threshold && map.has(ref)) {
+            value[i] = map.get(ref)
+            changed += 1
+          }
+        }
+      } else if (key === 'sourceEventSeq' && typeof value === 'number' && value >= threshold && map.has(value)) {
+        node[key] = map.get(value)
+        changed += 1
+      } else {
+        walk(value)
+      }
+    }
+  }
+  walk(event.data)
+  return changed
+}
+
+/**
+ * Repair the scanned log. Mutates the events array's `seq` fields and the
+ * reference fields it remaps.
+ * @param events - events from {@link scanEvents}.
+ * @param issue - the first issue from {@link scanEvents}, if any.
+ * @returns the action taken, the renumber delta, and counts.
+ */
+export function repairEvents(events, issue) {
+  if (issue === undefined) {
+    return { events, action: 'none', fromIndex: -1, delta: 0, changed: 0, refsChanged: 0 }
+  }
+  if (issue.kind !== 'duplicate') {
+    const kept = events.slice(0, issue.index)
+    return {
+      events: kept,
+      action: 'truncate',
+      fromIndex: issue.index,
+      delta: 0,
+      changed: events.length - kept.length,
+      refsChanged: 0,
+      message: issue.message,
+    }
+  }
+  // Duplicate seq: renumber every event from the first collision onward so
+  // `seq === index` again. The old→new map resolves cross-references: values
+  // below the collision index name pre-collision events (unchanged); values
+  // at or above it can only name post-collision events (renumbered).
+  const repaired = events
+  const map = new Map()
+  for (let index = issue.index; index < repaired.length; index += 1) {
+    const event = repaired[index]
+    map.set(event.seq, index)
+    event.seq = index
+  }
+  let refsChanged = 0
+  for (const event of repaired) {
+    refsChanged += remapReferences(event, issue.index, map)
+  }
+  return {
+    events: repaired,
+    action: 'renumber',
+    fromIndex: issue.index,
+    delta: issue.index - issue.got,
+    changed: repaired.length - issue.index,
+    refsChanged,
+    message: issue.message,
+  }
+}
+
+/**
+ * Encode the repaired log: the original header line verbatim, then one JSON
+ * row per event (packed chunk rows are expanded — the standard reader
+ * accepts unpacked rows).
+ */
+export function encodeLog(header, events) {
+  const lines = [header]
+  for (const event of events) lines.push(JSON.stringify(event))
+  return `${lines.join('\n')}\n`
+}

package/scripts/repair-session.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * @xmoon76/dsh-pi-tui/scripts/repair-session — repair a corrupted dsh
+ * session log.
+ *
+ * dsh persists sessions under `$DSH_HOME/sessions/<workspace>/<id>/` as
+ * `session.jsonl.zstd` (concatenated Zstandard frames of JSONL). A session
+ * written concurrently by two dsh processes can end up with duplicate or
+ * missing seq numbers and become unreadable (`corrupt session log: seq gap
+ * in committed region`). This script repairs the artifact and verifies the
+ * result with the same storage-format scan the reader performs.
+ *
+ * Usage:
+ *   node repair-session.mjs <session-id> [--yes] [--dsh-dir <path>] [--dsh-home <path>]
+ *   node repair-session.mjs --scan [--dsh-dir <path>] [--dsh-home <path>]
+ *
+ * - Default is a dry run: reports the diagnosis and the repair plan without
+ *   touching the file. Pass `--yes` to apply.
+ * - Before writing, the original artifact is ALWAYS backed up to
+ *   `<artifact>.bak-<timestamp>`; a failed backup aborts the write.
+ * - `--scan` read-only scans every persisted session and lists the damaged
+ *   ids (one line each, `CORRUPT <id>: <reason>`).
+ *
+ * Dependencies: resolves `decodeStorageRecord`/`packChunkRuns` from the
+ * installed dsh (`@deepseek-ai/dsh-session`). Resolution order:
+ * `--dsh-dir`, then the `dsh` launcher on PATH (its realpath walks up to
+ * the owning package), then `$DSH_HOME`/`DSH_DIR`.
+ */
+
+import { copyFileSync, existsSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, dirname, join, resolve } from 'node:path'
+import { createRequire } from 'node:module'
+import { spawnSync } from 'node:child_process'
+import { zstdCompressSync, zstdDecompressSync } from 'node:zlib'
+import { compressLog, decompressFrames, encodeLog, repairEvents, scanEvents, scanZstdLayout } from './repair-core.mjs'
+
+const USAGE = `usage:
+  node repair-session.mjs <session-id> [--yes] [--dsh-dir <path>] [--dsh-home <path>]
+  node repair-session.mjs --scan [--dsh-dir <path>] [--dsh-home <path>]
+
+repair one session log (dry run by default; --yes applies with a backup),
+or --scan all persisted sessions read-only and list damaged ids.`
+
+/** Locate the dsh package directory (the one whose manifest is @deepseek-ai/dsh). */
+function findDshPackageDir(from) {
+  let dir = from
+  for (let depth = 0; depth < 12; depth += 1) {
+    const manifest = join(dir, 'package.json')
+    if (existsSync(manifest)) {
+      try {
+        const pkg = JSON.parse(readFileSync(manifest, 'utf8'))
+        if (pkg.name === '@deepseek-ai/dsh') return dir
+      } catch {
+        // Not a readable manifest; keep walking up.
+      }
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+  return undefined
+}
+
+/** Resolve the dsh package directory from --dsh-dir / PATH / env. */
+function resolveDshDir(explicit) {
+  if (explicit !== undefined) {
+    const dir = findDshPackageDir(resolve(explicit))
+    if (dir !== undefined) return dir
+    throw new Error(`--dsh-dir ${explicit}: no @deepseek-ai/dsh package found under this path`)
+  }
+  const fromBin = spawnSync('which', ['dsh'], { encoding: 'utf8' }).stdout.trim()
+  if (fromBin !== '') {
+    const dir = findDshPackageDir(dirname(realpathSync(fromBin)))
+    if (dir !== undefined) return dir
+  }
+  const env = process.env.DSH_DIR
+  if (env !== undefined && env !== '') {
+    const dir = findDshPackageDir(resolve(env))
+    if (dir !== undefined) return dir
+  }
+  throw new Error('cannot locate the dsh installation; pass --dsh-dir <path-to-dsh-package>')
+}
+
+/** Load @deepseek-ai/dsh-session from the dsh install. */
+function loadDshSession(dshDir) {
+  const require = createRequire(join(dshDir, 'package.json'))
+  return require('@deepseek-ai/dsh-session')
+}
+
+/** The dsh home: $DSH_HOME, else ~/.dsh. */
+function dshHome() {
+  const explicit = process.env.DSH_HOME
+  if (explicit !== undefined && explicit !== '') return explicit
+  return join(homedir(), '.dsh')
+}
+
+/** Find the artifact file for one session id (or undefined). */
+function findSessionArtifact(home, id) {
+  const roots = readdirSync(join(home, 'sessions'), { withFileTypes: true })
+  for (const entry of roots) {
+    if (!entry.isDirectory()) continue
+    const dir = join(home, 'sessions', entry.name, id)
+    if (!existsSync(dir)) continue
+    for (const name of ['session.jsonl.zstd', 'session.jsonl']) {
+      const path = join(dir, name)
+      if (existsSync(path)) return { path, compression: name.endsWith('.zstd') ? 'zstd' : 'none' }
+    }
+  }
+  return undefined
+}
+
+/** Read one artifact into decompressed text, validating the zstd frame layout. */
+function readArtifact(path, compression) {
+  if (compression === 'none') return { text: readFileSync(path, 'utf8'), layoutIssue: undefined }
+  const buffer = readFileSync(path)
+  const layout = scanZstdLayout(buffer, zstdDecompressSync)
+  return { text: decompressFrames(buffer, zstdDecompressSync).text, layoutIssue: layout.ok ? undefined : layout.issue }
+}
+
+/** Write one artifact back: backup first, then atomic tmp+rename (0600 like the harness). */
+function writeArtifact(path, compression, text) {
+  const backup = `${path}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`
+  try {
+    copyFileSync(path, backup)
+  } catch (error) {
+    throw new Error(`backup failed (${error instanceof Error ? error.message : String(error)}); refusing to write`)
+  }
+  const tmp = `${path}.repair-tmp-${process.pid}`
+  const bytes = compression === 'none' ? Buffer.from(text, 'utf8') : compressLog(text, zstdCompressSync)
+  try {
+    writeFileSync(tmp, bytes, { mode: 0o600 })
+    renameSync(tmp, path)
+  } catch (error) {
+    try {
+      // Restore the backup so a failed write never leaves a half file.
+      copyFileSync(backup, path)
+    } catch {
+      // Best effort.
+    }
+    throw error
+  }
+  return backup
+}
+
+/** Scan every persisted session read-only; returns damaged entries. */
+function scanAll(home, decodeStorageRecord) {
+  const damaged = []
+  const roots = readdirSync(join(home, 'sessions'), { withFileTypes: true })
+  for (const entry of roots) {
+    if (!entry.isDirectory()) continue
+    const workspaceDir = join(home, 'sessions', entry.name)
+    for (const sessionEntry of readdirSync(workspaceDir, { withFileTypes: true })) {
+      if (!sessionEntry.isDirectory()) continue
+      const dir = join(workspaceDir, sessionEntry.name)
+      for (const name of ['session.jsonl.zstd', 'session.jsonl']) {
+        const path = join(dir, name)
+        if (!existsSync(path)) continue
+        const compression = name.endsWith('.zstd') ? 'zstd' : 'none'
+        const id = basename(dir)
+        try {
+          const { text, layoutIssue } = readArtifact(path, compression)
+          const { issue } = scanEvents(text, decodeStorageRecord)
+          if (layoutIssue !== undefined || issue !== undefined) {
+            damaged.push({
+              id,
+              path,
+              issue: { kind: layoutIssue !== undefined ? 'layout' : issue.kind, message: layoutIssue ?? issue.message },
+            })
+          }
+        } catch (error) {
+          damaged.push({ id, path, issue: { kind: 'unreadable', message: error instanceof Error ? error.message : String(error) } })
+        }
+      }
+    }
+  }
+  return damaged
+}
+
+const args = process.argv.slice(2)
+const flags = { scan: false, yes: false, dshDir: undefined }
+const positional = []
+for (let i = 0; i < args.length; i += 1) {
+  const arg = args[i]
+  if (arg === '--scan') flags.scan = true
+  else if (arg === '--yes') flags.yes = true
+  else if (arg === '--dsh-dir') flags.dshDir = args[++i]
+  else if (arg === '--dsh-home') process.env.DSH_HOME = args[++i]
+  else if (arg === '--help' || arg === '-h') {
+    console.log(USAGE)
+    process.exit(0)
+  } else positional.push(arg)
+}
+
+function main() {
+  const home = dshHome()
+  const sessionsRoot = join(home, 'sessions')
+  if (!existsSync(sessionsRoot)) {
+    console.error(`no sessions directory at ${sessionsRoot}`)
+    process.exit(2)
+  }
+  const dshDir = resolveDshDir(flags.dshDir)
+  const { decodeStorageRecord } = loadDshSession(dshDir)
+
+  if (flags.scan) {
+    const damaged = scanAll(home, decodeStorageRecord)
+    if (damaged.length === 0) {
+      console.log('no damaged sessions found')
+      process.exit(0)
+    }
+    for (const entry of damaged) {
+      console.log(`CORRUPT ${entry.id}: ${entry.issue.message}`)
+    }
+    console.log(`\n${damaged.length} damaged session(s); repair one with: node repair-session.mjs <session-id> --yes`)
+    process.exit(1)
+  }
+
+  if (positional.length !== 1) {
+    console.error(USAGE)
+    process.exit(2)
+  }
+  const id = positional[0]
+  const artifact = findSessionArtifact(home, id)
+  if (artifact === undefined) {
+    console.error(`session ${id}: no artifact found under ${sessionsRoot}`)
+    process.exit(2)
+  }
+
+  const { text, layoutIssue } = readArtifact(artifact.path, artifact.compression)
+  const { header, events, issue } = scanEvents(text, decodeStorageRecord)
+  if (layoutIssue === undefined && issue === undefined) {
+    console.log(`session ${id}: log is contiguous (${events.length} events) and the frame layout is valid; nothing to repair`)
+    process.exit(0)
+  }
+  // Content repair (renumber/truncate) applies when the event stream is
+  // damaged; a layout-damaged log (e.g. whole-log single frame) is re-framed.
+  const plan = issue === undefined ? undefined : repairEvents(events, issue)
+  if (layoutIssue !== undefined) console.log(`session ${id}: ${layoutIssue}`)
+  if (issue !== undefined) console.log(`session ${id}: ${issue.message}`)
+  console.log(`  file: ${artifact.path}`)
+  if (layoutIssue !== undefined) {
+    console.log('  plan: re-frame the log (dsh requires the header line alone in the first frame, one frame per flush batch)')
+  }
+  if (plan !== undefined) {
+    if (plan.action === 'renumber') {
+      console.log(`  plan: renumber ${plan.changed} event(s) from seq ${issue.got} by +${plan.delta} (${plan.refsChanged} reference(s) remapped)`)
+    } else if (plan.action === 'truncate') {
+      console.log(`  plan: truncate ${plan.changed} trailing event(s) after index ${plan.fromIndex} (missing/undecodable events cannot be recreated)`)
+    }
+  }
+
+  if (!flags.yes) {
+    console.log('  dry run: nothing written; pass --yes to apply (a backup is created first)')
+    process.exit(1)
+  }
+
+  const output = encodeLog(header, plan === undefined ? events : plan.events)
+  const backup = writeArtifact(artifact.path, artifact.compression, output)
+  console.log(`  backup: ${backup}`)
+  console.log(`  wrote: ${artifact.path}`)
+
+  // Verify with the same checks the reader performs: frame layout AND event contiguity.
+  const verifyArtifact = readArtifact(artifact.path, artifact.compression)
+  const verifyEvents = scanEvents(verifyArtifact.text, decodeStorageRecord)
+  if (verifyArtifact.layoutIssue !== undefined || verifyEvents.issue !== undefined) {
+    console.error(`  VERIFY FAILED: ${verifyArtifact.layoutIssue ?? verifyEvents.issue.message} — original preserved in ${backup}`)
+    process.exit(1)
+  }
+  console.log(`  verify: valid frame layout, contiguous, ${verifyEvents.events.length} event(s)`)
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(`repair-session: ${error instanceof Error ? error.message : String(error)}`)
+  process.exit(1)
+}