@andypai/agent-kanban 0.6.4 → 0.6.5

package/src/providers/jira-core.ts

@@ -48,6 +48,7 @@ import type {
 } from './types'
 import { DEFAULT_POLLING_SYNC_INTERVAL_MS } from '../sync-config'
 import { warnOnce } from './warn-once'
+import { applyTaskFilters, forEachWithConcurrency, SyncGate, syncStatusFromMeta } from './sync-core'
 
 export const FULL_RECONCILE_INTERVAL_MS = 5 * 60_000
 
@@ -158,6 +159,36 @@ export interface JiraCachePort {
   resolveIssueId(lookup: string): Promise<string | null>
 }
 
+type JiraCacheIssue = Parameters<JiraCachePort['upsertIssues']>[0][number]
+
+// Map a Jira API issue to the cache upsert row. Shared by bulk sync, direct
+// hydrate, and webhook ingest so every path caches the same issue shape.
+function toCacheIssue(
+  issue: JiraIssue,
+  baseUrl: string,
+  fallbackProjectKey: string,
+): JiraCacheIssue {
+  return {
+    id: issue.id,
+    key: issue.key,
+    summary: issue.fields.summary,
+    descriptionText: issue.fields.description
+      ? adfToPlainText(issue.fields.description as AdfDocument)
+      : '',
+    statusId: issue.fields.status.id,
+    priorityName: issue.fields.priority?.name ?? null,
+    issueTypeName: issue.fields.issuetype?.name ?? '',
+    assigneeAccountId: issue.fields.assignee?.accountId ?? null,
+    assigneeName: issue.fields.assignee?.displayName ?? null,
+    labels: issue.fields.labels ?? [],
+    commentCount: issue.fields.comment?.total ?? 0,
+    projectKey: issue.fields.project?.key ?? fallbackProjectKey,
+    url: `${baseUrl}/browse/${issue.key}`,
+    createdAt: issue.fields.created,
+    updatedAt: issue.fields.updated,
+  }
+}
+
 /**
  * Shared Jira provider business logic (sync orchestration, hydration, writes,
  * transitions, comments, webhook dispatch, activity mapping). Concrete providers
@@ -168,9 +199,7 @@ export class JiraProviderCore implements KanbanProvider {
   readonly type = 'jira' as const
   protected readonly client: JiraClient
   protected readonly pollingSyncIntervalMs: number
-  // When a server-side background warmer owns cache refresh, request-path syncs
-  // are suppressed once the cache is warm so reads/writes never block on Jira I/O.
-  private backgroundManaged = false
+  private readonly syncGate: SyncGate
 
   constructor(
     protected readonly cache: JiraCachePort,
@@ -178,6 +207,7 @@ export class JiraProviderCore implements KanbanProvider {
     client?: JiraClient,
   ) {
     this.pollingSyncIntervalMs = config.pollingSyncIntervalMs ?? DEFAULT_POLLING_SYNC_INTERVAL_MS
+    this.syncGate = new SyncGate(this.pollingSyncIntervalMs)
     this.client =
       client ??
       new JiraClient({
@@ -194,7 +224,6 @@ export class JiraProviderCore implements KanbanProvider {
   protected async sync(force = false, viaWarmer = false): Promise<void> {
     await this.cache.ready
     const meta = await this.cache.loadSyncMeta()
-    const lastSyncAtMs = meta.lastSyncAt ? Date.parse(meta.lastSyncAt) : 0
     // Server mode: a background warmer (syncCache(), viaWarmer=true) owns refresh.
     // Once the cache has synced at least once (lastSyncAt persisted), implicit
     // request-path reads serve the warm cache instead of blocking on a Jira
@@ -202,9 +231,8 @@ export class JiraProviderCore implements KanbanProvider {
     // (~minutes) and would otherwise exceed the HTTP idle timeout. Forced syncs
     // (writes' read-after-write) and the warmer still run; CLI mode and cold start
     // (no prior sync) fall through and sync synchronously, preserving freshness.
-    if (this.backgroundManaged && !force && !viaWarmer && lastSyncAtMs) return
+    if (this.syncGate.shouldSkip({ force, viaWarmer, lastSyncAt: meta.lastSyncAt })) return
     const now = Date.now()
-    if (!force && lastSyncAtMs && now - lastSyncAtMs < this.pollingSyncIntervalMs) return
     // `force` only bypasses the poll throttle; it must NOT imply a full
     // 1970-based reconcile, which re-fetches every issue plus a per-issue
     // changelog call (~minutes). Writes get read-after-write freshness from
@@ -216,10 +244,16 @@ export class JiraProviderCore implements KanbanProvider {
     await this.cache.saveTeamInfo({ id: project.id, key: project.key, name: project.name })
 
     // 2. Columns: board path OR status fallback path.
+    // The projection buckets issues by status-id membership in a column's
+    // status_ids; a status id present on an issue but in no column is cached but
+    // invisible to every listTasks({column}). Track the mapped set so we can
+    // surface such unmapped statuses below instead of dropping them silently.
+    const mappedStatusIds = new Set<string>()
     if (this.config.boardId !== undefined) {
       const boardCfg = await this.client.getBoardColumns(this.config.boardId)
       const boardId = this.config.boardId
       const rows = jiraBoardColumnRows(boardId, boardCfg.columnConfig.columns)
+      for (const row of rows) for (const id of row.statusIds) mappedStatusIds.add(id)
       await this.cache.replaceColumns(rows, fullReconcile)
     } else {
       const statusCats = await this.client.getProjectStatuses(project.key)
@@ -239,8 +273,11 @@ export class JiraProviderCore implements KanbanProvider {
         statusIds: [s.id],
         source: 'status' as const,
       }))
+      for (const row of rows) for (const id of row.statusIds) mappedStatusIds.add(id)
       await this.cache.replaceColumns(rows, fullReconcile)
     }
+    // Issue statuses seen this sync that map to no column (statusId → name).
+    const unmappedStatuses = new Map<string, string>()
 
     // 3. Catalogs: users + priorities + issue types in parallel.
     // NOTE: listAssignableUsers is capped at 100 in T04; tenants with more
@@ -317,25 +354,7 @@ export class JiraProviderCore implements KanbanProvider {
       })
 
       await this.cache.upsertIssues(
-        page.issues.map((issue) => ({
-          id: issue.id,
-          key: issue.key,
-          summary: issue.fields.summary,
-          descriptionText: issue.fields.description
-            ? adfToPlainText(issue.fields.description as AdfDocument)
-            : '',
-          statusId: issue.fields.status.id,
-          priorityName: issue.fields.priority?.name ?? null,
-          issueTypeName: issue.fields.issuetype?.name ?? '',
-          assigneeAccountId: issue.fields.assignee?.accountId ?? null,
-          assigneeName: issue.fields.assignee?.displayName ?? null,
-          labels: issue.fields.labels ?? [],
-          commentCount: issue.fields.comment?.total ?? 0,
-          projectKey: issue.fields.project?.key ?? project.key,
-          url: `${this.config.baseUrl}/browse/${issue.key}`,
-          createdAt: issue.fields.created,
-          updatedAt: issue.fields.updated,
-        })),
+        page.issues.map((issue) => toCacheIssue(issue, this.config.baseUrl, project.key)),
       )
 
       for (const issue of page.issues) {
@@ -343,19 +362,22 @@ export class JiraProviderCore implements KanbanProvider {
         if (newestUpdatedAt === null || issue.fields.updated > newestUpdatedAt) {
           newestUpdatedAt = issue.fields.updated
         }
+        if (!mappedStatusIds.has(issue.fields.status.id)) {
+          unmappedStatuses.set(issue.fields.status.id, issue.fields.status.name)
+        }
       }
 
       // Fetch changelog per changed issue so the poll-based
       // `moved` trigger in @garage/dispatch works. Server-side dedupe
       // keyed on (issue_id, history_id, item_field) keeps this cheap
       // even if the same issue is updated repeatedly.
-      for (const issue of page.issues) {
+      await forEachWithConcurrency(page.issues, 5, async (issue) => {
         await this.ingestIssueActivity(issue.id).catch((err) => {
           // Activity is best-effort; the main sync shouldn't fail if
           // one changelog call 404s or rate-limits.
           console.warn(`[jira] activity fetch for ${issue.key} failed:`, err)
         })
-      }
+      })
 
       const decision = decideJiraPagination(page, seenPageTokens)
       if (decision.nextToken !== undefined) {
@@ -375,6 +397,15 @@ export class JiraProviderCore implements KanbanProvider {
       break
     }
 
+    // Surface issues whose status maps to no column. They are cached but invisible
+    // to every listTasks({column}) and getCachedBoard — a silent drop that strands
+    // tickets (e.g. a poller's trigger column never sees them). Warn once per
+    // (project, status) so a misconfigured board or a status missing from the
+    // project's status catalog is observable rather than silent.
+    for (const [statusId, statusName] of unmappedStatuses) {
+      this.warnUnmappedStatus(project.key, statusId, statusName)
+    }
+
     if (!paginationComplete) {
       // The scan ended early (stalled/contradictory cursor). Leave sync metadata
       // unchanged so this partial result is not recorded as a clean sync: lastSyncAt
@@ -409,6 +440,18 @@ export class JiraProviderCore implements KanbanProvider {
     return resolveJiraColumnId(await this.cache.getColumns(), input)
   }
 
+  private warnUnmappedStatus(projectKey: string, statusId: string, statusName: string): void {
+    const hint =
+      this.config.boardId !== undefined
+        ? `it is not on board ${this.config.boardId}`
+        : `it is absent from the project status catalog`
+    warnOnce(
+      `jira-unmapped-status:${projectKey}:${statusId}`,
+      `[jira] ${projectKey} status '${statusName}' (${statusId}) maps to no column (${hint}); ` +
+        `issues in this status are cached but invisible to listTasks/getBoard`,
+    )
+  }
+
   private async buildBoardConfig(): Promise<BoardConfig> {
     const cache = await this.cache.getCachedConfig()
     const members = cache.users.map((u) => ({
@@ -434,16 +477,12 @@ export class JiraProviderCore implements KanbanProvider {
   }
 
   setBackgroundManaged(managed: boolean): void {
-    this.backgroundManaged = managed
+    this.syncGate.setBackgroundManaged(managed)
   }
 
   async getSyncStatus(): Promise<ProviderSyncStatus> {
     const meta = await this.cache.loadSyncMeta()
-    return {
-      lastSyncAt: meta.lastSyncAt,
-      lastFullSyncAt: meta.lastFullSyncAt,
-      lastWebhookAt: meta.lastWebhookAt,
-    }
+    return syncStatusFromMeta(meta)
   }
 
   async getContext(): Promise<ProviderContext> {
@@ -488,15 +527,10 @@ export class JiraProviderCore implements KanbanProvider {
   async listTasks(filters: TaskListFilters = {}): Promise<Task[]> {
     await this.sync()
     const columnId = filters.column ? await this.resolveColumnId(filters.column) : undefined
-    let tasks = await this.cache.getCachedTasks(columnId ? { columnId } : undefined)
-    if (filters.priority) tasks = tasks.filter((t) => t.priority === filters.priority)
-    if (filters.assignee) tasks = tasks.filter((t) => t.assignee === filters.assignee)
-    if (filters.project) tasks = tasks.filter((t) => t.project === filters.project)
-    if (filters.sort === 'title') tasks = [...tasks].sort((a, b) => a.title.localeCompare(b.title))
-    if (filters.sort === 'updated')
-      tasks = [...tasks].sort((a, b) => b.updated_at.localeCompare(a.updated_at))
-    if (filters.limit) tasks = tasks.slice(0, filters.limit)
-    return tasks
+    return applyTaskFilters(
+      await this.cache.getCachedTasks(columnId ? { columnId } : undefined),
+      filters,
+    )
   }
 
   async getTask(idOrRef: string): Promise<Task> {
@@ -588,25 +622,7 @@ export class JiraProviderCore implements KanbanProvider {
     // it rather than threading an unreachable null through every caller.
     const issue = await this.client.getIssue(key)
     await this.cache.upsertIssues([
-      {
-        id: issue.id,
-        key: issue.key,
-        summary: issue.fields.summary,
-        descriptionText: issue.fields.description
-          ? adfToPlainText(issue.fields.description as AdfDocument)
-          : '',
-        statusId: issue.fields.status.id,
-        priorityName: issue.fields.priority?.name ?? null,
-        issueTypeName: issue.fields.issuetype?.name ?? '',
-        assigneeAccountId: issue.fields.assignee?.accountId ?? null,
-        assigneeName: issue.fields.assignee?.displayName ?? null,
-        labels: issue.fields.labels ?? [],
-        commentCount: issue.fields.comment?.total ?? 0,
-        projectKey: issue.fields.project?.key ?? this.config.projectKey,
-        url: `${this.config.baseUrl}/browse/${issue.key}`,
-        createdAt: issue.fields.created,
-        updatedAt: issue.fields.updated,
-      },
+      toCacheIssue(issue, this.config.baseUrl, this.config.projectKey),
     ])
     // Ingest the changelog like the sync loop does, so a just-applied transition
     // is recorded in jira_activity immediately (backs getActivity and the
@@ -894,25 +910,7 @@ export class JiraProviderCore implements KanbanProvider {
         }
       }
       await this.cache.upsertIssues([
-        {
-          id: issue.id,
-          key: issue.key,
-          summary: issue.fields.summary,
-          descriptionText: issue.fields.description
-            ? adfToPlainText(issue.fields.description as AdfDocument)
-            : '',
-          statusId: issue.fields.status.id,
-          priorityName: issue.fields.priority?.name ?? null,
-          issueTypeName: issue.fields.issuetype?.name ?? '',
-          assigneeAccountId: issue.fields.assignee?.accountId ?? null,
-          assigneeName: issue.fields.assignee?.displayName ?? null,
-          labels: issue.fields.labels ?? [],
-          commentCount: issue.fields.comment?.total ?? 0,
-          projectKey,
-          url: `${this.config.baseUrl}/browse/${issue.key}`,
-          createdAt: issue.fields.created,
-          updatedAt: issue.fields.updated,
-        },
+        toCacheIssue(issue, this.config.baseUrl, this.config.projectKey),
       ])
       if (event === 'jira:issue_updated') {
         await this.ingestIssueActivity(issue.id).catch((err) => {

package/src/providers/linear-cache.ts

@@ -1,5 +1,9 @@
 import type { Database } from 'bun:sqlite'
+import { normalizeColumnName } from '../column-roles'
+import { ErrorCode, KanbanError } from '../errors'
 import type { BoardConfig, BoardView, ProviderTeamInfo, Task } from '../types'
+import { linearTaskFromRow, type LinearTaskRow } from './cache-task-mappers'
+import { parseProviderTeamInfo } from './team-info'
 
 export interface LinearStateRow {
   id: string
@@ -19,6 +23,39 @@ export interface LinearSyncMeta {
   lastWebhookAt: string | null
 }
 
+function ambiguousStateError(input: string, matches: LinearStateRow[]): KanbanError {
+  return new KanbanError(
+    ErrorCode.COLUMN_NOT_FOUND,
+    `Linear state name '${input}' is ambiguous; use one of these state ids: ${matches
+      .map((state) => state.id)
+      .join(', ')}`,
+  )
+}
+
+// Resolves a user-supplied column reference to a cached workflow state, trying
+// (1) exact id, (2) case-insensitive name, (3) separator-insensitive name
+// ('in-progress' → 'In Progress') — mirroring resolveJiraColumnId so collapsed
+// trigger strings resolve on both providers instead of throwing
+// COLUMN_NOT_FOUND. Exact passes run first so a precise reference is never
+// overridden by a normalized-name collision; name lookups matching multiple
+// states are rejected as ambiguous so the caller picks an id. A token that
+// collapses to empty is skipped so punctuation-only input never matches.
+export function resolveLinearState(states: LinearStateRow[], input: string): LinearStateRow {
+  const byId = states.find((state) => state.id === input)
+  if (byId) return byId
+  const lower = input.toLowerCase()
+  const byName = states.filter((state) => state.name.toLowerCase() === lower)
+  if (byName.length === 1) return byName[0]!
+  if (byName.length > 1) throw ambiguousStateError(input, byName)
+  const normalized = normalizeColumnName(input)
+  if (normalized !== '') {
+    const byNormalized = states.filter((state) => normalizeColumnName(state.name) === normalized)
+    if (byNormalized.length === 1) return byNormalized[0]!
+    if (byNormalized.length > 1) throw ambiguousStateError(input, byNormalized)
+  }
+  throw new KanbanError(ErrorCode.COLUMN_NOT_FOUND, `No Linear workflow state matching '${input}'`)
+}
+
 export function initLinearCacheSchema(db: Database): void {
   db.run(`
     CREATE TABLE IF NOT EXISTS linear_sync_meta (
@@ -200,9 +237,8 @@ export function saveSyncMeta(db: Database, meta: Partial<LinearSyncMeta>): void
 }
 
 export function loadSyncMeta(db: Database): LinearSyncMeta {
-  const teamRaw = getMeta(db, 'team')
   return {
-    team: teamRaw ? (JSON.parse(teamRaw) as ProviderTeamInfo) : null,
+    team: parseProviderTeamInfo(getMeta(db, 'team')),
     lastSyncAt: getMeta(db, 'lastSyncAt'),
     lastFullSyncAt: getMeta(db, 'lastFullSyncAt'),
     lastIssueUpdatedAt: getMeta(db, 'lastIssueUpdatedAt'),
@@ -442,70 +478,7 @@ export function getCachedColumns(db: Database): LinearStateRow[] {
   return db.query('SELECT * FROM linear_states ORDER BY position, name').all() as LinearStateRow[]
 }
 
-function mapPriority(priority: number): Task['priority'] {
-  switch (priority) {
-    case 1:
-      return 'urgent'
-    case 2:
-      return 'high'
-    case 3:
-      return 'medium'
-    case 0:
-    case 4:
-    default:
-      return 'low'
-  }
-}
-
-interface LinearIssueRow {
-  id: string
-  identifier: string
-  title: string
-  description: string
-  state_id: string
-  state_position: number
-  priority: number
-  assignee_name: string
-  project_name: string
-  labels: string
-  comment_count: number
-  url: string | null
-  created_at: string
-  updated_at: string
-}
-
-function parseLabels(raw: string): string[] {
-  try {
-    const parsed: unknown = JSON.parse(raw)
-    return Array.isArray(parsed) ? parsed.filter((v): v is string => typeof v === 'string') : []
-  } catch {
-    return []
-  }
-}
-
-function taskFromRow(row: LinearIssueRow): Task {
-  return {
-    id: `linear:${row.id}`,
-    providerId: row.id,
-    externalRef: row.identifier,
-    url: row.url,
-    title: row.title,
-    description: row.description,
-    column_id: row.state_id,
-    position: row.state_position,
-    priority: mapPriority(row.priority),
-    assignee: row.assignee_name,
-    assignees: row.assignee_name ? [row.assignee_name] : [],
-    labels: parseLabels(row.labels),
-    comment_count: row.comment_count,
-    project: row.project_name,
-    metadata: '{}',
-    created_at: row.created_at,
-    updated_at: row.updated_at,
-    version: row.updated_at,
-    source_updated_at: row.updated_at,
-  }
-}
+type LinearIssueRow = LinearTaskRow
 
 export function getCachedBoard(db: Database): BoardView {
   const columns = getCachedColumns(db)
@@ -520,7 +493,7 @@ export function getCachedBoard(db: Database): BoardView {
              ORDER BY updated_at DESC, title ASC`,
           )
           .all({ $state_id: column.id }) as LinearIssueRow[]
-      ).map(taskFromRow),
+      ).map(linearTaskFromRow),
     })),
   }
 }
@@ -534,7 +507,7 @@ export function getCachedTask(db: Database, lookup: string): Task | null {
        LIMIT 1`,
     )
     .get({ $lookup: normalized }) as LinearIssueRow | null
-  return row ? taskFromRow(row) : null
+  return row ? linearTaskFromRow(row) : null
 }
 
 export function getCachedTasks(db: Database): Task[] {
@@ -542,7 +515,7 @@ export function getCachedTasks(db: Database): Task[] {
     db
       .query('SELECT * FROM linear_issues ORDER BY updated_at DESC, title ASC')
       .all() as LinearIssueRow[]
-  ).map(taskFromRow)
+  ).map(linearTaskFromRow)
 }
 
 export function getCachedConfig(db: Database): BoardConfig {

package/src/providers/linear-core.ts

@@ -24,7 +24,12 @@ import {
   type LinearComment,
   type LinearIssue,
 } from './linear-client'
-import type { LinearActivityRow, LinearStateRow, LinearSyncMeta } from './linear-cache'
+import {
+  resolveLinearState,
+  type LinearActivityRow,
+  type LinearStateRow,
+  type LinearSyncMeta,
+} from './linear-cache'
 import { providerUpstreamError, unsupportedOperation } from './errors'
 import type {
   CreateTaskInput,
@@ -36,22 +41,16 @@ import type {
 } from './types'
 import { DEFAULT_POLLING_SYNC_INTERVAL_MS } from '../sync-config'
 import { warnOnce } from './warn-once'
+import {
+  applyTaskFilters,
+  maxSyncTimestamp,
+  parseSyncTimestamp,
+  SyncGate,
+  syncStatusFromMeta,
+} from './sync-core'
 
 const FULL_RECONCILIATION_INTERVAL_MS = 5 * 60_000
 
-function parseTimestamp(value: string | null | undefined): number {
-  if (!value) return 0
-  const parsed = Date.parse(value)
-  return Number.isFinite(parsed) ? parsed : 0
-}
-
-function maxTimestamp(a: string | null | undefined, b: string | null | undefined): string | null {
-  const aMs = parseTimestamp(a)
-  const bMs = parseTimestamp(b)
-  if (!aMs && !bMs) return null
-  return aMs >= bMs ? (a ?? null) : (b ?? null)
-}
-
 function toLinearPriority(priority: Task['priority'] | undefined): number | undefined {
   switch (priority) {
     case 'urgent':
@@ -169,16 +168,16 @@ export interface LinearCachePort {
  */
 export class LinearProviderCore implements KanbanProvider {
   readonly type = 'linear' as const
-  // When a server-side background warmer owns cache refresh, request-path syncs
-  // are suppressed once the cache is warm so reads/writes never block on Linear I/O.
-  private backgroundManaged = false
+  private readonly syncGate: SyncGate
 
   constructor(
     protected readonly cache: LinearCachePort,
     protected readonly teamId: string,
     protected readonly client: LinearClient,
     protected readonly pollingSyncIntervalMs = DEFAULT_POLLING_SYNC_INTERVAL_MS,
-  ) {}
+  ) {
+    this.syncGate = new SyncGate(this.pollingSyncIntervalMs)
+  }
 
   async initialize(): Promise<void> {
     await this.cache.ready
@@ -201,16 +200,14 @@ export class LinearProviderCore implements KanbanProvider {
   protected async sync(force = false, viaWarmer = false): Promise<void> {
     await this.cache.ready
     const meta = await this.cache.loadSyncMeta()
-    const lastSyncAtMs = parseTimestamp(meta.lastSyncAt)
-    const lastFullSyncAtMs = parseTimestamp(meta.lastFullSyncAt)
+    const lastFullSyncAtMs = parseSyncTimestamp(meta.lastFullSyncAt)
     // Server mode: a background warmer (syncCache(), viaWarmer=true) owns refresh.
     // Once the cache has synced at least once, implicit request-path reads serve the
     // warm cache instead of blocking on a Linear round-trip, which could exceed the
     // HTTP idle timeout. Forced syncs (writes' read-after-write) and the warmer
     // still run; CLI mode and cold start sync synchronously.
-    if (this.backgroundManaged && !force && !viaWarmer && lastSyncAtMs) return
+    if (this.syncGate.shouldSkip({ force, viaWarmer, lastSyncAt: meta.lastSyncAt })) return
     const now = Date.now()
-    if (!force && lastSyncAtMs && now - lastSyncAtMs < this.pollingSyncIntervalMs) return
 
     // `force` bypasses the poll throttle (above) for read-after-write freshness,
     // but does NOT imply a full workspace reconcile — that stays on its own
@@ -238,7 +235,7 @@ export class LinearProviderCore implements KanbanProvider {
       await this.cache.pruneIssues(issues.map((issue) => issue.id))
     }
 
-    const newestIssueTimestamp = maxTimestamp(
+    const newestIssueTimestamp = maxSyncTimestamp(
       meta.lastIssueUpdatedAt,
       issues.length > 0
         ? issues.reduce(
@@ -268,6 +265,9 @@ export class LinearProviderCore implements KanbanProvider {
   private async ingestTeamHistory(issueIds: string[], sinceIso: string | null): Promise<void> {
     if (issueIds.length === 0) return
     const concurrency = 5
+    // Manual windows rather than one mapWithConcurrency pass: each window's rows
+    // are persisted before the next window starts, so a mid-ingest failure keeps
+    // everything fetched so far.
     for (let i = 0; i < issueIds.length; i += concurrency) {
       const batch = issueIds.slice(i, i + concurrency)
       const results = await Promise.all(
@@ -319,6 +319,10 @@ export class LinearProviderCore implements KanbanProvider {
     return task
   }
 
+  private issueIdFor(task: Task): string {
+    return task.providerId || task.id.replace(/^linear:/, '')
+  }
+
   // Read-after-write refresh of a single issue. Re-fetching just the mutated
   // issue (and its history) keeps the post-write read fresh without paying for a
   // full team sync(true)/prune on every update or move.
@@ -345,17 +349,7 @@ export class LinearProviderCore implements KanbanProvider {
   }
 
   private async resolveState(column: string): Promise<Column> {
-    const states = await this.cache.getCachedColumns()
-    const match = states.find(
-      (state) => state.id === column || state.name.toLowerCase() === column.toLowerCase(),
-    )
-    if (!match) {
-      throw new KanbanError(
-        ErrorCode.COLUMN_NOT_FOUND,
-        `No Linear workflow state matching '${column}'`,
-      )
-    }
-    return match
+    return resolveLinearState(await this.cache.getCachedColumns(), column)
   }
 
   // Only invoked for non-empty names. A name that the cache cannot resolve is a
@@ -397,16 +391,12 @@ export class LinearProviderCore implements KanbanProvider {
   }
 
   setBackgroundManaged(managed: boolean): void {
-    this.backgroundManaged = managed
+    this.syncGate.setBackgroundManaged(managed)
   }
 
   async getSyncStatus(): Promise<ProviderSyncStatus> {
     const meta = await this.cache.loadSyncMeta()
-    return {
-      lastSyncAt: meta.lastSyncAt,
-      lastFullSyncAt: meta.lastFullSyncAt,
-      lastWebhookAt: meta.lastWebhookAt,
-    }
+    return syncStatusFromMeta(meta)
   }
 
   async getContext(): Promise<ProviderContext> {
@@ -449,14 +439,7 @@ export class LinearProviderCore implements KanbanProvider {
       const column = await this.resolveState(filters.column)
       tasks = tasks.filter((task) => task.column_id === column.id)
     }
-    if (filters.priority) tasks = tasks.filter((task) => task.priority === filters.priority)
-    if (filters.assignee) tasks = tasks.filter((task) => task.assignee === filters.assignee)
-    if (filters.project) tasks = tasks.filter((task) => task.project === filters.project)
-    if (filters.sort === 'title') tasks = [...tasks].sort((a, b) => a.title.localeCompare(b.title))
-    if (filters.sort === 'updated')
-      tasks = [...tasks].sort((a, b) => b.updated_at.localeCompare(a.updated_at))
-    if (filters.limit) tasks = tasks.slice(0, filters.limit)
-    return tasks
+    return applyTaskFilters(tasks, filters)
   }
 
   async getTask(idOrRef: string): Promise<Task> {
@@ -508,22 +491,24 @@ export class LinearProviderCore implements KanbanProvider {
     if (input.metadata !== undefined) {
       unsupportedOperation('Linear mode does not support metadata updates')
     }
-    const result = await this.client.updateIssue(task.providerId || task.id, updateInput)
+    const issueId = this.issueIdFor(task)
+    const result = await this.client.updateIssue(issueId, updateInput)
     if (!result.success) {
       throw new KanbanError(ErrorCode.PROVIDER_UPSTREAM_ERROR, 'Linear issue update failed')
     }
-    return this.hydrateIssue(task.providerId || task.id)
+    return this.hydrateIssue(issueId)
   }
 
   async moveTask(idOrRef: string, column: string): Promise<Task> {
     await this.sync()
     const task = await this.resolveTask(idOrRef)
     const state = await this.resolveState(column)
-    const result = await this.client.updateIssue(task.providerId || task.id, { stateId: state.id })
+    const issueId = this.issueIdFor(task)
+    const result = await this.client.updateIssue(issueId, { stateId: state.id })
     if (!result.success) {
       throw new KanbanError(ErrorCode.PROVIDER_UPSTREAM_ERROR, 'Linear issue move failed')
     }
-    return this.hydrateIssue(task.providerId || task.id)
+    return this.hydrateIssue(issueId)
   }
 
   async deleteTask(_idOrRef: string): Promise<Task> {
@@ -533,7 +518,7 @@ export class LinearProviderCore implements KanbanProvider {
   async listComments(idOrRef: string): Promise<TaskComment[]> {
     await this.sync()
     const task = await this.resolveTask(idOrRef)
-    const comments = await this.client.listComments(task.providerId || task.id)
+    const comments = await this.client.listComments(this.issueIdFor(task))
     return comments.map((comment) => this.toTaskComment(task, comment))
   }
 
@@ -547,11 +532,12 @@ export class LinearProviderCore implements KanbanProvider {
   async comment(idOrRef: string, body: string): Promise<TaskComment> {
     await this.sync()
     const task = await this.resolveTask(idOrRef)
-    const result = await this.client.commentCreate(task.providerId || task.id, body)
+    const issueId = this.issueIdFor(task)
+    const result = await this.client.commentCreate(issueId, body)
     if (!result.success || !result.comment) {
       throw new KanbanError(ErrorCode.PROVIDER_UPSTREAM_ERROR, 'Linear comment creation failed')
     }
-    await this.cache.adjustIssueCommentCount(task.providerId || task.id, 1)
+    await this.cache.adjustIssueCommentCount(issueId, 1)
     return this.toTaskComment(task, result.comment)
   }