mulmoclaude 0.1.0

package/server/workspace/tool-trace/index.ts

@@ -0,0 +1,250 @@
+// Driver for persisting built-in Claude tool events to the session
+// jsonl (#194). Called from routes/agent.ts for each tool_call and
+// tool_call_result event. Fire-and-forget semantics: all failures are
+// caught and log.warn'd with the `tool-trace` prefix.
+
+import { appendFile } from "node:fs/promises";
+import { log } from "../../system/logger/index.js";
+import { WEB_SEARCH_TOOL_NAME, classifyToolResult } from "./classify.js";
+import { writeSearchResult } from "./writeSearch.js";
+import { EVENT_TYPES } from "../../../src/types/events.js";
+import { isNonEmptyString, isRecord } from "../../utils/types.js";
+
+export interface ToolCallEvent {
+  type: typeof EVENT_TYPES.toolCall;
+  toolUseId: string;
+  toolName: string;
+  args: unknown;
+}
+
+export interface ToolCallResultEvent {
+  type: typeof EVENT_TYPES.toolCallResult;
+  toolUseId: string;
+  content: string;
+}
+
+export type ToolTraceEvent = ToolCallEvent | ToolCallResultEvent;
+
+export interface CachedCall {
+  toolName: string;
+  args: unknown;
+}
+
+export type ArgsCache = Map<string, CachedCall>;
+
+export interface RecordToolEventDeps {
+  workspaceRoot: string;
+  chatSessionId: string;
+  resultsFilePath: string;
+  argsCache: ArgsCache;
+  now?: () => Date;
+  // Test hooks.
+  appendLine?: (filePath: string, line: string) => Promise<void>;
+  saveSearch?: typeof writeSearchResult;
+}
+
+export function createArgsCache(): ArgsCache {
+  return new Map<string, CachedCall>();
+}
+
+const defaultAppendLine = (filePath: string, line: string) => appendFile(filePath, line, "utf-8");
+
+export async function recordToolEvent(event: ToolTraceEvent, deps: RecordToolEventDeps): Promise<void> {
+  try {
+    if (event.type === EVENT_TYPES.toolCall) {
+      await handleToolCall(event, deps);
+      return;
+    }
+    await handleToolCallResult(event, deps);
+  } catch (err) {
+    log.warn("tool-trace", "recordToolEvent failed", {
+      type: event.type,
+      toolUseId: event.toolUseId,
+      error: String(err),
+    });
+  }
+}
+
+async function handleToolCall(event: ToolCallEvent, deps: RecordToolEventDeps): Promise<void> {
+  deps.argsCache.set(event.toolUseId, {
+    toolName: event.toolName,
+    args: event.args,
+  });
+  const now = (deps.now ?? (() => new Date()))();
+  const record = {
+    source: "tool",
+    type: EVENT_TYPES.toolCall,
+    toolUseId: event.toolUseId,
+    toolName: event.toolName,
+    args: event.args,
+    ts: now.toISOString(),
+  };
+  await appendRecord(deps, record);
+  logToolCall(event);
+}
+
+// Emit an info-level log when a tool fires. WebSearch and WebFetch
+// get a little extra context (the query / URL) because those are the
+// two tools whose progress users most often want to watch in real
+// time.
+function logToolCall(event: ToolCallEvent): void {
+  if (event.toolName === "WebSearch") {
+    const query = extractQuery(event.args);
+    log.info("tool-trace", "web_search starting", {
+      toolUseId: event.toolUseId,
+      query: query ?? "<missing>",
+    });
+    return;
+  }
+  if (event.toolName === "WebFetch") {
+    const url = extractUrl(event.args);
+    log.info("tool-trace", "web_fetch starting", {
+      toolUseId: event.toolUseId,
+      url: url ?? "<missing>",
+    });
+    return;
+  }
+  log.debug("tool-trace", "tool_call", {
+    toolUseId: event.toolUseId,
+    toolName: event.toolName,
+  });
+}
+
+function extractUrl(args: unknown): string | null {
+  if (!isRecord(args)) return null;
+  const record = args;
+  const raw = record.url;
+  return isNonEmptyString(raw) ? raw : null;
+}
+
+// Emit progress on the result side. For WebSearch we specifically
+// log the saved `contentRef` so operators can follow the breadcrumb
+// from the server log straight to the on-disk search file.
+function logToolCallResult(
+  toolName: string,
+  event: ToolCallResultEvent,
+  classification: { kind: "pointer"; contentRef: string } | { kind: "inline"; content: string; truncated: boolean },
+  searchContentRef: string | undefined,
+): void {
+  if (toolName === "WebSearch" && searchContentRef) {
+    log.info("tool-trace", "web_search saved", {
+      toolUseId: event.toolUseId,
+      contentRef: searchContentRef,
+      bodyLen: event.content.length,
+    });
+    return;
+  }
+  if (toolName === "WebSearch") {
+    // Save failed earlier → we already emitted a warn; record
+    // inline-fallback landing at info so the pair stays matched.
+    log.info("tool-trace", "web_search inlined (save failed)", {
+      toolUseId: event.toolUseId,
+      bodyLen: event.content.length,
+    });
+    return;
+  }
+  if (classification.kind === "pointer") {
+    log.debug("tool-trace", "tool_call_result pointer", {
+      toolUseId: event.toolUseId,
+      toolName,
+      contentRef: classification.contentRef,
+    });
+    return;
+  }
+  log.debug("tool-trace", "tool_call_result inline", {
+    toolUseId: event.toolUseId,
+    toolName,
+    bodyLen: event.content.length,
+    truncated: classification.truncated,
+  });
+}
+
+async function handleToolCallResult(event: ToolCallResultEvent, deps: RecordToolEventDeps): Promise<void> {
+  const now = (deps.now ?? (() => new Date()))();
+  const cached = deps.argsCache.get(event.toolUseId);
+  const toolName = cached?.toolName ?? "";
+  const args = cached?.args ?? {};
+
+  const searchContentRef = await maybeWriteSearch({
+    toolName,
+    args,
+    content: event.content,
+    chatSessionId: deps.chatSessionId,
+    workspaceRoot: deps.workspaceRoot,
+    now,
+    saveSearch: deps.saveSearch,
+  });
+
+  const classification = classifyToolResult({
+    toolName,
+    args,
+    content: event.content,
+    searchContentRef,
+  });
+
+  const base = {
+    source: "tool",
+    type: EVENT_TYPES.toolCallResult,
+    toolUseId: event.toolUseId,
+    toolName,
+    ts: now.toISOString(),
+  };
+  const record =
+    classification.kind === "pointer"
+      ? { ...base, contentRef: classification.contentRef }
+      : {
+          ...base,
+          content: classification.content,
+          truncated: classification.truncated,
+        };
+  await appendRecord(deps, record);
+  logToolCallResult(toolName, event, classification, searchContentRef);
+
+  // Release the cache entry once consumed so long-lived sessions
+  // don't accumulate stale tool_use ids.
+  deps.argsCache.delete(event.toolUseId);
+}
+
+interface MaybeWriteSearchInputs {
+  toolName: string;
+  args: unknown;
+  content: string;
+  chatSessionId: string;
+  workspaceRoot: string;
+  now: Date;
+  saveSearch?: typeof writeSearchResult;
+}
+
+async function maybeWriteSearch(inputs: MaybeWriteSearchInputs): Promise<string | undefined> {
+  if (inputs.toolName !== WEB_SEARCH_TOOL_NAME) return undefined;
+  const query = extractQuery(inputs.args);
+  if (!query) return undefined;
+  const save = inputs.saveSearch ?? writeSearchResult;
+  try {
+    return await save({
+      workspaceRoot: inputs.workspaceRoot,
+      query,
+      sessionId: inputs.chatSessionId,
+      ts: inputs.now,
+      resultBody: inputs.content,
+    });
+  } catch (err) {
+    log.warn("tool-trace", "writeSearchResult failed", {
+      error: String(err),
+    });
+    return undefined;
+  }
+}
+
+function extractQuery(args: unknown): string | null {
+  if (!isRecord(args)) return null;
+  const record = args;
+  const raw = record.query;
+  if (typeof raw !== "string" || raw.length === 0) return null;
+  return raw;
+}
+
+async function appendRecord(deps: RecordToolEventDeps, record: object): Promise<void> {
+  const append = deps.appendLine ?? defaultAppendLine;
+  await append(deps.resultsFilePath, JSON.stringify(record) + "\n");
+}

