mulmoclaude 0.1.0

package/server/workspace/journal/paths.ts

@@ -0,0 +1,76 @@
+// Pure path / slug helpers for the workspace journal. Nothing here
+// touches the filesystem — every function is a straightforward
+// string transformation so it can be exhaustively unit-tested.
+
+import path from "node:path";
+import { WORKSPACE_DIRS } from "../paths.js";
+import { isValidIsoDate } from "../../utils/date.js";
+
+// Directory layout under workspace/conversations/summaries/ is an
+// implementation detail of the journal module; keep it centralised
+// here so tests and callers all agree on the structure.
+export const SUMMARIES_DIR = WORKSPACE_DIRS.summaries;
+export const STATE_FILE = "_state.json";
+export const INDEX_FILE = "_index.md";
+export const DAILY_DIR = "daily";
+export const TOPICS_DIR = "topics";
+export const ARCHIVE_DIR = "archive";
+
+// Absolute path to the summaries root inside a workspace.
+export function summariesRoot(workspaceRoot: string): string {
+  return path.join(workspaceRoot, SUMMARIES_DIR);
+}
+
+// summaries/daily/YYYY/MM/DD.md for a given ISO-ish date ("YYYY-MM-DD").
+// Throws if `isoDate` is not exactly YYYY-MM-DD — catches typos at
+// the boundary instead of producing "undefined/undefined.md" paths
+// downstream.
+export function dailyPathFor(workspaceRoot: string, isoDate: string): string {
+  if (!isValidIsoDate(isoDate)) {
+    throw new Error(`[journal] dailyPathFor: expected YYYY-MM-DD, got "${isoDate}"`);
+  }
+  const [year, month, day] = isoDate.split("-");
+  return path.join(summariesRoot(workspaceRoot), DAILY_DIR, year, month, `${day}.md`);
+}
+
+// summaries/topics/<slug>.md
+export function topicPathFor(workspaceRoot: string, slug: string): string {
+  return path.join(summariesRoot(workspaceRoot), TOPICS_DIR, `${slug}.md`);
+}
+
+// summaries/archive/topics/<slug>.md — where the optimizer moves
+// merged or stale topic files.
+export function archivedTopicPathFor(workspaceRoot: string, slug: string): string {
+  return path.join(summariesRoot(workspaceRoot), ARCHIVE_DIR, TOPICS_DIR, `${slug}.md`);
+}
+
+// Re-export for backwards compatibility — callers that import
+// toIsoDate from journal/paths keep working.
+export { toLocalIsoDate as toIsoDate } from "../../utils/date.js";
+
+// Convert a free-form topic name into a filesystem-safe slug.
+// Rules:
+//   - Lowercase ASCII letters, digits, and hyphens only
+//   - Whitespace and punctuation collapse to a single hyphen
+//   - Non-ASCII characters (Japanese, emoji) are dropped; if the
+//     result is empty we fall back to "topic" so we always yield a
+//     valid filename (LLMs occasionally emit pure-Japanese topic
+//     names; the markdown body still holds the original title for
+//     display, this slug is only the filesystem key)
+//   - Leading/trailing hyphens stripped
+//   - Empty-string input yields "topic"
+export function slugify(raw: string): string {
+  const lowered = raw.toLowerCase();
+  // Replace runs of non-ASCII-alnum with a single hyphen. Because
+  // we use `+` on a character class, this single pass already
+  // collapses runs — no second dedupe pass needed.
+  const hyphenated = lowered.replace(/[^a-z0-9]+/g, "-");
+  // Trim leading/trailing hyphens without a regex — sonarjs/slow-regex
+  // flags `^-+` / `-+$` patterns even though these inputs are tiny.
+  let start = 0;
+  let end = hyphenated.length;
+  while (start < end && hyphenated[start] === "-") start++;
+  while (end > start && hyphenated[end - 1] === "-") end--;
+  const trimmed = hyphenated.slice(start, end);
+  return trimmed.length > 0 ? trimmed : "topic";
+}

package/server/workspace/journal/state.ts

