@loicngr/kobo 1.11.9 → 1.11.10

package/AGENTS.md

@@ -10,7 +10,7 @@ Single-user dev tool, local by default. The server binds `127.0.0.1` unless the
 
 ## Tech stack
 
-**Backend**: Node.js ≥ 20, Hono (HTTP), `ws` (WebSocket), better-sqlite3 (WAL mode), nanoid, `@modelcontextprotocol/sdk`. TypeScript throughout, `tsx` for dev, `tsc` for production build.
+**Backend**: Node.js ≥ 24.15, Hono (HTTP), `ws` (WebSocket), better-sqlite3 (WAL mode), nanoid, `@modelcontextprotocol/sdk`. TypeScript throughout, `tsx` for dev, `tsc` for production build.
 
 **Frontend**: Vue 3, Quasar 2, Pinia, vue-router, marked + dompurify for markdown rendering. Vite via `@quasar/app-vite`, built and served as a Progressive Web App in production.
 
@@ -26,6 +26,7 @@ Single-user dev tool, local by default. The server binds `127.0.0.1` unless the
 # Install
 npm install                         # root
 (cd src/client && npm install)      # client — separate tree
+(cd src/client/src-pwa && npm install) # Quasar PWA build — separate tree
 
 # Develop
 npm run dev                         # backend only (tsx watch on src/server/index.ts)

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to Kōbō are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/). Each release is an `## <version>`
 section — the in-app "What's new" dialog reads this file.
 
+## 1.11.10
+
+- docs: update setup guide
+- fix: improve app reliability
+
 ## 1.11.9
 
 - fix: address 19 bugs found by parallel codebase audit

package/README.md

@@ -21,7 +21,7 @@ Kōbō runs multiple coding agents in parallel, each isolated in its own git wor
 - **Full MCP toolset (`kobo-tasks`)**: a per-workspace MCP server the agent uses for far more than tasks — task/acceptance-criteria CRUD, starting/stopping the dev server and reading its logs, a unified `get_ticket` (Notion or Sentry), searching past conversations across every workspace, per-session token/cost usage, and a `.ai/thoughts` decision log. Native Claude Code Task tools complement it for lightweight sub-agent coordination. See [`AGENTS.md`](./AGENTS.md) for the full tool list.
 
   ![Sub-agents panel showing parallel tool calls](docs/assets/images/sub-agents-panel.png)
-- **Git panel**: a Monaco-based diff viewer with **inline file editing** (edit the right-hand panel directly, save with `Ctrl/Cmd+S`, conflict-guarded via sha precondition), inline conflict resolution, and `Sync` / `Push` / `Commit` / `Open PR` / `Merge ready PR` / `Change PR base` / `Change source branch`. You can write the commit message yourself or ask the active engine to prepare the commit; PR/MR merging always requires a confirmation, then Kōbō can offer to delete the merged remote branch. Edit/Write cards in chat open their exact changed file in the diff viewer. Multi-forge: GitHub (`gh`), GitLab (`glab`), Bitbucket Community (`bkt`), or no forge, auto-detected from the remote and overridable per project.
+- **Git panel**: a Monaco-based diff viewer with **inline file editing** (edit the right-hand panel directly, save with `Ctrl/Cmd+S`, conflict-guarded via sha precondition) and syntax highlighting for PHP, Vue SFCs, JavaScript, TypeScript, and the existing web/config languages. It also provides inline conflict resolution and `Sync` / `Push` / `Commit` / `Open PR` / `Merge ready PR` / `Change PR base` / `Change source branch`. You can write the commit message yourself or ask the active engine to prepare the commit; PR/MR merging always requires a confirmation, then Kōbō can offer to delete the merged remote branch. Edit/Write cards in chat open their exact changed file in the diff viewer. Multi-forge: GitHub (`gh`), GitLab (`glab`), Bitbucket Community (`bkt`), or no forge, auto-detected from the remote and overridable per project.
 
   ![Diff viewer with side-by-side changes](docs/assets/images/diff-viewer.png)
 - **Dev server panel**: start, stop, and tail logs for a workspace's dev server (Docker or npm) straight from the Tools panel — no need to leave the UI. When a project has no configured server, the panel and MCP tool report that explicitly instead of implying one is running.
