@echomem/echo-memory-cloud-openclaw-plugin 0.1.1 → 0.1.2

package/lib/local-server.js

@@ -1,25 +1,25 @@
-import http from "node:http";
-import { spawn } from "node:child_process";
-import path from "node:path";
-import fs from "node:fs/promises";
-import fsSync from "node:fs";
-import { fileURLToPath } from "node:url";
-import { getLocalUiSetupState, saveLocalUiSetup } from "./config.js";
-import { scanFullWorkspace } from "./openclaw-memory-scan.js";
-import { readLastSyncState } from "./state.js";
-
-const BASE_PORT = 17823;
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const UI_HTML_PATH = path.join(__dirname, "local-ui.html");
-const UI_WORKDIR = path.join(__dirname, "local-ui");
-const UI_DIST_DIR = path.join(__dirname, "local-ui", "dist");
-const UI_NODE_MODULES_DIR = path.join(UI_WORKDIR, "node_modules");
-
-let _instance = null;
-let _bootstrapPromise = null;
-let _lastOpenedUrl = null;
-
-/* ── File Watcher + SSE ────────────────────────────────── */
+import http from "node:http";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import { fileURLToPath } from "node:url";
+import { getLocalUiSetupState, saveLocalUiSetup } from "./config.js";
+import { scanFullWorkspace } from "./openclaw-memory-scan.js";
+import { readLastSyncState } from "./state.js";
+
+const BASE_PORT = 17823;
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const UI_HTML_PATH = path.join(__dirname, "local-ui.html");
+const UI_WORKDIR = path.join(__dirname, "local-ui");
+const UI_DIST_DIR = path.join(__dirname, "local-ui", "dist");
+const UI_NODE_MODULES_DIR = path.join(UI_WORKDIR, "node_modules");
+
+let _instance = null;
+let _bootstrapPromise = null;
+let _lastOpenedUrl = null;
+
+/* ── File Watcher + SSE ────────────────────────────────── */
 
 const SKIP_DIRS = new Set(["node_modules", ".git", ".next", "dist", "build", "__pycache__", "logs", "completions", "delivery-queue", "browser", "canvas", "cron", "media"]);
 
