@yeaft/webchat-agent 0.1.747 → 0.1.749

package/package.json

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

package/unify/compact/compactor.js

@@ -0,0 +1,242 @@
+/**
+ * compactor.js — per-group post-turn history compactor.
+ *
+ * Owns the orchestration that previously lived inline in
+ * `agent/unify/web-bridge.js` as `getCompactState` /
+ * `scheduleCompactAfterTurn` / `runCompactNow`. Bridge keeps WS knowledge
+ * and history ownership; this class owns:
+ *   - per-group single-flight + anti-starvation `pending` chain,
+ *   - the precheck via `shouldCompactHistory`,
+ *   - the call into `compactHistory` (which itself calls the supplied
+ *     `summarize` injectable — bound to `Engine.summarizeForCompact` by
+ *     `session.js`),
+ *   - the race-guard that bails when the live history reference / length
+ *     diverges from the snapshot we captured before awaiting the LLM.
+ *
+ * History is passed in PER CALL via a `historyHandle = { get, set }` so
+ * Compactor never has to know about `groupContexts`, `historyHydrated`,
+ * or any other bridge-internal field. The WS event sink is wired
+ * separately via `setOnCompacted`.
+ *
+ * Engine instances are per-VP-per-group (`vpEngines` keyed by
+ * `${groupId}::${vpId}`), so this orchestration cannot live on `Engine`
+ * itself: a per-group single-flight slot pinned to a per-VP Engine is a
+ * category error. Compactor is constructed once per session, beside the
+ * `dreamScheduler`.
+ */
+
+import { compactHistory, shouldCompactHistory } from '../history-compact.js';
+
+/**
+ * Output cap for the summarizer call. The full compacted history is
+ * built around the LLM-produced summary, so the summary itself must be
+ * bounded — too long defeats the point of compacting, too short loses
+ * context. 1024 tokens is the value that lived inline in the old
+ * `runCompactNow` helper in `web-bridge.js` and matches the budget
+ * `compactHistory` plans around.
+ */
+const SUMMARIZER_MAX_TOKENS = 1024;
+
+/**
+ * @typedef {object} CompactorHistoryHandle
+ * @property {() => Array<object>} get  — return the current live history array
+ * @property {(next: Array<object>) => void} set  — replace the array reference
+ */
+
+/**
+ * @typedef {object} CompactedResult
+ * @property {string|null} reason
+ * @property {number} beforeTurns
+ * @property {number} afterTurns
+ * @property {number} beforeTokens
+ * @property {number} afterTokens
+ * @property {number} archivedCount
+ */
+
+export class Compactor {
+  /**
+   * @param {object} opts
+   * @param {(args: {system: string, prompt: string, maxTokens?: number}) => Promise<string>} opts.summarize
+   *        Bound to `engine.summarizeForCompact` by `session.js`. Returns
+   *        the trimmed summary text (or '' on failure — `compactHistory`
+   *        treats that as a soft failure).
+   * @param {() => number|undefined} [opts.getMaxContextTokens]
+   *        Returns `config.maxContextTokens` for `shouldCompactHistory`.
+   * @param {(groupId: string, result: CompactedResult) => void} [opts.onCompacted]
+   *        Optional sink. Bridge wires this to send the
+   *        `unify_history_compacted` WS event. Default: no-op. Can be
+   *        replaced post-construction via `setOnCompacted`.
+   */
+  constructor({ summarize, getMaxContextTokens, onCompacted } = {}) {
+    if (typeof summarize !== 'function') {
+      throw new TypeError('Compactor: summarize is required');
+    }
+    this._summarize = summarize;
+    this._getMaxContextTokens = typeof getMaxContextTokens === 'function'
+      ? getMaxContextTokens
+      : () => undefined;
+    this._onCompacted = typeof onCompacted === 'function' ? onCompacted : () => {};
+    /** @type {Map<string, { inFlight: Promise<void>|null, pending: boolean }>} */
+    this._states = new Map();
+  }
+
+  /**
+   * Replace the post-success sink. Bridge calls this from
+   * `installUnifyRuntimeBridge` once the bridge-local
+   * `sendToServer` + `unifyConversationId` are available — keeps WS
+   * knowledge out of Compactor's constructor and avoids a circular
+   * import between `session.js` and `web-bridge.js`.
+   */
+  setOnCompacted(fn) {
+    this._onCompacted = typeof fn === 'function' ? fn : () => {};
+  }
+
+  /** Get-or-create the per-group state record. */
+  _state(groupId) {
+    let s = this._states.get(groupId);
+    if (!s) {
+      s = { inFlight: null, pending: false };
+      this._states.set(groupId, s);
+    }
+    return s;
+  }
+
+  /**
+   * Entry-gate await. Bridge calls at the top of `handleUnifyGroupChat`
+   * so a brand-new turn never reads a half-mutated history mid-compact.
+   * Other groups' compacts never block this gate (per-group keying).
+   *
+   * @param {string} groupId
+   */
+  async awaitInFlight(groupId) {
+    if (!groupId) return;
+    const s = this._states.get(groupId);
+    if (s && s.inFlight) {
+      try { await s.inFlight; } catch { /* _runOnce already logs */ }
+    }
+  }
+
+  /**
+   * Post-turn fire-and-forget. Bridge calls after the per-VP fanout
+   * completes for a turn. The `historyHandle` MUST be a per-call value:
+   * its `get` / `set` close over the bridge's groupId-scoped helpers
+   * (`getOrCreateGroupHistory` / `setGroupHistory`), not over a frozen
+   * snapshot, so a chained follow-up sees fresh state.
+   *
+   * Anti-starvation: while a compact is in flight, additional
+   * `scheduleAfterTurn` calls collapse to a single `pending=true`. Once
+   * the in-flight finishes, exactly one follow-up runs (no matter how
+   * many turns piled up during the await).
+   *
+   * @param {string} groupId
+   * @param {CompactorHistoryHandle} historyHandle
+   */
+  scheduleAfterTurn(groupId, historyHandle) {
+    if (!groupId || !historyHandle) return;
+    const s = this._state(groupId);
+    if (s.inFlight) {
+      // Anti-starvation: compact is already running. Mark a follow-up
+      // so when it finishes, it re-evaluates and runs again if still
+      // triggered.
+      s.pending = true;
+      return;
+    }
+    s.inFlight = this._runOnce(groupId, historyHandle).finally(() => {
+      s.inFlight = null;
+      // If turns piled up while we were running and compaction is still
+      // needed, chain a follow-up. Use a microtask so the .finally
+      // chain settles cleanly before the next promise is created.
+      if (s.pending) {
+        s.pending = false;
+        queueMicrotask(() => this.scheduleAfterTurn(groupId, historyHandle));
+      }
+    });
+  }
+
+  /**
+   * One compact pass. Captures snapshot reference + length, runs the
+   * precheck, calls `compactHistory`, race-guards, applies via
+   * `historyHandle.set`, then notifies `onCompacted`. All errors are
+   * swallowed (logged) so `inFlight` always clears.
+   *
+   * @param {string} groupId
+   * @param {CompactorHistoryHandle} historyHandle
+   */
+  async _runOnce(groupId, historyHandle) {
+    try {
+      // Capture reference AND length. If a different code path swaps the
+      // array (`consolidate` event, session reset, manual clear) the
+      // reference will differ. If a driver path push-mutates new
+      // messages in place (e.g. `route_forward` triggering a new VP
+      // turn during compact), the reference is the same but the length
+      // grew. Both cases mean our snapshot is no longer canonical.
+      const snapshot = historyHandle.get();
+      if (!Array.isArray(snapshot) || snapshot.length === 0) return;
+      const snapshotLen = snapshot.length;
+
+      const maxContextTokens = this._getMaxContextTokens();
+
+      // Cheap O(n) precheck so we don't bother engaging the LLM at all
+      // when the conversation is still small. `compactHistory` runs the
+      // same check internally, but only after building the summarizer
+      // input — this keeps small chats off the LLM altogether.
+      const triage = shouldCompactHistory(snapshot, { maxContextTokens });
+      if (!triage.trigger) return;
+
+      const summarize = ({ system, prompt }) =>
+        this._summarize({ system, prompt, maxTokens: SUMMARIZER_MAX_TOKENS });
+
+      const result = await compactHistory(snapshot, { summarize, maxContextTokens });
+      if (!result || !result.compacted) {
+        if (result && result.error) {
+          console.warn(
+            `[Unify] history compact: summarizer failed (${result.error}); ` +
+            `keeping ${result.beforeTurns} turns / ~${result.beforeTokens} tokens`
+          );
+        }
+        return;
+      }
+
+      // Race guard: if the group's history was reassigned during the
+      // await (e.g. consolidate / reset), or push-mutated by a driver
+      // path, do NOT overwrite the fresh state with our stale compacted
+      // snapshot. These discards are EXPECTED during normal session
+      // resets / route_forward bursts — log at debug, not info.
+      const current = historyHandle.get();
+      if (current !== snapshot) {
+        console.debug('[Unify] history compact: history was reset during compact — discarding stale summary');
+        return;
+      }
+      if (current.length !== snapshotLen) {
+        console.debug('[Unify] history compact: history was appended-to during compact — discarding stale summary');
+        return;
+      }
+
+      historyHandle.set(result.messages);
+      console.log(
+        `[Unify] history compacted (reason=${result.reason}): ` +
+        `turns ${result.beforeTurns}→${result.afterTurns}, ` +
+        `tokens ~${result.beforeTokens}→${result.afterTokens}, ` +
+        `archived ${result.archivedCount} messages`
+      );
+
+      try {
+        this._onCompacted(groupId, {
+          reason: result.reason,
+          beforeTurns: result.beforeTurns,
+          afterTurns: result.afterTurns,
+          beforeTokens: result.beforeTokens,
+          afterTokens: result.afterTokens,
+          archivedCount: result.archivedCount,
+        });
+      } catch { /* sink failure must not abort the orchestrator */ }
+    } catch (err) {
+      console.warn(`[Unify] history compact: unexpected failure (groupId=${groupId})`, err?.message || err);
+    }
+  }
+
+  /** Test-only: clear all per-group state. */
+  __testReset() {
+    this._states.clear();
+  }
+}

