dsh-vscode-mode 0.14.5 → 0.14.7

package/src/svn.ts

@@ -19,6 +19,12 @@ import { attrOf, numAttrOf, scanXmlTags, textOf, unescapeXml } from './svnXml.js
 import { TEXT_OUTPUT_CAP, batchResultOf, tailOfText, updateResultOf } from './svnText.js'
 import { LOG_CAP, LOG_DEFAULT_LIMIT, SVN_LOG_SHOW_ALL_CAP, parseLogXml, parseSvnInfoRevision } from './svnLog.js'
 import { SvnUpdateJobs } from './svnUpdateJob.js'
+import { EXPLORER_CAP, explorerViewOf, scopeEntriesOf, statusXmlValid, viewArgsValid } from './svnExplorer.js'
+import { ExplorerScopes, explorerKey } from './svnExplorerCache.js'
+import type { ExplorerScan } from './svnExplorerCache.js'
+import type { SvnViewRequest } from './shared/svnExplorer.js'
+import { readStatusPipe } from './svnStatusStream.js'
+import type { StatusPipe } from './svnStatusStream.js'
 import type { UpdateProcess } from './svnUpdateJob.js'
 export { batchResultOf, commitResultOf, updateResultOf } from './svnText.js'
 export { mapRepoPath, parseLogXml } from './svnLog.js'
@@ -245,7 +251,8 @@ export function parseStatusXml(xml: string, cap: number = CHANGES_CAP): { entrie
     if (!pendingPath) continue
     const rawItem = attrOf(hit.attrs, 'item')
     const item = (rawItem || 'modified') as SvnItemStatus
-    const status: SvnItemStatus = KNOWN_ITEM_STATUS.has(item) ? item : 'modified'
+    const status: SvnItemStatus = attrOf(hit.attrs, 'tree-conflicted') === 'true'
+      ? 'conflicted' : (KNOWN_ITEM_STATUS.has(item) ? item : 'modified')
     const path = changePathOf(pendingPath)
     if (!path) { pendingPath = null; continue }
     if (entries.length >= cap) { truncated = true }
@@ -370,13 +377,14 @@ export function parseRemoteStatusXml(
     const repos = /<repos-status\b([^>]*?)\/?>/.exec(match[2])
     if (!repos) continue
     const item = attrOf(repos[1], 'item')
-    if (!item || item === 'none') continue
+    const props = attrOf(repos[1], 'props')
+    if ((!item || item === 'none' || item === 'normal') && props !== 'modified') continue
     // 路径形态双兼容（同 parseSummarizeXml：绝对/相对取决于调用目标形态）
     const rawPath = attrOf(match[1], 'path')
     const rel = relPathOfAbs(rawPath, wcRoot) ?? changePathOf(rawPath)
     if (!rel) continue
     if (outdated.length >= cap) { truncated = true; break }
-    outdated.push({ path: rel, item })
+    outdated.push({ path: rel, item: item && item !== 'none' && item !== 'normal' ? item : 'modified' })
   }
   return { outdated, againstRev, truncated }
 }
@@ -500,6 +508,9 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
   const updateRootCache = new Map<string, { at: number; root: string }>()
   /** 变更清单缓存（键 = 工作副本根；TTL 短，仅合并同一轮 UI 的多处拉取）。 */
   const changesCache = new Map<string, { at: number; value: { entries: SvnChangeEntry[]; truncated: boolean } }>()
+  /** Explorer snapshots are bounded and short-lived; concurrent scans share one subprocess. */
+  const explorerCache = new Map<string, { at: number; entries: SvnChangeEntry[]; truncated: boolean }>()
+  const explorerFlight = new Map<string, Promise<{ entries: SvnChangeEntry[]; truncated: boolean }>>()
   /** 混合通道方案收件箱（key = 工作副本根；覆盖式入箱 + TTL，见 svn.aiPlanSubmit/Pending）。 */
   const planInbox = new Map<string, { plan: SvnAiPlan; dropped: number; at: number }>()
   /** 工作副本根 relative-url 缓存（日志路径映射用；探测失败也缓存空串避免反复 spawn）。 */
