@andypai/agent-kanban 0.6.0 → 0.6.2

package/README.md

@@ -62,23 +62,25 @@ Running `kanban` with no arguments is equivalent to `kanban board view`.
 
 All operations route through a provider backend. Set `KANBAN_PROVIDER` to choose one.
 
-| Variable                     | Default       | Description                                                              |
-| ---------------------------- | ------------- | ------------------------------------------------------------------------ |
-| `KANBAN_PROVIDER`            | `local`       | `local`, `linear`, or `jira`                                             |
-| `KANBAN_STORAGE`             | `sqlite`      | `sqlite` or `postgres`                                                   |
-| `KANBAN_DATABASE_URL`        | —             | Required when `KANBAN_STORAGE=postgres`                                  |
-| `KANBAN_DB_PATH`             | auto-resolved | SQLite database path                                                     |
-| `KANBAN_DEFAULT_COLUMNS`     | —             | Optional bootstrap column names for local/Postgres caches                |
-| `KANBAN_DEFAULT_TASK_COLUMN` | —             | Optional created-task column override for local/Postgres caches          |
-| `KANBAN_SYNC_INTERVAL_MS`    | `30000`       | Polling sync interval for remote providers; integer milliseconds >= 1000 |
-| `LINEAR_API_KEY`             | —             | Required when `KANBAN_PROVIDER=linear`                                   |
-| `LINEAR_TEAM_ID`             | —             | Required when `KANBAN_PROVIDER=linear`                                   |
-| `JIRA_BASE_URL`              | —             | Required when `KANBAN_PROVIDER=jira` (e.g. `https://acme.atlassian.net`) |
-| `JIRA_EMAIL`                 | —             | Required when `KANBAN_PROVIDER=jira` (Atlassian account email)           |
-| `JIRA_API_TOKEN`             | —             | Required when `KANBAN_PROVIDER=jira` (Atlassian API token)               |
-| `JIRA_PROJECT_KEY`           | —             | Required when `KANBAN_PROVIDER=jira` (e.g. `ENG`)                        |
-| `JIRA_BOARD_ID`              | —             | Optional when `KANBAN_PROVIDER=jira` (Agile board id for column order)   |
-| `JIRA_ISSUE_TYPE`            | `Task`        | Optional when `KANBAN_PROVIDER=jira` (default issue type for new tasks)  |
+| Variable                     | Default       | Description                                                                                 |
+| ---------------------------- | ------------- | ------------------------------------------------------------------------------------------- |
+| `KANBAN_PROVIDER`            | `local`       | `local`, `linear`, or `jira`                                                                |
+| `KANBAN_STORAGE`             | `sqlite`      | `sqlite` or `postgres`                                                                      |
+| `KANBAN_DATABASE_URL`        | —             | Required when `KANBAN_STORAGE=postgres`                                                     |
+| `KANBAN_DB_PATH`             | auto-resolved | SQLite database path                                                                        |
+| `KANBAN_DEFAULT_COLUMNS`     | —             | Optional bootstrap column names for local/Postgres caches                                   |
+| `KANBAN_DEFAULT_TASK_COLUMN` | —             | Optional created-task column override for local/Postgres caches                             |
+| `KANBAN_SYNC_INTERVAL_MS`    | `30000`       | Polling sync interval for remote providers; integer milliseconds >= 1000                    |
+| `KANBAN_API_TOKEN`           | —             | When set, `kanban serve` requires `Authorization: Bearer <token>` (required for `--tunnel`) |
+| `KANBAN_ALLOWED_ORIGIN`      | —             | Allowed CORS origin for `kanban serve`; unset means same-origin only                        |
+| `LINEAR_API_KEY`             | —             | Required when `KANBAN_PROVIDER=linear`                                                      |
+| `LINEAR_TEAM_ID`             | —             | Required when `KANBAN_PROVIDER=linear`                                                      |
+| `JIRA_BASE_URL`              | —             | Required when `KANBAN_PROVIDER=jira` (e.g. `https://acme.atlassian.net`)                    |
+| `JIRA_EMAIL`                 | —             | Required when `KANBAN_PROVIDER=jira` (Atlassian account email)                              |
+| `JIRA_API_TOKEN`             | —             | Required when `KANBAN_PROVIDER=jira` (Atlassian API token)                                  |
+| `JIRA_PROJECT_KEY`           | —             | Required when `KANBAN_PROVIDER=jira` (e.g. `ENG`)                                           |
+| `JIRA_BOARD_ID`              | —             | Optional when `KANBAN_PROVIDER=jira` (Agile board id for column order)                      |
+| `JIRA_ISSUE_TYPE`            | `Task`        | Optional when `KANBAN_PROVIDER=jira` (default issue type for new tasks)                     |
 
 When `KANBAN_STORAGE=sqlite` and `KANBAN_DB_PATH` is unset, the local provider
 resolves the database in this order:
