@yeaft/webchat-agent 0.1.864 → 0.1.866

package/connection/message-router.js

@@ -18,7 +18,7 @@ import {
   handleGitStatus, handleGitDiff, handleGitAdd, handleGitReset, handleGitRestore, handleGitCommit, handleGitPush,
   handleFileSearch, handleCreateFile, handleDeleteFiles, handleMoveFiles, handleCopyFiles, handleUploadToDir, handleTransferFiles
 } from '../workbench.js';
-import { handleListHistorySessions, handleListFolders } from '../history.js';
+import { handleListHistorySessions, handleListFolders, handleListModels } from '../history.js';
 import {
   createConversation, resumeConversation, deleteConversation,
   handleRefreshConversation, handleCancelExecution,
@@ -112,6 +112,10 @@ export async function handleMessage(msg) {
       await handleListFolders(msg);
       break;
 
+    case 'list_models':
+      await handleListModels(msg);
+      break;
+
     case 'transfer_files':
       await handleTransferFiles(msg);
       break;

package/history.js

@@ -252,3 +252,32 @@ export async function handleListFolders(msg) {
     });
   }
 }
+
+// 列出指定 provider 下可选 model
+export async function handleListModels(msg) {
+  const { requestId, _requestClientId, provider } = msg;
+  const providerName = provider || DEFAULT_PROVIDER;
+  try {
+    const driver = getProvider(providerName);
+    let models = [];
+    if (typeof driver.listModels === 'function') {
+      models = await driver.listModels();
+    }
+    ctx.sendToServer({
+      type: 'models_list',
+      requestId,
+      _requestClientId,
+      provider: providerName,
+      models: Array.isArray(models) ? models : [],
+    });
+  } catch (e) {
+    ctx.sendToServer({
+      type: 'models_list',
+      requestId,
+      _requestClientId,
+      provider: providerName,
+      models: [],
+      error: e.message,
+    });
+  }
+}

package/package.json

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

package/providers/copilot-models.js

@@ -1,17 +1,131 @@
 /**
- * Hard-coded known Copilot CLI model IDs. The CLI accepts `--model <id>` but
- * doesn't expose a list over ACP today, so we ship a curated set that maps
- * to what `copilot /model` shows in interactive mode. Add to this list as
- * Copilot publishes new models — no other code change required.
+ * Copilot model list.
+ *
+ * The Copilot CLI accepts `--model <id>` and the agent-facing API exposes
+ * `GET https://api.githubcopilot.com/models` — the same endpoint VS Code's
+ * model picker uses. We hit it on demand (cached in-process for 10 min),
+ * filter to picker-enabled chat models, and fall back to a curated static
+ * list if the network call fails (so the UI never shows an empty picker).
+ *
+ * Auth re-uses the existing `agent/yeaft/llm/credentials/github-copilot.js`
+ * credential pipeline — gh CLI / env / persisted OAuth all work; the user
+ * does not need to paste an API key as long as Copilot CLI is logged in.
  */
