shieldcortex 4.16.0 → 4.17.0

package/dist/sessions/capture.js

@@ -0,0 +1,59 @@
+/**
+ * Session capture — write side.
+ *
+ * Hooks (`scripts/prompt-recall-hook.mjs`, `scripts/stop-hook.mjs`,
+ * `scripts/session-end-hook.mjs`, etc.) call `recordEvent()` or the
+ * batched `recordEvents()` to persist turn-by-turn events into the
+ * `session_events` table. The timeline reader in `./timeline.ts`
+ * then reassembles them into the replay stream.
+ *
+ * Distinct from the summary `sessions` table (one row per session)
+ * and from `defence_audit` (one row per scan). Captures every event
+ * with enough fidelity to scrub/replay.
+ */
+import { getDatabase } from '../database/init.js';
+/**
+ * Serialise payload to text. Objects/arrays go through JSON.stringify;
+ * strings pass through. This keeps the column NOT NULL constraint
+ * satisfied even for empty-object payloads and matches the timeline
+ * reader's `JSON.parse` with raw-string fallback.
+ */
+function serialisePayload(payload) {
+    if (typeof payload === 'string')
+        return payload;
+    return JSON.stringify(payload ?? null);
+}
+const INSERT_SQL = `
+  INSERT INTO session_events
+    (session_id, project, ts, kind, actor, payload, duration_ms, audit_id)
+  VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+`;
+/** Insert one event row. Returns the new row id. */
+export function recordEvent(input) {
+    const db = getDatabase();
+    const stmt = db.prepare(INSERT_SQL);
+    const result = stmt.run(input.session_id, input.project ?? null, input.ts, input.kind, input.actor ?? null, serialisePayload(input.payload), input.duration_ms ?? null, input.audit_id ?? null);
+    return Number(result.lastInsertRowid);
+}
+/**
+ * Batched insert wrapped in a single transaction. Used when a hook
+ * fires and produces several events at once (e.g. stop-hook emitting
+ * a `response` plus N tool_call/tool_result pairs from the just-
+ * finished turn). All-or-nothing: a CHECK violation rolls back the
+ * lot, so the table never holds half a turn.
+ */
+export function recordEvents(inputs) {
+    if (inputs.length === 0)
+        return [];
+    const db = getDatabase();
+    const stmt = db.prepare(INSERT_SQL);
+    const ids = [];
+    const tx = db.transaction((rows) => {
+        for (const row of rows) {
+            const result = stmt.run(row.session_id, row.project ?? null, row.ts, row.kind, row.actor ?? null, serialisePayload(row.payload), row.duration_ms ?? null, row.audit_id ?? null);
+            ids.push(Number(result.lastInsertRowid));
+        }
+    });
+    tx(inputs);
+    return ids;
+}

package/dist/sessions/import-jsonl.d.ts

