mulmoterminal 1.9.1 → 1.9.2

package/README.md

@@ -371,7 +371,7 @@ the server runs without one.
 | ------------ | -------------- | ----------- |
 | `PORT`        | `34567`        | Backend HTTP/WebSocket port (prod: the URL you open). |
 | `CLIENT_PORT` | `6856`         | Vite dev-server port (dev only: the URL you open with `yarn dev`). |
-| `CLAUDE_BIN` | `claude`       | The Claude Code binary to spawn. On Windows a bare name is resolved to the `.exe` on `PATH` before it reaches the PTY layer, which matches file names exactly. |
+| `CLAUDE_BIN` | `claude`       | The Claude Code binary to spawn. On Windows a bare name is resolved on `PATH` before it reaches the PTY layer (which matches file names exactly): to the `.exe` when there is one, otherwise to the `.cmd` shim an npm-global install leaves, run through `cmd.exe`. |
 | `CLAUDE_CWD` | current dir    | Working directory each `claude` PTY runs in; determines which project's sessions the sidebar lists. Via `npx mulmoterminal` it defaults to the directory you ran the command from (override with `--cwd <dir>`, relative allowed); when the server is run directly it falls back to `~/mulmoclaude`. A value read from `.env` must be an absolute path (`~` is not expanded). |
 | `CLAUDE_PERMISSION_MODE` | `auto` | Permission mode passed to each `claude` spawn. |
 | `MT_TITLE_MODEL` | `haiku` | Model used for the cell header's AI title (a cheap/fast model summarizing the recent turns). Accepts a `--model` alias or a full model id. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmoterminal",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "description": "MulmoTerminal — browser terminal + GUI panel for Claude Code. One command to start.",
   "type": "module",
   "license": "MIT",

package/server/infra/cmd-escape.ts

