docs: reorganize server and dev release docs

Make server usage easier to discover from the root README, add local install/run instructions, and document additional CLI flags/env vars for UI and logging.

.github/workflows/dev-release.yml

@@ -1,4 +1,4 @@
-name: Dev CI
+name: Develop Pre-Release
 
 on:
   push:
@@ -7,12 +7,35 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: read
+  id-token: write
+  contents: write
+
+concurrency:
+  group: dev-prerelease
+  cancel-in-progress: true
 
 jobs:
-  dev-ci:
-    uses: ./.github/workflows/build-and-upload.yml
+  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:
-      upload: false
-      set_versions: false
+      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

@@ -12,6 +12,11 @@ on:
         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:
@@ -21,6 +26,13 @@ on:
         required: false
         type: string
         default: dev
+      package_name:
+        required: false
+        type: string
+        default: "@neuralnomads/codenomad"
+    secrets:
+      NPM_TOKEN:
+        required: false
 
 permissions:
   contents: read
@@ -51,7 +63,7 @@ jobs:
         run: npm install @rollup/rollup-linux-x64-gnu --no-save
 
       - name: Build server package (includes UI bundling)
-        run: npm run build --workspace @neuralnomads/codenomad
+        run: npm run build --workspace packages/server
 
       - name: Set publish metadata
         shell: bash
@@ -62,13 +74,31 @@ jobs:
           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: |
-          npm publish --workspace @neuralnomads/codenomad --access public --tag ${DIST_TAG} --provenance
+          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.yml

@@ -14,4 +14,5 @@ jobs:
     uses: ./.github/workflows/reusable-release.yml
     with:
       dist_tag: latest
+      npm_package_name: "@neuralnomads/codenomad"
     secrets: inherit

.github/workflows/reusable-release.yml

@@ -13,6 +13,21 @@ on:
         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
@@ -53,11 +68,16 @@ jobs:
         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
-            gh release create "$TAG" --title "$TAG" --generate-notes
+            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:
@@ -71,6 +91,7 @@ jobs:
 
   release-ui:
     needs: prepare-release
+    if: ${{ inputs.release_ui }}
     permissions:
       contents: read
     uses: ./.github/workflows/release-ui.yml
@@ -84,4 +105,5 @@ jobs:
     with:
       version: ${{ needs.prepare-release.outputs.version }}
       dist_tag: ${{ inputs.dist_tag }}
+      package_name: ${{ inputs.npm_package_name }}
     secrets: inherit

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.

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

@@ -44,13 +44,21 @@ Run CodeNomad as a local server and access it via your web browser. Perfect for
 npx @neuralnomads/codenomad --launch
 ```
 
-For dev version
+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@dev --launch
+npx @neuralnomads/codenomad --help
 ```
 
-This command starts the server and opens the web client in your default browser.
+### 🧪 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
 

package.json

