dsh-vscode-mode 0.19.2 → 0.20.1

package/src/officialCapture.ts

@@ -0,0 +1,203 @@
+/** Deferred official-event collection; no private snapshot access. @author ddj 2026年10月26号 */
+import { captureState, repairPaths, saveSnapshot } from './reviewDb.js'
+import type { OfficialDiff, OfficialSummary, ReviewSnapshot } from './shared/review.js'
+import type { Ctx } from './store.js'
+import { loadBucket } from './store.js'
+import { log } from './log.js'
+
+interface SourceEvent { type: string; seq: number; data: { turn?: number } }
+interface SourceSession { id: string; inheritedEventCount?: number; header?: { cwd?: string } }
+interface SourceService {
+  summary(sessionId: string, seq: number): OfficialSummary | undefined
+  diff(sessionId: string, seq: number, index: number, signal: AbortSignal): Promise<OfficialDiff | undefined>
+}
+interface CaptureTask { sessionId: string; turn: number; seq: number; cwd?: string }
+export interface CaptureDeps {
+  source: () => SourceService | undefined
+  prepare(cwd: string): Promise<void>
+  identity(cwd: string, path: string): Promise<string>
+  persist: typeof saveSnapshot
+  state: typeof captureState
+  report(message: string): void
+  timeoutMs?: number
+  retryMs?: number
+}
+
+/** @public @author ddj 2026年10月26号 @param deps Official source and workspace adapters. @returns Bounded collector with cancellation and deferred event reads. */
+export function createCollector(deps: CaptureDeps) {
+  const waiting: CaptureTask[] = []
+  const pending = new Set<string>()
+  const controller = new AbortController()
+  let active = 0
+  let stopped = false
+  const running = new Set<string>()
+  const tasks = new Set<Promise<void>>()
+
+  /** @private @author ddj 2026年10月26号 @param ms Delay; aborted on unload. @returns Deferred completion, not synchronous observer work. */
+  function pause(ms: number): Promise<void> {
+    return new Promise((resolve) => {
+      /** @private @author ddj 2026年10月26号 Release both timer and listener. */
+      function finish(): void { clearTimeout(timer); controller.signal.removeEventListener('abort', finish); resolve() }
+      const timer = setTimeout(finish, ms)
+      controller.signal.addEventListener('abort', finish, { once: true })
+      if (stopped) finish()
+    })
+  }
+
+  /** @private @author ddj 2026年10月26号 @param task Source identity. @returns Complete payload staged before one database transaction. */
+  async function collect(task: CaptureTask): Promise<void> {
+    await pause(0) // Official append publishes before summary registration.
+    if (stopped) return
+    // The session header may predate cd. Bind the durable inbox only after
+    // reading the official event cwd; header cwd is a gap-report fallback.
+    const source = deps.source()
+    if (!source) throw new Error('官方 workspaceChanges 服务不可用')
+    let summary: OfficialSummary | undefined
+    for (let attempt = 0; attempt < 4 && !stopped; attempt++) {
+      summary = source.summary(task.sessionId, task.seq)
+      if (summary) break
+      await pause(deps.retryMs ?? 100)
+    }
+    if (!summary || stopped) throw new Error('官方事件已公告，但 summary 已失效或尚不可用')
+    // Detach all source aliases before asynchronous work; never resolve against current session cwd.
+    summary = structuredClone(summary)
+    if (summary.turn !== task.turn) throw new Error('官方 summary 轮次与事件不一致')
+    task.cwd = summary.cwd
+    await deps.prepare(summary.cwd)
+    if (stopped) return
+    deps.state(summary.cwd, { ...task, error: '' }, 'queued')
+    try {
+      const files = []
+      for (const [index, file] of summary.files.entries()) {
+        if (stopped) return
+        const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(deps.timeoutMs ?? 10000)])
+        const diff = await readDiff(source, task, index, signal)
+        if (!diff || diff.path !== file.path || diff.display !== file.display) throw new Error('官方文件差异缺失或身份不一致')
+        const identity = await deps.identity(summary.cwd, file.path)
+        files.push({ identity, diff: structuredClone(diff) })
+      }
+      if (!stopped) deps.persist(summary.cwd, { ...task, sourceKind: 'official', capturedAt: new Date().toISOString(), summary, files })
+    } catch (error) {
+      if (!stopped) deps.state(summary.cwd, { ...task, error: String(error) }, 'gap')
+      throw error
+    }
+  }
+
+  /** @private @author ddj 2026年10月26号 Starts at most two independent event reads, with each event's file reads serial. */
+  function drain(): void {
+    while (!stopped && active < 2 && waiting.length) {
+      const index = waiting.findIndex((task) => !running.has(JSON.stringify([task.sessionId, task.turn])))
+      if (index < 0) break
+      const task = waiting.splice(index, 1)[0]
+      const key = JSON.stringify([task.sessionId, task.turn, task.seq])
+      const turnKey = JSON.stringify([task.sessionId, task.turn])
+      active++; running.add(turnKey)
+      const work = collect(task).catch(async (error) => {
+        deps.report(`官方差异采集 ${key}: ${String(error)}`)
+        if (!stopped && task.cwd) {
+          try { await deps.prepare(task.cwd); if (!stopped) deps.state(task.cwd, { ...task, error: String(error) }, 'gap') }
+          catch (failure) { deps.report(`官方缺口落盘失败: ${String(failure)}`) }
+        }
+      }).finally(() => {
+        active--; pending.delete(key); running.delete(turnKey); tasks.delete(work); drain()
+      })
+      tasks.add(work)
+    }
+  }
+
+  /** @public @author ddj 2026年10月26号 @param session Source session. @param event Published event; inherited fork events are excluded. */
+  function enqueue(session: SourceSession, event: SourceEvent): void {
+    if (stopped || event.type !== 'workspace/changes' || !Number.isSafeInteger(event.data?.turn)
+      || !Number.isSafeInteger(event.seq) || event.seq < (session.inheritedEventCount ?? 0)) return
+    const task = { sessionId: session.id, turn: event.data.turn!, seq: event.seq, cwd: session.header?.cwd }
+    const key = JSON.stringify([task.sessionId, task.turn, task.seq])
+    if (pending.has(key)) return
+    pending.add(key); waiting.push(task); drain()
+  }
+
+  /** @public @author ddj 2026年10月26号 @returns Bounded durability checkpoint including work queued while active tasks finish. */
+  async function flush(): Promise<void> {
+    const deadline = Date.now() + (deps.timeoutMs ?? 10000)
+    while (tasks.size && !stopped && Date.now() < deadline) {
+      let timer: ReturnType<typeof setTimeout> | undefined
+      await Promise.race([Promise.all([...tasks]), new Promise<void>((resolve) => { timer = setTimeout(resolve, Math.max(1, deadline - Date.now())) })])
+      clearTimeout(timer)
+    }
+  }
+
+  /** @public @author ddj 2026年10月26号 @returns Bounded drain, then cancel timers and reads; incomplete staging cannot publish. */
+  async function dispose(): Promise<void> {
+    await flush()
+    stopped = true; controller.abort(); waiting.length = 0; pending.clear()
+    // Never await an uncooperative external adapter after the deadline.
+    // Every publish path checks stopped; late completion cannot reopen the database.
+  }
+  return { enqueue, flush, dispose }
+}
+
+/** @private @author ddj 2026年10月26号 @param source Public service. @param task Event. @param index File position. @param signal Cancellation/deadline. @returns A read bounded even if an adapter ignores abort. */
+async function readDiff(source: SourceService, task: CaptureTask, index: number, signal: AbortSignal): Promise<OfficialDiff | undefined> {
+  return new Promise((resolve, reject) => {
+    /** @private @author ddj 2026年10月26号 Propagate timeout or unload. */
+    function aborted(): void { reject(signal.reason) }
+    signal.addEventListener('abort', aborted, { once: true })
+    if (signal.aborted) { aborted(); return }
+    Promise.resolve().then(() => source.diff(task.sessionId, task.seq, index, signal))
+      .then(resolve, reject).finally(() => signal.removeEventListener('abort', aborted))
+  })
+}
+
+/** @public @author ddj 2026年10月26号 @param ctx Host lifecycle owner; services remain optional for older Hosts. */
+export function installCapture(ctx: Ctx, onSnapshot?: (cwd: string, snapshot: ReviewSnapshot) => void): () => Promise<void> {
+  const collector = createCollector({
+    source: () => ctx.get('workspaceChanges'),
+    prepare: async (cwd) => { await loadBucket(ctx, cwd); await repairPaths(cwd, resolvePath) },
+    identity: resolvePath,
+    persist: (cwd, snapshot) => {
+      const saved = saveSnapshot(cwd, snapshot)
+      onSnapshot?.(cwd, snapshot)
+      return saved
+    }, state: captureState, report: (message) => log.warn(message),
+  })
+  // Subscribe first: seed reads must not create a live-event race window.
+  ctx.on('session/event', collector.enqueue)
+  ctx.on('session/created', backfill)
+  ctx.on('session/flush', collector.flush)
+  for (const session of ctx.get('sessions').list()) void backfill(session)
+  return collector.dispose
+
+  /** @private @author ddj 2026年10月27号 @param cwd Source workspace. @param path Official relative path. @returns Backend-owned process path; never stringify opaque targets. @throws Invalid backend path. */
+  async function resolvePath(cwd: string, path: string): Promise<string> {
+    const fs = ctx.get('fs')
+    const target = await fs.resolve(path, { cwd })
+    const processPath = fs.processPath(target)
+    if (typeof processPath !== 'string' || !processPath || processPath === '[object Object]') {
+      throw new Error('官方文件路径解析失败')
+    }
+    return processPath
+  }
+
+  /** @private @author ddj 2026年10月26号 @param session Live session. Only public async reads, excluding inherited records. */
+  async function backfill(session: SourceSession): Promise<void> {
+    const query = ctx.get('sessionQuery')
+    if (!query?.listEvents || !query?.readEvent) {
+      log.warn('官方历史补采不可用：缺少 sessionQuery；后续实时事件仍会采集')
+      return
+    }
+    try {
+      // Repair durable history independently: official summaries do not survive Host restart.
+      // Each saved snapshot resolves against its own cwd, not the current session directory.
+      if (session.header?.cwd) {
+        await loadBucket(ctx, session.header.cwd)
+        await repairPaths(session.header.cwd, resolvePath)
+      }
+      // Semantic search omits structural events; only the raw metadata list contains workspace/changes.
+      const events = await query.listEvents(session.id)
+      for (const event of events) {
+        if (event.type !== 'workspace/changes' || event.seq < (session.inheritedEventCount ?? 0)) continue
+        const window = await query.readEvent({ sessionId: session.id, seq: event.seq })
+        collector.enqueue(session, window.target)
+      }
+    } catch (error) { log.warn('官方历史补采失败：' + String(error)) }
+  }
+}

