dsh-taskboard 0.2.2 → 0.3.3

package/src/host/git.ts

@@ -0,0 +1,293 @@
+/**
+ * Host git face (0.3.0): the ONLY place dsh-taskboard shells out to git.
+ * 0.3.1: per-repo serialization of structural operations, binary probing,
+ * no-op merge detection, worktree REUSE mode, and evidence size caps.
+ *
+ * Design invariants (plan §3.4/§3.5):
+ * - NARROW interface: detect / binaryAvailable / prepareWorktree / collect /
+ *   merge / isAncestor / removeWorktree / deleteBranch — nothing else leaks
+ *   into the plugin.
+ * - FAIL-SOFT: every call has a timeout and resolves to a benign result
+ *   (false / undefined / empty facts) on ANY git failure — a missing git,
+ *   a locked worktree, or a damaged repo degrades execution to the original
+ *   directory and NEVER fails the ledger or the run pipeline. Only the
+ *   explicit user actions (merge / remove / deleteBranch) throw, with a
+ *   readable message the GUI surfaces as-is.
+ * - SERIALIZED structural ops: concurrent isolated executions on the SAME
+ *   repository would race on git's index/worktree locks, so every structural
+ *   operation (prepareWorktree / merge / removeWorktree / deleteBranch) runs
+ *   inside a per-root in-process mutex. Read-only collects stay concurrent.
+ * - INJECTABLE runner: the exec layer is a single function so unit tests
+ *   script every path without a real git.
+ *
+ * @module dsh-taskboard/host/git
+ */
+import type { CommitInfo } from '../shared/protocol.ts'
+
+/** Timeout for quick read-only queries (rev-parse / status / log / diff). */
+const QUICK_TIMEOUT_MS = 2_000
+
+/** Timeout for structural operations (worktree add/remove, merge, branch). */
+const HEAVY_TIMEOUT_MS = 15_000
+
+/** Directory under a workspace where task worktrees live. */
+export const WORKTREE_DIR = '.dsh-worktrees'
+
+/** Evidence caps: commits kept per execution record (newest first). */
+export const MAX_COMMIT_EVIDENCE = 50
+
+/** Evidence caps: uncommitted-change lines kept per execution record. */
+export const MAX_DIRTY_EVIDENCE = 100
+
+/** Result of one underlying exec: `ok` is exit-0, output never null. */
+export interface ExecResult { ok: boolean; stdout: string; stderr: string }
+
+/** The injectable exec layer: run `git <args>` under a cwd with a timeout. */
+export type ExecFn = (args: string[], options: { cwd?: string; timeout?: number }) => Promise<ExecResult>
+
+/** Facts needed to open an isolated execution. */
+export interface WorktreeInfo {
+  /** Absolute worktree path (the session's cwd). */
+  path: string
+  /** The task branch checked out there. */
+  branch: 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
+}
+
+/** Settlement facts collected from a worktree (partial on best-effort basis). */
+export interface SettlementFacts {
+  headCommit?: string
+  commits: CommitInfo[]
+  /** Total commits before capping (equals commits.length when under the cap). */
+  commitsTotal: number
+  dirtyFiles: string[]
+  /** Total uncommitted lines before capping. */
+  dirtyFilesTotal: number
+  diffStat?: string
+  changedFiles: number
+}
+
+/** The narrow git face the rest of the plugin depends on. */
+export interface GitFace {
+  /** Whether `root` sits inside a usable git work tree (fail-soft → false). */
+  detect(root: string): Promise<boolean>
+  /** Whether a usable git binary answers at all (distinguishes 未装 git vs 非 git 仓库). */
+  binaryAvailable(): Promise<boolean>
+  /**
+   * Ensure a worktree at `path` on `branch`. Default mode `'fresh'` resets to
+   * the main worktree's current HEAD (每次全新); mode `'reuse'` keeps a live
+   * worktree exactly as-is (续跑 — agent's commits and uncommitted changes
+   * survive) and falls back to a fresh creation when none is alive. Resolves
+   * 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>
+  /** 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; THROWS when it still has uncommitted changes. */
+  removeWorktree(root: string, worktreePath: string): Promise<void>
+  /** Delete a branch; THROWS (e.g. still checked out in a worktree). */
+  deleteBranch(root: string, branch: string): Promise<void>
+}
+
+/**
+ * Build the task branch name `task/<标题>+<taskId>` (plan §9 拍板).
+ *
+ * Title sanitizing: whitespace runs collapse to `-`; git-illegal characters
+ * (`~ ^ : ? * [ \ / @ { }` and friends) are stripped; `..` collapses; the
+ * segment is trimmed of leading/trailing `.-` and truncated to ~20 code
+ * points; an empty result falls back to the bare `task/<taskId>`.
+ * @param title - the task title (already normalized 1..200 chars).
+ * @param taskId - the task id (stable suffix).
+ * @returns the branch name.
+ */
+export function sanitizeBranchName(title: string, taskId: string): string {
+  const segment = title.trim()
+    .replace(/\s+/g, '-')
+    .replace(/[/\\~^:?*[\]@{}"'<>|#%&;$!`'=,;()]+/g, '')
+    .replace(/\.\.+/g, '.')
+    .replace(/^[-.\s]+|[-.\s]+$/g, '')
+  const head = Array.from(segment).slice(0, 20).join('').replace(/^[-.]+|[-.]+$/g, '')
+  return head.length === 0 ? `task/${taskId}` : `task/${head}+${taskId}`
+}
+
+/** The canonical worktree path of a task inside its workspace (forward slashes). */
+export function worktreePathOf(workspacePath: string, taskId: string): string {
+  const root = workspacePath.replace(/[\\/]+$/, '').replaceAll('\\', '/')
+  return `${root}/${WORKTREE_DIR}/${taskId}`
+}
+
+/** Real exec layer over child_process.execFile (windowsHide, timeout, maxBuffer). */
+const realExec: ExecFn = (args, options) => new Promise(resolve => {
+  void (async () => {
+    const { execFile } = await import('node:child_process')
+    execFile('git', args, {
+      cwd: options.cwd,
+      timeout: options.timeout ?? QUICK_TIMEOUT_MS,
+      windowsHide: true,
+      maxBuffer: 4 * 1024 * 1024,
+      encoding: 'utf8',
+    }, (error, stdout, stderr) => {
+      resolve({ ok: error === null, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') })
+    })
+  })().catch(() => resolve({ ok: false, stdout: '', stderr: 'exec unavailable' }))
+})
+
+/**
+ * Build a {@link GitFace} over an injectable exec layer.
+ * @param exec - the exec function (real `git` when omitted).
+ */
+export function createGitFace(exec: ExecFn = realExec): GitFace {
+  const quick = (args: string[], cwd?: string): Promise<ExecResult> => exec(args, { cwd, timeout: QUICK_TIMEOUT_MS })
+  const heavy = (args: string[], cwd?: string): Promise<ExecResult> => exec(args, { cwd, timeout: HEAVY_TIMEOUT_MS })
+
+  // Per-root mutex (0.3.1): structural git ops on the SAME repository run one
+  // at a time — concurrent isolated executions must not race on git's locks.
+  const locks = new Map<string, Promise<unknown>>()
+  const withRootLock = <T>(root: string, fn: () => Promise<T>): Promise<T> => {
+    const prev = locks.get(root) ?? Promise.resolve()
+    const next = prev.then(fn, fn)
+    locks.set(root, next.catch(() => { /* the chain never blocks later ops */ }))
+    return next
+  }
+
+  return {
+    async detect(root) {
+      const r = await quick(['rev-parse', '--is-inside-work-tree'], root)
+      return r.ok && r.stdout.trim() === 'true'
+    },
+
+    async binaryAvailable() {
+      const r = await quick(['--version'])
+      return r.ok && r.stdout.startsWith('git version')
+    },
+
+    prepareWorktree: (root, path, branch, mode = 'fresh') => withRootLock(root, async () => {
+      // 续跑: a live worktree at the path is kept EXACTLY as-is — the agent's
+      // commits and uncommitted changes survive; the baseline becomes the
+      // worktree's own HEAD so evidence covers only the new run.
+      if (mode === 'reuse') {
+        const wtHead = await quick(['rev-parse', 'HEAD'], path)
+        if (wtHead.ok && wtHead.stdout.trim().length > 0) {
+          return { path, branch, baseCommit: wtHead.stdout.trim(), reused: true }
+        }
+        // No live worktree → fall through to a fresh preparation.
+      }
+
+      // Baseline: the main worktree's current HEAD (also validates the repo).
+      const head = await quick(['rev-parse', 'HEAD'], root)
+      if (!head.ok) return undefined
+      const baseCommit = head.stdout.trim()
+
+      const exists = await quick(['show-ref', '--verify', `refs/heads/${branch}`], root)
+      if (exists.ok) {
+        // Reuse the fixed branch name, but guarantee a FRESH baseline: drop
+        // any stale worktree at the path, move the branch to the current
+        // HEAD, then check the branch out again (每次全新，复用仅作选项保留).
+        await heavy(['worktree', 'remove', '--force', path], root)
+        await heavy(['worktree', 'prune'], root)
+        const moved = await heavy(['branch', '-f', branch, 'HEAD'], root)
+        if (!moved.ok) return undefined
+        const added = await heavy(['worktree', 'add', path, branch], root)
+        if (!added.ok) return undefined
+      } else {
+        const added = await heavy(['worktree', 'add', '-b', branch, path], root)
+        if (!added.ok) return undefined
+      }
+      return { path, branch, baseCommit }
+    }),
+
+    async collect(worktreePath, baseCommit) {
+      const facts: SettlementFacts = { commits: [], commitsTotal: 0, dirtyFiles: [], dirtyFilesTotal: 0, changedFiles: 0 }
+      const range = `${baseCommit}..HEAD`
+
+      const head = await quick(['rev-parse', 'HEAD'], worktreePath)
+      if (head.ok) facts.headCommit = head.stdout.trim()
+
+      const log = await quick(['log', '--pretty=format:%h %s', range], worktreePath)
+      if (log.ok) {
+        const commits = log.stdout.split('\n')
+          .map(line => line.trim())
+          .filter(line => line.length > 0)
+          .map(line => {
+            const space = line.indexOf(' ')
+            return space === -1
+              ? { hash: line, subject: '' }
+              : { hash: line.slice(0, space), subject: line.slice(space + 1) }
+          })
+        // Evidence caps (0.3.1): the ledger is rewritten whole on every
+        // mutation — cap what a huge branch/status dump can add to it.
+        facts.commitsTotal = commits.length
+        facts.commits = commits.slice(0, MAX_COMMIT_EVIDENCE)
+      }
+
+      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)
+        facts.dirtyFilesTotal = dirty.length
+        facts.dirtyFiles = dirty.slice(0, MAX_DIRTY_EVIDENCE)
+      }
+
+      const shortstat = await quick(['diff', '--shortstat', range], worktreePath)
+      if (shortstat.ok && shortstat.stdout.trim().length > 0) facts.diffStat = shortstat.stdout.trim()
+
+      const names = await quick(['diff', '--name-only', range], worktreePath)
+      if (names.ok) facts.changedFiles = names.stdout.split('\n').filter(l => l.trim().length > 0).length
+
+      return facts
+    },
+
+    merge: (root, branch) => 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')
+          .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) {
+          throw new Error(`主工作区有 ${dirtyLines.length} 处未提交修改，请先提交或暂存后再合并`)
+        }
+      }
+      const merged = await heavy(['merge', '--no-ff', '--no-edit', branch], root)
+      if (!merged.ok) {
+        // Roll the half-finished merge back so the main worktree stays usable;
+        // report the ORIGINAL failure verbatim (不自动解决冲突).
+        await heavy(['merge', '--abort'], root)
+        throw new Error(`合并失败：${merged.stderr.trim().slice(0, 300)}`)
+      }
+    }),
+
+    async isAncestor(root, branch) {
+      // exit 0 = branch is an ancestor of (or equal to) HEAD → merge no-op.
+      const r = await quick(['merge-base', '--is-ancestor', branch, 'HEAD'], root)
+      return r.ok
+    },
+
+    removeWorktree: (root, worktreePath) => withRootLock(root, async () => {
+      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)
+        throw new Error(`worktree 有 ${lines.length} 处未提交修改，拒绝删除：\n${lines.slice(0, 10).join('\n')}`)
+      }
+      const removed = await heavy(['worktree', 'remove', worktreePath], root)
+      if (!removed.ok) throw new Error(`删除 worktree 失败：${(removed.stderr.trim() || removed.stdout.trim()).slice(0, 300)}`)
+    }),
+
+    deleteBranch: (root, branch) => withRootLock(root, async () => {
+      const deleted = await heavy(['branch', '-D', branch], root)
+      if (!deleted.ok) throw new Error(`删除分支失败：${deleted.stderr.trim().slice(0, 300)}`)
+    }),
+  }
+}

