@loicngr/kobo 1.11.16 → 1.11.18

package/dist/server/routes/workspaces.js

@@ -41,6 +41,7 @@ import * as purgeWorktreeService from '../services/worktree-purge-service.js';
 import * as worktreeService from '../services/worktree-service.js';
 import { resolveUniqueBranchAndPath } from '../utils/branch-resolver.js';
 import * as gitOps from '../utils/git-ops.js';
+import { logError } from '../utils/logger.js';
 import { slugifyProjectName } from '../utils/project-slug.js';
 import * as safePath from '../utils/safe-path.js';
 import { resolveSiblingWorkspaceWorktreePath } from '../utils/worktree-paths.js';
@@ -48,6 +49,124 @@ import { resolveSiblingWorkspaceWorktreePath } from '../utils/worktree-paths.js'
 const app = new Hono();
 /** Tracks workspaces currently running a setup script to prevent concurrent executions. */
 const setupScriptRunning = new Set();
+/**
+ * Ordered, named steps of `POST /api/workspaces`. The handler already runs
+ * these sequentially; naming them is what lets the create page say WHAT it is
+ * waiting on instead of showing an undifferentiated spinner for what can be
+ * several minutes (a user-supplied setup script runs inside this request).
+ */
+export const CREATE_WORKSPACE_STEPS = [
+    'validate',
+    'fetch-source-branch',
+    'inspect-worktree',
+    'extract-notion',
+    'extract-sentry',
+    'create-record',
+    'create-tasks',
+    'create-worktree',
+    'write-conventions',
+    'write-context-files',
+    'build-prompt',
+    'setup-script',
+    'start-agent',
+    // Never reached on a happy path. Emitted while the handler UNDOES a failed
+    // creation, so the page stops showing the last step it managed to reach.
+    'rollback',
+    'done',
+];
+/**
+ * Emit one creation-progress beat.
+ *
+ * The channel is the client-supplied `creationId`, NOT a workspace id: while
+ * this handler runs, the workspace row may not exist yet and the client has
+ * no id to subscribe to (the POST response is still in flight). A WebSocket
+ * subscription is just a string in a Set, and `emitEphemeral` never persists,
+ * so there is no foreign key to satisfy — the existing machinery works as-is.
+ *
+ * No `creationId` (API consumers, tests) → no-op.
+ */
+function emitCreateProgress(creationId, step) {
+    if (!creationId)
+        return;
+    try {
+        wsService.emitEphemeral(creationId, 'workspace:create-progress', {
+            creationId,
+            step,
+            index: CREATE_WORKSPACE_STEPS.indexOf(step),
+            total: CREATE_WORKSPACE_STEPS.length,
+        });
+    }
+    catch (err) {
+        // Best-effort: a broken progress beat must never fail workspace creation.
+        console.error(`[workspaces] emitCreateProgress failed for step '${step}':`, err);
+    }
+}
+/**
+ * What a rollback provably cannot reach. The setup script may have installed
+ * dependencies in a global cache, started containers or written files outside
+ * the worktree — say so rather than implying a total undo.
+ */
+const SETUP_SCRIPT_ROLLBACK_CAVEAT = ' The setup script had already run: anything it created outside the worktree (containers, global caches, files elsewhere) was NOT undone.';
+/** Terminal failure beat — names the step that broke, so the user never has to guess. */
+function emitCreateFailed(creationId, step, message) {
+    if (!creationId)
+        return;
+    try {
+        wsService.emitEphemeral(creationId, 'workspace:create-failed', { creationId, step, message });
+    }
+    catch (err) {
+        // Best-effort: a broken failure beat must never mask or replace the real error.
+        console.error(`[workspaces] emitCreateFailed failed for step '${step}':`, err);
+    }
+}
+/**
+ * Undo a creation that failed after the workspace row existed.
+ *
+ * Delegates to `deleteWorkspaceWithSideEffects` — the module's ONE demolition
+ * path — rather than growing a second cleanup that would drift from it. That
+ * function already stops the agent, stops the dev server, destroys the
+ * terminal, skips a worktree the user brought (`worktreeOwned === false`), and
+ * collects side-effect failures as warnings without ever throwing.
+ *
+ * It is declared with `async function` further down the file, so it is hoisted
+ * and callable from here.
+ *
+ * IMPORTANT: this is best-effort cleanup. It must NEVER throw, and it must
+ * NEVER become the error the caller reports — the original cause always wins.
+ */
+async function rollbackFailedCreation(workspace, opts) {
+    try {
+        return await deleteWorkspaceWithSideEffects(workspace, {
+            deleteLocalBranch: opts.deleteLocalBranch,
+            // Nothing was ever pushed at this point in the creation flow.
+            deleteRemoteBranch: false,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[workspaces] rollback of '${workspace.id}' failed:`, message);
+        return [`Rollback of workspace '${workspace.name}' failed: ${message}`];
+    }
+}
+/**
+ * Move a freshly created workspace to `brainstorming`, never throwing.
+ *
+ * This transition is cosmetic — the agent starts either way — but it sits
+ * inside the creation try block, so letting it throw would hand a live
+ * workspace to the rollback path and demolish it. The realistic trigger is a
+ * race: a long setup script leaves the row visible in the sidebar, the user
+ * clicks Start, the agent moves the workspace to `executing`, and
+ * `executing -> brainstorming` is then a rejected transition. Losing the
+ * status beat is a cosmetic bug; losing the worktree is data loss.
+ */
+function markBrainstormingBestEffort(workspaceId) {
+    try {
+        workspaceService.updateWorkspaceStatus(workspaceId, 'brainstorming');
+    }
+    catch (err) {
+        console.error(`[workspaces] could not mark '${workspaceId}' as brainstorming:`, err);
+    }
+}
 const VALID_AGENT_PERMISSION_MODES = ['plan', 'bypass', 'strict', 'interactive'];
 const VALID_WORKSPACE_STATUSES = [
     'created',
@@ -144,8 +263,10 @@ app.post('/:id/switch-engine', migrationGuard, async (c) => {
         const handoff = typeof body.handoff === 'string' && body.handoff.trim()
             ? body.handoff.trim().slice(0, 30_000)
             : buildEngineHandoff(workspace, workspace.engine, body.engine);
+        // A new engine is started three lines below: the previous one must be dead
+        // first, or two agents share the worktree.
         if (agentManager.hasController(id))
-            agentManager.stopAgent(id);
+            await agentManager.stopAgentAndWait(id);
         const updated = workspaceService.updateWorkspaceEngineConfiguration(id, body.engine, model, effort, body.agentPermissionMode);
         const session = agentManager.startAgent(id, updated.worktreePath, handoff, updated.model, false, updated.agentPermissionMode, undefined, updated.reasoningEffort);
         workspaceService.updateWorkspaceStatus(id, 'executing');
@@ -158,6 +279,25 @@ app.post('/:id/switch-engine', migrationGuard, async (c) => {
 });
 // POST /api/workspaces — create workspace
 app.post('/', migrationGuard, async (c) => {
+    // Declared outside the try so the outermost catch (any unforeseen throw,
+    // including a malformed request body) can still name a step instead of
+    // leaving the create-progress channel silent. Updated in lockstep with
+    // every `emitCreateProgress` call below via the assignment-expression
+    // argument, so it always reflects the last beat actually emitted.
+    let creationId;
+    let currentStep = 'validate';
+    // The workspace row, as soon as it exists, so the outermost catch can undo a
+    // creation that broke on a step with no handler of its own. Only `name` ever
+    // changes afterwards (Notion / Sentry title), and the rollback uses it for
+    // log text alone — every field it acts on is fixed at creation time.
+    let createdWorkspace = null;
+    // Set only once WE created the worktree, which is also what created the
+    // branch. A failure before that point must not delete a branch we never made.
+    let createdBranch = false;
+    // Hoisted out of the `build-prompt` block (declared with `const` there) so
+    // both rollback paths — the `start-agent` branch and the outermost catch —
+    // can read it to decide whether the setup-script caveat applies.
+    let setupScriptConfigured = false;
     try {
         const body = await c.req.json();
         // workingBranch is derived from git when worktreePath is provided, so
@@ -168,6 +308,17 @@ app.post('/', migrationGuard, async (c) => {
         if (!body.worktreePath && !body.workingBranch) {
             return c.json({ error: 'Missing required field: workingBranch' }, 400);
         }
+        // Only when the caller actually supplies it: when worktreePath is given
+        // instead, workingBranch is derived from git itself further down, not
+        // user input. A name starting with `-` would otherwise read as a git
+        // option (`--upload-pack=…`) rather than a branch name — see
+        // isValidBranchName's own doc comment for why this specific shape matters.
+        if (body.workingBranch && !gitOps.isValidBranchName(body.workingBranch)) {
+            return c.json({ error: `Invalid working branch name: ${body.workingBranch}` }, 400);
+        }
+        creationId = typeof body.creationId === 'string' && body.creationId.length > 0 ? body.creationId : undefined;
+        currentStep = 'validate';
+        emitCreateProgress(creationId, currentStep);
         // 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.
@@ -175,7 +326,9 @@ app.post('/', migrationGuard, async (c) => {
             const engines = listEngines();
             const validEngineIds = engines.map((e) => e.id);
             if (!validEngineIds.includes(body.engine)) {
-                return c.json({ error: `Unknown engine '${body.engine}'. Valid engines: ${validEngineIds.join(', ')}` }, 400);
+                const message = `Unknown engine '${body.engine}'. Valid engines: ${validEngineIds.join(', ')}`;
+                emitCreateFailed(creationId, 'validate', message);
+                return c.json({ error: message, step: 'validate' }, 400);
             }
             // Cross-validate engine × permission mode: each engine declares which
             // modes it supports via `capabilities.permissionModes`. The UI already
@@ -186,9 +339,9 @@ app.post('/', migrationGuard, async (c) => {
                 const engine = engines.find((e) => e.id === body.engine);
                 const supported = engine?.capabilities.permissionModes ?? [];
                 if (!supported.includes(body.agentPermissionMode)) {
-                    return c.json({
-                        error: `Engine '${body.engine}' does not support agentPermissionMode '${body.agentPermissionMode}'. Supported: ${supported.join(', ')}`,
-                    }, 400);
+                    const message = `Engine '${body.engine}' does not support agentPermissionMode '${body.agentPermissionMode}'. Supported: ${supported.join(', ')}`;
+                    emitCreateFailed(creationId, 'validate', message);
+                    return c.json({ error: message, step: 'validate' }, 400);
                 }
             }
         }
@@ -197,6 +350,8 @@ app.post('/', migrationGuard, async (c) => {
         // and only hard-block (422) when neither origin nor a local branch is usable.
         // The reuse path (body.worktreePath) needs no base ref, so a failed fetch is
         // simply logged there.
+        currentStep = 'fetch-source-branch';
+        emitCreateProgress(creationId, currentStep);
         const isReuseRequest = !!body.worktreePath;
         let baseRef = `origin/${body.sourceBranch}`;
         let usedLocalFallback = false;
@@ -214,7 +369,9 @@ app.post('/', migrationGuard, async (c) => {
                 console.warn(`[workspaces] fetch of '${body.sourceBranch}' from origin failed; falling back to local branch: ${message}`);
             }
             else {
-                return c.json({ error: `${message} — and no local branch '${body.sourceBranch}' exists to fall back on` }, 422);
+                const failure = `${message} — and no local branch '${body.sourceBranch}' exists to fall back on`;
+                emitCreateFailed(creationId, 'fetch-source-branch', failure);
+                return c.json({ error: failure, step: 'fetch-source-branch' }, 422);
             }
         }
         // Reuse-existing-worktree path. When the caller passes `worktreePath`,
@@ -224,9 +381,15 @@ app.post('/', migrationGuard, async (c) => {
         // the working branch from git itself — the body.workingBranch is ignored.
         let useReusedWorktree = false;
         let reusedDerivedBranch = null;
+        if (body.worktreePath) {
+            currentStep = 'inspect-worktree';
+            emitCreateProgress(creationId, currentStep);
+        }
         if (body.worktreePath) {
             if (!fs.existsSync(body.worktreePath)) {
-                return c.json({ error: `Worktree path does not exist: ${body.worktreePath}` }, 422);
+                const failure = `Worktree path does not exist: ${body.worktreePath}`;
+                emitCreateFailed(creationId, 'inspect-worktree', failure);
+                return c.json({ error: failure, step: 'inspect-worktree' }, 422);
             }
             try {
                 const commonDir = execFileSync('git', ['-C', body.worktreePath, 'rev-parse', '--git-common-dir'], {
@@ -234,25 +397,33 @@ app.post('/', migrationGuard, async (c) => {
                 }).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 failure = `Worktree '${body.worktreePath}' belongs to a different repository`;
+                    emitCreateFailed(creationId, 'inspect-worktree', failure);
+                    return c.json({ error: failure, step: 'inspect-worktree' }, 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);
+                    const failure = 'Worktree is in detached HEAD state and cannot be attached';
+                    emitCreateFailed(creationId, 'inspect-worktree', failure);
+                    return c.json({ error: failure, step: 'inspect-worktree' }, 422);
                 }
                 reusedDerivedBranch = branch;
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                return c.json({ error: `Failed to inspect worktree: ${message}` }, 422);
+                const failure = `Failed to inspect worktree: ${message}`;
+                emitCreateFailed(creationId, 'inspect-worktree', failure);
+                return c.json({ error: failure, step: 'inspect-worktree' }, 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);
+                const failure = 'This worktree is already attached to another Kōbō workspace';
+                emitCreateFailed(creationId, 'inspect-worktree', failure);
+                return c.json({ error: failure, step: 'inspect-worktree' }, 422);
             }
             useReusedWorktree = true;
         }
@@ -261,15 +432,21 @@ app.post('/', migrationGuard, async (c) => {
         // before createWorkspace and surface failures as 422.
         let notionContent = null;
         if (body.notionUrl) {
+            currentStep = 'extract-notion';
+            emitCreateProgress(creationId, currentStep);
             if (!settingsService.getGlobalSettings().notionEnabled) {
-                return c.json({ error: 'Notion integration is disabled in Settings' }, 403);
+                const failure = 'Notion integration is disabled in Settings';
+                emitCreateFailed(creationId, 'extract-notion', failure);
+                return c.json({ error: failure, step: 'extract-notion' }, 403);
             }
             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);
+                const failure = `Failed to extract Notion page: ${message}`;
+                emitCreateFailed(creationId, 'extract-notion', failure);
+                return c.json({ error: failure, step: 'extract-notion' }, 422);
             }
             const assigneeProperty = settingsService.getGlobalSettings().notionAssigneeProperty;
             if (assigneeProperty && body.notionUrl) {
@@ -286,15 +463,21 @@ app.post('/', migrationGuard, async (c) => {
         }
         let sentryContent = null;
         if (body.sentryUrl) {
+            currentStep = 'extract-sentry';
+            emitCreateProgress(creationId, currentStep);
             if (!settingsService.getGlobalSettings().sentryEnabled) {
-                return c.json({ error: 'Sentry integration is disabled in Settings' }, 403);
+                const failure = 'Sentry integration is disabled in Settings';
+                emitCreateFailed(creationId, 'extract-sentry', failure);
+                return c.json({ error: failure, step: 'extract-sentry' }, 403);
             }
             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);
+                const failure = `Failed to extract Sentry issue: ${message}`;
+                emitCreateFailed(creationId, 'extract-sentry', failure);
+                return c.json({ error: failure, step: 'extract-sentry' }, 422);
             }
             if (sentryContent && sentryContent.assignee.length === 0) {
                 const sentryUrl = body.sentryUrl;
@@ -358,6 +541,8 @@ app.post('/', migrationGuard, async (c) => {
         //      request — keeps the user's flow smooth at the cost of a longer
         //      branch name. The same hash is applied to BOTH the branch and the
         //      worktree path so they stay aligned.
+        currentStep = 'create-record';
+        emitCreateProgress(creationId, currentStep);
         let prospectiveWorktreePath;
         let workingBranchAdjusted = false;
         if (useReusedWorktree) {
@@ -377,7 +562,8 @@ app.post('/', migrationGuard, async (c) => {
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                return c.json({ error: message }, 409);
+                emitCreateFailed(creationId, 'create-record', message);
+                return c.json({ error: message, step: 'create-record' }, 409);
             }
         }
         let workspace = workspaceService.createWorkspace({
@@ -397,6 +583,7 @@ app.post('/', migrationGuard, async (c) => {
             engine: body.engine,
             ...(useReusedWorktree ? {} : { worktreesPath: globalSettings.worktreesPath }),
         });
+        createdWorkspace = workspace;
         // Enable auto-loop before starting the initial brainstorming session so
         // its model override is available when selecting that session's model.
         if (body.autoLoop === true) {
@@ -443,6 +630,8 @@ app.post('/', migrationGuard, async (c) => {
             const prefix = sentryContent.issueId ? `${sentryContent.issueId} | ` : '';
             workspace = workspaceService.updateWorkspaceName(workspace.id, `${prefix}${sentryContent.title}`);
         }
+        currentStep = 'create-tasks';
+        emitCreateProgress(creationId, currentStep);
         // Create tasks from extracted Notion data
         if (notionContent) {
             let sortOrder = 0;
@@ -493,6 +682,8 @@ app.post('/', migrationGuard, async (c) => {
                 }
             }
         }
+        currentStep = 'create-worktree';
+        emitCreateProgress(creationId, currentStep);
         // 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;
@@ -503,27 +694,24 @@ app.post('/', migrationGuard, async (c) => {
             try {
                 const created = worktreeService.createWorktree(body.projectPath, workingBranch, baseRef, globalSettings.worktreesPath, projectSlug);
                 worktreePath = created.worktreePath;
+                // Not an assumption: `createWorktree` reports which git command it ran.
+                // It falls back to attaching an existing branch, and deleting that one
+                // on rollback would destroy commits the user made before Kobo existed.
+                createdBranch = created.branchCreated;
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                // Roll back the half-created workspace: a failed worktree creation must NOT
-                // leave an orphan record behind. Best-effort cleanup of any partial worktree
-                // dir git may have produced, then delete the just-inserted workspace row.
-                try {
-                    worktreeService.removeWorktree(body.projectPath, prospectiveWorktreePath);
-                }
-                catch {
-                    // worktree may never have been registered — ignore
-                }
-                try {
-                    workspaceService.deleteWorkspace(workspace.id);
-                }
-                catch (delErr) {
-                    console.error('[workspaces] rollback deleteWorkspace failed:', delErr);
-                }
-                return c.json({ error: `Failed to create worktree: ${message}` }, 500);
+                // Roll back the half-created workspace through the SHARED demolition
+                // path — a second inline cleanup here would drift from it. The branch
+                // is not deleted: `createWorktree` failed, so we never created one.
+                const rollbackWarnings = await rollbackFailedCreation(workspace, { deleteLocalBranch: false });
+                const failure = `Failed to create worktree: ${message}`;
+                emitCreateFailed(creationId, 'create-worktree', failure);
+                return c.json({ error: failure, step: 'create-worktree', rollback: { done: true, warnings: rollbackWarnings } }, 500);
             }
         }
+        currentStep = 'write-conventions';
+        emitCreateProgress(creationId, currentStep);
         // Ensure Kobo-generated files are gitignored. Check both the root
         // .gitignore and .ai/.gitignore to avoid duplicate entries.
         try {
@@ -554,7 +742,10 @@ app.post('/', migrationGuard, async (c) => {
             }
         }
         catch (err) {
-            console.error('[workspaces] Failed to update .gitignore:', err);
+            logError('workspaces', 'Failed to update .gitignore', {
+                workspaceId: workspace.id,
+                error: err instanceof Error ? err.message : String(err),
+            });
         }
         // Write git conventions to the worktree if configured
         const effectiveSettings = settingsService.getEffectiveSettings(body.projectPath);
@@ -566,13 +757,23 @@ app.post('/', migrationGuard, async (c) => {
                 fs.writeFileSync(conventionsPath, effectiveSettings.gitConventions, 'utf-8');
             }
             catch (err) {
-                console.error('[workspaces] Failed to write .git-conventions.md:', err);
+                logError('workspaces', 'Failed to write .git-conventions.md', {
+                    workspaceId: workspace.id,
+                    error: err instanceof Error ? err.message : String(err),
+                });
             }
         }
         // The setup script runs LATER (after the brainstorm prompt is built and
         // persisted via setInitialPrompt). This guarantees the prompt survives a
         // setup-script crash and can be replayed by /:id/start.
         let setupScriptFailed = false;
+        // Captured, not swallowed: a failed engine start used to reach only the
+        // server console while the route still answered 201 "created". A
+        // half-created workspace lies to the user, so this now drives a full
+        // rollback below instead of merely flipping the status to 'error'.
+        let agentStartError = null;
+        currentStep = 'write-context-files';
+        emitCreateProgress(creationId, currentStep);
         // Save Notion content as markdown in worktree
         let notionFilePath = null;
         if (notionContent && body.notionUrl) {
@@ -618,7 +819,10 @@ app.post('/', migrationGuard, async (c) => {
                 fs.writeFileSync(notionFilePath, md, 'utf-8');
             }
             catch (err) {
-                console.error('[workspaces] Failed to save Notion content:', err);
+                logError('workspaces', 'Failed to save Notion content', {
+                    workspaceId: workspace.id,
+                    error: err instanceof Error ? err.message : String(err),
+                });
             }
         }
         // --- Sentry file + task (extraction already done before worktree creation) --
@@ -667,7 +871,10 @@ app.post('/', migrationGuard, async (c) => {
                 });
             }
             catch (err) {
-                console.error('[workspaces] Failed to save Sentry content:', err);
+                logError('workspaces', 'Failed to save Sentry content', {
+                    workspaceId: workspace.id,
+                    error: err instanceof Error ? err.message : String(err),
+                });
                 sentryFilePath = null;
             }
         }
@@ -693,6 +900,8 @@ app.post('/', migrationGuard, async (c) => {
         // VALID_TRANSITIONS contract intact (`created → extracting → brainstorming`
         // vs `created → brainstorming` when setup is skipped).
         {
+            currentStep = 'build-prompt';
+            emitCreateProgress(creationId, currentStep);
             // Resolve the per-feature initial-prompt templates with single-fallback
             // semantics: project || global is already handled inside getEffectiveSettings,
             // and a whitespace-only string acts as a user escape hatch (skip injection).
@@ -842,8 +1051,10 @@ Once the brainstorming + planning steps above are complete and you have a saved
             // leaves the workspace in `error` state with `initial_prompt` ready for
             // a retry via POST /:id/start. Skipped when reusing an existing worktree
             // (rerunning could be destructive — drop a curated node_modules, etc.).
-            const setupScriptConfigured = effectiveSettings.setupScript && !body.skipSetupScript && !useReusedWorktree;
+            setupScriptConfigured = Boolean(effectiveSettings.setupScript) && !body.skipSetupScript && !useReusedWorktree;
             if (setupScriptConfigured) {
+                currentStep = 'setup-script';
+                emitCreateProgress(creationId, currentStep);
                 workspaceService.updateWorkspaceStatus(workspace.id, 'extracting');
                 wsService.emit(workspace.id, 'setup:output', { text: '[kobo] Running setup script...' });
                 try {
@@ -856,9 +1067,10 @@ Once the brainstorming + planning steps above are complete and you have a saved
                     if (result.exitCode !== 0) {
                         workspaceService.updateWorkspaceStatus(workspace.id, 'error');
                         setupScriptFailed = true;
+                        emitCreateFailed(creationId, 'setup-script', `Setup script exited with code ${result.exitCode}`);
                     }
                     else {
-                        workspaceService.updateWorkspaceStatus(workspace.id, 'brainstorming');
+                        markBrainstormingBestEffort(workspace.id);
                     }
                 }
                 catch (err) {
@@ -866,19 +1078,28 @@ Once the brainstorming + planning steps above are complete and you have a saved
                     console.error(`[workspaces] Setup script error: ${message}`);
                     workspaceService.updateWorkspaceStatus(workspace.id, 'error');
                     setupScriptFailed = true;
+                    emitCreateFailed(creationId, 'setup-script', message);
                 }
             }
             else {
                 // No setup step → go straight from `created` to `brainstorming`.
-                workspaceService.updateWorkspaceStatus(workspace.id, 'brainstorming');
+                markBrainstormingBestEffort(workspace.id);
             }
             if (setupScriptFailed) {
                 wsService.emit(workspace.id, 'setup:output', {
                     text: '[kobo] Setup script failed — the agent was NOT started. Your initial prompt has been saved. ' +
                         'Fix the setup script (Settings → Scripts) and click Start to retry with the original prompt.',
                 });
+                // This path keeps its deliberate recovery flow (workspace stays in
+                // `error`, prompt persisted, 201 response) — nothing is undone here.
+                // The step is already named on the create-progress channel by the
+                // `emitCreateFailed(creationId, 'setup-script', …)` calls above, at
+                // the point of detection (exit code / thrown error), so the create
+                // page never shows a mute spinner on this path.
             }
             else {
+                currentStep = 'start-agent';
+                emitCreateProgress(creationId, currentStep);
                 try {
                     // The brainstorming session (this very first startAgent call) uses
                     // brainstormModel when the workspace was created with auto-loop
@@ -906,15 +1127,35 @@ Once the brainstorming + planning steps above are complete and you have a saved
                 catch (err) {
                     const message = err instanceof Error ? err.message : String(err);
                     console.error(`[workspaces] Failed to start agent: ${message}`);
-                    try {
-                        workspaceService.updateWorkspaceStatus(workspace.id, 'error');
-                    }
-                    catch {
-                        /* already logged */
-                    }
+                    agentStartError = message;
                 }
             }
         }
+        // A workspace whose agent never started is a half-created object, and a
+        // half-created object is exactly what lies to the user. Undo everything
+        // and report the step that broke.
+        if (agentStartError) {
+            emitCreateProgress(creationId, 'rollback');
+            // A worktree the user brought is not ours to remove, and neither is the
+            // branch it was already sitting on. `deleteWorkspaceWithSideEffects`
+            // already guards the worktree via `worktreeOwned`; the branch flag is
+            // ours to set.
+            const rollbackWarnings = await rollbackFailedCreation(workspace, {
+                deleteLocalBranch: !useReusedWorktree,
+            });
+            // The setup script has already run by this point — see the caveat's own
+            // comment for what that rollback cannot reach.
+            const setupCaveat = setupScriptConfigured ? SETUP_SCRIPT_ROLLBACK_CAVEAT : '';
+            const failure = `Failed to start the agent: ${agentStartError}. The workspace, its worktree and its branch were removed.${setupCaveat}`;
+            emitCreateFailed(creationId, 'start-agent', failure);
+            return c.json({ error: failure, step: 'start-agent', rollback: { done: true, warnings: rollbackWarnings } }, 500);
+        }
+        // The agent is running. From here the workspace is a live object, not a
+        // half-created one, so it stops being the rollback's business: dropping the
+        // handle means a later throw (the read below, a header, a status beat)
+        // returns 500 without demolishing a worktree that already has an agent
+        // working in it. Failures before this line still roll back in full.
+        createdWorkspace = null;
         // Return created workspace with tasks
         const workspaceWithTasks = workspaceService.getWorkspaceWithTasks(workspace.id);
         if (workingBranchAdjusted) {
@@ -926,11 +1167,49 @@ Once the brainstorming + planning steps above are complete and you have a saved
         if (usedLocalFallback) {
             c.header('X-Kobo-Source-Fallback', 'local');
         }
+        // The `done` beat means "the sequence completed the way the user expects" —
+        // NOT merely "the HTTP response is about to return 201". A workspace whose
+        // setup script failed still gets a 201 (its record exists, in `error`
+        // status, ready for retry via POST /:id/start) because that path has a
+        // deliberate recovery flow — but the create-progress channel must not
+        // claim success on it: the corresponding emitCreateFailed above already
+        // named the real failure. A failed agent start never reaches this line at
+        // all (see the rollback branch above).
+        if (!setupScriptFailed) {
+            currentStep = 'done';
+            emitCreateProgress(creationId, currentStep);
+        }
         return c.json(workspaceWithTasks, 201);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return c.json({ error: message }, 500);
+        // Anything past `create-record` left a row behind. Leaving it there is a
+        // half-created workspace whose existence lies to the user — and the client
+        // already tells them "the server undoes everything it created". Make that
+        // sentence true for every step, not only the two that had their own
+        // handler. Best-effort: the rollback never throws and never becomes the
+        // reported error.
+        if (createdWorkspace) {
+            emitCreateProgress(creationId, 'rollback');
+            const rollbackWarnings = await rollbackFailedCreation(createdWorkspace, { deleteLocalBranch: createdBranch });
+            logError('workspaces', 'Rolled back a creation that failed outside any per-step handler', {
+                workspaceId: createdWorkspace.id,
+                step: currentStep,
+                error: message,
+                ...(rollbackWarnings.length > 0 ? { rollbackWarnings } : {}),
+            });
+            // Say exactly what was undone — a claim of "everything" would be the
+            // very kind of comfortable lie this route is being fixed for.
+            const removed = createdBranch
+                ? ' The workspace, its worktree and its branch were removed.'
+                : ' The half-created workspace was removed.';
+            const cause = message.endsWith('.') ? message : `${message}.`;
+            const failure = `${cause}${removed}${setupScriptConfigured ? SETUP_SCRIPT_ROLLBACK_CAVEAT : ''}`;
+            emitCreateFailed(creationId, currentStep, failure);
+            return c.json({ error: failure, step: currentStep, rollback: { done: true, warnings: rollbackWarnings } }, 500);
+        }
+        emitCreateFailed(creationId, currentStep, message);
+        return c.json({ error: message, step: currentStep }, 500);
     }
 });
 // POST /api/workspaces/:id/sessions — create a new idle agent session
@@ -994,6 +1273,9 @@ app.get('/info', (c) => {
             workspaces: workspaceService.listWorkspaces(false),
             prSnapshots: getAllPrSnapshots(),
             gitStats: getAllGitStats(),
+            // In-memory truth, not the `status` column: a workspace missing from
+            // this map has no agent, whatever its status claims.
+            agentLiveness: agentManager.getAllAgentLiveness(),
         });
     }
     catch (err) {
@@ -1419,7 +1701,15 @@ app.delete('/:id/events/:eventId', (c) => {
             return c.json({ error: `Workspace '${workspaceId}' not found` }, 404);
         }
         const db = getDb();
+        // Capture the session BEFORE deleting: since v36 there is no AFTER DELETE
+        // trigger, so the metrics of that session must be recomputed once, here.
+        const row = db
+            .prepare('SELECT session_id FROM ws_events WHERE id = ? AND workspace_id = ?')
+            .get(eventId, workspaceId);
         db.prepare('DELETE FROM ws_events WHERE id = ? AND workspace_id = ?').run(eventId, workspaceId);
+        if (row?.session_id) {
+            workspaceService.recomputeSessionMetrics(workspaceId, row.session_id);
+        }
         return c.json({ ok: true });
     }
     catch (err) {
@@ -1942,7 +2232,7 @@ app.get('/:id', (c) => {
         if (!workspace) {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
-        return c.json(workspace);
+        return c.json({ ...workspace, agentLiveness: agentManager.getAgentLiveness(id) });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -2244,14 +2534,15 @@ app.post('/:id/run-setup-script', async (c) => {
         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
+        // Stop the running agent before re-running the setup script — the script
+        // rewrites the worktree the agent may still be writing to.
         try {
             if (agentManager.getAgentStatus(id)) {
-                agentManager.stopAgent(id);
+                await agentManager.stopAgentAndWait(id);
             }
         }
-        catch {
-            /* best-effort — agent may already be stopped */
+        catch (err) {
+            console.error(`[workspaces] stopAgentAndWait before setup script failed for '${id}':`, err);
         }
         const effectiveSettings = settingsService.getEffectiveSettings(workspace.projectPath);
         if (!effectiveSettings.setupScript) {
@@ -2295,10 +2586,10 @@ app.post('/:id/archive', migrationGuard, async (c) => {
             return c.json({ error: 'Already archived' }, 400);
         }
         try {
-            agentManager.stopAgent(id);
+            await agentManager.stopAgentAndWait(id);
         }
-        catch {
-            // Agent may not be running — ignore
+        catch (err) {
+            console.error(`[workspaces] stopAgentAndWait during archive failed for '${id}':`, err);
         }
         try {
             await devServerService.stopDevServer(id);
@@ -2377,12 +2668,14 @@ app.post('/:id/unarchive', migrationGuard, (c) => {
 // rather than thrown, so a bulk delete never aborts mid-batch. Returns the
 // list of user-facing warning messages (empty when everything was clean).
 async function deleteWorkspaceWithSideEffects(workspace, opts) {
-    // Stop agent if running (best-effort)
+    // Stop the agent and WAIT for it to die. `git worktree remove --force` runs
+    // a few lines below: firing and forgetting here pulled the directory from
+    // under an agent still writing to it, destroying uncommitted work.
     try {
-        agentManager.stopAgent(workspace.id);
+        await agentManager.stopAgentAndWait(workspace.id);
     }
-    catch {
-        // Agent may not be running — ignore
+    catch (err) {
+        console.error(`[workspaces] stopAgentAndWait during delete failed for '${workspace.name}':`, err);
     }
     // Stop dev server if it was running. The processSpawn would otherwise
     // outlive the workspace (and keep its port + docker containers alive).
@@ -2412,7 +2705,7 @@ async function deleteWorkspaceWithSideEffects(workspace, opts) {
     }
     else if (workspace.worktreeOwned) {
         try {
-            worktreeService.removeWorktree(workspace.projectPath, worktreePath);
+            await worktreeService.removeWorktree(workspace.projectPath, worktreePath);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -2549,12 +2842,12 @@ app.post('/:id/start', migrationGuard, async (c) => {
         const prompt = body.prompt ?? pendingInitialPrompt ?? 'Continue the previous task where you left off.';
         const agentSessionId = body.agentSessionId;
         const resume = body.resume === true;
-        // Stop existing agent if running
+        // Stop the existing agent and wait: a fresh one starts right below.
         try {
-            agentManager.stopAgent(id);
+            await agentManager.stopAgentAndWait(id);
         }
-        catch {
-            // Agent may not be running — ignore
+        catch (err) {
+            console.error(`[workspaces] stopAgentAndWait before start failed for '${id}':`, err);
         }
         const worktreePath = workspace.worktreePath;
         const agent = agentManager.startAgent(id, worktreePath, prompt, workspace.model, resume, workspace.agentPermissionMode, agentSessionId, workspace.reasoningEffort);
@@ -2864,8 +3157,10 @@ app.post('/:id/rename-branch', async (c) => {
         if (!newName) {
             return c.json({ error: 'newName is required' }, 400);
         }
-        if (!/^[A-Za-z0-9/_\-.]+$/.test(newName)) {
-            return c.json({ error: 'Invalid branch name (only letters, digits, /, _, -, . allowed)' }, 400);
+        if (!gitOps.isValidBranchName(newName)) {
+            return c.json({
+                error: 'Invalid branch name. It must start with a letter or a digit and may then contain letters, digits, /, _, - and . — no leading dash, no "..", no trailing "/", "." or ".lock".',
+            }, 400);
         }
         const workspace = workspaceService.getWorkspace(id);
         if (!workspace) {
@@ -3419,7 +3714,17 @@ app.post('/:id/cancel-source-change', async (c) => {
         const workspace = workspaceService.getWorkspace(id);
         if (!workspace)
             return c.json({ error: `Workspace '${id}' not found` }, 404);
-        const backups = gitOps.listBackupBranches(workspace.worktreePath, workspace.workingBranch);
+        // "No backup exists" and "I could not find out" are different answers.
+        // Conflating them told the user restoration was impossible while the
+        // backup branch was on disk, closing the only rollback path there is.
+        let backups;
+        try {
+            backups = gitOps.listBackupBranches(workspace.worktreePath, workspace.workingBranch);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return c.json({ error: `Cannot list backup branches: ${message}`, code: 'backup_list_failed' }, 500);
+        }
         if (backups.length === 0) {
             return c.json({ error: 'No backup branch found — cannot auto-restore', code: 'no_backup' }, 409);
         }
@@ -3625,13 +3930,13 @@ app.post('/:id/start-review', async (c) => {
         let messageSent = false;
         let emitSessionId;
         if (newSession) {
-            // Stop current agent (best-effort) then start fresh.
+            // Stop current agent, wait for it, then start fresh.
             try {
-                agentManager.stopAgent(workspace.id);
+                await agentManager.stopAgentAndWait(workspace.id);
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
-                console.error(`[start-review] stopAgent failed (continuing): ${msg}`);
+                console.error(`[start-review] stopAgentAndWait failed (continuing): ${msg}`);
             }
             try {
                 const agent = agentManager.startAgent(workspace.id, worktreePath, rendered, workspace.model, false /* resume */, workspace.agentPermissionMode, undefined, workspace.reasoningEffort);
@@ -3807,7 +4112,7 @@ app.post('/:id/mark-read', (c) => {
     }
 });
 // POST /api/workspaces/:id/stop — stop agent
-app.post('/:id/stop', migrationGuard, (c) => {
+app.post('/:id/stop', migrationGuard, async (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
@@ -3815,10 +4120,12 @@ app.post('/:id/stop', migrationGuard, (c) => {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
         try {
-            agentManager.stopAgent(id);
+            // The response says "stopped": make that true before returning.
+            await agentManager.stopAgentAndWait(id);
         }
-        catch {
+        catch (err) {
             // Agent may not be tracked (e.g. server restarted) — just update status
+            console.error(`[workspaces] stopAgentAndWait on manual stop failed for '${id}':`, err);
         }
         // Always transition to idle so the UI reflects the stopped state
         try {