@goodandready/dsh-kanban 0.2.35 → 0.2.36

package/lib/config.js

@@ -94,6 +94,8 @@ export const CONFIG_DEFAULTS = {
   watchdogEnabled: true,
   watchdogStallTimeoutMin: 15,
   watchdogMaxConsecutiveErrors: 5,
+  timeMachineEnabled: true,
+  timeMachineAutoSnapshot: true,
 }
 
 /** Field descriptions reused in schema and settings card. */
@@ -147,6 +149,8 @@ export const CONFIG_HINTS = {
   watchdogEnabled: 'Enable background watchdog timer and circuit breaker for stalled agent tasks.',
   watchdogStallTimeoutMin: 'Minutes of inactivity before active task is marked stalled by watchdog (default: 15).',
   watchdogMaxConsecutiveErrors: 'Number of consecutive execution errors before tripping circuit breaker (default: 5).',
+  timeMachineEnabled: 'Enable integration with @goodandready/dsh-time-machine for task checkpoints and rollback.',
+  timeMachineAutoSnapshot: 'Automatically create inception snapshot when task transitions to in-progress.',
 }
 
 /** Setting key for column WIP limit; not all columns have limits. */

package/lib/dependencies.js

@@ -0,0 +1,175 @@
+// Directed Acyclic Graph (DAG) task dependency validation and auto-unblocking logic.
+// Enforces that tasks with unresolved blockers cannot transition to in-progress.
+// Cycle detection prevents circular dependencies (e.g. A -> B -> A).
+
+/**
+ * Check if targetId is reachable from startId following blockedBy links.
+ *
+ * @param {string} startId starting task identifier
+ * @param {string} targetId target task identifier
+ * @param {Function|object} getTaskFn task getter function or store
+ * @param {Set<string>} [visited] visited set to break cycles during traversal
+ * @returns {boolean} true if targetId is reachable
+ */
+function canReach(startId, targetId, getTaskFn, visited = new Set()) {
+  if (startId === targetId) return true
+  if (visited.has(startId)) return false
+  visited.add(startId)
+
+  const task = typeof getTaskFn === 'function' ? getTaskFn(startId) : getTaskFn?.getTask?.(startId)
+  if (!task) return false
+
+  const blockers = Array.isArray(task.blockedBy) ? task.blockedBy : []
+  for (const nextId of blockers) {
+    if (typeof nextId === 'string' && nextId.trim() !== '') {
+      if (canReach(nextId, targetId, getTaskFn, visited)) return true
+    }
+  }
+  return false
+}
+
+/**
+ * Validate proposed dependencies for a task against cycles and self-references.
+ *
+ * @param {string} taskId task identifier
+ * @param {string[]} newBlockedBy proposed array of blocking task IDs
+ * @param {Function|object} getTaskFn task getter function or store
+ * @returns {{valid: boolean, error?: string}}
+ */
+export function validateDependencies(taskId, newBlockedBy, getTaskFn) {
+  if (!Array.isArray(newBlockedBy)) {
+    return { valid: true }
+  }
+
+  // 1. Check self-dependency
+  if (newBlockedBy.includes(taskId)) {
+    return {
+      valid: false,
+      error: `Self-dependency: task "${taskId}" cannot depend on itself.`,
+    }
+  }
+
+  // 2. Check for circular dependency
+  for (const blockerId of newBlockedBy) {
+    if (typeof blockerId !== 'string' || blockerId.trim() === '') continue
+    if (canReach(blockerId, taskId, getTaskFn)) {
+      return {
+        valid: false,
+        error: `Circular dependency detected: task "${blockerId}" already depends on "${taskId}".`,
+      }
+    }
+  }
+
+  return { valid: true }
+}
+
+/**
+ * Compute reverse mapping (blocks) from blockedBy relations across tasks.
+ *
+ * @param {Array<object>} tasks list of all tasks
+ * @returns {Record<string, string[]>} mapping of taskId to list of tasks it blocks
+ */
+export function computeBlocksMap(tasks) {
+  const blocks = {}
+  if (!Array.isArray(tasks)) return blocks
+
+  for (const task of tasks) {
+    if (task && typeof task.id === 'string') {
+      blocks[task.id] = []
+    }
+  }
+
+  for (const task of tasks) {
+    if (!task || typeof task.id !== 'string') continue
+    const blockedBy = Array.isArray(task.blockedBy) ? task.blockedBy : []
+    for (const bId of blockedBy) {
+      if (typeof bId === 'string' && bId.trim() !== '') {
+        if (!blocks[bId]) blocks[bId] = []
+        if (!blocks[bId].includes(task.id)) {
+          blocks[bId].push(task.id)
+        }
+      }
+    }
+  }
+
+  return blocks
+}
+
+/**
+ * Check whether a task is blocked by unfinished tasks.
+ *
+ * @param {object} task task object
+ * @param {Function|object} getTaskFn task getter function or store
+ * @returns {{isBlocked: boolean, pendingBlockers: Array<object>}}
+ */
+export function checkTaskBlocked(task, getTaskFn) {
+  const blockedBy = Array.isArray(task?.blockedBy) ? task.blockedBy : []
+  if (blockedBy.length === 0) {
+    return { isBlocked: false, pendingBlockers: [] }
+  }
+
+  const pending = []
+  for (const bId of blockedBy) {
+    if (typeof bId !== 'string' || bId.trim() === '') continue
+    const bTask = typeof getTaskFn === 'function' ? getTaskFn(bId) : getTaskFn?.getTask?.(bId)
+    if (bTask && bTask.column !== 'done') {
+      pending.push(bTask)
+    }
+  }
+
+  return {
+    isBlocked: pending.length > 0,
+    pendingBlockers: pending,
+  }
+}
+
+/**
+ * Check if moving a task to a target column is allowed under dependency constraints.
+ *
+ * @param {object} task task object
+ * @param {string} targetColumn target column
+ * @param {Function|object} getTaskFn task getter function or store
+ * @returns {{allowed: boolean, reason?: string, pendingBlockers?: Array<object>}}
+ */
+export function checkMoveAllowed(task, targetColumn, getTaskFn) {
+  if (targetColumn === 'in-progress') {
+    const check = checkTaskBlocked(task, getTaskFn)
+    if (check.isBlocked) {
+      const names = check.pendingBlockers.map((b) => b.title || b.id).join(', ')
+      return {
+        allowed: false,
+        reason: `Cannot move card to in-progress: task is blocked by unfinished tasks (${names}). All blockers must be in done before starting.`,
+        pendingBlockers: check.pendingBlockers,
+      }
+    }
+  }
+  return { allowed: true }
+}
+
+/**
+ * Find all tasks that were blocked by completedTaskId and are now unblocked.
+ *
+ * @param {string} completedTaskId ID of task moving to done
+ * @param {Function|object} getTaskFn task getter function or store
+ * @param {Function} listTasksFn function returning all tasks
+ * @returns {Array<object>} tasks that transitioned from blocked to unblocked
+ */
+export function findUnblockedDependents(completedTaskId, getTaskFn, listTasksFn) {
+  const allTasks = typeof listTasksFn === 'function' ? listTasksFn() : []
+  const unblocked = []
+
+  for (const task of allTasks) {
+    if (!task || task.column === 'done') continue
+    const blockedBy = Array.isArray(task.blockedBy) ? task.blockedBy : []
+    if (!blockedBy.includes(completedTaskId)) continue
+
+    // Check if task is still blocked by any other unfinished task
+    const check = checkTaskBlocked(task, getTaskFn)
+    if (!check.isBlocked) {
+      unblocked.push(task)
+    }
+  }
+
+  return unblocked
+}
+