package/src/host/routes.ts

@@ -10,10 +10,13 @@
  * @module dsh-taskboard/host/routes
  */
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { readdir, rm } from 'node:fs/promises'
+import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 // Type-only: pulls the webServer Context merge (ctx.webServer).
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import {
+  asIsolation,
   asStatus,
   asUrgency,
   canTransition,
@@ -29,6 +32,7 @@ import {
   type TaskModel,
   type TaskRecord,
 } from '../shared/protocol.ts'
+import { WORKTREE_DIR, worktreePathOf, type GitFace } from './git.ts'
 import { ROUTE_PREFIX, SSE_PATH, type ApiFail, type ApiResult } from '../shared/api.ts'
 import type { TaskStore } from './store.ts'
 import type { WorkspaceFace } from './tools.ts'
@@ -36,6 +40,9 @@ import type { WorkspaceFace } from './tools.ts'
 /** Heartbeat cadence for the SSE stream. */
 const HEARTBEAT_MS = 20_000
 
+/** How long a workspace git-detection result stays cached (fail-soft). */
+const GIT_DETECT_TTL_MS = 60_000
+
 /** The workspaces face routes need (same narrow shape as tools). */
 export type RoutesWorkspaceFace = WorkspaceFace
 
@@ -44,8 +51,8 @@ export interface TaskboardRoutesOptions {
   store: TaskStore
   workspaces: RoutesWorkspaceFace
   now: () => number
-  /** Manual-run hook (the execution service); absent → 501. */
-  run?: (taskId: string) => Promise<{ ok: true; executionId: string; sessionId: string } | { ok: false; error: string }>
+  /** Manual-run hook (the execution service); absent → 501. Options carry `reuseWorktree` (续跑). */
+  run?: (taskId: string, options?: { reuseWorktree?: boolean }) => Promise<{ ok: true; executionId: string; sessionId: string } | { ok: false; error: string }>
   /** Cancel hook (the execution service); absent → 501. */
   cancel?: (taskId: string) => Promise<{ ok: true; executionId: string } | { ok: false; error: string }>
   /**
@@ -53,6 +60,8 @@ export interface TaskboardRoutesOptions {
    * advisory validation of pinned models; undefined = runtime unavailable.
    */
   modelProviders?: () => string[] | undefined
+  /** Git face for worktree actions + workspace git detection; absent → 501 on git actions. */
+  git?: GitFace
 }
 
 /** Validate a pinned model: structural check always, provider route when known. */
@@ -108,6 +117,12 @@ function num(body: Record<string, unknown>, key: string): number | undefined | n
   return typeof v === 'number' && Number.isFinite(v) ? v : null
 }
 
