@yeaft/webchat-agent 0.1.630 → 0.1.632

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.630",
+  "version": "0.1.632",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/config.js

@@ -217,6 +217,8 @@ function loadLegacyConfig(dir, overrides) {
     maxContinueTurns: overrides.maxContinueTurns ?? fileConfig.maxContinueTurns ?? DEFAULTS.maxContinueTurns,
     // task-318: legacy path never had the `unify` section — defaults.
     unify: normaliseUnifySection(null),
+    // DESIGN-v2 feature flag. Default true (PR-E flipped). Override wins.
+    memoryV2: overrides.memoryV2 !== undefined ? !!overrides.memoryV2 : true,
     providers: null,
     primaryModel: null,
     fastModel: null,
@@ -313,6 +315,14 @@ export function loadConfig(overrides = {}) {
     // don't pollute the flat config namespace used by chat/crew code.
     unify: normaliseUnifySection(jsonConfig.unify),
 
+    // DESIGN-v2 feature flag. When true the engine routes recall through
+    // memory/recall-v2.js (per-scope memory.md + summary.md) and the
+    // session wires the v2 dream pipeline (dream-v2/runner.js). PR-E
+    // flipped the default to true; users who need the legacy R6 paths
+    // can opt out via `"memoryV2": false` in ~/.yeaft/config.json.
+    memoryV2: overrides.memoryV2 !== undefined ? !!overrides.memoryV2
+      : (jsonConfig.memoryV2 !== undefined ? !!jsonConfig.memoryV2 : true),
+
     // Legacy fields (null when using config.json)
     apiKey: overrides.apiKey || null,
     openaiApiKey: null,

package/unify/dream-v2/session-wiring.js

@@ -0,0 +1,171 @@
+/**
+ * dream-v2/session-wiring.js — DESIGN-v2 §13 wire-up for session.js.
+ *
+ * Bridges the framework-agnostic `runDream` orchestrator (dream-v2/runner.js)
+ * to the live yeaft session: groups store, conversation log, LLM adapter,
+ * and the engine's progress event sink.
+ *
+ * The dream pipeline only activates when `config.memoryV2 === true`. When
+ * the flag is off, this module is a no-op — the legacy R6 dream-scheduler
+ * keeps running as before (session.js still wires it).
+ */
+
+import { join } from 'path';
+import { runDream } from './runner.js';
+import { createDreamScheduler } from './schedule.js';
+import { listGroups, openGroup } from '../groups/group-store.js';
+
+/**
+ * Build the per-call options for runDream. Pure: takes a session and returns
+ * the closures runDream needs (listGroups, countMessages, loadGroupDiff, etc.).
+ *
+ * @param {Object} session  — the live Session object from loadSession()
+ * @param {(event: object) => void} [onProgress]
+ * @returns {Object}
+ */
+export function buildRunDreamOpts(session, onProgress) {
+  const yeaftDir = session.yeaftDir;
+  const memoryRoot = join(yeaftDir, 'memory');
+  const groupsRoot = join(yeaftDir, 'groups');
+
+  return {
+    root: memoryRoot,
+    llm: makeLlm(session),
+    listGroups: async () => {
+      try { return listGroups(groupsRoot).map(g => g.id); }
+      catch { return []; }
+    },
+    countMessages: async (gid) => {
+      try {
+        const h = openGroup(groupsRoot, gid);
+        let n = 0;
+        for (const _m of h.streamMessages()) n += 1;
+        return n;
+      } catch { return 0; }
+    },
+    loadGroupDiff: async (gid, sinceId) => {
+      try {
+        const h = openGroup(groupsRoot, gid);
+        const out = [];
+        let started = !sinceId;
+        for (const m of h.streamMessages()) {
+          if (!started) {
+            if (m.id === sinceId) started = true;
+            continue;
+          }
+          out.push(translateGroupMessage(m));
+        }
+        return out;
+      } catch { return []; }
+    },
+    loadOverlapPreamble: async (gid, beforeId, n) => {
+      try {
+        const h = openGroup(groupsRoot, gid);
+        const buf = [];
+        for (const m of h.streamMessages()) {
+          if (m.id === beforeId) break;
+          buf.push(m);
+        }
+        return buf.slice(-n).map(translateGroupMessage);
+      } catch { return []; }
+    },
+    onProgress,
+  };
+}
+
+/**
+ * Translate a group-store message record (id, from, role, text, ...) into
+ * the shape runDream expects (id, role, body, vpId, author, featureId).
+ *
+ * @param {Object} m
+ */
+function translateGroupMessage(m) {
+  const role = m.role || (m.from === 'user' ? 'user' : 'assistant');
+  const out = {
+    id: m.id,
+    role,
+    body: m.text || '',
+  };
+  if (role === 'assistant' && m.from && m.from !== 'user') {
+    out.vpId = m.from;
+  }
+  if (m.meta && typeof m.meta === 'object' && m.meta.featureId) {
+    out.featureId = m.meta.featureId;
+  }
+  return out;
+}
+
+/**
+ * Build the LLM callable that runDream's triage/apply prompts use.
+ *
+ * @param {Object} session
+ */
+function makeLlm(session) {
+  return async ({ pass, prompt, system }) => {
+    const adapter = session.adapter;
+    const model = session.config?.fastModelId || session.config?.model;
+    if (!adapter || typeof adapter.call !== 'function') {
+      throw new Error(`dream-v2: no adapter.call available (pass=${pass})`);
+    }
+    const r = await adapter.call({
+      model,
+      system: system || `You are the dream pipeline — pass: ${pass}.`,
+      messages: [{ role: 'user', content: prompt }],
+      maxTokens: 2048,
+    });
+    return (r && r.text) ? r.text : '';
+  };
+}
+
+/**
+ * Create a v2 dream scheduler bound to a session and wire its progress
+ * events into the engine's sub-agent event sink (web-bridge translates
+ * `dream_progress` into `unify_output` for the debug panel).
+ *
+ * @param {Object} session
+ * @returns {Object}                   — scheduler (start/stop/triggerNow)
+ */
+export function createV2DreamScheduler(session) {
+  const onProgress = (evt) => {
+    try {
+      const sink = session.engine?.subAgentEventSink || null;
+      // We don't have a sub-agent id; emit on the engine's standard
+      // event channel instead. session.engine exposes setSubAgentEventSink
+      // for nested events; for top-level dream, we route through trace.
+      if (typeof session.trace?.event === 'function') {
+        session.trace.event('dream_progress', evt);
+      }
+      if (typeof session._dreamProgressSink === 'function') {
+        session._dreamProgressSink(evt);
+      }
+      // Best-effort console for debug builds.
+      if (session.config?.debug) {
+        // eslint-disable-next-line no-console
+        console.log('[dream-v2]', evt);
+      }
+    } catch { /* never let progress reporting kill the run */ }
+  };
+
+  const run = (opts = {}) => runDream({
+    ...buildRunDreamOpts(session, onProgress),
+    manual: !!opts.manual,
+    scopeFilter: Array.isArray(opts.scopeFilter) ? opts.scopeFilter : undefined,
+  });
+
+  const v2 = createDreamScheduler({
+    run,
+    logger: session.config?.debug ? console : undefined,
+  });
+  // Auto-start the timer.
+  v2.start();
+  // Adapter shim: legacy callers (web-bridge) call .noteUserMessage() and
+  // .triggerDreamNow() / .shutdown(). Map them onto the v2 API.
+  return {
+    noteUserMessage() { /* v2 doesn't gate on user-message count */ },
+    triggerDreamNow() { return v2.triggerNow(); },
+    shutdown() { v2.stop(); },
+    get isRunning() { return v2.isRunning(); },
+    // Preserve direct access for tests.
+    _v2: v2,
+  };
+}

package/unify/engine.js

@@ -21,6 +21,7 @@ import { randomUUID } from 'crypto';
 import { buildSystemPrompt, buildWorkerPrompt } from './prompts.js';
 import { LLMContextError, LLMAbortError } from './llm/adapter.js';
 import { recallR6, formatForInjection } from './memory/recall-r6.js';
+import { recallV2 } from './memory/recall-v2.js';
 import { shouldConsolidate, consolidate, partitionMessages } from './memory/consolidate.js';
 import { extractMemories } from './memory/extract.js';
 import { runCompact as runCompactOrchestrator } from './compact/orchestrator.js';
@@ -489,15 +490,40 @@ export class Engine {
 
   /**
    * Perform memory recall for a given prompt.
-   * Uses recallR6 (R6 shard-based recall) when memoryShardStore is available,
-   * falling back to empty results if not.
+   *
+   * Routes:
+   *   - config.memoryV2 === true → recall-v2 (per-scope memory.md + summary.md)
+   *   - else → R6 shard-based recall (legacy)
    *
    * @param {string} prompt
+   * @param {{ groupId?: string, vpId?: string, featureId?: string }} [ctx]
    * @returns {Promise<{ profile: string, entries: object[], formatted: string }|null>}
    */
-  async #recallMemory(prompt) {
+  async #recallMemory(prompt, ctx = {}) {
     const memory = { profile: '', entries: [], formatted: '' };
 
+    // ─── v2 path (DESIGN-v2) ───────────────────────────────────
+    if (this.#config && this.#config.memoryV2 && this.#yeaftDir) {
+      try {
+        const result = await recallV2({
+          prompt,
+          root: `${this.#yeaftDir}/memory`,
+          groupId: ctx.groupId,
+          vpId: ctx.vpId,
+          featureId: ctx.featureId,
+        });
+        memory.entries = result.sections || [];
+        memory.formatted = result.formatted || '';
+        // Profile concept: in v2 the user/memory.md IS the profile.
+        const userSec = (result.sections || []).find(s => s.kind === 'user');
+        memory.profile = userSec ? (userSec.summary || '') : '';
+      } catch {
+        // Fail soft — empty injection.
+      }
+      return memory;
+    }
+
+    // ─── R6 legacy path ────────────────────────────────────────
     // Build user profile from user-memory shard store (R6 path),
     // falling back to legacy readProfile if shard store unavailable.
     try {
@@ -885,7 +911,15 @@ export class Engine {
     }
 
     // R6 recall: append shard-based recall results to memory injection
-    const recallResult = await this.#recallMemory(prompt);
+    const recallResult = await this.#recallMemory(prompt, {
+      groupId,
+      vpId: vpPersona && typeof vpPersona === 'object' && typeof vpPersona.vpId === 'string'
+        ? vpPersona.vpId
+        : (typeof senderVpId === 'string' ? senderVpId : undefined),
+      featureId: typeof inboundEnvelope === 'object' && inboundEnvelope
+        ? inboundEnvelope.featureId
+        : undefined,
+    });
     if (recallResult && recallResult.formatted) {
       memoryInjection = memoryInjection
         ? memoryInjection + '\n\n' + recallResult.formatted

package/unify/memory/recall-v2.js

@@ -0,0 +1,258 @@
+/**
+ * memory/recall-v2.js — DESIGN-v2 Part II: scope-based memory recall.
+ *
+ * Recall under v2 is structurally different from R6: instead of selecting
+ * individual entry shards by tag/keyword, we assemble per-scope `memory.md`
+ * + `summary.md` for the scopes that are *known* to be relevant from the
+ * current turn's context (always-include rules) plus the topic scopes whose
+ * summary best matches the user's prompt keywords.
+ *
+ * Always-include scopes (no LLM):
+ *   - user                              (every turn)
+ *   - group/<groupId>                   (when groupId is provided)
+ *   - vp/<vpId>                         (when vpId is provided AND not a foreign vp)
+ *   - feature/<featureId>               (when featureId is provided)
+ *
+ * Topic scopes:
+ *   - Score each topic by simple keyword overlap between the prompt's
+ *     extracted keywords (via recall.js → extractKeywords) and the topic's
+ *     `summary.md` body. Top-N by score join the bundle.
+ *   - This is a heuristic — no LLM call. Topics that the dream pipeline
+ *     created already correlate with the conversation's natural language,
+ *     so a cheap keyword overlap is a good first cut.
+ *
+ * What this module deliberately does NOT do:
+ *   - No LLM side-query. R6's recall.js does a 3rd-step LLM-select; v2
+ *     skips it because the unit of selection is now whole scopes (5 + N
+ *     topics) instead of dozens of individual entries.
+ *   - No frontmatter parsing. memory.md is markdown; the dream-state tail
+ *     marker is stripped before injection (so the LLM doesn't see internal
+ *     bookkeeping bytes).
+ *   - No write side effects. Pure read.
+ *
+ * Reference: agent/unify/memory/DESIGN-v2.md §6 (recall surface).
+ */
+
+import { join } from 'path';
+import { promises as fsp, existsSync } from 'fs';
+
+import {
+  DEFAULT_MEMORY_ROOT, scopeDir, readMemory, readSummary,
+} from './store-v2.js';
+import { extractKeywords } from './recall.js';
+
+/** Default cap for how many topic scopes recall pulls in. */
+export const DEFAULT_TOPIC_LIMIT = 3;
+
+/** Marker block written by dream-v2/state.js — stripped from injection. */
+const DREAM_MARKER_RE = /\n*<!-- dream-state -->[\s\S]*?<!-- \/dream-state -->\s*$/;
+
+/**
+ * Strip the trailing dream-state marker block (if any) from a memory.md body.
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+export function stripDreamMarker(body) {
+  if (!body || typeof body !== 'string') return '';
+  return body.replace(DREAM_MARKER_RE, '').trimEnd();
+}
+
+/**
+ * List all topic scopes present under <root>/topic/. Returns paths like
+ * ['science', 'physics'] (level 1) or ['life', 'parenting'] (level 2).
+ *
+ * @param {string} root
+ * @returns {Promise<string[][]>}
+ */
+async function listTopicPaths(root) {
+  const out = [];
+  const topicRoot = join(root, 'topic');
+  if (!existsSync(topicRoot)) return out;
+  let l1Names;
+  try { l1Names = await fsp.readdir(topicRoot, { withFileTypes: true }); }
+  catch { return out; }
+  for (const e1 of l1Names) {
+    if (!e1.isDirectory()) continue;
+    if (e1.name.startsWith('.')) continue;
+    // Level-1 topic is itself a scope (memory.md may sit at this level).
+    out.push([e1.name]);
+    // Walk one more level.
+    let l2Names;
+    try { l2Names = await fsp.readdir(join(topicRoot, e1.name), { withFileTypes: true }); }
+    catch { continue; }
+    for (const e2 of l2Names) {
+      if (!e2.isDirectory()) continue;
+      if (e2.name.startsWith('.')) continue;
+      out.push([e1.name, e2.name]);
+    }
+  }
+  return out;
+}
+
+/**
+ * Score a topic by how many of its summary's tokens overlap the prompt's
+ * keyword set. Topics with no summary score 0.
+ *
+ * @param {string} summary
+ * @param {Set<string>} keywordSet
+ * @returns {number}
+ */
+function scoreTopic(summary, keywordSet) {
+  if (!summary || keywordSet.size === 0) return 0;
+  const tokens = (summary.toLowerCase()
+    .match(/[\p{L}\p{N}_-]+/gu) || [])
+    .filter(t => t.length > 1);
+  if (tokens.length === 0) return 0;
+  let hits = 0;
+  for (const t of tokens) {
+    if (keywordSet.has(t)) hits += 1;
+  }
+  return hits;
+}
+
+/**
+ * @typedef {Object} RecallV2Section
+ * @property {string} scope         — human label, e.g. "user", "group/g-eng"
+ * @property {string} kind          — 'user' | 'vp' | 'group' | 'feature' | 'topic'
+ * @property {string} memory        — memory.md body (dream marker stripped)
+ * @property {string} summary       — summary.md body
+ */
+
+/**
+ * @typedef {Object} RecallV2Result
+ * @property {RecallV2Section[]} sections
+ * @property {string[]} keywords
+ * @property {string} formatted     — ready to splice into the system prompt
+ */
+
+/**
+ * Build a scope label suitable for the formatted block heading.
+ *
+ * @param {import('./store-v2.js').Scope} scope
+ * @returns {string}
+ */
+export function scopeLabel(scope) {
+  if (scope.kind === 'user') return 'user';
+  if (scope.kind === 'topic') return `topic/${(scope.path || []).join('/')}`;
+  return `${scope.kind}/${scope.id || ''}`;
+}
+
+/**
+ * Format the bundle for direct injection into the system prompt.
+ *
+ * @param {RecallV2Section[]} sections
+ * @returns {string}
+ */
+export function formatRecallV2(sections) {
+  if (!sections || sections.length === 0) return '';
+  const blocks = [];
+  for (const s of sections) {
+    const memBlock = s.memory ? s.memory.trim() : '';
+    const sumBlock = s.summary ? s.summary.trim() : '';
+    if (!memBlock && !sumBlock) continue;
+    const parts = [`### ${s.scope}`];
+    if (sumBlock) parts.push(`**Summary**\n${sumBlock}`);
+    if (memBlock) parts.push(`**Memory**\n${memBlock}`);
+    blocks.push(parts.join('\n\n'));
+  }
+  if (blocks.length === 0) return '';
+  return ['## Recalled Memory (v2)', ...blocks].join('\n\n');
+}
+
+/**
+ * Read one scope's pair (memory.md + summary.md) and translate to a section.
+ * Returns null when both files are empty/missing or VP ACL refuses.
+ *
+ * @param {import('./store-v2.js').Scope} scope
+ * @param {{ root: string, currentVpId?: string }} opts
+ * @returns {Promise<RecallV2Section|null>}
+ */
+async function readScopeSection(scope, opts) {
+  let memory = '';
+  let summary = '';
+  try { memory = stripDreamMarker(await readMemory(scope, opts)); }
+  catch { return null; } // VP ACL or other → skip silently
+  try { summary = await readSummary(scope, opts); } catch { /* */ }
+  if (!memory && !summary) return null;
+  return {
+    scope: scopeLabel(scope),
+    kind: scope.kind,
+    memory,
+    summary,
+  };
+}
+
+/**
+ * Recall v2: assemble per-scope memory.md + summary.md for the current turn.
+ *
+ * @param {Object} params
+ * @param {string} params.prompt                    — the user's turn prompt
+ * @param {string} [params.root]                    — memory root (defaults to DEFAULT_MEMORY_ROOT)
+ * @param {string} [params.groupId]                 — active group, if any
+ * @param {string} [params.vpId]                    — active VP for this turn (NOT used as ACL)
+ * @param {string} [params.currentVpId]             — current session's VP, gates vp/<other> reads
+ * @param {string} [params.featureId]               — active feature, if any
+ * @param {number} [params.topicLimit]              — cap on topic scopes (default DEFAULT_TOPIC_LIMIT)
+ * @returns {Promise<RecallV2Result>}
+ */
+export async function recallV2({
+  prompt,
+  root = DEFAULT_MEMORY_ROOT,
+  groupId,
+  vpId,
+  currentVpId,
+  featureId,
+  topicLimit = DEFAULT_TOPIC_LIMIT,
+} = {}) {
+  const sections = [];
+  const opts = { root, currentVpId };
+  const keywords = extractKeywords(prompt || '');
+
+  // Always: user.
+  const userSec = await readScopeSection({ kind: 'user' }, opts);
+  if (userSec) sections.push(userSec);
+
+  // Conditional: group/<groupId>
+  if (groupId && typeof groupId === 'string' && groupId !== '_no-group') {
+    const sec = await readScopeSection({ kind: 'group', id: groupId }, opts);
+    if (sec) sections.push(sec);
+  }
+
+  // Conditional: vp/<vpId>
+  if (vpId && typeof vpId === 'string') {
+    const sec = await readScopeSection({ kind: 'vp', id: vpId }, opts);
+    if (sec) sections.push(sec);
+  }
+
+  // Conditional: feature/<featureId>
+  if (featureId && typeof featureId === 'string') {
+    const sec = await readScopeSection({ kind: 'feature', id: featureId }, opts);
+    if (sec) sections.push(sec);
+  }
+
+  // Topics: rank by keyword overlap on summary.
+  if (topicLimit > 0 && keywords.length > 0) {
+    const keywordSet = new Set(keywords.map(k => k.toLowerCase()));
+    const candidates = [];
+    const paths = await listTopicPaths(root);
+    for (const path of paths) {
+      const scope = { kind: 'topic', path };
+      let summary = '';
+      try { summary = await readSummary(scope, opts); } catch { /* */ }
+      const score = scoreTopic(summary, keywordSet);
+      if (score > 0) candidates.push({ scope, score });
+    }
+    candidates.sort((a, b) => b.score - a.score);
+    for (const c of candidates.slice(0, topicLimit)) {
+      const sec = await readScopeSection(c.scope, opts);
+      if (sec) sections.push(sec);
+    }
+  }
+
+  return {
+    sections,
+    keywords,
+    formatted: formatRecallV2(sections),
+  };
+}

package/unify/session.js

@@ -35,6 +35,7 @@ import { createDispatcher } from './pipeline/dispatcher.js';
 import { ensureDefaultGroupIfEmpty } from './groups/group-crud.js';
 import { seedDefaultVps } from './vp/seed-defaults.js';
 import { createDreamScheduler } from './memory/dream-scheduler.js';
+import { createV2DreamScheduler } from './dream-v2/session-wiring.js';
 import { getUserMemoryStore } from './memory/user-memory-store.js';
 import { join } from 'path';
 import { existsSync as existsSyncSafe, readFileSync as readFileSyncSafe } from 'fs';
@@ -246,29 +247,47 @@ export async function loadSession(options = {}) {
     yeaftDir,
   });
 
-  // ─── 9a. Create dream scheduler (wave-6b) ─────────────
-  const dreamScheduler = createDreamScheduler({
-    memoryShardStore,
-    userMemoryStore: getUserMemoryStore(),
-    conversationStore,
-    adapter,
-    config,
-    onDreamStart: (vpId) => {
-      if (config.debug) console.log(`[Yeaft] Dream started for VP ${vpId}`);
-    },
-    onDreamEnd: (vpId, result) => {
-      if (config.debug) console.log(`[Yeaft] Dream ended for VP ${vpId}:`, JSON.stringify({
-        trigger: result.trigger,
-        entriesMerged: result.entriesMerged,
-        entriesPruned: result.entriesPruned,
-        bytesReclaimed: result.bytesReclaimed,
-        errors: result.errors?.length || 0,
-      }));
-    },
-    onError: (vpId, err) => {
-      console.warn(`[Yeaft] Dream error for VP ${vpId}:`, err?.message || err);
-    },
-  });
+  // ─── 9a. Create dream scheduler (wave-6b / DESIGN-v2) ──
+  // When config.memoryV2 is on, route through the v2 pipeline (per-scope
+  // memory.md + summary.md). Otherwise keep the legacy R6 dream-scheduler.
+  let dreamScheduler;
+  if (config.memoryV2) {
+    // Build a partial session reference so the v2 wiring can see adapter,
+    // config, yeaftDir, engine, and trace. The scheduler's `run` closure
+    // dereferences these lazily, so mutating the object after this line
+    // (e.g. attaching engine) is safe.
+    const partialSession = {
+      yeaftDir,
+      adapter,
+      config,
+      engine,
+      trace,
+    };
+    dreamScheduler = createV2DreamScheduler(partialSession);
+  } else {
+    dreamScheduler = createDreamScheduler({
+      memoryShardStore,
+      userMemoryStore: getUserMemoryStore(),
+      conversationStore,
+      adapter,
+      config,
+      onDreamStart: (vpId) => {
+        if (config.debug) console.log(`[Yeaft] Dream started for VP ${vpId}`);
+      },
+      onDreamEnd: (vpId, result) => {
+        if (config.debug) console.log(`[Yeaft] Dream ended for VP ${vpId}:`, JSON.stringify({
+          trigger: result.trigger,
+          entriesMerged: result.entriesMerged,
+          entriesPruned: result.entriesPruned,
+          bytesReclaimed: result.bytesReclaimed,
+          errors: result.errors?.length || 0,
+        }));
+      },
+      onError: (vpId, err) => {
+        console.warn(`[Yeaft] Dream error for VP ${vpId}:`, err?.message || err);
+      },
+    });
+  }
 
   // task-308 Phase 2: thread-aware engine registry.
   // Each thread gets its own EngineInstance (lazy-created) that owns its

package/unify/web-bridge.js

@@ -532,6 +532,17 @@ export function installUnifyRuntimeBridge(s) {
   if (!s) return;
   const initialMax = s.engineRegistry?.maxConcurrent ?? null;
   const initialIdle = s.threadStore?.idleArchiveDays ?? 0;
+
+  // DESIGN-v2 §19.4: forward dream pipeline progress events to the web
+  // client so the debug panel can render live state. Events flow through
+  // the same `unify_output` channel; no new WebSocket message type is
+  // introduced.
+  s._dreamProgressSink = (evt) => {
+    try {
+      sendUnifyEvent({ type: 'dream_progress', ...evt });
+    } catch { /* never let event delivery throw */ }
+  };
+
   ctx.unifyRuntimeSettings = {
     get maxConcurrentThreads() { return s.engineRegistry?.maxConcurrent ?? initialMax; },
     set maxConcurrentThreads(v) {