@andypai/agent-kanban 0.3.7 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andypai/agent-kanban",
-  "version": "0.3.7",
+  "version": "0.5.0",
   "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__/api.test.ts

@@ -41,12 +41,18 @@ describe('handleRequest', () => {
     const req = new Request('http://localhost/api/tasks', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ title: 'Created via API' }),
+      body: JSON.stringify({ title: 'Created via API', labels: ['garage-smoke', 'api-smoke'] }),
     })
     const result = await handleRequest(provider, req)
+    const body = (await result.response.json()) as {
+      ok: boolean
+      data: { labels: string[] }
+    }
 
     expect(result.response.status).toBe(200)
     expect(result.mutated).toBe(true)
+    expect(body.ok).toBe(true)
+    expect(body.data.labels).toEqual(['garage-smoke', 'api-smoke'])
   })
 
   test('marks successful task delete as mutated', async () => {

package/src/__tests__/db.test.ts

@@ -79,7 +79,7 @@ describe('schema', () => {
     expect(listColumns(db)).toHaveLength(5)
   })
 
-  test('migrateSchema adds project column and index to legacy tasks table', () => {
+  test('migrateSchema adds project and labels columns to legacy tasks table', () => {
     const legacy = new Database(':memory:')
     legacy.run(
       `CREATE TABLE tasks (
@@ -102,6 +102,7 @@ describe('schema', () => {
     const indexes = legacy.query('PRAGMA index_list(tasks)').all() as { name: string }[]
 
     expect(columns.some((c) => c.name === 'project')).toBe(true)
+    expect(columns.some((c) => c.name === 'labels')).toBe(true)
     expect(indexes.some((i) => i.name === 'idx_tasks_project')).toBe(true)
   })
 

package/src/__tests__/index.test.ts

@@ -165,6 +165,10 @@ describe('run', () => {
           'alice',
           '--project',
           'Platform',
+          '--label',
+          'garage-smoke',
+          '--label',
+          'garage-owner-local,smoke-run',
           '-m',
           '{"sprint":5}',
         ]),
@@ -174,6 +178,7 @@ describe('run', () => {
       expect(created.priority).toBe('high')
       expect(created.assignee).toBe('alice')
       expect(created.project).toBe('Platform')
+      expect(created.labels).toEqual(['garage-smoke', 'garage-owner-local', 'smoke-run'])
       expect(created.metadata).toBe('{"sprint":5}')
 
       const listed = expectOk<Task[]>(

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

@@ -352,6 +352,7 @@ describe('JiraProvider mutations', () => {
       description: 'hello\n- item',
       priority: 'high',
       assignee: 'Alice',
+      labels: ['garage-smoke', 'garage-owner-local'],
     })
 
     expect(task.externalRef).toBe('ENG-10')
@@ -365,6 +366,7 @@ describe('JiraProvider mutations', () => {
     expect((body.fields.priority as { name: string }).name).toBe('High')
     expect((body.fields.assignee as { accountId: string }).accountId).toBe('a-1')
     expect((body.fields.project as { key: string }).key).toBe('ENG')
+    expect(body.fields.labels).toEqual(['garage-smoke', 'garage-owner-local'])
     const desc = body.fields.description as {
       version: number
       type: string

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

@@ -133,15 +133,32 @@ describe('LinearProvider sync', () => {
       lastIssueUpdatedAt: '2026-01-02T00:00:00Z',
     })
 
-    let createIssueTeamId: string | null = null
+    const createIssueInput: { current?: { labelIds?: string[]; teamId?: string } } = {}
     globalThis.fetch = (async (_input: string | URL | Request, init?: RequestInit) => {
       const body = JSON.parse(String(init?.body)) as {
         query: string
-        variables: { input?: { teamId?: string } }
+        variables: { input?: { labelIds?: string[]; teamId?: string } }
+      }
+
+      if (body.query.includes('query IssueLabels')) {
+        return new Response(
+          JSON.stringify({
+            data: {
+              issueLabels: {
+                nodes: [
+                  { id: 'label-smoke', name: 'garage-smoke' },
+                  { id: 'label-owner', name: 'garage-owner-local' },
+                ],
+                pageInfo: { hasNextPage: false, endCursor: null },
+              },
+            },
+          }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        )
       }
 
       if (body.query.includes('mutation CreateIssue')) {
-        createIssueTeamId = body.variables.input?.teamId ?? null
+        createIssueInput.current = body.variables.input
         return new Response(
           JSON.stringify({
             data: {
@@ -159,7 +176,12 @@ describe('LinearProvider sync', () => {
                   assignee: null,
                   project: null,
                   state: { id: 'state-1', name: 'Todo', position: 0 },
-                  labels: { nodes: [] },
+                  labels: {
+                    nodes: [
+                      { id: 'label-smoke', name: 'garage-smoke' },
+                      { id: 'label-owner', name: 'garage-owner-local' },
+                    ],
+                  },
                   comments: {
                     nodes: [],
                     pageInfo: { hasNextPage: false, endCursor: null },
@@ -176,10 +198,15 @@ describe('LinearProvider sync', () => {
     }) as unknown as typeof fetch
 
     const provider = new LinearProvider(db, 'R2P', 'lin_api_test')
-    const created = await provider.createTask({ title: 'Hello' })
+    const created = await provider.createTask({
+      title: 'Hello',
+      labels: ['garage-smoke', 'garage-owner-local'],
+    })
 
-    expect(String(createIssueTeamId)).toBe('3ca24047-e954-44e8-b266-c7182410befb')
+    expect(createIssueInput.current?.teamId).toBe('3ca24047-e954-44e8-b266-c7182410befb')
+    expect(createIssueInput.current?.labelIds).toEqual(['label-smoke', 'label-owner'])
     expect(created.externalRef).toBe('R2P-1')
+    expect(created.labels).toEqual(['garage-smoke', 'garage-owner-local'])
   })
 
   test('periodic full sync prunes cached issues missing from upstream', async () => {

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

@@ -3,6 +3,7 @@ import postgres from 'postgres'
 
 import { run } from '../index'
 import type { Task } from '../types'
+import { PostgresJiraProvider } from '../providers/postgres-jira'
 
 const databaseUrl = process.env['KANBAN_PG_TEST_URL'] ?? process.env['DATABASE_URL']
 const pgTest = databaseUrl ? test : test.skip
@@ -43,6 +44,7 @@ function makeIssue(
     id: string
     key: string
     summary: string
+    labels: string[]
     updated: string
   }> = {},
 ): Record<string, unknown> {
@@ -56,7 +58,7 @@ function makeIssue(
       issuetype: { id: '10000', name: 'Task' },
       priority: { id: '2', name: 'High' },
       assignee: { accountId: 'a1', displayName: 'Alice' },
-      labels: ['garage'],
+      labels: overrides.labels ?? ['garage'],
       comment: { total: 0 },
       created: '2026-01-01T00:00:00Z',
       updated: overrides.updated ?? '2026-01-02T00:00:00Z',
@@ -114,12 +116,13 @@ function standardRoutes(): StubRoute[] {
       match: (url) => url.endsWith('/rest/api/3/issue'),
       handler: async (_url, init) => {
         const body = JSON.parse(String(init?.body ?? '{}')) as {
-          fields?: { summary?: string }
+          fields?: { labels?: string[]; summary?: string }
         }
         const issue = makeIssue({
           id: '10002',
           key: 'ENG-2',
           summary: body.fields?.summary ?? 'Created issue',
+          labels: body.fields?.labels,
           updated: '2026-01-03T00:00:00Z',
         })
         issues.push(issue)
@@ -303,6 +306,34 @@ describe('postgres jira provider', () => {
     expect(comments).toHaveLength(1)
   })
 
+  pgTest('passes labels when creating Jira tasks through Postgres storage', async () => {
+    expect(sql).not.toBeNull()
+    if (!sql) throw new Error('expected postgres test connection')
+    const stub = jiraFetchStub(standardRoutes())
+    globalThis.fetch = stub.fn
+    const provider = new PostgresJiraProvider(sql, {
+      baseUrl: 'https://example.atlassian.net',
+      email: 'user@example.com',
+      apiToken: 'token',
+      projectKey: 'ENG',
+    })
+
+    const created = await provider.createTask({
+      title: 'Created with labels',
+      labels: ['garage-smoke', 'garage-owner-local'],
+    })
+
+    expect(created.labels).toEqual(['garage-smoke', 'garage-owner-local'])
+    const postCall = stub.calls.find(
+      (call) => call.init?.method === 'POST' && call.url.endsWith('/rest/api/3/issue'),
+    )
+    expect(postCall).toBeDefined()
+    const body = JSON.parse(String(postCall?.init?.body ?? '{}')) as {
+      fields?: Record<string, unknown>
+    }
+    expect(body.fields?.labels).toEqual(['garage-smoke', 'garage-owner-local'])
+  })
+
   pgTest('moves Jira tasks through Postgres storage', async () => {
     const moved = expectOk<Task>(await run(['task', 'move', 'ENG-1', 'Done']))
 

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

@@ -3,6 +3,7 @@ import postgres from 'postgres'
 
 import { run } from '../index'
 import type { Task, TaskComment } from '../types'
+import { PostgresLinearProvider } from '../providers/postgres-linear'
 
 const databaseUrl = process.env['KANBAN_PG_TEST_URL'] ?? process.env['DATABASE_URL']
 const pgTest = databaseUrl ? test : test.skip
@@ -31,6 +32,8 @@ type StubComment = {
   user: { id: string; name: string; displayName: string }
 }
 
+type LinearStubCall = { query: string; variables: Record<string, unknown> }
+
 function expectOk<T>(result: Awaited<ReturnType<typeof run>>): T {
   expect(result.exitCode).toBe(0)
   expect(result.output.ok).toBe(true)
@@ -64,7 +67,7 @@ function makeIssue(overrides: Partial<StubIssue> = {}): StubIssue {
   }
 }
 
-function linearFetchStub(): typeof fetch {
+function linearFetchStub(calls: LinearStubCall[] = []): typeof fetch {
   const commentsByIssue = new Map<string, StubComment[]>()
   const issues: StubIssue[] = [makeIssue()]
   const states = [
@@ -83,6 +86,12 @@ function linearFetchStub(): typeof fetch {
       { id: 'proj-1', name: 'Garage', url: 'https://linear.app/project/garage', state: 'started' },
     ],
   }
+  const labels = {
+    nodes: [
+      { id: 'label-smoke', name: 'garage-smoke' },
+      { id: 'label-owner', name: 'garage-owner-local' },
+    ],
+  }
 
   return (async (_input: string | URL | Request, init?: RequestInit) => {
     const body = JSON.parse(String(init?.body ?? '{}')) as {
@@ -91,6 +100,7 @@ function linearFetchStub(): typeof fetch {
     }
     const query = body.query
     const variables = body.variables ?? {}
+    calls.push({ query, variables })
 
     if (query.includes('query TeamSnapshot')) {
       return Response.json({ data: { team } })
@@ -101,6 +111,16 @@ function linearFetchStub(): typeof fetch {
     if (query.includes('query Projects')) {
       return Response.json({ data: { projects } })
     }
+    if (query.includes('query IssueLabels')) {
+      return Response.json({
+        data: {
+          issueLabels: {
+            ...labels,
+            pageInfo: { hasNextPage: false, endCursor: null },
+          },
+        },
+      })
+    }
     if (query.includes('query Issues')) {
       return Response.json({
         data: {
@@ -119,8 +139,10 @@ function linearFetchStub(): typeof fetch {
         stateId?: string
         assigneeId?: string
         projectId?: string
+        labelIds?: string[]
       }
       const state = states.find((candidate) => candidate.id === input.stateId) ?? states[0]!
+      const issueLabels = labels.nodes.filter((label) => input.labelIds?.includes(label.id))
       const issue = makeIssue({
         id: 'lin-2',
         identifier: 'GB-2',
@@ -130,6 +152,7 @@ function linearFetchStub(): typeof fetch {
         state,
         assignee: users.nodes.find((user) => user.id === input.assigneeId) ?? null,
         project: projects.nodes.find((project) => project.id === input.projectId) ?? null,
+        labels: { nodes: issueLabels },
         updatedAt: '2026-01-03T00:00:00.000Z',
       })
       issues.push(issue)
@@ -306,4 +329,26 @@ describe('postgres linear provider', () => {
     const comments = expectOk<TaskComment[]>(await run(['comment', 'list', 'GB-2']))
     expect(comments).toHaveLength(1)
   })
+
+  pgTest('passes labels when creating Linear tasks through Postgres storage', async () => {
+    expect(sql).not.toBeNull()
+    if (!sql) throw new Error('expected postgres test connection')
+
+    const calls: LinearStubCall[] = []
+    globalThis.fetch = linearFetchStub(calls)
+    const provider = new PostgresLinearProvider(sql, 'GB', 'linear-key')
+
+    const created = await provider.createTask({
+      title: 'Created with labels',
+      labels: ['garage-smoke', 'garage-owner-local'],
+    })
+
+    expect(created.labels).toEqual(['garage-smoke', 'garage-owner-local'])
+    const createCall = calls.find((call) => call.query.includes('mutation CreateIssue'))
+    expect(createCall).toBeDefined()
+    expect((createCall?.variables.input as { labelIds?: string[] })?.labelIds).toEqual([
+      'label-smoke',
+      'label-owner',
+    ])
+  })
 })

package/src/__tests__/postgres-local-provider.test.ts

@@ -78,6 +78,10 @@ describe('postgres local provider', () => {
         'garage',
         '--project',
         'Dispatch',
+        '--label',
+        'garage-smoke',
+        '--label',
+        'postgres-local',
         '-m',
         '{"storage":"postgres"}',
       ]),
@@ -85,6 +89,7 @@ describe('postgres local provider', () => {
 
     expect(created.title).toBe('Postgres-backed task')
     expect(created.column_name).toBe('recurring')
+    expect(created.labels).toEqual(['garage-smoke', 'postgres-local'])
     expect(created.version).toBe('0')
 
     const listed = expectOk<Task[]>(await run(['task', 'list', '-c', 'recurring']))

package/src/__tests__/webhook-events.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from 'bun:test'
+
+import { extractWebhookMeta, webhookEventStatus, webhookEventsEnabled } from '../webhook-events'
+
+describe('webhookEventStatus', () => {
+  test('handled -> accepted', () => {
+    expect(webhookEventStatus({ handled: true })).toBe('accepted')
+  })
+  test('unhandled -> skipped', () => {
+    expect(webhookEventStatus({ handled: false })).toBe('skipped')
+    expect(webhookEventStatus({ handled: false, message: 'Unsupported event' })).toBe('skipped')
+  })
+  test('unauthorized -> error (regardless of handled)', () => {
+    expect(webhookEventStatus({ handled: false, unauthorized: true })).toBe('error')
+    expect(webhookEventStatus({ handled: true, unauthorized: true })).toBe('error')
+  })
+})
+
+describe('webhookEventsEnabled', () => {
+  test('enabled by default / when unset', () => {
+    expect(webhookEventsEnabled({})).toBe(true)
+    expect(webhookEventsEnabled({ KANBAN_WEBHOOK_EVENTS: 'on' })).toBe(true)
+    expect(webhookEventsEnabled({ KANBAN_WEBHOOK_EVENTS: '1' })).toBe(true)
+  })
+  test('disabled by explicit off values', () => {
+    for (const v of ['0', 'false', 'off', 'no', 'OFF', ' false ']) {
+      expect(webhookEventsEnabled({ KANBAN_WEBHOOK_EVENTS: v })).toBe(false)
+    }
+  })
+})
+
+describe('extractWebhookMeta', () => {
+  test('jira: webhookEvent + issue.key', () => {
+    const body = JSON.stringify({ webhookEvent: 'jira:issue_updated', issue: { key: 'SMTS-7' } })
+    expect(extractWebhookMeta('jira', body)).toEqual({
+      eventType: 'jira:issue_updated',
+      externalRef: 'SMTS-7',
+    })
+  })
+  test('jira: tolerates a missing issue', () => {
+    expect(
+      extractWebhookMeta('jira', JSON.stringify({ webhookEvent: 'jira:issue_deleted' })),
+    ).toEqual({
+      eventType: 'jira:issue_deleted',
+    })
+  })
+  test('linear: type.action + data.identifier', () => {
+    const body = JSON.stringify({
+      type: 'Issue',
+      action: 'update',
+      data: { id: 'uuid-1', identifier: 'SMTS-9' },
+    })
+    expect(extractWebhookMeta('linear', body)).toEqual({
+      eventType: 'Issue.update',
+      externalRef: 'SMTS-9',
+    })
+  })
+  test('linear: falls back to data.id when identifier is absent', () => {
+    const body = JSON.stringify({ type: 'Issue', action: 'remove', data: { id: 'uuid-2' } })
+    expect(extractWebhookMeta('linear', body)).toEqual({
+      eventType: 'Issue.remove',
+      externalRef: 'uuid-2',
+    })
+  })
+  test('invalid / non-object body -> {}', () => {
+    expect(extractWebhookMeta('jira', 'not json')).toEqual({})
+    expect(extractWebhookMeta('jira', '"a string"')).toEqual({})
+    expect(extractWebhookMeta('linear', 'null')).toEqual({})
+  })
+  test('unknown provider -> {}', () => {
+    expect(extractWebhookMeta('local', JSON.stringify({ webhookEvent: 'x' }))).toEqual({})
+  })
+})

package/src/api.ts

@@ -1,6 +1,7 @@
 import { KanbanError, ErrorCode } from './errors'
 import type { BoardConfig, CliOutput, Task } from './types'
 import type { CreateTaskInput, UpdateTaskInput, KanbanProvider } from './providers/types'
+import { normalizeLabels } from './labels'
 
 export type WsEvent =
   | { type: 'task:upsert'; task: Task; columnName: string }
@@ -146,6 +147,7 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
         priority: body.priority,
         assignee: body.assignee,
         project: body.project,
+        labels: normalizeLabels(body.labels),
         metadata: body.metadata,
       })
       return { ok: true, data: created }

package/src/db.ts

@@ -6,6 +6,7 @@ import { generateId } from './id'
 import { ErrorCode, KanbanError } from './errors'
 import type { BoardView, Column, Priority, Task, TaskComment, TaskWithColumn } from './types'
 import { logActivity, enterColumn, exitColumn } from './activity'
+import { normalizeLabels, parseStoredLabels } from './labels'
 
 const DEFAULT_COLUMNS = [
   { name: 'recurring', position: 0 },
@@ -63,6 +64,7 @@ export function initSchema(db: Database): void {
       priority TEXT NOT NULL DEFAULT 'medium' CHECK (priority IN ('low','medium','high','urgent')),
       assignee TEXT NOT NULL DEFAULT '',
       project TEXT NOT NULL DEFAULT '',
+      labels TEXT NOT NULL DEFAULT '[]',
       metadata TEXT NOT NULL DEFAULT '{}',
       revision INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL DEFAULT (datetime('now')),
@@ -124,6 +126,10 @@ export function migrateSchema(db: Database): void {
   if (!hasProject) {
     db.run("ALTER TABLE tasks ADD COLUMN project TEXT NOT NULL DEFAULT ''")
   }
+  const hasLabels = columns.some((c) => c.name === 'labels')
+  if (!hasLabels) {
+    db.run("ALTER TABLE tasks ADD COLUMN labels TEXT NOT NULL DEFAULT '[]'")
+  }
   const hasRevision = columns.some((c) => c.name === 'revision')
   if (!hasRevision) {
     db.run('ALTER TABLE tasks ADD COLUMN revision INTEGER NOT NULL DEFAULT 0')
@@ -276,6 +282,7 @@ export function addTask(
     priority?: Priority
     assignee?: string
     project?: string
+    labels?: string[]
     metadata?: string
   } = {},
 ): TaskWithColumn {
@@ -297,13 +304,14 @@ export function addTask(
   }
 
   const id = generateId('t')
+  const labels = normalizeLabels(opts.labels)
   const maxPos = db
     .query('SELECT COALESCE(MAX(position), -1) + 1 as next FROM tasks WHERE column_id = $col')
     .get({ $col: column.id }) as { next: number }
 
   db.query(
-    `INSERT INTO tasks (id, title, description, column_id, position, priority, assignee, project, metadata)
-     VALUES ($id, $title, $desc, $col, $pos, $pri, $assignee, $project, $meta)`,
+    `INSERT INTO tasks (id, title, description, column_id, position, priority, assignee, project, labels, metadata)
+     VALUES ($id, $title, $desc, $col, $pos, $pri, $assignee, $project, $labels, $meta)`,
   ).run({
     $id: id,
     $title: title,
@@ -313,6 +321,7 @@ export function addTask(
     $pri: opts.priority ?? 'medium',
     $assignee: opts.assignee ?? '',
     $project: opts.project ?? '',
+    $labels: JSON.stringify(labels),
     $meta: opts.metadata ?? '{}',
   })
   logActivity(db, id, 'created', { new_value: title })
@@ -330,7 +339,7 @@ export function getTask(db: Database, id: string): TaskWithColumn {
   if (!task) {
     throw new KanbanError(ErrorCode.TASK_NOT_FOUND, `No task with id '${id}'`)
   }
-  return task
+  return hydrateTask(task)
 }
 
 export function listTasks(
@@ -384,7 +393,8 @@ export function listTasks(
        JOIN columns c ON t.column_id = c.id
        ${where} ORDER BY ${orderBy} ${limitClause}`,
     )
-    .all(params as Record<string, string>) as TaskWithColumn[]
+    .all(params as Record<string, string>)
+    .map((task) => hydrateTask(task as TaskWithColumn))
 }
 
 export function updateTask(
@@ -630,11 +640,18 @@ export function getBoardView(db: Database): BoardView {
       ...col,
       tasks: db
         .query('SELECT * FROM tasks WHERE column_id = $col ORDER BY position')
-        .all({ $col: col.id }) as Task[],
+        .all({ $col: col.id })
+        .map((task) => hydrateTask(task as Task)),
     })),
   }
 }
 
+function hydrateTask<T extends { labels?: unknown }>(
+  task: T,
+): Omit<T, 'labels'> & { labels: string[] } {
+  return { ...task, labels: parseStoredLabels(task.labels) }
+}
+
 // --- Bulk ---
 
 export function bulkMoveAll(

package/src/index.ts

@@ -15,6 +15,7 @@ import { openKanbanRuntime } from './provider-runtime'
 import { trackerConfigFromEnv } from './tracker-config'
 import type { KanbanProvider } from './providers/types'
 import { resolvePollingSyncIntervalMs } from './sync-config'
+import { normalizeLabels } from './labels'
 
 interface ParsedArgs {
   values: Record<string, unknown>
@@ -34,6 +35,8 @@ function parseCliArgs(argv: string[]): ParsedArgs {
       a: { type: 'string' },
       m: { type: 'string' },
       l: { type: 'string' },
+      label: { type: 'string', multiple: true },
+      labels: { type: 'string', multiple: true },
       sort: { type: 'string' },
       title: { type: 'string' },
       position: { type: 'string' },
@@ -68,6 +71,7 @@ async function routeTask(
           priority: values.p as Priority | undefined,
           assignee: values.a as string | undefined,
           project: values.project as string | undefined,
+          labels: normalizeLabels([values.label, values.labels]),
           metadata: values.m as string | undefined,
         }),
       )
@@ -388,7 +392,7 @@ Commands:
   board view                  View full board (default)
   board reset                 Reset board to defaults
 
-  task add <title>            Add a task [-d desc] [-c column] [-p priority] [-a assignee] [--project name] [-m json]
+  task add <title>            Add a task [-d desc] [-c column] [-p priority] [-a assignee] [--project name] [--label name] [-m json]
   task list                   List tasks [-c column] [-p priority] [-a assignee] [--project name] [-l limit] [--sort field]
   task view <id>              View task details
   task update <id>            Update task [--title] [-d] [-p] [-a] [--project name] [-m]

package/src/labels.ts

@@ -0,0 +1,34 @@
+export function normalizeLabels(input: unknown): string[] {
+  const labels: string[] = []
+  const seen = new Set<string>()
+
+  collectLabels(input, labels, seen)
+
+  return labels
+}
+
+export function parseStoredLabels(raw: unknown): string[] {
+  if (typeof raw !== 'string') return normalizeLabels(raw)
+
+  try {
+    return normalizeLabels(JSON.parse(raw))
+  } catch {
+    return normalizeLabels(raw)
+  }
+}
+
+function collectLabels(input: unknown, labels: string[], seen: Set<string>): void {
+  if (Array.isArray(input)) {
+    for (const item of input) collectLabels(item, labels, seen)
+    return
+  }
+
+  if (typeof input !== 'string') return
+
+  for (const part of input.split(',')) {
+    const label = part.trim()
+    if (!label || seen.has(label)) continue
+    seen.add(label)
+    labels.push(label)
+  }
+}

package/src/providers/jira-client.ts

@@ -388,3 +388,7 @@ export class JiraClient {
     })
   }
 }