@@ -41,7 +41,7 @@ Kōbō runs multiple coding agents in parallel, each isolated in its own git wor
 
 ## Quick start
 
-Requires Node.js ≥ 20 and a logged-in Claude Code **or** Codex CLI.
+Requires Node.js ≥ 24.15 and a logged-in Claude Code **or** Codex CLI.
 
 ```bash
 npx @loicngr/kobo@latest

package/dist/server/db/migrations.js

@@ -461,6 +461,136 @@ export const migrations = [
       `);
         },
     },
+    {
+        version: 34,
+        name: 'add-session-event-metrics',
+        migrate: (db) => {
+            const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((row) => row.name));
+            if (!tables.has('workspaces') || !tables.has('agent_sessions') || !tables.has('ws_events'))
+                return;
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS session_event_metrics (
+          workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+          session_id TEXT NOT NULL REFERENCES agent_sessions(id) ON DELETE CASCADE,
+          tool_calls INTEGER NOT NULL DEFAULT 0,
+          errors INTEGER NOT NULL DEFAULT 0,
+          input_tokens INTEGER NOT NULL DEFAULT 0,
+          output_tokens INTEGER NOT NULL DEFAULT 0,
+          PRIMARY KEY (workspace_id, session_id)
+        );
+        CREATE INDEX IF NOT EXISTS idx_ws_events_workspace_type_session
+          ON ws_events(workspace_id, type, session_id, created_at);
+        CREATE INDEX IF NOT EXISTS idx_ws_events_type_created
+          ON ws_events(type, created_at DESC, id DESC);
+
+        CREATE TRIGGER IF NOT EXISTS trg_ws_events_metrics_insert
+        AFTER INSERT ON ws_events
+        WHEN NEW.type = 'agent:event'
+          AND NEW.session_id IS NOT NULL
+          AND json_valid(NEW.payload)
+          AND EXISTS (
+            SELECT 1 FROM agent_sessions
+            WHERE id = NEW.session_id AND workspace_id = NEW.workspace_id
+          )
+        BEGIN
+          INSERT INTO session_event_metrics (
+            workspace_id, session_id, tool_calls, errors, input_tokens, output_tokens
+          ) VALUES (
+            NEW.workspace_id,
+            NEW.session_id,
+            CASE WHEN json_extract(NEW.payload, '$.kind') = 'tool:call' THEN 1 ELSE 0 END,
+            CASE
+              WHEN json_extract(NEW.payload, '$.kind') = 'error'
+                OR (json_extract(NEW.payload, '$.kind') = 'tool:result'
+                  AND json_extract(NEW.payload, '$.isError') = 1)
+              THEN 1 ELSE 0
+            END,
+            CASE
+              WHEN json_extract(NEW.payload, '$.kind') = 'usage'
+                AND json_type(NEW.payload, '$.inputTokens') IN ('integer', 'real')
+              THEN CAST(json_extract(NEW.payload, '$.inputTokens') AS INTEGER) ELSE 0
+            END,
+            CASE
+              WHEN json_extract(NEW.payload, '$.kind') = 'usage'
+                AND json_type(NEW.payload, '$.outputTokens') IN ('integer', 'real')
+              THEN CAST(json_extract(NEW.payload, '$.outputTokens') AS INTEGER) ELSE 0
+            END
+          )
+          ON CONFLICT(workspace_id, session_id) DO UPDATE SET
+            tool_calls = tool_calls + excluded.tool_calls,
+            errors = errors + excluded.errors,
+            input_tokens = MAX(input_tokens, excluded.input_tokens),
+            output_tokens = MAX(output_tokens, excluded.output_tokens);
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS trg_ws_events_metrics_delete
+        AFTER DELETE ON ws_events
+        WHEN OLD.type = 'agent:event' AND OLD.session_id IS NOT NULL
+        BEGIN
+          DELETE FROM session_event_metrics
+          WHERE workspace_id = OLD.workspace_id AND session_id = OLD.session_id;
+
+          INSERT INTO session_event_metrics (
+            workspace_id, session_id, tool_calls, errors, input_tokens, output_tokens
+          )
+          SELECT
+            e.workspace_id,
+            e.session_id,
+            SUM(CASE WHEN json_extract(e.payload, '$.kind') = 'tool:call' THEN 1 ELSE 0 END),
+            SUM(CASE
+              WHEN json_extract(e.payload, '$.kind') = 'error'
+                OR (json_extract(e.payload, '$.kind') = 'tool:result'
+                  AND json_extract(e.payload, '$.isError') = 1)
+              THEN 1 ELSE 0
+            END),
+            MAX(CASE
+              WHEN json_extract(e.payload, '$.kind') = 'usage'
+                AND json_type(e.payload, '$.inputTokens') IN ('integer', 'real')
+              THEN CAST(json_extract(e.payload, '$.inputTokens') AS INTEGER) ELSE 0
+            END),
+            MAX(CASE
+              WHEN json_extract(e.payload, '$.kind') = 'usage'
+                AND json_type(e.payload, '$.outputTokens') IN ('integer', 'real')
+              THEN CAST(json_extract(e.payload, '$.outputTokens') AS INTEGER) ELSE 0
+            END)
+          FROM ws_events e
+          JOIN agent_sessions s ON s.id = e.session_id AND s.workspace_id = e.workspace_id
+          WHERE e.workspace_id = OLD.workspace_id
+            AND e.session_id = OLD.session_id
+            AND e.type = 'agent:event'
+            AND json_valid(e.payload)
+          GROUP BY e.workspace_id, e.session_id;
+        END;
+
+        INSERT INTO session_event_metrics (
+          workspace_id, session_id, tool_calls, errors, input_tokens, output_tokens
+        )
+        SELECT
+          e.workspace_id,
+          e.session_id,
+          SUM(CASE WHEN json_extract(e.payload, '$.kind') = 'tool:call' THEN 1 ELSE 0 END),
+          SUM(CASE
+            WHEN json_extract(e.payload, '$.kind') = 'error'
+              OR (json_extract(e.payload, '$.kind') = 'tool:result'
+                AND json_extract(e.payload, '$.isError') = 1)
+            THEN 1 ELSE 0
+          END),
+          MAX(CASE WHEN json_extract(e.payload, '$.kind') = 'usage'
+            THEN COALESCE(CAST(json_extract(e.payload, '$.inputTokens') AS INTEGER), 0) ELSE 0 END),
+          MAX(CASE WHEN json_extract(e.payload, '$.kind') = 'usage'
+            THEN COALESCE(CAST(json_extract(e.payload, '$.outputTokens') AS INTEGER), 0) ELSE 0 END)
+        FROM ws_events e
+        JOIN agent_sessions s ON s.id = e.session_id AND s.workspace_id = e.workspace_id
+        WHERE e.type = 'agent:event' AND e.session_id IS NOT NULL AND json_valid(e.payload)
+        GROUP BY e.workspace_id, e.session_id
+        ON CONFLICT(workspace_id, session_id) DO UPDATE SET
+          tool_calls = excluded.tool_calls,
+          errors = excluded.errors,
+          input_tokens = excluded.input_tokens,
+          output_tokens = excluded.output_tokens;
+      `);
+        },
+    },
 ];
 /** Current schema version — always equals the highest migration version. */
 export const SCHEMA_VERSION = migrations.length > 0 ? migrations[migrations.length - 1].version : 1;
@@ -479,37 +609,43 @@ export function runMigrations(db) {
     if (hasLegacy) {
         const legacyRow = db.prepare('SELECT version FROM schema_version LIMIT 1').get();
         const legacyVersion = legacyRow?.version ?? 0;
-        // Back-fill history for all migrations that were already applied under the old system.
-        if (legacyVersion >= 1) {
-            const now = new Date().toISOString();
-            // Version 1 = initSchema (always applied if legacyVersion >= 1)
-            db.prepare('INSERT OR IGNORE INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?)').run(1, 'init-schema', now);
-            for (const m of migrations) {
-                if (m.version <= legacyVersion) {
-                    db.prepare('INSERT OR IGNORE INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?)').run(m.version, m.name, now);
+        db.transaction(() => {
+            // Back-fill history for all migrations that were already applied under the old system.
+            if (legacyVersion >= 1) {
+                const now = new Date().toISOString();
+                // Version 1 = initSchema (always applied if legacyVersion >= 1)
+                db.prepare('INSERT OR IGNORE INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?)').run(1, 'init-schema', now);
+                for (const m of migrations) {
+                    if (m.version <= legacyVersion) {
+                        db.prepare('INSERT OR IGNORE INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?)').run(m.version, m.name, now);
+                    }
                 }
             }
-        }
-        db.exec('DROP TABLE schema_version');
+            db.exec('DROP TABLE schema_version');
+        })();
     }
     // ── Determine current state ────────────────────────────────────────────────
     const applied = new Set(db.prepare('SELECT version FROM schema_migrations').all().map((r) => r.version));
     // Fresh install — no migrations applied yet.
     if (!applied.has(1)) {
-        initSchema(db);
-        const now = new Date().toISOString();
-        db.prepare('INSERT INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?)').run(1, 'init-schema', now);
-        // Mark all incremental migrations as applied (initSchema creates the latest shape).
-        for (const m of migrations) {
-            db.prepare('INSERT INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?)').run(m.version, m.name, now);
-        }
+        db.transaction(() => {
+            initSchema(db);
+            const now = new Date().toISOString();
+            db.prepare('INSERT INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?)').run(1, 'init-schema', now);
+            // Mark all incremental migrations as applied (initSchema creates the latest shape).
+            for (const m of migrations) {
+                db.prepare('INSERT INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?)').run(m.version, m.name, now);
+            }
+        })();
         return;
     }
     // Apply pending migrations sequentially.
     for (const m of migrations) {
         if (!applied.has(m.version)) {
-            m.migrate(db);
-            db.prepare('INSERT INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?)').run(m.version, m.name, new Date().toISOString());
+            db.transaction(() => {
+                m.migrate(db);
+                db.prepare('INSERT INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?)').run(m.version, m.name, new Date().toISOString());
+            })();
         }
     }
     // Soft downgrade guard: if the database carries a migration version this

package/dist/server/db/schema.js

@@ -74,6 +74,95 @@ export function initSchema(db) {
       created_at TEXT NOT NULL
     );
 
+    CREATE TABLE IF NOT EXISTS session_event_metrics (
+      workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+      session_id TEXT NOT NULL REFERENCES agent_sessions(id) ON DELETE CASCADE,
+      tool_calls INTEGER NOT NULL DEFAULT 0,
+      errors INTEGER NOT NULL DEFAULT 0,
+      input_tokens INTEGER NOT NULL DEFAULT 0,
+      output_tokens INTEGER NOT NULL DEFAULT 0,
+      PRIMARY KEY (workspace_id, session_id)
+    );
+
+    CREATE TRIGGER IF NOT EXISTS trg_ws_events_metrics_insert
+    AFTER INSERT ON ws_events
+    WHEN NEW.type = 'agent:event'
+      AND NEW.session_id IS NOT NULL
+      AND json_valid(NEW.payload)
+      AND EXISTS (
+        SELECT 1 FROM agent_sessions
+        WHERE id = NEW.session_id AND workspace_id = NEW.workspace_id
+      )
+    BEGIN
+      INSERT INTO session_event_metrics (
+        workspace_id, session_id, tool_calls, errors, input_tokens, output_tokens
+      ) VALUES (
+        NEW.workspace_id,
+        NEW.session_id,
+        CASE WHEN json_extract(NEW.payload, '$.kind') = 'tool:call' THEN 1 ELSE 0 END,
+        CASE
+          WHEN json_extract(NEW.payload, '$.kind') = 'error'
+            OR (json_extract(NEW.payload, '$.kind') = 'tool:result'
+              AND json_extract(NEW.payload, '$.isError') = 1)
+          THEN 1 ELSE 0
+        END,
+        CASE
+          WHEN json_extract(NEW.payload, '$.kind') = 'usage'
+            AND json_type(NEW.payload, '$.inputTokens') IN ('integer', 'real')
+          THEN CAST(json_extract(NEW.payload, '$.inputTokens') AS INTEGER) ELSE 0
+        END,
+        CASE
+          WHEN json_extract(NEW.payload, '$.kind') = 'usage'
+            AND json_type(NEW.payload, '$.outputTokens') IN ('integer', 'real')
+          THEN CAST(json_extract(NEW.payload, '$.outputTokens') AS INTEGER) ELSE 0
+        END
+      )
+      ON CONFLICT(workspace_id, session_id) DO UPDATE SET
+        tool_calls = tool_calls + excluded.tool_calls,
+        errors = errors + excluded.errors,
+        input_tokens = MAX(input_tokens, excluded.input_tokens),
+        output_tokens = MAX(output_tokens, excluded.output_tokens);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS trg_ws_events_metrics_delete
+    AFTER DELETE ON ws_events
+    WHEN OLD.type = 'agent:event' AND OLD.session_id IS NOT NULL
+    BEGIN
+      DELETE FROM session_event_metrics
+      WHERE workspace_id = OLD.workspace_id AND session_id = OLD.session_id;
+
+      INSERT INTO session_event_metrics (
+        workspace_id, session_id, tool_calls, errors, input_tokens, output_tokens
+      )
+      SELECT
+        e.workspace_id,
+        e.session_id,
+        SUM(CASE WHEN json_extract(e.payload, '$.kind') = 'tool:call' THEN 1 ELSE 0 END),
+        SUM(CASE
+          WHEN json_extract(e.payload, '$.kind') = 'error'
+            OR (json_extract(e.payload, '$.kind') = 'tool:result'
+              AND json_extract(e.payload, '$.isError') = 1)
+          THEN 1 ELSE 0
+        END),
+        MAX(CASE
+          WHEN json_extract(e.payload, '$.kind') = 'usage'
+            AND json_type(e.payload, '$.inputTokens') IN ('integer', 'real')
+          THEN CAST(json_extract(e.payload, '$.inputTokens') AS INTEGER) ELSE 0
+        END),
+        MAX(CASE
+          WHEN json_extract(e.payload, '$.kind') = 'usage'
+            AND json_type(e.payload, '$.outputTokens') IN ('integer', 'real')
+          THEN CAST(json_extract(e.payload, '$.outputTokens') AS INTEGER) ELSE 0
+        END)
+      FROM ws_events e
+      JOIN agent_sessions s ON s.id = e.session_id AND s.workspace_id = e.workspace_id
+      WHERE e.workspace_id = OLD.workspace_id
+        AND e.session_id = OLD.session_id
+        AND e.type = 'agent:event'
+        AND json_valid(e.payload)
+      GROUP BY e.workspace_id, e.session_id;
+    END;
+
     CREATE TABLE IF NOT EXISTS workspace_permission_rules (
       id TEXT PRIMARY KEY,
       workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
@@ -140,6 +229,10 @@ export function initSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_tasks_workspace_id ON tasks(workspace_id);
     CREATE INDEX IF NOT EXISTS idx_agent_sessions_workspace_id ON agent_sessions(workspace_id);
     CREATE INDEX IF NOT EXISTS idx_ws_events_workspace_id ON ws_events(workspace_id);
+    CREATE INDEX IF NOT EXISTS idx_ws_events_workspace_type_session
+      ON ws_events(workspace_id, type, session_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_ws_events_type_created
+      ON ws_events(type, created_at DESC, id DESC);
     CREATE INDEX IF NOT EXISTS idx_workspace_chat_history_workspace_id_id
       ON workspace_chat_history(workspace_id, id DESC);
   `);