+/** Normalize an agent preset id: trimmed, non-empty; empty string → undefined. */
+function normalizePresetId(raw: string | null): string | undefined {
+  const t = (raw ?? '').trim()
+  return t.length === 0 ? undefined : t
+}
+
 /** Map a thrown domain error to the envelope. */
 function toFail(error: unknown): { res: ApiFail; status: number } {
   const message = error instanceof Error ? error.message : String(error)
@@ -137,6 +152,72 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
   }
   store.subscribe(broadcast)
 
+  // Workspace git detection, TTL-cached and fail-soft (false on any error):
+  // feeds the create-form isolation toggle and the diagnostics panel.
+  const gitCache = new Map<string, { value: boolean; at: number }>()
+  const gitHinted = new Set<string>()
+
+  /** Whether <root>/.gitignore (missing file counts as missing) ignores our worktree dir. */
+  const gitignoreMissing = async (path: string): Promise<boolean> => {
+    try {
+      const { readFile } = await import('node:fs/promises')
+      const ignore = await readFile(join(path, '.gitignore'), 'utf8')
+      return !ignore.split('\n').some(l => {
+        const t = l.trim().replace(/\/+$/, '')
+        return t === WORKTREE_DIR || t === `/${WORKTREE_DIR}`
+      })
+    } catch {
+      return true // no .gitignore at all (or unreadable) → suggest creating one
+    }
+  }
+
+  const gitAvailable = async (path: string): Promise<boolean> => {
+    if (options.git === undefined) return false
+    const hit = gitCache.get(path)
+    if (hit !== undefined && options.now() - hit.at < GIT_DETECT_TTL_MS) return hit.value
+    let value = false
+    try {
+      value = await options.git.detect(path)
+    } catch { /* fail-soft → false */ }
+    gitCache.set(path, { value, at: options.now() })
+    // gitignore 建议 (plan §3.2): suggest (never write) ignoring our
+    // worktree directory, once per workspace per host run.
+    if (value && !gitHinted.has(path)) {
+      gitHinted.add(path)
+      if (await gitignoreMissing(path)) {
+        console.info(`[dsh-taskboard] 建议在 ${path}/.gitignore 加入一行 ${WORKTREE_DIR}/ 以隐藏任务 worktree 目录（不会自动修改）`)
+      }
+    }
+    return value
+  }
+
+  /** List orphan worktree dirs: entries under <ws>/.dsh-worktrees owned by no ledger task. */
+  const listOrphanWorktrees = async (): Promise<Array<{ workspaceId: string; workspacePath: string; taskId: string; path: string }>> => {
+    const orphans: Array<{ workspaceId: string; workspacePath: string; taskId: string; path: string }> = []
+    const known = new Set(store.snapshot().tasks.map(t => t.id))
+    for (const ws of workspaces.list()) {
+      let entries: string[] = []
+      try {
+        const dirents = await readdir(join(ws.path, WORKTREE_DIR), { withFileTypes: true })
+        entries = dirents.filter(e => e.isDirectory()).map(e => e.name)
+      } catch { /* no worktrees dir → nothing to do */ }
+      for (const taskId of entries) {
+        if (!known.has(taskId)) orphans.push({ workspaceId: ws.id, workspacePath: ws.path, taskId, path: worktreePathOf(ws.path, taskId) })
+      }
+    }
+    return orphans
+  }
+
+  /** Git-enabled workspaces whose .gitignore does not cover the worktree dir. */
+  const listGitignoreSuggestions = async (): Promise<Array<{ workspaceId: string; workspacePath: string }>> => {
+    const suggestions: Array<{ workspaceId: string; workspacePath: string }> = []
+    for (const ws of workspaces.list()) {
+      if (!(await gitAvailable(ws.path))) continue
+      if (await gitignoreMissing(ws.path)) suggestions.push({ workspaceId: ws.id, workspacePath: ws.path })
+    }
+    return suggestions
+  }
+
   const handler = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     try {
       const url = new URL(req.url ?? '/', 'http://x')
@@ -150,7 +231,30 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
           return
         }
         if (pathname === `${ROUTE_PREFIX}/workspaces`) {
-          json(res, { ok: true, value: workspaces.list() })
+          const list = workspaces.list()
+          const flags = await Promise.all(list.map(ws => gitAvailable(ws.path)))
+          json(res, {
+            ok: true,
+            value: list.map((ws, i) => ({ ...ws, sessionCount: 0, gitAvailable: flags[i] })),
+          })
+          return
+        }
+        if (pathname === `${ROUTE_PREFIX}/diagnostics`) {
+          const ledger = store.snapshot()
+          let staleRunning = 0
+          for (const t of ledger.tasks) {
+            for (const e of t.executions) if (e.outcome === 'running') staleRunning += 1
+          }
+          json(res, {
+            ok: true,
+            value: {
+              revision: ledger.revision,
+              tasks: ledger.tasks.length,
+              staleRunning,
+              orphanWorktrees: await listOrphanWorktrees(),
+              gitIgnoreSuggestions: await listGitignoreSuggestions(),
+            },
+          })
           return
         }
         const taskMatch = pathname.match(new RegExp(`^${ROUTE_PREFIX}/tasks/([^/]+)$`))
