shieldcortex 4.12.13 → 4.13.0

package/dist/setup/claude-md.d.ts

@@ -10,4 +10,5 @@
  */
 export declare function setupClaudeMd(options?: {
     stopHook?: boolean;
+    sessionEnd?: boolean;
 }): Promise<void>;

package/dist/setup/deep-clean.d.ts

@@ -73,6 +73,39 @@ export interface CleanResult {
  * currently populated. Pure read — no mutation.
  */
 export declare function scanForResidue(): ResidueReport;
+/**
+ * Detect whether the SC plugin / hook are currently installed on disk.
+ * Used by `scanForOrphans()` to tell legitimate install state from true orphans.
+ *
+ * Plugin install location depends on which install mode OpenClaw chose:
+ *
+ *   1. **native-package** (Mac homebrew, npm-global in OpenClaw's search path) —
+ *      plugin lives at `${npmRoot}/shieldcortex/plugins/openclaw/dist/`. The
+ *      user-space `~/.openclaw/extensions/` is NOT populated.
+ *   2. **trusted-local-copy** (Linux fleet, npm-global outside the search path) —
+ *      plugin is copied to `~/.openclaw/extensions/shieldcortex-realtime/`.
+ *
+ * The most reliable signal is the `installPath` recorded under
+ * `openclaw.json: .plugins.installs[shieldcortex-realtime]` — that's the path
+ * the installer actually used. We honour that first, then fall back to the
+ * known install locations so we can still detect installs that pre-date the
+ * `installPath` field.
+ */
+/**
+ * The plugin counts as installed when OpenClaw has registered it in BOTH
+ * `plugins.entries[<id>]` AND `plugins.allow[]`.
+ *
+ * Background: when the plugin was installed via `openclaw plugins install <pkg>`
+ * (native-package mode — Mac homebrew, Linux global), OpenClaw stores the plugin
+ * in its own internal tree, NOT under `~/.openclaw/extensions/`. From the doctor's
+ * perspective there are no plugin bytes on disk in any of the paths it checks.
+ * Without this check the doctor false-flags `plugins.entries[<id>]` and
+ * `plugins.allow[<id>]` as "OpenClaw residue" on every Mac homebrew install
+ * (the user-reported symptom on 4 May 2026 that triggered this fix).
+ *
+ * Exported for direct unit testing without having to mock fs / os.homedir().
+ */
+export declare function isPluginRegisteredInOpenClawConfig(cfg: unknown): boolean;
 /**
  * Return only residue entries that are TRUE ORPHANS — meaning the config /
  * lock-file entry references a ShieldCortex artefact that is NOT currently

package/dist/setup/deep-clean.js

@@ -219,6 +219,27 @@ export function scanForResidue() {
  * known install locations so we can still detect installs that pre-date the
  * `installPath` field.
  */
+/**
+ * The plugin counts as installed when OpenClaw has registered it in BOTH
+ * `plugins.entries[<id>]` AND `plugins.allow[]`.
+ *
+ * Background: when the plugin was installed via `openclaw plugins install <pkg>`
+ * (native-package mode — Mac homebrew, Linux global), OpenClaw stores the plugin
+ * in its own internal tree, NOT under `~/.openclaw/extensions/`. From the doctor's
+ * perspective there are no plugin bytes on disk in any of the paths it checks.
+ * Without this check the doctor false-flags `plugins.entries[<id>]` and
+ * `plugins.allow[<id>]` as "OpenClaw residue" on every Mac homebrew install
+ * (the user-reported symptom on 4 May 2026 that triggered this fix).
+ *
+ * Exported for direct unit testing without having to mock fs / os.homedir().
+ */
+export function isPluginRegisteredInOpenClawConfig(cfg) {
+    const entryEnabled = !!getPath(cfg, ['plugins', 'entries', PLUGIN_ID]);
+    const allowList = getPath(cfg, ['plugins', 'allow']);
+    const inAllow = Array.isArray(allowList)
+        && allowList.some((e) => typeof e === 'string' && e === PLUGIN_ID);
+    return entryEnabled && inAllow;
+}
 function detectInstallState() {
     const home = resolveHome();
     // 1. Honour whatever path the installer recorded in openclaw.json.
@@ -252,6 +273,11 @@ function detectInstallState() {
             pluginInstalled = true;
         }
     }
+    // 4. Fallback: trust OpenClaw's own plugin registry — see
+    //    `isPluginRegisteredInOpenClawConfig` below for the rationale.
+    if (!pluginInstalled && isPluginRegisteredInOpenClawConfig(cfg)) {
+        pluginInstalled = true;
+    }
     const hookCandidates = [
         path.join(home, '.openclaw', 'hooks', HOOK_NAME),
         path.join(home, '.claude', 'hooks', HOOK_NAME),

package/dist/setup/doctor.js

@@ -46,14 +46,19 @@ function checkDatabase() {
         add('FAIL', 'Database not found at ~/.shieldcortex/memories.db');
         return;
     }
-    const label = db.isLegacy ? '~/.claude-memory/memories.db (legacy)' : '~/.shieldcortex/memories.db';
+    const label = db.isLegacy ? `${db.path} (legacy)` : '~/.shieldcortex/memories.db';
     try {
         const stat = fs.statSync(db.path);
         const Database = require('better-sqlite3');
         const conn = new Database(db.path, { readonly: true });
         const row = conn.prepare('SELECT COUNT(*) as count FROM memories').get();
         conn.close();
-        add('PASS', `Database: ${label} (${row.count} memories, ${formatBytes(stat.size)})`);
+        if (db.isLegacy) {
+            add('WARN', `Database: ${label} (${row.count} memories, ${formatBytes(stat.size)}) — DEPRECATED, removed in v5.0.0; run: shieldcortex migrate-legacy`);
+        }
+        else {
+            add('PASS', `Database: ${label} (${row.count} memories, ${formatBytes(stat.size)})`);
+        }
     }
     catch (err) {
         add('FAIL', `Database: ${label} — ${err.message}`);

package/dist/setup/openclaw.js

@@ -491,45 +491,19 @@ function installPlugin(options = {}) {
         console.warn('  Or suppress this warning: shieldcortex openclaw install --no-plugins');
         return 'skipped';
     }
-    // If the plugin is already discoverable by OpenClaw via npm global install,
-    // skip the extensions copy to avoid "duplicate plugin id" warnings.
-    // OpenClaw auto-discovers from standard global node_modules paths only.
-    if (!process.env[OPENCLAW_SKIP_NATIVE_INSTALL_ENV]) {
-        try {
-            const npmRoot = execSync('npm root -g', { encoding: 'utf-8', timeout: 5000 }).trim();
-            const globalPluginPath = path.join(npmRoot, 'shieldcortex', 'plugins', 'openclaw', 'dist', 'openclaw.plugin.json');
-            // Only skip extensions copy if npm global is in a path OpenClaw searches
-            const openclawSearchPaths = [
-                '/usr/lib/node_modules',
-                '/usr/local/lib/node_modules',
-                '/opt/homebrew/lib/node_modules',
-            ];
-            const isInOpenClawSearchPath = openclawSearchPaths.some((p) => npmRoot.startsWith(p));
-            if (fs.existsSync(globalPluginPath) && isInOpenClawSearchPath) {
-                // Clean up any existing extensions copy that would cause duplicates
-                const extDir = findExtensionsDir();
-                if (extDir) {
-                    const staleDir = path.join(extDir, PLUGIN_DIR_NAME);
-                    if (fs.existsSync(staleDir)) {
-                        fs.rmSync(staleDir, { recursive: true, force: true });
-                    }
-                }
-                // Record the dir that ACTUALLY contains the manifest as `installPath`
-                // — that's the convention the trusted-local-copy path uses, and what
-                // `detectInstallState()` in deep-clean.ts checks. Earlier versions
-                // wrote `path.dirname(path.dirname(globalPluginPath))` (the package
-                // root, one level too high), so the manifest existence check failed
-                // and doctor flagged the legitimate config entries as orphans on
-                // every Mac homebrew install. Reproduced on Friday/mikes-mac on
-                // every release v4.12.3 → v4.12.6.
-                const pluginDir = path.dirname(globalPluginPath);
-                console.log(`Installed real-time plugin to ${pluginDir}`);
-                trustLocalPlugin(pluginDir, '');
-                return 'native-package';
-            }
-        }
-        catch { /* npm not available or no global install — fall through */ }
-    }
+    // Previously this branch tried to "skip the extensions copy" when the npm
+    // global path was on a list of "OpenClaw-searched" paths
+    // (/usr/lib/node_modules, /usr/local/lib/node_modules,
+    // /opt/homebrew/lib/node_modules). That premise was false: OpenClaw only
+    // discovers plugins from its own stock dir and ~/.openclaw/extensions/, not
+    // from arbitrary global node_modules entries. The branch deleted the
+    // working extension dir and pointed `trustLocalPlugin` at a path OpenClaw
+    // never reads, leaving every Mac homebrew (and Linux global) install with
+    // an unregistered plugin and a "plugin not found" doctor warning.
+    //
+    // Now we always go through `tryNativeOpenClawPluginInstall()` first
+    // (`openclaw plugins install <pkg>` registers correctly), then fall back
+    // to copying into the extensions dir.
     const nativeInstall = tryNativeOpenClawPluginInstall();
     if (nativeInstall) {
         return nativeInstall;

package/dist/setup/settings-hooks.d.ts

@@ -9,4 +9,5 @@
 export declare const REQUIRED_HOOK_NAMES: readonly string[];
 export declare function setupHooks(options?: {
     stopHook?: boolean;
+    sessionEnd?: boolean;
 }): void;

package/dist/setup/settings-hooks.js

@@ -28,6 +28,13 @@ export const REQUIRED_HOOK_NAMES = Object.freeze(Object.keys(CORTEX_HOOKS));
 const STOP_HOOK = {
     hooks: [{ type: 'command', command: 'shieldcortex hook stop', timeout: 10 }],
 };
+// SessionEnd is opt-in. The hook script gates execution behind
+// `autoMemory.enableSessionEnd` in ~/.shieldcortex/config.json AND a
+// process.env-based OpenClaw context detector, so wiring it via this flag
+// does NOT regress the v4.10 OpenClaw-crash class on its own.
+const SESSION_END_HOOK = {
+    hooks: [{ type: 'command', command: 'shieldcortex hook session-end', timeout: 10 }],
+};
 function hasCortexHook(entries) {
     return entries.some((e) => e.hooks?.some((h) => typeof h.command === 'string' && h.command.includes('shieldcortex')));
 }
@@ -79,18 +86,22 @@ export function setupHooks(options) {
     }
     // First: migrate any stale npx commands to direct binary
     const migrated = migrateNpxHooks(settings);
-    // Remove SessionEnd hook — causes fatal failures in OpenClaw agents
-    if (settings.hooks.SessionEnd) {
+    // SessionEnd handling is now bidirectional:
+    //   - if --with-session-end was passed, install it (the .mjs gates execution
+    //     by config + OpenClaw env so it's safe to wire here);
+    //   - otherwise, remove any existing ShieldCortex SessionEnd entry to keep
+    //     the OpenClaw-safe default for users who don't explicitly opt in.
+    if (!options?.sessionEnd && settings.hooks.SessionEnd) {
         const hadCortex = hasCortexHook(settings.hooks.SessionEnd);
         if (hadCortex) {
             settings.hooks.SessionEnd = settings.hooks.SessionEnd.filter((e) => !e.hooks?.some((h) => typeof h.command === 'string' && h.command.includes('shieldcortex')));
             if (settings.hooks.SessionEnd.length === 0)
                 delete settings.hooks.SessionEnd;
-            console.log('  - Hook: SessionEnd (removed — causes agent crashes, PreCompact handles this)');
+            console.log('  - Hook: SessionEnd (removed — opt in with `--with-session-end`)');
         }
     }
     let added = 0;
-    // Install command hooks (PreCompact, SessionStart, SessionEnd, UserPromptSubmit)
+    // Install command hooks (PreCompact, SessionStart, UserPromptSubmit)
     for (const [name, entry] of Object.entries(CORTEX_HOOKS)) {
         if (!Array.isArray(settings.hooks[name])) {
             settings.hooks[name] = [];
@@ -104,6 +115,20 @@ export function setupHooks(options) {
             console.log(`  = Hook: ${name} (already configured)`);
         }
     }
+    // Optionally install SessionEnd hook
+    if (options?.sessionEnd) {
+        if (!Array.isArray(settings.hooks.SessionEnd)) {
+            settings.hooks.SessionEnd = [];
+        }
+        if (!hasCortexHook(settings.hooks.SessionEnd)) {
+            settings.hooks.SessionEnd.push(SESSION_END_HOOK);
+            added++;
+            console.log(`  + Hook: SessionEnd (opt-in — gated by autoMemory.enableSessionEnd)`);
+        }
+        else {
+            console.log(`  = Hook: SessionEnd (already configured)`);
+        }
+    }
     // Optionally install Stop hook
     if (options?.stopHook) {
         if (!Array.isArray(settings.hooks.Stop)) {
@@ -112,7 +137,7 @@ export function setupHooks(options) {
         if (!hasCortexHook(settings.hooks.Stop)) {
             settings.hooks.Stop.push(STOP_HOOK);
             added++;
-            console.log(`  + Hook: Stop (opt-in)`);
+            console.log(`  + Hook: Stop (opt-in — gated by autoMemory.enableStop)`);
         }
         else {
             console.log(`  = Hook: Stop (already configured)`);

package/dist/setup/status.js

@@ -66,6 +66,33 @@ function getStatusInfo(dbPath) {
     catch {
         // Quarantine table doesn't exist - that's fine
     }
+    // Per-hook invocation telemetry (last 7 days). Disambiguates the
+    // "fires but produces nothing" vs "never fires" failure modes that
+    // both showed as "Last activity: never" in older releases.
+    const hookActivity = [];
+    try {
+        const rows = db.prepare(`
+      SELECT hook_name AS hookName,
+             COUNT(*)             AS invocationCount,
+             MAX(invoked_at)      AS lastInvokedAt,
+             SUM(memories_extracted) AS memoriesExtracted
+      FROM hook_invocations
+      WHERE invoked_at >= datetime('now', '-7 days')
+      GROUP BY hook_name
+      ORDER BY hook_name
+    `).all();
+        for (const r of rows) {
+            hookActivity.push({
+                hookName: r.hookName,
+                invocationCount: r.invocationCount,
+                lastInvokedAt: r.lastInvokedAt,
+                memoriesExtracted: r.memoriesExtracted ?? 0,
+            });
+        }
+    }
+    catch {
+        // hook_invocations table doesn't exist on pre-4.13 installs - leave empty
+    }
     return {
         dbPath,
         dbSize,
@@ -77,6 +104,7 @@ function getStatusInfo(dbPath) {
         lastActivity,
         quarantined,
         threatsBlocked,
+        hookActivity,
     };
 }
 const SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
@@ -145,6 +173,17 @@ export async function handleStatusCommand() {
   Defence:       ${info.quarantined} quarantined, ${info.threatsBlocked} threats blocked
   Hooks:         ${hooksConfigured ? 'configured' : '⚠️  not configured'}
 `);
+        if (info.hookActivity.length > 0) {
+            console.log('  Hook activity (last 7 days):');
+            for (const h of info.hookActivity) {
+                const last = h.lastInvokedAt ? formatRelativeTime(h.lastInvokedAt) : 'never';
+                const extracted = h.memoriesExtracted > 0
+                    ? `, extracted ${h.memoriesExtracted} memor${h.memoriesExtracted === 1 ? 'y' : 'ies'}`
+                    : '';
+                console.log(`    ${h.hookName.padEnd(14)} fired ${h.invocationCount}× — last ${last}${extracted}`);
+            }
+            console.log('');
+        }
         if (!hooksConfigured) {
             console.log(`  ⚠️  Claude Code hooks are not set up. Memory won't auto-save or inject context.`);
             console.log(`     Run: shieldcortex install\n`);

package/hooks/openclaw/cortex-memory/runtime.mjs

@@ -3,21 +3,35 @@ import fs from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 
-export function createOpenClawRuntime({ logPrefix = "[shieldcortex]" } = {}) {
+export function createOpenClawRuntime({
+  logPrefix = "[shieldcortex]",
+  configPath = path.join(homedir(), ".shieldcortex", "config.json"),
+} = {}) {
   let shieldConfig = null;
+  let shieldConfigMtime = 0;
   let resolvedServerCmd = null;
   let lastCallErrorType = null;
 
+  // mtime-gated cache: re-read on every call if the config file's modified
+  // time has advanced. Lets dashboard / CLI toggles take effect on the next
+  // event without an OpenClaw gateway restart.
   async function loadShieldConfig() {
-    if (shieldConfig) return shieldConfig;
+    let mtime = 0;
+    try {
+      const stats = await fs.stat(configPath);
+      mtime = stats.mtimeMs;
+    } catch {
+      mtime = 0;
+    }
+
+    if (shieldConfig && mtime === shieldConfigMtime) return shieldConfig;
 
     try {
-      const configPath = path.join(homedir(), ".shieldcortex", "config.json");
       shieldConfig = JSON.parse(await fs.readFile(configPath, "utf-8"));
     } catch {
       shieldConfig = {};
     }
-
+    shieldConfigMtime = mtime;
     return shieldConfig;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shieldcortex",
-  "version": "4.12.13",
+  "version": "4.13.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/index.js

@@ -156,6 +156,11 @@ const PLUGIN_CONFIG_JSON_SCHEMA = {
     },
 };
 let _config = null;
+// Identity of the shield config we last merged from. The runtime's
+// loadShieldConfig() returns the same parsed object until the file's mtime
+// advances; using reference equality lets us re-merge precisely when the
+// underlying config has actually changed (dashboard / CLI write).
+let _lastShieldConfigRef = null;
 let _configOverride = null;
 let _version = "0.0.0";
 try {
@@ -229,16 +234,17 @@ function applyPluginConfigOverride(api) {
         ...(_configOverride ?? {}),
         ...pluginConfig,
     };
-    if (_config) {
-        _config = { ..._config, ...pluginConfig };
-    }
+    // Override changed — invalidate so loadConfig() re-merges with new override.
+    _config = null;
+    _lastShieldConfigRef = null;
 }
 async function loadConfig() {
-    if (_config)
+    const shieldConfigRaw = await (await getRuntime()).loadShieldConfig();
+    if (_config && shieldConfigRaw === _lastShieldConfigRef)
         return _config;
-    const shieldConfig = normaliseConfig(await (await getRuntime()).loadShieldConfig());
+    _lastShieldConfigRef = shieldConfigRaw;
     _config = {
-        ...shieldConfig,
+        ...normaliseConfig(shieldConfigRaw),
         ...(_configOverride ?? {}),
     };
     return _config;

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

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.12.13",
+  "version": "4.13.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/auto-memory-config.mjs

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const CONFIG_PATH = join(homedir(), '.shieldcortex', 'config.json');
+
+const DEFAULTS = Object.freeze({
+  maxTranscriptBytes: 1024 * 1024,
+  maxTranscriptLines: 5000,
+  keepSlashCommandProse: true,
+  stopHookSamplingTurns: 10,
+  stopHookWindowBytes: 256 * 1024,
+  enableSessionEnd: false,
+  enableStop: false,
+});
+
+export function getAutoMemoryConfig() {
+  let raw = {};
+  try {
+    if (existsSync(CONFIG_PATH)) {
+      raw = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+    }
+  } catch {
+    // fall through to defaults
+  }
+  const overrides = (raw && typeof raw.autoMemory === 'object' && raw.autoMemory) || {};
+  return {
+    maxTranscriptBytes: pickPositiveInt(overrides.maxTranscriptBytes, DEFAULTS.maxTranscriptBytes),
+    maxTranscriptLines: pickPositiveInt(overrides.maxTranscriptLines, DEFAULTS.maxTranscriptLines),
+    keepSlashCommandProse: typeof overrides.keepSlashCommandProse === 'boolean'
+      ? overrides.keepSlashCommandProse
+      : DEFAULTS.keepSlashCommandProse,
+    stopHookSamplingTurns: pickPositiveInt(overrides.stopHookSamplingTurns, DEFAULTS.stopHookSamplingTurns),
+    stopHookWindowBytes: pickPositiveInt(overrides.stopHookWindowBytes, DEFAULTS.stopHookWindowBytes),
+    enableSessionEnd: overrides.enableSessionEnd === true,
+    enableStop: overrides.enableStop === true,
+  };
+}
+
+function pickPositiveInt(value, fallback) {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    return Math.floor(value);
+  }
+  return fallback;
+}

package/scripts/lib/telemetry.mjs

@@ -0,0 +1,58 @@
+/**
+ * Hook-invocation telemetry.
+ *
+ * Records every hook firing so `shieldcortex status` can show "fires but
+ * extracts nothing" failure modes (previously indistinguishable from
+ * "never fires"). Schema mirrors the migration in src/database/init.ts.
+ */
+
+let schemaEnsured = false;
+
+function ensureSchema(db) {
+  if (schemaEnsured) return;
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS hook_invocations (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      hook_name TEXT NOT NULL,
+      invoked_at TEXT NOT NULL DEFAULT (datetime('now')),
+      exit_code INTEGER,
+      duration_ms INTEGER,
+      memories_extracted INTEGER DEFAULT 0,
+      transcript_bytes INTEGER,
+      notes TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_hook_invocations_name_time ON hook_invocations(hook_name, invoked_at DESC);
+  `);
+  schemaEnsured = true;
+}
+
+/**
+ * Insert a single hook-invocation row. All fields except hook_name are
+ * optional. Wrapped in try/catch — telemetry must never block a hook.
+ *
+ * `invoked_at` is supplied as an explicit ISO-8601 UTC string (with `Z`)
+ * rather than relying on the SCHEMA's `datetime('now')` default — that
+ * default returns a naive `YYYY-MM-DD HH:MM:SS` string with no timezone,
+ * which JS Date() then interprets as local time and renders status
+ * timestamps off by the local UTC offset.
+ */
+export function recordHookInvocation(db, info) {
+  try {
+    ensureSchema(db);
+    db.prepare(`
+      INSERT INTO hook_invocations
+        (hook_name, invoked_at, exit_code, duration_ms, memories_extracted, transcript_bytes, notes)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      info.hookName,
+      new Date().toISOString(),
+      info.exitCode ?? null,
+      info.durationMs ?? null,
+      info.memoriesExtracted ?? 0,
+      info.transcriptBytes ?? null,
+      info.notes ?? null,
+    );
+  } catch (err) {
+    console.error(`[telemetry] Failed to record ${info?.hookName} invocation: ${err?.message}`);
+  }
+}

package/scripts/lib/transcript-reader.mjs

@@ -0,0 +1,123 @@
+import { existsSync, openSync, readSync, closeSync, statSync } from 'fs';
+import { homedir } from 'os';
+
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+const DEFAULT_MAX_LINES = 5000;
+const SLASH_DROP_LEN = 200;
+
+function isSingleLineSlashCommand(text) {
+  if (!text || text[0] !== '/') return false;
+  if (text.length >= SLASH_DROP_LEN) return false;
+  if (text.includes('\n')) return false;
+  return true;
+}
+
+function extractText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((c) => c && c.type === 'text' && typeof c.text === 'string')
+      .map((c) => c.text)
+      .join('\n');
+  }
+  return '';
+}
+
+/**
+ * Read the tail of a Claude Code transcript JSONL and return the
+ * concatenated user+assistant text plus telemetry metadata.
+ *
+ * Replaces three duplicated readers in pre-compact-hook and session-end-hook
+ * that all hard-coded `slice(-50)` and a blanket `startsWith('/')` filter.
+ *
+ * @param {string|null|undefined} transcriptPath  Path (may start with `~`).
+ * @param {object} [opts]
+ * @param {number} [opts.maxBytes=1MiB]   Tail-byte ceiling — bounds memory on huge transcripts.
+ * @param {number} [opts.maxLines=5000]   Hard line cap after JSONL parse.
+ * @param {boolean} [opts.keepSlashCommandProse=true]
+ *        true  → drop only single-line slash invocations under 200 chars
+ *        false → drop any message starting with `/` (legacy strict)
+ * @returns {{ text: string, messageCount: number, bytesRead: number, rawLineCount: number }}
+ */
+export function readTranscriptText(transcriptPath, opts = {}) {
+  const empty = { text: '', messageCount: 0, bytesRead: 0, rawLineCount: 0 };
+  if (!transcriptPath || typeof transcriptPath !== 'string') return empty;
+
+  const resolvedPath = transcriptPath.replace(/^~/, homedir());
+  if (!existsSync(resolvedPath)) return empty;
+
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+  const maxLines = opts.maxLines ?? DEFAULT_MAX_LINES;
+  const keepSlashProse = opts.keepSlashCommandProse !== false;
+
+  let raw;
+  let bytesRead = 0;
+  let truncated = false;
+  try {
+    const stat = statSync(resolvedPath);
+    const fileSize = stat.size;
+    bytesRead = Math.min(fileSize, Math.max(0, maxBytes));
+    truncated = bytesRead < fileSize;
+
+    if (bytesRead === 0) return empty;
+
+    const fd = openSync(resolvedPath, 'r');
+    try {
+      const buf = Buffer.alloc(bytesRead);
+      readSync(fd, buf, 0, bytesRead, fileSize - bytesRead);
+      raw = buf.toString('utf-8');
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return empty;
+  }
+
+  let lines = raw.split('\n');
+  // If we sliced from the middle of the file, the first line is likely a
+  // partial JSON fragment — drop it rather than emit a parse error.
+  if (truncated && lines.length > 0) {
+    lines = lines.slice(1);
+  }
+  // Trim a trailing empty line from a clean newline-terminated file.
+  if (lines.length > 0 && lines[lines.length - 1] === '') {
+    lines = lines.slice(0, -1);
+  }
+
+  // Hard cap: keep the most recent N lines.
+  if (lines.length > maxLines) {
+    lines = lines.slice(lines.length - maxLines);
+  }
+  const rawLineCount = lines.length;
+
+  const messages = [];
+  for (const line of lines) {
+    if (!line) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const role = entry.type || entry.message?.role;
+    if (role !== 'user' && role !== 'assistant') continue;
+
+    const text = extractText(entry.message?.content);
+    if (!text) continue;
+
+    if (keepSlashProse) {
+      if (isSingleLineSlashCommand(text)) continue;
+    } else if (text[0] === '/') {
+      continue;
+    }
+
+    messages.push(text);
+  }
+
+  return {
+    text: messages.join('\n\n'),
+    messageCount: messages.length,
+    bytesRead,
+    rawLineCount,
+  };
+}