v0.5.0: NomadArch - Binary-Free Mode Release

Features:
- Binary-Free Mode: No OpenCode binary required
- NomadArch Native mode with free Zen models
- Native session management
- Provider routing (Zen, Qwen, Z.AI)
- Fixed MCP connection with explicit connectAll()
- Updated installers and launchers for all platforms
- UI binary selector with Native option

Free Models Available:
- GPT-5 Nano (400K context)
- Grok Code Fast 1 (256K context)
- GLM-4.7 (205K context)
- Doubao Seed Code (256K context)
- Big Pickle (200K context)

packages/electron-app/electron/main/ipc.ts

@@ -0,0 +1,112 @@
+import { BrowserWindow, dialog, ipcMain, type OpenDialogOptions } from "electron"
+import path from "path"
+import type { CliProcessManager, CliStatus } from "./process-manager"
+import {
+  listUsers,
+  createUser,
+  updateUser,
+  deleteUser,
+  verifyPassword,
+  setActiveUser,
+  createGuestUser,
+  getActiveUser,
+  getUserDataRoot,
+} from "./user-store"
+
+interface DialogOpenRequest {
+  mode: "directory" | "file"
+  title?: string
+  defaultPath?: string
+  filters?: Array<{ name?: string; extensions: string[] }>
+}
+
+interface DialogOpenResult {
+  canceled: boolean
+  paths: string[]
+}
+
+export function setupCliIPC(mainWindow: BrowserWindow, cliManager: CliProcessManager) {
+  cliManager.on("status", (status: CliStatus) => {
+    if (!mainWindow.isDestroyed()) {
+      mainWindow.webContents.send("cli:status", status)
+    }
+  })
+
+  cliManager.on("ready", (status: CliStatus) => {
+    if (!mainWindow.isDestroyed()) {
+      mainWindow.webContents.send("cli:ready", status)
+    }
+  })
+
+  cliManager.on("error", (error: Error) => {
+    if (!mainWindow.isDestroyed()) {
+      mainWindow.webContents.send("cli:error", { message: error.message })
+    }
+  })
+
+  ipcMain.handle("cli:getStatus", async () => cliManager.getStatus())
+
+  ipcMain.handle("cli:restart", async () => {
+    const devMode = process.env.NODE_ENV === "development"
+    await cliManager.stop()
+    return cliManager.start({ dev: devMode })
+  })
+
+  ipcMain.handle("users:list", async () => listUsers())
+  ipcMain.handle("users:active", async () => getActiveUser())
+  ipcMain.handle("users:create", async (_, payload: { name: string; password: string }) => {
+    const user = createUser(payload.name, payload.password)
+    return user
+  })
+  ipcMain.handle("users:update", async (_, payload: { id: string; name?: string; password?: string }) => {
+    const user = updateUser(payload.id, { name: payload.name, password: payload.password })
+    return user
+  })
+  ipcMain.handle("users:delete", async (_, payload: { id: string }) => {
+    deleteUser(payload.id)
+    return { success: true }
+  })
+  ipcMain.handle("users:createGuest", async () => {
+    const user = createGuestUser()
+    return user
+  })
+  ipcMain.handle("users:login", async (_, payload: { id: string; password?: string }) => {
+    const ok = verifyPassword(payload.id, payload.password ?? "")
+    if (!ok) {
+      return { success: false }
+    }
+    const user = setActiveUser(payload.id)
+    const root = getUserDataRoot(user.id)
+    cliManager.setUserEnv({
+      CODENOMAD_USER_DIR: root,
+      CLI_CONFIG: path.join(root, "config.json"),
+    })
+    await cliManager.stop()
+    const devMode = process.env.NODE_ENV === "development"
+    await cliManager.start({ dev: devMode })
+    return { success: true, user }
+  })
+
+  ipcMain.handle("dialog:open", async (_, request: DialogOpenRequest): Promise<DialogOpenResult> => {
+    const properties: OpenDialogOptions["properties"] =
+      request.mode === "directory" ? ["openDirectory", "createDirectory"] : ["openFile"]
+
+    const filters = request.filters?.map((filter) => ({
+      name: filter.name ?? "Files",
+      extensions: filter.extensions,
+    }))
+
+    const windowTarget = mainWindow.isDestroyed() ? undefined : mainWindow
+    const dialogOptions: OpenDialogOptions = {
+      title: request.title,
+      defaultPath: request.defaultPath,
+      properties,
+      filters,
+    }
+    const result = windowTarget
+      ? await dialog.showOpenDialog(windowTarget, dialogOptions)
+      : await dialog.showOpenDialog(dialogOptions)
+
+    return { canceled: result.canceled, paths: result.filePaths }
+  })
+}

packages/electron-app/electron/main/main.ts

