shieldcortex 4.12.10 → 4.12.12

package/dist/defence/judge/worker.js

@@ -0,0 +1,106 @@
+import { parentPort } from 'worker_threads';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let generator = null;
+let activeModelId = null;
+let loadError = null;
+async function initTransformers(cacheDir, allowRemoteModels) {
+    try {
+        const mod = await import('@huggingface/transformers');
+        mod.env.allowRemoteModels = allowRemoteModels;
+        mod.env.allowLocalModels = true;
+        mod.env.cacheDir = cacheDir;
+    }
+    catch (error) {
+        loadError = error instanceof Error ? error.message : String(error);
+        throw new Error(`transformers_load_failed:${loadError}`);
+    }
+}
+async function loadModel(modelId, cacheDir, allowRemoteModels) {
+    if (generator && activeModelId === modelId)
+        return;
+    if (loadError)
+        throw new Error(loadError);
+    await initTransformers(cacheDir, allowRemoteModels);
+    const mod = await import('@huggingface/transformers');
+    generator = await mod.pipeline('text-generation', modelId, {
+        dtype: 'q4',
+    });
+    activeModelId = modelId;
+}
+async function withTimeout(promise, timeoutMs) {
+    let timeout = null;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeout = setTimeout(() => reject(new Error(`timeout:${timeoutMs}`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+async function generate(prompt, timeoutMs) {
+    const messages = [
+        {
+            role: 'system',
+            content: 'You are ShieldCortex Review Copilot. Return exactly one valid JSON object and no other text.',
+        },
+        {
+            role: 'user',
+            content: prompt,
+        },
+    ];
+    const output = await withTimeout(generator(messages, {
+        max_new_tokens: 768,
+        do_sample: false,
+        temperature: 0,
+        return_full_text: false,
+    }), timeoutMs);
+    if (Array.isArray(output) && output[0]?.generated_text) {
+        const generated = output[0].generated_text;
+        if (Array.isArray(generated)) {
+            const last = generated[generated.length - 1];
+            return String(last?.content ?? '');
+        }
+        return String(generated);
+    }
+    if (typeof output === 'object' && output && 'generated_text' in output) {
+        const generated = output.generated_text;
+        if (Array.isArray(generated)) {
+            const last = generated[generated.length - 1];
+            return String(last?.content ?? '');
+        }
+        return String(generated);
+    }
+    return String(output ?? '');
+}
+parentPort?.postMessage({ type: 'ready' });
+setInterval(() => {
+    parentPort?.postMessage({ type: 'heartbeat' });
+}, 5000).unref();
+parentPort?.on('message', async (msg) => {
+    try {
+        if (msg.type === 'ping') {
+            parentPort?.postMessage({ id: msg.id, ok: true, rawText: 'pong' });
+            return;
+        }
+        await loadModel(msg.modelId, msg.cacheDir, msg.allowRemoteModels);
+        if (msg.type === 'load') {
+            parentPort?.postMessage({ id: msg.id, ok: true, rawText: 'loaded' });
+            return;
+        }
+        if (!msg.prompt) {
+            parentPort?.postMessage({ id: msg.id, ok: false, reason: 'missing_prompt' });
+            return;
+        }
+        const rawText = await generate(msg.prompt, msg.timeoutMs);
+        parentPort?.postMessage({ id: msg.id, ok: true, rawText });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        parentPort?.postMessage({ id: msg.id, ok: false, reason });
+    }
+});

package/dist/defence/quarantine/review.js

@@ -42,14 +42,24 @@ function promoteApprovedQuarantineRow(row, reviewedBy) {
             : 'quarantine:review',
     });
 }
-function approveExistingPendingRow(row, reviewedBy) {
+function markPendingRowReviewed(id, status, reviewedBy) {
     const db = getDatabase();
-    const memory = promoteApprovedQuarantineRow(row, reviewedBy);
     const reviewedAt = new Date().toISOString();
-    const result = db.prepare('UPDATE quarantine SET status = ?, reviewed_at = ?, reviewed_by = ? WHERE id = ? AND status = ?').run('approved', reviewedAt, reviewedBy, row.id, 'pending');
+    const result = db.prepare('UPDATE quarantine SET status = ?, reviewed_at = ?, reviewed_by = ? WHERE id = ? AND status = ?').run(status, reviewedAt, reviewedBy, id, 'pending');
     if (result.changes === 0) {
         throw new Error('Quarantine entry not found or already reviewed');
     }
+}
+function approveExistingPendingRow(row, reviewedBy) {
+    if (row.source_type === 'memory_file') {
+        markPendingRowReviewed(row.id, 'approved', reviewedBy);
+        return {
+            id: row.id,
+            status: 'approved',
+        };
+    }
+    const memory = promoteApprovedQuarantineRow(row, reviewedBy);
+    markPendingRowReviewed(row.id, 'approved', reviewedBy);
     return {
         id: row.id,
         status: 'approved',
@@ -57,12 +67,11 @@ function approveExistingPendingRow(row, reviewedBy) {
     };
 }
 function rejectPendingQuarantineRow(id, reviewedBy) {
-    const db = getDatabase();
-    const reviewedAt = new Date().toISOString();
-    const result = db.prepare('UPDATE quarantine SET status = ?, reviewed_at = ?, reviewed_by = ? WHERE id = ? AND status = ?').run('rejected', reviewedAt, reviewedBy, id, 'pending');
-    if (result.changes === 0) {
+    const row = getPendingQuarantineRow(id);
+    if (!row) {
         return null;
     }
+    markPendingRowReviewed(row.id, 'rejected', reviewedBy);
     return { id, status: 'rejected' };
 }
 export function approveQuarantineItem(id, reviewedBy = 'dashboard') {

package/dist/index.d.ts

@@ -37,6 +37,7 @@
  *   shieldcortex config --openclaw-auto-memory true   # Enable OpenClaw auto-memory extraction
  *   shieldcortex config --openclaw-auto-memory false  # Disable OpenClaw auto-memory extraction
  *   shieldcortex cloud sync --full      # Backfill local memories + graph to ShieldCortex Cloud
+ *   shieldcortex review-copilot status  # Local AI Explainer status (Pro)
  *   shieldcortex copilot install         # Configure MCP server for VS Code + Cursor
  *   shieldcortex copilot uninstall       # Remove MCP server configuration
  *   shieldcortex copilot status          # Check MCP server configuration

package/dist/index.js

@@ -37,6 +37,7 @@
  *   shieldcortex config --openclaw-auto-memory true   # Enable OpenClaw auto-memory extraction
  *   shieldcortex config --openclaw-auto-memory false  # Disable OpenClaw auto-memory extraction
  *   shieldcortex cloud sync --full      # Backfill local memories + graph to ShieldCortex Cloud
+ *   shieldcortex review-copilot status  # Local AI Explainer status (Pro)
  *   shieldcortex copilot install         # Configure MCP server for VS Code + Cursor
  *   shieldcortex copilot uninstall       # Remove MCP server configuration
  *   shieldcortex copilot status          # Check MCP server configuration
@@ -453,6 +454,7 @@ ${bold}COMMANDS${reset}
   ${cyan}quickstart${reset} [target]    Detect integrations and guide/install setup
   ${cyan}config${reset} [options]      Configure cloud sync and settings
   ${cyan}cloud${reset} sync --full     Backfill local memories + graph to ShieldCortex Cloud
+  ${cyan}review-copilot${reset} <action> Local AI Explainer for quarantine review (Pro)
   ${cyan}cortex${reset} <command>       Mistake learning & pre-flight checks (Pro)
   ${cyan}license${reset} <action>      Manage licence key (activate, status, deactivate)
   ${cyan}iron-dome${reset} <action>    Manage behaviour protection layer
@@ -480,6 +482,7 @@ ${bold}EXAMPLES${reset}
   shieldcortex license activate sc_pro_...
   shieldcortex config --cloud-enable --cloud-api-key <key>
   shieldcortex cloud sync --full
+  shieldcortex review-copilot status
 
 ${bold}DOCS${reset}
   https://shieldcortex.ai/docs
@@ -575,6 +578,12 @@ ${bold}DOCS${reset}
         await handleCloudCommand(process.argv.slice(3));
         return;
     }
+    // Handle "review-copilot" subcommand (backwards-compatible Local AI Explainer command)
+    if (process.argv[2] === 'review-copilot') {
+        const { handleReviewCopilotCommand } = await import('./cli/review-copilot.js');
+        await handleReviewCopilotCommand(process.argv.slice(3), parsedArgs.dbPath);
+        return;
+    }
     // Handle "status" subcommand
     if (process.argv[2] === 'status') {
         const { handleStatusCommand } = await import('./setup/status.js');
@@ -954,7 +963,7 @@ ${bold}DOCS${reset}
     const knownCommands = new Set([
         'doctor', 'quickstart', 'setup', 'install', 'migrate', 'uninstall', 'hook', 'update',
         'openclaw', 'clawdbot', 'copilot', 'codex', 'service', 'config', 'status',
-        'graph', 'license', 'licence', 'audit', 'iron-dome', 'scan', 'cloud',
+        'graph', 'license', 'licence', 'audit', 'iron-dome', 'scan', 'cloud', 'review-copilot',
         'scan-skill', 'scan-skills', 'dashboard', 'api', 'worker', 'stats', 'cortex', 'consolidate', 'xray', 'xray-preinstall',
     ]);
     const arg = process.argv[2];

package/dist/lib.d.ts

@@ -11,6 +11,13 @@
 export { runDefencePipeline, runDefencePipelineWithVerify, DEFAULT_DEFENCE_CONFIG, scoreSource, filterByTrust, analyzeFirewall, classifySensitivity, redactContent, redactForDisplay, analyzeFragmentation, storeFragmentationData, scanForCredentials, redactCredentials, DEFAULT_CREDENTIAL_CONFIG, logAudit, queryAuditLogs, getAuditStats, getDefenceMode, setDefenceMode, isConfigTampered, getCloudConfig, setCloudConfig, clearCloudConfigCache, getOpenClawAutoMemory, setOpenClawAutoMemory, getOpenClawMemoryConfig, setOpenClawMemoryConfig, getVerifyConfig, setVerifyConfig, syncToCloud, syncQuarantineToCloud, submitVerification, pollVerification, getDeviceId, getDeviceName, } from './defence/index.js';
 export type { DefenceConfig, DefencePipelineResultWithVerify, DefenceSource, SensitivityLevel, FirewallResult, VerifyResult, VerifyThreat, } from './defence/types.js';
 export type { VerifyConfig } from './cloud/config.js';
+export { getReviewCopilotConfig, setReviewCopilotConfig } from './cloud/config.js';
+export { reviewQuarantineItem, groupReviewAnnotations, groupSimilarItems, parseReviewAnnotation, validateReviewAnnotation, fallbackAnnotation, } from './defence/judge/index.js';
+export { annotateQuarantineItem, annotatePendingQuarantineItems, getAnnotationForItem, } from './defence/judge/annotate.js';
+export type { ReviewCopilotConfig } from './cloud/config.js';
+export type { ReviewAnnotation, ReviewBatch, ReviewCopilotCategory, ReviewCopilotSuggestion, ReviewQuarantineItem, AnnotationRunResult, } from './defence/judge/index.js';
+export { explainLocalAiSubject, buildLocalAiExplainPrompt, parseLocalAiExplanation, fallbackLocalAiExplanation, } from './defence/explainer/index.js';
+export type { LocalAiEvidence, LocalAiExplanation, LocalAiExplainSubject, LocalAiExplainSubjectKind, } from './defence/explainer/index.js';
 export { scanToolResponse, shouldScanToolResponse } from './defence/tool-response-scanner.js';
 export type { ToolResponseScanResult } from './defence/types.js';
 export { activateIronDome, deactivateIronDome, getIronDomeStatus, isChannelTrusted, isActionAllowed, scanForInjection, checkPII, handleKillPhrase, IRON_DOME_PROFILES, DEFAULT_IRON_DOME_CONFIG, } from './defence/iron-dome/index.js';
@@ -32,8 +39,9 @@ export { extractFromMemory } from './graph/extract.js';
 export { processExtractionResult, mergeEntities } from './graph/resolve.js';
 export { backfillGraph } from './graph/backfill.js';
 export { initDatabase } from './database/init.js';
-export { scanMemories, scanMcpConfigs, scanEnvFiles, scanRulesFiles } from './audit/index.js';
+export { discoverMemoryFiles, isShieldCortexOwnMemoryPath, scanMemories, scanMemoryFilesDetailed, scanMcpConfigs, scanEnvFiles, scanRulesFiles, } from './audit/index.js';
 export { formatTerminalReport, formatMarkdownReport, formatJsonReport } from './audit/index.js';
+export type { DetailedMemoryFileScanResult, DiscoveredMemoryFile, MemoryFileDiscoveryOptions, MemoryFileEvidence, MemoryFileRisk, MemoryFileScanRecord, MemoryFileScanSummary, } from './audit/index.js';
 export type { AuditFinding, AuditSeverity } from './audit/types.js';
 export { getLicense, getLicenseTier, isFeatureEnabled, requireFeature, listFeatures, FeatureGatedError, verifyLicenseKey, TIER_RANK, } from './license/index.js';
 export type { LicenseTier, LicenseInfo, GatedFeature, } from './license/index.js';

package/dist/lib.js

@@ -10,6 +10,12 @@
  */
 // ── Defence ────────────────────────────────────────────────
 export { runDefencePipeline, runDefencePipelineWithVerify, DEFAULT_DEFENCE_CONFIG, scoreSource, filterByTrust, analyzeFirewall, classifySensitivity, redactContent, redactForDisplay, analyzeFragmentation, storeFragmentationData, scanForCredentials, redactCredentials, DEFAULT_CREDENTIAL_CONFIG, logAudit, queryAuditLogs, getAuditStats, getDefenceMode, setDefenceMode, isConfigTampered, getCloudConfig, setCloudConfig, clearCloudConfigCache, getOpenClawAutoMemory, setOpenClawAutoMemory, getOpenClawMemoryConfig, setOpenClawMemoryConfig, getVerifyConfig, setVerifyConfig, syncToCloud, syncQuarantineToCloud, submitVerification, pollVerification, getDeviceId, getDeviceName, } from './defence/index.js';
+// ── Review Copilot ───────────────────────────────────────
+export { getReviewCopilotConfig, setReviewCopilotConfig } from './cloud/config.js';
+export { reviewQuarantineItem, groupReviewAnnotations, groupSimilarItems, parseReviewAnnotation, validateReviewAnnotation, fallbackAnnotation, } from './defence/judge/index.js';
+export { annotateQuarantineItem, annotatePendingQuarantineItems, getAnnotationForItem, } from './defence/judge/annotate.js';
+// ── Local AI Explainer ────────────────────────────────────
+export { explainLocalAiSubject, buildLocalAiExplainPrompt, parseLocalAiExplanation, fallbackLocalAiExplanation, } from './defence/explainer/index.js';
 // ── Tool Response Scanner ─────────────────────────────────
 export { scanToolResponse, shouldScanToolResponse } from './defence/tool-response-scanner.js';
 // ── Iron Dome ─────────────────────────────────────────────
@@ -36,7 +42,7 @@ export { backfillGraph } from './graph/backfill.js';
 // ── Database ───────────────────────────────────────────────
 export { initDatabase } from './database/init.js';
 // ── Audit ──────────────────────────────────────────────────
-export { scanMemories, scanMcpConfigs, scanEnvFiles, scanRulesFiles } from './audit/index.js';
+export { discoverMemoryFiles, isShieldCortexOwnMemoryPath, scanMemories, scanMemoryFilesDetailed, scanMcpConfigs, scanEnvFiles, scanRulesFiles, } from './audit/index.js';
 export { formatTerminalReport, formatMarkdownReport, formatJsonReport } from './audit/index.js';
 // ── License ────────────────────────────────────────────────
 export { getLicense, getLicenseTier, isFeatureEnabled, requireFeature, listFeatures, FeatureGatedError, verifyLicenseKey, TIER_RANK, } from './license/index.js';

package/dist/license/gate.d.ts

@@ -6,7 +6,7 @@
  *   isFeatureEnabled('cloud_sync');               // returns boolean (soft check)
  */
 import { type LicenseTier } from './keys.js';
-export type GatedFeature = 'custom_injection_patterns' | 'custom_iron_dome_policies' | 'custom_firewall_rules' | 'audit_export' | 'skill_scanner_deep' | 'cloud_sync' | 'team_management' | 'shared_patterns' | 'cortex_learning' | 'deps_quarantine' | 'deps_clean' | 'deps_auto_protect' | 'deps_global_scan' | 'memory_types' | 'memory_scopes' | 'dream_mode' | 'llm_reranking' | 'positive_feedback' | 'xray_deep';
+export type GatedFeature = 'custom_injection_patterns' | 'custom_iron_dome_policies' | 'custom_firewall_rules' | 'audit_export' | 'skill_scanner_deep' | 'cloud_sync' | 'team_management' | 'shared_patterns' | 'cortex_learning' | 'deps_quarantine' | 'deps_clean' | 'deps_auto_protect' | 'deps_global_scan' | 'memory_types' | 'memory_scopes' | 'dream_mode' | 'llm_reranking' | 'positive_feedback' | 'local_ai_explainer' | 'memory_file_scan' | 'review_copilot' | 'xray_deep';
 export declare class FeatureGatedError extends Error {
     feature: GatedFeature;
     requiredTier: LicenseTier;

package/dist/license/gate.js

@@ -26,6 +26,9 @@ const FEATURE_TIERS = {
     dream_mode: 'pro',
     llm_reranking: 'pro',
     positive_feedback: 'pro',
+    local_ai_explainer: 'pro',
+    memory_file_scan: 'pro',
+    review_copilot: 'pro',
     xray_deep: 'pro',
 };
 const FEATURE_DESCRIPTIONS = {
@@ -47,6 +50,9 @@ const FEATURE_DESCRIPTIONS = {
     dream_mode: 'Background memory consolidation — merge duplicates, archive stale, detect contradictions.',
     llm_reranking: 'LLM-powered memory reranking for precision recall.',
     positive_feedback: 'Capture what worked, not just what failed — learn from success.',
+    local_ai_explainer: 'Local AI explanations for memories, X-Ray findings, and quarantine review without sending content to the cloud.',
+    memory_file_scan: 'Scan persistent agent memory files for poisoned instructions and credential leaks.',
+    review_copilot: 'Local AI quarantine review annotations, grouping, and batch triage.',
     xray_deep: 'Deep X-Ray scanning: npm registry analysis, binary file inspection, dependency graph risk, and AI-directive detection in metadata and filenames.',
 };
 // ── Error class ──────────────────────────────────────────

package/dist/setup/openclaw.d.ts

@@ -20,6 +20,22 @@ export declare function isDockerEnvironment(): boolean;
  * Creates the hooks/ subdirectory if the parent config dir exists.
  */
 export declare function findAllHooksDirs(): string[];
+/**
+ * Pure idempotency check for the openclaw.json plugin registration.
+ *
+ * Returns true if the config needs to be rewritten — i.e. ANY of the
+ * load-bearing fields differ from the desired state. Returns false when
+ * the config already matches and a re-install would otherwise produce a
+ * no-op write (which churned the gateway's config-watcher every
+ * `shieldcortex openclaw install` pre-v4.12.11).
+ *
+ * Intentionally treats `installedAt` as transient — only differing on
+ * that field does NOT force a write, otherwise this function would
+ * always trip on its own previous timestamp.
+ *
+ * Exported for direct unit testing without booting the full installer.
+ */
+export declare function pluginInstallNeedsWrite(config: unknown, pluginId: string, installDir: string, version: string): boolean;
 /**
  * Install options for `shieldcortex openclaw install`.
  */

package/dist/setup/openclaw.js

@@ -255,9 +255,19 @@ function detectLegacyHookVariants(hooksDir) {
 }
 // ==================== Cleanup Legacy Plugin ====================
 /**
- * Remove the shieldcortex-realtime plugin entry from openclaw.json
- * if it exists. Earlier versions incorrectly registered a plugin
- * that caused OpenClaw config validation errors.
+ * Remove genuinely-legacy plugin registration shapes from openclaw.json.
+ *
+ * The only known legacy shape that caused OpenClaw config validation
+ * errors was `plugins.allow` entries containing full file paths to the
+ * plugin (pre-v2026.3 format) rather than the bare plugin id. This
+ * function strips those.
+ *
+ * v4.12.11 — used to also unconditionally delete
+ * `plugins.entries['shieldcortex-realtime']` here. That key holds the
+ * CURRENT-format registration (`{ enabled: true }`) that `trustLocalPlugin`
+ * writes; deleting it on every install meant `trustLocalPlugin`'s
+ * idempotency check always saw a missing entry and re-wrote the file —
+ * defeating the v4.12.11 idempotency fix entirely. Removed.
  */
 function cleanupLegacyPlugin() {
     const home = resolveUserHome();
@@ -268,13 +278,6 @@ function cleanupLegacyPlugin() {
         const raw = fs.readFileSync(configPath, 'utf-8');
         const config = JSON.parse(raw);
         let changed = false;
-        // Remove legacy entries (old format before native installs)
-        if (config.plugins?.entries?.['shieldcortex-realtime']) {
-            delete config.plugins.entries['shieldcortex-realtime'];
-            if (Object.keys(config.plugins.entries).length === 0)
-                delete config.plugins.entries;
-            changed = true;
-        }
         // Remove stale full-path entries from plugins.allow
         // (pre-v2026.3 format used raw file paths instead of plugin IDs)
         if (Array.isArray(config.plugins?.allow)) {
@@ -297,6 +300,45 @@ function cleanupLegacyPlugin() {
 function openClawConfigPath() {
     return path.join(resolveUserHome(), '.openclaw', 'openclaw.json');
 }
+/**
+ * Pure idempotency check for the openclaw.json plugin registration.
+ *
+ * Returns true if the config needs to be rewritten — i.e. ANY of the
+ * load-bearing fields differ from the desired state. Returns false when
+ * the config already matches and a re-install would otherwise produce a
+ * no-op write (which churned the gateway's config-watcher every
+ * `shieldcortex openclaw install` pre-v4.12.11).
+ *
+ * Intentionally treats `installedAt` as transient — only differing on
+ * that field does NOT force a write, otherwise this function would
+ * always trip on its own previous timestamp.
+ *
+ * Exported for direct unit testing without booting the full installer.
+ */
+export function pluginInstallNeedsWrite(config, pluginId, installDir, version) {
+    if (!config || typeof config !== 'object')
+        return true;
+    const c = config;
+    if (!c.plugins || typeof c.plugins !== 'object')
+        return true;
+    const plugins = c.plugins;
+    const install = plugins.installs?.[pluginId];
+    if (!install || typeof install !== 'object')
+        return true;
+    const i = install;
+    if (i.source !== 'path' || i.installPath !== installDir || i.version !== version)
+        return true;
+    const allow = Array.isArray(plugins.allow) ? plugins.allow : [];
+    if (!allow.includes(pluginId))
+        return true;
+    const hasStale = allow.some((e) => typeof e === 'string' && e !== pluginId && e.includes(pluginId));
+    if (hasStale)
+        return true;
+    const entries = plugins.entries ?? {};
+    if (!entries[pluginId])
+        return true;
+    return false;
+}
 function trustLocalPlugin(installDir, version) {
     const configPath = openClawConfigPath();
     const configDir = path.dirname(configPath);
@@ -307,6 +349,13 @@ function trustLocalPlugin(installDir, version) {
         }
         const raw = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf-8') : '{}';
         const config = JSON.parse(raw);
+        // Idempotency: skip the write if everything is already correct.
+        // This stops `shieldcortex openclaw install` (and postinstall.mjs's
+        // auto-refresh) from bumping a fresh installedAt timestamp on every
+        // invocation when nothing has actually changed.
+        if (!pluginInstallNeedsWrite(config, pluginId, installDir, version)) {
+            return true;
+        }
         const plugins = typeof config.plugins === 'object' && config.plugins !== null ? config.plugins : {};
         const allow = Array.isArray(plugins.allow)
             ? (plugins.allow ?? [])
@@ -316,15 +365,18 @@ function trustLocalPlugin(installDir, version) {
         if (!cleaned.includes(pluginId)) {
             cleaned.push(pluginId);
         }
-        // Add installs entry so OpenClaw recognises the plugin
+        // Preserve the existing installedAt if present — we only land here
+        // when something genuine changed, but if the existing entry's path
+        // was wrong (say) we don't need to invent a new install timestamp.
         const installs = typeof plugins.installs === 'object' && plugins.installs !== null
             ? plugins.installs
             : {};
+        const existingInstall = installs[pluginId];
         installs[pluginId] = {
             source: 'path',
             installPath: installDir,
             version,
-            installedAt: new Date().toISOString(),
+            installedAt: existingInstall?.installedAt ?? new Date().toISOString(),
         };
         // Add entries to enable the plugin
         const entries = typeof plugins.entries === 'object' && plugins.entries !== null
@@ -598,17 +650,28 @@ function uninstallPlugin() {
             const raw = fs.readFileSync(configPath, 'utf-8');
             const config = JSON.parse(raw);
             const pluginId = PLUGIN_DIR_NAME;
-            if (Array.isArray(config.plugins?.allow)) {
-                // Remove both old file-path entries and new short-name entries
-                config.plugins.allow = config.plugins.allow.filter((entry) => !entry.includes(pluginId));
-            }
-            if (config.plugins?.installs?.[pluginId]) {
-                delete config.plugins.installs[pluginId];
-            }
-            if (config.plugins?.entries?.[pluginId]) {
-                delete config.plugins.entries[pluginId];
+            // Idempotency: only write the config if there's actually something
+            // to remove. Pre-v4.12.11 this rewrote openclaw.json every time
+            // even when no SC entries existed (e.g. a re-run of `uninstall
+            // --deep` after a previous successful uninstall).
+            const allowHasIt = Array.isArray(config.plugins?.allow)
+                && config.plugins.allow.some((e) => typeof e === 'string' && e.includes(pluginId));
+            const installsHasIt = !!config.plugins?.installs?.[pluginId];
+            const entriesHasIt = !!config.plugins?.entries?.[pluginId];
+            const needsWrite = allowHasIt || installsHasIt || entriesHasIt;
+            if (needsWrite) {
+                if (Array.isArray(config.plugins?.allow)) {
+                    // Remove both old file-path entries and new short-name entries
+                    config.plugins.allow = config.plugins.allow.filter((entry) => !entry.includes(pluginId));
+                }
+                if (config.plugins?.installs?.[pluginId]) {
+                    delete config.plugins.installs[pluginId];
+                }
+                if (config.plugins?.entries?.[pluginId]) {
+                    delete config.plugins.entries[pluginId];
+                }
+                fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
             }
-            fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
         }
         fs.rmSync(destDir, { recursive: true });
         console.log(`Removed real-time plugin from ${destDir}`);

package/dist/setup/uninstall.d.ts

@@ -13,6 +13,20 @@
 export declare function requireConfirmation(action: string): Promise<boolean>;
 export declare function removeHooks(): void;
 export declare function removeClaudeMdBlock(): void;
+/**
+ * Remove the ShieldCortex MCP server entry from ~/.claude.json.
+ *
+ * Pre-v4.12.11 uninstall left this entry in place. Every Claude Code
+ * session then tried to spawn the now-missing shieldcortex binary, and
+ * the failure cascaded into fleet-wide context loss — confirmed by a
+ * peer agent (Edith) who saw an affected host stabilise within minutes
+ * after manually removing the entry.
+ *
+ * Safe: only deletes entries that look ShieldCortex-owned. No-op if the
+ * file is missing, JSON is malformed, the entry is absent, or the entry
+ * belongs to another MCP server.
+ */
+export declare function removeMcpEntry(): void;
 export declare function uninstallSetup(): Promise<void>;
 export declare function uninstallAll(options?: {
     keepLogs?: boolean;

package/dist/setup/uninstall.js

@@ -128,6 +128,65 @@ export function removeClaudeMdBlock() {
     fs.writeFileSync(CLAUDE_MD_PATH, newContent, 'utf-8');
     console.log('CLAUDE.md: removed ShieldCortex memory instructions block.');
 }
+/**
+ * Ownership check: an mcpServers entry "looks like ShieldCortex" if its
+ * command path or args contain a shieldcortex / shield-cortex token.
+ * `mcpServers.memory` is a generic key — the official upstream
+ * `@modelcontextprotocol/server-memory` registers under the same name —
+ * so we MUST verify ownership before deletion or risk clobbering an
+ * unrelated MCP server the user installed.
+ */
+function looksLikeShieldcortex(entry) {
+    if (!entry || typeof entry !== 'object')
+        return false;
+    const e = entry;
+    const tokens = [];
+    if (typeof e.command === 'string')
+        tokens.push(e.command);
+    if (Array.isArray(e.args))
+        for (const a of e.args)
+            if (typeof a === 'string')
+                tokens.push(a);
+    return tokens.some((t) => /shield[-]?cortex/i.test(t));
+}
+/**
+ * Remove the ShieldCortex MCP server entry from ~/.claude.json.
+ *
+ * Pre-v4.12.11 uninstall left this entry in place. Every Claude Code
+ * session then tried to spawn the now-missing shieldcortex binary, and
+ * the failure cascaded into fleet-wide context loss — confirmed by a
+ * peer agent (Edith) who saw an affected host stabilise within minutes
+ * after manually removing the entry.
+ *
+ * Safe: only deletes entries that look ShieldCortex-owned. No-op if the
+ * file is missing, JSON is malformed, the entry is absent, or the entry
+ * belongs to another MCP server.
+ */
+export function removeMcpEntry() {
+    const mcpPath = path.join(os.homedir(), '.claude.json');
+    if (!fs.existsSync(mcpPath))
+        return;
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(mcpPath, 'utf-8'));
+    }
+    catch (err) {
+        console.warn(`MCP: could not parse ~/.claude.json — leaving it untouched: ${err.message}`);
+        return;
+    }
+    const entry = config?.mcpServers?.memory;
+    if (!entry) {
+        console.log('MCP: no shieldcortex entry found in ~/.claude.json.');
+        return;
+    }
+    if (!looksLikeShieldcortex(entry)) {
+        console.warn('MCP: ~/.claude.json mcpServers.memory does not look ShieldCortex-owned — leaving it alone.');
+        return;
+    }
+    delete config.mcpServers.memory;
+    fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    console.log('MCP: removed shieldcortex entry from ~/.claude.json.');
+}
 export async function uninstallSetup() {
     if (blockAgentUninstall())
         return;
@@ -149,6 +208,12 @@ export async function uninstallSetup() {
     catch (err) {
         console.error(`Failed to remove CLAUDE.md block: ${err.message}`);
     }
+    try {
+        removeMcpEntry();
+    }
+    catch (err) {
+        console.error(`Failed to remove MCP entry: ${err.message}`);
+    }
     console.log('\nSetup removal complete.');
 }
 export async function uninstallAll(options) {
@@ -191,7 +256,17 @@ 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
+    // 5. Remove the MCP entry from ~/.claude.json. This is THE
+    //    pre-v4.12.11 context-killer — every Claude Code session loaded
+    //    the orphaned entry, tried to spawn the missing binary, and the
+    //    failure cascaded into context loss across the fleet.
+    try {
+        removeMcpEntry();
+    }
+    catch (err) {
+        console.error(`Failed to remove MCP entry: ${err.message}`);
+    }
+    // 6. 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shieldcortex",
-  "version": "4.12.10",
+  "version": "4.12.12",
   "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",
@@ -43,6 +43,7 @@
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
     "build:ts": "node -e \"fs.rmSync('dist', { recursive: true, force: true }); fs.rmSync('plugins/openclaw/dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && tsc -p tsconfig.openclaw-plugin.json && cp plugins/openclaw/openclaw.plugin.json plugins/openclaw/dist/ && cp src/database/schema.sql dist/database/",
+    "postbuild:ts": "node scripts/ensure-bin-executable.mjs",
     "bootstrap:dashboard": "node -e \"if (!require('fs').existsSync('dashboard/node_modules')) { process.exit(1); }\" || (cd dashboard && npm ci --no-audit --no-fund)",
     "build:dashboard": "npm run bootstrap:dashboard && cd dashboard && npm run build && (cp -r .next/static .next/standalone/dashboard/.next/ 2>/dev/null || true) && (cp -r public .next/standalone/dashboard/ 2>/dev/null || true) && cd .. && node scripts/prune-dashboard-standalone.mjs",
     "build": "npm run build:ts && npm run build:dashboard",
@@ -57,6 +58,7 @@
     "test:watch": "node scripts/run-jest.mjs --watch",
     "test:coverage": "node scripts/run-jest.mjs --coverage",
     "audit:security": "npm audit --audit-level=moderate",
+    "prepack": "node scripts/ensure-bin-executable.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -139,6 +141,7 @@
     "hooks/openclaw",
     "plugins/openclaw/dist",
     "scripts/postinstall.mjs",
+    "scripts/ensure-bin-executable.mjs",
     "scripts/pre-compact-hook.mjs",
     "scripts/run-jest.mjs",
     "scripts/session-end-hook.mjs",

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

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.12.10",
+  "version": "4.12.12",
   "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/ensure-bin-executable.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { chmodSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+
+const entrypoint = join(process.cwd(), 'dist', 'index.js');
+
+if (!existsSync(entrypoint)) {
+  console.error('[ensure-bin-executable] Missing dist/index.js. Run npm run build:ts first.');
+  process.exit(1);
+}
+
+const currentMode = statSync(entrypoint).mode;
+const executableMode = currentMode | 0o755;
+
+chmodSync(entrypoint, executableMode);
+