@loicngr/kobo 1.11.6 → 1.11.7

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

@@ -17,6 +17,14 @@ import { getWorkspace as getWs, markWorkspaceUnread, updateWorkspaceStatus, } fr
 import { resolveEngine } from './engines/registry.js';
 import { routeEvent } from './event-router.js';
 import { SessionController } from './session-controller.js';
+export class InterruptAgentError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'InterruptAgentError';
+    }
+}
 // ── State ──────────────────────────────────────────────────────────────────────
 /** Actual bound port of the running backend — set at startup via setBackendPort() */
 let backendPort = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 3000;
@@ -30,6 +38,58 @@ export function getBackendPort() {
 }
 /** workspaceId -> SessionController */
 const controllers = new Map();
+/**
+ * Latest controller generation per persisted session row. A resumed run can
+ * reuse an agentSessionId while its predecessor is still draining events, so
+ * controller-map membership alone is not a durable ownership signal.
+ */
+const sessionLifecycleOwners = new Map();
+function registerSessionLifecycleOwner(workspaceId, agentSessionId, controller) {
+    const workspaceOwners = sessionLifecycleOwners.get(workspaceId) ?? new Map();
+    const existing = workspaceOwners.get(agentSessionId);
+    if (existing) {
+        if (!existing.ownerEnded)
+            existing.supersededControllers.add(existing.owner);
+        existing.owner = controller;
+        existing.ownerEnded = false;
+    }
+    else {
+        workspaceOwners.set(agentSessionId, {
+            owner: controller,
+            ownerEnded: false,
+            supersededControllers: new Set(),
+        });
+    }
+    sessionLifecycleOwners.set(workspaceId, workspaceOwners);
+}
+function getSessionLifecycleOwnership(workspaceId, agentSessionId) {
+    return sessionLifecycleOwners.get(workspaceId)?.get(agentSessionId);
+}
+function deleteSessionLifecycleOwnershipIfSettled(workspaceId, agentSessionId) {
+    const workspaceOwners = sessionLifecycleOwners.get(workspaceId);
+    const ownership = workspaceOwners?.get(agentSessionId);
+    if (!workspaceOwners || !ownership?.ownerEnded || ownership.supersededControllers.size > 0)
+        return;
+    workspaceOwners.delete(agentSessionId);
+    if (workspaceOwners.size === 0)
+        sessionLifecycleOwners.delete(workspaceId);
+}
+function markSessionLifecycleOwnerEnded(workspaceId, agentSessionId, controller) {
+    const ownership = getSessionLifecycleOwnership(workspaceId, agentSessionId);
+    if (!controller || !ownership || ownership.owner !== controller)
+        return;
+    ownership.ownerEnded = true;
+    deleteSessionLifecycleOwnershipIfSettled(workspaceId, agentSessionId);
+}
+function settleSupersededSessionController(workspaceId, agentSessionId, controller) {
+    const ownership = getSessionLifecycleOwnership(workspaceId, agentSessionId);
+    if (!ownership)
+        return;
+    ownership.supersededControllers.delete(controller);
+    deleteSessionLifecycleOwnershipIfSettled(workspaceId, agentSessionId);
+}
+export const FALLBACK_CONTROLLER_TURNOVER_TIMEOUT_MS = 2_000;
+export const FALLBACK_CONTROLLER_TURNOVER_POLL_MS = 25;
 /** workspaceId -> last engine session ID (for resume) */
 const sessionIds = new Map();
 /** workspaceId -> FIFO queue of pending items */
@@ -145,8 +205,8 @@ let availableSkills = (() => {
 })();
 /** workspaceId -> retry count (for quota backoff) */
 const retryCounts = new Map();
-/** Tracks workspaces where the current session failed due to a stale --resume session ID. */
-const resumeFailedSet = new Set();
+/** Tracks agent sessions that failed due to a stale --resume session ID. */
+const resumeFailedSessions = new Map();
 // ── Watchdog ──────────────────────────────────────────────────────────────────
 const WATCHDOG_INTERVAL_MS = 30_000;
 let watchdogTimer = null;
