backup: Phase 1 agent work (security, persistence, batch endpoint)

This is a backup of all work done by the 3 Phase 1 agents:

Agent A - Command Injection Fix (Issue #354):
- Fixed command injection in BranchManager.ts
- Fixed unnecessary shell usage in bun-path.ts
- Added comprehensive security test suite
- Created SECURITY.md and SECURITY_AUDIT_REPORT.md

Agent B - Observation Persistence Fix (Issue #353):
- Added PendingMessageStore from PR #335
- Integrated persistent queue into SessionManager
- Modified SDKAgent to mark messages complete
- Updated SessionStore with pending_messages migration
- Updated worker-types.ts with new interfaces

Agent C - Batch Endpoint Verification (Issue #348):
- Created batch-observations.test.ts
- Updated worker-service.mdx documentation

Also includes:
- Documentation context files (biomimetic, windows struggles)
- Build artifacts from agent testing

This work will be re-evaluated after v7.3.0 release.

docs/context/biomimetic/biomimetic-report.md

@@ -0,0 +1,152 @@
+# Research Report: The Genesis of Biomimetic Architecture in Claude-Mem
+
+## Executive Summary
+
+The concept of **"biomimetic architecture"** in claude-mem emerged organically during a concentrated development period in mid-November 2025, crystallizing around three foundational observations created on November 17, 2025. What began as a practical solution to AI context window exhaustion evolved into a comprehensive philosophy of mirroring human memory systems while augmenting them with computational advantages. This report traces the intellectual journey from problem identification through architectural breakthrough to public messaging.
+
+---
+
+## The Foundational Philosophy (November 17, 2025, Early Morning)
+
+The biomimetic architecture concept was formally articulated in three seminal observations created within a four-minute window between **1:31 AM and 1:35 AM** on November 17, 2025:
+
+### Observation #10140 (Nov 17, 2025 at 1:31 AM)
+**"Memory System Design Philosophy: Selective Retention with Total Recall Capability"**
+
+This observation established the core philosophical foundation: humans observe selectively and retain only portions that seem relevant, never creating complete transcripts of all experiences. The innovation was recognizing this selective retention as fundamental to human cognition, then creating a hybrid approach—normal operation uses human-like selective observation-based memory, but leverages computational advantages by maintaining capability for complete recall through optional transcript archival when needed.
+
+> **Key insight:** "Selective retention is fundamental to human cognition. The designed system replicates this behavior by observing and recording key observations, decisions, and discoveries rather than archiving everything."
+
+### Observation #10142 (Nov 17, 2025 at 1:35 AM)
+**"Biological Memory Principles in Endless Mode Architecture"**
+
+Created just four minutes later, this observation made the problem-solution connection explicit: Claude's context window was exploding from endless raw data accumulation—exactly the same problem biological brains evolved to solve through compression. The architecture directly implements the brain's solution: compressing experiences into abstract observations rather than retaining verbose raw transcripts.
+
+> **Critical innovation articulated:** "Unlike human memory which permanently loses raw data once compressed, Endless Mode maintains an archive of the original data. This creates a hybrid approach: the working memory operates on compressed abstractions for efficiency, while the full data remains available for later retrieval."
+
+The observation concluded: *"This design naturally feels correct because it implements proven biological principles at the AI level—the brain's solution to memory management, now augmented with perfect archival recall."*
+
+---
+
+## The Breakthrough: 95.1% Token Reduction (November 21, 2025)
+
+### Observation #13556 (Nov 21, 2025 at 10:25 PM)
+**"Endless Mode breakthrough: 95.1% token reduction through biomimetic memory compression"**
+
+Four days after the philosophical foundation was laid, the team validated the approach with empirical data. Real dataset analysis of 48 observations showed **95.1% token reduction** (16.5M → 801K tokens) with **20.6x efficiency gains**. The breakthrough document revealed the critical insight: observations are not lossy data compression but rather **memoized synthesis results**—caching the computational output Claude would generate from reading raw data.
+
+This transformed the recursive synthesis problem from **O(N²) quadratic complexity to O(N) linear complexity**. Each tool use previously forced Claude to re-read and re-synthesize ALL previous tool outputs. With Endless Mode, Claude reads pre-computed observations instead, turning each synthesis into a one-time cost with cached results.
+
+The observation explicitly framed this as: *"Two-tier memory system mimicking human working memory (compressed observations) but with digital advantages (perfect archival recall)."*
+
+---
+
+## Hybrid Architecture Recognition (November 21, 2025)
+
+### Observation #13169 (Nov 21, 2025 at 1:32 AM)
+**"Claude-mem Identified as Hybrid Architecture Mirroring Human Memory Systems"**
+
+This observation synthesized the complete architectural understanding, identifying claude-mem as combining three components that directly parallel human memory systems:
+
+1. **Episodic Memory** - Temporal timelines storing autobiographical, action-based experiences
+   *("On Nov 20, I fixed auth bug in session X")*
+
+2. **Semantic Memory** - RAG-like vector similarity search for retrieving relevant past episodes
+   *("Find all times I worked on authentication")*
+
+3. **Working Memory Compression** - Endless Mode preventing exponential context growth during active sessions
+   *(forget details, keep insights)*
+
+**The full lifecycle:** During sessions, Endless Mode compresses in real-time; between sessions, observations are stored in episodic memory; new sessions start with RAG-like retrieval plus temporal timeline injection.
+
+### Observation #13177 (Nov 21, 2025 at 1:35 AM)
+**"Final Synthesis: General-Purpose AI Context Management Solution for Entire Industry"**
+
+This observation expanded the vision beyond coding assistants, identifying seven application domains (healthcare, therapy, education, research, personal assistants, gaming, journalism) with the universal pattern: anywhere AI accumulates context over time benefits from ~80% compression.
+
+> **Critical distinction clarified:** "RAG accesses external static knowledge while claude-mem accesses the AI's own episodic memories. The system combines episodic memory, RAG-like retrieval, and real-time compression, making it more sophisticated than pure RAG with temporal, autobiographical, and compression features."
+
+---
+
+## Translation to Public Messaging (November 26, 2025)
+
+### Observation #15781 (Nov 26, 2025 at 5:15 PM)
+**"Memory search reveals 19 results on biomimetic design philosophy origins"**
+
+Five days later, during landing page development, the team executed a memory search for "biomimetic human memory design philosophy" which returned 19 matches. This search surfaced the November 17th foundational observations, providing the backstory needed for public-facing content development.
+
+### Observation #15757 (Nov 26, 2025 at 4:30 PM)
+**"BiomimeticDesign Component Created with Human Memory Philosophy Narrative"**
+
+The team created a landing page component explaining the philosophy to users. The narrative established that LLMs "simply DO" with no retention between sessions, then explained human memory as reconstructive—built from scattered fragments rather than photographic playback—framed as *"genius compression, not a bug."*
+
+**The three-pillar architecture** directly mapped human cognitive systems to technical implementation:
+
+- **Episodic Memory** → Timeline Observations
+- **Semantic Memory** → RAG Vector Search
+- **Working Memory** → Endless Mode (95% compression)
+
+### Observation #15818 (Nov 26, 2025 at 5:27 PM)
+**"Timeline Search as Causal Navigation Pattern Over Efficiency Metrics"**
+
+This observation refined the public messaging, identifying that the actual innovation wasn't compression percentages but **timeline-based search** returning contextual windows (7 before, 7 after) to expose causal relationships, combined with semantically rich titles functioning as retrieval cues.
+
+> **Key insight:** "The proof of effectiveness is behavioral: Claude knows exactly where to go without searching, using only index tables. The upfront cost of creating detailed observations eliminates ongoing re-synthesis cost—the understanding was already built, and the index preserves access to that synthesis."
+
+### Observation #15805 (Nov 26, 2025 at 5:24 PM)
+**"Reframed landing page copy from abstract to concrete Claude experience"**
+
+User feedback about "low context malarkey" prompted a pivot from theoretical human memory metaphors to concrete Claude behavior descriptions. The messaging shifted to specific examples:
+
+- **Pain point:** Claude re-reading, re-discovering, re-researching
+- **Solution:** Timeline feature showing 7 observations before/after
+- **Proof:** "It barely ever searches. It just knows where to go."
+
+---
+
+## The Terminology Debate (December 2, 2025)
+
+### Observation #19374 (Dec 2, 2025 at 7:37 PM)
+**"User Questioning Biomimetic Design Terminology"**
+
+The user raised questions about whether "biomimetic design" terminology should be changed to alternative phrasing, indicating potential reconsideration of naming conventions.
+
+### Observation #19377 (Dec 2, 2025 at 7:38 PM)
+**"Renamed BiomimeticDesign component to HowYouRemember"**
+
+The component was renamed from "BiomimeticDesign" to "HowYouRemember" for user-friendliness, though the underlying architecture and philosophy remained unchanged. The renaming improved semantic clarity by aligning the component name with its actual content—explaining how users can remember and query information.
+
+---
+
+## Key Timeline
+
+| Date | Time | Event |
+|------|------|-------|
+| **Nov 17, 2025** | 1:31-1:35 AM | Core biomimetic philosophy articulated in observations #10140 and #10142 |
+| **Nov 17, 2025** | 3:28 PM | Observation #10364 documents comprehensive development narrative |
+| **Nov 21, 2025** | 1:32 AM | Hybrid architecture recognition in observation #13169 |
+| **Nov 21, 2025** | 10:25 PM | Breakthrough validation with 95.1% token reduction in observation #13556 |
+| **Nov 26, 2025** | 4:30-5:27 PM | Public-facing BiomimeticDesign component created and messaging refined |
+| **Dec 2, 2025** | 7:37 PM | Terminology questioned and component renamed to HowYouRemember |
+
+---
+
+## Conclusion
+
+The biomimetic architecture concept emerged from a deep first-principles analysis of the AI context management problem. Rather than treating memory as a pure engineering challenge, the team recognized the parallel to biological systems that evolved to solve identical problems.
+
+The innovation wasn't merely copying human memory limitations, but rather **understanding the why behind selective retention and compression**, then augmenting those principles with computational advantages (perfect archival recall).
+
+The concept evolved through distinct phases:
+1. **Internal architectural philosophy** (Nov 17)
+2. **Empirical validation** (Nov 21)
+3. **Public messaging** (Nov 26)
+4. **User-friendly terminology** (Dec 2)
+
+...while preserving the core biomimetic principles that make the system work.
+
+---
+
+## References
+
+**Observations:** #10140, #10142, #10363, #10364, #13169, #13177, #13556, #15757, #15781, #15784, #15785, #15805, #15818, #15824, #19374, #19377

docs/context/biomimetic/references/unknown-obs-10140-.md

@@ -0,0 +1,23 @@
+# Observation #10140
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-10142-.md

@@ -0,0 +1,23 @@
+# Observation #10142
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-10363-.md

@@ -0,0 +1,23 @@
+# Observation #10363
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-10364-.md

@@ -0,0 +1,23 @@
+# Observation #10364
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-13169-.md

@@ -0,0 +1,23 @@
+# Observation #13169
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-13177-.md

@@ -0,0 +1,23 @@
+# Observation #13177
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-13556-.md

@@ -0,0 +1,23 @@
+# Observation #13556
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-15757-.md

@@ -0,0 +1,23 @@
+# Observation #15757
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-15781-.md

@@ -0,0 +1,23 @@
+# Observation #15781
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-15784-.md

@@ -0,0 +1,23 @@
+# Observation #15784
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-15785-.md

@@ -0,0 +1,23 @@
+# Observation #15785
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-15805-.md

@@ -0,0 +1,23 @@
+# Observation #15805
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-15818-.md

@@ -0,0 +1,23 @@
+# Observation #15818
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-15824-.md

@@ -0,0 +1,23 @@
+# Observation #15824
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-19374-.md

@@ -0,0 +1,23 @@
+# Observation #19374
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/biomimetic/references/unknown-obs-19377-.md

@@ -0,0 +1,23 @@
+# Observation #19377
+
+**Created**: 
+**Type**: 
+**Session**: 
+**Project**: 
+
+## Title
+
+
+## Subtitle
+
+
+## Narrative
+
+
+## Facts
+
+## Concepts
+
+
+## Discovery Tokens
+

docs/context/windows-bun-worker-struggles.md

@@ -0,0 +1,332 @@
+# Windows, Bun, and Worker Service Struggles
+
+A comprehensive chronicle of platform-specific issues, attempted fixes, and architectural decisions.
+
+## Executive Summary
+
+The claude-mem project has faced persistent Windows-specific issues centered around three core problems:
+
+1. **Console Window Popups**: Blank terminal windows appearing when spawning worker and SDK subprocess
+2. **Zombie Socket Issues**: Bun leaving TCP sockets in LISTEN state after termination on Windows
+3. **Process Management Complexity**: Platform-specific spawning logic and reliability issues
+
+These issues have driven multiple PRs, architectural pivots, and significant debate about runtime switching (Bun → Node.js).
+
+---
+
+## Timeline of Issues
+
+### Issue #209: Windows Worker Startup Failures (Dec 12-13, 2025)
+
+**Problem**: Worker service failed to start on Windows using PowerShell Start-Process approach.
+
+**Symptoms**:
+- Worker startup attempted via `powershell.exe -NoProfile -NonInteractive -Command Start-Process`
+- Health check retries exhausted (15 attempts over 15 seconds)
+- Users left unable to start worker manually
+
+**Root Causes**:
+- Platform-conditional process spawning (PowerShell for Windows, PM2 for Unix)
+- PowerShell spawning without `-PassThru` to capture PID
+- Inconsistent process management across platforms
+
+**Resolution**: Issue was marked as closed, suggesting it was resolved in v7.1.0 through architectural unification with Bun-based ProcessManager using PID file tracking consistently across all platforms.
+
+**Status**: ✅ Resolved (pre-PR #335)
+
+---
+
+### Issue #309 & PR #315: Console Window Popups (Dec 14-15, 2025)
+
+**Problem**: Blank terminal windows appear when spawning worker processes and SDK subprocesses on Windows.
+
+**First Attempted Fix (PR #315)**: Add `windowsHide: true` to spawn options
+
+**Why It Failed**: Node.js bug #21825 - `windowsHide: true` is **ignored** when `detached: true` is also set. Both flags are required:
+- `detached: true` - Needed for background process
+- `windowsHide: true` - Needed to hide window (but doesn't work when detached)
+
+**Testing Results** (by ToxMox):
+- Tested PR #315 on Windows 11
+- Confirmed blank terminal windows still appear for both worker and SDK subprocess spawns
+- Affects both `ProcessManager.ts` (worker) and `SDKAgent.ts` (SDK subprocess)
+
+**Working Solution**: Use PowerShell's `Start-Process` with `-WindowStyle Hidden` flag instead of standard spawn.
+
+**Status**: ❌ PR #315 closed in favor of more comprehensive solution
+
+---
+
+### Bun Zombie Socket Issue (Dec 15, 2025)
+
+**Problem**: Bun leaves TCP sockets in zombie LISTEN state on Windows after worker termination.
+
+**Symptoms**:
+- Port remains bound even though no process owns it
+- `OwningProcess` shows 0 or dead PID
+- New worker instances cannot start due to `EADDRINUSE` errors
+- Happens regardless of termination method (process.exit(), external kill, Ctrl+C)
+- **Only system reboot clears zombie ports**
+
+**Upstream Tracking**:
+- Bun issue #12127
+- Bun issue #5774
+- Bun issue #8786
+
+**Impact**: Windows users may need to reboot their systems when worker crashes or is restarted.
+
+**Proposed Solution**: Switch worker runtime from Bun to Node.js on Windows (or globally).
+
+**Status**: 🟡 Unresolved - Platform-specific bug in Bun's Windows socket cleanup
+
+---
+
+### SDK Subprocess Hang Issue (Dec 15, 2025)
+
+**Problem**: SDK subprocesses can hang indefinitely, blocking observation processing.
+
+**Root Cause**: `AbortController.abort()` does not actually terminate child processes.
+
+**Symptoms**:
+- For-await loop blocks forever waiting for output from hung subprocess
+- Observation processing halts
+- No recovery mechanism
+
+**Solution**: Implement watchdog timer that explicitly kills child processes using platform-specific commands:
+- **Windows**: `wmic process where ParentProcessId=<pid> delete`
+- **Unix**: `pkill -P <pid>`
+
+**Timeout**: `SDK_QUERY_TIMEOUT_MS` set to 2 minutes
+
+**Status**: ✅ Fixed in PR #335 (watchdog implementation)
+
+---
+
+## PR #335: Comprehensive Windows Fix (Dec 15, 2025)
+
+### What It Attempted
+
+ToxMox developed a comprehensive PR addressing all Windows issues simultaneously:
+
+1. **PowerShell-based spawning** to fix popup windows
+2. **Runtime switch** from Bun to Node.js (globally) to fix zombie sockets
+3. **Queue monitoring system** with persistent message queue
+4. **Watchdog service** for stuck message recovery
+5. **SQLite compatibility layer** for Node.js support
+
+### Architecture Decisions
+
+**ProcessManager Changes**:
+- Switched from `startWithBun()` to `startWithNode()`
+- Windows: Uses PowerShell `Start-Process -WindowStyle Hidden -PassThru`
+- Unix: Uses standard `spawn()` with `detached: true`
+- Captures PID via PowerShell `Select-Object -ExpandProperty Id`
+- Comment states: "Use Node on all platforms (Bun has zombie socket issues on Windows)"
+
+**SQLite Compatibility Layer**:
+- Created `sqlite-compat.ts` adapter pattern
+- Provides `bun:sqlite` API compatibility via `better-sqlite3`
+- Allows code to work with both Bun and Node.js runtimes
+
+### Critical Issues Identified
+
+#### 1. **Global vs Platform-Conditional Runtime**
+
+**The Inconsistency**: Code comment explicitly states zombie sockets occur "on Windows", yet solution applies Node.js universally across all platforms.
+
+**Questions Raised**:
+- Why sacrifice Bun's performance on macOS/Linux where no issues documented?
+- Platform-specific spawning already implemented - why not platform-specific runtime?
+- No documented Bun reliability issues on non-Windows platforms
+
+#### 2. **Performance Regressions**
+
+**better-sqlite3 Blocking**:
+- Synchronous-only API blocks Node.js event loop during all DB operations
+- Contrasts with Bun's async SQLite support
+- Affects: enqueue, markProcessing, markProcessed, watchdog checks
+
+**Watchdog Polling Overhead**:
+- Full table scans every 30 seconds even when idle
+- Constant database I/O overhead
+- No max queue size limits = unbounded growth
+
+**Startup Latency**:
+- Node.js initialization (slower than Bun)
+- Native module loading (better-sqlite3)
+- Database migrations
+- Stuck message scan
+- Watchdog initialization
+- HTTP server startup
+
+#### 3. **Build Dependencies**
+
+**better-sqlite3 Requirements**:
+- node-gyp
+- Python
+- C++ compiler toolchains
+- Visual Studio Build Tools (Windows)
+
+**Impact**:
+- Local development machines without build tools fail
+- CI/CD pipelines need updated Docker images
+- Restricted environments where compilers not permitted
+- ARM/M1 Mac compatibility issues
+
+#### 4. **Migration Risks**
+
+**Breaking Changes**:
+- Automatic database migration adds `pending_messages` table
+- Runtime switch not documented in PR
+- Node.js becomes undocumented hard requirement
+- No migration guide or rollback procedure
+
+**Unanswered Questions**:
+- What happens to in-flight messages during upgrade?
+- Can users safely downgrade?
+- Is migration idempotent?
+
+#### 5. **Code Quality Issues**
+
+**Command Injection Risk** (ProcessManager.ts:67):
+- PowerShell commands use template literal concatenation
+- Vulnerable if `MARKETPLACE_ROOT` or script paths attacker-controlled
+- Should use array-based argument passing
+
+**Missing Error Handling** (WatchdogService.ts:61):
+- `setInterval` callback lacks error handling
+- Timer continues running if `check()` throws
+- Creates zombie watchdog scenario
+
+**No Queue Size Limits**:
+- Unbounded database growth if messages accumulate
+- Failed messages (exceeding `maxRetries`) accumulate indefinitely
+- Only 24-hour retention for processed messages
+
+---
+
+## Assessment and Recommendations
+
+### What Was Validated
+
+**Legitimate Windows Issues**:
+- ✅ Console window popups are real (Node.js bug #21825)
+- ✅ PowerShell `Start-Process` solution works
+- ✅ Bun zombie socket issue is real and Windows-specific
+- ✅ SDK subprocess hang issue is real
+
+### What Remains Questionable
+
+**Global Runtime Switch**:
+- ❌ No evidence Bun problematic on macOS/Linux
+- ❌ Platform-conditional runtime not considered
+- ❌ Performance trade-offs not documented
+- ❌ "Windows-only" issue applied globally
+
+**Zombie Socket Root Cause**:
+- 🟡 May be fixable with proper cleanup handlers:
+  - Missing `server.close()` calls before exit
+  - Processes killed with `SIGKILL` before cleanup finishes
+  - Missing `SIGTERM` signal handlers for graceful shutdown
+- 🟡 Runtime switch may be unnecessary over-engineering
+
+### Salvageable Components
+
+**If Extracted into Separate PRs**:
+
+1. **PowerShell Spawning for Windows Worker**
+   - Focused PR: "Windows: Use Node.js instead of Bun for worker process"
+   - Platform-conditional logic (Node.js on Windows, Bun elsewhere)
+   - Independent justification required
+
+2. **SQLite Compatibility Layer**
+   - Well-designed adapter pattern
+   - Requires independent justification for Node.js runtime need
+   - Should not be bundled with other changes
+
+3. **Queue Monitoring UI Concept**
+   - Valuable visibility into worker state
+   - Should build on in-memory state first
+   - Remove database persistence requirement initially
+
+4. **Watchdog Improvements**
+   - SDK subprocess timeout handling
+   - Evidence of superiority over current approach needed
+
+---
+
+## Current Status
+
+### Resolved
+- ✅ Issue #209: Windows worker startup (v7.1.0)
+- ✅ SDK subprocess hang issue (watchdog implementation)
+
+### In Progress
+- 🔄 PR #339: Windows console popup fix (extracted from PR #335)
+- 🔄 PR #338: Queue monitoring system (extracted from PR #335)
+
+### Open Questions
+- ❓ Should runtime switch be global or Windows-only?
+- ❓ Can zombie socket issue be fixed without runtime switch?
+- ❓ Is better-sqlite3's synchronous blocking acceptable?
+- ❓ Should queue persistence be in-memory first?
+
+---
+
+## Lessons Learned
+
+### Architectural Principles Violated
+
+**YAGNI**: Queue persistence, watchdog service, and comprehensive monitoring added without proven need.
+
+**Happy Path**: Should have started with simplest Windows fix (PowerShell spawning), validated, then added complexity if needed.
+
+**Incremental Validation**: Bundling multiple architectural changes prevents isolating what actually solves the problem.
+
+### What Should Have Happened
+
+1. **Phase 1**: PowerShell spawning fix for Windows console popups (targeted, testable)
+2. **Phase 2**: Investigate zombie socket root cause (cleanup handlers vs runtime switch)
+3. **Phase 3**: If runtime switch justified, implement as Windows-conditional first
+4. **Phase 4**: Add queue monitoring as optional feature with in-memory state
+5. **Phase 5**: Add persistence only if in-memory insufficient
+
+### Key Takeaways
+
+- **Windows-specific issues don't justify global architectural changes** without clear evidence
+- **Platform-conditional logic is acceptable** when solving platform-specific problems
+- **Native module dependencies are heavy** - avoid unless necessary
+- **Performance regressions need explicit justification** - synchronous blocking, startup latency, polling overhead all impact UX
+- **Bundle size matters** - build tools, compilers, Python are significant requirements
+
+---
+
+## References
+
+**GitHub Issues**:
+- #209: Windows worker startup failures
+- #309: Console window popups
+- #315: windowsHide approach (closed)
+
+**PRs**:
+- #335: Comprehensive Windows fix (under review)
+- #338: Queue monitoring system (extracted)
+- #339: Windows console popup fix (extracted)
+
+**Upstream Bugs**:
+- Node.js #21825: windowsHide ignored with detached
+- Bun #12127, #5774, #8786: Windows zombie sockets
+
+**Related Observations**:
+- #27302: PR #315 windowsHide failure analysis
+- #27233: Bun zombie socket discovery
+- #27232: Windows background window root cause
+- #27286: Runtime switch assessment
+- #27283: PowerShell process spawn fix
+- #27190: ProcessManager Node.js implementation
+- #24532: Issue #209 resolution
+
+---
+
+**Last Updated**: 2025-12-16
+**Document Status**: Comprehensive review based on memory search through #S3485