Release v5.2.0: Major Worker Service Refactor & UI Improvements

This release merges PR #69, delivering a comprehensive architectural refactor
of the worker service, extensive UI enhancements, and significant code cleanup.

🏗️ Architecture Changes (Worker Service v2)

**Modular Rewrite**: Extracted monolithic worker-service.ts into focused modules:
- DatabaseManager.ts (111 lines): Centralized database initialization
- SessionManager.ts (204 lines): Complete session lifecycle management
- SDKAgent.ts (309 lines): Claude SDK interactions & observation compression
- SSEBroadcaster.ts (86 lines): Server-Sent Events broadcast management
- PaginationHelper.ts (196 lines): Reusable pagination logic
- SettingsManager.ts (68 lines): Viewer settings persistence
- worker-types.ts (176 lines): Shared TypeScript types

**Key Improvements**:
- Eliminated duplicated session logic (4 instances → 1 helper)
- Replaced magic numbers with named constants
- Removed fragile PM2 string parsing
- Fail-fast error handling instead of silent failures
- Fixed SDK agent narrative assignment (obs.title → obs.narrative)

🎨 UI/UX Improvements

**ScrollToTop Component**: GPU-accelerated smooth scrolling button
**ObservationCard Refactor**: Fixed facts toggle, improved metadata display
**Pagination Enhancements**: Better loading states, error recovery, deduplication
**Card Consistency**: Unified layout patterns across all card types

📚 Documentation

**New Files** (7,542 lines):
- context/agent-sdk-ref.md (1,797 lines): Complete Agent SDK reference
- docs/worker-service-architecture.md (1,174 lines): v2 architecture docs
- docs/worker-service-rewrite-outline.md (1,069 lines): Refactor plan
- docs/worker-service-overhead.md (959 lines): Performance analysis
- docs/processing-indicator-*.md (980 lines): Processing status docs
- docs/typescript-errors.md (180 lines): Error reference
- PLAN-full-observation-display.md (468 lines): Future UI roadmap

🧹 Code Cleanup

**Deleted Dead Code** (~2,000 lines):
- src/shared/{config.ts,storage.ts,types.ts}
- src/utils/{platform.ts,usage-logger.ts}
- src/hooks/index.ts, src/sdk/index.ts
- docs/{VIEWER.md,worker-server-architecture.md}

**Files Changed**: 70 total (11 new, 7 deleted, 52 modified)
**Net Impact**: +7,470 lines (11,105 additions, 3,635 deletions)

🐛 Bug Fixes

- Fixed SDK agent narrative assignment (e22edad)
- Corrected PostToolUse hook field name (13643a5)
- Removed unnecessary worker startup from smart-install (6204fe9)
- Simplified context-hook worker management (6204fe9)

✅ Testing

All systems verified:
- Worker service starts successfully
- All hooks function correctly
- Viewer UI renders properly
- Build pipeline compiles without errors

📖 Reference

PR: #69
Previous Version: 5.1.4
Semantic Version: MINOR (backward compatible features & improvements)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

scripts/build-hooks.js

@@ -77,6 +77,7 @@ async function buildHooks() {
       format: 'cjs',
       outfile: `${hooksDir}/${WORKER_SERVICE.name}.cjs`,
       minify: true,
+      logLevel: 'error', // Suppress warnings (import.meta warning is benign)
       external: ['better-sqlite3'],
       define: {
         '__DEFAULT_PACKAGE_VERSION__': `"${version}"`
@@ -147,7 +148,7 @@ async function buildHooks() {
     console.log(`   Output: ${hooksDir}/`);
     console.log(`   - Hooks: *-hook.js`);
     console.log(`   - Worker: worker-service.cjs`);
-    console.log(`   - Search: search-server.js`);
+    console.log(`   - Search: search-server.mjs`);
     console.log('\n💡 Note: Dependencies will be auto-installed on first hook execution');
 
   } catch (error) {

scripts/smart-install.js

@@ -245,39 +245,6 @@ function shouldFailOnWorkerStartup(workerStarted) {
   return !workerStarted && !existsSync(NODE_MODULES_PATH);
 }
 
-function startWorker() {
-  const ECOSYSTEM_CONFIG = join(PLUGIN_ROOT, 'ecosystem.config.cjs');
-  const PM2_PATH = join(PLUGIN_ROOT, 'node_modules', '.bin', 'pm2');
-
-  log('🚀 Starting worker service...', colors.dim);
-
-  try {
-    // Use the full path to PM2 to avoid PATH issues on Windows
-    // PM2 will either start it or report it's already running (both are success cases)
-    execSync(`"${PM2_PATH}" start "${ECOSYSTEM_CONFIG}"`, {
-      cwd: PLUGIN_ROOT,
-      stdio: 'pipe', // Capture output to avoid clutter
-      encoding: 'utf-8',
-    });
-
-    log('✓ Worker service ready', colors.dim);
-    return true;
-
-  } catch (error) {
-    // PM2 errors are often non-critical (e.g., "already running")
-    // Don't fail the entire setup if worker start has issues
-    log(`⚠️  Worker startup issue (non-critical): ${error.message}`, colors.yellow);
-
-    // Check if it's just because worker is already running
-    if (error.message && (error.message.includes('already') || error.message.includes('exist'))) {
-      log('✓ Worker was already running', colors.dim);
-      return true;
-    }
-
-    return false;
-  }
-}
-
 async function main() {
   try {
     // Check if we need to install dependencies
@@ -289,25 +256,16 @@ async function main() {
 
       if (!installSuccess) {
         log('', colors.red);
-        log('❌ Installation failed - cannot start worker without dependencies', colors.bright);
-        log('', colors.reset);
-        log('Please resolve the installation issues above and try again.', colors.yellow);
+        log('⚠️  Installation failed', colors.yellow);
         log('', colors.reset);
         process.exit(1);
       }
     }
 
-    // Start/ensure worker is running (only after successful install or if deps already exist)
-    const workerStarted = startWorker();
+    // Worker will be started lazily when needed (e.g., when save-hook sends data)
+    // Context hook only needs database access, not the worker service
 
-    if (shouldFailOnWorkerStartup(workerStarted)) {
-      log('', colors.red);
-      log('❌ Worker failed to start and dependencies are missing', colors.bright);
-      log('', colors.reset);
-      process.exit(1);
-    }
-
-    // Success - dependencies installed (if needed) and worker running (or already running)
+    // Success - dependencies installed (if needed)
     process.exit(0);
 
   } catch (error) {