@hyperspell/openclaw-hyperspell 0.18.1 → 0.20.0

package/dist/hooks/hot-buffer.js

@@ -1,3 +1,7 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getWorkspaceDir } from "../config.js";
+import { channelIdFromCtx } from "../lib/exclude-channels.js";
 import { resolveUser } from "../lib/sender.js";
 import { cleanupSpeakerSession, isMultiSpeaker, recordSender, senderIdFromCtx, } from "../lib/speaker-tracker.js";
 import { log } from "../logger.js";
@@ -12,10 +16,62 @@ const MAX_TOTAL_CHARS = 5_242_880;
  * this we'd re-post every prior message each turn. The server upserts (so it's
  * harmless correctness-wise), but re-posting is wasteful — this keeps each turn
  * to just its new messages. Cleared on session_end.
+ *
+ * This map alone is NOT restart-safe: it's module-scope, in-memory only. A
+ * gateway restart wipes it without firing session_end, so the next turn of a
+ * still-open session sees an empty set and re-posts the entire transcript to
+ * date in one shot (observed live: two 499/503-message flushes right after
+ * restarts, vs. the normal 2-10). `loadPersistedSent`/`persistSent` below
+ * mirror this map to disk per session so a restart degrades to "reload from
+ * disk" instead of "resend everything."
  */
 const sentBySession = new Map();
+function stateDir(root) {
+    return path.join(root, "hot-buffer-sent");
+}
+function stateFile(root, sessionId) {
+    const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return path.join(stateDir(root), `${safe}.json`);
+}
+function loadPersistedSent(root, sessionId) {
+    try {
+        const raw = fs.readFileSync(stateFile(root, sessionId), "utf-8");
+        const ids = JSON.parse(raw);
+        return new Set(ids);
+    }
+    catch {
+        return new Set();
+    }
+}
+function persistSent(root, sessionId, sent) {
+    try {
+        fs.mkdirSync(stateDir(root), { recursive: true });
+        fs.writeFileSync(stateFile(root, sessionId), JSON.stringify([...sent]));
+    }
+    catch (err) {
+        log.error("hot-buffer: failed to persist sent-id state to disk", err);
+    }
+}
+function deletePersistedSent(root, sessionId) {
+    try {
+        fs.unlinkSync(stateFile(root, sessionId));
+    }
+    catch {
+        // Nothing to clean up — fine.
+    }
+}
 /** Sessions where we've already emitted the group-chat attribution warning. */
 const warnedGroupSessions = new Set();
+/**
+ * Test-only: drop just the in-memory dedup cache for a session, leaving any
+ * persisted-to-disk state untouched. This is what a bare gateway restart
+ * looks like (module state wiped, disk state intact) — as opposed to
+ * `buildHotBufferSessionCleanupHandler`'s session_end, which clears both on
+ * purpose. Not used outside tests.
+ */
+export function __simulateRestartForTest(sessionId) {
+    sentBySession.delete(sessionId);
+}
 /**
  * Flatten a message's content into a single sanitized text string. Mirrors the
  * auto-trace sanitizer so the hot buffer never captures injected
@@ -57,7 +113,8 @@ function messageId(role, text) {
  * searchable. Runs on `agent_end` — fire-and-forget; a failure here must never
  * break the turn.
  */