@@ -0,0 +1,522 @@
+import { app, BrowserView, BrowserWindow, nativeImage, session, shell } from "electron"
+import { existsSync } from "fs"
+import { dirname, join } from "path"
+import { fileURLToPath } from "url"
+import { createApplicationMenu } from "./menu"
+import { setupCliIPC } from "./ipc"
+import { CliProcessManager } from "./process-manager"
+import { ensureDefaultUsers, getActiveUser, getUserDataRoot, clearGuestUsers } from "./user-store"
+
+const mainFilename = fileURLToPath(import.meta.url)
+const mainDirname = dirname(mainFilename)
+
+const isMac = process.platform === "darwin"
+
+const cliManager = new CliProcessManager()
+let mainWindow: BrowserWindow | null = null
+let currentCliUrl: string | null = null
+let pendingCliUrl: string | null = null
+let showingLoadingScreen = false
+let preloadingView: BrowserView | null = null
+
+// Retry logic constants
+const MAX_RETRY_ATTEMPTS = 5
+const LOAD_TIMEOUT_MS = 30000
+let retryAttempts = 0
+
+if (isMac) {
+  app.commandLine.appendSwitch("disable-spell-checking")
+}
+
+// Windows: Use Edge WebView2 rendering for better performance
+if (process.platform === "win32") {
+  app.commandLine.appendSwitch("enable-features", "WebViewTagWebComponent,WebView2")
+  app.commandLine.appendSwitch("disable-gpu-sandbox")
+  app.commandLine.appendSwitch("enable-gpu-rasterization")
+  app.commandLine.appendSwitch("enable-zero-copy")
+  app.commandLine.appendSwitch("disable-background-timer-throttling")
+  app.commandLine.appendSwitch("disable-renderer-backgrounding")
+}
+
+function getIconPath() {
+  if (app.isPackaged) {
+    return join(process.resourcesPath, "icon.png")
+  }
+
+  return join(mainDirname, "../resources/icon.png")
+}
+
+type LoadingTarget =
+  | { type: "url"; source: string }
+  | { type: "file"; source: string }
+
+function resolveDevLoadingUrl(): string | null {
+  if (app.isPackaged) {
+    return null
+  }
+  const devBase = process.env.VITE_DEV_SERVER_URL || process.env.ELECTRON_RENDERER_URL
+  if (!devBase) {
+    return null
+  }
+
+  try {
+    const normalized = devBase.endsWith("/") ? devBase : `${devBase}/`
+    return new URL("loading.html", normalized).toString()
+  } catch (error) {
+    console.warn("[cli] failed to construct dev loading URL", devBase, error)
+    return null
+  }
+}
+
+function resolveLoadingTarget(): LoadingTarget {
+  const devUrl = resolveDevLoadingUrl()
+  if (devUrl) {
+    return { type: "url", source: devUrl }
+  }
+  const filePath = resolveLoadingFilePath()
+  return { type: "file", source: filePath }
+}
+
+function resolveLoadingFilePath() {
+  const candidates = [
+    join(app.getAppPath(), "dist/renderer/loading.html"),
+    join(process.resourcesPath, "dist/renderer/loading.html"),
+    join(mainDirname, "../dist/renderer/loading.html"),
+  ]
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate
+    }
+  }
+
+  return join(app.getAppPath(), "dist/renderer/loading.html")
+}
+
+function loadLoadingScreen(window: BrowserWindow) {
+  const target = resolveLoadingTarget()
+  const loader =
+    target.type === "url"
+      ? window.loadURL(target.source)
+      : window.loadFile(target.source)
+
+  loader.catch((error) => {
+    console.error("[cli] failed to load loading screen:", error)
+  })
+}
+
+// Calculate exponential backoff delay
+function getRetryDelay(attempt: number): number {
+  return Math.min(1000 * Math.pow(2, attempt), 16000) // 1s, 2s, 4s, 8s, 16s max
+}
+
+// Show user-friendly error screen
+function showErrorScreen(window: BrowserWindow, errorMessage: string) {
+  const errorHtml = `
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <style>
+        body {
+          margin: 0;
+          padding: 40px;
+          font-family: system-ui, -apple-system, sans-serif;
+          background: #1a1a1a;
+          color: #fff;
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          justify-content: center;
+          min-height: 100vh;
+          box-sizing: border-box;
+        }
+        .error-icon { font-size: 48px; margin-bottom: 20px; }
+        h1 { margin: 0 0 16px; font-size: 24px; font-weight: 600; }
+        p { margin: 0 0 24px; color: #888; font-size: 14px; text-align: center; max-width: 400px; }
+        .error-code { font-family: monospace; background: #2a2a2a; padding: 8px 16px; border-radius: 6px; font-size: 12px; color: #f87171; margin-bottom: 24px; }
+        button {
+          background: #6366f1;
+          color: white;
+          border: none;
+          padding: 12px 32px;
+          border-radius: 8px;
+          font-size: 14px;
+          font-weight: 600;
+          cursor: pointer;
+          transition: all 0.2s;
+        }
+        button:hover { background: #818cf8; transform: scale(1.02); }
+      </style>
+    </head>
+    <body>
+      <div class="error-icon">⚠️</div>
+      <h1>Connection Failed</h1>
+      <p>NomadArch couldn't connect to the development server after multiple attempts. Please ensure the server is running.</p>
+      <div class="error-code">${errorMessage}</div>
+      <button onclick="location.reload()">Retry</button>
+    </body>
+    </html>
+  `
+  window.loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(errorHtml)}`)
+}
+
+function getAllowedRendererOrigins(): string[] {
+  const origins = new Set<string>()
+  const rendererCandidates = [currentCliUrl, process.env.VITE_DEV_SERVER_URL, process.env.ELECTRON_RENDERER_URL]
+  for (const candidate of rendererCandidates) {
+    if (!candidate) {
+      continue
+    }
+    try {
+      origins.add(new URL(candidate).origin)
+    } catch (error) {
+      console.warn("[cli] failed to parse origin for", candidate, error)
+    }
+  }
+  return Array.from(origins)
+}
+
+function shouldOpenExternally(url: string): boolean {
+  try {
+    const parsed = new URL(url)
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return true
+    }
+    const allowedOrigins = getAllowedRendererOrigins()
+    return !allowedOrigins.includes(parsed.origin)
+  } catch {
+    return false
+  }
+}
+
+function setupNavigationGuards(window: BrowserWindow) {
+  const handleExternal = (url: string) => {
+    shell.openExternal(url).catch((error) => console.error("[cli] failed to open external URL", url, error))
+  }
+
+  window.webContents.setWindowOpenHandler(({ url }) => {
+    if (shouldOpenExternally(url)) {
+      handleExternal(url)
+      return { action: "deny" }
+    }
+    return { action: "allow" }
+  })
+
+  window.webContents.on("will-navigate", (event, url) => {
+    if (shouldOpenExternally(url)) {
+      event.preventDefault()
+      handleExternal(url)
+    }
+  })
+}
+
+let cachedPreloadPath: string | null = null
+function getPreloadPath() {
+  if (cachedPreloadPath && existsSync(cachedPreloadPath)) {
+    return cachedPreloadPath
+  }
+
+  const candidates = [
+    join(process.resourcesPath, "preload/index.js"),
+    join(mainDirname, "../preload/index.js"),
+    join(mainDirname, "../preload/index.cjs"),
+    join(mainDirname, "../../preload/index.cjs"),
+    join(mainDirname, "../../electron/preload/index.cjs"),
+    join(app.getAppPath(), "preload/index.cjs"),
+    join(app.getAppPath(), "electron/preload/index.cjs"),
+  ]
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      cachedPreloadPath = candidate
+      return candidate
+    }
+  }
+
+  return join(mainDirname, "../preload/index.js")
+}
+
+function applyUserEnvToCli() {
+  const active = getActiveUser()
+  if (!active) {
+    const fallback = ensureDefaultUsers()
+    const fallbackRoot = getUserDataRoot(fallback.id)
+    cliManager.setUserEnv({
+      CODENOMAD_USER_DIR: fallbackRoot,
+      CLI_CONFIG: join(fallbackRoot, "config.json"),
+    })
+    return
+  }
+  const root = getUserDataRoot(active.id)
+  cliManager.setUserEnv({
+    CODENOMAD_USER_DIR: root,
+    CLI_CONFIG: join(root, "config.json"),
+  })
+}
+
+function destroyPreloadingView(target?: BrowserView | null) {
+  const view = target ?? preloadingView
+  if (!view) {
+    return
+  }
+
+  try {
+    const contents = view.webContents as any
+    contents?.destroy?.()
+  } catch (error) {
+    console.warn("[cli] failed to destroy preloading view", error)
+  }
+
+  if (!target || view === preloadingView) {
+    preloadingView = null
+  }
+}
+
+function createWindow() {
+  const prefersDark = true
+  const backgroundColor = prefersDark ? "#1a1a1a" : "#ffffff"
+  const iconPath = getIconPath()
+
+  mainWindow = new BrowserWindow({
+    width: 1400,
+    height: 900,
+    minWidth: 800,
+    minHeight: 600,
+    backgroundColor,
+    icon: iconPath,
+    title: "NomadArch 1.0",
+    webPreferences: {
+      preload: getPreloadPath(),
+      contextIsolation: true,
+      nodeIntegration: false,
+      spellcheck: !isMac,
+    },
+  })
+
+  setupNavigationGuards(mainWindow)
+
+  if (isMac) {
+    mainWindow.webContents.session.setSpellCheckerEnabled(false)
+  }
+
+  showingLoadingScreen = true
+  currentCliUrl = null
+  loadLoadingScreen(mainWindow)
+
+  if (process.env.NODE_ENV === "development" && process.env.NOMADARCH_OPEN_DEVTOOLS === "true") {
+    mainWindow.webContents.openDevTools({ mode: "detach" })
+  }
+
+  createApplicationMenu(mainWindow)
+  setupCliIPC(mainWindow, cliManager)
+
+  mainWindow.on("closed", () => {
+    destroyPreloadingView()
+    mainWindow = null
+    currentCliUrl = null
+    pendingCliUrl = null
+    showingLoadingScreen = false
+  })
+
+  if (pendingCliUrl) {
+    const url = pendingCliUrl
+    pendingCliUrl = null
+    startCliPreload(url)
+  }
+}
+
+function showLoadingScreen(force = false) {
+  if (!mainWindow || mainWindow.isDestroyed()) {
+    return
+  }
+
+  if (showingLoadingScreen && !force) {
+    return
+  }
+
+  destroyPreloadingView()
+  showingLoadingScreen = true
+  currentCliUrl = null
+  pendingCliUrl = null
+  loadLoadingScreen(mainWindow)
+}
+
+function startCliPreload(url: string) {
+  if (!mainWindow || mainWindow.isDestroyed()) {
+    pendingCliUrl = url
+    return
+  }
+
+  if (currentCliUrl === url && !showingLoadingScreen) {
+    return
+  }
+
+  pendingCliUrl = url
+  destroyPreloadingView()
+
+  if (!showingLoadingScreen) {
+    showLoadingScreen(true)
+  }
+
+  const view = new BrowserView({
+    webPreferences: {
+      contextIsolation: true,
+      nodeIntegration: false,
+      spellcheck: !isMac,
+    },
+  })
+
+  preloadingView = view
+
+  view.webContents.once("did-finish-load", () => {
+    if (preloadingView !== view) {
+      destroyPreloadingView(view)
+      return
+    }
+    finalizeCliSwap(url)
+  })
+
+  view.webContents.loadURL(url).catch((error) => {
+    console.error("[cli] failed to preload CLI view:", error)
+    if (preloadingView === view) {
+      destroyPreloadingView(view)
+    }
+  })
+}
+
+function finalizeCliSwap(url: string) {
+  destroyPreloadingView()
+
+  if (!mainWindow || mainWindow.isDestroyed()) {
+    pendingCliUrl = url
+    return
+  }
+
+  showingLoadingScreen = false
+  currentCliUrl = url
+  pendingCliUrl = null
+
+  // Reset retry counter on new URL
+  retryAttempts = 0
+
+  const loadWithRetry = () => {
+    if (!mainWindow || mainWindow.isDestroyed()) return
+
+    // Set timeout for load
+    const timeoutId = setTimeout(() => {
+      console.warn(`[cli] Load timeout after ${LOAD_TIMEOUT_MS}ms`)
+      handleLoadError(new Error(`Load timeout after ${LOAD_TIMEOUT_MS}ms`))
+    }, LOAD_TIMEOUT_MS)
+
+    mainWindow.loadURL(url)
+      .then(() => {
+        clearTimeout(timeoutId)
+        retryAttempts = 0 // Reset on success
+        console.info("[cli] Successfully loaded CLI view")
+      })
+      .catch((error) => {
+        clearTimeout(timeoutId)
+        handleLoadError(error)
+      })
+  }
+
+  const handleLoadError = (error: Error) => {
+    const errorCode = (error as any).errno
+    console.error(`[cli] failed to load CLI view (attempt ${retryAttempts + 1}/${MAX_RETRY_ATTEMPTS}):`, error.message)
+
+    // Retry on network errors (errno -3)
+    if (errorCode === -3 && retryAttempts < MAX_RETRY_ATTEMPTS) {
+      retryAttempts++
+      const delay = getRetryDelay(retryAttempts)
+      console.info(`[cli] Retrying in ${delay}ms (attempt ${retryAttempts}/${MAX_RETRY_ATTEMPTS})`)
+
+      if (mainWindow && !mainWindow.isDestroyed()) {
+        loadLoadingScreen(mainWindow)
+      }
+
+      setTimeout(loadWithRetry, delay)
+    } else if (retryAttempts >= MAX_RETRY_ATTEMPTS) {
+      console.error("[cli] Max retry attempts reached, showing error screen")
+      if (mainWindow && !mainWindow.isDestroyed()) {
+        showErrorScreen(mainWindow, `Failed after ${MAX_RETRY_ATTEMPTS} attempts: ${error.message}`)
+      }
+    }
+  }
+
+  loadWithRetry()
+}
+
+
+async function startCli() {
+  try {
+    const devMode = process.env.NODE_ENV === "development"
+    console.info("[cli] start requested (dev mode:", devMode, ")")
+    await cliManager.start({ dev: devMode })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    console.error("[cli] start failed:", message)
+    if (mainWindow && !mainWindow.isDestroyed()) {
+      mainWindow.webContents.send("cli:error", { message })
+    }
+  }
+}
+
+cliManager.on("ready", (status) => {
+  if (!status.url) {
+    return
+  }
+  startCliPreload(status.url)
+})
+
+cliManager.on("status", (status) => {
+  if (status.state !== "ready") {
+    showLoadingScreen()
+  }
+})
+
+if (isMac) {
+  app.on("web-contents-created", (_, contents) => {
+    contents.session.setSpellCheckerEnabled(false)
+  })
+}
+
+app.whenReady().then(() => {
+  ensureDefaultUsers()
+  applyUserEnvToCli()
+  startCli()
+
+  if (isMac) {
+    session.defaultSession.setSpellCheckerEnabled(false)
+    app.on("browser-window-created", (_, window) => {
+      window.webContents.session.setSpellCheckerEnabled(false)
+    })
+
+    if (app.dock) {
+      const dockIcon = nativeImage.createFromPath(getIconPath())
+      if (!dockIcon.isEmpty()) {
+        app.dock.setIcon(dockIcon)
+      }
+    }
+  }
+
+  createWindow()
+
+  app.on("activate", () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      createWindow()
+    }
+  })
+})
+
+app.on("before-quit", async (event) => {
+  event.preventDefault()
+  await cliManager.stop().catch(() => { })
+  clearGuestUsers()
+  app.exit(0)
+})
+
+app.on("window-all-closed", () => {
+  if (process.platform !== "darwin") {
+    app.quit()
+  }
+})

packages/electron-app/electron/main/menu.ts

@@ -0,0 +1,84 @@
+import { Menu, BrowserWindow, MenuItemConstructorOptions } from "electron"
+
+export function createApplicationMenu(mainWindow: BrowserWindow) {
+  const isMac = process.platform === "darwin"
+
+  const template: MenuItemConstructorOptions[] = [
+    ...(isMac
+      ? [
+          {
+            label: "CodeNomad",
+            submenu: [
+              { role: "about" as const },
+              { type: "separator" as const },
+              { role: "hide" as const },
+              { role: "hideOthers" as const },
+              { role: "unhide" as const },
+              { type: "separator" as const },
+              { role: "quit" as const },
+            ],
+          },
+        ]
+      : []),
+    {
+      label: "File",
+      submenu: [
+        {
+          label: "New Instance",
+          accelerator: "CmdOrCtrl+N",
+          click: () => {
+            mainWindow.webContents.send("menu:newInstance")
+          },
+        },
+        { type: "separator" as const },
+        isMac ? { role: "close" as const } : { role: "quit" as const },
+      ],
+    },
+    {
+      label: "Edit",
+      submenu: [
+        { role: "undo" as const },
+        { role: "redo" as const },
+        { type: "separator" as const },
+        { role: "cut" as const },
+        { role: "copy" as const },
+        { role: "paste" as const },
+        ...(isMac
+          ? [{ role: "pasteAndMatchStyle" as const }, { role: "delete" as const }, { role: "selectAll" as const }]
+          : [{ role: "delete" as const }, { type: "separator" as const }, { role: "selectAll" as const }]),
+      ],
+    },
+    {
+      label: "View",
+      submenu: [
+        { role: "reload" as const },
+        { role: "forceReload" as const },
+        { role: "toggleDevTools" as const },
+        { type: "separator" as const },
+        { role: "resetZoom" as const },
+        { role: "zoomIn" as const },
+        { role: "zoomOut" as const },
+        { type: "separator" as const },
+        { role: "togglefullscreen" as const },
+      ],
+    },
+    {
+      label: "Window",
+      submenu: [
+        { role: "minimize" as const },
+        { role: "zoom" as const },
+        ...(isMac
+          ? [
+              { type: "separator" as const },
+              { role: "front" as const },
+              { type: "separator" as const },
+              { role: "window" as const },
+            ]
+          : [{ role: "close" as const }]),
+      ],
+    },
+  ]
+
+  const menu = Menu.buildFromTemplate(template)
+  Menu.setApplicationMenu(menu)
+}

packages/electron-app/electron/main/process-manager.ts

@@ -0,0 +1,371 @@
+import { spawn, type ChildProcess } from "child_process"
+import { app } from "electron"
+import { createRequire } from "module"
+import { EventEmitter } from "events"
+import { existsSync, readFileSync } from "fs"
+import os from "os"
+import path from "path"
+import { buildUserShellCommand, getUserShellEnv, supportsUserShell } from "./user-shell"
+
+const nodeRequire = createRequire(import.meta.url)
+
+
+type CliState = "starting" | "ready" | "error" | "stopped"
+type ListeningMode = "local" | "all"
+
+export interface CliStatus {
+  state: CliState
+  pid?: number
+  port?: number
+  url?: string
+  error?: string
+}
+
+export interface CliLogEntry {
+  stream: "stdout" | "stderr"
+  message: string
+}
+
+interface StartOptions {
+  dev: boolean
+}
+
+interface CliEntryResolution {
+  entry: string
+  runner: "node" | "tsx"
+  runnerPath?: string
+}
+
+const DEFAULT_CONFIG_PATH = "~/.config/codenomad/config.json"
+
+function resolveConfigPath(configPath?: string): string {
+  const target = configPath && configPath.trim().length > 0 ? configPath : DEFAULT_CONFIG_PATH
+  if (target.startsWith("~/")) {
+    return path.join(os.homedir(), target.slice(2))
+  }
+  return path.resolve(target)
+}
+
+function resolveHostForMode(mode: ListeningMode): string {
+  return mode === "local" ? "127.0.0.1" : "0.0.0.0"
+}
+
+function readListeningModeFromConfig(): ListeningMode {
+  try {
+    const configPath = resolveConfigPath(process.env.CLI_CONFIG)
+    if (!existsSync(configPath)) return "local"
+    const content = readFileSync(configPath, "utf-8")
+    const parsed = JSON.parse(content)
+    const mode = parsed?.preferences?.listeningMode
+    if (mode === "local" || mode === "all") {
+      return mode
+    }
+  } catch (error) {
+    console.warn("[cli] failed to read listening mode from config", error)
+  }
+  return "local"
+}
+
+export declare interface CliProcessManager {
+  on(event: "status", listener: (status: CliStatus) => void): this
+  on(event: "ready", listener: (status: CliStatus) => void): this
+  on(event: "log", listener: (entry: CliLogEntry) => void): this
+  on(event: "exit", listener: (status: CliStatus) => void): this
+  on(event: "error", listener: (error: Error) => void): this
+}
+
+export class CliProcessManager extends EventEmitter {
+  private child?: ChildProcess
+  private status: CliStatus = { state: "stopped" }
+  private stdoutBuffer = ""
+  private stderrBuffer = ""
+  private userEnv: Record<string, string> = {}
+
+  setUserEnv(env: Record<string, string>) {
+    this.userEnv = { ...env }
+  }
+
+  async start(options: StartOptions): Promise<CliStatus> {
+    if (this.child) {
+      await this.stop()
+    }
+
+    this.stdoutBuffer = ""
+    this.stderrBuffer = ""
+    this.updateStatus({ state: "starting", port: undefined, pid: undefined, url: undefined, error: undefined })
+
+    const cliEntry = this.resolveCliEntry(options)
+    const listeningMode = this.resolveListeningMode()
+    const host = resolveHostForMode(listeningMode)
+    const args = this.buildCliArgs(options, host)
+
+    console.info(
+      `[cli] launching CodeNomad CLI (${options.dev ? "dev" : "prod"}) using ${cliEntry.runner} at ${cliEntry.entry} (host=${host})`,
+    )
+
+    const env = supportsUserShell() ? getUserShellEnv() : { ...process.env }
+    env.ELECTRON_RUN_AS_NODE = "1"
+    Object.assign(env, this.userEnv)
+
+    const spawnDetails = supportsUserShell()
+      ? buildUserShellCommand(`ELECTRON_RUN_AS_NODE=1 exec ${this.buildCommand(cliEntry, args)}`)
+      : this.buildDirectSpawn(cliEntry, args)
+
+    const child = spawn(spawnDetails.command, spawnDetails.args, {
+      cwd: process.cwd(),
+      stdio: ["ignore", "pipe", "pipe"],
+      env,
+      shell: false,
+    })
+
+    console.info(`[cli] spawn command: ${spawnDetails.command} ${spawnDetails.args.join(" ")}`)
+    if (!child.pid) {
+      console.error("[cli] spawn failed: no pid")
+    }
+
+    this.child = child
+    this.updateStatus({ pid: child.pid ?? undefined })
+
+    child.stdout?.on("data", (data: Buffer) => {
+      this.handleStream(data.toString(), "stdout")
+    })
+
+    child.stderr?.on("data", (data: Buffer) => {
+      this.handleStream(data.toString(), "stderr")
+    })
+
+    child.on("error", (error) => {
+      console.error("[cli] failed to start CLI:", error)
+      this.updateStatus({ state: "error", error: error.message })
+      this.emit("error", error)
+    })
+
+    child.on("exit", (code, signal) => {
+      const failed = this.status.state !== "ready"
+      const error = failed ? this.status.error ?? `CLI exited with code ${code ?? 0}${signal ? ` (${signal})` : ""}` : undefined
+      console.info(`[cli] exit (code=${code}, signal=${signal || ""})${error ? ` error=${error}` : ""}`)
+      this.updateStatus({ state: failed ? "error" : "stopped", error })
+      if (failed && error) {
+        this.emit("error", new Error(error))
+      }
+      this.emit("exit", this.status)
+      this.child = undefined
+    })
+
+    return new Promise<CliStatus>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.handleTimeout()
+        reject(new Error("CLI startup timeout"))
+      }, 60000)
+
+      this.once("ready", (status) => {
+        clearTimeout(timeout)
+        resolve(status)
+      })
+
+      this.once("error", (error) => {
+        clearTimeout(timeout)
+        reject(error)
+      })
+    })
+  }
+
+  async stop(): Promise<void> {
+    const child = this.child
+    if (!child) {
+      this.updateStatus({ state: "stopped" })
+      return
+    }
+
+    return new Promise((resolve) => {
+      const killTimeout = setTimeout(() => {
+        child.kill("SIGKILL")
+      }, 4000)
+
+      child.on("exit", () => {
+        clearTimeout(killTimeout)
+        this.child = undefined
+        console.info("[cli] CLI process exited")
+        this.updateStatus({ state: "stopped" })
+        resolve()
+      })
+
+      child.kill("SIGTERM")
+    })
+  }
+
+  getStatus(): CliStatus {
+    return { ...this.status }
+  }
+
+  private resolveListeningMode(): ListeningMode {
+    return readListeningModeFromConfig()
+  }
+
+  private handleTimeout() {
+    if (this.child) {
+      this.child.kill("SIGKILL")
+      this.child = undefined
+    }
+    this.updateStatus({ state: "error", error: "CLI did not start in time" })
+    this.emit("error", new Error("CLI did not start in time"))
+  }
+
+  private handleStream(chunk: string, stream: "stdout" | "stderr") {
+    if (stream === "stdout") {
+      this.stdoutBuffer += chunk
+      this.processBuffer("stdout")
+    } else {
+      this.stderrBuffer += chunk
+      this.processBuffer("stderr")
+    }
+  }
+
+  private processBuffer(stream: "stdout" | "stderr") {
+    const buffer = stream === "stdout" ? this.stdoutBuffer : this.stderrBuffer
+    const lines = buffer.split("\n")
+    const trailing = lines.pop() ?? ""
+
+    if (stream === "stdout") {
+      this.stdoutBuffer = trailing
+    } else {
+      this.stderrBuffer = trailing
+    }
+
+    for (const line of lines) {
+      if (!line.trim()) continue
+      console.info(`[cli][${stream}] ${line}`)
+      this.emit("log", { stream, message: line })
+
+      const port = this.extractPort(line)
+      if (port && this.status.state === "starting") {
+        const url = `http://127.0.0.1:${port}`
+        console.info(`[cli] ready on ${url}`)
+        this.updateStatus({ state: "ready", port, url })
+        this.emit("ready", this.status)
+      }
+    }
+  }
+
+  private extractPort(line: string): number | null {
+    const readyMatch = line.match(/CodeNomad Server is ready at http:\/\/[^:]+:(\d+)/i)
+    if (readyMatch) {
+      return parseInt(readyMatch[1], 10)
+    }
+
+    if (line.toLowerCase().includes("http server listening")) {
+      const httpMatch = line.match(/:(\d{2,5})(?!.*:\d)/)
+      if (httpMatch) {
+        return parseInt(httpMatch[1], 10)
+      }
+      try {
+        const parsed = JSON.parse(line)
+        if (typeof parsed.port === "number") {
+          return parsed.port
+        }
+      } catch {
+        // not JSON, ignore
+      }
+    }
+
+    return null
+  }
+
+  private updateStatus(patch: Partial<CliStatus>) {
+    this.status = { ...this.status, ...patch }
+    this.emit("status", this.status)
+  }
+
+  private buildCliArgs(options: StartOptions, host: string): string[] {
+    const args = ["serve", "--host", host, "--port", "0"]
+
+    if (options.dev) {
+      const uiPort = process.env.VITE_PORT || "3000"
+      args.push("--ui-dev-server", `http://localhost:${uiPort}`, "--log-level", "debug")
+    }
+
+    return args
+  }
+
+  private buildCommand(cliEntry: CliEntryResolution, args: string[]): string {
+    const parts = [JSON.stringify(process.execPath)]
+    if (cliEntry.runner === "tsx" && cliEntry.runnerPath) {
+      parts.push(JSON.stringify(cliEntry.runnerPath))
+    }
+    parts.push(JSON.stringify(cliEntry.entry))
+    args.forEach((arg) => parts.push(JSON.stringify(arg)))
+    return parts.join(" ")
+  }
+
+  private buildDirectSpawn(cliEntry: CliEntryResolution, args: string[]) {
+    if (cliEntry.runner === "tsx") {
+      return { command: process.execPath, args: [cliEntry.runnerPath!, cliEntry.entry, ...args] }
+    }
+
+    return { command: process.execPath, args: [cliEntry.entry, ...args] }
+  }
+
+  private resolveCliEntry(options: StartOptions): CliEntryResolution {
+    if (options.dev) {
+      const tsxPath = this.resolveTsx()
+      if (!tsxPath) {
+        throw new Error("tsx is required to run the CLI in development mode. Please install dependencies.")
+      }
+      const devEntry = this.resolveDevEntry()
+      return { entry: devEntry, runner: "tsx", runnerPath: tsxPath }
+    }
+ 
+    const distEntry = this.resolveProdEntry()
+    return { entry: distEntry, runner: "node" }
+  }
+ 
+  private resolveTsx(): string | null {
+    const candidates: Array<string | (() => string)> = [
+      () => nodeRequire.resolve("tsx/cli"),
+      () => nodeRequire.resolve("tsx/dist/cli.mjs"),
+      () => nodeRequire.resolve("tsx/dist/cli.cjs"),
+      path.resolve(process.cwd(), "node_modules", "tsx", "dist", "cli.mjs"),
+      path.resolve(process.cwd(), "node_modules", "tsx", "dist", "cli.cjs"),
+      path.resolve(process.cwd(), "..", "node_modules", "tsx", "dist", "cli.mjs"),
+      path.resolve(process.cwd(), "..", "node_modules", "tsx", "dist", "cli.cjs"),
+      path.resolve(process.cwd(), "..", "..", "node_modules", "tsx", "dist", "cli.mjs"),
+      path.resolve(process.cwd(), "..", "..", "node_modules", "tsx", "dist", "cli.cjs"),
+      path.resolve(app.getAppPath(), "..", "node_modules", "tsx", "dist", "cli.mjs"),
+      path.resolve(app.getAppPath(), "..", "node_modules", "tsx", "dist", "cli.cjs"),
+    ]
+ 
+    for (const candidate of candidates) {
+      try {
+        const resolved = typeof candidate === "function" ? candidate() : candidate
+        if (resolved && existsSync(resolved)) {
+          return resolved
+        }
+      } catch {
+        continue
+      }
+    }
+ 
+    return null
+  }
+ 
+  private resolveDevEntry(): string {
+    const entry = path.resolve(process.cwd(), "..", "server", "src", "index.ts")
+    if (!existsSync(entry)) {
+      throw new Error(`Dev CLI entry not found at ${entry}. Run npm run dev:electron from the repository root after installing dependencies.`)
+    }
+    return entry
+  }
+ 
+  private resolveProdEntry(): string {
+    try {
+      const entry = nodeRequire.resolve("@neuralnomads/codenomad/dist/bin.js")
+      if (existsSync(entry)) {
+        return entry
+      }
+    } catch {
+      // fall through to error below
+    }
+    throw new Error("Unable to locate CodeNomad CLI build (dist/bin.js). Run npm run build --workspace @neuralnomads/codenomad.")
+  }
+}
+

