@hyperspell/openclaw-hyperspell 0.19.0 → 0.21.0

package/dist/graph/ops.js

@@ -1,8 +1,31 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { MOOD_WEATHER_SOURCE } from "../lib/filters.js";
 import { getAllUserIds } from "../lib/sender.js";
 import { log } from "../logger.js";
 const ENTITY_TYPES = ["people", "projects", "organizations", "topics"];
+/**
+ * True for memories that came from a Memory Network entity file synced back
+ * to Hyperspell. These must never re-enter a scan as source memories — the
+ * extractor would be fed its own output every cycle (self-scan loop,
+ * proposal/06 §3.3). Two signals, both needed:
+ * - `graph_entity` metadata, propagated from entity-file frontmatter by the
+ *   sync paths (`sync/markdown.ts`) — the contract the extraction prompt states;
+ * - the entity-directory `file_path`, which covers records synced before the
+ *   frontmatter propagation existed (unchanged sections are content-hash
+ *   skipped on re-sync, so their old metadata never gets refreshed).
+ */
+export function isEntityFileMemory(metadata) {
+    if (!metadata)
+        return false;
+    if (metadata.graph_entity === "true" || metadata.graph_entity === true)
+        return true;
+    const filePath = metadata.file_path;
+    if (typeof filePath !== "string")
+        return false;
+    const normalized = filePath.split(path.sep).join("/");
+    return ENTITY_TYPES.some((type) => normalized.includes(`/memory/${type}/`));
+}
 export function slugify(name) {
     return name
         .toLowerCase()
@@ -60,17 +83,27 @@ function summarizeMemoryData(data, source) {
     }
     return parts.join("\n");
 }
