docs: add star history chart

Replace /login history entry on success and redirect authenticated /login to /, with no-store headers to prevent caching.

.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,41 @@
+name: Develop Pre-Release
+
+on:
+  push:
+    branches:
+      - dev
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: write
+
+concurrency:
+  group: dev-prerelease
+  cancel-in-progress: true
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    outputs:
+      version_suffix: ${{ steps.vars.outputs.version_suffix }}
+    steps:
+      - name: Compute version suffix
+        id: vars
+        shell: bash
+        run: |
+          set -euo pipefail
+          SHA8="${GITHUB_SHA::8}"
+          DATE=$(date -u +%Y%m%d)
+          echo "version_suffix=-dev-${DATE}-${SHA8}" >> "$GITHUB_OUTPUT"
+
+  prerelease:
+    needs: prepare
+    uses: ./.github/workflows/reusable-release.yml
+    with:
+      version_suffix: ${{ needs.prepare.outputs.version_suffix }}
+      npm_package_name: "@neuralnomads/codenomad-dev"
+      dist_tag: latest
+      prerelease: true
+      release_ui: false
+    secrets: inherit

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

@@ -0,0 +1,104 @@
+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
+      package_name:
+        description: "Package name to publish (e.g. @neuralnomads/codenomad-dev)"
+        required: false
+        default: "@neuralnomads/codenomad"
+        type: string
+  workflow_call:
+    inputs:
+      version:
+        required: true
+        type: string
+      dist_tag:
+        required: false
+        type: string
+        default: dev
+      package_name:
+        required: false
+        type: string
+        default: "@neuralnomads/codenomad"
+    secrets:
+      NPM_TOKEN:
+        required: false
+
+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 packages/server
+
+      - 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"
+          echo "PACKAGE_NAME=${{ inputs.package_name }}" >> "$GITHUB_ENV"
+
+      - name: Bump package version for publish
+        run: npm version ${VERSION} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
+
+      - name: Set server package name for publish
+        shell: bash
+        run: |
+          set -euo pipefail
+          node -e "const fs=require('fs'); const path=require('path'); const p=path.join('packages','server','package.json'); const j=JSON.parse(fs.readFileSync(p,'utf8')); j.name=process.env.PACKAGE_NAME || j.name; fs.writeFileSync(p, JSON.stringify(j, null, 2)+'\n'); console.log('Publishing as', j.name);"
+
+      - name: Publish server package with provenance
+        env:
+          # Optional: when present, npm will use token auth.
+          # When empty/unset, npm trusted publishing (OIDC) may be used if configured.
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true
+          NPM_CONFIG_REGISTRY: https://registry.npmjs.org
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ -z "${NODE_AUTH_TOKEN:-}" ]; then
+            echo "NPM_TOKEN not set; attempting npm trusted publishing (OIDC)"
+            unset NODE_AUTH_TOKEN
+          else
+            echo "Using NPM_TOKEN authentication"
+          fi
+          npm publish --workspace packages/server --access public --tag ${DIST_TAG} --provenance

.github/workflows/release-ui.yml

@@ -0,0 +1,47 @@
+name: Release UI
+
+on:
+  workflow_call: {}
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+env:
+  NODE_VERSION: 20
+
+jobs:
+  release-ui:
+    # Automated via reusable call (main releases); manual runs allowed on dev/main.
+    if: ${{ github.event_name == 'workflow_call' || github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-24.04
+    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 --include=optional
+
+      - name: Ensure rollup native binary
+        run: npm install @rollup/rollup-linux-x64-gnu --no-save
+
+      - name: Install Cloudflare worker deps
+        run: npm ci
+        working-directory: packages/cloudflare
+
+      - name: Build UI
+        run: npm run build --workspace @codenomad/ui
+
+      - name: Publish UI zip + update manifest
+        working-directory: packages/cloudflare
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          CODENOMAD_R2_BUCKET: ${{ vars.CODENOMAD_R2_BUCKET }}
+        run: npm run release:ui

.github/workflows/release.yml

@@ -6,211 +6,13 @@ on:
       - main
 
 permissions:
+  id-token: write
   contents: write
 
-env:
-  NODE_VERSION: 20
-
 jobs:
-  prepare-release:
-    runs-on: ubuntu-latest
-    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 }}
-
-      - 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
+  release:
+    uses: ./.github/workflows/reusable-release.yml
+    with:
+      dist_tag: latest
+      npm_package_name: "@neuralnomads/codenomad"
+    secrets: inherit

.github/workflows/reusable-release.yml

@@ -0,0 +1,109 @@
+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
+      npm_package_name:
+        description: "npm package name to publish (defaults to server package name)"
+        required: false
+        default: ""
+        type: string
+      prerelease:
+        description: "Create GitHub prerelease"
+        required: false
+        default: false
+        type: boolean
+      release_ui:
+        description: "Publish remote UI + manifest"
+        required: false
+        default: true
+        type: boolean
+
+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 }}
+          IS_PRERELEASE: ${{ inputs.prerelease }}
+        run: |
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Release $TAG already exists"
+          else
+            if [ "${IS_PRERELEASE}" = "true" ]; then
+              gh release create "$TAG" --title "$TAG" --generate-notes --prerelease
+            else
+              gh release create "$TAG" --title "$TAG" --generate-notes
+            fi
+          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
+
+  release-ui:
+    needs: prepare-release
+    if: ${{ inputs.release_ui }}
+    permissions:
+      contents: read
+    uses: ./.github/workflows/release-ui.yml
+    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 }}
+      package_name: ${{ inputs.npm_package_name }}
+    secrets: inherit

.gitignore

@@ -6,3 +6,10 @@ release/
 .vite/
 .electron-vite/
 out/
+.dir-locals.el
+.opencode/bashOutputs/
+
+# Local runtime artifacts
+.codenomad/
+.tmp/
+packages/cloudflare/.wrangler/

.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.

.opencode/commands/release-notes.md

@@ -0,0 +1,7 @@
+---
+description: Creates release notes
+agent: build
+---
+
+Check how I do prepare release notes here - https://github.com/NeuralNomadsAI/CodeNomad/releases/tag/v0.7.0
+Use the same format to create release notes from users perspective for new release by looking at changes from last tagged release to tip of branch

AGENTS.md

@@ -15,6 +15,35 @@
 - Prefer composable primitives (signals, hooks, utilities) over deep inheritance or implicit global state.
 - When adding platform integrations (SSE, IPC, SDK), isolate them in thin adapters that surface typed events/actions.
 
+## Multi-Language Support (i18n)
+
+The UI uses a small custom i18n layer (no ICU/messageformat). When building features, never hardcode user-visible strings.
+
+- **Runtime API:** use `useI18n()` in components (`const { t } = useI18n();`) and `tGlobal(...)` in stores/non-component code.
+  - Implementation: `packages/ui/src/lib/i18n/index.tsx`
+- **Where messages live:** `packages/ui/src/lib/i18n/messages/<locale>/` as TypeScript objects (`"flat.dot.keys": "string"`).
+  - Each locale has an `index.ts` that merges message parts; duplicate keys throw at build time.
+  - Merge helper: `packages/ui/src/lib/i18n/messages/merge.ts`
+- **Adding a new string:** add it to the appropriate `.../messages/en/*.ts` part file, then add the same key to each other locale’s corresponding file.
+  - Missing translations fall back to English (and finally to the key), so gaps can be easy to miss.
+- **Interpolation:** placeholders are simple `{name}` replacements (word characters only). Avoid placeholders like `{file-name}`.
+- **Pluralization:** handle manually via separate keys like `something.one` / `something.other` and choose in code.
+- **Adding a new language:** add a new `messages/<locale>/` folder + `index.ts`, register it in `packages/ui/src/lib/i18n/index.tsx`, and add it to the language picker in `packages/ui/src/components/folder-selection-view.tsx`.
+- **Locale persistence:** the selected locale is stored in app preferences (`locale`) and persisted via the server config (default `~/.config/codenomad/config.json`).
+- **Avoid English-only paths:** do not import `enMessages` directly in feature code; always go through `t(...)` so locale changes apply.
+
+## File Length Guidelines (Highlight Only)
+
+We track file size as a refactoring signal. When you touch or create files, highlight oversized files so the team can plan refactors when time permits.
+
+- Source files: warn after ~500 lines; target limit ~800 lines
+- Test files: highlight after ~1000 lines
+
+Behavior for agents:
+- Do not refactor solely to satisfy these thresholds.
+- When a change touches a file that exceeds the warning/limit, mention it in your final response and include the file path and approximate line count.
+- When creating new files, aim to stay under the thresholds unless there's a clear reason.
+
 ## Tooling Preferences
 - Use the `edit` tool for modifying existing files; prefer it over other editing methods.
 - Use the `write` tool only when creating new files from scratch.

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)
-2. **Bundle with Vite** → Optimized production build
+1. **Build @neuralnomads/codenomad** → Produces the CLI `dist/` bundle (also rebuilds the UI assets it serves)
+2. **Compile TypeScript + bundle with Vite** → Electron main, preload, and renderer output in `dist/`
 3. **Package with electron-builder** → Platform-specific binaries
 
 ## Output

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neural Nomads
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,58 +1,128 @@
 # 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
+```
+
+Full server/CLI documentation (flags + env vars, TLS, auth, remote access):
+- [packages/server/README.md](packages/server/README.md)
+
+To see all available options:
+
+```bash
+npx @neuralnomads/codenomad --help
+```
+
+### 🧪 Dev Releases
+Bleeding-edge builds are published as GitHub pre-releases and are generated automatically from the `dev` branch.
+
+```bash
+npx @neuralnomads/codenomad-dev --launch
+```
 
 ## Highlights
 
-- **Long-session native** – scroll through massive transcripts without hitches and keep full context visible.
-- **Multiple instances, one window** – juggle several OpenCode instances side-by-side with per-instance tabs.
-- **Deep task awareness** – jump into sub/child sessions (Tasks tool) instantly, monitor their status, and answer directly without losing your flow.
-- **Keyboard first** – the full UI is optimized for shortcuts so you can stay mouse-free when you want to.
-- **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.
+- **Multi-Instance**: Juggle several OpenCode sessions side-by-side with tabs.
+- **Long-Session Native**: Scroll through massive transcripts without hitches.
+- **Command Palette**: A single global palette to jump tabs, launch tools, and control everything.
+- **Deep Task Awareness**: Monitor background tasks and child sessions without losing flow.
 
 ## 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.
-- `packages/electron-app` — Electron main/preload processes plus packaging scripts. It consumes the UI package during development/build via `electron-vite`.
+```bash
+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
+### Linux (Wayland + NVIDIA): Tauri AppImage closes immediately
+On some Wayland compositor + NVIDIA driver setups, WebKitGTK can fail to initialize its DMA-BUF/GBM path and the Tauri build may exit right away.
 
