@goodandready/dsh-kanban 0.2.19 → 0.2.20

package/lib/index.js

@@ -1,14 +1,13 @@
 import { registerPluginUpdater } from './updater.js'
-// dsh-kanban — доска задач для DeepSeek Harness.
+// dsh-kanban — task board for DeepSeek Harness.
 //
-// Плагин состоит из двух половин: этот модуль — серверная, `lib/client.js` —
-// браузерная. Имя пакета `@goodandready/dsh-kanban` обязано совпадать в трёх
-// местах: `package.json`, `cordis.patch.yml` и `load({ id })` в client.js.
-// Расхождение НЕ даёт ошибки в журнале — интерфейс просто не появляется.
+// Plugin consists of two halves: this module is the backend server, and `lib/client.js` is the
+// browser bundle. The package name `@goodandready/dsh-kanban` must match in three places:
+// `package.json`, `cordis.patch.yml`, and `load({ id })` in client.js.
 //
-// Чистая логика вынесена в модули без зависимостей (`config.js`, `order.js`,
-// `routes.js`) и проверяется тестами без харнесса. Здесь остаётся обвязка
-// cordis: настройки, хранилище и маршруты.
+// Pure domain logic is kept in standalone modules (`config.js`, `order.js`, `routes.js`)
+// and tested without harness runtime. This module handles cordis integration:
+// configuration, database storage, and HTTP endpoints.
 
 import {
   MAX_BODY_BYTES,
@@ -102,35 +101,27 @@ import { TASK_TEMPLATES, getTemplateById } from './templates.js'
 
 export { COLUMN_ORDER, wipLimitField, withDefaults } from './config.js'
 
-/** Стабильное имя плагина cordis (строка в патче сборки). */
+/** Stable cordis plugin name (patch identifier). */
 export const name = '@goodandready/dsh-kanban'
 
 /**
- * Службы добавляются там, где впервые нужны: `gitea` — вместе с импортом
- * задач, `agents`/`sessions` — вместе с запуском работы. Объявленная, но
- * отсутствующая служба не даёт плагину загрузиться вовсе.
+ * Services are injected where needed. Declaring an unavailable service prevents
+ * the plugin from loading entirely.
  */
 export const inject = ['settings', 'webServer', 'agents', 'agentDefaultModel', 'credentials', 'llm', 'tools']
 
-/** Пространство настроек; то же имя продублировано в браузерной половине. */
-// Пространство настроек — просто строка.
-//
-// В 0.1.1 ядро отдавало помощника `settingsNamespace`, который проверял имя по
-// образцу и возвращал ту же строку с типом-меткой. В 0.1.2-alpha.2 помощника
-// убрали, и импорт его роняет ЗАГРУЗКУ ВСЕГО ПРОФИЛЯ, а не один плагин.
-// Проверять здесь нечего: имя — постоянная этого файла, а не пользовательский
-// ввод. На обеих версиях ядра значение одно и то же.
+/** Settings namespace string matching client bundle definition. */
+// Constant string defined in this file; identical across core versions.
 export const SETTINGS_NAMESPACE = 'dsh-kanban'
 
 /**
- * Схема собирается из значений по умолчанию, чтобы список полей жил в одном
- * месте. Только скаляры: клиентский API настроек пишет ТОЛЬКО скалярные поля,
- * и словарь или массив здесь сделал бы карточку нередактируемой.
+ * Schema constructed from default values so fields reside in one place.
+ * Scalar values only: client config API only writes scalar fields;
+ * dictionaries or arrays here would make the settings card uneditable.
  */
 export const Config = z.object(Object.fromEntries(
   Object.entries(CONFIG_DEFAULTS).map(([field, fallback]) => {
-    // Узел схемы выбирается по типу умолчания. Пропустить здесь булево значит
-    // объявить его строкой — и плагин не загрузится вовсе с «invalid config».
+    // Node type derived from default value type.
     let node = typeof fallback === 'number' ? z.number()
       : typeof fallback === 'boolean' ? z.boolean()
         : z.string()
@@ -141,7 +132,7 @@ export const Config = z.object(Object.fromEntries(
   }),
 ))
 
-/** Каталог хранилища. Абсолютных путей в коде нет — только переменная и дом. */
+/** Storage directory path resolved from environment variable or user home directory. */
 export function storeDir() {
   return process.env.DSH_KANBAN_DIR || join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'kanban')
 }
@@ -153,7 +144,7 @@ function writeJson(res, code, body) {
   } catch { /* socket closed */ }
 }
 
-/** Ответ обработчика: либо объект с `error` и `status`, либо полезная нагрузка. */
+/** Handler response helper: either an error object or success payload. */
 function reply(res, out) {
   if (out && typeof out === 'object' && typeof out.error === 'string') {
     writeJson(res, out.status ?? 400, { error: out.error })
@@ -185,11 +176,9 @@ function readBody(req) {
 }
 
 /**
- * Сырое тело запроса.
- *
- * Подпись вебхука считается по БАЙТАМ доставки. Разобрать JSON и собрать его
- * обратно — значит получить другую последовательность байт и не сойтись в
- * подписи на пустом месте.
+ * Read raw request body bytes.
+ * Webhook signatures are computed over delivery byte buffers; parsing and re-serializing
+ * could alter byte sequences and fail signature verification.
  */
 function readRaw(req) {
   return new Promise((resolve, reject) => {
@@ -217,9 +206,8 @@ export function apply(ctx, config) {
   let effective = withDefaults(config)
   const getConfig = () => effective
 
-  // Часть настроек управляет живыми подписками: промежутком сверки и наличием
-  // инструмента у агента. Прочитать их один раз при загрузке — значит сделать
-  // переключатель в карточке настроек безответным до перезапуска харнесса.
+  // Settings control live subscriptions: sync intervals and agent tools.
+  // Dynamic watcher re-evaluates configurations on change without requiring restart.
   const rearmers = new Set()
   const rearm = () => {
     for (const again of rearmers) {
@@ -234,9 +222,8 @@ export function apply(ctx, config) {
     ctx.effect(() => scope.watch(() => { effective = read(); rearm() }), 'dsh-kanban: settings watcher')
   })
 
-  // Клиент Gitea свой: токен всё равно живёт в службе учётных данных ядра, а
-  // шесть вызовов REST дешевле зависимости от чужого выпуска. Значение токена
-  // наружу не отдаётся — в настройках только ИМЯ учётной записи.
+  // Dedicated Gitea client resolves token via core credentials service.
+  // Secret token values are never exposed externally; only the credential reference name is stored.
   const resolveSecret = async (name) => {
     if (typeof name !== 'string' || name.trim() === '') return ''
     try {
@@ -263,8 +250,7 @@ export function apply(ctx, config) {
     getConfig,
   })
 
-  // Хранилище открывается один раз и закрывается уборщиком того же эффекта:
-  // выгрузка плагина обязана отпустить файл базы.
+  // Database store opens once and is closed on effect disposal.
   let store
   const taskService = createKanbanTaskService({ getStore: () => store })
   if (typeof ctx.provide === 'function') ctx.provide('dshKanban', taskService)
@@ -273,7 +259,7 @@ export function apply(ctx, config) {
     return () => { try { store.close() } catch { /* already closed */ } }
   }, 'dsh-kanban: task store')
 
-  // Кроссплатформенный ингибитор сна системы во время работы задач
+  // Cross-platform system sleep inhibitor while tasks are actively running
   const powerInhibitor = new PowerInhibitor({
     platform: process.platform,
     pid: process.pid,
@@ -312,7 +298,7 @@ export function apply(ctx, config) {
     return () => { powerInhibitor.destroy() }
   }, 'dsh-kanban: power inhibitor')
 
-  // Инъекция секции доски в системный промпт агента
+  // Inject board instructions into agent system prompt
   let disposePromptSection
   const syncPromptSection = () => {
     if (disposePromptSection) {
@@ -339,10 +325,10 @@ export function apply(ctx, config) {
     return () => { if (disposePromptSection) { try { disposePromptSection() } catch { /* cleanup best effort */ } } }
   }, 'dsh-kanban: system prompt section')
 
-  // Признак ожидания, исходы сессий и PROGRESSDUMP по событиям сессии.
+  // Track waiting flags, session outcomes, and progress dump from session events.
   ctx.effect(() => ctx.on('session/event', (session, event) => {
     try {
-      // Автосинхронизация сессий чата DSH в карточки канбана (#225)
+      // Auto-sync DSH chat sessions into kanban cards (#225)
       const sessionIdStr = String(session?.id ?? '')
       if (
         getConfig().autoSyncSessions === true &&
@@ -395,7 +381,7 @@ export function apply(ctx, config) {
         error: event?.error,
       })
       syncPower()
-      // Если сессия завершила шаг или упала — пробуем продвинуть очередь задач (#214)
+      // Dispatch next queued task when a session completes or fails (#214)
       if (event?.type === 'turn/end' || event?.type === 'turn/completed' || event?.type === 'session/error' || event?.type === 'turn/error') {
         dispatchNextQueuedTask({
           agents: ctx.agents,
@@ -414,7 +400,7 @@ export function apply(ctx, config) {
     }
   }), 'dsh-kanban: session events')
 
-  // Фоновый шедулер cron для задач
+  // Background cron scheduler for scheduled tasks
   ctx.effect(() => {
     let cronTimer
     const armCron = () => {
@@ -482,12 +468,8 @@ export function apply(ctx, config) {
     return () => { rearmers.delete(armCron); clearInterval(cronTimer) }
   }, 'dsh-kanban: cron scheduler')
 
-  // Периодическая сверка с Gitea. Ноль в настройках отключает её целиком, а
-  // перекрытие запусков не допускается: медленный инстанс иначе копил бы
-  // очередь сверок вместо одной идущей.
-  // Очередь отправки в Gitea. Перенос карточки не ждёт сети: доска обязана
-  // работать и при недоступном Gitea, а неудачная отправка повторяется и, если
-  // так и не удалась, попадает в журнал задачи.
+  // Periodic Gitea reconciliation. 0 disables it; overlapping executions are prevented.
+  // Outbound push queue to Gitea. Card moves do not block on network; failures retry in background.
   const outbox = createOutbox({ gitea: git, store, logger: ctx.logger })
 
   const queueOutbound = (taskId, column) => {
@@ -499,11 +481,8 @@ export function apply(ctx, config) {
   }
 
   /**
-   * Владелец для коротких имён в списке отслеживаемых репозиториев.
-   *
-   * Берётся из задач, уже лежащих на доске: другого источника у плагина нет,
-   * а спрашивать владельца отдельной настройкой значит просить дважды одно и
-   * то же.
+   * Default repository owner for short repository names.
+   * Inferred from existing board tasks when not explicitly configured.
    */
   let discoveredOwner
   const defaultOwner = async () => {
@@ -513,15 +492,13 @@ export function apply(ctx, config) {
       if (typeof task.owner === 'string' && task.owner !== '') return task.owner
     }
     if (discoveredOwner !== undefined) return discoveredOwner
-    // Спрашиваем у Gitea, и только когда организация ровно одна: при
-    // нескольких гадание молча смотрело бы не туда, а это хуже отказа.
+    // Fall back to Gitea organization if exactly one is accessible to the token.
     const orgs = await gitea.listOrgs()
     if (orgs.length === 1) { discoveredOwner = orgs[0]; return discoveredOwner }
     return undefined
   }
 
-  // Состояние сверки видно человеку в шапке доски: доска, переставшая
-  // обновляться, не имеет права молчать об этом.
+  // Sync telemetry state visible in board header.
   const syncState = createSyncState()
 
   let syncing = false
@@ -530,9 +507,8 @@ export function apply(ctx, config) {
     syncing = true
     syncState.started()
     try {
-      // Порядок важен. Сперва забираем новое: свежая задача должна попасть на
-      // доску и тут же быть сверена, а не ждать следующего прохода. Архивация
-      // последней — она смотрит на итог, а не на исходное.
+      // Order of operations: intake new issues first, reconcile active tasks, archive overdue.
+      // Inspect final outcome rather than initial state.
       const mode = String(getConfig()?.gitProvider || 'auto').toLowerCase()
       const providersToSync = []
       if (mode === 'github') {
@@ -562,18 +538,15 @@ export function apply(ctx, config) {
       }
       const out = await syncAll({ gitea: git, store, logger: ctx.logger })
       const tidied = archiveOverdue({ store, config: getConfig() })
-      // Отложенные отправки уходят той же волной: отдельный таймер ради них
-      // означал бы второй источник обращений к Gitea без всякой пользы.
+      // Outbox flushes run in the same cycle to minimize redundant Gitea API calls.
       const pushed = await outbox.flush()
-      // Беда подхвата — такая же слепота доски, как беда сверки: задачи не
-      // приезжают, а человеку об этом никто не говорит.
+      // Intake errors are reported in sync telemetry to keep failures visible.
       syncState.finished(out.problem === undefined && taken.problem !== undefined
         ? { ...out, problem: taken.problem }
         : out)
       return { ...out, pushed, taken, tidied }
     } catch (error) {
-      // Сверка не начиналась вовсе — тоже беда, и своя: так выглядит
-      // неразрешённый токен или отсутствующий клиент Gitea.
+      // Sync failure to start represents missing client or unconfigured credentials.
       syncState.failedToStart('sync', error?.message)
       throw error
     } finally {
@@ -620,17 +593,14 @@ export function apply(ctx, config) {
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: '/dsh-kanban/presets',
-    // Обе службы необязательны: развёртывание может не собирать ни профили,
-    // ни уровни доступа. Пустой список — не поломка, а «выбирать не из чего»,
-    // и браузер просто не рисует поле.
+    // Both services are optional in minimal environments. Empty lists render gracefully.
     handler: async (req, res) => {
       const presets = ctx.get('agentPresets')
       const permissions = ctx.get('permissionPresets')
       let agentPresets = []
       try {
         const rows = presets === undefined ? [] : await presets.list()
-        // Сломанный профиль остаётся в списке ядра, но выбрать его нельзя:
-        // сессия на нём не соберётся, а отказ прилетит уже после запуска.
+        // Filter out invalid presets that would fail session creation.
         agentPresets = rows.filter((row) => row?.broken === undefined).map((row) => ({
           id: row.id, name: row.name || row.id, description: row.description,
         }))
@@ -767,9 +737,7 @@ export function apply(ctx, config) {
     },
   }), 'dsh-kanban: gitea webhook')
 
-  // Инструмент для агента. По умолчанию ВЫКЛЮЧЕН: скилл воркфлоу пока
-  // запрещает этому CLI трогать канбан, и включить инструмент раньше правки
-  // скилла — значит толкать агента на нарушение.
+  // Agent tool definition. Default disabled; workflow skills explicitly enable it.
   ctx.effect(() => {
     let unregister
     const arm = () => {
@@ -779,8 +747,7 @@ export function apply(ctx, config) {
       unregister = registerBoardTool()
     }
 
-    // Один выключатель на оба инструмента доски: разделять их значило бы
-    // множить настройки ради разницы, которой человек не почувствует.
+    // Single setting switch controls both board tools.
     const registerBoardTool = () => {
       const off = [
         ctx.tools.register(defineTool(boardMoveDefinition({ store, config: getConfig }))),
@@ -801,8 +768,7 @@ export function apply(ctx, config) {
   }, 'dsh-kanban: board tool')
 
   /**
-   * Состояние живого агента сессии либо `undefined`, если агента нет.
-   * Отказ реестра на незнакомый идентификатор ловит сборка доски.
+   * Return active agent state or undefined if session is inactive.
    */
   const liveOf = (sessionId) => ctx.agents.get(sessionId)?.status
 
@@ -819,27 +785,15 @@ export function apply(ctx, config) {
         repo: url.searchParams.get('repo') || undefined,
         liveOf,
         sync: syncState.snapshot(),
-        // Фактический корень проектов едет с доской: браузер показывает его в
-        // окне запуска, когда человек не задал корень настройкой, — иначе
-        // сессия молча поднимается в рабочей папке харнесса.
+        // Resolved project root passed with board payload for session launch modal.
         projectRoot: rootOf(getConfig()),
       }))
     },
   }), 'dsh-kanban: board route')
 
-  // Снимок доски — ОДИН ресурс с двумя действиями, а не две ручки.
-  //
-  // Прежде выгрузка звалась `/export`, а загрузка занимала `/import` — тот
-  // самый путь, на котором с первого дня живёт импорт issue из Gitea. Два
-  // обработчика на одном пути означают, что один из них не отвечает вовсе, и
-  // какой именно — решает порядок регистрации, а не мы.
+  // Snapshot endpoint handles both export and import.
   /**
-   * Кто мы для Gitea, с памятью на время работы.
-   *
-   * Логин нужен и «взять себе», и запуску работы. Спрашивать его у Gitea
-   * каждый раз значит добавить в путь запуска ещё одну сеть, которая может не
-   * ответить; поэтому спрашиваем один раз и помним. Не ответила — работаем без
-   * назначения, а не отказываем в запуске.
+   * Cached identity for Gitea client to avoid redundant API lookups on task claim.
    */
   let knownLogin
   const whoAmI = async () => {
@@ -870,8 +824,7 @@ export function apply(ctx, config) {
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: '/dsh-kanban/whoami',
-    // Пустой логин — законный ответ: Gitea может быть не настроен или не
-    // отвечать. Браузер по нему просто не рисует «Мои», а не показывает ноль.
+    // Empty login indicates unconfigured or unreachable Gitea; client omits "Mine" filter.
     handler: async (req, res) => {
       if (req.method !== 'GET') { writeJson(res, 405, { error: 'method-not-allowed' }); return }
       reply(res, { login: await whoAmI() })
@@ -903,7 +856,7 @@ export function apply(ctx, config) {
     },
   }), 'dsh-kanban: sse events stream')
 
-  // Очистка SSE-клиентов и heartbeat таймера при выгрузке плагина (#282)
+  // Clean up SSE client connections and heartbeat timer on plugin disposal (#282)
   if (typeof ctx.on === 'function') {
     ctx.on('dispose', () => {
       eventHub.closeAll()
@@ -944,14 +897,13 @@ export function apply(ctx, config) {
   }), 'dsh-kanban: board snapshot')
 
   ctx.effect(() => ctx.webServer.register({
-    // Префикс регистрируется БЕЗ завершающего слэша: со слэшем сопоставление
-    // сводится к равенству пути, и всё, что глубже, уходит в статику.
+    // Prefix registered without trailing slash for sub-path routing.
     kind: 'prefix',
     path: '/dsh-kanban/task',
     handler: async (req, res) => {
       const pathname = urlOf(req).pathname
 
-      // Сам путь без идентификатора — создание своей задачи.
+      // Path without ID handles local task creation.
       if (pathname === '/dsh-kanban/task' || pathname === '/dsh-kanban/task/') {
         if (req.method !== 'POST') { writeJson(res, 405, { error: 'method-not-allowed' }); return }
         if (!isTrustedRequest(req)) { writeJson(res, 403, { error: 'cross-site' }); return }
@@ -970,8 +922,7 @@ export function apply(ctx, config) {
       if (req.method === 'GET' && action === 'log') { reply(res, taskLog({ store, id })); return }
       if (req.method === 'GET' && action === 'body') { reply(res, taskBody({ store, id })); return }
 
-      // Заготовку сообщения отдаём отсюда, а не собираем второй раз в браузере:
-      // иначе шаблон окажется в двух местах и однажды разойдётся.
+      // Generate start prompt on server for template consistency.
       if (req.method === 'GET' && action === 'message') {
         const task = store.getTask(id)
         if (task === undefined) { writeJson(res, 404, { error: 'task-not-found' }); return }
@@ -980,8 +931,7 @@ export function apply(ctx, config) {
       }
       if (!isTrustedRequest(req)) { writeJson(res, 403, { error: 'cross-site' }); return }
       if (req.method === 'DELETE' && action === undefined) { reply(res, deleteTask({ store, id })); return }
-      // Правка полей карточки: title, body, метки, приоритет. Приоритет —
-      // локальное свойство доски, в Gitea не пишется (updateTask это знает).
+      // Card fields update: title, body, labels, priority. Priority is board-local.
       if (req.method === 'POST' && action === 'update') {
         try {
           const input = await readBody(req)
@@ -1057,8 +1007,7 @@ export function apply(ctx, config) {
             config: getConfig(),
             provider: picked.provider,
             model: picked.model,
-            // Идентификатор мнётся ЛЕНИВО: при продолжении новая сессия не
-            // поднимается вовсе, и заранее занятое имя осталось бы висеть.
+            // Mint session ID lazily to avoid dangling IDs on resume.
             mintSessionId: () => SessionId(`kanban-${id}-${randomUUID()}`),
             createMessage: createUserMessage,
             logger: ctx.logger,
@@ -1073,8 +1022,7 @@ export function apply(ctx, config) {
           reply(res, started)
         } catch (error) {
           ctx.logger?.warn?.(`dsh-kanban: task launch failed: ${error?.message}`)
-          // Отказ по уровню доступа называется своим именем: «не удалось» на
-          // месте «сессия пошла бы с большими правами» — это молчание.
+          // Explicit permission errors are returned with status and key.
           writeJson(res, error?.status ?? 500, { error: error?.key ?? error?.message ?? 'start-failed' })
         }
         return
@@ -1083,13 +1031,7 @@ export function apply(ctx, config) {
       try {
         const input = await readBody(req)
         if (req.method === 'POST' && action === 'move') {
-          // Ручной перенос — КОМАНДА агенту, а не запись о состоянии.
-          // Автоматика (сверка, инструмент, жизненный цикл) сюда не приходит:
-          // она двигает карточку мимо этого маршрута.
-          //
-          // Команду отдаём ДО переноса: остановка должна случиться раньше, чем
-          // доска объявит работу прекращённой, а её исход становится
-          // пояснением к единственному переходу в журнале.
+          // Manual move dispatches stop command to agent prior to updating card column.
           const was = store.getTask(id)
           const acted = was !== undefined && input.column !== was.column
             ? dispatchMove({
@@ -1259,8 +1201,7 @@ export function apply(ctx, config) {
               store.updateTaskRun(task.id, latestRun.id, { endedAt: Date.now(), result: 'cancelled' })
             }
             syncPower()
-            // Остановка — событие, и в журнале ей место наравне с переносом:
-            // иначе прерванная работа выглядит просто оборвавшейся сама.
+            // Stop event recorded in transition history.
             store.addTransition({
               taskId: task.id, fromCol: task.column, toCol: task.column,
               source: 'manual', detail: STOP_DETAIL.stopped,
@@ -1272,8 +1213,7 @@ export function apply(ctx, config) {
         if (req.method === 'POST' && action === 'assign') {
           const was = store.getTask(id)
           if (was === undefined) { writeJson(res, 404, { error: 'task-not-found' }); return }
-          // Пустой логин снимает назначение; слово «me» просит того, чьим
-          // токеном ходит доска: своего понятия пользователя у харнесса нет.
+          // Empty login unassigns; 'me' resolves authenticated token identity.
           let login = typeof input.login === 'string' ? input.login.trim() : ''
           if (login === 'me') {
             login = await whoAmI()
@@ -1281,8 +1221,7 @@ export function apply(ctx, config) {
           }
           const out = assignTask({ store, id, login })
           if (out.task !== undefined && config.pushToGitea !== false) {
-            // В Gitea уходит очередью: доска не ждёт сеть и работает, когда
-            // Gitea лежит.
+            // Queue assignment update to outbox for offline resilience.
             outbox.push(id, planAssign(out.task, login))
           }
           reply(res, out)
@@ -1323,9 +1262,7 @@ export function apply(ctx, config) {
     },
   }), 'dsh-kanban: task routes')
 
-  // Готовность Gitea проверяется на каждом запросе, а не при загрузке: адрес и
-  // учётная запись правятся в карточке настроек на ходу, и маршруты обязаны
-  // внятно объяснять причину, а не отвечать 404.
+  // Check Gitea readiness per request to handle dynamically updated credentials.
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: '/dsh-kanban/gitea/repos',
@@ -1371,9 +1308,7 @@ export function apply(ctx, config) {
     },
   }), 'dsh-kanban: issue import')
 
-  // Провайдеры отдаются сразу, модели — только для запрошенного провайдера:
-  // перечень моделей провайдер отдаёт по сети, и опрашивать все разом ради
-  // одного выпадающего списка незачем.
+  // Providers returned immediately; models queried on-demand for selected provider.
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: '/dsh-kanban/models',
@@ -1396,8 +1331,7 @@ export function apply(ctx, config) {
           models: (rows ?? []).map((m) => ({ id: m.id, name: m.name ?? m.id })),
         })
       } catch {
-        // Провайдер может быть не настроен или недоступен: это не поломка
-        // доски, а пустой список с сохранённым выбором провайдера.
+        // Provider errors return empty model list while preserving selected provider.
         writeJson(res, 200, { current, providers, models: [] })
       }
     },

package/lib/intake.js

@@ -1,11 +1,9 @@
-// Архив выполненного и подхват новых задач из Gitea.
+// Archival of completed tasks and ingestion of new tasks from Gitea.
 //
-// Две противоположные заботы в одном месте: одна убирает с доски отработавшее,
-// другая приносит новое. Обе решают, ЧТО должно быть на доске, и держать их
-// рядом дешевле, чем искать по разным углам, почему карточка появилась или
-// пропала.
+// Two complementary concerns in one module: one clears finished tasks from board,
+// the other ingests new ones. Both govern WHAT belongs on the board.
 
-/** Разбор списка репозиториев из настройки: через запятую, пробелы не в счёт. */
+/** Parse repository list from config: comma-separated, ignoring whitespace. */
 export function parseWatchList(value) {
   return String(value ?? '')
     .split(',')
@@ -14,11 +12,9 @@ export function parseWatchList(value) {
 }
 
 /**
- * Репозитории, за которыми следим, если их назвали поимённо.
+ * Repositories watched explicitly when named.
  *
- * Пустой список означает «все», и разбирается это не здесь, а в проходе
- * подхвата: там есть Gitea, у которого можно спросить, какие репозитории вообще
- * существуют.
+ * Empty list means 'all', handled in intake pass where Gitea query lists all repos.
  *
  * @returns {Array<{owner: string, repo: string}>}
  */
@@ -26,8 +22,7 @@ export function watchedRepos({ config, owner }) {
   const out = []
   const seen = new Set()
   for (const name of parseWatchList(config?.watchRepos)) {
-    // Имя допускается и полное, и короткое: `владелец/репо` либо просто
-    // `репо` — тогда владелец берётся общий.
+    // Name can be full or short: `owner/repo` or just `repo` using default owner.
     const at = name.indexOf('/')
     const pair = at > 0
       ? { owner: name.slice(0, at), repo: name.slice(at + 1) }
@@ -42,16 +37,15 @@ export function watchedRepos({ config, owner }) {
 }
 
 /**
- * Стоит ли заводить карточку под этот issue.
+ * Whether to create a card for this issue.
  *
- * @returns {{take: boolean, why: string}} `why` называет причину отказа —
- *   иначе «почему этой задачи нет на доске» превращается в гадание.
+ * @returns {{take: boolean, why: string}} `why` states reason on rejection.
  */
 export function shouldTake({ store, owner, repo, issue }) {
   const number = issue?.number
   if (typeof number !== 'number') return { take: false, why: 'missing-number' }
-  // Pull request в Gitea — тоже issue, но работой на доске он не является:
-  // он ход работы, а не сама работа.
+  // Pull request in Gitea is also an issue, but not a standalone board card:
+  // it reflects execution progress, not the task definition.
   if (issue?.pull_request !== undefined && issue?.pull_request !== null) {
     return { take: false, why: 'pull-request-ignored' }
   }
@@ -66,13 +60,12 @@ export function shouldTake({ store, owner, repo, issue }) {
 }
 
 /**
- * Пора ли задаче в архив.
+ * Whether task is ready for archival.
  *
- * Архивируем ТОЛЬКО из `done`. Задача, застрявшая в ревью на месяц, — это
- * сигнал, а не мусор, и прятать её нельзя.
+ * Archived ONLY from `done`. A task stuck in review for a month is an alert,
+ * not clutter, and must not be hidden.
  *
- * Ноль в настройке отключает самоархивацию: это осознанное «не убирать»,
- * а не пропущенное значение.
+ * Zero in settings disables auto-archival.
  */
 export function archiveBefore({ now, afterDays }) {
   const days = Number(afterDays)
@@ -81,11 +74,10 @@ export function archiveBefore({ now, afterDays }) {
 }
 
 /**
- * Следим ли за этим репозиторием.
+ * Whether given repository is watched.
  *
- * Событие из репозитория вне списка подхвата не заслуживает: по таймеру мы
- * туда не ходим, и через вебхук ходить тоже не должны — иначе список перестаёт
- * что-либо решать.
+ * Events outside watched list are ignored: timer does not poll them,
+ * so webhooks should not process them either.
  */
 export function isWatched({ config, owner, defaultOwner, repo }) {
   return watchedRepos({ config, owner: defaultOwner }).some(