@loicngr/kobo 1.7.0 → 1.7.2

package/README.md

@@ -11,7 +11,7 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 
 ## Features
 
-- **Isolated git worktrees** — every workspace runs on its own branch in its own directory, so concurrent Claude sessions never step on each other
+- **Isolated git worktrees** — every workspace runs on its own branch in its own directory, with a configurable global worktrees root for new workspaces, so concurrent Claude sessions never step on each other
 - **Pluggable agent engine** — Kōbō talks to agents through an `AgentEngine` contract with a normalised `AgentEvent` stream (`src/server/services/agent/engines/`). The `claude-code` engine runs on the official [`@anthropic-ai/claude-agent-sdk`](https://github.com/anthropics/claude-agent-sdk-typescript); adding a second runtime (e.g. Codex) only requires a new adapter, not a rewrite of the UI or orchestration layer
 - **Interactive `AskUserQuestion`** — when the agent invokes `AskUserQuestion`, Kōbō pauses the session via the SDK's `defer` pattern, surfaces a question panel in the UI, and resumes the agent once the user answers. The session does not occupy any resources while it waits
 - **Rich chat feed** — live streaming text, thinking blocks, inline tool calls with expandable diffs for Edit/Write, per-turn session cards, markdown rendering, jump-to-previous-user-message button, and infinite scroll-up over persisted history
@@ -32,7 +32,7 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 - **Soft interrupt** — pause an agent mid-execution (SIGINT, like pressing Escape in Claude Code) without killing the process; the agent stops the current tool and waits for the next message
 - **Archive instead of delete** — soft-remove workspaces without losing the worktree, branches, or history; unarchive restores the exact pre-archive state
 - **Auto-loop mode** — opt-in, per-workspace: when enabled, Kōbō spawns a fresh Claude session for the next pending task after every `session:ended`, walking through the task list until all are `done`. Stops automatically on error, on stall (3 consecutive sessions with no task completed), or when the user clicks Stop. A grooming step (`/kobo-prep-autoloop`) ensures tasks are atomic before the loop runs; Notion-imported workspaces with both todos and acceptance criteria are auto-unlocked. **E2E grooming** — when a project declares an E2E framework in Settings (Cypress, Playwright, Vitest, etc.), the grooming phase injects an `[E2E] ` test sub-task between every parent task; each iteration then runs the matching E2E suite as part of its acceptance check
-- **Attach existing worktrees** — Kōbō detects orphan worktrees under `.worktrees/` (created outside Kōbō, or left over from an earlier install) and lets you attach them to a new workspace from the creation form, picking up the existing branch and folder instead of cloning a new one
+- **Attach existing worktrees** — Kōbō detects orphan git worktrees for the selected project (created outside Kōbō, or left over from an earlier install) and lets you attach them to a new workspace from the creation form, picking up the existing branch and folder instead of cloning a new one
 - **Quota-aware retry backoff** — when a Claude rate limit is hit mid-session, Kōbō schedules the retry at the actual reset time reported by the API (via `rate_limit.info.buckets[].resetsAt`), falling back to a 15 → 30 → 60 → 180 → 300 min ladder only when the reset info is missing or implausible
 - **Scheduled wakeups** — the `ScheduleWakeup` tool is honoured server-side: Kōbō persists the wakeup in SQLite, rehydrates on restart, and respawns the agent with `--resume` at the target time
 
@@ -252,7 +252,7 @@ See [`AGENTS.md`](./AGENTS.md) for a deeper dive into conventions, data model, W
 
 | Table | Purpose |
 |---|---|
-| `workspaces` | the unit of work — branch, status, model, engine, `archived_at`, `favorited_at`, `tags`, Notion link, … |
+| `workspaces` | the unit of work — branch, `worktree_path`, status, model, engine, `archived_at`, `favorited_at`, `tags`, Notion link, … |
 | `tasks` | workspace sub-items — tasks and acceptance criteria |
 | `agent_sessions` | agent runs — pid, `engine_session_id`, lifecycle |
 | `ws_events` | persisted WebSocket events (chat history, `agent:event` stream, user messages) for replay on reconnect |
@@ -269,9 +269,10 @@ The MCP server reads and writes the same SQLite database as the main backend. Is
 
 ## Configuration
 
-Kōbō reads settings from `~/.config/kobo/settings.json` (or falls back to defaults). Global settings cascade into per-project overrides:
+Kōbō reads settings from `~/.config/kobo/settings.json` (or falls back to defaults). Global settings define defaults, with per-project overrides for project-scoped fields:
 
 - `defaultModel` — Claude model to use (e.g. `claude-opus-4-6`)
+- `worktreesPath` — where new workspace worktrees are created. Defaults to `.worktrees`, resolved relative to the project. Absolute Linux/macOS paths, Windows paths (`C:\kobo\worktrees`, UNC shares), `$HOME/...`, `${HOME}/...`, `~/...`, and `%USERPROFILE%\...` are accepted. Paths containing parent-directory traversal (`..`) or drive-relative Windows syntax (`C:foo`) are rejected.
 - `prPromptTemplate` — template rendered when opening a PR via the `/open-pr` endpoint; supports `{{pr_number}}`, `{{pr_url}}`, `{{branch_name}}`, `{{diff_stats}}`, `{{commits}}`, etc.
 - `gitConventions` — markdown-formatted git conventions written to `.ai/.git-conventions.md` in every workspace so the agent follows them when committing
 - `devServer` — per-project `startCommand` / `stopCommand` for launching workspace-scoped dev servers
@@ -288,6 +289,10 @@ This is a personal tool, but PRs and issues are welcome. Before submitting:
 
 CI runs lint + type check + tests on every PR to `develop`.
 
+## Release
+
+Releases are cut from `main`. Bump `package.json` and `package-lock.json` on `develop`, merge `develop` into `main`, then push `main`. The release workflow builds, tests, publishes the current package version to npm, tags it as `v<version>`, and creates the GitHub Release. If the npm version or tag already exists, the workflow fails before publishing.
+
 ## License
 
 GNU General Public License v3.0 or later. See [`LICENSE`](./LICENSE) for the full text.

package/dist/mcp-server/kobo-tasks-handlers.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { nanoid } from 'nanoid';
+import { resolveWorkspaceWorktreePath } from '../server/utils/worktree-paths.js';
 /** Allowed task status values. */
 export const VALID_TASK_STATUSES = ['pending', 'in_progress', 'done'];
 function rowToDto(row) {
@@ -163,7 +164,7 @@ export function getWorkspaceInfoHandler(db, workspaceId) {
         projectPath: row.project_path,
         sourceBranch: row.source_branch,
         workingBranch: row.working_branch,
-        worktreePath: row.worktree_path ?? path.join(row.project_path, '.worktrees', row.working_branch),
+        worktreePath: row.worktree_path ?? resolveWorkspaceWorktreePath(row.project_path, row.working_branch),
         status: row.status,
         model: row.model,
         notionUrl: row.notion_url,

package/dist/server/routes/health.js

@@ -1,11 +1,11 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
-import path from 'node:path';
 import { Hono } from 'hono';
 import { getDb } from '../db/index.js';
 import { SCHEMA_VERSION } from '../db/migrations.js';
 import { getGlobalSettings, SETTINGS_SCHEMA_VERSION } from '../services/settings-service.js';
 import { getDbPath, getKoboHome } from '../utils/paths.js';
+import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 const app = new Hono();
 function checkClaudeCli() {
     try {
@@ -51,7 +51,7 @@ app.get('/report', (c) => {
     for (const ws of workspaces) {
         if (ws.archived_at)
             continue;
-        const wtPath = ws.worktree_path ?? path.join(ws.project_path, '.worktrees', ws.working_branch);
+        const wtPath = ws.worktree_path ?? resolveWorkspaceWorktreePath(ws.project_path, ws.working_branch);
         if (!fs.existsSync(wtPath)) {
             worktreesMissing.push({ workspaceId: ws.id, name: ws.name, path: wtPath, exists: false });
         }

package/dist/server/routes/settings.js

@@ -45,7 +45,8 @@ app.put('/global', async (c) => {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return c.json({ error: message }, 500);
+        const status = err instanceof Error && err.name === 'InvalidWorktreesPathError' ? 400 : 500;
+        return c.json({ error: message }, status);
     }
 });
 // GET /api/settings/projects — list all projects

package/dist/server/routes/workspaces.js

@@ -23,6 +23,7 @@ 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';
+import { resolveSiblingWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 /** Hono sub-router for workspace CRUD, tasks, agent lifecycle, git operations, and PR creation. */
 const app = new Hono();
 /** Tracks workspaces currently running a setup script to prevent concurrent executions. */
@@ -197,6 +198,7 @@ app.post('/', migrationGuard, async (c) => {
             reasoningEffort: body.reasoningEffort,
             agentPermissionMode: resolveCreateAgentPermissionMode(body.agentPermissionMode, body.projectPath, globalSettings),
             engine: body.engine,
+            ...(useReusedWorktree ? {} : { worktreesPath: globalSettings.worktreesPath }),
         });
         // Auto-tag the workspace based on its creation source — `notion` when
         // imported from a Notion page, `sentry` when bootstrapped from a Sentry
@@ -287,7 +289,7 @@ app.post('/', migrationGuard, async (c) => {
         }
         else {
             try {
-                worktreePath = worktreeService.createWorktree(body.projectPath, workingBranch, body.sourceBranch);
+                worktreePath = worktreeService.createWorktree(body.projectPath, workingBranch, body.sourceBranch, globalSettings.worktreesPath);
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -1725,11 +1727,7 @@ app.post('/:id/rename-branch', async (c) => {
         // Sibling rename: keep the same worktrees-root, swap the branch leaf.
         // Cannot use `path.dirname` directly because branches with slashes
         // (e.g. `feature/x`) make the dirname end one level too deep.
-        const oldSuffix = `/${workspace.workingBranch}`;
-        const worktreesRoot = oldWorktreePath.endsWith(oldSuffix)
-            ? oldWorktreePath.slice(0, -oldSuffix.length)
-            : path.join(workspace.projectPath, '.worktrees');
-        const newWorktreePath = path.join(worktreesRoot, newName);
+        const newWorktreePath = resolveSiblingWorkspaceWorktreePath(workspace.projectPath, oldWorktreePath, workspace.workingBranch, newName);
         // Reject early if the target name is already in use — either as a local
         // branch or on origin. Avoids git's generic "already exists" error and
         // protects against the same silent-fallback trap the create flow has.
@@ -1799,11 +1797,7 @@ app.post('/:id/resync-branch', (c) => {
         // if the move fails (dir already moved, lockfile, dirty tree), we still
         // update the DB so git ops stay aligned with the current ref name — the
         // user can repair the dir manually.
-        const oldSuffix = `/${workspace.workingBranch}`;
-        const worktreesRoot = worktreePath.endsWith(oldSuffix)
-            ? worktreePath.slice(0, -oldSuffix.length)
-            : path.join(workspace.projectPath, '.worktrees');
-        const newWorktreePath = path.join(worktreesRoot, actual);
+        const newWorktreePath = resolveSiblingWorkspaceWorktreePath(workspace.projectPath, worktreePath, workspace.workingBranch, actual);
         try {
             gitOps.moveWorktree(workspace.projectPath, worktreePath, newWorktreePath);
             workspaceService.updateWorktreePath(id, newWorktreePath);

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

@@ -4,6 +4,7 @@ import { CLAUDE_CODE_CAPABILITIES } from './capabilities.js';
 import { createMapperState, mapSdkMessage } from './event-mapper.js';
 import { buildClaudeOptions } from './options-builder.js';
 import { buildPreCompactCustomInstructions } from './precompact-hook.js';
+import { resolveClaudeBinaryPath } from './resolve-binary.js';
 function toMcpServersMap(specs) {
     if (!specs || specs.length === 0)
         return undefined;
@@ -112,6 +113,11 @@ export function createClaudeCodeEngine() {
                 },
             });
             sdkOptions.abortController = abortController;
+            // Override the SDK's libc-blind binary resolution on Linux glibc — see
+            // resolve-binary.ts for the full rationale. No-op on macOS/Windows/musl.
+            const explicitBinary = resolveClaudeBinaryPath();
+            if (explicitBinary)
+                sdkOptions.pathToClaudeCodeExecutable = explicitBinary;
             const q = query({ prompt: effectivePrompt, options: sdkOptions });
             let discoveredSessionId;
             // A throwing onEvent handler (e.g. DB query against a closed connection

package/dist/server/services/agent/engines/claude-code/resolve-binary.js

@@ -0,0 +1,50 @@
+import { createRequire } from 'node:module';
+const localRequire = createRequire(import.meta.url);
+/**
+ * Detect the live host's platform/arch/libc from `process`. `glibcVersionRuntime`
+ * lives in the diagnostic report header on glibc systems and is absent on musl.
+ * Available since Node 12; Kōbō requires Node ≥ 20 (see AGENTS.md).
+ */
+export function detectPlatform() {
+    const report = process.report;
+    const glibcVersion = report?.getReport().header?.glibcVersionRuntime;
+    return {
+        platform: process.platform,
+        arch: process.arch,
+        isGlibc: typeof glibcVersion === 'string' && glibcVersion.length > 0,
+    };
+}
+/**
+ * Resolve an explicit path to the Claude CLI binary that matches the host
+ * libc — or `undefined` to fall back to the SDK's built-in resolution.
+ *
+ * Why this exists: on Linux glibc systems npm installs both
+ * `@anthropic-ai/claude-agent-sdk-linux-${arch}` (glibc) and
+ * `@anthropic-ai/claude-agent-sdk-linux-${arch}-musl` because npm doesn't
+ * filter `optionalDependencies` by the `libc` field. The SDK's internal
+ * resolver tries the musl variant first and returns its path; that binary
+ * then ENOENTs at exec because its dynamic linker (`/lib/ld-musl-*.so.1`)
+ * is absent on glibc systems, surfacing the misleading "Claude Code native
+ * binary not found" error.
+ *
+ * Returning the explicit glibc path here overrides the SDK's choice and
+ * sidesteps the bug.
+ *
+ * On every other platform (musl Linux, macOS, Windows, unknown libc, or
+ * unsupported arch), this returns `undefined` so the SDK keeps its default
+ * resolution behaviour.
+ */
+export function resolveClaudeBinaryPath(probe = detectPlatform(), resolveFn = (id) => localRequire.resolve(id)) {
+    if (probe.platform !== 'linux')
+        return undefined;
+    if (!probe.isGlibc)
+        return undefined;
+    if (probe.arch !== 'x64' && probe.arch !== 'arm64')
+        return undefined;
+    try {
+        return resolveFn(`@anthropic-ai/claude-agent-sdk-linux-${probe.arch}/claude`);
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -590,11 +590,20 @@ function onSessionEnded(workspaceId, agentSessionId, exitCode, reason, resumeFai
     // `resumeFailed` is benign: stale id cleared, next iteration starts fresh.
     const isErrorOutcome = !resumeFailed && (reason === 'error' || (exitCode !== null && exitCode !== 0));
     const targetStatus = isErrorOutcome ? 'error' : 'completed';
-    try {
-        updateWorkspaceStatus(workspaceId, targetStatus);
-    }
-    catch (err) {
-        console.error('[orchestrator] Failed to update workspace status on exit:', err);
+    // Skip the transition when the workspace is already in a terminal state.
+    // This happens when stopAgent (or an equivalent caller) synchronously
+    // normalised the status before the engine's async stop emitted session:ended
+    // — typically `awaiting-user → idle`. Without this guard we'd attempt e.g.
+    // `idle → completed` and log a benign error on every such manual stop.
+    const currentStatus = currentWorkspace?.status;
+    const alreadyTerminal = currentStatus === 'idle' || currentStatus === 'completed' || currentStatus === 'error' || currentStatus === 'quota';
+    if (!alreadyTerminal) {
+        try {
+            updateWorkspaceStatus(workspaceId, targetStatus);
+        }
+        catch (err) {
+            console.error('[orchestrator] Failed to update workspace status on exit:', err);
+        }
     }
     try {
         markWorkspaceUnread(workspaceId);

package/dist/server/services/auto-loop-service.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
-import path from 'node:path';
 import { buildE2eIterationBlock, buildFinalizationIterationBlock } from '../../shared/auto-loop-prompts.js';
 import { getDb } from '../db/index.js';
+import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 import * as orchestrator from './agent/orchestrator.js';
 import * as settingsService from './settings-service.js';
 import { emit, emitEphemeral } from './websocket-service.js';
@@ -252,7 +252,7 @@ function spawnNextIteration(workspaceId, opts = {}) {
         .replaceAll('{taskTitle}', task.title)
         .replaceAll('{isAcceptanceCriterion}', String(task.isAcceptanceCriterion))
         .replaceAll('{overrideBlock}', overrideBlock);
-    const worktreePath = row.worktree_path ?? path.join(row.project_path, '.worktrees', row.working_branch);
+    const worktreePath = row.worktree_path ?? resolveWorkspaceWorktreePath(row.project_path, row.working_branch);
     // Plan mode would deadlock the loop (blocks MCP + edits) — promote to bypass.
     // Other modes (bypass/strict/interactive) are honored.
     const stored = (row.agent_permission_mode ?? 'bypass');

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

@@ -164,7 +164,7 @@ export function startDevServer(workspaceId) {
     const instanceName = sanitizeBranchName(workspace.workingBranch);
     // Execute as bash script (supports multi-line scripts)
     const worktreePath = workspace.worktreePath;
-    const cwd = existsSync(worktreePath) ? worktreePath : workspace.projectPath;
+    const cwd = worktreePath && existsSync(worktreePath) ? worktreePath : workspace.projectPath;
     const proc = spawn('bash', ['-c', settings.devServer.startCommand], {
         cwd,
         env: {
@@ -230,7 +230,7 @@ export function stopDevServer(workspaceId) {
     const config = resolveInstance(workspace.projectPath, workspace.workingBranch);
     const instanceName = config?.instanceName ?? sanitizeBranchName(workspace.workingBranch);
     const worktreePath = workspace.worktreePath;
-    const cwd = existsSync(worktreePath) ? worktreePath : workspace.projectPath;
+    const cwd = worktreePath && existsSync(worktreePath) ? worktreePath : workspace.projectPath;
     // Kill tracked process first (covers Node servers and any spawned process)
     const tracked = trackedProcesses.get(workspaceId);
     if (tracked) {

package/dist/server/services/pr-watcher-service.js

@@ -2,7 +2,7 @@ import { getPrStatusAsync } from '../utils/git-ops.js';
 import { stopDevServer } from './dev-server-service.js';
 import { destroyTerminal } from './terminal-service.js';
 import { emitEphemeral } from './websocket-service.js';
-import { archiveWorkspace, listWorkspaces } from './workspace-service.js';
+import { archiveWorkspace, listWorkspaces, updateWorkspaceSourceBranch } from './workspace-service.js';
 // ── PR Watcher ────────────────────────────────────────────────────────────────
 // Polls GitHub every POLL_INTERVAL_MS to detect merged/closed PRs and
 // automatically archive the corresponding workspace.
@@ -14,8 +14,7 @@ import { archiveWorkspace, listWorkspaces } from './workspace-service.js';
 const POLL_INTERVAL_MS = 30 * 1000; // 30 seconds
 let timer = null;
 let checking = false;
-/** Tracks the last known PR state per workspace to detect transitions. */
-const lastKnownState = new Map();
+const lastKnownPr = new Map();
 /**
  * Read-only snapshot of PR states known to the watcher, keyed by workspace id.
  * Used by the drawer to show a small PR-open indicator without N separate
@@ -25,17 +24,24 @@ const lastKnownState = new Map();
  */
 export function getAllPrStates() {
     const out = {};
-    for (const [id, state] of lastKnownState) {
-        out[id] = state;
+    for (const [id, known] of lastKnownPr) {
+        out[id] = known.state;
     }
     return out;
 }
-async function checkPrStatuses() {
+/**
+ * Test-only escape hatch — drops the in-memory cache so each test starts
+ * from a clean slate. Not part of the public API.
+ */
+export function _resetForTest() {
+    lastKnownPr.clear();
+}
+export async function checkPrStatuses() {
     const workspaces = listWorkspaces(false); // non-archived only
     // Clean up entries for workspaces that no longer exist
-    for (const id of lastKnownState.keys()) {
+    for (const id of lastKnownPr.keys()) {
         if (!workspaces.some((ws) => ws.id === id)) {
-            lastKnownState.delete(id);
+            lastKnownPr.delete(id);
         }
     }
     for (const ws of workspaces) {
@@ -46,10 +52,15 @@ async function checkPrStatuses() {
             const pr = await getPrStatusAsync(ws.projectPath, ws.workingBranch);
             if (!pr)
                 continue;
-            const prev = lastKnownState.get(ws.id);
-            lastKnownState.set(ws.id, pr.state);
-            // Only archive on a transition FROM OPEN — not on first sight of CLOSED/MERGED
-            if (prev === 'OPEN' && (pr.state === 'MERGED' || pr.state === 'CLOSED')) {
+            const prev = lastKnownPr.get(ws.id);
+            // We delay updating `lastKnownPr` until after the actions succeed.
+            // Setting it eagerly would poison the cache: if updateWorkspaceSourceBranch
+            // throws (transient DB issue, race with workspace deletion), the cache
+            // already holds the new base and the user never sees the toast — the
+            // next tick computes `prev.base === pr.base` and treats it as no-op.
+            // Archive on a transition FROM OPEN to CLOSED/MERGED. Skips the
+            // base-change detection below — archiving wins.
+            if (prev?.state === 'OPEN' && (pr.state === 'MERGED' || pr.state === 'CLOSED')) {
                 console.log(`[pr-watcher] PR ${pr.state.toLowerCase()} for workspace '${ws.name}' — archiving`);
                 // Best-effort cleanup (same as manual archive): stop dev server + terminal.
                 // Agent is already not running here (guarded above).
@@ -66,12 +77,51 @@ async function checkPrStatuses() {
                     // Terminal may not exist — ignore
                 }
                 archiveWorkspace(ws.id);
-                lastKnownState.delete(ws.id);
+                lastKnownPr.delete(ws.id);
                 emitEphemeral(ws.id, 'workspace:archived', {
                     reason: `PR ${pr.state.toLowerCase()}`,
                     prUrl: pr.url,
                 });
+                continue; // do not run base-change detection on a workspace we just archived
+            }
+            // Base-branch change detection. Only relevant for OPEN PRs — closed/
+            // merged PRs don't accept base changes. Skip if the GitHub response
+            // didn't include a baseRefName (defensive against malformed data).
+            if (pr.state !== 'OPEN' || !pr.base) {
+                // Still update the cache for the state — keeps the OPEN→CLOSED/MERGED
+                // archiving logic working on the next tick.
+                lastKnownPr.set(ws.id, { state: pr.state, base: prev?.base });
+                continue;
+            }
+            // Comparison baseline:
+            //  - If we've seen this workspace before, use the previous `base`.
+            //  - Otherwise (first sight after boot/unarchive), compare with the
+            //    `sourceBranch` recorded in the database — that catches base changes
+            //    that happened while Kobo was offline.
+            const previousBase = prev?.base ?? ws.sourceBranch;
+            if (previousBase === pr.base) {
+                // No-op path: still record the base so subsequent ticks have a baseline.
+                lastKnownPr.set(ws.id, { state: pr.state, base: pr.base });
+                continue;
+            }
+            console.log(`[pr-watcher] PR base changed for workspace '${ws.name}': ${previousBase} → ${pr.base}`);
+            try {
+                updateWorkspaceSourceBranch(ws.id, pr.base);
+            }
+            catch (err) {
+                console.error(`[pr-watcher] updateWorkspaceSourceBranch failed for '${ws.name}':`, err instanceof Error ? err.message : err);
+                // Don't poison the cache: leave the previous entry (or absence) so
+                // the next tick retries the detection.
+                continue;
             }
+            // Both the persistence and the emit are part of "we successfully
+            // observed a base change" — only NOW commit the new state to the cache.
+            lastKnownPr.set(ws.id, { state: pr.state, base: pr.base });
+            emitEphemeral(ws.id, 'pr:base-changed', {
+                oldBase: previousBase,
+                newBase: pr.base,
+                prUrl: pr.url,
+            });
         }
         catch (err) {
             console.error(`[pr-watcher] Failed to check PR for workspace '${ws.name}':`, err instanceof Error ? err.message : err);

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

@@ -1,7 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { WORKTREES_PATH } from '../../shared/consts.js';
 import { listClaudeMcpEntries } from '../utils/mcp-client.js';
 import { getSettingsPath } from '../utils/paths.js';
+import { InvalidWorktreesPathError, resolveGlobalWorktreesRoot, sanitizeWorktreesPath, validateWorktreesPath, } from '../utils/worktree-paths.js';
 const DEFAULT_GIT_CONVENTIONS = `# Git conventions
 
 ## Commits
@@ -191,6 +193,32 @@ const settingsMigrations = [
             }
         },
     },
+    {
+        version: 11,
+        name: 'add-global-worktrees-path',
+        migrate({ global }) {
+            global.worktreesPath = sanitizeWorktreesPath(global.worktreesPath);
+        },
+    },
+    {
+        version: 12,
+        name: 'add-audio-notification-sound',
+        migrate({ global }) {
+            if (typeof global.audioNotificationSound !== 'string' || global.audioNotificationSound.length === 0) {
+                global.audioNotificationSound = 'hey.mp3';
+            }
+        },
+    },
+    {
+        version: 13,
+        name: 'add-audio-notification-volume',
+        migrate({ global }) {
+            const v = global.audioNotificationVolume;
+            if (typeof v !== 'number' || Number.isNaN(v) || v < 0 || v > 1) {
+                global.audioNotificationVolume = 1;
+            }
+        },
+    },
 ];
 /** Current settings schema version — always equals the highest migration version. */
 export const SETTINGS_SCHEMA_VERSION = settingsMigrations.length > 0 ? settingsMigrations[settingsMigrations.length - 1].version : 0;
@@ -225,12 +253,15 @@ function defaultSettings() {
             editorCommand: '',
             browserNotifications: true,
             audioNotifications: true,
+            audioNotificationSound: 'hey.mp3',
+            audioNotificationVolume: 1,
             notionStatusProperty: '',
             notionInProgressStatus: '',
             defaultPermissionMode: 'plan',
             notionMcpKey: '',
             sentryMcpKey: '',
             tags: [...DEFAULT_WORKSPACE_TAGS],
+            worktreesPath: WORKTREES_PATH,
         },
         projects: [],
     };
@@ -278,6 +309,7 @@ export function runSettingsMigrations(raw) {
             version = m.version;
         }
     }
+    current.global.worktreesPath = sanitizeWorktreesPath(current.global.worktreesPath);
     current.schemaVersion = version;
     return current;
 }
@@ -310,9 +342,11 @@ function readSettings() {
     // Restore any global fields that may have been removed by external edits.
     // Defaults act as fallback for missing keys; existing values are preserved.
     const globalDefaults = defaultSettings().global;
+    const globalBeforeDefaults = JSON.stringify(migrated.global);
     migrated.global = { ...globalDefaults, ...migrated.global };
+    const restoredGlobalFields = JSON.stringify(migrated.global) !== globalBeforeDefaults;
     // Persist if migrations bumped the version, or if global fields were restored.
-    if (migrated.schemaVersion !== originalVersion) {
+    if (migrated.schemaVersion !== originalVersion || restoredGlobalFields) {
         writeSettings(migrated);
     }
     return migrated;
@@ -444,12 +478,15 @@ export function updateGlobalSettings(data) {
         'editorCommand',
         'browserNotifications',
         'audioNotifications',
+        'audioNotificationSound',
+        'audioNotificationVolume',
         'notionStatusProperty',
         'notionInProgressStatus',
         'defaultPermissionMode',
         'notionMcpKey',
         'sentryMcpKey',
         'tags',
+        'worktreesPath',
     ];
     const filtered = pickKnownKeys(data, allowedGlobalKeys);
     if (filtered.tags !== undefined) {
@@ -459,10 +496,34 @@ export function updateGlobalSettings(data) {
                 .filter((t) => t.length > 0 && t.length <= 50)))
             : settings.global.tags;
     }
+    if (filtered.audioNotificationVolume !== undefined) {
+        const v = Number(filtered.audioNotificationVolume);
+        filtered.audioNotificationVolume = Number.isFinite(v) ? Math.max(0, Math.min(1, v)) : 1;
+    }
+    if (filtered.worktreesPath !== undefined) {
+        filtered.worktreesPath = validateWorktreesPath(filtered.worktreesPath, { allowEmpty: false });
+        ensureGlobalWorktreesRootExists(filtered.worktreesPath);
+    }
     settings.global = { ...settings.global, ...filtered };
     writeSettings(settings, { backup: true });
     return settings.global;
 }
+function ensureGlobalWorktreesRootExists(worktreesPath) {
+    const root = resolveGlobalWorktreesRoot(worktreesPath);
+    if (!root || isNonNativeWindowsPath(root))
+        return;
+    try {
+        fs.mkdirSync(root, { recursive: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new InvalidWorktreesPathError(`Cannot create worktrees directory '${root}': ${message}`);
+    }
+}
+function isNonNativeWindowsPath(value) {
+    return (process.platform !== 'win32' &&
+        (/^[A-Za-z]:[\\/]/.test(value) || value.startsWith('\\\\') || value.startsWith('//')));
+}
 /** Create or update project-specific settings. Merges devServer, e2e, and finalization fields on update. */
 export function upsertProject(projectPath, data) {
     const allowedProjectKeys = [

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

@@ -1,5 +1,5 @@
-import path from 'node:path';
 import { getDb } from '../db/index.js';
+import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 import * as orchestrator from './agent/orchestrator.js';
 import { emitEphemeral } from './websocket-service.js';
 const MIN_DELAY_SECONDS = 60;
@@ -132,7 +132,7 @@ function fire(workspaceId) {
             emitEphemeral(workspaceId, 'wakeup:skipped', { reason: 'fire-failed' });
             return;
         }
-        const worktreePath = wsRow.worktree_path ?? path.join(wsRow.project_path, '.worktrees', wsRow.working_branch);
+        const worktreePath = wsRow.worktree_path ?? resolveWorkspaceWorktreePath(wsRow.project_path, wsRow.working_branch);
         // Narrow against the four known values; unknowns → 'bypass'.
         const stored = wsRow.agent_permission_mode;
         const agentPermissionMode = stored === 'plan' || stored === 'strict' || stored === 'interactive' ? stored : 'bypass';

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

@@ -1,5 +1,6 @@
 import { nanoid } from 'nanoid';
 import { getDb } from '../db/index.js';
+import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 import * as orchestrator from './agent/orchestrator.js';
 import * as autoLoopService from './auto-loop-service.js';
 import * as wakeupService from './wakeup-service.js';
@@ -91,7 +92,7 @@ export function createWorkspace(data) {
     const db = getDb();
     const now = new Date().toISOString();
     const id = nanoid();
-    const computedWorktreePath = data.worktreePath ?? `${data.projectPath}/.worktrees/${data.workingBranch}`;
+    const computedWorktreePath = data.worktreePath ?? resolveWorkspaceWorktreePath(data.projectPath, data.workingBranch, data.worktreesPath);
     const owned = data.worktreeOwned ?? true;
     // Mirror the unified mode into the legacy columns so older readers (in-flight
     // requests during deploy, external scripts) still see a sane value.
@@ -216,6 +217,27 @@ export function updateWorkingBranch(id, workingBranch) {
     }
     return getWorkspace(id);
 }
+/**
+ * Update the source branch in the database. Called by the PR watcher when
+ * GitHub reports a different `baseRefName` for the workspace's PR.
+ * Does NOT touch the worktree — the user (or the agent) decides when to
+ * rebase the local branch onto the new base.
+ */
+export function updateWorkspaceSourceBranch(id, sourceBranch) {
+    const sanitized = sourceBranch.trim();
+    if (!sanitized) {
+        throw new Error('Source branch cannot be empty');
+    }
+    const db = getDb();
+    const now = new Date().toISOString();
+    const result = db
+        .prepare('UPDATE workspaces SET source_branch = ?, updated_at = ? WHERE id = ?')
+        .run(sanitized, now, id);
+    if (result.changes === 0) {
+        throw new Error(`Workspace '${id}' not found`);
+    }
+    return getWorkspace(id);
+}
 /** Update the on-disk worktree path. Used by rename / resync-branch on owned worktrees. */
 export function updateWorktreePath(id, newPath) {
     const db = getDb();