@@ -66,10 +66,10 @@ function createFileWatcher(workspaceDir) {
   // Start watching
   watchRecursive(workspaceDir);
 
-  return {
-    sseClients,
-    broadcast,
-    close() {
+  return {
+    sseClients,
+    broadcast,
+    close() {
       if (debounceTimer) clearTimeout(debounceTimer);
       for (const w of watchers) { try { w.close(); } catch {} }
       watchers.length = 0;
@@ -91,209 +91,307 @@ function setCorsHeaders(res) {
   res.setHeader("Cache-Control", "no-store");
 }
 
-function sendJson(res, data) {
-  const body = JSON.stringify(data);
-  res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-  res.end(body);
-}
-
-async function pathExists(targetPath) {
-  try {
-    await fs.access(targetPath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function isLocalUiBuildReady() {
-  const indexPath = path.join(UI_DIST_DIR, "index.html");
-  if (!(await pathExists(indexPath))) {
-    return false;
-  }
-  const assetDir = path.join(UI_DIST_DIR, "assets");
-  if (!(await pathExists(assetDir))) {
-    return false;
-  }
-  try {
-    const assetNames = await fs.readdir(assetDir);
-    return assetNames.some((name) => name.endsWith(".js"));
-  } catch {
-    return false;
-  }
-}
-
-function getNpmCommand() {
-  return process.platform === "win32" ? "npm.cmd" : "npm";
-}
-
-function runNpmCommand(args, logger) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(getNpmCommand(), args, {
-      cwd: UI_WORKDIR,
-      env: process.env,
-      stdio: "pipe",
-      windowsHide: true,
-    });
-    const stdout = [];
-    const stderr = [];
-    child.stdout?.on("data", (chunk) => stdout.push(String(chunk)));
-    child.stderr?.on("data", (chunk) => stderr.push(String(chunk)));
-    child.on("error", (error) => reject(error));
-    child.on("close", (code) => {
-      if (code === 0) {
-        resolve();
-        return;
-      }
-      const output = [...stderr, ...stdout].join("").trim();
-      reject(new Error(output || `npm ${args.join(" ")} exited with code ${code ?? "unknown"}`));
-    });
-  }).catch((error) => {
-    logger?.warn?.(`[echo-memory] local-ui npm ${args.join(" ")} failed: ${String(error?.message ?? error)}`);
-    throw error;
-  });
-}
-
-export async function ensureLocalUiReady(cfg = {}, logger) {
-  if (await isLocalUiBuildReady()) {
-    return;
-  }
-  if (_bootstrapPromise) {
-    return _bootstrapPromise;
-  }
-
-  _bootstrapPromise = (async () => {
-    const hasNodeModules = await pathExists(UI_NODE_MODULES_DIR);
-    if (!hasNodeModules) {
-      if (!cfg?.localUiAutoInstall) {
-        throw new Error("local-ui dependencies are missing and auto-install is disabled");
-      }
-      logger?.info?.("[echo-memory] Installing local-ui dependencies...");
-      await runNpmCommand(["install"], logger);
-    }
-
-    if (!(await isLocalUiBuildReady())) {
-      logger?.info?.("[echo-memory] Building local-ui frontend...");
-      await runNpmCommand(["run", "build"], logger);
-    }
-
-    if (!(await isLocalUiBuildReady())) {
-      throw new Error("local-ui build did not produce expected dist assets");
-    }
-  })();
-
-  try {
-    await _bootstrapPromise;
-  } finally {
-    _bootstrapPromise = null;
-  }
-}
-
-function detectBrowserOpenSkipReason() {
-  if (process.env.CI) {
-    return "ci_environment";
-  }
-  if (process.env.SSH_CONNECTION || process.env.SSH_TTY) {
-    return "ssh_session";
-  }
-  if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
-    return "missing_display";
-  }
-  return null;
-}
-
-function getBrowserOpenCommand(url) {
-  if (process.platform === "win32") {
-    return {
-      command: "cmd",
-      args: ["/c", "start", "\"\"", url],
-    };
-  }
-  if (process.platform === "darwin") {
-    return {
-      command: "open",
-      args: [url],
-    };
-  }
-  if (process.platform === "linux") {
-    return {
-      command: "xdg-open",
-      args: [url],
-    };
-  }
-  return null;
-}
-
-export async function openUrlInDefaultBrowser(url, opts = {}) {
-  const { logger, force = false } = opts;
-  if (!force) {
-    const skipReason = detectBrowserOpenSkipReason();
-    if (skipReason) {
-      return { opened: false, reason: skipReason };
-    }
-  }
-  if (_lastOpenedUrl === url) {
-    return { opened: false, reason: "already_opened" };
-  }
-  const command = getBrowserOpenCommand(url);
-  if (!command) {
-    return { opened: false, reason: "unsupported_platform" };
-  }
-
-  try {
-    const child = spawn(command.command, command.args, {
-      detached: true,
-      stdio: "ignore",
-      windowsHide: true,
-    });
-    child.unref();
-    _lastOpenedUrl = url;
-    return { opened: true, reason: "opened" };
-  } catch (error) {
-    logger?.warn?.(`[echo-memory] browser open failed: ${String(error?.message ?? error)}`);
-    return { opened: false, reason: "spawn_failed" };
-  }
-}
-
-function readBody(req) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    req.on("data", (c) => chunks.push(c));
-    req.on("end", () => {
-      const rawText = Buffer.concat(chunks).toString("utf8");
-      if (!rawText.trim()) {
-        resolve({
-          ok: true,
-          body: {},
-          rawText,
-          parseError: null,
-        });
-        return;
-      }
-      try {
-        resolve({
-          ok: true,
-          body: JSON.parse(rawText),
-          rawText,
-          parseError: null,
-        });
-      } catch (error) {
-        resolve({
-          ok: false,
-          body: null,
-          rawText,
-          parseError: String(error?.message ?? error),
-        });
-      }
-    });
-    req.on("error", reject);
-  });
-}
-
-function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
-  const normalizedBase = path.resolve(workspaceDir) + path.sep;
-  const { apiClient, syncRunner, cfg, fileWatcher, logger } = opts;
-  const syncMemoryDir = cfg?.memoryDir ? path.resolve(cfg.memoryDir) : null;
+function sendJson(res, data) {
+  const body = JSON.stringify(data);
+  res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(body);
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isLocalUiBuildReady() {
+  const indexPath = path.join(UI_DIST_DIR, "index.html");
+  if (!(await pathExists(indexPath))) {
+    return false;
+  }
+  const assetDir = path.join(UI_DIST_DIR, "assets");
+  if (!(await pathExists(assetDir))) {
+    return false;
+  }
+  try {
+    const assetNames = await fs.readdir(assetDir);
+    return assetNames.some((name) => name.endsWith(".js"));
+  } catch {
+    return false;
+  }
+}
+
+function getNpmCommand() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function runNpmCommand(args, logger) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(getNpmCommand(), args, {
+      cwd: UI_WORKDIR,
+      env: process.env,
+      stdio: "pipe",
+      windowsHide: true,
+    });
+    const stdout = [];
+    const stderr = [];
+    child.stdout?.on("data", (chunk) => stdout.push(String(chunk)));
+    child.stderr?.on("data", (chunk) => stderr.push(String(chunk)));
+    child.on("error", (error) => reject(error));
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      const output = [...stderr, ...stdout].join("").trim();
+      reject(new Error(output || `npm ${args.join(" ")} exited with code ${code ?? "unknown"}`));
+    });
+  }).catch((error) => {
+    logger?.warn?.(`[echo-memory] local-ui npm ${args.join(" ")} failed: ${String(error?.message ?? error)}`);
+    throw error;
+  });
+}
+
+export async function ensureLocalUiReady(cfg = {}, logger) {
+  if (await isLocalUiBuildReady()) {
+    return;
+  }
+  if (_bootstrapPromise) {
+    return _bootstrapPromise;
+  }
+
+  _bootstrapPromise = (async () => {
+    const hasNodeModules = await pathExists(UI_NODE_MODULES_DIR);
+    if (!hasNodeModules) {
+      if (!cfg?.localUiAutoInstall) {
+        throw new Error("local-ui dependencies are missing and auto-install is disabled");
+      }
+      logger?.info?.("[echo-memory] Installing local-ui dependencies...");
+      await runNpmCommand(["install"], logger);
+    }
+
+    if (!(await isLocalUiBuildReady())) {
+      logger?.info?.("[echo-memory] Building local-ui frontend...");
+      await runNpmCommand(["run", "build"], logger);
+    }
+
+    if (!(await isLocalUiBuildReady())) {
+      throw new Error("local-ui build did not produce expected dist assets");
+    }
+  })();
+
+  try {
+    await _bootstrapPromise;
+  } finally {
+    _bootstrapPromise = null;
+  }
+}
+
+function detectBrowserOpenSkipReason() {
+  if (process.env.CI) {
+    return "ci_environment";
+  }
+  if (process.env.SSH_CONNECTION || process.env.SSH_TTY) {
+    return "ssh_session";
+  }
+  if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
+    return "missing_display";
+  }
+  return null;
+}
+
+function getBrowserOpenCommand(url) {
+  if (process.platform === "win32") {
+    return {
+      command: "cmd",
+      args: ["/c", "start", "\"\"", url],
+    };
+  }
+  if (process.platform === "darwin") {
+    return {
+      command: "open",
+      args: [url],
+    };
+  }
+  if (process.platform === "linux") {
+    return {
+      command: "xdg-open",
+      args: [url],
+    };
+  }
+  return null;
+}
+
+export async function openUrlInDefaultBrowser(url, opts = {}) {
+  const { logger, force = false } = opts;
+  if (!force) {
+    const skipReason = detectBrowserOpenSkipReason();
+    if (skipReason) {
+      return { opened: false, reason: skipReason };
+    }
+  }
+  if (_lastOpenedUrl === url) {
+    return { opened: false, reason: "already_opened" };
+  }
+  const command = getBrowserOpenCommand(url);
+  if (!command) {
+    return { opened: false, reason: "unsupported_platform" };
+  }
+
+  try {
+    const child = spawn(command.command, command.args, {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.unref();
+    _lastOpenedUrl = url;
+    return { opened: true, reason: "opened" };
+  } catch (error) {
+    logger?.warn?.(`[echo-memory] browser open failed: ${String(error?.message ?? error)}`);
+    return { opened: false, reason: "spawn_failed" };
+  }
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => {
+      const rawText = Buffer.concat(chunks).toString("utf8");
+      if (!rawText.trim()) {
+        resolve({
+          ok: true,
+          body: {},
+          rawText,
+          parseError: null,
+        });
+        return;
+      }
+      try {
+        resolve({
+          ok: true,
+          body: JSON.parse(rawText),
+          rawText,
+          parseError: null,
+        });
+      } catch (error) {
+        resolve({
+          ok: false,
+          body: null,
+          rawText,
+          parseError: String(error?.message ?? error),
+        });
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+function resolveStoredFilePath(workspaceDir, entry) {
+  const rawPath = entry?.filePath || entry?.file_path || entry?.path || null;
+  if (!rawPath) {
+    return null;
+  }
+  return path.isAbsolute(rawPath) ? path.normalize(rawPath) : path.resolve(workspaceDir, rawPath);
+}
+
+async function buildWorkspaceSyncView({ workspaceDir, syncMemoryDir, statePath }) {
+  const [lastState, files] = await Promise.all([
+    statePath ? readLastSyncState(statePath) : Promise.resolve(null),
+    scanFullWorkspace(workspaceDir),
+  ]);
+
+  const storedResults = Array.isArray(lastState?.results) ? lastState.results : [];
+  const resultMap = new Map();
+  for (const entry of storedResults) {
+    const storedPath = resolveStoredFilePath(workspaceDir, entry);
+    if (!storedPath) continue;
+    resultMap.set(storedPath, entry);
+  }
+
+  const DATE_RE = /^\d{4}-\d{2}-\d{2}/;
+  const eligibleAbsolutePaths = new Set();
+  const eligibleRelativePaths = [];
+
+  const fileStatuses = files.map((f) => {
+    const absPath = path.resolve(workspaceDir, f.relativePath);
+    const isPrivate =
+      f.relativePath.startsWith("memory/private/") ||
+      f.privacyLevel === "private";
+    const isSyncTarget =
+      Boolean(syncMemoryDir) && path.dirname(absPath) === syncMemoryDir;
+    const isDaily =
+      f.relativePath.startsWith("memory/") && DATE_RE.test(f.fileName);
+    const stored = resultMap.get(absPath) ?? null;
+    const storedStatus = String(stored?.status || "").trim().toLowerCase() || null;
+    const attemptedHash = stored?.contentHash || stored?.content_hash || null;
+    const successfulHash =
+      stored?.lastSuccessfulContentHash
+      || stored?.last_successful_content_hash
+      || (storedStatus && storedStatus !== "failed" ? attemptedHash : null);
+    const lastError = stored?.lastError || stored?.last_error || stored?.error || null;
+    const lastAttemptAt = stored?.lastAttemptAt || stored?.last_attempt_at || null;
+    const lastSuccessAt = stored?.lastSuccessAt || stored?.last_success_at || lastState?.finished_at || null;
+
+    if (isPrivate) {
+      return {
+        fileName: f.fileName,
+        relativePath: f.relativePath,
+        status: null,
+        syncEligible: false,
+        syncReason: "private",
+      };
+    }
+
+    if (!isSyncTarget) {
+      return {
+        fileName: f.fileName,
+        relativePath: f.relativePath,
+        status: "local",
+        syncEligible: false,
+        syncReason: "outside_memory_dir",
+      };
+    }
+
+    eligibleAbsolutePaths.add(absPath);
+    eligibleRelativePaths.push(f.relativePath);
+
+    let status = "new";
+    if (storedStatus === "failed" && attemptedHash && attemptedHash === f.contentHash) {
+      status = "failed";
+    } else if (successfulHash) {
+      status = isDaily || successfulHash === f.contentHash ? "synced" : "modified";
+    } else if (storedStatus === "failed") {
+      status = "modified";
+    }
+
+    return {
+      fileName: f.fileName,
+      relativePath: f.relativePath,
+      status,
+      syncEligible: true,
+      syncReason: "eligible",
+      lastError,
+      lastAttemptAt,
+      lastSuccessAt,
+    };
+  });
+
+  return {
+    lastState,
+    fileStatuses,
+    eligibleAbsolutePaths,
+    eligibleRelativePaths,
+  };
+}
+
+function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
+  const normalizedBase = path.resolve(workspaceDir) + path.sep;
+  const { apiClient, syncRunner, cfg, fileWatcher, logger } = opts;
+  const syncMemoryDir = cfg?.memoryDir ? path.resolve(cfg.memoryDir) : null;
 
   return async function handler(req, res) {
     setCorsHeaders(res);
@@ -316,7 +414,7 @@ function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
       return;
     }
 
-    // SSE endpoint — push file-change events to the frontend
+    // SSE endpoint — push file-change events to the frontend
     if (url.pathname === "/api/events") {
       res.writeHead(200, {
         "Content-Type": "text/event-stream",
@@ -412,7 +510,7 @@ function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
       return;
     }
 
-    if (url.pathname === "/api/auth-status") {
+    if (url.pathname === "/api/auth-status") {
       if (!apiClient) {
         sendJson(res, { connected: false, reason: "no_client" });
         return;
@@ -433,57 +531,57 @@ function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
       } catch (e) {
         sendJson(res, { connected: false, reason: "auth_failed", error: String(e?.message ?? e) });
       }
-      return;
-    }
-
-    if (url.pathname === "/api/setup-status") {
-      sendJson(res, getLocalUiSetupState(opts.pluginConfig ?? {}, cfg));
-      return;
-    }
-
-    if (url.pathname === "/api/setup-config" && req.method === "POST") {
-      try {
-        const bodyResult = await readBody(req);
-        if (!bodyResult.ok) {
-          logger?.warn?.(
-            `[echo-memory] invalid JSON for ${url.pathname}: ${bodyResult.parseError}; body=${JSON.stringify(bodyResult.rawText.slice(0, 400))}`,
-          );
-          res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
-          res.end(JSON.stringify({
-            ok: false,
-            error: "Invalid JSON body",
-            details: bodyResult.parseError,
-          }));
-          return;
-        }
-        const body = bodyResult.body;
-        const payload = {
-          ECHOMEM_API_KEY: typeof body.apiKey === "string" ? body.apiKey : "",
-          ECHOMEM_MEMORY_DIR: typeof body.memoryDir === "string" ? body.memoryDir : "",
-          ECHOMEM_LOCAL_ONLY_MODE:
-            typeof body.apiKey === "string" && body.apiKey.trim()
-              ? "false"
-              : "true",
-        };
-        const saveResult = saveLocalUiSetup(payload);
-        if (cfg) {
-          cfg.apiKey = payload.ECHOMEM_API_KEY.trim();
-          cfg.localOnlyMode = payload.ECHOMEM_LOCAL_ONLY_MODE === "true";
-          cfg.memoryDir = payload.ECHOMEM_MEMORY_DIR.trim() || cfg.memoryDir;
-        }
-        sendJson(res, {
-          ok: true,
-          ...saveResult,
-          setup: getLocalUiSetupState(opts.pluginConfig ?? {}, cfg),
-        });
-      } catch (error) {
-        res.writeHead(500, { "Content-Type": "application/json; charset=utf-8" });
-        res.end(JSON.stringify({ ok: false, error: String(error?.message ?? error) }));
-      }
-      return;
-    }
-
-    // Backend sources — authoritative COMPLETE list of files already synced to Echo cloud
+      return;
+    }
+
+    if (url.pathname === "/api/setup-status") {
+      sendJson(res, getLocalUiSetupState(opts.pluginConfig ?? {}, cfg));
+      return;
+    }
+
+    if (url.pathname === "/api/setup-config" && req.method === "POST") {
+      try {
+        const bodyResult = await readBody(req);
+        if (!bodyResult.ok) {
+          logger?.warn?.(
+            `[echo-memory] invalid JSON for ${url.pathname}: ${bodyResult.parseError}; body=${JSON.stringify(bodyResult.rawText.slice(0, 400))}`,
+          );
+          res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+          res.end(JSON.stringify({
+            ok: false,
+            error: "Invalid JSON body",
+            details: bodyResult.parseError,
+          }));
+          return;
+        }
+        const body = bodyResult.body;
+        const payload = {
+          ECHOMEM_API_KEY: typeof body.apiKey === "string" ? body.apiKey : "",
+          ECHOMEM_MEMORY_DIR: typeof body.memoryDir === "string" ? body.memoryDir : "",
+          ECHOMEM_LOCAL_ONLY_MODE:
+            typeof body.apiKey === "string" && body.apiKey.trim()
+              ? "false"
+              : "true",
+        };
+        const saveResult = saveLocalUiSetup(payload);
+        if (cfg) {
+          cfg.apiKey = payload.ECHOMEM_API_KEY.trim();
+          cfg.localOnlyMode = payload.ECHOMEM_LOCAL_ONLY_MODE === "true";
+          cfg.memoryDir = payload.ECHOMEM_MEMORY_DIR.trim() || cfg.memoryDir;
+        }
+        sendJson(res, {
+          ok: true,
+          ...saveResult,
+          setup: getLocalUiSetupState(opts.pluginConfig ?? {}, cfg),
+        });
+      } catch (error) {
+        res.writeHead(500, { "Content-Type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify({ ok: false, error: String(error?.message ?? error) }));
+      }
+      return;
+    }
+
+    // Backend sources — authoritative COMPLETE list of files already synced to Echo cloud
     if (url.pathname === "/api/backend-sources") {
       if (!apiClient) {
         sendJson(res, { ok: false, sources: [], error: "no_client" });
@@ -520,90 +618,21 @@ function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
     if (url.pathname === "/api/sync-status") {
       try {
         const statePath = syncRunner?.getStatePath() ?? null;
-        const [lastState, files] = await Promise.all([
-          statePath ? readLastSyncState(statePath) : Promise.resolve(null),
-          scanFullWorkspace(workspaceDir),
-        ]);
-        // Pure local comparison — no backend calls.
-        // Build map: absFilePath -> contentHash from last sync results
-        const lastSyncedMap = new Map();
-        if (Array.isArray(lastState?.results)) {
-          for (const r of lastState.results) {
-            // Support both camelCase (local dry-run) and snake_case (API response)
-            const fp = r.filePath || r.file_path;
-            if (fp && (r.status === "imported" || !r.status)) {
-              // Store contentHash if available; otherwise mark as synced without hash
-              // Note: older sync states may not have status field — treat as imported
-              lastSyncedMap.set(fp, r.contentHash || "__synced__");
-            }
-          }
-        }
-
-        // Daily files (YYYY-MM-DD*.md in memory/) are agent-generated and
-        // effectively immutable once written. We only check whether they've
-        // been synced before. Mutable files (root-level MEMORY.md, SOUL.md,
-        // etc.) need a content-hash comparison to detect edits.
-        const DATE_RE = /^\d{4}-\d{2}-\d{2}/;
-
-        const fileStatuses = files.map((f) => {
-          const absPath = path.resolve(workspaceDir, f.relativePath);
-          const isPrivate =
-            f.relativePath.startsWith("memory/private/") ||
-            f.privacyLevel === "private";
-          const isSyncTarget =
-            Boolean(syncMemoryDir) && path.dirname(absPath) === syncMemoryDir;
-
-          // Private files are never syncable
-          if (isPrivate) {
-            return { fileName: f.fileName, relativePath: f.relativePath, status: null };
-          }
-
-          // Files outside the configured sync target stay local-only in the UI.
-          if (!isSyncTarget) {
-            return { fileName: f.fileName, relativePath: f.relativePath, status: "local" };
-          }
-
-          const isDaily =
-            f.relativePath.startsWith("memory/") && DATE_RE.test(f.fileName);
-
-          if (!lastState) {
-            // Never synced at all — everything is new (except private)
-            return { fileName: f.fileName, relativePath: f.relativePath, status: "new" };
-          }
-
-          if (lastSyncedMap.has(absPath)) {
-            // Daily files don't change, skip expensive hash compare
-            if (isDaily) {
-              return {
-                fileName: f.fileName,
-                relativePath: f.relativePath,
-                status: "synced",
-                lastSynced: lastState.finished_at,
-              };
-            }
-            // Mutable file — compare hash if available
-            const savedHash = lastSyncedMap.get(absPath);
-            const status =
-              savedHash === "__synced__" || savedHash === f.contentHash
-                ? "synced"
-                : "modified";
-            return {
-              fileName: f.fileName,
-              relativePath: f.relativePath,
-              status,
-              lastSynced: lastState.finished_at,
-            };
-          }
-
-          // Not in sync state → new
-          return { fileName: f.fileName, relativePath: f.relativePath, status: "new" };
+        const syncView = await buildWorkspaceSyncView({
+          workspaceDir,
+          syncMemoryDir,
+          statePath,
         });
-
         sendJson(res, {
-          lastSyncAt: lastState?.finished_at ?? null,
-          syncedFileCount: lastSyncedMap.size,
-          fileStatuses,
+          lastSyncAt: syncView.lastState?.finished_at ?? null,
+          syncedFileCount: syncView.fileStatuses.filter((status) => status.status === 'synced').length,
+          syncTargetRoot: syncMemoryDir,
+          runInProgress: syncRunner?.isRunning?.() ?? false,
+          activeRun: syncRunner?.getActiveRunInfo?.() ?? null,
+          fileStatuses: syncView.fileStatuses,
         });
+        return;
+
       } catch (err) {
         res.writeHead(500, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ error: String(err?.message ?? err) }));
@@ -617,6 +646,14 @@ function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
         res.end(JSON.stringify({ error: "Sync not available" }));
         return;
       }
+      if (syncRunner.isRunning?.()) {
+        res.writeHead(409, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+          error: "A sync run is already in progress",
+          activeRun: syncRunner.getActiveRunInfo?.() ?? null,
+        }));
+        return;
+      }
       try {
         const result = await syncRunner.runSync("local-ui");
         sendJson(res, result);
@@ -627,73 +664,111 @@ function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
       return;
     }
 
-    if (url.pathname === "/api/sync-selected" && req.method === "POST") {
-      if (!syncRunner) {
-        res.writeHead(400, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Sync not available" }));
-        return;
-      }
-      try {
-        const bodyResult = await readBody(req);
-        if (!bodyResult.ok) {
-          logger?.warn?.(
-            `[echo-memory] invalid JSON for ${url.pathname}: ${bodyResult.parseError}; body=${JSON.stringify(bodyResult.rawText.slice(0, 400))}`,
-          );
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({
-            error: "Invalid JSON body for sync-selected",
-            details: bodyResult.parseError,
-            receivedBodyPreview: bodyResult.rawText.slice(0, 400),
-          }));
-          return;
-        }
-
-        const body = bodyResult.body;
-        const relativePaths = body.paths;
-        if (!Array.isArray(relativePaths) || relativePaths.length === 0) {
-          logger?.warn?.(
-            `[echo-memory] invalid sync-selected payload: expected non-empty paths array; body=${JSON.stringify(body).slice(0, 400)}`,
-          );
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({
-            error: "paths array required",
-            details: "Expected request body like {\"paths\":[\"memory/2026-03-17.md\"]}",
-            receivedBody: body,
-          }));
-          return;
-        }
-
-        const filterPaths = new Set();
-        const invalidPaths = [];
-        for (const rp of relativePaths) {
-          if (typeof rp !== "string" || !rp.trim()) {
-            invalidPaths.push(rp);
-            continue;
-          }
-          const absPath = path.resolve(workspaceDir, rp);
-          if (!absPath.startsWith(path.resolve(workspaceDir) + path.sep) || !absPath.endsWith(".md")) {
-            invalidPaths.push(rp);
-            continue;
-          }
-          filterPaths.add(absPath);
-        }
-
-        if (filterPaths.size === 0) {
-          logger?.warn?.(
-            `[echo-memory] sync-selected contained no valid markdown paths; requested=${JSON.stringify(relativePaths).slice(0, 400)}`,
-          );
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({
-            error: "No valid markdown paths to sync",
-            details: "All provided paths were outside the workspace or did not end with .md",
-            invalidPaths,
-            requestedPaths: relativePaths,
-          }));
-          return;
-        }
-        const result = await syncRunner.runSync("local-ui-selected", filterPaths);
-        sendJson(res, result);
-      } catch (e) {
+    if (url.pathname === "/api/sync-selected" && req.method === "POST") {
+      if (!syncRunner) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Sync not available" }));
+        return;
+      }
+      if (syncRunner.isRunning?.()) {
+        res.writeHead(409, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+          error: "A sync run is already in progress",
+          activeRun: syncRunner.getActiveRunInfo?.() ?? null,
+        }));
+        return;
+      }
+      try {
+        const bodyResult = await readBody(req);
+        if (!bodyResult.ok) {
+          logger?.warn?.(
+            `[echo-memory] invalid JSON for ${url.pathname}: ${bodyResult.parseError}; body=${JSON.stringify(bodyResult.rawText.slice(0, 400))}`,
+          );
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({
+            error: "Invalid JSON body for sync-selected",
+            details: bodyResult.parseError,
+            receivedBodyPreview: bodyResult.rawText.slice(0, 400),
+          }));
+          return;
+        }
+
+        const body = bodyResult.body;
+        const relativePaths = body.paths;
+        if (!Array.isArray(relativePaths) || relativePaths.length === 0) {
+          logger?.warn?.(
+            `[echo-memory] invalid sync-selected payload: expected non-empty paths array; body=${JSON.stringify(body).slice(0, 400)}`,
+          );
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({
+            error: "paths array required",
+            details: "Expected request body like {\"paths\":[\"memory/2026-03-17.md\"]}",
+            receivedBody: body,
+          }));
+          return;
+        }
+
+        const statePath = syncRunner?.getStatePath() ?? null;
+        const syncView = await buildWorkspaceSyncView({
+          workspaceDir,
+          syncMemoryDir,
+          statePath,
+        });
+        const statusMap = new Map(syncView.fileStatuses.map((status) => [status.relativePath, status]));
+        const requestedFilterPaths = new Set();
+        const requestedInvalidPaths = [];
+        for (const rp of relativePaths) {
+          if (typeof rp !== "string" || !rp.trim()) {
+            requestedInvalidPaths.push({ path: rp, reason: "invalid_path" });
+            continue;
+          }
+          const absPath = path.resolve(workspaceDir, rp);
+          if (!absPath.startsWith(path.resolve(workspaceDir) + path.sep) || !absPath.endsWith(".md")) {
+            requestedInvalidPaths.push({ path: rp, reason: "invalid_path" });
+            continue;
+          }
+          const status = statusMap.get(rp);
+          if (!status?.syncEligible || !syncView.eligibleAbsolutePaths.has(absPath)) {
+            requestedInvalidPaths.push({
+              path: rp,
+              reason: status?.syncReason || "not_sync_eligible",
+            });
+            continue;
+          }
+          requestedFilterPaths.add(absPath);
+        }
+
+        if (requestedInvalidPaths.length > 0) {
+          logger?.warn?.(
+            `[echo-memory] sync-selected rejected invalid or ineligible paths; requested=${JSON.stringify(relativePaths).slice(0, 400)}`,
+          );
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({
+            error: "One or more selected files cannot be synced",
+            details: "Selected files must be markdown files directly inside the configured memory directory.",
+            invalidPaths: requestedInvalidPaths,
+            requestedPaths: relativePaths,
+          }));
+          return;
+        }
+
+        if (requestedFilterPaths.size === 0) {
+          logger?.warn?.(
+            `[echo-memory] sync-selected contained no valid markdown paths; requested=${JSON.stringify(relativePaths).slice(0, 400)}`,
+          );
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({
+            error: "No valid markdown paths to sync",
+            details: "All provided paths were outside the configured memory directory or were not sync-eligible.",
+            requestedPaths: relativePaths,
+          }));
+          return;
+        }
+
+        const result = await syncRunner.runSync("local-ui-selected", requestedFilterPaths);
+        sendJson(res, result);
+        return;
+      } catch (e) {
         res.writeHead(500, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ error: String(e?.message ?? e) }));
       }
@@ -705,39 +780,46 @@ function createRequestHandler(workspaceDir, htmlContent, opts = {}) {
   };
 }
 
-export async function startLocalServer(workspaceDir, opts = {}) {
-  if (_instance) {
-    return _instance.url;
-  }
-
-  await ensureLocalUiReady(opts.cfg, opts.logger);
-  const htmlContent = await fs.readFile(UI_HTML_PATH, "utf8");
-  const fileWatcher = createFileWatcher(workspaceDir);
-  const unsubscribeSyncProgress = typeof opts.syncRunner?.onProgress === "function"
-    ? opts.syncRunner.onProgress((event) => {
-        const mapPath = (targetPath) => {
-          if (!targetPath) return null;
-          const relativePath = path.relative(workspaceDir, targetPath);
-          if (!relativePath || relativePath.startsWith("..")) return null;
-          return relativePath.replace(/\\/g, "/");
-        };
-
-        fileWatcher.broadcast({
-          type: "sync-progress",
-          progress: {
-            ...event,
-            queuedRelativePaths: event.phase === "started"
-              ? (event.currentFilePaths || []).map(mapPath).filter(Boolean)
-              : [],
-            currentRelativePaths: (event.currentFilePaths || []).map(mapPath).filter(Boolean),
-            completedRelativePaths: (event.completedFilePaths || []).map(mapPath).filter(Boolean),
-            failedRelativePaths: (event.failedFilePaths || []).map(mapPath).filter(Boolean),
-          },
-        });
-      })
-    : null;
-  const handler = createRequestHandler(workspaceDir, htmlContent, { ...opts, fileWatcher });
-  const server = http.createServer(handler);
+export async function startLocalServer(workspaceDir, opts = {}) {
+  if (_instance) {
+    return _instance.url;
+  }
+
+  await ensureLocalUiReady(opts.cfg, opts.logger);
+  const htmlContent = await fs.readFile(UI_HTML_PATH, "utf8");
+  const fileWatcher = createFileWatcher(workspaceDir);
+  const unsubscribeSyncProgress = typeof opts.syncRunner?.onProgress === "function"
+    ? opts.syncRunner.onProgress((event) => {
+        const mapPath = (targetPath) => {
+          if (!targetPath) return null;
+          const relativePath = path.relative(workspaceDir, targetPath);
+          if (!relativePath || relativePath.startsWith("..")) return null;
+          return relativePath.replace(/\\/g, "/");
+        };
+
+        fileWatcher.broadcast({
+          type: "sync-progress",
+          progress: {
+            ...event,
+            queuedRelativePaths: event.phase === "started"
+              ? (event.currentFilePaths || []).map(mapPath).filter(Boolean)
+              : [],
+            currentRelativePath: mapPath(event.currentFilePath),
+            currentRelativePaths: (event.currentFilePaths || []).map(mapPath).filter(Boolean),
+            completedRelativePaths: (event.completedFilePaths || []).map(mapPath).filter(Boolean),
+            failedRelativePaths: (event.failedFilePaths || []).map(mapPath).filter(Boolean),
+            recentFileResult: event.recentFileResult
+              ? {
+                  ...event.recentFileResult,
+                  relativePath: mapPath(event.recentFileResult.filePath),
+                }
+              : null,
+          },
+        });
+      })
+    : null;
+  const handler = createRequestHandler(workspaceDir, htmlContent, { ...opts, fileWatcher });
+  const server = http.createServer(handler);
 
   let port = null;
   for (let attempt = 0; attempt < 3; attempt++) {
@@ -751,19 +833,19 @@ export async function startLocalServer(workspaceDir, opts = {}) {
 
   if (port === null) {
     fileWatcher.close();
-    throw new Error(`Could not bind to ports ${BASE_PORT}–${BASE_PORT + 2}. All in use.`);
+    throw new Error(`Could not bind to ports ${BASE_PORT}–${BASE_PORT + 2}. All in use.`);
   }
 
   const url = `http://127.0.0.1:${port}`;
-  _instance = { server, url, fileWatcher, unsubscribeSyncProgress };
+  _instance = { server, url, fileWatcher, unsubscribeSyncProgress };
   return url;
 }
 
 export function stopLocalServer() {
-  if (_instance) {
-    _instance.server.close();
-    if (_instance.fileWatcher) _instance.fileWatcher.close();
-    if (_instance.unsubscribeSyncProgress) _instance.unsubscribeSyncProgress();
-    _instance = null;
-  }
-}
+  if (_instance) {
+    _instance.server.close();
+    if (_instance.fileWatcher) _instance.fileWatcher.close();
+    if (_instance.unsubscribeSyncProgress) _instance.unsubscribeSyncProgress();
+    _instance = null;
+  }
+}