@lyric_dev/data-loom 0.4.1 → 0.6.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 **and registers DataLoom with Claude Code** (the same as `data-loom connect claude-code`), so the always-on path both hosts the MCP endpoint and points Claude Code at it in one command. Pass `--no-start` to only register for next login, or `--no-connect` to skip the Claude Code registration. The Claude Code step is best-effort — if the `claude` CLI isn't found, `enable` warns and still sets up the login item and daemon. 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`, `data-loom disconnect claude-code`, and `data-loom disconnect claude-desktop` (below) undo each side effect, and each is idempotent.
+
 ## Run from source (development)
 
 Requires Node.js ≥ 20.
@@ -60,13 +85,29 @@ npm start            # serves the current directory's project
 
 The running daemon also **hosts an MCP server** over HTTP, so your own Claude session determines and applies the order of interdependent proposals — DataLoom holds no API key and the reasoning runs under your authenticated Claude. One registration serves **every** project; the target project is resolved per call (an explicit `project` argument, falling back to whatever the dashboard has selected).
 
-1. Register it once, globally — no per-project setup:
+1. Register it once, globally — no per-project setup. The easy way:
+
+   ```
+   data-loom connect claude-code
+   ```
+
+   This registers DataLoom's loopback endpoint with Claude Code at user scope via Claude Code's own CLI (it runs `claude mcp add` for you; DataLoom never edits `~/.claude.json` itself). Start a new Claude Code session to pick it up, and remove it any time with `data-loom disconnect claude-code`. If the `claude` CLI isn't on your PATH, the command prints the manual line to run instead:
 
    ```
    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.
+   Either way, if you enable always-on autostart (below), `data-loom autostart enable` already runs this registration for you — so a fresh install can be one command.
+
+   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.

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/claudeCode.js

@@ -0,0 +1,81 @@
+// Claude Code integration: register DataLoom's loopback MCP endpoint with
+// Claude Code at user (global) scope, so the same running daemon that serves
+// the dashboard also serves a Claude Code session.
+//
+// Unlike the Claude Desktop integration (which edits a small, DataLoom-owned
+// config file directly), this registers through Claude Code's OWN CLI
+// (`claude mcp add`/`remove`). DataLoom never reads or writes `~/.claude.json`
+// itself — that file holds OAuth tokens and per-project history and is written
+// live by any running session, so its one owner (the `claude` CLI) serializes
+// the write. When the `claude` CLI is missing, connect degrades to printing the
+// manual command rather than failing hard.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mcpUrl } from "./paths.js";
+const execFileP = promisify(execFile);
+const KEY = "data-loom";
+/** On Windows the CLI is a `.cmd`/`.ps1` shim, so it must be invoked through a shell. */
+function runClaude(args) {
+    return execFileP("claude", args, { shell: process.platform === "win32" });
+}
+/** The registration command a user can run by hand when the `claude` CLI is absent. */
+export function manualCommand() {
+    return `claude mcp add --transport http --scope user ${KEY} ${mcpUrl()}`;
+}
+/** True iff the `claude` CLI is invocable (resolves its version). */
+async function claudeAvailable() {
+    try {
+        await runClaude(["--version"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove any existing user-scope registration; tolerates "not registered". */
+async function removeRegistration() {
+    try {
+        await runClaude(["mcp", "remove", "--scope", "user", KEY]);
+    }
+    catch {
+        /* not registered (or nothing to remove) — idempotent no-op */
+    }
+}
+/**
+ * Register DataLoom with Claude Code at user scope, pointing at the daemon's
+ * loopback HTTP MCP endpoint. Idempotent upsert: remove any prior entry, then
+ * add, so exactly one current entry remains. Returns false (with printed
+ * guidance) when the `claude` CLI is unavailable, so callers can degrade
+ * gracefully instead of failing.
+ */
+export async function connect() {
+    if (!(await claudeAvailable())) {
+        console.log("[data-loom] the `claude` CLI was not found — cannot register automatically.\n" +
+            `[data-loom] register it by hand once with:\n    ${manualCommand()}`);
+        return false;
+    }
+    await removeRegistration();
+    await runClaude(["mcp", "add", "--transport", "http", "--scope", "user", KEY, mcpUrl()]);
+    return true;
+}
+/**
+ * Remove DataLoom's user-scope registration from Claude Code. Idempotent —
+ * reports whether anything was actually registered. Throws only if the `claude`
+ * CLI itself is unavailable (nothing could have been registered without it).
+ */
+export async function disconnect() {
+    if (!(await claudeAvailable())) {
+        throw new Error("the `claude` CLI was not found — nothing could have been registered");
+    }
+    // `claude mcp get <name>` exits non-zero when the entry is absent; use it to
+    // report removed-vs-nothing without parsing `list` output.
+    let existed = true;
+    try {
+        await runClaude(["mcp", "get", KEY]);
+    }
+    catch {
+        existed = false;
+    }
+    await removeRegistration();
+    return { removed: existed };
+}

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,14 @@ 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";
+import * as claudeCode from "./claudeCode.js";
+import { initTray } from "./tray.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;
@@ -42,28 +48,53 @@ async function main() {
     else {
         console.log("[data-loom] no openspec project found at launch — open the dashboard and pick one");
     }
-    server = await startServer({
-        publicDir: resolvePublicDir(),
-        host,
-        port,
-        getRoadmap: () => session?.model ?? null,
-        getMcp,
-        checkMcp,
-        getProjects,
-        selectProject,
-        getCurrentProject: () => session?.project ?? null,
-    });
-    console.log(`[data-loom] dashboard ready at http://${host}:${server.port}`);
+    try {
+        server = await startServer({
+            publicDir: resolvePublicDir(),
+            host,
+            port,
+            getRoadmap: () => session?.model ?? null,
+            getMcp,
+            checkMcp,
+            getProjects,
+            selectProject,
+            getCurrentProject: () => session?.project ?? null,
+        });
+    }
+    catch (err) {
+        if (err.code === "EADDRINUSE") {
+            // A DataLoom daemon is already on this port (e.g. the background one).
+            // That's fine — point at the running instance instead of crashing.
+            console.log(`[data-loom] already running at http://${host}:${port} — using that instance.`);
+            openBrowser(`http://${host}:${port}`);
+            session?.stopWatch(); // release the watcher started for this aborted launch
+            return;
+        }
+        throw err;
+    }
+    const url = `http://${host}:${server.port}`;
+    console.log(`[data-loom] dashboard ready at ${url}`);
     if (session)
         console.log(`[data-loom] project: ${session.project}`);