@@ -0,0 +1,85 @@
+/**
+ * JSONL transcript importer for Claude Code session files.
+ *
+ * Claude Code writes session transcripts to `~/.claude/projects/<slug>/
+ * <session-uuid>.jsonl`. Each line is a JSON object. Conversation lines
+ * have shape `{type, sessionId, timestamp, message: {role, content}}`
+ * where `content` is an Anthropic SDK content-block array
+ * (`text|thinking|tool_use|tool_result`).
+ *
+ * Mapping to `session_events.kind`:
+ *
+ *   user.text         → prompt
+ *   assistant.text    → response
+ *   assistant.tool_use → tool_call
+ *   user.tool_result  → tool_result
+ *   thinking          → (skipped — not user-replayable in v1)
+ *
+ * Non-conversation lines (`ai-title`, `attachment`, `system`,
+ * `queue-operation`, etc.) are skipped. Idempotent on re-import: each
+ * row carries a sha256 `content_hash` of `kind|payload`, and the
+ * `idx_session_events_dedupe` UNIQUE index drops collisions silently
+ * via `INSERT OR IGNORE`.
+ *
+ * Lossy by design — agentmemory documents the same scope:
+ *   - Anthropic-internal cache markers, partial-message frames, and
+ *     non-string tool_result encodings beyond plain text are not
+ *     preserved.
+ *   - Things we WILL preserve: prompts, assistant text, tool name +
+ *     args + result, and timestamps.
+ */
+import type { SessionEventInput } from './capture.js';
+export interface TranscriptLine {
+    type?: string;
+    sessionId?: string;
+    timestamp?: string;
+    message?: {
+        role?: 'user' | 'assistant';
+        content?: ContentBlock[];
+    };
+}
+type ContentBlock = {
+    type: 'text';
+    text?: string;
+} | {
+    type: 'thinking';
+    thinking?: string;
+} | {
+    type: 'tool_use';
+    id?: string;
+    name?: string;
+    input?: unknown;
+} | {
+    type: 'tool_result';
+    tool_use_id?: string;
+    content?: unknown;
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+export interface ImportResult {
+    sessionId: string | null;
+    eventCount: number;
+    /** Lines that produced zero events — non-conversation types + parse errors. */
+    skipped: number;
+    /** Lines whose JSON parsed but were rejected (missing required fields, unknown block types). */
+    malformed: number;
+}
+/**
+ * Pure mapper: one transcript line → 0..N `SessionEventInput`s.
+ *
+ * Exported so unit tests can exercise the mapping in isolation without
+ * standing up a database. Returns `[]` for any line that doesn't yield
+ * replayable events (thinking blocks, ai-title, missing fields, etc.) —
+ * the caller treats an empty array as "skipped".
+ */
+export declare function parseTranscriptLine(line: unknown): SessionEventInput[];
+/**
+ * Import one JSONL file. Wraps the whole import in a single transaction
+ * so a mid-file error rolls back cleanly — better-sqlite3's transaction
+ * helper restores DB state if the callback throws. Malformed lines do
+ * NOT throw — they're counted and skipped so a single bad row never
+ * blocks the rest of the file.
+ */
+export declare function importJsonlTranscript(path: string): ImportResult;
+export {};

package/dist/sessions/import-jsonl.js

@@ -0,0 +1,193 @@
+/**
+ * JSONL transcript importer for Claude Code session files.
+ *
+ * Claude Code writes session transcripts to `~/.claude/projects/<slug>/
+ * <session-uuid>.jsonl`. Each line is a JSON object. Conversation lines
+ * have shape `{type, sessionId, timestamp, message: {role, content}}`
+ * where `content` is an Anthropic SDK content-block array
+ * (`text|thinking|tool_use|tool_result`).
+ *
+ * Mapping to `session_events.kind`:
+ *
+ *   user.text         → prompt
+ *   assistant.text    → response
+ *   assistant.tool_use → tool_call
+ *   user.tool_result  → tool_result
+ *   thinking          → (skipped — not user-replayable in v1)
+ *
+ * Non-conversation lines (`ai-title`, `attachment`, `system`,
+ * `queue-operation`, etc.) are skipped. Idempotent on re-import: each
+ * row carries a sha256 `content_hash` of `kind|payload`, and the
+ * `idx_session_events_dedupe` UNIQUE index drops collisions silently
+ * via `INSERT OR IGNORE`.
+ *
+ * Lossy by design — agentmemory documents the same scope:
+ *   - Anthropic-internal cache markers, partial-message frames, and
+ *     non-string tool_result encodings beyond plain text are not
+ *     preserved.
+ *   - Things we WILL preserve: prompts, assistant text, tool name +
+ *     args + result, and timestamps.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { createHash } from 'crypto';
+import { getDatabase } from '../database/init.js';
+/**
+ * Pure mapper: one transcript line → 0..N `SessionEventInput`s.
+ *
+ * Exported so unit tests can exercise the mapping in isolation without
+ * standing up a database. Returns `[]` for any line that doesn't yield
+ * replayable events (thinking blocks, ai-title, missing fields, etc.) —
+ * the caller treats an empty array as "skipped".
+ */
+export function parseTranscriptLine(line) {
+    if (!line || typeof line !== 'object')
+        return [];
+    const l = line;
+    // Only conversation lines yield events.
+    if (l.type !== 'user' && l.type !== 'assistant')
+        return [];
+    if (typeof l.sessionId !== 'string' || l.sessionId.length === 0)
+        return [];
+    if (typeof l.timestamp !== 'string' || l.timestamp.length === 0)
+        return [];
+    const content = l.message?.content;
+    if (!Array.isArray(content) || content.length === 0)
+        return [];
+    const events = [];
+    for (const block of content) {
+        const event = blockToEvent(block, l);
+        if (event)
+            events.push(event);
+    }
+    return events;
+}
+function blockToEvent(block, line) {
+    const session_id = line.sessionId;
+    const ts = line.timestamp;
+    if (block.type === 'thinking')
+        return null;
+    if (block.type === 'text' && line.type === 'user') {
+        const text = typeof block.text === 'string' ? block.text : '';
+        if (!text)
+            return null;
+        return { session_id, ts, kind: 'prompt', payload: { text } };
+    }
+    if (block.type === 'text' && line.type === 'assistant') {
+        const text = typeof block.text === 'string' ? block.text : '';
+        if (!text)
+            return null;
+        return {
+            session_id,
+            ts,
+            kind: 'response',
+            payload: { text },
+            actor: 'assistant',
+        };
+    }
+    if (block.type === 'tool_use' && line.type === 'assistant') {
+        const toolBlock = block;
+        return {
+            session_id,
+            ts,
+            kind: 'tool_call',
+            payload: {
+                tool_use_id: toolBlock.id ?? null,
+                name: toolBlock.name ?? null,
+                input: toolBlock.input ?? null,
+            },
+            actor: 'assistant',
+        };
+    }
+    if (block.type === 'tool_result' && line.type === 'user') {
+        const tr = block;
+        return {
+            session_id,
+            ts,
+            kind: 'tool_result',
+            payload: {
+                tool_use_id: tr.tool_use_id ?? null,
+                content: tr.content ?? null,
+            },
+        };
+    }
+    return null;
+}
+/** SHA-256 of `kind|payload-as-canonical-json`. 64-char hex string. */
+function hashEvent(kind, payload) {
+    const canonical = typeof payload === 'string' ? payload : JSON.stringify(payload ?? null);
+    return createHash('sha256').update(`${kind}|${canonical}`).digest('hex');
+}
+const INSERT_OR_IGNORE_SQL = `
+  INSERT OR IGNORE INTO session_events
+    (session_id, project, ts, kind, actor, payload, duration_ms, audit_id, content_hash)
+  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+`;
+/**
+ * Import one JSONL file. Wraps the whole import in a single transaction
+ * so a mid-file error rolls back cleanly — better-sqlite3's transaction
+ * helper restores DB state if the callback throws. Malformed lines do
+ * NOT throw — they're counted and skipped so a single bad row never
+ * blocks the rest of the file.
+ */
+export function importJsonlTranscript(path) {
+    if (!existsSync(path)) {
+        throw new Error(`JSONL transcript not found: ${path}`);
+    }
+    const raw = readFileSync(path, 'utf-8');
+    const lines = raw.split(/\r?\n/);
+    const rows = [];
+    let sessionId = null;
+    let skipped = 0;
+    let malformed = 0;
+    for (const rawLine of lines) {
+        const trimmed = rawLine.trim();
+        if (trimmed.length === 0)
+            continue; // blank lines aren't skipped — they're just whitespace
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            malformed++;
+            skipped++;
+            continue;
+        }
+        const events = parseTranscriptLine(parsed);
+        if (events.length === 0) {
+            skipped++;
+            continue;
+        }
+        if (sessionId === null && events[0]?.session_id) {
+            sessionId = events[0].session_id;
+        }
+        for (const event of events) {
+            rows.push({
+                ...event,
+                content_hash: hashEvent(event.kind, event.payload),
+            });
+        }
+    }
+    if (rows.length === 0) {
+        return { sessionId, eventCount: 0, skipped, malformed };
+    }
+    const db = getDatabase();
+    const stmt = db.prepare(INSERT_OR_IGNORE_SQL);
+    const before = db.prepare('SELECT COUNT(*) AS c FROM session_events').get().c;
+    const tx = db.transaction((batch) => {
+        for (const row of batch) {
+            stmt.run(row.session_id, row.project ?? null, row.ts, row.kind, row.actor ?? null, typeof row.payload === 'string' ? row.payload : JSON.stringify(row.payload ?? null), row.duration_ms ?? null, row.audit_id ?? null, row.content_hash);
+        }
+    });
+    tx(rows);
+    const after = db.prepare('SELECT COUNT(*) AS c FROM session_events').get().c;
+    const inserted = after - before;
+    // `eventCount` reflects the total events parsed from this file regardless
+    // of whether the dedupe index dropped them. Caller can compare to
+    // `inserted` (via row count diff) to see how many were duplicates.
+    return {
+        sessionId,
+        eventCount: rows.length,
+        skipped: skipped + (rows.length - inserted),
+        malformed,
+    };
+}

