@goodandready/dsh-kanban 0.1.23 → 0.1.25

package/README.md

@@ -260,6 +260,21 @@ compares the requested names against the actual exports. It is deliberately not
 part of `npm test`: the test suite runs without a core and without a profile.
 Run it on the machine where the harness lives, before publishing.
 
+## 💻 Cross-Platform Path Handling
+
+Task working directories (`resolveCwd`) respect operating system path conventions.
+On Windows, repository root fencing accounts for drive letters and backslash path
+separators, ensuring full test and runtime compatibility across POSIX and Windows.
+
+## 🌳 Git Worktree Isolation
+
+When in-progress work begins on a repository task, the agent session is automatically
+isolated into a dedicated git worktree (`$DSH_HOME/worktrees/<repo-key>/<task-id>/` on branch
+`task/<id>-<slug>`). The worktree is registered in DSH's `workspaceRegistry` for full UI
+visibility and multi-agent concurrency protection. During the `cleanup` phase, uncommitted files
+are detected via `git status --porcelain` to prevent data loss, followed by clean worktree and workspace
+deregistration.
+
 ## 📄 License
 
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/docs/design/DESIGN.md

@@ -0,0 +1,53 @@
+# DESIGN.md — dsh-kanban
+
+## Product / Purpose
+- Назначение: Интегрированная доска задач для DeepSeek Harness с двусторонней сверкой с Gitea, автоматическим подхватом сессий агентов и управлением жизненным циклом.
+- Аудитория: Разработчики и операторы DeepSeek Harness, ведущие проектные задачи и сессии агентов.
+- Статус: Production, версия 0.1.23+.
+
+## User Surfaces
+- Web/UI: Экран доски в центральной колонке интерфейса DSH (mountBoard), выдвигающаяся панель задач, фильтры, группировки (по проектам, по исполнителю), метрики переходов.
+- DSH UI / settings / slots:
+  - Карточка настроек в слоте settings.plugin.item (пространство dsh-kanban).
+  - Чип активной задачи в conversation.session.header.utilities.
+  - Пункт бокового меню для вызова экрана доски.
+- API: HTTP эндпоинты /dsh-kanban/* (board, snapshot, task, sync, webhook, metrics, whoami).
+- CLI: node tools/compat.mjs (проверка совместимости экспортов ядра).
+- Документация: README.md, docs/README.ru.md, docs/README.zh.md, index.md.
+
+## Visual Direction
+- Атмосфера: Строгий утилитарный инструментальный интерфейс в едином стиле темы DeepSeek Harness.
+- Утверждённые референсы и что из них берём: Системные карточки DSH (стили заголовков, отступы, шрифты, цветовые токены --dsw-alias-*).
+- Не копировать: Внешние неинтегрированные темы, разнородные цвета рамок и теней.
+
+## Foundations
+- Цвета и роли: Использование CSS-переменных DSH темы (--dsw-alias-bg-layer-3, --dsw-alias-border-l2, --dsw-alias-label-primary, --dsw-alias-label-secondary).
+- Типографика: Системный стек шрифтов DSH (inherit, 13-14px базовый размер, 11-12px для бейджей и служебных меток).
+- Сетка, отступы, responsive: 5 стандартных колонок (backlog, ready, progress, review, done) с горизонтальным скроллом и адаптивными карточками.
+- Accessibility: Нативные кнопки button, role="status" для сообщений, семантичные поля ввода с aria-label/label.
+
+## Components And States
+- Компоненты: BoardScreen, Column, Card, TaskDrawer, KanbanSettingsCard, TaskChip, MetricsModal.
+- Loading / empty / error / success:
+  - Загрузка: состояние скелетона/лоадера без блокировки скролла.
+  - Пустые колонки: пунктирная область перетаскивания.
+  - Ошибки: всплывающий баннер с ключом локализации t('error.' + err).
+- Формы, валидация и действия: Валидация обязательных полей при создании задачи, блокировка повторных кликов при сохранении.
+
+## User Flows
+- Критические сценарии:
+  1. Создание задачи / подхват из Gitea Issue.
+  2. Перемещение карточки между колонками человеком или через инструмент агента board_move.
+  3. Запуск сессии агента по карточке с автоматическим назначением ответственного.
+  4. Автоматическое обновление статуса (waiting) по событиям ядра (session/event).
+  5. Экспорт и импорт снимка доски в JSON.
+
+## Do / Don't
+- Do: Использовать только токены темы --dsw-alias-*, очищать все слушатели событий при размонтировании, соблюдать порядок хуков React.
+- Don't: Не переводить карточку в done агентом (колонка done фиксируется только по факту закрытия issue и ветки).
+
+## Locked Design Decisions
+- 2026-08-20 — Карточка настроек монтируется в settings.plugin.item с резервом в settings.section.
+- 2026-08-25 — Использование дробной индексации ($O(1)$) для позиционирования карточек.
+- 2026-09-02 — Снимок доски объединён на маршруте /dsh-kanban/snapshot (GET: выгрузка, POST: загрузка).
+- 2026-09-03 — Изоляция сессий задач в git worktree ($DSH_HOME/worktrees/<repo-key>/<task-id>/ на ветке task/<id>-<slug>), регистрация воркдерева в workspaceRegistry, проверка dirtyFiles и безопасная очистка в фазе cleanup (#193).

package/lib/client.js

@@ -858,6 +858,10 @@ window.__ModuleLoader__.load({
       'field.boardToolEnabled': 'Let the agent move cards',
       'field.pushToGitea': 'Close the issue in Gitea',
       'field.webhookSecretRef': 'Webhook credential name',
+      'field.worktreeIsolation': 'Isolate tasks in git worktrees',
+      'hint.worktreeIsolation': 'Creates a separate git worktree for each task session to prevent file collisions.',
+      'field.worktreeRoot': 'Worktree root directory',
+      'hint.worktreeRoot': 'Custom folder for task worktrees. Leave empty to use $DSH_HOME/worktrees.',
       'hint.pushToGitea': 'A card reaching Done closes its issue. The board sets no labels: the stage is already visible from the branch and the pull request.',
       'hint.webhookSecretRef': 'NAME of a DSH credential holding the Gitea webhook secret. Empty leaves only polling.',
       'hint.syncIntervalSec': 'Zero turns the check off. Below fifteen seconds is raised to fifteen.',
@@ -1069,6 +1073,9 @@ window.__ModuleLoader__.load({
       'panel.startHint': 'A dedicated agent session opens for this task. Branch and worktree are created by the agent after its preflight, not here.',
       'panel.workDir': 'Working folder: {path}',
       'panel.workDirHint': 'The project root is not set in settings, so this folder is used.',
+      'panel.worktree': 'Worktree: {path}',
+      'panel.cleanupWorktree': 'Clean Worktree',
+      'panel.worktreeDirty': 'Uncommitted changes in worktree: {files}',
       'panel.priority': 'Priority',
       'panel.priorityNone': 'No priority',
       'priority.high': 'High',
@@ -1125,6 +1132,10 @@ window.__ModuleLoader__.load({
       'field.boardToolEnabled': '允许 Agent 移动卡片',
       'field.pushToGitea': '在 Gitea 中关闭 issue',
       'field.webhookSecretRef': 'Webhook 凭据名称',
+      'field.worktreeIsolation': '在 git worktree 中隔离任务',
+      'hint.worktreeIsolation': '为每个任务会话创建独立的 git worktree 以防止文件冲突。',
+      'field.worktreeRoot': 'Worktree 根目录',
+      'hint.worktreeRoot': '任务 worktree 的自定义目录。留空则使用 $DSH_HOME/worktrees。',
       'hint.pushToGitea': '卡片进入「已完成」即关闭其 issue。看板不设置任何标签：阶段从分支和 pull request 上已经看得出来。',
       'hint.webhookSecretRef': '保存 Gitea webhook 密钥的 DSH 凭据的名称。留空则只剩轮询。',
       'hint.syncIntervalSec': '填 0 关闭核对。小于十五秒会被提到十五秒。',
@@ -1336,6 +1347,9 @@ window.__ModuleLoader__.load({
       'panel.startHint': '会为该任务打开一个专属的 Agent 会话。分支和 worktree 由 Agent 在自检之后创建，不在这里。',
       'panel.workDir': '工作目录：{path}',
       'panel.workDirHint': '设置中未指定项目根目录，因此使用此目录。',
+      'panel.worktree': '工作区：{path}',
+      'panel.cleanupWorktree': '清理工作区',
+      'panel.worktreeDirty': '工作区中存在未提交的更改：{files}',
       'panel.priority': '优先级',
       'panel.priorityNone': '无优先级',
       'priority.high': '高',
@@ -1395,6 +1409,8 @@ window.__ModuleLoader__.load({
       { field: 'boardToolEnabled', kind: 'bool', group: 'sync' },
       { field: 'pushToGitea', kind: 'bool', group: 'sync' },
       { field: 'webhookSecretRef', kind: 'text', group: 'sync' },
+      { field: 'worktreeIsolation', kind: 'bool', group: 'general' },
+      { field: 'worktreeRoot', kind: 'text', group: 'general' },
     ]
 
     function hintKey(spec) {
@@ -2507,6 +2523,11 @@ window.__ModuleLoader__.load({
                 target: '_blank', rel: 'noreferrer noopener',
               }, ' · ' + t('panel.issue') + ' ↗')
               : null),
+          openTask.worktree
+            ? React.createElement('div', { className: 'dkb-note', style: { wordBreak: 'break-all' } },
+              t('panel.worktree', { path: openTask.worktree })
+              + (openTask.branch ? ' (' + openTask.branch + ')' : ''))
+            : null,
           // Пустое тело — отсутствие раздела, а не пустой раздел с заголовком.
           body === null
             ? React.createElement('p', { className: 'dkb-note' }, t('panel.bodyLoading'))
@@ -2717,7 +2738,24 @@ window.__ModuleLoader__.load({
                 },
               }, t('panel.archive'))
               : null,
-          
+            openTask.column === 'cleanup' && openTask.worktree
+              ? React.createElement('button', {
+                type: 'button', className: 'dkb-discard',
+                onClick: async () => {
+                  try {
+                    const out = await api('/task/' + encodeURIComponent(openTask.id) + '/cleanup-worktree', {
+                      method: 'POST', body: '{}',
+                    })
+                    if (out && out.error === 'worktree-dirty') {
+                      alert(t('panel.worktreeDirty', { files: (out.files || []).join(', ') }))
+                    } else {
+                      setOpenTask(null)
+                      await load(board)
+                    }
+                  } catch (e) { setError(t(e.key || 'error.unknown')) }
+                },
+              }, t('panel.cleanupWorktree'))
+              : null,
             ),
             React.createElement('button', {
               type: 'button', className: 'dkb-save', disabled: starting || model === '',

package/lib/config.js

@@ -71,6 +71,8 @@ export const CONFIG_DEFAULTS = {
   boardToolEnabled: false,
   webhookSecretRef: '',
   pushToGitea: true,
+  worktreeIsolation: true,
+  worktreeRoot: '',
 }
 
 /** Пояснения к полям; повторно используются схемой и карточкой настроек. */
