Changelog

Pricing model change: public tiers are now Free + Enterprise. Every local feature is free — the self-serve Pro and Team tiers are retired, the auto 14-day trial is gone, and cloud signup is open to everyone. Plus: the Action Guard reaches Claude Code.

• +Everything local is free — custom injection patterns, Iron Dome policies, firewall rules, audit export, the dependency scanner, Cortex, Dream Mode, and unlimited X-Ray (the 5-scans/day limit is gone) no longer require a licence. Cloud/org features (fleet sync, team management, SSO) are Enterprise via sales@drakonsystems.com; grandfathered Pro/Team keys keep working.
• +Cloud signup open to all — the dashboard's email → magic-link signup connects anyone to the cloud free tier (500 scans/month, 7-day audit retention).
• +Claude Code PreToolUse guard — every Claude Code tool call runs through the shared Iron Dome action guard: catastrophic ops deny outright, dangerous ops route through Claude Code's native permission dialog, and unattended dangerous calls fail closed.

Hotfix — CLI scans on headless servers were silently dropping cloud sync. Companion bug to v4.24.1. Once the gate was open (Free tier unblocked for audit-ingest), CLI scans on macOS started syncing reliably — the launchd-managed dashboard daemon kept the Node process alive long enough for the fire-and-forget POST to complete. On headless Linux servers (cron jobs, ad-hoc ssh scans, container entry points), shieldcortex scan … ran the pipeline, printed results, and called process.exit() within ~1 second — aborting the in-flight fetch.

• + Track in-flight cloud-sync promises in a module-level Set inside src/cloud/sync.ts. The fire-and-forget signature is preserved for the 50+ existing callers.
• + New flushPendingCloudSync(maxWaitMs = 8000) awaits all tracked promises with a timeout. Wired into the scan and scan-skill CLI subcommands immediately before process.exit(). Headless servers now drain cloud sync reliably; long-lived processes don't need to call it.

Hotfix — Free-tier audit sync to Cloud was incorrectly gated behind Team tier. The defence pipeline's audit-metadata sync (the feed for the Cloud dashboard's scan counts, threat timeline, and device list) was gated on isFeatureEnabled('cloud_sync') — but cloud_sync is a Team-tier feature. Every Free install with a valid cloud API key was silently dropping audit data. The Cloud dashboard appeared stuck on the No scan data yet empty state for every Free-tier user — contradicting the published Free-tier offer (500 scans/mo + 7-day retention).

• ~ Split cloud_sync into two narrower features: cloud_audit_sync (Free — audit metadata only, no content) and cloud_sync (Team — full bidirectional sync incl. memories, knowledge graph, and quarantine content).
• ~ Re-gate the audit-ingest call on cloud_audit_sync. Free-tier installs with a configured cloud API key now actually fire POST /v1/audit/ingest on each scan, as the dashboard has always expected. Quarantine content sync stays on cloud_sync (Team) — correctly.

Gentle Pro-tier upsell — doctor footer + dashboard banner. Free users now get a non-pushy “you can upgrade — 1-2-3” nudge in two places: the shieldcortex doctor output (where engaged users already look) and the local dashboard's shield overview. The doctor footer renders at most once per week; the dashboard banner is dismissable for 7 days. Anyone already on Pro / Team / Enterprise — or in an active trial — sees nothing.

• + Three trigger conditions evaluated in priority order: trial_ended (Pro trial expired within the last 30 days), usage (monthly defence_audit count ≥ 80% of the Free 500/mo cap), and engagement (oldest memory ≥ 14 days AND total memories ≥ 100).
• + Throttle + mute — 7-day cooldown via ~/.shieldcortex/upsell-state.json; mute via npx shieldcortex config --upsell-mute.
• + Dashboard banner mirrors the existing CloudUpsellCard state-machine pattern. Dismissable via X or Maybe later for 7 days. No telemetry, no remote calls — local-only.

Prompt-aware recall — FTS rank is now primary, salience the tiebreaker. Pre–v4.23.0 the UserPromptSubmit recall hook filtered candidates by FTS5 keyword match (ORDER BY fts.rank) but then did a final sort by raw salience — discarding the relevance signal entirely. High-salience-but-off-topic memories bubbled to the top of the per-prompt 🧠 Recalled from memory: preamble. This release picks the simplest of three candidate approaches: FTS-primary ordering with salience as the tiebreaker — no new dependencies, smallest blast radius.

• ~ prompt-recall-hook.mjs ranking — replaced raw-salience final sort with an FTS-rank-primary / salience-tiebreaker comparator. FTS5 BM25 ranks are negative numbers; lower (more negative) = more relevant. The category-boost fallback is preserved.
• i session-start-hook.mjs ranking stays salience-DESC — no query at session start, so FTS rank isn't applicable; the preamble's job is “what's important right now”, not “what matches your current question”.

Quiet the defence canary — drop the stderr noise that v4.22.0 introduced on cold doctor runs. Field signal showed v4.22.0's canary fires correctly (15–17ms, pattern matched) but leaked a [Events] Failed to persist event: Error: Database not initialized stack trace to stderr ahead of the check output. The doctor's other DB-touching checks lazy-init via getDatabase() and work fine, but the events DB needs explicit init that hadn't happened yet when the canary fired. Canary still worked; the output was polluted.

• ~ checkDefenceCanary() calls detectInstructions() directly instead of routing through the full runDefencePipeline(). Same signal — the firewall layer catches the marker or it doesn't — without the DB dependency, the audit-log write, or the event persist. As a bonus the canary now runs in ~1ms instead of 15–17ms, and stops accumulating cli:doctor:canary rows in defence_audit.

Defence canary + recall quick wins. Field-driven release closing two field critiques: “the defence layer is unprovable from inside the session” and “recall surfaces too much half-formed shrapnel with mid-word cuts.”