-export const COPILOT_MODELS = Object.freeze([
-  { id: 'gpt-5', label: 'GPT-5' },
-  { id: 'gpt-5-mini', label: 'GPT-5 Mini' },
-  { id: 'claude-sonnet-4', label: 'Claude Sonnet 4' },
-  { id: 'claude-sonnet-4.5', label: 'Claude Sonnet 4.5' },
-  { id: 'claude-opus-4', label: 'Claude Opus 4' },
-  { id: 'gpt-4o', label: 'GPT-4o' },
-  { id: 'o1', label: 'o1' },
+
+import { getApiToken, copilotRequestHeaders, validateRawToken, resolveRawToken } from '../yeaft/llm/credentials/github-copilot.js';
+import { readFile } from 'fs/promises';
+import { homedir } from 'os';
+import { join } from 'path';
+
+// Curated fallback — small, but covers the common picks if /models is down or
+// the user has no Copilot auth available yet.
+export const FALLBACK_COPILOT_MODELS = Object.freeze([
+  { id: 'claude-sonnet-4.5',  label: 'Claude Sonnet 4.5', vendor: 'Anthropic' },
+  { id: 'claude-sonnet-4',    label: 'Claude Sonnet 4',   vendor: 'Anthropic' },
+  { id: 'claude-opus-4.1',    label: 'Claude Opus 4.1',   vendor: 'Anthropic' },
+  { id: 'gpt-5',              label: 'GPT-5',             vendor: 'OpenAI'    },
+  { id: 'gpt-5-mini',         label: 'GPT-5 Mini',        vendor: 'OpenAI'    },
+  { id: 'gpt-4.1',            label: 'GPT-4.1',           vendor: 'OpenAI'    },
+  { id: 'gemini-2.5-pro',     label: 'Gemini 2.5 Pro',    vendor: 'Google'    },
 ]);
 
 export const DEFAULT_COPILOT_MODEL = 'claude-sonnet-4.5';
+
+const MODELS_ENDPOINT = 'https://api.githubcopilot.com/models';
+const CACHE_TTL_MS = 10 * 60 * 1000;
+const COPILOT_CLI_CONFIG = join(homedir(), '.copilot', 'config.json');
+
+/**
+ * Last-resort token source: the Copilot CLI itself caches an OAuth token at
+ * ~/.copilot/config.json after `copilot login`. If the standard yeaft
+ * credential pipeline (env / gh CLI / persisted device flow) didn't surface
+ * a token, we re-use the CLI's. Same auth surface — no extra perm needed.
+ */
+async function _resolveCopilotCliToken() {
+  try {
+    const raw = await readFile(COPILOT_CLI_CONFIG, 'utf8');
+    // Copilot CLI's config.json starts with `//` comments. Strip line comments
+    // before JSON.parse — the file otherwise has no string-context `//`.
+    const cleaned = raw.split('\n').filter(l => !l.trim().startsWith('//')).join('\n');
+    const cfg = JSON.parse(cleaned);
+    const tokens = cfg?.copilotTokens && typeof cfg.copilotTokens === 'object' ? cfg.copilotTokens : null;
+    if (!tokens) return null;
+    for (const tok of Object.values(tokens)) {
+      if (typeof tok === 'string' && validateRawToken(tok).valid) return tok;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function _resolveBearerToken() {
+  // The /models endpoint accepts the GitHub OAuth token directly as a Bearer
+  // — no token exchange needed (unlike the chat-completion endpoints). So we
+  // prefer the raw OAuth from the standard yeaft pipeline first, then fall
+  // back to the Copilot CLI's own cached OAuth at ~/.copilot/config.json.
+  try {
+    const raw = await resolveRawToken();
+    if (raw?.token) return raw.token;
+  } catch { /* fall through */ }
+  const cliRaw = await _resolveCopilotCliToken();
+  if (cliRaw) return cliRaw;
+  // Last resort: try exchanged token (works for chat endpoints; may also work
+  // if /models gained that auth path in future).
+  const cred = await getApiToken();
+  return cred?.token || null;
+}
+
+let _cache = null; // { models, fetchedAt }
+let _inflight = null; // dedupes concurrent cold-cache calls
+
+/**
+ * Returns a list of `{id, label, vendor, preview, family}` records,
+ * picker-enabled chat models only. Cached for 10 minutes. Never throws —
+ * falls back to the static list on any error (including network timeout).
+ */
+export async function listCopilotModels({ force = false } = {}) {
+  if (!force && _cache && Date.now() - _cache.fetchedAt < CACHE_TTL_MS) {
+    return _cache.models.slice();
+  }
+  if (_inflight) return (await _inflight).slice();
+  _inflight = (async () => {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), 5000);
+    try {
+      const token = await _resolveBearerToken();
+      if (!token) return FALLBACK_COPILOT_MODELS.slice();
+      const res = await fetch(MODELS_ENDPOINT, {
+        signal: ac.signal,
+        headers: { ...copilotRequestHeaders({ isAgentTurn: false }), Authorization: `Bearer ${token}` },
+      });
+      if (!res.ok) return FALLBACK_COPILOT_MODELS.slice();
+      const body = await res.json();
+      const data = Array.isArray(body?.data) ? body.data : [];
+      const models = data
+        .filter(m => m && m.model_picker_enabled && m.capabilities?.type === 'chat')
+        .map(m => ({
+          id: m.id,
+          label: m.name || m.id,
+          vendor: m.vendor || '',
+          preview: !!m.preview,
+          family: m.capabilities?.family || '',
+        }));
+      if (!models.length) return FALLBACK_COPILOT_MODELS.slice();
+      _cache = { models, fetchedAt: Date.now() };
+      return models.slice();
+    } catch {
+      return FALLBACK_COPILOT_MODELS.slice();
+    } finally {
+      clearTimeout(timer);
+    }
+  })();
+  try {
+    return (await _inflight).slice();
+  } finally {
+    _inflight = null;
+  }
+}
+
+/** Tests only. */
+export function _resetCopilotModelsCacheForTests() { _cache = null; _inflight = null; }

package/providers/copilot.js

@@ -6,7 +6,7 @@ import { join } from 'path';
 import { DatabaseSync } from 'node:sqlite';
 import ctx from '../context.js';
 import { AcpClient } from './acp-client.js';
-import { COPILOT_MODELS, DEFAULT_COPILOT_MODEL } from './copilot-models.js';
+import { listCopilotModels, DEFAULT_COPILOT_MODEL } from './copilot-models.js';
 
 export const name = 'copilot';
 
@@ -582,9 +582,12 @@ function _knownCopilotTools() {
   ];
 }
 
-/** Exported for the model picker UI. */
-export function listModels() {
-  return COPILOT_MODELS.slice();
+/**
+ * Exported for the model picker UI. Async — hits Copilot's /models endpoint
+ * (cached) and falls back to a static list if auth/network fails.
+ */
+export async function listModels() {
+  return await listCopilotModels();
 }
 
 export default { name, capabilities, start, sendInput, abort, clear, listFolders, listSessions, loadHistory, listModels, respondToPermissionRequest };

package/yeaft/init.js

@@ -8,6 +8,9 @@
 import { existsSync, mkdirSync, writeFileSync, accessSync, constants } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
+// NOTE: migrateSessionsV1 is imported by tests directly from
+// './migrate/sessions-v1.js' — not wired into initYeaftDir() yet (Phase 2
+// will activate it once the runtime reads from sessions/).
 
 /**
  * Check if an error is a permission error (EACCES or EPERM).
@@ -78,6 +81,7 @@ const SUBDIRS = [
   'chat/cold',
   'chat/blobs',
   'groups',
+  'sessions',
   'memory/entries',
   'tasks',
   'skills',
@@ -210,5 +214,12 @@ export function initYeaftDir(dir) {
     created.push(mcpExamplePath);
   }
 
+  // NOTE: sessions-v1 migration (collapse groups/ + chats/ → sessions/) is
+  // intentionally NOT wired here yet — Phase 1 ships the session-store +
+  // migration script + scope vocab as foundation only. Activating the
+  // migration before the runtime reads from sessions/ would move data out
+  // from under the live group/chat code paths. Phase 2 flips the runtime
+  // and then hooks `migrateSessionsV1(root)` here.
+
   return { dir: root, created, writable, warnings };
 }

package/yeaft/memory/segment.js

@@ -51,7 +51,7 @@ export const KIND_VALUES = new Set([
   'fact', 'preference', 'decision', 'lesson', 'relation', 'goal', 'context',
 ]);
 
-const SCOPE_RE = /^(user|group\/[\w-]+(?:\/(?:user|vp\/[\w-]+|feature\/[\w-]+|topic\/[\w-]+(?:\/[\w-]+)?))?|chat\/[\w-]+(?:\/vp\/[\w-]+)?)$/;
+const SCOPE_RE = /^(user|group\/[\w-]+(?:\/(?:user|vp\/[\w-]+|feature\/[\w-]+|topic\/[\w-]+(?:\/[\w-]+)?))?|chat\/[\w-]+(?:\/vp\/[\w-]+)?|session\/[\w-]+(?:\/vp\/[\w-]+)?)$/;
 
 /**
  * Compute a stable id from segment content. Same body + scope + kind →

package/yeaft/memory/store-v2.js

@@ -64,9 +64,11 @@ export const SCOPE_KINDS = Object.freeze([
   'group-topic',
   'chat',
   'chat-vp',
+  'session',
+  'session-vp',
 ]);
 
-/** @typedef {'user'|'group'|'group-user'|'group-vp'|'group-feature'|'group-topic'|'chat'|'chat-vp'} ScopeKind */
+/** @typedef {'user'|'group'|'group-user'|'group-vp'|'group-feature'|'group-topic'|'chat'|'chat-vp'|'session'|'session-vp'} ScopeKind */
 
 /**
  * @typedef {Object} Scope
@@ -136,6 +138,18 @@ export function scopeDir(scope) {
       assertSafeSegment(scope.id, 'chat-vp.id');
       return `chat/${scope.chatId}/vp/${scope.id}`;
     }
+    case 'session': {
+      if (!scope.id) throw new Error('scopeDir: session scope requires id');
+      assertSafeSegment(scope.id, 'session.id');
+      return `session/${scope.id}`;
+    }
+    case 'session-vp': {
+      if (!scope.sessionId) throw new Error('scopeDir: session-vp scope requires sessionId');
+      if (!scope.id) throw new Error('scopeDir: session-vp scope requires id');
+      assertSafeSegment(scope.sessionId, 'session-vp.sessionId');
+      assertSafeSegment(scope.id, 'session-vp.id');
+      return `session/${scope.sessionId}/vp/${scope.id}`;
+    }
     default:
       throw new Error(`scopeDir: unknown kind ${JSON.stringify(scope.kind)}`);
   }
@@ -201,7 +215,7 @@ export function isValidTopic(scope) {
  */
 export function isVpForeign(relPath, currentVpId) {
   if (!relPath || !currentVpId) return false;
-  const m = /^(?:group|chat)\/[^/]+\/vp\/([^/]+)(?:\/|$)/.exec(relPath);
+  const m = /^(?:group|chat|session)\/[^/]+\/vp\/([^/]+)(?:\/|$)/.exec(relPath);
   if (!m) return false;
   return m[1] !== currentVpId;
 }
@@ -564,6 +578,31 @@ export async function listScopes(opts = {}) {
     }
   }
 
+  // session/<s>/  and  session/<s>/vp/<v>/
+  const sessionRoot = join(root, 'session');
+  let sessions;
+  try { sessions = await fsp.readdir(sessionRoot, { withFileTypes: true }); }
+  catch (err) {
+    if (err && err.code === 'ENOENT') sessions = [];
+    else throw err;
+  }
+  for (const sent of sessions) {
+    if (!sent.isDirectory()) continue;
+    if (sent.name.startsWith('.')) continue;
+    if (!isSafeId(sent.name)) continue;
+    const s = sent.name;
+    out.push({ kind: 'session', id: s });
+    const vpDir = join(sessionRoot, s, 'vp');
+    let vps;
+    try { vps = await fsp.readdir(vpDir, { withFileTypes: true }); }
+    catch { vps = []; }
+    for (const vent of vps) {
+      if (!vent.isDirectory()) continue;
+      if (!isSafeId(vent.name)) continue;
+      out.push({ kind: 'session-vp', sessionId: s, id: vent.name });
+    }
+  }
+
   return out;
 }
 

package/yeaft/migrate/sessions-v1.js

@@ -0,0 +1,276 @@
+/**
+ * migrate/sessions-v1.js — One-shot migration: collapse groups/ + chats/ → sessions/
+ *
+ * Idempotent. Marks completion with a sentinel file
+ * `<yeaftDir>/.session-migration-v1.done`.
+ *
+ * Migrates:
+ *   1. ~/.yeaft/groups/<g>/         → ~/.yeaft/sessions/<g>/
+ *      group.json → meta.json with shape:
+ *        { id, vpIds: roster, displayName: name, workDir, createdAt,
+ *          lastTurnAt: null, archivedAt? }
+ *   2. ~/.yeaft/chats/<c>/          → ~/.yeaft/sessions/<c>/
+ *      chat.json → meta.json with vpIds: [vpId]
+ *   3. ~/.yeaft/memory/group/<g>/   → ~/.yeaft/memory/session/<g>/
+ *   4. ~/.yeaft/memory/chat/<c>/    → ~/.yeaft/memory/session/<c>/
+ *      Rewrites front-matter `scope:` fields from group/<id> / chat/<id>
+ *      → session/<id>.
+ *   5. ~/.yeaft/memory/groups/<g>/ams.json → ~/.yeaft/memory/sessions/<g>/ams.json
+ *
+ * Collision policy: if `sessions/<x>` already exists, log + skip (we assume
+ * a prior partial run already moved it). If both groups/<x> and chats/<x>
+ * exist with the same id, bail loudly — that shouldn't happen because
+ * group ids are `grp_*` and chat ids are `chat_*`.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs';
+import { join } from 'path';
+
+const SENTINEL = '.session-migration-v1.done';
+
+/**
+ * Run the v1 sessions migration. No-op when sentinel exists.
+ *
+ * @param {string} yeaftDir
+ * @returns {{ migrated: boolean, moved: number, warnings: string[] }}
+ */
+export function migrateSessionsV1(yeaftDir) {
+  const warnings = [];
+  if (!yeaftDir || !existsSync(yeaftDir)) {
+    return { migrated: false, moved: 0, warnings: ['yeaftDir missing'] };
+  }
+  const sentinel = join(yeaftDir, SENTINEL);
+  if (existsSync(sentinel)) {
+    return { migrated: false, moved: 0, warnings: [] };
+  }
+
+  const sessionsRoot = join(yeaftDir, 'sessions');
+  const groupsRoot = join(yeaftDir, 'groups');
+  const chatsRoot = join(yeaftDir, 'chats');
+  const memoryRoot = join(yeaftDir, 'memory');
+  const memSessionRoot = join(memoryRoot, 'session');
+  const memSessionsAmsRoot = join(memoryRoot, 'sessions');
+
+  if (!existsSync(sessionsRoot)) mkdirSync(sessionsRoot, { recursive: true });
+  if (!existsSync(memSessionRoot)) mkdirSync(memSessionRoot, { recursive: true });
+  if (!existsSync(memSessionsAmsRoot)) mkdirSync(memSessionsAmsRoot, { recursive: true });
+
+  // ID collision check
+  const groupIds = listDirs(groupsRoot);
+  const chatIds = listDirs(chatsRoot);
+  const overlap = groupIds.filter((id) => chatIds.includes(id));
+  if (overlap.length > 0) {
+    throw new Error(`sessions migration: id collision between groups/ and chats/: ${overlap.join(',')}`);
+  }
+
+  let moved = 0;
+
+  // 0. Reconcile any half-migrated sessions/<id>/ from a prior crash:
+  // a leftover group.json/chat.json with no meta.json means the rename
+  // succeeded but the rewrite didn't. Repair before moving on so the
+  // session is usable post-migration.
+  for (const id of listDirs(sessionsRoot)) {
+    const dst = join(sessionsRoot, id);
+    if (existsSync(join(dst, 'meta.json'))) continue;
+    if (existsSync(join(dst, 'group.json'))) {
+      rewriteGroupMetaToSessionMeta(dst, warnings);
+      warnings.push(`reconciled partial migration at sessions/${id}`);
+    } else if (existsSync(join(dst, 'chat.json'))) {
+      rewriteChatMetaToSessionMeta(dst, warnings);
+      warnings.push(`reconciled partial migration at sessions/${id}`);
+    }
+  }
+
+  // 1. groups/<g>/ → sessions/<g>/
+  for (const id of groupIds) {
+    const src = join(groupsRoot, id);
+    const dst = join(sessionsRoot, id);
+    if (existsSync(dst)) {
+      // Partial-run reconcile: if meta.json wasn't written yet, retry the
+      // rewrite from the leftover group.json at the destination. Avoids
+      // permanently broken sessions when the prior run crashed between
+      // renameSync and rewriteGroupMetaToSessionMeta.
+      if (!existsSync(join(dst, 'meta.json')) && existsSync(join(dst, 'group.json'))) {
+        rewriteGroupMetaToSessionMeta(dst, warnings);
+        warnings.push(`reconciled partial migration at sessions/${id}`);
+      } else {
+        warnings.push(`sessions/${id} already exists; skipping groups/${id}`);
+      }
+      continue;
+    }
+    renameSync(src, dst);
+    rewriteGroupMetaToSessionMeta(dst, warnings);
+    moved++;
+  }
+
+  // 2. chats/<c>/ → sessions/<c>/
+  for (const id of chatIds) {
+    const src = join(chatsRoot, id);
+    const dst = join(sessionsRoot, id);
+    if (existsSync(dst)) {
+      if (!existsSync(join(dst, 'meta.json')) && existsSync(join(dst, 'chat.json'))) {
+        rewriteChatMetaToSessionMeta(dst, warnings);
+        warnings.push(`reconciled partial migration at sessions/${id}`);
+      } else {
+        warnings.push(`sessions/${id} already exists; skipping chats/${id}`);
+      }
+      continue;
+    }
+    renameSync(src, dst);
+    rewriteChatMetaToSessionMeta(dst, warnings);
+    moved++;
+  }
+
+  // 3+4. memory/{group,chat}/<id>/ → memory/session/<id>/
+  for (const family of ['group', 'chat']) {
+    const root = join(memoryRoot, family);
+    if (!existsSync(root)) continue;
+    for (const id of listDirs(root)) {
+      const src = join(root, id);
+      const dst = join(memSessionRoot, id);
+      if (existsSync(dst)) {
+        warnings.push(`memory/session/${id} already exists; skipping memory/${family}/${id}`);
+        continue;
+      }
+      renameSync(src, dst);
+      rewriteSegmentScopes(dst, family, id, warnings);
+    }
+  }
+
+  // 5. memory/groups/<g>/ams.json → memory/sessions/<g>/ams.json
+  const amsGroupRoot = join(memoryRoot, 'groups');
+  if (existsSync(amsGroupRoot)) {
+    for (const id of listDirs(amsGroupRoot)) {
+      const srcDir = join(amsGroupRoot, id);
+      const dstDir = join(memSessionsAmsRoot, id);
+      if (existsSync(dstDir)) {
+        warnings.push(`memory/sessions/${id} already exists; skipping memory/groups/${id}`);
+        continue;
+      }
+      renameSync(srcDir, dstDir);
+    }
+  }
+  const amsChatRoot = join(memoryRoot, 'chats');
+  if (existsSync(amsChatRoot)) {
+    for (const id of listDirs(amsChatRoot)) {
+      const srcDir = join(amsChatRoot, id);
+      const dstDir = join(memSessionsAmsRoot, id);
+      if (existsSync(dstDir)) {
+        warnings.push(`memory/sessions/${id} already exists; skipping memory/chats/${id}`);
+        continue;
+      }
+      renameSync(srcDir, dstDir);
+    }
+  }
+
+  // 6. sentinel
+  //
+  // PHASE 2 TODO: the SQLite FTS index (memory/index-db.js) still has rows
+  // pointing at group/<id> and chat/<id> scopes after this migration. When
+  // Phase 2 activates this migration from initYeaftDir(), it MUST also
+  // delete or rebuild the FTS index so the new session/<id> scopes get
+  // re-indexed. Preflow recall is broken until then.
+  writeFileSync(sentinel, JSON.stringify({
+    version: 1,
+    migratedAt: new Date().toISOString(),
+    moved,
+    warnings,
+  }, null, 2), 'utf8');
+
+  return { migrated: true, moved, warnings };
+}
+
+function listDirs(root) {
+  if (!root || !existsSync(root)) return [];
+  const out = [];
+  for (const name of readdirSync(root)) {
+    if (name.startsWith('.')) continue;
+    try {
+      if (statSync(join(root, name)).isDirectory()) out.push(name);
+    } catch { /* ignore */ }
+  }
+  return out;
+}
+
+function rewriteGroupMetaToSessionMeta(sessionDir, warnings) {
+  const oldPath = join(sessionDir, 'group.json');
+  const newPath = join(sessionDir, 'meta.json');
+  if (!existsSync(oldPath)) {
+    if (!existsSync(newPath)) warnings.push(`no group.json in ${sessionDir}`);
+    return;
+  }
+  try {
+    const raw = JSON.parse(readFileSync(oldPath, 'utf8'));
+    const meta = {
+      id: raw.id,
+      displayName: raw.name || raw.id,
+      vpIds: Array.isArray(raw.roster) && raw.roster.length > 0 ? raw.roster.slice() : ['omni'],
+      // Preserve defaultVpId so Phase 2 coordinator can resolve "which VP
+      // answers when no @-mention". Easy to keep now, hard to backfill later.
+      ...(raw.defaultVpId ? { defaultVpId: raw.defaultVpId } : {}),
+      workDir: typeof raw.workDir === 'string' ? raw.workDir : '',
+      createdAt: raw.createdAt || new Date().toISOString(),
+      lastTurnAt: null,
+    };
+    writeFileSync(newPath, JSON.stringify(meta, null, 2), 'utf8');
+    try { unlinkSync(oldPath); } catch { /* keep both if cannot delete */ }
+  } catch (err) {
+    warnings.push(`failed to rewrite ${oldPath}: ${err.message}`);
+  }
+}
+
+function rewriteChatMetaToSessionMeta(sessionDir, warnings) {
+  const oldPath = join(sessionDir, 'chat.json');
+  const newPath = join(sessionDir, 'meta.json');
+  if (!existsSync(oldPath)) {
+    if (!existsSync(newPath)) warnings.push(`no chat.json in ${sessionDir}`);
+    return;
+  }
+  try {
+    const raw = JSON.parse(readFileSync(oldPath, 'utf8'));
+    const meta = {
+      id: raw.id,
+      displayName: raw.displayName || raw.id,
+      vpIds: [raw.vpId || 'omni'],
+      workDir: typeof raw.workDir === 'string' ? raw.workDir : '',
+      createdAt: raw.createdAt || new Date().toISOString(),
+      lastTurnAt: raw.lastTurnAt || null,
+    };
+    writeFileSync(newPath, JSON.stringify(meta, null, 2), 'utf8');
+    try { unlinkSync(oldPath); } catch { /* */ }
+  } catch (err) {
+    warnings.push(`failed to rewrite ${oldPath}: ${err.message}`);
+  }
+}
+
+function rewriteSegmentScopes(sessionMemoryDir, oldFamily, id, warnings) {
+  const segDir = join(sessionMemoryDir, 'segments');
+  if (!existsSync(segDir)) return;
+  let entries;
+  try { entries = readdirSync(segDir); } catch { return; }
+  const re = new RegExp(`^(\\s*scope:\\s*)${oldFamily}/${escapeRe(id)}\\b`, 'gm');
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue;
+    const path = join(segDir, name);
+    try {
+      const src = readFileSync(path, 'utf8');
+      const next = src.replace(re, `$1session/${id}`);
+      if (next !== src) writeFileSync(path, next, 'utf8');
+    } catch (err) {
+      warnings.push(`segment rewrite failed ${path}: ${err.message}`);
+    }
+  }
+}
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/yeaft/sessions/coordinator.js