packages/electron-app/electron/main/storage.ts

@@ -0,0 +1,121 @@
+import { app, ipcMain } from "electron"
+import { join } from "path"
+import { readFile, writeFile, mkdir, unlink, stat } from "fs/promises"
+import { existsSync } from "fs"
+
+const CONFIG_DIR = join(app.getPath("home"), ".config", "codenomad")
+const CONFIG_FILE = join(CONFIG_DIR, "config.json")
+const INSTANCES_DIR = join(CONFIG_DIR, "instances")
+
+// File watching for config changes
+let configWatchers = new Set<number>()
+let configLastModified = 0
+let configCache: string | null = null
+
+async function ensureDirectories() {
+  try {
+    await mkdir(CONFIG_DIR, { recursive: true })
+    await mkdir(INSTANCES_DIR, { recursive: true })
+  } catch (error) {
+    console.error("Failed to create directories:", error)
+  }
+}
+
+async function readConfigWithCache(): Promise<string> {
+  try {
+    const stats = await stat(CONFIG_FILE)
+    const currentModified = stats.mtime.getTime()
+
+    // If file hasn't been modified since last read, return cache
+    if (configCache && configLastModified >= currentModified) {
+      return configCache
+    }
+
+    const content = await readFile(CONFIG_FILE, "utf-8")
+    configCache = content
+    configLastModified = currentModified
+    return content
+  } catch (error) {
+    // File doesn't exist or can't be read
+    configCache = null
+    configLastModified = 0
+    throw error
+  }
+}
+
+function invalidateConfigCache() {
+  configCache = null
+  configLastModified = 0
+}
+
+export function setupStorageIPC() {
+  ensureDirectories()
+
+  ipcMain.handle("storage:getConfigPath", async () => CONFIG_FILE)
+  ipcMain.handle("storage:getInstancesDir", async () => INSTANCES_DIR)
+
+  ipcMain.handle("storage:readConfigFile", async () => {
+    try {
+      return await readConfigWithCache()
+    } catch (error) {
+      // Return empty config if file doesn't exist
+      return JSON.stringify({ preferences: { showThinkingBlocks: false, thinkingBlocksExpansion: "expanded" }, recentFolders: [] }, null, 2)
+    }
+  })
+
+  ipcMain.handle("storage:writeConfigFile", async (_, content: string) => {
+    try {
+      await writeFile(CONFIG_FILE, content, "utf-8")
+      invalidateConfigCache()
+
+      // Notify other renderer processes about config change
+      const windows = require("electron").BrowserWindow.getAllWindows()
+      windows.forEach((win: any) => {
+        if (win.webContents && !win.webContents.isDestroyed()) {
+          win.webContents.send("storage:configChanged")
+        }
+      })
+    } catch (error) {
+      console.error("Failed to write config file:", error)
+      throw error
+    }
+  })
+
+  ipcMain.handle("storage:readInstanceFile", async (_, filename: string) => {
+    const instanceFile = join(INSTANCES_DIR, `${filename}.json`)
+    try {
+      return await readFile(instanceFile, "utf-8")
+    } catch (error) {
+      // Return empty instance data if file doesn't exist
+      return JSON.stringify({ messageHistory: [] }, null, 2)
+    }
+  })
+
+  ipcMain.handle("storage:writeInstanceFile", async (_, filename: string, content: string) => {
+    const instanceFile = join(INSTANCES_DIR, `${filename}.json`)
+    try {
+      await writeFile(instanceFile, content, "utf-8")
+    } catch (error) {
+      console.error(`Failed to write instance file for ${filename}:`, error)
+      throw error
+    }
+  })
+
+  ipcMain.handle("storage:deleteInstanceFile", async (_, filename: string) => {
+    const instanceFile = join(INSTANCES_DIR, `${filename}.json`)
+    try {
+      if (existsSync(instanceFile)) {
+        await unlink(instanceFile)
+      }
+    } catch (error) {
+      console.error(`Failed to delete instance file for ${filename}:`, error)
+      throw error
+    }
+  })
+}
+
+// Clean up on app quit
+app.on("before-quit", () => {
+  configCache = null
+  configLastModified = 0
+})

