bosun 0.36.29 → 0.37.0

package/.env.example

@@ -4,8 +4,8 @@
 # All variables are optional unless marked [REQUIRED].
 # Boolean flags use true/false (preferred). Legacy 1/0 is still accepted.
 # Profile guidance:
-#  - Local development: DEVMODE=true, DEVMODE_MONITOR_MONITOR_ENABLED=true, *_TRANSPORT=sdk
-#  - End-user stable:  DEVMODE=false, DEVMODE_MONITOR_MONITOR_ENABLED=false, *_TRANSPORT=sdk
+#  - Local development: DEVMODE=true, *_TRANSPORT=sdk
+#  - End-user stable:  DEVMODE=false, *_TRANSPORT=sdk
 
 # ─── Task Claims and Coordination ─────────────────────────────────────────────
 # Shared state manager enables distributed task coordination across multiple
@@ -222,10 +222,6 @@ VOICE_DELEGATE_EXECUTOR=codex-sdk
 # SENTINEL_RESTART_BACKOFF_SEC=5
 # After manual /stop, suppress auto-restart for this many minutes (default: 10)
 # SENTINEL_MANUAL_STOP_HOLD_MIN=10
-# In devmode, validate monitor-monitor freshness before restart decisions (default: 1)
-# SENTINEL_MONITOR_MONITOR_CHECK_ENABLED=true
-# Max acceptable monitor-monitor age in minutes (default: 20)
-# SENTINEL_MONITOR_MONITOR_MAX_AGE_MIN=20
 
 # ─── Notification Batching (RECOMMENDED) ─────────────────────────────────────
 # Batch notifications into periodic summaries instead of spamming individual messages
@@ -776,31 +772,6 @@ VK_RECOVERY_PORT=54089
 # scripts check for this and exit silently if not present, preventing
 # hooks from firing in standalone Copilot/Codex/Claude sessions.
 
-# ─── Devmode Monitor-Monitor (24/7 reliability guardian) ───────────────────
-# Prompt is injected directly from bosun source (no .github/agents file required).
-# Enabled by default in devmode source checkouts. Set to false to disable.
-# DEVMODE_MONITOR_MONITOR_ENABLED=true
-# Poll interval for monitor-monitor runs (milliseconds). Default: 300000 (5 min)
-# DEVMODE_MONITOR_MONITOR_INTERVAL_MS=300000
-# Status stream update interval (milliseconds). Default: 1800000 (30 min)
-# DEVMODE_MONITOR_MONITOR_STATUS_INTERVAL_MS=1800000
-# Per-run timeout before watchdog abort/failover (milliseconds).
-# Default is 21600000 (6h) for long-running reliability analysis sessions.
-# 30 minutes (1800000) is safe if you prefer faster failover on stuck runs.
-# Watchdog abort triggers at timeout+60s, then accelerated force-reset at +120s.
-# Set this explicitly to avoid inherited shell
-# defaults (for example DEVMODE_AUTO_CODE_FIX_TIMEOUT_MS=300000).
-# DEVMODE_MONITOR_MONITOR_TIMEOUT_MS=1800000
-# Optional timeout bounds (applied only when set):
-# DEVMODE_MONITOR_MONITOR_TIMEOUT_MIN_MS=600000
-# DEVMODE_MONITOR_MONITOR_TIMEOUT_MAX_MS=7200000
-# Optional override for Claude tool access (comma-separated)
-# DEVMODE_MONITOR_MONITOR_CLAUDE_ALLOWED_TOOLS=Read,Write,Edit,Grep,Glob,Bash,WebSearch,Task,Skill
-# Legacy alias: DEVMODE_AUTO_CODE_FIX=true also enables this subsystem.
-# Legacy timeout fallback: if DEVMODE_MONITOR_MONITOR_TIMEOUT_MS is unset and
-# DEVMODE_AUTO_CODE_FIX_TIMEOUT_MS is set, monitor-monitor will use it (and
-# still apply DEVMODE_MONITOR_MONITOR_TIMEOUT_MIN_MS/MAX_MS bounds if provided).
-
 # ─── Copilot SDK (Primary Agent) ─────────────────────────────────────────────
 # Requires GitHub Copilot CLI installed and authenticated.
 # Set to true to disable Copilot SDK (primary agent) usage.