@@ -936,7 +947,96 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
     return { ok, count, summary, output: [...notes, ...failures].join('\n') }
   }
 
+  /** @private @author ddj 2026年10月10号 @param root Native WC root. @param prefix Session prefix. @param paths Subtree targets. @returns Existing parent roots, merged with segment boundaries; missing session forces full. */
+  const scopeRootsOf = async (root: string, prefix: string, paths: readonly string[]): Promise<string[]> => {
+    const roots: string[] = []
+    for (const raw of paths) {
+      let path = raw
+      while (path) {
+        try { if ((await stat(join(root, prefix, path))).isDirectory()) break } catch { /* Deleted subtree: climb. */ }
+        path = path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : ''
+      }
+      if (roots.some((parent) => !parent || path === parent || path.startsWith(parent + '/'))) continue
+      for (let i = roots.length - 1; i >= 0; i--) if (!path || roots[i].startsWith(path + '/')) roots.splice(i, 1)
+      roots.push(path)
+    }
+    return roots
+  }
+
+  /** @private @author ddj 2026年10月10号 @param cwd Session directory. @param root WC root. @param roots Bounded subtrees. @param signal Owner disposal. @returns Confirmed local statuses; malformed/pipe-empty output rejects. */
+  const scanExplorer = async (cwd: string, root: string, roots: readonly string[] = [''], signal?: AbortSignal): Promise<ExplorerScan> => {
+    const target = svnPathOf(cwd, root, '')
+    if (target === null) throw new Error('工作区不在 SVN 根目录内')
+    const spawn = subprocess()
+    if (!spawn) throw new Error('缺少 subprocess 服务')
+    const fs = ctx.get('fs') as { resolve?: (p: string, o: object) => Promise<unknown>; processPath?: (t: unknown) => string } | null
+    const realRoot = fs?.resolve && fs?.processPath ? fs.processPath(await fs.resolve(root, {})) : root
+    const validRoots = await scopeRootsOf(realRoot, target, roots)
+    const targets = validRoots.map((path) => {
+      const rel = [target === '.' ? '' : target, path].filter(Boolean).join('/') || '.'
+      return rel.includes('@') ? rel + '@' : rel
+    })
+    const handle = spawn({
+      argv: [settings.svn().svnPath.trim() || SVN_CLI_DEFAULT, '--non-interactive', 'status', '--xml', '--verbose', '--no-ignore', '--', ...targets],
+      cwd: realRoot, stdio: { stdout: 'pipe', stderr: { maxBytes: OUTPUT_CAP }, stdin: 'ignore' }, graceMs: STATUS_GRACE_MS,
+    }) as StatusPipe
+    const parsed = await readStatusPipe(handle, parseStatusXml, EXPLORER_CAP, STATUS_GRACE_MS, signal)
+    return { entries: scopeEntriesOf(parsed.entries, target), truncated: parsed.truncated, roots: validRoots }
+  }
+
+  /** @private @author ddj 2026年10月09号 @param cwd Session directory. @param root WC root. @param force Bypass TTL. @returns Shared bounded scan; old cache entries are evicted. */
+  const explorerOf = async (cwd: string, root: string, force: boolean) => {
+    const pending = explorerFlight.get(cwd)
+    if (pending) return pending
+    const hit = explorerCache.get(cwd)
+    if (!force && hit && now() - hit.at < CHANGES_TTL_MS) return hit
+    const work = scanExplorer(cwd, root)
+    explorerFlight.set(cwd, work)
+    try {
+      const result = await work
+      explorerCache.delete(cwd)
+      if (explorerCache.size >= 2) explorerCache.delete(explorerCache.keys().next().value!)
+      explorerCache.set(cwd, { at: now(), ...result })
+      return result
+    } finally { explorerFlight.delete(cwd) }
+  }
+
+  const explorerScopes = new ExplorerScopes()
+  /** @private @author ddj 2026年10月10号 @param args Validated view projection. @returns Scope-isolated compact evidence; no repository contact. */
+  const viewExplorer = async (args: SvnViewRequest) => {
+    if (!viewArgsValid(args)) return { ok: false as const, error: 'SVN 图标请求无效或超出行数/路径上限' }
+    const sc = await requireSvnSession(ctx, args.sessionId)
+    if ('err' in sc) return { ok: false as const, error: sc.err }
+    const status = await statusOf(sc.cwd)
+    if (!status.managed || !status.wcRoot || !status.svnCli) return { ok: false as const, error: 'SVN 工作副本或命令不可用' }
+    try {
+      const root = status.wcRoot
+      const scopeId = JSON.stringify([explorerKey(root), explorerKey(sc.cwd)])
+      /** @private @author ddj 2026年10月10号 @param roots Scoped subtrees. @param signal Owner disposal. @returns Streamed scan. */
+      const scan = (roots: readonly string[], signal: AbortSignal) => scanExplorer(sc.cwd, root, roots, signal)
+      const queue = explorerScopes.get(scopeId, scan, now)
+      const reason = args.reason ?? 'read'
+      if (reason !== 'read' && (reason !== 'calibrate' || now() - queue.state().confirmedAt > CHANGES_TTL_MS)) {
+        queue.invalidate({ full: reason !== 'paths', paths: args.paths, event: JSON.stringify([args.clientId, args.eventId]) })
+      }
+      await queue.initial()
+      return { ok: true as const, ...explorerViewOf(queue, scopeId, svnPathOf(sc.cwd, root, '') ?? '.', args) }
+    } catch (error) { return { ok: false as const, error: '读取 SVN 图标状态失败：' + String(error) } }
+  }
+
   const handlers = {
+    'svn.explorerView': viewExplorer,
+    /** @public @author ddj 2026年10月09号 @param args Session and refresh flag. @returns Read-only explorer snapshot; no repository contact. */
+    'svn.explorerStatus': async (args: { sessionId?: string; force?: boolean }) => {
+      const sc = await requireSvnSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false as const, error: sc.err }
+      const status = await statusOf(sc.cwd)
+      if (!status.managed || !status.wcRoot || !status.svnCli) return { ok: false as const, error: 'SVN 工作副本或命令不可用' }
+      try {
+        const result = await explorerOf(sc.cwd, status.wcRoot, args.force === true)
+        return { ok: true as const, ...result, prefix: svnPathOf(sc.cwd, status.wcRoot, '') ?? '.' }
+      } catch (error) { return { ok: false as const, error: '读取 SVN 图标状态失败：' + String(error) } }
+    },
     'svn.status': async (args: { sessionId?: string; force?: boolean }) => {
       const sc = await requireSvnSession(ctx, args.sessionId)
       if ('err' in sc) return { ok: false as const, error: sc.err }
@@ -1174,12 +1274,14 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
       if (!status.svnCli) return { ok: false as const, error: 'svn 命令不可用（可在设置页配置 svn 路径）' }
       try {
         // W2-3：M3 实测 —— 离线/无凭据会长时间挂起，REMOTE_GRACE_MS 短超时是硬约束
-        const argv = ['status', '-u', '--xml']
-        if (rel) argv.push('--', rel)
+        const target = svnPathOf(sc.cwd, status.wcRoot, rel)
+        if (target === null) return { ok: false as const, error: '路径不在 SVN 工作副本内' }
+        const argv = ['status', '-u', '--xml', '--', target]
         const outcome = await runSvn(status.wcRoot, argv, REMOTE_GRACE_MS, SUM_OUTPUT_CAP)
         if (outcome.code !== 0) {
           return { ok: false as const, error: '远端检查失败：' + tailOfText([outcome.stderr, outcome.stdout].filter(Boolean).join('\n')) }
         }
+        if (!statusXmlValid(outcome.stdout)) return { ok: false as const, error: '远端状态输出为空或不完整' }
         return { ok: true as const, ...parseRemoteStatusXml(outcome.stdout, status.wcRoot) }
       } catch (error) {
         return { ok: false as const, error: '远端检查失败：' + String(error) }
@@ -1492,5 +1594,5 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
       }
     },
   }
