@goodandready/dsh-kanban 0.1.24 → 0.1.26

package/lib/progress-dump.js

@@ -0,0 +1,134 @@
+// dsh-kanban: фиксация и безопасная передача среза прогресса задачи (PROGRESSDUMP).
+// Парсит блок <<<PROGRESSDUMP ... >>>PROGRESSDUMP, маскирует секреты и генерирует вводный бриф.
+
+export const BEGIN_MARKER = '<<<PROGRESSDUMP'
+export const END_MARKER = '>>>PROGRESSDUMP'
+export const FIELD_BYTE_LIMIT = 8 * 1024
+export const REDACTED = '[REDACTED]'
+
+const SENSITIVE_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /Bearer\s+[A-Za-z0-9._~+\/=:-]{8,}/gi,
+  /sk-[A-Za-z0-9_-]{8,}/g,
+  /ghp_[A-Za-z0-9]{20,}/g,
+  /glpat-[A-Za-z0-9_-]{15,}/g,
+  /xox[bpars]-[A-Za-z0-9-]{10,}/g,
+]
+
+function sanitizeText(raw) {
+  let text = raw
+  let redacted = false
+  for (const pattern of SENSITIVE_PATTERNS) {
+    if (pattern.test(text)) {
+      redacted = true
+      text = text.replace(pattern, REDACTED)
+    }
+  }
+  // Блокируем внедрение слэш-команд харнесса
+  text = text.split('\n')
+    .map((line) => (line.trim().startsWith('/') ? ('# ' + line) : line))
+    .join('\n')
+
+  return { text, redacted }
+}
+
+function truncateBytes(str, maxBytes) {
+  const buf = Buffer.from(str, 'utf8')
+  if (buf.length <= maxBytes) return str
+  return buf.subarray(0, maxBytes).toString('utf8')
+}
+
+/**
+ * Разобрать блок PROGRESSDUMP из произвольного текста.
+ * @param {string} text 
+ * @returns {{ ok: true, dump: { goal: string, progress: string, next: string, redacted: boolean } } | { ok: false, error: string }}
+ */
+export function parseProgressDump(text) {
+  if (typeof text !== 'string') return { ok: false, error: 'text-required' }
+
+  const startIdx = text.indexOf(BEGIN_MARKER)
+  const endIdx = text.indexOf(END_MARKER)
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+    return { ok: false, error: 'markers-not-found' }
+  }
+
+  const inner = text.slice(startIdx + BEGIN_MARKER.length, endIdx).trim()
+  const lines = inner.split('\n')
+
+  let currentKey = null
+  const sections = { goal: [], progress: [], next: [] }
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim()
+    const lower = line.toLowerCase()
+
+    if (lower.startsWith('цель:') || lower.startsWith('goal:')) {
+      currentKey = 'goal'
+      const val = line.slice(line.indexOf(':') + 1).trim()
+      if (val) sections.goal.push(val)
+    } else if (lower.startsWith('прогресс:') || lower.startsWith('progress:')) {
+      currentKey = 'progress'
+      const val = line.slice(line.indexOf(':') + 1).trim()
+      if (val) sections.progress.push(val)
+    } else if (lower.startsWith('следующие шаги:') || lower.startsWith('next:') || lower.startsWith('шаги:')) {
+      currentKey = 'next'
+      const val = line.slice(line.indexOf(':') + 1).trim()
+      if (val) sections.next.push(val)
+    } else if (currentKey) {
+      sections[currentKey].push(rawLine)
+    }
+  }
+
+  let totalRedacted = false
+  const result = { goal: '', progress: '', next: '', redacted: false }
+
+  for (const key of ['goal', 'progress', 'next']) {
+    const rawVal = sections[key].join('\n').trim()
+    const { text: cleanText, redacted } = sanitizeText(rawVal)
+    if (redacted) totalRedacted = true
+    result[key] = truncateBytes(cleanText, FIELD_BYTE_LIMIT)
+  }
+
+  result.redacted = totalRedacted
+  return { ok: true, dump: result }
+}
+
+/**
+ * Сериализовать срез в канонический блок <<<PROGRESSDUMP ... >>>PROGRESSDUMP.
+ */
+export function formatProgressDump(dump) {
+  if (!dump) return ''
+  return [
+    BEGIN_MARKER,
+    'Цель:',
+    dump.goal || '—',
+    '',
+    'Прогресс:',
+    dump.progress || '—',
+    '',
+    'Следующие шаги:',
+    dump.next || '—',
+    END_MARKER,
+  ].join('\n')
+}
+
+/**
+ * Сформировать аккуратный вводный бриф для новой сессии агента.
+ */
+export function formatHandoverPreamble(dump) {
+  if (!dump || (!dump.goal && !dump.progress && !dump.next)) return ''
+  return [
+    '## 📋 Эстафета задачи (PROGRESSDUMP)',
+    '> [!NOTE]',
+    '> Предыдущий ход зафиксировал текущее состояние работы:',
+    '',
+    '**Цель:** ' + (dump.goal || '—'),
+    '',
+    '**Сделано:** ' + (dump.progress || '—'),
+    '',
+    '**Следующие шаги:** ' + (dump.next || '—'),
+    '',
+    '---',
+    '',
+  ].join('\n')
+}