-    openBrowser(`http://${host}:${server.port}`);
+    openBrowser(url);
+    // Tray icon: an ambient "DataLoom is running" indicator (essential in the
+    // detached mode, which has no console). Guarded no-op where unavailable.
+    let tray = { dispose: () => { } };
     const shutdown = () => {
+        tray.dispose();
         session?.stopWatch();
         server?.close();
         process.exit(0);
     };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
+    tray = initTray({
+        url,
+        onOpen: () => launchBrowser(url),
+        onCopy: () => copyToClipboard(url),
+        onStop: shutdown,
+        log: (msg) => console.error(msg),
+    });
 }
 async function buildSession(project) {
     const client = new OpenSpecClient(project);
@@ -124,8 +155,14 @@ 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;
+    launchBrowser(url);
+}
+/** Open a URL in the default browser unconditionally (used by the tray). */
+function launchBrowser(url) {
     try {
         if (process.platform === "win32") {
             spawn("cmd", ["/c", "start", "", url], { stdio: "ignore", detached: true }).unref();
@@ -141,7 +178,130 @@ function openBrowser(url) {
         /* non-fatal — the URL is already logged */
     }
 }
-main().catch((err) => {
-    console.error(err);
-    process.exit(1);
-});
+/** Best-effort copy of text to the system clipboard; failure is silent. */
+function copyToClipboard(text) {
+    try {
+        const proc = process.platform === "win32"
+            ? spawn("clip")
+            : process.platform === "darwin"
+                ? spawn("pbcopy")
+                : spawn("xclip", ["-selection", "clipboard"]);
+        proc.on("error", () => { });
+        proc.stdin?.end(text);
+    }
+    catch {
+        /* no clipboard tool available — non-fatal */
+    }
+}
+// ---- 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();
+        // ...and points Claude Code at it, so the always-on path both hosts and
+        // registers the MCP endpoint. Best-effort: a missing `claude` CLI must not
+        // fail the enable (the login item + daemon already succeeded). Opt out with
+        // --no-connect.
+        if (!rest.includes("--no-connect")) {
+            try {
+                await claudeCode.connect();
+            }
+            catch (err) {
+                console.warn(`[data-loom] could not register with Claude Code (continuing): ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        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] [--no-connect]");
+}
+async function runConnect(rest) {
+    const target = rest[0];
+    if (target === "claude-code") {
+        const registered = await claudeCode.connect();
+        if (registered) {
+            console.log("[data-loom] registered DataLoom in Claude Code (user scope, native HTTP)");
+            console.log("[data-loom] start a new Claude Code session (or /mcp reconnect) to pick it up; DataLoom must be running to serve the tools.");
+        }
+        return;
+    }
+    if (target === "claude-desktop") {
+        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.");
+        return;
+    }
+    throw new Error("usage: data-loom connect <claude-code|claude-desktop [--bridge]>");
+}
+async function runDisconnect(rest) {
+    const target = rest[0];
+    if (target === "claude-code") {
+        const { removed } = await claudeCode.disconnect();
+        console.log(removed
+            ? "[data-loom] removed DataLoom from Claude Code"
+            : "[data-loom] DataLoom was not registered in Claude Code — nothing to remove");
+        return;
+    }
+    if (target === "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");
+        return;
+    }
+    throw new Error("usage: data-loom disconnect <claude-code|claude-desktop>");
+}
+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

@@ -7,9 +7,11 @@
 // server serves every project: the target project is resolved per call from an
 // explicit `project` argument, falling back to the daemon's current dashboard
 // selection. The server holds no single project frozen for its lifetime.
+import { readFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { OpenSpecClient } from "./openspecClient.js";
@@ -23,6 +25,19 @@ import { discoverProjects, isViewableProject } from "./projects.js";
  */
 class ToolError extends Error {
 }
+// The advertised server version — read from the package manifest shipped next
+// to the compiled code, so it can never drift from the released version again
+// (it was hardcoded and stuck at 0.4.1 through the 0.5.0 release).
+const VERSION = (() => {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const manifest = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+        return manifest.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
 // 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.
@@ -75,7 +90,7 @@ 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.1" }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    const server = new Server({ name: "data-loom", version: VERSION }, { 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.

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

@@ -117,6 +117,16 @@ export async function startServer(opts) {
                     sendError(res, 413, "request body too large");
                 return;
             }
+            if (e instanceof InvalidJsonError) {
+                // A body that never parsed is the caller's encoding fault — answer with
+                // a JSON-RPC parse error, not a 500. The classic trigger is a Windows
+                // path with unescaped backslashes ("D:\projects\…" — \p is not a valid
+                // JSON escape), so name that in the hint. The detail only ever echoes
+                // the parser's complaint about the caller's own body, never host state.
+                if (!res.headersSent)
+                    sendRpcParseError(res, e.message);
+                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);
@@ -174,6 +184,16 @@ export async function startServer(opts) {
         server: http,
         verifyClient: (info) => isAllowed(info.req),
     });
+    // ws re-emits the underlying server's 'error'; without a listener a bind
+    // failure (EADDRINUSE) becomes an unhandled 'error' event that crashes the
+    // process. The listen() promise below surfaces startup bind errors to the
+    // caller, so ignore those here (avoids a scary duplicate stack on the normal
+    // "already running" path); log only unexpected post-startup socket errors.
+    wss.on("error", (err) => {
+        if (err.code !== "EADDRINUSE") {
+            console.error("[data-loom] websocket error:", err);
+        }
+    });
     wss.on("connection", async (ws) => {
         const roadmap = getRoadmap();
         if (roadmap)
@@ -186,7 +206,18 @@ export async function startServer(opts) {
             /* project list optional */
         }
     });
-    await new Promise((ready) => http.listen(port, host, ready));
+    // Reject (rather than crash) if the port is taken — the caller decides how to
+    // report an already-running instance. After a clean listen, later server
+    // errors are logged, not fatal.
+    await new Promise((resolve, reject) => {
+        const onError = (err) => reject(err);
+        http.once("error", onError);
+        http.listen(port, host, () => {
+            http.removeListener("error", onError);
+            http.on("error", (err) => console.error("[data-loom] http server error:", err));
+            resolve();
+        });
+    });
     const actualPort = http.address()?.port ?? port;
     setAllowed(actualPort);
     return {
@@ -207,9 +238,29 @@ function sendError(res, code, message) {
     res.writeHead(code, { "content-type": MIME[".json"] });
     res.end(JSON.stringify({ error: message }));
 }
+/**
+ * Answer a request whose body was not valid JSON with a JSON-RPC parse error
+ * (-32700) over HTTP 400, per the Streamable-HTTP spec. `detail` is the JSON
+ * parser's message about the caller's own payload — safe to echo, and the hint
+ * names the most common cause on Windows (unescaped path backslashes).
+ */
+function sendRpcParseError(res, detail) {
+    res.writeHead(400, { "content-type": MIME[".json"] });
+    res.end(JSON.stringify({
+        jsonrpc: "2.0",
+        error: {
+            code: -32700,
+            message: `Parse error: request body is not valid JSON (${detail}). If the payload contains Windows paths, JSON-escape the backslashes ("D:\\\\projects\\\\…") or use forward slashes.`,
+        },
+        id: null,
+    }));
+}
 /** Raised when a request body exceeds the cap; mapped to HTTP 413. */
 class PayloadTooLargeError extends Error {
 }
+/** Raised when a request body is not parseable JSON; mapped to HTTP 400 / -32700. */
+class InvalidJsonError 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. */
@@ -239,7 +290,7 @@ function readJsonBody(req) {
                 resolve(JSON.parse(data));
             }
             catch (e) {
-                reject(e instanceof Error ? e : new Error("invalid JSON body"));
+                reject(new InvalidJsonError(e instanceof Error ? e.message : "invalid JSON body"));
             }
         });
         req.on("error", reject);

package/dist/tray.js

@@ -0,0 +1,142 @@
+// System-tray presence for the running daemon — a glanceable "is DataLoom
+// running?" signal for the detached/background mode that has no console or
+// window. Windows-first and dependency-free: a hidden PowerShell helper draws
+// the DataLoom mark, shows a tooltip, and offers Open / Copy / Stop; menu
+// clicks arrive back as stdout lines. Any failure (non-Windows, no PowerShell,
+// headless/session-0, DATA_LOOM_NO_TRAY) is a silent no-op, so the tray never
+// affects the daemon's ability to serve (mirror-not-launcher, DataLoom-only).
+import { spawn } from "node:child_process";
+const NOOP = { dispose: () => { } };
+/**
+ * Show a tray icon for the running daemon. Returns a disposer. Never throws:
+ * on any unsupported/headless host or failure it returns a no-op tray so the
+ * caller can wire it unconditionally.
+ */
+export function initTray(opts) {
+    if (process.env.DATA_LOOM_NO_TRAY)
+        return NOOP;
+    // Windows-first: elsewhere (and headless) we degrade to no tray.
+    if (process.platform !== "win32")
+        return NOOP;
+    try {
+        return startWindowsTray(opts);
+    }
+    catch (err) {
+        opts.log?.(`[data-loom] tray unavailable (continuing without it): ${err instanceof Error ? err.message : err}`);
+        return NOOP;
+    }
+}
+function startWindowsTray(opts) {
+    const script = buildScript(opts.url, process.pid);
+    // -EncodedCommand takes base64 of the UTF-16LE script, sidestepping all shell
+    // quoting. powershell.exe (Windows PowerShell 5.1) runs STA, which WinForms
+    // / NotifyIcon require.
+    const encoded = Buffer.from(script, "utf16le").toString("base64");
+    const child = spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden", "-ExecutionPolicy", "Bypass", "-EncodedCommand", encoded], { windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+    let disposed = false;
+    child.stdout?.setEncoding("utf8");
+    let buf = "";
+    child.stdout?.on("data", (chunk) => {
+        buf += chunk;
+        let nl;
+        while ((nl = buf.indexOf("\n")) >= 0) {
+            const line = buf.slice(0, nl).trim();
+            buf = buf.slice(nl + 1);
+            if (!line)
+                continue;
+            if (line === "open")
+                opts.onOpen();
+            else if (line === "copy")
+                opts.onCopy();
+            else if (line === "stop")
+                opts.onStop();
+        }
+    });
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+        // PowerShell serializes its progress/verbose streams to stderr as CLIXML
+        // when piped (e.g. "Preparing modules for first use") — benign noise. Only
+        // surface genuine error records.
+        if (!/S="error"/i.test(chunk))
+            return;
+        opts.log?.(`[data-loom] tray helper error: ${chunk.trim()}`);
+    });
+    child.on("error", (err) => opts.log?.(`[data-loom] tray helper error: ${err.message}`));
+    return {
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            // Intentionally not killed here: the helper polls for its parent (this
+            // daemon) and, once we exit, disposes its own NotifyIcon and quits — a
+            // clean icon removal. A hard kill would skip that and leave a ghost icon
+            // in the tray until the user hovers it. dispose() is only called during
+            // shutdown, which exits the process immediately afterward.
+            try {
+                child.stdout?.removeAllListeners();
+                child.stderr?.removeAllListeners();
+            }
+            catch {
+                /* nothing to clean up */
+            }
+        },
+    };
+}
+/**
+ * The PowerShell helper. Built as joined lines (no backticks, so it survives a
+ * JS template context) with the URL and parent PID inlined. It draws the woven
+ * DataLoom mark, shows a NotifyIcon with a tooltip and a context menu, reports
+ * menu clicks on stdout, and self-terminates (removing its icon) as soon as the
+ * parent daemon is gone.
+ */
+function buildScript(url, parentPid) {
+    const safeUrl = url.replace(/'/g, "''"); // single-quote escape for PS literal
+    return [
+        "$ErrorActionPreference = 'Stop'",
+        "$ProgressPreference = 'SilentlyContinue'",
+        "Add-Type -AssemblyName System.Windows.Forms",
+        "Add-Type -AssemblyName System.Drawing",
+        "$url = '" + safeUrl + "'",
+        "$parent = " + String(parentPid),
+        // Draw the woven-lattice mark (faint horizontals + accent-blue verticals).
+        "$bmp = New-Object System.Drawing.Bitmap 32,32",
+        "$g = [System.Drawing.Graphics]::FromImage($bmp)",
+        "$g.SmoothingMode = 'AntiAlias'",
+        "$g.Clear([System.Drawing.Color]::Transparent)",
+        "$accent = New-Object System.Drawing.Pen ([System.Drawing.Color]::FromArgb(255,37,99,184)), 2.4",
+        "$faint = New-Object System.Drawing.Pen ([System.Drawing.Color]::FromArgb(255,144,163,190)), 2.4",
+        "foreach ($y in 7,16,25) { $g.DrawLine($faint, 6, $y, 26, $y) }",
+        "foreach ($x in 8,16,24) { $g.DrawLine($accent, $x, 6, $x, 26) }",
+        "$g.Dispose()",
+        "$icon = [System.Drawing.Icon]::FromHandle($bmp.GetHicon())",
+        // Tray icon + tooltip.
+        "$notify = New-Object System.Windows.Forms.NotifyIcon",
+        "$notify.Icon = $icon",
+        "$notify.Text = 'DataLoom - running - ' + $url",
+        "$notify.Visible = $true",
+        // Context menu — DataLoom-only actions, reported to the daemon on stdout.
+        "$menu = New-Object System.Windows.Forms.ContextMenuStrip",
+        "$mOpen = $menu.Items.Add('Open Dashboard')",
+        "$mOpen.add_Click({ try { [Console]::Out.WriteLine('open'); [Console]::Out.Flush() } catch {} })",
+        "$mCopy = $menu.Items.Add('Copy URL')",
+        "$mCopy.add_Click({ try { [Console]::Out.WriteLine('copy'); [Console]::Out.Flush() } catch {} })",
+        "$mStop = $menu.Items.Add('Stop DataLoom')",
+        "$mStop.add_Click({ try { [Console]::Out.WriteLine('stop'); [Console]::Out.Flush() } catch {} })",
+        "$notify.ContextMenuStrip = $menu",
+        // Clean removal of the icon, however we exit.
+        "$cleanup = { try { $notify.Visible = $false } catch {}; try { $notify.Dispose() } catch {}; try { $icon.Dispose() } catch {}; try { $bmp.Dispose() } catch {} }",
+        // Pump WinForms messages (so the icon shows and the menu responds) while the
+        // parent daemon is alive; when it goes, remove our icon and quit. A manual
+        // DoEvents loop keeps $parent/$cleanup in the main scope, avoiding the scope
+        // pitfalls of .NET event-handler scriptblocks. The menu handlers above use
+        // only string literals, so they capture nothing.
+        "try {",
+        "  while (Get-Process -Id $parent -ErrorAction SilentlyContinue) {",
+        "    [System.Windows.Forms.Application]::DoEvents()",
+        "    Start-Sleep -Milliseconds 150",
+        "  }",
+        "} finally {",
+        "  & $cleanup",
+        "}",
+    ].join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyric_dev/data-loom",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Local dashboard for spec-driven development: a phased OpenSpec roadmap (WHAT) and an MCP topology (HOW).",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,9 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsc && node --watch dist/index.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "sync-global": "node scripts/sync-global.mjs",
+    "postpublish": "npm run sync-global"
   },
   "publishConfig": {
     "access": "public"