@loicngr/kobo 1.5.6 → 1.5.7

package/dist/server/db/migrations.js

@@ -64,6 +64,20 @@ export const migrations = [
             db.exec("ALTER TABLE workspaces ADD COLUMN reasoning_effort TEXT NOT NULL DEFAULT 'auto'");
         },
     },
+    {
+        version: 8,
+        name: 'add-workspace-favorited-at',
+        migrate: (db) => {
+            db.prepare('ALTER TABLE workspaces ADD COLUMN favorited_at TEXT').run();
+        },
+    },
+    {
+        version: 9,
+        name: 'add-workspace-tags',
+        migrate: (db) => {
+            db.prepare("ALTER TABLE workspaces ADD COLUMN tags TEXT NOT NULL DEFAULT '[]'").run();
+        },
+    },
 ];
 /** Current schema version — always equals the highest migration version. */
 export const SCHEMA_VERSION = migrations.length > 0 ? migrations[migrations.length - 1].version : 1;

package/dist/server/db/schema.js

@@ -16,6 +16,8 @@ export function initSchema(db) {
       dev_server_status TEXT NOT NULL DEFAULT 'stopped',
       has_unread INTEGER NOT NULL DEFAULT 0,
       archived_at TEXT,
+      favorited_at TEXT,
+      tags TEXT NOT NULL DEFAULT '[]',
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL
     );

package/dist/server/index.js

@@ -9,20 +9,23 @@ import { closeDb, getDb } from './db/index.js';
 import { runMigrations } from './db/migrations.js';
 import devServerRouter from './routes/dev-server.js';
 import gitRouter from './routes/git.js';
+import healthRouter from './routes/health.js';
 import imagesRouter from './routes/images.js';
 import notionRouter from './routes/notion.js';
 import plansRouter from './routes/plans.js';
+import searchRouter from './routes/search.js';
 import sentryRouter from './routes/sentry.js';
 import settingsRouter from './routes/settings.js';
 import templatesRouter from './routes/templates.js';
 import workspacesRouter from './routes/workspaces.js';
 import { getAvailableSkills, sendMessage, setBackendPort, startAgent, startWatchdog, stopAgent, stopWatchdog, } from './services/agent-manager.js';
+import { createDailyDbBackupIfNeeded } from './services/db-backup-service.js';
 import { startDevServer, stopDevServer } from './services/dev-server-service.js';
 import { startPrWatcher, stopPrWatcher } from './services/pr-watcher-service.js';
 import { createTerminal, destroyAllTerminals, getTerminal } from './services/terminal-service.js';
 import { emit, handleConnection, setMessageHandler } from './services/websocket-service.js';
 import { getActiveSession, getWorkspace, updateWorkspaceStatus } from './services/workspace-service.js';
-import { getClientSpaPath, getKoboHome, getPackageVersion } from './utils/paths.js';
+import { getClientSpaPath, getDbPath, getKoboHome, getPackageVersion } from './utils/paths.js';
 import { initProcessCleanup, killAll as killAllTrackedProcesses } from './utils/process-tracker.js';
 // Runtime prerequisite check — warn if the claude CLI is missing. Don't block
 // startup: the user may still want to configure settings or browse workspaces.
@@ -36,6 +39,17 @@ console.log(`[kobo] Kōbō home: ${getKoboHome()}`);
 // Initialize DB + run migrations
 const db = getDb();
 runMigrations(db);
+// Daily DB backup (best-effort, fire-and-forget — never blocks boot).
+// Creates a WAL-safe snapshot alongside kobo.db if no backup exists in the
+// last 24h, and rotates out older backups beyond the retention window.
+void createDailyDbBackupIfNeeded(db, getDbPath()).then((r) => {
+    if (r.created) {
+        console.log(`[kobo] Daily DB backup: ${r.created}`);
+        if (r.deleted.length > 0) {
+            console.log(`[kobo] Rotated ${r.deleted.length} old DB backup(s)`);
+        }
+    }
+});
 // Initialize process cleanup, agent watchdog, and PR watcher
 initProcessCleanup();
 startWatchdog();
