bump version to 0.5.1

Reduce per-token store churn by updating status on transitions, caching instance-level indicators, and avoiding O(n) session-map cloning.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,71 @@
+name: Bug Report
+description: Report a bug or regression in CodeNomad
+labels:
+  - bug
+title: "[Bug]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing a bug report! Please review open issues before submitting a new one and provide as much detail as possible so we can reproduce the problem.
+  - type: dropdown
+    id: variant
+    attributes:
+      label: App Variant
+      description: Which build are you running when this issue appears?
+      multiple: false
+      options:
+        - Electron
+        - Tauri
+        - Server CLI
+    validations:
+      required: true
+  - type: input
+    id: os-version
+    attributes:
+      label: Operating System & Version
+      description: Include the OS family and version (e.g., macOS 15.0, Ubuntu 24.04, Windows 11 23H2).
+      placeholder: macOS 15.0
+    validations:
+      required: true
+  - type: input
+    id: summary
+    attributes:
+      label: Issue Summary
+      description: Briefly describe what is happening.
+      placeholder: A quick one sentence problem statement
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to Reproduce
+      description: List the steps needed to reproduce the problem.
+      placeholder: |
+        1. Go to ...
+        2. Click ...
+        3. Observe ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: Describe what you expected to happen instead.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs & Screenshots
+      description: Attach relevant logs, stack traces, or screenshots if available.
+      placeholder: Paste logs here or drag-and-drop files onto the issue.
+    validations:
+      required: false
+  - type: textarea
+    id: extra
+    attributes:
+      label: Additional Context
+      description: Add any other context about the problem here.
+    validations:
+      required: false

.github/workflows/build-and-upload.yml

