@yeaft/webchat-agent 1.0.88 → 1.0.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.88",
+  "version": "1.0.90",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/migrate/project-sessions-to-user.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * migrate/project-sessions-to-user.js — copy workDir-backed Yeaft Sessions into
+ * the agent-local user Yeaft directory so normal startup discovers them from
+ * `<userYeaftDir>/sessions/` without depending on the workDir registry.
+ *
+ * Usage:
+ *   node agent/yeaft/migrate/project-sessions-to-user.js <projectDir> [userYeaftDir]
+ *   node agent/yeaft/migrate/project-sessions-to-user.js --dry-run <projectDir>
+ *   node agent/yeaft/migrate/project-sessions-to-user.js --overwrite <projectDir>
+ *
+ * Default userYeaftDir is `~/.yeaft`.
+ */
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+} from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import {
+  loadSessionMeta,
+} from '../sessions/session-store.js';
+import {
+  normalizeWorkDir,
+  scanWorkdirSessions,
+  sessionsRoot,
+  unregisterSessionWorkDir,
+  yeaftDirForWorkDir,
+} from '../sessions/session-crud.js';
+
+/**
+ * @typedef {Object} MigrationOptions
+ * @property {boolean} [dryRun]
+ * @property {boolean} [overwrite]
+ * @property {boolean} [deleteSource]
+ */
+
+/**
+ * Copy every readable Session under `<projectDir>/.yeaft/sessions/` into
+ * `<userYeaftDir>/sessions/` and copy matching memory scopes. Existing
+ * destination Sessions are skipped unless `overwrite` is true.
+ *
+ * We deliberately unregister migrated Session ids from the legacy workDir
+ * registry after a successful copy. Otherwise startup would still prefer the
+ * project-backed copy over the newly local copy.
+ *
+ * @param {string} projectDir
+ * @param {string} [userYeaftDir]
+ * @param {MigrationOptions} [options]
+ * @returns {{ok:boolean, projectDir:string, userYeaftDir:string, scanned:number, copied:number, skipped:number, overwritten:number, removedSources:number, sessions:Array<object>, warnings:string[]}}
+ */
+export function migrateProjectSessionsToUser(projectDir, userYeaftDir = join(homedir(), '.yeaft'), options = {}) {
+  const normalizedProjectDir = normalizeWorkDir(projectDir);
+  const normalizedUserYeaftDir = normalizeWorkDir(userYeaftDir || join(homedir(), '.yeaft'));
+  const dryRun = !!options.dryRun;
+  const overwrite = !!options.overwrite;
+  const deleteSource = !!options.deleteSource;
+  const warnings = [];
+  const sessions = [];
+
+  if (!normalizedProjectDir) {
+    throw new Error('projectDir required');
+  }
+  if (!normalizedUserYeaftDir) {
+    throw new Error('userYeaftDir required');
+  }
+
+  const projectYeaftDir = yeaftDirForWorkDir(normalizedProjectDir);
+  const projectSessionsRoot = sessionsRoot(projectYeaftDir);
+  const userSessionsRoot = sessionsRoot(normalizedUserYeaftDir);
+  const found = scanWorkdirSessions(normalizedProjectDir);
+
+  let copied = 0;
+  let skipped = 0;
+  let overwritten = 0;
+  let removedSources = 0;
+
+  if (!dryRun) {
+    mkdirSync(userSessionsRoot, { recursive: true });
+  }
+
+  for (const meta of found) {
+    const sessionId = meta.id;
+    const sourceDir = join(projectSessionsRoot, sessionId);
+    const destDir = join(userSessionsRoot, sessionId);
+    const row = {
+      id: sessionId,
+      name: meta.name || sessionId,
+      sourceDir,
+      destDir,
+      status: 'pending',
+    };
+
+    if (!existsSync(sourceDir) || !loadSessionMeta(sourceDir)) {
+      row.status = 'skipped';
+      row.reason = 'source_missing_or_corrupt';
+      skipped += 1;
+      sessions.push(row);
+      continue;
+    }
+
+    if (existsSync(destDir)) {
+      if (!overwrite) {
+        row.status = 'skipped';
+        row.reason = 'destination_exists';
+        skipped += 1;
+        sessions.push(row);
+        continue;
+      }
+      if (!dryRun) rmSync(destDir, { recursive: true, force: true });
+      overwritten += 1;
+      row.overwritten = true;
+    }
+
+    if (!dryRun) {
+      cpSync(sourceDir, destDir, { recursive: true, errorOnExist: false });
+      const copiedMemoryDirs = copySessionMemory(projectYeaftDir, normalizedUserYeaftDir, sessionId, { overwrite, dryRun, warnings });
+      unregisterSessionWorkDir(normalizedUserYeaftDir, sessionId);
+      markMigrated(destDir, normalizedProjectDir);
+      if (deleteSource) {
+        rmSync(sourceDir, { recursive: true, force: true });
+        removeCopiedSourceMemory(copiedMemoryDirs, warnings);
+        removedSources += 1;
+      }
+    }
+
+    row.status = dryRun ? 'would_copy' : 'copied';
+    copied += 1;
+    sessions.push(row);
+  }
+
+  return {
+    ok: true,
+    projectDir: normalizedProjectDir,
+    userYeaftDir: normalizedUserYeaftDir,
+    scanned: found.length,
+    copied,
+    skipped,
+    overwritten,
+    removedSources,
+    sessions,
+    warnings,
+  };
+}
+
+function copySessionMemory(projectYeaftDir, userYeaftDir, sessionId, { overwrite, dryRun, warnings }) {
+  const pairs = [
+    [join(projectYeaftDir, 'memory', 'session', sessionId), join(userYeaftDir, 'memory', 'session', sessionId)],
+    [join(projectYeaftDir, 'memory', 'sessions', sessionId), join(userYeaftDir, 'memory', 'sessions', sessionId)],
+    [join(projectYeaftDir, 'memory', 'group', sessionId), join(userYeaftDir, 'memory', 'group', sessionId)],
+  ];
+  const copied = [];
+  for (const [src, dst] of pairs) {
+    if (!existsSync(src)) continue;
+    if (existsSync(dst)) {
+      if (!overwrite) {
+        warnings.push(`memory destination exists; skipping ${dst}`);
+        continue;
+      }
+      if (!dryRun) rmSync(dst, { recursive: true, force: true });
+    }
+    if (!dryRun) {
+      mkdirSync(join(dst, '..'), { recursive: true });
+      cpSync(src, dst, { recursive: true, errorOnExist: false });
+    }
+    copied.push(src);
+  }
+  return copied;
+}
+
+function removeCopiedSourceMemory(copiedMemoryDirs, warnings) {
+  for (const dir of copiedMemoryDirs) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch (err) {
+      warnings.push(`failed to remove source memory ${dir}: ${err?.message || err}`);
+    }
+  }
+}
+
+function markMigrated(destDir, projectDir) {
+  const markerDir = join(destDir, '.migrations');
+  mkdirSync(markerDir, { recursive: true });
+  writeFileSync(
+    join(markerDir, 'project-sessions-to-user.json'),
+    `${JSON.stringify({ migratedAt: new Date().toISOString(), sourceProjectDir: projectDir }, null, 2)}\n`,
+  );
+}
+
+function parseCliArgs(argv) {
+  const args = argv.slice(2);
+  const options = { dryRun: false, overwrite: false, deleteSource: false };
+  const positional = [];
+  for (const arg of args) {
+    if (arg === '--dry-run') options.dryRun = true;
+    else if (arg === '--overwrite') options.overwrite = true;
+    else if (arg === '--delete-source') options.deleteSource = true;
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else positional.push(arg);
+  }
+  return { options, positional };
+}
+
+function printUsage() {
+  console.log('Usage: node agent/yeaft/migrate/project-sessions-to-user.js [--dry-run] [--overwrite] [--delete-source] <projectDir> [userYeaftDir]');
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const { options, positional } = parseCliArgs(process.argv);
+  if (options.help || positional.length < 1) {
+    printUsage();
+    process.exitCode = options.help ? 0 : 1;
+  } else {
+    try {
+      const result = migrateProjectSessionsToUser(positional[0], positional[1], options);
+      console.log(JSON.stringify(result, null, 2));
+      if (result.scanned === 0) process.exitCode = 2;
+    } catch (err) {
+      console.error(err?.message || String(err));
+      process.exitCode = 1;
+    }
+  }
+}

