@yeaft/webchat-agent 0.1.874 → 0.1.876

package/yeaft/memory/ams-registry.js

@@ -9,7 +9,7 @@
  *
  * Persistence is identity-only:
  *
- *   ~/.yeaft/memory/groups/<groupId>/ams.json
+ *   ~/.yeaft/memory/groups/<sessionId>/ams.json
  *   {
  *     "version": 1,
  *     "ownVpId": "alice"|null,
@@ -55,9 +55,9 @@ export const DEFAULT_GROUP_KEY = 'default';
  * Group-keyed in-memory cache + disk persistence for AMS instances.
  *
  * Lifecycle:
- *   - getOrCreate(groupId, {ownVpId}) — returns the cached AMS or loads
+ *   - getOrCreate(sessionId, {ownVpId}) — returns the cached AMS or loads
  *     from disk; falls through to a fresh empty AMS on cold start.
- *   - persist(groupId) — writes the current cached AMS to disk.
+ *   - persist(sessionId) — writes the current cached AMS to disk.
  *   - persistAll() — convenience for shutdown.
  *
  * The registry is intentionally narrow: it does not mutate the AMS
@@ -78,15 +78,15 @@ export class AmsRegistry {
   /**
    * Resolve the on-disk path for a group's ams.json.
    *
-   * `groupId` is trusted: `nextGroupId()` (groups/ids.js) emits ids matching
+   * `sessionId` is trusted: `nextSessionId()` (groups/ids.js) emits ids matching
    * `grp_[a-z0-9_-]+`, and the single-VP path uses the literal
    * `DEFAULT_GROUP_KEY`. No defensive escaping is needed.
    *
-   * @param {string} groupId
+   * @param {string} sessionId
    * @returns {string}
    */
-  amsPath(groupId) {
-    const key = String(groupId || DEFAULT_GROUP_KEY);
+  amsPath(sessionId) {
+    const key = String(sessionId || DEFAULT_GROUP_KEY);
     return join(this.yeaftDir, 'memory', 'groups', key, 'ams.json');
   }
 
@@ -107,12 +107,12 @@ export class AmsRegistry {
    * Loads persisted state from disk if any; on cold start returns an
    * empty AMS keyed to the supplied ownVpId.
    *
-   * @param {string|null|undefined} groupId
+   * @param {string|null|undefined} sessionId
    * @param {{ ownVpId?: string|null }} [opts]
    * @returns {ActiveMemorySet}
    */
-  getOrCreate(groupId, opts = {}) {
-    const key = groupId || DEFAULT_GROUP_KEY;
+  getOrCreate(sessionId, opts = {}) {
+    const key = sessionId || DEFAULT_GROUP_KEY;
     const cached = this._cache.get(key);
     if (cached) return cached.ams;
 
@@ -131,11 +131,11 @@ export class AmsRegistry {
    * group. Engine consults this on first AMS access so a reactivated group
    * doesn't re-run `runAdjust` on its first turn back online.
    *
-   * @param {string|null|undefined} groupId
+   * @param {string|null|undefined} sessionId
    * @returns {boolean}
    */
-  adjustRanThisSession(groupId) {
-    const key = groupId || DEFAULT_GROUP_KEY;
+  adjustRanThisSession(sessionId) {
+    const key = sessionId || DEFAULT_GROUP_KEY;
     return this._cache.get(key)?.adjustRanThisSession === true;
   }
 
@@ -144,11 +144,11 @@ export class AmsRegistry {
    * own — call `persist()` to flush). Engine flips this true after
    * `runAdjust` actually ran.
    *
-   * @param {string|null|undefined} groupId
+   * @param {string|null|undefined} sessionId
    * @param {boolean} value
    */
-  setAdjustRanThisSession(groupId, value) {
-    const key = groupId || DEFAULT_GROUP_KEY;
+  setAdjustRanThisSession(sessionId, value) {
+    const key = sessionId || DEFAULT_GROUP_KEY;
     const entry = this._cache.get(key);
     if (entry) entry.adjustRanThisSession = Boolean(value);
   }
@@ -157,10 +157,10 @@ export class AmsRegistry {
    * Mark a group's AMS as dirty so the next persist() actually writes.
    * The engine calls this after `runAdjust` mutates membership.
    *
-   * @param {string|null|undefined} groupId
+   * @param {string|null|undefined} sessionId
    */
-  markDirty(groupId) {
-    this._dirty.add(groupId || DEFAULT_GROUP_KEY);
+  markDirty(sessionId) {
+    this._dirty.add(sessionId || DEFAULT_GROUP_KEY);
   }
 
   /**
@@ -171,12 +171,12 @@ export class AmsRegistry {
    * entry so subsequent `adjustRanThisSession()` reads see the latest flag
    * without a round-trip through disk.
    *
-   * @param {string|null|undefined} groupId
+   * @param {string|null|undefined} sessionId
    * @param {{ force?: boolean, adjustRanThisSession?: boolean }} [opts]
    * @returns {boolean} true if the file was written
    */
-  persist(groupId, opts = {}) {
-    const key = groupId || DEFAULT_GROUP_KEY;
+  persist(sessionId, opts = {}) {
+    const key = sessionId || DEFAULT_GROUP_KEY;
     const entry = this._cache.get(key);
     if (!entry) return false;
     if (!opts.force && !this._dirty.has(key)) return false;

package/yeaft/memory/seed-backfill.js

@@ -150,11 +150,11 @@ export function backfillVpSummaries({ libDir, root = DEFAULT_MEMORY_ROOT }) {
 /**
  * Build a synthetic group summary from group.json on disk.
  *
- * @param {string} groupDir
+ * @param {string} sessionDir
  * @returns {string|null}
  */
-function readGroupSummaryBody(groupDir) {
-  const metaPath = join(groupDir, 'group.json');
+function readGroupSummaryBody(sessionDir) {
+  const metaPath = join(sessionDir, 'group.json');
   if (!existsSync(metaPath)) return null;
   let meta;
   try { meta = JSON.parse(readFileSync(metaPath, 'utf-8')); } catch { return null; }
@@ -236,20 +236,20 @@ export function migrateLegacyVpSummaries({ libDir, root = DEFAULT_MEMORY_ROOT })
 export function backfillGroupSummaries({ yeaftDir, root = DEFAULT_MEMORY_ROOT }) {
   let scanned = 0;
   let seeded = 0;
-  const groupsRoot = join(yeaftDir, 'groups');
-  if (!existsSync(groupsRoot)) return { scanned, seeded };
+  const sessionsRoot = join(yeaftDir, 'sessions');
+  if (!existsSync(sessionsRoot)) return { scanned, seeded };
   let entries;
-  try { entries = readdirSync(groupsRoot); } catch { return { scanned, seeded }; }
+  try { entries = readdirSync(sessionsRoot); } catch { return { scanned, seeded }; }
   for (const name of entries) {
     if (name.startsWith('.')) continue;
-    const groupDir = join(groupsRoot, name);
+    const sessionDir = join(sessionsRoot, name);
     let isDir = false;
-    try { isDir = statSync(groupDir).isDirectory(); } catch { /* skip */ }
+    try { isDir = statSync(sessionDir).isDirectory(); } catch { /* skip */ }
     if (!isDir) continue;
     scanned++;
     const summaryPath = join(root, 'group', name, 'summary.md');
     if (readIfPresent(summaryPath)) continue;
-    const body = readGroupSummaryBody(groupDir);
+    const body = readGroupSummaryBody(sessionDir);
     if (!body) continue;
     try {
       writeAtomicSync(summaryPath, body);

package/yeaft/memory/store-v2.js

@@ -8,7 +8,7 @@
  *   ~/.yeaft/memory/
  *     user/                    memory.md  summary.md
  *     vp/<vpId>/               memory.md  summary.md
- *     group/<groupId>/         memory.md  summary.md
+ *     group/<sessionId>/         memory.md  summary.md
  *     feature/<featureId>/     memory.md  summary.md
  *     topic/<l1>[/<l2>]/       memory.md  summary.md     (≤ 2 levels)
  *
@@ -74,7 +74,7 @@ export const SCOPE_KINDS = Object.freeze([
  * @typedef {Object} Scope
  * @property {ScopeKind} kind
  * @property {string} [id]        — required for group; for group-vp / group-feature the per-kind id
- * @property {string} [groupId]   — required for every group-* kind
+ * @property {string} [sessionId]   — required for every group-* kind
  * @property {string[]} [path]    — required for group-topic; 1–2 segments
  */
 
@@ -98,33 +98,33 @@ export function scopeDir(scope) {
       assertSafeSegment(scope.id, 'group.id');
       return `group/${scope.id}`;
     case 'group-user': {
-      if (!scope.groupId) throw new Error('scopeDir: group-user scope requires groupId');
-      assertSafeSegment(scope.groupId, 'group-user.groupId');
-      return `group/${scope.groupId}/user`;
+      if (!scope.sessionId) throw new Error('scopeDir: group-user scope requires sessionId');
+      assertSafeSegment(scope.sessionId, 'group-user.sessionId');
+      return `group/${scope.sessionId}/user`;
     }
     case 'group-vp': {
-      if (!scope.groupId) throw new Error('scopeDir: group-vp scope requires groupId');
+      if (!scope.sessionId) throw new Error('scopeDir: group-vp scope requires sessionId');
       if (!scope.id) throw new Error('scopeDir: group-vp scope requires id');
-      assertSafeSegment(scope.groupId, 'group-vp.groupId');
+      assertSafeSegment(scope.sessionId, 'group-vp.sessionId');
       assertSafeSegment(scope.id, 'group-vp.id');
-      return `group/${scope.groupId}/vp/${scope.id}`;
+      return `group/${scope.sessionId}/vp/${scope.id}`;
     }
     case 'group-feature': {
-      if (!scope.groupId) throw new Error('scopeDir: group-feature scope requires groupId');
+      if (!scope.sessionId) throw new Error('scopeDir: group-feature scope requires sessionId');
       if (!scope.id) throw new Error('scopeDir: group-feature scope requires id');
-      assertSafeSegment(scope.groupId, 'group-feature.groupId');
+      assertSafeSegment(scope.sessionId, 'group-feature.sessionId');
       assertSafeSegment(scope.id, 'group-feature.id');
-      return `group/${scope.groupId}/feature/${scope.id}`;
+      return `group/${scope.sessionId}/feature/${scope.id}`;
     }
     case 'group-topic': {
-      if (!scope.groupId) throw new Error('scopeDir: group-topic scope requires groupId');
-      assertSafeSegment(scope.groupId, 'group-topic.groupId');
+      if (!scope.sessionId) throw new Error('scopeDir: group-topic scope requires sessionId');
+      assertSafeSegment(scope.sessionId, 'group-topic.sessionId');
       const segs = Array.isArray(scope.path) ? scope.path : [];
       if (segs.length === 0 || segs.length > 2) {
         throw new Error('scopeDir: group-topic.path must have 1 or 2 segments');
       }
       for (const s of segs) assertSafeSegment(s, 'group-topic.path');
-      return `group/${scope.groupId}/topic/${segs.join('/')}`;
+      return `group/${scope.sessionId}/topic/${segs.join('/')}`;
     }
     case 'chat': {
       if (!scope.id) throw new Error('scopeDir: chat scope requires id');
@@ -190,7 +190,7 @@ function assertSafeSegment(s, ctx) {
  */
 export function isValidTopic(scope) {
   if (!scope || scope.kind !== 'group-topic') return false;
-  if (!scope.groupId || typeof scope.groupId !== 'string') return false;
+  if (!scope.sessionId || typeof scope.sessionId !== 'string') return false;
   if (!Array.isArray(scope.path)) return false;
   if (scope.path.length < 1 || scope.path.length > 2) return false;
   for (const s of scope.path) {
@@ -412,7 +412,7 @@ export function seedSummaryIfMissingSync(scope, body, opts = {}) {
 
 /**
  * Synchronously remove a scope's directory under the memory root. Used by
- * `deleteVp` / `deleteGroup` to cascade memory cleanup so a recreate of the
+ * `deleteVp` / `deleteSession` to cascade memory cleanup so a recreate of the
  * same id doesn't see stale `summary.md` / `memory.md` / `segments/` files.
  *
  * Idempotent — missing directory is a no-op.
@@ -460,10 +460,10 @@ export async function ensureScope(scope, opts = {}) {
  * Walks shallowly:
  *   user/                                  → { kind: 'user' }
  *   group/<g>/                             → { kind: 'group', id: g }
- *   group/<g>/user/                        → { kind: 'group-user', groupId: g }
- *   group/<g>/vp/<v>/                      → { kind: 'group-vp', groupId: g, id: v }
- *   group/<g>/feature/<f>/                 → { kind: 'group-feature', groupId: g, id: f }
- *   group/<g>/topic/<l1>[/<l2>]/           → { kind: 'group-topic', groupId: g, path: [...] }
+ *   group/<g>/user/                        → { kind: 'group-user', sessionId: g }
+ *   group/<g>/vp/<v>/                      → { kind: 'group-vp', sessionId: g, id: v }
+ *   group/<g>/feature/<f>/                 → { kind: 'group-feature', sessionId: g, id: f }
+ *   group/<g>/topic/<l1>[/<l2>]/           → { kind: 'group-topic', sessionId: g, path: [...] }
  *
  * Skips `.legacy/` and any dotfile / unsafe segment.
  *
@@ -478,13 +478,13 @@ export async function listScopes(opts = {}) {
   // user/
   if (existsSync(join(root, 'user'))) out.push({ kind: 'user' });
 
-  // group/<g>/...
+  // group/<g>/...  (LEGACY scope tree; kept for un-migrated data)
   const groupRoot = join(root, 'group');
   let groups;
   try { groups = await fsp.readdir(groupRoot, { withFileTypes: true }); }
   catch (err) {
-    if (err && err.code === 'ENOENT') return out;
-    throw err;
+    if (err && err.code === 'ENOENT') groups = [];
+    else throw err;
   }
 
   for (const gent of groups) {
@@ -497,7 +497,7 @@ export async function listScopes(opts = {}) {
 
     // group/<g>/user/
     if (existsSync(join(gAbs, 'user'))) {
-      out.push({ kind: 'group-user', groupId: g });
+      out.push({ kind: 'group-user', sessionId: g });
     }
 
     // group/<g>/vp/<v>/  and  group/<g>/feature/<f>/
@@ -514,7 +514,7 @@ export async function listScopes(opts = {}) {
         if (!isSafeId(ent.name)) continue;
         out.push({
           kind: kind === 'vp' ? 'group-vp' : 'group-feature',
-          groupId: g,
+          sessionId: g,
           id: ent.name,
         });
       }
@@ -540,14 +540,14 @@ export async function listScopes(opts = {}) {
       for (const l2ent of l2s) {
         if (!l2ent.isDirectory()) continue;
         if (!isSafeId(l2ent.name)) continue;
-        out.push({ kind: 'group-topic', groupId: g, path: [l1, l2ent.name] });
+        out.push({ kind: 'group-topic', sessionId: g, path: [l1, l2ent.name] });
         hasL2 = true;
       }
       if (!hasL2) {
         const hasMemory = existsSync(join(l1abs, 'memory.md'));
         const hasSummary = existsSync(join(l1abs, 'summary.md'));
         if (hasMemory || hasSummary) {
-          out.push({ kind: 'group-topic', groupId: g, path: [l1] });
+          out.push({ kind: 'group-topic', sessionId: g, path: [l1] });
         }
       }
     }

package/yeaft/prompts.js

@@ -268,7 +268,7 @@ export function normalizePromptLanguage(language) {
  *
  *   Active Scope params (DESIGN-PROMPT §3 ④):
  *   @param {object} [activeScope] — structured scope summary for this turn
- *   @param {string} [activeScope.groupId]
+ *   @param {string} [activeScope.sessionId]
  *   @param {string} [activeScope.vpId]
  *   @param {object} [activeScope.envelope]          inbound routing info (sender, intent)
  *
@@ -280,7 +280,7 @@ export function normalizePromptLanguage(language) {
  *   skillContent?: string,
  *   activeScope?: object,
  *   vpPersona?: object,
- *   groupAnnouncement?: string,
+ *   sessionAnnouncement?: string,
  *   projectDoc?: string,
  * }} params
  * @returns {string}
@@ -293,7 +293,7 @@ export function buildSystemPrompt({
   skillContent,
   activeScope,
   vpPersona,
-  groupAnnouncement = '',
+  sessionAnnouncement = '',
   projectDoc = '',
 } = {}) {
   // Normalize app locales like `zh-CN` to prompt dictionary/template keys.
@@ -341,7 +341,7 @@ export function buildSystemPrompt({
   // When a group has set an announcement, every VP in the group sees it
   // near the top of the system prompt — before tools, memory, mode-specific
   // instructions. Empty/whitespace = no block emitted.
-  const annText = (typeof groupAnnouncement === 'string') ? groupAnnouncement.trim() : '';
+  const annText = (typeof sessionAnnouncement === 'string') ? sessionAnnouncement.trim() : '';
   if (annText) {
     parts.push(`${lang.groupAnnouncementHeader || '[Group Announcement]'}\n${annText}`);
   }
@@ -482,7 +482,7 @@ function hasCjk(text) {
  *
  * Schema:
  *   ## active_scope
- *   group:   <groupId>               (omitted when missing)
+ *   group:   <sessionId>               (omitted when missing)
  *   vp:      <vpId>                  (omitted when missing)
  *   envelope: from=<sender> intent=<intent>   (omitted when no envelope)
  *
@@ -491,7 +491,7 @@ function hasCjk(text) {
  * with the rest of the Feature system; the JSDoc once described them.)
  *
  * @param {object} [activeScope]
- * @param {string} [activeScope.groupId]
+ * @param {string} [activeScope.sessionId]
  * @param {string} [activeScope.vpId]
  * @param {object} [activeScope.envelope]   inbound routing summary
  * @param {object} lang
@@ -501,8 +501,8 @@ function renderActiveScope(activeScope, lang) {
   if (!activeScope || typeof activeScope !== 'object') return '';
 
   const lines = [];
-  const group = typeof activeScope.groupId === 'string' && activeScope.groupId.trim()
-    ? activeScope.groupId.trim()
+  const group = typeof activeScope.sessionId === 'string' && activeScope.sessionId.trim()
+    ? activeScope.sessionId.trim()
     : '';
   if (group) lines.push(`group: ${group}`);
 
@@ -615,7 +615,7 @@ export function renderLayerASummaries(summaries, language = 'en') {
  * Earlier task-322 / task-334e variants accepted `taskScope` and
  * `turnScope` pass-through strings so callers could append their own
  * scope blocks. DESIGN-PROMPT v1 retired that surface — Active Scope is
- * now structured (`activeScope: { groupId, vpId, envelope }`) and
+ * now structured (`activeScope: { sessionId, vpId, envelope }`) and
  * rendered by `buildSystemPrompt` itself. Both pass-through params
  * had zero remaining callers when v1 landed; removing them prevents the
  * "two ways to describe scope" drift §1 set out to eliminate.

package/yeaft/routing/loop-guard.js

@@ -9,7 +9,7 @@
  *      rejects when the chain length would exceed MAX_CHAIN_DEPTH (10).
  *
  *   2. Rate throttle — within a sliding window (WINDOW_MS = 5000, default
- *      MAX_HITS_PER_WINDOW = 8), a single (groupId, vpId) target may be
+ *      MAX_HITS_PER_WINDOW = 8), a single (sessionId, vpId) target may be
  *      @-forwarded at most N times. On overflow, the forward returns a
  *      `throttled` error and does NOT dispatch. The counter uses a simple
  *      ring (timestamps array) so expired hits are collected on insert.
@@ -19,7 +19,7 @@
  * threat model is one runaway turn storm within a single process tick.
  *
  * Long-running process hygiene (N1, task-334d-followup):
- *   The `hits` Map is keyed by "groupId::vpId" and would otherwise grow
+ *   The `hits` Map is keyed by "sessionId::vpId" and would otherwise grow
  *   unboundedly over a long session. Two complementary bounds:
  *     - TTL sweep: on each NEW key insert, drop entries whose most
  *       recent hit is older than `ttlMultiplier × windowMs` (default 2×).
@@ -36,10 +36,10 @@
  *
  * Integration contract (routing/router.js):
  *   - router stamps envelope.meta.causedBy = [...prevChain, currentMsgId]
- *   - router calls `guard.check({ groupId, targetVpId, chain })` BEFORE
+ *   - router calls `guard.check({ sessionId, targetVpId, chain })` BEFORE
  *     calling coordinator.deliver; on `{ ok: false, reason }` returns a
  *     tool-level error.
- *   - on ok=true, router calls `guard.record({ groupId, targetVpId })` to
+ *   - on ok=true, router calls `guard.record({ sessionId, targetVpId })` to
  *     advance the rate counter.
  */
 
@@ -69,13 +69,13 @@ export function createLoopGuard(options = {}) {
   const ttlMultiplier = options.ttlMultiplier ?? DEFAULT_TTL_MULTIPLIER;
   const now = typeof options.now === 'function' ? options.now : Date.now;
 
-  /** Map<"groupId::vpId", number[]> — sorted ascending timestamps.
+  /** Map<"sessionId::vpId", number[]> — sorted ascending timestamps.
    * Map insertion order doubles as LRU recency: touching (delete+set) on
    * every access keeps the oldest-used entry at the front for eviction. */
   const hits = new Map();
   let evictions = 0;
 
-  function key(groupId, vpId) { return `${groupId}::${vpId}`; }
+  function key(sessionId, vpId) { return `${sessionId}::${vpId}`; }
 
   function trim(arr, cutoff) {
     let i = 0;
@@ -126,15 +126,15 @@ export function createLoopGuard(options = {}) {
 
   return {
     /**
-     * Check whether a forward to (groupId, vpId) with the supplied causedBy
+     * Check whether a forward to (sessionId, vpId) with the supplied causedBy
      * chain is permitted. Does NOT record — call record() after the caller
      * decides to proceed (keeps dry-run / simulation honest).
      *
-     * @param {{ groupId:string, targetVpId:string, chain?:string[] }} args
+     * @param {{ sessionId:string, targetVpId:string, chain?:string[] }} args
      * @returns {{ ok:true } | { ok:false, reason:'chain_depth_exceeded'|'throttled', detail?:any }}
      */
-    check({ groupId, targetVpId, chain = [] }) {
-      if (!groupId || !targetVpId) {
+    check({ sessionId, targetVpId, chain = [] }) {
+      if (!sessionId || !targetVpId) {
         return { ok: false, reason: 'chain_depth_exceeded', detail: { missing: true } };
       }
       if (Array.isArray(chain) && chain.length >= maxChainDepth) {
@@ -144,7 +144,7 @@ export function createLoopGuard(options = {}) {
           detail: { depth: chain.length, limit: maxChainDepth },
         };
       }
-      const k = key(groupId, targetVpId);
+      const k = key(sessionId, targetVpId);
       const arr = hits.get(k);
       if (arr) {
         const cutoff = now() - windowMs;
@@ -164,9 +164,9 @@ export function createLoopGuard(options = {}) {
     },
 
     /** Record a successful forward — advances the rate counter. */
-    record({ groupId, targetVpId }) {
-      if (!groupId || !targetVpId) return;
-      const k = key(groupId, targetVpId);
+    record({ sessionId, targetVpId }) {
+      if (!sessionId || !targetVpId) return;
+      const k = key(sessionId, targetVpId);
       let arr = hits.get(k);
       const creating = !arr;
       if (!arr) {

package/yeaft/routing/router.js

@@ -25,14 +25,14 @@
  *   (d) Tool schema uses defineTool (agent/yeaft/tools/types.js).
  */
 
-import { resolveMemberId } from '../groups/roster.js';
+import { resolveMemberId } from '../sessions/roster.js';
 import { createLoopGuard, extendCausedBy } from './loop-guard.js';
 
 /**
  * Build a router bound to a single GroupCoordinator + loop guard.
  *
  * @param {{
- *   coordinator: import('../groups/coordinator.js').GroupCoordinator,
+ *   coordinator: import('../sessions/coordinator.js').GroupCoordinator,
  *   guard?: ReturnType<typeof createLoopGuard>,
  *   now?: () => number,
  * }} deps
@@ -62,7 +62,7 @@ export function createRouter(deps = {}) {
    *   ok: boolean,
    *   error?: string,
    *   dispatched?: string[],
-   *   report?: import('../groups/coordinator.js').DispatchReport,
+   *   report?: import('../sessions/coordinator.js').DispatchReport,
    * }}
    */
   function forward(args, opts = {}) {
@@ -113,7 +113,7 @@ export function createRouter(deps = {}) {
     // member inboxes.
     const guardKey = targetVpId;
     const verdict = guard.check({
-      groupId: meta.id,
+      sessionId: meta.id,
       targetVpId: guardKey,
       chain,
     });
@@ -157,7 +157,7 @@ export function createRouter(deps = {}) {
     // dispatches (e.g. task.members gate) we still count it as a hit —
     // the forwarder still tried, and the guard's job is to throttle the
     // sender's ability to keep trying.
-    guard.record({ groupId: meta.id, targetVpId: guardKey });
+    guard.record({ sessionId: meta.id, targetVpId: guardKey });
 
     return {
       ok: true,

package/yeaft/session.js

@@ -42,7 +42,7 @@ import { ToolUsageStats } from './stats/tool-usage.js';
 // resumes with the same onDemand/recent membership it had on
 // disconnect. Engine.#runQuery uses the registry to populate the
 // AMS each turn and to run `memory/adjust.js` post-turn.
-import { ensureDefaultGroupIfEmpty } from './groups/group-crud.js';
+import { ensureDefaultSessionIfEmpty } from './sessions/session-crud.js';
 import { seedDefaultVps } from './vp/seed-defaults.js';
 import { topUpDefaultVps } from './vp/seed-topup.js';
 import { runSummaryBackfill, archiveLegacyScopes } from './memory/seed-backfill.js';
@@ -261,7 +261,7 @@ export async function loadSession(options = {}) {
   }
 
   // ─── 5-ams. (GC.1 follow-up) Group-keyed AMS registry ────
-  //     The registry caches one ActiveMemorySet per groupId and
+  //     The registry caches one ActiveMemorySet per sessionId and
   //     persists their state to disk so a deactivated group can be
   //     reactivated with the same onDemand/recent membership it had
   //     on disconnect. Without memoryIndex we have nothing to
@@ -289,7 +289,7 @@ export async function loadSession(options = {}) {
   if (!config._readOnly) {
     // task-337: seed the default VPs (steve, linus, martin, kongzi, buffett, omni, …)
     // on a fresh install so the library is never empty. Idempotent — a no-op
-    // once the user has any VP on disk. Must run BEFORE ensureDefaultGroupIfEmpty
+    // once the user has any VP on disk. Must run BEFORE ensureDefaultSessionIfEmpty
     // so the default group's roster scan sees the seeded VPs. Must also run
     // before any VpLoader.start() (VpLoader is lazy-started in vp-bridge.js
     // on first subscribe, which happens strictly after loadSession returns).
@@ -324,9 +324,9 @@ export async function loadSession(options = {}) {
       console.warn(`[Yeaft] topUpDefaultVps failed: ${err?.message || err}`);
     }
     try {
-      ensureDefaultGroupIfEmpty(yeaftDir, { memoryRoot: join(yeaftDir, 'memory') });
+      ensureDefaultSessionIfEmpty(yeaftDir, { memoryRoot: join(yeaftDir, 'memory') });
     } catch (err) {
-      console.warn(`[Yeaft] ensureDefaultGroupIfEmpty failed: ${err?.message || err}`);
+      console.warn(`[Yeaft] ensureDefaultSessionIfEmpty failed: ${err?.message || err}`);
     }
 
     // task-fix-memory-load: backfill summary.md for VPs / groups created