feat: worktree UX, PR status badges, reliable restart, model-spawn fix

CLAUDE.md

@@ -101,5 +101,5 @@ The lock file will prevent accidental duplicate starts.
 <!-- CODEUI-RULES -->
 ## Custom Rules
 
-if it's a new feature, try to use a test cli unless it would be much easier to just have the user do a manual test (this is usually the case for visual features).. if it doesn't have functionality to do the test then add it. you can also use playwright mcp or curl if either of these would be easier. make sure you have enough logging to debug any issues.. if you create any test files, clean them up when you are done.  NEVER TOUCH PORT 4001 or 5173.. if you are having issues with public apis, lookup examples online. NEVER create summary reports! NEVER add attribution comments like "Generated with Claude Code", "Co-Authored-By: Claude", or similar in PR descriptions, issues, commit messages, code comments, or any other artifacts.
+if it's a new feature, try to use a test cli unless it would be much easier to just have the user do a manual test (this is usually the case for visual features).. if it doesn't have functionality to do the test then add it. you can also use playwright mcp or curl if either of these would be easier. make sure you have enough logging to debug any issues.. if you create any test files, clean them up when you are done.  NEVER TOUCH PORT 4001 or 5173.. if you are having issues with public apis, lookup examples online. NEVER create summary reports! NEVER push to main without explicit user approval. NEVER commit and push without letting the user test/validate changes first. Always ask before committing and before pushing. All changes should go through PRs, not direct pushes to main. NEVER add attribution comments like "Generated with Claude Code", "Co-Authored-By: Claude", or similar in PR descriptions, issues, commit messages, code comments, or any other artifacts.
 <!-- /CODEUI-RULES -->

backend/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "cross-env NODE_OPTIONS=--max-old-space-size=2048 tsx watch --watch-path=src src/index.ts",
+    "dev": "cross-env CLAUDIA_WATCH_MODE=1 NODE_OPTIONS=--max-old-space-size=2048 tsx watch --watch-path=src src/index.ts",
     "dev:no-watch": "cross-env NODE_OPTIONS=--max-old-space-size=2048 tsx src/index.ts",
     "build": "tsc",
     "start": "node dist/index.js",

backend/src/claudia-mcp-server.ts