@@ -91,6 +93,8 @@ export const CONFIG_HINTS = {
   boardToolEnabled: 'Разрешить агенту двигать карточки инструментом board_move. Выключено, пока скилл воркфлоу запрещает CLI трогать канбан.',
   webhookSecretRef: 'ИМЯ учётной записи DSH с секретом вебхука Gitea. Пусто — вебхук не принимается, остаётся только опрос.',
   pushToGitea: 'Закрывать issue в Gitea, когда карточка уходит в колонку «Выполнено».',
+  worktreeIsolation: 'Изолировать сессии задач в отдельные git worktrees для предотвращения коллизий.',
+  worktreeRoot: 'Каталог для воркдеревьев задач. Пусто — $DSH_HOME/worktrees или .worktrees проекта.',
 }
 
 /** Поле настроек с пределом числа карточек; задан не у всех колонок. */

package/lib/index.js

@@ -29,6 +29,7 @@ import {
   runTask, resolveModel, buildStartMessage,
   runBatch, queueTask, unqueueTask, liveSessions,
 } from './launcher.js'
+import { cleanupTaskWorktree, checkWorktreeDirty } from './worktree.js'
 import { dispatchMove, MOVE_DETAIL, stopWork, STOP_DETAIL } from './commands.js'
 import { createGiteaClient } from './gitea.js'
 import { syncAll, createSyncState, intakeAll, archiveOverdue } from './sync.js'
