@loicngr/kobo 2.1.2 → 2.1.5

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to Kōbō are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/). Each release is an `## <version>`
 section — the in-app "What's new" dialog reads this file.
 
+## 2.1.5
+
+- fix(workspace): improve reliability and git controls
+
+## 2.1.4
+
+- chore(deps): update server client and pwa packages
+
+## 2.1.3
+
+- fix(subagents): reliable lifecycle tracking and a stop button
+
 ## 2.1.2
 
 - fix: read-only returning reviews, resumed-turn stdin, feed and tag filter

package/CONFIGURATION.md

@@ -751,9 +751,17 @@ both global (the database is single):
 | Events always kept per workspace | `0` | The most recent events of each workspace survive whatever their age. Set it (5000 is a good starting point) at the same time you enable retention, so an old but still-open workspace keeps a readable history. |
 
 The prune runs **at server startup and every 24 hours** while the backend stays
-running. Each pass reads the current settings and deletes in batches of 5,000
-rows. When enough pages have been freed, a `VACUUM` returns the space to the
-filesystem.
+running. Each pass reads the current settings, calculates the protected workspace
+tails once, and deletes in batches of 500 rows on a dedicated worker. Preview
+counts also run on that worker, so maintenance does not block HTTP or agent
+event handling. Shutdown waits for the worker to finish its current batch and
+reconcile affected metrics before closing the database.
+
+Freed database pages are reused for new events. Live maintenance performs a
+non-blocking WAL checkpoint and deliberately does not run a full `VACUUM`, which
+would hold SQLite's writer lock and interrupt live agents. To return database
+file space to the filesystem immediately, stop Kōbō and perform an explicit
+offline SQLite `VACUUM` after making a backup.
 
 **What it deletes:** eligible rows of `ws_events` — the recorded agent output.
 Affected session metrics and the derived search index are reconciled with the

package/dist/server/index.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { serve } from '@hono/node-server';
 import { Hono } from 'hono';
-import WebSocket, { WebSocketServer } from 'ws';
+import { WebSocketServer } from 'ws';
 import { closeDb, getDb } from './db/index.js';
 import { getPendingMigrations, runMigrations } from './db/migrations.js';
 import { hostCheckMiddleware } from './middleware/host-check-middleware.js';
@@ -49,14 +49,16 @@ import { startSearchIndex, stopSearchIndex } from './services/search-service.js'
 import { reconcileSessionHandoffs } from './services/session-handoff-service.js';
 import { getGlobalSettings, updateNetworkAccessSettings } from './services/settings-service.js';
 import { reloadDefaultTemplates } from './services/templates-service.js';
-import { createTerminal, destroyAllTerminals, getTerminal } from './services/terminal-service.js';
+import { destroyAllTerminals } from './services/terminal-service.js';
+import { handleTerminalConnection } from './services/terminal-websocket-service.js';
 import { startUpdateChecker, stopUpdateChecker } from './services/update-check-service.js';
 import { startUsagePoller, stopUsagePoller } from './services/usage/index.js';
 import * as wakeupService from './services/wakeup-service.js';
 import { handleConnection, setMessageHandler } from './services/websocket-service.js';
 import { deliverWorkspaceMessage } from './services/workspace-message-service.js';
 import { getWorkspace } from './services/workspace-service.js';
-import { pruneWsEvents, resolveRetentionConfig } from './services/ws-events-retention-service.js';
+import { resolveRetentionConfig } from './services/ws-events-retention-service.js';
+import { runWsEventsRetention, stopWsEventsRetention } from './services/ws-events-retention-worker-service.js';
 import { getChangelogPath, getClientSpaPath, getDbPath, getKoboHome, getPackageVersion, resolveSpaFile, } from './utils/paths.js';
 import { formatStartupBanner, readStartupNotes, startStartupSpinner, startupDebug } from './utils/startup-display.js';
 startupDebug(`[kobo] Kōbō home: ${getKoboHome()}`);
@@ -87,13 +89,13 @@ startSearchIndex();
 // conversation on the next upgrade, which is precisely why the UI shows a
 // count and asks first.
 // Best-effort — a failure must never block boot.
