@loicngr/kobo 1.4.5 → 1.4.7

package/dist/server/routes/workspaces.js

@@ -1,4 +1,4 @@
-import { execFile as execFileCb } from 'node:child_process';
+import { execFile as execFileCb, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 const execFileAsync = promisify(execFileCb);
 import fs from 'node:fs';
@@ -15,8 +15,10 @@ import * as wsService from '../services/websocket-service.js';
 import * as workspaceService from '../services/workspace-service.js';
 import * as worktreeService from '../services/worktree-service.js';
 import * as gitOps from '../utils/git-ops.js';
+/** Hono sub-router for workspace CRUD, tasks, agent lifecycle, git operations, and PR creation. */
 const app = new Hono();
-// GET /api/workspaces — list all workspaces
+/** Tracks workspaces currently running a setup script to prevent concurrent executions. */
+const setupScriptRunning = new Set();
 app.get('/', (c) => {
     try {
         const workspaces = workspaceService.listWorkspaces();
@@ -34,7 +36,7 @@ app.post('/', async (c) => {
         if (!body.name || !body.projectPath || !body.sourceBranch || !body.workingBranch) {
             return c.json({ error: 'Missing required fields: name, projectPath, sourceBranch, workingBranch' }, 400);
         }
-        // 1. Create workspace
+        // Create workspace record
         let workspace = workspaceService.createWorkspace({
             name: body.name,
             projectPath: body.projectPath,
@@ -45,7 +47,7 @@ app.post('/', async (c) => {
             model: body.model,
         });
         let notionContent = null;
-        // 2. If notionUrl provided, extract Notion page
+        // Extract Notion page content if a URL was provided
         if (body.notionUrl) {
             workspaceService.updateWorkspaceStatus(workspace.id, 'extracting');
             try {
@@ -56,7 +58,7 @@ app.post('/', async (c) => {
                 console.error(`[workspaces] Failed to extract Notion page: ${message}`);
             }
         }
-        // 3. Create tasks from extracted data
+        // Create tasks from extracted Notion data
         if (notionContent) {
             let sortOrder = 0;
             for (const todo of notionContent.todos) {
@@ -104,7 +106,7 @@ app.post('/', async (c) => {
                 }
             }
         }
-        // 4. Create worktree
+        // Create git worktree for the working branch
         let worktreePath;
         try {
             worktreePath = worktreeService.createWorktree(body.projectPath, body.workingBranch, body.sourceBranch);
@@ -114,45 +116,54 @@ app.post('/', async (c) => {
             workspaceService.updateWorkspaceStatus(workspace.id, 'error');
             return c.json({ error: `Failed to create worktree: ${message}` }, 500);
         }
-        // 4b. Ensure Kobo-generated files inside .ai/ are gitignored (the .ai/ dir
-        //     itself may contain project files that SHOULD be committed).
+        // Ensure Kobo-generated files are gitignored. Check both the root
+        // .gitignore and .ai/.gitignore to avoid duplicate entries.
         try {
-            const gitignorePath = path.join(worktreePath, '.gitignore');
-            const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf-8') : '';
-            const lines = existing.split('\n').map((l) => l.trim());
+            const rootGitignorePath = path.join(worktreePath, '.gitignore');
+            const aiGitignorePath = path.join(worktreePath, '.ai', '.gitignore');
+            const rootContent = fs.existsSync(rootGitignorePath) ? fs.readFileSync(rootGitignorePath, 'utf-8') : '';
+            const rootLines = rootContent.split('\n').map((l) => l.trim());
+            const aiContent = fs.existsSync(aiGitignorePath) ? fs.readFileSync(aiGitignorePath, 'utf-8') : '';
+            const aiLines = aiContent.split('\n').map((l) => l.trim());
+            // Each entry: [pattern for root .gitignore, equivalent pattern in .ai/.gitignore]
+            const entries = [
+                ['.ai/.git-conventions.md', '.git-conventions.md'],
+                ['.ai/thoughts/', 'thoughts/'],
+                ['.ai/images/', 'images/'],
+                ['.ai/.setup-script.tmp', '.setup-script.tmp'],
+                ['.mcp.json', ''],
+            ];
             const toAdd = [];
-            if (!lines.includes('.ai/git-conventions.md'))
-                toAdd.push('.ai/git-conventions.md');
-            if (!lines.includes('.ai/thoughts/'))
-                toAdd.push('.ai/thoughts/');
-            if (!lines.includes('.ai/images/'))
-                toAdd.push('.ai/images/');
-            if (!lines.includes('.ai/.setup-script.tmp'))
-                toAdd.push('.ai/.setup-script.tmp');
+            for (const [rootPattern, aiPattern] of entries) {
+                const inRoot = rootLines.includes(rootPattern);
+                const inAi = aiPattern && aiLines.includes(aiPattern);
+                if (!inRoot && !inAi)
+                    toAdd.push(rootPattern);
+            }
             if (toAdd.length > 0) {
-                const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
-                fs.appendFileSync(gitignorePath, `${separator}${toAdd.join('\n')}\n`, 'utf-8');
+                const separator = rootContent.length > 0 && !rootContent.endsWith('\n') ? '\n' : '';
+                fs.appendFileSync(rootGitignorePath, `${separator}${toAdd.join('\n')}\n`, 'utf-8');
             }
         }
         catch (err) {
             console.error('[workspaces] Failed to update .gitignore:', err);
         }
-        // 4c. Write git conventions to the worktree if configured
+        // Write git conventions to the worktree if configured
         const effectiveSettings = settingsService.getEffectiveSettings(body.projectPath);
         if (effectiveSettings.gitConventions) {
             try {
                 const aiDir = path.join(worktreePath, '.ai');
                 fs.mkdirSync(aiDir, { recursive: true });
-                const conventionsPath = path.join(aiDir, 'git-conventions.md');
+                const conventionsPath = path.join(aiDir, '.git-conventions.md');
                 fs.writeFileSync(conventionsPath, effectiveSettings.gitConventions, 'utf-8');
             }
             catch (err) {
-                console.error('[workspaces] Failed to write git-conventions.md:', err);
+                console.error('[workspaces] Failed to write .git-conventions.md:', err);
             }
         }
-        // 4d. Run setup script if configured
+        // Run setup script if configured and not skipped
         let setupScriptFailed = false;
-        if (effectiveSettings.setupScript) {
+        if (effectiveSettings.setupScript && !body.skipSetupScript) {
             workspaceService.updateWorkspaceStatus(workspace.id, 'extracting');
             wsService.emit(workspace.id, 'setup:output', { text: '[kobo] Running setup script...' });
             try {
@@ -174,17 +185,20 @@ app.post('/', async (c) => {
                 setupScriptFailed = true;
             }
         }
-        // 5. Save Notion content as markdown in worktree
+        // Save Notion content as markdown in worktree
         let notionFilePath = null;
         if (notionContent && body.notionUrl) {
             try {
                 const thoughtsDir = path.join(worktreePath, '.ai', 'thoughts');
                 fs.mkdirSync(thoughtsDir, { recursive: true });
-                // Derive filename from title (TK-XXX pattern or slug)
-                const tkMatch = workspace.name.match(/TK-\d+/i);
-                const filename = tkMatch
-                    ? `${tkMatch[0]}.md`
-                    : `PAGE-${notionService.parseNotionUrl(body.notionUrl).replace(/-/g, '')}.md`;
+                // Derive filename from Notion ticket ID, or fallback to branch/name pattern
+                const notionTicketId = notionContent.ticketId;
+                const fallbackMatch = `${workspace.name} ${body.workingBranch}`.match(/TK-\d+/i);
+                const filename = notionTicketId
+                    ? `${notionTicketId.toUpperCase()}.md`
+                    : fallbackMatch
+                        ? `${fallbackMatch[0].toUpperCase()}.md`
+                        : `PAGE-${notionService.parseNotionUrl(body.notionUrl).replace(/-/g, '')}.md`;
                 notionFilePath = path.join(thoughtsDir, filename);
                 const today = new Date().toISOString().split('T')[0];
                 let md = `# ${workspace.name}\n\n`;
@@ -215,17 +229,22 @@ app.post('/', async (c) => {
         }
         // Skip agent launch if setup script failed — workspace stays in 'error' status
         if (!setupScriptFailed) {
-            // 6. Update workspace status to 'brainstorming'
+            // Transition to brainstorming and build the initial agent prompt
             workspaceService.updateWorkspaceStatus(workspace.id, 'brainstorming');
-            // 6. Build prompt with tasks and acceptance criteria
+            // Build prompt with tasks and acceptance criteria
             const allTasks = workspaceService.listTasks(workspace.id);
             const todos = allTasks.filter((t) => !t.isAcceptanceCriterion);
             const criteria = allTasks.filter((t) => t.isAcceptanceCriterion);
             let brainstormPrompt = `You are working on: ${workspace.name}\n`;
+            // Include ticket ID if found so the agent uses the correct reference
+            const ticketId = notionContent?.ticketId || `${workspace.name} ${body.workingBranch}`.match(/TK-\d+/i)?.[0];
+            if (ticketId) {
+                brainstormPrompt += `Ticket: ${ticketId.toUpperCase()}\n`;
+            }
             if (notionContent?.goal) {
                 brainstormPrompt += `\nGoal: ${notionContent.goal}\n`;
             }
-            brainstormPrompt += `\nBranch: ${body.workingBranch}\n`;
+            brainstormPrompt += `\nBranch: ${body.workingBranch}\nSource branch: ${body.sourceBranch}\nIMPORTANT: When creating a pull request, always use --base ${body.sourceBranch} to target the correct source branch.\n`;
             if (notionFilePath) {
                 brainstormPrompt += `\nNotion ticket: ${body.notionUrl}`;
                 brainstormPrompt += `\nLocal copy: ${notionFilePath}\n`;
@@ -236,14 +255,17 @@ app.post('/', async (c) => {
             if (criteria.length > 0) {
                 brainstormPrompt += `\nAcceptance criteria:\n${criteria.map((t) => `- [${t.status === 'done' ? 'x' : ' '}] ${t.title}`).join('\n')}\n`;
             }
+            brainstormPrompt += `\nYou have access to MCP tools via the 'kobo-tasks' server:\n`;
             if (criteria.length > 0 || todos.length > 0) {
-                brainstormPrompt += `\nYou have access to MCP tools via the 'kobo-tasks' server:\n`;
                 brainstormPrompt += `- list_tasks() — list all tasks and criteria with their IDs and current status\n`;
                 brainstormPrompt += `- mark_task_done(task_id) — mark a task or criterion as done\n`;
-                brainstormPrompt += `\nAs you implement the work and validate each criterion, call mark_task_done with the corresponding task_id. Call list_tasks first to see the current IDs.\n`;
+                brainstormPrompt += `\nAs you work, keep the task list up to date: call mark_task_done(task_id) as soon as you complete a task or validate a criterion — don't wait until the end. Call list_tasks() first to see the current IDs.\n`;
+            }
+            if (body.notionUrl) {
+                brainstormPrompt += `- get_notion_ticket() — retrieve the Notion ticket info (URL, ticket ID, extracted content)\n`;
             }
             if (effectiveSettings.gitConventions) {
-                brainstormPrompt += `\n# Git conventions\nIMPORTANT: Before any git operation (commit, branch, rebase, merge, push), read and apply the conventions defined in \`.ai/git-conventions.md\`. They are project-specific and override any default behavior. Re-read this file if you're unsure or if context was compacted.\n`;
+                brainstormPrompt += `\n# Git conventions\nIMPORTANT: Before any git operation (commit, branch, rebase, merge, push), read and apply the conventions defined in \`.ai/.git-conventions.md\`. They are project-specific and override any default behavior. Re-read this file if you're unsure or if context was compacted.\n`;
             }
             brainstormPrompt += `\nIMPORTANT: Start by reading CLAUDE.md and/or AGENTS.md at the project root if they exist — they contain project conventions and instructions you must follow.`;
             brainstormPrompt += `\n\nThen brainstorm the implementation approach. Explore the codebase to understand the existing structure. Ask clarifying questions if needed. When you're done brainstorming and have a clear plan, create a plan file and proceed with implementation. Once you have completed the brainstorming phase, output [BRAINSTORM_COMPLETE] on its own line.`;
@@ -576,6 +598,82 @@ app.patch('/:id', async (c) => {
         return c.json({ error: message }, 500);
     }
 });
+/** Open the workspace worktree in the user's configured editor. */
+app.post('/:id/open-editor', (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 globalSettings = settingsService.getGlobalSettings();
+        if (!globalSettings.editorCommand) {
+            return c.json({ error: 'No editor command configured' }, 400);
+        }
+        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        if (!fs.existsSync(worktreePath)) {
+            return c.json({ error: `Worktree path does not exist: ${worktreePath}` }, 400);
+        }
+        const child = spawn(globalSettings.editorCommand, [worktreePath], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+        return c.json({ success: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+/** Re-run the project setup script in the workspace worktree. */
+app.post('/:id/run-setup-script', 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 (setupScriptRunning.has(id)) {
+            return c.json({ error: 'Setup script is already running for this workspace' }, 409);
+        }
+        // Stop the running agent before re-running the setup script
+        try {
+            if (agentManager.getAgentStatus(id)) {
+                agentManager.stopAgent(id);
+            }
+        }
+        catch {
+            /* best-effort — agent may already be stopped */
+        }
+        const effectiveSettings = settingsService.getEffectiveSettings(workspace.projectPath);
+        if (!effectiveSettings.setupScript) {
+            return c.json({ error: 'No setup script configured' }, 400);
+        }
+        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        if (!fs.existsSync(worktreePath)) {
+            return c.json({ error: `Worktree path does not exist: ${worktreePath}` }, 400);
+        }
+        setupScriptRunning.add(id);
+        try {
+            const result = await runSetupScript(workspace.id, worktreePath, effectiveSettings.setupScript, {
+                workspaceName: workspace.name,
+                branchName: workspace.workingBranch,
+                sourceBranch: workspace.sourceBranch,
+                projectPath: workspace.projectPath,
+            });
+            if (result.exitCode !== 0) {
+                return c.json({ error: `Setup script failed with exit code ${result.exitCode}` }, 500);
+            }
+            return c.json({ success: true });
+        }
+        finally {
+            setupScriptRunning.delete(id);
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
 // POST /api/workspaces/:id/archive — mark workspace as archived (soft-delete)
 app.post('/:id/archive', (c) => {
     try {
@@ -641,14 +739,14 @@ app.delete('/:id', async (c) => {
         const body = await c.req
             .json()
             .catch(() => ({}));
-        // 1. Stop agent if running
+        // Stop agent if running (best-effort)
         try {
             agentManager.stopAgent(id);
         }
         catch {
             // Agent may not be running — ignore
         }
-        // 2. Remove worktree
+        // Remove worktree
         const worktreesDir = `${workspace.projectPath}/.worktrees`;
         const worktreePath = `${worktreesDir}/${workspace.workingBranch}`;
         try {
@@ -658,7 +756,7 @@ app.delete('/:id', async (c) => {
             const message = err instanceof Error ? err.message : String(err);
             console.error(`[workspaces] Failed to remove worktree: ${message}`);
         }
-        // 3. Delete local branch if requested
+        // Delete local branch if requested
         if (body.deleteLocalBranch) {
             try {
                 gitOps.deleteLocalBranch(workspace.projectPath, workspace.workingBranch);
@@ -668,7 +766,7 @@ app.delete('/:id', async (c) => {
                 console.error(`[workspaces] Failed to delete local branch: ${message}`);
             }
         }
-        // 4. Delete remote branch if requested
+        // Delete remote branch if requested
         if (body.deleteRemoteBranch) {
             try {
                 gitOps.deleteRemoteBranch(workspace.projectPath, workspace.workingBranch);
@@ -678,7 +776,7 @@ app.delete('/:id', async (c) => {
                 console.error(`[workspaces] Failed to delete remote branch: ${message}`);
             }
         }
-        // 5. Delete workspace from DB
+        // Delete workspace from DB (cascades to tasks, sessions, events)
         workspaceService.deleteWorkspace(id);
         return new Response(null, { status: 204 });
     }
@@ -823,7 +921,7 @@ app.post('/:id/open-pr', async (c) => {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
         const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
-        // 1. Check branch is on remote
+        // Verify branch exists on remote
         let lsRemoteOut = '';
         try {
             const { stdout } = await execFileAsync('git', ['ls-remote', '--heads', 'origin', workspace.workingBranch], {
@@ -837,7 +935,7 @@ app.post('/:id/open-pr', async (c) => {
         if (!lsRemoteOut.trim()) {
             return c.json({ error: 'Branch is not on remote', code: 'branch_not_pushed' }, 409);
         }
-        // 2. Check all local commits are pushed
+        // Ensure all local commits are pushed
         try {
             const { stdout } = await execFileAsync('git', ['rev-list', '@{u}..HEAD', '--count'], { cwd: worktreePath });
             const countStr = stdout.trim();
@@ -855,7 +953,7 @@ app.post('/:id/open-pr', async (c) => {
             }
             return c.json({ error: `Failed to check branch state: ${message}` }, 500);
         }
-        // 3. Create PR via gh
+        // Create PR via GitHub CLI
         let ghOutput;
         try {
             const placeholderBody = 'Automated PR — description will be updated by the agent.';
@@ -878,7 +976,7 @@ app.post('/:id/open-pr', async (c) => {
             const stderr = err.stderr?.toString() ?? '';
             return c.json({ error: `gh pr create failed: ${message} ${stderr}`.trim() }, 500);
         }
-        // 4. Parse PR URL and number
+        // Parse PR URL and number from gh output
         const urlMatch = ghOutput.match(/https:\/\/github\.com\/[^\s]+\/pull\/(\d+)/);
         if (!urlMatch) {
             return c.json({ error: 'Could not parse PR URL from gh output' }, 500);
@@ -886,12 +984,12 @@ app.post('/:id/open-pr', async (c) => {
         const prUrl = urlMatch[0];
         const prNumber = parseInt(urlMatch[1], 10);
         // ── From here on, PR exists. No more 5xx responses. ──
-        // 5. Resolve the template; skip message steps if empty
+        // Resolve the PR prompt template; skip message steps if empty
         const effective = settingsService.getEffectiveSettings(workspace.projectPath);
         if (!effective.prPromptTemplate) {
             return c.json({ ok: true, prNumber, prUrl, messageSent: false });
         }
-        // 6. Build context and render the template
+        // Build context and render the PR prompt template
         const commits = gitOps.getCommitsBetween(worktreePath, workspace.sourceBranch, workspace.workingBranch);
         const diffStats = gitOps.getDiffStatsBetween(worktreePath, workspace.sourceBranch, workspace.workingBranch);
         const tasks = workspaceService.listTasks(workspace.id);
@@ -903,11 +1001,11 @@ app.post('/:id/open-pr', async (c) => {
             diffStats,
             tasks,
         });
-        // 7. Emit user:message into the chat feed
+        // Emit user:message into the chat feed
         const session = workspaceService.getLatestSession(workspace.id);
         const sessionId = session?.claudeSessionId ?? undefined;
         wsService.emit(workspace.id, 'user:message', { content: rendered, sender: 'user' }, sessionId);
-        // 8. Send to the running agent, or resume the agent with the PR prompt
+        // Send to the running agent, or resume the agent with the PR prompt
         let messageSent = false;
         try {
             agentManager.sendMessage(workspace.id, rendered);
@@ -933,6 +1031,23 @@ app.post('/:id/open-pr', async (c) => {
         return c.json({ error: message }, 500);
     }
 });
+/** POST /api/workspaces/:id/mark-read — mark workspace as read (clear unread indicator). */
+app.post('/:id/mark-read', (c) => {
+    try {
+        const id = c.req.param('id');
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace) {
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        }
+        workspaceService.markWorkspaceRead(id);
+        wsService.emitEphemeral(id, 'workspace:unread', { hasUnread: false });
+        return c.json({ success: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
 // POST /api/workspaces/:id/stop — stop agent
 app.post('/:id/stop', (c) => {
     try {

package/dist/server/services/agent-manager.js

@@ -7,8 +7,8 @@ import { getDb } from '../db/index.js';
 import { ensureKoboHome, getCompiledMcpServerPath, getDbPath, getMcpServerSourcePath, getSettingsPath, getSkillsPath, } from '../utils/paths.js';
 import { registerProcess, unregisterProcess } from '../utils/process-tracker.js';
 import { getEffectiveSettings } from './settings-service.js';
-import { emit } from './websocket-service.js';
-import { getWorkspace as getWs, listTasks, updateWorkspaceStatus } from './workspace-service.js';
+import { emit, emitEphemeral } from './websocket-service.js';
+import { getWorkspace as getWs, listTasks, markWorkspaceUnread, updateWorkspaceStatus } from './workspace-service.js';
 // ── State ──────────────────────────────────────────────────────────────────────
 /** Actual bound port of the running backend — set at startup via setBackendPort() */
 let backendPort = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;
@@ -82,6 +82,13 @@ function runWatchdog() {
         catch {
             // Transition may not be valid — ignore
         }
+        try {
+            markWorkspaceUnread(workspaceId);
+            emitEphemeral(workspaceId, 'workspace:unread', { hasUnread: true });
+        }
+        catch {
+            // best-effort
+        }
         emit(workspaceId, 'agent:status', { status: 'error', message: 'Agent process died unexpectedly' }, agent.claudeSessionId);
     }
 }
@@ -100,6 +107,7 @@ export function stopWatchdog() {
     }
 }
 // ── Start agent ────────────────────────────────────────────────────────────────
+/** Spawn a Claude Code CLI process for a workspace and wire up stdout/stderr/exit handling. */
 export function startAgent(workspaceId, workingDir, prompt, model, resume = false, permissionMode = 'auto-accept') {
     // Check if agent already running for this workspace
     if (agents.has(workspaceId)) {
@@ -301,7 +309,6 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
     });
     // ── stderr — detect quota / rate limit errors ──
     proc.stderr?.on('data', (data) => {
-        // I1: Don't process quota errors if the agent is already stopping or gone
         const currentAgent = agents.get(workspaceId);
         if (!currentAgent || currentAgent.status === 'stopping')
             return;
@@ -322,7 +329,6 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
         catch {
             // File may not exist (spawn failed) — ignore
         }
-        // I3: Close readline interface to release the stream reference
         agent.rl.close();
         unregisterProcess(workspaceId);
         // Only remove from the map if this exact agent instance is still current.
@@ -334,7 +340,7 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
         }
         // Clean up retry state and inactivity timer
         retryCounts.delete(workspaceId);
-        // C2: Clear the kill timer if it's still pending (process exited naturally before SIGKILL)
+        // Clear the kill timer if it's still pending (process exited naturally before SIGKILL)
         const pendingKillTimer = killTimers.get(workspaceId);
         if (pendingKillTimer) {
             clearTimeout(pendingKillTimer);
@@ -350,7 +356,7 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
             emit(workspaceId, 'agent:status', { status: 'stopped' }, agent.claudeSessionId);
             return;
         }
-        // C1: Also clear backoff timers on non-stopping exit
+        // Also clear backoff timers on non-stopping exit
         const pendingBackoff = backoffTimers.get(workspaceId);
         if (pendingBackoff) {
             clearTimeout(pendingBackoff);
@@ -363,6 +369,13 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
             catch (err) {
                 console.error('[agent] Failed to update workspace status on exit:', err);
             }
+            try {
+                markWorkspaceUnread(workspaceId);
+                emitEphemeral(workspaceId, 'workspace:unread', { hasUnread: true });
+            }
+            catch {
+                // best-effort
+            }
             emit(workspaceId, 'agent:status', { status: 'error', exitCode: code }, agent.claudeSessionId);
         }
         else {
@@ -372,6 +385,13 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
             catch (err) {
                 console.error('[agent] Failed to update workspace status on exit:', err);
             }
+            try {
+                markWorkspaceUnread(workspaceId);
+                emitEphemeral(workspaceId, 'workspace:unread', { hasUnread: true });
+            }
+            catch {
+                // best-effort
+            }
             emit(workspaceId, 'agent:status', { status: 'completed' }, agent.claudeSessionId);
         }
     });
@@ -382,6 +402,7 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
     return agent;
 }
 // ── Stop agent ─────────────────────────────────────────────────────────────────
+/** Gracefully stop an agent (SIGTERM, then SIGKILL after 5s). */
 export function stopAgent(workspaceId) {
     const agent = agents.get(workspaceId);
     if (!agent) {
@@ -398,7 +419,6 @@ export function stopAgent(workspaceId) {
         clearTimeout(timer);
         backoffTimers.delete(workspaceId);
     }
-    // I3: Close readline interface now that we're stopping
     try {
         agent.rl.close();
     }
@@ -414,7 +434,7 @@ export function stopAgent(workspaceId) {
     }
     // After 5s timeout, send SIGKILL if still running
     const killTimer = setTimeout(() => {
-        // C2: If a new agent has been started for this workspace in the meantime,
+        // If a new agent has been started for this workspace in the meantime,
         // don't kill the old process — it's handled by the new lifecycle.
         const currentAgent = agents.get(workspaceId);
         if (currentAgent && currentAgent !== agent) {
@@ -436,6 +456,7 @@ export function stopAgent(workspaceId) {
     killTimers.set(workspaceId, killTimer);
 }
 // ── Send message to agent stdin ────────────────────────────────────────────────
+/** Write a user message to the running agent's stdin. */
 export function sendMessage(workspaceId, content) {
     const agent = agents.get(workspaceId);
     if (!agent) {
@@ -447,15 +468,20 @@ export function sendMessage(workspaceId, content) {
     agent.process.stdin.write(`${content}\n`);
 }
 // ── Status queries ─────────────────────────────────────────────────────────────
+/** Get the in-memory status of the agent for a workspace, or null if not running. */
 export function getAgentStatus(workspaceId) {
     const agent = agents.get(workspaceId);
     return agent?.status ?? null;
 }
+/** Return the number of currently running agents. */
 export function getRunningCount() {
     return agents.size;
 }
+/** Kobo built-in slash commands injected into the skill list (without leading /). */
+const KOBO_COMMANDS = ['kobo-check-progress'];
+/** Return the cached list of slash commands discovered from the last agent init, plus Kobo built-in commands. */
 export function getAvailableSkills() {
-    return availableSkills;
+    return [...KOBO_COMMANDS, ...availableSkills];
 }
 // ── Quota handling ─────────────────────────────────────────────────────────────
 function handleQuota(workspaceId, claudeSessionId) {

package/dist/server/services/image-service.js

@@ -1,4 +1,3 @@
-// src/server/services/image-service.ts
 import fs from 'node:fs';
 import path from 'node:path';
 import { nanoid } from 'nanoid';
@@ -30,6 +29,7 @@ function readIndex(imagesDir) {
 function writeIndex(imagesDir, entries) {
     fs.writeFileSync(path.join(imagesDir, INDEX_FILE), JSON.stringify(entries, null, 2));
 }
+/** Save an image buffer to `.ai/images/` and update the index. Returns the UID and relative path. */
 export async function saveImage(worktreePath, fileBuffer, originalName) {
     const ext = path.extname(originalName).toLowerCase().replace('.', '');
     if (!ext) {
@@ -53,6 +53,7 @@ export async function saveImage(worktreePath, fileBuffer, originalName) {
     });
     return { uid, relativePath: `${IMAGES_DIR}/${filename}` };
 }
+/** Delete an image by UID from disk and the index. */
 export async function deleteImage(worktreePath, uid) {
     const imagesDir = path.join(worktreePath, IMAGES_DIR);
     await withLock(worktreePath, () => {