@aexol/spectral 0.9.234 → 0.9.241

package/dist/commands/update.js

@@ -2,24 +2,58 @@
  * `spectral update` — standalone binary self-update.
  *
  * Fetches the latest release manifest from api.aexol.ai, compares versions,
- * downloads the new binary, verifies its SHA256 checksum, and atomically
- * replaces the running binary on disk.
+ * downloads the new artifacts, verifies their SHA256 digests, and installs them
+ * over the current installation.
  *
- * Non-standalone install modes (Electron desktop app, npm global) are detected
- * and the user is pointed at the correct update path instead.
+ * Two manifest shapes are supported:
+ *
+ *   - binary only (every manifest ever published): `url` + `sha256` pin the
+ *     single-file binary. Only the binary is replaced — the companion assets an
+ *     `install.sh` user has next to it (`data/systems/`, `mcp/`,
+ *     `app-bridge.bundle.js`) keep the previous version, which is called out
+ *     with a warning telling the user to re-run `curl | sh`.
+ *   - release zip (ADDITIVE `zipUrl` + `zipSha256`, emitted by
+ *     cli-node/scripts/generate-cli-manifest.sh once scripts/package-standalone.sh
+ *     produced the archive): the zip carries the binary *and* the
+ *     `<platform>-data/` companion directory. Both are installed with the same
+ *     replace-don't-merge semantics as scripts/install.sh, so files deleted
+ *     between releases do not linger.
+ *
+ * Nothing is installed unverified: the zip digest is checked before unpacking,
+ * the inner binary digest before swapping, and any mismatch aborts without
+ * touching the current installation.
+ *
+ * Non-standalone install modes (npm global install) are detected and the user
+ * is pointed at the correct update path instead.
  */