packages/electron-app/electron/main/user-shell.ts

@@ -0,0 +1,139 @@
+import { spawn, spawnSync } from "child_process"
+import path from "path"
+
+interface ShellCommand {
+  command: string
+  args: string[]
+}
+
+const isWindows = process.platform === "win32"
+
+function getDefaultShellPath(): string {
+  if (process.env.SHELL && process.env.SHELL.trim().length > 0) {
+    return process.env.SHELL
+  }
+
+  if (process.platform === "darwin") {
+    return "/bin/zsh"
+  }
+
+  return "/bin/bash"
+}
+
+function wrapCommandForShell(command: string, shellPath: string): string {
+  const shellName = path.basename(shellPath)
+
+  if (shellName.includes("bash")) {
+    return 'if [ -f ~/.bashrc ]; then source ~/.bashrc >/dev/null 2>&1; fi; ' + command
+  }
+
+  if (shellName.includes("zsh")) {
+    return 'if [ -f ~/.zshrc ]; then source ~/.zshrc >/dev/null 2>&1; fi; ' + command
+  }
+
+  return command
+}
+
+function buildShellArgs(shellPath: string): string[] {
+  const shellName = path.basename(shellPath)
+  if (shellName.includes("zsh")) {
+    return ["-l", "-i", "-c"]
+  }
+  return ["-l", "-c"]
+}
+
+function sanitizeShellEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const cleaned = { ...env }
+  delete cleaned.npm_config_prefix
+  delete cleaned.NPM_CONFIG_PREFIX
+  return cleaned
+}
+
+export function supportsUserShell(): boolean {
+  return !isWindows
+}
+
+export function buildUserShellCommand(userCommand: string): ShellCommand {
+  if (!supportsUserShell()) {
+    throw new Error("User shell invocation is only supported on POSIX platforms")
+  }
+
+  const shellPath = getDefaultShellPath()
+  const script = wrapCommandForShell(userCommand, shellPath)
+  const args = buildShellArgs(shellPath)
+
+  return {
+    command: shellPath,
+    args: [...args, script],
+  }
+}
+
+export function getUserShellEnv(): NodeJS.ProcessEnv {
+  if (!supportsUserShell()) {
+    throw new Error("User shell invocation is only supported on POSIX platforms")
+  }
+  return sanitizeShellEnv(process.env)
+}
+
+export function runUserShellCommand(userCommand: string, timeoutMs = 5000): Promise<string> {
+  if (!supportsUserShell()) {
+    return Promise.reject(new Error("User shell invocation is only supported on POSIX platforms"))
+  }
+
+  const { command, args } = buildUserShellCommand(userCommand)
+  const env = getUserShellEnv()
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env,
+    })
+
+    let stdout = ""
+    let stderr = ""
+
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM")
+      reject(new Error(`Shell command timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+
+    child.stdout?.on("data", (data) => {
+      stdout += data.toString()
+    })
+
+    child.stderr?.on("data", (data) => {
+      stderr += data.toString()
+    })
+
+    child.on("error", (error) => {
+      clearTimeout(timeout)
+      reject(error)
+    })
+
+    child.on("close", (code) => {
+      clearTimeout(timeout)
+      if (code === 0) {
+        resolve(stdout.trim())
+      } else {
+        reject(new Error(stderr.trim() || `Shell command exited with code ${code}`))
+      }
+    })
+  })
+}
+
+export function runUserShellCommandSync(userCommand: string): string {
+  if (!supportsUserShell()) {
+    throw new Error("User shell invocation is only supported on POSIX platforms")
+  }
+
+  const { command, args } = buildUserShellCommand(userCommand)
+  const env = getUserShellEnv()
+  const result = spawnSync(command, args, { encoding: "utf-8", env })
+
+  if (result.status !== 0) {
+    const stderr = (result.stderr || "").toString().trim()
+    throw new Error(stderr || "Shell command failed")
+  }
+
+  return (result.stdout || "").toString().trim()
+}

packages/electron-app/electron/main/user-store.ts

@@ -0,0 +1,267 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, cpSync } from "fs"
+import os from "os"
+import path from "path"
+import crypto from "crypto"
+
+interface UserRecord {
+  id: string
+  name: string
+  salt?: string
+  passwordHash?: string
+  isGuest?: boolean
+  createdAt: string
+  updatedAt: string
+}
+
+interface UserStoreState {
+  users: UserRecord[]
+  activeUserId?: string
+}
+
+const CONFIG_ROOT = path.join(os.homedir(), ".config", "codenomad")
+const USERS_FILE = path.join(CONFIG_ROOT, "users.json")
+const USERS_ROOT = path.join(CONFIG_ROOT, "users")
+const LEGACY_ROOT = CONFIG_ROOT
+const LEGACY_INTEGRATIONS_ROOT = path.join(os.homedir(), ".nomadarch")
+
+function nowIso() {
+  return new Date().toISOString()
+}
+
+function sanitizeId(value: string) {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9-_]+/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-|-$/g, "")
+}
+
+function hashPassword(password: string, salt: string) {
+  return crypto.pbkdf2Sync(password, salt, 120000, 32, "sha256").toString("base64")
+}
+
+function generateSalt() {
+  return crypto.randomBytes(16).toString("base64")
+}
+
+function ensureDir(dir: string) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+}
+
+function readStore(): UserStoreState {
+  try {
+    if (!existsSync(USERS_FILE)) {
+      return { users: [] }
+    }
+    const content = readFileSync(USERS_FILE, "utf-8")
+    const parsed = JSON.parse(content) as UserStoreState
+    return {
+      users: Array.isArray(parsed.users) ? parsed.users : [],
+      activeUserId: parsed.activeUserId,
+    }
+  } catch {
+    return { users: [] }
+  }
+}
+
+function writeStore(state: UserStoreState) {
+  ensureDir(CONFIG_ROOT)
+  ensureDir(USERS_ROOT)
+  writeFileSync(USERS_FILE, JSON.stringify(state, null, 2), "utf-8")
+}
+
+function ensureUniqueId(base: string, existing: Set<string>) {
+  let candidate = sanitizeId(base) || "user"
+  let index = 1
+  while (existing.has(candidate)) {
+    candidate = `${candidate}-${index}`
+    index += 1
+  }
+  return candidate
+}
+
+function getUserDir(userId: string) {
+  return path.join(USERS_ROOT, userId)
+}
+
+function migrateLegacyData(targetDir: string) {
+  const legacyConfig = path.join(LEGACY_ROOT, "config.json")
+  const legacyInstances = path.join(LEGACY_ROOT, "instances")
+  const legacyWorkspaces = path.join(LEGACY_ROOT, "opencode-workspaces")
+
+  ensureDir(targetDir)
+
+  if (existsSync(legacyConfig)) {
+    cpSync(legacyConfig, path.join(targetDir, "config.json"), { force: true })
+  }
+  if (existsSync(legacyInstances)) {
+    cpSync(legacyInstances, path.join(targetDir, "instances"), { recursive: true, force: true })
+  }
+  if (existsSync(legacyWorkspaces)) {
+    cpSync(legacyWorkspaces, path.join(targetDir, "opencode-workspaces"), { recursive: true, force: true })
+  }
+
+  if (existsSync(LEGACY_INTEGRATIONS_ROOT)) {
+    cpSync(LEGACY_INTEGRATIONS_ROOT, path.join(targetDir, "integrations"), { recursive: true, force: true })
+  }
+}
+
+export function ensureDefaultUsers(): UserRecord {
+  const store = readStore()
+  if (store.users.length > 0) {
+    const active = store.users.find((u) => u.id === store.activeUserId) ?? store.users[0]
+    if (!store.activeUserId) {
+      store.activeUserId = active.id
+      writeStore(store)
+    }
+    return active
+  }
+
+  const existingIds = new Set<string>()
+  const userId = ensureUniqueId("roman", existingIds)
+  const salt = generateSalt()
+  const passwordHash = hashPassword("q1w2e3r4", salt)
+  const record: UserRecord = {
+    id: userId,
+    name: "roman",
+    salt,
+    passwordHash,
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+  }
+
+  store.users.push(record)
+  store.activeUserId = record.id
+  writeStore(store)
+
+  const userDir = getUserDir(record.id)
+  migrateLegacyData(userDir)
+
+  return record
+}
+
+export function listUsers(): UserRecord[] {
+  return readStore().users
+}
+
+export function getActiveUser(): UserRecord | null {
+  const store = readStore()
+  if (!store.activeUserId) return null
+  return store.users.find((user) => user.id === store.activeUserId) ?? null
+}
+
+export function setActiveUser(userId: string) {
+  const store = readStore()
+  const user = store.users.find((u) => u.id === userId)
+  if (!user) {
+    throw new Error("User not found")
+  }
+  store.activeUserId = userId
+  writeStore(store)
+  return user
+}
+
+export function createUser(name: string, password: string) {
+  const store = readStore()
+  const existingIds = new Set(store.users.map((u) => u.id))
+  const id = ensureUniqueId(name, existingIds)
+  const salt = generateSalt()
+  const passwordHash = hashPassword(password, salt)
+  const record: UserRecord = {
+    id,
+    name,
+    salt,
+    passwordHash,
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+  }
+  store.users.push(record)
+  writeStore(store)
+  ensureDir(getUserDir(id))
+  return record
+}
+
+export function createGuestUser() {
+  const store = readStore()
+  const existingIds = new Set(store.users.map((u) => u.id))
+  const id = ensureUniqueId(`guest-${crypto.randomUUID().slice(0, 8)}`, existingIds)
+  const record: UserRecord = {
+    id,
+    name: "Guest",
+    isGuest: true,
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+  }
+  store.users.push(record)
+  store.activeUserId = id
+  writeStore(store)
+  ensureDir(getUserDir(id))
+  return record
+}
+
+export function updateUser(userId: string, updates: { name?: string; password?: string }) {
+  const store = readStore()
+  const target = store.users.find((u) => u.id === userId)
+  if (!target) {
+    throw new Error("User not found")
+  }
+  if (updates.name) {
+    target.name = updates.name
+  }
+  if (updates.password && !target.isGuest) {
+    const salt = generateSalt()
+    target.salt = salt
+    target.passwordHash = hashPassword(updates.password, salt)
+  }
+  target.updatedAt = nowIso()
+  writeStore(store)
+  return target
+}
+
+export function deleteUser(userId: string) {
+  const store = readStore()
+  const target = store.users.find((u) => u.id === userId)
+  if (!target) return
+  store.users = store.users.filter((u) => u.id !== userId)
+  if (store.activeUserId === userId) {
+    store.activeUserId = store.users[0]?.id
+  }
+  writeStore(store)
+  const dir = getUserDir(userId)
+  if (existsSync(dir)) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+export function verifyPassword(userId: string, password: string): boolean {
+  const store = readStore()
+  const user = store.users.find((u) => u.id === userId)
+  if (!user) return false
+  if (user.isGuest) return true
+  if (!user.salt || !user.passwordHash) return false
+  return hashPassword(password, user.salt) === user.passwordHash
+}
+
+export function getUserDataRoot(userId: string) {
+  return getUserDir(userId)
+}
+
+export function clearGuestUsers() {
+  const store = readStore()
+  const guests = store.users.filter((u) => u.isGuest)
+  if (guests.length === 0) return
+  store.users = store.users.filter((u) => !u.isGuest)
+  if (store.activeUserId && guests.some((u) => u.id === store.activeUserId)) {
+    store.activeUserId = store.users[0]?.id
+  }
+  writeStore(store)
+  for (const guest of guests) {
+    const dir = getUserDir(guest.id)
+    if (existsSync(dir)) {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  }
+}