• + Defence canary doctor check — shieldcortex doctor now runs a synthetic-injection probe (__SHIELDCORTEX_CANARY_PROBE_v1__) through the defence pipeline and asserts the firewall blocked it. Output: ✅ Defence canary: caught (10ms, pattern: defence_canary). Moves the defence layer from “unprovable” to “self-attested” — every doctor invocation is a positive heartbeat for the security claim.
• + Word-boundary-aware truncation — new truncatePreservingWords(text, maxChars, lookback=20) backs off to the last whitespace/punctuation boundary within 20 chars of the limit and appends …. Replaces hard slice(0, N) + '...' at SessionStart (200-char limit) and UserPromptSubmit recall (150-char limit).
• ~ Auto-extract salience cap — calculateSalience() now supports { autoExtractMode: true }, capping the return at 0.6 instead of 1.0. Safety-in-depth: the downstream cap was already in place; making the function itself cap is the structural fix.

Doctor catches up to the v4.21.1 packaging contract — the OpenClaw plugin pkg check now reports INFO on the post–v4.21.1 “no discovery vectors” state. v4.21.0's doctor logic was tightly coupled to the v4.18.3-era invariant that the bare shieldcortex always shipped a root openclaw.plugin.json. v4.21.1 deliberately removed it — at which point the doctor's invariant ran backwards: healthy installs got reported as WARN because the manifest the doctor expected to find was no longer there. This release replaces the manifest-required INFO branch with a visibility-first model.

• ~ Visibility-first INFO — the bare is INFO when it has zero OpenClaw discovery vectors (post–v4.21.1 architecture). It is WARN when either vector is present (openclaw.extensions field OR root manifest), with the WARN message naming the specific vector so operators can diagnose.
• ~ WARN fix-message now points at the real fix: cd ~/.openclaw/npm && npm install shieldcortex@latest.

Kill the OpenClaw duplicate plugin id detected warning at its real source — drop the root openclaw.plugin.json shim that v4.20.0 left in the tarball as a one-release defensive measure. v4.20.0 removed openclaw.extensions from the main package, intending to make the bare shieldcortex invisible to OpenClaw's discovery. Fleet evidence showed the warning persisted — OpenClaw's bundledDiscovery: "compat" scans node_modules/*/openclaw.plugin.json independently of package.json#openclaw.extensions. The defensive root manifest was still being picked up. With this release the bare ships neither discovery vector — fully invisible to OpenClaw.

• ~ Root openclaw.plugin.json removed from the published tarball: dropped from package.json's files allow-list, removed from the repo working tree, build script no longer copies the plugin manifest to the package root.
• i openclaw.hooks kept in package.json — still load-bearing for the documented openclaw hooks install flow. The dedicated @drakon-systems/shieldcortex-realtime plugin remains the only discoverable target.

Stop the doctor crying wolf about peer-range version skew on healthy fleet boxes. Since v4.18.3 the bare shieldcortex sitting at ~/.openclaw/npm/node_modules/shieldcortex has been the expected steady state — OpenClaw's managed-peer-deps installer drops it there to satisfy @drakon-systems/shieldcortex-realtime's peerDependencies.shieldcortex. v4.19.1 taught the doctor to report INFO instead of WARN, but only when the bare version exactly equalled the realtime version. In practice OpenClaw never refreshes the bare copy when realtime upgrades — every fleet box where realtime moved forward still got WARN even though the install was healthy.

• ~ Doctor uses semver.satisfies() against realtime's declared peer range instead of strict equality. When the bare satisfies peerDependencies.shieldcortex AND the root manifest exists → INFO.
• ~ Realtime peer range widened — @drakon-systems/shieldcortex-realtime's peerDependencies.shieldcortex changes from ^4.20.0 to >=4.18.3 <5.0.0. v4.18.3 is the architectural floor.
• ~ Out-of-range fix message refined — doctor now suggests openclaw plugins update @drakon-systems/shieldcortex-realtime rather than rm (which doesn't stick — peer-resolution restores the same version from cache).
• + semver is now a declared direct dependency (^7.7.0). Was previously transitively loadable; making it explicit removes the fragility of relying on indirect resolution.

Drop openclaw.extensions from the main package — kill the OpenClaw duplicate plugin id detected warning at its source. OpenClaw's npm discovery is gated on openclaw.extensions. Pre–v4.20.0 both the main shieldcortex package and the dedicated @drakon-systems/shieldcortex-realtime plugin declared one, so OpenClaw scanned both copies (the bare main package gets pulled in as the realtime plugin's peer-dep), registered both under pluginId: shieldcortex-realtime, deduped, and emitted the warning on every openclaw update. Functionally fine (the right dist/index.js always won) but cosmetic noise on every fleet box. The bare shieldcortex is now invisible to discovery; the dedicated realtime plugin remains the only registration target.

• + Kept openclaw.hooks on the main package — still load-bearing for the documented openclaw hooks install flow.
• + Packaging test inverted to pin the new contract; doctor check unchanged (still handles mixed-version fleets where pre-4.20.0 bare copies linger).

Doctor: OpenClaw plugin pkg check goes WARN→INFO for the expected post–v4.18.3 peer-dep state. Since v4.18.3 the bare shieldcortex landing at ~/.openclaw/npm/node_modules/shieldcortex has been the expected steady state of a healthy install. The doctor's WARN here was conservative noise. Now reports INFO when bare version matches the installed realtime plugin AND the root manifest exists; WARN/FAIL retained for actual surprises (version mismatch, missing peer sibling, missing root manifest).

Living Constellation — the knowledge graph as a living map. The dashboard graph view at /memory/graph now has a pinned anchor node, a breathing animation, memory-activity pulses, and particles drifting along the hottest edges as new memories form. The 527-line ConstellationGraph.tsx monolith was refactored into a slim wirer composing seven focused modules. Pulse triggers wire through /ws/events with a polling fallback against /api/memories?mode=recent.

• + Pinnable anchor + click-to-orbit: the most-connected entity is pinned at canvas centre on load; click any node to smoothly transfer the anchor. Drag any node to pin it in place (drag-to-pin). Shift-click to release a user pin. Double-click empty canvas to reset.
• + Three-layer pulse system: always-on breathing modulated by salience; spikes on memory.created; warm glow on memory.accessed. Energy budget bounds directional-particle render to the top-N edges by recent activity.
• + Settings → Graph Motion intensity selector (Subtle / Moderate / Strong) persisted per-browser; prefers-reduced-motion: reduce short-circuits breathing + particles + tweens for accessibility. memory_created / memory_accessed events now carry entity_ids so the client can light up the right node without an extra round-trip.

Modern Node support — no more cryptic native crash on Node 23/24/25/26. engines.node was unbounded (>=18) while better-sqlite3 ^11's prebuilts stopped at older Node ABIs — users on a newer Node without a compiler hit a bare libc++abi … Napi::Error crash-loop with zero guidance. Node-LTS users were unaffected; this closes the gap.

• + Bumped better-sqlite3 ^11 → ^12 (prebuilts for Node 20/22/23/24/25/26); engines.node >=20 (Node 18 EOL). Added a guarded native loader + postinstall smoke-check that emit one actionable message instead of the opaque abort.

Cap the cloud sync retry queue. The 7-day TTL purge (purgeOldEntries) only runs while the brain worker is alive; MCP-only installs have no worker, so a long offline stretch could grow sync_queue on disk without bound. Now hard-capped at 5,000 rows, enforced on every enqueue and on the worker purge path. Eviction priority: already-synced → terminally-failed → oldest-pending. Once-per-hour warning when trimming kicks in. Fire-and-forget contract preserved.

OpenClaw gateway crash fix — bare shieldcortex ships root openclaw.plugin.json so config validation passes. After openclaw update pulled shieldcortex@4.18.2, OpenClaw config validation failed with "plugin manifest not found" because the package carried openclaw.extensions but didn't ship a root manifest. The tarball now ships openclaw.plugin.json at the package root, byte-identical to the canonical plugin manifest, and the declared openclaw.extensions[0] is resolvable from the published files.

shieldcortex doctor detects misplaced bare shieldcortex in the OpenClaw plugin tree. Background: on 2026-05-15 a fleet OpenClaw gateway restart-looped because a stale bare shieldcortex package had landed in ~/.openclaw/npm/node_modules/ — where only the dedicated @drakon-systems/shieldcortex-realtime plugin belongs. Diagnosis required SSHing into the box by hand. Doctor now reports FAIL on the stale state (declared extension entry missing — the crash-loop class), WARN when the bare package is present with its entry intact, and PASS on healthy installs.

Audit-pass patch — memory-safe JSONL imports, path-traversal hardening, replay UX polish. Two things move the needle for users with substantial transcript archives: JSONL imports now stream the file in 64 KB chunks via readSync + StringDecoder (UTF-8 safe across chunk boundaries) and flush parsed rows in 2,000-row transactional batches — peak memory is now bounded regardless of archive size; and POST /api/sessions/import-jsonl validates paths against $HOME + os.tmpdir() with path.normalize blocking .. traversal.

• + Replay UX polish: SessionList surfaces API errors instead of a perpetual "Loading…"; EventDetail renders a skeleton while switching sessions.

Session Replay UI — scrub every prompt, tool call, and response. A scrubbable timeline of every captured session lives at /memory/replay: session list on the left, kind-coloured tick timeline with a draggable playhead in the centre, focused-event detail on the right. Play, pause, scrub, 0.5×–4× speed, full keyboard control. Renders cleanly in both terminal and glass themes via the existing dual-render primitives.

• + Dashboard route /memory/replay with three-column responsive layout. Sessions sortable by recency or event count. Selected session lives in ?session=… so refresh + share-by-URL work.
• + Transport + keyboard: space toggle, ←/→ step, shift+arrows jump to ends, [/] cycle speed. Shortcuts skip when typing in inputs.
• + Glob-aware import endpoint: POST /api/sessions/import-jsonl accepts file paths, glob patterns, or empty body (defaults to ~/.claude/projects/**/*.jsonl). The dashboard's Import JSONL button uses the zero-arg form for one-click backfill.

