@andypai/agent-kanban 0.3.2 → 0.3.4

package/README.md

@@ -62,18 +62,19 @@ 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_DB_PATH`   | auto-resolved | SQLite database path                                                     |
-| `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_DB_PATH`          | auto-resolved | SQLite database path                                                     |
+| `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)  |
 
 Without `KANBAN_DB_PATH`, the local provider resolves the database in this order:
 
@@ -127,8 +128,8 @@ surface.
 
 Unsupported operations return error code `UNSUPPORTED_OPERATION` with exit code 1.
 
-Task comments are currently exposed through the REST API and dashboard task
-detail flows rather than dedicated `kanban comment ...` CLI commands.
+Task comments are exposed through the CLI, REST API, MCP, and dashboard task
+detail flows.
 
 In Linear and Jira modes, webhooks update the cache immediately when configured,
 and the normal poll loop still runs as a fallback so missed deliveries and
@@ -192,6 +193,14 @@ Default columns: `recurring`, `backlog`, `in-progress`, `review`, `done`.
 | `--project <name>` | New project     |
 | `-m <json>`        | New metadata    |
 
+### comment
+
+| Command                                               | Description           |
+| ----------------------------------------------------- | --------------------- |
+| `kanban comment list <task-id>`                       | List task comments    |
+| `kanban comment add <task-id> <body>`                 | Create a task comment |
+| `kanban comment update <task-id> <comment-id> <body>` | Update a task comment |
+
 ### column
 
 | Command                                       | Description             |
@@ -293,8 +302,9 @@ Starts a Bun HTTP server with:
 - **Sync status** at `/api/sync-status` — reports background sync state plus provider sync metadata
 
 In `serve` mode, remote providers now warm once on startup and continue syncing
-in the background every 30 seconds. Full reconciliation is still handled by the
-provider-specific logic on top of that steady cadence.
+in the background every `KANBAN_SYNC_INTERVAL_MS` milliseconds. Full
+reconciliation is still handled by the provider-specific logic on top of that
+steady cadence.
 
 Comment routes:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andypai/agent-kanban",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Agent-friendly kanban board CLI. Manage tasks via bash commands, parse structured JSON output.",
   "homepage": "https://github.com/abpai/agent-kanban#readme",
   "repository": {

package/src/__tests__/index.test.ts

@@ -4,7 +4,7 @@ import { mkdtempSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { ErrorCode, KanbanError, type ErrorCodeValue } from '../errors'
-import type { Task } from '../types'
+import type { Task, TaskComment } from '../types'
 import { parseServeArgs, run } from '../index'
 
 async function withTempDb(runTest: (dbPath: string) => Promise<void>): Promise<void> {
@@ -234,6 +234,28 @@ describe('run', () => {
     })
   })
 
+  test('runs comment commands through the real CLI path', async () => {
+    await withTempDb(async (dbPath) => {
+      const task = expectOk<Task>(await run(['--db', dbPath, 'task', 'add', 'Comment target']))
+
+      const created = expectOk<TaskComment>(
+        await run(['--db', dbPath, 'comment', 'add', task.id, 'hello', 'from', 'cli']),
+      )
+      expect(created.task_id).toBe(task.id)
+      expect(created.body).toBe('hello from cli')
+
+      const listed = expectOk<TaskComment[]>(
+        await run(['--db', dbPath, 'comment', 'list', task.id]),
+      )
+      expect(listed.map((comment) => comment.id)).toEqual([created.id])
+
+      const updated = expectOk<TaskComment>(
+        await run(['--db', dbPath, 'comment', 'update', task.id, created.id, 'edited', 'comment']),
+      )
+      expect(updated.body).toBe('edited comment')
+    })
+  })
+
   test('raises CLI errors for missing task arguments', async () => {
     await withTempDb(async (dbPath) => {
       const missingTitle = await expectKanbanError(
@@ -249,4 +271,28 @@ describe('run', () => {
       expect(missingId.message).toContain('Task ID is required')
     })
   })
+
+  test('raises CLI errors for missing comment arguments', async () => {
+    await withTempDb(async (dbPath) => {
+      const missingListId = await expectKanbanError(
+        run(['--db', dbPath, 'comment', 'list']),
+        ErrorCode.MISSING_ARGUMENT,
+      )
+      expect(missingListId.message).toContain('Task ID is required')
+
+      const missingAddBody = await expectKanbanError(
+        run(['--db', dbPath, 'comment', 'add', 't_1']),
+        ErrorCode.MISSING_ARGUMENT,
+      )
+      expect(missingAddBody.message).toContain('kanban comment add <task-id> <body>')
+
+      const missingUpdateBody = await expectKanbanError(
+        run(['--db', dbPath, 'comment', 'update', 't_1', 'c_1']),
+        ErrorCode.MISSING_ARGUMENT,
+      )
+      expect(missingUpdateBody.message).toContain(
+        'kanban comment update <task-id> <comment-id> <body>',
+      )
+    })
+  })
 })

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

@@ -5,6 +5,7 @@ import {
   type AdfBulletListNode,
   type AdfCodeBlockNode,
   type AdfDocument,
+  type AdfExpandNode,
   type AdfInlineNode,
   type AdfParagraphNode,
 } from '../providers/jira-adf'
@@ -432,3 +433,141 @@ describe('plainTextToAdf / adfToPlainText', () => {
     expect(adfToPlainText(doc)).toBe(input)
   })
 })