package/lib/routes.js

@@ -14,6 +14,7 @@ import { columnStats, doneWithin, stale } from './metrics.js'
 import { isStale } from './time.js'
 import { facetsOf, facetsOfTask, groupByRepo, sortByLife } from './filters.js'
 import { parseBody } from './markdown.js'
+import { computeNextRun } from './cron.js'
 
 /** Больше этого тело запроса не читаем: без предела один запрос кладёт хост. */
 export const MAX_BODY_BYTES = 256 * 1024
@@ -183,7 +184,8 @@ export function createTask({ store, input }) {
 
 /** Правка полей карточки. Колонку и порядок правит только перенос. */
 export function updateTask({ store, id, input }) {
-  if (store.getTask(id) === undefined) return { error: 'task-not-found', status: 404 }
+  const current = store.getTask(id)
+  if (current === undefined) return { error: 'task-not-found', status: 404 }
   const patch = {}
   if (typeof input?.title === 'string' && input.title.trim() !== '') patch.title = input.title.trim()
   if (typeof input?.body === 'string') patch.body = input.body
@@ -197,9 +199,28 @@ export function updateTask({ store, id, input }) {
   if (typeof input?.dueAt === 'number' && Number.isFinite(input.dueAt) && input.dueAt >= 0) {
     patch.dueAt = Math.floor(input.dueAt)
   }
+  if (typeof input?.cron === 'string') {
+    patch.cron = input.cron.trim()
+    patch.nextRunAt = patch.cron ? (computeNextRun(patch.cron) || 0) : 0
+  }
+  if (typeof input?.progressDump === 'string') {
+    patch.progressDump = input.progressDump
+  }
+  if (typeof input?.permission === 'string') {
+    patch.permission = input.permission
+    if (input.permission !== current.permission) {
+      patch.permissionConfirmedAt = 0
+    }
+  }
   return { task: store.updateTask(id, patch) }
 }
 
+export function confirmPermission({ store, id }) {
+  const task = store.getTask(id)
+  if (task === undefined) return { error: 'task-not-found', status: 404 }
+  return { task: store.updateTask(id, { permissionConfirmedAt: Date.now() }) }
+}
+
 /** Известные приоритеты. Пустой — «без приоритета». */
 export const PRIORITIES = ['', 'high', 'medium', 'low']
 

package/lib/store.js

@@ -40,6 +40,14 @@ CREATE TABLE IF NOT EXISTS tasks (
   labels       TEXT NOT NULL DEFAULT '[]',
   branch       TEXT,
   worktree     TEXT,
+  workspaceId           TEXT NOT NULL DEFAULT '',
+  cron                  TEXT NOT NULL DEFAULT '',
+  nextRunAt             INTEGER NOT NULL DEFAULT 0,
+  lastRunAt             INTEGER NOT NULL DEFAULT 0,
+  progressDump          TEXT NOT NULL DEFAULT '',
+  permission            TEXT NOT NULL DEFAULT '',
+  permissionConfirmedAt INTEGER NOT NULL DEFAULT 0,
+  runs                  TEXT NOT NULL DEFAULT '[]',
   sessionId    TEXT,
   model        TEXT,
   provider     TEXT,
@@ -82,8 +90,9 @@ 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',
+  'cron', 'nextRunAt', 'lastRunAt', 'progressDump', 'permission', 'permissionConfirmedAt', 'runs',
 ]
 
 /** Источники перехода; чужое значение не пишем, чтобы журнал оставался читаемым. */
@@ -91,7 +100,7 @@ const SOURCES = new Set(['manual', 'session', 'gitea', 'tool'])
 
 function rowToTask(row) {
   if (row === undefined) return undefined
-  const { col, labels, waiting, labelColors, ...rest } = row
+  const { col, labels, waiting, labelColors, runs, ...rest } = row
   let parsed = []
   try {
     const value = JSON.parse(labels)
@@ -102,7 +111,12 @@ function rowToTask(row) {
     const value = JSON.parse(labelColors ?? '{}')
     if (value !== null && typeof value === 'object' && !Array.isArray(value)) colors = value
   } catch { /* испорченное поле не должно ронять чтение всей доски */ }
-  return { ...rest, column: col, labels: parsed, labelColors: colors, waiting: waiting === 1 }
+  let parsedRuns = []
+  try {
+    const value = JSON.parse(runs ?? '[]')
+    if (Array.isArray(value)) parsedRuns = value
+  } catch { /* испорченное поле не должно ронять чтение всей доски */ }
+  return { ...rest, column: col, labels: parsed, labelColors: colors, waiting: waiting === 1, runs: parsedRuns }
 }
 
 /**
@@ -132,6 +146,14 @@ 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 ''"],
+    ['cron', "TEXT NOT NULL DEFAULT ''"],
+    ['nextRunAt', 'INTEGER NOT NULL DEFAULT 0'],
+    ['lastRunAt', 'INTEGER NOT NULL DEFAULT 0'],
+    ['progressDump', "TEXT NOT NULL DEFAULT ''"],
+    ['permission', "TEXT NOT NULL DEFAULT ''"],
+    ['permissionConfirmedAt', 'INTEGER NOT NULL DEFAULT 0'],
+    ['runs', "TEXT NOT NULL DEFAULT '[]'"],
   ]) {
     try { db.exec(`ALTER TABLE tasks ADD COLUMN ${column} ${definition}`) } catch { /* столбец уже есть */ }
   }
@@ -163,6 +185,8 @@ export function openStore({ dir }) {
     countInColumn: db.prepare('SELECT COUNT(*) AS n FROM tasks WHERE board = ? AND col = ?'),
     watchable: db.prepare(
       "SELECT * FROM tasks WHERE issueNumber IS NOT NULL AND col NOT IN ('done') ORDER BY updatedAt DESC"),
+    scheduledDue: db.prepare(
+      "SELECT * FROM tasks WHERE cron != '' AND nextRunAt > 0 AND nextRunAt <= ? AND archivedAt = 0 ORDER BY nextRunAt ASC"),
   }
 
   function ensureBoard(id, title, kind) {
@@ -260,15 +284,16 @@ 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,
-         labelColors, author, assignee, milestone, priority, dueAt, columnAt, createdAt, updatedAt)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+         labels, branch, worktree, workspaceId, sessionId, model, provider, waiting, syncedAt,
+         labelColors, author, assignee, milestone, priority, dueAt, columnAt, createdAt, updatedAt,
+         cron, nextRunAt, lastRunAt, progressDump, permission, permissionConfirmedAt, runs)
+        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,
@@ -279,6 +304,13 @@ export function openStore({ dir }) {
         input.priority ?? '',
         Number(input.dueAt) || 0,
         now, born, now,
+        input.cron ?? '',
+        Number(input.nextRunAt) || 0,
+        Number(input.lastRunAt) || 0,
+        input.progressDump ?? '',
+        input.permission ?? '',
+        Number(input.permissionConfirmedAt) || 0,
+        typeof input.runs === 'string' ? input.runs : JSON.stringify(input.runs ?? []),
       )
       return rowToTask(q.taskById.get(id))
     },
