@lyric_dev/data-loom 0.6.0 → 0.7.0

package/README.md

@@ -17,30 +17,34 @@ npm install -g openspec
 
 (data-loom invokes your installed `openspec`; if it's missing, it exits with this guidance instead of showing a blank dashboard.)
 
-## Get it (recommended): install from npm
+## Get started (one command)
 
-Requires [Node.js](https://nodejs.org) ≥ 20.
-
-Run it directly with `npx` (no install), pointing at a project (any directory containing an `openspec/` workspace):
+Requires [Node.js](https://nodejs.org) ≥ 20. From any project (a directory with an `openspec/` workspace), a single command takes a fresh machine to a fully working, always-on DataLoom:
 
 ```
-npx @lyric_dev/data-loom "C:\path\to\your\project"
+npx @lyric_dev/data-loom up "C:\path\to\your\project"
 ```
 
-Or install it globally and run the `data-loom` command:
+`data-loom up` checks the `openspec` prerequisite up front (and stops with the install command if it's missing, before changing anything), registers login autostart, starts the background daemon, and registers DataLoom with Claude Code — then prints a summary: dashboard URL and daemon state, autostart state, Claude Code registration, and a `/loom:weave` pointer. It's safe to re-run — on an already-configured host it reports each part as already in place, so it doubles as a "check my setup" command. Pass `--no-start` (register for next login only) or `--no-connect` (skip the Claude Code registration). Then open <http://127.0.0.1:4317>.
+
+For a durable setup, install globally so autostart points at a stable location instead of an ephemeral npx cache (`up` reminds you of this when run via npx):
 
 ```
 npm install -g @lyric_dev/data-loom
-data-loom "C:\path\to\your\project"
+data-loom up "C:\path\to\your\project"
 ```
 
-With no argument it uses the current directory. Then open <http://127.0.0.1:4317>.
+**Just want a quick look?** Run it in the foreground with no setup — it stops when you close the terminal (with no argument it uses the current directory):
+
+```
+npx @lyric_dev/data-loom "C:\path\to\your\project"
+```
 
 > Published to npm automatically by CI on version tags (`vX.Y.Z`) via GitHub Actions.
 
-## Run it always-on (background + autostart)
+## Run it always-on (manual controls)
 
-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 up` (above) sets all of this up in one shot; the commands here are the individual controls it composes, for when you want to manage the pieces directly. 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
@@ -51,7 +55,7 @@ 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:
+To have it launch automatically when you log in — and restart itself if it ever crashes:
 
 ```
 data-loom autostart enable    # register a per-user login item AND start it now
@@ -59,7 +63,17 @@ 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.
+`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, and it **supervises** the daemon so a crash restarts it automatically (a deliberate `data-loom stop` stays stopped) — a per-user Scheduled Task on Windows, a LaunchAgent with `KeepAlive` on macOS, a systemd user unit with `Restart=on-failure` on Linux. `data-loom status` reports which mechanism is registered and whether it's supervised. If the supervising mechanism can't be created on your host (e.g. Task Scheduler unavailable, no systemd user session), `enable` falls back to a plain login-item shortcut and tells you supervision isn't available — autostart still works, it just won't self-heal from a crash.
+
+**Upgrading from an earlier version?** Re-running `data-loom autostart enable` migrates an existing plain login item to the supervised form automatically — no separate migration step. Or use the single command below, which upgrades and re-registers in one step:
+
+```
+data-loom update   # upgrade the global install, restart a running daemon, refresh autostart
+```
+
+`update` upgrades the globally-installed package, restarts the daemon if one is running, and rewrites the autostart registration (including migrating to the supervised form) if autostart is enabled — reporting each step. It only works for a global npm install; if you run DataLoom via `npx`, it tells you so instead of guessing.
 
 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.
 
@@ -91,7 +105,7 @@ The running daemon also **hosts an MCP server** over HTTP, so your own Claude se
    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:
+   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) **and** provisions the `/loom:weave` command (see step 3) — one command, one reload, both the tools and `/loom:weave` are available. Remove both 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
@@ -101,6 +115,14 @@ The running daemon also **hosts an MCP server** over HTTP, so your own Claude se
 
    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.
 
+   **Prefer not to think about starting DataLoom at all?** Register the on-demand form instead:
+
+   ```
+   data-loom connect claude-code --on-demand
+   ```
+
+   This registers a stdio server that runs `data-loom mcp-shim` instead of pointing at the HTTP endpoint directly. Claude Code spawns that shim per session; it starts the daemon itself (through the same detached path as `data-loom start`) if it isn't already running, waits for it to come up, then transparently forwards MCP traffic to it — the shim adds no tools of its own, it just gets the real daemon running. Pick this when you don't run `autostart enable` and don't want to remember to `data-loom start` first; keep the default HTTP form when you're already running the dashboard always-on, since it's one less process per session. Only one form is ever registered — switching re-runs the same command with `--on-demand` (or without it, to switch back), and it reports the switch. `data-loom disconnect claude-code` removes whichever form is present.
+
    **Claude Desktop** reaches the same daemon — register it with:
 
    ```
@@ -114,11 +136,11 @@ The running daemon also **hosts an MCP server** over HTTP, so your own Claude se
    - `list_open_proposals(project?)` — the open changes with their proposal text, current phase/readiness, and dependency-review state (read-only; proposal text only, no secrets).
    - `set_dependency(from, to, project?)` — writes a `## Depends On` entry into a proposal.
    - `mark_independent(change, project?)` — records that a proposal genuinely depends on nothing, by writing an empty `## Depends On` block.
-   - `install_weave_skill` — installs the `/loom:weave` shortcut command (one-time setup, see below).
+   - `install_weave_skill` — fallback installer for the `/loom:weave` command (see below); unnecessary if you registered with `connect claude-code`, which already provisions it.
 
    Each write is an explicit, reviewable `## Depends On` edit; the roadmap then recomputes deterministically. Proposals that still need a dependency decision are flagged in the roadmap with a **"needs review"** badge, and DataLoom appears as a server in its own MCP Topology tab once registered.
 
-3. **One command for it all: `/loom:weave`.** Ask Claude to *"install the weave skill"* (it calls `install_weave_skill`). That writes a `/loom:weave` slash command into your global Claude config (`~/.claude/commands/loom/weave.md`); reload Claude Code, and from then on `/loom:weave` runs the whole review — list, propose, confirm, apply — in any project, passing that project explicitly. (It needs the daemon running; if the tools aren't reachable it tells you to start DataLoom.)
+3. **One command for it all: `/loom:weave`.** The whole review workflow — list, propose, confirm, apply — is served by the daemon itself as an MCP prompt named `weave`, so it always matches the running version. `data-loom connect claude-code` provisions a thin `/loom:weave` alias for it automatically (no separate install step); from then on, `/loom:weave` in any project fetches and runs the workflow, passing that project explicitly. If you registered another way, ask Claude to *"install the weave skill"* (it calls `install_weave_skill`) to add the alias yourself, then reload. (The alias needs the daemon running and registered; if unreachable it tells you to run `data-loom status` / `data-loom start` / `data-loom connect claude-code`.) Other MCP clients that support the prompts capability — e.g. Claude Desktop's prompt picker — can invoke the `weave` prompt directly, with no alias needed.
 
 > **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.
 

package/dist/autostart.js

@@ -1,22 +1,85 @@
 // 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`.
+// user logs in, using the native, no-elevation, per-user SUPERVISING
+// mechanism for each OS —
+//   Windows  a Scheduled Task (logon trigger, restart-on-failure)
+//   macOS    a LaunchAgent plist with RunAtLoad + KeepAlive (crash-only)
+//   Linux    a systemd user unit with Restart=on-failure
+// Each of these executes the daemon directly (via the stable launcher below)
+// in the FOREGROUND, so the supervisor tracks the daemon's own exit code and
+// can restart it on crash — a launcher that detaches and returns (like `data-
+// loom start`) would leave the supervisor watching nothing. When a platform's
+// supervising mechanism can't be created or isn't available, registration
+// falls back to the legacy, unsupervised form (Startup-folder shortcut /
+// XDG autostart), which still launches the daemon via the normal detached
+// `start` path. `enable()` migrates a legacy registration to the supervised
+// form when possible; `disable()` removes both generations.
 import { spawn } from "node:child_process";
-import { writeFile, rm, access, mkdir } from "node:fs/promises";
+import { writeFile, rm, access, mkdir, chmod, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { launcherFile, logFile, ensureStateDir } from "./paths.js";
 const NODE = process.execPath;
 const SCRIPT = process.argv[1];
 const LABEL = "dev.lyric.data-loom";
+const WIN_TASK_NAME = "DataLoom";
+const SYSTEMD_UNIT_NAME = "data-loom.service";
 function exists(p) {
     return access(p).then(() => true, () => false);
 }
-// ---- Windows: Startup-folder shortcut -------------------------------------
+/** Run a command, ignoring its outcome — used for best-effort teardown/reload steps. */
+function runBestEffort(cmd, args) {
+    return new Promise((resolve) => {
+        const p = spawn(cmd, args, { windowsHide: true, stdio: "ignore" });
+        p.on("error", () => resolve());
+        p.on("exit", () => resolve());
+    });
+}
+/** Run a command and resolve true iff it exits 0 — used for existence/availability probes. */
+function probe(cmd, args, timeout) {
+    return new Promise((resolve) => {
+        const p = spawn(cmd, args, { windowsHide: true, stdio: "ignore", timeout });
+        p.on("error", () => resolve(false));
+        p.on("exit", (code) => resolve(code === 0));
+    });
+}
+/**
+ * Write the stable launcher that OS supervisors invoke. It resolves
+ * `data-loom` from PATH at launch time, falling back to the node/script paths
+ * recorded when this was written, so a Node version-manager switch or an npm
+ * package relocation doesn't break the registration. It runs the daemon in
+ * the FOREGROUND with `DATA_LOOM_DETACHED=1` (no browser, daemon writes its
+ * own PID, output appended to the background log) and never backgrounds
+ * itself — the supervisor must see the daemon's own exit code.
+ */
+export async function writeLauncher() {
+    await ensureStateDir();
+    const path = launcherFile();
+    const log = logFile();
+    if (process.platform === "win32") {
+        const script = "@echo off\r\n" +
+            "set DATA_LOOM_DETACHED=1\r\n" +
+            "where data-loom >nul 2>nul\r\n" +
+            "if %ERRORLEVEL%==0 (\r\n" +
+            `  data-loom >> "${log}" 2>&1\r\n` +
+            ") else (\r\n" +
+            `  "${NODE}" "${SCRIPT}" >> "${log}" 2>&1\r\n` +
+            ")\r\n";
+        await writeFile(path, script, "utf8");
+    }
+    else {
+        const script = "#!/bin/sh\n" +
+            "export DATA_LOOM_DETACHED=1\n" +
+            "if command -v data-loom >/dev/null 2>&1; then\n" +
+            `  exec data-loom >> "${log}" 2>&1\n` +
+            "else\n" +
+            `  exec "${NODE}" "${SCRIPT}" >> "${log}" 2>&1\n` +
+            "fi\n";
+        await writeFile(path, script, "utf8");
+        await chmod(path, 0o755);
+    }
+    return path;
+}
+// ---- Windows: Scheduled Task (supervised) / Startup-folder shortcut (legacy) ----
 function winStartupLnk() {
     const appData = process.env.APPDATA ?? join(homedir(), "AppData", "Roaming");
     return join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup", "data-loom.lnk");
@@ -28,29 +91,67 @@ function runPowerShell(script) {
         ps.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`powershell exited ${code}`))));
     });
 }
-async function winEnable() {
+async function winScheduledTaskExists() {
+    return probe("schtasks", ["/Query", "/TN", WIN_TASK_NAME]);
+}
+async function winRegisterScheduledTask() {
+    const launcher = await writeLauncher();
+    const q = (s) => `'${s.replace(/'/g, "''")}'`;
+    const script = [
+        `$action = New-ScheduledTaskAction -Execute 'cmd.exe' -Argument ('/c "' + ${q(launcher)} + '"')`,
+        "$trigger = New-ScheduledTaskTrigger -AtLogOn",
+        "$settings = New-ScheduledTaskSettingsSet -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1) -MultipleInstances IgnoreNew -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries",
+        `Register-ScheduledTask -TaskName ${q(WIN_TASK_NAME)} -Action $action -Trigger $trigger -Settings $settings -RunLevel Limited -Force | Out-Null`,
+    ].join("; ");
+    await runPowerShell(script);
+}
+/** Legacy, unsupervised registration — a plain Startup-folder shortcut running the normal detached `start`. */
+async function winEnableLegacyShortcut() {
     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.Arguments = " + q(`"${SCRIPT}" start`),
         "$s.WindowStyle = 7",
         "$s.Description = 'DataLoom background daemon'",
         "$s.Save()",
     ].join("; "));
 }