+
+describe('jira-adf expand block', () => {
+  test('write: expand wrapping a fenced code block produces nested ADF', () => {
+    const input =
+      '::: expand title="garage-baton (machine-readable)"\n' +
+      '```garage-baton\n' +
+      '{"v":1}\n' +
+      '```\n' +
+      ':::'
+    const doc = plainTextToAdf(input)
+    expect(doc.content).toHaveLength(1)
+    const expand = doc.content[0] as AdfExpandNode
+    expect(expand.type).toBe('expand')
+    expect(expand.attrs?.title).toBe('garage-baton (machine-readable)')
+    expect(expand.content).toHaveLength(1)
+    const code = expand.content[0] as AdfCodeBlockNode
+    expect(code.type).toBe('codeBlock')
+    expect(code.attrs?.language).toBe('garage-baton')
+    expect(code.content?.[0]).toEqual({ type: 'text', text: '{"v":1}' })
+  })
+
+  test('read: ADF expand wrapping a codeBlock renders back to the wire format', () => {
+    const doc: AdfDocument = {
+      version: 1,
+      type: 'doc',
+      content: [
+        {
+          type: 'expand',
+          attrs: { title: 'garage-baton (machine-readable)' },
+          content: [
+            {
+              type: 'codeBlock',
+              attrs: { language: 'garage-baton' },
+              content: [{ type: 'text', text: '{"v":1}' }],
+            },
+          ],
+        },
+      ],
+    }
+    expect(adfToPlainText(doc)).toBe(
+      '::: expand title="garage-baton (machine-readable)"\n' +
+        '```garage-baton\n' +
+        '{"v":1}\n' +
+        '```\n' +
+        ':::',
+    )
+  })
+
+  test('write: bare ::: expand emits empty title', () => {
+    const input = '::: expand\nbody paragraph\n:::'
+    const doc = plainTextToAdf(input)
+    const expand = doc.content[0] as AdfExpandNode
+    expect(expand.type).toBe('expand')
+    expect(expand.attrs?.title).toBe('')
+    expect(expand.content[0]?.type).toBe('paragraph')
+  })
+
+  test('read: bare ::: expand renders without title attribute', () => {
+    const doc: AdfDocument = {
+      version: 1,
+      type: 'doc',
+      content: [
+        {
+          type: 'expand',
+          attrs: { title: '' },
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'body' }] }],
+        },
+      ],
+    }
+    expect(adfToPlainText(doc)).toBe('::: expand\nbody\n:::')
+  })
+
+  test('read: expand without attrs renders as a bare expand block', () => {
+    const doc: AdfDocument = {
+      version: 1,
+      type: 'doc',
+      content: [
+        {
+          type: 'expand',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'body' }] }],
+        },
+      ],
+    }
+    expect(adfToPlainText(doc)).toBe('::: expand\nbody\n:::')
+  })
+
+  test('write: unterminated ::: expand falls through to paragraph', () => {
+    const input = '::: expand title="oops"\nstray text without close'
+    const doc = plainTextToAdf(input)
+    // Both lines collapse into a single paragraph; no expand node.
+    expect(doc.content.every((b) => b.type !== 'expand')).toBe(true)
+    expect(doc.content[0]?.type).toBe('paragraph')
+  })
+
+  test('round-trip: typed-comment-shaped string is byte-stable', () => {
+    const input =
+      'garage-triage: **Accepted** — abpai/garage-band\n' +
+      '\n' +
+      'Increment current_count by 1.\n' +
+      '\n' +
+      '**Next:** Handing off to planner.\n' +
+      '\n' +
+      '::: expand title="garage-baton (machine-readable)"\n' +
+      '```garage-baton\n' +
+      '{"v":1,"accepted":true}\n' +
+      '```\n' +
+      ':::'
+    expect(adfToPlainText(plainTextToAdf(input))).toBe(input)
+  })
+
+  test('round-trip: nested paragraph and bullet list inside expand survive', () => {
+    const input =
+      '::: expand title="details"\n' +
+      'first paragraph\n' +
+      '\n' +
+      '- bullet one\n' +
+      '- bullet two\n' +
+      ':::'
+    expect(adfToPlainText(plainTextToAdf(input))).toBe(input)
+  })
+
+  test('write: expand title preserves escaped quote', () => {
+    const input = '::: expand title="quoted \\"title\\""\nx\n:::'
+    const doc = plainTextToAdf(input)
+    const expand = doc.content[0] as AdfExpandNode
+    expect(expand.attrs?.title).toBe('quoted "title"')
+    // Round-trip emits the same escaping.
+    expect(adfToPlainText(doc)).toBe(input)
+  })
+
+  test('write: text followed by ::: expand on the next line is two blocks', () => {
+    const input = 'leading paragraph\n' + '::: expand title="x"\n' + 'inside\n' + ':::'
+    const doc = plainTextToAdf(input)
+    expect(doc.content).toHaveLength(2)
+    expect(doc.content[0]?.type).toBe('paragraph')
+    expect(doc.content[1]?.type).toBe('expand')
+  })
+})

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