@@ -369,7 +369,7 @@ server.tool(
 // ============================================================================
 // Tool: claudia_create_task
 // ============================================================================
-const createTaskBaseDescription = `Create a new task in Claudia. The task will be assigned to a Claude Code agent in the current workspace (${WORKSPACE_ID || 'unknown'}). Use this to delegate work to other agents running in parallel.`;
+const createTaskBaseDescription = `Create a new task in Claudia. The task will be assigned to a Claude Code agent in the current workspace (${WORKSPACE_ID || 'unknown'}). Use this to delegate work to other agents running in parallel. PREFER this over launching your own internal subagent (the built-in Agent/Task tool) for any delegatable work — Claudia tasks are user-visible, monitorable, resumable, and isolated. Only use your own subagent for a quick throwaway lookup you need inline, or when a Claudia task would clearly give a worse result.`;
 
 const createTaskTieringSuffix = `
 
@@ -380,8 +380,8 @@ You can pass an optional \`complexity\` hint to control the cost of the spawned
 
 Be conservative — pick \`low\` when the work is genuinely simple. Omit the parameter to use the workspace's default model.`;
 
-async function handleCreateTask(args: { prompt: string; displayName?: string; complexity?: 'low' | 'medium' | 'high' }) {
-    const { prompt, displayName, complexity } = args;
+async function handleCreateTask(args: { prompt: string; displayName?: string; complexity?: 'low' | 'medium' | 'high'; isolate?: boolean }) {
+    const { prompt, displayName, complexity, isolate } = args;
     if (!WORKSPACE_ID) {
         return {
             content: [{
@@ -391,13 +391,44 @@ async function handleCreateTask(args: { prompt: string; displayName?: string; co
         };
     }
 
+    // If isolate=true, create an isolated worktree via the REST API before spawning the task
+    let effectiveWorkspaceId = WORKSPACE_ID;
+    if (isolate) {
+        try {
+            log.info('isolate=true: creating worktree before task spawn');
+            const { randomBytes } = await import('crypto');
+            const shortId = randomBytes(4).toString('hex');
+            const branch = `claudia/task-${shortId}`;
+            const res = await backendFetch(
+                `/api/worktrees?workspace=${encodeURIComponent(WORKSPACE_ID)}`,
+                {
+                    method: 'POST',
+                    body: JSON.stringify({ branch, createBranch: true }),
+                }
+            );
+            if (res.ok) {
+                const data = await res.json() as { worktreePath?: string; workspace?: { id?: string } };
+                const worktreePath = data.workspace?.id ?? data.worktreePath;
+                if (worktreePath) {
+                    effectiveWorkspaceId = worktreePath;
+                    log.info(`Worktree created: ${worktreePath} (branch=${branch})`);
+                }
+            } else {
+                const err = await res.text();
+                log.error(`Failed to create worktree (isolate): ${err}. Falling back to parent workspace.`);
+            }
+        } catch (isolateErr) {
+            log.error('Worktree creation for isolate failed (non-fatal)', isolateErr);
+        }
+    }
+
     try {
-        log.info(`Creating task in workspace: ${WORKSPACE_ID}${complexity ? ` (complexity=${complexity})` : ''}`);
+        log.info(`Creating task in workspace: ${effectiveWorkspaceId}${complexity ? ` (complexity=${complexity})` : ''}${isolate ? ' (isolated)' : ''}`);
         log.info(`Prompt: ${prompt.substring(0, 100)}...`);
 
         const payload: Record<string, unknown> = {
             prompt,
-            workspaceId: WORKSPACE_ID,
+            workspaceId: effectiveWorkspaceId,
             source: 'mcp',
         };
         if (MODEL_TIERING_ENABLED && complexity) {
@@ -427,10 +458,11 @@ async function handleCreateTask(args: { prompt: string; displayName?: string; co
                         taskId: task.id,
                         displayName: displayName || null,
                         state: task.state,
-                        workspace: task.workspaceId,
+                        workspace: effectiveWorkspaceId,
+                        isolated: isolate && effectiveWorkspaceId !== WORKSPACE_ID,
                         prompt: task.prompt?.substring(0, 200),
                         complexity: complexity || null,
-                        message: `Task '${task.id}'${displayName ? ` (${displayName})` : ''} created successfully. It is now running in workspace '${WORKSPACE_ID}'.`
+                        message: `Task '${task.id}'${displayName ? ` (${displayName})` : ''} created successfully${isolate && effectiveWorkspaceId !== WORKSPACE_ID ? ` in isolated worktree '${effectiveWorkspaceId}'` : ` in workspace '${WORKSPACE_ID}'`}.`
                     }, null, 2)
                 }]
             };
@@ -457,6 +489,14 @@ async function handleCreateTask(args: { prompt: string; displayName?: string; co
     }
 }
 
+const isolateParam = {
+    isolate: z.boolean().optional().describe(
+        'When true, creates a new isolated git worktree for this task (branch: claudia/task-<id>). ' +
+        'Use this when the task will make file changes that should not conflict with other tasks running in the same workspace. ' +
+        'Recommended for parallel feature development or any task that will commit changes.'
+    ),
+};
+
 if (MODEL_TIERING_ENABLED) {
     server.tool(
         'claudia_create_task',
@@ -467,6 +507,7 @@ if (MODEL_TIERING_ENABLED) {
             complexity: z.enum(['low', 'medium', 'high']).optional().describe(
                 'Cost/capability tier for the spawned task. Use "low" for trivial work, "medium" for normal coding, "high" for hard reasoning. Omit to use the workspace default model.'
             ),
+            ...isolateParam,
         },
         async (args) => handleCreateTask(args)
     );
@@ -477,6 +518,7 @@ if (MODEL_TIERING_ENABLED) {
         {
             prompt: z.string().describe('The prompt/instructions for the new task'),
             displayName: z.string().optional().describe('Optional short display name for the task in the Claudia sidebar (e.g., "Build API endpoint", "Write tests")'),
+            ...isolateParam,
         },
         async (args) => handleCreateTask(args)
     );

backend/src/git-utils.ts

@@ -1,6 +1,6 @@
 import { exec, execFile } from 'child_process';
 import { promisify } from 'util';
-import { TaskGitState, FileDiff } from '@claudia/shared';
+import { TaskGitState, FileDiff, WorkspacePrInfo } from '@claudia/shared';
 
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
@@ -244,6 +244,45 @@ export async function captureGitStateAfter(
 // Beyond this, the task is considered stale and revert is blocked
 const MAX_REVERT_COMMITS = 5;
 
+/**
+ * Detect if a directory is a git-linked worktree (not the main working tree).
+ * In a linked worktree, `.git` is a FILE; in the main working tree it is a DIRECTORY.
+ */
+export async function isLinkedWorktree(cwd: string): Promise<boolean> {
+    try {
+        const { lstatSync, existsSync } = await import('fs');
+        const { join } = await import('path');
+        const gitPath = join(cwd, '.git');
+        if (!existsSync(gitPath)) return false;
+        return lstatSync(gitPath).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Get the absolute path to the main working tree from any worktree.
+ * Uses `git rev-parse --path-format=absolute --git-common-dir` which works in both
+ * the main working tree and in linked worktrees.
+ */
+export async function getMainWorktreePath(cwd: string): Promise<string | null> {
+    try {
+        const { execFile } = await import('child_process');
+        const { promisify } = await import('util');
+        const { resolve } = await import('path');
+        const execFileA = promisify(execFile);
+        const { stdout } = await execFileA(
+            'git',
+            ['rev-parse', '--path-format=absolute', '--git-common-dir'],
+            { cwd }
+        );
+        // Strip trailing /.git[/] to get the main worktree directory
+        return resolve(stdout.trim().replace(/[\/\\]\.git[\/\\]?$/, ''));
+    } catch {
+        return null;
+    }
+}
+
 /**
  * Revert changes made by a task
  * This will:
@@ -346,3 +385,72 @@ export async function revertTaskChanges(
         };
     }
 }
+
+/** Summarize a gh statusCheckRollup array into a single CI state. */
+function summarizeCi(rollup: unknown): WorkspacePrInfo['ci'] {
+    if (!Array.isArray(rollup) || rollup.length === 0) return 'none';
+    let anyRunning = false;
+    let anyFailed = false;
+    let anyTerminal = false;
+    for (const check of rollup) {
+        if (!check || typeof check !== 'object') continue;
+        // CheckRun: { status: QUEUED|IN_PROGRESS|COMPLETED, conclusion: SUCCESS|FAILURE|... }
+        // StatusContext: { state: SUCCESS|PENDING|FAILURE|ERROR }
+        const status = String((check as any).status || '').toUpperCase();
+        const conclusion = String((check as any).conclusion || '').toUpperCase();
+        const state = String((check as any).state || '').toUpperCase();
+
+        if (status === 'IN_PROGRESS' || status === 'QUEUED' || status === 'PENDING' ||
+            status === 'WAITING' || status === 'REQUESTED' || state === 'PENDING' || state === 'EXPECTED') {
+            anyRunning = true;
+            continue;
+        }
+        const outcome = conclusion || state; // COMPLETED uses conclusion; StatusContext uses state
+        anyTerminal = true;
+        if (['FAILURE', 'ERROR', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED', 'STARTUP_FAILURE'].includes(outcome)) {
+            anyFailed = true;
+        }
+    }
+    if (anyFailed) return 'failed';
+    if (anyRunning) return 'running';
+    if (anyTerminal) return 'passed';
+    return 'none';
+}
+
+/**
+ * Look up the GitHub PR for a branch via the `gh` CLI. Returns null when there's
+ * no PR, `gh` is missing/unauthenticated, or the dir isn't a GitHub repo.
+ * Never throws — callers can treat null as "no badge".
+ */
+export async function getPrForBranch(repoPath: string, branch: string): Promise<WorkspacePrInfo | null> {
+    if (!branch || !isValidBranchName(branch)) return null;
+    try {
+        const { stdout } = await execFileAsync(
+            'gh',
+            ['pr', 'list', '--head', branch, '--state', 'all', '--limit', '1',
+             '--json', 'number,title,state,isDraft,url,statusCheckRollup'],
+            { cwd: repoPath, timeout: 15000 }
+        );
+        const arr = JSON.parse(stdout) as Array<{
+            number: number; title: string; state: string; isDraft: boolean; url: string; statusCheckRollup?: unknown;
+        }>;
+        if (!Array.isArray(arr) || arr.length === 0) return null;
+        const pr = arr[0];
+        const rawState = String(pr.state || '').toUpperCase();
+        const state: WorkspacePrInfo['state'] = pr.isDraft
+            ? 'draft'
+            : rawState === 'MERGED' ? 'merged'
+            : rawState === 'CLOSED' ? 'closed'
+            : 'open';
+        return {
+            number: pr.number,
+            title: pr.title || '',
+            state,
+            url: pr.url,
+            ci: summarizeCi(pr.statusCheckRollup),
+        };
+    } catch {
+        // gh missing/unauth, not a repo, no network — no badge.
+        return null;
+    }
+}