@andypai/agent-kanban 0.5.1 → 0.6.1

package/src/db.ts

@@ -137,22 +137,31 @@ export function migrateSchema(db: Database): void {
   db.run('CREATE INDEX IF NOT EXISTS idx_tasks_project ON tasks(project)')
 }
 
-export function seedDefaultColumns(db: Database): void {
+export function seedDefaultColumns(db: Database, columnNames?: string[]): void {
   const existing = db.query('SELECT COUNT(*) as count FROM columns').get() as {
     count: number
   }
   if (existing.count > 0) return
+  // Honor KANBAN_DEFAULT_COLUMNS (passed through as columnNames) when provided,
+  // matching the Postgres local provider; otherwise fall back to the built-in set.
+  const columns =
+    columnNames && columnNames.length > 0
+      ? columnNames.map((name, position) => ({ name, position }))
+      : DEFAULT_COLUMNS
   const stmt = db.prepare('INSERT INTO columns (id, name, position) VALUES ($id, $name, $position)')
-  for (const col of DEFAULT_COLUMNS) {
+  for (const col of columns) {
     stmt.run({ $id: generateId('c'), $name: col.name, $position: col.position })
   }
 }
 
 export function isInitialized(db: Database): boolean {
-  const result = db
+  const table = db
     .query("SELECT COUNT(*) as count FROM sqlite_master WHERE type='table' AND name='columns'")
     .get() as { count: number }
-  return result.count > 0
+  if (table.count === 0) return false
+
+  const rows = db.query('SELECT COUNT(*) as count FROM columns').get() as { count: number }
+  return rows.count > 0
 }
 
 // --- Column CRUD ---
@@ -309,23 +318,25 @@ export function addTask(
     .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, labels, metadata)
-     VALUES ($id, $title, $desc, $col, $pos, $pri, $assignee, $project, $labels, $meta)`,
-  ).run({
-    $id: id,
-    $title: title,
-    $desc: opts.description ?? '',
-    $col: column.id,
-    $pos: maxPos.next,
-    $pri: opts.priority ?? 'medium',
-    $assignee: opts.assignee ?? '',
-    $project: opts.project ?? '',
-    $labels: JSON.stringify(labels),
-    $meta: opts.metadata ?? '{}',
-  })
-  logActivity(db, id, 'created', { new_value: title })
-  enterColumn(db, id, column.id)
+  db.transaction(() => {
+    db.query(
+      `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,
+      $desc: opts.description ?? '',
+      $col: column.id,
+      $pos: maxPos.next,
+      $pri: opts.priority ?? 'medium',
+      $assignee: opts.assignee ?? '',
+      $project: opts.project ?? '',
+      $labels: JSON.stringify(labels),
+      $meta: opts.metadata ?? '{}',
+    })
+    logActivity(db, id, 'created', { new_value: title })
+    enterColumn(db, id, column.id)
+  })()
   return getTask(db, id)
 }
 
@@ -453,53 +464,57 @@ export function updateTask(
     params['$meta'] = updates.metadata
   }
 