@@ -240,6 +240,28 @@ describe('JiraProvider read path', () => {
     }
   })
 
+  test('custom polling sync interval refreshes before the default 30 seconds', async () => {
+    const { fn, calls } = jiraFetchStub(standardRoutes({}))
+    globalThis.fetch = fn
+    const client = new JiraClient({
+      baseUrl: baseConfig.baseUrl,
+      email: baseConfig.email,
+      apiToken: baseConfig.apiToken,
+    })
+    const provider = new JiraProvider(db, { ...baseConfig, pollingSyncIntervalMs: 5_000 }, client)
+    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',
+    })
+    Date.now = () => Date.parse('2026-01-01T00:00:06.000Z')
+
+    await provider.listTasks()
+
+    expect(calls.some((call) => call.url.includes('/rest/api/3/search/jql'))).toBe(true)
+  })
+
   test('sync delta JQL is exactly project = KEY AND updated >= "<ts>" ORDER BY updated ASC', async () => {
     const capturedJql: string[] = []
     // First sync: one issue returned so lastIssueUpdatedAt is set.

package/src/__tests__/linear-provider-sync.test.ts

@@ -485,4 +485,81 @@ describe('LinearProvider sync', () => {
 
     expect(issueQueries).toBe(1)
   })
+
+  test('custom polling sync interval refreshes before the default 30 seconds', async () => {
+    let issueQueries = 0
+
+    saveSyncMeta(db, {
+      team: { id: 'team-1', key: 'R2P', name: 'R2pi' },
+      lastSyncAt: '2026-01-01T00:00:00.000Z',
+      lastFullSyncAt: '2026-01-01T00:00:00.000Z',
+      lastIssueUpdatedAt: '2026-01-01T00:00:00.000Z',
+    })
+
+    globalThis.fetch = (async (_input: string | URL | Request, init?: RequestInit) => {
+      const body = JSON.parse(String(init?.body)) as {
+        query: string
+        variables: Record<string, unknown>
+      }
+
+      if (body.query.includes('query TeamSnapshot')) {
+        return new Response(
+          JSON.stringify({
+            data: {
+              team: {
+                id: 'team-1',
+                key: 'R2P',
+                name: 'R2pi',
+                states: { nodes: [{ id: 'state-1', name: 'Todo', position: 0 }] },
+              },
+            },
+          }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        )
+      }
+
+      if (body.query.includes('query Users')) {
+        return new Response(JSON.stringify({ data: { users: { nodes: [] } } }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        })
+      }
+
+      if (body.query.includes('query Projects')) {
+        return new Response(JSON.stringify({ data: { projects: { nodes: [] } } }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        })
+      }
+
+      if (body.query.includes('query Issues')) {
+        issueQueries += 1
+        return new Response(
+          JSON.stringify({
+            data: {
+              issues: {
+                nodes: [],
+                pageInfo: { hasNextPage: false, endCursor: null },
+              },
+            },
+          }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        )
+      }
+
+      return new Response(`Unexpected query: ${body.query}`, { status: 500 })
+    }) as unknown as typeof fetch
+
+    const originalDateNow = Date.now
+    Date.now = () => Date.parse('2026-01-01T00:00:06.000Z')
+
+    try {
+      const provider = new LinearProvider(db, 'R2P', 'lin_api_test', 5_000)
+      await provider.getBoard()
+    } finally {
+      Date.now = originalDateNow
+    }
+
+    expect(issueQueries).toBe(1)
+  })
 })

package/src/__tests__/output.test.ts

@@ -36,4 +36,21 @@ describe('formatOutput', () => {
     const output = formatOutput(result, true)
     expect(output).toBe('Board initialized.')
   })
+
+  test('formats comments in pretty mode', () => {
+    const output = formatOutput(
+      success([
+        {
+          id: 'c_1',
+          task_id: 't_1',
+          body: 'hello from cli',
+          author: 'alice',
+          created_at: '2026-04-26T00:00:00.000Z',
+          updated_at: '2026-04-26T00:00:00.000Z',
+        },
+      ]),
+      true,
+    )
+    expect(output).toBe('  c_1 @alice  hello from cli')
+  })
 })

