shieldcortex 4.11.1 → 4.12.1

package/dist/setup/deep-clean.js

@@ -0,0 +1,396 @@
+/**
+ * Deep-clean / residue detection for ShieldCortex ↔ OpenClaw integration.
+ *
+ * The standard `uninstall` and `uninstallPlugin` code paths only fire when
+ * the on-disk artefacts they expected are still present. Partial uninstalls,
+ * manual cleanups, and version-to-version shape changes left orphaned config
+ * entries in `~/.openclaw/openclaw.json` and `~/.openclaw/workspace/.clawhub/lock.json`
+ * that kept producing "plugin references without files" and "missing skill file"
+ * warnings until purged by hand (see incident notes 2026-04-23/24).
+ *
+ * This module scans every known residue location once, independently of disk
+ * state, and offers a single surgical clean-up pass.
+ *
+ * Scope: read/write of JSON config files + directory removal under the user's
+ * home directory. No network, no sudo, no shell invocation.
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { execSync } from 'child_process';
+const PLUGIN_ID = 'shieldcortex-realtime';
+const HOOK_NAME = 'cortex-memory';
+/**
+ * Resolve the real user's home directory (mirrors openclaw.ts behaviour so the
+ * two modules agree on which home to touch under sudo).
+ */
+function resolveHome() {
+    const sudoUser = process.env.SUDO_USER;
+    if (sudoUser) {
+        try {
+            const entry = execSync(`getent passwd ${sudoUser}`, {
+                encoding: 'utf-8',
+                timeout: 5000,
+            }).trim();
+            const homeDir = entry.split(':')[5];
+            if (homeDir && fs.existsSync(homeDir))
+                return homeDir;
+        }
+        catch {
+            // getent not available (macOS)
+        }
+    }
+    return os.homedir();
+}
+function readJsonOrNull(file) {
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        return typeof parsed === 'object' && parsed !== null
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeJson(file, data) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+function getPath(root, keyPath) {
+    let node = root;
+    for (const key of keyPath) {
+        if (typeof node !== 'object' || node === null)
+            return undefined;
+        node = node[key];
+    }
+    return node;
+}
+function deletePath(root, keyPath) {
+    if (keyPath.length === 0)
+        return false;
+    let node = root;
+    for (let i = 0; i < keyPath.length - 1; i++) {
+        const next = node[keyPath[i]];
+        if (typeof next !== 'object' || next === null)
+            return false;
+        node = next;
+    }
+    const leaf = keyPath[keyPath.length - 1];
+    if (leaf in node) {
+        delete node[leaf];
+        return true;
+    }
+    return false;
+}
+function filterArrayAtPath(root, keyPath, contains) {
+    const target = getPath(root, keyPath);
+    if (!Array.isArray(target))
+        return false;
+    const before = target.length;
+    const filtered = target.filter((entry) => !(typeof entry === 'string' && entry.includes(contains)));
+    if (filtered.length === before)
+        return false;
+    // Re-walk and assign back so we don't rely on aliasing
+    let node = root;
+    for (let i = 0; i < keyPath.length - 1; i++) {
+        node = node[keyPath[i]];
+    }
+    node[keyPath[keyPath.length - 1]] = filtered;
+    return true;
+}
+/**
+ * Build the full list of known residue locations and whether each one is
+ * currently populated. Pure read — no mutation.
+ */
+export function scanForResidue() {
+    const home = resolveHome();
+    const openclawJson = path.join(home, '.openclaw', 'openclaw.json');
+    const clawhubLock = path.join(home, '.openclaw', 'workspace', '.clawhub', 'lock.json');
+    const cfg = readJsonOrNull(openclawJson) ?? {};
+    const lock = readJsonOrNull(clawhubLock) ?? {};
+    const paths = [];
+    // ── openclaw.json: plugins ─────────────────────────────
+    paths.push({
+        description: `openclaw.json: .plugins.installs["${PLUGIN_ID}"]`,
+        removal: { kind: 'delete-config-key', file: openclawJson, keyPath: ['plugins', 'installs', PLUGIN_ID] },
+        present: !!getPath(cfg, ['plugins', 'installs', PLUGIN_ID]),
+        category: 'plugin-config',
+    });
+    paths.push({
+        description: `openclaw.json: .plugins.entries["${PLUGIN_ID}"]`,
+        removal: { kind: 'delete-config-key', file: openclawJson, keyPath: ['plugins', 'entries', PLUGIN_ID] },
+        present: !!getPath(cfg, ['plugins', 'entries', PLUGIN_ID]),
+        category: 'plugin-config',
+    });
+    paths.push({
+        description: `openclaw.json: .plugins.allow[] contains "${PLUGIN_ID}"`,
+        removal: { kind: 'filter-config-array', file: openclawJson, keyPath: ['plugins', 'allow'], contains: PLUGIN_ID },
+        present: (() => {
+            const arr = getPath(cfg, ['plugins', 'allow']);
+            return Array.isArray(arr) && arr.some((e) => typeof e === 'string' && e.includes(PLUGIN_ID));
+        })(),
+        category: 'plugin-config',
+    });
+    paths.push({
+        description: `openclaw.json: .plugins.load.paths[] contains "${PLUGIN_ID}"`,
+        removal: { kind: 'filter-config-array', file: openclawJson, keyPath: ['plugins', 'load', 'paths'], contains: PLUGIN_ID },
+        present: (() => {
+            const arr = getPath(cfg, ['plugins', 'load', 'paths']);
+            return Array.isArray(arr) && arr.some((e) => typeof e === 'string' && e.includes(PLUGIN_ID));
+        })(),
+        category: 'plugin-config',
+    });
+    // ── openclaw.json: hooks (both modern and legacy shapes) ─
+    paths.push({
+        description: 'openclaw.json: .hooks.shieldcortex',
+        removal: { kind: 'delete-config-key', file: openclawJson, keyPath: ['hooks', 'shieldcortex'] },
+        present: !!getPath(cfg, ['hooks', 'shieldcortex']),
+        category: 'hook-config',
+    });
+    paths.push({
+        description: 'openclaw.json: .hooks.internal.installs.shieldcortex',
+        removal: { kind: 'delete-config-key', file: openclawJson, keyPath: ['hooks', 'internal', 'installs', 'shieldcortex'] },
+        present: !!getPath(cfg, ['hooks', 'internal', 'installs', 'shieldcortex']),
+        category: 'hook-config',
+    });
+    paths.push({
+        description: 'openclaw.json: .hooks.internal.entries.shieldcortex',
+        removal: { kind: 'delete-config-key', file: openclawJson, keyPath: ['hooks', 'internal', 'entries', 'shieldcortex'] },
+        present: !!getPath(cfg, ['hooks', 'internal', 'entries', 'shieldcortex']),
+        category: 'hook-config',
+    });
+    paths.push({
+        description: 'openclaw.json: .hooks.internal.allow[] contains "shieldcortex"',
+        removal: { kind: 'filter-config-array', file: openclawJson, keyPath: ['hooks', 'internal', 'allow'], contains: 'shieldcortex' },
+        present: (() => {
+            const arr = getPath(cfg, ['hooks', 'internal', 'allow']);
+            return Array.isArray(arr) && arr.some((e) => typeof e === 'string' && e.includes('shieldcortex'));
+        })(),
+        category: 'hook-config',
+    });
+    // ── clawhub lock ────────────────────────────────────────
+    paths.push({
+        description: 'clawhub/lock.json: .skills.shieldcortex',
+        removal: { kind: 'delete-config-key', file: clawhubLock, keyPath: ['skills', 'shieldcortex'] },
+        present: !!getPath(lock, ['skills', 'shieldcortex']),
+        category: 'clawhub-skill-lock',
+    });
+    // ── filesystem ──────────────────────────────────────────
+    const dirEntries = [
+        // Current canonical paths (these ARE the install when present)
+        { dir: path.join(home, '.openclaw', 'hooks', HOOK_NAME), category: 'hook-dir' },
+        { dir: path.join(home, '.claude', 'hooks', HOOK_NAME), category: 'hook-dir' },
+        { dir: path.join(home, '.openclaw', 'extensions', PLUGIN_ID), category: 'plugin-dir' },
+        // Legacy paths — always orphaned when present (migrations should remove them)
+        { dir: path.join(home, '.openclaw', 'hooks', 'internal', HOOK_NAME), category: 'legacy-hook-dir' },
+        { dir: path.join(home, '.openclaw', 'hooks', 'shieldcortex'), category: 'legacy-hook-dir' },
+        { dir: path.join(home, '.claude', 'hooks', 'internal', HOOK_NAME), category: 'legacy-hook-dir' },
+    ];
+    for (const { dir, category } of dirEntries) {
+        paths.push({
+            description: dir,
+            removal: { kind: 'delete-directory', path: dir },
+            present: fs.existsSync(dir),
+            category,
+        });
+    }
+    const dirtyCount = paths.filter((p) => p.present).length;
+    const cleanCount = paths.length - dirtyCount;
+    return { paths, dirtyCount, cleanCount };
+}
+/**
+ * Detect whether the SC plugin / hook are currently installed on disk.
+ * Used by `scanForOrphans()` to tell legitimate install state from true orphans.
+ */
+function detectInstallState() {
+    const home = resolveHome();
+    const pluginManifest = path.join(home, '.openclaw', 'extensions', PLUGIN_ID, 'openclaw.plugin.json');
+    const pluginInstalled = fs.existsSync(pluginManifest);
+    const hookCandidates = [
+        path.join(home, '.openclaw', 'hooks', HOOK_NAME),
+        path.join(home, '.claude', 'hooks', HOOK_NAME),
+    ];
+    const hookInstalled = hookCandidates.some((d) => fs.existsSync(d));
+    return { pluginInstalled, hookInstalled };
+}
+/**
+ * Return only residue entries that are TRUE ORPHANS — meaning the config /
+ * lock-file entry references a ShieldCortex artefact that is NOT currently
+ * installed on disk, OR it's a legacy path that shouldn't exist anymore.
+ *
+ * This is what `shieldcortex doctor` wants: it should flag partial-uninstall
+ * wreckage without flagging every legitimate install as "residue" (which was
+ * the v4.12.0 bug — the doctor couldn't tell a healthy install from a leftover).
+ *
+ * The `--deep` purge path continues to use `scanForResidue()` because its job
+ * is to remove ALL traces unconditionally, not just orphans.
+ */
+export function scanForOrphans() {
+    const installState = detectInstallState();
+    const report = scanForResidue();
+    const orphans = report.paths.filter((p) => {
+        if (!p.present)
+            return false;
+        switch (p.category) {
+            case 'plugin-config':
+                // Config entry is legitimate iff the plugin dir is installed.
+                return !installState.pluginInstalled;
+            case 'hook-config':
+                // Config entry is legitimate iff any current hook dir is installed.
+                return !installState.hookInstalled;
+            case 'plugin-dir':
+            case 'hook-dir':
+                // These ARE the install when present — never orphaned.
+                return false;
+            case 'legacy-hook-dir':
+                // Legacy paths should have been migrated off; always flag.
+                return true;
+            case 'clawhub-skill-lock':
+                // SC's openclaw install wrapper doesn't manage the skill. If the entry
+                // is present it was written by `openclaw skills install shieldcortex`
+                // and is either a matching live skill or an orphan. We can't confirm
+                // which without knowing where OpenClaw keeps skill artefacts, so we
+                // conservatively flag it so the operator can decide (purge or reinstall).
+                return true;
+        }
+    });
+    return {
+        paths: orphans,
+        orphanCount: orphans.length,
+        installState,
+    };
+}
+/**
+ * Apply all pending removals from a residue report. Config mutations for the
+ * same file are batched so we write each JSON file at most once.
+ */
+export function cleanResidue(report, options = {}) {
+    const result = { removed: [], errors: [] };
+    // Load each referenced config file once
+    const configCache = new Map();
+    const loadConfig = (file) => {
+        if (!configCache.has(file)) {
+            configCache.set(file, readJsonOrNull(file) ?? {});
+        }
+        return configCache.get(file);
+    };
+    const dirtyConfigFiles = new Set();
+    for (const entry of report.paths) {
+        if (!entry.present)
+            continue;
+        try {
+            const r = entry.removal;
+            if (r.kind === 'delete-directory') {
+                if (!options.dryRun) {
+                    fs.rmSync(r.path, { recursive: true, force: true });
+                }
+                result.removed.push(entry.description);
+            }
+            else if (r.kind === 'delete-config-key') {
+                const cfg = loadConfig(r.file);
+                if (deletePath(cfg, r.keyPath)) {
+                    dirtyConfigFiles.add(r.file);
+                    result.removed.push(entry.description);
+                }
+            }
+            else if (r.kind === 'filter-config-array') {
+                const cfg = loadConfig(r.file);
+                if (filterArrayAtPath(cfg, r.keyPath, r.contains)) {
+                    dirtyConfigFiles.add(r.file);
+                    result.removed.push(entry.description);
+                }
+            }
+        }
+        catch (err) {
+            result.errors.push({ description: entry.description, error: err.message });
+        }
+    }
+    if (!options.dryRun) {
+        for (const file of dirtyConfigFiles) {
+            try {
+                writeJson(file, configCache.get(file));
+            }
+            catch (err) {
+                result.errors.push({ description: file, error: err.message });
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Best-effort restart of the OpenClaw gateway so the purged config takes
+ * effect. Returns a structured report; never throws.
+ *
+ * Order of attempts:
+ *   - Linux:  `systemctl --user restart openclaw-gateway`
+ *   - macOS:  `launchctl kickstart -k gui/<uid>/ai.openclaw.gateway`
+ *   - Fallback: skip with info message.
+ */
+export async function restartOpenClawGateway() {
+    const platform = process.platform;
+    if (platform === 'linux') {
+        try {
+            execSync('systemctl --user restart openclaw-gateway', {
+                encoding: 'utf-8',
+                timeout: 10000,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            return { attempted: true, restarted: true, method: 'systemctl --user' };
+        }
+        catch (err) {
+            return {
+                attempted: true,
+                restarted: false,
+                method: 'systemctl --user',
+                detail: err.message,
+            };
+        }
+    }
+    if (platform === 'darwin') {
+        try {
+            const uid = process.getuid ? process.getuid() : 0;
+            execSync(`launchctl kickstart -k gui/${uid}/ai.openclaw.gateway`, {
+                encoding: 'utf-8',
+                timeout: 10000,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            return { attempted: true, restarted: true, method: 'launchctl kickstart' };
+        }
+        catch (err) {
+            return {
+                attempted: true,
+                restarted: false,
+                method: 'launchctl kickstart',
+                detail: err.message,
+            };
+        }
+    }
+    return {
+        attempted: false,
+        restarted: false,
+        method: 'unsupported-platform',
+        detail: `Restart not implemented for platform: ${platform}`,
+    };
+}
+/**
+ * High-level entry point used by `shieldcortex uninstall --deep`.
+ * Scans → cleans → (optionally) restarts gateway.
+ */
+export async function runDeepClean(options = {}) {
+    const report = scanForResidue();
+    const result = cleanResidue(report, { dryRun: options.dryRun });
+    let gateway;
+    if (options.restartGateway && !options.dryRun && result.removed.length > 0) {
+        gateway = await restartOpenClawGateway();
+    }
+    return { report, result, gateway };
+}
+// Exported for tests
+export const _internals = {
+    PLUGIN_ID,
+    HOOK_NAME,
+    resolveHome,
+};

package/dist/setup/uninstall.d.ts

@@ -16,4 +16,6 @@ export declare function removeClaudeMdBlock(): void;
 export declare function uninstallSetup(): Promise<void>;
 export declare function uninstallAll(options?: {
     keepLogs?: boolean;
+    deep?: boolean;
+    restartGateway?: boolean;
 }): Promise<void>;

package/dist/setup/uninstall.js

@@ -154,7 +154,10 @@ export async function uninstallSetup() {
 export async function uninstallAll(options) {
     if (blockAgentUninstall())
         return;
-    const confirmed = await requireConfirmation('fully uninstall ShieldCortex');
+    const action = options?.deep
+        ? 'fully uninstall ShieldCortex and purge OpenClaw residue'
+        : 'fully uninstall ShieldCortex';
+    const confirmed = await requireConfirmation(action);
     if (!confirmed) {
         console.log('Uninstall cancelled.');
         return;
@@ -188,6 +191,44 @@ export async function uninstallAll(options) {
     catch (err) {
         console.error(`Failed to remove CLAUDE.md block: ${err.message}`);
     }
+    // 5. Deep clean: purge all known OpenClaw residue locations that the
+    //    version-specific uninstall paths miss, then (best-effort) restart
+    //    the gateway so the purged config takes effect immediately.
+    if (options?.deep) {
+        try {
+            const { runDeepClean } = await import('./deep-clean.js');
+            const { report, result, gateway } = await runDeepClean({
+                restartGateway: options?.restartGateway !== false,
+            });
+            if (result.removed.length > 0) {
+                console.log(`\nDeep clean: removed ${result.removed.length} residue reference(s):`);
+                for (const r of result.removed) {
+                    console.log(`  - ${r}`);
+                }
+            }
+            else if (report.dirtyCount === 0) {
+                console.log('\nDeep clean: no OpenClaw residue detected.');
+            }
+            if (result.errors.length > 0) {
+                console.warn(`\nDeep clean: ${result.errors.length} error(s):`);
+                for (const e of result.errors) {
+                    console.warn(`  - ${e.description}: ${e.error}`);
+                }
+            }
+            if (gateway) {
+                if (gateway.restarted) {
+                    console.log(`\nOpenClaw gateway restarted via ${gateway.method}.`);
+                }
+                else if (gateway.attempted) {
+                    console.warn(`\nOpenClaw gateway restart via ${gateway.method} failed: ${gateway.detail ?? 'unknown'}`);
+                    console.warn('Restart it manually for the cleanup to take effect.');
+                }
+            }
+        }
+        catch (err) {
+            console.error(`Deep clean failed: ${err.message}`);
+        }
+    }
     console.log('\nDatabase preserved at ~/.shieldcortex/memories.db — delete manually if desired.');
     console.log('Uninstall complete.\n');
     console.log('To also remove the npm package:');

package/hooks/openclaw/cortex-memory/HOOK.md

@@ -28,9 +28,9 @@ When `openclawAutoMemory` is enabled:
 5. Skips exact and near-duplicate memories using novelty filtering
 
 ### On Session Start (Agent Bootstrap)
-1. Calls Cortex `get_context` to retrieve relevant memories
-2. Injects them into the agent's bootstrap context
-3. Agent starts with knowledge of past sessions
+Bootstrap context injection was **disabled in v2026.2.26**. OpenClaw's native Memory Search now handles context recall at session start, so the hook no longer pushes memories into the system prompt (which was producing ~40× duplication of CORTEX_MEMORY.md and eating most of the context window).
+
+The hook still fires on `agent:bootstrap` for lifecycle wiring (warning-bootstrap-file handoff, etc.) but contributes nothing to the system prompt. This keeps `extraSystemPromptHash` stable across turns and prevents the session-binding reset loop documented in `src/setup/claude-md.ts`.
 
 ### Keyword Triggers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shieldcortex",
-  "version": "4.11.1",
+  "version": "4.12.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,9 +1,13 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.11.1",
+  "version": "4.12.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,
+  "engines": {
+    "openclaw": ">=2026.3.22",
+    "recommended": ">=2026.4.23"
+  },
   "enabledByDefault": false,
   "activation": {
     "hooks": ["llm_input", "llm_output", "before_tool_call", "session_end"],