@drakon-systems/shieldcortex-realtime 4.47.23 → 4.47.25

package/dist/index.js

@@ -149,6 +149,7 @@ export function __resetConfigStateForTest() {
     _lastShieldConfigRef = null;
     _registered = false;
     _beforeToolCallRegistered = false;
+    _registrationError = null;
 }
 const INTERCEPT_SEVERITIES = ['low', 'medium', 'high', 'critical'];
 const INTERCEPT_ACTIONS = ['log', 'warn', 'require_approval'];
@@ -281,7 +282,14 @@ const PLUGIN_CONFIG_JSON_SCHEMA = {
     type: "object",
     additionalProperties: false,
     properties: {
-        enabled: { type: "boolean" },
+        // #115: accepted for schema/UI compatibility but not read — plugin
+        // enablement lives host-side at plugins.entries[id].enabled (see
+        // rootConfigWith() shape in extractPluginConfig), one level up from this
+        // nested `config` object. normaliseConfig() has never populated
+        // SCConfig.enabled (no such field exists); documented rather than
+        // removed so an existing config.enabled:true/false written by a host UI
+        // doesn't fail `additionalProperties:false` validation.
+        enabled: { type: "boolean", description: "Unused — plugin on/off is controlled by plugins.entries[id].enabled on the host, not this nested config value." },
         binaryPath: { type: "string" },
         cloudApiKey: { type: "string" },
         cloudBaseUrl: { type: "string" },
@@ -330,7 +338,16 @@ let _registered = false;
 // unattended Codex agents even a no-op registered hook changes how OpenClaw
 // resolves approvals).
 let _beforeToolCallRegistered = false;
-function normaliseConfig(raw) {
+// #134 §2: register() wraps its whole body in try/catch so a plugin failure
+// never blocks channel startup — correct, but it used to report the failure
+// with a bare console.warn (bypasses the gateway's structured log, so the
+// operator's only view of a dead security plugin is stdout no one reads) and
+// the /shieldcortex-status command lived INSIDE the same try block, so a
+// crash before that line meant the command never existed at all — the plugin
+// couldn't even honestly report its own death. Set here so the status handler
+// (registered unconditionally, before the risky init work) can read it.
+let _registrationError = null;
+function normaliseConfig(raw, dropped) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         return {};
     const value = raw;
@@ -364,59 +381,107 @@ function normaliseConfig(raw) {
     // ignored and DEFAULT_INTERCEPTOR_CONFIG re-armed the before_tool_call gate.
     // Validate-and-preserve every nested interceptor key the manifest schema
     // accepts; invalid values are dropped individually, valid siblings survive.
-    const interceptor = normaliseInterceptorConfig(value.interceptor);
+    // #115: `dropped` collects the exact key paths any invalid value was
+    // dropped from — undefined here (the configSchema.parse() public contract
+    // stays a single return value); applyPluginConfigOverride is the one
+    // caller that both has a logger AND matters for this (it ingests the
+    // openclaw.json plugin entry a human hand-edits — the Edith #112 incident's
+    // `enabled:"false"` was exactly this shape of typo).
+    const interceptor = normaliseInterceptorConfig(value.interceptor, dropped);
     if (interceptor)
         config.interceptor = interceptor;
     return config;
 }
-function normaliseSeverityMap(raw, allowed) {
+// #115: returns undefined (not {}) when nothing valid was found, matching
+// normaliseInterceptorConfig's contract below — an empty/all-invalid map
+// must read as "absent" so mergeConfigs/applyPluginConfigOverride treat it
+// as no override rather than a truthy-but-empty one.
+function normaliseSeverityMap(raw, allowed, dropped, pathPrefix) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         return undefined;
     const value = raw;
     const out = {};
     for (const severity of INTERCEPT_SEVERITIES) {
         const entry = value[severity];
+        if (entry === undefined)
+            continue; // absent, not invalid — nothing to warn about
         if (typeof entry === "string" && allowed.includes(entry)) {
             out[severity] = entry;
         }
+        else if (pathPrefix) {
+            dropped?.push(`${pathPrefix}.${severity}`);
+        }
     }
     return Object.keys(out).length > 0 ? out : undefined;
 }
-function normaliseInterceptorConfig(raw) {
+function normaliseInterceptorConfig(raw, dropped) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         return undefined;
     const value = raw;
     const out = {};
-    if (typeof value.enabled === "boolean")
-        out.enabled = value.enabled;
-    const severityActions = normaliseSeverityMap(value.severityActions, INTERCEPT_ACTIONS);
+    if (value.enabled !== undefined) {
+        if (typeof value.enabled === "boolean")
+            out.enabled = value.enabled;
+        else
+            dropped?.push("interceptor.enabled");
+    }
+    const severityActions = normaliseSeverityMap(value.severityActions, INTERCEPT_ACTIONS, dropped, "interceptor.severityActions");
     if (severityActions)
         out.severityActions = severityActions;
-    const failurePolicy = normaliseSeverityMap(value.failurePolicy, FAILURE_ACTIONS);
+    const failurePolicy = normaliseSeverityMap(value.failurePolicy, FAILURE_ACTIONS, dropped, "interceptor.failurePolicy");
     if (failurePolicy)
         out.failurePolicy = failurePolicy;
-    if (value.actionGuard && typeof value.actionGuard === "object" && !Array.isArray(value.actionGuard)) {
-        const rawGuard = value.actionGuard;
-        const guard = {};
-        if (typeof rawGuard.enabled === "boolean")
-            guard.enabled = rawGuard.enabled;
-        if (typeof rawGuard.enforce === "boolean")
-            guard.enforce = rawGuard.enforce;
-        if (typeof rawGuard.auditAllows === "boolean")
-            guard.auditAllows = rawGuard.auditAllows;
-        if (Array.isArray(rawGuard.autoApprove) && rawGuard.autoApprove.every((entry) => typeof entry === "string")) {
-            guard.autoApprove = rawGuard.autoApprove;
+    if (value.actionGuard !== undefined) {
+        if (value.actionGuard && typeof value.actionGuard === "object" && !Array.isArray(value.actionGuard)) {
+            const rawGuard = value.actionGuard;
+            const guard = {};
+            if (rawGuard.enabled !== undefined) {
+                if (typeof rawGuard.enabled === "boolean")
+                    guard.enabled = rawGuard.enabled;
+                else
+                    dropped?.push("interceptor.actionGuard.enabled");
+            }
+            if (rawGuard.enforce !== undefined) {
+                if (typeof rawGuard.enforce === "boolean")
+                    guard.enforce = rawGuard.enforce;
+                else
+                    dropped?.push("interceptor.actionGuard.enforce");
+            }
+            if (rawGuard.auditAllows !== undefined) {
+                if (typeof rawGuard.auditAllows === "boolean")
+                    guard.auditAllows = rawGuard.auditAllows;
+                else
+                    dropped?.push("interceptor.actionGuard.auditAllows");
+            }
+            if (rawGuard.autoApprove !== undefined) {
+                if (Array.isArray(rawGuard.autoApprove) && rawGuard.autoApprove.every((entry) => typeof entry === "string")) {
+                    // #115: defensive copy — downstream (initInterceptor's spread into
+                    // InterceptorConfig) is read-only today, but aliasing the caller's
+                    // array means a future in-place mutation of the host config object
+                    // would silently corrupt the normalised config too.
+                    guard.autoApprove = [...rawGuard.autoApprove];
+                }
+                else {
+                    dropped?.push("interceptor.actionGuard.autoApprove");
+                }
+            }
+            // Carried through untouched — normaliseBrokerConfig is the boundary, and
+            // splitting that job across two files is how one of the halves ends up
+            // being the lenient one.
+            if (rawGuard.broker && typeof rawGuard.broker === "object" && !Array.isArray(rawGuard.broker)) {
+                guard.broker = rawGuard.broker;
+            }
+            if (Object.keys(guard).length > 0)
+                out.actionGuard = guard;
         }
-        // Carried through untouched — normaliseBrokerConfig is the boundary, and
-        // splitting that job across two files is how one of the halves ends up
-        // being the lenient one.
-        if (rawGuard.broker && typeof rawGuard.broker === "object" && !Array.isArray(rawGuard.broker)) {
-            guard.broker = rawGuard.broker;
+        else {
+            dropped?.push("interceptor.actionGuard");
         }
-        if (Object.keys(guard).length > 0)
-            out.actionGuard = guard;
     }
-    return out;
+    // #115: empty/all-invalid normalises to undefined, not {} — {} is truthy
+    // and made applyPluginConfigOverride treat a no-op interceptor block as a
+    // real override, inconsistent with normaliseSeverityMap's own contract.
+    return Object.keys(out).length > 0 ? out : undefined;
 }
 /**
  * Merge two normalised configs (#112). Semantics:
@@ -448,13 +513,13 @@ function mergeConfigs(base, override) {
     }
     return merged;
 }
-function extractPluginConfig(rootConfig) {
+function extractPluginConfig(rootConfig, dropped) {
     if (!rootConfig || typeof rootConfig !== "object" || Array.isArray(rootConfig))
         return {};
     const entries = rootConfig.plugins?.entries;
     const pluginConfig = entries?.[PLUGIN_ID]?.config ??
         entries?.[PLUGIN_PACKAGE_NAME]?.config;
-    return normaliseConfig(pluginConfig);
+    return normaliseConfig(pluginConfig, dropped);
 }
 function applyPluginConfigOverride(api) {
     const runtimeConfigApi = api.runtime?.config;
@@ -463,7 +528,16 @@ function applyPluginConfigOverride(api) {
         : typeof runtimeConfigApi?.loadConfig === "function"
             ? runtimeConfigApi.loadConfig()
             : api.config;
-    const pluginConfig = extractPluginConfig(runtimeConfig);
+    // #115: name the exact dropped interceptor key(s) in a warn log. Edith's
+    // #112 incident (interceptor.enabled:"false", a string not a boolean) took
+    // longer to diagnose than it should have because the drop was silent —
+    // this is the one normaliseConfig() call site that both parses the
+    // human-edited openclaw.json plugin entry AND has a logger to hand.
+    const dropped = [];
+    const pluginConfig = extractPluginConfig(runtimeConfig, dropped);
+    if (dropped.length > 0) {
+        api.logger?.warn?.(`[shieldcortex] plugin config: dropped invalid interceptor key(s), check type/value: ${dropped.join(', ')}`);
+    }
     if (Object.keys(pluginConfig).length === 0)
         return;
     _configOverride = mergeConfigs(_configOverride ?? {}, pluginConfig);
@@ -944,11 +1018,69 @@ export default {
         if (_registered)
             return;
         _registered = true;
+        // --- Interceptor (lazy init) ---
+        let interceptorReady = null;
+        let interceptorInitAttempted = false;
+        // #134 §2: registered UNCONDITIONALLY, before the try block below that can
+        // throw. Previously this command lived inside that try, so a plugin crash
+        // meant the operator had no /shieldcortex-status to run at all — the one
+        // place they'd look reported nothing, same as it not existing. Now it
+        // always exists, and honestly reports DEGRADED when init failed instead of
+        // rendering config-derived lines that describe a state the plugin never
+        // reached.
+        try {
+            api.registerCommand({
+                name: "shieldcortex-status",
+                description: "Show ShieldCortex real-time scanner status",
+                async handler() {
+                    if (_registrationError) {
+                        return {
+                            text: `ShieldCortex v${_version}\n` +
+                                `  STATUS: DEGRADED — plugin failed to initialize: ${_registrationError}\n` +
+                                `  Real-time scanning, memory capture and the Action Guard before_tool_call\n` +
+                                `  hook are ALL INACTIVE. Channels started normally (fail-open by design —\n` +
+                                `  a broken security plugin must never block the gateway), but this plugin\n` +
+                                `  is doing nothing until the underlying error is fixed and the gateway is\n` +
+                                `  restarted.`,
+                        };
+                    }
+                    const cfg = await loadConfig();
+                    const autoMemory = isAutoMemoryEnabled(cfg) ? "on" : "off";
+                    const dedupe = isAutoMemoryDedupeEnabled(cfg) ? "on" : "off";
+                    const cloud = cfg.cloudApiKey ? "configured" : "not configured";
+                    // Resolve the Action Guard state the same way initInterceptor() does,
+                    // so the status line reflects what before_tool_call will actually do.
+                    const rawInterceptor = cfg.interceptor;
+                    const guardCfg = {
+                        ...(DEFAULT_INTERCEPTOR_CONFIG.actionGuard ?? { enabled: true, enforce: true, autoApprove: [] }),
+                        ...(rawInterceptor && typeof rawInterceptor === 'object' ? rawInterceptor.actionGuard ?? {} : {}),
+                    };
+                    const interceptorOn = (rawInterceptor && typeof rawInterceptor === 'object' ? rawInterceptor.enabled : undefined) ?? DEFAULT_INTERCEPTOR_CONFIG.enabled;
+                    const autoApproved = Array.isArray(guardCfg.autoApprove) ? guardCfg.autoApprove.length : 0;
+                    const guardState = !_beforeToolCallRegistered
+                        ? "off (before_tool_call not registered — interceptor disabled in plugin config)"
+                        : !interceptorOn || !guardCfg.enabled
+                            ? "off"
+                            : `${guardCfg.enforce ? "enforce" : "warn"}${autoApproved > 0 ? ` (${autoApproved} auto-approved)` : ""}${interceptorReady ? "" : " — not yet initialised this session"}`;
+                    const hooksLine = _beforeToolCallRegistered
+                        ? "llm_input (scan), llm_output (memory), before_tool_call (action guard), session_end (cache reset)"
+                        : "llm_input (scan), llm_output (memory)";
+                    return {
+                        text: `ShieldCortex v${_version}\n` +
+                            `  Hooks: ${hooksLine}\n` +
+                            `  Action guard: ${guardState}\n` +
+                            `  Auto memory: ${autoMemory} | Dedupe: ${dedupe}\n` +
+                            `  Cloud sync: ${cloud}`,
+                    };
+                },
+            });
+        }
+        catch {
+            // Host doesn't support registerCommand at all — nothing more to do here;
+            // the try/catch below still logs the substantive init failure loudly.
+        }
         try {
             applyPluginConfigOverride(api);
-            // --- Interceptor (lazy init) ---
-            let interceptorReady = null;
-            let interceptorInitAttempted = false;
             async function initInterceptor() {
                 if (interceptorInitAttempted)
                     return interceptorReady;
@@ -1042,48 +1174,29 @@ export default {
             }
             api.on("llm_input", handleLlmInput, { timeoutMs: 30_000 });
             api.on("llm_output", handleLlmOutput, { timeoutMs: 30_000 });
-            // Register a lightweight status command so the plugin is not hook-only
-            api.registerCommand({
-                name: "shieldcortex-status",
-                description: "Show ShieldCortex real-time scanner status",
-                async handler() {
-                    const cfg = await loadConfig();
-                    const autoMemory = isAutoMemoryEnabled(cfg) ? "on" : "off";
-                    const dedupe = isAutoMemoryDedupeEnabled(cfg) ? "on" : "off";
-                    const cloud = cfg.cloudApiKey ? "configured" : "not configured";
-                    // Resolve the Action Guard state the same way initInterceptor() does,
-                    // so the status line reflects what before_tool_call will actually do.
-                    const rawInterceptor = cfg.interceptor;
-                    const guardCfg = {
-                        ...(DEFAULT_INTERCEPTOR_CONFIG.actionGuard ?? { enabled: true, enforce: true, autoApprove: [] }),
-                        ...(rawInterceptor && typeof rawInterceptor === 'object' ? rawInterceptor.actionGuard ?? {} : {}),
-                    };
-                    const interceptorOn = (rawInterceptor && typeof rawInterceptor === 'object' ? rawInterceptor.enabled : undefined) ?? DEFAULT_INTERCEPTOR_CONFIG.enabled;
-                    const autoApproved = Array.isArray(guardCfg.autoApprove) ? guardCfg.autoApprove.length : 0;
-                    const guardState = !_beforeToolCallRegistered
-                        ? "off (before_tool_call not registered — interceptor disabled in plugin config)"
-                        : !interceptorOn || !guardCfg.enabled
-                            ? "off"
-                            : `${guardCfg.enforce ? "enforce" : "warn"}${autoApproved > 0 ? ` (${autoApproved} auto-approved)` : ""}${interceptorReady ? "" : " — not yet initialised this session"}`;
-                    const hooksLine = _beforeToolCallRegistered
-                        ? "llm_input (scan), llm_output (memory), before_tool_call (action guard), session_end (cache reset)"
-                        : "llm_input (scan), llm_output (memory)";
-                    return {
-                        text: `ShieldCortex v${_version}\n` +
-                            `  Hooks: ${hooksLine}\n` +
-                            `  Action guard: ${guardState}\n` +
-                            `  Auto memory: ${autoMemory} | Dedupe: ${dedupe}\n` +
-                            `  Cloud sync: ${cloud}`,
-                    };
-                },
-            });
             api.logger.info(`[shieldcortex] v${_version} registered (llm_input + llm_output${_beforeToolCallRegistered ? " + before_tool_call" : ""} + /shieldcortex-status)`);
         }
         catch (err) {
-            // Plugin must never block channel startup — warn and bail gracefully
+            // Plugin must never block channel startup — warn and bail gracefully.
+            // #134 §2: this used to be a bare console.warn, which bypasses the
+            // gateway's structured log entirely — real-time scanning, memory
+            // capture and the Action Guard before_tool_call hook all go dark with
+            // no [plugins] line anywhere an operator looks. Route through
+            // api.logger.warn (the structured channel) and only fall back to
+            // console.error — never console.warn, so a fallback line is visibly
+            // distinct from a routed one — if the host doesn't even provide a
+            // logger, which would itself be a broken host.
             const msg = err instanceof Error ? err.message : String(err);
-            console.warn(`[shieldcortex] WARNING: Plugin failed to initialize: ${msg}`);
-            console.warn('[shieldcortex] Real-time scanning is disabled. Channels will start normally.');
+            _registrationError = msg;
+            const warn = api.logger?.warn;
+            if (typeof warn === 'function') {
+                warn.call(api.logger, `[shieldcortex] WARNING: Plugin failed to initialize: ${msg}`);
+                warn.call(api.logger, '[shieldcortex] Real-time scanning is disabled. Channels will start normally.');
+            }
+            else {
+                console.error(`[shieldcortex] WARNING: Plugin failed to initialize (no api.logger available): ${msg}`);
+                console.error('[shieldcortex] Real-time scanning is disabled. Channels will start normally.');
+            }
         }
     },
 };

package/dist/interceptor.js

@@ -355,8 +355,21 @@ function xrayMemoryGuard(content, title) {
 //   * anything over the size cap is refused (the guard then records it as
 //     `opaque-script-invocation` rather than pretending it was scanned);
 //   * every error returns `null`. Nothing escapes.
-const MAX_SCRIPT_SOURCE_BYTES = 262_144; // 256KB — matches the guard core's cap
-const UNREADABLE_PATH_PREFIX = /^\/(?:proc|sys|dev)\//;
+// The resolver is DUPLICATED here, deliberately (#160).
+//
+// This plugin publishes as its own npm package and builds standalone
+// (tsconfig.openclaw-plugin.json pins rootDir to plugins/openclaw), so it
+// genuinely cannot import from src/ — converging by import broke the plugin
+// build outright. A real constraint, then, not a tidiness failure.
+//
+// But two copies of a safety-railed file reader reached from untrusted tool
+// input is two chances to drift, and drift is what #160 was about. So the
+// copies are held together by a BEHAVIOURAL drift test that runs both
+// implementations over one fixture table and requires identical answers
+// (src/__tests__/enforcement-surface-parity.test.ts). Guard the duplication
+// rather than pretend it away.
+export const MAX_SCRIPT_SOURCE_BYTES = 262_144; // 256KB — matches the guard core's cap
+export const UNREADABLE_PATH_PREFIX = /^\/(?:proc|sys|dev)\//;
 export function createScriptSourceResolver(cwd) {
     const base = cwd && typeof cwd === 'string' ? cwd : process.cwd();
     return (scriptPath) => {

package/dist/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.47.23",
+  "version": "4.47.25",
   "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,
@@ -109,7 +109,8 @@
     "additionalProperties": false,
     "properties": {
       "enabled": {
-        "type": "boolean"
+        "type": "boolean",
+        "description": "Unused — plugin on/off is controlled by plugins.entries[id].enabled on the host, not this nested config value. See #115."
       },
       "binaryPath": {
         "type": "string"
@@ -138,6 +139,7 @@
       },
       "interceptor": {
         "type": "object",
+        "additionalProperties": false,
         "properties": {
           "enabled": {
             "type": "boolean",

package/index.ts

@@ -184,6 +184,7 @@ export function __resetConfigStateForTest(): void {
   _lastShieldConfigRef = null;
   _registered = false;
   _beforeToolCallRegistered = false;
+  _registrationError = null;
 }
 
 type LlmInputEvent = {
@@ -398,7 +399,14 @@ const PLUGIN_CONFIG_JSON_SCHEMA = {
   type: "object",
   additionalProperties: false,
   properties: {
-    enabled: { type: "boolean" },
+    // #115: accepted for schema/UI compatibility but not read — plugin
+    // enablement lives host-side at plugins.entries[id].enabled (see
+    // rootConfigWith() shape in extractPluginConfig), one level up from this
+    // nested `config` object. normaliseConfig() has never populated
+    // SCConfig.enabled (no such field exists); documented rather than
+    // removed so an existing config.enabled:true/false written by a host UI
+    // doesn't fail `additionalProperties:false` validation.
+    enabled: { type: "boolean", description: "Unused — plugin on/off is controlled by plugins.entries[id].enabled on the host, not this nested config value." },
     binaryPath: { type: "string" },
     cloudApiKey: { type: "string" },
     cloudBaseUrl: { type: "string" },
@@ -447,8 +455,17 @@ let _registered = false;
 // unattended Codex agents even a no-op registered hook changes how OpenClaw
 // resolves approvals).
 let _beforeToolCallRegistered = false;
-
-function normaliseConfig(raw: unknown): SCConfig {
+// #134 §2: register() wraps its whole body in try/catch so a plugin failure
+// never blocks channel startup — correct, but it used to report the failure
+// with a bare console.warn (bypasses the gateway's structured log, so the
+// operator's only view of a dead security plugin is stdout no one reads) and
+// the /shieldcortex-status command lived INSIDE the same try block, so a
+// crash before that line meant the command never existed at all — the plugin
+// couldn't even honestly report its own death. Set here so the status handler
+// (registered unconditionally, before the risky init work) can read it.
+let _registrationError: string | null = null;
+
+function normaliseConfig(raw: unknown, dropped?: string[]): SCConfig {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
 
   const value = raw as Record<string, unknown>;
@@ -484,60 +501,102 @@ function normaliseConfig(raw: unknown): SCConfig {
   // ignored and DEFAULT_INTERCEPTOR_CONFIG re-armed the before_tool_call gate.
   // Validate-and-preserve every nested interceptor key the manifest schema
   // accepts; invalid values are dropped individually, valid siblings survive.
-  const interceptor = normaliseInterceptorConfig(value.interceptor);
+  // #115: `dropped` collects the exact key paths any invalid value was
+  // dropped from — undefined here (the configSchema.parse() public contract
+  // stays a single return value); applyPluginConfigOverride is the one
+  // caller that both has a logger AND matters for this (it ingests the
+  // openclaw.json plugin entry a human hand-edits — the Edith #112 incident's
+  // `enabled:"false"` was exactly this shape of typo).
+  const interceptor = normaliseInterceptorConfig(value.interceptor, dropped);
   if (interceptor) config.interceptor = interceptor;
 
   return config;
 }
 
+// #115: returns undefined (not {}) when nothing valid was found, matching
+// normaliseInterceptorConfig's contract below — an empty/all-invalid map
+// must read as "absent" so mergeConfigs/applyPluginConfigOverride treat it
+// as no override rather than a truthy-but-empty one.
 function normaliseSeverityMap<A extends string>(
   raw: unknown,
   allowed: readonly A[],
+  dropped?: string[],
+  pathPrefix?: string,
 ): Partial<Record<InterceptSeverity, A>> | undefined {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
   const value = raw as Record<string, unknown>;
   const out: Partial<Record<InterceptSeverity, A>> = {};
   for (const severity of INTERCEPT_SEVERITIES) {
     const entry = value[severity];
+    if (entry === undefined) continue; // absent, not invalid — nothing to warn about
     if (typeof entry === "string" && (allowed as readonly string[]).includes(entry)) {
       out[severity] = entry as A;
+    } else if (pathPrefix) {
+      dropped?.push(`${pathPrefix}.${severity}`);
     }
   }
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
-function normaliseInterceptorConfig(raw: unknown): InterceptorUserConfig | undefined {
+function normaliseInterceptorConfig(raw: unknown, dropped?: string[]): InterceptorUserConfig | undefined {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
   const value = raw as Record<string, unknown>;
   const out: InterceptorUserConfig = {};
 
-  if (typeof value.enabled === "boolean") out.enabled = value.enabled;
+  if (value.enabled !== undefined) {
+    if (typeof value.enabled === "boolean") out.enabled = value.enabled;
+    else dropped?.push("interceptor.enabled");
+  }
 
-  const severityActions = normaliseSeverityMap(value.severityActions, INTERCEPT_ACTIONS);
+  const severityActions = normaliseSeverityMap(value.severityActions, INTERCEPT_ACTIONS, dropped, "interceptor.severityActions");
   if (severityActions) out.severityActions = severityActions;
 
-  const failurePolicy = normaliseSeverityMap(value.failurePolicy, FAILURE_ACTIONS);
+  const failurePolicy = normaliseSeverityMap(value.failurePolicy, FAILURE_ACTIONS, dropped, "interceptor.failurePolicy");
   if (failurePolicy) out.failurePolicy = failurePolicy;
 
-  if (value.actionGuard && typeof value.actionGuard === "object" && !Array.isArray(value.actionGuard)) {
-    const rawGuard = value.actionGuard as Record<string, unknown>;
-    const guard: NonNullable<InterceptorUserConfig["actionGuard"]> = {};
-    if (typeof rawGuard.enabled === "boolean") guard.enabled = rawGuard.enabled;
-    if (typeof rawGuard.enforce === "boolean") guard.enforce = rawGuard.enforce;
-    if (typeof rawGuard.auditAllows === "boolean") guard.auditAllows = rawGuard.auditAllows;
-    if (Array.isArray(rawGuard.autoApprove) && rawGuard.autoApprove.every((entry) => typeof entry === "string")) {
-      guard.autoApprove = rawGuard.autoApprove as string[];
-    }
-    // Carried through untouched — normaliseBrokerConfig is the boundary, and
-    // splitting that job across two files is how one of the halves ends up
-    // being the lenient one.
-    if (rawGuard.broker && typeof rawGuard.broker === "object" && !Array.isArray(rawGuard.broker)) {
-      guard.broker = rawGuard.broker as Record<string, unknown>;
+  if (value.actionGuard !== undefined) {
+    if (value.actionGuard && typeof value.actionGuard === "object" && !Array.isArray(value.actionGuard)) {
+      const rawGuard = value.actionGuard as Record<string, unknown>;
+      const guard: NonNullable<InterceptorUserConfig["actionGuard"]> = {};
+      if (rawGuard.enabled !== undefined) {
+        if (typeof rawGuard.enabled === "boolean") guard.enabled = rawGuard.enabled;
+        else dropped?.push("interceptor.actionGuard.enabled");
+      }
+      if (rawGuard.enforce !== undefined) {
+        if (typeof rawGuard.enforce === "boolean") guard.enforce = rawGuard.enforce;
+        else dropped?.push("interceptor.actionGuard.enforce");
+      }
+      if (rawGuard.auditAllows !== undefined) {
+        if (typeof rawGuard.auditAllows === "boolean") guard.auditAllows = rawGuard.auditAllows;
+        else dropped?.push("interceptor.actionGuard.auditAllows");
+      }
+      if (rawGuard.autoApprove !== undefined) {
+        if (Array.isArray(rawGuard.autoApprove) && rawGuard.autoApprove.every((entry) => typeof entry === "string")) {
+          // #115: defensive copy — downstream (initInterceptor's spread into
+          // InterceptorConfig) is read-only today, but aliasing the caller's
+          // array means a future in-place mutation of the host config object
+          // would silently corrupt the normalised config too.
+          guard.autoApprove = [...(rawGuard.autoApprove as string[])];
+        } else {
+          dropped?.push("interceptor.actionGuard.autoApprove");
+        }
+      }
+      // Carried through untouched — normaliseBrokerConfig is the boundary, and
+      // splitting that job across two files is how one of the halves ends up
+      // being the lenient one.
+      if (rawGuard.broker && typeof rawGuard.broker === "object" && !Array.isArray(rawGuard.broker)) {
+        guard.broker = rawGuard.broker as Record<string, unknown>;
+      }
+      if (Object.keys(guard).length > 0) out.actionGuard = guard;
+    } else {
+      dropped?.push("interceptor.actionGuard");
     }
-    if (Object.keys(guard).length > 0) out.actionGuard = guard;
   }
 
-  return out;
+  // #115: empty/all-invalid normalises to undefined, not {} — {} is truthy
+  // and made applyPluginConfigOverride treat a no-op interceptor block as a
+  // real override, inconsistent with normaliseSeverityMap's own contract.
+  return Object.keys(out).length > 0 ? out : undefined;
 }
 
 /**
@@ -571,7 +630,7 @@ function mergeConfigs(base: SCConfig, override: SCConfig): SCConfig {
   return merged;
 }
 
-function extractPluginConfig(rootConfig: unknown): SCConfig {
+function extractPluginConfig(rootConfig: unknown, dropped?: string[]): SCConfig {
   if (!rootConfig || typeof rootConfig !== "object" || Array.isArray(rootConfig)) return {};
   const entries = (rootConfig as {
     plugins?: {
@@ -583,7 +642,7 @@ function extractPluginConfig(rootConfig: unknown): SCConfig {
     entries?.[PLUGIN_ID]?.config ??
     entries?.[PLUGIN_PACKAGE_NAME]?.config;
 
-  return normaliseConfig(pluginConfig);
+  return normaliseConfig(pluginConfig, dropped);
 }
 
 function applyPluginConfigOverride(api: PluginApi): void {
@@ -593,7 +652,18 @@ function applyPluginConfigOverride(api: PluginApi): void {
     : typeof runtimeConfigApi?.loadConfig === "function"
       ? runtimeConfigApi.loadConfig()
       : api.config;
-  const pluginConfig = extractPluginConfig(runtimeConfig);
+  // #115: name the exact dropped interceptor key(s) in a warn log. Edith's
+  // #112 incident (interceptor.enabled:"false", a string not a boolean) took
+  // longer to diagnose than it should have because the drop was silent —
+  // this is the one normaliseConfig() call site that both parses the
+  // human-edited openclaw.json plugin entry AND has a logger to hand.
+  const dropped: string[] = [];
+  const pluginConfig = extractPluginConfig(runtimeConfig, dropped);
+  if (dropped.length > 0) {
+    (api.logger as any)?.warn?.(
+      `[shieldcortex] plugin config: dropped invalid interceptor key(s), check type/value: ${dropped.join(', ')}`,
+    );
+  }
   if (Object.keys(pluginConfig).length === 0) return;
   _configOverride = mergeConfigs(_configOverride ?? {}, pluginConfig);
   // Override changed — invalidate so loadConfig() re-merges with new override.
@@ -1129,13 +1199,74 @@ export default {
   register(api: PluginApi) {
     if (_registered) return;
     _registered = true;
-    try {
-    applyPluginConfigOverride(api);
 
     // --- Interceptor (lazy init) ---
     let interceptorReady: ReturnType<typeof createInterceptor> | null = null;
     let interceptorInitAttempted = false;
 
+    // #134 §2: registered UNCONDITIONALLY, before the try block below that can
+    // throw. Previously this command lived inside that try, so a plugin crash
+    // meant the operator had no /shieldcortex-status to run at all — the one
+    // place they'd look reported nothing, same as it not existing. Now it
+    // always exists, and honestly reports DEGRADED when init failed instead of
+    // rendering config-derived lines that describe a state the plugin never
+    // reached.
+    try {
+      api.registerCommand({
+        name: "shieldcortex-status",
+        description: "Show ShieldCortex real-time scanner status",
+        async handler() {
+          if (_registrationError) {
+            return {
+              text:
+                `ShieldCortex v${_version}\n` +
+                `  STATUS: DEGRADED — plugin failed to initialize: ${_registrationError}\n` +
+                `  Real-time scanning, memory capture and the Action Guard before_tool_call\n` +
+                `  hook are ALL INACTIVE. Channels started normally (fail-open by design —\n` +
+                `  a broken security plugin must never block the gateway), but this plugin\n` +
+                `  is doing nothing until the underlying error is fixed and the gateway is\n` +
+                `  restarted.`,
+            };
+          }
+          const cfg = await loadConfig();
+          const autoMemory = isAutoMemoryEnabled(cfg) ? "on" : "off";
+          const dedupe = isAutoMemoryDedupeEnabled(cfg) ? "on" : "off";
+          const cloud = cfg.cloudApiKey ? "configured" : "not configured";
+          // Resolve the Action Guard state the same way initInterceptor() does,
+          // so the status line reflects what before_tool_call will actually do.
+          const rawInterceptor = cfg.interceptor;
+          const guardCfg = {
+            ...(DEFAULT_INTERCEPTOR_CONFIG.actionGuard ?? { enabled: true, enforce: true, autoApprove: [] }),
+            ...(rawInterceptor && typeof rawInterceptor === 'object' ? rawInterceptor.actionGuard ?? {} : {}),
+          };
+          const interceptorOn = (rawInterceptor && typeof rawInterceptor === 'object' ? rawInterceptor.enabled : undefined) ?? DEFAULT_INTERCEPTOR_CONFIG.enabled;
+          const autoApproved = Array.isArray(guardCfg.autoApprove) ? guardCfg.autoApprove.length : 0;
+          const guardState = !_beforeToolCallRegistered
+            ? "off (before_tool_call not registered — interceptor disabled in plugin config)"
+            : !interceptorOn || !guardCfg.enabled
+              ? "off"
+              : `${guardCfg.enforce ? "enforce" : "warn"}${autoApproved > 0 ? ` (${autoApproved} auto-approved)` : ""}${interceptorReady ? "" : " — not yet initialised this session"}`;
+          const hooksLine = _beforeToolCallRegistered
+            ? "llm_input (scan), llm_output (memory), before_tool_call (action guard), session_end (cache reset)"
+            : "llm_input (scan), llm_output (memory)";
+          return {
+            text:
+              `ShieldCortex v${_version}\n` +
+              `  Hooks: ${hooksLine}\n` +
+              `  Action guard: ${guardState}\n` +
+              `  Auto memory: ${autoMemory} | Dedupe: ${dedupe}\n` +
+              `  Cloud sync: ${cloud}`,
+          };
+        },
+      });
+    } catch {
+      // Host doesn't support registerCommand at all — nothing more to do here;
+      // the try/catch below still logs the substantive init failure loudly.
+    }
+
+    try {
+    applyPluginConfigOverride(api);
+
     async function initInterceptor(): Promise<ReturnType<typeof createInterceptor> | null> {
       if (interceptorInitAttempted) return interceptorReady;
       interceptorInitAttempted = true;
@@ -1231,49 +1362,27 @@ export default {
     api.on("llm_input", handleLlmInput, { timeoutMs: 30_000 });
     api.on("llm_output", handleLlmOutput, { timeoutMs: 30_000 });
 
-    // Register a lightweight status command so the plugin is not hook-only
-    api.registerCommand({
-      name: "shieldcortex-status",
-      description: "Show ShieldCortex real-time scanner status",
-      async handler() {
-        const cfg = await loadConfig();
-        const autoMemory = isAutoMemoryEnabled(cfg) ? "on" : "off";
-        const dedupe = isAutoMemoryDedupeEnabled(cfg) ? "on" : "off";
-        const cloud = cfg.cloudApiKey ? "configured" : "not configured";
-        // Resolve the Action Guard state the same way initInterceptor() does,
-        // so the status line reflects what before_tool_call will actually do.
-        const rawInterceptor = cfg.interceptor;
-        const guardCfg = {
-          ...(DEFAULT_INTERCEPTOR_CONFIG.actionGuard ?? { enabled: true, enforce: true, autoApprove: [] }),
-          ...(rawInterceptor && typeof rawInterceptor === 'object' ? rawInterceptor.actionGuard ?? {} : {}),
-        };
-        const interceptorOn = (rawInterceptor && typeof rawInterceptor === 'object' ? rawInterceptor.enabled : undefined) ?? DEFAULT_INTERCEPTOR_CONFIG.enabled;
-        const autoApproved = Array.isArray(guardCfg.autoApprove) ? guardCfg.autoApprove.length : 0;
-        const guardState = !_beforeToolCallRegistered
-          ? "off (before_tool_call not registered — interceptor disabled in plugin config)"
-          : !interceptorOn || !guardCfg.enabled
-            ? "off"
-            : `${guardCfg.enforce ? "enforce" : "warn"}${autoApproved > 0 ? ` (${autoApproved} auto-approved)` : ""}${interceptorReady ? "" : " — not yet initialised this session"}`;
-        const hooksLine = _beforeToolCallRegistered
-          ? "llm_input (scan), llm_output (memory), before_tool_call (action guard), session_end (cache reset)"
-          : "llm_input (scan), llm_output (memory)";
-        return {
-          text:
-            `ShieldCortex v${_version}\n` +
-            `  Hooks: ${hooksLine}\n` +
-            `  Action guard: ${guardState}\n` +
-            `  Auto memory: ${autoMemory} | Dedupe: ${dedupe}\n` +
-            `  Cloud sync: ${cloud}`,
-        };
-      },
-    });
-
     api.logger.info(`[shieldcortex] v${_version} registered (llm_input + llm_output${_beforeToolCallRegistered ? " + before_tool_call" : ""} + /shieldcortex-status)`);
     } catch (err) {
-      // Plugin must never block channel startup — warn and bail gracefully
+      // Plugin must never block channel startup — warn and bail gracefully.
+      // #134 §2: this used to be a bare console.warn, which bypasses the
+      // gateway's structured log entirely — real-time scanning, memory
+      // capture and the Action Guard before_tool_call hook all go dark with
+      // no [plugins] line anywhere an operator looks. Route through
+      // api.logger.warn (the structured channel) and only fall back to
+      // console.error — never console.warn, so a fallback line is visibly
+      // distinct from a routed one — if the host doesn't even provide a
+      // logger, which would itself be a broken host.
       const msg = err instanceof Error ? err.message : String(err);
-      console.warn(`[shieldcortex] WARNING: Plugin failed to initialize: ${msg}`);
-      console.warn('[shieldcortex] Real-time scanning is disabled. Channels will start normally.');
+      _registrationError = msg;
+      const warn = (api.logger as any)?.warn;
+      if (typeof warn === 'function') {
+        warn.call(api.logger, `[shieldcortex] WARNING: Plugin failed to initialize: ${msg}`);
+        warn.call(api.logger, '[shieldcortex] Real-time scanning is disabled. Channels will start normally.');
+      } else {
+        console.error(`[shieldcortex] WARNING: Plugin failed to initialize (no api.logger available): ${msg}`);
+        console.error('[shieldcortex] Real-time scanning is disabled. Channels will start normally.');
+      }
     }
   },
 };

package/interceptor.ts

@@ -604,8 +604,21 @@ type PipelineRunner = (content: string, title: string, source: { type: string; i
 //   * anything over the size cap is refused (the guard then records it as
 //     `opaque-script-invocation` rather than pretending it was scanned);
 //   * every error returns `null`. Nothing escapes.
-const MAX_SCRIPT_SOURCE_BYTES = 262_144;   // 256KB — matches the guard core's cap
-const UNREADABLE_PATH_PREFIX = /^\/(?:proc|sys|dev)\//;
+// The resolver is DUPLICATED here, deliberately (#160).
+//
+// This plugin publishes as its own npm package and builds standalone
+// (tsconfig.openclaw-plugin.json pins rootDir to plugins/openclaw), so it
+// genuinely cannot import from src/ — converging by import broke the plugin
+// build outright. A real constraint, then, not a tidiness failure.
+//
+// But two copies of a safety-railed file reader reached from untrusted tool
+// input is two chances to drift, and drift is what #160 was about. So the
+// copies are held together by a BEHAVIOURAL drift test that runs both
+// implementations over one fixture table and requires identical answers
+// (src/__tests__/enforcement-surface-parity.test.ts). Guard the duplication
+// rather than pretend it away.
+export const MAX_SCRIPT_SOURCE_BYTES = 262_144;   // 256KB — matches the guard core's cap
+export const UNREADABLE_PATH_PREFIX = /^\/(?:proc|sys|dev)\//;
 
 export function createScriptSourceResolver(cwd?: string): (scriptPath: string) => string | null {
   const base = cwd && typeof cwd === 'string' ? cwd : process.cwd();

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.47.23",
+  "version": "4.47.25",
   "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,
@@ -109,7 +109,8 @@
     "additionalProperties": false,
     "properties": {
       "enabled": {
-        "type": "boolean"
+        "type": "boolean",
+        "description": "Unused — plugin on/off is controlled by plugins.entries[id].enabled on the host, not this nested config value. See #115."
       },
       "binaryPath": {
         "type": "string"
@@ -138,6 +139,7 @@
       },
       "interceptor": {
         "type": "object",
+        "additionalProperties": false,
         "properties": {
           "enabled": {
             "type": "boolean",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/shieldcortex-realtime",
-  "version": "4.47.23",
+  "version": "4.47.25",
   "description": "OpenClaw plugin for ShieldCortex real-time defence scanning and optional memory extraction.",
   "type": "module",
   "main": "./dist/index.js",