@drakon-systems/shieldcortex-realtime 4.47.38 → 4.47.40

package/dist/index.js

@@ -2,23 +2,41 @@
  * ShieldCortex Real-time Scanning Plugin for OpenClaw v2026.3.22+
  *
  * Uses typed OpenClaw plugin hooks (`api.on`) for llm_input/llm_output
- * scanning and before_tool_call interception. `api.registerHook` registers
- * internal HOOK-style automation and does not participate in the agent-loop
- * block/approval semantics ShieldCortex needs.
- * All scanning operations are fire-and-forget.
+ * scanning and before_tool_call / before_agent_run interception.
+ * `api.registerHook` registers internal HOOK-style automation and does not
+ * participate in the agent-loop block/approval semantics ShieldCortex needs.
+ *
+ * NOT all scanning is fire-and-forget, and the distinction is the product:
+ *
+ *   llm_input        — OBSERVATION. Fire-and-forget; it has no blocking
+ *                      contract, so a detection here cannot stop the turn.
+ *   before_agent_run — THE GATE (#225). Awaited by the gateway; its return
+ *                      value decides whether the run proceeds. Bounded end to
+ *                      end (CONVERSATION_SCAN_MAX_MS for the scan,
+ *                      CONVERSATION_NOTIFY_MAX_MS for the alert) because the
+ *                      user's turn waits on it, and failing OPEN on every
+ *                      internal error — as an EXPLICIT `{ outcome: 'pass' }`
+ *                      (#226), never as void, and never by throwing: the host
+ *                      registers this hook fail-CLOSED. See `gatePass`.
+ *   before_tool_call — the Action Guard's gate, likewise awaited.
+ *
+ * Both conversation hooks honour `interceptor.conversation.posture`, including
+ * `off`, which is read before any scanner, audit write or cloud call.
  */
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
 import { readConversationAccess, describeRegisteredHooks } from './conversation-access.js';
 import { createSessionTaintStore } from './session-taint.js';
 import { classifyConversationOrigin } from './conversation-trust.js';
 import { createInterceptor, DEFAULT_CONFIG as DEFAULT_INTERCEPTOR_CONFIG } from './interceptor.js';
 import { syncInterceptEvent } from './intercept-ingest.js';
 import { cloudSync } from './cloud-sync.js';
+import { createGatewayNotifyChannel } from './gateway-notify-channel.js';
 let runtimePromise = null;
 function addRuntimeCandidate(candidates, packageRoot) {
     const runtimePath = path.join(packageRoot, "hooks", "openclaw", "cortex-memory", "runtime.mjs");
@@ -35,13 +53,66 @@ function addAncestorCandidates(candidates, startPath) {
         current = path.dirname(current);
     }
 }
-function collectRuntimeCandidates() {
+/**
+ * Ask Node where the `shieldcortex` package actually is (#174).
+ *
+ * The plugin declares `shieldcortex` as a peer, so on ANY layout Node's own
+ * resolver can find it from here — no guessing at install prefixes. Resolving
+ * `shieldcortex/package.json` rather than the runtime file directly is
+ * deliberate: `./package.json` is the one subpath the main package's `exports`
+ * map always declares, whereas `hooks/openclaw/**` is in `files` but NOT in
+ * `exports`, so resolving it throws ERR_PACKAGE_PATH_NOT_EXPORTED.
+ *
+ * This is the strategy that fixes the reported `~/.local` host, and it works
+ * without widening the public `exports` surface.
+ */
+function addResolvedPeerCandidate(candidates, fromUrl, resolve = (spec, from) => createRequire(from).resolve(spec)) {
+    try {
+        addRuntimeCandidate(candidates, path.dirname(resolve("shieldcortex/package.json", fromUrl)));
+    }
+    catch { /* not resolvable from here — later strategies still apply */ }
+}
+/**
+ * Every place the runtime might live, in the order we should try them.
+ *
+ * `home` is injected because Jest sandboxes SHIELDCORTEX_CONFIG_DIR but never
+ * HOME, so a test that did not inject it would probe the developer's real
+ * install and pass for the wrong reason.
+ */
+function collectRuntimeCandidates(home = homedir(), resolveFrom = import.meta.url) {
     const candidates = new Set();
-    // 1. Relative path (works when running from within npm package tree)
-    candidates.add(new URL("../../hooks/openclaw/cortex-memory/runtime.mjs", import.meta.url).href);
-    // 2. Config file override (reads path from ~/.shieldcortex/config.json instead of env var)
+    // 0. Operator escape hatch. `resolveOpenClawBinary` and the approval channel
+    //    already honour an env override for the same class of "we guessed your
+    //    install prefix wrong" problem; this list was the only copy without one,
+    //    which is why every new prefix (bun, volta, asdf, ~/.local) has needed a
+    //    code change. Accepts either the runtime file itself or a package root.
+    const envOverride = process.env.SHIELDCORTEX_RUNTIME_PATH?.trim();
+    if (envOverride) {
+        if (envOverride.endsWith(".mjs") && existsSync(envOverride)) {
+            candidates.add(pathToFileURL(envOverride).href);
+        }
+        else {
+            addRuntimeCandidate(candidates, envOverride);
+        }
+    }
+    // 1. Ask Node. Works on every layout including the ~/.local one this fixes.
+    addResolvedPeerCandidate(candidates, resolveFrom);
+    // 2. Relative path — the repo/source-tree layout, where ../../hooks/… is real.
+    //    GUARDED, unlike before: on an installed layout this resolves to a
+    //    non-existent scoped path (`@drakon-systems/hooks/…`), and because it was
+    //    the only unguarded entry it became the SOLE list member and its
+    //    ERR_MODULE_NOT_FOUND became the operator-visible failure — the exact
+    //    message #174 reports. It is a real candidate in the source tree, so it
+    //    is kept and screened rather than deleted.
+    const relative = fileURLToPath(new URL("../../hooks/openclaw/cortex-memory/runtime.mjs", resolveFrom));
+    if (existsSync(relative))
+        candidates.add(pathToFileURL(relative).href);
+    // 3. Config file override. Honours SHIELDCORTEX_CONFIG_DIR like the rest of
+    //    the product — reading homedir() directly made this permanently blind on
+    //    a host that relocates its config.
     try {
-        const cfgPath = path.join(homedir(), ".shieldcortex", "config.json");
+        const configDir = process.env.SHIELDCORTEX_CONFIG_DIR?.trim() || path.join(home, ".shieldcortex");
+        const cfgPath = path.join(configDir, "config.json");
         if (existsSync(cfgPath)) {
             const cfg = JSON.parse(readFileSync(cfgPath, "utf-8"));
             if (cfg.installRoot)
@@ -49,10 +120,15 @@ function collectRuntimeCandidates() {
         }
     }
     catch { /* no config */ }
-    // 3. Walk up from current file location
-    addAncestorCandidates(candidates, path.dirname(fileURLToPath(import.meta.url)));
-    // 4. Resolve via common bin symlink paths (no child_process needed)
-    for (const binDir of ["/usr/local/bin", "/opt/homebrew/bin", path.join(homedir(), ".npm-global", "bin")]) {
+    // 4. Walk up from current file location
+    addAncestorCandidates(candidates, path.dirname(fileURLToPath(resolveFrom)));
+    // 5. Resolve via common bin symlink paths (no child_process needed)
+    for (const binDir of [
+        "/usr/local/bin",
+        "/opt/homebrew/bin",
+        path.join(home, ".npm-global", "bin"),
+        path.join(home, ".local", "bin"), // #174: pip-style / npm --prefix ~/.local
+    ]) {
         const binPath = path.join(binDir, "shieldcortex");
         try {
             if (existsSync(binPath))
@@ -60,18 +136,19 @@ function collectRuntimeCandidates() {
         }
         catch { /* broken symlink */ }
     }
-    // 5. Common global install paths (covers npm root -g results without spawning npm)
+    // 6. Common global install paths (covers npm root -g results without spawning npm)
     for (const root of [
         "/usr/lib/node_modules/shieldcortex",
         "/usr/local/lib/node_modules/shieldcortex",
         "/opt/homebrew/lib/node_modules/shieldcortex",
-        path.join(homedir(), ".npm-global", "lib", "node_modules", "shieldcortex"),
-        path.join(homedir(), ".nvm", "versions", "node"), // nvm users
+        path.join(home, ".npm-global", "lib", "node_modules", "shieldcortex"),
+        path.join(home, ".local", "lib", "node_modules", "shieldcortex"), // #174
+        path.join(home, ".nvm", "versions", "node"), // nvm users
     ]) {
         if (root.includes(".nvm")) {
             // For nvm, check the current symlink
             try {
-                const currentNode = path.join(homedir(), ".nvm", "current", "lib", "node_modules", "shieldcortex");
+                const currentNode = path.join(home, ".nvm", "current", "lib", "node_modules", "shieldcortex");
                 addRuntimeCandidate(candidates, currentNode);
             }
             catch { /* no nvm */ }
@@ -103,6 +180,16 @@ async function getRuntime() {
                     lastError = error;
                 }
             }
+            // #174: with every candidate screened by existsSync, "none found" is a
+            // real outcome and must not render as `Tried: . Last error: unknown
+            // error`. Name the escape hatch instead — this message is the only thing
+            // an operator on an unusual install prefix has to go on.
+            if (tried.length === 0) {
+                throw new Error("Could not load OpenClaw runtime: the shieldcortex package was not found from the plugin, " +
+                    "and no known install prefix contained hooks/openclaw/cortex-memory/runtime.mjs. " +
+                    "Point at it explicitly with SHIELDCORTEX_RUNTIME_PATH=/path/to/shieldcortex " +
+                    "(or to the runtime.mjs itself), or reinstall so `shieldcortex` resolves as a peer of the plugin.");
+            }
             const detail = lastError instanceof Error ? lastError.message : String(lastError ?? "unknown error");
             throw new Error(`Could not load OpenClaw runtime. Tried: ${tried.join(", ")}. Last error: ${detail}`);
         })();
@@ -142,6 +229,12 @@ async function getDefenceModule() {
 export function __getSessionTaintForTest() {
     return sessionTaint;
 }
+/** Test seam for #174 runtime resolution: `home` and the resolving module URL
+ *  are injectable because Jest sandboxes SHIELDCORTEX_CONFIG_DIR but never
+ *  HOME, so an un-injected probe would read the developer's real install. */
+export function __collectRuntimeCandidatesForTest(home, from) {
+    return collectRuntimeCandidates(home, from);
+}
 export function __setDefenceModuleForTest(mod) {
     _defenceModOverride = mod;
     _defenceModPromise = null;
@@ -155,13 +248,492 @@ export function __resetConfigStateForTest() {
     _config = null;
     _configOverride = null;
     _lastShieldConfigRef = null;
+    // Re-arm the once-per-load config-failure warning (#226).
+    _shieldConfigLoadFailureLogged = false;
     _registered = false;
     _beforeToolCallRegistered = false;
     _registrationError = null;
+    _beforeAgentRunRequested = false;
+    _conversationAccessGranted = false;
+    _gatewayNotifyContext = null;
+    _hostRuntimeVersion = null;
+    __resetScanUnavailableAlertState();
 }
 const INTERCEPT_SEVERITIES = ['low', 'medium', 'high', 'critical'];
 const INTERCEPT_ACTIONS = ['log', 'warn', 'require_approval'];
 const FAILURE_ACTIONS = ['allow', 'deny'];
+const CONVERSATION_POSTURES = ['off', 'observe', 'enforce'];
+/** Resolve the configured posture. Anything unrecognised resolves DOWN to
+ *  `observe`, never up to `enforce`: a typo must not silently start blocking
+ *  every turn on an operator's box. */
+export function conversationPosture(raw) {
+    if (!raw || typeof raw !== 'object')
+        return 'observe';
+    const value = raw.posture;
+    return typeof value === 'string' && CONVERSATION_POSTURES.includes(value)
+        ? value
+        : 'observe';
+}
+/**
+ * The whole decision, as a pure function — no I/O, no hooks, so the posture
+ * semantics are testable directly and cannot drift as the plumbing changes.
+ *
+ * The key line is `notify` on a non-blocking detection: logging is not a sink.
+ * The #225 finding was that a HIGH verdict reached a log file and nothing else,
+ * so a real threat on a real box was seen by nobody. Under `observe` we still
+ * do not stop the turn — but a human hears about it.
+ *
+ * `trust` is the second input because BLOCKING is a consequence, and #235's rule
+ * is that source trust gates consequences (see conversation-trust.ts). It is
+ * optional, and its absence means "origin not established", which resolves
+ * toward enforcement rather than away from it: a caller that does not know who
+ * spoke has not proved the owner did.
+ */
+export function evaluateConversationRun(posture, scan, trust) {
+    if (posture === 'off') {
+        return { block: false, notify: false, audit: false, reason: null, outcome: 'not-scanned' };
+    }
+    // Scanner failure fails OPEN — a broken scanner must not wedge every turn,
+    // which is the outcome ShieldCortex exists to prevent — but it is reported,
+    // because an unprotected turn must never read as a protected one. Note the
+    // condition: `available === false` OR the legacy `errored` flag, so a caller
+    // still constructing the old shape cannot route an unscanned turn into the
+    // clean branch.
+    if (scan.available === false || scan.errored) {
+        return {
+            block: false,
+            notify: true,
+            audit: true,
+            reason: `conversation scan unavailable (${scan.error ?? scan.summary}) — turn allowed UNSCANNED`,
+            outcome: 'unavailable',
+        };
+    }
+    if (scan.clean) {
+        return { block: false, notify: false, audit: false, reason: null, outcome: 'clean' };
+    }
+    // #235: the owner's own words are an instruction, so `enforce` does not act on
+    // them. This is the branch the whole trust module exists for — a block here
+    // does not warn the operator, it DESTROYS their message: OpenClaw keeps only
+    // the replacement text. Everything above still happened: the content was
+    // scanned, and `notify`/`audit` below are true whoever sent it. Only the
+    // consequence is withheld, and the reason says so on the row rather than
+    // leaving an enforce-posture host that did not block looking like a bug.
+    const trusted = trust !== undefined && !trust.mayTaint;
+    const block = posture === 'enforce' && !trusted;
+    return {
+        block,
+        notify: true,
+        audit: true,
+        reason: posture === 'enforce' && trusted
+            ? `conversation threat: ${scan.summary} — NOT blocked: ${trust.reason}`
+            : `conversation threat: ${scan.summary}`,
+        outcome: block ? 'blocked' : 'observed',
+    };
+}
+// ==================== CONVERSATION PLANE: HOST SUPPORT + CONSENT ============
+/**
+ * The first OpenClaw build whose plugin SDK declares the `before_agent_run`
+ * gate. Established by inspecting published npm artifacts, not by guessing:
+ *
+ *   2026.5.7        — `hook-types.d.ts` has no `before_agent_run` anywhere (0 hits);
+ *                     CONVERSATION_HOOK_NAMES = llm_input, llm_output,
+ *                     before_agent_finalize, agent_end
+ *   2026.5.9-beta.1 — FIRST published build declaring it: in `PLUGIN_HOOK_NAMES`,
+ *                     in `CONVERSATION_HOOK_NAMES`, in `PluginHookHandlerMap`, with
+ *                     `PluginHookBeforeAgentRunResult = InputGateDecision | void`
+ *   2026.5.12       — first STABLE (non-prerelease) build with it (2026.5.10 and
+ *                     2026.5.12 published betas in between; there is no plain
+ *                     2026.5.9 release)
+ *
+ * Below this floor `api.on('before_agent_run', …)` is accepted by the API and
+ * then DROPPED by the registry with an `unknown typed hook … ignored`
+ * diagnostic — it does not throw. So a version check is the only honest way to
+ * know, and claiming enforcement without one is exactly the class of false
+ * green #222 is about.
+ *
+ * ── ONE FLOOR, THREE FILES ────────────────────────────────────────────────
+ *
+ * The authoritative value is the STABLE release, and it is stated in three
+ * places that cannot import each other:
+ *
+ *   plugins/openclaw/index.ts                       — this constant
+ *   src/integrations/openclaw-conversation-capability.ts
+ *                                                   — CONVERSATION_ENFORCEMENT_MIN_OPENCLAW
+ *   plugins/openclaw/openclaw.plugin.json           — engines.conversationGate
+ *
+ * THE BOUNDARY IS REAL, not a preference. The plugin ships as its own dist,
+ * compiled by `tsconfig.openclaw-plugin.json` with `rootDir:
+ * ./plugins/openclaw` and an explicit `include` list; a `src/` import does not
+ * merely offend layering, it fails to emit — and the src module imports
+ * `semver`, which the plugin bundle does not carry (hence the hand-rolled
+ * `compareOpenClawVersions` below). The manifest is JSON read by the host and
+ * imports nothing at all.
+ *
+ * So the three are pinned EQUAL by test instead of shared by import:
+ * `src/__tests__/conversation-gate-floor-parity-226.test.ts` reads all three
+ * and fails on drift. Change one, that test tells you about the other two.
+ *
+ * `CONVERSATION_GATE_FIRST_PRERELEASE_OPENCLAW` is deliberately SUBORDINATE: it
+ * decides nothing an operator sees. Its only job is to mark the band where a
+ * version number alone cannot answer the question — see
+ * `hostSupportsConversationGate`.
+ */
+export const CONVERSATION_GATE_MIN_OPENCLAW = '2026.5.12';
+/**
+ * Documentation of when the hook first appeared, NOT a second floor.
+ *
+ * The previous cut used this as the support threshold, which made the plugin's
+ * operator-facing verdict disagree with the CLI's on any 2026.5.9-beta.1 →
+ * 2026.5.11 host: `shieldcortex doctor` said enforcement was unavailable while
+ * the plugin's own status line said supported. Two answers to one question is
+ * how the next false green gets built.
+ */
+export const CONVERSATION_GATE_FIRST_PRERELEASE_OPENCLAW = '2026.5.9-beta.1';
+/**
+ * Compare two OpenClaw CalVer strings (`2026.5.12`, `2026.5.9-beta.1`).
+ * Deliberately local and tiny: the plugin build cannot import semver, and the
+ * only question asked is "is this host at or above the floor".
+ * Returns null when either side cannot be parsed — "unknown", never "yes".
+ */
+export function compareOpenClawVersions(a, b) {
+    const parse = (v) => {
+        // Exactly three numeric parts, and only `-` introduces a prerelease. A
+        // trailing `.4` is NOT a prerelease tail — it is a version shape we do not
+        // understand, and the safe answer to that is "unknown".
+        const m = String(v ?? '').trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+        if (!m)
+            return null;
+        return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ? m[4].split('.') : [] };
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    if (!pa || !pb)
+        return null;
+    for (let i = 0; i < 3; i++) {
+        if (pa.nums[i] !== pb.nums[i])
+            return pa.nums[i] < pb.nums[i] ? -1 : 1;
+    }
+    // A prerelease sorts BELOW the same numeric release (2026.5.9-beta.1 < 2026.5.9).
+    if (pa.pre.length === 0 && pb.pre.length === 0)
+        return 0;
+    if (pa.pre.length === 0)
+        return 1;
+    if (pb.pre.length === 0)
+        return -1;
+    return comparePrerelease(pa.pre, pb.pre);
+}
+/** Semver prerelease precedence, restricted to what a CalVer tail can hold:
+ *  numeric identifiers compare numerically, a numeric identifier sorts below an
+ *  alphanumeric one, and a shorter identifier list sorts below an
+ *  otherwise-equal longer one (`beta` < `beta.1` < `beta.2` < `beta.10`).
+ *
+ *  The string compare this replaces put `beta.10` BELOW `beta.1`, so the tenth
+ *  beta of the gate build was classified as predating the first — an error in
+ *  the one direction this file must never make, since it demotes a host that
+ *  HAS the gate to 'unsupported'. */
+function comparePrerelease(a, b) {
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const x = a[i];
+        const y = b[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const xNum = /^\d+$/.test(x);
+        const yNum = /^\d+$/.test(y);
+        if (xNum && yNum) {
+            const nx = Number(x);
+            const ny = Number(y);
+            if (nx !== ny)
+                return nx < ny ? -1 : 1;
+            continue;
+        }
+        if (xNum !== yNum)
+            return xNum ? -1 : 1;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+/** Test seam: pins the host probe without touching disk. */
+let _hostProbeOverride;
+export function __setHostOpenClawProbeForTest(p) {
+    _hostProbeOverride = p;
+    _hostProbeCache = undefined;
+}
+let _hostProbeCache;
+/**
+ * The host runtime version the gateway told us about, captured at register().
+ *
+ * `api.runtime.version` is declared by the host SDK as
+ * `PluginRuntimeCore.version: string` — the version of the OpenClaw runtime
+ * this plugin is loaded into (verified against the installed host's
+ * `dist/plugin-sdk/src/plugins/runtime/types-core.d.ts`, and `api.runtime` is
+ * on `OpenClawPluginApi` in the same build). It is NOT `api.version`, which is
+ * the plugin's own version and would answer a completely different question:
+ * comparing OUR version against an OpenClaw floor would classify every host as
+ * unsupported.
+ *
+ * It is preferred over the filesystem walk because it is the running process
+ * describing itself, where the walk infers from whichever package.json happens
+ * to sit above the entry path. Null until a host actually supplies it — an
+ * older gateway, a CLI invocation or a test rig may not, and that is UNKNOWN.
+ */
+let _hostRuntimeVersion = null;
+/** Test seam for the runtime-supplied host version. */
+export function __setHostRuntimeVersionForTest(v) {
+    _hostRuntimeVersion = v;
+}
+/**
+ * Record `api.runtime.version` if this host exposes it. Returns what was
+ * recorded (null when nothing usable was offered), and never throws: a host
+ * with an exotic `runtime` getter must not take the plugin's registration down.
+ */
+export function recordHostRuntimeVersion(api) {
+    try {
+        const runtime = api?.runtime;
+        const version = runtime?.version;
+        _hostRuntimeVersion = typeof version === 'string' && version.trim() ? version.trim() : null;
+    }
+    catch {
+        _hostRuntimeVersion = null;
+    }
+    return _hostRuntimeVersion;
+}
+/** Does this host's shipped SDK declare the gate? Bounded, best-effort, and
+ *  null on anything unexpected — an unreadable install is UNKNOWN, never
+ *  "supported". */
+function probeGateDeclaration(root) {
+    const candidates = [];
+    // 2026.5.2-era layout: the declarations live under the plugin-sdk tree.
+    candidates.push(path.join(root, 'dist', 'plugin-sdk', 'src', 'plugins', 'hook-types.d.ts'));
+    // 2026.6+/2026.7 layout: a single hashed `hook-types-<hash>.d.ts` at dist root.
+    try {
+        const distDir = path.join(root, 'dist');
+        if (existsSync(distDir)) {
+            for (const name of readdirSync(distDir)) {
+                if (/^hook-types.*\.d\.ts$/.test(name))
+                    candidates.push(path.join(distDir, name));
+            }
+        }
+    }
+    catch { /* fall through to whatever candidates we have */ }
+    let sawAny = false;
+    for (const file of candidates) {
+        try {
+            if (!existsSync(file))
+                continue;
+            sawAny = true;
+            if (/\bbefore_agent_run\b/.test(readFileSync(file, 'utf-8')))
+                return true;
+        }
+        catch { /* unreadable candidate — try the next */ }
+    }
+    return sawAny ? false : null;
+}
+/**
+ * Everything we can learn about the host OpenClaw build from inside the plugin.
+ *
+ * Two independent sources, both read, neither invented:
+ *
+ *   - `api.runtime.version` — the running gateway's own statement of its
+ *     version, captured at register() (see `recordHostRuntimeVersion`). This is
+ *     the primary VERSION evidence when the host offers it. Note it is not
+ *     `api.version`, which is this plugin's version.
+ *   - the filesystem — walk up from the gateway's entry path to the package.json
+ *     that names openclaw, then read that install's own shipped hook
+ *     declarations. This is the version FALLBACK, and it is the only source of
+ *     `declaresGate`, which stays the strongest gate-support evidence of the two
+ *     (a backport or a fork answers it correctly where a version comparison
+ *     cannot — see `hostSupportsConversationGate`).
+ *
+ * No process is ever spawned. A null everywhere is a legitimate, frequently
+ * correct answer (a CLI invocation, an unusual install layout) and callers must
+ * treat it as UNKNOWN — never as "supported".
+ */
+export function detectHostOpenClaw() {
+    const disk = detectHostOpenClawFromDisk();
+    // The runtime's own version outranks whatever package.json the walk landed
+    // on — but only for the version; `declaresGate` and `root` are disk facts and
+    // are carried through untouched.
+    if (_hostRuntimeVersion)
+        return { ...disk, version: _hostRuntimeVersion, versionSource: 'runtime' };
+    return disk;
+}
+function detectHostOpenClawFromDisk() {
+    if (_hostProbeOverride !== undefined)
+        return _hostProbeOverride ?? { version: null, root: null, declaresGate: null };
+    if (_hostProbeCache !== undefined)
+        return _hostProbeCache;
+    _hostProbeCache = (() => {
+        const empty = { version: null, root: null, declaresGate: null, versionSource: null };
+        const entry = process.argv?.[1];
+        if (!entry || typeof entry !== 'string')
+            return empty;
+        let current;
+        try {
+            current = path.dirname(realpathSync(entry));
+        }
+        catch {
+            current = path.dirname(entry);
+        }
+        let previous = '';
+        for (let i = 0; i < 8 && current !== previous; i++) {
+            try {
+                const pkgPath = path.join(current, 'package.json');
+                if (existsSync(pkgPath)) {
+                    const hostPkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+                    if (hostPkg?.name === 'openclaw') {
+                        const version = typeof hostPkg.version === 'string' ? hostPkg.version : null;
+                        return {
+                            version,
+                            versionSource: version ? 'package.json' : null,
+                            root: current,
+                            declaresGate: probeGateDeclaration(current),
+                        };
+                    }
+                }
+            }
+            catch { /* keep walking up */ }
+            previous = current;
+            current = path.dirname(current);
+        }
+        return empty;
+    })();
+    return _hostProbeCache;
+}
+/** Convenience for callers that only want the version string. */
+export function detectHostOpenClawVersion() {
+    return detectHostOpenClaw().version;
+}
+/**
+ * Does this host have the `before_agent_run` gate at all?
+ *
+ * Order matters: what the installed build DECLARES outranks what its version
+ * number implies, and both outrank a guess. There is no branch here that
+ * returns 'supported' without evidence.
+ */
+export function hostSupportsConversationGate(probe) {
+    const resolved = typeof probe === 'string' || probe === null
+        ? { version: probe, root: null, declaresGate: null }
+        : probe;
+    if (resolved.declaresGate === true)
+        return 'supported';
+    if (resolved.declaresGate === false)
+        return 'unsupported';
+    if (!resolved.version)
+        return 'unknown';
+    const cmp = compareOpenClawVersions(resolved.version, CONVERSATION_GATE_MIN_OPENCLAW);
+    if (cmp === null)
+        return 'unknown';
+    if (cmp >= 0)
+        return 'supported';
+    // Below the STABLE floor. One band inside that is not honestly 'unsupported':
+    // 2026.5.9-beta.1 → 2026.5.11 ship the hook as a prerelease, so calling them
+    // unsupported would tell an operator "no posture can block a turn on this
+    // host" about a host that blocks. The opposite claim is worse still, so
+    // neither is made: this is the absence of a measurement, and
+    // `describeConversationPlane` renders it as UNPROVEN and active:false.
+    //
+    // In practice a real prerelease install lands on `declaresGate` above and
+    // never reaches here — this branch is what happens when the declarations
+    // could not be read either, i.e. when we genuinely do not know.
+    const pre = compareOpenClawVersions(resolved.version, CONVERSATION_GATE_FIRST_PRERELEASE_OPENCLAW);
+    if (pre === null)
+        return 'unknown';
+    return pre >= 0 ? 'unknown' : 'unsupported';
+}
+/**
+ * Read the operator's CONVERSATION-ACCESS consent for this plugin from the
+ * host config: `plugins.entries.<id>.hooks.allowConversationAccess === true`.
+ *
+ * OpenClaw refuses every conversation hook for a non-bundled plugin without
+ * this exact value (registry: `record.origin !== "bundled" &&
+ * explicitConversationAccess !== true`). `llm_input` and `llm_output` are on
+ * that list in every build; `before_agent_run` joins it in 2026.5.9-beta.1,
+ * the same build that first declares the gate at all — so from there on the
+ * grant governs the conversation firewall's enforcement point too.
+ * Strict `true` only, matching the host: `undefined` and `false` are the same
+ * refusal there, and reading them differently here would report protection the
+ * gateway is not providing.
+ *
+ * It is the operator's per-box CONSENT grant, and this plugin only ever READS
+ * it. Nothing on the plugin's own path — `register()`, a hook, a background
+ * refresh — may write it: a security product that silently grants itself the
+ * right to read every conversation is the behaviour this product exists to
+ * catch. The only thing that may set it is an explicit, operator-initiated
+ * install/repair that says so out loud (#225: "the installer must never set it
+ * silently"). Absence is therefore reported, loudly and by name, rather than
+ * fixed from in here.
+ */
+export function readConversationAccessGrant(rootConfig) {
+    if (!rootConfig || typeof rootConfig !== 'object' || Array.isArray(rootConfig))
+        return false;
+    const entries = rootConfig.plugins?.entries;
+    const entry = entries?.[PLUGIN_ID] ?? entries?.[PLUGIN_PACKAGE_NAME];
+    return entry?.hooks?.allowConversationAccess === true;
+}
+export function describeConversationPlane(input) {
+    const { posture, hookRequested, gateSupport, hostOpenClawVersion, consentGranted } = input;
+    const hostText = hostOpenClawVersion ? `OpenClaw ${hostOpenClawVersion}` : 'OpenClaw version undetermined';
+    if (posture === 'off') {
+        return {
+            ...input,
+            active: false,
+            summary: 'off — conversation scanning disabled by config (interceptor.conversation.posture=off)',
+        };
+    }
+    if (!consentGranted) {
+        return {
+            ...input,
+            active: false,
+            summary: `INACTIVE: conversation access NOT granted on this host — set plugins.entries.${PLUGIN_ID}.hooks.allowConversationAccess=true ` +
+                'in openclaw.json (operator consent; the installer will never set it for you). Until then the gateway REFUSES llm_input and ' +
+                'llm_output for this plugin — and, on builds that have it, before_agent_run too: nothing on the conversation path is scanned or blocked',
+        };
+    }
+    if (gateSupport === 'unsupported') {
+        return {
+            ...input,
+            active: false,
+            summary: `INACTIVE for enforcement: ${hostText} predates the before_agent_run gate ` +
+                `(floor ${CONVERSATION_GATE_MIN_OPENCLAW}; first seen as a prerelease in ${CONVERSATION_GATE_FIRST_PRERELEASE_OPENCLAW}) — ` +
+                'observation only; no posture can block a turn on this host',
+        };
+    }
+    if (!hookRequested) {
+        return { ...input, active: false, summary: 'INACTIVE: the before_agent_run hook was not registered this session' };
+    }
+    if (gateSupport === 'unknown') {
+        // UNPROVEN IS NOT ACTIVE. Every other branch above is a fact we read — the
+        // posture, the grant, the host build. This one is the absence of a
+        // measurement: we could not establish that this host has the gate at all,
+        // and `api.on` does not acknowledge a registration, so nothing here knows
+        // whether the hook exists. Reporting `active: true` with a caveat glued to
+        // the summary string — which is what this did — means every caller that
+        // reads the boolean instead of the prose (status renderers, doctor, any
+        // future check) claims a live firewall on evidence nobody has. Under
+        // `enforce` that is the worst version of it: the operator believes turns
+        // are being blocked on a host where the gate may be silently dropped.
+        return {
+            ...input,
+            active: false,
+            summary: `UNPROVEN: could not verify that host ${hostText} provides the before_agent_run gate ` +
+                `(no runtime version, no readable hook declarations), and the plugin API does not acknowledge a registration. ` +
+                (posture === 'enforce'
+                    ? 'The posture is enforce, so a dirty verdict WOULD block the run where the gate exists — but that it exists here is not established. Treat this host as observation-only until it is.'
+                    : 'Detections are audited and sent to the operator where the hook runs at all; nothing is blocked in this posture regardless.'),
+        };
+    }
+    return {
+        ...input,
+        active: true,
+        summary: posture === 'enforce'
+            ? 'enforce — a dirty verdict BLOCKS the run via before_agent_run'
+            : 'observe — detections are audited and sent to the operator; turns are NOT blocked',
+    };
+}
 const PLUGIN_ID = "shieldcortex-realtime";
 /**
  * #233: conversation-level taint, shared between the conversation scan (which
@@ -213,6 +785,21 @@ const PLUGIN_CONFIG_UI_HINTS = {
         label: "Enable Tool Call Interceptor",
         help: "Scan memory-write tool calls and gate suspicious content behind user approval.",
     },
+    // #226: these two exist in openclaw.plugin.json's uiHints and were missing
+    // here, so the host UI and the plugin's own declared hints described
+    // different sets of settings. The manifest parity test now pins the two key
+    // sets EQUAL in both directions, because a hint present on only one side is
+    // a setting one surface documents and the other silently omits.
+    "interceptor.severityActions.high": {
+        label: "High Severity Action",
+        help: "Action for high-severity threats: log, warn, or require_approval.",
+        advanced: true,
+    },
+    "interceptor.severityActions.critical": {
+        label: "Critical Severity Action",
+        help: "Action for critical-severity threats: log, warn, or require_approval.",
+        advanced: true,
+    },
     "interceptor.actionGuard.enabled": {
         label: "Action Guard",
         help: "Gate dangerous shell/file/network/git tool calls before they execute. Catastrophic operations are always blocked while enabled.",
@@ -241,6 +828,38 @@ const PLUGIN_CONFIG_UI_HINTS = {
         help: "Off = every dangerous-tier action still waits for you; the broker can then only harden, never release.",
         advanced: true,
     },
+    // #225. The posture is the whole product claim on the conversation path, so
+    // it is NOT marked advanced: an operator must be able to see, in the UI that
+    // configures this plugin, whether the firewall in front of their prompts can
+    // stop anything.
+    "interceptor.conversation.posture": {
+        label: "Conversation Firewall",
+        help: "What the conversation firewall does with a detection on the input path. " +
+            "off = do not scan; observe = scan, audit and alert the operator but never stop the turn (default); " +
+            "enforce = block the run via before_agent_run. Requires plugins.entries.shieldcortex-realtime.hooks.allowConversationAccess=true " +
+            "on this host — OpenClaw refuses conversation hooks without that operator grant, and ShieldCortex will never set it for you.",
+    },
+    "interceptor.actionGuard.notify.enabled": {
+        label: "Operator Notifications",
+        help: "Reach a human when the guard holds an action, or when the conversation firewall detects a threat. Off by default.",
+        advanced: true,
+    },
+    "interceptor.actionGuard.notify.webhookUrl": {
+        label: "Notify Webhook URL",
+        help: "http(s) endpoint the notification is POSTed to. Conversation-firewall alerts carry no approve/deny affordance — there is nothing to approve.",
+        advanced: true,
+    },
+    "interceptor.actionGuard.notify.webhookSecret": {
+        label: "Notify Webhook Secret",
+        help: "HMAC-SHA256 key for X-ShieldCortex-Signature, so the receiver can reject spoofed POSTs.",
+        sensitive: true,
+        advanced: true,
+    },
+    "interceptor.actionGuard.notify.openclaw": {
+        label: "Notify via OpenClaw",
+        help: "Deliver through the gateway's own channel where the runtime provides that seam.",
+        advanced: true,
+    },
 };
 const SEVERITY_ACTION_SCHEMA = {
     type: "object",
@@ -252,63 +871,137 @@ const FAILURE_POLICY_SCHEMA = {
     additionalProperties: false,
     properties: Object.fromEntries(INTERCEPT_SEVERITIES.map((severity) => [severity, { type: "string", enum: [...FAILURE_ACTIONS] }])),
 };
-const INTERCEPTOR_JSON_SCHEMA = {
+/** #225. Mirrored verbatim into openclaw.plugin.json's configSchema — the host
+ *  validates the on-disk config against THAT file, so a posture accepted here
+ *  and absent there is a config an operator writes from our own docs and the
+ *  gateway rejects. */
+const CONVERSATION_JSON_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        posture: {
+            type: "string",
+            enum: [...CONVERSATION_POSTURES],
+            default: "observe",
+            description: "off = do not scan the conversation; observe = scan, audit and alert but never block (default); " +
+                "enforce = block the run on a dirty verdict via before_agent_run.",
+        },
+    },
+};
+/** #235/#226. Mirrored verbatim into openclaw.plugin.json's configSchema, for
+ *  the same reason as the conversation posture above: the host validates the
+ *  on-disk config against THAT file, and a key our parser reads but neither
+ *  schema declares is one an operator cannot set at all. */
+const CONVERSATION_TRUST_JSON_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        trustOwnerInput: {
+            type: "boolean",
+            default: true,
+            description: "Default true: a message the host attributes to the gateway OWNER is an instruction, so a detection in it " +
+                "is audited and alerted but never taints the session or blocks the turn. Set false on a host where the owner " +
+                "routinely pastes untrusted content and you would rather have the caution than the quiet. Content from " +
+                "anyone else — including another agent on a trusted channel — is data regardless of this setting.",
+        },
+    },
+};
+/**
+ * The Action Guard block, declared ONCE and mounted in BOTH places the parser
+ * accepts it (#226).
+ *
+ * `normaliseConfig` has read a TOP-LEVEL `actionGuard` since #209 — that is the
+ * canonical location, and `interceptor.actionGuard` is the deprecated alias
+ * kept for pre-#209 configs. The schemas said the opposite: only the nested
+ * alias was declared, under `additionalProperties: false`, so a config written
+ * from our own documentation — `actionGuard.notify` at the top level — was
+ * rejected as an unknown key by any host that validates against the schema.
+ * The parser would have kept it; the config never reached the parser. That is
+ * the shape behind the original `parsedNotify: null` reproduction.
+ *
+ * One constant, two mount points, so the two can never drift. Mirrored by hand
+ * into openclaw.plugin.json's configSchema (the host validates the on-disk
+ * config against THAT file) and pinned equal by manifest-config-schema-226.test.ts.
+ */
+const ACTION_GUARD_JSON_SCHEMA = {
     type: "object",
     additionalProperties: false,
     properties: {
         enabled: { type: "boolean" },
-        severityActions: SEVERITY_ACTION_SCHEMA,
-        failurePolicy: FAILURE_POLICY_SCHEMA,
-        actionGuard: {
+        enforce: { type: "boolean" },
+        autoApprove: { type: "array", items: { type: "string" } },
+        auditAllows: { type: "boolean" },
+        // #143. Mirrors normaliseBrokerConfig's allowlist; that function still
+        // has the last word, so a value that slips past the schema is still
+        // range-checked (and dropped) before the broker sees it.
+        broker: {
             type: "object",
             additionalProperties: false,
             properties: {
                 enabled: { type: "boolean" },
-                enforce: { type: "boolean" },
-                autoApprove: { type: "array", items: { type: "string" } },
-                auditAllows: { type: "boolean" },
-                // #143. Mirrors normaliseBrokerConfig's allowlist; that function still
-                // has the last word, so a value that slips past the schema is still
-                // range-checked (and dropped) before the broker sees it.
-                broker: {
+                allowPreClear: { type: "boolean" },
+                preClearConfidence: { type: "number", minimum: 0.9, maximum: 1 },
+                judgeTimeoutMs: { type: "number", minimum: 500, maximum: 60000 },
+                approvalTimeoutMs: {
                     type: "object",
                     additionalProperties: false,
                     properties: {
-                        enabled: { type: "boolean" },
-                        allowPreClear: { type: "boolean" },
-                        preClearConfidence: { type: "number", minimum: 0.9, maximum: 1 },
-                        judgeTimeoutMs: { type: "number", minimum: 500, maximum: 60000 },
-                        approvalTimeoutMs: {
-                            type: "object",
-                            additionalProperties: false,
-                            properties: {
-                                sensitive: { type: "number", minimum: 1000, maximum: 3600000 },
-                                dangerous: { type: "number", minimum: 1000, maximum: 3600000 },
-                            },
-                        },
-                        model: { type: "string" },
+                        sensitive: { type: "number", minimum: 1000, maximum: 3600000 },
+                        dangerous: { type: "number", minimum: 1000, maximum: 3600000 },
                     },
                 },
-                // #189. Each entry pins one script by absolute path + content hash;
-                // createReviewedScriptCheck has the last word on every field.
-                reviewedScripts: {
-                    type: "array",
-                    items: {
-                        type: "object",
-                        additionalProperties: false,
-                        properties: {
-                            path: { type: "string" },
-                            sha256: { type: "string" },
-                            note: { type: "string" },
-                            addedAt: { type: "number" },
-                        },
-                        required: ["path", "sha256"],
-                    },
+                model: { type: "string" },
+            },
+        },
+        // #143/#225. Mirrors NotifyConfig in notify-config.ts, which still has
+        // the last word (strict-true booleans, http(s)-only URL, bounded
+        // timeout). Declared here because `additionalProperties: false` above
+        // means an undeclared key makes the WHOLE containing block invalid on
+        // a host that validates config against this schema — which is how the
+        // Action Guard's notify transport came to be unusable from inside the
+        // gateway plugin at all.
+        notify: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                enabled: { type: "boolean" },
+                webhookUrl: { type: "string" },
+                webhookSecret: { type: "string" },
+                openclaw: { type: "boolean" },
+                timeoutMs: { type: "number", minimum: 500, maximum: 60000 },
+            },
+        },
+        // #189. Each entry pins one script by absolute path + content hash;
+        // createReviewedScriptCheck has the last word on every field.
+        reviewedScripts: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    path: { type: "string" },
+                    sha256: { type: "string" },
+                    note: { type: "string" },
+                    addedAt: { type: "number" },
                 },
+                required: ["path", "sha256"],
             },
         },
     },
 };
+const INTERCEPTOR_JSON_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        enabled: { type: "boolean" },
+        severityActions: SEVERITY_ACTION_SCHEMA,
+        failurePolicy: FAILURE_POLICY_SCHEMA,
+        conversation: CONVERSATION_JSON_SCHEMA,
+        /** The DEPRECATED alias (#209). Still accepted, still parsed, still
+         *  gap-fills the canonical top-level block key by key. */
+        actionGuard: ACTION_GUARD_JSON_SCHEMA,
+    },
+};
 const PLUGIN_CONFIG_JSON_SCHEMA = {
     type: "object",
     additionalProperties: false,
@@ -331,6 +1024,15 @@ const PLUGIN_CONFIG_JSON_SCHEMA = {
         // #112: without this, `additionalProperties: false` declared the whole
         // interceptor block invalid — mirror openclaw.plugin.json's configSchema.
         interceptor: INTERCEPTOR_JSON_SCHEMA,
+        // #209/#226: the CANONICAL Action Guard location. normaliseConfig has read
+        // it here since #209 and folds it over the nested alias; the schema did not
+        // declare it, so `additionalProperties: false` rejected the documented
+        // config shape before the parser ever saw it.
+        actionGuard: ACTION_GUARD_JSON_SCHEMA,
+        // #235/#226: source trust. Same reason as `actionGuard` above — the parser
+        // reads it, so the schema must declare it or `additionalProperties: false`
+        // rejects the whole config an operator writes from our documentation.
+        conversationTrust: CONVERSATION_TRUST_JSON_SCHEMA,
     },
 };
 let _config = null;
@@ -369,6 +1071,17 @@ let _registered = false;
 // unattended Codex agents even a no-op registered hook changes how OpenClaw
 // resolves approvals).
 let _beforeToolCallRegistered = false;
+// #225: whether we CALLED api.on('before_agent_run', …) this session — nothing
+// more. It is deliberately not named "…Accepted": `api.on` returns void, never
+// throws on an unknown hook name, and never throws when the host refuses a
+// conversation hook (it records a diagnostic and returns), so acceptance is not
+// observable from in here. The two facts that decide whether the plane is live
+// — host build ≥ the gate's floor, and the operator's allowConversationAccess
+// grant — are read separately and reported by describeConversationPlane().
+let _beforeAgentRunRequested = false;
+// The operator's conversation-access grant as read from the host config at
+// register() time. Reported by /shieldcortex-status; never written by us.
+let _conversationAccessGranted = false;
 // #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
@@ -421,6 +1134,20 @@ function normaliseConfig(raw, dropped) {
     const interceptor = normaliseInterceptorConfig(value.interceptor, dropped);
     if (interceptor)
         config.interceptor = interceptor;
+    // Source trust (#235, wired to the gate in #226). Booleans only, and the
+    // block is kept only when it holds a valid one: a `trustOwnerInput: "false"`
+    // typo — the exact shape of the #112 incident — must not read as the opt-out
+    // having been applied, because the operator who wrote it believes owner input
+    // is being policed and it would not be.
+    if (value.conversationTrust && typeof value.conversationTrust === "object" && !Array.isArray(value.conversationTrust)) {
+        const trustRaw = value.conversationTrust;
+        if (typeof trustRaw.trustOwnerInput === "boolean") {
+            config.conversationTrust = { trustOwnerInput: trustRaw.trustOwnerInput };
+        }
+        else if (trustRaw.trustOwnerInput !== undefined) {
+            dropped?.push("conversationTrust.trustOwnerInput");
+        }
+    }
     // #209: single source of truth for the Action Guard. A top-level
     // `actionGuard` block governs every surface; `interceptor.actionGuard` is a
     // deprecated alias kept as per-key gap-fill so pre-#209 configs keep their
@@ -521,6 +1248,20 @@ function normaliseActionGuardBlock(raw, dropped, pathPrefix) {
     if (Array.isArray(rawGuard.reviewedScripts)) {
         guard.reviewedScripts = [...rawGuard.reviewedScripts];
     }
+    // #143/#225: the notify transport. Same passthrough discipline again —
+    // normaliseNotifyConfig is the boundary. Shallow-copied rather than aliased
+    // (the #115 reason: a later in-place mutation of the host config object must
+    // not reach into the normalised one), and a non-object is DROPPED by name so
+    // the #115 warn log can say which key was ignored, rather than silently
+    // leaving the operator with a transport that never fires.
+    if (rawGuard.notify !== undefined) {
+        if (rawGuard.notify && typeof rawGuard.notify === 'object' && !Array.isArray(rawGuard.notify)) {
+            guard.notify = { ...rawGuard.notify };
+        }
+        else {
+            dropped?.push(`${pathPrefix}.notify`);
+        }
+    }
     return Object.keys(guard).length > 0 ? guard : undefined;
 }
 function normaliseInterceptorConfig(raw, dropped) {
@@ -543,6 +1284,25 @@ function normaliseInterceptorConfig(raw, dropped) {
     const actionGuard = normaliseActionGuardBlock(value.actionGuard, dropped, "interceptor.actionGuard");
     if (actionGuard)
         out.actionGuard = actionGuard;
+    // #225: conversation posture. An invalid value is DROPPED (and named in the
+    // warn log) rather than coerced, so `conversationPosture()` falls back to
+    // `observe` — the safe direction. A typo must never start blocking turns.
+    if (value.conversation !== undefined) {
+        if (value.conversation && typeof value.conversation === "object" && !Array.isArray(value.conversation)) {
+            const posture = value.conversation.posture;
+            if (posture !== undefined) {
+                if (typeof posture === "string" && CONVERSATION_POSTURES.includes(posture)) {
+                    out.conversation = { posture: posture };
+                }
+                else {
+                    dropped?.push("interceptor.conversation.posture");
+                }
+            }
+        }
+        else {
+            dropped?.push("interceptor.conversation");
+        }
+    }
     // #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.
@@ -554,6 +1314,19 @@ function normaliseInterceptorConfig(raw, dropped) {
  *  - `interceptor` deep-merges PER KEY — per severity entry, per guard flag —
  *    so an override that sets one nested key does not wholesale-discard the
  *    base's other interceptor settings.
+ *  - `actionGuard.notify` and `actionGuard.broker` deep-merge per key too
+ *    (#226). They are the two OBJECT-valued guard keys, and a shallow spread
+ *    replaced them wholesale: an openclaw.json entry that says only
+ *    `notify: { enabled: true }` — the shape the UI writes when an operator
+ *    ticks "Operator Notifications" — discarded the shield config's
+ *    `webhookUrl` and `webhookSecret`, leaving notify ARMED with no channel and
+ *    no signing key. Every alert then reported "enabled but no channel is
+ *    configured/buildable on this host", which is the #143 silent-no-sink
+ *    failure in a new place.
+ *  - ARRAY-valued keys (`autoApprove`, `reviewedScripts`) still REPLACE. They
+ *    are allowlists: merging two of them would union permissions an operator
+ *    removed back into the effective config, which is the wrong direction for a
+ *    security control.
  *  - Explicit values, including `false`, always win over base values; absent
  *    keys fall through to the base.
  *  - Defaults are NOT applied here: DEFAULT_INTERCEPTOR_CONFIG only fills the
@@ -562,6 +1335,13 @@ function normaliseInterceptorConfig(raw, dropped) {
  */
 function mergeConfigs(base, override) {
     const merged = { ...base, ...override };
+    // Per-key, like every other nested block here. A plain spread would let an
+    // openclaw.json entry that mentions `conversationTrust` at all replace the
+    // shield-config block wholesale, silently reverting an opt-out set in the
+    // file the operator considers authoritative.
+    if (base.conversationTrust || override.conversationTrust) {
+        merged.conversationTrust = { ...base.conversationTrust, ...override.conversationTrust };
+    }
     if (base.interceptor || override.interceptor) {
         const b = base.interceptor ?? {};
         const o = override.interceptor ?? {};
@@ -573,7 +1353,14 @@ function mergeConfigs(base, override) {
             merged.interceptor.failurePolicy = { ...b.failurePolicy, ...o.failurePolicy };
         }
         if (b.actionGuard || o.actionGuard) {
-            merged.interceptor.actionGuard = { ...b.actionGuard, ...o.actionGuard };
+            const bg = b.actionGuard ?? {};
+            const og = o.actionGuard ?? {};
+            const guard = { ...bg, ...og };
+            if (bg.notify || og.notify)
+                guard.notify = { ...bg.notify, ...og.notify };
+            if (bg.broker || og.broker)
+                guard.broker = { ...bg.broker, ...og.broker };
+            merged.interceptor.actionGuard = guard;
         }
     }
     return merged;
@@ -610,8 +1397,58 @@ function applyPluginConfigOverride(api) {
     _config = null;
     _lastShieldConfigRef = null;
 }
+/**
+ * Load the effective config, DEGRADING rather than throwing (#226).
+ *
+ * `getRuntime()` resolves `shieldcortex/dist/…/runtime.mjs` by walking a list of
+ * install locations, and `loadShieldConfig()` then reads a file. Both can fail
+ * for ordinary reasons — the package was upgraded underneath a running gateway,
+ * a global install moved, `~/.shieldcortex/config.json` is half-written.
+ *
+ * This used to propagate, and the propagation went somewhere bad: every caller
+ * of `loadConfig` is a hook body, and in `handleBeforeAgentRun` the throw was
+ * caught by the OUTER catch — the one that fails open. So a host that could not
+ * load the runtime produced one console line per turn and NOTHING else: no
+ * posture, no scan, no audit row, no alert. Precisely the "unprotected turn that
+ * leaves no trace" the #225/#226 work exists to eliminate, reintroduced through
+ * the config read rather than through the scanner.
+ *
+ * Now it degrades to the plugin config from openclaw.json (already normalised by
+ * `applyPluginConfigOverride`), or to an empty config. The posture therefore
+ * still resolves, the scan still runs, `scanRealtimeContent` reports UNAVAILABLE
+ * on its own (the same runtime failure defeats the MCP fallback), and the gate
+ * writes its normal audit row and raises its normal alert.
+ *
+ * It does NOT cache the degraded result — a later successful load must take
+ * effect without a restart — and it never claims the shield config loaded: the
+ * warning says exactly what is missing, and is bounded, redacted, and emitted
+ * ONCE per plugin load (`__resetConfigStateForTest` re-arms it) so a per-turn
+ * failure cannot become per-turn log spam.
+ */
+let _shieldConfigLoadFailureLogged = false;
 async function loadConfig() {
-    const shieldConfigRaw = await (await getRuntime()).loadShieldConfig();
+    let shieldConfigRaw;
+    try {
+        shieldConfigRaw = await (await getRuntime()).loadShieldConfig();
+    }
+    catch (err) {
+        if (!_shieldConfigLoadFailureLogged) {
+            _shieldConfigLoadFailureLogged = true;
+            const detail = redactNotifyDetail(err instanceof Error ? err.message : String(err)).slice(0, 300);
+            console.warn('[shieldcortex] ⚠️ shield config could NOT be loaded — the ShieldCortex runtime did not resolve, ' +
+                `or it could not read ~/.shieldcortex/config.json (${detail}). Continuing with the openclaw.json ` +
+                'plugin config only; anything configured in the shield config file is NOT in effect, and ' +
+                'conversation scanning will report UNAVAILABLE until this is fixed. (Logged once per plugin load.)');
+        }
+        // A fresh object every time: `_configOverride` is module state and callers
+        // must not be handed something they could mutate.
+        return mergeConfigs({}, _configOverride ?? {});
+    }
+    // A load that succeeds after a failure re-arms the warning, so a SECOND
+    // outage is reported rather than swallowed by the first one's flag. Set
+    // before the cache check: a runtime that hands back the same object every
+    // call would otherwise take the early return and leave the flag latched.
+    _shieldConfigLoadFailureLogged = false;
     if (_config && shieldConfigRaw === _lastShieldConfigRef)
         return _config;
     _lastShieldConfigRef = shieldConfigRaw;
@@ -643,33 +1480,127 @@ function parseScanResponse(response) {
     const summary = detections ? `${risk} (${detections} detections)` : risk;
     return { clean, summary };
 }
+/**
+ * Scan one piece of conversation content.
+ *
+ * The contract changed in #225 and the change is the point: an unavailable
+ * scanner is now reported as `available: false, clean: false`, not as the old
+ * `{ clean: true, summary: 'scan unavailable' }`. That old return was the
+ * quietest bug in this file — the ORDINARY unavailable path (MCP fallback
+ * returns nothing, e.g. no shieldcortex binary on PATH) manufactured a clean
+ * verdict, so on any box where in-process defence failed to load, every message
+ * was reported scanned-and-fine while nothing had been looked at.
+ *
+ * Fails OPEN — callers must not block on `available: false` — but LOUDLY: the
+ * caller audits it, alerts on it, and doctor/status report the plane as
+ * unavailable rather than protected.
+ */
 export async function scanRealtimeContent(text) {
     // PRIMARY: scan in-process via the shared shieldcortex/defence module. The
     // scan is pure (no DB handle required — scanToolResponse's audit write is
     // guarded by isDatabaseInitialized()), so it is safe in the long-lived
     // gateway and avoids booting a cold MCP server per message.
-    const defenceMod = await getDefenceModule();
+    let defenceMod = null;
+    try {
+        defenceMod = await getDefenceModule();
+    }
+    catch (err) {
+        defenceMod = null;
+        void err;
+    }
     if (defenceMod && typeof defenceMod.scanToolResponse === "function") {
-        const scan = defenceMod.scanToolResponse("openclaw-realtime", text, "advisory");
-        // Reproduce the historical summary contract exactly: risk level + detection
-        // count only when the injection scan flagged something.
-        const risk = scan.injection.clean ? "unknown" : scan.injection.riskLevel;
-        const summary = scan.injection.clean
-            ? risk
-            : `${risk} (${scan.injection.detections.length} detections)`;
-        return { clean: scan.clean, summary };
+        try {
+            const scan = defenceMod.scanToolResponse("openclaw-realtime", text, "advisory");
+            // Reproduce the historical summary contract exactly: risk level + detection
+            // count only when the injection scan flagged something.
+            const risk = scan.injection.clean ? "unknown" : scan.injection.riskLevel;
+            const summary = scan.injection.clean
+                ? risk
+                : `${risk} (${scan.injection.detections.length} detections)`;
+            return { clean: scan.clean, summary, available: true };
+        }
+        catch (err) {
+            // A scanner that THROWS is not a clean verdict either. Same treatment as
+            // an absent one: unavailable, reported, never silently allowed to read as
+            // protected.
+            const detail = err instanceof Error ? err.message : String(err);
+            return { clean: false, available: false, errored: true, error: `in-process scanner threw: ${detail}`, summary: "scan unavailable" };
+        }
     }
     // FALLBACK: in-process defence unavailable (older install, import failed) —
     // degrade to the MCP shell-out so scanning still happens rather than breaking.
-    const response = await callCortex("scan_tool_response", {
-        toolName: "openclaw-realtime",
-        content: text,
-        mode: "advisory",
-    });
+    let response = null;
+    try {
+        response = await callCortex("scan_tool_response", {
+            toolName: "openclaw-realtime",
+            content: text,
+            mode: "advisory",
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return { clean: false, available: false, errored: true, error: `scan fallback failed: ${detail}`, summary: "scan unavailable" };
+    }
     if (!response) {
-        return { clean: true, summary: "scan unavailable" };
+        return {
+            clean: false,
+            available: false,
+            errored: true,
+            error: 'no in-process defence module and the MCP fallback returned nothing',
+            summary: 'scan unavailable',
+        };
+    }
+    const parsed = parseScanResponse(response);
+    return { ...parsed, available: true };
+}
+/**
+ * `scanRealtimeContent` with a hard deadline (#226).
+ *
+ * Used ONLY by the `before_agent_run` gate, which the gateway awaits: an
+ * unbounded scan there is an unbounded pause in front of the user's prompt. The
+ * MCP fallback boots a cold server through `npx` and has been measured at ~15s,
+ * so "it usually returns quickly" is not a bound.
+ *
+ * On expiry the result is an ordinary UNAVAILABLE verdict — fail open, audited,
+ * alerted — and the error string names the deadline and NOTHING ELSE. It must
+ * never quote the prompt: a timeout message is the one error a developer is
+ * most likely to paste into an issue.
+ *
+ * The losing promise is not abandoned silently: a `.catch` is attached before
+ * the race so a scan that rejects AFTER the deadline settles into a no-op
+ * instead of an unhandled rejection that could take the gateway down under
+ * `--unhandled-rejections=strict`.
+ */
+export async function scanWithDeadline(text, timeoutMs = CONVERSATION_SCAN_MAX_MS) {
+    const timedOut = {
+        clean: false,
+        available: false,
+        errored: true,
+        error: `conversation scan exceeded its ${timeoutMs}ms deadline`,
+        summary: 'scan unavailable',
+    };
+    const scan = scanRealtimeContent(text);
+    // Attached BEFORE the race, so a late rejection can never be unhandled.
+    scan.catch(() => { });
+    let timer;
+    try {
+        return await Promise.race([
+            scan,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(timedOut), timeoutMs);
+                // Never hold the process open on the deadline timer alone.
+                timer.unref?.();
+            }),
+        ]);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return { clean: false, available: false, errored: true, error: detail, summary: 'scan unavailable' };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
     }
-    return parseScanResponse(response);
 }
 // ==================== CONTENT PATTERNS ====================
 const PATTERNS = {
@@ -725,17 +1656,52 @@ function extractUserContent(msgs) {
     }
     return out;
 }
-const AUDIT_DIR = path.join(homedir(), ".shieldcortex", "audit");
+/** Where the realtime audit jsonl lives.
+ *
+ *  Resolved PER CALL, and honouring `SHIELDCORTEX_AUDIT_DIR`, so a test can
+ *  exercise the hook end-to-end without appending fabricated "threat" rows to
+ *  a real box's security audit trail. Default is unchanged
+ *  (`~/.shieldcortex/audit`), so nothing moves for an install that does not set
+ *  the variable. */
+function auditDir() {
+    const override = process.env.SHIELDCORTEX_AUDIT_DIR;
+    if (override && override.trim())
+        return override.trim();
+    return path.join(homedir(), ".shieldcortex", "audit");
+}
 const NOVELTY_CACHE_FILE = path.join(homedir(), ".shieldcortex", "openclaw-memory-cache.json");
 const DEFAULT_NOVELTY_THRESHOLD = 0.88;
 const DEFAULT_MAX_RECENT = 300;
 const MIN_NOVELTY_CHARS = 40;
+/**
+ * Append one row to the realtime audit jsonl. Returns WHETHER IT LANDED (#226).
+ *
+ * This used to swallow every failure and return void, so a caller could not
+ * distinguish "the evidence is on disk" from "the disk is full / the audit dir
+ * is not writable / it is a file where a directory should be". The
+ * `before_agent_run` gate then wrote a decision row, got nothing back, and
+ * proceeded to tell the operator — and the delivery row — that the decision was
+ * recorded. A security control claiming evidence it does not have is worse than
+ * one that admits the gap, because the gap is invisible in exactly the incident
+ * where the log matters.
+ *
+ * Still never throws: a broken audit sink must not become a broken turn.
+ */
 async function auditLog(entry) {
+    const dir = auditDir();
     try {
-        await fs.mkdir(AUDIT_DIR, { recursive: true });
-        await fs.appendFile(path.join(AUDIT_DIR, `realtime-${new Date().toISOString().slice(0, 10)}.jsonl`), JSON.stringify(entry) + "\n");
+        await fs.mkdir(dir, { recursive: true });
+        await fs.appendFile(path.join(dir, `realtime-${new Date().toISOString().slice(0, 10)}.jsonl`), JSON.stringify(entry) + "\n");
+        return true;
+    }
+    catch (err) {
+        // LOUD. The detail is the failure and the directory — never the row, which
+        // may carry a verdict summary, and never a credential (nothing in this path
+        // holds one). Bounded so a pathological error message cannot flood stderr.
+        const detail = err instanceof Error ? err.message : String(err);
+        console.error(`[shieldcortex] ⚠️ AUDIT WRITE FAILED (${dir}) — this event is NOT on disk: ${detail.slice(0, 300)}`);
+        return false;
     }
-    catch { }
 }
 function normalizeMemoryText(text) {
     return String(text || "")
@@ -873,6 +1839,17 @@ function isInternalContent(text) {
 // itself stays non-blocking.
 export async function scanLlmInput(event, _ctx) {
     try {
+        // #226: THE POSTURE GOVERNS THIS HOOK TOO. `off` means "do not scan the
+        // conversation at all", and this observation hook used to ignore it
+        // entirely: it scanned every prompt, wrote threat and scan_unavailable rows,
+        // and forwarded detections to the cloud on a box whose operator had
+        // explicitly turned conversation inspection OFF. The gate honoured the
+        // setting, so a reader of `handleBeforeAgentRun` would conclude the product
+        // did too. Read it FIRST, before any scanner, any audit row and any cloud
+        // call, so `off` costs exactly one config read.
+        const cfg = await loadConfig();
+        if (conversationPosture(cfg.interceptor?.conversation) === 'off')
+            return;
         // Only scan user content, skip system/boot/heartbeat prompts
         // Trust is resolved per TURN, not per message: the host tells us who sent
         // this turn, but history messages carry no individual attribution, so there
@@ -884,10 +1861,13 @@ export async function scanLlmInput(event, _ctx) {
         let trustMemo = null;
         const resolveTrust = async () => {
             if (!trustMemo) {
+                // `cfg` is already in hand from the posture read above, so this costs
+                // no I/O. It also reads the PARSED field rather than casting the config
+                // object — the cast this replaces asserted a key that normaliseConfig
+                // drops, so it was always undefined. See SCConfig.conversationTrust.
                 trustMemo = classifyConversationOrigin({
                     senderIsOwner: event.senderIsOwner,
-                    trustOwnerInput: (await loadConfig())
-                        ?.conversationTrust?.trustOwnerInput,
+                    trustOwnerInput: cfg.conversationTrust?.trustOwnerInput,
                 });
             }
             return trustMemo;
@@ -898,6 +1878,33 @@ export async function scanLlmInput(event, _ctx) {
             if (!text || text.length < 10)
                 continue;
             const result = await scanRealtimeContent(text);
+            // #225: "we could not look" is its own outcome. Before this branch the
+            // unavailable path returned clean:true and this loop did nothing at all —
+            // an unscanned message was indistinguishable from a scanned one, on the
+            // observation hook as well as the gate.
+            if (!result.available) {
+                // #226: redacted on the CONSOLE too, not only in the row. The reason
+                // comes from a transport/scanner failure string, which can name the
+                // endpoint it failed to reach — and a gateway's stdout is routinely
+                // shipped to a log aggregator, so "ephemeral" is not a property the
+                // console actually has.
+                const detail = redactNotifyDetail(result.error ?? result.summary);
+                console.warn(`[shieldcortex] ⚠️ conversation scan UNAVAILABLE (${detail}) — this message was NOT scanned`);
+                // AWAITED. The whole function is already fire-and-forget from
+                // `handleLlmInput`, so this blocks nothing the gateway is waiting on —
+                // and it means the row is on disk before the loop moves to the next
+                // message, and that `auditLog`'s new boolean (which logs loudly on
+                // failure) is actually reached rather than discarded into a floating
+                // promise.
+                await auditLog({
+                    type: 'scan_unavailable', hook: 'llm_input', sessionId: event.sessionId,
+                    model: event.model, reason: detail,
+                    chars: text.length,
+                    contentSha256: createHash('sha256').update(text).digest('hex').slice(0, 16),
+                    ts: new Date().toISOString(),
+                });
+                continue;
+            }
             if (!result.clean) {
                 const trust = await resolveTrust();
                 console.warn(`[shieldcortex] ⚠️ Threat in LLM input: ${result.summary} [${trust.origin}]`);
@@ -907,7 +1914,7 @@ export async function scanLlmInput(event, _ctx) {
                 // the Action Guard tighten by one notch for a bounded window.
                 //
                 // Source trust gates the CONSEQUENCE, never the detection: the warn and
-                // the audit row above happen whoever sent this. What trust decides is
+                // the audit row below happen whoever sent this. What trust decides is
                 // whether it may tighten the guard. The operator typing "delete the old
                 // logs" is an instruction, and treating it as an attack is the false
                 // alarm that gets a control switched off. Everything the agent was
@@ -915,17 +1922,28 @@ export async function scanLlmInput(event, _ctx) {
                 if (trust.mayTaint) {
                     sessionTaint.mark(event.sessionId, { reason: `conversation scan: ${result.summary}` });
                 }
+                // #226: NO `preview`. This row carried the first 100 characters of the
+                // prompt — the exact text that tripped an injection detector, i.e.
+                // hostile by assumption — into an append-only file that syncs. The gate
+                // on the very next hook has recorded only `chars` + `contentSha256`
+                // since #225 and says in its own comment that the prompt is never
+                // persisted; the observation hook quietly did the opposite, so the
+                // claim was false on the path that runs on every single turn. Length
+                // plus digest keeps the row correlatable with the gate's row for the
+                // same text without storing the text.
                 const entry = {
                     type: "threat", hook: "llm_input", sessionId: event.sessionId,
                     model: event.model, reason: result.summary,
-                    preview: text.slice(0, 100), ts: new Date().toISOString(),
+                    chars: text.length,
+                    contentSha256: createHash('sha256').update(text).digest('hex').slice(0, 16),
+                    ts: new Date().toISOString(),
                 };
-                auditLog(entry);
+                await auditLog(entry);
                 loadConfig()
                     // Pass the local entry as-is; cloudSync rebuilds a canonical metadata-only
-                    // entry from named fields and never reads preview/content. No raw LLM input
+                    // entry from named fields and never reads content. No raw LLM input
                     // leaves here.
-                    .then(cfg => cloudSync(entry, cfg))
+                    .then(cfg2 => cloudSync(entry, cfg2))
                     .catch(() => { });
             }
         }
@@ -935,9 +1953,625 @@ export async function scanLlmInput(event, _ctx) {
     }
 }
 function handleLlmInput(event, ctx) {
-    // Fire and forget
+    // Fire and forget — OBSERVATION ONLY. This hook cannot block (#225); the
+    // enforcement point is handleBeforeAgentRun below.
     void scanLlmInput(event, ctx);
 }
+/**
+ * Route a conversation-threat detection to a HUMAN (#225).
+ *
+ * This is the "sink" the issue is named for. Before it existed, a HIGH verdict
+ * produced a console line and an audit row, and a real detection on a live box
+ * was seen by nobody. It reuses the Action Guard's notify transport (#143)
+ * rather than inventing a second one — two notification paths would drift, and
+ * the operator would learn which one to ignore.
+ *
+ * Returns whether a human was actually reached, so callers (and doctor) can
+ * report "detected but undeliverable" instead of implying someone was told.
+ * Never throws: a failed notification must not become a failed turn.
+ */
+/** The longest the conversation gate will wait for an operator alert to be
+ *  handed to a transport. See the call site: the user's turn is blocked on this
+ *  hook, so the alert's deadline has to be a fraction of the hook's. */
+const CONVERSATION_NOTIFY_MAX_MS = 5_000;
+/**
+ * The longest the conversation gate will wait for a SCAN (#226).
+ *
+ * `before_agent_run` is awaited by the gateway — the user's turn is stopped
+ * dead until this handler returns — and the scan's fallback path is an MCP
+ * shell-out that boots a cold server via `npx`, which can take upwards of 15s.
+ * That is half the hook's entire 30s budget before an alert and two audit
+ * writes are added behind it, and it happens on exactly the hosts where the
+ * in-process defence module failed to load: the ones already degraded.
+ *
+ * Past this deadline the scan is treated as UNAVAILABLE, which fails OPEN (the
+ * turn proceeds) and is audited and alerted like any other unavailable scan. A
+ * security control that silently adds fifteen seconds to every prompt is one an
+ * operator uninstalls.
+ */
+export const CONVERSATION_SCAN_MAX_MS = 5_000;
+/**
+ * Repeat-alert suppression for the scan-unavailable path (#226).
+ *
+ * An unavailable scanner is not a transient event: it is usually a missing
+ * install, a broken defence build or an absent binary, and it recurs on EVERY
+ * turn. Alerting per turn turns the operator's phone into a metronome and the
+ * alert into something they mute — which is the same outcome as never sending
+ * one, reached by a more expensive route. First occurrence goes immediately;
+ * after that, at most one alert per window, with the suppressed count carried
+ * on the next alert that does go out so nothing is lost.
+ *
+ * THE WINDOW IS PER SESSION, not per process — see `noteScanUnavailable`. A
+ * gateway runs many sessions at once, and "we already told you about session A"
+ * is not a reason to stay silent about session B.
+ *
+ * AUDITING IS NOT RATE LIMITED. Every occurrence still writes its row, and the
+ * row records whether an alert was suppressed and how many have been seen —
+ * the evidence trail must be complete even when the notification stream is not.
+ */
+export const SCAN_UNAVAILABLE_ALERT_WINDOW_MS = 5 * 60_000;
+/**
+ * The bucket used when the host hands us no session identity at all.
+ *
+ * `before_agent_run`'s context declares `sessionId` and `sessionKey` as
+ * OPTIONAL, so both can be absent. Keying such an occurrence under a fixed
+ * fallback keeps rate limiting working exactly as it did on a single-session
+ * host, and — critically — keeps a nameless occurrence from sharing a bucket
+ * with a NAMED one, which is what a `String(undefined)` key would have done.
+ */
+const SCAN_UNAVAILABLE_FALLBACK_SESSION = '__unkeyed-session__';
+/**
+ * Cap on distinct sessions tracked at once.
+ *
+ * `session_end` is what normally frees an entry, and it is not guaranteed: an
+ * older host may not emit it, and a crashed session never will. This map is
+ * therefore bounded and evicts least-recently-seen first. Overshooting the cap
+ * costs at most one extra alert for the evicted session — the safe direction,
+ * since the failure mode of eviction is "tell the operator again", not "stay
+ * quiet". Each entry is four numbers and a short key, so 512 of them is a few
+ * kilobytes in a process that already holds a scanner.
+ */
+export const SCAN_UNAVAILABLE_MAX_SESSIONS = 512;
+const _scanUnavailable = new Map();
+/** Normalise whatever the host gave us into a map key. */
+function scanUnavailableSessionKey(sessionKey) {
+    const trimmed = typeof sessionKey === 'string' ? sessionKey.trim() : '';
+    return trimmed === '' ? SCAN_UNAVAILABLE_FALLBACK_SESSION : trimmed;
+}
+/**
+ * Should this scan-unavailable occurrence raise an operator alert?
+ *
+ * PER SESSION (#226). The first cut kept one module-global counter, which on a
+ * gateway — a process that multiplexes every channel and every concurrent
+ * agent — meant one session's broken scanner silenced the FIRST failure of
+ * every other session for the next five minutes. That is the same class of bug
+ * the rate limit exists to avoid, inverted: instead of too many alerts, a real
+ * new failure is never reported at all. Suppression is a property of one
+ * session's repeating failure, so the state is keyed by one session.
+ *
+ * Pure apart from the per-session counter it advances, and driven by an
+ * injectable `now` so the window is testable without sleeping. Exported for the
+ * regression test; not part of the plugin's host-facing surface.
+ *
+ * The key is a session id, never logged: it reaches this function only to index
+ * the map. The audit rows that carry `sessionId` are the deliberate place that
+ * fact is recorded.
+ */
+export function noteScanUnavailable(sessionKey, nowMs = Date.now()) {
+    const key = scanUnavailableSessionKey(sessionKey);
+    let state = _scanUnavailable.get(key);
+    if (!state) {
+        evictScanUnavailableOverflow(nowMs);
+        state = { count: 0, lastAlertAtMs: null, suppressedSinceAlert: 0, lastSeenAtMs: nowMs };
+        _scanUnavailable.set(key, state);
+    }
+    state.count += 1;
+    state.lastSeenAtMs = nowMs;
+    const last = state.lastAlertAtMs;
+    // A clock that jumped BACKWARDS (NTP step, suspend/resume) must not be able
+    // to wedge alerting off forever: treat a negative elapsed as "window over".
+    const elapsed = last === null ? Infinity : nowMs - last;
+    if (last === null || elapsed >= SCAN_UNAVAILABLE_ALERT_WINDOW_MS || elapsed < 0) {
+        const suppressed = state.suppressedSinceAlert;
+        state.lastAlertAtMs = nowMs;
+        state.suppressedSinceAlert = 0;
+        return { alert: true, count: state.count, suppressedSinceLastAlert: suppressed };
+    }
+    state.suppressedSinceAlert += 1;
+    return {
+        alert: false,
+        count: state.count,
+        suppressedSinceLastAlert: state.suppressedSinceAlert,
+    };
+}
+/** Keep the session map bounded when `session_end` never arrives. Evicts the
+ *  least-recently-seen entries; an evicted session simply alerts once more. */
+function evictScanUnavailableOverflow(nowMs) {
+    if (_scanUnavailable.size < SCAN_UNAVAILABLE_MAX_SESSIONS)
+        return;
+    const oldestFirst = [..._scanUnavailable.entries()].sort((a, b) => (a[1].lastSeenAtMs ?? nowMs) - (b[1].lastSeenAtMs ?? nowMs));
+    const drop = _scanUnavailable.size - SCAN_UNAVAILABLE_MAX_SESSIONS + 1;
+    for (const [key] of oldestFirst.slice(0, drop))
+        _scanUnavailable.delete(key);
+}
+/**
+ * Forget ONE session's suppression window. Called from `session_end`, so a
+ * long-lived gateway does not carry a finished session's suppression into a
+ * reused id — and, just as importantly, does not clear anyone ELSE's.
+ *
+ * A `session_end` that names no session clears the fallback bucket only: on a
+ * host that supplies no session identity every occurrence lands there, so that
+ * is precisely the state that ended.
+ */
+export function resetScanUnavailableAlertState(sessionKey) {
+    _scanUnavailable.delete(scanUnavailableSessionKey(sessionKey));
+}
+/** Test/reset seam: forget EVERY session. Production never wants this — one
+ *  session ending must not re-arm alerting for the others — so it is reachable
+ *  only from `__resetConfigStateForTest`. */
+export function __resetScanUnavailableAlertState() {
+    _scanUnavailable.clear();
+}
+/**
+ * Make a failure detail safe to PERSIST, SEND or PRINT (#226).
+ *
+ * The detail is assembled from channel names, scanner errors and whatever a
+ * transport said went wrong. Node's fetch failures do not name the URL, but a
+ * transport is free to put one in its reason — and a notify webhook URL
+ * routinely carries a token in its path or query
+ * (`https://hooks.example/services/T0/B0/XXXXXXXX`). So any http(s) URL is
+ * reduced to its origin: enough to tell WHICH endpoint failed, not enough to
+ * replay a request to it. Bounded too, so a transport that returns a page of
+ * HTML cannot bloat the log.
+ *
+ * EVERY sink gets the redacted string — not just the ones that obviously
+ * outlive the process. The audit row is append-only and syncs; the notification
+ * leaves the box; and the console is NOT the ephemeral thing an earlier version
+ * of this comment claimed it was, because a gateway's stdout is routinely
+ * shipped to a log aggregator and kept longer than the audit file. Redacting
+ * for the row and not for the other two protected the least exposed of the
+ * three.
+ */
+export function redactNotifyDetail(detail) {
+    const withoutUrls = String(detail ?? '').replace(/https?:\/\/[^\s'"]+/gi, (url) => {
+        try {
+            return `${new URL(url).origin}/…`;
+        }
+        catch {
+            return '<url>';
+        }
+    });
+    return withoutUrls.length > 500 ? `${withoutUrls.slice(0, 499)}…` : withoutUrls;
+}
+/**
+ * The seam a gateway MIGHT offer for sending an operator a message, captured at
+ * register() time if the API exposes it.
+ *
+ * No OpenClaw build we have inspected exposes it — neither 2026.5.2 nor
+ * 2026.7.1 has a `notifyOperator` anywhere in its plugin API — so in practice
+ * the webhook is the load-bearing channel and this stays null. It is read
+ * structurally rather than removed because #143's design intent was that on
+ * OpenClaw the transport should use the gateway's own message capability, and
+ * that only becomes true if the code is ready for the day it appears. Nothing
+ * here should be read as "ShieldCortex delivers natively on OpenClaw today".
+ */
+let _gatewayNotifyContext = null;
+export function __setGatewayNotifyContextForTest(ctx) {
+    _gatewayNotifyContext = ctx;
+}
+/**
+ * Route a conversation-firewall detection to a HUMAN (#225).
+ *
+ * This is the "sink" the issue is named for: before it existed, a HIGH verdict
+ * produced a console line and an audit row, and a real detection on a live box
+ * was seen by nobody.
+ *
+ * It reuses the Action Guard's #143 transport rather than inventing a second
+ * one — but *correctly*, which the first cut did not:
+ *
+ *   - the notification is built by the main package's
+ *     `buildConversationThreatNotification`, so it is a real, bounded
+ *     notification with its own event discriminator, NOT an ad-hoc
+ *     `{kind, severity, …}` literal cast through `NotifyChannel.send`. A
+ *     conversation alert therefore cannot render Approve/Deny controls or a
+ *     hash that does not exist — the fields simply are not on the type.
+ *   - delivery goes through `deliverOperatorNotification`, the same core the
+ *     approval path uses, so the deadline, the malformed-result handling and
+ *     the "nothing but the boolean is read back" rule are shared, not copied.
+ *   - the webhook secret is read from `webhookSecret` — the field
+ *     `normaliseNotifyConfig` actually returns. Mirroring it as `secret`
+ *     silently produced UNSIGNED POSTs.
+ *   - both channels are offered where the runtime provides them: the gateway's
+ *     own message seam first WHERE IT EXISTS (no build we have inspected
+ *     exposes one — see `_gatewayNotifyContext`), then the configured webhook,
+ *     which is what actually carries an alert off the box today.
+ *
+ * Returns what happened, and NEVER throws: a failed notification must not
+ * become a failed turn.
+ */
+export async function notifyOperatorOfConversationThreat(input) {
+    try {
+        const mod = await getDefenceModule();
+        const cfg = await loadConfig();
+        const raw = cfg.interceptor?.actionGuard?.notify;
+        if (!raw)
+            return { configured: false, delivered: false, via: null, detail: 'no notify config' };
+        if (typeof mod?.normaliseNotifyConfig !== 'function') {
+            return { configured: true, delivered: false, via: null, detail: 'installed shieldcortex build has no notify transport' };
+        }
+        const notify = mod.normaliseNotifyConfig(raw);
+        if (!notify.enabled)
+            return { configured: false, delivered: false, via: null, detail: 'notify disabled' };
+        const channels = [];
+        // The gateway's own message seam, WHERE the runtime provides one. It would
+        // go first, because it would reach the operator on a channel they already
+        // read — but `_gatewayNotifyContext` is null on every build we have
+        // inspected, so in practice this list starts at the webhook below.
+        if (notify.openclaw === true && _gatewayNotifyContext) {
+            const gatewayChannel = createGatewayNotifyChannel(_gatewayNotifyContext);
+            if (gatewayChannel)
+                channels.push(gatewayChannel);
+        }
+        if (notify.webhookUrl && typeof mod.createWebhookNotifyChannel === 'function') {
+            channels.push(mod.createWebhookNotifyChannel({
+                url: notify.webhookUrl,
+                // The signing key. Passed straight through and never logged — see
+                // notify-config.ts, which is the only place this value is parsed.
+                secret: notify.webhookSecret,
+            }));
+        }
+        if (channels.length === 0) {
+            return { configured: true, delivered: false, via: null, detail: 'notify enabled but no channel is configured/buildable on this host' };
+        }
+        const notification = typeof mod.buildConversationThreatNotification === 'function'
+            ? mod.buildConversationThreatNotification({
+                outcome: input.outcome,
+                posture: input.posture,
+                summary: input.summary,
+                reason: input.reason,
+                sessionId: input.sessionId,
+                model: input.model,
+                host: hostname(),
+                detectedAt: new Date().toISOString(),
+            })
+            : null;
+        if (!notification) {
+            // An older dist has the transport but not this event. Sending the
+            // approval-shaped payload instead would put an Approve button on an alert
+            // with nothing behind it — refuse, and say why.
+            return {
+                configured: true,
+                delivered: false,
+                via: null,
+                detail: 'installed shieldcortex build predates the conversation-threat notification — refusing to send an approval-shaped alert',
+            };
+        }
+        if (typeof mod.deliverOperatorNotification !== 'function') {
+            return { configured: true, delivered: false, via: null, detail: 'installed shieldcortex build has no notification delivery core' };
+        }
+        const result = await mod.deliverOperatorNotification(notification, {
+            channels,
+            // Bounded HARDER than the transport's own configured deadline, because
+            // this call sits inside a gate the gateway awaits: the user's turn is
+            // waiting on it. The hook is registered with a 30s timeout, and a gate
+            // that exceeds its own timeout is a security control that fails in a way
+            // nobody has reasoned about. The alert is already in the log and the
+            // audit row by this point, so what a longer wait buys is one extra retry
+            // window on a transport that is, by then, visibly unhealthy.
+            timeoutMs: Math.min(notify.timeoutMs ?? CONVERSATION_NOTIFY_MAX_MS, CONVERSATION_NOTIFY_MAX_MS),
+        });
+        const failures = result.attempts
+            .filter((a) => !a.result.delivered)
+            .map((a) => `${a.channel}: ${a.result.reason ?? 'failed'}`)
+            .join('; ');
+        return {
+            configured: true,
+            delivered: result.deliveredVia !== null,
+            via: result.deliveredVia,
+            detail: result.deliveredVia ? `delivered via ${result.deliveredVia}` : `undeliverable — ${failures || 'no channel accepted it'}`,
+        };
+    }
+    catch (err) {
+        return {
+            configured: true,
+            delivered: false,
+            via: null,
+            detail: `notify error: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+/**
+ * The gate's allow answer, stated explicitly (#226).
+ *
+ * A fresh literal per call, not a shared constant: the runner passes whatever
+ * we return into its own merge/normalise chain, and a frozen singleton handed
+ * to a host that decides to annotate it would fail in a way this plugin cannot
+ * see. It costs one object per turn.
+ *
+ * WHY EXPLICIT, when the SDK types the result `InputGateDecision | void` and
+ * this handler previously returned `undefined` on every allow path:
+ *
+ * The 2026.7.1-2 runner contradicts itself about void, one guard deep.
+ * `runBeforeAgentRun`'s doc comment says "Handlers that return void are treated
+ * as pass", and its `mergeResults` body opens with
+ *
+ *     if (next === void 0 || next === null) → { outcome: "block",
+ *                                               reason: "…invalid decision" }
+ *
+ * i.e. the merge is written to BLOCK on void. What saves an `undefined` return
+ * today is only that `runModifyingHook` never calls the merge for it —
+ * `if (handlerResult !== void 0 && (handlerResult !== null || mergeNullResults))`
+ * — so the void branch inside the merge is unreachable dead code, while `null`,
+ * the sibling value that same line treats identically, reaches it and DOES
+ * block. Verified by executing the real 2026.7.1-2 runner: `undefined` → pass,
+ * `null` → block/invalid, `{outcome:'pass'}` → pass.
+ *
+ * So void is not broken here — it is correct by one guard, against a merge
+ * function whose stated intent is to reject it. `{ outcome: 'pass' }` is
+ * correct under BOTH readings, and is the shape the host validates rather than
+ * the shape it happens to skip. That is the difference worth having in front of
+ * every user turn.
+ */
+function gatePass() {
+    return { outcome: 'pass' };
+}
+/**
+ * The conversation firewall's enforcement point (#225).
+ *
+ * Unlike `llm_input`, this hook is awaited by the gateway and its return value
+ * decides whether the run proceeds. It scans the prompt, applies the configured
+ * posture, and — critically — routes a detection to a HUMAN rather than only to
+ * a log file. The finding this fixes was that a HIGH verdict on a live box was
+ * seen by nobody.
+ *
+ * Fails OPEN on any internal error: a security plugin that bricks the gateway
+ * has caused a worse outage than the one it prevents. Every failure is reported.
+ *
+ * EVERY path returns a decision — `gatePass()` to allow, `{ outcome: 'block' }`
+ * only for a dirty verdict under `enforce`. Nothing returns `undefined`; see
+ * `gatePass` for the host-contract reason. "Fails open" therefore now means an
+ * explicit pass, which is a stronger statement than the absence of an answer:
+ * it is the same word said in the vocabulary the host validates.
+ */
+export async function handleBeforeAgentRun(event, ctx) {
+    let posture = 'observe';
+    try {
+        const cfg = await loadConfig();
+        posture = conversationPosture(cfg.interceptor?.conversation);
+        if (posture === 'off')
+            return gatePass();
+        const text = String(event?.prompt ?? '');
+        if (!text || text.length < 10 || isInternalContent(text))
+            return gatePass();
+        // sessionId/model come off the hook CONTEXT (PluginHookAgentContext); the
+        // event carries neither. Both are optional there too, so both may be absent.
+        const sessionId = ctx?.sessionId ?? ctx?.sessionKey;
+        const model = ctx?.modelId;
+        // scanRealtimeContent no longer throws on the paths that used to (it
+        // reports `available:false` instead), but a defensive catch stays: this
+        // function's contract is that nothing here can stop a turn by accident.
+        // #226: BOUNDED. The gateway awaits this hook, so an unbounded scan is an
+        // unbounded pause in front of the user's prompt — see scanWithDeadline.
+        let scan;
+        try {
+            scan = await scanWithDeadline(text);
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            scan = { clean: false, available: false, errored: true, error: detail, summary: 'scan unavailable' };
+        }
+        // #235: WHO sent this turn, resolved before the verdict is applied.
+        // `senderIsOwner` was declared on the event and read by nothing, so the
+        // enforce path could block the operator's own paste and destroy it. The
+        // config is already loaded, so this is a pure call — no second read.
+        const trust = classifyConversationOrigin({
+            senderIsOwner: event?.senderIsOwner,
+            trustOwnerInput: cfg.conversationTrust?.trustOwnerInput,
+        });
+        const decision = evaluateConversationRun(posture, scan, trust);
+        // #226: REDACT ONCE, then use the redacted string everywhere the reason
+        // goes — the persisted decision row, the outbound notification, the block
+        // reason, the console line. On the unavailable path `decision.reason`
+        // embeds the scanner's own failure string verbatim
+        // (`conversation scan unavailable (${scan.error})`), and that string is
+        // assembled from a transport error: a cold MCP start, a fetch, a defence
+        // build download. Any of those can name the endpoint it failed to reach,
+        // and such a URL routinely carries a credential in its path
+        // (`https://hooks.example/services/T0/B0/XXXX`). The console line was
+        // already redacted while the row and the alert — the two that PERSIST and
+        // LEAVE THE BOX — were not, which had the guarantee exactly backwards.
+        const safeReason = decision.reason === null ? null : redactNotifyDetail(decision.reason);
+        // #226: repeated unavailability alerts at most once per window. Called here
+        // rather than at the notify site so the COUNTERS advance on every
+        // occurrence, and the decision row can record what was suppressed even when
+        // no alert goes out.
+        // Keyed by SESSION: a broken scanner in one session must not silence the
+        // first report of a broken scanner in another. `sessionId` may be absent —
+        // noteScanUnavailable buckets that case separately rather than letting one
+        // nameless session stand in for all of them.
+        const unavailable = decision.outcome === 'unavailable';
+        const alertGate = unavailable ? noteScanUnavailable(sessionId) : null;
+        const suppressAlert = alertGate !== null && !alertGate.alert;
+        // ── EVIDENCE FIRST, SIDE EFFECT SECOND ────────────────────────────────
+        //
+        // The decision row is a LOCAL append and it goes to disk before anything
+        // leaves this box. The previous order awaited an external notification and
+        // then wrote the row — under a comment claiming the row already existed —
+        // so every way that call can end badly took the evidence with it: a
+        // notification channel that hangs until the gateway's 30s hook timeout
+        // fires, a transport that throws past its own catch, an operator restarting
+        // the gateway mid-alert, the process dying. In each case the block or the
+        // detection HAPPENED and there is no record that it did. That inverts the
+        // whole point: a security control's own log must not be contingent on an
+        // unrelated network round trip succeeding.
+        //
+        // The row carries a stable `eventId`, so the delivery row appended after
+        // the attempt below can be joined to it without either row having to
+        // predict the other's outcome.
+        const eventId = randomUUID();
+        // #226: whether the decision row ACTUALLY LANDED. `auditLog` used to
+        // swallow its failures and return void, so the code below could not tell an
+        // append from a silent no-op and every downstream statement — the operator
+        // alert, the delivery row, this function's own comments — asserted that
+        // evidence existed. Now the boolean is carried, said out loud on stderr,
+        // and attached to the alert as a bounded, secret-free fact.
+        let decisionRowPersisted = true;
+        if (decision.audit) {
+            // AWAITED: the row that says what was decided must exist before the
+            // decision is handed back, and its success or failure must be READ. The
+            // write is a bounded local append wrapped in its own try/catch.
+            decisionRowPersisted = await auditLog({
+                type: decision.outcome === 'unavailable' ? 'scan_unavailable' : 'threat',
+                hook: 'before_agent_run',
+                eventId,
+                sessionId,
+                model,
+                // The REDACTED reason. This row is appended to a file that syncs.
+                reason: safeReason,
+                posture,
+                outcome: decision.outcome,
+                // #235: the origin, on every conversation decision row. Without it an
+                // operator auditing an `enforce` host cannot tell a turn that was not
+                // blocked because it was clean from one that was not blocked because
+                // the owner sent it — and "why did this not block?" is the question
+                // this row exists to answer. A label ('owner'/'non-owner'/'unknown'),
+                // never a sender id: the row syncs.
+                origin: trust.origin,
+                // The verdict summary, never the prompt. The input that trips an
+                // injection detector is hostile text by assumption; copying it into an
+                // audit row that syncs to the dashboard/cloud would carry the payload
+                // one hop further. A length + digest keeps rows correlatable without
+                // storing the content.
+                verdict: scan.summary,
+                chars: text.length,
+                contentSha256: createHash('sha256').update(text).digest('hex').slice(0, 16),
+                // Deliberately NOT `notified: false`. Nothing has been attempted yet,
+                // and a false here would read as "we tried and failed". The attempt's
+                // result is its own row, keyed by this eventId.
+                notifyPending: decision.notify && !suppressAlert,
+                // #226: the unavailability run-length, on EVERY occurrence. Alerting is
+                // rate limited; auditing is not, so the row is where the true count
+                // lives — and it says explicitly when an alert was withheld, so a gap in
+                // the alert stream can never be mistaken for a gap in the failures.
+                ...(alertGate
+                    ? {
+                        unavailableCount: alertGate.count,
+                        alertSuppressed: suppressAlert,
+                        alertSuppressedSinceLastAlert: alertGate.suppressedSinceLastAlert,
+                    }
+                    : {}),
+                ts: new Date().toISOString(),
+            });
+            if (!decisionRowPersisted) {
+                console.error(`[shieldcortex] ⚠️ conversation ${decision.outcome} decision could NOT be written to the audit log — ` +
+                    'the decision itself still stands, but there is no local record of it. Check the audit directory ' +
+                    '(SHIELDCORTEX_AUDIT_DIR or ~/.shieldcortex/audit) for permissions or disk space.');
+            }
+        }
+        // The sink. Awaited — the first cut fired this off with `void` and threw
+        // the delivery boolean away, so the code could not tell "a human was told"
+        // from "nothing left this box". It is bounded (CONVERSATION_NOTIFY_MAX_MS,
+        // well under the hook's own 30s timeout) and never throws.
+        let notifyResult = null;
+        if (decision.notify) {
+            const label = decision.outcome === 'unavailable' ? 'unavailable' : decision.block ? 'blocked' : 'observed';
+            // The same redacted string the row got. A gateway's stdout is routinely
+            // shipped to a log aggregator, so "ephemeral" is not a property the
+            // console actually has either.
+            console.warn(`[shieldcortex] ⚠️ ${safeReason ?? 'conversation threat'} — posture=${posture}, outcome=${label}` +
+                (suppressAlert
+                    ? ` (operator alert SUPPRESSED — ${alertGate?.suppressedSinceLastAlert} since the last one; ${alertGate?.count} this session)`
+                    : ''));
+            // Audited above, not alerted. Nothing further is written for a suppressed
+            // occurrence: no attempt was made, and a delivery row saying
+            // `delivered: false` would read as a transport failure that never
+            // happened. The decision itself is unaffected — suppression governs who
+            // is TOLD, never what is DECIDED.
+            if (!suppressAlert) {
+                // The audit-persistence fact rides ALONG with the alert when the local
+                // record failed: bounded, no secrets, and it tells the operator that
+                // this notification is the only trace of the event. Appended to the
+                // reason rather than added as a field so it survives an older installed
+                // dist whose notification builder does not know about it.
+                const auditNote = decisionRowPersisted ? '' : ' [auditPersistence=failed: no local audit row for this event]';
+                const suppressedNote = alertGate && alertGate.suppressedSinceLastAlert > 0
+                    ? ` [${alertGate.suppressedSinceLastAlert} further scan-unavailable event(s) suppressed since the last alert; ${alertGate.count} this session]`
+                    : '';
+                notifyResult = await notifyOperatorOfConversationThreat({
+                    outcome: label,
+                    posture,
+                    summary: scan.summary,
+                    // REDACTED. This one leaves the box entirely — to a webhook, an
+                    // aggregator, a phone — so it is the last place a tokenised endpoint
+                    // URL lifted out of a scanner error may appear.
+                    reason: `${safeReason ?? 'conversation threat'}${suppressedNote}${auditNote}`,
+                    sessionId,
+                    model,
+                });
+                // Truthful reporting: never imply a human was reached unless a
+                // transport said so. "Not configured" is not a failure — it is the #143
+                // default.
+                if (notifyResult.configured && !notifyResult.delivered) {
+                    // #226: redacted HERE too, not only on the row below. The same detail
+                    // string reaches both, and a gateway's stdout is routinely shipped
+                    // somewhere it outlives the process.
+                    console.warn(`[shieldcortex] ⚠️ conversation alert UNDELIVERED — ${redactNotifyDetail(notifyResult.detail)}`);
+                }
+                // Guarded on `audit` because `eventId` has to point at something:
+                // `evaluateConversationRun` never sets notify without audit, and if that
+                // ever changed, a delivery row keyed to a decision row that was never
+                // written would be a dangling reference rather than evidence.
+                if (decision.audit) {
+                    // A SECOND row, not a rewrite of the first. The audit sink is an
+                    // append-only JSONL file, so "what was decided" and "who was told" are
+                    // separate facts recorded when each became true, joined by eventId.
+                    // `via` is the channel NAME ('webhook', 'openclaw-gateway'), never a
+                    // URL; the detail is redacted before it is persisted.
+                    await auditLog({
+                        type: 'notification_delivery',
+                        hook: 'before_agent_run',
+                        eventId,
+                        sessionId,
+                        configured: notifyResult.configured,
+                        delivered: notifyResult.delivered,
+                        via: notifyResult.via,
+                        detail: redactNotifyDetail(notifyResult.detail),
+                        // The eventId this row joins on may point at a row that was never
+                        // written. Say so here rather than leave a dangling reference that
+                        // reads as a missing file rather than a failed write.
+                        ...(decisionRowPersisted ? {} : { auditPersistence: 'failed' }),
+                        ts: new Date().toISOString(),
+                    });
+                }
+            }
+        }
+        // Clean, observed-not-blocked, and scan-unavailable all land here. The
+        // audit row and the operator alert above have already recorded what
+        // happened; the run itself proceeds, and says so.
+        if (!decision.block)
+            return gatePass();
+        return {
+            outcome: 'block',
+            // Redacted for the same reason as the row above: the host SDK documents
+            // `reason` as internal, but "internal" is a policy, not a guarantee.
+            reason: safeReason ?? 'conversation threat',
+            message: `ShieldCortex blocked this turn: ${scan.summary}. The prompt was not sent to the model.`,
+            category: 'prompt_injection',
+        };
+    }
+    catch (e) {
+        // Fail open, loudly. Never let the guard's own failure stop the agent.
+        //
+        // This catch is also why the handler must not be allowed to THROW: the host
+        // registers `before_agent_run` as fail-CLOSED
+        // (`failurePolicyByHook: { before_agent_run: 'fail-closed' }`), so an
+        // exception escaping here does not fail open at all — the gateway catches it
+        // and blocks the run with "before_agent_run hook failed". An explicit pass
+        // is the only way this function actually keeps its fail-open promise.
+        console.error('[shieldcortex] before_agent_run error (failing open):', e instanceof Error ? e.message : String(e));
+        return gatePass();
+    }
+}
 // Skip text blocks that are ShieldCortex/OpenClaw tool-result pass-throughs
 function isToolResultContent(text) {
     // ShieldCortex recall returns "Found N memories:" header
@@ -1117,6 +2751,12 @@ export default {
         if (_registered)
             return;
         _registered = true;
+        // #226: the host runtime's own version, before anything can throw. It is
+        // the primary version evidence for the conversation-gate check — the
+        // gateway stating its own version beats inferring one from whichever
+        // package.json sits above the entry path. Absent on a host that does not
+        // expose it, which stays UNKNOWN rather than becoming a guess.
+        recordHostRuntimeVersion(api);
         // --- Interceptor (lazy init) ---
         let interceptorReady = null;
         let interceptorInitAttempted = false;
@@ -1163,11 +2803,43 @@ export default {
                             : `${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)";
+                        // #226: session_end is registered even with the interceptor off —
+                        // the conversation gate keeps per-session state that needs freeing.
+                        : "llm_input (scan), llm_output (memory), session_end (cache reset)";
+                    // #225: the conversation plane, stated as evidence rather than as a
+                    // tick. Every clause below is something this process actually knows:
+                    // the configured posture, that we asked for the hook, the host build,
+                    // and the operator's grant. Nothing here claims the gateway accepted
+                    // the registration, because the plugin API never says so.
+                    const hostProbe = detectHostOpenClaw();
+                    const plane = describeConversationPlane({
+                        posture: conversationPosture(cfg.interceptor?.conversation),
+                        hookRequested: _beforeAgentRunRequested,
+                        gateSupport: hostSupportsConversationGate(hostProbe),
+                        hostOpenClawVersion: hostProbe.version,
+                        consentGranted: _conversationAccessGranted,
+                    });
+                    const notifyRaw = cfg.interceptor?.actionGuard?.notify;
+                    const notifyState = notifyRaw && notifyRaw.enabled === true
+                        ? 'configured'
+                        : 'not configured — detections reach the audit log and this box only';
                     return {
                         text: `ShieldCortex v${_version}\n` +
-                            `  Hooks: ${hooksLine}\n` +
+                            `  Hooks: ${hooksLine}${_beforeAgentRunRequested ? ', before_agent_run (conversation gate, requested)' : ''}\n` +
                             `  Action guard: ${guardState}\n` +
+                            `  Conversation firewall: ${plane.summary}\n` +
+                            // #226: state the PROVENANCE, not just the value. This flag is a
+                            // SNAPSHOT taken once, when the plugin loaded — the host reads
+                            // the grant at hook-registration time and this process never
+                            // re-reads it. So an operator who has just edited openclaw.json
+                            // and re-run the command sees the old answer, correctly, and
+                            // would otherwise conclude the grant does not work. Nothing here
+                            // is live: changing it requires a gateway restart before either
+                            // the gateway or this line reflects it.
+                            `  Conversation access grant: ${_conversationAccessGranted ? 'granted' : 'NOT granted'} (plugins.entries.${PLUGIN_ID}.hooks.allowConversationAccess)\n` +
+                            '    — read from openclaw.json when this plugin LOADED; it is a snapshot, not a live read.\n' +
+                            '      Editing that key takes effect only after a gateway restart, for the gateway and for this line.\n' +
+                            `  Operator notify: ${notifyState}\n` +
                             `  Auto memory: ${autoMemory} | Dedupe: ${dedupe}\n` +
                             `  Cloud sync: ${cloud}`,
                     };
@@ -1269,41 +2941,148 @@ export default {
                     return handleTypedBeforeToolCall(event, interceptor, api.logger, ctx?.sessionId);
                 }, { priority: 80, timeoutMs: 30_000 });
                 _beforeToolCallRegistered = true;
-                // Try to register session_end for cache cleanup (only meaningful while
-                // an interceptor can exist)
-                try {
-                    api.on('session_end', (ev) => {
-                        interceptorReady?.resetSession();
-                        // #233: a taint must not outlive the conversation that earned it.
-                        if (ev?.sessionId)
-                            sessionTaint.clear(ev.sessionId);
-                    });
-                }
-                catch {
-                    // session_end may not be a supported hook — TTL safety net handles this
-                }
+                // NOTE: session_end is NOT registered here — it moved out of this guard
+                // in #226 and is registered unconditionally below.
             }
             else {
                 api.logger?.info?.('[shieldcortex] interceptor.enabled:false in plugin config — before_tool_call hook not registered');
             }
-            // These two are CONVERSATION hooks: OpenClaw drops them at registration
-            // for a non-bundled plugin unless the host grants
-            // plugins.entries.<id>.hooks.allowConversationAccess = true. We still
-            // attempt registration (the host decides, and the grant can be added
-            // without a code change), but we must not CLAIM them afterwards — see the
-            // honesty note on the log line below (#225).
+            // session_end — registered UNCONDITIONALLY (#226).
+            //
+            // It used to live inside the `interceptorDisabledInHostConfig` guard above,
+            // on the reasoning that it exists for the interceptor's session cache. That
+            // stopped being true when `before_agent_run` landed: the gate is registered
+            // regardless of `interceptor.enabled` (its posture, not the interceptor
+            // flag, decides what it does), and it accumulates per-session
+            // scan-unavailable suppression state. With the cleanup hook skipped, a host
+            // that disabled the interceptor kept every session's window alive for the
+            // life of the gateway process.
+            //
+            // Registering it does NOT reintroduce #112. That incident was specific to
+            // `before_tool_call`: a registered approval hook changes how OpenClaw
+            // resolves tool-call approvals for unattended Codex agents, so an
+            // unattended turn waited 120s on a decision nobody could give. `session_end`
+            // is a notification — it cannot block, approve, or delay anything — and its
+            // handler here only frees local state.
+            try {
+                api.on('session_end', (event, ctx) => {
+                    interceptorReady?.resetSession();
+                    const endedSession = ctx?.sessionId ?? ctx?.sessionKey ?? event?.sessionId ?? event?.sessionKey ?? null;
+                    // #226: the scan-unavailable alert window is session state too, and it
+                    // is keyed per session — so clear THIS session's window and nobody
+                    // else's. Clearing them all would re-arm alerting for every live
+                    // session every time any one of them ended.
+                    resetScanUnavailableAlertState(endedSession);
+                    // #233: a taint must not outlive the conversation that earned it. Same
+                    // per-session rule, for the same reason.
+                    if (endedSession)
+                        sessionTaint.clear(endedSession);
+                });
+            }
+            catch {
+                // session_end may not be a supported hook — TTL safety net handles this
+            }
+            // llm_input/llm_output are CONVERSATION hooks: OpenClaw drops them at
+            // registration for a non-bundled plugin unless the host grants
+            // plugins.entries.<id>.hooks.allowConversationAccess = true. Registration is
+            // still attempted (the host decides, and the grant can be added without a
+            // code change), but they must not be CLAIMED afterwards — see the startup
+            // line below (#225/#230).
             api.on("llm_input", handleLlmInput, { timeoutMs: 30_000 });
             api.on("llm_output", handleLlmOutput, { timeoutMs: 30_000 });
-            // #225: this line used to announce `llm_input + llm_output` unconditionally.
-            // On any host without the conversation-access grant the gateway logged, on
-            // the very next two lines, that it had dropped both — so ShieldCortex was
-            // claiming conversation protection it did not have, in the one place an
-            // operator looks to confirm startup. Report only what is actually live, and
-            // name the missing grant when it is the reason.
-            const conversationAccess = readConversationAccess(homedir(), PLUGIN_ID);
+            // #225: the conversation firewall's ENFORCEMENT point. `llm_input` above is
+            // an OpenClaw *observation* hook — it cannot stop anything, which is why a
+            // detected injection reached the model regardless and the only trace was a
+            // console line. `before_agent_run` is the documented hook that can block a
+            // run, so the verdict lands here where it can actually act.
+            //
+            // Registration is attempted unconditionally: the posture
+            // (off/observe/enforce) decides what happens, and it is read per-call so a
+            // config change takes effect without a restart. Registering conditionally
+            // would make "is the guard wired?" depend on config read at boot — the
+            // exact class of silent gap that #214/#222 were.
+            //
+            // The try/catch is for a host whose `api.on` throws on an unknown name. On
+            // the hosts we have inspected it does NOT throw — an unsupported name is
+            // dropped with a diagnostic, and a conversation hook without the operator's
+            // grant is refused the same way — so a successful call proves only that we
+            // ASKED. That is exactly what the flag is named after, and the honest
+            // reporting comes from the version + consent evidence below.
+            try {
+                api.on("before_agent_run", handleBeforeAgentRun, { timeoutMs: 30_000 });
+                _beforeAgentRunRequested = true;
+            }
+            catch (err) {
+                _beforeAgentRunRequested = false;
+                api.logger?.warn?.(`[shieldcortex] before_agent_run could not be registered on this host (${err instanceof Error ? err.message : String(err)}) — the conversation firewall cannot block on this gateway`);
+            }
+            // The gateway's own message seam, WHERE a host provides one (#143's design
+            // intent: "on OpenClaw the transport should use the gateway's own message
+            // capability"). Probed structurally, never required. No build we have
+            // inspected exposes it — `notifyOperator` appears nowhere in the plugin API
+            // of 2026.5.2 or 2026.7.1 — so on today's hosts this stays null and
+            // conversation alerts go to the webhook.
+            const notifyCtx = api;
+            if (typeof notifyCtx.notifyOperator === 'function') {
+                _gatewayNotifyContext = notifyCtx;
+            }
+            else if (typeof notifyCtx.runtime?.notifyOperator === 'function') {
+                _gatewayNotifyContext = notifyCtx.runtime;
+            }
+            // The operator's conversation-access grant. Read, never written: OpenClaw
+            // refuses every conversation hook for a non-bundled plugin without it, so a
+            // box missing it runs with NO conversation plane at all — and on four of
+            // five fleet hosts surveyed in #222 that was the normal outcome of a
+            // documented install. Report it at boot rather than let the operator infer
+            // protection from a registration line that only states intent.
+            // The host's own in-memory config is the better source (it is what the
+            // loader consulted), so it is preferred; the file the host reads is the
+            // fallback for a runtime that does not expose it. `readConversationAccess`
+            // is #225's shared reader — it also tells us whether the config could be
+            // read at all, which is what keeps "not granted" apart from "cannot tell"
+            // on the startup line below.
+            const diskAccess = readConversationAccess(homedir(), PLUGIN_ID);
+            let rootConfigSeen = false;
+            try {
+                const runtimeConfigApi = api.runtime?.config;
+                const rootConfig = typeof runtimeConfigApi?.current === 'function'
+                    ? runtimeConfigApi.current()
+                    : typeof runtimeConfigApi?.loadConfig === 'function'
+                        ? runtimeConfigApi.loadConfig()
+                        : api.config;
+                rootConfigSeen = Boolean(rootConfig) && typeof rootConfig === 'object';
+                _conversationAccessGranted = rootConfigSeen
+                    ? readConversationAccessGrant(rootConfig)
+                    : diskAccess.granted;
+            }
+            catch {
+                _conversationAccessGranted = diskAccess.granted;
+            }
+            if (!_conversationAccessGranted) {
+                api.logger?.warn?.(`[shieldcortex] conversation firewall INACTIVE: plugins.entries.${PLUGIN_ID}.hooks.allowConversationAccess is not true in openclaw.json — ` +
+                    'the gateway will refuse llm_input, llm_output and before_agent_run for this plugin. Nothing on the conversation path is scanned or blocked. ' +
+                    'This is an operator consent grant and ShieldCortex will never set it for you.');
+            }
+            // #225/#230: this line used to announce `llm_input + llm_output`
+            // unconditionally. On any host without the conversation-access grant the
+            // gateway logged, on the very next two lines, that it had dropped both — so
+            // ShieldCortex was claiming conversation protection it did not have, in the
+            // one place an operator looks to confirm startup. Report only what is
+            // actually live, and name the missing grant when it is the reason.
+            //
+            // `before_agent_run` (#226) is on the same list from 2026.5.9-beta.1, so it
+            // is claimed only when the grant is present AND registration was attempted
+            // this session.
             api.logger.info(`[shieldcortex] v${_version} registered (${describeRegisteredHooks({
-                access: conversationAccess,
+                access: {
+                    granted: _conversationAccessGranted,
+                    // We could read SOMETHING (the host's config or the file) ⇒ the
+                    // ungranted state is a fact, not a failed measurement.
+                    readable: rootConfigSeen || diskAccess.readable,
+                    entryPresent: diskAccess.entryPresent,
+                },
                 beforeToolCallRegistered: _beforeToolCallRegistered,
+                beforeAgentRunRequested: _beforeAgentRunRequested,
             })})`);
         }
         catch (err) {