@loicngr/kobo 1.6.11 → 1.6.13

package/dist/server/routes/workspaces.js

@@ -1,10 +1,10 @@
-import { execFile as execFileCb, spawn } from 'node:child_process';
+import { execFile as execFileCb, execFileSync, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 const execFileAsync = promisify(execFileCb);
 import fs from 'node:fs';
 import path from 'node:path';
 import { Hono } from 'hono';
-import { AUTO_LOOP_GROOMING_STEPS, AUTO_LOOP_HARD_RULES } from '../../shared/auto-loop-prompts.js';
+import { AUTO_LOOP_HARD_RULES, buildAutoLoopGroomingSteps, PREP_AUTOLOOP_INTRO, } from '../../shared/auto-loop-prompts.js';
 import { getDb } from '../db/index.js';
 import { migrationGuard } from '../middleware/migration-guard.js';
 import { listEngines } from '../services/agent/engines/registry.js';
@@ -41,8 +41,13 @@ app.get('/', (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);
+        // workingBranch is derived from git when worktreePath is provided, so
+        // it's not required in that flow. The other 3 fields stay mandatory.
+        if (!body.name || !body.projectPath || !body.sourceBranch) {
+            return c.json({ error: 'Missing required fields: name, projectPath, sourceBranch' }, 400);
+        }
+        if (!body.worktreePath && !body.workingBranch) {
+            return c.json({ error: 'Missing required field: 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
@@ -62,10 +67,100 @@ app.post('/', migrationGuard, async (c) => {
             const message = err instanceof Error ? err.message : String(err);
             return c.json({ error: message }, 422);
         }
+        // Reuse-existing-worktree path. When the caller passes `worktreePath`,
+        // Kobo "attaches" to a pre-existing worktree on disk instead of creating
+        // a new one. We validate four invariants up-front (path exists, belongs
+        // to this repo, is on a real branch, isn't already attached) and derive
+        // the working branch from git itself — the body.workingBranch is ignored.
+        let useReusedWorktree = false;
+        let reusedDerivedBranch = null;
+        if (body.worktreePath) {
+            if (!fs.existsSync(body.worktreePath)) {
+                return c.json({ error: `Worktree path does not exist: ${body.worktreePath}` }, 422);
+            }
+            try {
+                const commonDir = execFileSync('git', ['-C', body.worktreePath, 'rev-parse', '--git-common-dir'], {
+                    encoding: 'utf-8',
+                }).trim();
+                const expectedCommonDir = path.join(body.projectPath, '.git');
+                if (path.resolve(commonDir) !== path.resolve(expectedCommonDir)) {
+                    return c.json({ error: `Worktree '${body.worktreePath}' belongs to a different repository` }, 422);
+                }
+                const branch = execFileSync('git', ['-C', body.worktreePath, 'rev-parse', '--abbrev-ref', 'HEAD'], {
+                    encoding: 'utf-8',
+                }).trim();
+                if (!branch || branch === 'HEAD') {
+                    return c.json({ error: 'Worktree is in detached HEAD state and cannot be attached' }, 422);
+                }
+                reusedDerivedBranch = branch;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return c.json({ error: `Failed to inspect worktree: ${message}` }, 422);
+            }
+            // Validate the worktree isn't already attached to another workspace.
+            const dbForCheck = getDb();
+            const existing = dbForCheck.prepare('SELECT id FROM workspaces WHERE worktree_path = ?').get(body.worktreePath);
+            if (existing) {
+                return c.json({ error: 'This worktree is already attached to another Kōbō workspace' }, 422);
+            }
+            useReusedWorktree = true;
+        }
+        // Pre-flight: extract Notion / Sentry before any DB write. A throw here
+        // must not leave a half-built workspace behind, so we run extraction
+        // before createWorkspace and surface failures as 422.
+        let notionContent = null;
+        if (body.notionUrl) {
+            try {
+                notionContent = await notionService.extractNotionPage(body.notionUrl);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return c.json({ error: `Failed to extract Notion page: ${message}` }, 422);
+            }
+        }
+        let sentryContent = null;
+        if (body.sentryUrl) {
+            try {
+                sentryContent = await sentryService.extractSentryIssue(body.sentryUrl);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return c.json({ error: `Failed to extract Sentry issue: ${message}` }, 422);
+            }
+        }
         // Create workspace record
         const globalSettings = settingsService.getGlobalSettings();
-        // workingBranch may be updated after Notion extraction to inject the ticket ID
-        let workingBranch = body.workingBranch;
+        // workingBranch may be updated after Notion extraction to inject the ticket ID,
+        // OR overridden by the branch derived from the existing worktree (reuse mode).
+        let workingBranch = useReusedWorktree && reusedDerivedBranch ? reusedDerivedBranch : body.workingBranch;
+        // Inject ticket ID into the working branch BEFORE creating the workspace,
+        // so the worktree_path recorded in the DB reflects the FINAL branch name.
+        // Works with or without Notion: ticket ID comes from Notion extraction first,
+        // then Sentry, then falls back to a TK-XXXX pattern anywhere in the body.name.
+        // Skip when reusing an existing worktree — its branch is already real on disk
+        // and we MUST NOT rename it.
+        if (!useReusedWorktree) {
+            // Sentry's canonical identifier is the issue short-ID (e.g. "ACME-API-3"),
+            // which is what Sentry auto-close recognises in commit messages.
+            const detectedTicketId = notionContent?.ticketId || sentryContent?.issueId || body.name.match(/[A-Z]+-\d+/i)?.[0];
+            if (detectedTicketId && !workingBranch.toLowerCase().includes(detectedTicketId.toLowerCase())) {
+                const ticketPrefix = detectedTicketId.toUpperCase();
+                const slashIdx = workingBranch.indexOf('/');
+                const typePrefix = slashIdx >= 0 ? workingBranch.slice(0, slashIdx + 1) : 'feature/';
+                // Use Notion/Sentry title or body name for the slug — all have proper accented
+                // characters that NFD normalization can transliterate (é→e, ç→c, etc.)
+                const titleSource = notionContent?.title || sentryContent?.title || body.name;
+                const titleSlug = titleSource
+                    .normalize('NFD')
+                    .replace(/[\u0300-\u036f]/g, '')
+                    .toLowerCase()
+                    .replace(/[^a-z0-9]+/g, '-')
+                    .replace(/^-|-$/g, '')
+                    .substring(0, 50);
+                workingBranch = `${typePrefix}${ticketPrefix}--${titleSlug}`;
+            }
+        }
         let workspace = workspaceService.createWorkspace({
             name: body.name,
             projectPath: body.projectPath,
@@ -73,13 +168,13 @@ app.post('/', migrationGuard, async (c) => {
             workingBranch,
             notionUrl: body.notionUrl,
             notionPageId: body.notionPageId,
+            sentryUrl: body.sentryUrl,
+            ...(useReusedWorktree ? { worktreePath: body.worktreePath, worktreeOwned: false } : {}),
             model: body.model,
             reasoningEffort: body.reasoningEffort,
             permissionMode: body.permissionMode || globalSettings.defaultPermissionMode || 'plan',
             engine: body.engine,
         });
-        let notionContent = null;
-        let sentryContent = null;
         // Auto-tag the workspace based on its creation source — `notion` when
         // imported from a Notion page, `sentry` when bootstrapped from a Sentry
         // issue URL. Pre-seeded in the global tag catalogue via migration v9.
@@ -101,29 +196,6 @@ app.post('/', migrationGuard, async (c) => {
                 console.error('[workspaces] Failed to apply auto tags:', err);
             }
         }
-        // Extract Notion page content if a URL was provided
-        if (body.notionUrl) {
-            workspaceService.updateWorkspaceStatus(workspace.id, 'extracting');
-            try {
-                notionContent = await notionService.extractNotionPage(body.notionUrl);
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                console.error(`[workspaces] Failed to extract Notion page: ${message}`);
-            }
-        }
-        // Extract Sentry issue content if a URL was provided. Done early (before
-        // worktree creation) so the issue ID can be injected into the branch name.
-        if (body.sentryUrl) {
-            workspaceService.updateWorkspaceStatus(workspace.id, 'extracting');
-            try {
-                sentryContent = await sentryService.extractSentryIssue(body.sentryUrl);
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                console.error(`[workspaces] Failed to extract Sentry issue: ${message}`);
-            }
-        }
         // Update workspace name with Sentry issue title if the user did not provide
         // a custom name and Notion hasn't already filled it.
         if (sentryContent?.title && !notionContent?.title && workspace.name === 'workspace') {
@@ -177,41 +249,21 @@ app.post('/', migrationGuard, async (c) => {
                 }
             }
         }
-        // Inject ticket ID into the working branch.
-        // Works with or without Notion: ticket ID comes from Notion extraction first,
-        // then falls back to a TK-XXXX pattern anywhere in the workspace name.
-        // The worktree has not been created yet, so a DB update is sufficient.
-        {
-            // Sentry's canonical identifier is the issue short-ID (e.g. "ACME-API-3"),
-            // which is what Sentry auto-close recognises in commit messages.
-            const detectedTicketId = notionContent?.ticketId || sentryContent?.issueId || workspace.name.match(/[A-Z]+-\d+/i)?.[0];
-            if (detectedTicketId && !workingBranch.toLowerCase().includes(detectedTicketId.toLowerCase())) {
-                const ticketPrefix = detectedTicketId.toUpperCase();
-                const slashIdx = workingBranch.indexOf('/');
-                const typePrefix = slashIdx >= 0 ? workingBranch.slice(0, slashIdx + 1) : 'feature/';
-                // Use Notion/Sentry title or workspace name for the slug — all have proper accented
-                // characters that NFD normalization can transliterate (é→e, ç→c, etc.)
-                const titleSource = notionContent?.title || sentryContent?.title || workspace.name;
-                const titleSlug = titleSource
-                    .normalize('NFD')
-                    .replace(/[\u0300-\u036f]/g, '')
-                    .toLowerCase()
-                    .replace(/[^a-z0-9]+/g, '-')
-                    .replace(/^-|-$/g, '')
-                    .substring(0, 50);
-                workingBranch = `${typePrefix}${ticketPrefix}--${titleSlug}`;
-                workspace = workspaceService.updateWorkingBranch(workspace.id, workingBranch);
-            }
-        }
-        // Create git worktree for the working branch
+        // Create git worktree for the working branch — unless we're reusing an
+        // existing one, in which case the path is taken straight from the body.
         let worktreePath;
-        try {
-            worktreePath = worktreeService.createWorktree(body.projectPath, workingBranch, body.sourceBranch);
+        if (useReusedWorktree) {
+            worktreePath = body.worktreePath;
         }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            workspaceService.updateWorkspaceStatus(workspace.id, 'error');
-            return c.json({ error: `Failed to create worktree: ${message}` }, 500);
+        else {
+            try {
+                worktreePath = worktreeService.createWorktree(body.projectPath, workingBranch, body.sourceBranch);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                workspaceService.updateWorkspaceStatus(workspace.id, 'error');
+                return c.json({ error: `Failed to create worktree: ${message}` }, 500);
+            }
         }
         // Ensure Kobo-generated files are gitignored. Check both the root
         // .gitignore and .ai/.gitignore to avoid duplicate entries.
@@ -260,7 +312,10 @@ app.post('/', migrationGuard, async (c) => {
         }
         // Run setup script if configured and not skipped
         let setupScriptFailed = false;
-        if (effectiveSettings.setupScript && !body.skipSetupScript) {
+        // Skip the setup script when reusing an existing worktree — the user
+        // already has the environment set up there and rerunning it could be
+        // destructive (drop a node_modules they curated, etc.).
+        if (effectiveSettings.setupScript && !body.skipSetupScript && !useReusedWorktree) {
             workspaceService.updateWorkspaceStatus(workspace.id, 'extracting');
             wsService.emit(workspace.id, 'setup:output', { text: '[kobo] Running setup script...' });
             try {
@@ -460,12 +515,20 @@ app.post('/', migrationGuard, async (c) => {
                 // NOT with implementation. The auto-loop will drive implementation after.
                 // The grooming steps + hard rules are shared with the PREP_AUTOLOOP_PROMPT
                 // sent by the "Prepare for auto-loop" button (src/shared/auto-loop-prompts.ts).
+                // Read per-project E2E settings so the grooming steps can include the
+                // E2E review pass when configured. We deliberately use
+                // `getProjectSettings` (NOT `getEffectiveSettings`) here because only
+                // project-level settings carry the `e2e` shape; if the project hasn't
+                // been registered yet, the empty default below is correct.
+                const projectSettingsForE2e = settingsService.getProjectSettings(body.projectPath);
+                const e2eSettings = projectSettingsForE2e?.e2e ?? { framework: '', skill: '', prompt: '' };
                 brainstormPrompt += `\n\nThen brainstorm the implementation approach. Explore the codebase to understand the existing structure. Ask clarifying questions if needed. When you have a clear plan, create a plan file.
 
 Auto-loop mode is active for this workspace. After the plan is ready, DO NOT implement anything. Instead:
 
-${AUTO_LOOP_GROOMING_STEPS}
-5. Output [BRAINSTORM_COMPLETE] on its own line and end your turn cleanly.
+${buildAutoLoopGroomingSteps(e2eSettings)}
+
+When the steps above are complete, output [BRAINSTORM_COMPLETE] on its own line and end your turn cleanly.
 
 ${AUTO_LOOP_HARD_RULES}`;
             }
@@ -688,46 +751,6 @@ app.patch('/:id/sessions/:sessionId', async (c) => {
         return c.json({ error: message }, 500);
     }
 });
-// POST /api/workspaces/:id/refresh-notion — re-extract Notion page and update tasks
-app.post('/:id/refresh-notion', 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 (!workspace.notionUrl)
-            return c.json({ error: 'No Notion URL configured' }, 400);
-        const notionContent = await notionService.extractNotionPage(workspace.notionUrl);
-        // Delete existing tasks and recreate from Notion
-        const db = getDb();
-        db.prepare('DELETE FROM tasks WHERE workspace_id = ?').run(id);
-        let sortOrder = 0;
-        for (const todo of notionContent.todos) {
-            workspaceService.createTask(id, {
-                title: todo.title,
-                isAcceptanceCriterion: false,
-                sortOrder: sortOrder++,
-            });
-        }
-        for (const feature of notionContent.gherkinFeatures) {
-            workspaceService.createTask(id, {
-                title: feature,
-                isAcceptanceCriterion: true,
-                sortOrder: sortOrder++,
-            });
-        }
-        // Update name if it was the default
-        if (notionContent.title && workspace.name === 'workspace') {
-            workspaceService.updateWorkspaceName(id, notionContent.title);
-        }
-        const updated = workspaceService.getWorkspaceWithTasks(id);
-        return c.json(updated);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return c.json({ error: message }, 500);
-    }
-});
 // POST /api/workspaces/:id/tasks — create a new task
 app.post('/:id/tasks', async (c) => {
     try {
@@ -949,6 +972,29 @@ app.get('/archived', (c) => {
         return c.json({ error: message }, 500);
     }
 });
+// GET /:id/prep-autoloop-prompt — compose the project-aware grooming
+// prompt. Used by the "Prepare for auto-loop" button. Place BEFORE
+// `app.get('/:id', ...)` so the more-specific path wins.
+app.get('/:id/prep-autoloop-prompt', (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 projectSettings = settingsService.getProjectSettings(workspace.projectPath);
+        const e2eSettings = projectSettings?.e2e ?? { framework: '', skill: '', prompt: '' };
+        const prompt = `${PREP_AUTOLOOP_INTRO}
+
+${buildAutoLoopGroomingSteps(e2eSettings)}
+
+${AUTO_LOOP_HARD_RULES}`;
+        return c.json({ prompt });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
 // GET /api/workspaces/:id — get workspace details with tasks
 app.get('/:id', (c) => {
     try {
@@ -1079,7 +1125,7 @@ app.post('/:id/open-editor', (c) => {
         if (!globalSettings.editorCommand) {
             return c.json({ error: 'No editor command configured' }, 400);
         }
-        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const worktreePath = workspace.worktreePath;
         if (!fs.existsSync(worktreePath)) {
             return c.json({ error: `Worktree path does not exist: ${worktreePath}` }, 400);
         }
@@ -1087,6 +1133,15 @@ app.post('/:id/open-editor', (c) => {
             detached: true,
             stdio: 'ignore',
         });
+        // spawn errors fire async on the ChildProcess (ENOENT etc.) — without a
+        // handler the unhandled 'error' event crashes the whole Node process.
+        child.on('error', (err) => {
+            console.error(`[open-editor] spawn '${globalSettings.editorCommand}' failed:`, err.message);
+            wsService.emitEphemeral(workspace.id, 'editor:open-failed', {
+                command: globalSettings.editorCommand,
+                message: err.message,
+            });
+        });
         child.unref();
         return c.json({ success: true });
     }
@@ -1118,7 +1173,7 @@ app.post('/:id/run-setup-script', async (c) => {
         if (!effectiveSettings.setupScript) {
             return c.json({ error: 'No setup script configured' }, 400);
         }
-        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const worktreePath = workspace.worktreePath;
         if (!fs.existsSync(worktreePath)) {
             return c.json({ error: `Worktree path does not exist: ${worktreePath}` }, 400);
         }
@@ -1235,20 +1290,25 @@ app.delete('/:id', migrationGuard, async (c) => {
         // Docker leaves root-owned files inside the worktree, git worktree
         // remove fails with EACCES.
         const warnings = [];
-        // Remove worktree
-        const worktreesDir = `${workspace.projectPath}/.worktrees`;
-        const worktreePath = `${worktreesDir}/${workspace.workingBranch}`;
-        try {
-            worktreeService.removeWorktree(workspace.projectPath, worktreePath);
+        // Remove worktree (only if owned — for attached external worktrees we
+        // never created the dir, so we must not delete it on the user's behalf).
+        const worktreePath = workspace.worktreePath;
+        if (workspace.worktreeOwned) {
+            try {
+                worktreeService.removeWorktree(workspace.projectPath, worktreePath);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(`[workspaces] Failed to remove worktree: ${message}`);
+                warnings.push(`Failed to remove worktree directory '${worktreePath}'. The git entry may still reference it. ` +
+                    `Fix manually:\n` +
+                    `  sudo rm -rf '${worktreePath}'\n` +
+                    `  cd '${workspace.projectPath}' && git worktree prune\n` +
+                    `Reason: ${message}`);
+            }
         }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            console.error(`[workspaces] Failed to remove worktree: ${message}`);
-            warnings.push(`Failed to remove worktree directory '${worktreePath}'. The git entry may still reference it. ` +
-                `Fix manually:\n` +
-                `  sudo rm -rf '${worktreePath}'\n` +
-                `  cd '${workspace.projectPath}' && git worktree prune\n` +
-                `Reason: ${message}`);
+        else {
+            console.log(`[workspaces] keeping reused worktree on delete: ${worktreePath}`);
         }
         // Delete local branch if requested
         if (body.deleteLocalBranch) {
@@ -1324,7 +1384,7 @@ app.post('/:id/start', migrationGuard, async (c) => {
         catch {
             // Agent may not be running — ignore
         }
-        const worktreePath = `${workspace.projectPath}/.worktrees/${workspace.workingBranch}`;
+        const worktreePath = workspace.worktreePath;
         const agent = agentManager.startAgent(id, worktreePath, prompt, workspace.model, resume, workspace.permissionMode, agentSessionId, workspace.reasoningEffort);
         workspaceService.updateWorkspaceStatus(id, 'executing');
         // Persist the user prompt so it survives page refresh.
@@ -1348,7 +1408,7 @@ app.get('/:id/git-stats', async (c) => {
         if (!workspace) {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
-        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const worktreePath = workspace.worktreePath;
         const commitCount = gitOps.getCommitCount(worktreePath, workspace.sourceBranch, workspace.workingBranch);
         const diffStats = gitOps.getStructuredDiffStatsBetween(worktreePath, workspace.sourceBranch, workspace.workingBranch);
         const pr = await gitOps.getPrStatusAsync(workspace.projectPath, workspace.workingBranch);
@@ -1383,7 +1443,7 @@ app.get('/:id/diff', (c) => {
         if (!workspace) {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
-        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const worktreePath = workspace.worktreePath;
         const files = mode === 'unpushed'
             ? gitOps.getUnpushedChangedFiles(worktreePath, workspace.workingBranch)
             : gitOps.getChangedFiles(worktreePath, workspace.sourceBranch);
@@ -1417,7 +1477,7 @@ app.get('/:id/diff-file', (c) => {
         if (!workspace) {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
-        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const worktreePath = workspace.worktreePath;
         const baseRef = mode === 'unpushed' ? `origin/${workspace.workingBranch}` : workspace.sourceBranch;
         const original = gitOps.getFileAtRef(worktreePath, baseRef, filePath);
         const modified = gitOps.getFileContent(worktreePath, filePath);
@@ -1440,7 +1500,7 @@ app.get('/:id/commits', (c) => {
         }
         const limitRaw = c.req.query('limit');
         const limit = Math.min(Math.max(1, parseInt(limitRaw ?? '50', 10) || 50), 200);
-        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const worktreePath = workspace.worktreePath;
         const commits = gitOps.listBranchCommits(worktreePath, workspace.sourceBranch, workspace.workingBranch, limit);
         c.header('Cache-Control', 'no-store');
         return c.json({ commits, sourceBranch: workspace.sourceBranch, workingBranch: workspace.workingBranch });
@@ -1470,11 +1530,23 @@ app.post('/:id/rename-branch', async (c) => {
         if (!workspace) {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
+        if (!workspace.worktreeOwned) {
+            return c.json({
+                error: 'Rename is not available for attached external worktrees. Manage the branch name with git directly.',
+            }, 400);
+        }
         if (newName === workspace.workingBranch) {
             return c.json(workspace); // no-op
         }
-        const oldWorktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
-        const newWorktreePath = path.join(workspace.projectPath, '.worktrees', newName);
+        const oldWorktreePath = workspace.worktreePath;
+        // Sibling rename: keep the same worktrees-root, swap the branch leaf.
+        // Cannot use `path.dirname` directly because branches with slashes
+        // (e.g. `feature/x`) make the dirname end one level too deep.
+        const oldSuffix = `/${workspace.workingBranch}`;
+        const worktreesRoot = oldWorktreePath.endsWith(oldSuffix)
+            ? oldWorktreePath.slice(0, -oldSuffix.length)
+            : path.join(workspace.projectPath, '.worktrees');
+        const newWorktreePath = path.join(worktreesRoot, newName);
         // Reject early if the target name is already in use — either as a local
         // branch or on origin. Avoids git's generic "already exists" error and
         // protects against the same silent-fallback trap the create flow has.
@@ -1494,9 +1566,11 @@ app.post('/:id/rename-branch', async (c) => {
         // not the dir, for git operations.
         try {
             gitOps.moveWorktree(workspace.projectPath, oldWorktreePath, newWorktreePath);
+            workspaceService.updateWorktreePath(id, newWorktreePath);
         }
         catch (err) {
             console.error('[workspaces] Failed to move worktree dir (branch renamed anyway):', err);
+            // worktree_path stays at oldWorktreePath, which still exists on disk
         }
         const updated = workspaceService.updateWorkingBranch(id, newName);
         return c.json(updated);
@@ -1517,7 +1591,12 @@ app.post('/:id/resync-branch', (c) => {
         if (!workspace) {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
-        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        if (!workspace.worktreeOwned) {
+            return c.json({
+                error: 'Resync-branch is not available for attached external worktrees.',
+            }, 400);
+        }
+        const worktreePath = workspace.worktreePath;
         let actual;
         try {
             actual = gitOps.getCurrentBranch(worktreePath).trim();
@@ -1531,18 +1610,24 @@ app.post('/:id/resync-branch', (c) => {
             return c.json({ ok: true, changed: false, workingBranch: workspace.workingBranch });
         }
         // Branch was renamed in-place by the agent (`git branch -m ...`). The
-        // worktree directory is still at .worktrees/<old-name>; move it so it
-        // matches the new ref, otherwise Kōbō's path resolver (projectPath +
-        // .worktrees + workingBranch) breaks and subsequent session spawns fail
-        // with ENOENT on .mcp.json. Best-effort: if the move fails (dir already
-        // moved, lockfile, dirty tree), we still update the DB so git ops stay
-        // aligned with the current ref name — the user can repair the dir manually.
-        const newWorktreePath = path.join(workspace.projectPath, '.worktrees', actual);
+        // worktree directory is still at <worktrees-root>/<old-name>; move it so it
+        // matches the new ref, otherwise Kōbō's path resolver breaks and
+        // subsequent session spawns fail with ENOENT on .mcp.json. Best-effort:
+        // if the move fails (dir already moved, lockfile, dirty tree), we still
+        // update the DB so git ops stay aligned with the current ref name — the
+        // user can repair the dir manually.
+        const oldSuffix = `/${workspace.workingBranch}`;
+        const worktreesRoot = worktreePath.endsWith(oldSuffix)
+            ? worktreePath.slice(0, -oldSuffix.length)
+            : path.join(workspace.projectPath, '.worktrees');
+        const newWorktreePath = path.join(worktreesRoot, actual);
         try {
             gitOps.moveWorktree(workspace.projectPath, worktreePath, newWorktreePath);
+            workspaceService.updateWorktreePath(id, newWorktreePath);
         }
         catch (err) {
             console.error('[workspaces] resync-branch: moveWorktree failed (DB update proceeds):', err);
+            // worktree_path stays at the old path; DB update for working branch still proceeds
         }
         const updated = workspaceService.updateWorkingBranch(id, actual);
         return c.json({ ok: true, changed: true, workingBranch: updated.workingBranch });
@@ -1562,7 +1647,7 @@ app.post('/:id/push', async (c) => {
         }
         const body = await c.req.json().catch(() => ({}));
         const force = body?.force === true;
-        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const worktreePath = workspace.worktreePath;
         try {
             // Only pass an options arg when force is requested — keeps the
             // no-options call shape identical to before for callers/tests that
@@ -1596,7 +1681,7 @@ app.post('/:id/pull', (c) => {
         if (!workspace) {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
-        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const worktreePath = workspace.worktreePath;
         try {
             gitOps.pullBranch(worktreePath, workspace.workingBranch);
         }
@@ -1621,7 +1706,7 @@ app.post('/:id/rebase', (c) => {
         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 worktreePath = workspace.worktreePath;
         gitOps.rebaseBranch(worktreePath, workspace.sourceBranch);
         return c.json({ success: true });
     }
@@ -1640,7 +1725,7 @@ app.post('/:id/merge', (c) => {
         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 worktreePath = workspace.worktreePath;
         gitOps.mergeBranch(worktreePath, workspace.sourceBranch);
         return c.json({ success: true });
     }
@@ -1659,7 +1744,7 @@ app.post('/:id/git/abort', (c) => {
         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 worktreePath = workspace.worktreePath;
         const aborted = gitOps.abortOngoingGitOperation(worktreePath);
         return c.json({ success: true, aborted });
     }
@@ -1676,7 +1761,7 @@ app.post('/:id/git/resolve-with-agent', migrationGuard, async (c) => {
         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 worktreePath = workspace.worktreePath;
         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) {
@@ -1747,7 +1832,7 @@ app.post('/:id/change-pr-base', async (c) => {
         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 worktreePath = workspace.worktreePath;
         await execFileAsync('gh', ['pr', 'edit', '--base', body.base], { cwd: worktreePath });
         return c.json({ success: true });
     }
@@ -1764,7 +1849,7 @@ app.post('/:id/open-pr', async (c) => {
         if (!workspace) {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
-        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const worktreePath = workspace.worktreePath;
         // Verify branch exists on remote
         let lsRemoteOut = '';
         try {
@@ -1859,7 +1944,7 @@ app.post('/:id/open-pr', async (c) => {
         catch {
             // Agent not running — resume it with the PR prompt
             try {
-                const worktreePathForResume = `${workspace.projectPath}/.worktrees/${workspace.workingBranch}`;
+                const worktreePathForResume = workspace.worktreePath;
                 agentManager.startAgent(workspace.id, worktreePathForResume, rendered, workspace.model, true, workspace.permissionMode, undefined, workspace.reasoningEffort);
                 workspaceService.updateWorkspaceStatus(workspace.id, 'executing');
                 messageSent = true;

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

@@ -5,6 +5,8 @@
  */
 const KOBO_MCP_BRIEF = [
     '[Kōbō MCP] This workspace exposes a dedicated MCP server with tools prefixed `kobo__`.',
+    "Non-interactive mode: this session runs via `claude -p`. Tools requiring a synchronous human reply (e.g. `AskUserQuestion`) won't complete — never call them. If you need user input, end the turn with a plain-text question; the user replies asynchronously via the chat UI.",
+    'Plan mode: when running with `--permission-mode plan`, the read-only restriction applies to MCP tools too, not just built-ins. For Kōbō: `kobo__list_*`, `kobo__read_document`, `kobo__search_codebase`, `kobo__get_*` are fine; `kobo__mark_task_done`, `kobo__log_thought`, `kobo__set_workspace_status` are mutations and must wait until the plan is approved.',
     'Conventions — read these BEFORE starting work, not as a fallback:',
     '• `kobo__list_tasks` first on any non-trivial turn, then `kobo__mark_task_done` as each item completes.',
     '• `kobo__list_documents` / `kobo__read_document` to discover existing plans and specs under docs/ and .ai/thoughts/ before writing new ones.',

package/dist/server/services/agent/orchestrator.js

@@ -704,7 +704,7 @@ function handleQuota(workspaceId, _agentSessionId) {
                     autoLoopService.onQuotaBackoffExpired(workspaceId);
                 }
                 else {
-                    const freshWorkingDir = `${freshWs.projectPath}/.worktrees/${freshWs.workingBranch}`;
+                    const freshWorkingDir = freshWs.worktreePath;
                     startAgent(workspaceId, freshWorkingDir, 'Continue the previous task where you left off.', undefined, true);
                 }
             }