dsh-taskboard 0.6.1 → 0.6.3

package/src/client/controller.ts

@@ -7,7 +7,7 @@
  *
  * @module dsh-taskboard/client/controller
  */
-import type { ChangeEvent, DiagnosticsResponse, DiffResponse, ImportCommitResponse, ImportPreviewResponse, PromptCompletionsResponse, TaskTemplate, TaskTemplateSpec, UpdateTaskBody, WorkspaceView } from '../shared/api.ts'
+import type { ChangeEvent, DiagnosticsResponse, DiffResponse, ImportCommitResponse, ImportPreviewResponse, MergeRepoResult, PromptCompletionsResponse, TaskTemplate, TaskTemplateSpec, UpdateTaskBody, WorkspaceView } from '../shared/api.ts'
 import type { ChecklistItem, TaskLedger, TaskRecord, Urgency } from '../shared/protocol.ts'
 import { emptyLedger } from '../shared/protocol.ts'
 import type { TaskboardClient } from './api.ts'
@@ -277,6 +277,12 @@ export class BoardController {
     return this.state.workspaces.find(w => w.id === workspaceId)?.gitAvailable === true
   }
 
+  /** How many repos a task mirror of this workspace would cover (0.6.3 mirror badge). */
+  repoCount(workspaceId: string | undefined): number {
+    if (workspaceId === undefined) return 1
+    return this.state.workspaces.find(w => w.id === workspaceId)?.repoCount ?? 1
+  }
+
   /**
    * Install the session-jump bridge (built from the runtime sessions service
    * by the client entry). Without it openSession reports 'unavailable'.
@@ -473,8 +479,8 @@ export class BoardController {
     }
   }
 
-  /** Diff view (0.4.0): one execution's commit or changed path; errors surface via throw. */
-  async fetchDiff(taskId: string, query: { execution: string; commit?: string; path?: string }): Promise<DiffResponse | undefined> {
+  /** Diff view (0.4.0): one execution's commit or changed path; `repo` picks a mirror repo (0.6.3). */
+  async fetchDiff(taskId: string, query: { execution: string; commit?: string; path?: string; repo?: string }): Promise<DiffResponse | undefined> {
     try {
       return await this.client.diff(taskId, query)
     } catch (error) {
@@ -520,13 +526,16 @@ export class BoardController {
 
   /**
    * ⇥ 合并 (detail page): merge the task branch into the main worktree.
-   * @returns the outcome; `noop` means the branch had no new commits (nothing merged).
+   * @returns the outcome; `noop` means the branch had no new commits (nothing
+   * merged); multi-repo tasks (0.6.3) additionally carry per-repo `results`.
    */
-  async mergeBranch(id: string): Promise<{ ok: true; noop?: boolean } | { ok: false; error: string }> {
+  async mergeBranch(id: string): Promise<{ ok: true; noop?: boolean; results?: MergeRepoResult[] } | { ok: false; error: string }> {
     try {
       const value = await this.client.mergeBranch(id)
       await this.refresh()
-      return value.noop === true ? { ok: true, noop: true } : { ok: true }
+      return value.noop === true
+        ? { ok: true, noop: true }
+        : value.results !== undefined ? { ok: true, results: value.results } : { ok: true }
     } catch (error) {
       return { ok: false, error: error instanceof Error ? error.message : String(error) }
     }

package/src/client/i18n/en.ts

@@ -166,6 +166,9 @@ export const en: TaskboardDict = {
   'iso.merge.button': '⇥ Merge into main worktree',
   'iso.merge.failed': 'Merge failed: {error}',
   'iso.merge.noop': 'The branch has no commits ahead of the main worktree — nothing to merge (send it back to continue running, or clean it up)',
+  'iso.merge.done': 'Merged per repo (--no-ff): {summary}',
+  'iso.merge.partial': 'Some repos failed to merge: {summary}\n{error}',
+  'iso.repo.root': 'Root repo',
   'iso.remove.wt': '🗑 Remove worktree',
   'iso.remove.wtTitle': 'git worktree remove (refused when uncommitted changes exist)',
   'iso.remove.wtb': '🗑 Remove worktree + branch',
@@ -290,6 +293,7 @@ export const en: TaskboardDict = {
   'form.iso.noneHintNonGit': 'Not a git repository; will run in the project directory',
   'form.iso.noneHint': 'No git; works directly in the project directory',
   'form.iso.nonGitNote': 'This project is not a git repository; the task will run in its directory (still created with the default configuration; the runtime degrades automatically)',
+  'form.iso.mirrorNote': 'Multi-repo workspace: worktree isolation automatically mirrors all {n} repos — one task branch each, merged per repo at acceptance',
   'form.field.checklist': 'Acceptance checklist (DoD)',
   'form.field.checklistOptional': 'Acceptance checklist (DoD, optional)',
   'form.check.itemPlaceholder': 'Checklist item {n} (definition of done)',
@@ -361,7 +365,7 @@ export const en: TaskboardDict = {
   'set.subtitle': 'Global defaults for new tasks and session sync',
   'set.iso.heading': 'Default execution isolation',
   'set.iso.noneHint': 'No git; works directly in the project directory (factory default)',
-  'set.iso.worktreeHint': 'Each execution runs on its own worktree branch (task/title+ID), isolated from the others',
+  'set.iso.worktreeHint': 'Each execution runs on its own worktree branch (task/title+ID), isolated from the others; multi-repo workspaces are mirrored whole (one branch per repo)',
   'set.iso.current': 'Currently saved default: {current}. Affects only tasks created hereafter; existing tasks keep their creation-time choice, and non-git projects still degrade to the project directory at run time.',
   'set.sync.heading': 'Auto-sync workspace sessions',
   'set.sync.off.name': '🚫 Sync off',

package/src/client/i18n/zh.ts

@@ -168,6 +168,9 @@ export const zh = {
   'iso.merge.button': '⇥ 合并到主工作区',
   'iso.merge.failed': '合并失败：{error}',
   'iso.merge.noop': '该分支没有领先主工作区的新提交，无需合并（可退回续跑或直接清理）',
+  'iso.merge.done': '已按仓库合并（--no-ff）：{summary}',
+  'iso.merge.partial': '部分仓库合并失败：{summary}\n{error}',
+  'iso.repo.root': '根仓库',
   'iso.remove.wt': '🗑 删除 worktree',
   'iso.remove.wtTitle': 'git worktree remove（有未提交修改时拒绝）',
   'iso.remove.wtb': '🗑 删 worktree + 分支',
@@ -292,6 +295,7 @@ export const zh = {
   'form.iso.noneHintNonGit': '当前项目非 git 仓库，将在原目录执行',
   'form.iso.noneHint': '不使用 git，直接在项目目录工作',
   'form.iso.nonGitNote': '当前项目非 git 仓库，将在原目录执行（任务仍按默认配置创建，运行时自动降级）',
+  'form.iso.mirrorNote': '多仓库工作区：Worktree 隔离将自动整区镜像 {n} 个仓库——每仓库独立任务分支，验收按仓库合并',
   'form.field.checklist': '验收清单（DoD）',
   'form.field.checklistOptional': '验收清单（DoD，可选）',
   'form.check.itemPlaceholder': '验收项 {n}（完成标准）',
@@ -363,7 +367,7 @@ export const zh = {
   'set.subtitle': '新建任务与会话同步的全局默认值',
   'set.iso.heading': '默认执行隔离',
   'set.iso.noneHint': '不使用 git，直接在项目目录工作（出厂默认）',
-  'set.iso.worktreeHint': '每次执行在独立 worktree 分支上进行（task/标题+ID），互不污染',
+  'set.iso.worktreeHint': '每次执行在独立 worktree 分支上进行（task/标题+ID），互不污染；多仓库工作区自动整区镜像（每仓库独立分支）',
   'set.iso.current': '当前保存的默认：{current}。仅影响之后新建的任务；已有任务保持创建时的选择，非 git 项目运行时仍自动降级原目录。',
   'set.sync.heading': '自动同步工作区会话',
   'set.sync.off.name': '🚫 关闭同步',

package/src/client/styles.ts

@@ -622,6 +622,13 @@ button.dsh-atb-chip2.dsh-atb-chip-btn:hover {
 .dsh-atb-isolation-note { display: block; margin-top: 6px; font-size: 11px; color: var(--dsw-alias-label-tertiary, gray); }
 .dsh-atb-mode-picker[data-disabled="true"] .dsh-atb-mode-opt { cursor: not-allowed; opacity: .55; }
 .dsh-atb-iso-none { font-size: 12.5px; color: var(--dsw-alias-label-secondary, inherit); }
+.dsh-atb-iso-repo[data-multi="true"] { padding: 6px 0 2px; border-top: 1px dashed var(--dsw-alias-border-secondary, #ddd2); }
+.dsh-atb-iso-repo[data-multi="true"]:first-of-type { border-top: none; padding-top: 0; }
+.dsh-atb-iso-repohead { display: flex; flex-wrap: wrap; gap: 6px 12px; margin-bottom: 6px; align-items: baseline; }
+.dsh-atb-iso-repohead code {
+font-family: ui-monospace, Consolas, monospace; font-size: 11.5px; font-weight: 600;
+color: var(--dsw-alias-state-business-primary, #3e63dd);
+}
 .dsh-atb-iso-facts { display: flex; flex-wrap: wrap; gap: 6px 12px; margin-bottom: 8px; }
 .dsh-atb-iso-fact { font-size: 11.5px; color: var(--dsw-alias-label-secondary, inherit); }
 .dsh-atb-iso-fact b { font-weight: 600; color: var(--dsw-alias-state-business-primary, #3e63dd); }

package/src/host/execution.ts

@@ -18,12 +18,15 @@ import {
   newExecutionId,
   normalizeBody,
   type ExecutionRecord,
+  type ExecutionRepoEvidence,
   type IsolationMode,
   type PermissionMode,
   type TaskModel,
   type TaskRecord,
 } from '../shared/protocol.ts'
-import { sanitizeBranchName, worktreePathOf, type GitFace, type SettlementFacts } from './git.ts'
+import { sanitizeBranchName, type GitFace, type SettlementFacts } from './git.ts'
+import { isLegacySingle, prepareMirror, type PreparedMirror, type PreparedMirrorRepo } from './isolation.ts'
+import { createRepoScanner, type RepoScanner } from './repos.ts'
 import { MessageId } from './sdk.ts'
 import type { TaskStore } from './store.ts'
 
@@ -94,6 +97,11 @@ export interface ExecutionDeps {
    * task degrades to the original directory with an isolationNote.
    */
   git?: GitFace
+  /**
+   * Nested-repo scanner for multi-repo mirrors (0.6.3). Absent → a default
+   * real-filesystem scanner is built on first use.
+   */
+  scanner?: RepoScanner
   /**
    * Resolve the preset composition for an execution session (0.3.3): hands
    * the session its tool set. Absent → sessions run on the bare host
@@ -131,15 +139,6 @@ function isErrorTurnEnd(data: unknown): { message: string } | undefined {
   return { message }
 }
 
-/** Prepared worktree facts threaded through a live run (settlement evidence). */
-export interface PreparedWorktree {
-  branch: string
-  worktreePath: string
-  baseCommit: string
-  /** True when an existing live worktree was kept as-is (续跑). */
-  reused?: boolean
-}
-
 /** Per-run options. */
 export interface RunOptions {
   /**
@@ -153,8 +152,8 @@ export interface RunOptions {
 /** One live execution tracked for settlement and cancellation. */
 interface RunEntry {
   sessionId: string
-  /** Worktree prepared for this run (evidence collection at ANY settlement). */
-  prepared?: PreparedWorktree
+  /** Task mirror prepared for this run (evidence collection at ANY settlement). */
+  prepared?: PreparedMirror
   settle: () => void
   dispose: () => Promise<void>
 }
@@ -193,28 +192,74 @@ export class ExecutionService {
   }
 
   /**
-   * Best-effort evidence collection for a prepared run (fail-soft: undefined
-   * on any git problem — settlement NEVER blocks on git).
+   * Best-effort evidence collection for a prepared mirror: a repo whose git
+   * collect fails is SKIPPED (missing pieces stay unset — settlement NEVER
+   * blocks on git); all-fail resolves undefined.
    */
-  private async collectEvidence(prepared: PreparedWorktree | undefined): Promise<SettlementFacts | undefined> {
-    if (prepared === undefined || this.deps.git === undefined) return undefined
-    try {
-      return await this.deps.git.collect(prepared.worktreePath, prepared.baseCommit)
-    } catch {
-      return undefined
+  private async collectEvidence(prepared: PreparedMirror | undefined): Promise<Array<{ repo: PreparedMirrorRepo; facts: SettlementFacts }> | undefined> {
+    if (prepared === undefined || this.deps.git === undefined || prepared.repos.length === 0) return undefined
+    const out: Array<{ repo: PreparedMirrorRepo; facts: SettlementFacts }> = []
+    // The root worktree's status lists its nested child worktrees as untracked
+    // noise — exclude them so a fully committed mirror doesn't report fake
+    // dirty evidence (0.6.3 review fix).
+    const nestedRels = prepared.repos.filter(r => r.repo !== '').map(r => r.repo)
+    for (const repo of prepared.repos) {
+      try {
+        const facts = await this.deps.git.collect(
+          repo.worktreePath,
+          repo.baseCommit,
+          repo.repo === '' && nestedRels.length > 0 ? nestedRels : undefined,
+        )
+        out.push({ repo, facts })
+      } catch {
+        /* fail-soft: this repo contributes no evidence */
+      }
+    }
+    return out.length > 0 ? out : undefined
+  }
+
+  /** Map one repo's settlement facts onto evidence record fields. */
+  private factsFields(facts: SettlementFacts): Omit<ExecutionRepoEvidence, 'repo' | 'branch' | 'worktreePath' | 'baseCommit'> {
+    return {
+      ...(facts.headCommit !== undefined ? { headCommit: facts.headCommit } : {}),
+      commits: facts.commits,
+      commitsTotal: facts.commitsTotal,
+      dirtyFiles: facts.dirtyFiles,
+      dirtyFilesTotal: facts.dirtyFilesTotal,
+      changedFiles: facts.changedFiles,
+      ...(facts.diffStat !== undefined ? { diffStat: facts.diffStat } : {}),
     }
   }
 
-  /** Copy collected facts onto an execution record (in place). */
-  private applyFacts(execution: ExecutionRecord, facts: SettlementFacts | undefined): void {
-    if (facts === undefined) return
-    if (facts.headCommit !== undefined) execution.headCommit = facts.headCommit
-    execution.commits = facts.commits
-    execution.commitsTotal = facts.commitsTotal
-    execution.dirtyFiles = facts.dirtyFiles
-    execution.dirtyFilesTotal = facts.dirtyFilesTotal
-    execution.changedFiles = facts.changedFiles
-    if (facts.diffStat !== undefined) execution.diffStat = facts.diffStat
+  /**
+   * Copy collected facts onto an execution record (in place). The legacy
+   * flat fields always carry the FIRST repo (the workspace root when it has
+   * one) so single-repo records stay byte-identical to the pre-mirror shape;
+   * non-legacy mirrors additionally fill the per-repo `repos` evidence.
+   */
+  private applyFacts(
+    execution: ExecutionRecord,
+    prepared: PreparedMirror | undefined,
+    evidence: Array<{ repo: PreparedMirrorRepo; facts: SettlementFacts }> | undefined,
+  ): void {
+    if (evidence === undefined || evidence.length === 0) return
+    const first = evidence[0]!.facts
+    if (first.headCommit !== undefined) execution.headCommit = first.headCommit
+    execution.commits = first.commits
+    execution.commitsTotal = first.commitsTotal
+    execution.dirtyFiles = first.dirtyFiles
+    execution.dirtyFilesTotal = first.dirtyFilesTotal
+    execution.changedFiles = first.changedFiles
+    if (first.diffStat !== undefined) execution.diffStat = first.diffStat
+    if (prepared !== undefined && !isLegacySingle(prepared)) {
+      execution.repos = evidence.map(({ repo, facts }) => ({
+        repo: repo.repo,
+        branch: repo.branch,
+        worktreePath: repo.worktreePath,
+        baseCommit: repo.baseCommit,
+        ...this.factsFields(facts),
+      }))
+    }
   }
 
   /**
@@ -228,7 +273,7 @@ export class ExecutionService {
     // The failed session may already have committed work — collect the
     // evidence (best effort) BEFORE marking the execution failed (0.3.1).
     const entry = [...this.runs.values()].find(e => e.sessionId === sessionId)
-    return this.collectEvidence(entry?.prepared).then(facts =>
+    return this.collectEvidence(entry?.prepared).then(evidence =>
       this.deps.store.mutate('execution-recorded', (ledger) => {
         for (const task of ledger.tasks) {
           for (const execution of task.executions) {
@@ -236,7 +281,7 @@ export class ExecutionService {
               execution.outcome = 'failed'
               execution.error = message.slice(0, 500)
               execution.endedAt = this.deps.now()
-              this.applyFacts(execution, facts)
+              this.applyFacts(execution, entry?.prepared, evidence)
               // The failed session will not finish the work: hand the task back
               // instead of leaving it stuck in in_progress forever — and leave a
               // system comment so the GUI shows why.
@@ -315,7 +360,6 @@ export class ExecutionService {
     //    the original directory fail-soft on any git problem.
     const isolation: IsolationMode = effectiveIsolation(task)
     const branch = task.branch ?? sanitizeBranchName(task.title, task.id)
-    const worktreePath = worktreePathOf(workspace.path, task.id)
 
     // 1. Open the execution record, flip the card to in_progress, and record
     //    the executing session as the claim holder — atomically.
@@ -356,23 +400,39 @@ export class ExecutionService {
 
     // 1b. Worktree preparation (fail-soft): any failure degrades this run to
     //     the original directory with an isolationNote — the ledger and the
-    //     execution pipeline itself never fail over git.
+    //     execution pipeline itself never fail over git. 0.6.3: preparation
+    //     builds a whole-workspace MIRROR (root repo + nested repos); a plain
+    //     single-repo workspace keeps the legacy record shape everywhere.
     let isolationNote: string | undefined
-    let prepared: PreparedWorktree | undefined
+    let prepared: PreparedMirror | undefined
     if (isolation === 'worktree') {
-      const outcome = await this.prepareIsolation(task, workspace.path, worktreePath, branch, options?.reuseWorktree === true)
-      if (outcome.prepared !== undefined) {
-        prepared = outcome.prepared
-        // Persist the isolation facts of the run (branch is already on the
-        // record from the gate mutation).
-        await this.patchExecution(executionId, {
-          worktreePath: outcome.prepared.worktreePath,
-          baseCommit: outcome.prepared.baseCommit,
-        })
-      } else {
-        isolationNote = outcome.note
-        // Degraded run: clear the optimistic worktree markers.
+      if (this.deps.git === undefined) {
+        isolationNote = 'git 集成不可用，已在原目录执行'
         await this.patchExecution(executionId, { isolation: 'none', isolationNote, branch: undefined, worktreePath: undefined, baseCommit: undefined })
+      } else {
+        const outcome = await prepareMirror(
+          { git: this.deps.git, scanner: this.deps.scanner ?? createRepoScanner() },
+          { workspacePath: workspace.path, taskId: task.id, branch, reuse: options?.reuseWorktree === true },
+        )
+        if ('mirror' in outcome) {
+          prepared = outcome.mirror
+          await this.pinBranches(task, prepared)
+          // Persist the isolation facts of the run (branch is already on the
+          // record from the gate mutation). The root repo keeps the legacy
+          // flat fields; non-legacy mirrors also record per-repo entries.
+          const root = prepared.repos[0]
+          await this.patchExecution(executionId, {
+            worktreePath: root?.worktreePath,
+            baseCommit: root?.baseCommit,
+            ...(!isLegacySingle(prepared)
+              ? { repos: prepared.repos.map(r => ({ repo: r.repo, branch: r.branch, worktreePath: r.worktreePath, baseCommit: r.baseCommit })) }
+              : {}),
+          })
+        } else {
+          isolationNote = outcome.note
+          // Degraded run: clear the optimistic worktree markers.
+          await this.patchExecution(executionId, { isolation: 'none', isolationNote, branch: undefined, worktreePath: undefined, baseCommit: undefined })
+        }
       }
     }
 
@@ -397,9 +457,7 @@ export class ExecutionService {
       await this.patchExecution(executionId, { outcome: 'failed', error: `preset 组合失败：${message.slice(0, 400)}`, endedAt: this.deps.now() })
       await this.revertProgress(taskId)
       // S1: a run that never started must not leave its worktree behind.
-      if (prepared !== undefined && this.deps.git !== undefined) {
-        try { await this.deps.git.removeWorktree(workspace.path, prepared.worktreePath) } catch { /* best effort (dirty worktrees are kept) */ }
-      }
+      await this.cleanupMirror(prepared, workspace.path)
       return { ok: false, error: `preset composition failed: ${message}` }
     }
     let handle: Awaited<ReturnType<AgentsFace['create']>>
@@ -425,9 +483,7 @@ export class ExecutionService {
       await this.patchExecution(executionId, { outcome: 'failed', error: message.slice(0, 500), endedAt: this.deps.now() })
       await this.revertProgress(taskId)
       // S1: a run that never started must not leave its worktree behind.
-      if (prepared !== undefined && this.deps.git !== undefined) {
-        try { await this.deps.git.removeWorktree(workspace.path, prepared.worktreePath) } catch { /* best effort (dirty worktrees are kept) */ }
-      }
+      await this.cleanupMirror(prepared, workspace.path)
       return { ok: false, error: message }
     }
 
@@ -443,9 +499,7 @@ export class ExecutionService {
     if (!stillRunning) {
       await handle.dispose().catch(() => { /* best effort */ })
       // S1: do not leave the startup artifacts behind a cancelled run either.
-      if (prepared !== undefined && this.deps.git !== undefined) {
-        try { await this.deps.git.removeWorktree(workspace.path, prepared.worktreePath) } catch { /* best effort */ }
-      }
+      await this.cleanupMirror(prepared, workspace.path)
       return { ok: false, error: 'cancelled during startup' }
     }
 
@@ -522,9 +576,9 @@ export class ExecutionService {
   private async settleExecution(
     executionId: string,
     sessionId: string,
-    prepared: PreparedWorktree | undefined,
+    prepared: PreparedMirror | undefined,
   ): Promise<void> {
-    const facts = await this.collectEvidence(prepared)
+    const evidence = await this.collectEvidence(prepared)
     await this.deps.store.mutate('execution-recorded', (ledger) => {
       for (const t of ledger.tasks) {
         const execution = t.executions.find(e => e.id === executionId)
@@ -532,7 +586,7 @@ export class ExecutionService {
           const now = this.deps.now()
           execution.outcome = 'succeeded'
           execution.endedAt = now
-          this.applyFacts(execution, facts)
+          this.applyFacts(execution, prepared, evidence)
           if (t.status === 'in_progress' && t.claimedBy === sessionId) {
             delete t.claimedBy
             delete t.claimedAt
@@ -559,57 +613,60 @@ export class ExecutionService {
   }
 
   /**
-   * Prepare the dedicated worktree for a run (fail-soft): detect git, then
-   * create/reset the fixed task branch — fresh baseline, or keep a live
-   * worktree as-is for 续跑. On success the branch name is pinned onto the
-   * task once (renames never change it); on any failure the run degrades
-   * with a human-readable note.
+   * Pin branch names at FIRST successful creation (§9: 改名不改分支) — the
+   * workspace root repo onto the legacy `branch` field, every nested repo
+   * into the `branches` map. Re-checked inside the mutation (the task may
+   * have moved between preparation and commit).
    */
-  private async prepareIsolation(
-    task: TaskRecord,
-    workspacePath: string,
-    worktreePath: string,
-    branch: string,
-    reuse: boolean,
-  ): Promise<{ prepared?: PreparedWorktree; note?: string }> {
-    const git = this.deps.git
-    if (git === undefined) return { note: 'git 集成不可用，已在原目录执行' }
-    let inside = false
-    try {
-      inside = await git.detect(workspacePath)
-    } catch { /* fail-soft */ }
-    if (!inside) {
-      // Distinguish 未装 git from 非 git 仓库 (0.3.1): probe the binary so the
-      // degradation note names the real cause.
-      let hasBinary = true
-      try {
-        hasBinary = await git.binaryAvailable()
-      } catch { /* fail-soft → treat as repo-side */ }
-      return { note: hasBinary ? '当前项目不是 git 仓库，已在原目录执行' : 'git 不可用（未安装或不在 PATH），已在原目录执行' }
+  private async pinBranches(task: TaskRecord, mirror: PreparedMirror): Promise<void> {
+    const wanted: Array<{ repo: string; branch: string }> = []
+    for (const repo of mirror.repos) {
+      if (repo.repo === '') {
+        if (task.branch === undefined) wanted.push({ repo: '', branch: repo.branch })
+      } else if (task.branches?.[repo.repo] === undefined) {
+        wanted.push({ repo: repo.repo, branch: repo.branch })
+      }
     }
-    let info
-    try {
-      info = await git.prepareWorktree(workspacePath, worktreePath, branch, reuse ? 'reuse' : 'fresh')
-    } catch { /* fail-soft */ }
-    if (info === undefined) return { note: 'worktree 准备失败（git 报错或目录被占用），已在原目录执行' }
-    // Pin the branch name at first SUCCESSFUL creation (§9: 改名不改分支).
-    if (task.branch === undefined) {
-      await this.deps.store.mutate('task-updated', (ledger) => {
-        const target = ledger.tasks.find(t => t.id === task.id)
-        if (target !== undefined && target.branch === undefined) {
-          target.branch = branch
-          return [target]
+    if (wanted.length === 0) return
+    await this.deps.store.mutate('task-updated', (ledger) => {
+      const target = ledger.tasks.find(t => t.id === task.id)
+      if (target === undefined) return undefined
+      let touched = false
+      for (const w of wanted) {
+        if (w.repo === '') {
+          if (target.branch === undefined) {
+            target.branch = w.branch
+            touched = true
+          }
+        } else if (target.branches?.[w.repo] === undefined) {
+          target.branches = { ...target.branches, [w.repo]: w.branch }
+          touched = true
         }
-        return undefined
-      })
-    }
-    return {
-      prepared: {
-        branch: info.branch,
-        worktreePath: info.path,
-        baseCommit: info.baseCommit,
-        ...(info.reused === true ? { reused: true } : {}),
-      },
+      }
+      return touched ? [target] : undefined
+    })
+  }
+
+  /**
+   * Best-effort mirror teardown after a failed start (S1): each repo's
+   * worktree is removed through its OWN repo root; dirty worktrees are kept
+   * — never a data-loss primitive.
+   */
+  private async cleanupMirror(mirror: PreparedMirror | undefined, workspacePath: string): Promise<void> {
+    if (mirror === undefined || this.deps.git === undefined) return
+    // Children first (removeMirror's rule): the root worktree's status shows
+    // its still-present child worktrees as untracked, so removing it first
+    // hits a false dirty-worktree refusal and leaves residue behind. The root
+    // gets the noise exemption but NO force: a reused worktree's real agent
+    // dirt must keep it alive. (Structural-noise residue stays recoverable
+    // through the routes' aggregated mirror removal.)
+    const nestedRels = mirror.repos.filter(r => r.repo !== '').map(r => r.repo)
+    for (const repo of [...mirror.repos].reverse()) {
+      const root = repo.repo === '' ? workspacePath : workspacePath + '/' + repo.repo
+      try {
+        await this.deps.git.removeWorktree(root, repo.worktreePath,
+          repo.repo === '' && nestedRels.length > 0 ? { exempt: nestedRels } : undefined)
+      } catch { /* best effort (dirty worktrees are kept) */ }
     }
   }
 
@@ -641,7 +698,7 @@ export class ExecutionService {
 
     // The cancelled session may already have committed work — keep the
     // evidence (best effort) so the user can inspect or 续跑 (0.3.1).
-    const facts = await this.collectEvidence(entry?.prepared)
+    const evidence = await this.collectEvidence(entry?.prepared)
     let settled = false
     await this.deps.store.mutate('execution-recorded', (ledger) => {
       const target = ledger.tasks.find(t => t.id === taskId)
@@ -651,7 +708,7 @@ export class ExecutionService {
       settled = true
       execution.outcome = 'cancelled'
       execution.endedAt = this.deps.now()
-      this.applyFacts(execution, facts)
+      this.applyFacts(execution, entry?.prepared, evidence)
       if (target.status === 'in_progress') {
         target.status = 'todo'
         target.updatedAt = this.deps.now()
@@ -708,10 +765,10 @@ export class ExecutionService {
    * the user reviews at merge time); 续跑 and degraded runs each add their
    * own steering line (0.3.1).
    * @param task - the task.
-   * @param prepared - worktree facts when this run is isolated.
+   * @param prepared - the task mirror when this run is isolated.
    * @param degradeNote - why a worktree task degraded to the main directory.
    */
-  private pluginFraming(task: TaskRecord, prepared?: PreparedWorktree, degradeNote?: string): string {
+  private pluginFraming(task: TaskRecord, prepared?: PreparedMirror, degradeNote?: string): string {
     let text = `【任务看板】${task.title}（ID: ${task.id}）\n`
       + `本会话由任务看板执行服务启动，任务已置为进行中——无需认领；「已完成」仅限用户在界面操作（代码已限制，移了会被拒）。\n`
       + `完成后按序交接：\n`
@@ -728,10 +785,16 @@ export class ExecutionService {
       text += `\n本任务有验收清单（DoD，${done}/${task.checklist.length} 已完成）——按清单干活：\n${items}\n完成一项就用 taskboard_checklist（action=check，附 note 证据）勾选；未完成项会在验收时高亮，全部完成再移待验收。需要补充验收项也可用 action=add 追加。`
     }
     if (prepared !== undefined) {
-      if (prepared.reused === true) {
-        text += `\n本任务启用了 Git Worktree 隔离，且本次为续跑：任务工作目录是独立分支 ${prepared.branch} 的 worktree——\n${prepared.worktreePath}\n上一次执行的改动与提交都保留在原处——请先查看已有改动（git status / git log）再继续，避免重复劳动，并把新完成的工作提交到该分支。`
+      if (isLegacySingle(prepared)) {
+        // Byte-identical legacy single-repo steering (0.3.0–0.6.2 wording).
+        const only = prepared.repos[0]!
+        if (only.reused === true) {
+          text += `\n本任务启用了 Git Worktree 隔离，且本次为续跑：任务工作目录是独立分支 ${only.branch} 的 worktree——\n${only.worktreePath}\n上一次执行的改动与提交都保留在原处——请先查看已有改动（git status / git log）再继续，避免重复劳动，并把新完成的工作提交到该分支。`
+        } else {
+          text += `\n本任务启用了 Git Worktree 隔离：任务工作目录是独立分支 ${only.branch} 的全新 worktree——\n${only.worktreePath}\n（全新检出，不含 node_modules/构建产物，构建或测试前可能需要先安装依赖）。\n⚠ 边界纪律：你的会话根目录是整个项目，但本任务的全部改动必须只发生在上述 worktree 目录内——命令用 workdir 指向它、文件读写用它的绝对路径；不要改动主工作区的任何其它文件；把完成的工作提交（git commit）到该分支，验收将基于该分支的提交记录合并。`
+        }
       } else {
-        text += `\n本任务启用了 Git Worktree 隔离：任务工作目录是独立分支 ${prepared.branch} 的全新 worktree——\n${prepared.worktreePath}\n（全新检出，不含 node_modules/构建产物，构建或测试前可能需要先安装依赖）。\n⚠ 边界纪律：你的会话根目录是整个项目，但本任务的全部改动必须只发生在上述 worktree 目录内——命令用 workdir 指向它、文件读写用它的绝对路径；不要改动主工作区的任何其它文件；把完成的工作提交（git commit）到该分支，验收将基于该分支的提交记录合并。`
+        text += this.mirrorFraming(prepared)
       }
     } else if (degradeNote !== undefined) {
       text += `\n⚠ 本次执行未能建立隔离，正在主项目目录中工作（原因：${degradeNote}）。该目录可能有他人未提交的改动：动手前先 git status 检查现状，改动尽量集中，结束时在评论中说明动了哪些文件；避免把未经验证的改动直接提交到主分支。`
@@ -739,6 +802,27 @@ export class ExecutionService {
     return text
   }
 
+  /**
+   * The multi-repo mirror section of the framing line (0.6.3): per-repo
+   * checkout list, the (possibly partial) coverage boundary, per-repo commit
+   * discipline, and the 禁改 list for repos that failed to mirror.
+   */
+  private mirrorFraming(mirror: PreparedMirror): string {
+    const mode = mirror.allReused ? '续跑' : '全新'
+    const lines = mirror.repos
+      .map(r => `- ${r.repo === '' ? '根仓库' : r.repo} → ${r.worktreePath}（分支 ${r.branch}${r.reused === true ? '，续跑' : ''}）`)
+      .join('\n')
+    let text = `\n本任务启用了 Git Worktree 隔离（多仓库镜像模式，本次${mode}）：整个工作区已镜像到任务目录——\n${mirror.root}\n各仓库检出位置与任务分支（每仓库各一个同名任务分支）：\n${lines}\n（全新检出的镜像不含 node_modules/构建产物，构建或测试前可能需要先安装依赖）。\n⚠ 边界纪律：你的会话根目录是整个项目，但本任务的全部改动必须只发生在上述任务目录内对应仓库的镜像里——命令用 workdir 指向它、文件读写用它的绝对路径；不要改动镜像之外的任何文件；改动发生在哪个仓库，就把完成的工作提交（git commit）到那个仓库的任务分支，验收将按仓库合并各分支的提交记录。`
+    if (mirror.skipped.length > 0) {
+      const skipped = mirror.skipped.map(s => `- ${s.repo}（原因：${s.reason}）`).join('\n')
+      text += `\n⚠ 以下仓库未能建立镜像：\n${skipped}\n本次执行严禁改动这些仓库的主目录。`
+    }
+    if (mirror.allReused) {
+      text += `\n本次为续跑：各仓库上一次执行的改动与提交都保留在镜像原处——动手前先在各仓库镜像里查看已有改动（git status / git log），避免重复劳动。`
+    }
+    return text
+  }
+
   /**
    * The card body as a normal user bubble: the effective prompt (title+
    * description, with the explicit prompt appended when set) with template
@@ -774,4 +858,4 @@ export class ExecutionService {
       return undefined
     })
   }
-}
+}