@@ -427,14 +487,35 @@ function reuseOrCreateFreshSession(workspaceId, existingSessionId, model, engine
     db.prepare('INSERT INTO agent_sessions (id, workspace_id, pid, engine, status, model, started_at) VALUES (?, ?, ?, ?, ?, ?, ?)').run(agentSessionId, workspaceId, null, engine, 'running', model ?? null, new Date().toISOString());
     return agentSessionId;
 }
-// ── Event handler ─────────────────────────────────────────────────────────────
-/**
- * Snapshots of task completion and task state at `session:started`, read back
- * at `session:ended` for auto-loop stall detection. A task moved to
- * `in_progress` is meaningful progress even if it is not done yet.
- */
-const tasksDoneSnapshot = new Map();
-const taskStateSnapshot = new Map();
+const taskProgressSnapshots = new Map();
+function rememberTaskProgressSnapshot(workspaceId, agentSessionId) {
+    const workspaceSnapshots = taskProgressSnapshots.get(workspaceId) ?? new Map();
+    workspaceSnapshots.set(agentSessionId, {
+        doneCount: getDoneTaskCount(workspaceId),
+        stateSignature: getTaskStateSignature(workspaceId),
+    });
+    taskProgressSnapshots.set(workspaceId, workspaceSnapshots);
+}
+function consumeTaskProgressSnapshot(workspaceId, agentSessionId) {
+    const workspaceSnapshots = taskProgressSnapshots.get(workspaceId);
+    const snapshot = workspaceSnapshots?.get(agentSessionId);
+    workspaceSnapshots?.delete(agentSessionId);
+    if (workspaceSnapshots?.size === 0)
+        taskProgressSnapshots.delete(workspaceId);
+    return snapshot;
+}
+function rememberResumeFailed(workspaceId, agentSessionId) {
+    const workspaceSessions = resumeFailedSessions.get(workspaceId) ?? new Set();
+    workspaceSessions.add(agentSessionId);
+    resumeFailedSessions.set(workspaceId, workspaceSessions);
+}
+function consumeResumeFailed(workspaceId, agentSessionId) {
+    const workspaceSessions = resumeFailedSessions.get(workspaceId);
+    const hadResumeFailure = workspaceSessions?.delete(agentSessionId) ?? false;
+    if (workspaceSessions?.size === 0)
+        resumeFailedSessions.delete(workspaceId);
+    return hadResumeFailure;
+}
 function getDoneTaskCount(workspaceId) {
     try {
         const db = getDb();
@@ -465,12 +546,11 @@ function getTaskStateSignature(workspaceId) {
 }
 /** Clear the in-memory done-count snapshot for a workspace (called on delete). */
 export function forgetTasksDoneSnapshot(workspaceId) {
-    tasksDoneSnapshot.delete(workspaceId);
-    taskStateSnapshot.delete(workspaceId);
+    taskProgressSnapshots.delete(workspaceId);
 }
 /** Drop the resume-failed flag for a workspace (called on delete). */
 export function forgetResumeFailed(workspaceId) {
-    resumeFailedSet.delete(workspaceId);
+    resumeFailedSessions.delete(workspaceId);
 }
 /** Drop the pending question/permission queue for a workspace (called on delete). */
 export function forgetPendingQueue(workspaceId) {
@@ -483,17 +563,35 @@ export function forgetPreAwaitStatus(workspaceId) {
 /** Drop the cached engine session id for a workspace (called on delete). */
 export function forgetSessionId(workspaceId) {
     sessionIds.delete(workspaceId);
+    sessionLifecycleOwners.delete(workspaceId);
 }
-function handleEvent(workspaceId, agentSessionId, ev) {
-    routeEvent(workspaceId, agentSessionId, ev);
+function handleEvent(workspaceId, agentSessionId, sourceController, ev) {
+    const registeredController = controllers.get(workspaceId);
+    const hasReplacement = sourceController !== undefined && registeredController !== undefined && registeredController !== sourceController;
+    const sourceNoLongerOwnsWorkspace = sourceController !== undefined && registeredController !== sourceController;
+    const lifecycleOwnership = getSessionLifecycleOwnership(workspaceId, agentSessionId);
+    const sourceIsSuperseded = sourceController !== undefined &&
+        lifecycleOwnership !== undefined &&
+        lifecycleOwnership.owner !== sourceController &&
+        lifecycleOwnership.supersededControllers.has(sourceController);
+    // A stopped controller can continue draining buffered engine events after it
+    // has lost ownership. Drop every stale non-terminal event before it reaches
+    // persistence/live delivery, including the gap where no replacement is
+    // registered yet. A terminal event still records session-local history; it
+    // carries a durable marker only when a different controller now owns the
+    // workspace, or when the latest owner already ended, so replay does not
+    // depend on transient browser state.
+    if (sourceNoLongerOwnsWorkspace && ev.kind !== 'session:ended')
+        return;
+    const routedEvent = ev.kind === 'session:ended' && (hasReplacement || sourceIsSuperseded) ? { ...ev, superseded: true } : ev;
+    routeEvent(workspaceId, agentSessionId, routedEvent);
     if (ev.kind === 'rate_limit') {
         latestRateLimitInfo.set(workspaceId, ev.info);
     }
     // Snapshot the done-count at session start so the session:ended hook below
     // can compute a delta for auto-loop stall detection.
     if (ev.kind === 'session:started') {
-        tasksDoneSnapshot.set(workspaceId, getDoneTaskCount(workspaceId));
-        taskStateSnapshot.set(workspaceId, getTaskStateSignature(workspaceId));
+        rememberTaskProgressSnapshot(workspaceId, agentSessionId);
     }
     // Legacy fallback: the built-in `ScheduleWakeup` tool (CLI tradition) isn't
     // declared by the SDK, so we intercept the tool:call event and apply the
@@ -580,19 +678,23 @@ function handleEvent(workspaceId, agentSessionId, ev) {
         void handleTransientAutoLoopFailure(workspaceId);
     }
     if (ev.kind === 'error' && ev.category === 'resume_failed') {
-        resumeFailedSet.add(workspaceId);
+        rememberResumeFailed(workspaceId, agentSessionId);
         clearStaleEngineSessionId(workspaceId);
     }
     if (ev.kind === 'session:ended') {
-        const isResumeFailed = resumeFailedSet.delete(workspaceId);
-        const before = tasksDoneSnapshot.get(workspaceId) ?? getDoneTaskCount(workspaceId);
+        if (sourceIsSuperseded && sourceController) {
+            settleSupersededSessionController(workspaceId, agentSessionId, sourceController);
+            return;
+        }
+        markSessionLifecycleOwnerEnded(workspaceId, agentSessionId, sourceController);
+        const isResumeFailed = consumeResumeFailed(workspaceId, agentSessionId);
+        const snapshot = consumeTaskProgressSnapshot(workspaceId, agentSessionId);
+        const before = snapshot?.doneCount ?? getDoneTaskCount(workspaceId);
         const after = getDoneTaskCount(workspaceId);
         const completedDelta = Math.max(0, after - before);
-        const taskStateBefore = taskStateSnapshot.get(workspaceId) ?? getTaskStateSignature(workspaceId);
+        const taskStateBefore = snapshot?.stateSignature ?? getTaskStateSignature(workspaceId);
         const taskStateAfter = getTaskStateSignature(workspaceId);
         const progressDelta = completedDelta > 0 || taskStateBefore !== taskStateAfter ? 1 : 0;
-        tasksDoneSnapshot.delete(workspaceId);
-        taskStateSnapshot.delete(workspaceId);
         clearPendingForSession(workspaceId, agentSessionId);
         // A completed/failed SDK session cannot resolve canUseTool anymore. Drop
         // its persisted prompts too, otherwise a reconnect resurrects a panel
@@ -601,7 +703,9 @@ function handleEvent(workspaceId, agentSessionId, ev) {
         // Must run BEFORE autoLoopService.onSessionEnded → spawnNextIteration →
         // startAgent, otherwise startAgent throws "Agent already running" because
         // the just-ended controller is still in the map.
-        onSessionEnded(workspaceId, agentSessionId, ev.exitCode, ev.reason, isResumeFailed);
+        const ownsWorkspaceLifecycle = onSessionEnded(workspaceId, agentSessionId, sourceController, ev.exitCode, ev.reason, isResumeFailed);
+        if (!ownsWorkspaceLifecycle)
+            return;
         // resume_failed exits with an error but the workspace is fine (stale id
         // cleared, next iteration will start fresh) — report 'completed' to
         // auto-loop so it continues.
@@ -664,21 +768,7 @@ function handleEvent(workspaceId, agentSessionId, ev) {
         }
     }
 }
-function onSessionEnded(workspaceId, agentSessionId, exitCode, reason, resumeFailed = false) {
-    const currentWorkspace = getWs(workspaceId);
-    const preserveQuotaBackoff = currentWorkspace?.status === 'quota';
-    const ctrl = controllers.get(workspaceId);
-    const wasStopping = ctrl?.status === 'stopping';
-    // Identity-preserving cleanup: only remove the controller if the map still
-    // points to this exact instance (a new controller may have been started in
-    // the meantime via stop-then-start).
-    if (ctrl && controllers.get(workspaceId) === ctrl) {
-        controllers.delete(workspaceId);
-    }
-    unregisterProcess(workspaceId);
-    if (!preserveQuotaBackoff) {
-        retryCounts.delete(workspaceId);
-    }
+function onSessionEnded(workspaceId, agentSessionId, sourceController, exitCode, reason, resumeFailed = false) {
     // Update the agent_sessions row
     try {
         const db = getDb();
@@ -687,8 +777,22 @@ function onSessionEnded(workspaceId, agentSessionId, exitCode, reason, resumeFai
     catch (err) {
         console.error('[orchestrator] Failed to update agent_sessions on exit:', err);
     }
+    const registeredController = controllers.get(workspaceId);
+    const isSuperseded = sourceController !== undefined && registeredController !== undefined && registeredController !== sourceController;
+    if (isSuperseded)
+        return false;
+    const currentWorkspace = getWs(workspaceId);
+    const preserveQuotaBackoff = currentWorkspace?.status === 'quota';
+    const wasStopping = sourceController?.status === 'stopping';
+    if (registeredController === sourceController) {
+        controllers.delete(workspaceId);
+    }
+    unregisterProcess(workspaceId);
+    if (!preserveQuotaBackoff) {
+        retryCounts.delete(workspaceId);
+    }
     if (wasStopping)
-        return;
+        return false;
     // When the session hit quota, handleQuota() already transitioned the
     // workspace to `quota` and armed the retry via quotaBackoffService.
     // Preserve that pending backoff in the quota path; otherwise clear any
@@ -704,7 +808,7 @@ function onSessionEnded(workspaceId, agentSessionId, exitCode, reason, resumeFai
         catch {
             // best-effort
         }
-        return;
+        return true;
     }
     // `reason` is authoritative (with the SDK engine `exitCode` is often null,
     // so reason='error'+exitCode=null would otherwise map wrongly to 'completed').
@@ -733,6 +837,7 @@ function onSessionEnded(workspaceId, agentSessionId, exitCode, reason, resumeFai
     catch {
         // best-effort
     }
+    return true;
 }
 // ── Public API ────────────────────────────────────────────────────────────────
 /**
@@ -816,7 +921,9 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
         mcpServers: buildMcpServers(workspaceId),
         env: ws ? buildAgentEnv(ws.projectPath) : undefined,
     };
-    const controller = new SessionController(workspaceId, agentSessionId, engine, (ev) => handleEvent(workspaceId, agentSessionId, ev));
+    let controller;
+    controller = new SessionController(workspaceId, agentSessionId, engine, (ev) => handleEvent(workspaceId, agentSessionId, controller, ev));
+    registerSessionLifecycleOwner(workspaceId, agentSessionId, controller);
     controllers.set(workspaceId, controller);
     // Kick off engine.start asynchronously. Errors surface as error events.
     void controller
@@ -836,12 +943,12 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
         .catch((err) => {
         console.error('[orchestrator] engine.start failed:', err);
         const message = err instanceof Error ? err.message : String(err);
-        handleEvent(workspaceId, agentSessionId, {
+        handleEvent(workspaceId, agentSessionId, controller, {
             kind: 'error',
             category: 'spawn_failed',
             message,
         });
-        handleEvent(workspaceId, agentSessionId, {
+        handleEvent(workspaceId, agentSessionId, controller, {
             kind: 'session:ended',
             reason: 'error',
             exitCode: null,
@@ -854,17 +961,23 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
  * alive — the current tool call is aborted and the agent waits for the next
  * user message.
  */
-export function interruptAgent(workspaceId) {
+export function interruptAgent(workspaceId, options = {}) {
     const ctrl = controllers.get(workspaceId);
     if (!ctrl) {
-        throw new Error(`No agent running for workspace '${workspaceId}'`);
+        throw new InterruptAgentError(`No agent running for workspace '${workspaceId}'`, 'no_agent_running');
+    }
+    if (options.expectedSessionId !== undefined && ctrl.agentSessionId !== options.expectedSessionId) {
+        throw new InterruptAgentError(`Session '${options.expectedSessionId}' is not active for workspace '${workspaceId}'`, 'session_not_active');
     }
     try {
         ctrl.interrupt();
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        throw new Error(`Failed to interrupt agent for workspace '${workspaceId}': ${message}`);
+        throw new InterruptAgentError(`Failed to interrupt agent for workspace '${workspaceId}': ${message}`, 'interrupt_failed');
+    }
+    if (options.disableAutoLoop && autoLoopService.getStatus(workspaceId).auto_loop) {
+        autoLoopService.disable(workspaceId, 'user-action');
     }
 }
 /** Gracefully stop an agent (the engine handles SIGTERM + SIGKILL). */
@@ -906,7 +1019,7 @@ export function stopAgent(workspaceId) {
     });
 }
 /** Write a user message to the running agent. */
-export function sendMessage(workspaceId, content, expectedSessionId) {
+export async function sendMessage(workspaceId, content, expectedSessionId) {
     const ctrl = controllers.get(workspaceId);
     if (!ctrl) {
         throw new Error(`No agent running for workspace '${workspaceId}'`);
@@ -915,7 +1028,34 @@ export function sendMessage(workspaceId, content, expectedSessionId) {
         throw new Error(`Session '${expectedSessionId}' is not active for workspace '${workspaceId}'`);
     }
     wakeupService.cancel(workspaceId, 'user-message');
-    return ctrl.sendMessage(content);
+    await ctrl.sendMessage(content);
+}
+export async function sendMessageForFallback(workspaceId, content) {
+    const capturedController = controllers.get(workspaceId);
+    if (!capturedController)
+        return { status: 'stopped' };
+    wakeupService.cancel(workspaceId, 'user-message');
+    try {
+        await capturedController.sendMessage(content);
+        return { status: 'sent', sessionId: capturedController.agentSessionId };
+    }
+    catch {
+        const deadline = Date.now() + FALLBACK_CONTROLLER_TURNOVER_TIMEOUT_MS;
+        while (controllers.get(workspaceId) === capturedController) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                throw new Error(`Timed out waiting for agent controller turnover for workspace '${workspaceId}'`);
+            }
+            await new Promise((resolve) => {
+                setTimeout(resolve, Math.min(FALLBACK_CONTROLLER_TURNOVER_POLL_MS, remaining));
+            });
+        }
+        const replacementController = controllers.get(workspaceId);
+        if (!replacementController)
+            return { status: 'stopped' };
+        await replacementController.sendMessage(content);
+        return { status: 'sent', sessionId: replacementController.agentSessionId };
+    }
 }
 /**
  * Render the user's answer to an AskUserQuestion as a markdown chat
@@ -1223,10 +1363,9 @@ export function forgetRateLimitInfo(workspaceId) {
     latestRateLimitInfo.delete(workspaceId);
 }
 /**
- * Null out the engine_session_id on all agent_sessions rows for a workspace
- * and clear the in-memory sessionIds cache. Called when a --resume attempt
- * fails ("No conversation found with session ID") so that the next startAgent
- * call starts a fresh conversation instead of retrying the stale ID.
+ * Null out every engine_session_id for the workspace and clear its cache.
+ * This runs only while the failing session owns the workspace, ensuring a
+ * future resume cannot fall back to an older stale engine session.
  */
 function clearStaleEngineSessionId(workspaceId) {
     try {
@@ -1412,4 +1551,16 @@ export function _runWatchdogForTest() {
     runWatchdog();
 }
 /** Test-only export. Not part of the public module API. */
-export const __test__ = { handleEvent, handleQuota };
+export const __test__ = {
+    getSessionLifecycleOwnerCount(workspaceId) {
+        return sessionLifecycleOwners.get(workspaceId)?.size ?? 0;
+    },
+    handleEvent(workspaceId, agentSessionId, ev) {
+        const sourceController = controllers.get(workspaceId);
+        if (sourceController && sourceController.agentSessionId !== agentSessionId) {
+            throw new Error(`Session '${agentSessionId}' is not active for workspace '${workspaceId}'`);
+        }
+        handleEvent(workspaceId, agentSessionId, sourceController, ev);
+    },
+    handleQuota,
+};

package/dist/server/services/agent/session-controller.js

@@ -4,6 +4,7 @@ export class SessionController {
     engine;
     onEvent;
     _engineProcess;
+    _startPromise;
     _status = 'running';
     get engineProcess() {
         return this._engineProcess;
@@ -15,15 +16,30 @@ export class SessionController {
         this.onEvent = onEvent;
     }
     async start(options) {
-        if (this._engineProcess)
+        if (this._startPromise)
             throw new Error('SessionController already started');
-        this._engineProcess = await this.engine.start(options, (ev) => this.handle(ev));
+        this._startPromise = this.startEngine(options);
+        await this._startPromise;
+    }
+    async startEngine(options) {
+        const process = await this.engine.start(options, (ev) => this.handle(ev));
+        this._engineProcess = process;
+        if (this._status === 'stopping') {
+            this._engineProcess = undefined;
+            await process.stop();
+            return;
+        }
         this._status = 'running';
     }
-    sendMessage(content) {
+    async sendMessage(content) {
+        if (!this._startPromise)
+            throw new Error('SessionController not started');
+        await this._startPromise;
+        if (this._status === 'stopping')
+            throw new Error('SessionController is stopping');
         if (!this._engineProcess)
             throw new Error('SessionController not started');
-        this._engineProcess.sendMessage(content);
+        await this._engineProcess.sendMessage(content);
     }
     interrupt() {
         if (!this._engineProcess)

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

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { WORKTREES_PATH } from '../../shared/consts.js';
 import { isValidProjectColor } from '../../shared/project-colors.js';
 import { isValidSkillSuite } from '../../shared/skill-suite-prompts.js';
+import { DEFAULT_WHIP_SHORTCUT, isValidWhipShortcut } from '../../shared/whip-shortcut.js';
 import { listClaudeMcpEntries } from '../utils/mcp-client.js';
 import { getSettingsPath } from '../utils/paths.js';
 import { InvalidWorktreesPathError, resolveGlobalWorktreesRoot, sanitizeWorktreesPath, validateWorktreesPath, } from '../utils/worktree-paths.js';
@@ -110,6 +111,12 @@ export const DEFAULT_WORKSPACE_TAGS = [
  * one pre-selected on the workspace creation page.
  */
 export const DEFAULT_BRANCH_PREFIXES = ['feature', 'fix', 'hotfix', 'chore', 'refactor', 'docs', 'test'];
+function normalizeWhipShortcut(value) {
+    return isValidWhipShortcut(value) ? value : DEFAULT_WHIP_SHORTCUT;
+}
+function normalizeWhipVolume(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1 ? value : 1;
+}
 /**
  * Sanitize a raw branch-prefix list: trim, strip surrounding slashes, drop
  * entries that aren't valid git branch segments, dedupe, cap length. Returns
@@ -803,6 +810,28 @@ const settingsMigrations = [
                 global.bitbucketUsername = '';
         },
     },
+    {
+        version: 51,
+        name: 'add-whip-feature-toggle',
+        migrate: ({ global }) => {
+            if (typeof global.whipEnabled !== 'boolean')
+                global.whipEnabled = false;
+        },
+    },
+    {
+        version: 52,
+        name: 'add-whip-keyboard-shortcut',
+        migrate: ({ global }) => {
+            global.whipShortcut = normalizeWhipShortcut(global.whipShortcut);
+        },
+    },
+    {
+        version: 53,
+        name: 'add-whip-volume',
+        migrate: ({ global }) => {
+            global.whipVolume = normalizeWhipVolume(global.whipVolume);
+        },
+    },
 ];
 /** Current settings schema version — always equals the highest migration version. */
 export const SETTINGS_SCHEMA_VERSION = settingsMigrations.length > 0 ? settingsMigrations[settingsMigrations.length - 1].version : 0;
@@ -899,6 +928,9 @@ function defaultSettings() {
             notionEnabled: true,
             sentryEnabled: true,
             showThinkingBlocks: true,
+            whipEnabled: false,
+            whipShortcut: DEFAULT_WHIP_SHORTCUT,
+            whipVolume: 1,
             tags: [...DEFAULT_WORKSPACE_TAGS],
             branchPrefixes: [...DEFAULT_BRANCH_PREFIXES],
             worktreesPath: WORKTREES_PATH,
@@ -982,6 +1014,9 @@ export function runSettingsMigrations(raw) {
         }
     }
     current.global.worktreesPath = sanitizeWorktreesPath(current.global.worktreesPath);
+    current.global.whipEnabled = current.global.whipEnabled === true;
+    current.global.whipShortcut = normalizeWhipShortcut(current.global.whipShortcut);
+    current.global.whipVolume = normalizeWhipVolume(current.global.whipVolume);
     current.schemaVersion = version;
     return current;
 }
@@ -1010,15 +1045,18 @@ function readSettings() {
         return defaults;
     }
     const originalVersion = parsed.schemaVersion;
+    const globalBeforeMigrations = JSON.stringify(parsed.global ?? null);
     const migrated = runSettingsMigrations(parsed);
+    const normalizedGlobalFields = JSON.stringify(migrated.global) !== globalBeforeMigrations;
     // 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 || restoredGlobalFields) {
+    // Persist if migrations bumped the version, known fields were normalized,
+    // or missing global fields were restored.
+    if (migrated.schemaVersion !== originalVersion || normalizedGlobalFields || restoredGlobalFields) {
         writeSettings(migrated);
     }
     return migrated;
@@ -1299,6 +1337,9 @@ export function updateGlobalSettings(data) {
         'notionEnabled',
         'sentryEnabled',
         'showThinkingBlocks',
+        'whipEnabled',
+        'whipShortcut',
+        'whipVolume',
         'tags',
         'branchPrefixes',
         'worktreesPath',
@@ -1335,6 +1376,15 @@ export function updateGlobalSettings(data) {
         const sanitized = sanitizeBranchPrefixes(filtered.branchPrefixes);
         filtered.branchPrefixes = sanitized.length > 0 ? sanitized : settings.global.branchPrefixes;
     }
+    if (filtered.whipVolume !== undefined) {
+        const rawWhipVolume = filtered.whipVolume;
+        const whipVolume = typeof rawWhipVolume === 'number'
+            ? rawWhipVolume
+            : typeof rawWhipVolume === 'string' && rawWhipVolume.trim().length > 0
+                ? Number(rawWhipVolume)
+                : Number.NaN;
+        filtered.whipVolume = Number.isFinite(whipVolume) ? Math.max(0, Math.min(1, whipVolume)) : 1;
+    }
     for (const key of [
         'audioNotificationVolume',
         'audioQuestionVolume',
@@ -1356,6 +1406,12 @@ export function updateGlobalSettings(data) {
         const t = Number(filtered.voiceTemperature);
         filtered.voiceTemperature = Number.isFinite(t) ? Math.max(0, Math.min(1, t)) : settings.global.voiceTemperature;
     }
+    if (filtered.whipEnabled !== undefined) {
+        filtered.whipEnabled = filtered.whipEnabled === true;
+    }
+    if (filtered.whipShortcut !== undefined) {
+        filtered.whipShortcut = normalizeWhipShortcut(filtered.whipShortcut);
+    }
     if (filtered.worktreesPath !== undefined) {
         filtered.worktreesPath = validateWorktreesPath(filtered.worktreesPath, { allowEmpty: false });
         ensureGlobalWorktreesRootExists(filtered.worktreesPath);

package/dist/shared/whip-shortcut.js

@@ -0,0 +1,41 @@
+export const DEFAULT_WHIP_SHORTCUT = 'mod+shift+x';
+export const WHIP_SHORTCUT_MODIFIERS = ['mod', 'ctrl', 'meta', 'alt', 'shift'];
+export const RESERVED_WHIP_SHORTCUTS = [
+    'mod+w',
+    'mod+shift+w',
+    'ctrl+w',
+    'ctrl+shift+w',
+    'meta+w',
+    'meta+shift+w',
+];
+const RESERVED_WHIP_SHORTCUT_SET = new Set(RESERVED_WHIP_SHORTCUTS);
+const NON_KEY_TOKENS = new Set(['control', ...WHIP_SHORTCUT_MODIFIERS]);
+export function isReservedWhipShortcut(value) {
+    return RESERVED_WHIP_SHORTCUT_SET.has(value);
+}
+export function parseWhipShortcut(value) {
+    if (typeof value !== 'string' || value.length === 0 || value !== value.toLowerCase())
+        return null;
+    if (isReservedWhipShortcut(value))
+        return null;
+    const tokens = value.split('+');
+    if (tokens.some((token) => token.length === 0))
+        return null;
+    const key = tokens.at(-1);
+    if (!key || !/^[a-z0-9][a-z0-9_-]*$/.test(key) || NON_KEY_TOKENS.has(key))
+        return null;
+    const modifiers = tokens.slice(0, -1);
+    const parsedModifiers = new Set();
+    let previousIndex = -1;
+    for (const modifier of modifiers) {
+        const index = WHIP_SHORTCUT_MODIFIERS.indexOf(modifier);
+        if (index <= previousIndex)
+            return null;
+        previousIndex = index;
+        parsedModifiers.add(modifier);
+    }
+    return { modifiers: parsedModifiers, key };
+}
+export function isValidWhipShortcut(value) {
+    return parseWhipShortcut(value) !== null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loicngr/kobo",
-  "version": "1.11.6",
+  "version": "1.11.7",
   "description": "Kōbō — multi-workspace agent manager for Claude Code. Orchestrates isolated git worktrees with dev servers, Notion integration, and MCP tools.",
   "type": "module",
   "license": "GPL-3.0-or-later",