dsh-taskboard 0.4.5 → 0.5.1

package/src/client/controller.ts

@@ -8,7 +8,7 @@
  * @module dsh-taskboard/client/controller
  */
 import type { ChangeEvent, DiagnosticsResponse, DiffResponse, ImportCommitResponse, ImportPreviewResponse, TaskTemplate, TaskTemplateSpec, UpdateTaskBody, WorkspaceView } from '../shared/api.ts'
-import type { ChecklistItem, IsolationMode, TaskLedger, TaskRecord, Urgency } from '../shared/protocol.ts'
+import type { ChecklistItem, TaskLedger, TaskRecord, Urgency } from '../shared/protocol.ts'
 import { emptyLedger } from '../shared/protocol.ts'
 import type { TaskboardClient } from './api.ts'
 import type { SessionJumpResult } from './session-jump.ts'
@@ -27,26 +27,6 @@ export type SortBy = 'default' | 'updated' | 'urgency' | 'created'
 /** localStorage key for persisted view state (filters + sort). */
 const VIEW_KEY = 'dsh-taskboard-view-v1'
 
-/** localStorage key for the remembered isolation toggle choice (0.3.0). */
-const ISOLATION_KEY = 'dsh-taskboard-isolation-v1'
-
-/** Load the remembered default isolation (worktree unless explicitly turned off). */
-export function loadDefaultIsolation(): IsolationMode {
-  try {
-    const raw = localStorage.getItem(ISOLATION_KEY)
-    return raw === 'none' ? 'none' : 'worktree'
-  } catch {
-    return 'worktree'
-  }
-}
-
-/** Remember the isolation toggle choice across forms (best effort). */
-export function saveDefaultIsolation(mode: IsolationMode): void {
-  try {
-    localStorage.setItem(ISOLATION_KEY, mode)
-  } catch { /* storage unavailable — choice just won't persist */ }
-}
-
 /** Load the persisted view state (never throws; fresh on any parse error). */
 function loadView(): { workspaceId?: string; urgencies: Urgency[]; sortBy: SortBy } {
   try {
@@ -92,6 +72,8 @@ export interface ControllerState {
   tplManagerOpen: boolean
   /** Import modal visible (0.4.0). */
   importOpen: boolean
+  /** Board-settings modal visible (0.5.0). */
+  settingsOpen: boolean
   /** Fields a chosen template prefills into the create form (consumed on open). */
   templatePrefill?: TaskTemplateSpec
   /** Transient error surface (action failures); cleared on next success. */
@@ -114,6 +96,7 @@ function initialState(): ControllerState {
     templates: [],
     tplManagerOpen: false,
     importOpen: false,
+    settingsOpen: false,
   }
 }
 
@@ -126,7 +109,14 @@ export class BoardController {
   private disposed = false
   private disposeStream: (() => void) | undefined
   private refreshInFlight: Promise<void> | undefined
+  /** Newest change-frame revision seen on the SSE stream (S16 refresh chase). */
+  private seenRevision: number | undefined
   private sessionJumper: ((sessionId: string) => Promise<SessionJumpResult>) | undefined
+  /** Composer catalog faces, installed formally by the client entry (T13). */
+  private readonly catalogFaces: {
+    models?: () => Promise<Array<{ provider: string; model: string; name?: string }>>
+    presets?: () => Promise<{ presets: Array<{ id: string; name?: string }>; defaultId?: string }>
+  } = {}
 
   /** @param client - the route client. */
   constructor(private readonly client: TaskboardClient) {}
@@ -157,8 +147,10 @@ export class BoardController {
     void this.refresh()
     this.disposeStream = this.client.stream(
       (change: ChangeEvent) => {
-        this.setState({ ledger: { ...this.state.ledger, revision: change.revision } })
+        this.seenRevision = change.revision
         // Any change invalidates the full snapshot; refetch (cheap, local).
+        // No intermediate revision-only setState — the refresh result is the
+        // single render a frame produces (review P2: frames rendered twice).
         void this.refresh()
       },
       () => { void this.refresh() },
@@ -170,15 +162,23 @@ export class BoardController {
     if (this.refreshInFlight !== undefined) return this.refreshInFlight
     this.refreshInFlight = (async () => {
       try {
-        const [ledger, workspaces] = await Promise.all([
-          this.client.state(),
-          this.client.workspaces(),
-        ])
-        let selected: TaskRecord | undefined
-        if (this.state.selectedId !== undefined) {
-          selected = ledger.tasks.find(t => t.id === this.state.selectedId)
+        // S16: a change frame landing while a fetch is in flight used to
+        // strand the board on a stale snapshot forever (the deduped request
+        // predates the newest frame and no further event arrives). Chase the
+        // newest seen revision — bounded rounds, then give up until the next
+        // frame.
+        for (let round = 0; round < 3; round++) {
+          const [ledger, workspaces] = await Promise.all([
+            this.client.state(),
+            this.client.workspaces(),
+          ])
+          let selected: TaskRecord | undefined
+          if (this.state.selectedId !== undefined) {
+            selected = ledger.tasks.find(t => t.id === this.state.selectedId)
+          }
+          this.setState({ ledger, workspaces, error: undefined, selectedId: selected === undefined ? undefined : this.state.selectedId })
+          if (this.seenRevision === undefined || ledger.revision >= this.seenRevision) break
         }
-        this.setState({ ledger, workspaces, error: undefined, selectedId: selected === undefined ? undefined : this.state.selectedId })
       } catch (error) {
         this.setState({ error: error instanceof Error ? error.message : String(error) })
       } finally {
@@ -277,6 +277,26 @@ export class BoardController {
     this.sessionJumper = jumper
   }
 
+  /** T13: formal installers for the composer catalog faces (was a monkeypatch from the client entry). */
+  installModelCatalog(fn: () => Promise<Array<{ provider: string; model: string; name?: string }>>): void {
+    this.catalogFaces.models = fn
+  }
+
+  /** T13: formal installer for the preset roster face. */
+  installPresetRoster(fn: () => Promise<{ presets: Array<{ id: string; name?: string }>; defaultId?: string }>): void {
+    this.catalogFaces.presets = fn
+  }
+
+  /** The installed model catalog face, when the runtime provides one. */
+  get modelCatalog(): (() => Promise<Array<{ provider: string; model: string; name?: string }>>) | undefined {
+    return this.catalogFaces.models
+  }
+
+  /** The installed preset roster face, when the runtime provides one. */
+  get presetCatalog(): (() => Promise<{ presets: Array<{ id: string; name?: string }>; defaultId?: string }>) | undefined {
+    return this.catalogFaces.presets
+  }
+
   /**
    * Jump to an execution's session (open it in the GUI). On success the board
    * closes so the conversation shows; a deleted-or-archived session reports
@@ -390,13 +410,18 @@ export class BoardController {
     }
   }
 
-  /** Append a user comment. */
-  async comment(id: string, body: string): Promise<void> {
+  /**
+   * Append a user comment. Returns whether it landed — the composer keeps its
+   * text on failure (T13: it used to clear unconditionally and lose the draft).
+   */
+  async comment(id: string, body: string): Promise<boolean> {
     try {
       await this.client.comment(id, body)
       await this.refresh()
+      return true
     } catch (error) {
       this.setState({ error: error instanceof Error ? error.message : String(error) })
+      return false
     }
   }
 
@@ -459,6 +484,28 @@ export class BoardController {
   /** Close the ⚙ diagnostics panel. */
   closeDiagnostics(): void { this.setState({ diagOpen: false }) }
 
+  /** Open the board-settings modal (0.5.0). */
+  openSettings(): void { this.setState({ settingsOpen: true }) }
+
+  /** Close the board-settings modal. */
+  closeSettings(): void { this.setState({ settingsOpen: false }) }
+
+  /**
+   * Replace board settings (0.5.0). The host broadcasts a settings-updated
+   * frame; refresh() pulls ledger.settings so every open view follows.
+   * @returns whether the write succeeded.
+   */
+  async updateSettings(body: Parameters<TaskboardClient['updateSettings']>[0]): Promise<boolean> {
+    try {
+      await this.client.updateSettings(body)
+      await this.refresh()
+      return true
+    } catch (error) {
+      this.setState({ error: error instanceof Error ? error.message : String(error) })
+      return false
+    }
+  }
+
   /** Clean one orphan worktree (⚙ panel); refreshes the diagnostics payload. */
   async cleanupOrphan(workspaceId: string, taskId: string): Promise<void> {
     try {
@@ -485,7 +532,8 @@ export class BoardController {
   async duplicate(task: TaskRecord): Promise<void> {
     try {
       await this.client.create({
-        title: `${task.title}（副本）`,
+        // Keep the suffix under the host's 200-char title cap (review P1).
+        title: `${task.title.slice(0, 196)}（副本）`,
         workspaceId: task.workspaceId,
         urgency: task.urgency,
         description: task.description.length > 0 ? task.description : undefined,
@@ -615,7 +663,11 @@ export class BoardController {
   /** Download the task list as a CSV (BOM-prefixed for Excel + Chinese text). */
   exportCsv(): void {
     const esc = (v: unknown): string => {
-      const s = String(v ?? '')
+      let s = String(v ?? '')
+      // S17: formula-injection guard — title/description are agent-controllable
+      // and a cell starting with = + - @ would be EXECUTED as a formula by
+      // Excel; neutralize with a leading apostrophe.
+      if (/^[=+\-@\t\r]/.test(s)) s = `'${s}`
       return /[",\n\r]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s
     }
     const header = ['id', 'title', 'status', 'urgency', 'blocked', 'project', 'claimedBy', 'mode', 'cron', 'nextRunAt', 'model', 'createdAt', 'updatedAt', 'comments', 'executions']

package/src/client/index.ts

@@ -52,11 +52,13 @@ export function apply(ctx: ClientContextFace): void {
     const client = createClient()
     const controller = new BoardController(client)
 
-    // Model catalog for the composer: llm.models over the connection RPC.
+    // Model catalog for the composer: llm.models over the connection RPC —
+    // installed through the controller's formal installer (T13: no more
+    // monkeypatched instance properties).
     const connection = ctx.get?.('connection') as ConnectionFace | undefined
     if (connection !== undefined) {
       type CatalogRow = { provider: string; model: string; name?: string }
-      ;(controller as unknown as { modelCatalog?: () => Promise<CatalogRow[]> }).modelCatalog = async (): Promise<CatalogRow[]> => {
+      controller.installModelCatalog(async (): Promise<CatalogRow[]> => {
         const response = await connection.api.llm.models({})
         if (!response.result.ok) return []
         const out: CatalogRow[] = []
@@ -66,13 +68,13 @@ export function apply(ctx: ClientContextFace): void {
           }
         }
         return out
-      }
+      })
 
       // Preset roster for the composer (0.3.3): agentPreset.list over the
       // connection RPC — [{id, name}] plus which one is the deployment
       // default (the form pre-selects it on create).
       type PresetRow = { id: string; name?: string }
-      ;(controller as unknown as { presetCatalog?: () => Promise<{ presets: PresetRow[]; defaultId?: string }> }).presetCatalog = async (): Promise<{ presets: PresetRow[]; defaultId?: string }> => {
+      controller.installPresetRoster(async (): Promise<{ presets: PresetRow[]; defaultId?: string }> => {
         const list = connection.api.agentPresets
         if (list === undefined) return { presets: [] }
         const response = await list.list({})
@@ -80,7 +82,7 @@ export function apply(ctx: ClientContextFace): void {
         const presets = response.result.value.presets.map((p: { id: string; name?: string }) => ({ id: p.id, name: p.name }))
         const def = response.result.value.presets.find((p: { id: string; isDefault: boolean }) => p.isDefault)
         return { presets, ...(def !== undefined ? { defaultId: def.id } : {}) }
-      }
+      })
     }
 
     // Session navigation for execution rows: resolved LAZILY on every jump —

package/src/client/sidebar-entry.ts

@@ -196,7 +196,11 @@ interface AtbDebug { attempts: number; found: boolean; placed: boolean }
 export function mountSidebarEntry(controller: BoardController): () => void {
   const entry = createEntry(controller)
   const debug: AtbDebug = { attempts: 0, found: false, placed: false }
-  ;(window as unknown as { __atbDebug?: AtbDebug }).__atbDebug = debug
+  // Debug handle only where the GUI runs locally; never on remote origins.
+  const host = globalThis.location?.hostname
+  if (host === 'localhost' || host === '127.0.0.1') {
+    ;(window as unknown as { __atbDebug?: AtbDebug }).__atbDebug = debug
+  }
   let root: HTMLElement | undefined
   let placed = false
 

package/src/client/styles.ts

@@ -689,6 +689,10 @@ html[data-dsh-atb-active] .dsh-atb-view { display: flex; flex-direction: column;
 .dsh-atb-imp-row-status { font-size: 10.5px; color: var(--dsw-alias-label-tertiary, gray); flex-shrink: 0; }
 .dsh-atb-imp-result { font-size: 12px; color: var(--dsw-alias-state-success-primary, #30a46c); margin-top: 10px; }
 .dsh-atb-badge[data-kind="checklist"] { color: var(--dsw-alias-label-secondary, inherit); }
+/* ---------- 0.5.0 board settings ---------- */
+.dsh-atb-set { max-width: 460px; width: min(460px, 92vw); }
+.dsh-atb-set .dsh-atb-mode-picker { margin-top: 8px; }
+.dsh-atb-set .dsh-atb-isolation-note { margin-top: 10px; }
 `
 
 /** Style element id (stable since 0.1.x: hook for tests and debugging). */

package/src/host/execution.ts

@@ -119,10 +119,8 @@ function isErrorTurnEnd(data: unknown): { message: string } | undefined {
   const kind = (reason as { kind?: unknown }).kind
   if (kind !== 'error') return undefined
   const error = (reason as { error?: { message?: unknown } }).error
-  const detail = JSON.stringify(error) ?? ''
   const message = typeof error?.message === 'string' ? error.message : 'turn failed'
-  console.error('[dsh-taskboard] turn error detail:', detail.slice(0, 2000))
-  void detail
+  console.error('[dsh-taskboard] turn error detail:', JSON.stringify(error)?.slice(0, 2000) ?? '')
   return { message }
 }
 
@@ -161,15 +159,32 @@ export class ExecutionService {
   /** Live executions by execution id (settles and cancels remove entries). */
   private readonly runs = new Map<string, RunEntry>()
 
+  /** Detaches the turn/end listener (plugin teardown — review P1). */
+  private readonly unsubscribeEvents: () => void
+
   /** @param deps - store + agents + workspaces + events + clock. */
   constructor(private readonly deps: ExecutionDeps) {
-    deps.events.onSessionEvent((sessionId, event) => {
+    this.unsubscribeEvents = deps.events.onSessionEvent((sessionId, event) => {
       if (event.type !== 'turn/end') return
+      // S7 (open question): ANY turn/end with an error reason fails the whole
+      // execution and hands the task back. Whether the DSH session loop can
+      // produce recoverable per-turn errors (and keep the session alive) needs
+      // host-side confirmation; if it can, this should count consecutive
+      // errors or wait for an explicit termination signal instead.
       const failure = isErrorTurnEnd(event.data)
-      if (failure !== undefined) this.noteFailure(sessionId, failure.message)
+      if (failure !== undefined) {
+        this.noteFailure(sessionId, failure.message).catch(error => {
+          console.error('[dsh-taskboard] failure settlement error:', error)
+        })
+      }
     })
   }
 
+  /** Detach the settlement listener; safe to call once at plugin teardown. */
+  dispose(): void {
+    this.unsubscribeEvents()
+  }
+
   /**
    * Best-effort evidence collection for a prepared run (fail-soft: undefined
    * on any git problem — settlement NEVER blocks on git).
@@ -195,13 +210,19 @@ export class ExecutionService {
     if (facts.diffStat !== undefined) execution.diffStat = facts.diffStat
   }
 
-  /** Record a turn failure against the running execution of that session and give the task back. */
-  private noteFailure(sessionId: string, message: string): void {
+  /**
+   * Record a turn failure against the running execution of that session and
+   * give the task back. Resolves once the failure settlement has COMMITTED —
+   * R2: the whenIdle rejection path awaits this (and only this) before
+   * releasing its run entry, so a success settlement can never race it into
+   * the ledger and record a failed run as succeeded.
+   */
+  private noteFailure(sessionId: string, message: string): Promise<void> {
     // 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)
-    void this.collectEvidence(entry?.prepared).then(facts => {
-      void this.deps.store.mutate('execution-recorded', (ledger) => {
+    return this.collectEvidence(entry?.prepared).then(facts =>
+      this.deps.store.mutate('execution-recorded', (ledger) => {
         for (const task of ledger.tasks) {
           for (const execution of task.executions) {
             if (execution.sessionId === sessionId && execution.outcome === 'running') {
@@ -229,16 +250,22 @@ export class ExecutionService {
           }
         }
         return undefined
-      })
-    })
+      }),
+    ).then(() => { /* failure settlement committed */ })
   }
 
-  /** Patch one task's execution record in the ledger. */
+  /**
+   * Patch one task's execution record in the ledger. R3 depth: a record that
+   * already settled (cancelled/failed/succeeded) is never resurrected — the
+   * startup path patches sessionId long after the gate opened, and a cancel
+   * may have committed in between.
+   */
   private async patchExecution(executionId: string, patch: Partial<ExecutionRecord>): Promise<void> {
     await this.deps.store.mutate('execution-recorded', (ledger) => {
       for (const task of ledger.tasks) {
         const execution = task.executions.find(e => e.id === executionId)
         if (execution !== undefined) {
+          if (execution.outcome !== 'running') return undefined
           Object.assign(execution, patch)
           return [task]
         }
@@ -296,6 +323,14 @@ export class ExecutionService {
         gate = 'task is already in progress'
         return undefined
       }
+      // S4: authoritative capacity check INSIDE the gate — counts ledger-wide
+      // running executions, immune to the startup window (`runs` registers
+      // only after agent creation, seconds later).
+      const running = ledger.tasks.reduce((n, t) => n + t.executions.filter(e => e.outcome === 'running').length, 0)
+      if (running >= max) {
+        gate = `execution concurrency limit reached (${running}/${max} running)`
+        return undefined
+      }
       target.executions.push({
         id: executionId,
         trigger,
@@ -305,7 +340,7 @@ export class ExecutionService {
       })
       target.status = 'in_progress'
       target.updatedAt = this.deps.now()
-      target.updatedBy = { kind: 'user' }
+      target.updatedBy = { kind: 'system' }
       target.claimedBy = sessionId
       target.claimedAt = this.deps.now()
       return [target]
@@ -354,6 +389,10 @@ export class ExecutionService {
       const message = error instanceof Error ? error.message : String(error)
       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) */ }
+      }
       return { ok: false, error: `preset composition failed: ${message}` }
     }
     let handle: Awaited<ReturnType<AgentsFace['create']>>
@@ -372,9 +411,31 @@ export class ExecutionService {
       const message = error instanceof Error ? error.message : String(error)
       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) */ }
+      }
       return { ok: false, error: message }
     }
 
+    // R3: the startup path above awaited seconds of git + agent work. A
+    // cancel() that landed inside that window already settled the execution
+    // (cancelled + task back to todo) — with nothing registered in `runs`,
+    // it could not dispose the agent this path was about to create. Re-verify
+    // INSIDE the queue (after any enqueued cancel committed) BEFORE injecting:
+    // a cancelled card must not gain a zombie session that burns tokens and
+    // edits files while the task sits in todo, re-runnable by anyone.
+    const stillRunning = await this.deps.store.read(ledger =>
+      ledger.tasks.some(t => t.executions.some(e => e.id === executionId && e.outcome === 'running')))
+    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 */ }
+      }
+      return { ok: false, error: 'cancelled during startup' }
+    }
+
     // 3. Attach the session to the workspace (GUI project session list).
     await this.deps.workspaces.attach(task.workspaceId, sessionId).catch(() => { /* cosmetic */ })
 
@@ -418,9 +479,16 @@ export class ExecutionService {
       void this.settleExecution(executionId, sessionId, prepared)
     }
     this.runs.set(executionId, { sessionId, ...(prepared !== undefined ? { prepared } : {}), settle, dispose: () => handle.dispose() })
+    // R2: the rejection path owns its state transition EXCLUSIVELY — the old
+    // code also called settle() here, racing two evidence collections whose
+    // mutations both checked outcome === 'running': whoever committed first
+    // won, so a run that never reached quiescence could be recorded as
+    // succeeded (and auto-moved to in_review). Now only the failure
+    // settlement writes, and the run entry is released after it commits.
     void handle.agent.whenIdle().then(settle, () => {
       this.noteFailure(sessionId, 'agent did not reach quiescence')
-      settle()
+        .then(() => { this.runs.delete(executionId) })
+        .catch(() => { this.runs.delete(executionId) })
     })
 
     return { ok: true, executionId, sessionId }
@@ -461,7 +529,7 @@ export class ExecutionService {
             })
             t.status = 'in_review'
             t.updatedAt = now
-            t.updatedBy = { kind: 'user' }
+            t.updatedBy = { kind: 'system' }
           }
           return [t]
         }
@@ -554,11 +622,13 @@ 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)
+    let settled = false
     await this.deps.store.mutate('execution-recorded', (ledger) => {
       const target = ledger.tasks.find(t => t.id === taskId)
       if (target === undefined) return undefined
       const execution = target.executions.find(e => e.id === running.id)
       if (execution === undefined || execution.outcome !== 'running') return undefined
+      settled = true
       execution.outcome = 'cancelled'
       execution.endedAt = this.deps.now()
       this.applyFacts(execution, facts)
@@ -570,6 +640,10 @@ export class ExecutionService {
       }
       return [target]
     })
+    // The execution may have settled (succeeded/failed) between the stale
+    // read above and this mutation — a no-op cancel must NOT report success
+    // (the GUI used to show 取消成功 for an already-succeeded run, review P1).
+    if (!settled) return { ok: false, error: 'execution already settled' }
     return { ok: true, executionId: running.id }
   }
 
@@ -656,7 +730,7 @@ export class ExecutionService {
     const lastExec = [...task.executions].reverse().find(e => e.outcome !== 'running')
     const lastExecText = lastExec === undefined
       ? '（无）'
-      : `${lastExec.trigger} · ${lastExec.outcome}${lastExec.error !== undefined ? ` · ${lastExec.error.slice(0, 200)}` : ''} · ${new Date(lastExec.startedAt ?? 0).toISOString()}`
+      : `${lastExec.trigger} · ${lastExec.outcome}${lastExec.error !== undefined ? ` · ${lastExec.error.slice(0, 200)}` : ''} · ${lastExec.startedAt !== undefined ? new Date(lastExec.startedAt).toISOString() : '?'}`
     const lastCommentsText = task.comments.slice(-3)
       .map(c => `[${c.threadId !== undefined ? 'agent' : 'user'}] ${c.body}`)
       .join('\n') || '（无）'

package/src/host/git.ts

@@ -22,7 +22,8 @@
  *
  * @module dsh-taskboard/host/git
  */
-import type { CommitInfo } from '../shared/protocol.ts'
+import { resolve } from 'node:path'
+import { isValidTaskId, type CommitInfo } from '../shared/protocol.ts'
 
 /** Timeout for quick read-only queries (rev-parse / status / log / diff). */
 const QUICK_TIMEOUT_MS = 2_000
@@ -123,8 +124,12 @@ export interface GitFace {
   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>
+  /**
+   * 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).
+   */
+  removeWorktree(root: string, worktreePath: string): Promise<'removed' | 'unregistered'>
   /** Delete a branch; THROWS (e.g. still checked out in a worktree). */
   deleteBranch(root: string, branch: string): Promise<void>
   /**
@@ -162,8 +167,16 @@ export function sanitizeBranchName(title: string, taskId: string): string {
   return head.length === 0 ? `task/${taskId}` : `task/${head}+${taskId}`
 }
 
-/** The canonical worktree path of a task inside its workspace (forward slashes). */
+/**
+ * The canonical worktree path of a task inside its workspace (forward
+ * slashes). R4②: the id is validated HERE so every present and future call
+ * site is covered — a traversal-shaped id must never ride into a filesystem
+ * path (the cleanup/purge flows `rm -rf` what this returns).
+ */
 export function worktreePathOf(workspacePath: string, taskId: string): string {
+  if (!isValidTaskId(taskId)) {
+    throw new Error(`Error: invalid_input: illegal task id ${JSON.stringify(taskId.slice(0, 40))}`)
+  }
   const root = workspacePath.replace(/[\\/]+$/, '').replaceAll('\\', '/')
   return `${root}/${WORKTREE_DIR}/${taskId}`
 }
@@ -219,10 +232,15 @@ export function createGitFace(exec: ExecFn = realExec): GitFace {
       // 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) {
+        // S14: a readable HEAD is not enough — the worktree must be on OUR
+        // branch, otherwise a user-created repo at the path would be silently
+        // taken over. Foreign or detached → fall through to fresh preparation.
+        const wtBranch = wtHead.ok ? await quick(['rev-parse', '--abbrev-ref', 'HEAD'], path) : undefined
+        if (wtHead.ok && wtHead.stdout.trim().length > 0
+          && wtBranch !== undefined && wtBranch.ok && wtBranch.stdout.trim() === branch) {
           return { path, branch, baseCommit: wtHead.stdout.trim(), reused: true }
         }
-        // No live worktree → fall through to a fresh preparation.
+        // No live worktree on our branch → fall through to a fresh preparation.
       }
 
       // Baseline: the main worktree's current HEAD (also validates the repo).
@@ -302,7 +320,8 @@ export function createGitFace(exec: ExecFn = realExec): GitFace {
             return path !== WORKTREE_DIR && !path.startsWith(`${WORKTREE_DIR}/`)
           })
         if (dirtyLines.length > 0) {
-          throw new Error(`主工作区有 ${dirtyLines.length} 处未提交修改，请先提交或暂存后再合并`)
+          // Machine-readable tag: callers classify without parsing zh-CN text.
+          throw Object.assign(new Error(`主工作区有 ${dirtyLines.length} 处未提交修改，请先提交或暂存后再合并`), { code: 'dirty-tree' })
         }
       }
       const merged = await heavy(['merge', '--no-ff', '--no-edit', branch], root)
@@ -320,14 +339,24 @@ export function createGitFace(exec: ExecFn = realExec): GitFace {
       return r.ok
     },
 
-    removeWorktree: (root, worktreePath) => withRootLock(root, async () => {
+    removeWorktree: (root, worktreePath) => 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)
-        throw new Error(`worktree 有 ${lines.length} 处未提交修改，拒绝删除：\n${lines.slice(0, 10).join('\n')}`)
+        // 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)
-      if (!removed.ok) throw new Error(`删除 worktree 失败：${(removed.stderr.trim() || removed.stdout.trim()).slice(0, 300)}`)
+      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
+      // an error the caller should relay verbatim.
+      const list = await quick(['worktree', 'list', '--porcelain'], root)
+      const registered = list.ok && list.stdout.split('\n')
+        .some(l => l.startsWith('worktree ')
+          && resolve(l.slice('worktree '.length).trim()).toLowerCase() === resolve(worktreePath).toLowerCase())
+      if (!registered) return 'unregistered'
+      throw new Error(`删除 worktree 失败：${(removed.stderr.trim() || removed.stdout.trim()).slice(0, 300)}`)
     }),
 
     deleteBranch: (root, branch) => withRootLock(root, async () => {