@andypai/agent-kanban 0.6.2 → 0.6.3

package/src/providers/linear-core.ts

@@ -18,9 +18,14 @@ import {
   type WebhookResult,
 } from '../webhooks'
 import { LINEAR_CAPABILITIES } from './capabilities'
-import { LinearClient, resolveLabelIdsForCreate, type LinearComment } from './linear-client'
+import {
+  LinearClient,
+  resolveLabelIdsForCreate,
+  type LinearComment,
+  type LinearIssue,
+} from './linear-client'
 import type { LinearActivityRow, LinearStateRow, LinearSyncMeta } from './linear-cache'
-import { unsupportedOperation } from './errors'
+import { providerUpstreamError, unsupportedOperation } from './errors'
 import type {
   CreateTaskInput,
   KanbanProvider,
@@ -61,6 +66,33 @@ function toLinearPriority(priority: Task['priority'] | undefined): number | unde
   }
 }
 
+type CacheIssue = Parameters<LinearCachePort['upsertIssues']>[0][number]
+
+// Map a Linear API issue to the cache upsert row. Shared by the bulk sync and
+// the single-issue hydrate path so a read-after-write refresh caches exactly the
+// same shape as a full sync.
+function toCacheIssue(issue: LinearIssue): CacheIssue {
+  return {
+    id: issue.id,
+    identifier: issue.identifier,
+    title: issue.title,
+    description: issue.description ?? '',
+    priority: issue.priority ?? 0,
+    assigneeId: issue.assignee?.id ?? null,
+    assigneeName: issue.assignee?.name ?? null,
+    projectId: issue.project?.id ?? null,
+    projectName: issue.project?.name ?? null,
+    stateId: issue.state.id,
+    stateName: issue.state.name,
+    statePosition: issue.state.position,
+    labels: issue.labels ?? [],
+    commentCount: issue.commentCount,
+    url: issue.url ?? null,
+    createdAt: issue.createdAt,
+    updatedAt: issue.updatedAt,
+  }
+}
+
 /**
  * Storage-agnostic cache/repository port the Linear core depends on. The SQLite
  * (linear.ts) and Postgres (postgres-linear.ts) backends each provide an
@@ -179,8 +211,10 @@ export class LinearProviderCore implements KanbanProvider {
     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
+    // cadence so a single write isn't coupled to team-wide prune/refetch.
     const shouldFullSync =
-      force ||
       !lastFullSyncAtMs ||
       !meta.lastIssueUpdatedAt ||
       now - lastFullSyncAtMs >= FULL_RECONCILIATION_INTERVAL_MS
@@ -198,27 +232,7 @@ export class LinearProviderCore implements KanbanProvider {
     await this.cache.replaceStates(team.states)
     await this.cache.upsertUsers(users)
     await this.cache.upsertProjects(projects)
-    await this.cache.upsertIssues(
-      issues.map((issue) => ({
-        id: issue.id,
-        identifier: issue.identifier,
-        title: issue.title,
-        description: issue.description ?? '',
-        priority: issue.priority ?? 0,
-        assigneeId: issue.assignee?.id ?? null,
-        assigneeName: issue.assignee?.name ?? null,
-        projectId: issue.project?.id ?? null,
-        projectName: issue.project?.name ?? null,
-        stateId: issue.state.id,
-        stateName: issue.state.name,
-        statePosition: issue.state.position,
-        labels: issue.labels ?? [],
-        commentCount: issue.commentCount,
-        url: issue.url ?? null,
-        createdAt: issue.createdAt,
-        updatedAt: issue.updatedAt,
-      })),
-    )
+    await this.cache.upsertIssues(issues.map(toCacheIssue))
     if (shouldFullSync) {
       await this.cache.pruneIssues(issues.map((issue) => issue.id))
     }
@@ -304,6 +318,31 @@ export class LinearProviderCore implements KanbanProvider {
     return task
   }
 
+  // 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.
+  private async hydrateIssue(issueId: string): Promise<Task> {
+    const issue = await this.client.getIssue(issueId)
+    // Mirror the bulk sync's team scoping: it only caches issues from the
+    // configured team. If the issue vanished upstream or moved out of the team,
+    // drop the now out-of-scope local row instead of re-caching it, matching what
+    // a full reconcile would eventually prune.
+    if (!issue || (issue.teamId && issue.teamId !== (await this.resolvedTeamId()))) {
+      await this.cache.deleteIssue(issueId)
+      throw new KanbanError(ErrorCode.TASK_NOT_FOUND, `No task with id '${issueId}'`)
+    }
+    await this.cache.upsertIssues([toCacheIssue(issue)])
+    // Best-effort changelog ingest for the moved/updated issue so activity stays
+    // current; failures don't fail the write's read-after-write.
+    await this.ingestTeamHistory(
+      [issue.id],
+      (await this.cache.loadSyncMeta()).lastIssueUpdatedAt,
+    ).catch((err) => {
+      console.warn('[linear] issueHistory ingest failed:', err)
+    })
+    return this.resolveTask(issue.id)
+  }
+
   private async resolveState(column: string): Promise<Column> {
     const states = await this.cache.getCachedColumns()
     const match = states.find(
@@ -318,14 +357,25 @@ export class LinearProviderCore implements KanbanProvider {
     return match
   }
 
-  private async resolveAssigneeId(name?: string): Promise<string | undefined> {
-    if (!name) return undefined
-    return (await this.cache.findUserIdByName(name)) ?? undefined
+  // Only invoked for non-empty names. A name that the cache cannot resolve is a
+  // hard error rather than a silent drop/clear: callers handle "not provided"
+  // (undefined) and "clear" (empty string) before calling this.
+  private async resolveAssigneeId(name: string): Promise<string> {
+    const id = await this.cache.findUserIdByName(name)
+    if (!id) {
+      providerUpstreamError(
+        `Linear assignee '${name}' was not found in the cached user list. Try 'kanban task list --assignee' to see cached names.`,
+      )
+    }
+    return id
   }
 
-  private async resolveProjectId(name?: string): Promise<string | undefined> {
-    if (!name) return undefined
-    return (await this.cache.findProjectIdByName(name)) ?? undefined
+  private async resolveProjectId(name: string): Promise<string> {
+    const id = await this.cache.findProjectIdByName(name)
+    if (!id) {
+      providerUpstreamError(`Linear project '${name}' was not found in the cached project list.`)
+    }
+    return id
   }
 
   private toTaskComment(task: Task, comment: LinearComment): TaskComment {
@@ -423,35 +473,15 @@ export class LinearProviderCore implements KanbanProvider {
       title: input.title,
       description: input.description,
       priority: toLinearPriority(input.priority),
-      assigneeId: await this.resolveAssigneeId(input.assignee),
-      projectId: await this.resolveProjectId(input.project),
+      assigneeId: input.assignee ? await this.resolveAssigneeId(input.assignee) : undefined,
+      projectId: input.project ? await this.resolveProjectId(input.project) : undefined,
       labelIds,
     })
     if (!result.success || !result.issue) {
       throw new KanbanError(ErrorCode.PROVIDER_UPSTREAM_ERROR, 'Linear issue creation failed')
     }
     const issue = result.issue
-    await this.cache.upsertIssues([
-      {
-        id: issue.id,
-        identifier: issue.identifier,
-        title: issue.title,
-        description: issue.description ?? '',
-        priority: issue.priority ?? 0,
-        assigneeId: issue.assignee?.id ?? null,
-        assigneeName: issue.assignee?.name ?? issue.assignee?.displayName ?? '',
-        projectId: issue.project?.id ?? null,
-        projectName: issue.project?.name ?? '',
-        stateId: issue.state.id,
-        stateName: issue.state.name,
-        statePosition: issue.state.position,
-        labels: issue.labels ?? [],
-        commentCount: issue.commentCount,
-        url: issue.url ?? null,
-        createdAt: issue.createdAt,
-        updatedAt: issue.updatedAt,
-      },
-    ])
+    await this.cache.upsertIssues([toCacheIssue(issue)])
     return this.resolveTask(issue.id)
   }
 
@@ -469,9 +499,11 @@ export class LinearProviderCore implements KanbanProvider {
     if (input.description !== undefined) updateInput['description'] = input.description
     if (input.priority !== undefined) updateInput['priority'] = toLinearPriority(input.priority)
     if (input.assignee !== undefined)
-      updateInput['assigneeId'] = (await this.resolveAssigneeId(input.assignee)) ?? null
+      updateInput['assigneeId'] = input.assignee
+        ? await this.resolveAssigneeId(input.assignee)
+        : null
     if (input.project !== undefined)
-      updateInput['projectId'] = (await this.resolveProjectId(input.project)) ?? null
+      updateInput['projectId'] = input.project ? await this.resolveProjectId(input.project) : null
     if (input.metadata !== undefined) {
       unsupportedOperation('Linear mode does not support metadata updates')
     }
@@ -479,8 +511,7 @@ export class LinearProviderCore implements KanbanProvider {
     if (!result.success) {
       throw new KanbanError(ErrorCode.PROVIDER_UPSTREAM_ERROR, 'Linear issue update failed')
     }
-    await this.sync(true)
-    return this.resolveTask(task.providerId || task.id)
+    return this.hydrateIssue(task.providerId || task.id)
   }
 
   async moveTask(idOrRef: string, column: string): Promise<Task> {
@@ -491,8 +522,7 @@ export class LinearProviderCore implements KanbanProvider {
     if (!result.success) {
       throw new KanbanError(ErrorCode.PROVIDER_UPSTREAM_ERROR, 'Linear issue move failed')
     }
-    await this.sync(true)
-    return this.resolveTask(task.providerId || task.id)
+    return this.hydrateIssue(task.providerId || task.id)
   }
 
   async deleteTask(_idOrRef: string): Promise<Task> {

package/src/providers/postgres-local.ts

@@ -2,7 +2,7 @@ import type { Sql, TransactionSql } from 'postgres'
 
 import { ErrorCode, KanbanError } from '../errors'
 import { generateId } from '../id'
-import { selectDoneColumnIds, selectInProgressColumnIds } from '../column-roles'
+import { assembleBoardMetrics, classifyColumnRoles } from '../metrics-spec'
 import type {
   ActivityEntry,
   BoardBootstrap,
@@ -15,7 +15,8 @@ import type {
   TaskComment,
   TaskWithColumn,
 } from '../types'
-import { LOCAL_CAPABILITIES } from './capabilities'
+import { POSTGRES_LOCAL_CAPABILITIES } from './capabilities'
+import { unsupportedOperation } from './errors'
 import type {
   CreateTaskInput,
   KanbanProvider,
@@ -170,7 +171,10 @@ export class PostgresLocalProvider implements KanbanProvider {
         exited_at TEXT
       )
     `
-    await this.sql`ALTER TABLE tasks ADD COLUMN IF NOT EXISTS labels TEXT NOT NULL DEFAULT '[]'`
+    // Run column migrations before creating indexes — pre-existing databases
+    // miss columns added after the original tasks table, and CREATE TABLE IF NOT
+    // EXISTS won't add them (parity with SQLite migrateSchema).
+    await this.migrateTasksTable()
     await this.sql`CREATE INDEX IF NOT EXISTS idx_tasks_column_id ON tasks(column_id)`
     await this.sql`CREATE INDEX IF NOT EXISTS idx_tasks_priority ON tasks(priority)`
     await this.sql`CREATE INDEX IF NOT EXISTS idx_tasks_assignee ON tasks(assignee)`
@@ -182,6 +186,14 @@ export class PostgresLocalProvider implements KanbanProvider {
       .sql`CREATE INDEX IF NOT EXISTS idx_column_time_task_id ON column_time_tracking(task_id)`
   }
 
+  // Backfill columns added after the original tasks table shipped. Keep this in
+  // lockstep with src/db.ts:migrateSchema (project, labels, revision).
+  private async migrateTasksTable(): Promise<void> {
+    await this.sql`ALTER TABLE tasks ADD COLUMN IF NOT EXISTS project TEXT NOT NULL DEFAULT ''`
+    await this.sql`ALTER TABLE tasks ADD COLUMN IF NOT EXISTS labels TEXT NOT NULL DEFAULT '[]'`
+    await this.sql`ALTER TABLE tasks ADD COLUMN IF NOT EXISTS revision INTEGER NOT NULL DEFAULT 0`
+  }
+
   private async seedDefaultColumns(): Promise<void> {
     const [row] = await this.sql<
       { count: string | number }[]
@@ -284,7 +296,7 @@ export class PostgresLocalProvider implements KanbanProvider {
 
   async getContext(): Promise<ProviderContext> {
     await this.ready
-    return { provider: this.type, capabilities: LOCAL_CAPABILITIES, team: null }
+    return { provider: this.type, capabilities: POSTGRES_LOCAL_CAPABILITIES, team: null }
   }
 
   async getBootstrap(): Promise<BoardBootstrap> {
@@ -292,7 +304,7 @@ export class PostgresLocalProvider implements KanbanProvider {
     const metrics = await this.getMetrics()
     return {
       provider: this.type,
-      capabilities: LOCAL_CAPABILITIES,
+      capabilities: POSTGRES_LOCAL_CAPABILITIES,
       board: await this.getBoard(),
       config: await this.getConfig(),
       metrics,
@@ -328,27 +340,44 @@ export class PostgresLocalProvider implements KanbanProvider {
 
   async listTasks(filters: TaskListFilters = {}): Promise<Task[]> {
     await this.ready
-    const rows = await this.sql<TaskRow[]>`
-      SELECT tasks.*, columns.name AS column_name
-      FROM tasks
-      JOIN columns ON columns.id = tasks.column_id
-      ORDER BY tasks.created_at
-    `
-    const counts = await this.commentCountsByTask()
-    let tasks = rows.map((task) => this.enrichTask(task, counts.get(task.id) ?? 0))
 
+    // Push filtering, ordering, and the row cap into SQL instead of loading the
+    // whole table and a full comments group-by to filter in JS. Mirrors the
+    // SQLite path (db.ts:listTasks) so both backends share filter/sort semantics.
+    const conditions = []
     if (filters.column) {
       const column = await this.resolveColumn(filters.column)
-      tasks = tasks.filter((task) => task.column_id === column.id)
+      conditions.push(this.sql`tasks.column_id = ${column.id}`)
+    }
+    if (filters.priority) conditions.push(this.sql`tasks.priority = ${filters.priority}`)
+    if (filters.assignee) conditions.push(this.sql`tasks.assignee = ${filters.assignee}`)
+    if (filters.project) conditions.push(this.sql`tasks.project = ${filters.project}`)
+    const where = conditions.length
+      ? conditions.reduce((acc, cond) => this.sql`${acc} AND ${cond}`)
+      : this.sql`TRUE`
+
+    // Whitelisted ORDER BY fragments; the sort key never reaches SQL as data.
+    const orderByMap: Record<string, ReturnType<typeof this.sql>> = {
+      priority: this
+        .sql`CASE tasks.priority WHEN 'urgent' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 WHEN 'low' THEN 3 END`,
+      created: this.sql`tasks.created_at`,
+      updated: this.sql`tasks.updated_at`,
+      position: this.sql`tasks.position`,
+      title: this.sql`tasks.title`,
     }
-    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
+    const orderBy = orderByMap[filters.sort ?? 'position'] ?? orderByMap['position']!
+    const limit = filters.limit ? this.sql`LIMIT ${filters.limit}` : this.sql``
+
+    const rows = await this.sql<Array<TaskRow & { comment_count: string | number }>>`
+      SELECT tasks.*, columns.name AS column_name,
+        (SELECT COUNT(*) FROM comments WHERE comments.task_id = tasks.id) AS comment_count
+      FROM tasks
+      JOIN columns ON columns.id = tasks.column_id
+      WHERE ${where}
+      ORDER BY ${orderBy}
+      ${limit}
+    `
+    return rows.map((row) => this.enrichTask(row, Number(row.comment_count ?? 0)))
   }
 
   async getTask(idOrRef: string): Promise<Task> {
@@ -448,6 +477,29 @@ export class PostgresLocalProvider implements KanbanProvider {
           tx,
         )
       }
+      if (input.project !== undefined && input.project !== current.project) {
+        await this.insertActivity(
+          current.id,
+          'updated',
+          'project',
+          current.project || null,
+          input.project,
+          tx,
+        )
+      }
+      if (input.description !== undefined && input.description !== current.description) {
+        await this.insertActivity(
+          current.id,
+          'updated',
+          'description',
+          current.description,
+          input.description,
+          tx,
+        )
+      }
+      if (metadata !== undefined && metadata !== current.metadata) {
+        await this.insertActivity(current.id, 'updated', 'metadata', current.metadata, metadata, tx)
+      }
     })
     return this.getTask(current.id)
   }
@@ -526,22 +578,33 @@ export class PostgresLocalProvider implements KanbanProvider {
     const task = await this.requireTask(idOrRef)
     const id = generateId('cm')
     const timestamp = nowIso()
-    const [comment] = await this.sql<TaskComment[]>`
-      INSERT INTO comments (id, task_id, body, author, created_at, updated_at)
-      VALUES (${id}, ${task.id}, ${body}, ${null}, ${timestamp}, ${timestamp})
-      RETURNING *
-    `
+    // Comment writes are part of task history (parity with SQLite addComment):
+    // insert and activity in one transaction so they commit or roll back together.
+    const comment = await this.sql.begin(async (tx) => {
+      const [row] = await tx<TaskComment[]>`
+        INSERT INTO comments (id, task_id, body, author, created_at, updated_at)
+        VALUES (${id}, ${task.id}, ${body}, ${null}, ${timestamp}, ${timestamp})
+        RETURNING *
+      `
+      await this.insertActivity(task.id, 'updated', 'comment', null, body, tx)
+      return row
+    })
     return comment!
   }
 
   async updateComment(idOrRef: string, commentId: string, body: string): Promise<TaskComment> {
     const existing = await this.getComment(idOrRef, commentId)
-    const [comment] = await this.sql<TaskComment[]>`
-      UPDATE comments
-      SET body = ${body}, updated_at = ${nowIso()}
-      WHERE id = ${existing.id}
-      RETURNING *
-    `
+    const timestamp = nowIso()
+    const comment = await this.sql.begin(async (tx) => {
+      const [row] = await tx<TaskComment[]>`
+        UPDATE comments
+        SET body = ${body}, updated_at = ${timestamp}
+        WHERE id = ${existing.id}
+        RETURNING *
+      `
+      await this.insertActivity(existing.task_id, 'updated', 'comment', existing.body, body, tx)
+      return row
+    })
     return comment!
   }
 
@@ -567,39 +630,39 @@ export class PostgresLocalProvider implements KanbanProvider {
     const [total] = await this.sql<
       { count: string | number }[]
     >`SELECT COUNT(*) AS count FROM tasks`
-    // Classify columns by role (custom names / KANBAN_DEFAULT_COLUMNS) instead of
-    // matching the literal 'done' / 'in-progress'. Kept in lockstep with the
-    // SQLite copy in metrics.ts:getBoardMetrics.
-    const columns = await this.sql<{ id: string; name: string; position: number }[]>`
-      SELECT id, name, position FROM columns ORDER BY position
-    `
-    const doneColumnIds = selectDoneColumnIds(columns)
-    const inProgressColumnIds = selectInProgressColumnIds(columns)
-    const [completed] =
-      doneColumnIds.length > 0
-        ? await this.sql<{ count: string | number }[]>`
-          SELECT COUNT(*) AS count FROM tasks WHERE column_id IN ${this.sql(doneColumnIds)}
-        `
-        : [{ count: 0 }]
-    const tasksByColumn = await this.sql<{ column_name: string; count: string | number }[]>`
-      SELECT columns.name AS column_name, COUNT(tasks.id) AS count
+
+    // Gather raw aggregates with Postgres SQL; metrics-spec owns the derived
+    // fields (role classification, completion math, priority ordering) so both
+    // backends stay identical without manual lockstep.
+    const columnRows = await this.sql<
+      { id: string; name: string; position: number; count: string | number }[]
+    >`
+      SELECT columns.id AS id, columns.name AS name, columns.position AS position,
+        COUNT(tasks.id) AS count
       FROM columns
       LEFT JOIN tasks ON tasks.column_id = columns.id
       GROUP BY columns.id, columns.name, columns.position
       ORDER BY columns.position
     `
-    const tasksByPriority = await this.sql<{ priority: string; count: string | number }[]>`
-      SELECT priority, COUNT(*) AS count FROM tasks GROUP BY priority ORDER BY priority
-    `
-    const assignees = await this.discoveredAssignees()
-    const projects = await this.discoveredProjects()
-    const totalTasks = Number(total?.count ?? 0)
-    const completedTasks = Number(completed?.count ?? 0)
+    const columnCounts = columnRows.map((row) => ({
+      id: row.id,
+      name: row.name,
+      position: Number(row.position),
+      count: Number(row.count),
+    }))
+    // Done ids are needed up front to scope the average-completion query.
+    const { doneColumnIds } = classifyColumnRoles(columnCounts)
+
+    const priorityCounts = (
+      await this.sql<{ priority: string; count: string | number }[]>`
+        SELECT priority, COUNT(*) AS count FROM tasks GROUP BY priority
+      `
+    ).map((row) => ({ priority: row.priority, count: Number(row.count) }))
+
     // Average completion time = first tracked entry (creation) -> first time the
     // task entered Done. Using the Done *entry* (not exit) counts tasks resting
     // in Done; MIN() handles tasks that re-enter Done. Cast to timestamptz so the
-    // ISO-UTC strings compare correctly regardless of the server timezone. Kept
-    // in lockstep with the SQLite copy in metrics.ts:getBoardMetrics.
+    // ISO-UTC strings compare correctly regardless of the server timezone.
     const [avgResult] =
       doneColumnIds.length > 0
         ? await this.sql<{ avg_hours: string | number | null }[]>`
@@ -622,31 +685,17 @@ export class PostgresLocalProvider implements KanbanProvider {
       SELECT COUNT(*) AS count FROM tasks
       WHERE created_at::timestamptz >= NOW() - INTERVAL '7 days'
     `
-    const inProgressNames = new Set(
-      columns.filter((c) => inProgressColumnIds.includes(c.id)).map((c) => c.name),
-    )
-    const inProgressCount = tasksByColumn
-      .filter((row) => inProgressNames.has(row.column_name))
-      .reduce((sum, row) => sum + Number(row.count), 0)
-    return {
-      tasksByColumn: tasksByColumn.map((row) => ({
-        column_name: row.column_name,
-        count: Number(row.count),
-      })),
-      tasksByPriority: tasksByPriority.map((row) => ({
-        priority: row.priority,
-        count: Number(row.count),
-      })),
-      totalTasks,
-      completedTasks,
+
+    return assembleBoardMetrics({
+      columnCounts,
+      priorityCounts,
+      totalTasks: Number(total?.count ?? 0),
+      tasksCreatedThisWeek: Number(weekCount?.count ?? 0),
       avgCompletionHours: avgResult?.avg_hours != null ? Number(avgResult.avg_hours) : null,
       recentActivity: await this.getActivity(20),
-      tasksCreatedThisWeek: Number(weekCount?.count ?? 0),
-      inProgressCount,
-      completionPercent: totalTasks === 0 ? 0 : Math.round((completedTasks / totalTasks) * 100),
-      assignees,
-      projects,
-    }
+      assignees: await this.discoveredAssignees(),
+      projects: await this.discoveredProjects(),
+    })
   }
 
   private async discoveredAssignees(): Promise<string[]> {
@@ -707,14 +756,12 @@ export class PostgresLocalProvider implements KanbanProvider {
     }
   }
 
-  async patchConfig(input: Partial<BoardConfig>): Promise<BoardConfig> {
-    await this.ready
-    const config = await this.getConfig()
-    return {
-      ...config,
-      members: input.members ?? config.members,
-      projects: input.projects ?? config.projects,
-    }
+  async patchConfig(_input: Partial<BoardConfig>): Promise<BoardConfig> {
+    // No persistent config repository exists for Postgres-local (getConfig is
+    // reconstructed from task data). Rather than silently merge-and-return
+    // without persisting, advertise the capability honestly (configEdit:false)
+    // and fail loudly so the HTTP API and CLI agree.
+    unsupportedOperation('Editing board config is not supported with KANBAN_STORAGE=postgres')
   }
 
   async getSyncStatus(): Promise<ProviderSyncStatus | null> {

package/src/tracker-config.ts

@@ -1,3 +1,4 @@
+import { ErrorCode, KanbanError } from './errors'
 import { providerNotConfigured } from './providers/errors'
 import { resolvePollingSyncIntervalMs } from './sync-config'
 
@@ -100,5 +101,20 @@ function defaultColumnsFromEnv(env: Record<string, string | undefined>): string[
     .split(',')
     .map((name) => name.trim())
     .filter(Boolean)
-  return columns.length > 0 ? columns : undefined
+  if (columns.length === 0) return undefined
+  // Column resolution is case-insensitive (LOWER(name)), and interactive column
+  // creation rejects case-insensitive duplicates. Reject them here too so the
+  // config path can't seed an ambiguous board state the interactive path forbids.
+  const seen = new Set<string>()
+  for (const name of columns) {
+    const key = name.toLowerCase()
+    if (seen.has(key)) {
+      throw new KanbanError(
+        ErrorCode.INVALID_CONFIG,
+        `KANBAN_DEFAULT_COLUMNS contains a duplicate column name (case-insensitive): '${name}'`,
+      )
+    }
+    seen.add(key)
+  }
+  return columns
 }

package/src/transport-input.ts

@@ -0,0 +1,30 @@
+import { ErrorCode, KanbanError } from './errors'
+
+/**
+ * Parse an optional positive integer supplied through a transport boundary
+ * (HTTP query string, CLI flag). Returns `undefined` when the value is absent,
+ * and throws a `KanbanError(INVALID_ARGUMENT)` for anything that is not a
+ * positive integer — `NaN`, negatives, zero, decimals, and trailing-garbage
+ * strings like `"5abc"`. Centralizing this keeps invalid limits from leaking
+ * into provider logic, where they would otherwise produce inconsistent
+ * behavior across SQL `LIMIT`, `Array.prototype.slice`, and Postgres.
+ */
+export function parsePositiveInt(
+  value: string | null | undefined,
+  field = 'limit',
+): number | undefined {
+  if (value === null || value === undefined) return undefined
+  const trimmed = value.trim()
+  if (trimmed === '') return undefined
+  // Plain decimal digits only — reject signs, decimals, and exponent forms like
+  // "1e100" that Number() would otherwise treat as integers and let escape into
+  // SQL `LIMIT`. Cap at MAX_SAFE_INTEGER so the parsed value stays exact.
+  const parsed = /^\d+$/.test(trimmed) ? Number(trimmed) : NaN
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > Number.MAX_SAFE_INTEGER) {
+    throw new KanbanError(
+      ErrorCode.INVALID_ARGUMENT,
+      `${field} must be a positive integer (received '${value}')`,
+    )
+  }
+  return parsed
+}

package/src/version.ts

@@ -0,0 +1,8 @@
+import packageJson from '../package.json'
+
+/**
+ * Single source of truth for the build/package version. Import this anywhere a
+ * release version is reported (e.g. MCP server metadata) so transports never
+ * advertise a hard-coded version that drifts from package.json.
+ */
+export const VERSION: string = packageJson.version