@@ -0,0 +1,625 @@
+name: Build and Upload Binaries
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        description: "Version to apply to workspace packages (release builds)"
+        required: false
+        default: ""
+        type: string
+      tag:
+        description: "Git tag to upload assets to (release builds)"
+        required: false
+        default: ""
+        type: string
+      release_name:
+        description: "Release name (unused here, for context)"
+        required: false
+        default: ""
+        type: string
+      upload:
+        description: "Upload built artifacts to the GitHub release"
+        required: false
+        default: true
+        type: boolean
+      set_versions:
+        description: "Run npm version to set workspace versions"
+        required: false
+        default: true
+        type: boolean
+
+# Permissions are intentionally omitted here so callers can choose
+# least-privilege (e.g. dev CI uses read-only; releases grant write).
+
+env:
+  NODE_VERSION: 20
+
+jobs:
+  build-macos:
+    runs-on: macos-15-intel
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      VERSION: ${{ inputs.version }}
+      TAG: ${{ inputs.tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Set workspace versions
+        if: ${{ inputs.set_versions && inputs.version != '' }}
+        run: npm version ${VERSION} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
+
+      - name: Install dependencies
+        run: npm ci --workspaces --include=optional
+
+      - name: Ensure rollup native binary
+        run: npm install @rollup/rollup-darwin-x64 --no-save
+
+      - name: Build macOS binaries (Electron)
+        run: npm run build:mac --workspace @neuralnomads/codenomad-electron-app
+
+      - name: Upload release assets
+        if: ${{ inputs.upload && inputs.tag != '' }}
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          for file in packages/electron-app/release/*.zip; do
+            [ -f "$file" ] || continue
+            echo "Uploading $file"
+            gh release upload "$TAG" "$file" --clobber
+          done
+
+  build-windows:
+    runs-on: windows-2025
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      VERSION: ${{ inputs.version }}
+      TAG: ${{ inputs.tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Set workspace versions
+        if: ${{ inputs.set_versions && inputs.version != '' }}
+        run: npm version ${{ env.VERSION }} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
+        shell: bash
+
+      - name: Install dependencies
+        run: npm ci --workspaces --include=optional
+
+      - name: Ensure rollup native binary
+        run: npm install @rollup/rollup-win32-x64-msvc --no-save
+
+      - name: Build Windows binaries (Electron)
+        run: npm run build:win --workspace @neuralnomads/codenomad-electron-app
+
+      - name: Upload release assets
+        if: ${{ inputs.upload && inputs.tag != '' }}
+        shell: pwsh
+        run: |
+          Get-ChildItem -Path "packages/electron-app/release" -Filter *.zip -File | ForEach-Object {
+            Write-Host "Uploading $($_.FullName)"
+            gh release upload $env:TAG $_.FullName --clobber
+          }
+
+  build-linux:
+    runs-on: ubuntu-24.04
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      VERSION: ${{ inputs.version }}
+      TAG: ${{ inputs.tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Set workspace versions
+        if: ${{ inputs.set_versions && inputs.version != '' }}
+        run: npm version ${VERSION} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
+
+      - name: Install dependencies
+        run: npm ci --workspaces --include=optional
+
+      - name: Ensure rollup native binary
+        run: npm install @rollup/rollup-linux-x64-gnu --no-save
+
+      - name: Build Linux binaries (Electron)
+        run: npm run build:linux --workspace @neuralnomads/codenomad-electron-app
+
+      - name: Upload release assets
+        if: ${{ inputs.upload && inputs.tag != '' }}
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          for file in packages/electron-app/release/*.zip; do
+            [ -f "$file" ] || continue
+            echo "Uploading $file"
+            gh release upload "$TAG" "$file" --clobber
+          done
+
+  build-tauri-macos:
+    runs-on: macos-15-intel
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      VERSION: ${{ inputs.version }}
+      TAG: ${{ inputs.tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Setup Rust (Tauri)
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set workspace versions
+        if: ${{ inputs.set_versions && inputs.version != '' }}
+        run: npm version ${VERSION} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
+
+      - name: Install dependencies
+        run: npm ci --workspaces --include=optional
+
+      - name: Ensure rollup native binary
+        run: npm install @rollup/rollup-darwin-x64 --no-save
+
+      - name: Prebuild (Tauri)
+        run: npm run prebuild --workspace @codenomad/tauri-app
+
+      - name: Ensure tauri native binary
+        working-directory: packages/tauri-app
+        run: |
+          set -euo pipefail
+          for attempt in 1 2 3; do
+            if [ "$attempt" -gt 1 ]; then
+              echo "Retrying Tauri CLI install (attempt $attempt)..."
+            fi
+            npm install @tauri-apps/cli@2.9.4 @tauri-apps/cli-darwin-x64@2.9.4 --no-save --no-audit --no-fund --workspaces=false
+            node -e "require('@tauri-apps/cli'); console.log('Tauri CLI loaded')" && exit 0
+          done
+          echo "Tauri CLI failed to load after retries" >&2
+          exit 1
+
+      - name: Build macOS bundle (Tauri)
+        working-directory: packages/tauri-app
+        run: npm exec -- tauri build
+
+      - name: Package Tauri artifacts (macOS)
+        if: ${{ inputs.upload }}
+        run: |
+          set -euo pipefail
+          BUNDLE_ROOT="packages/tauri-app/target/release/bundle"
+          ARTIFACT_DIR="packages/tauri-app/release-tauri"
+          rm -rf "$ARTIFACT_DIR"
+          mkdir -p "$ARTIFACT_DIR"
+          if [ -d "$BUNDLE_ROOT/macos/CodeNomad.app" ]; then
+            ditto -ck --sequesterRsrc --keepParent "$BUNDLE_ROOT/macos/CodeNomad.app" "$ARTIFACT_DIR/CodeNomad-Tauri-${VERSION}-macos-x64.zip"
+          fi
+
+      - name: Upload Tauri release assets (macOS)
+        if: ${{ inputs.upload && inputs.tag != '' }}
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          for file in packages/tauri-app/release-tauri/*.zip; do
+            [ -f "$file" ] || continue
+            echo "Uploading $file"
+            gh release upload "$TAG" "$file" --clobber
+          done
+
+  build-tauri-macos-arm64:
+    runs-on: macos-26
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      VERSION: ${{ inputs.version }}
+      TAG: ${{ inputs.tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Setup Rust (Tauri)
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set workspace versions
+        if: ${{ inputs.set_versions && inputs.version != '' }}
+        run: npm version ${VERSION} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
+
+      - name: Install dependencies
+        run: npm ci --workspaces --include=optional
+
+      - name: Ensure rollup native binary
+        run: npm install @rollup/rollup-darwin-arm64 --no-save
+
+      - name: Prebuild (Tauri)
+        run: npm run prebuild --workspace @codenomad/tauri-app
+
+      - name: Ensure tauri native binary
+        working-directory: packages/tauri-app
+        run: |
+          set -euo pipefail
+          for attempt in 1 2 3; do
+            if [ "$attempt" -gt 1 ]; then
+              echo "Retrying Tauri CLI install (attempt $attempt)..."
+            fi
+            npm install @tauri-apps/cli@2.9.4 @tauri-apps/cli-darwin-arm64@2.9.4 --no-save --no-audit --no-fund --workspaces=false
+            node -e "require('@tauri-apps/cli'); console.log('Tauri CLI loaded')" && exit 0
+          done
+          echo "Tauri CLI failed to load after retries" >&2
+          exit 1
+
+      - name: Build macOS bundle (Tauri, arm64)
+        working-directory: packages/tauri-app
+        run: npm exec -- tauri build
+
+      - name: Package Tauri artifacts (macOS arm64)
+        if: ${{ inputs.upload }}
+        run: |
+          set -euo pipefail
+          BUNDLE_ROOT="packages/tauri-app/target/release/bundle"
+          ARTIFACT_DIR="packages/tauri-app/release-tauri"
+          rm -rf "$ARTIFACT_DIR"
+          mkdir -p "$ARTIFACT_DIR"
+          if [ -d "$BUNDLE_ROOT/macos/CodeNomad.app" ]; then
+            ditto -ck --sequesterRsrc --keepParent "$BUNDLE_ROOT/macos/CodeNomad.app" "$ARTIFACT_DIR/CodeNomad-Tauri-${VERSION}-macos-arm64.zip"
+          fi
+
+      - name: Upload Tauri release assets (macOS arm64)
+        if: ${{ inputs.upload && inputs.tag != '' }}
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          for file in packages/tauri-app/release-tauri/*.zip; do
+            [ -f "$file" ] || continue
+            echo "Uploading $file"
+            gh release upload "$TAG" "$file" --clobber
+          done
+
+  build-tauri-windows:
+    runs-on: windows-2025
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      VERSION: ${{ inputs.version }}
+      TAG: ${{ inputs.tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Setup Rust (Tauri)
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set workspace versions
+        if: ${{ inputs.set_versions && inputs.version != '' }}
+        run: npm version ${{ env.VERSION }} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
+        shell: bash
+
+      - name: Install dependencies
+        run: npm ci --workspaces --include=optional
+
+      - name: Ensure rollup native binary
+        run: npm install @rollup/rollup-win32-x64-msvc --no-save
+
+      - name: Prebuild (Tauri)
+        run: npm run prebuild --workspace @codenomad/tauri-app
+
+      - name: Ensure tauri native binary
+        shell: bash
+        working-directory: packages/tauri-app
+        run: |
+          set -euo pipefail
+          for attempt in 1 2 3; do
+            if [ "$attempt" -gt 1 ]; then
+              echo "Retrying Tauri CLI install (attempt $attempt)..."
+            fi
+            npm install @tauri-apps/cli@2.9.4 @tauri-apps/cli-win32-x64-msvc@2.9.4 --no-save --no-audit --no-fund --workspaces=false
+            node -e "require('@tauri-apps/cli'); console.log('Tauri CLI loaded')" && exit 0
+          done
+          echo "Tauri CLI failed to load after retries" >&2
+          exit 1
+
+      - name: Build Windows bundle (Tauri)
+        shell: bash
+        working-directory: packages/tauri-app
+        run: npm exec -- tauri build
+
+      - name: Package Tauri artifacts (Windows)
+        if: ${{ inputs.upload }}
+        shell: pwsh
+        run: |
+          $bundleRoot = "packages/tauri-app/target/release/bundle"
+          $artifactDir = "packages/tauri-app/release-tauri"
+          if (Test-Path $artifactDir) { Remove-Item $artifactDir -Recurse -Force }
+          New-Item -ItemType Directory -Path $artifactDir | Out-Null
+          $exe = Get-ChildItem -Path $bundleRoot -Recurse -File -Filter *.exe | Select-Object -First 1
+          if ($null -ne $exe) {
+            $dest = Join-Path $artifactDir ("CodeNomad-Tauri-$env:VERSION-windows-x64.zip")
+            Compress-Archive -Path $exe.Directory.FullName -DestinationPath $dest -Force
+          }
+
+      - name: Upload Tauri release assets (Windows)
+        if: ${{ inputs.upload && inputs.tag != '' }}
+        shell: pwsh
+        run: |
+          if (Test-Path "packages/tauri-app/release-tauri") {
+            Get-ChildItem -Path "packages/tauri-app/release-tauri" -Filter *.zip -File | ForEach-Object {
+              Write-Host "Uploading $($_.FullName)"
+              gh release upload $env:TAG $_.FullName --clobber
+            }
+          }
+
+  build-tauri-linux:
+    runs-on: ubuntu-24.04
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      VERSION: ${{ inputs.version }}
+      TAG: ${{ inputs.tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Setup Rust (Tauri)
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install Linux build dependencies (Tauri)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            pkg-config \
+            libgtk-3-dev \
+            libglib2.0-dev \
+            libwebkit2gtk-4.1-dev \
+            libsoup-3.0-dev \
+            libayatana-appindicator3-dev \
+            librsvg2-dev
+
+      - name: Set workspace versions
+        if: ${{ inputs.set_versions && inputs.version != '' }}
+        run: npm version ${VERSION} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
+
+      - name: Install dependencies
+        run: npm ci --workspaces --include=optional
+
+      - name: Ensure rollup native binary
+        run: npm install @rollup/rollup-linux-x64-gnu --no-save
+
+      - name: Prebuild (Tauri)
+        run: npm run prebuild --workspace @codenomad/tauri-app
+
+      - name: Ensure tauri native binary
+        working-directory: packages/tauri-app
+        run: |
+          set -euo pipefail
+          for attempt in 1 2 3; do
+            if [ "$attempt" -gt 1 ]; then
+              echo "Retrying Tauri CLI install (attempt $attempt)..."
+            fi
+            npm install @tauri-apps/cli@2.9.4 @tauri-apps/cli-linux-x64-gnu@2.9.4 --no-save --no-audit --no-fund --workspaces=false
+            node -e "require('@tauri-apps/cli'); console.log('Tauri CLI loaded')" && exit 0
+          done
+          echo "Tauri CLI failed to load after retries" >&2
+          exit 1
+
+      - name: Build Linux bundle (Tauri)
+        working-directory: packages/tauri-app
+        run: npm exec -- tauri build
+
+      - name: Package Tauri artifacts (Linux)
+        if: ${{ inputs.upload }}
+        run: |
+          set -euo pipefail
+          SEARCH_ROOT="packages/tauri-app/target"
+          ARTIFACT_DIR="packages/tauri-app/release-tauri"
+          rm -rf "$ARTIFACT_DIR"
+          mkdir -p "$ARTIFACT_DIR"
+          shopt -s nullglob globstar
+
+          find_one() {
+            find "$SEARCH_ROOT" -type f -iname "$1" | head -n1
+          }
+
+          appimage=$(find_one "*.AppImage")
+          deb=$(find_one "*.deb")
+          rpm=$(find_one "*.rpm")
+
+          if [ -z "$appimage" ] || [ -z "$deb" ] || [ -z "$rpm" ]; then
+            echo "Missing bundle(s): appimage=${appimage:-none} deb=${deb:-none} rpm=${rpm:-none}" >&2
+            exit 1
+          fi
+
+          cp "$appimage" "$ARTIFACT_DIR/CodeNomad-Tauri-${VERSION}-linux-x64.AppImage"
+          cp "$deb" "$ARTIFACT_DIR/CodeNomad-Tauri-${VERSION}-linux-x64.deb"
+          cp "$rpm" "$ARTIFACT_DIR/CodeNomad-Tauri-${VERSION}-linux-x64.rpm"
+
+      - name: Upload Tauri release assets (Linux)
+        if: ${{ inputs.upload && inputs.tag != '' }}
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          for file in packages/tauri-app/release-tauri/*; do
+            [ -f "$file" ] || continue
+            echo "Uploading $file"
+            gh release upload "$TAG" "$file" --clobber
+          done
+
+  build-tauri-linux-arm64:
+    if: ${{ false }}
+    runs-on: ubuntu-24.04
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      VERSION: ${{ inputs.version }}
+      TAG: ${{ inputs.tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup QEMU
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: linux/arm64
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Setup Rust (Tauri)
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: aarch64-unknown-linux-gnu
+
+      - name: Install Linux build dependencies (Tauri)
+        run: |
+          sudo dpkg --add-architecture arm64
+          sudo tee /etc/apt/sources.list.d/arm64.list >/dev/null <<'EOF'
+          deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports noble main restricted universe multiverse
+          deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports noble-updates main restricted universe multiverse
+          deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports noble-security main restricted universe multiverse
+          deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports noble-backports main restricted universe multiverse
+          EOF
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            pkg-config \
+            gcc-aarch64-linux-gnu \
+            g++-aarch64-linux-gnu \
+            libgtk-3-dev:arm64 \
+            libglib2.0-dev:arm64 \
+            libwebkit2gtk-4.1-dev:arm64 \
+            libsoup-3.0-dev:arm64 \
+            libayatana-appindicator3-dev:arm64 \
+            librsvg2-dev:arm64
+
+      - name: Set workspace versions
+        run: npm version ${VERSION} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
+
+      - name: Install dependencies
+        run: npm ci --workspaces --include=optional
+
+      - name: Ensure rollup native binary
+        run: npm install @rollup/rollup-linux-arm64-gnu --no-save
+
+      - name: Build Linux bundle (Tauri arm64)
+        env:
+          TAURI_BUILD_TARGET: aarch64-unknown-linux-gnu
+          PKG_CONFIG_PATH: /usr/lib/aarch64-linux-gnu/pkgconfig
+          CC_aarch64_unknown_linux_gnu: aarch64-linux-gnu-gcc
+          CXX_aarch64_unknown_linux_gnu: aarch64-linux-gnu-g++
+          AR_aarch64_unknown_linux_gnu: aarch64-linux-gnu-ar
+        run: npm run build --workspace @codenomad/tauri-app
+
+      - name: Package Tauri artifacts (Linux arm64)
+        run: |
+          set -euo pipefail
+          SEARCH_ROOT="packages/tauri-app/target"
+          ARTIFACT_DIR="packages/tauri-app/release-tauri"
+          rm -rf "$ARTIFACT_DIR"
+          mkdir -p "$ARTIFACT_DIR"
+          shopt -s nullglob globstar
+          first_artifact=$(find "$SEARCH_ROOT" -type f \( -name "*.AppImage" -o -name "*.deb" -o -name "*.rpm" -o -name "*.tar.gz" \) | head -n1)
+          fallback_bin="$SEARCH_ROOT/release/codenomad-tauri"
+          if [ -n "$first_artifact" ]; then
+            zip -j "$ARTIFACT_DIR/CodeNomad-Tauri-${VERSION}-linux-x64.zip" "$first_artifact"
+          elif [ -f "$fallback_bin" ]; then
+            zip -j "$ARTIFACT_DIR/CodeNomad-Tauri-${VERSION}-linux-x64.zip" "$fallback_bin"
+          else
+            echo "No bundled artifact found under $SEARCH_ROOT and no binary at $fallback_bin" >&2
+            exit 1
+          fi
+
+
+      - name: Upload Tauri release assets (Linux arm64)
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          for file in packages/tauri-app/release-tauri/*.zip; do
+            [ -f "$file" ] || continue
+            echo "Uploading $file"
+            gh release upload "$TAG" "$file" --clobber
+          done
+
+
+  build-linux-rpm:
+    runs-on: ubuntu-24.04
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      VERSION: ${{ inputs.version }}
+      TAG: ${{ inputs.tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Install rpm packaging dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y rpm ruby ruby-dev build-essential
+          sudo gem install --no-document fpm
+
+      - name: Set workspace versions
+        if: ${{ inputs.set_versions && inputs.version != '' }}
+        run: npm version ${VERSION} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
+
+      - name: Install project dependencies
+        run: npm ci --workspaces --include=optional
+
+      - name: Ensure rollup native binary
+        run: npm install @rollup/rollup-linux-x64-gnu --no-save
+
+      - name: Build Linux RPM binaries
+        run: npm run build:linux-rpm --workspace @neuralnomads/codenomad-electron-app
+
+      - name: Upload RPM release assets
+        if: ${{ inputs.upload && inputs.tag != '' }}
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          for file in packages/electron-app/release/*.rpm; do
+            [ -f "$file" ] || continue
+            echo "Uploading $file"
+            gh release upload "$TAG" "$file" --clobber
+          done

.github/workflows/dev-release.yml

@@ -0,0 +1,18 @@
+name: Dev CI
+
+on:
+  push:
+    branches:
+      - dev
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  dev-ci:
+    uses: ./.github/workflows/build-and-upload.yml
+    with:
+      upload: false
+      set_versions: false
+    secrets: inherit

.github/workflows/manual-npm-publish.yml

@@ -0,0 +1,74 @@
+name: Manual NPM Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to publish (e.g. 0.2.0-dev)"
+        required: false
+        type: string
+      dist_tag:
+        description: "npm dist-tag"
+        required: false
+        default: dev
+        type: string
+  workflow_call:
+    inputs:
+      version:
+        required: true
+        type: string
+      dist_tag:
+        required: false
+        type: string
+        default: dev
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    env:
+      NODE_VERSION: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: https://registry.npmjs.org
+
+      - name: Ensure npm >=11.5.1
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: npm ci --workspaces
+
+      - name: Ensure rollup native binary
+        run: npm install @rollup/rollup-linux-x64-gnu --no-save
+
+      - name: Build server package (includes UI bundling)
+        run: npm run build --workspace @neuralnomads/codenomad
+
+      - name: Set publish metadata
+        shell: bash
+        run: |
+          VERSION_INPUT="${{ inputs.version }}"
+          if [ -z "$VERSION_INPUT" ]; then
+            VERSION_INPUT=$(node -p "require('./package.json').version")
+          fi
+          echo "VERSION=$VERSION_INPUT" >> "$GITHUB_ENV"
+          echo "DIST_TAG=${{ inputs.dist_tag || 'dev' }}" >> "$GITHUB_ENV"
+
+      - name: Bump package version for publish
+        run: npm version ${VERSION} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
+
+      - name: Publish server package with provenance
+        env:
+          NPM_CONFIG_PROVENANCE: true
+          NPM_CONFIG_REGISTRY: https://registry.npmjs.org
+        run: |
+          npm publish --workspace @neuralnomads/codenomad --access public --tag ${DIST_TAG} --provenance

.github/workflows/release.yml

@@ -6,211 +6,12 @@ on:
       - main
 
 permissions:
+  id-token: write
   contents: write
 
-env:
-  NODE_VERSION: 20
-
 jobs:
-  prepare-release:
+  release:
-    runs-on: ubuntu-latest
+    uses: ./.github/workflows/reusable-release.yml
-    outputs:
-      version: ${{ steps.get_version.outputs.version }}
-      tag: ${{ steps.ensure_tag.outputs.tag }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
     with:
-          node-version: ${{ env.NODE_VERSION }}
+      dist_tag: latest
-
+    secrets: inherit
-      - name: Read version
-        id: get_version
-        run: |
-          VERSION=$(node -p "require('./package.json').version")
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-
-      - name: Ensure git tag
-        id: ensure_tag
-        env:
-          VERSION: ${{ steps.get_version.outputs.version }}
-        run: |
-          TAG="v${VERSION}"
-          git fetch --tags
-          if git rev-parse "$TAG" >/dev/null 2>&1; then
-            echo "tag=$TAG" >> "$GITHUB_OUTPUT"
-            echo "Tag $TAG already exists"
-          else
-            git config user.name "github-actions[bot]"
-            git config user.email "github-actions[bot]@users.noreply.github.com"
-            git tag "$TAG"
-            git push origin "$TAG"
-            echo "tag=$TAG" >> "$GITHUB_OUTPUT"
-            echo "Created tag $TAG"
-          fi
-
-      - name: Ensure GitHub release
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          TAG: ${{ steps.ensure_tag.outputs.tag }}
-          VERSION: ${{ steps.get_version.outputs.version }}
-        run: |
-          if gh release view "$TAG" >/dev/null 2>&1; then
-            echo "Release $TAG already exists"
-          else
-            gh release create "$TAG" --title "CodeNomad v${VERSION}" --generate-notes
-          fi
-
-  build-macos:
-    needs: prepare-release
-    runs-on: macos-13
-    env:
-      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci --workspaces
-
-      - name: Build macOS binaries
-        run: npm run build:mac --workspace @codenomad/electron-app
-
-      - name: Upload release assets
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          TAG: ${{ needs.prepare-release.outputs.tag }}
-        run: |
-          set -euo pipefail
-          shopt -s nullglob
-          for file in packages/electron-app/release/*; do
-            [ -f "$file" ] || continue
-            case "$file" in
-              *.dmg|*.zip)
-                gh release upload "$TAG" "$file" --clobber
-                ;;
-              *)
-                echo "Skipping non-installer asset: $file"
-                ;;
-            esac
-          done
-
-  build-windows:
-    needs: prepare-release
-    runs-on: windows-latest
-    env:
-      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci --workspaces
-
-      - name: Build Windows binaries
-        run: npm run build:win --workspace @codenomad/electron-app
-
-      - name: Upload release assets
-        shell: pwsh
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          TAG: ${{ needs.prepare-release.outputs.tag }}
-        run: |
-          Get-ChildItem -Path "packages/electron-app/release" -File | Where-Object {
-            $_.Name -match '\.(exe|zip)$'
-          } | ForEach-Object {
-            gh release upload $env:TAG $_.FullName --clobber
-          }
-
-  build-linux:
-    needs: prepare-release
-    runs-on: ubuntu-latest
-    env:
-      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci --workspaces
-
-      - name: Build Linux binaries
-        run: npm run build:linux --workspace @codenomad/electron-app
-
-      - name: Upload release assets
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          TAG: ${{ needs.prepare-release.outputs.tag }}
-        run: |
-          set -euo pipefail
-          shopt -s nullglob
-          for file in packages/electron-app/release/*; do
-            [ -f "$file" ] || continue
-            case "$file" in
-              *.AppImage|*.deb|*.tar.gz)
-                gh release upload "$TAG" "$file" --clobber
-                ;;
-              *)
-                echo "Skipping non-installer asset: $file"
-                ;;
-            esac
-          done
-
-  build-linux-rpm:
-    needs: prepare-release
-    runs-on: ubuntu-latest
-    env:
-      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: npm
-
-      - name: Install rpm packaging dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y rpm ruby ruby-dev build-essential
-          sudo gem install --no-document fpm
-
-      - name: Install project dependencies
-        run: npm ci --workspaces
-
-      - name: Build Linux RPM binaries
-        run: npm run build:linux-rpm --workspace @codenomad/electron-app
-
-      - name: Upload RPM release assets
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          TAG: ${{ needs.prepare-release.outputs.tag }}
-        run: |
-          set -euo pipefail
-          shopt -s nullglob
-          for file in packages/electron-app/release/*.rpm; do
-            [ -f "$file" ] || continue
-            gh release upload "$TAG" "$file" --clobber
-          done

.github/workflows/reusable-release.yml

@@ -0,0 +1,80 @@
+name: Reusable Release
+
+on:
+  workflow_call:
+    inputs:
+      version_suffix:
+        description: "Suffix appended to package.json version"
+        required: false
+        default: ""
+        type: string
+      dist_tag:
+        description: "npm dist-tag to publish under"
+        required: false
+        default: dev
+        type: string
+
+permissions:
+  id-token: write
+  contents: write
+
+env:
+  NODE_VERSION: 20
+
+jobs:
+  prepare-release:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.versions.outputs.version }}
+      tag: ${{ steps.versions.outputs.tag }}
+      release_name: ${{ steps.versions.outputs.release_name }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Compute release versions
+        id: versions
+        env:
+          VERSION_SUFFIX: ${{ inputs.version_suffix }}
+        run: |
+          BASE_VERSION=$(node -p "require('./package.json').version")
+          VERSION="${BASE_VERSION}${VERSION_SUFFIX}"
+          TAG="v${VERSION}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "release_name=$TAG" >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.versions.outputs.tag }}
+        run: |
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Release $TAG already exists"
+          else
+            gh release create "$TAG" --title "$TAG" --generate-notes
+          fi
+
+  build-and-upload:
+    needs: prepare-release
+    uses: ./.github/workflows/build-and-upload.yml
+    with:
+      version: ${{ needs.prepare-release.outputs.version }}
+      tag: ${{ needs.prepare-release.outputs.tag }}
+      release_name: ${{ needs.prepare-release.outputs.release_name }}
+    secrets: inherit
+
+  publish-server:
+    needs:
+      - prepare-release
+      - build-and-upload
+    uses: ./.github/workflows/manual-npm-publish.yml
+    with:
+      version: ${{ needs.prepare-release.outputs.version }}
+      dist_tag: ${{ inputs.dist_tag }}
+    secrets: inherit

.gitignore

@@ -6,3 +6,5 @@ release/
 .vite/
 .electron-vite/
 out/
+.dir-locals.el
+.opencode/bashOutputs/

.opencode/agent/web_developer.md

@@ -1,6 +1,5 @@
 ---
 description: Develops Web UI components.
 mode: all
-model: zai-coding-plan/glm-4.6
 ---
 You are a Web Frontend Developer Agent. Your primary focus is on developing SolidJS UI components, ensuring adherence to modern web best practices, excellent UI/UX, and efficient data integration.

BUILD.md

@@ -13,7 +13,7 @@ This guide explains how to build distributable binaries for CodeNomad.
 All commands now run inside the workspace packages. From the repo root you can target the Electron app package directly:
 
 ```bash
-npm run build --workspace @codenomad/electron-app
+npm run build --workspace @neuralnomads/codenomad-electron-app
 ```
 
 ### Build for Current Platform (macOS default)
@@ -77,8 +77,8 @@ bun run build:all
 
 The build script performs these steps:
 
-1. **Compile TypeScript** → Electron app (main, preload, renderer)
+1. **Build @neuralnomads/codenomad** → Produces the CLI `dist/` bundle (also rebuilds the UI assets it serves)
-2. **Bundle with Vite** → Optimized production build
+2. **Compile TypeScript + bundle with Vite** → Electron main, preload, and renderer output in `dist/`
 3. **Package with electron-builder** → Platform-specific binaries
 
 ## Output

README.md

@@ -1,58 +1,94 @@
 # CodeNomad
-## A fast, multi-instance desktop client for running OpenCode sessions the way long-haul builders actually work.
 
-## What is CodeNomad?
+## A fast, multi-instance workspace for running OpenCode sessions.
 
-CodeNomad is built for people who live inside OpenCode for hours on end and need a cockpit, not a kiosk. When terminals get unwieldy and web clients feel laggy, CodeNomad delivers a desktop-native workspace that favors speed, clarity, and direct control. It runs on macOS, Windows, and Linux using Electron + SolidJS, with prebuilt binaries so you can get started immediately.
+CodeNomad is built for people who live inside OpenCode for hours on end and need a cockpit, not a kiosk. It delivers a premium, low-latency workspace that favors speed, clarity, and direct control.
 
 ![Multi-instance workspace](docs/screenshots/newSession.png)
+_Manage multiple OpenCode sessions side-by-side._
+
+<details>
+<summary>📸 More Screenshots</summary>
 
 ![Command palette overlay](docs/screenshots/command-palette.png)
+_Global command palette for keyboard-first control._
+
+![Image Previews](docs/screenshots/image-previews.png)
+_Rich media previews for images and assets._
+
+![Browser Support](docs/screenshots/browser-support.png)
+_Browser support via CodeNomad Server._
+
+</details>
+
+## Getting Started
+
+Choose the way that fits your workflow:
+
+### 🖥️ Desktop App (Recommended)
+The best experience. A native application (Electron-based) with global shortcuts, deeper system integration, and a dedicated window.
+
+- **Download**: Grab the latest installer for macOS, Windows, or Linux from the [Releases Page](https://github.com/shantur/CodeNomad/releases).
+- **Run**: Install and launch like any other app.
+
+### 🦀 Tauri App (Experimental)
+We are also working on a lightweight, high-performance version built with [Tauri](https://tauri.app). It is currently in active development.
+
+- **Download**: Experimental builds are available on the [Releases Page](https://github.com/shantur/CodeNomad/releases).
+- **Source**: Check out `packages/tauri-app` if you're interested in contributing.
+
+### 💻 CodeNomad Server
+Run CodeNomad as a local server and access it via your web browser. Perfect for remote development (SSH/VPN) or running as a service.
+
+```bash
+npx @neuralnomads/codenomad --launch
+```
+
+For dev version
+
+```bash
+npx @neuralnomads/codenomad@dev --launch
+```
+
+This command starts the server and opens the web client in your default browser.
 
 ## Highlights
 
-- **Long-session native** – scroll through massive transcripts without hitches and keep full context visible.
+- **Multi-Instance**: Juggle several OpenCode sessions side-by-side with tabs.
-- **Multiple instances, one window** – juggle several OpenCode instances side-by-side with per-instance tabs.
+- **Long-Session Native**: Scroll through massive transcripts without hitches.
-- **Deep task awareness** – jump into sub/child sessions (Tasks tool) instantly, monitor their status, and answer directly without losing your flow.
+- **Command Palette**: A single global palette to jump tabs, launch tools, and control everything.
-- **Keyboard first** – the full UI is optimized for shortcuts so you can stay mouse-free when you want to.
+- **Deep Task Awareness**: Monitor background tasks and child sessions without losing flow.
-- **Command palette superpowers** – summon a single, global palette to jump tabs, launch tools, tweak preferences, or fire shortcuts. Every action is categorized, fuzzy searchable, and previewed so you can chain moves together in seconds. It keeps your workflow predictable and fast whether you are juggling one session or ten.
-- **Developer-friendly rendering** – syntax highlighting, inline diffs, and thoughtful presentation keep the signal high.
 
 ## Requirements
 
-- [OpenCode CLI](https://opencode.ai) installed and available in your `PATH`, or point CodeNomad to a local binary through Advanced Settings.
+- **[OpenCode CLI](https://opencode.ai)**: Must be installed and available in your `PATH`.
+- **Node.js 18+**: Required if running the CLI server or building from source.
 
-## Repository Layout
+## Troubleshooting
 
-CodeNomad now ships as a small workspace with two packages:
+### macOS says the app is damaged
+If macOS reports that "CodeNomad.app is damaged and can't be opened," Gatekeeper flagged the download because the app is not yet notarized. You can clear the quarantine flag after moving CodeNomad into `/Applications`:
 
-- `packages/ui` — SolidJS renderer, Tailwind styles, and standalone Vite configuration for building the UI bundle independently.
+```bash
-- `packages/electron-app` — Electron main/preload processes plus packaging scripts. It consumes the UI package during development/build via `electron-vite`.
+xattr -l /Applications/CodeNomad.app
+xattr -dr com.apple.quarantine /Applications/CodeNomad.app
+```
 
-Use `npm run dev --workspace @codenomad/electron-app` for the Electron shell and `npm run dev --workspace @codenomad/ui` for UI-only work. Working with the workspace requires Node.js 18+ with npm 7 or newer so the workspace protocol is available.
+After removing the quarantine attribute, launch the app normally. On Intel Macs you may also need to approve CodeNomad from **System Settings → Privacy & Security** the first time you run it.
 
-## Downloads
+## Architecture & Development
 
-Grab the latest build for macOS, Windows, and Linux from the [GitHub Releases page](https://github.com/shantur/CodeNomad/releases).
+CodeNomad is a monorepo split into specialized packages. If you want to contribute or build from source, check out the individual package documentation:
 
-## Quick Start
+| Package | Description |
+|---------|-------------|
+| **[packages/electron-app](packages/electron-app/README.md)** | The native desktop application shell. Wraps the UI and Server. |
+| **[packages/server](packages/server/README.md)** | The core logic and CLI. Manages workspaces, proxies OpenCode, and serves the API. |
+| **[packages/ui](packages/ui/README.md)** | The SolidJS-based frontend. Fast, reactive, and beautiful. |
 
-1. Install the OpenCode CLI and confirm it is reachable via your terminal.
+### Quick Build
-2. Download the CodeNomad build for your platform and launch the app.
+To build the Desktop App from source:
-3. Connect to one or more OpenCode instances, set keyboard shortcuts in preferences, and start a session.
-4. Use tabs to swap between instances, the task sidebar to dive into child sessions, and the prompt input to keep shipping.
-
-## CLI Server Flags
-
-The bundled CLI server (`@codenomad/cli`) controls which folders the UI can browse when you pick a workspace:
-
-- `--workspace-root <path>` (default: current working directory) scopes browsing to a safe subtree. The UI can only see folders beneath this root.
-- `--unrestricted-root` explicitly allows full-machine browsing for the current process. In this mode the UI starts from the host home directory, adds a "parent" option so you can reach `/` on macOS/Linux, and lists drives/UNC paths on Windows. The flag is runtime-only—restart the CLI without it to go back to restricted mode.
-- `--ui-dev-server <url>` proxies UI asset requests to a running Vite dev server while the CLI continues to expose its REST APIs and workspace proxies from the same port. Point this at `http://localhost:3000` when developing the renderer to keep hot reloads without sacrificing the single entry point.
-
-Use unrestricted mode only when you trust the host; the CLI will skip directories it cannot read and never persists the opt-in.
-
-### Single Port Proxying
-
-Every OpenCode instance now tunnels through the CLI port. Each workspace descriptor publishes a stable `proxyPath` (e.g., `/workspaces/<id>/instance`), and the CLI exposes `GET/POST/...` + SSE at `http(s)://<cli-host>:<cli-port>${proxyPath}`. That means the UI, Electron shell, and browser clients only need firewall access to the CLI; instance ports stay private on `127.0.0.1`. In development, the `--ui-dev-server` flag still routes UI traffic through the CLI proxy so all instance calls share the same origin.
 
+1.  Clone the repo.
+2.  Run `npm install` (requires pnpm or npm 7+ for workspaces).
+3.  Run `npm run build --workspace @neuralnomads/codenomad-electron-app`.

dev-docs/architecture.md

@@ -29,13 +29,13 @@ CodeNomad is a cross-platform desktop application built with Electron that provi
 │  │  │  State Management (SolidJS Stores)         │  │  │
 │  │  │  - instances[]                             │  │  │
 │  │  │  - sessions[] per instance                 │  │  │
-│  │  │  - messages[] per session                  │  │  │
+│  │  │  - normalized message store per session    │  │  │
 │  │  └────────────────────────────────────────────┘  │  │
 │  │  ┌────────────────────────────────────────────┐  │  │
 │  │  │  UI Components                             │  │  │
 │  │  │  - InstanceTabs                            │  │  │
 │  │  │  - SessionTabs                             │  │  │
-│  │  │  - MessageStream                           │  │  │
+│  │  │  - MessageSection                        │  │  │
 │  │  │  - PromptInput                             │  │  │
 │  │  └────────────────────────────────────────────┘  │  │
 │  └──────────────────────────────────────────────────┘  │

dev-docs/solidjs-llms.txt

@@ -0,0 +1,82 @@
+# SolidJS Documentation
+
+> Solid is a modern JavaScript framework for building user interfaces with fine-grained reactivity. It compiles JSX to real DOM elements and updates only what changes, delivering exceptional performance without a virtual DOM. Solid provides reactive primitives like signals, effects, and stores for predictable state management.
+
+SolidJS is a declarative JavaScript framework that prioritizes performance and developer experience. Unlike frameworks that re-run components on every update, Solid components run once during initialization and set up a reactive system that precisely updates the DOM when dependencies change.
+
+Key principles:
+- Fine-grained reactivity: Updates only the specific DOM nodes that depend on changed data
+- Compile-time optimization: JSX transforms into efficient DOM operations
+- Unidirectional data flow: Props are read-only, promoting predictable state management
+- Component lifecycle: Components run once, with reactive primitives handling updates
+
+**Use your web fetch tool on any of the following links to understand the relevant concept**.
+
+## Quick Start
+
+- [Overview](https://docs.solidjs.com/): Framework introduction and key advantages
+- [Quick Start](https://docs.solidjs.com/quick-start): Installation and project setup with create-solid
+- [Interactive Tutorial](https://www.solidjs.com/tutorial/introduction_basics): Learn Solid basics through guided examples
+- [Playground](https://playground.solidjs.com/): Experiment with Solid directly in your browser
+
+## Core Concepts
+
+- [Intro to Reactivity](https://docs.solidjs.com/concepts/intro-to-reactivity): Signals, subscribers, and reactive principles
+- [Understanding JSX](https://docs.solidjs.com/concepts/understanding-jsx): How Solid uses JSX and key differences from HTML
+- [Components Basics](https://docs.solidjs.com/concepts/components/basics): Component trees, lifecycles, and composition patterns
+- [Signals](https://docs.solidjs.com/concepts/signals): Core reactive primitive for state management with getters/setters
+- [Effects](https://docs.solidjs.com/concepts/effects): Side effects, dependency tracking, and lifecycle functions
+- [Stores](https://docs.solidjs.com/concepts/stores): Complex state management with proxy-based reactivity
+- [Context](https://docs.solidjs.com/concepts/context): Cross-component state sharing without prop drilling
+
+## Component APIs
+
+- [Props](https://docs.solidjs.com/concepts/components/props): Passing data and handlers to child components
+- [Event Handlers](https://docs.solidjs.com/concepts/components/event-handlers): Managing user interactions
+- [Class and Style](https://docs.solidjs.com/concepts/components/class-style): Dynamic styling approaches
+- [Refs](https://docs.solidjs.com/concepts/refs): Accessing DOM elements directly
+
+## Control Flow
+
+- [Conditional Rendering](https://docs.solidjs.com/concepts/control-flow/conditional-rendering): Show, Switch, and Match components
+- [List Rendering](https://docs.solidjs.com/concepts/control-flow/list-rendering): For, Index, and keyed iteration
+- [Dynamic](https://docs.solidjs.com/concepts/control-flow/dynamic): Dynamic component switching
+- [Portal](https://docs.solidjs.com/concepts/control-flow/portal): Rendering outside component hierarchy
+- [Error Boundary](https://docs.solidjs.com/concepts/control-flow/error-boundary): Graceful error handling
+
+## Derived Values
+
+- [Derived Signals](https://docs.solidjs.com/concepts/derived-values/derived-signals): Computed values from signals
+- [Memos](https://docs.solidjs.com/concepts/derived-values/memos): Cached computed values for performance
+
+## State Management
+
+- [Basic State Management](https://docs.solidjs.com/guides/state-management): One-way data flow and lifting state
+- [Complex State Management](https://docs.solidjs.com/guides/complex-state-management): Stores for scalable applications
+- [Fetching Data](https://docs.solidjs.com/guides/fetching-data): Async data with createResource
+
+## Routing
+
+- [Routing & Navigation](https://docs.solidjs.com/guides/routing-and-navigation): @solidjs/router setup and usage
+- [Dynamic Routes](https://docs.solidjs.com/guides/routing-and-navigation#dynamic-routes): Route parameters and validation
+- [Nested Routes](https://docs.solidjs.com/guides/routing-and-navigation#nested-routes): Hierarchical route structures
+- [Preload Functions](https://docs.solidjs.com/guides/routing-and-navigation#preload-functions): Parallel data fetching
+
+## Advanced Topics
+
+- [Fine-Grained Reactivity](https://docs.solidjs.com/advanced-concepts/fine-grained-reactivity): Deep dive into reactive system
+- [TypeScript](https://docs.solidjs.com/configuration/typescript): Type safety and configuration
+
+## Ecosystem
+
+- [Solid Router](https://docs.solidjs.com/solid-router/): File-system routing and data APIs
+- [SolidStart](https://docs.solidjs.com/solid-start/): Full-stack meta-framework
+- [Solid Meta](https://docs.solidjs.com/solid-meta/): Document head management
+- [Templates](https://github.com/solidjs/templates): Starter templates for different setups
+
+## Optional
+
+- [Ecosystem Libraries](https://www.solidjs.com/ecosystem): Community packages and tools
+- [API Reference](https://docs.solidjs.com/reference/): Complete API documentation
+- [Testing](https://docs.solidjs.com/guides/testing): Testing strategies and utilities
+- [Deployment](https://docs.solidjs.com/guides/deploying-your-app): Build and deployment options

dev-docs/technical-implementation.md

@@ -49,7 +49,7 @@ packages/opencode-client/
 │   ├── components/
 │   │   ├── instance-tabs.tsx       # Level 1 tabs
 │   │   ├── session-tabs.tsx        # Level 2 tabs
-│   │   ├── message-stream.tsx      # Messages display
+│   │   ├── message-stream-v2.tsx  # Messages display (normalized store)
 │   │   ├── message-item.tsx        # Single message
 │   │   ├── tool-call.tsx           # Tool execution display
 │   │   ├── prompt-input.tsx        # Input with attachments
@@ -153,16 +153,24 @@ interface Session {
     providerId: string
     modelId: string
   }
-  messages: Message[]
+  version: string
-  status: SessionStatus
+  time: { created: number; updated: number }
-  createdAt: number
+  revert?: {
-  updatedAt: number
+    messageID?: string
+    partID?: string
+    snapshot?: string
+    diff?: string
+  }
 }
 
+// Message content lives in the normalized message-v2 store
+// keyed by instanceId/sessionId/messageId
+
 type SessionStatus =
   | "idle" // No activity
   | "streaming" // Assistant responding
   | "error" // Error occurred
+
 ```
 
 ### UI Store

package.json

@@ -1,25 +1,33 @@
 {
   "name": "codenomad-workspace",
-  "version": "0.1.2",
+  "version": "0.5.1",
   "private": true,
   "description": "CodeNomad monorepo workspace",
   "workspaces": {
     "packages": [
-      "packages/*"
+      "packages/server",
+      "packages/ui",
+      "packages/electron-app",
+      "packages/tauri-app"
     ]
   },
   "scripts": {
-    "dev": "npm run dev --workspace @codenomad/electron-app",
+    "dev": "npm run dev --workspace @neuralnomads/codenomad-electron-app",
-    "dev:electron": "npm run dev --workspace @codenomad/electron-app",
+    "dev:electron": "npm run dev --workspace @neuralnomads/codenomad-electron-app",
-    "dev:ui": "npm run dev --workspace @codenomad/ui",
+    "dev:tauri": "npm run dev --workspace @codenomad/tauri-app",
-    "build": "npm run build --workspace @codenomad/electron-app",
+    "build": "npm run build --workspace @neuralnomads/codenomad-electron-app",
+    "build:tauri": "npm run build --workspace @codenomad/tauri-app",
     "build:ui": "npm run build --workspace @codenomad/ui",
-    "build:mac-x64": "npm run build:mac-x64 --workspace @codenomad/electron-app",
+    "build:mac-x64": "npm run build:mac-x64 --workspace @neuralnomads/codenomad-electron-app",
-    "build:binaries": "npm run build:binaries --workspace @codenomad/electron-app",
+    "build:binaries": "npm run build:binaries --workspace @neuralnomads/codenomad-electron-app",
-    "typecheck": "npm run typecheck --workspace @codenomad/ui && npm run typecheck --workspace @codenomad/electron-app"
+    "typecheck": "npm run typecheck --workspace @codenomad/ui && npm run typecheck --workspace @neuralnomads/codenomad-electron-app",
+    "bumpVersion": "npm version --workspaces --include-workspace-root --no-git-tag-version"
   },
   "dependencies": {
     "7zip-bin": "^5.2.0",
     "google-auth-library": "^10.5.0"
+  },
+  "devDependencies": {
+    "baseline-browser-mapping": "^2.9.11"
   }
 }

packages/cli/src/server/routes/meta.ts

@@ -1,10 +0,0 @@
-import { FastifyInstance } from "fastify"
-import { ServerMeta } from "../../api-types"
-
-interface RouteDeps {
-  serverMeta: ServerMeta
-}
-
-export function registerMetaRoutes(app: FastifyInstance, deps: RouteDeps) {
-  app.get("/api/meta", async () => deps.serverMeta)
-}

packages/cli/src/workspaces/manager.ts

@@ -1,173 +0,0 @@
-import path from "path"
-import { EventBus } from "../events/bus"
-import { ConfigStore } from "../config/store"
-import { BinaryRegistry } from "../config/binaries"
-import { FileSystemBrowser } from "../filesystem/browser"
-import { WorkspaceDescriptor, WorkspaceFileResponse, FileSystemEntry } from "../api-types"
-import { WorkspaceRuntime } from "./runtime"
-import { Logger } from "../logger"
-
-interface WorkspaceManagerOptions {
-  rootDir: string
-  configStore: ConfigStore
-  binaryRegistry: BinaryRegistry
-  eventBus: EventBus
-  logger: Logger
-}
-
-interface WorkspaceRecord extends WorkspaceDescriptor {}
-
-export class WorkspaceManager {
-  private readonly workspaces = new Map<string, WorkspaceRecord>()
-  private readonly runtime: WorkspaceRuntime
-
-  constructor(private readonly options: WorkspaceManagerOptions) {
-    this.runtime = new WorkspaceRuntime(this.options.eventBus, this.options.logger)
-  }
-
-  list(): WorkspaceDescriptor[] {
-    return Array.from(this.workspaces.values())
-  }
-
-  get(id: string): WorkspaceDescriptor | undefined {
-    return this.workspaces.get(id)
-  }
-
-  getInstancePort(id: string): number | undefined {
-    return this.workspaces.get(id)?.port
-  }
-
-  listFiles(workspaceId: string, relativePath = "."): FileSystemEntry[] {
-    const workspace = this.requireWorkspace(workspaceId)
-    const browser = new FileSystemBrowser({ rootDir: workspace.path })
-    return browser.list(relativePath)
-  }
-
-  readFile(workspaceId: string, relativePath: string): WorkspaceFileResponse {
-    const workspace = this.requireWorkspace(workspaceId)
-    const browser = new FileSystemBrowser({ rootDir: workspace.path })
-    const contents = browser.readFile(relativePath)
-    return {
-      workspaceId,
-      relativePath,
-      contents,
-    }
-  }
-
-  async create(folder: string, name?: string): Promise<WorkspaceDescriptor> {
-    const id = `${Date.now().toString(36)}`
-    const binary = this.options.binaryRegistry.resolveDefault()
-    const workspacePath = path.isAbsolute(folder) ? folder : path.resolve(this.options.rootDir, folder)
-
-    this.options.logger.info({ workspaceId: id, folder: workspacePath, binary: binary.path }, "Creating workspace")
-
-    const proxyPath = `/workspaces/${id}/instance`
-
-    const descriptor: WorkspaceRecord = {
-      id,
-      path: workspacePath,
-      name,
-      status: "starting",
-      proxyPath,
-      binaryId: binary.id,
-      binaryLabel: binary.label,
-      binaryVersion: binary.version,
-      createdAt: new Date().toISOString(),
-      updatedAt: new Date().toISOString(),
-    }
-
-    this.workspaces.set(id, descriptor)
-    this.options.eventBus.publish({ type: "workspace.created", workspace: descriptor })
-
-    const environment = this.options.configStore.get().preferences.environmentVariables ?? {}
-
-    try {
-      const { pid, port } = await this.runtime.launch({
-        workspaceId: id,
-        folder: workspacePath,
-        binaryPath: binary.path,
-        environment,
-        onExit: (info) => this.handleProcessExit(info.workspaceId, info),
-      })
-
-      descriptor.pid = pid
-      descriptor.port = port
-      descriptor.status = "ready"
-      descriptor.updatedAt = new Date().toISOString()
-      this.options.eventBus.publish({ type: "workspace.started", workspace: descriptor })
-      this.options.logger.info({ workspaceId: id, port }, "Workspace ready")
-      return descriptor
-    } catch (error) {
-      descriptor.status = "error"
-      descriptor.error = error instanceof Error ? error.message : String(error)
-      descriptor.updatedAt = new Date().toISOString()
-      this.options.eventBus.publish({ type: "workspace.error", workspace: descriptor })
-      this.options.logger.error({ workspaceId: id, err: error }, "Workspace failed to start")
-      throw error
-    }
-  }
-
-  async delete(id: string): Promise<WorkspaceDescriptor | undefined> {
-    const workspace = this.workspaces.get(id)
-    if (!workspace) return undefined
-
-    this.options.logger.info({ workspaceId: id }, "Stopping workspace")
-    const wasRunning = Boolean(workspace.pid)
-    if (wasRunning) {
-      await this.runtime.stop(id).catch((error) => {
-        this.options.logger.warn({ workspaceId: id, err: error }, "Failed to stop workspace process cleanly")
-      })
-    }
-
-    this.workspaces.delete(id)
-    if (!wasRunning) {
-      this.options.eventBus.publish({ type: "workspace.stopped", workspaceId: id })
-    }
-    return workspace
-  }
-
-  async shutdown() {
-    this.options.logger.info("Shutting down all workspaces")
-    for (const [id, workspace] of this.workspaces) {
-      if (workspace.pid) {
-        this.options.logger.info({ workspaceId: id }, "Stopping workspace during shutdown")
-        await this.runtime.stop(id).catch((error) => {
-          this.options.logger.error({ workspaceId: id, err: error }, "Failed to stop workspace during shutdown")
-        })
-      } else {
-        this.options.logger.debug({ workspaceId: id }, "Workspace already stopped")
-      }
-    }
-    this.workspaces.clear()
-    this.options.logger.info("All workspaces cleared")
-  }
-
-  private requireWorkspace(id: string): WorkspaceRecord {
-    const workspace = this.workspaces.get(id)
-    if (!workspace) {
-      throw new Error("Workspace not found")
-    }
-    return workspace
-  }
-
-  private handleProcessExit(workspaceId: string, info: { code: number | null; requested: boolean }) {
-    const workspace = this.workspaces.get(workspaceId)
-    if (!workspace) return
-
-    this.options.logger.info({ workspaceId, ...info }, "Workspace process exited")
-
-    workspace.pid = undefined
-    workspace.port = undefined
-    workspace.updatedAt = new Date().toISOString()
-
-    if (info.requested || info.code === 0) {
-      workspace.status = "stopped"
-      workspace.error = undefined
-      this.options.eventBus.publish({ type: "workspace.stopped", workspaceId })
-    } else {
-      workspace.status = "error"
-      workspace.error = `Process exited with code ${info.code}`
-      this.options.eventBus.publish({ type: "workspace.error", workspace })
-    }
-  }
-}

packages/electron-app/README.md

@@ -0,0 +1,40 @@
+# CodeNomad App
+
+This package contains the native desktop application shell for CodeNomad, built with [Electron](https://www.electronjs.org/).
+
+## Overview
+
+The Electron app wraps the CodeNomad UI and Server into a standalone executable. It provides deeper system integration, such as:
+- Native window management
+- Global keyboard shortcuts
+- Application menu integration
+
+## Development
+
+To run the Electron app in development mode:
+
+```bash
+npm run dev
+```
+
+This will start the renderer (UI) and the main process with hot reloading.
+
+## Building
+
+To build the application for your current platform:
+
+```bash
+npm run build
+```
+
+To build for specific platforms (requires appropriate build tools):
+
+- **macOS**: `npm run build:mac`
+- **Windows**: `npm run build:win`
+- **Linux**: `npm run build:linux`
+
+## Structure
+
+- `electron/main`: Main process code (window creation, IPC).
+- `electron/preload`: Preload scripts for secure bridge between main and renderer.
+- `electron/resources`: Static assets like icons.

packages/electron-app/electron.vite.config.ts

@@ -6,6 +6,7 @@ const uiRoot = resolve(__dirname, "../ui")
 const uiSrc = resolve(uiRoot, "src")
 const uiRendererRoot = resolve(uiRoot, "src/renderer")
 const uiRendererEntry = resolve(uiRendererRoot, "index.html")
+const uiRendererLoadingEntry = resolve(uiRendererRoot, "loading.html")
 
 export default defineConfig({
   main: {
@@ -25,7 +26,7 @@ export default defineConfig({
     build: {
       outDir: "dist/preload",
       lib: {
-        entry: resolve(__dirname, "electron/preload/index.ts"),
+        entry: resolve(__dirname, "electron/preload/index.cjs"),
         formats: ["cjs"],
         fileName: () => "index.js",
       },
@@ -52,9 +53,19 @@ export default defineConfig({
       port: 3000,
     },
     build: {
+      minify: false,
+      cssMinify: false,
+      sourcemap: true,
       outDir: resolve(__dirname, "dist/renderer"),
       rollupOptions: {
-        input: uiRendererEntry,
+        input: {
+          main: uiRendererEntry,
+          loading: uiRendererLoadingEntry,
+        },
+        output: {
+          compact: false,
+          minifyInternalExports: false,
+        },
       },
     },
   },

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

@@ -1,243 +1,65 @@
-import { ipcMain, BrowserWindow, dialog } from "electron"
+import { BrowserWindow, dialog, ipcMain, type OpenDialogOptions } from "electron"
-import { processManager } from "./process-manager"
+import type { CliProcessManager, CliStatus } from "./process-manager"
-import { randomBytes } from "crypto"
-import * as fs from "fs"
-import * as path from "path"
-import { spawn } from "child_process"
-import ignore from "ignore"
 
-interface Instance {
+interface DialogOpenRequest {
-  id: string
+  mode: "directory" | "file"
-  folder: string
+  title?: string
-  port: number
+  defaultPath?: string
-  pid: number
+  filters?: Array<{ name?: string; extensions: string[] }>
-  status: "starting" | "ready" | "error" | "stopped"
-  error?: string
 }
 
-const instances = new Map<string, Instance>()
+interface DialogOpenResult {
-
+  canceled: boolean
-function generateId(): string {
+  paths: string[]
-  return randomBytes(16).toString("hex")
 }
 
-function runBinaryVersion(binaryPath: string, timeoutMs = 5000): Promise<string> {
+export function setupCliIPC(mainWindow: BrowserWindow, cliManager: CliProcessManager) {
-  return new Promise((resolve, reject) => {
+  cliManager.on("status", (status: CliStatus) => {
-    const child = spawn(binaryPath, ["-v"], {
+    if (!mainWindow.isDestroyed()) {
-      stdio: ["ignore", "pipe", "pipe"],
+      mainWindow.webContents.send("cli:status", status)
-    })
-
-    let stdout = ""
-    let stderr = ""
-
-    const timeout = setTimeout(() => {
-      child.kill("SIGTERM")
-      reject(new Error("Version check timed out"))
-    }, 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() || `Binary exited with code ${code}`))
     }
   })
-  })
+
-}
+  cliManager.on("ready", (status: CliStatus) => {
-
+    if (!mainWindow.isDestroyed()) {
-export function setupInstanceIPC(mainWindow: BrowserWindow) {
+      mainWindow.webContents.send("cli:ready", status)
-  processManager.setMainWindow(mainWindow)
+    }
-
+  })
-  ipcMain.handle("dialog:selectFolder", async () => {
+
-    const result = await dialog.showOpenDialog(mainWindow!, {
+  cliManager.on("error", (error: Error) => {
-      title: "Select Project Folder",
+    if (!mainWindow.isDestroyed()) {
-      properties: ["openDirectory"],
+      mainWindow.webContents.send("cli:error", { message: error.message })
-    })
+    }
-
+  })
-    if (result.canceled || !result.filePaths.length) {
+
-      return null
+  ipcMain.handle("cli:getStatus", async () => cliManager.getStatus())
-    }
+
-
+  ipcMain.handle("cli:restart", async () => {
-    return result.filePaths[0]
+    const devMode = process.env.NODE_ENV === "development"
-  })
+    await cliManager.stop()
-
+    return cliManager.start({ dev: devMode })
-  ipcMain.handle(
+  })
-    "instance:create",
+
-    async (event, id: string, folder: string, binaryPath?: string, environmentVariables?: Record<string, string>) => {
+  ipcMain.handle("dialog:open", async (_, request: DialogOpenRequest): Promise<DialogOpenResult> => {
-      const instance: Instance = {
+    const properties: OpenDialogOptions["properties"] =
-        id,
+      request.mode === "directory" ? ["openDirectory", "createDirectory"] : ["openFile"]
-        folder,
+
-        port: 0,
+    const filters = request.filters?.map((filter) => ({
-        pid: 0,
+      name: filter.name ?? "Files",
-        status: "starting",
+      extensions: filter.extensions,
-      }
+    }))
-
+
-      instances.set(id, instance)
+    const windowTarget = mainWindow.isDestroyed() ? undefined : mainWindow
-
+    const dialogOptions: OpenDialogOptions = {
-      try {
+      title: request.title,
-        const {
+      defaultPath: request.defaultPath,
-          pid,
+      properties,
-          port,
+      filters,
-          binaryPath: actualBinaryPath,
+    }
-        } = await processManager.spawn(folder, id, binaryPath, environmentVariables)
+    const result = windowTarget
-
+      ? await dialog.showOpenDialog(windowTarget, dialogOptions)
-        instance.port = port
+      : await dialog.showOpenDialog(dialogOptions)
-        instance.pid = pid
+
-        instance.status = "ready"
+    return { canceled: result.canceled, paths: result.filePaths }
-
-        mainWindow.webContents.send("instance:started", { id, port, pid, binaryPath: actualBinaryPath })
-
-        const meta = processManager.getAllProcesses().get(pid)
-        if (meta) {
-          meta.childProcess.on("exit", (code, signal) => {
-            instance.status = "stopped"
-            mainWindow.webContents.send("instance:stopped", { id })
-          })
-        }
-
-        return { id, port, pid, binaryPath: actualBinaryPath }
-      } catch (error) {
-        instance.status = "error"
-        instance.error = error instanceof Error ? error.message : String(error)
-
-        mainWindow.webContents.send("instance:error", {
-          id,
-          error: instance.error,
-        })
-
-        throw error
-      }
-    },
-  )
-
-  ipcMain.handle("instance:stop", async (event, pid: number) => {
-    await processManager.kill(pid)
-
-    for (const [id, instance] of instances.entries()) {
-      if (instance.pid === pid) {
-        instance.status = "stopped"
-        break
-      }
-    }
-  })
-
-  ipcMain.handle("instance:status", async (event, pid: number) => {
-    return processManager.getStatus(pid)
-  })
-
-  ipcMain.handle("instance:list", async () => {
-    return Array.from(instances.values())
-  })
-
-  ipcMain.handle("fs:scanDirectory", async (event, workspaceFolder: string) => {
-    const ig = ignore()
-    ig.add([".git", "node_modules"])
-
-    const gitignorePath = path.join(workspaceFolder, ".gitignore")
-    if (fs.existsSync(gitignorePath)) {
-      const content = fs.readFileSync(gitignorePath, "utf-8")
-      ig.add(content)
-    }
-
-    function scanDir(dirPath: string, baseDir: string): string[] {
-      const results: string[] = []
-
-      try {
-        const entries = fs.readdirSync(dirPath, { withFileTypes: true })
-
-        for (const entry of entries) {
-          const fullPath = path.join(dirPath, entry.name)
-          const relativePath = path.relative(baseDir, fullPath)
-
-          if (ig.ignores(relativePath)) {
-            continue
-          }
-
-          if (entry.isDirectory()) {
-            const dirWithSlash = relativePath + "/"
-            if (!ig.ignores(dirWithSlash)) {
-              results.push(dirWithSlash)
-              const subFiles = scanDir(fullPath, baseDir)
-              results.push(...subFiles)
-            }
-          } else {
-            results.push(relativePath)
-          }
-        }
-      } catch (error) {
-        console.warn(`Error scanning ${dirPath}:`, error)
-      }
-
-      return results
-    }
-
-    return scanDir(workspaceFolder, workspaceFolder)
-  })
-
-  // OpenCode binary operations
-  ipcMain.handle("dialog:selectOpenCodeBinary", async () => {
-    const result = await dialog.showOpenDialog(mainWindow!, {
-      title: "Select OpenCode Binary",
-      filters: [
-        { name: "Executable Files", extensions: ["exe", "cmd", "bat", "sh", "command", "app", ""] },
-        { name: "All Files", extensions: ["*"] },
-      ],
-      properties: ["openFile"],
-    })
-
-    if (result.canceled || !result.filePaths.length) {
-      return null
-    }
-
-    return result.filePaths[0]
-  })
-
-  ipcMain.handle("opencode:validateBinary", async (event, binaryPath: string) => {
-    try {
-      // Special handling for system PATH binary
-      const isSystemPath = binaryPath === "opencode"
-
-      if (!isSystemPath) {
-        // Check if file exists and is executable for custom paths
-        if (!fs.existsSync(binaryPath)) {
-          return { valid: false, error: "File does not exist" }
-        }
-
-        const stats = fs.statSync(binaryPath)
-        if (!stats.isFile()) {
-          return { valid: false, error: "Path is not a file" }
-        }
-      }
-
-      // Try to get version once via -v flag
-      try {
-        const version = await runBinaryVersion(binaryPath)
-        return { valid: true, version }
-      } catch (error) {
-        return {
-          valid: false,
-          error: error instanceof Error ? error.message : String(error),
-        }
-      }
-    } catch (error) {
-      return {
-        valid: false,
-        error: error instanceof Error ? error.message : String(error),
-      }
-    }
   })
 }

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

@@ -1,30 +1,190 @@
-import { app, BrowserWindow, dialog, ipcMain, nativeImage, nativeTheme, session } from "electron"
+import { app, BrowserView, BrowserWindow, nativeImage, session, shell } from "electron"
-import { join } from "path"
+import { existsSync } from "fs"
+import { dirname, join } from "path"
+import { fileURLToPath } from "url"
 import { createApplicationMenu } from "./menu"
-import { setupInstanceIPC } from "./ipc"
+import { setupCliIPC } from "./ipc"
-import { setupStorageIPC } from "./storage"
+import { CliProcessManager } from "./process-manager"
+
+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
+
 if (isMac) {
   app.commandLine.appendSwitch("disable-spell-checking")
 }
 
-// Setup IPC handlers before creating windows
-setupStorageIPC()
-
-let mainWindow: BrowserWindow | null = null
-
 function getIconPath() {
   if (app.isPackaged) {
     return join(process.resourcesPath, "icon.png")
   }
 
-  return join(app.getAppPath(), "electron/resources/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)
+  })
+}
+
+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 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 //nativeTheme.shouldUseDarkColors
+  const prefersDark = true
   const backgroundColor = prefersDark ? "#1a1a1a" : "#ffffff"
   const iconPath = getIconPath()
 
@@ -36,33 +196,146 @@ function createWindow() {
     backgroundColor,
     icon: iconPath,
     webPreferences: {
-      preload: join(__dirname, "../preload/index.js"),
+      preload: getPreloadPath(),
       contextIsolation: true,
       nodeIntegration: false,
       spellcheck: !isMac,
     },
   })
 
+  setupNavigationGuards(mainWindow)
+
   if (isMac) {
-    // Disable macOS spell server to avoid input lag
     mainWindow.webContents.session.setSpellCheckerEnabled(false)
   }
 
+  showingLoadingScreen = true
+  currentCliUrl = null
+  loadLoadingScreen(mainWindow)
+
   if (process.env.NODE_ENV === "development") {
-    mainWindow.loadURL("http://localhost:3000")
+    mainWindow.webContents.openDevTools({ mode: "detach" })
-    mainWindow.webContents.openDevTools()
-  } else {
-    mainWindow.loadFile(join(__dirname, "../renderer/index.html"))
   }
 
   createApplicationMenu(mainWindow)
-  setupInstanceIPC(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
+  mainWindow.loadURL(url).catch((error) => console.error("[cli] failed to load CLI view:", error))
+}
+
+
+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)
@@ -70,6 +343,8 @@ if (isMac) {
 }
 
 app.whenReady().then(() => {
+  startCli()
+
   if (isMac) {
     session.defaultSession.setSpellCheckerEnabled(false)
     app.on("browser-window-created", (_, window) => {
@@ -84,8 +359,6 @@ app.whenReady().then(() => {
     }
   }
 
-  console.log("[spellcheck] default session enabled:", session.defaultSession.isSpellCheckerEnabled())
-
   createWindow()
 
   app.on("activate", () => {
@@ -95,6 +368,12 @@ app.whenReady().then(() => {
   })
 })
 
+app.on("before-quit", async (event) => {
+  event.preventDefault()
+  await cliManager.stop().catch(() => {})
+  app.exit(0)
+})
+
 app.on("window-all-closed", () => {
   if (process.platform !== "darwin") {
     app.quit()

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

@@ -1,218 +1,186 @@
-import { spawn, execSync, ChildProcess } from "child_process"
+import { spawn, type ChildProcess } from "child_process"
-import { app, BrowserWindow } from "electron"
+import { app } from "electron"
-import { existsSync, statSync } from "fs"
+import { createRequire } from "module"
-import { buildUserShellCommand, getUserShellEnv, runUserShellCommandSync, supportsUserShell } from "./user-shell"
+import { EventEmitter } from "events"
+import { existsSync, readFileSync } from "fs"
+import os from "os"
+import path from "path"
+import { buildUserShellCommand, getUserShellEnv, supportsUserShell } from "./user-shell"
 
-export interface ProcessInfo {
+const nodeRequire = createRequire(import.meta.url)
-  pid: number
+
-  port: number
+
-  binaryPath: string
+type CliState = "starting" | "ready" | "error" | "stopped"
+type ListeningMode = "local" | "all"
+
+export interface CliStatus {
+  state: CliState
+  pid?: number
+  port?: number
+  url?: string
+  error?: string
 }
 
-interface ProcessMeta {
+export interface CliLogEntry {
-  pid: number
+  stream: "stdout" | "stderr"
-  port: number
+  message: string
-  folder: string
-  startTime: number
-  childProcess: ChildProcess
-  logs: string[]
-  instanceId: string
 }
 
-class ProcessManager {
+interface StartOptions {
-  private processes = new Map<number, ProcessMeta>()
+  dev: boolean
-  private mainWindow: BrowserWindow | null = null
+}
 
-  setMainWindow(window: BrowserWindow) {
+interface CliEntryResolution {
-    this.mainWindow = window
+  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 = ""
+
+  async start(options: StartOptions): Promise<CliStatus> {
+    if (this.child) {
+      await this.stop()
     }
 
-  private parseLogLevel(message: string): "info" | "error" | "warn" | "debug" {
+    this.stdoutBuffer = ""
-    const upperMessage = message.toUpperCase()
+    this.stderrBuffer = ""
-    if (upperMessage.includes("[ERROR]") || upperMessage.includes("ERROR:")) return "error"
+    this.updateStatus({ state: "starting", port: undefined, pid: undefined, url: undefined, error: undefined })
-    if (upperMessage.includes("[WARN]") || upperMessage.includes("WARN:")) return "warn"
-    if (upperMessage.includes("[DEBUG]") || upperMessage.includes("DEBUG:")) return "debug"
-    if (upperMessage.includes("[INFO]") || upperMessage.includes("INFO:")) return "info"
-    return "info"
-  }
 
-  private sendLog(instanceId: string, level: "info" | "error" | "warn" | "debug", message: string) {
+    const cliEntry = this.resolveCliEntry(options)
-    if (this.mainWindow && message.trim()) {
+    const listeningMode = this.resolveListeningMode()
-      const parsedLevel = this.parseLogLevel(message)
+    const host = resolveHostForMode(listeningMode)
-      this.mainWindow.webContents.send("instance:log", {
+    const args = this.buildCliArgs(options, host)
-        id: instanceId,
-        entry: {
-          timestamp: Date.now(),
-          level: parsedLevel,
-          message: message.trim(),
-        },
-      })
-    }
-  }
 
-  async spawn(
+    console.info(
-    folder: string,
+      `[cli] launching CodeNomad CLI (${options.dev ? "dev" : "prod"}) using ${cliEntry.runner} at ${cliEntry.entry} (host=${host})`,
-    instanceId: string,
-    binaryPath?: string,
-    environmentVariables?: Record<string, string>,
-  ): Promise<ProcessInfo> {
-    this.validateFolder(folder)
-    const useUserShell = supportsUserShell()
-    const logAttempt = (message: string) => {
-      console.info(`[ProcessManager] ${message}`)
-      this.sendLog(instanceId, "debug", message)
-    }
-
-    const env = useUserShell ? getUserShellEnv() : { ...process.env }
-    if (environmentVariables) {
-      Object.assign(env, environmentVariables)
-      this.sendLog(
-        instanceId,
-        "info",
-        `Using ${Object.keys(environmentVariables).length} custom environment variables:`,
     )
 
-      // Log each environment variable
+    const env = supportsUserShell() ? getUserShellEnv() : { ...process.env }
-      for (const [key, value] of Object.entries(environmentVariables)) {
+    env.ELECTRON_RUN_AS_NODE = "1"
-        this.sendLog(instanceId, "info", `  ${key}=${value}`)
-      }
-    }
 
-    let targetBinary: string
+    const spawnDetails = supportsUserShell()
-    if (!binaryPath || binaryPath === "opencode") {
+      ? buildUserShellCommand(`ELECTRON_RUN_AS_NODE=1 exec ${this.buildCommand(cliEntry, args)}`)
-      targetBinary = useUserShell ? "opencode" : this.validateOpenCodeBinary(logAttempt)
+      : this.buildDirectSpawn(cliEntry, args)
-    } else {
-      targetBinary = this.validateCustomBinary(binaryPath, logAttempt)
-    }
 
-    const spawnCommand = useUserShell
+    const child = spawn(spawnDetails.command, spawnDetails.args, {
-      ? this.buildShellServeCommand(targetBinary)
+      cwd: process.cwd(),
-      : { command: targetBinary, args: this.buildServeArgs() }
-
-    const launchDetail = `${spawnCommand.command} ${spawnCommand.args.join(" ")}`.trim()
-    this.sendLog(instanceId, "debug", `Launching process with: ${launchDetail}`)
-
-    this.sendLog(
-      instanceId,
-      "info",
-      `Starting OpenCode server for ${folder} using ${targetBinary}...`,
-    )
-
-    return new Promise((resolve, reject) => {
-      const child = spawn(spawnCommand.command, spawnCommand.args, {
-        cwd: folder,
       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")
+    }
 
-      const timeout = setTimeout(() => {
+    this.child = child
-        child.kill("SIGKILL")
+    this.updateStatus({ pid: child.pid ?? undefined })
-        this.sendLog(instanceId, "error", "Server startup timeout (10s exceeded)")
-        reject(new Error("Server startup timeout (10s exceeded)"))
-      }, 10000)
-
-      let stdoutBuffer = ""
-      let stderrBuffer = ""
-      let portFound = false
 
     child.stdout?.on("data", (data: Buffer) => {
-        const text = data.toString()
+      this.handleStream(data.toString(), "stdout")
-        stdoutBuffer += text
-
-        const lines = stdoutBuffer.split("\n")
-        stdoutBuffer = lines.pop() || ""
-
-        for (const line of lines) {
-          if (!line.trim()) continue
-
-          this.sendLog(instanceId, "info", line)
-
-          const portMatch = line.match(/opencode server listening on http:\/\/[^:]+:(\d+)/)
-          if (portMatch && !portFound) {
-            portFound = true
-            const port = parseInt(portMatch[1], 10)
-            clearTimeout(timeout)
-
-            const meta: ProcessMeta = {
-              pid: child.pid!,
-              port,
-              folder,
-              startTime: Date.now(),
-              childProcess: child,
-              logs: [line],
-              instanceId,
-            }
-
-            this.processes.set(child.pid!, meta)
-            resolve({ pid: child.pid!, port, binaryPath: targetBinary })
-          }
-
-          const meta = this.processes.get(child.pid!)
-          if (meta) {
-            meta.logs.push(line)
-          }
-        }
     })
 
     child.stderr?.on("data", (data: Buffer) => {
-        const text = data.toString()
+      this.handleStream(data.toString(), "stderr")
-        stderrBuffer += text
-
-        const lines = stderrBuffer.split("\n")
-        stderrBuffer = lines.pop() || ""
-
-        for (const line of lines) {
-          if (!line.trim()) continue
-
-          this.sendLog(instanceId, "error", line)
-
-          const meta = this.processes.get(child.pid!)
-          if (meta) {
-            meta.logs.push(line)
-          }
-        }
     })
 
     child.on("error", (error) => {
-        clearTimeout(timeout)
+      console.error("[cli] failed to start CLI:", error)
-        if (error.message.includes("ENOENT")) {
+      this.updateStatus({ state: "error", error: error.message })
-          reject(new Error("opencode binary not found in PATH"))
+      this.emit("error", error)
-        } else {
-          reject(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)
-        this.processes.delete(child.pid!)
+        resolve(status)
+      })
 
-        if (!portFound) {
+      this.once("error", (error) => {
-          const errorMsg = stderrBuffer || `Process exited with code ${code}`
+        clearTimeout(timeout)
-          reject(new Error(errorMsg))
+        reject(error)
-        }
       })
     })
   }
 
-  async kill(pid: number): Promise<void> {
+  async stop(): Promise<void> {
-    const meta = this.processes.get(pid)
+    const child = this.child
-    if (!meta) {
+    if (!child) {
-      // Treat unknown processes as already stopped so tabs close cleanly
+      this.updateStatus({ state: "stopped" })
       return
     }
 
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve) => {
-      const child = meta.childProcess
-
       const killTimeout = setTimeout(() => {
         child.kill("SIGKILL")
-      }, 2000)
+      }, 4000)
 
       child.on("exit", () => {
         clearTimeout(killTimeout)
-        this.processes.delete(pid)
+        this.child = undefined
+        console.info("[cli] CLI process exited")
+        this.updateStatus({ state: "stopped" })
         resolve()
       })
 
@@ -220,134 +188,177 @@ class ProcessManager {
     })
   }
 
-  getStatus(pid: number): "running" | "stopped" | "unknown" {
+  getStatus(): CliStatus {
-    if (!this.processes.has(pid)) {
+    return { ...this.status }
-      return "unknown"
   }
 
+  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 {
-      process.kill(pid, 0)
+        const parsed = JSON.parse(line)
-      return "running"
+        if (typeof parsed.port === "number") {
+          return parsed.port
+        }
       } catch {
-      return "stopped"
+        // not JSON, ignore
       }
     }
 
-  getAllProcesses(): Map<number, ProcessMeta> {
+    return null
-    return new Map(this.processes)
   }
 
-  async cleanup(): Promise<void> {
+  private updateStatus(patch: Partial<CliStatus>) {
-    const killPromises = Array.from(this.processes.keys()).map((pid) => this.kill(pid).catch(() => {}))
+    this.status = { ...this.status, ...patch }
-    await Promise.all(killPromises)
+    this.emit("status", this.status)
   }
 
-  private validateFolder(folder: string): void {
+  private buildCliArgs(options: StartOptions, host: string): string[] {
-    if (!existsSync(folder)) {
+    const args = ["serve", "--host", host, "--port", "0"]
-      throw new Error(`Folder does not exist: ${folder}`)
+
+    if (options.dev) {
+      args.push("--ui-dev-server", "http://localhost:3000", "--log-level", "debug")
     }
 
-    const stats = statSync(folder)
+    return args
-    if (!stats.isDirectory()) {
-      throw new Error(`Path is not a directory: ${folder}`)
-    }
   }
 
-  private validateOpenCodeBinary(logAttempt?: (message: string) => void): string {
+  private buildCommand(cliEntry: CliEntryResolution, args: string[]): string {
-    const log = logAttempt ?? ((message: string) => console.info(`[ProcessManager] ${message}`))
+    const parts = [JSON.stringify(process.execPath)]
-
+    if (cliEntry.runner === "tsx" && cliEntry.runnerPath) {
-    if (process.platform === "win32") {
+      parts.push(JSON.stringify(cliEntry.runnerPath))
-      log("Checking PATH via 'where opencode'")
+    }
-      return this.resolveBinaryViaLocator("where opencode", log)
+    parts.push(JSON.stringify(cliEntry.entry))
+    args.forEach((arg) => parts.push(JSON.stringify(arg)))
+    return parts.join(" ")
   }
 
-    const shellCheck = buildUserShellCommand("command -v opencode")
+  private buildDirectSpawn(cliEntry: CliEntryResolution, args: string[]) {
-    const shellPreview = [shellCheck.command, ...shellCheck.args].join(" ")
+    if (cliEntry.runner === "tsx") {
-    log(`Checking PATH via shell: ${shellPreview}`)
+      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 = runUserShellCommandSync("command -v opencode")
+        const resolved = typeof candidate === "function" ? candidate() : candidate
-      const path = this.pickFirstPath(resolved)
+        if (resolved && existsSync(resolved)) {
-      if (path) {
+          return resolved
-        log(`Shell located opencode at ${path}`)
-        return path
         }
-      throw new Error("Empty result from shell lookup")
-    } catch (shellError) {
-      const message = shellError instanceof Error ? shellError.message : String(shellError)
-      log(`Shell lookup failed: ${message}`)
-      try {
-        log("Fallback to 'which opencode'")
-        return this.resolveBinaryViaLocator("which opencode", log)
-      } catch (locatorError) {
-        const locatorMessage = locatorError instanceof Error ? locatorError.message : String(locatorError)
-        log(`Locator fallback failed: ${locatorMessage}`)
-        throw new Error(
-          "opencode binary not found in PATH. Please install OpenCode CLI first: npm install -g @opencode/cli",
-        )
-      }
-    }
-  }
-
-  private validateCustomBinary(binaryPath: string, log?: (message: string) => void): string {
-    log?.(`Validating custom binary at ${binaryPath}`)
-
-    if (!existsSync(binaryPath)) {
-      throw new Error(`OpenCode binary not found: ${binaryPath}`)
-    }
-
-    const stats = statSync(binaryPath)
-    if (!stats.isFile()) {
-      throw new Error(`Path is not a file: ${binaryPath}`)
-    }
-
-    // Check if executable (on Unix systems)
-    if (process.platform !== "win32") {
-      try {
-        execSync(`test -x "${binaryPath}"`, { stdio: "pipe" })
       } catch {
-        throw new Error(`Binary is not executable: ${binaryPath}`)
+        continue
       }
     }
  
-    return binaryPath
+    return null
   }
  
-  private resolveBinaryViaLocator(command: string, log?: (message: string) => void): string {
+  private resolveDevEntry(): string {
-    log?.(`Running locator command: ${command}`)
+    const entry = path.resolve(process.cwd(), "..", "server", "src", "index.ts")
-    const output = execSync(command, { stdio: "pipe", encoding: "utf-8" })
+    if (!existsSync(entry)) {
-    log?.(`Locator output: ${output.trim() || "<empty>"}`)
+      throw new Error(`Dev CLI entry not found at ${entry}. Run npm run dev:electron from the repository root after installing dependencies.`)
-    const path = this.pickFirstPath(output)
-    if (!path) {
-      throw new Error("opencode binary not found in PATH")
     }
-    return path
+    return entry
   }
  
-  private pickFirstPath(output: string): string | null {
+  private resolveProdEntry(): string {
-    const line = output
+    try {
-      .split("\n")
+      const entry = nodeRequire.resolve("@neuralnomads/codenomad/dist/bin.js")
-      .map((entry) => entry.trim())
+      if (existsSync(entry)) {
-      .find((entry) => entry.length > 0)
+        return entry
-    return line ?? null
       }
-
+    } catch {
-  private buildServeArgs(): string[] {
+      // fall through to error below
-    return ["serve", "--port", "0", "--print-logs", "--log-level", "DEBUG"]
     }
-
+    throw new Error("Unable to locate CodeNomad CLI build (dist/bin.js). Run npm run build --workspace @neuralnomads/codenomad.")
-  private buildShellServeCommand(binaryPath: string): { command: string; args: string[] } {
-    const args = this.buildServeArgs()
-      .map((arg) => JSON.stringify(arg))
-      .join(" ")
-    return buildUserShellCommand(`exec ${JSON.stringify(binaryPath)} ${args}`)
   }
 }
 
-export const processManager = new ProcessManager()
-
-app.on("before-quit", async (event) => {
-  event.preventDefault()
-  await processManager.cleanup()
-  app.exit(0)
-})

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

@@ -59,7 +59,7 @@ export function setupStorageIPC() {
       return await readConfigWithCache()
     } catch (error) {
       // Return empty config if file doesn't exist
-      return JSON.stringify({ preferences: { showThinkingBlocks: false }, recentFolders: [] }, null, 2)
+      return JSON.stringify({ preferences: { showThinkingBlocks: false, thinkingBlocksExpansion: "expanded" }, recentFolders: [] }, null, 2)
     }
   })
 

packages/electron-app/electron/preload/index.cjs

@@ -0,0 +1,17 @@
+const { contextBridge, ipcRenderer } = require("electron")
+
+const electronAPI = {
+  onCliStatus: (callback) => {
+    ipcRenderer.on("cli:status", (_, data) => callback(data))
+    return () => ipcRenderer.removeAllListeners("cli:status")
+  },
+  onCliError: (callback) => {
+    ipcRenderer.on("cli:error", (_, data) => callback(data))
+    return () => ipcRenderer.removeAllListeners("cli:error")
+  },
+  getCliStatus: () => ipcRenderer.invoke("cli:getStatus"),
+  restartCli: () => ipcRenderer.invoke("cli:restart"),
+  openDialog: (options) => ipcRenderer.invoke("dialog:open", options),
+}
+
+contextBridge.exposeInMainWorld("electronAPI", electronAPI)

packages/electron-app/electron/preload/index.ts

@@ -1,49 +0,0 @@
-import { contextBridge, ipcRenderer } from "electron"
-import type { ElectronAPI } from "../../../ui/src/types/electron-api"
-
-const electronAPI: ElectronAPI = {
-  selectFolder: () => ipcRenderer.invoke("dialog:selectFolder"),
-  createInstance: (id: string, folder: string, binaryPath?: string, environmentVariables?: Record<string, string>) =>
-    ipcRenderer.invoke("instance:create", id, folder, binaryPath, environmentVariables),
-  stopInstance: (pid: number) => ipcRenderer.invoke("instance:stop", pid),
-  onInstanceStarted: (callback) => {
-    ipcRenderer.on("instance:started", (_, data) => callback(data))
-  },
-  onInstanceError: (callback) => {
-    ipcRenderer.on("instance:error", (_, data) => callback(data))
-  },
-  onInstanceStopped: (callback) => {
-    ipcRenderer.on("instance:stopped", (_, data) => callback(data))
-  },
-  onInstanceLog: (callback) => {
-    ipcRenderer.on("instance:log", (_, data) => callback(data))
-  },
-  onNewInstance: (callback) => {
-    ipcRenderer.on("menu:newInstance", () => callback())
-  },
-  scanDirectory: (workspaceFolder: string) => ipcRenderer.invoke("fs:scanDirectory", workspaceFolder),
-  // OpenCode binary operations
-  selectOpenCodeBinary: () => ipcRenderer.invoke("dialog:selectOpenCodeBinary"),
-  validateOpenCodeBinary: (path: string) => ipcRenderer.invoke("opencode:validateBinary", path),
-  // Storage operations
-  getConfigPath: () => ipcRenderer.invoke("storage:getConfigPath"),
-  getInstancesDir: () => ipcRenderer.invoke("storage:getInstancesDir"),
-  readConfigFile: () => ipcRenderer.invoke("storage:readConfigFile"),
-  writeConfigFile: (content: string) => ipcRenderer.invoke("storage:writeConfigFile", content),
-  readInstanceFile: (filename: string) => ipcRenderer.invoke("storage:readInstanceFile", filename),
-  writeInstanceFile: (filename: string, content: string) =>
-    ipcRenderer.invoke("storage:writeInstanceFile", filename, content),
-  deleteInstanceFile: (filename: string) => ipcRenderer.invoke("storage:deleteInstanceFile", filename),
-  onConfigChanged: (callback: () => void) => {
-    ipcRenderer.on("storage:configChanged", () => callback())
-    return () => ipcRenderer.removeAllListeners("storage:configChanged")
-  },
-}
-
-contextBridge.exposeInMainWorld("electronAPI", electronAPI)
-
-declare global {
-  interface Window {
-    electronAPI: ElectronAPI
-  }
-}

packages/electron-app/package.json

@@ -1,16 +1,21 @@
 {
-  "name": "@codenomad/electron-app",
+  "name": "@neuralnomads/codenomad-electron-app",
-  "version": "0.1.2",
+  "version": "0.5.1",
   "description": "CodeNomad - AI coding assistant",
   "author": {
-    "name": "Shantur Rathore",
+    "name": "Neural Nomads",
-    "email": "codenomad@shantur.com"
+    "email": "codenomad@neuralnomads.ai"
   },
   "type": "module",
   "main": "dist/main/main.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NeuralNomadsAI/CodeNomad.git"
+  },
+  "homepage": "https://github.com/NeuralNomadsAI/CodeNomad",
   "scripts": {
     "dev": "electron-vite dev",
-    "dev:electron": "NODE_ENV=development electron .",
+    "dev:electron": "NODE_ENV=development ELECTRON_ENABLE_LOGGING=1 NODE_OPTIONS=\"--import tsx\" electron electron/main/main.ts",
     "build": "electron-vite build",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "preview": "electron-vite preview",
@@ -29,8 +34,8 @@
     "package:linux": "electron-builder --linux"
   },
   "dependencies": {
-    "@codenomad/ui": "file:../ui",
+    "@neuralnomads/codenomad": "file:../server",
-    "ignore": "7.0.5"
+    "@codenomad/ui": "file:../ui"
   },
   "devDependencies": {
     "7zip-bin": "^5.2.0",
@@ -40,6 +45,7 @@
     "electron-vite": "4.0.1",
     "png2icons": "^2.0.1",
     "pngjs": "^7.0.0",
+    "tsx": "^4.20.6",
     "typescript": "^5.3.0",
     "vite": "^5.0.0",
     "vite-plugin-solid": "^2.10.0"
@@ -55,39 +61,59 @@
       "dist/**/*",
       "package.json"
     ],
+    "extraResources": [
+      {
+        "from": "electron/resources",
+        "to": "",
+        "filter": [
+          "!icon.icns",
+          "!icon.ico"
+        ]
+      },
+      {
+        "from": "../server/dist/opencode-config",
+        "to": "opencode-config"
+      }
+    ],
     "mac": {
       "category": "public.app-category.developer-tools",
       "target": [
-        {
-          "target": "dmg",
-          "arch": ["x64", "arm64", "universal"]
-        },
         {
           "target": "zip",
-          "arch": ["x64", "arm64", "universal"]
+          "arch": [
+            "x64",
+            "arm64"
+          ]
         }
       ],
-      "artifactName": "${productName}-${version}-${os}-${arch}.${ext}",
+      "artifactName": "CodeNomad-${version}-${os}-${arch}.${ext}",
       "icon": "electron/resources/icon.icns"
     },
     "dmg": {
       "contents": [
-        { "x": 130, "y": 220 },
+        {
-        { "x": 410, "y": 220, "type": "link", "path": "/Applications" }
+          "x": 130,
+          "y": 220
+        },
+        {
+          "x": 410,
+          "y": 220,
+          "type": "link",
+          "path": "/Applications"
+        }
       ]
     },
     "win": {
       "target": [
-        {
-          "target": "nsis",
-          "arch": ["x64", "arm64"]
-        },
         {
           "target": "zip",
-          "arch": ["x64", "arm64"]
+          "arch": [
+            "x64",
+            "arm64"
+          ]
         }
       ],
-      "artifactName": "${productName}-${version}-${os}-${arch}.${ext}",
+      "artifactName": "CodeNomad-${version}-${os}-${arch}.${ext}",
       "icon": "electron/resources/icon.ico"
     },
     "nsis": {
@@ -99,23 +125,14 @@
     "linux": {
       "target": [
         {
-          "target": "AppImage",
+          "target": "zip",
-          "arch": ["x64", "arm64"]
+          "arch": [
-        },
+            "x64",
-        {
+            "arm64"
-          "target": "deb",
+          ]
-          "arch": ["x64", "arm64"]
-        },
-        {
-          "target": "rpm",
-          "arch": ["x64", "arm64"]
-        },
-        {
-          "target": "tar.gz",
-          "arch": ["x64", "arm64"]
         }
       ],
-      "artifactName": "${productName}-${version}-${os}-${arch}.${ext}",
+      "artifactName": "CodeNomad-${version}-${os}-${arch}.${ext}",
       "category": "Development",
       "icon": "electron/resources/icon.png"
     }

packages/electron-app/scripts/build.js

@@ -2,20 +2,22 @@
 
 import { spawn } from "child_process"
 import { existsSync } from "fs"
-import { join } from "path"
+import path, { join } from "path"
 import { fileURLToPath } from "url"
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url))
 const appDir = join(__dirname, "..")
