nastechai-desktop 18.1.0

package/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "arrowParens": "avoid",
+  "bracketSpacing": true,
+  "endOfLine": "auto",
+  "printWidth": 120,
+  "semi": false,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "none",
+  "useTabs": false
+}

package/DESIGN.md

@@ -0,0 +1,167 @@
+# Desktop Design System
+
+Conventions for the Electron desktop app (`apps/desktop`). Read this before
+adding a component, overlay, or style. The rule of thumb: **one source per
+concern, tokens over literals, flat over boxed.** If you reach for a raw color,
+a one-off shadow, a bespoke button, or a hardcoded `px-*` on a control — stop,
+there's already a primitive for it.
+
+## Principles
+
+1. **Flat, not boxed.** No card-in-card, no divider borders inside a panel.
+   Group with whitespace and a single hairline, never nested rounded boxes.
+2. **Borderless + shadow for elevation.** Overlays float on `shadow-nastech` + a
+   `--stroke-nastech` hairline, not hard borders.
+3. **One primitive per concern.** One `Button`, one set of control variants,
+   one `SearchField`, one `Loader`, one `ErrorState`. Migrate onto them; don't
+   fork.
+4. **Tokens, not literals.** Reference CSS vars (`--ui-*`, `--shadow-nastech`,
+   `--theme-*`), never raw hex / ad-hoc rgba in components.
+5. **Style lives in the primitive.** Variants and sizes own padding, radius,
+   color, chrome. Call sites pass a `variant`/`size`, not `className` overrides
+   that re-specify those.
+
+## Surfaces & elevation
+
+Every overlay / dialog / toast (boot-failure, install, notifications,
+model-picker, onboarding, prompt-overlays, updates, base `Dialog`) uses:
+
+```
+shadow-nastech           /* downward-weighted, layered contact→ambient falloff */
+border-(--stroke-nastech) /* currentColor hairline, theme-adaptive */
+```
+
+Both are CSS vars in `src/styles.css` — tune in one place, everything inherits.
+Don't add per-overlay `shadow-[…]` or `border-(--ui-stroke-secondary)`
+one-offs; if elevation needs to change, change the token.
+
+## Stroke & color tokens
+
+| Token | Use |
+| --- | --- |
+| `--ui-stroke-primary…quaternary` | hairlines, in descending strength |
+| `--ui-stroke-tertiary` | the default in-panel divider / list hairline |
+| `--stroke-nastech` | the overlay hairline (pairs with `shadow-nastech`) |
+| `--ui-text-primary / -secondary / -tertiary` | text hierarchy |
+| `--ui-bg-quaternary` | soft control fill (secondary button) |
+| `--chrome-action-hover` | hover fill for quiet controls |
+| `--theme-primary`, `--ui-accent` | brand/accent |
+
+Never hardcode `border-gray-*`, `bg-white`, `text-black`, etc. The white tile in
+`BrandMark` is the one sanctioned literal (the mark needs a fixed backdrop).
+
+## Buttons — one component
+
+`src/components/ui/button.tsx` is the single source. Pick a `variant` + `size`;
+do **not** pass `h-*`, `px-*`, `py-*`, or icon-size overrides.
+
+**Variants:** `default` (primary), `destructive`, `secondary` (soft fill —
+the default non-primary look), `outline` (transparent + 1px inset ring, no
+fill/shadow), `ghost`, `link`, `text` (boxless quiet inline — "Cancel",
+"Clear"), `textStrong` (bold underlined inline affordance — "Change",
+"Open logs").
+
+**Sizes:** `default`, `xs`, `sm`, `lg`, `inline` (flush, zero box — for buttons
+that sit inside a heading/sentence; replaces `h-auto px-0 py-0`), and the icon
+family `icon` / `icon-xs` / `icon-sm` / `icon-lg` / `icon-titlebar`.
+
+Notes:
+- Text buttons are square (no radius) and sized by padding + line-height (no
+  fixed heights). Only icon buttons carry the shared 4px radius.
+- SVGs inherit `size-3.5` (`size-3` at `xs`). Don't re-set icon size.
+- Polymorph with `asChild` when the button must render as a link/Slot.
+
+## Form controls
+
+- **`controlVariants`** (`src/components/ui/control.ts`) is the shared shape for
+  `Input` / `Textarea` / `SelectTrigger`. New text-entry controls compose it.
+- **`SearchField`** — borderless, underline-on-focus, auto-width. The only
+  search input. Don't build boxed search bars; don't wrap it in a bordered tile.
+  Empty lists hide their search field.
+- **`SegmentedControl`** — the choice control for small mutually-exclusive sets
+  (color mode, tool-call display, usage period). Replaces radio piles and
+  pill rows.
+- **`Switch`** (`size="xs"`) — bare, with `aria-label`. No bordered text wrapper.
+
+## Layout
+
+- **Gutters:** `PAGE_INSET_X` (`src/app/layout-constants.ts`) for page side
+  padding; `PAGE_INSET_NEG_X` to bleed a child to the edge. Don't hardcode
+  `px-6`/`px-8` on pages.
+- **Master/detail overlays:** `OverlaySplitLayout` + `OverlaySidebar` /
+  `OverlayMain`. Cron, profiles, etc. ride this — don't rebuild a titlebar
+  shell.
+- **Rows:** `ListRow` (settings `primitives.tsx`) for label/description/action
+  rows. Flat, flush-left; no per-row indentation that fights flush headers.
+- **No dividers between rows** unless the list genuinely needs them; prefer
+  spacing. When you do need one, it's a single `--ui-stroke-tertiary` hairline.
+
+## Feedback & empty/error/loading states
+
+- **Loading:** `Loader` (`src/components/ui/loader.tsx`) — animated math/ascii
+  curves (`lemniscate-bloom` for long ops). Never ship the literal text
+  "Loading…".
+- **Errors:** `ErrorState` + the canonical `ErrorIcon` (no bg chip). One look
+  for the React boundary, in-dialog errors, and the boot-failure banner. Pass
+  nodes for title/description so Radix `DialogTitle`/`Description` can flow
+  through for a11y.
+- **Logs:** `LogView` — no bg, hairline border, tight padding, small mono.
+  Every place we surface raw logs uses it.
+- **Empty:** `EmptyState` / `EmptyPanel` — don't hand-roll centered empties.
+
+## Iconography & brand
+
+- **`Codicon`** is the icon set. No mixing icon libraries inline.
+- **`BrandMark`** (`src/components/brand-mark.tsx`) is the brand glyph — the
+  `nastech-girl` mark on a white tile, softly rounded, identical in light/dark.
+  It replaced scattered Sparkles glyphs in updates / onboarding / about. Use it
+  for hero/brand moments; don't reintroduce decorative star/sparkle icons.
+
+## Motion
+
+- Quick, functional transitions (~100ms on controls). Respect
+  `prefers-reduced-motion` for anything beyond a fade.
+- Choreographed exits (e.g. onboarding's "matrix" fade-down) stagger per-element
+  then settle the surface — the outer container's fade is *delayed* so it
+  doesn't swallow the inner animation. Don't let a global fade race the detail.
+
+## i18n
+
+- Every user-facing string goes through `useI18n()` (`src/i18n/context.tsx`).
+  No literals in JSX.
+- **Update all locales together** — `en`, `ja`, `zh`, `zh-hant`. A string change
+  in `en.ts` that skips the others is a regression (drifted punctuation,
+  stale labels). Keep trailing-punctuation and tone consistent across all four.
+
+## State (TypeScript)
+
+Mirrors the repo TS style (see root `AGENTS.md`):
+
+- Shared/cross-component state → small **nanostores**, not prop-drilling.
+  Each feature owns its atoms; shared atoms live in `src/store`.
+- Rendering components subscribe with `useStore`; non-render actions read with
+  `$atom.get()`.
+- Colocated action modules over god hooks. A hook owns one narrow job.
+- Keep persistence beside the atom that owns it. Route roots stay thin.
+- Prefer `interface` for public props; extend React primitives
+  (`React.ComponentProps<'button'>`, `Omit<…>`).
+
+## Affordances
+
+- `cursor-pointer` at the primitive level (Button, dropdown/select) — don't
+  hardcode it per call site.
+- Global focus-ring reset; titlebar actions have no active-background state.
+- `Esc` closes every dismissable overlay/dialog (install/onboarding excluded);
+  close is an x-icon, not the word "Close".
+
+## Before you add something — checklist
+
+- [ ] Reuse a primitive (`Button`, `SearchField`, `SegmentedControl`,
+      `ListRow`, `Loader`, `ErrorState`, `LogView`) instead of forking one?
+- [ ] Tokens (`--ui-*`, `shadow-nastech`, `--stroke-nastech`) — zero raw colors /
+      one-off shadows?
+- [ ] No `className` overriding a primitive's padding / size / radius / chrome?
+- [ ] Overlay uses `shadow-nastech` + `border-(--stroke-nastech)`, no hard border?
+- [ ] Flat — no card-in-card, no gratuitous row dividers?
+- [ ] All four locales updated for any new/changed string?
+- [ ] `cursor-pointer`, focus ring, and `Esc`-to-close behave?

package/README.md

@@ -0,0 +1,141 @@
+# NasTech Desktop ☤
+
+<p align="center">
+  <a href="https://github.com/nastech-ai/NasTech-Agent/releases"><img src="https://img.shields.io/badge/Download-macOS%20%C2%B7%20Windows%20%C2%B7%20Linux-FFD700?style=for-the-badge" alt="Download"></a>
+  <a href="https://nastech-agent.nastech.ai/docs/"><img src="https://img.shields.io/badge/Docs-NASTECH--agent.nastech.ai-FFD700?style=for-the-badge" alt="Documentation"></a>
+  <a href="https://discord.gg/nastech"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
+  <a href="https://github.com/nastech-ai/NasTech-Agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License: MIT"></a>
+</p>
+
+**The native desktop app for [NasTech Agent](../../README.md) — the self-improving AI agent from [NasTech](https://nastech.ai).** Same agent, same skills, same memory as the CLI and gateway, in a polished native window — chat with streaming tool output, side-by-side previews, a file browser, voice, and settings, no terminal required. Available for **macOS, Windows, and Linux**.
+
+<table>
+<tr><td><b>Chat with the full agent</b></td><td>Streaming responses, live tool activity, structured tool summaries, and the same conversation history as every other NasTech surface.</td></tr>
+<tr><td><b>Side-by-side previews</b></td><td>Render web pages, files, and tool outputs in a right-hand pane while you keep chatting.</td></tr>
+<tr><td><b>File browser</b></td><td>Explore and preview the working directory without leaving the app.</td></tr>
+<tr><td><b>Voice</b></td><td>Talk to NasTech and hear it back.</td></tr>
+<tr><td><b>Settings & onboarding</b></td><td>Manage providers, models, tools, and credentials from a real UI. First-run setup gets you to your first message in seconds.</td></tr>
+<tr><td><b>Stays current</b></td><td>Built-in updates pull the latest agent and rebuild the app in place.</td></tr>
+</table>
+
+---
+
+## Install
+
+### Install with NasTech (recommended)
+
+Already have the NasTech CLI? Just run:
+
+```bash
+NASTECH desktop
+```
+
+It builds and launches the GUI against your existing install — same config, keys, sessions, and skills. On first launch NasTech walks you through picking a provider and model; nothing else to configure.
+
+### Prebuilt installers
+
+Prebuilt installers are built and distributed via [the NasTech Desktop website.](https://nastech-agent.nastech.ai/desktop).
+
+---
+
+## Updating
+
+The app checks for updates in the background and offers a one-click update when one is ready. You can also update any time from the CLI:
+
+```bash
+NASTECH update
+```
+
+---
+
+## Requirements
+
+The installer handles everything for you (Python 3.11+, a portable Git, ripgrep).
+
+---
+
+## Development
+
+Want to hack on the app itself? Install workspace deps from the repo root once, then run the dev server from this directory:
+
+```bash
+npm install          # from repo root — links apps/desktop, web, apps/shared
+cd apps/desktop
+npm run dev          # Vite renderer + Electron, which boots the Python backend
+```
+
+Point the app at a specific source checkout, or sandbox it away from your real config:
+
+```bash
+NASTECH_DESKTOP_NASTECH_ROOT=/path/to/clone npm run dev
+NASTECH_HOME=/tmp/throwaway npm run dev
+npm run dev:fake-boot   # exercise the startup overlay with deterministic delays
+```
+
+### Building installers
+
+```bash
+npm run dist:mac     # DMG + zip
+npm run dist:win     # NSIS + MSI
+npm run dist:linux   # AppImage + deb + rpm
+npm run pack         # unpacked app under release/ (no installer)
+```
+
+Installers are built and uploaded to GitHub Releases manually. macOS/Windows signing & notarization happen automatically when the relevant credentials are present in the environment (`CSC_LINK` / `CSC_KEY_PASSWORD` / `APPLE_*` for macOS, `WIN_CSC_*` for Windows).
+
+### How it works
+
+The packaged app ships only the Electron shell. On first launch it installs the NasTech Agent runtime into `NASTECH_HOME` (`~/.NASTECH`, or `%LOCALAPPDATA%\NASTECH` on Windows) — the **same layout a CLI install uses**, so the two are interchangeable. The renderer (React, in `src/`) talks to a `NASTECH dashboard` backend over the standard gateway APIs and reuses the embedded TUI rather than reimplementing chat. The install, backend-resolution, and self-update logic all live in `electron/main.cjs`.
+
+### Verification
+
+Run before opening a PR (lint may surface pre-existing warnings but must exit cleanly):
+
+```bash
+npm run fix
+npm run type-check
+npm run lint
+npm run test:desktop:all
+```
+
+### Troubleshooting
+
+Boot logs land in `NASTECH_HOME/logs/desktop.log` (includes backend output and recent Python tracebacks) — check it first if the app reports a boot failure.
+
+**macOS / Linux:**
+
+```bash
+# Force a clean first-launch setup
+rm "$HOME/.NASTECH/nastech-agent/.NASTECH-bootstrap-complete"
+# Rebuild a broken Python venv
+rm -rf "$HOME/.NASTECH/nastech-agent/venv"
+# Reset a stuck macOS microphone prompt (macOS only)
+tccutil reset Microphone com.nastech.NASTECH
+```
+
+**Windows (PowerShell):**
+
+```powershell
+# Force a clean first-launch setup
+Remove-Item "$env:LOCALAPPDATA\NASTECH\nastech-agent\.NASTECH-bootstrap-complete"
+# Rebuild a broken Python venv
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\NASTECH\nastech-agent\venv"
+```
+
+> The default NasTech home on Windows is `%LOCALAPPDATA%\NASTECH`. Set the `NASTECH_HOME` env var if you've relocated it.
+
+---
+
+## Community
+
+- 💬 [Discord](https://discord.gg/nastech)
+- 📖 [Documentation](https://nastech-agent.nastech.ai/docs/)
+- 🐛 [Issues](https://github.com/nastech-ai/NasTech-Agent/issues)
+
+---
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).
+
+Built by [NasTech](https://nastech.ai).

package/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/electron/backend-env.cjs

@@ -0,0 +1,112 @@
+const path = require('node:path')
+
+// Match the POSIX fallback surface used by the Python terminal environment.
+// macOS apps launched from Finder/Dock often inherit only /usr/bin:/bin:/usr/sbin:/sbin,
+// which misses Apple Silicon Homebrew and user-installed CLI tools such as codex.
+const POSIX_SANE_PATH_ENTRIES = Object.freeze([
+  '/opt/homebrew/bin',
+  '/opt/homebrew/sbin',
+  '/usr/local/sbin',
+  '/usr/local/bin',
+  '/usr/sbin',
+  '/usr/bin',
+  '/sbin',
+  '/bin'
+])
+
+function delimiterForPlatform(platform = process.platform) {
+  return platform === 'win32' ? ';' : ':'
+}
+
+function pathModuleForPlatform(platform = process.platform) {
+  return platform === 'win32' ? path.win32 : path.posix
+}
+
+function pathEnvKey(env = process.env, platform = process.platform) {
+  if (platform !== 'win32') return 'PATH'
+  return Object.keys(env || {}).find(key => key.toUpperCase() === 'PATH') || 'PATH'
+}
+
+function currentPathValue(env = process.env, platform = process.platform) {
+  const key = pathEnvKey(env, platform)
+  return env?.[key] || ''
+}
+
+function appendUniquePathEntries(entries, { delimiter = path.delimiter } = {}) {
+  const seen = new Set()
+  const ordered = []
+
+  for (const entry of entries) {
+    if (!entry) continue
+    const parts = Array.isArray(entry) ? entry : String(entry).split(delimiter)
+    for (const part of parts) {
+      if (!part || seen.has(part)) continue
+      seen.add(part)
+      ordered.push(part)
+    }
+  }
+
+  return ordered.join(delimiter)
+}
+
+function buildDesktopBackendPath({
+  nastechHome,
+  venvRoot,
+  currentPath = '',
+  platform = process.platform,
+  pathModule = pathModuleForPlatform(platform)
+} = {}) {
+  const delimiter = delimiterForPlatform(platform)
+  const nastechNodeBin = nastechHome ? pathModule.join(nastechHome, 'node', 'bin') : null
+  const venvBin = venvRoot ? pathModule.join(venvRoot, platform === 'win32' ? 'Scripts' : 'bin') : null
+  const saneEntries = platform === 'win32' ? [] : POSIX_SANE_PATH_ENTRIES
+
+  return appendUniquePathEntries(
+    [nastechNodeBin, venvBin, currentPath, saneEntries],
+    { delimiter }
+  )
+}
+
+function normalizeNasTechHomeRoot(nastechHome, { pathModule = pathModuleForPlatform(process.platform) } = {}) {
+  if (!nastechHome) return nastechHome
+  const resolved = pathModule.resolve(String(nastechHome))
+  const parent = pathModule.dirname(resolved)
+  if (pathModule.basename(parent).toLowerCase() === 'profiles') {
+    return pathModule.dirname(parent)
+  }
+  return resolved
+}
+
+function buildDesktopBackendEnv({
+  nastechHome,
+  pythonPathEntries = [],
+  venvRoot,
+  currentEnv = process.env,
+  platform = process.platform,
+  pathModule = pathModuleForPlatform(platform)
+} = {}) {
+  const delimiter = delimiterForPlatform(platform)
+  const currentPythonPath = currentEnv?.PYTHONPATH || ''
+  const key = pathEnvKey(currentEnv, platform)
+
+  return {
+    PYTHONPATH: appendUniquePathEntries([...pythonPathEntries, currentPythonPath], { delimiter }),
+    [key]: buildDesktopBackendPath({
+      nastechHome,
+      venvRoot,
+      currentPath: currentPathValue(currentEnv, platform),
+      platform,
+      pathModule
+    })
+  }
+}
+
+module.exports = {
+  POSIX_SANE_PATH_ENTRIES,
+  appendUniquePathEntries,
+  buildDesktopBackendEnv,
+  buildDesktopBackendPath,
+  delimiterForPlatform,
+  normalizeNasTechHomeRoot,
+  pathEnvKey
+}

package/electron/backend-env.test.cjs

@@ -0,0 +1,111 @@
+const test = require('node:test')
+const assert = require('node:assert/strict')
+const path = require('node:path')
+
+const {
+  POSIX_SANE_PATH_ENTRIES,
+  appendUniquePathEntries,
+  buildDesktopBackendEnv,
+  buildDesktopBackendPath,
+  normalizeNasTechHomeRoot,
+  pathEnvKey
+} = require('./backend-env.cjs')
+
+test('desktop backend PATH adds NasTech-managed bins and missing POSIX sane entries', () => {
+  const result = buildDesktopBackendPath({
+    nastechHome: '/Users/test/.nastech',
+    venvRoot: '/Users/test/.nastech/nastech-agent/venv',
+    currentPath: '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin',
+    platform: 'darwin',
+    pathModule: path.posix
+  })
+
+  const entries = result.split(':')
+  assert.equal(entries[0], '/Users/test/.nastech/node/bin')
+  assert.equal(entries[1], '/Users/test/.nastech/nastech-agent/venv/bin')
+  assert.ok(entries.includes('/opt/homebrew/bin'), 'Apple Silicon Homebrew bin is added')
+  assert.ok(entries.includes('/opt/homebrew/sbin'), 'Apple Silicon Homebrew sbin is added')
+  assert.ok(entries.includes('/usr/local/sbin'), 'missing standard sbin is added')
+
+  for (const expected of POSIX_SANE_PATH_ENTRIES) {
+    assert.ok(entries.includes(expected), `${expected} should be present`)
+  }
+})
+
+test('desktop backend PATH preserves first occurrence and avoids duplicates', () => {
+  const result = buildDesktopBackendPath({
+    nastechHome: '/Users/test/.nastech',
+    venvRoot: '/Users/test/.nastech/nastech-agent/venv',
+    currentPath: '/opt/homebrew/bin:/usr/bin:/opt/homebrew/bin:/bin',
+    platform: 'darwin',
+    pathModule: path.posix
+  })
+
+  const entries = result.split(':')
+  assert.equal(entries.filter(entry => entry === '/opt/homebrew/bin').length, 1)
+  assert.ok(
+    entries.indexOf('/opt/homebrew/bin') < entries.indexOf('/opt/homebrew/sbin'),
+    'existing Homebrew bin keeps its precedence over appended missing sane entries'
+  )
+})
+
+test('buildDesktopBackendEnv extends PYTHONPATH and backend PATH together', () => {
+  const env = buildDesktopBackendEnv({
+    nastechHome: '/Users/test/.nastech',
+    pythonPathEntries: ['/repo/nastech-agent'],
+    venvRoot: '/Users/test/.nastech/nastech-agent/venv',
+    currentEnv: {
+      PATH: '/usr/bin:/bin',
+      PYTHONPATH: '/existing/pythonpath'
+    },
+    platform: 'darwin',
+    pathModule: path.posix
+  })
+
+  assert.equal(env.PYTHONPATH, '/repo/nastech-agent:/existing/pythonpath')
+  assert.ok(env.PATH.startsWith('/Users/test/.nastech/node/bin:/Users/test/.nastech/nastech-agent/venv/bin:'))
+  assert.ok(env.PATH.includes('/opt/homebrew/bin'))
+})
+
+test('normalizeNasTechHomeRoot maps profile homes back to the global NasTech root', () => {
+  assert.equal(
+    normalizeNasTechHomeRoot('/Users/test/.nastech/profiles/oracle', { pathModule: path.posix }),
+    '/Users/test/.nastech'
+  )
+  assert.equal(
+    normalizeNasTechHomeRoot('C:\\Users\\test\\AppData\\Local\\nastech\\profiles\\oracle', { pathModule: path.win32 }),
+    'C:\\Users\\test\\AppData\\Local\\nastech'
+  )
+  assert.equal(
+    normalizeNasTechHomeRoot('/Users/test/.nastech', { pathModule: path.posix }),
+    '/Users/test/.nastech'
+  )
+})
+
+test('Windows PATH casing and delimiter are preserved without POSIX sane entries', () => {
+  const env = buildDesktopBackendEnv({
+    nastechHome: 'C:\\Users\\test\\AppData\\Local\\nastech',
+    pythonPathEntries: ['C:\\repo\\nastech-agent'],
+    venvRoot: 'C:\\Users\\test\\AppData\\Local\\nastech\\nastech-agent\\venv',
+    currentEnv: {
+      Path: 'C:\\Windows\\System32;C:\\Windows',
+      PYTHONPATH: 'C:\\existing\\pythonpath'
+    },
+    platform: 'win32',
+    pathModule: path.win32
+  })
+
+  assert.equal(pathEnvKey({ Path: 'x' }, 'win32'), 'Path')
+  assert.equal(env.PATH, undefined)
+  assert.ok(env.Path.startsWith('C:\\Users\\test\\AppData\\Local\\nastech\\node\\bin;'))
+  assert.ok(env.Path.includes('\\venv\\Scripts;'))
+  assert.ok(env.Path.includes(';C:\\Windows\\System32;C:\\Windows'))
+  assert.equal(env.Path.includes('/opt/homebrew/bin'), false)
+})
+
+test('appendUniquePathEntries drops empty entries and keeps first occurrence', () => {
+  assert.equal(
+    appendUniquePathEntries([':/a::/b', ['/a', '/c']], { delimiter: ':' }),
+    '/a:/b:/c'
+  )
+})

package/electron/backend-probes.cjs

@@ -0,0 +1,106 @@
+/**
+ * backend-probes.cjs
+ *
+ * Cheap "does this candidate backend actually work" checks used by
+ * resolveNastechBackend (main.cjs). The resolver walks a ladder of
+ * candidates -- bootstrap marker, `nastech` on PATH, system Python with
+ * nastech_cli installed -- and historically returned the first candidate
+ * whose binary existed on disk. That assumption breaks when a user has
+ * a pre-installed Python 3.11-3.13 (so findSystemPython() returns a
+ * path) but no nastech_cli in its site-packages: the resolver hands back
+ * a backend the spawn step can't actually run, and the user gets a
+ * dead-on-arrival "ModuleNotFoundError: No module named 'nastech_cli'"
+ * instead of the first-launch installer.
+ *
+ * These probes give the resolver a way to verify a candidate before
+ * trusting it. Failure (non-zero exit, exception, timeout) means "skip
+ * this rung, try the next one"; success means "spawn this for real."
+ * Falling off the bottom of the ladder lands on the bootstrap-needed
+ * sentinel, which is exactly what we want when nothing pre-existing
+ * actually works.
+ *
+ * Both probes are deliberately fast and forgiving:
+ *   - 5s timeout (a hung interpreter beats forever, but we still give
+ *     slow disks / cold caches room to breathe)
+ *   - stdio ignored (we only care about exit code; stdout/stderr are
+ *     not surfaced to the user, just to recentNastechLog for forensics
+ *     via the caller's catch block if it chooses)
+ *   - any throw -> false (never propagate -- resolver wants a boolean)
+ *
+ * Kept in a standalone cjs module so it can be unit-tested with
+ * `node --test` without dragging in the electron runtime (same pattern
+ * as bootstrap-platform.cjs and hardening.cjs).
+ */
+
+const { execFileSync } = require('node:child_process')
+
+const PROBE_TIMEOUT_MS = 5000
+
+/**
+ * Return true iff `python -c "import nastech_cli"` exits 0.
+ *
+ * Used to gate the "fallback to system Python with nastech_cli installed"
+ * rung of resolveNastechBackend. Without this, a system Python 3.11-3.13
+ * registered in PEP 514 makes findSystemPython() succeed regardless of
+ * whether nastech_cli has actually been pip-installed into its
+ * site-packages -- and the resolver returns a backend that immediately
+ * dies on spawn.
+ *
+ * @param {string} pythonPath - Absolute path to a python.exe / python.
+ * @returns {boolean}
+ */
+function canImportNastechCli(pythonPath) {
+  if (!pythonPath) return false
+  try {
+    execFileSync(pythonPath, ['-c', 'import nastech_cli'], {
+      stdio: 'ignore',
+      timeout: PROBE_TIMEOUT_MS,
+      windowsHide: true
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Return true iff `<nastechCommand> --version` exits 0.
+ *
+ * Used to gate the "existing `nastech` on PATH" rung. Without this, a
+ * stale nastech.cmd shim left behind by an uninstalled pip install (or
+ * a half-built venv whose `nastech` entry-point points at a deleted
+ * Python) survives findOnPath() and gets selected as the backend.
+ *
+ * We intentionally avoid invoking the command with the dashboard args
+ * here -- `--version` is the cheapest "is this binary alive" smoke
+ * test that every nastech_cli entry-point has supported since 0.1.
+ *
+ * @param {string} nastechCommand - Resolved absolute path to a nastech
+ *   executable (or an interpreter+script wrapper).
+ * @param {object} [opts]
+ * @param {boolean} [opts.shell] - Whether to run through a shell. For
+ *   .cmd/.bat shims on Windows execFileSync needs shell:true to find
+ *   the cmd interpreter; mirrors the same flag isCommandScript() drives
+ *   in resolveNastechBackend.
+ * @returns {boolean}
+ */
+function verifyNastechCli(nastechCommand, opts = {}) {
+  if (!nastechCommand) return false
+  try {
+    execFileSync(nastechCommand, ['--version'], {
+      stdio: 'ignore',
+      timeout: PROBE_TIMEOUT_MS,
+      shell: Boolean(opts.shell),
+      windowsHide: true
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+module.exports = {
+  canImportNastechCli,
+  verifyNastechCli,
+  PROBE_TIMEOUT_MS
+}