shieldcortex 4.13.0 → 4.14.0

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/context/derive-project-key.d.ts

@@ -0,0 +1,36 @@
+/**
+ * TypeScript port of scripts/lib/project-key.mjs.
+ *
+ * Both the MCP-server side (this module) and the hook scripts must agree on
+ * how a cwd maps to a project key — otherwise writes and reads fall under
+ * different scopes and recall silently misses (issue #42).
+ *
+ * Resolution order:
+ *   1. SHIELDCORTEX_PROJECT_KEY env override
+ *   2. CLAUDE_MEMORY_PROJECT env override (legacy alias for SC env var)
+ *   3. ~/.shieldcortex/config.json projectKey
+ *   4. ~/.shieldcortex/config.json projectAliases[basename]
+ *   5. Git origin owner-repo (walk up from cwd)
+ *   6. Cwd basename (legacy behaviour), skipping noise directories
+ */
+export declare function basenameFromCwd(path: string | null | undefined): string | null;
+declare function parseOriginUrl(url: string): {
+    owner: string;
+    repo: string;
+} | null;
+declare function readOriginFromGitConfig(gitPath: string): {
+    owner: string;
+    repo: string;
+} | null;
+/**
+ * Derive the project key for a given working directory. Mirrors
+ * scripts/lib/project-key.mjs::deriveProjectKey so MCP-server-side and
+ * hook-side keys agree.
+ */
+export declare function deriveProjectKey(cwd: string | null | undefined): string | null;
+export declare const __internal: {
+    parseOriginUrl: typeof parseOriginUrl;
+    basenameFromCwd: typeof basenameFromCwd;
+    readOriginFromGitConfig: typeof readOriginFromGitConfig;
+};
+export {};

package/dist/context/derive-project-key.js