@@ -0,0 +1,48 @@
+// Building the command line that runs a Windows batch shim (`claude.cmd` from an npm-global
+// install) under `cmd.exe`. CreateProcessW — what node-pty ultimately calls — executes PE
+// images only, so a batch target has no other way in (#798).
+//
+// The command line is then parsed TWICE: by cmd.exe, and by the child's CRT. The two
+// disagree about escaping, and cmd's rules are the ones that decide whether an argument
+// stays an argument: `\"` (the CRT's escape, and what node-pty's own argsToCommandLine
+// emits) does not escape a quote for cmd — it ends the quoted run, after which a `&` in the
+// same argument is a command separator. Hence the rules below, which are cmd's.
+
+/** An argument that cannot be represented on a Windows command line. Thrown rather than
+ *  silently mangled: a truncated argument reaches the agent as a DIFFERENT instruction. */
+export class UnsafeArgumentError extends Error {
+  constructor(reason: string) {
+    super(reason);
+    this.name = "UnsafeArgumentError";
+  }
+}
+
+// A command line has no encoding for these: CR/LF end it, NUL terminates it.
+const UNREPRESENTABLE = /[\0\r\n]/;
+
+// Counted rather than matched: an anchored `\\+$` backtracks over a long run.
+const trailingBackslashCount = (text: string): number => {
+  const fromEnd = [...text].reverse().findIndex((ch) => ch !== "\\");
+  return fromEnd === -1 ? text.length : fromEnd;
+};
+
+/** One argument, quoted for cmd.exe. Always quoted — inside quotes cmd's metacharacters
+ *  (`& | < > ^ ( )`) are literal, which is the whole defence. Internal quotes are doubled
+ *  (cmd's escape), and a trailing backslash run is doubled so it escapes itself instead of
+ *  the closing quote when the CRT parses the same text afterwards. */
+export function escapeBatchArgument(arg: string): string {
+  if (UNREPRESENTABLE.test(arg)) throw new UnsafeArgumentError(`argument contains a NUL, CR or LF: ${JSON.stringify(arg)}`);
+  const quotesDoubled = arg.replace(/"/g, '""');
+  return `"${quotesDoubled}${"\\".repeat(trailingBackslashCount(quotesDoubled))}"`;
+}
+
+/** Everything after `cmd.exe` for running `batchPath args…`.
+ *
+ *  `/d` skips AutoRun, so a `HKCU\…\Command Processor\AutoRun` command cannot run inside our
+ *  session first. `/s` makes cmd strip exactly the outer quote pair and take the rest
+ *  verbatim, instead of applying its "is the first token a quoted path?" heuristics to a line
+ *  that already contains quoted arguments. */
+export function batchCommandLine(batchPath: string, args: readonly string[]): string {
+  const command = [escapeBatchArgument(batchPath), ...args.map(escapeBatchArgument)].join(" ");
+  return `/d /s /c "${command}"`;
+}

package/server/infra/pty-env.ts

@@ -37,14 +37,17 @@ export function isPathVar(name: string): boolean {
   return name.toLowerCase() === "path";
 }
 
-// The search path out of a PLAIN env object. `env.PATH` is only reliable on the live
-// `process.env`, whose Windows lookups are case-insensitive; a copy (what sanitizePtyEnv
-// returns) keeps the original "Path" key and answers undefined to `.PATH`.
-export function pathFromEnv(env: NodeJS.ProcessEnv): string | undefined {
-  const entry = Object.entries(env).find(([name]) => isPathVar(name));
-  return entry?.[1];
+// A variable out of a PLAIN env object, matched the way Windows matches: case-insensitively.
+// `env.PATH` / `env.ComSpec` are only reliable on the live `process.env`, whose Windows
+// lookups are case-insensitive; a copy (what sanitizePtyEnv returns) keeps whatever casing
+// the system used and answers undefined to any other spelling.
+export function envValue(env: NodeJS.ProcessEnv, name: string): string | undefined {
+  const wanted = name.toLowerCase();
+  return Object.entries(env).find(([key]) => key.toLowerCase() === wanted)?.[1];
 }
 
+export const pathFromEnv = (env: NodeJS.ProcessEnv): string | undefined => envValue(env, "PATH");
+
 // yarn v1's temp dir is `yarn--` + a timestamp.
 const YARN_SHIM_DIR = /^yarn--\d/;
 

package/server/infra/resolve-bin.ts

@@ -4,28 +4,33 @@
 // compares each PATH directory's file name EXACTLY — it never appends an executable
 // extension. A bare "claude" therefore misses `…\.local\bin\claude.exe` and the spawn dies
 // with `File not found: ` (nothing after the colon, since the path it failed to find is the
-// empty string). Handing it an absolute path skips that lookup entirely.
+// empty string). Handing it an absolute path skips that lookup entirely (#794).
 //
-// The gate is all this has to satisfy: node-pty then launches via
-// `CreateProcessW(nullptr, cmdline, …)`, which does its own PATH search. Which is also why
-// only a PE image may be returned here — CreateProcess cannot run a `.cmd`, a `.bat`, or an
-// extensionless shell shim, so resolving a bare name to one would turn a spawn that works
-// today (the shim satisfies the gate, CreateProcess finds the real .exe elsewhere on PATH)
-// into `Cannot create process`.
+// node-pty then launches via `CreateProcessW(nullptr, cmdline, …)`, which runs PE images
+// only. A batch shim — all an npm-global install leaves on PATH — therefore has to go
+// through `cmd.exe` instead of being named directly (#798), which is why this resolves to a
+// launch descriptor rather than to a path.
 import { statSync } from "node:fs";
 import path from "node:path";
-import { pathFromEnv } from "./pty-env.js";
+import { envValue, pathFromEnv } from "./pty-env.js";
+import { batchCommandLine } from "./cmd-escape.js";
 
 // `.exe` first: with both present, a bare name would have reached the `.exe` (CreateProcess
 // appends exactly that), so resolving must not silently switch which file runs.
 const EXECUTABLE_EXTENSIONS = [".exe", ".com"] as const;
+const BATCH_EXTENSIONS = [".cmd", ".bat"] as const;
 
-const hasExecutableExtension = (bin: string): boolean => EXECUTABLE_EXTENSIONS.some((ext) => bin.toLowerCase().endsWith(ext));
+const endsWithOneOf = (bin: string, extensions: readonly string[]): boolean => extensions.some((ext) => bin.toLowerCase().endsWith(ext));
 
 // A name node-pty/CreateProcess already resolves on its own (absolute, or relative to a
 // directory) rather than by searching PATH.
 const namesAPath = (bin: string): boolean => bin.includes("\\") || bin.includes("/");
 
+// What node-pty is handed. `args` as a STRING is a raw command line that node-pty passes
+// through verbatim (its argsToCommandLine only quotes an argv ARRAY) — which is what lets
+// the cmd.exe wrapping below own its own quoting.
+export type PtyLaunch = { file: string; args: string[] | string };
+
 export function isExecutableFile(candidate: string): boolean {
   try {
     return statSync(candidate).isFile();
@@ -34,17 +39,6 @@ export function isExecutableFile(candidate: string): boolean {
   }
 }
 
-/** The absolute path of the executable a bare Windows command name refers to, or null when
- *  PATH holds no `.exe`/`.com` for it (the caller then leaves the name as it is). Pure —
- *  `searchPath` and the existence check are parameters, and `path.win32` + ";" are used
- *  explicitly, so the rule is checkable from a POSIX host too. */
-export function resolveWindowsExecutable(bin: string, searchPath: string | undefined, fileExists: (candidate: string) => boolean): string | null {
-  if (bin === "" || namesAPath(bin)) return null;
-  const names = hasExecutableExtension(bin) ? [bin] : EXECUTABLE_EXTENSIONS.map((ext) => bin + ext);
-  const candidates = searchDirectories(searchPath).flatMap((dir) => names.map((name) => path.win32.join(dir, name)));
-  return candidates.find(fileExists) ?? null; // `find` is lazy: it stops at the first hit
-}
-
 // A PATH entry may be quoted — `"C:\Program Files\tools"` — which the shells strip and a
 // plain join would not, leaving a path that matches nothing.
 const searchDirectories = (searchPath: string | undefined): string[] =>
@@ -53,15 +47,72 @@ const searchDirectories = (searchPath: string | undefined): string[] =>
     .map((entry) => entry.replace(/^"(.*)"$/, "$1"))
     .filter((entry) => entry !== "");
 
-/** The name to hand node-pty for `bin`. Unchanged off Windows, and unchanged when nothing
- *  resolves — a host that spawns fine today must keep spawning fine. */
-export function resolvePtyBin(bin: string, platform: NodeJS.Platform, searchPath: string | undefined, fileExists = isExecutableFile): string {
-  if (platform !== "win32") return bin;
-  return resolveWindowsExecutable(bin, searchPath, fileExists) ?? bin;
+// The first `<dir>\<bin><ext>` that exists, over every PATH directory for one set of
+// extensions. `find` is lazy, so it stops at the first hit.
+function searchPathFor(bin: string, extensions: readonly string[], searchPath: string | undefined, fileExists: (candidate: string) => boolean): string | null {
+  const names = endsWithOneOf(bin, extensions) ? [bin] : extensions.map((ext) => bin + ext);
+  return (
+    searchDirectories(searchPath)
+      .flatMap((dir) => names.map((name) => path.win32.join(dir, name)))
+      .find(fileExists) ?? null
+  );
+}
+
+/** The absolute path of the executable a bare Windows command name refers to, or null when
+ *  PATH holds no `.exe`/`.com` for it. Pure — `searchPath` and the existence check are
+ *  parameters, and `path.win32` + ";" are used explicitly, so the rule is checkable from a
+ *  POSIX host too. */
+export function resolveWindowsExecutable(bin: string, searchPath: string | undefined, fileExists: (candidate: string) => boolean): string | null {
+  if (bin === "" || namesAPath(bin)) return null;
+  return searchPathFor(bin, EXECUTABLE_EXTENSIONS, searchPath, fileExists);
+}
+
+/** The absolute path of the batch shim a bare command name refers to, or null. Only ever
+ *  consulted after `resolveWindowsExecutable` has come up empty ACROSS THE WHOLE PATH —
+ *  deliberately not cmd.exe's per-directory order. An install whose shim sits in an earlier
+ *  PATH directory than its real `.exe` runs the `.exe` today; moving it onto the cmd.exe
+ *  path would add a parsing layer to a spawn that already works. */
+export function resolveWindowsBatch(bin: string, searchPath: string | undefined, fileExists: (candidate: string) => boolean): string | null {
+  if (bin === "" || namesAPath(bin)) return null;
+  return searchPathFor(bin, BATCH_EXTENSIONS, searchPath, fileExists);
+}
+
+/** How to launch `bin args…`. Off Windows, and whenever nothing resolves, this is the
+ *  arguments unchanged — a host that spawns fine today must keep spawning fine. */
+export function resolvePtyLaunch(
+  bin: string,
+  args: string[],
+  platform: NodeJS.Platform,
+  searchPath: string | undefined,
+  comspec: string | undefined,
+  fileExists = isExecutableFile,
+): PtyLaunch {
+  if (platform !== "win32") return { file: bin, args };
+  // A name that already names a path needs no PATH search — but CreateProcess still cannot
+  // RUN a batch file, and `CLAUDE_BIN=C:\…\claude.cmd` is exactly what someone reaches for
+  // when working around a broken spawn. Wrapped without an existence check: a relative path
+  // is relative to the PTY's cwd, not this process's, so checking here would ask the wrong
+  // directory — and cmd.exe naming the path it cannot find beats node-pty's empty message.
+  if (namesAPath(bin)) {
+    if (!endsWithOneOf(bin, BATCH_EXTENSIONS)) return { file: bin, args };
+    return { file: commandProcessor(comspec, searchPath, fileExists), args: batchCommandLine(bin, args) };
+  }
+  const executable = resolveWindowsExecutable(bin, searchPath, fileExists);
+  if (executable) return { file: executable, args };
+  const batch = resolveWindowsBatch(bin, searchPath, fileExists);
+  if (batch) return { file: commandProcessor(comspec, searchPath, fileExists), args: batchCommandLine(batch, args) };
+  return { file: bin, args };
+}
+
+// ComSpec is where Windows itself records the command processor; falling back to a PATH
+// lookup (and then to the bare name) keeps a stripped environment working.
+function commandProcessor(comspec: string | undefined, searchPath: string | undefined, fileExists: (candidate: string) => boolean): string {
+  if (comspec && namesAPath(comspec) && fileExists(comspec)) return comspec;
+  return resolveWindowsExecutable("cmd.exe", searchPath, fileExists) ?? "cmd.exe";
 }
 
-/** `resolvePtyBin` against the environment the session itself will run with: the binary that
- *  matters is the one reachable from the child's PATH, not the server's. */
-export function resolvePtyBinForEnv(bin: string, env: NodeJS.ProcessEnv): string {
-  return resolvePtyBin(bin, process.platform, pathFromEnv(env));
+/** `resolvePtyLaunch` against the environment the session itself will run with: the binary
+ *  that matters is the one reachable from the child's PATH, not the server's. */
+export function resolvePtyLaunchForEnv(bin: string, args: string[], env: NodeJS.ProcessEnv): PtyLaunch {
+  return resolvePtyLaunch(bin, args, process.platform, pathFromEnv(env), envValue(env, "ComSpec"));
 }

package/server/session/pty-spawn.ts

@@ -7,7 +7,7 @@ import type { IPty } from "node-pty";
 import path from "node:path";
 import type { WebSocket } from "ws";
 import { sanitizePtyEnv } from "../infra/pty-env.js";
-import { resolvePtyBinForEnv } from "../infra/resolve-bin.js";
+import { resolvePtyLaunchForEnv } from "../infra/resolve-bin.js";
 import { withoutUnset } from "./provider-env.js";
 import { tmuxAvailable, tmuxNewSessionArgs, tmuxScrubEnvNames } from "../infra/tmux.js";
 import {
@@ -34,9 +34,11 @@ const PTY_ROWS = 30;
 // the settings `env` block, which can set a variable but not remove one.
 export function spawnPty(bin: string, args: string[], cwd: string, unset: readonly string[] = []): IPty {
   const env = withoutUnset(sanitizePtyEnv(process.env, path.delimiter), unset);
-  // On Windows a bare name never reaches node-pty as-is: its own PATH lookup ignores
-  // executable extensions, so `claude` misses claude.exe (see infra/resolve-bin.ts, #794).
-  return pty.spawn(resolvePtyBinForEnv(bin, env), args, { name: "xterm-256color", cols: PTY_COLS, rows: PTY_ROWS, cwd, env });
+  // On Windows neither the name nor the arguments reach node-pty as they are: its PATH
+  // lookup ignores executable extensions (so `claude` misses claude.exe, #794), and a batch
+  // shim has to be run through cmd.exe (#798). See infra/resolve-bin.ts.
+  const launch = resolvePtyLaunchForEnv(bin, args, env);
+  return pty.spawn(launch.file, launch.args, { name: "xterm-256color", cols: PTY_COLS, rows: PTY_ROWS, cwd, env });
 }
 
 // Would this session run in the Docker sandbox? Single-view interactive only (the caller