@yeaft/webchat-agent 0.1.723 → 0.1.726

package/package.json

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

package/unify/engine.js

@@ -28,6 +28,7 @@ import { archiveTurn } from './archive/turn-archive.js';
 import { archiveToolResults } from './archive/tool-results.js';
 import { readSummary as readScopeSummary } from './memory/store-v2.js';
 import { runAdjust } from './memory/adjust.js';
+import { isVpSeedBackfillStub } from './memory/seed-backfill.js';
 import { runStopHooks } from './stop-hooks.js';
 // H2.f.5: threads/ retired. Persisted messages still carry a `threadId`
 // field for back-compat with old conversation files; new writes always use
@@ -176,6 +177,45 @@ export function estimateMessagesTokens(system, messages) {
 
 // ─── Engine ──────────────────────────────────────────────────────
 
+/**
+ * buildResidentEntries — pure helper that builds the AMS Resident entry
+ * list from the per-turn Layer-A summaries.
+ *
+ * Encodes one non-trivial rule on top of "push if non-empty":
+ *
+ *   The `vp/<ownVpId>` summary is skipped when it carries the
+ *   seed-backfill stub marker. The persona body is already rendered as
+ *   Section 1 of the system prompt by `renderVpPersona`; surfacing the
+ *   stub's `# Name / Role` line as a Resident entry would re-label the
+ *   same identity in Section 6 ("Active Memory Set") with no added
+ *   information — the visible follow-up to the persona-dup bug fixed in
+ *   PR #722. Once Dream-v2 writes a real summary for this scope it
+ *   lacks the marker and is surfaced normally.
+ *
+ * Other-VP entries (group collaborators) are NOT considered here — only
+ * the local VP's summary is loaded into `summaries.vp` upstream by
+ * `#loadLayerASummaries`. Cross-VP context flows through onDemand recall.
+ *
+ * @param {{
+ *   groupId?: string|null,
+ *   ownVpId?: string|null,
+ *   summaries: { user?: string, group?: string, vp?: string }
+ * }} args
+ * @returns {Array<{scope: string, summary: string}>}
+ */
+export function buildResidentEntries(args) {
+  const summaries = (args && args.summaries) || {};
+  const out = [];
+  if (summaries.user) out.push({ scope: 'user', summary: summaries.user });
+  if (args.groupId && summaries.group) {
+    out.push({ scope: `group/${args.groupId}`, summary: summaries.group });
+  }
+  if (args.ownVpId && summaries.vp && !isVpSeedBackfillStub(summaries.vp)) {
+    out.push({ scope: `vp/${args.ownVpId}`, summary: summaries.vp });
+  }
+  return out;
+}
+
 export class Engine {
   /** @type {import('./llm/adapter.js').LLMAdapter} */
   #adapter;
@@ -505,14 +545,11 @@ export class Engine {
 
     // (a) Resident: rebuild from the same scope summaries the worker
     // prompt is already going to see.
-    const residentEntries = [];
-    if (args.summaries?.user)  residentEntries.push({ scope: 'user', summary: args.summaries.user });
-    if (args.groupId && args.summaries?.group) {
-      residentEntries.push({ scope: `group/${args.groupId}`, summary: args.summaries.group });
-    }
-    if (ownVpId && args.summaries?.vp) {
-      residentEntries.push({ scope: `vp/${ownVpId}`, summary: args.summaries.vp });
-    }
+    const residentEntries = buildResidentEntries({
+      groupId: args.groupId,
+      ownVpId,
+      summaries: args.summaries || {},
+    });
     ams.setResident(residentEntries);
 
     // (b) onDemand: replace with this turn's FTS hits.
@@ -836,11 +873,19 @@ export class Engine {
    * Persist user message and assistant response to conversation store.
    * Skipped in read-only mode (config._readOnly).
    *
+   * Multi-VP fan-out (Bug 1): when several engines run the same user
+   * prompt in parallel, we must NOT each write our own copy of the user
+   * message — `coord.ingest`/the orchestrator already wrote it once. Pass
+   * `userAlreadyPersisted: true` from the caller to skip the user-row
+   * append while still persisting the assistant + tool rows.
+   *
    * @param {string} userContent
    * @param {string} assistantContent
    * @param {object[]} [toolCalls]
+   * @param {string} [groupId]
+   * @param {boolean} [userAlreadyPersisted]
    */
-  #persistMessages(userContent, assistantContent, toolCalls, groupId) {
+  #persistMessages(userContent, assistantContent, toolCalls, groupId, userAlreadyPersisted = false) {
     if (!this.#conversationStore) return;
     if (this.#config._readOnly) return;
 
@@ -848,14 +893,17 @@ export class Engine {
     // for back-compat with old conversation files; new writes always use 'main'.
     const threadId = MAIN_THREAD_ID;
 
-    // Persist user message
-    this.#conversationStore.append({
-      role: 'user',
-      content: userContent,
-      threadId,
-      // Bug 6: stamp groupId so history replay can route by group.
-      ...(groupId ? { groupId } : {}),
-    });
+    // Persist user message — unless an upstream caller (e.g. the group
+    // coordinator) has already done so for this turn.
+    if (!userAlreadyPersisted) {
+      this.#conversationStore.append({
+        role: 'user',
+        content: userContent,
+        threadId,
+        // Bug 6: stamp groupId so history replay can route by group.
+        ...(groupId ? { groupId } : {}),
+      });
+    }
 
     // Persist assistant message
     const assistantMsg = {
@@ -1003,7 +1051,7 @@ export class Engine {
    *   string-prompt shape (no regression for existing callers).
    * @yields {EngineEvent}
    */
-  async *query({ prompt, promptParts = null, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement } = {}) {
+  async *query({ prompt, promptParts = null, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement, userAlreadyPersisted = false } = {}) {
     if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
       yield {
         type: 'error',
@@ -1062,7 +1110,7 @@ export class Engine {
     const runSignal = abortCtrl.signal;
 
     try {
-      yield* this.#runQuery({ prompt: effectivePrompt, promptParts, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement });
+      yield* this.#runQuery({ prompt: effectivePrompt, promptParts, messages, signal: runSignal, userEffort: effectiveUserEffort, scenario, vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement, userAlreadyPersisted });
     } finally {
       if (signal) {
         try { signal.removeEventListener('abort', onExternalAbort); } catch { /* ignore */ }
@@ -1080,7 +1128,7 @@ export class Engine {
    * in a try/finally without indenting the whole loop.
    * @private
    */
-  async *#runQuery({ prompt, promptParts = null, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement }) {
+  async *#runQuery({ prompt, promptParts = null, messages, signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, groupId, vpPlan, groupAnnouncement, userAlreadyPersisted = false }) {
 
     // ─── Pre-query: FTS5 Memory Recall + AMS snapshot ─────
     // Memory has a SINGLE render outlet now (DESIGN-PROMPT §3 ③):
@@ -1691,6 +1739,11 @@ export class Engine {
             // Bug 6: tag persisted messages with the originating group so
             // history replay can re-stamp them on reload.
             groupId,
+            // Multi-VP fan-out (history-dedup): skip the user-row append
+            // in stop-hooks when the orchestrator already wrote it once
+            // for this turn. The hook still persists assistant + tool
+            // rows for THIS VP's contribution.
+            userAlreadyPersisted,
           });
 
           if (hookResult.consolidated) {
@@ -1698,7 +1751,7 @@ export class Engine {
           }
         } else {
           // Legacy path (no yeaftDir → use old behavior)
-          this.#persistMessages(prompt, fullResponseText, assistantMsg.toolCalls, groupId);
+          this.#persistMessages(prompt, fullResponseText, assistantMsg.toolCalls, groupId, userAlreadyPersisted);
 
           const consolidated = await this.#maybeConsolidate();
           if (consolidated && consolidated.archivedCount > 0) {

package/unify/memory/seed-backfill.js

@@ -22,6 +22,42 @@ import { parseRoleMd } from '../vp/vp-store.js';
 
 const DEFAULT_MEMORY_ROOT = join(homedir(), '.yeaft', 'memory');
 
+/**
+ * Marker stamped into every VP summary written by this module.
+ *
+ * Two consumers care about it:
+ *   1. `engine.#prepareAms` uses `isVpSeedBackfillStub` to skip the
+ *      `vp/<ownVpId>` Resident entry when its summary is just our stub —
+ *      the real persona is already rendered as Section 1 of the system
+ *      prompt by `renderVpPersona`. Without the skip, AMS Resident dups
+ *      Section 1 with redundant `name + role` labels.
+ *   2. `migrateLegacyVpSummaries` uses absence-of-marker + presence of
+ *      `**Persona:**` to identify pre-fix summary.md files (which copied
+ *      up to 800 chars of `role.md` body) and rewrite them as stubs.
+ *
+ * Bump the version suffix when the stub format changes meaningfully so
+ * old stamps can be re-migrated if needed.
+ */
+export const VP_STUB_MARKER = '<!-- seed-backfill:vp-stub v1 -->';
+
+/**
+ * True iff the given summary text was produced by this module's VP stub
+ * writer (i.e. carries the marker comment). Whitespace-tolerant.
+ *
+ * Used by `engine.#prepareAms` to decide whether to surface the
+ * `vp/<ownVpId>` summary as a Resident AMS entry. Stubs are skipped so
+ * Section 1 (`renderVpPersona`) is the sole rendering of own-VP identity;
+ * Dream-v2's eventual real summary will lack the marker and be surfaced
+ * normally.
+ *
+ * @param {string|null|undefined} text
+ * @returns {boolean}
+ */
+export function isVpSeedBackfillStub(text) {
+  if (typeof text !== 'string' || text.length === 0) return false;
+  return text.includes(VP_STUB_MARKER);
+}
+
 function readIfPresent(path) {
   try {
     if (!existsSync(path)) return '';
@@ -39,10 +75,25 @@ function writeAtomicSync(path, body) {
 /**
  * Build a synthetic VP summary from the on-disk role.md.
  *
+ * IMPORTANT — this is a STUB that lives until Dream-v2 writes a real
+ * per-scope summary. Earlier versions copied up to 800 chars of the
+ * `role.md` body into `summary.md`. That body is *also* rendered as
+ * Section 1 of the system prompt (`renderVpPersona` in `prompts.js`),
+ * so the same persona text reappeared in `## Active Memory Set →
+ * Resident → vp/<id>` — the user-visible "Why is the persona defined
+ * twice?" bug.
+ *
+ * The summary.md placeholder is therefore deliberately minimal: just
+ * the VP's display name + role label. Layer-A AMS still sees a
+ * non-empty `vp/<id>` resident entry (so adjust/recall scope wiring
+ * stays unchanged), but the persona body is rendered exactly once,
+ * by Section 1.
+ *
+ * Once Dream-v2 produces a real summary for this scope it overwrites
+ * this stub — see `idempotency` note at the top of the file.
+ *
  * Delegates frontmatter parsing to `vp-store.js#parseRoleMd` so the
- * backfill stays in sync with the production loader. The earlier hand-
- * rolled regex parser silently dropped quoted multi-line scalars and
- * list-shaped fields — `parseRoleMd` covers both.
+ * backfill stays in sync with the production loader.
  *
  * @param {string} libDir
  * @param {string} vpId
@@ -54,17 +105,12 @@ function readVpRoleSummary(libDir, vpId) {
   let raw = '';
   try { raw = readFileSync(rolePath, 'utf-8'); } catch { return null; }
 
-  const { meta, body } = parseRoleMd(raw);
+  const { meta } = parseRoleMd(raw);
   const name = String(meta.name || vpId).trim() || vpId;
   const role = typeof meta.role === 'string' ? meta.role.trim() : '';
 
-  const persona = typeof body === 'string' ? body.trim() : '';
-  const lines = [`# ${name}`];
+  const lines = [VP_STUB_MARKER, '', `# ${name}`];
   if (role) lines.push('', `**Role:** ${role}`);
-  if (persona) {
-    const truncated = persona.length > 800 ? persona.slice(0, 800).trim() + '…' : persona;
-    lines.push('', '**Persona:**', '', truncated);
-  }
   return lines.join('\n').trim();
 }
 
@@ -123,6 +169,64 @@ function readGroupSummaryBody(groupDir) {
   return lines.join('\n').trim();
 }
 
+/**
+ * Detect the *legacy* (pre-stamp) VP summary shape: a body that lacks
+ * `VP_STUB_MARKER` AND contains the `**Persona:**` block written by the
+ * older stub. Tight signature on purpose — we don't want to clobber
+ * hand-edited or Dream-v2-produced summaries that happen to be missing
+ * the marker for unrelated reasons.
+ *
+ * @param {string} body
+ * @returns {boolean}
+ */
+function isLegacyVpSummary(body) {
+  if (typeof body !== 'string' || body.length === 0) return false;
+  if (body.includes(VP_STUB_MARKER)) return false;
+  return body.includes('**Persona:**');
+}
+
+/**
+ * One-shot migration: walk `<root>/vp/<id>/summary.md` and rewrite any
+ * file matching the legacy shape (`isLegacyVpSummary`) into the current
+ * stamped stub. Idempotent — a stamped or Dream-v2-produced file is left
+ * untouched. Safe to run on every session boot.
+ *
+ * Existing users whose `summary.md` was written by the pre-stamp stub
+ * carry the persona body forever, because `backfillVpSummaries` only
+ * writes when the file is empty/missing. This pass closes that gap.
+ *
+ * @param {{ libDir: string, root?: string }} opts
+ * @returns {{ scanned: number, migrated: number }}
+ */
+export function migrateLegacyVpSummaries({ libDir, root = DEFAULT_MEMORY_ROOT }) {
+  let scanned = 0;
+  let migrated = 0;
+  const vpRoot = join(root, 'vp');
+  if (!existsSync(vpRoot)) return { scanned, migrated };
+  let entries;
+  try { entries = readdirSync(vpRoot); } catch { return { scanned, migrated }; }
+  for (const name of entries) {
+    if (name.startsWith('.')) continue;
+    const summaryPath = join(vpRoot, name, 'summary.md');
+    let body = '';
+    try {
+      if (!existsSync(summaryPath)) continue;
+      body = readFileSync(summaryPath, 'utf-8');
+    } catch { continue; }
+    scanned++;
+    if (!isLegacyVpSummary(body)) continue;
+    const stub = readVpRoleSummary(libDir, name);
+    if (!stub) continue;
+    try {
+      writeAtomicSync(summaryPath, stub);
+      migrated++;
+    } catch (err) {
+      console.warn(`[seed-backfill] migrate vp ${name}: ${err?.message || err}`);
+    }
+  }
+  return { scanned, migrated };
+}
+
 /**
  * Walk groups/ and seed `summary.md` for every group without one.
  *
@@ -161,17 +265,30 @@ export function backfillGroupSummaries({ yeaftDir, root = DEFAULT_MEMORY_ROOT })
  * Run all backfills sequentially. Best-effort — any per-step error is
  * logged and the next step still runs.
  *
+ * Order:
+ *   1. Migrate legacy VP summaries (rewrite pre-stamp persona-body stubs
+ *      to current-format stamped stubs). Runs FIRST so that
+ *      `backfillVpSummaries` sees consistent on-disk state and any
+ *      future logic that distinguishes "stamped" vs "free-form" works
+ *      uniformly downstream.
+ *   2. Backfill missing VP summaries.
+ *   3. Backfill missing group summaries.
+ *
  * @param {{ yeaftDir: string, libDir: string, root?: string }} opts
- * @returns {{ vp: {scanned:number, seeded:number}, group: {scanned:number, seeded:number} }}
+ * @returns {{ migrate: {scanned:number, migrated:number}, vp: {scanned:number, seeded:number}, group: {scanned:number, seeded:number} }}
  */
 export function runSummaryBackfill({ yeaftDir, libDir, root = DEFAULT_MEMORY_ROOT }) {
+  let migrate = { scanned: 0, migrated: 0 };
   let vp = { scanned: 0, seeded: 0 };
   let group = { scanned: 0, seeded: 0 };
+  try { migrate = migrateLegacyVpSummaries({ libDir, root }); } catch (err) {
+    console.warn('[seed-backfill] vp migrate failed:', err?.message || err);
+  }
   try { vp = backfillVpSummaries({ libDir, root }); } catch (err) {
     console.warn('[seed-backfill] vp pass failed:', err?.message || err);
   }
   try { group = backfillGroupSummaries({ yeaftDir, root }); } catch (err) {
     console.warn('[seed-backfill] group pass failed:', err?.message || err);
   }
-  return { vp, group };
+  return { migrate, vp, group };
 }

package/unify/stop-hooks.js

@@ -51,6 +51,11 @@ export async function runStopHooks(context) {
     // history replay can route messages back into the originating group.
     groupId,
     threadId,
+    // Multi-VP fan-out (history-dedup): when several engines run the
+    // same user prompt in parallel, the orchestrator persists the user
+    // row exactly once before fan-out. Each VP's stop-hook then skips
+    // the user record but still writes its own assistant + tool rows.
+    userAlreadyPersisted = false,
   } = context;
 
   // Model name for persisted messages: use primaryModel if provided, else config.model
@@ -90,6 +95,11 @@ export async function runStopHooks(context) {
       const recentMessages = messages.slice(turnStart);
       for (const msg of recentMessages) {
         if (!msg || !msg.role) continue;
+        // Skip the user row if the orchestrator already wrote it once for
+        // this turn (multi-VP fan-out: every VP's engine sees the same
+        // user prompt at conversationMessages[turnStart] but only the
+        // first writer should land on disk).
+        if (userAlreadyPersisted && msg.role === 'user') continue;
         // Allow empty assistant content when toolCalls are present;
         // tool messages have content by construction.
         const hasContent =

package/unify/vp/vp-crud.js

@@ -23,6 +23,7 @@ import { homedir } from 'os';
 import { validateVpId } from '../groups/ids.js';
 import { DEFAULT_VP_LIB_DIR, parseRoleMd } from './vp-store.js';
 import { seedSummaryIfMissingSync, removeScopeDirSync } from '../memory/store-v2.js';
+import { VP_STUB_MARKER } from '../memory/seed-backfill.js';
 
 /**
  * Default memory root used when callers don't pass `options.memoryRoot`.
@@ -40,26 +41,36 @@ const DEFAULT_MEMORY_ROOT = join(homedir(), '.yeaft', 'memory');
  * @param {object} payload  same shape as createVp
  * @returns {string}
  */
+/**
+ * Build the seed body for a freshly-created VP's `<root>/vp/<id>/summary.md`.
+ *
+ * IMPORTANT — this is a STUB that mirrors `seed-backfill.js#readVpRoleSummary`.
+ * Earlier versions of both writers embedded up to 800 chars of `persona`
+ * here. That body is *also* rendered as Section 1 of the system prompt by
+ * `renderVpPersona`, so the same persona text reappeared in the AMS
+ * Resident block — the user-visible "persona defined twice" bug. PR #722
+ * fixed `seed-backfill.js`; this writer is the create-time twin.
+ *
+ * The seed is therefore deliberately minimal (name + role + traits) and
+ * stamped with `VP_STUB_MARKER` so `engine.buildResidentEntries` knows to
+ * skip the own-VP Resident push (Section 1 is already the source of truth
+ * for own-VP identity). Once Dream-v2 writes a real summary it overwrites
+ * this stub and lacks the marker, so it surfaces normally.
+ *
+ * @param {object} payload  same shape as createVp
+ * @returns {string}
+ */
 export function buildVpSeedSummary(payload) {
   const id = String(payload?.vpId || '').trim();
   const name = (payload?.displayName != null ? String(payload.displayName) : id).trim();
   const role = (payload?.role != null ? String(payload.role) : '').trim();
-  const persona = (typeof payload?.persona === 'string' ? payload.persona : '').trim();
   const traits = Array.isArray(payload?.traits)
     ? payload.traits.map(t => String(t)).filter(Boolean)
     : [];
 
-  const lines = [];
-  lines.push(`# ${name}`);
+  const lines = [VP_STUB_MARKER, '', `# ${name}`];
   if (role) lines.push('', `**Role:** ${role}`);
   if (traits.length > 0) lines.push('', `**Traits:** ${traits.join(', ')}`);
-  if (persona) {
-    // Keep the persona body terse — first 800 chars is plenty for an
-    // initial Layer-A resident summary; Dream-v2 will rewrite it as
-    // memory accumulates.
-    const truncated = persona.length > 800 ? persona.slice(0, 800).trim() + '…' : persona;
-    lines.push('', '**Persona:**', '', truncated);
-  }
   return lines.join('\n').trim();
 }
 

package/unify/web-bridge.js

@@ -399,6 +399,30 @@ function ensureDriverRunning(groupId, vpId) {
       const promptParts = inboundParts.length > 0
         ? [...inboundParts, { type: 'text', text: prompt }]
         : null;
+
+      // Multi-VP fan-out — history dedup. Persist the user row exactly
+      // once per envelope (keyed by coordinator-minted msg.id). The
+      // first driver to pick up an envelope writes; later drivers
+      // (other VPs in the same fan-out, or downstream route_forward
+      // targets sharing an msg.id) become no-ops. Each VP's engine
+      // runs with `userAlreadyPersisted: true` so its stop-hook never
+      // tries to write the user row a second time.
+      //
+      // Belt-and-suspenders against the handleUnifyGroupChat call: in
+      // the common path that one runs first and this is a no-op; in
+      // edge paths (route_forward without an upstream user write) this
+      // is the writer.
+      try {
+        const envMsgId = envelope?.msg?.id;
+        if (envMsgId && text) {
+          persistUserMessageOnceByMsgId({
+            msgId: envMsgId,
+            text,
+            groupId,
+          });
+        }
+      } catch { /* never crash WS pipeline */ }
+
       try {
         await runVpTurn({
           prompt,
@@ -1411,6 +1435,36 @@ export async function handleUnifyGroupChat(msg) {
     return;
   }
 
+  // Multi-VP fan-out — history dedup (PR-fix-unify-group-history-dedup):
+  // persist the user row EXACTLY ONCE per turn. We do it AFTER
+  // `coord.ingest` so we can key dedup on the coordinator-minted
+  // `report.message.id` — the same id the per-VP driver will see on
+  // `envelope.msg.id`, which lets a route_forward injection that lands
+  // on the same id be a no-op.
+  //
+  // Each VP's engine then runs with `userAlreadyPersisted: true` (see
+  // runVpTurn's vpEngine.query call) so its stop-hook skips the
+  // user-row append while still writing assistant + tool rows.
+  //
+  // We persist the canonical `text` (no `@vp-X ` prefix) because that's
+  // what the user actually typed. Clean text matches what `loadHistory`
+  // replays back to the frontend on refresh.
+  try {
+    const persistedMsgId = report?.message?.id;
+    if (persistedMsgId) {
+      persistUserMessageOnceByMsgId({
+        msgId: persistedMsgId,
+        text,
+        groupId,
+      });
+    }
+  } catch (err) {
+    console.warn(
+      '[Unify] unify_group_chat: persistUserMessageOnceByMsgId failed',
+      err?.message || err,
+    );
+  }
+
   const dispatchedIds = Array.isArray(report?.dispatched) ? report.dispatched : [];
   const fallbackId = typeof report?.fallback === 'string' ? report.fallback : null;
   if (dispatchedIds.length === 0 && !fallbackId) {
@@ -1792,6 +1846,14 @@ async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, en
         promptParts,
         messages: trimmedMessages,
         signal: vpAbort.signal,
+        // Multi-VP fan-out (history-dedup): the user row was persisted
+        // ONCE by handleUnifyGroupChat → persistUserMessageOnce before
+        // fan-out. Tell the engine's stop-hook to skip the user-row
+        // append for THIS VP's turn (it still writes assistant + tool
+        // rows for this VP). Without this the magnet of N engines would
+        // each write a copy of the user message, and history replay
+        // would render the user's prompt N times.
+        userAlreadyPersisted: true,
         ...queryOpts,
       })) {
         resetQueryTimer();
@@ -1916,6 +1978,87 @@ function appendTurnToHistory(prompt, assistantTextParts, toolCallsAccum, toolRes
   }
 }
 
+/**
+ * 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.
+ *
+ * Without this dedup, a 2-VP group prompt produces TWO `m{NNNN}.md`
+ * user rows (one per engine) — `handleUnifyLoadHistory` then replays
+ * the user's prompt twice and sandwiches one VP's reply between two
+ * copies of the user message. Visually this reads as "messages out of
+ * order" because the second copy of the user prompt sits BETWEEN the
+ * two VPs' replies.
+ *
+ * Best-effort: a write failure does NOT abort the turn — engines can
+ * still run, and the next user message will trigger another append.
+ *
+ * Note: we mirror `engine.#persistMessages`'s schema for the user row
+ * exactly (role/content/threadId/groupId), so existing parsers /
+ * loaders see no schema drift. Attachments are not part of the on-disk
+ * 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
+ * @returns {boolean} true if this call wrote the row, false if a prior
+ *   call already wrote it (dedup hit).
+ */
+function persistUserMessageOnceByMsgId({ msgId, text, groupId }) {
+  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
+  // `if (persistedMsgId)`); refusing here keeps the helper's contract
+  // clean. A synthetic-id fallback (Date.now+random) would defeat dedup —
+  // every call would mint a unique id and write a duplicate row, which
+  // is the exact bug this helper exists to prevent.
+  if (!msgId || typeof msgId !== 'string') return false;
+  if (_persistedUserMsgIds.has(msgId)) return false;
+  // Mark BEFORE the empty-text bail. If a later same-id call arrives
+  // with non-empty text (e.g. a route_forward injection that the first
+  // caller passed in with empty text), the Set must already remember
+  // this id so the second call dedups instead of writing.
+  _persistedUserMsgIds.add(msgId);
+  if (!text || typeof text !== 'string') return false;
+  // Bound the Set so it doesn't grow unbounded over a long session.
+  // 4096 msg-ids is well past any realistic "messages in flight"
+  // window — once N drivers have observed the id, the rest can fall
+  // back to "write again" without harm (the second writer would be a
+  // duplicate, but it requires both: (a) the Set evicting an id AND
+  // (b) a still-running driver getting around to its first persist).
+  if (_persistedUserMsgIds.size > 4096) {
+    const iter = _persistedUserMsgIds.values();
+    for (let i = 0; i < 1024; i++) {
+      const v = iter.next();
+      if (v.done) break;
+      _persistedUserMsgIds.delete(v.value);
+    }
+  }
+  try {
+    const record = {
+      role: 'user',
+      content: text,
+      threadId: 'main',
+    };
+    if (groupId) record.groupId = groupId;
+    session.conversationStore.append(record);
+    return true;
+  } catch (err) {
+    console.warn(
+      '[Unify] persistUserMessageOnceByMsgId failed (non-fatal):',
+      err?.message || err,
+    );
+    return false;
+  }
+}
+
+/**
+ * Cleared on session reset (resetUnifySession) so a fresh session
+ * starts with no stale msg-ids.
+ */
+const _persistedUserMsgIds = new Set();
+
 /**
  * In-flight compact promise. Set by `scheduleCompactAfterTurn` when a
  * turn ends and triggers compaction; awaited by the next
@@ -2501,6 +2644,9 @@ export async function resetUnifySession() {
   vpDrivers.clear();
   vpEngines.clear();
   groupContexts.clear();
+  // History-dedup cache is keyed by per-session coordinator msg ids;
+  // a fresh session resets the id space, so clear the cache too.
+  _persistedUserMsgIds.clear();
 
   try {
     const yeaftDir = ctx.CONFIG?.yeaftDir;