feat(settings): VS Code-style GUI settings system

.claude/architecture-decisions/LESSON-0001-wave-terminal-is-host-environment.md

@@ -0,0 +1,72 @@
+# LESSON-0001: Wave Terminal IS the Host Environment
+
+**Date:** 2026-01-22
+**Category:** Development Environment
+**Severity:** CRITICAL
+
+---
+
+## Problem
+
+When developing Wave Terminal, Claude Code runs **inside** Wave Terminal itself. This creates a unique situation where the application under development is also the host environment for the development agent.
+
+## Incident
+
+During xterm.js 6.1.0 migration testing:
+- Agent checked for running processes with `tasklist | grep wave`
+- Found multiple `Wave.exe` and `wavesrv.x64.exe` processes
+- Incorrectly assumed these were the dev instance that was just started
+- Nearly suggested actions that could have killed the host terminal
+
+## Key Understanding
+
+```
+┌─────────────────────────────────────────────────┐
+│  Wave Terminal (Production/User Instance)        │
+│  ├── Wave.exe (main process)                    │
+│  ├── wavesrv.x64.exe (backend server)           │
+│  └── Claude Code (running in this terminal)     │
+│       └── Agent conversation (THIS SESSION)     │
+└─────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────┐
+│  Wave Terminal (Dev Instance - separate)        │
+│  ├── Wave.exe (dev main process)               │
+│  ├── wavesrv.x64.exe (dev backend)             │
+│  └── Started by `npm run dev` or `task dev`    │
+└─────────────────────────────────────────────────┘
+```
+
+## Rules
+
+### NEVER DO:
+- ❌ Kill `Wave.exe` or `wavesrv.x64.exe` processes without explicit user instruction
+- ❌ Assume Wave.exe processes are from your dev instance
+- ❌ Run `taskkill` on any Wave-related processes
+- ❌ Use the Electron MCP tools to interact with the production Wave instance
+
+### ALWAYS DO:
+- ✅ Understand that Wave Terminal is the HOST, not the target
+- ✅ The dev instance runs separately with its own processes
+- ✅ Ask user before any process management
+- ✅ Use `npm run dev` or `task dev` to start a SEPARATE dev instance
+
+## Impact
+
+- **If violated:** Kills Claude Code session, loses all conversation context
+- **Recovery:** User must restart Wave Terminal and Claude Code from scratch
+- **Data loss:** Any uncommitted work or in-progress analysis
+
+## Applies To
+
+- Any development work on Wave Terminal
+- Any testing involving Electron processes
+- Any process management commands
+- Any use of Electron MCP tools
+
+---
+
+## Related
+
+- xterm.js 6.1.0 upgrade task
+- QA testing procedures for Electron apps

.claude/architecture-decisions/README.md

@@ -0,0 +1,34 @@
+# Wave Terminal Architecture Decisions Registry
+
+This directory contains architecture decision records (ADRs), lessons learned, and error solutions for the Wave Terminal project.
+
+## Index
+
+### Lessons Learned
+
+| ID | Title | Category | Severity |
+|----|-------|----------|----------|
+| [LESSON-0001](LESSON-0001-wave-terminal-is-host-environment.md) | Wave Terminal IS the Host Environment | Development Environment | CRITICAL |
+
+### Architecture Decision Records (ADRs)
+
+*None yet*
+
+### Error Solutions
+
+*None yet*
+
+---
+
+## Usage
+
+### Before Development
+Query this registry to check for relevant patterns, known pitfalls, and proven approaches.
+
+### After Development
+Update this registry with new ADRs, lessons learned, or error solutions.
+
+---
+
+## Last Updated
+2026-01-22

.claude/worktrees/waveterm-experimental.json

@@ -0,0 +1,23 @@
+{
+  "lastUpdated": "2026-01-23T12:18:55.2633571-03:00",
+  "sessions": [
+    {
+      "sessionId": "aa5892ec-e359-44df-874e-b2d74860fcb7",
+      "ended": "2026-01-23T12:18:55.2697385-03:00"
+    },
+    {
+      "sessionId": "1421db85-83a1-4848-8c73-2677e47c920b",
+      "ended": "2026-01-23T00:59:12.2164267-03:00"
+    }
+  ],
+  "created": "2026-01-23T00:59:12.2084213-03:00",
+  "path": "G:\\Code\\waveterm-experimental",
+  "branch": "feat/experimental-upstream-fixes",
+  "name": "waveterm-experimental",
+  "parentRepo": "G:\\Code\\waveterm",
+  "context": {
+    "purpose": "",
+    "notes": [],
+    "relatedIssues": []
+  }
+}

BUILD.md

@@ -51,9 +51,16 @@ For packaging, the following additional packages are required:
 
 #### Windows
 