-  return { handlers, dispose: () => { updateJobs.dispose(); updateRootCache.clear() } }
+  return { handlers, dispose: () => { explorerScopes.dispose(); explorerCache.clear(); updateJobs.dispose(); updateRootCache.clear() } }
 }

package/src/svnExplorer.ts

@@ -0,0 +1,56 @@
+/** Bounded verbose status reader for confirmed clean icons. @author ddj 2026年10月09号 */
+import type { SvnChangeEntry } from './shared/svn.js'
+import { explorerPathOf } from './shared/svnExplorer.js'
+import type { SvnViewPayload, SvnViewRequest } from './shared/svnExplorer.js'
+import type { ExplorerQueue } from './svnExplorerCache.js'
+
+/** Covers measured 125415-entry WC while bounding retained RPC objects, not XML bytes. */
+export const EXPLORER_CAP = 250_000
+export const EXPLORER_ROWS = 1000
+
+/** @public @author ddj 2026年10月10号 @param raw Untrusted RPC request. @returns Whether bounded relative row/invalidation paths and tokens are legal. */
+export function viewArgsValid(raw: unknown): raw is SvnViewRequest {
+  if (!raw || typeof raw !== 'object') return false
+  const args = raw as SvnViewRequest
+  if (!Array.isArray(args.rows) || args.rows.length > EXPLORER_ROWS) return false
+  if (args.reason && !['read', 'paths', 'full', 'calibrate'].includes(args.reason)) return false
+  if (args.paths && (!Array.isArray(args.paths) || args.paths.length > 256 || !args.paths.every(viewPathValid))) return false
+  if (!args.rows.every((row) => row && typeof row.isDir === 'boolean' && viewPathValid(row.path))) return false
+  if (args.rows.reduce((bytes, row) => bytes + Buffer.byteLength(JSON.stringify(row.path)) + 80, 0) > 240 * 1024) return false
+  if ([args.clientId, args.eventId].some((id) => id !== undefined && (typeof id !== 'string' || !id || id.length > 128))) return false
+  if (args.reason && args.reason !== 'read' && (!args.clientId || !args.eventId)) return false
+  return [args.revision, args.generation].every((n) => n === undefined || (Number.isSafeInteger(n) && n >= 0))
+}
+/** @private @author ddj 2026年10月10号 @param path Untrusted relative path. @returns No absolute/traversal/control characters; max row size bounds JSON. */
+function viewPathValid(path: unknown): path is string {
+  if (typeof path !== 'string' || path.length > 1024 || /[\x00-\x1f]/.test(path)) return false
+  const normalized = path.replace(/\\/g, '/')
+  return !normalized.startsWith('/') && !/^[A-Za-z]:/.test(normalized) && !normalized.split('/').includes('..')
+}
+
+/** @public @author ddj 2026年10月10号 @param queue Scope-owned index. @param scopeId Canonical scope. @param prefix WC prefix. @param args Rows and consistency token. @returns Compact rows; page mismatch returns no mixed-version data. */
+export function explorerViewOf(queue: ExplorerQueue, scopeId: string, prefix: string, args: SvnViewRequest): SvnViewPayload {
+  const state = queue.state()
+  const mismatch = (args.revision !== undefined && args.revision !== state.revision)
+    || (args.generation !== undefined && args.generation !== state.generation)
+  const rows = mismatch ? [] : args.rows.map((row) => {
+    const { mark, count } = queue.data.mark(row.path, row.isDir)
+    return { path: row.path, kind: mark?.kind ?? null, count, stale: queue.stale(row.path, row.isDir) }
+  })
+  return { scopeId, prefix, ...state, mismatch, rows }
+}
+
+/** @public @author ddj 2026年10月09号 @param xml Collected CLI output. @returns True only for a complete status document. */
+export function statusXmlValid(xml: string): boolean {
+  return /^\s*(?:<\?xml[^>]*>\s*)?<status(?:\s[^>]*)?>/.test(xml) && /<\/status>\s*$/.test(xml)
+}
+
+/** @public @author ddj 2026年10月09号 @param entries WC-relative statuses. @param prefix Session prefix. @returns Session-relative subset. */
+export function scopeEntriesOf(entries: readonly SvnChangeEntry[], prefix: string): SvnChangeEntry[] {
+  const scoped: SvnChangeEntry[] = []
+  for (const entry of entries) {
+    const path = explorerPathOf(entry.path, prefix)
+    if (path !== null) scoped.push({ ...entry, path })
+  }
+  return scoped
+}