@@ -0,0 +1,125 @@
+// Journal state file schema + persistence. The state file tracks
+// what the archivist has already done so we only re-process new or
+// changed sessions on each run.
+//
+// The pure bits (default creation, schema validation, interval
+// arithmetic) live at the top of the file so tests can exercise
+// them without touching disk. Filesystem helpers at the bottom wrap
+// those pure functions with atomic read/write.
+
+import {
+  readJournalState as readJournalStateRaw,
+  writeJournalState as writeJournalStateRaw,
+  journalStateExists as journalStateExistsRaw,
+} from "../../utils/files/journal-io.js";
+import { ONE_HOUR_MS, ONE_DAY_MS } from "../../utils/time.js";
+import { isRecord } from "../../utils/types.js";
+
+// Bump this when the schema changes in a backwards-incompatible way.
+// Older state files are treated as corrupted and replaced with a
+// fresh default (ingest everything from scratch) — cheap because it
+// only costs one extra archivist pass.
+export const JOURNAL_STATE_VERSION = 1;
+
+export interface ProcessedSessionRecord {
+  // mtime (ms since epoch) of the session's .jsonl file when we
+  // last ingested it. If mtime advances on the next run, the session
+  // has appended events and needs re-ingest.
+  lastMtimeMs: number;
+}
+
+export interface JournalState {
+  version: number;
+  lastDailyRunAt: string | null;
+  lastOptimizationRunAt: string | null;
+  dailyIntervalHours: number;
+  optimizationIntervalDays: number;
+  processedSessions: Record<string, ProcessedSessionRecord>;
+  knownTopics: string[];
+}
+
+export const DEFAULT_DAILY_INTERVAL_HOURS = 1;
+export const DEFAULT_OPTIMIZATION_INTERVAL_DAYS = 7;
+
+// --- Pure helpers (unit-testable without disk) ---------------------
+
+export function defaultState(): JournalState {
+  return {
+    version: JOURNAL_STATE_VERSION,
+    lastDailyRunAt: null,
+    lastOptimizationRunAt: null,
+    dailyIntervalHours: DEFAULT_DAILY_INTERVAL_HOURS,
+    optimizationIntervalDays: DEFAULT_OPTIMIZATION_INTERVAL_DAYS,
+    processedSessions: {},
+    knownTopics: [],
+  };
+}
+
+// Narrow an `unknown` into a JournalState. Accepts partial / missing
+// fields and fills defaults — users can hand-edit the file to change
+// intervals and we want to be forgiving.
+export function parseState(raw: unknown): JournalState {
+  if (!isRecord(raw)) return defaultState();
+  const obj = raw as Record<string, unknown>;
+
+  // Version mismatch → throw it all out. Cheap to rebuild.
+  if (obj.version !== JOURNAL_STATE_VERSION) return defaultState();
+
+  const d = defaultState();
+  return {
+    version: JOURNAL_STATE_VERSION,
+    lastDailyRunAt: typeof obj.lastDailyRunAt === "string" ? obj.lastDailyRunAt : null,
+    lastOptimizationRunAt: typeof obj.lastOptimizationRunAt === "string" ? obj.lastOptimizationRunAt : null,
+    dailyIntervalHours: typeof obj.dailyIntervalHours === "number" && obj.dailyIntervalHours > 0 ? obj.dailyIntervalHours : d.dailyIntervalHours,
+    optimizationIntervalDays:
+      typeof obj.optimizationIntervalDays === "number" && obj.optimizationIntervalDays > 0 ? obj.optimizationIntervalDays : d.optimizationIntervalDays,
+    processedSessions: parseProcessedSessions(obj.processedSessions),
+    knownTopics: Array.isArray(obj.knownTopics) ? obj.knownTopics.filter((t): t is string => typeof t === "string") : [],
+  };
+}
+
+function parseProcessedSessions(raw: unknown): Record<string, ProcessedSessionRecord> {
+  if (!isRecord(raw)) return {};
+  const out: Record<string, ProcessedSessionRecord> = {};
+  for (const [id, rec] of Object.entries(raw as Record<string, unknown>)) {
+    if (!isRecord(rec)) continue;
+    const mtime = (rec as Record<string, unknown>).lastMtimeMs;
+    if (typeof mtime === "number" && mtime >= 0) {
+      out[id] = { lastMtimeMs: mtime };
+    }
+  }
+  return out;
+}
+
+// Has the configured daily interval elapsed since the last run? A
+// null lastDailyRunAt means "never run" → always due.
+export function isDailyDue(state: JournalState, nowMs: number): boolean {
+  if (state.lastDailyRunAt === null) return true;
+  const last = Date.parse(state.lastDailyRunAt);
+  if (Number.isNaN(last)) return true;
+  const intervalMs = state.dailyIntervalHours * ONE_HOUR_MS;
+  return nowMs - last >= intervalMs;
+}
+
+export function isOptimizationDue(state: JournalState, nowMs: number): boolean {
+  if (state.lastOptimizationRunAt === null) return true;
+  const last = Date.parse(state.lastOptimizationRunAt);
+  if (Number.isNaN(last)) return true;
+  const intervalMs = state.optimizationIntervalDays * ONE_DAY_MS;
+  return nowMs - last >= intervalMs;
+}
+
+// --- Filesystem helpers (delegated to journal-io) --------------------
+
+export async function readState(workspaceRoot: string): Promise<JournalState> {
+  const raw = await readJournalStateRaw<unknown>(null, workspaceRoot);
+  return parseState(raw);
+}
+
+export async function writeState(workspaceRoot: string, state: JournalState): Promise<void> {
+  await writeJournalStateRaw(state, workspaceRoot);
+}
+
+export function stateFileExists(workspaceRoot: string): boolean {
+  return journalStateExistsRaw(workspaceRoot);
+}