-  db.query(`UPDATE tasks SET ${sets.join(', ')} WHERE id = $id`).run(params)
+  db.transaction(() => {
+    db.query(`UPDATE tasks SET ${sets.join(', ')} WHERE id = $id`).run(params)
 
-  if (updates.assignee !== undefined && updates.assignee !== existing.assignee) {
-    logActivity(db, id, 'assigned', {
-      field: 'assignee',
-      old_value: existing.assignee || null,
-      new_value: updates.assignee,
-    })
-  }
-  if (updates.priority !== undefined && updates.priority !== existing.priority) {
-    logActivity(db, id, 'prioritized', {
-      field: 'priority',
-      old_value: existing.priority,
-      new_value: updates.priority,
-    })
-  }
-  if (updates.project !== undefined && updates.project !== existing.project) {
-    logActivity(db, id, 'updated', {
-      field: 'project',
-      old_value: existing.project || null,
-      new_value: updates.project,
-    })
-  }
-  const fieldsToLog: Array<{ key: keyof typeof updates; field: string }> = [
-    { key: 'title', field: 'title' },
-    { key: 'description', field: 'description' },
-    { key: 'metadata', field: 'metadata' },
-  ]
-  for (const { key, field } of fieldsToLog) {
-    if (updates[key] !== undefined && updates[key] !== existing[key as keyof TaskWithColumn]) {
+    if (updates.assignee !== undefined && updates.assignee !== existing.assignee) {
+      logActivity(db, id, 'assigned', {
+        field: 'assignee',
+        old_value: existing.assignee || null,
+        new_value: updates.assignee,
+      })
+    }
+    if (updates.priority !== undefined && updates.priority !== existing.priority) {
+      logActivity(db, id, 'prioritized', {
+        field: 'priority',
+        old_value: existing.priority,
+        new_value: updates.priority,
+      })
+    }
+    if (updates.project !== undefined && updates.project !== existing.project) {
       logActivity(db, id, 'updated', {
-        field,
-        old_value: String(existing[key as keyof TaskWithColumn] ?? ''),
-        new_value: String(updates[key]),
+        field: 'project',
+        old_value: existing.project || null,
+        new_value: updates.project,
       })
     }
-  }
+    const fieldsToLog: Array<{ key: keyof typeof updates; field: string }> = [
+      { key: 'title', field: 'title' },
+      { key: 'description', field: 'description' },
+      { key: 'metadata', field: 'metadata' },
+    ]
+    for (const { key, field } of fieldsToLog) {
+      if (updates[key] !== undefined && updates[key] !== existing[key as keyof TaskWithColumn]) {
+        logActivity(db, id, 'updated', {
+          field,
+          old_value: String(existing[key as keyof TaskWithColumn] ?? ''),
+          new_value: String(updates[key]),
+        })
+      }
+    }
+  })()
 
   return getTask(db, id)
 }
 
 export function deleteTask(db: Database, id: string): TaskWithColumn {
   const task = getTask(db, id)
-  exitColumn(db, id, task.column_id)
-  logActivity(db, id, 'deleted', { old_value: task.title })
-  db.query('DELETE FROM tasks WHERE id = $id').run({ $id: id })
-  renumberTasksInColumn(db, task.column_id)
+  db.transaction(() => {
+    exitColumn(db, id, task.column_id)
+    logActivity(db, id, 'deleted', { old_value: task.title })
+    db.query('DELETE FROM tasks WHERE id = $id').run({ $id: id })
+    renumberTasksInColumn(db, task.column_id)
+  })()
   return task
 }
 
@@ -557,19 +572,21 @@ export function addComment(
 ): TaskComment {
   getTask(db, taskId)
   const id = generateId('cm')
-  db.query(
-    `INSERT INTO comments (id, task_id, body, author)
-     VALUES ($id, $task_id, $body, $author)`,
-  ).run({
-    $id: id,
-    $task_id: taskId,
-    $body: body,
-    $author: author,
-  })
-  logActivity(db, taskId, 'updated', {
-    field: 'comment',
-    new_value: body,
-  })
+  db.transaction(() => {
+    db.query(
+      `INSERT INTO comments (id, task_id, body, author)
+       VALUES ($id, $task_id, $body, $author)`,
+    ).run({
+      $id: id,
+      $task_id: taskId,
+      $body: body,
+      $author: author,
+    })
+    logActivity(db, taskId, 'updated', {
+      field: 'comment',
+      new_value: body,
+    })
+  })()
   return getComment(db, taskId, id)
 }
 
@@ -580,21 +597,23 @@ export function updateComment(
   body: string,
 ): TaskComment {
   const existing = getComment(db, taskId, commentId)
-  db.query(
-    `UPDATE comments
-        SET body = $body,
-            updated_at = datetime('now')
-      WHERE id = $id AND task_id = $task_id`,
-  ).run({
-    $id: commentId,
-    $task_id: taskId,
-    $body: body,
-  })
-  logActivity(db, taskId, 'updated', {
-    field: 'comment',
-    old_value: existing.body,
-    new_value: body,
-  })
+  db.transaction(() => {
+    db.query(
+      `UPDATE comments
+          SET body = $body,
+              updated_at = datetime('now')
+        WHERE id = $id AND task_id = $task_id`,
+    ).run({
+      $id: commentId,
+      $task_id: taskId,
+      $body: body,
+    })
+    logActivity(db, taskId, 'updated', {
+      field: 'comment',
+      old_value: existing.body,
+      new_value: body,
+    })
+  })()
   return getComment(db, taskId, commentId)
 }
 
