fix(agents): deliver OpenClaw prompt via --message-file on Windows

[oleg-ai-dev]

Summary

Fixes #96 — OpenClaw is unusable on Windows whenever the prompt contains a newline or a space.

Root cause

invokeAgent in next/src/lib/agents/invoke.ts spawns agent CLIs with shell: true on Windows (needed since npm installs CLIs like OpenClaw as .cmd shims, which CreateProcess can't launch directly — landed in #13/#15). Node's shell: true on Windows joins file + args into a single command string with a plain ' '.join(...) and no escaping, then hands that string to cmd.exe /d /s /c.

OpenClaw is the only adapter using the argv-message protocol, so invoke.ts appends --message <prompt text> directly to argv. Once the prompt contains:

• an embedded newline — cmd.exe treats it as a statement separator; everything after the first \n is silently lost. cmd.exe has no way to embed a literal newline inside a single /c "..." invocation the way an actual shell script could, so this isn't fixable by quoting --message's value harder.
• an embedded space — with no per-argument quoting, cmd.exe splits it into extra tokens ("Too many arguments").

#97 (already merged) fixes a related-but-different symptom (binary paths containing spaces) and explicitly doesn't touch this — quoting bin alone can't fix content splitting inside --message.

Fix

Since the underlying problem is that any prompt content crossing the cmd.exe command-line boundary is unsafe, the fix avoids putting the prompt there at all on Windows. Checked OpenClaw's own CLI docs (docs/cli/agent.md) rather than assuming a fix direction: --message-file <path> is documented as a supported alternative to -m/--message <text> for the exact openclaw agent ... invocation this codebase uses.

• next/src/lib/agents/argv.ts: added quoteWindowsShellArg() and buildMessageFlagArgv(platform, prompt, messageFilePath) — a pure function returning ["--message-file", quotedPath] on win32, and the original ["--message", prompt] everywhere else (POSIX spawns via execve with no shell involved, so nothing needed to change there).
• next/src/lib/agents/invoke.ts: on win32 only, writes opts.prompt to a per-invocation temp file (mkdtempSync under os.tmpdir()) before spawning, and builds the argv tail via buildMessageFlagArgv. Added cleanupMessageFile(), called from every exit path (spawn throwing, child.on("error"), child.on("close")) so the temp directory never leaks.
• Added next/src/lib/agents/__tests__/invoke-message-argv.test.ts covering both helpers, including the regression case that the raw multi-line/space-containing prompt must never appear as a literal argv element on Windows.

Verification

• pnpm exec tsx scripts/guard.ts — passes.
• pnpm -F @html-anything/next typecheck — clean.
• pnpm -F @html-anything/next test — full suite green except pre-existing/unrelated flakes (traced to a local Git-Bash tar path-translation quirk and one timing-sensitive gzip-bomb decompression test — both confirmed unrelated by isolated re-runs via PowerShell/native tar).
• pnpm -F @html-anything/next build — succeeds.
• Independent end-to-end repro: called spawnSync with the exact options invoke.ts uses (shell: true, windowsVerbatimArguments: false) against a fake .cmd shim that echoes back what it received.
  • Before this fix (--message "line one\nline two with spaces"): shim received only --message line one — everything after the newline was dropped, and even "line one" split into two args.
  • After this fix (--message-file "<a 'John Doe'-style path with a space>"): shim received exactly the two intended args, and reading the temp file back gave byte-for-byte the original multi-line prompt.

No lint script or changesets config exists in this repo, so typecheck/test/build/guard is the full verification bar.

[oleg-ai-dev]

Pushed a follow-up commit after a self-review pass turned up a few things worth hardening in the original fix:

• Switched the temp-file setup/cleanup to node:fs/promises (matching how install.ts already handles its own scratch-temp-dir case) instead of the sync fs calls, since this all runs inside an already-async handler.
• Wrapped the mkdtemp+write in try/catch so a failure there (e.g. an unwritable tmpdir) surfaces through the same {type:"error"} event every other failure path uses, and cleans up any partial directory instead of leaking it.
• The start SSE event was including the real server-side temp file path (which embeds the OS username) in the argv field forwarded to the browser — added a small redactStartEventArgv() helper so only <message file> is shown there instead.
• On abort, killing the cmd.exe-wrapped child on Windows doesn't reliably propagate to the actual openclaw process it launched (that's a pre-existing platform limitation, not something this PR introduces) — so I skip temp-file cleanup specifically when the request was aborted, to avoid deleting the file out from under a possibly-still-running orphaned process. Trade-off is a small leaked temp file on that path, which felt safer than the alternative.

No behavior change to the core fix — same --message-file approach, same test coverage plus a couple more cases for the redaction helper.

[nettee]

@oleg-ai-dev

I reviewed all three changed files and the complete head-to-main diff. The targeted and full Next test suites, typecheck, guard, and production build all pass, but the Windows path and cancellation handling still have blocking correctness and lifecycle issues described in the inline comments.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[nettee]

Blocking: quoteWindowsShellArg only quotes whitespace, but this value is still concatenated into the Windows cmd.exe command. A valid TEMP/TMP root such as C:\Temp&Data\html-anything-msg-abc\prompt.txt, or one containing ^, |, <, >, or %, can contain no whitespace, so this function returns the path unquoted; cmd.exe then treats those metacharacters as command separators or expansions. That can break the OpenClaw invocation and, for an environment-controlled temp root, can turn the shell boundary into command injection. Because os.tmpdir() is environment-controlled, this is part of the input crossing the shell boundary. Use a proper cmd.exe argument-escaping routine (or a guaranteed shell-safe temp root) that handles all metacharacters, and add regression cases for metacharacter paths before passing the result to spawn.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[nettee]

Blocking: the new awaited mkdtemp/writeFile setup runs before the abort listener is installed at the end of start. If the request signal aborts while either await is pending, the abort event is missed; adding a listener later does not replay an already-aborted signal, so this code still spawns OpenClaw after the caller has cancelled and aborted remains false. That wastes a process after disconnect/cancel and bypasses the intended cleanup decision. Check opts.signal.aborted before setup and again after each await (or install an early setup handler), remove any created directory, and return without spawning; add a regression test for abort during setup.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[nettee]

Blocking: onAbort sets aborted to true and closes the stream, then the child close handler calls cleanupMessageFile. Because this guard returns whenever aborted is true, every cancelled Windows OpenClaw run leaves its mkdtemp directory and prompt file behind; there is no later cleanup or bounded janitor. The UI aborts requests on cancel and re-run, and request disconnects can do the same, so repeated cancellations cause unbounded TEMP growth. Keep the path for a delayed, bounded cleanup after killing the process tree (or use taskkill /T before removing it), and make failed removal observable or retryable; add a cancellation test that verifies eventual cleanup without deleting a file still needed during the grace period.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[lefarcen]

Heads-up: #146 is also open against the same OpenClaw multiline-prompt path — both PRs touch next/src/lib/agents/invoke.ts and are trying to move prompt delivery onto --message-file. You and @haoke016 may want to compare approaches so review effort doesn't split unnecessarily.