Session Capture Backend — turn-by-turn event store, JSONL importer, HTTP API. ShieldCortex now records every prompt, response, tool call, tool result, and hook fire into a dedicated session_events table with enough fidelity to scrub/replay a session end-to-end. Two ingestion paths in lockstep: live capture (hook scripts) and batch import (shieldcortex import-jsonl). A content_hash + UNIQUE index makes re-imports idempotent.

• + session_events schema with CHECK kind IN (prompt|response|tool_call|tool_result|tool_error|hook_fire), project + ts indexes, and an audit-id foreign key so events outlive their audit rows.
• + JSONL importer maps Anthropic SDK content blocks to event kinds. Thinking blocks are skipped (not user-replayable). SHA-256 content_hash + INSERT OR IGNORE drops collisions silently.
• + Live hook capture wired into prompt-recall, session-end, and pre-compact hooks. Opt-out via captureEvents=false.
• + Four new HTTP routes: list, detail, paginated events, import.

Defence pipeline + chunker hardening on the auto-capture write path. Three coupled defects closed: session-end / pre-compact / stop hooks routed memories through the firewall pipeline (defence_audit rows now created on every capture); 9 built-in firewall rules seeded on first run; and the chunker rejects six classes of malformed candidates (imperative tool-call segments, email-body fragments, bare imperatives, etc.) before they reach the dedupe stage. Auto-extract salience capped at 0.6.

Hybrid retrieval with Reciprocal Rank Fusion + LongMemEval benchmark harness. ShieldCortex's recall pipeline now fuses FTS5 keyword, vector cosine, and graph-walk retrievers via Cormack et al. (2009) RRF (k=60). The harness reproduces locally via npm run bench against a 5-question toy fixture today; numbers against the full LongMemEval-S corpus are on the roadmap and not yet published. Legacy weighted-sum scoring stays available as a one-release safety belt (SHIELDCORTEX_RANKER=legacy).