@@ -0,0 +1,145 @@
+/**
+ * sessions/coordinator.js — Session Coordinator.
+ *
+ * Ported from groups/coordinator.js as part of the chat+group → session
+ * unification. Persists envelopes to a SessionHandle's jsonl-log and
+ * dispatches user-text turns to target VPs via pre-flow's selection
+ * matrix.
+ *
+ * N=1 (the old "chat") and N>1 (the old "group") are handled by the same
+ * logic — chat is just the degenerate case where pre-flow's @-mention
+ * matrix always falls back to the lone roster member.
+ *
+ * This module does NOT run the engine. It only:
+ *   1. Persists the message (via SessionHandle.appendMessage)
+ *   2. Asks pre-flow which VPs should respond
+ *   3. Calls deliver(vpId, envelope) per target
+ */
+
+import { parseMentions, selectRespondingVps } from './pre-flow.js';
+
+export { parseMentions };
+
+/**
+ * @param {import('./session-store.js').SessionHandle} sessionHandle
+ * @param {{ deliver?: (vpId:string, envelope:any) => void, perGroupFanOut?: number }} [options]
+ */
+export function createCoordinator(sessionHandle, options = {}) {
+  const deliver = options.deliver || (() => {});
+  const fanOutCap = options.perGroupFanOut ?? 16;
+
+  function ingest(input, opts = {}) {
+    if (!input || typeof input !== 'object') {
+      throw new Error('ingest: input required');
+    }
+    if (typeof input.text !== 'string') {
+      throw new Error('ingest: input.text required (string)');
+    }
+    const meta = sessionHandle.getMeta();
+    if (!meta) throw new Error('session not initialised (call createSession first)');
+
+    const isRouteForwardInjection = input?.meta?.injectedBy === 'route_forward';
+    const fromUser = input.from === 'user'
+      || input.role === 'user'
+      || isRouteForwardInjection;
+    const mentions = parseMentions(input.text);
+
+    const persistInput = {};
+    const ephemeral = {};
+    for (const [k, v] of Object.entries(input)) {
+      if (typeof k === 'string' && k.startsWith('_')) {
+        ephemeral[k] = v;
+      } else {
+        persistInput[k] = v;
+      }
+    }
+    {
+      const leaked = Object.keys(persistInput).filter((k) => typeof k === 'string' && k.startsWith('_'));
+      if (leaked.length > 0) {
+        throw new Error(`coordinator.ingest: ephemeral fields leaked into persisted record: ${leaked.join(', ')}`);
+      }
+    }
+    const stored = sessionHandle.appendMessage({
+      ...persistInput,
+      mentions,
+      role: input.role || (fromUser ? 'user' : 'assistant'),
+    });
+
+    const selection = selectRespondingVps({
+      meta,
+      fromUser,
+      mentions,
+      sender: input.from,
+      fanOutCap,
+      taskMembers: opts.taskMembers,
+    });
+
+    if (selection.reason === 'vp-author-no-text-routing') {
+      return {
+        message: stored,
+        dispatched: [],
+        fallback: null,
+        errors: [],
+        skipped: 'vp-author-no-text-routing',
+      };
+    }
+
+    if (selection.reason === 'broadcast') {
+      const envelope = makeEnvelope(stored, meta, 'broadcast', ephemeral);
+      for (const vpId of selection.dispatched) deliver(vpId, envelope);
+      return {
+        message: stored,
+        dispatched: selection.dispatched,
+        fallback: null,
+        errors: selection.errors,
+        broadcast: true,
+        truncatedAtFanOutCap: !!selection.truncatedAtFanOutCap,
+      };
+    }
+
+    if (selection.reason === 'mention') {
+      for (const vpId of selection.dispatched) {
+        deliver(vpId, makeEnvelope(stored, meta, 'mention', ephemeral));
+      }
+      return {
+        message: stored,
+        dispatched: selection.dispatched,
+        fallback: null,
+        errors: selection.errors,
+      };
+    }
+
+    if (selection.reason === 'fallback' && selection.fallback) {
+      deliver(selection.fallback, makeEnvelope(stored, meta, 'fallback', ephemeral));
+      return {
+        message: stored,
+        dispatched: selection.dispatched,
+        fallback: selection.fallback,
+        errors: selection.errors,
+      };
+    }
+
+    return {
+      message: stored,
+      dispatched: [],
+      fallback: null,
+      errors: selection.errors,
+    };
+  }
+
+  return {
+    session: sessionHandle,
+    ingest,
+    parseMentions,
+  };
+}
+
+function makeEnvelope(msg, meta, trigger, ephemeral = {}) {
+  return {
+    sessionId: meta.id,
+    taskId: msg.taskId || null,
+    msg,
+    trigger,
+    ...ephemeral,
+  };
+}