package/lib/routes/board.js

@@ -4,6 +4,7 @@ import { columnStats, doneWithin, stale } from '../metrics.js'
 import { isStale } from '../time.js'
 import { facetsOf, facetsOfTask, groupByRepo, sortByLife } from '../filters.js'
 import { computeNextRun } from '../cron.js'
+import { computeBlocksMap, checkTaskBlocked } from '../dependencies.js'
 
 export function withPlan(task, liveOf, config, now, sameSession) {
   const plan = parsePlan(task.plan)
@@ -74,12 +75,15 @@ export function buildBoard({ store, config, board = 'main', repo, liveOf, sync,
     if (!bySession.has(id)) bySession.set(id, [])
     bySession.get(id).push(task)
   }
+  const blocksMap = computeBlocksMap(raw)
   const tasks = orderForBoard(
     raw.map((task) => {
       const enriched = withPlan(task, liveOf, config, now, bySession.get(task.sessionId) ?? [])
       if (task.isEpic) {
         enriched.subtasksCount = store.countSubtasks(task.id)
       }
+      enriched.blocks = blocksMap[task.id] || []
+      enriched.isBlocked = checkTaskBlocked(task, store).isBlocked
       return enriched
     }),
     columnsOf(store.boardKind(board)),

package/lib/routes/task-actions.js

@@ -1,3 +1,5 @@
+import { isTimeMachineAvailable, listTaskSnapshots, createCheckpointSnapshot, rollbackToSnapshot } from '../time-machine.js'
+
 /**
  * Extended actions for task route handlers (comments, reports, checklist, triage, subtasks, PR, nudge).
  * Zero Cyrillic in lib/ according to Issue #366.
@@ -343,3 +345,74 @@ export async function handleTaskNudge({ store, id, prompt, agents, createMessage
     },
   }
 }
+
+/**
+ * Handle listing or creating snapshots via dsh-time-machine (#377).
+ */
+export async function handleTaskSnapshot({ ctx, store, id, method, body, config, env, cwdOf, logger }) {
+  const task = store.getTask(id)
+  if (!task) return { status: 404, body: { error: 'task-not-found' } }
+
+  if (method === 'GET') {
+    const available = isTimeMachineAvailable(ctx)
+    const snapshots = available ? await listTaskSnapshots({ ctx, task }) : []
+    return {
+      status: 200,
+      body: {
+        available,
+        inceptionSnapshotId: task.inceptionSnapshotId || '',
+        snapshots,
+      },
+    }
+  }
+
+  if (method === 'POST') {
+    const label = typeof body?.label === 'string' ? body.label.trim() : ''
+    const res = await createCheckpointSnapshot({ ctx, task, label, config, env, cwdOf, logger })
+    if (!res.available) {
+      return {
+        status: 503,
+        body: {
+          error: 'time-machine-unavailable',
+          message: 'Plugin @goodandready/dsh-time-machine is not installed or active in this profile.',
+        },
+      }
+    }
+    if (!res.created) {
+      return { status: 500, body: { error: 'snapshot-failed', message: res.error } }
+    }
+    return { status: 201, body: { success: true, snapshot: res.snapshot } }
+  }
+
+  return { status: 405, body: { error: 'method-not-allowed' } }
+}
+
+/**
+ * Handle rolling back task worktree to inception or specified snapshot (#377).
+ */
+export async function handleTaskRollbackSnapshot({ ctx, store, id, body, config, env, cwdOf, logger, eventHub }) {
+  const task = store.getTask(id)
+  if (!task) return { status: 404, body: { error: 'task-not-found' } }
+
+  const snapshotId = typeof body?.snapshotId === 'string' ? body.snapshotId.trim() : task.inceptionSnapshotId
+  const res = await rollbackToSnapshot({ ctx, task, snapshotId, config, env, cwdOf, logger })
+  if (!res.available) {
+    return { status: 503, body: { error: 'time-machine-unavailable', message: res.message } }
+  }
+  if (!res.rolledBack) {
+    return { status: 400, body: { error: res.error, message: res.message } }
+  }
+
+  if (eventHub && typeof eventHub.broadcast === 'function') {
+    eventHub.broadcast('task:change', { taskId: id, action: 'rollback', snapshotId: res.snapshotId })
+  }
+
+  return {
+    status: 200,
+    body: {
+      success: true,
+      snapshotId: res.snapshotId,
+      result: res.result,
+    },
+  }
+}

package/lib/routes/task.js

@@ -1,6 +1,7 @@
 import { parseBody } from '../markdown.js'
 import { columnsOf, wipLimitField } from '../config.js'
 import { withPlan } from './board.js'
+import { checkMoveAllowed, validateDependencies, findUnblockedDependents } from '../dependencies.js'
 
 export function parseTaskPath(pathname) {
   const m = /^\/dsh-kanban\/task\/([^/]+)(?:\/([a-z-]+))?\/?$/.exec(pathname ?? '')
@@ -23,6 +24,17 @@ export function applyMove({ store, config, id, column, beforeId, afterId, source
     if (!allowed.includes(column)) {
       return { error: 'invalid-column', status: 400 }
     }
+    if (column === 'in-progress' && before.column !== 'in-progress') {
+      const moveCheck = checkMoveAllowed(before, column, store)
+      if (!moveCheck.allowed) {
+        return {
+          error: 'task-blocked',
+          status: 400,
+          message: moveCheck.reason,
+          pendingBlockers: moveCheck.pendingBlockers,
+        }
+      }
+    }
   }
   const task = store.moveTask(id, { column, beforeId, afterId })
   if (task.column !== before.column) {
@@ -32,7 +44,10 @@ export function applyMove({ store, config, id, column, beforeId, afterId, source
   }
   const limit = wipLimitField(config, task.column)
   const count = store.countInColumn(task.board, task.column)
-  return { task, overLimit: limit !== undefined && count > limit }
+  const unblocked = (task.column === 'done' && before.column !== 'done')
+    ? findUnblockedDependents(id, store, () => store.listTasks({ board: task.board }))
+    : []
+  return { task, overLimit: limit !== undefined && count > limit, unblocked }
 }
 
 /** Create local board task (not linked to Gitea). */
@@ -96,6 +111,17 @@ export function updateTask({ store, id, input }) {
     const val = input.forge.trim().toLowerCase()
     if (val === 'github' || val === 'gitea') patch.forge = val
   }
+  if (Array.isArray(input?.blockedBy)) {
+    const newBlockedBy = input.blockedBy.filter((b) => typeof b === 'string' && b.trim() !== '')
+    const check = validateDependencies(id, newBlockedBy, store)
+    if (!check.valid) {
+      return { error: 'circular-dependency', status: 400, message: check.error }
+    }
+    patch.blockedBy = newBlockedBy
+  }
+  if (typeof input?.inceptionSnapshotId === 'string') {
+    patch.inceptionSnapshotId = input.inceptionSnapshotId.trim()
+  }
   return { task: store.updateTask(id, patch) }
 }
 

package/lib/routes.js

@@ -69,4 +69,6 @@ export {
   handleToggleChecklistItem,
   handleCreateTaskPr,
   handleTaskNudge,
+  handleTaskSnapshot,
+  handleTaskRollbackSnapshot,
 } from './routes/task-actions.js'

package/lib/server/task-handler.js

@@ -30,6 +30,8 @@ import {
   handleToggleChecklistItem,
 } from '../routes.js'
 import { verifyAndRecordGate } from '../verification.js'
+import { handleTaskSnapshot, handleTaskRollbackSnapshot } from '../routes.js'
+import { createInceptionSnapshot } from '../time-machine.js'
 import { runTask, queueTask, unqueueTask, resolveModel, buildStartMessage, PERMISSION_RANKS } from '../launcher.js'
 import { dispatchMove, stopWork, MOVE_DETAIL, STOP_DETAIL } from '../commands.js'
 import { checkWorktreeDirty } from '../worktree.js'
@@ -257,6 +259,25 @@ export function createTaskRouteHandler(deps) {
                 out.dirtyFiles = dirty.files
               }
             }
+            if (out.task.column === 'in-progress' && was?.column !== 'in-progress') {
+              const cfg = getConfig()
+              if (cfg?.timeMachineEnabled !== false && cfg?.timeMachineAutoSnapshot !== false) {
+                createInceptionSnapshot({
+                  ctx,
+                  task: out.task,
+                  config: cfg,
+                  env: process.env,
+                  cwdOf: () => rootOf(cfg, () => process.cwd()).path,
+                  store,
+                  logger: ctx.logger,
+                }).catch(() => {})
+              }
+            }
+            if (Array.isArray(out.unblocked) && out.unblocked.length > 0) {
+              for (const dep of out.unblocked) {
+                eventHub.broadcast('task:change', { taskId: dep.id, action: 'unblocked', task: dep })
+              }
+            }
           }
           reply(res, out)
           return
@@ -400,6 +421,24 @@ export function createTaskRouteHandler(deps) {
           writeJson(res, resObj.status, resObj.body)
           return
         }
+        if ((req.method === 'GET' || req.method === 'POST') && action === 'snapshot') {
+          const cfg = getConfig()
+          const resObj = await handleTaskSnapshot({
+            ctx, store, id, method: req.method, body: input, config: cfg,
+            env: process.env, cwdOf: () => rootOf(cfg, () => process.cwd()).path, logger: ctx.logger,
+          })
+          writeJson(res, resObj.status, resObj.body)
+          return
+        }
+        if (req.method === 'POST' && action === 'rollback-snapshot') {
+          const cfg = getConfig()
+          const resObj = await handleTaskRollbackSnapshot({
+            ctx, store, id, body: input, config: cfg,
+            env: process.env, cwdOf: () => rootOf(cfg, () => process.cwd()).path, logger: ctx.logger, eventHub,
+          })
+          writeJson(res, resObj.status, resObj.body)
+          return
+        }
         if (req.method === 'POST' && action === 'resume') {
           watchdog?.resumeTask?.({ store, taskId: id, eventHub })
           const task = store.getTask(id)

package/lib/store.js

@@ -79,6 +79,8 @@ CREATE TABLE IF NOT EXISTS tasks (
   stalled               INTEGER NOT NULL DEFAULT 0,
   stalledReason         TEXT NOT NULL DEFAULT '',
   stalledAt             INTEGER NOT NULL DEFAULT 0,
+  blockedBy             TEXT NOT NULL DEFAULT '[]',
+  inceptionSnapshotId   TEXT NOT NULL DEFAULT '',
   updatedAt    INTEGER NOT NULL
 );
 CREATE INDEX IF NOT EXISTS tasks_board_col ON tasks(board, col, position);
@@ -114,6 +116,7 @@ const WRITABLE = [
   'verificationCommand', 'verificationStatus',
   'costMetrics', 'costLimitExceeded',
   'stalled', 'stalledReason', 'stalledAt',
+  'blockedBy', 'inceptionSnapshotId',
 ]
 
 /** Valid transition sources; unexpected values are rejected to preserve log integrity. */
@@ -121,7 +124,7 @@ const SOURCES = new Set(['manual', 'session', 'gitea', 'github', 'tool', 'workfl
 
 function rowToTask(row) {
   if (row === undefined) return undefined
-  const { col, labels, waiting, labelColors, runs, checklist, report, comments, rejectReason, rejectedAt, isEpic, parentId, stalled, ...rest } = row
+  const { col, labels, waiting, labelColors, runs, checklist, report, comments, rejectReason, rejectedAt, isEpic, parentId, stalled, blockedBy, inceptionSnapshotId, ...rest } = row
   let parsedChecklist = []
   try {
     const value = JSON.parse(checklist ?? '[]')
@@ -177,6 +180,13 @@ function rowToTask(row) {
       return rest.costMetrics && typeof rest.costMetrics === 'object' ? rest.costMetrics : null;
     })(),
     costLimitExceeded: rest.costLimitExceeded === 1 || rest.costLimitExceeded === true,
+    blockedBy: (() => {
+      try {
+        const val = JSON.parse(blockedBy ?? '[]')
+        return Array.isArray(val) ? val.filter((x) => typeof x === 'string') : []
+      } catch { return [] }
+    })(),
+    inceptionSnapshotId: typeof inceptionSnapshotId === 'string' ? inceptionSnapshotId : (typeof rest.inceptionSnapshotId === 'string' ? rest.inceptionSnapshotId : ''),
   }
 }
 
@@ -272,6 +282,8 @@ export function openStore({ dir }) {
     ['stalled', 'INTEGER NOT NULL DEFAULT 0'],
     ['stalledReason', "TEXT NOT NULL DEFAULT ''"],
     ['stalledAt', 'INTEGER NOT NULL DEFAULT 0'],
+    ['blockedBy', "TEXT NOT NULL DEFAULT '[]'"],
+    ['inceptionSnapshotId', "TEXT NOT NULL DEFAULT ''"],
   ]) {
     try { db.exec(`ALTER TABLE tasks ADD COLUMN ${column} ${definition}`) } catch { /* column already exists */ }
   }
@@ -614,6 +626,8 @@ export function openStore({ dir }) {
         else if (key === 'syncedAt') values.push(Number(patch[key]) || 0)
         else if (key === 'isEpic') values.push(patch[key] ? 1 : 0)
         else if (key === 'parentId') values.push(String(patch[key] ?? ''))
+        else if (key === 'blockedBy') values.push(Array.isArray(patch[key]) ? JSON.stringify(patch[key]) : (typeof patch[key] === 'string' ? patch[key] : '[]'))
+        else if (key === 'inceptionSnapshotId') values.push(String(patch[key] ?? ''))
         else values.push(patch[key] ?? null)
       }
       if (fields.length > 0) {

package/lib/time-machine.js

@@ -0,0 +1,214 @@
+// Integration service for @goodandready/dsh-time-machine snapshot and rollback capabilities.
+// Provides automatic inception snapshots on task start and one-click rollback to clean state.
+// Degrades gracefully when @goodandready/dsh-time-machine plugin is not installed in DSH profile.
+
+import { resolveTaskWorktreePath } from './worktree.js'
+
+/**
+ * Check whether timeMachineEngine is available in the Cordis context.
+ *
+ * @param {object} ctx Cordis context or harness
+ * @returns {boolean} true if time machine engine is available
+ */
+export function isTimeMachineAvailable(ctx) {
+  if (!ctx || typeof ctx !== 'object') return false
+  const engine = ctx.timeMachineEngine || (typeof ctx.get === 'function' ? (ctx.get('timeMachineEngine') || ctx.get('timeMachine')) : null)
+  return !!(engine && (typeof engine.createSnapshot === 'function' || typeof engine.rollbackSnapshot === 'function' || typeof engine.listSnapshots === 'function'))
+}
+
+/**
+ * Resolve the timeMachineEngine instance from context.
+ *
+ * @param {object} ctx Cordis context
+ * @returns {object|null}
+ */
+export function getTimeMachineEngine(ctx) {
+  if (!ctx || typeof ctx !== 'object') return null
+  const engine = ctx.timeMachineEngine || (typeof ctx.get === 'function' ? (ctx.get('timeMachineEngine') || ctx.get('timeMachine')) : null)
+  if (engine && (typeof engine.createSnapshot === 'function' || typeof engine.rollbackSnapshot === 'function' || typeof engine.listSnapshots === 'function')) {
+    return engine
+  }
+  return null
+}
+
+/**
+ * Resolve the directory path to snapshot for a task.
+ *
+ * @param {{task: object, config?: object, env?: object, cwdOf?: Function}} options
+ * @returns {string}
+ */
+export function resolveSnapshotDir({ task, config, env, cwdOf }) {
+  if (task?.worktree && typeof task.worktree === 'string' && task.worktree.trim() !== '') {
+    return task.worktree.trim()
+  }
+  try {
+    const resolved = resolveTaskWorktreePath({ task, config, env, cwdOf: cwdOf || (() => process.cwd()) })
+    if (resolved) return resolved
+  } catch {
+    /* fallback to cwd */
+  }
+  return typeof cwdOf === 'function' ? cwdOf() : process.cwd()
+}
+
+/**
+ * Automatically create inception snapshot when task moves to in-progress.
+ *
+ * @param {{ctx: object, task: object, config?: object, env?: object, cwdOf?: Function, store?: object, logger?: object}} options
+ * @returns {Promise<{available: boolean, created: boolean, snapshotId?: string, alreadyExists?: boolean, snapshot?: object, error?: string}>}
+ */
+export async function createInceptionSnapshot({ ctx, task, config, env, cwdOf, store, logger }) {
+  const engine = getTimeMachineEngine(ctx)
+  if (!engine) {
+    return { available: false, created: false }
+  }
+
+  if (task?.inceptionSnapshotId && typeof task.inceptionSnapshotId === 'string' && task.inceptionSnapshotId.trim() !== '') {
+    return {
+      available: true,
+      created: false,
+      alreadyExists: true,
+      snapshotId: task.inceptionSnapshotId.trim(),
+    }
+  }
+
+  const targetDir = resolveSnapshotDir({ task, config, env, cwdOf })
+  const label = `Inception: ${task?.id || 'task'} (${task?.title || 'untitled'})`
+  const sessionId = `task-${task?.id || 'default'}`
+
+  try {
+    const snapshot = await engine.createSnapshot(label, {
+      sessionId,
+      cwd: targetDir,
+      skipIfNoChanges: false,
+    })
+
+    if (snapshot?.id && store && typeof store.updateTask === 'function' && task?.id) {
+      store.updateTask(task.id, { inceptionSnapshotId: snapshot.id })
+    }
+
+    return {
+      available: true,
+      created: true,
+      snapshotId: snapshot?.id,
+      snapshot,
+    }
+  } catch (err) {
+    logger?.warn?.('[dsh-kanban] Failed to create inception snapshot:', err?.message || err)
+    return {
+      available: true,
+      created: false,
+      error: err?.message || String(err),
+    }
+  }
+}
+
+/**
+ * Manually create a checkpoint snapshot for a task.
+ *
+ * @param {{ctx: object, task: object, label?: string, config?: object, env?: object, cwdOf?: Function, logger?: object}} options
+ * @returns {Promise<{available: boolean, created: boolean, snapshot?: object, error?: string}>}
+ */
+export async function createCheckpointSnapshot({ ctx, task, label, config, env, cwdOf, logger }) {
+  const engine = getTimeMachineEngine(ctx)
+  if (!engine) {
+    return { available: false, created: false }
+  }
+
+  const targetDir = resolveSnapshotDir({ task, config, env, cwdOf })
+  const snapshotLabel = `Checkpoint: ${label || 'manual'} (${task?.id || 'task'})`
+  const sessionId = `task-${task?.id || 'default'}`
+
+  try {
+    const snapshot = await engine.createSnapshot(snapshotLabel, {
+      sessionId,
+      cwd: targetDir,
+      skipIfNoChanges: false,
+    })
+    return {
+      available: true,
+      created: true,
+      snapshot,
+    }
+  } catch (err) {
+    logger?.warn?.('[dsh-kanban] Failed to create checkpoint snapshot:', err?.message || err)
+    return {
+      available: true,
+      created: false,
+      error: err?.message || String(err),
+    }
+  }
+}
+
+/**
+ * Roll back task files to a snapshot (default: inception snapshot).
+ *
+ * @param {{ctx: object, task: object, snapshotId?: string, config?: object, env?: object, cwdOf?: Function, logger?: object}} options
+ * @returns {Promise<{available: boolean, rolledBack: boolean, snapshotId?: string, result?: object, error?: string, message?: string}>}
+ */
+export async function rollbackToSnapshot({ ctx, task, snapshotId, config, env, cwdOf, logger }) {
+  const engine = getTimeMachineEngine(ctx)
+  if (!engine) {
+    return {
+      available: false,
+      rolledBack: false,
+      error: 'time-machine-unavailable',
+      message: 'Plugin @goodandready/dsh-time-machine is not installed or active in this profile.',
+    }
+  }
+
+  const targetId = snapshotId || task?.inceptionSnapshotId
+  if (!targetId || typeof targetId !== 'string' || targetId.trim() === '') {
+    return {
+      available: true,
+      rolledBack: false,
+      error: 'no-snapshot-id',
+      message: 'No snapshot ID specified and task has no inception snapshot.',
+    }
+  }
+
+  const targetDir = resolveSnapshotDir({ task, config, env, cwdOf })
+
+  try {
+    const result = await engine.rollbackSnapshot(String(targetId).trim(), {
+      confirm: true,
+      cwd: targetDir,
+    })
+    return {
+      available: true,
+      rolledBack: true,
+      snapshotId: targetId,
+      result,
+    }
+  } catch (err) {
+    logger?.error?.('[dsh-kanban] Failed to rollback snapshot:', err?.message || err)
+    return {
+      available: true,
+      rolledBack: false,
+      error: 'rollback-failed',
+      message: err?.message || String(err),
+    }
+  }
+}
+
+/**
+ * List snapshots for a task.
+ *
+ * @param {{ctx: object, task: object}} options
+ * @returns {Promise<Array<object>>}
+ */
+export async function listTaskSnapshots({ ctx, task }) {
+  const engine = getTimeMachineEngine(ctx)
+  if (!engine || !task?.id) return []
+
+  const sessionId = `task-${task.id}`
+  try {
+    if (typeof engine.listSnapshots === 'function') {
+      const list = engine.listSnapshots(sessionId)
+      return Array.isArray(list) ? list : []
+    }
+  } catch {
+    /* ignore error */
+  }
+  return []
+}
+