@@ -252,9 +254,30 @@ Default columns: `recurring`, `backlog`, `in-progress`, `review`, `done`.
 kanban serve            # default port 3000
 kanban serve --port 8080
 kanban serve --sync-interval-ms 300000
-kanban serve --tunnel   # optional public URL for webhook testing
+kanban serve --token "$(openssl rand -hex 32)"   # require an API token
+kanban serve --tunnel --token "$SECRET"           # public URL (token required)
 ```
 
+#### Authentication & CORS
+
+By default `serve` binds locally and leaves the API open for backward
+compatibility. To require authentication, set a token via `--token` or the
+`KANBAN_API_TOKEN` env var. When a token is set:
+
+- All `/api/*` routes (reads and mutations) and the `/ws` upgrade require
+  `Authorization: Bearer <token>`. The WebSocket, which can't send headers,
+  accepts `?token=<token>` instead.
+- `/api/health` stays public (liveness probe).
+- `/api/webhooks/*` are **not** covered by this token — they authenticate with
+  the provider webhook secret (e.g. `JIRA_WEBHOOK_SECRET`).
+- The bundled UI picks the token up once from `?token=` / `#token=` and stores
+  it in `localStorage`, so you can open `https://<host>/?token=<token>`.
+
+`--tunnel` exposes the dashboard publicly, so it **refuses to start without a
+token**. CORS is off by default (same-origin); set `KANBAN_ALLOWED_ORIGIN` (or
+`--allowed-origin`) to allow a specific cross-origin browser client. CORS is
+origin hygiene, not an auth control — the token is the security boundary.
+
 ### mcp
 
 ```bash
@@ -301,7 +324,7 @@ In Linear mode the dashboard hides unsupported actions and shows Linear issue id
 Starts a Bun HTTP server with:
 
 - **REST API** at `/api/*` — board, tasks, task comments, bootstrap/provider metadata, activity, metrics, config, and webhook endpoints
-- **WebSocket** at `/ws` — push notifications on board mutations (clients receive `task:upsert`, `task:delete`, or a fallback `refresh` event)
+- **WebSocket** at `/ws` — push notifications on board mutations (clients receive `task:upsert` with `{ task, columnId }`, `task:delete` with `{ id }`, or a fallback `refresh` event)
 - **Static UI** served from `ui/dist/` (build with `bun run build:ui` or `bun run ui:build`)
 - **Health check** at `/api/health` — cheap process liveness only
 - **Readiness check** at `/api/ready` — reports whether the cache has warmed at least once

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andypai/agent-kanban",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Agent-friendly kanban board CLI. Manage tasks via bash commands, parse structured JSON output.",
   "homepage": "https://github.com/abpai/agent-kanban#readme",
   "repository": {
@@ -42,7 +42,8 @@
     "lint": "bunx eslint .",
     "format": "bunx prettier --write .",
     "typecheck": "bunx tsc --noEmit",
-    "check": "bun run lint && bun run typecheck",
+    "ui:typecheck": "cd ui && bunx tsc --noEmit",
+    "check": "bun run lint && bun run typecheck && bun run ui:typecheck",
     "test": "bun test",
     "test:watch": "bun test --watch",
     "seed:test": "bun --env-file=.env.test scripts/seed-test-db.ts",

package/src/__tests__/activity.test.ts

@@ -90,6 +90,18 @@ describe('activity logging', () => {
     expect(moves).toHaveLength(2)
   })
 
+  test('bulkMoveAll to the same column does not add moved activity or tracking rows', () => {
+    const task = addTask(db, 'A', { column: 'recurring' })
+
+    bulkMoveAll(db, 'recurring', 'recurring')
+
+    const activities = listActivity(db)
+    expect(activities.filter((a) => a.action === 'moved')).toHaveLength(0)
+    const entries = getColumnTimeEntries(task.id)
+    expect(entries).toHaveLength(1)
+    expect(entries[0]!.exited_at).toBeNull()
+  })
+
   test('bulkClearDone logs deleted activity for each task', () => {
     addTask(db, 'Done A', { column: 'done' })
     addTask(db, 'Done B', { column: 'done' })

package/src/__tests__/api.test.ts

@@ -132,7 +132,8 @@ describe('handleRequest', () => {
     expect(result.event?.type).toBe('task:upsert')
     if (result.event?.type !== 'task:upsert') throw new Error('unreachable')
     expect(result.event.task.title).toBe('Optimistic')
-    expect(result.event.columnName.toLowerCase()).toBe('backlog')
+    expect('columnId' in result.event).toBe(true)
+    expect('columnName' in result.event).toBe(false)
   })
 
   test('emits task:upsert event on move across columns', async () => {
@@ -148,7 +149,8 @@ describe('handleRequest', () => {
     expect(result.event?.type).toBe('task:upsert')
     if (result.event?.type !== 'task:upsert') throw new Error('unreachable')
     expect(result.event.task.id).toBe(task.id)
-    expect(result.event.columnName.toLowerCase()).toBe('in-progress')
+    expect('columnId' in result.event).toBe(true)
+    expect('columnName' in result.event).toBe(false)
   })
 
   test('emits task:delete event on delete', async () => {

package/src/__tests__/board-utils.test.ts

@@ -95,11 +95,24 @@ describe('boardUtils', () => {
     const nextBoard = upsertTaskInColumn(
       board,
       makeTask({ id: 't-1', title: 'First edited', column_id: 'c-backlog', position: 0 }),
-      'backlog',
+      'c-backlog',
     )
 
-    expect(nextBoard.columns[0]!.tasks.map((task) => task.id)).toEqual(['t-1', 'tmp-1', 't-2'])
-    expect(nextBoard.columns[0]!.tasks[0]!.title).toBe('First edited')
+    expect(nextBoard).not.toBeNull()
+    expect(nextBoard!.columns[0]!.tasks.map((task) => task.id)).toEqual(['t-1', 'tmp-1', 't-2'])
+    expect(nextBoard!.columns[0]!.tasks[0]!.title).toBe('First edited')
+  })
+
+  test('upsertTaskInColumn returns null when the target column is not on the board', () => {
+    const board = makeBoard()
+
+    const nextBoard = upsertTaskInColumn(
+      board,
+      makeTask({ id: 't-9', title: 'Unknown column', column_id: 'status:10001', position: 0 }),
+      'status:10001',
+    )
+
+    expect(nextBoard).toBeNull()
   })
 
   test('moveTaskInBoard accepts a column id when column names repeat', () => {

package/src/__tests__/column-roles.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test'
+import { selectDoneColumnIds, selectInProgressColumnIds } from '../column-roles'
+
+const cols = (names: string[]) => names.map((name, i) => ({ id: `c${i}`, name, position: i }))
+
+describe('selectDoneColumnIds', () => {
+  test('matches done synonyms regardless of case/separators', () => {
+    const columns = cols(['Backlog', 'In Progress', 'Done'])
+    expect(selectDoneColumnIds(columns)).toEqual(['c2'])
+    expect(selectDoneColumnIds(cols(['todo', 'completed']))).toEqual(['c1'])
+    expect(selectDoneColumnIds(cols(['Open', 'Merged']))).toEqual(['c1'])
+  })
+
+  test('falls back to the terminal column when no name matches', () => {
+    // Custom names with no recognizable "done" -> last column by position.
+    expect(selectDoneColumnIds(cols(['Todo', 'Doing', 'Shipping Soon']))).toEqual(['c2'])
+  })
+
+  test('returns empty for no columns', () => {
+    expect(selectDoneColumnIds([])).toEqual([])
+  })
+})
+
+describe('selectInProgressColumnIds', () => {
+  test('matches in-progress synonyms regardless of case/separators', () => {
+    expect(selectInProgressColumnIds(cols(['Todo', 'In Progress', 'Done']))).toEqual(['c1'])
+    expect(selectInProgressColumnIds(cols(['in-progress']))).toEqual(['c0'])
+    expect(selectInProgressColumnIds(cols(['WIP', 'Doing']))).toEqual(['c0', 'c1'])
+  })
+
+  test('returns empty when nothing matches (no positional fallback)', () => {
+    expect(selectInProgressColumnIds(cols(['Backlog', 'Done']))).toEqual([])
+  })
+})

package/src/__tests__/commands/board.test.ts

@@ -17,6 +17,13 @@ describe('boardInit', () => {
     expect(result.ok).toBe(true)
   })
 
+  test('initializes when the schema exists without seeded columns', () => {
+    initSchema(db)
+    const result = boardInit(db)
+    expect(result.ok).toBe(true)
+    expect(getBoardView(db).columns).toHaveLength(5)
+  })
+
   test('throws if already initialized', () => {
     initSchema(db)
     seedDefaultColumns(db)

package/src/__tests__/conflict.test.ts

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, test } from 'bun:test'
 import { Database } from 'bun:sqlite'
-import { initSchema, seedDefaultColumns } from '../db'
+import { initSchema, seedDefaultColumns, resolveColumn } from '../db'
 import { LocalProvider } from '../providers/local'
 import { ErrorCode, KanbanError } from '../errors'
 
@@ -61,4 +61,14 @@ describe('local provider conflict detection', () => {
     const v2 = await provider.updateTask(created.id, { title: 'b' })
     expect(v2.version).toBe('2')
   })
+
+  // moveTask(id, column) intentionally has no expectedVersion parameter, so moves
+  // are last-write-wins by design (drag-and-drop has no loaded version to check).
+  // This locks in that contract so a move is never rejected for a stale version.
+  test('moveTask has no expectedVersion contract (move after an update still succeeds)', async () => {
+    const created = await provider.createTask({ title: 'T1', column: 'backlog' })
+    await provider.updateTask(created.id, { title: 'bumped' })
+    const moved = await provider.moveTask(created.id, 'in-progress')
+    expect(moved.column_id).toBe(resolveColumn(db, 'in-progress').id)
+  })
 })

package/src/__tests__/db.test.ts

@@ -25,6 +25,9 @@ import {
   bulkClearDone,
   resetBoard,
   migrateSchema,
+  addComment,
+  updateComment,
+  listComments,
 } from '../db'
 import { KanbanError } from '../errors'
 
@@ -79,6 +82,27 @@ describe('schema', () => {
     expect(listColumns(db)).toHaveLength(5)
   })
 
+  test('seedDefaultColumns honors provided column names (KANBAN_DEFAULT_COLUMNS)', () => {
+    const fresh = new Database(':memory:')
+    initSchema(fresh)
+    seedDefaultColumns(fresh, ['Todo', 'In Progress', 'Done'])
+    const cols = listColumns(fresh)
+    expect(cols.map((c) => c.name)).toEqual(['Todo', 'In Progress', 'Done'])
+    expect(cols.map((c) => c.position)).toEqual([0, 1, 2])
+  })
+
+  test('seedDefaultColumns falls back to defaults for an empty list', () => {
+    const fresh = new Database(':memory:')
+    initSchema(fresh)
+    seedDefaultColumns(fresh, [])
+    expect(listColumns(fresh)).toHaveLength(5)
+  })
+
+  test('resetBoard reseeds with provided column names', () => {
+    resetBoard(db, ['Alpha', 'Beta'])
+    expect(listColumns(db).map((c) => c.name)).toEqual(['Alpha', 'Beta'])
+  })
+
   test('migrateSchema adds project and labels columns to legacy tasks table', () => {
     const legacy = new Database(':memory:')
     legacy.run(
@@ -308,6 +332,16 @@ describe('bulk operations', () => {
     expect(listTasks(db, { column: 'recurring' })).toHaveLength(0)
   })
 
+  test('bulkMoveAll to the same column is a no-op', () => {
+    const a = addTask(db, 'A', { column: 'recurring' })
+    const b = addTask(db, 'B', { column: 'recurring' })
+
+    const result = bulkMoveAll(db, 'recurring', 'recurring')
+
+    expect(result.moved).toBe(0)
+    expect(listTasks(db, { column: 'recurring' }).map((task) => task.id)).toEqual([a.id, b.id])
+  })
+
   test('bulkClearDone removes tasks in done column', () => {
     addTask(db, 'Finished', { column: 'done' })
     addTask(db, 'Also done', { column: 'done' })
@@ -326,3 +360,39 @@ describe('resetBoard', () => {
     expect(listTasks(db)).toHaveLength(0)
   })
 })
+
+describe('comment atomicity', () => {
+  const countActivity = (taskId: string): number =>
+    (
+      db
+        .query('SELECT COUNT(*) AS count FROM activity_log WHERE task_id = $task_id')
+        .get({ $task_id: taskId }) as { count: number }
+    ).count
+
+  test('addComment writes the comment and its activity entry together', () => {
+    const task = addTask(db, 'Has comments')
+    const before = countActivity(task.id)
+    addComment(db, task.id, 'hello')
+    expect(listComments(db, task.id)).toHaveLength(1)
+    expect(countActivity(task.id)).toBe(before + 1)
+  })
+
+  test('addComment rolls back the comment if the activity write fails', () => {
+    const task = addTask(db, 'Atomic add')
+    // Force the second write (logActivity) to fail mid-transaction.
+    db.run('DROP TABLE activity_log')
+    expect(() => addComment(db, task.id, 'orphan?')).toThrow()
+    // The comment INSERT must not survive the failed transaction.
+    expect(listComments(db, task.id)).toHaveLength(0)
+  })
+
+  test('updateComment rolls back the body change if the activity write fails', () => {
+    const task = addTask(db, 'Atomic update')
+    const comment = addComment(db, task.id, 'original')
+    db.run('DROP TABLE activity_log')
+    expect(() => updateComment(db, task.id, comment.id, 'changed')).toThrow()
+    // The body must remain unchanged after the rolled-back transaction.
+    const [persisted] = listComments(db, task.id)
+    expect(persisted?.body).toBe('original')
+  })
+})

package/src/__tests__/index.test.ts

@@ -47,7 +47,11 @@ async function expectKanbanError(
 describe('parseServeArgs', () => {
   test('defaults: no tunnel, port from PORT env or 3000', () => {
     const prev = process.env['PORT']
+    const prevToken = process.env['KANBAN_API_TOKEN']
+    const prevOrigin = process.env['KANBAN_ALLOWED_ORIGIN']
     delete process.env['PORT']
+    delete process.env['KANBAN_API_TOKEN']
+    delete process.env['KANBAN_ALLOWED_ORIGIN']
     try {
       expect(parseServeArgs(['serve'])).toEqual({ db: undefined, port: 3000, tunnel: false })
       process.env['PORT'] = '4001'
@@ -55,6 +59,10 @@ describe('parseServeArgs', () => {
     } finally {
       if (prev === undefined) delete process.env['PORT']
       else process.env['PORT'] = prev
+      if (prevToken === undefined) delete process.env['KANBAN_API_TOKEN']
+      else process.env['KANBAN_API_TOKEN'] = prevToken
+      if (prevOrigin === undefined) delete process.env['KANBAN_ALLOWED_ORIGIN']
+      else process.env['KANBAN_ALLOWED_ORIGIN'] = prevOrigin
     }
   })
 
@@ -82,9 +90,56 @@ describe('parseServeArgs', () => {
       expect(() => parseServeArgs(['serve', '--sync-interval-ms', raw])).toThrow(KanbanError)
     }
   })
+
+  test('--token / --allowed-origin flags and env are parsed; flags win over env', () => {
+    const prevToken = process.env['KANBAN_API_TOKEN']
+    const prevOrigin = process.env['KANBAN_ALLOWED_ORIGIN']
+    delete process.env['KANBAN_API_TOKEN']
+    delete process.env['KANBAN_ALLOWED_ORIGIN']
+    try {
+      const flags = parseServeArgs([
+        'serve',
+        '--token',
+        'flag-token',
+        '--allowed-origin',
+        'https://flag.example',
+      ])
+      expect(flags.authToken).toBe('flag-token')
+      expect(flags.allowedOrigin).toBe('https://flag.example')
+
+      process.env['KANBAN_API_TOKEN'] = 'env-token'
+      process.env['KANBAN_ALLOWED_ORIGIN'] = 'https://env.example'
+      expect(parseServeArgs(['serve']).authToken).toBe('env-token')
+      expect(parseServeArgs(['serve']).allowedOrigin).toBe('https://env.example')
+      // Flag overrides env.
+      expect(parseServeArgs(['serve', '--token', 'flag-token']).authToken).toBe('flag-token')
+    } finally {
+      if (prevToken === undefined) delete process.env['KANBAN_API_TOKEN']
+      else process.env['KANBAN_API_TOKEN'] = prevToken
+      if (prevOrigin === undefined) delete process.env['KANBAN_ALLOWED_ORIGIN']
+      else process.env['KANBAN_ALLOWED_ORIGIN'] = prevOrigin
+    }
+  })
 })
 
 describe('run', () => {
+  test('initializes a fresh board through the CLI path', async () => {
+    await withTempDb(async (dbPath) => {
+      const result = expectOk<{ message: string }>(await run(['--db', dbPath, 'board', 'init']))
+      expect(result.message).toContain('Board initialized')
+
+      const db = new Database(dbPath)
+      const columns = db.query('SELECT COUNT(*) as count FROM columns').get() as { count: number }
+      expect(columns.count).toBeGreaterThan(0)
+      db.close()
+
+      await expectKanbanError(
+        run(['--db', dbPath, 'board', 'init']),
+        ErrorCode.BOARD_ALREADY_INITIALIZED,
+      )
+    })
+  })
+
   test('applies schema migration before task commands', async () => {
     await withTempDb(async (dbPath) => {
       const legacy = new Database(dbPath)

package/src/__tests__/jira-cache.test.ts

@@ -62,6 +62,62 @@ describe('jira-cache', () => {
     expect(decodeColumnStatusIds(col)).toEqual(['10001', '10002', '10003'])
   })
 
+  test('catalog replace prune=false upserts without deleting obsolete rows', () => {
+    // Seed a full catalog (prune defaults to true → full replace).
+    replaceJiraColumns(db, [
+      { id: 'status:1', name: 'To Do', position: 0, statusIds: ['1'], source: 'status' },
+      { id: 'status:2', name: 'Done', position: 1, statusIds: ['2'], source: 'status' },
+    ])
+    replaceJiraPriorities(db, [
+      { id: 'p1', name: 'High' },
+      { id: 'p2', name: 'Low' },
+    ])
+    replaceJiraIssueTypes(db, [
+      { id: 't1', name: 'Bug' },
+      { id: 't2', name: 'Task' },
+    ])
+
+    // A delta sync (prune=false) carries a partial snapshot: it should upsert the
+    // rows it sees and leave the others in place (self-healing), not delete them.
+    replaceJiraColumns(
+      db,
+      [
+        {
+          id: 'status:1',
+          name: 'To Do (renamed)',
+          position: 0,
+          statusIds: ['1'],
+          source: 'status',
+        },
+      ],
+      false,
+    )
+    replaceJiraPriorities(db, [{ id: 'p1', name: 'Highest' }], false)
+    replaceJiraIssueTypes(db, [{ id: 't1', name: 'Defect' }], false)
+
+    const columns = getCachedColumns(db)
+    expect(columns.map((c) => c.id).sort()).toEqual(['status:1', 'status:2'])
+    expect(columns.find((c) => c.id === 'status:1')?.name).toBe('To Do (renamed)')
+
+    const { priorities, issueTypes } = getCachedConfig(db)
+    expect(priorities.map((p) => p.id).sort()).toEqual(['p1', 'p2'])
+    expect(priorities.find((p) => p.id === 'p1')?.name).toBe('Highest')
+    expect(issueTypes.map((t) => t.id).sort()).toEqual(['t1', 't2'])
+    expect(issueTypes.find((t) => t.id === 't1')?.name).toBe('Defect')
+  })
+
+  test('catalog replace prune=true (default) removes obsolete rows', () => {
+    replaceJiraColumns(db, [
+      { id: 'status:1', name: 'To Do', position: 0, statusIds: ['1'], source: 'status' },
+      { id: 'status:2', name: 'Done', position: 1, statusIds: ['2'], source: 'status' },
+    ])
+    // A full reconcile (prune=true) replaces the catalog: status:2 is gone.
+    replaceJiraColumns(db, [
+      { id: 'status:1', name: 'To Do', position: 0, statusIds: ['1'], source: 'status' },
+    ])
+    expect(getCachedColumns(db).map((c) => c.id)).toEqual(['status:1'])
+  })
+
   test('decodeColumnStatusIds handles 3-element array without ordering loss', () => {
     expect(decodeColumnStatusIds({ status_ids: JSON.stringify(['c', 'a', 'b']) })).toEqual([
       'c',

package/src/__tests__/jira-jql.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'bun:test'
+import { buildDeltaJql, assertSafeProjectKey, safeDeltaSince } from '../providers/jira-jql'
+import { KanbanError } from '../errors'
+
+describe('buildDeltaJql', () => {
+  test('preserves the existing query format for a full scan (null since)', () => {
+    expect(buildDeltaJql('ENG', null)).toBe(
+      'project = ENG AND updated >= "1970-01-01 00:00" ORDER BY updated ASC',
+    )
+  })
+
+  test('interpolates a valid ISO timestamp unchanged', () => {
+    expect(buildDeltaJql('ENG', '2026-01-05T00:00:00Z')).toBe(
+      'project = ENG AND updated >= "2026-01-05T00:00:00Z" ORDER BY updated ASC',
+    )
+  })
+
+  test('accepts the ISO offset form Jira returns in issue.fields.updated', () => {
+    expect(buildDeltaJql('ENG', '2026-06-08T12:34:56.789+0000')).toContain(
+      'updated >= "2026-06-08T12:34:56.789+0000"',
+    )
+  })
+
+  test('rejects an injection attempt in the since cursor and falls back to a full scan', () => {
+    const malicious = '2026-01-01" OR project = OTHER ORDER BY updated ASC -- '
+    expect(buildDeltaJql('ENG', malicious)).toBe(
+      'project = ENG AND updated >= "1970-01-01 00:00" ORDER BY updated ASC',
+    )
+  })
+
+  test('rejects an invalid project key', () => {
+    expect(() => buildDeltaJql('ENG" OR 1=1', null)).toThrow(KanbanError)
+    expect(() => assertSafeProjectKey('has space')).toThrow(KanbanError)
+    expect(assertSafeProjectKey('ENG')).toBe('ENG')
+  })
+})
+
+describe('safeDeltaSince', () => {
+  test('passes through valid cursors and null', () => {
+    expect(safeDeltaSince(null)).toBeNull()
+    expect(safeDeltaSince('2026-01-05T00:00:00Z')).toBe('2026-01-05T00:00:00Z')
+    expect(safeDeltaSince('1970-01-01 00:00')).toBe('1970-01-01 00:00')
+  })
+
+  test('nulls out an unsafe cursor so it is not carried forward or re-persisted', () => {
+    // A lexicographically-high injection value would otherwise survive the
+    // `issue.fields.updated > newestUpdatedAt` comparison and re-persist itself,
+    // trapping every future sync into a full scan.
+    expect(safeDeltaSince('9999" OR project = OTHER')).toBeNull()
+  })
+})

package/src/__tests__/jira-provider-read.test.ts

@@ -845,4 +845,54 @@ describe('JiraProvider read path', () => {
     saveTeamInfo(db, null)
     expect(loadTeamInfo(db)).toBeNull()
   })
+
+  // Regression: in server (background-managed) mode, request-path reads must serve
+  // the warm cache instead of blocking on a Jira sync — otherwise a stale-throttle
+  // read triggers a foreground network sync that can exceed the HTTP idle timeout
+  // (observed as /api/board ERR_EMPTY_RESPONSE).
+  const seedSyncedMeta = () =>
+    saveJiraSyncMeta(db, {
+      projectKey: 'ENG',
+      lastSyncAt: '2026-01-01T00:00:00.000Z',
+      lastFullSyncAt: '2026-01-01T00:00:00.000Z',
+      lastIssueUpdatedAt: '2026-01-01T00:00:00.000Z',
+    })
+  const wellPastThrottle = () => {
+    Date.now = () => Date.parse('2026-01-01T01:00:00.000Z') // +1h, throttle long expired
+  }
+
+  test('background-managed reads do NOT foreground-sync once the cache is warm', async () => {
+    const { provider, calls } = makeProvider(standardRoutes({}))
+    provider.setBackgroundManaged(true)
+    seedSyncedMeta()
+    wellPastThrottle()
+
+    await provider.listTasks()
+
+    expect(calls.some((c) => c.url.includes('/rest/api/3/search/jql'))).toBe(false)
+  })
+
+  test('non-managed reads still foreground-sync when the throttle has expired', async () => {
+    const { provider, calls } = makeProvider(standardRoutes({}))
+    // backgroundManaged left false (CLI / default)
+    seedSyncedMeta()
+    wellPastThrottle()
+
+    await provider.listTasks()
+
+    expect(calls.some((c) => c.url.includes('/rest/api/3/search/jql'))).toBe(true)
+  })
+
+  test('background warmer (syncCache) still syncs when background-managed', async () => {
+    const { provider, calls } = makeProvider(standardRoutes({}))
+    provider.setBackgroundManaged(true)
+    seedSyncedMeta()
+    wellPastThrottle()
+
+    // syncCache bypasses the managed read-path gate (viaWarmer), so the warmer
+    // keeps refreshing the cache even though plain reads would be suppressed.
+    await provider.syncCache()
+
+    expect(calls.some((c) => c.url.includes('/rest/api/3/search/jql'))).toBe(true)
+  })
 })

package/src/__tests__/mcp-server.test.ts

@@ -85,7 +85,7 @@ function startTrackerServer(
     url,
     async close() {
       await tracker.close()
-      httpServer.stop(true)
+      void httpServer.stop(true)
     },
   }
 }
@@ -246,7 +246,7 @@ describe('createTrackerMcpServer', () => {
         message: 'Tracker MCP server is closed',
       })
     } finally {
-      runtime.httpServer.stop(true)
+      void runtime.httpServer.stop(true)
     }
   })
 })