package/dist/server/index.js

@@ -406,12 +406,9 @@ setMessageHandler(async (type, payload) => {
         }
     }
     if (type === 'devserver:stop' && p?.workspaceId) {
-        try {
-            stopDevServer(p.workspaceId);
-        }
-        catch (err) {
+        void stopDevServer(p.workspaceId).catch((err) => {
             console.error('[ws] Failed to stop dev-server:', err);
-        }
+        });
     }
 });
 // Handle WebSocket upgrade requests on /ws path
@@ -451,16 +448,22 @@ server.on('upgrade', (request, socket, head) => {
 });
 // Graceful shutdown handler
 let isShuttingDown = false;
-function gracefulShutdown(signal) {
+async function gracefulShutdown(signal) {
     if (isShuttingDown)
         return;
     isShuttingDown = true;
     console.log(`\n[kobo] Received ${signal}, shutting down gracefully…`);
-    // Stop accepting new connections
-    wss.close(() => {
-        console.log('[kobo] WebSocket server closed');
-    });
-    terminalWss.close();
+    const forceExitTimer = setTimeout(() => {
+        console.error('[kobo] Graceful shutdown timed out; forcing exit');
+        process.exit(1);
+    }, 5_000);
+    forceExitTimer.unref();
+    // Ask WebSocket clients to leave so their upgraded HTTP connections do not
+    // keep server.close() waiting indefinitely.
+    for (const client of wss.clients)
+        client.close(1001, 'Server shutting down');
+    for (const client of terminalWss.clients)
+        client.close(1001, 'Server shutting down');
     try {
         destroyAllTerminals();
         console.log('[kobo] Terminals killed');
@@ -468,9 +471,6 @@ function gracefulShutdown(signal) {
     catch {
         // Best-effort
     }
-    server.close(() => {
-        console.log('[kobo] HTTP server closed');
-    });
     // Stop background services
     try {
         stopWatchdog();
@@ -498,19 +498,28 @@ function gracefulShutdown(signal) {
     catch {
         // Best-effort
     }
-    // Close database
+    // Stop accepting new HTTP/WS work, then let in-flight handlers finish before
+    // closing SQLite. Closing the DB earlier makes those handlers fail midway.
     try {
-        closeDb();
-        console.log('[kobo] Database closed');
+        await Promise.all([
+            new Promise((resolve) => server.close(() => resolve())),
+            new Promise((resolve) => wss.close(() => resolve())),
+            new Promise((resolve) => terminalWss.close(() => resolve())),
+        ]);
+        console.log('[kobo] HTTP and WebSocket servers closed');
     }
-    catch {
-        // Best-effort
+    finally {
+        try {
+            closeDb();
+            console.log('[kobo] Database closed');
+        }
+        catch {
+            // Best-effort
+        }
     }
-    // Give a short grace period for in-flight requests, then exit
-    setTimeout(() => {
-        console.log('[kobo] Shutdown complete');
-        process.exit(0);
-    }, 2000).unref();
+    clearTimeout(forceExitTimer);
+    console.log('[kobo] Shutdown complete');
+    process.exit(0);
 }
-process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
-process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+process.on('SIGTERM', () => void gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => void gracefulShutdown('SIGINT'));

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

@@ -6,7 +6,7 @@ import { getWorkspace } from '../services/workspace-service.js';
 /** Hono sub-router for per-workspace dev server lifecycle (start, stop, status, logs). */
 const app = new Hono();
 // GET /api/dev-server/:workspaceId/status
-app.get('/:workspaceId/status', (c) => {
+app.get('/:workspaceId/status', async (c) => {
     try {
         const workspaceId = c.req.param('workspaceId');
         const workspace = getWorkspace(workspaceId);
@@ -26,7 +26,7 @@ app.get('/:workspaceId/status', (c) => {
                 containers: [],
             });
         }
-        const status = getStatus(workspace.projectPath, workspace.workingBranch, workspaceId);
+        const status = await 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;
@@ -56,14 +56,14 @@ app.post('/:workspaceId/start', migrationGuard, (c) => {
     }
 });
 // POST /api/dev-server/:workspaceId/stop
-app.post('/:workspaceId/stop', migrationGuard, (c) => {
+app.post('/:workspaceId/stop', migrationGuard, async (c) => {
     try {
         const workspaceId = c.req.param('workspaceId');
         const workspace = getWorkspace(workspaceId);
         if (!workspace) {
             return c.json({ error: `Workspace '${workspaceId}' not found` }, 404);
         }
-        const status = stopDevServer(workspaceId);
+        const status = await stopDevServer(workspaceId);
         return c.json(status);
     }
     catch (err) {
@@ -72,15 +72,16 @@ app.post('/:workspaceId/stop', migrationGuard, (c) => {
     }
 });
 // GET /api/dev-server/:workspaceId/logs
-app.get('/:workspaceId/logs', (c) => {
+app.get('/:workspaceId/logs', async (c) => {
     try {
         const workspaceId = c.req.param('workspaceId');
         const workspace = getWorkspace(workspaceId);
         if (!workspace) {
             return c.json({ error: `Workspace '${workspaceId}' not found` }, 404);
         }
-        const tail = parseInt(c.req.query('tail') ?? '200', 10);
-        const logs = getDevServerLogs(workspaceId, tail);
+        const parsedTail = parseInt(c.req.query('tail') ?? '200', 10);
+        const tail = Math.max(1, Math.min(Number.isFinite(parsedTail) ? parsedTail : 200, 1000));
+        const logs = await getDevServerLogs(workspaceId, tail);
         return c.json({ logs });
     }
     catch (err) {

package/dist/server/routes/documents.js

@@ -1,7 +1,8 @@
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { Hono } from 'hono';
 import * as workspaceService from '../services/workspace-service.js';
+import { isPathInside, resolveExistingPathInside } from '../utils/safe-path.js';
 /** Hono sub-router for workspace document browsing (read-only). */
 const app = new Hono();
 /**
@@ -17,6 +18,7 @@ const DOCUMENT_DIRS = ['docs/plans', 'docs/superpowers', '.ai/thoughts'];
 const MD_EXT = '.md';
 /** Depth cap to keep recursion bounded even on pathological symlink loops. */
 const MAX_DEPTH = 8;
+const MAX_DOCUMENT_SIZE = 1024 * 1024;
 function walkMarkdownFiles(rootAbs, rootRel, out, depth = 0) {
     if (depth > MAX_DEPTH)
         return;
@@ -34,11 +36,13 @@ function walkMarkdownFiles(rootAbs, rootRel, out, depth = 0) {
         const relEntry = `${rootRel}/${entry}`;
         let stat;
         try {
-            stat = statSync(absEntry);
+            stat = lstatSync(absEntry);
         }
         catch {
             continue;
         }
+        if (stat.isSymbolicLink())
+            continue;
         if (stat.isDirectory()) {
             walkMarkdownFiles(absEntry, relEntry, out, depth + 1);
         }
@@ -65,6 +69,15 @@ app.get('/:id/documents', (c) => {
             const absDir = path.join(worktreePath, dir);
             if (!existsSync(absDir))
                 continue;
+            const dirStat = lstatSync(absDir);
+            if (dirStat.isSymbolicLink() || !dirStat.isDirectory())
+                continue;
+            try {
+                resolveExistingPathInside(worktreePath, absDir);
+            }
+            catch {
+                continue;
+            }
             walkMarkdownFiles(absDir, dir, documents);
         }
         // Sort by modifiedAt descending (most recent first)
@@ -102,7 +115,24 @@ app.get('/:id/document', (c) => {
         if (!existsSync(absPath)) {
             return c.json({ error: `Document not found: ${normalized}` }, 404);
         }
-        const content = readFileSync(absPath, 'utf-8');
+        const fileStat = lstatSync(absPath);
+        if (fileStat.isSymbolicLink())
+            return c.json({ error: 'Symbolic links are not allowed' }, 400);
+        if (!fileStat.isFile())
+            return c.json({ error: `Document not found: ${normalized}` }, 404);
+        const realWorktree = realpathSync(worktreePath);
+        const realFile = resolveExistingPathInside(worktreePath, absPath);
+        const allowed = DOCUMENT_DIRS.some((dir) => {
+            const allowedRoot = path.join(worktreePath, dir);
+            if (!existsSync(allowedRoot) || lstatSync(allowedRoot).isSymbolicLink())
+                return false;
+            return isPathInside(realpathSync(allowedRoot), realFile);
+        });
+        if (!isPathInside(realWorktree, realFile) || !allowed)
+            return c.json({ error: 'Path escapes allowed root' }, 400);
+        if (fileStat.size > MAX_DOCUMENT_SIZE)
+            return c.json({ error: 'Document exceeds the 1 MB size limit' }, 413);
+        const content = readFileSync(realFile, 'utf-8');
         return c.json({ content, path: normalized });
     }
     catch (err) {

package/dist/server/routes/health.js

@@ -1,5 +1,6 @@
-import { spawnSync } from 'node:child_process';
+import { execFile as execFileCb } from 'node:child_process';
 import fs from 'node:fs';
+import { promisify } from 'node:util';
 import { Hono } from 'hono';
 import { getDb } from '../db/index.js';
 import { SCHEMA_VERSION } from '../db/migrations.js';
@@ -9,24 +10,22 @@ import { getDbPath, getKoboHome, getPackageVersion } from '../utils/paths.js';
 import { slugifyProjectName } from '../utils/project-slug.js';
 import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 const app = new Hono();
-function checkClaudeCli() {
+const execFileAsync = promisify(execFileCb);
+async function checkCli(binary) {
     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 };
+        const { stdout } = await execFileAsync(binary, ['--version'], { encoding: 'utf-8', timeout: 2_000 });
+        return { available: true, version: stdout.trim() || null };
     }
     catch {
         return { available: false, version: null };
     }
 }
-function checkCodexCli() {
+function checkClaudeCli() {
+    return checkCli('claude');
+}
+async function checkCodexCli() {
     try {
-        const bin = resolveCodexBinary();
-        const r = spawnSync(bin, ['--version'], { encoding: 'utf-8' });
-        if (r.error || r.status !== 0)
-            return { available: false, version: null };
-        return { available: true, version: (r.stdout ?? '').trim() || null };
+        return await checkCli(resolveCodexBinary());
     }
     catch {
         return { available: false, version: null };
@@ -50,10 +49,11 @@ function safeFileSize(p) {
     }
 }
 // GET /api/health/report — detailed health diagnostics for the Health panel.
-app.get('/report', (c) => {
+app.get('/report', async (c) => {
     const db = getDb();
     const dbPath = getDbPath();
     const home = getKoboHome();
+    const cliChecks = Promise.all([checkClaudeCli(), checkCodexCli()]);
     // DB schema version
     const row = db.prepare('SELECT MAX(version) as v FROM schema_migrations').get();
     const dbSchemaVersion = row?.v ?? 0;
@@ -145,6 +145,7 @@ app.get('/report', (c) => {
         .all();
     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 [claudeCli, codexCli] = await cliChecks;
     const report = {
         version: getPackageVersion(),
         koboHome: home,
@@ -155,8 +156,8 @@ app.get('/report', (c) => {
             currentSchemaVersion: SCHEMA_VERSION,
         },
         settings: { schemaVersion: SETTINGS_SCHEMA_VERSION },
-        claudeCli: checkClaudeCli(),
-        codexCli: checkCodexCli(),
+        claudeCli,
+        codexCli,
         workspaces: {
             total: settingsRow.n,
             archived: archivedRow.n,