@andypai/agent-kanban 0.6.3 → 0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andypai/agent-kanban",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Agent-friendly kanban board CLI. Manage tasks via bash commands, parse structured JSON output.",
   "homepage": "https://github.com/abpai/agent-kanban#readme",
   "repository": {
@@ -34,6 +34,9 @@
   },
   "packageManager": "bun@1.3.3",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "dev": "bun --watch src/index.ts",
     "start": "bun src/index.ts",
@@ -53,17 +56,22 @@
     "dev:ui": "bun scripts/dev.ts",
     "build:ui": "bun run ui:build",
     "prepare": "if [ \"${HUSKY:-1}\" != \"0\" ] && command -v husky >/dev/null 2>&1; then husky install; fi",
-    "prepack": "cd ui && bun install --frozen-lockfile && bun run build"
+    "prepack": "cd ui && bun install --frozen-lockfile && bun run build",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "postgres": "^3.4.4"
   },
   "devDependencies": {
+    "@changesets/changelog-github": "^0.7.0",
+    "@changesets/cli": "^2.31.0",
     "@eslint/js": "^9.39.1",
+    "@types/bun": "^1.1.22",
     "@typescript-eslint/eslint-plugin": "^8.18.0",
     "@typescript-eslint/parser": "^8.18.0",
-    "@types/bun": "^1.1.22",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",

package/src/__tests__/index.test.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { ErrorCode, KanbanError, type ErrorCodeValue } from '../errors'
 import type { Task, TaskComment } from '../types'
-import { parseServeArgs, run } from '../index'
+import { parseMcpArgs, parseServeArgs, run } from '../index'
 
 async function withTempDb(runTest: (dbPath: string) => Promise<void>): Promise<void> {
   const dir = mkdtempSync(join(tmpdir(), 'kanban-run-'))
@@ -120,6 +120,26 @@ describe('parseServeArgs', () => {
       else process.env['KANBAN_ALLOWED_ORIGIN'] = prevOrigin
     }
   })
+
+  test('rejects unknown serve options', () => {
+    expect(() => parseServeArgs(['serve', '--bogus'])).toThrow(KanbanError)
+    try {
+      parseServeArgs(['serve', '--bogus'])
+    } catch (err) {
+      expect((err as KanbanError).code).toBe(ErrorCode.INVALID_ARGUMENT)
+    }
+  })
+})
+
+describe('parseMcpArgs', () => {
+  test('rejects unknown mcp options', () => {
+    expect(() => parseMcpArgs(['mcp', '--bogus'])).toThrow(KanbanError)
+    try {
+      parseMcpArgs(['mcp', '--bogus'])
+    } catch (err) {
+      expect((err as KanbanError).code).toBe(ErrorCode.INVALID_ARGUMENT)
+    }
+  })
 })
 
 describe('run', () => {
@@ -375,4 +395,10 @@ describe('run', () => {
       )
     })
   })
+
+  test('rejects unknown top-level options before opening a runtime', async () => {
+    const err = await run(['--bogus']).catch((e: unknown) => e)
+    expect(err).toBeInstanceOf(KanbanError)
+    expect((err as KanbanError).code).toBe(ErrorCode.INVALID_ARGUMENT)
+  })
 })

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

@@ -12,10 +12,12 @@ import {
   replaceJiraColumns,
   replaceJiraIssueTypes,
   replaceJiraPriorities,
+  resolveJiraColumnId,
   saveJiraSyncMeta,
   upsertJiraIssues,
   upsertJiraUsers,
 } from '../providers/jira-cache'
+import type { JiraColumnRow } from '../providers/jira-cache'
 
 let db: Database
 
@@ -358,3 +360,69 @@ describe('jira-cache', () => {
     expect(getCachedTasks(db, { columnId })).toEqual([])
   })
 })
