shieldcortex 4.31.2 → 4.32.0

package/dist/defence/tool-response-scanner.d.ts

@@ -1,11 +1,25 @@
 /**
  * Tool Response Scanner
  *
- * Lightweight defence scanner for MCP tool outputs (read-path).
- * Runs injection detection + credential leak scanning (2 of 6 layers).
- * Skips fragmentation, sensitivity, and trust scoring (write-path concerns).
+ * Defence scanner for MCP tool outputs (read-path). Tool output is the #1 MCP
+ * attack surface, so the read path shares the WRITE-path detection surface
+ * instead of running a thinner pattern set:
  *
- * Advisory by default: logs threats but never blocks tool responses.
+ *   - scanForInjection   — Iron Dome regex set (named-pattern reporting)
+ *   - detectInstructions — write-path instruction detector; folds cross-script
+ *                          homoglyphs and scans in windows (catches `ignorе …`)
+ *   - detectEncoding     — write-path encoding detector; decodes base64/hex/url
+ *                          blobs so a BARE blob that decodes to an injection is
+ *                          re-scanned on the plaintext (decode-and-rescan)
+ *   - detectMarkdownImageExfil — markdown image whose URL smuggles data out
+ *   - scanForCredentials — credential leak scanning (retained)
+ *
+ * It deliberately does NOT pull in the write-path's trust scoring, anomaly,
+ * privilege, fragmentation or sensitivity layers — those are write concerns.
+ *
+ * Advisory by default: logs threats but never blocks tool responses. Only the
+ * audit/event firewall_result reflects enforce mode; the scan itself never hard
+ * blocks tool execution.
  */
 import type { ToolResponseScanResult } from './types.js';
 /**
@@ -16,7 +30,9 @@ export declare function shouldScanToolResponse(toolName: string): boolean;
 /**
  * Scan a tool response for threats.
  *
- * Runs injection scanning (40+ patterns) + credential leak detection (25+ providers).
+ * Shares the write-path detection surface: Iron Dome injection patterns,
+ * instruction detection (with homoglyph folding + windowed scanning), encoding
+ * decode-and-rescan, markdown-image exfiltration, and credential leak detection.
  * In advisory mode, threats are logged but the response is never blocked.
  */
 export declare function scanToolResponse(toolName: string, content: string, mode?: 'advisory' | 'enforce'): ToolResponseScanResult;

package/dist/defence/tool-response-scanner.js

@@ -1,17 +1,41 @@
 /**
  * Tool Response Scanner
  *
- * Lightweight defence scanner for MCP tool outputs (read-path).
- * Runs injection detection + credential leak scanning (2 of 6 layers).
- * Skips fragmentation, sensitivity, and trust scoring (write-path concerns).
+ * Defence scanner for MCP tool outputs (read-path). Tool output is the #1 MCP
+ * attack surface, so the read path shares the WRITE-path detection surface
+ * instead of running a thinner pattern set:
  *
- * Advisory by default: logs threats but never blocks tool responses.
+ *   - scanForInjection   — Iron Dome regex set (named-pattern reporting)
+ *   - detectInstructions — write-path instruction detector; folds cross-script
+ *                          homoglyphs and scans in windows (catches `ignorе …`)
+ *   - detectEncoding     — write-path encoding detector; decodes base64/hex/url
+ *                          blobs so a BARE blob that decodes to an injection is
+ *                          re-scanned on the plaintext (decode-and-rescan)
+ *   - detectMarkdownImageExfil — markdown image whose URL smuggles data out
+ *   - scanForCredentials — credential leak scanning (retained)
+ *
+ * It deliberately does NOT pull in the write-path's trust scoring, anomaly,
+ * privilege, fragmentation or sensitivity layers — those are write concerns.
+ *
+ * Advisory by default: logs threats but never blocks tool responses. Only the
+ * audit/event firewall_result reflects enforce mode; the scan itself never hard
+ * blocks tool execution.
  */
 import { scanForInjection } from './iron-dome/injection-scanner.js';
 import { scanForCredentials } from './credential-leak/index.js';