+
+export function normalizeJiraLabels(labels: string[] | undefined): string[] {
+  return (labels ?? []).map((label) => label.trim()).filter(Boolean)
+}

package/src/providers/jira.ts

@@ -20,7 +20,7 @@ import {
 import { adfToPlainText, plainTextToAdf, type AdfDocument } from './jira-adf'
 import { JIRA_CAPABILITIES } from './capabilities'
 import { providerUpstreamError, unsupportedOperation } from './errors'
-import { JiraClient, type JiraComment, type JiraIssue } from './jira-client'
+import { JiraClient, normalizeJiraLabels, type JiraComment, type JiraIssue } from './jira-client'
 import {
   adjustJiraIssueCommentCount,
   decodeColumnStatusIds,
@@ -488,6 +488,8 @@ export class JiraProvider implements KanbanProvider {
         accountId: this.resolveAssigneeAccountId(input.assignee),
       }
     }
+    const labels = normalizeJiraLabels(input.labels)
+    if (labels.length > 0) fields['labels'] = labels
     // Column at create-time is intentionally unsupported in Jira mode: new
     // issues land in the project workflow's default start state. Use
     // `moveTask` after create to change status.

package/src/providers/linear-client.ts

@@ -43,6 +43,11 @@ export interface LinearComment {
   user?: { id: string; name?: string | null; displayName?: string | null } | null
 }
 
+export interface LinearIssueLabel {
+  id: string
+  name: string
+}
+
 interface LinearIssueNode {
   id: string
   identifier: string
@@ -232,6 +237,40 @@ export class LinearClient {
     return data.projects.nodes
   }
 
+  async listIssueLabels(): Promise<LinearIssueLabel[]> {
+    let after: string | null = null
+    const labels: LinearIssueLabel[] = []
+
+    do {
+      const data: {
+        issueLabels: {
+          nodes: LinearIssueLabel[]
+          pageInfo: PageInfo
+        }
+      } = await this.query(
+        `
+          query IssueLabels($after: String) {
+            issueLabels(first: 100, after: $after) {
+              nodes {
+                id
+                name
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
+            }
+          }
+        `,
+        { after },
+      )
+      labels.push(...data.issueLabels.nodes)
+      after = data.issueLabels.pageInfo.hasNextPage ? data.issueLabels.pageInfo.endCursor : null
+    } while (after)
+
+    return labels
+  }
+
   async listIssues(teamId: string, updatedAfter?: string): Promise<LinearIssue[]> {
     let after: string | null = null
     const issues: LinearIssue[] = []
@@ -311,6 +350,7 @@ export class LinearClient {
     priority?: number
     assigneeId?: string
     projectId?: string
+    labelIds?: string[]
   }): Promise<{ success: boolean; issue: LinearIssue | null }> {
     const data = await this.query<{
       issueCreate: { success: boolean; issue: LinearIssueNode | null }
@@ -349,6 +389,7 @@ export class LinearClient {
           priority: input.priority,
           assigneeId: input.assigneeId,
           projectId: input.projectId,
+          labelIds: input.labelIds,
         },
       },
     )
@@ -567,3 +608,57 @@ export class LinearClient {
     }
   }
 }