+
+describe('resolveJiraColumnId', () => {
+  const col = (id: string, name: string, statusIds: string[] = []): JiraColumnRow => ({
+    id,
+    name,
+    position: 0,
+    status_ids: JSON.stringify(statusIds),
+    source: 'status',
+  })
+
+  test('matches by exact id first', () => {
+    const columns = [col('status:12136', 'To Do'), col('status:12137', 'In Progress')]
+    expect(resolveJiraColumnId(columns, 'status:12137')).toBe('status:12137')
+  })
+
+  test('matches by case-insensitive name', () => {
+    const columns = [col('status:12136', 'To Do')]
+    expect(resolveJiraColumnId(columns, 'to do')).toBe('status:12136')
+  })
+
+  test("resolves a separator-collapsed trigger string ('Todo') to the 'To Do' status column", () => {
+    const columns = [col('status:12136', 'To Do'), col('status:12137', 'In Progress')]
+    expect(resolveJiraColumnId(columns, 'Todo')).toBe('status:12136')
+    expect(resolveJiraColumnId(columns, 'ToDo')).toBe('status:12136')
+    expect(resolveJiraColumnId(columns, 'In-Progress')).toBe('status:12137')
+  })
+
+  test('exact case-insensitive name wins over a separator-insensitive collision', () => {
+    // 'To Do' and 'Todo' both normalize to 'todo'; an exact lowercase hit must
+    // not be derailed into the ambiguity branch.
+    const columns = [col('status:1', 'To Do'), col('status:2', 'Todo')]
+    expect(resolveJiraColumnId(columns, 'todo')).toBe('status:2')
+  })
+
+  test('rejects a separator-insensitive match that collapses two distinct columns', () => {
+    const columns = [col('status:1', 'To Do'), col('status:2', 'To-Do')]
+    expect(() => resolveJiraColumnId(columns, 'Todo')).toThrow(/ambiguous/)
+  })
+
+  test('falls back to raw status id containment', () => {
+    const columns = [col('board:1:Backlog', 'Backlog', ['10001', '10002'])]
+    expect(resolveJiraColumnId(columns, '10002')).toBe('board:1:Backlog')
+  })
+
+  test('raw status id wins over a column whose name normalizes to that id', () => {
+    // A numeric status-id reference must resolve by containment, not be hijacked
+    // by a column whose name only matches after the fuzzy normalized pass
+    // ('1-0-0-0-3' → '10003').
+    const columns = [
+      col('status:1', '1-0-0-0-3', ['99999']),
+      col('board:1:Backlog', 'Backlog', ['10003']),
+    ]
+    expect(resolveJiraColumnId(columns, '10003')).toBe('board:1:Backlog')
+  })
+
+  test('empty / separator-only input does not match a separator-only column name', () => {
+    const columns = [col('status:1', '---'), col('status:2', 'To Do')]
+    expect(() => resolveJiraColumnId(columns, '   ')).toThrow(/No Jira column matching/)
+    expect(() => resolveJiraColumnId(columns, '!!!')).toThrow(/No Jira column matching/)
+  })
+
+  test('throws COLUMN_NOT_FOUND when nothing matches', () => {
+    const columns = [col('status:12136', 'To Do')]
+    expect(() => resolveJiraColumnId(columns, 'Done')).toThrow(/No Jira column matching/)
+  })
+})

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

@@ -3,6 +3,7 @@ import { Database } from 'bun:sqlite'
 import { ErrorCode, KanbanError } from '../errors'
 import { JiraClient } from '../providers/jira-client'
 import { JiraProvider, type JiraProviderConfig } from '../providers/jira'
