@openclaw/lobster 2026.2.17 → 2026.2.19

package/README.md

@@ -72,4 +72,4 @@ Notes:
 - Runs the `lobster` executable as a local subprocess.
 - Does not manage OAuth/tokens.
 - Uses timeouts, stdout caps, and strict JSON envelope parsing.
-- Prefer an absolute `lobsterPath` in production to avoid PATH hijack.
+- Ensure `lobster` is available on `PATH` for the gateway process.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/lobster",
-  "version": "2026.2.17",
+  "version": "2026.2.19",
   "description": "Lobster workflow tool plugin (typed pipelines + resumable approvals)",
   "type": "module",
   "devDependencies": {

package/src/lobster-tool.test.ts

@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { PassThrough } from "node:stream";
-import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "../../../src/plugins/types.js";
 
 const spawnState = vi.hoisted(() => ({
@@ -57,16 +57,51 @@ function fakeCtx(overrides: Partial<OpenClawPluginToolContext> = {}): OpenClawPl
   };
 }
 
+function setProcessPlatform(platform: NodeJS.Platform) {
+  Object.defineProperty(process, "platform", {
+    value: platform,
+    configurable: true,
+  });
+}
+
 describe("lobster plugin tool", () => {
   let tempDir = "";
-  let lobsterBinPath = "";
+  const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
+  const originalPath = process.env.PATH;
+  const originalPathAlt = process.env.Path;
+  const originalPathExt = process.env.PATHEXT;
+  const originalPathExtAlt = process.env.Pathext;
 
   beforeAll(async () => {
     ({ createLobsterTool } = await import("./lobster-tool.js"));
 
     tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-lobster-plugin-"));
-    lobsterBinPath = path.join(tempDir, process.platform === "win32" ? "lobster.cmd" : "lobster");
-    await fs.writeFile(lobsterBinPath, "", { encoding: "utf8", mode: 0o755 });
+  });
+
+  afterEach(() => {
+    if (originalPlatform) {
+      Object.defineProperty(process, "platform", originalPlatform);
+    }
+    if (originalPath === undefined) {
+      delete process.env.PATH;
+    } else {
+      process.env.PATH = originalPath;
+    }
+    if (originalPathAlt === undefined) {
+      delete process.env.Path;
+    } else {
+      process.env.Path = originalPathAlt;
+    }
+    if (originalPathExt === undefined) {
+      delete process.env.PATHEXT;
+    } else {
+      process.env.PATHEXT = originalPathExt;
+    }
+    if (originalPathExtAlt === undefined) {
+      delete process.env.Pathext;
+    } else {
+      process.env.Pathext = originalPathExtAlt;
+    }
   });
 
   afterAll(async () => {
@@ -110,6 +145,28 @@ describe("lobster plugin tool", () => {
     });
   });
 
+  const queueSuccessfulEnvelope = (hello = "world") => {
+    spawnState.queue.push({
+      stdout: JSON.stringify({
+        ok: true,
+        status: "ok",
+        output: [{ hello }],
+        requiresApproval: null,
+      }),
+    });
+  };
+
+  const createWindowsShimFixture = async (params: {
+    shimPath: string;
+    scriptPath: string;
+    scriptToken: string;
+  }) => {
+    await fs.mkdir(path.dirname(params.scriptPath), { recursive: true });
+    await fs.mkdir(path.dirname(params.shimPath), { recursive: true });
+    await fs.writeFile(params.scriptPath, "module.exports = {};\n", "utf8");
+    await fs.writeFile(params.shimPath, `@echo off\r\n"${params.scriptToken}" %*\r\n`, "utf8");
+  };
+
   it("runs lobster and returns parsed envelope in details", async () => {
     spawnState.queue.push({
       stdout: JSON.stringify({
@@ -147,26 +204,43 @@ describe("lobster plugin tool", () => {
     expect(res.details).toMatchObject({ ok: true, status: "ok" });
   });
 
-  it("requires absolute lobsterPath when provided (even though it is ignored)", async () => {
+  it("requires action", async () => {
+    const tool = createLobsterTool(fakeApi());
+    await expect(tool.execute("call-action-missing", {})).rejects.toThrow(/action required/);
+  });
+
+  it("requires pipeline for run action", async () => {
     const tool = createLobsterTool(fakeApi());
     await expect(
-      tool.execute("call2", {
+      tool.execute("call-pipeline-missing", {
         action: "run",
-        pipeline: "noop",
-        lobsterPath: "./lobster",
       }),
-    ).rejects.toThrow(/absolute path/);
+    ).rejects.toThrow(/pipeline required/);
   });
 
-  it("rejects lobsterPath (deprecated) when invalid", async () => {
+  it("requires token and approve for resume action", async () => {
     const tool = createLobsterTool(fakeApi());
     await expect(
-      tool.execute("call2b", {
-        action: "run",
-        pipeline: "noop",
-        lobsterPath: "/bin/bash",
+      tool.execute("call-resume-token-missing", {
+        action: "resume",
+        approve: true,
+      }),
+    ).rejects.toThrow(/token required/);
+    await expect(
+      tool.execute("call-resume-approve-missing", {
+        action: "resume",
+        token: "resume-token",
+      }),
+    ).rejects.toThrow(/approve required/);
+  });
+
+  it("rejects unknown action", async () => {
+    const tool = createLobsterTool(fakeApi());
+    await expect(
+      tool.execute("call-action-unknown", {
+        action: "explode",
       }),
-    ).rejects.toThrow(/lobster executable/);
+    ).rejects.toThrow(/Unknown action/);
   });
 
   it("rejects absolute cwd", async () => {
@@ -191,39 +265,69 @@ describe("lobster plugin tool", () => {
     ).rejects.toThrow(/must stay within/);
   });
 
-  it("uses pluginConfig.lobsterPath when provided", async () => {
-    spawnState.queue.push({
-      stdout: JSON.stringify({
-        ok: true,
-        status: "ok",
-        output: [{ hello: "world" }],
-        requiresApproval: null,
+  it("rejects invalid JSON from lobster", async () => {
+    spawnState.queue.push({ stdout: "nope" });
+
+    const tool = createLobsterTool(fakeApi());
+    await expect(
+      tool.execute("call3", {
+        action: "run",
+        pipeline: "noop",
       }),
+    ).rejects.toThrow(/invalid JSON/);
+  });
+
+  it("runs Windows cmd shims through Node without enabling shell", async () => {
+    setProcessPlatform("win32");
+    const shimScriptPath = path.join(tempDir, "shim-dist", "lobster-cli.cjs");
+    const shimPath = path.join(tempDir, "shim-bin", "lobster.cmd");
+    await createWindowsShimFixture({
+      shimPath,
+      scriptPath: shimScriptPath,
+      scriptToken: "%dp0%\\..\\shim-dist\\lobster-cli.cjs",
     });
+    process.env.PATHEXT = ".CMD;.EXE";
+    process.env.PATH = `${path.dirname(shimPath)};${process.env.PATH ?? ""}`;
+    queueSuccessfulEnvelope();
 
-    const tool = createLobsterTool(fakeApi({ pluginConfig: { lobsterPath: lobsterBinPath } }));
-    const res = await tool.execute("call-plugin-config", {
+    const tool = createLobsterTool(fakeApi());
+    await tool.execute("call-win-shim", {
       action: "run",
       pipeline: "noop",
-      timeoutMs: 1000,
     });
 
-    expect(spawnState.spawn).toHaveBeenCalled();
-    const [execPath] = spawnState.spawn.mock.calls[0] ?? [];
-    expect(execPath).toBe(lobsterBinPath);
-    expect(res.details).toMatchObject({ ok: true, status: "ok" });
+    const [command, argv, options] = spawnState.spawn.mock.calls[0] ?? [];
+    expect(command).toBe(process.execPath);
+    expect(argv).toEqual([shimScriptPath, "run", "--mode", "tool", "noop"]);
+    expect(options).toMatchObject({ windowsHide: true });
+    expect(options).not.toHaveProperty("shell");
   });
 
-  it("rejects invalid JSON from lobster", async () => {
-    spawnState.queue.push({ stdout: "nope" });
+  it("does not retry a failed Windows spawn with shell fallback", async () => {
+    setProcessPlatform("win32");
+    spawnState.spawn.mockReset();
+    spawnState.spawn.mockImplementationOnce(() => {
+      const child = new EventEmitter() as EventEmitter & {
+        stdout: PassThrough;
+        stderr: PassThrough;
+        kill: (signal?: string) => boolean;
+      };
+      child.stdout = new PassThrough();
+      child.stderr = new PassThrough();
+      child.kill = () => true;
+      const err = Object.assign(new Error("spawn failed"), { code: "ENOENT" });
+      setImmediate(() => child.emit("error", err));
+      return child;
+    });
 
     const tool = createLobsterTool(fakeApi());
     await expect(
-      tool.execute("call3", {
+      tool.execute("call-win-no-retry", {
         action: "run",
         pipeline: "noop",
       }),
-    ).rejects.toThrow(/invalid JSON/);
+    ).rejects.toThrow(/spawn failed/);
+    expect(spawnState.spawn).toHaveBeenCalledTimes(1);
   });
 
   it("can be gated off in sandboxed contexts", async () => {

package/src/lobster-tool.ts

@@ -1,8 +1,8 @@
 import { spawn } from "node:child_process";
-import fs from "node:fs";
 import path from "node:path";
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "../../../src/plugins/types.js";
+import { resolveWindowsLobsterSpawn } from "./windows-spawn.js";
 
 type LobsterEnvelope =
   | {
@@ -21,43 +21,6 @@ type LobsterEnvelope =
       error: { type?: string; message: string };
     };
 
-function resolveExecutablePath(lobsterPathRaw: string | undefined) {
-  const lobsterPath = lobsterPathRaw?.trim() || "lobster";
-
-  // SECURITY:
-  // Never allow arbitrary executables (e.g. /bin/bash). If the caller overrides
-  // the path, it must still be the lobster binary (by name) and be absolute.
-  if (lobsterPath !== "lobster") {
-    if (!path.isAbsolute(lobsterPath)) {
-      throw new Error("lobsterPath must be an absolute path (or omit to use PATH)");
-    }
-    const base = path.basename(lobsterPath).toLowerCase();
-    const allowed =
-      process.platform === "win32" ? ["lobster.exe", "lobster.cmd", "lobster.bat"] : ["lobster"];
-    if (!allowed.includes(base)) {
-      throw new Error("lobsterPath must point to the lobster executable");
-    }
-    let stat: fs.Stats;
-    try {
-      stat = fs.statSync(lobsterPath);
-    } catch {
-      throw new Error("lobsterPath must exist");
-    }
-    if (!stat.isFile()) {
-      throw new Error("lobsterPath must point to a file");
-    }
-    if (process.platform !== "win32") {
-      try {
-        fs.accessSync(lobsterPath, fs.constants.X_OK);
-      } catch {
-        throw new Error("lobsterPath must be executable");
-      }
-    }
-  }
-
-  return lobsterPath;
-}
-
 function normalizeForCwdSandbox(p: string): string {
   const normalized = path.normalize(p);
   return process.platform === "win32" ? normalized.toLowerCase() : normalized;
@@ -84,28 +47,13 @@ function resolveCwd(cwdRaw: unknown): string {
   return resolved;
 }
 
-function isWindowsSpawnErrorThatCanUseShell(err: unknown) {
-  if (!err || typeof err !== "object") {
-    return false;
-  }
-  const code = (err as { code?: unknown }).code;
-
-  // On Windows, spawning scripts discovered on PATH (e.g. lobster.cmd) can fail
-  // with EINVAL, and PATH discovery itself can fail with ENOENT when the binary
-  // is only available via PATHEXT/script wrappers.
-  return code === "EINVAL" || code === "ENOENT";
-}
-
-async function runLobsterSubprocessOnce(
-  params: {
-    execPath: string;
-    argv: string[];
-    cwd: string;
-    timeoutMs: number;
-    maxStdoutBytes: number;
-  },
-  useShell: boolean,
-) {
+async function runLobsterSubprocessOnce(params: {
+  execPath: string;
+  argv: string[];
+  cwd: string;
+  timeoutMs: number;
+  maxStdoutBytes: number;
+}) {
   const { execPath, argv, cwd } = params;
   const timeoutMs = Math.max(200, params.timeoutMs);
   const maxStdoutBytes = Math.max(1024, params.maxStdoutBytes);
@@ -115,19 +63,46 @@ async function runLobsterSubprocessOnce(
   if (nodeOptions.includes("--inspect")) {
     delete env.NODE_OPTIONS;
   }
+  const spawnTarget =
+    process.platform === "win32"
+      ? resolveWindowsLobsterSpawn(execPath, argv, env)
+      : { command: execPath, argv };
 
   return await new Promise<{ stdout: string }>((resolve, reject) => {
-    const child = spawn(execPath, argv, {
+    const child = spawn(spawnTarget.command, spawnTarget.argv, {
       cwd,
       stdio: ["ignore", "pipe", "pipe"],
       env,
-      shell: useShell,
-      windowsHide: useShell ? true : undefined,
+      windowsHide: spawnTarget.windowsHide,
     });
 
     let stdout = "";
     let stdoutBytes = 0;
     let stderr = "";
+    let settled = false;
+
+    const settle = (
+      result: { ok: true; value: { stdout: string } } | { ok: false; error: Error },
+    ) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      if (result.ok) {
+        resolve(result.value);
+      } else {
+        reject(result.error);
+      }
+    };
+
+    const failAndTerminate = (message: string) => {
+      try {
+        child.kill("SIGKILL");
+      } finally {
+        settle({ ok: false, error: new Error(message) });
+      }
+    };
 
     child.stdout?.setEncoding("utf8");
     child.stderr?.setEncoding("utf8");
@@ -136,11 +111,7 @@ async function runLobsterSubprocessOnce(
       const str = String(chunk);
       stdoutBytes += Buffer.byteLength(str, "utf8");
       if (stdoutBytes > maxStdoutBytes) {
-        try {
-          child.kill("SIGKILL");
-        } finally {
-          reject(new Error("lobster output exceeded maxStdoutBytes"));
-        }
+        failAndTerminate("lobster output exceeded maxStdoutBytes");
         return;
       }
       stdout += str;
@@ -151,46 +122,26 @@ async function runLobsterSubprocessOnce(
     });
 
     const timer = setTimeout(() => {
-      try {
-        child.kill("SIGKILL");
-      } finally {
-        reject(new Error("lobster subprocess timed out"));
-      }
+      failAndTerminate("lobster subprocess timed out");
     }, timeoutMs);
 
     child.once("error", (err) => {
-      clearTimeout(timer);
-      reject(err);
+      settle({ ok: false, error: err });
     });
 
     child.once("exit", (code) => {
-      clearTimeout(timer);
       if (code !== 0) {
-        reject(new Error(`lobster failed (${code ?? "?"}): ${stderr.trim() || stdout.trim()}`));
+        settle({
+          ok: false,
+          error: new Error(`lobster failed (${code ?? "?"}): ${stderr.trim() || stdout.trim()}`),
+        });
         return;
       }
-      resolve({ stdout });
+      settle({ ok: true, value: { stdout } });
     });
   });
 }
 
-async function runLobsterSubprocess(params: {
-  execPath: string;
-  argv: string[];
-  cwd: string;
-  timeoutMs: number;
-  maxStdoutBytes: number;
-}) {
-  try {
-    return await runLobsterSubprocessOnce(params, false);
-  } catch (err) {
-    if (process.platform === "win32" && isWindowsSpawnErrorThatCanUseShell(err)) {
-      return await runLobsterSubprocessOnce(params, true);
-    }
-    throw err;
-  }
-}
-
 function parseEnvelope(stdout: string): LobsterEnvelope {
   const trimmed = stdout.trim();
 
@@ -229,6 +180,33 @@ function parseEnvelope(stdout: string): LobsterEnvelope {
   throw new Error("lobster returned invalid JSON envelope");
 }
 
+function buildLobsterArgv(action: string, params: Record<string, unknown>): string[] {
+  if (action === "run") {
+    const pipeline = typeof params.pipeline === "string" ? params.pipeline : "";
+    if (!pipeline.trim()) {
+      throw new Error("pipeline required");
+    }
+    const argv = ["run", "--mode", "tool", pipeline];
+    const argsJson = typeof params.argsJson === "string" ? params.argsJson : "";
+    if (argsJson.trim()) {
+      argv.push("--args-json", argsJson);
+    }
+    return argv;
+  }
+  if (action === "resume") {
+    const token = typeof params.token === "string" ? params.token : "";
+    if (!token.trim()) {
+      throw new Error("token required");
+    }
+    const approve = params.approve;
+    if (typeof approve !== "boolean") {
+      throw new Error("approve required");
+    }
+    return ["resume", "--token", token, "--approve", approve ? "yes" : "no"];
+  }
+  throw new Error(`Unknown action: ${action}`);
+}
+
 export function createLobsterTool(api: OpenClawPluginApi) {
   return {
     name: "lobster",
@@ -242,11 +220,6 @@ export function createLobsterTool(api: OpenClawPluginApi) {
       argsJson: Type.Optional(Type.String()),
       token: Type.Optional(Type.String()),
       approve: Type.Optional(Type.Boolean()),
-      // SECURITY: Do not allow the agent to choose an executable path.
-      // Host can configure the lobster binary via plugin config.
-      lobsterPath: Type.Optional(
-        Type.String({ description: "(deprecated) Use plugin config instead." }),
-      ),
       cwd: Type.Optional(
         Type.String({
           description:
@@ -262,55 +235,19 @@ export function createLobsterTool(api: OpenClawPluginApi) {
         throw new Error("action required");
       }
 
-      // SECURITY: never allow tool callers (agent/user) to select executables.
-      // If a host needs to override the binary, it must do so via plugin config.
-      // We still validate the parameter shape to prevent reintroducing an RCE footgun.
-      if (typeof params.lobsterPath === "string" && params.lobsterPath.trim()) {
-        resolveExecutablePath(params.lobsterPath);
-      }
-
-      const execPath = resolveExecutablePath(
-        typeof api.pluginConfig?.lobsterPath === "string"
-          ? api.pluginConfig.lobsterPath
-          : undefined,
-      );
+      const execPath = "lobster";
       const cwd = resolveCwd(params.cwd);
       const timeoutMs = typeof params.timeoutMs === "number" ? params.timeoutMs : 20_000;
       const maxStdoutBytes =
         typeof params.maxStdoutBytes === "number" ? params.maxStdoutBytes : 512_000;
 
-      const argv = (() => {
-        if (action === "run") {
-          const pipeline = typeof params.pipeline === "string" ? params.pipeline : "";
-          if (!pipeline.trim()) {
-            throw new Error("pipeline required");
-          }
-          const argv = ["run", "--mode", "tool", pipeline];
-          const argsJson = typeof params.argsJson === "string" ? params.argsJson : "";
-          if (argsJson.trim()) {
-            argv.push("--args-json", argsJson);
-          }
-          return argv;
-        }
-        if (action === "resume") {
-          const token = typeof params.token === "string" ? params.token : "";
-          if (!token.trim()) {
-            throw new Error("token required");
-          }
-          const approve = params.approve;
-          if (typeof approve !== "boolean") {
-            throw new Error("approve required");
-          }
-          return ["resume", "--token", token, "--approve", approve ? "yes" : "no"];
-        }
-        throw new Error(`Unknown action: ${action}`);
-      })();
+      const argv = buildLobsterArgv(action, params);
 
       if (api.runtime?.version && api.logger?.debug) {
         api.logger.debug(`lobster plugin runtime=${api.runtime.version}`);
       }
 
-      const { stdout } = await runLobsterSubprocess({
+      const { stdout } = await runLobsterSubprocessOnce({
         execPath,
         argv,
         cwd,

package/src/windows-spawn.test.ts

@@ -0,0 +1,148 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { resolveWindowsLobsterSpawn } from "./windows-spawn.js";
+
+function setProcessPlatform(platform: NodeJS.Platform) {
+  Object.defineProperty(process, "platform", {
+    value: platform,
+    configurable: true,
+  });
+}
+
+describe("resolveWindowsLobsterSpawn", () => {
+  let tempDir = "";
+  const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
+  const originalPath = process.env.PATH;
+  const originalPathAlt = process.env.Path;
+  const originalPathExt = process.env.PATHEXT;
+  const originalPathExtAlt = process.env.Pathext;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-lobster-win-spawn-"));
+    setProcessPlatform("win32");
+  });
+
+  afterEach(async () => {
+    if (originalPlatform) {
+      Object.defineProperty(process, "platform", originalPlatform);
+    }
+    if (originalPath === undefined) {
+      delete process.env.PATH;
+    } else {
+      process.env.PATH = originalPath;
+    }
+    if (originalPathAlt === undefined) {
+      delete process.env.Path;
+    } else {
+      process.env.Path = originalPathAlt;
+    }
+    if (originalPathExt === undefined) {
+      delete process.env.PATHEXT;
+    } else {
+      process.env.PATHEXT = originalPathExt;
+    }
+    if (originalPathExtAlt === undefined) {
+      delete process.env.Pathext;
+    } else {
+      process.env.Pathext = originalPathExtAlt;
+    }
+    if (tempDir) {
+      await fs.rm(tempDir, { recursive: true, force: true });
+      tempDir = "";
+    }
+  });
+
+  it("unwraps cmd shim with %dp0% token", async () => {
+    const scriptPath = path.join(tempDir, "shim-dist", "lobster-cli.cjs");
+    const shimPath = path.join(tempDir, "shim", "lobster.cmd");
+    await fs.mkdir(path.dirname(scriptPath), { recursive: true });
+    await fs.mkdir(path.dirname(shimPath), { recursive: true });
+    await fs.writeFile(scriptPath, "module.exports = {};\n", "utf8");
+    await fs.writeFile(
+      shimPath,
+      `@echo off\r\n"%dp0%\\..\\shim-dist\\lobster-cli.cjs" %*\r\n`,
+      "utf8",
+    );
+
+    const target = resolveWindowsLobsterSpawn(shimPath, ["run", "noop"], process.env);
+    expect(target.command).toBe(process.execPath);
+    expect(target.argv).toEqual([scriptPath, "run", "noop"]);
+    expect(target.windowsHide).toBe(true);
+  });
+
+  it("unwraps cmd shim with %~dp0% token", async () => {
+    const scriptPath = path.join(tempDir, "shim-dist", "lobster-cli.cjs");
+    const shimPath = path.join(tempDir, "shim", "lobster.cmd");
+    await fs.mkdir(path.dirname(scriptPath), { recursive: true });
+    await fs.mkdir(path.dirname(shimPath), { recursive: true });
+    await fs.writeFile(scriptPath, "module.exports = {};\n", "utf8");
+    await fs.writeFile(
+      shimPath,
+      `@echo off\r\n"%~dp0%\\..\\shim-dist\\lobster-cli.cjs" %*\r\n`,
+      "utf8",
+    );
+
+    const target = resolveWindowsLobsterSpawn(shimPath, ["run", "noop"], process.env);
+    expect(target.command).toBe(process.execPath);
+    expect(target.argv).toEqual([scriptPath, "run", "noop"]);
+    expect(target.windowsHide).toBe(true);
+  });
+
+  it("ignores node.exe shim entries and picks lobster script", async () => {
+    const shimDir = path.join(tempDir, "shim-with-node");
+    const scriptPath = path.join(tempDir, "shim-dist-node", "lobster-cli.cjs");
+    const shimPath = path.join(shimDir, "lobster.cmd");
+    await fs.mkdir(path.dirname(scriptPath), { recursive: true });
+    await fs.mkdir(shimDir, { recursive: true });
+    await fs.writeFile(path.join(shimDir, "node.exe"), "", "utf8");
+    await fs.writeFile(scriptPath, "module.exports = {};\n", "utf8");
+    await fs.writeFile(
+      shimPath,
+      `@echo off\r\n"%~dp0%\\node.exe" "%~dp0%\\..\\shim-dist-node\\lobster-cli.cjs" %*\r\n`,
+      "utf8",
+    );
+
+    const target = resolveWindowsLobsterSpawn(shimPath, ["run", "noop"], process.env);
+    expect(target.command).toBe(process.execPath);
+    expect(target.argv).toEqual([scriptPath, "run", "noop"]);
+    expect(target.windowsHide).toBe(true);
+  });
+
+  it("resolves lobster.cmd from PATH and unwraps npm layout shim", async () => {
+    const binDir = path.join(tempDir, "node_modules", ".bin");
+    const packageDir = path.join(tempDir, "node_modules", "lobster");
+    const scriptPath = path.join(packageDir, "dist", "cli.js");
+    const shimPath = path.join(binDir, "lobster.cmd");
+    await fs.mkdir(path.dirname(scriptPath), { recursive: true });
+    await fs.mkdir(binDir, { recursive: true });
+    await fs.writeFile(shimPath, "@echo off\r\n", "utf8");
+    await fs.writeFile(
+      path.join(packageDir, "package.json"),
+      JSON.stringify({ name: "lobster", version: "0.0.0", bin: { lobster: "dist/cli.js" } }),
+      "utf8",
+    );
+    await fs.writeFile(scriptPath, "module.exports = {};\n", "utf8");
+
+    const env = {
+      ...process.env,
+      PATH: `${binDir};${process.env.PATH ?? ""}`,
+      PATHEXT: ".CMD;.EXE",
+    };
+    const target = resolveWindowsLobsterSpawn("lobster", ["run", "noop"], env);
+    expect(target.command).toBe(process.execPath);
+    expect(target.argv).toEqual([scriptPath, "run", "noop"]);
+    expect(target.windowsHide).toBe(true);
+  });
+
+  it("fails fast when wrapper cannot be resolved without shell execution", async () => {
+    const badShimPath = path.join(tempDir, "bad-shim", "lobster.cmd");
+    await fs.mkdir(path.dirname(badShimPath), { recursive: true });
+    await fs.writeFile(badShimPath, "@echo off\r\nREM no entrypoint\r\n", "utf8");
+
+    expect(() => resolveWindowsLobsterSpawn(badShimPath, ["run", "noop"], process.env)).toThrow(
+      /without shell execution/,
+    );
+  });
+});

package/src/windows-spawn.ts

@@ -0,0 +1,193 @@
+import fs from "node:fs";
+import path from "node:path";
+
+type SpawnTarget = {
+  command: string;
+  argv: string[];
+  windowsHide?: boolean;
+};
+
+function isFilePath(value: string): boolean {
+  try {
+    const stat = fs.statSync(value);
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function resolveWindowsExecutablePath(execPath: string, env: NodeJS.ProcessEnv): string {
+  if (execPath.includes("/") || execPath.includes("\\") || path.isAbsolute(execPath)) {
+    return execPath;
+  }
+
+  const pathValue = env.PATH ?? env.Path ?? process.env.PATH ?? process.env.Path ?? "";
+  const pathEntries = pathValue
+    .split(";")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+  const hasExtension = path.extname(execPath).length > 0;
+  const pathExtRaw =
+    env.PATHEXT ??
+    env.Pathext ??
+    process.env.PATHEXT ??
+    process.env.Pathext ??
+    ".EXE;.CMD;.BAT;.COM";
+  const pathExt = hasExtension
+    ? [""]
+    : pathExtRaw
+        .split(";")
+        .map((ext) => ext.trim())
+        .filter(Boolean)
+        .map((ext) => (ext.startsWith(".") ? ext : `.${ext}`));
+
+  for (const dir of pathEntries) {
+    for (const ext of pathExt) {
+      for (const candidateExt of [ext, ext.toLowerCase(), ext.toUpperCase()]) {
+        const candidate = path.join(dir, `${execPath}${candidateExt}`);
+        if (isFilePath(candidate)) {
+          return candidate;
+        }
+      }
+    }
+  }
+
+  return execPath;
+}
+
+function resolveBinEntry(binField: string | Record<string, string> | undefined): string | null {
+  if (typeof binField === "string") {
+    const trimmed = binField.trim();
+    return trimmed || null;
+  }
+  if (!binField || typeof binField !== "object") {
+    return null;
+  }
+
+  const preferred = binField.lobster;
+  if (typeof preferred === "string" && preferred.trim()) {
+    return preferred.trim();
+  }
+
+  for (const value of Object.values(binField)) {
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return null;
+}
+
+function resolveLobsterScriptFromPackageJson(wrapperPath: string): string | null {
+  const wrapperDir = path.dirname(wrapperPath);
+  const packageDirs = [
+    // Local install: <repo>/node_modules/.bin/lobster.cmd -> ../lobster
+    path.resolve(wrapperDir, "..", "lobster"),
+    // Global npm install: <npm-prefix>/lobster.cmd -> ./node_modules/lobster
+    path.resolve(wrapperDir, "node_modules", "lobster"),
+  ];
+
+  for (const packageDir of packageDirs) {
+    const packageJsonPath = path.join(packageDir, "package.json");
+    if (!isFilePath(packageJsonPath)) {
+      continue;
+    }
+
+    try {
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8")) as {
+        bin?: string | Record<string, string>;
+      };
+      const scriptRel = resolveBinEntry(packageJson.bin);
+      if (!scriptRel) {
+        continue;
+      }
+      const scriptPath = path.resolve(packageDir, scriptRel);
+      if (isFilePath(scriptPath)) {
+        return scriptPath;
+      }
+    } catch {
+      // Ignore malformed package metadata; caller will throw a guided error.
+    }
+  }
+
+  return null;
+}
+
+function resolveLobsterScriptFromCmdShim(wrapperPath: string): string | null {
+  if (!isFilePath(wrapperPath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(wrapperPath, "utf8");
+    const candidates: string[] = [];
+    const extractRelativeFromToken = (token: string): string | null => {
+      const match = token.match(/%~?dp0%\s*[\\/]*(.*)$/i);
+      if (!match) {
+        return null;
+      }
+      const relative = match[1];
+      if (!relative) {
+        return null;
+      }
+      return relative;
+    };
+
+    const matches = content.matchAll(/"([^"\r\n]*)"/g);
+    for (const match of matches) {
+      const token = match[1] ?? "";
+      const relative = extractRelativeFromToken(token);
+      if (!relative) {
+        continue;
+      }
+
+      const normalizedRelative = relative
+        .trim()
+        .replace(/[\\/]+/g, path.sep)
+        .replace(/^[\\/]+/, "");
+      const candidate = path.resolve(path.dirname(wrapperPath), normalizedRelative);
+      if (isFilePath(candidate)) {
+        candidates.push(candidate);
+      }
+    }
+
+    const nonNode = candidates.find((candidate) => {
+      const base = path.basename(candidate).toLowerCase();
+      return base !== "node.exe" && base !== "node";
+    });
+    if (nonNode) {
+      return nonNode;
+    }
+  } catch {
+    // Ignore unreadable shims; caller will throw a guided error.
+  }
+
+  return null;
+}
+
+export function resolveWindowsLobsterSpawn(
+  execPath: string,
+  argv: string[],
+  env: NodeJS.ProcessEnv,
+): SpawnTarget {
+  const resolvedExecPath = resolveWindowsExecutablePath(execPath, env);
+  const ext = path.extname(resolvedExecPath).toLowerCase();
+  if (ext !== ".cmd" && ext !== ".bat") {
+    return { command: resolvedExecPath, argv };
+  }
+
+  const scriptPath =
+    resolveLobsterScriptFromCmdShim(resolvedExecPath) ??
+    resolveLobsterScriptFromPackageJson(resolvedExecPath);
+  if (!scriptPath) {
+    throw new Error(
+      `${path.basename(resolvedExecPath)} wrapper resolved, but no Node entrypoint could be resolved without shell execution. Ensure Lobster is installed and runnable on PATH (prefer lobster.exe).`,
+    );
+  }
+
+  const entryExt = path.extname(scriptPath).toLowerCase();
+  if (entryExt === ".exe") {
+    return { command: scriptPath, argv, windowsHide: true };
+  }
+  return { command: process.execPath, argv: [scriptPath, ...argv], windowsHide: true };
+}