@@ -1046,7 +1017,6 @@ COPILOT_CLOUD_DISABLED=true
 # Files in that folder are loaded automatically and are intended for per-project customization.
 # You can also override any prompt path explicitly with env vars:
 # BOSUN_PROMPT_PLANNER=.bosun/agents/task-planner.md
-# BOSUN_PROMPT_MONITOR_MONITOR=.bosun/agents/monitor-monitor.md
 # BOSUN_PROMPT_TASK_EXECUTOR=.bosun/agents/task-executor.md
 # BOSUN_PROMPT_REVIEWER=.bosun/agents/reviewer.md
 # BOSUN_PROMPT_SDK_CONFLICT_RESOLVER=.bosun/agents/sdk-conflict-resolver.md

package/agent-prompts.mjs

@@ -17,16 +17,6 @@ const PROMPT_DEFS = [
     filename: "orchestrator.md",
     description: "Primary task execution prompt for autonomous task agents.",
   },
-  {
-    key: "planner",
-    filename: "task-planner.md",
-    description: "Backlog planning prompt used by task planner runs.",
-  },
-  {
-    key: "monitorMonitor",
-    filename: "monitor-monitor.md",
-    description: "Long-running reliability monitor prompt used in devmode.",
-  },
   {
     key: "taskExecutor",
     filename: "task-executor.md",
@@ -199,68 +189,6 @@ apply patterns discovered by previous agents:
 After completing a task, if you discovered a non-obvious pattern, workaround, or
 domain-specific fact, write or update a skill file at \`.bosun/skills/<module>.md\`
 so the next agent benefits from your investigation.
-`,
-  planner: `# Codex-Task-Planner Agent
-
-You generate production-grade backlog tasks for autonomous executors.
-
-## Mission
-
-1. Analyze current repo and delivery state.
-2. Identify highest-value next work.
-3. Create concrete, execution-ready tasks.
-
-## Requirements
-
-- Avoid vague tasks and duplicate work.
-- Balance reliability fixes, feature delivery, and debt reduction.
-- Every task includes implementation steps, acceptance criteria, and verification plan.
-- Every task title starts with one size label: [xs], [s], [m], [l], [xl], [xxl].
-- Prefer task sets that can run in parallel with low file overlap.
-- Do not call any kanban API, CLI, or external service to create tasks.
-  The workflow will automatically materialize your output into kanban tasks.
-- Output must be machine-parseable JSON — see Output Contract below.
-- Task objects must be valid for Bosun backlog creation with fields:
-  \'title\', \'description\', \'implementation_steps\', \'acceptance_criteria\',
-  \'verification\', optional \'base_branch\'.
-- Do not emit empty or placeholder tasks. Every task must be actionable and execution-ready.
-
-## Output Contract (MANDATORY — STRICT)
-
-Your ENTIRE response must be a single fenced JSON block. Do NOT include any
-text, commentary, explanations, or markdown before or after the JSON block.
-The downstream parser extracts JSON from fenced blocks — any deviation causes
-task creation to hard-fail.
-
-Return exactly this shape:
-
-\`\`\`json
-{
-  "tasks": [
-    {
-      "title": "[m] feat(veid): example task title",
-      "description": "Problem statement and scope",
-      "implementation_steps": ["step 1", "step 2"],
-      "acceptance_criteria": ["criterion 1", "criterion 2"],
-      "verification": ["test/check 1", "test/check 2"],
-      "base_branch": "origin/veid"
-    }
-  ]
-}
-\`\`\`
-
-Rules:
-- The \`tasks\` array MUST contain at least the requested task count.
-- Do NOT output partial JSON, truncated arrays, or commentary mixed with JSON.
-- Keep titles unique and specific.
-- Keep file overlap low across tasks to maximize parallel execution.
-- Descriptions must include concrete implementation details, not generic intent text.
-- Include verification commands/checks that a worker can run without additional planning.
-- **Module branch routing:** When the task title follows conventional commit format
-  \`feat(module):\` or \`fix(module):\`, set \`base_branch\` to \`origin/<module>\`.
-  This routes the task to the module's dedicated branch for parallel, isolated development.
-  Examples: \`feat(veid):\` → \`"base_branch": "origin/veid"\`, \`fix(market):\` → \`"base_branch": "origin/market"\`.
-  Omit \`base_branch\` for cross-cutting tasks that span multiple modules.
 `,
   taskManager: `# Bosun Task Manager Agent
 
@@ -305,8 +233,6 @@ bosun task stats --json
 # Bulk import from JSON file
 bosun task import ./backlog.json
 
-# Trigger AI task planner
-bosun task plan --count 5 --reason "Sprint planning"
 \`\`\`
 
 ### 2. REST API (port 18432 — always available when bosun daemon runs)
@@ -440,23 +366,6 @@ draft → todo → inprogress → inreview → done
 7. **Module branch routing** — When a task title follows conventional commit format
    \`feat(module):\` or \`fix(module):\`, set \`baseBranch\` to \`origin/<module>\` to route the task
    to the module's dedicated branch for parallel, isolated development.
-`,
-  monitorMonitor: `# Bosun-Monitor Agent
-
-You are the always-on reliability guardian for bosun in devmode.
-
-## Core Role
-
-- Monitor logs, failures, and agent/orchestrator behavior continuously.
-- Immediately fix reliability regressions and execution blockers.
-- Improve prompt/tool/executor reliability to reduce failure loops.
-- Only when runtime is healthy, perform code-analysis improvements.
-
-## Constraints
-
-- Operate only in devmode.
-- Do not commit/push/initiate PR lifecycle changes in this context.
-- Apply focused fixes, run focused validation, and keep monitoring.
 `,
   taskExecutor: `# {{TASK_ID}} — {{TASK_TITLE}}
 

package/config.mjs

@@ -506,7 +506,9 @@ function normalizeExecutorModels(executor, models, variant = "DEFAULT") {
     );
     return inferred.length > 0 ? inferred : [...known];
   }
-  return input.filter((model) => known.has(model));
+  // Preserve custom/deployment slugs in addition to known models so user-provided
+  // model routing survives normalization (for example Azure deployment names).
+  return [...new Set(input.filter(Boolean))];
 }
 
 function normalizeExecutorEntry(entry, index = 0, total = 1) {
@@ -540,49 +542,8 @@ function normalizeExecutorEntry(entry, index = 0, total = 1) {
   };
 }
 
-function buildDefaultTriggerTemplates({
-  plannerMode,
-  plannerPerCapitaThreshold,
-  plannerIdleSlotThreshold,
-  plannerDedupHours,
-} = {}) {
+function buildDefaultTriggerTemplates() {
   return [
-    {
-      id: "task-planner",
-      name: "Task Planner",
-      description: "Create planning tasks when backlog/slot metrics indicate replenishment.",
-      enabled: false,
-      action: "task-planner",
-      trigger: {
-        anyOf: [
-          {
-            kind: "metric",
-            metric: "backlogPerCapita",
-            operator: "lt",
-            value: plannerPerCapitaThreshold,
-          },
-          {
-            kind: "metric",
-            metric: "idleSlots",
-            operator: "gte",
-            value: plannerIdleSlotThreshold,
-          },
-          {
-            kind: "metric",
-            metric: "backlogRemaining",
-            operator: "eq",
-            value: 0,
-          },
-        ],
-      },
-      minIntervalMinutes: Math.max(1, Number(plannerDedupHours || 6) * 60),
-      config: {
-        plannerMode,
-        defaultTaskCount: Number(process.env.TASK_PLANNER_DEFAULT_COUNT || "30"),
-        executor: "auto",
-        model: "auto",
-      },
-    },
     {
       id: "daily-review-digest",
       name: "Daily Review Digest",
@@ -1990,32 +1951,8 @@ export function loadConfig(argv = process.argv, options = {}) {
     "summary"
   ).toLowerCase();
 
-  // ── Task Planner ─────────────────────────────────────────
-  // Mode: "codex-sdk" (default) runs Codex directly, "kanban" creates a VK
-  // task for a real agent to plan, "disabled" turns off the planner entirely.
-  const plannerMode = (
-    process.env.TASK_PLANNER_MODE ||
-    configData.plannerMode ||
-    (mode === "generic" ? "disabled" : "codex-sdk")
-  ).toLowerCase();
-  const plannerPerCapitaThreshold = Number(
-    process.env.TASK_PLANNER_PER_CAPITA_THRESHOLD || "1",
-  );
-  const plannerIdleSlotThreshold = Number(
-    process.env.TASK_PLANNER_IDLE_SLOT_THRESHOLD || "1",
-  );
-  const plannerDedupHours = Number(process.env.TASK_PLANNER_DEDUP_HOURS || "6");
-  const plannerDedupMs = Number.isFinite(plannerDedupHours)
-    ? plannerDedupHours * 60 * 60 * 1000
-    : 24 * 60 * 60 * 1000;
-
   const triggerSystemDefaults = Object.freeze({
-    templates: buildDefaultTriggerTemplates({
-      plannerMode,
-      plannerPerCapitaThreshold,
-      plannerIdleSlotThreshold,
-      plannerDedupHours,
-    }),
+    templates: buildDefaultTriggerTemplates(),
     defaults: Object.freeze({
       executor: "auto",
       model: "auto",
@@ -2290,12 +2227,6 @@ export function loadConfig(argv = process.argv, options = {}) {
     telegramCommandEnabled,
     telegramVerbosity,
 
-    // Task Planner
-    plannerMode,
-    plannerPerCapitaThreshold,
-    plannerIdleSlotThreshold,
-    plannerDedupHours,
-    plannerDedupMs,
     triggerSystem,
 
     // GitHub Reconciler
@@ -2349,7 +2280,7 @@ export function loadConfig(argv = process.argv, options = {}) {
         configData.trustedCreators ||
         process.env.BOSUN_TRUSTED_CREATORS?.split(",") ||
         [],
-      // Enforce all new tasks go to backlog unless planner config allows auto-push
+      // Enforce all new tasks go to backlog
       enforceBacklog:
         typeof configData.enforceBacklog === "boolean"
           ? configData.enforceBacklog

package/copilot-shell.mjs

@@ -469,9 +469,26 @@ async function ensureClientStarted() {
   const modeLabel = clientOptions.cliUrl ? "remote" : "local (stdio)";
   console.log(`[copilot-shell] starting client in ${modeLabel} mode`);
 
+  const START_TIMEOUT_MS =
+    Number(process.env.COPILOT_START_TIMEOUT_MS) || 20_000;
+
   await withSanitizedOpenAiEnv(async () => {
     copilotClient = new Cls(clientOptions);
-    await copilotClient.start();
+    await Promise.race([
+      copilotClient.start(),
+      new Promise((_, reject) =>
+        setTimeout(
+          () =>
+            reject(
+              new Error(
+                `Copilot CLI failed to start within ${START_TIMEOUT_MS / 1000}s — ` +
+                  `verify COPILOT_CLI_PATH or run \`gh auth login\``,
+              ),
+            ),
+          START_TIMEOUT_MS,
+        ),
+      ),
+    ]);
   });
   clientStarted = true;
   console.log("[copilot-shell] client started");

