Bugfix: Native macOS shortcuts are read-only

- The four macOS-native commands (`app.quit`/`hide`/`hideOthers`/`showAll`) are AppKit `PredefinedMenuItem`s: macOS owns both the behavior and the accelerator, so editing them in Settings was a double illusion (removal didn't disable the OS accelerator; a new binding dispatched into a void).
- Registry: add a `nativeShortcut?: true` flag on the `Command` interface, set on exactly those four entries. New `NATIVE_SHORTCUT_COMMAND_IDS` export is the single source of truth; `command-handlers/types.ts` now sources its Family-1 dispatch-exempt list from it. A `command-registry.test.ts` set-equality test pins the flag to the list and proves the dispatch-exempt round-trip.
- Editor: native rows render read-only — plain static pills, a small "macOS" badge with the tooltip "macOS handles this shortcut. Cmdr can't change it.", and no `+`/`×`/reset/add-slot. `Show all` shows `(none)` unframed plus the badge. Normal rows keep every affordance.
- Honest conflict capture: when a captured combo conflicts with a native command (native wins even in a mixed set), the banner reads `⌘H is reserved by macOS (Hide Cmdr) and won't reach Cmdr. Pick a different combo.` and offers ONLY Cancel — no "Remove from other" / "Keep both" (both would be a lie). Purely non-native conflicts keep the resolvable banner. Classification extracted to the pure `keyboard-shortcuts-banner.ts`.
- Store: `initializeShortcuts` drops any persisted native customization on load (the dev `shortcuts.json` had `app.hide: []`); `setShortcut`/`addShortcut`/`removeShortcut` no-op with a `log.warn` for native commands (defense in depth — MCP shortcut edits route through these mutators too). `resetShortcut` stays permissive (delete-only). New `isNativeShortcutCommand` predicate.
- Scrollbar gutter: reserve `scrollbar-gutter: stable` on `.commands-list` so the trailing `+`/badge controls never sit under an overlay scrollbar when the list scrolls.
- Migrated palette / store tests that used native ids as plain rebindable fixtures to non-native commands; added store-guard, healing, read-only-row, reserved-banner, and conflict-detection tests. Updated colocated CLAUDE.md docs.

Author: vdavid

apps/desktop/src/lib/command-palette/CommandPalette.test.ts

@@ -487,8 +487,10 @@ describe('CommandPalette', () => {
   })
 
   it('renders the effective custom binding, not the registry default', async () => {
-    // app.quit defaults to ⌘Q; rebind it and the row must show the custom combo.
-    setShortcut('app.quit', 0, '⌘0')
+    // view.showHidden defaults to ⌘⇧.; rebind it and the row must show the custom
+    // combo. (A non-native command: the macOS-native commands like app.quit can't
+    // be rebound and aren't shown in the palette anyway.)
+    setShortcut('view.showHidden', 0, '⌘0')
 
     const target = document.createElement('div')
     mount(CommandPalette, {
@@ -497,7 +499,7 @@ describe('CommandPalette', () => {
     })
     await tick()
 
-    expect(shortcutTextsFor(target, 'app.quit')).toEqual(['⌘0'])
+    expect(shortcutTextsFor(target, 'view.showHidden')).toEqual(['⌘0'])
   })
 
   it('caps the shown shortcuts at three', async () => {
@@ -519,8 +521,9 @@ describe('CommandPalette', () => {
 
   it('updates a rendered row live when the binding changes while the palette is open', async () => {
     // Custom bindings are stored verbatim (no platform conversion), so they assert
-    // cleanly regardless of the test platform.
-    setShortcut('app.quit', 0, '⌘7')
+    // cleanly regardless of the test platform. (view.showHidden is a normal,
+    // rebindable command — unlike the macOS-native ones.)
+    setShortcut('view.showHidden', 0, '⌘7')
 
     const target = document.createElement('div')
     mount(CommandPalette, {
@@ -529,13 +532,13 @@ describe('CommandPalette', () => {
     })
     await tick()
 
-    expect(shortcutTextsFor(target, 'app.quit')).toEqual(['⌘7'])
+    expect(shortcutTextsFor(target, 'view.showHidden')).toEqual(['⌘7'])
 
     // Simulate a rebind (the MCP / Settings path) while the palette stays open.
-    setShortcut('app.quit', 0, '⌘8')
+    setShortcut('view.showHidden', 0, '⌘8')
     flushSync()
 
-    expect(shortcutTextsFor(target, 'app.quit')).toEqual(['⌘8'])
+    expect(shortcutTextsFor(target, 'view.showHidden')).toEqual(['⌘8'])
   })
 
   it('does not throw if the previously focused element is no longer in the DOM', async () => {

apps/desktop/src/lib/commands/CLAUDE.md

@@ -27,6 +27,7 @@ interface Command {
   scope: CommandScope // hierarchical, display-only (does not enforce routing)
   showInPalette: boolean
   shortcuts: string[] // e.g. ['⌘Q'], ['Backspace', '⌘↑']
+  nativeShortcut?: true // macOS owns behavior AND accelerator (PredefinedMenuItem); read-only in the editor
   description?: string
 }
 
@@ -186,10 +187,16 @@ scope enforcement centralized would require the command module to know about all
 conflict detection in the shortcuts system and for display in settings; the actual dispatch is the responsibility of
 each component's keydown handler or the centralized dispatch map.
 
-**Decision**: `showInPalette: false` for native macOS commands (quit, hide, hide others, show all). **Why**: These
-commands are handled by macOS via `PredefinedMenuItems` with native selectors (`terminate:`, `hide:`, etc.). The native
-menu accelerators handle the keyboard shortcuts directly. Including them in the JS shortcut dispatch map would cause
-double-execution: the native handler fires AND the JS handler fires.
+**Decision**: `showInPalette: false` AND `nativeShortcut: true` for native macOS commands (quit, hide, hide others, show
+all). **Why**: These commands are handled by macOS via `PredefinedMenuItems` with native selectors (`terminate:`,
+`hide:`, etc.). The native menu accelerators handle the keyboard shortcuts directly. Including them in the JS shortcut
+dispatch map would cause double-execution: the native handler fires AND the JS handler fires. AppKit owns BOTH the
+behavior and the accelerator, so Cmdr can neither rebind nor intercept them — editing them in Settings would be a double
+illusion (removal doesn't disable the OS accelerator; a new binding dispatches into a void). `nativeShortcut: true` (set
+on exactly the `NATIVE_SHORTCUT_COMMAND_IDS` exported from `command-registry.ts`) is the single source of truth that
+makes the shortcuts editor render these rows read-only and makes the store mutators refuse to write them.
+`command-handlers/types.ts` sources its Family-1 dispatch-exempt list from the same `NATIVE_SHORTCUT_COMMAND_IDS`, so
+the "AppKit owns this" fact lives in one place; `command-registry.test.ts` pins the flag set-equal to that list.
 
 **Decision**: `isMacOS()` called at module load time for platform-specific command names and visibility. **Why**: Some
 commands only make sense on macOS (`Get info`, `Quick look`, `Show in Finder`). Rather than filtering at render time,

apps/desktop/src/lib/commands/command-registry.test.ts

@@ -1,7 +1,8 @@
 import { describe, it, expect } from 'vitest'
-import { commands, getPaletteCommands, updateLicenseCommandName } from './command-registry'
+import { commands, getPaletteCommands, updateLicenseCommandName, NATIVE_SHORTCUT_COMMAND_IDS } from './command-registry'
 import { COMMAND_IDS, isCommandId, type CommandId } from './command-ids'
 import type { CommandArgs, CommandDispatchArgs } from './types'
+import { DISPATCH_EXEMPT_IDS } from '../../routes/(main)/command-handlers/types'
 
 /**
  * The exact set of commands the palette shows the user. Pinned so a new
@@ -129,6 +130,45 @@ describe('command-registry id sync', () => {
   })
 })
 
+describe('nativeShortcut flag', () => {
+  it('the source list names the four macOS-native commands', () => {
+    // Sanity guard against a silently-failing import: the set-equality below
+    // would falsely pass if `NATIVE_SHORTCUT_COMMAND_IDS` resolved to undefined.
+    expect([...NATIVE_SHORTCUT_COMMAND_IDS].sort()).toEqual(
+      ['app.hide', 'app.hideOthers', 'app.quit', 'app.showAll'].sort(),
+    )
+  })
+
+  it('marks exactly the commands in NATIVE_SHORTCUT_COMMAND_IDS', () => {
+    // The `nativeShortcut` registry flag and `NATIVE_SHORTCUT_COMMAND_IDS` are
+    // two views of the same set: macOS owns both the behavior AND the accelerator
+    // (PredefinedMenuItems), so the editor must render them read-only and the
+    // store must refuse to rebind them. Keying the flag off the list keeps the
+    // sites from drifting.
+    const flagged = new Set(commands.filter((c) => c.nativeShortcut).map((c) => c.id))
+    const expected = new Set<string>(NATIVE_SHORTCUT_COMMAND_IDS)
+    expect(flagged).toEqual(expected)
+  })
+
+  it('every native command is also dispatch-exempt (Family 1)', () => {
+    // The native commands are handler-less by design (AppKit runs them). The
+    // dispatch-exempt list sources Family 1 from the same registry list, so this
+    // also proves that single-source wiring round-trips.
+    const exempt = new Set<string>(DISPATCH_EXEMPT_IDS)
+    for (const id of NATIVE_SHORTCUT_COMMAND_IDS) {
+      expect(exempt.has(id), `${id} must be dispatch-exempt`).toBe(true)
+    }
+  })
+
+  it('only ever uses `true` for the flag (never `false`/`undefined` noise)', () => {
+    for (const cmd of commands) {
+      if (cmd.nativeShortcut !== undefined) {
+        expect(cmd.nativeShortcut).toBe(true)
+      }
+    }
+  })
+})
+
 describe('palette-visible command set', () => {
   it('shows exactly the pinned set of commands (no silent additions or removals)', () => {
     const paletteIds = getPaletteCommands().map((c) => c.id)

apps/desktop/src/lib/commands/command-registry.ts

@@ -11,6 +11,17 @@
 import type { Command } from './types'
 import { isMacOS } from '$lib/shortcuts/key-capture'
 
+/**
+ * The macOS-native commands: AppKit `PredefinedMenuItem`s own BOTH the behavior
+ * and the accelerator (`terminate:`, `hide:`, `hideOtherApplications:`,
+ * `unhideAllApplications:`). Cmdr can neither rebind nor intercept them, so the
+ * shortcuts editor renders them read-only and the store refuses to customize
+ * them. Single source of truth: the registry entries below carry
+ * `nativeShortcut: true` for exactly these ids (pinned by `command-registry.test.ts`),
+ * and `command-handlers/types.ts` sources its Family-1 dispatch-exempt list from here.
+ */
+export const NATIVE_SHORTCUT_COMMAND_IDS = ['app.quit', 'app.hide', 'app.hideOthers', 'app.showAll'] as const
+
 // `Command.id` is the `CommandId` union derived from `COMMAND_IDS` in
 // `command-ids.ts`. Adding an entry here whose id isn't in that tuple is a
 // compile error; a tuple id with no entry here is caught by the set-equality
@@ -23,11 +34,19 @@ export const commands: Command[] = [
   // ============================================================================
   // Native-only: handled by PredefinedMenuItems via macOS selectors (hide:, hideOtherApplications:,
   // unhideAllApplications:, terminate:). showInPalette: false keeps them out of the JS shortcut
-  // dispatch map; the native menu accelerators handle the keyboard shortcuts directly.
-  { id: 'app.quit', name: 'Quit Cmdr', scope: 'App', showInPalette: false, shortcuts: ['⌘Q'] },
-  { id: 'app.hide', name: 'Hide Cmdr', scope: 'App', showInPalette: false, shortcuts: ['⌘H'] },
-  { id: 'app.hideOthers', name: 'Hide others', scope: 'App', showInPalette: false, shortcuts: ['⌥⌘H'] },
-  { id: 'app.showAll', name: 'Show all', scope: 'App', showInPalette: false, shortcuts: [] },
+  // dispatch map; the native menu accelerators handle the keyboard shortcuts directly. `nativeShortcut`
+  // makes the editor read-only and the store refuse to rebind them (NATIVE_SHORTCUT_COMMAND_IDS above).
+  { id: 'app.quit', name: 'Quit Cmdr', scope: 'App', showInPalette: false, shortcuts: ['⌘Q'], nativeShortcut: true },
+  { id: 'app.hide', name: 'Hide Cmdr', scope: 'App', showInPalette: false, shortcuts: ['⌘H'], nativeShortcut: true },
+  {
+    id: 'app.hideOthers',
+    name: 'Hide others',
+    scope: 'App',
+    showInPalette: false,
+    shortcuts: ['⌥⌘H'],
+    nativeShortcut: true,
+  },
+  { id: 'app.showAll', name: 'Show all', scope: 'App', showInPalette: false, shortcuts: [], nativeShortcut: true },
   { id: 'app.about', name: 'About Cmdr', scope: 'App', showInPalette: true, shortcuts: [] },
   { id: 'app.licenseKey', name: 'See license details', scope: 'App', showInPalette: true, shortcuts: [] },
   {

apps/desktop/src/lib/commands/types.ts

@@ -132,6 +132,14 @@ export interface Command {
   showInPalette: boolean
   /** Keyboard shortcuts (like ['⌘⇧P', 'F1']) */
   shortcuts: string[]
+  /**
+   * macOS owns this command's behavior AND its accelerator via a
+   * `PredefinedMenuItem` (`terminate:`, `hide:`, `hideOtherApplications:`,
+   * `unhideAllApplications:`). Cmdr can neither rebind nor intercept it, so the
+   * shortcuts editor renders it read-only and the store refuses to customize it.
+   * Set only on the four `NATIVE_SHORTCUT_COMMAND_IDS` (Family 1 dispatch-exempt).
+   */
+  nativeShortcut?: true
   /** Optional description for long-form help */
   description?: string
   /**

apps/desktop/src/lib/settings/sections/CLAUDE.md

@@ -35,6 +35,7 @@ Parents: [`../CLAUDE.md`](../CLAUDE.md) (registry, store, applier, search) and
 | `license-section-utils.ts`         | Pure label/status formatters extracted from `LicenseSection` for testability                                                                                                                                                                                                                                                                                                                                                                |
 | `ram-gauge-utils.ts`               | Pure stacked-bar segment math for `AiLocalSection`'s memory gauge (used → projected → free, plus warning thresholds)                                                                                                                                                                                                                                                                                                                        |
 | `keyboard-shortcuts-grouping.ts`   | Pure scope→group logic for `KeyboardShortcutsSection` (one titled group per `CommandScope`, fixed order). Tested by the set-equality regression guard                                                                                                                                                                                                                                                                                       |
+| `keyboard-shortcuts-banner.ts`     | Pure conflict-banner classification for `KeyboardShortcutsSection` (`classifyConflict` → native vs normal; `reservedByMacOsMessage`). Native conflicts win even in a mixed set. Unit-tested                                                                                                                                                                                                                                                 |
 
 Each section ships with an `*.a11y.test.ts` (axe-core tier-3). `McpServerSection`, `UpdatesSection`, `SearchSection`,
 `FileSystemWatchingSection`, and `KeyboardShortcutsSection` also have functional `*.test.ts` / `*.svelte.test.ts` files;
@@ -142,6 +143,33 @@ after that lands as an overwrite of that pill instead of an append. It needs a p
 command, the result is visible immediately, and any fix (re-deriving the slot on `shortcutChangeCounter` bumps) costs
 more state than the race is worth. Revisit only if it shows up in practice.
 
+## macOS-native rows are read-only
+
+The four `nativeShortcut` commands (`app.quit`/`hide`/`hideOthers`/`showAll`) render read-only: their combos show as
+plain `.shortcut-pill.static` spans (no click-to-edit), with no `+` add, no `×` remove, no reset button, and never the
+add slot. Each native row also carries a small "macOS" badge (`.macos-badge`) with a tooltip: "macOS handles this
+shortcut. Cmdr can't change it." (`Show all` has no default binding, so it renders its `(none)` unframed plus the
+badge.) The branch is keyed off `isNativeShortcutCommand(command.id)` from `$lib/shortcuts`. This is honest: AppKit owns
+both the behavior and the accelerator (see `lib/shortcuts/CLAUDE.md` § "macOS-native commands are not customizable"), so
+an editable control here would be a double illusion. The store also refuses these writes as defense in depth, so the UI
+and the store agree.
+
+## Conflict banner: native conflicts are honest (reserved by macOS), others are resolvable
+
+`handleKeyCapture` classifies the captured combo's conflicts via the pure `classifyConflict`
+(`keyboard-shortcuts-banner.ts`):
+
+- If the conflict set includes a `nativeShortcut` command (even in a MIXED set with a normal command — the native wins,
+  because the combo is unusable regardless), the banner reads
+  `⌘H is reserved by macOS (Hide Cmdr) and won't reach Cmdr. Pick a different combo.` (`reservedByMacOsMessage`) and
+  offers ONLY Cancel. No "Remove from other" (removing Cmdr's binding doesn't free the OS accelerator) and no "Keep
+  both" (the user's binding would never fire) — both would be a lie.
+- A purely non-native conflict keeps the resolvable banner (Remove-from-other / Keep-both / Cancel).
+
+`conflictWarning` carries `{ shortcut, conflict: ConflictKind }`; the template branches on `conflict.kind`. The
+classification logic is extracted to the pure `keyboard-shortcuts-banner.ts` (unit-tested) to keep the section component
+lean.
+
 ## Conflict banner: the editing pill reads as a pending decision
 
 When a captured combo conflicts, `handleKeyCapture` sets `conflictWarning` and returns without saving (the banner offers