-Grab the latest build for macOS, Windows, and Linux from the [GitHub Releases page](https://github.com/shantur/CodeNomad/releases).
+Try running with one of these environment variables:
 
-## Quick Start
+```bash
+# Most reliable workaround (can reduce rendering performance)
+WEBKIT_DISABLE_DMABUF_RENDERER=1 codenomad
 
-1. Install the OpenCode CLI and confirm it is reachable via your terminal.
-2. Download the CodeNomad build for your platform and launch the app.
-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.
+# Alternative for some Wayland setups
+__NV_DISABLE_EXPLICIT_SYNC=1 codenomad
+```
 
-## CLI Server Flags
+If you're running the Tauri AppImage and want the workaround applied every time, create a tiny wrapper script on your `PATH`:
 
-The bundled CLI server (`@codenomad/cli`) controls which folders the UI can browse when you pick a workspace:
+```bash
+#!/bin/bash
+export WEBKIT_DISABLE_DMABUF_RENDERER=1
+exec ~/.local/share/bauh/appimage/installed/codenomad/CodeNomad-Tauri-0.4.0-linux-x64.AppImage "$@"
+```
 
-- `--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.
+Upstream tracking: https://github.com/tauri-apps/tauri/issues/10702
 
-Use unrestricted mode only when you trust the host; the CLI will skip directories it cannot read and never persists the opt-in.
+## Architecture & Development
 
-### Single Port Proxying
+CodeNomad is a monorepo split into specialized packages. If you want to contribute or build from source, check out the individual package documentation:
 
-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.
+| 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. |
+
+### Quick Build
+To build the Desktop App from source:
+
+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`.
+
+[![Star History Chart](https://api.star-history.com/svg?repos=NeuralNomadsAI/CodeNomad&type=Date)](https://star-history.com/#NeuralNomadsAI/CodeNomad&Date)
 

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[]
-  status: SessionStatus
-  createdAt: number
-  updatedAt: number
+  version: string
+  time: { created: number; updated: number }
+  revert?: {
+    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,34 @@
 {
   "name": "codenomad-workspace",
-  "version": "0.1.2",
+  "version": "0.11.1",
   "private": true,
   "description": "CodeNomad monorepo workspace",
+  "license": "MIT",
   "workspaces": {
     "packages": [
-      "packages/*"
+      "packages/server",
+      "packages/ui",
+      "packages/electron-app",
+      "packages/tauri-app"
     ]
   },
   "scripts": {
-    "dev": "npm run dev --workspace @codenomad/electron-app",
-    "dev:electron": "npm run dev --workspace @codenomad/electron-app",
-    "dev:ui": "npm run dev --workspace @codenomad/ui",
-    "build": "npm run build --workspace @codenomad/electron-app",
+    "dev": "npm run dev --workspace @neuralnomads/codenomad-electron-app",
+    "dev:electron": "npm run dev --workspace @neuralnomads/codenomad-electron-app",
+    "dev:tauri": "npm run dev --workspace @codenomad/tauri-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:binaries": "npm run build:binaries --workspace @codenomad/electron-app",
-    "typecheck": "npm run typecheck --workspace @codenomad/ui && npm run typecheck --workspace @codenomad/electron-app"
+    "build:mac-x64": "npm run build:mac-x64 --workspace @neuralnomads/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 @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/.gitignore

@@ -1 +0,0 @@
-public/

packages/cli/package.json

@@ -1,33 +0,0 @@
-{
-  "name": "@codenomad/cli",
-  "version": "0.1.0",
-  "description": "CodeNomad CLI server for HTTP/SSE control plane",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "codenomad-cli": "dist/bin.js"
-  },
-  "scripts": {
-    "build": "npm run build:ui && npm run prepare-ui && tsc -p tsconfig.json",
-    "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",
-    "typecheck": "tsc --noEmit -p tsconfig.json"
-  },
-  "dependencies": {
-    "@fastify/cors": "^8.5.0",
-    "@fastify/reply-from": "^9.8.0",
-    "@fastify/static": "^7.0.4",
-    "commander": "^12.1.0",
-    "fastify": "^4.28.1",
-    "pino": "^9.4.0",
-    "undici": "^6.19.8",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "cross-env": "^7.0.3",
-    "ts-node": "^10.9.2",
-    "tsx": "^4.20.6",
-    "typescript": "^5.6.3"
-  }
-}

packages/cli/src/config/binaries.ts

@@ -1,155 +0,0 @@
-import {
-  BinaryCreateRequest,
-  BinaryRecord,
-  BinaryUpdateRequest,
-  BinaryValidationResult,
-} from "../api-types"
-import { ConfigStore } from "./store"
-import { EventBus } from "../events/bus"
-import type { ConfigFileUpdate } from "./schema"
-import { Logger } from "../logger"
-
-export class BinaryRegistry {
-  constructor(
-    private readonly configStore: ConfigStore,
-    private readonly eventBus: EventBus | undefined,
-    private readonly logger: Logger,
-  ) {}
-
-  list(): BinaryRecord[] {
-    return this.mapRecords()
-  }
-
-  resolveDefault(): BinaryRecord {
-    const binaries = this.mapRecords()
-    if (binaries.length === 0) {
-      this.logger.warn("No configured binaries found, falling back to opencode")
-      return this.buildFallbackRecord("opencode")
-    }
-    return binaries.find((binary) => binary.isDefault) ?? binaries[0]
-  }
-
-  create(request: BinaryCreateRequest): BinaryRecord {
-    this.logger.debug({ path: request.path }, "Registering OpenCode binary")
-    const entry = {
-      path: request.path,
-      version: undefined,
-      lastUsed: Date.now(),
-      label: request.label,
-    }
-
-    const config = this.configStore.get()
-    const deduped = config.opencodeBinaries.filter((binary) => binary.path !== request.path)
-
-    const update: ConfigFileUpdate = {
-      opencodeBinaries: [entry, ...deduped],
-    }
-
-    if (request.makeDefault) {
-      update.preferences = { lastUsedBinary: request.path }
-    }
-
-    this.configStore.update(update)
-    const record = this.getById(request.path)
-    this.emitChange()
-    return record
-  }
-
-  update(id: string, updates: BinaryUpdateRequest): BinaryRecord {
-    this.logger.debug({ id }, "Updating OpenCode binary")
-    const config = this.configStore.get()
-    const updatedEntries = config.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 }
-    }
-
-    this.configStore.update(update)
-    const record = this.getById(id)
-    this.emitChange()
-    return record
-  }
-
-  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 update: ConfigFileUpdate = { opencodeBinaries: remaining }
-
-    if (config.preferences.lastUsedBinary === id) {
-      update.preferences = { lastUsedBinary: remaining[0]?.path }
-    }
-
-    this.configStore.update(update)
-    this.emitChange()
-  }
-
-  validatePath(path: string): BinaryValidationResult {
-    this.logger.debug({ path }, "Validating OpenCode binary path")
-    return this.validateRecord({
-      id: path,
-      path,
-      label: this.prettyLabel(path),
-      isDefault: false,
-    })
-  }
-
-  private mapRecords(): BinaryRecord[] {
-    const config = this.configStore.get()
-    const configuredBinaries = config.opencodeBinaries.map<BinaryRecord>((binary) => ({
-      id: binary.path,
-      path: binary.path,
-      label: binary.label ?? this.prettyLabel(binary.path),
-      version: binary.version,
-      isDefault: false,
-    }))
-
-    const defaultPath = config.preferences.lastUsedBinary ?? configuredBinaries[0]?.path ?? "opencode"
-
-    const annotated = configuredBinaries.map((binary) => ({
-      ...binary,
-      isDefault: binary.path === defaultPath,
-    }))
-
-    if (!annotated.some((binary) => binary.path === defaultPath)) {
-      annotated.unshift(this.buildFallbackRecord(defaultPath))
-    }
-
-    return annotated
-  }
-
-  private getById(id: string): BinaryRecord {
-    return this.mapRecords().find((binary) => binary.id === id) ?? this.buildFallbackRecord(id)
-  }
-
-  private emitChange() {
-    this.logger.debug("Emitting binaries changed event")
-    this.eventBus?.publish({ type: "config.binariesChanged", binaries: this.mapRecords() })
-  }
-
-  private validateRecord(record: BinaryRecord): BinaryValidationResult {
-    // TODO: call actual binary -v check.
-    return { valid: true, version: record.version }
-  }
-
-  private buildFallbackRecord(path: string): BinaryRecord {
-    return {
-      id: path,
-      path,
-      label: this.prettyLabel(path),
-      isDefault: true,
-    }
-  }
-
-  private prettyLabel(path: string) {
-    const parts = path.split(/[\\/]/)
-    const last = parts[parts.length - 1] || path
-    return last || path
-  }
-}

packages/cli/src/config/schema.ts

@@ -1,80 +0,0 @@
-import { z } from "zod"
-
-const ModelPreferenceSchema = z.object({
-  providerId: z.string(),
-  modelId: z.string(),
-})
-
-const AgentModelSelectionSchema = z.record(z.string(), ModelPreferenceSchema)
-const AgentModelSelectionsSchema = z.record(z.string(), AgentModelSelectionSchema)
-
-const PreferencesSchema = z.object({
-  showThinkingBlocks: z.boolean().default(false),
-  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"),
-})
-
-const PreferencesUpdateSchema = z.object({
-  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({
-  path: z.string(),
-  lastAccessed: z.number().nonnegative(),
-})
-
-const OpenCodeBinarySchema = z.object({
-  path: z.string(),
-  version: z.string().optional(),
-  lastUsed: z.number().nonnegative(),
-  label: z.string().optional(),
-})
-
-const ConfigFileSchema = z.object({
-  preferences: PreferencesSchema.default({}),
-  recentFolders: z.array(RecentFolderSchema).default([]),
-  opencodeBinaries: z.array(OpenCodeBinarySchema).default([]),
-  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 {
-  ModelPreferenceSchema,
-  AgentModelSelectionSchema,
-  AgentModelSelectionsSchema,
-  PreferencesSchema,
-  RecentFolderSchema,
-  OpenCodeBinarySchema,
-  ConfigFileSchema,
-  ConfigFileUpdateSchema,
-  DEFAULT_CONFIG,
-}
-
-export type ModelPreference = z.infer<typeof ModelPreferenceSchema>
-export type AgentModelSelection = z.infer<typeof AgentModelSelectionSchema>
-export type AgentModelSelections = z.infer<typeof AgentModelSelectionsSchema>
-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/cli/src/config/store.ts

@@ -1,120 +0,0 @@
-import fs from "fs"
-import path from "path"
-import { EventBus } from "../events/bus"
-import { Logger } from "../logger"
-import {
-  AgentModelSelections,
-  ConfigFile,
-  ConfigFileUpdate,
-  ConfigFileSchema,
-  ConfigFileUpdateSchema,
-  DEFAULT_CONFIG,
-} from "./schema"
-
-export class ConfigStore {
-  private cache: ConfigFile = DEFAULT_CONFIG
-  private loaded = false
-
-  constructor(
-    private readonly configPath: string,
-    private readonly eventBus: EventBus | undefined,
-    private readonly logger: Logger,
-  ) {}
-
-  load(): ConfigFile {
-    if (this.loaded) {
-      return this.cache
-    }
-
-    try {
-      const resolved = this.resolvePath(this.configPath)
-      if (fs.existsSync(resolved)) {
-        const content = fs.readFileSync(resolved, "utf-8")
-        const parsed = JSON.parse(content)
-        this.cache = ConfigFileSchema.parse(parsed)
-        this.logger.debug({ resolved }, "Loaded existing config file")
-      } else {
-        this.cache = DEFAULT_CONFIG
-        this.logger.debug({ resolved }, "No config file found, using defaults")
-      }
-    } catch (error) {
-      this.logger.warn({ err: error }, "Failed to load config, using defaults")
-      this.cache = DEFAULT_CONFIG
-    }
-
-    this.loaded = true
-    return this.cache
-  }
-
-  get(): ConfigFile {
-    return this.load()
-  }
-
-  update(partial: ConfigFile | ConfigFileUpdate) {
-    const safePartial =
-      "recentFolders" in partial && "opencodeBinaries" in partial
-        ? ConfigFileSchema.parse(partial)
-        : ConfigFileUpdateSchema.parse(partial ?? {})
-    const merged = this.mergeConfig(this.load(), safePartial)
-    this.cache = ConfigFileSchema.parse(merged)
-    this.persist()
-    this.eventBus?.publish({ type: "config.appChanged", config: this.cache })
-    this.logger.debug("Config updated")
-  }
-
-  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() {
-    try {
-      const resolved = this.resolvePath(this.configPath)
-      fs.mkdirSync(path.dirname(resolved), { recursive: true })
-      fs.writeFileSync(resolved, JSON.stringify(this.cache, null, 2), "utf-8")
-      this.logger.debug({ resolved }, "Persisted config file")
-    } catch (error) {
-      this.logger.warn({ err: error }, "Failed to persist config")
-    }
-  }
-
-  private resolvePath(filePath: string) {
-    if (filePath.startsWith("~/")) {
-      return path.join(process.env.HOME ?? "", filePath.slice(2))
-    }
-    return path.resolve(filePath)
-  }
-}

packages/cli/src/index.ts

@@ -1,183 +0,0 @@
-/**
- * CLI entry point.
- * For now this only wires the typed modules together; actual command handling comes later.
- */
-import { Command, InvalidArgumentError, Option } from "commander"
-import path from "path"
-import { fileURLToPath } from "url"
-import { createRequire } from "module"
-import { createHttpServer } from "./server/http-server"
-import { WorkspaceManager } from "./workspaces/manager"
-import { ConfigStore } from "./config/store"
-import { BinaryRegistry } from "./config/binaries"
-import { FileSystemBrowser } from "./filesystem/browser"
-import { EventBus } from "./events/bus"
-import { ServerMeta } from "./api-types"
-import { InstanceStore } from "./storage/instance-store"
-import { createLogger } from "./logger"
-
-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)
-const DEFAULT_UI_STATIC_DIR = path.resolve(__dirname, "../public")
-
-interface CliOptions {
-  port: number
-  host: string
-  rootDir: string
-  configPath: string
-  unrestrictedRoot: boolean
-  logLevel?: string
-  logDestination?: string
-  uiStaticDir: string
-  uiDevServer?: string
-}
-
-const DEFAULT_PORT = 9898
-const DEFAULT_HOST = "127.0.0.1"
-const DEFAULT_CONFIG_PATH = "~/.config/codenomad/config.json"
-
-function parseCliOptions(argv: string[]): CliOptions {
-  const program = new Command()
-    .name("codenomad-cli")
-    .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))
-    .addOption(new Option("--port <number>", "Port for the HTTP server").env("CLI_PORT").default(DEFAULT_PORT).argParser(parsePort))
-    .addOption(
-      new Option("--workspace-root <path>", "Workspace root directory").env("CLI_WORKSPACE_ROOT").default(process.cwd()),
-    )
-    .addOption(new Option("--root <path>").env("CLI_ROOT").hideHelp(true))
-    .addOption(new Option("--unrestricted-root", "Allow browsing the full filesystem").env("CLI_UNRESTRICTED_ROOT").default(false))
-    .addOption(new Option("--config <path>", "Path to the config file").env("CLI_CONFIG").default(DEFAULT_CONFIG_PATH))
-    .addOption(new Option("--log-level <level>", "Log level (trace|debug|info|warn|error)").env("CLI_LOG_LEVEL"))
-    .addOption(new Option("--log-destination <path>", "Log destination file (defaults to stdout)").env("CLI_LOG_DESTINATION"))
-    .addOption(
-      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"))
-
-  program.parse(argv, { from: "user" })
-  const parsed = program.opts<{
-    host: string
-    port: number
-    workspaceRoot?: string
-    root?: string
-    unrestrictedRoot?: boolean
-    config: string
-    logLevel?: string
-    logDestination?: string
-    uiDir: string
-    uiDevServer?: string
-  }>()
-
-  const resolvedRoot = parsed.workspaceRoot ?? parsed.root ?? process.cwd()
-
-  return {
-    port: parsed.port,
-    host: parsed.host,
-    rootDir: resolvedRoot,
-    configPath: parsed.config,
-    unrestrictedRoot: Boolean(parsed.unrestrictedRoot),
-    logLevel: parsed.logLevel,
-    logDestination: parsed.logDestination,
-    uiStaticDir: parsed.uiDir,
-    uiDevServer: parsed.uiDevServer,
-  }
-}
-
-function parsePort(input: string): number {
-  const value = Number(input)
-  if (!Number.isInteger(value) || value < 1 || value > 65535) {
-    throw new InvalidArgumentError("Port must be an integer between 1 and 65535")
-  }
-  return value
-}
-
-async function main() {
-  const options = parseCliOptions(process.argv.slice(2))
-  const logger = createLogger({ level: options.logLevel, destination: options.logDestination, component: "app" })
-  const workspaceLogger = logger.child({ component: "workspace" })
-  const configLogger = logger.child({ component: "config" })
-  const eventLogger = logger.child({ component: "events" })
-
-  logger.info({ options }, "Starting CodeNomad CLI server")
-
-  const eventBus = new EventBus(eventLogger)
-  const configStore = new ConfigStore(options.configPath, eventBus, configLogger)
-  const binaryRegistry = new BinaryRegistry(configStore, eventBus, configLogger)
-  const workspaceManager = new WorkspaceManager({
-    rootDir: options.rootDir,
-    configStore,
-    binaryRegistry,
-    eventBus,
-    logger: workspaceLogger,
-  })
-  const fileSystemBrowser = new FileSystemBrowser({ rootDir: options.rootDir, unrestricted: options.unrestrictedRoot })
-  const instanceStore = new InstanceStore()
-
-  const serverMeta: ServerMeta = {
-    httpBaseUrl: `http://${options.host}:${options.port}`,
-    eventsUrl: `/api/events`,
-    hostLabel: options.host,
-    workspaceRoot: options.rootDir,
-  }
-
-  const server = createHttpServer({
-    host: options.host,
-    port: options.port,
-    workspaceManager,
-    configStore,
-    binaryRegistry,
-    fileSystemBrowser,
-    eventBus,
-    serverMeta,
-    instanceStore,
-    uiStaticDir: options.uiStaticDir,
-    uiDevServerUrl: options.uiDevServer,
-    logger,
-  })
-
-
-  await server.start()
-  logger.info({ port: options.port, host: options.host }, "HTTP server listening")
-  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
-
-  const shutdown = async () => {
-    if (shuttingDown) {
-      logger.info("Shutdown already in progress, ignoring signal")
-      return
-    }
-    shuttingDown = true
-    logger.info("Received shutdown signal, closing server")
-    try {
-      await server.stop()
-      logger.info("HTTP server stopped")
-    } catch (error) {
-      logger.error({ err: error }, "Failed to stop HTTP server")
-    }
-
-    try {
-      await workspaceManager.shutdown()
-      logger.info("Workspace manager shutdown complete")
-    } catch (error) {
-      logger.error({ err: error }, "Workspace manager shutdown failed")
-    }
-
-    logger.info("Exiting process")
-    process.exit(0)
-  }
-
-  process.on("SIGINT", shutdown)
-  process.on("SIGTERM", shutdown)
-}
-
-main().catch((error) => {
-  const logger = createLogger({ component: "app" })
-  logger.error({ err: error }, "CLI server crashed")
-  process.exit(1)
-})

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

@@ -1,262 +0,0 @@
-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 fs from "fs"
-import path from "path"
-import { fetch } from "undici"
-import type { Logger } from "../logger"
-import { WorkspaceManager } from "../workspaces/manager"
-
-import { ConfigStore } from "../config/store"
-import { BinaryRegistry } from "../config/binaries"
-import { FileSystemBrowser } from "../filesystem/browser"
-import { EventBus } from "../events/bus"
-import { registerWorkspaceRoutes } from "./routes/workspaces"
-import { registerConfigRoutes } from "./routes/config"
-import { registerFilesystemRoutes } from "./routes/filesystem"
-import { registerMetaRoutes } from "./routes/meta"
-import { registerEventRoutes } from "./routes/events"
-import { registerStorageRoutes } from "./routes/storage"
-import { ServerMeta } from "../api-types"
-import { InstanceStore } from "../storage/instance-store"
-
-interface HttpServerDeps {
-  host: string
-  port: number
-  workspaceManager: WorkspaceManager
-  configStore: ConfigStore
-  binaryRegistry: BinaryRegistry
-  fileSystemBrowser: FileSystemBrowser
-  eventBus: EventBus
-  serverMeta: ServerMeta
-  instanceStore: InstanceStore
-  uiStaticDir: string
-  uiDevServerUrl?: string
-  logger: Logger
-}
-
-
-export function createHttpServer(deps: HttpServerDeps) {
-  const app = Fastify({ logger: false })
-  const proxyLogger = deps.logger.child({ component: "proxy" })
-
-  const sseClients = new Set<() => void>()
-  const registerSseClient = (cleanup: () => void) => {
-    sseClients.add(cleanup)
-    return () => sseClients.delete(cleanup)
-  }
-  const closeSseClients = () => {
-    for (const cleanup of Array.from(sseClients)) {
-      cleanup()
-    }
-    sseClients.clear()
-  }
-
-  app.register(cors, {
-    origin: true,
-    credentials: true,
-  })
-
-  app.register(replyFrom, {
-    contentTypesToEncode: [],
-  })
-
-  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 })
-  registerStorageRoutes(app, { instanceStore: deps.instanceStore })
-  registerInstanceProxyRoutes(app, { workspaceManager: deps.workspaceManager, logger: proxyLogger })
-
-  if (deps.uiDevServerUrl) {
-    setupDevProxy(app, deps.uiDevServerUrl)
-  } else {
-    setupStaticUi(app, deps.uiStaticDir)
-  }
-
-  return {
-    instance: app,
-    start: () => app.listen({ port: deps.port, host: deps.host }),
-    stop: () => {
-      closeSseClients()
-      return app.close()
-    },
-  }
-}
-
-interface InstanceProxyDeps {
-  workspaceManager: WorkspaceManager
-  logger: Logger
-}
-
-function registerInstanceProxyRoutes(app: FastifyInstance, deps: InstanceProxyDeps) {
-  app.register(async (instance) => {
-    instance.removeAllContentTypeParsers()
-    instance.addContentTypeParser("*", (req, body, done) => done(null, body))
-
-    const proxyBaseHandler = async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
-      await proxyWorkspaceRequest({
-        request,
-        reply,
-        workspaceManager: deps.workspaceManager,
-        pathSuffix: "",
-        logger: deps.logger,
-      })
-    }
-
-    const proxyWildcardHandler = async (
-      request: FastifyRequest<{ Params: { id: string; "*": string } }>,
-      reply: FastifyReply,
-    ) => {
-      await proxyWorkspaceRequest({
-        request,
-        reply,
-        workspaceManager: deps.workspaceManager,
-        pathSuffix: request.params["*"] ?? "",
-        logger: deps.logger,
-      })
-    }
-
-    instance.all("/workspaces/:id/instance", proxyBaseHandler)
-    instance.all("/workspaces/:id/instance/*", proxyWildcardHandler)
-  })
-}
-
-const INSTANCE_PROXY_HOST = "127.0.0.1"
-
-async function proxyWorkspaceRequest(args: {
-  request: FastifyRequest
-  reply: FastifyReply
-  workspaceManager: WorkspaceManager
-  logger: Logger
-  pathSuffix?: string
-}) {
-  const { request, reply, workspaceManager, logger } = args
-  const workspaceId = (request.params as { id: string }).id
-  const workspace = workspaceManager.get(workspaceId)
-
-  if (!workspace) {
-    reply.code(404).send({ error: "Workspace not found" })
-    return
-  }
-
-  const port = workspaceManager.getInstancePort(workspaceId)
-  if (!port) {
-    reply.code(502).send({ error: "Workspace instance is not ready" })
-    return
-  }
-
-  const normalizedSuffix = normalizeInstanceSuffix(args.pathSuffix)
-  const queryIndex = (request.raw.url ?? "").indexOf("?")
-  const search = queryIndex >= 0 ? (request.raw.url ?? "").slice(queryIndex) : ""
-  const targetUrl = `http://${INSTANCE_PROXY_HOST}:${port}${normalizedSuffix}${search}`
-
-  return reply.from(targetUrl, {
-    onError: (proxyReply, { error }) => {
-      logger.error({ err: error, workspaceId, targetUrl }, "Failed to proxy workspace request")
-      if (!proxyReply.sent) {
-        proxyReply.code(502).send({ error: "Workspace instance proxy failed" })
-      }
-    },
-  })
-}
-
-function normalizeInstanceSuffix(pathSuffix: string | undefined) {
-  if (!pathSuffix || pathSuffix === "/") {
-    return "/"
-  }
-  const trimmed = pathSuffix.replace(/^\/+/, "")
-  return trimmed.length === 0 ? "/" : `/${trimmed}`
-}
-
-function setupStaticUi(app: FastifyInstance, uiDir: string) {
-  if (!uiDir) {
-    app.log.warn("UI static directory not provided; API endpoints only")
-    return
-  }
-
-  if (!fs.existsSync(uiDir)) {
-    app.log.warn({ uiDir }, "UI static directory missing; API endpoints only")
-    return
-  }
-
-  app.register(fastifyStatic, {
-    root: uiDir,
-    prefix: "/",
-    decorateReply: false,
-  })
-
-  const indexPath = path.join(uiDir, "index.html")
-
-  app.setNotFoundHandler((request: FastifyRequest, reply: FastifyReply) => {
-    const url = request.raw.url ?? ""
-    if (isApiRequest(url)) {
-      reply.code(404).send({ message: "Not Found" })
-      return
-    }
-
-    if (fs.existsSync(indexPath)) {
-      reply.type("text/html").send(fs.readFileSync(indexPath, "utf-8"))
-    } else {
-      reply.code(404).send({ message: "UI bundle missing" })
-    }
-  })
-}
-
-function setupDevProxy(app: FastifyInstance, upstreamBase: string) {
-  app.log.info({ upstreamBase }, "Proxying UI requests to development server")
-  app.setNotFoundHandler((request: FastifyRequest, reply: FastifyReply) => {
-    const url = request.raw.url ?? ""
-    if (isApiRequest(url)) {
-      reply.code(404).send({ message: "Not Found" })
-      return
-    }
-    void proxyToDevServer(request, reply, upstreamBase)
-  })
-}
-
-async function proxyToDevServer(request: FastifyRequest, reply: FastifyReply, upstreamBase: string) {
-  try {
-    const targetUrl = new URL(request.raw.url ?? "/", upstreamBase)
-    const response = await fetch(targetUrl, {
-      method: request.method,
-      headers: buildProxyHeaders(request.headers),
-    })
-
-    response.headers.forEach((value, key) => {
-      reply.header(key, value)
-    })
-
-    reply.code(response.status)
-
-    if (!response.body || request.method === "HEAD") {
-      reply.send()
-      return
-    }
-
-    const buffer = Buffer.from(await response.arrayBuffer())
-    reply.send(buffer)
-  } catch (error) {
-    request.log.error({ err: error }, "Failed to proxy UI request to dev server")
-    if (!reply.sent) {
-      reply.code(502).send("UI dev server is unavailable")
-    }
-  }
-}
-
-function isApiRequest(rawUrl: string | null | undefined) {
-  if (!rawUrl) return false
-  const pathname = rawUrl.split("?")[0] ?? ""
-  return pathname === "/api" || pathname.startsWith("/api/")
-}
-
-function buildProxyHeaders(headers: FastifyRequest["headers"]): Record<string, string> {
-  const result: Record<string, string> = {}
-  for (const [key, value] of Object.entries(headers ?? {})) {
-    if (!value || key.toLowerCase() === "host") continue
-    result[key] = Array.isArray(value) ? value.join(",") : value
-  }
-  return result
-}

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

@@ -1,68 +0,0 @@
-import { FastifyInstance } from "fastify"
-import { z } from "zod"
-import { ConfigStore } from "../../config/store"
-import { BinaryRegistry } from "../../config/binaries"
-import { ConfigFileSchema, ConfigFileUpdateSchema } from "../../config/schema"
-
-interface RouteDeps {
-  configStore: ConfigStore
-  binaryRegistry: BinaryRegistry
-}
-
-const BinaryCreateSchema = z.object({
-  path: z.string(),
-  label: z.string().optional(),
-  makeDefault: z.boolean().optional(),
-})
-
-const BinaryUpdateSchema = z.object({
-  label: z.string().optional(),
-  makeDefault: z.boolean().optional(),
-})
-
-const BinaryValidateSchema = z.object({
-  path: z.string(),
-})
-
-export function registerConfigRoutes(app: FastifyInstance, deps: RouteDeps) {
-  app.get("/api/config/app", async () => deps.configStore.get())
-
-  app.put("/api/config/app", async (request) => {
-    const body = ConfigFileSchema.parse(request.body ?? {})
-    deps.configStore.update(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()
-  })
-
-  app.get("/api/config/binaries", async () => {
-    return { binaries: deps.binaryRegistry.list() }
-  })
-
-  app.post("/api/config/binaries", async (request, reply) => {
-    const body = BinaryCreateSchema.parse(request.body ?? {})
-    const binary = deps.binaryRegistry.create(body)
-    reply.code(201)
-    return { binary }
-  })
-
-  app.patch<{ Params: { id: string } }>("/api/config/binaries/:id", async (request) => {
-    const body = BinaryUpdateSchema.parse(request.body ?? {})
-    const binary = deps.binaryRegistry.update(request.params.id, body)
-    return { binary }
-  })
-
-  app.delete<{ Params: { id: string } }>("/api/config/binaries/:id", async (request, reply) => {
-    deps.binaryRegistry.remove(request.params.id)
-    reply.code(204)
-  })
-
-  app.post("/api/config/binaries/validate", async (request) => {
-    const body = BinaryValidateSchema.parse(request.body ?? {})
-    return deps.binaryRegistry.validatePath(body.path)
-  })
-}

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

@@ -1,27 +0,0 @@
-import { FastifyInstance } from "fastify"
-import { z } from "zod"
-import { FileSystemBrowser } from "../../filesystem/browser"
-
-interface RouteDeps {
-  fileSystemBrowser: FileSystemBrowser
-}
-
-const FilesystemQuerySchema = z.object({
-  path: z.string().optional(),
-  includeFiles: z.coerce.boolean().optional(),
-})
-
-export function registerFilesystemRoutes(app: FastifyInstance, deps: RouteDeps) {
-  app.get("/api/filesystem", async (request, reply) => {
-    const query = FilesystemQuerySchema.parse(request.query ?? {})
-
-    try {
-      return deps.fileSystemBrowser.browse(query.path, {
-        includeFiles: query.includeFiles,
-      })
-    } catch (error) {
-      reply.code(400)
-      return { error: (error as Error).message }
-    }
-  })
-}

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/cli/src/workspaces/runtime.ts

@@ -1,214 +0,0 @@
-import { ChildProcess, spawn } from "child_process"
-import { existsSync, statSync } from "fs"
-import path from "path"
-import { EventBus } from "../events/bus"
-import { LogLevel, WorkspaceLogEntry } from "../api-types"
-import { Logger } from "../logger"
-
-interface LaunchOptions {
-  workspaceId: string
-  folder: string
-  binaryPath: string
-  environment?: Record<string, string>
-  onExit?: (info: ProcessExitInfo) => void
-}
-
-interface ProcessExitInfo {
-  workspaceId: string
-  code: number | null
-  signal: NodeJS.Signals | null
-  requested: boolean
-}
-
-interface ManagedProcess {
-  child: ChildProcess
-  requestedStop: boolean
-}
-
-export class WorkspaceRuntime {
-  private processes = new Map<string, ManagedProcess>()
-
-  constructor(private readonly eventBus: EventBus, private readonly logger: Logger) {}
-
-  async launch(options: LaunchOptions): Promise<{ pid: number; port: number }> {
-    this.validateFolder(options.folder)
-
-    const args = ["serve", "--port", "0", "--print-logs", "--log-level", "DEBUG"]
-    const env = { ...process.env, ...(options.environment ?? {}) }
-
-    return new Promise((resolve, reject) => {
-      this.logger.info({ workspaceId: options.workspaceId, folder: options.folder }, "Launching OpenCode process")
-      const child = spawn(options.binaryPath, args, {
-        cwd: options.folder,
-        env,
-        stdio: ["ignore", "pipe", "pipe"],
-      })
-
-      const managed: ManagedProcess = { child, requestedStop: false }
-      this.processes.set(options.workspaceId, managed)
-
-      let stdoutBuffer = ""
-      let stderrBuffer = ""
-      let portFound = false
-
-      let warningTimer: NodeJS.Timeout | null = null
-
-      const startWarningTimer = () => {
-        warningTimer = setInterval(() => {
-          this.logger.warn({ workspaceId: options.workspaceId }, "Workspace runtime has not reported a port yet")
-        }, 10000)
-      }
-
-      const stopWarningTimer = () => {
-        if (warningTimer) {
-          clearInterval(warningTimer)
-          warningTimer = null
-        }
-      }
-
-      startWarningTimer()
-
-      const cleanupStreams = () => {
-        stopWarningTimer()
-        child.stdout?.removeAllListeners()
-        child.stderr?.removeAllListeners()
-      }
-
-      const handleExit = (code: number | null, signal: NodeJS.Signals | null) => {
-        this.logger.info({ workspaceId: options.workspaceId, code, signal }, "OpenCode process exited")
-        this.processes.delete(options.workspaceId)
-        cleanupStreams()
-        child.removeListener("error", handleError)
-        child.removeListener("exit", handleExit)
-        if (!portFound) {
-          const reason = stderrBuffer || `Process exited with code ${code}`
-          reject(new Error(reason))
-        } else {
-          options.onExit?.({ workspaceId: options.workspaceId, code, signal, requested: managed.requestedStop })
-        }
-      }
-
-      const handleError = (error: Error) => {
-        cleanupStreams()
-        child.removeListener("exit", handleExit)
-        this.processes.delete(options.workspaceId)
-        this.logger.error({ workspaceId: options.workspaceId, err: error }, "Workspace runtime error")
-        reject(error)
-      }
-
-      child.on("error", handleError)
-      child.on("exit", handleExit)
-
-      child.stdout?.on("data", (data: Buffer) => {
-        const text = data.toString()
-        stdoutBuffer += text
-        const lines = stdoutBuffer.split("\n")
-        stdoutBuffer = lines.pop() ?? ""
-
-        for (const line of lines) {
-          if (!line.trim()) continue
-          this.emitLog(options.workspaceId, "info", line)
-
-          if (!portFound) {
-            const portMatch = line.match(/opencode server listening on http:\/\/.+:(\d+)/i)
-            if (portMatch) {
-              portFound = true
-              cleanupStreams()
-              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 })
-            }
-          }
-        }
-      })
-
-      child.stderr?.on("data", (data: Buffer) => {
-        const text = data.toString()
-        stderrBuffer += text
-        const lines = stderrBuffer.split("\n")
-        stderrBuffer = lines.pop() ?? ""
-
-        for (const line of lines) {
-          if (!line.trim()) continue
-          this.emitLog(options.workspaceId, "error", line)
-        }
-      })
-    })
-  }
-
-  async stop(workspaceId: string): Promise<void> {
-    const managed = this.processes.get(workspaceId)
-    if (!managed) return
-
-    managed.requestedStop = true
-    const child = managed.child
-    this.logger.info({ workspaceId }, "Stopping OpenCode process")
-
-    await new Promise<void>((resolve, reject) => {
-      const cleanup = () => {
-        child.removeListener("exit", onExit)
-        child.removeListener("error", onError)
-      }
-
-      const onExit = () => {
-        cleanup()
-        resolve()
-      }
-      const onError = (error: Error) => {
-        cleanup()
-        reject(error)
-      }
-
-      const resolveIfAlreadyExited = () => {
-        if (child.exitCode !== null || child.signalCode !== null) {
-          this.logger.debug({ workspaceId, exitCode: child.exitCode, signal: child.signalCode }, "Process already exited")
-          cleanup()
-          resolve()
-          return true
-        }
-        return false
-      }
-
-      child.once("exit", onExit)
-      child.once("error", onError)
-
-      if (resolveIfAlreadyExited()) {
-        return
-      }
-
-      this.logger.debug({ workspaceId }, "Sending SIGTERM to workspace process")
-      child.kill("SIGTERM")
-      setTimeout(() => {
-        if (!child.killed) {
-          this.logger.warn({ workspaceId }, "Process did not stop after SIGTERM, force killing")
-          child.kill("SIGKILL")
-        } else {
-          this.logger.debug({ workspaceId }, "Workspace process stopped gracefully before SIGKILL timeout")
-        }
-      }, 2000)
-    })
-  }
-
-  private emitLog(workspaceId: string, level: LogLevel, message: string) {
-    const entry: WorkspaceLogEntry = {
-      workspaceId,
-      timestamp: new Date().toISOString(),
-      level,
-      message: message.trim(),
-    }
-
-    this.eventBus.publish({ type: "workspace.log", entry })
-  }
-
-  private validateFolder(folder: string) {
-    const resolved = path.resolve(folder)
-    if (!existsSync(resolved)) {
-      throw new Error(`Folder does not exist: ${resolved}`)
-    }
-    const stats = statSync(resolved)
-    if (!stats.isDirectory()) {
-      throw new Error(`Path is not a directory: ${resolved}`)
-    }
-  }
-}

packages/cloudflare/.gitignore

@@ -0,0 +1 @@
+dist/

packages/cloudflare/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@codenomad/ui-host-worker",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build:manifest": "node ./scripts/build-manifest.mjs",
+    "release:ui": "node ./scripts/release-ui.mjs",
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy"
+  },
+  "devDependencies": {
+    "wrangler": "^4.0.0"
+  }
+}

packages/cloudflare/release-config.json

@@ -0,0 +1,4 @@
+{
+  "minServerVersion": "0.11.1",
+  "latestServerUrl": "https://github.com/NeuralNomadsAI/CodeNomad/releases/latest"
+}

packages/cloudflare/scripts/build-manifest.mjs

@@ -0,0 +1,83 @@
+import { createHash } from "crypto"
+import fs from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const root = path.resolve(__dirname, "..")
+const repoRoot = path.resolve(root, "..", "..")
+
+const releaseConfigPath = path.join(root, "release-config.json")
+const uiPackageJsonPath = path.join(repoRoot, "packages/ui/package.json")
+const serverPackageJsonPath = path.join(repoRoot, "packages/server/package.json")
+
+const distDir = path.join(root, "dist")
+const manifestPath = path.join(distDir, "version.json")
+
+const args = new Set(process.argv.slice(2))
+
+function getArgValue(flag) {
+  const idx = process.argv.indexOf(flag)
+  if (idx === -1) return null
+  return process.argv[idx + 1] ?? null
+}
+
+const zipPath = getArgValue("--zip")
+
+if (!zipPath) {
+  console.error("Usage: node scripts/build-manifest.mjs --zip <path-to-ui-zip>")
+  process.exit(1)
+}
+
+const resolvedZipPath = path.resolve(process.cwd(), zipPath)
+if (!fs.existsSync(resolvedZipPath)) {
+  console.error(`Zip not found: ${resolvedZipPath}`)
+  process.exit(1)
+}
+
+const releaseConfig = JSON.parse(fs.readFileSync(releaseConfigPath, "utf-8"))
+const uiPackageJson = JSON.parse(fs.readFileSync(uiPackageJsonPath, "utf-8"))
+const serverPackageJson = JSON.parse(fs.readFileSync(serverPackageJsonPath, "utf-8"))
+
+const bucket = process.env.CODENOMAD_R2_BUCKET
+
+if (!bucket) {
+  console.error("Missing env var: CODENOMAD_R2_BUCKET")
+  process.exit(1)
+}
+
+const uiVersion = uiPackageJson.version
+const serverVersion = serverPackageJson.version
+
+if (!uiVersion || !serverVersion) {
+  console.error("Missing version fields in package.json")
+  process.exit(1)
+}
+
+const sha256 = createHash("sha256").update(fs.readFileSync(resolvedZipPath)).digest("hex")
+
+const uiPackageURL = `https://download.codenomad.neuralnomads.ai/ui/ui-${uiVersion}.zip`
+
+const manifest = {
+  minServerVersion: releaseConfig.minServerVersion,
+  latestUIVersion: uiVersion,
+  uiPackageURL,
+  sha256,
+  latestServerVersion: serverVersion,
+  latestServerUrl: releaseConfig.latestServerUrl,
+}
+
+fs.mkdirSync(distDir, { recursive: true })
+fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8")
+
+const headersPath = path.join(distDir, "_headers")
+fs.writeFileSync(
+  headersPath,
+  "/version.json\n  Cache-Control: no-cache\n  Content-Type: application/json; charset=utf-8\n",
+  "utf-8",
+)
+
+console.log(`Wrote ${manifestPath}`)
+console.log(`Wrote ${headersPath}`)

packages/cloudflare/scripts/release-ui.mjs

@@ -0,0 +1,81 @@
+import { execFileSync } from "child_process"
+import fs from "fs"
+import os from "os"
+import path from "path"
+import { fileURLToPath } from "url"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const root = path.resolve(__dirname, "..")
+const repoRoot = path.resolve(root, "..", "..")
+
+const r2Bucket = process.env.CODENOMAD_R2_BUCKET
+
+if (!r2Bucket) {
+  console.error("Missing env var: CODENOMAD_R2_BUCKET")
+  process.exit(1)
+}
+
+const uiPackageJsonPath = path.join(repoRoot, "packages/ui/package.json")
+const uiPackageJson = JSON.parse(fs.readFileSync(uiPackageJsonPath, "utf-8"))
+const uiVersion = uiPackageJson.version
+
+if (!uiVersion) {
+  console.error("Missing packages/ui/package.json version")
+  process.exit(1)
+}
+
+const uiBuildDir = path.join(repoRoot, "packages/ui/src/renderer/dist")
+if (!fs.existsSync(uiBuildDir)) {
+  console.error(`Missing UI build dir: ${uiBuildDir}. Run UI build first.`)
+  process.exit(1)
+}
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "codenomad-ui-release-"))
+const zipPath = path.join(tmpDir, `ui-${uiVersion}.zip`)
+
+try {
+  // Zip the CONTENTS of the dist dir (so index.html is at zip root).
+  execFileSync("/usr/bin/zip", ["-q", "-r", zipPath, "."], { cwd: uiBuildDir, stdio: "inherit" })
+
+  // Upload to R2.
+  const objectKey = `ui/ui-${uiVersion}.zip`
+  console.log(`[release-ui] Uploading ${zipPath} -> r2://${r2Bucket}/${objectKey}`)
+
+  execFileSync(
+    "npx",
+    ["wrangler", "r2", "object", "put", "--remote", `${r2Bucket}/${objectKey}`, "--file", zipPath],
+    { cwd: root, stdio: "inherit" },
+  )
+
+  // Generate version.json into packages/cloudflare/dist
+  console.log("[release-ui] Generating version.json")
+  execFileSync(
+    process.execPath,
+    [path.join(root, "scripts/build-manifest.mjs"), "--zip", zipPath],
+    {
+      cwd: root,
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        CODENOMAD_R2_BUCKET: r2Bucket,
+      },
+    },
+  )
+
+  console.log("[release-ui] Deploying worker")
+  execFileSync("npx", ["wrangler", "deploy"], {
+    cwd: root,
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      CLOUDFLARE_API_TOKEN: process.env.CLOUDFLARE_API_TOKEN,
+      CLOUDFLARE_ACCOUNT_ID: process.env.CLOUDFLARE_ACCOUNT_ID,
+    },
+  })
+
+  console.log("[release-ui] Done")
+} finally {
+  fs.rmSync(tmpDir, { recursive: true, force: true })
+}

packages/cloudflare/src/index.ts

@@ -0,0 +1,9 @@
+export interface Env {
+  ASSETS: { fetch: (request: Request) => Promise<Response> }
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return env.ASSETS.fetch(request)
+  },
+}

packages/cloudflare/wrangler.toml

@@ -0,0 +1,14 @@
+name = "codenomad-ui-host"
+main = "src/index.ts"
+compatibility_date = "2026-01-22"
+
+# Custom domain for the manifest host.
+# Note: Custom domains apply to all paths on the hostname.
+[[routes]]
+pattern = "ui.codenomad.neuralnomads.ai"
+custom_domain = true
+
+[assets]
+directory = "./dist"
+binding = "ASSETS"
+not_found_handling = "404-page"

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

@@ -1,11 +1,39 @@
 import { defineConfig, externalizeDepsPlugin } from "electron-vite"
 import solid from "vite-plugin-solid"
 import { resolve } from "path"
+import { copyMonacoPublicAssets } from "../ui/scripts/monaco-public-assets.js"
 
 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")