@@ -293,6 +325,7 @@ export function openStore({ dir }) {
         fields.push(`${key} = ?`)
         if (key === 'labels') values.push(JSON.stringify(patch[key] ?? []))
         else if (key === 'labelColors') values.push(JSON.stringify(patch[key] ?? {}))
+        else if (key === 'runs') values.push(typeof patch[key] === 'string' ? patch[key] : JSON.stringify(patch[key] ?? []))
         else if (key === 'waiting') values.push(patch[key] ? 1 : 0)
         else if (key === 'syncedAt') values.push(Number(patch[key]) || 0)
         else values.push(patch[key] ?? null)
@@ -304,6 +337,31 @@ export function openStore({ dir }) {
       return rowToTask(q.taskById.get(id))
     },
 
+    listDueTasks(now = Date.now()) {
+      return q.scheduledDue.all(now).map(rowToTask)
+    },
+
+    recordTaskRun(id, run) {
+      const task = rowToTask(q.taskById.get(id))
+      if (!task) return undefined
+      const runs = Array.isArray(task.runs) ? [...task.runs] : []
+      runs.unshift(run)
+      const trimmed = runs.slice(0, 20)
+      this.updateTask(id, { runs: JSON.stringify(trimmed) })
+      return rowToTask(q.taskById.get(id))
+    },
+
+    updateTaskRun(id, runId, patch) {
+      const task = rowToTask(q.taskById.get(id))
+      if (!task) return undefined
+      const runs = Array.isArray(task.runs) ? [...task.runs] : []
+      const idx = runs.findIndex((r) => r.id === runId)
+      if (idx === -1) return undefined
+      runs[idx] = { ...runs[idx], ...patch }
+      this.updateTask(id, { runs: JSON.stringify(runs) })
+      return rowToTask(q.taskById.get(id))
+    },
+
     moveTask(id, { column, beforeId, afterId }) {
       const current = q.taskById.get(id)
       if (current === undefined) throw new Error(`задача ${id} не найдена`)

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.24",
+  "version": "0.1.26",
   "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",