package/unify/engine.js

@@ -1755,6 +1755,17 @@ export class Engine {
             config: this.#fastConfig,
             primaryModel: this.#config.model,
             messages: conversationMessages,
+            // Reflect-persist fix: tell stop-hooks the EXACT turn boundary
+            // instead of letting it heuristically scan back to the last
+            // role:'user'. With T1/T2 reflection collapse, the last
+            // role:'user' is the synthetic reflection message — not the
+            // original user prompt — so the heuristic was dropping
+            // earlier reflection messages and the original prompt off
+            // the persistence window. `turnStartIdx` is the index of
+            // the original user prompt (set at query() entry); slicing
+            // from there persists the full collapsed turn including all
+            // reflection messages and the trailing assistant response.
+            turnStartIdx,
             trace: this.#trace,
             // Bug 6: tag persisted messages with the originating group so
             // history replay can re-stamp them on reload.

package/unify/session.js

@@ -23,6 +23,7 @@ import { MCPManager } from './mcp.js';
 import { createFullRegistry } from './tools/index.js';
 import { initFeatureStore } from './tools/feature-tools.js';
 import { Engine } from './engine.js';
+import { Compactor } from './compact/compactor.js';
 // H2.f.5: threads/, pipeline/dispatcher and input-queue retired. The
 // session now exposes a single Engine.
 //
@@ -65,6 +66,7 @@ import { existsSync as existsSyncSafe, readFileSync as readFileSyncSafe } from '
 /**
  * @typedef {Object} Session
  * @property {Engine} engine — The wired engine, ready for .query()
+ * @property {import('./compact/compactor.js').Compactor} compactor — Per-group history compactor
  * @property {import('./llm/adapter.js').LLMAdapter} adapter — The LLM adapter
  * @property {object} config — Resolved configuration
  * @property {ConversationStore} conversationStore — Conversation persistence
@@ -303,6 +305,18 @@ export async function loadSession(options = {}) {
     yeaftDir,
   });
 
+  // ─── 9a-pre. Create per-group history Compactor ────────
+  // Owns the post-turn single-flight + race-guarded compactor that used
+  // to live inline in web-bridge.js. Bridge keeps history ownership and
+  // wires the WS sink (`unify_history_compacted`) via
+  // `compactor.setOnCompacted` from `installUnifyRuntimeBridge`.
+  const compactor = new Compactor({
+    summarize: ({ system, prompt, maxTokens } = {}) =>
+      engine.summarizeForCompact({ system, prompt, maxTokens }),
+    getMaxContextTokens: () =>
+      typeof config.maxContextTokens === 'number' ? config.maxContextTokens : undefined,
+  });
+
   // ─── 9a. Create dream scheduler ────────────
   // The legacy R6 dream-scheduler was retired alongside recall-r6;
   // dream-v2 is the only active path (the `config.memoryV2` opt-out
@@ -396,6 +410,7 @@ export async function loadSession(options = {}) {
     config,
     conversationStore,
     dreamScheduler,
+    compactor,
     skillManager,
     mcpManager,
     toolRegistry,

package/unify/stop-hooks.js

@@ -30,6 +30,7 @@ let _permissionWarned = false;
  *   config: object,
  *   primaryModel?: string,
  *   messages?: object[],
+ *   turnStartIdx?: number,
  *   taskId?: string,
  *   workerId?: string,
  *   trace?: object,
@@ -45,6 +46,19 @@ export async function runStopHooks(context) {
     config,
     primaryModel,
     messages = [],
+    // Reflect-persist fix: when the engine knows the exact turn boundary
+    // (it does — `turnStartIdx` is set at query() entry as
+    // `conversationMessages.length - 1`), pass it in. The legacy
+    // heuristic of "scan back for the last role:'user'" is wrong once
+    // T1/T2 reflection has collapsed the tool arc into a synthetic
+    // role:'user' message — that synthetic message would be picked as
+    // the turn start, dropping the original prompt AND any earlier
+    // reflection messages from the persistence window.
+    //
+    // When undefined, falls back to the legacy heuristic so older
+    // callers (sub-agents, workers) that don't pass it continue to
+    // work.
+    turnStartIdx,
     taskId,
     trace,
     // Bug 6: groupId/threadId stamped on every persisted message so
@@ -77,19 +91,33 @@ export async function runStopHooks(context) {
   // assistant's `toolCalls` and each paired `role:'tool'` result —
   // otherwise restoring history on session reload drops the pairing
   // and causes "No tool output found for function call" 400s on the
-  // next chat-completions request. We walk back from the end of
-  // `messages` to find the first `role:'user'` that marks the start
-  // of the current turn, then persist everything from there forward.
+  // next chat-completions request.
+  //
+  // Reflect-persist fix: prefer the explicit `turnStartIdx` from the
+  // engine when given. The legacy heuristic of "find the last
+  // role:'user'" is broken in the presence of T1/T2 reflection
+  // collapse, because the collapsed reflection is itself a
+  // role:'user' message — using it as the turn start would drop the
+  // real user prompt and any earlier reflections.
   try {
     if (conversationStore && messages.length > 0) {
-      // Find the start of the latest turn — the last `role:'user'`
-      // message in the array. Everything from that index onward is
-      // new this turn (user + assistant[+toolCalls] + tool results).
-      let turnStart = messages.length - 1;
-      for (let i = messages.length - 1; i >= 0; i--) {
-        if (messages[i] && messages[i].role === 'user') {
-          turnStart = i;
-          break;
+      let turnStart;
+      if (typeof turnStartIdx === 'number'
+          && Number.isFinite(turnStartIdx)
+          && turnStartIdx >= 0
+          && turnStartIdx < messages.length) {
+        // Engine-supplied exact turn boundary — preferred.
+        turnStart = turnStartIdx;
+      } else {
+        // Legacy heuristic — find the last role:'user' message.
+        // Used by sub-agent / worker callers that don't compute the
+        // boundary explicitly.
+        turnStart = messages.length - 1;
+        for (let i = messages.length - 1; i >= 0; i--) {
+          if (messages[i] && messages[i].role === 'user') {
+            turnStart = i;
+            break;
+          }
         }
       }
       const recentMessages = messages.slice(turnStart);
@@ -99,7 +127,18 @@ export async function runStopHooks(context) {
         // 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;
+        //
+        // With the engine-supplied turnStartIdx, `messages[turnStart]`
+        // is the ORIGINAL user prompt (not a reflection placeholder),
+        // so the first message in `recentMessages` is the one that
+        // gets skipped on subsequent VPs. Reflection messages that
+        // come AFTER turnStart still have role:'user' — they are NOT
+        // skipped because `userAlreadyPersisted` only suppresses the
+        // first user-prompt copy; reflections are per-VP outputs and
+        // each VP's reflections are valid contributions to the
+        // shared history (this matches today's per-VP fan-out where
+        // each VP appends its own assistant + tool rows).
+        if (userAlreadyPersisted && msg.role === 'user' && msg === recentMessages[0]) continue;
         // Allow empty assistant content when toolCalls are present;
         // tool messages have content by construction.
         const hasContent =

package/unify/web-bridge.js

@@ -46,8 +46,6 @@ import { openGroup, loadGroupMeta } from './groups/group-store.js';
 import { createCoordinator } from './groups/coordinator.js';
 import { seedDefaultGroup } from './groups/seed-default.js';
 import {
-  shouldCompactHistory,
-  compactHistory,
   trimSnapshotForBudget,
 } from './history-compact.js';
 import { persistUnifyAttachments, attachmentsForPersistence } from './attachments.js';
@@ -236,36 +234,189 @@ let unifyConversationId = null;
 let _vpUnsubscribe = null;
 
 /**
- * Flat conversation history for engine context continuity. H2.f.2: replaces
- * the per-thread Map. Cleared on session reset or by a `consolidate` event.
- * @type {Array<{role:'user'|'assistant'|'tool', content:string|Array, toolCalls?:Array, toolCallId?:string, isError?:boolean}>}
+ * Per-group conversation history lives on the GroupContext entry
+ * (`groupContexts.get(groupId).history`). The pre-refactor module-level
+ * `conversationMessages` was a single array shared across every group —
+ * a user prompt in group-A would leak into group-B's next-turn snapshot
+ * because the bridge appended every turn to the same array regardless
+ * of which group it belonged to. Disk was group-tagged correctly, but
+ * the in-memory tape was unified.
+ *
+ * Post-refactor: each GroupContext owns its own `history`, lazily
+ * hydrated from `conversationStore.loadRecentByGroup(groupId)` on first
+ * access. Group-A and group-B are isolated.
+ *
+ * @typedef {Array<{role:'user'|'assistant'|'tool', content:string|Array, toolCalls?:Array, toolCallId?:string, isError?:boolean}>} GroupHistory
  */
-let conversationMessages = [];
 
 /**
- * Restore conversation history from persisted store. Accepts `role:'tool'`
- * messages and preserves `toolCalls`/`toolCallId` so the next chat-completions
- * serialization includes paired tool messages (avoids "No tool output found
- * for function call" 400s).
+ * @typedef {Object} GroupContextEntry
+ * @property {object|null} coord — group coordinator (lazily built by getOrCreateGroupContext)
+ * @property {object|null} router — message router (lazily built by getOrCreateGroupContext)
+ * @property {object|null} groupHandle — opened group handle (lazily built by getOrCreateGroupContext)
+ * @property {GroupHistory} history — per-group conversation tape
+ * @property {boolean} historyHydrated — true once history has been loaded
+ *   from disk (or explicitly assigned). The flag is required because an
+ *   empty array is legitimate post-consolidate / post-clear state and
+ *   MUST NOT trigger a re-hydrate. Without the flag, a partial entry
+ *   would short-circuit `getOrCreateGroupHistory` on truthy `[]` and skip
+ *   the disk load.
+ */
+
+/** Build a fresh stub entry with no coord/router/history loaded. */
+function makeGroupContextStub() {
+  return {
+    coord: null,
+    router: null,
+    groupHandle: null,
+    history: [],
+    historyHydrated: false,
+  };
+}
+
+/**
+ * Project a persisted message record into the in-memory history shape.
+ * Accepts `role:'tool'` and preserves `toolCalls`/`toolCallId` so the
+ * next chat-completions serialization includes paired tool messages
+ * (avoids "No tool output found for function call" 400s).
  *
- * @param {Array<object>} recent — output of conversationStore.loadRecent()
+ * @param {object} m — record from conversationStore.loadRecent*()
+ * @returns {object|null} history-shape entry, or null to skip
  */
-function restoreHistoryFromRecent(recent) {
-  conversationMessages = [];
-  for (const m of recent) {
-    if (m.role !== 'user' && m.role !== 'assistant' && m.role !== 'tool') continue;
-    const entry = { role: m.role, content: m.content };
-    if (m.toolCallId) entry.toolCallId = m.toolCallId;
-    if (Array.isArray(m.toolCalls) && m.toolCalls.length > 0) {
-      entry.toolCalls = m.toolCalls.map(tc => ({
-        id: tc.id,
-        name: tc.name,
-        input: tc.input,
-      }));
-    }
-    if (m.isError) entry.isError = true;
-    conversationMessages.push(entry);
+function projectPersistedToHistoryEntry(m) {
+  if (!m) return null;
+  if (m.role !== 'user' && m.role !== 'assistant' && m.role !== 'tool') return null;
+  const entry = { role: m.role, content: m.content };
+  if (m.toolCallId) entry.toolCallId = m.toolCallId;
+  if (Array.isArray(m.toolCalls) && m.toolCalls.length > 0) {
+    entry.toolCalls = m.toolCalls.map(tc => ({
+      id: tc.id,
+      name: tc.name,
+      input: tc.input,
+    }));
   }
+  if (m.isError) entry.isError = true;
+  return entry;
+}
+
+/**
+ * Hydrate a freshly-created GroupContext's history from the on-disk
+ * conversation store. Returns an empty array if the session isn't
+ * loaded yet (sub-agent / test paths) or if the load throws.
+ *
+ * @param {string} groupId
+ * @returns {GroupHistory}
+ */
+function hydrateGroupHistory(groupId) {
+  if (!session?.conversationStore || !groupId) return [];
+  let recent;
+  try {
+    recent = session.conversationStore.loadRecentByGroup(groupId);
+  } catch (err) {
+    console.warn('[Unify] hydrateGroupHistory failed (groupId=%s):', groupId, err?.message || err);
+    return [];
+  }
+  const out = [];
+  for (const m of recent || []) {
+    const entry = projectPersistedToHistoryEntry(m);
+    if (entry) out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * Get-or-create the per-group history array. Used everywhere the bridge
+ * needs to read/append/snapshot a group's conversation tape. Lazily
+ * inserts an entry into `groupContexts` on first access — no
+ * `groupHandle` required (history is independent of coord/router
+ * lifecycle, so a sub-agent / route_forward path that hasn't yet
+ * opened the group can still read history).
+ *
+ * Returns the SAME array reference across calls within the same
+ * lifecycle, so consumers can mutate-in-place. Reassigned only by
+ * compact (race guard checks reference equality), `consolidate`
+ * events, and session reset.
+ *
+ * @param {string} groupId
+ * @returns {GroupHistory}
+ */
+function getOrCreateGroupHistory(groupId) {
+  if (!groupId) return [];
+  let entry = groupContexts.get(groupId);
+  // Use `historyHydrated` rather than truthiness on `history` itself —
+  // an empty array (post-consolidate, post-clear, or a partial entry
+  // seeded by an early `getOrCreateGroupContext` call before data was
+  // loaded) is legitimate state that does NOT mean "needs hydration"...
+  // unless we never loaded from disk in the first place. The flag
+  // separates the two cases.
+  if (entry && entry.historyHydrated) return entry.history;
+  if (!entry) {
+    entry = makeGroupContextStub();
+    groupContexts.set(groupId, entry);
+  }
+  entry.history = hydrateGroupHistory(groupId);
+  entry.historyHydrated = true;
+  return entry.history;
+}
+
+/**
+ * Reassign a group's history reference. Used by compact + consolidate +
+ * clear paths that need to swap the array (not just mutate it). Returns
+ * the new reference. Idempotent if the entry doesn't exist (creates one).
+ *
+ * Sets `historyHydrated = true` because an explicit assignment is itself
+ * a hydration — even setting `[]` after `consolidate` means "this is the
+ * canonical state right now, don't re-load from disk".
+ *
+ * @param {string} groupId
+ * @param {GroupHistory} next
+ */
+function setGroupHistory(groupId, next) {
+  if (!groupId) return;
+  let entry = groupContexts.get(groupId);
+  if (!entry) {
+    entry = makeGroupContextStub();
+    groupContexts.set(groupId, entry);
+  }
+  entry.history = next;
+  entry.historyHydrated = true;
+}
+
+/**
+ * Test-only access to a group's history array. Re-exported below as
+ * `__testGroupHistory`. Lets tests pin the per-group isolation contract
+ * without booting a full session.
+ *
+ * @param {string} groupId
+ */
+export function __testGroupHistory(groupId) {
+  return getOrCreateGroupHistory(groupId);
+}
+
+/**
+ * Test-only: install a minimal `session` so `hydrateGroupHistory` can
+ * read from a real `ConversationStore`. Pass `null` to clear.
+ *
+ * Tests that need to verify the hydrate-from-disk path can construct a
+ * `ConversationStore` against a tmp dir, write per-group records via
+ * `store.append({groupId, ...})`, then call this helper to wire the
+ * store into the bridge before calling `__testGroupHistory(groupId)`.
+ *
+ * @param {{ conversationStore: object } | null} sessionLike
+ */
+export function __testSetSession(sessionLike) {
+  session = sessionLike;
+}
+
+/**
+ * Test-only: peek at the GroupContext entry for a group (or undefined
+ * if never seeded). Lets tests assert the `historyHydrated` flag without
+ * exporting the entire `groupContexts` Map.
+ *
+ * @param {string} groupId
+ */
+export function __testGroupContextEntry(groupId) {
+  return groupContexts.get(groupId);
 }
 
 /** Whether we've already sent a permission warning to the UI */
@@ -334,13 +485,29 @@ function getOrCreateVpEngine(groupId, vpId) {
  */
 function getOrCreateGroupContext(groupId, groupHandle) {
   let entry = groupContexts.get(groupId);
-  if (entry) return entry;
+  if (entry && entry.coord && entry.router) return entry;
+  // Either no entry, or a partial entry seeded by `getOrCreateGroupHistory`
+  // (no coord/router yet). Build the coord/router and merge into the
+  // existing record so the per-group history reference and hydration
+  // flag are preserved.
   const coord = createCoordinator(groupHandle, {
     deliver: (vpId, envelope) => enqueueForVp(groupId, vpId, envelope),
   });
   const router = createRouter({ coordinator: coord });
-  entry = { coord, router, groupHandle };
-  groupContexts.set(groupId, entry);
+  if (!entry) {
+    entry = makeGroupContextStub();
+    groupContexts.set(groupId, entry);
+  }
+  entry.coord = coord;
+  entry.router = router;
+  entry.groupHandle = groupHandle;
+  // Defend against a future caller that builds a coord/router without
+  // having gone through `getOrCreateGroupHistory` first: a partial entry
+  // could exist with `historyHydrated:false`, so do the load now.
+  if (!entry.historyHydrated) {
+    entry.history = hydrateGroupHistory(groupId);
+    entry.historyHydrated = true;
+  }
   return entry;
 }
 
@@ -411,8 +578,9 @@ function ensureDriverRunning(groupId, vpId) {
       turnAbortCtrls.set(turnId, vpAbort);
       // Snapshot history at the moment this turn starts. Later turns in
       // the same driver loop see updated history (post-append from the
-      // previous turn).
-      const baseSnapshot = [...conversationMessages];
+      // previous turn). Per-group: each driver only sees its own group's
+      // tape, so cross-group prompts never leak into a VP's snapshot.
+      const baseSnapshot = [...getOrCreateGroupHistory(groupId)];
       const trigger = envelope?.trigger || 'fallback';
       // Synthesize the prompt. For coordinator-emitted envelopes the
       // text lives at envelope.msg.text. We prefix `@vp-<id>` to mirror
@@ -559,6 +727,12 @@ export async function __testResetVpState() {
   vpEngines.clear();
   vpAborts.clear();
   groupContexts.clear();
+  // Per-group compact in-flight + pending state lives on the session's
+  // Compactor. Clear it so a follow-on test doesn't see ghost in-flight
+  // promises from a prior run.
+  if (session?.compactor && typeof session.compactor.__testReset === 'function') {
+    session.compactor.__testReset();
+  }
 }
 
 
@@ -924,6 +1098,28 @@ export function installUnifyRuntimeBridge(s) {
     } catch { /* never let event delivery throw */ }
   };
 
+  // Wire the post-compact WS sink. Compactor is constructed in
+  // session.js with a no-op sink; bridge owns `sendUnifyEvent` /
+  // `unifyConversationId`, so the sink is wired here once a session is
+  // present. Per-group `unify_history_compacted` events fire after a
+  // successful summarize+swap.
+  if (s.compactor && typeof s.compactor.setOnCompacted === 'function') {
+    s.compactor.setOnCompacted((groupId, result) => {
+      try {
+        sendUnifyEvent({
+          type: 'unify_history_compacted',
+          reason: result?.reason ?? null,
+          beforeTurns: result?.beforeTurns,
+          afterTurns: result?.afterTurns,
+          beforeTokens: result?.beforeTokens,
+          afterTokens: result?.afterTokens,
+          archivedCount: result?.archivedCount,
+          ts: Date.now(),
+        }, { groupId });
+      } catch { /* WS pipeline failure must not crash compact */ }
+    });
+  }
+
   ctx.unifyRuntimeSettings = {
     // No multi-thread settings to surface anymore. Stub for back-compat
     // with message-router's update_unify_settings branch — assignments are
@@ -1081,8 +1277,9 @@ function handleEngineEvent(event, hctx) {
       break;
 
     case 'consolidate':
-      // Engine compressed the context — clear our accumulated history.
-      conversationMessages = [];
+      // Engine compressed the context — clear THIS group's accumulated
+      // history. Other groups' histories stay intact.
+      if (hctx.groupId) setGroupHistory(hctx.groupId, []);
       sendUnifyEvent({
         type: 'consolidate',
         archivedCount: event.archivedCount,
@@ -1254,13 +1451,16 @@ export async function handleUnifyGroupChat(msg) {
     ? msg.groupId.trim()
     : 'grp_default';
 
-  // Entry gate: if a compact is in flight from the previous turn,
-  // wait for it to finish before reading conversationMessages. Compact
-  // runs at turn END (post-fanout) so it does not block the user's
-  // current message latency, but a fast double-send from the user must
-  // not race with the swap.
-  if (_compactInFlight) {
-    try { await _compactInFlight; } catch { /* first caller logs */ }
+  // Entry gate: if a compact is in flight from the previous turn IN
+  // THIS GROUP, wait for it to finish before reading the group's
+  // history. Compact runs at turn END (post-fanout) so it does not
+  // block the user's current message latency, but a fast double-send
+  // from the user must not race with the swap. Other groups' compacts
+  // never block this gate. Compactor is created in session.js — until
+  // a session has loaded (or in test paths that never call
+  // `ensureSessionLoaded`) it may be unavailable; skip gracefully.
+  if (session?.compactor) {
+    await session.compactor.awaitInFlight(groupId);
   }
 
   // yeaftDir is a hard prerequisite for both session boot and group seeding;
@@ -1524,12 +1724,21 @@ export async function handleUnifyGroupChat(msg) {
   await waitForVpDrivers(groupId, primaryTargets);
 
   // Post-turn compaction. Triggers when the JUST-APPENDED turn pushed
-  // history past 20 turns / 80K tokens. Runs in the background — does
-  // not block the response to this message. The next user message
-  // awaits `_compactInFlight` at the entry gate (handleUnifyGroupChat
-  // top), so the swap is guaranteed to be observed before the next
-  // baseSnapshot capture. Errors are swallowed; next turn retries.
-  scheduleCompactAfterTurn(groupId);
+  // history past the configured token thresholds for THIS group. Runs
+  // in the background — does not block the response to this message.
+  // The next user message in the same group awaits its per-group
+  // in-flight at the entry gate (handleUnifyGroupChat top) via
+  // `compactor.awaitInFlight`, so the swap is guaranteed to be
+  // observed before the next baseSnapshot capture. Errors are
+  // swallowed; next turn retries. The Compactor takes a per-call
+  // historyHandle so the bridge keeps history ownership and the
+  // Compactor stays ignorant of `groupContexts` / `historyHydrated`.
+  if (session?.compactor && groupId) {
+    session.compactor.scheduleAfterTurn(groupId, {
+      get: () => getOrCreateGroupHistory(groupId),
+      set: (next) => setGroupHistory(groupId, next),
+    });
+  }
 }
 
 /**
@@ -1696,7 +1905,8 @@ async function ensureSessionLoaded() {
 
   unifyConversationId = `unify-${Date.now()}`;
 
-  restoreHistoryFromRecent(session.conversationStore.loadRecent());
+  // Per-group history is hydrated lazily on first `getOrCreateGroupHistory`
+  // — there's no global "all conversations" tape any more.
 
   sendUnifyEvent({
     type: 'session_ready',
@@ -1902,7 +2112,7 @@ async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, en
       }
 
       // Turn completed — atomically append this VP's output to shared history.
-      appendTurnToHistory(prompt, assistantTextParts, toolCallsAccum, toolResultsAccum);
+      appendTurnToGroupHistory(groupId, prompt, assistantTextParts, toolCallsAccum, toolResultsAccum);
 
       sendUnifyOutput({
         type: 'assistant',
@@ -1960,11 +2170,21 @@ async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, en
 }
 
 /**
- * Atomically append a completed VP-turn's messages to the shared
+ * Atomically append a completed VP-turn's messages to the GROUP'S
  * conversation history. Called once at turn end (not during streaming).
+ *
+ * Note: this does NOT see the engine's collapsed form — it appends the
+ * raw user prompt + the per-VP assistant text + tool results. The
+ * engine's own `conversationMessages` (with T1/T2 collapse applied)
+ * is persisted to disk via stop-hooks, so the next turn's history is
+ * read from disk via `loadRecentByGroup` on next session boot. Within
+ * a session, this in-memory tape carries the un-collapsed form — which
+ * is fine because each VP turn's `engine.query` re-collapses on the fly.
  */
-function appendTurnToHistory(prompt, assistantTextParts, toolCallsAccum, toolResultsAccum) {
-  conversationMessages.push({ role: 'user', content: prompt });
+function appendTurnToGroupHistory(groupId, prompt, assistantTextParts, toolCallsAccum, toolResultsAccum) {
+  if (!groupId) return;
+  const history = getOrCreateGroupHistory(groupId);
+  history.push({ role: 'user', content: prompt });
 
   const fullText = assistantTextParts.join('');
   if (fullText || toolCallsAccum.length > 0) {
@@ -1976,10 +2196,10 @@ function appendTurnToHistory(prompt, assistantTextParts, toolCallsAccum, toolRes
         input: tc.input,
       }));
     }
-    conversationMessages.push(assistantMsg);
+    history.push(assistantMsg);
 
     for (const tr of toolResultsAccum) {
-      conversationMessages.push({
+      history.push({
         role: 'tool',
         toolCallId: tr.toolCallId,
         content: tr.content,
@@ -2070,160 +2290,13 @@ function persistUserMessageOnceByMsgId({ msgId, text, groupId }) {
  */
 const _persistedUserMsgIds = new Set();
 
-/**
- * In-flight compact promise. Set by `scheduleCompactAfterTurn` when a
- * turn ends and triggers compaction; awaited by the next
- * `handleUnifyGroupChat` invocation at its entry gate so the next
- * baseSnapshot reflects the compacted history.
- *
- * Compact runs at turn END (not before fan-out), so it does not add
- * latency to the user's current message. The trade-off: the next user
- * message may have to wait briefly for the compact to finish — but
- * compact uses the fast model and typically completes in 1–3s.
- *
- * @type {Promise<void>|null}
- */
-let _compactInFlight = null;
-
-/**
- * Re-trigger flag. If `scheduleCompactAfterTurn` is called while a
- * compact is already in flight, set this so the in-flight one chains
- * a follow-up immediately on completion. Without this, a sustained
- * burst of turns could starve compaction: turn N triggers compact,
- * turns N+1 / N+2 / … each find `_compactInFlight` set and skip,
- * leaving history above threshold until the burst ends.
- */
-let _compactPending = false;
-
-/**
- * Fire-and-forget post-turn compaction. Called once at the end of each
- * `handleUnifyGroupChat` after `Promise.all(runVpTurn)` resolves. If a
- * compaction is still in flight from an earlier turn, we set
- * `_compactPending` so the running compact chains a follow-up on
- * completion (anti-starvation).
- *
- * The promise is stored in `_compactInFlight` so the next user message
- * can await it before reading `conversationMessages`.
- *
- * @param {string} groupId — for envelope tagging on the emitted event
- */
-function scheduleCompactAfterTurn(groupId) {
-  if (_compactInFlight) {
-    // A compact is already running. Mark a follow-up so when it
-    // finishes, it re-evaluates and runs again if still triggered.
-    _compactPending = true;
-    return;
-  }
-  // Cheap O(n) precheck so we don't bother engaging the LLM at all
-  // when the conversation is still small. Mirrors the policy that
-  // `runCompactNow` will apply: 30K soft floor / 40 % of configured
-  // context / 200K hard ceiling. (The turn-count trigger is off by
-  // default — DEFAULT_TURN_LIMIT=Infinity — pin `turnLimit` via opts
-  // to re-enable it.)
-  const maxContextTokens =
-    typeof session?.config?.maxContextTokens === 'number'
-      ? session.config.maxContextTokens
-      : undefined;
-  const triage = shouldCompactHistory(conversationMessages, { maxContextTokens });
-  if (!triage.trigger) return;
-  if (!session?.engine || typeof session.engine.summarizeForCompact !== 'function') {
-    console.warn('[Unify] history compact: engine.summarizeForCompact unavailable — skipping');
-    return;
-  }
-
-  _compactInFlight = runCompactNow(groupId).finally(() => {
-    _compactInFlight = null;
-    // If turns piled up while we were running and compaction is still
-    // needed, chain a follow-up. Use a microtask so the .finally chain
-    // settles cleanly before the next promise is created.
-    if (_compactPending) {
-      _compactPending = false;
-      queueMicrotask(() => scheduleCompactAfterTurn(groupId));
-    }
-  });
-}
-
-/**
- * Run the in-memory history compactor. Replaces the older prefix of
- * `conversationMessages` with a single user-role summary message,
- * preserving the recent tail verbatim. Mutates the module-level
- * variable in place via reassignment.
- *
- * Behaviour:
- *   - If summarization fails, leaves history untouched.
- *   - On success, emits a `unify_history_compacted` event so dev tools
- *     can show what happened (frontend currently ignores it).
- *
- * Race safety:
- *   - Single-flight via `_compactInFlight` (only one runs at a time).
- *   - Reads the array reference once into `snapshot`. If anything else
- *     reassigns `conversationMessages` during the await (`consolidate`
- *     event from the engine, `clearUnifyMessages`, `resetUnifySession`),
- *     we detect the swap by reference comparison and bail without
- *     overwriting their fresh state.
- *
- * @param {string} groupId
- * @returns {Promise<void>}
- */
-async function runCompactNow(groupId) {
-  const summarize = ({ system, prompt }) =>
-    session.engine.summarizeForCompact({ system, prompt, maxTokens: 1024 });
-
-  // Capture the current array reference. If anyone reassigns
-  // `conversationMessages` while we're summarizing (engine consolidate
-  // event, session reset, manual clear), the reference will differ
-  // and we abandon the swap.
-  const snapshot = conversationMessages;
-
-  // Pull the user-configured context width so the 40 %-of-context
-  // threshold auto-adjusts to whatever model they're on. Falls back to
-  // the module default when missing.
-  const maxContextTokens =
-    typeof session?.config?.maxContextTokens === 'number'
-      ? session.config.maxContextTokens
-      : undefined;
-
-  try {
-    const result = await compactHistory(snapshot, { summarize, maxContextTokens });
-    if (!result.compacted) {
-      if (result.error) {
-        console.warn(
-          `[Unify] history compact: summarizer failed (${result.error}); ` +
-          `keeping ${result.beforeTurns} turns / ~${result.beforeTokens} tokens`
-        );
-      }
-      return;
-    }
-    // Race guard: if `conversationMessages` was reassigned during the
-    // await (e.g. consolidate / reset), do NOT overwrite the fresh
-    // state with our stale compacted snapshot.
-    if (conversationMessages !== snapshot) {
-      console.log('[Unify] history compact: history was reset during compact — discarding stale summary');
-      return;
-    }
-    conversationMessages = result.messages;
-    console.log(
-      `[Unify] history compacted (reason=${result.reason}): ` +
-      `turns ${result.beforeTurns}→${result.afterTurns}, ` +
-      `tokens ~${result.beforeTokens}→${result.afterTokens}, ` +
-      `archived ${result.archivedCount} messages`
-    );
-    try {
-      sendUnifyEvent({
-        type: 'unify_history_compacted',
-        reason: result.reason,
-        beforeTurns: result.beforeTurns,
-        afterTurns: result.afterTurns,
-        beforeTokens: result.beforeTokens,
-        afterTokens: result.afterTokens,
-        archivedCount: result.archivedCount,
-        ts: Date.now(),
-      }, { groupId });
-    } catch { /* WS pipeline failure must not crash compact */ }
-  } catch (err) {
-    console.warn('[Unify] history compact: unexpected failure', err?.message || err);
-  }
-}
+// Per-group post-turn compaction lives on `session.compactor`
+// (`agent/unify/compact/compactor.js`), constructed in `session.js`.
+// Bridge passes a per-call `historyHandle = { get, set }` and wires the
+// `unify_history_compacted` WS sink via `compactor.setOnCompacted` from
+// `installUnifyRuntimeBridge`. The bridge keeps history ownership; the
+// Compactor owns single-flight, anti-starvation, race-guard, and the
+// LLM summarize call.
 
 /**
  * Abort every in-flight VP turn and clear all queued envelopes across
@@ -2593,12 +2666,17 @@ export async function handleUnifyLoadHistory(msg) {
 
     unifyConversationId = `unify-${Date.now()}`;
 
-    restoreHistoryFromRecent(pickRecent(session.conversationStore, undefined));
+    // Per-group history hydrates lazily via getOrCreateGroupHistory.
+    // When the load-history call carries a groupId, force-refresh THAT
+    // group's tape so the next user message sees on-disk state. When
+    // it doesn't (legacy callers), do nothing — the per-group lazy
+    // hydration handles it.
+    if (groupId) setGroupHistory(groupId, hydrateGroupHistory(groupId));
   } else if (groupId) {
     // Re-entering an existing session with a (possibly new) group filter:
-    // re-seed the engine's flat history so it doesn't carry messages from
-    // another group into the next turn's context.
-    restoreHistoryFromRecent(pickRecent(session.conversationStore, undefined));
+    // re-seed THIS group's history from disk so it doesn't carry stale
+    // in-memory state into the next turn's context.
+    setGroupHistory(groupId, hydrateGroupHistory(groupId));
   }
 
   // Always replay session_ready so refresh / reconnect rebuilds UI state.
@@ -2753,7 +2831,9 @@ export async function resetUnifySession() {
     session = null;
   }
   unifyConversationId = null;
-  conversationMessages = [];
+  // Per-group histories live on groupContexts entries — clearing the
+  // map (a few lines below) drops every group's history with it. No
+  // separate global tape to clear.
   // Re-arm the permission warning. The user might have fixed the
   // ~/.yeaft/ permissions in the interim and is now restarting the
   // session — they should see the diagnostic again if it still fails.
@@ -2786,7 +2866,8 @@ export async function resetUnifySession() {
 
     unifyConversationId = `unify-${Date.now()}`;
 
-    restoreHistoryFromRecent(session.conversationStore.loadRecent());
+    // Per-group history hydrates lazily via getOrCreateGroupHistory on
+    // first read. Nothing to seed here.
 
     sendUnifyEvent({
       type: 'session_ready',