+
+function prepareMonacoPublicAssets() {
+  return {
+    name: "prepare-monaco-public-assets",
+    configureServer(server: any) {
+      copyMonacoPublicAssets({
+        uiRendererRoot: uiRendererRoot,
+        warn: (msg: string) => server.config.logger.warn(msg),
+        sourceRoots: [
+          resolve(__dirname, "../../node_modules/monaco-editor/min/vs"),
+          resolve(uiRoot, "node_modules/monaco-editor/min/vs"),
+        ],
+      })
+    },
+    buildStart(this: any) {
+      copyMonacoPublicAssets({
+        uiRendererRoot: uiRendererRoot,
+        warn: (msg: string) => this.warn(msg),
+        sourceRoots: [
+          resolve(__dirname, "../../node_modules/monaco-editor/min/vs"),
+          resolve(uiRoot, "node_modules/monaco-editor/min/vs"),
+        ],
+      })
+    },
+  }
+}
 
 export default defineConfig({
   main: {
@@ -25,7 +53,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",
       },
@@ -39,7 +67,7 @@ export default defineConfig({
   },
   renderer: {
     root: uiRendererRoot,
-    plugins: [solid()],
+    plugins: [solid(), prepareMonacoPublicAssets()],
     css: {
       postcss: resolve(uiRoot, "postcss.config.js"),
     },
@@ -52,9 +80,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,113 @@
-import { ipcMain, BrowserWindow, dialog } from "electron"
-import { processManager } 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"
+import { BrowserWindow, Notification, dialog, ipcMain, powerSaveBlocker, type OpenDialogOptions } from "electron"
+import type { CliProcessManager, CliStatus } from "./process-manager"
 
-interface Instance {
-  id: string
-  folder: string
-  port: number
-  pid: number
-  status: "starting" | "ready" | "error" | "stopped"
-  error?: string
+let wakeLockId: number | null = null
+
+interface DialogOpenRequest {
+  mode: "directory" | "file"
+  title?: string
+  defaultPath?: string
+  filters?: Array<{ name?: string; extensions: string[] }>
 }
 
-const instances = new Map<string, Instance>()
-
-function generateId(): string {
-  return randomBytes(16).toString("hex")
+interface DialogOpenResult {
+  canceled: boolean
+  paths: string[]
 }
 
-function runBinaryVersion(binaryPath: string, timeoutMs = 5000): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const child = spawn(binaryPath, ["-v"], {
-      stdio: ["ignore", "pipe", "pipe"],
-    })
-
-    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}`))
-      }
-    })
+export function setupCliIPC(mainWindow: BrowserWindow, cliManager: CliProcessManager) {
+  cliManager.on("status", (status: CliStatus) => {
+    if (!mainWindow.isDestroyed()) {
+      mainWindow.webContents.send("cli:status", status)
+    }
   })
-}
 
-export function setupInstanceIPC(mainWindow: BrowserWindow) {
-  processManager.setMainWindow(mainWindow)
+  cliManager.on("ready", (status: CliStatus) => {
+    if (!mainWindow.isDestroyed()) {
+      mainWindow.webContents.send("cli:ready", status)
+    }
+  })
 
-  ipcMain.handle("dialog:selectFolder", async () => {
-    const result = await dialog.showOpenDialog(mainWindow!, {
-      title: "Select Project Folder",
-      properties: ["openDirectory"],
-    })
+  cliManager.on("error", (error: Error) => {
+    if (!mainWindow.isDestroyed()) {
+      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 () => {
+    const devMode = process.env.NODE_ENV === "development"
+    await cliManager.stop()
+    return cliManager.start({ dev: devMode })
+  })
+
+  ipcMain.handle("dialog:open", async (_, request: DialogOpenRequest): Promise<DialogOpenResult> => {
+    const properties: OpenDialogOptions["properties"] =
+      request.mode === "directory" ? ["openDirectory", "createDirectory"] : ["openFile"]
+
+    const filters = request.filters?.map((filter) => ({
+      name: filter.name ?? "Files",
+      extensions: filter.extensions,
+    }))
+
+    const windowTarget = mainWindow.isDestroyed() ? undefined : mainWindow
+    const dialogOptions: OpenDialogOptions = {
+      title: request.title,
+      defaultPath: request.defaultPath,
+      properties,
+      filters,
+    }
+    const result = windowTarget
+      ? await dialog.showOpenDialog(windowTarget, dialogOptions)
+      : await dialog.showOpenDialog(dialogOptions)
+
+    return { canceled: result.canceled, paths: result.filePaths }
+  })
+
+  ipcMain.handle("power:setWakeLock", async (_event, enabled: boolean): Promise<{ enabled: boolean }> => {
+    const next = Boolean(enabled)
+    if (next) {
+      if (wakeLockId !== null && powerSaveBlocker.isStarted(wakeLockId)) {
+        return { enabled: true }
+      }
+      try {
+        wakeLockId = powerSaveBlocker.start("prevent-display-sleep")
+      } catch {
+        wakeLockId = null
+        return { enabled: false }
+      }
+      return { enabled: true }
     }
 
-    return result.filePaths[0]
+    if (wakeLockId !== null) {
+      try {
+        if (powerSaveBlocker.isStarted(wakeLockId)) {
+          powerSaveBlocker.stop(wakeLockId)
+        }
+      } finally {
+        wakeLockId = null
+      }
+    }
+    return { enabled: false }
   })
 
   ipcMain.handle(
-    "instance:create",
-    async (event, id: string, folder: string, binaryPath?: string, environmentVariables?: Record<string, string>) => {
-      const instance: Instance = {
-        id,
-        folder,
-        port: 0,
-        pid: 0,
-        status: "starting",
+    "notifications:show",
+    async (_event, payload: { title?: unknown; body?: unknown }): Promise<{ ok: boolean; reason?: string }> => {
+      if (!Notification.isSupported()) {
+        return { ok: false, reason: "unsupported" }
       }
 
-      instances.set(id, instance)
-
+      const title = typeof payload?.title === "string" ? payload.title : "CodeNomad"
+      const body = typeof payload?.body === "string" ? payload.body : ""
       try {
-        const {
-          pid,
-          port,
-          binaryPath: actualBinaryPath,
-        } = await processManager.spawn(folder, id, binaryPath, environmentVariables)
-
-        instance.port = port
-        instance.pid = pid
-        instance.status = "ready"
-
-        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 }
+        const notification = new Notification({ title, body })
+        notification.show()
+        return { ok: true }
       } 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
+        return { ok: false, reason: error instanceof Error ? error.message : String(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,193 @@
-import { app, BrowserWindow, dialog, ipcMain, nativeImage, nativeTheme, session } from "electron"
-import { join } from "path"
+import { app, BrowserView, BrowserWindow, nativeImage, session, shell } from "electron"
+import http from "node:http"
+import https from "node:https"
+import { existsSync } from "fs"
+import { dirname, join } from "path"
+import { fileURLToPath } from "url"
 import { createApplicationMenu } from "./menu"
-import { setupInstanceIPC } from "./ipc"
-import { setupStorageIPC } from "./storage"
+import { setupCliIPC } from "./ipc"
+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 pendingBootstrapToken: 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 +199,277 @@ 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()
-  } else {
-    mainWindow.loadFile(join(__dirname, "../renderer/index.html"))
+    mainWindow.webContents.openDevTools({ mode: "detach" })
   }
 
   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 isBootstrapTokenUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url)
+    return parsed.pathname === "/auth/token" && parsed.hash.length > 1
+  } catch {
+    return false
+  }
+}
+
+function startCliPreload(url: string) {
+  if (!mainWindow || mainWindow.isDestroyed()) {
+    pendingCliUrl = url
+    return
+  }
+
+  if (currentCliUrl === url && !showingLoadingScreen) {
+    return
+  }
+
+  pendingCliUrl = url
+  destroyPreloadingView()
+
+  if (!showingLoadingScreen) {
+    showLoadingScreen(true)
+  }
+
+  // Important: /auth/token#... is one-time. Preloading + swapping would load it twice,
+  // consuming the token in the hidden view and then failing in the main window.
+  if (isBootstrapTokenUrl(url)) {
+    finalizeCliSwap(url)
+    return
+  }
+
+  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))
+}
+
+const SESSION_COOKIE_NAME = "codenomad_session"
+let bootstrapExchangeInFlight = false
+
+function extractCookieValue(setCookieHeader: string | string[] | undefined, name: string): string | null {
+  const raw = Array.isArray(setCookieHeader) ? setCookieHeader[0] : setCookieHeader
+  if (!raw) return null
+
+  const first = raw.split(";")[0] ?? ""
+  const index = first.indexOf("=")
+  if (index < 0) return null
+
+  const key = first.slice(0, index).trim()
+  const value = first.slice(index + 1).trim()
+  if (key !== name || !value) return null
+
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
+async function exchangeBootstrapToken(baseUrl: string, token: string): Promise<boolean> {
+  const target = new URL("/api/auth/token", baseUrl)
+  const body = JSON.stringify({ token })
+
+  const transport = target.protocol === "https:" ? https : http
+
+  const result = await new Promise<{ statusCode: number; setCookie: string | string[] | undefined }>((resolve, reject) => {
+    const req = transport.request(
+      target,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(body),
+        },
+      },
+      (res) => {
+        res.resume()
+        resolve({ statusCode: res.statusCode ?? 0, setCookie: res.headers["set-cookie"] })
+      },
+    )
+
+    req.on("error", reject)
+    req.write(body)
+    req.end()
+  })
+
+  if (result.statusCode !== 200) {
+    return false
+  }
+
+  const sessionId = extractCookieValue(result.setCookie, SESSION_COOKIE_NAME)
+  if (!sessionId) {
+    return false
+  }
+
+  await session.defaultSession.cookies.set({
+    url: baseUrl,
+    name: SESSION_COOKIE_NAME,
+    value: sessionId,
+    httpOnly: true,
+    path: "/",
+    sameSite: "lax",
+  })
+
+  return true
+}
+
+async function startCli() {
+  try {
+    // In desktop dev workflows we always want the CLI to run in dev mode so it:
+    // - uses plain HTTP
+    // - proxies UI requests to the renderer dev server
+    // Monaco's AMD assets are served from that dev server.
+    const devMode = !app.isPackaged
+    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 })
+    }
+  }
+}
+
+async function maybeExchangeAndNavigate(baseUrl: string) {
+  if (bootstrapExchangeInFlight) {
+    return
+  }
+
+  const token = pendingBootstrapToken
+  if (!token) {
+    startCliPreload(baseUrl)
+    return
+  }
+
+  bootstrapExchangeInFlight = true
+
+  try {
+    const ok = await exchangeBootstrapToken(baseUrl, token)
+    pendingBootstrapToken = null
+
+    if (!ok) {
+      startCliPreload(`${baseUrl}/login`)
+      return
+    }
+
+    startCliPreload(baseUrl)
+  } catch (error) {
+    console.error("[cli] bootstrap token exchange failed:", error)
+    pendingBootstrapToken = null
+    startCliPreload(`${baseUrl}/login`)
+  } finally {
+    bootstrapExchangeInFlight = false
+  }
+}
+
+cliManager.on("bootstrapToken", (token) => {
+  pendingBootstrapToken = token
+
+  const status = cliManager.getStatus()
+  if (status.url) {
+    void maybeExchangeAndNavigate(status.url)
+  }
+})
+
+cliManager.on("ready", (status) => {
+  if (!status.url) {
+    return
+  }
+
+  void maybeExchangeAndNavigate(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 +477,16 @@ if (isMac) {
 }
 
 app.whenReady().then(() => {
+  // Required for Windows notifications / taskbar grouping.
+  // Keep in sync with desktop app identifier.
+  try {
+    app.setAppUserModelId("ai.neuralnomads.codenomad.client")
+  } catch {
+    // ignore
+  }
+
+  startCli()
+
   if (isMac) {
     session.defaultSession.setSpellCheckerEnabled(false)
     app.on("browser-window-created", (_, window) => {
@@ -84,8 +501,6 @@ app.whenReady().then(() => {
     }
   }
 
-  console.log("[spellcheck] default session enabled:", session.defaultSession.isSpellCheckerEnabled())
-
   createWindow()
 
   app.on("activate", () => {
@@ -95,8 +510,13 @@ app.whenReady().then(() => {
   })
 })
 
-app.on("window-all-closed", () => {
-  if (process.platform !== "darwin") {
-    app.quit()
-  }
+app.on("before-quit", async (event) => {
+  event.preventDefault()
+  await cliManager.stop().catch(() => {})
+  app.exit(0)
+})
+
+app.on("window-all-closed", () => {
+  // CodeNomad supports a single window; closing it should quit the app on all platforms.
+  app.quit()
 })

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

@@ -1,353 +1,520 @@
-import { spawn, execSync, ChildProcess } from "child_process"
-import { app, BrowserWindow } from "electron"
-import { existsSync, statSync } from "fs"
-import { buildUserShellCommand, getUserShellEnv, runUserShellCommandSync, supportsUserShell } from "./user-shell"
+import { spawn, spawnSync, type ChildProcess } from "child_process"
+import { app } from "electron"
+import { createRequire } from "module"
+import { EventEmitter } from "events"
+import { existsSync, readFileSync } from "fs"
+import os from "os"
+import path from "path"
+import { parse as parseYaml } from "yaml"
+import { buildUserShellCommand, getUserShellEnv, supportsUserShell } from "./user-shell"
 
-export interface ProcessInfo {
-  pid: number
-  port: number
-  binaryPath: string
+const nodeRequire = createRequire(import.meta.url)
+
+const BOOTSTRAP_TOKEN_PREFIX = "CODENOMAD_BOOTSTRAP_TOKEN:"
+
+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 {
-  pid: number
-  port: number
-  folder: string
-  startTime: number
-  childProcess: ChildProcess
-  logs: string[]
-  instanceId: string
+export interface CliLogEntry {
+  stream: "stdout" | "stderr"
+  message: string
 }
 
-class ProcessManager {
-  private processes = new Map<number, ProcessMeta>()
-  private mainWindow: BrowserWindow | null = null
+interface StartOptions {
+  dev: boolean
+}
 
-  setMainWindow(window: BrowserWindow) {
-    this.mainWindow = window
+interface CliEntryResolution {
+  entry: string
+  runner: "node" | "tsx"
+  runnerPath?: string
+}
+
+const DEFAULT_CONFIG_PATH = "~/.config/codenomad/config.json"
+
+function isYamlPath(filePath: string): boolean {
+  const lower = filePath.toLowerCase()
+  return lower.endsWith(".yaml") || lower.endsWith(".yml")
+}
+
+function isJsonPath(filePath: string): boolean {
+  return filePath.toLowerCase().endsWith(".json")
+}
+
+function resolveConfigPaths(raw?: string): { configYamlPath: string; legacyJsonPath: string } {
+  const target = raw && raw.trim().length > 0 ? raw.trim() : DEFAULT_CONFIG_PATH
+  const resolved = resolveConfigPath(target)
+
+  if (isYamlPath(resolved)) {
+    const baseDir = path.dirname(resolved)
+    return { configYamlPath: resolved, legacyJsonPath: path.join(baseDir, "config.json") }
   }
 
-  private parseLogLevel(message: string): "info" | "error" | "warn" | "debug" {
-    const upperMessage = message.toUpperCase()
-    if (upperMessage.includes("[ERROR]") || upperMessage.includes("ERROR:")) return "error"
-    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"
+  if (isJsonPath(resolved)) {
+    const baseDir = path.dirname(resolved)
+    return { configYamlPath: path.join(baseDir, "config.yaml"), legacyJsonPath: resolved }
   }
 
-  private sendLog(instanceId: string, level: "info" | "error" | "warn" | "debug", message: string) {
-    if (this.mainWindow && message.trim()) {
-      const parsedLevel = this.parseLogLevel(message)
-      this.mainWindow.webContents.send("instance:log", {
-        id: instanceId,
-        entry: {
-          timestamp: Date.now(),
-          level: parsedLevel,
-          message: message.trim(),
-        },
-      })
-    }
+  // Treat as directory.
+  return {
+    configYamlPath: path.join(resolved, "config.yaml"),
+    legacyJsonPath: path.join(resolved, "config.json"),
   }
+}
 
-  async spawn(
-    folder: string,
-    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)
-    }
+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)
+}
 
-    const env = useUserShell ? getUserShellEnv() : { ...process.env }
-    if (environmentVariables) {
-      Object.assign(env, environmentVariables)
-      this.sendLog(
-        instanceId,
-        "info",
-        `Using ${Object.keys(environmentVariables).length} custom environment variables:`,
-      )
+function resolveHostForMode(mode: ListeningMode): string {
+  return mode === "local" ? "127.0.0.1" : "0.0.0.0"
+}
 
-      // Log each environment variable
-      for (const [key, value] of Object.entries(environmentVariables)) {
-        this.sendLog(instanceId, "info", `  ${key}=${value}`)
-      }
-    }
+function readListeningModeFromConfig(): ListeningMode {
+  try {
+    const { configYamlPath, legacyJsonPath } = resolveConfigPaths(process.env.CLI_CONFIG)
 
-    let targetBinary: string
-    if (!binaryPath || binaryPath === "opencode") {
-      targetBinary = useUserShell ? "opencode" : this.validateOpenCodeBinary(logAttempt)
+    let parsed: any = null
+    if (existsSync(configYamlPath)) {
+      const content = readFileSync(configYamlPath, "utf-8")
+      parsed = parseYaml(content)
+    } else if (existsSync(legacyJsonPath)) {
+      const content = readFileSync(legacyJsonPath, "utf-8")
+      parsed = JSON.parse(content)
     } else {
-      targetBinary = this.validateCustomBinary(binaryPath, logAttempt)
+      return "local"
     }
 
-    const spawnCommand = useUserShell
-      ? this.buildShellServeCommand(targetBinary)
-      : { command: targetBinary, args: this.buildServeArgs() }
+    const mode = parsed?.server?.listeningMode ?? 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"
+}
 
-    const launchDetail = `${spawnCommand.command} ${spawnCommand.args.join(" ")}`.trim()
-    this.sendLog(instanceId, "debug", `Launching process with: ${launchDetail}`)
+export declare interface CliProcessManager {
+  on(event: "status", listener: (status: CliStatus) => void): this
+  on(event: "ready", listener: (status: CliStatus) => void): this
+  on(event: "bootstrapToken", listener: (token: string) => 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
+}
 
-    this.sendLog(
-      instanceId,
-      "info",
-      `Starting OpenCode server for ${folder} using ${targetBinary}...`,
+export class CliProcessManager extends EventEmitter {
+  private child?: ChildProcess
+  private status: CliStatus = { state: "stopped" }
+  private stdoutBuffer = ""
+  private stderrBuffer = ""
+  private bootstrapToken: string | null = null
+  private requestedStop = false
+
+  async start(options: StartOptions): Promise<CliStatus> {
+    if (this.child) {
+      await this.stop()
+    }
+
+    this.stdoutBuffer = ""
+    this.stderrBuffer = ""
+    this.bootstrapToken = null
+    this.requestedStop = false
+    this.updateStatus({ state: "starting", port: undefined, pid: undefined, url: undefined, error: undefined })
+
+    const cliEntry = this.resolveCliEntry(options)
+    const listeningMode = this.resolveListeningMode()
+    const host = resolveHostForMode(listeningMode)
+    const args = this.buildCliArgs(options, host)
+
+    console.info(
+      `[cli] launching CodeNomad CLI (${options.dev ? "dev" : "prod"}) using ${cliEntry.runner} at ${cliEntry.entry} (host=${host})`,
     )
 
-    return new Promise((resolve, reject) => {
-      const child = spawn(spawnCommand.command, spawnCommand.args, {
-        cwd: folder,
-        stdio: ["ignore", "pipe", "pipe"],
-        env,
-        shell: false,
-      })
+    const env = supportsUserShell() ? getUserShellEnv() : { ...process.env }
+    env.ELECTRON_RUN_AS_NODE = "1"
 
+    const spawnDetails = supportsUserShell()
+      ? buildUserShellCommand(`ELECTRON_RUN_AS_NODE=1 exec ${this.buildCommand(cliEntry, args)}`)
+      : this.buildDirectSpawn(cliEntry, args)
 
+    const detached = process.platform !== "win32"
+    const child = spawn(spawnDetails.command, spawnDetails.args, {
+      cwd: process.cwd(),
+      stdio: ["ignore", "pipe", "pipe"],
+      env,
+      shell: false,
+      detached,
+    })
+
+    console.info(`[cli] spawn command: ${spawnDetails.command} ${spawnDetails.args.join(" ")}`)
+    if (!child.pid) {
+      console.error("[cli] spawn failed: no pid")
+    }
+
+    this.child = child
+    this.updateStatus({ pid: child.pid ?? undefined })
+
+    child.stdout?.on("data", (data: Buffer) => {
+      this.handleStream(data.toString(), "stdout")
+    })
+
+    child.stderr?.on("data", (data: Buffer) => {
+      this.handleStream(data.toString(), "stderr")
+    })
+
+    child.on("error", (error) => {
+      console.error("[cli] failed to start CLI:", error)
+      this.updateStatus({ state: "error", error: error.message })
+      this.emit("error", error)
+    })
+
+    child.on("exit", (code, signal) => {
+      const failed = this.status.state !== "ready"
+      const error = failed ? this.status.error ?? `CLI exited with code ${code ?? 0}${signal ? ` (${signal})` : ""}` : undefined
+      console.info(`[cli] exit (code=${code}, signal=${signal || ""})${error ? ` error=${error}` : ""}`)
+      this.updateStatus({ state: failed ? "error" : "stopped", error })
+      if (failed && error) {
+        this.emit("error", new Error(error))
+      }
+      this.emit("exit", this.status)
+      this.child = undefined
+    })
+
+    return new Promise<CliStatus>((resolve, reject) => {
       const timeout = setTimeout(() => {
-        child.kill("SIGKILL")
-        this.sendLog(instanceId, "error", "Server startup timeout (10s exceeded)")
-        reject(new Error("Server startup timeout (10s exceeded)"))
-      }, 10000)
+        this.handleTimeout()
+        reject(new Error("CLI startup timeout"))
+      }, 60000)
 
-      let stdoutBuffer = ""
-      let stderrBuffer = ""
-      let portFound = false
-
-      child.stdout?.on("data", (data: Buffer) => {
-        const text = data.toString()
-        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()
-        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) => {
+      this.once("ready", (status) => {
         clearTimeout(timeout)
-        if (error.message.includes("ENOENT")) {
-          reject(new Error("opencode binary not found in PATH"))
-        } else {
-          reject(error)
-        }
+        resolve(status)
       })
 
-      child.on("exit", (code, signal) => {
+      this.once("error", (error) => {
         clearTimeout(timeout)
-        this.processes.delete(child.pid!)
-
-        if (!portFound) {
-          const errorMsg = stderrBuffer || `Process exited with code ${code}`
-          reject(new Error(errorMsg))
-        }
+        reject(error)
       })
     })
   }
 
-  async kill(pid: number): Promise<void> {
-    const meta = this.processes.get(pid)
-    if (!meta) {
-      // Treat unknown processes as already stopped so tabs close cleanly
+  async stop(): Promise<void> {
+    const child = this.child
+    if (!child) {
+      this.updateStatus({ state: "stopped" })
       return
     }
 
-    return new Promise((resolve, reject) => {
-      const child = meta.childProcess
+    this.requestedStop = true
 
+    const pid = child.pid
+    if (!pid) {
+      this.child = undefined
+      this.updateStatus({ state: "stopped" })
+      return
+    }
+
+    const isAlreadyExited = () => child.exitCode !== null || child.signalCode !== null
+
+    const tryKillPosixGroup = (signal: NodeJS.Signals) => {
+      try {
+        // Negative PID targets the process group (POSIX).
+        process.kill(-pid, signal)
+        return true
+      } catch (error) {
+        const err = error as NodeJS.ErrnoException
+        if (err?.code === "ESRCH") {
+          return true
+        }
+        return false
+      }
+    }
+
+    const tryKillSinglePid = (signal: NodeJS.Signals) => {
+      try {
+        process.kill(pid, signal)
+        return true
+      } catch (error) {
+        const err = error as NodeJS.ErrnoException
+        if (err?.code === "ESRCH") {
+          return true
+        }
+        return false
+      }
+    }
+
+    const tryTaskkill = (force: boolean) => {
+      const args = ["/PID", String(pid), "/T"]
+      if (force) {
+        args.push("/F")
+      }
+
+      try {
+        const result = spawnSync("taskkill", args, { encoding: "utf8" })
+        const exitCode = result.status
+        if (exitCode === 0) {
+          return true
+        }
+
+        // If the PID is already gone, treat it as success.
+        const stderr = (result.stderr ?? "").toString().toLowerCase()
+        const stdout = (result.stdout ?? "").toString().toLowerCase()
+        const combined = `${stdout}\n${stderr}`
+        if (combined.includes("not found") || combined.includes("no running instance")) {
+          return true
+        }
+        return false
+      } catch {
+        return false
+      }
+    }
+
+    const sendStopSignal = (signal: NodeJS.Signals) => {
+      if (process.platform === "win32") {
+        tryTaskkill(signal === "SIGKILL")
+        return
+      }
+
+      // Prefer process-group signaling so wrapper launchers (shell/tsx) don't outlive Electron.
+      const groupOk = tryKillPosixGroup(signal)
+      if (!groupOk) {
+        tryKillSinglePid(signal)
+      }
+    }
+
+    return new Promise((resolve) => {
       const killTimeout = setTimeout(() => {
-        child.kill("SIGKILL")
-      }, 2000)
+        console.warn(
+          `[cli] stop timed out after 30000ms; sending SIGKILL (pid=${child.pid ?? "unknown"})`,
+        )
+        sendStopSignal("SIGKILL")
+      }, 30000)
 
       child.on("exit", () => {
         clearTimeout(killTimeout)
-        this.processes.delete(pid)
+        this.child = undefined
+        console.info("[cli] CLI process exited")
+        this.updateStatus({ state: "stopped" })
         resolve()
       })
 
-      child.kill("SIGTERM")
+      if (isAlreadyExited()) {
+        clearTimeout(killTimeout)
+        this.child = undefined
+        this.updateStatus({ state: "stopped" })
+        resolve()
+        return
+      }
+
+      sendStopSignal("SIGTERM")
     })
   }
 
-  getStatus(pid: number): "running" | "stopped" | "unknown" {
-    if (!this.processes.has(pid)) {
-      return "unknown"
-    }
-
-    try {
-      process.kill(pid, 0)
-      return "running"
-    } catch {
-      return "stopped"
-    }
+  getStatus(): CliStatus {
+    return { ...this.status }
   }
 
-  getAllProcesses(): Map<number, ProcessMeta> {
-    return new Map(this.processes)
+  private resolveListeningMode(): ListeningMode {
+    return readListeningModeFromConfig()
   }
 
-  async cleanup(): Promise<void> {
-    const killPromises = Array.from(this.processes.keys()).map((pid) => this.kill(pid).catch(() => {}))
-    await Promise.all(killPromises)
-  }
-
-  private validateFolder(folder: string): void {
-    if (!existsSync(folder)) {
-      throw new Error(`Folder does not exist: ${folder}`)
-    }
-
-    const stats = statSync(folder)
-    if (!stats.isDirectory()) {
-      throw new Error(`Path is not a directory: ${folder}`)
-    }
-  }
-
-  private validateOpenCodeBinary(logAttempt?: (message: string) => void): string {
-    const log = logAttempt ?? ((message: string) => console.info(`[ProcessManager] ${message}`))
-
-    if (process.platform === "win32") {
-      log("Checking PATH via 'where opencode'")
-      return this.resolveBinaryViaLocator("where opencode", log)
-    }
-
-    const shellCheck = buildUserShellCommand("command -v opencode")
-    const shellPreview = [shellCheck.command, ...shellCheck.args].join(" ")
-    log(`Checking PATH via shell: ${shellPreview}`)
-
-    try {
-      const resolved = runUserShellCommandSync("command -v opencode")
-      const path = this.pickFirstPath(resolved)
-      if (path) {
-        log(`Shell located opencode at ${path}`)
-        return path
+  private handleTimeout() {
+    if (this.child) {
+      const pid = this.child.pid
+      if (pid && process.platform !== "win32") {
+        try {
+          process.kill(-pid, "SIGKILL")
+        } catch {
+          this.child.kill("SIGKILL")
+        }
+      } else {
+        this.child.kill("SIGKILL")
       }
-      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",
-        )
+      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) {
+      const trimmed = line.trim()
+      if (!trimmed) continue
+
+      if (trimmed.startsWith(BOOTSTRAP_TOKEN_PREFIX)) {
+        const token = trimmed.slice(BOOTSTRAP_TOKEN_PREFIX.length).trim()
+        if (token && !this.bootstrapToken) {
+          this.bootstrapToken = token
+          this.emit("bootstrapToken", token)
+        }
+        continue
+      }
+
+      console.info(`[cli][${stream}] ${trimmed}`)
+      this.emit("log", { stream, message: trimmed })
+
+      const localUrl = this.extractLocalUrl(trimmed)
+      if (localUrl && this.status.state === "starting") {
+        let port: number | undefined
+        try {
+          port = Number(new URL(localUrl).port) || undefined
+        } catch {
+          port = undefined
+        }
+        console.info(`[cli] ready on ${localUrl}`)
+        this.updateStatus({ state: "ready", port, url: localUrl })
+        this.emit("ready", this.status)
       }
     }
   }
 
-  private validateCustomBinary(binaryPath: string, log?: (message: string) => void): string {
-    log?.(`Validating custom binary at ${binaryPath}`)
+  private extractLocalUrl(line: string): string | null {
+    const match = line.match(/^Local\s+Connection\s+URL\s*:\s*(https?:\/\/\S+)\s*$/i)
+    if (!match) {
+      return null
+    }
+    return match[1] ?? null
+  }
 
-    if (!existsSync(binaryPath)) {
-      throw new Error(`OpenCode binary not found: ${binaryPath}`)
+  private updateStatus(patch: Partial<CliStatus>) {
+    this.status = { ...this.status, ...patch }
+    this.emit("status", this.status)
+  }
+
+  private buildCliArgs(options: StartOptions, host: string): string[] {
+    const args = ["serve", "--host", host, "--generate-token"]
+
+    if (options.dev) {
+      // Dev: run plain HTTP + Vite dev server proxy.
+      args.push("--https", "false", "--http", "true")
+      // Avoid collisions with an already-running server (and dual-stack ::/0.0.0.0 quirks)
+      // by forcing an ephemeral port in dev.
+      args.push("--http-port", "0")
+    } else {
+      // Prod desktop: always keep loopback HTTP enabled.
+      args.push("--https", "true", "--http", "true")
     }
 
-    const stats = statSync(binaryPath)
-    if (!stats.isFile()) {
-      throw new Error(`Path is not a file: ${binaryPath}`)
+    if (options.dev) {
+      const devServer = process.env.VITE_DEV_SERVER_URL || process.env.ELECTRON_RENDERER_URL || "http://localhost:3000"
+      args.push("--ui-dev-server", devServer, "--log-level", "debug")
     }
 
-    // Check if executable (on Unix systems)
-    if (process.platform !== "win32") {
+    return args
+  }
+
+  private buildCommand(cliEntry: CliEntryResolution, args: string[]): string {
+    const parts = [JSON.stringify(process.execPath)]
+    if (cliEntry.runner === "tsx" && cliEntry.runnerPath) {
+      parts.push(JSON.stringify(cliEntry.runnerPath))
+    }
+    parts.push(JSON.stringify(cliEntry.entry))
+    args.forEach((arg) => parts.push(JSON.stringify(arg)))
+    return parts.join(" ")
+  }
+
+  private buildDirectSpawn(cliEntry: CliEntryResolution, args: string[]) {
+    if (cliEntry.runner === "tsx") {
+      return { command: process.execPath, args: [cliEntry.runnerPath!, cliEntry.entry, ...args] }
+    }
+
+    return { command: process.execPath, args: [cliEntry.entry, ...args] }
+  }
+
+  private resolveCliEntry(options: StartOptions): CliEntryResolution {
+    if (options.dev) {
+      const tsxPath = this.resolveTsx()
+      if (!tsxPath) {
+        throw new Error("tsx is required to run the CLI in development mode. Please install dependencies.")
+      }
+      const devEntry = this.resolveDevEntry()
+      return { entry: devEntry, runner: "tsx", runnerPath: tsxPath }
+    }
+ 
+    const distEntry = this.resolveProdEntry()
+    return { entry: distEntry, runner: "node" }
+  }
+ 
+  private resolveTsx(): string | null {
+    const candidates: Array<string | (() => string)> = [
+      () => nodeRequire.resolve("tsx/cli"),
+      () => nodeRequire.resolve("tsx/dist/cli.mjs"),
+      () => nodeRequire.resolve("tsx/dist/cli.cjs"),
+      path.resolve(process.cwd(), "node_modules", "tsx", "dist", "cli.mjs"),
+      path.resolve(process.cwd(), "node_modules", "tsx", "dist", "cli.cjs"),
+      path.resolve(process.cwd(), "..", "node_modules", "tsx", "dist", "cli.mjs"),
+      path.resolve(process.cwd(), "..", "node_modules", "tsx", "dist", "cli.cjs"),
+      path.resolve(process.cwd(), "..", "..", "node_modules", "tsx", "dist", "cli.mjs"),
+      path.resolve(process.cwd(), "..", "..", "node_modules", "tsx", "dist", "cli.cjs"),
+      path.resolve(app.getAppPath(), "..", "node_modules", "tsx", "dist", "cli.mjs"),
+      path.resolve(app.getAppPath(), "..", "node_modules", "tsx", "dist", "cli.cjs"),
+    ]
+ 
+    for (const candidate of candidates) {
       try {
-        execSync(`test -x "${binaryPath}"`, { stdio: "pipe" })
+        const resolved = typeof candidate === "function" ? candidate() : candidate
+        if (resolved && existsSync(resolved)) {
+          return resolved
+        }
       } catch {
-        throw new Error(`Binary is not executable: ${binaryPath}`)
+        continue
       }
     }
-
-    return binaryPath
+ 
+    return null
   }
-
-  private resolveBinaryViaLocator(command: string, log?: (message: string) => void): string {
-    log?.(`Running locator command: ${command}`)
-    const output = execSync(command, { stdio: "pipe", encoding: "utf-8" })
-    log?.(`Locator output: ${output.trim() || "<empty>"}`)
-    const path = this.pickFirstPath(output)
-    if (!path) {
-      throw new Error("opencode binary not found in PATH")
+ 
+  private resolveDevEntry(): string {
+    const entry = path.resolve(process.cwd(), "..", "server", "src", "index.ts")
+    if (!existsSync(entry)) {
+      throw new Error(`Dev CLI entry not found at ${entry}. Run npm run dev:electron from the repository root after installing dependencies.`)
     }
-    return path
+    return entry
   }
-
-  private pickFirstPath(output: string): string | null {
-    const line = output
-      .split("\n")
-      .map((entry) => entry.trim())
-      .find((entry) => entry.length > 0)
-    return line ?? null
-  }
-
-  private buildServeArgs(): string[] {
-    return ["serve", "--port", "0", "--print-logs", "--log-level", "DEBUG"]
-  }
-
-  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}`)
+ 
+  private resolveProdEntry(): string {
+    try {
+      const entry = nodeRequire.resolve("@neuralnomads/codenomad/dist/bin.js")
+      if (existsSync(entry)) {
+        return entry
+      }
+    } catch {
+      // fall through to error below
+    }
+    throw new Error("Unable to locate CodeNomad CLI build (dist/bin.js). Run npm run build --workspace @neuralnomads/codenomad.")
   }
 }
-
-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,19 @@
+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),
+  setWakeLock: (enabled) => ipcRenderer.invoke("power:setWakeLock", Boolean(enabled)),
+  showNotification: (payload) => ipcRenderer.invoke("notifications:show", payload),
+}
+
+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,22 @@
 {
-  "name": "@codenomad/electron-app",
-  "version": "0.1.2",
+  "name": "@neuralnomads/codenomad-electron-app",
+  "version": "0.11.1",
   "description": "CodeNomad - AI coding assistant",
+  "license": "MIT",
   "author": {
-    "name": "Shantur Rathore",
-    "email": "codenomad@shantur.com"
+    "name": "Neural Nomads",
+    "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 +35,9 @@
     "package:linux": "electron-builder --linux"
   },
   "dependencies": {
+    "@neuralnomads/codenomad": "file:../server",
     "@codenomad/ui": "file:../ui",
-    "ignore": "7.0.5"
+    "yaml": "^2.4.2"
   },
   "devDependencies": {
     "7zip-bin": "^5.2.0",
@@ -40,6 +47,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 +63,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 +127,14 @@
     "linux": {
       "target": [
         {
-          "target": "AppImage",
-          "arch": ["x64", "arm64"]
-        },
-        {
-          "target": "deb",
-          "arch": ["x64", "arm64"]
-        },
-        {
-          "target": "rpm",
-          "arch": ["x64", "arm64"]
-        },
-        {
-          "target": "tar.gz",
-          "arch": ["x64", "arm64"]
+          "target": "zip",
+          "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"],
-    description: "macOS (Intel, Apple Silicon, Universal)",
+    args: ["--mac", "--x64", "--arm64"],
+    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,9 @@
+{
+  "name": "@codenomad/opencode-config",
+  "version": "0.5.0",
+  "private": true,
+  "license": "MIT",
+  "dependencies": {
+    "@opencode-ai/plugin": "1.2.4"
+  }
+}

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,253 @@
+import path from "path"
+import { tool } from "@opencode-ai/plugin/tool"
+import { createCodeNomadRequester, type CodeNomadConfig } from "./request"
+
+type BackgroundProcess = {
+  id: string
+  title: string
+  command: string
+  status: "running" | "stopped" | "error"
+  startedAt: string
+  stoppedAt?: string
+  exitCode?: number
+  outputSizeBytes?: number
+}
+
+type BackgroundProcessOptions = {
+  baseDir: string
+}
+
+type ParsedCommand = {
+  head: string
+  args: string[]
+}
+
+export function createBackgroundProcessTools(config: CodeNomadConfig, options: BackgroundProcessOptions) {
+  const requester = createCodeNomadRequester(config)
+
+  const request = async <T>(path: string, init?: RequestInit): Promise<T> => {
+    return requester.requestJson<T>(`/background-processes${path}`, init)
+  }
+
+  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()
+      tokens.push(char)
+      continue
+    }
+
+    current += char
+  }
+
+  flush()
+  return tokens
+}
+
+function isSeparator(token: string): boolean {
+  return token === "|" || token === "&" || token === ";"
+}
+
+function unquote(token: string): string {
+  if ((token.startsWith('"') && token.endsWith('"')) || (token.startsWith("'") && token.endsWith("'"))) {
+    return token.slice(1, -1)
+  }
+  return token
+}
+
+function isWithinBase(base: string, candidate: string): boolean {
+  const relative = path.relative(base, candidate)
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))
+}

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

@@ -0,0 +1,133 @@
+import { createCodeNomadRequester, type CodeNomadConfig, type PluginEvent } from "./request"
+
+export { getCodeNomadConfig, type CodeNomadConfig, type PluginEvent } from "./request"
+
+export function createCodeNomadClient(config: CodeNomadConfig) {
+  const requester = createCodeNomadRequester(config)
+
+  return {
+    postEvent: (event: PluginEvent) =>
+      requester.requestVoid("/event", {
+        method: "POST",
+        body: JSON.stringify(event),
+      }),
+    startEvents: (onEvent: (event: PluginEvent) => void) => startPluginEvents(requester, onEvent),
+  }
+}
+
+function delay(ms: number) {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms))
+}
+
+async function startPluginEvents(
+  requester: ReturnType<typeof createCodeNomadRequester>,
+  onEvent: (event: PluginEvent) => void,
+) {
+  // Fail plugin startup if we cannot establish the initial connection.
+  const initialBody = await connectWithRetries(requester, 3)
+
+  // After startup, keep reconnecting; throw after 3 consecutive failures.
+  void consumeWithReconnect(requester, onEvent, initialBody)
+}
+
+async function connectWithRetries(requester: ReturnType<typeof createCodeNomadRequester>, maxAttempts: number) {
+  let lastError: unknown
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      return await requester.requestSseBody("/events")
+    } catch (error) {
+      lastError = error
+      await delay(500 * attempt)
+    }
+  }
+
+  const reason = lastError instanceof Error ? lastError.message : String(lastError)
+  const url = requester.buildUrl("/events")
+  throw new Error(`[CodeNomadPlugin] Failed to connect to CodeNomad at ${url} after ${maxAttempts} retries: ${reason}`)
+}
+
+async function consumeWithReconnect(
+  requester: ReturnType<typeof createCodeNomadRequester>,
+  onEvent: (event: PluginEvent) => void,
+  initialBody: ReadableStream<Uint8Array>,
+) {
+  let consecutiveFailures = 0
+  let body: ReadableStream<Uint8Array> | null = initialBody
+
+  while (true) {
+    try {
+      if (!body) {
+        body = await connectWithRetries(requester, 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/opencode-config/plugin/lib/request.ts

@@ -0,0 +1,214 @@
+import http from "http"
+import https from "https"
+import { Readable } from "stream"
+
+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 createCodeNomadRequester(config: CodeNomadConfig) {
+  const rawBaseUrl = (config.baseUrl ?? "").trim()
+  const baseUrl = rawBaseUrl.replace(/\/+$/, "")
+  const pluginBase = `${baseUrl}/workspaces/${encodeURIComponent(config.instanceId)}/plugin`
+  const authorization = buildInstanceAuthorizationHeader()
+
+  const buildUrl = (path: string) => {
+    if (path.startsWith("http://") || path.startsWith("https://")) {
+      return path
+    }
+    const normalized = path.startsWith("/") ? path : `/${path}`
+    return `${pluginBase}${normalized}`
+  }
+
+  const buildHeaders = (headers: HeadersInit | undefined, hasBody: boolean): Record<string, string> => {
+    const output: Record<string, string> = normalizeHeaders(headers)
+    output.Authorization = authorization
+    if (hasBody) {
+      output["Content-Type"] = output["Content-Type"] ?? "application/json"
+    }
+    return output
+  }
+
+  const fetchWithAuth = async (path: string, init?: RequestInit): Promise<Response> => {
+    const url = buildUrl(path)
+    const hasBody = init?.body !== undefined
+    const headers = buildHeaders(init?.headers, hasBody)
+
+    // The CodeNomad plugin only talks to the local CodeNomad server.
+    // Use a single request implementation that tolerates custom/self-signed certs
+    // without disabling TLS verification for the whole Node process.
+    return nodeFetch(url, { ...init, headers }, { rejectUnauthorized: false })
+  }
+
+  const requestJson = async <T>(path: string, init?: RequestInit): Promise<T> => {
+    const response = await fetchWithAuth(path, init)
+    if (!response.ok) {
+      const message = await response.text().catch(() => "")
+      throw new Error(message || `Request failed with ${response.status}`)
+    }
+
+    if (response.status === 204) {
+      return undefined as T
+    }
+
+    return (await response.json()) as T
+  }
+
+  const requestVoid = async (path: string, init?: RequestInit): Promise<void> => {
+    const response = await fetchWithAuth(path, init)
+    if (!response.ok) {
+      const message = await response.text().catch(() => "")
+      throw new Error(message || `Request failed with ${response.status}`)
+    }
+  }
+
+  const requestSseBody = async (path: string): Promise<ReadableStream<Uint8Array>> => {
+    const response = await fetchWithAuth(path, { headers: { Accept: "text/event-stream" } })
+    if (!response.ok || !response.body) {
+      throw new Error(`SSE unavailable (${response.status})`)
+    }
+    return response.body as ReadableStream<Uint8Array>
+  }
+
+  return {
+    buildUrl,
+    fetch: fetchWithAuth,
+    requestJson,
+    requestVoid,
+    requestSseBody,
+  }
+}
+
+async function nodeFetch(
+  url: string,
+  init: RequestInit & { headers?: Record<string, string> },
+  tls: { rejectUnauthorized: boolean },
+): Promise<Response> {
+  const parsed = new URL(url)
+  const isHttps = parsed.protocol === "https:"
+  const requestFn = isHttps ? https.request : http.request
+
+  const method = (init.method ?? "GET").toUpperCase()
+  const headers = init.headers ?? {}
+  const body = init.body
+
+  return await new Promise<Response>((resolve, reject) => {
+    const req = requestFn(
+      {
+        protocol: parsed.protocol,
+        hostname: parsed.hostname,
+        port: parsed.port ? Number(parsed.port) : undefined,
+        path: `${parsed.pathname}${parsed.search}`,
+        method,
+        headers,
+        ...(isHttps ? { rejectUnauthorized: tls.rejectUnauthorized } : {}),
+      },
+      (res) => {
+        const responseHeaders = new Headers()
+        for (const [key, value] of Object.entries(res.headers)) {
+          if (value === undefined) continue
+          if (Array.isArray(value)) {
+            responseHeaders.set(key, value.join(", "))
+          } else {
+            responseHeaders.set(key, String(value))
+          }
+        }
+
+        // Convert Node stream -> Web ReadableStream for Response.
+        const webBody = Readable.toWeb(res) as unknown as ReadableStream<Uint8Array>
+        resolve(new Response(webBody, { status: res.statusCode ?? 0, headers: responseHeaders }))
+      },
+    )
+
+    const signal = init.signal
+    const abort = () => {
+      const err = new Error("Request aborted")
+      ;(err as any).name = "AbortError"
+      req.destroy(err)
+      reject(err)
+    }
+
+    if (signal) {
+      if (signal.aborted) {
+        abort()
+        return
+      }
+      signal.addEventListener("abort", abort, { once: true })
+      req.once("close", () => signal.removeEventListener("abort", abort))
+    }
+
+    req.once("error", reject)
+
+    if (body === undefined || body === null) {
+      req.end()
+      return
+    }
+
+    if (typeof body === "string") {
+      req.end(body)
+      return
+    }
+
+    if (body instanceof Uint8Array) {
+      req.end(Buffer.from(body))
+      return
+    }
+
+    if (body instanceof ArrayBuffer) {
+      req.end(Buffer.from(new Uint8Array(body)))
+      return
+    }
+
+    // Fallback for less common BodyInit types.
+    req.end(String(body))
+  })
+}
+
+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 buildInstanceAuthorizationHeader(): string {
+  const username = requireEnv("OPENCODE_SERVER_USERNAME")
+  const password = requireEnv("OPENCODE_SERVER_PASSWORD")
+  const token = Buffer.from(`${username}:${password}`, "utf8").toString("base64")
+  return `Basic ${token}`
+}
+
+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/server/.gitignore

@@ -0,0 +1,4 @@
+public/
+
+# Local developer config (may contain secrets)
+config-*.json

packages/server/README.md

@@ -0,0 +1,162 @@
+# 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
+```
+
+To list all CLI options:
+
+```sh
+npx @neuralnomads/codenomad --help
+```
+
+On startup, CodeNomad prints two URLs:
+
+- `Local Connection URL : ...` (used by desktop shells)
+- `Remote Connection URL : ...` (used by browsers/other machines when remote access is enabled)
+
+### Install Globally
+Or install it globally to use the `codenomad` command:
+
+```sh
+npm install -g @neuralnomads/codenomad
+codenomad --launch
+```
+
+### Install Locally (per-project)
+If you prefer to install CodeNomad into a project and run the local binary:
+
+```sh
+npm install @neuralnomads/codenomad
+npx codenomad --launch
+```
+
+(`npx codenomad ...` will use `./node_modules/.bin/codenomad` when present.)
+
+### Common Flags
+You can configure the server using flags or environment variables:
+
+| Flag | Env Variable | Description |
+|------|--------------|-------------|
+| `--https <enabled>` | `CLI_HTTPS` | Enable HTTPS listener (default `true`) |
+| `--http <enabled>` | `CLI_HTTP` | Enable HTTP listener (default `false`) |
+| `--https-port <number>` | `CLI_HTTPS_PORT` | HTTPS port (default `9898`, use `0` for auto) |
+| `--http-port <number>` | `CLI_HTTP_PORT` | HTTP port (default `9899`, use `0` for auto) |
+| `--tls-key <path>` | `CLI_TLS_KEY` | TLS private key (PEM). Requires `--tls-cert`. |
+| `--tls-cert <path>` | `CLI_TLS_CERT` | TLS certificate (PEM). Requires `--tls-key`. |
+| `--tls-ca <path>` | `CLI_TLS_CA` | Optional CA chain/bundle (PEM) |
+| `--tlsSANs <list>` | `CLI_TLS_SANS` | Additional TLS SANs (comma-separated) |
+| `--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) |
+| `--log-destination <path>` | `CLI_LOG_DESTINATION` | Log destination file (defaults to stdout) |
+| `--username <username>` | `CODENOMAD_SERVER_USERNAME` | Username for CodeNomad's internal auth (default `codenomad`) |
+| `--password <password>` | `CODENOMAD_SERVER_PASSWORD` | Password for CodeNomad's internal auth |
+| `--generate-token` | `CODENOMAD_GENERATE_TOKEN` | Emit a one-time local bootstrap token for desktop flows |
+| `--dangerously-skip-auth` | `CODENOMAD_SKIP_AUTH` | Disable CodeNomad's internal auth (use only behind a trusted perimeter) |
+| `--ui-dir <path>` | `CLI_UI_DIR` | Directory containing the built UI bundle |
+| `--ui-dev-server <url>` | `CLI_UI_DEV_SERVER` | Proxy UI requests to a running dev server (requires `--https=false --http=true`) |
+| `--ui-no-update` | `CLI_UI_NO_UPDATE` | Disable remote UI updates |
+| `--ui-auto-update <enabled>` | `CLI_UI_AUTO_UPDATE` | Enable remote UI updates (true|false) |
+| `--ui-manifest-url <url>` | `CLI_UI_MANIFEST_URL` | Remote UI manifest URL |
+
+### Dev Releases (Advanced)
+If you want the latest bleeding-edge builds (published as GitHub pre-releases), use the dev package:
+
+```sh
+npx @neuralnomads/codenomad-dev --launch
+```
+
+These environment variables control how CodeNomad checks for dev updates:
+
+| Env Variable | Description |
+|-------------|-------------|
+| `CODENOMAD_UPDATE_CHANNEL` | Update channel (use `dev` to enable dev build update checks) |
+| `CODENOMAD_GITHUB_REPO` | GitHub repo used for dev release checks (default `NeuralNomadsAI/CodeNomad`) |
+
+### HTTP vs HTTPS
+
+- Default: `--https=true --http=false` (HTTPS only).
+- To run plain HTTP only (useful for development):
+
+```sh
+codenomad --https=false --http=true
+```
+
+- To run both HTTPS (for remote) and HTTP loopback (for desktop):
+
+```sh
+codenomad --https=true --http=true
+```
+
+### Remote Access Binding Rules
+
+- When remote access is enabled (bind host is non-loopback, e.g. `--host 0.0.0.0`):
+  - HTTP listens on `127.0.0.1` only.
+  - HTTPS listens on `--host` (LAN/all interfaces).
+- When remote access is disabled (bind host is loopback, e.g. `--host 127.0.0.1`):
+  - Both HTTP and HTTPS listen on `127.0.0.1`.
+
+### Self-Signed Certificates
+
+If `--https=true` and you do not provide `--tls-key/--tls-cert`, CodeNomad generates a local certificate automatically under your config directory:
+
+- `~/.config/codenomad/tls/ca-cert.pem`
+- `~/.config/codenomad/tls/server-cert.pem`
+
+Certificates are valid for about 30 days and rotate automatically on startup when needed. You can add extra SANs via:
+
+```sh
+codenomad --tlsSANs "localhost,127.0.0.1,my-hostname,192.168.1.10"
+```
+
+### Authentication
+- Default behavior: CodeNomad requires a login (username/password) and stores a session cookie in the browser.
+- `--dangerously-skip-auth` / `CODENOMAD_SKIP_AUTH=true` disables the login prompt and treats all requests as authenticated.
+  Use this only when access is already protected by another layer (SSO proxy, VPN, Coder workspace auth, etc.).
+  If you bind to `0.0.0.0` while skipping auth, anyone who can reach the port can access the API.
+
+### Progressive Web App (PWA)
+When running as a server CodeNomad can also be installed as a PWA from any supported browser, giving you a native app experience just like the Electron installation but executing on the remote server instead.
+
+1. Open the CodeNomad UI in a Chromium-based browser (Chrome, Edge, Brave, etc.).
+2. Click the install icon in the address bar, or use the browser menu → "Install CodeNomad".
+3. The app will open in a standalone window and appear in your OS app list.
+
+> **TLS requirement**
+> Browsers require a secure (`https://`) connection for PWA installation.
+> If you host CodeNomad on a remote machine, use HTTPS. Self-signed certificates generally won't work unless they are explicitly trusted by the device/browser (e.g., via a custom CA).
+
+### Data Storage
+- **Config**: `~/.config/codenomad/config.json`
+- **Instance Data**: `~/.config/codenomad/instances` (chat history, etc.)

packages/server/package-lock.json

@@ -1,20 +1,30 @@
 {
-  "name": "@codenomad/cli",
-  "version": "0.1.0",
+  "name": "@neuralnomads/codenomad",
+  "version": "0.11.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "@codenomad/cli",
-      "version": "0.1.0",
+      "name": "@neuralnomads/codenomad",
+      "version": "0.11.1",
       "dependencies": {
         "@fastify/cors": "^8.5.0",
+        "@fastify/reply-from": "^9.8.0",
+        "@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",
+        "yauzl": "^2.10.0",
         "zod": "^3.23.8"
       },
+      "bin": {
+        "codenomad": "dist/bin.js"
+      },
       "devDependencies": {
+        "@types/yauzl": "^2.10.0",
+        "cross-env": "^7.0.3",
         "ts-node": "^10.9.2",
         "tsx": "^4.20.6",
         "typescript": "^5.6.3"
@@ -475,6 +485,15 @@
         "node": ">=18"
       }
     },
+    "node_modules/@fastify/accept-negotiator": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@fastify/accept-negotiator/-/accept-negotiator-1.1.0.tgz",
+      "integrity": "sha512-OIHZrb2ImZ7XG85HXOONLcJWGosv7sIvM2ifAPQVhg9Lv7qdmMBNVaai4QTdyuaqbKM5eO6sLSQOYI7wEQeCJQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      }
+    },
     "node_modules/@fastify/ajv-compiler": {
       "version": "3.6.0",
       "resolved": "https://registry.npmjs.org/@fastify/ajv-compiler/-/ajv-compiler-3.6.0.tgz",
@@ -486,6 +505,15 @@
         "fast-uri": "^2.0.0"
       }
     },
+    "node_modules/@fastify/busboy": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/@fastify/busboy/-/busboy-2.1.1.tgz",
+      "integrity": "sha512-vBZP4NlzfOlerQTnba4aqZoMhE/a9HY7HRqoOPaETQcSQuWEIyZMHGfVu6w9wGtGK5fED5qRs2DteVCjOH60sA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      }
+    },
     "node_modules/@fastify/cors": {
       "version": "8.5.0",
       "resolved": "https://registry.npmjs.org/@fastify/cors/-/cors-8.5.0.tgz",
@@ -520,6 +548,77 @@
         "fast-deep-equal": "^3.1.3"
       }
     },