@@ -194,6 +298,9 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
           const status = str(body, 'status') === null ? 'todo' as const : asStatus(str(body, 'status')!)
           const execution = normalizeExecution((body.execution as { mode?: string; cron?: string } | undefined) ?? {}, options.now())
           const model = body.model === undefined ? undefined : checkModel(body.model, options.modelProviders)
+          const isolationRaw = str(body, 'isolation')
+          const isolation = isolationRaw === null ? undefined : asIsolation(isolationRaw)
+          const presetId = normalizePresetId(str(body, 'presetId'))
           const now = options.now()
           const task: TaskRecord = {
             id: newTaskId(),
@@ -206,6 +313,8 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             blocked: false,
             execution,
             model,
+            ...(isolation !== undefined ? { isolation } : {}),
+            ...(presetId !== undefined ? { presetId } : {}),
             version: 1,
             createdAt: now,
             updatedAt: now,
@@ -227,7 +336,9 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
       }
 
       // ------------------------------------------- POST /tasks/:id/{action}
-      const actionMatch = pathname.match(new RegExp(`^${ROUTE_PREFIX}/tasks/([^/]+)/(\\w+)$`))
+      // (\w+ after the id would not match hyphenated actions like
+      // worktree-remove, hence the explicit class.)
+      const actionMatch = pathname.match(new RegExp(`^${ROUTE_PREFIX}/tasks/([^/]+)/([\\w-]+)$`))
       if (actionMatch !== null) {
         const id = actionMatch[1]!
         const action = actionMatch[2]!
@@ -258,6 +369,18 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             if (body.execution !== undefined) next.execution = normalizeExecution(body.execution as { mode?: string; cron?: string }, options.now())
             if (body.model === null) next.model = undefined
             else if (body.model !== undefined) next.model = checkModel(body.model, options.modelProviders)
+            // Isolation may change only before the first execution (分支与基线
+            // 取决于该选择 — plan §3.1: 执行开始后锁定).
+            const isolationRaw = str(body, 'isolation')
+            if (isolationRaw !== null) {
+              if (task.executions.length > 0 || task.status === 'in_progress') {
+                throw new Error('Error: invalid_input: isolation 已锁定（任务已有执行记录），不可修改')
+              }
+              next.isolation = asIsolation(isolationRaw)
+            }
+            // Preset may change any time: each run composes fresh.
+            if (body.presetId === null) delete next.presetId
+            else if (body.presetId !== undefined) next.presetId = normalizePresetId(str(body, 'presetId'))!
             next.version = task.version + 1
             next.updatedAt = options.now()
             next.updatedBy = { kind: 'user' }
@@ -336,6 +459,34 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             const purge = body.purge === true
             if (purge) {
               if (task.trashedAt === undefined) throw new Error('Error: invalid_input: purge requires a trashed task (soft-delete first)')
+              // Worktree safety before purge (plan §3.3, 0.3.1): refuse while
+              // uncommitted work remains; otherwise clean the worktree and
+              // the task branch along with the ledger entry.
+              if (options.git !== undefined) {
+                const ws = workspaces.get(task.workspaceId)
+                if (ws !== undefined) {
+                  const path = worktreePathOf(ws.path, id)
+                  try {
+                    await options.git.removeWorktree(ws.path, path)
+                  } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error)
+                    if (message.includes('未提交修改')) {
+                      throw new Error(`Error: invalid_input: ${message}；请先处理这些改动（提交、续跑或手动保存）再物理清除任务`)
+                    }
+                    if (/not a working tree|not a working-tree/i.test(message)) {
+                      // An unregistered leftover dir: plain fs removal.
+                      await rm(path, { recursive: true, force: true })
+                    } else {
+                      throw new Error(`Error: invalid_input: ${message}`)
+                    }
+                  }
+                  if (task.branch !== undefined) {
+                    try {
+                      await options.git.deleteBranch(ws.path, task.branch)
+                    } catch { /* best effort: the branch may outlive the task */ }
+                  }
+                }
+              }
               await store.mutate('task-deleted', ledger => {
                 ledger.tasks = ledger.tasks.filter(t => t.id !== id)
                 return []
@@ -363,7 +514,10 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
               json(res, f.res, 501)
               return
             }
-            const result = await options.run(id)
+            // `reuse: true` = 续跑: keep a live worktree/branch as-is instead
+            // of resetting to a fresh baseline (0.3.1).
+            const runOptions = body.reuse === true ? { reuseWorktree: true } : undefined
+            const result = await options.run(id, runOptions)
             if (result.ok) json(res, { ok: true, value: result }, 202)
             else {
               const f = fail('invalid_input', result.error)
@@ -385,6 +539,78 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             }
             return
           }