package/server/workspace/paths.ts

@@ -0,0 +1,158 @@
+// Single source of truth for workspace directory / file names and
+// their absolute paths. The record below uses workspace-relative
+// paths (possibly multi-segment, e.g. `config/roles`) as values; code
+// looks up via `WORKSPACE_PATHS.<key>` to get the absolute form.
+//
+// Layout grouping (issue #284):
+//
+//   config/          settings + roles + helps
+//   conversations/   chat + memory.md + summaries
+//   data/            user-managed (wiki, todos, calendar, contacts,
+//                    scheduler, sources, transports)
+//   artifacts/       LLM-generated (charts, html, images, documents,
+//                    spreadsheets, stories, news)
+//
+// Existing workspaces need the one-shot `scripts/migrate-workspace-284.ts`
+// script run before first startup with this code. `server/workspace.ts`
+// detects the pre-migration layout at boot and aborts with a pointer
+// to the script.
+//
+// When adding a new top-level directory: add the name to the
+// `WORKSPACE_DIRS` record below. The absolute path is derived
+// automatically via `WORKSPACE_PATHS`.
+
+import os from "os";
+import path from "path";
+
+// Workspace root. Hard-coded to `~/mulmoclaude` — there is no
+// WORKSPACE_PATH env override today; changing the location
+// requires a code edit or a symlink. Re-exported by
+// `server/workspace.ts` for backwards compatibility of existing
+// callers that `import { workspacePath } from "./workspace.js"`.
+export const workspacePath = path.join(os.homedir(), "mulmoclaude");
+
+// Workspace-relative paths. Keys are the stable code-side identifiers
+// (e.g. `markdowns` — unchanged for call-site compatibility); values
+// are the on-disk paths, grouped per issue #284.
+export const WORKSPACE_DIRS = {
+  // conversations/
+  chat: "conversations/chat",
+  summaries: "conversations/summaries",
+  // Tool-trace output for WebSearch (one .md per search, referenced
+  // from chat JSONL `contentRef`). Lives alongside chat/ so search
+  // trace and chat session share the same grouping.
+  searches: "conversations/searches",
+  // data/
+  wiki: "data/wiki",
+  todos: "data/todos",
+  calendar: "data/calendar",
+  contacts: "data/contacts",
+  scheduler: "data/scheduler",
+  sources: "data/sources",
+  transports: "data/transports",
+  // artifacts/
+  charts: "artifacts/charts",
+  // `markdowns` key preserved for call-site compatibility; on-disk
+  // name is `documents` for clarity.
+  markdowns: "artifacts/documents",
+  // `htmls` = `presentHtml` plugin output (many files, persistent).
+  // On-disk normalized to lowercase `html`.
+  htmls: "artifacts/html",
+  // Distinct from `htmls`: scratch buffer for the `/api/html`
+  // generate-and-preview route. One file (`current.html`), always
+  // overwritten. Kept separate so reloading a saved HTML artifact
+  // doesn't clobber the current preview.
+  html: "artifacts/html-scratch",
+  images: "artifacts/images",
+  spreadsheets: "artifacts/spreadsheets",
+  stories: "artifacts/stories",
+  news: "artifacts/news",
+  // config/
+  configs: "config",
+  roles: "config/roles",
+  helps: "config/helps",
+  // Nested subdirs inside a top-level grouping. Kept here (rather
+  // than module-local constants) when multiple modules need to
+  // reference the same nested path — e.g. wiki/pages/ is used by
+  // the wiki route, the wiki-backlinks driver, and the system
+  // prompt hint.
+  wikiPages: "data/wiki/pages",
+  wikiSources: "data/wiki/sources",
+  // Development — git-cloned repositories (#256).
+  github: "github",
+} as const;
+
+// Well-known individual files — imported from the shared
+// src/config/workspacePaths.ts (single source of truth for both
+// server and frontend). Re-exported so server callers keep the
+// same `import { WORKSPACE_FILES } from "./paths.js"` they use.
+import { WORKSPACE_FILES } from "../../src/config/workspacePaths.js";
+export { WORKSPACE_FILES };
+
+// Absolute paths, built once at module load from `workspacePath`.
+// The `workspacePath` const is itself fixed (reads `os.homedir()`
+// at process start — no env override, see `server/workspace.ts`),
+// so freezing these paths is safe.
+export const WORKSPACE_PATHS = {
+  chat: path.join(workspacePath, WORKSPACE_DIRS.chat),
+  todos: path.join(workspacePath, WORKSPACE_DIRS.todos),
+  calendar: path.join(workspacePath, WORKSPACE_DIRS.calendar),
+  contacts: path.join(workspacePath, WORKSPACE_DIRS.contacts),
+  scheduler: path.join(workspacePath, WORKSPACE_DIRS.scheduler),
+  roles: path.join(workspacePath, WORKSPACE_DIRS.roles),
+  stories: path.join(workspacePath, WORKSPACE_DIRS.stories),
+  images: path.join(workspacePath, WORKSPACE_DIRS.images),
+  markdowns: path.join(workspacePath, WORKSPACE_DIRS.markdowns),
+  spreadsheets: path.join(workspacePath, WORKSPACE_DIRS.spreadsheets),
+  charts: path.join(workspacePath, WORKSPACE_DIRS.charts),
+  configs: path.join(workspacePath, WORKSPACE_DIRS.configs),
+  helps: path.join(workspacePath, WORKSPACE_DIRS.helps),
+  wiki: path.join(workspacePath, WORKSPACE_DIRS.wiki),
+  news: path.join(workspacePath, WORKSPACE_DIRS.news),
+  sources: path.join(workspacePath, WORKSPACE_DIRS.sources),
+  summaries: path.join(workspacePath, WORKSPACE_DIRS.summaries),
+  searches: path.join(workspacePath, WORKSPACE_DIRS.searches),
+  htmls: path.join(workspacePath, WORKSPACE_DIRS.htmls),
+  html: path.join(workspacePath, WORKSPACE_DIRS.html),
+  transports: path.join(workspacePath, WORKSPACE_DIRS.transports),
+  github: path.join(workspacePath, WORKSPACE_DIRS.github),
+  // nested subdirs
+  wikiPages: path.join(workspacePath, WORKSPACE_DIRS.wikiPages),
+  wikiSources: path.join(workspacePath, WORKSPACE_DIRS.wikiSources),
+  // files
+  memory: path.join(workspacePath, WORKSPACE_FILES.memory),
+  sessionToken: path.join(workspacePath, WORKSPACE_FILES.sessionToken),
+  wikiIndex: path.join(workspacePath, WORKSPACE_FILES.wikiIndex),
+  wikiLog: path.join(workspacePath, WORKSPACE_FILES.wikiLog),
+  wikiSchema: path.join(workspacePath, WORKSPACE_FILES.wikiSchema),
+  wikiSummary: path.join(workspacePath, WORKSPACE_FILES.wikiSummary),
+  summariesIndex: path.join(workspacePath, WORKSPACE_FILES.summariesIndex),
+  todosItems: path.join(workspacePath, WORKSPACE_FILES.todosItems),
+  todosColumns: path.join(workspacePath, WORKSPACE_FILES.todosColumns),
+  schedulerItems: path.join(workspacePath, WORKSPACE_FILES.schedulerItems),
+  schedulerUserTasks: path.join(workspacePath, WORKSPACE_FILES.schedulerUserTasks),
+  schedulerOverrides: path.join(workspacePath, WORKSPACE_FILES.schedulerOverrides),
+} as const;
+
+export type WorkspaceDirKey = keyof typeof WORKSPACE_DIRS;
+export type WorkspacePathKey = keyof typeof WORKSPACE_PATHS;
+
+// Directories `initWorkspace()` creates eagerly on server start.
+// Kept as a subset of `WORKSPACE_DIRS` so new entries are additive
+// without touching `server/workspace.ts`. Everything *not* on this
+// list is created lazily (first write) by its owning module.
+export const EAGER_WORKSPACE_DIRS: readonly WorkspaceDirKey[] = [
+  "chat",
+  "todos",
+  "calendar",
+  "contacts",
+  "scheduler",
+  "roles",
+  "stories",
+  "images",
+  "markdowns",
+  "spreadsheets",
+  "charts",
+  "configs",
+  "github",
+];