+    "node_modules/@fastify/reply-from": {
+      "version": "9.8.0",
+      "resolved": "https://registry.npmjs.org/@fastify/reply-from/-/reply-from-9.8.0.tgz",
+      "integrity": "sha512-bPNVaFhEeNI0Lyl6404YZaPFokudCplidE3QoOcr78yOy6H9sYw97p5KPYvY/NJNUHfFtvxOaSAHnK+YSiv/Mg==",
+      "license": "MIT",
+      "dependencies": {
+        "@fastify/error": "^3.0.0",
+        "end-of-stream": "^1.4.4",
+        "fast-content-type-parse": "^1.1.0",
+        "fast-querystring": "^1.0.0",
+        "fastify-plugin": "^4.0.0",
+        "toad-cache": "^3.7.0",
+        "undici": "^5.19.1"
+      }
+    },
+    "node_modules/@fastify/reply-from/node_modules/undici": {
+      "version": "5.29.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-5.29.0.tgz",
+      "integrity": "sha512-raqeBD6NQK4SkWhQzeYKd1KmIG6dllBOTt55Rmkt4HtI9mwdWtJljnrXjAFUBLTSN67HWrOIZ3EPF4kjUw80Bg==",
+      "license": "MIT",
+      "dependencies": {
+        "@fastify/busboy": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=14.0"
+      }
+    },
+    "node_modules/@fastify/send": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@fastify/send/-/send-2.1.0.tgz",
+      "integrity": "sha512-yNYiY6sDkexoJR0D8IDy3aRP3+L4wdqCpvx5WP+VtEU58sn7USmKynBzDQex5X42Zzvw2gNzzYgP90UfWShLFA==",
+      "license": "MIT",
+      "dependencies": {
+        "@lukeed/ms": "^2.0.1",
+        "escape-html": "~1.0.3",
+        "fast-decode-uri-component": "^1.0.1",
+        "http-errors": "2.0.0",
+        "mime": "^3.0.0"
+      }
+    },
+    "node_modules/@fastify/static": {
+      "version": "7.0.4",
+      "resolved": "https://registry.npmjs.org/@fastify/static/-/static-7.0.4.tgz",
+      "integrity": "sha512-p2uKtaf8BMOZWLs6wu+Ihg7bWNBdjNgCwDza4MJtTqg+5ovKmcbgbR9Xs5/smZ1YISfzKOCNYmZV8LaCj+eJ1Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@fastify/accept-negotiator": "^1.0.0",
+        "@fastify/send": "^2.0.0",
+        "content-disposition": "^0.5.3",
+        "fastify-plugin": "^4.0.0",
+        "fastq": "^1.17.0",
+        "glob": "^10.3.4"
+      }
+    },
+    "node_modules/@isaacs/cliui": {
+      "version": "8.0.2",
+      "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-8.0.2.tgz",
+      "integrity": "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==",
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^5.1.2",
+        "string-width-cjs": "npm:string-width@^4.2.0",
+        "strip-ansi": "^7.0.1",
+        "strip-ansi-cjs": "npm:strip-ansi@^6.0.1",
+        "wrap-ansi": "^8.1.0",
+        "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/@jridgewell/resolve-uri": {
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
@@ -548,12 +647,31 @@
         "@jridgewell/sourcemap-codec": "^1.4.10"
       }
     },