-function runRetentionPass(context) {
+async function runRetentionPass(context) {
     try {
         const retentionConfig = resolveRetentionConfig(getGlobalSettings());
         if (retentionConfig.retentionDays <= 0)
             return;
         const retentionStartedAt = Date.now();
-        const retention = pruneWsEvents(db, retentionConfig);
+        const retention = await runWsEventsRetention(retentionConfig);
         if (retention.deleted > 0 || retention.vacuumed) {
             console.log(`[kobo] Event retention ${context} (${retentionConfig.retentionDays} d, keeping ${retentionConfig.keepPerWorkspace}/workspace): ` +
                 `${retention.deleted} agent event(s) permanently deleted, ` +
@@ -106,12 +108,12 @@ function runRetentionPass(context) {
         console.error('[kobo] Event retention failed (continuing):', err);
     }
 }
-runRetentionPass('at boot');
+void runRetentionPass('at boot');
 // Kōbō is a daemon people leave running for weeks, and `emit` writes a row per
 // agent event. Running the pass only at boot meant a window the user enabled
 // was not applied again until the next restart.
 const RETENTION_INTERVAL_MS = 24 * 60 * 60 * 1000;
-const retentionTimer = setInterval(() => runRetentionPass('daily'), RETENTION_INTERVAL_MS);
+const retentionTimer = setInterval(() => void runRetentionPass('daily'), RETENTION_INTERVAL_MS);
 retentionTimer.unref?.();
 // Check on boot and hourly so servers running longer than a day keep backing up.
 const dailyBackupScheduler = startDailyDbBackupScheduler(async () => {
@@ -278,87 +280,7 @@ wss.on('connection', (ws) => {
 });
 // Wire terminal WebSocket connections
 terminalWss.on('connection', (ws, workspaceId) => {
-    let currentPty = getTerminal(workspaceId);
-    let dataDisposable = null;
-    let exitDisposable = null;
-    function attachListeners(ptyInstance) {
-        // Dispose previous listeners to avoid stacking on reconnect
-        dataDisposable?.dispose();
-        exitDisposable?.dispose();
-        dataDisposable = ptyInstance.onData((output) => {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(Buffer.from(output), { binary: true });
-            }
-        });
-        exitDisposable = ptyInstance.onExit(({ exitCode }) => {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(JSON.stringify({ type: 'exited', code: exitCode }));
-                ws.close();
-            }
-        });
-    }
-    ws.on('close', () => {
-        dataDisposable?.dispose();
-        exitDisposable?.dispose();
-        dataDisposable = null;
-        exitDisposable = null;
-    });
-    ws.on('error', (err) => {
-        console.error(`[terminal] WebSocket error for workspace ${workspaceId}:`, err);
-    });
-    ws.on('message', (data, isBinary) => {
-        if (isBinary) {
-            if (currentPty) {
-                currentPty.write(data.toString());
-            }
-            return;
-        }
-        let msg;
-        try {
-            msg = JSON.parse(data.toString());
-        }
-        catch {
-            return; // Invalid JSON — ignore
-        }
-        if (msg.type === 'create') {
-            if (!currentPty) {
-                const workspace = getWorkspace(workspaceId);
-                if (!workspace) {
-                    ws.send(JSON.stringify({ type: 'error', message: 'Workspace not found' }));
-                    return;
-                }
-                if (workspace.archivedAt) {
-                    ws.send(JSON.stringify({ type: 'error', message: 'Workspace is archived' }));
-                    return;
-                }
-                const cwd = workspace.worktreePath;
-                try {
-                    currentPty = createTerminal(workspaceId, cwd);
-                }
-                catch (err) {
-                    const message = err instanceof Error ? err.message : String(err);
-                    ws.send(JSON.stringify({ type: 'error', message }));
-                    return;
-                }
-            }
-            attachListeners(currentPty);
-            ws.send(JSON.stringify({ type: 'ready' }));
-            return;
-        }
-        if (msg.type === 'resize' && msg.cols && msg.rows) {
-            if (currentPty) {
-                const cols = Math.max(1, Math.floor(msg.cols));
-                const rows = Math.max(1, Math.floor(msg.rows));
-                try {
-                    currentPty.resize(cols, rows);
-                }
-                catch (err) {
-                    console.error(`[terminal] resize failed for workspace ${workspaceId}:`, err);
-                }
-            }
-            return;
-        }
-    });
+    handleTerminalConnection(ws, workspaceId, () => isShuttingDown);
 });
 // Wire websocket-service message handler to the agent orchestrator
 setMessageHandler(async (type, payload) => {
@@ -411,6 +333,10 @@ setMessageHandler(async (type, payload) => {
 });
 // Handle WebSocket upgrade requests on /ws path
 server.on('upgrade', (request, socket, head) => {
+    if (isShuttingDown) {
+        socket.destroy();
+        return;
+    }
     const { pathname } = new URL(request.url ?? '/', `http://localhost:${PORT}`);
     const wsGlobal = getGlobalSettings();
     // WebSockets are exempt from the same-origin policy and send no preflight,
@@ -495,7 +421,7 @@ async function gracefulShutdown(signal, exitCode = 0) {
     for (const client of terminalWss.clients)
         client.close(1001, 'Server shutting down');
     try {
-        destroyAllTerminals();
+        await destroyAllTerminals();
         console.log('[kobo] Terminals killed');
     }
     catch {
@@ -547,8 +473,15 @@ async function gracefulShutdown(signal, exitCode = 0) {
     }
     finally {
         try {
-            await stopSearchIndex();
-            await dailyBackupScheduler.stop();
+            const stopped = await Promise.allSettled([
+                stopWsEventsRetention(),
+                stopSearchIndex(),
+                dailyBackupScheduler.stop(),
+            ]);
+            for (const result of stopped) {
+                if (result.status === 'rejected')
+                    console.error('[kobo] Background service shutdown failed:', result.reason);
+            }
             closeDb();
             console.log('[kobo] Database closed');
         }

package/dist/server/routes/git.js

@@ -1,18 +1,17 @@
 import { Hono } from 'hono';
 import { getDb } from '../db/index.js';
 import { listOrphanWorktrees } from '../services/worktree-service.js';
-import { listBranches, listRemoteBranches, listWorktreeFiles } from '../utils/git-ops.js';
+import { listBranchesAsync, listRemoteBranchesAsync, listWorktreeFilesAsync } from '../utils/git-ops.js';
 /** Hono sub-router for git-related endpoints (branch listing). */
 const app = new Hono();
 // GET /api/git/branches?path=<repoPath> — list branches for a repo
-app.get('/branches', (c) => {
+app.get('/branches', async (c) => {
     try {
         const repoPath = c.req.query('path');
         if (!repoPath) {
             return c.json({ error: 'Missing required query parameter: path' }, 400);
         }
-        const local = listBranches(repoPath);
-        const remote = listRemoteBranches(repoPath);
+        const [local, remote] = await Promise.all([listBranchesAsync(repoPath), listRemoteBranchesAsync(repoPath)]);
         return c.json({ local, remote });
     }
     catch (err) {
@@ -20,12 +19,12 @@ app.get('/branches', (c) => {
         return c.json({ error: message }, 500);
     }
 });
-/** Hard ceiling on the worktree listing. `listWorktreeFiles` already truncates
+/** Hard ceiling on the worktree listing. `listWorktreeFilesAsync` already truncates
  *  at this value; exposing it lets a caller ask for LESS, never for more. */
 const MAX_WORKTREE_FILES = 5000;
 // GET /api/git/files?path=<worktreePath>&limit=<n> — list a worktree's files
 // (tracked + untracked-but-not-ignored) for the chat's `@file` autocomplete.
-app.get('/files', (c) => {
+app.get('/files', async (c) => {
     try {
         const repoPath = c.req.query('path');
         if (!repoPath) {
@@ -33,7 +32,7 @@ app.get('/files', (c) => {
         }
         const requested = Number.parseInt(c.req.query('limit') ?? '', 10);
         const limit = Number.isFinite(requested) && requested > 0 ? Math.min(requested, MAX_WORKTREE_FILES) : MAX_WORKTREE_FILES;
-        return c.json({ files: listWorktreeFiles(repoPath, limit) });
+        return c.json({ files: await listWorktreeFilesAsync(repoPath, limit) });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/dist/server/routes/settings.js

@@ -11,8 +11,8 @@ import { DEFAULT_CHANGE_SOURCE_BRANCH_SCRIPT } from '../services/settings-defaul
 import * as settingsService from '../services/settings-service.js';
 import { DEFAULT_CI_FIX_PROMPT_TEMPLATE, DEFAULT_FINALIZATION_PROMPT, DEFAULT_GIT_CONVENTIONS, DEFAULT_PR_PROMPT_TEMPLATE, } from '../services/settings-service.js';
 import { getSuitePrompts } from '../services/skill-suite-prompts.js';
-import { listTemplates, replaceAllTemplates } from '../services/templates-service.js';
-import { countPrunableWsEvents } from '../services/ws-events-retention-service.js';
+import { listTemplates, replaceAllTemplates, validateTemplatesForReplacement } from '../services/templates-service.js';
+import { previewWsEventsRetention } from '../services/ws-events-retention-worker-service.js';
 /** Hono sub-router for global and per-project settings CRUD. */
 const app = new Hono();
 // GET /api/settings — return full settings, credentials masked
@@ -67,17 +67,15 @@ app.get('/defaults', (c) => {
 // the confirmation dialog: enabling retention on a year-old database destroys
 // months of conversation in one go, and the user is entitled to the number
 // before agreeing to it.
-app.get('/ws-events-retention-preview', (c) => {
+app.get('/ws-events-retention-preview', async (c) => {
     try {
         const days = Number.parseInt(c.req.query('days') ?? '', 10);
         const keep = Number.parseInt(c.req.query('keep') ?? '', 10);
         if (!Number.isInteger(days) || days < 0 || !Number.isInteger(keep) || keep < 0) {
             return c.json({ error: 'days and keep must be non-negative integers' }, 400);
         }
-        const db = getDb();
-        const total = db.prepare('SELECT COUNT(*) AS c FROM ws_events').get().c;
-        const deletable = countPrunableWsEvents(db, { retentionDays: days, keepPerWorkspace: keep });
-        return c.json({ deletable, total });
+        const preview = await previewWsEventsRetention({ retentionDays: days, keepPerWorkspace: keep });
+        return c.json(preview);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -252,11 +250,23 @@ app.get('/export', (c) => {
 app.post('/import', async (c) => {
     try {
         const body = (await c.req.json());
-        // Validate settings first — throws on malformed payload before we touch disk.
+        // Validate templates before settings import writes anything. An invalid
+        // row must not leave an otherwise rejected bundle partially applied.
+        let validatedTemplates;
+        if (body?.templates !== undefined) {
+            try {
+                validatedTemplates = validateTemplatesForReplacement(body.templates);
+            }
+            catch (error) {
+                return c.json({ error: error instanceof Error ? error.message : String(error) }, 400);
+            }
+        }
+        // Settings validates its section before writing. Each file is replaced
+        // atomically; this is not a transaction spanning the two files.
         settingsService.importConfigBundle(body);
-        if (body.templates !== undefined) {
-            // Accept missing templates (backward-compatible). Otherwise validate and replace.
-            replaceAllTemplates(body.templates);
+        if (validatedTemplates !== undefined) {
+            // Accept missing templates for backward-compatible bundles.
+            replaceAllTemplates(validatedTemplates);
         }
         return c.json({ ok: true });
     }

package/dist/server/routes/workspaces.js

@@ -6,7 +6,7 @@ import { getSearchIndexStatus, searchEvents } from '../services/search-service.j
 import { createSessionHandoff, decideSessionHandoff, getCurrentSessionHandoff, SessionHandoffError, submitSessionHandoff, waitForSessionHandoff, } from '../services/session-handoff-service.js';
 import { AgentStopError, assertAgentStopped } from '../utils/agent-stop-result.js';
 import { withGitRepoLock } from '../utils/git-repo-lock.js';
-import { isWorkspaceLifecycleBusy, workspaceLifecycleReason } from '../utils/workspace-lifecycle-guard.js';
+import { assertWorkspaceLifecycleAvailable, isWorkspaceLifecycleBusy, workspaceLifecycleReason, } from '../utils/workspace-lifecycle-guard.js';
 import autoLoopMessagesRoutes from './auto-loop-messages.js';
 const execFileAsync = promisify(execFileCb);
 import fs from 'node:fs';
@@ -73,7 +73,11 @@ function realPathOrResolved(p) {
     }
 }
 function workspaceErrorStatus(err) {
-    return err instanceof AgentStopError || err instanceof WorkspaceLifecycleBusyError ? 409 : 500;
+    return err instanceof AgentStopError ||
+        err instanceof WorkspaceLifecycleBusyError ||
+        err instanceof terminalService.TerminalStopError
+        ? 409
+        : 500;
 }
 /** Hono sub-router for workspace CRUD, tasks, agents, Git and PR creation. */
 const app = new Hono();
@@ -381,7 +385,7 @@ app.post('/:id/engine-handoff-preview', migrationGuard, async (c) => {
         const engine = listEngines().find((item) => item.id === body.engine);
         if (!engine)
             return c.json({ error: `Unknown engine '${body.engine ?? ''}'` }, 400);
-        return c.json({ handoff: buildEngineHandoff(workspace, workspace.engine, engine.id) });
+        return c.json({ handoff: await buildEngineHandoff(workspace, workspace.engine, engine.id) });
     }
     catch (err) {
         return c.json({ error: err instanceof Error ? err.message : 'Failed to build engine handoff' }, 500);
@@ -414,7 +418,7 @@ app.post('/:id/switch-engine', migrationGuard, async (c) => {
         const effort = typeof body.reasoningEffort === 'string' ? body.reasoningEffort : 'auto';
         const handoff = typeof body.handoff === 'string' && body.handoff.trim()
             ? body.handoff.trim().slice(0, 30_000)
-            : buildEngineHandoff(workspace, workspace.engine, body.engine);
+            : await buildEngineHandoff(workspace, workspace.engine, body.engine);
         if (workspaceService.getWorkspace(workspace.id)?.status === 'compacting') {
             return c.json({
                 code: 'compacting',
@@ -1914,13 +1918,19 @@ app.post('/:id/pending-wakeup', async (c) => {
         if (rawMode !== 'fresh' && rawMode !== 'resume') {
             return c.json({ error: "mode must be 'fresh' or 'resume'" }, 400);
         }
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace)
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        if (workspace.archivedAt || workspace.worktreePurgedAt) {
+            return c.json({ error: 'Restore the workspace before scheduling a wakeup' }, 409);
+        }
+        assertWorkspaceLifecycleAvailable(id);
         // 'resume' pins the active session so the wakeup resumes that conversation;
         // 'fresh' (default) — or 'resume' with no active session — leaves it unpinned
         // so the wakeup fires a brand-new session running `prompt`. This is what makes
         // manual scheduling on an idle workspace possible (no more hard 409).
         const agentSessionId = rawMode === 'resume' ? (agentManager.getActiveSessionId(id) ?? undefined) : undefined;
-        wakeupService.schedule(id, delaySeconds, prompt, reason, agentSessionId);
-        const pending = wakeupService.getPending(id);
+        const pending = wakeupService.schedule(id, delaySeconds, prompt, reason, agentSessionId);
         return c.json({ ok: true, pending });
     }
     catch (err) {
@@ -3018,12 +3028,7 @@ app.post('/:id/archive', migrationGuard, async (c) => {
             console.error(`[workspaces] stopDevServer during archive failed: ${message}`);
             throw err;
         }
-        try {
-            terminalService.destroyTerminal(id);
-        }
-        catch {
-            // Terminal may not exist — ignore
-        }
+        await terminalService.destroyTerminal(id);
         const updated = workspaceService.archiveWorkspace(id);
         wsService.emitEphemeral(id, 'workspace:archived', { workspace: updated });
         // Run the project's archive script (best-effort — never blocks the archive).
@@ -3140,12 +3145,7 @@ async function deleteWorkspaceWithSideEffectsUnlocked(workspace, opts) {
         console.error(`[workspaces] stopDevServer during delete failed for '${workspace.name}':`, err);
         throw err;
     }
-    try {
-        terminalService.destroyTerminal(workspace.id);
-    }
-    catch {
-        // Terminal may not exist — ignore
-    }
+    await terminalService.destroyTerminal(workspace.id);
     // Collected best-effort warnings: the DB deletion always proceeds, but
     // side-effects (worktree, local/remote branches) can fail independently.
     // We surface a user-friendly message per failure so the UI can show a
@@ -3178,7 +3178,7 @@ async function deleteWorkspaceWithSideEffectsUnlocked(workspace, opts) {
     // Delete local branch if requested
     if (opts.deleteLocalBranch) {
         try {
-            gitOps.deleteLocalBranch(workspace.projectPath, workspace.workingBranch);
+            await gitOps.deleteLocalBranchAsync(workspace.projectPath, workspace.workingBranch);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -3191,7 +3191,7 @@ async function deleteWorkspaceWithSideEffectsUnlocked(workspace, opts) {
     // Delete remote branch if requested
     if (opts.deleteRemoteBranch) {
         try {
-            gitOps.deleteRemoteBranch(workspace.projectPath, workspace.workingBranch);
+            await gitOps.deleteRemoteBranchAsync(workspace.projectPath, workspace.workingBranch);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -3405,7 +3405,7 @@ app.get('/:id/diff', async (c) => {
             if (!from || !to) {
                 return c.json({ error: 'mode=commits requires from and to query params' }, 400);
             }
-            if (!gitOps.commitExists(worktreePath, to)) {
+            if (!(await gitOps.commitExistsAsync(worktreePath, to))) {
                 return c.json({ error: `Invalid commit ref '${to}'` }, 400);
             }
             // `to` is strict (400 above). `from` is intentionally lenient: any ref it
@@ -3413,8 +3413,8 @@ app.get('/:id/diff', async (c) => {
             // only unresolved `from` the UI ever sends is a root commit's `<sha>^`
             // (single-commit diff of the first commit); the compare dialog otherwise
             // only offers refs that resolve.
-            const fromRef = gitOps.commitExists(worktreePath, from) ? from : gitOps.EMPTY_TREE_SHA;
-            const files = gitOps.getChangedFilesBetween(worktreePath, fromRef, to);
+            const fromRef = (await gitOps.commitExistsAsync(worktreePath, from)) ? from : gitOps.EMPTY_TREE_SHA;
+            const files = await gitOps.getChangedFilesBetweenAsync(worktreePath, fromRef, to);
             c.header('Cache-Control', 'no-store');
             return c.json({ files, mode: 'commits', from: fromRef, to });
         }
@@ -3426,8 +3426,8 @@ app.get('/:id/diff', async (c) => {
             await gitOps.fetchSourceBranchAsync(worktreePath, workspace.sourceBranch);
         }
         const files = mode === 'unpushed'
-            ? gitOps.getUnpushedChangedFiles(worktreePath, workspace.workingBranch)
-            : gitOps.getChangedFiles(worktreePath, workspace.sourceBranch, includeUntracked);
+            ? await gitOps.getUnpushedChangedFilesAsync(worktreePath, workspace.workingBranch)
+            : await gitOps.getChangedFilesAsync(worktreePath, workspace.sourceBranch, includeUntracked);
         c.header('Cache-Control', 'no-store');
         return c.json({
             files,
@@ -3446,7 +3446,7 @@ app.get('/:id/diff', async (c) => {
 //  - `branch`   → sourceBranch
 //  - `unpushed` → origin/<workingBranch>
 // `modified` is always the current worktree content.
-app.get('/:id/diff-file', (c) => {
+app.get('/:id/diff-file', async (c) => {
     try {
         const id = c.req.param('id');
         const filePath = c.req.query('path');
@@ -3472,14 +3472,16 @@ app.get('/:id/diff-file', (c) => {
             if (!from || !to) {
                 return c.json({ error: 'mode=commits requires from and to query params' }, 400);
             }
-            if (!gitOps.commitExists(worktreePath, to)) {
+            if (!(await gitOps.commitExistsAsync(worktreePath, to))) {
                 return c.json({ error: `Invalid commit ref '${to}'` }, 400);
             }
             // `from` is lenient (empty-tree fallback) for a root commit's `<sha>^` —
             // see the matching note in the `/diff` commits branch above.
-            const fromRef = gitOps.commitExists(worktreePath, from) ? from : gitOps.EMPTY_TREE_SHA;
-            const original = gitOps.getFileAtRef(worktreePath, fromRef, filePath);
-            const modified = gitOps.getFileAtRef(worktreePath, to, filePath);
+            const fromRef = (await gitOps.commitExistsAsync(worktreePath, from)) ? from : gitOps.EMPTY_TREE_SHA;
+            const [original, modified] = await Promise.all([
+                gitOps.getFileAtRefAsync(worktreePath, fromRef, filePath),
+                gitOps.getFileAtRefAsync(worktreePath, to, filePath),
+            ]);
             c.header('Cache-Control', 'no-store');
             return c.json({
                 original: original ?? '',
@@ -3491,7 +3493,7 @@ app.get('/:id/diff-file', (c) => {
             });
         }
         const baseRef = mode === 'unpushed' ? `origin/${workspace.workingBranch}` : workspace.sourceBranch;
-        const original = gitOps.getFileAtRef(worktreePath, baseRef, filePath);
+        const original = await gitOps.getFileAtRefAsync(worktreePath, baseRef, filePath);
         const modified = gitOps.getFileContent(worktreePath, filePath);
         c.header('Cache-Control', 'no-store');
         return c.json({
@@ -3555,7 +3557,7 @@ app.post('/:id/rollback-file', async (c) => {
 // GET /api/workspaces/:id/branch-divergence?limit=50
 // Returns commits on the working branch ahead of `origin/<sourceBranch>`
 // (`ahead`) and commits on `origin/<sourceBranch>` not yet on the working
-// branch (`behind`). Refreshes `origin/<sourceBranch>` synchronously so the
+// branch (`behind`). Awaits refreshing `origin/<sourceBranch>` so the
 // counts and lists are never computed against a stale local source ref.
 app.get('/:id/branch-divergence', async (c) => {
     try {
@@ -3569,8 +3571,8 @@ app.get('/:id/branch-divergence', async (c) => {
         const limit = Math.min(Math.max(1, Number.isNaN(parsed) ? 50 : parsed), 200);
         const worktreePath = workspace.worktreePath;
         await gitOps.fetchSourceBranchAsync(worktreePath, workspace.sourceBranch);
-        const ahead = gitOps.listBranchCommits(worktreePath, workspace.sourceBranch, workspace.workingBranch, limit);
-        const behind = gitOps.listCommitsBehind(worktreePath, workspace.sourceBranch, workspace.workingBranch, limit);
+        const ahead = await gitOps.listBranchCommitsAsync(worktreePath, workspace.sourceBranch, workspace.workingBranch, limit);
+        const behind = await gitOps.listCommitsBehindAsync(worktreePath, workspace.sourceBranch, workspace.workingBranch, limit);
         c.header('Cache-Control', 'no-store');
         return c.json({
             ahead,
@@ -3586,7 +3588,7 @@ app.get('/:id/branch-divergence', async (c) => {
 });
 // GET /api/workspaces/:id/commits?limit=50 — list commits between
 // `origin/<sourceBranch>` and HEAD, each tagged with whether it's already
-// pushed to origin/<branch>. Refreshes `origin/<sourceBranch>` synchronously
+// pushed to origin/<branch>. Awaits refreshing `origin/<sourceBranch>`
 // so the list is not computed against a stale local source ref.
 app.get('/:id/commits', async (c) => {
     try {
@@ -3599,7 +3601,7 @@ app.get('/:id/commits', async (c) => {
         const limit = Math.min(Math.max(1, parseInt(limitRaw ?? '50', 10) || 50), 200);
         const worktreePath = workspace.worktreePath;
         await gitOps.fetchSourceBranchAsync(worktreePath, workspace.sourceBranch);
-        const commits = gitOps.listBranchCommits(worktreePath, workspace.sourceBranch, workspace.workingBranch, limit);
+        const commits = await gitOps.listBranchCommitsAsync(worktreePath, workspace.sourceBranch, workspace.workingBranch, limit);
         c.header('Cache-Control', 'no-store');
         return c.json({ commits, sourceBranch: workspace.sourceBranch, workingBranch: workspace.workingBranch });
     }
@@ -3609,13 +3611,13 @@ app.get('/:id/commits', async (c) => {
     }
 });
 // GET /:id/working-tree-files — list uncommitted working-tree files (read-only)
-app.get('/:id/working-tree-files', (c) => {
+app.get('/:id/working-tree-files', async (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
         if (!workspace)
             return c.json({ error: `Workspace '${id}' not found` }, 404);
-        const files = gitOps.getWorkingTreeFiles(workspace.worktreePath);
+        const files = await gitOps.getWorkingTreeFilesAsync(workspace.worktreePath);
         return c.json({ files });
     }
     catch (err) {
@@ -3954,7 +3956,7 @@ app.post('/:id/git/commit-with-agent', migrationGuard, async (c) => {
         const workspace = workspaceService.getWorkspace(id);
         if (!workspace)
             return c.json({ error: `Workspace '${id}' not found` }, 404);
-        const workingTree = gitOps.getWorkingTreeStatus(workspace.worktreePath);
+        const workingTree = await gitOps.getWorkingTreeStatusAsync(workspace.worktreePath);
         if (workingTree.staged + workingTree.modified + workingTree.untracked === 0) {
             return c.json({ error: 'No uncommitted changes to commit' }, 400);
         }
@@ -4372,8 +4374,8 @@ app.post('/:id/open-pr', async (c) => {
             return c.json({ ok: true, prNumber, prUrl, messageSent: false });
         }
         // 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 commits = await gitOps.getCommitsBetweenAsync(worktreePath, workspace.sourceBranch, workspace.workingBranch);
+        const diffStats = await gitOps.getDiffStatsBetweenAsync(worktreePath, workspace.sourceBranch, workspace.workingBranch);
         const tasks = workspaceService.listTasks(workspace.id);
         const rendered = renderPrTemplate(effective.prPromptTemplate, {
             workspace,
@@ -4621,4 +4623,43 @@ app.post('/:id/interrupt', migrationGuard, async (c) => {
         return c.json({ error: message }, workspaceErrorStatus(err));
     }
 });
+// POST /api/workspaces/:id/subagents/stop - stop one running sub-agent (body
+// `{ id }`, its canonical card id) or all of them, without interrupting the turn
+app.post('/:id/subagents/stop', migrationGuard, async (c) => {
+    try {
+        const id = c.req.param('id');
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace) {
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        }
+        const rawBody = await c.req.text();
+        let body = {};
+        if (rawBody.trim().length > 0) {
+            let parsed;
+            try {
+                parsed = JSON.parse(rawBody);
+            }
+            catch {
+                return c.json({ error: 'Request body must be valid JSON' }, 400);
+            }
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                return c.json({ error: 'Request body must be a JSON object' }, 400);
+            }
+            body = parsed;
+        }
+        if (body.id !== undefined && (typeof body.id !== 'string' || body.id.trim().length === 0)) {
+            return c.json({ error: 'id must be a non-empty string when provided' }, 400);
+        }
+        const stopped = agentManager.stopSubagents(id, body.id);
+        return c.json({ stopped });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (err instanceof agentManager.StopSubagentsError) {
+            const status = err.code === 'subagent_not_running' ? 404 : 409;
+            return c.json({ error: message, code: err.code }, status);
+        }
+        return c.json({ error: message }, workspaceErrorStatus(err));
+    }
+});
 export default app;