+
+export async function resolveLabelIdsForCreate(
+  client: LinearClient,
+  inputLabels: string[] | undefined,
+): Promise<string[] | undefined> {
+  if (!inputLabels?.some((label) => label.trim())) return undefined
+  return resolveLinearLabelIds(inputLabels, await client.listIssueLabels())
+}
+
+export function resolveLinearLabelIds(
+  inputLabels: string[] | undefined,
+  availableLabels: LinearIssueLabel[],
+): string[] | undefined {
+  const requested = dedupeLabelQueries(inputLabels)
+  if (requested.length === 0) return undefined
+
+  const byName = new Map(
+    availableLabels.map((label) => [label.name.trim().toLowerCase(), label.id]),
+  )
+  const knownIds = new Set(availableLabels.map((label) => label.id))
+  const ids: string[] = []
+  const missing: string[] = []
+
+  for (const label of requested) {
+    const id = byName.get(label.toLowerCase()) ?? (knownIds.has(label) ? label : undefined)
+    if (!id) {
+      missing.push(label)
+      continue
+    }
+    if (!ids.includes(id)) ids.push(id)
+  }
+
+  if (missing.length > 0) {
+    providerUpstreamError(
+      `Linear label${missing.length === 1 ? '' : 's'} not found: ${missing.join(', ')}`,
+    )
+  }
+
+  return ids.length > 0 ? ids : undefined
+}
+
+function dedupeLabelQueries(labels: string[] | undefined): string[] {
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const label of labels ?? []) {
+    const trimmed = label.trim()
+    if (!trimmed) continue
+    const key = trimmed.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(trimmed)
+  }
+  return out
+}