+    "node_modules/@lukeed/ms": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/@lukeed/ms/-/ms-2.0.2.tgz",
+      "integrity": "sha512-9I2Zn6+NJLfaGoz9jN3lpwDgAYvfGeNYdbAIjJOqzs4Tpc+VU3Jqq4IofSUBKajiDS8k9fZIg18/z13mpk1bsA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/@pinojs/redact": {
       "version": "0.4.0",
       "resolved": "https://registry.npmjs.org/@pinojs/redact/-/redact-0.4.0.tgz",
       "integrity": "sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg==",
       "license": "MIT"
     },
+    "node_modules/@pkgjs/parseargs": {
+      "version": "0.11.0",
+      "resolved": "https://registry.npmjs.org/@pkgjs/parseargs/-/parseargs-0.11.0.tgz",
+      "integrity": "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=14"
+      }
+    },
     "node_modules/@tsconfig/node10": {
       "version": "1.0.12",
       "resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.12.tgz",
@@ -593,6 +711,16 @@
         "undici-types": "~7.16.0"
       }
     },
+    "node_modules/@types/yauzl": {
+      "version": "2.10.3",
+      "resolved": "https://registry.npmjs.org/@types/yauzl/-/yauzl-2.10.3.tgz",
+      "integrity": "sha512-oJoftv0LSuaDZE3Le4DbKX+KS9G36NzOeSap90UIK0yMA/NhKJhqlSGtNDORNRaIbQfzjXDrQa0ytJ6mNRGz/Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/abstract-logging": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/abstract-logging/-/abstract-logging-2.0.1.tgz",
@@ -674,6 +802,30 @@
       ],
       "license": "BSD-3-Clause"
     },
+    "node_modules/ansi-regex": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz",
+      "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-regex?sponsor=1"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
+      "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
     "node_modules/arg": {
       "version": "4.1.3",
       "resolved": "https://registry.npmjs.org/arg/-/arg-4.1.3.tgz",
@@ -700,6 +852,48 @@
         "fastq": "^1.17.1"
       }
     },
+    "node_modules/balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
+      "license": "MIT"
+    },
+    "node_modules/brace-expansion": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
+      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^1.0.0"
+      }
+    },
+    "node_modules/buffer-crc32": {
+      "version": "0.2.13",
+      "resolved": "https://registry.npmjs.org/buffer-crc32/-/buffer-crc32-0.2.13.tgz",
+      "integrity": "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ==",
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/color-convert": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
+      "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
+      "license": "MIT",
+      "dependencies": {
+        "color-name": "~1.1.4"
+      },
+      "engines": {
+        "node": ">=7.0.0"
+      }
+    },
+    "node_modules/color-name": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
+      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
+      "license": "MIT"
+    },
     "node_modules/commander": {
       "version": "12.1.0",
       "resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz",
@@ -709,6 +903,18 @@
         "node": ">=18"
       }
     },
+    "node_modules/content-disposition": {
+      "version": "0.5.4",
+      "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-0.5.4.tgz",
+      "integrity": "sha512-FveZTNuGw04cxlAiWbzi6zTAL/lhehaWbTtgluJh4/E95DqMwTmha3KZN1aAWA8cFIhHzMZUvLevkw5Rqk+tSQ==",
+      "license": "MIT",
+      "dependencies": {
+        "safe-buffer": "5.2.1"
+      },
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
     "node_modules/cookie": {
       "version": "0.7.2",
       "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz",
@@ -725,6 +931,48 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/cross-env": {
+      "version": "7.0.3",
+      "resolved": "https://registry.npmjs.org/cross-env/-/cross-env-7.0.3.tgz",
+      "integrity": "sha512-+/HKd6EgcQCJGh2PSjZuUitQBQynKor4wrFbRg4DtAgS1aWO+gU52xpH7M9ScGgXSYmAVS9bIJ8EzuaGw0oNAw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cross-spawn": "^7.0.1"
+      },
+      "bin": {
+        "cross-env": "src/bin/cross-env.js",
+        "cross-env-shell": "src/bin/cross-env-shell.js"
+      },
+      "engines": {
+        "node": ">=10.14",
+        "npm": ">=6",
+        "yarn": ">=1"
+      }
+    },
+    "node_modules/cross-spawn": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+      "license": "MIT",
+      "dependencies": {
+        "path-key": "^3.1.0",
+        "shebang-command": "^2.0.0",
+        "which": "^2.0.1"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/depd": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz",
+      "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
     "node_modules/diff": {
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/diff/-/diff-4.0.2.tgz",
@@ -735,6 +983,27 @@
         "node": ">=0.3.1"
       }
     },
+    "node_modules/eastasianwidth": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/eastasianwidth/-/eastasianwidth-0.2.0.tgz",
+      "integrity": "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==",
+      "license": "MIT"
+    },
+    "node_modules/emoji-regex": {
+      "version": "9.2.2",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz",
+      "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==",
+      "license": "MIT"
+    },
+    "node_modules/end-of-stream": {
+      "version": "1.4.5",
+      "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
+      "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
+      "license": "MIT",
+      "dependencies": {
+        "once": "^1.4.0"
+      }
+    },
     "node_modules/esbuild": {
       "version": "0.25.12",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz",
@@ -777,6 +1046,12 @@
         "@esbuild/win32-x64": "0.25.12"
       }
     },
+    "node_modules/escape-html": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz",
+      "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==",
+      "license": "MIT"
+    },
     "node_modules/fast-content-type-parse": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/fast-content-type-parse/-/fast-content-type-parse-1.1.0.tgz",
@@ -891,6 +1166,15 @@
         "reusify": "^1.0.4"
       }
     },
+    "node_modules/fd-slicer": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/fd-slicer/-/fd-slicer-1.1.0.tgz",
+      "integrity": "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g==",
+      "license": "MIT",
+      "dependencies": {
+        "pend": "~1.2.0"
+      }
+    },
     "node_modules/find-my-way": {
       "version": "8.2.2",
       "resolved": "https://registry.npmjs.org/find-my-way/-/find-my-way-8.2.2.tgz",
@@ -905,6 +1189,22 @@
         "node": ">=14"
       }
     },
+    "node_modules/foreground-child": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.3.1.tgz",
+      "integrity": "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==",
+      "license": "ISC",
+      "dependencies": {
+        "cross-spawn": "^7.0.6",
+        "signal-exit": "^4.0.1"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/forwarded": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
@@ -929,6 +1229,12 @@
         "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
       }
     },
+    "node_modules/fuzzysort": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/fuzzysort/-/fuzzysort-2.0.4.tgz",
+      "integrity": "sha512-Api1mJL+Ad7W7vnDZnWq5pGaXJjyencT+iKGia2PlHUcSsSzWwIQ3S1isiMpwpavjYtGd2FzhUIhnnhOULZgDw==",
+      "license": "MIT"
+    },
     "node_modules/get-tsconfig": {
       "version": "4.13.0",
       "resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-4.13.0.tgz",
@@ -942,6 +1248,48 @@
         "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
       }
     },
+    "node_modules/glob": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz",
+      "integrity": "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==",
+      "license": "ISC",
+      "dependencies": {
+        "foreground-child": "^3.1.0",
+        "jackspeak": "^3.1.2",
+        "minimatch": "^9.0.4",
+        "minipass": "^7.1.2",
+        "package-json-from-dist": "^1.0.0",
+        "path-scurry": "^1.11.1"
+      },
+      "bin": {
+        "glob": "dist/esm/bin.mjs"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/http-errors": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.0.tgz",
+      "integrity": "sha512-FtwrG/euBzaEjYeRqOgly7G0qviiXoJWnvEH2Z1plBdXgbyjv34pHTSb9zoeHMyDy33+DWy5Wt9Wo+TURtOYSQ==",
+      "license": "MIT",
+      "dependencies": {
+        "depd": "2.0.0",
+        "inherits": "2.0.4",
+        "setprototypeof": "1.2.0",
+        "statuses": "2.0.1",
+        "toidentifier": "1.0.1"
+      },
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/inherits": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
+      "license": "ISC"
+    },
     "node_modules/ipaddr.js": {
       "version": "1.9.1",
       "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz",
@@ -951,6 +1299,36 @@
         "node": ">= 0.10"
       }
     },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/isexe": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
+      "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+      "license": "ISC"
+    },
+    "node_modules/jackspeak": {
+      "version": "3.4.3",
+      "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-3.4.3.tgz",
+      "integrity": "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==",
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "@isaacs/cliui": "^8.0.2"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      },
+      "optionalDependencies": {
+        "@pkgjs/parseargs": "^0.11.0"
+      }
+    },
     "node_modules/json-schema-ref-resolver": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/json-schema-ref-resolver/-/json-schema-ref-resolver-1.0.1.tgz",
@@ -977,6 +1355,12 @@
         "set-cookie-parser": "^2.4.1"
       }
     },
+    "node_modules/lru-cache": {
+      "version": "10.4.3",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz",
+      "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==",
+      "license": "ISC"
+    },
     "node_modules/make-error": {
       "version": "1.3.6",
       "resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz",
@@ -984,6 +1368,42 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/mime": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-3.0.0.tgz",
+      "integrity": "sha512-jSCU7/VB1loIWBZe14aEYHU/+1UMEHoaO7qxCOVJOw9GgH72VAWppxNcjU+x9a2k3GSIBXNKxXQFqRvvZ7vr3A==",
+      "license": "MIT",
+      "bin": {
+        "mime": "cli.js"
+      },
+      "engines": {
+        "node": ">=10.0.0"
+      }
+    },
+    "node_modules/minimatch": {
+      "version": "9.0.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz",
+      "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==",
+      "license": "ISC",
+      "dependencies": {
+        "brace-expansion": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=16 || 14 >=14.17"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/minipass": {
+      "version": "7.1.2",
+      "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.2.tgz",
+      "integrity": "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=16 || 14 >=14.17"
+      }
+    },
     "node_modules/mnemonist": {
       "version": "0.39.6",
       "resolved": "https://registry.npmjs.org/mnemonist/-/mnemonist-0.39.6.tgz",
@@ -1008,6 +1428,52 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/once": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
+      "license": "ISC",
+      "dependencies": {
+        "wrappy": "1"
+      }
+    },
+    "node_modules/package-json-from-dist": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz",
+      "integrity": "sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==",
+      "license": "BlueOak-1.0.0"
+    },
+    "node_modules/path-key": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+      "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/path-scurry": {
+      "version": "1.11.1",
+      "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-1.11.1.tgz",
+      "integrity": "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==",
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "lru-cache": "^10.2.0",
+        "minipass": "^5.0.0 || ^6.0.2 || ^7.0.0"
+      },
+      "engines": {
+        "node": ">=16 || 14 >=14.18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/pend": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/pend/-/pend-1.2.0.tgz",
+      "integrity": "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg==",
+      "license": "MIT"
+    },
     "node_modules/pino": {
       "version": "9.14.0",
       "resolved": "https://registry.npmjs.org/pino/-/pino-9.14.0.tgz",
@@ -1139,6 +1605,26 @@
       "integrity": "sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==",
       "license": "MIT"
     },
+    "node_modules/safe-buffer": {
+      "version": "5.2.1",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
+      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/safe-regex2": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/safe-regex2/-/safe-regex2-3.1.0.tgz",
@@ -1181,6 +1667,45 @@
       "integrity": "sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==",
       "license": "MIT"
     },
+    "node_modules/setprototypeof": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz",
+      "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==",
+      "license": "ISC"
+    },
+    "node_modules/shebang-command": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+      "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+      "license": "MIT",
+      "dependencies": {
+        "shebang-regex": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/shebang-regex": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+      "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/signal-exit": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
+      "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/sonic-boom": {
       "version": "4.2.0",
       "resolved": "https://registry.npmjs.org/sonic-boom/-/sonic-boom-4.2.0.tgz",
@@ -1199,6 +1724,111 @@
         "node": ">= 10.x"
       }
     },
+    "node_modules/statuses": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.1.tgz",
+      "integrity": "sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/string-width": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz",
+      "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==",
+      "license": "MIT",
+      "dependencies": {
+        "eastasianwidth": "^0.2.0",
+        "emoji-regex": "^9.2.2",
+        "strip-ansi": "^7.0.1"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/string-width-cjs": {
+      "name": "string-width",
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/string-width-cjs/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/string-width-cjs/node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT"
+    },
+    "node_modules/string-width-cjs/node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "7.1.2",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.1.2.tgz",
+      "integrity": "sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/strip-ansi?sponsor=1"
+      }
+    },
+    "node_modules/strip-ansi-cjs": {
+      "name": "strip-ansi",
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-ansi-cjs/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/thread-stream": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/thread-stream/-/thread-stream-3.1.0.tgz",
@@ -1217,6 +1847,15 @@
         "node": ">=12"
       }
     },
+    "node_modules/toidentifier": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
+      "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.6"
+      }
+    },
     "node_modules/ts-node": {
       "version": "10.9.2",
       "resolved": "https://registry.npmjs.org/ts-node/-/ts-node-10.9.2.tgz",
@@ -1296,6 +1935,15 @@
         "node": ">=14.17"
       }
     },
+    "node_modules/undici": {
+      "version": "6.23.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-6.23.0.tgz",
+      "integrity": "sha512-VfQPToRA5FZs/qJxLIinmU59u0r7LXqoJkCzinq3ckNJp3vKEh7jTWN589YQ5+aoAC/TGRLyJLCPKcLQbM8r9g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.17"
+      }
+    },
     "node_modules/undici-types": {
       "version": "7.16.0",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz",
@@ -1310,6 +1958,128 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/which": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^2.0.0"
+      },
+      "bin": {
+        "node-which": "bin/node-which"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/wrap-ansi": {
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-8.1.0.tgz",
+      "integrity": "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.1.0",
+        "string-width": "^5.0.1",
+        "strip-ansi": "^7.0.1"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi-cjs": {
+      "name": "wrap-ansi",
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
+      "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.0.0",
+        "string-width": "^4.1.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi-cjs/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/wrap-ansi-cjs/node_modules/ansi-styles": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "license": "MIT",
+      "dependencies": {
+        "color-convert": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi-cjs/node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT"
+    },
+    "node_modules/wrap-ansi-cjs/node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/wrap-ansi-cjs/node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/wrappy": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
+      "license": "ISC"
+    },
+    "node_modules/yauzl": {
+      "version": "2.10.0",
+      "resolved": "https://registry.npmjs.org/yauzl/-/yauzl-2.10.0.tgz",
+      "integrity": "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g==",
+      "license": "MIT",
+      "dependencies": {
+        "buffer-crc32": "~0.2.3",
+        "fd-slicer": "~1.1.0"
+      }
+    },
     "node_modules/yn": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/yn/-/yn-3.1.1.tgz",

packages/server/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@neuralnomads/codenomad",
+  "version": "0.11.1",
+  "description": "CodeNomad Server",
+  "license": "MIT",
+  "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": "dist/bin.js"
+  },
+  "scripts": {
+    "build": "npm run build:ui && npm run prepare-ui && tsc -p tsconfig.json && node ./scripts/copy-auth-pages.mjs && npm run prepare-config",
+    "build:ui": "npm run build --prefix ../ui",
+    "prepare-ui": "node ./scripts/copy-ui-dist.mjs",
+    "prepare-config": "node ./scripts/copy-opencode-config.mjs",
+    "dev": "cross-env CODENOMAD_DEV=1 CODENOMAD_SERVER_PASSWORD=codenomad-dev CLI_UI_DEV_SERVER=http://localhost:3000 CLI_HTTPS=false CLI_HTTP=true tsx src/index.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@fastify/cors": "^8.5.0",
+    "@fastify/reply-from": "^9.8.0",
+    "@fastify/static": "^7.0.4",
+    "commander": "^12.1.0",
+    "fastify": "^4.28.1",
+    "fuzzysort": "^2.0.4",
+    "node-forge": "^1.3.3",
+    "pino": "^9.4.0",
+    "undici": "^6.19.8",
+    "yaml": "^2.4.2",
+    "yauzl": "^2.10.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node-forge": "^1.3.14",
+    "@types/yauzl": "^2.10.0",
+    "cross-env": "^7.0.3",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.6.3"
+  }
+}