package/src/__tests__/sync-config.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'bun:test'
+import { ErrorCode, KanbanError } from '../errors'
+import {
+  DEFAULT_POLLING_SYNC_INTERVAL_MS,
+  MIN_POLLING_SYNC_INTERVAL_MS,
+  resolvePollingSyncIntervalMs,
+} from '../sync-config'
+
+describe('sync config', () => {
+  test('defaults when unset or blank', () => {
+    expect(resolvePollingSyncIntervalMs(undefined)).toBe(DEFAULT_POLLING_SYNC_INTERVAL_MS)
+    expect(resolvePollingSyncIntervalMs('   ')).toBe(DEFAULT_POLLING_SYNC_INTERVAL_MS)
+  })
+
+  test('accepts an integer millisecond interval', () => {
+    expect(resolvePollingSyncIntervalMs('5000')).toBe(5_000)
+  })
+
+  test('rejects invalid or too-aggressive intervals', () => {
+    for (const raw of ['999', '5s', '1000.5', '0']) {
+      let err: unknown
+      try {
+        resolvePollingSyncIntervalMs(raw)
+      } catch (caught) {
+        err = caught
+      }
+      expect(err).toBeInstanceOf(KanbanError)
+      expect((err as KanbanError).code).toBe(ErrorCode.INVALID_CONFIG)
+      expect((err as Error).message).toContain(String(MIN_POLLING_SYNC_INTERVAL_MS))
+    }
+  })
+})

package/src/errors.ts

@@ -9,6 +9,7 @@ export const ErrorCode = {
   INVALID_PRIORITY: 'INVALID_PRIORITY',
   INVALID_METADATA: 'INVALID_METADATA',
   INVALID_POSITION: 'INVALID_POSITION',
+  INVALID_CONFIG: 'INVALID_CONFIG',
   CONFLICT: 'CONFLICT',
   MISSING_ARGUMENT: 'MISSING_ARGUMENT',
   UNKNOWN_COMMAND: 'UNKNOWN_COMMAND',

package/src/index.ts

@@ -139,6 +139,45 @@ async function routeTask(
   }
 }
 
