Update docs to reflect kernel restart bug (#34) resolution (#41)

- Update AGENTS.md with critical materializer determinism requirements
- Add detailed section about ctx.query() being forbidden in materializers
- Document specific commits (6e0fb4f, a1bf20d) that fixed the issue
- Provide code examples showing wrong vs correct materializer patterns
- Update HANDOFF.md to remove bug from critical issues, add to recent fixes
- Update ROADMAP.md to mark kernel session reliability as completed
- Upgrade auto kernel management priority due to more solid foundation

This prevents future developers from accidentally reintroducing side effects
in materializers that would cause LiveStore hash mismatches and kernel failures.

Author: rgbkrk

AGENTS.md

@@ -112,6 +112,67 @@ pnpm cache:clear       # Clear package cache
 - **Single source of truth**: No compiled artifacts needed - TypeScript handles type checking from source
 - **No timestamp fields** - LiveStore handles timing automatically
 
+### ⚠️ CRITICAL: Materializer Determinism Requirements
+
+**NEVER use `ctx.query()` in materializers** - This was the root cause of kernel restart bug #34.
+
+LiveStore requires all materializers to be **pure functions without side effects**. Any data needed by a materializer must be passed via the event payload, not looked up during materialization.
+
+**What caused the bug:**
+```typescript
+// ❌ WRONG - This causes LiveStore.UnexpectedError materializer hash mismatch
+"v1.ExecutionCompleted": ({ queueId }, ctx) => {
+  const queueEntries = ctx.query(
+    tables.executionQueue.select().where({ id: queueId }).limit(1)
+  );
+  // ... rest of materializer
+}
+```
+
+**Correct approach:**
+```typescript
+// ✅ CORRECT - All needed data in event payload
+"v1.ExecutionCompleted": ({ queueId, cellId, status }) => [
+  tables.executionQueue.update({ 
+    status: status === "success" ? "completed" : "failed" 
+  }).where({ id: queueId }),
+  tables.cells.update({ 
+    executionState: status === "success" ? "completed" : "error" 
+  }).where({ id: cellId }),
+]
+```
+
+**Fixed commits for reference:**
+- `6e0fb4f`: Fixed ExecutionCompleted/ExecutionCancelled materializers
+- `a1bf20d`: Fixed ExecutionStarted materializer
+
+**Rule**: If you need data in a materializer, add it to the event schema and pass it when committing the event. Materializers must be deterministic and reproducible.
+
+### Recent Critical Fixes (December 2024)
+
+**Kernel Restart Bug (#34) - RESOLVED** ✅
+
+The project recently resolved a major stability issue where 3rd+ kernel sessions would fail to receive work assignments due to LiveStore materializer hash mismatches. This was caused by non-deterministic materializers using `ctx.query()` calls.
+
+**What was broken:**
+- ExecutionCompleted, ExecutionCancelled, and ExecutionStarted materializers were using `ctx.query()` 
+- This made them non-deterministic, causing LiveStore to shut down with "UnexpectedError materializer hash mismatch"
+- Kernel restarts would accumulate terminated sessions and eventually fail
+
+**How it was fixed (commits 6e0fb4f and a1bf20d):**
+1. **Added cellId to event schemas**: ExecutionCompleted, ExecutionCancelled, ExecutionStarted now include `cellId` in payload
+2. **Removed all ctx.query() calls**: Materializers now receive all needed data via event payload
+3. **Updated all event commits**: All places that commit these events now pass `cellId` explicitly
+4. **Made materializers pure functions**: No side effects, deterministic output for same input
+
+**Impact:** Kernel sessions are now reliable across multiple restarts, enabling future automated kernel management.
+
+**For Future Development:**
+- Always check that new materializers are pure functions
+- Never use `ctx.query()` in materializers - pass data via event payload
+- Reference these commits when adding new execution-related events
+- Test kernel restart scenarios when modifying execution flow
+
 ### Local-First Architecture
 - All data operations happen locally first
 - Events synced across clients via document worker
@@ -215,6 +276,8 @@ pnpm cache:warm-up   # Pre-loads numpy, pandas, matplotlib, requests, etc.
 
 **Do NOT use manual timestamps in code or events.** LiveStore automatically handles all timing through its event sourcing system. Focus development on features and architecture rather than timestamp management.
 
+**⚠️ CRITICAL: Do NOT use `ctx.query()` in materializers.** This causes LiveStore materializer hash mismatches and kernel restart failures (see bug #34 - RESOLVED in commits 6e0fb4f and a1bf20d). All materializers must be pure functions with all needed data passed via event payload.
+
 **Testing is Critical**: Many claims about functionality need verification through proper integration tests. Core features exist but integration testing is minimal.
 
 **AI Tool Calling**: The next major enhancement is enabling AI to actively participate in notebook development through function calling - creating cells, modifying content, and executing code.

HANDOFF.md

@@ -60,7 +60,7 @@
 
 ## Current Work State
 
-**Status**: 🚧 **Working Prototype** - Core collaborative editing, Python execution, and basic AI integration functional, rich outputs need verification
+**Status**: 🚧 **Working Prototype** - Core collaborative editing, Python execution, and basic AI integration functional, rich outputs need verification. Major kernel restart bug (#34) resolved.
 
 ### What's Actually Working ✅
 
@@ -72,6 +72,7 @@
 
 #### Python Execution
 - **Basic Python execution** - Code cells run Python via Pyodide (manual kernel startup)
+- **Kernel session reliability** - Fixed materializer side effects causing restart failures (#34) ✅
 - **Error handling** - Python exceptions properly captured and displayed
 - **Text output** - print() statements and basic stdout/stderr capture
 - **Execution queue** - Proper job queuing and status tracking
@@ -144,7 +145,7 @@
 - Streaming responses for better UX
 - Multi-turn conversation support
 
-### Priority 3: MCP Integration Foundation 🔮 LONG-TERM
+### Priority 4: MCP Integration Foundation 🔮 LONG-TERM
 **Status**: 🎯 **Architecture planning**
 
 **Goal**: Connect to Model Context Protocol providers for extensible AI tooling
@@ -169,23 +170,26 @@
 **Estimated effort**: 1-2 months (after tool calling foundation)
 **Impact**: Enables unlimited AI tool extensibility through Python ecosystem
 
-### Priority 4: Auto Kernel Management (High Impact)
+### Priority 3: Auto Kernel Management (High Impact) 🚀 UPGRADED
 **Current friction**: Manual `NOTEBOOK_ID=xyz pnpm dev:kernel` per notebook
 
 **Goal**: One-click notebook startup with automatic kernel lifecycle
 
+**Foundation now solid**: With kernel restart bug (#34) fixed, automated management is much more viable
+
 **Next actions**:
 - Modify `pnpm dev` to auto-spawn kernels per notebook
 - Add kernel health monitoring and restart capability
 - Better error messages when kernels fail or disconnect
+- Leverage fixed kernel session reliability for robust auto-restart
 
 **Files to modify**:
 - Root `package.json` - Update dev script
 - `packages/web-client/src/components/notebook/NotebookViewer.tsx` - Status display
 - Add kernel process management utilities
 
-**Estimated effort**: 2-3 hours
-**Impact**: Removes major user friction
+**Estimated effort**: 2-3 hours (reduced due to fixed foundation)
+**Impact**: Removes major user friction + leverages recent reliability improvements
 
 ### Priority 5: Rich Output Verification (Medium)
 **Current state**: Code exists but integration unclear
@@ -262,7 +266,11 @@ pnpm test               # Full test suite (27 passing, 13 skipped)
 - **Performance claims unverified**: Need integration tests to validate speed/output claims
 
 ### Known Critical Issues
-- **🐛 Kernel Restart Bug**: 3rd+ kernel sessions fail to receive work assignments due to LiveStore web client shutdowns when multiple terminated sessions accumulate (see https://github.com/rgbkrk/anode/issues/34 and branch `annoying-multiples-bug`)
+- **None currently identified** - Major kernel restart bug (#34) resolved by cleaning up side effects in materializers
+
+### Recent Fixes ✅
+- **Kernel restart bug (#34)** - Fixed materializer side effects that caused 3rd+ kernel sessions to fail work assignments
+- **LiveStore web client shutdowns** - Resolved accumulation of terminated sessions causing kernel communication failures
 
 ### Schema & Architecture Notes
 - All packages use direct TypeScript imports: `../../../shared/schema.js`

ROADMAP.md

@@ -2,14 +2,15 @@
 
 **Vision**: A real-time collaborative notebook system enabling seamless AI ↔ Python ↔ User interactions through local-first architecture.
 
-**Current Status**: Core prototype with collaborative editing, basic Python execution, and AI integration with context awareness working. AI tool calling and rich outputs in active development.
+**Current Status**: Core prototype with collaborative editing, basic Python execution, and AI integration with context awareness working. Major kernel restart bug (#34) resolved by fixing materializer side effects. AI tool calling and rich outputs in active development.
 
 ## Foundation Complete ✅
 
 ### Core Architecture
 - **LiveStore event-sourcing** - Real-time collaborative state management
 - **Direct TypeScript schema** - No build complexity, full type safety
 - **Reactive execution queue** - Kernel work detection without polling
+- **Reliable kernel sessions** - Fixed materializer side effects, stable multi-session operation
 - **Cell management** - Create, edit, move, delete with proper state sync
 - **Basic Python execution** - Code cells run via Pyodide (manual kernel startup)
 
@@ -54,6 +55,7 @@
 ### Automated Kernel Management
 **Goal**: Remove manual `NOTEBOOK_ID=xyz pnpm dev:kernel` friction
 
+- [x] **Kernel session reliability** - Fixed materializer side effects causing restart failures (#34)
 - [ ] **Auto-spawning kernels** - One-click notebook startup
 - [ ] **Kernel health monitoring** - Detect failures and restart
 - [ ] **Better status UI** - Clear feedback on kernel state