@yeaft/webchat-agent 0.1.805 → 0.1.808

package/package.json

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

package/unify/engine.js

@@ -35,7 +35,8 @@ import { runStopHooks } from './stop-hooks.js';
 // pass a real threadId per (groupId, vpId, threadId) engine instance.
 const MAIN_THREAD_ID = 'main';
 import { pickEffort, parseEffortPrefix } from './effort.js';
-import { normalizeEffort, resolveContextWindow } from './models.js';
+import { DEFAULT_CONTEXT_WINDOW, normalizeEffort, resolveContextWindow, resolveModel } from './models.js';
+import { countTurns } from './turn-utils.js';
 import { attachRouterPlan, extractPriorPlan, stripMetaForWire } from './router/continuity.js';
 import { resolveThinking } from './router/thinking.js';
 import { approxTokens } from './memory/budget.js';
@@ -161,6 +162,51 @@ export function estimateMessagesTokens(system, messages) {
   return total;
 }
 
+export const GROUP_CONTEXT_PRESSURE_RATIO = 0.8;
+export const GROUP_MIN_TURNS_FOR_COMPACT = 5;
+
+export function shouldAllowGroupReflection({
+  system = '',
+  messages = [],
+  model = null,
+  config = {},
+  groupId = null,
+} = {}) {
+  if (!groupId) {
+    return {
+      allowed: true,
+      compactAllowed: true,
+      tokenEstimate: estimateMessagesTokens(system, messages),
+      threshold: 0,
+      contextWindow: null,
+      ratio: GROUP_CONTEXT_PRESSURE_RATIO,
+      turnCount: countTurns(messages),
+      usedFallbackContextWindow: false,
+    };
+  }
+  const contextWindow = resolveContextWindow(model, config);
+  const hasRegistryContext = !!resolveModel(model)?.contextWindow;
+  const hasConfigContext = Number.isFinite(config?.maxContextTokens) && config.maxContextTokens > 0;
+  const threshold = Math.floor(contextWindow * GROUP_CONTEXT_PRESSURE_RATIO);
+  const tokenEstimate = estimateMessagesTokens(system, messages);
+  const overThreshold = tokenEstimate >= threshold;
+  const turnCount = countTurns(messages);
+  return {
+    // Group send defaults to no reflection. Trust the model until context
+    // pressure says we are near the model window.
+    allowed: overThreshold,
+    // Durable compact is also protected for tiny histories: fewer than five
+    // turns do not compact unless they already exceed the same 80% threshold.
+    compactAllowed: overThreshold || turnCount >= GROUP_MIN_TURNS_FOR_COMPACT,
+    tokenEstimate,
+    threshold,
+    contextWindow,
+    ratio: GROUP_CONTEXT_PRESSURE_RATIO,
+    turnCount,
+    usedFallbackContextWindow: !hasRegistryContext && !hasConfigContext && contextWindow === DEFAULT_CONTEXT_WINDOW,
+  };
+}
+
 // ─── Engine Events (superset of adapter events) ──────────────────
 
 /**
@@ -1024,10 +1070,30 @@ export class Engine {
     if (!Array.isArray(messages) || messages.length === 0) return null;
 
     const tokenCount = conversationStore.hotTokens();
+    const groupId = messages.find(m => m && typeof m.groupId === 'string' && m.groupId)?.groupId || null;
+    const groupContextGate = shouldAllowGroupReflection({
+      system: '',
+      messages,
+      model: this.#config.model,
+      config: this.#config,
+      groupId,
+    });
+    if (groupId && groupContextGate?.usedFallbackContextWindow) {
+      this.#trace.log?.('group_context_window_fallback', {
+        groupId,
+        model: this.#config.model,
+        contextWindow: groupContextGate.contextWindow,
+        threshold: groupContextGate.threshold,
+      });
+    }
+    if (groupId && !groupContextGate.compactAllowed) return null;
+
     const trig = evaluateCompactTriggers({
       messages,
       tokenCount,
       contextLimit: this.#config.maxContextTokens || 200000,
+      tokenRatio: groupId ? GROUP_CONTEXT_PRESSURE_RATIO : undefined,
+      maxMessages: groupId ? Number.POSITIVE_INFINITY : undefined,
     });
     if (!trig.trigger) return null;
 
@@ -1358,13 +1424,34 @@ export class Engine {
       { role: 'user', content: finalUserContent },
     ];
 
+    const groupReflectionGate = shouldAllowGroupReflection({
+      system: systemPrompt,
+      messages: conversationMessages,
+      model: this.#config.model,
+      config: this.#config,
+      groupId,
+    });
+    const groupReflectionAllowed = groupReflectionGate.allowed === true;
+    if (groupId && groupReflectionGate?.usedFallbackContextWindow) {
+      this.#trace.log?.('group_context_window_fallback', {
+        groupId,
+        model: this.#config.model,
+        contextWindow: groupReflectionGate.contextWindow,
+        threshold: groupReflectionGate.threshold,
+      });
+    }
+
     // PR-L: T2 carry-forward. If a previous query()'s end-of-turn
     // reflection has resolved, rewrite that turn's range in
     // `conversationMessages` to a single assistant reflection message.
     // If still pending, fall back to the exec-log stub — non-blocking,
     // never wait. This runs BEFORE the first adapter.stream so the
-    // upcoming call sees the rewritten history.
-    yield* this.#applyPendingT2Reflections(conversationMessages, prompt);
+    // upcoming call sees the rewritten history. Group send defaults to no
+    // reflection; only high context pressure (>=80% of model window)
+    // enables the carry-forward rewrite.
+    if (groupReflectionAllowed) {
+      yield* this.#applyPendingT2Reflections(conversationMessages, prompt);
+    }
 
     // PR-L: track this query()'s tool-arc for reflection.
     // `turnStartIdx` is where the current user message lives; the arc
@@ -2022,7 +2109,7 @@ export class Engine {
         // tight-loop retries — but no collapse happened, so T2 should
         // still be allowed to fall back at end_turn. Fowler-review
         // critical finding.
-        if (queryToolCount > TURN_SUMMARY_THRESHOLD && t1CollapsesDone === 0) {
+        if (groupReflectionAllowed && queryToolCount > TURN_SUMMARY_THRESHOLD && t1CollapsesDone === 0) {
           const arcStart = turnStartIdx + 1;
           const arcEnd = conversationMessages.length - 1;
           if (arcEnd > arcStart) {
@@ -2303,7 +2390,7 @@ export class Engine {
       //     batch within the same query gets a distinct entry — without
       //     this the second batch would be silently skipped.
       const t1BatchDue = queryToolCount - lastT1AtToolCount >= TOOL_BATCH_SIZE;
-      if (t1BatchDue && !abortedDuringTools && !signal?.aborted) {
+      if (groupReflectionAllowed && t1BatchDue && !abortedDuringTools && !signal?.aborted) {
         const t1DedupKey = `${queryNumber}:t1:${queryToolCount}`;
         if (this.#reflectedTurns.has(t1DedupKey)) {
           // Defensive: should never hit since t1BatchDue gates re-entry

package/unify/groups/group-config.js

@@ -1,7 +1,7 @@
 /**
- * group-config.js — Per-group configuration overrides.
+ * group-config.js — Per-group selected model state.
  *
- * Each group may carry its own `config.json` at
+ * Each group may carry its header-selected model in `config.json` at
  *   ~/.yeaft/groups/<groupId>/config.json
  *
  * v1 schema (intentionally tiny — extend via additive keys only):
@@ -11,7 +11,7 @@
  *
  * Missing file → empty object. Missing field → fall back to user-level
  * config (`~/.yeaft/config.json` via loadConfig()). Resolution is a
- * shallow overlay (group fields override user fields when truthy).
+ * shallow overlay for send-time effective config.
  *
  * Storage layer only — no engine wiring, no validation of model strings
  * against the provider registry (that's done lazily at resolve time by
@@ -25,7 +25,7 @@ import { groupsRoot, resolveGroupYeaftDir } from './group-crud.js';
 
 const CONFIG_FILE = 'config.json';
 
-/** Whitelist of fields a group may override. Reject everything else. */
+/** Whitelist of persisted group model-state fields. Reject everything else. */
 const ALLOWED_KEYS = new Set(['model']);
 
 export class GroupConfigError extends Error {

package/unify/groups/group-crud.js

@@ -329,7 +329,7 @@ export function updateGroupAnnouncement(yeaftDir, groupId, text) {
 }
 
 /**
- * (A.2.c) Update per-group config overrides (v1: just `model`).
+ * (A.2.c) Persist the model selected in the group conversation header.
  * Returns the persisted config object so the caller can broadcast it.
  *
  * Throws GroupConfigError on validation failure (unknown key, bad type).

package/unify/history-compact.js

@@ -26,10 +26,12 @@
  *   4. Keep the last `keepRecent` user→assistant turns intact so the model
  *      has fresh, untransformed context for whatever the user just said.
  *
- * Triggers (any fires, but only above a 30K token soft floor):
- *   - tokens < 30_000 → never compact (cheap chat, no point paying
+ * Triggers:
+ *   - tokens < 12_000 → never compact (cheap chat, no point paying
  *     the summarizer)
- *   - tokens > 40 % of `maxContextTokens` (defaults to 200K → 80K)
+ *   - fewer than 5 turns → do not compact unless context pressure is
+ *     already high
+ *   - tokens > 80 % of `maxContextTokens` (defaults to 200K → 160K)
  *   - tokens > 200,000 hard ceiling
  *
  * The "turn > 20" trigger that an earlier revision used was dropped:
@@ -72,8 +74,10 @@ export const countTurns = countTurnsImpl;
  *     cost; the LLM hasn't started feeling the context yet either),
  *   - otherwise compact if ANY of:
  *       turnCount > 30           (back-stop for chats with many small turns)
- *       tokens > 40 % of `maxContextTokens` (default 200K → 80K)
+ *       tokens > 80 % of `maxContextTokens` (default 200K → 160K)
  *       tokens > 200K hard ceiling
+ *     Fewer than 5 turns are protected from compact unless the token
+ *     threshold is already crossed.
  *
  * Lowered from 30K → 12K and re-enabled a turn-count back-stop because
  * the previous "soft floor of 30K, no turn cap" combination is dead in
@@ -93,11 +97,13 @@ export const countTurns = countTurnsImpl;
 export const DEFAULT_TURN_LIMIT = 30;
 export const DEFAULT_MIN_TOKEN_FLOOR = 12_000;
 export const DEFAULT_MAX_CONTEXT_TOKENS = 200_000;
-export const DEFAULT_TOKEN_FRACTION = 0.4;
+export const DEFAULT_TOKEN_FRACTION = 0.8;
 export const DEFAULT_HARD_TOKEN_CEILING = 200_000;
+export const DEFAULT_MIN_TURNS_FOR_COMPACT = 5;
+export const DEFAULT_KEEP_TOOL_TURNS = 3;
 /**
  * Effective default token trigger when no `maxContextTokens` is provided:
- *   min(40% of 200K, 200K) = 80K. Preserved as `DEFAULT_TOKEN_LIMIT` for
+ *   min(80% of 200K, 200K) = 160K. Preserved as `DEFAULT_TOKEN_LIMIT` for
  *   back-compat with existing tests that import this name.
  */
 export const DEFAULT_TOKEN_LIMIT = Math.min(
@@ -183,12 +189,13 @@ export function estimateMessagesTokens(messages) {
  * Pure trigger evaluator. Decides whether the in-memory history needs
  * compaction. No I/O, no LLM call.
  *
- * Policy (2026-05-01):
- *   1. tokens < `minTokenFloor` (default 30K) → trigger=false (always).
- *   2. otherwise trigger if ANY of:
- *        turnCount > turnLimit (default Infinity → effectively off;
- *           callers can pin a number to re-enable a turn-count trigger)
- *        tokenCount > maxContextTokens*fraction (reason='token_threshold')
+ * Policy (2026-05-22):
+ *   1. tokens < `minTokenFloor` (default 12K) → trigger=false (always).
+ *   2. fewer than `minTurnsForCompact` turns (default 5) → trigger=false
+ *      unless tokenCount already exceeds the fractional context threshold.
+ *   3. otherwise trigger if ANY of:
+ *        turnCount > turnLimit (default 30 back-stop)
+ *        tokenCount > maxContextTokens*fraction (default 80%, reason='token_threshold')
  *        tokenCount > hardTokenCeiling          (reason='token_ceiling')
  *
  * `tokenLimit` is preserved as a back-compat override for callers /
@@ -198,6 +205,7 @@ export function estimateMessagesTokens(messages) {
  * @param {Array<object>} messages
  * @param {{
  *   turnLimit?: number,
+ *   minTurnsForCompact?: number,
  *   tokenLimit?: number,
  *   minTokenFloor?: number,
  *   maxContextTokens?: number,
@@ -206,7 +214,7 @@ export function estimateMessagesTokens(messages) {
  * }} [opts]
  * @returns {{trigger: boolean, reason: 'turn_count'|'token_threshold'|'token_ceiling'|null,
  *            turnCount: number, tokenCount: number,
- *            turnLimit: number, tokenLimit: number,
+ *            turnLimit: number, tokenLimit: number, minTurnsForCompact: number,
  *            minTokenFloor: number, hardTokenCeiling: number}}
  */
 export function shouldCompactHistory(messages, opts = {}) {
@@ -215,6 +223,7 @@ export function shouldCompactHistory(messages, opts = {}) {
   const hardTokenCeiling = opts.hardTokenCeiling ?? DEFAULT_HARD_TOKEN_CEILING;
   const maxContextTokens = opts.maxContextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS;
   const tokenFraction = opts.tokenFraction ?? DEFAULT_TOKEN_FRACTION;
+  const minTurnsForCompact = opts.minTurnsForCompact ?? DEFAULT_MIN_TURNS_FOR_COMPACT;
   // tokenLimit override wins; otherwise compute fractional threshold.
   const tokenLimit =
     opts.tokenLimit
@@ -225,7 +234,9 @@ export function shouldCompactHistory(messages, opts = {}) {
 
   let reason = null;
   // (1) Soft floor: never compact small conversations.
-  if (tokenCount < minTokenFloor) {
+  // (2) Short-history guard: fewer than five turns should not compact unless
+  //     the estimated prompt is already at the context-pressure threshold.
+  if (tokenCount < minTokenFloor || (turnCount < minTurnsForCompact && tokenCount < tokenLimit)) {
     return {
       trigger: false,
       reason: null,
@@ -233,6 +244,7 @@ export function shouldCompactHistory(messages, opts = {}) {
       tokenCount,
       turnLimit,
       tokenLimit,
+      minTurnsForCompact,
       minTokenFloor,
       hardTokenCeiling,
     };
@@ -240,7 +252,7 @@ export function shouldCompactHistory(messages, opts = {}) {
   // (2) Trigger evaluation. Turn check is opt-in (Infinity by default).
   if (Number.isFinite(turnLimit) && turnCount > turnLimit) reason = 'turn_count';
   else if (tokenCount > hardTokenCeiling) reason = 'token_ceiling';
-  else if (tokenCount > tokenLimit) reason = 'token_threshold';
+  else if (tokenCount >= tokenLimit) reason = 'token_threshold';
 
   return {
     trigger: reason !== null,
@@ -249,11 +261,71 @@ export function shouldCompactHistory(messages, opts = {}) {
     tokenCount,
     turnLimit,
     tokenLimit,
+    minTurnsForCompact,
     minTokenFloor,
     hardTokenCeiling,
   };
 }
 
+function hasContentAfterToolStrip(content) {
+  if (typeof content === 'string') return content.trim().length > 0;
+  if (Array.isArray(content)) return content.length > 0;
+  return content != null;
+}
+
+function stripToolContentParts(content) {
+  if (!Array.isArray(content)) return content;
+  return content.filter(part => {
+    if (!part || typeof part !== 'object') return true;
+    return part.type !== 'tool_use'
+      && part.type !== 'tool_result'
+      && part.type !== 'function_call'
+      && part.type !== 'function_call_output';
+  });
+}
+
+/**
+ * Remove tool-call / tool-result noise from turns older than the recent
+ * lossless window. The last `keepToolTurns` turns keep their full tool
+ * chains; older turns keep user/assistant text but lose `toolCalls`,
+ * Anthropic/OpenAI tool content blocks, and `role:'tool'` messages.
+ *
+ * This is deliberately a wire-history transform, not a summarizer: it
+ * never invents a summary and it never mutates input. Pair-sanitize runs
+ * afterwards so no orphan tool_use/tool_result can survive.
+ *
+ * @param {Array<object>} messages
+ * @param {{ keepToolTurns?: number }} [opts]
+ * @returns {Array<object>}
+ */
+export function stripToolNoiseFromOlderTurns(messages, opts = {}) {
+  if (!Array.isArray(messages) || messages.length === 0) return [];
+  const keepToolTurns = Number.isFinite(opts.keepToolTurns) && opts.keepToolTurns >= 0
+    ? opts.keepToolTurns
+    : DEFAULT_KEEP_TOOL_TURNS;
+  const cutIdx = indexOfNthTurnFromEnd(messages, keepToolTurns);
+  if (cutIdx <= 0) return messages.map(m => ({ ...m }));
+
+  const older = messages.slice(0, cutIdx);
+  const recent = messages.slice(cutIdx);
+  const cleanedOlder = [];
+
+  for (const m of older) {
+    if (!m || typeof m !== 'object') continue;
+    if (m.role === 'tool') continue;
+
+    const next = { ...m };
+    if (Array.isArray(next.toolCalls)) delete next.toolCalls;
+    if (Array.isArray(next.content)) next.content = stripToolContentParts(next.content);
+
+    if (next.role === 'assistant' && !hasContentAfterToolStrip(next.content)) continue;
+    if (next.role === 'user' && Array.isArray(next.content) && next.content.length === 0) continue;
+    cleanedOlder.push(next);
+  }
+
+  return [...cleanedOlder, ...recent.map(m => ({ ...m }))];
+}
+
 /**
  * Strip noise from a message list before sending it to the summarizer:
  *   - drop `role: 'tool'` (raw tool results — too verbose, mostly redundant)
@@ -442,6 +514,7 @@ export async function compactHistory(messages, options) {
     maxContextTokens,
     tokenFraction,
     hardTokenCeiling,
+    minTurnsForCompact: options?.minTurnsForCompact,
   };
   const before = shouldCompactHistory(messages, triggerOpts);
   if (!before.trigger) {
@@ -581,7 +654,7 @@ export async function compactHistory(messages, options) {
  * between trim (per-call) and compact (global) explicit.
  *
  * @param {Array<object>} snapshot
- * @param {{ messageTokenBudget?: number, recentTurnCap?: number }} [opts]
+ * @param {{ messageTokenBudget?: number, recentTurnCap?: number, keepToolTurns?: number }} [opts]
  * @returns {Array<object>}
  */
 export function trimSnapshotForBudget(snapshot, opts = {}) {
@@ -607,6 +680,12 @@ export function trimSnapshotForBudget(snapshot, opts = {}) {
     tokens = estimateMessagesTokens(trimmed);
   }
 
-  // Stage 3: pair-sanitize to drop orphan tool_use/tool_result.
+  // Stage 3: keep only the recent tool chains lossless. Older turns
+  // retain text but drop tool_use/tool_result noise before pair safety.
+  trimmed = stripToolNoiseFromOlderTurns(trimmed, {
+    keepToolTurns: opts.keepToolTurns,
+  });
+
+  // Stage 4: pair-sanitize to drop orphan tool_use/tool_result.
   return pairSanitize(trimmed);
 }

package/unify/turn-utils.js

@@ -45,6 +45,17 @@ export function stripVpMentionPrefix(content) {
   return content.replace(/^@vp-[A-Za-z0-9_-]+\s+/, '');
 }
 
+function canonicalUserTurnContent(content) {
+  if (typeof content === 'string') return stripVpMentionPrefix(content);
+  if (!Array.isArray(content)) return null;
+  const text = content
+    .filter(part => part && typeof part === 'object' && part.type === 'text')
+    .map(part => typeof part.text === 'string' ? part.text : '')
+    .join('\n')
+    .trim();
+  return text ? stripVpMentionPrefix(text) : null;
+}
+
 /**
  * Count "turns" — distinct user prompts after `@vp-X` collapsing.
  *
@@ -62,7 +73,8 @@ export function countTurns(messages) {
   let prev = null;
   for (const m of messages) {
     if (!m || m.role !== 'user') continue;
-    const canonical = stripVpMentionPrefix(m.content || '');
+    const canonical = canonicalUserTurnContent(m.content);
+    if (canonical == null) continue;
     if (canonical !== prev) {
       n++;
       prev = canonical;
@@ -101,7 +113,8 @@ export function indexOfNthTurnFromEnd(messages, n) {
   let candidate = -1;
   for (let i = messages.length - 1; i >= 0; i--) {
     if (!messages[i] || messages[i].role !== 'user') continue;
-    const canonical = stripVpMentionPrefix(messages[i].content || '');
+    const canonical = canonicalUserTurnContent(messages[i].content);
+    if (canonical == null) continue;
     if (canonical !== openCanonical) {
       // Boundary: a new (older) turn starts here.
       turnsFromEnd++;

package/unify/vp/seed-topup.js

@@ -3,17 +3,17 @@
  *
  * Problem: `seedDefaultVps` is first-run-only — once the library has any VP
  * in it, that function never runs again. When we expanded the default roster
- * from 12 to 32 (philosophy, psychology, strategy, history, investing,
- * business, writing, science, arts), existing installs would never see the
- * 20 new VPs without either (a) the user manually deleting their library or
+ * from 12 to 33 (philosophy, psychology, strategy, history, investing,
+ * business, writing, science, arts, Omni), existing installs would never see the
+ * new VPs without either (a) the user manually deleting their library or
  * (b) a forced overwrite that would clobber their hand edits.
  *
  * This module runs on every agent start alongside `seedDefaultVps` and does
  * two minimal, additive things:
  *
- *   1. **Top-up missing default VPs**. If a vpId from `DEFAULT_VPS` is not
- *      on disk AND the user has not explicitly deleted it before (tracked
- *      via `<libDir>/.seeded-versions.json`), `createVp()` it.
+ *   1. **Top-up missing stock VPs**. If a vpId from `DEFAULT_VPS` is not
+ *      on disk, `createVp()` it. This keeps product-owned defaults such as
+ *      Omni and the expanded role roster visible in group/member pickers.
  *
  *   2. **Backfill the `area` frontmatter line** on existing seeded VPs whose
  *      role.md predates the area field. The body is left BYTE-IDENTICAL —
@@ -24,9 +24,9 @@
  * Hard rules:
  *   - **Never** overwrite a VP that is on disk. The user might have edited
  *     persona/role/traits; that is their truth, not ours.
- *   - **Never** recreate a VP the user has deleted. The seed-versions file
- *     remembers "we have seeded this before" — if it's gone now, the user
- *     wants it gone.
+ *   - **Keep stock defaults available.** If a shipped stock VP is missing,
+ *     recreate it, but never overwrite an on-disk VP. The group/member picker
+ *     depends on these product-owned defaults being present.
  *   - Best-effort: any failure is logged, never thrown.
  *
  * Pre-ledger deletion caveat: on the very first top-up against an existing
@@ -34,8 +34,8 @@
  * deleted VP X before the expansion landed" from "X was never seeded." The
  * bootstrap records only on-disk ids as `legacy`; an id the user had deleted
  * BEFORE this code shipped looks identical to a brand-new default and will
- * be recreated once. After that single bootstrap event the ledger is
- * authoritative — any subsequent delete is permanent.
+ * be recreated once. Stock defaults remain authoritative product entries and
+ * may be recreated later if missing; existing files are still never overwritten.
  *
  * Sidecar file: `<libDir>/.seeded-versions.json`
  *
@@ -56,6 +56,7 @@ import { join } from 'path';
 import { createVp, VpCrudError } from './vp-crud.js';
 import { DEFAULT_VP_LIB_DIR, personaHash } from './vp-store.js';
 import { DEFAULT_VPS } from './seed-defaults.js';
+import { STOCK_VP_IDS } from './stock-ids.js';
 
 const SEEDED_VERSIONS_FILE = '.seeded-versions.json';
 const SEEDED_VERSIONS_VERSION = 1;
@@ -319,13 +320,17 @@ export function topUpDefaultVps(libDir = DEFAULT_VP_LIB_DIR) {
       continue;
     }
 
-    if (inLedger) {
-      // We seeded this before, user has since deleted it — respect that.
+    if (inLedger && !STOCK_VP_IDS.has(vpId)) {
+      // We seeded this custom/default VP before, user has since deleted it — respect that.
+      // Stock/default personas are product-owned roster entries and must remain
+      // available in group creation/member pickers after migrations. Recreate
+      // them below without overwriting anything that exists on disk.
       respectedDeletes.push(vpId);
       continue;
     }
 
-    // Missing on disk and never seeded — create it.
+    // Missing on disk and never seeded — or a missing stock VP that must remain available.
+
     try {
       createVp(vp, { libDir });
       versions.seeded[vpId] = personaHash(vp.persona);

package/unify/web-bridge.js

@@ -1416,12 +1416,12 @@ export function handleUnifyUpdateGroup(msg) {
 }
 
 /**
- * Update per-group config overrides (v1: `model`). Cache invalidation:
+ * Persist the model selected in the group conversation header. Cache invalidation:
  * drop every cached Engine whose key starts with `${groupId}::` so the
  * next turn picks up the new model. The group meta itself is untouched.
  *
  * Payload: { groupId, requestId, config: { model?: string|null } }
- *  - `model: ''` or `null` clears the override (group falls back to user default).
+ *  - `model: ''` or `null` clears the selected group model (falls back to user default).
  */
 export function handleUnifyUpdateGroupConfig(msg) {
   const requestId = msg && msg.requestId;