package/desktop/desktop-shortcuts.mjs

@@ -36,6 +36,7 @@ export const SCOPE_LOCAL = "local";
  * @property {string}  description        Longer description for tooltips/help.
  * @property {string}  defaultAccelerator Default Electron accelerator string.
  * @property {string}  scope              "global" | "local"
+ * @property {boolean} [globalEligible]   If true the user can opt this local shortcut in as a global one.
  * @property {string}  [group]            Optional display grouping.
  */
 
@@ -61,26 +62,35 @@ export const DEFAULT_SHORTCUTS = [
   {
     id: "bosun.voice.call",
     label: "Start Voice Call",
-    description: "Open the voice companion and start a voice call",
+    description:
+      "Open the voice companion and start a voice call. " +
+      "Only fires when Bosun is focused unless 'Enable as global shortcut' is on.",
     defaultAccelerator: "CmdOrCtrl+Shift+Space",
-    scope: SCOPE_GLOBAL,
-    group: "Global",
+    scope: SCOPE_LOCAL,
+    globalEligible: true,
+    group: "Voice",
   },
   {
     id: "bosun.voice.video",
     label: "Start Video Call",
-    description: "Open the voice companion and start a video call",
+    description:
+      "Open the voice companion and start a video call. " +
+      "Only fires when Bosun is focused unless 'Enable as global shortcut' is on.",
     defaultAccelerator: "CmdOrCtrl+Shift+K",
-    scope: SCOPE_GLOBAL,
-    group: "Global",
+    scope: SCOPE_LOCAL,
+    globalEligible: true,
+    group: "Voice",
   },
   {
     id: "bosun.voice.toggle",
     label: "Toggle Voice Companion",
-    description: "Show or hide the floating voice companion window",
+    description:
+      "Show or hide the floating voice companion window. " +
+      "Only fires when Bosun is focused unless 'Enable as global shortcut' is on.",
     defaultAccelerator: "CmdOrCtrl+Shift+V",
-    scope: SCOPE_GLOBAL,
-    group: "Global",
+    scope: SCOPE_LOCAL,
+    globalEligible: true,
+    group: "Voice",
   },
 
   // ── Local ─ menu accelerators, only when app is focused ───────────────────
@@ -217,6 +227,12 @@ const actionHandlers = new Map();
  */
 let customizations = new Map();
 
+/**
+ * Per-shortcut global-scope overrides for globalEligible shortcuts.
+ * Map<id, boolean> — true = user has opted this local shortcut in as global.
+ */
+let scopeOverrides = new Map();
+
 /** Path to the JSON config file. */
 let configFilePath = null;
 
@@ -233,7 +249,9 @@ let globalsActive = false;
  */
 export function initShortcuts(configDir) {
   configFilePath = resolve(configDir, "desktop-shortcuts.json");
-  customizations = _loadCustomizations(configFilePath);
+  const loaded = _loadPersisted(configFilePath);
+  customizations = loaded.customizations;
+  scopeOverrides = loaded.scopeOverrides;
 }
 
 /**
@@ -248,7 +266,24 @@ export function onShortcut(id, handler) {
 }
 
 /**
- * Register all SCOPE_GLOBAL shortcuts with Electron.
+ * Return true when a shortcut should currently be registered as a global.
+ * A shortcut qualifies if:
+ *  - Its catalog scope is SCOPE_GLOBAL, OR
+ *  - It is globalEligible AND the user has opted it in via setShortcutScope().
+ *
+ * @param {ShortcutDef} def
+ * @returns {boolean}
+ */
+function _isRegisteredGlobal(def) {
+  if (def.scope === SCOPE_GLOBAL) return true;
+  if (def.globalEligible && scopeOverrides.get(def.id) === true) return true;
+  return false;
+}
+
+/**
+ * Register all global shortcuts with Electron.
+ * Includes catalog-scope SCOPE_GLOBAL entries + any globalEligible shortcuts
+ * that the user has opted in to fire system-wide.
  * Silently skips shortcuts that have no registered action handler.
  * Safe to call multiple times — old registrations are cleared first.
  */
@@ -257,7 +292,7 @@ export function registerGlobalShortcuts() {
   _unregisterAllGlobals();
 
   for (const def of DEFAULT_SHORTCUTS) {
-    if (def.scope !== SCOPE_GLOBAL) continue;
+    if (!_isRegisteredGlobal(def)) continue;
 
     const accelerator = getEffectiveAccelerator(def.id);
     if (!accelerator) continue; // disabled by user
@@ -311,6 +346,15 @@ export function getAllShortcuts() {
         ? (overrideValue ?? null)
         : def.defaultAccelerator,
       scope: def.scope,
+      /** Whether this shortcut can be opted in as a system-wide global. */
+      globalEligible: def.globalEligible ?? false,
+      /**
+       * Whether this globalEligible shortcut is currently firing system-wide.
+       * Always true for catalog-scope SCOPE_GLOBAL shortcuts.
+       */
+      isGlobalEnabled:
+        def.scope === SCOPE_GLOBAL ||
+        (def.globalEligible === true && scopeOverrides.get(def.id) === true),
       group: def.group ?? "",
       isCustomized: hasOverride && overrideValue !== undefined,
       isDisabled: hasOverride && overrideValue === null,
@@ -342,6 +386,35 @@ export function getEffectiveAccelerator(id) {
  * @param   {string|null} accelerator  Electron accelerator string, or null to disable.
  * @returns {{ ok: boolean, error?: string }}
  */
+/**
+ * Enable or disable global (system-wide) firing for a globalEligible shortcut.
+ * Has no effect on shortcuts that are catalog-level SCOPE_GLOBAL.
+ *
+ * @param   {string}  id
+ * @param   {boolean} isGlobal
+ * @returns {{ ok: boolean, error?: string }}
+ */
+export function setShortcutScope(id, isGlobal) {
+  const def = DEFAULT_SHORTCUTS.find((d) => d.id === id);
+  if (!def) return { ok: false, error: `Unknown shortcut: ${id}` };
+  if (!def.globalEligible) {
+    return { ok: false, error: `Shortcut '${id}' does not support scope override.` };
+  }
+
+  if (isGlobal) {
+    scopeOverrides.set(id, true);
+  } else {
+    scopeOverrides.delete(id);
+  }
+
+  _savePersisted(configFilePath, customizations, scopeOverrides);
+
+  // Re-apply so the shortcut is registered / unregistered immediately.
+  if (globalsActive) registerGlobalShortcuts();
+
+  return { ok: true };
+}
+
 export function setShortcut(id, accelerator) {
   const def = DEFAULT_SHORTCUTS.find((d) => d.id === id);
   if (!def) return { ok: false, error: `Unknown shortcut: ${id}` };
@@ -362,10 +435,10 @@ export function setShortcut(id, accelerator) {
   }
 
   customizations.set(id, accelerator === undefined ? null : accelerator);
-  _saveCustomizations(configFilePath, customizations);
+  _savePersisted(configFilePath, customizations, scopeOverrides);
 
-  // Re-apply globals when a global shortcut is changed.
-  if (def.scope === SCOPE_GLOBAL && globalsActive) {
+  // Re-apply globals when a global/globally-enabled shortcut is changed.
+  if (_isRegisteredGlobal(def) && globalsActive) {
     registerGlobalShortcuts();
   }
 
@@ -383,9 +456,9 @@ export function resetShortcut(id) {
   if (!def) return { ok: false, error: `Unknown shortcut: ${id}` };
 
   customizations.delete(id);
-  _saveCustomizations(configFilePath, customizations);
+  _savePersisted(configFilePath, customizations, scopeOverrides);
 
-  if (def.scope === SCOPE_GLOBAL && globalsActive) {
+  if (_isRegisteredGlobal(def) && globalsActive) {
     registerGlobalShortcuts();
   }
 
@@ -399,7 +472,8 @@ export function resetShortcut(id) {
  */
 export function resetAllShortcuts() {
   customizations.clear();
-  _saveCustomizations(configFilePath, customizations);
+  scopeOverrides.clear();
+  _savePersisted(configFilePath, customizations, scopeOverrides);
 
   if (globalsActive) registerGlobalShortcuts();
   return { ok: true };
@@ -409,7 +483,10 @@ export function resetAllShortcuts() {
 
 function _unregisterAllGlobals() {
   for (const def of DEFAULT_SHORTCUTS) {
-    if (def.scope !== SCOPE_GLOBAL) continue;
+    // Unregister any shortcut that was or could be registered as global.
+    // This covers catalog-level globals AND globalEligible shortcuts regardless
+    // of the current scopeOverride value (handles transitions cleanly).
+    if (def.scope !== SCOPE_GLOBAL && !def.globalEligible) continue;
 
     // Unregister both the currently effective AND the default to be safe
     // when an override is being replaced.
@@ -454,25 +531,65 @@ function _normalizeAcc(acc) {
   return String(acc).toLowerCase().replace(/\s+/g, "");
 }
 
-function _loadCustomizations(filePath) {
+/**
+ * Load both accelerator customizations and scope overrides from disk.
+ * File format:
+ * {
+ *   "shortcut.id": "Accelerator" | null,
+ *   "_scopes": { "shortcut.id": true }
+ * }
+ * The "_scopes" key is reserved and never treated as a shortcut ID.
+ *
+ * @param {string} filePath
+ * @returns {{ customizations: Map<string, string|null>, scopeOverrides: Map<string, boolean> }}
+ */
+function _loadPersisted(filePath) {
   try {
-    if (!existsSync(filePath)) return new Map();
+    if (!existsSync(filePath)) {
+      return { customizations: new Map(), scopeOverrides: new Map() };
+    }
     const raw = JSON.parse(readFileSync(filePath, "utf8"));
-    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return new Map();
-    return new Map(
-      Object.entries(raw).map(([k, v]) => [k, v === null ? null : String(v)]),
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      return { customizations: new Map(), scopeOverrides: new Map() };
+    }
+
+    const scopesRaw = raw._scopes;
+    const scopeOverridesMap = new Map(
+      scopesRaw && typeof scopesRaw === "object" && !Array.isArray(scopesRaw)
+        ? Object.entries(scopesRaw)
+            .filter(([, v]) => v === true)
+            .map(([k]) => [k, true])
+        : [],
+    );
+
+    const customizationsMap = new Map(
+      Object.entries(raw)
+        .filter(([k]) => k !== "_scopes")
+        .map(([k, v]) => [k, v === null ? null : String(v)]),
     );
+
+    return { customizations: customizationsMap, scopeOverrides: scopeOverridesMap };
   } catch {
-    return new Map();
+    return { customizations: new Map(), scopeOverrides: new Map() };
   }
 }
 
-function _saveCustomizations(filePath, map) {
+/**
+ * Persist both accelerator customizations and scope overrides to disk.
+ *
+ * @param {string|null}             filePath
+ * @param {Map<string, string|null>} customizationsMap
+ * @param {Map<string, boolean>}     scopeOverridesMap
+ */
+function _savePersisted(filePath, customizationsMap, scopeOverridesMap) {
   if (!filePath) return;
   try {
     const dir = dirname(filePath);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    const obj = Object.fromEntries(map);
+    const obj = Object.fromEntries(customizationsMap);
+    if (scopeOverridesMap.size > 0) {
+      obj._scopes = Object.fromEntries(scopeOverridesMap);
+    }
     writeFileSync(filePath, JSON.stringify(obj, null, 2), "utf8");
   } catch (err) {
     console.warn("[shortcuts] failed to save:", err?.message || err);