@@ -602,23 +621,29 @@ export function moveTask(db: Database, id: string, columnIdOrName: string): Task
   const task = getTask(db, id)
   const column = resolveColumn(db, columnIdOrName)
 
+  // No-op move to the same column: skip the write so we don't fragment
+  // column-time tracking (spurious exit/enter) or re-append the task.
+  if (column.id === task.column_id) return task
+
   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 }
 
   const oldColumnId = task.column_id
-  db.query(
-    "UPDATE tasks SET column_id = $col, position = $pos, updated_at = datetime('now'), revision = revision + 1 WHERE id = $id",
-  ).run({ $col: column.id, $pos: maxPos.next, $id: id })
-  renumberTasksInColumn(db, oldColumnId)
-
-  exitColumn(db, id, oldColumnId)
-  enterColumn(db, id, column.id)
-  logActivity(db, id, 'moved', {
-    field: 'column',
-    old_value: task.column_name,
-    new_value: column.name,
-  })
+  db.transaction(() => {
+    db.query(
+      "UPDATE tasks SET column_id = $col, position = $pos, updated_at = datetime('now'), revision = revision + 1 WHERE id = $id",
+    ).run({ $col: column.id, $pos: maxPos.next, $id: id })
+    renumberTasksInColumn(db, oldColumnId)
+
+    exitColumn(db, id, oldColumnId)
+    enterColumn(db, id, column.id)
+    logActivity(db, id, 'moved', {
+      field: 'column',
+      old_value: task.column_name,
+      new_value: column.name,
+    })
+  })()
 
   return getTask(db, id)
 }
