@yeaft/webchat-agent 0.1.903 → 0.1.905

package/yeaft/conversation/persist.js

@@ -4,6 +4,14 @@
  * Each message is stored as a .md file with YAML frontmatter in
  * ~/.yeaft/chat/messages/ or ~/.yeaft/groups/<sessionId>/conversation/messages/. Design: zero JSON, all Markdown.
  *
+ * Vocabulary note: the on-disk layout literally uses `groups/<id>/` (and
+ * the AMS registry uses `memory/sessions/<id>/`) — the asymmetry is
+ * deliberate. The `groups/` path predates the rename and we keep it as a
+ * literal string to avoid a destructive data migration; every API
+ * surface above the disk layer (method names, params, comments) uses
+ * "session" vocabulary. See `ConversationStore.#sessionsDir` for the
+ * boundary annotation.
+ *
  * Message format:
  *   ---
  *   id: m0355
@@ -22,7 +30,7 @@ import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rename
 import { join, basename } from 'path';
 import { isPermissionError } from '../init.js';
 import { pairSanitize } from '../pair-sanitize.js';
-import { indexOfNthTurnFromEnd, sliceLastNTurns } from '../turn-utils.js';
+import { countTurns, indexOfNthTurnFromEnd, sliceLastNTurns } from '../turn-utils.js';
 
 /**
  * Default cold-start "recent window" size, expressed in TURNS (not raw
@@ -38,8 +46,94 @@ import { indexOfNthTurnFromEnd, sliceLastNTurns } from '../turn-utils.js';
  * The session-level compactor in `history-compact.js` is the authoritative
  * size limiter once the engine is running; this is just the cold-start
  * replay window after a fresh boot or reconnect.
+ *
+ * Configurable via `~/.yeaft/config.json` → `yeaft.recentTurnsLimit`.
+ * Session boot calls `setDefaultRecentTurnsLimit()` once with the
+ * resolved config value; tests can call it directly.
+ *
+ * NB: this is intentionally `let` (not `const`) and read via
+ * `getDefaultRecentTurnsLimit()` from outside this module — ES module
+ * named exports ARE live bindings, but callers that snapshot the value
+ * at module load (`const cap = DEFAULT_RECENT_TURNS`) would not see
+ * runtime overrides. The reader function makes that always-correct.
  */
-export const DEFAULT_RECENT_TURNS = 20;
+let DEFAULT_RECENT_TURNS = 20;
+
+/** Read the current default cold-start replay window (turn count). */
+export function getDefaultRecentTurnsLimit() {
+  return DEFAULT_RECENT_TURNS;
+}
+
+// Back-compat re-export for callers that grab a snapshot at module load.
+// New code should call `getDefaultRecentTurnsLimit()` so it sees runtime
+// overrides applied by `setDefaultRecentTurnsLimit()`.
+export { DEFAULT_RECENT_TURNS };
+
+/**
+ * Override the default cold-start replay window. Called once per
+ * session boot (`session.js`) from the loaded config. Silently ignores
+ * unparseable input but emits a `console.warn` so a hand-edited config
+ * (`recentTurnsLimit: "twenty"`) doesn't fail open without a signal.
+ *
+ * @param {number|string} n
+ */
+export function setDefaultRecentTurnsLimit(n) {
+  const v = Number(n);
+  if (!Number.isFinite(v) || v < 1) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[Yeaft] setDefaultRecentTurnsLimit(${JSON.stringify(n)}) ignored — ` +
+      `expected a positive number; keeping DEFAULT_RECENT_TURNS=${DEFAULT_RECENT_TURNS}.`
+    );
+    return;
+  }
+  DEFAULT_RECENT_TURNS = Math.floor(v);
+}
+
+/**
+ * Per-session warn-once tracker. Keyed by `${storeDir}::${sessionId}`
+ * so a single process running multiple sessions only warns once per
+ * session per boot.
+ *
+ * The Set is module-level (singleton) because the warning is about
+ * end-user UX (don't spam the console), not about test isolation. Tests
+ * that exercise the warn-once gate call `__resetTruncationWarned()` in
+ * their setup to start from a clean slate; without this seam two
+ * sequential tests in the same module would observe the gate from the
+ * first test silently suppress the second test's warn.
+ */
+const _truncationWarned = new Set();
+
+/** Test-only: clear the warn-once gate (do not call in production). */
+export function __resetTruncationWarned() {
+  _truncationWarned.clear();
+}
+
+/**
+ * Warn (once per session per process) when the cold-start replay window
+ * truncated history AND no compact summary exists to cover the dropped
+ * turns. The user is then losing context with no UX signal otherwise.
+ *
+ * @param {string} sessionId
+ * @param {string} storeDir
+ * @param {number} totalTurns      — turns available on disk
+ * @param {number} returnedTurns   — turns the load returned
+ * @param {boolean} hasCompactSummary
+ */
+function maybeWarnHistoryTruncated(sessionId, storeDir, totalTurns, returnedTurns, hasCompactSummary) {
+  if (!sessionId || !storeDir) return;
+  if (returnedTurns >= totalTurns) return;
+  if (hasCompactSummary) return;
+  const key = `${storeDir}::${sessionId}`;
+  if (_truncationWarned.has(key)) return;
+  _truncationWarned.add(key);
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[Yeaft] history for session ${sessionId} truncated to ${returnedTurns} of ${totalTurns} turns (recentTurnsLimit=${DEFAULT_RECENT_TURNS}); ` +
+    `no compact summary exists, so older context is dropped. ` +
+    `Raise yeaft.recentTurnsLimit in ~/.yeaft/config.json if this is a problem.`
+  );
+}
 
 // ─── Token estimation ────────────────────────────────────────
 