+async function winEnable() {
+    try {
+        await winRegisterScheduledTask();
+        // Migrate away from any legacy shortcut now that the supervised form exists.
+        await rm(winStartupLnk(), { force: true }).catch(() => { });
+        // The Scheduled Task fires on the next logon, not now — the caller still
+        // needs to start the daemon for this session.
+        return { mechanism: "scheduled-task", supervised: true, startedNow: false };
+    }
+    catch {
+        // Scheduled Task creation failed (e.g. Task Scheduler service unavailable) —
+        // fall back to the legacy shortcut so autostart still works, just unsupervised.
+        await winEnableLegacyShortcut();
+        return { mechanism: "startup-shortcut", supervised: false, startedNow: false };
+    }
+}
 async function winDisable() {
+    await runBestEffort("schtasks", ["/Delete", "/TN", WIN_TASK_NAME, "/F"]);
     await rm(winStartupLnk(), { force: true }).catch(() => { });
 }
-// ---- macOS: LaunchAgent ----------------------------------------------------
+async function winGetRegistrationInfo() {
+    if (await winScheduledTaskExists())
+        return { enabled: true, mechanism: "scheduled-task", supervised: true };
+    if (await exists(winStartupLnk()))
+        return { enabled: true, mechanism: "startup-shortcut", supervised: false };
+    return { enabled: false, mechanism: "none", supervised: false };
+}
+// ---- macOS: LaunchAgent (KeepAlive = supervised) ---------------------------
 function macPlistPath() {
     return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
 }
 async function macEnable() {
+    const launcher = await writeLauncher();
     const path = macPlistPath();
     await mkdir(dirname(path), { recursive: true });
     const plist = `<?xml version="1.0" encoding="UTF-8"?>
@@ -60,38 +161,87 @@ async function macEnable() {
   <key>Label</key><string>${LABEL}</string>
   <key>ProgramArguments</key>
   <array>
-    <string>${NODE}</string>
-    <string>${SCRIPT}</string>
-    <string>start</string>
+    <string>/bin/sh</string>
+    <string>${launcher}</string>
   </array>
   <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key><false/>
+  </dict>
 </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());
-    });
+    // Unload first (best-effort) so a rewritten KeepAlive setting actually takes
+    // effect if the agent was already loaded from a prior (pre-supervision) version.
+    await runBestEffort("launchctl", ["unload", "-w", path]);
+    await runBestEffort("launchctl", ["load", "-w", path]);
+    // `load -w` with RunAtLoad launches the daemon now, so it's already up this
+    // session — the caller must not spawn a second instance that races it.
+    return { mechanism: "launch-agent", supervised: true, startedNow: true };
 }
 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 runBestEffort("launchctl", ["unload", "-w", path]);
     }
     await rm(path, { force: true }).catch(() => { });
 }
-// ---- Linux: XDG autostart --------------------------------------------------
+async function macGetRegistrationInfo() {
+    const path = macPlistPath();
+    if (!(await exists(path)))
+        return { enabled: false, mechanism: "none", supervised: false };
+    const content = await readFile(path, "utf8").catch(() => "");
+    return { enabled: true, mechanism: "launch-agent", supervised: content.includes("KeepAlive") };
+}
+// ---- Linux: systemd user unit (supervised) / XDG autostart (legacy) -------
 function linuxDesktopPath() {
     const cfg = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
     return join(cfg, "autostart", "data-loom.desktop");
 }
-async function linuxEnable() {
+function systemdUnitDir() {
+    return join(homedir(), ".config", "systemd", "user");
+}
+function systemdUnitPath() {
+    return join(systemdUnitDir(), SYSTEMD_UNIT_NAME);
+}
+async function systemdUnitFileExists() {
+    return exists(systemdUnitPath());
+}
+/** Probe whether `systemctl --user` is usable (systemd present, user session/bus reachable). */
+async function hasSystemdUserAvailable() {
+    return probe("systemctl", ["--user", "list-units", "--no-legend"], 3000);
+}
+/** True iff the supervised systemd unit is currently active — used by `stop` to avoid a raw SIGTERM racing systemd's own bookkeeping. */
+export async function isSystemdUnitActive() {
+    if (process.platform !== "linux")
+        return false;
+    return probe("systemctl", ["--user", "is-active", "--quiet", SYSTEMD_UNIT_NAME]);
+}
+/** Stop the daemon through systemd rather than a raw signal, so the unit's state reflects an intentional stop. */
+export async function stopSystemdUnit() {
+    await runBestEffort("systemctl", ["--user", "stop", SYSTEMD_UNIT_NAME]);
+}
+async function linuxSystemdEnable() {
+    const launcher = await writeLauncher();
+    await mkdir(systemdUnitDir(), { recursive: true });
+    const unit = "[Unit]\n" +
+        "Description=DataLoom background daemon\n" +
+        "\n" +
+        "[Service]\n" +
+        "Type=simple\n" +
+        `ExecStart=${launcher}\n` +
+        "Restart=on-failure\n" +
+        "\n" +
+        "[Install]\n" +
+        "WantedBy=default.target\n";
+    await writeFile(systemdUnitPath(), unit, "utf8");
+    await runBestEffort("systemctl", ["--user", "daemon-reload"]);
+    await runBestEffort("systemctl", ["--user", "enable", "--now", SYSTEMD_UNIT_NAME]);
+}
+/** Legacy, unsupervised registration — an XDG autostart entry running the normal detached `start`. */
+async function linuxEnableXdg() {
     await mkdir(dirname(linuxDesktopPath()), { recursive: true });
     const entry = `[Desktop Entry]
 Type=Application
@@ -102,14 +252,47 @@ X-GNOME-Autostart-enabled=true
 `;
     await writeFile(linuxDesktopPath(), entry, "utf8");
 }
+async function linuxEnable() {
+    if (await hasSystemdUserAvailable()) {
+        await linuxSystemdEnable();
+        // Migrate away from any legacy XDG entry now that the supervised form exists.
+        await rm(linuxDesktopPath(), { force: true }).catch(() => { });
+        // `enable --now` starts the unit immediately, so the daemon is already up
+        // this session — the caller must not spawn a second instance that races it.
+        return { mechanism: "systemd-unit", supervised: true, startedNow: true };
+    }
+    // No systemd user session available — fall back to XDG autostart, unsupervised.
+    // XDG entries only fire on the next login, so the caller still starts the
+    // daemon for this session.
+    await linuxEnableXdg();
+    return { mechanism: "xdg-autostart", supervised: false, startedNow: false };
+}
 async function linuxDisable() {
+    if (await systemdUnitFileExists()) {
+        await runBestEffort("systemctl", ["--user", "disable", "--now", SYSTEMD_UNIT_NAME]);
+        await rm(systemdUnitPath(), { force: true }).catch(() => { });
+        await runBestEffort("systemctl", ["--user", "daemon-reload"]);
+    }
     await rm(linuxDesktopPath(), { force: true }).catch(() => { });
 }
+async function linuxGetRegistrationInfo() {
+    if (await systemdUnitFileExists())
+        return { enabled: true, mechanism: "systemd-unit", supervised: true };
+    if (await exists(linuxDesktopPath()))
+        return { enabled: true, mechanism: "xdg-autostart", supervised: false };
+    return { enabled: false, mechanism: "none", supervised: false };
+}
 // ---- 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). */
+/**
+ * Register the daemon to launch at login (idempotent — overwrites any prior).
+ * Prefers the OS's supervising mechanism so a crashed daemon restarts
+ * automatically; falls back to the legacy, unsupervised form when the
+ * supervising mechanism can't be created. Migrates away from a legacy
+ * registration when the supervised form succeeds.
+ */
 export async function enable() {
     if (process.platform === "win32")
         return winEnable();
@@ -119,7 +302,7 @@ export async function enable() {
         return linuxEnable();
     unsupported();
 }
-/** Remove the login registration (idempotent — succeeds when not enabled). */
+/** Remove the login registration — both the supervised and any legacy form (idempotent). */
 export async function disable() {
     if (process.platform === "win32")
         return winDisable();
@@ -129,13 +312,17 @@ export async function disable() {
         return linuxDisable();
     unsupported();
 }
-/** True iff a login registration currently exists for this user. */
+/** True iff a login registration currently exists for this user, of either generation. */
 export async function isEnabled() {
+    return (await getRegistrationInfo()).enabled;
+}
+/** Full registration state: whether one exists, which mechanism, and whether it's supervised. */
+export async function getRegistrationInfo() {
     if (process.platform === "win32")
-        return exists(winStartupLnk());
+        return winGetRegistrationInfo();
     if (process.platform === "darwin")
-        return exists(macPlistPath());
+        return macGetRegistrationInfo();
     if (process.platform === "linux")
-        return exists(linuxDesktopPath());
-    return false;
+        return linuxGetRegistrationInfo();
+    return { enabled: false, mechanism: "none", supervised: false };
 }

package/dist/claudeCode.js

@@ -12,15 +12,24 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { mcpUrl } from "./paths.js";
+import { provisionWeaveAlias, removeWeaveAliasIfOurs } from "./weaveAlias.js";
+import { VERSION } from "./version.js";
 const execFileP = promisify(execFile);
 const KEY = "data-loom";
+// The on-demand form registers this PATH command (never node+script — same
+// stable-launcher reasoning as autostart's supervised launcher), which starts
+// the daemon if needed and proxies to it for the session (see mcpShim.ts).
+const SHIM_COMMAND = "data-loom";
+const SHIM_ARGS = ["mcp-shim"];
 /** 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()}`;
+export function manualCommand(onDemand = false) {
+    return onDemand
+        ? `claude mcp add --scope user ${KEY} -- ${SHIM_COMMAND} ${SHIM_ARGS.join(" ")}`
+        : `claude mcp add --transport http --scope user ${KEY} ${mcpUrl()}`;
 }
 /** True iff the `claude` CLI is invocable (resolves its version). */
 async function claudeAvailable() {
@@ -32,6 +41,25 @@ async function claudeAvailable() {
         return false;
     }
 }
+/**
+ * The form of the current `data-loom` registration, or undefined when there is
+ * none (or it can't be determined). Parsed from `claude mcp get`'s human-
+ * readable output, so this is best-effort — used only to report a form switch
+ * to the user, never to decide correctness (removeRegistration + add below
+ * guarantees a single entry regardless).
+ */
+async function currentForm() {
+    try {
+        const { stdout } = await runClaude(["mcp", "get", KEY]);
+        const m = /^\s*Type:\s*(\S+)/im.exec(stdout);
+        if (!m)
+            return undefined;
+        return m[1].toLowerCase() === "stdio" ? "stdio" : "http";
+    }
+    catch {
+        return undefined; // not registered, or `claude mcp get` itself failed
+    }
+}
 /** Remove any existing user-scope registration; tolerates "not registered". */
 async function removeRegistration() {
     try {
@@ -42,26 +70,55 @@ async function removeRegistration() {
     }
 }
 /**
- * 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.
+ * Register DataLoom with Claude Code at user scope: by default the daemon's
+ * loopback HTTP MCP endpoint, or — with `onDemand` — the stdio shim that
+ * starts the daemon itself when needed. Idempotent upsert: remove any prior
+ * entry (of either form), then add, so exactly one current entry remains;
+ * when a registration of the other form existed, `switchedFrom` reports it.
+ * Returns `registered: false` (with printed guidance) when the `claude` CLI is
+ * unavailable, so callers can degrade gracefully instead of failing.
+ *
+ * Also provisions the `/loom:weave` alias, best-effort: a failure to write it
+ * warns but does not fail the connect, since the MCP registration is the
+ * primary outcome.
  */
-export async function connect() {
+export async function connect(opts = {}) {
+    const onDemand = opts.onDemand ?? false;
     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;
+            `[data-loom] register it by hand once with:\n    ${manualCommand(onDemand)}`);
+        return { registered: false };
     }
+    const existingForm = await currentForm();
     await removeRegistration();
-    await runClaude(["mcp", "add", "--transport", "http", "--scope", "user", KEY, mcpUrl()]);
-    return true;
+    if (onDemand) {
+        await runClaude(["mcp", "add", "--scope", "user", KEY, "--", SHIM_COMMAND, ...SHIM_ARGS]);
+    }
+    else {
+        await runClaude(["mcp", "add", "--transport", "http", "--scope", "user", KEY, mcpUrl()]);
+    }
+    try {
+        await provisionWeaveAlias(VERSION);
+    }
+    catch (err) {
+        console.warn(`[data-loom] could not write the /loom:weave command (continuing): ${err instanceof Error ? err.message : err}`);
+    }
+    const requestedForm = onDemand ? "stdio" : "http";
+    return {
+        registered: true,
+        switchedFrom: existingForm && existingForm !== requestedForm ? existingForm : undefined,
+    };
 }
 /**
- * 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).
+ * Remove DataLoom's user-scope registration from Claude Code, whichever form
+ * (HTTP or on-demand stdio) is present — `claude mcp remove` deletes the entry
+ * by name only, so this is form-agnostic already. Idempotent — reports whether
+ * anything was actually registered. Throws only if the `claude` CLI itself is
+ * unavailable (nothing could have been registered without it).
+ *
+ * Also removes the `/loom:weave` alias, but only when its version stamp
+ * identifies it as ours — a file we don't recognize is left untouched. This is
+ * best-effort like the alias write in connect().
  */
 export async function disconnect() {
     if (!(await claudeAvailable())) {
@@ -77,5 +134,11 @@ export async function disconnect() {
         existed = false;
     }
     await removeRegistration();
+    try {
+        await removeWeaveAliasIfOurs();
+    }
+    catch (err) {
+        console.warn(`[data-loom] could not remove the /loom:weave command (continuing): ${err instanceof Error ? err.message : err}`);
+    }
     return { removed: existed };
 }