@loicngr/kobo 1.6.0 → 1.6.2

package/AGENTS.md

@@ -58,7 +58,12 @@ src/
 │   │   └── migrations.ts           # incremental migrations, bumped per feature
 │   ├── services/                   # business logic — pure functions over db + external processes
 │   │   ├── workspace-service.ts    # workspaces + tasks + agent_sessions CRUD
-│   │   ├── agent-manager.ts        # spawns Claude Code CLI, streams stdout, tracks sessions, interrupt/stop
+│   │   ├── agent/                  # agent engine abstraction (replaces former agent-manager.ts)
+│   │   │   ├── orchestrator.ts     # per-workspace engine map, retry/quota handling, watchdog, public API
+│   │   │   ├── session-controller.ts # lifecycle wrapper around an AgentEngine instance
+│   │   │   ├── event-router.ts     # maps engine AgentEvent stream to WS emit + DB side-effects
+│   │   │   └── engines/claude-code/ # Claude Code engine (spawn + stream-parser + args-builder + mcp-config + capabilities)
+│   │   ├── content-migration-service.ts # runtime legacy ws_events → normalised AgentEvent migration
 │   │   ├── templates-service.ts    # prompt templates CRUD (JSON file persistence, seeding)
 │   │   ├── dev-server-service.ts   # per-workspace dev server lifecycle (docker or npm process)
 │   │   ├── websocket-service.ts    # emit / emitEphemeral to subscribed clients

package/README.md