package/src/providers/linear.ts

@@ -31,7 +31,7 @@ import {
   upsertUsers,
   type LinearActivityRow,
 } from './linear-cache'
-import { LinearClient, type LinearComment } from './linear-client'
+import { LinearClient, resolveLabelIdsForCreate, type LinearComment } from './linear-client'
 import { unsupportedOperation } from './errors'
 import type {
   CreateTaskInput,
@@ -349,6 +349,7 @@ export class LinearProvider implements KanbanProvider {
   async createTask(input: CreateTaskInput) {
     await this.sync()
     const state = input.column ? this.resolveState(input.column) : undefined
+    const labelIds = await resolveLabelIdsForCreate(this.client, input.labels)
     const result = await this.client.createIssue({
       teamId: this.resolvedTeamId(),
       stateId: state?.id,
@@ -357,6 +358,7 @@ export class LinearProvider implements KanbanProvider {
       priority: toLinearPriority(input.priority),
       assigneeId: this.resolveAssigneeId(input.assignee),
       projectId: this.resolveProjectId(input.project),
+      labelIds,
     })
     if (!result.success || !result.issue) {
       throw new KanbanError(ErrorCode.PROVIDER_UPSTREAM_ERROR, 'Linear issue creation failed')

package/src/providers/local.ts

@@ -56,13 +56,14 @@ export class LocalProvider implements KanbanProvider {
   private enrichTask(task: Task, commentCount?: number): Task {
     const revision = task.revision ?? 0
     const assignees = task.assignee ? [task.assignee] : []
+    const labels = Array.isArray(task.labels) ? task.labels : []
     return {
       ...task,
       providerId: task.id,
       externalRef: task.id,
       url: null,
       assignees,
-      labels: [],
+      labels,
       comment_count: commentCount ?? countComments(this.db, task.id),
       version: String(revision),
       source_updated_at: null,

package/src/providers/postgres-jira.ts

@@ -16,7 +16,7 @@ import type {
 import { JIRA_CAPABILITIES } from './capabilities'
 import { decodeColumnStatusIds, type JiraActivityRow, type JiraColumnRow } from './jira-cache'
 import { adfToPlainText, plainTextToAdf, type AdfDocument } from './jira-adf'
-import { JiraClient, type JiraComment, type JiraIssue } from './jira-client'
+import { JiraClient, normalizeJiraLabels, type JiraComment, type JiraIssue } from './jira-client'
 import type { JiraProviderConfig } from './jira'
 import { providerUpstreamError, unsupportedOperation } from './errors'
 import type {
@@ -34,6 +34,12 @@ import {
   type WebhookRequest,
   type WebhookResult,
 } from '../webhooks'
+import {
+  ensureWebhookEventsSchema,
+  extractWebhookMeta,
+  recordWebhookEvent,
+  webhookEventStatus,
+} from '../webhook-events'
 
 const FULL_RECONCILE_INTERVAL_MS = 5 * 60_000
 
@@ -230,6 +236,7 @@ export class PostgresJiraProvider implements KanbanProvider {
     await this.sql`
       CREATE INDEX IF NOT EXISTS jira_activity_created_at_idx ON jira_activity(created_at DESC)
     `
+    await ensureWebhookEventsSchema(this.sql)
   }
 
   private async setMeta(key: string, value: string): Promise<void> {
@@ -941,6 +948,8 @@ export class PostgresJiraProvider implements KanbanProvider {
     if (input.assignee) {
       fields['assignee'] = { accountId: await this.resolveAssigneeAccountId(input.assignee) }
     }
+    const labels = normalizeJiraLabels(input.labels)
+    if (labels.length > 0) fields['labels'] = labels
     const created = await this.client.createIssue({ fields })
     await this.sync(true)
     const fresh = await this.getCachedTask(created.key)
@@ -1127,6 +1136,28 @@ export class PostgresJiraProvider implements KanbanProvider {
   }
 
   async handleWebhook(payload: WebhookRequest): Promise<WebhookResult> {
+    const meta = extractWebhookMeta('jira', payload.rawBody)
+    let result: WebhookResult
+    try {
+      result = await this.handleWebhookInner(payload)
+    } catch (err) {
+      void recordWebhookEvent(this.sql, {
+        provider: 'jira',
+        ...meta,
+        status: 'error',
+        detail: { error: err instanceof Error ? err.message : String(err) },
+      })
+      throw err
+    }
+    void recordWebhookEvent(this.sql, {
+      provider: 'jira',
+      ...meta,
+      status: webhookEventStatus(result),
+    })
+    return result
+  }
+
+  private async handleWebhookInner(payload: WebhookRequest): Promise<WebhookResult> {
     const secret = process.env['JIRA_WEBHOOK_SECRET']
     if (secret) {
       const sig = headerLower(payload.headers, 'x-hub-signature')

package/src/providers/postgres-linear.ts

@@ -14,9 +14,15 @@ import type {
 } from '../types'
 import { DEFAULT_POLLING_SYNC_INTERVAL_MS } from '../sync-config'
 import { headerLower, verifyHmacSha256, type WebhookRequest, type WebhookResult } from '../webhooks'
+import {
+  ensureWebhookEventsSchema,
+  extractWebhookMeta,
+  recordWebhookEvent,
+  webhookEventStatus,
+} from '../webhook-events'
 import { LINEAR_CAPABILITIES } from './capabilities'
 import { unsupportedOperation } from './errors'
-import { LinearClient, type LinearComment } from './linear-client'
+import { LinearClient, resolveLabelIdsForCreate, type LinearComment } from './linear-client'
 import type {
   CreateTaskInput,
   KanbanProvider,
@@ -255,6 +261,7 @@ export class PostgresLinearProvider implements KanbanProvider {
     await this.sql`
       CREATE INDEX IF NOT EXISTS linear_activity_created_at_idx ON linear_activity(created_at DESC)
     `
+    await ensureWebhookEventsSchema(this.sql)
   }
 
   private async setMeta(key: string, value: string): Promise<void> {
@@ -815,6 +822,7 @@ export class PostgresLinearProvider implements KanbanProvider {
   async createTask(input: CreateTaskInput): Promise<Task> {
     await this.sync()
     const state = input.column ? await this.resolveState(input.column) : undefined
+    const labelIds = await resolveLabelIdsForCreate(this.client, input.labels)
     const result = await this.client.createIssue({
       teamId: await this.resolvedTeamId(),
       stateId: state?.id,
@@ -823,6 +831,7 @@ export class PostgresLinearProvider implements KanbanProvider {
       priority: toLinearPriority(input.priority),
       assigneeId: await this.resolveAssigneeId(input.assignee),
       projectId: await this.resolveProjectId(input.project),
+      labelIds,
     })
     if (!result.success || !result.issue) {
       throw new KanbanError(ErrorCode.PROVIDER_UPSTREAM_ERROR, 'Linear issue creation failed')
@@ -979,6 +988,28 @@ export class PostgresLinearProvider implements KanbanProvider {
   }
 
   async handleWebhook(payload: WebhookRequest): Promise<WebhookResult> {
+    const meta = extractWebhookMeta('linear', payload.rawBody)
+    let result: WebhookResult
+    try {
+      result = await this.handleWebhookInner(payload)
+    } catch (err) {
+      void recordWebhookEvent(this.sql, {
+        provider: 'linear',
+        ...meta,
+        status: 'error',
+        detail: { error: err instanceof Error ? err.message : String(err) },
+      })
+      throw err
+    }
+    void recordWebhookEvent(this.sql, {
+      provider: 'linear',
+      ...meta,
+      status: webhookEventStatus(result),
+    })
+    return result
+  }
+
+  private async handleWebhookInner(payload: WebhookRequest): Promise<WebhookResult> {
     const secret = process.env['LINEAR_WEBHOOK_SECRET']
     if (secret) {
       const sig = headerLower(payload.headers, 'linear-signature')

package/src/providers/postgres-local.ts

@@ -24,6 +24,7 @@ import type {
   UpdateTaskInput,
 } from './types'
 import type { LocalTrackerConfig } from '../tracker-config'
+import { normalizeLabels, parseStoredLabels } from '../labels'
 
 const DEFAULT_COLUMNS = [
   { name: 'recurring', position: 0 },
@@ -43,6 +44,7 @@ interface TaskRow {
   priority: Priority
   assignee: string
   project: string
+  labels: string
   metadata: string
   revision: number
   created_at: string
@@ -126,6 +128,7 @@ export class PostgresLocalProvider implements KanbanProvider {
         priority TEXT NOT NULL DEFAULT 'medium',
         assignee TEXT NOT NULL DEFAULT '',
         project TEXT NOT NULL DEFAULT '',
+        labels TEXT NOT NULL DEFAULT '[]',
         metadata TEXT NOT NULL DEFAULT '{}',
         revision INTEGER NOT NULL DEFAULT 0,
         created_at TEXT NOT NULL,
@@ -162,6 +165,7 @@ export class PostgresLocalProvider implements KanbanProvider {
         exited_at TEXT
       )
     `
+    await this.sql`ALTER TABLE tasks ADD COLUMN IF NOT EXISTS labels TEXT NOT NULL DEFAULT '[]'`
     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)`
@@ -194,7 +198,7 @@ export class PostgresLocalProvider implements KanbanProvider {
       externalRef: row.id,
       url: null,
       assignees: row.assignee ? [row.assignee] : [],
-      labels: [],
+      labels: parseStoredLabels(row.labels),
       comment_count: commentCount,
       version: String(row.revision ?? 0),
       source_updated_at: null,
@@ -352,6 +356,7 @@ export class PostgresLocalProvider implements KanbanProvider {
     const priority = input.priority ?? 'medium'
     assertPriority(priority)
     const metadata = parseMetadata(input.metadata)
+    const labels = normalizeLabels(input.labels)
     const column = input.column
       ? await this.resolveColumn(input.column)
       : await this.resolveDefaultTaskColumn()
@@ -362,12 +367,12 @@ export class PostgresLocalProvider implements KanbanProvider {
     const timestamp = nowIso()
     await this.sql`
       INSERT INTO tasks (
-        id, title, description, column_id, position, priority, assignee, project, metadata,
+        id, title, description, column_id, position, priority, assignee, project, labels, metadata,
         revision, created_at, updated_at
       )
       VALUES (
         ${id}, ${input.title}, ${input.description ?? ''}, ${column.id}, ${Number(positionRow?.next ?? 0)},
-        ${priority}, ${input.assignee ?? ''}, ${input.project ?? ''}, ${metadata},
+        ${priority}, ${input.assignee ?? ''}, ${input.project ?? ''}, ${JSON.stringify(labels)}, ${metadata},
         0, ${timestamp}, ${timestamp}
       )
     `

package/src/providers/types.ts

@@ -29,6 +29,7 @@ export interface CreateTaskInput {
   priority?: Priority
   assignee?: string
   project?: string
+  labels?: string[]
   metadata?: string
 }
 

package/src/webhook-events.ts

@@ -0,0 +1,135 @@
+/**
+ * `webhook_events` — a small, generically-named receipts table that the Postgres
+ * providers append to on every received webhook. It is *not* used by agent-kanban
+ * itself; it exists so an external consumer (Garage Band's Studio "Webhooks"
+ * panel) can show "did the sidecar receive/process a tracker webhook, and when".
+ *
+ * Ownership: agent-kanban owns and creates this table; consumers read it
+ * read-only. Columns a consumer can rely on:
+ *   id           bigserial   — newest-first tie-breaker (required by readers'
+ *                              `ORDER BY received_at DESC, id DESC`)
+ *   received_at  timestamptz — when the webhook hit the sidecar
+ *   provider     text        — 'jira' | 'linear'
+ *   event_type   text|null   — Jira's `webhookEvent`, or Linear's `type.action`
+ *   external_ref text|null   — tracker key when derivable from the body
+ *   status       text        — 'accepted' (handled) | 'skipped' (unhandled) |
+ *                              'error' (unauthorized or threw)
+ *   detail       jsonb       — emit-time-controlled; never raw secrets/payloads
+ *                              (currently only `{ error }` on error rows)
+ *
+ * Best-effort by design: a receipt write must never fail or slow a webhook, and
+ * the whole feature no-ops when `KANBAN_WEBHOOK_EVENTS` is off, so it is safe to
+ * ship before any consumer exists.
+ */
+
+import type { JSONValue, Sql } from 'postgres'
+
+import type { TrackerProvider } from './tracker-config'
+import type { WebhookResult } from './webhooks'
+
+export type WebhookEventStatus = 'accepted' | 'skipped' | 'error'
+
+export interface WebhookEventRecord {
+  provider: TrackerProvider
+  eventType?: string | undefined
+  externalRef?: string | undefined
+  status: WebhookEventStatus
+  detail?: Record<string, unknown> | undefined
+}
+
+/** `KANBAN_WEBHOOK_EVENTS` toggles the receipts table; enabled unless explicitly off. */
+export function webhookEventsEnabled(
+  env: Record<string, string | undefined> = process.env,
+): boolean {
+  const value = env['KANBAN_WEBHOOK_EVENTS']?.trim().toLowerCase()
+  return value !== '0' && value !== 'false' && value !== 'off' && value !== 'no'
+}
+
+/** Idempotent — call from a Postgres provider's schema bootstrap. */
+export async function ensureWebhookEventsSchema(sql: Sql): Promise<void> {
+  if (!webhookEventsEnabled()) return
+  await sql`
+    CREATE TABLE IF NOT EXISTS webhook_events (
+      id           bigserial   PRIMARY KEY,
+      received_at  timestamptz NOT NULL DEFAULT now(),
+      provider     text        NOT NULL,
+      event_type   text,
+      external_ref text,
+      status       text        NOT NULL,
+      detail       jsonb       NOT NULL DEFAULT '{}'::jsonb
+    )
+  `
+  await sql`
+    CREATE INDEX IF NOT EXISTS webhook_events_received_at_idx
+      ON webhook_events (received_at DESC, id DESC)
+  `
+}
+
+export function webhookEventStatus(result: WebhookResult): WebhookEventStatus {
+  if (result.unauthorized) return 'error'
+  return result.handled ? 'accepted' : 'skipped'
+}
+
+/** Append a receipt. Swallows every error — a logging miss must never fail the webhook. */
+export async function recordWebhookEvent(sql: Sql, record: WebhookEventRecord): Promise<void> {
+  if (!webhookEventsEnabled()) return
+  try {
+    await sql`
+      INSERT INTO webhook_events (provider, event_type, external_ref, status, detail)
+      VALUES (
+        ${record.provider},
+        ${record.eventType ?? null},
+        ${record.externalRef ?? null},
+        ${record.status},
+        ${sql.json((record.detail ?? {}) as JSONValue)}
+      )
+    `
+  } catch (err) {
+    console.warn('[webhook-events] failed to record receipt:', err)
+  }
+}
+
+/** Light, provider-shaped peek at the raw body for a receipt's `event_type` / `external_ref`. */
+export function extractWebhookMeta(
+  providerType: TrackerProvider,
+  rawBody: string,
+): { eventType?: string; externalRef?: string } {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(rawBody)
+  } catch {
+    return {}
+  }
+  if (typeof parsed !== 'object' || parsed === null) return {}
+  const body = parsed as Record<string, unknown>
+
+  if (providerType === 'jira') {
+    const eventType = typeof body['webhookEvent'] === 'string' ? body['webhookEvent'] : undefined
+    const externalRef = nestedString(body['issue'], 'key')
+    return withDefined({ eventType, externalRef })
+  }
+  if (providerType === 'linear') {
+    const type = typeof body['type'] === 'string' ? body['type'] : undefined
+    const action = typeof body['action'] === 'string' ? body['action'] : undefined
+    const eventType = type && action ? `${type}.${action}` : (type ?? action)
+    const externalRef = nestedString(body['data'], 'identifier') ?? nestedString(body['data'], 'id')
+    return withDefined({ eventType, externalRef })
+  }
+  return {}
+}
+
+function nestedString(container: unknown, key: string): string | undefined {
+  if (typeof container !== 'object' || container === null) return undefined
+  const value = (container as Record<string, unknown>)[key]
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+function withDefined(meta: { eventType?: string | undefined; externalRef?: string | undefined }): {
+  eventType?: string
+  externalRef?: string
+} {
+  return {
+    ...(meta.eventType ? { eventType: meta.eventType } : {}),
+    ...(meta.externalRef ? { externalRef: meta.externalRef } : {}),
+  }
+}