@goodandready/dsh-kanban 0.2.19 → 0.2.21

package/lib/lifecycle.js

@@ -1,34 +1,28 @@
-// Признак ожидания по событиям сессии.
-//
-// Колонки «Блокировано» в согласованном наборе нет, поэтому запрос разрешения
-// или вопрос агента НЕ двигают карточку, а поднимают на ней признак «нужен
-// человек». Двигать в несуществующую колонку нельзя, а прятать «агент стоит и
-// ждёт» — значит терять главное, ради чего смотрят на доску.
-//
-// Подписка на события ядра живёт в `lib/index.js`; здесь только решение, что
-// делать с очередным событием.
+// Session waiting indicators.
+// Permission requests or agent prompts raise a 'waiting for user' flag on card
+// without moving it to a non-existent blocked column.
 
 import { waitingFromEvent } from './transitions.js'
 import { parseProgressDump, formatProgressDump } from './progress-dump.js'
 
 /**
- * Обработать событие сессии.
+ * Process session event.
  *
- * Задача ищется по идентификатору сессии. Сессий, поднятых не с доски,
- * большинство — для них здесь ничего не происходит, и это штатный ход, а не
- * пропуск.
+ * Looks up task by sessionId. Non-kanban sessions are cleanly
+ * ignored without side effects.
+
  *
- * @returns {{taskId: string, waiting?: boolean}|undefined} что изменилось
+ * @returns {{taskId: string, waiting?: boolean}|undefined} mutation report
  */
 export function handleSessionEvent({ store, sessionId, session, type, text, error }) {
-  // Исключаем события дочерних сессий субагентов (#215)
+  // Filter out subagent child session events (#215)
   if (session && (session.origin === 'subagent' || session.parentId !== undefined || session.meta?.origin === 'subagent' || session.isSubagent)) {
     return undefined
   }
   const task = store.findTaskBySession(sessionId)
   if (task === undefined) return undefined
 
-  // Если в ответе пришёл PROGRESSDUMP — обновляем срез в задаче
+  // If turn returned PROGRESSDUMP, update task snapshot
   if (typeof text === 'string' && text.includes('<<<PROGRESSDUMP')) {
     const parsed = parseProgressDump(text)
     if (parsed.ok) {
@@ -36,7 +30,7 @@ export function handleSessionEvent({ store, sessionId, session, type, text, erro
     }
   }
 
-  // Обновляем исход запуска в истории runs
+  // Update run outcome in run history
   if (type === 'turn/end' || type === 'turn/completed') {
     const latestRun = Array.isArray(task.runs) ? task.runs[0] : undefined
     if (latestRun && latestRun.sessionId === sessionId && !latestRun.endedAt && typeof store.updateTaskRun === 'function') {

package/lib/markdown.js

@@ -1,21 +1,19 @@
-// Разбор тела задачи в дерево узлов.
+// Parse task body into node tree.
 //
-// Тело приходит из Gitea и пишет его кто угодно. Поэтому разбор отдаёт ДЕРЕВО,
-// а не строку HTML: браузерная половина собирает его элементами React, и
-// подстановка чужой разметки становится невозможной по построению, а не по
-// бдительности того, кто вспомнит про экранирование.
+// Body originates from Gitea and can contain arbitrary user content.
+// Parser returns a node TREE rather than raw HTML string: frontend renders
+// via React elements, preventing XSS injection structurally.
 //
-// Полноценный markdown здесь не нужен и не будет: заголовки, списки, выделение,
-// код и ссылки покрывают почти всякое тело issue. Всё непонятое остаётся
-// текстом как есть — это честнее, чем угадывать.
+// Full markdown engine is intentionally omitted: headings, lists, formatting,
+// code blocks and links cover typical issue bodies. Unrecognized text remains as-is.
 
-/** Ссылки открываем только по этим схемам: `javascript:` в теле — тот же обход. */
+/** Allowed link protocols: `javascript:` in body is blocked. */
 const SAFE_LINK = /^https?:\/\//i
 
 /**
- * Разобрать тело в список блоков.
+ * Parse body into list of blocks.
  *
- * @returns {Array<object>} блоки вида
+ * @returns {Array<object>} blocks shaped as
  *   `{kind:'heading', level, spans}`, `{kind:'para', spans}`,
  *   `{kind:'list', ordered, items:[spans]}`, `{kind:'code', text}`,
  *   `{kind:'quote', spans}`, `{kind:'rule'}`
@@ -30,7 +28,7 @@ export function parseBody(text) {
 
     if (line.trim() === '') { i += 1; continue }
 
-    // Блок кода: всё внутри дословно, включая то, что похоже на разметку.
+    // Code block: content preserved verbatim, including markup-like sequences.
     const fence = /^\s*```(.*)$/.exec(line)
     if (fence !== null) {
       const body = []
@@ -77,7 +75,7 @@ export function parseBody(text) {
       continue
     }
 
-    // Абзац: строки до пустой склеиваются, как это делает markdown.
+    // Paragraph: lines up to blank line are merged per markdown semantics.
     const body = []
     while (i < lines.length && lines[i].trim() !== ''
       && !/^\s*(#{1,6})\s+/.test(lines[i])
@@ -95,14 +93,14 @@ export function parseBody(text) {
 }
 
 /**
- * Разобрать строку на куски: обычный текст, код, выделение, ссылка.
+ * Parse line into inline segments: plain text, code, emphasis, links.
  *
  * @returns {Array<{kind: 'text'|'code'|'strong'|'em'|'link', text: string, href?: string}>}
  */
 export function parseSpans(text) {
   const out = []
   const src = String(text ?? '')
-  // Код первым: внутри обратных кавычек разметки нет, там всё дословно.
+  // Code spans first: inside backticks markup is treated literally.
   const re = /(`[^`]+`)|(\[[^\]]+\]\([^)\s]+\))|(\*\*[^*]+\*\*)|(__[^_]+__)|(\*[^*]+\*)|(_[^_]+_)/g
   let at = 0
   let m = re.exec(src)
@@ -117,8 +115,7 @@ export function parseSpans(text) {
       const cut = piece.indexOf('](')
       const label = piece.slice(1, cut)
       const href = piece.slice(cut + 2, -1)
-      // Небезопасная схема — не ссылка, а текст. Молча выбрасывать нельзя:
-      // человек должен видеть, что там было написано.
+      // Unsafe protocol rendered as plain text rather than active link.
       if (isSafeHref(href)) out.push({ kind: 'link', text: label, href })
       else out.push({ kind: 'text', text: piece })
     } else if (piece.startsWith('**') || piece.startsWith('__')) {
@@ -136,11 +133,7 @@ export function parseSpans(text) {
 }
 
 /**
- * Склеить соседние куски текста.
- *
- * Разбор дробит строку там, где нашёл разметку и передумал: `[клик](javascript:…)`
- * не стал ссылкой, но оставил после себя два куска. Дробление наружу не
- * выпускаем — оно не значит ничего, а читателю мешает.
+ * Merge adjacent text segments to avoid fragmentation.
  */
 function mergeText(spans) {
   const out = []
@@ -155,7 +148,7 @@ function mergeText(spans) {
   return out
 }
 
-/** Безопасна ли ссылка. Наружу — чтобы браузерная половина не решала это заново. */
+/** Whether a link protocol is safe. Exported so frontend does not recompute. */
 export function isSafeHref(href) {
   return SAFE_LINK.test(String(href ?? ''))
 }

package/lib/metrics.js

@@ -1,22 +1,22 @@
-// Метрики доски: взгляд на журнал переходов, а не новые данные.
+// Board metrics: view over transition history, not new mutable state.
 //
-// Журнал копится с первого дня, но прочитать его можно было только по одной
-// задаче. Вопросы «где затык», «сколько живёт задача» и «что лежит месяц» имеют
-// ответ в тех же записях — их надо только сложить.
+// History accumulates from day one, but was previously queried per-task.
+// Questions like 'where is bottleneck', 'task lifetime', 'stale tasks'
+// can all be answered from transition records.
 //
-// Ничего не записываем: метрика, которая пишет, перестаёт быть наблюдением и
-// становится ещё одним источником правды, расходящимся с журналом.
+// Read-only calculation: metrics do not write state to avoid becoming an
+// unaligned second source of truth.
 
 /**
- * Сколько времени задача пробыла в каждой колонке.
+ * Time spent by task in each column.
  *
- * Переход закрывает предыдущий отрезок и открывает следующий. Последний
- * отрезок закрывается «сейчас»: задача всё ещё лежит там, и это время идёт.
+ * Transition closes previous time slice and opens next.
+ * Final slice closes at present moment.
  *
- * @param {Array<{toCol: string, at: number}>} moves переходы задачи, старые первыми
- * @param {number} bornAt когда задача заведена — начало первого отрезка
+ * @param {Array<{toCol: string, at: number}>} moves task transitions, oldest first
+ * @param {number} bornAt task creation timestamp
  * @param {number} now
- * @returns {Object<string, number>} колонка → миллисекунды
+ * @returns {Object<string, number>} column -> milliseconds
  */
 export function timeInColumns(moves, bornAt, now) {
   const rows = (moves ?? [])
@@ -25,8 +25,8 @@ export function timeInColumns(moves, bornAt, now) {
     .sort((a, b) => a.at - b.at)
 
   const out = {}
-  // До первого перехода задача лежит там, где её завели. Колонку начала берём
-  // из первого перехода: `fromCol` и есть то, откуда она уехала.
+  // Prior to first transition, task resides in initial column.
+  // Derived from `fromCol` of first transition.
   let col = rows.length > 0 && typeof rows[0].fromCol === 'string' ? rows[0].fromCol : 'backlog'
   let since = typeof bornAt === 'number' ? bornAt : (rows[0]?.at ?? now)
 
@@ -44,7 +44,7 @@ export function timeInColumns(moves, bornAt, now) {
   return out
 }
 
-/** Медиана: половина значений меньше, половина больше. */
+/** Median calculation. */
 export function median(values) {
   const rows = (values ?? []).filter((x) => typeof x === 'number').slice().sort((a, b) => a - b)
   if (rows.length === 0) return 0
@@ -52,7 +52,7 @@ export function median(values) {
   return rows.length % 2 === 1 ? rows[mid] : Math.round((rows[mid - 1] + rows[mid]) / 2)
 }
 
-/** Среднее; пустой набор даёт ноль, а не деление на ноль. */
+/** Mean average; empty set returns zero without dividing by zero. */
 export function mean(values) {
   const rows = (values ?? []).filter((x) => typeof x === 'number')
   if (rows.length === 0) return 0
@@ -60,10 +60,10 @@ export function mean(values) {
 }
 
 /**
- * Сводка по колонкам: сколько в среднем и по медиане в них лежат.
+ * Column summary: average and median time spent in each column.
  *
- * Медиана важнее среднего: одна задача, забытая на полгода, сдвигает среднее
- * так, что оно перестаёт описывать хоть что-нибудь.
+ * Median is preferred over average: a single forgotten task can skew
+ * the average heavily.
  *
  * @param {Array<{task: object, moves: object[]}>} rows
  * @returns {Array<{column: string, mean: number, median: number, tasks: number}>}
@@ -88,10 +88,9 @@ export function columnStats(rows, now) {
 }
 
 /**
- * Задачи, залежавшиеся в своей колонке дольше порога.
+ * Tasks that stayed in their current column longer than threshold.
  *
- * Считаем от входа в колонку, а не от заведения: задача может быть старой и
- * при этом двигаться каждый день.
+ * Measured from column entry timestamp rather than creation date.
  *
  * @returns {Array<{id: string, title: string, column: string, since: number}>}
  */
@@ -112,10 +111,9 @@ export function stale(tasks, now, thresholdMs) {
 }
 
 /**
- * Сколько задач доехало до «Выполнено» за период.
+ * How many tasks reached 'done' within given time period.
  *
- * Считаем по переходам, а не по текущей колонке: задача, ушедшая в архив,
- * всё равно была сделана.
+ * Computed from transitions rather than current column to account for archived tasks.
  */
 export function doneWithin(rows, from, to) {
   let count = 0

package/lib/order.js

@@ -1,35 +1,33 @@
-// Дробный индекс порядка карточек.
+// Fractional ordering index for cards.
 //
-// Наивный подход хранит целочисленный индекс, и перетаскивание карточки в
-// начало колонки из десяти строк требует переписать все десять. Здесь порядок
-// хранится строкой, а новое значение выдаётся МЕЖДУ двумя соседями, поэтому
-// перетаскивание — всегда один UPDATE одной строки, сколько бы карточек ни
-// было в колонке.
+// Naive approach stores integer index, and dragging card to the top of column
+// with ten items requires rewriting all ten. Here order is stored as string,
+// and new value is generated BETWEEN two neighbors, so drag-and-drop is always
+// a single UPDATE of one row regardless of how many cards are in column.
 //
-// Реализация строковая намеренно. Вариант на числах с плавающей точкой
-// проходит поверхностную проверку и разваливается примерно на пятидесятой
-// вставке в одно и то же место, когда кончается разрядность.
+// String-based implementation is intentional. Floating-point numbers fail
+// after ~50 insertions into the same position when precision runs out.
 //
-// Ключ читается как дробь после подразумеваемого «0.»: сравнение обычное
-// лексикографическое. Ключ никогда не заканчивается первым символом алфавита —
-// иначе следующее деление слева стало бы невозможным.
+// Key is read as fraction after implicit '0.': comparison is standard
+// lexicographical. Key never ends with first alphabet character to ensure
+// subsequent division remains possible.
 
-/** Алфавит в порядке возрастания кодов символов. */
+/** Alphabet in ascending character code order. */
 const DIGITS = '0123456789abcdefghijklmnopqrstuvwxyz'
 const FIRST = DIGITS[0]
 
-/** Значение строго между `a` и `b`; `b === undefined` означает «до конца». */
+/** Value strictly between `a` and `b`; `b === undefined` means unbounded right. */
 function midpoint(a, b) {
   if (b !== undefined && a >= b) {
-    throw new Error(`порядок нарушен: ${JSON.stringify(a)} не меньше ${JSON.stringify(b)}`)
+    throw new Error(`order violated: ${JSON.stringify(a)} not less than ${JSON.stringify(b)}`)
   }
   if (a.endsWith(FIRST) || (b !== undefined && b.endsWith(FIRST))) {
-    throw new Error('ключ порядка не может заканчиваться первым символом алфавита')
+    throw new Error('order key cannot end with first alphabet symbol')
   }
 
   if (b !== undefined) {
-    // Общий префикс переносится в результат как есть, деление продолжается на
-    // остатке — иначе для близких соседей пришлось бы наращивать длину с нуля.
+    // Common prefix carried as-is, division continues on remainder
+    // to avoid inflating key length unnecessarily.
     let n = 0
     while ((a[n] ?? FIRST) === b[n]) n += 1
     if (n > 0) return b.slice(0, n) + midpoint(a.slice(n), b.slice(n))
@@ -37,7 +35,7 @@ function midpoint(a, b) {
 
   const from = a === '' ? 0 : DIGITS.indexOf(a[0])
   const to = b === undefined ? DIGITS.length : DIGITS.indexOf(b[0])
-  if (from < 0 || to < 0) throw new Error('ключ порядка содержит символ вне алфавита')
+  if (from < 0 || to < 0) throw new Error('order key contains character outside alphabet')
 
   if (to - from > 1) {
     return DIGITS[Math.round(0.5 * (from + to))]
@@ -45,21 +43,20 @@ function midpoint(a, b) {
   if (b !== undefined && b.length > 1) {
     return b.slice(0, 1)
   }
-  // Соседние символы: занимаем разряд `a` и делим следующий.
+  // Adjacent symbols: take `a` digit and divide next position.
   return DIGITS[from] + midpoint(a.slice(1), undefined)
 }
 
 /**
- * Ключ порядка строго между двумя соседями.
+ * Fractional order key strictly between two neighbors.
  *
- * Оба соседа необязательны: без обоих выдаётся стартовое значение, без правого
- * — значение после `a`, без левого — значение перед `b`. Результат всегда
- * можно снова разделить.
+ * Both neighbors are optional: without either returns default initial value;
+ * without right returns value after `a`; without left returns value before `b`.
  *
- * @param {string} [a] ключ карточки слева
- * @param {string} [b] ключ карточки справа
- * @returns {string} ключ строго между ними
- * @throws если `a` не меньше `b` либо ключ содержит символ вне алфавита
+ * @param {string} [a] left neighbor order key
+ * @param {string} [b] right neighbor order key
+ * @returns {string} key strictly between them
+ * @throws if `a` is not less than `b` or key contains invalid character
  */
 export function keyBetween(a, b) {
   return midpoint(a ?? '', b ?? undefined)

package/lib/outbound.js

@@ -1,22 +1,21 @@
-// Канбан → Gitea: закрытие issue.
+// Kanban -> Gitea: closing issue.
 //
-// Отправка идёт очередью, а не прямо из обработчика переноса. Причина простая:
-// Gitea может быть недоступен, а доска обязана двигать карточки и при
-// недоступном Gitea. Перенос, ждущий сети, превратил бы доску в заложника
-// чужого времени ответа.
+// Sending runs via queue rather than synchronously in move handler.
+// Gitea may be unreachable, but the board must still move cards.
+// A network-blocking move would make the board hostage to external latency.
 //
-// Неудачная отправка не теряется и не молчит: она повторяется, а после
-// нескольких неудач попадает в журнал задачи как проблема. Молча съеденное
-// расхождение — худшее, что может сделать синхронизация.
+// Failed dispatch is not dropped silently: it retries, and after
+// several attempts is logged as a problem in task history.
+// Silently swallowed divergence is the worst sync failure mode.
 //
-// Меток колонок доска НЕ ставит. Она их никогда и не читала: колонка выводится
-// из состояния issue, ветки и pull request, а метка лишь пересказывала в Gitea
-// то, что там уже написано. Взамен доска не трогает чужую разметку вовсе.
+// The board does NOT set column labels. It never reads them:
+// column is derived from issue/branch/PR state, while labels only duplicate it.
+// In exchange, the board leaves external labels untouched.
 
 /**
- * Что отправить в Gitea при смене ответственного.
+ * What to send to Gitea on assignee change.
  *
- * Своей задачи (без issue) это не касается: назначать там некого и негде.
+ * Does not apply to local tasks (without issue): no remote assignee exists.
  */
 export function planAssign(task, login) {
   if (typeof task?.issueNumber !== 'number') return []
@@ -31,20 +30,20 @@ export function planAssign(task, login) {
 
 export function planOutbound(task, column, config) {
   if (typeof task?.issueNumber !== 'number') return []
-  // Закрытие issue — единственное, что доска сообщает Gitea: это факт, а не
-  // пересказ фактов, которые в issue и так видны.
+  // Closing issue is the only mutation sent to Gitea: it is a concrete action,
+  // not redundant mirroring.
   return column === 'done'
     ? [{ kind: 'close', owner: task.owner, repo: task.repo, index: task.issueNumber }]
     : []
 }
 
 /**
- * Очередь отправки с повторами.
+ * Dispatch queue with retries.
  *
  * @param {object} options
- * @param {object} options.gitea клиент
- * @param {object} options.store хранилище — туда пишется отчёт о неудаче
- * @param {number} [options.maxAttempts] после скольких неудач сдаться и записать
+ * @param {object} options.gitea client
+ * @param {object} options.store store where failures are reported
+ * @param {number} [options.maxAttempts] max failed attempts before giving up
  */
 export function createOutbox({ gitea, store, logger, maxAttempts = 4 }) {
   const queue = []
@@ -57,11 +56,11 @@ export function createOutbox({ gitea, store, logger, maxAttempts = 4 }) {
     },
 
     /**
-     * Попробовать отправить всё накопленное.
+     * Try delivering all queued operations.
      *
-     * Успех убирает операцию, неудача возвращает её в очередь до предела
-     * попыток. Исчерпав попытки, операция НЕ исчезает молча: о ней пишется в
-     * журнал задачи, чтобы расхождение с Gitea было видно человеку.
+     * Success clears operation, failure reenqueues until attempt limit.
+     * Once attempts are exhausted, operation is NOT dropped silently:
+     * recorded in task history so divergence is visible to user.
      */
     async flush() {
       const pending = queue.splice(0)
@@ -89,19 +88,20 @@ export function createOutbox({ gitea, store, logger, maxAttempts = 4 }) {
             continue
           }
           dropped += 1
-          logger?.warn?.(`dsh-kanban: отправка в Gitea не удалась окончательно: ${error?.message}`)
+          logger?.warn?.(`dsh-kanban: Gitea delivery failed permanently: ${error?.message}`)
           try {
-            const task = store.getTask(item.taskId)
+            const currentStore = typeof store === 'function' ? store() : store
+            const task = currentStore?.getTask?.(item.taskId)
             if (task !== undefined) {
-              store.addTransition({
+              currentStore?.addTransition?.({
                 taskId: item.taskId,
                 fromCol: task.column,
                 toCol: task.column,
                 source: 'gitea',
-                detail: `не отправлено в Gitea после ${item.attempts} попыток: ${item.op.kind}`,
+                detail: `failed delivery to Gitea after ${item.attempts} attempts: ${item.op.kind}`,
               })
             }
-          } catch { /* журнал не должен ронять отправку */ }
+          } catch { /* log must not fail delivery */ }
         }
       }
       return { sent, retried, dropped }

package/lib/plan.js

@@ -1,31 +1,28 @@
-// План работы агента и состояние задачи.
+// Agent execution plan and task state.
 //
-// План получаем ПРЯМО — своим инструментом, а не разбором сообщений агента:
-// разбор это гадание, а инструмент `todo_list` принадлежит чужому плагину, и
-// опираться на его события значит завести зависимость.
+// Plan is captured DIRECTLY via native tool rather than parsing chat messages:
+// message parsing is heuristic, and external todo tools introduce fragile dependencies.
 //
-// Состояние тоже факт, а не догадка по таймауту. Порог тишины в настройки не
-// выносим: он был бы догадкой там, где есть точный признак.
+// State is an explicit fact rather than timeout inference.
 
-/** Пункты плана дальше этого числа не храним: план — не журнал. */
+/** Maximum plan items retained: plan is not a log history. */
 export const MAX_ITEMS = 50
 
-/** Длиннее этого пункт обрезаем: он едет на карточку в одну строку. */
+/** Truncate items longer than this: displayed in card single-line view. */
 export const MAX_ITEM_LENGTH = 120
 
 const EMPTY = { items: [], current: 0 }
 
-/** Приведение пункта к строке разумной длины. */
+/** Coerce item to string of reasonable length. */
 function cleanItem(value) {
   const text = String(value ?? '').replace(/\s+/g, ' ').trim()
   return text.length > MAX_ITEM_LENGTH ? text.slice(0, MAX_ITEM_LENGTH - 1) + '…' : text
 }
 
 /**
- * Разобрать план из хранилища.
+ * Parse plan from storage.
  *
- * Испорченное поле не должно ронять чтение всей доски, поэтому любой сбой
- * разбора превращается в пустой план.
+ * Corrupted field must not break board loading; errors return empty plan.
  */
 export function parsePlan(raw) {
   if (typeof raw !== 'string' || raw === '') return EMPTY
@@ -45,11 +42,8 @@ export function serializePlan(plan) {
 }
 
 /**
- * Указатель на пункт в работе.
+ * Pointer to active plan item.
  *
- * Ноль означает «плана нет либо он ещё не начат»; значение больше длины плана —
- * «всё сделано», и удерживать его на последнем пункте нельзя: тогда законченный
- * план вечно показывал бы последний пункт как текущий.
  */
 function clampCurrent(value, total) {
   const n = Number(value)
@@ -58,11 +52,8 @@ function clampCurrent(value, total) {
 }
 
 /**
- * Наложить правку инструмента на прежний план.
+ * Apply tool update to existing plan.
  *
- * Пункты необязательны: агент публикует план один раз, а дальше двигает только
- * указатель. Требовать список на каждом шаге значило бы гонять его целиком ради
- * одного числа.
  */
 export function applyPlan(previous, patch) {
   const prev = previous ?? EMPTY
@@ -76,10 +67,8 @@ export function applyPlan(previous, patch) {
 }
 
 /**
- * Что показать о плане.
+ * Plan display metadata.
  *
- * Числа и текст пункта отдаём отдельно: строку «3 из 7» собирает браузер, он
- * же её и переводит.
  *
  * @returns {{total: number, done: number, current: number, text: string}|undefined}
  */
@@ -87,14 +76,14 @@ export function planProgress(plan) {
   const items = plan?.items ?? []
   if (items.length === 0) return undefined
   const current = clampCurrent(plan?.current, items.length)
-  // Всё, что до текущего пункта, считается сделанным. Модель линейная: агент
-  // двигает одно число, а не ведёт список галочек.
+  // Items before active pointer are considered completed.
+  // Items before active pointer are considered completed.
   const done = current === 0 ? 0 : Math.min(current - 1, items.length)
   const text = current >= 1 && current <= items.length ? items[current - 1] : ''
   return { total: items.length, done, current, text }
 }
 
-/** Отметки пунктов для окна карточки. */
+/** Plan item checklist state. */
 export function planItems(plan) {
   const items = plan?.items ?? []
   const current = clampCurrent(plan?.current, items.length)
@@ -106,43 +95,32 @@ export function planItems(plan) {
 }
 
 /**
- * Состояние задачи.
+ * Task state resolution.
  *
- * `stopped` — не догадка по тишине, а факт: у задачи записана сессия, но живого
- * агента за ней нет. Так выглядит прерванная работа после перезапуска харнесса.
  *
- * `queued` — задача отдана сессии, но агент до неё не дошёл: она ждёт своей
- * очереди. Выводится из отметки постановки, а не хранится отдельным полем.
  *
  * @param {{task: object, live: 'running'|'idle'|undefined}} args
- *   `live` — состояние живого агента; `undefined` означает, что агента нет.
  */
 export function taskState({ task, live }) {
   const sessionId = typeof task?.sessionId === 'string' ? task.sessionId : ''
   if (sessionId === '') return 'none'
-  // Задача отдана агенту, но он до неё ещё не дошёл. Без этого состояния
-  // десять карточек в бэклоге ничем не отличаются от нетронутых, и через час
-  // никто не вспомнит, какие уже отданы.
+  // Task queued for agent session.
+  // Task queued for agent session.
+  // Task queued for agent session.
   if (typeof task?.queuedAt === 'number' && task.queuedAt > 0) return 'queued'
-  // Ожидание человека важнее хода: агент технически «работает», но без ответа
-  // не сдвинется, и именно это надо показать.
+  // Human waiting takes precedence over running status.
+  // Human waiting takes precedence over running status.
   if (task?.waiting === true) return 'waiting'
   if (live === undefined) return 'stopped'
   return live === 'running' ? 'running' : 'idle'
 }
 
 /**
- * Номер задачи в очереди своей сессии.
+ * Task index in session queue.
  *
- * Считается на лету, а не хранится: агент берёт задачи одну за другой, и у
- * оставшихся третий сам становится вторым. Хранимый номер пришлось бы
- * пересчитывать, и однажды его бы забыли.
  *
- * Порядок — по отметке постановки, а НЕ по положению карточки в колонке.
- * Перетаскивание мышью — про то, как задачи лежат; очередь — про то, в каком
- * порядке их получит агент, и менять второе первым нельзя.
  *
- * @returns {number|undefined} место начиная с единицы
+ * @returns {number|undefined} 1-based index in queue
  */
 export function queuePosition(task, sameSession) {
   const at = task?.queuedAt