dsh-taskboard 0.6.1 → 0.6.3

package/src/host/git.ts

@@ -34,6 +34,30 @@ const HEAVY_TIMEOUT_MS = 15_000
 /** Directory under a workspace where task worktrees live. */
 export const WORKTREE_DIR = '.dsh-worktrees'
 
+/**
+ * The path segment of one `status --porcelain` line. Shape-aware: the RAW
+ * line is `XY path` (path at index 3) while the plugin's trimmed evidence
+ * lines collapse a leading-space status to `X path` (path at index 2) —
+ * slicing a fixed 3 misparses exactly the gitlink/unstaged shapes a
+ * multi-repo mirror produces (` M sub-repo`), 0.6.3 review fix.
+ */
+export function statusLinePath(line: string): string {
+  if (line.length >= 3 && line[2] === ' ') return line.slice(3)
+  if (line.length >= 2 && line[1] === ' ') return line.slice(2)
+  return line
+}
+
+/**
+ * Whether a `status --porcelain` line targets one of `rels` (a repo-relative
+ * path) or anything under it. Porcelain prints untracked directories with a
+ * trailing slash (`?? sub/`), so all three shapes match. Empty rels never
+ * match (0.6.3 review fix).
+ */
+export function statusLineUnder(line: string, rels: readonly string[]): boolean {
+  const p = statusLinePath(line)
+  return rels.some(rel => rel.length > 0 && (p === rel || p === rel + '/' || p.startsWith(rel + '/')))
+}
+
 /** Evidence caps: commits kept per execution record (newest first). */
 export const MAX_COMMIT_EVIDENCE = 50
 
