@yeaft/webchat-agent 1.0.59 → 1.0.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.59",
+  "version": "1.0.62",
   "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/cli.js

@@ -116,7 +116,7 @@ function parseArgs(argv) {
 
 // ─── Trace query handler ───────────────────────────────────────
 
-function handleTraceQuery(args, config) {
+async function handleTraceQuery(args, config) {
   const traceDir = config.dir;
   let trace;
   try {
@@ -128,7 +128,7 @@ function handleTraceQuery(args, config) {
   try {
     switch (args.trace) {
       case 'stats': {
-        const s = trace.stats();
+        const s = await trace.stats();
         console.log('Debug Trace Statistics:');
         console.log(`  Turns:    ${s.turnCount}`);
         console.log(`  Tools:    ${s.toolCount}`);
@@ -137,7 +137,7 @@ function handleTraceQuery(args, config) {
         break;
       }
       case 'recent': {
-        const turns = trace.queryRecent(20);
+        const turns = await trace.queryRecent(20);
         if (turns.length === 0) {
           console.log('No recent turns.');
         } else {
@@ -154,7 +154,7 @@ function handleTraceQuery(args, config) {
         if (!args.traceArg) {
           throw new Error('Usage: --trace search <keyword>');
         }
-        const results = trace.search(args.traceArg);
+        const results = await trace.search(args.traceArg);
         console.log(`Found ${results.length} turns matching "${args.traceArg}":`);
         for (const t of results) {
           const time = new Date(t.started_at).toLocaleString();
@@ -164,7 +164,7 @@ function handleTraceQuery(args, config) {
         break;
       }
       case 'tools': {
-        const tools = trace.queryTools({ name: args.traceArg });
+        const tools = await trace.queryTools({ name: args.traceArg });
         console.log(`Found ${tools.length} tool calls${args.traceArg ? ` for "${args.traceArg}"` : ''}:`);
         for (const t of tools.slice(0, 20)) {
           const time = new Date(t.created_at).toLocaleString();
@@ -174,10 +174,10 @@ function handleTraceQuery(args, config) {
         break;
       }
       case 'compact': {
-        const s = trace.stats();
+        const s = await trace.stats();
         console.log(`Compacting debug trace files (${(s.dbSizeBytes / 1048576).toFixed(1)} MB, ${s.turnCount} turns)...`);
         console.log('This prunes old request folders and may take a moment. Do not interrupt.');
-        const { before, after } = trace.compact();
+        const { before, after } = await trace.compact();
         const saved = Math.max(0, before - after);
         console.log(`Done. ${(before / 1048576).toFixed(1)} MB → ${(after / 1048576).toFixed(1)} MB (reclaimed ${(saved / 1048576).toFixed(1)} MB).`);
         break;
@@ -186,7 +186,7 @@ function handleTraceQuery(args, config) {
         throw new Error(`Unknown trace command: ${args.trace}. Available: stats, recent, search <keyword>, tools [name], compact`);
     }
   } finally {
-    trace.close();
+    await trace.close();
   }
 }
 
@@ -383,7 +383,7 @@ async function runREPL(config, args) {
         case 'trace': {
           const subcmd = cmdArgs[0] || 'stats';
           try {
-            handleTraceQuery({ trace: subcmd, traceArg: cmdArgs[1] }, session.config);
+            await handleTraceQuery({ trace: subcmd, traceArg: cmdArgs[1] }, session.config);
           } catch (e) {
             console.error(`Trace error: ${e.message}`);
           }
@@ -454,7 +454,7 @@ async function runREPL(config, args) {
           break;
 
         case 'stats': {
-          const s = trace.stats();
+          const s = await trace.stats();
           console.log(`Session stats:`);
           console.log(`  Debug: ${session.config.debug}`);
           console.log(`  Turns: ${s.turnCount}`);
@@ -799,7 +799,7 @@ async function main() {
 
   // Handle --trace queries (no LLM needed, no session needed)
   if (args.trace) {
-    handleTraceQuery(args, config);
+    await handleTraceQuery(args, config);
     return;
   }
 

package/yeaft/debug-trace.js

@@ -11,16 +11,7 @@
  * and dropped, never allowed to stop the agent.
  */
 
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  renameSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from 'fs';
+import { promises as fsp } from 'fs';
 import { basename, dirname, extname, join } from 'path';
 import { randomUUID } from 'crypto';
 
@@ -56,20 +47,20 @@ function fileTraceRoot(inputPath) {
   return extname(basename(raw)) ? `${raw}.files` : raw;
 }
 
-function ensureDir(dir) {
-  mkdirSync(dir, { recursive: true });
+async function ensureDir(dir) {
+  await fsp.mkdir(dir, { recursive: true });
 }
 
-function atomicWriteJson(filePath, value) {
-  ensureDir(dirname(filePath));
-  const tmp = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-  writeFileSync(tmp, JSON.stringify(value), 'utf8');
-  renameSync(tmp, filePath);
+async function atomicWriteText(filePath, text) {
+  await ensureDir(dirname(filePath));
+  const tmp = `${filePath}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  await fsp.writeFile(tmp, text, 'utf8');
+  await fsp.rename(tmp, filePath);
 }
 
-function readJson(filePath) {
+async function readJson(filePath) {
   try {
-    return JSON.parse(readFileSync(filePath, 'utf8'));
+    return JSON.parse(await fsp.readFile(filePath, 'utf8'));
   } catch {
     return null;
   }
@@ -533,38 +524,40 @@ function traceToolToLegacy(trace, tool) {
   };
 }
 
-function collectTraceFiles(rootDir, sessionId = null) {
+async function readdirSafe(dir) {
+  try { return await fsp.readdir(dir, { withFileTypes: true }); }
+  catch { return []; }
+}
+
+async function collectTraceFiles(rootDir, sessionId = null) {
   const files = [];
-  const addFromRequestsDir = (requestsDir) => {
-    let entries = [];
-    try { entries = readdirSync(requestsDir, { withFileTypes: true }); }
-    catch { return; }
-    for (const entry of entries) {
+  const addFromRequestsDir = async (requestsDir) => {
+    for (const entry of await readdirSafe(requestsDir)) {
       if (!entry.isDirectory()) continue;
       const file = requestFilePath(join(requestsDir, entry.name));
-      if (existsSync(file)) files.push(file);
+      try {
+        await fsp.access(file);
+        files.push(file);
+      } catch { /* trace.json not yet written for this request dir */ }
     }
   };
   if (sessionId) {
-    addFromRequestsDir(sessionRequestsDir(rootDir, sessionId));
+    await addFromRequestsDir(sessionRequestsDir(rootDir, sessionId));
     return files;
   }
-  addFromRequestsDir(sessionRequestsDir(rootDir, null));
+  await addFromRequestsDir(sessionRequestsDir(rootDir, null));
   const sessionsRoot = join(rootDir, 'sessions');
-  let sessionEntries = [];
-  try { sessionEntries = readdirSync(sessionsRoot, { withFileTypes: true }); }
-  catch { return files; }
-  for (const entry of sessionEntries) {
+  for (const entry of await readdirSafe(sessionsRoot)) {
     if (!entry.isDirectory()) continue;
-    addFromRequestsDir(join(sessionsRoot, entry.name, 'debug', 'requests'));
+    await addFromRequestsDir(join(sessionsRoot, entry.name, 'debug', 'requests'));
   }
   return files;
 }
 
-function readTraceSummaries(rootDir, sessionId = null) {
+async function readTraceSummaries(rootDir, sessionId = null) {
   const traces = [];
-  for (const file of collectTraceFiles(rootDir, sessionId)) {
-    const trace = readJson(file);
+  for (const file of await collectTraceFiles(rootDir, sessionId)) {
+    const trace = await readJson(file);
     if (!trace || !trace.requestId) continue;
     traces.push({ trace, file, openedAt: Number(trace.openedAt || 0) });
   }
@@ -572,23 +565,20 @@ function readTraceSummaries(rootDir, sessionId = null) {
   return traces;
 }
 
-function countDirFiles(rootDir) {
+async function countDirFiles(rootDir) {
   let files = 0;
   let bytes = 0;
-  const walk = (dir) => {
-    let entries = [];
-    try { entries = readdirSync(dir, { withFileTypes: true }); }
-    catch { return; }
-    for (const entry of entries) {
+  const walk = async (dir) => {
+    for (const entry of await readdirSafe(dir)) {
       const p = join(dir, entry.name);
-      if (entry.isDirectory()) walk(p);
+      if (entry.isDirectory()) await walk(p);
       else {
         files += 1;
-        try { bytes += statSync(p).size; } catch { /* ignore */ }
+        try { bytes += (await fsp.stat(p)).size; } catch { /* ignore */ }
       }
     }
   };
-  walk(rootDir);
+  await walk(rootDir);
   return { files, bytes };
 }
 
@@ -605,6 +595,38 @@ export class DebugTrace {
   #flushTimer = null;
   /** @type {number} */
   #sequence = 0;
+  /**
+   * In-memory dream/event ring (authoritative copy; persisted async).
+   * @type {Array<object>}
+   */
+  #events = [];
+  /** @type {boolean} */
+  #eventsDirty = false;
+  /**
+   * Whether the on-disk events.json has been folded into #events yet. The
+   * events ring must merge prior-run history exactly once before any flush
+   * overwrites the file, or a live append landing before first hydrate would
+   * silently destroy cross-restart dream history.
+   * @type {boolean}
+   */
+  #eventsHydrated = false;
+  /** @type {NodeJS.Timeout|null} */
+  #eventFlushTimer = null;
+  /**
+   * One-time hydrate guard. Reads/maintenance load every on-disk trace into
+   * #requestCache exactly once; afterwards every query is served from memory
+   * with zero disk reads. The write path never hydrates — it only appends.
+   * @type {boolean}
+   */
+  #hydrated = false;
+  /** @type {Promise<void>|null} */
+  #hydratePromise = null;
+  /**
+   * Serializes async flushes so two overlapping flushes never interleave
+   * writes to the same trace file. close()/purge() await this to drain.
+   * @type {Promise<void>}
+   */
+  #flushChain = Promise.resolve();
 
   /**
    * @param {string} tracePath — Back-compatible path. If it looks like a DB
@@ -614,7 +636,9 @@ export class DebugTrace {
     const rootDir = fileTraceRoot(tracePath);
     if (!rootDir) throw new Error('DebugTrace requires a storage path');
     this.#rootDir = rootDir;
-    ensureDir(rootDir);
+    // Best-effort, fire-and-forget: atomicWriteText re-ensures the request
+    // subdir before every write, so a missed mkdir here is harmless.
+    ensureDir(rootDir).catch(() => {});
   }
 
   startTurn({ traceId, messageId = null, mode = null, turnNumber = null, sessionId = null, vpId = null, threadId = null, userPrompt = null } = {}) {
@@ -713,19 +737,20 @@ export class DebugTrace {
 
   logEvent({ traceId, eventType, eventData = null } = {}) {
     const id = randomUUID();
-    const file = join(this.#rootDir, 'events.json');
-    const existingEvents = readJson(file);
-    const events = Array.isArray(existingEvents) ? existingEvents : [];
-    events.push({
+    // In-memory authoritative ring; persisted async (fire-and-forget). The
+    // dream/event sink runs on the engine hot path, so it must not block on a
+    // synchronous read-modify-write of events.json.
+    this.#events.push({
       id,
       traceId: traceId || String(eventType || 'event'),
       eventType: eventType || 'event',
       eventData: safeJsonValue(eventData),
       createdAt: Date.now(),
     });
-    const trimmed = events.slice(-MAX_DREAM_EVENTS);
-    try { atomicWriteJson(file, trimmed); }
-    catch (err) { console.warn('[Yeaft] debug trace event write failed:', err?.message || err); }
+    if (this.#events.length > MAX_DREAM_EVENTS) {
+      this.#events = this.#events.slice(-MAX_DREAM_EVENTS);
+    }
+    this.#scheduleEventFlush();
     return id;
   }
 
@@ -736,24 +761,27 @@ export class DebugTrace {
     return this.logEvent({ traceId, eventType, eventData });
   }
 
-  queryByMessage(messageId) {
-    this.#flushPendingSync();
+  async queryByMessage(messageId) {
+    await this.#ensureHydrated();
+    await this.#drainWrites();
     const traces = this.#traceSummaries()
       .filter(({ trace }) => trace.messageId === messageId)
       .map(({ trace }) => trace);
     return this.#expandLegacy(traces);
   }
 
-  queryByTrace(traceId) {
-    this.#flushPendingSync();
+  async queryByTrace(traceId) {
+    await this.#ensureHydrated();
+    await this.#drainWrites();
     const traces = this.#traceSummaries()
       .filter(({ trace }) => trace.traceId === traceId || trace.requestId === traceId)
       .map(({ trace }) => trace);
     return this.#expandLegacy(traces);
   }
 
-  queryRecent(limit = 20) {
-    this.#flushPendingSync();
+  async queryRecent(limit = 20) {
+    await this.#ensureHydrated();
+    await this.#drainWrites();
     const lim = Math.max(1, Math.min(MAX_HISTORY_LIMIT, Number(limit) || MAX_HISTORY_LIMIT));
     return this.#traceSummaries()
       .slice(-lim)
@@ -761,8 +789,9 @@ export class DebugTrace {
       .flatMap(({ trace }) => traceToLegacyRows(trace));
   }
 
-  fetchRecentDebugHistory({ limit = MAX_HISTORY_LIMIT, dreamLimit = 5, sessionId = null, threadId = null, indexOnly = false, detailTurnId = null, search = '' } = {}) {
-    this.#flushPendingSync();
+  async fetchRecentDebugHistory({ limit = MAX_HISTORY_LIMIT, dreamLimit = 5, sessionId = null, threadId = null, indexOnly = false, detailTurnId = null, search = '' } = {}) {
+    await this.#ensureHydrated();
+    await this.#drainWrites();
     const lim = Math.max(1, Math.min(MAX_HISTORY_LIMIT, Number(limit) || MAX_HISTORY_LIMIT));
     const requestedDetailTurnId = typeof detailTurnId === 'string' && detailTurnId ? detailTurnId : null;
     const searchRegex = requestedDetailTurnId ? null : compileTraceSearchRegex(search);
@@ -797,8 +826,9 @@ export class DebugTrace {
     return { ...expanded, dreamEvents, hasMore: traces.length > selected.length, limit: lim, indexOnly: false };
   }
 
-  queryTools({ name = null, since = null } = {}) {
-    this.#flushPendingSync();
+  async queryTools({ name = null, since = null } = {}) {
+    await this.#ensureHydrated();
+    await this.#drainWrites();
     const tools = [];
     for (const { trace } of this.#traceSummaries()) {
       for (const tool of Array.isArray(trace.tools) ? trace.tools : []) {
@@ -812,8 +842,9 @@ export class DebugTrace {
     return tools.slice(0, 100);
   }
 
-  search(keyword) {
-    this.#flushPendingSync();
+  async search(keyword) {
+    await this.#ensureHydrated();
+    await this.#drainWrites();
     const needle = String(keyword || '').toLowerCase();
     if (!needle) return [];
     return this.#traceSummaries()
@@ -823,62 +854,79 @@ export class DebugTrace {
       .flatMap(({ trace }) => traceToLegacyRows(trace));
   }
 
-  stats() {
-    this.#flushPendingSync();
+  async stats() {
+    await this.#ensureHydrated();
+    await this.#drainWrites();
     const traces = this.#traceSummaries().map(({ trace }) => trace);
     const turnCount = traces.reduce((n, trace) => n + (Array.isArray(trace.loops) ? trace.loops.length : 0), 0);
     const toolCount = traces.reduce((n, trace) => n + (Array.isArray(trace.tools) ? trace.tools.length : 0), 0);
-    const events = readJson(join(this.#rootDir, 'events.json'));
-    const eventCount = Array.isArray(events) ? events.length : 0;
-    const { bytes } = countDirFiles(this.#rootDir);
+    const eventCount = this.#events.length;
+    const { bytes } = await countDirFiles(this.#rootDir);
     return { turnCount, toolCount, eventCount, dbSizeBytes: bytes, fileSizeBytes: bytes, requestCount: traces.length };
   }
 
-  cleanup(retention = REQUEST_RETENTION) {
-    this.#flushPendingSync();
+  async cleanup(retention = REQUEST_RETENTION) {
+    await this.#ensureHydrated();
+    await this.#drainWrites();
     const keep = Math.max(1, Math.min(REQUEST_RETENTION, Number(retention) || REQUEST_RETENTION));
-    const before = readTraceSummaries(this.#rootDir).length;
-    this.#pruneAll(keep);
-    const after = readTraceSummaries(this.#rootDir).length;
+    const before = this.#traceSummaries().length;
+    await this.#pruneAll(keep);
+    const after = this.#traceSummaries().length;
     return { deletedTurns: Math.max(0, before - after), deletedTools: 0, deletedEvents: 0, deletedRequests: Math.max(0, before - after) };
   }
 
-  compact() {
-    this.#flushPendingSync();
-    const before = countDirFiles(this.#rootDir).bytes;
-    this.cleanup(REQUEST_RETENTION);
-    const after = countDirFiles(this.#rootDir).bytes;
+  async compact() {
+    await this.#ensureHydrated();
+    const before = (await countDirFiles(this.#rootDir)).bytes;
+    await this.cleanup(REQUEST_RETENTION);
+    const after = (await countDirFiles(this.#rootDir)).bytes;
     return { before, after };
   }
 
-  purge() {
-    this.#flushPendingSync();
-    try { rmSync(this.#rootDir, { recursive: true, force: true }); }
+  async purge() {
+    await this.#drainWrites();
+    try { await fsp.rm(this.#rootDir, { recursive: true, force: true }); }
     catch { /* ignore */ }
-    ensureDir(this.#rootDir);
+    await ensureDir(this.#rootDir);
     this.#turnIndex.clear();
     this.#requestCache.clear();
+    this.#events = [];
+    this.#hydrated = false;
+    this.#hydratePromise = null;
+    this.#eventsHydrated = false;
   }
 
-  close() { this.#flushPendingSync(); }
+  async close() {
+    // #drainWrites() flushes pending writes itself; no separate #flushPending().
+    await this.#drainWrites();
+  }
+
+  /**
+   * Force all buffered trace + event writes to disk and await them. Unlike
+   * close() this does not tear down state, so the instance keeps accepting
+   * writes. Useful when a caller needs durability at a checkpoint.
+   */
+  async flush() {
+    await this.#drainWrites();
+  }
 
   #getOrCreateRequest({ traceId, turnNumber, messageId, mode, sessionId, vpId, threadId, userPrompt, now, turnRowId }) {
     const normalizedSessionId = sessionId || null;
-    let all = null;
     const isUsableExisting = (t) => (
       t?.sessionId === normalizedSessionId
       && t?.traceId === traceId
       && !(turnNumber === 1 && (t.loops || []).some(l => l.loopNumber === 1))
     );
-    const newestTrace = (items) => items
+    // Cache-only: the write path must NEVER touch disk (that was the O(N^2)
+    // event-loop stall). Every trace created in this process lives in
+    // #requestCache; same-traceId reuse and the legacy-duplicate-Loop-1 split
+    // both only concern traces opened in THIS run.
+    const sameSession = Array.from(this.#requestCache.values())
+      .filter(t => (t?.sessionId || null) === normalizedSessionId);
+    const existing = sameSession
       .filter(isUsableExisting)
       .sort((a, b) => ((a.openedAt || 0) - (b.openedAt || 0)) || String(a.requestKey || '').localeCompare(String(b.requestKey || '')))
       .at(-1) || null;
-    let existing = newestTrace(Array.from(this.#requestCache.values()));
-    if (!existing) {
-      all = this.#traceSummaries(normalizedSessionId).map(({ trace }) => trace);
-      existing = newestTrace(all);
-    }
     if (existing) {
       existing.updatedAt = now;
       this.#requestCache.set(existing.requestKey, existing);
@@ -886,7 +934,7 @@ export class DebugTrace {
     }
     const seq = (this.#sequence = (this.#sequence + 1) % 1_000_000);
     const requestKey = `${String(now).padStart(13, '0')}-${String(seq).padStart(6, '0')}-${safeDirComponent(traceId || turnRowId, 'request')}-${turnRowId.slice(0, 8)}`;
-    const requestId = turnNumber === 1 && all.some(t => t.traceId === traceId) ? turnRowId : traceId;
+    const requestId = turnNumber === 1 && sameSession.some(t => t.traceId === traceId) ? turnRowId : traceId;
     const trace = {
       version: TRACE_VERSION,
       requestKey,
@@ -911,27 +959,80 @@ export class DebugTrace {
   }
 
   #loadRequest(sessionId, requestKey) {
-    const cached = this.#requestCache.get(requestKey);
-    if (cached) return cached;
-    const file = tracePathFor(this.#rootDir, sessionId, requestKey);
-    const trace = readJson(file);
-    if (trace) this.#requestCache.set(requestKey, trace);
-    return trace;
+    // Cache-only by design: endTurn/logTool always run in the same turn that
+    // startTurn minted the trace, so it is already resident. Never read disk
+    // on the write path — that is the stall we are eliminating.
+    return this.#requestCache.get(requestKey) || null;
   }
 
   #traceSummaries(sessionId = null) {
-    const byKey = new Map(readTraceSummaries(this.#rootDir, sessionId).map(item => [item.trace.requestKey, item]));
+    // Cache-only: #ensureHydrated() has already merged every on-disk trace
+    // into #requestCache exactly once, so we never touch disk here. This is
+    // what turns the old O(N^2) per-query rescan into an in-memory filter.
+    const out = [];
     for (const trace of this.#requestCache.values()) {
       if (sessionId && trace.sessionId !== sessionId) continue;
       if (!trace?.requestId || !trace?.requestKey) continue;
-      byKey.set(trace.requestKey, {
+      out.push({
         trace,
         file: this.#traceFile(trace),
         openedAt: Number(trace.openedAt || 0),
       });
     }
-    return Array.from(byKey.values())
-      .sort((a, b) => ((a.openedAt || 0) - (b.openedAt || 0)) || String(a.trace?.requestKey || a.file).localeCompare(String(b.trace?.requestKey || b.file)));
+    return out.sort((a, b) => ((a.openedAt || 0) - (b.openedAt || 0)) || String(a.trace?.requestKey || a.file).localeCompare(String(b.trace?.requestKey || b.file)));
+  }
+
+  /**
+   * Load every on-disk trace into #requestCache exactly once. Live entries
+   * (created by this process) always win over their disk copy — a flush may
+   * be mid-flight, and the in-memory trace is the newer truth. Idempotent and
+   * concurrency-safe: overlapping callers await the same promise.
+   *
+   * Footprint trade-off (deliberate): this pins every session's full trace
+   * payload (systemPrompt + cumulative messages + rawRequest, each already
+   * byte-bounded) in #requestCache for the instance's lifetime — O(retention ×
+   * total sessions) memory instead of the old O(N²) per-query CPU rescan that
+   * stalled the event loop. Retention (10/session) and the byte caps keep it
+   * bounded, and the web path uses a single module-level instance. Follow-up if
+   * footprint ever bites: hydrate per queried sessionId, or keep only a
+   * lightweight summary resident and lazy-load full payloads on detailTurnId.
+   */
+  async #ensureHydrated() {
+    if (this.#hydrated) return;
+    if (this.#hydratePromise) return this.#hydratePromise;
+    this.#hydratePromise = (async () => {
+      const [summaries, storedEvents] = await Promise.all([
+        readTraceSummaries(this.#rootDir),
+        readJson(join(this.#rootDir, 'events.json')),
+      ]);
+      for (const { trace } of summaries) {
+        if (!trace?.requestKey) continue;
+        // Never clobber a live in-memory trace with its older disk snapshot.
+        if (!this.#requestCache.has(trace.requestKey)) {
+          this.#requestCache.set(trace.requestKey, trace);
+        }
+      }
+      if (Array.isArray(storedEvents)) this.#mergeStoredEvents(storedEvents);
+      this.#hydrated = true;
+      this.#hydratePromise = null;
+    })();
+    return this.#hydratePromise;
+  }
+
+  /**
+   * Fold on-disk events into the in-memory ring by id, preserving live order
+   * and bounding to MAX_DREAM_EVENTS. Unseen disk records are prepended (they
+   * are older); a live append therefore never erases prior-run history. Sets
+   * #eventsHydrated so this runs at most once.
+   */
+  #mergeStoredEvents(stored) {
+    if (this.#eventsHydrated) return;
+    this.#eventsHydrated = true;
+    if (!Array.isArray(stored) || stored.length === 0) return;
+    const seen = new Set(this.#events.map(e => e?.id).filter(Boolean));
+    const older = stored.filter(e => e && (!e.id || !seen.has(e.id)));
+    if (older.length === 0) return;
+    this.#events = [...older, ...this.#events].slice(-MAX_DREAM_EVENTS);
   }
 
   #traceWriteKey(trace) {
@@ -960,7 +1061,7 @@ export class DebugTrace {
     this.#requestCache.set(trace.requestKey, trace);
 
     if (force || item.dirtyLoops >= TRACE_FLUSH_DIRTY_LOOPS) {
-      this.#flushPendingSync();
+      this.#flushPending();
       return;
     }
     this.#scheduleFlushTimer(now);
@@ -972,27 +1073,108 @@ export class DebugTrace {
     const dueIn = Math.max(0, TRACE_FLUSH_INTERVAL_MS - (now - oldestDirtyAt));
     this.#flushTimer = setTimeout(() => {
       this.#flushTimer = null;
-      this.#flushPendingSync();
+      this.#flushPending();
     }, dueIn);
     if (typeof this.#flushTimer.unref === 'function') this.#flushTimer.unref();
   }
 
-  #flushPendingSync() {
+  #scheduleEventFlush() {
+    this.#eventsDirty = true;
+    if (this.#eventFlushTimer) return;
+    this.#eventFlushTimer = setTimeout(() => {
+      this.#eventFlushTimer = null;
+      this.#flushEvents();
+    }, TRACE_FLUSH_INTERVAL_MS);
+    if (typeof this.#eventFlushTimer.unref === 'function') this.#eventFlushTimer.unref();
+  }
+
+  /**
+   * Drain pending trace writes synchronously-from-the-caller's-view: snapshot
+   * each dirty trace to a JSON STRING now (so later in-place mutation of the
+   * live `loops` array can't tear the payload), then chain the async writes
+   * onto #flushChain. Returns nothing; callers that need durability await
+   * #drainWrites().
+   */
+  #flushPending() {
     if (this.#flushTimer) {
       clearTimeout(this.#flushTimer);
       this.#flushTimer = null;
     }
     const entries = Array.from(this.#pendingWrites.values());
-    if (entries.length === 0) return;
+    if (entries.length === 0) {
+      this.#flushEvents();
+      return;
+    }
     this.#pendingWrites.clear();
-    for (const { trace } of entries) {
-      try {
-        atomicWriteJson(this.#traceFile(trace), this.#serializableTrace(trace));
-      } catch (err) {
-        console.warn('[Yeaft] debug trace write failed:', err?.message || err);
+    // Capture point-in-time payloads synchronously (so later in-place mutation
+    // of the live `loops` array can't tear a payload), but remember each
+    // request key: a prune chained ahead of this write may evict the request
+    // before the write runs, and we must NOT resurrect a pruned trace on disk.
+    const jobs = entries.map(({ trace }) => ({
+      requestKey: trace.requestKey,
+      file: this.#traceFile(trace),
+      text: JSON.stringify(this.#serializableTrace(trace)),
+    }));
+    this.#chain(async () => {
+      for (const { requestKey, file, text } of jobs) {
+        // Skip if an earlier chained prune already evicted this request.
+        if (!this.#requestCache.has(requestKey)) continue;
+        try { await atomicWriteText(file, text); }
+        catch (err) { console.warn('[Yeaft] debug trace write failed:', err?.message || err); }
       }
+      try { await this.#pruneAll(REQUEST_RETENTION); }
+      catch (err) { console.warn('[Yeaft] debug trace prune failed:', err?.message || err); }
+    });
+    this.#flushEvents();
+  }
+
+  /**
+   * Append `task` to the single-writer flush mutex. Each link is isolated:
+   * a rejected predecessor can NEVER skip a later task (the classic
+   * `chain = chain.then(task)` footgun, where one rejection poisons every
+   * subsequent `.then(onFulfilled)` and silently stops all future writes).
+   * Here we always `await prev` inside a swallowing try/catch before running
+   * `task`, so the chain stays alive for the instance's lifetime.
+   */
+  #chain(task) {
+    const prev = this.#flushChain;
+    this.#flushChain = (async () => {
+      try { await prev; } catch { /* predecessor errors already logged */ }
+      await task();
+    })();
+    return this.#flushChain;
+  }
+
+  #flushEvents() {
+    if (!this.#eventsDirty) return;
+    this.#eventsDirty = false;
+    if (this.#eventFlushTimer) {
+      clearTimeout(this.#eventFlushTimer);
+      this.#eventFlushTimer = null;
+    }
+    const file = join(this.#rootDir, 'events.json');
+    this.#chain(async () => {
+      // Fold in any prior-run events we haven't loaded yet BEFORE overwriting,
+      // so a write that beats #ensureHydrated can't drop cross-restart history.
+      if (!this.#eventsHydrated) {
+        this.#mergeStoredEvents(await readJson(file));
+      }
+      const text = JSON.stringify(this.#events.slice(-MAX_DREAM_EVENTS));
+      try { await atomicWriteText(file, text); }
+      catch (err) { console.warn('[Yeaft] debug trace event write failed:', err?.message || err); }
+    });
+  }
+
+  /** Await every scheduled write (and prune) to settle. Used by close()/queries. */
+  async #drainWrites() {
+    this.#flushPending();
+    let prev = null;
+    // The chain can grow while we await (a query's flush appends more); loop
+    // until it stabilises so close() is a true barrier.
+    while (this.#flushChain !== prev) {
+      prev = this.#flushChain;
+      try { await prev; } catch { /* per-write errors already logged */ }
     }
-    this.#pruneAll(REQUEST_RETENTION);
   }
 
   #reconstructLastSnapshot(trace) {
@@ -1006,8 +1188,8 @@ export class DebugTrace {
   #readDreamEvents({ sessionId = null, dreamLimit = 5 } = {}) {
     const limit = Number.isFinite(Number(dreamLimit)) ? Math.max(0, Math.min(50, Number(dreamLimit))) : 5;
     if (limit <= 0) return [];
-    const storedEvents = readJson(join(this.#rootDir, 'events.json'));
-    const events = Array.isArray(storedEvents) ? storedEvents : [];
+    // In-memory ring (hydrated once); no disk read on the query path.
+    const events = this.#events;
     const out = [];
     for (const event of events.slice().reverse()) {
       const data = isPlainObject(event.eventData) ? event.eventData : {};
@@ -1029,22 +1211,25 @@ export class DebugTrace {
     return out.reverse();
   }
 
-  #pruneAll(keep) {
+  async #pruneAll(keep) {
+    // Cache-only enumeration; rm the pruned request dirs async. No disk scan.
     const sessions = new Set([null]);
-    for (const { trace } of this.#traceSummaries()) sessions.add(trace.sessionId || null);
-    for (const sid of sessions) this.#pruneSession(sid, keep);
+    for (const trace of this.#requestCache.values()) sessions.add(trace.sessionId || null);
+    for (const sid of sessions) await this.#pruneSession(sid, keep);
   }
 
-  #pruneSession(sessionId, keep = REQUEST_RETENTION) {
+  async #pruneSession(sessionId, keep = REQUEST_RETENTION) {
     const traces = this.#traceSummaries(sessionId);
     const activeCutoff = Date.now() - 6 * 60 * 60 * 1000;
     const protectedItems = traces.filter(item => item.trace?.active && Number(item.trace?.updatedAt || 0) >= activeCutoff);
     const pruneCandidates = traces.filter(item => !protectedItems.includes(item));
     const stale = pruneCandidates.slice(0, Math.max(0, traces.length - protectedItems.length - keep));
     for (const item of stale) {
-      try { rmSync(dirname(item.file), { recursive: true, force: true }); }
-      catch { /* ignore */ }
+      // Drop from cache first so subsequent queries never resurface it, even
+      // if the async rm is still in flight or fails.
       this.#requestCache.delete(item.trace.requestKey);
+      try { await fsp.rm(dirname(item.file), { recursive: true, force: true }); }
+      catch { /* ignore */ }
     }
   }
 
@@ -1066,17 +1251,18 @@ export class NullTrace {
   logTool() { return 'null'; }
   logEvent() { return 'null'; }
   event() { return 'null'; }
-  queryByMessage() { return { turns: [], tools: [], events: [] }; }
-  queryByTrace() { return { turns: [], tools: [], events: [] }; }
-  queryRecent() { return []; }
-  queryTools() { return []; }
-  search() { return []; }
-  stats() { return { turnCount: 0, toolCount: 0, eventCount: 0, dbSizeBytes: 0, fileSizeBytes: 0, requestCount: 0 }; }
-  cleanup() { return { deletedTurns: 0, deletedTools: 0, deletedEvents: 0, deletedRequests: 0 }; }
-  compact() { return { before: 0, after: 0 }; }
-  purge() {}
-  close() {}
-  fetchRecentDebugHistory() { return { loops: [], turns: [], dreamEvents: [] }; }
+  async queryByMessage() { return { turns: [], tools: [], events: [] }; }
+  async queryByTrace() { return { turns: [], tools: [], events: [] }; }
+  async queryRecent() { return []; }
+  async queryTools() { return []; }
+  async search() { return []; }
+  async stats() { return { turnCount: 0, toolCount: 0, eventCount: 0, dbSizeBytes: 0, fileSizeBytes: 0, requestCount: 0 }; }
+  async cleanup() { return { deletedTurns: 0, deletedTools: 0, deletedEvents: 0, deletedRequests: 0 }; }
+  async compact() { return { before: 0, after: 0 }; }
+  async purge() {}
+  async close() {}
+  async flush() {}
+  async fetchRecentDebugHistory() { return { loops: [], turns: [], dreamEvents: [] }; }
 }
 
 export function createTrace({ enabled, dbPath, dirPath }) {

package/yeaft/engine.js

@@ -96,7 +96,10 @@ const RETRY_DEFAULTS = Object.freeze({
   jitterRatio: 0.25,
 });
 
-const EXPLICIT_SKILL_COMMAND_RE = /^\/skill:([^\s]+)(\s+|$)/;
+// Accept the Yeaft-native alias and the Claude Code plugin-style command.
+// Autocomplete prefers /yeaft-skills:<name>; /skill:<name> remains supported
+// for older clients and typed history.
+const EXPLICIT_SKILL_COMMAND_RE = /^\/(?:skill|yeaft-skills):([^\s]+)(\s+|$)/;
 
 function parseExplicitSkillCommand(prompt) {
   if (typeof prompt !== 'string') {

package/yeaft/session.js

@@ -229,10 +229,12 @@ export async function loadSession(options = {}) {
     dirPath: yeaftDir,
   });
   // Hard cap debug history to the most recent 10 requests per Session. Trace
-  // failures are best-effort and must never stop the agent loop.
-  try { trace.cleanup?.(10); } catch (err) {
+  // failures are best-effort and must never stop the agent loop. cleanup() is
+  // now async (it hydrates the in-memory index, then prunes); run it
+  // fire-and-forget so session load never blocks on the startup disk scan.
+  Promise.resolve(trace.cleanup?.(10)).catch((err) => {
     console.warn('[Yeaft] trace.cleanup failed:', err?.message || err);
-  }
+  });
 
   // ─── 4. Create LLM adapter ────────────────────────────
   const adapter = await createLLMAdapter(config);
@@ -562,7 +564,7 @@ export async function loadSession(options = {}) {
       // Best-effort cleanup
     }
     try {
-      trace.close();
+      await trace.close();
     } catch {
       // Trace might not have close() (NullTrace)
     }

package/yeaft/sessions/pre-flow.js

@@ -266,15 +266,18 @@ export function buildRelevantScopes({ sessionId, chatId, vpId, extra } = {}) {
     scopes.push(`chat/${chatId}`);
     if (vpId) scopes.push(`chat/${chatId}/vp/${vpId}`);
   } else if (sessionId) {
-    // Read both legacy `group/<id>` and new `session/<id>` scopes so recall
-    // works regardless of which path the writers used for a given session.
-    // (Writers still emit `group/<id>` for back-compat; migration may have
-    // rewritten on-disk data to `session/<id>`.)
+    // Read every persisted Session spelling that can exist on disk. Current
+    // Dream writers use `sessions/<id>`; older readers/writers used singular
+    // `session/<id>` or legacy `group/<id>`. SQLite FTS is scope-filtered, so
+    // omitting any spelling makes valid indexed memory invisible.
+    scopes.push(`sessions/${sessionId}`);
+    scopes.push(`sessions/${sessionId}/user`);
     scopes.push(`session/${sessionId}`);
     scopes.push(`session/${sessionId}/user`);
     scopes.push(`group/${sessionId}`);
     scopes.push(`group/${sessionId}/user`);
     if (vpId) {
+      scopes.push(`sessions/${sessionId}/vp/${vpId}`);
       scopes.push(`session/${sessionId}/vp/${vpId}`);
       scopes.push(`group/${sessionId}/vp/${vpId}`);
     }

package/yeaft/web-bridge.js

@@ -76,7 +76,8 @@ import { getAgentRegistry, agentBelongsToScope } from './tools/agent.js';
 import { isPromptableAgentStatus } from './sub-agent/status.js';
 import { perfNowMs, recordAgentPerfTrace } from './perf-trace.js';
 
-const SKILL_COMMAND_PREFIX = 'skill:';
+const LEGACY_SKILL_COMMAND_PREFIX = 'skill:';
+const YEAFT_SKILL_COMMAND_PREFIX = 'yeaft-skills:';
 
 /** @type {import('./session.js').Session | null} */
 let session = null;
@@ -1854,9 +1855,15 @@ export function buildSkillSlashCommands(skillManager) {
   const descriptions = {};
   for (const skill of skillManager.list()) {
     if (!skill?.name || typeof skill.name !== 'string') continue;
-    const commandName = `${SKILL_COMMAND_PREFIX}${skill.name}`;
+    const commandName = `${YEAFT_SKILL_COMMAND_PREFIX}${skill.name}`;
     commands.push(commandName);
     descriptions[commandName] = skill.description || skill.trigger || 'Load Yeaft skill';
+
+    // Legacy alias for older typed commands and persisted drafts. Do not add it
+    // to the visible command list; autocomplete should show the same plugin-style
+    // names users see in Claude Code, e.g. /yeaft-skills:code-review.
+    const legacyCommandName = `${LEGACY_SKILL_COMMAND_PREFIX}${skill.name}`;
+    descriptions[legacyCommandName] = descriptions[commandName];
   }
   commands.sort((a, b) => a.localeCompare(b));
   return { commands, descriptions };
@@ -1876,12 +1883,13 @@ export function buildMergedSkillSlashCommands(skillManagers = []) {
 function broadcastSkillSlashCommands(sessionLike, extraSkillManagers = []) {
   const managers = [sessionLike?.skillManager, ...extraSkillManagers].filter(Boolean);
   const { commands, descriptions } = buildMergedSkillSlashCommands(managers);
-  const nonSkillCommands = (ctx.slashCommands || [])
-    .filter(cmd => !(typeof cmd === 'string' && cmd.startsWith(SKILL_COMMAND_PREFIX)));
+  const isYeaftSkillCommand = (cmd) => typeof cmd === 'string'
+    && (cmd.startsWith(LEGACY_SKILL_COMMAND_PREFIX) || cmd.startsWith(YEAFT_SKILL_COMMAND_PREFIX));
+  const nonSkillCommands = (ctx.slashCommands || []).filter(cmd => !isYeaftSkillCommand(cmd));
   const slashCommands = [...new Set([...nonSkillCommands, ...commands])];
   const slashCommandDescriptions = Object.fromEntries(
     Object.entries(ctx.slashCommandDescriptions || {})
-      .filter(([cmd]) => !(typeof cmd === 'string' && cmd.startsWith(SKILL_COMMAND_PREFIX)))
+      .filter(([cmd]) => !isYeaftSkillCommand(cmd))
   );
   Object.assign(slashCommandDescriptions, descriptions);
   ctx.slashCommands = slashCommands;
@@ -4813,6 +4821,12 @@ export function __testAppendTurnToSessionHistory(...args) {
  * Backwards-compat: when neither field is set, defaults to `vpId='default'`
  * which matches the pre-v0.1.754 behavior.
  */
+function resolveDreamTriggerSessionId(msg = {}) {
+  return typeof msg.sessionId === 'string' && msg.sessionId
+    ? msg.sessionId
+    : (typeof msg.groupId === 'string' && msg.groupId ? msg.groupId : null);
+}
+
 export function normalizeDreamResult(result) {
   const sessions = Array.isArray(result?.sessions) ? result.sessions : [];
   const targets = Array.isArray(result?.targets) ? result.targets : [];
@@ -4861,7 +4875,7 @@ export async function handleYeaftDreamTrigger(msg = {}) {
   // route the error event back to the right row and the per-group
   // "Run dream now" button would stay stuck on "Running…" forever
   // (review feedback from PR #757).
-  const sessionId = typeof msg.sessionId === 'string' && msg.sessionId ? msg.sessionId : null;
+  const sessionId = resolveDreamTriggerSessionId(msg);
   const vpId = !sessionId ? (msg.vpId || 'default') : null;
   const tag = sessionId ? { sessionId } : { vpId };
 
@@ -5069,7 +5083,7 @@ export async function handleYeaftFetchDebugHistory(msg = {}) {
   let hasMore = false;
   try {
     if (session?.trace && typeof session.trace.fetchRecentDebugHistory === 'function') {
-      const out = session.trace.fetchRecentDebugHistory({ limit, dreamLimit, sessionId, threadId, indexOnly, detailTurnId, search });
+      const out = await session.trace.fetchRecentDebugHistory({ limit, dreamLimit, sessionId, threadId, indexOnly, detailTurnId, search });
       loops = Array.isArray(out?.loops) ? out.loops : [];
       turns = Array.isArray(out?.turns) ? out.turns : [];
       dreamEvents = Array.isArray(out?.dreamEvents) ? out.dreamEvents : [];
@@ -5916,6 +5930,7 @@ export const __testHooks = {
     return getVpStatusBroker().transition(status);
   },
   decorateSessionsWithRuntimeState,
+  resolveDreamTriggerSessionId,
   async loadProjectRuntime(workDir) {
     return loadProjectRuntime(workDir);
   },