packages/server/scripts/copy-auth-pages.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+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, "src/server/routes/auth-pages")
+const targetDir = path.resolve(cliRoot, "dist/server/routes/auth-pages")
+
+if (!existsSync(sourceDir)) {
+  console.error(`[copy-auth-pages] Missing auth pages at ${sourceDir}`)
+  process.exit(1)
+}
+
+rmSync(targetDir, { recursive: true, force: true })
+mkdirSync(targetDir, { recursive: true })
+cpSync(sourceDir, targetDir, { recursive: true })
+
+console.log(`[copy-auth-pages] Copied ${sourceDir} -> ${targetDir}`)

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,6 +1,6 @@
 import type {
+  AgentModelSelection,
   AgentModelSelections,
-  ConfigFile,
   ModelPreference,
   OpenCodeBinary,
   Preferences,
@@ -49,6 +49,38 @@ export interface WorkspaceDeleteResponse {
   status: WorkspaceStatus
 }
 
+export type WorktreeKind = "root" | "worktree"
+
+export interface WorktreeDescriptor {
+  /** Stable identifier used by CodeNomad + clients ("root" for repo root). */
+  slug: string
+  /** Absolute directory path on the server host. */
+  directory: string
+  kind: WorktreeKind
+  /** Optional VCS branch name when available. */
+  branch?: string
+}
+
+export interface WorktreeListResponse {
+  worktrees: WorktreeDescriptor[]
+  /** True when the workspace folder resolves to a Git repository. */
+  isGitRepo?: boolean
+}
+
+export interface WorktreeCreateRequest {
+  slug: string
+  /** Optional branch name (defaults to slug). */
+  branch?: string
+}
+
+export interface WorktreeMap {
+  version: 1
+  /** Default worktree to use for new sessions and as fallback. */
+  defaultWorktreeSlug: string
+  /** Mapping of *parent* session IDs to a worktree slug. */
+  parentSessionWorktreeSlug: Record<string, string>
+}
+
 export type LogLevel = "debug" | "info" | "warn" | "error"
 
 export interface WorkspaceLogEntry {
@@ -94,6 +126,26 @@ export interface FileSystemListResponse {
   metadata: FileSystemListingMetadata
 }
 
+export interface FileSystemCreateFolderRequest {
+  /**
+   * Path identifier for the currently browsed directory.
+   * Matches the `path` parameter used for `/api/filesystem`.
+   */
+  parentPath?: string
+  /** Single folder name (no separators). */
+  name: string
+}
+
+export interface FileSystemCreateFolderResponse {
+  /**
+   * Path identifier that can be passed back to `/api/filesystem` to browse the new folder.
+   * Relative for restricted listings, absolute for unrestricted.
+   */
+  path: string
+  /** Absolute folder path on the server host. */
+  absolutePath: string
+}
+
 export const WINDOWS_DRIVES_ROOT = "__drives__"
 
 export interface WorkspaceFileResponse {
@@ -103,8 +155,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,15 +175,16 @@ 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
   validationError?: string
 }
 
-export type AppConfig = ConfigFile
-export type AppConfigResponse = AppConfig
-export type AppConfigUpdateRequest = Partial<AppConfig>
+export type SettingsOwner = string
+export type SettingsBucket = Record<string, unknown>
+export type SettingsDoc = Record<string, unknown>
 
 export interface BinaryListResponse {
   binaries: BinaryRecord[]
@@ -149,8 +213,11 @@ export type WorkspaceEventType =
   | "workspace.error"
   | "workspace.stopped"
   | "workspace.log"
-  | "config.appChanged"
-  | "config.binariesChanged"
+  | "storage.configChanged"
+  | "storage.stateChanged"
+  | "instance.dataChanged"
+  | "instance.event"
+  | "instance.eventStatus"
 
 export type WorkspaceEventPayload =
   | { type: "workspace.created"; workspace: WorkspaceDescriptor }
@@ -158,18 +225,95 @@ export type WorkspaceEventPayload =
   | { type: "workspace.error"; workspace: WorkspaceDescriptor }
   | { type: "workspace.stopped"; workspaceId: string }
   | { type: "workspace.log"; entry: WorkspaceLogEntry }
-  | { type: "config.appChanged"; config: AppConfig }
-  | { type: "config.binariesChanged"; binaries: BinaryRecord[] }
+  | { type: "storage.configChanged"; owner: SettingsOwner; value: SettingsBucket }
+  | { type: "storage.stateChanged"; owner: SettingsOwner; value: SettingsBucket }
+  | { type: "instance.dataChanged"; instanceId: string; data: InstanceData }
+  | { type: "instance.event"; instanceId: string; event: InstanceStreamEvent }
+  | { type: "instance.eventStatus"; instanceId: string; status: InstanceStreamStatus; reason?: string }
+
+export interface NetworkAddress {
+  ip: string
+  family: "ipv4" | "ipv6"
+  scope: "external" | "internal" | "loopback"
+  /** Remote URL using the server's remote protocol/port for this IP. */
+  remoteUrl: string
+}
+
+export interface LatestReleaseInfo {
+  version: string
+  tag: string
+  url: string
+  channel: "stable" | "dev"
+  publishedAt?: string
+  notes?: string
+}
+
+export interface UiMeta {
+  version?: string
+  source: "bundled" | "downloaded" | "previous" | "override" | "dev-proxy" | "missing"
+}
+
+export interface SupportMeta {
+  supported: boolean
+  message?: string
+  minServerVersion?: string
+  latestServerVersion?: string
+  latestServerUrl?: string
+}
 
 export interface ServerMeta {
-  /** Base URL clients should target for REST calls (useful for Electron embedding). */
-  httpBaseUrl: string
+  /** URL desktop apps should use to connect (prefers loopback HTTP when enabled). */
+  localUrl: string
+  /** URL remote clients should use (prefers HTTPS when enabled). */
+  remoteUrl?: 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 local port in use after binding. */
+  localPort: number
+  /** Actual remote port in use after binding (when remoteUrl is set). */
+  remotePort?: 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[]
+  serverVersion?: string
+  ui?: UiMeta
+  support?: SupportMeta
+  /** Optional update info (dev channel only). */
+  update?: LatestReleaseInfo | null
+}
+
+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/auth/auth-store.ts

@@ -0,0 +1,175 @@
+import fs from "fs"
+import path from "path"
+import type { Logger } from "../logger"
+import { hashPassword, type PasswordHashRecord, verifyPassword } from "./password-hash"
+
+export interface AuthFile {
+  version: 1
+  username: string
+  password: PasswordHashRecord
+  userProvided: boolean
+  updatedAt: string
+}
+
+export interface AuthStatus {
+  username: string
+  passwordUserProvided: boolean
+}
+
+export class AuthStore {
+  private cachedFile: AuthFile | null = null
+  private overrideAuth: AuthFile | null = null
+  private bootstrapUsername: string | null = null
+
+  constructor(private readonly authFilePath: string, private readonly logger: Logger) {}
+
+  getAuthFilePath() {
+    return this.authFilePath
+  }
+
+  load(): AuthFile | null {
+    if (this.overrideAuth) {
+      return this.overrideAuth
+    }
+
+    if (this.cachedFile) {
+      return this.cachedFile
+    }
+
+    try {
+      if (!fs.existsSync(this.authFilePath)) {
+        return null
+      }
+      const raw = fs.readFileSync(this.authFilePath, "utf-8")
+      const parsed = JSON.parse(raw) as AuthFile
+      if (!parsed || parsed.version !== 1) {
+        this.logger.warn({ authFilePath: this.authFilePath }, "Auth file has unsupported version")
+        return null
+      }
+      this.cachedFile = parsed
+      return parsed
+    } catch (error) {
+      this.logger.warn({ err: error, authFilePath: this.authFilePath }, "Failed to load auth file")
+      return null
+    }
+  }
+
+  ensureInitialized(params: {
+    username: string
+    password?: string
+    allowBootstrapWithoutPassword: boolean
+  }): void {
+    const password = params.password?.trim()
+    if (password) {
+      const now = new Date().toISOString()
+      const runtime: AuthFile = {
+        version: 1,
+        username: params.username,
+        password: hashPassword(password),
+        userProvided: true,
+        updatedAt: now,
+      }
+      this.overrideAuth = runtime
+      this.cachedFile = null
+      this.bootstrapUsername = null
+      this.logger.debug({ authFilePath: this.authFilePath }, "Using runtime auth password override; ignoring auth file")
+      return
+    }
+
+    const existing = this.load()
+    if (existing) {
+      if (existing.username !== params.username) {
+        // Keep existing username unless explicitly overridden later.
+        this.logger.debug({ existing: existing.username, requested: params.username }, "Auth username differs from requested")
+      }
+      this.bootstrapUsername = null
+      return
+    }
+
+    if (params.allowBootstrapWithoutPassword) {
+      this.bootstrapUsername = params.username
+      this.logger.debug({ authFilePath: this.authFilePath }, "No auth file present; bootstrap-only mode enabled")
+      return
+    }
+
+    throw new Error(
+      `No server password configured. Create ${this.authFilePath} or start with --password / CODENOMAD_SERVER_PASSWORD.`,
+    )
+  }
+
+  validateCredentials(username: string, password: string): boolean {
+    const auth = this.load()
+    if (!auth) {
+      return false
+    }
+
+    if (username !== auth.username) {
+      return false
+    }
+
+    return verifyPassword(password, auth.password)
+  }
+
+  setPassword(params: { password: string; markUserProvided: boolean }): AuthStatus {
+    if (this.overrideAuth) {
+      throw new Error(
+        "Server password is provided via CLI/env and cannot be changed while running. Restart without --password / CODENOMAD_SERVER_PASSWORD to use auth.json.",
+      )
+    }
+
+    const current = this.load()
+
+    if (!current) {
+      if (!this.bootstrapUsername) {
+        throw new Error("Auth is not initialized")
+      }
+
+      const created: AuthFile = {
+        version: 1,
+        username: this.bootstrapUsername,
+        password: hashPassword(params.password),
+        userProvided: params.markUserProvided,
+        updatedAt: new Date().toISOString(),
+      }
+
+      this.persist(created)
+      this.bootstrapUsername = null
+      return { username: created.username, passwordUserProvided: created.userProvided }
+    }
+
+    const next: AuthFile = {
+      ...current,
+      password: hashPassword(params.password),
+      userProvided: params.markUserProvided,
+      updatedAt: new Date().toISOString(),
+    }
+
+    this.persist(next)
+    return { username: next.username, passwordUserProvided: next.userProvided }
+  }
+
+  getStatus(): AuthStatus {
+    const current = this.load()
+    if (current) {
+      return { username: current.username, passwordUserProvided: current.userProvided }
+    }
+
+    if (this.bootstrapUsername) {
+      return { username: this.bootstrapUsername, passwordUserProvided: false }
+    }
+
+    throw new Error("Auth is not initialized")
+  }
+
+  private persist(auth: AuthFile) {
+    try {
+      fs.mkdirSync(path.dirname(this.authFilePath), { recursive: true })
+      fs.writeFileSync(this.authFilePath, JSON.stringify(auth, null, 2), "utf-8")
+      this.cachedFile = auth
+      this.logger.debug({ authFilePath: this.authFilePath }, "Persisted auth file")
+    } catch (error) {
+      this.logger.error({ err: error, authFilePath: this.authFilePath }, "Failed to persist auth file")
+      throw error
+    }
+  }
+}

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

@@ -0,0 +1,38 @@
+import type { FastifyReply, FastifyRequest } from "fastify"
+
+export function parseCookies(header: string | undefined): Record<string, string> {
+  const result: Record<string, string> = {}
+  if (!header) return result
+
+  const parts = header.split(";")
+  for (const part of parts) {
+    const index = part.indexOf("=")
+    if (index < 0) continue
+    const key = part.slice(0, index).trim()
+    const value = part.slice(index + 1).trim()
+    if (!key) continue
+    result[key] = decodeURIComponent(value)
+  }
+  return result
+}
+
+export function isLoopbackAddress(remoteAddress: string | undefined): boolean {
+  if (!remoteAddress) return false
+  if (remoteAddress === "127.0.0.1" || remoteAddress === "::1") return true
+  if (remoteAddress === "::ffff:127.0.0.1") return true
+  return false
+}
+
+export function wantsHtml(request: FastifyRequest): boolean {
+  const accept = (request.headers["accept"] ?? "").toString().toLowerCase()
+  return accept.includes("text/html") || accept.includes("application/xhtml")
+}
+
+export function sendUnauthorized(request: FastifyRequest, reply: FastifyReply) {
+  if (request.method === "GET" && !request.url.startsWith("/api/") && wantsHtml(request)) {
+    reply.redirect("/login")
+    return
+  }
+
+  reply.code(401).send({ error: "Unauthorized" })
+}

packages/server/src/auth/manager.ts

@@ -0,0 +1,163 @@
+import type { FastifyReply, FastifyRequest } from "fastify"
+import path from "path"
+import type { Logger } from "../logger"
+import { AuthStore } from "./auth-store"
+import { TokenManager } from "./token-manager"
+import { SessionManager } from "./session-manager"
+import { isLoopbackAddress, parseCookies } from "./http-auth"
+
+export const BOOTSTRAP_TOKEN_STDOUT_PREFIX = "CODENOMAD_BOOTSTRAP_TOKEN:" as const
+export const DEFAULT_AUTH_USERNAME = "codenomad" as const
+export const DEFAULT_AUTH_COOKIE_NAME = "codenomad_session" as const
+
+export interface AuthManagerInit {
+  configPath: string
+  username: string
+  password?: string
+  generateToken: boolean
+  dangerouslySkipAuth?: boolean
+}
+
+export class AuthManager {
+  private readonly authStore: AuthStore | null
+  private readonly tokenManager: TokenManager | null
+  private readonly sessionManager = new SessionManager()
+  private readonly cookieName = DEFAULT_AUTH_COOKIE_NAME
+  private readonly authEnabled: boolean
+
+  constructor(private readonly init: AuthManagerInit, private readonly logger: Logger) {
+    this.authEnabled = !Boolean(init.dangerouslySkipAuth)
+
+    if (!this.authEnabled) {
+      this.authStore = null
+      this.tokenManager = null
+      return
+    }
+
+    const authFilePath = resolveAuthFilePath(init.configPath)
+    this.authStore = new AuthStore(authFilePath, logger.child({ component: "auth" }))
+
+    // Startup: password comes from CLI/env, auth.json, or bootstrap-only mode.
+    this.authStore.ensureInitialized({
+      username: init.username,
+      password: init.password,
+      allowBootstrapWithoutPassword: init.generateToken,
+    })
+
+    this.tokenManager = init.generateToken ? new TokenManager(60_000) : null
+  }
+
+  isAuthEnabled(): boolean {
+    return this.authEnabled
+  }
+
+  getCookieName(): string {
+    return this.cookieName
+  }
+
+  isTokenBootstrapEnabled(): boolean {
+    return Boolean(this.tokenManager)
+  }
+
+  issueBootstrapToken(): string | null {
+    if (!this.tokenManager) return null
+    return this.tokenManager.generate()
+  }
+
+  consumeBootstrapToken(token: string): boolean {
+    if (!this.tokenManager) return false
+    return this.tokenManager.consume(token)
+  }
+
+  validateLogin(username: string, password: string): boolean {
+    if (!this.authEnabled) {
+      return true
+    }
+    return this.requireAuthStore().validateCredentials(username, password)
+  }
+
+  createSession(username: string) {
+    if (!this.authEnabled) {
+      return { id: "auth-disabled", createdAt: Date.now(), username: this.init.username }
+    }
+    return this.sessionManager.createSession(username)
+  }
+
+  getStatus() {
+    if (!this.authEnabled) {
+      return { username: this.init.username, passwordUserProvided: false }
+    }
+    return this.requireAuthStore().getStatus()
+  }
+
+  setPassword(password: string) {
+    if (!this.authEnabled) {
+      throw new Error("Internal authentication is disabled")
+    }
+    return this.requireAuthStore().setPassword({ password, markUserProvided: true })
+  }
+
+  isLoopbackRequest(request: FastifyRequest): boolean {
+    return isLoopbackAddress(request.socket.remoteAddress)
+  }
+
+  getSessionFromRequest(request: FastifyRequest): { username: string; sessionId: string } | null {
+    if (!this.authEnabled) {
+      // When auth is disabled, treat all requests as authenticated.
+      // We still return a stable username so callers can display it.
+      return { username: this.init.username, sessionId: "auth-disabled" }
+    }
+
+    const cookies = parseCookies(request.headers.cookie)
+    const sessionId = cookies[this.cookieName]
+    const session = this.sessionManager.getSession(sessionId)
+    if (!session) return null
+    return { username: session.username, sessionId: session.id }
+  }
+
+  setSessionCookie(reply: FastifyReply, sessionId: string) {
+    reply.header("Set-Cookie", buildSessionCookie(this.cookieName, sessionId))
+  }
+
+  setSessionCookieWithOptions(reply: FastifyReply, sessionId: string, options?: { secure?: boolean }) {
+    reply.header("Set-Cookie", buildSessionCookie(this.cookieName, sessionId, options))
+  }
+
+  clearSessionCookie(reply: FastifyReply) {
+    reply.header("Set-Cookie", buildSessionCookie(this.cookieName, "", { maxAgeSeconds: 0 }))
+  }
+
+  clearSessionCookieWithOptions(reply: FastifyReply, options?: { secure?: boolean }) {
+    reply.header("Set-Cookie", buildSessionCookie(this.cookieName, "", { maxAgeSeconds: 0, ...options }))
+  }
+
+  private requireAuthStore(): AuthStore {
+    if (!this.authStore) {
+      throw new Error("Auth store is unavailable")
+    }
+    return this.authStore
+  }
+}
+
+function resolveAuthFilePath(configPath: string) {
+  const resolvedConfigPath = resolvePath(configPath)
+  return path.join(path.dirname(resolvedConfigPath), "auth.json")
+}
+
+function resolvePath(filePath: string) {
+  if (filePath.startsWith("~/")) {
+    return path.join(process.env.HOME ?? "", filePath.slice(2))
+  }
+  return path.resolve(filePath)
+}
+
+function buildSessionCookie(name: string, value: string, options?: { maxAgeSeconds?: number; secure?: boolean }) {
+  const parts = [`${name}=${encodeURIComponent(value)}`, "HttpOnly", "Path=/", "SameSite=Lax"]
+  if (options?.secure) {
+    parts.push("Secure")
+  }
+  if (options?.maxAgeSeconds !== undefined) {
+    parts.push(`Max-Age=${Math.max(0, Math.floor(options.maxAgeSeconds))}`)
+  }
+  return parts.join("; ")
+}

packages/server/src/auth/password-hash.ts

@@ -0,0 +1,49 @@
+import crypto from "crypto"
+
+export interface PasswordHashRecord {
+  algorithm: "scrypt"
+  saltBase64: string
+  hashBase64: string
+  keyLength: number
+  params: {
+    N: number
+    r: number
+    p: number
+    maxmem: number
+  }
+}
+
+const DEFAULT_SCRYPT_PARAMS = {
+  N: 16384,
+  r: 8,
+  p: 1,
+  maxmem: 32 * 1024 * 1024,
+}
+
+export function hashPassword(password: string): PasswordHashRecord {
+  const salt = crypto.randomBytes(16)
+  const params = DEFAULT_SCRYPT_PARAMS
+  const keyLength = 64
+  const derived = crypto.scryptSync(password, salt, keyLength, params)
+  return {
+    algorithm: "scrypt",
+    saltBase64: salt.toString("base64"),
+    hashBase64: Buffer.from(derived).toString("base64"),
+    keyLength,
+    params,
+  }
+}
+
+export function verifyPassword(password: string, record: PasswordHashRecord): boolean {
+  if (record.algorithm !== "scrypt") {
+    return false
+  }
+
+  const salt = Buffer.from(record.saltBase64, "base64")
+  const expected = Buffer.from(record.hashBase64, "base64")
+  const derived = crypto.scryptSync(password, salt, record.keyLength, record.params)
+  if (expected.length !== derived.length) {
+    return false
+  }
+  return crypto.timingSafeEqual(expected, Buffer.from(derived))
+}

packages/server/src/auth/session-manager.ts

@@ -0,0 +1,23 @@
+import crypto from "crypto"
+
+export interface SessionInfo {
+  id: string
+  createdAt: number
+  username: string
+}
+
+export class SessionManager {
+  private sessions = new Map<string, SessionInfo>()
+
+  createSession(username: string): SessionInfo {
+    const id = crypto.randomBytes(32).toString("base64url")
+    const info: SessionInfo = { id, createdAt: Date.now(), username }
+    this.sessions.set(id, info)
+    return info
+  }
+
+  getSession(id: string | undefined): SessionInfo | undefined {
+    if (!id) return undefined
+    return this.sessions.get(id)
+  }
+}

packages/server/src/auth/token-manager.ts

@@ -0,0 +1,32 @@
+import crypto from "crypto"
+
+export interface BootstrapToken {
+  token: string
+  createdAt: number
+  consumed: boolean
+}
+
+export class TokenManager {
+  private token: BootstrapToken | null = null
+
+  constructor(private readonly ttlMs: number) {}
+
+  generate(): string {
+    const token = crypto.randomBytes(32).toString("base64url")
+    this.token = { token, createdAt: Date.now(), consumed: false }
+    return token
+  }
+
+  consume(token: string): boolean {
+    if (!this.token) return false
+    if (this.token.consumed) return false
+    if (Date.now() - this.token.createdAt > this.ttlMs) return false
+    if (token !== this.token.token) return false
+    this.token.consumed = true
+    return true
+  }
+
+  peek(): string | null {
+    return this.token?.token ?? null
+  }
+}

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

@@ -0,0 +1,519 @@
+import { spawn, spawnSync, 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 EXIT_WAIT_TIMEOUT_MS = 5000
+const MAX_OUTPUT_BYTES = 20 * 1024
+const OUTPUT_PUBLISH_INTERVAL_MS = 1000
+
+interface ManagerDeps {
+  workspaceManager: WorkspaceManager
+  eventBus: EventBus
+  logger: Logger
+}
+
+interface RunningProcess {
+  id: string
+  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 { shellCommand, shellArgs, spawnOptions } = this.buildShellSpawn(command)
+
+    const child = spawn(shellCommand, shellArgs, {
+      cwd: workspace.path,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: process.platform !== "win32",
+      ...spawnOptions,
+    })
+
+    child.on("exit", () => {
+      this.killProcessTree(child, "SIGTERM")
+    })
+
+    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, { 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) {
+      this.killProcessTree(running.child, "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) {
+      this.killProcessTree(running.child, "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
+      this.killProcessTree(running.child, "SIGTERM")
+      await this.waitForExit(running)
+    }
+
+    await this.removeWorkspaceDir(workspaceId)
+  }
+
+  private killProcessTree(child: ChildProcess, signal: NodeJS.Signals) {
+    const pid = child.pid
+    if (!pid) return
+
+    if (process.platform === "win32") {
+      const args = this.buildWindowsTaskkillArgs(pid, signal)
+      try {
+        spawnSync("taskkill", args, { stdio: "ignore" })
+        return
+      } catch {
+        // Fall back to killing the direct child.
+      }
+    } else {
+      try {
+        process.kill(-pid, signal)
+        return
+      } catch {
+        // Fall back to killing the direct child.
+      }
+    }
+
+    try {
+      child.kill(signal)
+    } catch {
+      // ignore
+    }
+  }
+
+  private async waitForExit(running: RunningProcess) {
+    let exited = false
+    const exitPromise = running.exitPromise.finally(() => {
+      exited = true
+    })
+
+    const killTimeout = setTimeout(() => {
+      if (!exited) {
+        this.killProcessTree(running.child, "SIGKILL")
+      }
+    }, STOP_TIMEOUT_MS)
+
+    try {
+      await Promise.race([
+        exitPromise,
+        new Promise<void>((resolve) => {
+          setTimeout(resolve, EXIT_WAIT_TIMEOUT_MS)
+        }),
+      ])
+
+      if (!exited) {
+        this.killProcessTree(running.child, "SIGKILL")
+        this.running.delete(running.id)
+        this.deps.logger.warn({ pid: running.child.pid }, "Timed out waiting for background process to exit")
+      }
+    } finally {
+      clearTimeout(killTimeout)
+    }
+  }
+
+
+  private buildShellSpawn(command: string): { shellCommand: string; shellArgs: string[]; spawnOptions?: Record<string, unknown> } {
+    if (process.platform === "win32") {
+      const comspec = process.env.ComSpec || "cmd.exe"
+      return {
+        shellCommand: comspec,
+        shellArgs: ["/d", "/s", "/c", command],
+        spawnOptions: { windowsVerbatimArguments: true },
+      }
+    }
+
+    // Keep bash for macOS/Linux.
+    return { shellCommand: "bash", shellArgs: ["-c", command] }
+  }
+
+  private buildWindowsTaskkillArgs(pid: number, signal: NodeJS.Signals): string[] {
+    // Default to graceful termination (no /F), then force kill when we escalate.
+    const force = signal === "SIGKILL"
+    const args = ["/PID", String(pid), "/T"]
+    if (force) {
+      args.push("/F")
+    }
+    return args
+  }
+
+  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/location.ts

@@ -0,0 +1,78 @@
+import os from "os"
+import path from "path"
+
+export interface ConfigLocation {
+  /** Resolved absolute base directory containing all persisted server data. */
+  baseDir: string
+  /** Canonical YAML config file path (may be custom when input points to a YAML file). */
+  configYamlPath: string
+  /** Canonical YAML state file path (always in baseDir). */
+  stateYamlPath: string
+  /** Legacy JSON config file path used for migration (always in baseDir, or explicit JSON input). */
+  legacyJsonPath: string
+  /** Directory for per-instance persisted data (chat history etc.). */
+  instancesDir: string
+}
+
+function resolvePath(inputPath: string): string {
+  if (inputPath.startsWith("~/")) {
+    return path.join(os.homedir(), inputPath.slice(2))
+  }
+  return path.resolve(inputPath)
+}
+
+function isYamlPath(filePath: string): boolean {
+  const lower = filePath.toLowerCase()
+  return lower.endsWith(".yaml") || lower.endsWith(".yml")
+}
+
+function isJsonPath(filePath: string): boolean {
+  return filePath.toLowerCase().endsWith(".json")
+}
+
+/**
+ * Resolve CodeNomad's config location into a stable base directory + derived file paths.
+ *
+ * Supported inputs:
+ * - Directory: "~/.config/codenomad"
+ * - YAML file: "~/.config/codenomad/config.yaml" (or any *.yml/*.yaml)
+ * - Legacy JSON file: "~/.config/codenomad/config.json"
+ */
+export function resolveConfigLocation(raw: string): ConfigLocation {
+  const trimmed = (raw ?? "").trim()
+  const fallback = "~/.config/codenomad/config.json"
+  const input = trimmed.length > 0 ? trimmed : fallback
+
+  const resolvedInput = resolvePath(input)
+
+  if (isYamlPath(resolvedInput)) {
+    const baseDir = path.dirname(resolvedInput)
+    return {
+      baseDir,
+      configYamlPath: resolvedInput,
+      stateYamlPath: path.join(baseDir, "state.yaml"),
+      legacyJsonPath: path.join(baseDir, "config.json"),
+      instancesDir: path.join(baseDir, "instances"),
+    }
+  }
+
+  if (isJsonPath(resolvedInput)) {
+    const baseDir = path.dirname(resolvedInput)
+    return {
+      baseDir,
+      configYamlPath: path.join(baseDir, "config.yaml"),
+      stateYamlPath: path.join(baseDir, "state.yaml"),
+      legacyJsonPath: resolvedInput,
+      instancesDir: path.join(baseDir, "instances"),
+    }
+  }
+
+  const baseDir = resolvedInput
+  return {
+    baseDir,
+    configYamlPath: path.join(baseDir, "config.yaml"),
+    stateYamlPath: path.join(baseDir, "state.yaml"),
+    legacyJsonPath: path.join(baseDir, "config.json"),
+    instancesDir: path.join(baseDir, "instances"),
+  }
+}

packages/server/src/config/schema.ts

@@ -0,0 +1,104 @@
+import { z } from "zod"
+
+const ModelPreferenceSchema = z.object({
+  providerId: z.string(),
+  modelId: z.string(),
+})
+
+const AgentModelSelectionSchema = z.record(z.string(), ModelPreferenceSchema)
+const AgentModelSelectionsSchema = z.record(z.string(), AgentModelSelectionSchema)
+
+const PreferencesSchema = z
+  .object({
+  showThinkingBlocks: z.boolean().default(false),
+  thinkingBlocksExpansion: z.enum(["expanded", "collapsed"]).default("expanded"),
+  showTimelineTools: z.boolean().default(true),
+  promptSubmitOnEnter: z.boolean().default(false),
+  lastUsedBinary: z.string().optional(),
+  locale: z.string().optional(),
+  environmentVariables: z.record(z.string()).default({}),
+  modelRecents: z.array(ModelPreferenceSchema).default([]),
+  modelFavorites: z.array(ModelPreferenceSchema).default([]),
+  modelThinkingSelections: z.record(z.string(), z.string()).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),
+  listeningMode: z.enum(["local", "all"]).default("local"),
+
+  // OS notifications
+  osNotificationsEnabled: z.boolean().default(false),
+  osNotificationsAllowWhenVisible: z.boolean().default(false),
+  notifyOnNeedsInput: z.boolean().default(true),
+  notifyOnIdle: z.boolean().default(true),
+  })
+  // Preserve unknown preference keys so newer configs survive older binaries.
+  .passthrough()
+
+const RecentFolderSchema = z.object({
+  path: z.string(),
+  lastAccessed: z.number().nonnegative(),
+})
+
+const OpenCodeBinarySchema = z.object({
+  path: z.string(),
+  version: z.string().optional(),
+  lastUsed: z.number().nonnegative(),
+  label: z.string().optional(),
+})
+
+const ConfigFileSchema = z
+  .object({
+    preferences: PreferencesSchema.default({}),
+    recentFolders: z.array(RecentFolderSchema).default([]),
+    opencodeBinaries: z.array(OpenCodeBinarySchema).default([]),
+    theme: z.enum(["light", "dark", "system"]).optional(),
+  })
+  // Preserve unknown top-level keys so optional future features survive downgrades.
+  .passthrough()
+
+// On-disk config.yaml only stores stable configuration (not volatile state like recent folders).
+const ConfigYamlSchema = z
+  .object({
+    preferences: PreferencesSchema.default({}),
+    opencodeBinaries: z.array(OpenCodeBinarySchema).default([]),
+    theme: z.enum(["light", "dark", "system"]).optional(),
+  })
+  .passthrough()
+
+// On-disk state.yaml stores server-scoped mutable state (per-server, not per-client).
+const StateFileSchema = z
+  .object({
+    recentFolders: z.array(RecentFolderSchema).default([]),
+  })
+  .passthrough()
+
+const DEFAULT_CONFIG = ConfigFileSchema.parse({})
+const DEFAULT_CONFIG_YAML = ConfigYamlSchema.parse({})
+const DEFAULT_STATE = StateFileSchema.parse({})
+
+export {
+  ModelPreferenceSchema,
+  AgentModelSelectionSchema,
+  AgentModelSelectionsSchema,
+  PreferencesSchema,
+  RecentFolderSchema,
+  OpenCodeBinarySchema,
+  ConfigFileSchema,
+  ConfigYamlSchema,
+  StateFileSchema,
+  DEFAULT_CONFIG,
+  DEFAULT_CONFIG_YAML,
+  DEFAULT_STATE,
+}
+
+export type ModelPreference = z.infer<typeof ModelPreferenceSchema>
+export type AgentModelSelection = z.infer<typeof AgentModelSelectionSchema>
+export type AgentModelSelections = z.infer<typeof AgentModelSelectionsSchema>
+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 ConfigYamlFile = z.infer<typeof ConfigYamlSchema>
+export type StateFile = z.infer<typeof StateFileSchema>

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)
   }
 
@@ -19,16 +24,22 @@ export class EventBus extends EventEmitter {
     this.on("workspace.error", handler)
     this.on("workspace.stopped", handler)
     this.on("workspace.log", handler)
-    this.on("config.appChanged", handler)
-    this.on("config.binariesChanged", handler)
+    this.on("storage.configChanged", handler)
+    this.on("storage.stateChanged", handler)
+    this.on("instance.dataChanged", handler)
+    this.on("instance.event", handler)
+    this.on("instance.eventStatus", handler)
     return () => {
       this.off("workspace.created", handler)
       this.off("workspace.started", handler)
       this.off("workspace.error", handler)
       this.off("workspace.stopped", handler)
       this.off("workspace.log", handler)
-      this.off("config.appChanged", handler)
-      this.off("config.binariesChanged", handler)
+      this.off("storage.configChanged", handler)
+      this.off("storage.stateChanged", handler)
+      this.off("instance.dataChanged", handler)
+      this.off("instance.event", handler)
+      this.off("instance.eventStatus", 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/browser.ts

@@ -2,6 +2,7 @@ import fs from "fs"
 import os from "os"
 import path from "path"
 import {
+  FileSystemCreateFolderResponse,
   FileSystemEntry,
   FileSystemListResponse,
   FileSystemListingMetadata,
@@ -56,6 +57,30 @@ export class FileSystemBrowser {
     return this.listRestrictedWithMetadata(targetPath, includeFiles)
   }
 
+  createFolder(parentPath: string | undefined, folderName: string): FileSystemCreateFolderResponse {
+    const name = this.normalizeFolderName(folderName)
+
+    if (this.unrestricted) {
+      const resolvedParent = this.resolveUnrestrictedPath(parentPath)
+      if (this.isWindows && resolvedParent === WINDOWS_DRIVES_ROOT) {
+        throw new Error("Cannot create folders at drive root")
+      }
+      this.assertDirectoryExists(resolvedParent)
+      const absolutePath = this.resolveAbsoluteChild(resolvedParent, name)
+      fs.mkdirSync(absolutePath)
+      return { path: absolutePath, absolutePath }
+    }
+
+    const normalizedParent = this.normalizeRelativePath(parentPath)
+    const parentAbsolute = this.toRestrictedAbsolute(normalizedParent)
+    this.assertDirectoryExists(parentAbsolute)
+
+    const relativePath = this.buildRelativePath(normalizedParent, name)
+    const absolutePath = this.toRestrictedAbsolute(relativePath)
+    fs.mkdirSync(absolutePath)
+    return { path: relativePath, absolutePath }
+  }
+
   readFile(relativePath: string): string {
     if (this.unrestricted) {
       throw new Error("readFile is not available in unrestricted mode")
@@ -157,25 +182,58 @@ export class FileSystemBrowser {
     return { entries, metadata }
   }
 
+  private normalizeFolderName(input: string): string {
+    const name = input.trim()
+    if (!name) {
+      throw new Error("Folder name is required")
+    }
+
+    if (name === "." || name === "..") {
+      throw new Error("Invalid folder name")
+    }
+
+    if (name.startsWith("~")) {
+      throw new Error("Invalid folder name")
+    }
+
+    if (name.includes("/") || name.includes("\\")) {
+      throw new Error("Folder name must not include path separators")
+    }
+
+    if (name.includes("\u0000")) {
+      throw new Error("Invalid folder name")
+    }
+
+    return name
+  }
+
+  private assertDirectoryExists(directory: string) {
+    if (!fs.existsSync(directory)) {
+      throw new Error(`Directory does not exist: ${directory}`)
+    }
+    const stats = fs.statSync(directory)
+    if (!stats.isDirectory()) {
+      throw new Error(`Path is not a directory: ${directory}`)
+    }
+  }
+
   private readDirectoryEntries(directory: string, options: DirectoryReadOptions): FileSystemEntry[] {
     const dirents = fs.readdirSync(directory, { withFileTypes: true })
     const results: FileSystemEntry[] = []
 
     for (const entry of dirents) {
-      if (!options.includeFiles && !entry.isDirectory()) {
-        continue
-      }
-
       const absoluteEntryPath = path.join(directory, entry.name)
       let stats: fs.Stats
       try {
+        // Use fs.statSync (not Dirent.isDirectory) so symlinks to directories
+        // are treated as directories in directory-only listings.
         stats = fs.statSync(absoluteEntryPath)
       } catch {
         // Skip entries we cannot stat (insufficient permissions, etc.)
         continue
       }
 
-      const isDirectory = entry.isDirectory()
+      const isDirectory = stats.isDirectory()
       if (!options.includeFiles && !isDirectory) {
         continue
       }

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

@@ -0,0 +1,529 @@
+/**
+ * CLI entry point.
+ * For now this only wires the typed modules together; actual command handling comes later.
+ */
+import { Command, InvalidArgumentError, Option } from "commander"
+import path from "path"
+import { fileURLToPath } from "url"
+import { createRequire } from "module"
+import { createHttpServer } from "./server/http-server"
+import { WorkspaceManager } from "./workspaces/manager"
+import { resolveConfigLocation } from "./config/location"
+import { SettingsService } from "./settings/service"
+import { BinaryResolver } from "./settings/binaries"
+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 { resolveUi } from "./ui/remote-ui"
+import { AuthManager, BOOTSTRAP_TOKEN_STDOUT_PREFIX, DEFAULT_AUTH_USERNAME } from "./auth/manager"
+import { resolveHttpsOptions } from "./server/tls"
+import { resolveNetworkAddresses } from "./server/network-addresses"
+import { startDevReleaseMonitor } from "./releases/dev-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)
+const DEFAULT_UI_STATIC_DIR = path.resolve(__dirname, "../public")
+
+interface CliOptions {
+  host: string
+  https: boolean
+  http: boolean
+  httpsPort: number
+  httpPort: number
+  tlsKeyPath?: string
+  tlsCertPath?: string
+  tlsCaPath?: string
+  tlsSANs?: string
+  rootDir: string
+  configPath: string
+  unrestrictedRoot: boolean
+  logLevel?: string
+  logDestination?: string
+  uiStaticDir: string
+  uiDevServer?: string
+  uiAutoUpdate: boolean
+  uiNoUpdate: boolean
+  uiManifestUrl?: string
+  launch: boolean
+  authUsername: string
+  authPassword?: string
+  generateToken: boolean
+  dangerouslySkipAuth: boolean
+}
+
+const DEFAULT_HOST = "127.0.0.1"
+const DEFAULT_CONFIG_PATH = "~/.config/codenomad/config.json"
+const DEFAULT_HTTPS_PORT = 9898
+const DEFAULT_HTTP_PORT = 9899
+
+function parseCliOptions(argv: string[]): CliOptions {
+  const program = new Command()
+    .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))
+    .addOption(new Option("--https <enabled>", "Enable HTTPS listener (true|false)").env("CLI_HTTPS").default("true"))
+    .addOption(new Option("--http <enabled>", "Enable HTTP listener (true|false)").env("CLI_HTTP").default("false"))
+    .addOption(new Option("--https-port <number>", "HTTPS port (0 for auto)").env("CLI_HTTPS_PORT").default(DEFAULT_HTTPS_PORT).argParser(parsePort))
+    .addOption(new Option("--http-port <number>", "HTTP port (0 for auto)").env("CLI_HTTP_PORT").default(DEFAULT_HTTP_PORT).argParser(parsePort))
+    .addOption(new Option("--tls-key <path>", "TLS private key (PEM)").env("CLI_TLS_KEY"))
+    .addOption(new Option("--tls-cert <path>", "TLS certificate (PEM)").env("CLI_TLS_CERT"))
+    .addOption(new Option("--tls-ca <path>", "TLS CA chain (PEM)").env("CLI_TLS_CA"))
+    .addOption(new Option("--tlsSANs <list>", "Additional TLS SANs (comma-separated)").env("CLI_TLS_SANS"))
+    .addOption(
+      new Option("--workspace-root <path>", "Workspace root directory").env("CLI_WORKSPACE_ROOT").default(process.cwd()),
+    )
+    .addOption(new Option("--root <path>").env("CLI_ROOT").hideHelp(true))
+    .addOption(new Option("--unrestricted-root", "Allow browsing the full filesystem").env("CLI_UNRESTRICTED_ROOT").default(false))
+    .addOption(new Option("--config <path>", "Path to the config file").env("CLI_CONFIG").default(DEFAULT_CONFIG_PATH))
+    .addOption(new Option("--log-level <level>", "Log level (trace|debug|info|warn|error)").env("CLI_LOG_LEVEL"))
+    .addOption(new Option("--log-destination <path>", "Log destination file (defaults to stdout)").env("CLI_LOG_DESTINATION"))
+    .addOption(
+      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("--ui-no-update", "Disable remote UI updates").env("CLI_UI_NO_UPDATE").default(false))
+    .addOption(new Option("--ui-auto-update <enabled>", "Enable remote UI updates (true|false)").env("CLI_UI_AUTO_UPDATE").default("true"))
+    .addOption(new Option("--ui-manifest-url <url>", "Remote UI manifest URL").env("CLI_UI_MANIFEST_URL"))
+    .addOption(new Option("--launch", "Launch the UI in a browser after start").env("CLI_LAUNCH").default(false))
+    .addOption(
+      new Option("--username <username>", "Username for server authentication")
+        .env("CODENOMAD_SERVER_USERNAME")
+        .default(DEFAULT_AUTH_USERNAME),
+    )
+    .addOption(new Option("--password <password>", "Password for server authentication").env("CODENOMAD_SERVER_PASSWORD"))
+    .addOption(
+      new Option("--generate-token", "Emit a one-time bootstrap token for desktop")
+        .env("CODENOMAD_GENERATE_TOKEN")
+        .default(false),
+    )
+    .addOption(
+      new Option(
+        "--dangerously-skip-auth",
+        "Disable CodeNomad's internal auth. Use only behind a trusted perimeter (SSO/VPN/etc).",
+      )
+        .env("CODENOMAD_SKIP_AUTH")
+        .default(false),
+    )
+
+  program.parse(argv, { from: "user" })
+  const parsed = program.opts<{
+    host: string
+    https?: string
+    http?: string
+    httpsPort: number
+    httpPort: number
+    tlsKey?: string
+    tlsCert?: string
+    tlsCa?: string
+    tlsSANs?: string
+    workspaceRoot?: string
+    root?: string
+    unrestrictedRoot?: boolean
+    config: string
+    logLevel?: string
+    logDestination?: string
+    uiDir: string
+    uiDevServer?: string
+    uiNoUpdate?: boolean
+    uiAutoUpdate?: string
+    uiManifestUrl?: string
+    launch?: boolean
+    username: string
+    password?: string
+    generateToken?: boolean
+    dangerouslySkipAuth?: boolean
+  }>()
+
+  const parseBooleanEnv = (value: string | undefined): boolean => {
+    const normalized = (value ?? "").trim().toLowerCase()
+    return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "y" || normalized === "on"
+  }
+
+  const resolvedRoot = parsed.workspaceRoot ?? parsed.root ?? process.cwd()
+
+  const normalizedHost = resolveHost(parsed.host)
+
+  const autoUpdateString = (parsed.uiAutoUpdate ?? "true").trim().toLowerCase()
+  const uiAutoUpdate = autoUpdateString === "1" || autoUpdateString === "true" || autoUpdateString === "yes"
+
+  const httpsEnabled = parseBooleanEnv(parsed.https)
+  const httpEnabled = parseBooleanEnv(parsed.http)
+
+  if (!httpsEnabled && !httpEnabled) {
+    throw new InvalidArgumentError("At least one listener must be enabled (--https or --http)")
+  }
+
+  return {
+    host: normalizedHost,
+    https: httpsEnabled,
+    http: httpEnabled,
+    httpsPort: parsed.httpsPort,
+    httpPort: parsed.httpPort,
+    tlsKeyPath: parsed.tlsKey,
+    tlsCertPath: parsed.tlsCert,
+    tlsCaPath: parsed.tlsCa,
+    tlsSANs: parsed.tlsSANs,
+    rootDir: resolvedRoot,
+    configPath: parsed.config,
+    unrestrictedRoot: Boolean(parsed.unrestrictedRoot),
+    logLevel: parsed.logLevel,
+    logDestination: parsed.logDestination,
+    uiStaticDir: parsed.uiDir,
+    uiDevServer: parsed.uiDevServer,
+    uiAutoUpdate,
+    uiNoUpdate: Boolean(parsed.uiNoUpdate),
+    uiManifestUrl: parsed.uiManifestUrl,
+    launch: Boolean(parsed.launch),
+    authUsername: parsed.username,
+    authPassword: parsed.password,
+    generateToken: Boolean(parsed.generateToken),
+    dangerouslySkipAuth: Boolean(parsed.dangerouslySkipAuth),
+  }
+}
+
+function parsePort(input: string): number {
+  const value = Number(input)
+  if (!Number.isInteger(value) || value < 0 || value > 65535) {
+    throw new InvalidArgumentError("Port must be an integer between 0 and 65535")
+  }
+  return value
+}
+
+function resolveHost(input: string | undefined): string {
+  const trimmed = input?.trim()
+  if (!trimmed) return DEFAULT_HOST
+
+  if (trimmed === "0.0.0.0") {
+    return "0.0.0.0"
+  }
+
+  if (trimmed === "localhost") {
+    return DEFAULT_HOST
+  }
+
+  return trimmed
+}
+
+function programHasArg(argv: string[], flag: string): boolean {
+  return argv.includes(flag)
+}
+
+async function main() {
+  const options = parseCliOptions(process.argv.slice(2))
+  const logger = createLogger({ level: options.logLevel, destination: options.logDestination, component: "app" })
+  const workspaceLogger = logger.child({ component: "workspace" })
+  const configLogger = logger.child({ component: "config" })
+  const eventLogger = logger.child({ component: "events" })
+
+  const logOptions = {
+    ...options,
+    authPassword: options.authPassword ? "[REDACTED]" : undefined,
+  }
+
+  logger.info({ options: logOptions }, "Starting CodeNomad CLI server")
+
+  if (options.dangerouslySkipAuth) {
+    logger.warn(
+      "DANGEROUS: internal authentication is disabled (--dangerously-skip-auth / CODENOMAD_SKIP_AUTH).",
+    )
+  }
+
+  const eventBus = new EventBus(eventLogger)
+
+  const isLoopbackHost = (host: string) => host === "127.0.0.1" || host === "::1" || host.startsWith("127.")
+
+  const configLocation = resolveConfigLocation(options.configPath)
+  const configDir = configLocation.baseDir
+
+  if ((options.tlsKeyPath && !options.tlsCertPath) || (!options.tlsKeyPath && options.tlsCertPath)) {
+    throw new InvalidArgumentError("--tls-key and --tls-cert must be provided together")
+  }
+
+  const serverMeta: ServerMeta = {
+    localUrl: "http://localhost:0",
+    remoteUrl: undefined,
+    eventsUrl: `/api/events`,
+    host: options.host,
+    listeningMode: isLoopbackHost(options.host) ? "local" : "all",
+    localPort: 0,
+    remotePort: undefined,
+    hostLabel: options.host,
+    workspaceRoot: options.rootDir,
+    addresses: [],
+  }
+
+  const authManager = new AuthManager(
+    {
+      configPath: configLocation.configYamlPath,
+      username: options.authUsername,
+      password: options.authPassword,
+      generateToken: options.generateToken,
+      dangerouslySkipAuth: options.dangerouslySkipAuth,
+    },
+    logger.child({ component: "auth" }),
+  )
+
+  if (options.generateToken && !options.dangerouslySkipAuth) {
+    const token = authManager.issueBootstrapToken()
+    if (token) {
+      console.log(`${BOOTSTRAP_TOKEN_STDOUT_PREFIX}${token}`)
+    }
+  }
+
+  const tlsResolution = resolveHttpsOptions({
+    enabled: options.https,
+    configDir,
+    host: options.host,
+    tlsKeyPath: options.tlsKeyPath,
+    tlsCertPath: options.tlsCertPath,
+    tlsCaPath: options.tlsCaPath,
+    tlsSANs: options.tlsSANs,
+    logger: logger.child({ component: "tls" }),
+  })
+
+  const nodeExtraCaCertsPath = !options.http ? tlsResolution?.caCertPath : undefined
+
+  const settings = new SettingsService(configLocation, eventBus, configLogger)
+  const binaryResolver = new BinaryResolver(settings)
+  const workspaceManager = new WorkspaceManager({
+    rootDir: options.rootDir,
+    settings,
+    binaryResolver,
+    eventBus,
+    logger: workspaceLogger,
+    getServerBaseUrl: () => serverMeta.localUrl,
+    nodeExtraCaCertsPath,
+  })
+  const fileSystemBrowser = new FileSystemBrowser({ rootDir: options.rootDir, unrestricted: options.unrestrictedRoot })
+  const instanceStore = new InstanceStore(configLocation.instancesDir)
+  const instanceEventBridge = new InstanceEventBridge({
+    workspaceManager,
+    eventBus,
+    logger: logger.child({ component: "instance-events" }),
+  })
+
+  const uiDirEnvOverride = Boolean(process.env.CLI_UI_DIR)
+  const uiDirCliOverride = programHasArg(process.argv.slice(2), "--ui-dir")
+  const uiOverrideIsExplicit = uiDirEnvOverride || uiDirCliOverride
+  const uiDirOverride = uiOverrideIsExplicit ? options.uiStaticDir : undefined
+
+  const autoUpdateEnabled = options.uiAutoUpdate && !options.uiNoUpdate
+
+  const uiResolution = await resolveUi({
+    serverVersion: packageJson.version,
+    bundledUiDir: DEFAULT_UI_STATIC_DIR,
+    autoUpdate: autoUpdateEnabled,
+    overrideUiDir: uiDirOverride,
+    uiDevServerUrl: options.uiDevServer,
+    manifestUrl: options.uiManifestUrl,
+    logger: logger.child({ component: "ui" }),
+  })
+
+  serverMeta.serverVersion = packageJson.version
+  serverMeta.ui = {
+    version: uiResolution.uiVersion,
+    source: uiResolution.source,
+  }
+  serverMeta.support = {
+    supported: uiResolution.supported,
+    message: uiResolution.message,
+    latestServerVersion: uiResolution.latestServerVersion,
+    latestServerUrl: uiResolution.latestServerUrl,
+    minServerVersion: uiResolution.minServerVersion,
+  }
+
+  const updateChannel = (process.env.CODENOMAD_UPDATE_CHANNEL ?? "").trim().toLowerCase()
+  const githubRepo = (process.env.CODENOMAD_GITHUB_REPO ?? "NeuralNomadsAI/CodeNomad").trim()
+  const isDevVersion = packageJson.version.includes("-dev.") || packageJson.version.includes("-dev-")
+  const enableDevUpdateChecks = updateChannel === "dev" || (updateChannel === "" && isDevVersion)
+  const devReleaseMonitor = enableDevUpdateChecks
+    ? startDevReleaseMonitor({
+        currentVersion: packageJson.version,
+        repo: githubRepo,
+        logger: logger.child({ component: "updates" }),
+        onUpdate: (release) => {
+          serverMeta.update = release
+        },
+      })
+    : null
+
+  if (uiResolution.uiDevServerUrl && options.https) {
+    throw new InvalidArgumentError("UI dev proxy is only supported with --https=false --http=true")
+  }
+
+  const remoteAccessEnabled = options.host === "0.0.0.0" || !isLoopbackHost(options.host)
+
+  const httpsPortExplicit = programHasArg(process.argv.slice(2), "--https-port") || Boolean(process.env.CLI_HTTPS_PORT)
+  const httpPortExplicit = programHasArg(process.argv.slice(2), "--http-port") || Boolean(process.env.CLI_HTTP_PORT)
+
+  const httpsBindPort = httpsPortExplicit ? options.httpsPort : 0
+  const httpBindPort = httpPortExplicit ? options.httpPort : 0
+
+  // Listener binding rules:
+  // - Remote access enabled: HTTP listens on loopback, HTTPS on all IPs (host=0.0.0.0 / LAN IP).
+  // - Remote access disabled: both listen on loopback.
+  // - HTTP-only mode: respect --host (used for dev/testing).
+  const httpsBindHost = remoteAccessEnabled ? options.host : "127.0.0.1"
+  const httpBindHost = options.http ? (options.https ? "127.0.0.1" : options.host) : "127.0.0.1"
+
+  const servers: Array<ReturnType<typeof createHttpServer>> = []
+
+  const httpServer = options.http
+    ? createHttpServer({
+        bindHost: httpBindHost,
+        bindPort: httpBindPort,
+        defaultPort: options.httpPort,
+        protocol: "http",
+        workspaceManager,
+        settings,
+        fileSystemBrowser,
+        eventBus,
+        serverMeta,
+        instanceStore,
+        authManager,
+        uiStaticDir: uiResolution.uiStaticDir ?? DEFAULT_UI_STATIC_DIR,
+        uiDevServerUrl: uiResolution.uiDevServerUrl,
+        logger,
+      })
+    : null
+
+  const httpsServer = options.https
+    ? createHttpServer({
+        bindHost: httpsBindHost,
+        bindPort: httpsBindPort,
+        defaultPort: options.httpsPort,
+        protocol: "https",
+        httpsOptions: tlsResolution?.httpsOptions,
+        workspaceManager,
+        settings,
+        fileSystemBrowser,
+        eventBus,
+        serverMeta,
+        instanceStore,
+        authManager,
+        uiStaticDir: uiResolution.uiStaticDir ?? DEFAULT_UI_STATIC_DIR,
+        uiDevServerUrl: undefined,
+        logger,
+      })
+    : null
+
+  if (httpServer) servers.push(httpServer)
+  if (httpsServer) servers.push(httpsServer)
+
+  const [httpStart, httpsStart] = await Promise.all([
+    httpServer ? httpServer.start() : Promise.resolve(null),
+    httpsServer ? httpsServer.start() : Promise.resolve(null),
+  ])
+
+  const localStart = httpStart ?? httpsStart
+  if (!localStart) {
+    throw new Error("No listeners started")
+  }
+
+  const remoteStart = httpsStart ?? httpStart
+  const localProtocol: "http" | "https" = httpStart ? "http" : "https"
+  const remoteProtocol: "http" | "https" = httpsStart ? "https" : "http"
+
+  // Use an explicit IPv4 loopback address for the "local" URL.
+  // On macOS, `localhost` often resolves to ::1 first, and it is possible to have
+  // another instance bound on IPv6 while this instance binds IPv4 (or vice versa),
+  // which can lead clients to talk to the wrong process.
+  const localUrl = `${localProtocol}://127.0.0.1:${localStart.port}`
+  let remoteUrl: string | undefined
+  if (remoteStart) {
+    const wantsAll = options.host === "0.0.0.0" || !isLoopbackHost(options.host)
+    let remoteHost = options.host
+    if (wantsAll) {
+      if (options.host === "0.0.0.0") {
+        const candidates = resolveNetworkAddresses({ host: options.host, protocol: remoteProtocol, port: remoteStart.port })
+        remoteHost = candidates.find((addr) => addr.scope === "external")?.ip ?? "localhost"
+      }
+    } else {
+      remoteHost = "localhost"
+    }
+    remoteUrl = `${remoteProtocol}://${remoteHost}:${remoteStart.port}`
+  }
+
+  serverMeta.localUrl = localUrl
+  serverMeta.localPort = localStart.port
+  serverMeta.remoteUrl = remoteUrl
+  serverMeta.remotePort = remoteStart?.port
+  serverMeta.host = options.host
+  serverMeta.listeningMode = options.host === "0.0.0.0" || !isLoopbackHost(options.host) ? "all" : "local"
+
+  if (serverMeta.remotePort && remoteUrl) {
+    serverMeta.addresses = resolveNetworkAddresses({ host: options.host, protocol: remoteProtocol, port: serverMeta.remotePort })
+  } else {
+    serverMeta.addresses = []
+  }
+
+  console.log(`Local Connection URL : ${serverMeta.localUrl}`)
+  if (serverMeta.remoteUrl) {
+    console.log(`Remote Connection URL : ${serverMeta.remoteUrl}`)
+  }
+
+  if (options.launch) {
+    await launchInBrowser(serverMeta.localUrl, logger.child({ component: "launcher" }))
+  }
+
+  let shuttingDown = false
+
+  const shutdown = async () => {
+    if (shuttingDown) {
+      logger.info("Shutdown already in progress, ignoring signal")
+      return
+    }
+    shuttingDown = true
+    logger.info("Received shutdown signal, stopping workspaces and server")
+
+    const shutdownWorkspaces = (async () => {
+      try {
+        instanceEventBridge.shutdown()
+      } catch (error) {
+        logger.warn({ err: error }, "Instance event bridge shutdown failed")
+      }
+
+      try {
+        await workspaceManager.shutdown()
+        logger.info("Workspace manager shutdown complete")
+      } catch (error) {
+        logger.error({ err: error }, "Workspace manager shutdown failed")
+      }
+    })()
+
+    const shutdownHttp = (async () => {
+      try {
+        await Promise.allSettled(servers.map((srv) => srv.stop()))
+        logger.info("HTTP server(s) stopped")
+      } catch (error) {
+        logger.error({ err: error }, "Failed to stop HTTP server")
+      }
+    })()
+
+    await Promise.allSettled([shutdownWorkspaces, shutdownHttp])
+
+    // no-op: remote UI manifest replaces GitHub release monitor
+
+    devReleaseMonitor?.stop()
+
+    logger.info("Exiting process")
+    process.exit(0)
+  }
+
+  process.on("SIGINT", shutdown)
+  process.on("SIGTERM", shutdown)
+}
+
+main().catch((error) => {
+  const logger = createLogger({ component: "app" })
+  logger.error({ err: error }, "CLI server crashed")
+  process.exit(1)
+})

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/dev-release-monitor.ts

@@ -0,0 +1,118 @@
+import { fetch } from "undici"
+import type { LatestReleaseInfo } from "../api-types"
+import type { Logger } from "../logger"
+import { compareVersionStrings, stripTagPrefix } from "./release-monitor"
+
+interface DevReleaseMonitorOptions {
+  /** Current running server version (from package.json). */
+  currentVersion: string
+  /** GitHub repo in the form "owner/name". */
+  repo: string
+  logger: Logger
+  onUpdate: (release: LatestReleaseInfo | null) => void
+  pollIntervalMs?: number
+}
+
+interface GithubReleaseListItem {
+  tag_name?: string
+  name?: string
+  html_url?: string
+  body?: string
+  published_at?: string
+  created_at?: string
+  prerelease?: boolean
+  draft?: boolean
+}
+
+export interface DevReleaseMonitor {
+  stop(): void
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 15 * 60 * 1000
+
+export function startDevReleaseMonitor(options: DevReleaseMonitorOptions): DevReleaseMonitor {
+  let stopped = false
+  let timer: ReturnType<typeof setInterval> | null = null
+
+  const pollIntervalMs =
+    Number.isFinite(options.pollIntervalMs) && (options.pollIntervalMs ?? 0) > 0
+      ? (options.pollIntervalMs as number)
+      : DEFAULT_POLL_INTERVAL_MS
+
+  const refresh = async () => {
+    if (stopped) return
+    try {
+      const release = await fetchLatestPrerelease({
+        repo: options.repo,
+        currentVersion: options.currentVersion,
+      })
+      options.onUpdate(release)
+    } catch (error) {
+      options.logger.debug({ err: error }, "Failed to refresh dev prerelease information")
+    }
+  }
+
+  void refresh()
+  timer = setInterval(() => void refresh(), pollIntervalMs)
+
+  return {
+    stop() {
+      stopped = true
+      if (timer) {
+        clearInterval(timer)
+        timer = null
+      }
+    },
+  }
+}
+
+async function fetchLatestPrerelease(args: {
+  repo: string
+  currentVersion: string
+}): Promise<LatestReleaseInfo | null> {
+  const normalizedRepo = args.repo.trim()
+  if (!/^[^/\s]+\/[^/\s]+$/.test(normalizedRepo)) {
+    throw new Error(`Invalid GitHub repo: ${args.repo}`)
+  }
+
+  const apiUrl = `https://api.github.com/repos/${normalizedRepo}/releases?per_page=20`
+  const response = await fetch(apiUrl, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      "User-Agent": "CodeNomad-CLI",
+    },
+  })
+
+  if (!response.ok) {
+    throw new Error(`GitHub releases API responded with ${response.status}`)
+  }
+
+  const list = (await response.json()) as GithubReleaseListItem[]
+  const latest = list.find((r) => r && r.prerelease === true && r.draft !== true)
+  if (!latest) {
+    return null
+  }
+
+  const tag = latest.tag_name || latest.name
+  if (!tag) {
+    return null
+  }
+
+  const normalizedVersion = stripTagPrefix(tag)
+  if (!normalizedVersion) {
+    return null
+  }
+
+  if (compareVersionStrings(normalizedVersion, args.currentVersion) <= 0) {
+    return null
+  }
+
+  return {
+    version: normalizedVersion,
+    tag,
+    url: latest.html_url ?? `https://github.com/${normalizedRepo}/releases/tag/${encodeURIComponent(tag)}`,
+    channel: "dev",
+    publishedAt: latest.published_at ?? latest.created_at,
+    notes: latest.body,
+  }
+}

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

@@ -0,0 +1,149 @@
+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
+    },
+  }
+}
+
+export function compareVersionStrings(a: string, b: string): number {
+  const left = parseVersion(a)
+  const right = parseVersion(b)
+  return compareVersions(left, right)
+}
+
+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,
+  }
+}
+
+export 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 dashIndex = normalized.indexOf("-")
+  const core = dashIndex >= 0 ? normalized.slice(0, dashIndex) : normalized
+  const prerelease = dashIndex >= 0 ? normalized.slice(dashIndex + 1) : null
+  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

@@ -0,0 +1,691 @@
+import Fastify, { type FastifyInstance, type FastifyReply, type FastifyRequest } from "fastify"
+import cors from "@fastify/cors"
+import fastifyStatic from "@fastify/static"
+import replyFrom from "@fastify/reply-from"
+import fs from "fs"
+import path from "path"
+import { fetch } from "undici"
+import type { Logger } from "../logger"
+import { WorkspaceManager } from "../workspaces/manager"
+import { isValidWorktreeSlug, listWorktrees, resolveRepoRoot } from "../workspaces/git-worktrees"
+
+import type { SettingsService } from "../settings/service"
+import { FileSystemBrowser } from "../filesystem/browser"
+import { EventBus } from "../events/bus"
+import { registerWorkspaceRoutes } from "./routes/workspaces"
+import { registerSettingsRoutes } from "./routes/settings"
+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 { registerWorktreeRoutes } from "./routes/worktrees"
+import { ServerMeta } from "../api-types"
+import { InstanceStore } from "../storage/instance-store"
+import { BackgroundProcessManager } from "../background-processes/manager"
+import type { AuthManager } from "../auth/manager"
+import { registerAuthRoutes } from "./routes/auth"
+import { sendUnauthorized, wantsHtml } from "../auth/http-auth"
+
+interface HttpServerDeps {
+  bindHost: string
+  bindPort: number
+  /** When bindPort is 0, try this first. */
+  defaultPort: number
+  protocol: "http" | "https"
+  httpsOptions?: { key: string | Buffer; cert: string | Buffer; ca?: string | Buffer }
+  workspaceManager: WorkspaceManager
+  settings: SettingsService
+  fileSystemBrowser: FileSystemBrowser
+  eventBus: EventBus
+  serverMeta: ServerMeta
+  instanceStore: InstanceStore
+  authManager: AuthManager
+  uiStaticDir: string
+  uiDevServerUrl?: string
+  logger: Logger
+}
+
+interface HttpServerStartResult {
+  port: number
+  url: string
+  displayHost: string
+}
+
+export function createHttpServer(deps: HttpServerDeps) {
+  // Fastify's type-level RawServer inference gets noisy when toggling HTTP vs HTTPS.
+  // We keep the runtime behavior correct and cast the instance to a generic FastifyInstance.
+  const app = Fastify(
+    ({
+      logger: false,
+      ...(deps.protocol === "https" && deps.httpsOptions ? { https: deps.httpsOptions } : {}),
+    } as unknown) as any,
+  ) as unknown as FastifyInstance
+  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) => {
+    sseClients.add(cleanup)
+    return () => sseClients.delete(cleanup)
+  }
+  const closeSseClients = () => {
+    for (const cleanup of Array.from(sseClients)) {
+      cleanup()
+    }
+    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()
+  })
+
+  const allowedDevOrigins = new Set(["http://localhost:3000", "http://127.0.0.1:3000"])
+  const isLoopbackHost = (host: string) => host === "127.0.0.1" || host === "::1" || host.startsWith("127.")
+
+  const getSelfOrigins = (): Set<string> => {
+    const origins = new Set<string>()
+    const candidates: Array<string | undefined> = [deps.serverMeta.localUrl, deps.serverMeta.remoteUrl]
+    for (const candidate of candidates) {
+      if (!candidate) continue
+      try {
+        origins.add(new URL(candidate).origin)
+      } catch {
+        // ignore
+      }
+    }
+    for (const addr of deps.serverMeta.addresses ?? []) {
+      try {
+        origins.add(new URL(addr.remoteUrl).origin)
+      } catch {
+        // ignore
+      }
+    }
+    return origins
+  }
+
+  app.register(cors, {
+    origin: (origin, cb) => {
+      if (!origin) {
+        cb(null, true)
+        return
+      }
+
+      const selfOrigins = getSelfOrigins()
+      if (selfOrigins.has(origin)) {
+        cb(null, true)
+        return
+      }
+
+       if (allowedDevOrigins.has(origin)) {
+         cb(null, true)
+         return
+       }
+
+       // When we bind to a non-loopback host (e.g., 0.0.0.0 or LAN IP), allow cross-origin UI access.
+       if (deps.bindHost === "0.0.0.0" || !isLoopbackHost(deps.bindHost)) {
+         cb(null, true)
+         return
+       }
+
+
+      cb(null, false)
+    },
+    credentials: true,
+  })
+
+  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" }),
+  })
+
+  registerAuthRoutes(app, { authManager: deps.authManager })
+
+  app.addHook("preHandler", (request, reply, done) => {
+    const rawUrl = request.raw.url ?? request.url
+    const pathname = (rawUrl.split("?")[0] ?? "").trim()
+
+    const publicApiPaths = new Set(["/api/auth/login", "/api/auth/token", "/api/auth/status", "/api/auth/logout"])
+    const publicPagePaths = new Set(["/login"])
+    if (deps.authManager.isTokenBootstrapEnabled()) {
+      publicPagePaths.add("/auth/token")
+    }
+
+    if (publicApiPaths.has(pathname) || publicPagePaths.has(pathname)) {
+      done()
+      return
+    }
+
+    const session = deps.authManager.getSessionFromRequest(request)
+
+    const requiresAuthForApi = pathname.startsWith("/api/") || pathname.startsWith("/workspaces/")
+    if (requiresAuthForApi && !session) {
+      // Allow OpenCode plugin -> CodeNomad calls with per-instance basic auth.
+      const pluginMatch = pathname.match(/^\/workspaces\/([^/]+)\/plugin(?:\/|$)/)
+      if (pluginMatch) {
+        const workspaceId = pluginMatch[1]
+        const expected = deps.workspaceManager.getInstanceAuthorizationHeader(workspaceId)
+        const provided = Array.isArray(request.headers.authorization)
+          ? request.headers.authorization[0]
+          : request.headers.authorization
+
+        if (expected && provided && provided === expected) {
+          done()
+          return
+        }
+      }
+
+      sendUnauthorized(request, reply)
+      return
+    }
+
+    if (!session && wantsHtml(request)) {
+      reply.redirect("/login")
+      return
+    }
+
+    done()
+  })
+
+  app.get("/", async (request, reply) => {
+    const session = deps.authManager.getSessionFromRequest(request)
+    if (!session) {
+      reply.redirect("/login")
+      return
+    }
+
+    if (deps.uiDevServerUrl) {
+      await proxyToDevServer(request, reply, deps.uiDevServerUrl)
+      return
+    }
+
+    const uiDir = deps.uiStaticDir
+    const indexPath = path.join(uiDir, "index.html")
+    if (uiDir && fs.existsSync(indexPath)) {
+      reply.type("text/html").send(fs.readFileSync(indexPath, "utf-8"))
+      return
+    }
+
+    reply.code(404).send({ message: "UI bundle missing" })
+  })
+
+  registerWorkspaceRoutes(app, { workspaceManager: deps.workspaceManager })
+  registerSettingsRoutes(app, { settings: deps.settings, logger: apiLogger })
+  registerFilesystemRoutes(app, { fileSystemBrowser: deps.fileSystemBrowser })
+  registerMetaRoutes(app, { serverMeta: deps.serverMeta })
+  registerEventRoutes(app, { eventBus: deps.eventBus, registerClient: registerSseClient, logger: sseLogger })
+  registerWorktreeRoutes(app, { workspaceManager: deps.workspaceManager })
+  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, deps.authManager)
+  } else {
+    setupStaticUi(app, deps.uiStaticDir, deps.authManager)
+  }
+
+  return {
+    instance: app,
+    start: async (): Promise<HttpServerStartResult> => {
+      const attemptListen = async (requestedPort: number) => {
+        const addressInfo = await app.listen({ port: requestedPort, host: deps.bindHost })
+        return { addressInfo, requestedPort }
+      }
+
+      const autoPortRequested = deps.bindPort === 0
+      const primaryPort = autoPortRequested ? deps.defaultPort : deps.bindPort
+
+      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.bindHost === "127.0.0.1" ? "localhost" : deps.bindHost
+      const serverUrl = `${deps.protocol}://${displayHost}:${actualPort}`
+
+      deps.logger.info({ port: actualPort, host: deps.bindHost, protocol: deps.protocol }, "HTTP server listening")
+
+      return { port: actualPort, url: serverUrl, displayHost }
+    },
+    stop: () => {
+      closeSseClients()
+      return app.close()
+    },
+  }
+}
+
+interface InstanceProxyDeps {
+  workspaceManager: WorkspaceManager
+  logger: Logger
+}
+
+function registerInstanceProxyRoutes(app: FastifyInstance, deps: InstanceProxyDeps) {
+  app.register(async (instance) => {
+    instance.removeAllContentTypeParsers()
+    instance.addContentTypeParser("*", (req, body, done) => done(null, body))
+
+    const proxyBaseHandler = async (
+      request: FastifyRequest<{ Params: { id: string; slug: string } }>,
+      reply: FastifyReply,
+    ) => {
+      await proxyWorkspaceRequest({
+        request,
+        reply,
+        workspaceManager: deps.workspaceManager,
+        worktreeSlug: request.params.slug,
+        pathSuffix: "",
+        logger: deps.logger,
+      })
+    }
+
+    const proxyWildcardHandler = async (
+      request: FastifyRequest<{ Params: { id: string; slug: string; "*": string } }>,
+      reply: FastifyReply,
+    ) => {
+      await proxyWorkspaceRequest({
+        request,
+        reply,
+        workspaceManager: deps.workspaceManager,
+        worktreeSlug: request.params.slug,
+        pathSuffix: request.params["*"] ?? "",
+        logger: deps.logger,
+      })
+    }
+
+    instance.all("/workspaces/:id/worktrees/:slug/instance", proxyBaseHandler)
+    instance.all("/workspaces/:id/worktrees/:slug/instance/*", proxyWildcardHandler)
+  })
+}
+
+const INSTANCE_PROXY_HOST = "127.0.0.1"
+
+async function proxyWorkspaceRequest(args: {
+  request: FastifyRequest
+  reply: FastifyReply
+  workspaceManager: WorkspaceManager
+  logger: Logger
+  worktreeSlug: string
+  pathSuffix?: string
+}) {
+  const { request, reply, workspaceManager, logger, worktreeSlug } = args
+  const workspaceId = (request.params as { id: string }).id
+  const workspace = workspaceManager.get(workspaceId)
+
+  const bodyToJson = (body: unknown): unknown => {
+    if (body == null) return null
+
+    const anyBody = body as any
+    if (anyBody && typeof anyBody.pipe === "function") {
+      // Don't consume streams (would break proxying).
+      // Best-effort: if the stream already has buffered chunks, parse those.
+      try {
+        const buffered = anyBody?._readableState?.buffer
+        if (Array.isArray(buffered) && buffered.length > 0) {
+          const chunks: Buffer[] = []
+          for (const entry of buffered) {
+            if (!entry) continue
+            if (Buffer.isBuffer(entry)) {
+              chunks.push(entry)
+              continue
+            }
+            const data = (entry as any).data
+            if (Buffer.isBuffer(data)) {
+              chunks.push(data)
+            }
+          }
+
+          if (chunks.length > 0) {
+            const text = Buffer.concat(chunks).toString("utf-8")
+            try {
+              return JSON.parse(text)
+            } catch {
+              return { __raw: text }
+            }
+          }
+        }
+      } catch {
+        // fall through
+      }
+
+      return { __stream: true }
+    }
+
+    const maybeParse = (input: string): unknown => {
+      try {
+        return JSON.parse(input)
+      } catch {
+        return { __raw: input }
+      }
+    }
+
+    if (Buffer.isBuffer(body)) {
+      return maybeParse(body.toString("utf-8"))
+    }
+
+    if (typeof body === "string") {
+      return maybeParse(body)
+    }
+
+    if (typeof body === "object") {
+      return body
+    }
+
+    return body
+  }
+
+  if (!workspace) {
+    reply.code(404).send({ error: "Workspace not found" })
+    return
+  }
+
+  const port = workspaceManager.getInstancePort(workspaceId)
+  if (!port) {
+    reply.code(502).send({ error: "Workspace instance is not ready" })
+    return
+  }
+
+  if (!isValidWorktreeSlug(worktreeSlug)) {
+    reply.code(400).send({ error: "Invalid worktree slug" })
+    return
+  }
+
+  const directory = await resolveWorktreeDirectory({
+    workspaceId,
+    workspacePath: workspace.path,
+    worktreeSlug,
+    logger,
+  })
+
+  if (!directory) {
+    reply.code(404).send({ error: "Worktree not found" })
+    return
+  }
+
+  const normalizedSuffix = normalizeInstanceSuffix(args.pathSuffix)
+  const queryIndex = (request.raw.url ?? "").indexOf("?")
+  const search = queryIndex >= 0 ? (request.raw.url ?? "").slice(queryIndex) : ""
+  const targetUrl = `http://${INSTANCE_PROXY_HOST}:${port}${normalizedSuffix}${search}`
+  const instanceAuthHeader = workspaceManager.getInstanceAuthorizationHeader(workspaceId)
+
+  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, {
+    rewriteRequestHeaders: (_originalRequest, headers) => {
+      if (instanceAuthHeader) {
+        headers.authorization = instanceAuthHeader
+      }
+
+      // OpenCode expects the *full* path; we send it via header to avoid query tampering.
+      const isNonASCII = /[^\x00-\x7F]/.test(directory)
+      const encodedDirectory = isNonASCII ? encodeURIComponent(directory) : directory
+
+      // Overwrite any client-provided value (case-insensitive headers are normalized by Node).
+      ;(headers as Record<string, unknown>)["x-opencode-directory"] = encodedDirectory
+
+      if (logger.isLevelEnabled("trace")) {
+        const outgoing: Record<string, unknown> = {}
+        for (const [key, value] of Object.entries(headers as Record<string, unknown>)) {
+          outgoing[key] = value
+        }
+
+        // Redact sensitive headers.
+        for (const key of Object.keys(outgoing)) {
+          const lower = key.toLowerCase()
+          if (lower === "authorization" || lower === "cookie" || lower === "set-cookie") {
+            outgoing[key] = "<redacted>"
+          }
+        }
+
+        logger.trace(
+          {
+            workspaceId,
+            method: request.method,
+            targetUrl,
+            worktreeSlug,
+            directory,
+            contentType: request.headers["content-type"],
+            body: bodyToJson(request.body),
+            headers: outgoing,
+          },
+          "Proxy -> OpenCode request",
+        )
+      }
+
+      return headers
+    },
+    onError: (proxyReply, { error }) => {
+      logger.error({ err: error, workspaceId, targetUrl }, "Failed to proxy workspace request")
+      if (!proxyReply.sent) {
+        proxyReply.code(502).send({ error: "Workspace instance proxy failed" })
+      }
+    },
+  })
+}
+
+function normalizeInstanceSuffix(pathSuffix: string | undefined) {
+  if (!pathSuffix || pathSuffix === "/") {
+    return "/"
+  }
+  const trimmed = pathSuffix.replace(/^\/+/, "")
+  return trimmed.length === 0 ? "/" : `/${trimmed}`
+}
+
+type WorktreeCacheEntry = {
+  expiresAt: number
+  repoRoot: string
+  worktrees: Array<{ slug: string; directory: string }>
+}
+
+const WORKTREE_CACHE_TTL_MS = 2000
+const worktreeCache = new Map<string, WorktreeCacheEntry>()
+
+async function getCachedWorktrees(params: { workspaceId: string; workspacePath: string; logger: Logger }) {
+  const cached = worktreeCache.get(params.workspaceId)
+  const now = Date.now()
+  if (cached && cached.expiresAt > now) {
+    return cached
+  }
+
+  const { repoRoot } = await resolveRepoRoot(params.workspacePath, params.logger)
+  const worktrees = await listWorktrees({ repoRoot, workspaceFolder: params.workspacePath, logger: params.logger })
+  const entry: WorktreeCacheEntry = {
+    expiresAt: now + WORKTREE_CACHE_TTL_MS,
+    repoRoot,
+    worktrees: worktrees.map((wt) => ({ slug: wt.slug, directory: wt.directory })),
+  }
+  worktreeCache.set(params.workspaceId, entry)
+  return entry
+}
+
+async function resolveWorktreeDirectory(params: {
+  workspaceId: string
+  workspacePath: string
+  worktreeSlug: string
+  logger: Logger
+}): Promise<string | null> {
+  const { worktreeSlug } = params
+  const cached = await getCachedWorktrees({ workspaceId: params.workspaceId, workspacePath: params.workspacePath, logger: params.logger })
+  const match = cached.worktrees.find((wt) => wt.slug === worktreeSlug)
+  if (match) {
+    return match.directory
+  }
+
+  // If the slug is new (e.g., created moments ago), refresh once.
+  worktreeCache.delete(params.workspaceId)
+  const refreshed = await getCachedWorktrees({ workspaceId: params.workspaceId, workspacePath: params.workspacePath, logger: params.logger })
+  return refreshed.worktrees.find((wt) => wt.slug === worktreeSlug)?.directory ?? null
+}
+
+function setupStaticUi(app: FastifyInstance, uiDir: string, authManager: AuthManager) {
+  if (!uiDir) {
+    app.log.warn("UI static directory not provided; API endpoints only")
+    return
+  }
+
+  if (!fs.existsSync(uiDir)) {
+    app.log.warn({ uiDir }, "UI static directory missing; API endpoints only")
+    return
+  }
+
+  app.register(fastifyStatic, {
+    root: uiDir,
+    prefix: "/",
+    decorateReply: false,
+  })
+
+  const indexPath = path.join(uiDir, "index.html")
+
+  app.setNotFoundHandler((request: FastifyRequest, reply: FastifyReply) => {
+    const url = request.raw.url ?? ""
+    if (isApiRequest(url)) {
+      reply.code(404).send({ message: "Not Found" })
+      return
+    }
+
+    const session = authManager.getSessionFromRequest(request)
+    if (!session && wantsHtml(request)) {
+      reply.redirect("/login")
+      return
+    }
+
+    if (fs.existsSync(indexPath)) {
+      reply.type("text/html").send(fs.readFileSync(indexPath, "utf-8"))
+    } else {
+      reply.code(404).send({ message: "UI bundle missing" })
+    }
+  })
+}
+
+function setupDevProxy(app: FastifyInstance, upstreamBase: string, authManager: AuthManager) {
+  app.log.info({ upstreamBase }, "Proxying UI requests to development server")
+  app.setNotFoundHandler((request: FastifyRequest, reply: FastifyReply) => {
+    const url = request.raw.url ?? ""
+    if (isApiRequest(url)) {
+      reply.code(404).send({ message: "Not Found" })
+      return
+    }
+
+    const session = authManager.getSessionFromRequest(request)
+    if (!session && wantsHtml(request)) {
+      reply.redirect("/login")
+      return
+    }
+
+    void proxyToDevServer(request, reply, upstreamBase)
+  })
+}
+
+async function proxyToDevServer(request: FastifyRequest, reply: FastifyReply, upstreamBase: string) {
+  try {
+    const targetUrl = new URL(request.raw.url ?? "/", upstreamBase)
+    const response = await fetch(targetUrl, {
+      method: request.method,
+      headers: buildProxyHeaders(request.headers),
+    })
+
+    response.headers.forEach((value, key) => {
+      reply.header(key, value)
+    })
+
+    reply.code(response.status)
+
+    if (!response.body || request.method === "HEAD") {
+      reply.send()
+      return
+    }
+
+    const buffer = Buffer.from(await response.arrayBuffer())
+    reply.send(buffer)
+  } catch (error) {
+    request.log.error({ err: error }, "Failed to proxy UI request to dev server")
+    if (!reply.sent) {
+      reply.code(502).send("UI dev server is unavailable")
+    }
+  }
+}
+
+function isApiRequest(rawUrl: string | null | undefined) {
+  if (!rawUrl) return false
+  const pathname = rawUrl.split("?")[0] ?? ""
+  return pathname === "/api" || pathname.startsWith("/api/")
+}
+
+function buildProxyHeaders(headers: FastifyRequest["headers"]): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const [key, value] of Object.entries(headers ?? {})) {
+    if (!value || key.toLowerCase() === "host") continue
+    result[key] = Array.isArray(value) ? value.join(",") : value
+  }
+  return result
+}

