@loicngr/kobo 1.5.6 → 1.6.0

package/README.md

@@ -4,6 +4,8 @@
 
 > [!WARNING]
 > 🚧 **Work in progress** — This project is under active development. Breaking changes may occur at any time.
+>
+> **Engine refactor planned.** Kōbō currently drives the `claude` CLI via `spawn(..., ['-p', ...])` and parses stdout, which is brittle on edge cases (interrupts, long-running sessions, MCP lifecycle, tool-use streaming). A rewrite is planned to use the [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents-and-tools/claude-agent-sdk/overview) directly so the agent runs in-process, with proper streaming primitives, structured tool-use events, and cleaner interrupt / resume semantics. Expect churn in `src/server/services/agent-manager.ts` and the WebSocket event shape during that migration.
 
 Kōbō lets you delegate multiple coding missions to Claude Code agents in parallel. Each workspace lives in its own isolated git worktree with its own branch, its own Claude session, optionally its own dev server, and a custom MCP tools server the agent uses to track progress. A Vue 3 dashboard shows live agent output, tasks, acceptance criteria, and git state across every workspace.
 

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 {
@@ -1179,6 +1225,110 @@ app.post('/:id/rebase', (c) => {
         gitOps.rebaseBranch(worktreePath, workspace.sourceBranch);
         return c.json({ success: true });
     }
+    catch (err) {
+        if (err instanceof gitOps.GitConflictError) {
+            return c.json({ error: err.message, conflict: true, operation: err.operation, files: err.files }, 409);
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+/** Merge the source branch into the workspace branch (non-fast-forward). */
+app.post('/:id/merge', (c) => {
+    try {
+        const id = c.req.param('id');
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace)
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        gitOps.mergeBranch(worktreePath, workspace.sourceBranch);
+        return c.json({ success: true });
+    }
+    catch (err) {
+        if (err instanceof gitOps.GitConflictError) {
+            return c.json({ error: err.message, conflict: true, operation: err.operation, files: err.files }, 409);
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+/** Abort any in-progress merge or rebase in the worktree. */
+app.post('/:id/git/abort', (c) => {
+    try {
+        const id = c.req.param('id');
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace)
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const aborted = gitOps.abortOngoingGitOperation(worktreePath);
+        return c.json({ success: true, aborted });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+/** Hand off merge/rebase conflicts to the workspace agent with an intelligent-resolution prompt. */
+app.post('/:id/git/resolve-with-agent', async (c) => {
+    try {
+        const id = c.req.param('id');
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace)
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        const body = (await c.req.json().catch(() => ({})));
+        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const operation = body.operation ?? gitOps.getOngoingGitOperation(worktreePath) ?? 'merge';
+        const files = body.files && body.files.length > 0 ? body.files : gitOps.getConflictedFiles(worktreePath);
+        if (files.length === 0) {
+            return c.json({ error: 'No conflicted files detected — nothing for the agent to resolve' }, 400);
+        }
+        const fileList = files.map((f) => `- ${f}`).join('\n');
+        const continueCmd = operation === 'merge' ? 'git merge --continue' : 'git rebase --continue';
+        const prompt = `I started a \`git ${operation}\` of \`origin/${workspace.sourceBranch}\` into our working branch \`${workspace.workingBranch}\` and it produced conflicts that I need your help to resolve INTELLIGENTLY.
+
+Conflicted files (${files.length}):
+${fileList}
+
+## Resolution rules — read carefully
+
+1. **Our branch is the source of truth for the feature we are building.** Its behavior must be preserved.
+2. **The source branch (\`${workspace.sourceBranch}\`) carries legitimate upstream changes** (bug fixes, refactors, dependency bumps). Integrate these where they don't conflict with our intent.
+3. **Do NOT blindly pick a side.** Neither \`--ours\` nor \`--theirs\` wholesale. Read each conflict hunk and reason about what the correct merged state is.
+4. **Think semantically, not syntactically.** If our branch renamed \`foo\` to \`bar\` and the source branch added a new call to \`foo\`, the correct resolution is a new call to \`bar\`, not "keep ours and drop the new call".
+5. **Preserve tests and contracts.** If both sides touched the same test, keep coverage from both.
+6. **Imports, versions, lock files:** prefer the superset (union) unless they genuinely conflict — in which case use the more recent / more restrictive.
+
+## Steps
+
+1. For each conflicted file, open it and read both conflict markers.
+2. Decide the merge intent. If unsure, investigate both sides' commit history (\`git log --oneline ours..HEAD <file>\` vs \`git log --oneline origin/${workspace.sourceBranch} <file>\`).
+3. Edit the file to the correct merged state and remove the conflict markers.
+4. Run the test suite to verify no regression (\`npm test\` or the project's equivalent).
+5. \`git add <resolved-files>\` then \`${continueCmd}\`.
+6. Report the summary: which files you touched, the key decisions you made, and the final test result.
+
+Start now.`;
+        // Persist the prompt in the chat feed so the user sees what was dispatched.
+        const session = workspaceService.getActiveSession(workspace.id);
+        wsService.emit(workspace.id, 'user:message', { content: prompt, sender: 'user' }, session?.id ?? undefined);
+        let messageSent = false;
+        try {
+            agentManager.sendMessage(workspace.id, prompt);
+            messageSent = true;
+        }
+        catch {
+            try {
+                agentManager.startAgent(workspace.id, worktreePath, prompt, workspace.model, true, workspace.permissionMode, undefined, workspace.reasoningEffort);
+                workspaceService.updateWorkspaceStatus(workspace.id, 'executing');
+                messageSent = true;
+            }
+            catch (resumeErr) {
+                const resumeMsg = resumeErr instanceof Error ? resumeErr.message : String(resumeErr);
+                console.warn(`[workspaces] resolve-with-agent: agent resume failed: ${resumeMsg}`);
+            }
+        }
+        return c.json({ ok: true, operation, files, messageSent });
+    }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return c.json({ error: message }, 500);

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;
+}