shieldcortex 4.13.0 → 4.13.1

package/dist/cli/doctor.js

@@ -338,6 +338,90 @@ async function checkHooks() {
         return { label: 'Hooks', status: 'warn', message: `check failed — ${msg}` };
     }
 }
+// ── Check 4b: Auto-memory hook gates ──────────────────────
+/**
+ * Surfaces the resolved on/off state of the opt-in Stop and SessionEnd
+ * auto-memory hooks. Pre-v4.13.1 these were triple-gated (install flag,
+ * runtime config, sampling) with the runtime gate failing silently —
+ * users who wired the hook saw zero captures and zero feedback (#41).
+ *
+ * The check looks at both layers:
+ *   - settings.json: is the hook wired so Claude Code will fire it?
+ *   - autoMemory.enableStop / enableSessionEnd: will the hook actually run?
+ *
+ * Both layers must agree for the hook to do work. v4.13.1 onwards, the
+ * install flag flips both — if they disagree here, the user edited one
+ * side by hand and should re-run setup.
+ */
+export async function checkAutoMemoryHooks() {
+    const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+    let wiredStop = false;
+    let wiredSessionEnd = false;
+    try {
+        if (fs.existsSync(settingsPath)) {
+            const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+            const hooks = settings?.hooks || {};
+            const isCortexWired = (entries) => Array.isArray(entries) && entries.some((entry) => Array.isArray(entry?.hooks) && entry.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('shieldcortex')));
+            wiredStop = isCortexWired(hooks.Stop);
+            wiredSessionEnd = isCortexWired(hooks.SessionEnd);
+        }
+    }
+    catch { /* fall through — both stay false, user gets a clean info row */ }
+    // Lazy-import to avoid pulling cloud/config into doctor's static graph
+    // when the user hasn't configured anything yet.
+    let gateStop = false;
+    let gateSessionEnd = false;
+    let samplingTurns = 10;
+    try {
+        const cfg = await import('../cloud/config.js');
+        const enable = cfg.getAutoMemoryEnableConfig();
+        gateStop = enable.enableStop;
+        gateSessionEnd = enable.enableSessionEnd;
+        const raw = cfg.readRawConfig();
+        const am = raw.autoMemory && typeof raw.autoMemory === 'object'
+            ? raw.autoMemory
+            : {};
+        if (typeof am.stopHookSamplingTurns === 'number' && am.stopHookSamplingTurns > 0) {
+            samplingTurns = Math.floor(am.stopHookSamplingTurns);
+        }
+    }
+    catch { /* defaults already set */ }
+    const rowFor = (label, wired, gate, flag, extra) => {
+        if (!wired && !gate) {
+            return {
+                label,
+                status: 'info',
+                message: 'opt-in (not installed)',
+            };
+        }
+        if (wired && gate) {
+            return {
+                label,
+                status: 'pass',
+                message: extra ? `enabled (${extra})` : 'enabled',
+            };
+        }
+        if (wired && !gate) {
+            return {
+                label,
+                status: 'warn',
+                message: 'wired in settings.json but runtime gate is off — hook will exit silently every turn',
+                fix: `Run \`shieldcortex setup ${flag}\` to flip the gate, or set autoMemory.enableStop/enableSessionEnd=true in ~/.shieldcortex/config.json`,
+            };
+        }
+        // gate && !wired
+        return {
+            label,
+            status: 'warn',
+            message: 'runtime gate is on but hook is not wired in settings.json — hook will never fire',
+            fix: `Run \`shieldcortex setup ${flag}\` to wire the hook`,
+        };
+    };
+    return [
+        rowFor('Auto-memory: Stop hook', wiredStop, gateStop, '--with-stop-hook', `samples turn % ${samplingTurns} == 0`),
+        rowFor('Auto-memory: SessionEnd hook', wiredSessionEnd, gateSessionEnd, '--with-session-end'),
+    ];
+}
 // ── Check 5: Process check ────────────────────────────────
 async function checkProcesses() {
     const results = [];
@@ -588,6 +672,7 @@ export async function runDoctor() {
         checkWritePath, // Smoke test: real INSERT/SELECT/DELETE round-trip — catches silent schema drift
         checkMemoryStats,
         checkHooks,
+        checkAutoMemoryHooks,
         checkProcesses,
         checkDiskUsage,
         checkLockFile,

package/dist/cloud/config.d.ts

@@ -116,6 +116,28 @@ export declare function setProactiveRecall(enabled: boolean): void;
  * so the flip is a one-command undo.
  */
 export declare function restore410Defaults(): void;
+export interface AutoMemoryEnableConfig {
+    enableStop: boolean;
+    enableSessionEnd: boolean;
+}
+/**
+ * Returns the resolved on/off state of the opt-in auto-memory hooks.
+ *
+ * Default is false for both — preserves the OpenClaw-safe default that
+ * shipped in v4.13.0. The install flags (`--with-stop-hook` /
+ * `--with-session-end`) flip these to true so that wiring the hook in
+ * settings.json and enabling the runtime gate are a single user action.
+ */
+export declare function getAutoMemoryEnableConfig(): AutoMemoryEnableConfig;
+/**
+ * Persists the on/off state of the opt-in auto-memory hooks.
+ *
+ * Lives in `autoMemory.enableStop` / `autoMemory.enableSessionEnd` under
+ * `~/.shieldcortex/config.json` — the same namespace `auto-memory-config.mjs`
+ * reads from at hook fire time. Single source of truth: install flag +
+ * runtime gate cannot disagree.
+ */
+export declare function setAutoMemoryEnableConfig(updates: Partial<AutoMemoryEnableConfig>): void;
 export interface ToolResponseScanConfig {
     scanToolResponses: boolean;
     toolResponseMode: 'advisory' | 'enforce';

package/dist/cloud/config.js

@@ -499,6 +499,44 @@ export function restore410Defaults() {
     };
     writeRawConfig(raw);
 }
+/**
+ * Returns the resolved on/off state of the opt-in auto-memory hooks.
+ *
+ * Default is false for both — preserves the OpenClaw-safe default that
+ * shipped in v4.13.0. The install flags (`--with-stop-hook` /
+ * `--with-session-end`) flip these to true so that wiring the hook in
+ * settings.json and enabling the runtime gate are a single user action.
+ */
+export function getAutoMemoryEnableConfig() {
+    const raw = readRawConfig();
+    const am = raw.autoMemory && typeof raw.autoMemory === 'object'
+        ? raw.autoMemory
+        : {};
+    return {
+        enableStop: am.enableStop === true,
+        enableSessionEnd: am.enableSessionEnd === true,
+    };
+}
+/**
+ * Persists the on/off state of the opt-in auto-memory hooks.
+ *
+ * Lives in `autoMemory.enableStop` / `autoMemory.enableSessionEnd` under
+ * `~/.shieldcortex/config.json` — the same namespace `auto-memory-config.mjs`
+ * reads from at hook fire time. Single source of truth: install flag +
+ * runtime gate cannot disagree.
+ */
+export function setAutoMemoryEnableConfig(updates) {
+    const raw = readRawConfig();
+    const existing = raw.autoMemory && typeof raw.autoMemory === 'object'
+        ? raw.autoMemory
+        : {};
+    if (updates.enableStop !== undefined)
+        existing.enableStop = updates.enableStop;
+    if (updates.enableSessionEnd !== undefined)
+        existing.enableSessionEnd = updates.enableSessionEnd;
+    raw.autoMemory = existing;
+    writeRawConfig(raw);
+}
 const DEFAULT_TOOL_RESPONSE_SCAN_CONFIG = {
     scanToolResponses: true,
     toolResponseMode: 'advisory',

package/dist/setup/settings-hooks.js

@@ -4,6 +4,7 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { setAutoMemoryEnableConfig } from '../cloud/config.js';
 const SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
 const CORTEX_HOOKS = {
     PreCompact: {
@@ -123,7 +124,7 @@ export function setupHooks(options) {
         if (!hasCortexHook(settings.hooks.SessionEnd)) {
             settings.hooks.SessionEnd.push(SESSION_END_HOOK);
             added++;
-            console.log(`  + Hook: SessionEnd (opt-in — gated by autoMemory.enableSessionEnd)`);
+            console.log(`  + Hook: SessionEnd (opt-in — flipping autoMemory.enableSessionEnd=true)`);
         }
         else {
             console.log(`  = Hook: SessionEnd (already configured)`);
@@ -137,7 +138,7 @@ export function setupHooks(options) {
         if (!hasCortexHook(settings.hooks.Stop)) {
             settings.hooks.Stop.push(STOP_HOOK);
             added++;
-            console.log(`  + Hook: Stop (opt-in — gated by autoMemory.enableStop)`);
+            console.log(`  + Hook: Stop (opt-in — flipping autoMemory.enableStop=true)`);
         }
         else {
             console.log(`  = Hook: Stop (already configured)`);
@@ -151,4 +152,24 @@ export function setupHooks(options) {
     else {
         console.log('Hooks: all hooks already configured in ~/.claude/settings.json');
     }
+    // Single source of truth: the install flag IS the runtime gate. Wiring the
+    // hook in settings.json without flipping autoMemory.enable* was the
+    // silent-amnesia failure mode in #41 — passing --with-stop-hook wrote the
+    // hook but the runtime gate (default false) made it bail on every fire.
+    // Always sync gate to install flag — including the false case, so removing
+    // a hook by re-running install without the flag also disables the gate.
+    if (options?.stopHook !== undefined || options?.sessionEnd !== undefined) {
+        const updates = {};
+        if (options.stopHook !== undefined)
+            updates.enableStop = options.stopHook;
+        if (options.sessionEnd !== undefined)
+            updates.enableSessionEnd = options.sessionEnd;
+        try {
+            setAutoMemoryEnableConfig(updates);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`Hooks: could not update autoMemory enable config — ${msg}`);
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shieldcortex",
-  "version": "4.13.0",
+  "version": "4.13.1",
   "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.13.0",
+  "version": "4.13.1",
   "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

@@ -2,7 +2,14 @@ import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 
-const CONFIG_PATH = join(homedir(), '.shieldcortex', 'config.json');
+function getConfigPath() {
+  // Honour the same SHIELDCORTEX_CONFIG_DIR override that src/cloud/config.ts
+  // uses, so the runtime gate and the rest of the system always resolve to the
+  // same config file (and so tests can isolate via a temp dir).
+  const override = process.env.SHIELDCORTEX_CONFIG_DIR?.trim();
+  const dir = override || join(homedir(), '.shieldcortex');
+  return join(dir, 'config.json');
+}
 
 const DEFAULTS = Object.freeze({
   maxTranscriptBytes: 1024 * 1024,
@@ -17,8 +24,9 @@ const DEFAULTS = Object.freeze({
 export function getAutoMemoryConfig() {
   let raw = {};
   try {
-    if (existsSync(CONFIG_PATH)) {
-      raw = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+    const configPath = getConfigPath();
+    if (existsSync(configPath)) {
+      raw = JSON.parse(readFileSync(configPath, 'utf-8'));
     }
   } catch {
     // fall through to defaults

package/scripts/stop-hook.mjs

@@ -17,7 +17,7 @@
  */
 
 import Database from 'better-sqlite3';
-import { existsSync, mkdirSync, openSync, readSync, closeSync, statSync } from 'fs';
+import { existsSync, mkdirSync, openSync, readSync, closeSync, statSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { saveAutoExtractedMemory } from './lib/save-memory.mjs';
@@ -25,6 +25,35 @@ import { readTranscriptText } from './lib/transcript-reader.mjs';
 import { getAutoMemoryConfig } from './lib/auto-memory-config.mjs';
 import { recordHookInvocation } from './lib/telemetry.mjs';
 
+// Sentinel directory for once-per-session "disabled" log lines. Without this
+// the stop hook bails silently on every turn when autoMemory.enableStop is
+// false — the user-visible symptom is "ShieldCortex never captured anything"
+// with zero feedback (filed in #41 as silent-amnesia). One sentinel file
+// per session keeps the log to a single line for the lifetime of the session.
+const SC_LOG_DIR = join(homedir(), '.shieldcortex', 'logs');
+const STOP_DISABLED_SENTINEL_DIR = join(SC_LOG_DIR, 'stop-hook-disabled-sessions');
+
+function logDisabledOnceForSession(sessionId, reason) {
+  // Always print the line — stderr is the existing channel for hook diagnostics
+  // (mirrors session-end-hook). Then plant a sentinel so subsequent fires in
+  // the same session stay quiet.
+  if (!sessionId) {
+    console.error(`[shieldcortex stop-hook] ${reason}`);
+    return;
+  }
+  try {
+    mkdirSync(STOP_DISABLED_SENTINEL_DIR, { recursive: true });
+    const sentinel = join(STOP_DISABLED_SENTINEL_DIR, sessionId.replace(/[^a-zA-Z0-9_.-]/g, '_'));
+    if (existsSync(sentinel)) return;
+    writeFileSync(sentinel, new Date().toISOString(), { mode: 0o600 });
+    console.error(`[shieldcortex stop-hook] ${reason}`);
+  } catch {
+    // Sentinel write failed — fall back to printing once per fire rather than
+    // staying silent. Better noisy-but-discoverable than silent-amnesia.
+    console.error(`[shieldcortex stop-hook] ${reason}`);
+  }
+}
+
 // ==================== DB ====================
 
 const NEW_DB_DIR = join(homedir(), '.shieldcortex');
@@ -303,8 +332,15 @@ process.stdin.on('end', () => {
 
     const autoMemConfig = getAutoMemoryConfig();
     if (!autoMemConfig.enableStop) {
-      // Opt-in by config (or by `--with-stop-hook` install flag, which only
-      // wires the hook in settings.json — config still gates execution).
+      // Opt-in by config. As of v4.13.1 the install flag (`--with-stop-hook`)
+      // flips this gate at install time so wiring the hook and enabling it are
+      // a single user action. If the gate is still false here, the user wired
+      // the hook by hand without setting autoMemory.enableStop=true. Log once
+      // per session so the failure is visible (was silent-amnesia in #41).
+      logDisabledOnceForSession(
+        hookData.session_id,
+        `disabled — set autoMemory.enableStop=true in ~/.shieldcortex/config.json (or re-run \`shieldcortex setup --with-stop-hook\`)`,
+      );
       process.exit(0);
     }
 
@@ -313,8 +349,11 @@ process.stdin.on('end', () => {
 
     const turnCount = countAssistantTurns(hookData.transcript_path, windowBytes);
     if (turnCount === 0 || turnCount % samplingTurns !== 0) {
-      // Off-sample. Exit silently — but record the firing so telemetry shows
-      // the hook is actually wired and active.
+      // Off-sample. Surface the sampling decision to stderr so the
+      // "1-in-N turns" behaviour stops being invisible (was a discoverability
+      // gap flagged in #41) — and still record telemetry so the dashboard
+      // shows the hook is actually wired and active.
+      console.error(`[shieldcortex stop-hook] telemetry-only turn=${turnCount}/${samplingTurns}`);
       if (existsSync(DB_PATH)) {
         try {
           const tdb = new Database(DB_PATH, { timeout: 1500 });