-export function buildHotBufferHandler(client, cfg) {
+export function buildHotBufferHandler(client, cfg, opts) {
+    const stateRoot = opts?.stateRoot ?? getWorkspaceDir();
     return async (event, ctx) => {
         if (event.success === false) {
             log.debug("hot-buffer: skipping — agent ended with error");
@@ -86,7 +143,15 @@ export function buildHotBufferHandler(client, cfg) {
             event.sessionId ??
             crypto.randomUUID();
         const resourceId = sessionId;
-        const sent = sentBySession.get(sessionId) ?? new Set();
+        // Fall back to disk before assuming "nothing sent yet" — an empty
+        // in-memory entry is ambiguous between "brand new session" and "this
+        // process restarted mid-session," and treating the latter as the former
+        // is exactly the full-transcript-resend bug this guards against.
+        let sent = sentBySession.get(sessionId);
+        if (!sent) {
+            sent = loadPersistedSent(stateRoot, sessionId);
+            sentBySession.set(sessionId, sent);
+        }
         // Record the current sender for evidence-based multi-speaker detection.
         // isMultiSpeaker() will return true once a second distinct sender_id
         // appears in this session, regardless of whether is_group_chat was set.
@@ -166,9 +231,11 @@ export function buildHotBufferHandler(client, cfg) {
             // 2026-07-02 (docs/filter-dialect-test.mjs: metadata-carrying row is
             // baseline-retrievable AND filterable). The retrieval exclude
             // {openclaw_source:{$ne:"agent_end"}} keeps "hot_buffer" rows.
-            const channelId = typeof ctx?.channelId === "string" && ctx.channelId.length > 0
-                ? ctx.channelId
-                : undefined;
+            // channelIdFromCtx (ctx.channelId, else sessionKey parse) is the same
+            // resolver the quarantine check uses — tag-time identity must equal
+            // quarantine-time identity or purge-channel misses rows the exclude
+            // would have blocked.
+            const channelId = channelIdFromCtx(ctx);
             const metadata = {
                 openclaw_source: "hot_buffer",
                 openclaw_session_id: sessionId,
@@ -186,6 +253,7 @@ export function buildHotBufferHandler(client, cfg) {
             for (const id of pendingIds)
                 sent.add(id);
             sentBySession.set(sessionId, sent);
+            persistSent(stateRoot, sessionId, sent);
             log.info(`hot-buffer: wrote ${total} message(s) to ${sessionId} (user=${userId})`);
         }
         catch (err) {
@@ -195,13 +263,15 @@ export function buildHotBufferHandler(client, cfg) {
     };
 }
 /** Drop per-session state on session end to avoid unbounded growth. */
-export function buildHotBufferSessionCleanupHandler() {
+export function buildHotBufferSessionCleanupHandler(opts) {
+    const stateRoot = opts?.stateRoot ?? getWorkspaceDir();
     return (event) => {
         const sessionId = event.sessionId;
         if (sessionId) {
             sentBySession.delete(sessionId);
             warnedGroupSessions.delete(sessionId);
             cleanupSpeakerSession(sessionId);
+            deletePersistedSent(stateRoot, sessionId);
         }
     };
 }

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";
@@ -78,7 +79,7 @@ function isoDaysAgo(days) {
  * an unresolved caller has no personal space to orient to. In single-user mode,
  * return undefined so the client falls back to its configured userId.
  */
-function personalUserId(cfg, ctx) {
+export function personalUserId(cfg, ctx) {
     if (!cfg.multiUser)
         return { skip: false, userId: undefined };
     const resolved = resolveUser(ctx, cfg);
@@ -191,8 +192,83 @@ async function fetchRecentConversations(client, limit, userId) {
     }
     return out;
 }
-export function buildStartupOrientationHandler(client, cfg) {
+/**
+ * The fetch+format core of startup orientation, shared by the real
+ * before_agent_start handler and the read-only /previewcontext command.
+ * Pure with respect to session lifecycle: no inject-once cache, no retry
+ * counting — callers own that policy. Keeping one formatter here keeps the
+ * preview byte-identical to real injection.
+ */
+export async function gatherOrientation(client, cfg, userId) {
     const so = cfg.startupOrientation;
+    // Source recent-interactions from wherever the session record actually
+    // lives. Prefer the hot buffer (modern path: clean session-grouped vault
+    // resources, present whenever the hot buffer is on — including auto-trace-
+    // off agents). Fall back to agent_end traces only when there's no hot
+    // buffer but auto-trace is on. Otherwise skip: there's nothing to fetch,
+    // and the trace-source list is expensive (observed ~12s + failing/turn),
+    // blocking before_agent_start and slowing the reply.
+    const recentSource = cfg.hotBuffer.enabled
+        ? "hotBuffer"
+        : cfg.autoTrace.enabled
+            ? "autoTrace"
+            : "none";
+    const recentFetch = recentSource === "hotBuffer"
+        ? fetchRecentConversations(client, so.recentLimit, userId)
+        : recentSource === "autoTrace"
+            ? fetchRecentTraces(client, isoDaysAgo(so.recentDays), so.recentLimit, 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";
+    const loopsOk = loopsSettled.status === "fulfilled";
+    const recent = recentOk ? recentSettled.value : [];
+    const loops = loopsOk ? loopsSettled.value : [];
+    if (!recentOk) {
+        log.error("startup-orientation: recent listMemories failed", recentSettled.reason);
+    }
+    if (!loopsOk) {
+        log.error("startup-orientation: loops search failed", loopsSettled.reason);
+    }
+    const recentBody = formatRecentInteractions(recent);
+    const loopsBody = formatUnfinishedLoops(loops);
+    return {
+        recentOk,
+        loopsOk,
+        recentCount: recent.length,
+        loopsCount: loops.length,
+        recentSource,
+        recentBlock: recentBody
+            ? [
+                "<hyperspell-recent-interactions>",
+                `Your last ${so.recentDays} days of conversations with this user, most-recent-first. Use for situational continuity — don't quote verbatim.`,
+                "",
+                recentBody,
+                "</hyperspell-recent-interactions>",
+            ].join("\n")
+            : null,
+        loopsBlock: loopsBody
+            ? [
+                "<hyperspell-unfinished-loops>",
+                "Possible open threads — promises made, questions pending, work in progress. Low-confidence retrieval; treat as prompts to consider, not facts to act on.",
+                "",
+                loopsBody,
+                "</hyperspell-unfinished-loops>",
+            ].join("\n")
+            : null,
+    };
+}
+export function buildStartupOrientationHandler(client, cfg) {
     return async (_event, ctx) => {
         const sessionKey = ctx?.sessionKey;
         if (sessionKey && injectedSessions.has(sessionKey))
@@ -224,36 +300,8 @@ export function buildStartupOrientationHandler(client, cfg) {
                 injectedSessions.add(sessionKey);
             return;
         }
-        // Source recent-interactions from wherever the session record actually
-        // lives. Prefer the hot buffer (modern path: clean session-grouped vault
-        // resources, present whenever the hot buffer is on — including auto-trace-
-        // off agents). Fall back to agent_end traces only when there's no hot
-        // buffer but auto-trace is on. Otherwise skip: there's nothing to fetch,
-        // and the trace-source list is expensive (observed ~12s + failing/turn),
-        // blocking before_agent_start and slowing the reply.
-        const recentFetch = cfg.hotBuffer.enabled
-            ? fetchRecentConversations(client, so.recentLimit, userId)
-            : cfg.autoTrace.enabled
-                ? fetchRecentTraces(client, isoDaysAgo(so.recentDays), so.recentLimit, userId)
-                : Promise.resolve([]);
-        const [recentSettled, loopsSettled] = await Promise.allSettled([
-            recentFetch,
-            client.search(so.loopsQuery, {
-                limit: so.loopsLimit,
-                userId,
-            }),
-        ]);
-        const recentOk = recentSettled.status === "fulfilled";
-        const loopsOk = loopsSettled.status === "fulfilled";
-        const recent = recentOk ? recentSettled.value : [];
-        const loops = loopsOk ? loopsSettled.value : [];
-        if (!recentOk) {
-            log.error("startup-orientation: recent listMemories failed", recentSettled.reason);
-        }
-        if (!loopsOk) {
-            log.error("startup-orientation: loops search failed", loopsSettled.reason);
-        }
-        if (!recentOk && !loopsOk) {
+        const gathered = await gatherOrientation(client, cfg, userId);
+        if (!gathered.recentOk && !gathered.loopsOk) {
             if (sessionKey)
                 failedAttempts.set(sessionKey, tries + 1);
             log.debug(`startup-orientation: both calls failed (attempt ${tries + 1}/${MAX_ATTEMPTS}); will retry next turn`);
@@ -263,32 +311,15 @@ export function buildStartupOrientationHandler(client, cfg) {
             injectedSessions.add(sessionKey);
             failedAttempts.delete(sessionKey);
         }
-        const recentBody = formatRecentInteractions(recent);
-        const loopsBody = formatUnfinishedLoops(loops);
-        if (!recentBody && !loopsBody) {
+        if (!gathered.recentBlock && !gathered.loopsBlock) {
             log.debug("startup-orientation: nothing to inject");
             return;
         }
-        const blocks = [];
-        if (recentBody) {
-            blocks.push([
-                "<hyperspell-recent-interactions>",
-                `Your last ${so.recentDays} days of conversations with this user, most-recent-first. Use for situational continuity — don't quote verbatim.`,
-                "",
-                recentBody,
-                "</hyperspell-recent-interactions>",
-            ].join("\n"));
-        }
-        if (loopsBody) {
-            blocks.push([
-                "<hyperspell-unfinished-loops>",
-                "Possible open threads — promises made, questions pending, work in progress. Low-confidence retrieval; treat as prompts to consider, not facts to act on.",
-                "",
-                loopsBody,
-                "</hyperspell-unfinished-loops>",
-            ].join("\n"));
-        }
-        log.debug(`startup-orientation: injecting recent=${recent.length} loops=${loops.length}`);
+        const blocks = [gathered.recentBlock, gathered.loopsBlock].filter((b) => b !== null);
+        // 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

@@ -10,6 +10,7 @@ import { buildHotBufferHandler, buildHotBufferSessionCleanupHandler, } from "./h
 import { buildStartupOrientationCompactionHandler, buildStartupOrientationHandler, buildStartupOrientationSessionCleanupHandler, } from "./hooks/startup-orientation.js";
 import { isExcludedChannel } from "./lib/exclude-channels.js";
 import { initLogger, log } from "./logger.js";
+import { createEmotionalArcToolFactory } from "./tools/emotional-arc.js";
 import { createRememberToolFactory } from "./tools/remember.js";
 import { createSearchToolFactory } from "./tools/search.js";
 import { registerNetworkTools } from "./graph/index.js";
@@ -63,6 +64,17 @@ export default {
                     };
                 },
             });
+            api.registerCommand({
+                name: "previewcontext",
+                description: "Preview what Hyperspell would inject at the next session start",
+                acceptsArgs: false,
+                requireAuth: false,
+                handler: async () => {
+                    return {
+                        text: "Hyperspell not configured. Run 'openclaw openclaw-hyperspell setup' first.",
+                    };
+                },
+            });
             return;
         }
         const cfg = parseConfig(api.pluginConfig);
@@ -89,6 +101,15 @@ export default {
         });
         const startHandlers = [];
         if (cfg.emotionalContext) {
+            // moodWeatherChance defaults to 0, so mood weather is inert unless the
+            // operator opts in — say so once at startup rather than staying silent.
+            if (cfg.moodWeatherChance === 0) {
+                log.info("emotionalContext is on but moodWeatherChance is 0 — mood weather will never roll. Set moodWeatherChance (e.g. 0.03–0.05) to enable it.");
+            }
+            // On-demand arc re-fetch (issue #76): the session-start injection can be
+            // compacted out of history mid-session; this tool lets the agent pull the
+            // exact same block back without waiting for the next prompt build.
+            api.registerTool(toolUnlessQuarantined(createEmotionalArcToolFactory(client, cfg)), { name: "hyperspell_emotional_arc" });
             startHandlers.push(buildEmotionalStateFetchHandler(client, cfg));
             api.on("after_compaction", buildEmotionalStateCompactionHandler());
             api.on("session_end", buildEmotionalStateSessionCleanupHandler());
@@ -149,6 +170,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/eval-matchers.js

@@ -0,0 +1,49 @@
+/**
+ * Parse the JSONL fixture file: one JSON object per line; blank lines and
+ * `//` comment lines are ignored. Every fixture needs a query and at least
+ * one matcher — a matcher-less line would vacuously fail and look like a
+ * ranking problem, so reject it at parse time with the line number.
+ */
+export function parseFixtures(jsonl) {
+    const fixtures = [];
+    for (const [idx, line] of jsonl.split("\n").entries()) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("//"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            throw new Error(`fixtures line ${idx + 1}: invalid JSON`);
+        }
+        const f = parsed;
+        if (typeof f.query !== "string" || f.query.trim() === "") {
+            throw new Error(`fixtures line ${idx + 1}: "query" is required`);
+        }
+        if (!f.expectedResourceId && !f.expectedTitleContains) {
+            throw new Error(`fixtures line ${idx + 1}: at least one of "expectedResourceId" / "expectedTitleContains" is required`);
+        }
+        fixtures.push(f);
+    }
+    return fixtures;
+}
+/**
+ * OR-semantics matcher (proposal §3.1): a result satisfies a fixture if the
+ * resourceId matches exactly, or the title/any highlight contains the
+ * expected substring (case-insensitive). Returns WHICH matcher hit so the
+ * runner can warn when only the title matched — the id may have churned.
+ */
+export function matchFixture(r, f) {
+    if (f.expectedResourceId && r.resourceId === f.expectedResourceId)
+        return "id";
+    if (f.expectedTitleContains) {
+        const needle = f.expectedTitleContains.toLowerCase();
+        const hay = [r.title ?? "", ...r.highlights.map((h) => h.text)]
+            .join(" ")
+            .toLowerCase();
+        if (hay.includes(needle))
+            return "title";
+    }
+    return null;
+}

package/dist/lib/exclude-channels.js

@@ -11,6 +11,10 @@
  * (`ctx.channelId` on agent hook contexts — e.g. a Discord channel id). Tool
  * factory contexts don't carry `channelId`, so we recover the same id from the
  * composite `sessionKey` (`agent:<agentId>:<provider>:<kind>:<id>[...]`).
+ *
+ * Quarantine is FORWARD-ONLY: it stops future injection/writes/tools but does
+ * not remove already-synced content. Retroactive cleanup of channel-tagged
+ * rows is the `purge-channel` CLI command (commands/purge-channel.ts).
  */
 // Conversation-kind segments used in OpenClaw session keys. Mirrors core's
 // TARGET_PREFIXES (src/plugins/hook-agent-context.ts) so the sessionKey
@@ -40,6 +44,17 @@ export function channelIdFromCtx(ctx) {
         return direct;
     return conversationIdFromSessionKey(ctx?.sessionKey);
 }
+/**
+ * True when a stored conversation id belongs to `channel` — exact match or a
+ * thread suffix (`<channel>:thread:<n>`), case-insensitive. Shared by the
+ * quarantine check and the purge-channel CLI so "what gets blocked" and "what
+ * gets purged" can never drift apart.
+ */
+export function conversationMatchesChannel(id, channel) {
+    const a = id.toLowerCase();
+    const b = channel.toLowerCase();
+    return a === b || a.startsWith(`${b}:`);
+}
 /**
  * True when the context's conversation is quarantined. Purely subtractive on
  * failure: an unresolvable id means "not excluded" — a session we can't place
@@ -48,12 +63,8 @@ export function channelIdFromCtx(ctx) {
 export function isExcludedChannel(ctx, cfg) {
     if (cfg.excludeChannels.length === 0)
         return false;
-    const id = channelIdFromCtx(ctx)?.toLowerCase();
+    const id = channelIdFromCtx(ctx);
     if (!id)
         return false;
-    return cfg.excludeChannels.some((entry) => {
-        const excluded = entry.toLowerCase();
-        // Prefix match so threads inside an excluded channel inherit the quarantine.
-        return id === excluded || id.startsWith(`${excluded}:`);
-    });
+    return cfg.excludeChannels.some((entry) => conversationMatchesChannel(id, entry));
 }