@onmars/lunar-core 0.1.0

package/src/__tests__/hook-runner.test.ts

@@ -0,0 +1,1689 @@
+/**
+ * # HookRunner — Functional Specification
+ *
+ * Lifecycle hook evaluation and execution engine for the memory system.
+ *
+ * ## Core responsibilities:
+ * - Evaluate guard conditions (providersAvailable, minMessages)
+ * - Execute built-in actions: promote, boost, context, summarize
+ * - Maintain declared order per lifecycle event
+ * - Best-effort execution: failures logged, never block
+ * - Mutable context: actions modify results/facts in-place
+ * - Extensible action registry for custom actions
+ *
+ * ## Key design decisions:
+ * - Guards check registration only (not health) for speed
+ * - Time window parser supports s/m/h/d/w units
+ * - Boost modifies scores in-place and re-sorts
+ * - Promote supports two strategies: extraction and recall-transfer
+ * - Context pre-loads results by appending to existing
+ * - Summarize updates context.sessionSummary for downstream hooks
+ */
+import { beforeEach, describe, expect, it } from 'bun:test'
+import type { HookCondition, HookEntry, HooksConfig, LifecycleEvent } from '../lib/config-loader'
+import type { HookContext, LLMFunction } from '../lib/hook-runner'
+import {
+  evaluateGuard,
+  getAction,
+  HookRunner,
+  listActions,
+  parseTimeWindow,
+  registerAction,
+} from '../lib/hook-runner'
+import type { Fact, MemoryProvider, MemoryResult, SearchOptions } from '../types/memory'
+
+// ═══════════════════════════════════════════════════════════════════
+// Test helpers
+// ═══════════════════════════════════════════════════════════════════
+
+function createMockProvider(
+  id: string,
+  options?: {
+    recallResults?: MemoryResult[]
+    failRecall?: boolean
+    failSave?: boolean
+    savedFacts?: Fact[][]
+    instructions?: string
+  },
+): MemoryProvider {
+  const savedFacts: Fact[][] = options?.savedFacts ?? []
+
+  return {
+    id,
+    name: `Mock ${id}`,
+    async init() {},
+    async destroy() {},
+    async recall(_query: string, _opts?: SearchOptions): Promise<MemoryResult[]> {
+      if (options?.failRecall) throw new Error(`${id} recall failed`)
+      return options?.recallResults ?? []
+    },
+    async save(facts: Fact[]) {
+      if (options?.failSave) throw new Error(`${id} save failed`)
+      savedFacts.push(facts)
+    },
+    async health() {
+      return { ok: true }
+    },
+    agentInstructions() {
+      return options?.instructions ?? ''
+    },
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// parseTimeWindow — time window string to milliseconds
+// ═══════════════════════════════════════════════════════════════════
+
+describe('parseTimeWindow', () => {
+  it('parses seconds', () => {
+    expect(parseTimeWindow('30s')).toBe(30_000)
+  })
+
+  it('parses minutes', () => {
+    expect(parseTimeWindow('5m')).toBe(300_000)
+  })
+
+  it('parses hours', () => {
+    expect(parseTimeWindow('24h')).toBe(86_400_000)
+  })
+
+  it('parses days', () => {
+    expect(parseTimeWindow('7d')).toBe(604_800_000)
+  })
+
+  it('parses weeks', () => {
+    expect(parseTimeWindow('2w')).toBe(1_209_600_000)
+  })
+
+  it('defaults to 24h for invalid format', () => {
+    expect(parseTimeWindow('invalid')).toBe(86_400_000)
+    expect(parseTimeWindow('')).toBe(86_400_000)
+    expect(parseTimeWindow('24')).toBe(86_400_000)
+    expect(parseTimeWindow('h24')).toBe(86_400_000)
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// evaluateGuard — guard condition evaluation
+// ═══════════════════════════════════════════════════════════════════
+
+describe('evaluateGuard', () => {
+  const providers = new Map<string, MemoryProvider>([
+    ['brain', createMockProvider('brain')],
+    ['engram', createMockProvider('engram')],
+  ])
+  const baseContext: HookContext = { messageCount: 5 }
+
+  it('returns true when no guard is defined', () => {
+    expect(evaluateGuard(undefined, baseContext, providers)).toBe(true)
+  })
+
+  it('returns true when all providers are available', () => {
+    const guard: HookCondition = { providersAvailable: ['brain', 'engram'] }
+    expect(evaluateGuard(guard, baseContext, providers)).toBe(true)
+  })
+
+  it('returns false when a required provider is missing', () => {
+    const guard: HookCondition = { providersAvailable: ['brain', 'missing'] }
+    expect(evaluateGuard(guard, baseContext, providers)).toBe(false)
+  })
+
+  it('returns true when messageCount meets minMessages', () => {
+    const guard: HookCondition = { minMessages: 3 }
+    expect(evaluateGuard(guard, baseContext, providers)).toBe(true)
+  })
+
+  it('returns false when messageCount is below minMessages', () => {
+    const guard: HookCondition = { minMessages: 10 }
+    expect(evaluateGuard(guard, baseContext, providers)).toBe(false)
+  })
+
+  it('requires ALL conditions to be met', () => {
+    const guard: HookCondition = {
+      providersAvailable: ['brain'],
+      minMessages: 10, // context has 5 — should fail
+    }
+    expect(evaluateGuard(guard, baseContext, providers)).toBe(false)
+  })
+
+  it('returns true when all combined conditions are met', () => {
+    const guard: HookCondition = {
+      providersAvailable: ['brain'],
+      minMessages: 3,
+    }
+    expect(evaluateGuard(guard, baseContext, providers)).toBe(true)
+  })
+
+  it('returns true for empty providersAvailable array', () => {
+    const guard: HookCondition = { providersAvailable: [] }
+    expect(evaluateGuard(guard, baseContext, providers)).toBe(true)
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Action registry — extensibility
+// ═══════════════════════════════════════════════════════════════════
+
+describe('action registry', () => {
+  it('has 4 built-in actions', () => {
+    const actions = listActions()
+    expect(actions).toContain('promote')
+    expect(actions).toContain('boost')
+    expect(actions).toContain('context')
+    expect(actions).toContain('summarize')
+  })
+
+  it('registers and retrieves custom actions', () => {
+    const customAction = async () => {}
+    registerAction('custom-test', customAction)
+    expect(getAction('custom-test')).toBe(customAction)
+  })
+
+  it('overwrites existing actions', () => {
+    const original = getAction('boost')
+    const replacement = async () => {}
+    registerAction('boost', replacement)
+    expect(getAction('boost')).toBe(replacement)
+
+    // Restore original
+    if (original) registerAction('boost', original)
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// HookRunner — core lifecycle engine
+// ═══════════════════════════════════════════════════════════════════
+
+describe('HookRunner', () => {
+  it('returns context unchanged when no hooks for event', async () => {
+    const runner = new HookRunner({}, [])
+    const context: HookContext = { messageCount: 5 }
+    const result = await runner.run('sessionStart', context)
+    expect(result).toBe(context)
+  })
+
+  it('reports active events', () => {
+    const hooks: HooksConfig = {
+      sessionStart: [{ action: 'context', provider: 'engram' }],
+      afterRecall: [{ action: 'boost', provider: 'engram' }],
+    }
+    const runner = new HookRunner(hooks, [])
+    expect(runner.activeEvents).toContain('sessionStart')
+    expect(runner.activeEvents).toContain('afterRecall')
+    expect(runner.activeEvents).not.toContain('sessionEnd')
+  })
+
+  it('checks hasHooks correctly', () => {
+    const hooks: HooksConfig = {
+      sessionStart: [{ action: 'context', provider: 'engram' }],
+    }
+    const runner = new HookRunner(hooks, [])
+    expect(runner.hasHooks('sessionStart')).toBe(true)
+    expect(runner.hasHooks('sessionEnd')).toBe(false)
+  })
+
+  it('accepts provider array (converts to map by id)', async () => {
+    const savedFacts: Fact[][] = []
+    const providers = [createMockProvider('brain', { savedFacts })]
+    const hooks: HooksConfig = {
+      sessionEnd: [{ action: 'summarize', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, providers)
+
+    await runner.run('sessionEnd', {
+      messageCount: 3,
+      messages: [{ role: 'user', content: 'test' }],
+    })
+
+    expect(savedFacts.length).toBe(1)
+  })
+
+  it('accepts provider map', async () => {
+    const savedFacts: Fact[][] = []
+    const map = new Map<string, MemoryProvider>([
+      ['brain', createMockProvider('brain', { savedFacts })],
+    ])
+    const hooks: HooksConfig = {
+      sessionEnd: [{ action: 'summarize', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, map)
+
+    await runner.run('sessionEnd', {
+      messageCount: 3,
+      messages: [{ role: 'user', content: 'test' }],
+    })
+
+    expect(savedFacts.length).toBe(1)
+  })
+
+  it('skips hook when guard fails', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'engram',
+          to: 'brain',
+          when: { minMessages: 10 }, // context has 2 — guard fails
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [
+      createMockProvider('brain', { savedFacts }),
+      createMockProvider('engram'),
+    ])
+
+    await runner.run('afterSessionEnd', { messageCount: 2 })
+
+    expect(savedFacts.length).toBe(0) // hook was skipped
+  })
+
+  it('skips unknown actions gracefully', async () => {
+    const hooks: HooksConfig = {
+      sessionStart: [{ action: 'nonexistent-action' }],
+    }
+    const runner = new HookRunner(hooks, [])
+
+    // Should not throw
+    const result = await runner.run('sessionStart', { messageCount: 0 })
+    expect(result.messageCount).toBe(0)
+  })
+
+  it('continues after a hook failure (best-effort)', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      sessionEnd: [
+        { action: 'summarize', provider: 'failing' }, // will fail (provider not found)
+        { action: 'summarize', provider: 'brain' }, // should still run
+      ],
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('brain', { savedFacts })])
+
+    await runner.run('sessionEnd', {
+      messageCount: 3,
+      messages: [{ role: 'user', content: 'test' }],
+    })
+
+    // Second hook should have run despite first failing
+    expect(savedFacts.length).toBe(1)
+  })
+
+  it('executes hooks in declared order', async () => {
+    const order: string[] = []
+
+    registerAction('order-a', async () => {
+      order.push('a')
+    })
+    registerAction('order-b', async () => {
+      order.push('b')
+    })
+    registerAction('order-c', async () => {
+      order.push('c')
+    })
+
+    const hooks: HooksConfig = {
+      sessionStart: [{ action: 'order-a' }, { action: 'order-b' }, { action: 'order-c' }],
+    }
+    const runner = new HookRunner(hooks, [])
+
+    await runner.run('sessionStart', { messageCount: 0 })
+
+    expect(order).toEqual(['a', 'b', 'c'])
+  })
+
+  it('updates providers at runtime', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      sessionEnd: [{ action: 'summarize', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [])
+
+    // First run — no providers, summarize should skip
+    await runner.run('sessionEnd', {
+      messageCount: 3,
+      messages: [{ role: 'user', content: 'test' }],
+    })
+    expect(savedFacts.length).toBe(0)
+
+    // Add provider
+    runner.updateProviders([createMockProvider('brain', { savedFacts })])
+
+    // Second run — provider available, should save
+    await runner.run('sessionEnd', {
+      messageCount: 3,
+      messages: [{ role: 'user', content: 'test' }],
+    })
+    expect(savedFacts.length).toBe(1)
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Action: boost — recency-based score adjustment
+// ═══════════════════════════════════════════════════════════════════
+
+describe('action: boost', () => {
+  it('boosts recent results', async () => {
+    const hooks: HooksConfig = {
+      afterRecall: [
+        {
+          action: 'boost',
+          provider: 'engram',
+          recencyWindow: '24h',
+          factor: 1.5,
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('engram')])
+
+    const recentDate = new Date(Date.now() - 3_600_000) // 1h ago
+    const context: HookContext = {
+      messageCount: 0,
+      results: [
+        { content: 'Old fact', score: 0.8, source: 'engram', storedAt: new Date('2020-01-01') },
+        { content: 'Recent fact', score: 0.6, source: 'engram', storedAt: recentDate },
+      ],
+    }
+
+    await runner.run('afterRecall', context)
+
+    // Recent fact should be boosted (0.6 * 1.5 = 0.9)
+    const recentResult = context.results!.find((r) => r.content === 'Recent fact')!
+    expect(recentResult.score).toBeCloseTo(0.9)
+
+    // Old fact should be unchanged
+    const oldResult = context.results!.find((r) => r.content === 'Old fact')!
+    expect(oldResult.score).toBe(0.8)
+  })
+
+  it('re-sorts after boosting', async () => {
+    const hooks: HooksConfig = {
+      afterRecall: [
+        {
+          action: 'boost',
+          factor: 1.5,
+          recencyWindow: '24h',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [])
+
+    const context: HookContext = {
+      messageCount: 0,
+      results: [
+        { content: 'High but old', score: 0.9, source: 'brain', storedAt: new Date('2020-01-01') },
+        { content: 'Low but recent', score: 0.5, source: 'engram', storedAt: new Date() },
+      ],
+    }
+
+    await runner.run('afterRecall', context)
+
+    // Low-but-recent (0.5 * 1.5 = 0.75) is still below old (0.9)
+    // But with a higher factor it could overtake
+    expect(context.results![0].content).toBe('High but old')
+  })
+
+  it('caps boosted score at 1.0', async () => {
+    const hooks: HooksConfig = {
+      afterRecall: [
+        {
+          action: 'boost',
+          factor: 2.0,
+          recencyWindow: '24h',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [])
+
+    const context: HookContext = {
+      messageCount: 0,
+      results: [{ content: 'High score', score: 0.9, source: 'x', storedAt: new Date() }],
+    }
+
+    await runner.run('afterRecall', context)
+
+    // 0.9 * 2.0 = 1.8 → capped at 1.0
+    expect(context.results![0].score).toBe(1.0)
+  })
+
+  it('filters by provider when specified', async () => {
+    const hooks: HooksConfig = {
+      afterRecall: [
+        {
+          action: 'boost',
+          provider: 'engram',
+          factor: 1.5,
+          recencyWindow: '24h',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [])
+
+    const context: HookContext = {
+      messageCount: 0,
+      results: [
+        { content: 'Brain result', score: 0.7, source: 'brain', storedAt: new Date() },
+        { content: 'Engram result', score: 0.7, source: 'engram', storedAt: new Date() },
+      ],
+    }
+
+    await runner.run('afterRecall', context)
+
+    // Only engram should be boosted
+    const brainResult = context.results!.find((r) => r.source === 'brain')!
+    const engramResult = context.results!.find((r) => r.source === 'engram')!
+    expect(brainResult.score).toBe(0.7) // unchanged
+    expect(engramResult.score).toBeCloseTo(1.0) // 0.7 * 1.5 = 1.05 → capped
+  })
+
+  it('does nothing with empty results', async () => {
+    const hooks: HooksConfig = {
+      afterRecall: [{ action: 'boost', factor: 1.5 }],
+    }
+    const runner = new HookRunner(hooks, [])
+    const context: HookContext = { messageCount: 0, results: [] }
+
+    await runner.run('afterRecall', context)
+    expect(context.results).toEqual([])
+  })
+
+  it('defaults to factor 1.2 and window 24h', async () => {
+    const hooks: HooksConfig = {
+      afterRecall: [{ action: 'boost' }],
+    }
+    const runner = new HookRunner(hooks, [])
+
+    const context: HookContext = {
+      messageCount: 0,
+      results: [{ content: 'Recent', score: 0.5, source: 'x', storedAt: new Date() }],
+    }
+
+    await runner.run('afterRecall', context)
+    expect(context.results![0].score).toBeCloseTo(0.6) // 0.5 * 1.2
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Action: promote — cross-provider knowledge transfer
+// ═══════════════════════════════════════════════════════════════════
+
+describe('action: promote', () => {
+  it('transfers via extraction using session summary', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'engram',
+          to: 'brain',
+          via: 'extraction',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [
+      createMockProvider('engram'),
+      createMockProvider('brain', { savedFacts }),
+    ])
+
+    await runner.run('afterSessionEnd', {
+      messageCount: 5,
+      messages: [{ role: 'user', content: 'Hello' }],
+      sessionSummary: 'Discussed project architecture',
+    })
+
+    expect(savedFacts.length).toBe(1)
+    expect(savedFacts[0][0].content).toBe('Discussed project architecture')
+    expect(savedFacts[0][0].category).toBe('session-promotion')
+    expect(savedFacts[0][0].tags).toContain('from:engram')
+  })
+
+  it('transfers via recall-save (default strategy)', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'engram',
+          to: 'brain',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [
+      createMockProvider('engram', {
+        recallResults: [
+          { content: 'Fact from engram session', score: 0.9 },
+          { content: 'Another engram fact', score: 0.8 },
+        ],
+      }),
+      createMockProvider('brain', { savedFacts }),
+    ])
+
+    await runner.run('afterSessionEnd', { messageCount: 3 })
+
+    expect(savedFacts.length).toBe(1)
+    expect(savedFacts[0]).toHaveLength(2)
+    expect(savedFacts[0][0].content).toBe('Fact from engram session')
+    expect(savedFacts[0][0].tags).toContain('promoted')
+  })
+
+  it('skips when from/to not specified', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      afterSessionEnd: [{ action: 'promote', from: 'engram' }], // missing 'to'
+    }
+    const runner = new HookRunner(hooks, [
+      createMockProvider('engram'),
+      createMockProvider('brain', { savedFacts }),
+    ])
+
+    await runner.run('afterSessionEnd', { messageCount: 3 })
+    expect(savedFacts.length).toBe(0)
+  })
+
+  it('skips when source provider not found', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'nonexistent',
+          to: 'brain',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('brain', { savedFacts })])
+
+    await runner.run('afterSessionEnd', { messageCount: 3 })
+    expect(savedFacts.length).toBe(0)
+  })
+
+  it('builds summary from context when no sessionSummary', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'engram',
+          to: 'brain',
+          via: 'extraction',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [
+      createMockProvider('engram'),
+      createMockProvider('brain', { savedFacts }),
+    ])
+
+    await runner.run('afterSessionEnd', {
+      messageCount: 7,
+      messages: [{ role: 'user', content: 'test' }],
+      topics: ['architecture', 'memory'],
+    })
+
+    expect(savedFacts[0][0].content).toContain('7 messages')
+    expect(savedFacts[0][0].content).toContain('architecture')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Action: context — pre-load context at session start
+// ═══════════════════════════════════════════════════════════════════
+
+describe('action: context', () => {
+  it('pre-loads results from a provider', async () => {
+    const hooks: HooksConfig = {
+      sessionStart: [
+        {
+          action: 'context',
+          provider: 'engram',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [
+      createMockProvider('engram', {
+        recallResults: [
+          { content: 'Previous session context', score: 0.8 },
+          { content: 'Recent activity', score: 0.7 },
+        ],
+      }),
+    ])
+
+    const context: HookContext = { messageCount: 0 }
+    await runner.run('sessionStart', context)
+
+    expect(context.results).toHaveLength(2)
+    expect(context.results![0].content).toBe('Previous session context')
+  })
+
+  it('appends to existing results', async () => {
+    const hooks: HooksConfig = {
+      sessionStart: [
+        {
+          action: 'context',
+          provider: 'engram',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [
+      createMockProvider('engram', {
+        recallResults: [{ content: 'New', score: 0.8 }],
+      }),
+    ])
+
+    const context: HookContext = {
+      messageCount: 0,
+      results: [{ content: 'Existing', score: 0.9 }],
+    }
+    await runner.run('sessionStart', context)
+
+    expect(context.results).toHaveLength(2)
+    expect(context.results![0].content).toBe('Existing')
+    expect(context.results![1].content).toBe('New')
+  })
+
+  it('skips when provider not specified', async () => {
+    const hooks: HooksConfig = {
+      sessionStart: [{ action: 'context' }], // missing provider
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('engram')])
+
+    const context: HookContext = { messageCount: 0 }
+    await runner.run('sessionStart', context)
+
+    expect(context.results).toBeUndefined()
+  })
+
+  it('handles provider with no results', async () => {
+    const hooks: HooksConfig = {
+      sessionStart: [
+        {
+          action: 'context',
+          provider: 'engram',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('engram', { recallResults: [] })])
+
+    const context: HookContext = { messageCount: 0 }
+    await runner.run('sessionStart', context)
+
+    expect(context.results).toBeUndefined()
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Action: summarize — session summary generation
+// ═══════════════════════════════════════════════════════════════════
+
+describe('action: summarize', () => {
+  it('saves session summary to provider', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      sessionEnd: [
+        {
+          action: 'summarize',
+          provider: 'brain',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('brain', { savedFacts })])
+
+    await runner.run('sessionEnd', {
+      messageCount: 10,
+      messages: [{ role: 'user', content: 'Hello' }],
+      sessionSummary: 'Detailed session analysis',
+    })
+
+    expect(savedFacts.length).toBe(1)
+    expect(savedFacts[0][0].content).toBe('Detailed session analysis')
+    expect(savedFacts[0][0].category).toBe('session-summary')
+    expect(savedFacts[0][0].tags).toContain('summary')
+  })
+
+  it('builds summary from context when no sessionSummary', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      sessionEnd: [
+        {
+          action: 'summarize',
+          provider: 'brain',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('brain', { savedFacts })])
+
+    await runner.run('sessionEnd', {
+      messageCount: 5,
+      messages: [{ role: 'user', content: 'test' }],
+      topics: ['hooks', 'memory'],
+    })
+
+    expect(savedFacts[0][0].content).toContain('5 messages')
+    expect(savedFacts[0][0].content).toContain('hooks')
+  })
+
+  it('updates context.sessionSummary for downstream hooks', async () => {
+    const hooks: HooksConfig = {
+      sessionEnd: [
+        {
+          action: 'summarize',
+          provider: 'brain',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('brain')])
+
+    const context: HookContext = {
+      messageCount: 3,
+      messages: [{ role: 'user', content: 'test' }],
+    }
+    await runner.run('sessionEnd', context)
+
+    expect(context.sessionSummary).toBeDefined()
+    expect(context.sessionSummary).toContain('3 messages')
+  })
+
+  it('skips when no messages', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      sessionEnd: [{ action: 'summarize', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('brain', { savedFacts })])
+
+    await runner.run('sessionEnd', { messageCount: 0 })
+
+    expect(savedFacts.length).toBe(0)
+  })
+})
+
+// ═════════════════════════════════════════════════════════════════════
+// Action: summarize — LLM-powered summarization
+// ═════════════════════════════════════════════════════════════════════
+
+describe('action: summarize (LLM)', () => {
+  it('uses LLM when available for rich summary', async () => {
+    const savedFacts: Fact[][] = []
+    const mockLlm: LLMFunction = async (prompt: string) => {
+      expect(prompt).toContain('user: Hello world')
+      return '- [Decision] Decided to use hooks for memory lifecycle'
+    }
+
+    const hooks: HooksConfig = {
+      sessionEnd: [{ action: 'summarize', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('brain', { savedFacts })], {
+      llm: mockLlm,
+    })
+
+    const context: HookContext = {
+      messageCount: 4,
+      messages: [
+        { role: 'user', content: 'Hello world' },
+        { role: 'assistant', content: 'Hi there' },
+        { role: 'user', content: 'Lets decide on hooks' },
+        { role: 'assistant', content: 'Good idea' },
+      ],
+    }
+    await runner.run('sessionEnd', context)
+
+    expect(savedFacts.length).toBe(1)
+    expect(savedFacts[0][0].content).toBe('- [Decision] Decided to use hooks for memory lifecycle')
+    expect(savedFacts[0][0].tags).toContain('llm-generated')
+    expect(savedFacts[0][0].importance).toBe(7)
+    expect(context.sessionSummary).toBe('- [Decision] Decided to use hooks for memory lifecycle')
+  })
+
+  it('falls back to basic summary when LLM fails', async () => {
+    const savedFacts: Fact[][] = []
+    const failingLlm: LLMFunction = async () => {
+      throw new Error('API rate limited')
+    }
+
+    const hooks: HooksConfig = {
+      sessionEnd: [{ action: 'summarize', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('brain', { savedFacts })], {
+      llm: failingLlm,
+    })
+
+    await runner.run('sessionEnd', {
+      messageCount: 3,
+      messages: [{ role: 'user', content: 'test' }],
+      topics: ['hooks', 'memory'],
+    })
+
+    expect(savedFacts[0][0].content).toContain('3 messages')
+    expect(savedFacts[0][0].content).toContain('hooks')
+    expect(savedFacts[0][0].tags).toContain('auto-generated')
+    expect(savedFacts[0][0].importance).toBe(5)
+  })
+
+  it('falls back to basic summary when LLM returns empty', async () => {
+    const savedFacts: Fact[][] = []
+    const emptyLlm: LLMFunction = async () => '   '
+
+    const hooks: HooksConfig = {
+      sessionEnd: [{ action: 'summarize', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('brain', { savedFacts })], {
+      llm: emptyLlm,
+    })
+
+    await runner.run('sessionEnd', {
+      messageCount: 5,
+      messages: [{ role: 'user', content: 'test' }],
+    })
+
+    expect(savedFacts[0][0].content).toContain('5 messages')
+  })
+
+  it('skips LLM for very short sessions (< 2 messages)', async () => {
+    const savedFacts: Fact[][] = []
+    let llmCalled = false
+    const mockLlm: LLMFunction = async () => {
+      llmCalled = true
+      return 'should not be called'
+    }
+
+    const hooks: HooksConfig = {
+      sessionEnd: [{ action: 'summarize', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('brain', { savedFacts })], {
+      llm: mockLlm,
+    })
+
+    await runner.run('sessionEnd', {
+      messageCount: 1,
+      messages: [{ role: 'user', content: 'hi' }],
+    })
+
+    expect(llmCalled).toBe(false)
+    expect(savedFacts[0][0].content).toContain('1 messages')
+  })
+
+  it('injects LLM into context for all hooks in event', async () => {
+    let contextHadLlm = false
+    registerAction('check-llm', async (_hook, ctx) => {
+      contextHadLlm = !!ctx.llm
+    })
+
+    const hooks: HooksConfig = {
+      sessionStart: [{ action: 'check-llm' }],
+    }
+    const mockLlm: LLMFunction = async () => 'test'
+    const runner = new HookRunner(hooks, [], { llm: mockLlm })
+
+    await runner.run('sessionStart', { messageCount: 0 })
+
+    expect(contextHadLlm).toBe(true)
+  })
+
+  it('does not override context.llm if already present', async () => {
+    const originalLlm: LLMFunction = async () => 'original'
+    const runnerLlm: LLMFunction = async () => 'runner'
+    let usedLlm: string | undefined
+
+    registerAction('check-which-llm', async (_hook, ctx) => {
+      usedLlm = ctx.llm ? await ctx.llm('test') : undefined
+    })
+
+    const hooks: HooksConfig = {
+      sessionStart: [{ action: 'check-which-llm' }],
+    }
+    const runner = new HookRunner(hooks, [], { llm: runnerLlm })
+
+    await runner.run('sessionStart', { messageCount: 0, llm: originalLlm })
+
+    expect(usedLlm).toBe('original')
+  })
+
+  it('setLLM updates the function at runtime', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      sessionEnd: [{ action: 'summarize', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [createMockProvider('brain', { savedFacts })])
+
+    // Without LLM — basic summary
+    await runner.run('sessionEnd', {
+      messageCount: 3,
+      messages: [
+        { role: 'user', content: 'test' },
+        { role: 'assistant', content: 'ok' },
+        { role: 'user', content: 'done' },
+      ],
+    })
+    expect(savedFacts[0][0].content).toContain('3 messages')
+
+    // Set LLM
+    runner.setLLM(async () => 'Rich LLM summary of session')
+
+    // With LLM — rich summary
+    await runner.run('sessionEnd', {
+      messageCount: 3,
+      messages: [
+        { role: 'user', content: 'test' },
+        { role: 'assistant', content: 'ok' },
+        { role: 'user', content: 'done' },
+      ],
+    })
+    expect(savedFacts[1][0].content).toBe('Rich LLM summary of session')
+  })
+})
+
+// ═════════════════════════════════════════════════════════════════════
+// Action: promote via 'full' — summary + individual observations
+// ═════════════════════════════════════════════════════════════════════
+
+describe('action: promote via full', () => {
+  it('parses LLM summary lines into individual facts + source observations', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'engram',
+          to: 'brain',
+          via: 'full',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [
+      createMockProvider('engram', {
+        recallResults: [
+          { content: 'Observation about hooks design', score: 0.9 },
+          { content: 'Bug found in mapper casing', score: 0.8 },
+        ],
+      }),
+      createMockProvider('brain', { savedFacts }),
+    ])
+
+    await runner.run('afterSessionEnd', {
+      messageCount: 10,
+      messages: [{ role: 'user', content: 'test' }],
+      sessionSummary:
+        'DECISION: Use LLM for summarization\nINFO: Brain stores long-term facts\nPROBLEM: Empty responses from CLI -> fixed with no-tools instruction',
+      topics: ['hooks'],
+    })
+
+    expect(savedFacts.length).toBe(1)
+    const facts = savedFacts[0]
+
+    // 3 parsed from summary + 2 from source recall (deduped across topic queries)
+    expect(facts.length).toBe(5)
+
+    // Parsed facts have mapped categories
+    expect(facts[0].category).toBe('decision')
+    expect(facts[0].content).toBe('Use LLM for summarization')
+    expect(facts[0].importance).toBe(7)
+    expect(facts[0].tags).toContain('decision')
+
+    expect(facts[1].category).toBe('observation')
+    expect(facts[1].content).toBe('Brain stores long-term facts')
+    expect(facts[1].tags).toContain('info')
+
+    expect(facts[2].category).toBe('learning')
+    expect(facts[2].content).toContain('Empty responses from CLI')
+    expect(facts[2].tags).toContain('problem')
+
+    // Source observations
+    expect(facts[3].content).toBe('Observation about hooks design')
+    expect(facts[4].content).toBe('Bug found in mapper casing')
+  })
+
+  it('deduplicates identical observations across topics', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'engram',
+          to: 'brain',
+          via: 'full',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [
+      createMockProvider('engram', {
+        recallResults: [{ content: 'Same observation returned for all queries', score: 0.9 }],
+      }),
+      createMockProvider('brain', { savedFacts }),
+    ])
+
+    await runner.run('afterSessionEnd', {
+      messageCount: 5,
+      messages: [{ role: 'user', content: 'test' }],
+      sessionSummary: 'Session summary',
+      topics: ['topic1', 'topic2', 'topic3'],
+    })
+
+    const facts = savedFacts[0]
+    // 1 unique observation (deduped across 3 topic queries)
+    // No parsed lines since sessionSummary is not in PREFIX: format
+    expect(facts.length).toBe(1)
+  })
+
+  it('caps promoted facts at MAX_PROMOTED (10)', async () => {
+    const savedFacts: Fact[][] = []
+    // Create provider that returns many results per query
+    let queryCount = 0
+    const manyResultsProvider: MemoryProvider = {
+      ...createMockProvider('engram'),
+      async recall() {
+        queryCount++
+        return Array.from({ length: 3 }, (_, i) => ({
+          content: `Observation ${queryCount}-${i}`,
+          score: 0.8,
+        }))
+      },
+    }
+
+    const hooks: HooksConfig = {
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'engram',
+          to: 'brain',
+          via: 'full',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [
+      manyResultsProvider,
+      createMockProvider('brain', { savedFacts }),
+    ])
+
+    await runner.run('afterSessionEnd', {
+      messageCount: 20,
+      messages: [{ role: 'user', content: 'test' }],
+      sessionSummary: 'Summary',
+      topics: ['t1', 't2', 't3', 't4', 't5'],
+    })
+
+    expect(savedFacts[0].length).toBeLessThanOrEqual(10)
+  })
+
+  it('parses summary lines even without topics', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'engram',
+          to: 'brain',
+          via: 'full',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [
+      createMockProvider('engram'),
+      createMockProvider('brain', { savedFacts }),
+    ])
+
+    await runner.run('afterSessionEnd', {
+      messageCount: 3,
+      messages: [{ role: 'user', content: 'test' }],
+      sessionSummary: 'DECISION: Deploy to production\nINFO: Version 2.0 released',
+    })
+
+    expect(savedFacts.length).toBe(1)
+    expect(savedFacts[0].length).toBe(2)
+    expect(savedFacts[0][0].category).toBe('decision')
+    expect(savedFacts[0][1].category).toBe('observation')
+  })
+
+  it('saves nothing when summary has no parseable lines and no topics', async () => {
+    const savedFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'engram',
+          to: 'brain',
+          via: 'full',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [
+      createMockProvider('engram'),
+      createMockProvider('brain', { savedFacts }),
+    ])
+
+    await runner.run('afterSessionEnd', {
+      messageCount: 3,
+      messages: [{ role: 'user', content: 'test' }],
+      sessionSummary: 'Just a plain text summary without prefixes',
+    })
+
+    // No parseable lines, no topics to search
+    expect(savedFacts.length).toBe(0)
+  })
+
+  it('continues when source recall fails for a topic', async () => {
+    const savedFacts: Fact[][] = []
+    let callCount = 0
+    const flakeyProvider: MemoryProvider = {
+      ...createMockProvider('engram'),
+      async recall() {
+        callCount++
+        if (callCount === 1) throw new Error('Connection reset')
+        return [{ content: 'Valid observation', score: 0.8 }]
+      },
+    }
+
+    const hooks: HooksConfig = {
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'engram',
+          to: 'brain',
+          via: 'full',
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [
+      flakeyProvider,
+      createMockProvider('brain', { savedFacts }),
+    ])
+
+    await runner.run('afterSessionEnd', {
+      messageCount: 5,
+      messages: [{ role: 'user', content: 'test' }],
+      sessionSummary: 'Summary',
+      topics: ['fails', 'works'],
+    })
+
+    // 1 summary + observations from successful topic query
+    expect(savedFacts[0].length).toBeGreaterThanOrEqual(1)
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Integration: multi-hook chains
+// ═══════════════════════════════════════════════════════════════════
+
+describe('multi-hook chains', () => {
+  it('summarize → promote chain at session end', async () => {
+    const brainFacts: Fact[][] = []
+    const hooks: HooksConfig = {
+      sessionEnd: [{ action: 'summarize', provider: 'engram' }],
+      afterSessionEnd: [
+        {
+          action: 'promote',
+          from: 'engram',
+          to: 'brain',
+          via: 'extraction',
+          when: { providersAvailable: ['engram', 'brain'], minMessages: 3 },
+        },
+      ],
+    }
+    const runner = new HookRunner(hooks, [
+      createMockProvider('engram'),
+      createMockProvider('brain', { savedFacts: brainFacts }),
+    ])
+
+    // sessionEnd: summarize creates summary in context
+    const ctx: HookContext = {
+      messageCount: 5,
+      messages: [{ role: 'user', content: 'test' }],
+    }
+    await runner.run('sessionEnd', ctx)
+    expect(ctx.sessionSummary).toBeDefined()
+
+    // afterSessionEnd: promote uses the summary
+    await runner.run('afterSessionEnd', {
+      ...ctx,
+      messages: [{ role: 'user', content: 'test' }],
+    })
+    expect(brainFacts.length).toBe(1)
+    expect(brainFacts[0][0].content).toContain('5 messages')
+  })
+
+  it('context → boost chain (sessionStart + afterRecall)', async () => {
+    const hooks: HooksConfig = {
+      sessionStart: [{ action: 'context', provider: 'engram' }],
+      afterRecall: [{ action: 'boost', provider: 'engram', factor: 1.3, recencyWindow: '1h' }],
+    }
+    const runner = new HookRunner(hooks, [
+      createMockProvider('engram', {
+        recallResults: [{ content: 'Warm context', score: 0.7, storedAt: new Date() }],
+      }),
+    ])
+
+    // sessionStart: context pre-loads
+    const startCtx: HookContext = { messageCount: 0 }
+    await runner.run('sessionStart', startCtx)
+    expect(startCtx.results).toHaveLength(1)
+
+    // afterRecall: boost adjusts scores
+    const recallCtx: HookContext = {
+      messageCount: 0,
+      results: [
+        { content: 'From recall', score: 0.8, source: 'engram', storedAt: new Date() },
+        { content: 'Old recall', score: 0.5, source: 'brain' },
+      ],
+    }
+    await runner.run('afterRecall', recallCtx)
+
+    // Only engram result with recent storedAt should be boosted
+    const engramResult = recallCtx.results!.find((r) => r.source === 'engram')!
+    expect(engramResult.score).toBeGreaterThan(0.8)
+  })
+})
+
+// ════════════════════════════════════════════════════════════
+// New actions: episode, journal, experience, reconcile, episodeClose
+// ════════════════════════════════════════════════════════════
+
+describe('action: episode', () => {
+  it('calls getOrCreateEpisode and sets context.episodeId', async () => {
+    const brainProvider = createMockProvider('brain')
+    ;(brainProvider as any).getOrCreateEpisode = async (date: string, channel?: string) => ({
+      id: 'ep-123',
+      sessionDate: date,
+      channel,
+    })
+
+    const hooks: HooksConfig = {
+      sessionStart: [{ action: 'episode', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [brainProvider])
+
+    const context: HookContext = {
+      messageCount: 0,
+      channel: 'research',
+      sessionDate: '2026-03-01',
+    }
+    const result = await runner.run('sessionStart', context)
+
+    expect(result.episodeId).toBe('ep-123')
+    expect(result.sessionDate).toBe('2026-03-01')
+    expect(result.createdFactIds).toEqual([])
+  })
+
+  it('skips when provider has no getOrCreateEpisode', async () => {
+    const provider = createMockProvider('basic')
+    const hooks: HooksConfig = {
+      sessionStart: [{ action: 'episode', provider: 'basic' }],
+    }
+    const runner = new HookRunner(hooks, [provider])
+
+    const context: HookContext = { messageCount: 0 }
+    const result = await runner.run('sessionStart', context)
+
+    expect(result.episodeId).toBeUndefined()
+  })
+})
+
+describe('action: journal', () => {
+  it('generates journal entry via LLM and saves to provider', async () => {
+    const savedFacts: any[] = []
+    const provider = createMockProvider('brain')
+    provider.save = async (facts) => {
+      savedFacts.push(...facts)
+      return ['fact-j-1']
+    }
+
+    const hooks: HooksConfig = {
+      sessionEnd: [{ action: 'journal', provider: 'brain' }],
+    }
+    const llm = async (prompt: string) => 'Hoy aprendí algo importante sobre la arquitectura.'
+    const runner = new HookRunner(hooks, [provider], { llm })
+
+    const context: HookContext = {
+      messageCount: 5,
+      messages: [
+        { role: 'user', content: 'vamos a diseñar la arquitectura' },
+        { role: 'assistant', content: 'vale, empecemos por el core' },
+      ],
+      episodeId: 'ep-123',
+      sessionDate: '2026-03-01',
+    }
+    const result = await runner.run('sessionEnd', context)
+
+    expect(savedFacts).toHaveLength(1)
+    expect(savedFacts[0].domain).toBe('self')
+    expect(savedFacts[0].category).toBe('journal')
+    expect(savedFacts[0].episodeId).toBe('ep-123')
+    expect(savedFacts[0].sessionDate).toBe('2026-03-01')
+    expect(result.createdFactIds).toContain('fact-j-1')
+  })
+
+  it('skips when LLM is not available', async () => {
+    const provider = createMockProvider('brain')
+    const hooks: HooksConfig = {
+      sessionEnd: [{ action: 'journal', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [provider])
+
+    const context: HookContext = {
+      messageCount: 5,
+      messages: [
+        { role: 'user', content: 'hello' },
+        { role: 'assistant', content: 'hi' },
+      ],
+    }
+    const result = await runner.run('sessionEnd', context)
+    expect(result.createdFactIds).toBeUndefined()
+  })
+})
+
+describe('action: experience', () => {
+  it('generates experience entry via LLM and saves to provider', async () => {
+    const savedFacts: any[] = []
+    const provider = createMockProvider('brain')
+    provider.save = async (facts) => {
+      savedFacts.push(...facts)
+      return ['fact-e-1']
+    }
+
+    const hooks: HooksConfig = {
+      sessionEnd: [{ action: 'experience', provider: 'brain' }],
+    }
+    const llm = async (prompt: string) => 'Sesión cálida y enfocada.'
+    const runner = new HookRunner(hooks, [provider], { llm })
+
+    const context: HookContext = {
+      messageCount: 5,
+      messages: [
+        { role: 'user', content: 'vamos a diseñar la arquitectura' },
+        { role: 'assistant', content: 'vale, empecemos por el core' },
+      ],
+      episodeId: 'ep-123',
+      sessionDate: '2026-03-01',
+    }
+    const result = await runner.run('sessionEnd', context)
+
+    expect(savedFacts).toHaveLength(1)
+    expect(savedFacts[0].domain).toBe('self')
+    expect(savedFacts[0].category).toBe('experience')
+    expect(savedFacts[0].episodeId).toBe('ep-123')
+    expect(result.createdFactIds).toContain('fact-e-1')
+  })
+})
+
+describe('action: reconcile', () => {
+  it('parses summary lines and deduplicates against existing', async () => {
+    const savedFacts: any[] = []
+    const provider = createMockProvider('brain')
+    provider.save = async (facts) => {
+      savedFacts.push(...facts)
+      return facts.map((_: any, i: number) => `fact-r-${i}`)
+    }
+    // Simulate existing facts returned by recall
+    provider.recall = async () => [{ content: 'Mars decided to use Postgres', score: 0.9 }]
+
+    const hooks: HooksConfig = {
+      afterSessionEnd: [{ action: 'reconcile', to: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [provider])
+
+    const context: HookContext = {
+      messageCount: 10,
+      sessionSummary: [
+        'DECISION: Mars decided to use Postgres',
+        'DECISION: Architecture will have 5 layers',
+        'INFO: Qwen 2.5 14B selected for local model',
+        'TECHNICAL: BrainClient needs episode methods',
+      ].join('\n'),
+      episodeId: 'ep-456',
+      sessionDate: '2026-03-01',
+      topics: ['architecture', 'brain'],
+    }
+    const result = await runner.run('afterSessionEnd', context)
+
+    // First decision should be deduped (existing contains it)
+    // Remaining 3 should be saved
+    expect(savedFacts).toHaveLength(3)
+    expect(savedFacts.every((f: any) => f.episodeId === 'ep-456')).toBe(true)
+  })
+
+  it('saves nothing when summary has no parseable lines', async () => {
+    const provider = createMockProvider('brain')
+    let saveCalled = false
+    provider.save = async () => {
+      saveCalled = true
+      return []
+    }
+
+    const hooks: HooksConfig = {
+      afterSessionEnd: [{ action: 'reconcile', to: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [provider])
+
+    const context: HookContext = {
+      messageCount: 5,
+      sessionSummary: 'Just some text without prefixes',
+    }
+    await runner.run('afterSessionEnd', context)
+
+    expect(saveCalled).toBe(false)
+  })
+})
+
+describe('action: episodeClose', () => {
+  it('calls updateEpisode with factIds and summary', async () => {
+    let updateCall: any = null
+    const provider = createMockProvider('brain')
+    ;(provider as any).updateEpisode = async (id: string, data: any) => {
+      updateCall = { id, data }
+      return { id, ...data }
+    }
+
+    const hooks: HooksConfig = {
+      afterSessionEnd: [{ action: 'episodeClose', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [provider])
+
+    const context: HookContext = {
+      messageCount: 15,
+      episodeId: 'ep-789',
+      createdFactIds: ['fact-1', 'fact-2', 'fact-3'],
+      sessionSummary: 'Great session about architecture',
+      topics: ['architecture', 'design'],
+    }
+    await runner.run('afterSessionEnd', context)
+
+    expect(updateCall).not.toBeNull()
+    expect(updateCall.id).toBe('ep-789')
+    expect(updateCall.data.factIds).toEqual(['fact-1', 'fact-2', 'fact-3'])
+    expect(updateCall.data.topics).toEqual(['architecture', 'design'])
+    expect(updateCall.data.messageCount).toBe(15)
+  })
+
+  it('skips when no episodeId in context', async () => {
+    let updateCalled = false
+    const provider = createMockProvider('brain')
+    ;(provider as any).updateEpisode = async () => {
+      updateCalled = true
+    }
+
+    const hooks: HooksConfig = {
+      afterSessionEnd: [{ action: 'episodeClose', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [provider])
+
+    const context: HookContext = { messageCount: 5 }
+    await runner.run('afterSessionEnd', context)
+
+    expect(updateCalled).toBe(false)
+  })
+})
+
+describe('full diary chain', () => {
+  it('summarize → journal → experience → reconcile → episodeClose', async () => {
+    const savedFacts: any[] = []
+    let factCounter = 0
+    let episodeUpdate: any = null
+
+    const brain = createMockProvider('brain')
+    brain.save = async (facts) => {
+      savedFacts.push(...facts)
+      return facts.map(() => `fact-${++factCounter}`)
+    }
+    brain.recall = async () => []
+    ;(brain as any).updateEpisode = async (id: string, data: any) => {
+      episodeUpdate = { id, data }
+    }
+
+    const hooks: HooksConfig = {
+      sessionEnd: [
+        { action: 'summarize', provider: 'brain' },
+        { action: 'journal', provider: 'brain' },
+        { action: 'experience', provider: 'brain' },
+      ],
+      afterSessionEnd: [
+        { action: 'reconcile', to: 'brain' },
+        { action: 'episodeClose', provider: 'brain' },
+      ],
+    }
+
+    const llm = async (prompt: string) => {
+      if (prompt.includes('factual session logger')) {
+        return 'DECISION: Use 5 cognitive layers\nINFO: Qwen 2.5 14B selected'
+      }
+      if (prompt.includes('personal journal')) {
+        return 'Me sorprendió la profundidad de la conversación.'
+      }
+      if (prompt.includes('emotional tone')) {
+        return 'Sesión intensa y reveladora.'
+      }
+      return ''
+    }
+
+    const runner = new HookRunner(hooks, [brain], { llm })
+
+    // Run sessionEnd
+    const endContext: HookContext = {
+      messageCount: 20,
+      messages: [
+        { role: 'user', content: 'diseñemos las capas cognitivas' },
+        { role: 'assistant', content: 'propongo 5 capas...' },
+      ],
+      episodeId: 'ep-full',
+      sessionDate: '2026-03-01',
+      createdFactIds: [],
+    }
+    const afterEnd = await runner.run('sessionEnd', endContext)
+
+    // Should have: 1 summary + 1 journal + 1 experience = 3 facts
+    expect(savedFacts).toHaveLength(3)
+    expect(savedFacts[0].category).toBe('session-summary')
+    expect(savedFacts[1].category).toBe('journal')
+    expect(savedFacts[2].category).toBe('experience')
+
+    // Run afterSessionEnd with the carried context
+    const afterContext: HookContext = {
+      ...afterEnd,
+      createdFactIds: afterEnd.createdFactIds ?? [],
+    }
+    const finalResult = await runner.run('afterSessionEnd', afterContext)
+
+    // Reconcile should have saved 2 more (DECISION + INFO from summary)
+    expect(savedFacts.length).toBeGreaterThanOrEqual(4)
+
+    // EpisodeClose should have been called
+    expect(episodeUpdate).not.toBeNull()
+    expect(episodeUpdate.id).toBe('ep-full')
+    expect(episodeUpdate.data.factIds.length).toBeGreaterThan(0)
+  })
+})
+
+describe('action: diaryRecall', () => {
+  it('loads self facts and summaries by date, prepends to context.results', async () => {
+    const provider = createMockProvider('brain')
+    ;(provider as any).queryFacts = async (filters: any) => {
+      if (filters.domain === 'self') {
+        return [
+          {
+            id: 'j1',
+            content: 'Me sorprendió la profundidad',
+            domain: 'self',
+            category: 'journal',
+            episodeId: 'ep1',
+            createdAt: '2026-03-01T10:00:00Z',
+            importance: 7,
+          },
+          {
+            id: 'e1',
+            content: 'Sesión cálida',
+            domain: 'self',
+            category: 'experience',
+            episodeId: 'ep1',
+            createdAt: '2026-03-01T10:00:00Z',
+            importance: 6,
+          },
+        ]
+      }
+      if (filters.category === 'session-summary') {
+        return [
+          {
+            id: 's1',
+            content: 'Implemented diary spec',
+            domain: 'session',
+            category: 'session-summary',
+            episodeId: 'ep1',
+            createdAt: '2026-03-01T10:00:00Z',
+            importance: 7,
+          },
+        ]
+      }
+      return []
+    }
+
+    const hooks: HooksConfig = {
+      sessionStart: [{ action: 'diaryRecall', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [provider])
+
+    const context: HookContext = {
+      messageCount: 0,
+      sessionDate: '2026-03-01',
+      results: [{ content: 'existing result', score: 0.5 }],
+    }
+    const result = await runner.run('sessionStart', context)
+
+    // Diary results should be prepended (before existing)
+    expect(result.results!.length).toBe(4) // 2 self + 1 summary + 1 existing
+    expect(result.results![0].source).toBe('brain:diary')
+    expect(result.results![0].score).toBe(1.0) // Max score
+    expect(result.results![2].source).toBe('brain:diary')
+    expect(result.results![2].score).toBe(0.9)
+    expect(result.results![3].content).toBe('existing result') // Original at end
+  })
+
+  it('falls back to yesterday when today has no entries', async () => {
+    const queriedDates: string[] = []
+    const provider = createMockProvider('brain')
+    ;(provider as any).queryFacts = async (filters: any) => {
+      queriedDates.push(filters.sessionDate)
+      if (filters.sessionDate === '2026-03-01') return []
+      if (filters.sessionDate === '2026-02-28' && filters.domain === 'self') {
+        return [
+          {
+            id: 'j-yesterday',
+            content: 'Yesterday journal',
+            domain: 'self',
+            category: 'journal',
+            createdAt: '2026-02-28T20:00:00Z',
+            importance: 7,
+          },
+        ]
+      }
+      return []
+    }
+
+    const hooks: HooksConfig = {
+      sessionStart: [{ action: 'diaryRecall', provider: 'brain' }],
+    }
+    const runner = new HookRunner(hooks, [provider])
+
+    const context: HookContext = { messageCount: 0, sessionDate: '2026-03-01' }
+    const result = await runner.run('sessionStart', context)
+
+    // Should have tried today first, then yesterday
+    expect(queriedDates).toContain('2026-03-01')
+    expect(queriedDates).toContain('2026-02-28')
+    expect(result.results!.length).toBe(1)
+    expect(result.results![0].content).toContain('Yesterday journal')
+  })
+})