@@ -58,7 +152,7 @@ export function estimateTokens(text) {
 /**
  * Parse the global monotonic sequence number out of a message id of the
  * form `m####`. Returns NaN for malformed ids. Used by the pagination
- * cursor (`loadOlderByGroup`) to compare ids numerically without having
+ * cursor (`loadOlderBySession`) to compare ids numerically without having
  * to trust file-system sort order.
  *
  * @param {string} id
@@ -343,7 +437,12 @@ export function parseMessage(raw) {
 export class ConversationStore {
   #dir;         // root dir (e.g. ~/.yeaft)
   #chatDir;     // ~/.yeaft/chat
-  #groupsDir;   // ~/.yeaft/groups
+  // ~/.yeaft/groups — on-disk path literal kept for backward compat with
+  // existing user data; the live disk layout is still `groups/<id>/` even
+  // after the session-v1 meta migration (which only collapses the meta
+  // files, not the conversation tree). All API surfaces above the disk
+  // layer have been renamed to the "session" vocabulary.
+  #sessionsDir;
   #legacyConvDir; // ~/.yeaft/conversation (read-only compatibility)
   #convDir;     // default thread dir root: ~/.yeaft/chat
   #msgDir;      // default hot messages dir: ~/.yeaft/chat/messages
@@ -356,7 +455,7 @@ export class ConversationStore {
   #chatColdDir;
   #legacyMsgDir;
   #legacyColdDir;
-  #nextSeq;     // next message sequence number across chat/group/legacy
+  #nextSeq;     // next message sequence number across chat/session/legacy
   #nextSeqByThread; // Map<threadId, number> — per-thread counters (task-314)
 
   /**
@@ -365,7 +464,7 @@ export class ConversationStore {
   constructor(dir) {
     this.#dir = dir;
     this.#chatDir = join(dir, 'chat');
-    this.#groupsDir = join(dir, 'groups');
+    this.#sessionsDir = join(dir, 'groups');
     this.#legacyConvDir = join(dir, 'conversation');
 
     this.#convDir = this.#chatDir;
@@ -393,7 +492,7 @@ export class ConversationStore {
     // new versions.
     for (const d of [
       this.#chatDir, join(this.#chatDir, 'blobs'), this.#chatMsgDir, this.#chatColdDir,
-      this.#groupsDir,
+      this.#sessionsDir,
     ]) {
       try {
         if (!existsSync(d)) mkdirSync(d, { recursive: true, mode: 0o755 });
@@ -563,7 +662,7 @@ export class ConversationStore {
    */
   #scopedCompactPath(sessionId, vpId) {
     if (!sessionId || !vpId) return null;
-    const compactDir = join(this.#groupConversationDir(sessionId, { create: true }), 'compact');
+    const compactDir = join(this.#sessionConversationDir(sessionId, { create: true }), 'compact');
     return join(compactDir, `${this.#safeIdComponent(vpId)}.md`);
   }
 
@@ -632,9 +731,9 @@ export class ConversationStore {
    * @param {string} sessionId
    * @returns {boolean}
    */
-  hasAnyCompactSummaryForGroup(sessionId) {
+  hasAnyCompactSummaryForSession(sessionId) {
     if (!sessionId) return false;
-    const compactDir = join(this.#groupConversationDir(sessionId), 'compact');
+    const compactDir = join(this.#sessionConversationDir(sessionId), 'compact');
     for (const dir of [compactDir, this.#legacyCompactScopedDir]) {
       if (!existsSync(dir)) continue;
       try {
@@ -689,7 +788,7 @@ export class ConversationStore {
    * Clear all messages (hot + cold + compact).
    */
   clear() {
-    for (const dir of [this.#chatMsgDir, this.#chatColdDir, ...this.#groupMessageDirs('messages'), ...this.#groupMessageDirs('cold')]) {
+    for (const dir of [this.#chatMsgDir, this.#chatColdDir, ...this.#sessionMessageDirs('messages'), ...this.#sessionMessageDirs('cold')]) {
       if (existsSync(dir)) {
         for (const file of readdirSync(dir)) {
           if (file.endsWith('.md')) {
@@ -786,12 +885,26 @@ export class ConversationStore {
    * @param {number} [turnsLimit=DEFAULT_RECENT_TURNS]
    * @returns {object[]}
    */
-  loadRecentByGroup(sessionId, turnsLimit = DEFAULT_RECENT_TURNS) {
+  loadRecentBySession(sessionId, turnsLimit = DEFAULT_RECENT_TURNS) {
     if (!sessionId) return [];
-    const all = this.#loadGroupMessages(sessionId)
+    const all = this.#loadSessionMessages(sessionId);
     const filtered = all.filter(m => m && m.sessionId === sessionId);
     if (turnsLimit === Infinity || turnsLimit < 0) return pairSanitize(filtered);
-    return pairSanitize(sliceLastNTurns(filtered, turnsLimit));
+    const sliced = sliceLastNTurns(filtered, turnsLimit);
+    // Warn once per (sessionId, storeDir) when truncation drops turns
+    // that no compact summary covers — the user is silently losing
+    // older context otherwise. Cheap check: countTurns is O(N) over
+    // already-loaded messages; we only run it when the slice actually
+    // returned fewer rows than the full filtered set.
+    if (sliced.length < filtered.length) {
+      const totalTurns = countTurns(filtered);
+      const returnedTurns = countTurns(sliced);
+      if (returnedTurns < totalTurns) {
+        const hasCompact = this.hasAnyCompactSummaryForSession(sessionId);
+        maybeWarnHistoryTruncated(sessionId, this.#dir, totalTurns, returnedTurns, hasCompact);
+      }
+    }
+    return pairSanitize(sliced);
   }
 
   /**
@@ -800,8 +913,8 @@ export class ConversationStore {
    * @param {string} sessionId
    * @returns {object[]}
    */
-  loadAllByGroup(sessionId) {
-    return this.loadRecentByGroup(sessionId, Infinity);
+  loadAllBySession(sessionId) {
+    return this.loadRecentBySession(sessionId, Infinity);
   }
 
   /**
@@ -829,9 +942,9 @@ export class ConversationStore {
    * @param {string} vpId
    * @returns {object[]}
    */
-  loadGroupHistoryForVp(sessionId, vpId) {
+  loadSessionHistoryForVp(sessionId, vpId) {
     if (!sessionId || !vpId) return [];
-    const all = this.#loadGroupMessages(sessionId)
+    const all = this.#loadSessionMessages(sessionId);
     const out = [];
     for (const m of all) {
       if (!m || m.sessionId !== sessionId) continue;
@@ -896,15 +1009,15 @@ export class ConversationStore {
    *     from the newest (no upper bound).
    *   - `0` is a VALID finite cutoff that excludes everything (since seqs
    *     start at 1). Distinct from `null`. A caller writing
-   *     `loadOlderByGroup(g, store.firstSeq || 0, ...)` will silently get
+   *     `loadOlderBySession(g, store.firstSeq || 0, ...)` will silently get
    *     an empty page — pass `null` if you mean "from newest".
    * @param {number} [turnsLimit=DEFAULT_RECENT_TURNS] — max turns per page
    * @returns {{ messages: object[], oldestSeq: number|null, hasMore: boolean }}
    */
-  loadOlderByGroup(sessionId, beforeSeq, turnsLimit = DEFAULT_RECENT_TURNS) {
+  loadOlderBySession(sessionId, beforeSeq, turnsLimit = DEFAULT_RECENT_TURNS) {
     if (!sessionId) return { messages: [], oldestSeq: null, hasMore: false };
-    const hot = this.#loadGroupHotMessages(sessionId);
-    const cold = this.#loadGroupColdMessages(sessionId);
+    const hot = this.#loadSessionHotMessages(sessionId);
+    const cold = this.#loadSessionColdMessages(sessionId);
     // Cold ids strictly < hot ids by construction → chronological concat.
     const all = [...cold, ...hot];
     const cutoff = Number.isFinite(beforeSeq) ? beforeSeq : Infinity;
@@ -930,7 +1043,7 @@ export class ConversationStore {
   }
 
   /**
-   * Visible UI pagination read for one group. Unlike `loadOlderByGroup`, this
+   * Visible UI pagination read for one group. Unlike `loadOlderBySession`, this
    * projects out internal/reflection/system rows BEFORE applying the turn
    * window, so a dense run of hidden metadata cannot force the first screen to
    * scan and materialize the group's entire history in the web bridge.
@@ -940,12 +1053,12 @@ export class ConversationStore {
    * @param {number} [turnsLimit=DEFAULT_RECENT_TURNS]
    * @returns {{ messages: object[], oldestSeq: number|null, hasMore: boolean }}
    */
-  loadVisibleByGroup(sessionId, beforeSeq, turnsLimit = DEFAULT_RECENT_TURNS) {
+  loadVisibleBySession(sessionId, beforeSeq, turnsLimit = DEFAULT_RECENT_TURNS) {
     if (!sessionId || !(turnsLimit > 0)) return { messages: [], oldestSeq: null, hasMore: false };
 
     const cutoff = Number.isFinite(beforeSeq) ? beforeSeq : Infinity;
-    const hot = this.#loadVisibleFromDirsByGroup([...this.#groupMessageDirs('messages', sessionId), this.#legacyMsgDir], sessionId, cutoff);
-    const cold = this.#loadVisibleFromDirsByGroup([...this.#groupMessageDirs('cold', sessionId), this.#legacyColdDir], sessionId, cutoff);
+    const hot = this.#loadVisibleFromDirsBySession([...this.#sessionMessageDirs('messages', sessionId), this.#legacyMsgDir], sessionId, cutoff);
+    const cold = this.#loadVisibleFromDirsBySession([...this.#sessionMessageDirs('cold', sessionId), this.#legacyColdDir], sessionId, cutoff);
     const visible = [...cold, ...hot];
     if (visible.length === 0) return { messages: [], oldestSeq: null, hasMore: false };
 
@@ -981,8 +1094,8 @@ export class ConversationStore {
     const limit = Number.isFinite(opts.limit) && opts.limit > 0 ? opts.limit : 500;
     const cutoff = Number.isFinite(afterSeq) && afterSeq >= 0 ? afterSeq : null;
     if (cutoff === null) return { messages: [], latestSeq: null };
-    const hot = this.#loadGroupHotMessages(sessionId);
-    const cold = this.#loadGroupColdMessages(sessionId);
+    const hot = this.#loadSessionHotMessages(sessionId);
+    const cold = this.#loadSessionColdMessages(sessionId);
     const all = [...cold, ...hot].sort(compareMessagesBySeq);
     const after = all.filter((m) => {
       if (!m || m.sessionId !== sessionId) return false;
@@ -1012,7 +1125,7 @@ export class ConversationStore {
    * @returns {number}
    */
   countHot() {
-    return this.#countFilesInDirs([this.#chatMsgDir, ...this.#groupMessageDirs('messages'), this.#legacyMsgDir]);
+    return this.#countFilesInDirs([this.#chatMsgDir, ...this.#sessionMessageDirs('messages'), this.#legacyMsgDir]);
   }
 
   /**
@@ -1021,7 +1134,7 @@ export class ConversationStore {
    * @returns {number}
    */
   countCold() {
-    return this.#countFilesInDirs([this.#chatColdDir, ...this.#groupMessageDirs('cold'), this.#legacyColdDir]);
+    return this.#countFilesInDirs([this.#chatColdDir, ...this.#sessionMessageDirs('cold'), this.#legacyColdDir]);
   }
 
   /**
@@ -1077,7 +1190,7 @@ export class ConversationStore {
   deleteByGroup(sessionId) {
     if (!sessionId) return 0;
     let removed = 0;
-    for (const dir of [this.#chatMsgDir, this.#chatColdDir, ...this.#groupMessageDirs('messages'), ...this.#groupMessageDirs('cold'), this.#legacyMsgDir, this.#legacyColdDir]) {
+    for (const dir of [this.#chatMsgDir, this.#chatColdDir, ...this.#sessionMessageDirs('messages'), ...this.#sessionMessageDirs('cold'), this.#legacyMsgDir, this.#legacyColdDir]) {
       if (!existsSync(dir)) continue;
       let files;
       try {
@@ -1135,7 +1248,7 @@ export class ConversationStore {
     let scanned = 0;
     let removed = 0;
     const orphans = [];
-    for (const dir of [this.#chatMsgDir, this.#chatColdDir, ...this.#groupMessageDirs('messages'), ...this.#groupMessageDirs('cold'), this.#legacyMsgDir, this.#legacyColdDir]) {
+    for (const dir of [this.#chatMsgDir, this.#chatColdDir, ...this.#sessionMessageDirs('messages'), ...this.#sessionMessageDirs('cold'), this.#legacyMsgDir, this.#legacyColdDir]) {
       if (!existsSync(dir)) continue;
       let files;
       try {
@@ -1189,7 +1302,7 @@ export class ConversationStore {
   reassignThread(sourceId, targetId) {
     if (!sourceId || !targetId || sourceId === targetId) return 0;
     let rewritten = 0;
-    for (const dir of [this.#chatMsgDir, this.#chatColdDir, ...this.#groupMessageDirs('messages'), ...this.#groupMessageDirs('cold'), this.#legacyMsgDir, this.#legacyColdDir]) {
+    for (const dir of [this.#chatMsgDir, this.#chatColdDir, ...this.#sessionMessageDirs('messages'), ...this.#sessionMessageDirs('cold'), this.#legacyMsgDir, this.#legacyColdDir]) {
       if (!existsSync(dir)) continue;
       let files;
       try {
@@ -1268,7 +1381,7 @@ export class ConversationStore {
 
     // Collect source-thread candidate files from both hot + cold dirs.
     const candidates = [];
-    for (const dir of [this.#chatColdDir, this.#chatMsgDir, ...this.#groupMessageDirs('cold'), ...this.#groupMessageDirs('messages'), this.#legacyColdDir, this.#legacyMsgDir]) {
+    for (const dir of [this.#chatColdDir, this.#chatMsgDir, ...this.#sessionMessageDirs('cold'), ...this.#sessionMessageDirs('messages'), this.#legacyColdDir, this.#legacyMsgDir]) {
       if (!existsSync(dir)) continue;
       let files;
       try {
@@ -1375,7 +1488,7 @@ export class ConversationStore {
     }
     // Legacy: messages live in the flat dir stamped with threadId.
     const collected = [];
-    for (const dir of [this.#chatColdDir, this.#chatMsgDir, ...this.#groupMessageDirs('cold'), ...this.#groupMessageDirs('messages'), this.#legacyColdDir, this.#legacyMsgDir]) {
+    for (const dir of [this.#chatColdDir, this.#chatMsgDir, ...this.#sessionMessageDirs('cold'), ...this.#sessionMessageDirs('messages'), this.#legacyColdDir, this.#legacyMsgDir]) {
       if (!existsSync(dir)) continue;
       for (const f of readdirSync(dir).filter(x => x.endsWith('.md'))) {
         try {
@@ -1398,7 +1511,7 @@ export class ConversationStore {
   #messageDirFor(msg) {
     if (msg?.chatId) return join(this.#chatConversationDir(msg.chatId, { create: true }), 'messages');
     if (!msg?.sessionId) return this.#chatMsgDir;
-    return join(this.#groupConversationDir(msg.sessionId, { create: true }), 'messages');
+    return join(this.#sessionConversationDir(msg.sessionId, { create: true }), 'messages');
   }
 
   #chatConversationDir(chatId, { create = false } = {}) {
@@ -1462,7 +1575,7 @@ export class ConversationStore {
     }
   }
 
-  /** Recent messages for a chat — chat mode mirror of loadRecentByGroup. */
+  /** Recent messages for a chat — chat mode mirror of loadRecentBySession. */
   loadRecentByChat(chatId, turnsLimit = DEFAULT_RECENT_TURNS) {
     if (!chatId) return [];
     const all = [
@@ -1474,7 +1587,7 @@ export class ConversationStore {
     return pairSanitize(sliceLastNTurns(filtered, turnsLimit));
   }
 
-  /** VP-scoped chat history — chat-mode mirror of loadGroupHistoryForVp. */
+  /** VP-scoped chat history — chat-mode mirror of loadSessionHistoryForVp. */
   loadChatHistoryForVp(chatId, vpId) {
     if (!chatId || !vpId) return [];
     const all = [
@@ -1496,8 +1609,8 @@ export class ConversationStore {
     return pairSanitize(out);
   }
 
-  #groupConversationDir(sessionId, { create = false } = {}) {
-    const dir = join(this.#groupsDir, this.#safeDirComponent(sessionId), 'conversation');
+  #sessionConversationDir(sessionId, { create = false } = {}) {
+    const dir = join(this.#sessionsDir, this.#safeDirComponent(sessionId), 'conversation');
     if (create) this.#ensureConversationDirs(dir);
     return dir;
   }
@@ -1508,11 +1621,11 @@ export class ConversationStore {
     }
   }
 
-  #groupConversationDirs() {
-    if (!existsSync(this.#groupsDir)) return [];
+  #sessionConversationDirs() {
+    if (!existsSync(this.#sessionsDir)) return [];
     const dirs = [];
-    for (const name of readdirSync(this.#groupsDir)) {
-      const sessionDir = join(this.#groupsDir, name);
+    for (const name of readdirSync(this.#sessionsDir)) {
+      const sessionDir = join(this.#sessionsDir, name);
       try {
         if (!statSync(sessionDir).isDirectory()) continue;
       } catch (err) {
@@ -1525,12 +1638,12 @@ export class ConversationStore {
     return dirs;
   }
 
-  #groupMessageDirs(kind, sessionId = null) {
+  #sessionMessageDirs(kind, sessionId = null) {
     if (sessionId) {
-      const dir = join(this.#groupConversationDir(sessionId), kind);
+      const dir = join(this.#sessionConversationDir(sessionId), kind);
       return existsSync(dir) ? [dir] : [];
     }
-    return this.#groupConversationDirs()
+    return this.#sessionConversationDirs()
       .map(dir => join(dir, kind))
       .filter(dir => existsSync(dir));
   }
@@ -1538,7 +1651,7 @@ export class ConversationStore {
   #hotColdDirPairs({ includeLegacy = true } = {}) {
     const pairs = [
       [this.#chatMsgDir, this.#chatColdDir],
-      ...this.#groupConversationDirs().map(dir => [join(dir, 'messages'), join(dir, 'cold')]),
+      ...this.#sessionConversationDirs().map(dir => [join(dir, 'messages'), join(dir, 'cold')]),
     ];
     if (includeLegacy) pairs.push([this.#legacyMsgDir, this.#legacyColdDir]);
     return pairs;
@@ -1554,22 +1667,22 @@ export class ConversationStore {
     ].sort(compareMessagesBySeq);
   }
 
-  #loadGroupHotMessages(sessionId = null) {
+  #loadSessionHotMessages(sessionId = null) {
     return [
       ...this.#loadFromDir(this.#legacyMsgDir, Infinity).filter(m => m?.sessionId),
-      ...this.#groupMessageDirs('messages', sessionId).flatMap(dir => this.#loadFromDir(dir, Infinity)),
+      ...this.#sessionMessageDirs('messages', sessionId).flatMap(dir => this.#loadFromDir(dir, Infinity)),
     ].sort(compareMessagesBySeq);
   }
 
-  #loadGroupColdMessages(sessionId = null) {
+  #loadSessionColdMessages(sessionId = null) {
     return [
       ...this.#loadFromDir(this.#legacyColdDir, Infinity).filter(m => m?.sessionId),
-      ...this.#groupMessageDirs('cold', sessionId).flatMap(dir => this.#loadFromDir(dir, Infinity)),
+      ...this.#sessionMessageDirs('cold', sessionId).flatMap(dir => this.#loadFromDir(dir, Infinity)),
     ].sort(compareMessagesBySeq);
   }
 
-  #loadGroupMessages(sessionId = null) {
-    return [...this.#loadGroupColdMessages(sessionId), ...this.#loadGroupHotMessages(sessionId)].sort(compareMessagesBySeq);
+  #loadSessionMessages(sessionId = null) {
+    return [...this.#loadSessionColdMessages(sessionId), ...this.#loadSessionHotMessages(sessionId)].sort(compareMessagesBySeq);
   }
 
   #loadAllMessages() {
@@ -1578,8 +1691,8 @@ export class ConversationStore {
       ...this.#loadFromDir(this.#legacyMsgDir, Infinity),
       ...this.#loadFromDir(this.#chatColdDir, Infinity),
       ...this.#loadFromDir(this.#chatMsgDir, Infinity),
-      ...this.#groupMessageDirs('cold').flatMap(dir => this.#loadFromDir(dir, Infinity)),
-      ...this.#groupMessageDirs('messages').flatMap(dir => this.#loadFromDir(dir, Infinity)),
+      ...this.#sessionMessageDirs('cold').flatMap(dir => this.#loadFromDir(dir, Infinity)),
+      ...this.#sessionMessageDirs('messages').flatMap(dir => this.#loadFromDir(dir, Infinity)),
     ].sort(compareMessagesBySeq);
   }
 
@@ -1596,8 +1709,8 @@ export class ConversationStore {
     return total;
   }
 
-  #loadVisibleFromDirsByGroup(dirs, sessionId, beforeSeq) {
-    return dirs.flatMap(dir => this.#loadVisibleFromDirByGroup(dir, sessionId, beforeSeq))
+  #loadVisibleFromDirsBySession(dirs, sessionId, beforeSeq) {
+    return dirs.flatMap(dir => this.#loadVisibleFromDirBySession(dir, sessionId, beforeSeq))
       .sort(compareMessagesBySeq);
   }
 
@@ -1659,7 +1772,7 @@ export class ConversationStore {
     return messages;
   }
 
-  #loadVisibleFromDirByGroup(dir, sessionId, beforeSeq) {
+  #loadVisibleFromDirBySession(dir, sessionId, beforeSeq) {
     if (!existsSync(dir)) return [];
 
     const files = readdirSync(dir)
@@ -1693,7 +1806,7 @@ export class ConversationStore {
     if (this.#nextSeq != null) return this.#nextSeq;
 
     let maxSeq = 0;
-    for (const dir of [this.#chatMsgDir, this.#chatColdDir, ...this.#groupMessageDirs('messages'), ...this.#groupMessageDirs('cold'), this.#legacyMsgDir, this.#legacyColdDir]) {
+    for (const dir of [this.#chatMsgDir, this.#chatColdDir, ...this.#sessionMessageDirs('messages'), ...this.#sessionMessageDirs('cold'), this.#legacyMsgDir, this.#legacyColdDir]) {
       if (!existsSync(dir)) continue;
       for (const file of readdirSync(dir)) {
         const match = file.match(/^m(\d+)\.md$/);

package/yeaft/engine.js

@@ -1107,7 +1107,7 @@ export class Engine {
     // Per-(group, vp) scoping: when this engine is bound to a fan-out VP
     // (the common case in group mode), load only the rows THIS VP saw in
     // its context — user prompts + every VP's assistant text, with other
-    // VPs' tool calls/results stripped (see persist.loadGroupHistoryForVp).
+    // VPs' tool calls/results stripped (see persist.loadSessionHistoryForVp).
     //
     // Legacy / sub-agent callers (no sessionId/vpId pair) keep the global
     // loadAll() behaviour so we don't break those flows.
@@ -1115,12 +1115,12 @@ export class Engine {
     const scopedChat = !!(this.#chatId && this.#vpId
       && typeof conversationStore.loadChatHistoryForVp === 'function');
     const scoped = !scopedChat && !!(this.#sessionId && this.#vpId
-      && typeof conversationStore.loadGroupHistoryForVp === 'function');
+      && typeof conversationStore.loadSessionHistoryForVp === 'function');
     try {
       messages = scopedChat
         ? conversationStore.loadChatHistoryForVp(this.#chatId, this.#vpId)
         : scoped
-          ? conversationStore.loadGroupHistoryForVp(this.#sessionId, this.#vpId)
+          ? conversationStore.loadSessionHistoryForVp(this.#sessionId, this.#vpId)
           : conversationStore.loadAll();
     } catch { return null; }
     if (!Array.isArray(messages) || messages.length === 0) return null;

package/yeaft/llm/router.js

@@ -118,7 +118,7 @@ export function filterEffortForModel(params) {
  * task-715: last-line-of-defense pair sanitize at the wire.
  *
  * `pairSanitize` already runs in two upstream paths
- * (`conversation/persist.js#loadRecentByGroup` and
+ * (`conversation/persist.js#loadRecentBySession` and
  * `history-compact.js#compactHistory`), but the engine's main loop
  * mutates `conversationMessages` AFTER those — appending tool results
  * mid-loop, archiving bulky tool results into stubs, and (in failure

package/yeaft/memory/ams-registry.js

@@ -1,15 +1,14 @@
 /**
- * memory/ams-registry.js — group-keyed AMS lifecycle.
+ * memory/ams-registry.js — session-keyed AMS lifecycle.
  *
- * The Active Memory Set is conceptually session-scoped, but Yeaft's
- * unit of "session" is a group: a deactivated group can be reactivated
- * later and should resume with the AMS state it had on disconnect (the
- * onDemand segments it had pulled in, the recent LRU touches, whether
- * `adjust` already ran). Sessions come and go; the group's AMS persists.
+ * The Active Memory Set is conceptually session-scoped, with `sessionId`
+ * as the unit. A deactivated session can be reactivated later and should
+ * resume with the AMS state it had on disconnect (the onDemand segments
+ * it had pulled in, the recent LRU touches, whether `adjust` already ran).
  *
  * Persistence is identity-only:
  *
- *   ~/.yeaft/memory/groups/<sessionId>/ams.json
+ *   ~/.yeaft/memory/sessions/<sessionId>/ams.json
  *   {
  *     "version": 1,
  *     "ownVpId": "alice"|null,
@@ -21,11 +20,11 @@
  *
  * Bodies are NOT serialised — they're re-hydrated from the SegmentIndex
  * on load, so a body edited by Dream after save still surfaces correctly
- * the next time the group is opened. Resident layer is derived state
+ * the next time the session is opened. Resident layer is derived state
  * (rebuilt every turn from `<scope>/summary.md`) — never persisted.
  *
- * For the single-VP Yeaft path (no group), the registry uses the literal
- * key `"default"` so there's still a stable home for AMS state.
+ * For the single-VP Yeaft path (no session id supplied), the registry uses
+ * the literal key `"default"` so there's still a stable home for AMS state.
  */
 
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
@@ -35,7 +34,7 @@ import { ActiveMemorySet } from './ams.js';
 import { computeBudget } from './budget.js';
 
 export const AMS_FILE_VERSION = 1;
-export const DEFAULT_GROUP_KEY = 'default';
+export const DEFAULT_SESSION_KEY = 'default';
 
 /**
  * @typedef {object} AmsRegistryDeps
@@ -80,15 +79,15 @@ export class AmsRegistry {
    *
    * `sessionId` is trusted: `nextSessionId()` (sessions/ids.js) emits ids matching
    * `grp_[a-z0-9_-]+_[0-9A-HJKMNP-TV-Z]{8}` (slug + 8-char crockford suffix),
-   * and the single-VP path uses the literal `DEFAULT_GROUP_KEY`. No defensive
+   * and the single-VP path uses the literal `DEFAULT_SESSION_KEY`. No defensive
    * escaping is needed.
    *
    * @param {string} sessionId
    * @returns {string}
    */
   amsPath(sessionId) {
-    const key = String(sessionId || DEFAULT_GROUP_KEY);
-    return join(this.yeaftDir, 'memory', 'groups', key, 'ams.json');
+    const key = String(sessionId || DEFAULT_SESSION_KEY);
+    return join(this.yeaftDir, 'memory', 'sessions', key, 'ams.json');
   }
 
   /**
@@ -113,7 +112,7 @@ export class AmsRegistry {
    * @returns {ActiveMemorySet}
    */
   getOrCreate(sessionId, opts = {}) {
-    const key = sessionId || DEFAULT_GROUP_KEY;
+    const key = sessionId || DEFAULT_SESSION_KEY;
     const cached = this._cache.get(key);
     if (cached) return cached.ams;
 
@@ -136,7 +135,7 @@ export class AmsRegistry {
    * @returns {boolean}
    */
   adjustRanThisSession(sessionId) {
-    const key = sessionId || DEFAULT_GROUP_KEY;
+    const key = sessionId || DEFAULT_SESSION_KEY;
     return this._cache.get(key)?.adjustRanThisSession === true;
   }
 
@@ -149,7 +148,7 @@ export class AmsRegistry {
    * @param {boolean} value
    */
   setAdjustRanThisSession(sessionId, value) {
-    const key = sessionId || DEFAULT_GROUP_KEY;
+    const key = sessionId || DEFAULT_SESSION_KEY;
     const entry = this._cache.get(key);
     if (entry) entry.adjustRanThisSession = Boolean(value);
   }
@@ -161,7 +160,7 @@ export class AmsRegistry {
    * @param {string|null|undefined} sessionId
    */
   markDirty(sessionId) {
-    this._dirty.add(sessionId || DEFAULT_GROUP_KEY);
+    this._dirty.add(sessionId || DEFAULT_SESSION_KEY);
   }
 
   /**
@@ -177,7 +176,7 @@ export class AmsRegistry {
    * @returns {boolean} true if the file was written
    */
   persist(sessionId, opts = {}) {
-    const key = sessionId || DEFAULT_GROUP_KEY;
+    const key = sessionId || DEFAULT_SESSION_KEY;
     const entry = this._cache.get(key);
     if (!entry) return false;
     if (!opts.force && !this._dirty.has(key)) return false;

package/yeaft/pair-sanitize.js

@@ -3,7 +3,7 @@
  * slice so it can be safely fed to the LLM adapter.
  *
  * Why this exists:
- *   `agent/yeaft/conversation/persist.js#loadRecentByGroup` and
+ *   `agent/yeaft/conversation/persist.js#loadRecentBySession` and
  *   `agent/yeaft/history-compact.js#compactHistory` both produce
  *   sub-slices of a longer message stream. Both paths can — depending on
  *   where the cut lands — produce one of two illegal shapes: