@yeaft/webchat-agent 0.1.753 → 0.1.755

package/package.json

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

package/unify/conversation/persist.js

@@ -102,6 +102,11 @@ function serializeMessage(msg) {
   // in the default group and switching back to the originating group
   // shows an empty pane.
   if (msg.groupId) fm.push(`groupId: ${msg.groupId}`);
+  // Group-chat attribution: when a VP authors an assistant turn (either
+  // its own reply or a route_forward injection from another VP), stamp
+  // the speaker so the UI can render the message on the correct VP track.
+  // For real user messages this is unset.
+  if (msg.speakerVpId) fm.push(`speakerVpId: ${msg.speakerVpId}`);
 
   // Token estimate
   const content = msg.content || '';
@@ -173,6 +178,7 @@ export function parseMessage(raw) {
       case 'threadId': msg.threadId = value; break;
       case 'sourceThreadId': msg.sourceThreadId = value; break;
       case 'groupId': msg.groupId = value; break;
+      case 'speakerVpId': msg.speakerVpId = value; break;
       // toolCalls are multi-line YAML — handled separately below
     }
   }

package/unify/dream-v2/runner.js

@@ -44,7 +44,7 @@ import { listScopes, readSummary } from '../memory/store-v2.js';
 import {
   DEFAULT_LIMITS,
 } from './limits.js';
-import { readGroupState, writeGroupState } from './state.js';
+import { readGroupState, writeGroupState, writeDreamError } from './state.js';
 import { segmentDiff, truncateMessage, estimateMessagesTokens } from './segment.js';
 import { triageGroupSegments } from './triage.js';
 import { mergeByTarget } from './merge.js';
@@ -148,6 +148,14 @@ export async function runDream(opts) {
     } catch (err) {
       groupsReport.push({ groupId, new: newCount, status: 'error', error: err.message });
       onProgress({ phase: 'triage', groupId, status: 'error', error: err.message });
+      // Journal the failure on disk so operators can see WHY dream is
+      // not advancing without having to enable `config.debug`. Best-
+      // effort — `writeDreamError` swallows its own I/O errors.
+      await writeDreamError(opts.root, `group/${groupId}`, {
+        phase: 'triage',
+        message: err.message,
+        stack: err.stack,
+      });
       continue;
     }
 
@@ -191,6 +199,14 @@ export async function runDream(opts) {
         error: err.message,
       });
       onProgress({ phase: 'apply', target: merged.target, status: 'error', error: err.message });
+      // Journal apply-stage failures into the target scope's directory
+      // (`<root>/<merged.target>/.dream-last-error.json`). Same rationale
+      // as the triage catch above.
+      await writeDreamError(opts.root, merged.target, {
+        phase: 'apply',
+        message: err.message,
+        stack: err.stack,
+      });
     }
   }
 

package/unify/dream-v2/state.js

@@ -1,7 +1,7 @@
 /**
  * dream-v2/state.js.
  *
- * Two pieces of state, tracked separately:
+ * Three pieces of state, tracked separately:
  *
  *   1. Per-group control state (used to decide whether a group enters
  *      triage and how far to advance the cursor):
@@ -31,13 +31,25 @@
  *      control-flow decision. We update it by replacing the existing
  *      block (if any) or appending a new one to the end of the file.
  *
- * Both helpers are pure I/O; no LLM, no logic beyond parsing.
+ *   3. Per-scope dream-error sink (added v0.1.754):
+ *
+ *        ~/.yeaft/memory/<scope>/.dream-last-error.json
+ *
+ *      Most-recent-wins JSON written unconditionally on every triage
+ *      or apply failure (best-effort — never throws even when the I/O
+ *      itself fails). The runner used to swallow these exceptions and
+ *      the only sink was a `config.debug`-gated console.log; this file
+ *      gives operators on-disk evidence regardless of debug. See
+ *      `writeDreamError` / `readDreamError` below for the contract.
+ *
+ * All helpers are pure I/O; no LLM, no logic beyond parsing.
  */
 
 import { promises as fsp, existsSync } from 'fs';
 import { join, dirname } from 'path';
 
 const STATE_FILE = '.dream-state';
+const ERROR_FILE = '.dream-last-error.json';
 const DREAM_BLOCK_OPEN = '<!-- dream-state -->';
 const DREAM_BLOCK_CLOSE = '<!-- /dream-state -->';
 
@@ -101,6 +113,95 @@ function parseGroupState(raw) {
   return out;
 }
 
+// ─── per-scope dream error sink ────────────────────────────────
+//
+// Why: dream-v2 silently swallowed exceptions at the triage / apply
+// catch sites — the only sink was `trace.event('dream_progress', evt)`
+// and a `config.debug`-gated `console.log` in `session-wiring.js`. With
+// `debug=false` (the default), there was no on-disk evidence that a
+// dream pass had ever failed: no `.dream-state` (because we only write
+// it on success), no log file, nothing. The Resident layer's continued
+// regurgitation of the bootstrap seed was the only symptom.
+//
+// `writeDreamError` writes `<memoryRoot>/<scope>/.dream-last-error.json`
+// unconditionally on every catch (best-effort — write failures must not
+// shadow the original error). Operators can then `ls ~/.yeaft/memory/
+// group/<id>/` and see what blew up, without having to re-enable debug.
+
+/**
+ * Resolve a memoryRoot + scope-string to the scope directory.
+ * The scope string is the same shape dream-v2 already uses internally:
+ * `'user'`, `'vp/<vpId>'`, `'group/<groupId>'`, `'feature/<id>'`, etc.
+ *
+ * Pure path-join; does NOT create the directory. The writer creates it.
+ *
+ * @param {string} root
+ * @param {string} scope
+ * @returns {string}
+ */
+export function scopeDirFor(root, scope) {
+  // Defensive: trim leading/trailing slashes so callers can pass either
+  // `'group/grp_fun'` or `/group/grp_fun/` — both land on the same dir.
+  const clean = String(scope || '').replace(/^\/+|\/+$/g, '');
+  return join(root, clean);
+}
+
+/**
+ * Best-effort write of the dream-error sink. Never throws — a failed
+ * write is silently swallowed because the caller is already in an
+ * error-handling path and we must not mask the original failure.
+ *
+ * @param {string} root         — memory root, e.g. ~/.yeaft/memory
+ * @param {string} scope        — `'group/<id>'` for triage failures,
+ *                                `merged.target` for apply failures.
+ * @param {{ phase: string, message: string, stack?: string|null, at?: string }} info
+ * @returns {Promise<void>}
+ */
+export async function writeDreamError(root, scope, info) {
+  try {
+    const dir = scopeDirFor(root, scope);
+    await fsp.mkdir(dir, { recursive: true });
+    const abs = join(dir, ERROR_FILE);
+    const at = (info && info.at) || new Date().toISOString();
+    // Trim stack to the first 5 frames — enough for diagnosis, small
+    // enough that the artifact stays human-readable. Missing/empty
+    // stack collapses to `null` rather than `""` so the artifact is
+    // cleaner for operators.
+    const rawStack = info && typeof info.stack === 'string' ? info.stack : '';
+    const stackLines = rawStack ? rawStack.split('\n').slice(0, 5) : [];
+    const body = JSON.stringify({
+      at,
+      scope,
+      phase: String(info?.phase || 'unknown'),
+      message: String(info?.message || ''),
+      stack: stackLines.length > 0 ? stackLines.join('\n') : null,
+    }, null, 2) + '\n';
+    await atomicWrite(abs, body);
+  } catch {
+    // Best-effort: swallow. The caller is already handling the real
+    // error; an inability to journal it must not shadow that.
+  }
+}
+
+/**
+ * Read the last dream error JSON for a scope, or null if absent. Used
+ * by the debug panel and by tests. Tolerates a malformed file by
+ * returning `{ raw: <body>, parseError: <message> }` instead of
+ * throwing.
+ *
+ * @param {string} root
+ * @param {string} scope
+ * @returns {Promise<object|null>}
+ */
+export async function readDreamError(root, scope) {
+  const abs = join(scopeDirFor(root, scope), ERROR_FILE);
+  let raw;
+  try { raw = await fsp.readFile(abs, 'utf8'); }
+  catch (err) { if (err && err.code === 'ENOENT') return null; throw err; }
+  try { return JSON.parse(raw); }
+  catch (e) { return { raw, parseError: e.message }; }
+}
+
 // ─── per-scope marker (memory.md tail block) ───────────────────
 
 /**

package/unify/groups/coordinator.js

@@ -64,7 +64,20 @@ export function createCoordinator(group, options = {}) {
     const meta = group.getMeta();
     if (!meta) throw new Error('group not initialised (call createGroup first)');
 
-    const fromUser = input.from === 'user' || input.role === 'user';
+    // `fromUser` drives `selectRespondingVps` — when true, the @-mention
+    // matrix runs (mention/broadcast/fallback). When false, VPs cannot
+    // text-@-route (VP-authored free text is surface noise per arch §6).
+    //
+    // route_forward injection is a special case: the message is VP-authored
+    // (role='assistant') but it MUST trigger dispatch (target VP needs to
+    // run). We detect it via `meta.injectedBy === 'route_forward'` and
+    // treat it as "user-like" for dispatch purposes only. Persistence still
+    // honours the caller's `role` field so the on-disk record correctly
+    // attributes the turn to the sending VP, not to the user.
+    const isRouteForwardInjection = input?.meta?.injectedBy === 'route_forward';
+    const fromUser = input.from === 'user'
+      || input.role === 'user'
+      || isRouteForwardInjection;
     const mentions = parseMentions(input.text);
 
     // Persist first — audit log / replay works even if dispatch has bugs.

package/unify/routing/router.js

@@ -125,17 +125,12 @@ export function createRouter(deps = {}) {
     }
 
     // Synthesize an injection message — coordinator's `ingest` expects the
-    // {from, role, text} shape. We set role='user' ONLY because that's the
-    // code path that triggers @-routing; semantically it is a VP-initiated
-    // injection. The `from` field preserves the real sender vpId, and we
-    // stamp meta.synthetic + meta.injectedBy so downstream auditors can
-    // tell it apart from real user input.
-    //
-    // Why not add a third role to Coordinator? Scope discipline: Coordinator
-    // (334b) owns user vs VP branching. A third branch would force edits
-    // across both 334b and 334d for one hop. Setting role='user' with
-    // synthetic meta keeps the Coordinator API frozen — and `from` still
-    // reflects the real author, which is what the guard keys on anyway.
+    // {from, role, text} shape. The forwarded message is semantically the
+    // SENDER VP speaking (just delivered to a different VP's inbox), so it
+    // persists as role='assistant' attributed to `from`. The `meta.injectedBy`
+    // stamp + `synthetic` marker let Coordinator's `selectRespondingVps`
+    // still treat this like a routed turn (target VPs need to respond) even
+    // though role is now 'assistant'.
     const injectText = to === 'all'
       ? `@all ${text}`
       : `@${to} ${text}`;
@@ -143,7 +138,7 @@ export function createRouter(deps = {}) {
     const report = coordinator.ingest(
       {
         from,                  // real VP id — preserved for provenance
-        role: 'user',          // triggers coordinator dispatch path
+        role: 'assistant',     // VP-authored — persists as assistant turn
         text: injectText,
         taskId: args.taskId ?? null,
         meta: {

package/unify/web-bridge.js

@@ -617,10 +617,22 @@ function ensureDriverRunning(groupId, vpId) {
       try {
         const envMsgId = envelope?.msg?.id;
         if (envMsgId && text) {
-          persistUserMessageOnceByMsgId({
+          // route_forward injection: the envelope text was authored by the
+          // sending VP, not the user. Persist as an assistant row attributed
+          // to the sender so history replay puts it on the VP track, not on
+          // the human "user" track. Non-forward envelopes (real user input)
+          // persist as the user row exactly like before.
+          const meta = envelope?.msg?.meta || {};
+          const isForward = meta.injectedBy === 'route_forward';
+          const senderVpId = isForward
+            ? (meta.senderVpId || envelope?.msg?.from || null)
+            : null;
+          persistInboundMessageOnceByMsgId({
             msgId: envMsgId,
             text,
             groupId,
+            role: isForward ? 'assistant' : 'user',
+            speakerVpId: senderVpId,
           });
         }
       } catch { /* never crash WS pipeline */ }