@@ -2,10 +2,8 @@
 
 > **Kōbō** (工房) — Japanese for *workshop*. A multi-workspace agent manager for [Claude Code](https://claude.com/claude-code).
 
-> [!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.
+> [!NOTE]
+> 🚧 **Active development** — breaking changes may still land on `develop`. The database layer ships with forward-only migrations and a timestamped pre-migration backup of `kobo.db` before any schema change, so upgrades preserve your data even across invasive refactors.
 
 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.
 
@@ -14,25 +12,31 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 ## Features
 
 - **Isolated git worktrees** — every workspace runs on its own branch in its own directory, so concurrent Claude sessions never step on each other
-- **Live agent output** — stream `stdout`/`stderr` from Claude Code to the browser via WebSocket, with persisted event replay on reconnect
+- **Pluggable agent engine** — Kōbō talks to agents through an `AgentEngine` contract with a normalised `AgentEvent` stream (`src/server/services/agent/engines/`). Claude Code is the first engine; dropping in another runtime (e.g. the Claude Agent SDK) only requires a new adapter, not a rewrite of the UI or orchestration layer
+- **Rich chat feed** — live streaming text, thinking blocks, inline tool calls with expandable diffs for Edit/Write, per-turn session cards, markdown rendering, jump-to-previous-user-message button, and infinite scroll-up over persisted history
 - **Task & acceptance criteria tracking** — the agent reports progress through a dedicated MCP server (`kobo-tasks`) that reads and updates tasks directly from the SQLite database
+- **Documents panel** — tree view in the right drawer that surfaces every AI-generated markdown file under `docs/plans/`, `docs/superpowers/`, and `.ai/thoughts/`. Paths mentioned in chat messages are auto-detected against the catalogue and become one-click deep-links into the panel
+- **Git panel with inline diff viewer** — Monaco-powered side-by-side / inline diff of the working branch against its source, with file tree (same q-tree as Documents), inline rebase/merge conflict resolution, and a clean action bar: `Sync` split-button (pull / rebase / merge), `Push`, `Diff`, `Create PR`
 - **Notion integration** — pull workspace missions straight from Notion pages, extract markdown, and use it as the source of truth for acceptance criteria
 - **Sentry integration** — paste a Sentry issue URL to spin up a dedicated "fix workspace" with the stacktrace, tags, and offending spans written to `.ai/thoughts/SENTRY-<id>.md`; the agent is primed with a TDD fix workflow and has access to the Sentry MCP tools for deeper digging
 - **Per-workspace dev servers** — start/stop Docker or Node dev servers scoped to each branch, with log streaming
 - **Conventional-commit enforcement** — project-level git conventions are written to `.ai/.git-conventions.md` inside every workspace so Claude follows them during commits
-- **Pull request automation** — one-click `push`, `pull`, and `open-pr` endpoints integrate with the GitHub CLI, using a configurable prompt template
+- **Pull request automation** — one-click `push`, `pull`, `open-pr`, and "change PR base" endpoints integrate with the GitHub CLI, using a configurable prompt template
 - **Multi-session support** — create multiple Claude agent sessions per workspace, each with its own chat history; resume completed sessions via `--resume`; sessions are named and persisted in localStorage
 - **Prompt templates** — personal library of reusable prompts with variable substitution (`{working_branch}`, `{commit_count}`, etc.), insertable from the chat input via `/` autocomplete; editable in Settings > Templates
-- **Plan browser** — read-only viewer for markdown plan files produced by agents, rendered directly in the right-side panel
+- **Favorites and tags** — pin workspaces to the top via right-click favourite, organise with per-workspace tags filterable from the sidebar; a global tag catalogue keeps colours consistent across workspaces
+- **Health panel + config export/import** — inspect backend health (agent sessions, migration state, dev servers, DB size) and roundtrip your Kōbō config (settings, templates, skills) between machines via JSON
+- **Usage tracking** — rolling input/output token counts and cost estimates per workspace, aggregated across sessions and live-updated from `usage` events
+- **Resizable right drawer** — drag-to-resize horizontally and vertically, with tab state and split ratio persisted to localStorage
 - **Soft interrupt** — pause an agent mid-execution (SIGINT, like pressing Escape in Claude Code) without killing the process; the agent stops the current tool and waits for the next message
 - **Archive instead of delete** — soft-remove workspaces without losing the worktree, branches, or history; unarchive restores the exact pre-archive state
 
 ## Tech stack
 
 - **Backend** — Node.js ≥ 20, [Hono](https://hono.dev/), [better-sqlite3](https://github.com/WiseLibs/better-sqlite3), [ws](https://github.com/websockets/ws), [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk)
-- **Frontend** — [Vue 3](https://vuejs.org/), [Quasar 2](https://quasar.dev/), [Pinia](https://pinia.vuejs.org/), `vue-router`
+- **Frontend** — [Vue 3](https://vuejs.org/), [Quasar 2](https://quasar.dev/), [Pinia](https://pinia.vuejs.org/), `vue-router`, [Monaco Editor](https://microsoft.github.io/monaco-editor/) (git diff viewer), `marked` + `dompurify` (markdown rendering)
 - **Tooling** — TypeScript, [Vitest](https://vitest.dev/), [Biome](https://biomejs.dev/) (lint + format), `tsx` for dev
-- **Storage** — single SQLite file (`~/.config/kobo/kobo.db` by default, overridable via `KOBO_HOME`) with WAL mode
+- **Storage** — single SQLite file (`~/.config/kobo/kobo.db` by default, overridable via `KOBO_HOME`) with WAL mode and forward-only migrations
 
 ## Quick start
 
@@ -49,7 +53,7 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 ### Run via `npx` (recommended)
 
 ```bash
-PORT=9999 npx @loicngr/kobo@latest
+SERVER_PORT=9998 PORT=9999 npx @loicngr/kobo@latest
 ```
 
 That's it. npm downloads the package, installs dependencies, starts the Kōbō server on the port you specified, and serves the web UI at `http://localhost:9999`. Data is persisted to `~/.config/kobo/` (overridable via `KOBO_HOME`).
@@ -92,7 +96,9 @@ npm start           # runs the compiled server
 ### Test & lint
 
 ```bash
-npm test            # full vitest suite (366+ tests)
+npm test            # backend vitest suite (740+ tests)
+npm run test:client # client vitest suite (Pinia stores + pure utils, 85+ tests)
+npm run test:all    # backend + client suites
 npm run lint        # biome check (lint + format verification)
 npm run lint:fix    # biome check with safe auto-fixes
 npm run format      # biome format --write
@@ -207,22 +213,31 @@ Then start a new workspace in Kōbō — the agent will pick up the skills autom
 
 ```
 src/
-├── server/                         # Hono backend
-│   ├── index.ts                    # app bootstrap + WS upgrade
-│   ├── db/                         # SQLite schema and singleton
-│   ├── services/                   # business logic (workspace, agent, dev-server, ws, notion, settings, pr-template)
-│   ├── routes/                     # Hono handlers
-│   └── utils/                      # git-ops, process-tracker
-├── client/                         # Vue 3 + Quasar SPA
+├── server/                                 # Hono backend
+│   ├── index.ts                            # app bootstrap + WS upgrade
+│   ├── db/                                 # SQLite schema, migrations, singleton
+│   ├── services/
+│   │   ├── agent/                          # agent engine abstraction (replaces agent-manager.ts)
+│   │   │   ├── orchestrator.ts             # per-workspace engine map, retry/quota, watchdog, public API
+│   │   │   ├── session-controller.ts       # lifecycle wrapper around one AgentEngine instance
+│   │   │   ├── event-router.ts             # maps engine AgentEvent stream to WS emit + DB side-effects
+│   │   │   └── engines/claude-code/        # spawn + NDJSON stream-parser + args-builder + mcp-config + capabilities
+│   │   ├── content-migration-service.ts    # legacy ws_events → normalised AgentEvent rows, with DB backup
+│   │   └── …                               # workspace, dev-server, ws, notion, sentry, settings, pr-template
+│   ├── routes/                             # Hono handlers (workspaces, engines, migration, templates, …)
+│   └── utils/                              # git-ops, process-tracker, paths
+├── shared/                                 # modules shared by backend and frontend (e.g. model catalogue)
+├── client/                                 # Vue 3 + Quasar SPA
 │   └── src/
-│       ├── stores/                 # Pinia state management
-│       ├── components/             # WorkspaceList, NotionPanel, ChatInput, GitPanel, …
-│       ├── pages/                  # WorkspacePage, CreatePage, SettingsPage
+│       ├── stores/                         # Pinia: workspace, websocket, agent-stream, migration, settings, …
+│       ├── components/                     # ActivityFeed, TurnCard, WorkspaceList, ChatInput, GitPanel, …
+│       ├── services/                       # agent-event-view (foldEvents), conversation-turns (groupIntoTurns), inline-diff
+│       ├── pages/                          # WorkspacePage, CreatePage, SettingsPage
 │       └── router/
-├── mcp-server/                     # Standalone MCP server spawned per workspace
-│   ├── kobo-tasks-server.ts        # entry point, registers list_tasks & mark_task_done
-│   └── kobo-tasks-handlers.ts      # pure handlers over SQLite
-└── __tests__/                      # Vitest suite
+├── mcp-server/                             # standalone MCP server spawned per workspace
+│   ├── kobo-tasks-server.ts                # entry point, registers list_tasks & mark_task_done
+│   └── kobo-tasks-handlers.ts              # pure handlers over SQLite
+└── __tests__/                              # Vitest suite (engines, orchestrator, migration, routes, …)
 ```
 
 See [`AGENTS.md`](./AGENTS.md) for a deeper dive into conventions, data model, WebSocket protocol, and contribution guidelines.
@@ -231,10 +246,10 @@ See [`AGENTS.md`](./AGENTS.md) for a deeper dive into conventions, data model, W
 
 | Table | Purpose |
 |---|---|
-| `workspaces` | the unit of work — branch, status, Notion link, model, `archived_at`, … |
+| `workspaces` | the unit of work — branch, status, model, engine, `archived_at`, `favorited_at`, `tags`, Notion link, … |
 | `tasks` | workspace sub-items — tasks and acceptance criteria |
-| `agent_sessions` | Claude Code CLI invocations — `claude_session_id`, pid, lifecycle |
-| `ws_events` | persisted WebSocket events for replay on reconnect |
+| `agent_sessions` | agent runs — pid, `engine_session_id`, lifecycle |
+| `ws_events` | persisted WebSocket events (chat history, `agent:event` stream, user messages) for replay on reconnect |
 
 ## MCP server
 
@@ -261,7 +276,6 @@ This is a personal tool, but PRs and issues are welcome. Before submitting:
 1. Read [`AGENTS.md`](./AGENTS.md) — it covers the commit rules, branching model, and code conventions
 2. Run `npm run lint`, `npx tsc --noEmit`, and `npm test` locally
 3. Base your branch on `develop` (not `main`); PRs target `develop`
-4. **Do not add `Co-Authored-By` trailers** in commits, even for AI-assisted work
 
 CI runs lint + type check + tests on every PR to `develop`.
 

package/dist/server/db/index.js

@@ -1,9 +1,17 @@
+import os from 'node:os';
+import path from 'node:path';
 import Database from 'better-sqlite3';
 import { ensureKoboHome, getDbPath } from '../utils/paths.js';
 let instance = null;
 /**
  * Return the singleton SQLite database connection, creating it on first call.
  * Configures WAL mode, busy timeout, and foreign keys.
+ *
+ * Safety guard: when running under vitest, refuse to open any DB located
+ * under the user's real home directory. If the caller didn't pass a
+ * custom path AND KOBO_HOME wasn't pinned to a temp dir, the vitest
+ * global setup is misconfigured — better to fail loudly than to silently
+ * mutate production data.
  */
 export function getDb(dbPath) {
     if (instance)
@@ -13,6 +21,15 @@ export function getDb(dbPath) {
         ensureKoboHome();
         resolvedPath = getDbPath();
     }
+    if (process.env.VITEST) {
+        const home = os.homedir();
+        const resolved = path.resolve(resolvedPath);
+        if (resolved.startsWith(home) && !resolved.startsWith(path.resolve(os.tmpdir()))) {
+            throw new Error(`[kobo-db] Refusing to open production DB under a user home directory while VITEST is active: ${resolved}. ` +
+                `This is a safety guard against tests leaking into the developer's ~/.config/kobo/. ` +
+                `Ensure vitest.setup.ts sets KOBO_HOME to a tmp directory, or pass an explicit dbPath to getDb().`);
+        }
+    }
     instance = new Database(resolvedPath);
     instance.pragma('journal_mode=WAL');
     instance.pragma('busy_timeout=5000');

package/dist/server/db/migrations.js

@@ -78,6 +78,16 @@ export const migrations = [
             db.prepare("ALTER TABLE workspaces ADD COLUMN tags TEXT NOT NULL DEFAULT '[]'").run();
         },
     },
+    {
+        version: 10,
+        name: 'agent-engine-abstraction',
+        migrate: (db) => {
+            db.transaction(() => {
+                db.prepare("ALTER TABLE workspaces ADD COLUMN engine TEXT NOT NULL DEFAULT 'claude-code'").run();
+                db.prepare('ALTER TABLE agent_sessions RENAME COLUMN claude_session_id TO engine_session_id').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

@@ -18,6 +18,7 @@ export function initSchema(db) {
       archived_at TEXT,
       favorited_at TEXT,
       tags TEXT NOT NULL DEFAULT '[]',
+      engine TEXT NOT NULL DEFAULT 'claude-code',
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL
     );
@@ -37,7 +38,7 @@ export function initSchema(db) {
       id TEXT PRIMARY KEY,
       workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
       pid INTEGER,
-      claude_session_id TEXT,
+      engine_session_id TEXT,
       status TEXT NOT NULL DEFAULT 'running',
       started_at TEXT NOT NULL,
       ended_at TEXT,

package/dist/server/index.js

@@ -8,17 +8,20 @@ import WebSocket, { WebSocketServer } from 'ws';
 import { closeDb, getDb } from './db/index.js';
 import { runMigrations } from './db/migrations.js';
 import devServerRouter from './routes/dev-server.js';
+import documentsRouter from './routes/documents.js';
+import { enginesRouter } from './routes/engines.js';
 import gitRouter from './routes/git.js';
 import healthRouter from './routes/health.js';
 import imagesRouter from './routes/images.js';
+import { migrationRouter } from './routes/migration.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 { getAvailableSkills, reconcileOrphanSessions, sendMessage, setBackendPort, startAgent, startWatchdog, stopAgent, stopWatchdog, } from './services/agent/orchestrator.js';
+import { runContentMigrationIfNeeded } from './services/content-migration-service.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';
@@ -52,6 +55,7 @@ void createDailyDbBackupIfNeeded(db, getDbPath()).then((r) => {
 });
 // Initialize process cleanup, agent watchdog, and PR watcher
 initProcessCleanup();
+reconcileOrphanSessions();
 startWatchdog();
 startPrWatcher();
 // Create Hono app
@@ -67,9 +71,11 @@ app.route('/api/git', gitRouter);
 app.route('/api/settings', settingsRouter);
 app.route('/api/dev-server', devServerRouter);
 app.route('/api/templates', templatesRouter);
-app.route('/api/workspaces', plansRouter);
+app.route('/api/workspaces', documentsRouter);
 app.route('/api/search', searchRouter);
 app.route('/api/health', healthRouter);
+app.route('/api/engines', enginesRouter);
+app.route('/api/migration', migrationRouter);
 // Skills endpoint
 app.get('/api/skills', (c) => c.json(getAvailableSkills()));
 const PORT = parseInt(process.env.SERVER_PORT || process.env.PORT || '3000', 10);
@@ -120,6 +126,13 @@ const server = serve({
 }, (info) => {
     setBackendPort(info.port);
     console.log(`Server running at http://localhost:${info.port}`);
+    // Content migration runs AFTER the HTTP listener is up so the frontend
+    // can observe progress via WS broadcasts + GET /api/migration/status.
+    // Not awaited — the callback returns quickly, the migration runs in the
+    // background.
+    void runContentMigrationIfNeeded(getDb(), getDbPath()).catch((err) => {
+        console.error('[boot] content migration failed:', err);
+    });
 });
 // Create WebSocketServer attached to the HTTP server
 const wss = new WebSocketServer({ noServer: true });
@@ -212,7 +225,7 @@ terminalWss.on('connection', (ws, workspaceId) => {
         }
     });
 });
-// Wire websocket-service message handler to agent-manager
+// Wire websocket-service message handler to the agent orchestrator
 setMessageHandler((type, payload) => {
     const p = payload;
     if (type === 'chat:message' && p?.workspaceId && p?.content) {
@@ -226,7 +239,15 @@ setMessageHandler((type, payload) => {
         try {
             sendMessage(p.workspaceId, p.content);
         }
-        catch {
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // Only resume on the specific "No agent running" path. Other errors
+            // (stdin closed, process dead mid-write, etc.) should surface to the
+            // logs instead of silently respawning a fresh agent.
+            if (!msg.includes('No agent running')) {
+                console.error(`[ws] chat:message failed for workspace ${p.workspaceId}:`, err);
+                return;
+            }
             // Agent not running — resume the session hinted by the client if any,
             // otherwise the most-recent active session.
             try {

package/dist/server/middleware/migration-guard.js

@@ -0,0 +1,15 @@
+import { getContentMigrationStatus } from '../services/content-migration-service.js';
+/**
+ * Blocks mutating requests while the content migration is running.
+ *
+ * Returns 503 with `{ error: 'migration-in-progress' }` whenever the migration
+ * state is anything other than `idle` or `done`. Mounted per-handler on routes
+ * that write to `ws_events` or spawn agents so the user can still observe
+ * progress through GETs and `/api/migration/status` while the migration runs.
+ */
+export const migrationGuard = async (c, next) => {
+    const state = getContentMigrationStatus().state;
+    if (state === 'idle' || state === 'done')
+        return next();
+    return c.json({ error: 'migration-in-progress' }, 503);
+};

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

@@ -1,4 +1,5 @@
 import { Hono } from 'hono';
+import { migrationGuard } from '../middleware/migration-guard.js';
 import { getDevServerLogs, getStatus, startDevServer, stopDevServer } from '../services/dev-server-service.js';
 import { getWorkspace } from '../services/workspace-service.js';
 /** Hono sub-router for per-workspace dev server lifecycle (start, stop, status, logs). */
@@ -24,7 +25,7 @@ app.get('/:workspaceId/status', (c) => {
     }
 });
 // POST /api/dev-server/:workspaceId/start
-app.post('/:workspaceId/start', (c) => {
+app.post('/:workspaceId/start', migrationGuard, (c) => {
     try {
         const workspaceId = c.req.param('workspaceId');
         const workspace = getWorkspace(workspaceId);
@@ -40,7 +41,7 @@ app.post('/:workspaceId/start', (c) => {
     }
 });
 // POST /api/dev-server/:workspaceId/stop
-app.post('/:workspaceId/stop', (c) => {
+app.post('/:workspaceId/stop', migrationGuard, (c) => {
     try {
         const workspaceId = c.req.param('workspaceId');
         const workspace = getWorkspace(workspaceId);

package/dist/server/routes/documents.js

@@ -0,0 +1,113 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { Hono } from 'hono';
+import * as workspaceService from '../services/workspace-service.js';
+/** Hono sub-router for workspace document browsing (read-only). */
+const app = new Hono();
+/**
+ * Directories (relative to the worktree root) where AI-generated documents
+ * may live. Scanned recursively — any `.md` file found below one of these
+ * roots is surfaced in the documents panel.
+ *
+ * Kept intentionally narrow to avoid leaking unrelated project docs
+ * (README, product specs, …) into the panel.
+ */
+const DOCUMENT_DIRS = ['docs/plans', 'docs/superpowers', '.ai/thoughts'];
+/** Only .md files are listed. */
+const MD_EXT = '.md';
+/** Depth cap to keep recursion bounded even on pathological symlink loops. */
+const MAX_DEPTH = 8;
+function walkMarkdownFiles(rootAbs, rootRel, out, depth = 0) {
+    if (depth > MAX_DEPTH)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(rootAbs);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.startsWith('.') && entry !== '.ai')
+            continue; // skip hidden except `.ai`
+        const absEntry = path.join(rootAbs, entry);
+        const relEntry = `${rootRel}/${entry}`;
+        let stat;
+        try {
+            stat = statSync(absEntry);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            walkMarkdownFiles(absEntry, relEntry, out, depth + 1);
+        }
+        else if (stat.isFile() && entry.endsWith(MD_EXT)) {
+            out.push({
+                path: relEntry,
+                name: entry,
+                modifiedAt: stat.mtime.toISOString(),
+            });
+        }
+    }
+}
+// GET /:id/documents — list every .md file under DOCUMENT_DIRS in the workspace worktree
+app.get('/:id/documents', (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 documents = [];
+        for (const dir of DOCUMENT_DIRS) {
+            const absDir = path.join(worktreePath, dir);
+            if (!existsSync(absDir))
+                continue;
+            walkMarkdownFiles(absDir, dir, documents);
+        }
+        // Sort by modifiedAt descending (most recent first)
+        documents.sort((a, b) => new Date(b.modifiedAt).getTime() - new Date(a.modifiedAt).getTime());
+        return c.json({ documents });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+// GET /:id/document?path=<relative> — read a single document
+app.get('/:id/document', (c) => {
+    try {
+        const id = c.req.param('id');
+        const filePath = c.req.query('path');
+        if (!filePath) {
+            return c.json({ error: 'Missing path query parameter' }, 400);
+        }
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace) {
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        }
+        // Security: normalize the path and verify it stays within allowed roots.
+        const normalized = path.normalize(filePath);
+        if (normalized.includes('..') ||
+            !DOCUMENT_DIRS.some((dir) => normalized.startsWith(`${dir}/`) || normalized === dir)) {
+            return c.json({ error: `Invalid path: must be under ${DOCUMENT_DIRS.map((d) => `${d}/`).join(', ')}` }, 400);
+        }
+        if (!normalized.endsWith(MD_EXT)) {
+            return c.json({ error: 'Only .md files can be read' }, 400);
+        }
+        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const absPath = path.join(worktreePath, normalized);
+        if (!existsSync(absPath)) {
+            return c.json({ error: `Document not found: ${normalized}` }, 404);
+        }
+        const content = readFileSync(absPath, 'utf-8');
+        return c.json({ content, path: normalized });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+export default app;

package/dist/server/routes/engines.js

@@ -0,0 +1,9 @@
+import { Hono } from 'hono';
+import { listEngines } from '../services/agent/engines/registry.js';
+/** Hono sub-router exposing `GET /` — the list of registered agent engines with capabilities. */
+export const enginesRouter = new Hono();
+enginesRouter.get('/', (c) => c.json(listEngines().map((e) => ({
+    id: e.id,
+    displayName: e.displayName,
+    capabilities: e.capabilities,
+}))));

package/dist/server/routes/migration.js

@@ -0,0 +1,5 @@
+import { Hono } from 'hono';
+import { getContentMigrationStatus } from '../services/content-migration-service.js';
+/** Hono sub-router exposing `GET /status` for the runtime content migration. */
+export const migrationRouter = new Hono();
+migrationRouter.get('/status', (c) => c.json(getContentMigrationStatus()));

package/dist/server/routes/workspaces.js

@@ -5,7 +5,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Hono } from 'hono';
 import { getDb } from '../db/index.js';
-import * as agentManager from '../services/agent-manager.js';
+import { migrationGuard } from '../middleware/migration-guard.js';
+import { listEngines } from '../services/agent/engines/registry.js';
+import * as agentManager from '../services/agent/orchestrator.js';
 import * as devServerService from '../services/dev-server-service.js';
 import * as notionService from '../services/notion-service.js';
 import { renderPrTemplate } from '../services/pr-template-service.js';
@@ -32,12 +34,21 @@ app.get('/', (c) => {
     }
 });
 // POST /api/workspaces — create workspace
-app.post('/', async (c) => {
+app.post('/', migrationGuard, async (c) => {
     try {
         const body = await c.req.json();
         if (!body.name || !body.projectPath || !body.sourceBranch || !body.workingBranch) {
             return c.json({ error: 'Missing required fields: name, projectPath, sourceBranch, workingBranch' }, 400);
         }
+        // Validate the engine id (if provided) against the registry. An unknown
+        // engine is rejected up-front so we don't create orphan workspaces that
+        // can't spawn an agent.
+        if (body.engine) {
+            const validEngineIds = listEngines().map((e) => e.id);
+            if (!validEngineIds.includes(body.engine)) {
+                return c.json({ error: `Unknown engine '${body.engine}'. Valid engines: ${validEngineIds.join(', ')}` }, 400);
+            }
+        }
         // Fetch the source branch from origin first — if this fails, block creation
         // immediately (no DB records created, user stays on the create page).
         try {
@@ -61,6 +72,7 @@ app.post('/', async (c) => {
             model: body.model,
             reasoningEffort: body.reasoningEffort,
             permissionMode: body.permissionMode || globalSettings.defaultPermissionMode || 'plan',
+            engine: body.engine,
         });
         let notionContent = null;
         let sentryContent = null;
@@ -446,7 +458,7 @@ app.post('/', async (c) => {
     }
 });
 // POST /api/workspaces/:id/sessions — create a new idle agent session
-app.post('/:id/sessions', (c) => {
+app.post('/:id/sessions', migrationGuard, (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
@@ -803,7 +815,7 @@ app.put('/:id/tags', async (c) => {
     }
 });
 // PATCH /api/workspaces/:id — update workspace fields (status, model, permissionMode, name)
-app.patch('/:id', async (c) => {
+app.patch('/:id', migrationGuard, async (c) => {
     try {
         const id = c.req.param('id');
         const body = await c.req.json();
@@ -930,7 +942,7 @@ app.post('/:id/run-setup-script', async (c) => {
     }
 });
 // POST /api/workspaces/:id/archive — mark workspace as archived (soft-delete)
-app.post('/:id/archive', (c) => {
+app.post('/:id/archive', migrationGuard, (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
@@ -969,7 +981,7 @@ app.post('/:id/archive', (c) => {
     }
 });
 // POST /api/workspaces/:id/unarchive — restore an archived workspace
-app.post('/:id/unarchive', (c) => {
+app.post('/:id/unarchive', migrationGuard, (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
@@ -989,7 +1001,7 @@ app.post('/:id/unarchive', (c) => {
     }
 });
 // DELETE /api/workspaces/:id — delete workspace
-app.delete('/:id', async (c) => {
+app.delete('/:id', migrationGuard, async (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
@@ -1053,13 +1065,25 @@ app.delete('/:id', async (c) => {
     }
 });
 // POST /api/workspaces/:id/start — start/restart agent
-app.post('/:id/start', async (c) => {
+app.post('/:id/start', migrationGuard, 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);
         }
+        // If the workspace declares an engine, ensure it is still registered.
+        // Otherwise startAgent() would throw from deep inside resolveEngine and
+        // surface as an opaque 500 — better to fail fast with a clear 400.
+        const workspaceEngine = workspace.engine;
+        if (workspaceEngine) {
+            const validEngineIds = listEngines().map((e) => e.id);
+            if (!validEngineIds.includes(workspaceEngine)) {
+                return c.json({
+                    error: `Workspace uses engine '${workspaceEngine}' which is no longer available. Recreate or reconfigure the workspace.`,
+                }, 400);
+            }
+        }
         const body = await c.req
             .json()
             .catch(() => ({ prompt: undefined, agentSessionId: undefined, resume: undefined }));
@@ -1269,7 +1293,7 @@ app.post('/:id/git/abort', (c) => {
     }
 });
 /** Hand off merge/rebase conflicts to the workspace agent with an intelligent-resolution prompt. */
-app.post('/:id/git/resolve-with-agent', async (c) => {
+app.post('/:id/git/resolve-with-agent', migrationGuard, async (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
@@ -1489,7 +1513,7 @@ app.post('/:id/mark-read', (c) => {
     }
 });
 // POST /api/workspaces/:id/stop — stop agent
-app.post('/:id/stop', (c) => {
+app.post('/:id/stop', migrationGuard, (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
@@ -1517,7 +1541,7 @@ app.post('/:id/stop', (c) => {
     }
 });
 // POST /api/workspaces/:id/interrupt — soft-interrupt agent (SIGINT, like Escape in Claude Code)
-app.post('/:id/interrupt', (c) => {
+app.post('/:id/interrupt', migrationGuard, (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);

package/dist/server/services/agent/engines/claude-code/args-builder.js

@@ -0,0 +1,22 @@
+export function buildClaudeArgs(input) {
+    const args = ['--output-format', 'stream-json', '--verbose'];
+    if (input.skipPermissions)
+        args.push('--dangerously-skip-permissions');
+    let prompt = input.prompt;
+    if (input.permissionMode === 'plan') {
+        prompt = `[PLAN MODE] You are in PLAN/READ-ONLY mode. You MUST NOT create, edit, write, or delete any files. Only use read-only tools (Read, Grep, Glob, LS, Bash for read-only commands). Analyze the codebase, plan your approach, and present your findings — but do NOT execute any changes.\n\n${prompt}`;
+    }
+    if (input.model && input.model !== 'auto')
+        args.push('--model', input.model);
+    if (input.effort && input.effort !== 'auto')
+        args.push('--effort', input.effort);
+    if (input.mcpConfigPath)
+        args.push('--mcp-config', input.mcpConfigPath);
+    if (input.resumeFromEngineSessionId) {
+        args.push('--resume', input.resumeFromEngineSessionId, '-p', prompt);
+    }
+    else {
+        args.push('-p', prompt);
+    }
+    return { args, effectivePrompt: prompt };
+}