@@ -1,8 +1,9 @@
 {
   "name": "codenomad-workspace",
-  "version": "0.9.2",
+  "version": "0.10.3",
   "private": true,
   "description": "CodeNomad monorepo workspace",
+  "license": "MIT",
   "workspaces": {
     "packages": [
       "packages/server",

packages/cloudflare/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@codenomad/ui-host-worker",
   "private": true,
+  "license": "MIT",
   "type": "module",
   "scripts": {
     "build:manifest": "node ./scripts/build-manifest.mjs",

packages/cloudflare/release-config.json

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

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

@@ -1,6 +1,7 @@
 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")
@@ -8,6 +9,32 @@ 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: {
     plugins: [externalizeDepsPlugin()],
@@ -40,7 +67,7 @@ export default defineConfig({
   },
   renderer: {
     root: uiRendererRoot,
-    plugins: [solid()],
+    plugins: [solid(), prepareMonacoPublicAssets()],
     css: {
       postcss: resolve(uiRoot, "postcss.config.js"),
     },

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

@@ -1,6 +1,8 @@
-import { BrowserWindow, dialog, ipcMain, type OpenDialogOptions } from "electron"
+import { BrowserWindow, Notification, dialog, ipcMain, powerSaveBlocker, type OpenDialogOptions } from "electron"
 import type { CliProcessManager, CliStatus } from "./process-manager"
 
+let wakeLockId: number | null = null
+
 interface DialogOpenRequest {
   mode: "directory" | "file"
   title?: string
@@ -62,4 +64,50 @@ export function setupCliIPC(mainWindow: BrowserWindow, cliManager: CliProcessMan
 
     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 }
+    }
+
+    if (wakeLockId !== null) {
+      try {
+        if (powerSaveBlocker.isStarted(wakeLockId)) {
+          powerSaveBlocker.stop(wakeLockId)
+        }
+      } finally {
+        wakeLockId = null
+      }
+    }
+    return { enabled: false }
+  })
+
+  ipcMain.handle(
+    "notifications:show",
+    async (_event, payload: { title?: unknown; body?: unknown }): Promise<{ ok: boolean; reason?: string }> => {
+      if (!Notification.isSupported()) {
+        return { ok: false, reason: "unsupported" }
+      }
+
+      const title = typeof payload?.title === "string" ? payload.title : "CodeNomad"
+      const body = typeof payload?.body === "string" ? payload.body : ""
+      try {
+        const notification = new Notification({ title, body })
+        notification.show()
+        return { ok: true }
+      } catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+      }
+    },
+  )
 }

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

@@ -399,7 +399,11 @@ async function exchangeBootstrapToken(baseUrl: string, token: string): Promise<b
 
 async function startCli() {
   try {
-    const devMode = process.env.NODE_ENV === "development"
+    // 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) {
@@ -473,6 +477,14 @@ 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) {
@@ -505,7 +517,6 @@ app.on("before-quit", async (event) => {
 })
 
 app.on("window-all-closed", () => {
-  if (process.platform !== "darwin") {
-    app.quit()
-  }
+  // 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,10 +1,11 @@
-import { spawn, type ChildProcess } from "child_process"
+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"
 
 const nodeRequire = createRequire(import.meta.url)
@@ -39,6 +40,36 @@ interface CliEntryResolution {
 
 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") }
+  }
+
+  if (isJsonPath(resolved)) {
+    const baseDir = path.dirname(resolved)
+    return { configYamlPath: path.join(baseDir, "config.yaml"), legacyJsonPath: resolved }
+  }
+
+  // Treat as directory.
+  return {
+    configYamlPath: path.join(resolved, "config.yaml"),
+    legacyJsonPath: path.join(resolved, "config.json"),
+  }
+}
+
 function resolveConfigPath(configPath?: string): string {
   const target = configPath && configPath.trim().length > 0 ? configPath : DEFAULT_CONFIG_PATH
   if (target.startsWith("~/")) {
@@ -53,10 +84,19 @@ function resolveHostForMode(mode: ListeningMode): string {
 
 function readListeningModeFromConfig(): ListeningMode {
   try {
-    const configPath = resolveConfigPath(process.env.CLI_CONFIG)
-    if (!existsSync(configPath)) return "local"
-    const content = readFileSync(configPath, "utf-8")
-    const parsed = JSON.parse(content)
+    const { configYamlPath, legacyJsonPath } = resolveConfigPaths(process.env.CLI_CONFIG)
+
+    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 {
+      return "local"
+    }
+
     const mode = parsed?.preferences?.listeningMode
     if (mode === "local" || mode === "all") {
       return mode
@@ -82,6 +122,7 @@ export class CliProcessManager extends EventEmitter {
   private stdoutBuffer = ""
   private stderrBuffer = ""
   private bootstrapToken: string | null = null
+  private requestedStop = false
 
   async start(options: StartOptions): Promise<CliStatus> {
     if (this.child) {
@@ -91,6 +132,7 @@ export class CliProcessManager extends EventEmitter {
     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)
@@ -109,11 +151,13 @@ export class CliProcessManager extends EventEmitter {
       ? 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(" ")}`)
@@ -175,12 +219,89 @@ export class CliProcessManager extends EventEmitter {
       return
     }
 
+    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(() => {
         console.warn(
           `[cli] stop timed out after 30000ms; sending SIGKILL (pid=${child.pid ?? "unknown"})`,
         )
-        child.kill("SIGKILL")
+        sendStopSignal("SIGKILL")
       }, 30000)
 
       child.on("exit", () => {
@@ -191,7 +312,15 @@ export class CliProcessManager extends EventEmitter {
         resolve()
       })
 
-      child.kill("SIGTERM")
+      if (isAlreadyExited()) {
+        clearTimeout(killTimeout)
+        this.child = undefined
+        this.updateStatus({ state: "stopped" })
+        resolve()
+        return
+      }
+
+      sendStopSignal("SIGTERM")
     })
   }
 
@@ -205,7 +334,16 @@ export class CliProcessManager extends EventEmitter {
 
   private handleTimeout() {
     if (this.child) {
-      this.child.kill("SIGKILL")
+      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")
+      }
       this.child = undefined
     }
     this.updateStatus({ state: "error", error: "CLI did not start in time" })
@@ -249,38 +387,27 @@ export class CliProcessManager extends EventEmitter {
       console.info(`[cli][${stream}] ${trimmed}`)
       this.emit("log", { stream, message: trimmed })
 
-      const port = this.extractPort(trimmed)
-      if (port && this.status.state === "starting") {
-        const url = `http://127.0.0.1:${port}`
-        console.info(`[cli] ready on ${url}`)
-        this.updateStatus({ state: "ready", port, url })
+      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 extractPort(line: string): number | null {
-    const readyMatch = line.match(/CodeNomad Server is ready at http:\/\/[^:]+:(\d+)/i)
-    if (readyMatch) {
-      return parseInt(readyMatch[1], 10)
+  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
     }
-
-    if (line.toLowerCase().includes("http server listening")) {
-      const httpMatch = line.match(/:(\d{2,5})(?!.*:\d)/)
-      if (httpMatch) {
-        return parseInt(httpMatch[1], 10)
-      }
-      try {
-        const parsed = JSON.parse(line)
-        if (typeof parsed.port === "number") {
-          return parsed.port
-        }
-      } catch {
-        // not JSON, ignore
-      }
-    }
-
-    return null
+    return match[1] ?? null
   }
 
   private updateStatus(patch: Partial<CliStatus>) {
@@ -289,10 +416,22 @@ export class CliProcessManager extends EventEmitter {
   }
 
   private buildCliArgs(options: StartOptions, host: string): string[] {
-    const args = ["serve", "--host", host, "--port", "0", "--generate-token"]
+    const args = ["serve", "--host", host, "--generate-token"]
 
     if (options.dev) {
-      args.push("--ui-dev-server", "http://localhost:3000", "--log-level", "debug")
+      // 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")
+    }
+
+    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")
     }
 
     return args

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

@@ -12,6 +12,8 @@ const electronAPI = {
   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/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@neuralnomads/codenomad-electron-app",
-  "version": "0.9.2",
+  "version": "0.10.3",
   "description": "CodeNomad - AI coding assistant",
+  "license": "MIT",
   "author": {
     "name": "Neural Nomads",
     "email": "codenomad@neuralnomads.ai"
@@ -35,7 +36,8 @@
   },
   "dependencies": {
     "@neuralnomads/codenomad": "file:../server",
-    "@codenomad/ui": "file:../ui"
+    "@codenomad/ui": "file:../ui",
+    "yaml": "^2.4.2"
   },
   "devDependencies": {
     "7zip-bin": "^5.2.0",

packages/opencode-config/package.json

@@ -2,7 +2,8 @@
   "name": "@codenomad/opencode-config",
   "version": "0.5.0",
   "private": true,
+  "license": "MIT",
   "dependencies": {
-    "@opencode-ai/plugin": "1.1.36"
+    "@opencode-ai/plugin": "1.1.53"
   }
-}
+}

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

@@ -1,3 +1,7 @@
+import http from "http"
+import https from "https"
+import { Readable } from "stream"
+
 export type PluginEvent = {
   type: string
   properties?: Record<string, unknown>
@@ -16,7 +20,8 @@ export function getCodeNomadConfig(): CodeNomadConfig {
 }
 
 export function createCodeNomadRequester(config: CodeNomadConfig) {
-  const baseUrl = config.baseUrl.replace(/\/+$/, "")
+  const rawBaseUrl = (config.baseUrl ?? "").trim()
+  const baseUrl = rawBaseUrl.replace(/\/+$/, "")
   const pluginBase = `${baseUrl}/workspaces/${encodeURIComponent(config.instanceId)}/plugin`
   const authorization = buildInstanceAuthorizationHeader()
 
@@ -42,10 +47,10 @@ export function createCodeNomadRequester(config: CodeNomadConfig) {
     const hasBody = init?.body !== undefined
     const headers = buildHeaders(init?.headers, hasBody)
 
-    return fetch(url, {
-      ...init,
-      headers,
-    })
+    // 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> => {
@@ -87,6 +92,91 @@ export function createCodeNomadRequester(config: CodeNomadConfig) {
   }
 }
 
+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()) {

packages/server/.gitignore

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

packages/server/README.md

@@ -31,6 +31,17 @@ You can run CodeNomad directly without installing it:
 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:
 
@@ -39,20 +50,113 @@ 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 |
 |------|--------------|-------------|
-| `--port <number>` | `CLI_PORT` | HTTP port (default 9898) |
+| `--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,12 +1,12 @@
 {
   "name": "@neuralnomads/codenomad",
-  "version": "0.9.2",
+  "version": "0.10.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@neuralnomads/codenomad",
-      "version": "0.9.2",
+      "version": "0.10.3",
       "dependencies": {
         "@fastify/cors": "^8.5.0",
         "@fastify/reply-from": "^9.8.0",

packages/server/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@neuralnomads/codenomad",
-  "version": "0.9.2",
+  "version": "0.10.3",
   "description": "CodeNomad Server",
+  "license": "MIT",
   "author": {
     "name": "Neural Nomads",
     "email": "codenomad@neuralnomads.ai"
@@ -20,7 +21,7 @@
     "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 tsx src/index.ts",
+    "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": {
@@ -30,12 +31,15 @@
     "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",

packages/server/src/api-types.ts

@@ -50,6 +50,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 {
@@ -204,7 +236,8 @@ export interface NetworkAddress {
   ip: string
   family: "ipv4" | "ipv6"
   scope: "external" | "internal" | "loopback"
-  url: string
+  /** Remote URL using the server's remote protocol/port for this IP. */
+  remoteUrl: string
 }
 
 export interface LatestReleaseInfo {
@@ -230,16 +263,20 @@ export interface SupportMeta {
 }
 
 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 port in use after binding. */
-  port: number
+  /** 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. */
@@ -249,6 +286,8 @@ export interface ServerMeta {
   serverVersion?: string
   ui?: UiMeta
   support?: SupportMeta
+  /** Optional update info (dev channel only). */
+  update?: LatestReleaseInfo | null
 }
 
 export type BackgroundProcessStatus = "running" | "stopped" | "error"

packages/server/src/auth/manager.ts

@@ -15,15 +15,25 @@ export interface AuthManagerInit {
   username: string
   password?: string
   generateToken: boolean
+  dangerouslySkipAuth?: boolean
 }
 
 export class AuthManager {
-  private readonly authStore: AuthStore
+  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" }))
 
@@ -37,6 +47,10 @@ export class AuthManager {
     this.tokenManager = init.generateToken ? new TokenManager(60_000) : null
   }
 
+  isAuthEnabled(): boolean {
+    return this.authEnabled
+  }
+
   getCookieName(): string {
     return this.cookieName
   }
@@ -56,19 +70,31 @@ export class AuthManager {
   }
 
   validateLogin(username: string, password: string): boolean {
-    return this.authStore.validateCredentials(username, password)
+    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() {
-    return this.authStore.getStatus()
+    if (!this.authEnabled) {
+      return { username: this.init.username, passwordUserProvided: false }
+    }
+    return this.requireAuthStore().getStatus()
   }
 
   setPassword(password: string) {
-    return this.authStore.setPassword({ password, markUserProvided: true })
+    if (!this.authEnabled) {
+      throw new Error("Internal authentication is disabled")
+    }
+    return this.requireAuthStore().setPassword({ password, markUserProvided: true })
   }
 
   isLoopbackRequest(request: FastifyRequest): boolean {
@@ -76,6 +102,12 @@ export class AuthManager {
   }
 
   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)
@@ -87,9 +119,24 @@ export class AuthManager {
     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) {
@@ -104,8 +151,11 @@ function resolvePath(filePath: string) {
   return path.resolve(filePath)
 }
 
-function buildSessionCookie(name: string, value: string, options?: { maxAgeSeconds?: number }) {
+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))}`)
   }

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

@@ -8,10 +8,12 @@ const ModelPreferenceSchema = z.object({
 const AgentModelSelectionSchema = z.record(z.string(), ModelPreferenceSchema)
 const AgentModelSelectionsSchema = z.record(z.string(), AgentModelSelectionSchema)
 
-const PreferencesSchema = z.object({
+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({}),
@@ -24,7 +26,15 @@ const PreferencesSchema = z.object({
   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(),
@@ -38,14 +48,35 @@ const OpenCodeBinarySchema = z.object({
   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 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,
@@ -55,7 +86,11 @@ export {
   RecentFolderSchema,
   OpenCodeBinarySchema,
   ConfigFileSchema,
+  ConfigYamlSchema,
+  StateFileSchema,
   DEFAULT_CONFIG,
+  DEFAULT_CONFIG_YAML,
+  DEFAULT_STATE,
 }
 
 export type ModelPreference = z.infer<typeof ModelPreferenceSchema>
@@ -65,3 +100,5 @@ 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/config/store.ts

@@ -1,15 +1,27 @@
 import fs from "fs"
 import path from "path"
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml"
 import { EventBus } from "../events/bus"
 import { Logger } from "../logger"
-import { ConfigFile, ConfigFileSchema, DEFAULT_CONFIG } from "./schema"
+import {
+  ConfigFile,
+  ConfigFileSchema,
+  ConfigYamlSchema,
+  DEFAULT_CONFIG,
+  DEFAULT_CONFIG_YAML,
+  DEFAULT_STATE,
+  StateFile,
+  StateFileSchema,
+} from "./schema"
+import type { ConfigLocation } from "./location"
 
 export class ConfigStore {
   private cache: ConfigFile = DEFAULT_CONFIG
+  private state: StateFile = DEFAULT_STATE
   private loaded = false
 
   constructor(
-    private readonly configPath: string,
+    private readonly location: ConfigLocation,
     private readonly eventBus: EventBus | undefined,
     private readonly logger: Logger,
   ) {}
@@ -20,19 +32,37 @@ export class ConfigStore {
     }
 
     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")
+      const configYamlPath = this.location.configYamlPath
+      const stateYamlPath = this.location.stateYamlPath
+      const legacyJsonPath = this.location.legacyJsonPath
+
+      if (fs.existsSync(configYamlPath)) {
+        const configDoc = this.readYamlFile(configYamlPath, DEFAULT_CONFIG_YAML, ConfigYamlSchema, "config")
+        const stateDoc = fs.existsSync(stateYamlPath)
+          ? this.readYamlFile(stateYamlPath, DEFAULT_STATE, StateFileSchema, "state")
+          : DEFAULT_STATE
+
+        this.state = stateDoc
+        this.cache = this.mergeDocs(configDoc, stateDoc)
+        this.logger.debug({ configYamlPath, stateYamlPath }, "Loaded existing YAML config/state")
+      } else if (fs.existsSync(legacyJsonPath)) {
+        const migrated = this.migrateFromLegacyJson(legacyJsonPath)
+        this.state = migrated.state
+        this.cache = migrated.config
       } else {
-        this.cache = DEFAULT_CONFIG
-        this.logger.debug({ resolved }, "No config file found, using defaults")
+        // Fresh install: write defaults.
+        this.state = DEFAULT_STATE
+        this.cache = this.mergeDocs(DEFAULT_CONFIG_YAML, DEFAULT_STATE)
+        this.persist()
+        this.logger.debug(
+          { configYamlPath, stateYamlPath },
+          "No config files found, created default YAML config/state",
+        )
       }
     } catch (error) {
-      this.logger.warn({ err: error }, "Failed to load config, using defaults")
-      this.cache = DEFAULT_CONFIG
+      this.logger.warn({ err: error }, "Failed to load config/state, using defaults")
+      this.state = DEFAULT_STATE
+      this.cache = this.mergeDocs(DEFAULT_CONFIG_YAML, DEFAULT_STATE)
     }
 
     this.loaded = true
@@ -48,9 +78,30 @@ export class ConfigStore {
     this.commit(validated)
   }
 
+  /**
+   * Apply a merge-patch update to the current config.
+   * - Missing keys are preserved.
+   * - Object values are merged recursively.
+   * - Explicit `null` deletes keys.
+   * - Arrays are replaced.
+   */
+  mergePatch(patch: unknown) {
+    if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+      throw new Error("Config patch must be a JSON object")
+    }
+    const current = this.get()
+    const next = applyMergePatch(current as any, patch as any)
+    const validated = ConfigFileSchema.parse(next)
+    this.commit(validated)
+  }
+
   private commit(next: ConfigFile) {
     this.cache = next
     this.loaded = true
+    this.state = {
+      ...this.state,
+      recentFolders: next.recentFolders,
+    }
     this.persist()
     const published = Boolean(this.eventBus)
     this.eventBus?.publish({ type: "config.appChanged", config: this.cache })
@@ -60,19 +111,134 @@ export class ConfigStore {
 
   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")
+      const configYamlPath = this.location.configYamlPath
+      const stateYamlPath = this.location.stateYamlPath
+
+      fs.mkdirSync(this.location.baseDir, { recursive: true })
+      fs.mkdirSync(path.dirname(configYamlPath), { recursive: true })
+
+      const configYaml = stringifyYaml(stripRecentFolders(this.cache) as any)
+      const stateYaml = stringifyYaml(this.state as any)
+
+      fs.writeFileSync(configYamlPath, ensureTrailingNewline(configYaml), "utf-8")
+      fs.writeFileSync(stateYamlPath, ensureTrailingNewline(stateYaml), "utf-8")
+
+      this.logger.debug({ configYamlPath, stateYamlPath }, "Persisted YAML config/state")
     } 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))
+  private mergeDocs(configDoc: unknown, stateDoc: StateFile): ConfigFile {
+    const merged = {
+      ...(configDoc as any),
+      // State wins for recent folders.
+      recentFolders: stateDoc.recentFolders ?? [],
     }
-    return path.resolve(filePath)
+
+    return ConfigFileSchema.parse(merged)
+  }
+
+  private readYamlFile<T>(
+    filePath: string,
+    fallback: T,
+    schema: { parse: (value: unknown) => T },
+    label: string,
+  ): T {
+    try {
+      const content = fs.readFileSync(filePath, "utf-8")
+      const parsed = parseYaml(content)
+      return schema.parse(parsed ?? {})
+    } catch (error) {
+      this.logger.warn({ err: error, filePath, label }, "Failed to read YAML file, using defaults")
+      return fallback
+    }
+  }
+
+  private migrateFromLegacyJson(legacyJsonPath: string): { config: ConfigFile; state: StateFile } {
+    const configYamlPath = this.location.configYamlPath
+    const stateYamlPath = this.location.stateYamlPath
+
+    const content = fs.readFileSync(legacyJsonPath, "utf-8")
+    const parsed = JSON.parse(content)
+    const legacy = ConfigFileSchema.parse(parsed)
+
+    const state: StateFile = StateFileSchema.parse({
+      ...DEFAULT_STATE,
+      recentFolders: legacy.recentFolders ?? [],
+    })
+
+    const merged = this.mergeDocs(stripRecentFolders(legacy), state)
+
+    // Persist YAML docs first, then move legacy aside.
+    try {
+      fs.mkdirSync(this.location.baseDir, { recursive: true })
+      fs.writeFileSync(configYamlPath, ensureTrailingNewline(stringifyYaml(stripRecentFolders(merged) as any)), "utf-8")
+      fs.writeFileSync(stateYamlPath, ensureTrailingNewline(stringifyYaml(state as any)), "utf-8")
+      this.logger.info({ legacyJsonPath, configYamlPath, stateYamlPath }, "Migrated config.json -> YAML")
+    } catch (error) {
+      this.logger.warn({ err: error }, "Failed to persist migrated YAML config/state")
+    }
+
+    try {
+      const bakPath = pickBackupPath(legacyJsonPath)
+      fs.renameSync(legacyJsonPath, bakPath)
+      this.logger.info({ legacyJsonPath, bakPath }, "Moved legacy config.json to backup")
+    } catch (error) {
+      this.logger.warn({ err: error, legacyJsonPath }, "Failed to rename legacy config.json to backup")
+    }
+
+    return { config: merged, state }
   }
 }
+
+function ensureTrailingNewline(content: string): string {
+  if (!content) return "\n"
+  return content.endsWith("\n") ? content : `${content}\n`
+}
+
+function stripRecentFolders(config: ConfigFile): Omit<ConfigFile, "recentFolders"> & Record<string, unknown> {
+  const clone: Record<string, unknown> = { ...(config as any) }
+  delete clone.recentFolders
+  return clone as any
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object") return false
+  if (Array.isArray(value)) return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+function applyMergePatch(current: any, patch: any): any {
+  // RFC 7396-ish merge patch with explicit null deletes.
+  if (!isPlainObject(patch)) {
+    return patch
+  }
+
+  const base = isPlainObject(current) ? { ...current } : {}
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) {
+      delete base[key]
+      continue
+    }
+
+    if (isPlainObject(value) && isPlainObject(base[key])) {
+      base[key] = applyMergePatch(base[key], value)
+      continue
+    }
+
+    // Arrays and scalars replace.
+    base[key] = value
+  }
+  return base
+}
+
+function pickBackupPath(legacyJsonPath: string): string {
+  const base = legacyJsonPath.endsWith(".json") ? legacyJsonPath.slice(0, -".json".length) : legacyJsonPath
+  const preferred = `${base}.json.bak`
+  if (!fs.existsSync(preferred)) {
+    return preferred
+  }
+  return `${base}.json.bak.${Date.now()}`
+}

packages/server/src/filesystem/browser.ts

@@ -222,20 +222,18 @@ export class FileSystemBrowser {
     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/index.ts

@@ -9,6 +9,7 @@ import { createRequire } from "module"
 import { createHttpServer } from "./server/http-server"
 import { WorkspaceManager } from "./workspaces/manager"
 import { ConfigStore } from "./config/store"
+import { resolveConfigLocation } from "./config/location"
 import { BinaryRegistry } from "./config/binaries"
 import { FileSystemBrowser } from "./filesystem/browser"
 import { EventBus } from "./events/bus"
@@ -19,6 +20,9 @@ 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)
 
@@ -28,8 +32,15 @@ const __dirname = path.dirname(__filename)
 const DEFAULT_UI_STATIC_DIR = path.resolve(__dirname, "../public")
 
 interface CliOptions {
-  port: number
   host: string
+  https: boolean
+  http: boolean
+  httpsPort: number
+  httpPort: number
+  tlsKeyPath?: string
+  tlsCertPath?: string
+  tlsCaPath?: string
+  tlsSANs?: string
   rootDir: string
   configPath: string
   unrestrictedRoot: boolean
@@ -44,11 +55,13 @@ interface CliOptions {
   authUsername: string
   authPassword?: string
   generateToken: boolean
+  dangerouslySkipAuth: boolean
 }
 
-const DEFAULT_PORT = 9898
 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()
@@ -56,7 +69,14 @@ function parseCliOptions(argv: string[]): CliOptions {
     .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("--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()),
     )
@@ -84,11 +104,26 @@ function parseCliOptions(argv: string[]): CliOptions {
         .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
-    port: number
+    https?: string
+    http?: string
+    httpsPort: number
+    httpPort: number
+    tlsKey?: string
+    tlsCert?: string
+    tlsCa?: string
+    tlsSANs?: string
     workspaceRoot?: string
     root?: string
     unrestrictedRoot?: boolean
@@ -104,8 +139,14 @@ function parseCliOptions(argv: string[]): CliOptions {
     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)
@@ -113,9 +154,23 @@ function parseCliOptions(argv: string[]): CliOptions {
   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 {
-    port: parsed.port,
     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),
@@ -130,6 +185,7 @@ function parseCliOptions(argv: string[]): CliOptions {
     authUsername: parsed.username,
     authPassword: parsed.password,
     generateToken: Boolean(parsed.generateToken),
+    dangerouslySkipAuth: Boolean(parsed.dangerouslySkipAuth),
   }
 }
 
@@ -174,16 +230,31 @@ async function main() {
 
   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 = {
-    httpBaseUrl: `http://${options.host}:${options.port}`,
+    localUrl: "http://localhost:0",
+    remoteUrl: undefined,
     eventsUrl: `/api/events`,
     host: options.host,
     listeningMode: isLoopbackHost(options.host) ? "local" : "all",
-    port: options.port,
+    localPort: 0,
+    remotePort: undefined,
     hostLabel: options.host,
     workspaceRoot: options.rootDir,
     addresses: [],
@@ -191,22 +262,45 @@ async function main() {
 
   const authManager = new AuthManager(
     {
-      configPath: options.configPath,
+      configPath: configLocation.configYamlPath,
       username: options.authUsername,
       password: options.authPassword,
       generateToken: options.generateToken,
+      dangerouslySkipAuth: options.dangerouslySkipAuth,
     },
     logger.child({ component: "auth" }),
   )
 
-  if (options.generateToken) {
+  if (options.generateToken && !options.dangerouslySkipAuth) {
     const token = authManager.issueBootstrapToken()
     if (token) {
       console.log(`${BOOTSTRAP_TOKEN_STDOUT_PREFIX}${token}`)
     }
   }
 
-  const configStore = new ConfigStore(options.configPath, eventBus, configLogger)
+  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 configStore = new ConfigStore(configLocation, eventBus, configLogger)
+
+  // Eagerly load config at boot so migrations run immediately
+  // (instead of waiting for the first /api/config request).
+  try {
+    configStore.get()
+  } catch (error) {
+    configLogger.warn({ err: error }, "Failed to load config at boot; continuing with defaults")
+  }
+
   const binaryRegistry = new BinaryRegistry(configStore, eventBus, configLogger)
   const workspaceManager = new WorkspaceManager({
     rootDir: options.rootDir,
@@ -214,10 +308,11 @@ async function main() {
     binaryRegistry,
     eventBus,
     logger: workspaceLogger,
-    getServerBaseUrl: () => serverMeta.httpBaseUrl,
+    getServerBaseUrl: () => serverMeta.localUrl,
+    nodeExtraCaCertsPath,
   })
   const fileSystemBrowser = new FileSystemBrowser({ rootDir: options.rootDir, unrestricted: options.unrestrictedRoot })
-  const instanceStore = new InstanceStore()
+  const instanceStore = new InstanceStore(configLocation.instancesDir)
   const instanceEventBridge = new InstanceEventBridge({
     workspaceManager,
     eventBus,
@@ -254,28 +349,140 @@ async function main() {
     minServerVersion: uiResolution.minServerVersion,
   }
 
-  const server = createHttpServer({
-    host: options.host,
-    port: options.port,
-    workspaceManager,
-    configStore,
-    binaryRegistry,
-    fileSystemBrowser,
-    eventBus,
-    serverMeta,
-    instanceStore,
-    authManager,
-    uiStaticDir: uiResolution.uiStaticDir ?? DEFAULT_UI_STATIC_DIR,
-    uiDevServerUrl: uiResolution.uiDevServerUrl,
-    logger,
-  })
+  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
 
-  const startInfo = await server.start()
-  logger.info({ port: startInfo.port, host: options.host }, "HTTP server listening")
-  console.log(`CodeNomad Server is ready at ${startInfo.url}`)
+  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,
+        configStore,
+        binaryRegistry,
+        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,
+        configStore,
+        binaryRegistry,
+        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(startInfo.url, logger.child({ component: "launcher" }))
+    await launchInBrowser(serverMeta.localUrl, logger.child({ component: "launcher" }))
   }
 
   let shuttingDown = false
@@ -305,8 +512,8 @@ async function main() {
 
     const shutdownHttp = (async () => {
       try {
-        await server.stop()
-        logger.info("HTTP server stopped")
+        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")
       }
@@ -316,6 +523,8 @@ async function main() {
 
     // no-op: remote UI manifest replaces GitHub release monitor
 
+    devReleaseMonitor?.stop()
+
     logger.info("Exiting process")
     process.exit(0)
   }

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

@@ -52,6 +52,12 @@ export function startReleaseMonitor(options: ReleaseMonitorOptions): ReleaseMoni
   }
 }
 
+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: {
@@ -92,7 +98,7 @@ async function fetchLatestRelease(options: ReleaseMonitorOptions): Promise<Lates
   }
 }
 
-function stripTagPrefix(tag: string | undefined): string | null {
+export function stripTagPrefix(tag: string | undefined): string | null {
   if (!tag) return null
   const trimmed = tag.trim()
   if (!trimmed) return null
@@ -101,7 +107,9 @@ function stripTagPrefix(tag: string | undefined): string | null {
 
 function parseVersion(value: string): NormalizedVersion {
   const normalized = stripTagPrefix(value) ?? "0.0.0"
-  const [core, prerelease = null] = normalized.split("-", 2)
+  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

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

@@ -7,6 +7,7 @@ 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 { ConfigStore } from "../config/store"
 import { BinaryRegistry } from "../config/binaries"
@@ -20,6 +21,7 @@ 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"
@@ -28,8 +30,12 @@ import { registerAuthRoutes } from "./routes/auth"
 import { sendUnauthorized, wantsHtml } from "../auth/http-auth"
 
 interface HttpServerDeps {
-  host: string
-  port: number
+  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
   configStore: ConfigStore
   binaryRegistry: BinaryRegistry
@@ -49,10 +55,15 @@ interface HttpServerStartResult {
   displayHost: string
 }
 
-const DEFAULT_HTTP_PORT = 9898
-
 export function createHttpServer(deps: HttpServerDeps) {
-  const app = Fastify({ logger: false })
+  // 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" })
@@ -95,6 +106,27 @@ export function createHttpServer(deps: HttpServerDeps) {
   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) {
@@ -102,14 +134,8 @@ export function createHttpServer(deps: HttpServerDeps) {
         return
       }
 
-      let selfOrigin: string | null = null
-      try {
-        selfOrigin = new URL(deps.serverMeta.httpBaseUrl).origin
-      } catch {
-        selfOrigin = null
-      }
-
-      if (selfOrigin && origin === selfOrigin) {
+      const selfOrigins = getSelfOrigins()
+      if (selfOrigins.has(origin)) {
         cb(null, true)
         return
       }
@@ -120,7 +146,7 @@ export function createHttpServer(deps: HttpServerDeps) {
        }
 
        // When we bind to a non-loopback host (e.g., 0.0.0.0 or LAN IP), allow cross-origin UI access.
-       if (deps.host === "0.0.0.0" || !isLoopbackHost(deps.host)) {
+       if (deps.bindHost === "0.0.0.0" || !isLoopbackHost(deps.bindHost)) {
          cb(null, true)
          return
        }
@@ -222,6 +248,7 @@ export function createHttpServer(deps: HttpServerDeps) {
   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,
@@ -242,12 +269,12 @@ export function createHttpServer(deps: HttpServerDeps) {
     instance: app,
     start: async (): Promise<HttpServerStartResult> => {
       const attemptListen = async (requestedPort: number) => {
-        const addressInfo = await app.listen({ port: requestedPort, host: deps.host })
+        const addressInfo = await app.listen({ port: requestedPort, host: deps.bindHost })
         return { addressInfo, requestedPort }
       }
 
-      const autoPortRequested = deps.port === 0
-      const primaryPort = autoPortRequested ? DEFAULT_HTTP_PORT : deps.port
+      const autoPortRequested = deps.bindPort === 0
+      const primaryPort = autoPortRequested ? deps.defaultPort : deps.bindPort
 
       const shouldRetryWithEphemeral = (error: unknown) => {
         if (!autoPortRequested) return false
@@ -283,15 +310,10 @@ export function createHttpServer(deps: HttpServerDeps) {
         }
       }
 
-      const displayHost = deps.host === "127.0.0.1" ? "localhost" : deps.host
-      const serverUrl = `http://${displayHost}:${actualPort}`
+      const displayHost = deps.bindHost === "127.0.0.1" ? "localhost" : deps.bindHost
+      const serverUrl = `${deps.protocol}://${displayHost}:${actualPort}`
 
-      deps.serverMeta.httpBaseUrl = serverUrl
-      deps.serverMeta.host = deps.host
-      deps.serverMeta.port = actualPort
-      deps.serverMeta.listeningMode = deps.host === "0.0.0.0" || !isLoopbackHost(deps.host) ? "all" : "local"
-      deps.logger.info({ port: actualPort, host: deps.host }, "HTTP server listening")
-      console.log(`CodeNomad Server is ready at ${serverUrl}`)
+      deps.logger.info({ port: actualPort, host: deps.bindHost, protocol: deps.protocol }, "HTTP server listening")
 
       return { port: actualPort, url: serverUrl, displayHost }
     },
@@ -312,31 +334,36 @@ function registerInstanceProxyRoutes(app: FastifyInstance, deps: InstanceProxyDe
     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 } }>,
+    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/instance", proxyBaseHandler)
-    instance.all("/workspaces/:id/instance/*", proxyWildcardHandler)
+    instance.all("/workspaces/:id/worktrees/:slug/instance", proxyBaseHandler)
+    instance.all("/workspaces/:id/worktrees/:slug/instance/*", proxyWildcardHandler)
   })
 }
 
@@ -347,12 +374,75 @@ async function proxyWorkspaceRequest(args: {
   reply: FastifyReply
   workspaceManager: WorkspaceManager
   logger: Logger
+  worktreeSlug: string
   pathSuffix?: string
 }) {
-  const { request, reply, workspaceManager, logger } = args
+  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
@@ -364,6 +454,23 @@ async function proxyWorkspaceRequest(args: {
     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) : ""
@@ -380,6 +487,43 @@ async function proxyWorkspaceRequest(args: {
       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 }) => {
@@ -399,6 +543,52 @@ function normalizeInstanceSuffix(pathSuffix: string | undefined) {
   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")

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

@@ -88,7 +88,7 @@ export function registerAuthRoutes(app: FastifyInstance, deps: RouteDeps) {
     }
 
     const session = deps.authManager.createSession(body.username)
-    deps.authManager.setSessionCookie(reply, session.id)
+    deps.authManager.setSessionCookieWithOptions(reply, session.id, { secure: isSecureRequest(request) })
     reply.send({ ok: true })
   })
 
@@ -112,12 +112,12 @@ export function registerAuthRoutes(app: FastifyInstance, deps: RouteDeps) {
 
     const username = deps.authManager.getStatus().username
     const session = deps.authManager.createSession(username)
-    deps.authManager.setSessionCookie(reply, session.id)
+    deps.authManager.setSessionCookieWithOptions(reply, session.id, { secure: isSecureRequest(request) })
     reply.send({ ok: true })
   })
 
-  app.post("/api/auth/logout", async (_request, reply) => {
-    deps.authManager.clearSessionCookie(reply)
+  app.post("/api/auth/logout", async (request, reply) => {
+    deps.authManager.clearSessionCookieWithOptions(reply, { secure: isSecureRequest(request) })
     reply.send({ ok: true })
   })
 
@@ -139,6 +139,13 @@ export function registerAuthRoutes(app: FastifyInstance, deps: RouteDeps) {
   })
 }
 
+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) {

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

@@ -2,7 +2,6 @@ import { FastifyInstance } from "fastify"
 import { z } from "zod"
 import { ConfigStore } from "../../config/store"
 import { BinaryRegistry } from "../../config/binaries"
-import { ConfigFileSchema } from "../../config/schema"
 
 interface RouteDeps {
   configStore: ConfigStore
@@ -27,10 +26,25 @@ const BinaryValidateSchema = z.object({
 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.replace(body)
-    return deps.configStore.get()
+  app.put("/api/config/app", async (request, reply) => {
+    // Backwards compatible: treat PUT as a merge-patch update.
+    try {
+      deps.configStore.mergePatch(request.body ?? {})
+      return deps.configStore.get()
+    } catch (error) {
+      reply.code(400)
+      return { error: error instanceof Error ? error.message : "Invalid config patch" }
+    }
+  })
+
+  app.patch("/api/config/app", async (request, reply) => {
+    try {
+      deps.configStore.mergePatch(request.body ?? {})
+      return deps.configStore.get()
+    } catch (error) {
+      reply.code(400)
+      return { error: error instanceof Error ? error.message : "Invalid config patch" }
+    }
   })
 
   app.get("/api/config/binaries", async () => {

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

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

packages/server/src/server/routes/worktrees.ts

@@ -0,0 +1,195 @@
+import type { FastifyInstance, FastifyReply } from "fastify"
+import { z } from "zod"
+import { WorkspaceManager } from "../../workspaces/manager"
+import {
+  resolveRepoRoot,
+  listWorktrees,
+  isValidWorktreeSlug,
+  createManagedWorktree,
+  removeWorktree,
+} from "../../workspaces/git-worktrees"
+import type { WorktreeListResponse, WorktreeMap } from "../../api-types"
+import { ensureCodenomadGitExclude, readWorktreeMap, writeWorktreeMap } from "../../workspaces/worktree-map"
+
+interface RouteDeps {
+  workspaceManager: WorkspaceManager
+}
+
+const WorktreeMapSchema = z.object({
+  version: z.literal(1),
+  defaultWorktreeSlug: z.string().min(1).default("root"),
+  parentSessionWorktreeSlug: z.record(z.string(), z.string()).default({}),
+})
+
+const WorktreeCreateSchema = z.object({
+  slug: z.string().trim().min(1),
+  branch: z.string().trim().min(1).optional(),
+})
+
+export function registerWorktreeRoutes(app: FastifyInstance, deps: RouteDeps) {
+  app.get<{ Params: { id: string } }>("/api/workspaces/:id/worktrees", async (request, reply) => {
+    const workspace = deps.workspaceManager.get(request.params.id)
+    if (!workspace) {
+      reply.code(404)
+      return { error: "Workspace not found" }
+    }
+
+    const { repoRoot, isGitRepo } = await resolveRepoRoot(workspace.path, request.log)
+    const worktrees = await listWorktrees({ repoRoot, workspaceFolder: workspace.path, logger: request.log })
+    const response: WorktreeListResponse = { worktrees, isGitRepo }
+    return response
+  })
+
+  app.post<{ Params: { id: string } }>("/api/workspaces/:id/worktrees", async (request, reply) => {
+    const workspace = deps.workspaceManager.get(request.params.id)
+    if (!workspace) {
+      reply.code(404)
+      return { error: "Workspace not found" }
+    }
+
+    try {
+      const body = WorktreeCreateSchema.parse(request.body ?? {})
+      const slug = body.slug
+      if (!isValidWorktreeSlug(slug) || slug === "root") {
+        reply.code(400)
+        return { error: "Invalid worktree slug" }
+      }
+      if (body.branch) {
+        if (!isValidWorktreeSlug(body.branch) || body.branch === "root") {
+          reply.code(400)
+          return { error: "Invalid worktree branch" }
+        }
+        if (body.branch !== slug) {
+          reply.code(400)
+          return { error: "Branch must match slug" }
+        }
+      }
+
+      const { repoRoot, isGitRepo } = await resolveRepoRoot(workspace.path, request.log)
+      if (!isGitRepo) {
+        reply.code(400)
+        return { error: "Workspace is not a Git repository" }
+      }
+
+      await ensureCodenomadGitExclude(workspace.path, request.log).catch(() => undefined)
+
+      const created = await createManagedWorktree({
+        repoRoot,
+        workspaceFolder: workspace.path,
+        slug,
+        logger: request.log,
+      })
+
+      reply.code(201)
+      return created
+    } catch (error) {
+      return handleError(error, reply)
+    }
+  })
+
+  app.delete<{ Params: { id: string; slug: string }; Querystring: { force?: string } }>(
+    "/api/workspaces/:id/worktrees/:slug",
+    async (request, reply) => {
+    const workspace = deps.workspaceManager.get(request.params.id)
+    if (!workspace) {
+      reply.code(404)
+      return { error: "Workspace not found" }
+    }
+
+    const slug = (request.params.slug ?? "").trim()
+    if (!isValidWorktreeSlug(slug) || slug === "root") {
+      reply.code(400)
+      return { error: "Invalid worktree slug" }
+    }
+
+    const { repoRoot, isGitRepo } = await resolveRepoRoot(workspace.path, request.log)
+    if (!isGitRepo) {
+      reply.code(400)
+      return { error: "Workspace is not a Git repository" }
+    }
+
+    const force = (request.query?.force ?? "").toString().toLowerCase() === "true"
+
+    try {
+      const worktrees = await listWorktrees({ repoRoot, workspaceFolder: workspace.path, logger: request.log })
+      const match = worktrees.find((wt) => wt.slug === slug)
+      if (!match || match.kind === "root") {
+        reply.code(404)
+        return { error: "Worktree not found" }
+      }
+
+      await removeWorktree({ workspaceFolder: workspace.path, directory: match.directory, force, logger: request.log })
+
+      // Best-effort: prune any mappings that point at the deleted worktree.
+      const current = await readWorktreeMap(workspace.path, request.log)
+      let changed = false
+      const nextMapping: Record<string, string> = { ...(current.parentSessionWorktreeSlug ?? {}) }
+      for (const [sessionId, mapped] of Object.entries(nextMapping)) {
+        if (mapped === slug) {
+          delete nextMapping[sessionId]
+          changed = true
+        }
+      }
+      const nextDefault = current.defaultWorktreeSlug === slug ? "root" : current.defaultWorktreeSlug
+      if (nextDefault !== current.defaultWorktreeSlug) {
+        changed = true
+      }
+      if (changed) {
+        await writeWorktreeMap(
+          workspace.path,
+          {
+            version: 1,
+            defaultWorktreeSlug: nextDefault,
+            parentSessionWorktreeSlug: nextMapping,
+          },
+          request.log,
+        )
+      }
+
+      reply.code(204)
+    } catch (error) {
+      return handleError(error, reply)
+    }
+  },
+  )
+
+  app.get<{ Params: { id: string } }>("/api/workspaces/:id/worktrees/map", async (request, reply) => {
+    const workspace = deps.workspaceManager.get(request.params.id)
+    if (!workspace) {
+      reply.code(404)
+      return { error: "Workspace not found" }
+    }
+    return await readWorktreeMap(workspace.path, request.log)
+  })
+
+  app.put<{ Params: { id: string } }>("/api/workspaces/:id/worktrees/map", async (request, reply) => {
+    const workspace = deps.workspaceManager.get(request.params.id)
+    if (!workspace) {
+      reply.code(404)
+      return { error: "Workspace not found" }
+    }
+
+    try {
+      const parsed = WorktreeMapSchema.parse(request.body ?? {}) as WorktreeMap
+      if (!isValidWorktreeSlug(parsed.defaultWorktreeSlug)) {
+        reply.code(400)
+        return { error: "Invalid defaultWorktreeSlug" }
+      }
+      for (const slug of Object.values(parsed.parentSessionWorktreeSlug ?? {})) {
+        if (!isValidWorktreeSlug(slug)) {
+          reply.code(400)
+          return { error: "Invalid worktree slug in mapping" }
+        }
+      }
+      await writeWorktreeMap(workspace.path, parsed, request.log)
+      reply.code(204)
+    } catch (error) {
+      return handleError(error, reply)
+    }
+  })
+}
+
+function handleError(error: unknown, reply: FastifyReply) {
+  reply.code(400)
+  return { error: error instanceof Error ? error.message : "Unable to fulfill request" }
+}

packages/server/src/server/tls.ts

@@ -0,0 +1,283 @@
+import crypto from "crypto"
+import fs from "fs"
+import path from "path"
+import { createRequire } from "module"
+import type { Logger } from "../logger"
+
+const require = createRequire(import.meta.url)
+
+type Forge = typeof import("node-forge")
+
+function loadForge(): Forge {
+  // node-forge is CJS in many installs; require keeps this compatible with our ESM output.
+  return require("node-forge") as Forge
+}
+
+export interface ResolvedHttpsOptions {
+  httpsOptions: { key: string | Buffer; cert: string | Buffer; ca?: string | Buffer }
+  /** Path to CA certificate suitable for NODE_EXTRA_CA_CERTS. */
+  caCertPath?: string
+  mode: "provided" | "generated"
+}
+
+export interface ResolveHttpsOptionsArgs {
+  enabled: boolean
+  configDir: string
+  host: string
+  tlsKeyPath?: string
+  tlsCertPath?: string
+  tlsCaPath?: string
+  tlsSANs?: string
+  logger: Logger
+}
+
+const LEAF_VALIDITY_DAYS = 30
+const ROTATE_IF_EXPIRES_WITHIN_DAYS = 3
+
+const CA_VALIDITY_DAYS = 365
+
+export function resolveHttpsOptions(args: ResolveHttpsOptionsArgs): ResolvedHttpsOptions | null {
+  if (!args.enabled) {
+    return null
+  }
+
+  const hasProvided = Boolean(args.tlsKeyPath && args.tlsCertPath)
+  if (hasProvided) {
+    const key = fs.readFileSync(args.tlsKeyPath!, "utf-8")
+    const cert = fs.readFileSync(args.tlsCertPath!, "utf-8")
+    const ca = args.tlsCaPath ? fs.readFileSync(args.tlsCaPath, "utf-8") : undefined
+    return {
+      httpsOptions: { key, cert, ca },
+      caCertPath: args.tlsCaPath,
+      mode: "provided",
+    }
+  }
+
+  return ensureGeneratedTls(args)
+}
+
+function ensureGeneratedTls(args: ResolveHttpsOptionsArgs): ResolvedHttpsOptions {
+  const tlsDir = path.join(args.configDir, "tls")
+  const caKeyPath = path.join(tlsDir, "ca-key.pem")
+  const caCertPath = path.join(tlsDir, "ca-cert.pem")
+  const keyPath = path.join(tlsDir, "server-key.pem")
+  const certPath = path.join(tlsDir, "server-cert.pem")
+
+  fs.mkdirSync(tlsDir, { recursive: true })
+
+  const shouldRotateLeaf = () => {
+    try {
+      if (!fs.existsSync(certPath)) return true
+      const pem = fs.readFileSync(certPath, "utf-8")
+      const x509 = new crypto.X509Certificate(pem)
+      const validToMs = Date.parse(x509.validTo)
+      if (!Number.isFinite(validToMs)) return true
+      const rotateAt = validToMs - ROTATE_IF_EXPIRES_WITHIN_DAYS * 24 * 60 * 60 * 1000
+      return Date.now() >= rotateAt
+    } catch {
+      return true
+    }
+  }
+
+  const shouldRotateCa = () => {
+    try {
+      if (!fs.existsSync(caCertPath)) return true
+      const pem = fs.readFileSync(caCertPath, "utf-8")
+      const x509 = new crypto.X509Certificate(pem)
+      const validToMs = Date.parse(x509.validTo)
+      if (!Number.isFinite(validToMs)) return true
+      // CA rotates only when expired.
+      return Date.now() >= validToMs
+    } catch {
+      return true
+    }
+  }
+
+  if (shouldRotateCa() || !fs.existsSync(caKeyPath)) {
+    const { caKeyPem, caCertPem } = generateCaCertificate()
+    writePemFile(caKeyPath, caKeyPem, 0o600)
+    writePemFile(caCertPath, caCertPem, 0o644)
+    args.logger.info({ caCertPath }, "Generated self-signed CodeNomad CA certificate")
+  }
+
+  if (shouldRotateLeaf() || !fs.existsSync(keyPath)) {
+    const caKeyPem = fs.readFileSync(caKeyPath, "utf-8")
+    const caCertPem = fs.readFileSync(caCertPath, "utf-8")
+
+    const { keyPem, certPem } = generateServerCertificate({
+      host: args.host,
+      tlsSANs: args.tlsSANs,
+      caKeyPem,
+      caCertPem,
+    })
+
+    writePemFile(keyPath, keyPem, 0o600)
+    writePemFile(certPath, certPem, 0o644)
+    args.logger.info({ certPath }, "Generated CodeNomad HTTPS certificate")
+  }
+
+  const key = fs.readFileSync(keyPath, "utf-8")
+  const cert = fs.readFileSync(certPath, "utf-8")
+  const ca = fs.readFileSync(caCertPath, "utf-8")
+
+  // Present the CA as part of the chain.
+  const chainedCert = `${cert.trim()}\n${ca.trim()}\n`
+
+  return {
+    httpsOptions: {
+      key,
+      cert: chainedCert,
+    },
+    caCertPath,
+    mode: "generated",
+  }
+}
+
+function writePemFile(filePath: string, content: string, mode: number) {
+  fs.writeFileSync(filePath, content, { encoding: "utf-8", mode })
+  try {
+    fs.chmodSync(filePath, mode)
+  } catch {
+    // best effort on platforms that ignore chmod
+  }
+}
+
+function generateCaCertificate(): { caKeyPem: string; caCertPem: string } {
+  const forge = loadForge()
+
+  const keys = forge.pki.rsa.generateKeyPair(2048)
+  const cert = forge.pki.createCertificate()
+  cert.publicKey = keys.publicKey
+  cert.serialNumber = crypto.randomBytes(16).toString("hex")
+
+  const now = new Date()
+  const notBefore = new Date(now.getTime() - 60_000)
+  const notAfter = new Date(now.getTime() + CA_VALIDITY_DAYS * 24 * 60 * 60 * 1000)
+  cert.validity.notBefore = notBefore
+  cert.validity.notAfter = notAfter
+
+  const attrs = [{ name: "commonName", value: "CodeNomad Local CA" }]
+  cert.setSubject(attrs)
+  cert.setIssuer(attrs)
+
+  cert.setExtensions([
+    { name: "basicConstraints", cA: true },
+    { name: "keyUsage", keyCertSign: true, cRLSign: true, digitalSignature: true },
+    { name: "subjectKeyIdentifier" },
+  ])
+
+  cert.sign(keys.privateKey, forge.md.sha256.create())
+
+  return {
+    caKeyPem: forge.pki.privateKeyToPem(keys.privateKey),
+    caCertPem: forge.pki.certificateToPem(cert),
+  }
+}
+
+function generateServerCertificate(args: {
+  host: string
+  tlsSANs?: string
+  caKeyPem: string
+  caCertPem: string
+}): { keyPem: string; certPem: string } {
+  const forge = loadForge()
+
+  const caKey = forge.pki.privateKeyFromPem(args.caKeyPem)
+  const caCert = forge.pki.certificateFromPem(args.caCertPem)
+
+  const keys = forge.pki.rsa.generateKeyPair(2048)
+  const cert = forge.pki.createCertificate()
+  cert.publicKey = keys.publicKey
+  cert.serialNumber = crypto.randomBytes(16).toString("hex")
+
+  const now = new Date()
+  const notBefore = new Date(now.getTime() - 60_000)
+  const notAfter = new Date(now.getTime() + LEAF_VALIDITY_DAYS * 24 * 60 * 60 * 1000)
+  cert.validity.notBefore = notBefore
+  cert.validity.notAfter = notAfter
+
+  const commonName = pickCommonName(args.host)
+  cert.setSubject([{ name: "commonName", value: commonName }])
+  cert.setIssuer(caCert.subject.attributes)
+
+  const san = buildSubjectAltNames(args.host, args.tlsSANs)
+
+  cert.setExtensions([
+    { name: "basicConstraints", cA: false },
+    { name: "keyUsage", digitalSignature: true, keyEncipherment: true },
+    { name: "extKeyUsage", serverAuth: true },
+    { name: "subjectAltName", altNames: san },
+    { name: "subjectKeyIdentifier" },
+  ])
+
+  cert.sign(caKey, forge.md.sha256.create())
+
+  return {
+    keyPem: forge.pki.privateKeyToPem(keys.privateKey),
+    certPem: forge.pki.certificateToPem(cert),
+  }
+}
+
+function pickCommonName(host: string): string {
+  if (!host || host === "0.0.0.0") {
+    return "localhost"
+  }
+  if (host === "127.0.0.1") {
+    return "localhost"
+  }
+  return host
+}
+
+function buildSubjectAltNames(host: string, tlsSANs?: string): Array<{ type: number; value?: string; ip?: string }> {
+  const dns = new Set<string>()
+  const ips = new Set<string>()
+
+  dns.add("localhost")
+  ips.add("127.0.0.1")
+
+  if (host && host !== "0.0.0.0") {
+    if (isIPv4(host)) {
+      ips.add(host)
+    } else {
+      dns.add(host)
+    }
+  }
+
+  for (const token of splitList(tlsSANs)) {
+    if (isIPv4(token)) {
+      ips.add(token)
+    } else if (token) {
+      dns.add(token)
+    }
+  }
+
+  const altNames: Array<{ type: number; value?: string; ip?: string }> = []
+
+  // 2 = DNS, 7 = IP
+  for (const name of Array.from(dns)) {
+    altNames.push({ type: 2, value: name })
+  }
+  for (const ip of Array.from(ips)) {
+    altNames.push({ type: 7, ip })
+  }
+
+  return altNames
+}
+
+function splitList(input: string | undefined): string[] {
+  if (!input) return []
+  return input
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean)
+}
+
+function isIPv4(value: string): boolean {
+  const parts = value.split(".")
+  if (parts.length !== 4) return false
+  return parts.every((part) => {
+    if (!/^[0-9]+$/.test(part)) return false
+    const num = Number(part)
+    return Number.isInteger(num) && num >= 0 && num <= 255
+  })
+}

packages/server/src/workspaces/git-worktrees.ts

@@ -0,0 +1,241 @@
+import path from "path"
+import { spawn } from "child_process"
+import type { WorktreeDescriptor } from "../api-types"
+import { promises as fsp } from "fs"
+
+export interface LogLike {
+  debug?: (obj: any, msg?: string) => void
+  warn?: (obj: any, msg?: string) => void
+}
+
+type GitResult = { ok: true; stdout: string } | { ok: false; error: Error; stdout?: string; stderr?: string }
+
+function runGit(args: string[], cwd: string): Promise<GitResult> {
+  return new Promise((resolve) => {
+    const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] })
+    let stdout = ""
+    let stderr = ""
+
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString()
+    })
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString()
+    })
+    child.once("error", (error) => {
+      resolve({ ok: false, error, stdout, stderr })
+    })
+    child.once("close", (code) => {
+      if (code === 0) {
+        resolve({ ok: true, stdout })
+      } else {
+        const error = new Error(stderr.trim() || `git ${args.join(" ")} failed with code ${code}`)
+        resolve({ ok: false, error, stdout, stderr })
+      }
+    })
+  })
+}
+
+export async function resolveRepoRoot(folder: string, logger?: LogLike): Promise<{ repoRoot: string; isGitRepo: boolean }> {
+  const result = await runGit(["rev-parse", "--show-toplevel"], folder)
+  if (!result.ok) {
+    logger?.debug?.({ folder, err: result.error }, "Folder is not a Git repository; using workspace folder as root")
+    return { repoRoot: folder, isGitRepo: false }
+  }
+  const repoRoot = result.stdout.trim()
+  if (!repoRoot) {
+    return { repoRoot: folder, isGitRepo: false }
+  }
+  return { repoRoot, isGitRepo: true }
+}
+
+function parseWorktreePorcelain(output: string): Array<{ worktree: string; branch?: string; head?: string; detached?: boolean }> {
+  const records: Array<{ worktree: string; branch?: string; head?: string; detached?: boolean }> = []
+  const lines = output.split(/\r?\n/)
+  let current: { worktree?: string; branch?: string; head?: string; detached?: boolean } = {}
+
+  const flush = () => {
+    if (current.worktree) {
+      records.push({ worktree: current.worktree, branch: current.branch })
+    }
+    current = {}
+  }
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed) {
+      flush()
+      continue
+    }
+    const [key, ...rest] = trimmed.split(" ")
+    const value = rest.join(" ").trim()
+    if (key === "worktree") {
+      current.worktree = value
+    } else if (key === "branch") {
+      // branch is like refs/heads/foo
+      current.branch = value.replace(/^refs\/heads\//, "")
+    } else if (key === "HEAD") {
+      current.head = value
+    } else if (key === "detached") {
+      current.detached = true
+    }
+  }
+  flush()
+  return records
+}
+
+export async function listWorktrees(params: {
+  repoRoot: string
+  workspaceFolder: string
+  logger?: LogLike
+}): Promise<WorktreeDescriptor[]> {
+  const { repoRoot, workspaceFolder, logger } = params
+  const rootDescriptor: WorktreeDescriptor = { slug: "root", directory: repoRoot, kind: "root" }
+
+  const result = await runGit(["worktree", "list", "--porcelain"], workspaceFolder)
+  if (!result.ok) {
+    logger?.debug?.({ repoRoot, err: result.error }, "Failed to list git worktrees; returning root only")
+    return [rootDescriptor]
+  }
+
+  const records = parseWorktreePorcelain(result.stdout)
+
+  const worktrees: WorktreeDescriptor[] = [rootDescriptor]
+  const seen = new Set<string>(["root"])
+
+  const normalizeSlug = (record: { branch?: string; head?: string; detached?: boolean; worktree: string }): string => {
+    const branch = (record.branch ?? "").trim()
+    if (branch) {
+      return branch
+    }
+    const head = (record.head ?? "").trim()
+    if (head && /^[0-9a-f]{7,40}$/i.test(head)) {
+      return `detached-${head.slice(0, 7)}`
+    }
+    // Fallback: stable-ish identifier derived from directory basename.
+    const base = path.basename(record.worktree || "")
+    return base ? `worktree-${base}` : "worktree"
+  }
+
+
+  for (const record of records) {
+    const abs = record.worktree
+    if (!abs || typeof abs !== "string") continue
+
+    // Skip the root record (we always expose it as slug="root").
+    if (path.resolve(abs) === path.resolve(repoRoot)) {
+      continue
+    }
+
+    const slug = normalizeSlug(record)
+    if (!slug || slug === "root") {
+      continue
+    }
+    if (seen.has(slug)) {
+      continue
+    }
+    seen.add(slug)
+    worktrees.push({ slug, directory: abs, kind: "worktree", branch: record.branch })
+  }
+
+  return worktrees
+}
+
+export function isValidWorktreeSlug(slug: string): boolean {
+  if (!slug) return false
+  const trimmed = slug.trim()
+  if (!trimmed) return false
+  if (trimmed.length > 200) return false
+  // Disallow control characters; allow branch-like slugs including '/'.
+  if (/[\x00-\x1F\x7F]/.test(trimmed)) return false
+  return true
+}
+
+export async function createManagedWorktree(params: {
+  repoRoot: string
+  workspaceFolder: string
+  slug: string
+  logger?: LogLike
+}): Promise<{ slug: string; directory: string; branch?: string }> {
+  const { repoRoot, workspaceFolder, logger } = params
+  const branch = params.slug.trim()
+
+  if (!branch || branch === "root" || !isValidWorktreeSlug(branch)) {
+    throw new Error("Invalid worktree slug")
+  }
+
+  const sanitizeDirName = (input: string): string => {
+    const normalized = input
+      .trim()
+      .replace(/[\\/]+/g, "-")
+      .replace(/\s+/g, "-")
+      .replace(/[^a-zA-Z0-9_.-]+/g, "-")
+      .replace(/-{2,}/g, "-")
+      .replace(/^-+|-+$/g, "")
+    return normalized || "worktree"
+  }
+
+  const worktreesDir = path.join(repoRoot, ".codenomad", "worktrees")
+  const targetDir = path.join(worktreesDir, sanitizeDirName(branch))
+  await fsp.mkdir(worktreesDir, { recursive: true })
+
+  try {
+    const stat = await fsp.stat(targetDir)
+    if (stat.isDirectory()) {
+      throw new Error("Worktree directory already exists")
+    }
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code
+    if (code !== "ENOENT") {
+      throw error
+    }
+  }
+
+  logger?.debug?.({ slug: branch, branch, targetDir }, "Creating managed git worktree")
+
+  // Prefer creating a new branch from HEAD.
+  const first = await runGit(["worktree", "add", "-b", branch, targetDir, "HEAD"], workspaceFolder)
+  if (first.ok) {
+    return { slug: branch, directory: targetDir, branch }
+  }
+
+  const message = first.stderr?.toLowerCase() ?? first.error.message.toLowerCase()
+  if (message.includes("already exists")) {
+    // If the branch already exists, add worktree for that branch.
+    const second = await runGit(["worktree", "add", targetDir, branch], workspaceFolder)
+    if (second.ok) {
+      return { slug: branch, directory: targetDir, branch }
+    }
+    throw second.error
+  }
+
+  throw first.error
+}
+
+export async function removeWorktree(params: {
+  workspaceFolder: string
+  directory: string
+  force?: boolean
+  logger?: LogLike
+}): Promise<void> {
+  const { workspaceFolder, logger } = params
+  const directory = (params.directory ?? "").trim()
+  if (!directory) {
+    throw new Error("Invalid worktree directory")
+  }
+  logger?.debug?.({ directory, force: Boolean(params.force) }, "Removing git worktree")
+
+  const args = ["worktree", "remove"]
+  if (params.force) {
+    args.push("--force")
+  }
+  args.push(directory)
+
+  const result = await runGit(args, workspaceFolder)
+  if (!result.ok) {
+    throw result.error
+  }
+
+  // Best-effort cleanup of stale metadata.
+  await runGit(["worktree", "prune"], workspaceFolder).catch(() => undefined)
+}

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

@@ -95,7 +95,7 @@ export class InstanceEventBridge {
   }
 
   private async consumeStream(workspaceId: string, port: number, signal: AbortSignal) {
-    const url = `http://${INSTANCE_HOST}:${port}/event`
+    const url = `http://${INSTANCE_HOST}:${port}/global/event`
 
     const headers: Record<string, string> = { Accept: "text/event-stream" }
     const authHeader = this.options.workspaceManager.getInstanceAuthorizationHeader(workspaceId)
@@ -165,8 +165,32 @@ export class InstanceEventBridge {
     }
 
     try {
-      const event = JSON.parse(payload) as InstanceStreamEvent
-      this.options.logger.debug({ workspaceId, eventType: event.type }, "Instance SSE event received")
+      const parsed = JSON.parse(payload) as any
+      if (!parsed || typeof parsed !== "object") {
+        this.options.logger.warn({ workspaceId, chunk: payload }, "Dropped malformed instance event")
+        return
+      }
+
+      // OpenCode SSE payload shapes vary across versions.
+      // Common variants:
+      // - { type, properties, ... }
+      // - { payload: { type, properties, ... }, directory: "/abs/path" }
+      // - { payload: { type, properties, ... } }
+      const base = parsed.payload && typeof parsed.payload === "object" ? parsed.payload : parsed
+
+      const event: InstanceStreamEvent | null = base && typeof base === "object" ? ({ ...base } as any) : null
+
+      // Attach directory when available (don't overwrite if already present).
+      if (event && !(event as any).directory && typeof (parsed as any).directory === "string") {
+        ;(event as any).directory = (parsed as any).directory
+      }
+
+      if (!event || typeof (event as any).type !== "string") {
+        this.options.logger.warn({ workspaceId, chunk: payload }, "Dropped malformed instance event")
+        return
+      }
+
+      this.options.logger.debug({ workspaceId, eventType: (event as any).type }, "Instance SSE event received")
       if (this.options.logger.isLevelEnabled("trace")) {
         this.options.logger.trace({ workspaceId, event }, "Instance SSE event payload")
       }

packages/server/src/workspaces/manager.ts

@@ -28,6 +28,8 @@ interface WorkspaceManagerOptions {
   eventBus: EventBus
   logger: Logger
   getServerBaseUrl: () => string
+  /** Optional CA bundle path to trust CodeNomad HTTPS certs. */
+  nodeExtraCaCertsPath?: string
 }
 
 interface WorkspaceRecord extends WorkspaceDescriptor {}
@@ -91,7 +93,7 @@ export class WorkspaceManager {
 
     this.options.logger.info({ workspaceId: id, folder: workspacePath, binary: resolvedBinaryPath }, "Creating workspace")
 
-    const proxyPath = `/workspaces/${id}/instance`
+    const proxyPath = `/workspaces/${id}/worktrees/root/instance`
 
 
     const descriptor: WorkspaceRecord = {
@@ -132,6 +134,7 @@ export class WorkspaceManager {
       OPENCODE_CONFIG_DIR: this.opencodeConfigDir,
       CODENOMAD_INSTANCE_ID: id,
       CODENOMAD_BASE_URL: this.options.getServerBaseUrl(),
+      ...(this.options.nodeExtraCaCertsPath ? { NODE_EXTRA_CA_CERTS: this.options.nodeExtraCaCertsPath } : {}),
       [OPENCODE_SERVER_USERNAME_ENV]: opencodeUsername,
       [OPENCODE_SERVER_PASSWORD_ENV]: opencodePassword,
     }

packages/server/src/workspaces/runtime.ts

@@ -116,12 +116,26 @@ export class WorkspaceRuntime {
           folder: options.folder,
           binary: options.binaryPath,
           spawnCommand: spec.command,
-          spawnArgs: spec.args,
           commandLine,
-          env: redactEnvironment(env),
         },
         "Launching OpenCode process",
       )
+
+      this.logger.debug(
+        {
+          workspaceId: options.workspaceId,
+          spawnArgs: spec.args,
+        },
+        "OpenCode spawn args",
+      )
+
+      this.logger.trace(
+        {
+          workspaceId: options.workspaceId,
+          env: redactEnvironment(env),
+        },
+        "OpenCode spawn environment",
+      )
       const detached = process.platform !== "win32"
       const child = spawn(spec.command, spec.args, {
         cwd: options.folder,

packages/server/src/workspaces/worktree-map.ts

@@ -0,0 +1,129 @@
+import fs from "fs"
+import { promises as fsp } from "fs"
+import path from "path"
+import type { WorktreeMap } from "../api-types"
+import { resolveRepoRoot } from "./git-worktrees"
+import type { LogLike } from "./git-worktrees"
+
+const DEFAULT_MAP: WorktreeMap = {
+  version: 1,
+  defaultWorktreeSlug: "root",
+  parentSessionWorktreeSlug: {},
+}
+
+function getMapPath(repoRoot: string): string {
+  return path.join(repoRoot, ".codenomad", "worktreeMap.json")
+}
+
+function getGitExcludePath(repoRoot: string): string {
+  return path.join(repoRoot, ".git", "info", "exclude")
+}
+
+async function ensureGitExclude(repoRoot: string, logger?: LogLike): Promise<void> {
+  const excludePath = getGitExcludePath(repoRoot)
+  try {
+    await fsp.mkdir(path.dirname(excludePath), { recursive: true })
+  } catch {
+    return
+  }
+
+  const entries = [
+    ".codenomad/worktrees/",
+    ".codenomad/worktreeMap.json",
+  ]
+
+  let existing = ""
+  try {
+    existing = await fsp.readFile(excludePath, "utf-8")
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code
+    if (code !== "ENOENT") {
+      logger?.debug?.({ err: error, excludePath }, "Failed to read .git/info/exclude")
+      return
+    }
+    existing = ""
+  }
+
+  const lines = new Set(existing.split(/\r?\n/).map((l) => l.trim()).filter(Boolean))
+  const missing = entries.filter((e) => !lines.has(e))
+  if (missing.length === 0) {
+    return
+  }
+
+  const header = existing.includes("# codenomad") ? "" : (existing.trim() ? "\n" : "") + "# codenomad\n"
+  const suffix = missing.map((e) => `${e}\n`).join("")
+  await fsp.writeFile(excludePath, `${existing}${header}${suffix}`, "utf-8")
+}
+
+export async function ensureCodenomadGitExclude(workspaceFolder: string, logger?: LogLike): Promise<void> {
+  const { repoRoot, isGitRepo } = await resolveRepoRoot(workspaceFolder, logger)
+  if (!isGitRepo) {
+    return
+  }
+  await ensureGitExclude(repoRoot, logger)
+}
+
+export async function readWorktreeMap(workspaceFolder: string, logger?: LogLike): Promise<WorktreeMap> {
+  const { repoRoot, isGitRepo } = await resolveRepoRoot(workspaceFolder, logger)
+  const filePath = getMapPath(repoRoot)
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8")
+    const parsed = JSON.parse(raw)
+    if (!parsed || typeof parsed !== "object") {
+      return DEFAULT_MAP
+    }
+    const version = (parsed as any).version
+    if (version !== 1) {
+      return DEFAULT_MAP
+    }
+    const defaultWorktreeSlug = typeof (parsed as any).defaultWorktreeSlug === "string" ? (parsed as any).defaultWorktreeSlug : "root"
+    const parentSessionWorktreeSlug = (parsed as any).parentSessionWorktreeSlug
+    const mapping = parentSessionWorktreeSlug && typeof parentSessionWorktreeSlug === "object" ? parentSessionWorktreeSlug : {}
+    return {
+      version: 1,
+      defaultWorktreeSlug,
+      parentSessionWorktreeSlug: { ...mapping },
+    }
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code
+    if (code === "ENOENT") {
+      if (isGitRepo) {
+        // Best-effort ignore setup on first use.
+        await ensureGitExclude(repoRoot, logger).catch(() => undefined)
+      }
+      return DEFAULT_MAP
+    }
+    logger?.warn?.({ err: error, filePath }, "Failed to read worktree map")
+    return DEFAULT_MAP
+  }
+}
+
+export async function writeWorktreeMap(workspaceFolder: string, next: WorktreeMap, logger?: LogLike): Promise<void> {
+  const { repoRoot, isGitRepo } = await resolveRepoRoot(workspaceFolder, logger)
+  const filePath = getMapPath(repoRoot)
+  await fsp.mkdir(path.dirname(filePath), { recursive: true })
+
+  // Ensure ignore rules are present (local-only).
+  if (isGitRepo) {
+    await ensureGitExclude(repoRoot, logger).catch(() => undefined)
+  }
+
+  const payload: WorktreeMap = {
+    version: 1,
+    defaultWorktreeSlug: next.defaultWorktreeSlug || "root",
+    parentSessionWorktreeSlug: next.parentSessionWorktreeSlug ?? {},
+  }
+
+  // Write atomically.
+  const tmpPath = `${filePath}.${process.pid}.tmp`
+  await fsp.writeFile(tmpPath, JSON.stringify(payload, null, 2), "utf-8")
+  await fsp.rename(tmpPath, filePath)
+}
+
+export function worktreeMapExists(repoRoot: string): boolean {
+  try {
+    return fs.existsSync(getMapPath(repoRoot))
+  } catch {
+    return false
+  }
+}

packages/tauri-app/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@codenomad/tauri-app",
-  "version": "0.9.2",
+  "version": "0.10.3",
   "private": true,
+  "license": "MIT",
   "scripts": {
     "dev": "tauri dev",
     "dev:ui": "npm run dev --workspace @codenomad/ui",

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

@@ -3,6 +3,7 @@
 const fs = require("fs")
 const path = require("path")
 const { execSync } = require("child_process")
+const { pathToFileURL } = require("url")
 
 const root = path.resolve(__dirname, "..")
 const workspaceRoot = path.resolve(root, "..", "..")
@@ -10,6 +11,20 @@ const uiRoot = path.resolve(root, "..", "ui")
 const uiDist = path.resolve(uiRoot, "src", "renderer", "dist")
 const uiLoadingDest = path.resolve(root, "src-tauri", "resources", "ui-loading")
 
+async function ensureMonacoAssets() {
+  const helperPath = path.join(uiRoot, "scripts", "monaco-public-assets.js")
+  const helperUrl = pathToFileURL(helperPath).href
+  const { copyMonacoPublicAssets } = await import(helperUrl)
+  copyMonacoPublicAssets({
+    uiRendererRoot: path.join(uiRoot, "src", "renderer"),
+    warn: (msg) => console.warn(`[dev-prep] ${msg}`),
+    sourceRoots: [
+      path.resolve(workspaceRoot, "node_modules", "monaco-editor", "min", "vs"),
+      path.resolve(uiRoot, "node_modules", "monaco-editor", "min", "vs"),
+    ],
+  })
+}
+
 function ensureUiBuild() {
   const loadingHtml = path.join(uiDist, "loading.html")
   if (fs.existsSync(loadingHtml)) {
@@ -42,5 +57,11 @@ function copyUiLoadingAssets() {
   console.log(`[dev-prep] copied loader bundle from ${uiDist}`)
 }
 
-ensureUiBuild()
-copyUiLoadingAssets()
+;(async () => {
+  await ensureMonacoAssets()
+  ensureUiBuild()
+  copyUiLoadingAssets()
+})().catch((err) => {
+  console.error("[dev-prep] failed:", err)
+  process.exit(1)
+})

packages/tauri-app/scripts/prebuild.js

@@ -2,6 +2,7 @@
 const fs = require("fs")
 const path = require("path")
 const { execSync } = require("child_process")
+const { pathToFileURL } = require("url")
 
 const root = path.resolve(__dirname, "..")
 const workspaceRoot = path.resolve(root, "..", "..")
@@ -37,6 +38,20 @@ const braceExpansionPath = path.join(
 
 const viteBinPath = path.join(uiRoot, "node_modules", ".bin", "vite")
 
+async function ensureMonacoAssets() {
+  const helperPath = path.join(uiRoot, "scripts", "monaco-public-assets.js")
+  const helperUrl = pathToFileURL(helperPath).href
+  const { copyMonacoPublicAssets } = await import(helperUrl)
+  copyMonacoPublicAssets({
+    uiRendererRoot: path.join(uiRoot, "src", "renderer"),
+    warn: (msg) => console.warn(`[prebuild] ${msg}`),
+    sourceRoots: [
+      path.resolve(workspaceRoot, "node_modules", "monaco-editor", "min", "vs"),
+      path.resolve(uiRoot, "node_modules", "monaco-editor", "min", "vs"),
+    ],
+  })
+}
+
 function ensureServerBuild() {
   const distPath = path.join(serverRoot, "dist")
   const publicPath = path.join(serverRoot, "public")
@@ -223,12 +238,18 @@ function copyUiLoadingAssets() {
   console.log(`[prebuild] prepared UI loading assets from ${uiDist}`)
 }
 
-ensureServerDevDependencies()
-ensureUiDevDependencies()
-ensureRollupPlatformBinary()
-ensureServerDependencies()
-ensureServerBuild()
-ensureUiBuild()
-copyServerArtifacts()
-stripNodeModuleBins()
-copyUiLoadingAssets()
+;(async () => {
+  ensureServerDevDependencies()
+  ensureUiDevDependencies()
+  await ensureMonacoAssets()
+  ensureRollupPlatformBinary()
+  ensureServerDependencies()
+  ensureServerBuild()
+  ensureUiBuild()
+  copyServerArtifacts()
+  stripNodeModuleBins()
+  copyUiLoadingAssets()
+})().catch((err) => {
+  console.error("[prebuild] failed:", err)
+  process.exit(1)
+})

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

@@ -2,6 +2,7 @@
 name = "codenomad-tauri"
 version = "0.1.0"
 edition = "2021"
+license = "MIT"
 
 [build-dependencies]
 tauri-build = { version = "2.5.2", features = [] }
@@ -10,6 +11,7 @@ tauri-build = { version = "2.5.2", features = [] }
 tauri = { version = "2.5.2", features = [ "devtools"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+serde_yaml = "0.9"
 regex = "1"
 once_cell = "1"
 parking_lot = "0.12"
@@ -21,3 +23,5 @@ tauri-plugin-dialog = "2"
 dirs = "5"
 tauri-plugin-opener = "2"
 url = "2"
+tauri-plugin-keepawake = "0.1.1"
+tauri-plugin-notification = "2"

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

@@ -3,7 +3,7 @@
   "identifier": "main-window-native-dialogs",
   "description": "Grant the main window access to required core features and native dialog commands.",
   "remote": {
-    "urls": ["http://127.0.0.1:*", "http://localhost:*"]
+    "urls": ["http://127.0.0.1:*", "http://localhost:*", "http://tauri.localhost/*", "https://tauri.localhost/*"]
   },
   "windows": ["main"],
   "permissions": [
@@ -11,6 +11,10 @@
     "core:menu:default",
     "dialog:allow-open",
     "opener:allow-default-urls",
+    "notification:allow-is-permission-granted",
+    "notification:allow-request-permission",
+    "notification:allow-notify",
+    "notification:allow-show",
     "core:webview:allow-set-webview-zoom"
   ]
 }

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

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

packages/tauri-app/src-tauri/gen/schemas/desktop-schema.json

@@ -2378,6 +2378,234 @@
           "const": "dialog:deny-save",
           "markdownDescription": "Denies the save command without any pre-configured scope."
         },
+        {
+          "description": "Default permissions for the plugin\n#### This default permission set includes:\n\n- `allow-start`\n- `allow-stop`",
+          "type": "string",
+          "const": "keepawake:default",
+          "markdownDescription": "Default permissions for the plugin\n#### This default permission set includes:\n\n- `allow-start`\n- `allow-stop`"
+        },
+        {
+          "description": "Enables the start command without any pre-configured scope.",
+          "type": "string",
+          "const": "keepawake:allow-start",
+          "markdownDescription": "Enables the start command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the stop command without any pre-configured scope.",
+          "type": "string",
+          "const": "keepawake:allow-stop",
+          "markdownDescription": "Enables the stop command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the start command without any pre-configured scope.",
+          "type": "string",
+          "const": "keepawake:deny-start",
+          "markdownDescription": "Denies the start command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the stop command without any pre-configured scope.",
+          "type": "string",
+          "const": "keepawake:deny-stop",
+          "markdownDescription": "Denies the stop command without any pre-configured scope."
+        },
+        {
+          "description": "This permission set configures which\nnotification features are by default exposed.\n\n#### Granted Permissions\n\nIt allows all notification related features.\n\n\n#### This default permission set includes:\n\n- `allow-is-permission-granted`\n- `allow-request-permission`\n- `allow-notify`\n- `allow-register-action-types`\n- `allow-register-listener`\n- `allow-cancel`\n- `allow-get-pending`\n- `allow-remove-active`\n- `allow-get-active`\n- `allow-check-permissions`\n- `allow-show`\n- `allow-batch`\n- `allow-list-channels`\n- `allow-delete-channel`\n- `allow-create-channel`\n- `allow-permission-state`",
+          "type": "string",
+          "const": "notification:default",
+          "markdownDescription": "This permission set configures which\nnotification features are by default exposed.\n\n#### Granted Permissions\n\nIt allows all notification related features.\n\n\n#### This default permission set includes:\n\n- `allow-is-permission-granted`\n- `allow-request-permission`\n- `allow-notify`\n- `allow-register-action-types`\n- `allow-register-listener`\n- `allow-cancel`\n- `allow-get-pending`\n- `allow-remove-active`\n- `allow-get-active`\n- `allow-check-permissions`\n- `allow-show`\n- `allow-batch`\n- `allow-list-channels`\n- `allow-delete-channel`\n- `allow-create-channel`\n- `allow-permission-state`"
+        },
+        {
+          "description": "Enables the batch command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-batch",
+          "markdownDescription": "Enables the batch command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the cancel command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-cancel",
+          "markdownDescription": "Enables the cancel command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the check_permissions command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-check-permissions",
+          "markdownDescription": "Enables the check_permissions command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the create_channel command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-create-channel",
+          "markdownDescription": "Enables the create_channel command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the delete_channel command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-delete-channel",
+          "markdownDescription": "Enables the delete_channel command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the get_active command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-get-active",
+          "markdownDescription": "Enables the get_active command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the get_pending command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-get-pending",
+          "markdownDescription": "Enables the get_pending command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the is_permission_granted command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-is-permission-granted",
+          "markdownDescription": "Enables the is_permission_granted command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the list_channels command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-list-channels",
+          "markdownDescription": "Enables the list_channels command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the notify command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-notify",
+          "markdownDescription": "Enables the notify command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the permission_state command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-permission-state",
+          "markdownDescription": "Enables the permission_state command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the register_action_types command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-register-action-types",
+          "markdownDescription": "Enables the register_action_types command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the register_listener command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-register-listener",
+          "markdownDescription": "Enables the register_listener command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the remove_active command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-remove-active",
+          "markdownDescription": "Enables the remove_active command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the request_permission command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-request-permission",
+          "markdownDescription": "Enables the request_permission command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the show command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-show",
+          "markdownDescription": "Enables the show command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the batch command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-batch",
+          "markdownDescription": "Denies the batch command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the cancel command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-cancel",
+          "markdownDescription": "Denies the cancel command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the check_permissions command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-check-permissions",
+          "markdownDescription": "Denies the check_permissions command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the create_channel command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-create-channel",
+          "markdownDescription": "Denies the create_channel command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the delete_channel command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-delete-channel",
+          "markdownDescription": "Denies the delete_channel command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the get_active command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-get-active",
+          "markdownDescription": "Denies the get_active command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the get_pending command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-get-pending",
+          "markdownDescription": "Denies the get_pending command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the is_permission_granted command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-is-permission-granted",
+          "markdownDescription": "Denies the is_permission_granted command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the list_channels command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-list-channels",
+          "markdownDescription": "Denies the list_channels command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the notify command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-notify",
+          "markdownDescription": "Denies the notify command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the permission_state command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-permission-state",
+          "markdownDescription": "Denies the permission_state command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the register_action_types command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-register-action-types",
+          "markdownDescription": "Denies the register_action_types command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the register_listener command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-register-listener",
+          "markdownDescription": "Denies the register_listener command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the remove_active command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-remove-active",
+          "markdownDescription": "Denies the remove_active command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the request_permission command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-request-permission",
+          "markdownDescription": "Denies the request_permission command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the show command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-show",
+          "markdownDescription": "Denies the show command without any pre-configured scope."
+        },
         {
           "description": "This permission set allows opening `mailto:`, `tel:`, `https://` and `http://` urls using their default application\nas well as reveal file in directories using default file explorer\n#### This default permission set includes:\n\n- `allow-open-url`\n- `allow-reveal-item-in-dir`\n- `allow-default-urls`",
           "type": "string",

packages/tauri-app/src-tauri/gen/schemas/macOS-schema.json

@@ -2378,6 +2378,234 @@
           "const": "dialog:deny-save",
           "markdownDescription": "Denies the save command without any pre-configured scope."
         },
+        {
+          "description": "Default permissions for the plugin\n#### This default permission set includes:\n\n- `allow-start`\n- `allow-stop`",
+          "type": "string",
+          "const": "keepawake:default",
+          "markdownDescription": "Default permissions for the plugin\n#### This default permission set includes:\n\n- `allow-start`\n- `allow-stop`"
+        },
+        {
+          "description": "Enables the start command without any pre-configured scope.",
+          "type": "string",
+          "const": "keepawake:allow-start",
+          "markdownDescription": "Enables the start command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the stop command without any pre-configured scope.",
+          "type": "string",
+          "const": "keepawake:allow-stop",
+          "markdownDescription": "Enables the stop command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the start command without any pre-configured scope.",
+          "type": "string",
+          "const": "keepawake:deny-start",
+          "markdownDescription": "Denies the start command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the stop command without any pre-configured scope.",
+          "type": "string",
+          "const": "keepawake:deny-stop",
+          "markdownDescription": "Denies the stop command without any pre-configured scope."
+        },
+        {
+          "description": "This permission set configures which\nnotification features are by default exposed.\n\n#### Granted Permissions\n\nIt allows all notification related features.\n\n\n#### This default permission set includes:\n\n- `allow-is-permission-granted`\n- `allow-request-permission`\n- `allow-notify`\n- `allow-register-action-types`\n- `allow-register-listener`\n- `allow-cancel`\n- `allow-get-pending`\n- `allow-remove-active`\n- `allow-get-active`\n- `allow-check-permissions`\n- `allow-show`\n- `allow-batch`\n- `allow-list-channels`\n- `allow-delete-channel`\n- `allow-create-channel`\n- `allow-permission-state`",
+          "type": "string",
+          "const": "notification:default",
+          "markdownDescription": "This permission set configures which\nnotification features are by default exposed.\n\n#### Granted Permissions\n\nIt allows all notification related features.\n\n\n#### This default permission set includes:\n\n- `allow-is-permission-granted`\n- `allow-request-permission`\n- `allow-notify`\n- `allow-register-action-types`\n- `allow-register-listener`\n- `allow-cancel`\n- `allow-get-pending`\n- `allow-remove-active`\n- `allow-get-active`\n- `allow-check-permissions`\n- `allow-show`\n- `allow-batch`\n- `allow-list-channels`\n- `allow-delete-channel`\n- `allow-create-channel`\n- `allow-permission-state`"
+        },
+        {
+          "description": "Enables the batch command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-batch",
+          "markdownDescription": "Enables the batch command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the cancel command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-cancel",
+          "markdownDescription": "Enables the cancel command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the check_permissions command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-check-permissions",
+          "markdownDescription": "Enables the check_permissions command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the create_channel command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-create-channel",
+          "markdownDescription": "Enables the create_channel command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the delete_channel command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-delete-channel",
+          "markdownDescription": "Enables the delete_channel command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the get_active command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-get-active",
+          "markdownDescription": "Enables the get_active command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the get_pending command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-get-pending",
+          "markdownDescription": "Enables the get_pending command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the is_permission_granted command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-is-permission-granted",
+          "markdownDescription": "Enables the is_permission_granted command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the list_channels command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-list-channels",
+          "markdownDescription": "Enables the list_channels command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the notify command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-notify",
+          "markdownDescription": "Enables the notify command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the permission_state command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-permission-state",
+          "markdownDescription": "Enables the permission_state command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the register_action_types command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-register-action-types",
+          "markdownDescription": "Enables the register_action_types command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the register_listener command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-register-listener",
+          "markdownDescription": "Enables the register_listener command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the remove_active command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-remove-active",
+          "markdownDescription": "Enables the remove_active command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the request_permission command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-request-permission",
+          "markdownDescription": "Enables the request_permission command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the show command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:allow-show",
+          "markdownDescription": "Enables the show command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the batch command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-batch",
+          "markdownDescription": "Denies the batch command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the cancel command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-cancel",
+          "markdownDescription": "Denies the cancel command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the check_permissions command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-check-permissions",
+          "markdownDescription": "Denies the check_permissions command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the create_channel command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-create-channel",
+          "markdownDescription": "Denies the create_channel command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the delete_channel command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-delete-channel",
+          "markdownDescription": "Denies the delete_channel command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the get_active command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-get-active",
+          "markdownDescription": "Denies the get_active command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the get_pending command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-get-pending",
+          "markdownDescription": "Denies the get_pending command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the is_permission_granted command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-is-permission-granted",
+          "markdownDescription": "Denies the is_permission_granted command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the list_channels command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-list-channels",
+          "markdownDescription": "Denies the list_channels command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the notify command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-notify",
+          "markdownDescription": "Denies the notify command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the permission_state command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-permission-state",
+          "markdownDescription": "Denies the permission_state command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the register_action_types command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-register-action-types",
+          "markdownDescription": "Denies the register_action_types command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the register_listener command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-register-listener",
+          "markdownDescription": "Denies the register_listener command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the remove_active command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-remove-active",
+          "markdownDescription": "Denies the remove_active command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the request_permission command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-request-permission",
+          "markdownDescription": "Denies the request_permission command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the show command without any pre-configured scope.",
+          "type": "string",
+          "const": "notification:deny-show",
+          "markdownDescription": "Denies the show command without any pre-configured scope."
+        },
         {
           "description": "This permission set allows opening `mailto:`, `tel:`, `https://` and `http://` urls using their default application\nas well as reveal file in directories using default file explorer\n#### This default permission set includes:\n\n- `allow-open-url`\n- `allow-reveal-item-in-dir`\n- `allow-default-urls`",
           "type": "string",

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

@@ -145,12 +145,33 @@ struct AppConfig {
     preferences: Option<PreferencesConfig>,
 }
 
-fn resolve_config_path() -> PathBuf {
+fn resolve_config_locations() -> (PathBuf, PathBuf) {
     let raw = env::var("CLI_CONFIG")
         .ok()
         .filter(|value| !value.trim().is_empty())
         .unwrap_or_else(|| DEFAULT_CONFIG_PATH.to_string());
-    expand_home(&raw)
+
+    let expanded = expand_home(&raw);
+    let lower = raw.trim().to_lowercase();
+
+    if lower.ends_with(".yaml") || lower.ends_with(".yml") {
+        let base = expanded
+            .parent()
+            .map(|p| p.to_path_buf())
+            .unwrap_or_else(|| expanded.clone());
+        return (expanded, base.join("config.json"));
+    }
+
+    if lower.ends_with(".json") {
+        let base = expanded
+            .parent()
+            .map(|p| p.to_path_buf())
+            .unwrap_or_else(|| expanded.clone());
+        return (base.join("config.yaml"), expanded);
+    }
+
+    // Treat as directory.
+    (expanded.join("config.yaml"), expanded.join("config.json"))
 }
 
 fn expand_home(path: &str) -> PathBuf {
@@ -163,8 +184,27 @@ fn expand_home(path: &str) -> PathBuf {
 }
 
 fn resolve_listening_mode() -> String {
-    let path = resolve_config_path();
-    if let Ok(content) = fs::read_to_string(path) {
+    let (yaml_path, json_path) = resolve_config_locations();
+
+    if let Ok(content) = fs::read_to_string(&yaml_path) {
+        if let Ok(config) = serde_yaml::from_str::<AppConfig>(&content) {
+            if let Some(mode) = config
+                .preferences
+                .as_ref()
+                .and_then(|prefs| prefs.listening_mode.as_ref())
+            {
+                if mode == "local" {
+                    return "local".to_string();
+                }
+                if mode == "all" {
+                    return "all".to_string();
+                }
+            }
+        }
+    }
+
+    // Legacy fallback.
+    if let Ok(content) = fs::read_to_string(&json_path) {
         if let Ok(config) = serde_json::from_str::<AppConfig>(&content) {
             if let Some(mode) = config
                 .preferences
@@ -260,7 +300,14 @@ impl CliProcessManager {
         let ready_flag = self.ready.clone();
         let token_arc = self.bootstrap_token.clone();
         thread::spawn(move || {
-            if let Err(err) = Self::spawn_cli(app.clone(), status_arc.clone(), child_arc, ready_flag, token_arc, dev) {
+            if let Err(err) = Self::spawn_cli(
+                app.clone(),
+                status_arc.clone(),
+                child_arc,
+                ready_flag,
+                token_arc,
+                dev,
+            ) {
                 log_line(&format!("cli spawn failed: {err}"));
                 let mut locked = status_arc.lock();
                 locked.state = CliState::Error;
@@ -369,7 +416,9 @@ impl CliProcessManager {
 
         if !supports_user_shell() {
             if which::which(&resolution.node_binary).is_err() {
-                return Err(anyhow::anyhow!("Node binary not found. Make sure Node.js is installed."));
+                return Err(anyhow::anyhow!(
+                    "Node binary not found. Make sure Node.js is installed."
+                ));
             }
         }
 
@@ -420,7 +469,6 @@ impl CliProcessManager {
         let token_clone = bootstrap_token.clone();
 
         thread::spawn(move || {
-
             let stdout = child_clone
                 .lock()
                 .as_mut()
@@ -433,10 +481,24 @@ impl CliProcessManager {
                 .map(BufReader::new);
 
             if let Some(reader) = stdout {
-                Self::process_stream(reader, "stdout", &app_clone, &status_clone, &ready_clone, &token_clone);
+                Self::process_stream(
+                    reader,
+                    "stdout",
+                    &app_clone,
+                    &status_clone,
+                    &ready_clone,
+                    &token_clone,
+                );
             }
             if let Some(reader) = stderr {
-                Self::process_stream(reader, "stderr", &app_clone, &status_clone, &ready_clone, &token_clone);
+                Self::process_stream(
+                    reader,
+                    "stderr",
+                    &app_clone,
+                    &status_clone,
+                    &ready_clone,
+                    &token_clone,
+                );
             }
         });
 
@@ -464,13 +526,33 @@ impl CliProcessManager {
         let status_clone = status.clone();
         let app_clone = app.clone();
         thread::spawn(move || {
-            let code = {
-                let mut guard = child_holder.lock();
-                if let Some(child) = guard.as_mut() {
-                    child.wait().ok()
-                } else {
-                    None
+            // Do not hold the child mutex while waiting for process exit.
+            // Holding the lock across `wait()` deadlocks `stop()`, which needs the
+            // same lock to send SIGTERM/SIGKILL when the user quits the app.
+            let code = loop {
+                let maybe_exited = {
+                    let mut guard = child_holder.lock();
+                    if guard.is_none() {
+                        return;
+                    }
+                    match guard
+                        .as_mut()
+                        .and_then(|child| child.try_wait().ok().flatten())
+                    {
+                        Some(status) => {
+                            // Drop the handle after the process exits so other callers
+                            // don't attempt to stop/kill a finished process.
+                            *guard = None;
+                            Some(status)
+                        }
+                        None => None,
+                    }
+                };
+
+                if let Some(status) = maybe_exited {
+                    break Some(status);
                 }
+                thread::sleep(Duration::from_millis(100));
             };
 
             let mut locked = status_clone.lock();
@@ -489,8 +571,14 @@ impl CliProcessManager {
                 if locked.error.is_none() {
                     locked.error = err_msg.clone();
                 }
-                log_line(&format!("cli process exited before ready: {:?}", locked.error));
-                let _ = app_clone.emit("cli:error", json!({"message": locked.error.clone().unwrap_or_default()}));
+                log_line(&format!(
+                    "cli process exited before ready: {:?}",
+                    locked.error
+                ));
+                let _ = app_clone.emit(
+                    "cli:error",
+                    json!({"message": locked.error.clone().unwrap_or_default()}),
+                );
             } else {
                 locked.state = CliState::Stopped;
                 log_line("cli process stopped cleanly");
@@ -511,7 +599,7 @@ impl CliProcessManager {
         bootstrap_token: &Arc<Mutex<Option<String>>>,
     ) {
         let mut buffer = String::new();
-        let port_regex = Regex::new(r"CodeNomad Server is ready at http://[^:]+:(\d+)").ok();
+        let local_url_regex = Regex::new(r"^Local\s+Connection\s+URL\s*:\s*(https?://\S+)").ok();
         let http_regex = Regex::new(r":(\d{2,5})(?!.*:\d)").ok();
         let token_prefix = "CODENOMAD_BOOTSTRAP_TOKEN:";
 
@@ -539,12 +627,12 @@ impl CliProcessManager {
                             continue;
                         }
 
-                        if let Some(port) = port_regex
+                        if let Some(url) = local_url_regex
                             .as_ref()
                             .and_then(|re| re.captures(line).and_then(|c| c.get(1)))
-                            .and_then(|m| m.as_str().parse::<u16>().ok())
+                            .map(|m| m.as_str().to_string())
                         {
-                            Self::mark_ready(app, status, ready, bootstrap_token, port);
+                            Self::mark_ready(app, status, ready, bootstrap_token, url);
                             continue;
                         }
 
@@ -554,13 +642,25 @@ impl CliProcessManager {
                                 .and_then(|re| re.captures(line).and_then(|c| c.get(1)))
                                 .and_then(|m| m.as_str().parse::<u16>().ok())
                             {
-                                Self::mark_ready(app, status, ready, bootstrap_token, port);
+                                Self::mark_ready(
+                                    app,
+                                    status,
+                                    ready,
+                                    bootstrap_token,
+                                    format!("http://localhost:{port}"),
+                                );
                                 continue;
                             }
 
                             if let Ok(value) = serde_json::from_str::<serde_json::Value>(line) {
                                 if let Some(port) = value.get("port").and_then(|p| p.as_u64()) {
-                                    Self::mark_ready(app, status, ready, bootstrap_token, port as u16);
+                                    Self::mark_ready(
+                                        app,
+                                        status,
+                                        ready,
+                                        bootstrap_token,
+                                        format!("http://localhost:{}", port),
+                                    );
                                     continue;
                                 }
                             }
@@ -577,12 +677,15 @@ impl CliProcessManager {
         status: &Arc<Mutex<CliStatus>>,
         ready: &Arc<AtomicBool>,
         bootstrap_token: &Arc<Mutex<Option<String>>>,
-        port: u16,
+        base_url: String,
     ) {
         ready.store(true, Ordering::SeqCst);
-        let base_url = format!("http://127.0.0.1:{port}");
+        let port = Url::parse(&base_url)
+            .ok()
+            .and_then(|u| u.port_or_known_default())
+            .map(|p| p as u16);
         let mut locked = status.lock();
-        locked.port = Some(port);
+        locked.port = port;
         locked.url = Some(base_url.clone());
         locked.state = CliState::Ready;
         locked.error = None;
@@ -591,22 +694,29 @@ impl CliProcessManager {
         let token = bootstrap_token.lock().take();
 
         if let Some(token) = token {
-            match exchange_bootstrap_token(&base_url, &token) {
-                Ok(Some(session_id)) => {
-                    if let Err(err) = set_session_cookie(app, &base_url, &session_id) {
-                        log_line(&format!("failed to set session cookie: {err}"));
-                        navigate_main(app, &format!("{base_url}/login"));
-                    } else {
-                        navigate_main(app, &base_url);
+            // Token exchange is only implemented for loopback HTTP. If localUrl is HTTPS,
+            // skip the exchange and let the user authenticate normally.
+            let scheme = Url::parse(&base_url).ok().map(|u| u.scheme().to_string());
+            if scheme.as_deref() != Some("http") {
+                navigate_main(app, &base_url);
+            } else {
+                match exchange_bootstrap_token(&base_url, &token) {
+                    Ok(Some(session_id)) => {
+                        if let Err(err) = set_session_cookie(app, &base_url, &session_id) {
+                            log_line(&format!("failed to set session cookie: {err}"));
+                            navigate_main(app, &format!("{base_url}/login"));
+                        } else {
+                            navigate_main(app, &base_url);
+                        }
+                    }
+                    Ok(None) => {
+                        log_line("bootstrap token exchange failed (invalid token)");
+                        navigate_main(app, &format!("{base_url}/login"));
+                    }
+                    Err(err) => {
+                        log_line(&format!("bootstrap token exchange failed: {err}"));
+                        navigate_main(app, &format!("{base_url}/login"));
                     }
-                }
-                Ok(None) => {
-                    log_line("bootstrap token exchange failed (invalid token)");
-                    navigate_main(app, &format!("{base_url}/login"));
-                }
-                Err(err) => {
-                    log_line(&format!("bootstrap token exchange failed: {err}"));
-                    navigate_main(app, &format!("{base_url}/login"));
                 }
             }
         } else {
@@ -693,15 +803,25 @@ impl CliEntry {
             "serve".to_string(),
             "--host".to_string(),
             host.to_string(),
-            "--port".to_string(),
-            "0".to_string(),
             "--generate-token".to_string(),
         ];
+
         if dev {
+            // Dev: plain HTTP + Vite dev server proxy.
+            args.push("--https".to_string());
+            args.push("false".to_string());
+            args.push("--http".to_string());
+            args.push("true".to_string());
             args.push("--ui-dev-server".to_string());
             args.push("http://localhost:3000".to_string());
             args.push("--log-level".to_string());
             args.push("debug".to_string());
+        } else {
+            // Prod desktop: always keep loopback HTTP enabled.
+            args.push("--https".to_string());
+            args.push("true".to_string());
+            args.push("--http".to_string());
+            args.push("true".to_string());
         }
         args
     }
@@ -726,9 +846,10 @@ fn resolve_tsx(_app: &AppHandle) -> Option<String> {
         std::env::current_dir()
             .ok()
             .map(|p| p.join("node_modules/tsx/dist/cli.js")),
-        std::env::current_exe()
-            .ok()
-            .and_then(|ex| ex.parent().map(|p| p.join("../node_modules/tsx/dist/cli.js"))),
+        std::env::current_exe().ok().and_then(|ex| {
+            ex.parent()
+                .map(|p| p.join("../node_modules/tsx/dist/cli.js"))
+        }),
     ];
 
     first_existing(candidates)
@@ -751,7 +872,8 @@ fn resolve_dist_entry(_app: &AppHandle) -> Option<String> {
     let base = workspace_root();
     let mut candidates: Vec<Option<PathBuf>> = vec![
         base.as_ref().map(|p| p.join("packages/server/dist/bin.js")),
-        base.as_ref().map(|p| p.join("packages/server/dist/index.js")),
+        base.as_ref()
+            .map(|p| p.join("packages/server/dist/index.js")),
         base.as_ref().map(|p| p.join("server/dist/bin.js")),
         base.as_ref().map(|p| p.join("server/dist/index.js")),
     ];
@@ -766,7 +888,9 @@ fn resolve_dist_entry(_app: &AppHandle) -> Option<String> {
             candidates.push(Some(resources.join("resources/server/dist/bin.js")));
             candidates.push(Some(resources.join("resources/server/dist/index.js")));
             candidates.push(Some(resources.join("resources/server/dist/server/bin.js")));
-            candidates.push(Some(resources.join("resources/server/dist/server/index.js")));
+            candidates.push(Some(
+                resources.join("resources/server/dist/server/index.js"),
+            ));
 
             let linux_resource_roots = [dir.join("../lib/CodeNomad"), dir.join("../lib/codenomad")];
             for root in linux_resource_roots {
@@ -785,8 +909,10 @@ fn resolve_dist_entry(_app: &AppHandle) -> Option<String> {
     first_existing(candidates)
 }
 
-fn build_shell_command_string(entry: &CliEntry, cli_args: &[String]) -> anyhow::Result<ShellCommand> {
-
+fn build_shell_command_string(
+    entry: &CliEntry,
+    cli_args: &[String],
+) -> anyhow::Result<ShellCommand> {
     let shell = default_shell();
     let mut quoted: Vec<String> = Vec::new();
     quoted.push(shell_escape(&entry.node_binary));
@@ -817,7 +943,7 @@ fn shell_escape(input: &str) -> String {
         "''".to_string()
     } else if !input
         .chars()
-        .any(|c| matches!(c, ' ' | '"' | '\'' | '$' | '`' | '!' ))
+        .any(|c| matches!(c, ' ' | '"' | '\'' | '$' | '`' | '!'))
     {
         input.to_string()
     } else {

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

@@ -4,6 +4,7 @@ mod cli_manager;
 
 use cli_manager::{CliProcessManager, CliStatus};
 use serde_json::json;
+use std::sync::atomic::{AtomicBool, Ordering};
 use tauri::menu::{MenuBuilder, MenuItem, SubmenuBuilder};
 use tauri::plugin::{Builder as PluginBuilder, TauriPlugin};
 use tauri::webview::Webview;
@@ -11,6 +12,8 @@ use tauri::{AppHandle, Emitter, Manager, Runtime, Wry};
 use tauri_plugin_opener::OpenerExt;
 use url::Url;
 
+static QUIT_REQUESTED: AtomicBool = AtomicBool::new(false);
+
 #[derive(Clone)]
 pub struct AppState {
     pub manager: CliProcessManager,
@@ -32,6 +35,7 @@ fn cli_restart(app: AppHandle, state: tauri::State<AppState>) -> Result<CliStatu
     Ok(state.manager.status())
 }
 
+
 fn is_dev_mode() -> bool {
     cfg!(debug_assertions) || std::env::var("TAURI_DEV").is_ok()
 }
@@ -39,7 +43,10 @@ fn is_dev_mode() -> bool {
 fn should_allow_internal(url: &Url) -> bool {
     match url.scheme() {
         "tauri" | "asset" | "file" => true,
-        "http" | "https" => matches!(url.host_str(), Some("127.0.0.1" | "localhost")),
+        // On Windows/WebView2, Tauri serves the app assets from `tauri.localhost`.
+        // This must be treated as an internal origin or the navigation guard will
+        // redirect it to the system browser and the app will appear blank.
+        "http" | "https" => matches!(url.host_str(), Some("127.0.0.1" | "localhost" | "tauri.localhost")),
         _ => false,
     }
 }
@@ -67,6 +74,8 @@ fn main() {
     tauri::Builder::default()
         .plugin(tauri_plugin_dialog::init())
         .plugin(tauri_plugin_opener::init())
+        .plugin(tauri_plugin_keepawake::init())
+        .plugin(tauri_plugin_notification::init())
         .plugin(navigation_guard)
         .manage(AppState {
             manager: CliProcessManager::new(),
@@ -164,6 +173,11 @@ fn main() {
         .expect("error while building tauri application")
         .run(|app_handle, event| match event {
             tauri::RunEvent::ExitRequested { api, .. } => {
+                // `app_handle.exit(0)` triggers another `ExitRequested`. Without a guard, we can
+                // prevent exit forever and the app never quits (Cmd+Q / Quit menu appears stuck).
+                if QUIT_REQUESTED.swap(true, Ordering::SeqCst) {
+                    return;
+                }
                 api.prevent_exit();
                 let app = app_handle.clone();
                 std::thread::spawn(move || {
@@ -178,6 +192,9 @@ fn main() {
                 ..
             } => {
                 // Ensure we have time to stop the CLI process before the app exits.
+                if QUIT_REQUESTED.swap(true, Ordering::SeqCst) {
+                    return;
+                }
                 api.prevent_close();
                 let app = app_handle.clone();
                 std::thread::spawn(move || {

packages/ui/.gitignore

@@ -1,3 +1,5 @@
 node_modules/
 dist/
 .vite/
+src/renderer/public/logo.png
+src/renderer/public/monaco/

packages/ui/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@codenomad/ui",
-  "version": "0.9.2",
+  "version": "0.10.3",
   "private": true,
+  "license": "MIT",
   "type": "module",
   "scripts": {
     "dev": "vite dev",
@@ -17,22 +18,28 @@
     "@suid/icons-material": "^0.9.0",
     "@suid/material": "^0.19.0",
     "@suid/system": "^0.14.0",
+    "@tauri-apps/plugin-opener": "^2.5.3",
+    "@tauri-apps/plugin-notification": "^2.3.3",
     "ansi-sequence-parser": "^1.1.3",
     "debug": "^4.4.3",
     "github-markdown-css": "^5.8.1",
     "lucide-solid": "^0.300.0",
     "marked": "^12.0.0",
+    "monaco-editor": "^0.52.2",
     "qrcode": "^1.5.3",
     "shiki": "^3.13.0",
     "solid-js": "^1.8.0",
-    "solid-toast": "^0.5.0"
+    "solid-toast": "^0.5.0",
+    "tauri-plugin-keepawake-api": "^0.1.0"
   },
   "devDependencies": {
+    "@vite-pwa/assets-generator": "^1.0.2",
     "autoprefixer": "10.4.21",
     "postcss": "8.5.6",
     "tailwindcss": "3",
     "typescript": "^5.3.0",
     "vite": "^5.0.0",
+    "vite-plugin-pwa": "^1.2.0",
     "vite-plugin-solid": "^2.10.0"
   }
 }

packages/ui/scripts/monaco-public-assets.d.ts

@@ -0,0 +1,7 @@
+export type CopyMonacoPublicAssetsParams = {
+  uiRendererRoot: string
+  warn?: (message: string) => void
+  sourceRoots?: string[]
+}
+
+export function copyMonacoPublicAssets(params: CopyMonacoPublicAssetsParams): void

packages/ui/scripts/monaco-public-assets.js

@@ -0,0 +1,97 @@
+import fs from "fs"
+import { resolve } from "path"
+
+/**
+ * Copy Monaco's AMD `min/vs` assets into the UI renderer public folder.
+ *
+ * Monaco is loaded at runtime via `/monaco/vs/loader.js`. These assets are gitignored
+ * and generated on demand in dev/build so the repo stays clean.
+ *
+ * @param {object} params
+ * @param {string} params.uiRendererRoot Absolute path to `packages/ui/src/renderer`.
+ * @param {(message: string) => void} [params.warn] Warning logger.
+ * @param {string[]} [params.sourceRoots] Optional override list of `.../monaco-editor/min/vs` roots.
+ */
+export function copyMonacoPublicAssets(params) {
+  const uiRendererRoot = params?.uiRendererRoot
+  if (!uiRendererRoot) {
+    throw new Error("copyMonacoPublicAssets: uiRendererRoot is required")
+  }
+
+  const warn = params?.warn ?? ((message) => console.warn(message))
+  const publicDir = resolve(uiRendererRoot, "public")
+  const destRoot = resolve(publicDir, "monaco/vs")
+
+  const candidates =
+    params?.sourceRoots?.length > 0
+      ? params.sourceRoots
+      : [
+          // Workspace root hoisted deps.
+          resolve(process.cwd(), "node_modules/monaco-editor/min/vs"),
+          // UI package local deps (covers non-hoisted installs).
+          resolve(process.cwd(), "packages/ui/node_modules/monaco-editor/min/vs"),
+        ]
+
+  const sourceRoot = candidates.find((p) => fs.existsSync(resolve(p, "loader.js")))
+  if (!sourceRoot) {
+    warn("Monaco source directory not found; skipping copy")
+    return
+  }
+
+  const copyRecursive = (src, dest) => {
+    const stat = fs.statSync(src)
+    if (stat.isDirectory()) {
+      fs.mkdirSync(dest, { recursive: true })
+      for (const entry of fs.readdirSync(src)) {
+        copyRecursive(resolve(src, entry), resolve(dest, entry))
+      }
+      return
+    }
+    fs.copyFileSync(src, dest)
+  }
+
+  // Keep the working tree clean; these assets are generated.
+  try {
+    fs.rmSync(destRoot, { recursive: true, force: true })
+  } catch {
+    // ignore
+  }
+  fs.mkdirSync(destRoot, { recursive: true })
+
+  // Copy core Monaco runtime.
+  for (const dir of ["base", "editor", "platform"]) {
+    const src = resolve(sourceRoot, dir)
+    if (fs.existsSync(src)) {
+      copyRecursive(src, resolve(destRoot, dir))
+    }
+  }
+
+  // loader.js is required.
+  copyRecursive(resolve(sourceRoot, "loader.js"), resolve(destRoot, "loader.js"))
+
+  // Copy baseline rich language packages + workers.
+  for (const lang of ["typescript", "html", "json", "css"]) {
+    const src = resolve(sourceRoot, "language", lang)
+    if (fs.existsSync(src)) {
+      copyRecursive(src, resolve(destRoot, "language", lang))
+    }
+  }
+
+  // Copy baseline basic tokenizers.
+  for (const lang of ["python", "markdown", "cpp", "kotlin"]) {
+    const src = resolve(sourceRoot, "basic-languages", lang)
+    if (fs.existsSync(src)) {
+      copyRecursive(src, resolve(destRoot, "basic-languages", lang))
+    }
+  }
+
+  // Copy monaco.contribution.js entrypoints (needed by some loads).
+  const monacoContribution = resolve(sourceRoot, "basic-languages", "monaco.contribution.js")
+  if (fs.existsSync(monacoContribution)) {
+    copyRecursive(monacoContribution, resolve(destRoot, "basic-languages", "monaco.contribution.js"))
+  }
+  const underscoreContribution = resolve(sourceRoot, "basic-languages", "_.contribution.js")
+  if (fs.existsSync(underscoreContribution)) {
+    copyRecursive(underscoreContribution, resolve(destRoot, "basic-languages", "_.contribution.js"))
+  }
+}

packages/ui/src/App.tsx

@@ -19,6 +19,7 @@ import { getLogger } from "./lib/logger"
 import { initReleaseNotifications } from "./stores/releases"
 import { runtimeEnv } from "./lib/runtime-env"
 import { useI18n } from "./lib/i18n"
+import { setWakeLockDesired } from "./lib/native/wake-lock"
 import {
   hasInstances,
   isSelectingFolder,
@@ -48,6 +49,8 @@ import {
   updateSessionModel,
 } from "./stores/sessions"
 
+import { getInstanceSessionIndicatorStatus } from "./stores/session-status"
+
 const log = getLogger("actions")
 
 const App: Component = () => {
@@ -57,9 +60,11 @@ const App: Component = () => {
     preferences,
     recordWorkspaceLaunch,
     toggleShowThinkingBlocks,
+    toggleKeyboardShortcutHints,
     toggleShowTimelineTools,
     toggleAutoCleanupBlankSessions,
     toggleUsageMetrics,
+    togglePromptSubmitOnEnter,
     setDiffViewMode,
     setToolOutputExpansion,
     setDiagnosticsExpansion,
@@ -76,6 +81,13 @@ const App: Component = () => {
   const [remoteAccessOpen, setRemoteAccessOpen] = createSignal(false)
   const [instanceTabBarHeight, setInstanceTabBarHeight] = createSignal(0)
 
+  createEffect(() => {
+    if (typeof document === "undefined") return
+    const shouldShow =
+      runtimeEnv.host !== "web" && runtimeEnv.platform !== "mobile" && (preferences().showKeyboardShortcutHints ?? true)
+    document.documentElement.dataset.keyboardHints = shouldShow ? "show" : "hide"
+  })
+
   const updateInstanceTabBarHeight = () => {
     if (typeof document === "undefined") return
     const element = document.querySelector<HTMLElement>(".tab-bar-instance")
@@ -90,6 +102,26 @@ const App: Component = () => {
     initReleaseNotifications()
   })
 
+  const shouldHoldWakeLock = createMemo(() => {
+    const map = instances()
+    for (const id of map.keys()) {
+      const status = getInstanceSessionIndicatorStatus(id)
+      if (status !== "idle") {
+        return true
+      }
+    }
+    return false
+  })
+
+  createEffect(() => {
+    const hold = shouldHoldWakeLock()
+    void setWakeLockDesired(hold)
+  })
+
+  onCleanup(() => {
+    void setWakeLockDesired(false)
+  })
+
   createEffect(() => {
     instances()
     hasInstances()
@@ -269,8 +301,10 @@ const App: Component = () => {
     preferences,
     toggleAutoCleanupBlankSessions,
     toggleShowThinkingBlocks,
+    toggleKeyboardShortcutHints,
     toggleShowTimelineTools,
     toggleUsageMetrics,
+    togglePromptSubmitOnEnter,
     setDiffViewMode,
     setToolOutputExpansion,
     setDiagnosticsExpansion,
@@ -329,32 +363,34 @@ const App: Component = () => {
       <Dialog open={Boolean(launchError())} modal>
         <Dialog.Portal>
           <Dialog.Overlay class="modal-overlay" />
-          <div class="fixed inset-0 z-50 flex items-center justify-center p-4">
-            <Dialog.Content class="modal-surface w-full max-w-md p-6 flex flex-col gap-6">
-              <div>
-                <Dialog.Title class="text-xl font-semibold text-primary">{t("app.launchError.title")}</Dialog.Title>
-                <Dialog.Description class="text-sm text-secondary mt-2 break-words">
-                  {t("app.launchError.description")}
-                </Dialog.Description>
-              </div>
+           <div class="fixed inset-0 z-50 flex items-center justify-center p-4">
+             <Dialog.Content class="modal-surface w-full max-w-3xl p-6 flex flex-col gap-6 max-h-[80vh] min-h-0 overflow-hidden">
+               <div>
+                 <Dialog.Title class="text-xl font-semibold text-primary">{t("app.launchError.title")}</Dialog.Title>
+                 <Dialog.Description class="text-sm text-secondary mt-2 break-words">
+                   {t("app.launchError.description")}
+                 </Dialog.Description>
+               </div>
 
-              <div class="rounded-lg border border-base bg-surface-secondary p-4">
-                <p class="text-xs font-medium text-muted uppercase tracking-wide mb-1">{t("app.launchError.binaryPathLabel")}</p>
-                <p class="text-sm font-mono text-primary break-all">{launchErrorPath()}</p>
-              </div>
+               <div class={`flex flex-col gap-4 ${launchErrorMessage() ? "flex-1 min-h-0" : ""}`}>
+                 <div class="rounded-lg border border-base bg-surface-secondary p-4 flex-shrink-0">
+                   <p class="text-xs font-medium text-muted uppercase tracking-wide mb-1">{t("app.launchError.binaryPathLabel")}</p>
+                   <p class="text-sm font-mono text-primary break-all">{launchErrorPath()}</p>
+                 </div>
+ 
+                 <Show when={launchErrorMessage()}>
+                   <div class="rounded-lg border border-base bg-surface-secondary p-4 flex flex-col gap-2 flex-1 min-h-0">
+                     <p class="text-xs font-medium text-muted uppercase tracking-wide">{t("app.launchError.errorOutputLabel")}</p>
+                     <pre class="text-sm font-mono text-primary whitespace-pre-wrap break-words overflow-auto flex-1 min-h-0">{launchErrorMessage()}</pre>
+                   </div>
+                 </Show>
+               </div>
 
-              <Show when={launchErrorMessage()}>
-                <div class="rounded-lg border border-base bg-surface-secondary p-4">
-                  <p class="text-xs font-medium text-muted uppercase tracking-wide mb-1">{t("app.launchError.errorOutputLabel")}</p>
-                  <pre class="text-sm font-mono text-primary whitespace-pre-wrap break-words max-h-48 overflow-y-auto">{launchErrorMessage()}</pre>
-                </div>
-              </Show>
-
-              <div class="flex justify-end gap-2">
-                <Show when={launchError()?.missingBinary}>
-                  <button
-                    type="button"
-                    class="selector-button selector-button-secondary"
+               <div class="flex justify-end gap-2">
+                 <Show when={launchError()?.missingBinary}>
+                   <button
+                     type="button"
+                     class="selector-button selector-button-secondary"
                     onClick={handleLaunchErrorAdvanced}
                   >
                     {t("app.launchError.openAdvancedSettings")}

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

@@ -5,7 +5,6 @@ import { ChevronDown } from "lucide-solid"
 import type { Agent } from "../types/session"
 import { useI18n } from "../lib/i18n"
 import { getLogger } from "../lib/logger"
-import Kbd from "./kbd"
 const log = getLogger("session")
 
 
@@ -113,9 +112,6 @@ export default function AgentSelector(props: AgentSelectorProps) {
               )}
             </Select.Value>
           </div>
-          <span class="selector-trigger-hint selector-trigger-hint--top" aria-hidden="true">
-            <Kbd shortcut="cmd+shift+a" />
-          </span>
           <Select.Icon class="selector-trigger-icon">
             <ChevronDown class="w-3 h-3" />
           </Select.Icon>

packages/ui/src/components/code-block-inline.tsx

@@ -55,7 +55,7 @@ export function CodeBlockInline(props: CodeBlockInlineProps) {
 
       const highlighted = highlighter.codeToHtml(props.code, {
         lang: props.language as CodeToHtmlOptions["lang"],
-        theme: isDark() ? "github-dark" : "github-light",
+        theme: isDark() ? "github-dark" : "github-light-high-contrast",
       })
       setHtml(highlighted)
     } catch {

packages/ui/src/components/command-palette.tsx

@@ -112,6 +112,10 @@ const CommandPalette: Component<CommandPaletteProps> = (props) => {
 
   const groupedCommandList = () => processedCommands().groups
   const orderedCommands = () => processedCommands().ordered
+
+  const isCommandDisabled = (command: Command) => {
+    return command.disabled ? Boolean(resolveResolvable(command.disabled)) : false
+  }
   const selectedIndex = createMemo(() => {
     const ordered = orderedCommands()
     if (ordered.length === 0) return -1
@@ -138,10 +142,11 @@ const CommandPalette: Component<CommandPaletteProps> = (props) => {
       }
       return
     }
- 
+
     const currentId = selectedCommandId()
     if (!currentId || !ordered.some((cmd) => cmd.id === currentId)) {
-      setSelectedCommandId(ordered[0].id)
+      const firstEnabled = ordered.find((cmd) => !isCommandDisabled(cmd))
+      setSelectedCommandId((firstEnabled || ordered[0])?.id ?? null)
     }
   })
 
@@ -195,12 +200,14 @@ const CommandPalette: Component<CommandPaletteProps> = (props) => {
       if (index < 0 || index >= ordered.length) return
       const command = ordered[index]
       if (!command) return
+      if (isCommandDisabled(command)) return
       props.onExecute(command)
       props.onClose()
     }
   }
 
   function handleCommandClick(command: Command) {
+    if (isCommandDisabled(command)) return
     props.onExecute(command)
     props.onClose()
   }
@@ -265,11 +272,13 @@ const CommandPalette: Component<CommandPaletteProps> = (props) => {
                       <For each={group.commands}>
                         {(command, localIndex) => {
                           const commandIndex = group.startIndex + localIndex()
+                          const disabled = isCommandDisabled(command)
                           return (
                             <button
                               type="button"
                               data-command-index={commandIndex}
                               onClick={() => handleCommandClick(command)}
+                              disabled={disabled}
                               class={`modal-item ${selectedCommandId() === command.id ? "modal-item-highlight" : ""}`}
                               onPointerMove={(event) => {
                                 if (event.movementX === 0 && event.movementY === 0) return

packages/ui/src/components/file-viewer/monaco-diff-viewer.tsx

@@ -0,0 +1,116 @@
+import { createEffect, createSignal, onCleanup, onMount } from "solid-js"
+import { loadMonaco } from "../../lib/monaco/setup"
+import { getOrCreateTextModel } from "../../lib/monaco/model-cache"
+import { inferMonacoLanguageId } from "../../lib/monaco/language"
+import { ensureMonacoLanguageLoaded } from "../../lib/monaco/setup"
+import { useTheme } from "../../lib/theme"
+
+interface MonacoDiffViewerProps {
+  scopeKey: string
+  path: string
+  before: string
+  after: string
+  viewMode?: "split" | "unified"
+  contextMode?: "expanded" | "collapsed"
+}
+
+export function MonacoDiffViewer(props: MonacoDiffViewerProps) {
+  const { isDark } = useTheme()
+  let host: HTMLDivElement | undefined
+
+  let diffEditor: any = null
+  let monaco: any = null
+  const [ready, setReady] = createSignal(false)
+
+  const disposeEditor = () => {
+    try {
+      diffEditor?.setModel(null as any)
+    } catch {
+      // ignore
+    }
+    try {
+      diffEditor?.dispose()
+    } catch {
+      // ignore
+    }
+    diffEditor = null
+  }
+
+  onMount(() => {
+    let cancelled = false
+    void (async () => {
+      monaco = await loadMonaco()
+      if (cancelled) return
+      if (!host || !monaco) return
+
+      monaco.editor.setTheme(isDark() ? "vs-dark" : "vs")
+      diffEditor = monaco.editor.createDiffEditor(host, {
+        readOnly: true,
+        automaticLayout: true,
+        renderSideBySide: true,
+        renderSideBySideInlineBreakpoint: 0,
+        renderMarginRevertIcon: false,
+        minimap: { enabled: false },
+        scrollBeyondLastLine: false,
+        renderWhitespace: "selection",
+        fontSize: 13,
+        wordWrap: "off",
+        glyphMargin: false,
+        folding: false,
+        // Keep enough gutter space so unified diffs don't overlap `+`/`-` markers.
+        lineNumbersMinChars: 4,
+        lineDecorationsWidth: 12,
+      })
+
+      setReady(true)
+    })()
+
+    onCleanup(() => {
+      cancelled = true
+      setReady(false)
+      disposeEditor()
+    })
+  })
+
+  createEffect(() => {
+    if (!ready() || !monaco || !diffEditor) return
+    monaco.editor.setTheme(isDark() ? "vs-dark" : "vs")
+  })
+
+  createEffect(() => {
+    if (!ready() || !monaco || !diffEditor) return
+    const viewMode = props.viewMode === "unified" ? "unified" : "split"
+    const contextMode = props.contextMode === "collapsed" ? "collapsed" : "expanded"
+
+    diffEditor.updateOptions({
+      renderSideBySide: viewMode === "split",
+      renderSideBySideInlineBreakpoint: 0,
+      hideUnchangedRegions:
+        contextMode === "collapsed"
+          ? { enabled: true }
+          : { enabled: false },
+    })
+  })
+
+  createEffect(() => {
+    if (!ready() || !monaco || !diffEditor) return
+    const languageId = inferMonacoLanguageId(monaco, props.path)
+    const beforeKey = `${props.scopeKey}:diff:${props.path}:before`
+    const afterKey = `${props.scopeKey}:diff:${props.path}:after`
+
+    const original = getOrCreateTextModel({ monaco, cacheKey: beforeKey, value: props.before, languageId })
+    const modified = getOrCreateTextModel({ monaco, cacheKey: afterKey, value: props.after, languageId })
+    diffEditor.setModel({ original, modified })
+
+    void ensureMonacoLanguageLoaded(languageId).then(() => {
+      try {
+        monaco.editor.setModelLanguage(original, languageId)
+        monaco.editor.setModelLanguage(modified, languageId)
+      } catch {
+        // ignore
+      }
+    })
+  })
+
+  return <div class="monaco-viewer" ref={host} />
+}

packages/ui/src/components/file-viewer/monaco-file-viewer.tsx

@@ -0,0 +1,89 @@
+import { createEffect, createSignal, onCleanup, onMount } from "solid-js"
+import { loadMonaco } from "../../lib/monaco/setup"
+import { getOrCreateTextModel } from "../../lib/monaco/model-cache"
+import { inferMonacoLanguageId } from "../../lib/monaco/language"
+import { ensureMonacoLanguageLoaded } from "../../lib/monaco/setup"
+import { useTheme } from "../../lib/theme"
+
+interface MonacoFileViewerProps {
+  scopeKey: string
+  path: string
+  content: string
+}
+
+export function MonacoFileViewer(props: MonacoFileViewerProps) {
+  const { isDark } = useTheme()
+  let host: HTMLDivElement | undefined
+
+  let editor: any = null
+  let monaco: any = null
+  const [ready, setReady] = createSignal(false)
+
+  const disposeEditor = () => {
+    try {
+      editor?.setModel(null)
+    } catch {
+      // ignore
+    }
+    try {
+      editor?.dispose()
+    } catch {
+      // ignore
+    }
+    editor = null
+  }
+
+  onMount(() => {
+    let cancelled = false
+    void (async () => {
+      monaco = await loadMonaco()
+      if (cancelled) return
+      if (!host || !monaco) return
+
+      monaco.editor.setTheme(isDark() ? "vs-dark" : "vs")
+      editor = monaco.editor.create(host, {
+        value: "",
+        language: "plaintext",
+        readOnly: true,
+        automaticLayout: true,
+        lineNumbers: "on",
+        minimap: { enabled: false },
+        scrollBeyondLastLine: false,
+        wordWrap: "off",
+        renderWhitespace: "selection",
+        fontSize: 13,
+      })
+
+      setReady(true)
+    })()
+
+    onCleanup(() => {
+      cancelled = true
+      setReady(false)
+      disposeEditor()
+    })
+  })
+
+  createEffect(() => {
+    if (!ready() || !monaco || !editor) return
+    monaco.editor.setTheme(isDark() ? "vs-dark" : "vs")
+  })
+
+  createEffect(() => {
+    if (!ready() || !monaco || !editor) return
+    const languageId = inferMonacoLanguageId(monaco, props.path)
+    const cacheKey = `${props.scopeKey}:file:${props.path}`
+    const model = getOrCreateTextModel({ monaco, cacheKey, value: props.content, languageId })
+    editor.setModel(model)
+
+    void ensureMonacoLanguageLoaded(languageId).then(() => {
+      try {
+        monaco.editor.setModelLanguage(model, languageId)
+      } catch {
+        // ignore
+      }
+    })
+  })
+
+  return <div class="monaco-viewer" ref={host} />
+}

packages/ui/src/components/filesystem-browser-dialog.tsx

@@ -431,7 +431,7 @@ const FileSystemBrowserDialog: Component<FileSystemBrowserDialogProps> = (props)
               </Show>
             </div>
 
-            <div class="panel-footer">
+            <div class="panel-footer keyboard-hints">
               <div class="panel-footer-hints">
                 <div class="flex items-center gap-1.5">
                   <kbd class="kbd">↑</kbd>

packages/ui/src/components/folder-selection-view.tsx

@@ -5,6 +5,7 @@ import { useConfig } from "../stores/preferences"
 import AdvancedSettingsModal from "./advanced-settings-modal"
 import DirectoryBrowserDialog from "./directory-browser-dialog"
 import Kbd from "./kbd"
+import { ThemeModeToggle } from "./theme-mode-toggle"
 import { openNativeFolderDialog, supportsNativeDialogs } from "../lib/native/native-functions"
 import VersionPill from "./version-pill"
 import { DiscordSymbolIcon, GitHubMarkIcon } from "./brand-icons"
@@ -253,12 +254,63 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
 
 
   function getDisplayPath(path: string): string {
+    if (!path) return path
+
+    // macOS: /Users/<name>/...
     if (path.startsWith("/Users/")) {
       return path.replace(/^\/Users\/[^/]+/, "~")
     }
+
+    // Linux: /home/<name>/...
+    if (path.startsWith("/home/")) {
+      return path.replace(/^\/home\/[^/]+/, "~")
+    }
+
+    // Windows: C:\Users\<name>\... (and the forward-slash variant)
+    if (/^[A-Za-z]:\\Users\\/.test(path)) {
+      return path.replace(/^[A-Za-z]:\\Users\\[^\\]+/, "~")
+    }
+    if (/^[A-Za-z]:\/Users\//.test(path)) {
+      return path.replace(/^[A-Za-z]:\/Users\/[^/]+/, "~")
+    }
+
     return path
   }
 
+  function looksLikeWindowsPath(value: string): boolean {
+    if (!value) return false
+    // Drive letter (C:\...) or UNC (\\server\share\...)
+    return /^[A-Za-z]:[\\/]/.test(value) || /^\\\\[^\\]+\\[^\\]+/.test(value)
+  }
+
+  function splitFolderPath(rawPath: string): { baseName: string; dirName: string } {
+    if (!rawPath) return { baseName: "", dirName: "" }
+
+    const isWindows = looksLikeWindowsPath(rawPath)
+    const trimmed = rawPath.replace(/[\\/]+$/, "")
+
+    // Root edge-cases ("/", "C:\\", "\\\\server\\share\\")
+    if (!trimmed) {
+      return { baseName: rawPath, dirName: "" }
+    }
+
+    if (isWindows && /^[A-Za-z]:$/.test(trimmed)) {
+      return { baseName: `${trimmed}\\`, dirName: "" }
+    }
+
+    const lastSlash = trimmed.lastIndexOf("/")
+    const lastBackslash = isWindows ? trimmed.lastIndexOf("\\") : -1
+    const lastSep = Math.max(lastSlash, lastBackslash)
+
+    if (lastSep < 0) {
+      return { baseName: trimmed, dirName: "" }
+    }
+
+    const baseName = trimmed.slice(lastSep + 1) || trimmed
+    const dirName = trimmed.slice(0, lastSep)
+    return { baseName, dirName }
+  }
+
   return (
     <>
       <div
@@ -313,8 +365,9 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
               </Select.Portal>
             </Select>
           </div>
-          <Show when={props.onOpenRemoteAccess}>
-            <div class="absolute top-4 right-6">
+          <div class="absolute top-4 right-6 flex items-center gap-2">
+            <ThemeModeToggle class="selector-button selector-button-secondary w-auto p-2 inline-flex items-center justify-center" />
+            <Show when={props.onOpenRemoteAccess}>
               <button
                 type="button"
                 class="selector-button selector-button-secondary w-auto p-2 inline-flex items-center justify-center"
@@ -322,8 +375,8 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
               >
                 <MonitorUp class="w-4 h-4" />
               </button>
-            </div>
-          </Show>
+            </Show>
+          </div>
           <div class="mb-6 text-center shrink-0">
             <div class="mb-3 flex justify-center">
               <img src={codeNomadLogo} alt={t("folderSelection.logoAlt")} class="h-32 w-auto sm:h-48" loading="lazy" />
@@ -439,14 +492,14 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
                                   <div class="flex items-center gap-2 mb-1">
                                     <Folder class="w-4 h-4 flex-shrink-0 icon-muted" />
                                     <span class="text-sm font-medium truncate text-primary">
-                                      {folder.path.split("/").pop()}
+                                      {splitFolderPath(folder.path).baseName}
                                     </span>
                                   </div>
-                                  <div class="text-xs font-mono truncate pl-6 text-muted">
-                                    {getDisplayPath(folder.path)}
-                                  </div>
-                                  <div class="text-xs mt-1 pl-6 text-muted">
-                                    {formatRelativeTime(folder.lastAccessed)}
+                                  <div class="flex items-center gap-2 pl-6 text-xs text-muted min-w-0">
+                                    <span class="font-mono truncate-start flex-1 min-w-0">
+                                      {getDisplayPath(folder.path)}
+                                    </span>
+                                    <span class="flex-shrink-0">{formatRelativeTime(folder.lastAccessed)}</span>
                                   </div>
                                 </div>
                                 <Show when={focusMode() === "recent" && selectedIndex() === index()}>
@@ -495,7 +548,7 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
                           : t("folderSelection.browse.button")}
                       </span>
                     </div>
-                    <Kbd shortcut="cmd+n" class="ml-2" />
+                    <Kbd shortcut="cmd+n" class="ml-2 kbd-hint" />
                   </button>
                 </div>
 
@@ -520,7 +573,7 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
 
             </div>
 
-            <div class="panel panel-footer shrink-0 hidden sm:block">
+            <div class="panel panel-footer shrink-0 hidden sm:block keyboard-hints">
               <div class="panel-footer-hints">
                 <Show when={folders().length > 0}>
                   <div class="flex items-center gap-1.5">
@@ -538,7 +591,7 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
                   </div>
                 </Show>
                 <div class="flex items-center gap-1.5">
-                  <Kbd shortcut="cmd+n" />
+                  <Kbd shortcut="cmd+n" class="kbd-hint" />
                   <span>{t("folderSelection.hints.browse")}</span>
                 </div>
               </div>

packages/ui/src/components/hint-row.tsx

@@ -3,10 +3,15 @@ import { Component, JSX } from "solid-js"
 interface HintRowProps {
   children: JSX.Element
   class?: string
+  ariaHidden?: boolean
 }
 
 const HintRow: Component<HintRowProps> = (props) => {
-  return <span class={`text-xs text-muted ${props.class || ""}`}>{props.children}</span>
+  return (
+    <span aria-hidden={props.ariaHidden} class={`keyboard-hints text-xs text-muted ${props.class || ""}`}>
+      {props.children}
+    </span>
+  )
 }
 
 export default HintRow

packages/ui/src/components/instance-tab.tsx

@@ -11,20 +11,11 @@ interface InstanceTabProps {
   onClose: () => void
 }
 
-function formatFolderName(path: string, instances: Instance[], currentInstance: Instance): string {
-  const name = path.split("/").pop() || path
-
-  const duplicates = instances.filter((i) => {
-    const iName = i.folder.split("/").pop() || i.folder
-    return iName === name
-  })
-
-  if (duplicates.length > 1) {
-    const index = duplicates.findIndex((i) => i.id === currentInstance.id)
-    return `~/${name} (${index + 1})`
-  }
-
-  return `~/${name}`
+function getPathBasename(path: string): string {
+  // Instance folders can be POSIX-like (/Users/...) on macOS/Linux or Windows-like (C:\Users\...).
+  // Normalize by trimming trailing separators and then splitting on both '/' and '\\'.
+  const normalized = path.replace(/[\\/]+$/, "")
+  return normalized.split(/[\\/]/).pop() || path
 }
 
 const InstanceTab: Component<InstanceTabProps> = (props) => {
@@ -58,7 +49,7 @@ const InstanceTab: Component<InstanceTabProps> = (props) => {
       >
         <FolderOpen class="w-4 h-4 flex-shrink-0" />
         <span class="tab-label">
-          {props.instance.folder.split("/").pop() || props.instance.folder}
+          {getPathBasename(props.instance.folder)}
         </span>
         <span
           class={`status-indicator session-status ml-auto ${statusClassName()}`}

packages/ui/src/components/instance-tabs.tsx

@@ -1,10 +1,15 @@
-import { Component, For, Show } from "solid-js"
+import { Component, For, Show, createMemo, createSignal } from "solid-js"
+import { Dynamic } from "solid-js/web"
 import type { Instance } from "../types/instance"
 import InstanceTab from "./instance-tab"
 import KeyboardHint from "./keyboard-hint"
-import { Plus, MonitorUp } from "lucide-solid"
+import { Plus, MonitorUp, Bell, BellOff } from "lucide-solid"
 import { keyboardRegistry } from "../lib/keyboard-registry"
 import { useI18n } from "../lib/i18n"
+import { ThemeModeToggle } from "./theme-mode-toggle"
+import NotificationsSettingsModal from "./notifications-settings-modal"
+import { isOsNotificationSupportedSync } from "../lib/os-notifications"
+import { useConfig } from "../stores/preferences"
 
 interface InstanceTabsProps {
   instances: Map<string, Instance>
@@ -17,6 +22,21 @@ interface InstanceTabsProps {
 
 const InstanceTabs: Component<InstanceTabsProps> = (props) => {
   const { t } = useI18n()
+  const { preferences } = useConfig()
+  const [notificationsOpen, setNotificationsOpen] = createSignal(false)
+
+  const notificationsSupported = createMemo(() => isOsNotificationSupportedSync())
+  const notificationsEnabled = createMemo(() => Boolean(preferences().osNotificationsEnabled))
+  const notificationIcon = createMemo(() => {
+    if (!notificationsSupported()) return BellOff
+    return notificationsEnabled() ? Bell : BellOff
+  })
+
+  const notificationTitle = createMemo(() => {
+    if (!notificationsSupported()) return "Notifications unsupported"
+    return notificationsEnabled() ? "Notifications enabled" : "Notifications disabled"
+  })
+
   return (
     <div class="tab-bar tab-bar-instance">
       <div class="tab-container" role="tablist">
@@ -52,6 +72,17 @@ const InstanceTabs: Component<InstanceTabsProps> = (props) => {
                 />
               </div>
             </Show>
+            <ThemeModeToggle class="new-tab-button" />
+
+            <button
+              class={`new-tab-button ${!notificationsSupported() ? "opacity-50" : ""}`}
+              onClick={() => setNotificationsOpen(true)}
+              title={notificationTitle()}
+              aria-label={notificationTitle()}
+            >
+              <Dynamic component={notificationIcon()} class="w-4 h-4" />
+            </button>
+
             <Show when={Boolean(props.onOpenRemoteAccess)}>
               <button
                 class="new-tab-button tab-remote-button"
@@ -65,6 +96,8 @@ const InstanceTabs: Component<InstanceTabsProps> = (props) => {
           </div>
         </div>
       </div>
+
+      <NotificationsSettingsModal open={notificationsOpen()} onClose={() => setNotificationsOpen(false)} />
     </div>
 
   )

packages/ui/src/components/instance-welcome-view.tsx

@@ -502,7 +502,7 @@ const InstanceWelcomeView: Component<InstanceWelcomeViewProps> = (props) => {
                     )}
                     <span>{t("instanceWelcome.new.createButton")}</span>
                   </div>
-                  <Kbd shortcut={newSessionShortcutString()} class="ml-2" />
+                  <Kbd shortcut={newSessionShortcutString()} class="ml-2 kbd-hint" />
                 </button>
               </div>
             </div>
@@ -539,7 +539,7 @@ const InstanceWelcomeView: Component<InstanceWelcomeViewProps> = (props) => {
         </div>
       </Show>
 
-      <div class="panel-footer hidden sm:block">
+      <div class="panel-footer hidden sm:block keyboard-hints">
 
         <div class="panel-footer-hints">
           <div class="flex items-center gap-1.5">

packages/ui/src/components/instance/shell/SessionSidebar.tsx

@@ -0,0 +1,187 @@
+import { Show, type Accessor, type Component } from "solid-js"
+import type { SessionThread } from "../../../stores/session-state"
+import type { Session } from "../../../types/session"
+import { keyboardRegistry, type KeyboardShortcut } from "../../../lib/keyboard-registry"
+import type { DrawerViewState } from "./types"
+
+import { PlusSquare, Search } from "lucide-solid"
+import IconButton from "@suid/material/IconButton"
+import MenuOpenIcon from "@suid/icons-material/MenuOpen"
+import PushPinIcon from "@suid/icons-material/PushPin"
+import PushPinOutlinedIcon from "@suid/icons-material/PushPinOutlined"
+import InfoOutlinedIcon from "@suid/icons-material/InfoOutlined"
+
+import SessionList from "../../session-list"
+import KeyboardHint from "../../keyboard-hint"
+import WorktreeSelector from "../../worktree-selector"
+import AgentSelector from "../../agent-selector"
+import ModelSelector from "../../model-selector"
+import ThinkingSelector from "../../thinking-selector"
+import { getLogger } from "../../../lib/logger"
+
+const log = getLogger("session")
+
+interface SessionSidebarProps {
+  t: (key: string) => string
+  instanceId: string
+  threads: Accessor<SessionThread[]>
+  activeSessionId: Accessor<string | null>
+  activeSession: Accessor<Session | null>
+
+  showSearch: Accessor<boolean>
+  onToggleSearch: () => void
+
+  keyboardShortcuts: Accessor<KeyboardShortcut[]>
+  isPhoneLayout: Accessor<boolean>
+  drawerState: Accessor<DrawerViewState>
+  leftPinned: Accessor<boolean>
+
+  onSelectSession: (sessionId: string) => void
+  onNewSession: () => Promise<void> | void
+  onSidebarAgentChange: (sessionId: string, agent: string) => Promise<void>
+  onSidebarModelChange: (sessionId: string, model: { providerId: string; modelId: string }) => Promise<void>
+  onPinLeftDrawer: () => void
+  onUnpinLeftDrawer: () => void
+  onCloseLeftDrawer: () => void
+
+  setContentEl: (el: HTMLElement | null) => void
+}
+
+const SessionSidebar: Component<SessionSidebarProps> = (props) => (
+  <div class="flex flex-col h-full min-h-0" ref={props.setContentEl}>
+    <div class="flex flex-col gap-2 px-4 py-3 border-b border-base">
+      <div class="flex items-center justify-between gap-2">
+        <span class="session-sidebar-title text-sm font-semibold uppercase text-primary">
+          {props.t("instanceShell.leftPanel.sessionsTitle")}
+        </span>
+        <div class="flex items-center gap-2 text-primary">
+          <IconButton
+            size="small"
+            color="inherit"
+            aria-label={props.t("sessionList.actions.newSession.ariaLabel")}
+            title={props.t("sessionList.actions.newSession.title")}
+            onClick={() => {
+              const result = props.onNewSession()
+              if (result instanceof Promise) {
+                void result.catch((error) => log.error("Failed to create session:", error))
+              }
+            }}
+          >
+            <PlusSquare class="w-5 h-5" />
+          </IconButton>
+          <IconButton
+            size="small"
+            color="inherit"
+            aria-label={props.t("sessionList.filter.ariaLabel")}
+            title={props.t("sessionList.filter.ariaLabel")}
+            aria-pressed={props.showSearch()}
+            onClick={props.onToggleSearch}
+            sx={{
+              color: props.showSearch() ? "var(--text-primary)" : "inherit",
+              backgroundColor: props.showSearch() ? "var(--surface-hover)" : "transparent",
+              "&:hover": {
+                backgroundColor: "var(--surface-hover)",
+              },
+            }}
+          >
+            <Search class="w-5 h-5" />
+          </IconButton>
+          <IconButton
+            size="small"
+            color="inherit"
+            aria-label={props.t("instanceShell.leftPanel.instanceInfo")}
+            title={props.t("instanceShell.leftPanel.instanceInfo")}
+            onClick={() => props.onSelectSession("info")}
+          >
+            <InfoOutlinedIcon fontSize="small" />
+          </IconButton>
+          <Show when={!props.isPhoneLayout()}>
+            <IconButton
+              size="small"
+              color="inherit"
+              aria-label={props.leftPinned() ? props.t("instanceShell.leftDrawer.unpin") : props.t("instanceShell.leftDrawer.pin")}
+              onClick={() => (props.leftPinned() ? props.onUnpinLeftDrawer() : props.onPinLeftDrawer())}
+            >
+              {props.leftPinned() ? <PushPinIcon fontSize="small" /> : <PushPinOutlinedIcon fontSize="small" />}
+            </IconButton>
+          </Show>
+          <Show when={props.drawerState() === "floating-open"}>
+            <IconButton
+              size="small"
+              color="inherit"
+              aria-label={props.t("instanceShell.leftDrawer.toggle.close")}
+              title={props.t("instanceShell.leftDrawer.toggle.close")}
+              onClick={props.onCloseLeftDrawer}
+            >
+              <MenuOpenIcon fontSize="small" />
+            </IconButton>
+          </Show>
+        </div>
+      </div>
+      <div class="session-sidebar-shortcuts">
+        <Show when={props.keyboardShortcuts().length}>
+          <KeyboardHint shortcuts={props.keyboardShortcuts()} separator=" " showDescription={false} />
+        </Show>
+      </div>
+    </div>
+
+    <div class="session-sidebar flex flex-col flex-1 min-h-0">
+      <SessionList
+        instanceId={props.instanceId}
+        threads={props.threads()}
+        activeSessionId={props.activeSessionId()}
+        onSelect={props.onSelectSession}
+        onNew={() => {
+          const result = props.onNewSession()
+          if (result instanceof Promise) {
+            void result.catch((error) => log.error("Failed to create session:", error))
+          }
+        }}
+        enableFilterBar={props.showSearch()}
+        showHeader={false}
+        showFooter={false}
+      />
+
+      <div class="session-sidebar-separator" />
+      <Show when={props.activeSession()}>
+        {(activeSession) => (
+          <>
+            <div class="session-sidebar-controls px-4 py-4 border-t border-base flex flex-col gap-3">
+              <WorktreeSelector instanceId={props.instanceId} sessionId={activeSession().id} />
+
+              <AgentSelector
+                instanceId={props.instanceId}
+                sessionId={activeSession().id}
+                currentAgent={activeSession().agent}
+                onAgentChange={(agent) => props.onSidebarAgentChange(activeSession().id, agent)}
+              />
+
+              <ModelSelector
+                instanceId={props.instanceId}
+                sessionId={activeSession().id}
+                currentModel={activeSession().model}
+                onModelChange={(model) => props.onSidebarModelChange(activeSession().id, model)}
+              />
+
+              <ThinkingSelector instanceId={props.instanceId} currentModel={activeSession().model} />
+
+              <KeyboardHint
+                class="session-sidebar-selector-hints"
+                ariaHidden={true}
+                shortcuts={[
+                  keyboardRegistry.get("open-agent-selector"),
+                  keyboardRegistry.get("focus-model"),
+                  keyboardRegistry.get("focus-variant"),
+                ].filter((shortcut): shortcut is KeyboardShortcut => Boolean(shortcut))}
+                separator=" "
+                showDescription={false}
+              />
+            </div>
+          </>
+        )}
+      </Show>
+    </div>
+  </div>
+)
+
+export default SessionSidebar

packages/ui/src/components/instance/shell/right-panel/RightPanel.tsx

@@ -0,0 +1,829 @@
+import {
+  Show,
+  createEffect,
+  createMemo,
+  createSignal,
+  onCleanup,
+  type Accessor,
+  type Component,
+} from "solid-js"
+import type { ToolState } from "@opencode-ai/sdk"
+import type { FileContent, FileNode, File as GitFileStatus } from "@opencode-ai/sdk/v2/client"
+import IconButton from "@suid/material/IconButton"
+import MenuOpenIcon from "@suid/icons-material/MenuOpen"
+import PushPinIcon from "@suid/icons-material/PushPin"
+import PushPinOutlinedIcon from "@suid/icons-material/PushPinOutlined"
+
+import type { Instance } from "../../../../types/instance"
+import type { BackgroundProcess } from "../../../../../../server/src/api-types"
+import type { Session } from "../../../../types/session"
+import type { DrawerViewState } from "../types"
+import type { DiffContextMode, DiffViewMode, RightPanelTab } from "./types"
+
+import ChangesTab from "./tabs/ChangesTab"
+import FilesTab from "./tabs/FilesTab"
+import GitChangesTab from "./tabs/GitChangesTab"
+import StatusTab from "./tabs/StatusTab"
+
+import { getDefaultWorktreeSlug, getOrCreateWorktreeClient, getWorktreeSlugForSession } from "../../../../stores/worktrees"
+import { requestData } from "../../../../lib/opencode-api"
+import { buildUnifiedDiffFromSdkPatch, tryReverseApplyUnifiedDiff } from "../../../../lib/unified-diff-reverse"
+import { useGlobalPointerDrag } from "../useGlobalPointerDrag"
+import {
+  RIGHT_PANEL_CHANGES_DIFF_CONTEXT_MODE_KEY,
+  RIGHT_PANEL_CHANGES_DIFF_VIEW_MODE_KEY,
+  RIGHT_PANEL_CHANGES_LIST_OPEN_NONPHONE_KEY,
+  RIGHT_PANEL_CHANGES_LIST_OPEN_PHONE_KEY,
+  RIGHT_PANEL_CHANGES_SPLIT_WIDTH_KEY,
+  RIGHT_PANEL_FILES_LIST_OPEN_NONPHONE_KEY,
+  RIGHT_PANEL_FILES_LIST_OPEN_PHONE_KEY,
+  RIGHT_PANEL_FILES_SPLIT_WIDTH_KEY,
+  RIGHT_PANEL_GIT_CHANGES_LIST_OPEN_NONPHONE_KEY,
+  RIGHT_PANEL_GIT_CHANGES_LIST_OPEN_PHONE_KEY,
+  RIGHT_PANEL_GIT_CHANGES_SPLIT_WIDTH_KEY,
+  RIGHT_PANEL_TAB_STORAGE_KEY,
+  readStoredBool,
+  readStoredEnum,
+  readStoredPanelWidth,
+  readStoredRightPanelTab,
+} from "../storage"
+
+interface RightPanelProps {
+  t: (key: string, vars?: Record<string, any>) => string
+
+  instanceId: string
+  instance: Instance
+
+  activeSessionId: Accessor<string | null>
+  activeSession: Accessor<Session | null>
+  activeSessionDiffs: Accessor<any[] | undefined>
+
+  latestTodoState: Accessor<ToolState | null>
+  backgroundProcessList: Accessor<BackgroundProcess[]>
+  onOpenBackgroundOutput: (process: BackgroundProcess) => void
+  onStopBackgroundProcess: (processId: string) => Promise<void> | void
+  onTerminateBackgroundProcess: (processId: string) => Promise<void> | void
+
+  isPhoneLayout: Accessor<boolean>
+  rightDrawerWidth: Accessor<number>
+  rightDrawerWidthInitialized: Accessor<boolean>
+  rightDrawerState: Accessor<DrawerViewState>
+  rightPinned: Accessor<boolean>
+  onCloseRightDrawer: () => void
+  onPinRightDrawer: () => void
+  onUnpinRightDrawer: () => void
+
+  setContentEl: (el: HTMLElement | null) => void
+}
+
+const RightPanel: Component<RightPanelProps> = (props) => {
+  const [rightPanelTab, setRightPanelTab] = createSignal<RightPanelTab>(readStoredRightPanelTab("changes"))
+  const [rightPanelExpandedItems, setRightPanelExpandedItems] = createSignal<string[]>([
+    "plan",
+    "background-processes",
+    "mcp",
+    "lsp",
+    "plugins",
+  ])
+  const [selectedFile, setSelectedFile] = createSignal<string | null>(null)
+
+  const [browserPath, setBrowserPath] = createSignal(".")
+  const [browserEntries, setBrowserEntries] = createSignal<FileNode[] | null>(null)
+  const [browserLoading, setBrowserLoading] = createSignal(false)
+  const [browserError, setBrowserError] = createSignal<string | null>(null)
+  const [browserSelectedPath, setBrowserSelectedPath] = createSignal<string | null>(null)
+  const [browserSelectedContent, setBrowserSelectedContent] = createSignal<string | null>(null)
+  const [browserSelectedLoading, setBrowserSelectedLoading] = createSignal(false)
+  const [browserSelectedError, setBrowserSelectedError] = createSignal<string | null>(null)
+
+  const [diffViewMode, setDiffViewMode] = createSignal<DiffViewMode>(
+    readStoredEnum(RIGHT_PANEL_CHANGES_DIFF_VIEW_MODE_KEY, ["split", "unified"] as const) ?? "unified",
+  )
+  const [diffContextMode, setDiffContextMode] = createSignal<DiffContextMode>(
+    readStoredEnum(RIGHT_PANEL_CHANGES_DIFF_CONTEXT_MODE_KEY, ["expanded", "collapsed"] as const) ?? "collapsed",
+  )
+
+  const [changesSplitWidth, setChangesSplitWidth] = createSignal(320)
+  const [filesSplitWidth, setFilesSplitWidth] = createSignal(320)
+  const [gitChangesSplitWidth, setGitChangesSplitWidth] = createSignal(320)
+  const [activeSplitResize, setActiveSplitResize] = createSignal<"changes" | "git-changes" | "files" | null>(null)
+  const [splitResizeStartX, setSplitResizeStartX] = createSignal(0)
+  const [splitResizeStartWidth, setSplitResizeStartWidth] = createSignal(0)
+
+  const [filesListOpen, setFilesListOpen] = createSignal(true)
+  const [filesListTouched, setFilesListTouched] = createSignal(false)
+  const [changesListOpen, setChangesListOpen] = createSignal(true)
+  const [changesListTouched, setChangesListTouched] = createSignal(false)
+  const [gitChangesListOpen, setGitChangesListOpen] = createSignal(true)
+  const [gitChangesListTouched, setGitChangesListTouched] = createSignal(false)
+
+  const listLayoutKey = createMemo(() => (props.isPhoneLayout() ? "phone" : "nonphone"))
+
+  const listOpenStorageKey = (tab: "changes" | "git-changes" | "files") => {
+    const layout = listLayoutKey()
+    if (tab === "changes") {
+      return layout === "phone" ? RIGHT_PANEL_CHANGES_LIST_OPEN_PHONE_KEY : RIGHT_PANEL_CHANGES_LIST_OPEN_NONPHONE_KEY
+    }
+    if (tab === "git-changes") {
+      return layout === "phone"
+        ? RIGHT_PANEL_GIT_CHANGES_LIST_OPEN_PHONE_KEY
+        : RIGHT_PANEL_GIT_CHANGES_LIST_OPEN_NONPHONE_KEY
+    }
+    return layout === "phone" ? RIGHT_PANEL_FILES_LIST_OPEN_PHONE_KEY : RIGHT_PANEL_FILES_LIST_OPEN_NONPHONE_KEY
+  }
+
+  const persistListOpen = (tab: "changes" | "git-changes" | "files", value: boolean) => {
+    if (typeof window === "undefined") return
+    window.localStorage.setItem(listOpenStorageKey(tab), value ? "true" : "false")
+  }
+
+  createEffect(() => {
+    // Refresh persisted visibility when layout changes (phone vs non-phone).
+    const layout = listLayoutKey()
+    layout
+
+    const filesPersisted = readStoredBool(listOpenStorageKey("files"))
+    if (filesPersisted !== null) {
+      setFilesListOpen(filesPersisted)
+      setFilesListTouched(true)
+    } else {
+      setFilesListOpen(true)
+      setFilesListTouched(false)
+    }
+
+    const changesPersisted = readStoredBool(listOpenStorageKey("changes"))
+    if (changesPersisted !== null) {
+      setChangesListOpen(changesPersisted)
+      setChangesListTouched(true)
+    } else {
+      setChangesListOpen(true)
+      setChangesListTouched(false)
+    }
+
+    const gitPersisted = readStoredBool(listOpenStorageKey("git-changes"))
+    if (gitPersisted !== null) {
+      setGitChangesListOpen(gitPersisted)
+      setGitChangesListTouched(true)
+    } else {
+      setGitChangesListOpen(true)
+      setGitChangesListTouched(false)
+    }
+  })
+
+  createEffect(() => {
+    // Default behavior: when nothing is selected, keep the file list open.
+    // Once the user explicitly toggles it, we stop auto-opening.
+    if (rightPanelTab() !== "files") return
+    if (filesListTouched()) return
+    if (!browserSelectedPath()) {
+      setFilesListOpen(true)
+    }
+  })
+
+  createEffect(() => {
+    if (typeof window === "undefined") return
+    window.localStorage.setItem(RIGHT_PANEL_TAB_STORAGE_KEY, rightPanelTab())
+  })
+
+  createEffect(() => {
+    if (typeof window === "undefined") return
+    window.localStorage.setItem(RIGHT_PANEL_CHANGES_DIFF_VIEW_MODE_KEY, diffViewMode())
+  })
+
+  createEffect(() => {
+    if (typeof window === "undefined") return
+    window.localStorage.setItem(RIGHT_PANEL_CHANGES_DIFF_CONTEXT_MODE_KEY, diffContextMode())
+  })
+
+  const clampSplitWidth = (value: number) => {
+    const min = 200
+    const maxByDrawer = Math.max(min, Math.floor(props.rightDrawerWidth() * 0.65))
+    const max = Math.min(560, maxByDrawer)
+    return Math.min(max, Math.max(min, Math.floor(value)))
+  }
+
+  const [splitWidthsInitialized, setSplitWidthsInitialized] = createSignal(false)
+
+  createEffect(() => {
+    if (splitWidthsInitialized()) return
+    if (!props.rightDrawerWidthInitialized()) return
+    setSplitWidthsInitialized(true)
+    setChangesSplitWidth(clampSplitWidth(readStoredPanelWidth(RIGHT_PANEL_CHANGES_SPLIT_WIDTH_KEY, 320)))
+    setFilesSplitWidth(clampSplitWidth(readStoredPanelWidth(RIGHT_PANEL_FILES_SPLIT_WIDTH_KEY, 320)))
+    setGitChangesSplitWidth(clampSplitWidth(readStoredPanelWidth(RIGHT_PANEL_GIT_CHANGES_SPLIT_WIDTH_KEY, 320)))
+  })
+
+  const persistSplitWidth = (mode: "changes" | "git-changes" | "files", width: number) => {
+    if (typeof window === "undefined") return
+    const key =
+      mode === "changes"
+        ? RIGHT_PANEL_CHANGES_SPLIT_WIDTH_KEY
+        : mode === "git-changes"
+          ? RIGHT_PANEL_GIT_CHANGES_SPLIT_WIDTH_KEY
+          : RIGHT_PANEL_FILES_SPLIT_WIDTH_KEY
+    window.localStorage.setItem(key, String(width))
+  }
+
+  function stopSplitResize() {
+    setActiveSplitResize(null)
+    if (typeof document === "undefined") return
+    splitPointerDrag.stop()
+  }
+
+  function splitMouseMove(event: MouseEvent) {
+    const mode = activeSplitResize()
+    if (!mode) return
+    event.preventDefault()
+    const delta = event.clientX - splitResizeStartX()
+    const next = clampSplitWidth(splitResizeStartWidth() + delta)
+    if (mode === "changes") setChangesSplitWidth(next)
+    else if (mode === "git-changes") setGitChangesSplitWidth(next)
+    else setFilesSplitWidth(next)
+  }
+
+  function splitMouseUp() {
+    const mode = activeSplitResize()
+    if (mode) {
+      const width =
+        mode === "changes" ? changesSplitWidth() : mode === "git-changes" ? gitChangesSplitWidth() : filesSplitWidth()
+      persistSplitWidth(mode, width)
+    }
+    stopSplitResize()
+  }
+
+  function splitTouchMove(event: TouchEvent) {
+    const mode = activeSplitResize()
+    if (!mode) return
+    const touch = event.touches[0]
+    if (!touch) return
+    event.preventDefault()
+    const delta = touch.clientX - splitResizeStartX()
+    const next = clampSplitWidth(splitResizeStartWidth() + delta)
+    if (mode === "changes") setChangesSplitWidth(next)
+    else if (mode === "git-changes") setGitChangesSplitWidth(next)
+    else setFilesSplitWidth(next)
+  }
+
+  function splitTouchEnd() {
+    const mode = activeSplitResize()
+    if (mode) {
+      const width =
+        mode === "changes" ? changesSplitWidth() : mode === "git-changes" ? gitChangesSplitWidth() : filesSplitWidth()
+      persistSplitWidth(mode, width)
+    }
+    stopSplitResize()
+  }
+
+  const splitPointerDrag = useGlobalPointerDrag({
+    onMouseMove: splitMouseMove,
+    onMouseUp: splitMouseUp,
+    onTouchMove: splitTouchMove,
+    onTouchEnd: splitTouchEnd,
+  })
+
+  const startSplitResize = (mode: "changes" | "git-changes" | "files", clientX: number) => {
+    if (typeof document === "undefined") return
+    setActiveSplitResize(mode)
+    setSplitResizeStartX(clientX)
+    setSplitResizeStartWidth(
+      mode === "changes" ? changesSplitWidth() : mode === "git-changes" ? gitChangesSplitWidth() : filesSplitWidth(),
+    )
+    splitPointerDrag.start()
+  }
+
+  const handleSplitResizeMouseDown = (mode: "changes" | "git-changes" | "files") => (event: MouseEvent) => {
+    event.preventDefault()
+    startSplitResize(mode, event.clientX)
+  }
+
+  const handleSplitResizeTouchStart = (mode: "changes" | "git-changes" | "files") => (event: TouchEvent) => {
+    const touch = event.touches[0]
+    if (!touch) return
+    event.preventDefault()
+    startSplitResize(mode, touch.clientX)
+  }
+
+  onCleanup(() => {
+    stopSplitResize()
+  })
+
+  const worktreeSlugForViewer = createMemo(() => {
+    const sessionId = props.activeSessionId()
+    if (sessionId && sessionId !== "info") {
+      return getWorktreeSlugForSession(props.instanceId, sessionId)
+    }
+    return getDefaultWorktreeSlug(props.instanceId)
+  })
+
+  const browserClient = createMemo(() => getOrCreateWorktreeClient(props.instanceId, worktreeSlugForViewer()))
+
+  const [gitStatusEntries, setGitStatusEntries] = createSignal<GitFileStatus[] | null>(null)
+  const [gitStatusLoading, setGitStatusLoading] = createSignal(false)
+  const [gitStatusError, setGitStatusError] = createSignal<string | null>(null)
+  const [gitSelectedPath, setGitSelectedPath] = createSignal<string | null>(null)
+  const [gitSelectedLoading, setGitSelectedLoading] = createSignal(false)
+  const [gitSelectedError, setGitSelectedError] = createSignal<string | null>(null)
+  const [gitSelectedBefore, setGitSelectedBefore] = createSignal<string | null>(null)
+  const [gitSelectedAfter, setGitSelectedAfter] = createSignal<string | null>(null)
+
+  const gitMostChangedPath = createMemo<string | null>(() => {
+    const entries = gitStatusEntries()
+    if (!Array.isArray(entries) || entries.length === 0) return null
+    const candidates = entries.filter((item) => item && item.status !== "deleted")
+    if (candidates.length === 0) return null
+    const best = candidates.reduce((currentBest, item) => {
+      const bestScore = (currentBest?.added ?? 0) + (currentBest?.removed ?? 0)
+      const score = (item?.added ?? 0) + (item?.removed ?? 0)
+      if (score > bestScore) return item
+      if (score < bestScore) return currentBest
+      return String(item.path || "").localeCompare(String(currentBest?.path || "")) < 0 ? item : currentBest
+    }, candidates[0])
+    return typeof best?.path === "string" ? best.path : null
+  })
+
+  createEffect(() => {
+    // Reset tab state when worktree context changes.
+    worktreeSlugForViewer()
+    setBrowserPath(".")
+    setBrowserEntries(null)
+    setBrowserError(null)
+    setBrowserSelectedPath(null)
+    setBrowserSelectedContent(null)
+    setBrowserSelectedError(null)
+    setBrowserSelectedLoading(false)
+
+    setGitStatusEntries(null)
+    setGitStatusError(null)
+    setGitStatusLoading(false)
+    setGitSelectedPath(null)
+    setGitSelectedLoading(false)
+    setGitSelectedError(null)
+    setGitSelectedBefore(null)
+    setGitSelectedAfter(null)
+  })
+
+  const loadGitStatus = async (force = false) => {
+    if (!force && gitStatusEntries() !== null) return
+    setGitStatusLoading(true)
+    setGitStatusError(null)
+    try {
+      const list = await requestData<GitFileStatus[]>(browserClient().file.status(), "file.status")
+      setGitStatusEntries(Array.isArray(list) ? list : [])
+    } catch (error) {
+      setGitStatusError(error instanceof Error ? error.message : "Failed to load git status")
+      setGitStatusEntries([])
+    } finally {
+      setGitStatusLoading(false)
+    }
+  }
+
+  async function openGitFile(path: string) {
+    setGitSelectedPath(path)
+    setGitSelectedLoading(true)
+    setGitSelectedError(null)
+    setGitSelectedBefore(null)
+    setGitSelectedAfter(null)
+
+    const list = gitStatusEntries() || []
+    const entry = list.find((item) => item.path === path) || null
+    if (entry?.status === "deleted") {
+      setGitSelectedError("Deleted file diff is not available yet")
+      setGitSelectedLoading(false)
+      return
+    }
+
+    // Phone: treat file selection as a commit action and close the overlay.
+    if (props.isPhoneLayout()) {
+      setGitChangesListOpen(false)
+    }
+
+    try {
+      const content = await requestData<FileContent>(browserClient().file.read({ path }), "file.read")
+      const type = (content as any)?.type
+      const encoding = (content as any)?.encoding
+      if (type && type !== "text") {
+        throw new Error("Binary file cannot be displayed")
+      }
+      if (encoding === "base64") {
+        throw new Error("Binary file cannot be displayed")
+      }
+      const afterText = typeof (content as any)?.content === "string" ? ((content as any).content as string) : null
+      if (afterText === null) {
+        throw new Error("Unsupported file type")
+      }
+
+      setGitSelectedAfter(afterText)
+
+      if (entry?.status === "added") {
+        setGitSelectedBefore("")
+        return
+      }
+
+      const diffText =
+        typeof (content as any)?.diff === "string" && String((content as any).diff).trim().length > 0
+          ? String((content as any).diff)
+          : (content as any)?.patch
+            ? buildUnifiedDiffFromSdkPatch((content as any).patch)
+            : ""
+
+      const beforeText = tryReverseApplyUnifiedDiff(afterText, diffText)
+      if (beforeText === null) {
+        throw new Error("Unable to calculate diff for this file")
+      }
+      setGitSelectedBefore(beforeText)
+    } catch (error) {
+      setGitSelectedError(error instanceof Error ? error.message : "Failed to load file changes")
+    } finally {
+      setGitSelectedLoading(false)
+    }
+  }
+
+  createEffect(() => {
+    if (rightPanelTab() !== "git-changes") return
+    const entries = gitStatusEntries()
+    if (entries === null) return
+    if (gitSelectedPath()) return
+    const next = gitMostChangedPath()
+    if (!next) return
+    void openGitFile(next)
+  })
+
+  const refreshGitStatus = async () => {
+    await loadGitStatus(true)
+    const selected = gitSelectedPath()
+    if (selected) {
+      void openGitFile(selected)
+    }
+  }
+
+  const bestDiffFile = createMemo<string | null>(() => {
+    const diffs = props.activeSessionDiffs()
+    if (!Array.isArray(diffs) || diffs.length === 0) return null
+    const best = diffs.reduce((currentBest, item) => {
+      const bestAdd = typeof (currentBest as any)?.additions === "number" ? (currentBest as any).additions : 0
+      const bestDel = typeof (currentBest as any)?.deletions === "number" ? (currentBest as any).deletions : 0
+      const bestScore = bestAdd + bestDel
+
+      const add = typeof (item as any)?.additions === "number" ? (item as any).additions : 0
+      const del = typeof (item as any)?.deletions === "number" ? (item as any).deletions : 0
+      const score = add + del
+
+      if (score > bestScore) return item
+      if (score < bestScore) return currentBest
+      return String(item.file || "").localeCompare(String((currentBest as any)?.file || "")) < 0 ? item : currentBest
+    }, diffs[0])
+    return typeof (best as any)?.file === "string" ? (best as any).file : null
+  })
+
+  createEffect(() => {
+    const next = bestDiffFile()
+    if (!next) return
+    const diffs = props.activeSessionDiffs()
+    if (!Array.isArray(diffs) || diffs.length === 0) return
+
+    const current = selectedFile()
+    if (current && diffs.some((d) => d.file === current)) return
+    setSelectedFile(next)
+  })
+
+  const normalizeBrowserPath = (input: string) => {
+    const raw = String(input || ".").trim()
+    if (!raw || raw === "./") return "."
+    const cleaned = raw.replace(/\\/g, "/").replace(/\/+$/, "")
+    return cleaned === "" ? "." : cleaned
+  }
+
+  const getParentPath = (path: string): string | null => {
+    const current = normalizeBrowserPath(path)
+    if (current === ".") return null
+    const parts = current.split("/").filter(Boolean)
+    parts.pop()
+    return parts.length ? parts.join("/") : "."
+  }
+
+  const loadBrowserEntries = async (path: string) => {
+    const normalized = normalizeBrowserPath(path)
+    setBrowserLoading(true)
+    setBrowserError(null)
+    try {
+      const nodes = await requestData<FileNode[]>(browserClient().file.list({ path: normalized }), "file.list")
+      setBrowserPath(normalized)
+      setBrowserEntries(Array.isArray(nodes) ? nodes : [])
+    } catch (error) {
+      setBrowserError(error instanceof Error ? error.message : "Failed to load files")
+      setBrowserEntries([])
+    } finally {
+      setBrowserLoading(false)
+    }
+  }
+
+  const openBrowserFile = async (path: string) => {
+    setBrowserSelectedPath(path)
+    setBrowserSelectedLoading(true)
+    setBrowserSelectedError(null)
+    setBrowserSelectedContent(null)
+
+    // Phone: treat file selection as a commit action and close the overlay.
+    if (props.isPhoneLayout()) {
+      setFilesListOpen(false)
+    }
+    try {
+      const content = await requestData<FileContent>(browserClient().file.read({ path }), "file.read")
+      const type = (content as any)?.type
+      const encoding = (content as any)?.encoding
+      if (type && type !== "text") {
+        throw new Error("Binary file cannot be displayed")
+      }
+      if (encoding === "base64") {
+        throw new Error("Binary file cannot be displayed")
+      }
+      const text = (content as any)?.content
+      if (typeof text !== "string") {
+        throw new Error("Unsupported file type")
+      }
+      setBrowserSelectedContent(text)
+    } catch (error) {
+      setBrowserSelectedError(error instanceof Error ? error.message : "Failed to read file")
+    } finally {
+      setBrowserSelectedLoading(false)
+    }
+  }
+
+  createEffect(() => {
+    if (rightPanelTab() !== "files") return
+    if (browserLoading()) return
+    if (browserEntries() !== null) return
+    void loadBrowserEntries(browserPath())
+  })
+
+  createEffect(() => {
+    if (rightPanelTab() !== "git-changes") return
+    if (gitStatusLoading()) return
+    if (gitStatusEntries() !== null) return
+    void loadGitStatus()
+  })
+
+  const handleSelectChangesFile = (file: string, closeList: boolean) => {
+    setSelectedFile(file)
+    if (closeList) {
+      setChangesListOpen(false)
+    }
+  }
+
+  const toggleChangesList = () => {
+    setChangesListTouched(true)
+    setChangesListOpen((current) => {
+      const next = !current
+      persistListOpen("changes", next)
+      return next
+    })
+  }
+
+  const toggleFilesList = () => {
+    setFilesListTouched(true)
+    setFilesListOpen((current) => {
+      const next = !current
+      persistListOpen("files", next)
+      return next
+    })
+  }
+
+  const toggleGitList = () => {
+    setGitChangesListTouched(true)
+    setGitChangesListOpen((current) => {
+      const next = !current
+      persistListOpen("git-changes", next)
+      return next
+    })
+  }
+
+  const refreshFilesTab = async () => {
+    void loadBrowserEntries(browserPath())
+    const selected = browserSelectedPath()
+    if (selected) {
+      // Refresh file content without altering overlay state.
+      setBrowserSelectedLoading(true)
+      setBrowserSelectedError(null)
+      try {
+        const content = await requestData<FileContent>(browserClient().file.read({ path: selected }), "file.read")
+        const type = (content as any)?.type
+        const encoding = (content as any)?.encoding
+        if (type && type !== "text") {
+          throw new Error("Binary file cannot be displayed")
+        }
+        if (encoding === "base64") {
+          throw new Error("Binary file cannot be displayed")
+        }
+        const text = (content as any)?.content
+        if (typeof text !== "string") {
+          throw new Error("Unsupported file type")
+        }
+        setBrowserSelectedContent(text)
+      } catch (error) {
+        setBrowserSelectedError(error instanceof Error ? error.message : "Failed to read file")
+      } finally {
+        setBrowserSelectedLoading(false)
+      }
+    }
+  }
+
+  const browserParentPath = createMemo(() => getParentPath(browserPath()))
+  const browserScopeKey = createMemo(() => `${props.instanceId}:${worktreeSlugForViewer()}`)
+  const gitScopeKey = createMemo(() => `${props.instanceId}:git:${worktreeSlugForViewer()}`)
+
+  const openChangesTabFromStatus = (file?: string) => {
+    if (file) {
+      setSelectedFile(file)
+    }
+    setRightPanelTab("changes")
+  }
+
+  const statusSectionIds = ["session-changes", "plan", "background-processes", "mcp", "lsp", "plugins"]
+
+  createEffect(() => {
+    const currentExpanded = new Set(rightPanelExpandedItems())
+    if (statusSectionIds.every((id) => currentExpanded.has(id))) return
+    setRightPanelExpandedItems(statusSectionIds)
+  })
+
+  const handleAccordionChange = (values: string[]) => {
+    setRightPanelExpandedItems(values)
+  }
+
+  const tabClass = (tab: RightPanelTab) =>
+    `right-panel-tab ${rightPanelTab() === tab ? "right-panel-tab-active" : "right-panel-tab-inactive"}`
+
+  return (
+    <div class="flex flex-col h-full" ref={props.setContentEl}>
+      <div class="right-panel-tab-bar">
+        <div class="tab-container">
+          <div class="tab-strip-shortcuts text-primary">
+            <Show when={props.rightDrawerState() === "floating-open"}>
+              <IconButton
+                size="small"
+                color="inherit"
+                aria-label={props.t("instanceShell.rightDrawer.toggle.close")}
+                title={props.t("instanceShell.rightDrawer.toggle.close")}
+                onClick={props.onCloseRightDrawer}
+              >
+                <MenuOpenIcon fontSize="small" sx={{ transform: "scaleX(-1)" }} />
+              </IconButton>
+            </Show>
+            <Show when={!props.isPhoneLayout()}>
+              <IconButton
+                size="small"
+                color="inherit"
+                aria-label={props.rightPinned() ? props.t("instanceShell.rightDrawer.unpin") : props.t("instanceShell.rightDrawer.pin")}
+                onClick={() => (props.rightPinned() ? props.onUnpinRightDrawer() : props.onPinRightDrawer())}
+              >
+                {props.rightPinned() ? <PushPinIcon fontSize="small" /> : <PushPinOutlinedIcon fontSize="small" />}
+              </IconButton>
+            </Show>
+          </div>
+          <div class="tab-scroll">
+            <div class="tab-strip">
+              <div class="tab-strip-tabs" role="tablist" aria-label={props.t("instanceShell.rightPanel.tabs.ariaLabel")}> 
+                <button
+                  type="button"
+                  role="tab"
+                  class={tabClass("changes")}
+                  aria-selected={rightPanelTab() === "changes"}
+                  onClick={() => setRightPanelTab("changes")}
+                >
+                  <span class="tab-label">{props.t("instanceShell.rightPanel.tabs.changes")}</span>
+                </button>
+                <button
+                  type="button"
+                  role="tab"
+                  class={tabClass("git-changes")}
+                  aria-selected={rightPanelTab() === "git-changes"}
+                  onClick={() => setRightPanelTab("git-changes")}
+                >
+                  <span class="tab-label">{props.t("instanceShell.rightPanel.tabs.gitChanges")}</span>
+                </button>
+                <button
+                  type="button"
+                  role="tab"
+                  class={tabClass("files")}
+                  aria-selected={rightPanelTab() === "files"}
+                  onClick={() => setRightPanelTab("files")}
+                >
+                  <span class="tab-label">{props.t("instanceShell.rightPanel.tabs.files")}</span>
+                </button>
+                <button
+                  type="button"
+                  role="tab"
+                  class={tabClass("status")}
+                  aria-selected={rightPanelTab() === "status"}
+                  onClick={() => setRightPanelTab("status")}
+                >
+                  <span class="tab-label">{props.t("instanceShell.rightPanel.tabs.status")}</span>
+                </button>
+              </div>
+
+              <div class="tab-strip-spacer" />
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div class="flex-1 overflow-y-auto">
+        <Show when={rightPanelTab() === "changes"}>
+          <ChangesTab
+            t={props.t}
+            instanceId={props.instanceId}
+            activeSessionId={props.activeSessionId}
+            activeSessionDiffs={props.activeSessionDiffs}
+            selectedFile={selectedFile}
+            onSelectFile={handleSelectChangesFile}
+            diffViewMode={diffViewMode}
+            diffContextMode={diffContextMode}
+            onViewModeChange={setDiffViewMode}
+            onContextModeChange={setDiffContextMode}
+            listOpen={changesListOpen}
+            onToggleList={toggleChangesList}
+            splitWidth={changesSplitWidth}
+            onResizeMouseDown={handleSplitResizeMouseDown("changes")}
+            onResizeTouchStart={handleSplitResizeTouchStart("changes")}
+            isPhoneLayout={props.isPhoneLayout}
+          />
+        </Show>
+
+        <Show when={rightPanelTab() === "git-changes"}>
+          <GitChangesTab
+            t={props.t}
+            activeSessionId={props.activeSessionId}
+            entries={gitStatusEntries}
+            statusLoading={gitStatusLoading}
+            statusError={gitStatusError}
+            selectedPath={gitSelectedPath}
+            selectedLoading={gitSelectedLoading}
+            selectedError={gitSelectedError}
+            selectedBefore={gitSelectedBefore}
+            selectedAfter={gitSelectedAfter}
+            mostChangedPath={gitMostChangedPath}
+            scopeKey={gitScopeKey}
+            diffViewMode={diffViewMode}
+            diffContextMode={diffContextMode}
+            onViewModeChange={setDiffViewMode}
+            onContextModeChange={setDiffContextMode}
+            onOpenFile={(path) => void openGitFile(path)}
+            onRefresh={() => void refreshGitStatus()}
+            listOpen={gitChangesListOpen}
+            onToggleList={toggleGitList}
+            splitWidth={gitChangesSplitWidth}
+            onResizeMouseDown={handleSplitResizeMouseDown("git-changes")}
+            onResizeTouchStart={handleSplitResizeTouchStart("git-changes")}
+            isPhoneLayout={props.isPhoneLayout}
+          />
+        </Show>
+
+        <Show when={rightPanelTab() === "files"}>
+          <FilesTab
+            t={props.t}
+            browserPath={browserPath}
+            browserEntries={browserEntries}
+            browserLoading={browserLoading}
+            browserError={browserError}
+            browserSelectedPath={browserSelectedPath}
+            browserSelectedContent={browserSelectedContent}
+            browserSelectedLoading={browserSelectedLoading}
+            browserSelectedError={browserSelectedError}
+            parentPath={browserParentPath}
+            scopeKey={browserScopeKey}
+            onLoadEntries={(path) => void loadBrowserEntries(path)}
+            onOpenFile={(path) => void openBrowserFile(path)}
+            onRefresh={() => void refreshFilesTab()}
+            listOpen={filesListOpen}
+            onToggleList={toggleFilesList}
+            splitWidth={filesSplitWidth}
+            onResizeMouseDown={handleSplitResizeMouseDown("files")}
+            onResizeTouchStart={handleSplitResizeTouchStart("files")}
+            isPhoneLayout={props.isPhoneLayout}
+          />
+        </Show>
+
+        <Show when={rightPanelTab() === "status"}>
+          <StatusTab
+            t={props.t}
+            instanceId={props.instanceId}
+            instance={props.instance}
+            activeSessionId={props.activeSessionId}
+            activeSession={props.activeSession}
+            activeSessionDiffs={props.activeSessionDiffs}
+            latestTodoState={props.latestTodoState}
+            backgroundProcessList={props.backgroundProcessList}
+            onOpenBackgroundOutput={props.onOpenBackgroundOutput}
+            onStopBackgroundProcess={props.onStopBackgroundProcess}
+            onTerminateBackgroundProcess={props.onTerminateBackgroundProcess}
+            expandedItems={rightPanelExpandedItems}
+            onExpandedItemsChange={handleAccordionChange}
+            onOpenChangesTab={openChangesTabFromStatus}
+          />
+        </Show>
+      </div>
+    </div>
+  )
+}
+
+export default RightPanel

packages/ui/src/components/instance/shell/right-panel/components/DiffToolbar.tsx

@@ -0,0 +1,53 @@
+import type { Component } from "solid-js"
+
+import type { DiffContextMode, DiffViewMode } from "../types"
+
+interface DiffToolbarProps {
+  viewMode: DiffViewMode
+  contextMode: DiffContextMode
+  onViewModeChange: (mode: DiffViewMode) => void
+  onContextModeChange: (mode: DiffContextMode) => void
+}
+
+const DiffToolbar: Component<DiffToolbarProps> = (props) => {
+  return (
+    <div class="file-viewer-toolbar">
+      <button
+        type="button"
+        class={`file-viewer-toolbar-button${props.viewMode === "split" ? " active" : ""}`}
+        aria-pressed={props.viewMode === "split"}
+        onClick={() => props.onViewModeChange("split")}
+      >
+        Split
+      </button>
+      <button
+        type="button"
+        class={`file-viewer-toolbar-button${props.viewMode === "unified" ? " active" : ""}`}
+        aria-pressed={props.viewMode === "unified"}
+        onClick={() => props.onViewModeChange("unified")}
+      >
+        Unified
+      </button>
+      <button
+        type="button"
+        class={`file-viewer-toolbar-button${props.contextMode === "collapsed" ? " active" : ""}`}
+        aria-pressed={props.contextMode === "collapsed"}
+        onClick={() => props.onContextModeChange("collapsed")}
+        title="Hide unchanged regions"
+      >
+        Collapsed
+      </button>
+      <button
+        type="button"
+        class={`file-viewer-toolbar-button${props.contextMode === "expanded" ? " active" : ""}`}
+        aria-pressed={props.contextMode === "expanded"}
+        onClick={() => props.onContextModeChange("expanded")}
+        title="Show full file"
+      >
+        Expanded
+      </button>
+    </div>
+  )
+}
+
+export default DiffToolbar

packages/ui/src/components/instance/shell/right-panel/components/OverlayList.tsx

@@ -0,0 +1,16 @@
+import type { Component, JSX } from "solid-js"
+
+interface OverlayListProps {
+  ariaLabel: string
+  children: JSX.Element
+}
+
+const OverlayList: Component<OverlayListProps> = (props) => {
+  return (
+    <div class="file-list-overlay" role="dialog" aria-label={props.ariaLabel}>
+      <div class="file-list-scroll">{props.children}</div>
+    </div>
+  )
+}
+
+export default OverlayList

packages/ui/src/components/instance/shell/right-panel/components/SplitFilePanel.tsx

@@ -0,0 +1,70 @@
+import { Show, type Component, type JSX } from "solid-js"
+
+import OverlayList from "./OverlayList"
+
+type SplitFilePanelList = {
+  panel: () => JSX.Element
+  overlay: () => JSX.Element
+}
+
+interface SplitFilePanelProps {
+  header: JSX.Element
+  list: SplitFilePanelList
+  viewer: JSX.Element
+
+  listOpen: boolean
+  onToggleList: () => void
+
+  splitWidth: number
+  onResizeMouseDown: (event: MouseEvent) => void
+  onResizeTouchStart: (event: TouchEvent) => void
+
+  isPhoneLayout: boolean
+  overlayAriaLabel: string
+}
+
+const SplitFilePanel: Component<SplitFilePanelProps> = (props) => {
+  return (
+    <div class="files-tab-container">
+      <div class="files-tab-header">
+        <div class="files-tab-header-row">
+          <button type="button" class="files-toggle-button" onClick={props.onToggleList}>
+            {props.listOpen ? "Hide files" : "Show files"}
+          </button>
+
+          {props.header}
+        </div>
+      </div>
+
+      <div class="files-tab-body">
+        <Show
+          when={!props.isPhoneLayout && props.listOpen}
+          fallback={props.viewer}
+        >
+          <div class="files-split" style={{ "--files-pane-width": `${props.splitWidth}px` }}>
+            <div class="file-list-panel">
+              <div class="file-list-scroll">{props.list.panel()}</div>
+            </div>
+            <div
+              class="file-split-handle"
+              role="separator"
+              aria-orientation="vertical"
+              aria-label="Resize file list"
+              onMouseDown={props.onResizeMouseDown}
+              onTouchStart={props.onResizeTouchStart}
+            />
+            {props.viewer}
+          </div>
+        </Show>
+
+        <Show when={props.isPhoneLayout}>
+          <Show when={props.listOpen}>
+            <OverlayList ariaLabel={props.overlayAriaLabel}>{props.list.overlay()}</OverlayList>
+          </Show>
+        </Show>
+      </div>
+    </div>
+  )
+}
+
+export default SplitFilePanel

packages/ui/src/components/instance/shell/right-panel/tabs/ChangesTab.tsx

@@ -0,0 +1,203 @@
+import { For, Show, type Accessor, type Component, type JSX } from "solid-js"
+
+import { MonacoDiffViewer } from "../../../../file-viewer/monaco-diff-viewer"
+
+import DiffToolbar from "../components/DiffToolbar"
+import SplitFilePanel from "../components/SplitFilePanel"
+import type { DiffContextMode, DiffViewMode } from "../types"
+
+interface ChangesTabProps {
+  t: (key: string, vars?: Record<string, any>) => string
+
+  instanceId: string
+  activeSessionId: Accessor<string | null>
+  activeSessionDiffs: Accessor<any[] | undefined>
+
+  selectedFile: Accessor<string | null>
+  onSelectFile: (file: string, closeList: boolean) => void
+
+  diffViewMode: Accessor<DiffViewMode>
+  diffContextMode: Accessor<DiffContextMode>
+  onViewModeChange: (mode: DiffViewMode) => void
+  onContextModeChange: (mode: DiffContextMode) => void
+
+  listOpen: Accessor<boolean>
+  onToggleList: () => void
+  splitWidth: Accessor<number>
+  onResizeMouseDown: (event: MouseEvent) => void
+  onResizeTouchStart: (event: TouchEvent) => void
+  isPhoneLayout: Accessor<boolean>
+}
+
+const ChangesTab: Component<ChangesTabProps> = (props) => {
+  const renderContent = (): JSX.Element => {
+    const sessionId = props.activeSessionId()
+
+    const hasSession = Boolean(sessionId && sessionId !== "info")
+    const diffs = hasSession ? props.activeSessionDiffs() : null
+
+    const sorted = Array.isArray(diffs) ? [...diffs].sort((a, b) => String(a.file || "").localeCompare(String(b.file || ""))) : []
+    const totals = sorted.reduce(
+      (acc, item) => {
+        acc.additions += typeof item.additions === "number" ? item.additions : 0
+        acc.deletions += typeof item.deletions === "number" ? item.deletions : 0
+        return acc
+      },
+      { additions: 0, deletions: 0 },
+    )
+
+    const mostChanged = sorted.length
+      ? sorted.reduce((best, item) => {
+          const bestAdd = typeof (best as any)?.additions === "number" ? (best as any).additions : 0
+          const bestDel = typeof (best as any)?.deletions === "number" ? (best as any).deletions : 0
+          const bestScore = bestAdd + bestDel
+
+          const add = typeof (item as any)?.additions === "number" ? (item as any).additions : 0
+          const del = typeof (item as any)?.deletions === "number" ? (item as any).deletions : 0
+          const score = add + del
+
+          if (score > bestScore) return item
+          if (score < bestScore) return best
+          return String(item.file || "").localeCompare(String((best as any)?.file || "")) < 0 ? item : best
+        }, sorted[0])
+      : null
+
+    // Auto-select the most-changed file if none selected.
+    const currentSelected = props.selectedFile()
+    const selectedFileData = sorted.find((f) => f.file === currentSelected) || mostChanged
+
+    const scopeKey = `${props.instanceId}:${hasSession ? sessionId : "no-session"}`
+
+    const emptyViewerMessage = () => {
+      if (!hasSession) return props.t("instanceShell.sessionChanges.noSessionSelected")
+      if (diffs === undefined) return props.t("instanceShell.sessionChanges.loading")
+      if (!Array.isArray(diffs) || diffs.length === 0) return props.t("instanceShell.sessionChanges.empty")
+      return props.t("instanceShell.filesShell.viewerEmpty")
+    }
+
+    const renderViewer = () => (
+      <div class="file-viewer-panel flex-1">
+        <div class="file-viewer-header">
+          <DiffToolbar
+            viewMode={props.diffViewMode()}
+            contextMode={props.diffContextMode()}
+            onViewModeChange={props.onViewModeChange}
+            onContextModeChange={props.onContextModeChange}
+          />
+        </div>
+        <div class="file-viewer-content file-viewer-content--monaco">
+          <Show
+            when={selectedFileData && hasSession && Array.isArray(diffs) && diffs.length > 0 ? selectedFileData : null}
+            fallback={
+              <div class="file-viewer-empty">
+                <span class="file-viewer-empty-text">{emptyViewerMessage()}</span>
+              </div>
+            }
+          >
+            {(file) => (
+              <MonacoDiffViewer
+                scopeKey={scopeKey}
+                path={String(file().file || "")}
+                before={String((file() as any).before || "")}
+                after={String((file() as any).after || "")}
+                viewMode={props.diffViewMode()}
+                contextMode={props.diffContextMode()}
+              />
+            )}
+          </Show>
+        </div>
+      </div>
+    )
+
+    const renderEmptyList = () => (
+      <div class="p-3 text-xs text-secondary">{emptyViewerMessage()}</div>
+    )
+
+    const renderListPanel = () => (
+      <Show when={sorted.length > 0} fallback={renderEmptyList()}>
+        <For each={sorted}>
+          {(item) => (
+            <div
+              class={`file-list-item ${selectedFileData?.file === item.file ? "file-list-item-active" : ""}`}
+              onClick={() => {
+                props.onSelectFile(item.file, props.isPhoneLayout())
+              }}
+            >
+              <div class="file-list-item-content">
+                <div class="file-list-item-path" title={item.file}>
+                  <span class="file-path-text">{item.file}</span>
+                </div>
+                <div class="file-list-item-stats">
+                  <span class="file-list-item-additions">+{item.additions}</span>
+                  <span class="file-list-item-deletions">-{item.deletions}</span>
+                </div>
+              </div>
+            </div>
+          )}
+        </For>
+      </Show>
+    )
+
+    const renderListOverlay = () => (
+      <Show when={sorted.length > 0} fallback={renderEmptyList()}>
+        <For each={sorted}>
+          {(item) => (
+            <div
+              class={`file-list-item ${selectedFileData?.file === item.file ? "file-list-item-active" : ""}`}
+              onClick={() => {
+                props.onSelectFile(item.file, true)
+              }}
+              title={item.file}
+            >
+              <div class="file-list-item-content">
+                <div class="file-list-item-path" title={item.file}>
+                  <span class="file-path-text">{item.file}</span>
+                </div>
+                <div class="file-list-item-stats">
+                  <span class="file-list-item-additions">+{item.additions}</span>
+                  <span class="file-list-item-deletions">-{item.deletions}</span>
+                </div>
+              </div>
+            </div>
+          )}
+        </For>
+      </Show>
+    )
+
+    const headerPath = () => (selectedFileData?.file ? selectedFileData.file : props.t("instanceShell.rightPanel.tabs.changes"))
+
+    return (
+      <SplitFilePanel
+        header={
+          <>
+            <span class="files-tab-selected-path" title={headerPath()}>
+              <span class="file-path-text">{headerPath()}</span>
+            </span>
+
+            <div class="files-tab-stats" style={{ flex: "0 0 auto" }}>
+              <span class="files-tab-stat files-tab-stat-additions">
+                <span class="files-tab-stat-value">+{totals.additions}</span>
+              </span>
+              <span class="files-tab-stat files-tab-stat-deletions">
+                <span class="files-tab-stat-value">-{totals.deletions}</span>
+              </span>
+            </div>
+          </>
+        }
+        list={{ panel: renderListPanel, overlay: renderListOverlay }}
+        viewer={renderViewer()}
+        listOpen={props.listOpen()}
+        onToggleList={props.onToggleList}
+        splitWidth={props.splitWidth()}
+        onResizeMouseDown={props.onResizeMouseDown}
+        onResizeTouchStart={props.onResizeTouchStart}
+        isPhoneLayout={props.isPhoneLayout()}
+        overlayAriaLabel="Changes"
+      />
+    )
+  }
+
+  return <>{renderContent()}</>
+}
+
+export default ChangesTab

packages/ui/src/components/instance/shell/right-panel/tabs/FilesTab.tsx

@@ -0,0 +1,191 @@
+import { For, Show, type Accessor, type Component, type JSX } from "solid-js"
+import type { FileNode } from "@opencode-ai/sdk/v2/client"
+
+import { RefreshCw } from "lucide-solid"
+
+import { MonacoFileViewer } from "../../../../file-viewer/monaco-file-viewer"
+
+import SplitFilePanel from "../components/SplitFilePanel"
+
+interface FilesTabProps {
+  t: (key: string, vars?: Record<string, any>) => string
+
+  browserPath: Accessor<string>
+  browserEntries: Accessor<FileNode[] | null>
+  browserLoading: Accessor<boolean>
+  browserError: Accessor<string | null>
+
+  browserSelectedPath: Accessor<string | null>
+  browserSelectedContent: Accessor<string | null>
+  browserSelectedLoading: Accessor<boolean>
+  browserSelectedError: Accessor<string | null>
+
+  parentPath: Accessor<string | null>
+  scopeKey: Accessor<string>
+
+  onLoadEntries: (path: string) => void
+  onOpenFile: (path: string) => void
+  onRefresh: () => void
+
+  listOpen: Accessor<boolean>
+  onToggleList: () => void
+  splitWidth: Accessor<number>
+  onResizeMouseDown: (event: MouseEvent) => void
+  onResizeTouchStart: (event: TouchEvent) => void
+  isPhoneLayout: Accessor<boolean>
+}
+
+const FilesTab: Component<FilesTabProps> = (props) => {
+  const renderContent = (): JSX.Element => {
+    const entriesValue = props.browserEntries()
+    const entries = entriesValue || []
+    const sorted = [...entries].sort((a, b) => {
+      const aDir = a.type === "directory" ? 0 : 1
+      const bDir = b.type === "directory" ? 0 : 1
+      if (aDir !== bDir) return aDir - bDir
+      return String(a.name || "").localeCompare(String(b.name || ""))
+    })
+
+    const parent = props.parentPath()
+
+    const headerDisplayedPath = () => props.browserSelectedPath() || props.browserPath()
+
+    const emptyViewerMessage = () => {
+      if (props.browserLoading() && entriesValue === null) return "Loading files..."
+      return "Select a file to preview"
+    }
+
+    const renderViewer = () => (
+      <div class="file-viewer-panel flex-1">
+        <div class="file-viewer-content file-viewer-content--monaco">
+          <Show
+            when={props.browserSelectedLoading()}
+            fallback={
+              <Show
+                when={props.browserSelectedError()}
+                fallback={
+                  <Show
+                    when={
+                      props.browserSelectedPath() && props.browserSelectedContent() !== null
+                        ? { path: props.browserSelectedPath() as string, content: props.browserSelectedContent() as string }
+                        : null
+                    }
+                    fallback={
+                      <div class="file-viewer-empty">
+                        <span class="file-viewer-empty-text">{emptyViewerMessage()}</span>
+                      </div>
+                    }
+                  >
+                    {(payload) => (
+                      <MonacoFileViewer scopeKey={props.scopeKey()} path={payload().path} content={payload().content} />
+                    )}
+                  </Show>
+                }
+              >
+                {(err) => (
+                  <div class="file-viewer-empty">
+                    <span class="file-viewer-empty-text">{err()}</span>
+                  </div>
+                )}
+              </Show>
+            }
+          >
+            <div class="file-viewer-empty">
+              <span class="file-viewer-empty-text">Loading…</span>
+            </div>
+          </Show>
+        </div>
+      </div>
+    )
+
+    const renderList = () => (
+      <>
+        <Show when={parent}>
+          {(p) => (
+            <div class="file-list-item" onClick={() => props.onLoadEntries(p())}>
+              <div class="file-list-item-content">
+                <div class="file-list-item-path" title={p()}>
+                  <span class="file-path-text">..</span>
+                </div>
+              </div>
+            </div>
+          )}
+        </Show>
+
+        <Show when={props.browserLoading() && entriesValue === null}>
+          <div class="p-3 text-xs text-secondary">Loading files...</div>
+        </Show>
+
+        <For each={sorted}>
+          {(item) => (
+            <div
+              class={`file-list-item ${props.browserSelectedPath() === item.path ? "file-list-item-active" : ""}`}
+              onClick={() => {
+                if (item.type === "directory") {
+                  props.onLoadEntries(item.path)
+                  return
+                }
+                props.onOpenFile(item.path)
+              }}
+              title={item.path}
+            >
+              <div class="file-list-item-content">
+                <div class="file-list-item-path" title={item.path}>
+                  <span class="file-path-text">{item.name}</span>
+                </div>
+                <div class="file-list-item-stats">
+                  <span class="text-[10px] text-secondary">{item.type}</span>
+                </div>
+              </div>
+            </div>
+          )}
+        </For>
+      </>
+    )
+
+    return (
+      <SplitFilePanel
+        header={
+          <>
+            <div class="files-tab-stats">
+              <span class="files-tab-stat">
+                <span class="files-tab-selected-path" title={headerDisplayedPath()}>
+                  <span class="file-path-text">{headerDisplayedPath()}</span>
+                </span>
+              </span>
+              <Show when={props.browserLoading()}>
+                <span>Loading…</span>
+              </Show>
+              <Show when={props.browserError()}>{(err) => <span class="text-error">{err()}</span>}</Show>
+            </div>
+
+            <button
+              type="button"
+              class="files-header-icon-button"
+              title={props.t("instanceShell.rightPanel.actions.refresh")}
+              aria-label={props.t("instanceShell.rightPanel.actions.refresh")}
+              disabled={props.browserLoading()}
+              style={{ "margin-left": "auto" }}
+              onClick={() => props.onRefresh()}
+            >
+              <RefreshCw class={`h-4 w-4${props.browserLoading() ? " animate-spin" : ""}`} />
+            </button>
+          </>
+        }
+        list={{ panel: renderList, overlay: renderList }}
+        viewer={renderViewer()}
+        listOpen={props.listOpen()}
+        onToggleList={props.onToggleList}
+        splitWidth={props.splitWidth()}
+        onResizeMouseDown={props.onResizeMouseDown}
+        onResizeTouchStart={props.onResizeTouchStart}
+        isPhoneLayout={props.isPhoneLayout()}
+        overlayAriaLabel="Files"
+      />
+    )
+  }
+
+  return <>{renderContent()}</>
+}
+
+export default FilesTab

packages/ui/src/components/instance/shell/right-panel/tabs/GitChangesTab.tsx

@@ -0,0 +1,258 @@
+import { For, Show, type Accessor, type Component, type JSX } from "solid-js"
+import type { File as GitFileStatus } from "@opencode-ai/sdk/v2/client"
+
+import { RefreshCw } from "lucide-solid"
+
+import { MonacoDiffViewer } from "../../../../file-viewer/monaco-diff-viewer"
+
+import DiffToolbar from "../components/DiffToolbar"
+import SplitFilePanel from "../components/SplitFilePanel"
+import type { DiffContextMode, DiffViewMode } from "../types"
+
+interface GitChangesTabProps {
+  t: (key: string, vars?: Record<string, any>) => string
+
+  activeSessionId: Accessor<string | null>
+
+  entries: Accessor<GitFileStatus[] | null>
+  statusLoading: Accessor<boolean>
+  statusError: Accessor<string | null>
+
+  selectedPath: Accessor<string | null>
+  selectedLoading: Accessor<boolean>
+  selectedError: Accessor<string | null>
+  selectedBefore: Accessor<string | null>
+  selectedAfter: Accessor<string | null>
+  mostChangedPath: Accessor<string | null>
+
+  scopeKey: Accessor<string>
+
+  diffViewMode: Accessor<DiffViewMode>
+  diffContextMode: Accessor<DiffContextMode>
+  onViewModeChange: (mode: DiffViewMode) => void
+  onContextModeChange: (mode: DiffContextMode) => void
+
+  onOpenFile: (path: string) => void
+  onRefresh: () => void
+
+  listOpen: Accessor<boolean>
+  onToggleList: () => void
+  splitWidth: Accessor<number>
+  onResizeMouseDown: (event: MouseEvent) => void
+  onResizeTouchStart: (event: TouchEvent) => void
+  isPhoneLayout: Accessor<boolean>
+}
+
+const GitChangesTab: Component<GitChangesTabProps> = (props) => {
+  const renderContent = (): JSX.Element => {
+    const sessionId = props.activeSessionId()
+
+    const hasSession = Boolean(sessionId && sessionId !== "info")
+    const entries = hasSession ? props.entries() : null
+
+    const sorted = Array.isArray(entries)
+      ? [...entries].sort((a, b) => String(a.path || "").localeCompare(String(b.path || "")))
+      : []
+
+    const totals = sorted.reduce(
+      (acc, item) => {
+        acc.additions += typeof item.added === "number" ? item.added : 0
+        acc.deletions += typeof item.removed === "number" ? item.removed : 0
+        return acc
+      },
+      { additions: 0, deletions: 0 },
+    )
+
+    const nonDeleted = sorted.filter((item) => item && item.status !== "deleted")
+
+    const emptyViewerMessage = () => {
+      if (!hasSession) return "Select a session to view changes."
+      if (entries === null) return "Loading git changes…"
+      if (nonDeleted.length === 0) return "No git changes yet."
+      return "No file selected."
+    }
+
+    const selectedPath = props.selectedPath()
+    const fallbackPath = props.mostChangedPath()
+    const selectedEntry =
+      sorted.find((item) => item.path === selectedPath) ||
+      (fallbackPath ? sorted.find((item) => item.path === fallbackPath) : null)
+
+    const renderViewer = () => (
+      <div class="file-viewer-panel flex-1">
+        <div class="file-viewer-header">
+          <DiffToolbar
+            viewMode={props.diffViewMode()}
+            contextMode={props.diffContextMode()}
+            onViewModeChange={props.onViewModeChange}
+            onContextModeChange={props.onContextModeChange}
+          />
+        </div>
+        <div class="file-viewer-content file-viewer-content--monaco">
+          <Show
+            when={props.selectedLoading()}
+            fallback={
+              <Show
+                when={props.selectedError()}
+                fallback={
+                  <Show
+                    when={
+                      selectedEntry &&
+                      props.selectedBefore() !== null &&
+                      props.selectedAfter() !== null &&
+                      selectedEntry.status !== "deleted"
+                        ? {
+                            path: selectedEntry.path,
+                            before: props.selectedBefore() as string,
+                            after: props.selectedAfter() as string,
+                          }
+                        : null
+                    }
+                    fallback={
+                      <div class="file-viewer-empty">
+                        <span class="file-viewer-empty-text">{emptyViewerMessage()}</span>
+                      </div>
+                    }
+                  >
+                    {(file) => (
+                      <MonacoDiffViewer
+                        scopeKey={props.scopeKey()}
+                        path={String(file().path || "")}
+                        before={String((file() as any).before || "")}
+                        after={String((file() as any).after || "")}
+                        viewMode={props.diffViewMode()}
+                        contextMode={props.diffContextMode()}
+                      />
+                    )}
+                  </Show>
+                }
+              >
+                {(err) => (
+                  <div class="file-viewer-empty">
+                    <span class="file-viewer-empty-text">{err()}</span>
+                  </div>
+                )}
+              </Show>
+            }
+          >
+            <div class="file-viewer-empty">
+              <span class="file-viewer-empty-text">Loading…</span>
+            </div>
+          </Show>
+        </div>
+      </div>
+    )
+
+    const renderEmptyList = () => <div class="p-3 text-xs text-secondary">{emptyViewerMessage()}</div>
+
+    const renderListPanel = () => (
+      <Show when={nonDeleted.length > 0} fallback={renderEmptyList()}>
+        <For each={sorted}>
+          {(item) => (
+            <div
+              class={`file-list-item ${props.selectedPath() === item.path ? "file-list-item-active" : ""}`}
+              onClick={() => {
+                props.onOpenFile(item.path)
+              }}
+            >
+              <div class="file-list-item-content">
+                <div class="file-list-item-path" title={item.path}>
+                  <span class="file-path-text">{item.path}</span>
+                </div>
+                <div class="file-list-item-stats">
+                  <Show when={item.status === "deleted"}>
+                    <span class="text-[10px] text-secondary">deleted</span>
+                  </Show>
+                  <Show when={item.status !== "deleted"}>
+                    <>
+                      <span class="file-list-item-additions">+{item.added}</span>
+                      <span class="file-list-item-deletions">-{item.removed}</span>
+                    </>
+                  </Show>
+                </div>
+              </div>
+            </div>
+          )}
+        </For>
+      </Show>
+    )
+
+    const renderListOverlay = () => (
+      <Show when={nonDeleted.length > 0} fallback={renderEmptyList()}>
+        <For each={sorted}>
+          {(item) => (
+            <div
+              class={`file-list-item ${props.selectedPath() === item.path ? "file-list-item-active" : ""}`}
+              onClick={() => props.onOpenFile(item.path)}
+              title={item.path}
+            >
+              <div class="file-list-item-content">
+                <div class="file-list-item-path" title={item.path}>
+                  <span class="file-path-text">{item.path}</span>
+                </div>
+                <div class="file-list-item-stats">
+                  <Show when={item.status === "deleted"}>
+                    <span class="text-[10px] text-secondary">deleted</span>
+                  </Show>
+                  <Show when={item.status !== "deleted"}>
+                    <>
+                      <span class="file-list-item-additions">+{item.added}</span>
+                      <span class="file-list-item-deletions">-{item.removed}</span>
+                    </>
+                  </Show>
+                </div>
+              </div>
+            </div>
+          )}
+        </For>
+      </Show>
+    )
+
+    return (
+      <SplitFilePanel
+        header={
+          <>
+            <span class="files-tab-selected-path" title={selectedEntry?.path || "Git Changes"}>
+              <span class="file-path-text">{selectedEntry?.path || "Git Changes"}</span>
+            </span>
+
+            <div class="files-tab-stats" style={{ flex: "0 0 auto" }}>
+              <span class="files-tab-stat files-tab-stat-additions">
+                <span class="files-tab-stat-value">+{totals.additions}</span>
+              </span>
+              <span class="files-tab-stat files-tab-stat-deletions">
+                <span class="files-tab-stat-value">-{totals.deletions}</span>
+              </span>
+              <Show when={props.statusError()}>{(err) => <span class="text-error">{err()}</span>}</Show>
+            </div>
+
+            <button
+              type="button"
+              class="files-header-icon-button"
+              title={props.t("instanceShell.rightPanel.actions.refresh")}
+              aria-label={props.t("instanceShell.rightPanel.actions.refresh")}
+              disabled={!hasSession || props.statusLoading() || entries === null}
+              style={{ "margin-left": "auto" }}
+              onClick={() => props.onRefresh()}
+            >
+              <RefreshCw class={`h-4 w-4${props.statusLoading() ? " animate-spin" : ""}`} />
+            </button>
+          </>
+        }
+        list={{ panel: renderListPanel, overlay: renderListOverlay }}
+        viewer={renderViewer()}
+        listOpen={props.listOpen()}
+        onToggleList={props.onToggleList}
+        splitWidth={props.splitWidth()}
+        onResizeMouseDown={props.onResizeMouseDown}
+        onResizeTouchStart={props.onResizeTouchStart}
+        isPhoneLayout={props.isPhoneLayout()}
+        overlayAriaLabel="Git Changes"
+      />
+    )
+  }
+
+  return <>{renderContent()}</>
+}
+
+export default GitChangesTab

packages/ui/src/components/instance/shell/right-panel/tabs/StatusTab.tsx

@@ -0,0 +1,294 @@
+import { For, Show, type Accessor, type Component } from "solid-js"
+import type { ToolState } from "@opencode-ai/sdk"
+import { Accordion } from "@kobalte/core"
+
+import { ChevronDown, TerminalSquare, Trash2, XOctagon } from "lucide-solid"
+
+import type { Instance } from "../../../../../types/instance"
+import type { BackgroundProcess } from "../../../../../../../server/src/api-types"
+import type { Session } from "../../../../../types/session"
+
+import ContextUsagePanel from "../../../../session/context-usage-panel"
+import { TodoListView } from "../../../../tool-call/renderers/todo"
+import InstanceServiceStatus from "../../../../instance-service-status"
+
+interface StatusTabProps {
+  t: (key: string, vars?: Record<string, any>) => string
+
+  instanceId: string
+  instance: Instance
+
+  activeSessionId: Accessor<string | null>
+  activeSession: Accessor<Session | null>
+  activeSessionDiffs: Accessor<any[] | undefined>
+
+  latestTodoState: Accessor<ToolState | null>
+
+  backgroundProcessList: Accessor<BackgroundProcess[]>
+  onOpenBackgroundOutput: (process: BackgroundProcess) => void
+  onStopBackgroundProcess: (processId: string) => Promise<void> | void
+  onTerminateBackgroundProcess: (processId: string) => Promise<void> | void
+
+  expandedItems: Accessor<string[]>
+  onExpandedItemsChange: (values: string[]) => void
+
+  onOpenChangesTab: (file?: string) => void
+}
+
+const StatusTab: Component<StatusTabProps> = (props) => {
+  const isSectionExpanded = (id: string) => props.expandedItems().includes(id)
+
+  const renderStatusSessionChanges = () => {
+    const sessionId = props.activeSessionId()
+    if (!sessionId || sessionId === "info") {
+      return (
+        <div class="right-panel-empty right-panel-empty--left">
+          <span class="text-xs">{props.t("instanceShell.sessionChanges.noSessionSelected")}</span>
+        </div>
+      )
+    }
+
+    const diffs = props.activeSessionDiffs()
+    if (diffs === undefined) {
+      return (
+        <div class="right-panel-empty right-panel-empty--left">
+          <span class="text-xs">{props.t("instanceShell.sessionChanges.loading")}</span>
+        </div>
+      )
+    }
+
+    if (!Array.isArray(diffs) || diffs.length === 0) {
+      return (
+        <div class="right-panel-empty right-panel-empty--left">
+          <span class="text-xs">{props.t("instanceShell.sessionChanges.empty")}</span>
+        </div>
+      )
+    }
+
+    const sorted = [...diffs].sort((a, b) => String(a.file || "").localeCompare(String(b.file || "")))
+    const totals = sorted.reduce(
+      (acc, item) => {
+        acc.additions += typeof item.additions === "number" ? item.additions : 0
+        acc.deletions += typeof item.deletions === "number" ? item.deletions : 0
+        return acc
+      },
+      { additions: 0, deletions: 0 },
+    )
+
+    return (
+      <div class="flex flex-col gap-3 min-h-0">
+        <div class="flex items-center justify-between gap-2 text-[11px] text-secondary">
+          <span>{props.t("instanceShell.sessionChanges.filesChanged", { count: sorted.length })}</span>
+          <span class="flex items-center gap-2">
+            <span style={{ color: "var(--session-status-idle-fg)" }}>{`+${totals.additions}`}</span>
+            <span style={{ color: "var(--session-status-working-fg)" }}>{`-${totals.deletions}`}</span>
+          </span>
+        </div>
+
+        <div class="rounded-md border border-base bg-surface-secondary p-2 max-h-[40vh] overflow-y-auto">
+          <div class="flex flex-col">
+            <For each={sorted}>
+              {(item) => (
+                <button
+                  type="button"
+                  class="border-b border-base last:border-b-0 text-left hover:bg-surface-muted rounded-sm"
+                  onClick={() => props.onOpenChangesTab(item.file)}
+                  title={props.t("instanceShell.sessionChanges.actions.show")}
+                >
+                  <div class="flex items-center justify-between gap-3">
+                    <div
+                      class="text-xs font-mono text-primary min-w-0 flex-1 overflow-hidden whitespace-nowrap"
+                      title={item.file}
+                      style="text-overflow: ellipsis; direction: rtl; text-align: left; unicode-bidi: plaintext;"
+                    >
+                      {item.file}
+                    </div>
+                    <div class="flex items-center gap-2 text-[11px] flex-shrink-0">
+                      <span style={{ color: "var(--session-status-idle-fg)" }}>{`+${item.additions}`}</span>
+                      <span style={{ color: "var(--session-status-working-fg)" }}>{`-${item.deletions}`}</span>
+                    </div>
+                  </div>
+                </button>
+              )}
+            </For>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  const renderPlanSectionContent = () => {
+    const sessionId = props.activeSessionId()
+    if (!sessionId || sessionId === "info") {
+      return (
+        <div class="right-panel-empty right-panel-empty--left">
+          <span class="text-xs">{props.t("instanceShell.plan.noSessionSelected")}</span>
+        </div>
+      )
+    }
+    const todoState = props.latestTodoState()
+    if (!todoState) {
+      return (
+        <div class="right-panel-empty right-panel-empty--left">
+          <span class="text-xs">{props.t("instanceShell.plan.empty")}</span>
+        </div>
+      )
+    }
+    return <TodoListView state={todoState} emptyLabel={props.t("instanceShell.plan.empty")} showStatusLabel={false} />
+  }
+
+  const renderBackgroundProcesses = () => {
+    const processes = props.backgroundProcessList()
+    if (processes.length === 0) {
+      return (
+        <div class="right-panel-empty right-panel-empty--left">
+          <span class="text-xs">{props.t("instanceShell.backgroundProcesses.empty")}</span>
+        </div>
+      )
+    }
+
+    return (
+      <div class="flex flex-col gap-2">
+        <For each={processes}>
+          {(process) => (
+            <div class="status-process-card">
+              <div class="status-process-header">
+                <span class="status-process-title">{process.title}</span>
+                <div class="status-process-meta">
+                  <span>{props.t("instanceShell.backgroundProcesses.status", { status: process.status })}</span>
+                  <Show when={typeof process.outputSizeBytes === "number"}>
+                    <span>
+                      {props.t("instanceShell.backgroundProcesses.output", {
+                        sizeKb: Math.round((process.outputSizeBytes ?? 0) / 1024),
+                      })}
+                    </span>
+                  </Show>
+                </div>
+              </div>
+              <div class="status-process-actions">
+                <button
+                  type="button"
+                  class="button-tertiary w-full p-1 inline-flex items-center justify-center"
+                  onClick={() => props.onOpenBackgroundOutput(process)}
+                  aria-label={props.t("instanceShell.backgroundProcesses.actions.output")}
+                  title={props.t("instanceShell.backgroundProcesses.actions.output")}
+                >
+                  <TerminalSquare class="h-4 w-4" />
+                </button>
+                <button
+                  type="button"
+                  class="button-tertiary w-full p-1 inline-flex items-center justify-center"
+                  disabled={process.status !== "running"}
+                  onClick={() => props.onStopBackgroundProcess(process.id)}
+                  aria-label={props.t("instanceShell.backgroundProcesses.actions.stop")}
+                  title={props.t("instanceShell.backgroundProcesses.actions.stop")}
+                >
+                  <XOctagon class="h-4 w-4" />
+                </button>
+                <button
+                  type="button"
+                  class="button-tertiary w-full p-1 inline-flex items-center justify-center"
+                  onClick={() => props.onTerminateBackgroundProcess(process.id)}
+                  aria-label={props.t("instanceShell.backgroundProcesses.actions.terminate")}
+                  title={props.t("instanceShell.backgroundProcesses.actions.terminate")}
+                >
+                  <Trash2 class="h-4 w-4" />
+                </button>
+              </div>
+            </div>
+          )}
+        </For>
+      </div>
+    )
+  }
+
+  const statusSections = [
+    {
+      id: "session-changes",
+      labelKey: "instanceShell.rightPanel.sections.sessionChanges",
+      render: renderStatusSessionChanges,
+    },
+    {
+      id: "plan",
+      labelKey: "instanceShell.rightPanel.sections.plan",
+      render: renderPlanSectionContent,
+    },
+    {
+      id: "background-processes",
+      labelKey: "instanceShell.rightPanel.sections.backgroundProcesses",
+      render: renderBackgroundProcesses,
+    },
+    {
+      id: "mcp",
+      labelKey: "instanceShell.rightPanel.sections.mcp",
+      render: () => (
+        <InstanceServiceStatus
+          initialInstance={props.instance}
+          sections={["mcp"]}
+          showSectionHeadings={false}
+          class="space-y-2"
+        />
+      ),
+    },
+    {
+      id: "lsp",
+      labelKey: "instanceShell.rightPanel.sections.lsp",
+      render: () => (
+        <InstanceServiceStatus
+          initialInstance={props.instance}
+          sections={["lsp"]}
+          showSectionHeadings={false}
+          class="space-y-2"
+        />
+      ),
+    },
+    {
+      id: "plugins",
+      labelKey: "instanceShell.rightPanel.sections.plugins",
+      render: () => (
+        <InstanceServiceStatus
+          initialInstance={props.instance}
+          sections={["plugins"]}
+          showSectionHeadings={false}
+          class="space-y-2"
+        />
+      ),
+    },
+  ]
+
+  return (
+    <div class="status-tab-container">
+      <Show when={props.activeSession()}>
+        {(activeSession) => (
+          <ContextUsagePanel instanceId={props.instanceId} sessionId={activeSession().id} class="status-tab-context-panel" />
+        )}
+      </Show>
+
+      <Accordion.Root
+        class="right-panel-accordion"
+        collapsible
+        multiple
+        value={props.expandedItems()}
+        onChange={props.onExpandedItemsChange}
+      >
+        <For each={statusSections}>
+          {(section) => (
+            <Accordion.Item value={section.id} class="right-panel-accordion-item">
+              <Accordion.Header>
+                <Accordion.Trigger class="right-panel-accordion-trigger">
+                  <span>{props.t(section.labelKey)}</span>
+                  <ChevronDown
+                    class={`right-panel-accordion-chevron ${isSectionExpanded(section.id) ? "right-panel-accordion-chevron-expanded" : ""}`}
+                  />
+                </Accordion.Trigger>
+              </Accordion.Header>
+              <Accordion.Content class="right-panel-accordion-content">{section.render()}</Accordion.Content>
+            </Accordion.Item>
+          )}
+        </For>
+      </Accordion.Root>
+    </div>
+  )
+}
+
+export default StatusTab

packages/ui/src/components/instance/shell/right-panel/types.ts

@@ -0,0 +1,5 @@
+export type RightPanelTab = "changes" | "git-changes" | "files" | "status"
+
+export type DiffViewMode = "split" | "unified"
+
+export type DiffContextMode = "expanded" | "collapsed"

packages/ui/src/components/instance/shell/storage.ts

@@ -0,0 +1,92 @@
+export const DEFAULT_SESSION_SIDEBAR_WIDTH = 340
+export const MIN_SESSION_SIDEBAR_WIDTH = 220
+export const MAX_SESSION_SIDEBAR_WIDTH = 400
+
+export const RIGHT_DRAWER_WIDTH = 260
+export const MIN_RIGHT_DRAWER_WIDTH = 200
+export const MAX_RIGHT_DRAWER_WIDTH = 1200
+
+export const LEFT_DRAWER_STORAGE_KEY = "opencode-session-sidebar-width-v8"
+export const RIGHT_DRAWER_STORAGE_KEY = "opencode-session-right-drawer-width-v1"
+export const LEFT_PIN_STORAGE_KEY = "opencode-session-left-drawer-pinned-v1"
+export const RIGHT_PIN_STORAGE_KEY = "opencode-session-right-drawer-pinned-v1"
+export const RIGHT_PANEL_TAB_STORAGE_KEY = "opencode-session-right-panel-tab-v2"
+export const LEGACY_RIGHT_PANEL_TAB_STORAGE_KEY = "opencode-session-right-panel-tab-v1"
+export const RIGHT_PANEL_CHANGES_SPLIT_WIDTH_KEY = "opencode-session-right-panel-changes-split-width-v1"
+export const RIGHT_PANEL_FILES_SPLIT_WIDTH_KEY = "opencode-session-right-panel-files-split-width-v1"
+export const RIGHT_PANEL_GIT_CHANGES_SPLIT_WIDTH_KEY = "opencode-session-right-panel-git-changes-split-width-v1"
+export const RIGHT_PANEL_CHANGES_LIST_OPEN_NONPHONE_KEY = "opencode-session-right-panel-changes-list-open-nonphone-v1"
+export const RIGHT_PANEL_CHANGES_LIST_OPEN_PHONE_KEY = "opencode-session-right-panel-changes-list-open-phone-v1"
+export const RIGHT_PANEL_FILES_LIST_OPEN_NONPHONE_KEY = "opencode-session-right-panel-files-list-open-nonphone-v1"
+export const RIGHT_PANEL_FILES_LIST_OPEN_PHONE_KEY = "opencode-session-right-panel-files-list-open-phone-v1"
+export const RIGHT_PANEL_GIT_CHANGES_LIST_OPEN_NONPHONE_KEY = "opencode-session-right-panel-git-changes-list-open-nonphone-v1"
+export const RIGHT_PANEL_GIT_CHANGES_LIST_OPEN_PHONE_KEY = "opencode-session-right-panel-git-changes-list-open-phone-v1"
+export const RIGHT_PANEL_CHANGES_DIFF_VIEW_MODE_KEY = "opencode-session-right-panel-changes-diff-view-mode-v1"
+export const RIGHT_PANEL_CHANGES_DIFF_CONTEXT_MODE_KEY = "opencode-session-right-panel-changes-diff-context-mode-v1"
+
+export const clampWidth = (value: number) =>
+  Math.min(MAX_SESSION_SIDEBAR_WIDTH, Math.max(MIN_SESSION_SIDEBAR_WIDTH, value))
+
+export const clampRightWidth = (value: number) => {
+  const windowMax = typeof window !== "undefined" ? Math.floor(window.innerWidth * 0.7) : MAX_RIGHT_DRAWER_WIDTH
+  const max = Math.max(MIN_RIGHT_DRAWER_WIDTH, windowMax)
+  return Math.min(max, Math.max(MIN_RIGHT_DRAWER_WIDTH, value))
+}
+
+const getPinStorageKey = (side: "left" | "right") => (side === "left" ? LEFT_PIN_STORAGE_KEY : RIGHT_PIN_STORAGE_KEY)
+
+export function readStoredPinState(side: "left" | "right", defaultValue: boolean) {
+  if (typeof window === "undefined") return defaultValue
+  const stored = window.localStorage.getItem(getPinStorageKey(side))
+  if (stored === "true") return true
+  if (stored === "false") return false
+  return defaultValue
+}
+
+export function persistPinState(side: "left" | "right", value: boolean) {
+  if (typeof window === "undefined") return
+  window.localStorage.setItem(getPinStorageKey(side), value ? "true" : "false")
+}
+
+export function readStoredRightPanelTab(
+  defaultValue: "changes" | "git-changes" | "files" | "status",
+): "changes" | "git-changes" | "files" | "status" {
+  if (typeof window === "undefined") return defaultValue
+
+  const stored = window.localStorage.getItem(RIGHT_PANEL_TAB_STORAGE_KEY)
+  if (stored === "status") return "status"
+  if (stored === "changes") return "changes"
+  if (stored === "git-changes") return "git-changes"
+  if (stored === "files") return "files"
+
+  // Migrate from v1 (where the stored values were the internal tab ids).
+  const legacy = window.localStorage.getItem(LEGACY_RIGHT_PANEL_TAB_STORAGE_KEY)
+  if (legacy === "status") return "status"
+  if (legacy === "browser") return "files"
+  if (legacy === "files") return "changes"
+
+  return defaultValue
+}
+
+export function readStoredPanelWidth(key: string, fallback: number) {
+  if (typeof window === "undefined") return fallback
+  const stored = window.localStorage.getItem(key)
+  if (!stored) return fallback
+  const parsed = Number.parseInt(stored, 10)
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+
+export function readStoredBool(key: string): boolean | null {
+  if (typeof window === "undefined") return null
+  const stored = window.localStorage.getItem(key)
+  if (stored === "true") return true
+  if (stored === "false") return false
+  return null
+}
+
+export function readStoredEnum<T extends string>(key: string, allowed: readonly T[]): T | null {
+  if (typeof window === "undefined") return null
+  const stored = window.localStorage.getItem(key)
+  if (!stored) return null
+  return (allowed as readonly string[]).includes(stored) ? (stored as T) : null
+}

packages/ui/src/components/instance/shell/types.ts

@@ -0,0 +1,3 @@
+export type LayoutMode = "desktop" | "tablet" | "phone"
+
+export type DrawerViewState = "pinned" | "floating-open" | "floating-closed"

packages/ui/src/components/instance/shell/useDrawerChrome.ts

@@ -0,0 +1,260 @@
+import {
+  batch,
+  createComponent,
+  createEffect,
+  createMemo,
+  createSignal,
+  onCleanup,
+  onMount,
+  type Accessor,
+  type JSX,
+  type Setter,
+} from "solid-js"
+import MenuIcon from "@suid/icons-material/Menu"
+
+import type { TranslateParams } from "../../../lib/i18n"
+
+import type { DrawerViewState, LayoutMode } from "./types"
+import { persistPinState, readStoredPinState } from "./storage"
+
+export interface UseDrawerChromeOptions {
+  t: (key: string, params?: TranslateParams) => string
+  layoutMode: Accessor<LayoutMode>
+  leftPinningSupported: Accessor<boolean>
+  rightPinningSupported: Accessor<boolean>
+  leftDrawerContentEl: Accessor<HTMLElement | null>
+  rightDrawerContentEl: Accessor<HTMLElement | null>
+  leftToggleButtonEl: Accessor<HTMLElement | null>
+  rightToggleButtonEl: Accessor<HTMLElement | null>
+  measureDrawerHost?: () => void
+}
+
+export interface DrawerChromeApi {
+  leftPinned: Accessor<boolean>
+  leftOpen: Accessor<boolean>
+  rightPinned: Accessor<boolean>
+  rightOpen: Accessor<boolean>
+  setLeftOpen: Setter<boolean>
+  setRightOpen: Setter<boolean>
+  leftDrawerState: Accessor<DrawerViewState>
+  rightDrawerState: Accessor<DrawerViewState>
+  pinLeft: () => void
+  unpinLeft: () => void
+  pinRight: () => void
+  unpinRight: () => void
+  closeLeft: () => void
+  closeRight: () => void
+  leftAppBarButtonLabel: Accessor<string>
+  rightAppBarButtonLabel: Accessor<string>
+  leftAppBarButtonIcon: Accessor<JSX.Element>
+  rightAppBarButtonIcon: Accessor<JSX.Element>
+  handleLeftAppBarButtonClick: () => void
+  handleRightAppBarButtonClick: () => void
+}
+
+export function useDrawerChrome(options: UseDrawerChromeOptions): DrawerChromeApi {
+  const [leftPinned, setLeftPinned] = createSignal(true)
+  const [leftOpen, setLeftOpen] = createSignal(true)
+  const [rightPinned, setRightPinned] = createSignal(true)
+  const [rightOpen, setRightOpen] = createSignal(true)
+
+  const measureDrawerHost = () => options.measureDrawerHost?.()
+
+  const focusTarget = (element: HTMLElement | null) => {
+    if (!element) return
+    requestAnimationFrame(() => {
+      element.focus()
+    })
+  }
+
+  const blurIfInside = (element: HTMLElement | null) => {
+    if (typeof document === "undefined" || !element) return
+    const active = document.activeElement as HTMLElement | null
+    if (active && element.contains(active)) {
+      active.blur()
+    }
+  }
+
+  const persistPinIfSupported = (side: "left" | "right", value: boolean) => {
+    if (side === "left" && !options.leftPinningSupported()) return
+    if (side === "right" && !options.rightPinningSupported()) return
+    persistPinState(side, value)
+  }
+
+  createEffect(() => {
+    switch (options.layoutMode()) {
+      case "desktop": {
+        const leftSaved = readStoredPinState("left", true)
+        const rightSaved = readStoredPinState("right", true)
+        setLeftPinned(leftSaved)
+        setLeftOpen(leftSaved)
+        setRightPinned(rightSaved)
+        setRightOpen(rightSaved)
+        break
+      }
+      case "tablet": {
+        setLeftPinned(true)
+        setLeftOpen(true)
+        setRightPinned(false)
+        setRightOpen(false)
+        break
+      }
+      default:
+        setLeftPinned(false)
+        setLeftOpen(false)
+        setRightPinned(false)
+        setRightOpen(false)
+        break
+    }
+  })
+
+  const leftDrawerState = createMemo<DrawerViewState>(() => {
+    if (leftPinned()) return "pinned"
+    return leftOpen() ? "floating-open" : "floating-closed"
+  })
+
+  const rightDrawerState = createMemo<DrawerViewState>(() => {
+    if (rightPinned()) return "pinned"
+    return rightOpen() ? "floating-open" : "floating-closed"
+  })
+
+  const leftAppBarButtonLabel = () => {
+    const state = leftDrawerState()
+    if (state === "pinned") return options.t("instanceShell.leftDrawer.toggle.pinned")
+    return options.t("instanceShell.leftDrawer.toggle.open")
+  }
+
+  const rightAppBarButtonLabel = () => {
+    const state = rightDrawerState()
+    if (state === "pinned") return options.t("instanceShell.rightDrawer.toggle.pinned")
+    return options.t("instanceShell.rightDrawer.toggle.open")
+  }
+
+  const leftAppBarButtonIcon = () => {
+    return createComponent(MenuIcon, { fontSize: "small" })
+  }
+
+  const rightAppBarButtonIcon = () => {
+    return createComponent(MenuIcon, { fontSize: "small", sx: { transform: "scaleX(-1)" } })
+  }
+
+  const pinLeft = () => {
+    blurIfInside(options.leftDrawerContentEl())
+    batch(() => {
+      setLeftPinned(true)
+      setLeftOpen(true)
+    })
+    persistPinIfSupported("left", true)
+    measureDrawerHost()
+  }
+
+  const unpinLeft = () => {
+    blurIfInside(options.leftDrawerContentEl())
+    batch(() => {
+      setLeftPinned(false)
+      setLeftOpen(true)
+    })
+    persistPinIfSupported("left", false)
+    measureDrawerHost()
+  }
+
+  const pinRight = () => {
+    blurIfInside(options.rightDrawerContentEl())
+    batch(() => {
+      setRightPinned(true)
+      setRightOpen(true)
+    })
+    persistPinIfSupported("right", true)
+    measureDrawerHost()
+  }
+
+  const unpinRight = () => {
+    blurIfInside(options.rightDrawerContentEl())
+    batch(() => {
+      setRightPinned(false)
+      setRightOpen(true)
+    })
+    persistPinIfSupported("right", false)
+    measureDrawerHost()
+  }
+
+  const handleLeftAppBarButtonClick = () => {
+    const state = leftDrawerState()
+    if (state !== "floating-closed") return
+    setLeftOpen(true)
+    measureDrawerHost()
+  }
+
+  const handleRightAppBarButtonClick = () => {
+    const state = rightDrawerState()
+    if (state !== "floating-closed") return
+    setRightOpen(true)
+    measureDrawerHost()
+  }
+
+  const closeLeft = () => {
+    if (leftDrawerState() === "pinned") return
+    blurIfInside(options.leftDrawerContentEl())
+    setLeftOpen(false)
+    focusTarget(options.leftToggleButtonEl())
+  }
+
+  const closeRight = () => {
+    if (rightDrawerState() === "pinned") return
+    blurIfInside(options.rightDrawerContentEl())
+    setRightOpen(false)
+    focusTarget(options.rightToggleButtonEl())
+  }
+
+  const closeFloatingDrawersIfAny = () => {
+    let handled = false
+    if (!leftPinned() && leftOpen()) {
+      setLeftOpen(false)
+      blurIfInside(options.leftDrawerContentEl())
+      focusTarget(options.leftToggleButtonEl())
+      handled = true
+    }
+    if (!rightPinned() && rightOpen()) {
+      setRightOpen(false)
+      blurIfInside(options.rightDrawerContentEl())
+      focusTarget(options.rightToggleButtonEl())
+      handled = true
+    }
+    return handled
+  }
+
+  onMount(() => {
+    if (typeof window === "undefined") return
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key !== "Escape") return
+      if (!closeFloatingDrawersIfAny()) return
+      event.preventDefault()
+      event.stopPropagation()
+    }
+    window.addEventListener("keydown", handleEscape, true)
+    onCleanup(() => window.removeEventListener("keydown", handleEscape, true))
+  })
+
+  return {
+    leftPinned,
+    leftOpen,
+    rightPinned,
+    rightOpen,
+    setLeftOpen,
+    setRightOpen,
+    leftDrawerState,
+    rightDrawerState,
+    pinLeft,
+    unpinLeft,
+    pinRight,
+    unpinRight,
+    closeLeft,
+    closeRight,
+    leftAppBarButtonLabel,
+    rightAppBarButtonLabel,
+    leftAppBarButtonIcon,
+    rightAppBarButtonIcon,
+    handleLeftAppBarButtonClick,
+    handleRightAppBarButtonClick,
+  }
+}

packages/ui/src/components/instance/shell/useDrawerHostMeasure.ts

@@ -0,0 +1,65 @@
+import { createEffect, createSignal, type Accessor } from "solid-js"
+
+type DrawerHostMeasure = {
+  setDrawerHost: (element: HTMLElement) => void
+  drawerContainer: () => HTMLElement | undefined
+  measureDrawerHost: () => void
+  floatingTopPx: () => string
+  floatingHeight: () => string
+}
+
+export function useDrawerHostMeasure(tabBarOffset: Accessor<number>): DrawerHostMeasure {
+  const [drawerHost, setDrawerHost] = createSignal<HTMLElement | null>(null)
+  const [floatingDrawerTop, setFloatingDrawerTop] = createSignal(0)
+  const [floatingDrawerHeight, setFloatingDrawerHeight] = createSignal(0)
+
+  const storeDrawerHost = (element: HTMLElement) => {
+    setDrawerHost(element)
+  }
+
+  const measureDrawerHost = () => {
+    if (typeof window === "undefined") return
+    const host = drawerHost()
+    if (!host) return
+    const rect = host.getBoundingClientRect()
+    setFloatingDrawerTop(rect.top)
+    setFloatingDrawerHeight(Math.max(0, rect.height))
+  }
+
+  createEffect(() => {
+    tabBarOffset()
+    if (typeof window === "undefined") return
+    requestAnimationFrame(() => measureDrawerHost())
+  })
+
+  const drawerContainer = () => {
+    const host = drawerHost()
+    if (host) return host
+    if (typeof document !== "undefined") {
+      return document.body
+    }
+    return undefined
+  }
+
+  const fallbackDrawerTop = () => tabBarOffset()
+  const floatingTop = () => {
+    const measured = floatingDrawerTop()
+    if (measured > 0) return measured
+    return fallbackDrawerTop()
+  }
+
+  const floatingTopPx = () => `${floatingTop()}px`
+  const floatingHeight = () => {
+    const measured = floatingDrawerHeight()
+    if (measured > 0) return `${measured}px`
+    return `calc(100% - ${floatingTop()}px)`
+  }
+
+  return {
+    setDrawerHost: storeDrawerHost,
+    drawerContainer,
+    measureDrawerHost,
+    floatingTopPx,
+    floatingHeight,
+  }
+}

packages/ui/src/components/instance/shell/useDrawerResize.ts

@@ -0,0 +1,113 @@
+import { createSignal, onCleanup, type Accessor, type Setter } from "solid-js"
+
+import { useGlobalPointerDrag } from "./useGlobalPointerDrag"
+
+type DrawerResizeSide = "left" | "right"
+
+type DrawerResizeOptions = {
+  sessionSidebarWidth: Accessor<number>
+  rightDrawerWidth: Accessor<number>
+  setSessionSidebarWidth: Setter<number>
+  setRightDrawerWidth: Setter<number>
+  clampLeft: (width: number) => number
+  clampRight: (width: number) => number
+  measureDrawerHost: () => void
+}
+
+type DrawerResizeApi = {
+  handleDrawerResizeMouseDown: (side: DrawerResizeSide) => (event: MouseEvent) => void
+  handleDrawerResizeTouchStart: (side: DrawerResizeSide) => (event: TouchEvent) => void
+}
+
+export function useDrawerResize(options: DrawerResizeOptions): DrawerResizeApi {
+  const [activeResizeSide, setActiveResizeSide] = createSignal<DrawerResizeSide | null>(null)
+  const [resizeStartX, setResizeStartX] = createSignal(0)
+  const [resizeStartWidth, setResizeStartWidth] = createSignal(0)
+
+  const scheduleDrawerMeasure = () => {
+    if (typeof window === "undefined") {
+      options.measureDrawerHost()
+      return
+    }
+    requestAnimationFrame(() => options.measureDrawerHost())
+  }
+
+  const applyDrawerWidth = (side: DrawerResizeSide, width: number) => {
+    if (side === "left") {
+      options.setSessionSidebarWidth(width)
+    } else {
+      options.setRightDrawerWidth(width)
+    }
+    scheduleDrawerMeasure()
+  }
+
+  const handleDrawerPointerMove = (clientX: number) => {
+    const side = activeResizeSide()
+    if (!side) return
+    const startWidth = resizeStartWidth()
+    const clamp = side === "left" ? options.clampLeft : options.clampRight
+    const delta = side === "left" ? clientX - resizeStartX() : resizeStartX() - clientX
+    const nextWidth = clamp(startWidth + delta)
+    applyDrawerWidth(side, nextWidth)
+  }
+
+  function drawerMouseMove(event: MouseEvent) {
+    event.preventDefault()
+    handleDrawerPointerMove(event.clientX)
+  }
+
+  function drawerMouseUp() {
+    stopDrawerResize()
+  }
+
+  function drawerTouchMove(event: TouchEvent) {
+    const touch = event.touches[0]
+    if (!touch) return
+    event.preventDefault()
+    handleDrawerPointerMove(touch.clientX)
+  }
+
+  function drawerTouchEnd() {
+    stopDrawerResize()
+  }
+
+  const drawerPointerDrag = useGlobalPointerDrag({
+    onMouseMove: drawerMouseMove,
+    onMouseUp: drawerMouseUp,
+    onTouchMove: drawerTouchMove,
+    onTouchEnd: drawerTouchEnd,
+  })
+
+  function stopDrawerResize() {
+    setActiveResizeSide(null)
+    drawerPointerDrag.stop()
+  }
+
+  const startDrawerResize = (side: DrawerResizeSide, clientX: number) => {
+    setActiveResizeSide(side)
+    setResizeStartX(clientX)
+    setResizeStartWidth(side === "left" ? options.sessionSidebarWidth() : options.rightDrawerWidth())
+    drawerPointerDrag.start()
+  }
+
+  const handleDrawerResizeMouseDown = (side: DrawerResizeSide) => (event: MouseEvent) => {
+    event.preventDefault()
+    startDrawerResize(side, event.clientX)
+  }
+
+  const handleDrawerResizeTouchStart = (side: DrawerResizeSide) => (event: TouchEvent) => {
+    const touch = event.touches[0]
+    if (!touch) return
+    event.preventDefault()
+    startDrawerResize(side, touch.clientX)
+  }
+
+  onCleanup(() => {
+    stopDrawerResize()
+  })
+
+  return {
+    handleDrawerResizeMouseDown,
+    handleDrawerResizeTouchStart,
+  }
+}

packages/ui/src/components/instance/shell/useGlobalPointerDrag.ts

@@ -0,0 +1,29 @@
+type GlobalPointerDragHandlers = {
+  onMouseMove: (event: MouseEvent) => void
+  onMouseUp: (event: MouseEvent) => void
+  onTouchMove: (event: TouchEvent) => void
+  onTouchEnd: (event: TouchEvent) => void
+}
+
+type GlobalPointerDrag = {
+  start: () => void
+  stop: () => void
+}
+
+export function useGlobalPointerDrag(handlers: GlobalPointerDragHandlers): GlobalPointerDrag {
+  const start = () => {
+    document.addEventListener("mousemove", handlers.onMouseMove)
+    document.addEventListener("mouseup", handlers.onMouseUp)
+    document.addEventListener("touchmove", handlers.onTouchMove, { passive: false })
+    document.addEventListener("touchend", handlers.onTouchEnd)
+  }
+
+  const stop = () => {
+    document.removeEventListener("mousemove", handlers.onMouseMove)
+    document.removeEventListener("mouseup", handlers.onMouseUp)
+    document.removeEventListener("touchmove", handlers.onTouchMove)
+    document.removeEventListener("touchend", handlers.onTouchEnd)
+  }
+
+  return { start, stop }
+}

packages/ui/src/components/instance/shell/useInstanceSessionContext.ts

@@ -0,0 +1,173 @@
+import { batch, createMemo, type Accessor } from "solid-js"
+import type { ToolState } from "@opencode-ai/sdk"
+import type { Session } from "../../../types/session"
+import {
+  activeParentSessionId,
+  activeSessionId as activeSessionMap,
+  getSessionFamily,
+  getSessionInfo,
+  getSessionThreads,
+  sessions,
+  setActiveParentSession,
+  setActiveSession,
+} from "../../../stores/sessions"
+import { messageStoreBus } from "../../../stores/message-v2/bus"
+import { getBackgroundProcesses } from "../../../stores/background-processes"
+import type { LatestTodoSnapshot, SessionUsageState } from "../../../stores/message-v2/types"
+
+type InstanceSessionContextOptions = {
+  instanceId: Accessor<string>
+}
+
+type InstanceSessionContextState = {
+  // Session collections and selections
+  allInstanceSessions: Accessor<Map<string, Session>>
+  sessionThreads: Accessor<ReturnType<typeof getSessionThreads>>
+  activeSessions: Accessor<Map<string, SessionFamilyMember>>
+  activeSessionIdForInstance: Accessor<string | null>
+  parentSessionIdForInstance: Accessor<string | null>
+  activeSessionForInstance: Accessor<SessionFamilyMember | null>
+  activeSessionDiffs: Accessor<SessionFamilyMember["diff"] | undefined>
+
+  // Usage / info summaries
+  activeSessionUsage: Accessor<SessionUsageState | null>
+  activeSessionInfoDetails: Accessor<ReturnType<typeof getSessionInfo> | null>
+  tokenStats: Accessor<{ used: number; avail: number | null }>
+
+  // Todo state
+  latestTodoSnapshot: Accessor<LatestTodoSnapshot | null>
+  latestTodoState: Accessor<ToolState | null>
+
+  // Background processes
+  backgroundProcessList: Accessor<ReturnType<typeof getBackgroundProcesses>>
+
+  // Controller
+  handleSessionSelect: (sessionId: string) => void
+}
+
+type SessionFamilyMember = ReturnType<typeof getSessionFamily>[number]
+
+export function useInstanceSessionContext(options: InstanceSessionContextOptions): InstanceSessionContextState {
+  const messageStore = createMemo(() => messageStoreBus.getOrCreate(options.instanceId()))
+
+  const allInstanceSessions = createMemo<Map<string, Session>>(() => {
+    return sessions().get(options.instanceId()) ?? new Map()
+  })
+
+  const sessionThreads = createMemo(() => getSessionThreads(options.instanceId()))
+
+  const activeSessions = createMemo(() => {
+    const parentId = activeParentSessionId().get(options.instanceId())
+    if (!parentId) return new Map<string, ReturnType<typeof getSessionFamily>[number]>()
+    const sessionFamily = getSessionFamily(options.instanceId(), parentId)
+    return new Map(sessionFamily.map((s) => [s.id, s]))
+  })
+
+  const activeSessionIdForInstance = createMemo(() => {
+    return activeSessionMap().get(options.instanceId()) || null
+  })
+
+  const parentSessionIdForInstance = createMemo(() => {
+    return activeParentSessionId().get(options.instanceId()) || null
+  })
+
+  const activeSessionForInstance = createMemo(() => {
+    const sessionId = activeSessionIdForInstance()
+    if (!sessionId || sessionId === "info") return null
+    return activeSessions().get(sessionId) ?? null
+  })
+
+  const activeSessionDiffs = createMemo(() => {
+    const session = activeSessionForInstance()
+    return session?.diff
+  })
+
+  const activeSessionUsage = createMemo(() => {
+    const sessionId = activeSessionIdForInstance()
+    if (!sessionId) return null
+    const store = messageStore()
+    return store?.getSessionUsage(sessionId) ?? null
+  })
+
+  const activeSessionInfoDetails = createMemo(() => {
+    const sessionId = activeSessionIdForInstance()
+    if (!sessionId) return null
+    return getSessionInfo(options.instanceId(), sessionId) ?? null
+  })
+
+  const tokenStats = createMemo(() => {
+    const usage = activeSessionUsage()
+    const info = activeSessionInfoDetails()
+    return {
+      used: usage?.actualUsageTokens ?? info?.actualUsageTokens ?? 0,
+      avail: info?.contextAvailableTokens ?? null,
+    }
+  })
+
+  const latestTodoSnapshot = createMemo(() => {
+    const sessionId = activeSessionIdForInstance()
+    if (!sessionId || sessionId === "info") return null
+    const store = messageStore()
+    if (!store) return null
+    const snapshot = store.state.latestTodos[sessionId]
+    return snapshot ?? null
+  })
+
+  const latestTodoState = createMemo<ToolState | null>(() => {
+    const snapshot = latestTodoSnapshot()
+    if (!snapshot) return null
+    const store = messageStore()
+    if (!store) return null
+    const message = store.getMessage(snapshot.messageId)
+    if (!message) return null
+    const partRecord = message.parts?.[snapshot.partId]
+    const part = partRecord?.data as { type?: string; tool?: string; state?: ToolState }
+    if (!part || part.type !== "tool" || part.tool !== "todowrite") return null
+    const state = part.state
+    if (!state || state.status !== "completed") return null
+    return state
+  })
+
+  const backgroundProcessList = createMemo(() => getBackgroundProcesses(options.instanceId()))
+
+  const handleSessionSelect = (sessionId: string) => {
+    const instanceId = options.instanceId()
+    if (sessionId === "info") {
+      setActiveSession(instanceId, sessionId)
+      return
+    }
+
+    const session = allInstanceSessions().get(sessionId)
+    if (!session) return
+
+    if (session.parentId === null) {
+      setActiveParentSession(instanceId, sessionId)
+      return
+    }
+
+    const parentId = session.parentId
+    if (!parentId) return
+
+    batch(() => {
+      setActiveParentSession(instanceId, parentId)
+      setActiveSession(instanceId, sessionId)
+    })
+  }
+
+  return {
+    allInstanceSessions,
+    sessionThreads,
+    activeSessions,
+    activeSessionIdForInstance,
+    parentSessionIdForInstance,
+    activeSessionForInstance,
+    activeSessionDiffs,
+    activeSessionUsage,
+    activeSessionInfoDetails,
+    tokenStats,
+    latestTodoSnapshot,
+    latestTodoState,
+    backgroundProcessList,
+    handleSessionSelect,
+  }
+}

packages/ui/src/components/instance/shell/useSessionCache.ts

@@ -0,0 +1,99 @@
+import { createEffect, createSignal, type Accessor } from "solid-js"
+import { messageStoreBus } from "../../../stores/message-v2/bus"
+import { clearSessionRenderCache } from "../../message-block"
+import { getLogger } from "../../../lib/logger"
+
+const log = getLogger("session")
+
+const SESSION_CACHE_LIMIT = 5
+
+type SessionCacheOptions = {
+  instanceId: Accessor<string>
+  instanceSessions: Accessor<Map<string, unknown>>
+  activeSessionId: Accessor<string | null>
+}
+
+type SessionCacheState = {
+  cachedSessionIds: Accessor<string[]>
+}
+
+export function useSessionCache(options: SessionCacheOptions): SessionCacheState {
+  const [cachedSessionIds, setCachedSessionIds] = createSignal<string[]>([])
+  const [pendingEvictions, setPendingEvictions] = createSignal<string[]>([])
+
+  const evictSession = (sessionId: string) => {
+    if (!sessionId) return
+    const instanceId = options.instanceId()
+    log.info("Evicting cached session", { instanceId, sessionId })
+    const store = messageStoreBus.getInstance(instanceId)
+    store?.clearSession(sessionId)
+    clearSessionRenderCache(instanceId, sessionId)
+  }
+
+  const scheduleEvictions = (ids: string[]) => {
+    if (!ids.length) return
+    setPendingEvictions((current) => {
+      const existing = new Set(current)
+      const next = [...current]
+      ids.forEach((id) => {
+        if (!existing.has(id)) {
+          next.push(id)
+          existing.add(id)
+        }
+      })
+      return next
+    })
+  }
+
+  createEffect(() => {
+    const pending = pendingEvictions()
+    if (!pending.length) return
+    const cached = new Set(cachedSessionIds())
+    const remaining: string[] = []
+    pending.forEach((id) => {
+      if (cached.has(id)) {
+        remaining.push(id)
+      } else {
+        evictSession(id)
+      }
+    })
+    if (remaining.length !== pending.length) {
+      setPendingEvictions(remaining)
+    }
+  })
+
+  createEffect(() => {
+    const instanceSessions = options.instanceSessions()
+    const activeId = options.activeSessionId()
+
+    setCachedSessionIds((current) => {
+      const next = current.filter((id) => id !== "info" && instanceSessions.has(id))
+
+      const touch = (id: string | null) => {
+        if (!id || id === "info") return
+        if (!instanceSessions.has(id)) return
+
+        const index = next.indexOf(id)
+        if (index !== -1) {
+          next.splice(index, 1)
+        }
+        next.unshift(id)
+      }
+
+      touch(activeId)
+
+      const trimmed = next.length > SESSION_CACHE_LIMIT ? next.slice(0, SESSION_CACHE_LIMIT) : next
+
+      const trimmedSet = new Set(trimmed)
+      const removed = current.filter((id) => !trimmedSet.has(id))
+      if (removed.length) {
+        scheduleEvictions(removed)
+      }
+      return trimmed
+    })
+  })
+
+  return {
+    cachedSessionIds,
+  }
+}

packages/ui/src/components/instance/shell/useSessionSidebarRequests.ts

@@ -0,0 +1,109 @@
+import { createEffect, createSignal, onCleanup, onMount, type Accessor } from "solid-js"
+import {
+  SESSION_SIDEBAR_EVENT,
+  type SessionSidebarRequestAction,
+  type SessionSidebarRequestDetail,
+} from "../../../lib/session-sidebar-events"
+
+interface PendingSidebarAction {
+  action: SessionSidebarRequestAction
+  id: number
+}
+
+interface UseSessionSidebarRequestsOptions {
+  instanceId: Accessor<string>
+  sidebarContentEl: Accessor<HTMLElement | null>
+  leftPinned: Accessor<boolean>
+  leftOpen: Accessor<boolean>
+  setLeftOpen: (next: boolean) => void
+  measureDrawerHost: () => void
+}
+
+export function useSessionSidebarRequests(options: UseSessionSidebarRequestsOptions) {
+  let sidebarActionId = 0
+  const [pendingSidebarAction, setPendingSidebarAction] = createSignal<PendingSidebarAction | null>(null)
+
+  const triggerKeyboardEvent = (target: HTMLElement, options: { key: string; code: string; keyCode: number }) => {
+    target.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key: options.key,
+        code: options.code,
+        keyCode: options.keyCode,
+        which: options.keyCode,
+        bubbles: true,
+        cancelable: true,
+      }),
+    )
+  }
+
+  const focusAgentSelectorControl = () => {
+    const agentTrigger = options.sidebarContentEl()?.querySelector("[data-agent-selector]") as HTMLElement | null
+    if (!agentTrigger) return false
+    agentTrigger.focus()
+    setTimeout(() => triggerKeyboardEvent(agentTrigger, { key: "Enter", code: "Enter", keyCode: 13 }), 10)
+    return true
+  }
+
+  const focusModelSelectorControl = () => {
+    const input = options.sidebarContentEl()?.querySelector<HTMLInputElement>("[data-model-selector]")
+    if (!input) return false
+    input.focus()
+    setTimeout(() => triggerKeyboardEvent(input, { key: "ArrowDown", code: "ArrowDown", keyCode: 40 }), 10)
+    return true
+  }
+
+  const focusVariantSelectorControl = () => {
+    const input = options.sidebarContentEl()?.querySelector<HTMLInputElement>("[data-thinking-selector]")
+    if (!input) return false
+    input.focus()
+    setTimeout(() => triggerKeyboardEvent(input, { key: "ArrowDown", code: "ArrowDown", keyCode: 40 }), 10)
+    return true
+  }
+
+  createEffect(() => {
+    const pending = pendingSidebarAction()
+    if (!pending) return
+    const action = pending.action
+    const contentReady = Boolean(options.sidebarContentEl())
+    if (!contentReady) {
+      return
+    }
+    if (action === "show-session-list") {
+      setPendingSidebarAction(null)
+      return
+    }
+    const handled =
+      action === "focus-agent-selector"
+        ? focusAgentSelectorControl()
+        : action === "focus-model-selector"
+          ? focusModelSelectorControl()
+          : focusVariantSelectorControl()
+    if (handled) {
+      setPendingSidebarAction(null)
+    }
+  })
+
+  const handleSidebarRequest = (action: SessionSidebarRequestAction) => {
+    setPendingSidebarAction({ action, id: sidebarActionId++ })
+    if (!options.leftPinned() && !options.leftOpen()) {
+      options.setLeftOpen(true)
+      options.measureDrawerHost()
+    }
+  }
+
+  onMount(() => {
+    if (typeof window === "undefined") return
+    const handler = (event: Event) => {
+      const detail = (event as CustomEvent<SessionSidebarRequestDetail>).detail
+      if (!detail || detail.instanceId !== options.instanceId()) return
+      handleSidebarRequest(detail.action)
+    }
+    window.addEventListener(SESSION_SIDEBAR_EVENT, handler)
+    onCleanup(() => window.removeEventListener(SESSION_SIDEBAR_EVENT, handler))
+  })
+
+  return {
+    handleSidebarRequest,
+    pendingSidebarAction,
+  }
+}

packages/ui/src/components/kbd.tsx

@@ -1,4 +1,5 @@
 import { Component, JSX, For } from "solid-js"
+import useMediaQuery from "@suid/material/useMediaQuery"
 import { isMac } from "../lib/keyboard-utils"
 
 interface KbdProps {
@@ -27,6 +28,9 @@ const SPECIAL_KEY_LABELS: Record<string, string> = {
 }
 
 const Kbd: Component<KbdProps> = (props) => {
+  const desktopQuery = useMediaQuery("(min-width: 1280px)")
+  if (!desktopQuery()) return null
+
   const parts = () => {
     if (props.children) return [{ text: props.children, isModifier: false }]
     if (!props.shortcut) return []

packages/ui/src/components/keyboard-hint.tsx

@@ -1,14 +1,20 @@
 import { Component, For } from "solid-js"
-import { formatShortcut, isMac } from "../lib/keyboard-utils"
+import useMediaQuery from "@suid/material/useMediaQuery"
 import type { KeyboardShortcut } from "../lib/keyboard-registry"
 import Kbd from "./kbd"
 import HintRow from "./hint-row"
 
 const KeyboardHint: Component<{
   shortcuts: KeyboardShortcut[]
-  separator?: string
+  separator?: string | null
   showDescription?: boolean
+  class?: string
+  ariaHidden?: boolean
 }> = (props) => {
+  // Centralize layout gating here so call sites don't need to.
+  // We only show keyboard hint UI on desktop layouts.
+  const desktopQuery = useMediaQuery("(min-width: 1280px)")
+
   function buildShortcutString(shortcut: KeyboardShortcut): string {
     const parts: string[] = []
 
@@ -26,12 +32,14 @@ const KeyboardHint: Component<{
     return parts.join("+")
   }
 
+  if (!desktopQuery()) return null
+
   return (
-    <HintRow>
+    <HintRow class={props.class} ariaHidden={props.ariaHidden}>
       <For each={props.shortcuts}>
         {(shortcut, i) => (
           <>
-            {i() > 0 && <span class="mx-1">{props.separator || "•"}</span>}
+            {i() > 0 && props.separator !== null && <span class="mx-1">{props.separator ?? "•"}</span>}
             {props.showDescription !== false && <span class="mr-1">{shortcut.description}</span>}
             <Kbd shortcut={buildShortcutString(shortcut)} />
           </>

packages/ui/src/components/markdown.tsx

@@ -1,5 +1,5 @@
 import { createEffect, createMemo, createSignal, onCleanup, onMount } from "solid-js"
-import { renderMarkdown, onLanguagesLoaded, decodeHtmlEntities } from "../lib/markdown"
+import { renderMarkdown, onLanguagesLoaded, decodeHtmlEntities, setMarkdownTheme } from "../lib/markdown"
 import { useGlobalCache } from "../lib/hooks/use-global-cache"
 import type { TextPart, RenderCache } from "../types/message"
 import { getLogger } from "../lib/logger"
@@ -72,6 +72,9 @@ export function Markdown(props: MarkdownProps) {
   createEffect(async () => {
     const { part, text, themeKey, highlightEnabled, version } = resolved()
 
+    // Ensure the markdown highlighter theme matches the active UI theme.
+    setMarkdownTheme(themeKey === "dark")
+
     latestRequestedText = text
 
     const cacheMatches = (cache: RenderCache | undefined) => {
@@ -171,6 +174,8 @@ export function Markdown(props: MarkdownProps) {
 
       const { part, text, themeKey, version } = resolved()
 
+      setMarkdownTheme(themeKey === "dark")
+
       if (latestRequestedText !== text) {
         return
       }

packages/ui/src/components/message-block.tsx

@@ -1,5 +1,5 @@
 import { For, Match, Show, Switch, createEffect, createMemo, createSignal, untrack } from "solid-js"
-import { FoldVertical } from "lucide-solid"
+import { ChevronsDownUp, ChevronsUpDown, ExternalLink, FoldVertical, Trash2 } from "lucide-solid"
 import MessageItem from "./message-item"
 import ToolCall from "./tool-call"
 import type { InstanceMessageStore } from "../stores/message-v2/instance-store"
@@ -11,6 +11,8 @@ import { messageStoreBus } from "../stores/message-v2/bus"
 import { formatTokenTotal } from "../lib/formatters"
 import { sessions, setActiveParentSession, setActiveSession } from "../stores/sessions"
 import { setActiveInstanceId } from "../stores/instances"
+import { showAlertDialog } from "../stores/alerts"
+import { deleteMessagePart } from "../stores/session-actions"
 import { useI18n } from "../lib/i18n"
 
 const TOOL_ICON = "🔧"
@@ -172,21 +174,256 @@ messageStoreBus.onInstanceDestroyed(clearInstanceCaches)
 interface ContentDisplayItem {
   type: "content"
   key: string
-  record: MessageRecord
-  parts: ClientPart[]
-  messageInfo?: MessageInfo
-  isQueued: boolean
-  showAgentMeta?: boolean
+  messageId: string
+  startPartId: string
 }
 
 interface ToolDisplayItem {
   type: "tool"
   key: string
-  toolPart: ToolCallPart
-  messageInfo?: MessageInfo
   messageId: string
-  messageVersion: number
-  partVersion: number
+  partId: string
+}
+
+interface MessageContentItemProps {
+  instanceId: string
+  sessionId: string
+  store: () => InstanceMessageStore
+  messageId: string
+  startPartId: string
+  messageIndex: number
+  lastAssistantIndex: () => number
+  onRevert?: (messageId: string) => void
+  onFork?: (messageId?: string) => void
+  onContentRendered?: () => void
+}
+
+function MessageContentItem(props: MessageContentItemProps) {
+  const record = createMemo(() => props.store().getMessage(props.messageId))
+  const messageInfo = createMemo(() => props.store().getMessageInfo(props.messageId))
+
+  const isQueued = createMemo(() => {
+    const current = record()
+    if (!current) return false
+    if (current.role !== "user") return false
+    const lastAssistant = props.lastAssistantIndex()
+    return lastAssistant === -1 || props.messageIndex > lastAssistant
+  })
+
+  const parts = createMemo<ClientPart[]>(() => {
+    const current = record()
+    if (!current) return []
+    const ids = current.partIds
+    const startIndex = ids.indexOf(props.startPartId)
+    if (startIndex === -1) return []
+
+    const resolved: ClientPart[] = []
+    for (let idx = startIndex; idx < ids.length; idx++) {
+      const partId = ids[idx]
+      const part = current.parts[partId]?.data
+      if (!part) continue
+      if (
+        part.type === "tool" ||
+        part.type === "reasoning" ||
+        part.type === "compaction" ||
+        part.type === "step-start" ||
+        part.type === "step-finish"
+      ) {
+        break
+      }
+      resolved.push(part)
+    }
+
+    return resolved
+  })
+
+  const showAgentMeta = createMemo(() => {
+    const current = record()
+    if (!current) return false
+    if (current.role !== "assistant") return false
+
+    const currentParts = parts()
+    if (!currentParts.some((part) => partHasRenderableText(part))) {
+      return false
+    }
+
+    const ids = current.partIds
+    const startIndex = ids.indexOf(props.startPartId)
+    if (startIndex === -1) return false
+
+    // Only show agent meta on the first content segment that contains renderable content.
+    for (let idx = 0; idx < startIndex; idx++) {
+      const partId = ids[idx]
+      const part = current.parts[partId]?.data
+      if (!part) continue
+      if (
+        part.type === "tool" ||
+        part.type === "reasoning" ||
+        part.type === "compaction" ||
+        part.type === "step-start" ||
+        part.type === "step-finish"
+      ) {
+        continue
+      }
+      if (partHasRenderableText(part)) {
+        return false
+      }
+    }
+
+    return true
+  })
+
+  return (
+    <Show when={record()}>
+      {(resolvedRecord) => (
+        <MessageItem
+          record={resolvedRecord()}
+          messageInfo={messageInfo()}
+          parts={parts()}
+          instanceId={props.instanceId}
+          sessionId={props.sessionId}
+          isQueued={isQueued()}
+          showAgentMeta={showAgentMeta()}
+          onRevert={props.onRevert}
+          onFork={props.onFork}
+          onContentRendered={props.onContentRendered}
+        />
+      )}
+    </Show>
+  )
+}
+
+interface ToolCallItemProps {
+  instanceId: string
+  sessionId: string
+  store: () => InstanceMessageStore
+  messageId: string
+  partId: string
+  onContentRendered?: () => void
+}
+
+function ToolCallItem(props: ToolCallItemProps) {
+  const { t } = useI18n()
+  const [deleting, setDeleting] = createSignal(false)
+
+  const record = createMemo(() => props.store().getMessage(props.messageId))
+  const messageInfo = createMemo(() => props.store().getMessageInfo(props.messageId))
+  const partEntry = createMemo(() => record()?.parts?.[props.partId])
+
+  const toolPart = createMemo(() => {
+    const part = partEntry()?.data as ClientPart | undefined
+    if (!part || part.type !== "tool") return undefined
+    return part as ToolCallPart
+  })
+
+  const toolState = createMemo(() => toolPart()?.state as ToolState | undefined)
+  const toolName = createMemo(() => toolPart()?.tool || "")
+  const messageVersion = createMemo(() => record()?.revision ?? 0)
+  const partVersion = createMemo(() => partEntry()?.revision ?? 0)
+
+  const deleteDisabled = createMemo(() => {
+    if (deleting()) return true
+    // Avoid deleting while a tool is actively running to prevent confusing UI states.
+    if (isToolStateRunning(toolState())) return true
+    // Avoid deleting permission prompts from here; those are interactive.
+    return Boolean(toolPart()?.pendingPermission)
+  })
+
+  const taskSessionId = createMemo(() => {
+    const state = toolState()
+    if (!state) return ""
+    if (!(isToolStateRunning(state) || isToolStateCompleted(state) || isToolStateError(state))) {
+      return ""
+    }
+    return extractTaskSessionId(state)
+  })
+
+  const taskLocation = createMemo(() => {
+    const id = taskSessionId()
+    if (!id) return null
+    return findTaskSessionLocation(id, props.instanceId)
+  })
+
+  const handleGoToTaskSession = (event: MouseEvent) => {
+    event.preventDefault()
+    event.stopPropagation()
+    const location = taskLocation()
+    if (!location) return
+    navigateToTaskSession(location)
+  }
+
+  const handleDeleteToolPart = async (event: MouseEvent) => {
+    event.preventDefault()
+    event.stopPropagation()
+
+    if (deleteDisabled()) return
+
+    setDeleting(true)
+    try {
+      await deleteMessagePart(props.instanceId, props.sessionId, props.messageId, props.partId)
+    } catch (error) {
+      showAlertDialog(t("messageBlock.tool.deletePart.failed.message"), {
+        title: t("messageBlock.tool.deletePart.failed.title"),
+        detail: error instanceof Error ? error.message : String(error),
+        variant: "error",
+      })
+    } finally {
+      setDeleting(false)
+    }
+  }
+
+  return (
+    <Show when={toolPart()}>
+      {(resolvedToolPart) => (
+        <>
+          <div class="tool-call-header-label">
+            <div class="tool-call-header-meta">
+              <span class="tool-call-icon">{TOOL_ICON}</span>
+              <span>{t("messageBlock.tool.header")}</span>
+              <span class="tool-name">{toolName() || t("messageBlock.tool.unknown")}</span>
+            </div>
+
+            <div class="flex items-center gap-2">
+              <Show when={taskSessionId()}>
+                <button
+                  class="tool-call-header-button"
+                  type="button"
+                  disabled={!taskLocation()}
+                  onClick={handleGoToTaskSession}
+                  title={t("messageBlock.tool.goToSession.label")}
+                  aria-label={t("messageBlock.tool.goToSession.label")}
+                >
+                  <ExternalLink class="w-3.5 h-3.5" aria-hidden="true" />
+                </button>
+              </Show>
+
+              <button
+                class="tool-call-header-button"
+                type="button"
+                disabled={deleteDisabled()}
+                onClick={handleDeleteToolPart}
+                title={deleting() ? t("messageBlock.tool.deletePart.deleting") : t("messageBlock.tool.deletePart.label")}
+                aria-label={deleting() ? t("messageBlock.tool.deletePart.deleting") : t("messageBlock.tool.deletePart.label")}
+              >
+                <Trash2 class="w-3.5 h-3.5" aria-hidden="true" />
+              </button>
+            </div>
+          </div>
+
+          <ToolCall
+            toolCall={resolvedToolPart()}
+            toolCallId={props.partId}
+            messageId={props.messageId}
+            messageVersion={messageVersion()}
+            partVersion={partVersion()}
+            instanceId={props.instanceId}
+            sessionId={props.sessionId}
+            onContentRendered={props.onContentRendered}
+          />
+        </>
+      )}
+    </Show>
+  )
 }
 
 interface StepDisplayItem {
@@ -204,6 +441,8 @@ type ReasoningDisplayItem = {
   messageInfo?: MessageInfo
   showAgentMeta?: boolean
   defaultExpanded: boolean
+  messageId: string
+  partId: string
 }
 
 type CompactionDisplayItem = {
@@ -212,6 +451,8 @@ type CompactionDisplayItem = {
   part: ClientPart
   messageInfo?: MessageInfo
   accentColor?: string
+  messageId: string
+  partId: string
 }
 
 type MessageBlockItem = ContentDisplayItem | ToolDisplayItem | StepDisplayItem | ReasoningDisplayItem | CompactionDisplayItem
@@ -272,7 +513,6 @@ export default function MessageBlock(props: MessageBlockProps) {
     const items: MessageBlockItem[] = []
     const blockContentKeys: string[] = []
     const blockToolKeys: string[] = []
-    let segmentIndex = 0
     let pendingParts: ClientPart[] = []
     let agentMetaAttached = current.role !== "assistant"
     const defaultAccentColor = current.role === "user" ? USER_BORDER_COLOR : ASSISTANT_BORDER_COLOR
@@ -280,34 +520,28 @@ export default function MessageBlock(props: MessageBlockProps) {
 
     const flushContent = () => {
       if (pendingParts.length === 0) return
-      const segmentKey = `${current.id}:segment:${segmentIndex}`
-      segmentIndex += 1
-      const shouldShowAgentMeta =
-        current.role === "assistant" &&
-        !agentMetaAttached &&
-        pendingParts.some((part) => partHasRenderableText(part))
+      const startPartId = typeof (pendingParts[0] as any)?.id === "string" ? ((pendingParts[0] as any).id as string) : ""
+      if (!startPartId) {
+        pendingParts = []
+        return
+      }
+
+      if (!agentMetaAttached && pendingParts.some((part) => partHasRenderableText(part))) {
+        agentMetaAttached = true
+      }
+
+      const segmentKey = `${current.id}:content:${startPartId}`
       let cached = sessionCache.messageItems.get(segmentKey)
       if (!cached) {
         cached = {
           type: "content",
           key: segmentKey,
-          record: current,
-          parts: pendingParts.slice(),
-          messageInfo: info,
-          isQueued,
-          showAgentMeta: shouldShowAgentMeta,
+          messageId: current.id,
+          startPartId,
         }
         sessionCache.messageItems.set(segmentKey, cached)
-      } else {
-        cached.record = current
-        cached.parts = pendingParts.slice()
-        cached.messageInfo = info
-        cached.isQueued = isQueued
-        cached.showAgentMeta = shouldShowAgentMeta
-      }
-      if (shouldShowAgentMeta) {
-        agentMetaAttached = true
       }
+
       items.push(cached)
       blockContentKeys.push(segmentKey)
       lastAccentColor = defaultAccentColor
@@ -317,28 +551,26 @@ export default function MessageBlock(props: MessageBlockProps) {
     orderedParts.forEach((part, partIndex) => {
       if (part.type === "tool") {
         flushContent()
-        const partVersion = typeof (part as any).revision === "number" ? (part as any).revision : 0
-        const messageVersion = current.revision
-        const key = `${current.id}:${part.id ?? partIndex}`
+        const partId = part.id
+        if (!partId) {
+          // Tool parts are required to have ids; if one slips through, skip rendering
+          // to avoid unstable keys and accidental remount cascades.
+          return
+        }
+        const key = `${current.id}:${partId}`
         let toolItem = sessionCache.toolItems.get(key)
         if (!toolItem) {
           toolItem = {
             type: "tool",
             key,
-            toolPart: part as ToolCallPart,
-            messageInfo: info,
             messageId: current.id,
-            messageVersion,
-            partVersion,
+            partId,
           }
           sessionCache.toolItems.set(key, toolItem)
         } else {
           toolItem.key = key
-          toolItem.toolPart = part as ToolCallPart
-          toolItem.messageInfo = info
           toolItem.messageId = current.id
-          toolItem.messageVersion = messageVersion
-          toolItem.partVersion = partVersion
+          toolItem.partId = partId
         }
         items.push(toolItem)
         blockToolKeys.push(key)
@@ -348,7 +580,8 @@ export default function MessageBlock(props: MessageBlockProps) {
 
       if (part.type === "compaction") {
         flushContent()
-        const key = `${current.id}:${part.id ?? partIndex}:compaction`
+        const partId = part.id ?? ""
+        const key = `${current.id}:${partId || partIndex}:compaction`
         const isAuto = Boolean((part as any)?.auto)
         items.push({
           type: "compaction",
@@ -356,6 +589,8 @@ export default function MessageBlock(props: MessageBlockProps) {
           part,
           messageInfo: info,
           accentColor: isAuto ? "var(--session-status-compacting-fg)" : USER_BORDER_COLOR,
+          messageId: current.id,
+          partId,
         })
         lastAccentColor = isAuto ? "var(--session-status-compacting-fg)" : USER_BORDER_COLOR
         return
@@ -380,7 +615,8 @@ export default function MessageBlock(props: MessageBlockProps) {
       if (part.type === "reasoning") {
         flushContent()
         if (props.showThinking() && reasoningHasRenderableContent(part)) {
-          const key = `${current.id}:${part.id ?? partIndex}:reasoning`
+          const partId = part.id ?? ""
+          const key = `${current.id}:${partId || partIndex}:reasoning`
           const showAgentMeta = current.role === "assistant" && !agentMetaAttached
           if (showAgentMeta) {
             agentMetaAttached = true
@@ -392,6 +628,8 @@ export default function MessageBlock(props: MessageBlockProps) {
             messageInfo: info,
             showAgentMeta,
             defaultExpanded: props.thinkingDefaultExpanded(),
+            messageId: current.id,
+            partId,
           })
           lastAccentColor = ASSISTANT_BORDER_COLOR
         }
@@ -427,21 +665,21 @@ export default function MessageBlock(props: MessageBlockProps) {
   })
 
   return (
-    <Show when={block()} keyed>
+    <Show when={block()}>
       {(resolvedBlock) => (
-        <div class="message-stream-block" data-message-id={resolvedBlock.record.id}>
-          <For each={resolvedBlock.items}>
+        <div class="message-stream-block" data-message-id={resolvedBlock().record.id}>
+          <For each={resolvedBlock().items}>
             {(item) => (
               <Switch>
                 <Match when={item.type === "content"}>
-                  <MessageItem
-                    record={(item as ContentDisplayItem).record}
-                    messageInfo={(item as ContentDisplayItem).messageInfo}
-                    parts={(item as ContentDisplayItem).parts}
+                  <MessageContentItem
                     instanceId={props.instanceId}
                     sessionId={props.sessionId}
-                    isQueued={(item as ContentDisplayItem).isQueued}
-                    showAgentMeta={(item as ContentDisplayItem).showAgentMeta}
+                    store={props.store}
+                    messageId={(item as ContentDisplayItem).messageId}
+                    startPartId={(item as ContentDisplayItem).startPartId}
+                    messageIndex={props.messageIndex}
+                    lastAssistantIndex={props.lastAssistantIndex}
                     onRevert={props.onRevert}
                     onFork={props.onFork}
                     onContentRendered={props.onContentRendered}
@@ -450,46 +688,14 @@ export default function MessageBlock(props: MessageBlockProps) {
                 <Match when={item.type === "tool"}>
                   {(() => {
                     const toolItem = item as ToolDisplayItem
-                    const toolState = toolItem.toolPart.state as ToolState | undefined
-                    const hasToolState =
-                      Boolean(toolState) && (isToolStateRunning(toolState) || isToolStateCompleted(toolState) || isToolStateError(toolState))
-                    const taskSessionId = hasToolState ? extractTaskSessionId(toolState) : ""
-                    const taskLocation = taskSessionId ? findTaskSessionLocation(taskSessionId, props.instanceId) : null
-                    const handleGoToTaskSession = (event: MouseEvent) => {
-                      event.preventDefault()
-                      event.stopPropagation()
-                      if (!taskLocation) return
-                      navigateToTaskSession(taskLocation)
-                    }
-
                     return (
                       <div class="tool-call-message" data-key={toolItem.key}>
-                        <div class="tool-call-header-label">
-                          <div class="tool-call-header-meta">
-                            <span class="tool-call-icon">{TOOL_ICON}</span>
-                            <span>{t("messageBlock.tool.header")}</span>
-                            <span class="tool-name">{toolItem.toolPart.tool || t("messageBlock.tool.unknown")}</span>
-                          </div>
-                          <Show when={taskSessionId}>
-                            <button
-                              class="tool-call-header-button"
-                              type="button"
-                              disabled={!taskLocation}
-                              onClick={handleGoToTaskSession}
-                              title={!taskLocation ? t("messageBlock.tool.goToSession.unavailableTitle") : t("messageBlock.tool.goToSession.title")}
-                            >
-                              {t("messageBlock.tool.goToSession.label")}
-                            </button>
-                          </Show>
-                        </div>
-                        <ToolCall
-                          toolCall={toolItem.toolPart}
-                          toolCallId={toolItem.toolPart.id}
-                          messageId={toolItem.messageId}
-                          messageVersion={toolItem.messageVersion}
-                          partVersion={toolItem.partVersion}
+                        <ToolCallItem
                           instanceId={props.instanceId}
                           sessionId={props.sessionId}
+                          store={props.store}
+                          messageId={toolItem.messageId}
+                          partId={toolItem.partId}
                           onContentRendered={props.onContentRendered}
                         />
                       </div>
@@ -497,7 +703,12 @@ export default function MessageBlock(props: MessageBlockProps) {
                   })()}
                 </Match>
                 <Match when={item.type === "step-start"}>
-                  <StepCard kind="start" part={(item as StepDisplayItem).part} messageInfo={(item as StepDisplayItem).messageInfo} showAgentMeta />
+                  <StepCard
+                    kind="start"
+                    part={(item as StepDisplayItem).part}
+                    messageInfo={(item as StepDisplayItem).messageInfo}
+                    showAgentMeta
+                  />
                 </Match>
                 <Match when={item.type === "step-finish"}>
                   <StepCard
@@ -509,7 +720,15 @@ export default function MessageBlock(props: MessageBlockProps) {
                   />
                 </Match>
                 <Match when={item.type === "compaction"}>
-                  <CompactionCard part={(item as CompactionDisplayItem).part} messageInfo={(item as CompactionDisplayItem).messageInfo} borderColor={(item as CompactionDisplayItem).accentColor} />
+                  <CompactionCard
+                    part={(item as CompactionDisplayItem).part}
+                    messageInfo={(item as CompactionDisplayItem).messageInfo}
+                    borderColor={(item as CompactionDisplayItem).accentColor}
+                    instanceId={props.instanceId}
+                    sessionId={props.sessionId}
+                    messageId={(item as CompactionDisplayItem).messageId}
+                    partId={(item as CompactionDisplayItem).partId}
+                  />
                 </Match>
                 <Match when={item.type === "reasoning"}>
                   <ReasoningCard
@@ -517,6 +736,8 @@ export default function MessageBlock(props: MessageBlockProps) {
                     messageInfo={(item as ReasoningDisplayItem).messageInfo}
                     instanceId={props.instanceId}
                     sessionId={props.sessionId}
+                    messageId={(item as ReasoningDisplayItem).messageId}
+                    partId={(item as ReasoningDisplayItem).partId}
                     showAgentMeta={(item as ReasoningDisplayItem).showAgentMeta}
                     defaultExpanded={(item as ReasoningDisplayItem).defaultExpanded}
                   />
@@ -539,8 +760,19 @@ interface StepCardProps {
   borderColor?: string
 }
 
-function CompactionCard(props: { part: ClientPart; messageInfo?: MessageInfo; borderColor?: string }) {
+interface CompactionCardProps {
+  part: ClientPart
+  messageInfo?: MessageInfo
+  borderColor?: string
+  instanceId: string
+  sessionId: string
+  messageId: string
+  partId: string
+}
+
+function CompactionCard(props: CompactionCardProps) {
   const { t } = useI18n()
+  const [deleting, setDeleting] = createSignal(false)
   const isAuto = () => Boolean((props.part as any)?.auto)
   const label = () => (isAuto() ? t("messageBlock.compaction.autoLabel") : t("messageBlock.compaction.manualLabel"))
   const borderColor = () => props.borderColor ?? (isAuto() ? "var(--session-status-compacting-fg)" : USER_BORDER_COLOR)
@@ -548,13 +780,43 @@ function CompactionCard(props: { part: ClientPart; messageInfo?: MessageInfo; bo
   const containerClass = () =>
     `message-compaction-card ${isAuto() ? "message-compaction-card--auto" : "message-compaction-card--manual"}`
 
+  const canDelete = () => Boolean(props.partId) && !deleting()
+
+  const handleDelete = async (event: MouseEvent) => {
+    event.preventDefault()
+    event.stopPropagation()
+    if (!canDelete()) return
+    setDeleting(true)
+    try {
+      await deleteMessagePart(props.instanceId, props.sessionId, props.messageId, props.partId)
+    } catch (error) {
+      showAlertDialog(t("messagePart.actions.deleteFailedMessage"), {
+        title: t("messagePart.actions.deleteFailedTitle"),
+        detail: error instanceof Error ? error.message : String(error),
+        variant: "error",
+      })
+    } finally {
+      setDeleting(false)
+    }
+  }
+
   return (
     <div
-      class={containerClass()}
+      class={`${containerClass()} relative`}
       style={{ "border-left": `4px solid ${borderColor()}` }}
       role="status"
       aria-label={t("messageBlock.compaction.ariaLabel")}
     >
+      <button
+        type="button"
+        class="tool-call-header-button absolute right-2 top-1/2 -translate-y-1/2"
+        disabled={!canDelete()}
+        onClick={handleDelete}
+        title={t("messagePart.actions.deleteTitle")}
+      >
+        {deleting() ? t("messagePart.actions.deleting") : t("messagePart.actions.delete")}
+      </button>
+
       <div class="message-compaction-row">
         <FoldVertical class="message-compaction-icon w-4 h-4" aria-hidden="true" />
         <span class="message-compaction-label">{label()}</span>
@@ -609,6 +871,7 @@ function StepCard(props: StepCardProps) {
 
   const finishStyle = () => (props.borderColor ? { "border-left-color": props.borderColor } : undefined)
 
+
   const renderUsageChips = (usage: NonNullable<ReturnType<typeof usageStats>>) => {
     const entries = [
       { label: t("messageBlock.usage.input"), value: usage.input, formatter: formatTokenTotal },
@@ -674,6 +937,8 @@ interface ReasoningCardProps {
   messageInfo?: MessageInfo
   instanceId: string
   sessionId: string
+  messageId: string
+  partId: string
   showAgentMeta?: boolean
   defaultExpanded?: boolean
 }
@@ -681,6 +946,7 @@ interface ReasoningCardProps {
 function ReasoningCard(props: ReasoningCardProps) {
   const { t } = useI18n()
   const [expanded, setExpanded] = createSignal(Boolean(props.defaultExpanded))
+  const [deleting, setDeleting] = createSignal(false)
 
   createEffect(() => {
     setExpanded(Boolean(props.defaultExpanded))
@@ -744,39 +1010,92 @@ function ReasoningCard(props: ReasoningCardProps) {
 
   const toggle = () => setExpanded((prev) => !prev)
 
+  const viewHideLabel = () =>
+    expanded() ? t("messageBlock.reasoning.indicator.hide") : t("messageBlock.reasoning.indicator.view")
+
+  const hasDeleteTarget = () => Boolean(props.partId)
+  const canDelete = () => hasDeleteTarget() && !deleting()
+
+  const handleDelete = async (event: MouseEvent) => {
+    event.preventDefault()
+    event.stopPropagation()
+    if (!canDelete()) return
+    setDeleting(true)
+    try {
+      await deleteMessagePart(props.instanceId, props.sessionId, props.messageId, props.partId)
+    } catch (error) {
+      showAlertDialog(t("messagePart.actions.deleteFailedMessage"), {
+        title: t("messagePart.actions.deleteFailedTitle"),
+        detail: error instanceof Error ? error.message : String(error),
+        variant: "error",
+      })
+    } finally {
+      setDeleting(false)
+    }
+  }
+
   return (
     <div class="message-reasoning-card">
-      <button
-        type="button"
-        class="message-reasoning-toggle"
-        onClick={toggle}
-        aria-expanded={expanded()}
-        aria-label={expanded() ? t("messageBlock.reasoning.collapseAriaLabel") : t("messageBlock.reasoning.expandAriaLabel")}
-      >
-        <span class="message-reasoning-label flex flex-wrap items-center gap-2">
-          <span>{t("messageBlock.reasoning.thinkingLabel")}</span>
-          <Show when={props.showAgentMeta && (agentIdentifier() || modelIdentifier())}>
-            <span class="message-step-meta-inline">
-              <Show when={agentIdentifier()}>
-                {(value) => (
-                  <span class="font-medium text-[var(--message-assistant-border)]">{t("messageBlock.step.agentLabel", { agent: value() })}</span>
-                )}
-              </Show>
-              <Show when={modelIdentifier()}>
-                {(value) => (
-                  <span class="font-medium text-[var(--message-assistant-border)]">{t("messageBlock.step.modelLabel", { model: value() })}</span>
-                )}
-              </Show>
-            </span>
-          </Show>
-        </span>
-        <span class="message-reasoning-meta">
-          <span class="message-reasoning-indicator">
-            {expanded() ? t("messageBlock.reasoning.indicator.hide") : t("messageBlock.reasoning.indicator.view")}
+      <div class="message-reasoning-header">
+        <button
+          type="button"
+          class="message-reasoning-toggle"
+          onClick={toggle}
+          aria-expanded={expanded()}
+          aria-label={expanded() ? t("messageBlock.reasoning.collapseAriaLabel") : t("messageBlock.reasoning.expandAriaLabel")}
+        >
+          <span class="message-reasoning-label flex flex-wrap items-center gap-2">
+            <span>{t("messageBlock.reasoning.thinkingLabel")}</span>
+            <Show when={props.showAgentMeta && (agentIdentifier() || modelIdentifier())}>
+              <span class="message-step-meta-inline">
+                <Show when={agentIdentifier()}>
+                  {(value) => (
+                    <span class="font-medium text-[var(--message-assistant-border)]">{t("messageBlock.step.agentLabel", { agent: value() })}</span>
+                  )}
+                </Show>
+                <Show when={modelIdentifier()}>
+                  {(value) => (
+                    <span class="font-medium text-[var(--message-assistant-border)]">{t("messageBlock.step.modelLabel", { model: value() })}</span>
+                  )}
+                </Show>
+              </span>
+            </Show>
           </span>
+        </button>
+
+        <div class="message-reasoning-actions">
+          <button
+            type="button"
+            class="message-action-button"
+            onClick={(event) => {
+              event.preventDefault()
+              event.stopPropagation()
+              toggle()
+            }}
+            aria-label={viewHideLabel()}
+            title={viewHideLabel()}
+          >
+            <Show when={expanded()} fallback={<ChevronsUpDown class="w-3.5 h-3.5" aria-hidden="true" />}>
+              <ChevronsDownUp class="w-3.5 h-3.5" aria-hidden="true" />
+            </Show>
+          </button>
+
+          <Show when={hasDeleteTarget()}>
+            <button
+              type="button"
+              class="message-action-button"
+              onClick={handleDelete}
+              disabled={!canDelete()}
+              aria-label={t("messagePart.actions.deleteTitle")}
+              title={t("messagePart.actions.deleteTitle")}
+            >
+              <Trash2 class="w-3.5 h-3.5" aria-hidden="true" />
+            </button>
+          </Show>
+
           <span class="message-reasoning-time">{timestamp()}</span>
-        </span>
-      </button>
+        </div>
+      </div>
 
       <Show when={expanded()}>
         <div class="message-reasoning-expanded">

packages/ui/src/components/message-item.tsx

@@ -1,10 +1,13 @@
 import { For, Show, createSignal } from "solid-js"
+import { Copy, Split, Trash2, Undo } from "lucide-solid"
 import type { MessageInfo, ClientPart } from "../types/message"
 import { partHasRenderableText } from "../types/message"
 import type { MessageRecord } from "../stores/message-v2/types"
 import MessagePart from "./message-part"
 import { copyToClipboard } from "../lib/clipboard"
 import { useI18n } from "../lib/i18n"
+import { showAlertDialog } from "../stores/alerts"
+import { deleteMessagePart } from "../stores/session-actions"
 
 interface MessageItemProps {
   record: MessageRecord
@@ -22,6 +25,7 @@ interface MessageItemProps {
 export default function MessageItem(props: MessageItemProps) {
   const { t } = useI18n()
   const [copied, setCopied] = createSignal(false)
+  const [deletingParts, setDeletingParts] = createSignal<Set<string>>(new Set())
 
   const isUser = () => props.record.role === "user"
   const createdTimestamp = () => props.messageInfo?.time?.created ?? props.record.createdAt
@@ -137,8 +141,17 @@ export default function MessageItem(props: MessageItemProps) {
   }
 
   const isGenerating = () => {
+    if (hasContent()) {
+      return false
+    }
+
+    // Prefer the local record status for streaming placeholders.
+    if (!isUser() && props.record.status === "streaming") {
+      return true
+    }
+
     const info = props.messageInfo
-    return !hasContent() && info && info.role === "assistant" && info.time.completed !== undefined && info.time.completed === 0
+    return Boolean(info && info.role === "assistant" && info.time.completed !== undefined && info.time.completed === 0)
   }
 
   const handleRevert = () => {
@@ -147,6 +160,8 @@ export default function MessageItem(props: MessageItemProps) {
     }
   }
 
+  const copyLabel = () => (copied() ? t("messageItem.actions.copied") : t("messageItem.actions.copy"))
+
   const getRawContent = () => {
     return props.parts
       .filter(part => part.type === "text")
@@ -163,7 +178,51 @@ export default function MessageItem(props: MessageItemProps) {
     setTimeout(() => setCopied(false), 2000)
   }
 
-  if (!isUser() && !hasContent()) {
+  const deletableTextPartId = () => {
+    const part = props.parts.find((candidate) => {
+      if (!candidate || candidate.type !== "text") return false
+      const id = (candidate as any).id
+      if (typeof id !== "string" || id.length === 0) return false
+      return !Boolean((candidate as any).synthetic)
+    })
+    return (part as any)?.id as string | undefined
+  }
+
+  const isDeletingPart = (partId?: string) => {
+    if (!partId) return false
+    return deletingParts().has(partId)
+  }
+
+  const setPartDeleting = (partId: string, value: boolean) => {
+    setDeletingParts((prev) => {
+      const next = new Set(prev)
+      if (value) {
+        next.add(partId)
+      } else {
+        next.delete(partId)
+      }
+      return next
+    })
+  }
+
+  const handleDeletePart = async (partId?: string) => {
+    if (!partId) return
+    if (isDeletingPart(partId)) return
+    setPartDeleting(partId, true)
+    try {
+      await deleteMessagePart(props.instanceId, props.sessionId, props.record.id, partId)
+    } catch (error) {
+      showAlertDialog(t("messagePart.actions.deleteFailedMessage"), {
+        title: t("messagePart.actions.deleteFailedTitle"),
+        detail: error instanceof Error ? error.message : String(error),
+        variant: "error",
+      })
+    } finally {
+      setPartDeleting(partId, false)
+    }
+  }
+
+  if (!isUser() && !hasContent() && !isGenerating()) {
     return null
   }
 
@@ -209,62 +268,84 @@ export default function MessageItem(props: MessageItemProps) {
   return (
     <div class={containerClass()}>
       <header class={`message-item-header ${isUser() ? "pb-0.5" : "pb-0"}`}>
-        <div class="message-speaker">
-          <span class="message-speaker-label" data-role={isUser() ? "user" : "assistant"}>
-            {speakerLabel()}
-          </span>
-          <Show when={agentMeta()}>{(meta) => <span class="message-agent-meta">{meta()}</span>}</Show>
-        </div>
-        <div class="message-item-actions">
-          <Show when={isUser()}>
-            <div class="message-action-group">
-              <Show when={props.onRevert}>
-                <button
-                  class="message-action-button"
-                  onClick={handleRevert}
-                  title={t("messageItem.actions.revertTitle")}
-                  aria-label={t("messageItem.actions.revertTitle")}
-                >
-                  {t("messageItem.actions.revert")}
-                </button>
-              </Show>
-              <Show when={props.onFork}>
-                <button
-                  class="message-action-button"
-                  onClick={() => props.onFork?.(props.record.id)}
-                  title={t("messageItem.actions.forkTitle")}
-                  aria-label={t("messageItem.actions.forkTitle")}
-                >
-                  {t("messageItem.actions.fork")}
-                </button>
-              </Show>
-              <button
-                class="message-action-button"
-                onClick={handleCopy}
-                title={t("messageItem.actions.copyTitle")}
-                aria-label={t("messageItem.actions.copyTitle")}
-              >
-                <Show when={copied()} fallback={t("messageItem.actions.copy")}>
-                  {t("messageItem.actions.copied")}
+        <div class="message-item-header-row message-item-header-row--top">
+          <div class="message-speaker">
+            <span class="message-speaker-label" data-role={isUser() ? "user" : "assistant"}>
+              {speakerLabel()}
+            </span>
+          </div>
+
+          <div class="message-item-actions">
+            <Show when={isUser()}>
+              <div class="message-action-group">
+                <Show when={props.onRevert}>
+                  <button
+                    class="message-action-button"
+                    onClick={handleRevert}
+                    title={t("messageItem.actions.revert")}
+                    aria-label={t("messageItem.actions.revert")}
+                  >
+                    <Undo class="w-3.5 h-3.5" aria-hidden="true" />
+                  </button>
                 </Show>
-              </button>
-            </div>
-          </Show>
-          <Show when={!isUser()}>
-            <button
-              class="message-action-button"
-              onClick={handleCopy}
-              title={t("messageItem.actions.copyTitle")}
-              aria-label={t("messageItem.actions.copyTitle")}
-            >
-              <Show when={copied()} fallback={t("messageItem.actions.copy")}>
-                {t("messageItem.actions.copied")}
-              </Show>
-            </button>
-          </Show>
-          <time class="message-timestamp" dateTime={timestampIso()}>{timestamp()}</time>
+                <Show when={props.onFork}>
+                  <button
+                    class="message-action-button"
+                    onClick={() => props.onFork?.(props.record.id)}
+                    title={t("messageItem.actions.fork")}
+                    aria-label={t("messageItem.actions.fork")}
+                  >
+                    <Split class="w-3.5 h-3.5" aria-hidden="true" />
+                  </button>
+                </Show>
+                <button
+                  class="message-action-button"
+                  onClick={handleCopy}
+                  title={copyLabel()}
+                  aria-label={copyLabel()}
+                >
+                  <Copy class="w-3.5 h-3.5" aria-hidden="true" />
+                </button>
+              </div>
+            </Show>
+            <Show when={!isUser()}>
+              <div class="message-action-group">
+                <button
+                  class="message-action-button"
+                  onClick={handleCopy}
+                  title={copyLabel()}
+                  aria-label={copyLabel()}
+                >
+                  <Copy class="w-3.5 h-3.5" aria-hidden="true" />
+                </button>
+
+                <Show when={deletableTextPartId()}>
+                  {(partId) => (
+                    <button
+                      class="message-action-button"
+                      onClick={() => void handleDeletePart(partId())}
+                      disabled={isDeletingPart(partId())}
+                      title={isDeletingPart(partId()) ? t("messagePart.actions.deleting") : t("messagePart.actions.delete")}
+                      aria-label={isDeletingPart(partId()) ? t("messagePart.actions.deleting") : t("messagePart.actions.delete")}
+                    >
+                      <Trash2 class="w-3.5 h-3.5" aria-hidden="true" />
+                    </button>
+                  )}
+                </Show>
+              </div>
+            </Show>
+            <time class="message-timestamp" dateTime={timestampIso()}>{timestamp()}</time>
+          </div>
         </div>
 
+        <Show when={agentMeta()}>
+          {(meta) => (
+            <div class="message-item-header-row message-item-header-row--bottom">
+              <span class="message-agent-meta">{meta()}</span>
+            </div>
+          )}
+        </Show>
+
       </header>
 
       <div class="pt-1 whitespace-pre-wrap break-words leading-[1.1]">
@@ -328,6 +409,19 @@ export default function MessageItem(props: MessageItemProps) {
                         <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 12l4 4 4-4m-4-8v12" />
                       </svg>
                     </button>
+
+                    <button
+                      type="button"
+                      onClick={() => void handleDeletePart(attachment.id)}
+                      class="attachment-remove"
+                      disabled={isDeletingPart(attachment.id)}
+                      aria-label={t("messagePart.actions.deleteTitle")}
+                      title={t("messagePart.actions.deleteTitle")}
+                    >
+                      <svg class="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+                      </svg>
+                    </button>
                     <Show when={isImage}>
                       <div class="attachment-chip-preview">
                         <img src={attachment.url} alt={name} />

packages/ui/src/components/message-list-header.tsx

@@ -3,7 +3,7 @@ import Kbd from "./kbd"
 import { useI18n } from "../lib/i18n"
 
 const METRIC_CHIP_CLASS = "inline-flex items-center gap-1 rounded-full border border-base px-2 py-0.5 text-xs text-primary"
-const METRIC_LABEL_CLASS = "uppercase text-[10px] tracking-wide text-primary/70"
+const METRIC_LABEL_CLASS = "uppercase text-[10px] tracking-wide text-muted"
 
 interface MessageListHeaderProps {
   usedTokens: number
@@ -62,7 +62,7 @@ export default function MessageListHeader(props: MessageListHeaderProps) {
             {t("messageListHeader.commandPalette.button")}
           </button>
           <span class="connection-status-shortcut-hint">
-            <Kbd shortcut="cmd+shift+p" />
+            <Kbd shortcut="cmd+shift+p" class="kbd-hint" />
           </span>
         </div>
       </div>

packages/ui/src/components/message-part.tsx

@@ -15,7 +15,7 @@ interface MessagePartProps {
   sessionId: string
   onRendered?: () => void
  }
- export default function MessagePart(props: MessagePartProps) {
+  export default function MessagePart(props: MessagePartProps) {
 
   const { isDark } = useTheme()
   const { preferences } = useConfig()
@@ -25,6 +25,14 @@ interface MessagePartProps {
   const isAssistantMessage = () => props.messageType === "assistant"
   const textContainerClass = () => (isAssistantMessage() ? "message-text message-text-assistant" : "message-text")
 
+  const shouldHideTextPart = () => {
+    const part = props.part
+    if (!part || part.type !== "text") return false
+    // Keep optimistic user prompts visible; hide synthetic assistant text.
+    return Boolean((part as any).synthetic) && props.messageType !== "user"
+  }
+
+
   const plainTextContent = () => {
     const part = props.part
 
@@ -94,23 +102,23 @@ interface MessagePartProps {
   return (
     <Switch>
       <Match when={partType() === "text"}>
-        <Show when={!(props.part.type === "text" && props.part.synthetic) && partHasRenderableText(props.part)}>
+        <Show when={!shouldHideTextPart() && partHasRenderableText(props.part)}>
           <div class={textContainerClass()}>
-            <Show
-               when={isAssistantMessage()}
-               fallback={<span>{plainTextContent()}</span>}
-             >
-              <Markdown
-                part={createTextPartForMarkdown()}
-                instanceId={props.instanceId}
-                sessionId={props.sessionId}
-                isDark={isDark()}
-                size={isAssistantMessage() ? "tight" : "base"}
-                onRendered={props.onRendered}
-              />
-             </Show>
+                <Show
+                 when={isAssistantMessage()}
+                 fallback={<span class="text-primary">{plainTextContent()}</span>}
+               >
+                 <Markdown
+                   part={createTextPartForMarkdown()}
+                   instanceId={props.instanceId}
+                   sessionId={props.sessionId}
+                   isDark={isDark()}
+                 size={isAssistantMessage() ? "tight" : "base"}
+                 onRendered={props.onRendered}
+               />
+              </Show>
 
-          </div>
+           </div>
         </Show>
       </Match>
 

packages/ui/src/components/message-section.tsx

@@ -7,6 +7,8 @@ import { getSessionInfo } from "../stores/sessions"
 import { messageStoreBus } from "../stores/message-v2/bus"
 import { useScrollCache } from "../lib/hooks/use-scroll-cache"
 import { useI18n } from "../lib/i18n"
+import { copyToClipboard } from "../lib/clipboard"
+import { showToastNotification } from "../lib/notifications"
 import type { InstanceMessageStore } from "../stores/message-v2/instance-store"
 
 const SCROLL_SCOPE = "session"
@@ -94,6 +96,9 @@ export default function MessageSection(props: MessageSectionProps) {
 
   const seenTimelineMessageIds = new Set<string>()
   const seenTimelineSegmentKeys = new Set<string>()
+  const timelinePartCountsByMessageId = new Map<string, number>()
+  let pendingTimelineMessagePartUpdates = new Set<string>()
+  let pendingTimelinePartUpdateFrame: number | null = null
 
   function makeTimelineKey(segment: TimelineSegment) {
     return `${segment.messageId}:${segment.id}:${segment.type}`
@@ -102,6 +107,7 @@ export default function MessageSection(props: MessageSectionProps) {
   function seedTimeline() {
     seenTimelineMessageIds.clear()
     seenTimelineSegmentKeys.clear()
+    timelinePartCountsByMessageId.clear()
     const ids = untrack(messageIds)
     const resolvedStore = untrack(store)
     const segments: TimelineSegment[] = []
@@ -109,6 +115,7 @@ export default function MessageSection(props: MessageSectionProps) {
       const record = resolvedStore.getMessage(messageId)
       if (!record) return
       seenTimelineMessageIds.add(messageId)
+      timelinePartCountsByMessageId.set(messageId, record.partIds.length)
       const built = buildTimelineSegments(props.instanceId, record, t)
       built.forEach((segment) => {
         const key = makeTimelineKey(segment)
@@ -123,6 +130,7 @@ export default function MessageSection(props: MessageSectionProps) {
   function appendTimelineForMessage(messageId: string) {
     const record = untrack(() => store().getMessage(messageId))
     if (!record) return
+    timelinePartCountsByMessageId.set(messageId, record.partIds.length)
     const built = buildTimelineSegments(props.instanceId, record, t)
     if (built.length === 0) return
     const newSegments: TimelineSegment[] = []
@@ -375,7 +383,9 @@ export default function MessageSection(props: MessageSectionProps) {
     const anchorRect = rects.length > 0 ? rects[0] : range.getBoundingClientRect()
     const shellRect = shell.getBoundingClientRect()
     const relativeTop = Math.max(anchorRect.top - shellRect.top - 40, 8)
-    const maxLeft = Math.max(shell.clientWidth - 180, 8)
+    // Keep the popover within the stream shell. The quote popover currently
+    // renders 3 actions; keep enough horizontal room for the pill.
+    const maxLeft = Math.max(shell.clientWidth - 260, 8)
     const relativeLeft = Math.min(Math.max(anchorRect.left - shellRect.left, 8), maxLeft)
     setQuoteSelection({ text: limited, top: relativeTop, left: relativeLeft })
   }
@@ -394,6 +404,24 @@ export default function MessageSection(props: MessageSectionProps) {
       selection?.removeAllRanges()
     }
   }
+
+  async function handleCopySelectionRequest() {
+    const info = quoteSelection()
+    if (!info) return
+
+    const success = await copyToClipboard(info.text)
+    showToastNotification({
+      message: success ? t("messageSection.quote.copied") : t("messageSection.quote.copyFailed"),
+      variant: success ? "success" : "error",
+      duration: success ? 2000 : 6000,
+    })
+
+    clearQuoteSelection()
+    if (typeof window !== "undefined") {
+      const selection = window.getSelection()
+      selection?.removeAllRanges()
+    }
+  }
  
   function handleContentRendered() {
     if (props.loading) {
@@ -468,8 +496,6 @@ export default function MessageSection(props: MessageSectionProps) {
   })
 
   let previousTimelineIds: string[] = []
-  let previousLastTimelineMessageId: string | null = null
-  let previousLastTimelinePartCount = 0
 
   createEffect(() => {
     const loading = Boolean(props.loading)
@@ -477,11 +503,15 @@ export default function MessageSection(props: MessageSectionProps) {
 
     if (loading) {
       previousTimelineIds = []
-      previousLastTimelineMessageId = null
-      previousLastTimelinePartCount = 0
       setTimelineSegments([])
       seenTimelineMessageIds.clear()
       seenTimelineSegmentKeys.clear()
+      timelinePartCountsByMessageId.clear()
+      pendingTimelineMessagePartUpdates.clear()
+      if (pendingTimelinePartUpdateFrame !== null) {
+        cancelAnimationFrame(pendingTimelinePartUpdateFrame)
+        pendingTimelinePartUpdateFrame = null
+      }
       return
     }
 
@@ -523,6 +553,14 @@ export default function MessageSection(props: MessageSectionProps) {
             next.forEach((segment) => seenTimelineSegmentKeys.add(makeTimelineKey(segment)))
             return next
           })
+
+          // Keep part count tracking in sync with id replacement.
+          const existingPartCount = timelinePartCountsByMessageId.get(oldId)
+          if (existingPartCount !== undefined) {
+            timelinePartCountsByMessageId.delete(oldId)
+            timelinePartCountsByMessageId.set(newId, existingPartCount)
+          }
+
           previousTimelineIds = ids.slice()
           return
         }
@@ -546,30 +584,95 @@ export default function MessageSection(props: MessageSectionProps) {
     previousTimelineIds = ids.slice()
   })
 
+  function clearPendingTimelinePartUpdateFrame() {
+    if (pendingTimelinePartUpdateFrame !== null) {
+      cancelAnimationFrame(pendingTimelinePartUpdateFrame)
+      pendingTimelinePartUpdateFrame = null
+    }
+  }
+
+  function scheduleTimelinePartUpdateFlush() {
+    if (pendingTimelinePartUpdateFrame !== null) return
+    pendingTimelinePartUpdateFrame = requestAnimationFrame(() => {
+      pendingTimelinePartUpdateFrame = null
+      if (pendingTimelineMessagePartUpdates.size === 0) return
+      const changedIds = Array.from(pendingTimelineMessagePartUpdates)
+      pendingTimelineMessagePartUpdates = new Set<string>()
+
+      const ids = messageIds()
+      const resolvedStore = store()
+
+      setTimelineSegments((prev) => {
+        let next = prev
+
+        for (const changedId of changedIds) {
+          // Remove old segments for this message.
+          next = next.filter((segment) => segment.messageId !== changedId)
+
+          const record = resolvedStore.getMessage(changedId)
+          const rebuilt = record ? buildTimelineSegments(props.instanceId, record, t) : []
+
+          // Insert rebuilt segments in the correct place based on session message order.
+          if (rebuilt.length > 0) {
+            let insertAt = next.length
+            const changedIndex = ids.indexOf(changedId)
+            if (changedIndex >= 0) {
+              for (let i = changedIndex + 1; i < ids.length; i++) {
+                const followingId = ids[i]
+                const existingIndex = next.findIndex((segment) => segment.messageId === followingId)
+                if (existingIndex >= 0) {
+                  insertAt = existingIndex
+                  break
+                }
+              }
+            }
+            next = [...next.slice(0, insertAt), ...rebuilt, ...next.slice(insertAt)]
+          }
+        }
+
+        // Rebuild the segment key set since we may have removed/replaced segments.
+        seenTimelineSegmentKeys.clear()
+        next.forEach((segment) => seenTimelineSegmentKeys.add(makeTimelineKey(segment)))
+        return next
+      })
+    })
+  }
+
+  // Keep timeline segments in sync when message parts are added/removed.
+  // Part deletion does not remove message ids from the session, so we must
+  // explicitly replace segments for messages whose part count changed.
   createEffect(() => {
     if (props.loading) return
     const ids = messageIds()
-    if (ids.length === 0) return
-    const lastId = ids[ids.length - 1]
-    if (!lastId) return
-    const record = store().getMessage(lastId)
-    if (!record) return
-    const partCount = record.partIds.length
-    if (lastId === previousLastTimelineMessageId && partCount === previousLastTimelinePartCount) {
-      return
+    const resolvedStore = store()
+
+    let hasChanges = false
+    for (const messageId of ids) {
+      const record = resolvedStore.getMessage(messageId)
+      const partCount = record?.partIds.length ?? 0
+      const previousCount = timelinePartCountsByMessageId.get(messageId)
+
+      if (previousCount === undefined) {
+        timelinePartCountsByMessageId.set(messageId, partCount)
+        continue
+      }
+
+      if (previousCount !== partCount) {
+        timelinePartCountsByMessageId.set(messageId, partCount)
+        pendingTimelineMessagePartUpdates.add(messageId)
+        hasChanges = true
+      }
     }
-    previousLastTimelineMessageId = lastId
-    previousLastTimelinePartCount = partCount
-    const built = buildTimelineSegments(props.instanceId, record, t)
-    const newSegments: TimelineSegment[] = []
-    built.forEach((segment) => {
-      const key = makeTimelineKey(segment)
-      if (seenTimelineSegmentKeys.has(key)) return
-      seenTimelineSegmentKeys.add(key)
-      newSegments.push(segment)
-    })
-    if (newSegments.length > 0) {
-      setTimelineSegments((prev) => [...prev, ...newSegments])
+
+    // Drop tracking for ids that are no longer present.
+    for (const trackedId of Array.from(timelinePartCountsByMessageId.keys())) {
+      if (!ids.includes(trackedId)) {
+        timelinePartCountsByMessageId.delete(trackedId)
+      }
+    }
+
+    if (hasChanges) {
+      scheduleTimelinePartUpdateFlush()
     }
   })
 
@@ -736,6 +839,7 @@ export default function MessageSection(props: MessageSectionProps) {
       cancelAnimationFrame(pendingAnchorScroll)
     }
     clearScrollToBottomFrames()
+    clearPendingTimelinePartUpdateFrame()
     if (detachScrollIntentListeners) {
       detachScrollIntentListeners()
     }
@@ -763,7 +867,7 @@ export default function MessageSection(props: MessageSectionProps) {
                   <ul>
                     <li>
                       <span>{t("messageSection.empty.tips.commandPalette")}</span>
-                      <Kbd shortcut="cmd+shift+p" class="ml-2" />
+                      <Kbd shortcut="cmd+shift+p" class="ml-2 kbd-hint" />
                     </li>
                     <li>{t("messageSection.empty.tips.askAboutCodebase")}</li>
                     <li>
@@ -835,6 +939,9 @@ export default function MessageSection(props: MessageSectionProps) {
                   <button type="button" class="message-quote-button" onClick={() => handleQuoteSelectionRequest("code")}>
                     {t("messageSection.quote.addAsCode")}
                   </button>
+                  <button type="button" class="message-quote-button" onClick={() => void handleCopySelectionRequest()}>
+                    {t("messageSection.quote.copy")}
+                  </button>
                 </div>
               </div>
             )}