@lyric_dev/data-loom 0.4.0 → 0.5.0

package/README.md

@@ -38,6 +38,31 @@ With no argument it uses the current directory. Then open <http://127.0.0.1:4317
 
 > Published to npm automatically by CI on version tags (`vX.Y.Z`) via GitHub Actions.
 
+## Run it always-on (background + autostart)
+
+The command above runs in the foreground and stops when you close the terminal. Since the daemon also hosts the MCP endpoint, you usually want it always running. Manage a detached background daemon with:
+
+```
+data-loom start [C:\path\to\project]   # launch detached; returns immediately
+data-loom status                       # is it running? where are the logs?
+data-loom stop                         # stop the background daemon
+data-loom restart [path]               # stop then start
+```
+
+There is at most one instance: `start` while one is already running is a no-op that just reports it. Background output goes to a log file (path shown by `status`) since there's no attached console — on Windows, `%LOCALAPPDATA%\data-loom\daemon.log` (macOS `~/Library/Application Support/data-loom/`, Linux `${XDG_STATE_HOME:-~/.local/state}/data-loom/`).
+
+To have it launch automatically when you log in:
+
+```
+data-loom autostart enable    # register a per-user login item AND start it now
+data-loom autostart status    # is autostart registered?
+data-loom autostart disable   # remove the login item (does not stop a running daemon)
+```
+
+`enable` also starts the daemon immediately; pass `--no-start` to only register for next login. The login item is per-user and needs no admin rights — a Startup-folder shortcut on Windows, a LaunchAgent on macOS, an XDG autostart entry on Linux.
+
+Everything is reversible: `data-loom stop`, `data-loom autostart disable`, and `data-loom disconnect claude-desktop` (below) undo each side effect, and each is idempotent.
+
 ## Run from source (development)
 
 Requires Node.js ≥ 20.