package/server/workspace/tool-trace/writeSearch.ts

@@ -0,0 +1,98 @@
+// Saves WebSearch results as a durable markdown file under
+// `workspace/conversations/searches/YYYY-MM-DD/<slug>-<hash>.md` and
+// returns the workspace-relative path for use as a jsonl `contentRef`.
+//
+// The pure helpers (slug / hash / path / content template) are
+// exported for unit tests; the side-effecting function at the end is
+// a thin wrapper.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { slugify } from "../../utils/slug.js";
+import { toUtcIsoDate } from "../../utils/date.js";
+import { WORKSPACE_DIRS } from "../paths.js";
+
+export const SEARCHES_DIR = WORKSPACE_DIRS.searches;
+const SEARCH_HASH_LEN = 8;
+const MAX_QUERY_SLUG_CHARS = 40;
+
+// Re-export for backwards compatibility with callers that imported
+// from this module. The function is now in utils/date.ts.
+export { toUtcIsoDate as formatSearchDateDir } from "../../utils/date.js";
+
+export function computeSearchHash(query: string, sessionId: string, ts: Date): string {
+  return createHash("sha256").update(`${query}\n${sessionId}\n${ts.toISOString()}`, "utf-8").digest("base64url").slice(0, SEARCH_HASH_LEN);
+}
+
+export interface SearchPathInputs {
+  query: string;
+  sessionId: string;
+  ts: Date;
+}
+
+// Returns the workspace-relative path (POSIX slashes) where the search
+// file should live, e.g. "conversations/searches/2026-04-13/foo-abc12345.md".
+export function computeSearchRelPath(inputs: SearchPathInputs): string {
+  const slug = slugify(inputs.query, "search", MAX_QUERY_SLUG_CHARS);
+  const hash = computeSearchHash(inputs.query, inputs.sessionId, inputs.ts);
+  const dateDir = toUtcIsoDate(inputs.ts);
+  return path.posix.join(SEARCHES_DIR, dateDir, `${slug}-${hash}.md`);
+}
+
+export interface SearchContentInputs {
+  query: string;
+  sessionId: string;
+  ts: Date;
+  resultBody: string;
+}
+
+// Build the on-disk markdown body: YAML frontmatter with
+// machine-readable metadata, then a human-readable heading, then the
+// raw search result body verbatim.
+export function buildSearchMarkdown(inputs: SearchContentInputs): string {
+  const { query, sessionId, ts, resultBody } = inputs;
+  const body = resultBody.endsWith("\n") ? resultBody : `${resultBody}\n`;
+  return ["---", `query: ${jsonStringSafe(query)}`, `sessionId: ${sessionId}`, `ts: ${ts.toISOString()}`, "---", "", `# Search: ${query}`, "", body].join("\n");
+}
+
+// Quote a string for YAML only when it could otherwise be
+// misinterpreted (contains a colon, hash, or leading/trailing space).
+// Cheap and good enough for a machine-authored frontmatter.
+function jsonStringSafe(s: string): string {
+  const needsQuote = /[:#\n]/.test(s) || s !== s.trim();
+  return needsQuote ? JSON.stringify(s) : s;
+}
+
+export interface WriteSearchInputs extends SearchContentInputs {
+  workspaceRoot: string;
+}
+
+export interface WriteSearchDeps {
+  mkdir: (dir: string) => Promise<void>;
+  writeFile: (p: string, content: string) => Promise<void>;
+}
+
+const defaultDeps: WriteSearchDeps = {
+  mkdir: async (dir) => {
+    await fsp.mkdir(dir, { recursive: true });
+  },
+  writeFile: (p, content) => fsp.writeFile(p, content, "utf-8"),
+};
+
+/**
+ * Save the search result to disk and return the workspace-relative
+ * path that should be used as the jsonl `contentRef`.
+ */
+export async function writeSearchResult(inputs: WriteSearchInputs, deps: Partial<WriteSearchDeps> = {}): Promise<string> {
+  const d: WriteSearchDeps = { ...defaultDeps, ...deps };
+  const relPath = computeSearchRelPath({
+    query: inputs.query,
+    sessionId: inputs.sessionId,
+    ts: inputs.ts,
+  });
+  const absPath = path.join(inputs.workspaceRoot, relPath);
+  await d.mkdir(path.dirname(absPath));
+  await d.writeFile(absPath, buildSearchMarkdown(inputs));
+  return relPath;
+}

package/server/workspace/wiki-backlinks/index.ts

@@ -0,0 +1,107 @@
+// Driver for wiki page session-backlink appendix (#109).
+//
+// The agent route calls `maybeAppendWikiBacklinks({ chatSessionId,
+// turnStartedAt, ... })` from its `finally` block — fire-and-forget.
+// This module:
+//
+//   - scans `wiki/pages/*.md` for files modified during this turn
+//   - appends a session backlink to each qualifying page
+//   - swallows all errors with a log.warn so nothing ever bubbles
+//     back into the request handler
+//
+// Mtime-based detection sounds fragile but works well here because
+// MulmoClaude is single-user / single-process and the turn scope is
+// strictly <= one agent run. If two sessions ever overlap on the
+// same page the later turn will simply add a second bullet — which
+// is the intended behaviour.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { workspacePath as defaultWorkspacePath } from "../workspace.js";
+import { WORKSPACE_DIRS } from "../paths.js";
+import { log } from "../../system/logger/index.js";
+import { updateSessionBacklinks } from "./sessionBacklinks.js";
+import { ONE_SECOND_MS } from "../../utils/time.js";
+
+// Small tolerance for filesystem mtime granularity (some filesystems
+// only record to 1-second precision). Without this, a page written
+// within the same millisecond as turnStartedAt could be skipped.
+const MTIME_TOLERANCE_MS = ONE_SECOND_MS;
+
+export interface WikiBacklinksDeps {
+  readdir: (dir: string) => Promise<string[]>;
+  stat: (p: string) => Promise<{ mtimeMs: number }>;
+  readFile: (p: string) => Promise<string>;
+  writeFile: (p: string, content: string) => Promise<void>;
+}
+
+const defaultDeps: WikiBacklinksDeps = {
+  readdir: (dir) => fsp.readdir(dir),
+  stat: (p) => fsp.stat(p),
+  readFile: (p) => fsp.readFile(p, "utf-8"),
+  writeFile: (p, content) => fsp.writeFile(p, content, "utf-8"),
+};
+
+export interface MaybeAppendWikiBacklinksOptions {
+  chatSessionId: string;
+  turnStartedAt: number;
+  workspaceRoot?: string;
+  deps?: Partial<WikiBacklinksDeps>;
+}
+
+export async function maybeAppendWikiBacklinks(opts: MaybeAppendWikiBacklinksOptions): Promise<void> {
+  if (!opts.chatSessionId) return;
+  const workspaceRoot = opts.workspaceRoot ?? defaultWorkspacePath;
+  const deps: WikiBacklinksDeps = { ...defaultDeps, ...(opts.deps ?? {}) };
+  const pagesDir = path.join(workspaceRoot, WORKSPACE_DIRS.wikiPages);
+
+  const files = await listPageFiles(pagesDir, deps);
+  if (files.length === 0) return;
+
+  const threshold = opts.turnStartedAt - MTIME_TOLERANCE_MS;
+  for (const fileName of files) {
+    await processOneFile(pagesDir, fileName, opts.chatSessionId, threshold, deps);
+  }
+}
+
+async function listPageFiles(pagesDir: string, deps: WikiBacklinksDeps): Promise<string[]> {
+  try {
+    const entries = await deps.readdir(pagesDir);
+    return entries.filter((name) => name.endsWith(".md"));
+  } catch {
+    // `wiki/pages/` may not exist yet — first run, empty workspace.
+    // Not an error.
+    return [];
+  }
+}
+
+async function processOneFile(pagesDir: string, fileName: string, sessionId: string, mtimeThreshold: number, deps: WikiBacklinksDeps): Promise<void> {
+  const fullPath = path.join(pagesDir, fileName);
+  try {
+    const st = await deps.stat(fullPath);
+    if (st.mtimeMs < mtimeThreshold) return;
+
+    const content = await deps.readFile(fullPath);
+    // Compute the relative path from the wiki page's directory to
+    // the chat jsonl. Layout grouped both under `data/wiki/pages/`
+    // and `conversations/chat/` post-#284, so the href is no longer
+    // a fixed `../../chat/…` — derive from the constants.
+    const workspaceRoot = path.resolve(pagesDir, "..", "..", "..");
+    const chatFileAbs = path.join(workspaceRoot, WORKSPACE_DIRS.chat, `${sessionId}.jsonl`);
+    // Markdown link targets are URL-ish and must use forward slashes
+    // even on Windows, where `path.relative` returns backslashes.
+    const linkHref = path.relative(path.dirname(fullPath), chatFileAbs).split(path.sep).join("/");
+    const updated = updateSessionBacklinks(content, sessionId, linkHref);
+    if (updated === content) return;
+
+    await deps.writeFile(fullPath, updated);
+    log.debug("wiki-backlinks", "appended", {
+      file: `wiki/pages/${fileName}`,
+    });
+  } catch (err) {
+    log.warn("wiki-backlinks", "failed to update page", {
+      file: `wiki/pages/${fileName}`,
+      error: String(err),
+    });
+  }
+}

package/server/workspace/wiki-backlinks/sessionBacklinks.ts

@@ -0,0 +1,144 @@
+// Pure helpers for wiki page session-backlink appendix (#109).
+//
+// Each wiki page that was touched during a chat session gets a small
+// machine-managed appendix at the end listing the sessions that
+// modified it. The appendix is demarcated by an HTML comment so
+// renderers don't show the marker and our parser can find the
+// boundary without a regex:
+//
+//   ... user-authored page body ...
+//
+//   <!-- journal-session-backlinks -->
+//   ## History
+//
+//   - [session 3e0382cb](../../chat/3e0382cb-f02f-4f5b-a9a3-a71e50d7ad0c.jsonl)
+//   - [session 4d7f5377](../../chat/4d7f5377-1bac-460c-8ec5-ea054fa0492d.jsonl)
+//
+// Contract: `updateSessionBacklinks(existingContent, sessionId,
+// linkHref)` returns the content that should be written back. If the
+// sessionId is already listed in the appendix, the return value is
+// byte-for-byte equal to `existingContent` so the caller can skip the
+// write.
+
+export const BACKLINKS_MARKER = "<!-- journal-session-backlinks -->";
+const HISTORY_HEADING = "## History";
+const SESSION_ID_SHORT_LEN = 8;
+
+/**
+ * Append a backlink for `sessionId` to the appendix of `existingContent`.
+ *
+ * If the appendix doesn't exist yet it is created at the end of the
+ * content. If it exists and already lists `sessionId` the content is
+ * returned unchanged (idempotent).
+ */
+export function updateSessionBacklinks(existingContent: string, sessionId: string, linkHref: string): string {
+  if (!sessionId) return existingContent;
+
+  const markerIdx = existingContent.indexOf(BACKLINKS_MARKER);
+  if (markerIdx === -1) {
+    return appendFreshAppendix(existingContent, sessionId, linkHref);
+  }
+
+  const bodyBeforeAppendix = existingContent.slice(0, markerIdx);
+  const appendixSection = existingContent.slice(markerIdx);
+  const existingSessionIds = extractSessionIdsFromAppendix(appendixSection);
+  if (existingSessionIds.has(sessionId)) return existingContent;
+
+  const newBullet = buildBullet(sessionId, linkHref);
+  const updatedAppendix = appendBulletToAppendix(appendixSection, newBullet);
+  return bodyBeforeAppendix + updatedAppendix;
+}
+
+function buildBullet(sessionId: string, linkHref: string): string {
+  const short = sessionId.slice(0, SESSION_ID_SHORT_LEN) || sessionId;
+  return `- [session ${short}](${linkHref})`;
+}
+
+function appendFreshAppendix(body: string, sessionId: string, linkHref: string): string {
+  const bullet = buildBullet(sessionId, linkHref);
+  const separator = body.length === 0 || body.endsWith("\n") ? "" : "\n";
+  const leadingBlank = body.length === 0 ? "" : "\n";
+  return `${body}${separator}${leadingBlank}${BACKLINKS_MARKER}\n${HISTORY_HEADING}\n\n${bullet}\n`;
+}
+
+// Walk the appendix section looking for `- [...](...)` bullets and
+// collect the session id from each link href. No regex — the href
+// format is tightly constrained (one bracket pair then one paren
+// pair) so a character scan is sufficient and faster than a
+// backtracking regex.
+function extractSessionIdsFromAppendix(appendix: string): Set<string> {
+  const ids = new Set<string>();
+  for (const rawLine of appendix.split("\n")) {
+    const line = rawLine.trim();
+    if (!line.startsWith("- ") && !line.startsWith("* ")) continue;
+    const href = extractHrefFromBullet(line);
+    if (!href) continue;
+    const id = extractSessionIdFromHref(href);
+    if (id) ids.add(id);
+  }
+  return ids;
+}
+
+// Given a bullet line like `- [session abc](../../chat/abc-123.jsonl)`,
+// return the href. Returns null for malformed bullets.
+function extractHrefFromBullet(line: string): string | null {
+  const bracketOpen = line.indexOf("[");
+  if (bracketOpen === -1) return null;
+  const bracketClose = line.indexOf("]", bracketOpen + 1);
+  if (bracketClose === -1) return null;
+  if (line[bracketClose + 1] !== "(") return null;
+  const parenClose = line.indexOf(")", bracketClose + 2);
+  if (parenClose === -1) return null;
+  return line.slice(bracketClose + 2, parenClose);
+}
+
+// Pull the session id out of an href that ends with a `.jsonl`
+// filename under some `chat/` segment. Supports both workspace-
+// absolute (`/chat/<id>.jsonl`) and relative (`../../chat/<id>.jsonl`)
+// forms so the dedupe is robust to the caller's path choice.
+function extractSessionIdFromHref(href: string): string | null {
+  const JSONL_SUFFIX = ".jsonl";
+  // Strip optional #fragment or ?query tail.
+  const cleanHref = stripFragmentAndQuery(href);
+  if (!cleanHref.endsWith(JSONL_SUFFIX)) return null;
+  const lastSlash = cleanHref.lastIndexOf("/");
+  if (lastSlash === -1) return null;
+  const parentSegment = findPrecedingSegment(cleanHref, lastSlash);
+  if (parentSegment !== "chat") return null;
+  const id = cleanHref.slice(lastSlash + 1, cleanHref.length - JSONL_SUFFIX.length);
+  if (id.length === 0 || id.includes("/")) return null;
+  return id;
+}
+
+function stripFragmentAndQuery(s: string): string {
+  let end = s.length;
+  const hash = s.indexOf("#");
+  if (hash !== -1) end = hash;
+  const query = s.indexOf("?");
+  if (query !== -1 && query < end) end = query;
+  return s.slice(0, end);
+}
+
+// Given `.../chat/abc.jsonl` and the index of the last `/`, return
+// the segment immediately before the filename (here: `"chat"`).
+function findPrecedingSegment(s: string, lastSlash: number): string {
+  const prevSlash = s.lastIndexOf("/", lastSlash - 1);
+  return s.slice(prevSlash + 1, lastSlash);
+}
+
+// Insert `newBullet` at the end of the History list inside the
+// appendix. The appendix already contains the marker + heading +
+// zero or more bullets; we simply append another bullet line,
+// preserving any trailing blank lines the user may have added.
+function appendBulletToAppendix(appendix: string, newBullet: string): string {
+  // Normalise: ensure exactly one trailing newline before adding.
+  // Hand-rolled rtrim so sonarjs/slow-regex stays quiet.
+  let end = appendix.length;
+  while (end > 0) {
+    const ch = appendix.charCodeAt(end - 1);
+    // Whitespace codepoints we expect here: \n, \r, \t, space.
+    if (ch !== 10 && ch !== 13 && ch !== 9 && ch !== 32) break;
+    end--;
+  }
+  return `${appendix.slice(0, end)}\n${newBullet}\n`;
+}

package/server/workspace/workspace.ts

@@ -0,0 +1,66 @@
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { log } from "../system/logger/index.js";
+import { EAGER_WORKSPACE_DIRS, WORKSPACE_FILES, WORKSPACE_PATHS, workspacePath } from "./paths.js";
+import { existsInWorkspace, writeWorkspaceTextSync } from "../utils/files/workspace-io.js";
+import { loadCustomDirs, ensureCustomDirs } from "./custom-dirs.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(__dirname, "helps");
+
+// Re-exported so existing callers (`import { workspacePath } from
+// "./workspace.js"`) keep working. See workspace-paths.ts for the
+// definitive source.
+export { workspacePath };
+
+// Must exist before downstream modules call realpathSync(workspacePath) at their own module-load time.
+fs.mkdirSync(workspacePath, { recursive: true });
+
+export function initWorkspace(): string {
+  // Create directory structure if needed
+  for (const key of EAGER_WORKSPACE_DIRS) {
+    fs.mkdirSync(WORKSPACE_PATHS[key], { recursive: true });
+  }
+
+  // Create memory.md if it doesn't exist
+  if (!existsInWorkspace(WORKSPACE_FILES.memory)) {
+    writeWorkspaceTextSync(WORKSPACE_FILES.memory, "# Memory\n\nDistilled facts about you and your work.\n");
+  }
+
+  // Always sync all files from server/helps/ into workspace/helps/
+  fs.mkdirSync(WORKSPACE_PATHS.helps, { recursive: true });
+  for (const file of fs.readdirSync(TEMPLATES_DIR)) {
+    fs.copyFileSync(path.join(TEMPLATES_DIR, file), path.join(WORKSPACE_PATHS.helps, file));
+  }
+
+  // Create .gitignore if missing. The workspace is a git repo for
+  // version-tracking user data, but cloned dev repos under github/
+  // have their own .git and shouldn't be committed (#256).
+  if (!existsInWorkspace(".gitignore")) {
+    writeWorkspaceTextSync(
+      ".gitignore",
+      ["# Cloned repositories have their own .git — don't nest", "github/", "", "# Auth token (regenerated each startup)", ".session-token", ""].join("\n"),
+    );
+  }
+
+  // User-defined custom directories (#239)
+  const customDirs = loadCustomDirs();
+  if (customDirs.length > 0) {
+    ensureCustomDirs(customDirs);
+    log.info("workspace", "custom directories loaded", {
+      count: customDirs.length,
+    });
+  }
+
+  // Git init if not already a repo
+  const gitDir = path.join(workspacePath, ".git");
+  if (!fs.existsSync(gitDir)) {
+    execSync("git init", { cwd: workspacePath });
+    log.info("workspace", "initialized git repository", { workspacePath });
+  }
+
+  log.info("workspace", "ready", { workspacePath });
+  return workspacePath;
+}