@yeaft/webchat-agent 0.1.440 → 0.1.442

package/claude.js

@@ -5,6 +5,24 @@ import ctx from './context.js';
 import { sendConversationList, sendOutput, sendError, handleAskUserQuestion } from './conversation.js';
 import { startSubagentWatcher, stopSubagentWatcher, cleanupSubagentWatchers } from './subagent.js';
 
+/**
+ * Detect whether a user message is a Claude Code compact summary.
+ * These appear after context compaction and should not be displayed in the UI.
+ *
+ * @param {string} text — user message content
+ * @returns {boolean}
+ */
+function isCompactSummary(text) {
+  if (!text || text.length < 200) return false;
+  // Claude Code compact summary always starts with this exact text
+  if (text.includes('This session is being continued from a previous conversation')) return true;
+  // Alternate compact summary indicator (Claude Code uses <system-reminder> blocks)
+  if (text.includes('The summary below covers the earlier portion of the conversation')) return true;
+  // Context compaction with numbered sections (1. Primary Request, 2. Key Technical Concepts, etc.)
+  if (/^[\s\S]*Summary:[\s\S]*\d+\.\s+(Primary Request|Key Technical|Current Work)/m.test(text)) return true;
+  return false;
+}
+
 /**
  * Determine maxContextTokens and autoCompactThreshold from model name.
  * Returns defaults suitable for the model's context window size.
@@ -423,7 +441,7 @@ async function processClaudeOutput(conversationId, claudeQuery, state) {
 
       // 过滤 compact summary 消息（compact_boundary 之后的 user 消息）
       if (message.type === 'user' && state._compactSummaryPending) {
-        console.log(`[${conversationId}] Filtering compact summary message`);
+        console.log(`[${conversationId}] Filtering compact summary message (pending flag)`);
         continue;
       }
       // compact 后的 <local-command-stdout>Compacted </local-command-stdout> 标记 summary 结束
@@ -431,6 +449,28 @@ async function processClaudeOutput(conversationId, claudeQuery, state) {
         state._compactSummaryPending = false;
       }
 
+      // 兜底过滤: Claude Code 的 compact summary 有时不触发 compact_boundary,
+      // 直接以 user 消息形式出现。通过内容特征检测过滤。
+      if (message.type === 'user') {
+        const userText = typeof message.content === 'string'
+          ? message.content
+          : (Array.isArray(message.content) ? message.content.map(b => b.text || '').join('') : '');
+        if (userText && isCompactSummary(userText)) {
+          console.log(`[${conversationId}] Filtering compact summary message (content match)`);
+          // 补发 compact 完成通知（如果之前没发过）
+          if (!state._compactCompleteSent) {
+            state._compactCompleteSent = true;
+            ctx.sendToServer({
+              type: 'compact_status',
+              conversationId,
+              status: 'completed',
+              message: 'Context compacted successfully'
+            });
+          }
+          continue;
+        }
+      }
+
       // 捕获 result 消息中的 usage 信息
       if (message.type === 'result') {
         // Log result message keys for debugging slash command output

package/package.json

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

package/unify/conversation/persist.js

@@ -20,9 +20,16 @@
 
 import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, renameSync, unlinkSync } from 'fs';
 import { join, basename } from 'path';
+import { isPermissionError } from '../init.js';
 
 // ─── Token estimation ────────────────────────────────────────
 
+/**
+ * Whether a permission warning has already been logged for this store instance.
+ * Used to avoid spamming the console with repeated warnings.
+ */
+let _permissionWarned = false;
+
 /** Rough token estimation: ~4 chars per token. */
 export function estimateTokens(text) {
   if (!text) return 0;
@@ -169,9 +176,20 @@ export class ConversationStore {
     this.#compactPath = join(dir, 'conversation', 'compact.md');
     this.#nextSeq = null;
 
-    // Ensure directories exist
+    // Ensure directories exist (graceful on permission errors)
     for (const d of [this.#convDir, this.#msgDir, this.#coldDir]) {
-      if (!existsSync(d)) mkdirSync(d, { recursive: true });
+      try {
+        if (!existsSync(d)) mkdirSync(d, { recursive: true, mode: 0o755 });
+      } catch (err) {
+        if (isPermissionError(err)) {
+          if (!_permissionWarned) {
+            console.warn(`[Yeaft] Cannot create directory ${d}: ${err.code} — persistence disabled`);
+            _permissionWarned = true;
+          }
+        } else {
+          throw err;
+        }
+      }
     }
   }
 
@@ -194,7 +212,18 @@ export class ConversationStore {
     };
 
     const filePath = join(this.#msgDir, `${id}.md`);
-    writeFileSync(filePath, serializeMessage(fullMsg), 'utf8');
+    try {
+      writeFileSync(filePath, serializeMessage(fullMsg), { encoding: 'utf8', mode: 0o644 });
+    } catch (err) {
+      if (isPermissionError(err)) {
+        if (!_permissionWarned) {
+          console.warn(`[Yeaft] Cannot write message ${id}: ${err.code} — message not persisted`);
+          _permissionWarned = true;
+        }
+        return fullMsg; // Return the message but don't persist
+      }
+      throw err;
+    }
 
     this.#nextSeq = seq + 1;
 
@@ -220,7 +249,18 @@ export class ConversationStore {
     const src = join(this.#msgDir, `${id}.md`);
     const dst = join(this.#coldDir, `${id}.md`);
     if (existsSync(src)) {
-      renameSync(src, dst);
+      try {
+        renameSync(src, dst);
+      } catch (err) {
+        if (isPermissionError(err)) {
+          if (!_permissionWarned) {
+            console.warn(`[Yeaft] Cannot move message ${id} to cold: ${err.code}`);
+            _permissionWarned = true;
+          }
+        } else {
+          throw err;
+        }
+      }
     }
   }
 
@@ -248,7 +288,18 @@ export class ConversationStore {
 
     const date = new Date().toISOString().split('T')[0];
     const entry = `\n## ${date}\n\n${summary}\n`;
-    writeFileSync(this.#compactPath, existing + entry, 'utf8');
+    try {
+      writeFileSync(this.#compactPath, existing + entry, { encoding: 'utf8', mode: 0o644 });
+    } catch (err) {
+      if (isPermissionError(err)) {
+        if (!_permissionWarned) {
+          console.warn(`[Yeaft] Cannot write compact summary: ${err.code}`);
+          _permissionWarned = true;
+        }
+      } else {
+        throw err;
+      }
+    }
   }
 
   /**
@@ -285,7 +336,18 @@ export class ConversationStore {
       'This file tracks the conversation state for the "one eternal conversation" model.',
     ].join('\n');
 
-    writeFileSync(this.#indexPath, content, 'utf8');
+    try {
+      writeFileSync(this.#indexPath, content, { encoding: 'utf8', mode: 0o644 });
+    } catch (err) {
+      if (isPermissionError(err)) {
+        if (!_permissionWarned) {
+          console.warn(`[Yeaft] Cannot write conversation index: ${err.code}`);
+          _permissionWarned = true;
+        }
+      } else {
+        throw err;
+      }
+    }
   }
 
   /**
@@ -296,14 +358,22 @@ export class ConversationStore {
       if (existsSync(dir)) {
         for (const file of readdirSync(dir)) {
           if (file.endsWith('.md')) {
-            unlinkSync(join(dir, file));
+            try {
+              unlinkSync(join(dir, file));
+            } catch (err) {
+              if (!isPermissionError(err)) throw err;
+            }
           }
         }
       }
     }
     // Reset compact
     if (existsSync(this.#compactPath)) {
-      writeFileSync(this.#compactPath, '', 'utf8');
+      try {
+        writeFileSync(this.#compactPath, '', { encoding: 'utf8', mode: 0o644 });
+      } catch (err) {
+        if (!isPermissionError(err)) throw err;
+      }
     }
     this.#nextSeq = 1;
     this.updateIndex({ totalMessages: 0, lastMessageId: null });

package/unify/engine.js

@@ -255,6 +255,7 @@ export class Engine {
 
   /**
    * Persist user message and assistant response to conversation store.
+   * Skipped in read-only mode (config._readOnly).
    *
    * @param {string} userContent
    * @param {string} assistantContent
@@ -263,6 +264,7 @@ export class Engine {
    */
   #persistMessages(userContent, assistantContent, mode, toolCalls) {
     if (!this.#conversationStore) return;
+    if (this.#config._readOnly) return;
 
     // Persist user message
     this.#conversationStore.append({
@@ -286,11 +288,13 @@ export class Engine {
 
   /**
    * Check and trigger consolidation if needed.
+   * Skipped in read-only mode.
    *
    * @returns {Promise<{ archivedCount: number, extractedCount: number }|null>}
    */
   async #maybeConsolidate() {
     if (!this.#conversationStore || !this.#memoryStore) return null;
+    if (this.#config._readOnly) return null;
 
     const budget = this.#config.messageTokenBudget || 8192;
     if (!shouldConsolidate(this.#conversationStore, budget)) return null;
@@ -520,7 +524,9 @@ export class Engine {
         yield { type: 'turn_end', turnNumber, stopReason };
 
         // ─── Post-query: StopHooks or Legacy ─────────────
-        if (this.#yeaftDir && this.#conversationStore) {
+        if (this.#config._readOnly) {
+          // Read-only mode: skip all persistence operations
+        } else if (this.#yeaftDir && this.#conversationStore) {
           // Full pipeline: persist + consolidate + dream gate
           // Note: stopHooks uses fastConfig for consolidation/dream (cheaper internal tasks)
           // but receives both configs — messages are persisted with primary model name

package/unify/index.js

@@ -4,7 +4,7 @@
  * Re-exports all public APIs for external consumption.
  */
 
-export { initYeaftDir, DEFAULT_YEAFT_DIR } from './init.js';
+export { initYeaftDir, DEFAULT_YEAFT_DIR, isWritable, isPermissionError } from './init.js';
 export { loadConfig, parseFrontmatter, loadMCPConfig } from './config.js';
 export { DebugTrace, NullTrace, createTrace } from './debug-trace.js';
 export {

package/unify/init.js

@@ -5,10 +5,70 @@
  * Creates default config.md, MEMORY.md, and conversation/index.md if missing.
  */
 
-import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, writeFileSync, accessSync, constants } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 
+/**
+ * Check if an error is a permission error (EACCES or EPERM).
+ * @param {Error} err
+ * @returns {boolean}
+ */
+export function isPermissionError(err) {
+  return err?.code === 'EACCES' || err?.code === 'EPERM';
+}
+
+/**
+ * Try to write a file, catching permission errors gracefully.
+ * @param {string} filePath
+ * @param {string} content
+ * @param {string[]} warnings — array to push warning messages into
+ */
+function safeWriteFile(filePath, content, warnings) {
+  try {
+    writeFileSync(filePath, content, { encoding: 'utf8', mode: 0o644 });
+  } catch (err) {
+    if (isPermissionError(err)) {
+      warnings.push(`Cannot write ${filePath}: ${err.code}`);
+    } else {
+      throw err;
+    }
+  }
+}
+
+/**
+ * Try to create a directory, catching permission errors gracefully.
+ * @param {string} dirPath
+ * @param {string[]} warnings — array to push warning messages into
+ * @returns {boolean} — true if directory exists (created or already existed)
+ */
+function safeMkdir(dirPath, warnings) {
+  try {
+    mkdirSync(dirPath, { recursive: true, mode: 0o755 });
+    return true;
+  } catch (err) {
+    if (isPermissionError(err)) {
+      warnings.push(`Cannot create directory ${dirPath}: ${err.code}`);
+      return existsSync(dirPath);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Check if a directory is writable.
+ * @param {string} dirPath
+ * @returns {boolean}
+ */
+export function isWritable(dirPath) {
+  try {
+    accessSync(dirPath, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /** Default directory for Yeaft data. */
 export const DEFAULT_YEAFT_DIR = join(homedir(), '.yeaft');
 
@@ -92,24 +152,34 @@ This file tracks the conversation state for the "one eternal conversation" model
  * Initialize the Yeaft data directory structure.
  *
  * @param {string} [dir] — Root directory path. Defaults to ~/.yeaft/
- * @returns {{ dir: string, created: string[] }} — The root dir and list of created paths
+ * @returns {{ dir: string, created: string[], writable: boolean, warnings: string[] }} — The root dir, list of created paths, writability status, and any warnings
  */
 export function initYeaftDir(dir) {
   const root = dir || DEFAULT_YEAFT_DIR;
   const created = [];
+  const warnings = [];
 
   // Ensure root exists
   if (!existsSync(root)) {
-    mkdirSync(root, { recursive: true });
-    created.push(root);
+    if (safeMkdir(root, warnings)) {
+      created.push(root);
+    }
+  }
+
+  // Check if root is writable early — if not, skip file creation
+  const writable = isWritable(root);
+  if (!writable) {
+    warnings.push(`Directory ${root} is not writable — session will run in read-only mode`);
+    return { dir: root, created, writable, warnings };
   }
 
   // Ensure all subdirectories exist
   for (const sub of SUBDIRS) {
     const fullPath = join(root, sub);
     if (!existsSync(fullPath)) {
-      mkdirSync(fullPath, { recursive: true });
-      created.push(fullPath);
+      if (safeMkdir(fullPath, warnings)) {
+        created.push(fullPath);
+      }
     }
   }
 
@@ -117,28 +187,28 @@ export function initYeaftDir(dir) {
   // config.json — default configuration (user edits this directly)
   const configJsonPath = join(root, 'config.json');
   if (!existsSync(configJsonPath)) {
-    writeFileSync(configJsonPath, DEFAULT_CONFIG_JSON, 'utf8');
+    safeWriteFile(configJsonPath, DEFAULT_CONFIG_JSON, warnings);
     created.push(configJsonPath);
   }
 
   const memoryPath = join(root, 'memory', 'MEMORY.md');
   if (!existsSync(memoryPath)) {
-    writeFileSync(memoryPath, DEFAULT_MEMORY, 'utf8');
+    safeWriteFile(memoryPath, DEFAULT_MEMORY, warnings);
     created.push(memoryPath);
   }
 
   const indexPath = join(root, 'conversation', 'index.md');
   if (!existsSync(indexPath)) {
-    writeFileSync(indexPath, DEFAULT_CONVERSATION_INDEX, 'utf8');
+    safeWriteFile(indexPath, DEFAULT_CONVERSATION_INDEX, warnings);
     created.push(indexPath);
   }
 
   // mcp.json.example — reference template for MCP server configuration
   const mcpExamplePath = join(root, 'mcp.json.example');
   if (!existsSync(mcpExamplePath)) {
-    writeFileSync(mcpExamplePath, DEFAULT_MCP_EXAMPLE, 'utf8');
+    safeWriteFile(mcpExamplePath, DEFAULT_MCP_EXAMPLE, warnings);
     created.push(mcpExamplePath);
   }
 
-  return { dir: root, created };
+  return { dir: root, created, writable, warnings };
 }

package/unify/memory/store.js

@@ -25,6 +25,7 @@
 
 import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync } from 'fs';
 import { join, basename } from 'path';
+import { isPermissionError } from '../init.js';
 
 // ─── Constants ──────────────────────────────────────────────────
 
@@ -37,6 +38,9 @@ export const MAX_ENTRIES = 200;
 /** Maximum MEMORY.md line count. */
 export const MAX_MEMORY_LINES = 200;
 
+/** Whether a permission warning has been logged for this store. */
+let _permissionWarned = false;
+
 // ─── Entry Parsing ──────────────────────────────────────────────
 
 /**
@@ -157,9 +161,20 @@ export class MemoryStore {
     this.#memoryPath = join(dir, 'memory', 'MEMORY.md');
     this.#scopesPath = join(dir, 'memory', 'scopes.md');
 
-    // Ensure directories exist
+    // Ensure directories exist (graceful on permission errors)
     for (const d of [this.#memoryDir, this.#entriesDir]) {
-      if (!existsSync(d)) mkdirSync(d, { recursive: true });
+      try {
+        if (!existsSync(d)) mkdirSync(d, { recursive: true, mode: 0o755 });
+      } catch (err) {
+        if (isPermissionError(err)) {
+          if (!_permissionWarned) {
+            console.warn(`[Yeaft] Cannot create directory ${d}: ${err.code} — memory persistence disabled`);
+            _permissionWarned = true;
+          }
+        } else {
+          throw err;
+        }
+      }
     }
   }
 
@@ -179,7 +194,18 @@ export class MemoryStore {
    * @param {string} content
    */
   writeProfile(content) {
-    writeFileSync(this.#memoryPath, content, 'utf8');
+    try {
+      writeFileSync(this.#memoryPath, content, { encoding: 'utf8', mode: 0o644 });
+    } catch (err) {
+      if (isPermissionError(err)) {
+        if (!_permissionWarned) {
+          console.warn(`[Yeaft] Cannot write MEMORY.md: ${err.code}`);
+          _permissionWarned = true;
+        }
+      } else {
+        throw err;
+      }
+    }
   }
 
   /**
@@ -286,7 +312,18 @@ export class MemoryStore {
       lines.push(`| ${scope} | ${info.count} | ${info.lastUpdated} |`);
     }
 
-    writeFileSync(this.#scopesPath, lines.join('\n') + '\n', 'utf8');
+    try {
+      writeFileSync(this.#scopesPath, lines.join('\n') + '\n', { encoding: 'utf8', mode: 0o644 });
+    } catch (err) {
+      if (isPermissionError(err)) {
+        if (!_permissionWarned) {
+          console.warn(`[Yeaft] Cannot write scopes.md: ${err.code}`);
+          _permissionWarned = true;
+        }
+      } else {
+        throw err;
+      }
+    }
   }
 
   // ─── Entries CRUD ─────────────────────────────────────
@@ -342,7 +379,18 @@ export class MemoryStore {
     };
 
     const filePath = join(this.#entriesDir, `${slug}.md`);
-    writeFileSync(filePath, serializeEntry(fullEntry), 'utf8');
+    try {
+      writeFileSync(filePath, serializeEntry(fullEntry), { encoding: 'utf8', mode: 0o644 });
+    } catch (err) {
+      if (isPermissionError(err)) {
+        if (!_permissionWarned) {
+          console.warn(`[Yeaft] Cannot write memory entry ${slug}: ${err.code}`);
+          _permissionWarned = true;
+        }
+        return slug; // Return slug but don't persist
+      }
+      throw err;
+    }
 
     return slug;
   }
@@ -378,7 +426,18 @@ export class MemoryStore {
     entry.frequency = (entry.frequency || 1) + 1;
     entry.updated_at = new Date().toISOString();
     const filePath = join(this.#entriesDir, `${name}.md`);
-    writeFileSync(filePath, serializeEntry(entry), 'utf8');
+    try {
+      writeFileSync(filePath, serializeEntry(entry), { encoding: 'utf8', mode: 0o644 });
+    } catch (err) {
+      if (isPermissionError(err)) {
+        if (!_permissionWarned) {
+          console.warn(`[Yeaft] Cannot bump frequency for ${name}: ${err.code}`);
+          _permissionWarned = true;
+        }
+      } else {
+        throw err;
+      }
+    }
   }
 
   // ─── Search / Filter ──────────────────────────────────
@@ -489,19 +548,31 @@ export class MemoryStore {
     if (existsSync(this.#entriesDir)) {
       for (const file of readdirSync(this.#entriesDir)) {
         if (file.endsWith('.md')) {
-          unlinkSync(join(this.#entriesDir, file));
+          try {
+            unlinkSync(join(this.#entriesDir, file));
+          } catch (err) {
+            if (!isPermissionError(err)) throw err;
+          }
         }
       }
     }
 
     // Clear MEMORY.md
     if (existsSync(this.#memoryPath)) {
-      writeFileSync(this.#memoryPath, '', 'utf8');
+      try {
+        writeFileSync(this.#memoryPath, '', { encoding: 'utf8', mode: 0o644 });
+      } catch (err) {
+        if (!isPermissionError(err)) throw err;
+      }
     }
 
     // Clear scopes.md
     if (existsSync(this.#scopesPath)) {
-      unlinkSync(this.#scopesPath);
+      try {
+        unlinkSync(this.#scopesPath);
+      } catch (err) {
+        if (!isPermissionError(err)) throw err;
+      }
     }
   }
 }

package/unify/session.js

@@ -13,7 +13,7 @@
  * a fully wired Session ready for queries.
  */
 
-import { initYeaftDir, DEFAULT_YEAFT_DIR } from './init.js';
+import { initYeaftDir, DEFAULT_YEAFT_DIR, isWritable } from './init.js';
 import { loadConfig, loadMCPConfig } from './config.js';
 import { createTrace } from './debug-trace.js';
 import { createLLMAdapter } from './llm/adapter.js';
@@ -85,12 +85,25 @@ export async function loadSession(options = {}) {
   if (debug !== undefined) overrides.debug = debug;
 
   const yeaftDir = overrides.dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
-  initYeaftDir(yeaftDir);
+  const initResult = initYeaftDir(yeaftDir);
   overrides.dir = yeaftDir;
 
+  // Log any warnings from directory initialization
+  for (const w of initResult.warnings) {
+    console.warn(`[Yeaft] ${w}`);
+  }
+
   // ─── 2. Load config ───────────────────────────────────
   const config = loadConfig(overrides);
 
+  // ─── 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.
+  if (!initResult.writable) {
+    config._readOnly = true;
+    console.warn(`[Yeaft] ${yeaftDir} is not writable — running in read-only mode`);
+  }
+
   // ─── 3. Create debug trace ─────────────────────────────
   const trace = createTrace({
     enabled: config.debug,

package/unify/stop-hooks.js

@@ -12,6 +12,10 @@
 
 import { shouldConsolidate, consolidate } from './memory/consolidate.js';
 import { checkDreamGate, incrementQueryCount, dream } from './memory/dream.js';
+import { isPermissionError } from './init.js';
+
+/** Track whether we've already warned about permission issues in stop hooks. */
+let _permissionWarned = false;
 
 /**
  * Run all stop hooks after a query completes.
@@ -77,7 +81,14 @@ export async function runStopHooks(context) {
       }
     }
   } catch (err) {
-    result.errors.push(`Persist failed: ${err.message}`);
+    if (isPermissionError(err)) {
+      if (!_permissionWarned) {
+        result.errors.push('Cannot write to ~/.yeaft/ — check directory permissions');
+        _permissionWarned = true;
+      }
+    } else {
+      result.errors.push(`Persist failed: ${err.message}`);
+    }
   }
 
   // 2. Consolidate check (non-blocking, but awaited for correctness)
@@ -102,7 +113,14 @@ export async function runStopHooks(context) {
       }
     }
   } catch (err) {
-    result.errors.push(`Consolidate failed: ${err.message}`);
+    if (isPermissionError(err)) {
+      if (!_permissionWarned) {
+        result.errors.push('Cannot write to ~/.yeaft/ — consolidation skipped');
+        _permissionWarned = true;
+      }
+    } else {
+      result.errors.push(`Consolidate failed: ${err.message}`);
+    }
   }
 
   // 3. Increment dream query counter
@@ -111,7 +129,11 @@ export async function runStopHooks(context) {
       incrementQueryCount(yeaftDir);
     }
   } catch (err) {
-    result.errors.push(`Dream counter failed: ${err.message}`);
+    if (isPermissionError(err)) {
+      // Silent — already warned about permission issues
+    } else {
+      result.errors.push(`Dream counter failed: ${err.message}`);
+    }
   }
 
   // 4. Dream gate check (fire-and-forget, background)
@@ -136,7 +158,9 @@ export async function runStopHooks(context) {
       }
     }
   } catch (err) {
-    result.errors.push(`Dream gate check failed: ${err.message}`);
+    if (!isPermissionError(err)) {
+      result.errors.push(`Dream gate check failed: ${err.message}`);
+    }
   }
 
   return result;

package/unify/web-bridge.js

@@ -32,6 +32,20 @@ let unifyConversationId = null;
 /** Current query mode: 'chat' or 'work' */
 let currentMode = 'chat';
 
+/** Whether we've already sent a permission warning to the UI */
+let _permissionDiagnosticSent = false;
+
+/**
+ * Check if an error message is a permission error.
+ * @param {string} msg
+ * @returns {boolean}
+ */
+function isPermissionErrorMsg(msg) {
+  if (!msg) return false;
+  const lower = msg.toLowerCase();
+  return lower.includes('eacces') || lower.includes('eperm') || lower.includes('permission denied');
+}
+
 /**
  * Send a unify_output message carrying claude_output-format data.
  * The server forwards this as-is to the web client.
@@ -251,17 +265,36 @@ export async function handleUnifyChat(msg) {
           break;
 
         // ── Errors ──
-        case 'error':
-          sendUnifyOutput({
-            type: 'assistant',
-            message: {
-              content: [{
-                type: 'text',
-                text: `⚠️ Error: ${event.error?.message || 'Unknown error'}`,
-              }],
-            },
-          });
+        case 'error': {
+          const errMsg = event.error?.message || 'Unknown error';
+          // Filter permission errors: show friendly one-time diagnostic instead of raw error
+          if (isPermissionErrorMsg(errMsg)) {
+            if (!_permissionDiagnosticSent) {
+              _permissionDiagnosticSent = true;
+              sendUnifyOutput({
+                type: 'assistant',
+                message: {
+                  content: [{
+                    type: 'text',
+                    text: '⚠️ Cannot write to ~/.yeaft/ directory — some features (memory, history) are unavailable. Please check directory permissions: `chmod -R u+rw ~/.yeaft/`',
+                  }],
+                },
+              });
+            }
+            // Don't show subsequent permission errors
+          } else {
+            sendUnifyOutput({
+              type: 'assistant',
+              message: {
+                content: [{
+                  type: 'text',
+                  text: `⚠️ Error: ${errMsg}`,
+                }],
+              },
+            });
+          }
           break;
+        }
 
         default:
           // Silently consume unknown events
@@ -306,15 +339,32 @@ export async function handleUnifyChat(msg) {
     }
 
     console.error('[Unify] query error:', err.message);
-    sendUnifyOutput({
-      type: 'assistant',
-      message: {
-        content: [{
-          type: 'text',
-          text: `⚠️ Session error: ${err.message}`,
-        }],
-      },
-    });
+
+    // Filter permission errors at the session level too
+    if (isPermissionErrorMsg(err.message)) {
+      if (!_permissionDiagnosticSent) {
+        _permissionDiagnosticSent = true;
+        sendUnifyOutput({
+          type: 'assistant',
+          message: {
+            content: [{
+              type: 'text',
+              text: '⚠️ Cannot write to ~/.yeaft/ directory — some features (memory, history) are unavailable. Please check directory permissions: `chmod -R u+rw ~/.yeaft/`',
+            }],
+          },
+        });
+      }
+    } else {
+      sendUnifyOutput({
+        type: 'assistant',
+        message: {
+          content: [{
+            type: 'text',
+            text: `⚠️ Session error: ${err.message}`,
+          }],
+        },
+      });
+    }
     // Still send result to clear processing state
     sendUnifyOutput({
       type: 'result',