+const workspaceRoot = join(appDir, "..", "..")
 
 const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm"
 const npxCmd = process.platform === "win32" ? "npx.cmd" : "npx"
 const nodeModulesPath = join(appDir, "node_modules")
+const workspaceNodeModulesPath = join(workspaceRoot, "node_modules")
 
 const platforms = {
   mac: {
-    args: ["--mac", "--x64", "--arm64", "--universal"],
+    args: ["--mac", "--x64", "--arm64"],
-    description: "macOS (Intel, Apple Silicon, Universal)",
+    description: "macOS (Intel & Apple Silicon)",
   },
   "mac-x64": {
     args: ["--mac", "--x64"],
@@ -53,12 +55,22 @@ const platforms = {
 
 function run(command, args, options = {}) {
   return new Promise((resolve, reject) => {
+    const env = { ...process.env, NODE_PATH: nodeModulesPath, ...(options.env || {}) }
+    const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path") ?? "PATH"
+
+    const binPaths = [
+      join(nodeModulesPath, ".bin"),
+      join(workspaceNodeModulesPath, ".bin"),
+    ]
+
+    env[pathKey] = `${binPaths.join(path.delimiter)}${path.delimiter}${env[pathKey] ?? ""}`
+
     const spawnOptions = {
       cwd: appDir,
       stdio: "inherit",
       shell: process.platform === "win32",
       ...options,
-      env: { ...process.env, NODE_PATH: nodeModulesPath, ...(options.env || {}) },
+      env,
     }
 
     const child = spawn(command, args, spawnOptions)
@@ -93,10 +105,16 @@ async function build(platform) {
   console.log(`\n🔨 Building for: ${config.description}\n`)
 
   try {
-    console.log("📦 Step 1/2: Building Electron app...\n")
+    console.log("📦 Step 1/3: Building CLI dependency...\n")
+    await run(npmCmd, ["run", "build", "--workspace", "@neuralnomads/codenomad"], {
+      cwd: workspaceRoot,
+      env: { NODE_PATH: workspaceNodeModulesPath },
+    })
+
+    console.log("\n📦 Step 2/3: Building Electron app...\n")
     await run(npmCmd, ["run", "build"])
 
-    console.log("\n📦 Step 2/2: Packaging binaries...\n")
+    console.log("\n📦 Step 3/3: Packaging binaries...\n")
     const distPath = join(appDir, "dist")
     if (!existsSync(distPath)) {
       throw new Error("dist/ directory not found. Build failed.")

packages/opencode-config/README.md

@@ -0,0 +1,32 @@
+# opencode-config
+
+## TLDR
+Template config + plugins injected into every OpenCode instance that CodeNomad launches. It provides a CodeNomad bridge plugin for local event exchange between the CLI server and opencode.
+
+## What it is
+A packaged config directory that CodeNomad copies into `~/.config/codenomad/opencode-config` for production builds or uses directly in dev. OpenCode autoloads any `plugin/*.ts` or `plugin/*.js` from this directory.
+
+## How it works
+- CodeNomad sets `OPENCODE_CONFIG_DIR` when spawning each opencode instance (`packages/server/src/workspaces/manager.ts`).
+- This template is synced from `packages/opencode-config` (`packages/server/src/opencode-config.ts`, `packages/server/scripts/copy-opencode-config.mjs`).
+- OpenCode autoloads plugins from `plugin/` (`packages/opencode-config/plugin/codenomad.ts`).
+- The `CodeNomadPlugin` reads `CODENOMAD_INSTANCE_ID` + `CODENOMAD_BASE_URL`, connects to `GET /workspaces/:id/plugin/events`, and posts to `POST /workspaces/:id/plugin/event` (`packages/opencode-config/plugin/lib/client.ts`).
+- The server exposes the plugin routes and maps events into the UI SSE pipeline (`packages/server/src/server/routes/plugin.ts`, `packages/server/src/plugins/handlers.ts`).
+
+## Expectations
+- Local-only bridge (no auth/token yet).
+- Plugin must fail startup if it cannot connect after 3 retries.
+- Keep plugin entrypoints thin; put shared logic under `plugin/lib/` to avoid autoloaded helpers.
+- Keep event shapes small and explicit; use `type` + `properties` only.
+
+## Ideas
+- Add feature modules under `plugin/lib/features/` (tool lifecycle, permission prompts, custom commands).
+- Expand `/workspaces/:id/plugin/*` with dedicated endpoints as needed.
+- Promote stable event shapes and version tags once the protocol settles.
+
+## Pointers
+- Plugin entry: `packages/opencode-config/plugin/codenomad.ts`
+- Plugin client: `packages/opencode-config/plugin/lib/client.ts`
+- Plugin server routes: `packages/server/src/server/routes/plugin.ts`
+- Plugin event handling: `packages/server/src/plugins/handlers.ts`
+- Workspace env injection: `packages/server/src/workspaces/manager.ts`

packages/opencode-config/opencode.jsonc

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://opencode.ai/config.json"
+}

packages/opencode-config/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@codenomad/opencode-config",
+  "version": "0.5.0",
+  "private": true,
+  "dependencies": {
+    "@opencode-ai/plugin": "1.1.1"
+  }
+}

packages/opencode-config/plugin/codenomad.ts

@@ -0,0 +1,32 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+import { createCodeNomadClient, getCodeNomadConfig } from "./lib/client"
+import { createBackgroundProcessTools } from "./lib/background-process"
+
+export async function CodeNomadPlugin(input: PluginInput) {
+  const config = getCodeNomadConfig()
+  const client = createCodeNomadClient(config)
+  const backgroundProcessTools = createBackgroundProcessTools(config, { baseDir: input.directory })
+
+  await client.startEvents((event) => {
+    if (event.type === "codenomad.ping") {
+      void client.postEvent({
+        type: "codenomad.pong",
+        properties: {
+          ts: Date.now(),
+          pingTs: (event.properties as any)?.ts,
+        },
+      }).catch(() => {})
+    }
+  })
+
+  return {
+    tool: {
+      ...backgroundProcessTools,
+    },
+    async event(input: { event: any }) {
+      const opencodeEvent = input?.event
+      if (!opencodeEvent || typeof opencodeEvent !== "object") return
+
+    },
+  }
+}

packages/opencode-config/plugin/lib/background-process.ts

@@ -0,0 +1,309 @@
+import path from "path"
+import { tool } from "@opencode-ai/plugin/tool"
+
+type BackgroundProcess = {
+  id: string
+  title: string
+  command: string
+  status: "running" | "stopped" | "error"
+  startedAt: string
+  stoppedAt?: string
+  exitCode?: number
+  outputSizeBytes?: number
+}
+
+type CodeNomadConfig = {
+  instanceId: string
+  baseUrl: string
+}
+
+type BackgroundProcessOptions = {
+  baseDir: string
+}
+
+type ParsedCommand = {
+  head: string
+  args: string[]
+}
+
+export function createBackgroundProcessTools(config: CodeNomadConfig, options: BackgroundProcessOptions) {
+  const request = async <T>(path: string, init?: RequestInit): Promise<T> => {
+
+    const base = config.baseUrl.replace(/\/+$/, "")
+    const url = `${base}/workspaces/${config.instanceId}/plugin/background-processes${path}`
+    const headers = normalizeHeaders(init?.headers)
+    if (init?.body !== undefined) {
+      headers["Content-Type"] = "application/json"
+    }
+
+    const response = await fetch(url, {
+      ...init,
+      headers,
+    })
+
+    if (!response.ok) {
+      const message = await response.text()
+      throw new Error(message || `Request failed with ${response.status}`)
+    }
+
+    if (response.status === 204) {
+      return undefined as T
+    }
+
+    return (await response.json()) as T
+  }
+
+  return {
+    run_background_process: tool({
+      description:
+        "Run a long-lived background process (dev servers, DBs, watchers) so it keeps running while you do other tasks. Use it for running processes that timeout otherwise or produce a lot of output.",
+      args: {
+        title: tool.schema.string().describe("Short label for the process (e.g. Dev server, DB server)"),
+        command: tool.schema.string().describe("Shell command to run in the workspace"),
+      },
+      async execute(args) {
+        assertCommandWithinBase(args.command, options.baseDir)
+        const process = await request<BackgroundProcess>("", {
+          method: "POST",
+          body: JSON.stringify({ title: args.title, command: args.command }),
+        })
+
+        return `Started background process ${process.id} (${process.title})\nStatus: ${process.status}\nCommand: ${process.command}`
+      },
+    }),
+    list_background_processes: tool({
+      description: "List background processes running for this workspace.",
+      args: {},
+      async execute() {
+        const response = await request<{ processes: BackgroundProcess[] }>("")
+        if (response.processes.length === 0) {
+          return "No background processes running."
+        }
+
+        return response.processes
+          .map((process) => {
+            const status = process.status === "running" ? "running" : process.status
+            const exit = process.exitCode !== undefined ? ` (exit ${process.exitCode})` : ""
+            const size =
+              typeof process.outputSizeBytes === "number" ? ` | ${Math.round(process.outputSizeBytes / 1024)}KB` : ""
+            return `- ${process.id} | ${process.title} | ${status}${exit}${size}\n  ${process.command}`
+          })
+          .join("\n")
+      },
+    }),
+    read_background_process_output: tool({
+      description: "Read output from a background process. Use full, grep, head, or tail.",
+      args: {
+        id: tool.schema.string().describe("Background process ID"),
+        method: tool.schema
+          .enum(["full", "grep", "head", "tail"])
+          .default("full")
+          .describe("Method to read output"),
+        pattern: tool.schema.string().optional().describe("Pattern for grep method"),
+        lines: tool.schema.number().optional().describe("Number of lines for head/tail methods"),
+      },
+      async execute(args) {
+        if (args.method === "grep" && !args.pattern) {
+          return "Pattern is required for grep method."
+        }
+
+        const params = new URLSearchParams({ method: args.method })
+        if (args.pattern) {
+          params.set("pattern", args.pattern)
+        }
+        if (args.lines) {
+          params.set("lines", String(args.lines))
+        }
+
+        const response = await request<{ id: string; content: string; truncated: boolean; sizeBytes: number }>(
+          `/${args.id}/output?${params.toString()}`,
+        )
+
+        const header = response.truncated
+          ? `Output (truncated, ${Math.round(response.sizeBytes / 1024)}KB):`
+          : `Output (${Math.round(response.sizeBytes / 1024)}KB):`
+
+        return `${header}\n\n${response.content}`
+      },
+    }),
+    stop_background_process: tool({
+      description: "Stop a background process (SIGTERM) but keep its output and entry.",
+      args: {
+        id: tool.schema.string().describe("Background process ID"),
+      },
+      async execute(args) {
+        const process = await request<BackgroundProcess>(`/${args.id}/stop`, { method: "POST" })
+        return `Stopped background process ${process.id} (${process.title}). Status: ${process.status}`
+      },
+    }),
+    terminate_background_process: tool({
+      description: "Terminate a background process and delete its output + entry.",
+      args: {
+        id: tool.schema.string().describe("Background process ID"),
+      },
+      async execute(args) {
+        await request<void>(`/${args.id}/terminate`, { method: "POST" })
+        return `Terminated background process ${args.id} and removed its output.`
+      },
+    }),
+  }
+}
+
+const FILE_COMMANDS = new Set(["cd", "rm", "cp", "mv", "mkdir", "touch", "chmod", "chown"])
+const EXPANSION_CHARS = /[~*$?\[\]`$]/
+
+function assertCommandWithinBase(command: string, baseDir: string) {
+  const normalizedBase = path.resolve(baseDir)
+  const commands = splitCommands(command)
+
+  for (const item of commands) {
+    if (!FILE_COMMANDS.has(item.head)) {
+      continue
+    }
+
+    for (const arg of item.args) {
+      if (!arg) continue
+      if (arg.startsWith("-") || (item.head === "chmod" && arg.startsWith("+"))) continue
+
+      const literalArg = unquote(arg)
+      if (EXPANSION_CHARS.test(literalArg)) {
+        throw new Error(`Background process commands may only reference paths within ${normalizedBase}.`)
+      }
+
+      const resolved = path.isAbsolute(literalArg) ? path.normalize(literalArg) : path.resolve(normalizedBase, literalArg)
+      if (!isWithinBase(normalizedBase, resolved)) {
+        throw new Error(`Background process commands may only reference paths within ${normalizedBase}.`)
+      }
+    }
+  }
+}
+
+function splitCommands(command: string): ParsedCommand[] {
+  const tokens = tokenize(command)
+  const commands: ParsedCommand[] = []
+  let current: string[] = []
+
+  for (const token of tokens) {
+    if (isSeparator(token)) {
+      if (current.length > 0) {
+        commands.push({ head: current[0], args: current.slice(1) })
+        current = []
+      }
+      continue
+    }
+    current.push(token)
+  }
+
+  if (current.length > 0) {
+    commands.push({ head: current[0], args: current.slice(1) })
+  }
+
+  return commands
+}
+
+function tokenize(input: string): string[] {
+  const tokens: string[] = []
+  let current = ""
+  let quote: "'" | '"' | null = null
+  let escape = false
+
+  const flush = () => {
+    if (current.length > 0) {
+      tokens.push(current)
+      current = ""
+    }
+  }
+
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index]
+
+    if (escape) {
+      current += char
+      escape = false
+      continue
+    }
+
+    if (char === "\\" && quote !== "'") {
+      escape = true
+      continue
+    }
+
+    if (quote) {
+      current += char
+      if (char === quote) {
+        quote = null
+      }
+      continue
+    }
+
+    if (char === "'" || char === '"') {
+      quote = char
+      current += char
+      continue
+    }
+
+    if (char === " " || char === "\n" || char === "\t") {
+      flush()
+      continue
+    }
+
+    if (char === "|" || char === "&" || char === ";") {
+      flush()
+      const next = input[index + 1]
+      if ((char === "|" || char === "&") && next === char) {
+        tokens.push(char + next)
+        index += 1
+      } else {
+        tokens.push(char)
+      }
+      continue
+    }
+
+    current += char
+  }
+
+  flush()
+  return tokens
+}
+
+function isSeparator(token: string) {
+  return token === "|" || token === "||" || token === "&&" || token === ";" || token === "&"
+}
+
+function unquote(value: string) {
+  if (value.length >= 2) {
+    const first = value[0]
+    const last = value[value.length - 1]
+    if ((first === "'" && last === "'") || (first === '"' && last === '"')) {
+      return value.slice(1, -1)
+    }
+  }
+  return value
+}
+
+function isWithinBase(baseDir: string, target: string) {
+  const relative = path.relative(baseDir, target)
+  if (!relative) return true
+  return !relative.startsWith("..") && !path.isAbsolute(relative)
+}
+
+function normalizeHeaders(headers: HeadersInit | undefined): Record<string, string> {
+  const output: Record<string, string> = {}
+  if (!headers) return output
+
+  if (headers instanceof Headers) {
+    headers.forEach((value, key) => {
+      output[key] = value
+    })
+    return output
+  }
+
+  if (Array.isArray(headers)) {
+    for (const [key, value] of headers) {
+      output[key] = value
+    }
+    return output
+  }
+
+  return { ...headers }
+}

packages/opencode-config/plugin/lib/client.ts

@@ -0,0 +1,165 @@
+export type PluginEvent = {
+  type: string
+  properties?: Record<string, unknown>
+}
+
+export type CodeNomadConfig = {
+  instanceId: string
+  baseUrl: string
+}
+
+export function getCodeNomadConfig(): CodeNomadConfig {
+  return {
+    instanceId: requireEnv("CODENOMAD_INSTANCE_ID"),
+    baseUrl: requireEnv("CODENOMAD_BASE_URL"),
+  }
+}
+
+export function createCodeNomadClient(config: CodeNomadConfig) {
+  return {
+    postEvent: (event: PluginEvent) => postPluginEvent(config.baseUrl, config.instanceId, event),
+    startEvents: (onEvent: (event: PluginEvent) => void) => startPluginEvents(config.baseUrl, config.instanceId, onEvent),
+  }
+}
+
+function requireEnv(key: string): string {
+  const value = process.env[key]
+  if (!value || !value.trim()) {
+    throw new Error(`[CodeNomadPlugin] Missing required env var ${key}`)
+  }
+  return value
+}
+
+function delay(ms: number) {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms))
+}
+
+async function postPluginEvent(baseUrl: string, instanceId: string, event: PluginEvent) {
+  const url = `${baseUrl.replace(/\/+$/, "")}/workspaces/${instanceId}/plugin/event`
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(event),
+  })
+
+  if (!response.ok) {
+    throw new Error(`[CodeNomadPlugin] POST ${url} failed (${response.status})`)
+  }
+}
+
+async function startPluginEvents(baseUrl: string, instanceId: string, onEvent: (event: PluginEvent) => void) {
+  const url = `${baseUrl.replace(/\/+$/, "")}/workspaces/${instanceId}/plugin/events`
+
+  // Fail plugin startup if we cannot establish the initial connection.
+  const initialBody = await connectWithRetries(url, 3)
+
+  // After startup, keep reconnecting; throw after 3 consecutive failures.
+  void consumeWithReconnect(url, onEvent, initialBody)
+}
+
+async function connectWithRetries(url: string, maxAttempts: number) {
+  let lastError: unknown
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const response = await fetch(url, { headers: { Accept: "text/event-stream" } })
+      if (!response.ok || !response.body) {
+        throw new Error(`[CodeNomadPlugin] SSE unavailable (${response.status})`)
+      }
+      return response.body
+    } catch (error) {
+      lastError = error
+      await delay(500 * attempt)
+    }
+  }
+
+  const reason = lastError instanceof Error ? lastError.message : String(lastError)
+  throw new Error(`[CodeNomadPlugin] Failed to connect to CodeNomad after ${maxAttempts} retries: ${reason}`)
+}
+
+async function consumeWithReconnect(
+  url: string,
+  onEvent: (event: PluginEvent) => void,
+  initialBody: ReadableStream<Uint8Array>,
+) {
+  let consecutiveFailures = 0
+  let body: ReadableStream<Uint8Array> | null = initialBody
+
+  while (true) {
+    try {
+      if (!body) {
+        body = await connectWithRetries(url, 3)
+      }
+
+      await consumeSseBody(body, onEvent)
+      body = null
+      consecutiveFailures = 0
+    } catch (error) {
+      body = null
+      consecutiveFailures += 1
+      if (consecutiveFailures >= 3) {
+        const reason = error instanceof Error ? error.message : String(error)
+        throw new Error(`[CodeNomadPlugin] Plugin event stream failed after 3 retries: ${reason}`)
+      }
+      await delay(500 * consecutiveFailures)
+    }
+  }
+}
+
+async function consumeSseBody(body: ReadableStream<Uint8Array>, onEvent: (event: PluginEvent) => void) {
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ""
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done || !value) {
+      break
+    }
+
+    buffer += decoder.decode(value, { stream: true })
+
+    let separatorIndex = buffer.indexOf("\n\n")
+    while (separatorIndex >= 0) {
+      const chunk = buffer.slice(0, separatorIndex)
+      buffer = buffer.slice(separatorIndex + 2)
+      separatorIndex = buffer.indexOf("\n\n")
+
+      const event = parseSseChunk(chunk)
+      if (event) {
+        onEvent(event)
+      }
+    }
+  }
+
+  throw new Error("SSE stream ended")
+}
+
+function parseSseChunk(chunk: string): PluginEvent | null {
+  const lines = chunk.split(/\r?\n/)
+  const dataLines: string[] = []
+
+  for (const line of lines) {
+    if (line.startsWith(":")) continue
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice(5).trimStart())
+    }
+  }
+
+  if (dataLines.length === 0) return null
+
+  const payload = dataLines.join("\n").trim()
+  if (!payload) return null
+
+  try {
+    const parsed = JSON.parse(payload)
+    if (!parsed || typeof parsed !== "object" || typeof (parsed as any).type !== "string") {
+      return null
+    }
+    return parsed as PluginEvent
+  } catch {
+    return null
+  }
+}

packages/server/README.md

@@ -0,0 +1,58 @@
+# CodeNomad Server
+
+**CodeNomad Server** is the high-performance engine behind the CodeNomad cockpit. It transforms your machine into a robust development host, managing the lifecycle of multiple OpenCode instances and providing the low-latency data streams that long-haul builders demand. It bridges your local filesystem with the UI, ensuring that whether you are on localhost or a remote tunnel, you have the speed, clarity, and control of a native workspace.
+
+## Features & Capabilities
+
+### 🌍 Deployment Freedom
+- **Remote Access**: Host CodeNomad on a powerful workstation and access it from your lightweight laptop.
+- **Code Anywhere**: Tunnel in via VPN or SSH to code securely from coffee shops or while traveling.
+- **Multi-Device**: The responsive web client works on tablets and iPads, turning any screen into a dev terminal.
+- **Always-On**: Run as a background service so your sessions are always ready when you connect.
+
+### ⚡️ Workspace Power
+- **Multi-Instance**: Juggle multiple OpenCode sessions side-by-side with per-instance tabs.
+- **Long-Context Native**: Scroll through massive transcripts without hitches.
+- **Deep Task Awareness**: Monitor background tasks and child sessions without losing your flow.
+- **Command Palette**: A single, global palette to jump tabs, launch tools, and fire shortcuts.
+
+## Prerequisites
+- **OpenCode**: `opencode` must be installed and configured on your system.
+- Node.js 18+ and npm (for running or building from source).
+- A workspace folder on disk you want to serve.
+- Optional: a Chromium-based browser if you want `--launch` to open the UI automatically.
+
+## Usage
+
+### Run via npx (Recommended)
+You can run CodeNomad directly without installing it:
+
+```sh
+npx @neuralnomads/codenomad --launch
+```
+
+### Install Globally
+Or install it globally to use the `codenomad` command:
+
+```sh
+npm install -g @neuralnomads/codenomad
+codenomad --launch
+```
+
+### Common Flags
+You can configure the server using flags or environment variables:
+
+| Flag | Env Variable | Description |
+|------|--------------|-------------|
+| `--port <number>` | `CLI_PORT` | HTTP port (default 9898) |
+| `--host <addr>` | `CLI_HOST` | Interface to bind (default 127.0.0.1) |
+| `--workspace-root <path>` | `CLI_WORKSPACE_ROOT` | Default root for new workspaces |
+| `--unrestricted-root` | `CLI_UNRESTRICTED_ROOT` | Allow full-filesystem browsing |
+| `--config <path>` | `CLI_CONFIG` | Config file location |
+| `--launch` | `CLI_LAUNCH` | Open the UI in a Chromium-based browser |
+| `--log-level <level>` | `CLI_LOG_LEVEL` | Logging level (trace, debug, info, warn, error) |
+
+### Data Storage
+- **Config**: `~/.config/codenomad/config.json`
+- **Instance Data**: `~/.config/codenomad/instances` (chat history, etc.)
+

packages/server/package-lock.json

@@ -1,12 +1,12 @@
 {
-  "name": "@codenomad/cli",
+  "name": "@neuralnomads/codenomad",
-  "version": "0.1.0",
+  "version": "0.5.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "@codenomad/cli",
+      "name": "@neuralnomads/codenomad",
-      "version": "0.1.0",
+      "version": "0.5.1",
       "dependencies": {
         "@fastify/cors": "^8.5.0",
         "commander": "^12.1.0",

packages/server/package.json

@@ -1,17 +1,26 @@
 {
-  "name": "@codenomad/cli",
+  "name": "@neuralnomads/codenomad",
-  "version": "0.1.0",
+  "version": "0.5.1",
-  "description": "CodeNomad CLI server for HTTP/SSE control plane",
+  "description": "CodeNomad Server",
+  "author": {
+    "name": "Neural Nomads",
+    "email": "codenomad@neuralnomads.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NeuralNomadsAI/CodeNomad.git"
+  },
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "codenomad-cli": "dist/bin.js"
+    "codenomad": "dist/bin.js"
   },
   "scripts": {
-    "build": "npm run build:ui && npm run prepare-ui && tsc -p tsconfig.json",
+    "build": "npm run build:ui && npm run prepare-ui && tsc -p tsconfig.json && npm run prepare-config",
     "build:ui": "npm run build --prefix ../ui",
     "prepare-ui": "node ./scripts/copy-ui-dist.mjs",
-    "dev": "cross-env CLI_UI_DEV_SERVER=http://localhost:3000 tsx src/index.ts",
+    "prepare-config": "node ./scripts/copy-opencode-config.mjs",
+    "dev": "cross-env CODENOMAD_DEV=1 CLI_UI_DEV_SERVER=http://localhost:3000 tsx src/index.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
@@ -20,6 +29,7 @@
     "@fastify/static": "^7.0.4",
     "commander": "^12.1.0",
     "fastify": "^4.28.1",
+    "fuzzysort": "^2.0.4",
     "pino": "^9.4.0",
     "undici": "^6.19.8",
     "zod": "^3.23.8"

packages/server/scripts/copy-opencode-config.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { spawnSync } from "child_process"
+import { cpSync, existsSync, mkdirSync, rmSync } from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const cliRoot = path.resolve(__dirname, "..")
+const sourceDir = path.resolve(cliRoot, "../opencode-config")
+const targetDir = path.resolve(cliRoot, "dist/opencode-config")
+const nodeModulesDir = path.resolve(sourceDir, "node_modules")
+const selfLinkDir = path.resolve(nodeModulesDir, "@codenomad", "opencode-config")
+const npmExecPath = process.env.npm_execpath
+const npmNodeExecPath = process.env.npm_node_execpath
+
+if (!existsSync(sourceDir)) {
+  console.error(`[copy-opencode-config] Missing source directory at ${sourceDir}`)
+  process.exit(1)
+}
+
+if (!existsSync(nodeModulesDir)) {
+  console.log(`[copy-opencode-config] Installing opencode-config dependencies in ${sourceDir}`)
+
+  const npmArgs = [
+    "install",
+    "--prefix",
+    sourceDir,
+    "--omit=dev",
+    "--ignore-scripts",
+    "--fund=false",
+    "--audit=false",
+    "--package-lock=false",
+    "--workspaces=false",
+  ]
+
+  const env = { ...process.env, npm_config_workspaces: "false" }
+
+  const npmCli = npmExecPath && npmNodeExecPath ? [npmNodeExecPath, [npmExecPath, ...npmArgs]] : null
+  const result = npmCli
+    ? spawnSync(npmCli[0], npmCli[1], { cwd: sourceDir, stdio: "inherit", env })
+    : spawnSync("npm", npmArgs, { cwd: sourceDir, stdio: "inherit", env, shell: process.platform === "win32" })
+
+  if (result.status !== 0) {
+    if (result.error) {
+      console.error("[copy-opencode-config] npm install failed to start", result.error)
+    }
+    console.error("[copy-opencode-config] Failed to install opencode-config dependencies")
+    process.exit(result.status ?? 1)
+  }
+}
+
+// npm can create a self-referential link for scoped packages on Windows.
+// That link causes recursive copies (ELOOP) during bundling.
+rmSync(selfLinkDir, { recursive: true, force: true })
+
+rmSync(targetDir, { recursive: true, force: true })
+mkdirSync(path.dirname(targetDir), { recursive: true })
+cpSync(sourceDir, targetDir, { recursive: true })
+
+console.log(`[copy-opencode-config] Copied ${sourceDir} -> ${targetDir}`)

packages/server/src/api-types.ts

@@ -1,4 +1,5 @@
 import type {
+  AgentModelSelection,
   AgentModelSelections,
   ConfigFile,
   ModelPreference,
@@ -103,8 +104,19 @@ export interface WorkspaceFileResponse {
   contents: string
 }
 
+export type WorkspaceFileSearchResponse = FileSystemEntry[]
+
 export interface InstanceData {
   messageHistory: string[]
+  agentModelSelections: AgentModelSelection
+}
+
+export type InstanceStreamStatus = "connecting" | "connected" | "error" | "disconnected"
+
+export interface InstanceStreamEvent {
+  type: string
+  properties?: Record<string, unknown>
+  [key: string]: unknown
 }
 
 export interface BinaryRecord {
@@ -112,6 +124,7 @@ export interface BinaryRecord {
   path: string
   label: string
   version?: string
+
   /** Indicates that this binary will be picked when workspaces omit an explicit choice. */
   isDefault: boolean
   lastValidatedAt?: string
@@ -151,6 +164,10 @@ export type WorkspaceEventType =
   | "workspace.log"
   | "config.appChanged"
   | "config.binariesChanged"
+  | "instance.dataChanged"
+  | "instance.event"
+  | "instance.eventStatus"
+  | "app.releaseAvailable"
 
 export type WorkspaceEventPayload =
   | { type: "workspace.created"; workspace: WorkspaceDescriptor }
@@ -160,16 +177,73 @@ export type WorkspaceEventPayload =
   | { type: "workspace.log"; entry: WorkspaceLogEntry }
   | { type: "config.appChanged"; config: AppConfig }
   | { type: "config.binariesChanged"; binaries: BinaryRecord[] }
+  | { type: "instance.dataChanged"; instanceId: string; data: InstanceData }
+  | { type: "instance.event"; instanceId: string; event: InstanceStreamEvent }
+  | { type: "instance.eventStatus"; instanceId: string; status: InstanceStreamStatus; reason?: string }
+  | { type: "app.releaseAvailable"; release: LatestReleaseInfo }
+
+export interface NetworkAddress {
+  ip: string
+  family: "ipv4" | "ipv6"
+  scope: "external" | "internal" | "loopback"
+  url: string
+}
+
+export interface LatestReleaseInfo {
+  version: string
+  tag: string
+  url: string
+  channel: "stable" | "dev"
+  publishedAt?: string
+  notes?: string
+}
 
 export interface ServerMeta {
   /** Base URL clients should target for REST calls (useful for Electron embedding). */
   httpBaseUrl: string
   /** SSE endpoint advertised to clients (`/api/events` by default). */
   eventsUrl: string
+  /** Host the server is bound to (e.g., 127.0.0.1 or 0.0.0.0). */
+  host: string
+  /** Listening mode derived from host binding. */
+  listeningMode: "local" | "all"
+  /** Actual port in use after binding. */
+  port: number
   /** Display label for the host (e.g., hostname or friendly name). */
   hostLabel: string
   /** Absolute path of the filesystem root exposed to clients. */
   workspaceRoot: string
+  /** Reachable addresses for this server, external first. */
+  addresses: NetworkAddress[]
+  /** Optional metadata about the most recent public release. */
+  latestRelease?: LatestReleaseInfo
+}
+
+export type BackgroundProcessStatus = "running" | "stopped" | "error"
+
+export interface BackgroundProcess {
+  id: string
+  workspaceId: string
+  title: string
+  command: string
+  cwd: string
+  status: BackgroundProcessStatus
+  pid?: number
+  startedAt: string
+  stoppedAt?: string
+  exitCode?: number
+  outputSizeBytes?: number
+}
+
+export interface BackgroundProcessListResponse {
+  processes: BackgroundProcess[]
+}
+
+export interface BackgroundProcessOutputResponse {
+  id: string
+  content: string
+  truncated: boolean
+  sizeBytes: number
 }
 
 export type {

packages/server/src/background-processes/manager.ts

@@ -0,0 +1,438 @@
+import { spawn, type ChildProcess } from "child_process"
+import { createWriteStream, existsSync, promises as fs } from "fs"
+import path from "path"
+import { randomBytes } from "crypto"
+import type { EventBus } from "../events/bus"
+import type { WorkspaceManager } from "../workspaces/manager"
+import type { Logger } from "../logger"
+import type { BackgroundProcess, BackgroundProcessStatus } from "../api-types"
+
+const ROOT_DIR = ".codenomad/background_processes"
+const INDEX_FILE = "index.json"
+const OUTPUT_FILE = "output.txt"
+const STOP_TIMEOUT_MS = 2000
+const MAX_OUTPUT_BYTES = 20 * 1024
+const OUTPUT_PUBLISH_INTERVAL_MS = 1000
+
+interface ManagerDeps {
+  workspaceManager: WorkspaceManager
+  eventBus: EventBus
+  logger: Logger
+}
+
+interface RunningProcess {
+  child: ChildProcess
+  outputPath: string
+  exitPromise: Promise<void>
+  workspaceId: string
+}
+
+export class BackgroundProcessManager {
+  private readonly running = new Map<string, RunningProcess>()
+
+  constructor(private readonly deps: ManagerDeps) {
+    this.deps.eventBus.on("workspace.stopped", (event) => this.cleanupWorkspace(event.workspaceId))
+    this.deps.eventBus.on("workspace.error", (event) => this.cleanupWorkspace(event.workspace.id))
+  }
+
+  async list(workspaceId: string): Promise<BackgroundProcess[]> {
+    const records = await this.readIndex(workspaceId)
+    const enriched = await Promise.all(
+      records.map(async (record) => ({
+        ...record,
+        outputSizeBytes: await this.getOutputSize(workspaceId, record.id),
+      })),
+    )
+    return enriched
+  }
+
+  async start(workspaceId: string, title: string, command: string): Promise<BackgroundProcess> {
+    const workspace = this.deps.workspaceManager.get(workspaceId)
+    if (!workspace) {
+      throw new Error("Workspace not found")
+    }
+
+    const id = this.generateId()
+    const processDir = await this.ensureProcessDir(workspaceId, id)
+    const outputPath = path.join(processDir, OUTPUT_FILE)
+
+    const outputStream = createWriteStream(outputPath, { flags: "a" })
+
+    const child = spawn("bash", ["-c", command], {
+      cwd: workspace.path,
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+
+    const record: BackgroundProcess = {
+      id,
+      workspaceId,
+      title,
+      command,
+      cwd: workspace.path,
+      status: "running",
+      pid: child.pid,
+      startedAt: new Date().toISOString(),
+      outputSizeBytes: 0,
+    }
+
+    const exitPromise = new Promise<void>((resolve) => {
+      child.on("close", async (code) => {
+        await new Promise<void>((resolve) => outputStream.end(resolve))
+        this.running.delete(id)
+
+        record.status = this.statusFromExit(code)
+        record.exitCode = code === null ? undefined : code
+        record.stoppedAt = new Date().toISOString()
+
+        await this.upsertIndex(workspaceId, record)
+        record.outputSizeBytes = await this.getOutputSize(workspaceId, record.id)
+        this.publishUpdate(workspaceId, record)
+        resolve()
+      })
+    })
+
+    this.running.set(id, { child, outputPath, exitPromise, workspaceId })
+
+    let lastPublishAt = 0
+    const maybePublishSize = () => {
+      const now = Date.now()
+      if (now - lastPublishAt < OUTPUT_PUBLISH_INTERVAL_MS) {
+        return
+      }
+      lastPublishAt = now
+      this.publishUpdate(workspaceId, record)
+    }
+
+    child.stdout?.on("data", (data) => {
+      outputStream.write(data)
+      record.outputSizeBytes = (record.outputSizeBytes ?? 0) + data.length
+      maybePublishSize()
+    })
+    child.stderr?.on("data", (data) => {
+      outputStream.write(data)
+      record.outputSizeBytes = (record.outputSizeBytes ?? 0) + data.length
+      maybePublishSize()
+    })
+
+    await this.upsertIndex(workspaceId, record)
+    record.outputSizeBytes = await this.getOutputSize(workspaceId, record.id)
+    this.publishUpdate(workspaceId, record)
+    return record
+  }
+
+  async stop(workspaceId: string, processId: string): Promise<BackgroundProcess | null> {
+    const record = await this.findProcess(workspaceId, processId)
+    if (!record) {
+      return null
+    }
+
+    const running = this.running.get(processId)
+    if (running?.child && !running.child.killed) {
+      running.child.kill("SIGTERM")
+      await this.waitForExit(running)
+    }
+
+    if (record.status === "running") {
+      record.status = "stopped"
+      record.stoppedAt = new Date().toISOString()
+      await this.upsertIndex(workspaceId, record)
+      record.outputSizeBytes = await this.getOutputSize(workspaceId, record.id)
+      this.publishUpdate(workspaceId, record)
+    }
+
+    return record
+  }
+
+  async terminate(workspaceId: string, processId: string): Promise<void> {
+    const record = await this.findProcess(workspaceId, processId)
+    if (!record) return
+
+    const running = this.running.get(processId)
+    if (running?.child && !running.child.killed) {
+      running.child.kill("SIGTERM")
+      await this.waitForExit(running)
+    }
+
+    await this.removeFromIndex(workspaceId, processId)
+    await this.removeProcessDir(workspaceId, processId)
+
+    this.deps.eventBus.publish({
+      type: "instance.event",
+      instanceId: workspaceId,
+      event: { type: "background.process.removed", properties: { processId } },
+    })
+  }
+
+  async readOutput(
+    workspaceId: string,
+    processId: string,
+    options: { method?: "full" | "tail" | "head" | "grep"; pattern?: string; lines?: number; maxBytes?: number },
+  ) {
+    const outputPath = this.getOutputPath(workspaceId, processId)
+    if (!existsSync(outputPath)) {
+      return { id: processId, content: "", truncated: false, sizeBytes: 0 }
+    }
+
+    const stats = await fs.stat(outputPath)
+    const sizeBytes = stats.size
+    const method = options.method ?? "full"
+    const lineCount = options.lines ?? 10
+
+    const raw = await this.readOutputBytes(outputPath, sizeBytes, options.maxBytes)
+    let content = raw
+
+    switch (method) {
+      case "head":
+        content = this.headLines(raw, lineCount)
+        break
+      case "tail":
+        content = this.tailLines(raw, lineCount)
+        break
+      case "grep":
+        if (!options.pattern) {
+          throw new Error("Pattern is required for grep output")
+        }
+        content = this.grepLines(raw, options.pattern)
+        break
+      default:
+        content = raw
+    }
+
+    const effectiveMaxBytes = options.maxBytes
+    return {
+      id: processId,
+      content,
+      truncated: effectiveMaxBytes !== undefined && sizeBytes > effectiveMaxBytes,
+      sizeBytes,
+    }
+  }
+
+  async streamOutput(workspaceId: string, processId: string, reply: any) {
+    const outputPath = this.getOutputPath(workspaceId, processId)
+    if (!existsSync(outputPath)) {
+      reply.code(404).send({ error: "Output not found" })
+      return
+    }
+
+    reply.raw.setHeader("Content-Type", "text/event-stream")
+    reply.raw.setHeader("Cache-Control", "no-cache")
+    reply.raw.setHeader("Connection", "keep-alive")
+    reply.raw.flushHeaders?.()
+    reply.hijack()
+
+    const file = await fs.open(outputPath, "r")
+    let position = (await file.stat()).size
+
+    const tick = async () => {
+      const stats = await file.stat()
+      if (stats.size <= position) return
+
+      const length = stats.size - position
+      const buffer = Buffer.alloc(length)
+      await file.read(buffer, 0, length, position)
+      position = stats.size
+
+      const content = buffer.toString("utf-8")
+      reply.raw.write(`data: ${JSON.stringify({ type: "chunk", content })}\n\n`)
+    }
+
+    const interval = setInterval(() => {
+      tick().catch((error) => {
+        this.deps.logger.warn({ err: error }, "Failed to stream background process output")
+      })
+    }, 1000)
+
+    const close = () => {
+      clearInterval(interval)
+      file.close().catch(() => undefined)
+      reply.raw.end?.()
+    }
+
+    reply.raw.on("close", close)
+    reply.raw.on("error", close)
+  }
+
+  private async cleanupWorkspace(workspaceId: string) {
+    for (const [, running] of this.running.entries()) {
+      if (running.workspaceId !== workspaceId) continue
+      running.child.kill("SIGTERM")
+      await this.waitForExit(running)
+    }
+    await this.removeWorkspaceDir(workspaceId)
+  }
+
+  private async waitForExit(running: RunningProcess) {
+    let resolved = false
+    const timeout = setTimeout(() => {
+      if (!resolved) {
+        running.child.kill("SIGKILL")
+      }
+    }, STOP_TIMEOUT_MS)
+
+    await running.exitPromise.finally(() => {
+      resolved = true
+      clearTimeout(timeout)
+    })
+  }
+
+  private statusFromExit(code: number | null): BackgroundProcessStatus {
+    if (code === null) return "stopped"
+    if (code === 0) return "stopped"
+    return "error"
+  }
+
+  private async readOutputBytes(outputPath: string, sizeBytes: number, maxBytes?: number): Promise<string> {
+    if (maxBytes === undefined || sizeBytes <= maxBytes) {
+      return await fs.readFile(outputPath, "utf-8")
+    }
+
+    const start = Math.max(0, sizeBytes - maxBytes)
+    const file = await fs.open(outputPath, "r")
+    const buffer = Buffer.alloc(sizeBytes - start)
+    await file.read(buffer, 0, buffer.length, start)
+    await file.close()
+    return buffer.toString("utf-8")
+  }
+
+  private headLines(input: string, lines: number): string {
+    const parts = input.split(/\r?\n/)
+    return parts.slice(0, Math.max(0, lines)).join("\n")
+  }
+
+  private tailLines(input: string, lines: number): string {
+    const parts = input.split(/\r?\n/)
+    return parts.slice(Math.max(0, parts.length - lines)).join("\n")
+  }
+
+  private grepLines(input: string, pattern: string): string {
+    let matcher: RegExp
+    try {
+      matcher = new RegExp(pattern)
+    } catch {
+      throw new Error("Invalid grep pattern")
+    }
+    return input
+      .split(/\r?\n/)
+      .filter((line) => matcher.test(line))
+      .join("\n")
+  }
+
+  private async ensureProcessDir(workspaceId: string, processId: string) {
+    const root = await this.ensureWorkspaceDir(workspaceId)
+    const processDir = path.join(root, processId)
+    await fs.mkdir(processDir, { recursive: true })
+    return processDir
+  }
+
+  private async ensureWorkspaceDir(workspaceId: string) {
+    const workspace = this.deps.workspaceManager.get(workspaceId)
+    if (!workspace) {
+      throw new Error("Workspace not found")
+    }
+    const root = path.join(workspace.path, ROOT_DIR, workspaceId)
+    await fs.mkdir(root, { recursive: true })
+    return root
+  }
+
+  private getOutputPath(workspaceId: string, processId: string) {
+    const workspace = this.deps.workspaceManager.get(workspaceId)
+    if (!workspace) {
+      throw new Error("Workspace not found")
+    }
+    return path.join(workspace.path, ROOT_DIR, workspaceId, processId, OUTPUT_FILE)
+  }
+
+  private async findProcess(workspaceId: string, processId: string): Promise<BackgroundProcess | null> {
+    const records = await this.readIndex(workspaceId)
+    return records.find((entry) => entry.id === processId) ?? null
+  }
+
+  private async readIndex(workspaceId: string): Promise<BackgroundProcess[]> {
+    const indexPath = await this.getIndexPath(workspaceId)
+    if (!existsSync(indexPath)) return []
+
+    try {
+      const raw = await fs.readFile(indexPath, "utf-8")
+      const parsed = JSON.parse(raw)
+      return Array.isArray(parsed) ? (parsed as BackgroundProcess[]) : []
+    } catch {
+      return []
+    }
+  }
+
+  private async upsertIndex(workspaceId: string, record: BackgroundProcess) {
+    const records = await this.readIndex(workspaceId)
+    const index = records.findIndex((entry) => entry.id === record.id)
+    if (index >= 0) {
+      records[index] = record
+    } else {
+      records.push(record)
+    }
+    await this.writeIndex(workspaceId, records)
+  }
+
+  private async removeFromIndex(workspaceId: string, processId: string) {
+    const records = await this.readIndex(workspaceId)
+    const next = records.filter((entry) => entry.id !== processId)
+    await this.writeIndex(workspaceId, next)
+  }
+
+  private async writeIndex(workspaceId: string, records: BackgroundProcess[]) {
+    const indexPath = await this.getIndexPath(workspaceId)
+    await fs.mkdir(path.dirname(indexPath), { recursive: true })
+    await fs.writeFile(indexPath, JSON.stringify(records, null, 2))
+  }
+
+  private async getIndexPath(workspaceId: string) {
+    const workspace = this.deps.workspaceManager.get(workspaceId)
+    if (!workspace) {
+      throw new Error("Workspace not found")
+    }
+    return path.join(workspace.path, ROOT_DIR, workspaceId, INDEX_FILE)
+  }
+
+  private async removeProcessDir(workspaceId: string, processId: string) {
+    const workspace = this.deps.workspaceManager.get(workspaceId)
+    if (!workspace) {
+      return
+    }
+    const processDir = path.join(workspace.path, ROOT_DIR, workspaceId, processId)
+    await fs.rm(processDir, { recursive: true, force: true })
+  }
+
+  private async removeWorkspaceDir(workspaceId: string) {
+    const workspace = this.deps.workspaceManager.get(workspaceId)
+    if (!workspace) {
+      return
+    }
+    const workspaceDir = path.join(workspace.path, ROOT_DIR, workspaceId)
+    await fs.rm(workspaceDir, { recursive: true, force: true })
+  }
+
+  private async getOutputSize(workspaceId: string, processId: string): Promise<number> {
+    const outputPath = this.getOutputPath(workspaceId, processId)
+    if (!existsSync(outputPath)) {
+      return 0
+    }
+    try {
+      const stats = await fs.stat(outputPath)
+      return stats.size
+    } catch {
+      return 0
+    }
+  }
+
+  private publishUpdate(workspaceId: string, record: BackgroundProcess) {
+    this.deps.eventBus.publish({
+      type: "instance.event",
+      instanceId: workspaceId,
+      event: { type: "background.process.updated", properties: { process: record } },
+    })
+  }
+
+  private generateId(): string {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "").slice(0, 15)
+    const random = randomBytes(3).toString("hex")
+    return `proc_${timestamp}_${random}`
+  }
+}

packages/server/src/config/binaries.ts

@@ -6,7 +6,7 @@ import {
 } from "../api-types"
 import { ConfigStore } from "./store"
 import { EventBus } from "../events/bus"
-import type { ConfigFileUpdate } from "./schema"
+import type { ConfigFile } from "./schema"
 import { Logger } from "../logger"
 
 export class BinaryRegistry {
@@ -39,17 +39,15 @@ export class BinaryRegistry {
     }
 
     const config = this.configStore.get()
-    const deduped = config.opencodeBinaries.filter((binary) => binary.path !== request.path)
+    const nextConfig = this.cloneConfig(config)
-
+    const deduped = nextConfig.opencodeBinaries.filter((binary) => binary.path !== request.path)
-    const update: ConfigFileUpdate = {
+    nextConfig.opencodeBinaries = [entry, ...deduped]
-      opencodeBinaries: [entry, ...deduped],
-    }
 
     if (request.makeDefault) {
-      update.preferences = { lastUsedBinary: request.path }
+      nextConfig.preferences.lastUsedBinary = request.path
     }
 
-    this.configStore.update(update)
+    this.configStore.replace(nextConfig)
     const record = this.getById(request.path)
     this.emitChange()
     return record
@@ -58,19 +56,16 @@ export class BinaryRegistry {
   update(id: string, updates: BinaryUpdateRequest): BinaryRecord {
     this.logger.debug({ id }, "Updating OpenCode binary")
     const config = this.configStore.get()
-    const updatedEntries = config.opencodeBinaries.map((binary) =>
+    const nextConfig = this.cloneConfig(config)
+    nextConfig.opencodeBinaries = nextConfig.opencodeBinaries.map((binary) =>
       binary.path === id ? { ...binary, label: updates.label ?? binary.label } : binary,
     )
 
-    const update: ConfigFileUpdate = {
-      opencodeBinaries: updatedEntries,
-    }
-
     if (updates.makeDefault) {
-      update.preferences = { lastUsedBinary: id }
+      nextConfig.preferences.lastUsedBinary = id
     }
 
-    this.configStore.update(update)
+    this.configStore.replace(nextConfig)
     const record = this.getById(id)
     this.emitChange()
     return record
@@ -79,14 +74,15 @@ export class BinaryRegistry {
   remove(id: string) {
     this.logger.debug({ id }, "Removing OpenCode binary")
     const config = this.configStore.get()
-    const remaining = config.opencodeBinaries.filter((binary) => binary.path !== id)
+    const nextConfig = this.cloneConfig(config)
-    const update: ConfigFileUpdate = { opencodeBinaries: remaining }
+    const remaining = nextConfig.opencodeBinaries.filter((binary) => binary.path !== id)
+    nextConfig.opencodeBinaries = remaining
 
-    if (config.preferences.lastUsedBinary === id) {
+    if (nextConfig.preferences.lastUsedBinary === id) {
-      update.preferences = { lastUsedBinary: remaining[0]?.path }
+      nextConfig.preferences.lastUsedBinary = remaining[0]?.path
     }
 
-    this.configStore.update(update)
+    this.configStore.replace(nextConfig)
     this.emitChange()
   }
 
@@ -100,7 +96,12 @@ export class BinaryRegistry {
     })
   }
 
+  private cloneConfig(config: ConfigFile): ConfigFile {
+    return JSON.parse(JSON.stringify(config)) as ConfigFile
+  }
+
   private mapRecords(): BinaryRecord[] {
+
     const config = this.configStore.get()
     const configuredBinaries = config.opencodeBinaries.map<BinaryRecord>((binary) => ({
       id: binary.path,

packages/server/src/config/schema.ts

@@ -10,24 +10,17 @@ const AgentModelSelectionsSchema = z.record(z.string(), AgentModelSelectionSchem
 
 const PreferencesSchema = z.object({
   showThinkingBlocks: z.boolean().default(false),
+  thinkingBlocksExpansion: z.enum(["expanded", "collapsed"]).default("expanded"),
+  showTimelineTools: z.boolean().default(true),
   lastUsedBinary: z.string().optional(),
   environmentVariables: z.record(z.string()).default({}),
   modelRecents: z.array(ModelPreferenceSchema).default([]),
-  agentModelSelections: AgentModelSelectionsSchema.default({}),
   diffViewMode: z.enum(["split", "unified"]).default("split"),
   toolOutputExpansion: z.enum(["expanded", "collapsed"]).default("expanded"),
   diagnosticsExpansion: z.enum(["expanded", "collapsed"]).default("expanded"),
-})
+  showUsageMetrics: z.boolean().default(true),
-
+  autoCleanupBlankSessions: z.boolean().default(true),
-const PreferencesUpdateSchema = z.object({
+  listeningMode: z.enum(["local", "all"]).default("local"),
-  showThinkingBlocks: z.boolean().optional(),
-  lastUsedBinary: z.string().optional(),
-  environmentVariables: z.record(z.string()).optional(),
-  modelRecents: z.array(ModelPreferenceSchema).optional(),
-  agentModelSelections: AgentModelSelectionsSchema.optional(),
-  diffViewMode: z.enum(["split", "unified"]).optional(),
-  toolOutputExpansion: z.enum(["expanded", "collapsed"]).optional(),
-  diagnosticsExpansion: z.enum(["expanded", "collapsed"]).optional(),
 })
 
 const RecentFolderSchema = z.object({
@@ -49,13 +42,6 @@ const ConfigFileSchema = z.object({
   theme: z.enum(["light", "dark", "system"]).optional(),
 })
 
-const ConfigFileUpdateSchema = z.object({
-  preferences: PreferencesUpdateSchema.optional(),
-  recentFolders: z.array(RecentFolderSchema).optional(),
-  opencodeBinaries: z.array(OpenCodeBinarySchema).optional(),
-  theme: z.enum(["light", "dark", "system"]).optional(),
-})
-
 const DEFAULT_CONFIG = ConfigFileSchema.parse({})
 
 export {
@@ -66,7 +52,6 @@ export {
   RecentFolderSchema,
   OpenCodeBinarySchema,
   ConfigFileSchema,
-  ConfigFileUpdateSchema,
   DEFAULT_CONFIG,
 }
 
@@ -77,4 +62,3 @@ export type Preferences = z.infer<typeof PreferencesSchema>
 export type RecentFolder = z.infer<typeof RecentFolderSchema>
 export type OpenCodeBinary = z.infer<typeof OpenCodeBinarySchema>
 export type ConfigFile = z.infer<typeof ConfigFileSchema>
-export type ConfigFileUpdate = z.infer<typeof ConfigFileUpdateSchema>

packages/server/src/config/store.ts

@@ -2,14 +2,7 @@ import fs from "fs"
 import path from "path"
 import { EventBus } from "../events/bus"
 import { Logger } from "../logger"
-import {
+import { ConfigFile, ConfigFileSchema, DEFAULT_CONFIG } from "./schema"
-  AgentModelSelections,
-  ConfigFile,
-  ConfigFileUpdate,
-  ConfigFileSchema,
-  ConfigFileUpdateSchema,
-  DEFAULT_CONFIG,
-} from "./schema"
 
 export class ConfigStore {
   private cache: ConfigFile = DEFAULT_CONFIG
@@ -50,54 +43,19 @@ export class ConfigStore {
     return this.load()
   }
 
-  update(partial: ConfigFile | ConfigFileUpdate) {
+  replace(config: ConfigFile) {
-    const safePartial =
+    const validated = ConfigFileSchema.parse(config)
-      "recentFolders" in partial && "opencodeBinaries" in partial
+    this.commit(validated)
-        ? ConfigFileSchema.parse(partial)
+  }
-        : ConfigFileUpdateSchema.parse(partial ?? {})
+
-    const merged = this.mergeConfig(this.load(), safePartial)
+  private commit(next: ConfigFile) {
-    this.cache = ConfigFileSchema.parse(merged)
+    this.cache = next
+    this.loaded = true
     this.persist()
+    const published = Boolean(this.eventBus)
     this.eventBus?.publish({ type: "config.appChanged", config: this.cache })
-    this.logger.debug("Config updated")
+    this.logger.debug({ broadcast: published }, "Config SSE event emitted")
-  }
+    this.logger.trace({ config: this.cache }, "Config payload")
-
-  private mergeConfig(current: ConfigFile, partial: ConfigFile | ConfigFileUpdate): ConfigFile {
-    const mergedPreferences = {
-      ...current.preferences,
-      ...partial.preferences,
-      environmentVariables: {
-        ...current.preferences.environmentVariables,
-        ...(partial.preferences?.environmentVariables ?? {}),
-      },
-      agentModelSelections: this.mergeAgentSelections(
-        current.preferences.agentModelSelections,
-        partial.preferences?.agentModelSelections,
-      ),
-    }
-
-    return {
-      ...current,
-      ...partial,
-      preferences: mergedPreferences,
-      recentFolders: partial.recentFolders ?? current.recentFolders,
-      opencodeBinaries: partial.opencodeBinaries ?? current.opencodeBinaries,
-    }
-  }
-
-  private mergeAgentSelections(base: AgentModelSelections, update?: AgentModelSelections) {
-    if (!update) {
-      return base
-    }
-
-    const result: AgentModelSelections = { ...base }
-    for (const [instanceId, agentMap] of Object.entries(update)) {
-      result[instanceId] = {
-        ...(base[instanceId] ?? {}),
-        ...agentMap,
-      }
-    }
-    return result
   }
 
   private persist() {

packages/server/src/events/bus.ts

@@ -8,7 +8,12 @@ export class EventBus extends EventEmitter {
   }
 
   publish(event: WorkspaceEventPayload): boolean {
-    this.logger?.debug({ event }, "Publishing workspace event")
+    if (event.type !== "instance.event" && event.type !== "instance.eventStatus") {
+      this.logger?.debug({ type: event.type }, "Publishing workspace event")
+      if (this.logger?.isLevelEnabled("trace")) {
+        this.logger.trace({ event }, "Workspace event payload")
+      }
+    }
     return super.emit(event.type, event)
   }
 
@@ -21,6 +26,10 @@ export class EventBus extends EventEmitter {
     this.on("workspace.log", handler)
     this.on("config.appChanged", handler)
     this.on("config.binariesChanged", handler)
+    this.on("instance.dataChanged", handler)
+    this.on("instance.event", handler)
+    this.on("instance.eventStatus", handler)
+    this.on("app.releaseAvailable", handler)
     return () => {
       this.off("workspace.created", handler)
       this.off("workspace.started", handler)
@@ -29,6 +38,10 @@ export class EventBus extends EventEmitter {
       this.off("workspace.log", handler)
       this.off("config.appChanged", handler)
       this.off("config.binariesChanged", handler)
+      this.off("instance.dataChanged", handler)
+      this.off("instance.event", handler)
+      this.off("instance.eventStatus", handler)
+      this.off("app.releaseAvailable", handler)
     }
   }
 }

packages/server/src/filesystem/__tests__/search-cache.test.ts

@@ -0,0 +1,61 @@
+import assert from "node:assert/strict"
+import { beforeEach, describe, it } from "node:test"
+import type { FileSystemEntry } from "../../api-types"
+import {
+  clearWorkspaceSearchCache,
+  getWorkspaceCandidates,
+  refreshWorkspaceCandidates,
+  WORKSPACE_CANDIDATE_CACHE_TTL_MS,
+} from "../search-cache"
+
+describe("workspace search cache", () => {
+  beforeEach(() => {
+    clearWorkspaceSearchCache()
+  })
+
+  it("expires cached candidates after the TTL", () => {
+    const workspacePath = "/tmp/workspace"
+    const startTime = 1_000
+
+    refreshWorkspaceCandidates(workspacePath, () => [createEntry("file-a")], startTime)
+
+    const beforeExpiry = getWorkspaceCandidates(
+      workspacePath,
+      startTime + WORKSPACE_CANDIDATE_CACHE_TTL_MS - 1,
+    )
+    assert.ok(beforeExpiry)
+    assert.equal(beforeExpiry.length, 1)
+    assert.equal(beforeExpiry[0].name, "file-a")
+
+    const afterExpiry = getWorkspaceCandidates(
+      workspacePath,
+      startTime + WORKSPACE_CANDIDATE_CACHE_TTL_MS + 1,
+    )
+    assert.equal(afterExpiry, undefined)
+  })
+
+  it("replaces cached entries when manually refreshed", () => {
+    const workspacePath = "/tmp/workspace"
+
+    refreshWorkspaceCandidates(workspacePath, () => [createEntry("file-a")], 5_000)
+    const initial = getWorkspaceCandidates(workspacePath)
+    assert.ok(initial)
+    assert.equal(initial[0].name, "file-a")
+
+    refreshWorkspaceCandidates(workspacePath, () => [createEntry("file-b")], 6_000)
+    const refreshed = getWorkspaceCandidates(workspacePath)
+    assert.ok(refreshed)
+    assert.equal(refreshed[0].name, "file-b")
+  })
+})
+
+function createEntry(name: string): FileSystemEntry {
+  return {
+    name,
+    path: name,
+    absolutePath: `/tmp/${name}`,
+    type: "file",
+    size: 1,
+    modifiedAt: new Date().toISOString(),
+  }
+}

packages/server/src/filesystem/search-cache.ts

@@ -0,0 +1,66 @@
+import path from "path"
+import type { FileSystemEntry } from "../api-types"
+
+export const WORKSPACE_CANDIDATE_CACHE_TTL_MS = 30_000
+
+interface WorkspaceCandidateCacheEntry {
+  expiresAt: number
+  candidates: FileSystemEntry[]
+}
+
+const workspaceCandidateCache = new Map<string, WorkspaceCandidateCacheEntry>()
+
+export function getWorkspaceCandidates(rootDir: string, now = Date.now()): FileSystemEntry[] | undefined {
+  const key = normalizeKey(rootDir)
+  const cached = workspaceCandidateCache.get(key)
+  if (!cached) {
+    return undefined
+  }
+
+  if (cached.expiresAt <= now) {
+    workspaceCandidateCache.delete(key)
+    return undefined
+  }
+
+  return cloneEntries(cached.candidates)
+}
+
+export function refreshWorkspaceCandidates(
+  rootDir: string,
+  builder: () => FileSystemEntry[],
+  now = Date.now(),
+): FileSystemEntry[] {
+  const key = normalizeKey(rootDir)
+  const freshCandidates = builder()
+
+  if (!freshCandidates || freshCandidates.length === 0) {
+    workspaceCandidateCache.delete(key)
+    return []
+  }
+
+  const storedCandidates = cloneEntries(freshCandidates)
+  workspaceCandidateCache.set(key, {
+    expiresAt: now + WORKSPACE_CANDIDATE_CACHE_TTL_MS,
+    candidates: storedCandidates,
+  })
+
+  return cloneEntries(storedCandidates)
+}
+
+export function clearWorkspaceSearchCache(rootDir?: string) {
+  if (typeof rootDir === "undefined") {
+    workspaceCandidateCache.clear()
+    return
+  }
+
+  const key = normalizeKey(rootDir)
+  workspaceCandidateCache.delete(key)
+}
+
+function cloneEntries(entries: FileSystemEntry[]): FileSystemEntry[] {
+  return entries.map((entry) => ({ ...entry }))
+}
+
+function normalizeKey(rootDir: string) {
+  return path.resolve(rootDir)
+}

packages/server/src/filesystem/search.ts

@@ -0,0 +1,184 @@
+import fs from "fs"
+import path from "path"
+import fuzzysort from "fuzzysort"
+import type { FileSystemEntry } from "../api-types"
+import { clearWorkspaceSearchCache, getWorkspaceCandidates, refreshWorkspaceCandidates } from "./search-cache"
+
+const DEFAULT_LIMIT = 100
+const MAX_LIMIT = 200
+const MAX_CANDIDATES = 8000
+const IGNORED_DIRECTORIES = new Set(
+  [".git", ".hg", ".svn", "node_modules", "dist", "build", ".next", ".nuxt", ".turbo", ".cache", "coverage"].map(
+    (name) => name.toLowerCase(),
+  ),
+)
+
+export type WorkspaceFileSearchType = "all" | "file" | "directory"
+
+export interface WorkspaceFileSearchOptions {
+  limit?: number
+  type?: WorkspaceFileSearchType
+  refresh?: boolean
+}
+
+interface CandidateEntry {
+  entry: FileSystemEntry
+  key: string
+}
+
+export function searchWorkspaceFiles(
+  rootDir: string,
+  query: string,
+  options: WorkspaceFileSearchOptions = {},
+): FileSystemEntry[] {
+  const trimmedQuery = query.trim()
+  if (!trimmedQuery) {
+    throw new Error("Search query is required")
+  }
+
+  const normalizedRoot = path.resolve(rootDir)
+  const limit = normalizeLimit(options.limit)
+  const typeFilter: WorkspaceFileSearchType = options.type ?? "all"
+  const refreshRequested = options.refresh === true
+
+  let entries: FileSystemEntry[] | undefined
+
+  try {
+    if (!refreshRequested) {
+      entries = getWorkspaceCandidates(normalizedRoot)
+    }
+
+    if (!entries) {
+      entries = refreshWorkspaceCandidates(normalizedRoot, () => collectCandidates(normalizedRoot))
+    }
+  } catch (error) {
+    clearWorkspaceSearchCache(normalizedRoot)
+    throw error
+  }
+
+  if (!entries || entries.length === 0) {
+    clearWorkspaceSearchCache(normalizedRoot)
+    return []
+  }
+
+  const candidates = buildCandidateEntries(entries, typeFilter)
+
+  if (candidates.length === 0) {
+    return []
+  }
+
+  const matches = fuzzysort.go<CandidateEntry>(trimmedQuery, candidates, {
+    key: "key",
+    limit,
+  })
+
+  if (!matches || matches.length === 0) {
+    return []
+  }
+
+  return matches.map((match) => match.obj.entry)
+}
+
+
+function collectCandidates(rootDir: string): FileSystemEntry[] {
+  const queue: string[] = [""]
+  const entries: FileSystemEntry[] = []
+
+  while (queue.length > 0 && entries.length < MAX_CANDIDATES) {
+    const relativeDir = queue.pop() || ""
+    const absoluteDir = relativeDir ? path.join(rootDir, relativeDir) : rootDir
+
+    let dirents: fs.Dirent[]
+    try {
+      dirents = fs.readdirSync(absoluteDir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+
+    for (const dirent of dirents) {
+      const entryName = dirent.name
+      const lowerName = entryName.toLowerCase()
+      const relativePath = relativeDir ? `${relativeDir}/${entryName}` : entryName
+      const absolutePath = path.join(absoluteDir, entryName)
+
+      if (dirent.isDirectory() && IGNORED_DIRECTORIES.has(lowerName)) {
+        continue
+      }
+
+      let stats: fs.Stats
+      try {
+        stats = fs.statSync(absolutePath)
+      } catch {
+        continue
+      }
+
+      const isDirectory = stats.isDirectory()
+
+      if (isDirectory && !IGNORED_DIRECTORIES.has(lowerName)) {
+        if (entries.length < MAX_CANDIDATES) {
+          queue.push(relativePath)
+        }
+      }
+
+      const entryType: FileSystemEntry["type"] = isDirectory ? "directory" : "file"
+      const normalizedPath = normalizeRelativeEntryPath(relativePath)
+      const entry: FileSystemEntry = {
+        name: entryName,
+        path: normalizedPath,
+        absolutePath: path.resolve(rootDir, normalizedPath === "." ? "" : normalizedPath),
+        type: entryType,
+        size: entryType === "file" ? stats.size : undefined,
+        modifiedAt: stats.mtime.toISOString(),
+      }
+
+      entries.push(entry)
+
+      if (entries.length >= MAX_CANDIDATES) {
+        break
+      }
+    }
+  }
+
+  return entries
+}
+
+function buildCandidateEntries(entries: FileSystemEntry[], filter: WorkspaceFileSearchType): CandidateEntry[] {
+  const filtered: CandidateEntry[] = []
+  for (const entry of entries) {
+    if (!shouldInclude(entry.type, filter)) {
+      continue
+    }
+    filtered.push({ entry, key: buildSearchKey(entry) })
+  }
+  return filtered
+}
+
+function normalizeLimit(limit?: number) {
+  if (!limit || Number.isNaN(limit)) {
+    return DEFAULT_LIMIT
+  }
+  const clamped = Math.min(Math.max(limit, 1), MAX_LIMIT)
+  return clamped
+}
+
+function shouldInclude(entryType: FileSystemEntry["type"], filter: WorkspaceFileSearchType) {
+  return filter === "all" || entryType === filter
+}
+
+function normalizeRelativeEntryPath(relativePath: string): string {
+  if (!relativePath) {
+    return "."
+  }
+  let normalized = relativePath.replace(/\\+/g, "/")
+  if (normalized.startsWith("./")) {
+    normalized = normalized.replace(/^\.\/+/, "")
+  }
+  if (normalized.startsWith("/")) {
+    normalized = normalized.replace(/^\/+/g, "")
+  }
+  return normalized || "."
+}
+
+function buildSearchKey(entry: FileSystemEntry) {
+  return entry.path.toLowerCase()
+}

packages/server/src/index.ts

@@ -14,9 +14,13 @@ import { FileSystemBrowser } from "./filesystem/browser"
 import { EventBus } from "./events/bus"
 import { ServerMeta } from "./api-types"
 import { InstanceStore } from "./storage/instance-store"
+import { InstanceEventBridge } from "./workspaces/instance-events"
 import { createLogger } from "./logger"
+import { launchInBrowser } from "./launcher"
+import { startReleaseMonitor } from "./releases/release-monitor"
 
 const require = createRequire(import.meta.url)
+
 const packageJson = require("../package.json") as { version: string }
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -32,6 +36,7 @@ interface CliOptions {
   logDestination?: string
   uiStaticDir: string
   uiDevServer?: string
+  launch: boolean
 }
 
 const DEFAULT_PORT = 9898
@@ -40,7 +45,7 @@ const DEFAULT_CONFIG_PATH = "~/.config/codenomad/config.json"
 
 function parseCliOptions(argv: string[]): CliOptions {
   const program = new Command()
-    .name("codenomad-cli")
+    .name("codenomad")
     .description("CodeNomad CLI server")
     .version(packageJson.version, "-v, --version", "Show the CLI version")
     .addOption(new Option("--host <host>", "Host interface to bind").env("CLI_HOST").default(DEFAULT_HOST))
@@ -57,6 +62,7 @@ function parseCliOptions(argv: string[]): CliOptions {
       new Option("--ui-dir <path>", "Directory containing the built UI bundle").env("CLI_UI_DIR").default(DEFAULT_UI_STATIC_DIR),
     )
     .addOption(new Option("--ui-dev-server <url>", "Proxy UI requests to a running dev server").env("CLI_UI_DEV_SERVER"))
+    .addOption(new Option("--launch", "Launch the UI in a browser after start").env("CLI_LAUNCH").default(false))
 
   program.parse(argv, { from: "user" })
   const parsed = program.opts<{
@@ -70,13 +76,16 @@ function parseCliOptions(argv: string[]): CliOptions {
     logDestination?: string
     uiDir: string
     uiDevServer?: string
+    launch?: boolean
   }>()
 
   const resolvedRoot = parsed.workspaceRoot ?? parsed.root ?? process.cwd()
 
+  const normalizedHost = resolveHost(parsed.host)
+
   return {
     port: parsed.port,
-    host: parsed.host,
+    host: normalizedHost,
     rootDir: resolvedRoot,
     configPath: parsed.config,
     unrestrictedRoot: Boolean(parsed.unrestrictedRoot),
@@ -84,17 +93,25 @@ function parseCliOptions(argv: string[]): CliOptions {
     logDestination: parsed.logDestination,
     uiStaticDir: parsed.uiDir,
     uiDevServer: parsed.uiDevServer,
+    launch: Boolean(parsed.launch),
   }
 }
 
 function parsePort(input: string): number {
   const value = Number(input)
-  if (!Number.isInteger(value) || value < 1 || value > 65535) {
+  if (!Number.isInteger(value) || value < 0 || value > 65535) {
-    throw new InvalidArgumentError("Port must be an integer between 1 and 65535")
+    throw new InvalidArgumentError("Port must be an integer between 0 and 65535")
   }
   return value
 }
 
+function resolveHost(input: string | undefined): string {
+  if (input && input.trim() === "0.0.0.0") {
+    return "0.0.0.0"
+  }
+  return DEFAULT_HOST
+}
+
 async function main() {
   const options = parseCliOptions(process.argv.slice(2))
   const logger = createLogger({ level: options.logLevel, destination: options.logDestination, component: "app" })
@@ -105,6 +122,18 @@ async function main() {
   logger.info({ options }, "Starting CodeNomad CLI server")
 
   const eventBus = new EventBus(eventLogger)
+
+  const serverMeta: ServerMeta = {
+    httpBaseUrl: `http://${options.host}:${options.port}`,
+    eventsUrl: `/api/events`,
+    host: options.host,
+    listeningMode: options.host === "0.0.0.0" ? "all" : "local",
+    port: options.port,
+    hostLabel: options.host,
+    workspaceRoot: options.rootDir,
+    addresses: [],
+  }
+
   const configStore = new ConfigStore(options.configPath, eventBus, configLogger)
   const binaryRegistry = new BinaryRegistry(configStore, eventBus, configLogger)
   const workspaceManager = new WorkspaceManager({
@@ -113,16 +142,28 @@ async function main() {
     binaryRegistry,
     eventBus,
     logger: workspaceLogger,
+    getServerBaseUrl: () => serverMeta.httpBaseUrl,
   })
   const fileSystemBrowser = new FileSystemBrowser({ rootDir: options.rootDir, unrestricted: options.unrestrictedRoot })
   const instanceStore = new InstanceStore()
+  const instanceEventBridge = new InstanceEventBridge({
+    workspaceManager,
+    eventBus,
+    logger: logger.child({ component: "instance-events" }),
+  })
 
-  const serverMeta: ServerMeta = {
+  const releaseMonitor = startReleaseMonitor({
-    httpBaseUrl: `http://${options.host}:${options.port}`,
+    currentVersion: packageJson.version,
-    eventsUrl: `/api/events`,
+    logger: logger.child({ component: "release-monitor" }),
-    hostLabel: options.host,
+    onUpdate: (release) => {
-    workspaceRoot: options.rootDir,
+      if (release) {
+        serverMeta.latestRelease = release
+        eventBus.publish({ type: "app.releaseAvailable", release })
+      } else {
+        delete serverMeta.latestRelease
       }
+    },
+  })
 
   const server = createHttpServer({
     host: options.host,
@@ -139,11 +180,13 @@ async function main() {
     logger,
   })
 
+  const startInfo = await server.start()
+  logger.info({ port: startInfo.port, host: options.host }, "HTTP server listening")
+  console.log(`CodeNomad Server is ready at ${startInfo.url}`)
 
-  await server.start()
+  if (options.launch) {
-  logger.info({ port: options.port, host: options.host }, "HTTP server listening")
+    await launchInBrowser(startInfo.url, logger.child({ component: "launcher" }))
-  const displayHost = options.host === "127.0.0.1" || options.host === "0.0.0.0" ? "localhost" : options.host
+  }
-  console.log(`CodeNomad Server is ready at http://${displayHost}:${options.port}`)
 
   let shuttingDown = false
 
@@ -162,12 +205,15 @@ async function main() {
     }
 
     try {
+      instanceEventBridge.shutdown()
       await workspaceManager.shutdown()
       logger.info("Workspace manager shutdown complete")
     } catch (error) {
       logger.error({ err: error }, "Workspace manager shutdown failed")
     }
 
+    releaseMonitor.stop()
+
     logger.info("Exiting process")
     process.exit(0)
   }

packages/server/src/launcher.ts

@@ -0,0 +1,177 @@
+import { spawn } from "child_process"
+import os from "os"
+import path from "path"
+import type { Logger } from "./logger"
+
+interface BrowserCandidate {
+  name: string
+  command: string
+  args: (url: string) => string[]
+}
+
+const APP_ARGS = (url: string) => [`--app=${url}`, "--new-window"]
+
+export async function launchInBrowser(url: string, logger: Logger): Promise<boolean> {
+  const { platform, candidates, manualExamples } = buildPlatformCandidates(url)
+
+  console.log(`Attempting to launch browser (${platform}) using:`)
+  candidates.forEach((candidate) => console.log(`  - ${candidate.name}: ${candidate.command}`))
+
+  for (const candidate of candidates) {
+    const success = await tryLaunch(candidate, url, logger)
+    if (success) {
+      return true
+    }
+  }
+
+  console.error(
+    "No supported browser found to launch. Run without --launch and use one of the commands below or install a compatible browser.",
+  )
+  if (manualExamples.length > 0) {
+    console.error("Manual launch commands:")
+    manualExamples.forEach((line) => console.error(`  ${line}`))
+  }
+
+  return false
+}
+
+async function tryLaunch(candidate: BrowserCandidate, url: string, logger: Logger): Promise<boolean> {
+  return new Promise((resolve) => {
+    let resolved = false
+    try {
+      const args = candidate.args(url)
+      const child = spawn(candidate.command, args, { stdio: "ignore", detached: true })
+
+      child.once("error", (error) => {
+        if (resolved) return
+        resolved = true
+        logger.debug({ err: error, candidate: candidate.name, command: candidate.command, args }, "Browser launch failed")
+        resolve(false)
+      })
+
+      child.once("spawn", () => {
+        if (resolved) return
+        resolved = true
+        logger.info(
+          {
+            browser: candidate.name,
+            command: candidate.command,
+            args,
+            fullCommand: [candidate.command, ...args].join(" "),
+          },
+          "Launched browser in app mode",
+        )
+        child.unref()
+        resolve(true)
+      })
+    } catch (error) {
+      if (resolved) return
+      resolved = true
+      logger.debug({ err: error, candidate: candidate.name, command: candidate.command }, "Browser spawn threw")
+      resolve(false)
+    }
+  })
+}
+
+function buildPlatformCandidates(url: string) {
+  switch (os.platform()) {
+    case "darwin":
+      return {
+        platform: "macOS",
+        candidates: buildMacCandidates(),
+        manualExamples: buildMacManualExamples(url),
+      }
+    case "win32":
+      return {
+        platform: "Windows",
+        candidates: buildWindowsCandidates(),
+        manualExamples: buildWindowsManualExamples(url),
+      }
+    default:
+      return {
+        platform: "Linux",
+        candidates: buildLinuxCandidates(),
+        manualExamples: buildLinuxManualExamples(url),
+      }
+  }
+}
+
+function buildMacCandidates(): BrowserCandidate[] {
+  const apps = [
+    { name: "Google Chrome", path: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" },
+    { name: "Google Chrome Canary", path: "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary" },
+    { name: "Microsoft Edge", path: "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" },
+    { name: "Brave Browser", path: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" },
+    { name: "Chromium", path: "/Applications/Chromium.app/Contents/MacOS/Chromium" },
+    { name: "Vivaldi", path: "/Applications/Vivaldi.app/Contents/MacOS/Vivaldi" },
+    { name: "Arc", path: "/Applications/Arc.app/Contents/MacOS/Arc" },
+  ]
+
+  return apps.map((entry) => ({ name: entry.name, command: entry.path, args: APP_ARGS }))
+}
+
+function buildWindowsCandidates(): BrowserCandidate[] {
+  const programFiles = process.env["ProgramFiles"]
+  const programFilesX86 = process.env["ProgramFiles(x86)"]
+  const localAppData = process.env["LocalAppData"]
+
+  const paths = [
+    [programFiles, "Google/Chrome/Application/chrome.exe", "Google Chrome"],
+    [programFilesX86, "Google/Chrome/Application/chrome.exe", "Google Chrome (x86)"],
+    [localAppData, "Google/Chrome/Application/chrome.exe", "Google Chrome (User)"],
+    [programFiles, "Microsoft/Edge/Application/msedge.exe", "Microsoft Edge"],
+    [programFilesX86, "Microsoft/Edge/Application/msedge.exe", "Microsoft Edge (x86)"],
+    [localAppData, "Microsoft/Edge/Application/msedge.exe", "Microsoft Edge (User)"],
+    [programFiles, "BraveSoftware/Brave-Browser/Application/brave.exe", "Brave"],
+    [localAppData, "BraveSoftware/Brave-Browser/Application/brave.exe", "Brave (User)"],
+    [programFiles, "Chromium/Application/chromium.exe", "Chromium"],
+  ] as const
+
+  return paths
+    .filter(([root]) => Boolean(root))
+    .map(([root, rel, name]) => ({
+      name,
+      command: path.join(root as string, rel),
+      args: APP_ARGS,
+    }))
+}
+
+function buildLinuxCandidates(): BrowserCandidate[] {
+  const names = [
+    "google-chrome",
+    "google-chrome-stable",
+    "chromium",
+    "chromium-browser",
+    "brave-browser",
+    "microsoft-edge",
+    "microsoft-edge-stable",
+    "vivaldi",
+  ]
+
+  return names.map((name) => ({ name, command: name, args: APP_ARGS }))
+}
+
+function buildMacManualExamples(url: string) {
+  return [
+    `"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --app="${url}" --new-window`,
+    `"/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" --app="${url}" --new-window`,
+    `"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" --app="${url}" --new-window`,
+  ]
+}
+
+function buildWindowsManualExamples(url: string) {
+  return [
+    `"%ProgramFiles%\\Google\\Chrome\\Application\\chrome.exe" --app="${url}" --new-window`,
+    `"%ProgramFiles%\\Microsoft\\Edge\\Application\\msedge.exe" --app="${url}" --new-window`,
+    `"%ProgramFiles%\\BraveSoftware\\Brave-Browser\\Application\\brave.exe" --app="${url}" --new-window`,
+  ]
+}
+
+function buildLinuxManualExamples(url: string) {
+  return [
+    `google-chrome --app="${url}" --new-window`,
+    `chromium --app="${url}" --new-window`,
+    `brave-browser --app="${url}" --new-window`,
+    `microsoft-edge --app="${url}" --new-window`,
+  ]
+}

packages/server/src/opencode-config.ts

@@ -0,0 +1,31 @@
+import { existsSync } from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+import { createLogger } from "./logger"
+
+const log = createLogger({ component: "opencode-config" })
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const devTemplateDir = path.resolve(__dirname, "../../opencode-config")
+const resourcesPath = (process as NodeJS.Process & { resourcesPath?: string }).resourcesPath
+const prodTemplateDirs = [
+  resourcesPath ? path.resolve(resourcesPath, "opencode-config") : undefined,
+  path.resolve(__dirname, "opencode-config"),
+].filter((dir): dir is string => Boolean(dir))
+
+const isDevBuild = Boolean(process.env.CODENOMAD_DEV ?? process.env.CLI_UI_DEV_SERVER) || existsSync(devTemplateDir)
+const templateDir = isDevBuild
+  ? devTemplateDir
+  : prodTemplateDirs.find((dir) => existsSync(dir)) ?? prodTemplateDirs[0]
+
+export function getOpencodeConfigDir(): string {
+  if (!existsSync(templateDir)) {
+    throw new Error(`CodeNomad Opencode config template missing at ${templateDir}`)
+  }
+
+  if (isDevBuild) {
+    log.debug({ templateDir }, "Using Opencode config template directly (dev mode)")
+  }
+
+  return templateDir
+}

packages/server/src/plugins/channel.ts

@@ -0,0 +1,55 @@
+import type { FastifyReply } from "fastify"
+import type { Logger } from "../logger"
+
+export interface PluginOutboundEvent {
+  type: string
+  properties?: Record<string, unknown>
+}
+
+interface ClientConnection {
+  reply: FastifyReply
+  workspaceId: string
+}
+
+export class PluginChannelManager {
+  private readonly clients = new Set<ClientConnection>()
+
+  constructor(private readonly logger: Logger) {}
+
+  register(workspaceId: string, reply: FastifyReply) {
+    const connection: ClientConnection = { workspaceId, reply }
+    this.clients.add(connection)
+    this.logger.debug({ workspaceId }, "Plugin SSE client connected")
+
+    let closed = false
+    const close = () => {
+      if (closed) return
+      closed = true
+      this.clients.delete(connection)
+      this.logger.debug({ workspaceId }, "Plugin SSE client disconnected")
+    }
+
+    return { close }
+  }
+
+  send(workspaceId: string, event: PluginOutboundEvent) {
+    for (const client of this.clients) {
+      if (client.workspaceId !== workspaceId) continue
+      this.write(client.reply, event)
+    }
+  }
+
+  broadcast(event: PluginOutboundEvent) {
+    for (const client of this.clients) {
+      this.write(client.reply, event)
+    }
+  }
+
+  private write(reply: FastifyReply, event: PluginOutboundEvent) {
+    try {
+      reply.raw.write(`data: ${JSON.stringify(event)}\n\n`)
+    } catch (error) {
+      this.logger.warn({ err: error }, "Failed to write plugin SSE event")
+    }
+  }
+}

packages/server/src/plugins/handlers.ts

@@ -0,0 +1,36 @@
+import type { EventBus } from "../events/bus"
+import type { WorkspaceManager } from "../workspaces/manager"
+import type { Logger } from "../logger"
+import type { PluginOutboundEvent } from "./channel"
+
+export interface PluginInboundEvent {
+  type: string
+  properties?: Record<string, unknown>
+}
+
+interface HandlerDeps {
+  workspaceManager: WorkspaceManager
+  eventBus: EventBus
+  logger: Logger
+}
+
+export function handlePluginEvent(workspaceId: string, event: PluginInboundEvent, deps: HandlerDeps) {
+  switch (event.type) {
+    case "codenomad.pong":
+      deps.logger.debug({ workspaceId, properties: event.properties }, "Plugin pong received")
+      return
+
+    default:
+      deps.logger.debug({ workspaceId, eventType: event.type }, "Unhandled plugin event")
+  }
+}
+
+export function buildPingEvent(): PluginOutboundEvent {
+
+  return {
+    type: "codenomad.ping",
+    properties: {
+      ts: Date.now(),
+    },
+  }
+}

packages/server/src/releases/release-monitor.ts

@@ -0,0 +1,141 @@
+import { fetch } from "undici"
+import type { LatestReleaseInfo } from "../api-types"
+import type { Logger } from "../logger"
+
+const RELEASES_API_URL = "https://api.github.com/repos/NeuralNomadsAI/CodeNomad/releases/latest"
+interface ReleaseMonitorOptions {
+  currentVersion: string
+  logger: Logger
+  onUpdate: (release: LatestReleaseInfo | null) => void
+}
+
+interface GithubReleaseResponse {
+  tag_name?: string
+  name?: string
+  html_url?: string
+  body?: string
+  published_at?: string
+  created_at?: string
+  prerelease?: boolean
+}
+
+interface NormalizedVersion {
+  major: number
+  minor: number
+  patch: number
+  prerelease: string | null
+}
+
+export interface ReleaseMonitor {
+  stop(): void
+}
+
+export function startReleaseMonitor(options: ReleaseMonitorOptions): ReleaseMonitor {
+  let stopped = false
+
+  const refreshRelease = async () => {
+    if (stopped) return
+    try {
+      const release = await fetchLatestRelease(options)
+      options.onUpdate(release)
+    } catch (error) {
+      options.logger.warn({ err: error }, "Failed to refresh release information")
+    }
+  }
+
+  void refreshRelease()
+
+  return {
+    stop() {
+      stopped = true
+    },
+  }
+}
+
+async function fetchLatestRelease(options: ReleaseMonitorOptions): Promise<LatestReleaseInfo | null> {
+  const response = await fetch(RELEASES_API_URL, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      "User-Agent": "CodeNomad-CLI",
+    },
+  })
+
+  if (!response.ok) {
+    throw new Error(`Release API responded with ${response.status}`)
+  }
+
+  const json = (await response.json()) as GithubReleaseResponse
+  const tagFromServer = json.tag_name || json.name
+  if (!tagFromServer) {
+    return null
+  }
+
+  const normalizedVersion = stripTagPrefix(tagFromServer)
+  if (!normalizedVersion) {
+    return null
+  }
+
+  const current = parseVersion(options.currentVersion)
+  const remote = parseVersion(normalizedVersion)
+
+  if (compareVersions(remote, current) <= 0) {
+    return null
+  }
+
+  return {
+    version: normalizedVersion,
+    tag: tagFromServer,
+    url: json.html_url ?? `https://github.com/NeuralNomadsAI/CodeNomad/releases/tag/${encodeURIComponent(tagFromServer)}`,
+    channel: json.prerelease || normalizedVersion.includes("-") ? "dev" : "stable",
+    publishedAt: json.published_at ?? json.created_at,
+    notes: json.body,
+  }
+}
+
+function stripTagPrefix(tag: string | undefined): string | null {
+  if (!tag) return null
+  const trimmed = tag.trim()
+  if (!trimmed) return null
+  return trimmed.replace(/^v/i, "")
+}
+
+function parseVersion(value: string): NormalizedVersion {
+  const normalized = stripTagPrefix(value) ?? "0.0.0"
+  const [core, prerelease = null] = normalized.split("-", 2)
+  const [major = 0, minor = 0, patch = 0] = core.split(".").map((segment) => {
+    const parsed = Number.parseInt(segment, 10)
+    return Number.isFinite(parsed) ? parsed : 0
+  })
+  return {
+    major,
+    minor,
+    patch,
+    prerelease,
+  }
+}
+
+function compareVersions(a: NormalizedVersion, b: NormalizedVersion): number {
+  if (a.major !== b.major) {
+    return a.major > b.major ? 1 : -1
+  }
+  if (a.minor !== b.minor) {
+    return a.minor > b.minor ? 1 : -1
+  }
+  if (a.patch !== b.patch) {
+    return a.patch > b.patch ? 1 : -1
+  }
+
+  const aPre = a.prerelease && a.prerelease.length > 0 ? a.prerelease : null
+  const bPre = b.prerelease && b.prerelease.length > 0 ? b.prerelease : null
+
+  if (aPre === bPre) {
+    return 0
+  }
+  if (!aPre) {
+    return 1
+  }
+  if (!bPre) {
+    return -1
+  }
+  return aPre.localeCompare(bPre)
+}

packages/server/src/server/http-server.ts

@@ -1,7 +1,7 @@
 import Fastify, { type FastifyInstance, type FastifyReply, type FastifyRequest } from "fastify"
 import cors from "@fastify/cors"
 import fastifyStatic from "@fastify/static"
-import replyFrom, { type FastifyReplyFromOptions } from "@fastify/reply-from"
+import replyFrom from "@fastify/reply-from"
 import fs from "fs"
 import path from "path"
 import { fetch } from "undici"
@@ -18,8 +18,11 @@ import { registerFilesystemRoutes } from "./routes/filesystem"
 import { registerMetaRoutes } from "./routes/meta"
 import { registerEventRoutes } from "./routes/events"
 import { registerStorageRoutes } from "./routes/storage"
+import { registerPluginRoutes } from "./routes/plugin"
+import { registerBackgroundProcessRoutes } from "./routes/background-processes"
 import { ServerMeta } from "../api-types"
 import { InstanceStore } from "../storage/instance-store"
+import { BackgroundProcessManager } from "../background-processes/manager"
 
 interface HttpServerDeps {
   host: string
@@ -36,10 +39,19 @@ interface HttpServerDeps {
   logger: Logger
 }
 
+interface HttpServerStartResult {
+  port: number
+  url: string
+  displayHost: string
+}
+
+const DEFAULT_HTTP_PORT = 9898
 
 export function createHttpServer(deps: HttpServerDeps) {
   const app = Fastify({ logger: false })
   const proxyLogger = deps.logger.child({ component: "proxy" })
+  const apiLogger = deps.logger.child({ component: "http" })
+  const sseLogger = deps.logger.child({ component: "sse" })
 
   const sseClients = new Set<() => void>()
   const registerSseClient = (cleanup: () => void) => {
@@ -53,6 +65,29 @@ export function createHttpServer(deps: HttpServerDeps) {
     sseClients.clear()
   }
 
+  app.addHook("onRequest", (request, _reply, done) => {
+    ;(request as FastifyRequest & { __logMeta?: { start: bigint } }).__logMeta = {
+      start: process.hrtime.bigint(),
+    }
+    done()
+  })
+
+  app.addHook("onResponse", (request, reply, done) => {
+    const meta = (request as FastifyRequest & { __logMeta?: { start: bigint } }).__logMeta
+    const durationMs = meta ? Number((process.hrtime.bigint() - meta.start) / BigInt(1_000_000)) : undefined
+    const base = {
+      method: request.method,
+      url: request.url,
+      status: reply.statusCode,
+      durationMs,
+    }
+    apiLogger.debug(base, "HTTP request completed")
+    if (apiLogger.isLevelEnabled("trace")) {
+      apiLogger.trace({ ...base, params: request.params, query: request.query, body: request.body }, "HTTP request payload")
+    }
+    done()
+  })
+
   app.register(cors, {
     origin: true,
     credentials: true,
@@ -60,16 +95,35 @@ export function createHttpServer(deps: HttpServerDeps) {
 
   app.register(replyFrom, {
     contentTypesToEncode: [],
+    undici: {
+      connections: 16,
+      pipelining: 1,
+      bodyTimeout: 0,
+      headersTimeout: 0,
+    },
+  })
+
+  const backgroundProcessManager = new BackgroundProcessManager({
+    workspaceManager: deps.workspaceManager,
+    eventBus: deps.eventBus,
+    logger: deps.logger.child({ component: "background-processes" }),
   })
 
   registerWorkspaceRoutes(app, { workspaceManager: deps.workspaceManager })
   registerConfigRoutes(app, { configStore: deps.configStore, binaryRegistry: deps.binaryRegistry })
   registerFilesystemRoutes(app, { fileSystemBrowser: deps.fileSystemBrowser })
   registerMetaRoutes(app, { serverMeta: deps.serverMeta })
-  registerEventRoutes(app, { eventBus: deps.eventBus, registerClient: registerSseClient })
+  registerEventRoutes(app, { eventBus: deps.eventBus, registerClient: registerSseClient, logger: sseLogger })
-  registerStorageRoutes(app, { instanceStore: deps.instanceStore })
+  registerStorageRoutes(app, {
+    instanceStore: deps.instanceStore,
+    eventBus: deps.eventBus,
+    workspaceManager: deps.workspaceManager,
+  })
+  registerPluginRoutes(app, { workspaceManager: deps.workspaceManager, eventBus: deps.eventBus, logger: proxyLogger })
+  registerBackgroundProcessRoutes(app, { backgroundProcessManager })
   registerInstanceProxyRoutes(app, { workspaceManager: deps.workspaceManager, logger: proxyLogger })
 
+
   if (deps.uiDevServerUrl) {
     setupDevProxy(app, deps.uiDevServerUrl)
   } else {
@@ -78,7 +132,61 @@ export function createHttpServer(deps: HttpServerDeps) {
 
   return {
     instance: app,
-    start: () => app.listen({ port: deps.port, host: deps.host }),
+    start: async (): Promise<HttpServerStartResult> => {
+      const attemptListen = async (requestedPort: number) => {
+        const addressInfo = await app.listen({ port: requestedPort, host: deps.host })
+        return { addressInfo, requestedPort }
+      }
+
+      const autoPortRequested = deps.port === 0
+      const primaryPort = autoPortRequested ? DEFAULT_HTTP_PORT : deps.port
+
+      const shouldRetryWithEphemeral = (error: unknown) => {
+        if (!autoPortRequested) return false
+        const err = error as NodeJS.ErrnoException | undefined
+        return Boolean(err && err.code === "EADDRINUSE")
+      }
+
+      let listenResult
+
+      try {
+        listenResult = await attemptListen(primaryPort)
+      } catch (error) {
+        if (!shouldRetryWithEphemeral(error)) {
+          throw error
+        }
+        deps.logger.warn({ err: error, port: primaryPort }, "Preferred port unavailable, retrying on ephemeral port")
+        listenResult = await attemptListen(0)
+      }
+
+      let actualPort = listenResult.requestedPort
+
+      if (typeof listenResult.addressInfo === "string") {
+        try {
+          const parsed = new URL(listenResult.addressInfo)
+          actualPort = Number(parsed.port) || listenResult.requestedPort
+        } catch {
+          actualPort = listenResult.requestedPort
+        }
+      } else {
+        const address = app.server.address()
+        if (typeof address === "object" && address) {
+          actualPort = address.port
+        }
+      }
+
+      const displayHost = deps.host === "0.0.0.0" ? "127.0.0.1" : deps.host === "127.0.0.1" ? "localhost" : deps.host
+      const serverUrl = `http://${displayHost}:${actualPort}`
+
+      deps.serverMeta.httpBaseUrl = serverUrl
+      deps.serverMeta.host = deps.host
+      deps.serverMeta.port = actualPort
+      deps.serverMeta.listeningMode = deps.host === "0.0.0.0" ? "all" : "local"
+      deps.logger.info({ port: actualPort, host: deps.host }, "HTTP server listening")
+      console.log(`CodeNomad Server is ready at ${serverUrl}`)
+
+      return { port: actualPort, url: serverUrl, displayHost }
+    },
     stop: () => {
       closeSseClients()
       return app.close()
@@ -153,6 +261,11 @@ async function proxyWorkspaceRequest(args: {
   const search = queryIndex >= 0 ? (request.raw.url ?? "").slice(queryIndex) : ""
   const targetUrl = `http://${INSTANCE_PROXY_HOST}:${port}${normalizedSuffix}${search}`
 
+  logger.debug({ workspaceId, method: request.method, targetUrl }, "Proxying request to instance")
+  if (logger.isLevelEnabled("trace")) {
+    logger.trace({ workspaceId, targetUrl, body: request.body }, "Instance proxy payload")
+  }
+
   return reply.from(targetUrl, {
     onError: (proxyReply, { error }) => {
       logger.error({ err: error, workspaceId, targetUrl }, "Failed to proxy workspace request")

packages/server/src/server/routes/background-processes.ts

@@ -0,0 +1,85 @@
+import { FastifyInstance } from "fastify"
+import { z } from "zod"
+import type { BackgroundProcessManager } from "../../background-processes/manager"
+
+interface RouteDeps {
+  backgroundProcessManager: BackgroundProcessManager
+}
+
+const StartSchema = z.object({
+  title: z.string().trim().min(1),
+  command: z.string().trim().min(1),
+})
+
+const OutputQuerySchema = z.object({
+  method: z.enum(["full", "tail", "head", "grep"]).optional(),
+  mode: z.enum(["full", "tail", "head", "grep"]).optional(),
+  pattern: z.string().optional(),
+  lines: z.coerce.number().int().positive().max(2000).optional(),
+  maxBytes: z.coerce.number().int().positive().optional(),
+})
+
+export function registerBackgroundProcessRoutes(app: FastifyInstance, deps: RouteDeps) {
+  app.get<{ Params: { id: string } }>("/workspaces/:id/plugin/background-processes", async (request) => {
+    const processes = await deps.backgroundProcessManager.list(request.params.id)
+    return { processes }
+  })
+
+  app.post<{ Params: { id: string } }>("/workspaces/:id/plugin/background-processes", async (request, reply) => {
+    const payload = StartSchema.parse(request.body ?? {})
+    const process = await deps.backgroundProcessManager.start(request.params.id, payload.title, payload.command)
+    reply.code(201)
+    return process
+  })
+
+  app.post<{ Params: { id: string; processId: string } }>(
+    "/workspaces/:id/plugin/background-processes/:processId/stop",
+    async (request, reply) => {
+      const process = await deps.backgroundProcessManager.stop(request.params.id, request.params.processId)
+      if (!process) {
+        reply.code(404)
+        return { error: "Process not found" }
+      }
+      return process
+    },
+  )
+
+  app.post<{ Params: { id: string; processId: string } }>(
+    "/workspaces/:id/plugin/background-processes/:processId/terminate",
+    async (request, reply) => {
+      await deps.backgroundProcessManager.terminate(request.params.id, request.params.processId)
+      reply.code(204)
+      return undefined
+    },
+  )
+
+  app.get<{ Params: { id: string; processId: string } }>(
+    "/workspaces/:id/plugin/background-processes/:processId/output",
+    async (request, reply) => {
+      const query = OutputQuerySchema.parse(request.query ?? {})
+      const method = query.method ?? query.mode
+      if (method === "grep" && !query.pattern) {
+        reply.code(400)
+        return { error: "Pattern is required for grep output" }
+      }
+      try {
+        return await deps.backgroundProcessManager.readOutput(request.params.id, request.params.processId, {
+          method,
+          pattern: query.pattern,
+          lines: query.lines,
+          maxBytes: query.maxBytes,
+        })
+      } catch (error) {
+        reply.code(400)
+        return { error: error instanceof Error ? error.message : "Invalid output request" }
+      }
+    },
+  )
+
+  app.get<{ Params: { id: string; processId: string } }>(
+    "/workspaces/:id/plugin/background-processes/:processId/stream",
+    async (request, reply) => {
+      await deps.backgroundProcessManager.streamOutput(request.params.id, request.params.processId, reply)
+    },
+  )
+}

packages/server/src/server/routes/config.ts

@@ -2,7 +2,7 @@ import { FastifyInstance } from "fastify"
 import { z } from "zod"
 import { ConfigStore } from "../../config/store"
 import { BinaryRegistry } from "../../config/binaries"
-import { ConfigFileSchema, ConfigFileUpdateSchema } from "../../config/schema"
+import { ConfigFileSchema } from "../../config/schema"
 
 interface RouteDeps {
   configStore: ConfigStore
@@ -29,13 +29,7 @@ export function registerConfigRoutes(app: FastifyInstance, deps: RouteDeps) {
 
   app.put("/api/config/app", async (request) => {
     const body = ConfigFileSchema.parse(request.body ?? {})
-    deps.configStore.update(body)
+    deps.configStore.replace(body)
-    return deps.configStore.get()
-  })
-
-  app.patch("/api/config/app", async (request) => {
-    const body = ConfigFileUpdateSchema.parse(request.body ?? {})
-    deps.configStore.update(body)
     return deps.configStore.get()
   })
 

packages/server/src/server/routes/events.ts

@@ -1,14 +1,21 @@
 import { FastifyInstance } from "fastify"
 import { EventBus } from "../../events/bus"
 import { WorkspaceEventPayload } from "../../api-types"
+import { Logger } from "../../logger"
 
 interface RouteDeps {
   eventBus: EventBus
   registerClient: (cleanup: () => void) => () => void
+  logger: Logger
 }
 
+let nextClientId = 0
+
 export function registerEventRoutes(app: FastifyInstance, deps: RouteDeps) {
   app.get("/api/events", (request, reply) => {
+    const clientId = ++nextClientId
+    deps.logger.debug({ clientId }, "SSE client connected")
+
     const origin = request.headers.origin ?? "*"
     reply.raw.setHeader("Access-Control-Allow-Origin", origin)
     reply.raw.setHeader("Access-Control-Allow-Credentials", "true")
@@ -19,6 +26,10 @@ export function registerEventRoutes(app: FastifyInstance, deps: RouteDeps) {
     reply.hijack()
 
     const send = (event: WorkspaceEventPayload) => {
+      deps.logger.debug({ clientId, type: event.type }, "SSE event dispatched")
+      if (deps.logger.isLevelEnabled("trace")) {
+        deps.logger.trace({ clientId, event }, "SSE event payload")
+      }
       reply.raw.write(`data: ${JSON.stringify(event)}\n\n`)
     }
 
@@ -34,6 +45,7 @@ export function registerEventRoutes(app: FastifyInstance, deps: RouteDeps) {
       clearInterval(heartbeat)
       unsubscribe()
       reply.raw.end?.()
+      deps.logger.debug({ clientId }, "SSE client disconnected")
     }
 
     const unregister = deps.registerClient(close)

packages/server/src/server/routes/meta.ts

@@ -0,0 +1,104 @@
+import { FastifyInstance } from "fastify"
+import os from "os"
+import { NetworkAddress, ServerMeta } from "../../api-types"
+
+interface RouteDeps {
+  serverMeta: ServerMeta
+}
+
+export function registerMetaRoutes(app: FastifyInstance, deps: RouteDeps) {
+  app.get("/api/meta", async () => buildMetaResponse(deps.serverMeta))
+}
+
+function buildMetaResponse(meta: ServerMeta): ServerMeta {
+  const port = resolvePort(meta)
+  const addresses = port > 0 ? resolveAddresses(port, meta.host) : []
+
+  return {
+    ...meta,
+    port,
+    listeningMode: meta.host === "0.0.0.0" ? "all" : "local",
+    addresses,
+  }
+}
+
+function resolvePort(meta: ServerMeta): number {
+  if (Number.isInteger(meta.port) && meta.port > 0) {
+    return meta.port
+  }
+  try {
+    const parsed = new URL(meta.httpBaseUrl)
+    const port = Number(parsed.port)
+    return Number.isInteger(port) && port > 0 ? port : 0
+  } catch {
+    return 0
+  }
+}
+
+function resolveAddresses(port: number, host: string): NetworkAddress[] {
+  const interfaces = os.networkInterfaces()
+  const seen = new Set<string>()
+  const results: NetworkAddress[] = []
+
+  const addAddress = (ip: string, scope: NetworkAddress["scope"]) => {
+    if (!ip || ip === "0.0.0.0") return
+    const key = `ipv4-${ip}`
+    if (seen.has(key)) return
+    seen.add(key)
+    results.push({ ip, family: "ipv4", scope, url: `http://${ip}:${port}` })
+  }
+
+  const normalizeFamily = (value: string | number) => {
+    if (typeof value === "string") {
+      const lowered = value.toLowerCase()
+      if (lowered === "ipv4") {
+        return "ipv4" as const
+      }
+    }
+    if (value === 4) return "ipv4" as const
+    return null
+  }
+
+  if (host === "0.0.0.0") {
+    // Enumerate system interfaces (IPv4 only)
+    for (const entries of Object.values(interfaces)) {
+      if (!entries) continue
+      for (const entry of entries) {
+        const family = normalizeFamily(entry.family)
+        if (!family) continue
+        if (!entry.address || entry.address === "0.0.0.0") continue
+        const scope: NetworkAddress["scope"] = entry.internal ? "loopback" : "external"
+        addAddress(entry.address, scope)
+      }
+    }
+  }
+
+  // Always include loopback address
+  addAddress("127.0.0.1", "loopback")
+
+  // Include explicitly configured host if it was IPv4
+  if (isIPv4Address(host) && host !== "0.0.0.0") {
+    const isLoopback = host.startsWith("127.")
+    addAddress(host, isLoopback ? "loopback" : "external")
+  }
+
+  const scopeWeight: Record<NetworkAddress["scope"], number> = { external: 0, internal: 1, loopback: 2 }
+
+  return results.sort((a, b) => {
+    const scopeDelta = scopeWeight[a.scope] - scopeWeight[b.scope]
+    if (scopeDelta !== 0) return scopeDelta
+    return a.ip.localeCompare(b.ip)
+  })
+}
+
+function isIPv4Address(value: string | undefined): value is string {
+  if (!value) return false
+  const parts = value.split(".")
+  if (parts.length !== 4) return false
+  return parts.every((part) => {
+    if (part.length === 0 || part.length > 3) return false
+    if (!/^[0-9]+$/.test(part)) return false
+    const num = Number(part)
+    return Number.isInteger(num) && num >= 0 && num <= 255
+  })
+}

packages/server/src/server/routes/plugin.ts

@@ -0,0 +1,75 @@
+import { FastifyInstance } from "fastify"
+import { z } from "zod"
+import type { WorkspaceManager } from "../../workspaces/manager"
+import type { EventBus } from "../../events/bus"
+import type { Logger } from "../../logger"
+import { PluginChannelManager } from "../../plugins/channel"
+import { buildPingEvent, handlePluginEvent } from "../../plugins/handlers"
+
+interface RouteDeps {
+  workspaceManager: WorkspaceManager
+  eventBus: EventBus
+  logger: Logger
+}
+
+const PluginEventSchema = z.object({
+  type: z.string().min(1),
+  properties: z.record(z.unknown()).optional(),
+})
+
+export function registerPluginRoutes(app: FastifyInstance, deps: RouteDeps) {
+  const channel = new PluginChannelManager(deps.logger.child({ component: "plugin-channel" }))
+
+  app.get<{ Params: { id: string } }>("/workspaces/:id/plugin/events", (request, reply) => {
+    const workspace = deps.workspaceManager.get(request.params.id)
+    if (!workspace) {
+      reply.code(404).send({ error: "Workspace not found" })
+      return
+    }
+
+    reply.raw.setHeader("Content-Type", "text/event-stream")
+    reply.raw.setHeader("Cache-Control", "no-cache")
+    reply.raw.setHeader("Connection", "keep-alive")
+    reply.raw.flushHeaders?.()
+    reply.hijack()
+
+    const registration = channel.register(request.params.id, reply)
+
+    const heartbeat = setInterval(() => {
+      channel.send(request.params.id, buildPingEvent())
+    }, 15000)
+
+    const close = () => {
+      clearInterval(heartbeat)
+      registration.close()
+      reply.raw.end?.()
+    }
+
+    request.raw.on("close", close)
+    request.raw.on("error", close)
+  })
+
+  const handleWildcard = async (request: any, reply: any) => {
+    const workspaceId = request.params.id as string
+    const workspace = deps.workspaceManager.get(workspaceId)
+    if (!workspace) {
+      reply.code(404).send({ error: "Workspace not found" })
+      return
+    }
+
+    const suffix = (request.params["*"] as string | undefined) ?? ""
+    const normalized = suffix.replace(/^\/+/, "")
+
+    if (normalized === "event" && request.method === "POST") {
+      const parsed = PluginEventSchema.parse(request.body ?? {})
+      handlePluginEvent(workspaceId, parsed, { workspaceManager: deps.workspaceManager, eventBus: deps.eventBus, logger: deps.logger })
+      reply.code(204).send()
+      return
+    }
+
+    reply.code(404).send({ error: "Unknown plugin endpoint" })
+  }
+
+  app.all("/workspaces/:id/plugin/*", handleWildcard)
+  app.all("/workspaces/:id/plugin", handleWildcard)
+}

packages/server/src/server/routes/storage.ts

@@ -1,19 +1,37 @@
 import { FastifyInstance } from "fastify"
 import { z } from "zod"
 import { InstanceStore } from "../../storage/instance-store"
+import { EventBus } from "../../events/bus"
+import { ModelPreferenceSchema } from "../../config/schema"
+import type { InstanceData } from "../../api-types"
+import { WorkspaceManager } from "../../workspaces/manager"
 
 interface RouteDeps {
   instanceStore: InstanceStore
+  eventBus: EventBus
+  workspaceManager: WorkspaceManager
 }
 
 const InstanceDataSchema = z.object({
   messageHistory: z.array(z.string()).default([]),
+  agentModelSelections: z.record(z.string(), ModelPreferenceSchema).default({}),
 })
 
+const EMPTY_INSTANCE_DATA: InstanceData = {
+  messageHistory: [],
+  agentModelSelections: {},
+}
+
 export function registerStorageRoutes(app: FastifyInstance, deps: RouteDeps) {
+  const resolveStorageKey = (instanceId: string): string => {
+    const workspace = deps.workspaceManager.get(instanceId)
+    return workspace?.path ?? instanceId
+  }
+
   app.get<{ Params: { id: string } }>("/api/storage/instances/:id", async (request, reply) => {
     try {
-      const data = await deps.instanceStore.read(request.params.id)
+      const storageId = resolveStorageKey(request.params.id)
+      const data = await deps.instanceStore.read(storageId)
       return data
     } catch (error) {
       reply.code(500)
@@ -24,7 +42,9 @@ export function registerStorageRoutes(app: FastifyInstance, deps: RouteDeps) {
   app.put<{ Params: { id: string } }>("/api/storage/instances/:id", async (request, reply) => {
     try {
       const body = InstanceDataSchema.parse(request.body ?? {})
-      await deps.instanceStore.write(request.params.id, body)
+      const storageId = resolveStorageKey(request.params.id)
+      await deps.instanceStore.write(storageId, body)
+      deps.eventBus.publish({ type: "instance.dataChanged", instanceId: request.params.id, data: body })
       reply.code(204)
     } catch (error) {
       reply.code(400)
@@ -34,7 +54,9 @@ export function registerStorageRoutes(app: FastifyInstance, deps: RouteDeps) {
 
   app.delete<{ Params: { id: string } }>("/api/storage/instances/:id", async (request, reply) => {
     try {
-      await deps.instanceStore.delete(request.params.id)
+      const storageId = resolveStorageKey(request.params.id)
+      await deps.instanceStore.delete(storageId)
+      deps.eventBus.publish({ type: "instance.dataChanged", instanceId: request.params.id, data: EMPTY_INSTANCE_DATA })
       reply.code(204)
     } catch (error) {
       reply.code(500)

packages/server/src/server/routes/workspaces.ts

@@ -19,16 +19,32 @@ const WorkspaceFileContentQuerySchema = z.object({
   path: z.string(),
 })
 
+const WorkspaceFileSearchQuerySchema = z.object({
+  q: z.string().trim().min(1, "Query is required"),
+  limit: z.coerce.number().int().positive().max(200).optional(),
+  type: z.enum(["all", "file", "directory"]).optional(),
+  refresh: z
+    .string()
+    .optional()
+    .transform((value) => (value === undefined ? undefined : value === "true")),
+})
+
 export function registerWorkspaceRoutes(app: FastifyInstance, deps: RouteDeps) {
   app.get("/api/workspaces", async () => {
     return deps.workspaceManager.list()
   })
 
   app.post("/api/workspaces", async (request, reply) => {
+    try {
       const body = WorkspaceCreateSchema.parse(request.body ?? {})
       const workspace = await deps.workspaceManager.create(body.path, body.name)
       reply.code(201)
       return workspace
+    } catch (error) {
+      request.log.error({ err: error }, "Failed to create workspace")
+      const message = error instanceof Error ? error.message : "Failed to create workspace"
+      reply.code(400).type("text/plain").send(message)
+    }
   })
 
   app.get<{ Params: { id: string } }>("/api/workspaces/:id", async (request, reply) => {
@@ -57,6 +73,22 @@ export function registerWorkspaceRoutes(app: FastifyInstance, deps: RouteDeps) {
     }
   })
 
+  app.get<{
+    Params: { id: string }
+    Querystring: { q?: string; limit?: string; type?: "all" | "file" | "directory"; refresh?: string }
+  }>("/api/workspaces/:id/files/search", async (request, reply) => {
+    try {
+      const query = WorkspaceFileSearchQuerySchema.parse(request.query ?? {})
+      return deps.workspaceManager.searchFiles(request.params.id, query.q, {
+        limit: query.limit,
+        type: query.type,
+        refresh: query.refresh,
+      })
+    } catch (error) {
+      return handleWorkspaceError(error, reply)
+    }
+  })
+
   app.get<{
     Params: { id: string }
     Querystring: { path?: string }
@@ -70,6 +102,7 @@ export function registerWorkspaceRoutes(app: FastifyInstance, deps: RouteDeps) {
   })
 }
 
+
 function handleWorkspaceError(error: unknown, reply: FastifyReply) {
   if (error instanceof Error && error.message === "Workspace not found") {
     reply.code(404)

packages/server/src/storage/instance-store.ts

@@ -6,6 +6,7 @@ import type { InstanceData } from "../api-types"
 
 const DEFAULT_INSTANCE_DATA: InstanceData = {
   messageHistory: [],
+  agentModelSelections: {},
 }
 
 export class InstanceStore {

packages/server/src/workspaces/instance-events.ts

@@ -0,0 +1,195 @@
+import { Agent, fetch } from "undici"
+import { Agent as UndiciAgent } from "undici"
+import { EventBus } from "../events/bus"
+import { Logger } from "../logger"
+import { WorkspaceManager } from "./manager"
+import { InstanceStreamEvent, InstanceStreamStatus } from "../api-types"
+
+const INSTANCE_HOST = "127.0.0.1"
+const STREAM_AGENT = new UndiciAgent({ bodyTimeout: 0, headersTimeout: 0 })
+const RECONNECT_DELAY_MS = 1000
+
+interface InstanceEventBridgeOptions {
+  workspaceManager: WorkspaceManager
+  eventBus: EventBus
+  logger: Logger
+}
+
+interface ActiveStream {
+  controller: AbortController
+  task: Promise<void>
+}
+
+export class InstanceEventBridge {
+  private readonly streams = new Map<string, ActiveStream>()
+
+  constructor(private readonly options: InstanceEventBridgeOptions) {
+    const bus = this.options.eventBus
+    bus.on("workspace.started", (event) => this.startStream(event.workspace.id))
+    bus.on("workspace.stopped", (event) => this.stopStream(event.workspaceId, "workspace stopped"))
+    bus.on("workspace.error", (event) => this.stopStream(event.workspace.id, "workspace error"))
+  }
+
+  shutdown() {
+    for (const [id, active] of this.streams) {
+      active.controller.abort()
+      this.publishStatus(id, "disconnected")
+    }
+    this.streams.clear()
+  }
+
+  private startStream(workspaceId: string) {
+    if (this.streams.has(workspaceId)) {
+      return
+    }
+
+    const controller = new AbortController()
+    const task = this.runStream(workspaceId, controller.signal)
+      .catch((error) => {
+        if (!controller.signal.aborted) {
+          this.options.logger.warn({ workspaceId, err: error }, "Instance event stream failed")
+          this.publishStatus(workspaceId, "error", error instanceof Error ? error.message : String(error))
+        }
+      })
+      .finally(() => {
+        const active = this.streams.get(workspaceId)
+        if (active?.controller === controller) {
+          this.streams.delete(workspaceId)
+        }
+      })
+
+    this.streams.set(workspaceId, { controller, task })
+  }
+
+  private stopStream(workspaceId: string, reason?: string) {
+    const active = this.streams.get(workspaceId)
+    if (!active) {
+      return
+    }
+    active.controller.abort()
+    this.streams.delete(workspaceId)
+    this.publishStatus(workspaceId, "disconnected", reason)
+  }
+
+  private async runStream(workspaceId: string, signal: AbortSignal) {
+    while (!signal.aborted) {
+      const port = this.options.workspaceManager.getInstancePort(workspaceId)
+      if (!port) {
+        await this.delay(RECONNECT_DELAY_MS, signal)
+        continue
+      }
+
+      this.publishStatus(workspaceId, "connecting")
+
+      try {
+        await this.consumeStream(workspaceId, port, signal)
+      } catch (error) {
+        if (signal.aborted) {
+          break
+        }
+        this.options.logger.warn({ workspaceId, err: error }, "Instance event stream disconnected")
+        this.publishStatus(workspaceId, "error", error instanceof Error ? error.message : String(error))
+        await this.delay(RECONNECT_DELAY_MS, signal)
+      }
+    }
+  }
+
+  private async consumeStream(workspaceId: string, port: number, signal: AbortSignal) {
+    const url = `http://${INSTANCE_HOST}:${port}/event`
+    const response = await fetch(url, {
+      headers: { Accept: "text/event-stream" },
+      signal,
+      dispatcher: STREAM_AGENT,
+    })
+
+    if (!response.ok || !response.body) {
+      throw new Error(`Instance event stream unavailable (${response.status})`)
+    }
+
+    this.publishStatus(workspaceId, "connected")
+
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ""
+
+    while (!signal.aborted) {
+      const { done, value } = await reader.read()
+      if (done || !value) {
+        break
+      }
+      buffer += decoder.decode(value, { stream: true })
+      buffer = this.flushEvents(buffer, workspaceId)
+    }
+  }
+
+  private flushEvents(buffer: string, workspaceId: string) {
+    let separatorIndex = buffer.indexOf("\n\n")
+
+    while (separatorIndex >= 0) {
+      const chunk = buffer.slice(0, separatorIndex)
+      buffer = buffer.slice(separatorIndex + 2)
+      this.processChunk(chunk, workspaceId)
+      separatorIndex = buffer.indexOf("\n\n")
+    }
+
+    return buffer
+  }
+
+  private processChunk(chunk: string, workspaceId: string) {
+    const lines = chunk.split(/\r?\n/)
+    const dataLines: string[] = []
+
+    for (const line of lines) {
+      if (line.startsWith(":")) {
+        continue
+      }
+      if (line.startsWith("data:")) {
+        dataLines.push(line.slice(5).trimStart())
+      }
+    }
+
+    if (dataLines.length === 0) {
+      return
+    }
+
+    const payload = dataLines.join("\n").trim()
+    if (!payload) {
+      return
+    }
+
+    try {
+      const event = JSON.parse(payload) as InstanceStreamEvent
+      this.options.logger.debug({ workspaceId, eventType: event.type }, "Instance SSE event received")
+      if (this.options.logger.isLevelEnabled("trace")) {
+        this.options.logger.trace({ workspaceId, event }, "Instance SSE event payload")
+      }
+      this.options.eventBus.publish({ type: "instance.event", instanceId: workspaceId, event })
+    } catch (error) {
+      this.options.logger.warn({ workspaceId, chunk: payload, err: error }, "Failed to parse instance SSE payload")
+    }
+  }
+
+  private publishStatus(instanceId: string, status: InstanceStreamStatus, reason?: string) {
+    this.options.logger.debug({ instanceId, status, reason }, "Instance SSE status updated")
+    this.options.eventBus.publish({ type: "instance.eventStatus", instanceId, status, reason })
+  }
+
+  private delay(duration: number, signal: AbortSignal) {
+    if (duration <= 0) {
+      return Promise.resolve()
+    }
+    return new Promise<void>((resolve) => {
+      const timeout = setTimeout(() => {
+        signal.removeEventListener("abort", onAbort)
+        resolve()
+      }, duration)
+
+      const onAbort = () => {
+        clearTimeout(timeout)
+        resolve()
+      }
+
+      signal.addEventListener("abort", onAbort, { once: true })
+    })
+  }
+}

packages/server/src/workspaces/manager.ts

@@ -0,0 +1,427 @@
+import path from "path"
+import { spawnSync } from "child_process"
+import { connect } from "net"
+import { EventBus } from "../events/bus"
+import { ConfigStore } from "../config/store"
+import { BinaryRegistry } from "../config/binaries"
+import { FileSystemBrowser } from "../filesystem/browser"
+import { searchWorkspaceFiles, WorkspaceFileSearchOptions } from "../filesystem/search"
+import { clearWorkspaceSearchCache } from "../filesystem/search-cache"
+import { WorkspaceDescriptor, WorkspaceFileResponse, FileSystemEntry } from "../api-types"
+import { WorkspaceRuntime, ProcessExitInfo } from "./runtime"
+import { Logger } from "../logger"
+import { getOpencodeConfigDir } from "../opencode-config.js"
+
+const STARTUP_STABILITY_DELAY_MS = 1500
+
+interface WorkspaceManagerOptions {
+  rootDir: string
+  configStore: ConfigStore
+  binaryRegistry: BinaryRegistry
+  eventBus: EventBus
+  logger: Logger
+  getServerBaseUrl: () => string
+}
+
+interface WorkspaceRecord extends WorkspaceDescriptor {}
+
+export class WorkspaceManager {
+  private readonly workspaces = new Map<string, WorkspaceRecord>()
+  private readonly runtime: WorkspaceRuntime
+  private readonly opencodeConfigDir: string
+
+  constructor(private readonly options: WorkspaceManagerOptions) {
+    this.runtime = new WorkspaceRuntime(this.options.eventBus, this.options.logger)
+    this.opencodeConfigDir = getOpencodeConfigDir()
+  }
+
+  list(): WorkspaceDescriptor[] {
+    return Array.from(this.workspaces.values())
+  }
+
+  get(id: string): WorkspaceDescriptor | undefined {
+    return this.workspaces.get(id)
+  }
+
+  getInstancePort(id: string): number | undefined {
+    return this.workspaces.get(id)?.port
+  }
+
+  listFiles(workspaceId: string, relativePath = "."): FileSystemEntry[] {
+    const workspace = this.requireWorkspace(workspaceId)
+    const browser = new FileSystemBrowser({ rootDir: workspace.path })
+    return browser.list(relativePath)
+  }
+
+  searchFiles(workspaceId: string, query: string, options?: WorkspaceFileSearchOptions): FileSystemEntry[] {
+    const workspace = this.requireWorkspace(workspaceId)
+    return searchWorkspaceFiles(workspace.path, query, options)
+  }
+
+  readFile(workspaceId: string, relativePath: string): WorkspaceFileResponse {
+    const workspace = this.requireWorkspace(workspaceId)
+    const browser = new FileSystemBrowser({ rootDir: workspace.path })
+    const contents = browser.readFile(relativePath)
+    return {
+      workspaceId,
+      relativePath,
+      contents,
+    }
+  }
+
+  async create(folder: string, name?: string): Promise<WorkspaceDescriptor> {
+ 
+    const id = `${Date.now().toString(36)}`
+    const binary = this.options.binaryRegistry.resolveDefault()
+    const resolvedBinaryPath = this.resolveBinaryPath(binary.path)
+    const workspacePath = path.isAbsolute(folder) ? folder : path.resolve(this.options.rootDir, folder)
+    clearWorkspaceSearchCache(workspacePath)
+
+    this.options.logger.info({ workspaceId: id, folder: workspacePath, binary: resolvedBinaryPath }, "Creating workspace")
+
+    const proxyPath = `/workspaces/${id}/instance`
+
+
+    const descriptor: WorkspaceRecord = {
+      id,
+      path: workspacePath,
+      name,
+      status: "starting",
+      proxyPath,
+      binaryId: resolvedBinaryPath,
+      binaryLabel: binary.label,
+      binaryVersion: binary.version,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    }
+
+    if (!descriptor.binaryVersion) {
+      descriptor.binaryVersion = this.detectBinaryVersion(resolvedBinaryPath)
+    }
+
+    this.workspaces.set(id, descriptor)
+
+
+    this.options.eventBus.publish({ type: "workspace.created", workspace: descriptor })
+
+    const preferences = this.options.configStore.get().preferences ?? {}
+    const userEnvironment = preferences.environmentVariables ?? {}
+    const environment = {
+      ...userEnvironment,
+      OPENCODE_CONFIG_DIR: this.opencodeConfigDir,
+      CODENOMAD_INSTANCE_ID: id,
+      CODENOMAD_BASE_URL: this.options.getServerBaseUrl(),
+    }
+
+    try {
+      const { pid, port, exitPromise, getLastOutput } = await this.runtime.launch({
+        workspaceId: id,
+        folder: workspacePath,
+        binaryPath: resolvedBinaryPath,
+        environment,
+        onExit: (info) => this.handleProcessExit(info.workspaceId, info),
+      })
+
+      await this.waitForWorkspaceReadiness({ workspaceId: id, port, exitPromise, getLastOutput })
+
+      descriptor.pid = pid
+      descriptor.port = port
+      descriptor.status = "ready"
+      descriptor.updatedAt = new Date().toISOString()
+      this.options.eventBus.publish({ type: "workspace.started", workspace: descriptor })
+      this.options.logger.info({ workspaceId: id, port }, "Workspace ready")
+      return descriptor
+    } catch (error) {
+      descriptor.status = "error"
+      descriptor.error = error instanceof Error ? error.message : String(error)
+      descriptor.updatedAt = new Date().toISOString()
+      this.options.eventBus.publish({ type: "workspace.error", workspace: descriptor })
+      this.options.logger.error({ workspaceId: id, err: error }, "Workspace failed to start")
+      throw error
+    }
+  }
+
+  async delete(id: string): Promise<WorkspaceDescriptor | undefined> {
+    const workspace = this.workspaces.get(id)
+    if (!workspace) return undefined
+
+    this.options.logger.info({ workspaceId: id }, "Stopping workspace")
+    const wasRunning = Boolean(workspace.pid)
+    if (wasRunning) {
+      await this.runtime.stop(id).catch((error) => {
+        this.options.logger.warn({ workspaceId: id, err: error }, "Failed to stop workspace process cleanly")
+      })
+    }
+
+    this.workspaces.delete(id)
+    clearWorkspaceSearchCache(workspace.path)
+    if (!wasRunning) {
+      this.options.eventBus.publish({ type: "workspace.stopped", workspaceId: id })
+    }
+    return workspace
+  }
+
+  async shutdown() {
+    this.options.logger.info("Shutting down all workspaces")
+    for (const [id, workspace] of this.workspaces) {
+      if (workspace.pid) {
+        this.options.logger.info({ workspaceId: id }, "Stopping workspace during shutdown")
+        await this.runtime.stop(id).catch((error) => {
+          this.options.logger.error({ workspaceId: id, err: error }, "Failed to stop workspace during shutdown")
+        })
+      } else {
+        this.options.logger.debug({ workspaceId: id }, "Workspace already stopped")
+      }
+    }
+    this.workspaces.clear()
+    this.options.logger.info("All workspaces cleared")
+  }
+
+  private requireWorkspace(id: string): WorkspaceRecord {
+    const workspace = this.workspaces.get(id)
+    if (!workspace) {
+      throw new Error("Workspace not found")
+    }
+    return workspace
+  }
+
+  private resolveBinaryPath(identifier: string): string {
+    if (!identifier) {
+      return identifier
+    }
+
+    const looksLikePath = identifier.includes("/") || identifier.includes("\\") || identifier.startsWith(".")
+    if (path.isAbsolute(identifier) || looksLikePath) {
+      return identifier
+    }
+
+    const locator = process.platform === "win32" ? "where" : "which"
+
+    try {
+      const result = spawnSync(locator, [identifier], { encoding: "utf8" })
+      if (result.status === 0 && result.stdout) {
+        const resolved = result.stdout
+          .split(/\r?\n/)
+          .map((line) => line.trim())
+          .find((line) => line.length > 0)
+
+        if (resolved) {
+          this.options.logger.debug({ identifier, resolved }, "Resolved binary path from system PATH")
+          return resolved
+        }
+      } else if (result.error) {
+        this.options.logger.warn({ identifier, err: result.error }, "Failed to resolve binary path via locator command")
+      }
+    } catch (error) {
+      this.options.logger.warn({ identifier, err: error }, "Failed to resolve binary path from system PATH")
+    }
+
+    return identifier
+  }
+
+  private detectBinaryVersion(resolvedPath: string): string | undefined {
+    if (!resolvedPath) {
+      return undefined
+    }
+
+    try {
+      const result = spawnSync(resolvedPath, ["--version"], { encoding: "utf8" })
+      if (result.status === 0 && result.stdout) {
+        const line = result.stdout.split(/\r?\n/).find((entry) => entry.trim().length > 0)
+        if (line) {
+          const normalized = line.trim()
+          const versionMatch = normalized.match(/([0-9]+\.[0-9]+\.[0-9A-Za-z.-]+)/)
+          if (versionMatch) {
+            const version = versionMatch[1]
+            this.options.logger.debug({ binary: resolvedPath, version }, "Detected binary version")
+            return version
+          }
+          this.options.logger.debug({ binary: resolvedPath, reported: normalized }, "Binary reported version string")
+          return normalized
+        }
+      } else if (result.error) {
+        this.options.logger.warn({ binary: resolvedPath, err: result.error }, "Failed to read binary version")
+      }
+    } catch (error) {
+      this.options.logger.warn({ binary: resolvedPath, err: error }, "Failed to detect binary version")
+    }
+
+    return undefined
+  }
+
+  private async waitForWorkspaceReadiness(params: {
+    workspaceId: string
+    port: number
+    exitPromise: Promise<ProcessExitInfo>
+    getLastOutput: () => string
+  }) {
+
+    await Promise.race([
+      this.waitForPortAvailability(params.port),
+      params.exitPromise.then((info) => {
+        throw this.buildStartupError(
+          params.workspaceId,
+          "exited before becoming ready",
+          info,
+          params.getLastOutput(),
+        )
+      }),
+    ])
+
+    await this.waitForInstanceHealth(params)
+
+    await Promise.race([
+      this.delay(STARTUP_STABILITY_DELAY_MS),
+      params.exitPromise.then((info) => {
+        throw this.buildStartupError(
+          params.workspaceId,
+          "exited shortly after start",
+          info,
+          params.getLastOutput(),
+        )
+      }),
+    ])
+  }
+
+  private async waitForInstanceHealth(params: {
+    workspaceId: string
+    port: number
+    exitPromise: Promise<ProcessExitInfo>
+    getLastOutput: () => string
+  }) {
+    const probeResult = await Promise.race([
+      this.probeInstance(params.workspaceId, params.port),
+      params.exitPromise.then((info) => {
+        throw this.buildStartupError(
+          params.workspaceId,
+          "exited during health checks",
+          info,
+          params.getLastOutput(),
+        )
+      }),
+    ])
+
+    if (probeResult.ok) {
+      return
+    }
+
+    const latestOutput = params.getLastOutput().trim()
+    if (latestOutput) {
+      throw new Error(latestOutput)
+    }
+    const reason = probeResult.reason ?? "Health check failed"
+    throw new Error(`Workspace ${params.workspaceId} failed health check: ${reason}.`)
+  }
+
+  private async probeInstance(workspaceId: string, port: number): Promise<{ ok: boolean; reason?: string }> {
+    const url = `http://127.0.0.1:${port}/project/current`
+
+    try {
+      const response = await fetch(url)
+      if (!response.ok) {
+        const reason = `health probe returned HTTP ${response.status}`
+        this.options.logger.debug({ workspaceId, status: response.status }, "Health probe returned server error")
+        return { ok: false, reason }
+      }
+      return { ok: true }
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      this.options.logger.debug({ workspaceId, err: error }, "Health probe failed")
+      return { ok: false, reason }
+    }
+  }
+
+  private buildStartupError(
+    workspaceId: string,
+    phase: string,
+    exitInfo: ProcessExitInfo,
+    lastOutput: string,
+  ): Error {
+    const exitDetails = this.describeExit(exitInfo)
+    const trimmedOutput = lastOutput.trim()
+    const outputDetails = trimmedOutput ? ` Last output: ${trimmedOutput}` : ""
+    return new Error(`Workspace ${workspaceId} ${phase} (${exitDetails}).${outputDetails}`)
+  }
+
+  private waitForPortAvailability(port: number, timeoutMs = 5000): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const deadline = Date.now() + timeoutMs
+      let settled = false
+      let retryTimer: NodeJS.Timeout | null = null
+
+      const cleanup = () => {
+        settled = true
+        if (retryTimer) {
+          clearTimeout(retryTimer)
+          retryTimer = null
+        }
+      }
+
+      const tryConnect = () => {
+        if (settled) {
+          return
+        }
+        const socket = connect({ port, host: "127.0.0.1" }, () => {
+          cleanup()
+          socket.end()
+          resolve()
+        })
+        socket.once("error", () => {
+          socket.destroy()
+          if (settled) {
+            return
+          }
+          if (Date.now() >= deadline) {
+            cleanup()
+            reject(new Error(`Workspace port ${port} did not become ready within ${timeoutMs}ms`))
+          } else {
+            retryTimer = setTimeout(() => {
+              retryTimer = null
+              tryConnect()
+            }, 100)
+          }
+        })
+      }
+
+      tryConnect()
+    })
+  }
+
+  private delay(durationMs: number): Promise<void> {
+    if (durationMs <= 0) {
+      return Promise.resolve()
+    }
+    return new Promise((resolve) => setTimeout(resolve, durationMs))
+  }
+
+  private describeExit(info: ProcessExitInfo): string {
+    if (info.signal) {
+      return `signal ${info.signal}`
+    }
+    if (info.code !== null) {
+      return `code ${info.code}`
+    }
+    return "unknown reason"
+  }
+
+  private handleProcessExit(workspaceId: string, info: { code: number | null; requested: boolean }) {
+    const workspace = this.workspaces.get(workspaceId)
+    if (!workspace) return
+
+    this.options.logger.info({ workspaceId, ...info }, "Workspace process exited")
+
+    workspace.pid = undefined
+    workspace.port = undefined
+    workspace.updatedAt = new Date().toISOString()
+
+    if (info.requested || info.code === 0) {
+      workspace.status = "stopped"
+      workspace.error = undefined
+      this.options.eventBus.publish({ type: "workspace.stopped", workspaceId })
+    } else {
+      workspace.status = "error"
+      workspace.error = `Process exited with code ${info.code}`
+      this.options.eventBus.publish({ type: "workspace.error", workspace })
+    }
+  }
+}

packages/server/src/workspaces/runtime.ts

@@ -13,7 +13,7 @@ interface LaunchOptions {
   onExit?: (info: ProcessExitInfo) => void
 }
 
-interface ProcessExitInfo {
+export interface ProcessExitInfo {
   workspaceId: string
   code: number | null
   signal: NodeJS.Signals | null
@@ -30,14 +30,47 @@ export class WorkspaceRuntime {
 
   constructor(private readonly eventBus: EventBus, private readonly logger: Logger) {}
 
-  async launch(options: LaunchOptions): Promise<{ pid: number; port: number }> {
+  async launch(options: LaunchOptions): Promise<{ pid: number; port: number; exitPromise: Promise<ProcessExitInfo>; getLastOutput: () => string }> {
     this.validateFolder(options.folder)
 
     const args = ["serve", "--port", "0", "--print-logs", "--log-level", "DEBUG"]
     const env = { ...process.env, ...(options.environment ?? {}) }
 
+    let exitResolve: ((info: ProcessExitInfo) => void) | null = null
+    const exitPromise = new Promise<ProcessExitInfo>((resolveExit) => {
+      exitResolve = resolveExit
+    })
+
+    // Store recent output for debugging - keep last 50 lines from each stream
+    const MAX_OUTPUT_LINES = 50
+    const recentStdout: string[] = []
+    const recentStderr: string[] = []
+    const getLastOutput = () => {
+      const combined: string[] = []
+      if (recentStderr.length > 0) {
+        combined.push("Error Stream")
+        combined.push(...recentStderr.slice(-10))
+      }
+      if (recentStdout.length > 0) {
+        combined.push("Output Stream")
+        combined.push(...recentStdout.slice(-10))
+      }
+      return combined.join("\n")
+    }
+
     return new Promise((resolve, reject) => {
-      this.logger.info({ workspaceId: options.workspaceId, folder: options.folder }, "Launching OpenCode process")
+      const commandLine = [options.binaryPath, ...args].join(" ")
+      this.logger.info(
+        {
+          workspaceId: options.workspaceId,
+          folder: options.folder,
+          binary: options.binaryPath,
+          args,
+          commandLine,
+          env,
+        },
+        "Launching OpenCode process",
+      )
       const child = spawn(options.binaryPath, args, {
         cwd: options.folder,
         env,
@@ -80,11 +113,22 @@ export class WorkspaceRuntime {
         cleanupStreams()
         child.removeListener("error", handleError)
         child.removeListener("exit", handleExit)
+        const exitInfo: ProcessExitInfo = {
+          workspaceId: options.workspaceId,
+          code,
+          signal,
+          requested: managed.requestedStop,
+        }
+        if (exitResolve) {
+          exitResolve(exitInfo)
+          exitResolve = null
+        }
         if (!portFound) {
-          const reason = stderrBuffer || `Process exited with code ${code}`
+          const recentOutput = getLastOutput().trim()
+          const reason = recentOutput || stderrBuffer || `Process exited with code ${code}`
           reject(new Error(reason))
         } else {
-          options.onExit?.({ workspaceId: options.workspaceId, code, signal, requested: managed.requestedStop })
+          options.onExit?.(exitInfo)
         }
       }
 
@@ -93,6 +137,10 @@ export class WorkspaceRuntime {
         child.removeListener("exit", handleExit)
         this.processes.delete(options.workspaceId)
         this.logger.error({ workspaceId: options.workspaceId, err: error }, "Workspace runtime error")
+        if (exitResolve) {
+          exitResolve({ workspaceId: options.workspaceId, code: null, signal: null, requested: managed.requestedStop })
+          exitResolve = null
+        }
         reject(error)
       }
 
@@ -106,18 +154,25 @@ export class WorkspaceRuntime {
         stdoutBuffer = lines.pop() ?? ""
 
         for (const line of lines) {
-          if (!line.trim()) continue
+          const trimmed = line.trim()
+          if (!trimmed) continue
+
+          recentStdout.push(trimmed)
+          if (recentStdout.length > MAX_OUTPUT_LINES) {
+            recentStdout.shift()
+          }
+
           this.emitLog(options.workspaceId, "info", line)
 
           if (!portFound) {
             const portMatch = line.match(/opencode server listening on http:\/\/.+:(\d+)/i)
             if (portMatch) {
               portFound = true
-              cleanupStreams()
+              stopWarningTimer()
               child.removeListener("error", handleError)
               const port = parseInt(portMatch[1], 10)
               this.logger.info({ workspaceId: options.workspaceId, port }, "Workspace runtime allocated port")
-              resolve({ pid: child.pid!, port })
+              resolve({ pid: child.pid!, port, exitPromise, getLastOutput })
             }
           }
         }
@@ -130,7 +185,14 @@ export class WorkspaceRuntime {
         stderrBuffer = lines.pop() ?? ""
 
         for (const line of lines) {
-          if (!line.trim()) continue
+          const trimmed = line.trim()
+          if (!trimmed) continue
+
+          recentStderr.push(trimmed)
+          if (recentStderr.length > MAX_OUTPUT_LINES) {
+            recentStderr.shift()
+          }
+
           this.emitLog(options.workspaceId, "error", line)
         }
       })

packages/tauri-app/.gitignore

@@ -0,0 +1,7 @@
+src-tauri/target
+src-tauri/Cargo.lock
+src-tauri/resources/
+target
+node_modules
+dist
+.DS_Store

packages/tauri-app/Cargo.toml

@@ -0,0 +1,3 @@
+[workspace]
+members = ["src-tauri"]
+resolver = "2"

packages/tauri-app/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@codenomad/tauri-app",
+  "version": "0.5.1",
+  "private": true,
+  "scripts": {
+    "dev": "tauri dev",
+    "dev:ui": "npm run dev --workspace @codenomad/ui",
+    "dev:prep": "node ./scripts/dev-prep.js",
+    "dev:bootstrap": "npm run dev:prep && npm run dev:ui",
+    "prebuild": "node ./scripts/prebuild.js",
+    "bundle:server": "npm run prebuild",
+    "build": "tauri build"
+  },
+  "devDependencies": {
+    "@tauri-apps/cli": "^2.9.4"
+  }
+}

packages/tauri-app/scripts/dev-prep.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+const fs = require("fs")
+const path = require("path")
+const { execSync } = require("child_process")
+
+const root = path.resolve(__dirname, "..")
+const workspaceRoot = path.resolve(root, "..", "..")
+const uiRoot = path.resolve(root, "..", "ui")
+const uiDist = path.resolve(uiRoot, "src", "renderer", "dist")
+const uiLoadingDest = path.resolve(root, "src-tauri", "resources", "ui-loading")
+
+function ensureUiBuild() {
+  const loadingHtml = path.join(uiDist, "loading.html")
+  if (fs.existsSync(loadingHtml)) {
+    return
+  }
+
+  console.log("[dev-prep] UI loader build missing; running workspace build…")
+  execSync("npm --workspace @codenomad/ui run build", {
+    cwd: workspaceRoot,
+    stdio: "inherit",
+  })
+
+  if (!fs.existsSync(loadingHtml)) {
+    throw new Error("[dev-prep] failed to produce loading.html after UI build")
+  }
+}
+
+function copyUiLoadingAssets() {
+  const loadingSource = path.join(uiDist, "loading.html")
+  const assetsSource = path.join(uiDist, "assets")
+
+  fs.rmSync(uiLoadingDest, { recursive: true, force: true })
+  fs.mkdirSync(uiLoadingDest, { recursive: true })
+
+  fs.copyFileSync(loadingSource, path.join(uiLoadingDest, "loading.html"))
+  if (fs.existsSync(assetsSource)) {
+    fs.cpSync(assetsSource, path.join(uiLoadingDest, "assets"), { recursive: true })
+  }
+
+  console.log(`[dev-prep] copied loader bundle from ${uiDist}`)
+}
+
+ensureUiBuild()
+copyUiLoadingAssets()

packages/tauri-app/scripts/prebuild.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+const fs = require("fs")
+const path = require("path")
+const { execSync } = require("child_process")
+
+const root = path.resolve(__dirname, "..")
+const workspaceRoot = path.resolve(root, "..", "..")
+const serverRoot = path.resolve(root, "..", "server")
+const uiRoot = path.resolve(root, "..", "ui")
+const uiDist = path.resolve(uiRoot, "src", "renderer", "dist")
+const serverDest = path.resolve(root, "src-tauri", "resources", "server")
+const uiLoadingDest = path.resolve(root, "src-tauri", "resources", "ui-loading")
+
+const sources = ["dist", "public", "node_modules", "package.json"]
+
+const serverInstallCommand =
+  "npm install --omit=dev --ignore-scripts --workspaces=false --package-lock=false --install-strategy=shallow --fund=false --audit=false"
+const serverDevInstallCommand =
+  "npm install --workspace @neuralnomads/codenomad --include-workspace-root=false --install-strategy=nested --fund=false --audit=false"
+const uiDevInstallCommand =
+  "npm install --workspace @codenomad/ui --include-workspace-root=false --install-strategy=nested --fund=false --audit=false"
+
+const envWithRootBin = {
+  ...process.env,
+  PATH: `${path.join(workspaceRoot, "node_modules/.bin")}:${process.env.PATH}`,
+}
+
+const braceExpansionPath = path.join(
+  serverRoot,
+  "node_modules",
+  "@fastify",
+  "static",
+  "node_modules",
+  "brace-expansion",
+  "package.json",
+)
+
+const viteBinPath = path.join(uiRoot, "node_modules", ".bin", "vite")
+
+function ensureServerBuild() {
+  const distPath = path.join(serverRoot, "dist")
+  const publicPath = path.join(serverRoot, "public")
+  if (fs.existsSync(distPath) && fs.existsSync(publicPath)) {
+    return
+  }
+
+  console.log("[prebuild] server build missing; running workspace build...")
+  execSync("npm --workspace @neuralnomads/codenomad run build", {
+    cwd: workspaceRoot,
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      PATH: `${path.join(workspaceRoot, "node_modules/.bin")}:${process.env.PATH}`,
+    },
+  })
+
+  if (!fs.existsSync(distPath) || !fs.existsSync(publicPath)) {
+    throw new Error("[prebuild] server artifacts still missing after build")
+  }
+}
+
+function ensureUiBuild() {
+  const loadingHtml = path.join(uiDist, "loading.html")
+  if (fs.existsSync(loadingHtml)) {
+    return
+  }
+
+  console.log("[prebuild] ui build missing; running workspace build...")
+  execSync("npm --workspace @codenomad/ui run build", {
+    cwd: workspaceRoot,
+    stdio: "inherit",
+  })
+
+  if (!fs.existsSync(loadingHtml)) {
+    throw new Error("[prebuild] ui loading assets missing after build")
+  }
+}
+
+function ensureServerDevDependencies() {
+  if (fs.existsSync(braceExpansionPath)) {
+    return
+  }
+
+  console.log("[prebuild] ensuring server build dependencies (with dev)...")
+  execSync(serverDevInstallCommand, {
+    cwd: workspaceRoot,
+    stdio: "inherit",
+    env: envWithRootBin,
+  })
+}
+
+function ensureServerDependencies() {
+  if (fs.existsSync(braceExpansionPath)) {
+    return
+  }
+
+  console.log("[prebuild] ensuring server production dependencies...")
+  execSync(serverInstallCommand, {
+    cwd: serverRoot,
+    stdio: "inherit",
+  })
+}
+
+function ensureUiDevDependencies() {
+  if (fs.existsSync(viteBinPath)) {
+    return
+  }
+
+  console.log("[prebuild] ensuring ui build dependencies...")
+  execSync(uiDevInstallCommand, {
+    cwd: workspaceRoot,
+    stdio: "inherit",
+    env: envWithRootBin,
+  })
+}
+
+function ensureRollupPlatformBinary() {
+  const platformKey = `${process.platform}-${process.arch}`
+  const platformPackages = {
+    "linux-x64": "@rollup/rollup-linux-x64-gnu",
+    "linux-arm64": "@rollup/rollup-linux-arm64-gnu",
+    "darwin-arm64": "@rollup/rollup-darwin-arm64",
+    "darwin-x64": "@rollup/rollup-darwin-x64",
+    "win32-x64": "@rollup/rollup-win32-x64-msvc",
+  }
+
+  const pkgName = platformPackages[platformKey]
+  if (!pkgName) {
+    return
+  }
+
+  const platformPackagePath = path.join(workspaceRoot, "node_modules", "@rollup", pkgName.split("/").pop())
+  if (fs.existsSync(platformPackagePath)) {
+    return
+  }
+
+  let rollupVersion = ""
+  try {
+    rollupVersion = require(path.join(workspaceRoot, "node_modules", "rollup", "package.json")).version
+  } catch (error) {
+    // leave version empty; fallback install will use latest compatible
+  }
+
+  const packageSpec = rollupVersion ? `${pkgName}@${rollupVersion}` : pkgName
+
+  console.log("[prebuild] installing rollup platform binary (optional dep workaround)...")
+  execSync(`npm install ${packageSpec} --no-save --ignore-scripts --fund=false --audit=false`, {
+    cwd: workspaceRoot,
+    stdio: "inherit",
+  })
+}
+
+function copyServerArtifacts() {
+  fs.rmSync(serverDest, { recursive: true, force: true })
+  fs.mkdirSync(serverDest, { recursive: true })
+
+  for (const name of sources) {
+    const from = path.join(serverRoot, name)
+    const to = path.join(serverDest, name)
+    if (!fs.existsSync(from)) {
+      console.warn(`[prebuild] skipped missing ${from}`)
+      continue
+    }
+    fs.cpSync(from, to, { recursive: true, dereference: true })
+    console.log(`[prebuild] copied ${from} -> ${to}`)
+  }
+}
+
+function copyUiLoadingAssets() {
+  const loadingSource = path.join(uiDist, "loading.html")
+  const assetsSource = path.join(uiDist, "assets")
+
+  if (!fs.existsSync(loadingSource)) {
+    throw new Error("[prebuild] cannot find built loading.html")
+  }
+
+  fs.rmSync(uiLoadingDest, { recursive: true, force: true })
+  fs.mkdirSync(uiLoadingDest, { recursive: true })
+
+  fs.copyFileSync(loadingSource, path.join(uiLoadingDest, "loading.html"))
+  if (fs.existsSync(assetsSource)) {
+    fs.cpSync(assetsSource, path.join(uiLoadingDest, "assets"), { recursive: true })
+  }
+
+  console.log(`[prebuild] prepared UI loading assets from ${uiDist}`)
+}
+
+ensureServerDevDependencies()
+ensureUiDevDependencies()
+ensureRollupPlatformBinary()
+ensureServerDependencies()
+ensureServerBuild()
+ensureUiBuild()
+copyServerArtifacts()
+copyUiLoadingAssets()

packages/tauri-app/src-tauri/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "codenomad-tauri"
+version = "0.1.0"
+edition = "2021"
+
+[build-dependencies]
+tauri-build = { version = "2.5.2", features = [] }
+
+[dependencies]
+tauri = { version = "2.5.2", features = [ "devtools"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+regex = "1"
+once_cell = "1"
+parking_lot = "0.12"
+thiserror = "1"
+anyhow = "1"
+which = "4"
+libc = "0.2"
+tauri-plugin-dialog = "2"
+dirs = "5"
+tauri-plugin-opener = "2"
+url = "2"

packages/tauri-app/src-tauri/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build()
+}

packages/tauri-app/src-tauri/capabilities/main-window.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://schema.tauri.app/capabilities.json",
+  "identifier": "main-window-native-dialogs",
+  "description": "Grant the main window access to required core features and native dialog commands.",
+  "remote": {
+    "urls": ["http://127.0.0.1:*", "http://localhost:*"]
+  },
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "core:menu:default",
+    "dialog:allow-open",
+    "opener:allow-default-urls",
+    "core:webview:allow-set-webview-zoom"
+  ]
+}

packages/tauri-app/src-tauri/gen/schemas/capabilities.json

@@ -0,0 +1 @@
+{"main-window-native-dialogs":{"identifier":"main-window-native-dialogs","description":"Grant the main window access to required core features and native dialog commands.","remote":{"urls":["http://127.0.0.1:*","http://localhost:*"]},"local":true,"windows":["main"],"permissions":["core:default","core:menu:default","dialog:allow-open","opener:allow-default-urls","core:webview:allow-set-webview-zoom"]}}

packages/tauri-app/src-tauri/src/cli_manager.rs

@@ -0,0 +1,712 @@
+use dirs::home_dir;
+use parking_lot::Mutex;
+use regex::Regex;
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+use std::collections::VecDeque;
+use std::env;
+use std::ffi::OsStr;
+use std::fs;
+use std::io::{BufRead, BufReader};
+use std::path::PathBuf;
+use std::process::{Child, Command, Stdio};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::thread;
+use std::time::{Duration, Instant};
+use tauri::{AppHandle, Emitter, Manager, Url};
+
+fn log_line(message: &str) {
+    println!("[tauri-cli] {message}");
+}
+
+fn workspace_root() -> Option<PathBuf> {
+    std::env::current_dir().ok().and_then(|mut dir| {
+        for _ in 0..3 {
+            if let Some(parent) = dir.parent() {
+                dir = parent.to_path_buf();
+            }
+        }
+        Some(dir)
+    })
+}
+
+fn navigate_main(app: &AppHandle, url: &str) {
+    if let Some(win) = app.webview_windows().get("main") {
+        log_line(&format!("navigating main to {url}"));
+        if let Ok(parsed) = Url::parse(url) {
+            let _ = win.navigate(parsed);
+        } else {
+            log_line("failed to parse URL for navigation");
+        }
+    } else {
+        log_line("main window not found for navigation");
+    }
+}
+
+const DEFAULT_CONFIG_PATH: &str = "~/.config/codenomad/config.json";
+
+#[derive(Debug, Deserialize)]
+struct PreferencesConfig {
+    #[serde(rename = "listeningMode")]
+    listening_mode: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct AppConfig {
+    preferences: Option<PreferencesConfig>,
+}
+
+fn resolve_config_path() -> PathBuf {
+    let raw = env::var("CLI_CONFIG")
+        .ok()
+        .filter(|value| !value.trim().is_empty())
+        .unwrap_or_else(|| DEFAULT_CONFIG_PATH.to_string());
+    expand_home(&raw)
+}
+
+fn expand_home(path: &str) -> PathBuf {
+    if path.starts_with("~/") {
+        if let Some(home) = home_dir().or_else(|| env::var("HOME").ok().map(PathBuf::from)) {
+            return home.join(path.trim_start_matches("~/"));
+        }
+    }
+    PathBuf::from(path)
+}
+
+fn resolve_listening_mode() -> String {
+    let path = resolve_config_path();
+    if let Ok(content) = fs::read_to_string(path) {
+        if let Ok(config) = serde_json::from_str::<AppConfig>(&content) {
+            if let Some(mode) = config
+                .preferences
+                .as_ref()
+                .and_then(|prefs| prefs.listening_mode.as_ref())
+            {
+                if mode == "local" {
+                    return "local".to_string();
+                }
+                if mode == "all" {
+                    return "all".to_string();
+                }
+            }
+        }
+    }
+    "local".to_string()
+}
+
+fn resolve_listening_host() -> String {
+    let mode = resolve_listening_mode();
+    if mode == "local" {
+        "127.0.0.1".to_string()
+    } else {
+        "0.0.0.0".to_string()
+    }
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum CliState {
+    Starting,
+    Ready,
+    Error,
+    Stopped,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct CliStatus {
+    pub state: CliState,
+    pub pid: Option<u32>,
+    pub port: Option<u16>,
+    pub url: Option<String>,
+    pub error: Option<String>,
+}
+
+impl Default for CliStatus {
+    fn default() -> Self {
+        Self {
+            state: CliState::Stopped,
+            pid: None,
+            port: None,
+            url: None,
+            error: None,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct CliProcessManager {
+    status: Arc<Mutex<CliStatus>>,
+    child: Arc<Mutex<Option<Child>>>,
+    ready: Arc<AtomicBool>,
+}
+
+impl CliProcessManager {
+    pub fn new() -> Self {
+        Self {
+            status: Arc::new(Mutex::new(CliStatus::default())),
+            child: Arc::new(Mutex::new(None)),
+            ready: Arc::new(AtomicBool::new(false)),
+        }
+    }
+
+    pub fn start(&self, app: AppHandle, dev: bool) -> anyhow::Result<()> {
+        log_line(&format!("start requested (dev={dev})"));
+        self.stop()?;
+        self.ready.store(false, Ordering::SeqCst);
+        {
+            let mut status = self.status.lock();
+            status.state = CliState::Starting;
+            status.port = None;
+            status.url = None;
+            status.error = None;
+            status.pid = None;
+        }
+        Self::emit_status(&app, &self.status.lock());
+
+        let status_arc = self.status.clone();
+        let child_arc = self.child.clone();
+        let ready_flag = self.ready.clone();
+        thread::spawn(move || {
+            if let Err(err) = Self::spawn_cli(app.clone(), status_arc.clone(), child_arc, ready_flag, dev) {
+                log_line(&format!("cli spawn failed: {err}"));
+                let mut locked = status_arc.lock();
+                locked.state = CliState::Error;
+                locked.error = Some(err.to_string());
+                let snapshot = locked.clone();
+                drop(locked);
+                let _ = app.emit("cli:error", json!({"message": err.to_string()}));
+                let _ = app.emit("cli:status", snapshot);
+            }
+        });
+
+        Ok(())
+    }
+
+    pub fn stop(&self) -> anyhow::Result<()> {
+        let mut child_opt = self.child.lock();
+        if let Some(mut child) = child_opt.take() {
+            #[cfg(unix)]
+            unsafe {
+                libc::kill(child.id() as i32, libc::SIGTERM);
+            }
+            #[cfg(windows)]
+            {
+                let _ = child.kill();
+            }
+
+            let start = Instant::now();
+            loop {
+                match child.try_wait() {
+                    Ok(Some(_)) => break,
+                    Ok(None) => {
+                        if start.elapsed() > Duration::from_secs(4) {
+                            #[cfg(unix)]
+                            unsafe {
+                                libc::kill(child.id() as i32, libc::SIGKILL);
+                            }
+                            #[cfg(windows)]
+                            {
+                                let _ = child.kill();
+                            }
+                            break;
+                        }
+                        thread::sleep(Duration::from_millis(50));
+                    }
+                    Err(_) => break,
+                }
+            }
+        }
+
+        let mut status = self.status.lock();
+        status.state = CliState::Stopped;
+        status.pid = None;
+        status.port = None;
+        status.url = None;
+        status.error = None;
+
+        Ok(())
+    }
+
+    pub fn status(&self) -> CliStatus {
+        self.status.lock().clone()
+    }
+
+    fn spawn_cli(
+        app: AppHandle,
+        status: Arc<Mutex<CliStatus>>,
+        child_holder: Arc<Mutex<Option<Child>>>,
+        ready: Arc<AtomicBool>,
+        dev: bool,
+    ) -> anyhow::Result<()> {
+        log_line("resolving CLI entry");
+        let resolution = CliEntry::resolve(&app, dev)?;
+        let host = resolve_listening_host();
+        log_line(&format!(
+            "resolved CLI entry runner={:?} entry={} host={}",
+            resolution.runner, resolution.entry, host
+        ));
+        let args = resolution.build_args(dev, &host);
+        log_line(&format!("CLI args: {:?}", args));
+        if dev {
+            log_line("development mode: will prefer tsx + source if present");
+        }
+
+        let cwd = workspace_root();
+        if let Some(ref c) = cwd {
+            log_line(&format!("using cwd={}", c.display()));
+        }
+
+        let command_info = if supports_user_shell() {
+            log_line("spawning via user shell");
+            ShellCommandType::UserShell(build_shell_command_string(&resolution, &args)?)
+        } else {
+            log_line("spawning directly with node");
+            ShellCommandType::Direct(DirectCommand {
+                program: resolution.node_binary.clone(),
+                args: resolution.runner_args(&args),
+            })
+        };
+
+        if !supports_user_shell() {
+            if which::which(&resolution.node_binary).is_err() {
+                return Err(anyhow::anyhow!("Node binary not found. Make sure Node.js is installed."));
+            }
+        }
+
+        let child = match &command_info {
+            ShellCommandType::UserShell(cmd) => {
+                log_line(&format!("spawn command: {} {:?}", cmd.shell, cmd.args));
+                let mut c = Command::new(&cmd.shell);
+                c.args(&cmd.args)
+                    .env("ELECTRON_RUN_AS_NODE", "1")
+                    .stdout(Stdio::piped())
+                    .stderr(Stdio::piped());
+                if let Some(ref cwd) = cwd {
+                    c.current_dir(cwd);
+                }
+                c.spawn()?
+            }
+            ShellCommandType::Direct(cmd) => {
+                log_line(&format!("spawn command: {} {:?}", cmd.program, cmd.args));
+                let mut c = Command::new(&cmd.program);
+                c.args(&cmd.args)
+                    .env("ELECTRON_RUN_AS_NODE", "1")
+                    .stdout(Stdio::piped())
+                    .stderr(Stdio::piped());
+                if let Some(ref cwd) = cwd {
+                    c.current_dir(cwd);
+                }
+                c.spawn()?
+            }
+        };
+
+        let pid = child.id();
+        log_line(&format!("spawned pid={pid}"));
+        {
+            let mut locked = status.lock();
+            locked.pid = Some(pid);
+        }
+        Self::emit_status(&app, &status.lock());
+
+        {
+            let mut holder = child_holder.lock();
+            *holder = Some(child);
+        }
+
+        let child_clone = child_holder.clone();
+        let status_clone = status.clone();
+        let app_clone = app.clone();
+        let ready_clone = ready.clone();
+
+        thread::spawn(move || {
+            let stdout = child_clone
+                .lock()
+                .as_mut()
+                .and_then(|c| c.stdout.take())
+                .map(BufReader::new);
+            let stderr = child_clone
+                .lock()
+                .as_mut()
+                .and_then(|c| c.stderr.take())
+                .map(BufReader::new);
+
+            if let Some(reader) = stdout {
+                Self::process_stream(reader, "stdout", &app_clone, &status_clone, &ready_clone);
+            }
+            if let Some(reader) = stderr {
+                Self::process_stream(reader, "stderr", &app_clone, &status_clone, &ready_clone);
+            }
+        });
+
+        let app_clone = app.clone();
+        let status_clone = status.clone();
+        let ready_clone = ready.clone();
+        let child_holder_clone = child_holder.clone();
+        thread::spawn(move || {
+            let timeout = Duration::from_secs(60);
+            thread::sleep(timeout);
+            if ready_clone.load(Ordering::SeqCst) {
+                return;
+            }
+            let mut locked = status_clone.lock();
+            locked.state = CliState::Error;
+            locked.error = Some("CLI did not start in time".to_string());
+            log_line("timeout waiting for CLI readiness");
+            if let Some(child) = child_holder_clone.lock().as_mut() {
+                let _ = child.kill();
+            }
+            let _ = app_clone.emit("cli:error", json!({"message": "CLI did not start in time"}));
+            Self::emit_status(&app_clone, &locked);
+        });
+
+        let status_clone = status.clone();
+        let app_clone = app.clone();
+        thread::spawn(move || {
+            let code = {
+                let mut guard = child_holder.lock();
+                if let Some(child) = guard.as_mut() {
+                    child.wait().ok()
+                } else {
+                    None
+                }
+            };
+
+            let mut locked = status_clone.lock();
+            let failed = locked.state != CliState::Ready;
+            let err_msg = if failed {
+                Some(match code {
+                    Some(status) => format!("CLI exited early: {status}"),
+                    None => "CLI exited early".to_string(),
+                })
+            } else {
+                None
+            };
+
+            if failed {
+                locked.state = CliState::Error;
+                if locked.error.is_none() {
+                    locked.error = err_msg.clone();
+                }
+                log_line(&format!("cli process exited before ready: {:?}", locked.error));
+                let _ = app_clone.emit("cli:error", json!({"message": locked.error.clone().unwrap_or_default()}));
+            } else {
+                locked.state = CliState::Stopped;
+                log_line("cli process stopped cleanly");
+            }
+
+            Self::emit_status(&app_clone, &locked);
+        });
+
+        Ok(())
+    }
+
+    fn process_stream<R: BufRead>(
+        mut reader: R,
+        stream: &str,
+        app: &AppHandle,
+        status: &Arc<Mutex<CliStatus>>,
+        ready: &Arc<AtomicBool>,
+    ) {
+        let mut buffer = String::new();
+        let port_regex = Regex::new(r"CodeNomad Server is ready at http://[^:]+:(\d+)").ok();
+        let http_regex = Regex::new(r":(\d{2,5})(?!.*:\d)").ok();
+
+        loop {
+            buffer.clear();
+            match reader.read_line(&mut buffer) {
+                Ok(0) => break,
+                Ok(_) => {
+                    let line = buffer.trim_end();
+                    if !line.is_empty() {
+                        log_line(&format!("[cli][{}] {}", stream, line));
+
+                        if ready.load(Ordering::SeqCst) {
+                            continue;
+                        }
+
+                        if let Some(port) = port_regex
+                            .as_ref()
+                            .and_then(|re| re.captures(line).and_then(|c| c.get(1)))
+                            .and_then(|m| m.as_str().parse::<u16>().ok())
+                        {
+                            Self::mark_ready(app, status, ready, port);
+                            continue;
+                        }
+
+                        if line.to_lowercase().contains("http server listening") {
+                            if let Some(port) = http_regex
+                                .as_ref()
+                                .and_then(|re| re.captures(line).and_then(|c| c.get(1)))
+                                .and_then(|m| m.as_str().parse::<u16>().ok())
+                            {
+                                Self::mark_ready(app, status, ready, port);
+                                continue;
+                            }
+
+                            if let Ok(value) = serde_json::from_str::<serde_json::Value>(line) {
+                                if let Some(port) = value.get("port").and_then(|p| p.as_u64()) {
+                                    Self::mark_ready(app, status, ready, port as u16);
+                                    continue;
+                                }
+                            }
+                        }
+                    }
+                }
+                Err(_) => break,
+            }
+        }
+    }
+
+    fn mark_ready(app: &AppHandle, status: &Arc<Mutex<CliStatus>>, ready: &Arc<AtomicBool>, port: u16) {
+        ready.store(true, Ordering::SeqCst);
+        let mut locked = status.lock();
+        let url = format!("http://127.0.0.1:{port}");
+        locked.port = Some(port);
+        locked.url = Some(url.clone());
+        locked.state = CliState::Ready;
+        locked.error = None;
+        log_line(&format!("cli ready on {url}"));
+        navigate_main(app, &url);
+        let _ = app.emit("cli:ready", locked.clone());
+        Self::emit_status(app, &locked);
+    }
+
+    fn emit_status(app: &AppHandle, status: &CliStatus) {
+        let _ = app.emit("cli:status", status.clone());
+    }
+}
+
+fn supports_user_shell() -> bool {
+    cfg!(unix)
+}
+
+#[derive(Debug)]
+struct ShellCommand {
+    shell: String,
+    args: Vec<String>,
+}
+
+#[derive(Debug)]
+struct DirectCommand {
+    program: String,
+    args: Vec<String>,
+}
+
+#[derive(Debug)]
+enum ShellCommandType {
+    UserShell(ShellCommand),
+    Direct(DirectCommand),
+}
+
+#[derive(Debug)]
+struct CliEntry {
+    entry: String,
+    runner: Runner,
+    runner_path: Option<String>,
+    node_binary: String,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Runner {
+    Node,
+    Tsx,
+}
+
+impl CliEntry {
+    fn resolve(app: &AppHandle, dev: bool) -> anyhow::Result<Self> {
+        let node_binary = std::env::var("NODE_BINARY").unwrap_or_else(|_| "node".to_string());
+
+        if dev {
+            if let Some(tsx_path) = resolve_tsx(app) {
+                if let Some(entry) = resolve_dev_entry(app) {
+                    return Ok(Self {
+                        entry,
+                        runner: Runner::Tsx,
+                        runner_path: Some(tsx_path),
+                        node_binary,
+                    });
+                }
+            }
+        }
+
+        if let Some(entry) = resolve_dist_entry(app) {
+            return Ok(Self {
+                entry,
+                runner: Runner::Node,
+                runner_path: None,
+                node_binary,
+            });
+        }
+
+        Err(anyhow::anyhow!(
+            "Unable to locate CodeNomad CLI build (dist/bin.js). Please build @neuralnomads/codenomad."
+        ))
+    }
+
+    fn build_args(&self, dev: bool, host: &str) -> Vec<String> {
+        let mut args = vec![
+            "serve".to_string(),
+            "--host".to_string(),
+            host.to_string(),
+            "--port".to_string(),
+            "0".to_string(),
+        ];
+        if dev {
+            args.push("--ui-dev-server".to_string());
+            args.push("http://localhost:3000".to_string());
+            args.push("--log-level".to_string());
+            args.push("debug".to_string());
+        }
+        args
+    }
+
+    fn runner_args(&self, cli_args: &[String]) -> Vec<String> {
+        let mut args = VecDeque::new();
+        if self.runner == Runner::Tsx {
+            if let Some(path) = &self.runner_path {
+                args.push_back(path.clone());
+            }
+        }
+        args.push_back(self.entry.clone());
+        for arg in cli_args {
+            args.push_back(arg.clone());
+        }
+        args.into_iter().collect()
+    }
+}
+
+fn resolve_tsx(_app: &AppHandle) -> Option<String> {
+    let candidates = vec![
+        std::env::current_dir()
+            .ok()
+            .map(|p| p.join("node_modules/tsx/dist/cli.js")),
+        std::env::current_exe()
+            .ok()
+            .and_then(|ex| ex.parent().map(|p| p.join("../node_modules/tsx/dist/cli.js"))),
+    ];
+
+    first_existing(candidates)
+}
+
+fn resolve_dev_entry(_app: &AppHandle) -> Option<String> {
+    let candidates = vec![
+        std::env::current_dir()
+            .ok()
+            .map(|p| p.join("packages/server/src/index.ts")),
+        std::env::current_dir()
+            .ok()
+            .map(|p| p.join("../server/src/index.ts")),
+    ];
+
+    first_existing(candidates)
+}
+
+fn resolve_dist_entry(_app: &AppHandle) -> Option<String> {
+    let base = workspace_root();
+    let mut candidates: Vec<Option<PathBuf>> = vec![
+        base.as_ref().map(|p| p.join("packages/server/dist/bin.js")),
+        base.as_ref().map(|p| p.join("packages/server/dist/index.js")),
+        base.as_ref().map(|p| p.join("server/dist/bin.js")),
+        base.as_ref().map(|p| p.join("server/dist/index.js")),
+    ];
+
+    if let Ok(exe) = std::env::current_exe() {
+        if let Some(dir) = exe.parent() {
+            let resources = dir.join("../Resources");
+            candidates.push(Some(resources.join("server/dist/bin.js")));
+            candidates.push(Some(resources.join("server/dist/index.js")));
+            candidates.push(Some(resources.join("server/dist/server/bin.js")));
+            candidates.push(Some(resources.join("server/dist/server/index.js")));
+            candidates.push(Some(resources.join("resources/server/dist/bin.js")));
+            candidates.push(Some(resources.join("resources/server/dist/index.js")));
+            candidates.push(Some(resources.join("resources/server/dist/server/bin.js")));
+            candidates.push(Some(resources.join("resources/server/dist/server/index.js")));
+
+            let linux_resource_roots = [dir.join("../lib/CodeNomad"), dir.join("../lib/codenomad")];
+            for root in linux_resource_roots {
+                candidates.push(Some(root.join("server/dist/bin.js")));
+                candidates.push(Some(root.join("server/dist/index.js")));
+                candidates.push(Some(root.join("server/dist/server/bin.js")));
+                candidates.push(Some(root.join("server/dist/server/index.js")));
+                candidates.push(Some(root.join("resources/server/dist/bin.js")));
+                candidates.push(Some(root.join("resources/server/dist/index.js")));
+                candidates.push(Some(root.join("resources/server/dist/server/bin.js")));
+                candidates.push(Some(root.join("resources/server/dist/server/index.js")));
+            }
+        }
+    }
+
+    first_existing(candidates)
+}
+
+fn build_shell_command_string(entry: &CliEntry, cli_args: &[String]) -> anyhow::Result<ShellCommand> {
+
+    let shell = default_shell();
+    let mut quoted: Vec<String> = Vec::new();
+    quoted.push(shell_escape(&entry.node_binary));
+    for arg in entry.runner_args(cli_args) {
+        quoted.push(shell_escape(&arg));
+    }
+    let command = format!("ELECTRON_RUN_AS_NODE=1 exec {}", quoted.join(" "));
+    let args = build_shell_args(&shell, &command);
+    log_line(&format!("user shell command: {} {:?}", shell, args));
+    Ok(ShellCommand { shell, args })
+}
+
+fn default_shell() -> String {
+    if let Ok(shell) = std::env::var("SHELL") {
+        if !shell.trim().is_empty() {
+            return shell;
+        }
+    }
+    if cfg!(target_os = "macos") {
+        "/bin/zsh".to_string()
+    } else {
+        "/bin/bash".to_string()
+    }
+}
+
+fn shell_escape(input: &str) -> String {
+    if input.is_empty() {
+        "''".to_string()
+    } else if !input
+        .chars()
+        .any(|c| matches!(c, ' ' | '"' | '\'' | '$' | '`' | '!' ))
+    {
+        input.to_string()
+    } else {
+        let escaped = input.replace('\'', "'\\''");
+        format!("'{}'", escaped)
+    }
+}
+
+fn build_shell_args(shell: &str, command: &str) -> Vec<String> {
+    let shell_name = std::path::Path::new(shell)
+        .file_name()
+        .and_then(OsStr::to_str)
+        .unwrap_or("")
+        .to_lowercase();
+
+    if shell_name.contains("zsh") {
+        vec!["-l".into(), "-i".into(), "-c".into(), command.into()]
+    } else {
+        vec!["-l".into(), "-c".into(), command.into()]
+    }
+}
+
+fn first_existing(paths: Vec<Option<PathBuf>>) -> Option<String> {
+    paths
+        .into_iter()
+        .flatten()
+        .find(|p| p.exists())
+        .map(|p| normalize_path(p))
+}
+
+fn normalize_path(path: PathBuf) -> String {
+    if let Ok(clean) = path.canonicalize() {
+        clean.to_string_lossy().to_string()
+    } else {
+        path.to_string_lossy().to_string()
+    }
+}

packages/tauri-app/src-tauri/src/main.rs

@@ -0,0 +1,267 @@
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+mod cli_manager;
+
+use cli_manager::{CliProcessManager, CliStatus};
+use serde_json::json;
+use tauri::menu::{MenuBuilder, MenuItem, SubmenuBuilder};
+use tauri::plugin::{Builder as PluginBuilder, TauriPlugin};
+use tauri::webview::Webview;
+use tauri::{AppHandle, Emitter, Manager, Runtime, Wry};
+use tauri_plugin_opener::OpenerExt;
+use url::Url;
+
+#[derive(Clone)]
+pub struct AppState {
+    pub manager: CliProcessManager,
+}
+
+#[tauri::command]
+fn cli_get_status(state: tauri::State<AppState>) -> CliStatus {
+    state.manager.status()
+}
+
+#[tauri::command]
+fn cli_restart(app: AppHandle, state: tauri::State<AppState>) -> Result<CliStatus, String> {
+    let dev_mode = is_dev_mode();
+    state.manager.stop().map_err(|e| e.to_string())?;
+    state
+        .manager
+        .start(app, dev_mode)
+        .map_err(|e| e.to_string())?;
+    Ok(state.manager.status())
+}
+
+fn is_dev_mode() -> bool {
+    cfg!(debug_assertions) || std::env::var("TAURI_DEV").is_ok()
+}
+
+fn should_allow_internal(url: &Url) -> bool {
+    match url.scheme() {
+        "tauri" | "asset" | "file" => true,
+        "http" | "https" => matches!(url.host_str(), Some("127.0.0.1" | "localhost")),
+        _ => false,
+    }
+}
+
+fn intercept_navigation<R: Runtime>(webview: &Webview<R>, url: &Url) -> bool {
+    if should_allow_internal(url) {
+        return true;
+    }
+
+    if let Err(err) = webview
+        .app_handle()
+        .opener()
+        .open_url(url.as_str(), None::<&str>)
+    {
+        eprintln!("[tauri] failed to open external link {}: {}", url, err);
+    }
+    false
+}
+
+fn main() {
+    let navigation_guard: TauriPlugin<Wry, ()> = PluginBuilder::new("external-link-guard")
+        .on_navigation(|webview, url| intercept_navigation(webview, url))
+        .build();
+
+    tauri::Builder::default()
+        .plugin(tauri_plugin_dialog::init())
+        .plugin(tauri_plugin_opener::init())
+        .plugin(navigation_guard)
+        .manage(AppState {
+            manager: CliProcessManager::new(),
+        })
+        .setup(|app| {
+            build_menu(&app.handle())?;
+            let dev_mode = is_dev_mode();
+            let app_handle = app.handle().clone();
+            let manager = app.state::<AppState>().manager.clone();
+            std::thread::spawn(move || {
+                if let Err(err) = manager.start(app_handle.clone(), dev_mode) {
+                    let _ = app_handle.emit("cli:error", json!({"message": err.to_string()}));
+                }
+            });
+            Ok(())
+        })
+        .invoke_handler(tauri::generate_handler![cli_get_status, cli_restart])
+        .on_menu_event(|app_handle, event| {
+            match event.id().0.as_str() {
+                // File menu
+                "new_instance" => {
+                    if let Some(window) = app_handle.get_webview_window("main") {
+                        let _ = window.emit("menu:newInstance", ());
+                    }
+                }
+                "close" => {
+                    if let Some(window) = app_handle.get_webview_window("main") {
+                        let _ = window.close();
+                    }
+                }
+                "quit" => {
+                    app_handle.exit(0);
+                }
+
+                // View menu
+                "reload" => {
+                    if let Some(window) = app_handle.get_webview_window("main") {
+                        let _ = window.eval("window.location.reload()");
+                    }
+                }
+                "force_reload" => {
+                    if let Some(window) = app_handle.get_webview_window("main") {
+                        let _ = window.eval("window.location.reload(true)");
+                    }
+                }
+                "toggle_devtools" => {
+                    if let Some(window) = app_handle.get_webview_window("main") {
+                        window.open_devtools();
+                    }
+                }
+
+                "toggle_fullscreen" => {
+                    if let Some(window) = app_handle.get_webview_window("main") {
+                        let _ = window.set_fullscreen(!window.is_fullscreen().unwrap_or(false));
+                    }
+                }
+
+                // Window menu
+                "minimize" => {
+                    if let Some(window) = app_handle.get_webview_window("main") {
+                        let _ = window.minimize();
+                    }
+                }
+                "zoom" => {
+                    if let Some(window) = app_handle.get_webview_window("main") {
+                        let _ = window.maximize();
+                    }
+                }
+
+                // App menu (macOS)
+                "about" => {
+                    // TODO: Implement about dialog
+                    println!("About menu item clicked");
+                }
+                "hide" => {
+                    if let Some(window) = app_handle.get_webview_window("main") {
+                        let _ = window.hide();
+                    }
+                }
+                "hide_others" => {
+                    // TODO: Hide other app windows
+                    println!("Hide Others menu item clicked");
+                }
+                "show_all" => {
+                    // TODO: Show all app windows
+                    println!("Show All menu item clicked");
+                }
+
+                _ => {
+                    println!("Unhandled menu event: {}", event.id().0);
+                }
+            }
+        })
+        .build(tauri::generate_context!())
+        .expect("error while building tauri application")
+        .run(|app_handle, event| match event {
+            tauri::RunEvent::ExitRequested { .. } => {
+                let app = app_handle.clone();
+                std::thread::spawn(move || {
+                    if let Some(state) = app.try_state::<AppState>() {
+                        let _ = state.manager.stop();
+                    }
+                    app.exit(0);
+                });
+            }
+            tauri::RunEvent::WindowEvent {
+                event: tauri::WindowEvent::Destroyed,
+                ..
+            } => {
+                if app_handle.webview_windows().len() <= 1 {
+                    let app = app_handle.clone();
+                    std::thread::spawn(move || {
+                        if let Some(state) = app.try_state::<AppState>() {
+                            let _ = state.manager.stop();
+                        }
+                        app.exit(0);
+                    });
+                }
+            }
+            _ => {}
+        });
+}
+
+fn build_menu(app: &AppHandle) -> tauri::Result<()> {
+    let is_mac = cfg!(target_os = "macos");
+
+    // Create submenus
+    let mut submenus = Vec::new();
+
+    // App menu (macOS only)
+    if is_mac {
+        let app_menu = SubmenuBuilder::new(app, "CodeNomad")
+            .text("about", "About CodeNomad")
+            .separator()
+            .text("hide", "Hide CodeNomad")
+            .text("hide_others", "Hide Others")
+            .text("show_all", "Show All")
+            .separator()
+            .text("quit", "Quit CodeNomad")
+            .build()?;
+        submenus.push(app_menu);
+    }
+
+    // File menu - create New Instance with accelerator
+    let new_instance_item = MenuItem::with_id(
+        app,
+        "new_instance",
+        "New Instance",
+        true,
+        Some("CmdOrCtrl+N")
+    )?;
+    
+    let file_menu = SubmenuBuilder::new(app, "File")
+        .item(&new_instance_item)
+        .separator()
+        .text(if is_mac { "close" } else { "quit" }, if is_mac { "Close" } else { "Quit" })
+        .build()?;
+    submenus.push(file_menu);
+
+    // Edit menu with predefined items for standard functionality
+    let edit_menu = SubmenuBuilder::new(app, "Edit")
+        .undo()
+        .redo()
+        .separator()
+        .cut()
+        .copy()
+        .paste()
+        .separator()
+        .select_all()
+        .build()?;
+    submenus.push(edit_menu);
+
+    // View menu
+    let view_menu = SubmenuBuilder::new(app, "View")
+        .text("reload", "Reload")
+        .text("force_reload", "Force Reload")
+        .text("toggle_devtools", "Toggle Developer Tools")
+        .separator()
+
+        .separator()
+        .text("toggle_fullscreen", "Toggle Full Screen")
+        .build()?;
+    submenus.push(view_menu);
+
+    // Window menu
+    let window_menu = SubmenuBuilder::new(app, "Window")
+        .text("minimize", "Minimize")
+        .text("zoom", "Zoom")
+        .build()?;
+    submenus.push(window_menu);
+
+    // Build the main menu with all submenus
+    let submenu_refs: Vec<&dyn tauri::menu::IsMenuItem<_>> = submenus.iter().map(|s| s as &dyn tauri::menu::IsMenuItem<_>).collect();
+    let menu = MenuBuilder::new(app).items(&submenu_refs).build()?;
+    
+    app.set_menu(menu)?;
+    Ok(())
+}

packages/tauri-app/src-tauri/tauri.conf.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "CodeNomad",
+  "version": "0.1.0",
+  "identifier": "ai.opencode.client",
+  "build": {
+    "beforeDevCommand": "npm run dev:bootstrap",
+    "beforeBuildCommand": "npm run bundle:server",
+    "frontendDist": "resources/ui-loading"
+  },
+
+ 
+
+  "app": {
+    "withGlobalTauri": true,
+    "windows": [
+      {
+        "label": "main",
+        "title": "CodeNomad",
+        "url": "loading.html",
+        "width": 1400,
+        "height": 900,
+        "minWidth": 800,
+        "minHeight": 600,
+        "center": true,
+        "resizable": true,
+        "fullscreen": false,
+        "decorations": true,
+        "theme": "Dark",
+        "backgroundColor": "#1a1a1a",
+        "zoomHotkeysEnabled": true
+      }
+    ],
+    "security": {
+      "assetProtocol": {
+        "scope": ["**"]
+      },
+      "capabilities": ["main-window-native-dialogs"]
+    }
+  },
+  "bundle": {
+    "active": true,
+    "resources": [
+      "resources/server",
+      "resources/ui-loading"
+    ],
+    "icon": ["icon.icns", "icon.ico", "icon.png"],
+    "targets": ["app", "appimage", "deb", "rpm", "nsis"]
+  }
+}

packages/ui/README.md

@@ -0,0 +1,54 @@
+# CodeNomad UI
+
+This package contains the frontend user interface for CodeNomad, built with [SolidJS](https://www.solidjs.com/) and [Tailwind CSS](https://tailwindcss.com/).
+
+## Overview
+
+The UI is designed to be a high-performance, low-latency cockpit for managing OpenCode sessions. It connects to the CodeNomad server (either running locally via CLI or embedded in the Electron app).
+
+## Features
+
+- **SolidJS**: Fine-grained reactivity for high performance.
+- **Tailwind CSS**: Utility-first styling for rapid development.
+- **Vite**: Fast build tool and dev server.
+
+## Development
+
+To run the UI in standalone mode (connected to a running server):
+
+```bash
+npm run dev
+```
+
+This starts the Vite dev server at `http://localhost:3000`.
+
+## Building
+
+To build the production assets:
+
+```
+npm run build
+```
+
+The output will be generated in the `dist` directory, which is then consumed by the Server or Electron app.
+
+## Debug Logging
+
+The UI now routes all logging through a lightweight wrapper around [`debug`](https://github.com/debug-js/debug). The logger exposes four namespaces that can be toggled at runtime:
+
+- `sse` – Server-sent event transport and handlers
+- `api` – HTTP/API calls and workspace lifecycle
+- `session` – Session/model state, prompt handling, tool calls
+- `actions` – User-driven interactions in UI components
+
+You can enable or disable namespaces from DevTools (in dev or production builds) via the global `window.codenomadLogger` helpers:
+
+```js
+window.codenomadLogger?.listLoggerNamespaces() // => [{ name: "sse", enabled: false }, ...]
+window.codenomadLogger?.enableLogger("sse") // turn on SSE logs
+window.codenomadLogger?.disableLogger("sse") // turn them off again
+window.codenomadLogger?.enableAllLoggers() // optional helper
+```
+
+Enabled namespaces are persisted in `localStorage` under `opencode:logger:namespaces`, so your preference survives reloads.
+

packages/ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codenomad/ui",
-  "version": "0.1.2",
+  "version": "0.5.1",
   "private": true,
   "type": "module",
   "scripts": {
@@ -12,11 +12,17 @@
   "dependencies": {
     "@git-diff-view/solid": "^0.0.8",
     "@kobalte/core": "0.13.11",
-    "@opencode-ai/sdk": "1.0.68",
+    "@opencode-ai/sdk": "1.1.1",
     "@solidjs/router": "^0.13.0",
+    "@suid/icons-material": "^0.9.0",
+    "@suid/material": "^0.19.0",
+    "@suid/system": "^0.14.0",
+    "ansi-sequence-parser": "^1.1.3",
+    "debug": "^4.4.3",
     "github-markdown-css": "^5.8.1",
     "lucide-solid": "^0.300.0",
     "marked": "^12.0.0",
+    "qrcode": "^1.5.3",
     "shiki": "^3.13.0",
     "solid-js": "^1.8.0",
     "solid-toast": "^0.5.0"

packages/ui/src/App.tsx

@@ -1,19 +1,26 @@
-import { Component, Show, createMemo, createEffect, createSignal } from "solid-js"
+import { Component, For, Show, createMemo, createEffect, createSignal, onMount, onCleanup } from "solid-js"
 import { Dialog } from "@kobalte/core/dialog"
 import { Toaster } from "solid-toast"
+import AlertDialog from "./components/alert-dialog"
 import FolderSelectionView from "./components/folder-selection-view"
+import { showConfirmDialog } from "./stores/alerts"
 import InstanceTabs from "./components/instance-tabs"
 import InstanceDisconnectedModal from "./components/instance-disconnected-modal"
-import InstanceShell from "./components/instance/instance-shell"
+import InstanceShell from "./components/instance/instance-shell2"
+import { RemoteAccessOverlay } from "./components/remote-access-overlay"
+import { InstanceMetadataProvider } from "./lib/contexts/instance-metadata-context"
 import { initMarkdown } from "./lib/markdown"
+
 import { useTheme } from "./lib/theme"
 import { useCommands } from "./lib/hooks/use-commands"
 import { useAppLifecycle } from "./lib/hooks/use-app-lifecycle"
+import { getLogger } from "./lib/logger"
+import { initReleaseNotifications } from "./stores/releases"
+import { runtimeEnv } from "./lib/runtime-env"
 import {
   hasInstances,
   isSelectingFolder,
   setIsSelectingFolder,
-  setHasInstances,
   showFolderSelection,
   setShowFolderSelection,
 } from "./stores/ui"
@@ -39,22 +46,58 @@ import {
   updateSessionModel,
 } from "./stores/sessions"
 
+const log = getLogger("actions")
+
 const App: Component = () => {
   const { isDark } = useTheme()
   const {
     preferences,
-    addRecentFolder,
+    recordWorkspaceLaunch,
     toggleShowThinkingBlocks,
+    toggleShowTimelineTools,
+    toggleAutoCleanupBlankSessions,
+    toggleUsageMetrics,
     setDiffViewMode,
     setToolOutputExpansion,
     setDiagnosticsExpansion,
+    setThinkingBlocksExpansion,
   } = useConfig()
   const [escapeInDebounce, setEscapeInDebounce] = createSignal(false)
-  const [launchErrorBinary, setLaunchErrorBinary] = createSignal<string | null>(null)
+  interface LaunchErrorState {
+    message: string
+    binaryPath: string
+    missingBinary: boolean
+  }
+  const [launchError, setLaunchError] = createSignal<LaunchErrorState | null>(null)
   const [isAdvancedSettingsOpen, setIsAdvancedSettingsOpen] = createSignal(false)
+  const [remoteAccessOpen, setRemoteAccessOpen] = createSignal(false)
+  const [instanceTabBarHeight, setInstanceTabBarHeight] = createSignal(0)
+
+  const updateInstanceTabBarHeight = () => {
+    if (typeof document === "undefined") return
+    const element = document.querySelector<HTMLElement>(".tab-bar-instance")
+    setInstanceTabBarHeight(element?.offsetHeight ?? 0)
+  }
 
   createEffect(() => {
-    void initMarkdown(isDark()).catch(console.error)
+    void initMarkdown(isDark()).catch((error) => log.error("Failed to initialize markdown", error))
+  })
+
+  createEffect(() => {
+    initReleaseNotifications()
+  })
+
+  createEffect(() => {
+    instances()
+    hasInstances()
+    requestAnimationFrame(() => updateInstanceTabBarHeight())
+  })
+
+  onMount(() => {
+    updateInstanceTabBarHeight()
+    const handleResize = () => updateInstanceTabBarHeight()
+    window.addEventListener("resize", handleResize)
+    onCleanup(() => window.removeEventListener("resize", handleResize))
   })
 
   const activeInstance = createMemo(() => getActiveInstance())
@@ -65,14 +108,30 @@ const App: Component = () => {
   })
 
   const launchErrorPath = () => {
-    const value = launchErrorBinary()
+    const value = launchError()?.binaryPath
     if (!value) return "opencode"
     return value.trim() || "opencode"
   }
 
-  const isMissingBinaryError = (error: unknown): boolean => {
+  const launchErrorMessage = () => launchError()?.message ?? ""
-    if (!error) return false
+
-    const message = typeof error === "string" ? error : error instanceof Error ? error.message : String(error)
+  const formatLaunchErrorMessage = (error: unknown): string => {
+    if (!error) {
+      return "Failed to launch workspace"
+    }
+    const raw = typeof error === "string" ? error : error instanceof Error ? error.message : String(error)
+    try {
+      const parsed = JSON.parse(raw)
+      if (parsed && typeof parsed.error === "string") {
+        return parsed.error
+      }
+    } catch {
+      // ignore JSON parse errors
+    }
+    return raw
+  }
+
+  const isMissingBinaryMessage = (message: string): boolean => {
     const normalized = message.toLowerCase()
     return (
       normalized.includes("opencode binary not found") ||
@@ -83,7 +142,7 @@ const App: Component = () => {
     )
   }
 
-  const clearLaunchError = () => setLaunchErrorBinary(null)
+  const clearLaunchError = () => setLaunchError(null)
 
   async function handleSelectFolder(folderPath: string, binaryPath?: string) {
     if (!folderPath) {
@@ -92,20 +151,25 @@ const App: Component = () => {
     setIsSelectingFolder(true)
     const selectedBinary = binaryPath || preferences().lastUsedBinary || "opencode"
     try {
-      addRecentFolder(folderPath)
+      recordWorkspaceLaunch(folderPath, selectedBinary)
       clearLaunchError()
       const instanceId = await createInstance(folderPath, selectedBinary)
-      setHasInstances(true)
       setShowFolderSelection(false)
       setIsAdvancedSettingsOpen(false)
 
-      console.log("Created instance:", instanceId, "Port:", instances().get(instanceId)?.port)
+      log.info("Created instance", {
+        instanceId,
+        port: instances().get(instanceId)?.port,
+      })
     } catch (error) {
-      clearLaunchError()
+      const message = formatLaunchErrorMessage(error)
-      if (isMissingBinaryError(error)) {
+      const missingBinary = isMissingBinaryMessage(message)
-        setLaunchErrorBinary(selectedBinary)
+      setLaunchError({
-      }
+        message,
-      console.error("Failed to create instance:", error)
+        binaryPath: selectedBinary,
+        missingBinary,
+      })
+      log.error("Failed to create instance", error)
     } finally {
       setIsSelectingFolder(false)
     }
@@ -130,17 +194,24 @@ const App: Component = () => {
     try {
       await acknowledgeDisconnectedInstance()
     } catch (error) {
-      console.error("Failed to finalize disconnected instance:", error)
+      log.error("Failed to finalize disconnected instance", error)
     }
   }
 
   async function handleCloseInstance(instanceId: string) {
-    if (confirm("Stop OpenCode instance? This will stop the server.")) {
+    const confirmed = await showConfirmDialog(
+      "Stop OpenCode instance? This will stop the server.",
+      {
+        title: "Stop instance",
+        variant: "warning",
+        confirmLabel: "Stop",
+        cancelLabel: "Keep running",
+      },
+    )
+
+    if (!confirmed) return
+
     await stopInstance(instanceId)
-      if (instances().size === 0) {
-        setHasInstances(false)
-      }
-    }
   }
 
   async function handleNewSession(instanceId: string) {
@@ -148,7 +219,7 @@ const App: Component = () => {
       const session = await createSession(instanceId)
       setActiveParentSession(instanceId, session.id)
     } catch (error) {
-      console.error("Failed to create session:", error)
+      log.error("Failed to create session", error)
     }
   }
 
@@ -172,7 +243,7 @@ const App: Component = () => {
     try {
       await fetchSessions(instanceId)
     } catch (error) {
-      console.error("Failed to refresh sessions after closing:", error)
+      log.error("Failed to refresh sessions after closing", error)
     }
   }
 
@@ -192,10 +263,14 @@ const App: Component = () => {
 
   const { commands: paletteCommands, executeCommand } = useCommands({
     preferences,
+    toggleAutoCleanupBlankSessions,
     toggleShowThinkingBlocks,
+    toggleShowTimelineTools,
+    toggleUsageMetrics,
     setDiffViewMode,
     setToolOutputExpansion,
     setDiagnosticsExpansion,
+    setThinkingBlocksExpansion,
     handleNewInstanceRequest,
     handleCloseInstance,
     handleNewSession,
@@ -216,6 +291,28 @@ const App: Component = () => {
     getActiveSessionIdForInstance: activeSessionIdForInstance,
   })
 
+  // Listen for Tauri menu events
+  onMount(() => {
+    if (runtimeEnv.host === "tauri") {
+      const tauriBridge = (window as { __TAURI__?: { event?: { listen: (event: string, handler: (event: { payload: unknown }) => void) => Promise<() => void> } } }).__TAURI__
+      if (tauriBridge?.event) {
+        let unlistenMenu: (() => void) | null = null
+        
+        tauriBridge.event.listen("menu:newInstance", () => {
+          handleNewInstanceRequest()
+        }).then((unlisten) => {
+          unlistenMenu = unlisten
+        }).catch((error) => {
+          log.error("Failed to listen for menu:newInstance event", error)
+        })
+
+        onCleanup(() => {
+          unlistenMenu?.()
+        })
+      }
+    }
+  })
+
   return (
     <>
       <InstanceDisconnectedModal
@@ -225,16 +322,16 @@ const App: Component = () => {
         onClose={handleDisconnectedInstanceClose}
       />
 
-      <Dialog open={Boolean(launchErrorBinary())} modal>
+      <Dialog open={Boolean(launchError())} modal>
         <Dialog.Portal>
           <Dialog.Overlay class="modal-overlay" />
           <div class="fixed inset-0 z-50 flex items-center justify-center p-4">
             <Dialog.Content class="modal-surface w-full max-w-md p-6 flex flex-col gap-6">
               <div>
                 <Dialog.Title class="text-xl font-semibold text-primary">Unable to launch OpenCode</Dialog.Title>
-                <Dialog.Description class="text-sm text-secondary mt-2">
+                <Dialog.Description class="text-sm text-secondary mt-2 break-words">
-                  Install the OpenCode CLI and make sure it is available in your PATH, or pick a custom binary from
+                  We couldn't start the selected OpenCode binary. Review the error output below or choose a different
-                  Advanced Settings.
+                  binary from Advanced Settings.
                 </Dialog.Description>
               </div>
 
@@ -243,10 +340,23 @@ const App: Component = () => {
                 <p class="text-sm font-mono text-primary break-all">{launchErrorPath()}</p>
               </div>
 
+              <Show when={launchErrorMessage()}>
+                <div class="rounded-lg border border-base bg-surface-secondary p-4">
+                  <p class="text-xs font-medium text-muted uppercase tracking-wide mb-1">Error output</p>
+                  <pre class="text-sm font-mono text-primary whitespace-pre-wrap break-words max-h-48 overflow-y-auto">{launchErrorMessage()}</pre>
+                </div>
+              </Show>
+
               <div class="flex justify-end gap-2">
-                <button type="button" class="selector-button selector-button-secondary" onClick={handleLaunchErrorAdvanced}>
+                <Show when={launchError()?.missingBinary}>
+                  <button
+                    type="button"
+                    class="selector-button selector-button-secondary"
+                    onClick={handleLaunchErrorAdvanced}
+                  >
                     Open Advanced Settings
                   </button>
+                </Show>
                 <button type="button" class="selector-button selector-button-primary" onClick={handleLaunchErrorClose}>
                   Close
                 </button>
@@ -266,10 +376,16 @@ const App: Component = () => {
                 onSelect={setActiveInstanceId}
                 onClose={handleCloseInstance}
                 onNew={handleNewInstanceRequest}
+                onOpenRemoteAccess={() => setRemoteAccessOpen(true)}
               />
  
-              <Show when={activeInstance()} keyed>
+              <For each={Array.from(instances().values())}>
-                {(instance) => (
+                {(instance) => {
+                  const isActiveInstance = () => activeInstanceId() === instance.id
+                  const isVisible = () => isActiveInstance() && !showFolderSelection()
+                    return (
+                      <div class="flex-1 min-h-0 overflow-hidden" style={{ display: isVisible() ? "flex" : "none" }}>
+                        <InstanceMetadataProvider instance={instance}>
                           <InstanceShell
                             instance={instance}
                             escapeInDebounce={escapeInDebounce()}
@@ -279,9 +395,16 @@ const App: Component = () => {
                             handleSidebarAgentChange={(sessionId, agent) => handleSidebarAgentChange(instance.id, sessionId, agent)}
                             handleSidebarModelChange={(sessionId, model) => handleSidebarModelChange(instance.id, sessionId, model)}
                             onExecuteCommand={executeCommand}
+                            tabBarOffset={instanceTabBarHeight()}
                           />
-                )}
+                        </InstanceMetadataProvider>
-              </Show>
+
+                      </div>
+                    )
+
+                }}
+              </For>
+
             </>
           }
         >
@@ -291,6 +414,7 @@ const App: Component = () => {
             advancedSettingsOpen={isAdvancedSettingsOpen()}
             onAdvancedSettingsOpen={() => setIsAdvancedSettingsOpen(true)}
             onAdvancedSettingsClose={() => setIsAdvancedSettingsOpen(false)}
+            onOpenRemoteAccess={() => setRemoteAccessOpen(true)}
           />
         </Show>
 
@@ -321,6 +445,10 @@ const App: Component = () => {
           </div>
         </Show>
  
+        <RemoteAccessOverlay open={remoteAccessOpen()} onClose={() => setRemoteAccessOpen(false)} />
+ 
+        <AlertDialog />
+
         <Toaster
           position="top-right"
           gutter={16}
@@ -334,4 +462,5 @@ const App: Component = () => {
   )
 }
 
+
 export default App

packages/ui/src/components/agent-selector.tsx

@@ -3,7 +3,9 @@ import { For, Show, createEffect, createMemo } from "solid-js"
 import { agents, fetchAgents, sessions } from "../stores/sessions"
 import { ChevronDown } from "lucide-solid"
 import type { Agent } from "../types/session"
-import Kbd from "./kbd"
+import { getLogger } from "../lib/logger"
+const log = getLogger("session")
+
 
 interface AgentSelectorProps {
   instanceId: string
@@ -50,10 +52,11 @@ export default function AgentSelector(props: AgentSelectorProps) {
 
   createEffect(() => {
     if (instanceAgents().length === 0) {
-      fetchAgents(props.instanceId).catch(console.error)
+      fetchAgents(props.instanceId).catch((error) => log.error("Failed to fetch agents", error))
     }
   })
 
+
   const handleChange = async (value: Agent | null) => {
     if (value && value.name !== props.currentAgent) {
       await props.onAgentChange(value.name)
@@ -111,14 +114,11 @@ export default function AgentSelector(props: AgentSelectorProps) {
         </Select.Trigger>
 
         <Select.Portal>
-          <Select.Content class="selector-popover max-h-80 overflow-auto p-1 z-50">
+          <Select.Content class="selector-popover max-h-80 overflow-auto p-1">
             <Select.Listbox class="selector-listbox" />
           </Select.Content>
         </Select.Portal>
       </Select>
-      <span class="hint sidebar-selector-hint">
-        <Kbd shortcut="cmd+shift+a" />
-      </span>
     </div>
   )
 }

packages/ui/src/components/alert-dialog.tsx

@@ -0,0 +1,132 @@
+import { Dialog } from "@kobalte/core/dialog"
+import { Component, Show, createEffect } from "solid-js"
+import { alertDialogState, dismissAlertDialog } from "../stores/alerts"
+import type { AlertVariant, AlertDialogState } from "../stores/alerts"
+
+const variantAccent: Record<AlertVariant, { badgeBg: string; badgeBorder: string; badgeText: string; symbol: string; fallbackTitle: string }> = {
+  info: {
+    badgeBg: "var(--badge-neutral-bg)",
+    badgeBorder: "var(--border-base)",
+    badgeText: "var(--accent-primary)",
+    symbol: "i",
+    fallbackTitle: "Heads up",
+  },
+  warning: {
+    badgeBg: "rgba(255, 152, 0, 0.14)",
+    badgeBorder: "var(--status-warning)",
+    badgeText: "var(--status-warning)",
+    symbol: "!",
+    fallbackTitle: "Please review",
+  },
+  error: {
+    badgeBg: "var(--danger-soft-bg)",
+    badgeBorder: "var(--status-error)",
+    badgeText: "var(--status-error)",
+    symbol: "!",
+    fallbackTitle: "Something went wrong",
+  },
+}
+
+function dismiss(confirmed: boolean, payload?: AlertDialogState | null) {
+  const current = payload ?? alertDialogState()
+  if (current?.type === "confirm") {
+    if (confirmed) {
+      current.onConfirm?.()
+    } else {
+      current.onCancel?.()
+    }
+    current.resolve?.(confirmed)
+  } else if (confirmed) {
+    current?.onConfirm?.()
+  }
+  dismissAlertDialog()
+}
+
+const AlertDialog: Component = () => {
+  let primaryButtonRef: HTMLButtonElement | undefined
+
+  createEffect(() => {
+    if (alertDialogState()) {
+      queueMicrotask(() => {
+        primaryButtonRef?.focus()
+      })
+    }
+  })
+
+  return (
+    <Show when={alertDialogState()} keyed>
+      {(payload) => {
+        const variant = payload.variant ?? "info"
+        const accent = variantAccent[variant]
+        const title = payload.title || accent.fallbackTitle
+        const isConfirm = payload.type === "confirm"
+        const confirmLabel = payload.confirmLabel || (isConfirm ? "Confirm" : "OK")
+        const cancelLabel = payload.cancelLabel || "Cancel"
+
+        return (
+          <Dialog
+            open
+            modal
+            onOpenChange={(open) => {
+              if (!open) {
+                dismiss(false, payload)
+              }
+            }}
+          >
+            <Dialog.Portal>
+              <Dialog.Overlay class="modal-overlay" />
+              <div class="fixed inset-0 z-50 flex items-center justify-center p-4">
+                <Dialog.Content class="modal-surface w-full max-w-sm p-6 border border-base shadow-2xl" tabIndex={-1}>
+                  <div class="flex items-start gap-3">
+                    <div
+                      class="flex h-12 w-12 shrink-0 items-center justify-center rounded-xl border text-base font-semibold"
+                      style={{
+                        "background-color": accent.badgeBg,
+                        "border-color": accent.badgeBorder,
+                        color: accent.badgeText,
+                      }}
+                      aria-hidden
+                    >
+                      {accent.symbol}
+                    </div>
+                    <div class="flex-1 min-w-0">
+                      <Dialog.Title class="text-lg font-semibold text-primary">{title}</Dialog.Title>
+                      <Dialog.Description class="text-sm text-secondary mt-1 whitespace-pre-line break-words">
+                        {payload.message}
+                        {payload.detail && <p class="mt-2 text-secondary">{payload.detail}</p>}
+                      </Dialog.Description>
+                    </div>
+                  </div>
+
+                  <div class="mt-6 flex justify-end gap-3">
+                    {isConfirm && (
+                      <button
+                        type="button"
+                        class="button-secondary"
+                        onClick={() => dismiss(false, payload)}
+                      >
+                        {cancelLabel}
+                      </button>
+                    )}
+                    <button
+                      type="button"
+                      class="button-primary"
+                      ref={(el) => {
+                        primaryButtonRef = el
+                      }}
+                      onClick={() => dismiss(true, payload)}
+                    >
+                      {confirmLabel}
+                    </button>
+                  </div>
+                </Dialog.Content>
+              </div>
+            </Dialog.Portal>
+          </Dialog>
+        )
+      }}
+    </Show>
+  )
+}
+
+export default AlertDialog

packages/ui/src/components/background-process-output-dialog.tsx

@@ -0,0 +1,167 @@
+import { Dialog } from "@kobalte/core/dialog"
+import { Show, createEffect, createSignal, onCleanup } from "solid-js"
+import type { BackgroundProcess } from "../../../server/src/api-types"
+import { buildBackgroundProcessStreamUrl, serverApi } from "../lib/api-client"
+import { createAnsiStreamRenderer, hasAnsi } from "../lib/ansi"
+
+interface BackgroundProcessOutputDialogProps {
+  open: boolean
+  instanceId: string
+  process: BackgroundProcess | null
+  onClose: () => void
+}
+
+export function BackgroundProcessOutputDialog(props: BackgroundProcessOutputDialogProps) {
+  const [output, setOutput] = createSignal("")
+  const [outputHtml, setOutputHtml] = createSignal("")
+  const [ansiEnabled, setAnsiEnabled] = createSignal(false)
+  const [truncated, setTruncated] = createSignal(false)
+  const [loading, setLoading] = createSignal(false)
+  let ansiRenderer = createAnsiStreamRenderer()
+
+  createEffect(() => {
+    const process = props.process
+    if (!props.open || !process) {
+      return
+    }
+
+    let eventSource: EventSource | null = null
+    let active = true
+
+    let rawOutput = ""
+
+    const setRawOutput = (next: string) => {
+      rawOutput = next
+      setOutput(next)
+    }
+
+    const appendRawOutput = (chunk: string) => {
+      rawOutput += chunk
+      setOutput(rawOutput)
+    }
+
+    setAnsiEnabled(false)
+    setOutputHtml("")
+    setRawOutput("")
+    ansiRenderer.reset()
+
+    setLoading(true)
+    serverApi
+      .fetchBackgroundProcessOutput(props.instanceId, process.id, { method: "full", maxBytes: undefined })
+      .then((response) => {
+        if (!active) return
+
+        setRawOutput(response.content)
+        setTruncated(response.truncated)
+
+        const detectedAnsi = hasAnsi(response.content)
+        if (detectedAnsi) {
+          setAnsiEnabled(true)
+          ansiRenderer.reset()
+          setOutputHtml(ansiRenderer.render(response.content))
+        } else {
+          setAnsiEnabled(false)
+          setOutputHtml("")
+          ansiRenderer.reset()
+        }
+      })
+      .catch(() => {
+        if (!active) return
+        setRawOutput("Failed to load output.")
+        setAnsiEnabled(false)
+        setOutputHtml("")
+      })
+      .finally(() => {
+        if (!active) return
+        setLoading(false)
+      })
+
+    eventSource = new EventSource(buildBackgroundProcessStreamUrl(props.instanceId, process.id))
+    eventSource.onmessage = (event) => {
+      try {
+        const payload = JSON.parse(event.data) as { type?: string; content?: string }
+        if (payload?.type !== "chunk" || typeof payload.content !== "string") {
+          return
+        }
+
+        const chunk = payload.content
+        const wasAnsiEnabled = ansiEnabled()
+
+        if (!wasAnsiEnabled) {
+          appendRawOutput(chunk)
+
+          if (hasAnsi(chunk)) {
+            setAnsiEnabled(true)
+            ansiRenderer.reset()
+            setOutputHtml(ansiRenderer.render(rawOutput))
+          }
+
+          return
+        }
+
+        appendRawOutput(chunk)
+        const htmlChunk = ansiRenderer.render(chunk)
+        setOutputHtml((prev) => `${prev}${htmlChunk}`)
+      } catch {
+        // ignore parse errors
+      }
+    }
+
+    onCleanup(() => {
+      active = false
+      eventSource?.close()
+    })
+  })
+
+  return (
+    <Dialog open={props.open} onOpenChange={(open) => !open && props.onClose()} modal>
+      <Dialog.Portal>
+        <Dialog.Overlay class="modal-overlay" />
+        <div class="fixed inset-0 z-50 flex items-center justify-center p-4">
+          <Dialog.Content class="modal-surface w-full max-w-5xl max-h-[90vh] flex flex-col overflow-hidden">
+            <div class="flex items-start justify-between px-6 py-4 border-b border-base gap-4">
+              <div class="flex-1 min-w-0">
+                <Dialog.Title class="text-lg font-semibold text-primary">Background Output</Dialog.Title>
+                <Show when={props.process}>
+                  <span class="text-xs text-secondary block">
+                    {props.process?.title} · {props.process?.id}
+                  </span>
+                  <span class="text-xs text-secondary mt-1 block truncate" title={props.process?.command}>
+                    {props.process?.command}
+                  </span>
+                </Show>
+              </div>
+
+              <button type="button" class="button-tertiary flex-shrink-0" onClick={props.onClose}>
+                Close
+              </button>
+            </div>
+            <div class="flex-1 overflow-auto p-6">
+              <Show when={loading()}>
+                <p class="text-xs text-secondary">Loading output...</p>
+              </Show>
+              <Show when={!loading()}>
+                <Show when={truncated()}>
+                  <p class="text-xs text-secondary mb-2">Output truncated for display.</p>
+                </Show>
+                <Show
+                  when={ansiEnabled()}
+                  fallback={
+                    <pre class="text-xs whitespace-pre-wrap break-all text-primary bg-surface-secondary border border-base rounded-md p-4 font-mono">
+                      {output()}
+                    </pre>
+                  }
+                >
+                  <pre
+                    class="text-xs whitespace-pre-wrap break-all text-primary bg-surface-secondary border border-base rounded-md p-4 font-mono"
+                    innerHTML={outputHtml()}
+                  />
+                </Show>
+              </Show>
+            </div>
+          </Dialog.Content>
+        </div>
+      </Dialog.Portal>
+    </Dialog>
+  )
+}