fix(desktop): make macOS dev permission grants reliable

apps/desktop/.gitignore

@@ -1,3 +1,5 @@
 # Playwright E2E run artifacts: traces, videos, screenshots, last-run state.
 test-results/
 resources/workers/
+.maka-dev/
+.maka-dev-session/

apps/desktop/README.md

@@ -2,6 +2,44 @@
 
 The Electron desktop app: `main` (Node/Electron main process) + `preload` (context bridge) + `renderer` (React UI). This file covers the three-layer split and the IPC contract. For build/test commands and the test-layer selection guide, see the top-level `README.md`; for the renderer interior, see `src/renderer/README.md`.
 
+## macOS development permissions
+
+`npm run dev` and `npm start` launch macOS development builds through a generated, ad-hoc-signed
+`apps/desktop/.maka-dev/Maka Dev.app`. The stable bundle identity lets macOS TCC
+retain Accessibility and Screen Recording grants while renderer and main-process
+code change. The generated app is ignored by Git and is rebuilt automatically
+when the installed Electron version changes. Run
+`npm --workspace @maka/desktop run prepare:dev-app` to prepare it explicitly.
+
+The scripts launch the bundle through macOS LaunchServices rather than executing
+its internal binary from a terminal. This is required for TCC to attribute the
+running process to `Maka Dev` and recognize the stored grants.
+The launcher remains alive as the development-session supervisor until the
+terminal receives Ctrl-C or SIGTERM. The generated bundle contains a small local
+bootstrap that reads a PID-validated, per-worktree session file, restoring the
+Vite URL and a curated environment-variable allowlist before importing the main
+process. macOS's Screen Recording “Quit & Reopen” action can therefore reconnect
+to the same HMR session without relying on command-line arguments that the
+system restart discards. Session files live in the ignored
+`apps/desktop/.maka-dev-session/` directory, outside the rebuildable app bundle,
+and are written atomically with mode `0600`. Startup is acknowledged only after
+the single-instance lock and main-process boot succeed; failures and timeouts are
+reported in the terminal instead of leaving a windowless supervisor running.
+
+The default profile is `~/Library/Application Support/Maka Dev-<worktree-id>`.
+This keeps development isolated from the packaged Maka profile and lets separate
+worktrees run concurrently. An explicit `--user-data-dir` still takes precedence.
+
+Only one supervised Maka Dev session can use a worktree at a time. Runtime
+preparation is protected by a PID lock, and shutdown targets the app PID recorded
+by that supervisor rather than every process sharing the development bundle ID.
+Runtime rebuilds refuse to proceed while that worktree has a live supervisor.
+
+Grant permissions to **Maka Dev**, not a generic Electron entry. Screen Recording
+changes require restarting the development app. Recreating the app or changing
+its Electron version may require granting permissions again. Other platforms
+continue to use their normal Electron development executable.
+
 ## Three layers
 
 | Layer | Path | Role |

apps/desktop/package.json

@@ -9,7 +9,8 @@
   "type": "module",
   "main": "dist/main/main.js",
   "scripts": {
-    "start": "electron .",
+    "start": "node scripts/start-dev-app.mjs",
+    "prepare:dev-app": "node scripts/prepare-dev-app.mjs",
     "dev": "node scripts/dev.mjs",
     "dev:hmr": "node scripts/dev.mjs",
     "storybook": "storybook dev -p 6006 -c .storybook",
@@ -58,6 +59,7 @@
   },
   "devDependencies": {
     "@ant-design/icons-svg": "4.5.0",
+    "@electron/asar": "3.4.1",
     "@fontsource-variable/geist": "^5.2.9",
     "@fontsource-variable/geist-mono": "^5.2.8",
     "@playwright/test": "^1.61.1",