@loicngr/kobo 1.5.7 → 1.6.1

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

@@ -4,6 +4,10 @@
 
 > [!WARNING]
 > 🚧 **Work in progress** — This project is under active development. Breaking changes may occur at any time.
+> ⚠️ **Planned refactor with potential data loss** — A major refactor is planned and may require database/schema changes that can cause data loss.
+> ❌ **Do not use in production** until this refactor is complete and a stable migration path is documented.
+>
+> **Engine refactor in progress.** The legacy `agent-manager.ts` has been split into an agent engine abstraction (`src/server/services/agent/`) with a pluggable `AgentEngine` contract, a shared `Orchestrator`, and a normalised `AgentEvent` stream. The Claude Code CLI is now one engine among potentially several (`src/server/services/agent/engines/claude-code/`). A runtime migration (`content-migration-service.ts`) converts legacy `ws_events` into the new normalised form on first boot after upgrade; **a timestamped copy of `kobo.db` is written alongside it before the migration runs**, so you can roll back by restoring the backup if anything goes sideways. Expect continued churn until the WebSocket event surface and UI stream reducers stabilise.
 
 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.
 
@@ -90,7 +94,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
@@ -205,22 +211,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.

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,9 +8,11 @@ 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 { 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';
@@ -18,7 +20,8 @@ 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
@@ -70,6 +74,8 @@ app.route('/api/templates', templatesRouter);
 app.route('/api/workspaces', plansRouter);
 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/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 }));
@@ -1225,6 +1249,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', 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);
+        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);
@@ -1385,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);
@@ -1413,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 };
+}

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

@@ -0,0 +1,17 @@
+import { CLAUDE_MODELS } from '../../../../../shared/models.js';
+export const CLAUDE_CODE_CAPABILITIES = {
+    // Models come from the shared catalogue in `src/shared/models.ts` — the
+    // ONE source of truth, consumed both by this file (for /api/engines and
+    // for validation in POST /api/workspaces) and by the frontend selectors.
+    models: CLAUDE_MODELS.map((m) => ({ id: m.id, label: m.label })),
+    effortLevels: [
+        { id: 'auto', label: 'Auto' },
+        { id: 'low', label: 'Low' },
+        { id: 'medium', label: 'Medium' },
+        { id: 'high', label: 'High' },
+    ],
+    permissionModes: ['auto-accept', 'plan'],
+    supportsResume: true,
+    supportsMcp: true,
+    supportsSkills: true,
+};