@@ -66,7 +91,15 @@ The running daemon also **hosts an MCP server** over HTTP, so your own Claude se
    claude mcp add --transport http --scope user data-loom http://127.0.0.1:4317/mcp
    ```
 
-   The MCP server lives in the daemon, so **DataLoom must be running** for the tools to be reachable (start it with `npx @lyric_dev/data-loom "C:\path\to\your\project"`). It binds to loopback only.
+   The MCP server lives in the daemon, so **DataLoom must be running** for the tools to be reachable (start it with `data-loom start` or `npx @lyric_dev/data-loom "C:\path\to\your\project"`). It binds to loopback only.
+
+   **Claude Desktop** reaches the same daemon — register it with:
+
+   ```
+   data-loom connect claude-desktop
+   ```
+
+   This adds a `data-loom` entry to Claude Desktop's `claude_desktop_config.json` (additively — your other servers are untouched), pointing at the same loopback endpoint via Claude Desktop's native remote-MCP support. Restart Claude Desktop to pick it up. On older Claude Desktop versions without native remote support, pass `--bridge` to register a stdio↔HTTP bridge (`npx mcp-remote`) instead. Remove it any time with `data-loom disconnect claude-desktop`. As with Claude Code, the daemon must be running for the tools to appear.
 
 2. In any project, ask Claude something like *"review DataLoom's open proposals and set the dependencies."* On connect, the server asks Claude to surface any proposal that hasn't been reviewed for dependencies yet, propose the edges, and **confirm with you before writing**. It exposes these tools:
    - `list_projects` — the selectable OpenSpec workspaces plus the current selection (read-only), to discover/confirm a `project` path.
@@ -81,6 +114,17 @@ The running daemon also **hosts an MCP server** over HTTP, so your own Claude se
 
 > **Upgrading from an earlier version?** The MCP server used to be a per-project stdio registration (`claude mcp add data-loom -- npx … mcp "<path>"`). That mode is gone. Remove any old per-project `data-loom` registrations and add the single user-scope HTTP one above.
 
+## Security
+
+DataLoom runs entirely on `127.0.0.1` and is built for a single local user.
+
+- **Loopback only** — the daemon (dashboard, WebSocket, and MCP endpoint) binds to the loopback interface and is never exposed to the network.
+- **Host + Origin validated** — every HTTP request and WebSocket upgrade is checked: requests with a non-loopback `Host` (DNS-rebinding) or a non-loopback `Origin` (cross-site requests from a web page) are rejected. Native MCP clients (which send no `Origin`) are allowed. This is what keeps a random website you visit from driving the daemon.
+- **No secrets** — the MCP tools carry only proposal text and change names; the topology view redacts server commands/args and shows scheme+host only. No API keys or config are read or returned, and the daemon holds no credential.
+- **Bounded** — request bodies are capped (4 MB) and MCP sessions are capped and idle-evicted, so a local client can't exhaust memory.
+
+The MCP tools can read and write any OpenSpec workspace path you point them at (this is intentional, so the tool can stay LLM-provider-independent). That means: treat the daemon as you would any local dev server — fine for your own machine, not something to run on a shared/multi-user host.
+
 ## Design principles
 
 - **Derived, not stored** — phase/order is a pure function of the OpenSpec files, recomputed on every change. Nothing about ordering is persisted.

package/dist/autostart.js

@@ -0,0 +1,141 @@
+// Per-user login autostart: register the background daemon to launch when the
+// user logs in, using the native, no-elevation mechanism for each OS —
+//   Windows  a shortcut in the per-user Startup folder
+//   macOS    a LaunchAgent plist with RunAtLoad
+//   Linux    an XDG autostart .desktop entry
+// Every registration launches `<node> <script> start`, so a login-triggered
+// launch shares the exact same detached/single-instance/logging path as a
+// manual `data-loom start`.
+import { spawn } from "node:child_process";
+import { writeFile, rm, access, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const NODE = process.execPath;
+const SCRIPT = process.argv[1];
+const LABEL = "dev.lyric.data-loom";
+function exists(p) {
+    return access(p).then(() => true, () => false);
+}
+// ---- Windows: Startup-folder shortcut -------------------------------------
+function winStartupLnk() {
+    const appData = process.env.APPDATA ?? join(homedir(), "AppData", "Roaming");
+    return join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup", "data-loom.lnk");
+}
+function runPowerShell(script) {
+    return new Promise((resolve, reject) => {
+        const ps = spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script], { windowsHide: true, stdio: "ignore" });
+        ps.on("error", reject);
+        ps.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`powershell exited ${code}`))));
+    });
+}
+async function winEnable() {
+    const lnk = winStartupLnk();
+    await mkdir(dirname(lnk), { recursive: true });
+    // Create the .lnk via WScript.Shell; WindowStyle 7 = minimized so the brief
+    // launcher console doesn't grab focus (the daemon itself is detached).
+    const q = (s) => `'${s.replace(/'/g, "''")}'`;
+    await runPowerShell([
+        "$s = (New-Object -ComObject WScript.Shell).CreateShortcut(" + q(lnk) + ")",
+        "$s.TargetPath = " + q(NODE),
+        '$s.Arguments = ' + q(`"${SCRIPT}" start`),
+        "$s.WindowStyle = 7",
+        "$s.Description = 'DataLoom background daemon'",
+        "$s.Save()",
+    ].join("; "));
+}
+async function winDisable() {
+    await rm(winStartupLnk(), { force: true }).catch(() => { });
+}
+// ---- macOS: LaunchAgent ----------------------------------------------------
+function macPlistPath() {
+    return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+}
+async function macEnable() {
+    const path = macPlistPath();
+    await mkdir(dirname(path), { recursive: true });
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${NODE}</string>
+    <string>${SCRIPT}</string>
+    <string>start</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+</dict>
+</plist>
+`;
+    await writeFile(path, plist, "utf8");
+    await new Promise((resolve) => {
+        const p = spawn("launchctl", ["load", "-w", path], { stdio: "ignore" });
+        p.on("error", () => resolve()); // best-effort; the plist is written regardless
+        p.on("exit", () => resolve());
+    });
+}
+async function macDisable() {
+    const path = macPlistPath();
+    if (await exists(path)) {
+        await new Promise((resolve) => {
+            const p = spawn("launchctl", ["unload", "-w", path], { stdio: "ignore" });
+            p.on("error", () => resolve());
+            p.on("exit", () => resolve());
+        });
+    }
+    await rm(path, { force: true }).catch(() => { });
+}
+// ---- Linux: XDG autostart --------------------------------------------------
+function linuxDesktopPath() {
+    const cfg = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(cfg, "autostart", "data-loom.desktop");
+}
+async function linuxEnable() {
+    await mkdir(dirname(linuxDesktopPath()), { recursive: true });
+    const entry = `[Desktop Entry]
+Type=Application
+Name=DataLoom
+Comment=DataLoom background daemon
+Exec="${NODE}" "${SCRIPT}" start
+X-GNOME-Autostart-enabled=true
+`;
+    await writeFile(linuxDesktopPath(), entry, "utf8");
+}
+async function linuxDisable() {
+    await rm(linuxDesktopPath(), { force: true }).catch(() => { });
+}
+// ---- Dispatch --------------------------------------------------------------
+function unsupported() {
+    throw new Error(`[data-loom] autostart is not supported on platform "${process.platform}"`);
+}
+/** Register the daemon to launch at login (idempotent — overwrites any prior). */
+export async function enable() {
+    if (process.platform === "win32")
+        return winEnable();
+    if (process.platform === "darwin")
+        return macEnable();
+    if (process.platform === "linux")
+        return linuxEnable();
+    unsupported();
+}
+/** Remove the login registration (idempotent — succeeds when not enabled). */
+export async function disable() {
+    if (process.platform === "win32")
+        return winDisable();
+    if (process.platform === "darwin")
+        return macDisable();
+    if (process.platform === "linux")
+        return linuxDisable();
+    unsupported();
+}
+/** True iff a login registration currently exists for this user. */
+export async function isEnabled() {
+    if (process.platform === "win32")
+        return exists(winStartupLnk());
+    if (process.platform === "darwin")
+        return exists(macPlistPath());
+    if (process.platform === "linux")
+        return exists(linuxDesktopPath());
+    return false;
+}

package/dist/claudeDesktop.js

@@ -0,0 +1,82 @@
+// Claude Desktop integration: register DataLoom's loopback MCP endpoint into
+// Claude Desktop's claude_desktop_config.json so the same running daemon that
+// serves Claude Code also serves Claude Desktop.
+//
+// By default we write the native remote/HTTP form (a URL entry) — no extra
+// process, one daemon as the single source of truth. Claude Desktop versions
+// without native remote support use the stdio bridge (`npx mcp-remote <url>`),
+// which the caller forces with `--bridge`. Either way the daemon needs no change:
+// it already permits native (no-Origin) MCP clients on loopback.
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { mcpUrl } from "./paths.js";
+const KEY = "data-loom";
+/** Per-OS location of Claude Desktop's config file. */
+export function configPath() {
+    if (process.platform === "win32") {
+        const appData = process.env.APPDATA ?? join(homedir(), "AppData", "Roaming");
+        return join(appData, "Claude", "claude_desktop_config.json");
+    }
+    if (process.platform === "darwin") {
+        return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    const cfg = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(cfg, "Claude", "claude_desktop_config.json");
+}
+/** Read + parse the config, or return {} when absent. Throws on malformed JSON. */
+async function readConfig(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        return {};
+    }
+    if (!raw.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null) {
+            throw new Error("not a JSON object");
+        }
+        return parsed;
+    }
+    catch (e) {
+        throw new Error(`[data-loom] ${path} is not valid JSON (${e instanceof Error ? e.message : "parse error"}); ` +
+            "fix or remove it, then retry — DataLoom will not overwrite it.");
+    }
+}
+async function writeConfig(path, cfg) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+/** The MCP entry we register — native URL form by default, stdio bridge on demand. */
+function entry(bridge) {
+    const url = mcpUrl();
+    return bridge ? { command: "npx", args: ["-y", "mcp-remote", url] } : { type: "http", url };
+}
+/**
+ * Add/update DataLoom's entry under mcpServers, preserving everything else.
+ * Returns the path written so the caller can report it.
+ */
+export async function connect(opts = {}) {
+    const path = configPath();
+    const cfg = await readConfig(path);
+    cfg.mcpServers = { ...(cfg.mcpServers ?? {}), [KEY]: entry(opts.bridge ?? false) };
+    await writeConfig(path, cfg);
+    return path;
+}
+/**
+ * Remove only DataLoom's entry. Idempotent — returns false when nothing was
+ * registered (so the caller can say "nothing to remove").
+ */
+export async function disconnect() {
+    const path = configPath();
+    const cfg = await readConfig(path);
+    if (!cfg.mcpServers || !(KEY in cfg.mcpServers))
+        return { path, removed: false };
+    delete cfg.mcpServers[KEY];
+    await writeConfig(path, cfg);
+    return { path, removed: true };
+}

package/dist/index.js

@@ -12,8 +12,12 @@ import { discover } from "./mcp/discovery.js";
 import { checkServer } from "./mcp/availability.js";
 import { discoverProjects, isViewableProject } from "./projects.js";
 import { resolvePublicDir } from "./assets.js";
-const host = "127.0.0.1";
-const port = Number(process.env.PORT ?? 4317);
+import { HOST, PORT } from "./paths.js";
+import * as lifecycle from "./lifecycle.js";
+import * as autostart from "./autostart.js";
+import * as claudeDesktop from "./claudeDesktop.js";
+const host = HOST;
+const port = PORT;
 // Initial project: CLI argument, then DATA_LOOM_ROOT, then cwd.
 const initialProject = resolve(process.argv[2] ?? process.env.DATA_LOOM_ROOT ?? process.cwd());
 let session;
@@ -124,7 +128,9 @@ function getProjects() {
     return discoverProjects(session?.project ?? "");
 }
 function openBrowser(url) {
-    if (process.env.DATA_LOOM_NO_OPEN)
+    // Detached background runs have no attached console and no user waiting at the
+    // terminal, so never pop a browser for them (nor when explicitly suppressed).
+    if (process.env.DATA_LOOM_NO_OPEN || process.env.DATA_LOOM_DETACHED)
         return;
     try {
         if (process.platform === "win32") {
@@ -141,7 +147,82 @@ function openBrowser(url) {
         /* non-fatal — the URL is already logged */
     }
 }
-main().catch((err) => {
-    console.error(err);
-    process.exit(1);
-});
+// ---- CLI verb dispatch -----------------------------------------------------
+// A leading reserved verb selects a lifecycle/autostart/integration command;
+// anything else falls through to the foreground daemon (with argv[2] as the
+// optional project path), preserving the original invocation unchanged.
+const VERBS = new Set(["start", "stop", "restart", "status", "autostart", "connect", "disconnect"]);
+async function runAutostart(rest) {
+    const sub = rest[0];
+    if (sub === "enable") {
+        await autostart.enable();
+        console.log("[data-loom] autostart enabled (launches on login)");
+        // Enabling also brings the daemon up now, so it's running this session too —
+        // opt out with --no-start.
+        if (!rest.includes("--no-start"))
+            await lifecycle.start();
+        return;
+    }
+    if (sub === "disable") {
+        await autostart.disable();
+        console.log("[data-loom] autostart disabled");
+        return;
+    }
+    if (sub === "status") {
+        console.log((await autostart.isEnabled())
+            ? "[data-loom] autostart is enabled"
+            : "[data-loom] autostart is not enabled");
+        return;
+    }
+    throw new Error("usage: data-loom autostart <enable|disable|status> [--no-start]");
+}
+async function runConnect(rest) {
+    if (rest[0] !== "claude-desktop")
+        throw new Error("usage: data-loom connect claude-desktop [--bridge]");
+    const bridge = rest.includes("--bridge");
+    const path = await claudeDesktop.connect({ bridge });
+    console.log(`[data-loom] registered DataLoom in Claude Desktop (${bridge ? "stdio bridge" : "native HTTP"}) — ${path}`);
+    console.log("[data-loom] restart Claude Desktop to pick it up; DataLoom must be running to serve the tools.");
+}
+async function runDisconnect(rest) {
+    if (rest[0] !== "claude-desktop")
+        throw new Error("usage: data-loom disconnect claude-desktop");
+    const { path, removed } = await claudeDesktop.disconnect();
+    console.log(removed
+        ? `[data-loom] removed DataLoom from Claude Desktop — ${path}`
+        : "[data-loom] DataLoom was not registered in Claude Desktop — nothing to remove");
+}
+async function runCli(argv) {
+    const [verb, ...rest] = argv;
+    switch (verb) {
+        case "start":
+            return lifecycle.start(rest[0]);
+        case "stop":
+            return lifecycle.stop();
+        case "restart":
+            return lifecycle.restart(rest[0]);
+        case "status":
+            return lifecycle.status();
+        case "autostart":
+            return runAutostart(rest);
+        case "connect":
+            return runConnect(rest);
+        case "disconnect":
+            return runDisconnect(rest);
+        default:
+            throw new Error(`unknown command: ${verb}`);
+    }
+}
+const cliArgs = process.argv.slice(2);
+if (cliArgs[0] && VERBS.has(cliArgs[0])) {
+    runCli(cliArgs).catch((err) => {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}
+else {
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/dist/lifecycle.js

@@ -0,0 +1,101 @@
+// Background lifecycle for the daemon: start it detached, stop it, restart it,
+// and report status. The loopback port is the authoritative "is it running?"
+// signal — a stale PID file never blocks a start, because the source of truth is
+// whether something actually answers on the port.
+import { spawn } from "node:child_process";
+import { openSync } from "node:fs";
+import { readFile, writeFile, rm } from "node:fs/promises";
+import { get } from "node:http";
+import { HOST, PORT, baseUrl, logFile, pidFile, ensureStateDir } from "./paths.js";
+/** Probe the loopback endpoint; true iff a daemon answers within the timeout. */
+export function isRunning() {
+    return new Promise((resolve) => {
+        const req = get({ host: HOST, port: PORT, path: "/api/model", timeout: 1000 }, (res) => {
+            res.resume(); // drain
+            resolve(true);
+        });
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve(false);
+        });
+    });
+}
+async function readPid() {
+    try {
+        const n = Number((await readFile(pidFile(), "utf8")).trim());
+        return Number.isInteger(n) && n > 0 ? n : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Start the daemon detached from this terminal. If one already answers on the
+ * port, this is a reported no-op (single-instance guard). The child re-runs this
+ * same entry point in the foreground with DATA_LOOM_DETACHED set so it skips the
+ * browser and logs to the state-dir log file.
+ */
+export async function start(project) {
+    if (await isRunning()) {
+        console.log(`[data-loom] already running — ${baseUrl()}`);
+        return;
+    }
+    await ensureStateDir();
+    const out = openSync(logFile(), "a");
+    const args = [process.argv[1], ...(project ? [project] : [])];
+    const child = spawn(process.execPath, args, {
+        detached: true,
+        windowsHide: true,
+        stdio: ["ignore", out, out],
+        env: { ...process.env, DATA_LOOM_DETACHED: "1" },
+    });
+    child.unref();
+    if (child.pid)
+        await writeFile(pidFile(), String(child.pid), "utf8");
+    console.log(`[data-loom] started in background (pid ${child.pid ?? "?"}) — ${baseUrl()}`);
+    console.log(`[data-loom] logs: ${logFile()}`);
+}
+/** Stop the background daemon; a no-op (with notice) when nothing is running. */
+export async function stop() {
+    const pid = await readPid();
+    const running = await isRunning();
+    if (!running && pid === undefined) {
+        console.log("[data-loom] not running — nothing to stop");
+        return;
+    }
+    if (pid !== undefined) {
+        try {
+            process.kill(pid, "SIGTERM");
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    else if (running) {
+        console.error("[data-loom] a daemon is answering the port but no PID file was found; stop it manually");
+        return;
+    }
+    // Wait for the port to actually free (up to ~5s), then drop the PID file.
+    for (let i = 0; i < 25 && (await isRunning()); i++)
+        await delay(200);
+    await rm(pidFile(), { force: true }).catch(() => { });
+    console.log("[data-loom] stopped");
+}
+/** Restart: stop any running instance, then start a fresh one. */
+export async function restart(project) {
+    await stop();
+    await start(project);
+}
+/** Report whether the daemon is running, and where to reach it / find its logs. */
+export async function status() {
+    if (await isRunning()) {
+        const pid = await readPid();
+        console.log(`[data-loom] running — ${baseUrl()}${pid !== undefined ? ` (pid ${pid})` : ""}`);
+        console.log(`[data-loom] logs: ${logFile()}`);
+    }
+    else {
+        console.log("[data-loom] not running");
+    }
+}

package/dist/mcpServer.js

@@ -15,6 +15,14 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { OpenSpecClient } from "./openspecClient.js";
 import { deriveModel } from "./derive.js";
 import { discoverProjects, isViewableProject } from "./projects.js";
+/**
+ * A validation error whose message is safe to return to the client because it
+ * only references caller-supplied input (a change name, a path the caller named).
+ * Anything that is NOT a ToolError is treated as an unexpected internal failure
+ * and reported generically, so host filesystem detail never leaks.
+ */
+class ToolError extends Error {
+}
 // Advertised to the client on connect. The "confirm before writing" gate lives
 // here, in the agent's behavior — the server cannot verify a human approved.
 const INSTRUCTIONS = `This server exposes a project's open OpenSpec proposals and lets you record the dependency order between them. It holds no model and cannot infer anything on its own — the judgment is yours and the decision is the user's.
@@ -67,18 +75,18 @@ const PROJECT_ARG = {
  * the dashboard selection is the single fallback source of project truth.
  */
 export function createMcpServer(deps) {
-    const server = new Server({ name: "data-loom", version: "0.4.0" }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    const server = new Server({ name: "data-loom", version: "0.4.1" }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
     // Resolve the target project for a call: explicit arg, then dashboard
     // selection, then an instructive error. Validated as a real workspace before
     // any read or write.
     const resolveProject = (explicit) => {
         const raw = typeof explicit === "string" && explicit.trim() ? explicit : deps.getCurrentProject();
         if (!raw) {
-            throw new Error("No `project` given and no project is selected in the DataLoom dashboard. Call list_projects to see the available OpenSpec workspaces, then pass one as the `project` argument.");
+            throw new ToolError("No `project` given and no project is selected in the DataLoom dashboard. Call list_projects to see the available OpenSpec workspaces, then pass one as the `project` argument.");
         }
         const abs = resolve(raw);
         if (!isViewableProject(abs)) {
-            throw new Error(`${abs} is not an OpenSpec workspace (no openspec/ directory). Call list_projects to see the available workspaces.`);
+            throw new ToolError(`${abs} is not an OpenSpec workspace (no openspec/ directory). Call list_projects to see the available workspaces.`);
         }
         return abs;
     };
@@ -161,7 +169,12 @@ export function createMcpServer(deps) {
             return err(`unknown tool: ${name}`);
         }
         catch (e) {
-            return err(e instanceof Error ? e.message : String(e));
+            // Validation errors (caller-supplied input) are safe to surface; anything
+            // else is an unexpected internal failure → generic message, detail to log.
+            if (e instanceof ToolError)
+                return err(e.message);
+            console.error("[data-loom mcp] tool error:", e);
+            return err("internal error");
         }
     });
     return server;
@@ -202,14 +215,14 @@ async function listOpenProposals(client, changesDir, project) {
 }
 async function setDependency(client, changesDir, project, from, to) {
     if (!from || !to)
-        throw new Error("both 'from' and 'to' are required");
+        throw new ToolError("both 'from' and 'to' are required");
     if (from === to)
-        throw new Error("a change cannot depend on itself");
+        throw new ToolError("a change cannot depend on itself");
     const names = new Set((await openChanges(client)).map((c) => c.name));
     if (!names.has(from))
-        throw new Error(`unknown open change: ${from}`);
+        throw new ToolError(`unknown open change: ${from}`);
     if (!names.has(to))
-        throw new Error(`unknown open change: ${to}`);
+        throw new ToolError(`unknown open change: ${to}`);
     const path = join(changesDir, from, "proposal.md");
     const text = await readFile(path, "utf8");
     const updated = addDependsOn(text, to);
@@ -220,10 +233,10 @@ async function setDependency(client, changesDir, project, from, to) {
 }
 async function markIndependent(client, changesDir, project, change) {
     if (!change)
-        throw new Error("'change' is required");
+        throw new ToolError("'change' is required");
     const names = new Set((await openChanges(client)).map((c) => c.name));
     if (!names.has(change))
-        throw new Error(`unknown open change: ${change}`);
+        throw new ToolError(`unknown open change: ${change}`);
     const path = join(changesDir, change, "proposal.md");
     const text = await readFile(path, "utf8");
     const updated = ensureDependsOnSection(text);

package/dist/paths.js

@@ -0,0 +1,39 @@
+// Shared config + per-user state locations for the daemon and its CLI verbs.
+// The lifecycle commands (start/stop/status), autostart registration, and the
+// Claude Desktop integration all need to agree on the loopback address, the
+// state directory, and the PID/log paths — so they live here, in one place.
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Loopback host + port the daemon binds. Port overridable via env for tests. */
+export const HOST = "127.0.0.1";
+export const PORT = Number(process.env.PORT ?? 4317);
+/** Dashboard base URL and the MCP endpoint hosted on the same authority. */
+export const baseUrl = () => `http://${HOST}:${PORT}`;
+export const mcpUrl = () => `${baseUrl()}/mcp`;
+/**
+ * Per-user state directory, using the OS convention:
+ *   Windows  %LOCALAPPDATA%\data-loom
+ *   macOS    ~/Library/Application Support/data-loom
+ *   Linux    ${XDG_STATE_HOME:-~/.local/state}/data-loom
+ * Holds the PID file and the background log — never the project dir.
+ */
+export function stateDir() {
+    if (process.platform === "win32") {
+        const local = process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local");
+        return join(local, "data-loom");
+    }
+    if (process.platform === "darwin") {
+        return join(homedir(), "Library", "Application Support", "data-loom");
+    }
+    const xdg = process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
+    return join(xdg, "data-loom");
+}
+export const pidFile = () => join(stateDir(), "daemon.pid");
+export const logFile = () => join(stateDir(), "daemon.log");
+/** Create the state dir on demand; safe to call repeatedly. */
+export async function ensureStateDir() {
+    const dir = stateDir();
+    await mkdir(dir, { recursive: true });
+    return dir;
+}

package/dist/server.js

@@ -1,7 +1,7 @@
 // Serve the SPA on loopback and push roadmap + MCP + project state over a websocket.
 import { createServer } from "node:http";
 import { randomUUID } from "node:crypto";
-import { extname } from "node:path";
+import { extname, resolve, sep } from "node:path";
 import { WebSocketServer, WebSocket } from "ws";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
@@ -24,53 +24,110 @@ export async function startServer(opts) {
                 ws.send(data);
         }
     };
+    // Loopback origin/host allowlist — the DNS-rebinding + CSRF guard. Built from
+    // the actually-bound port after listen; seeded from the requested port so the
+    // guard is active from the first request.
+    const loopbackHosts = ["127.0.0.1", "localhost", "[::1]"];
+    let allowedAuthorities = new Set();
+    const setAllowed = (p) => {
+        allowedAuthorities = new Set(loopbackHosts.map((h) => `${h}:${p}`));
+    };
+    setAllowed(port);
+    // Reject what a hostile web page or a rebound DNS name could mount: a Host
+    // that is not our loopback authority (DNS rebinding), or any *present* Origin
+    // that is not a loopback origin (CSRF). An absent Origin = a native, non-
+    // browser client (e.g. Claude Code), which is allowed.
+    const isAllowed = (req) => {
+        const host = req.headers.host;
+        if (!host || !allowedAuthorities.has(host))
+            return false;
+        const origin = req.headers.origin;
+        if (origin) {
+            try {
+                if (!allowedAuthorities.has(new URL(origin).host))
+                    return false;
+            }
+            catch {
+                return false;
+            }
+        }
+        return true;
+    };
     // One MCP server + transport per client session (stateful Streamable-HTTP),
-    // keyed by the session id. Each session's tools resolve their target project
-    // per call from getCurrentProject (see mcpServer.ts), so one daemon serves
-    // every project.
-    const mcpTransports = new Map();
+    // keyed by session id. Sessions are capped and idle-evicted so churn cannot
+    // grow memory without bound. Tools resolve their target project per call from
+    // getCurrentProject (see mcpServer.ts), so one daemon serves every project.
+    const MAX_SESSIONS = 32;
+    const SESSION_IDLE_TTL_MS = 30 * 60 * 1000;
+    const mcpSessions = new Map();
+    const idleSweep = setInterval(() => {
+        const now = Date.now();
+        for (const [sid, s] of mcpSessions) {
+            if (now - s.lastSeen > SESSION_IDLE_TTL_MS) {
+                mcpSessions.delete(sid);
+                void s.transport.close();
+            }
+        }
+    }, 60 * 1000);
+    idleSweep.unref();
     const handleMcp = async (req, res) => {
         const sessionId = req.headers["mcp-session-id"];
         try {
             if (req.method === "POST") {
                 const body = await readJsonBody(req);
-                let transport = sessionId ? mcpTransports.get(sessionId) : undefined;
-                if (!transport) {
-                    if (!isInitializeRequest(body)) {
-                        return sendError(res, 400, "missing or invalid mcp-session-id");
-                    }
-                    transport = new StreamableHTTPServerTransport({
-                        sessionIdGenerator: () => randomUUID(),
-                        onsessioninitialized: (sid) => {
-                            mcpTransports.set(sid, transport);
-                        },
-                    });
-                    transport.onclose = () => {
-                        if (transport.sessionId)
-                            mcpTransports.delete(transport.sessionId);
-                    };
-                    await createMcpServer({ getCurrentProject }).connect(transport);
+                const existing = sessionId ? mcpSessions.get(sessionId) : undefined;
+                if (existing) {
+                    existing.lastSeen = Date.now();
+                    await existing.transport.handleRequest(req, res, body);
+                    return;
+                }
+                if (!isInitializeRequest(body)) {
+                    return sendError(res, 400, "missing or invalid mcp-session-id");
                 }
+                if (mcpSessions.size >= MAX_SESSIONS) {
+                    return sendError(res, 503, "too many sessions");
+                }
+                const transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (sid) => {
+                        mcpSessions.set(sid, { transport, lastSeen: Date.now() });
+                    },
+                });
+                transport.onclose = () => {
+                    if (transport.sessionId)
+                        mcpSessions.delete(transport.sessionId);
+                };
+                await createMcpServer({ getCurrentProject }).connect(transport);
                 await transport.handleRequest(req, res, body);
                 return;
             }
             if (req.method === "GET" || req.method === "DELETE") {
-                const transport = sessionId ? mcpTransports.get(sessionId) : undefined;
-                if (!transport)
+                const s = sessionId ? mcpSessions.get(sessionId) : undefined;
+                if (!s)
                     return sendError(res, 400, "missing or invalid mcp-session-id");
-                await transport.handleRequest(req, res);
+                s.lastSeen = Date.now();
+                await s.transport.handleRequest(req, res);
                 return;
             }
             return sendError(res, 405, "method not allowed");
         }
         catch (e) {
-            if (!res.headersSent) {
-                sendError(res, 500, e instanceof Error ? e.message : "mcp error");
+            if (e instanceof PayloadTooLargeError) {
+                if (!res.headersSent)
+                    sendError(res, 413, "request body too large");
+                return;
             }
+            // Unexpected failures stay in the server log; the client gets nothing
+            // about the host (no paths, no stack).
+            console.error("[data-loom] mcp request error:", e);
+            if (!res.headersSent)
+                sendError(res, 500, "internal error");
         }
     };
     const http = createServer(async (req, res) => {
         try {
+            if (!isAllowed(req))
+                return sendError(res, 403, "forbidden");
             const url = new URL(req.url ?? "/", `http://${host}`);
             if (url.pathname === "/mcp")
                 return handleMcp(req, res);
@@ -96,9 +153,12 @@ export async function startServer(opts) {
                     return sendError(res, 400, err instanceof Error ? err.message : "invalid project");
                 }
             }
-            // static assets (served from public/ on the filesystem)
+            // static assets (served from public/ on the filesystem) — resolve and
+            // assert the path stays within publicDir before reading.
             const rel = url.pathname === "/" ? "index.html" : url.pathname.replace(/^\/+/, "");
-            if (rel.includes(".."))
+            const root = resolve(publicDir);
+            const full = resolve(root, rel);
+            if (full !== root && !full.startsWith(root + sep))
                 return sendError(res, 403, "forbidden");
             const file = await loadAsset(rel, publicDir);
             if (!file)
@@ -110,7 +170,10 @@ export async function startServer(opts) {
             sendError(res, 500, "error");
         }
     });
-    wss = new WebSocketServer({ server: http });
+    wss = new WebSocketServer({
+        server: http,
+        verifyClient: (info) => isAllowed(info.req),
+    });
     wss.on("connection", async (ws) => {
         const roadmap = getRoadmap();
         if (roadmap)
@@ -123,11 +186,14 @@ export async function startServer(opts) {
             /* project list optional */
         }
     });
-    await new Promise((resolve) => http.listen(port, host, resolve));
+    await new Promise((ready) => http.listen(port, host, ready));
+    const actualPort = http.address()?.port ?? port;
+    setAllowed(actualPort);
     return {
-        port,
+        port: actualPort,
         broadcast,
         close: () => {
+            clearInterval(idleSweep);
             wss.close();
             http.close();
         },
@@ -141,12 +207,32 @@ function sendError(res, code, message) {
     res.writeHead(code, { "content-type": MIME[".json"] });
     res.end(JSON.stringify({ error: message }));
 }
+/** Raised when a request body exceeds the cap; mapped to HTTP 413. */
+class PayloadTooLargeError extends Error {
+}
+/** Largest request body we will buffer (JSON-RPC tool calls are tiny). */
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
 /** Read and JSON-parse a request body; returns undefined for an empty body. */
 function readJsonBody(req) {
     return new Promise((resolve, reject) => {
         let data = "";
-        req.on("data", (chunk) => (data += chunk));
+        let size = 0;
+        let aborted = false;
+        req.on("data", (chunk) => {
+            if (aborted)
+                return;
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                aborted = true;
+                reject(new PayloadTooLargeError("request body too large"));
+                req.destroy();
+                return;
+            }
+            data += chunk;
+        });
         req.on("end", () => {
+            if (aborted)
+                return;
             if (!data)
                 return resolve(undefined);
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyric_dev/data-loom",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Local dashboard for spec-driven development: a phased OpenSpec roadmap (WHAT) and an MCP topology (HOW).",
   "type": "module",
   "license": "MIT",