+          if (action === 'merge') {
+            // ⇥ 合并 (detail page, user-only): merge the task branch into the
+            // main worktree with --no-ff; conflicts are reported verbatim.
+            if (options.git === undefined) {
+              const f = fail('invalid_input', 'git integration unavailable')
+              json(res, f.res, 501)
+              return
+            }
+            if (task.branch === undefined) throw new Error('Error: invalid_input: 该任务还没有 worktree 分支（未隔离执行过）')
+            if (task.status === 'in_progress') throw new Error('Error: invalid_input: 任务执行中，不能合并')
+            if (task.executions.some(e => e.outcome === 'running')) throw new Error('Error: invalid_input: 任务执行中，不能合并')
+            const ws = workspaces.get(task.workspaceId)
+            if (ws === undefined) throw new Error('Error: not_found: unknown workspace')
+            // No-op detection (0.3.1): a branch with no commits over HEAD
+            // merges as "already up to date" — report that instead of landing
+            // a bogus 已合并 comment.
+            let noop = false
+            try {
+              noop = await options.git.isAncestor(ws.path, task.branch)
+            } catch { /* fail-soft: proceed to the real merge */ }
+            if (noop) {
+              json(res, { ok: true, value: { merged: false, noop: true, branch: task.branch } })
+              return
+            }
+            try {
+              await options.git.merge(ws.path, task.branch)
+            } catch (error) {
+              throw new Error(`Error: invalid_input: ${error instanceof Error ? error.message : String(error)}`)
+            }
+            const mergedComment = { id: newCommentId(), body: normalizeBody(`[系统] 分支 ${task.branch} 已合并到主工作区（--no-ff）。`), version: 1, createdAt: options.now() }
+            const next = structuredClone(task)
+            next.comments.push(mergedComment)
+            next.version = task.version + 1
+            next.updatedAt = options.now()
+            await store.mutate('comment-added', ledger => {
+              const i = ledger.tasks.findIndex(t => t.id === id)
+              ledger.tasks[i] = next
+              return [next]
+            })
+            json(res, { ok: true, value: { merged: true, branch: task.branch } })
+            return
+          }
+          if (action === 'worktree-remove') {
+            // 🗑 删除 worktree (detail page): refuses uncommitted changes;
+            // optionally deletes the task branch after the worktree is gone.
+            if (options.git === undefined) {
+              const f = fail('invalid_input', 'git integration unavailable')
+              json(res, f.res, 501)
+              return
+            }
+            if (task.executions.some(e => e.outcome === 'running')) throw new Error('Error: invalid_input: 任务执行中，不能删除 worktree')
+            const ws = workspaces.get(task.workspaceId)
+            if (ws === undefined) throw new Error('Error: not_found: unknown workspace')
+            const path = worktreePathOf(ws.path, id)
+            try {
+              await options.git.removeWorktree(ws.path, path)
+            } catch (error) {
+              throw new Error(`Error: invalid_input: ${error instanceof Error ? error.message : String(error)}`)
+            }
+            let branchDeleted = false
+            let branchError: string | undefined
+            if (body.deleteBranch === true && task.branch !== undefined) {
+              try {
+                await options.git.deleteBranch(ws.path, task.branch)
+                branchDeleted = true
+              } catch (error) {
+                branchError = error instanceof Error ? error.message : String(error)
+              }
+            }
+            json(res, { ok: true, value: { removed: true, branchDeleted, ...(branchError !== undefined ? { branchError } : {}) } })
+            return
+          }
           const f = fail('not_found', `unknown action ${action}`)
           json(res, f.res, f.status)
         } catch (error) {
@@ -394,6 +620,43 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
         return
       }
 