package/src/svnExplorerCache.ts

@@ -0,0 +1,304 @@
+/** Host-only scoped SVN index and single-flight invalidation queue. @author ddj 2026年10月10号 */
+import type { SvnChangeEntry, SvnItemStatus } from './shared/svn.js'
+import { SVN_FOLDER_STATUS_RANK } from './shared/svn.js'
+import { explorerMarkOf, localStatusOf } from './shared/svnExplorer.js'
+import type { SvnExplorerIndex } from './shared/svnExplorer.js'
+import { EXPLORER_CAP } from './svnExplorer.js'
+
+export interface ExplorerScan { entries: SvnChangeEntry[]; truncated: boolean; roots?: readonly string[] }
+export type ExplorerScanner = (paths: readonly string[], signal: AbortSignal) => Promise<ExplorerScan>
+export interface ExplorerChange { paths?: readonly string[]; full?: boolean; event?: string }
+export interface ExplorerState {
+  revision: number; generation: number; observedGeneration: number; confirmedAt: number; complete: boolean
+  refreshing: boolean; scanMs: number; error: string
+}
+type StatusCounts = Map<SvnItemStatus, number>
+const QUIET_MS = 300
+const MAX_WAIT_MS = 1000
+const EVENT_CAP = 512
+
+// --region Path sets and normalization
+/** @public @author ddj 2026年10月10号 @param path Validated relative path. @param windows Case-insensitive platform. @returns Canonical lookup key, preserving row spelling separately. */
+export function explorerKey(path: string, windows = process.platform === 'win32'): string {
+  const normalized = path.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '')
+  return windows ? normalized.toLowerCase() : normalized
+}
+/** @private @author ddj 2026年10月10号 @param path Canonical descendant. @param root Canonical subtree. @returns Segment-bound membership including root. */
+function within(path: string, root: string): boolean { return !root || path === root || path.startsWith(root + '/') }
+/** @private @author ddj 2026年10月10号 @param path Canonical entry. @returns Ancestors excluding virtual scope root. */
+function ancestors(path: string): string[] {
+  const parents: string[] = []
+  let parent = path
+  while (parent.includes('/')) { parent = parent.slice(0, parent.lastIndexOf('/')); parents.push(parent) }
+  return parents
+}
+/** @public @author ddj 2026年10月10号 @param paths Changed paths. @param windows Platform matching. @returns Minimal parent subtree set; empty root means full scan. */
+export function scanRootsOf(paths: readonly string[], windows = process.platform === 'win32'): string[] {
+  const roots: string[] = []
+  for (const raw of paths) {
+    const path = explorerKey(raw, windows)
+    const parent = path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : ''
+    if (roots.some((root) => within(parent, root))) continue
+    for (let i = roots.length - 1; i >= 0; i--) if (within(roots[i], parent)) roots.splice(i, 1)
+    roots.push(parent)
+  }
+  return roots
+}
+// --endregion
+
+// --region Incremental subtree index
+/** @public @author ddj 2026年10月10号 Retains authoritative entries and decrementable ancestor counts; no client-wide payload. */
+export class ExplorerIndex {
+  readonly index: SvnExplorerIndex = { entries: new Map(), folders: new Map(), truncated: false }
+  private readonly counts = new Map<string, StatusCounts>()
+  private readonly children = new Map<string, Set<string>>()
+  /** @public @author ddj 2026年10月10号 @param windows Case-insensitive lookup mode. */
+  constructor(private readonly windows = process.platform === 'win32') {}
+
+  /** @private @author ddj 2026年10月10号 @param entry Entry contribution. @param delta Add or remove. Updates strongest status after downgrade. */
+  private contribute(entry: SvnChangeEntry, delta: number): void {
+    const status = localStatusOf(entry)
+    if (status === 'normal' || status === 'ignored' || status === 'external') return
+    for (const parent of ancestors(entry.path)) {
+      const counts = this.counts.get(parent) ?? new Map<SvnItemStatus, number>()
+      const next = (counts.get(status) ?? 0) + delta
+      if (next > 0) counts.set(status, next)
+      else counts.delete(status)
+      if (!counts.size) { this.counts.delete(parent); this.index.folders.delete(parent); continue }
+      this.counts.set(parent, counts)
+      let strongest: SvnItemStatus = 'normal'
+      let count = 0
+      for (const [item, n] of counts) {
+        count += n
+        if ((SVN_FOLDER_STATUS_RANK[item] ?? 0) > (SVN_FOLDER_STATUS_RANK[strongest] ?? 0)) strongest = item
+      }
+      this.index.folders.set(parent, { status: strongest, count })
+    }
+  }
+
+  /** @private @author ddj 2026年10月10号 @param path Canonical entry. Build direct child membership, including implicit ancestors. */
+  private link(path: string): void {
+    let child = path
+    while (child) {
+      const parent = child.includes('/') ? child.slice(0, child.lastIndexOf('/')) : ''
+      const siblings = this.children.get(parent) ?? new Set<string>()
+      siblings.add(child); this.children.set(parent, siblings)
+      child = parent
+    }
+  }
+  /** @private @author ddj 2026年10月10号 @param path Removed entry. Prune only empty implicit ancestors; retained siblings remain indexed. */
+  private unlink(path: string): void {
+    let child = path
+    while (child && !this.index.entries.has(child) && !this.children.get(child)?.size) {
+      const parent = child.includes('/') ? child.slice(0, child.lastIndexOf('/')) : ''
+      this.children.delete(child)
+      const siblings = this.children.get(parent)
+      siblings?.delete(child)
+      if (!siblings?.size) this.children.delete(parent)
+      child = parent
+    }
+  }
+  /** @private @author ddj 2026年10月10号 @param roots Subtree membership roots. @returns Retained affected entries only; no whole-index iteration for local replacement. */
+  private members(roots: readonly string[]): string[] {
+    const result = new Set<string>(), pending = [...roots], visited = new Set<string>()
+    while (pending.length) {
+      const path = pending.pop()!
+      if (visited.has(path)) continue
+      visited.add(path)
+      if (this.index.entries.has(path)) result.add(path)
+      for (const child of this.children.get(path) ?? []) pending.push(child)
+    }
+    return [...result]
+  }
+
+  /** @public @author ddj 2026年10月10号 @param roots Replaced session-relative subtrees. @param result Complete or bounded scan. @throws Capacity mismatch on partial replacement; caller must full-calibrate. */
+  replace(roots: readonly string[], result: ExplorerScan): void {
+    const keys = roots.map((root) => explorerKey(root, this.windows))
+    const full = keys.includes('')
+    const incoming = new Map<string, SvnChangeEntry>()
+    for (const entry of result.entries) {
+      const path = explorerKey(entry.path, this.windows)
+      if (keys.some((root) => within(path, root))) incoming.set(path, { ...entry, path })
+    }
+    const removed = full ? [] : this.members(keys)
+    if (!full && (result.truncated || this.index.entries.size - removed.length + incoming.size > EXPLORER_CAP)) {
+      throw new Error('局部 SVN 状态不完整，需要全量校准')
+    }
+    if (full) this.clear()
+    else for (const path of removed) {
+      this.contribute(this.index.entries.get(path)!, -1)
+      this.index.entries.delete(path)
+      this.unlink(path)
+    }
+    for (const [path, entry] of incoming) { this.index.entries.set(path, entry); this.link(path); this.contribute(entry, 1) }
+    if (full) this.index.truncated = result.truncated
+  }
+
+  /** @public @author ddj 2026年10月10号 Release retained entries and aggregation counters. */
+  clear(): void { this.index.entries.clear(); this.index.folders.clear(); this.counts.clear(); this.children.clear() }
+
+  /** @public @author ddj 2026年10月10号 @param path Display row spelling. @param isDir Directory row. @returns Exact/ancestor mark and dirty descendant count. */
+  mark(path: string, isDir: boolean) {
+    const key = explorerKey(path, this.windows)
+    return { mark: explorerMarkOf(this.index, key, isDir), count: isDir ? this.index.folders.get(key)?.count ?? 0 : 0 }
+  }
+}
+// --endregion
+
+// --region Scoped ownership
+/** @public @author ddj 2026年10月10号 Two retained scope indexes; active work is never evicted to satisfy a new reader. */
+export class ExplorerScopes {
+  private readonly scopes = new Map<string, ExplorerQueue>()
+  /** @public @author ddj 2026年10月10号 @param key Canonical root/session key. @param scan Scanner bound to this scope. @param now Clock. @param windows Matching. @returns Shared owner; refuses new scopes if all retained owners are busy. */
+  get(key: string, scan: ExplorerScanner, now = Date.now, windows = process.platform === 'win32'): ExplorerQueue {
+    const existing = this.scopes.get(key)
+    if (existing) { this.scopes.delete(key); this.scopes.set(key, existing); return existing }
+    if (this.scopes.size >= 2) {
+      const idle = [...this.scopes].find(([, queue]) => queue.idle())
+      if (!idle) throw new Error('SVN 状态扫描繁忙，请稍后重试')
+      idle[1].dispose()
+      this.scopes.delete(idle[0])
+    }
+    const queue = new ExplorerQueue(scan, now, windows)
+    this.scopes.set(key, queue)
+    return queue
+  }
+  /** @public @author ddj 2026年10月10号 Release all scoped work and retained state. */
+  dispose(): void { for (const queue of this.scopes.values()) queue.dispose(); this.scopes.clear() }
+}
+// --endregion
+
+// --region Single-flight dirty queue
+/** @public @author ddj 2026年10月10号 Coalesces generations without swallowing changes arriving during a scan. */
+export class ExplorerQueue {
+  readonly data: ExplorerIndex
+  private generation = 0
+  private observed = 0
+  private revision = 0
+  private confirmedAt = 0
+  private scanMs = 0
+  private error = ''
+  private fullDirty = false
+  private readonly dirty = new Set<string>()
+  private active: readonly string[] | null = null
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private pendingSince: number | null = null
+  private lastEventAt = 0
+  private controller: AbortController | null = null
+  private flight: Promise<void> | null = null
+  private stopped = false
+  private readonly events = new Set<string>()
+  private staleRoots: readonly string[] | null = null
+
+  /** @public @author ddj 2026年10月10号 @param scan Managed scoped scan. @param now Injectable clock. @param windows Canonical path matching. */
+  constructor(private readonly scan: ExplorerScanner, private readonly now = Date.now, private readonly windows = process.platform === 'win32') {
+    this.data = new ExplorerIndex(windows)
+  }
+
+  /** @public @author ddj 2026年10月10号 @param change Path/full invalidation and idempotency token. @returns Whether a new change was registered. */
+  invalidate(change: ExplorerChange = { full: true }): boolean {
+    if (this.stopped || (change.event && this.events.has(change.event))) return false
+    if (change.event) {
+      this.events.add(change.event)
+      if (this.events.size > EVENT_CAP) this.events.delete(this.events.values().next().value!)
+    }
+    this.generation++
+    this.staleRoots = null
+    this.lastEventAt = this.now()
+    if (this.pendingSince === null) this.pendingSince = this.lastEventAt
+    if (change.full || !change.paths?.length || !this.confirmedAt || this.data.index.truncated) this.fullDirty = true
+    for (const path of change.paths ?? []) this.dirty.add(explorerKey(path, this.windows))
+    if (this.dirty.size > 256 || scanRootsOf([...this.dirty], this.windows).length > 32) this.fullDirty = true
+    if (this.fullDirty) this.dirty.clear()
+    this.schedule()
+    return true
+  }
+
+  /** @private @author ddj 2026年10月10号 Tail debounce has a hard max wait; active scans retain one merged follow-up batch. */
+  private schedule(): void {
+    if (this.stopped || this.active || this.pendingSince === null) return
+    if (this.timer) clearTimeout(this.timer)
+    const delay = Math.max(0, Math.min(this.lastEventAt + QUIET_MS, this.pendingSince + MAX_WAIT_MS) - this.now())
+    this.timer = setTimeout(() => { this.timer = null; this.launch() }, delay)
+  }
+
+  /** @private @author ddj 2026年10月10号 Starts one scan, snapshots generation and dirtiness before yielding. */
+  private launch(): void {
+    if (this.stopped || this.active || this.pendingSince === null) return
+    const roots = this.fullDirty ? [''] : scanRootsOf([...this.dirty], this.windows)
+    const generation = this.generation
+    this.fullDirty = false
+    this.dirty.clear()
+    this.pendingSince = null
+    this.active = roots
+    this.staleRoots = null
+    this.controller = new AbortController()
+    this.flight = this.run(roots, generation, this.controller.signal)
+  }
+
+  /** @private @author ddj 2026年10月10号 @param roots Scan subtrees. @param generation Captured invalidation generation. @param signal Owner disposal. Applies known evidence but never confirms newer dirty paths. */
+  private async run(roots: readonly string[], generation: number, signal: AbortSignal): Promise<void> {
+    const started = this.now()
+    try {
+      const result = await this.scan(roots, signal)
+      if (this.stopped) return
+      this.data.replace(result.roots ?? roots, result)
+      this.observed = generation
+      this.revision++
+      this.error = ''
+      if (generation === this.generation && !result.truncated) this.confirmedAt = this.now()
+    } catch (failure) {
+      if (this.stopped) return
+      this.error = String(failure)
+      // A failed subtree must not keep green evidence. Retry only on a later read/event, not a spin loop.
+      this.fullDirty = true
+    } finally {
+      this.scanMs = Math.max(0, this.now() - started)
+      this.active = null
+      this.staleRoots = null
+      this.controller = null
+      this.flight = null
+      this.schedule()
+    }
+  }
+
+  /** @public @author ddj 2026年10月10号 @param path Display row. @param isDir Directory membership. @returns Whether evidence intersects active/queued changes or incomplete state. */
+  stale(path: string, isDir: boolean): boolean {
+    if (!this.confirmedAt || this.fullDirty || this.data.index.truncated) return true
+    const key = explorerKey(path, this.windows)
+    const roots = this.staleRoots ??= [...(this.active ?? []), ...scanRootsOf([...this.dirty], this.windows)]
+    return roots.some((root) => within(key, root) || (isDir && within(root, key)))
+  }
+
+  /** @public @author ddj 2026年10月10号 @returns Lightweight scope metadata; freshness is independent of cache TTL. */
+  state(): ExplorerState {
+    return { revision: this.revision, generation: this.generation, observedGeneration: this.observed, confirmedAt: this.confirmedAt,
+      complete: this.confirmedAt > 0 && !this.data.index.truncated && !this.fullDirty && !this.active && !this.dirty.size,
+      refreshing: this.active !== null || this.timer !== null, scanMs: this.scanMs, error: this.error }
+  }
+
+  /** @public @author ddj 2026年10月10号 @returns First-load confirmation; warm callers project immediately with stale flags. */
+  async initial(): Promise<void> {
+    if (this.stopped) throw new Error('SVN 状态调度已释放')
+    if (this.confirmedAt || this.revision || this.error) return
+    if (this.pendingSince === null && !this.active) this.invalidate({ full: true })
+    if (this.timer) { clearTimeout(this.timer); this.timer = null }
+    this.launch()
+    await this.flight
+  }
+
+  /** @public @author ddj 2026年10月10号 @returns Whether an owner may evict this scope without killing shared work. */
+  idle(): boolean { return !this.active && !this.timer }
+
+  /** @public @author ddj 2026年10月10号 Abort owned scans and timers; late completions cannot restore state. */
+  dispose(): void {
+    this.stopped = true
+    if (this.timer) clearTimeout(this.timer)
+    this.timer = null
+    this.controller?.abort(new Error('SVN 状态调度已释放'))
+    this.dirty.clear()
+    this.events.clear()
+    this.data.clear()
+  }
+}
+// --endregion