package/server/workspace/reference-dirs.ts

@@ -0,0 +1,252 @@
+// User-defined reference directories (#455).
+//
+// Loaded from `config/reference-dirs.json`. Users can specify external
+// directories that the agent can read (but not write to).
+//
+// Docker mode: mounted as `:ro` — filesystem-enforced read-only.
+// Non-Docker mode: prompt-based restriction only.
+
+import { createHash } from "crypto";
+import path from "path";
+import os from "os";
+import { log } from "../system/logger/index.js";
+import { readReferenceDirsJson, writeReferenceDirsJson, isExistingDirectory } from "../utils/files/reference-dirs-io.js";
+import { isRecord } from "../utils/types.js";
+
+// ── Types ───────────────────────────────────────────────────────
+
+export interface ReferenceDirEntry {
+  /** Absolute host path to the directory. */
+  hostPath: string;
+  /** Short label shown in prompt and UI. */
+  label: string;
+}
+
+// ── Constants ───────────────────────────────────────────────────
+
+const MAX_ENTRIES = 20;
+const MAX_LABEL_LENGTH = 100;
+const CONTAINER_MOUNT_ROOT = "/mnt/readonly";
+
+/** Home-relative directories that must never be mounted. */
+const HOME_RELATIVE_BLOCKED = [".ssh", ".aws", ".gnupg", ".config/gh", ".kube", ".docker"];
+
+/** Absolute system paths that must never be mounted. */
+const SYSTEM_BLOCKED_PREFIXES = ["/etc", "/root", "/var", "/proc", "/sys", "/boot", "/private/etc", "/private/var", "/System", "/Library"];
+
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHAR_RE_G = /[\x00-\x1f]/g;
+
+// ── Validation ──────────────────────────────────────────────────
+
+function expandHome(p: string): string {
+  if (p.startsWith("~/")) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}
+
+function isSensitivePath(absPath: string): boolean {
+  const normalized = path.resolve(absPath);
+
+  // Reject filesystem root
+  if (normalized === path.parse(normalized).root) return true;
+
+  const home = os.homedir();
+
+  // Block $HOME itself (transitively exposes .ssh etc.)
+  if (normalized === home) return true;
+
+  // Block home-relative sensitive dirs
+  if (
+    HOME_RELATIVE_BLOCKED.some((bp) => {
+      const full = path.join(home, bp);
+      return normalized === full || normalized.startsWith(full + path.sep);
+    })
+  ) {
+    return true;
+  }
+
+  // Block system directories
+  return SYSTEM_BLOCKED_PREFIXES.some((p) => normalized === p || normalized.startsWith(p + path.sep));
+}
+
+function sanitizeLabel(raw: string): string {
+  if (typeof raw !== "string") return "";
+  return raw.replace(CONTROL_CHAR_RE_G, " ").trim().slice(0, MAX_LABEL_LENGTH);
+}
+
+function hasTraversalSegment(p: string): boolean {
+  return p.split(path.sep).some((seg) => seg === "..");
+}
+
+function validateEntry(raw: unknown): ReferenceDirEntry | null {
+  if (!isRecord(raw)) return null;
+  const obj = raw as Record<string, unknown>;
+
+  const rawPath = typeof obj.hostPath === "string" ? obj.hostPath : "";
+  if (!rawPath) return null;
+
+  const expanded = expandHome(rawPath);
+
+  // Must be absolute
+  if (!path.isAbsolute(expanded)) return null;
+
+  // Normalize to collapse . and // segments
+  const absPath = path.resolve(expanded);
+
+  // Reject actual ".." traversal segments (not substrings in filenames)
+  if (hasTraversalSegment(expanded)) return null;
+
+  // Block sensitive directories
+  if (isSensitivePath(absPath)) {
+    log.warn("reference-dirs", "blocked sensitive path", { path: absPath });
+    return null;
+  }
+
+  const label = sanitizeLabel(String(obj.label ?? path.basename(absPath)));
+
+  return { hostPath: absPath, label };
+}
+
+// ── Load ────────────────────────────────────────────────────────
+
+export function loadReferenceDirs(root?: string): ReferenceDirEntry[] {
+  const parsed = readReferenceDirsJson(root);
+  const seenLabels = new Set<string>();
+  const entries = parsed
+    .slice(0, MAX_ENTRIES)
+    .map(validateEntry)
+    .filter((e): e is ReferenceDirEntry => {
+      if (!e) return false;
+      // Deduplicate labels — first entry wins
+      if (seenLabels.has(e.label)) return false;
+      seenLabels.add(e.label);
+      return true;
+    });
+
+  const skipped = parsed.length - entries.length;
+  if (skipped > 0) {
+    log.warn("reference-dirs", "skipped invalid entries", { skipped });
+  }
+  return entries;
+}
+
+// ── Save ────────────────────────────────────────────────────────
+
+export function saveReferenceDirs(entries: readonly ReferenceDirEntry[], root?: string): void {
+  writeReferenceDirsJson(entries, root);
+  invalidateCache();
+}
+
+// ── Validate input array (for API) ─────────────────────────────
+
+export function validateReferenceDirs(raw: unknown): { entries: ReferenceDirEntry[] } | { error: string } {
+  if (!Array.isArray(raw)) {
+    return { error: "expected an array" };
+  }
+  if (raw.length > MAX_ENTRIES) {
+    return { error: `too many entries (max ${MAX_ENTRIES})` };
+  }
+  const entries: ReferenceDirEntry[] = [];
+  const errors: string[] = [];
+  raw.forEach((item, i) => {
+    const entry = validateEntry(item);
+    if (entry) {
+      entries.push(entry);
+    } else {
+      const p = isRecord(item) ? String((item as Record<string, unknown>).hostPath ?? "") : "";
+      errors.push(`entry ${i}: invalid or blocked path "${p}"`);
+    }
+  });
+  if (errors.length > 0) {
+    return { error: errors.join("; ") };
+  }
+
+  // Reject duplicate labels — @ref/<label> routing requires uniqueness
+  const seenLabels = new Set<string>();
+  for (const entry of entries) {
+    if (seenLabels.has(entry.label)) {
+      return { error: `duplicate label "${entry.label}"` };
+    }
+    seenLabels.add(entry.label);
+  }
+  return { entries };
+}
+
+// ── Cached loader (for system prompt + Docker mounts) ───────────
+
+let cachedEntries: ReferenceDirEntry[] | null = null;
+
+export function getCachedReferenceDirs(): readonly ReferenceDirEntry[] {
+  if (cachedEntries === null) {
+    cachedEntries = loadReferenceDirs();
+  }
+  return cachedEntries;
+}
+
+function invalidateCache(): void {
+  cachedEntries = null;
+}
+
+// ── Docker mount args ───────────────────────────────────────────
+
+/** Container path for a reference directory.
+ *  Disambiguates with a short hash suffix to prevent collisions
+ *  when different host paths share the same basename. */
+export function containerPath(entry: ReferenceDirEntry): string {
+  const basename = path.basename(entry.hostPath);
+  const hash = createHash("sha256").update(entry.hostPath).digest("hex").slice(0, 8);
+  return path.posix.join(CONTAINER_MOUNT_ROOT, `${basename}-${hash}`);
+}
+
+/**
+ * Return Docker `-v` args for read-only reference directory mounts.
+ * Skips entries whose host path doesn't exist.
+ */
+export function referenceDirMountArgs(entries: readonly ReferenceDirEntry[]): string[] {
+  const args: string[] = [];
+  for (const entry of entries) {
+    if (!isExistingDirectory(entry.hostPath)) {
+      log.info("reference-dirs", "skipped (not found or not a directory)", {
+        path: entry.hostPath,
+      });
+      continue;
+    }
+    const host = entry.hostPath.replace(/\\/g, "/");
+    args.push("-v", `${host}:${containerPath(entry)}:ro`);
+  }
+  return args;
+}
+
+// ── System prompt snippet ───────────────────────────────────────
+
+export function buildReferenceDirsPrompt(entries: readonly ReferenceDirEntry[], useDocker: boolean): string {
+  if (entries.length === 0) return "";
+
+  const lines = [
+    "",
+    "## Reference Directories (Read-Only)",
+    "",
+    "The user has configured external directories for reference.",
+    "You may READ files in these directories but MUST NOT write, modify, or delete anything in them.",
+    "",
+  ];
+
+  for (const e of entries) {
+    const mountPath = useDocker ? containerPath(e) : e.hostPath;
+    lines.push(`- \`${mountPath}\` — ${e.label}`);
+  }
+
+  if (!useDocker) {
+    lines.push("");
+    lines.push(
+      "**Important**: These directories are outside the workspace. " +
+        "Do not create, edit, or delete files in them. " +
+        "Only use read operations (read, glob, grep).",
+    );
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}

package/server/workspace/roles.ts

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { BUILTIN_ROLES, RoleSchema, type Role } from "../../src/config/roles.js";
+import { WORKSPACE_DIRS } from "./paths.js";
+import { readdirUnderSync, readTextUnderSync } from "../utils/files/workspace-io.js";
+import { workspacePath } from "./paths.js";
+
+function withSwitchRole(role: Role): Role {
+  if (role.availablePlugins.includes("switchRole")) return role;
+  return {
+    ...role,
+    availablePlugins: [...role.availablePlugins, "switchRole"],
+  };
+}
+
+export function loadCustomRoles(): Role[] {
+  return readdirUnderSync(workspacePath, WORKSPACE_DIRS.roles)
+    .filter((f) => f.endsWith(".json"))
+    .flatMap((f) => {
+      try {
+        const raw = readTextUnderSync(workspacePath, path.posix.join(WORKSPACE_DIRS.roles, f));
+        if (!raw) return [];
+        return [withSwitchRole(RoleSchema.parse(JSON.parse(raw)))];
+      } catch {
+        return [];
+      }
+    });
+}
+
+export function loadAllRoles(): Role[] {
+  const custom = loadCustomRoles();
+  const builtIn = BUILTIN_ROLES.filter((r) => !custom.find((c) => c.id === r.id));
+  return [...builtIn, ...custom];
+}
+
+export function getRole(id: string): Role {
+  return loadAllRoles().find((r) => r.id === id) ?? BUILTIN_ROLES[0];
+}