@@ -118,18 +142,40 @@ export interface GitFace {
    * undefined on any failure — callers degrade to the original directory.
    */
   prepareWorktree(root: string, path: string, branch: string, mode?: 'fresh' | 'reuse'): Promise<WorktreeInfo | undefined>
-  /** Collect settlement facts (never throws; missing pieces stay unset). */
-  collect(worktreePath: string, baseCommit: string): Promise<SettlementFacts>
-  /** Merge `branch` into the main worktree (`--no-ff`); THROWS with a readable reason. */
-  merge(root: string, branch: string): Promise<void>
+  /**
+   * Collect settlement facts (never throws; missing pieces stay unset).
+   * `excludeRelPaths` drops `status --porcelain` lines targeting those
+   * repo-relative paths (or anything under them) — the mirror's NESTED repo
+   * worktrees read as untracked noise in the root worktree's status and are
+   * not this repo's uncommitted changes (0.6.3 review fix).
+   */
+  collect(worktreePath: string, baseCommit: string, excludeRelPaths?: readonly string[]): Promise<SettlementFacts>
+  /**
+   * Uncommitted-change lines of a working tree ([] = clean; undefined on git
+   * failure). Mirror removal pre-checks EVERY repo worktree before deleting
+   * any, so one dirty repo refuses the whole mirror (0.6.3).
+   */
+  dirtyLines(cwd: string): Promise<string[] | undefined>
+  /**
+   * Merge `branch` into the main worktree (`--no-ff`); THROWS with a readable
+   * reason. `exemptRelPaths` extends the main-clean exemption beyond
+   * `.dsh-worktrees`: uncommitted-shape noise under those repo-relative paths
+   * (parallel repos are self-governing — their content AND their gitlink
+   * entries don't gate the root repo's merge, 0.6.3 review fix).
+   */
+  merge(root: string, branch: string, exemptRelPaths?: readonly string[]): Promise<void>
   /** Whether `branch` is already an ancestor of HEAD (a merge would be a no-op). */
   isAncestor(root: string, branch: string): Promise<boolean>
   /**
    * Remove a worktree. Resolves 'removed' on success, 'unregistered' when git
    * no longer knows the path (an orphaned directory). THROWS when it still
    * has uncommitted changes, or on any other git failure (readable reason).
+   * `opts.exempt` drops mirror-structural noise from the dirty check and
+   * `opts.force` lets `git worktree remove` accept it — for callers that have
+   * ALREADY aggregated the real-dirty check themselves (the mirror removal:
+   * noise-exempt clean → force is safe; real dirt never gets here).
    */
-  removeWorktree(root: string, worktreePath: string): Promise<'removed' | 'unregistered'>
+  removeWorktree(root: string, worktreePath: string, opts?: { exempt?: readonly string[]; force?: boolean }): Promise<'removed' | 'unregistered'>
   /** Delete a branch; THROWS (e.g. still checked out in a worktree). */
   deleteBranch(root: string, branch: string): Promise<void>
   /**
@@ -266,7 +312,7 @@ export function createGitFace(exec: ExecFn = realExec): GitFace {
       return { path, branch, baseCommit }
     }),
 
-    async collect(worktreePath, baseCommit) {
+    async collect(worktreePath, baseCommit, excludeRelPaths) {
       const facts: SettlementFacts = { commits: [], commitsTotal: 0, dirtyFiles: [], dirtyFilesTotal: 0, changedFiles: 0 }
       const range = `${baseCommit}..HEAD`
 
@@ -292,7 +338,14 @@ export function createGitFace(exec: ExecFn = realExec): GitFace {
 
       const status = await quick(['status', '--porcelain'], worktreePath)
       if (status.ok) {
-        const dirty = status.stdout.split('\n').map(l => l.trim()).filter(l => l.length > 0)
+        // excludeRelPaths drops the mirror's nested repo worktrees — they
+        // read as untracked noise / gitlink drift here, not as this repo's
+        // uncommitted changes. Excluded on the RAW line (path extraction is
+        // shape-aware); the stored evidence keeps its trimmed 0.3.x shape.
+        const dirty = status.stdout.split('\n')
+          .filter(l => l.trim().length > 0)
+          .filter(l => !statusLineUnder(l, excludeRelPaths ?? []))
+          .map(l => l.trim())
         facts.dirtyFilesTotal = dirty.length
         facts.dirtyFiles = dirty.slice(0, MAX_DIRTY_EVIDENCE)
       }
@@ -306,19 +359,22 @@ export function createGitFace(exec: ExecFn = realExec): GitFace {
       return facts
     },
 
-    merge: (root, branch) => withRootLock(root, async () => {
+    async dirtyLines(cwd) {
+      const status = await quick(['status', '--porcelain'], cwd)
+      if (!status.ok) return undefined
+      return status.stdout.split('\n').map(l => l.trim()).filter(l => l.length > 0)
+    },
+
+    merge: (root, branch, exemptRelPaths) => withRootLock(root, async () => {
       // Main-clean check. The plugin's own worktree directory
       // (<root>/.dsh-worktrees) shows up as untracked noise and is EXEMPT —
       // otherwise merging would be impossible without gitignoring it first.
       const status = await quick(['status', '--porcelain'], root)
       if (status.ok) {
         const dirtyLines = status.stdout.split('\n')
+          .filter(l => l.trim().length > 0)
+          .filter(l => !statusLineUnder(l, [WORKTREE_DIR, ...(exemptRelPaths ?? [])]))
           .map(l => l.trim())
-          .filter(l => {
-            if (l.length === 0) return false
-            const path = l.slice(3)
-            return path !== WORKTREE_DIR && !path.startsWith(`${WORKTREE_DIR}/`)
-          })
         if (dirtyLines.length > 0) {
           // Machine-readable tag: callers classify without parsing zh-CN text.
           throw Object.assign(new Error(`主工作区有 ${dirtyLines.length} 处未提交修改，请先提交或暂存后再合并`), { code: 'dirty-tree' })
@@ -339,14 +395,24 @@ export function createGitFace(exec: ExecFn = realExec): GitFace {
       return r.ok
     },
 
-    removeWorktree: (root, worktreePath) => withRootLock(root, async (): Promise<'removed' | 'unregistered'> => {
+    removeWorktree: (root, worktreePath, opts) => withRootLock(root, async (): Promise<'removed' | 'unregistered'> => {
       const status = await quick(['status', '--porcelain'], worktreePath)
       if (status.ok && status.stdout.trim().length > 0) {
-        const lines = status.stdout.split('\n').map(l => l.trim()).filter(l => l.length > 0)
-        // Machine-readable tag: purge flows classify without parsing zh-CN text.
-        throw Object.assign(new Error(`worktree 有 ${lines.length} 处未提交修改，拒绝删除：\n${lines.slice(0, 10).join('\n')}`), { code: 'dirty-worktree' })
+        // opts.exempt drops mirror-structural noise (nested child worktrees /
+        // gitlink drift) — the caller's aggregated check already refused real
+        // dirt before reaching here.
+        const lines = status.stdout.split('\n')
+          .filter(l => l.trim().length > 0)
+          .filter(l => !statusLineUnder(l, opts?.exempt ?? []))
+          .map(l => l.trim())
+        if (lines.length > 0) {
+          // Machine-readable tag: purge flows classify without parsing zh-CN text.
+          throw Object.assign(new Error(`worktree 有 ${lines.length} 处未提交修改，拒绝删除：\n${lines.slice(0, 10).join('\n')}`), { code: 'dirty-worktree' })
+        }
       }
-      const removed = await heavy(['worktree', 'remove', worktreePath], root)
+      const removed = await heavy(opts?.force === true
+        ? ['worktree', 'remove', '--force', worktreePath]
+        : ['worktree', 'remove', worktreePath], root)
       if (removed.ok) return 'removed'
       // S3: classify the failure WITHOUT parsing git's (localizable) stderr —
       // a path absent from `worktree list` is an unregistered leftover, not

package/src/host/isolation.ts

@@ -0,0 +1,268 @@
+/**
+ * Worktree isolation orchestration (0.6.3): turns the single-repo worktree
+ * flow into a whole-workspace MIRROR when a workspace holds parallel git
+ * repositories — the workspace root repo plus its nested ones (plan §3/§4).
+ *
+ * Responsibilities (git.ts stays the narrow per-repo face):
+ * - prepareMirror: discover the repos, prepare one worktree per repo under
+ *   the task mirror directory (root repo at the mirror root, each nested
+ *   repo at its relative path), with per-repo reuse (续跑) and a bounded
+ *   partial-failure policy: the FIRST repo failing degrades the whole run
+ *   to the original directory (legacy semantics), a later repo failing
+ *   just drops it from the mirror (framing marks it 禁改 — the isolation
+ *   boundary never blurs).
+ * - removeMirror: children-first removal with an aggregated dirty
+ *   pre-check (one dirty repo refuses the WHOLE mirror before anything is
+ *   deleted). Children must go first: a nested worktree under the root
+ *   worktree reads as untracked noise there, so the root worktree is only
+ *   removable once they are gone.
+ *
+ * Every git interaction stays fail-soft at the boundaries the execution
+ * service already owns: this module returns outcomes, it never fails a run.
+ *
+ * @module dsh-taskboard/host/isolation
+ */
+import { MAX_MIRROR_REPOS, isValidRelRepoPath } from '../shared/protocol.ts'
+import type { GitFace } from './git.ts'
+import { statusLineUnder, worktreePathOf } from './git.ts'
+import type { RepoRef, RepoScanner } from './repos.ts'
+
+/** One prepared repo worktree inside a task mirror. */
+export interface PreparedMirrorRepo {
+  /** Repo path relative to the workspace ('' = the workspace root repo). */
+  repo: string
+  /** The task branch checked out there. */
+  branch: string
+  /** Absolute worktree path (the working directory for this repo in the run). */
+  worktreePath: string
+  /** Baseline for evidence collection: main HEAD (fresh) or worktree HEAD (reuse). */
+  baseCommit: string
+  /** True when an existing live worktree was kept as-is (续跑). */
+  reused?: boolean
+}
+
+/** The mirror of one run: prepared repos + repos deliberately left out. */
+export interface PreparedMirror {
+  /** Absolute path of the task mirror directory (the framing names it). */
+  root: string
+  /** Prepared worktrees in mirror order (root repo first when present). */
+  repos: PreparedMirrorRepo[]
+  /** Repos discovered but NOT mirrored (prepare failed); framing marks them 禁改. */
+  skipped: Array<{ repo: string; reason: string }>
+  /** True when EVERY prepared worktree was kept as-is (续跑 — framing picks the resume wording). */
+  allReused: boolean
+}
+
+/** Outcome of a mirror preparation: either a mirror or a degrade note. */
+export type MirrorPrepareOutcome =
+  | { mirror: PreparedMirror }
+  | { note: string }
+
+/** Whether this mirror is exactly the legacy single-repo shape. */
+export function isLegacySingle(mirror: PreparedMirror): boolean {
+  return mirror.repos.length === 1
+    && mirror.repos[0]!.repo === ''
+    && mirror.skipped.length === 0
+}
+
+/** Whether a repo key may ride into a mirror path (defense in depth under worktreePathOf). */
+function assertRepoKey(repo: string): void {
+  if (!isValidRelRepoPath(repo)) {
+    throw new Error('Error: invalid_input: illegal repo path ' + JSON.stringify(repo.slice(0, 80)))
+  }
+}
+
+/** Best-effort filesystem existence probe (fail-soft → false). */
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    const { stat } = await import('node:fs/promises')
+    return await stat(path).then(() => true, () => false)
+  } catch {
+    return false
+  }
+}
+
+/** Join a repo relative path under a base path (forward slashes). */
+function under(base: string, rel: string): string {
+  return rel === '' ? base : base + '/' + rel
+}
+
+/**
+ * Prepare the task mirror across every repo of the workspace.
+ *
+ * Repo list: the workspace root repo (GitFace.detect decides, whatever its
+ * .git shape) leads, nested parallel repos follow in path order. Each repo
+ * gets its own worktree on the SAME task branch name; reuse keeps live
+ * worktrees as-is per repo (续跑), falling back to a fresh preparation per
+ * repo — and a stale blocking directory gets one forced-fresh retry.
+ */
+export async function prepareMirror(
+  deps: { git: GitFace; scanner: RepoScanner },
+  args: { workspacePath: string; taskId: string; branch: string; reuse: boolean },
+): Promise<MirrorPrepareOutcome> {
+  const { git, scanner } = deps
+
+  // 1. Discover. The root repo is probed through the git face; nested repos
+  //    come from the bounded scanner.
+  const repos: RepoRef[] = []
+  let inside = false
+  try {
+    inside = await git.detect(args.workspacePath)
+  } catch { /* fail-soft → treated as "root is not a repo" */ }
+  if (inside) repos.push({ relPath: '', absPath: args.workspacePath })
+  let nested: RepoRef[] = []
+  try {
+    nested = await scanner.findNestedRepos(args.workspacePath)
+  } catch { nested = [] }
+  for (const repo of nested) {
+    assertRepoKey(repo.relPath)
+    repos.push(repo)
+  }
+
+  if (repos.length === 0) {
+    // Distinguish 未装 git from 非 git 仓库 (0.3.1 wording preserved).
+    let hasBinary = true
+    try {
+      hasBinary = await git.binaryAvailable()
+    } catch { /* fail-soft → repo-side wording */ }
+    return {
+      note: hasBinary
+        ? '当前项目不是 git 仓库，已在原目录执行'
+        : 'git 不可用（未安装或不在 PATH），已在原目录执行',
+    }
+  }
+  if (repos.length > MAX_MIRROR_REPOS) {
+    return { note: '工作区内 git 仓库数超过镜像上限（' + repos.length + ' > ' + MAX_MIRROR_REPOS + '），已在原目录执行' }
+  }
+
+  // 2. Prepare per repo. FIRST repo failing → whole-run degrade (legacy
+  //    semantics); a later failure drops just that repo from the mirror.
+  const mirrorRoot = worktreePathOf(args.workspacePath, args.taskId)
+  const prepared: PreparedMirrorRepo[] = []
+  const skipped: PreparedMirror['skipped'] = []
+  for (let i = 0; i < repos.length; i++) {
+    const repo = repos[i]!
+    const target = under(mirrorRoot, repo.relPath)
+    let info
+    try {
+      info = await git.prepareWorktree(repo.absPath, target, args.branch, args.reuse ? 'reuse' : 'fresh')
+    } catch { /* fail-soft */ }
+    if (info === undefined && args.reuse) {
+      // A stale non-matching directory can block reuse; force one fresh
+      // attempt (fresh mode already drops + prunes the stale worktree).
+      try {
+        info = await git.prepareWorktree(repo.absPath, target, args.branch, 'fresh')
+      } catch { /* fail-soft */ }
+    }
+    if (info === undefined) {
+      if (i === 0) return { note: 'worktree 准备失败（git 报错或目录被占用），已在原目录执行' }
+      skipped.push({ repo: repo.relPath, reason: 'worktree 准备失败' })
+      continue
+    }
+    prepared.push({
+      repo: repo.relPath,
+      branch: info.branch,
+      worktreePath: info.path,
+      baseCommit: info.baseCommit,
+      ...(info.reused === true ? { reused: true } : {}),
+    })
+  }
+  return {
+    mirror: {
+      root: mirrorRoot,
+      repos: prepared,
+      skipped,
+      allReused: prepared.length > 0 && prepared.every(p => p.reused === true),
+    },
+  }
+}
+
+/**
+ * Remove a task whole mirror: aggregate the dirty pre-check across EVERY
+ * repo worktree first (one dirty repo refuses everything, nothing is
+ * deleted), then remove children before the root (see module doc).
+ * Unknown-to-git leftovers report as unregistered — the caller fs-removes
+ * the mirror root afterwards (scope-verified route flows own that rm).
+ * @throws with code dirty-mirror when any repo worktree holds uncommitted changes.
+ */
+export async function removeMirror(
+  deps: { git: GitFace; scanner: RepoScanner },
+  args: { workspacePath: string; taskId: string },
+): Promise<void> {
+  const { git, scanner } = deps
+  const mirrorRoot = worktreePathOf(args.workspacePath, args.taskId)
+  // Structural teardown must target a FRESH discovery: a stale TTL cache
+  // could miss a repo added since the last scan and strand its mirror
+  // worktree inside the root (which then reads as unremovable noise). The
+  // cache exists for the prepare/merge hot path, not for teardown.
+  scanner.clearCache()
+  let nested: RepoRef[] = []
+  try {
+    nested = await scanner.findNestedRepos(args.workspacePath)
+  } catch { nested = [] }
+
+  const targets: Array<{ repo: string; repoRoot: string; path: string }> = []
+  for (const repo of nested) {
+    assertRepoKey(repo.relPath)
+    const path = under(mirrorRoot, repo.relPath)
+    if (await pathExists(path)) targets.push({ repo: repo.relPath, repoRoot: repo.absPath, path })
+  }
+  // The mirror ROOT is always a target (the legacy flow called removeWorktree
+  // unconditionally): when the workspace root is a repo this removes the root
+  // worktree; when it is not (plain mirror dir, already-gone path) git side
+  // reports it unregistered and the caller's fs rm cleans up.
+  targets.push({ repo: '', repoRoot: args.workspacePath, path: mirrorRoot });
+
+  const childRels = targets.filter(t => t.repo !== '').map(t => t.repo)
+  const dirty: Array<{ repo: string; lines: string[] }> = []
+  for (const target of targets) {
+    const raw = await git.dirtyLines(target.path).catch(() => undefined)
+    // The root worktree's status lists its nested child worktrees as untracked
+    // noise (`?? sub/`) — those trees belong to the children (checked in their
+    // own pass below), not to the root repo's uncommitted changes. Without
+    // this exemption a fully committed mirror still reads as dirty and every
+    // cleanup route refuses forever (0.6.3 review fix).
+    const lines = target.repo === '' && raw !== undefined
+      ? raw.filter(l => !statusLineUnder(l, childRels))
+      : raw
+    if (lines !== undefined && lines.length > 0) dirty.push({ repo: target.repo, lines })
+  }
+  if (dirty.length > 0) {
+    const detail = dirty
+      .map(d => (d.repo === '' ? '根仓库' : d.repo) + '：\n' + d.lines.slice(0, 10).join('\n'))
+      .join('\n')
+    throw Object.assign(
+      new Error('镜像中 ' + dirty.length + ' 个仓库有未提交修改，拒绝删除：\n' + detail),
+      { code: 'dirty-mirror' },
+    )
+  }
+
+  // Removal walks the array FORWARD: children were pushed before the root, so
+  // this IS the children-first order. (The original reverse loop removed the
+  // root FIRST — its own doc said children-first; the P1 dirty refusal above
+  // masked the bug because the loop never actually ran on a real mirror.)
+  const failures: string[] = []
+  for (const target of targets) {
+    try {
+      // The root's structural noise (nested child worktrees / gitlink drift)
+      // survived the aggregated pre-check above — exempt + force is safe by
+      // construction: real dirt never got past it.
+      await git.removeWorktree(target.repoRoot, target.path,
+        target.repo === '' ? { exempt: childRels, force: true } : undefined)
+    } catch (error) {
+      failures.push((target.repo === '' ? '根仓库' : target.repo) + '：' + (error instanceof Error ? error.message : String(error)))
+    }
+  }
+  if (failures.length > 0) {
+    throw new Error('删除镜像失败：\n' + failures.slice(0, 5).join('\n'))
+  }
+}
+
+/**
+ * Absolute path of a repo main checkout inside the workspace (the fallback
+ * cwd for diff views after a mirror is gone).
+ */
+export function repoMainPath(workspacePath: string, repo: string): string {
+  assertRepoKey(repo)
+  return under(workspacePath, repo)
+}