-export async function scanMemories(client, stateManager, batchSize, cfg) {
+export async function scanMemories(client, stateManager, batchSize, 
+// Required (not optional) so no caller can silently bypass the multiUser
+// fan-out again — the CLI `network scan` did exactly that (proposal/06 §3.3).
+cfg) {
     const unprocessed = [];
-    const userIds = cfg ? getAllUserIds(cfg) : [undefined];
+    // Single-user installs without a configured userId resolve to no ids;
+    // scan under the API key's default identity in that case.
+    const configuredIds = getAllUserIds(cfg);
+    const userIds = configuredIds.length > 0 ? configuredIds : [undefined];
     outer: for (const userId of userIds) {
         for await (const mem of client.listMemories({ userId })) {
             if (stateManager.isProcessed(mem.resourceId))
                 continue;
-            if (mem.metadata?.graph_entity === "true" || mem.metadata?.graph_entity === true)
+            if (isEntityFileMemory(mem.metadata))
                 continue;
             if (mem.metadata?.status !== "completed")
                 continue;
+            // Mood-weather roll records are observability-only (issue #71): the graph
+            // feeds context, so ingesting them would leak the rolls back into recall.
+            if (mem.metadata?.openclaw_source === MOOD_WEATHER_SOURCE)
+                continue;
             let summary = "";
             try {
                 const full = await client.getMemory(mem.resourceId, mem.source, { userId });

package/dist/hooks/auto-context.js

@@ -1,7 +1,8 @@
 import { appendFileSync } from "node:fs";
 import { buildScopeFilter, getCanReadScopes, resolveUser, } from "../lib/sender.js";
 import { excludeFilterFor, mergeWithExclude } from "../lib/filters.js";
-import { explainSelection, rerank, } from "../lib/ranking.js";
+import { explainSelection, kindTally, rerank, } from "../lib/ranking.js";
+import { recordCoverageEvent, } from "../lib/coverage-log.js";
 import { classifySearchError, logSearchError } from "../lib/search-error.js";
 import { resolveCurrentSessionId } from "../lib/session.js";
 import { recordSender, senderIdFromCtx } from "../lib/speaker-tracker.js";
@@ -54,22 +55,38 @@ function formatHighlightBullets(results, maxResults, threshold) {
         return null;
     return sections.join("\n\n");
 }
+// A second highlight rides along only when it is within this much of the top
+// one's score — a distant second is dilution inside a correct pick (proposal
+// 12). Absolute difference (not a ratio) to match every other score rule in
+// this pipeline; 0.15 is "one storyBoost's worth" on the composite scale.
+// Deliberately a constant, not config: a formatting heuristic two levels
+// below anything a user reasons about — promote to ranking.highlightGap only
+// if live tuning proves deployments actually differ.
+const HIGHLIGHT_GAP = 0.15;
 /**
  * Format already-SELECTED composite-ranked results (threshold + chatter quota
  * applied upstream by selectRanked). Highlights are floored at the lower of
  * (threshold, the result's own base relevance), so we don't hide the very lines
- * that define a boosted-but-quiet memory.
+ * that define a boosted-but-quiet memory. Exported for direct testing.
  */
-function formatSelected(selected, threshold) {
+export function formatSelected(selected, threshold) {
     const sections = [];
     for (const r of selected) {
         const hiFloor = Math.min(threshold, r._base);
-        const chosen = [...r.highlights]
+        const passing = [...r.highlights]
             .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
-            .filter((h) => (h.score ?? 0) >= hiFloor)
-            .slice(0, 2);
-        if (chosen.length === 0)
+            .filter((h) => (h.score ?? 0) >= hiFloor);
+        if (passing.length === 0)
             continue;
+        // Floor first (is this highlight relevant at all?), gap second (is the
+        // runner-up close enough to the winner to be worth its tokens?). The TOP
+        // highlight is always kept — the lowered hiFloor exists to protect
+        // boosted-but-quiet memories, and the gap rule must never re-hide them; a
+        // selected result can never format to fewer sections than today.
+        const [top, second] = passing;
+        const chosen = second && (top.score ?? 0) - (second.score ?? 0) <= HIGHLIGHT_GAP
+            ? [top, second]
+            : [top];
         const title = r.title ?? `[${r.source}]`;
         const bullets = chosen
             .map((h) => `- ${h.text.replace(/\n/g, " ")} [${Math.round((h.score ?? 0) * 100)}%]`)
@@ -168,7 +185,12 @@ export function dropCurrentSession(results, currentSessionId) {
     }
     return kept;
 }
-export function buildAutoContextHandler(client, cfg) {
+/** Highest raw relevance among candidates — `topScore 0.54` vs `threshold 0.6`
+ * is a ranking near-miss; `0.12` means the vault has nothing close (capture). */
+function topScoreOf(results) {
+    return results.length ? Math.max(...results.map((r) => r.score ?? 0)) : null;
+}
+export function buildAutoContextHandler(client, cfg, opts) {
     return async (event, ctx) => {
         const prompt = event.prompt;
         if (!prompt || prompt.length < 5)
@@ -184,7 +206,7 @@ export function buildAutoContextHandler(client, cfg) {
         // Multi-user path
         if (cfg.multiUser) {
             const resolved = resolveUser(ctx, cfg);
-            return multiUserSearch(client, cfg, prompt, resolved, currentSessionId);
+            return multiUserSearch(client, cfg, prompt, resolved, currentSessionId, opts?.stateRoot);
         }
         // Single-user path — preserves main's highlights + threshold behavior
         log.debug(`auto-context: searching for "${prompt.slice(0, 50)}..."`);
@@ -195,20 +217,39 @@ export function buildAutoContextHandler(client, cfg) {
             const limit = ranking.enabled
                 ? cfg.maxResults * ranking.candidateMultiplier
                 : cfg.maxResults;
-            const results = dropCurrentSession(await client.search(prompt, { limit, filter: excludeFilterFor(cfg) }), currentSessionId);
+            // Kept as two steps so the coverage event below can report the pre-drop
+            // fetch count (a session-echo-dominated pool must be visible as such).
+            const rawResults = await client.search(prompt, {
+                limit,
+                filter: excludeFilterFor(cfg),
+            });
+            const results = dropCurrentSession(rawResults, currentSessionId);
             let formatted;
             if (ranking.enabled) {
                 const ranked = rerank(results, ranking);
                 // Threshold + chatter quota applied here, so a high-similarity echo can
                 // inform but never flood (the quota bounds count; the penalty bounds rank).
-                const explained = explainSelection(ranked, cfg.maxResults, cfg.relevanceThreshold, ranking.chatterQuota);
+                const explained = explainSelection(ranked, cfg.maxResults, cfg.relevanceThreshold, ranking.chatterQuota, ranking.dedupThreshold, ranking.elbow);
                 logScoreSamples(prompt, currentSessionId, "single", explained, cfg.relevanceThreshold);
                 const selected = explained.filter((e) => e.selected).map((e) => e.result);
+                // Candidates → selected kind tally, logged UNCONDITIONALLY (unlike the
+                // "injecting" line below): a story/curated match that loses to the
+                // threshold is exactly the case an operator tuning storyTerms needs to
+                // see, and it never reaches the formatted branch (proposal 01 §3.4).
+                log.diag(`auto-context: ranked ${JSON.stringify(kindTally(ranked))} candidates → selected ${JSON.stringify(kindTally(selected))} (chatter cap ${ranking.chatterQuota})`);
+                for (const r of ranked.slice(0, 10)) {
+                    log.debug(`  [${r._kind}] ${r._base.toFixed(2)}→${r._composite.toFixed(2)} ${(r.title ?? r.resourceId).slice(0, 60)}`);
+                }
                 // Cut-reason visibility (proposal 02, absorbs proposal 03): logged
                 // BEFORE the `formatted` check so quota drops stay visible even when
                 // nothing is injected (e.g. chatterQuota 0 with only chatter clearing
                 // the threshold). Stable "auto-context: cut" prefix for log greps.
                 // flatMap (not filter) so TS narrows to the cut member of the union.
+                // Elbow verdict — the live-validation instrument for proposal 13's
+                // rollout: firing rate + cut depth come straight from this line.
+                if (ranking.elbow.enabled && explained.some((e) => e.cut === "elbow")) {
+                    log.diag(`auto-context: elbow stopped at ${selected.length} (ceiling ${cfg.maxResults})`);
+                }
                 const cuts = explained.flatMap((e) => (e.selected ? [] : [e]));
                 if (cuts.length > 0) {
                     const cutTally = cuts.reduce((acc, e) => ((acc[e.cut] = (acc[e.cut] ?? 0) + 1), acc), {});
@@ -216,12 +257,11 @@ export function buildAutoContextHandler(client, cfg) {
                     const quotaNote = topQuotaDrop
                         ? `, top quota-dropped composite ${topQuotaDrop.result._composite.toFixed(2)}`
                         : "";
-                    log.debug(`auto-context: cut ${cuts.length} of ${ranked.length} candidates ${JSON.stringify(cutTally)}${quotaNote}`);
+                    log.diag(`auto-context: cut ${cuts.length} of ${ranked.length} candidates ${JSON.stringify(cutTally)}${quotaNote}`);
                 }
                 formatted = formatSelected(selected, cfg.relevanceThreshold);
                 if (formatted) {
-                    const tally = selected.reduce((acc, r) => ((acc[r._kind] = (acc[r._kind] ?? 0) + 1), acc), {});
-                    log.debug(`auto-context: injecting (ranked) ${JSON.stringify(tally)} from ${results.length} candidates (chatter cap ${ranking.chatterQuota}, composite ${selected.at(-1)?._composite.toFixed(2)}–${selected[0]?._composite.toFixed(2)})`);
+                    log.diag(`auto-context: injecting (ranked) ${JSON.stringify(kindTally(selected))} from ${results.length} candidates (chatter cap ${ranking.chatterQuota}, composite ${selected.at(-1)?._composite.toFixed(2)}–${selected[0]?._composite.toFixed(2)})`);
                 }
             }
             else {
@@ -234,6 +274,23 @@ export function buildAutoContextHandler(client, cfg) {
             // every-turn banner (which reads as framing and trains search-as-ritual).
             if (!formatted) {
                 log.debug("auto-context: no relevant memories found");
+                // Coverage signal (proposal 15): search SUCCEEDED but injected nothing —
+                // durably distinguish "never captured" (empty) from "captured but ranked
+                // out" (below_threshold). Thrown searches never reach here (the catch
+                // below owns them), so availability blips can't pollute the log.
+                if (cfg.coverageLog) {
+                    recordCoverageEvent({
+                        outcome: results.length > 0 ? "below_threshold" : "empty",
+                        prompt,
+                        fetched: rawResults.length,
+                        candidates: results.length,
+                        droppedCurrentSession: rawResults.length - results.length,
+                        topScore: topScoreOf(results),
+                        threshold: cfg.relevanceThreshold,
+                        ranking: ranking.enabled,
+                        sessionId: currentSessionId,
+                    }, opts?.stateRoot);
+                }
                 return;
             }
             return { prependContext: wrapContext(formatted) };
@@ -252,7 +309,7 @@ export function buildAutoContextHandler(client, cfg) {
 // single-user path only: this path never runs rerank/explainSelection, so
 // there is no composite score to attribute. If ranking ever lands here, call
 // logScoreSamples with scope "personal" / "shared" per search.
-async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId) {
+async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId, stateRoot) {
     const multiUser = cfg.multiUser;
     const isKnownSender = !!resolved?.resolved;
     const includeShared = multiUser.includeSharedInSearch;
@@ -290,9 +347,18 @@ async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId)
     let idx = 0;
     let personalResults = [];
     let sharedResults = [];
+    // Per-lane fulfillment + pre-drop counts feed the coverage event below: a
+    // lane that REJECTED must never be recorded as "zero candidates" (#39's
+    // unavailable-is-not-empty distinction, kept intact in the log schema).
+    let personalOk = false;
+    let sharedOk = false;
+    let rawPersonalCount = 0;
+    let rawSharedCount = 0;
     if (personalSearch) {
         const r = settled[idx++];
         if (r.status === "fulfilled") {
+            personalOk = true;
+            rawPersonalCount = r.value.length;
             personalResults = dropCurrentSession(r.value, currentSessionId);
         }
         else {
@@ -302,6 +368,8 @@ async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId)
     if (sharedSearch) {
         const r = settled[idx++];
         if (r.status === "fulfilled") {
+            sharedOk = true;
+            rawSharedCount = r.value.length;
             sharedResults = dropCurrentSession(r.value, currentSessionId);
         }
         else {
@@ -335,6 +403,49 @@ async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId)
     const haveMemorySections = sections.some((s) => s.startsWith("<personal-context>") || s.startsWith("<shared-context>"));
     if (!haveMemorySections) {
         log.debug("auto-context: no relevant memories found");
+        // Coverage signal (proposal 15): one event per turn (not per lane), with
+        // per-lane detail so "personal lane was down" is never misread as
+        // "personal memory is empty". Written only when at least one lane
+        // fulfilled — every-lane-failed is an availability event (#39), already
+        // logged by logSearchError above, and "unknown" is not "zero".
+        if (cfg.coverageLog) {
+            const lanes = [];
+            if (personalSearch)
+                lanes.push(personalOk
+                    ? {
+                        lane: "personal",
+                        status: "ok",
+                        candidates: personalResults.length,
+                        topScore: topScoreOf(personalResults),
+                    }
+                    : { lane: "personal", status: "error" });
+            if (sharedSearch)
+                lanes.push(sharedOk
+                    ? {
+                        lane: "shared",
+                        status: "ok",
+                        candidates: sharedResults.length,
+                        topScore: topScoreOf(sharedResults),
+                    }
+                    : { lane: "shared", status: "error" });
+            if (lanes.some((l) => l.status === "ok")) {
+                const candidates = personalResults.length + sharedResults.length;
+                const fetched = rawPersonalCount + rawSharedCount;
+                recordCoverageEvent({
+                    outcome: candidates > 0 ? "below_threshold" : "empty",
+                    prompt,
+                    fetched,
+                    candidates,
+                    droppedCurrentSession: fetched - candidates,
+                    topScore: topScoreOf([...personalResults, ...sharedResults]),
+                    threshold: cfg.relevanceThreshold,
+                    ranking: cfg.ranking.enabled,
+                    sessionId: currentSessionId,
+                    userId: resolved?.userId,
+                    lanes,
+                }, stateRoot);
+            }
+        }
         if (isKnownSender && resolved) {
             const contextLine = resolved.context ? ` ${resolved.context}` : "";
             return {

package/dist/hooks/emotional-state.js

@@ -3,7 +3,7 @@ import { resolveCurrentSessionId } from "../lib/session.js";
 import { isMultiSpeaker } from "../lib/speaker-tracker.js";
 import { log } from "../logger.js";
 import { sanitizeTraceText } from "./auto-trace.js";
-import { buildMoodWeatherContext, rollMood } from "./mood-weather.js";
+import { buildMoodWeatherContext, recordMoodRoll, rollMood, } from "./mood-weather.js";
 /** How many recent registers to surface as the "arc" at session start. */
 export const EMOTIONAL_ARC_LIMIT = 3;
 const MIN_MESSAGES = 3;
@@ -15,6 +15,12 @@ const MIN_CONVERSATION_LENGTH = 100;
  * heartbeat overwrite the register from a deep conversation (the whipsaw).
  * `ctx.trigger` is one of cron|heartbeat|manual|memory|overflow|user; we store
  * only for user-driven turns (and `overflow`, a continuation of a user run).
+ *
+ * Lifetime (verified against openclaw core, issue #70): `trigger` is PER-RUN,
+ * not session-fixed — core rebuilds the hook ctx from each run's own params
+ * (embedded-agent-runner/run.ts), and inbound human replies always start a new
+ * run with trigger="user" even inside a cron-originated session. So a scheduled
+ * check-in that becomes a real conversation IS stored on the human turns.
  */
 const NON_CONVERSATIONAL_TRIGGERS = new Set(["cron", "heartbeat", "memory"]);
 /**
@@ -224,12 +230,15 @@ export function buildEmotionalStateFetchHandler(client, cfg, deps = {}) {
                 if (sessionKey)
                     sessionMoods.set(sessionKey, mood);
                 log.info(`mood-weather: rolled "${mood.id}" this session`);
-                // Coordination with issue #71 (mood-weather observability): if #71's
-                // recordMoodRoll(client, mood, {...}) has landed, its call belongs
-                // HERE — inside this `!priorMood` guard — not on a bare `if (mood)`
-                // at the two return sites below. A priorMood replay (post-compaction
-                // re-injection of an already-rolled mood) is not a new roll; calling
-                // recordMoodRoll on replay would log the same event twice.
+                // Observability record (issue #71) — fire-and-forget, recall-excluded.
+                // Stays inside the !priorMood guard: a post-compaction replay of an
+                // already-rolled mood is NOT a new roll and must not double-log. Rolls
+                // only happen past the still-extracting early return above, so every
+                // recorded roll is one that actually lands in this session's context.
+                recordMoodRoll(client, mood, {
+                    sessionKey,
+                    relationshipId: cfg.relationshipId,
+                });
             }
             const moodBlock = mood ? buildMoodWeatherContext(mood) : "";
             if (usable.length === 0) {
@@ -239,7 +248,9 @@ export function buildEmotionalStateFetchHandler(client, cfg, deps = {}) {
                     injectedSessions.add(sessionKey);
                 return moodBlock ? { prependContext: moodBlock } : undefined;
             }
-            log.debug(`emotional-context: injecting ${usable.length} recent register(s)`);
+            // log.diag, not debug: the exact line issue #118's live audit proved
+            // invisible — one line per injection, operator-meaningful.
+            log.diag(`emotional-context: injecting ${usable.length} recent register(s)`);
             // Mood block comes AFTER the arc so it reads as today's override on top
             // of the remembered trajectory — not blended into it.
             const context = moodBlock

package/dist/hooks/memory-sync.js

@@ -1,7 +1,7 @@
 import * as path from "node:path";
 import { getWorkspaceDir } from "../config.js";
 import { log } from "../logger.js";
-import { syncMarkdownFile, syncMarkdownFileSectionized, syncAllMemoryFiles, syncAllFilesSectionized, } from "../sync/markdown.js";
+import { resolveSyncSource, resolveWatchPath, syncMarkdownFile, syncMarkdownFileSectionized, syncAllMemoryFiles, syncAllFilesSectionized, } from "../sync/markdown.js";
 /**
  * Build a handler for file change events that syncs markdown files to Hyperspell.
  *
@@ -21,17 +21,27 @@ export function buildFileSyncHandler(client, cfg) {
     const debounceMs = cfg.syncMemoriesConfig.debounceMs;
     const ignoreDirs = new Set(cfg.syncMemoriesConfig.ignorePaths);
     // Resolve additional watch paths to absolute paths for matching
-    const resolvedWatchPaths = (watchPaths ?? []).map((wp) => wp.startsWith("/") ? wp : path.join(workspaceDir, wp));
+    const resolvedWatchPaths = (watchPaths ?? []).map((wp) => resolveWatchPath(workspaceDir, wp.path));
     /**
      * Mirror the bulk walk's exclusions on the live path: a file under a
      * dot-directory (e.g. .dreams) or an ignored directory (e.g. dreaming) must
      * not live-sync either, or an edit would re-ingest exactly what the walk
-     * skips.
+     * skips. Applies against every watch root (memory/ AND each watchPath), so
+     * e.g. notes/brainstem/.drafts/x.md is excluded like the walk excludes it.
+     * The longest containing root wins: segments inside an explicitly configured
+     * watchPath are judged, the watchPath's own path is not.
      */
     function isIgnoredPath(filePath) {
-        const rel = path.relative(memoryDir, filePath);
-        if (rel.startsWith("..") || path.isAbsolute(rel))
+        let root;
+        for (const candidate of [memoryDir, ...resolvedWatchPaths]) {
+            if (filePath === candidate || filePath.startsWith(candidate + path.sep)) {
+                if (!root || candidate.length > root.length)
+                    root = candidate;
+            }
+        }
+        if (!root)
             return false;
+        const rel = path.relative(root, filePath);
         const segments = rel.split(path.sep).slice(0, -1); // directory segments only
         return segments.some((seg) => seg.startsWith(".") || ignoreDirs.has(seg));
     }
@@ -59,9 +69,12 @@ export function buildFileSyncHandler(client, cfg) {
     async function doSync(filePath) {
         const fileName = path.basename(filePath);
         log.info(`Memory file changed: ${fileName}`);
+        // Same provenance the startup bulk sync stamps, so a file gets identical
+        // openclaw_sync_source metadata whichever path ingests it first.
+        const syncSource = resolveSyncSource(filePath, workspaceDir, watchPaths ?? []);
         try {
             if (sectionize) {
-                const result = await syncMarkdownFileSectionized(client, filePath, workspaceDir, { userId: syncUserId });
+                const result = await syncMarkdownFileSectionized(client, filePath, workspaceDir, { userId: syncUserId, syncSource });
                 if (result.synced > 0 || result.removed > 0) {
                     log.info(`Section-synced ${fileName}: ${result.synced} synced, ${result.skipped} unchanged, ${result.removed} removed`);
                 }
@@ -77,7 +90,10 @@ export function buildFileSyncHandler(client, cfg) {
             }
             else {
                 // Legacy whole-file sync
-                const result = await syncMarkdownFile(client, filePath, { userId: syncUserId });
+                const result = await syncMarkdownFile(client, filePath, {
+                    userId: syncUserId,
+                    syncSource,
+                });
                 if (result.success) {
                     log.info(`Synced ${fileName} -> ${result.resourceId}`);
                 }

package/dist/hooks/mood-weather.js

@@ -22,11 +22,16 @@
  *    store path. One random cold morning must NOT calcify into "we've been
  *    distant lately." One day's weather, then gone. (The store handler in
  *    emotional-state.ts is untouched, so this is enforced by construction.)
+ *    A private, recall-excluded observability record IS written per roll
+ *    (issue #71) — see recordMoodRoll below; it is invisible to every
+ *    injection/recall path, so the guarantee holds.
  *  - BOUNDED. The dice can make her *difficult* — short, contrary, melancholy,
  *    flat. They do NOT get to make her hurtful on purpose. "In a mood" is alive;
  *    "mean" is just a bad feature. Mood descriptions below stay on the right side
  *    of that line.
  */
+import { MOOD_WEATHER_SOURCE } from "../lib/filters.js";
+import { log } from "../logger.js";
 /**
  * The weather table. Warmer/lighter moods are weighted a touch heavier than the
  * darker ones — not to defang it, but because a person who woke up cold *every*
@@ -111,3 +116,43 @@ export function buildMoodWeatherContext(mood) {
         "</hyperspell-mood-weather>",
     ].join("\n");
 }
+/** Collection the roll records live in, so /moodweather can list them without a search. */
+export const MOOD_WEATHER_COLLECTION = "mood-weather";
+/**
+ * Fire-and-forget observability record for a mood roll (issue #71).
+ *
+ * This does NOT weaken the "does not write forward" contract above: the record
+ * goes to the generic vault store tagged openclaw_source="mood_weather", which
+ * excludeFilterFor() drops from every recall path (auto-context, the
+ * hyperspell_search tool, startup-orientation loops, knowledge graph). The
+ * emotional-state arc fetch reads a different endpoint entirely (GET
+ * /emotional-state[/recent], written only by storeEmotionalState), so it can
+ * never surface there. Queryable only via the dedicated /moodweather command.
+ *
+ * Written via client.addMemory (memories.add) — NEVER POST /messages: a
+ * /messages write carrying metadata renders the row non-retrievable (see the
+ * warning in lib/filters.ts), while memories.add metadata is proven to persist
+ * and be filterable (canary A in docs/filter-dialect-test.mjs).
+ *
+ * Deliberately not awaited: this sits on the first-turn injection hot path, and
+ * a logging write must never delay or break the session.
+ */
+export function recordMoodRoll(client, mood, opts) {
+    const rolledAt = new Date().toISOString();
+    void client
+        .addMemory(`Mood weather roll: woke up "${mood.id}" (${rolledAt}). Exogenous session mood — uncaused, session-only, never part of the relational register.`, {
+        title: `Mood weather — ${mood.id} (${rolledAt.slice(0, 10)})`,
+        collection: MOOD_WEATHER_COLLECTION,
+        metadata: {
+            openclaw_source: MOOD_WEATHER_SOURCE,
+            mood: mood.id,
+            rolled_at: rolledAt,
+            ...(opts.sessionKey ? { session: opts.sessionKey } : {}),
+            ...(opts.relationshipId ? { relationship_id: opts.relationshipId } : {}),
+        },
+    })
+        .catch((err) => {
+        // Fire-and-forget — observability must never break the session.
+        log.warn("mood-weather: roll record write failed (non-fatal)", err);
+    });
+}

package/dist/hooks/startup-orientation.js

@@ -1,3 +1,4 @@
+import { excludeFilterFor } from "../lib/filters.js";
 import { resolveUser } from "../lib/sender.js";
 import { resolveCurrentSessionId } from "../lib/session.js";
 import { isMultiSpeaker } from "../lib/speaker-tracker.js";
@@ -219,9 +220,14 @@ export async function gatherOrientation(client, cfg, userId) {
             : Promise.resolve([]);
     const [recentSettled, loopsSettled] = await Promise.allSettled([
         recentFetch,
+        // Loops feed agent context, so tagged observability rows (agent_end
+        // traces, mood_weather rolls) must be dropped like on every other recall
+        // path — this also closes a pre-existing gap where agent_end traces
+        // could surface in the loops block.
         client.search(so.loopsQuery, {
             limit: so.loopsLimit,
             userId,
+            filter: excludeFilterFor(cfg),
         }),
     ]);
     const recentOk = recentSettled.status === "fulfilled";
@@ -310,7 +316,10 @@ export function buildStartupOrientationHandler(client, cfg) {
             return;
         }
         const blocks = [gathered.recentBlock, gathered.loopsBlock].filter((b) => b !== null);
-        log.debug(`startup-orientation: injecting recent=${gathered.recentCount} loops=${gathered.loopsCount}`);
+        // log.diag, not debug: this one-line injection summary is the operator's
+        // only live signal that orientation fired (issue #118 — host drops plugin
+        // debug output from gateway.log).
+        log.diag(`startup-orientation: injecting recent=${gathered.recentCount} loops=${gathered.loopsCount}`);
         return { prependContext: blocks.join("\n\n") };
     };
 }

package/dist/index.js

@@ -1,7 +1,7 @@
 import { HyperspellClient } from "./client.js";
 import { registerCommands } from "./commands/slash.js";
 import { registerCliCommands } from "./commands/setup.js";
-import { parseConfig, hyperspellConfigSchema, getWorkspaceDir } from "./config.js";
+import { parseConfig, hyperspellConfigSchema, getWorkspaceDir, VALID_SOURCES } from "./config.js";
 import { buildAutoContextHandler } from "./hooks/auto-context.js";
 import { buildAutoTraceHandler } from "./hooks/auto-trace.js";
 import { buildEmotionalStateCompactionHandler, buildEmotionalStateFetchHandler, buildEmotionalStateSessionCleanupHandler, buildEmotionalStateStoreHandler, } from "./hooks/emotional-state.js";
@@ -79,6 +79,13 @@ export default {
         }
         const cfg = parseConfig(api.pluginConfig);
         initLogger(api.logger, cfg.debug);
+        // sourceWeights keys are deliberately not schema-validated (new backend
+        // sources must not fail manifest validation), so a typo is a silent
+        // neutral no-op — surface it once at startup instead.
+        const unknownWeightKeys = Object.keys(cfg.ranking.sourceWeights).filter((k) => !VALID_SOURCES.includes(k));
+        if (unknownWeightKeys.length > 0) {
+            log.diag(`ranking.sourceWeights keys not in the known source list (typo? they weight nothing): ${unknownWeightKeys.join(", ")}`);
+        }
         const client = new HyperspellClient(cfg);
         // Channel quarantine (cfg.excludeChannels): excluded conversations get no
         // memory surface in either direction. Guard the shared choke points here —
@@ -170,6 +177,22 @@ export default {
         if (cfg.knowledgeGraph.enabled) {
             registerNetworkTools(api, client, cfg);
         }
+        else {
+            // Discoverability (issue #81): the Memory Network ships fully built but
+            // default-off. If memories are accumulating (hot buffer / auto-trace /
+            // emotional state) and the operator never made a knowledgeGraph decision,
+            // say so once at startup — otherwise the feature is undetectable without
+            // reading source. Keyed off the RAW config: an explicit `knowledgeGraph`
+            // key (even { enabled: false }) is a decision and suppresses this.
+            const memoryAccumulating = cfg.hotBuffer.enabled || cfg.autoTrace.enabled || cfg.emotionalContext;
+            if (rawConfig?.knowledgeGraph === undefined && memoryAccumulating) {
+                log.info("memories are accumulating but the Memory Network (knowledgeGraph) is not configured — " +
+                    "no entity extraction into memory/people|projects|organizations|topics will run. " +
+                    "Enable it via 'openclaw openclaw-hyperspell setup' (Memory Network step) or set " +
+                    "knowledgeGraph.enabled: true, or silence this note with knowledgeGraph: { enabled: false }. " +
+                    "See README § Memory Network.");
+            }
+        }
         // Register slash commands
         registerCommands(api, client, cfg);
         // Register service for lifecycle management

package/dist/lib/coverage-log.js

@@ -0,0 +1,47 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getWorkspaceDir } from "../config.js";
+import { log } from "../logger.js";
+export const COVERAGE_LOG_NAME = ".hyperspell-coverage.jsonl";
+// Truncation bounds line size and what sits on disk; 500 chars is enough to
+// judge "should this have found something" without full-prompt fidelity.
+const MAX_PROMPT_CHARS = 500;
+// One-generation rotation caps the total footprint at ~2× this (current + .old).
+const MAX_LOG_BYTES = 5 * 1024 * 1024;
+/**
+ * Append one coverage event to the LOCAL-ONLY coverage log
+ * (`<workspaceDir>/.hyperspell-coverage.jsonl`). Never sent to the backend —
+ * same trust domain as the hot-buffer state files already living there.
+ * Prompt text is sensitive plaintext, so writes happen only behind the
+ * explicit `coverageLog: true` opt-in (checked at call sites, default OFF).
+ * Best-effort by contract: any failure is swallowed (debug-logged) — a
+ * coverage write must never throw into, block, or delay the turn.
+ */
+export function recordCoverageEvent(event, stateRoot) {
+    try {
+        const dir = stateRoot ?? getWorkspaceDir();
+        const p = path.join(dir, COVERAGE_LOG_NAME);
+        rotateIfOversized(p);
+        const line = JSON.stringify({
+            v: 1,
+            ts: new Date().toISOString(),
+            ...event,
+            prompt: event.prompt.slice(0, MAX_PROMPT_CHARS),
+        });
+        fs.appendFileSync(p, `${line}\n`);
+    }
+    catch (err) {
+        log.debug(`coverage-log: append failed — ${String(err)}`);
+    }
+}
+/** One-generation rotation: current file > cap → rename to .old (replacing the
+ * previous .old), start fresh. Total footprint bounded at ~2× MAX_LOG_BYTES. */
+function rotateIfOversized(p) {
+    try {
+        if (fs.statSync(p).size > MAX_LOG_BYTES)
+            fs.renameSync(p, `${p}.old`);
+    }
+    catch {
+        /* missing file or rename race — appendFileSync creates/handles it */
+    }
+}