package/src/reviewCapture.ts

@@ -0,0 +1,112 @@
+/** Independent byte evidence; official diff remains the only display authority. @author ddj 2026年10月27号 */
+import { rawReviewFile, evidenceBlocks } from './reviewEvidence.js'
+import type { RawReviewFile } from './reviewEvidence.js'
+import type { ReviewSnapshot } from './shared/review.js'
+import { reviewDb } from './reviewDb.js'
+import { resolveTarget } from './store.js'
+import type { Ctx } from './store.js'
+import { log } from './log.js'
+
+interface ByteChain { before: RawReviewFile; after: RawReviewFile; busy: boolean; invalid: boolean }
+interface EvidenceCapture {
+  persist(cwd: string, snapshot: ReviewSnapshot): void
+  dispose(): void
+}
+
+/** @public @author ddj 2026年10月27号 @param ctx Host lifecycle owner. @returns Scoped byte recorder; failures disable undo evidence only, never tool execution. */
+export function installEvidence(ctx: Ctx): EvidenceCapture {
+  const chains = new Map<string, Map<string, ByteChain>>()
+  const staged = new Map<string, Map<string, ByteChain>>()
+  let stopped = false
+  ctx.on('tools/execute', aroundTool)
+  ctx.on('session/event', onEvent)
+  ctx.on('session/disposed', onDisposed)
+
+  /** @private @author ddj 2026年10月27号 @param session Disposed owner. Drops optional in-memory evidence, never persisted official facts. */
+  function onDisposed(session: { id: string }): void { chains.delete(session.id) }
+
+  /** @private @author ddj 2026年10月27号 @returns Current bounded capture footprint, excluding transient filesystem reads. */
+  function footprint(): number {
+    let bytes = 0
+    for (const group of [chains, staged]) {
+      for (const files of group.values()) {
+        for (const chain of files.values()) bytes += chain.before.bytes.length + chain.after.bytes.length
+      }
+    }
+    return bytes
+  }
+
+  /** @private @author ddj 2026年10月27号 @param exec Allowed tool dispatch. @param next Original dispatch. @returns Original result unchanged, regardless of capture failure. */
+  async function aroundTool(exec: any, next: () => Promise<any>): Promise<any> {
+    const session = exec.agent?.session
+    const path = exec.arguments?.file_path
+    if (stopped || !session?.id || !['edit', 'write'].includes(exec.name) || typeof path !== 'string') return next()
+    let fs: any
+    let chain: ByteChain | undefined
+    let target: any
+    try {
+      if ((chains.size >= 16 && !chains.has(session.id)) || footprint() >= 32 * 1024 * 1024) return next()
+      fs = ctx.get('fs')
+      target = await resolveTarget(ctx, session, path)
+      const identity = fs.processPath(target)
+      const before = await readRaw(fs, target, exec.signal)
+      let files = chains.get(session.id)
+      if (!files) { files = new Map(); chains.set(session.id, files) }
+      if (files.size >= 64 && !files.has(identity)) return next()
+      chain = files.get(identity)
+      if (!chain) { chain = { before, after: before, busy: false, invalid: false }; files.set(identity, chain) }
+      if (chain.busy || chain.after.hash !== before.hash) chain.invalid = true
+      chain.busy = true
+    } catch { /* No trustworthy read means no undo evidence, not a failed user tool. */ }
+    try { return await next() }
+    finally {
+      if (chain) {
+        try { chain.after = await readRaw(fs, target, exec.signal) } catch { chain.invalid = true }
+        chain.busy = false
+      }
+    }
+  }
+
+  /** @private @author ddj 2026年10月27号 @param session Source session. @param event Published official turn. Freezes the chain before the next turn can mutate it. */
+  function onEvent(session: any, event: any): void {
+    if (stopped || event.type !== 'workspace/changes') return
+    const files = chains.get(session.id)
+    chains.delete(session.id)
+    if (!files || staged.size >= 128) return
+    staged.set(JSON.stringify([session.id, event.seq]), structuredClone(files))
+  }
+
+  /** @public @author ddj 2026年10月27号 @param cwd Official workspace. @param snapshot Committed official facts. Persists only independently validated, exact-correspondence byte chains. */
+  function persist(cwd: string, snapshot: ReviewSnapshot): void {
+    const key = JSON.stringify([snapshot.sessionId, snapshot.seq])
+    const files = staged.get(key)
+    staged.delete(key)
+    if (!files || stopped) return
+    const db = reviewDb(cwd)
+    for (const file of snapshot.files) {
+      const chain = files.get(file.identity)
+      if (!chain || chain.invalid || chain.busy) continue
+      try {
+        const evidence = { before: chain.before, after: chain.after }
+        evidenceBlocks(file.diff, evidence)
+        db.prepare(`INSERT OR IGNORE INTO review_evidence(file_id,payload)
+          SELECT id,? FROM review_files WHERE session_id=? AND turn=? AND seq=? AND identity=?`)
+          .run(JSON.stringify(evidence), snapshot.sessionId, snapshot.turn, snapshot.seq, file.identity)
+      } catch (error) { log.warn('官方回滚证据不可用：' + String(error)) }
+    }
+  }
+
+  /** @public @author ddj 2026年10月27号 Release bounded in-memory images after capture has drained. */
+  function dispose(): void { stopped = true; chains.clear(); staged.clear() }
+  return { persist, dispose }
+}
+
+/** @private @author ddj 2026年10月27号 @param fs Public filesystem. @param target Backend identity. @returns Raw bounded file or confirmed missing. @throws Any non-missing read error. */
+async function readRaw(fs: any, target: any, signal?: AbortSignal): Promise<RawReviewFile> {
+  try { return rawReviewFile(await fs.readBytes(target, signal, 1024 * 1024)) }
+  catch (error) {
+    const code = (error as { code?: string }).code
+    if (code === 'ENOENT' || code === 'FS_NOT_FOUND') return rawReviewFile(null)
+    throw error
+  }
+}