+      // -------------------------------------- POST /worktree-cleanup (⚙ 诊断)
+      if (pathname === `${ROUTE_PREFIX}/worktree-cleanup`) {
+        try {
+          if (options.git === undefined) {
+            const f = fail('invalid_input', 'git integration unavailable')
+            json(res, f.res, 501)
+            return
+          }
+          const workspaceId = str(body, 'workspaceId') ?? ''
+          const taskId = str(body, 'taskId') ?? ''
+          const ws = workspaces.get(workspaceId)
+          if (ws === undefined) throw new Error('Error: not_found: unknown workspace')
+          // Only dirs owned by NO ledger task may be cleaned here; live tasks
+          // remove their worktree from the detail page.
+          if (store.get(taskId) !== undefined) throw new Error('Error: invalid_input: 任务仍在看板中，请从任务详情页删除其 worktree')
+          const path = worktreePathOf(ws.path, taskId)
+          try {
+            await options.git.removeWorktree(ws.path, path)
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            // An unregistered leftover (git no longer knows this worktree):
+            // fall back to direct fs removal — the dir lives inside the
+            // plugin's own .dsh-worktrees scope.
+            if (/not a working tree|not a working-tree/i.test(message)) {
+              await rm(path, { recursive: true, force: true })
+            } else {
+              throw new Error(`Error: invalid_input: ${message}`)
+            }
+          }
+          json(res, { ok: true, value: { cleaned: true, path } })
+        } catch (error) {
+          const f = toFail(error)
+          json(res, f.res, f.status)
+        }
+        return
+      }
+
       res.writeHead(404)
       res.end()
     } catch (error) {