@xyagent/cli 0.0.1

package/src-ext/core/scanWorkspaces.mjs

@@ -0,0 +1,842 @@
+/**
+ * scanWorkspaces.mjs — relay RPC `workspaces.scan` implementation
+ *
+ * Exports:
+ *   readOpenClawWorkspaces({ gatewayId, limit, includeBranch, workspaceRoot? })
+ *   readClaudeWorkspaces({ gatewayId, limit, includeBranch, claudeJsonPath? })
+ *   readCodexWorkspaces({ gatewayId, limit, includeBranch, codexHome? })
+ *   readHermesWorkspaces()
+ *   scanWorkspacesByRuntime({ runtimeKind, gatewayId, params })
+ */
+
+import crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { defaultWorkspacePath } from "./defaultWorkspace.mjs";
+
+// ─── constants ───────────────────────────────────────────────────────────────
+
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+const HARD_TIMEOUT_MS = 5000;
+const GIT_BRANCH_TIMEOUT_MS = 200;
+
+// Runtime metadata — agentKind values must match dart stub ScannedAgentGroup.kind exactly.
+const RUNTIME_META = {
+  OpenClaw: {
+    agentKind: "OpenClaw",
+    emoji: "🐼",
+    tagline: "开源多模态智能体运行时",
+    idPrefix: "oc",
+  },
+  "Claude Code": {
+    agentKind: "Claude Code",
+    emoji: "🧠",
+    tagline: "Anthropic 官方 AI 编程助手",
+    idPrefix: "cc",
+  },
+  Codex: {
+    agentKind: "Codex",
+    emoji: "💡",
+    tagline: "OpenAI Codex CLI 智能体",
+    idPrefix: "cx",
+  },
+  Hermes: {
+    agentKind: "Hermes",
+    emoji: "🪽",
+    tagline: "Agentlink 内置对话智能体",
+    idPrefix: "hm",
+  },
+};
+
+// runtimeKind string → RUNTIME_META key
+const RUNTIME_KIND_MAP = {
+  openclaw: "OpenClaw",
+  "claude code": "Claude Code",
+  claude: "Claude Code",
+  codex: "Codex",
+  hermes: "Hermes",
+};
+
+// ─── utility functions ───────────────────────────────────────────────────────
+
+/**
+ * Stable, deterministic workspace ID: <prefix>-<sha256(absolutePath).hex.slice(0,12)>
+ */
+export function pathToId(prefix, absolutePath) {
+  const hash = crypto.createHash("sha256").update(absolutePath, "utf8").digest("hex");
+  return `${prefix}-${hash.slice(0, 12)}`;
+}
+
+/**
+ * Shorten absolutePath to tilde form for display.
+ */
+export function tildify(absolutePath, home = os.homedir()) {
+  if (absolutePath === home) return "~";
+  if (absolutePath.startsWith(home + path.sep)) {
+    return "~" + absolutePath.slice(home.length);
+  }
+  return absolutePath;
+}
+
+/**
+ * Host metadata object.
+ */
+export function hostMeta(gatewayId) {
+  return {
+    id: gatewayId,
+    label: os.hostname(),
+    platform: process.platform,
+  };
+}
+
+/**
+ * Get the current git branch for a directory. Returns null on timeout or error.
+ * @param {string} absolutePath
+ * @param {number} timeoutMs
+ * @returns {Promise<string|null>}
+ */
+export function gitBranch(absolutePath, timeoutMs = GIT_BRANCH_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      child.kill();
+      resolve(null);
+    }, timeoutMs);
+
+    const child = execFile(
+      "git",
+      ["symbolic-ref", "--short", "HEAD"],
+      { cwd: absolutePath, encoding: "utf8" },
+      (err, stdout) => {
+        clearTimeout(timer);
+        if (err) {
+          resolve(null);
+        } else {
+          resolve(stdout.trim() || null);
+        }
+      },
+    );
+  });
+}
+
+/**
+ * Run gitBranch for multiple paths concurrently, bounded by CPU count.
+ */
+async function resolveBranches(paths, includeBranch) {
+  if (!includeBranch) return paths.map(() => null);
+  const concurrency = Math.max(1, os.cpus().length);
+  const results = new Array(paths.length).fill(null);
+  for (let i = 0; i < paths.length; i += concurrency) {
+    const batch = paths.slice(i, i + concurrency);
+    const settled = await Promise.allSettled(
+      batch.map((p) => gitBranch(p)),
+    );
+    for (let j = 0; j < batch.length; j++) {
+      const r = settled[j];
+      results[i + j] = r.status === "fulfilled" ? r.value : null;
+    }
+  }
+  return results;
+}
+
+// ─── OpenClaw reader ─────────────────────────────────────────────────────────
+
+/**
+ * Read OpenClaw workspaces.
+ *
+ * OpenClaw 模型：workspace = agent 的家目录本身（cwd / 记忆目录），**1 个 agent
+ * 对应 1 个 workspace**（见官方 concepts/agent-workspace）。所以这里返回每个 agent
+ * 配置的 workspace 目录「本身」，而不是去列某个根目录下的项目子目录（那是
+ * Claude/Codex 的「多项目」口径，不适用于 OpenClaw）。
+ *
+ * 解析来源（[resolveOpenClawAgentWorkspaceDirs]，对齐 bin/agentlink）：
+ *   ~/.openclaw/openclaw.json 的 agents.list[].workspace（缺省继承
+ *   agents.defaults.workspace）；list 为空时即默认那一个。
+ *
+ * @param {object} opts
+ * @param {string} opts.gatewayId
+ * @param {number} opts.limit
+ * @param {boolean} opts.includeBranch
+ * @param {string} [opts.workspaceRoot]  测试注入：视作唯一 agent 的 workspace 目录
+ */
+export async function readOpenClawWorkspaces({
+  gatewayId,
+  limit,
+  includeBranch,
+  workspaceRoot,
+}) {
+  const warnings = [];
+
+  let dirs;
+  if (workspaceRoot) {
+    dirs = [path.resolve(workspaceRoot)];
+  } else {
+    try {
+      dirs = resolveOpenClawAgentWorkspaceDirs();
+    } catch (err) {
+      warnings.push(`OpenClaw: failed to resolve workspace dirs: ${err.message}`);
+      return { workspaces: [], warnings, truncated: false };
+    }
+  }
+
+  // 去重 + 只保留真实存在的目录（不存在不算错误：agent 可能还没初始化 workspace）。
+  const seen = new Set();
+  const existing = [];
+  for (const d of dirs) {
+    const abs = path.resolve(d);
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    try {
+      if (fs.statSync(abs).isDirectory()) existing.push(abs);
+    } catch (err) {
+      if (err.code === "EACCES" || err.code === "EPERM") {
+        warnings.push(`OpenClaw: permission denied reading ${abs}: ${err.message}`);
+      }
+      // ENOENT / 其它：静默跳过（未初始化的 workspace 不报错）
+    }
+  }
+
+  const effectiveLimit = clampLimit(limit);
+  const truncated = existing.length > effectiveLimit;
+  const selected = existing.slice(0, effectiveLimit);
+
+  const branches = await resolveBranches(selected, includeBranch);
+  const meta = RUNTIME_META["OpenClaw"];
+  const workspaces = selected.map((abs, i) => ({
+    id: pathToId(meta.idPrefix, abs),
+    name: path.basename(abs),
+    path: abs,
+    absolutePath: abs,
+    branch: branches[i],
+    lastUsedAtMs: null,
+  }));
+
+  return { workspaces, warnings, truncated };
+}
+
+// ─── Claude Code reader ───────────────────────────────────────────────────────
+
+/**
+ * 从 ~/.claude.json 的 projects 中挑出应展示的项目路径。
+ *
+ * 入选条件（任一满足）：
+ *   1. 显式信任：hasTrustDialogAccepted === true
+ *   2. 实际用过：存在 lastSessionId / lastCost / lastDuration（跑过 session 的痕迹）。
+ *      新版 Claude Code 在祖先目录已信任时子目录项目自身标记为 false，仅靠条件 1 会漏掉
+ *      用户真正在用的项目（P0：「我电脑上项目都没扫出来」）。
+ *   3. 信任继承：某个显式信任目录是该路径的祖先（与 Claude Code 的目录信任语义一致）。
+ *
+ * @param {Record<string, object>} projects  ~/.claude.json 的 projects 对象
+ * @returns {string[]} 原始路径列表（未 normalize）
+ */
+export function selectClaudeProjectPaths(projects) {
+  const entries = Object.entries(projects).filter(([, meta]) => meta && typeof meta === "object");
+  const explicitlyTrusted = entries
+    .filter(([, meta]) => meta.hasTrustDialogAccepted === true)
+    .map(([p]) => p);
+  const trustedPrefixes = explicitlyTrusted.map((p) => (p.endsWith(path.sep) ? p : p + path.sep));
+
+  const hasUsageEvidence = (meta) =>
+    (typeof meta.lastSessionId === "string" && meta.lastSessionId !== "") ||
+    typeof meta.lastCost === "number" ||
+    typeof meta.lastDuration === "number";
+  const hasTrustedAncestor = (p) => trustedPrefixes.some((prefix) => p.startsWith(prefix));
+
+  return entries
+    .filter(
+      ([p, meta]) =>
+        meta.hasTrustDialogAccepted === true || hasUsageEvidence(meta) || hasTrustedAncestor(p),
+    )
+    .map(([p]) => p);
+}
+
+/**
+ * Read workspaces from Claude Code's ~/.claude.json trusted projects list.
+ *
+ * @param {object} opts
+ * @param {string} opts.gatewayId
+ * @param {number} opts.limit
+ * @param {boolean} opts.includeBranch
+ * @param {string} [opts.claudeJsonPath]  override for testing
+ */
+export async function readClaudeWorkspaces({
+  gatewayId,
+  limit,
+  includeBranch,
+  claudeJsonPath,
+}) {
+  const warnings = [];
+  const effectiveLimit = clampLimit(limit);
+  const home = os.homedir();
+
+  // align-runtime-default-workspace: 合成 default entry（无条件，不建目录，按 path 去重）
+  const meta = RUNTIME_META["Claude Code"];
+  const defaultPath = defaultWorkspacePath("claude");
+  const defaultEntry = {
+    id: pathToId(meta.idPrefix, defaultPath),
+    name: "default",
+    path: defaultPath,
+    absolutePath: defaultPath,
+    branch: null,
+    lastUsedAtMs: null,
+  };
+
+  const filePath = claudeJsonPath ?? path.join(home, ".claude.json");
+
+  let trustedPaths;
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const obj = JSON.parse(raw);
+    const projects = obj?.projects;
+    if (!projects || typeof projects !== "object") {
+      trustedPaths = [];
+    } else {
+      trustedPaths = selectClaudeProjectPaths(projects);
+    }
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      if (err.code === "EACCES" || err.code === "EPERM") {
+        warnings.push(`Claude Code: permission denied reading ${filePath}: ${err.message}`);
+      }
+      // For ENOENT: file doesn't exist — not an error per spec
+    }
+    // 即使文件不存在，仍返回 default entry
+    return { workspaces: [defaultEntry], warnings, truncated: false };
+  }
+
+  // Normalize paths: expand ~ and resolve to absolute
+  const normalizedPaths = trustedPaths.map((p) => path.resolve(p.replace(/^~/, home)));
+
+  // Filter to existing paths only
+  const existing = normalizedPaths.filter((p) => {
+    try { return fs.existsSync(p); } catch { return false; }
+  });
+
+  // 去重：排除与 defaultPath 相同的路径（default 优先，排首位）
+  const dedupedExisting = existing.filter((p) => p !== defaultPath);
+
+  // 将 default 计入 limit 总数（default 排首位，先占 1 个槽位）
+  const totalCount = 1 + dedupedExisting.length;
+  const truncated = totalCount > effectiveLimit;
+  // effectiveLimit - 1 给剩余项目（default 已占 1 位）
+  const remainingLimit = Math.max(0, effectiveLimit - 1);
+  const selected = dedupedExisting.slice(0, remainingLimit);
+
+  const branches = await resolveBranches(selected, includeBranch);
+
+  const workspaces = [
+    defaultEntry,
+    ...selected.map((absPath, i) => ({
+      id: pathToId(meta.idPrefix, absPath),
+      name: path.basename(absPath),
+      path: absPath,
+      absolutePath: absPath,
+      branch: branches[i],
+      lastUsedAtMs: null,
+    })),
+  ];
+
+  return { workspaces, warnings, truncated };
+}
+
+// ─── Codex reader ─────────────────────────────────────────────────────────────
+
+/**
+ * Read workspaces from Codex session jsonl files.
+ * Reads the first line of each .jsonl file to extract `cwd`.
+ * Dedupes by absolutePath.
+ *
+ * @param {object} opts
+ * @param {string} opts.gatewayId
+ * @param {number} opts.limit
+ * @param {boolean} opts.includeBranch
+ * @param {string} [opts.codexHome]  override for testing (~/.codex)
+ */
+export async function readCodexWorkspaces({
+  gatewayId,
+  limit,
+  includeBranch,
+  codexHome,
+}) {
+  const warnings = [];
+  const effectiveLimit = clampLimit(limit);
+  const home = os.homedir();
+
+  // align-runtime-default-workspace: 合成 default entry（无条件，不建目录，按 path 去重）
+  const meta = RUNTIME_META["Codex"];
+  const defaultPath = defaultWorkspacePath("codex");
+  const defaultEntry = {
+    id: pathToId(meta.idPrefix, defaultPath),
+    name: "default",
+    path: defaultPath,
+    absolutePath: defaultPath,
+    branch: null,
+    lastUsedAtMs: null,
+  };
+
+  const baseDir = codexHome ?? path.join(home, ".codex");
+  const sessionDirs = [
+    path.join(baseDir, "sessions"),
+    path.join(baseDir, "archived_sessions"),
+  ];
+
+  const cwdByPath = new Map(); // absolutePath → true (for dedupe)
+
+  for (const dir of sessionDirs) {
+    let files;
+    try {
+      files = fs.readdirSync(dir);
+    } catch (err) {
+      if (err.code === "EACCES" || err.code === "EPERM") {
+        warnings.push(`Codex: permission denied reading ${dir}: ${err.message}`);
+      }
+      // ENOENT: dir doesn't exist — skip silently
+      continue;
+    }
+
+    for (const file of files) {
+      if (!file.endsWith(".jsonl")) continue;
+      const filePath = path.join(dir, file);
+      try {
+        const content = fs.readFileSync(filePath, "utf8");
+        const firstLine = content.split("\n")[0].trim();
+        if (!firstLine) continue;
+        const parsed = JSON.parse(firstLine);
+        const cwd = parsed?.cwd;
+        if (typeof cwd === "string" && cwd) {
+          cwdByPath.set(path.resolve(cwd.replace(/^~/, home)), true);
+        }
+      } catch (err) {
+        warnings.push(`Codex: failed to parse first line of ${file}: ${err.message}`);
+      }
+    }
+  }
+
+  // 去重：排除与 defaultPath 相同的路径（default 优先，排首位）
+  const uniquePaths = Array.from(cwdByPath.keys()).filter((p) => p !== defaultPath);
+
+  // 将 default 计入 limit 总数（default 排首位，先占 1 个槽位）
+  const totalCount = 1 + uniquePaths.length;
+  const truncated = totalCount > effectiveLimit;
+  const remainingLimit = Math.max(0, effectiveLimit - 1);
+  const selected = uniquePaths.slice(0, remainingLimit);
+
+  const branches = await resolveBranches(selected, includeBranch);
+
+  const workspaces = [
+    defaultEntry,
+    ...selected.map((absPath, i) => ({
+      id: pathToId(meta.idPrefix, absPath),
+      name: path.basename(absPath),
+      path: absPath,
+      absolutePath: absPath,
+      branch: branches[i],
+      lastUsedAtMs: null,
+    })),
+  ];
+
+  return { workspaces, warnings, truncated };
+}
+
+// ─── Hermes reader ─────────────────────────────────────────────────────────────
+
+/**
+ * hermes profile id 正则（对齐 hermes 官方 _PROFILE_ID_RE）。
+ * 目录名必须符合此正则才会被扫描。
+ */
+const HERMES_PROFILE_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+/**
+ * 极简 YAML 解析器 — 仅支持 hermes config.yaml 中用到的两层键值结构。
+ *
+ * 支持的格式：
+ *   model: string-value       (model 是字符串)
+ *   model:                    (model 是 dict)
+ *     default: string         (可选键 default 或 model)
+ *     model: string           (可选键)
+ *     provider: string
+ *
+ * @param {string} content
+ * @returns {{ model?: any, [key: string]: any }}
+ */
+function parseSimpleYaml(content) {
+  const result = {};
+  let currentKey = null;
+  let currentObj = null;
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    // Skip blank lines and comment lines
+    if (!rawLine.trim() || rawLine.trim().startsWith("#")) continue;
+
+    const indented = rawLine.startsWith(" ") || rawLine.startsWith("\t");
+    if (!indented) {
+      // Top-level key
+      const colonIdx = rawLine.indexOf(":");
+      if (colonIdx < 0) continue;
+      currentKey = rawLine.slice(0, colonIdx).trim();
+      const rest = rawLine.slice(colonIdx + 1).trim();
+      if (rest) {
+        // Inline value — strip optional quotes
+        result[currentKey] = stripYamlQuotes(rest);
+        currentObj = null;
+      } else {
+        // Dict value follows
+        currentObj = {};
+        result[currentKey] = currentObj;
+      }
+    } else if (currentObj !== null) {
+      // Nested key under currentKey
+      const trimmed = rawLine.trim();
+      const colonIdx = trimmed.indexOf(":");
+      if (colonIdx < 0) continue;
+      const k = trimmed.slice(0, colonIdx).trim();
+      const v = trimmed.slice(colonIdx + 1).trim();
+      currentObj[k] = v ? stripYamlQuotes(v) : "";
+    }
+  }
+  return result;
+}
+
+function stripYamlQuotes(s) {
+  if (s.length >= 2 && ((s[0] === '"' && s[s.length - 1] === '"') ||
+                         (s[0] === "'" && s[s.length - 1] === "'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+/**
+ * 从 config.yaml 解析的 model dict/string 提取 { model, provider }。
+ * 对齐 design.md §config.yaml 读法。
+ *
+ * @param {any} raw  parseSimpleYaml(content)["model"]
+ * @returns {{ model: string|null, provider: string|null }}
+ */
+function extractModelProvider(raw) {
+  if (!raw) return { model: null, provider: null };
+  if (typeof raw === "string") {
+    return { model: raw || null, provider: null };
+  }
+  if (typeof raw === "object") {
+    const model = raw["default"] || raw["model"] || null;
+    const provider = raw["provider"] || null;
+    return {
+      model: model || null,
+      provider: provider || null,
+    };
+  }
+  return { model: null, provider: null };
+}
+
+/**
+ * 从 SOUL.md 内容提取第一个非注释非空文本行作为 identityName。
+ * 失败或内容全空 → null（不报 warning）。
+ *
+ * @param {string} content
+ * @returns {string|null}
+ */
+function extractIdentityName(content) {
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    // Skip markdown comment lines (<!-- ... -->) but NOT heading lines (# ...)
+    // per spec: 「第一个非注释非空文本行」
+    if (trimmed.startsWith("<!--")) continue;
+    return trimmed;
+  }
+  return null;
+}
+
+/**
+ * 扫描 ~/.hermes/profiles/* 已有 profile，返回可供 App 展示的 workspace 列表。
+ *
+ * @param {object} opts
+ * @param {string} opts.gatewayId
+ * @param {number} opts.limit
+ * @param {boolean} opts.includeBranch
+ * @param {string} [opts.hermesProfilesRoot]  测试注入：override ~/.hermes/profiles
+ */
+export async function readHermesWorkspaces({
+  gatewayId,
+  limit,
+  includeBranch,
+  hermesProfilesRoot,
+} = {}) {
+  const warnings = [];
+  const effectiveLimit = clampLimit(limit);
+  const profilesRoot = hermesProfilesRoot ?? path.join(os.homedir(), ".hermes", "profiles");
+
+  // align-runtime-default-workspace: default profile root = dirname(profilesRoot) = ~/.hermes
+  // hermesProfilesRoot 注入时，default root 取 path.dirname(hermesProfilesRoot)
+  const hermesRoot = path.dirname(profilesRoot);
+  const meta = RUNTIME_META["Hermes"];
+
+  // 1. List profiles directory
+  let entries;
+  try {
+    entries = fs.readdirSync(profilesRoot, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      // profiles 目录不存在 — 检查 hermesRoot 目录是否存在来决定是否加 default
+      let hermesRootExists = false;
+      try {
+        const stat = fs.statSync(hermesRoot);
+        hermesRootExists = stat.isDirectory();
+      } catch {
+        hermesRootExists = false;
+      }
+      if (!hermesRootExists) {
+        // hermesRoot 也不存在 → 完全返回空
+        return { workspaces: [], warnings: [], truncated: false };
+      }
+      // hermesRoot 存在但 profiles/ 不存在 — 仍 emit default profile
+    } else if (err.code === "EACCES" || err.code === "EPERM") {
+      warnings.push(`Hermes: permission denied reading profiles directory ${profilesRoot}: ${err.message}`);
+      return { workspaces: [], warnings, truncated: false };
+    } else {
+      throw err;
+    }
+    entries = []; // ENOENT 时 entries 为空，继续处理 default profile
+  }
+
+  // 2. Filter: only directories matching HERMES_PROFILE_ID_RE
+  const validProfileNames = (entries || [])
+    .filter((e) => {
+      if (!e.isDirectory()) return false;
+      return HERMES_PROFILE_ID_RE.test(e.name);
+    })
+    .map((e) => e.name)
+    .sort(); // Sort alphabetically
+
+  // 3. 构建 default profile entry（读 hermesRoot/config.yaml + SOUL.md，缺失降级不报 warning）
+  let defaultModel = null;
+  let defaultProvider = null;
+  let defaultIdentityName = null;
+  try {
+    const rootConfigPath = path.join(hermesRoot, "config.yaml");
+    const configContent = fs.readFileSync(rootConfigPath, "utf8");
+    const parsed = parseSimpleYaml(configContent);
+    const extracted = extractModelProvider(parsed["model"]);
+    defaultModel = extracted.model;
+    defaultProvider = extracted.provider;
+  } catch {
+    // ENOENT 或其他错误 → 降级为 null，不报 warning
+  }
+  try {
+    const rootSoulPath = path.join(hermesRoot, "SOUL.md");
+    const soulContent = fs.readFileSync(rootSoulPath, "utf8");
+    defaultIdentityName = extractIdentityName(soulContent);
+  } catch {
+    // 不存在或读失败 → null，不报 warning
+  }
+
+  const defaultEntry = {
+    id: pathToId(meta.idPrefix, hermesRoot),
+    name: "default",
+    path: hermesRoot,
+    absolutePath: hermesRoot,
+    model: defaultModel,
+    provider: defaultProvider,
+    identityName: defaultIdentityName,
+    branch: null,
+    lastUsedAtMs: null,
+  };
+
+  // 4. Apply limit（default 排首位，计入 limit）
+  const totalCount = 1 + validProfileNames.length;
+  const truncated = totalCount > effectiveLimit;
+  const remainingLimit = Math.max(0, effectiveLimit - 1);
+  const selected = validProfileNames.slice(0, remainingLimit);
+
+  // 5. Build profile workspace entries
+  const workspaces = [defaultEntry];
+
+  for (const profileName of selected) {
+    const absolutePath = path.join(profilesRoot, profileName);
+
+    // Read config.yaml
+    let model = null;
+    let provider = null;
+    try {
+      const configPath = path.join(absolutePath, "config.yaml");
+      const content = fs.readFileSync(configPath, "utf8");
+      const parsed = parseSimpleYaml(content);
+      const extracted = extractModelProvider(parsed["model"]);
+      model = extracted.model;
+      provider = extracted.provider;
+    } catch (err) {
+      if (err.code === "EACCES" || err.code === "EPERM") {
+        warnings.push(`Hermes: permission denied reading ${profileName}/config.yaml: ${err.message}`);
+      } else if (err.code !== "ENOENT") {
+        warnings.push(`Hermes: failed to parse ${profileName}/config.yaml: ${err.message}`);
+      }
+      // model/provider remain null — profile still appears in list
+    }
+
+    // Read SOUL.md for identityName (failure → null, no warning)
+    let identityName = null;
+    try {
+      const soulPath = path.join(absolutePath, "SOUL.md");
+      const content = fs.readFileSync(soulPath, "utf8");
+      identityName = extractIdentityName(content);
+    } catch {
+      // ENOENT or any error → identityName stays null, no warning per spec
+    }
+
+    workspaces.push({
+      id: pathToId(meta.idPrefix, absolutePath),
+      name: profileName,
+      path: absolutePath,
+      absolutePath,
+      model,
+      provider,
+      identityName,
+      branch: null,        // hermes profile 无 git branch 概念
+      lastUsedAtMs: null,  // 暂不实现
+    });
+  }
+
+  return { workspaces, warnings, truncated };
+}
+
+// ─── main export ─────────────────────────────────────────────────────────────
+
+/**
+ * Dispatch to the correct runtime reader and return a full response shape.
+ *
+ * @param {object} opts
+ * @param {string} opts.runtimeKind  e.g. "openclaw" | "hermes" | "claude" | "codex"
+ * @param {string} opts.gatewayId
+ * @param {object} [opts.params]     { limit?, includeBranch? }
+ * @returns {Promise<object>}        Full response shape
+ */
+export async function scanWorkspacesByRuntime({ runtimeKind, gatewayId, params }) {
+  const kind = normalizeRuntimeKind(runtimeKind);
+  const meta = RUNTIME_META[kind] ?? RUNTIME_META["OpenClaw"];
+  const limit = clampLimit(params?.limit ?? DEFAULT_LIMIT);
+  const includeBranch = params?.includeBranch === true;
+
+  const readerArgs = { gatewayId, limit, includeBranch };
+  // Pass through hermes-specific test-injection param
+  if (params?.hermesProfilesRoot != null) {
+    readerArgs.hermesProfilesRoot = params.hermesProfilesRoot;
+  }
+
+  // Wrap reader in 5s hard timeout
+  const readerPromise = runReader(kind, readerArgs);
+  const timeoutPromise = new Promise((resolve) =>
+    setTimeout(
+      () => resolve({ workspaces: [], warnings: ["scan timed out after 5s"], truncated: false }),
+      HARD_TIMEOUT_MS,
+    ),
+  );
+
+  let readerResult;
+  try {
+    readerResult = await Promise.race([readerPromise, timeoutPromise]);
+  } catch (err) {
+    // Catch top-level reader errors and degrade gracefully
+    readerResult = {
+      workspaces: [],
+      warnings: [`reader error: ${err.message}`],
+      truncated: false,
+    };
+  }
+
+  const { workspaces, warnings, truncated } = readerResult;
+
+  return {
+    ok: true,
+    agentKind: meta.agentKind,
+    emoji: meta.emoji,
+    tagline: meta.tagline,
+    host: hostMeta(gatewayId),
+    workspaces: workspaces ?? [],
+    truncated: truncated ?? false,
+    scannedAt: new Date().toISOString(),
+    warnings: warnings ?? [],
+  };
+}
+
+// ─── private helpers ──────────────────────────────────────────────────────────
+
+function clampLimit(raw) {
+  const n = typeof raw === "number" ? raw : DEFAULT_LIMIT;
+  return Math.min(Math.max(1, Math.floor(n)), MAX_LIMIT);
+}
+
+function normalizeRuntimeKind(kind) {
+  if (!kind) return "OpenClaw";
+  const lower = String(kind).toLowerCase().trim();
+  return RUNTIME_KIND_MAP[lower] ?? "OpenClaw";
+}
+
+async function runReader(kind, args) {
+  try {
+    switch (kind) {
+      case "OpenClaw":    return await readOpenClawWorkspaces(args);
+      case "Claude Code": return await readClaudeWorkspaces(args);
+      case "Codex":       return await readCodexWorkspaces(args);
+      case "Hermes":      return await readHermesWorkspaces(args);
+      default:            return await readOpenClawWorkspaces(args);
+    }
+  } catch (err) {
+    // Permission errors degrade to warnings
+    if (err.code === "EACCES" || err.code === "EPERM") {
+      return { workspaces: [], warnings: [`permission denied: ${err.message}`], truncated: false };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Resolve OpenClaw home dir. Mirrors bin/agentlink resolveOpenClawHome():
+ * OPENCLAW_HOME 环境变量优先，否则 <home>/.openclaw。
+ */
+function resolveOpenClawHomeDir() {
+  const fromEnv = process.env.OPENCLAW_HOME?.trim();
+  if (fromEnv) return fromEnv;
+  const home =
+    (process.env.HOME ?? process.env.USERPROFILE ?? "").trim() || os.homedir();
+  return path.join(home, ".openclaw");
+}
+
+/**
+ * 解析每个 OpenClaw agent 的 workspace 目录（1 agent = 1 workspace），对齐
+ * bin/agentlink resolveConfiguredWorkspaceRoot()：
+ *   - 配置文件是 <OPENCLAW_HOME>/**openclaw.json**（不是 config.json！旧代码读错了
+ *     文件名 → 永远读不到，fallback 到不存在的 ~/workspace → 扫描恒空）。
+ *   - agents.list[] 每个 agent 的 workspace（缺省继承 agents.defaults.workspace）；
+ *     list 为空 → 仅默认 workspace 一个。
+ *   - 默认值：agents.defaults.workspace → 否则 <OPENCLAW_HOME>/workspace
+ *     （即 ~/.openclaw/workspace，旧代码错写成 ~/workspace）。
+ * 相对路径相对配置文件目录解析。
+ *
+ * @returns {string[]} 绝对 workspace 目录列表（可能含不存在的，调用方负责过滤）
+ */
+function resolveOpenClawAgentWorkspaceDirs() {
+  const homeDir = resolveOpenClawHomeDir();
+  const configPath = path.join(homeDir, "openclaw.json");
+  let config = null;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch {
+    // 配置缺失 / 解析失败：退到默认 workspace（下方 defaultWs）。
+  }
+
+  const resolveWs = (raw) => {
+    const v = String(raw ?? "").trim();
+    if (!v) return null;
+    return path.isAbsolute(v) ? v : path.resolve(path.dirname(configPath), v);
+  };
+
+  const defaultWs =
+    resolveWs(config?.agents?.defaults?.workspace) ??
+    path.join(homeDir, "workspace");
+
+  const list = Array.isArray(config?.agents?.list) ? config.agents.list : [];
+  if (list.length === 0) return [defaultWs];
+  return list.map((a) => resolveWs(a?.workspace) ?? defaultWs);
+}