package/src/reviewDb.ts

@@ -0,0 +1,285 @@
+/** Official history shares the archive connection, but never the legacy callId namespace. @author ddj 2026年10月26号 */
+import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { archiveDbFile } from './paths.js'
+import { reviewBlocks } from './shared/reviewRegions.js'
+import type { ReviewBlockState } from './shared/reviewRegions.js'
+import type { DatabaseSync } from 'node:sqlite'
+import { activeReady, dbFor } from './archiveDb.js'
+import type { CaptureGap, DecideReview, OfficialDiff, ReviewDetail, ReviewItem, ReviewPage, ReviewSnapshot } from './shared/review.js'
+
+type Row = Record<string, string | number | null>
+
+/** @public @author ddj 2026年10月26号 @param cwd Migrated workspace. @returns Schema4 connection; DDL and version change roll back together. */
+export function reviewDb(cwd: string): DatabaseSync {
+  if (!activeReady(cwd)) throw new Error('官方审查要求先完成活跃库迁移')
+  const db = dbFor(cwd)
+  const version = db.prepare("SELECT value FROM metadata WHERE name='schema'").get() as Row
+  if (version.value === '4') { migrateBlocks(cwd, db); return db }
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    db.exec(`CREATE TABLE review_snapshots (
+      session_id TEXT NOT NULL, turn INTEGER NOT NULL, seq INTEGER NOT NULL,
+      payload TEXT NOT NULL, digest TEXT NOT NULL, current INTEGER NOT NULL DEFAULT 1,
+      PRIMARY KEY(session_id,turn,seq));
+      CREATE TABLE review_files (
+      id TEXT PRIMARY KEY, session_id TEXT NOT NULL, turn INTEGER NOT NULL, seq INTEGER NOT NULL,
+      identity TEXT NOT NULL, summary TEXT NOT NULL, diff TEXT NOT NULL,
+      decision TEXT NOT NULL DEFAULT 'pending', revision INTEGER NOT NULL DEFAULT 0,
+      current INTEGER NOT NULL DEFAULT 1);
+      CREATE INDEX review_pending ON review_files(current,decision,id);
+      CREATE INDEX review_turn ON review_files(session_id,turn,seq);
+      CREATE TABLE review_capture (
+      session_id TEXT NOT NULL, turn INTEGER NOT NULL, seq INTEGER NOT NULL,
+      state TEXT NOT NULL, error TEXT, PRIMARY KEY(session_id,turn,seq));
+      CREATE TABLE review_ops (
+      operation_id TEXT PRIMARY KEY, request TEXT NOT NULL, state TEXT NOT NULL, result TEXT,
+      evidence TEXT);
+      UPDATE metadata SET value='4' WHERE name='schema';`)
+    db.exec('COMMIT')
+  } catch (error) {
+    if (db.isTransaction) db.exec('ROLLBACK')
+    throw error
+  }
+  migrateBlocks(cwd, db)
+  return db
+}
+
+/** @private @author ddj 2026年10月27号 @param cwd Workspace backup identity. @param db Open schema4 database. Extends the official-review sub-schema without changing legacy archive schema. @throws Migration failure, leaving prior decisions intact. */
+function migrateBlocks(cwd: string, db: DatabaseSync): void {
+  if (db.prepare("SELECT value FROM metadata WHERE name='review_schema'").get()) return
+  const backup = archiveDbFile(cwd) + '.before-review-blocks.bak'
+  if (!existsSync(backup)) db.exec(`VACUUM INTO '${backup.replace(/'/g, "''")}'`)
+
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    db.exec(`CREATE TABLE review_blocks (file_id TEXT NOT NULL, block_id TEXT NOT NULL,
+      decision TEXT NOT NULL, PRIMARY KEY(file_id,block_id));
+      CREATE TABLE review_evidence (file_id TEXT PRIMARY KEY, payload TEXT NOT NULL);
+      INSERT INTO metadata(name,value) VALUES('review_schema','2');`)
+    const files = db.prepare('SELECT id,diff,decision FROM review_files').all() as Row[]
+    for (const file of files) seedBlocks(db, String(file.id), JSON.parse(String(file.diff)), String(file.decision))
+    db.exec('COMMIT')
+  } catch (error) {
+    if (db.isTransaction) db.exec('ROLLBACK')
+    throw error
+  }
+}
+
+/** @private @author ddj 2026年10月27号 @param db Transaction connection. @param id File record. @param diff Immutable official source. @param decision Prior file decision. Seeds deterministic blocks without changing source facts. */
+function seedBlocks(db: DatabaseSync, id: string, diff: OfficialDiff, decision: string): void {
+  const insert = db.prepare('INSERT INTO review_blocks VALUES(?,?,?)')
+  for (const block of reviewBlocks(diff)) insert.run(id, block.id, decision)
+}
+
+/** @private @author ddj 2026年10月26号 @param text Canonical serialized input. @returns Collision-resistant identity. */
+function digest(text: string): string { return createHash('sha256').update(text).digest('hex') }
+
+/** @public @author ddj 2026年10月26号 @param cwd Workspace. @param snapshot Complete staged event. @returns False for late versions; commits facts, pointers and capture state atomically. */
+export function saveSnapshot(cwd: string, snapshot: ReviewSnapshot): boolean {
+  const db = reviewDb(cwd)
+  const { sessionId, turn, seq } = snapshot
+  if (snapshot.summary.cwd !== cwd || snapshot.summary.turn !== turn || snapshot.files.length !== snapshot.summary.files.length) throw new Error('官方采集不完整')
+  const identities = new Set(snapshot.files.map((file) => file.identity))
+  if (identities.size !== snapshot.files.length) throw new Error('官方文件身份重复')
+  // capturedAt is acquisition metadata, not part of the immutable source identity.
+  const hash = digest(JSON.stringify({ ...snapshot, capturedAt: '' }))
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    const prior = db.prepare('SELECT digest FROM review_snapshots WHERE session_id=? AND turn=? AND seq=?').get(sessionId, turn, seq) as Row | undefined
+    if (prior && prior.digest !== hash) throw new Error('同一官方事件的内容发生变化')
+    const latest = db.prepare('SELECT MAX(seq) AS seq FROM review_snapshots WHERE session_id=? AND turn=?').get(sessionId, turn) as Row
+    if (prior || (typeof latest.seq === 'number' && latest.seq > seq)) { db.exec('COMMIT'); return false }
+    insertSnapshot(db, snapshot, hash)
+    db.prepare("INSERT INTO review_capture VALUES(?,?,?,'complete',NULL) ON CONFLICT(session_id,turn,seq) DO UPDATE SET state='complete',error=NULL").run(sessionId, turn, seq)
+    db.exec('COMMIT')
+    return true
+  } catch (error) {
+    if (db.isTransaction) db.exec('ROLLBACK')
+    throw error
+  }
+}
+
+/** @public @author ddj 2026年10月27号 @param cwd Workspace. @param resolvePath Backend path adapter. @returns Repairs only historical object-string identities; preserves IDs, decisions and immutable official facts. @throws Resolution or concurrent payload changes. */
+export async function repairPaths(cwd: string, resolvePath: (cwd: string, path: string) => Promise<string>): Promise<void> {
+  const db = reviewDb(cwd)
+  const broken = db.prepare(`SELECT DISTINCT s.* FROM review_snapshots s JOIN review_files f
+    USING(session_id,turn,seq) WHERE f.identity='[object Object]'`).all() as Row[]
+  for (const row of broken) {
+    const snapshot = JSON.parse(String(row.payload)) as ReviewSnapshot
+    for (const file of snapshot.files) {
+      if (file.identity !== '[object Object]') continue
+      file.identity = await resolvePath(snapshot.summary.cwd, file.diff.path)
+      if (!file.identity || file.identity === '[object Object]') throw new Error('官方文件路径修复失败')
+    }
+    if (new Set(snapshot.files.map((file) => file.identity)).size !== snapshot.files.length) throw new Error('官方文件身份重复')
+
+    // All IO is staged before locking; compare the persisted payload to avoid overwriting newer repairs.
+    db.exec('BEGIN IMMEDIATE')
+    try {
+      const current = db.prepare('SELECT payload FROM review_snapshots WHERE session_id=? AND turn=? AND seq=?')
+        .get(snapshot.sessionId, snapshot.turn, snapshot.seq) as Row | undefined
+      if (current?.payload === row.payload) {
+        for (const file of snapshot.files) {
+          db.prepare(`UPDATE review_files SET identity=? WHERE session_id=? AND turn=? AND seq=?
+            AND identity='[object Object]' AND json_extract(diff,'$.path')=?`)
+            .run(file.identity, snapshot.sessionId, snapshot.turn, snapshot.seq, file.diff.path)
+        }
+        db.prepare('UPDATE review_snapshots SET payload=?,digest=? WHERE session_id=? AND turn=? AND seq=?')
+          .run(JSON.stringify(snapshot), digest(JSON.stringify({ ...snapshot, capturedAt: '' })), snapshot.sessionId, snapshot.turn, snapshot.seq)
+      }
+      db.exec('COMMIT')
+    } catch (error) {
+      if (db.isTransaction) db.exec('ROLLBACK')
+      throw error
+    }
+  }
+}
+
+/** @private @author ddj 2026年10月26号 @param db Transaction. @param snapshot Source payload. @param hash Source digest. */
+function insertSnapshot(db: DatabaseSync, snapshot: ReviewSnapshot, hash: string): void {
+  const { sessionId, turn, seq } = snapshot
+  const previous = db.prepare('SELECT id,identity,diff,decision FROM review_files WHERE session_id=? AND turn=? AND current=1').all(sessionId, turn) as Row[]
+  db.prepare('UPDATE review_snapshots SET current=0 WHERE session_id=? AND turn=?').run(sessionId, turn)
+  db.prepare('UPDATE review_files SET current=0 WHERE session_id=? AND turn=?').run(sessionId, turn)
+  db.prepare('INSERT INTO review_snapshots VALUES(?,?,?,?,?,1)').run(sessionId, turn, seq, JSON.stringify(snapshot), hash)
+  const insert = db.prepare('INSERT INTO review_files VALUES(?,?,?,?,?,?,?,?,0,1)')
+  for (const [index, file] of snapshot.files.entries()) {
+    const encoded = JSON.stringify(file.diff)
+    const unchanged = previous.find((item) => item.identity === file.identity && item.diff === encoded)
+    const id = digest(JSON.stringify([sessionId, turn, seq, file.identity]))
+    const decision = String(unchanged?.decision ?? 'pending')
+    insert.run(id, sessionId, turn, seq, file.identity, JSON.stringify(snapshot.summary.files[index]), encoded, decision)
+    seedBlocks(db, id, file.diff, decision)
+    if (unchanged) {
+      // A same-turn republish must preserve mixed per-block decisions, not seed all blocks as mixed.
+      db.prepare(`UPDATE review_blocks SET decision=(SELECT p.decision FROM review_blocks p
+        WHERE p.file_id=? AND p.block_id=review_blocks.block_id)
+        WHERE file_id=? AND EXISTS(SELECT 1 FROM review_blocks p WHERE p.file_id=? AND p.block_id=review_blocks.block_id)`)
+        .run(unchanged.id, id, unchanged.id)
+      db.prepare('INSERT INTO review_evidence SELECT ?,payload FROM review_evidence WHERE file_id=?').run(id, unchanged.id)
+    }
+  }
+}
+
+/** @public @author ddj 2026年10月26号 @param cwd Workspace. @param gap Announced event identity. @param state Durable inbox or explicit failure. */
+export function captureState(cwd: string, gap: CaptureGap, state: 'queued' | 'gap'): void {
+  reviewDb(cwd).prepare(`INSERT INTO review_capture VALUES(?,?,?,?,?) ON CONFLICT(session_id,turn,seq)
+    DO UPDATE SET state=excluded.state,error=excluded.error WHERE review_capture.state<>'complete'`).run(gap.sessionId, gap.turn, gap.seq, state, gap.error)
+}
+
+/** @private @author ddj 2026年10月26号 @param row File and state. @returns Wire-safe summary without hunks. */
+function itemOf(row: Row): ReviewItem {
+  const summary = JSON.parse(String(row.summary))
+  const kind = row.kind ?? (JSON.parse(String(row.diff)) as OfficialDiff).kind
+  return { id: String(row.id), sessionId: String(row.session_id), turn: Number(row.turn), seq: Number(row.seq),
+    ...summary, currentPath: String(row.identity), kind: kind as ReviewItem['kind'], decision: row.decision as ReviewItem['decision'], revision: Number(row.revision), current: row.current === 1 }
+}
+
+/** @public @author ddj 2026年10月26号 @param cwd Workspace. @param cursor Page offset. @param history Include withdrawn/decided history. @returns Bounded metadata page; pending across all source sessions/turns. */
+export function reviewPage(cwd: string, cursor = 0, history = false, path?: string): ReviewPage {
+  const db = reviewDb(cwd)
+  const offset = Number.isSafeInteger(cursor) && cursor >= 0 ? cursor : 0
+  const conditions = history ? [] : ["current=1 AND decision='pending'"]
+  if (path !== undefined) conditions.push('identity=?')
+  const clause = conditions.length ? `WHERE ${conditions.join(' AND ')}` : ''
+  const parameters = path === undefined ? [offset] : [path, offset]
+  const rows = db.prepare(`SELECT id,session_id,turn,seq,identity,summary,decision,revision,current,
+    json_extract(diff,'$.kind') AS kind FROM review_files ${clause} ORDER BY rowid DESC LIMIT 51 OFFSET ?`).all(...parameters) as Row[]
+  const count = db.prepare("SELECT COUNT(*) AS n FROM review_files WHERE current=1 AND decision='pending'").get() as Row
+  const gaps = db.prepare("SELECT * FROM review_capture WHERE state<>'complete' ORDER BY seq DESC LIMIT 50").all() as Row[]
+  const capped = db.prepare(`SELECT session_id,turn,seq,json_extract(payload,'$.summary.total') AS total,
+    json_array_length(payload,'$.summary.files') AS listed FROM review_snapshots WHERE current=1
+    AND json_extract(payload,'$.summary.total')>json_array_length(payload,'$.summary.files') LIMIT 50`).all() as Row[]
+  // Navigation is metadata-only and independent of the 50-row patch-history page.
+  const files = db.prepare(`SELECT identity,MIN(json_extract(summary,'$.display')) AS label,COUNT(*) AS n
+    FROM review_files WHERE current=1 AND decision='pending' GROUP BY identity ORDER BY identity`).all() as Row[]
+  const covered = db.prepare('SELECT DISTINCT identity FROM review_files').all() as Row[]
+  return { overview: { files: files.map((row) => ({ sourceKind: 'official', path: String(row.identity), label: String(row.label), pending: Number(row.n) })),
+    coveredPaths: covered.map((row) => String(row.identity)) },
+    items: rows.slice(0, 50).map(itemOf), pending: Number(count.n), nextCursor: rows.length > 50 ? offset + 50 : null,
+    gaps: [
+      ...gaps.map((row) => ({ sessionId: String(row.session_id), turn: Number(row.turn), seq: Number(row.seq), error: String(row.error || '采集中或上次采集被中断') })),
+      ...capped.map((row) => ({ sessionId: String(row.session_id), turn: Number(row.turn), seq: Number(row.seq), error: `官方列表已截断：总计 ${row.total} 个文件，仅提供 ${row.listed} 个` })),
+    ] }
+
+}
+
+/** @public @author ddj 2026年10月26号 @param cwd Migrated workspace. @param path Legacy write target. @returns Whether any official version owns the file, including decided history. */
+export function hasOfficial(cwd: string, path: string): boolean {
+  const db = dbFor(cwd)
+  // A read guard must not acquire a migration write lock on legacy-only databases.
+  if (!db.prepare("SELECT 1 FROM sqlite_master WHERE name='review_files' AND type='table'").get()) return false
+  if (/^[A-Za-z]:[\\/]/.test(path)) {
+    return !!db.prepare("SELECT 1 FROM review_files WHERE lower(replace(identity,char(92),'/'))=? LIMIT 1")
+      .get(path.replace(/\\/g, '/').toLowerCase())
+  }
+  return !!db.prepare('SELECT 1 FROM review_files WHERE identity=? LIMIT 1').get(path)
+}
+
+/** @public @author ddj 2026年10月26号 @param cwd Workspace. @param id Immutable file identity. @returns Historical patch, not a reconstruction from disk. */
+export function reviewDetail(cwd: string, id: string): ReviewDetail | null {
+  const db = reviewDb(cwd)
+  const row = db.prepare(`SELECT f.*,json_extract(s.payload,'$.capturedAt') AS captured_at FROM review_files f JOIN review_snapshots s
+    USING(session_id,turn,seq) WHERE f.id=?`).get(id) as Row | undefined
+  if (!row) return null
+  const blocks = db.prepare('SELECT block_id AS id,decision FROM review_blocks WHERE file_id=? ORDER BY rowid').all(id) as unknown as ReviewBlockState[]
+  const diff = JSON.parse(String(row.diff)) as OfficialDiff
+  const evidence = db.prepare('SELECT 1 FROM review_evidence WHERE file_id=?').get(id)
+  const pending = row.current === 1 && row.decision === 'pending'
+  const undo = pending && !!evidence && diff.kind === 'text' && diff.before && diff.after && !diff.coarse
+  return { item: itemOf(row), diff, capturedAt: String(row.captured_at), blocks,
+    capability: { keep: pending, undo,
+      reason: undo ? 'Undo 将校验原始字节、当前文件版本及已处理差异块；文件变化会安全拒绝。'
+        : '该记录缺少可验证的原始字节或受控写回能力；仍可显示差异和 Keep，不能猜测历史全文执行 Undo。' } }
+}
+
+/** @public @author ddj 2026年10月27号 @param db Active decision transaction. @param request File or block action. Updates aggregate without losing mixed decisions. @throws Invalid or already-decided block. */
+export function changeBlocks(db: DatabaseSync, request: DecideReview): void {
+  if (request.scope === 'hunk') {
+    const changed = db.prepare("UPDATE review_blocks SET decision=? WHERE file_id=? AND block_id=? AND decision='pending'")
+      .run(request.decision, request.id, request.blockId ?? '')
+    if (changed.changes !== 1) throw new Error('差异块不存在或已处理')
+  } else {
+    db.prepare("UPDATE review_blocks SET decision=? WHERE file_id=? AND decision='pending'").run(request.decision, request.id)
+  }
+  const states = db.prepare('SELECT DISTINCT decision FROM review_blocks WHERE file_id=?').all(request.id) as Row[]
+  const decisions = states.map((row) => String(row.decision))
+  let aggregate = request.decision as string
+  if (decisions.includes('pending')) aggregate = 'pending'
+  else if (decisions.length > 1) aggregate = 'mixed'
+  else if (decisions.length === 1) aggregate = decisions[0]
+  db.prepare('UPDATE review_files SET decision=? WHERE id=?').run(aggregate, request.id)
+}
+
+/** @public @author ddj 2026年10月26号 @param cwd Workspace. @param request Frozen identity/revision. @returns Idempotent decision; rejection never guesses a target. */
+export function decideReview(cwd: string, request: DecideReview): { revision: number } {
+  const db = reviewDb(cwd)
+  const encoded = JSON.stringify(request)
+  if (!request.operationId || request.operationId.length > 128) throw new Error('operationId 无效')
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    const previous = db.prepare('SELECT request,result FROM review_ops WHERE operation_id=?').get(request.operationId) as Row | undefined
+    if (previous) {
+      if (previous.request !== encoded) throw new Error('operationId 已用于其他请求')
+      if (!previous.result) throw new Error('Undo 尚待写后核对，请重试原操作')
+      db.exec('COMMIT')
+      return JSON.parse(String(previous.result))
+    }
+    if (db.prepare("SELECT 1 FROM review_ops WHERE state='prepared' AND json_extract(request,'$.id')=?").get(request.id)) {
+      throw new Error('该文件有尚待核对的 Undo，暂不能 Keep')
+    }
+    if (request.decision !== 'accepted') throw new Error('缺少可信全文证据，禁止拒绝写回')
+    const change = db.prepare(`UPDATE review_files SET decision='accepted',revision=revision+1
+      WHERE id=? AND seq=? AND revision=? AND current=1 AND decision='pending'`).run(request.id, request.seq, request.revision)
+    if (change.changes !== 1) throw new Error('审查版本冲突，请刷新后重试')
+    changeBlocks(db, request)
+    const result = { revision: request.revision + 1 }
+    db.prepare("INSERT INTO review_ops VALUES(?,?,'committed',?,NULL)").run(request.operationId, encoded, JSON.stringify(result))
+    db.exec('COMMIT')
+    return result
+  } catch (error) {
+    if (db.isTransaction) db.exec('ROLLBACK')
+    throw error
+  }
+}