@@ -661,6 +662,7 @@ export function apply(ctx, config) {
             agentPreset: typeof input.agentPreset === 'string' ? input.agentPreset : undefined,
             permission: typeof input.permission === 'string' ? input.permission : undefined,
             permissions: ctx.get('permissionPresets'),
+            workspaceRegistry: ctx.get('workspaceRegistry'),
             claimAs: await whoAmI(),
           }))
         } catch (error) {
@@ -698,10 +700,42 @@ export function apply(ctx, config) {
           if (out?.task !== undefined) {
             queueOutbound(id, out.task.column)
             if (acted !== undefined) out.command = acted
+            if (input.column === 'cleanup' && was?.worktree) {
+              const dirty = await checkWorktreeDirty({ worktreePath: was.worktree })
+              if (dirty.dirty) {
+                out.worktreeWarning = 'worktree-dirty'
+                out.dirtyFiles = dirty.files
+              }
+            }
           }
           reply(res, out)
           return
         }
+        if (req.method === 'POST' && action === 'cleanup-worktree') {
+          const task = store.getTask(id)
+          if (task === undefined) { writeJson(res, 404, { error: 'task-not-found' }); return }
+          const out = await cleanupTaskWorktree({
+            store,
+            task,
+            workspaceRegistry: ctx.get('workspaceRegistry'),
+            force: input?.force === true,
+          })
+          reply(res, out)
+          return
+        }
+        if (req.method === 'GET' && action === 'worktree-status') {
+          const task = store.getTask(id)
+          if (task === undefined) { writeJson(res, 404, { error: 'task-not-found' }); return }
+          const dirtyCheck = await checkWorktreeDirty({ worktreePath: task.worktree })
+          reply(res, {
+            worktree: task.worktree || '',
+            branch: task.branch || '',
+            workspaceId: task.workspaceId || '',
+            dirty: dirtyCheck.dirty,
+            files: dirtyCheck.files,
+          })
+          return
+        }
         if (req.method === 'POST' && action === 'stop') {
           const task = store.getTask(id)
           if (task === undefined) { writeJson(res, 404, { error: 'task-not-found' }); return }

package/lib/launcher.js

@@ -12,7 +12,8 @@
 // Пакеты ядра здесь не импортируются: идентификатор сессии и сборка сообщения
 // приходят параметрами. Так модуль проверяется без харнесса и без сети.
 
-import { isAbsolute, join, resolve } from 'node:path'
+import { isAbsolute, join, resolve, sep } from 'node:path'
+import { createTaskWorktree, registerDshWorkspace } from './worktree.js'
 
 /**
  * Хвост своей задачи — УСЛОВИЕ, а не приказ.
@@ -110,7 +111,8 @@ export function resolveCwd(task, config, cwdOf = () => process.cwd()) {
 
   const target = resolve(join(root, repo))
   const fence = resolve(root)
-  if (target !== fence && !target.startsWith(fence.endsWith('/') ? fence : fence + '/')) {
+  const fenceSep = fence.endsWith(sep) || fence.endsWith('/') ? fence : fence + sep
+  if (target !== fence && !target.startsWith(fenceSep) && !target.startsWith(fence.endsWith('/') ? fence : fence + '/')) {
     throw new Error('имя репозитория выводит за пределы корня проектов')
   }
   return target
@@ -145,7 +147,7 @@ export function applyPermission({ permissions, agent, name }) {
 
 export async function obtainAgent({
   agents, task, config, provider, model, mintSessionId, cwdOf, logger,
-  agentPreset, permission, permissions,
+  agentPreset, permission, permissions, gitRunner, workspaceRegistry,
 }) {
   const known = typeof task?.sessionId === 'string' && task.sessionId !== '' ? task.sessionId : undefined
 
@@ -164,12 +166,51 @@ export async function obtainAgent({
     }
   }
 
-  const cwd = resolveCwd(task, config, cwdOf)
+  let cwd = resolveCwd(task, config, cwdOf)
+  let worktreePath = task?.worktree || undefined
+  let branchName = task?.branch || undefined
+  let workspaceId = task?.workspaceId || undefined
+  let worktreeCreated = false
+
+  if (config?.worktreeIsolation !== false && task?.repo) {
+    try {
+      const created = await createTaskWorktree({
+        task,
+        repoDir: cwd,
+        config,
+        gitRunner,
+        cwdOf,
+      })
+      if (created) {
+        worktreePath = created.worktreePath
+        branchName = created.branchName
+        worktreeCreated = created.created === true
+        cwd = created.worktreePath
+
+        if (workspaceRegistry) {
+          workspaceId = await registerDshWorkspace({
+            workspaceRegistry,
+            worktreePath,
+            title: `${task.owner ? task.owner + '/' : ''}${task.repo}#${task.issueNumber || task.id.slice(0, 8)}: ${task.title}`,
+          })
+        }
+      }
+    } catch (err) {
+      logger?.warn?.(`dsh-kanban: не удалось создать worktree для ${task.id}: ${err.message}`)
+    }
+  } else if (worktreePath) {
+    cwd = worktreePath
+  }
+
+  const meta = { cwd }
+  if (typeof agentPreset === 'string' && agentPreset !== '') meta.agentPreset = agentPreset
+  if (workspaceId) meta.workspaceId = workspaceId
+
   const handle = await agents.create({
     sessionId: mintSessionId(),
     // Профиль — факт создания сессии: у идущей его не сменить, поэтому он
     // едет здесь, а не отдельным вызовом после.
-    meta: typeof agentPreset === 'string' && agentPreset !== '' ? { cwd, agentPreset } : { cwd },
+    meta,
     agentOptions: { provider, model },
   })
   const access = applyPermission({ permissions, agent: handle.agent, name: permission })
@@ -182,7 +223,15 @@ export async function obtainAgent({
     error.status = 409
     throw error
   }
-  return { agent: handle.agent, sessionId: handle.agent.session.id, mode: 'created' }
+  return {
+    agent: handle.agent,
+    sessionId: handle.agent.session.id,
+    mode: 'created',
+    worktree: worktreePath,
+    branch: branchName,
+    workspaceId,
+    worktreeCreated,
+  }
 }
 
 /**
@@ -240,10 +289,11 @@ export async function runTask({
   agents, store, task, config, provider, model,
   mintSessionId, createMessage, cwdOf, logger, text,
   agentPreset, permission, permissions, claimAs,
+  gitRunner, workspaceRegistry,
 }) {
   const taken = await obtainAgent({
     agents, task, config, provider, model, mintSessionId, cwdOf, logger,
-    agentPreset, permission, permissions,
+    agentPreset, permission, permissions, gitRunner, workspaceRegistry,
   })
 
   await taken.agent.whenIdle()
@@ -255,12 +305,30 @@ export async function runTask({
   }))
 
   const before = store.getTask(task.id)
-  const patch = { sessionId: taken.sessionId, provider, model }
+  const patch = {
+    sessionId: taken.sessionId,
+    provider,
+    model,
+    ...(taken.worktree ? { worktree: taken.worktree } : {}),
+    ...(taken.branch ? { branch: taken.branch } : {}),
+    ...(taken.workspaceId ? { workspaceId: taken.workspaceId } : {}),
+  }
   store.updateTask(task.id, patch)
   // Запустил — значит отвечаешь: свободная задача становится твоей, чужая
   // остаётся чужой.
   claimOnStart({ store, task: before, login: claimAs })
 
+  // Изоляция сессии в отдельном воркдереве фиксируется в журнале.
+  if (taken.worktreeCreated) {
+    store.addTransition({
+      taskId: task.id,
+      fromCol: before.column,
+      toCol: before.column,
+      source: 'session',
+      detail: `изоляция: создано воркдерево ${taken.worktree} (${taken.branch})`,
+    })
+  }
+
   // Подмена чата не должна быть молчаливой: человек вернётся к задаче и не
   // поймёт, куда делась переписка.
   if (taken.mode === 'created' && before.sessionId) {

package/lib/store.js

@@ -40,6 +40,7 @@ CREATE TABLE IF NOT EXISTS tasks (
   labels       TEXT NOT NULL DEFAULT '[]',
   branch       TEXT,
   worktree     TEXT,
+  workspaceId  TEXT NOT NULL DEFAULT '',
   sessionId    TEXT,
   model        TEXT,
   provider     TEXT,
@@ -82,7 +83,7 @@ CREATE TABLE IF NOT EXISTS dismissed (
 /** Поля задачи, которые разрешено править через updateTask. */
 const WRITABLE = [
   'title', 'body', 'owner', 'repo', 'issueNumber', 'issueUrl', 'labels',
-  'branch', 'worktree', 'sessionId', 'model', 'provider', 'waiting', 'syncedAt', 'plan',
+  'branch', 'worktree', 'workspaceId', 'sessionId', 'model', 'provider', 'waiting', 'syncedAt', 'plan',
   'labelColors', 'queuedAt', 'createdAt', 'author', 'assignee', 'milestone', 'priority', 'dueAt',
 ]
 
@@ -132,6 +133,7 @@ export function openStore({ dir }) {
     ['milestone', "TEXT NOT NULL DEFAULT ''"],
     ['priority', "TEXT NOT NULL DEFAULT ''"],
     ['dueAt', 'INTEGER NOT NULL DEFAULT 0'],
+    ['workspaceId', "TEXT NOT NULL DEFAULT ''"],
   ]) {
     try { db.exec(`ALTER TABLE tasks ADD COLUMN ${column} ${definition}`) } catch { /* столбец уже есть */ }
   }
@@ -260,15 +262,15 @@ export function openStore({ dir }) {
       const position = positionFor(board, column, input.beforeId, input.afterId)
       db.prepare(`INSERT INTO tasks
         (id, board, col, position, title, body, owner, repo, issueNumber, issueUrl,
-         labels, branch, worktree, sessionId, model, provider, waiting, syncedAt,
+         labels, branch, worktree, workspaceId, sessionId, model, provider, waiting, syncedAt,
          labelColors, author, assignee, milestone, priority, dueAt, columnAt, createdAt, updatedAt)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
         id, board, column, position,
         input.title ?? '', input.body ?? '',
         input.owner ?? null, input.repo ?? null,
         input.issueNumber ?? null, input.issueUrl ?? null,
         JSON.stringify(input.labels ?? []),
-        input.branch ?? null, input.worktree ?? null,
+        input.branch ?? null, input.worktree ?? null, input.workspaceId ?? '',
         input.sessionId ?? null, input.model ?? null, input.provider ?? null,
         input.waiting ? 1 : 0,
         Number(input.syncedAt) || 0,

package/lib/worktree.js

@@ -0,0 +1,339 @@
+// Управляемые воркдеревья для сессий агентов под задачи (Issue #193).
+//
+// Изоляция сессии агента в отдельном git worktree защищает основной
+// репозиторий от параллельных правок нескольких задач, предотвращает
+// перезапись веток и фиксирует рабочее окружение карточки.
+//
+// Жизненный цикл:
+// 1. При переходе в In Progress создаётся воркдерево task/<id>-<slug>
+// 2. Воркдерево регистрируется в DSH workspaceRegistry как рабочий каталог
+// 3. Сессия агента запускается с cwd = worktreePath
+// 4. В колонке Cleanup проверяются незакоммиченные файлы (dirtyFiles)
+// 5. После подтверждения воркдерево удаляется, воркспейс дерегистрируется.
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { existsSync } from 'node:fs'
+import { isAbsolute, join, resolve, sep } from 'node:path'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * Стандартный исполнитель git-команд.
+ * Принимает аргументы массивом, исключая шелл-инъекции.
+ */
+export async function defaultGitRunner(args, cwd) {
+  try {
+    const { stdout, stderr } = await execFileAsync('git', args, {
+      cwd,
+      maxBuffer: 10 * 1024 * 1024,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    })
+    return { stdout: stdout.trim(), stderr: stderr.trim(), code: 0 }
+  } catch (err) {
+    const error = new Error(`git ${args.join(' ')} failed: ${err.stderr || err.message}`)
+    error.code = err.code || 1
+    error.stdout = err.stdout ? String(err.stdout).trim() : ''
+    error.stderr = err.stderr ? String(err.stderr).trim() : ''
+    throw error
+  }
+}
+
+/**
+ * Преобразовать строку в безопасный фрагмент имени ветки или каталога.
+ */
+export function slugify(text) {
+  if (typeof text !== 'string') return 'task'
+  const slug = text
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-z0-9а-яё_-]+/gi, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40)
+  return slug || 'task'
+}
+
+/**
+ * Безопасный ключ репозитория для каталога воркдеревьев.
+ */
+export function safeRepoKey(task) {
+  const owner = typeof task?.owner === 'string' ? task.owner.trim() : ''
+  const repo = typeof task?.repo === 'string' ? task.repo.trim() : ''
+  if (owner && repo) return `${owner}_${repo}`
+  if (repo) return repo
+  return 'local'
+}
+
+/**
+ * Определить корневой каталог для всех управляемых воркдеревьев.
+ */
+export function resolveWorktreeRoot(config, env = process.env, cwdOf = () => process.cwd()) {
+  const custom = typeof config?.worktreeRoot === 'string' ? config.worktreeRoot.trim() : ''
+  if (custom !== '') {
+    return isAbsolute(custom) ? resolve(custom) : resolve(join(cwdOf(), custom))
+  }
+  if (typeof env?.DSH_HOME === 'string' && env.DSH_HOME.trim() !== '') {
+    return resolve(join(env.DSH_HOME.trim(), 'worktrees'))
+  }
+  const projectRoot = typeof config?.defaultProjectRoot === 'string' && config.defaultProjectRoot.trim() !== ''
+    ? config.defaultProjectRoot.trim()
+    : cwdOf()
+  return resolve(join(projectRoot, '.worktrees'))
+}
+
+/**
+ * Вычислить канонический путь к воркдереву задачи с защитой от path traversal.
+ */
+export function resolveTaskWorktreePath({ task, config, env, cwdOf }) {
+  const root = resolveWorktreeRoot(config, env, cwdOf)
+  const repoKey = safeRepoKey(task)
+  const taskId = typeof task?.id === 'string' && task.id.trim() !== '' ? task.id.trim() : 'task'
+  const target = resolve(join(root, repoKey, taskId))
+
+  const fenceSep = root.endsWith(sep) || root.endsWith('/') ? root : root + sep
+  if (target !== root && !target.startsWith(fenceSep) && !target.startsWith(root + '/')) {
+    throw new Error('путь воркдерева выходит за пределы корня воркдеревьев')
+  }
+  return target
+}
+
+/**
+ * Сформировать имя ветки задачи.
+ */
+export function resolveTaskBranch(task) {
+  const prefix = typeof task?.issueNumber === 'number'
+    ? String(task.issueNumber)
+    : (typeof task?.id === 'string' ? task.id.slice(0, 8) : 'task')
+  const slug = slugify(task?.title || '')
+  return `task/${prefix}-${slug}`
+}
+
+/**
+ * Проверить, является ли каталог git-репозиторием.
+ */
+export async function isGitRepo(repoDir, gitRunner = defaultGitRunner) {
+  if (!repoDir) return false
+  try {
+    const res = await gitRunner(['rev-parse', '--is-inside-work-tree'], repoDir)
+    return res.stdout === 'true'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Получить список существующих путей воркдеревьев для репозитория.
+ */
+export async function listWorktrees(repoDir, gitRunner = defaultGitRunner) {
+  try {
+    const res = await gitRunner(['worktree', 'list', '--porcelain'], repoDir)
+    const paths = []
+    for (const line of res.stdout.split('\n')) {
+      if (line.startsWith('worktree ')) {
+        paths.push(resolve(line.slice(9).trim()))
+      }
+    }
+    return paths
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Определить базовую ветку для создания воркдерева.
+ */
+export async function determineBaseRef(repoDir, gitRunner = defaultGitRunner) {
+  for (const candidate of ['origin/main', 'origin/master', 'main', 'master', 'HEAD']) {
+    try {
+      await gitRunner(['rev-parse', '--verify', '--quiet', candidate], repoDir)
+      return candidate
+    } catch {
+      continue
+    }
+  }
+  return 'HEAD'
+}
+
+/**
+ * Создать или переиспользовать воркдерево под задачу.
+ */
+export async function createTaskWorktree({
+  task,
+  repoDir,
+  config,
+  gitRunner = defaultGitRunner,
+  env,
+  cwdOf,
+}) {
+  if (!repoDir) return undefined
+  const isGit = await isGitRepo(repoDir, gitRunner)
+  if (!isGit) return undefined
+
+  const worktreePath = resolveTaskWorktreePath({ task, config, env, cwdOf })
+  const branchName = resolveTaskBranch(task)
+
+  // Проверяем, не зарегистрировано ли уже это воркдерево
+  const existing = await listWorktrees(repoDir, gitRunner)
+  if (existing.includes(resolve(worktreePath))) {
+    return { worktreePath, branchName, reused: true }
+  }
+
+  // Проверяем, существует ли уже локальная ветка с таким именем
+  let branchExists = false
+  try {
+    await gitRunner(['rev-parse', '--verify', '--quiet', `refs/heads/${branchName}`], repoDir)
+    branchExists = true
+  } catch {
+    branchExists = false
+  }
+
+  if (branchExists) {
+    await gitRunner(['worktree', 'add', worktreePath, branchName], repoDir)
+  } else {
+    const baseRef = await determineBaseRef(repoDir, gitRunner)
+    await gitRunner(['worktree', 'add', '-b', branchName, worktreePath, baseRef], repoDir)
+  }
+
+  return { worktreePath, branchName, created: true }
+}
+
+/**
+ * Проверить наличие незакоммиченных изменений в воркдереве.
+ */
+export async function checkWorktreeDirty({ worktreePath, gitRunner = defaultGitRunner }) {
+  if (!worktreePath || !existsSync(worktreePath)) {
+    return { dirty: false, files: [] }
+  }
+  try {
+    const res = await gitRunner(['status', '--porcelain'], worktreePath)
+    const files = res.stdout.split('\n').map((l) => l.trim()).filter((l) => l.length > 0)
+    return { dirty: files.length > 0, files }
+  } catch (error) {
+    return { dirty: false, files: [], error: String(error?.message ?? error) }
+  }
+}
+
+/**
+ * Безопасно удалить воркдерево задачи.
+ */
+export async function removeTaskWorktree({
+  repoDir,
+  worktreePath,
+  branchName,
+  force = false,
+  deleteBranch = true,
+  gitRunner = defaultGitRunner,
+}) {
+  if (!worktreePath || !existsSync(worktreePath)) {
+    return { removed: false, reason: 'not-found' }
+  }
+
+  const dirtyCheck = await checkWorktreeDirty({ worktreePath, gitRunner })
+  if (dirtyCheck.dirty && !force) {
+    return {
+      removed: false,
+      error: 'worktree-dirty',
+      files: dirtyCheck.files,
+    }
+  }
+
+  const removeArgs = force
+    ? ['worktree', 'remove', '--force', worktreePath]
+    : ['worktree', 'remove', worktreePath]
+
+  await gitRunner(removeArgs, repoDir)
+  try { await gitRunner(['worktree', 'prune'], repoDir) } catch { /* prune игнорирует ошибки */ }
+
+  let branchDeleted = false
+  if (deleteBranch && branchName && repoDir) {
+    try {
+      await gitRunner(['branch', '-d', branchName], repoDir)
+      branchDeleted = true
+    } catch {
+      // Игнорируем: ветка не удалена, если ещё не влита
+      branchDeleted = false
+    }
+  }
+
+  return { removed: true, branchDeleted }
+}
+
+/**
+ * Зарегистрировать каталог воркдерева в DSH workspaceRegistry.
+ */
+export async function registerDshWorkspace({ workspaceRegistry, worktreePath, title }) {
+  if (!workspaceRegistry || typeof workspaceRegistry.create !== 'function') return undefined
+  try {
+    const entity = await workspaceRegistry.create(worktreePath, title || 'Task Workspace')
+    return entity?.id
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Дерегистрировать воркспейс из DSH workspaceRegistry.
+ */
+export async function deregisterDshWorkspace({ workspaceRegistry, workspaceId }) {
+  if (!workspaceRegistry || typeof workspaceRegistry.delete !== 'function' || !workspaceId) return false
+  try {
+    return (await workspaceRegistry.delete(workspaceId)) === true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Выполнить очистку воркдерева задачи с проверкой незакоммиченных изменений.
+ */
+export async function cleanupTaskWorktree({
+  store,
+  task,
+  repoDir,
+  workspaceRegistry,
+  force = false,
+  deleteBranch = true,
+  gitRunner = defaultGitRunner,
+}) {
+  const current = typeof task === 'object' && task !== null ? task : store?.getTask?.(task)
+  if (!current) return { error: 'task-not-found', status: 404 }
+  if (!current.worktree) return { noop: true, removed: false }
+
+  const targetRepoDir = repoDir || current.worktree
+  const result = await removeTaskWorktree({
+    repoDir: targetRepoDir,
+    worktreePath: current.worktree,
+    branchName: current.branch,
+    force,
+    deleteBranch,
+    gitRunner,
+  })
+
+  if (result.error === 'worktree-dirty') {
+    store?.addTransition?.({
+      taskId: current.id,
+      fromCol: current.column,
+      toCol: current.column,
+      source: 'session',
+      detail: `очистка отложена: обнаружены незакоммиченные файлы: ${result.files.slice(0, 3).join(', ')}`,
+    })
+    return { error: 'worktree-dirty', files: result.files }
+  }
+
+  if (workspaceRegistry && current.workspaceId) {
+    await deregisterDshWorkspace({ workspaceRegistry, workspaceId: current.workspaceId })
+  }
+
+  store?.updateTask?.(current.id, { worktree: '', workspaceId: '' })
+  store?.addTransition?.({
+    taskId: current.id,
+    fromCol: current.column,
+    toCol: current.column,
+    source: 'session',
+    detail: 'очистка: воркдерево удалено' + (result.branchDeleted ? ', ветка удалена' : ''),
+  })
+
+  return { success: true, removed: true, branchDeleted: result.branchDeleted }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-kanban",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Visual Kanban board for DeepSeek Harness: Gitea-backed tasks, workflow columns, and a dedicated agent session per task.",
   "type": "module",
   "main": "lib/index.js",