package/dist/sessions/timeline.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Session capture — read side.
+ *
+ * `getTimeline(sessionId)` returns every event for a session, sorted
+ * by `ts` ascending, with payload JSON.parse'd back into a JS value
+ * (or surfaced as a raw string when the payload was deliberately
+ * stored as plain text). Powers the dashboard replay scrubber.
+ *
+ * Kept deliberately minimal — pagination, filtering by kind, and
+ * cross-session timelines belong on the API route (`./api/routes/
+ * sessions.ts`) above, not in this reader.
+ */
+import type { SessionEventKind } from './capture.js';
+export interface SessionEventRow {
+    id: number;
+    session_id: string;
+    project: string | null;
+    ts: string;
+    kind: SessionEventKind;
+    actor: string | null;
+    /** Parsed JSON (object/array/primitive) or raw string fall-through. */
+    payload: unknown;
+    duration_ms: number | null;
+    audit_id: number | null;
+    created_at: string;
+}
+/** All events for a session, in `ts` ascending order. */
+export declare function getTimeline(sessionId: string): SessionEventRow[];

package/dist/sessions/timeline.js

@@ -0,0 +1,52 @@
+/**
+ * Session capture — read side.
+ *
+ * `getTimeline(sessionId)` returns every event for a session, sorted
+ * by `ts` ascending, with payload JSON.parse'd back into a JS value
+ * (or surfaced as a raw string when the payload was deliberately
+ * stored as plain text). Powers the dashboard replay scrubber.
+ *
+ * Kept deliberately minimal — pagination, filtering by kind, and
+ * cross-session timelines belong on the API route (`./api/routes/
+ * sessions.ts`) above, not in this reader.
+ */
+import { getDatabase } from '../database/init.js';
+/**
+ * Reverse of `capture.serialisePayload`: try JSON.parse, fall back to
+ * the raw string if the payload was stored as plain text. We don't
+ * throw on un-parseable — the importer may legitimately ingest non-JSON
+ * tool output, and a replay viewer that crashes on bad data is useless.
+ */
+function deserialisePayload(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function hydrate(row) {
+    return {
+        id: row.id,
+        session_id: row.session_id,
+        project: row.project,
+        ts: row.ts,
+        kind: row.kind,
+        actor: row.actor,
+        payload: deserialisePayload(row.payload),
+        duration_ms: row.duration_ms,
+        audit_id: row.audit_id,
+        created_at: row.created_at,
+    };
+}
+/** All events for a session, in `ts` ascending order. */
+export function getTimeline(sessionId) {
+    const db = getDatabase();
+    const rows = db
+        .prepare(`SELECT id, session_id, project, ts, kind, actor, payload, duration_ms, audit_id, created_at
+       FROM session_events
+       WHERE session_id = ?
+       ORDER BY ts ASC, id ASC`)
+        .all(sessionId);
+    return rows.map(hydrate);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shieldcortex",
-  "version": "4.16.0",
+  "version": "4.17.0",
   "description": "Trustworthy memory and security for AI agents. Recall debugging, review queue, OpenClaw session capture, and memory poisoning defence for Claude Code, Codex, OpenClaw, LangChain, and MCP agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugins/openclaw/dist/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.16.0",
+  "version": "4.17.0",
   "name": "ShieldCortex Real-time Scanner",
   "description": "Real-time defence scanning on LLM input, memory extraction on LLM output, and active tool call interception with approval gating.",
   "kind": null,

package/scripts/lib/session-capture.mjs

@@ -0,0 +1,102 @@
+/**
+ * Hook-side session_events writer.
+ *
+ * Mirrors the API of `src/sessions/capture.ts` but for `.mjs` hook
+ * scripts that import `better-sqlite3` directly and can't reach into
+ * the TS module without a build step. The two implementations write
+ * the same rows and share the same dedupe constraints.
+ *
+ * Hooks (prompt-recall, stop, session-end, pre-compact) call
+ * `recordSessionEvent(db, event)` with an already-open writable DB
+ * connection. Failures are caught + logged at the call site so a
+ * defective event capture never blocks the hook's primary job.
+ */
+
+const VALID_KINDS = new Set([
+  'prompt',
+  'response',
+  'tool_call',
+  'tool_result',
+  'tool_error',
+  'hook_fire',
+]);
+
+const INSERT_SQL = `
+  INSERT INTO session_events
+    (session_id, project, ts, kind, actor, payload, duration_ms, audit_id)
+  VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+`;
+
+/** Stringify payload — objects → JSON, strings pass through verbatim. */
+function serialisePayload(payload) {
+  if (typeof payload === 'string') return payload;
+  return JSON.stringify(payload ?? null);
+}
+
+/**
+ * Insert one event row. Returns the new row id, or `null` on validation
+ * failure (the caller decides whether that's an error or expected —
+ * e.g. session_id missing from hook data is "expected, skip" not "throw").
+ *
+ * Does NOT throw on SQL errors — the caller's hook flow must keep going.
+ * Captures the error message and returns null so the hook can log it.
+ */
+export function recordSessionEvent(db, event) {
+  if (!db || typeof db.prepare !== 'function') return null;
+  if (!event || typeof event !== 'object') return null;
+  if (typeof event.session_id !== 'string' || event.session_id.length === 0) return null;
+  if (typeof event.ts !== 'string' || event.ts.length === 0) return null;
+  if (!VALID_KINDS.has(event.kind)) return null;
+  if (event.payload === undefined) return null;
+
+  try {
+    const stmt = db.prepare(INSERT_SQL);
+    const result = stmt.run(
+      event.session_id,
+      event.project ?? null,
+      event.ts,
+      event.kind,
+      event.actor ?? null,
+      serialisePayload(event.payload),
+      event.duration_ms ?? null,
+      event.audit_id ?? null,
+    );
+    return Number(result.lastInsertRowid);
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
+/**
+ * Batched insert under a single transaction. Returns an array of
+ * inserted row ids; rolls back the lot if any row violates a
+ * constraint. Empty input returns [] without opening a transaction.
+ */
+export function recordSessionEvents(db, events) {
+  if (!Array.isArray(events) || events.length === 0) return [];
+  const stmt = db.prepare(INSERT_SQL);
+  const ids = [];
+  const tx = db.transaction((rows) => {
+    for (const event of rows) {
+      if (typeof event?.session_id !== 'string') {
+        throw new Error('session_id required');
+      }
+      if (!VALID_KINDS.has(event.kind)) {
+        throw new Error(`invalid kind: ${event.kind}`);
+      }
+      const result = stmt.run(
+        event.session_id,
+        event.project ?? null,
+        event.ts,
+        event.kind,
+        event.actor ?? null,
+        serialisePayload(event.payload),
+        event.duration_ms ?? null,
+        event.audit_id ?? null,
+      );
+      ids.push(Number(result.lastInsertRowid));
+    }
+  });
+  tx(events);
+  return ids;
+}

package/scripts/pre-compact-hook.mjs

@@ -21,6 +21,7 @@ import { readTranscriptText } from './lib/transcript-reader.mjs';
 import { getAutoMemoryConfig } from './lib/auto-memory-config.mjs';
 import { recordHookInvocation } from './lib/telemetry.mjs';
 import { deriveProjectKey } from './lib/project-key.mjs';
+import { recordSessionEvent } from './lib/session-capture.mjs';
 import {
   extractMemorableSegments,
   processSegments,
@@ -154,6 +155,24 @@ process.stdin.on('end', async () => {
     // timeout: 5000ms prevents hook from hanging if DB is locked
     db = new Database(DB_PATH, { timeout: 5000 });
 
+    // ── Session capture (v4.17): mark the compaction boundary in the
+    //    replay timeline. Reuses the already-open write connection so
+    //    no extra better-sqlite3 handle is created.
+    {
+      const sessionId = hookData.session_id || hookData.sessionId || null;
+      if (sessionId) {
+        try {
+          recordSessionEvent(db, {
+            session_id: sessionId,
+            ts: new Date().toISOString(),
+            kind: 'hook_fire',
+            payload: { hook: 'pre-compact', trigger, transcript_path: hookData.transcript_path ?? null },
+            project: project || null,
+          });
+        } catch { /* best-effort */ }
+      }
+    }
+
     // Get current memory stats for dynamic threshold calculation
     const stats = getMemoryStats(db);
     const totalMemories = stats.shortTerm + stats.longTerm;

package/scripts/prompt-recall-hook.mjs

@@ -15,6 +15,7 @@ import { join } from 'path';
 import { homedir } from 'os';
 import { deriveProjectKey } from './lib/project-key.mjs';
 import { sanitisePromptForRecall } from './lib/prompt-sanitiser.mjs';
+import { recordSessionEvent } from './lib/session-capture.mjs';
 
 // ==================== CONFIG ====================
 
@@ -153,15 +154,40 @@ process.stdin.on('readable', () => {
 process.stdin.on('end', () => {
   try {
     const config = loadConfig();
+    const hookData = JSON.parse(input || '{}');
+    const rawPrompt = hookData.prompt || '';
+    const cwd = hookData.cwd || process.cwd();
+    const sessionId = hookData.session_id || hookData.sessionId || null;
+
+    // ── Session capture (v4.17): record the user prompt regardless of
+    //    proactiveRecall config so the dashboard replay timeline gets a
+    //    complete event stream. Opt-out via captureEvents=false. Failures
+    //    are swallowed — capture must never block the user prompt.
+    if (config.captureEvents !== false && sessionId && rawPrompt) {
+      try {
+        const project = deriveProjectKey(cwd);
+        const dbPath = getDbPath();
+        if (existsSync(dbPath)) {
+          const captureDb = new Database(dbPath, { timeout: 1000 });
+          recordSessionEvent(captureDb, {
+            session_id: sessionId,
+            ts: new Date().toISOString(),
+            kind: 'prompt',
+            payload: { text: rawPrompt },
+            project: project || null,
+            actor: 'user',
+          });
+          captureDb.close();
+        }
+      } catch {
+        // Capture is best-effort.
+      }
+    }
 
     if (config.proactiveRecall !== true) {
       process.exit(0);
     }
 
-    const hookData = JSON.parse(input || '{}');
-    const rawPrompt = hookData.prompt || '';
-    const cwd = hookData.cwd || process.cwd();
-
     // Strip OpenClaw / framework metadata wrappers (e.g. Telegram channel
     // headers) before any prompt-based decisions. Without this, the FTS5
     // query is built from "Conversation info untrusted metadata json" tokens

package/scripts/session-end-hook.mjs

@@ -30,6 +30,7 @@ import { readTranscriptText } from './lib/transcript-reader.mjs';
 import { getAutoMemoryConfig } from './lib/auto-memory-config.mjs';
 import { recordHookInvocation } from './lib/telemetry.mjs';
 import { deriveProjectKey } from './lib/project-key.mjs';
+import { recordSessionEvent } from './lib/session-capture.mjs';
 import {
   extractMemorableSegments,
   processSegments,
@@ -128,6 +129,24 @@ process.stdin.on('end', async () => {
     const reason = hookData.reason || 'unknown';
     const project = deriveProjectKey(hookData.cwd);
     const autoMemConfig = getAutoMemoryConfig();
+    const sessionId = hookData.session_id || hookData.sessionId || null;
+
+    // ── Session capture (v4.17): record a `hook_fire` marker so the
+    //    replay timeline shows where sessions end. Best-effort — never
+    //    blocks memory extraction below.
+    if (sessionId && existsSync(DB_PATH)) {
+      try {
+        const captureDb = new Database(DB_PATH, { timeout: 1000 });
+        recordSessionEvent(captureDb, {
+          session_id: sessionId,
+          ts: new Date().toISOString(),
+          kind: 'hook_fire',
+          payload: { hook: 'session-end', reason, transcript_path: hookData.transcript_path ?? null },
+          project: project || null,
+        });
+        captureDb.close();
+      } catch { /* best-effort */ }
+    }
 
     // Config gate: opt-in (default off). Preserves the historical default
     // that protected OpenClaw users. We exit before touching the DB so a