+async function routeComment(
+  provider: ReturnType<typeof createProvider>,
+  action: string | undefined,
+  positionals: string[],
+): Promise<CliOutput> {
+  switch (action) {
+    case 'list': {
+      const id = positionals[2]
+      if (!id) throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Task ID is required')
+      return success(await provider.listComments(id))
+    }
+    case 'add': {
+      const id = positionals[2]
+      const body = positionals.slice(3).join(' ')
+      if (!id || !body) {
+        throw new KanbanError(
+          ErrorCode.MISSING_ARGUMENT,
+          'Usage: kanban comment add <task-id> <body>',
+        )
+      }
+      return success(await provider.comment(id, body))
+    }
+    case 'update': {
+      const id = positionals[2]
+      const commentId = positionals[3]
+      const body = positionals.slice(4).join(' ')
+      if (!id || !commentId || !body) {
+        throw new KanbanError(
+          ErrorCode.MISSING_ARGUMENT,
+          'Usage: kanban comment update <task-id> <comment-id> <body>',
+        )
+      }
+      return success(await provider.updateComment(id, commentId, body))
+    }
+    default:
+      throw new KanbanError(ErrorCode.UNKNOWN_COMMAND, `Unknown comment command '${action}'`)
+  }
+}
+
 function routeColumn(
   db: Database,
   providerType: string,
@@ -298,6 +337,9 @@ async function run(argv: string[]): Promise<{ output: CliOutput; exitCode: numbe
       case 'task':
         output = await routeTask(provider, action, positionals, values)
         break
+      case 'comment':
+        output = await routeComment(provider, action, positionals)
+        break
       case 'column':
         output = routeColumn(db, provider.type, action, positionals, values)
         break
@@ -335,6 +377,11 @@ Commands:
   task assign <id> <user>     Assign task
   task prioritize <id> <lvl>  Set priority
 
+  comment list <task-id>      List comments on a task
+  comment add <task-id> <body> Create a comment
+  comment update <task-id> <comment-id> <body>
+                              Update a comment
+
   column add <name>           Add column [--position n] [--color hex]
   column list                 List columns
   column rename <id> <name>   Rename column

package/src/mcp/errors.ts

@@ -39,6 +39,7 @@ function providerError(code: ErrorCodeValue): TrackerMcpErrorCode {
     case ErrorCode.INVALID_METADATA:
     case ErrorCode.INVALID_POSITION:
     case ErrorCode.INVALID_PRIORITY:
+    case ErrorCode.INVALID_CONFIG:
     case ErrorCode.MISSING_ARGUMENT:
     case ErrorCode.UNSUPPORTED_OPERATION:
     case ErrorCode.CONFLICT:

package/src/output.ts

@@ -1,4 +1,4 @@
-import type { CliOutput, BoardView, Task, TaskWithColumn, Column } from './types'
+import type { CliOutput, BoardView, Task, TaskWithColumn, TaskComment, Column } from './types'
 
 export function success<T>(data: T): CliOutput<T> {
   return { ok: true, data }
@@ -25,12 +25,16 @@ function formatPrettyData(data: unknown): string {
   if (Array.isArray(data)) {
     if (data.length === 0) return 'No items found.'
     if ('column_id' in data[0]) return data.map(formatTaskLine).join('\n')
+    if ('task_id' in data[0]) return data.map(formatCommentLine).join('\n')
     if ('position' in data[0]) return data.map(formatColumnLine).join('\n')
     return JSON.stringify(data, null, 2)
   }
   if (data && typeof data === 'object' && 'column_id' in data) {
     return formatTaskDetail(data as TaskWithColumn)
   }
+  if (data && typeof data === 'object' && 'task_id' in data) {
+    return formatCommentDetail(data as TaskComment)
+  }
   if (data && typeof data === 'object' && 'moved' in data) {
     return `Moved ${(data as { moved: number }).moved} task(s).`
   }
@@ -79,6 +83,23 @@ function formatTaskDetail(task: Task): string {
   return lines.join('\n')
 }
 
+function formatCommentLine(comment: TaskComment): string {
+  const author = comment.author ? ` @${comment.author}` : ''
+  return `  ${comment.id}${author}  ${comment.body}`
+}
+
+function formatCommentDetail(comment: TaskComment): string {
+  const lines = [
+    `Comment: ${comment.id}`,
+    `Task: ${comment.task_id}`,
+    ...(comment.author ? [`Author: ${comment.author}`] : []),
+    `Body: ${comment.body}`,
+    `Created: ${comment.created_at}`,
+    `Updated: ${comment.updated_at}`,
+  ]
+  return lines.join('\n')
+}
+
 function formatColumnLine(col: Column): string {
   const color = col.color ? ` (${col.color})` : ''
   return `  ${col.position}. ${col.name}${color}  [${col.id}]`

package/src/providers/index.ts

@@ -5,6 +5,7 @@ import { JiraProvider } from './jira'
 import { LinearProvider } from './linear'
 import { LocalProvider } from './local'
 import type { KanbanProvider } from './types'
+import { resolvePollingSyncIntervalMs } from '../sync-config'
 
 export function createProvider(db: Database, dbPath = getDbPath()): KanbanProvider {
   const providerType = (process.env['KANBAN_PROVIDER'] ?? 'local') as 'local' | 'linear' | 'jira'
@@ -17,7 +18,7 @@ export function createProvider(db: Database, dbPath = getDbPath()): KanbanProvid
         'LINEAR_API_KEY and LINEAR_TEAM_ID are required when KANBAN_PROVIDER=linear',
       )
     }
-    return new LinearProvider(db, teamId!, apiKey!)
+    return new LinearProvider(db, teamId!, apiKey!, resolvePollingSyncIntervalMs())
   }
 
   if (providerType === 'jira') {
@@ -45,6 +46,7 @@ export function createProvider(db: Database, dbPath = getDbPath()): KanbanProvid
       projectKey: projectKey!,
       boardId: Number.isFinite(boardId) ? boardId : undefined,
       defaultIssueType,
+      pollingSyncIntervalMs: resolvePollingSyncIntervalMs(),
     })
   }
 

package/src/providers/jira-adf.ts

@@ -68,6 +68,12 @@ export interface AdfHeadingNode {
   content?: AdfInlineNode[]
 }
 
+export interface AdfExpandNode {
+  type: 'expand'
+  attrs?: { title?: string }
+  content: AdfBlockNode[]
+}
+
 export interface AdfUnknownBlockNode {
   type: string
   [key: string]: unknown
@@ -79,6 +85,7 @@ export type AdfBlockNode =
   | AdfOrderedListNode
   | AdfCodeBlockNode
   | AdfHeadingNode
+  | AdfExpandNode
   | AdfUnknownBlockNode
 
 // Public AdfNode union covers every node shape this module recognizes.
@@ -90,6 +97,18 @@ const ORDERED_MARKER = /^(\d+)\. (.*)$/
 // no whitespace before it. Fence must occupy the whole line.
 const FENCE_OPEN = /^```([^\s`]*)$/
 const FENCE_CLOSE = /^```$/
+// Expand wrapper: `::: expand` or `::: expand title="..."`. Quotes and
+// backslashes in the title are escaped with a leading `\`.
+const EXPAND_OPEN = /^::: expand(?: title="((?:\\.|[^"\\])*)")?$/
+const EXPAND_CLOSE = /^:::$/
+
+function unescapeTitle(raw: string): string {
+  return raw.replace(/\\(.)/g, '$1')
+}
+
+function escapeTitle(value: string): string {
+  return value.replace(/(["\\])/g, '\\$1')
+}
 
 function paragraphFromText(text: string): AdfParagraphNode {
   if (text.length === 0) {
@@ -145,13 +164,26 @@ export function plainTextToAdf(text: string): AdfDocument {
   if (text.length === 0) {
     return { version: 1, type: 'doc', content: [] }
   }
-
   const lines = text.split('\n')
-  const blocks: AdfBlockNode[] = []
+  const { blocks } = parseBlocks(lines, 0, () => false)
+  return { version: 1, type: 'doc', content: blocks }
+}
+
+interface ParseResult {
+  blocks: AdfBlockNode[]
+  // Index just past the last consumed line. When `stop` matches, this points
+  // at the stop line itself (the caller is responsible for stepping past it).
+  endIndex: number
+}
 
-  let i = 0
+function parseBlocks(lines: string[], start: number, stop: (line: string) => boolean): ParseResult {
+  const blocks: AdfBlockNode[] = []
+  let i = start
   while (i < lines.length) {
     const line = lines[i] ?? ''
+    if (stop(line)) {
+      return { blocks, endIndex: i }
+    }
 
     // Blank line separates blocks — consume and move on.
     if (line === '') {
@@ -159,6 +191,19 @@ export function plainTextToAdf(text: string): AdfDocument {
       continue
     }
 
+    // Expand wrapper.
+    const expandOpen = line.match(EXPAND_OPEN)
+    if (expandOpen) {
+      const title = unescapeTitle(expandOpen[1] ?? '')
+      const inner = parseBlocks(lines, i + 1, (l) => EXPAND_CLOSE.test(l))
+      if (inner.endIndex < lines.length) {
+        blocks.push({ type: 'expand', attrs: { title }, content: inner.blocks })
+        i = inner.endIndex + 1
+        continue
+      }
+      // Unterminated `::: expand` — fall through to paragraph.
+    }
+
     // Fenced code block.
     const fenceOpen = line.match(FENCE_OPEN)
     if (fenceOpen) {
@@ -227,16 +272,19 @@ export function plainTextToAdf(text: string): AdfDocument {
       continue
     }
 
-    // Paragraph: consume until blank line or a block-starting line.
+    // Paragraph: consume until blank line, stop predicate, or a
+    // block-starting line.
     const paragraphLines: string[] = [line]
     i += 1
     while (i < lines.length) {
       const current = lines[i] ?? ''
       if (
         current === '' ||
+        stop(current) ||
         BULLET_MARKER.test(current) ||
         ORDERED_MARKER.test(current) ||
-        FENCE_OPEN.test(current)
+        FENCE_OPEN.test(current) ||
+        EXPAND_OPEN.test(current)
       ) {
         break
       }
@@ -246,7 +294,7 @@ export function plainTextToAdf(text: string): AdfDocument {
     blocks.push(paragraphFromText(paragraphLines.join('\n')))
   }
 
-  return { version: 1, type: 'doc', content: blocks }
+  return { blocks, endIndex: i }
 }
 
 function inlineText(
@@ -357,6 +405,14 @@ function renderBlock(node: AdfBlockNode): string | null {
     }
     case 'heading':
       return inlineText((node as AdfHeadingNode).content)
+    case 'expand': {
+      const expand = node as AdfExpandNode
+      const title = expand.attrs?.title ?? ''
+      const open = title.length > 0 ? `::: expand title="${escapeTitle(title)}"` : '::: expand'
+      const inner = renderBlocks(expand.content)
+      const body = inner.length > 0 ? `${open}\n${inner}\n:::` : `${open}\n:::`
+      return body
+    }
     case 'blockCard':
     case 'embedCard': {
       const url = readCardUrl(node)
@@ -368,12 +424,16 @@ function renderBlock(node: AdfBlockNode): string | null {
   }
 }
 
-export function adfToPlainText(doc: AdfDocument): string {
-  const rendered: string[] = []
-  for (const block of doc.content) {
+function renderBlocks(nodes: AdfBlockNode[]): string {
+  const out: string[] = []
+  for (const block of nodes) {
     const text = renderBlock(block)
     if (text === null) continue
-    rendered.push(text)
+    out.push(text)
   }
-  return rendered.join('\n\n')
+  return out.join('\n\n')
+}
+
+export function adfToPlainText(doc: AdfDocument): string {
+  return renderBlocks(doc.content)
 }

package/src/providers/jira.ts

@@ -49,8 +49,8 @@ import type {
   TaskListFilters,
   UpdateTaskInput,
 } from './types'
+import { resolvePollingSyncIntervalMs } from '../sync-config'
 
-const SYNC_INTERVAL_MS = 30_000
 const FULL_RECONCILE_INTERVAL_MS = 5 * 60_000
 
 function shouldRunFullReconcile(lastFullSyncAt: string | null, now: number): boolean {
@@ -78,11 +78,13 @@ export interface JiraProviderConfig {
   projectKey: string
   boardId?: number
   defaultIssueType?: string
+  pollingSyncIntervalMs?: number
 }
 
 export class JiraProvider implements KanbanProvider {
   readonly type = 'jira' as const
   private readonly client: JiraClient
+  private readonly pollingSyncIntervalMs: number
 
   constructor(
     private readonly db: Database,
@@ -90,6 +92,7 @@ export class JiraProvider implements KanbanProvider {
     client?: JiraClient,
   ) {
     initJiraCacheSchema(db)
+    this.pollingSyncIntervalMs = config.pollingSyncIntervalMs ?? resolvePollingSyncIntervalMs()
     this.client =
       client ??
       new JiraClient({
@@ -103,7 +106,7 @@ export class JiraProvider implements KanbanProvider {
     const meta = loadJiraSyncMeta(this.db)
     const lastSyncAtMs = meta.lastSyncAt ? Date.parse(meta.lastSyncAt) : 0
     const now = Date.now()
-    if (!force && lastSyncAtMs && now - lastSyncAtMs < SYNC_INTERVAL_MS) return
+    if (!force && lastSyncAtMs && now - lastSyncAtMs < this.pollingSyncIntervalMs) return
     const fullReconcile = force || shouldRunFullReconcile(meta.lastFullSyncAt, now)
 
     // 1. Resolve project.

package/src/providers/linear.ts

@@ -41,8 +41,8 @@ import type {
   TaskListFilters,
   UpdateTaskInput,
 } from './types'
+import { resolvePollingSyncIntervalMs } from '../sync-config'
 
-const SYNC_INTERVAL_MS = 30_000
 const FULL_RECONCILIATION_INTERVAL_MS = 5 * 60_000
 
 function parseTimestamp(value: string | null | undefined): number {
@@ -81,6 +81,7 @@ export class LinearProvider implements KanbanProvider {
     private readonly db: Database,
     private readonly teamId: string,
     apiKey: string,
+    private readonly pollingSyncIntervalMs = resolvePollingSyncIntervalMs(),
   ) {
     initLinearCacheSchema(db)
     this.client = new LinearClient(apiKey)
@@ -105,7 +106,7 @@ export class LinearProvider implements KanbanProvider {
     const lastSyncAtMs = parseTimestamp(meta.lastSyncAt)
     const lastFullSyncAtMs = parseTimestamp(meta.lastFullSyncAt)
     const now = Date.now()
-    if (!force && lastSyncAtMs && now - lastSyncAtMs < SYNC_INTERVAL_MS) return
+    if (!force && lastSyncAtMs && now - lastSyncAtMs < this.pollingSyncIntervalMs) return
 
     const shouldFullSync =
       force ||

package/src/server.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 import { handleRequest } from './api'
 import type { ServerWebSocket } from 'bun'
 import type { KanbanProvider } from './providers/types'
+import { resolvePollingSyncIntervalMs } from './sync-config'
 
 const wsClients = new Set<ServerWebSocket<unknown>>()
 const CORS_HEADERS = {
@@ -10,8 +11,6 @@ const CORS_HEADERS = {
   'Access-Control-Allow-Methods': 'GET, POST, PATCH, DELETE, OPTIONS',
   'Access-Control-Allow-Headers': 'Content-Type',
 }
-const DEFAULT_BACKGROUND_SYNC_INTERVAL_MS = 30_000
-
 interface BackgroundSyncState {
   enabled: boolean
   inFlight: boolean
@@ -64,7 +63,7 @@ export function startServer(
 ): StartedServer {
   const distDir = join(import.meta.dir, '..', 'ui', 'dist')
   const hasStatic = existsSync(distDir)
-  const syncIntervalMs = opts.syncIntervalMs ?? DEFAULT_BACKGROUND_SYNC_INTERVAL_MS
+  const syncIntervalMs = opts.syncIntervalMs ?? resolvePollingSyncIntervalMs()
   const syncCache = provider.syncCache?.bind(provider)
   const getSyncStatus = provider.getSyncStatus?.bind(provider)
   const backgroundSync: BackgroundSyncState = {

package/src/sync-config.ts

@@ -0,0 +1,18 @@
+import { ErrorCode, KanbanError } from './errors'
+
+export const DEFAULT_POLLING_SYNC_INTERVAL_MS = 30_000
+export const MIN_POLLING_SYNC_INTERVAL_MS = 1_000
+
+export function resolvePollingSyncIntervalMs(raw = process.env['KANBAN_SYNC_INTERVAL_MS']): number {
+  const value = raw?.trim()
+  if (!value) return DEFAULT_POLLING_SYNC_INTERVAL_MS
+
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed < MIN_POLLING_SYNC_INTERVAL_MS) {
+    throw new KanbanError(
+      ErrorCode.INVALID_CONFIG,
+      `KANBAN_SYNC_INTERVAL_MS must be an integer >= ${MIN_POLLING_SYNC_INTERVAL_MS}`,
+    )
+  }
+  return parsed
+}