package/yeaft/sessions/pre-flow.js

@@ -0,0 +1,212 @@
+/**
+ * sessions/pre-flow.js — explicit pre-flow stage for Yeaft (session-scoped).
+ *
+ * Ported from groups/pre-flow.js as part of the chat+group → session
+ * unification. Scope strings use the unified `session/<id>` /
+ * `session/<id>/vp/<vp>` shape instead of the legacy
+ * `group/<g>` / `chat/<c>` shapes.
+ *
+ * NOTE: the old groups/pre-flow.js is still in place — callers (web-bridge,
+ * coordinator) will switch over in Phase A6/A7. Do not delete the old file
+ * until every importer has been migrated.
+ */
+
+import { runPreflow as runFtsPreflow } from '../memory/preflow.js';
+
+/** Matches `@vp-id` where id is [A-Za-z0-9_-]+. Captures the id. */
+const MENTION_RE = /(^|\s)@([A-Za-z0-9_][A-Za-z0-9_-]*)/g;
+
+export function parseMentions(text) {
+  if (!text || typeof text !== 'string') return [];
+  const out = [];
+  const seen = new Set();
+  MENTION_RE.lastIndex = 0;
+  let m;
+  while ((m = MENTION_RE.exec(text))) {
+    const id = m[2];
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+
+/**
+ * Pure VP-selection for a session. Returns the list of VP ids that should
+ * respond to a user turn — mention / @all / fallback to first roster
+ * member. (Sessions have no `defaultVpId` field; the first VP in `vpIds`
+ * is the fallback.)
+ *
+ * @param {{
+ *   meta: { id: string, vpIds: string[] },
+ *   fromUser: boolean,
+ *   mentions: string[],
+ *   sender?: string,
+ *   fanOutCap?: number,
+ *   taskMembers?: string[],
+ * }} input
+ */
+export function selectRespondingVps(input) {
+  const meta = input?.meta;
+  if (!meta) {
+    return { dispatched: [], fallback: null, errors: [{ error: 'no_session_meta' }], reason: 'no-default' };
+  }
+  const fanOutCap = Number.isFinite(input.fanOutCap) ? input.fanOutCap : 16;
+  const taskMembers = Array.isArray(input.taskMembers) ? input.taskMembers : null;
+  const mentions = Array.isArray(input.mentions) ? input.mentions : [];
+  const roster = Array.isArray(meta.vpIds) ? meta.vpIds : [];
+
+  if (!input.fromUser) {
+    return {
+      dispatched: [],
+      fallback: null,
+      errors: [],
+      reason: 'vp-author-no-text-routing',
+    };
+  }
+
+  if (mentions.includes('all')) {
+    const expanded = roster.filter((v) => v !== input.sender).slice(0, fanOutCap);
+    const scoped = taskMembers ? expanded.filter((v) => taskMembers.includes(v)) : expanded;
+    return {
+      dispatched: scoped,
+      fallback: null,
+      errors: [],
+      reason: 'broadcast',
+      truncatedAtFanOutCap: roster.length - 1 > fanOutCap,
+    };
+  }
+
+  if (mentions.length > 0) {
+    const dispatched = [];
+    const errors = [];
+    for (const vpId of mentions) {
+      if (!roster.includes(vpId)) {
+        errors.push({ vpId, error: 'not_in_roster' });
+        continue;
+      }
+      if (taskMembers && !taskMembers.includes(vpId)) {
+        errors.push({ vpId, error: 'not_in_task_members' });
+        continue;
+      }
+      if (!dispatched.includes(vpId)) dispatched.push(vpId);
+    }
+    return { dispatched, fallback: null, errors, reason: 'mention' };
+  }
+
+  const fallback = roster[0] || null;
+  if (!fallback) {
+    return {
+      dispatched: [],
+      fallback: null,
+      errors: [{ error: 'no_default_vp' }],
+      reason: 'no-default',
+    };
+  }
+  if (taskMembers && !taskMembers.includes(fallback)) {
+    return {
+      dispatched: [],
+      fallback: null,
+      errors: [{ vpId: fallback, error: 'not_in_task_members' }],
+      reason: 'no-default',
+    };
+  }
+  return {
+    dispatched: [fallback],
+    fallback,
+    errors: [],
+    reason: 'fallback',
+  };
+}
+
+function scopeHeading(scope) {
+  if (scope === 'user') return '## Memory: User';
+  let m = /^session\/([^/]+)\/vp\/(.+)$/.exec(scope);
+  if (m) return `## Memory: VP ${m[2]}`;
+  m = /^session\/([^/]+)$/.exec(scope);
+  if (m) return `## Memory: Session ${m[1]}`;
+  if (scope.startsWith('vp/')) return `## Memory: VP ${scope.slice(3)}`;
+  return `## Memory: ${scope}`;
+}
+
+export function formatPickedForInjection(picked) {
+  if (!picked || picked.length === 0) return '';
+  const byScope = new Map();
+  for (const seg of picked) {
+    const scope = seg.scope || 'unknown';
+    if (!byScope.has(scope)) byScope.set(scope, []);
+    byScope.get(scope).push(seg);
+  }
+  const parts = [];
+  for (const [scope, segs] of byScope.entries()) {
+    parts.push(scopeHeading(scope));
+    for (const s of segs) {
+      const body = (s.body || '').trim();
+      if (body) parts.push(body);
+    }
+    parts.push('');
+  }
+  return parts.join('\n').trim();
+}
+
+/**
+ * Canonical scope list for a session VP turn:
+ *   ['user', 'session/<id>', 'session/<id>/vp/<vp>']
+ *
+ * @param {{ sessionId?: string, vpId?: string, extra?: string[] }} ctx
+ */
+export function buildRelevantScopes({ sessionId, vpId, extra } = {}) {
+  const scopes = ['user'];
+  if (sessionId) {
+    scopes.push(`session/${sessionId}`);
+    if (vpId) scopes.push(`session/${sessionId}/vp/${vpId}`);
+  }
+  if (Array.isArray(extra)) {
+    for (const s of extra) {
+      if (s && !scopes.includes(s)) scopes.push(s);
+    }
+  }
+  return scopes;
+}
+
+export function runMemoryPreflow(index, opts) {
+  if (!index) {
+    return { profile: '', entries: [], formatted: '', meta: { skipped: 'no-index' } };
+  }
+  const userMsg = (opts?.userMsg || '').trim();
+  if (!userMsg) {
+    return { profile: '', entries: [], formatted: '', meta: { skipped: 'no-user-msg' } };
+  }
+
+  const relevantScopes = buildRelevantScopes({
+    sessionId: opts.sessionId,
+    vpId: opts.vpId,
+    extra: opts.extraScopes,
+  });
+
+  const result = runFtsPreflow(index, {
+    userMsg,
+    relevantScopes,
+    ownVpId: opts.vpId || null,
+    currentTags: opts.currentTags || [],
+    topK: opts.topK,
+    budgetTokens: opts.budgetTokens,
+  });
+
+  const userSeg = (result.picked || []).find((p) => p.scope === 'user');
+  const profile = userSeg ? (userSeg.body || '').trim() : '';
+  const formatted = formatPickedForInjection(result.picked || []);
+
+  return {
+    profile,
+    entries: result.picked || [],
+    formatted,
+    meta: {
+      keywords: result.keywords,
+      ftsQuery: result.ftsQuery,
+      pickedTokens: result.pickedTokens,
+      droppedCount: result.droppedCount,
+      hitCount: (result.hits || []).length,
+    },
+  };
+}

package/yeaft/sessions/session-store.js

@@ -0,0 +1,281 @@
+/**
+ * session-store.js — Per-session persistent store (collapses group + chat).
+ *
+ * Layout:
+ *   ~/.yeaft/sessions/<sessionId>/
+ *     meta.json   # { sessionId, vpIds[], displayName, workDir, createdAt, lastTurnAt, archivedAt? }
+ *     messages/   # JSONL size-rotation log (storage/openLog)
+ *       000001.jsonl
+ *       index.json
+ *
+ * A session has N≥1 VPs. N=1 is the old "chat"; N>1 is the old "group".
+ * The coordinator fan-out is identical for both — N=1 just resolves to
+ * one VP turn per ingest.
+ *
+ * Hard constraint: no @-mention parsing, no dispatch, no engine awareness.
+ * Pure persistence.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+} from 'fs';
+import { join } from 'path';
+import { writeAtomic, openLog } from '../storage/index.js';
+import {
+  nextMsgId,
+  isReservedVpId,
+  ReservedVpIdError,
+  validateVpId,
+  InvalidVpIdError,
+} from '../groups/ids.js';
+
+const META_FILE = 'meta.json';
+const MESSAGES_DIR = 'messages';
+const SESSION_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/**
+ * Open (or partially create) the directory for a session. Returns a handle
+ * even when meta.json is absent — call createSession() to materialise it.
+ *
+ * @param {string} sessionsRoot
+ * @param {string} sessionId
+ * @returns {SessionHandle}
+ */
+export function openSession(sessionsRoot, sessionId) {
+  if (!sessionId || typeof sessionId !== 'string') {
+    throw new Error('openSession: sessionId required (string)');
+  }
+  if (!SESSION_ID_RE.test(sessionId)) {
+    throw new Error(`openSession: invalid sessionId "${sessionId}"`);
+  }
+  const dir = join(sessionsRoot, sessionId);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  let meta = loadSessionMeta(dir);
+
+  const messagesDir = join(dir, MESSAGES_DIR);
+  if (!existsSync(messagesDir)) mkdirSync(messagesDir, { recursive: true });
+  const log = openLog(messagesDir);
+
+  return {
+    dir,
+    id: sessionId,
+    getMeta() { return meta ? structuredClone(meta) : null; },
+    saveMeta(next) {
+      validateMeta(next);
+      meta = next;
+      writeAtomic(join(dir, META_FILE), JSON.stringify(meta, null, 2));
+    },
+    appendMessage(record) {
+      if (!record || typeof record !== 'object') {
+        throw new Error('appendMessage: record required');
+      }
+      const leaked = Object.keys(record).filter((k) => typeof k === 'string' && k.startsWith('_'));
+      if (leaked.length > 0) {
+        throw new Error(`appendMessage: ephemeral fields leaked into log: ${leaked.join(', ')}`);
+      }
+      const stored = {
+        id: record.id || nextMsgId(),
+        ts: record.ts || new Date().toISOString(),
+        from: record.from,
+        role: record.role || (record.from === 'user' ? 'user' : 'assistant'),
+        text: record.text ?? '',
+        taskId: record.taskId || null,
+        mentions: Array.isArray(record.mentions) ? record.mentions.slice() : [],
+        meta: record.meta || {},
+      };
+      log.append(stored);
+      return stored;
+    },
+    *streamMessages() { yield* log.streamAll(); },
+    *readMessageRange(firstId, lastId) { yield* log.readRange(firstId, lastId); },
+    close() { log.close(); },
+  };
+}
+
+/**
+ * Create a new session on disk. Fails if meta.json already exists.
+ * @param {string} sessionsRoot
+ * @param {{
+ *   id: string,
+ *   vpIds: string[],
+ *   displayName?: string,
+ *   workDir?: string,
+ *   createdAt?: string,
+ * }} spec
+ * @returns {SessionHandle}
+ */
+export function createSession(sessionsRoot, spec) {
+  if (!spec || !spec.id) throw new Error('createSession: spec.id required');
+  if (!Array.isArray(spec.vpIds) || spec.vpIds.length === 0) {
+    throw new Error('createSession: spec.vpIds required (non-empty array)');
+  }
+  for (const v of spec.vpIds) {
+    if (isReservedVpId(v)) throw new ReservedVpIdError(v);
+    const verdict = validateVpId(v);
+    if (!verdict.ok) throw new InvalidVpIdError(v, verdict.reason);
+  }
+  const h = openSession(sessionsRoot, spec.id);
+  if (h.getMeta()) throw new Error(`session ${spec.id} already exists`);
+  const meta = {
+    id: spec.id,
+    displayName: typeof spec.displayName === 'string' && spec.displayName.trim()
+      ? spec.displayName.trim() : spec.id,
+    vpIds: Array.from(new Set(spec.vpIds)),
+    workDir: typeof spec.workDir === 'string' ? spec.workDir.trim() : '',
+    createdAt: spec.createdAt || new Date().toISOString(),
+    lastTurnAt: null,
+  };
+  h.saveMeta(meta);
+  return h;
+}
+
+/** Non-destructive load — returns null if meta.json is missing/corrupt. */
+export function loadSessionMeta(dir) {
+  const path = join(dir, META_FILE);
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    validateMeta(parsed);
+    if (typeof parsed.displayName !== 'string') parsed.displayName = parsed.id;
+    if (typeof parsed.workDir !== 'string') parsed.workDir = '';
+    if (parsed.lastTurnAt === undefined) parsed.lastTurnAt = null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** List every session directory under `sessionsRoot`. */
+export function listSessions(sessionsRoot) {
+  if (!existsSync(sessionsRoot)) return [];
+  const out = [];
+  for (const name of readdirSync(sessionsRoot)) {
+    if (name.startsWith('.')) continue;
+    const p = join(sessionsRoot, name);
+    try {
+      if (!statSync(p).isDirectory()) continue;
+    } catch { continue; }
+    const meta = loadSessionMeta(p);
+    if (meta) out.push(meta);
+  }
+  return out;
+}
+
+/** Update a session's displayName. */
+export function renameSession(sessionsRoot, sessionId, displayName) {
+  const h = openSession(sessionsRoot, sessionId);
+  const meta = h.getMeta();
+  if (!meta) throw new Error(`renameSession: session ${sessionId} not found`);
+  const next = { ...meta, displayName: String(displayName || '').trim() || meta.id };
+  h.saveMeta(next);
+  h.close();
+  return next;
+}
+
+/**
+ * Patch a session's meta: add/remove VPs or change displayName/workDir.
+ * @param {string} sessionsRoot
+ * @param {string} sessionId
+ * @param {{addVpIds?: string[], removeVpIds?: string[], displayName?: string, workDir?: string}} patch
+ */
+export function updateSession(sessionsRoot, sessionId, patch = {}) {
+  const h = openSession(sessionsRoot, sessionId);
+  const meta = h.getMeta();
+  if (!meta) { h.close(); throw new Error(`updateSession: session ${sessionId} not found`); }
+  let vpIds = Array.from(meta.vpIds || []);
+  if (Array.isArray(patch.addVpIds)) {
+    for (const v of patch.addVpIds) {
+      if (isReservedVpId(v)) throw new ReservedVpIdError(v);
+      const verdict = validateVpId(v);
+      if (!verdict.ok) throw new InvalidVpIdError(v, verdict.reason);
+      if (!vpIds.includes(v)) vpIds.push(v);
+    }
+  }
+  if (Array.isArray(patch.removeVpIds)) {
+    const drop = new Set(patch.removeVpIds);
+    vpIds = vpIds.filter((v) => !drop.has(v));
+  }
+  if (vpIds.length === 0) {
+    h.close();
+    throw new Error('updateSession: refusing to leave session with zero VPs');
+  }
+  const next = { ...meta, vpIds };
+  if (typeof patch.displayName === 'string' && patch.displayName.trim()) {
+    next.displayName = patch.displayName.trim();
+  }
+  if (typeof patch.workDir === 'string') {
+    next.workDir = patch.workDir.trim();
+  }
+  h.saveMeta(next);
+  h.close();
+  return next;
+}
+
+/** Stamp lastTurnAt. */
+export function touchSession(sessionsRoot, sessionId, when = new Date().toISOString()) {
+  const h = openSession(sessionsRoot, sessionId);
+  const meta = h.getMeta();
+  if (!meta) { h.close(); return null; }
+  const next = { ...meta, lastTurnAt: when };
+  h.saveMeta(next);
+  h.close();
+  return next;
+}
+
+/** Soft-archive: rename dir to `.archived-<sessionId>-<ts>`. */
+export function archiveSession(sessionsRoot, sessionId) {
+  const src = join(sessionsRoot, sessionId);
+  if (!existsSync(src)) return false;
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const dst = join(sessionsRoot, `.archived-${sessionId}-${ts}`);
+  renameSync(src, dst);
+  return true;
+}
+
+/** Permanently delete a session directory. */
+export function deleteSession(sessionsRoot, sessionId) {
+  const src = join(sessionsRoot, sessionId);
+  if (!existsSync(src)) return false;
+  rmSync(src, { recursive: true, force: true });
+  return true;
+}
+
+function validateMeta(meta) {
+  if (!meta || typeof meta !== 'object') throw new Error('session meta.json must be object');
+  if (!meta.id || typeof meta.id !== 'string') throw new Error('session.id required');
+  if (!Array.isArray(meta.vpIds) || meta.vpIds.length === 0) {
+    throw new Error('session.vpIds required (non-empty array)');
+  }
+  for (const v of meta.vpIds) {
+    if (typeof v !== 'string') throw new Error('session.vpIds must be string[]');
+  }
+  if (meta.displayName != null && typeof meta.displayName !== 'string') {
+    throw new Error('session.displayName must be string');
+  }
+  if (meta.workDir != null && typeof meta.workDir !== 'string') {
+    throw new Error('session.workDir must be string');
+  }
+  if (meta.lastTurnAt != null && typeof meta.lastTurnAt !== 'string') {
+    throw new Error('session.lastTurnAt must be string|null');
+  }
+}
+
+/**
+ * @typedef {Object} SessionHandle
+ * @property {string} dir
+ * @property {string} id
+ * @property {() => any} getMeta
+ * @property {(next:any) => void} saveMeta
+ * @property {(record:any) => any} appendMessage
+ * @property {() => Generator<any>} streamMessages
+ * @property {(first:string,last:string) => Generator<any>} readMessageRange
+ * @property {() => void} close
+ */