@@ -54,6 +68,8 @@ app.route('/api/settings', settingsRouter);
 app.route('/api/dev-server', devServerRouter);
 app.route('/api/templates', templatesRouter);
 app.route('/api/workspaces', plansRouter);
+app.route('/api/search', searchRouter);
+app.route('/api/health', healthRouter);
 // Skills endpoint
 app.get('/api/skills', (c) => c.json(getAvailableSkills()));
 const PORT = parseInt(process.env.SERVER_PORT || process.env.PORT || '3000', 10);

package/dist/server/routes/dev-server.js

@@ -11,7 +11,7 @@ app.get('/:workspaceId/status', (c) => {
         if (!workspace) {
             return c.json({ error: `Workspace '${workspaceId}' not found` }, 404);
         }
-        const status = getStatus(workspace.projectPath, workspace.workingBranch);
+        const status = getStatus(workspace.projectPath, workspace.workingBranch, workspaceId);
         // If runtime detection returns unknown, use persisted status from DB
         if (status.status === 'unknown' && workspace.devServerStatus && workspace.devServerStatus !== 'stopped') {
             status.status = workspace.devServerStatus;

package/dist/server/routes/health.js

@@ -0,0 +1,95 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Hono } from 'hono';
+import { getDb } from '../db/index.js';
+import { SCHEMA_VERSION } from '../db/migrations.js';
+import { getGlobalSettings, SETTINGS_SCHEMA_VERSION } from '../services/settings-service.js';
+import { getDbPath, getKoboHome } from '../utils/paths.js';
+const app = new Hono();
+function checkClaudeCli() {
+    try {
+        const r = spawnSync('claude', ['--version'], { encoding: 'utf-8' });
+        if (r.error || r.status !== 0)
+            return { available: false, version: null };
+        return { available: true, version: (r.stdout ?? '').trim() || null };
+    }
+    catch {
+        return { available: false, version: null };
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function safeFileSize(p) {
+    try {
+        return fs.statSync(p).size;
+    }
+    catch {
+        return null;
+    }
+}
+// GET /api/health/report — detailed health diagnostics for the Health panel.
+app.get('/report', (c) => {
+    const db = getDb();
+    const dbPath = getDbPath();
+    const home = getKoboHome();
+    // DB schema version
+    const row = db.prepare('SELECT MAX(version) as v FROM schema_migrations').get();
+    const dbSchemaVersion = row?.v ?? 0;
+    // Workspaces + worktrees on-disk check
+    const workspaces = db
+        .prepare('SELECT id, name, project_path, working_branch, archived_at FROM workspaces')
+        .all();
+    const worktreesMissing = [];
+    for (const ws of workspaces) {
+        if (ws.archived_at)
+            continue;
+        const wtPath = path.join(ws.project_path, '.worktrees', ws.working_branch);
+        if (!fs.existsSync(wtPath)) {
+            worktreesMissing.push({ workspaceId: ws.id, name: ws.name, path: wtPath, exists: false });
+        }
+    }
+    // Orphan agent sessions — marked running but PID no longer alive
+    const runningSessions = db
+        .prepare("SELECT pid FROM agent_sessions WHERE status = 'running' AND pid IS NOT NULL")
+        .all();
+    let orphaned = 0;
+    for (const s of runningSessions) {
+        if (s.pid && !isProcessAlive(s.pid))
+            orphaned++;
+    }
+    const globalSettings = getGlobalSettings();
+    const settingsRow = db.prepare('SELECT COUNT(*) as n FROM workspaces').get();
+    const archivedRow = db.prepare('SELECT COUNT(*) as n FROM workspaces WHERE archived_at IS NOT NULL').get();
+    const report = {
+        koboHome: home,
+        db: {
+            path: dbPath,
+            sizeBytes: safeFileSize(dbPath),
+            schemaVersion: dbSchemaVersion,
+            currentSchemaVersion: SCHEMA_VERSION,
+        },
+        settings: { schemaVersion: SETTINGS_SCHEMA_VERSION },
+        claudeCli: checkClaudeCli(),
+        workspaces: {
+            total: settingsRow.n,
+            archived: archivedRow.n,
+            worktreesMissing,
+        },
+        agentSessions: { orphaned },
+        integrations: {
+            notion: { configured: Boolean(globalSettings.notionMcpKey) },
+            sentry: { configured: Boolean(globalSettings.sentryMcpKey) },
+            editor: { configured: Boolean(globalSettings.editorCommand) },
+        },
+    };
+    return c.json(report);
+});
+export default app;

package/dist/server/routes/search.js

@@ -0,0 +1,33 @@
+import { Hono } from 'hono';
+import { searchEvents } from '../services/search-service.js';
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+const app = new Hono();
+// GET /api/search?q=...&limit=50&includeArchived=true
+// Search readable text across ws_events (user messages + agent outputs),
+// joined with workspaces. Returns up to `limit` snippets, most recent first.
+app.get('/', (c) => {
+    const qRaw = c.req.query('q') ?? '';
+    const q = qRaw.trim();
+    if (!q) {
+        return c.json({ error: "Missing or empty 'q' query parameter" }, 400);
+    }
+    let limit = DEFAULT_LIMIT;
+    const limitRaw = c.req.query('limit');
+    if (limitRaw) {
+        const parsed = parseInt(limitRaw, 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            limit = Math.min(parsed, MAX_LIMIT);
+        }
+    }
+    const includeArchived = c.req.query('includeArchived') === 'true';
+    try {
+        const results = searchEvents(q, { limit, includeArchived });
+        return c.json(results);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+export default app;

package/dist/server/routes/settings.js

@@ -1,5 +1,6 @@
 import { Hono } from 'hono';
 import * as settingsService from '../services/settings-service.js';
+import { listTemplates, replaceAllTemplates } from '../services/templates-service.js';
 /** Hono sub-router for global and per-project settings CRUD. */
 const app = new Hono();
 // GET /api/settings — return full settings
@@ -101,4 +102,33 @@ app.delete('/projects/:encodedPath', (c) => {
         return c.json({ error: message }, 500);
     }
 });
+// GET /api/settings/export — download a JSON bundle of settings + templates (MCP keys stripped)
+app.get('/export', (c) => {
+    try {
+        const bundle = settingsService.exportConfigBundle(listTemplates());
+        return c.json(bundle);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+// POST /api/settings/import — replace settings + templates from an uploaded bundle
+app.post('/import', async (c) => {
+    try {
+        const body = (await c.req.json());
+        // Validate settings first — throws on malformed payload before we touch disk.
+        settingsService.importConfigBundle(body);
+        if (body.templates !== undefined) {
+            // Accept missing templates (backward-compatible). Otherwise validate and replace.
+            replaceAllTemplates(body.templates);
+        }
+        return c.json({ ok: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const isValidation = message.includes('Invalid bundle') || message.includes('Invalid template');
+        return c.json({ error: message }, isValidation ? 400 : 500);
+    }
+});
 export default app;

package/dist/server/routes/workspaces.js

@@ -756,6 +756,52 @@ app.get('/:id', (c) => {
         return c.json({ error: message }, 500);
     }
 });
+// POST /api/workspaces/:id/favorite — mark workspace as favorite
+app.post('/:id/favorite', (c) => {
+    const { id } = c.req.param();
+    try {
+        const ws = workspaceService.setFavorite(id);
+        return c.json(ws);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        const status = msg.includes('not found') ? 404 : 500;
+        return c.json({ error: msg }, status);
+    }
+});
+// DELETE /api/workspaces/:id/favorite — remove favorite from workspace
+app.delete('/:id/favorite', (c) => {
+    const { id } = c.req.param();
+    try {
+        const ws = workspaceService.unsetFavorite(id);
+        return c.json(ws);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        const status = msg.includes('not found') ? 404 : 500;
+        return c.json({ error: msg }, status);
+    }
+});
+// PUT /api/workspaces/:id/tags — replace the workspace's tag list
+app.put('/:id/tags', async (c) => {
+    const { id } = c.req.param();
+    try {
+        const body = await c.req.json();
+        if (!Array.isArray(body.tags)) {
+            return c.json({ error: 'tags must be an array of strings' }, 400);
+        }
+        if (body.tags.some((t) => typeof t !== 'string')) {
+            return c.json({ error: 'tags must contain only strings' }, 400);
+        }
+        const ws = workspaceService.setWorkspaceTags(id, body.tags);
+        return c.json(ws);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        const status = msg.includes('not found') ? 404 : 500;
+        return c.json({ error: msg }, status);
+    }
+});
 // PATCH /api/workspaces/:id — update workspace fields (status, model, permissionMode, name)
 app.patch('/:id', async (c) => {
     try {

package/dist/server/services/db-backup-service.js

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const BACKUP_PREFIX = 'kobo.db.backup-';
+const DEFAULT_KEEP = 7;
+const DAILY_MS = 24 * 60 * 60 * 1000;
+let backupSequence = 0;
+/** Test-only: reset the in-process monotonic sequence to 0. */
+export function _resetBackupSequenceForTests() {
+    backupSequence = 0;
+}
+function listBackups(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.startsWith(BACKUP_PREFIX))
+        .map((f) => {
+        const full = path.join(dir, f);
+        const stat = fs.statSync(full);
+        return { path: full, mtimeMs: stat.mtimeMs };
+    })
+        .sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+/**
+ * Create a WAL-safe snapshot of the Kōbō DB if no backup has been made in the
+ * last 24h. Rotates old backups, keeping only the `keepCount` most recent.
+ *
+ * - Location: same directory as `dbPath`, named `kobo.db.backup-<ISO>-<seq>`
+ *   (mirrors the settings.json backup convention).
+ * - Uses better-sqlite3's online `.backup()` API, which is safe while the DB
+ *   is open and under write load (WAL mode).
+ * - Best-effort: never throws. On failure, logs to console.error and returns
+ *   `{ created: null, deleted: [] }` so the boot path is never blocked.
+ */
+export async function createDailyDbBackupIfNeeded(db, dbPath, keepCount = DEFAULT_KEEP, nowMs = Date.now()) {
+    const result = { created: null, deleted: [] };
+    const dir = path.dirname(dbPath);
+    try {
+        const existing = listBackups(dir);
+        const latestMtime = existing[0]?.mtimeMs ?? 0;
+        if (latestMtime && nowMs - latestMtime < DAILY_MS) {
+            return result;
+        }
+        const stamp = new Date(nowMs).toISOString().replace(/[:.]/g, '-');
+        backupSequence += 1;
+        const backupPath = path.join(dir, `${BACKUP_PREFIX}${stamp}-${backupSequence}`);
+        await db.backup(backupPath);
+        result.created = backupPath;
+        const all = listBackups(dir);
+        if (all.length > keepCount) {
+            for (const entry of all.slice(keepCount)) {
+                try {
+                    fs.unlinkSync(entry.path);
+                    result.deleted.push(entry.path);
+                }
+                catch (err) {
+                    console.error(`[kobo] Failed to delete old DB backup ${entry.path}:`, err);
+                }
+            }
+        }
+    }
+    catch (err) {
+        console.error('[kobo] DB daily backup failed:', err);
+    }
+    return result;
+}

package/dist/server/services/dev-server-service.js

@@ -16,6 +16,10 @@ function cleanEnv() {
 // ── State ──────────────────────────────────────────────────────────────────────
 /** workspaceId -> spawned dev-server process */
 const trackedProcesses = new Map();
+/** Test-only: clear the tracked-processes map between tests. */
+export function _resetTrackedProcessesForTests() {
+    trackedProcesses.clear();
+}
 // ── Pure helpers ───────────────────────────────────────────────────────────────
 /**
  * Sanitize a branch name for use as a Docker instance name.
@@ -94,8 +98,14 @@ export function listRunningContainers() {
 // ── Status ─────────────────────────────────────────────────────────────────────
 /**
  * Get the dev-server status for a given project + branch.
+ *
+ * When `workspaceId` is provided and a start process for that workspace is
+ * still running (e.g. `docker compose up -d` is pulling/building images), the
+ * status is reported as `'starting'` even if no matching container is visible
+ * in `docker ps` yet. This prevents the UI from flashing to `'stopped'` during
+ * long build phases.
  */
-export function getStatus(projectPath, workingBranch) {
+export function getStatus(projectPath, workingBranch, workspaceId) {
     const config = resolveInstance(projectPath, workingBranch);
     if (!config) {
         return {
@@ -119,6 +129,19 @@ export function getStatus(projectPath, workingBranch) {
             containers: matching,
         };
     }
+    // No matching container yet — but is a start process still in flight?
+    // This covers the long `docker compose up -d` build/pull phase where the
+    // CLI hasn't exited yet and containers haven't appeared in `docker ps`.
+    if (workspaceId && trackedProcesses.has(workspaceId)) {
+        return {
+            status: 'starting',
+            instanceName: config.instanceName,
+            projectName: config.projectName,
+            httpPort: config.httpPort,
+            url: '',
+            containers: [],
+        };
+    }
     return {
         status: 'stopped',
         instanceName: config.instanceName,

package/dist/server/services/search-service.js

@@ -0,0 +1,102 @@
+import { getDb } from '../db/index.js';
+/** Event types that carry user-authored or assistant-authored readable text. */
+const SEARCHABLE_TYPES = ['user:message', 'agent:output'];
+const SNIPPET_CONTEXT = 100; // chars on each side of the match
+/**
+ * Extract the readable text content of a ws_events payload, or `null` when
+ * the event carries no natural-language content (system events, rate-limit
+ * pings, etc.).
+ */
+function extractReadableText(type, payload) {
+    if (!payload || typeof payload !== 'object')
+        return null;
+    const p = payload;
+    if (type === 'user:message') {
+        return typeof p.content === 'string' ? p.content : null;
+    }
+    if (type === 'agent:output') {
+        // Claude Code streams `{type: 'assistant', message: {content: [{type: 'text', text: '...'}, ...]}}`
+        const msg = p.message;
+        if (msg && Array.isArray(msg.content)) {
+            const parts = [];
+            for (const block of msg.content) {
+                if (block && typeof block === 'object') {
+                    const b = block;
+                    if (b.type === 'text' && typeof b.text === 'string')
+                        parts.push(b.text);
+                }
+            }
+            return parts.length > 0 ? parts.join('\n') : null;
+        }
+    }
+    return null;
+}
+function buildSnippet(text, matchIndex, query) {
+    const start = Math.max(0, matchIndex - SNIPPET_CONTEXT);
+    const end = Math.min(text.length, matchIndex + query.length + SNIPPET_CONTEXT);
+    const prefix = start > 0 ? '…' : '';
+    const suffix = end < text.length ? '…' : '';
+    return `${prefix}${text.slice(start, end).trim()}${suffix}`;
+}
+/**
+ * Full-text-ish search across `ws_events.payload` joined with `workspaces`.
+ *
+ * - Trimmed empty queries return `[]` without hitting the database.
+ * - SQLite does the first filter via `LIKE '%q%'` on the raw payload JSON.
+ *   Results are then post-filtered in JS against the **readable** text
+ *   (extracted from the JSON) to avoid false positives like matches inside
+ *   field names or schema strings.
+ * - Snippets are 100 chars of context on either side of the first match.
+ */
+export function searchEvents(query, options = {}) {
+    const trimmed = query.trim();
+    if (trimmed.length === 0)
+        return [];
+    const { limit = 50, includeArchived = false } = options;
+    const db = getDb();
+    const typePlaceholders = SEARCHABLE_TYPES.map(() => '?').join(', ');
+    const archiveFilter = includeArchived ? '' : 'AND w.archived_at IS NULL';
+    const likePattern = `%${trimmed}%`;
+    // Over-fetch a bit so post-filter rejects don't shrink us below `limit` on
+    // realistic datasets, without scanning the entire table.
+    const dbLimit = Math.max(limit * 3, 100);
+    const rows = db
+        .prepare(`SELECT e.workspace_id, e.type, e.created_at, e.payload,
+              w.name AS workspace_name, w.archived_at
+       FROM ws_events e
+       JOIN workspaces w ON e.workspace_id = w.id
+       WHERE e.type IN (${typePlaceholders})
+         AND e.payload LIKE ?
+         ${archiveFilter}
+       ORDER BY e.created_at DESC
+       LIMIT ?`)
+        .all(...SEARCHABLE_TYPES, likePattern, dbLimit);
+    const needle = trimmed.toLowerCase();
+    const results = [];
+    for (const row of rows) {
+        let parsed;
+        try {
+            parsed = JSON.parse(row.payload);
+        }
+        catch {
+            continue;
+        }
+        const text = extractReadableText(row.type, parsed);
+        if (!text)
+            continue;
+        const idx = text.toLowerCase().indexOf(needle);
+        if (idx < 0)
+            continue;
+        results.push({
+            workspaceId: row.workspace_id,
+            workspaceName: row.workspace_name,
+            archived: row.archived_at !== null,
+            type: row.type,
+            timestamp: row.created_at,
+            snippet: buildSnippet(text, idx, trimmed),
+        });
+        if (results.length >= limit)
+            break;
+    }
+    return results;
+}

package/dist/server/services/settings-service.js

@@ -53,6 +53,8 @@ Please:
 3. Post a comment on the PR summarizing what was done and any follow-up items
 4. Do NOT add a "Generated with Claude Code" footer or any AI attribution to the PR description
 `;
+/** Default workspace tags seeded on fresh install and on settings upgrade. */
+export const DEFAULT_WORKSPACE_TAGS = ['bug', 'feature', 'refactor', 'docs', 'wip', 'urgent', 'blocked'];
 const settingsMigrations = [
     {
         version: 1,
@@ -136,6 +138,14 @@ const settingsMigrations = [
                 global.sentryMcpKey = '';
         },
     },
+    {
+        version: 8,
+        name: 'add-workspace-tags',
+        migrate({ global }) {
+            if (!Array.isArray(global.tags))
+                global.tags = [...DEFAULT_WORKSPACE_TAGS];
+        },
+    },
 ];
 /** Current settings schema version — always equals the highest migration version. */
 export const SETTINGS_SCHEMA_VERSION = settingsMigrations.length > 0 ? settingsMigrations[settingsMigrations.length - 1].version : 0;
@@ -175,6 +185,7 @@ function defaultSettings() {
             defaultPermissionMode: 'plan',
             notionMcpKey: '',
             sentryMcpKey: '',
+            tags: [...DEFAULT_WORKSPACE_TAGS],
         },
         projects: [],
     };
@@ -189,8 +200,6 @@ function defaultProjectSettings(projectPath) {
         prPromptTemplate: '',
         gitConventions: '',
         setupScript: '',
-        notionInProgressStatus: '',
-        notionStatusProperty: '',
         devServer: {
             startCommand: '',
             stopCommand: '',
@@ -281,6 +290,58 @@ function writeSettings(settings, options) {
 export function getSettings() {
     return readSettings();
 }
+/** Keys stripped from exports — secrets that should stay on the machine. */
+const SECRET_GLOBAL_KEYS = ['notionMcpKey', 'sentryMcpKey'];
+/** Build an export bundle with settings + templates. MCP keys are stripped. */
+export function exportConfigBundle(templates) {
+    const settings = readSettings();
+    const sanitizedGlobal = { ...settings.global };
+    for (const key of SECRET_GLOBAL_KEYS) {
+        sanitizedGlobal[key] = '';
+    }
+    return {
+        bundleVersion: 1,
+        exportedAt: new Date().toISOString(),
+        settings: { ...settings, global: sanitizedGlobal },
+        templates,
+    };
+}
+/** Replace the settings file with an imported bundle. MCP keys in the current settings are preserved. */
+export function importConfigBundle(bundle) {
+    if (!bundle || typeof bundle !== 'object') {
+        throw new Error('Invalid bundle: payload must be an object');
+    }
+    if (bundle.bundleVersion !== 1) {
+        throw new Error('Invalid bundle: expected bundleVersion = 1');
+    }
+    const incoming = bundle.settings;
+    if (!incoming || typeof incoming !== 'object') {
+        throw new Error('Invalid bundle: missing or malformed settings');
+    }
+    const incomingSettings = incoming;
+    if (!incomingSettings.global ||
+        typeof incomingSettings.global !== 'object' ||
+        Array.isArray(incomingSettings.global)) {
+        throw new Error('Invalid bundle: settings.global must be an object');
+    }
+    if (!Array.isArray(incomingSettings.projects)) {
+        throw new Error('Invalid bundle: settings.projects must be an array');
+    }
+    for (let i = 0; i < incomingSettings.projects.length; i++) {
+        const p = incomingSettings.projects[i];
+        if (!p || typeof p !== 'object' || Array.isArray(p)) {
+            throw new Error(`Invalid bundle: settings.projects[${i}] must be an object`);
+        }
+    }
+    const current = readSettings();
+    // Run the incoming through the migration pipeline in case an older version is imported.
+    const migrated = runSettingsMigrations(incoming);
+    // Preserve existing MCP keys — the export stripped them and we don't want to clobber a local config.
+    for (const key of SECRET_GLOBAL_KEYS) {
+        migrated.global[key] = current.global[key];
+    }
+    writeSettings(migrated, { backup: true });
+}
 /** Return only the global settings section. */
 export function getGlobalSettings() {
     return readSettings().global;
@@ -315,8 +376,8 @@ export function getEffectiveSettings(projectPath) {
         sourceBranch: project.defaultSourceBranch,
         devServer: project.devServer,
         setupScript: project.setupScript || '',
-        notionStatusProperty: project.notionStatusProperty || settings.global.notionStatusProperty,
-        notionInProgressStatus: project.notionInProgressStatus || settings.global.notionInProgressStatus,
+        notionStatusProperty: settings.global.notionStatusProperty,
+        notionInProgressStatus: settings.global.notionInProgressStatus,
     };
 }
 /** Merge partial updates into global settings and persist. */
@@ -335,8 +396,16 @@ export function updateGlobalSettings(data) {
         'defaultPermissionMode',
         'notionMcpKey',
         'sentryMcpKey',
+        'tags',
     ];
     const filtered = pickKnownKeys(data, allowedGlobalKeys);
+    if (filtered.tags !== undefined) {
+        filtered.tags = Array.isArray(filtered.tags)
+            ? Array.from(new Set(filtered.tags
+                .map((t) => (typeof t === 'string' ? t.trim() : ''))
+                .filter((t) => t.length > 0 && t.length <= 50)))
+            : settings.global.tags;
+    }
     settings.global = { ...settings.global, ...filtered };
     writeSettings(settings, { backup: true });
     return settings.global;
@@ -351,8 +420,6 @@ export function upsertProject(projectPath, data) {
         'prPromptTemplate',
         'gitConventions',
         'setupScript',
-        'notionStatusProperty',
-        'notionInProgressStatus',
         'devServer',
     ];
     const allowedDevServerKeys = ['startCommand', 'stopCommand'];