+import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { chmod, mkdtemp, rename, rm, stat, writeFile, } from "node:fs/promises";
+import { chmod, cp, mkdir, mkdtemp, readdir, rename, rm, stat, writeFile, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import pc from "picocolors";
 import { getVersion } from "../version.js";
+import { isStandaloneBinary } from "../utils/standalone.js";
 /** Base URL for the Aexol release manifest / binary downloads. */
 const RELEASE_BASE = "https://api.aexol.ai/api/releases/download";
+/** Stable entry point of the curl|sh installer (quoted in warnings). */
+const INSTALLER_URL = "https://api.aexol.ai/api/releases/download/latest/install.sh";
+/** Default `run`: a real spawn, stdio detached from the CLI's own output. */
+const defaultRun = (cmd, args) => new Promise((resolveRun, rejectRun) => {
+    const child = spawn(cmd, args, { stdio: "ignore" });
+    child.on("error", rejectRun);
+    child.on("close", (code) => resolveRun(code ?? -1));
+});
+/** Companion directories install.sh places next to the binary. */
+const COMPANION_DIRS = ["data", "mcp"];
+/** Companion files install.sh places next to the binary. */
+const COMPANION_FILES = ["app-bridge.bundle.js"];
+/** Version stamp read by scripts/install.sh to skip a redundant reinstall. */
+const VERSION_STAMP = ".spectral-version";
 /**
  * Resolve the current CLI version via the centralized getVersion() helper
- * (src/version.ts), which works for npm install, standalone Bun binaries, and
- * the Electron app — all of which previously fell back to "0.0.0".
+ * (src/version.ts), which works for npm install and standalone Bun binaries —
+ * both of which previously fell back to "0.0.0".
  */
 function currentVersion() {
     return getVersion();
@@ -59,28 +93,6 @@ function detectPlatform() {
         return "win-x64";
     return null;
 }
-/**
- * Whether the process is running as a Bun `--compile` standalone binary.
- *
- * In a compiled binary, `process.execPath` points at the binary itself (e.g.
- * `spectral`) rather than a `node`/`bun` runtime, and Bun's embedded-files
- * surface may be present.
- */
-function isStandaloneBinary() {
-    // Bun-compiled binary with embedded files is a strong positive signal.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const Bun = globalThis.Bun;
-    if (Bun && typeof Bun === "object" && "embeddedFiles" in Bun) {
-        return true;
-    }
-    const execName = basename(process.execPath).replace(/\.exe$/i, "");
-    const isRuntime = execName === "node" || execName === "bun";
-    return !isRuntime;
-}
-/** True when invoked inside the Electron desktop app. */
-function isElectronBundled() {
-    return Boolean(process.env.SPECTRAL_DESKTOP_VERSION);
-}
 /**
  * Compute the SHA256 hex digest of a file's contents.
  */
@@ -133,6 +145,139 @@ async function fetchManifest(platform) {
     const data = (await res.json());
     return data;
 }
+/**
+ * Unpack `zipPath` into a fresh sub-directory of `tempDir` using the first
+ * archive tool that is both present and successful:
+ *
+ *   1. `unzip`  — the normal case (macOS, most Linux distros, Git Bash);
+ *   2. `tar -xf`— works where tar is bsdtar (macOS, Windows' built-in tar) and
+ *      merely exits non-zero where tar is GNU tar (which has no zip support).
+ *
+ * `node:zlib` is deliberately not used: it decodes gzip, not the zip container.
+ */
+async function unpackReleaseZip(params) {
+    const { zipPath, tempDir, run } = params;
+    const destDir = join(tempDir, "unpacked");
+    await mkdir(destDir, { recursive: true });
+    const attempts = [
+        { cmd: "unzip", args: ["-q", "-o", zipPath, "-d", destDir] },
+        { cmd: "tar", args: ["-xf", zipPath, "-C", destDir] },
+    ];
+    const notes = [];
+    for (const attempt of attempts) {
+        try {
+            const code = await run(attempt.cmd, attempt.args);
+            if (code === 0)
+                return { ok: true, destDir, notes: [...notes, `${attempt.cmd} ok`] };
+            notes.push(`${attempt.cmd} exited with code ${code}`);
+        }
+        catch (runErr) {
+            const msg = runErr instanceof Error ? runErr.message : String(runErr);
+            notes.push(`${attempt.cmd} unavailable (${msg})`);
+        }
+    }
+    return { ok: false, notes };
+}
+/**
+ * Locate the `<platform>-data/` companion directory at the root of an unpacked
+ * release zip (the layout defined by scripts/package-standalone.sh).
+ */
+async function findDataDir(stageDir) {
+    const entries = await readdir(stageDir, { withFileTypes: true });
+    const hit = entries.find((e) => e.isDirectory() && e.name.endsWith("-data"));
+    return hit ? join(stageDir, hit.name) : null;
+}
+/**
+ * Pick the binary out of an unpacked release zip. The archive ships it as
+ * `spectral` / `spectral.exe` (scripts/package-standalone.sh renames it), while
+ * a user may have renamed their own install — so the live name is tried first,
+ * then the canonical ones.
+ */
+async function findStagedBinary(stageDir, liveName) {
+    const candidates = [liveName, "spectral", "spectral.exe"];
+    for (const name of candidates) {
+        if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\\")) {
+            continue;
+        }
+        const candidate = join(stageDir, name);
+        try {
+            const st = await stat(candidate);
+            if (st.isFile())
+                return candidate;
+        }
+        catch {
+            // not there — try the next candidate name
+        }
+    }
+    return null;
+}
+/**
+ * Replace the companion assets next to the binary with the ones from the zip.
+ *
+ * Semantics are those of scripts/install.sh: the `<platform>-data/` directory is
+ * placed next to the binary and *then* its contents are copied alongside it,
+ * with the previous `data/`, `mcp/` and `app-bridge.bundle.js` removed first —
+ * replace, not merge, so files deleted between releases do not linger.
+ *
+ * SAFETY: `installDir` is `dirname(process.execPath)` — the directory that
+ * *holds* the running binary. Only the explicitly named companion paths inside
+ * it are ever removed, and only for a real absolute path, so a bad `execPath`
+ * can never wipe a directory that contains the binary.
+ */
+export async function swapCompanionAssets(params) {
+    const { stageDir, installDir } = params;
+    if (!installDir || !installDir.startsWith("/") || installDir === "/") {
+        return { dataDirName: null, replaced: [] };
+    }
+    const srcDataDir = await findDataDir(stageDir);
+    if (!srcDataDir)
+        return { dataDirName: null, replaced: [] };
+    const dataDirName = basename(srcDataDir);
+    if (!dataDirName || dataDirName === "." || dataDirName === "..") {
+        return { dataDirName: null, replaced: [] };
+    }
+    // Drop the previous version's data directory, then stage the new one next to
+    // the binary. `cp` rather than `rename`: the temp dir may live on a different
+    // filesystem than ~/.spectral/bin, which would make a rename fail with EXDEV.
+    const destDataDir = join(installDir, dataDirName);
+    await rm(destDataDir, { recursive: true, force: true });
+    await cp(srcDataDir, destDataDir, { recursive: true, force: true });
+    // Remove the stale companion assets *before* copying the new ones.
+    for (const name of COMPANION_DIRS) {
+        await rm(join(installDir, name), { recursive: true, force: true });
+    }
+    for (const name of COMPANION_FILES) {
+        await rm(join(installDir, name), { force: true });
+    }
+    // Copy the new companion contents next to the binary: the compiled binary
+    // resolves data/systems and app-bridge.bundle.js relative to execPath.
+    const replaced = [];
+    for (const entry of await readdir(destDataDir, { withFileTypes: true })) {
+        await cp(join(destDataDir, entry.name), join(installDir, entry.name), {
+            recursive: true,
+            force: true,
+        });
+        replaced.push(entry.name);
+    }
+    return { dataDirName, replaced };
+}
+/**
+ * Record the installed version so install.sh can skip a redundant reinstall.
+ * Only written when the companion assets moved together with the binary.
+ */
+async function writeVersionStamp(installDir, version) {
+    await writeFile(join(installDir, VERSION_STAMP), `${version}\n`);
+}
+/**
+ * Drop the version stamp: only the binary was updated, so the installation as a
+ * whole no longer matches the stamped version — re-running `curl | sh` must
+ * then refresh the companion assets instead of reporting "already installed".
+ */
+async function clearVersionStamp(installDir) {
+    if (!installDir || installDir === "/")
+        return;
+    await rm(join(installDir, VERSION_STAMP), { force: true });
+}
 /**
  * Atomically replace the running binary at `currentPath` with `newBinaryPath`.
  *
@@ -140,7 +285,7 @@ async function fetchManifest(platform) {
  * place, and makes it executable. On Windows the running executable cannot be
  * renamed while live, so we print an actionable message instead.
  */
-async function atomicReplace(currentPath, newBinaryPath) {
+async function atomicReplace(currentPath, newBinaryPath, out = (t) => process.stdout.write(t)) {
     const isWindows = process.platform === "win32";
     const dir = dirname(currentPath);
     if (isWindows) {
@@ -149,7 +294,7 @@ async function atomicReplace(currentPath, newBinaryPath) {
         // user to restart. A launcher / wrapper script would handle the swap.
         const staged = join(dir, basename(currentPath) + ".new");
         await rename(newBinaryPath, staged);
-        process.stdout.write(pc.yellow(`New binary staged at ${staged}\n` +
+        out(pc.yellow(`New binary staged at ${staged}\n` +
             `Close all spectral processes, then replace the .exe manually,\n` +
             `or run the provided update helper.\n`));
         return;
@@ -199,76 +344,161 @@ async function atomicReplace(currentPath, newBinaryPath) {
  * Run the `spectral update` subcommand.
  *
  * @param args remaining CLI args after the `update` subcommand
+ * @param deps injectable I/O for tests (network, spawns, exec path, version)
  */
-export async function runUpdate(args) {
+export async function runUpdate(args, deps = {}) {
     const checkOnly = args.includes("--check") || args.includes("-c");
+    const out = deps.out ?? ((t) => process.stdout.write(t));
+    const err = deps.err ?? ((t) => process.stderr.write(t));
+    const getManifest = deps.fetchManifest ?? fetchManifest;
+    const download = deps.download ?? downloadToFile;
+    const run = deps.run ?? defaultRun;
+    const standalone = deps.standalone ?? isStandaloneBinary();
+    const execPath = deps.execPath ?? process.execPath;
     // --- Installation mode detection --------------------------------------
-    if (isElectronBundled()) {
-        process.stdout.write(pc.cyan("You're running Spectral inside the desktop app. Use the app menu → " +
-            "Check for Updates to update.\n"));
-        return;
-    }
-    if (!isStandaloneBinary()) {
-        process.stdout.write(pc.cyan("Run `npm i -g @aexol/spectral@latest` to update.\n"));
+    if (!standalone) {
+        out(pc.cyan("Run `npm i -g @aexol/spectral@latest` to update.\n"));
         return;
     }
     // --- Standalone self-update flow --------------------------------------
-    const platform = detectPlatform();
+    const platform = deps.platform !== undefined ? deps.platform : detectPlatform();
     if (!platform) {
-        process.stderr.write(pc.red(`Update is not supported on this platform (${process.platform}/${process.arch}).\n`));
+        err(pc.red(`Update is not supported on this platform (${process.platform}/${process.arch}).\n`));
         return;
     }
-    const cur = currentVersion();
+    const cur = deps.version ?? currentVersion();
     let manifest;
     try {
-        manifest = await fetchManifest(platform);
+        manifest = await getManifest(platform);
     }
     catch {
-        process.stdout.write(pc.yellow("Could not check for updates. Make sure you're connected to the internet.\n"));
+        out(pc.yellow("Could not check for updates. Make sure you're connected to the internet.\n"));
         return;
     }
     const latest = manifest.version.replace(/^v/i, "");
     const comparison = compareSemver(cur, latest);
     if (comparison >= 0) {
-        process.stdout.write(pc.green(`Spectral is up to date (v${cur}).\n`));
+        out(pc.green(`Spectral is up to date (v${cur}).\n`));
         return;
     }
     if (checkOnly) {
-        process.stdout.write(pc.cyan(`Update available: v${cur} → v${latest}. Run \`spectral update\` to install.\n`));
+        out(pc.cyan(`Update available: v${cur} → v${latest}. Run \`spectral update\` to install.\n`));
         return;
     }
     // --- Download + verify + replace -------------------------------------
     if (!manifest.url) {
-        process.stderr.write(pc.red("Update manifest is missing a download URL. Aborting.\n"));
+        err(pc.red("Update manifest is missing a download URL. Aborting.\n"));
         return;
     }
     let tempDir = null;
     try {
         tempDir = await mkdtemp(join(tmpdir(), "spectral-update-"));
+        const currentPath = execPath;
+        const installDir = dirname(currentPath);
+        // The manifest only pins a zip when the archive was actually published.
+        const zipUrl = manifest.zipUrl?.trim() ?? "";
+        const zipSha = manifest.zipSha256?.trim() ?? "";
+        if (!!zipUrl !== !!zipSha) {
+            out(pc.yellow("Release manifest pins only part of the archive (zipUrl/zipSha256) —\n" +
+                "installing the verified raw binary instead.\n"));
+        }
+        // ----- preferred path: release zip (binary + companion assets) -------
+        if (zipUrl && zipSha) {
+            const zipPath = join(tempDir, "release.zip");
+            out(pc.dim(`Downloading v${latest} (release zip)…\n`));
+            await download(zipUrl, zipPath);
+            await stat(zipPath);
+            out(pc.dim("Verifying archive checksum…\n"));
+            const actualZip = await sha256OfFile(zipPath);
+            if (actualZip.toLowerCase() !== zipSha.toLowerCase()) {
+                err(pc.red(`Archive checksum mismatch. Expected ${zipSha.toLowerCase()}, got ${actualZip}.\n` +
+                    "The downloaded zip may be corrupted or tampered with. Nothing was installed.\n"));
+                return;
+            }
+            const unpacked = await unpackReleaseZip({ zipPath, tempDir, run });
+            if (unpacked.ok && unpacked.destDir) {
+                const stageDir = unpacked.destDir;
+                const stagedSource = await findStagedBinary(stageDir, basename(currentPath));
+                if (!stagedSource) {
+                    err(pc.red(`Release zip does not contain the ${basename(currentPath)} binary at its root. ` +
+                        "Nothing was installed.\n"));
+                    return;
+                }
+                const newBinary = join(tempDir, basename(currentPath) || "spectral-new");
+                await cp(stagedSource, newBinary, { force: true });
+                // The zip digest already pins the archive; re-checking the binary inside
+                // also guards against a mismatched archive (same as install.sh).
+                if (manifest.sha256) {
+                    out(pc.dim("Verifying binary checksum…\n"));
+                    const actualBin = await sha256OfFile(newBinary);
+                    if (actualBin.toLowerCase() !== manifest.sha256.toLowerCase()) {
+                        err(pc.red(`Binary checksum mismatch. Expected ${manifest.sha256.toLowerCase()}, got ${actualBin}.\n` +
+                            "Nothing was installed.\n"));
+                        return;
+                    }
+                }
+                out(pc.dim("Installing…\n"));
+                if (process.platform === "win32") {
+                    // A running .exe cannot be swapped from within itself, so the companion
+                    // assets are left untouched too — refreshing them while the old binary
+                    // is still in place would split the pair.
+                    await atomicReplace(currentPath, newBinary, out);
+                    out(pc.yellow("Companion assets were NOT updated. Re-run the installer to refresh them:\n" +
+                        `  curl -fsSL ${INSTALLER_URL} | sh\n`));
+                    return;
+                }
+                // Binary first: `atomicReplace` is the step most likely to fail (it needs
+                // write access to the install directory), and if it does nothing else has
+                // been touched. The companion assets only move once the new binary is in
+                // place, so a failed update never leaves new assets next to an old binary.
+                await atomicReplace(currentPath, newBinary, out);
+                const { dataDirName, replaced } = await swapCompanionAssets({ stageDir, installDir });
+                await writeVersionStamp(installDir, latest);
+                out(pc.green(`Spectral updated to v${latest}. Restart spectral to use the new version.\n`));
+                if (replaced.length) {
+                    out(pc.dim(`Companion assets refreshed: ${[dataDirName, ...replaced].join(", ")}.\n`));
+                }
+                else {
+                    out(pc.yellow("WARNING: the release zip contained no *-data directory —\n" +
+                        "companion assets were left as they were.\n"));
+                }
+                return;
+            }
+            // No usable archive tool on this machine: fall through to the raw binary.
+            out(pc.yellow(`Could not unpack the release zip (${unpacked.notes.join("; ")}) —\n` +
+                "falling back to replacing the binary only.\n"));
+        }
+        // ----- fallback path: raw binary only --------------------------------
         const downloadedPath = join(tempDir, "spectral-new");
-        process.stdout.write(pc.dim(`Downloading v${latest}…\n`));
-        await downloadToFile(manifest.url, downloadedPath);
+        out(pc.dim(`Downloading v${latest}…\n`));
+        await download(manifest.url, downloadedPath);
         // Verify the download is complete and readable.
         await stat(downloadedPath);
         // SHA256 verification.
         if (manifest.sha256) {
-            process.stdout.write(pc.dim("Verifying checksum…\n"));
+            out(pc.dim("Verifying checksum…\n"));
             const actual = await sha256OfFile(downloadedPath);
             const expected = manifest.sha256.toLowerCase();
             if (actual.toLowerCase() !== expected) {
-                process.stderr.write(pc.red(`Checksum mismatch. Expected ${expected}, got ${actual}.\n` +
+                err(pc.red(`Checksum mismatch. Expected ${expected}, got ${actual}.\n` +
                     "The downloaded file may be corrupted or tampered with. Aborting.\n"));
                 return;
             }
         }
-        const currentPath = process.execPath;
-        process.stdout.write(pc.dim("Installing…\n"));
-        await atomicReplace(currentPath, downloadedPath);
-        process.stdout.write(pc.green(`Spectral updated to v${latest}. Restart spectral to use the new version.\n`));
+        out(pc.dim("Installing…\n"));
+        await atomicReplace(currentPath, downloadedPath, out);
+        // The stamp means "this version is installed *with* its companion assets".
+        // Only the binary moved, so drop it — a stale stamp would make install.sh
+        // report "already installed" and never refresh data/ + mcp/.
+        await clearVersionStamp(installDir);
+        out(pc.green(`Spectral updated to v${latest}. Restart spectral to use the new version.\n`));
+        out(pc.yellow("WARNING: only the binary was replaced — companion assets (design systems,\n" +
+            "MCP app bridge) may be out of date. Refresh them by re-running:\n" +
+            `  curl -fsSL ${INSTALLER_URL} | sh\n`));
     }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(pc.red(`Update failed: ${msg}\n`));
+    catch (failure) {
+        const msg = failure instanceof Error ? failure.message : String(failure);
+        err(pc.red(`Update failed: ${msg}\n`));
     }
     finally {
         if (tempDir) {

package/dist/extensions/desktop-control/macos.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"macos.d.ts","sourceRoot":"","sources":["../../../src/extensions/desktop-control/macos.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAmB,MAAM,YAAY,CAAC;AA+CjF,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE;IAAE,IAAI,EAAE,YAAY,GAAG,aAAa,GAAG,YAAY,GAAG,QAAQ,CAAA;CAAE,CAAC,GAAG,MAAM,CA2CtI;AAED,uGAAuG;AACvG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAW/E;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAUlE;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAanF;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAOjE;AAUD,8EAA8E;AAC9E,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAW9D;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAsB3E;AAuED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAiB5D;AAMD,eAAO,MAAM,sBAAsB,QAI4B,CAAC;AAEhE;;;;GAIG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,CAMvD;AAoBD,eAAO,MAAM,YAAY,EAAE,cA8E1B,CAAC"}
+{"version":3,"file":"macos.d.ts","sourceRoot":"","sources":["../../../src/extensions/desktop-control/macos.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAmB,MAAM,YAAY,CAAC;AA+CjF,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE;IAAE,IAAI,EAAE,YAAY,GAAG,aAAa,GAAG,YAAY,GAAG,QAAQ,CAAA;CAAE,CAAC,GAAG,MAAM,CA2CtI;AAED,uGAAuG;AACvG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAW/E;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAUlE;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAanF;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAOjE;AAUD,8EAA8E;AAC9E,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAW9D;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAsB3E;AAuED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAiB5D;AAMD,eAAO,MAAM,sBAAsB,QAIuC,CAAC;AAE3E;;;;GAIG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,CAMvD;AAoBD,eAAO,MAAM,YAAY,EAAE,cA8E1B,CAAC"}

package/dist/extensions/desktop-control/macos.js

@@ -268,7 +268,7 @@ export function accessibilityError(rawStderr) {
     if (s.includes("assistive access") || s.includes("accessib")) {
         return ("macOS blocked desktop control: Accessibility permission is missing.\n" +
             "Fix: System Settings > Privacy & Security > Accessibility -> add (and enable) the app that runs " +
-            "spectral (your terminal, or the Electron host). Then retry. " +
+            "spectral (your terminal, or the spectral desktop wrapper). Then retry. " +
             "You can verify from the terminal with: osascript -e 'tell application \"System Events\" to get name of first process whose frontmost is true'");
     }
     if (s.includes("not allowed to send apple events") || s.includes("-1743") || s.includes("automat")) {
@@ -283,7 +283,7 @@ export function accessibilityError(rawStderr) {
 export const SCREEN_RECORDING_ERROR = "macOS blocked the safety screenshots: Screen Recording permission is missing.\n" +
     "Without it the BEFORE/AFTER captures silently show only the desktop wallpaper, so the action was refused before mutating anything.\n" +
     "Fix: System Settings > Privacy & Security > Screen Recording -> add (and enable) the app that runs " +
-    "spectral (your terminal, or the Electron host). Then retry.";
+    "spectral (your terminal, or the spectral desktop wrapper). Then retry.";
 /**
  * One-shot JXA probe: CGPreflightScreenCaptureAccess() — true when Screen
  * Recording TCC is granted. The function is missing from CoreGraphics'

package/dist/mcp/server-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-manager.d.ts","sourceRoot":"","sources":["../../src/mcp/server-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EACV,OAAO,EACP,WAAW,EACX,gBAAgB,EAChB,mCAAmC,EACnC,SAAS,EACV,MAAM,YAAY,CAAC;AAMpB,OAAO,EAA2B,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAG3F,UAAU,gBAAgB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;CAC/C;AAED,KAAK,gBAAgB,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,mCAAmC,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;AAElH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,eAAe,CAAgD;IACvE,OAAO,CAAC,iBAAiB,CAAuC;IAChE,OAAO,CAAC,cAAc,CAAmC;IAEzD,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI;IAI3D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAyBtE,gBAAgB;IAmF9B,OAAO,CAAC,YAAY;YAWN,mBAAmB;YAyEnB,aAAa;YAab,iBAAiB;IAkB/B,OAAO,CAAC,iCAAiC;IAQzC,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAI/E,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAI3C,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgBpE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAelC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIzD,iBAAiB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAIlD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOzB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOrC,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOrC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;CAMjD"}
+{"version":3,"file":"server-manager.d.ts","sourceRoot":"","sources":["../../src/mcp/server-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EACV,OAAO,EACP,WAAW,EACX,gBAAgB,EAChB,mCAAmC,EACnC,SAAS,EACV,MAAM,YAAY,CAAC;AAMpB,OAAO,EAA2B,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAI3F,UAAU,gBAAgB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;CAC/C;AAED,KAAK,gBAAgB,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,mCAAmC,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;AAElH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,eAAe,CAAgD;IACvE,OAAO,CAAC,iBAAiB,CAAuC;IAChE,OAAO,CAAC,cAAc,CAAmC;IAEzD,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI;IAI3D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAyBtE,gBAAgB;IAmF9B,OAAO,CAAC,YAAY;YAWN,mBAAmB;YAyEnB,aAAa;YAab,iBAAiB;IAkB/B,OAAO,CAAC,iCAAiC;IAQzC,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAI/E,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAI3C,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgBpE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAelC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIzD,iBAAiB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAIlD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOzB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOrC,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOrC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;CAMjD"}

package/dist/mcp/server-manager.js

@@ -10,6 +10,7 @@ import { McpOAuthProvider } from "./mcp-oauth-provider.js";
 import { supportsOAuth } from "./mcp-auth-flow.js";
 import { registerSamplingHandler } from "./sampling-handler.js";
 import { interpolateEnvRecord, resolveBearerToken, resolveConfigPath } from "./utils.js";
+import { augmentPath, getPathEnvKey } from "../utils/augment-path.js";
 export class McpServerManager {
     connections = new Map();
     connectPromises = new Map();
@@ -293,6 +294,11 @@ function resolveEnv(env) {
             resolved[key] = value;
         }
     }
+    // MCP stdio servers are spawned by name (`npx -y pkg`, `node server.js`), so
+    // they live or die by PATH. When spectral itself was launched from a GUI
+    // context that PATH has no node/npm in it — augment it for the child only,
+    // leaving our own process env untouched.
+    resolved[getPathEnvKey(resolved)] = augmentPath(resolved[getPathEnvKey(resolved)]);
     if (!env)
         return resolved;
     const overrides = interpolateEnvRecord(env);

package/dist/memory/tools/receive-agent-observations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"receive-agent-observations.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/receive-agent-observations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAIhF,eAAO,MAAM,oCAAoC,+BAA+B,CAAC;AAEjF,MAAM,WAAW,uBAAuB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IAClD,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,aAAa,GAAG,YAAY,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,4BAA4B;;;iFAqEvC,CAAC;AAEH,wBAAgB,oCAAoC,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAE5E"}
+{"version":3,"file":"receive-agent-observations.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/receive-agent-observations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAIhF,eAAO,MAAM,oCAAoC,+BAA+B,CAAC;AAEjF,MAAM,WAAW,uBAAuB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IAClD,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,aAAa,GAAG,YAAY,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,4BAA4B;;;iFAkFvC,CAAC;AAEH,wBAAgB,oCAAoC,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAE5E"}

package/dist/memory/tools/receive-agent-observations.js

@@ -8,7 +8,8 @@ export const receiveAgentObservationsTool = defineTool({
     label: "Receive observations from other agents",
     description: "Poll for observations shared by other active sessions on this machine working in the " +
         "same directory (same-machine, same-cwd; no cross-machine or team relay). " +
-        "Call this before starting work or when you suspect another agent has shared context.",
+        "Call this before starting work or when you suspect another agent has shared context. " +
+        "Delivery is per-recipient: each session polls its own inbox, and you never see your own messages.",
     promptSnippet: "Use receive_agent_observations() to pull shared observations from other active sessions on this machine.",
     promptGuidelines: [
         "Messages are same-machine + same-cwd only; there is no cross-machine or team fan-out.",
@@ -29,7 +30,13 @@ export const receiveAgentObservationsTool = defineTool({
             };
         }
         const projectId = store.getProjectByCwd(ctx.cwd);
-        const sessionId = ctx.sessionManager.getSessionId?.();
+        // Subagents receive a DISTINCT derived observation session id on the
+        // SubagentToolContext so they poll their own inbox; primary sessions
+        // fall back to the session manager's id. Never the bare parent id for
+        // subagents — per-recipient delivery would let a subagent consume the
+        // parent's broadcast observations.
+        const subCtx = ctx;
+        const sessionId = subCtx.observationSessionId ?? subCtx.sessionManager?.getSessionId?.();
         if (!projectId || !sessionId) {
             return {
                 content: [{ type: "text", text: "No project/session context." }],
@@ -40,6 +47,9 @@ export const receiveAgentObservationsTool = defineTool({
             projectId,
             channel: "memory",
             recipientSessionId: sessionId,
+            // Self-filtering: never surface the requesting session's own
+            // observations back to it (live subscribe already does this).
+            excludeSenderSessionId: sessionId,
             since: params.since,
             limit: params.limit ?? 20,
             markDelivered: true,

package/dist/relay/dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/relay/dispatcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/relay/dispatcher.ts"],"names":[],"mappings":"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"}

package/dist/relay/dispatcher.js

@@ -291,7 +291,11 @@ export async function handleClientMessage(frame, deps) {
     // Set autonomous iterative loop state before firing the prompt.
     // loop:true  → start/renew loop with the current content as original prompt;
     // loop:false → stop any active loop.
-    manager.setLoopActive(sessionId, isLoop, content, loopMaxIterations, loopGoal);
+    // Arm loop state BEFORE any await: for non-reference prompts this is
+    // synchronous, preserving the client_message/subscribe interleave below.
+    // For "@preset:<name>" prompts this returns a promise that we await just
+    // before firing the turn, so the loop replays the EXPANDED prompt.
+    const armed = manager.setLoopActive(sessionId, isLoop, content, loopMaxIterations, loopGoal);
     // 2. Attach (idempotent). On first attach we capture the replay payload
     //    and synthesize a `session_ready` ws_event so the browser sees the
     //    same first frame it would have on a direct WS connection.
@@ -350,6 +354,30 @@ export async function handleClientMessage(frame, deps) {
             });
         }
     }
+    // "@preset:<name>" loop prompts: resolve the preset before the turn fires
+    // (undefined = already armed synchronously — no yield, no reordering).
+    // The arm path resolves to the EXPANDED prompt; `null` means it failed or
+    // was aborted (loop state changed mid-resolution) — fall back to the raw
+    // content in those cases. The promise is caught, not just awaited: serve
+    // calls this handler fire-and-forget, so a rejection (e.g. a sync throw
+    // from teamIdForSession inside the manager) would otherwise surface as an
+    // unhandled rejection instead of a visible error event.
+    let expandedLoopPrompt = null;
+    if (armed instanceof Promise) {
+        try {
+            expandedLoopPrompt = await armed;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error?.(`[dispatcher] loop arming failed for ${sessionId}:`, err);
+            relay.send({
+                kind: "ws_event",
+                sessionId,
+                event: { type: "error", message: humanizeProviderError(msg) },
+            });
+        }
+    }
+    const promptContent = expandedLoopPrompt ?? content;
     // 3. Fire the prompt. `prompt()` resolves on `agent_end`; errors are
     //    converted to `error` events by the manager itself, so we just log.
     //    `modelId` (Phase 3 — Available Models whitelist) is forwarded as
@@ -359,7 +387,7 @@ export async function handleClientMessage(frame, deps) {
     //
     //    When `loop: true`, loop state is set before prompting; the normal
     //    model is used — loop replay is handled by session-stream on agent_end.
-    manager.prompt(sessionId, content, modelId, validImages, reasoningEffort).catch((err) => {
+    manager.prompt(sessionId, promptContent, modelId, validImages, reasoningEffort).catch((err) => {
         logger.error?.(`[dispatcher] manager.prompt failed for ${sessionId}:`, err);
     });
     // Arm the interval scheduler after the first (immediate) launch.

package/dist/sdk/coding-agent/core/extensions/types.d.ts

@@ -108,6 +108,14 @@ export interface SubagentToolContext {
     cwd: string;
     getSystemPrompt(): string;
     sessionManager?: Pick<ReadonlySessionManager, "getBranch" | "getSessionId">;
+    /**
+     * Session identity for inter-agent observation tools (polling the shared
+     * inter-agent inbox). Subagents receive a DISTINCT derived id
+     * (`${parentSessionId}#sub:${agentName}:${suffix}`) so they never consume
+     * or misattribute the parent session's inbox. Absent in primary sessions —
+     * tools fall back to `sessionManager.getSessionId()`.
+     */
+    observationSessionId?: string;
 }
 /**
  * Extended context for command handlers.