@@ -0,0 +1,150 @@
+/**
+ * TypeScript port of scripts/lib/project-key.mjs.
+ *
+ * Both the MCP-server side (this module) and the hook scripts must agree on
+ * how a cwd maps to a project key — otherwise writes and reads fall under
+ * different scopes and recall silently misses (issue #42).
+ *
+ * Resolution order:
+ *   1. SHIELDCORTEX_PROJECT_KEY env override
+ *   2. CLAUDE_MEMORY_PROJECT env override (legacy alias for SC env var)
+ *   3. ~/.shieldcortex/config.json projectKey
+ *   4. ~/.shieldcortex/config.json projectAliases[basename]
+ *   5. Git origin owner-repo (walk up from cwd)
+ *   6. Cwd basename (legacy behaviour), skipping noise directories
+ */
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+const SKIP_DIRECTORIES = [
+    'src', 'lib', 'dist', 'build', 'out',
+    'node_modules', '.git', '.next', '.cache',
+    'test', 'tests', '__tests__', 'spec',
+    'bin', 'scripts', 'config', 'public', 'static',
+];
+function resolveHome() {
+    return process.env.HOME || process.env.USERPROFILE || homedir();
+}
+function configPath() {
+    return join(resolveHome(), '.shieldcortex', 'config.json');
+}
+function loadConfig() {
+    try {
+        const p = configPath();
+        if (!existsSync(p))
+            return {};
+        return JSON.parse(readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function basenameFromCwd(path) {
+    if (!path)
+        return null;
+    const segments = path.split(/[/\\]/).filter(Boolean);
+    for (let i = segments.length - 1; i >= 0; i--) {
+        const segment = segments[i];
+        if (SKIP_DIRECTORIES.includes(segment.toLowerCase()))
+            continue;
+        if (segment.startsWith('.'))
+            continue;
+        return segment;
+    }
+    return null;
+}
+function findGitDir(startPath) {
+    let current = startPath;
+    const root = '/';
+    for (let i = 0; i < 40 && current && current !== root; i++) {
+        const candidate = join(current, '.git');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+function parseOriginUrl(url) {
+    if (!url)
+        return null;
+    const trimmed = url.trim();
+    const sshMatch = trimmed.match(/^[^@]+@[^:]+:([^/]+)\/(.+?)(?:\.git)?$/);
+    if (sshMatch)
+        return { owner: sshMatch[1], repo: sshMatch[2] };
+    const urlMatch = trimmed.match(/^[a-z]+:\/\/[^/]+\/(.+?)\/([^/]+?)(?:\.git)?$/i);
+    if (urlMatch)
+        return { owner: urlMatch[1], repo: urlMatch[2] };
+    return null;
+}
+function readOriginFromGitConfig(gitPath) {
+    try {
+        let realGitDir = gitPath;
+        const stats = statSync(gitPath);
+        if (stats.isFile()) {
+            const content = readFileSync(gitPath, 'utf-8');
+            if (content.startsWith('gitdir:')) {
+                realGitDir = content.slice('gitdir:'.length).trim();
+            }
+            else {
+                return null;
+            }
+        }
+        const cfgPath = join(realGitDir, 'config');
+        if (!existsSync(cfgPath))
+            return null;
+        const content = readFileSync(cfgPath, 'utf-8');
+        const section = content.match(/\[remote\s+"origin"\][^[]*/);
+        if (!section)
+            return null;
+        const urlMatch = section[0].match(/\burl\s*=\s*(.+)/);
+        if (!urlMatch)
+            return null;
+        return parseOriginUrl(urlMatch[1]);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Derive the project key for a given working directory. Mirrors
+ * scripts/lib/project-key.mjs::deriveProjectKey so MCP-server-side and
+ * hook-side keys agree.
+ */
+export function deriveProjectKey(cwd) {
+    if (process.env.SHIELDCORTEX_PROJECT_KEY) {
+        return process.env.SHIELDCORTEX_PROJECT_KEY;
+    }
+    if (process.env.CLAUDE_MEMORY_PROJECT) {
+        const v = process.env.CLAUDE_MEMORY_PROJECT.trim();
+        if (v)
+            return v;
+    }
+    const config = loadConfig();
+    const projectKey = config.projectKey;
+    if (typeof projectKey === 'string' && projectKey.trim()) {
+        return projectKey.trim();
+    }
+    const basename = basenameFromCwd(cwd);
+    const aliases = config.projectAliases;
+    if (aliases && typeof aliases === 'object' && basename) {
+        const alias = aliases[basename];
+        if (typeof alias === 'string' && alias.trim())
+            return alias.trim();
+    }
+    const gitDir = cwd ? findGitDir(cwd) : null;
+    if (gitDir) {
+        const origin = readOriginFromGitConfig(gitDir);
+        if (origin?.owner && origin?.repo) {
+            return `${origin.owner}-${origin.repo}`;
+        }
+    }
+    return basename;
+}
+export const __internal = {
+    parseOriginUrl,
+    basenameFromCwd,
+    readOriginFromGitConfig,
+};

package/dist/context/project-context.d.ts

@@ -2,22 +2,25 @@
  * Project Context Module
  * Automatically detects and manages the active project scope for memory operations.
  *
- * Detection priority:
- * 1. CLAUDE_MEMORY_PROJECT environment variable
- * 2. Extract from process.cwd() (working directory)
+ * Project key derivation is delegated to deriveProjectKey (mirroring
+ * scripts/lib/project-key.mjs) so reads and writes share one source of truth.
  *
  * The "*" sentinel means "global/all projects" (no filtering).
  */
 /** Sentinel value meaning "all projects" - no project filtering */
 export declare const GLOBAL_PROJECT_SENTINEL = "*";
 /**
- * Extract project name from a file path.
- * Skips common directory names that don't represent projects.
+ * Extract project name from a file path (basename only, with noise-dir skip).
+ * Retained for backwards compatibility with consumers that need just the
+ * basename component. New code should call deriveProjectKey instead.
  */
 export declare function extractProjectFromPath(path: string): string | null;
 /**
  * Initialize project context from environment or working directory.
  * Call this once at server startup.
+ *
+ * Uses the shared deriveProjectKey helper, so the resolved key is identical
+ * to whatever the .mjs hooks would resolve from the same cwd / env / config.
  */
 export declare function initProjectContext(): void;
 /**

package/dist/context/project-context.js

@@ -2,54 +2,38 @@
  * Project Context Module
  * Automatically detects and manages the active project scope for memory operations.
  *
- * Detection priority:
- * 1. CLAUDE_MEMORY_PROJECT environment variable
- * 2. Extract from process.cwd() (working directory)
+ * Project key derivation is delegated to deriveProjectKey (mirroring
+ * scripts/lib/project-key.mjs) so reads and writes share one source of truth.
  *
  * The "*" sentinel means "global/all projects" (no filtering).
  */
+import { deriveProjectKey, basenameFromCwd } from './derive-project-key.js';
 /** Sentinel value meaning "all projects" - no project filtering */
 export const GLOBAL_PROJECT_SENTINEL = '*';
 /** Currently active project (null = global/no filter) */
 let activeProject = null;
 /** How the project was detected */
 let projectDetectionSource = 'none';
-/** Directories to skip when extracting project name from path */
-const SKIP_DIRECTORIES = [
-    'src', 'lib', 'dist', 'build', 'out',
-    'node_modules', '.git', '.next', '.cache',
-    'test', 'tests', '__tests__', 'spec',
-    'bin', 'scripts', 'config', 'public', 'static',
-];
 /**
- * Extract project name from a file path.
- * Skips common directory names that don't represent projects.
+ * Extract project name from a file path (basename only, with noise-dir skip).
+ * Retained for backwards compatibility with consumers that need just the
+ * basename component. New code should call deriveProjectKey instead.
  */
 export function extractProjectFromPath(path) {
-    if (!path)
-        return null;
-    const segments = path.split(/[/\\]/).filter(Boolean);
-    if (segments.length === 0)
-        return null;
-    // Start from the end and find first non-skipped segment
-    for (let i = segments.length - 1; i >= 0; i--) {
-        const segment = segments[i];
-        if (!SKIP_DIRECTORIES.includes(segment.toLowerCase())) {
-            // Skip hidden directories (starting with .)
-            if (segment.startsWith('.'))
-                continue;
-            return segment;
-        }
-    }
-    return null;
+    return basenameFromCwd(path);
 }
 /**
  * Initialize project context from environment or working directory.
  * Call this once at server startup.
+ *
+ * Uses the shared deriveProjectKey helper, so the resolved key is identical
+ * to whatever the .mjs hooks would resolve from the same cwd / env / config.
  */
 export function initProjectContext() {
-    // Priority 1: Environment variable (explicit override)
-    const envProject = process.env.CLAUDE_MEMORY_PROJECT;
+    // Env overrides — match deriveProjectKey's order. We track these separately
+    // so projectDetectionSource keeps reporting 'env' when the user pinned the
+    // project explicitly (visible in get_project / dashboard).
+    const envProject = process.env.SHIELDCORTEX_PROJECT_KEY || process.env.CLAUDE_MEMORY_PROJECT;
     if (envProject) {
         const trimmed = envProject.trim();
         if (trimmed === GLOBAL_PROJECT_SENTINEL) {
@@ -62,9 +46,9 @@ export function initProjectContext() {
         }
         return;
     }
-    // Priority 2: Extract from current working directory
+    // Otherwise: config override → projectAliases → git origin → basename.
     const cwd = process.cwd();
-    const detected = extractProjectFromPath(cwd);
+    const detected = deriveProjectKey(cwd);
     if (detected) {
         activeProject = detected;
         projectDetectionSource = 'cwd';

package/dist/index.js

@@ -77,7 +77,7 @@ import { handleCodexCommand } from './setup/codex.js';
 import { createRequire } from 'module';
 import { execSync } from 'child_process';
 import { disposeModel, preloadModel } from './embeddings/index.js';
-import { stopDefaultWorker } from './worker/brain-worker.js';
+import { startDefaultWorker, stopDefaultWorker } from './worker/brain-worker.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 /**
@@ -172,6 +172,21 @@ async function startMcpServer(dbPath) {
     });
     // Connect via stdio transport
     await server.connect(transport);
+    // Start the brain worker in MCP-lite profile so STM→LTM consolidation runs
+    // even on hooks-only installs (no dashboard, no `service install`). Without
+    // this, MCP-only deployments accumulate STM forever and never promote (#45).
+    // The MCP profile uses a 15 min cadence and skips medium-tick + cloud-sync
+    // work to keep total background load bounded across many open windows.
+    // Disabled via SHIELDCORTEX_DISABLE_WORKER=1 for forensics / debugging.
+    if (process.env.SHIELDCORTEX_DISABLE_WORKER !== '1') {
+        try {
+            startDefaultWorker({ profile: 'mcp' });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error('[shieldcortex] Brain worker autostart failed (continuing without):', msg);
+        }
+    }
     // Preload embedding model in background so first tool call doesn't hang.
     // Fire-and-forget: failure is fine — searchMemories falls back to FTS-only.
     if (process.env.SHIELDCORTEX_SKIP_EMBEDDINGS !== '1') {

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

@@ -7,6 +7,12 @@
  * Keep this alongside CORTEX_HOOKS — drift between the two is what caused #23.
  */
 export declare const REQUIRED_HOOK_NAMES: readonly string[];
+/**
+ * Canonical timeout (seconds) for each ShieldCortex hook. Used by
+ * `shieldcortex doctor` to flag drift in hand-edited settings.json files —
+ * a too-tight UserPromptSubmit timeout silently dropped recall pre-#43.
+ */
+export declare const CANONICAL_HOOK_TIMEOUTS: Readonly<Record<string, number>>;
 export declare function setupHooks(options?: {
     stopHook?: boolean;
     sessionEnd?: boolean;

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: {
@@ -16,7 +17,11 @@ const CORTEX_HOOKS = {
     // agents when the session is already gone. PreCompact handles memory
     // extraction. The cortex-memory hook handles session-end for OpenClaw.
     UserPromptSubmit: {
-        hooks: [{ type: 'command', command: 'shieldcortex hook prompt-recall', timeout: 2 }],
+        // Cold-spawn floor for the recall hook is ~1.5 s (Node + better-sqlite3 +
+        // FTS query). The previous 2 s ceiling SIGKILLed the hook silently under
+        // any IO pressure, dropping recall context with no user-visible error
+        // (#43). 5 s leaves ~3 s headroom on a busy host.
+        hooks: [{ type: 'command', command: 'shieldcortex hook prompt-recall', timeout: 5 }],
     },
 };
 /**
@@ -25,6 +30,15 @@ const CORTEX_HOOKS = {
  * Keep this alongside CORTEX_HOOKS — drift between the two is what caused #23.
  */
 export const REQUIRED_HOOK_NAMES = Object.freeze(Object.keys(CORTEX_HOOKS));
+/**
+ * Canonical timeout (seconds) for each ShieldCortex hook. Used by
+ * `shieldcortex doctor` to flag drift in hand-edited settings.json files —
+ * a too-tight UserPromptSubmit timeout silently dropped recall pre-#43.
+ */
+export const CANONICAL_HOOK_TIMEOUTS = Object.freeze(Object.fromEntries(Object.entries(CORTEX_HOOKS).map(([name, entry]) => [
+    name,
+    entry.hooks?.[0]?.timeout ?? 0,
+])));
 const STOP_HOOK = {
     hooks: [{ type: 'command', command: 'shieldcortex hook stop', timeout: 10 }],
 };
@@ -123,7 +137,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 +151,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 +165,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/dist/worker/brain-worker.d.ts

@@ -29,7 +29,10 @@ export declare class BrainWorker {
     /**
      * Create a new BrainWorker
      *
-     * @param config - Partial configuration to override defaults
+     * @param config - Partial configuration to override defaults. When `profile`
+     *                is 'mcp' and no explicit `lightTickIntervalMs` is provided,
+     *                the lite 15-minute cadence is applied so MCP-server-mode
+     *                workers don't run as often as dashboard-mode ones.
      */
     constructor(config?: Partial<WorkerConfig>);
     /**
@@ -87,13 +90,18 @@ export declare class BrainWorker {
     triggerMediumTick(): Promise<MediumTickResult>;
 }
 /**
- * Get or create the default worker instance
+ * Get or create the default worker instance.
+ * The first call wins — subsequent calls return the existing singleton even
+ * if a different config is passed. That's intentional: it prevents accidental
+ * re-instantiation from creating two competing timer sets within one process.
  */
-export declare function getDefaultWorker(): BrainWorker;
+export declare function getDefaultWorker(config?: Partial<WorkerConfig>): BrainWorker;
 /**
- * Start the default worker if not already running
+ * Start the default worker if not already running. Forwards config to the
+ * underlying constructor on first call (used by MCP-server mode to start
+ * with `profile: 'mcp'`).
  */
-export declare function startDefaultWorker(): BrainWorker;
+export declare function startDefaultWorker(config?: Partial<WorkerConfig>): BrainWorker;
 /**
  * Stop the default worker
  */