packages/server/src/server/network-addresses.ts

@@ -0,0 +1,75 @@
+import os from "os"
+import type { NetworkAddress } from "../api-types"
+
+export function resolveNetworkAddresses(args: {
+  host: string
+  protocol: "http" | "https"
+  port: number
+}): NetworkAddress[] {
+  const { host, protocol, port } = args
+  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, remoteUrl: `${protocol}://${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/auth-pages/login.html

@@ -0,0 +1,135 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>CodeNomad Login</title>
+    <style>
+      body {
+        font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial;
+        background: #0b0b0f;
+        color: #fff;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        height: 100vh;
+        margin: 0;
+      }
+      .card {
+        width: 420px;
+        max-width: calc(100vw - 32px);
+        background: #14141c;
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        border-radius: 14px;
+        padding: 24px;
+      }
+      h1 {
+        font-size: 18px;
+        margin: 0 0 12px;
+      }
+      p {
+        margin: 0 0 18px;
+        color: rgba(255, 255, 255, 0.7);
+        font-size: 13px;
+        line-height: 1.4;
+      }
+      label {
+        display: block;
+        font-size: 12px;
+        margin: 10px 0 6px;
+        color: rgba(255, 255, 255, 0.75);
+      }
+      input {
+        width: 100%;
+        box-sizing: border-box;
+        padding: 10px 12px;
+        border-radius: 10px;
+        border: 1px solid rgba(255, 255, 255, 0.12);
+        background: #0f0f16;
+        color: #fff;
+      }
+      button {
+        width: 100%;
+        margin-top: 14px;
+        padding: 10px 12px;
+        border-radius: 10px;
+        border: 0;
+        background: #4c6fff;
+        color: #fff;
+        font-weight: 600;
+        cursor: pointer;
+      }
+      .error {
+        margin-top: 12px;
+        color: #ff6b6b;
+        font-size: 13px;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1>Sign in</h1>
+      <p>This CodeNomad server is protected. Enter your credentials to continue.</p>
+
+      <label for="username">Username</label>
+      <input id="username" autocomplete="username" placeholder="{{DEFAULT_USERNAME}}" value="" />
+
+      <label for="password">Password</label>
+      <input id="password" type="password" autocomplete="current-password" value="" />
+
+      <button id="submit" type="button">Continue</button>
+      <div id="error" class="error" style="display: none"></div>
+    </div>
+
+    <script>
+      const $ = (id) => document.getElementById(id)
+      const errorEl = $("error")
+      const showError = (msg) => {
+        errorEl.textContent = msg
+        errorEl.style.display = "block"
+      }
+      const hideError = () => {
+        errorEl.textContent = ""
+        errorEl.style.display = "none"
+      }
+
+      async function submit() {
+        hideError()
+        const username = $("username").value.trim()
+        const password = $("password").value
+        if (!username || !password) {
+          showError("Username and password are required.")
+          return
+        }
+        try {
+          const res = await fetch("/api/auth/login", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ username, password }),
+            credentials: "include",
+          })
+          if (!res.ok) {
+            let message = ""
+            try {
+              const json = await res.json()
+              message = json && json.error ? String(json.error) : ""
+            } catch {
+              message = ""
+            }
+            showError(message || `Login failed (${res.status})`)
+            return
+          }
+          // Replace history entry so Back doesn't return to /login.
+          window.location.replace("/")
+        } catch (e) {
+          showError(e && e.message ? e.message : String(e))
+        }
+      }
+
+      $("submit").addEventListener("click", submit)
+      $("password").addEventListener("keydown", (e) => {
+        if (e.key === "Enter") submit()
+      })
+    </script>
+  </body>
+</html>

packages/server/src/server/routes/auth-pages/token.html

@@ -0,0 +1,93 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>CodeNomad</title>
+    <style>
+      body {
+        font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial;
+        background: #0b0b0f;
+        color: #fff;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        height: 100vh;
+        margin: 0;
+      }
+      .card {
+        width: 420px;
+        max-width: calc(100vw - 32px);
+        background: #14141c;
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        border-radius: 14px;
+        padding: 24px;
+      }
+      h1 {
+        font-size: 18px;
+        margin: 0 0 12px;
+      }
+      p {
+        margin: 0;
+        color: rgba(255, 255, 255, 0.7);
+        font-size: 13px;
+        line-height: 1.4;
+      }
+      .error {
+        margin-top: 12px;
+        color: #ff6b6b;
+        font-size: 13px;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1>Connecting…</h1>
+      <p>Finalizing local authentication.</p>
+      <div id="error" class="error" style="display: none"></div>
+    </div>
+
+    <script>
+      const token = (location.hash || "").replace(/^#/, "").trim()
+      const errorEl = document.getElementById("error")
+      const showError = (msg) => {
+        errorEl.textContent = msg
+        errorEl.style.display = "block"
+      }
+
+      async function run() {
+        if (!token) {
+          showError("Missing bootstrap token.")
+          return
+        }
+
+        try {
+          const res = await fetch("/api/auth/token", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ token }),
+            credentials: "include",
+          })
+
+          if (!res.ok) {
+            let message = ""
+            try {
+              const json = await res.json()
+              message = json && json.error ? String(json.error) : ""
+            } catch {
+              message = ""
+            }
+            showError(message || `Token exchange failed (${res.status})`)
+            return
+          }
+
+          window.location.replace("/")
+        } catch (e) {
+          showError(e && e.message ? e.message : String(e))
+        }
+      }
+
+      run()
+    </script>
+  </body>
+</html>

packages/server/src/server/routes/auth.ts

@@ -0,0 +1,181 @@
+import type { FastifyInstance } from "fastify"
+import fs from "fs"
+import { z } from "zod"
+import type { AuthManager } from "../../auth/manager"
+import { isLoopbackAddress } from "../../auth/http-auth"
+
+interface RouteDeps {
+  authManager: AuthManager
+}
+
+const LoginSchema = z.object({
+  username: z.string().min(1),
+  password: z.string().min(1),
+})
+
+const TokenSchema = z.object({
+  token: z.string().min(1),
+})
+
+const PasswordSchema = z.object({
+  password: z.string().min(8),
+})
+
+const LOGIN_TEMPLATE_URL = new URL("./auth-pages/login.html", import.meta.url)
+const TOKEN_TEMPLATE_URL = new URL("./auth-pages/token.html", import.meta.url)
+
+let cachedLoginTemplate: string | null = null
+let cachedTokenTemplate: string | null = null
+
+function readTemplate(url: URL, cache: string | null): string {
+  if (cache) return cache
+  const content = fs.readFileSync(url, "utf-8")
+  return content
+}
+
+function getLoginHtml(defaultUsername: string): string {
+  if (!cachedLoginTemplate) {
+    cachedLoginTemplate = readTemplate(LOGIN_TEMPLATE_URL, null)
+  }
+
+  const escapedUsername = escapeHtml(defaultUsername)
+  return cachedLoginTemplate.replace(/\{\{DEFAULT_USERNAME\}\}/g, escapedUsername)
+}
+
+function getTokenHtml(): string {
+  if (!cachedTokenTemplate) {
+    cachedTokenTemplate = readTemplate(TOKEN_TEMPLATE_URL, null)
+  }
+
+  return cachedTokenTemplate
+}
+
+export function registerAuthRoutes(app: FastifyInstance, deps: RouteDeps) {
+  app.get("/login", async (request, reply) => {
+    // If already authenticated, don't show the login page.
+    const session = deps.authManager.getSessionFromRequest(request)
+    if (session) {
+      reply.redirect("/")
+      return
+    }
+
+    // Avoid caching the login page (helps with bfcache/back behavior).
+    reply.header("Cache-Control", "no-store")
+    reply.header("Pragma", "no-cache")
+    reply.header("Expires", "0")
+
+    const status = deps.authManager.getStatus()
+    reply.type("text/html").send(getLoginHtml(status.username))
+  })
+
+  app.get("/auth/token", async (request, reply) => {
+    if (!deps.authManager.isTokenBootstrapEnabled()) {
+      reply.code(404).send({ error: "Not found" })
+      return
+    }
+
+    if (!isLoopbackAddress(request.socket.remoteAddress)) {
+      reply.code(404).send({ error: "Not found" })
+      return
+    }
+
+    // Avoid caching the token bootstrap page.
+    reply.header("Cache-Control", "no-store")
+    reply.header("Pragma", "no-cache")
+    reply.header("Expires", "0")
+
+    reply.type("text/html").send(getTokenHtml())
+  })
+
+  app.get("/api/auth/status", async (request, reply) => {
+    const session = deps.authManager.getSessionFromRequest(request)
+    if (!session) {
+      reply.send({ authenticated: false })
+      return
+    }
+    reply.send({ authenticated: true, ...deps.authManager.getStatus() })
+  })
+
+  app.post("/api/auth/login", async (request, reply) => {
+    const body = LoginSchema.parse(request.body ?? {})
+    const ok = deps.authManager.validateLogin(body.username, body.password)
+    if (!ok) {
+      reply.code(401).send({ error: "Invalid credentials" })
+      return
+    }
+
+    const session = deps.authManager.createSession(body.username)
+    deps.authManager.setSessionCookieWithOptions(reply, session.id, { secure: isSecureRequest(request) })
+    reply.send({ ok: true })
+  })
+
+  app.post("/api/auth/token", async (request, reply) => {
+    if (!deps.authManager.isTokenBootstrapEnabled()) {
+      reply.code(404).send({ error: "Not found" })
+      return
+    }
+
+    if (!isLoopbackAddress(request.socket.remoteAddress)) {
+      reply.code(404).send({ error: "Not found" })
+      return
+    }
+
+    const body = TokenSchema.parse(request.body ?? {})
+    const ok = deps.authManager.consumeBootstrapToken(body.token)
+    if (!ok) {
+      reply.code(401).send({ error: "Invalid token" })
+      return
+    }
+
+    const username = deps.authManager.getStatus().username
+    const session = deps.authManager.createSession(username)
+    deps.authManager.setSessionCookieWithOptions(reply, session.id, { secure: isSecureRequest(request) })
+    reply.send({ ok: true })
+  })
+
+  app.post("/api/auth/logout", async (request, reply) => {
+    deps.authManager.clearSessionCookieWithOptions(reply, { secure: isSecureRequest(request) })
+    reply.send({ ok: true })
+  })
+
+  app.post("/api/auth/password", async (request, reply) => {
+    const session = deps.authManager.getSessionFromRequest(request)
+    if (!session) {
+      reply.code(401).send({ error: "Unauthorized" })
+      return
+    }
+
+    const body = PasswordSchema.parse(request.body ?? {})
+    try {
+      const status = deps.authManager.setPassword(body.password)
+      reply.send({ ok: true, ...status })
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      reply.code(409).type("text/plain").send(message)
+    }
+  })
+}
+
+function isSecureRequest(request: any) {
+  if (request.protocol === "https") {
+    return true
+  }
+  return Boolean(request.raw?.socket && request.raw.socket.encrypted)
+}
+
+function escapeHtml(value: string) {
+  return value.replace(/[&<>"]/g, (char) => {
+    switch (char) {
+      case "&":
+        return "&amp;"
+      case "<":
+        return "&lt;"
+      case ">":
+        return "&gt;"
+      case '"':
+        return "&quot;"
+      default:
+        return char
+    }
+  })
+}

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/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/filesystem.ts

@@ -0,0 +1,54 @@
+import { FastifyInstance } from "fastify"
+import { z } from "zod"
+import { FileSystemBrowser } from "../../filesystem/browser"
+
+interface RouteDeps {
+  fileSystemBrowser: FileSystemBrowser
+}
+
+const FilesystemQuerySchema = z.object({
+  path: z.string().optional(),
+  includeFiles: z.coerce.boolean().optional(),
+})
+
+const FilesystemCreateFolderSchema = z.object({
+  parentPath: z.string().optional(),
+  name: z.string(),
+})
+
+export function registerFilesystemRoutes(app: FastifyInstance, deps: RouteDeps) {
+  app.get("/api/filesystem", async (request, reply) => {
+    const query = FilesystemQuerySchema.parse(request.query ?? {})
+
+    try {
+      return deps.fileSystemBrowser.browse(query.path, {
+        includeFiles: query.includeFiles,
+      })
+    } catch (error) {
+      reply.code(400)
+      return { error: (error as Error).message }
+    }
+  })
+
+  app.post("/api/filesystem/folders", async (request, reply) => {
+    const body = FilesystemCreateFolderSchema.parse(request.body ?? {})
+
+    try {
+      const created = deps.fileSystemBrowser.createFolder(body.parentPath, body.name)
+      reply.code(201)
+      return created
+    } catch (error) {
+      const err = error as NodeJS.ErrnoException
+      if (err?.code === "EEXIST") {
+        reply.code(409).type("text/plain").send("Folder already exists")
+        return
+      }
+      if (err?.code === "EACCES" || err?.code === "EPERM") {
+        reply.code(403).type("text/plain").send("Permission denied")
+        return
+      }
+
+      reply.code(400).type("text/plain").send((error as Error).message)
+    }
+  })
+}

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

@@ -0,0 +1,58 @@
+import { FastifyInstance } from "fastify"
+import { ServerMeta } from "../../api-types"
+import { resolveNetworkAddresses } from "../network-addresses"
+
+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 localPort = resolveLocalPort(meta)
+  const remote = resolveRemote(meta)
+  const addresses = remote && remote.port > 0 ? resolveNetworkAddresses({ host: meta.host, protocol: remote.protocol, port: remote.port }) : []
+
+  return {
+    ...meta,
+    localPort,
+    remotePort: remote?.port,
+    listeningMode: meta.host === "0.0.0.0" || !isLoopbackHost(meta.host) ? "all" : "local",
+    addresses,
+  }
+}
+
+function resolveLocalPort(meta: ServerMeta): number {
+  if (Number.isInteger(meta.localPort) && meta.localPort > 0) {
+    return meta.localPort
+  }
+  try {
+    const parsed = new URL(meta.localUrl)
+    const port = Number(parsed.port)
+    return Number.isInteger(port) && port > 0 ? port : 0
+  } catch {
+    return 0
+  }
+}
+
+function resolveRemote(meta: ServerMeta): { protocol: "http" | "https"; port: number } | null {
+  if (!meta.remoteUrl) {
+    return null
+  }
+  try {
+    const parsed = new URL(meta.remoteUrl)
+    const protocol = parsed.protocol === "https:" ? "https" : "http"
+    const port = Number(parsed.port)
+    return { protocol, port: Number.isInteger(port) && port > 0 ? port : 0 }
+  } catch {
+    return null
+  }
+}
+
+function isLoopbackHost(host: string): boolean {
+  return host === "127.0.0.1" || host === "::1" || host.startsWith("127.")
+}
+
+// NetworkAddress shape is resolved in ../network-addresses