@@ -1685,7 +1697,7 @@ export async function handleUnifyGroupChat(msg) {
   try {
     const persistedMsgId = report?.message?.id;
     if (persistedMsgId) {
-      persistUserMessageOnceByMsgId({
+      persistInboundMessageOnceByMsgId({
         msgId: persistedMsgId,
         text,
         groupId,
@@ -1693,7 +1705,7 @@ export async function handleUnifyGroupChat(msg) {
     }
   } catch (err) {
     console.warn(
-      '[Unify] unify_group_chat: persistUserMessageOnceByMsgId failed',
+      '[Unify] unify_group_chat: persistInboundMessageOnceByMsgId failed',
       err?.message || err,
     );
   }
@@ -2210,11 +2222,13 @@ function appendTurnToGroupHistory(groupId, prompt, assistantTextParts, toolCalls
 }
 
 /**
- * Persist the user row to disk EXACTLY ONCE per coordinator-ingest call,
- * keyed by the coordinator-assigned `msgId`. Both `handleUnifyGroupChat`
- * (real user input) and `enqueueForVp`'s driver loop (route_forward
- * synthetic injections) call this — the Set guard makes either path
- * the writer, whichever runs first, while the other becomes a no-op.
+ * Persist an inbound message row to disk EXACTLY ONCE per
+ * coordinator-ingest call, keyed by the coordinator-assigned `msgId`.
+ * Both `handleUnifyGroupChat` (real user input, persists as
+ * role='user') and `enqueueForVp`'s driver loop (route_forward
+ * synthetic injections, persists as role='assistant' attributed via
+ * `speakerVpId`) call this — the Set guard makes either path the
+ * writer, whichever runs first, while the other becomes a no-op.
  *
  * Without this dedup, a 2-VP group prompt produces TWO `m{NNNN}.md`
  * user rows (one per engine) — `handleUnifyLoadHistory` then replays
@@ -2232,11 +2246,11 @@ function appendTurnToGroupHistory(groupId, prompt, assistantTextParts, toolCalls
  * schema today (the engine never wrote them either) — they live on the
  * coordinator's jsonl-log under group meta.
  *
- * @param {{ msgId:string, text:string, groupId:string }} args
+ * @param {{ msgId:string, text:string, groupId:string, role?:string, speakerVpId?:string|null }} args
  * @returns {boolean} true if this call wrote the row, false if a prior
  *   call already wrote it (dedup hit).
  */
-function persistUserMessageOnceByMsgId({ msgId, text, groupId }) {
+function persistInboundMessageOnceByMsgId({ msgId, text, groupId, role, speakerVpId }) {
   if (!session?.conversationStore) return false;
   // No msgId means no dedup key — caller is responsible for guarding.
   // Both call sites already do (`if (envMsgId && text)` and
@@ -2267,17 +2281,30 @@ function persistUserMessageOnceByMsgId({ msgId, text, groupId }) {
     }
   }
   try {
+    // role defaults to 'user' for back-compat: handleUnifyGroupChat's
+    // real-user call site passes no role and gets a user row. The driver
+    // loop passes role='assistant' + speakerVpId for route_forward
+    // injections so the on-disk record correctly attributes the text to
+    // the sending VP.
+    const persistRole = role === 'assistant' ? 'assistant' : 'user';
     const record = {
-      role: 'user',
+      role: persistRole,
       content: text,
       threadId: 'main',
     };
     if (groupId) record.groupId = groupId;
+    // Stamp speakerVpId so the UI's loadHistory replay can route the row
+    // to the correct VP block. Only meaningful when role='assistant'; for
+    // a real user message we leave it unset (the UI's user track is
+    // unattributed).
+    if (persistRole === 'assistant' && speakerVpId && typeof speakerVpId === 'string') {
+      record.speakerVpId = speakerVpId;
+    }
     session.conversationStore.append(record);
     return true;
   } catch (err) {
     console.warn(
-      '[Unify] persistUserMessageOnceByMsgId failed (non-fatal):',
+      '[Unify] persistInboundMessageOnceByMsgId failed (non-fatal):',
       err?.message || err,
     );
     return false;
@@ -2418,28 +2445,55 @@ export function __testGetRegisteredThreadIds() {
 export const __testRaceWithEscalation = raceWithEscalation;
 
 /**
- * Manual dream trigger from VP detail page.
+ * Manual dream trigger.
+ *
+ * Two call shapes, both routed through this single handler:
+ *
+ *   { type: 'unify_dream_trigger', vpId }     — per-VP trigger (legacy
+ *     VP-detail page button). Fires an unscoped dream pass; the result
+ *     event is tagged with `vpId` so the per-VP store row updates.
+ *
+ *   { type: 'unify_dream_trigger', groupId }  — per-GROUP trigger (new
+ *     in v0.1.754 — added so users can manually kick dream for a group
+ *     after seeing the Resident layer stuck on the bootstrap seed).
+ *     Fires a scope-filtered pass via `triggerDreamForScopes(['group/X'])`
+ *     so unrelated groups don't get processed; the result event is
+ *     tagged with `groupId` for the per-group UI row.
+ *
+ * Backwards-compat: when neither field is set, defaults to `vpId='default'`
+ * which matches the pre-v0.1.754 behavior.
  */
 export async function handleUnifyDreamTrigger(msg = {}) {
+  // Resolve tag up-front so EVERY outbound envelope (including the
+  // scheduler-uninitialised early-return below) carries `groupId` /
+  // `vpId`. Without this the frontend's `applyDreamResult` couldn't
+  // route the error event back to the right row and the per-group
+  // "Run dream now" button would stay stuck on "Running…" forever
+  // (review feedback from PR #757).
+  const groupId = typeof msg.groupId === 'string' && msg.groupId ? msg.groupId : null;
+  const vpId = !groupId ? (msg.vpId || 'default') : null;
+  const tag = groupId ? { groupId } : { vpId };
+
   if (!session?.dreamScheduler) {
     sendToServer({
       type: 'unify_dream_result',
+      ...tag,
       success: false,
       error: 'Dream scheduler not initialized — session not loaded.',
     });
     return;
   }
 
-  const vpId = msg.vpId || 'default';
-
   try {
     sendToServer({
       type: 'unify_dream_status',
-      vpId,
+      ...tag,
       status: 'running',
     });
 
-    const result = await session.dreamScheduler.triggerDreamNow();
+    const result = groupId
+      ? await session.dreamScheduler.triggerDreamForScopes([`group/${groupId}`])
+      : await session.dreamScheduler.triggerDreamNow();
 
     // fix/dream-cadence-and-ui-trigger: derive a single "entries
     // created" count for the UI bubble. The runner returns a richer
@@ -2457,7 +2511,7 @@ export async function handleUnifyDreamTrigger(msg = {}) {
     // PR #743.
     sendToServer({
       type: 'unify_dream_result',
-      vpId,
+      ...tag,
       ...result,
       success: !result.error && !result.skipped,
       entriesCreated,
@@ -2466,7 +2520,7 @@ export async function handleUnifyDreamTrigger(msg = {}) {
   } catch (err) {
     sendToServer({
       type: 'unify_dream_result',
-      vpId,
+      ...tag,
       success: false,
       error: err?.message || String(err),
     });
@@ -2704,11 +2758,19 @@ export async function handleUnifyLoadHistory(msg) {
     if (m.role === 'user') {
       sendUnifyOutput({ type: 'user', message: { content: m.content } }, { groupId: m.groupId || null });
     } else if (m.role === 'assistant') {
+      // speakerVpId rides on the envelope so the frontend can route this
+      // replayed assistant text to the correct VP track. Without it, the
+      // history replay would merge replies from different VPs onto one
+      // anonymous assistant turn.
+      const envelopeOpts = {
+        groupId: m.groupId || null,
+      };
+      if (m.speakerVpId) envelopeOpts.vpId = m.speakerVpId;
       sendUnifyOutput({
         type: 'assistant',
         message: { content: [{ type: 'text', text: m.content }] },
-      }, { groupId: m.groupId || null });
-      sendUnifyOutput({ type: 'result', result_text: '' }, { groupId: m.groupId || null });
+      }, envelopeOpts);
+      sendUnifyOutput({ type: 'result', result_text: '' }, envelopeOpts);
     }
   }