@@ -661,6 +686,7 @@ export function bulkMoveAll(
 ): { moved: number } {
   const fromCol = resolveColumn(db, fromIdOrName)
   const toCol = resolveColumn(db, toIdOrName)
+  if (fromCol.id === toCol.id) return { moved: 0 }
 
   const maxPos = db
     .query('SELECT COALESCE(MAX(position), -1) + 1 as next FROM tasks WHERE column_id = $col')
@@ -673,16 +699,19 @@ export function bulkMoveAll(
   const stmt = db.prepare(
     "UPDATE tasks SET column_id = $toCol, position = $pos, updated_at = datetime('now') WHERE id = $id",
   )
-  tasks.forEach(({ id }, i) => {
-    stmt.run({ $toCol: toCol.id, $pos: maxPos.next + i, $id: id })
-    exitColumn(db, id, fromCol.id)
-    enterColumn(db, id, toCol.id)
-    logActivity(db, id, 'moved', {
-      field: 'column',
-      old_value: fromCol.name,
-      new_value: toCol.name,
+  db.transaction(() => {
+    tasks.forEach(({ id }, i) => {
+      stmt.run({ $toCol: toCol.id, $pos: maxPos.next + i, $id: id })
+      exitColumn(db, id, fromCol.id)
+      enterColumn(db, id, toCol.id)
+      logActivity(db, id, 'moved', {
+        field: 'column',
+        old_value: fromCol.name,
+        new_value: toCol.name,
+      })
     })
-  })
+    renumberTasksInColumn(db, toCol.id)
+  })()
 
   return { moved: tasks.length }
 }
@@ -697,20 +726,22 @@ export function bulkClearDone(db: Database): { deleted: number } {
   const tasks = db
     .query('SELECT id, title FROM tasks WHERE column_id = $col')
     .all({ $col: doneCol.id }) as { id: string; title: string }[]
-  for (const task of tasks) {
-    exitColumn(db, task.id, doneCol.id)
-    logActivity(db, task.id, 'deleted', { old_value: task.title })
-  }
-  db.query('DELETE FROM tasks WHERE column_id = $col').run({ $col: doneCol.id })
+  db.transaction(() => {
+    for (const task of tasks) {
+      exitColumn(db, task.id, doneCol.id)
+      logActivity(db, task.id, 'deleted', { old_value: task.title })
+    }
+    db.query('DELETE FROM tasks WHERE column_id = $col').run({ $col: doneCol.id })
+  })()
   return { deleted: tasks.length }
 }
 
-export function resetBoard(db: Database): void {
+export function resetBoard(db: Database, columnNames?: string[]): void {
   db.run('DROP TABLE IF EXISTS comments')
   db.run('DROP TABLE IF EXISTS column_time_tracking')
   db.run('DROP TABLE IF EXISTS activity_log')
   db.run('DROP TABLE IF EXISTS tasks')
   db.run('DROP TABLE IF EXISTS columns')
   initSchema(db)
-  seedDefaultColumns(db)
+  seedDefaultColumns(db, columnNames)
 }

package/src/errors.ts

@@ -4,6 +4,7 @@ export const ErrorCode = {
   TASK_NOT_FOUND: 'TASK_NOT_FOUND',
   COMMENT_NOT_FOUND: 'COMMENT_NOT_FOUND',
   COLUMN_NOT_FOUND: 'COLUMN_NOT_FOUND',
+  NOT_FOUND: 'NOT_FOUND',
   COLUMN_NOT_EMPTY: 'COLUMN_NOT_EMPTY',
   COLUMN_NAME_EXISTS: 'COLUMN_NAME_EXISTS',
   INVALID_PRIORITY: 'INVALID_PRIORITY',

package/src/index.ts

@@ -15,7 +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'
+import * as useCases from './use-cases'
 
 interface ParsedArgs {
   values: Record<string, unknown>
@@ -64,21 +64,21 @@ async function routeTask(
       const title = positionals[2]
       if (!title) throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Task title is required')
       return success(
-        await provider.createTask({
+        await useCases.createTask(provider, {
           title,
           description: values.d as string | undefined,
           column: values.c as string | undefined,
           priority: values.p as Priority | undefined,
           assignee: values.a as string | undefined,
           project: values.project as string | undefined,
-          labels: normalizeLabels([values.label, values.labels]),
+          labels: [values.label, values.labels],
           metadata: values.m as string | undefined,
         }),
       )
     }
     case 'list':
       return success(
-        await provider.listTasks({
+        await useCases.listTasks(provider, {
           column: values.c as string | undefined,
           priority: values.p as string | undefined,
           assignee: values.a as string | undefined,
@@ -90,13 +90,13 @@ async function routeTask(
     case 'view': {
       const id = positionals[2]
       if (!id) throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Task ID is required')
-      return success(await provider.getTask(id))
+      return success(await useCases.getTask(provider, id))
     }
     case 'update': {
       const id = positionals[2]
       if (!id) throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Task ID is required')
       return success(
-        await provider.updateTask(id, {
+        await useCases.updateTask(provider, id, {
           title: values.title as string | undefined,
           description: values.d as string | undefined,
           priority: values.p as Priority | undefined,
@@ -109,7 +109,7 @@ async function routeTask(
     case 'delete': {
       const id = positionals[2]
       if (!id) throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Task ID is required')
-      return success(await provider.deleteTask(id))
+      return success(await useCases.deleteTask(provider, id))
     }
     case 'move': {
       const id = positionals[2]
@@ -117,7 +117,7 @@ async function routeTask(
       if (!id || !column) {
         throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Usage: kanban task move <id> <column>')
       }
-      return success(await provider.moveTask(id, column))
+      return success(await useCases.moveTask(provider, id, column))
     }
     case 'assign': {
       const id = positionals[2]
@@ -128,7 +128,7 @@ async function routeTask(
           'Usage: kanban task assign <id> <assignee>',
         )
       }
-      return success(await provider.updateTask(id, { assignee }))
+      return success(await useCases.updateTask(provider, id, { assignee }))
     }
     case 'prioritize': {
       const id = positionals[2]
@@ -139,7 +139,7 @@ async function routeTask(
           'Usage: kanban task prioritize <id> <level>',
         )
       }
-      return success(await provider.updateTask(id, { priority: priority as Priority }))
+      return success(await useCases.updateTask(provider, id, { priority: priority as Priority }))
     }
     default:
       throw new KanbanError(ErrorCode.UNKNOWN_COMMAND, `Unknown task command '${action}'`)
@@ -155,7 +155,7 @@ async function routeComment(
     case 'list': {
       const id = positionals[2]
       if (!id) throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Task ID is required')
-      return success(await provider.listComments(id))
+      return success(await useCases.listComments(provider, id))
     }
     case 'add': {
       const id = positionals[2]
@@ -166,7 +166,7 @@ async function routeComment(
           'Usage: kanban comment add <task-id> <body>',
         )
       }
-      return success(await provider.comment(id, body))
+      return success(await useCases.addComment(provider, id, body))
     }
     case 'update': {
       const id = positionals[2]
@@ -178,7 +178,7 @@ async function routeComment(
           'Usage: kanban comment update <task-id> <comment-id> <body>',
         )
       }
-      return success(await provider.updateComment(id, commentId, body))
+      return success(await useCases.updateComment(provider, id, commentId, body))
     }
     default:
       throw new KanbanError(ErrorCode.UNKNOWN_COMMAND, `Unknown comment command '${action}'`)
@@ -239,7 +239,7 @@ async function routeConfig(
 ): Promise<CliOutput> {
   if (provider.type !== 'local') {
     if (action === 'show' || action === undefined) {
-      return success(await provider.getConfig())
+      return success(await useCases.getConfig(provider))
     }
     unsupportedOperation('Config mutation is only available in local mode')
   }
@@ -250,7 +250,7 @@ async function routeConfig(
   switch (action) {
     case 'show':
     case undefined:
-      return success(await provider.getConfig())
+      return success(await useCases.getConfig(provider))
     case 'set-member': {
       const name = positionals[2]
       if (!name) throw new KanbanError(ErrorCode.MISSING_ARGUMENT, 'Member name is required')
@@ -297,21 +297,22 @@ async function routeBoard(
   db: Database,
   provider: KanbanProvider,
   action: string | undefined,
+  columnNames?: string[],
 ): Promise<CliOutput> {
   switch (action) {
     case 'init':
       requireLocalProvider(provider.type, 'Board initialization')
-      return boardInit(db)
+      return boardInit(db, columnNames)
     case 'view':
     case undefined:
       if (provider.type === 'local') {
         initSchema(db)
-        seedDefaultColumns(db)
+        seedDefaultColumns(db, columnNames)
       }
-      return success(await provider.getBoard())
+      return success(await useCases.getBoard(provider))
     case 'reset':
       requireLocalProvider(provider.type, 'Board reset')
-      return boardReset(db)
+      return boardReset(db, columnNames)
     default:
       throw new KanbanError(ErrorCode.UNKNOWN_COMMAND, `Unknown board command '${action}'`)
   }
@@ -323,27 +324,36 @@ async function run(argv: string[]): Promise<{ output: CliOutput; exitCode: numbe
     return { output: { ok: true, data: { message: HELP_TEXT } }, exitCode: 0 }
   }
 
+  const actionRequiresExplicitInit = positionals[0] === 'board' && positionals[1] === 'init'
   const runtime = await openKanbanRuntime({
     dbPath: (values.db as string | undefined) ?? getDbPath(),
+    seedLocalColumns: actionRequiresExplicitInit ? false : undefined,
   })
 
   try {
-    const { provider, sqliteDb, dbPath } = runtime
+    const { provider, sqliteDb, dbPath, trackerConfig } = runtime
     const group = positionals[0]
     const action = positionals[1]
+    const defaultColumns =
+      trackerConfig.provider === 'local' ? trackerConfig.defaultColumns : undefined
 
     if (!group) {
-      if (sqliteDb) return { output: await routeBoard(sqliteDb, provider, undefined), exitCode: 0 }
-      return { output: success(await provider.getBoard()), exitCode: 0 }
+      if (sqliteDb)
+        return {
+          output: await routeBoard(sqliteDb, provider, undefined, defaultColumns),
+          exitCode: 0,
+        }
+      return { output: success(await useCases.getBoard(provider)), exitCode: 0 }
     }
 
     let output: CliOutput
     switch (group) {
       case 'board':
         if (sqliteDb) {
-          output = await routeBoard(sqliteDb, provider, action)
+          output = await routeBoard(sqliteDb, provider, action, defaultColumns)
         } else {
-          if (action === 'view' || action === undefined) output = success(await provider.getBoard())
+          if (action === 'view' || action === undefined)
+            output = success(await useCases.getBoard(provider))
           else unsupportedOperation(`board ${action} is not available with KANBAN_STORAGE=postgres`)
         }
         break
@@ -368,7 +378,7 @@ async function run(argv: string[]): Promise<{ output: CliOutput; exitCode: numbe
           output = await routeConfig(provider, dbPath, action, positionals, values)
         } else {
           if (action === 'show' || action === undefined)
-            output = success(await provider.getConfig())
+            output = success(await useCases.getConfig(provider))
           else
             unsupportedOperation(`config ${action} is not available with KANBAN_STORAGE=postgres`)
         }
@@ -435,6 +445,8 @@ export interface ServeOptions {
   port: number
   syncIntervalMs?: number
   tunnel: boolean
+  authToken?: string
+  allowedOrigin?: string
 }
 
 export function parseServeArgs(argv: string[]): ServeOptions {
@@ -445,6 +457,8 @@ export function parseServeArgs(argv: string[]): ServeOptions {
       port: { type: 'string' },
       'sync-interval-ms': { type: 'string' },
       tunnel: { type: 'boolean', default: false },
+      token: { type: 'string' },
+      'allowed-origin': { type: 'string' },
     },
     strict: false,
     allowPositionals: true,
@@ -452,6 +466,10 @@ export function parseServeArgs(argv: string[]): ServeOptions {
   const port = values.port
     ? parseInt(values.port as string, 10)
     : parseInt(process.env['PORT'] || '3000', 10)
+  // Flags win over env so a one-off `--token` can override the ambient config.
+  const authToken = (values.token as string | undefined) || process.env['KANBAN_API_TOKEN']
+  const allowedOrigin =
+    (values['allowed-origin'] as string | undefined) || process.env['KANBAN_ALLOWED_ORIGIN']
   return {
     db: values.db as string | undefined,
     port,
@@ -459,6 +477,8 @@ export function parseServeArgs(argv: string[]): ServeOptions {
       ? { syncIntervalMs: parseSyncIntervalMs(values['sync-interval-ms'] as string) }
       : {}),
     tunnel: Boolean(values.tunnel),
+    ...(authToken ? { authToken } : {}),
+    ...(allowedOrigin ? { allowedOrigin } : {}),
   }
 }
 
@@ -495,6 +515,16 @@ if (import.meta.main) {
   } else if (argv[0] === 'serve') {
     const opts = parseServeArgs(argv)
 
+    // A tunnel exposes the dashboard publicly, so refuse to start one without a
+    // token. Plain localhost serve stays open for backward compatibility.
+    if (opts.tunnel && !opts.authToken) {
+      console.error(
+        'Refusing to start a public tunnel without an API token. ' +
+          'Set KANBAN_API_TOKEN or pass --token <token>.',
+      )
+      process.exit(1)
+    }
+
     const runtime = await openKanbanRuntime({
       dbPath: opts.db ?? getDbPath(),
       ...(opts.syncIntervalMs !== undefined
@@ -507,22 +537,43 @@ if (import.meta.main) {
         : {}),
     })
     const { startServer } = await import('./server')
-    startServer(runtime.provider, opts.port, { syncIntervalMs: runtime.syncIntervalMs })
+    const server = startServer(runtime.provider, opts.port, {
+      syncIntervalMs: runtime.syncIntervalMs,
+      ...(opts.authToken ? { authToken: opts.authToken } : {}),
+      ...(opts.allowedOrigin ? { allowedOrigin: opts.allowedOrigin } : {}),
+    })
 
+    let tunnelHandle: { stop: () => void } | null = null
     if (opts.tunnel) {
       const { startCloudflareTunnel } = await import('./tunnel')
       try {
-        const handle = startCloudflareTunnel(opts.port)
-        const shutdown = (): void => {
-          handle.stop()
-          process.exit(0)
-        }
-        process.on('SIGINT', shutdown)
-        process.on('SIGTERM', shutdown)
+        tunnelHandle = startCloudflareTunnel(opts.port)
       } catch {
         // startCloudflareTunnel already logged a friendly message
       }
     }
+
+    // Shut down gracefully on signals regardless of tunnel mode: stop the tunnel
+    // and server (which clears the background-sync timer), then close the runtime
+    // so the Postgres pool / SQLite handle is released.
+    let shuttingDown = false
+    const shutdown = async (): Promise<void> => {
+      if (shuttingDown) return
+      shuttingDown = true
+      // try/finally so a cleanup failure (e.g. runtime.close() rejecting) still
+      // exits the process instead of leaving an unhandled rejection and a hang.
+      try {
+        tunnelHandle?.stop()
+        server.stop()
+        await runtime.close()
+      } catch (err) {
+        console.error('Error during shutdown:', err instanceof Error ? err.message : err)
+      } finally {
+        process.exit(0)
+      }
+    }
+    process.on('SIGINT', () => void shutdown())
+    process.on('SIGTERM', () => void shutdown())
   } else {
     let exitCode = 0
     const pretty = argv.includes('--pretty')