+import { resetWarnOnce } from '../providers/warn-once'
 import {
   getCachedColumns,
   getCachedTasks,
@@ -176,6 +177,7 @@ beforeEach(() => {
   db = new Database(':memory:')
   originalFetch = globalThis.fetch
   originalDateNow = Date.now
+  resetWarnOnce()
 })
 
 afterEach(() => {
@@ -837,6 +839,46 @@ describe('JiraProvider read path', () => {
     expect(getCachedTasks(db)).toHaveLength(150)
   })
 
+  test('sync fetches Jira changelogs with bounded concurrency', async () => {
+    const issues = Array.from({ length: 6 }, (_, i) =>
+      makeIssue({
+        id: String(i + 1),
+        key: `ENG-${i + 1}`,
+        statusId: '10001',
+        updated: '2026-01-02T00:00:00Z',
+      }),
+    )
+    const searchHandler: StubHandler = () => jsonResponse({ isLast: true, issues })
+    let calls = 0
+    let inFlight = 0
+    let maxInFlight = 0
+    const changelogHandler: StubHandler = async () => {
+      calls += 1
+      inFlight += 1
+      maxInFlight = Math.max(maxInFlight, inFlight)
+      await new Promise((resolve) => setTimeout(resolve, 5))
+      inFlight -= 1
+      return jsonResponse({
+        startAt: 0,
+        maxResults: 100,
+        total: 0,
+        isLast: true,
+        values: [],
+      })
+    }
+
+    const { provider } = makeProviderWithBoard(
+      standardRoutes({ searchHandler, changelogHandler }),
+      3,
+    )
+
+    await provider.getBoard()
+
+    expect(calls).toBe(6)
+    expect(maxInFlight).toBeGreaterThan(1)
+    expect(maxInFlight).toBeLessThanOrEqual(5)
+  })
+
   test('saveTeamInfo / loadTeamInfo roundtrip', () => {
     initJiraCacheSchema(db)
     saveTeamInfo(db, { id: '10000', key: 'ENG', name: 'Engineering' })
@@ -895,4 +937,92 @@ describe('JiraProvider read path', () => {
 
     expect(calls.some((c) => c.url.includes('/rest/api/3/search/jql'))).toBe(true)
   })
+
+  function captureUnmappedWarnings(): {
+    messages: string[]
+    restore: () => void
+  } {
+    const all: string[] = []
+    const origWarn = console.warn
+    console.warn = (...args: unknown[]) => {
+      all.push(args.map(String).join(' '))
+    }
+    return {
+      get messages() {
+        return all.filter((m) => m.includes('maps to no column'))
+      },
+      restore: () => {
+        console.warn = origWarn
+      },
+    }
+  }
+
+  test('warns when an issue status maps to no board column and keeps it off the board', async () => {
+    // Board maps statuses 10001/10002 to 'Done'; 10003 is on no column.
+    const searchHandler: StubHandler = () =>
+      jsonResponse({
+        startAt: 0,
+        maxResults: 100,
+        total: 1,
+        issues: [makeIssue({ id: '7', key: 'ENG-7', statusId: '10003' })],
+      })
+    const warn = captureUnmappedWarnings()
+    try {
+      const { provider } = makeProviderWithBoard(standardRoutes({ searchHandler }), 3)
+      const board = await provider.getBoard()
+      expect(warn.messages).toHaveLength(1)
+      expect(warn.messages[0]).toContain("status 'Status 10003' (10003)")
+      expect(warn.messages[0]).toContain('not on board 3')
+      // Cached but invisible: present in jira_issues, absent from every column.
+      expect(getCachedTasks(db).some((t) => t.externalRef === 'ENG-7')).toBe(true)
+      expect(board.columns.flatMap((c) => c.tasks)).toHaveLength(0)
+    } finally {
+      warn.restore()
+    }
+  })
+
+  test('warns when an issue status is absent from the status-fallback catalog', async () => {
+    // Status-fallback columns come from statuses 10001/10002/10003; 10099 is absent.
+    const searchHandler: StubHandler = () =>
+      jsonResponse({
+        startAt: 0,
+        maxResults: 100,
+        total: 1,
+        issues: [makeIssue({ id: '8', key: 'ENG-8', statusId: '10099' })],
+      })
+    const warn = captureUnmappedWarnings()
+    try {
+      const { provider } = makeProvider(standardRoutes({ searchHandler }))
+      await provider.getBoard()
+      expect(warn.messages).toHaveLength(1)
+      expect(warn.messages[0]).toContain("status 'Status 10099' (10099)")
+      expect(warn.messages[0]).toContain('absent from the project status catalog')
+    } finally {
+      warn.restore()
+    }
+  })
+
+  test('unmapped-status warning fires once across repeated syncs', async () => {
+    const searchHandler: StubHandler = () =>
+      jsonResponse({
+        startAt: 0,
+        maxResults: 100,
+        total: 1,
+        issues: [makeIssue({ id: '9', key: 'ENG-9', statusId: '10003' })],
+      })
+    const warn = captureUnmappedWarnings()
+    try {
+      const { provider, calls } = makeProviderWithBoard(standardRoutes({ searchHandler }), 3)
+      await provider.getBoard()
+      const origNow = originalDateNow
+      Date.now = () => origNow() + 31_000
+      await provider.getBoard()
+      // Both reads must actually sync (the +31s skip clears the poll throttle);
+      // otherwise a single warning here would prove nothing about dedup.
+      expect(calls.filter((c) => c.url.includes('/rest/api/3/search/jql'))).toHaveLength(2)
+      expect(warn.messages).toHaveLength(1)
+    } finally {
+      warn.restore()
+    }
+  })
 })

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

@@ -182,6 +182,47 @@ describe('jira-wiring', () => {
     expect(err.message).toContain('Bulk commands')
   })
 
+  test('kanban board init under KANBAN_PROVIDER=jira keeps the SQLite remote local-only error', async () => {
+    const { dbPath } = makeDb()
+    setJiraRequiredEnv()
+    const result = await run(['--db', dbPath, 'board', 'init']).catch((err: unknown) => ({
+      error: err as KanbanError,
+    }))
+    expect('error' in result).toBe(true)
+    const err = (result as { error: KanbanError }).error
+    expect(err).toBeInstanceOf(KanbanError)
+    expect(err.code).toBe(ErrorCode.UNSUPPORTED_OPERATION)
+    expect(err.message).toContain('Board initialization is only available in local mode')
+    expect(err.message).not.toContain('KANBAN_STORAGE=postgres')
+  })
+
+  test('kanban board reset under KANBAN_PROVIDER=jira keeps the SQLite remote local-only error', async () => {
+    const { dbPath } = makeDb()
+    setJiraRequiredEnv()
+    const result = await run(['--db', dbPath, 'board', 'reset']).catch((err: unknown) => ({
+      error: err as KanbanError,
+    }))
+    expect('error' in result).toBe(true)
+    const err = (result as { error: KanbanError }).error
+    expect(err).toBeInstanceOf(KanbanError)
+    expect(err.code).toBe(ErrorCode.UNSUPPORTED_OPERATION)
+    expect(err.message).toContain('Board reset is only available in local mode')
+    expect(err.message).not.toContain('KANBAN_STORAGE=postgres')
+  })
+
+  test('kanban unknown board action under KANBAN_PROVIDER=jira remains an unknown command', async () => {
+    const { dbPath } = makeDb()
+    setJiraRequiredEnv()
+    const result = await run(['--db', dbPath, 'board', 'nope']).catch((err: unknown) => ({
+      error: err as KanbanError,
+    }))
+    expect('error' in result).toBe(true)
+    const err = (result as { error: KanbanError }).error
+    expect(err).toBeInstanceOf(KanbanError)
+    expect(err.code).toBe(ErrorCode.UNKNOWN_COMMAND)
+    expect(err.message).toContain("Unknown board command 'nope'")
+  })
+
   test('kanban config set-member under KANBAN_PROVIDER=jira exits with UNSUPPORTED_OPERATION', async () => {
     const { dbPath } = makeDb()
     setJiraRequiredEnv()

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

@@ -1,5 +1,8 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
 import { Database } from 'bun:sqlite'
+import type { BoardConfig, BoardView, Task } from '../types'
+import { LinearClient } from '../providers/linear-client'
+import { LinearProviderCore, type LinearCachePort } from '../providers/linear-core'
 import { LinearProvider } from '../providers/linear'
 import {
   initLinearCacheSchema,
@@ -8,6 +11,68 @@ import {
   upsertIssues,
 } from '../providers/linear-cache'
 
+function taskWithEmptyProviderId(): Task {
+  return {
+    id: 'linear:issue-1',
+    providerId: '',
+    externalRef: 'ENG-1',
+    url: 'https://linear.app/x/issue/ENG-1',
+    title: 'Issue 1',
+    description: '',
+    column_id: 'state-1',
+    position: 0,
+    priority: 'low',
+    assignee: '',
+    assignees: [],
+    labels: [],
+    comment_count: 0,
+    project: '',
+    metadata: '{}',
+    created_at: '2026-01-01T00:00:00Z',
+    updated_at: '2026-01-02T00:00:00Z',
+    version: '2026-01-02T00:00:00Z',
+    source_updated_at: '2026-01-02T00:00:00Z',
+  }
+}
+
+function fakeLinearCache(task: Task): LinearCachePort {
+  const meta = {
+    team: { id: 'team-1', key: 'ENG', name: 'Engineering' },
+    lastSyncAt: new Date().toISOString(),
+    lastFullSyncAt: null,
+    lastIssueUpdatedAt: '2026-01-02T00:00:00Z',
+    lastWebhookAt: null,
+  }
+  return {
+    ready: Promise.resolve(),
+    loadSyncMeta: async () => meta,
+    saveSyncMeta: async () => {},
+    replaceStates: async () => {},
+    upsertUsers: async () => {},
+    upsertProjects: async () => {},
+    upsertIssues: async () => {},
+    deleteIssue: async () => {},
+    pruneIssues: async () => {},
+    adjustIssueCommentCount: async () => {},
+    saveActivity: async () => {},
+    getCachedActivity: async () => [],
+    getCachedColumns: async () => [],
+    getCachedBoard: async (): Promise<BoardView> => ({ columns: [] }),
+    getCachedTask: async () => task,
+    getCachedTasks: async () => [task],
+    getCachedConfig: async (): Promise<BoardConfig> => ({
+      members: [],
+      projects: [],
+      provider: 'linear',
+      discoveredAssignees: [],
+      discoveredProjects: [],
+    }),
+    findUserIdByName: async () => null,
+    findProjectIdByName: async () => null,
+    resolveIssueId: async () => 'issue-1',
+  }
+}
+
 let db: Database
 let originalFetch: typeof fetch
 let requests: Array<{ query: string; variables: Record<string, unknown> }>
@@ -206,6 +271,22 @@ describe('LinearProvider.comment', () => {
     ])
   })
 
+  test('uses the unprefixed task id when providerId is empty', async () => {
+    const provider = new LinearProviderCore(
+      fakeLinearCache(taskWithEmptyProviderId()),
+      'team-1',
+      new LinearClient('lin_api_test'),
+    )
+
+    await provider.listComments('ENG-1')
+
+    expect(requests[0]?.query).toContain('query IssueComments')
+    expect(requests[0]?.variables).toEqual({
+      issueId: 'issue-1',
+      after: null,
+    })
+  })
+
   test('queries a single Linear comment by id', async () => {
     const provider = new LinearProvider(db, 'team-1', 'lin_api_test')
 

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

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
 import { Database } from 'bun:sqlite'
 import { LinearProvider } from '../providers/linear'
 import {
+  getCachedLinearActivity,
   getCachedTasks,
   initLinearCacheSchema,
   loadSyncMeta,
@@ -666,6 +667,112 @@ describe('LinearProvider sync', () => {
     expect(loadSyncMeta(db).lastFullSyncAt).not.toBeNull()
   })
 
+  test('history ingest preserves activity from completed batches before a later batch fails', async () => {
+    saveSyncMeta(db, {
+      team: { id: 'team-1', key: 'R2P', name: 'R2pi' },
+      lastSyncAt: '2026-01-01T00:00:00Z',
+      lastFullSyncAt: '2026-01-01T00:00:00Z',
+      lastIssueUpdatedAt: '2026-01-01T00:00:00Z',
+    })
+    const issues = Array.from({ length: 6 }, (_, i) =>
+      linearIssue({
+        id: `issue-${i + 1}`,
+        identifier: `R2P-${i + 1}`,
+        updatedAt: '2026-01-02T00:00:00Z',
+      }),
+    )
+
+    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: [], pageInfo: { hasNextPage: false, endCursor: null } } },
+          }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        )
+      }
+      if (body.query.includes('query Projects')) {
+        return new Response(
+          JSON.stringify({
+            data: { projects: { nodes: [], pageInfo: { hasNextPage: false, endCursor: null } } },
+          }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        )
+      }
+      if (body.query.includes('query Issues')) {
+        return new Response(
+          JSON.stringify({
+            data: { issues: { nodes: issues, pageInfo: { hasNextPage: false, endCursor: null } } },
+          }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        )
+      }
+      if (body.query.includes('query IssueHistory')) {
+        const issueId = String(body.variables.issueId)
+        if (issueId === 'issue-6') {
+          return new Response('history failed', { status: 500 })
+        }
+        return new Response(
+          JSON.stringify({
+            data: {
+              issue: {
+                history: {
+                  nodes: [
+                    {
+                      id: `hist-${issueId}`,
+                      createdAt: '2026-01-02T00:00:00Z',
+                      fromState: { id: 'state-0' },
+                      toState: { id: 'state-1' },
+                    },
+                  ],
+                  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:01:00Z')
+    try {
+      const provider = new LinearProvider(db, 'R2P', 'lin_api_test')
+      await provider.getBoard()
+    } finally {
+      Date.now = originalDateNow
+    }
+
+    expect(
+      getCachedLinearActivity(db)
+        .map((row) => row.issue_id)
+        .sort(),
+    ).toEqual(['issue-1', 'issue-2', 'issue-3', 'issue-4', 'issue-5'])
+  })
+
   test('counts comments beyond the inline first page instead of capping at the page length', async () => {
     saveSyncMeta(db, {
       team: { id: 'team-1', key: 'R2P', name: 'R2pi' },

package/src/__tests__/linear-state-resolution.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'bun:test'
+
+import { resolveLinearState, type LinearStateRow } from '../providers/linear-cache'
+
+describe('resolveLinearState', () => {
+  const state = (id: string, name: string): LinearStateRow => ({
+    id,
+    name,
+    position: 0,
+    color: null,
+    type: null,
+    created_at: '2026-01-01T00:00:00.000Z',
+    updated_at: '2026-01-01T00:00:00.000Z',
+  })
+
+  test('matches by exact id first', () => {
+    const states = [state('state-1', 'Todo'), state('state-2', 'In Progress')]
+    expect(resolveLinearState(states, 'state-2').id).toBe('state-2')
+  })
+
+  test('matches by case-insensitive name', () => {
+    const states = [state('state-1', 'In Progress')]
+    expect(resolveLinearState(states, 'in progress').id).toBe('state-1')
+  })
+
+  test("resolves a separator-collapsed trigger string ('in-progress') to the 'In Progress' state", () => {
+    const states = [state('state-1', 'Todo'), state('state-2', 'In Progress')]
+    expect(resolveLinearState(states, 'in-progress').id).toBe('state-2')
+    expect(resolveLinearState(states, 'InProgress').id).toBe('state-2')
+    expect(resolveLinearState(states, 'in_progress').id).toBe('state-2')
+  })
+
+  test('exact case-insensitive name wins over a separator-insensitive collision', () => {
+    // 'To Do' and 'Todo' both normalize to 'todo'; an exact lowercase hit must
+    // not be derailed into the ambiguity branch.
+    const states = [state('state-1', 'To Do'), state('state-2', 'Todo')]
+    expect(resolveLinearState(states, 'todo').id).toBe('state-2')
+  })
+
+  test('rejects a separator-insensitive match that collapses two distinct states', () => {
+    const states = [state('state-1', 'To Do'), state('state-2', 'To-Do')]
+    expect(() => resolveLinearState(states, 'Todo')).toThrow(/ambiguous/)
+  })
+
+  test('rejects duplicate case-insensitive state names as ambiguous', () => {
+    const states = [state('state-1', 'Done'), state('state-2', 'done')]
+    expect(() => resolveLinearState(states, 'DONE')).toThrow(/ambiguous/)
+  })
+
+  test('empty / separator-only input does not match a separator-only state name', () => {
+    const states = [state('state-1', '---'), state('state-2', 'To Do')]
+    expect(() => resolveLinearState(states, '   ')).toThrow(/No Linear workflow state matching/)
+    expect(() => resolveLinearState(states, '!!!')).toThrow(/No Linear workflow state matching/)
+  })
+
+  test('throws COLUMN_NOT_FOUND when nothing matches', () => {
+    const states = [state('state-1', 'Todo')]
+    expect(() => resolveLinearState(states, 'Done')).toThrow(/No Linear workflow state matching/)
+  })
+})