+import { detectInstructions } from './firewall/instruction-detector.js';
+import { detectEncoding } from './firewall/encoding-detector.js';
+import { detectMarkdownImageExfil } from './firewall/markdown-image-detector.js';
 import { logAudit } from './audit/logger.js';
 import { isDatabaseInitialized } from '../database/init.js';
 import { getToolResponseScanConfig } from '../cloud/config.js';
+import { persistEvent } from '../api/events.js';
+// ../api/events.js is imported statically. Safe at module-eval time: there is no
+// import cycle on this edge — events imports only an EventEmitter, getDatabase
+// and types, never back into this module — and it does no work at import (no
+// server/ws stack). persistEvent is only called inside scanToolResponse. The
+// try/catch below stays — dashboard event persistence is best-effort and must
+// never affect tool-response delivery.
 // Tools that return memory/knowledge content (worth scanning)
 const HIGH_RISK_TOOLS = new Set([
     'recall',
@@ -46,7 +70,9 @@ export function shouldScanToolResponse(toolName) {
 /**
  * Scan a tool response for threats.
  *
- * Runs injection scanning (40+ patterns) + credential leak detection (25+ providers).
+ * Shares the write-path detection surface: Iron Dome injection patterns,
+ * instruction detection (with homoglyph folding + windowed scanning), encoding
+ * decode-and-rescan, markdown-image exfiltration, and credential leak detection.
  * In advisory mode, threats are logged but the response is never blocked.
  */
 export function scanToolResponse(toolName, content, mode) {
@@ -66,28 +92,70 @@ export function scanToolResponse(toolName, content, mode) {
             auditId: -1,
         };
     }
-    // 1. Injection scan (Iron Dome patterns)
+    // 1. Injection scan (Iron Dome named patterns — drives the `injection` field
+    //    of the result and the human-readable summary).
     const injection = scanForInjection(content);
-    // 2. Credential leak scan
+    // 2. Write-path detectors (parity). detectInstructions folds homoglyphs and
+    //    scans in windows; detectEncoding decodes base64/hex/url blobs.
+    const instructions = detectInstructions(content);
+    const encoding = detectEncoding(content);
+    // 2b. Decode-and-rescan: re-run instruction + credential detection on each
+    //     decoded snippet so a BARE base64/hex blob that decodes to an injection
+    //     (the Iron Dome base64 rule only fires on literal framing words) is
+    //     caught on its plaintext. Reuses the write-path detectors — no
+    //     duplicated detection logic.
+    let decodedInjection = false;
+    let decodedCredentialLeak = false;
+    for (const snippet of encoding.decodedSnippets) {
+        if (!decodedInjection && detectInstructions(snippet).detected) {
+            decodedInjection = true;
+        }
+        if (!decodedCredentialLeak && scanForCredentials(snippet).leaked) {
+            decodedCredentialLeak = true;
+        }
+        if (decodedInjection && decodedCredentialLeak)
+            break;
+    }
+    // 3. Markdown-image exfiltration (rendered image URL smuggling data out).
+    const markdownImage = detectMarkdownImageExfil(content);
+    // 4. Credential leak scan (retained from the original 2-layer read path).
     const credentials = scanForCredentials(content);
-    // 3. Collect threat indicators
+    // 5. Collect threat indicators across every layer.
     const threatIndicators = [];
+    const pushIndicator = (indicator) => {
+        if (!threatIndicators.includes(indicator))
+            threatIndicators.push(indicator);
+    };
+    if (instructions.detected || decodedInjection) {
+        pushIndicator('instruction_injection');
+    }
+    if (encoding.detected) {
+        pushIndicator('encoding_obfuscation');
+    }
     if (!injection.clean) {
-        threatIndicators.push('instruction_injection');
+        pushIndicator('instruction_injection');
         const categories = new Set(injection.detections.map(d => d.category));
         if (categories.has('credential_extraction')) {
-            threatIndicators.push('credential_leak');
+            pushIndicator('credential_leak');
         }
         if (categories.has('encoding_trick')) {
-            threatIndicators.push('encoding_obfuscation');
+            pushIndicator('encoding_obfuscation');
         }
     }
-    if (credentials.leaked && !threatIndicators.includes('credential_leak')) {
-        threatIndicators.push('credential_leak');
+    if (markdownImage.detected) {
+        pushIndicator('external_url');
+    }
+    if (credentials.leaked || decodedCredentialLeak) {
+        pushIndicator('credential_leak');
     }
-    const clean = injection.clean && !credentials.leaked;
+    const clean = injection.clean &&
+        !instructions.detected &&
+        !encoding.detected &&
+        !decodedInjection &&
+        !markdownImage.detected &&
+        !credentials.leaked;
     const durationMs = Math.round(performance.now() - startTime);
-    // 4. Build summary
+    // 6. Build summary
     let summary;
     if (clean) {
         summary = `Tool response from "${toolName}" is clean (${durationMs}ms)`;
@@ -96,11 +164,33 @@ export function scanToolResponse(toolName, content, mode) {
         const parts = [];
         if (!injection.clean)
             parts.push(`injection: ${injection.summary}`);
+        if (instructions.detected)
+            parts.push(`instructions: ${instructions.patterns.join(', ')}`);
+        if (decodedInjection)
+            parts.push('decoded payload contains injection');
+        if (encoding.detected)
+            parts.push(`encoding: ${encoding.encodingTypes.join(', ')}`);
+        if (markdownImage.detected)
+            parts.push(`markdown-image exfil: ${markdownImage.urls.length} URL(s)`);
         if (credentials.leaked)
             parts.push(`credentials: ${credentials.findings.length} finding(s)`);
+        else if (decodedCredentialLeak)
+            parts.push('decoded payload contains credentials');
         summary = `THREAT in "${toolName}" response: ${parts.join('; ')} (${durationMs}ms)`;
     }
-    // 5. Audit log (threats only)
+    // 7. Anomaly score: CRITICAL Iron Dome risk pins to 1.0; any other detection
+    //    (homoglyph, decoded payload, markdown-image exfil, etc.) scores 0.7.
+    const anomalyScore = injection.riskLevel === 'CRITICAL' ? 1.0 : 0.7;
+    // Blocked patterns reported to the audit/dashboard — Iron Dome named patterns
+    // plus the parity detectors' own labels.
+    const blockedPatterns = [
+        ...injection.detections.map(d => d.pattern),
+        ...instructions.patterns,
+        ...encoding.encodingTypes,
+        ...(decodedInjection ? ['decoded_injection'] : []),
+        ...(markdownImage.detected ? ['markdown_image_exfil'] : []),
+    ];
+    // 8. Audit log (threats only)
     let auditId = -1;
     if (!clean && isDatabaseInitialized()) {
         try {
@@ -111,11 +201,11 @@ export function scanToolResponse(toolName, content, mode) {
                 source_type: 'tool_response',
                 source_identifier: toolName,
                 trust_score: 0.5,
-                sensitivity_level: credentials.leaked ? 'CONFIDENTIAL' : 'PUBLIC',
+                sensitivity_level: (credentials.leaked || decodedCredentialLeak) ? 'CONFIDENTIAL' : 'PUBLIC',
                 firewall_result: resolvedMode === 'enforce' ? 'BLOCK' : 'ALLOW',
-                anomaly_score: injection.clean ? 0 : (injection.riskLevel === 'CRITICAL' ? 1.0 : 0.7),
+                anomaly_score: anomalyScore,
                 threat_indicators: JSON.stringify(threatIndicators),
-                blocked_patterns: JSON.stringify(injection.detections.map(d => d.pattern)),
+                blocked_patterns: JSON.stringify(blockedPatterns),
                 reason: summary,
                 fragmentation_score: null,
                 pipeline_duration_ms: durationMs,
@@ -124,15 +214,14 @@ export function scanToolResponse(toolName, content, mode) {
         catch {
             // Audit logging must never affect tool response delivery
         }
-        // 6. Dashboard real-time event
+        // 9. Dashboard real-time event
         try {
-            const { persistEvent } = require('../api/events.js');
             persistEvent('defence_event', {
                 source_type: 'tool_response',
                 source_identifier: toolName,
                 firewall_result: resolvedMode === 'enforce' ? 'BLOCK' : 'ALLOW',
                 trust_score: 0.5,
-                anomaly_score: injection.clean ? 0 : 0.7,
+                anomaly_score: anomalyScore,
                 reason: summary,
                 threat_indicators: JSON.stringify(threatIndicators),
                 timestamp: new Date().toISOString(),

package/dist/defence/types.d.ts

@@ -6,7 +6,7 @@
  */
 export type SensitivityLevel = 'PUBLIC' | 'INTERNAL' | 'CONFIDENTIAL' | 'RESTRICTED';
 export type FirewallResult = 'ALLOW' | 'BLOCK' | 'QUARANTINE';
-export type ThreatIndicator = 'instruction_injection' | 'privilege_escalation' | 'encoding_obfuscation' | 'credential_leak' | 'external_url' | 'fragmented_payload' | 'restricted_content' | 'pipeline_error' | 'custom_rule' | 'custom_pattern' | 'builtin_rule';
+export type ThreatIndicator = 'instruction_injection' | 'privilege_escalation' | 'encoding_obfuscation' | 'credential_leak' | 'external_url' | 'fragmented_payload' | 'restricted_content' | 'pipeline_error' | 'semantic_similarity' | 'custom_rule' | 'custom_pattern' | 'builtin_rule';
 export interface DefenceSource {
     type: 'user' | 'cli' | 'hook' | 'email' | 'web' | 'agent' | 'file' | 'api' | 'tool_response';
     identifier: string;
@@ -92,6 +92,16 @@ export interface DefencePipelineResultWithVerify extends DefencePipelineResult {
         mode: 'advisory' | 'enforce';
         originalFirewallResult?: FirewallResult;
     };
+    /**
+     * Result of the async-path semantic-similarity layer (embedding vs curated
+     * attack corpus). Present only when the embedding model was available; absent
+     * when it degraded. For observability — the verdict escalation it may trigger
+     * is reflected in `firewall`.
+     */
+    semanticSimilarity?: {
+        maxSimilarity: number;
+        matchedPhrase?: string;
+    };
 }
 export interface QuarantineEntry {
     id: number;

package/dist/index.d.ts

@@ -63,4 +63,33 @@
  *   shieldcortex uninstall --confirm     # Full uninstall (non-interactive)
  *   shieldcortex uninstall --keep-logs   # Full uninstall but keep log files
  */
+type ServerMode = 'mcp' | 'api' | 'both' | 'dashboard' | 'worker';
+/**
+ * Should the interactive trial/stats banner print for this invocation?
+ *
+ * It must print for normal interactive CLI commands (status, scan, doctor,
+ * audit, setup, …) but NEVER for:
+ *   - the MCP stdio server path (bare `shieldcortex`, `shieldcortex --db x`,
+ *     or `shieldcortex --mode mcp`) — stdout there is the JSON-RPC channel and
+ *     any banner bytes corrupt the protocol;
+ *   - the per-prompt `hook` path (dispatched + returned before this is reached).
+ *
+ * The previous guard was `argv[2] && mode !== 'mcp'`. That was broken because
+ * `parseArgs()` defaults `mode` to `'mcp'` for EVERY command except the few
+ * server modes (dashboard/api/worker/--mode) — so `status`, `scan`, `doctor`,
+ * `audit` etc. all kept `mode === 'mcp'` and were silently excluded, and the
+ * banner never showed for any normal command (Phase 11 reordered this block but
+ * left the faulty condition).
+ *
+ * The reliable discriminator is a POSITIONAL command word: the MCP stdio launch
+ * is only ever reached with no positional command (flags only). So we show the
+ * banner when either (a) there's a positional first arg that isn't a flag, or
+ * (b) a non-mcp server mode was selected. `mcp` as an explicit positional
+ * subcommand IS an interactive CLI command (the MCP-config scanner) — it parses
+ * to mode 'mcp' but is not the stdio server, and prints normal stdout, so it's
+ * fine for it to show the banner.
+ *
+ * Exported for unit testing.
+ */
+export declare function shouldShowInteractiveBanner(argv: string[], mode: ServerMode): boolean;
 export * from './lib.js';

package/dist/index.js

@@ -69,18 +69,14 @@ import { fileURLToPath } from 'url';
 import http from 'http';
 import path from 'path';
 import fs from 'fs';
-import { createServer } from './server.js';
-import { startVisualizationServer } from './api/visualization-server.js';
-import { handleServiceCommand } from './service/install.js';
-import { setupClaudeMd } from './setup/claude-md.js';
-import { handleHookCommand } from './setup/hooks.js';
-import { handleOpenClawCommand } from './setup/openclaw.js';
-import { handleCopilotCommand } from './setup/copilot.js';
-import { handleCodexCommand } from './setup/codex.js';
 import { createRequire } from 'module';
 import { execSync } from 'child_process';
-import { disposeModel, preloadModel } from './embeddings/index.js';
-import { startDefaultWorker, stopDefaultWorker } from './worker/brain-worker.js';
+// Heavy modules (MCP server, visualization API + express/cors/ws, embedding
+// model, brain worker, installer handlers) are loaded lazily via `await import`
+// inside the dispatch branch that needs them — keeping per-prompt hook startup
+// and lightweight CLI commands (--version, --help, status, doctor) fast. See
+// Phase 11 of the hardening plan: the `hook` path must not eagerly pull in any
+// of these, nor run the npx-staleness check.
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 /**
@@ -111,6 +107,50 @@ function checkVersionStaleness() {
 // Get the directory of this file for relative paths
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+/**
+ * Should the interactive trial/stats banner print for this invocation?
+ *
+ * It must print for normal interactive CLI commands (status, scan, doctor,
+ * audit, setup, …) but NEVER for:
+ *   - the MCP stdio server path (bare `shieldcortex`, `shieldcortex --db x`,
+ *     or `shieldcortex --mode mcp`) — stdout there is the JSON-RPC channel and
+ *     any banner bytes corrupt the protocol;
+ *   - the per-prompt `hook` path (dispatched + returned before this is reached).
+ *
+ * The previous guard was `argv[2] && mode !== 'mcp'`. That was broken because
+ * `parseArgs()` defaults `mode` to `'mcp'` for EVERY command except the few
+ * server modes (dashboard/api/worker/--mode) — so `status`, `scan`, `doctor`,
+ * `audit` etc. all kept `mode === 'mcp'` and were silently excluded, and the
+ * banner never showed for any normal command (Phase 11 reordered this block but
+ * left the faulty condition).
+ *
+ * The reliable discriminator is a POSITIONAL command word: the MCP stdio launch
+ * is only ever reached with no positional command (flags only). So we show the
+ * banner when either (a) there's a positional first arg that isn't a flag, or
+ * (b) a non-mcp server mode was selected. `mcp` as an explicit positional
+ * subcommand IS an interactive CLI command (the MCP-config scanner) — it parses
+ * to mode 'mcp' but is not the stdio server, and prints normal stdout, so it's
+ * fine for it to show the banner.
+ *
+ * Exported for unit testing.
+ */
+export function shouldShowInteractiveBanner(argv, mode) {
+    const first = argv[2];
+    if (!first)
+        return false; // bare invocation → MCP stdio server
+    // A positional (non-flag) first arg means a CLI subcommand was given.
+    const hasPositionalCommand = !first.startsWith('-');
+    if (hasPositionalCommand) {
+        // The only way a positional first arg lands on the stdio MCP server is the
+        // explicit server-mode words, which select a non-mcp mode anyway — so any
+        // positional command that resolves to mode 'mcp' is an interactive command
+        // (e.g. `mcp`, `scan`, `status`). Always show for positional commands.
+        return true;
+    }
+    // Flag-only invocation (e.g. `--db x`, `--mode mcp`, `--version`). Show only
+    // when a non-mcp server mode was explicitly requested (dashboard/api/worker).
+    return mode !== 'mcp';
+}
 // Parse command line arguments
 function parseArgs() {
     const args = process.argv.slice(2);
@@ -143,6 +183,11 @@ function parseArgs() {
  * Start MCP server for Claude Code integration
  */
 async function startMcpServer(dbPath) {
+    // Lazy-load heavy server/worker/embedding modules — only the actual MCP
+    // server path needs them, so they stay out of fast CLI/hook startup.
+    const { createServer } = await import('./server.js');
+    const { disposeModel, preloadModel } = await import('./embeddings/index.js');
+    const { startDefaultWorker, stopDefaultWorker } = await import('./worker/brain-worker.js');
     // Create the MCP server
     const server = createServer(dbPath);
     const transport = new StdioServerTransport();
@@ -387,7 +432,7 @@ function startDashboard() {
 }
 async function startWorkerMode(dbPath) {
     const { initDatabase } = await import('./database/init.js');
-    const { startDefaultWorker } = await import('./worker/brain-worker.js');
+    const { startDefaultWorker, stopDefaultWorker } = await import('./worker/brain-worker.js');
     initDatabase(dbPath);
     startDefaultWorker();
     // Resilience handlers (v4.14.8). Without these, any throw outside a tick's
@@ -459,12 +504,25 @@ async function isLocalDashboardRunning() {
  * Main entry point
  */
 async function main() {
+    // Dispatch the "hook" subcommand FIRST — before checkVersionStaleness() and
+    // the trial/stats banner. Hooks fire on every UserPromptSubmit, so this path
+    // must be as cheap as possible: no `npm ls -g` staleness probe (hooks were
+    // migrated to the global binary, where the warning is meaningless) and no
+    // trial/stats banners. handleHookCommand is imported lazily so the rest of
+    // the installer surface stays out of hook startup.
+    if (process.argv[2] === 'hook') {
+        const { handleHookCommand } = await import('./setup/hooks.js');
+        await handleHookCommand(process.argv[3] || '');
+        return;
+    }
     // Warn if npx is serving a stale cached version
     checkVersionStaleness();
     const parsedArgs = parseArgs();
     // ── Trial welcome / expiry warning ──────────────────────
-    // Only show for interactive CLI commands (not MCP server mode — stdout must stay clean for JSON-RPC)
-    if (process.argv[2] && parsedArgs.mode !== 'mcp') {
+    // Only show for interactive CLI commands. shouldShowInteractiveBanner gates
+    // out the MCP stdio server path (bare / --mode mcp / --db) where stdout is
+    // the JSON-RPC channel; the per-prompt `hook` path already returned above.
+    if (shouldShowInteractiveBanner(process.argv, parsedArgs.mode)) {
         try {
             const { existsSync } = await import('fs');
             const { join } = await import('path');
@@ -534,6 +592,8 @@ ${bold}USAGE${reset}
   shieldcortex [command] [options]
 
 ${bold}COMMANDS${reset}
+  ${cyan}remember${reset} <title>       Write a memory (via the defence pipeline)
+                        --content <text> or pipe via stdin; --importance, --tags
   ${cyan}scan${reset} <text>           Scan text through the defence pipeline
   ${cyan}scan-skill${reset} <path>     Scan an agent instruction file for threats
   ${cyan}scan-skills${reset}           Scan all installed skills/hooks
@@ -617,6 +677,7 @@ ${bold}DOCS${reset}
         }
         const stopHook = process.argv.includes('--with-stop-hook');
         const sessionEnd = process.argv.includes('--with-session-end');
+        const { setupClaudeMd } = await import('./setup/claude-md.js');
         await setupClaudeMd({ stopHook, sessionEnd });
         return;
     }
@@ -636,28 +697,30 @@ ${bold}DOCS${reset}
         });
         return;
     }
-    // Handle "hook" subcommand
-    if (process.argv[2] === 'hook') {
-        await handleHookCommand(process.argv[3] || '');
-        return;
-    }
+    // NOTE: the "hook" subcommand is dispatched at the very top of main(),
+    // before checkVersionStaleness() and the trial/stats banner — it must stay
+    // fast (fires on every UserPromptSubmit) and never run `npm ls -g`.
     // Handle "openclaw" subcommand (backward compat: "clawdbot" also accepted)
     if (process.argv[2] === 'openclaw' || process.argv[2] === 'clawdbot') {
+        const { handleOpenClawCommand } = await import('./setup/openclaw.js');
         await handleOpenClawCommand(process.argv[3] || '', process.argv.slice(4));
         return;
     }
     // Handle "copilot" subcommand (VS Code + Cursor MCP setup)
     if (process.argv[2] === 'copilot') {
+        const { handleCopilotCommand } = await import('./setup/copilot.js');
         await handleCopilotCommand(process.argv[3] || '');
         return;
     }
     // Handle "codex" subcommand (Codex CLI + VS Code MCP setup)
     if (process.argv[2] === 'codex') {
+        const { handleCodexCommand } = await import('./setup/codex.js');
         await handleCodexCommand(process.argv[3] || '');
         return;
     }
     // Handle "service" subcommand before normal mode parsing
     if (process.argv[2] === 'service') {
+        const { handleServiceCommand } = await import('./service/install.js');
         await handleServiceCommand(process.argv[3] || '', process.argv.slice(4));
         return;
     }
@@ -685,6 +748,14 @@ ${bold}DOCS${reset}
         await handleMemoriesCommand(process.argv.slice(3));
         return;
     }
+    // Handle "remember" subcommand (Phase 15c) — direct, non-hanging memory write
+    // through the same defence pipeline + project scoping the MCP tool uses.
+    // Content via --content or piped stdin; never blocks on a TTY (prints usage).
+    if (process.argv[2] === 'remember') {
+        const { handleRememberCommand } = await import('./cli/remember.js');
+        await handleRememberCommand(process.argv.slice(3));
+        return;
+    }
     // Handle "import-jsonl" subcommand — import Claude Code session transcripts
     // into session_events for dashboard replay.
     if (process.argv[2] === 'import-jsonl') {
@@ -747,6 +818,13 @@ ${bold}DOCS${reset}
         await handleAuditCommand(process.argv.slice(3));
         return;
     }
+    // Handle "mcp" subcommand (Phase 14) — scan configured MCP servers' tool
+    // descriptions for poisoning / line-jumping and rug-pull drift.
+    if (process.argv[2] === 'mcp') {
+        const { handleMcpCommand } = await import('./cli/mcp.js');
+        await handleMcpCommand(process.argv.slice(3));
+        return;
+    }
     // Handle "memory" subcommand (v4.25.0) — show / downvote / list a single
     // memory. Distinct from the existing "memories" (plural) command which
     // routes to migrate-legacy.
@@ -972,9 +1050,9 @@ ${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', 'review-copilot',
+        'graph', 'license', 'licence', 'audit', 'mcp', 'iron-dome', 'scan', 'cloud', 'review-copilot',
         'scan-skill', 'scan-skills', 'dashboard', 'api', 'worker', 'stats', 'cortex', 'consolidate', 'xray', 'xray-preinstall',
-        'memories', 'import-jsonl',
+        'memories', 'import-jsonl', 'remember',
     ]);
     const arg = process.argv[2];
     if (arg && !arg.startsWith('-') && !knownCommands.has(arg)) {
@@ -984,6 +1062,12 @@ ${bold}DOCS${reset}
     }
     const { dbPath, mode } = parsedArgs;
     let dashboardProcess = null;
+    // Lazy-load the visualization server (pulls in express + cors + ws) only on
+    // the modes that actually start it. mcp/worker never touch it.
+    const needsVizServer = mode === 'api' || mode === 'dashboard' || mode === 'both';
+    const startVisualizationServer = needsVizServer
+        ? (await import('./api/visualization-server.js')).startVisualizationServer
+        : undefined;
     if (mode === 'api') {
         // API mode only - for dashboard visualization
         if (await isLocalApiRunning()) {

package/dist/memory/consolidate.js

@@ -8,6 +8,7 @@
  * - Merges similar memories to reduce redundancy
  */
 import { getDatabase, withTransaction } from '../database/init.js';
+import { expireQuarantineItems } from '../defence/quarantine/auto-expire.js';
 import { DEFAULT_CONFIG, } from './types.js';
 import { getMemoriesByType, getRecentMemories, promoteMemory, deleteMemory, searchMemories, getMemoryStats, updateDecayScores, addMemory, rowToMemory, } from './store.js';
 import { processDecay, } from './decay.js';
@@ -895,7 +896,6 @@ export function fullCleanup(config = DEFAULT_CONFIG) {
     // Expire old quarantine items
     let quarantineExpired = 0;
     try {
-        const { expireQuarantineItems } = require('../defence/quarantine/auto-expire.js');
         quarantineExpired = expireQuarantineItems();
     }
     catch { /* defence module may not be available */ }

package/dist/memory/decay.js

@@ -150,7 +150,9 @@ export function processDecay(memories, config = DEFAULT_CONFIG) {
             console.log(`[expiry] Deleted ${deleted} expired memories (${kept} protected)`);
         }
     }
-    catch { /* silent */ }
+    catch (err) {
+        console.error('[expiry] applyExpiryRules failed:', err);
+    }
     return { toDelete, toPromote, updated };
 }
 /**

package/dist/memory/embedding.d.ts

@@ -27,8 +27,24 @@ export declare function cosineSimilarity(a: Float32Array, b: Float32Array): numb
 export declare function getCachedQueryEmbedding(query: string): Promise<Float32Array | null>;
 export declare function clearQueryEmbeddingCache(): void;
 /**
- * Embed the query, compute similarity against all memory embeddings,
- * return top K (default 10) sorted by score desc.
+ * Embed the query, compute similarity against the candidate memories' PERSISTED
+ * embeddings, return top K (default 10) sorted by score desc.
+ *
+ * Candidate embeddings are read from the canonical `memories.embedding` column —
+ * the same vector addMemory persists on write and vectorSearch scores against —
+ * in ONE batched `WHERE id IN (...)` query, decoded with the shared
+ * `decodeEmbeddingBlob`. This is a reuse, not a recompute: previously every
+ * candidate was routed through `getOrComputeEmbedding`, which checked a SEPARATE,
+ * perpetually-cold `memory_embeddings` cache and re-embedded each candidate's text
+ * through the worker on the (near-universal) miss — up to 200 sequential worker
+ * round-trips per cold recall, all redundant.
+ *
+ * Candidates that genuinely lack a persisted embedding (rare — writes populate it;
+ * only possible when the model was unavailable at write time, or for legacy rows)
+ * are skipped, not re-embedded: re-embedding here would reintroduce exactly the
+ * per-candidate worker storm this change removed, and `addMemory` already
+ * (re)populates the column out of band. They simply don't contribute to the
+ * vector-similarity fallback this turn; FTS and the next write still cover them.
  *
  * Non-throwing: returns empty array on failure.
  */