@cleocode/core 2026.4.7 → 2026.4.11

package/dist/hooks/handlers/context-hooks.js

@@ -0,0 +1,111 @@
+/**
+ * Context Compaction Hook Handlers
+ *
+ * Captures PreCompact and PostCompact events to BRAIN so that agents
+ * can later observe when context compactions occurred and what state
+ * preceded them. This is especially useful for long sessions where
+ * context is compacted multiple times.
+ *
+ * PreCompact saves a session context snapshot before compaction begins.
+ * PostCompact records that compaction occurred and the resulting token counts.
+ *
+ * Gated behind brain.autoCapture config. Never throws — all errors are
+ * swallowed so brain capture never blocks context compaction.
+ *
+ * Auto-registers on module load.
+ *
+ * @task T166
+ * @epic T134
+ */
+import { hooks } from '../registry.js';
+import { isAutoCaptureEnabled, isMissingBrainSchemaError } from './handler-helpers.js';
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+/**
+ * Handle PreCompact — snapshot current session memory context to BRAIN.
+ *
+ * Fires immediately before context compaction begins. Records the token
+ * count and compaction reason so the brain retains context about what
+ * was in scope before compaction.
+ *
+ * Gated behind brain.autoCapture config. Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - PreCompact event payload.
+ *
+ * @task T166
+ * @epic T134
+ */
+export async function handlePreCompact(projectRoot, payload) {
+    if (!(await isAutoCaptureEnabled(projectRoot)))
+        return;
+    const { observeBrain } = await import('../../memory/brain-retrieval.js');
+    const tokensPart = payload.tokensBefore != null ? ` (~${payload.tokensBefore.toLocaleString()} tokens)` : '';
+    const reasonPart = payload.reason ? ` Reason: ${payload.reason}` : '';
+    try {
+        await observeBrain(projectRoot, {
+            text: `Context compaction about to begin${tokensPart}.${reasonPart}`,
+            title: 'Pre-compaction context snapshot',
+            type: 'discovery',
+            sourceSessionId: payload.sessionId,
+            sourceType: 'agent',
+        });
+    }
+    catch (err) {
+        if (!isMissingBrainSchemaError(err))
+            throw err;
+    }
+}
+/**
+ * Handle PostCompact — record compaction completion to BRAIN.
+ *
+ * Fires immediately after context compaction completes. Records the
+ * before/after token counts so agents can correlate observations made
+ * before compaction with those made after.
+ *
+ * Gated behind brain.autoCapture config. Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - PostCompact event payload.
+ *
+ * @task T166
+ * @epic T134
+ */
+export async function handlePostCompact(projectRoot, payload) {
+    if (!(await isAutoCaptureEnabled(projectRoot)))
+        return;
+    const { observeBrain } = await import('../../memory/brain-retrieval.js');
+    const statusPart = payload.success ? 'succeeded' : 'failed';
+    const beforePart = payload.tokensBefore != null ? ` before=${payload.tokensBefore.toLocaleString()}` : '';
+    const afterPart = payload.tokensAfter != null ? ` after=${payload.tokensAfter.toLocaleString()}` : '';
+    try {
+        await observeBrain(projectRoot, {
+            text: `Context compaction ${statusPart}${beforePart}${afterPart}`,
+            title: 'Post-compaction record',
+            type: 'change',
+            sourceSessionId: payload.sessionId,
+            sourceType: 'agent',
+        });
+    }
+    catch (err) {
+        if (!isMissingBrainSchemaError(err))
+            throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// Auto-registration
+// ---------------------------------------------------------------------------
+hooks.register({
+    id: 'brain-pre-compact',
+    event: 'PreCompact',
+    handler: handlePreCompact,
+    priority: 100,
+});
+hooks.register({
+    id: 'brain-post-compact',
+    event: 'PostCompact',
+    handler: handlePostCompact,
+    priority: 100,
+});
+//# sourceMappingURL=context-hooks.js.map

package/dist/hooks/handlers/context-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-hooks.js","sourceRoot":"","sources":["../../../src/hooks/handlers/context-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEvF,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,WAAmB,EACnB,OAA0B;IAE1B,IAAI,CAAC,CAAC,MAAM,oBAAoB,CAAC,WAAW,CAAC,CAAC;QAAE,OAAO;IAEvD,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,iCAAiC,CAAC,CAAC;IAEzE,MAAM,UAAU,GACd,OAAO,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,YAAY,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5F,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAEtE,IAAI,CAAC;QACH,MAAM,YAAY,CAAC,WAAW,EAAE;YAC9B,IAAI,EAAE,oCAAoC,UAAU,IAAI,UAAU,EAAE;YACpE,KAAK,EAAE,iCAAiC;YACxC,IAAI,EAAE,WAAW;YACjB,eAAe,EAAE,OAAO,CAAC,SAAS;YAClC,UAAU,EAAE,OAAO;SACpB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC;YAAE,MAAM,GAAG,CAAC;IACjD,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,WAAmB,EACnB,OAA2B;IAE3B,IAAI,CAAC,CAAC,MAAM,oBAAoB,CAAC,WAAW,CAAC,CAAC;QAAE,OAAO;IAEvD,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,iCAAiC,CAAC,CAAC;IAEzE,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC5D,MAAM,UAAU,GACd,OAAO,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC,CAAC,WAAW,OAAO,CAAC,YAAY,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACzF,MAAM,SAAS,GACb,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC,CAAC,UAAU,OAAO,CAAC,WAAW,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAEtF,IAAI,CAAC;QACH,MAAM,YAAY,CAAC,WAAW,EAAE;YAC9B,IAAI,EAAE,sBAAsB,UAAU,GAAG,UAAU,GAAG,SAAS,EAAE;YACjE,KAAK,EAAE,wBAAwB;YAC/B,IAAI,EAAE,QAAQ;YACd,eAAe,EAAE,OAAO,CAAC,SAAS;YAClC,UAAU,EAAE,OAAO;SACpB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC;YAAE,MAAM,GAAG,CAAC;IACjD,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,KAAK,CAAC,QAAQ,CAAC;IACb,EAAE,EAAE,mBAAmB;IACvB,KAAK,EAAE,YAAY;IACnB,OAAO,EAAE,gBAAgB;IACzB,QAAQ,EAAE,GAAG;CACd,CAAC,CAAC;AAEH,KAAK,CAAC,QAAQ,CAAC;IACb,EAAE,EAAE,oBAAoB;IACxB,KAAK,EAAE,aAAa;IACpB,OAAO,EAAE,iBAAiB;IAC1B,QAAQ,EAAE,GAAG;CACd,CAAC,CAAC"}

package/dist/hooks/handlers/error-hooks.js

@@ -0,0 +1,52 @@
+/**
+ * Error Hook Handlers - Wave 2 of T5237
+ *
+ * Captures operation errors to BRAIN via memory.observe.
+ * Includes infinite-loop guard to prevent onError triggering onError.
+ * Auto-registers on module load.
+ */
+import { hooks } from '../registry.js';
+/**
+ * Handle PostToolUseFailure — capture operation errors to BRAIN.
+ *
+ * Includes an infinite-loop guard: if the payload carries a `_fromHook`
+ * metadata marker the handler skips immediately to prevent the cycle
+ * `PostToolUseFailure → observeBrain → PostToolUseFailure`. All
+ * `observeBrain` errors are also silently suppressed for the same reason.
+ *
+ * Never throws. All brain-write errors are swallowed so error hooks
+ * never block the original error path.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - PostToolUseFailure event payload.
+ *
+ * @task T166
+ * @epic T134
+ */
+export async function handleError(projectRoot, payload) {
+    // Infinite-loop guard: skip if this error originated from a hook
+    if (payload.metadata?.['_fromHook'])
+        return;
+    const { observeBrain } = await import('../../memory/brain-retrieval.js');
+    const domainOp = payload.domain && payload.operation ? `${payload.domain}.${payload.operation}` : 'unknown';
+    try {
+        await observeBrain(projectRoot, {
+            text: `Error in ${domainOp}: ${payload.message}\nCode: ${payload.errorCode}${payload.gateway ? `\nGateway: ${payload.gateway}` : ''}`,
+            title: `Error: ${domainOp}`,
+            type: 'discovery',
+            sourceType: 'agent',
+        });
+    }
+    catch (_err) {
+        // Silently suppress all observeBrain errors in hook context
+        // to prevent re-entrant hook firing
+    }
+}
+// Register handler on module load
+hooks.register({
+    id: 'brain-error',
+    event: 'PostToolUseFailure',
+    handler: handleError,
+    priority: 100,
+});
+//# sourceMappingURL=error-hooks.js.map

package/dist/hooks/handlers/error-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-hooks.js","sourceRoot":"","sources":["../../../src/hooks/handlers/error-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,WAAmB,EACnB,OAAkC;IAElC,iEAAiE;IACjE,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,WAAW,CAAC;QAAE,OAAO;IAE5C,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,iCAAiC,CAAC,CAAC;IAEzE,MAAM,QAAQ,GACZ,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAE7F,IAAI,CAAC;QACH,MAAM,YAAY,CAAC,WAAW,EAAE;YAC9B,IAAI,EAAE,YAAY,QAAQ,KAAK,OAAO,CAAC,OAAO,WAAW,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE;YACrI,KAAK,EAAE,UAAU,QAAQ,EAAE;YAC3B,IAAI,EAAE,WAAW;YACjB,UAAU,EAAE,OAAO;SACpB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,IAAI,EAAE,CAAC;QACd,4DAA4D;QAC5D,oCAAoC;IACtC,CAAC;AACH,CAAC;AAED,kCAAkC;AAClC,KAAK,CAAC,QAAQ,CAAC;IACb,EAAE,EAAE,aAAa;IACjB,KAAK,EAAE,oBAAoB;IAC3B,OAAO,EAAE,WAAW;IACpB,QAAQ,EAAE,GAAG;CACd,CAAC,CAAC"}

package/dist/hooks/handlers/file-hooks.js

@@ -0,0 +1,104 @@
+/**
+ * File Change Hook Handlers - Wave 2 of T5237
+ *
+ * Captures file change events to BRAIN via memory.observe.
+ * Includes 5-second dedup and path-based filtering to avoid noisy writes.
+ * Auto-registers on module load.
+ *
+ * Disabled by default. Enable via:
+ *   - Config: brain.captureFiles = true  (checked first)
+ *   - Env:    CLEO_BRAIN_CAPTURE_FILES=true  (overrides config)
+ */
+import { isAbsolute, relative } from 'node:path';
+import { hooks } from '../registry.js';
+import { isMissingBrainSchemaError } from './handler-helpers.js';
+/** 5-second dedup map: filePath -> last dispatch timestamp */
+const recentWrites = new Map();
+const DEDUP_INTERVAL_MS = 5_000;
+/** Path patterns to exclude from brain observations (internal/noisy files). */
+const SKIP_PATTERNS = [
+    /\.cleo\//, // All .cleo internal files (sessions.json, config.json, tasks.db, etc.)
+    /\.cleo\\/, // Windows path variant
+    /\/\.temp\//, // Temp directories
+    /cleo-test-/, // Vitest test temp dirs
+    /cleo-edge-/, // Edge-case test temp dirs
+    /node_modules\//, // Dependencies
+    /\.git\//, // Git internals
+    /dist\//, // Build output
+];
+/** Check whether a relative path should be skipped. */
+function shouldSkipPath(relativePath) {
+    return SKIP_PATTERNS.some((pattern) => pattern.test(relativePath));
+}
+/**
+ * Check whether file-change capture is enabled.
+ *
+ * Resolution order (first truthy wins):
+ *   1. CLEO_BRAIN_CAPTURE_FILES env var (explicit override)
+ *   2. brain.captureFiles project config value
+ *
+ * Defaults to false when neither is set.
+ */
+async function isFileCaptureEnabled(projectRoot) {
+    const envOverride = process.env['CLEO_BRAIN_CAPTURE_FILES'];
+    if (envOverride !== undefined) {
+        return envOverride === 'true';
+    }
+    try {
+        const { loadConfig } = await import('../../config.js');
+        const config = await loadConfig(projectRoot);
+        return config.brain?.captureFiles ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Handle Notification (file-change variant) - capture file changes to BRAIN
+ *
+ * Gated behind brain.captureFiles config or CLEO_BRAIN_CAPTURE_FILES env var.
+ * Env var takes precedence over config for backward compatibility.
+ * Deduplicates rapid writes to the same file within a 5-second window.
+ * Filters out .cleo/ internal files and test temp directories.
+ * Converts absolute paths to project-relative paths.
+ */
+export async function handleFileChange(projectRoot, payload) {
+    // Only handle file-change notifications
+    if (!payload.filePath || !payload.changeType)
+        return;
+    // Opt-in gate: disabled by default to prevent observation noise
+    if (!(await isFileCaptureEnabled(projectRoot)))
+        return;
+    // 5-second dedup
+    const now = Date.now();
+    const lastWrite = recentWrites.get(payload.filePath);
+    if (lastWrite && now - lastWrite < DEDUP_INTERVAL_MS)
+        return;
+    recentWrites.set(payload.filePath, now);
+    // Convert absolute paths to relative, normalize to forward slashes
+    const relativePath = (isAbsolute(payload.filePath) ? relative(projectRoot, payload.filePath) : payload.filePath).replaceAll('\\', '/');
+    // Skip internal/noisy files
+    if (shouldSkipPath(relativePath))
+        return;
+    const { observeBrain } = await import('../../memory/brain-retrieval.js');
+    try {
+        await observeBrain(projectRoot, {
+            text: `File ${payload.changeType}: ${relativePath}${payload.sizeBytes != null ? ` (${payload.sizeBytes} bytes)` : ''}`,
+            title: `File changed: ${relativePath}`,
+            type: 'change',
+            sourceType: 'agent',
+        });
+    }
+    catch (err) {
+        if (!isMissingBrainSchemaError(err))
+            throw err;
+    }
+}
+// Register handler on module load
+hooks.register({
+    id: 'brain-file-change',
+    event: 'Notification',
+    handler: handleFileChange,
+    priority: 100,
+});
+//# sourceMappingURL=file-hooks.js.map

package/dist/hooks/handlers/file-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-hooks.js","sourceRoot":"","sources":["../../../src/hooks/handlers/file-hooks.ts"],"names":[],"mappings":"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"}

package/dist/hooks/handlers/handler-helpers.js

@@ -0,0 +1,61 @@
+/**
+ * Shared helpers for hook handler modules.
+ *
+ * Centralises the two patterns repeated across all brain-capture handlers:
+ *
+ * 1. `isMissingBrainSchemaError` — detects the "no such table: brain_*" error
+ *    thrown when brain.db has not been migrated yet, so handlers can swallow
+ *    it silently instead of crashing agent workflows.
+ *
+ * 2. `isAutoCaptureEnabled` — reads `brain.autoCapture` from the cascaded
+ *    project config and returns false when the config is unreadable.
+ *
+ * Import these instead of redefining them in each handler file.
+ *
+ * @task T166
+ * @epic T134
+ */
+// ---------------------------------------------------------------------------
+// Brain schema error guard
+// ---------------------------------------------------------------------------
+/**
+ * Return true when the error is the "no such table: brain_*" SQLite error
+ * thrown before brain.db has been migrated.
+ *
+ * Hook handlers use this to swallow migration-lag errors without hiding
+ * genuine failures: if the error is NOT a missing-schema error it is
+ * re-thrown so it propagates normally.
+ *
+ * @param err - The caught error value (may be any type).
+ */
+export function isMissingBrainSchemaError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const message = String(err.message || '').toLowerCase();
+    return message.includes('no such table') && message.includes('brain_');
+}
+// ---------------------------------------------------------------------------
+// Auto-capture config gate
+// ---------------------------------------------------------------------------
+/**
+ * Return true when `brain.autoCapture` is enabled for the given project.
+ *
+ * Resolution order (first truthy wins):
+ *   1. `brain.autoCapture` project config value (via `loadConfig` cascade)
+ *
+ * Defaults to `false` when the config is unreadable or the key is absent,
+ * so handlers are safely disabled in environments where brain.db is not set up.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ */
+export async function isAutoCaptureEnabled(projectRoot) {
+    try {
+        const { loadConfig } = await import('../../config.js');
+        const config = await loadConfig(projectRoot);
+        return config.brain?.autoCapture ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=handler-helpers.js.map

package/dist/hooks/handlers/handler-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-helpers.js","sourceRoot":"","sources":["../../../src/hooks/handlers/handler-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAY;IACpD,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACxD,OAAO,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACzE,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,WAAmB;IAC5D,IAAI,CAAC;QACH,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;QACvD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,WAAW,CAAC,CAAC;QAC7C,OAAO,MAAM,CAAC,KAAK,EAAE,WAAW,IAAI,KAAK,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/hooks/handlers/index.js

@@ -0,0 +1,28 @@
+/**
+ * Hook Handlers Index - Phase 2D of T5237
+ *
+ * Barrel export for all hook handlers. Importing this module will
+ * auto-register all handlers with the hook registry.
+ *
+ * @task T166
+ * @epic T134
+ */
+// Import handlers to trigger auto-registration on module load
+import './session-hooks.js';
+import './task-hooks.js';
+import './error-hooks.js';
+import './file-hooks.js';
+import './notification-hooks.js';
+import './work-capture-hooks.js';
+import './agent-hooks.js';
+import './context-hooks.js';
+export { handleSubagentStart, handleSubagentStop } from './agent-hooks.js';
+export { handlePostCompact, handlePreCompact } from './context-hooks.js';
+export { handleError } from './error-hooks.js';
+export { handleFileChange } from './file-hooks.js';
+export { handleSystemNotification } from './notification-hooks.js';
+// Re-export handler functions for explicit use
+export { handleSessionEnd, handleSessionStart } from './session-hooks.js';
+export { handleToolComplete, handleToolStart } from './task-hooks.js';
+export { handleWorkPromptSubmit, handleWorkResponseComplete } from './work-capture-hooks.js';
+//# sourceMappingURL=index.js.map

package/dist/hooks/handlers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hooks/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,8DAA8D;AAC9D,OAAO,oBAAoB,CAAC;AAC5B,OAAO,iBAAiB,CAAC;AACzB,OAAO,kBAAkB,CAAC;AAC1B,OAAO,iBAAiB,CAAC;AACzB,OAAO,yBAAyB,CAAC;AACjC,OAAO,yBAAyB,CAAC;AACjC,OAAO,kBAAkB,CAAC;AAC1B,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,+CAA+C;AAC/C,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/hooks/handlers/memory-bridge-refresh.js

@@ -0,0 +1,42 @@
+/**
+ * Shared memory bridge refresh helper for hook handlers.
+ *
+ * Provides a config-gated, debounced wrapper around refreshMemoryBridge().
+ * Prevents rapid regeneration of .cleo/memory-bridge.md when multiple
+ * lifecycle events fire in quick succession (e.g. session end + task complete).
+ *
+ * Debounce: max one refresh per 30 seconds across all callers in the process.
+ *
+ * @task T138
+ * @epic T134
+ */
+/** Debounce window in milliseconds. */
+const DEBOUNCE_MS = 30_000;
+/** Timestamp of the last successful refresh call (module-level singleton). */
+let lastRefreshTime = 0;
+/**
+ * Refresh the memory bridge if autoRefresh is enabled and the debounce window
+ * has elapsed. Reads config via loadConfig() (cascaded). Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ */
+export async function maybeRefreshMemoryBridge(projectRoot) {
+    try {
+        const { loadConfig } = await import('../../config.js');
+        const config = await loadConfig(projectRoot);
+        if (!config.brain?.memoryBridge?.autoRefresh) {
+            return;
+        }
+        const now = Date.now();
+        if (now - lastRefreshTime < DEBOUNCE_MS) {
+            return;
+        }
+        lastRefreshTime = now;
+        const { refreshMemoryBridge } = await import('../../memory/memory-bridge.js');
+        await refreshMemoryBridge(projectRoot);
+    }
+    catch {
+        // Best-effort: never block lifecycle events
+    }
+}
+//# sourceMappingURL=memory-bridge-refresh.js.map

package/dist/hooks/handlers/memory-bridge-refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-bridge-refresh.js","sourceRoot":"","sources":["../../../src/hooks/handlers/memory-bridge-refresh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,uCAAuC;AACvC,MAAM,WAAW,GAAG,MAAM,CAAC;AAE3B,8EAA8E;AAC9E,IAAI,eAAe,GAAG,CAAC,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,WAAmB;IAChE,IAAI,CAAC;QACH,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;QACvD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,WAAW,CAAC,CAAC;QAE7C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC;YAC7C,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,GAAG,GAAG,eAAe,GAAG,WAAW,EAAE,CAAC;YACxC,OAAO;QACT,CAAC;QAED,eAAe,GAAG,GAAG,CAAC;QAEtB,MAAM,EAAE,mBAAmB,EAAE,GAAG,MAAM,MAAM,CAAC,+BAA+B,CAAC,CAAC;QAC9E,MAAM,mBAAmB,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,4CAA4C;IAC9C,CAAC;AACH,CAAC"}

package/dist/hooks/handlers/notification-hooks.js

@@ -0,0 +1,62 @@
+/**
+ * System Notification Hook Handler
+ *
+ * Captures message-bearing system notifications as BRAIN observations.
+ * File-change notifications (filePath + changeType) are handled by
+ * file-hooks.ts; this module only handles Notification payloads with
+ * a `message` field.
+ *
+ * Gated behind brain.autoCapture config. Never throws.
+ * Auto-registers on module load.
+ *
+ * @task T166
+ */
+import { hooks } from '../registry.js';
+import { isAutoCaptureEnabled, isMissingBrainSchemaError } from './handler-helpers.js';
+/**
+ * Handle Notification — capture system notifications as BRAIN observations.
+ *
+ * Only fires for Notification payloads that carry a message field (i.e. system
+ * notifications). File-change notifications (filePath + changeType) are
+ * handled exclusively by file-hooks.ts and are skipped here to avoid
+ * double-capture.
+ *
+ * Gated behind brain.autoCapture config. Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - Notification event payload.
+ *
+ * @task T166
+ */
+export async function handleSystemNotification(projectRoot, payload) {
+    // File-change notifications are handled by file-hooks.ts
+    if (payload.filePath || payload.changeType)
+        return;
+    // Only handle message-bearing system notifications
+    if (!payload.message)
+        return;
+    if (!(await isAutoCaptureEnabled(projectRoot)))
+        return;
+    const { observeBrain } = await import('../../memory/brain-retrieval.js');
+    try {
+        await observeBrain(projectRoot, {
+            text: `System notification: ${payload.message}`,
+            title: `Notification: ${payload.message.slice(0, 60)}`,
+            type: 'discovery',
+            sourceSessionId: payload.sessionId,
+            sourceType: 'agent',
+        });
+    }
+    catch (err) {
+        if (!isMissingBrainSchemaError(err))
+            throw err;
+    }
+}
+// Lower priority (90) so file-hooks.ts (100) runs first for Notification events
+hooks.register({
+    id: 'brain-system-notification',
+    event: 'Notification',
+    handler: handleSystemNotification,
+    priority: 90,
+});
+//# sourceMappingURL=notification-hooks.js.map

package/dist/hooks/handlers/notification-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-hooks.js","sourceRoot":"","sources":["../../../src/hooks/handlers/notification-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEvF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,WAAmB,EACnB,OAA4B;IAE5B,yDAAyD;IACzD,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,UAAU;QAAE,OAAO;IACnD,mDAAmD;IACnD,IAAI,CAAC,OAAO,CAAC,OAAO;QAAE,OAAO;IAC7B,IAAI,CAAC,CAAC,MAAM,oBAAoB,CAAC,WAAW,CAAC,CAAC;QAAE,OAAO;IAEvD,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,iCAAiC,CAAC,CAAC;IAEzE,IAAI,CAAC;QACH,MAAM,YAAY,CAAC,WAAW,EAAE;YAC9B,IAAI,EAAE,wBAAwB,OAAO,CAAC,OAAO,EAAE;YAC/C,KAAK,EAAE,iBAAiB,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;YACtD,IAAI,EAAE,WAAW;YACjB,eAAe,EAAE,OAAO,CAAC,SAAS;YAClC,UAAU,EAAE,OAAO;SACpB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC;YAAE,MAAM,GAAG,CAAC;IACjD,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,KAAK,CAAC,QAAQ,CAAC;IACb,EAAE,EAAE,2BAA2B;IAC/B,KAAK,EAAE,cAAc;IACrB,OAAO,EAAE,wBAAwB;IACjC,QAAQ,EAAE,EAAE;CACb,CAAC,CAAC"}

package/dist/hooks/handlers/session-hooks.d.ts

@@ -7,6 +7,9 @@
  * T138: Triggers memory bridge refresh on session start and end.
  * T139: Regenerates bridge with session scope on start.
  * T144: Extracts transcript observations on session end.
+ * T5158: Auto-snapshots SQLite databases (tasks.db + brain.db) via
+ *        VACUUM INTO on SessionEnd to preserve a recovery point now that
+ *        the databases are no longer tracked in project git (ADR-013).
  */
 import type { SessionEndPayload, SessionStartPayload } from '../types.js';
 /**
@@ -23,4 +26,22 @@ export declare function handleSessionStart(projectRoot: string, payload: Session
  * T144: Extract transcript observations via cross-provider adapter.
  */
 export declare function handleSessionEnd(projectRoot: string, payload: SessionEndPayload): Promise<void>;
+/**
+ * Handle SessionEnd - snapshot SQLite databases to `.cleo/backups/sqlite/`.
+ *
+ * ADR-013 / T5158: `.cleo/tasks.db` and `.cleo/brain.db` are NOT tracked in
+ * project git, so we need an out-of-band recovery mechanism. This handler
+ * calls `vacuumIntoBackupAll` with `force: true` at every session end to
+ * guarantee a fresh point-in-time snapshot of both databases.
+ *
+ * Rotation (MAX_SNAPSHOTS = 10 per database) is handled inside
+ * `sqlite-backup.ts`. Failures here are non-fatal: a backup error must
+ * never block session end.
+ *
+ * The `vacuumIntoBackupAll` import is deferred to call time so tests that
+ * auto-load session-hooks (e.g. via `handlers/index.ts`) do not have to
+ * mock every transitive dependency of `sqlite-backup.ts` at hoisted
+ * `vi.mock` time.
+ */
+export declare function handleSessionEndBackup(projectRoot: string, _payload: SessionEndPayload): Promise<void>;
 //# sourceMappingURL=session-hooks.d.ts.map

package/dist/hooks/handlers/session-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/session-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAI1E;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CA8Cf"}
+{"version":3,"file":"session-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/session-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAI1E;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CA8Cf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAOf"}