package/src/host/repos.ts

@@ -0,0 +1,146 @@
+/**
+ * Workspace repository discovery (0.6.3): locate the PARALLEL nested git
+ * repositories inside a workspace so worktree isolation can mirror the
+ * whole multi-repo layout under the task's worktree directory (plan §4.1).
+ *
+ * Scope rules:
+ * - Only TRUE independent repositories qualify: a child directory counts
+ *   when it contains a `.git` DIRECTORY. A `.git` FILE (a linked worktree
+ *   or a submodule) is skipped — its refs live in some other repository's
+ *   object store, so treating it as a repo would double-register that one.
+ * - Bounded scan (depth ≤ {@link MAX_SCAN_DEPTH}), never descending into a
+ *   discovered repo, a skip-listed directory (node_modules, build output,
+ *   the plugin's own .dsh-worktrees), or a dot directory.
+ * - FAIL-SOFT: every IO error shrinks the result and never throws — the
+ *   caller degrades to single-repo (or plain no-git) behavior.
+ * - Per-workspace TTL cache: the layout rarely changes mid-run.
+ *
+ * The workspace ROOT repo is not discovered here — the caller (isolation)
+ * composes it in front of this list when `GitFace.detect` says the root is
+ * a work tree, whatever `.git` shape it has.
+ *
+ * @module dsh-taskboard/host/repos
+ */
+
+/** How deep below the workspace root nested repos are looked for. */
+export const MAX_SCAN_DEPTH = 3
+
+/** Default TTL of the per-workspace discovery cache (aligns routes' git-detect TTL). */
+const CACHE_TTL_MS = 60_000
+
+/** Skip-listed directory names at every level of the scan. */
+const SKIP_DIRS: ReadonlySet<string> = new Set([
+  'node_modules',
+  '.dsh-worktrees',
+  'lib',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  '.venv',
+  'venv',
+  '__pycache__',
+  'target',
+  '.next',
+  '.nuxt',
+  '.cache',
+  '.gradle',
+  'Pods',
+])
+
+/** One discovered repository: path relative to the workspace + absolute. */
+export interface RepoRef {
+  /**
+   * Forward-slash path relative to the workspace root. `` (empty) is
+   * reserved for the workspace root repo and is NEVER returned here.
+   */
+  relPath: string
+  /** Absolute working-tree path of the repository. */
+  absPath: string
+}
+
+/** Injectable IO face (unit tests script the layout without a filesystem). */
+export interface RepoIo {
+  /** Direct child directory names of `dir` ([] on any error). */
+  readDir(dir: string): Promise<string[]>
+  /** Whether `dir` contains a `.git` DIRECTORY (true independent repo). */
+  hasGitDir(dir: string): Promise<boolean>
+}
+
+/** Real IO over node:fs/promises (dynamic import like the git face). */
+const realRepoIo: RepoIo = {
+  async readDir(dir) {
+    try {
+      const { readdir } = await import('node:fs/promises')
+      const entries = await readdir(dir, { withFileTypes: true })
+      return entries.filter(e => e.isDirectory()).map(e => e.name)
+    } catch {
+      return []
+    }
+  },
+  async hasGitDir(dir) {
+    try {
+      const { stat } = await import('node:fs/promises')
+      return (await stat(`${dir}/.git`)).isDirectory()
+    } catch {
+      return false
+    }
+  },
+}
+
+/** The scanner: discovery plus its TTL cache. */
+export interface RepoScanner {
+  /** Discover the nested parallel repos of a workspace (cache-backed). */
+  findNestedRepos(workspacePath: string): Promise<RepoRef[]>
+  /** Drop every cached discovery (mirror teardown re-discovers fresh — the TTL cache only serves the prepare/merge hot path). */
+  clearCache(): void
+}
+
+/**
+ * Build a scanner over an injectable IO face.
+ * @param io - the IO face (real filesystem when omitted).
+ * @param ttlMs - cache lifetime; `0` disables caching (tests).
+ */
+export function createRepoScanner(io: RepoIo = realRepoIo, ttlMs: number = CACHE_TTL_MS): RepoScanner {
+  const cache = new Map<string, { at: number; repos: RepoRef[] }>()
+
+  const scanDir = async (dir: string, rel: string, depth: number, out: RepoRef[]): Promise<void> => {
+    if (depth > MAX_SCAN_DEPTH) return
+    const names = (await io.readDir(dir)).slice().sort()
+    for (const name of names) {
+      if (name.startsWith('.') || SKIP_DIRS.has(name)) continue
+      const childRel = rel.length === 0 ? name : `${rel}/${name}`
+      const childAbs = `${dir}/${name}`
+      if (await io.hasGitDir(childAbs)) {
+        // A discovered repo is a LEAF: repos nested inside it (vendored
+        // copies) are not part of the workspace's parallel layout.
+        out.push({ relPath: childRel, absPath: childAbs })
+        continue
+      }
+      // One unreadable subtree must not sink the whole walk (fail-soft).
+      try {
+        await scanDir(childAbs, childRel, depth + 1, out)
+      } catch { /* skip the unreadable subtree */ }
+    }
+  }
+
+  return {
+    async findNestedRepos(workspacePath) {
+      const root = workspacePath.replace(/[\\/]+$/, '')
+      const now = Date.now()
+      const cached = cache.get(root)
+      if (ttlMs > 0 && cached !== undefined && now - cached.at < ttlMs) return cached.repos
+      const out: RepoRef[] = []
+      try {
+        await scanDir(root, '', 1, out)
+      } catch {
+        /* fail-soft: keep whatever was found before the error */
+      }
+      if (ttlMs > 0) cache.set(root, { at: now, repos: out })
+      return out
+    },
+    clearCache() {
+      cache.clear()
+    },
+  }
+}