-You will need the [Zig](https://ziglang.org/) compiler for statically linking CGO.
+You will need the following:
 
-You can find installation instructions for Zig on Windows [here](https://ziglang.org/learn/getting-started/#managers).
+- **[Zig](https://ziglang.org/)** — Required for statically linking CGO. See [installation instructions](https://ziglang.org/learn/getting-started/#managers).
+- **[PowerShell 7+](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows)** — Required for build scripts. Windows ships with PowerShell 5.1, but the build system requires PowerShell 7 (pwsh). Install via winget:
+
+```powershell
+winget install Microsoft.PowerShell
+```
+
+Or download from the [PowerShell releases page](https://github.com/PowerShell/PowerShell/releases).
 
 ### Task
 

CHANGES.md

@@ -0,0 +1,104 @@
+# Changes Summary: Race Condition Fixes with Optimistic Locking
+
+## Overview
+
+This implementation addresses race conditions in tab metadata updates (spec-004) by implementing optimistic locking with version checking. The changes prevent TOCTOU (Time-Of-Check-Time-Of-Use) vulnerabilities in concurrent metadata operations.
+
+## Files Modified
+
+### Backend (Go)
+
+#### `pkg/wstore/wstore_dbops.go`
+- Added `ErrVersionMismatch` error variable for concurrent modification detection
+- Added `ErrObjectLocked` error variable for lock state rejection
+
+#### `pkg/wstore/wstore.go`
+- Added `UpdateObjectMetaWithVersion()` function:
+  - Performs optimistic locking update with version checking
+  - If `expectedVersion > 0` and doesn't match current version, returns `ErrVersionMismatch`
+  - If `expectedVersion == 0`, behaves like `UpdateObjectMeta` (no version check)
+
+- Added `UpdateObjectMetaIfNotLocked()` function:
+  - Atomically checks lock and updates metadata
+  - Lock is checked INSIDE the transaction, eliminating TOCTOU vulnerability
+  - Returns `ErrObjectLocked` (wrapped in `ErrVersionMismatch`) if locked
+  - Returns `ErrVersionMismatch` if version doesn't match
+
+#### `pkg/service/objectservice/objectservice.go`
+- Added `UpdateObjectMetaWithVersion()` RPC service method
+- Added `UpdateObjectMetaIfNotLocked()` RPC service method
+- Both methods include proper metadata annotations for TypeScript binding generation
+
+### Frontend (TypeScript)
+
+#### `frontend/app/view/term/termwrap.ts`
+- Added debounce map (`osc7DebounceMap`) for OSC 7 updates per tab
+- Added `OSC7_DEBOUNCE_MS = 300` constant for debounce delay
+- Added `clearOsc7Debounce()` helper function
+- Added `cleanupOsc7DebounceForTab()` exported function for memory leak prevention
+- Updated `handleOsc7Command()` to:
+  - Add null safety check for `tabData?.oid`
+  - Use debouncing to reduce race condition window
+  - Use atomic lock-aware update (`UpdateObjectMetaIfNotLocked`) instead of regular update
+  - Gracefully handle version mismatch and locked state errors
+
+#### `frontend/app/tab/tab.tsx`
+- Added `getApi` to imports from `@/app/store/global` (fix for pre-existing missing import)
+
+### Generated Files
+
+#### `frontend/app/store/services.ts`
+- Auto-generated new TypeScript methods:
+  - `UpdateObjectMetaWithVersion(oref, meta, expectedVersion)`
+  - `UpdateObjectMetaIfNotLocked(oref, meta, lockKey, expectedVersion)`
+
+## Key Features Implemented
+
+### 1. Optimistic Locking
+- Uses existing `version` field in WaveObj types
+- Version checked inside transaction to prevent TOCTOU
+- Atomic increment of version on successful update (already implemented in `DBUpdate`)
+
+### 2. Error Types
+- **ErrVersionMismatch**: Indicates concurrent modification detected
+- **ErrObjectLocked**: Indicates update rejected due to lock state
+- Both errors are wrapped appropriately for consistent error handling
+
+### 3. OSC 7 Debouncing
+- 300ms debounce window for rapid directory changes
+- Per-tab debounce timers in a Map
+- Cleanup function to prevent memory leaks on tab close
+
+### 4. Atomic Lock Checking
+- Lock state checked INSIDE database transaction
+- Eliminates race condition between lock check and update
+- If lock is toggled during update, the update is safely rejected
+
+## Acceptance Criteria Status
+
+- [x] `UpdateObjectMetaWithVersion` added to `wstore.go`
+- [x] RPC endpoints added to `objectservice.go`
+- [x] OSC 7 debounce map with cleanup function
+- [x] Null safety guards in `termwrap.ts`
+- [x] `ErrVersionMismatch` error type created
+- [x] `ErrObjectLocked` error type created
+- [x] TypeScript compilation passes (our files)
+- [x] Go compilation passes
+- [x] Changes committed
+
+## Testing Notes
+
+To test the implementation:
+
+1. **Version Mismatch Test**: Open two terminals in the same tab, rapidly change directories in both - the race condition should be handled gracefully
+
+2. **Lock Bypass Test**: Toggle the lock while an OSC 7 update is in flight - the update should be rejected if lock is set
+
+3. **Debounce Test**: Rapidly `cd` between directories - only the final directory should be set as basedir
+
+4. **Memory Leak Test**: Open and close multiple tabs - the debounce map should be cleaned up
+
+## Notes
+
+- The spec mentions retry logic for manual updates (handleSetBaseDir, handleToggleLock) - this was NOT implemented as the spec noted it as optional for Phase 4 and the core race condition fixes are functional without it
+- Pre-existing TypeScript errors in unrelated files (streamdown.tsx, notificationpopover.tsx) remain unfixed as they are not related to this implementation