• + Reproducible benchmark: npm run bench produces benchmark/longmemeval/SCORECARD.md with R@5, R@10, MRR, and per-question diff between RRF and legacy engines. CI uploads the scorecard as a release artifact on every tagged push.
• + Multiplicative post-fusion boosts (recency, category, link, tag, activation, contradiction penalty) modulate the rank-fused score without drowning the underlying retrieval signal — what additive weighted-sum couldn't avoid.

Doctor disk check excluded local-AI model cache from the 100 MB safety limit. The 100 MB limit predates the local Review Copilot AI Explainer feature. Once a user opts into local AI, ShieldCortex caches ~750 MB of Qwen2.5-0.5B-Instruct ONNX weights under ~/.shieldcortex/models/. Doctor walked the entire tree, so users with the model cached saw a permanent Disk: at limit! plus a fix command (Run consolidation or delete old memories) that would never recover the bytes — memories prune only operates on rows in memories.db, never on model files.

• ~ models/ excluded from the 100 MB limit. Disk check now splits the directory into a data bucket (DB, state, audit, logs, telemetry, quarantine — everything except models/) and a models bucket. The 100 MB limit applies only to data. The models total is still reported as a parenthetical (e.g. 2.0 MB / 100 MB limit + 750.0 MB models).
• ~ Fix message updated to point at the actual recovery commands (shieldcortex memories prune --execute / memories dedupe --execute) instead of the vague Run consolidation.
• + 6 new tests in doctor-disk-models-exclusion.test.ts covering small data + small models, the bug case (small data + 200 MB models), 99 MB data fail with DB-trimming fix, 85 MB warn, no models/ subtree, and missing scDir.

Two unrelated regressions surfaced after v4.14.2: shieldcortex update couldn't reconcile the OpenClaw plugin on 2026.5.5+, and doctor still hardcoded the pre-v4.14.0 sampling cadence in one cosmetic message.

• ~ shieldcortex update passes --force to openclaw plugins install. OpenClaw 2026.5.5 added a guard that refuses install when the plugin is already present, telling the caller to use update or --force. Reconcile is by definition an overwrite — the user wants the latest plugin, not the existing one. --force also handles fresh installs (no-op when nothing to replace). Reconcile detection extended to include the ~/.openclaw/npm/node_modules/... path so the step actually runs on 2026.5.x installs.
• ~ Doctor's stop-hook fallback default lowered 10 → 5 to match the canonical default in scripts/lib/auto-memory-config.mjs. Users without an autoMemory.stopHookSamplingTurns override now see the correct value in the Auto-memory: Stop hook row.