package/yeaft/session.js

@@ -45,7 +45,7 @@ import { TaskManager } from './tasks/manager.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 { ensureDefaultSessionIfEmpty, yeaftDirForWorkDir } from './sessions/session-crud.js';
+import { ensureDefaultSessionIfEmpty, migrateRegisteredWorkDirSessions } from './sessions/session-crud.js';
 import { seedDefaultVps } from './vp/seed-defaults.js';
 import { topUpDefaultVps } from './vp/seed-topup.js';
 import { archiveLegacyScopes } from './memory/seed-backfill.js';
@@ -71,7 +71,7 @@ const DEFAULT_COMPACT_TRIGGER_RATIO = 0.7;
 /**
  * @typedef {Object} SessionOptions
  * @property {string} [dir] — Yeaft data directory override (default: ~/.yeaft)
- * @property {string} [workDir] — Session workDir; when provided, storage lives under <workDir>/.yeaft while config still comes from dir/defaults
+ * @property {string} [workDir] — Session workDir; used only for project-tier assets such as skills/MCP, while Session data stays under the user-level dir
  * @property {string} [model] — Model override
  * @property {string} [language] — Language override ('en' | 'zh')
  * @property {boolean} [debug] — Debug mode override
@@ -150,9 +150,10 @@ export async function loadSession(options = {}) {
 
   // ─── 1. Determine config + store directories ─────────────
   //        Must happen BEFORE loadConfig so that first-run generates a
-  //        default config.json that loadConfig can read. workDir-backed
-  //        Sessions store conversation/session data under <workDir>/.yeaft,
-  //        but runtime config still comes from the agent-local configDir.
+  //        default config.json that loadConfig can read. Session data
+  //        (metadata/roster/config/messages/memory/tasks) is agent-user data
+  //        and stays under configDir (`~/.yeaft`). workDir is only a project
+  //        tier for assets such as skills and MCP config.
   const overrides = { ...configOverrides };
   if (dir) overrides.dir = dir;
   if (model) overrides.model = model;
@@ -161,15 +162,13 @@ export async function loadSession(options = {}) {
 
   const sessionWorkDir = typeof workDir === 'string' && workDir.trim() ? workDir.trim() : '';
   const configDir = overrides.dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
-  const yeaftDir = sessionWorkDir ? yeaftDirForWorkDir(sessionWorkDir) : configDir;
+  const yeaftDir = configDir;
   const configInitResult = initYeaftDir(configDir);
-  const storeInitResult = yeaftDir === configDir ? configInitResult : initYeaftDir(yeaftDir);
+  const storeInitResult = configInitResult;
   overrides.dir = configDir;
 
   // Log any warnings from directory initialization.
-  const initWarnings = yeaftDir === configDir
-    ? configInitResult.warnings
-    : [...configInitResult.warnings, ...storeInitResult.warnings];
+  const initWarnings = configInitResult.warnings;
   for (const w of initWarnings) {
     console.warn(`[Yeaft] ${w}`);
   }
@@ -219,6 +218,22 @@ export async function loadSession(options = {}) {
   //         dream directly. Existing users have already migrated
   //         (state file in ~/.yeaft/.memory-v2-migration.json).
 
+  // ─── 2.3 Project-session migration ─────────────────────
+  //         Session data used to be allowed under `<workDir>/.yeaft/sessions`.
+  //         It is now user-level only (`~/.yeaft/sessions`). Copy any registered
+  //         project-backed sessions into the user root before stores open.
+  try {
+    const migration = migrateRegisteredWorkDirSessions(configDir);
+    if (migration.migrated.length > 0 || migration.errors.length > 0) {
+      console.log(
+        `[Yeaft] session project-store migration: migrated=${migration.migrated.length} ` +
+        `errors=${migration.errors.length}`,
+      );
+    }
+  } catch (err) {
+    console.warn(`[Yeaft] session project-store migration failed: ${err?.message || err}`);
+  }
+
   // ─── 2a. Permission pre-check ─────────────────────────
   //         If the data dir is not writable, mark session as read-only.
   //         Persistence (conversation, memory, dream) is skipped in this mode.

package/yeaft/sessions/session-config.js

@@ -1,10 +1,11 @@
 /**
  * session-config.js — Per-session selected model override state.
  *
- * Each session may carry its header-selected model override in `config.json` at
+ * Each session carries its header-selected model override in `config.json` at
  *   ~/.yeaft/sessions/<sessionId>/config.json
- * or, for workDir-backed sessions:
- *   <workDir>/.yeaft/sessions/<sessionId>/config.json
+ *
+ * Session config is user-level state. Project `.yeaft` directories may provide
+ * project assets such as skills/MCP config, but must not own Session config.
  *
  * v1 schema (intentionally tiny — extend via additive keys only):
  *   {
@@ -24,7 +25,7 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { writeAtomic } from '../storage/index.js';
-import { sessionsRoot, resolveSessionYeaftDir } from './session-crud.js';
+import { sessionsRoot } from './session-crud.js';
 
 const CONFIG_FILE = 'config.json';
 
@@ -41,14 +42,12 @@ export class SessionConfigError extends Error {
 }
 
 /**
- * Resolve the on-disk path for a session's config.json. Honours the
- * per-session workDir registry so sessions bound to a project directory
- * keep their config alongside the session metadata.
+ * Resolve the on-disk path for a session's config.json. Always uses the
+ * agent-local Yeaft root (`~/.yeaft` in production), not a project `.yeaft`.
  */
 export function sessionConfigPath(yeaftDir, sessionId) {
   if (!yeaftDir) return null;
-  const sessionYeaftDir = resolveSessionYeaftDir(yeaftDir, sessionId);
-  return join(sessionsRoot(sessionYeaftDir), sessionId, CONFIG_FILE);
+  return join(sessionsRoot(yeaftDir), sessionId, CONFIG_FILE);
 }
 
 /**

package/yeaft/sessions/session-crud.js

@@ -43,12 +43,13 @@ import {
   mkdirSync,
   readFileSync,
   writeFileSync,
+  cpSync,
 } from 'fs';
 import { randomBytes } from 'crypto';
 import { homedir } from 'os';
 import { isAbsolute, join, resolve } from 'path';
 import {
-  openSession, createSession, listSessions, loadSessionMeta,
+  openSession, createSession, loadSessionMeta,
 } from './session-store.js';
 import { addVp as rosterAdd, removeVp as rosterRemove, setDefaultVp } from './roster.js';
 import { seedDefaultSession, DEFAULT_SESSION_ID } from './seed-default.js';
@@ -56,6 +57,14 @@ import { nextSessionId, validateVpId, isReservedVpId } from './ids.js';
 import { scanVpLibrary, DEFAULT_VP_LIB_DIR } from '../vp/vp-store.js';
 import { seedSummaryIfMissingSync, removeScopeDirSync } from '../memory/store.js';
 import { ensureSessionConfigFile, saveSessionConfig, loadSessionConfig } from './session-config.js';
+import {
+  addOrUpdateManifestSession,
+  ensureSessionsManifest,
+  hasSessionManifest,
+  listManifestSessions,
+  removeManifestSession,
+  resolveManifestSessionDir,
+} from './session-manifest.js';
 
 /**
  * Default memory root used when callers don't pass `options.memoryRoot`.
@@ -155,6 +164,59 @@ export function unregisterSessionWorkDir(defaultYeaftDir, sessionId) {
   writeWorkDirRegistry(defaultYeaftDir, registry);
 }
 
+function ensureSessionManifestReady(yeaftDir) {
+  return ensureSessionsManifest(yeaftDir, {
+    sessionsRoot: sessionsRoot(yeaftDir),
+    registry: readWorkDirRegistry(yeaftDir),
+    yeaftDirForWorkDir,
+    sessionsRootForYeaftDir: sessionsRoot,
+    copySessionExtras: (projectYeaftDir, sessionId) => copySessionExtras(projectYeaftDir, yeaftDir, sessionId),
+    unregisterSessionWorkDir: (sessionId) => unregisterSessionWorkDir(yeaftDir, sessionId),
+  });
+}
+
+function copySessionExtras(sourceYeaftDir, destYeaftDir, sessionId) {
+  for (const family of ['session', 'sessions', 'group']) {
+    const src = join(sourceYeaftDir, 'memory', family, sessionId);
+    const dst = join(destYeaftDir, 'memory', family, sessionId);
+    if (!existsSync(src) || existsSync(dst)) continue;
+    mkdirSync(join(dst, '..'), { recursive: true });
+    cpSync(src, dst, { recursive: true, errorOnExist: false });
+  }
+}
+
+/**
+ * One-way compatibility migration for sessions previously stored under a
+ * project `.yeaft/sessions` tree. New steady-state discovery uses
+ * `sessions-manifest.json`; this helper bootstraps that manifest once and
+ * reports what happened for boot logs/tests.
+ *
+ * @param {string} yeaftDir user-level Yeaft root
+ * @returns {{migrated:string[], skipped:string[], errors:Array<{sessionId:string,error:string}>}}
+ */
+export function migrateRegisteredWorkDirSessions(yeaftDir) {
+  const result = { migrated: [], skipped: [], errors: [] };
+  if (!yeaftDir || hasSessionManifest(yeaftDir)) return result;
+
+  const invalidTargets = new Set();
+  const registry = readWorkDirRegistry(yeaftDir);
+  for (const [sessionId, workDir] of Object.entries(registry)) {
+    const normalized = normalizeWorkDir(workDir);
+    if (!sessionId || !normalized) continue;
+    const targetDir = join(sessionsRoot(yeaftDir), sessionId);
+    if (existsSync(targetDir) && !loadSessionMeta(targetDir)) {
+      invalidTargets.add(sessionId);
+      result.errors.push({ sessionId, error: 'target session directory exists but session metadata is invalid' });
+    }
+  }
+
+  const bootstrap = ensureSessionManifestReady(yeaftDir);
+  result.migrated = Array.isArray(bootstrap.migratedIds) ? bootstrap.migratedIds.slice() : [];
+  result.skipped = (Array.isArray(bootstrap.skippedIds) ? bootstrap.skippedIds : [])
+    .filter(sessionId => !invalidTargets.has(sessionId));
+  return result;
+}
+
 /**
  * Scan the `.yeaft/sessions/` directory under `workDir` and return every
  * session meta we can read. Read-only: never touches the registry.
@@ -228,18 +290,46 @@ export function restoreSessionToRegistry(defaultYeaftDir, sessionId, workDir) {
   if (!sessionId) throw new SessionCrudError('invalid_session_id', null);
   const normalized = normalizeWorkDir(workDir);
   if (!normalized) throw new SessionCrudError('invalid_workdir', sessionId);
-  const groupYeaftDir = yeaftDirForWorkDir(normalized);
-  const dir = join(sessionsRoot(groupYeaftDir), sessionId);
-  if (!existsSync(dir)) throw new SessionCrudError('not_found', sessionId);
-  const meta = loadSessionMeta(dir);
-  if (!meta) throw new SessionCrudError('corrupt_meta', sessionId, `session metadata missing or unreadable at ${dir} (expected session.json or legacy group.json)`);
-  registerSessionWorkDir(defaultYeaftDir, sessionId, normalized);
-  return { ...meta, workDir: normalized };
+  const projectYeaftDir = yeaftDirForWorkDir(normalized);
+  const sourceDir = join(sessionsRoot(projectYeaftDir), sessionId);
+  if (!existsSync(sourceDir)) throw new SessionCrudError('not_found', sessionId);
+  const meta = loadSessionMeta(sourceDir);
+  if (!meta) throw new SessionCrudError('corrupt_meta', sessionId, `session metadata missing or unreadable at ${sourceDir} (expected session.json or legacy group.json)`);
+
+  ensureSessionManifestReady(defaultYeaftDir);
+  const root = sessionsRoot(defaultYeaftDir);
+  const destDir = join(root, sessionId);
+  const manifestDir = resolveManifestSessionDir(defaultYeaftDir, sessionId);
+  if (existsSync(destDir)) {
+    const existing = loadSessionMeta(destDir);
+    if (existing && manifestDir === destDir) return { ...existing, workDir: existing.workDir || normalized };
+    throw new SessionCrudError('duplicate', sessionId, `session already exists at ${destDir}`);
+  }
+
+  mkdirSync(root, { recursive: true });
+  cpSync(sourceDir, destDir, { recursive: true, errorOnExist: true });
+  const importedMeta = { ...meta, workDir: normalized };
+  const handle = openSession(root, sessionId);
+  try {
+    handle.saveMeta(importedMeta);
+  } finally {
+    handle.close();
+  }
+  copySessionExtras(projectYeaftDir, defaultYeaftDir, sessionId);
+  addOrUpdateManifestSession(defaultYeaftDir, importedMeta, destDir);
+  unregisterSessionWorkDir(defaultYeaftDir, sessionId);
+  return importedMeta;
 }
 
 export function resolveSessionYeaftDir(defaultYeaftDir, sessionId) {
   if (!defaultYeaftDir || !sessionId) return defaultYeaftDir;
 
+  const manifestReady = hasSessionManifest(defaultYeaftDir);
+  ensureSessionManifestReady(defaultYeaftDir);
+  const manifestDir = resolveManifestSessionDir(defaultYeaftDir, sessionId);
+  if (manifestDir) return join(manifestDir, '..', '..');
+  if (manifestReady) return defaultYeaftDir;
+
   const registry = readWorkDirRegistry(defaultYeaftDir);
   const workDir = normalizeWorkDir(registry[sessionId]);
   if (workDir) {
@@ -290,7 +380,8 @@ function scanSortedVpIds(libDir) {
 export function ensureDefaultSessionIfEmpty(yeaftDir, options = {}) {
   const libDir = options.libDir || DEFAULT_VP_LIB_DIR;
   const memoryRoot = options.memoryRoot || DEFAULT_MEMORY_ROOT;
-  const existing = listSessions(sessionsRoot(yeaftDir));
+  ensureSessionManifestReady(yeaftDir);
+  const existing = listManifestSessions(yeaftDir).map(row => row.meta);
   if (existing.length > 0) {
     return { seeded: false, sessionId: existing[0].id };
   }
@@ -307,6 +398,8 @@ export function ensureDefaultSessionIfEmpty(yeaftDir, options = {}) {
     defaultVpId,
     memoryRoot,
   });
+  const meta = group.getMeta();
+  if (meta) addOrUpdateManifestSession(yeaftDir, meta, join(sessionsRoot(yeaftDir), meta.id));
   return {
     seeded: created,
     sessionId: group.id,
@@ -328,7 +421,8 @@ export function ensureDefaultSessionIfEmpty(yeaftDir, options = {}) {
 export function createSessionFromSpec(yeaftDir, spec, options = {}) {
   const input = spec || {};
   const normalizedWorkDir = normalizeWorkDir(input.workDir);
-  const groupYeaftDir = normalizedWorkDir ? yeaftDirForWorkDir(normalizedWorkDir) : yeaftDir;
+  ensureSessionManifestReady(yeaftDir);
+  const groupYeaftDir = yeaftDir;
   const memoryRoot = options.memoryRoot || (groupYeaftDir ? join(groupYeaftDir, 'memory') : DEFAULT_MEMORY_ROOT);
   const libDir = options.libDir || DEFAULT_VP_LIB_DIR;
   const name = String(input.name || '').trim();
@@ -364,7 +458,7 @@ export function createSessionFromSpec(yeaftDir, spec, options = {}) {
   const handle = createSession(root, { id, name, roster, defaultVpId, workDir: normalizedWorkDir });
   const meta = handle.getMeta();
   handle.close();
-  if (normalizedWorkDir) registerSessionWorkDir(yeaftDir, id, normalizedWorkDir);
+  addOrUpdateManifestSession(yeaftDir, meta, join(root, id));
 
   // Per-session config (v1: model only). We always create an empty
   // config.json so hand-editing tools can find a session-level override
@@ -463,6 +557,7 @@ export function archiveSession(yeaftDir, sessionId) {
   // still cleared in case it points at a stale row.
   if (!existsSync(srcDir) || !loadSessionMeta(srcDir)) {
     unregisterSessionWorkDir(yeaftDir, sessionId);
+    removeManifestSession(yeaftDir, sessionId);
     return { sessionId, archivedAs: null, alreadyGone: true };
   }
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
@@ -471,6 +566,7 @@ export function archiveSession(yeaftDir, sessionId) {
   const dstDir = join(root, `.archived-${ts}-${suffix}-${sessionId}`);
   renameSync(srcDir, dstDir);
   unregisterSessionWorkDir(yeaftDir, sessionId);
+  removeManifestSession(yeaftDir, sessionId);
   return { sessionId, archivedAs: dstDir, alreadyGone: false };
 }
 
@@ -529,6 +625,7 @@ export function deleteSession(yeaftDir, sessionId, options = {}) {
   }
 
   unregisterSessionWorkDir(yeaftDir, sessionId);
+  removeManifestSession(yeaftDir, sessionId);
   return {
     sessionId,
     deleted: liveExists,
@@ -621,16 +718,10 @@ export function requireSession(yeaftDir, sessionId) {
 
 /** Convenience: snapshot all non-archived groups for WS broadcast. */
 export function snapshotSessions(yeaftDir) {
+  ensureSessionManifestReady(yeaftDir);
   const byId = new Map();
-  for (const group of listSessions(sessionsRoot(yeaftDir))) {
-    byId.set(group.id, group);
-  }
-  const registry = readWorkDirRegistry(yeaftDir);
-  for (const [sessionId, workDir] of Object.entries(registry)) {
-    const groupYeaftDir = yeaftDirForWorkDir(workDir);
-    const dir = join(sessionsRoot(groupYeaftDir), sessionId);
-    const meta = existsSync(dir) ? loadSessionMeta(dir) : null;
-    if (meta) byId.set(meta.id, meta);
+  for (const row of listManifestSessions(yeaftDir)) {
+    byId.set(row.meta.id, row.meta);
   }
   // Attach per-group config overrides (v1: just `model`). Frontend can
   // render the effective model without re-querying.

package/yeaft/sessions/session-manifest.js

@@ -0,0 +1,217 @@
+/**
+ * session-manifest.js — canonical index for Yeaft Session folders.
+ *
+ * Boot flow:
+ *   1. If `<yeaftDir>/sessions-manifest.json` exists, load it and trust only
+ *      valid entries whose folder still contains readable session metadata.
+ *   2. If it does not exist, bootstrap once from legacy folder-based storage:
+ *      copy registered workDir-backed Sessions into `<yeaftDir>/sessions/`, then
+ *      index `<yeaftDir>/sessions/` into the manifest.
+ *
+ * The legacy `group-workdirs.json` registry remains readable for bootstrap only.
+ * New steady-state discovery should use this manifest.
+ */
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'fs';
+import { join } from 'path';
+import { loadSessionMeta } from './session-store.js';
+
+export const SESSIONS_MANIFEST_FILE = 'sessions-manifest.json';
+const MANIFEST_VERSION = 1;
+
+export function sessionManifestPath(yeaftDir) {
+  return join(yeaftDir, SESSIONS_MANIFEST_FILE);
+}
+
+export function hasSessionManifest(yeaftDir) {
+  return !!yeaftDir && existsSync(sessionManifestPath(yeaftDir));
+}
+
+export function loadSessionsManifest(yeaftDir) {
+  if (!hasSessionManifest(yeaftDir)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(sessionManifestPath(yeaftDir), 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    if (!Array.isArray(parsed.sessions)) return null;
+    return {
+      version: Number(parsed.version) || MANIFEST_VERSION,
+      generatedAt: typeof parsed.generatedAt === 'string' ? parsed.generatedAt : '',
+      sessions: parsed.sessions
+        .filter(row => row && typeof row === 'object' && typeof row.id === 'string' && typeof row.path === 'string')
+        .map(row => ({
+          id: row.id,
+          path: row.path,
+          name: typeof row.name === 'string' ? row.name : row.id,
+          createdAt: typeof row.createdAt === 'string' ? row.createdAt : '',
+          workDir: typeof row.workDir === 'string' ? row.workDir : '',
+        })),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeSessionsManifest(yeaftDir, sessions) {
+  if (!yeaftDir) throw new Error('yeaftDir required');
+  mkdirSync(yeaftDir, { recursive: true });
+  const manifest = {
+    version: MANIFEST_VERSION,
+    generatedAt: new Date().toISOString(),
+    sessions: dedupeSessions(sessions).sort((a, b) => String(a.createdAt || '').localeCompare(String(b.createdAt || ''))),
+  };
+  writeFileSync(sessionManifestPath(yeaftDir), `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+export function buildManifestFromLocalSessions(yeaftDir, sessionsRoot) {
+  const rows = [];
+  if (!sessionsRoot || !existsSync(sessionsRoot)) return rows;
+  let entries;
+  try {
+    entries = readdirSync(sessionsRoot);
+  } catch {
+    return rows;
+  }
+  for (const name of entries) {
+    if (name.startsWith('.')) continue;
+    const dir = join(sessionsRoot, name);
+    try { if (!statSync(dir).isDirectory()) continue; } catch { continue; }
+    const meta = loadSessionMeta(dir);
+    if (!meta) continue;
+    rows.push(manifestRowFromMeta(meta, dir));
+  }
+  return rows;
+}
+
+export function listManifestSessions(yeaftDir) {
+  const manifest = loadSessionsManifest(yeaftDir);
+  if (!manifest) return [];
+  const rows = [];
+  const seen = new Set();
+  for (const entry of manifest.sessions) {
+    if (seen.has(entry.id)) continue;
+    seen.add(entry.id);
+    const meta = loadSessionMeta(entry.path);
+    if (!meta) continue;
+    rows.push({ meta, dir: entry.path });
+  }
+  return rows.sort((a, b) => String(a.meta.createdAt || '').localeCompare(String(b.meta.createdAt || '')));
+}
+
+export function resolveManifestSessionDir(yeaftDir, sessionId) {
+  const manifest = loadSessionsManifest(yeaftDir);
+  if (!manifest || !sessionId) return null;
+  const entry = manifest.sessions.find(row => row.id === sessionId);
+  if (!entry) return null;
+  if (!loadSessionMeta(entry.path)) return null;
+  return entry.path;
+}
+
+/**
+ * Bootstrap the manifest from legacy storage if it does not exist.
+ *
+ * @param {string} yeaftDir
+ * @param {{sessionsRoot:string, registry?:object, yeaftDirForWorkDir:(workDir:string)=>string, sessionsRootForYeaftDir:(dir:string)=>string, copySessionExtras?:(projectYeaftDir:string, sessionId:string)=>void, unregisterSessionWorkDir?:(sessionId:string)=>void}} options
+ */
+export function ensureSessionsManifest(yeaftDir, options) {
+  if (hasSessionManifest(yeaftDir)) {
+    return { created: false, migrated: 0, skipped: 0, manifest: loadSessionsManifest(yeaftDir) };
+  }
+  const root = options.sessionsRoot;
+  mkdirSync(root, { recursive: true });
+
+  let migrated = 0;
+  let skipped = 0;
+  const migratedIds = [];
+  const skippedIds = [];
+  const registry = options.registry && typeof options.registry === 'object' ? options.registry : {};
+  for (const [sessionId, workDir] of Object.entries(registry)) {
+    if (!sessionId || !workDir) continue;
+    const projectYeaftDir = options.yeaftDirForWorkDir(workDir);
+    const projectRoot = options.sessionsRootForYeaftDir(projectYeaftDir);
+    const sourceDir = join(projectRoot, sessionId);
+    const destDir = join(root, sessionId);
+    const meta = existsSync(sourceDir) ? loadSessionMeta(sourceDir) : null;
+    if (!meta) {
+      skipped += 1;
+      skippedIds.push(sessionId);
+      continue;
+    }
+    if (existsSync(destDir)) {
+      if (loadSessionMeta(destDir)) {
+        skipped += 1;
+        skippedIds.push(sessionId);
+        if (typeof options.unregisterSessionWorkDir === 'function') {
+          options.unregisterSessionWorkDir(sessionId);
+        }
+        continue;
+      }
+      skipped += 1;
+      skippedIds.push(sessionId);
+      continue;
+    }
+    cpSync(sourceDir, destDir, { recursive: true, errorOnExist: false });
+    migrated += 1;
+    migratedIds.push(sessionId);
+    if (typeof options.copySessionExtras === 'function') {
+      options.copySessionExtras(projectYeaftDir, sessionId);
+    }
+    if (typeof options.unregisterSessionWorkDir === 'function') {
+      options.unregisterSessionWorkDir(sessionId);
+    }
+  }
+
+  const manifest = writeSessionsManifest(yeaftDir, buildManifestFromLocalSessions(yeaftDir, root));
+  return { created: true, migrated, skipped, migratedIds, skippedIds, manifest };
+}
+
+export function addOrUpdateManifestSession(yeaftDir, meta, dir) {
+  const current = loadSessionsManifest(yeaftDir) || { sessions: [] };
+  const rows = current.sessions.filter(row => row.id !== meta.id);
+  rows.push(manifestRowFromMeta(meta, dir));
+  return writeSessionsManifest(yeaftDir, rows);
+}
+
+export function removeManifestSession(yeaftDir, sessionId) {
+  const current = loadSessionsManifest(yeaftDir);
+  if (!current) return null;
+  return writeSessionsManifest(yeaftDir, current.sessions.filter(row => row.id !== sessionId));
+}
+
+function manifestRowFromMeta(meta, dir) {
+  return {
+    id: meta.id,
+    name: meta.name || meta.id,
+    path: dir,
+    createdAt: meta.createdAt || '',
+    workDir: meta.workDir || '',
+  };
+}
+
+function dedupeSessions(sessions) {
+  const byId = new Map();
+  for (const row of sessions || []) {
+    if (!row || !row.id || !row.path) continue;
+    byId.set(row.id, {
+      id: row.id,
+      name: row.name || row.id,
+      path: row.path,
+      createdAt: row.createdAt || '',
+      workDir: row.workDir || '',
+    });
+  }
+  return Array.from(byId.values());
+}
+
+export function __testRemoveSessionsManifest(yeaftDir) {
+  rmSync(sessionManifestPath(yeaftDir), { force: true });
+}

package/yeaft/web-bridge.js

@@ -45,12 +45,11 @@ import {
   removeMember,
   setSessionDefaultVp,
   snapshotSessions,
-  resolveSessionYeaftDir,
   sessionsRoot,
   scanWorkdirSessions,
   restoreSessionToRegistry,
   readWorkDirRegistry,
-  yeaftDirForWorkDir,
+  migrateRegisteredWorkDirSessions,
 } from './sessions/session-crud.js';
 import { openSession, loadSessionMeta } from './sessions/session-store.js';
 import { loadSessionConfig, resolveSessionConfig, SessionConfigError } from './sessions/session-config.js';
@@ -189,8 +188,8 @@ function scheduleYeaftLoadHistoryMetadataReplay(sessionId) {
       let projectRuntime = null;
       if (sessionId) {
         try {
-          const groupYeaftDir = resolveSessionYeaftDir(ctx.CONFIG?.yeaftDir || DEFAULT_YEAFT_DIR, sessionId);
-          const meta = loadSessionMeta(join(sessionsRoot(groupYeaftDir), sessionId));
+          const metaRoot = ctx.CONFIG?.yeaftDir || DEFAULT_YEAFT_DIR;
+          const meta = loadSessionMeta(join(sessionsRoot(metaRoot), sessionId));
           projectRuntime = await ensureProjectRuntimeForSessionMeta(meta);
         } catch { /* best-effort project metadata */ }
       }
@@ -429,13 +428,6 @@ function projectRuntimeKey(workDir) {
   return normalizeSessionWorkDir(workDir) || '__agent_cwd__';
 }
 
-function resolveStoreYeaftDirForSession(defaultYeaftDir, { sessionId = null, sessionMeta = null, workDir = '' } = {}) {
-  const normalizedWorkDir = normalizeSessionWorkDir(workDir || sessionMeta?.workDir);
-  if (normalizedWorkDir) return yeaftDirForWorkDir(normalizedWorkDir);
-  if (sessionId) return resolveSessionYeaftDir(defaultYeaftDir, sessionId);
-  return defaultYeaftDir;
-}
-
 function createThreadId() {
   return `thr_${Date.now().toString(36)}_${randomUUID().slice(0, 8)}`;
 }
@@ -1315,10 +1307,8 @@ function getOrCreateVpEngine(sessionId, vpId, threadId = 'main') {
   const key = threadKey(sessionId, vpId, threadId);
   if (!session) throw new Error('getOrCreateVpEngine: session not loaded');
   // Per-session config overlay (v1: model only). Falls back to the
-  // session's user-level config when no override is set. Prefer the agent-local
-  // config root: sessionConfigPath() resolves registered workDir-backed
-  // sessions from there, while still allowing a later agent-local session in
-  // the same bridge runtime to read its own override after a workDir-first boot.
+  // session's user-level config when no override is set. Session config is
+  // always resolved from the agent-local root; project `.yeaft` is ignored.
   const sessionConfigRoot = liveConfigRoot();
   const groupCfg = loadSessionConfig(sessionConfigRoot, sessionId);
   const effectiveConfig = resolveSessionConfig(session.config, groupCfg);
@@ -2465,14 +2455,10 @@ export function handleYeaftCreateSession(msg) {
 }
 
 /**
- * `yeaft_scan_workdir_sessions` — read-only probe: list every yeaft
- * session physically present under `<workDir>/.yeaft/sessions/` along with
- * an `alreadyRegistered` flag (so the restore UI can disable sessions
- * already visible in the sidebar). Never mutates the registry; never
- * throws on missing/empty directories.
- *
- * Pairs with `handleYeaftRestoreSession` for the "Restore session from a
- * workdir" flow — see plan rosy-snuggling-waterfall.md.
+ * `yeaft_scan_workdir_sessions` — compatibility endpoint for the retired
+ * workdir Session scan flow. Session data now lives under the user-level
+ * `~/.yeaft/sessions`; project `.yeaft` is reserved for project assets such as
+ * skills and MCP config.
  */
 export function handleYeaftScanWorkdirSessions(msg) {
   const requestId = msg && msg.requestId;
@@ -2480,11 +2466,8 @@ export function handleYeaftScanWorkdirSessions(msg) {
     const workDir = String(msg && msg.workDir || '').trim();
     if (!workDir) throw new SessionCrudError('invalid_workdir', null, 'workDir required');
     const yeaftDir = ctx.CONFIG?.yeaftDir;
-    // scanWorkdirSessions is a layer-pure utility — it doesn't read the
-    // central workdir registry. The handler is the right layer to fold in
-    // `alreadyRegistered` because that flag couples the per-workdir scan
-    // to a specific agent's registry (the same scan from a CLI tool or
-    // a different agent would compare against a different registry).
+    // scanWorkdirSessions is now a compatibility no-op because Session data is
+    // user-level only. Keep the decoration shape stable for older clients.
     const sessions = scanWorkdirSessions(workDir);
     const registry = readWorkDirRegistry(yeaftDir);
     const decorated = sessions.map(s => ({
@@ -3533,8 +3516,8 @@ async function runYeaftSessionSend(msg) {
     return;
   }
 
-  // Open the session metadata first so a workDir-backed Session can schedule
-  // project runtime loading without blocking the user-message hot path. If
+  // Open the user-level session metadata first so project runtime loading can
+  // use the stored workDir without blocking the user-message hot path. If
   // metadata is missing we still boot the agent runtime for a useful error
   // response, then fail on the session open check.
   let sessionHandle = null;
@@ -3542,8 +3525,7 @@ async function runYeaftSessionSend(msg) {
   let sessionMetaForRuntime = null;
   const openSessionStart = perfNowMs();
   try {
-    const groupYeaftDir = resolveSessionYeaftDir(yeaftDir, sessionId);
-    sessionRoot = sessionsRoot(groupYeaftDir);
+    sessionRoot = sessionsRoot(yeaftDir);
     const dir = join(sessionRoot, sessionId);
     if (existsSync(dir) && loadSessionMeta(dir)) {
       sessionHandle = openSession(sessionRoot, sessionId);
@@ -3564,6 +3546,17 @@ async function runYeaftSessionSend(msg) {
 
   const ensureSessionStart = perfNowMs();
   await ensureSessionLoaded({ sessionMeta: sessionMetaForRuntime, perfTraceId });
+  if (!sessionHandle) {
+    try {
+      const dir = join(sessionRoot, sessionId);
+      if (existsSync(dir) && loadSessionMeta(dir)) {
+        sessionHandle = openSession(sessionRoot, sessionId);
+        sessionMetaForRuntime = sessionHandle.getMeta();
+      }
+    } catch (err) {
+      console.warn('[Yeaft] yeaft_session_chat: migrated session reopen failed', err?.message || err);
+    }
+  }
   scheduleProjectRuntimeLoad(sessionMetaForRuntime?.workDir);
   traceDuration('session_send.ensure_session_loaded', ensureSessionStart);
 
@@ -3927,11 +3920,6 @@ async function ensureSessionLoaded(opts = {}) {
   sessionLoadPromise = (async () => {
     const yeaftDir = ctx.CONFIG?.yeaftDir;
     const normalizedWorkDir = normalizeSessionWorkDir(opts?.workDir || opts?.sessionMeta?.workDir);
-    const sessionYeaftDir = resolveStoreYeaftDirForSession(yeaftDir, {
-      sessionId: opts?.sessionId || opts?.sessionMeta?.id || null,
-      sessionMeta: opts?.sessionMeta || null,
-      workDir: normalizedWorkDir,
-    });
     session = await loadSession({
       ...(yeaftDir && { dir: yeaftDir }),
       ...(normalizedWorkDir && { workDir: normalizedWorkDir }),
@@ -5694,13 +5682,15 @@ export async function handleYeaftLoadHistory(msg) {
     ensureYeaftConversationId();
 
     let sessionMetaForRuntime = null;
-    let sessionYeaftDir = yeaftDir;
+    const historyYeaftDir = yeaftDir;
     if (sessionId) {
       try {
-        sessionYeaftDir = resolveSessionYeaftDir(yeaftDir, sessionId);
-        const metaDir = join(sessionsRoot(sessionYeaftDir), sessionId);
+        migrateRegisteredWorkDirSessions(yeaftDir);
+        const metaDir = join(sessionsRoot(yeaftDir), sessionId);
         sessionMetaForRuntime = loadSessionMeta(metaDir);
-      } catch { /* best-effort metadata hint */ }
+      } catch (err) {
+        console.warn('[Yeaft] load_history project-store migration failed:', err?.message || err);
+      }
     }
 
     // First paint must not wait for full Yeaft runtime boot (MCP connects,
@@ -5708,7 +5698,7 @@ export async function handleYeaftLoadHistory(msg) {
     // source of truth and can be opened cheaply, so replay the visible message
     // window immediately, then finish loadSession below for actual turns.
     const coldStoreStart = perfNowMs();
-    const coldStore = new ConversationStore(sessionYeaftDir);
+    const coldStore = new ConversationStore(historyYeaftDir);
     traceDuration('history.cold_store_open', coldStoreStart);
     if (sessionId && (afterSeqRaw !== null || afterMessageId)) {
       let afterSeq = afterSeqRaw;