Fix — shieldcortex install ignored timeout drift on existing hook entries. Doctor correctly flagged a too-low UserPromptSubmit=2s (canonical 5s) timeout (the v4.14.0 #43 check working as intended) and pointed users at Re-run shieldcortex install to restore canonical timeouts. But running install logged = Hook: UserPromptSubmit (already configured) and exited without updating the timeout — re-running doctor showed the same warning. setupHooks() only added missing hooks; existing shieldcortex entries were treated as immutable.

• ~ setupHooks reconciles timeouts on existing entries. After the npx-migration pass, reconcileHookTimeouts() walks every hook event in ~/.claude/settings.json and, for any entry whose command references shieldcortex AND whose timeout is below the canonical value, bumps it to canonical. Higher-than-canonical user overrides are preserved. Non-shieldcortex entries are never touched. Doctor warn → install → no-warn now actually works. Idempotent on re-run.
• + 4 tests in hook-timeout-reconcile.test.ts pin the contract: 2 → 5 bump, idempotency, non-shieldcortex isolation, above-canonical preservation.

Fix — OpenClaw plugin install fails on OpenClaw 2026.5.5+. Field-filed within minutes of v4.14.0 going live: every fleet host running shieldcortex update saw the npm package install successfully but the OpenClaw plugin reinstall step bail with HOOK.md missing in /tmp/openclaw-hook-…/extract/package/llm_input. OpenClaw 2026.5.5 introduced a new install-time hook-pack validator that, for every entry declared in openclaw.hooks, requires a directory of that name at the package root containing HOOK.md plus a handler.ts/handler.js or index.ts/index.js.

• + Per-hook stub directories for llm_input, llm_output, before_tool_call, session_end. Each contains HOOK.md with YAML frontmatter and a minimal handler.js stub. validateHookDir only checks file existence at install time; runtime hook handlers are still registered via register(api) in dist/index.js, so behaviour is unchanged.
• ~ Plugin files: array extended to ship the four new directories. Plugin peerDependency bumped to shieldcortex: ^4.14.1.

Auto-memory hardening — coordinated fix for issues #42, #43, #44, #45. Field-filed by Jarvis after observing 7 days of effectively empty memory on a stock install: 5 STM rows, 0 LTM, 0 episodic. Investigation surfaced four faults in the auto-memory pipeline, all real, all stacking — silent-amnesia from a project-key mismatch (#42), recall drops from a too-tight hook timeout (#43), 90% sampling loss from a too-sparse modulo gate (#44), and STM→LTM promotion never running because the brain worker never autostarted under the default MCP-only install shape (#45). Each issue's fix on its own would still have left the others producing the same symptom.

• ~ #42 — silent amnesia from project-key mismatch. All hook writers (stop, session-end, pre-compact) now derive project keys via the shared deriveProjectKey() helper instead of local extractProjectFromPath() copies. New TS port mirrors the .mjs helper so the MCP-server side matches the hook side. Both SHIELDCORTEX_PROJECT_KEY and the legacy CLAUDE_MEMORY_PROJECT are honoured.
• + #42 data recovery — shieldcortex memories repair-project-keys. New CLI subcommand: dry-run by default, --map basename=canonical, --scan-paths <dirs>, --include-stm, auto-backup before write, JSON log of every rewrite, idempotent on re-run.
• ~ #43 — UserPromptSubmit hook timeout 2 s → 5 s. Cold-spawn floor on the recall hook is ~1.5 s; the previous 2 s ceiling SIGKILLed the hook silently under IO pressure. 5 s leaves ~3 s headroom on a busy host.
• ~ #44 — stop-hook 1-in-10 sampling left LTM under-fed. Default stopHookSamplingTurns lowered 10 → 5. New stopHookSalienceBypass (default true) skips the modulo gate when the recent transcript window contains a fenced code block or hits ≥2 keyword categories. High-signal turns get captured at any cadence; low-signal turns still throttle.
• ~ #45 — STM→LTM promotion never ran on hooks-only installs. Brain worker now autostarts in MCP-server mode under a new lightweight 'mcp' profile (15 min cadence, no medium tick, no cloud sync). Pre-4.14, the worker was only instantiated by --mode dashboard / --mode api / --mode worker — typical hooks-only installs never reached it, and consolidate() never fired. Each light tick persists pid + profile + lastLightTick state to ~/.shieldcortex/state/worker.json. SHIELDCORTEX_DISABLE_WORKER=1 escape hatch.
• + Four new shieldcortex doctor checks: auto-memory sampling, brain-worker freshness, project-key consistency, hook timeouts.
• + 18 new tests + 936 existing pass across hooks-project-key-alignment, brain-worker-mcp-profile, and repair-project-keys.

Fix — doctor stale-lock check produced false positives for long-running daemons. Field-filed against a local install. shieldcortex doctor reported ⚠️ Lock: stale lock file found: memories.db.lock and instructed deletion, despite the recorded PID (shieldcortex dashboard, started 36+ hours earlier under launchd) being alive and actively holding the lock. Following the suggested fix would have broken the dashboard's coordination with the database. Symptom traced to checkLockFile flagging any lock with mtime > 1h as stale — a heuristic that's wrong for daemons launched at boot.

• ~ PID liveness, not mtime age, decides staleness. checkLockFile now parses the lock file's JSON payload, reads the recorded PID, and runs process.kill(pid, 0). ESRCH ⇒ stale, EPERM ⇒ active, success ⇒ active. Matches the semantics already in acquireStartupLock. The 1-hour mtime fallback is replaced by a 24-hour fallback used only when the lock file is unparseable or missing a PID field.
• + 5 new tests in doctor-lock-check.test.ts covering live-PID-with-old-mtime (the bug), an ESRCH PID, unparseable-and-old, unparseable-and-recent, and the empty-directory pass case.

Fix #41 — auto-memory hooks: triple-gating produced silent-amnesia. Field-filed by Jarvis within 24 hours of v4.13.0 going live. v4.13.0 shipped opt-in Stop and SessionEnd hooks gated in three independent places — install flag, runtime gate, and sampling counter. The install flag and runtime gate had no link, so passing --with-stop-hook wired the hook but left the runtime gate at default-false. The hook fired on every turn and immediately process.exit(0)'d with no log line. Looked indistinguishable from "the model forgot."

• ~ Single source of truth: install flag IS the runtime gate. setupHooks with stopHook / sessionEnd options now writes autoMemory.enableStop: true / enableSessionEnd: true to ~/.shieldcortex/config.json alongside the settings.json wiring. Re-running setup without the flag disables both layers symmetrically.
• ~ Loud bail, once per session. Stop hook now prints [shieldcortex stop-hook] disabled — set autoMemory.enableStop=true … to stderr the first time it bails in a session and plants a sentinel under ~/.shieldcortex/logs/stop-hook-disabled-sessions/ so subsequent fires stay quiet.
• + Doctor surfaces resolved gate state. New checkAutoMemoryHooks reports Auto-memory: Stop hook and Auto-memory: SessionEnd hook. Wired+gate-on → pass, wired+gate-off → warn with the silent-amnesia hint, gate-on+not-wired → warn (inverse mismatch), neither → info opt-in (not installed).
• ~ OpenClaw plugin sub-package republished as @drakon-systems/shieldcortex-realtime@4.13.1, fixing a long-standing publish-shape bug that OpenClaw 2026.5.4's stricter validator finally caught (files: array missed dist/; openclaw.hooks key was missing).

Auto-memory pipeline capture-rate fix + per-hook telemetry. Field diagnosis found memories.db empty after weeks despite hooks installed. Root causes: PreCompact rarely fires; when it does, only the last 50 transcript lines were scanned; a slash-command filter silently dropped /skill turns. Fixed end-to-end, plus a sampled Stop hook and the diagnostics to make "fires but extracts nothing" visible.

• ~ Transcript reader rewrite — three duplicated slice(-50) readers replaced with a single shared helper that tail-reads up to 1 MiB (configurable) and applies a smart slash-command filter: drop only single-line slash invocations under 200 chars, keep multi-line and long slash messages with prose. On an 85 MB local transcript: 38 messages from the last 1 MiB vs ~5 under the old slice.
• ~ Stop hook is now a sampling extractor — old behaviour blocked Claude with exit 2 to nudge a remember call (cost an extra turn each time). New behaviour counts assistant turns from the transcript tail and runs full extraction every Nth turn (default 10). Always exits 0. Opt-in via --with-stop-hook.
• + SessionEnd hook (opt-in) — --with-session-end install flag wires SessionEnd as a final extraction backstop for sessions that never compact. Gated by config AND a process.env-based OpenClaw-context guard so it can't regress the v4.10 OpenClaw-crash class.
• + Per-hook telemetry — new hook_invocations table records every firing (hook name, time, duration, memories extracted, transcript bytes scanned). shieldcortex status now shows a Hook activity (last 7 days) section so "fires but extracts nothing" stops being indistinguishable from "never fires".
• + New autoMemory.* config namespace in ~/.shieldcortex/config.json — maxTranscriptBytes, stopHookSamplingTurns, enableSessionEnd, enableStop, and more. Defaults preserve current behaviour for every existing user.
• + 14 new transcript-reader tests + 1 deep-clean test fix — full suite 904/904 passing across 78 suites. Includes a related fix for the deep-clean test that was inconsistent with the c16ccc1 native-install detection (Mac homebrew false-positive fix).

The suspected fleet-wide context-killer + install churn. Two surgical fixes in the install/uninstall paths. One is the suspected root cause of weeks of cross-fleet Claude Code context loss; the other stops shieldcortex update from rewriting OpenClaw's config every time it runs.

• ~ Context-killer fix — pre-v4.12.11 uninstall left mcpServers.memory in ~/.claude.json pointing at a now-missing binary. Every Claude Code session loaded the orphan, tried to spawn the binary, failed, and the spawn-fail cascaded into context loss across the fleet. New removeMcpEntry() with ownership check (only deletes SC-owned entries — won't clobber the official upstream MCP server which uses the same generic key), wired into both uninstallSetup() and uninstallAll() paths.
• ~ openclaw.json install idempotency — trustLocalPlugin() used to bump a fresh installedAt timestamp on every call regardless of state, churning the gateway's config-watcher on every npm install -g. New pluginInstallNeedsWrite() pure helper makes the install + uninstall a no-op when state already matches. Loop test on a real Mac confirms 6 back-to-back installs produce zero writes.
• i Two related claims investigated and disproven — SC ships no SKILL.md path it doesn't actually ship (the references found are SC's own skill-scanner module that scans third-party skills); memory extraction code is correct end-to-end since v4.12.5 (the "still returning 0" report was anecdotal — FLEET-STATUS doesn't even contain a memory-count metric).
• + 17 new tests across uninstall-mcp-cleanup.test.ts and openclaw-install-idempotency.test.ts. Credit to Edith (peer agent) for finding the mcpServers orphan.

Background service crash-loops with exit 209/STDOUT after the logs dir is removed. Caught on Jarvis and Tars after this session's residue cleanup wiped ~/.shieldcortex/. The systemd unit hardcoded StandardOutput=append: to a path inside that dir. systemd opens that file before any ExecStart*, so once the directory disappeared, the service entered a permanent restart loop (300+ attempts on Jarvis). ExecStartPre=mkdir would not have helped — file open precedes ExecStartPre too.

• ~ Logs now go to journald — StandardOutput=journal with SyslogIdentifier=shieldcortex-${mode}. Inspect with journalctl --user -u shieldcortex-dashboard.service. No filesystem dependency — rm -rf of any user dir cannot break it.
• + Stale-unit detector — shieldcortex service status now recognises pre-v4.12.10 broken units and prints the missing log dir as the reason. Migrate with shieldcortex service repair --headless.
• i Why journald and not LogsDirectory= — that directive needs systemd ≥ 250 for user units, and Ubuntu 22.04 ships systemd 249. Journald works on every supported version and survives any cleanup of user dirs.

v4.12.8 didn't actually silence the audit — comments count. v4.12.8 extracted cloud sync to its own module so no plugin file paired the two APIs. But the new module included a doc comment that named both APIs alongside the actual call. OpenClaw's audit fired immediately on the next install. The audit is purely textual — it does not strip comments before scanning.

• ~ Doc comment trimmed in cloud-sync.ts to one line that does not name the file-read API.
• ~ Test now mirrors OpenClaw's real scan — raw text, no comment stripping. v4.12.8's test stripped comments because that's what a thoughtful linter would do; OpenClaw doesn't, so the regression shipped. Don't infer a spec — mirror the implementation.
• + Future regressions caught locally — if anyone re-introduces an explanatory comment that names both APIs in the same plugin file, the test now fails before publish, not after the fleet hits a fresh install.

OpenClaw 2026.4.24 plugin-audit warning silenced. The new install-time security scanner flagged shieldcortex-realtime with [potential-exfiltration] because readFileSync and fetch() appeared in the same source file. False positive — the two operations never share data — but the heuristic is textual.

• ~ Cloud sync extracted to its own module (plugins/openclaw/cloud-sync.ts) with zero fs imports. Mirrors the pattern already used for intercept-ingest.ts. Behaviour-equivalent: same threat object, same endpoint, same 5s timeout.
• + Static-analysis test guard — asserts no plugin source file pairs readFileSync/readFile with fetch(. Stops the warning ever silently coming back if the two operations are re-merged.
• i Two related findings are not SC bugs — plugins.installs_unpinned_npm_specs (OpenClaw installer records @latest unless given an exact pin) and plugins.installs_version_drift (clears with openclaw plugins update --all). Both are upstream.

Mac homebrew false-positive fix — root cause of the v4.12.3–v4.12.6 Mac regression. Doctor kept flagging legitimate plugin config entries as orphans on every Mac install. Linux fleet hosts never hit it.

• ~ Wrong installPath recorded — the native-package install code (Mac homebrew) wrote installPath = .../plugins/openclaw (the package root) instead of .../plugins/openclaw/dist (where the manifest actually lives). Doctor checked the wrong path, didn't find the manifest, and false-flagged the install.
• ~ Defensive fallback for old installs — detectInstallState() now also checks installPath/dist/openclaw.plugin.json so existing Mac hosts with the bad path written stop false-flagging on next doctor run, before they even need to re-install.
• + 4 new tests — repro of Friday's scenario, plus source-level guards that the writer always uses the correct convention.

Install now restarts the OpenClaw gateway — symmetric with uninstall --deep. Without this, an npm-package upgrade left the running gateway with the old plugin in memory until something else triggered a restart. Caught Edith mid-fleet-rollout: package on 4.12.5, plugin still loading 4.12.2, status reporting 0 memories / never.

• ~ Auto-restart by default — shieldcortex openclaw install now calls the same gateway-restart helper that uninstall --deep uses (systemctl on Linux, launchctl on macOS). Skipped when both --no-hooks and --no-plugins are passed.
• + New --no-gateway-restart flag for scripted multi-step installs that want to defer the restart.
• ~ Platform-specific manual fallback — if the auto-restart fails, the installer prints the exact systemctl / launchctl command for the host.
• + 8 new tests lock in the wiring (option declared, CLI flag parsed and passed through, default-true gating, "only restart when something installed" guard, no duplicated implementation).

Auto-extract write path fix — v4.12.4 unblocked the read side of auto-extract; v4.12.5 closes the write side. Both pre-compact and session-end hooks built INSERT statements that omitted the uuid column. The schema declares uuid TEXT NOT NULL UNIQUE with no default, so every insert silently errored with NOT NULL constraint failed: memories.uuid and zero memories landed.

• ~ UUID generated on every insert — new shared scripts/lib/save-memory.mjs util generates crypto.randomUUID() and binds it to the INSERT.
• ~ Single write path for both hooks — pre-compact and session-end now delegate to the same util, so they can no longer drift apart and produce "one hook works, the other silently fails" bugs.
• + 5 new tests against a fresh SQLite DB built from the real schema — covers the bug repro, UUID uniqueness over bulk inserts, null project, and tag JSON encoding.

Silent zero-memory fix — every fleet host running ShieldCortex from inside a dotfile-prefixed working directory (e.g. ~/.openclaw/workspace) was producing 0 auto-extracted memories on every pre-compact event. Doctor was green, hooks were "configured", but the actual capture was zero.

• ~ Encoder mismatch — pre-compact's auto-extract path encoded the cwd into a Claude Code project-folder slug by replacing only / with -. Claude Code itself replaces both / and ., so the lookup never matched the folder Claude Code wrote and the transcript was never opened.
• ~ Now matches Claude Code exactly — new scripts/lib/claude-project-dir.mjs util replaces /, \, ., and : with - and prefixes a leading separator. Other hooks (session-end, prompt-recall, session-start, stop) were audited and confirmed safe — they receive transcript_path directly from the hook payload.
• + 6 new tests covering the original repro plus dot-inside-component and Windows path scenarios.

Doctor recognises Mac homebrew installs — v4.12.2 only checked ~/.openclaw/extensions/ for the plugin. On macOS via homebrew the plugin actually lives in the npm-global tree at /opt/homebrew/lib/node_modules/shieldcortex/... (OpenClaw's "native-package" discovery mode). Doctor saw "no plugin" and flagged the legitimate config entries as orphans.

• ~ installPath-aware detection — detectInstallState() now reads .plugins.installs[shieldcortex-realtime].installPath from openclaw.json first (the path the installer actually used), with user-space and home-relative npm-global fallbacks for older installs that pre-date the field.
• + 2 new tests covering the homebrew repro and the missing-installPath fallback path.

Doctor DB-init guidance fix — v4.12.1 doctor's "Database: not found" suggested-fix told you to run shieldcortex quickstart, but quickstart only configures hooks/MCP — it doesn't touch the database. On TARS during fleet rollout the user looped on quickstart → doctor → quickstart. v4.12.2 points at the right command.

• ~ New suggested fix — shieldcortex scan "init" creates the database explicitly. Works on every install shape (Claude+OpenClaw, OpenClaw-only, headless).
• ~ Lazy-init alternative noted — on Claude+OpenClaw hosts the message also mentions starting a Claude Code session, which lazy-inits the DB via the MCP server on first memory call.
• + 3 new tests lock the corrected guidance in: no quickstart reference inside checkDatabase(), explicit scan "init" reference present, MCP lazy-init mention preserved.

Doctor fix — v4.12.0's OpenClaw residue check flagged legitimate install state as "residue". A freshly-installed host showed 6–7 false-positive warnings and pointed users at uninstall --deep to "purge" a healthy install. v4.12.1 teaches doctor to tell the difference.

• ~ Orphan-only detection — new scanForOrphans() applies presence-aware filtering. Plugin config entries are only flagged if the extension dir is gone. Hook config entries are only flagged if no cortex-memory hook dir exists. Current install paths are never orphaned; legacy paths and ClawHub skill-locks always are.
• ~ Tailored "clean" message — doctor now reports "clean (plugin + hook installed, config aligned)" when the install is healthy, instead of a generic "clean" line that left operators unsure whether the check actually ran.
• ~ uninstall --deep unchanged — still purges everything unconditionally, since its job is total removal for cleanup scenarios.
• + 7 new tests covering the Case repro, missing-plugin-dir, missing-hook-dir, legacy-always-flagged, ClawHub-always-flagged, canonical-dirs-never-flagged, and a migration guard.

ShieldCortex ↔ OpenClaw compatibility pass. Closes the "partial uninstall" gap that left orphan config entries after every version bump, and unlocks OpenClaw 2026.4.23's host-package linking for peer-declared plugins.

• + shieldcortex uninstall --deep — scans 15 known residue locations across ~/.openclaw/openclaw.json, .clawhub/lock.json, and stale hook/extension dirs. Surgically removes ShieldCortex references while preserving sibling keys, then best-effort restarts the gateway. --no-gateway-restart opts out.
• + shieldcortex doctor gains OpenClaw residue check — reports dirty-location count and points at uninstall --deep as the fix. Skipped cleanly on non-OpenClaw hosts.
• + Plugin declares openclaw as optional peer dep — unlocks OpenClaw 2026.4.23's host-package linking (#70462). Plugin manifest hints at engines.openclaw >=2026.4.23 recommended.
• + Hash-stability guard — 4 static-analysis tests lock in the invariant that the CLAUDE.md INSTRUCTIONS block contains no runtime-dependent content (no Date.now, randomUUID, env reads). Protects against the same silent session-wipe class of bug v4.11.1 closed for MCP config.
• ~ 19 new tests — 8 deep-clean, 7 plugin-manifest, 4 hook-hash-stability.

Fleet-critical fix — MCP registration no longer uses npx -y. The installer now resolves and pins the installed shieldcortex binary path, falling back to npx -y only when no global install exists. Closes a silent session-wipe loop.

• ~ Why it mattered — npx -y resolves dynamically every invocation. Any shift in what it resolves to (cache misses, fresh publishes, version drift) flipped the MCP config hash, triggering cli session reset reason=mcp and wiping context mid-conversation. Observed on TARS firing ~every 30 minutes before the fix.
• ~ Stale registrations auto-upgrade — re-running shieldcortex setup on v4.11.0-or-earlier installs rewrites the MCP config to the stable binary path.

Memory-injection side is now opt-in. Default behaviour flipped so Recall / CLAUDE.md / session hooks only inject when explicitly enabled — resolves the cases where auto-injection was bloating context windows on resumed sessions.

Upgrade-path fix — shieldcortex update now always reconciles the OpenClaw plugin and skill, even when the main npm package is already on the latest version.

• ~ Short-circuit removed — the early-return when main was current was skipping plugin + skill reconciliation, so v4.9 → v4.10 upgraders stayed stuck on the old plugin. Plugin now always gets rm -rf + fresh install, skill always gets force-reinstall.
• ~ If you're on v4.9.x, run shieldcortex update once and all three components — main, plugin, skill — land on 4.10.1 in one shot.

Environment Firewall (Phase 1) — new third defence layer protecting what the agent sees. Memory firewall covers what the agent stores, Iron Dome covers what it does, Environment Firewall covers what it trusts from the world around it.

• + New CLI shieldcortex env scan <url> — fetches a URL, scores provenance, extracts visible vs hidden content, runs injection patterns against each surface, returns a taint label (trusted / untrusted / suspicious / hostile). Exit codes 0/1/2 so it drops into CI.
• + Hidden-instruction detection — display:none, visibility:hidden, zero font-size, off-screen positioning, same-colour text, ARIA-hidden, HTML comments, inline scripts, Unicode bidi overrides, zero-width characters, meta refreshes. Injection patterns found in hidden content mark the page HOSTILE regardless of domain.
• + Provenance scoring — TLS, redirect chain, domain allowlist, suspicious TLDs, Punycode homograph flags, raw-IP hosts, embedded credentials.
• + Library export — import { scanUrl } from 'shieldcortex/environment'.

Cloud audit log alignment — closed silent data loss between npm and SaaS audit ingest.

• ~ blocked_patterns now persisted — npm package sends the matched pattern list on every audit event; SaaS schema and DB columns store it for review.
• ~ fragmentation_score now persisted — cross-memory assembly score travels through /v1/audit/ingest instead of being silently dropped.

Defence pipeline hardening — wired skill scanner threat patterns into write-time pipeline.

• + Skill threat patterns at write-time — the firewall now blocks the seven skill scanner categories on every memory write, not just on demand: tool_injection, scope_escalation, data_exfiltration, persistence, supply_chain, agent_manipulation, and stealth_instruction.
• + Decoded content re-scan expanded — base64/hex payloads are now re-checked against credential detection and the seven skill threat patterns, not just the legacy injection set.
• + Path traversal protection — /api/skills/scan rejects ../ escapes before touching the filesystem.

Proactive Recall, self-update CLI, OpenClaw plugin hardening, and database resilience improvements.

• + Proactive Recall — relevant memories auto-injected into every conversation before the model responds. FTS5 + category boost in under 100ms. Works with Claude Code and OpenClaw.
• + shieldcortex update — new CLI command to check for and install the latest version.
• + Clickable dashboard — stat cards, hygiene numbers, and quality items navigate to the relevant view on click. Review focus wiring auto-scrolls to the right section.
• + Cloud sync actions — Clear Failed button in the warning banner. Honest messaging for dead-letter failures instead of "healthy with failed history".
• ~ Database resilience — auto-reconnect when the live DB file is replaced during recovery. Stale backup cleanup on startup. Precision fix for threshold comparisons.
• ~ OpenClaw plugin hardened — removed child_process dependency for scanner compatibility. Auto-migrate stale hook registrations. Plugin reinstall handles existing directories automatically.
• ~ Quality API aligned — duplicate counts now match between stat cards and review queue. SKILL.md rewritten for ClawHub scanner transparency.

Constellation Graph, Review Queue redesign, X-Ray accuracy, cloud sync diagnostics, and 13 bug fixes.

• + Constellation Knowledge Graph — cluster-based view with coloured nebula halos, bloom-on-click drill-down, and cross-cluster ghost links.
• + Review Queue redesign — card-based flow with Keep/Suppress/Archive actions, slide animations, and progress bar.
• + X-Ray accuracy — eliminated 98% of false positives with path exclusions, header-only polyglot checks, and code-aware obfuscation detection.
• + Cloud sync diagnostics — clear failed items, manual refresh, save feedback, replication status cards.
• ~ Auth token race conditions, WebSocket reconnect, graph search limits, button defaults, keyboard accessibility, and 8 more fixes.

Finding lifecycle, X-Ray findings dashboard, dashboard redesign with dark theme, and watch mode improvements.

• + Finding Lifecycle — X-Ray findings now have persistent status (new, reviewed, ignored, resolved, quarantined) with review, ignore, resolve, quarantine, and delete actions.
• + Findings Tab — new tab in X-Ray with status filters, stats summary, and action buttons on every finding.
• + Dashboard Redesign — OpenClaw-inspired dark theme with coral/cyan accents, glassmorphic cards, simplified navigation from 18 routes to 5 tabbed sections.
• + Real-time Alerts — watch detections broadcast via WebSocket with toast notifications in the dashboard.

X-Ray — a new product module for inspecting packages, files, and plugins for hidden risk.

• + X-Ray Scanner — shieldcortex xray <target> scans local files, directories, and npm packages for eval/exec, shell execution, AI directives, prompt injection, steganography, obfuscation, unicode tricks, network beacons, persistence hooks, and dependency risk.
• + Trust Score — 0–100 score with SAFE / LOW / MEDIUM / HIGH / CRITICAL risk levels.
• + Deep npm scan — --deep flag pulls registry metadata for full package analysis (Pro).
• + Output formats — --json and --markdown for scripting and reports.