fix: harden gemini cli oauth discovery (#1773) (thanks @benostein)

Fixes #1765

- Extract client ID and secret from Gemini CLI's bundled oauth2.js
- Cross-platform binary lookup (no shell commands)
- Fallback to env vars for user override
- Add tests for credential extraction

CHANGELOG.md

@@ -28,8 +28,11 @@ Docs: https://docs.clawd.bot
 - Diagnostics: add diagnostic flags for targeted debug logs (config + env override). https://docs.clawd.bot/diagnostics/flags
 
 ### Fixes
+- Gemini CLI OAuth: auto-detect client id from installed CLI and harden discovery paths. (#1773) Thanks @benostein.
+- Matrix: decrypt E2EE media attachments with preflight size guard. (#1744) Thanks @araa47.
+- Gateway: allow Control UI token-only auth to skip device pairing even when device identity is present (`gateway.controlUi.allowInsecureAuth`). (#1679) Thanks @steipete.
 - Gateway: include inline config env vars in service install environments. (#1735) Thanks @Seredeep.
-- UI: add ellipsis to config section titles in the Control UI. (#1784) Thanks @robbyczgw-cla.
+- Exec: treat Windows platform labels as Windows for node shell selection. (#1760) Thanks @ymat19.
 - BlueBubbles: route phone-number targets to DMs, avoid leaking routing IDs, and auto-create missing DMs (Private API required). (#1751) Thanks @tyler6204. https://docs.clawd.bot/channels/bluebubbles
 - BlueBubbles: keep part-index GUIDs in reply tags when short IDs are missing.
 - Web UI: hide internal `message_id` hints in chat bubbles.

CONTRIBUTING.md

@@ -40,3 +40,13 @@ Please include in your PR:
 - [ ] Confirm you understand what the code does
 
 AI PRs are first-class citizens here. We just want transparency so reviewers know what to look for.
+
+## Current Focus & Roadmap 🗺
+
+We are currently prioritizing:
+- **Stability**: Fixing edge cases in channel connections (WhatsApp/Telegram).
+- **UX**: Improving the onboarding wizard and error messages.
+- **Skills**: Expanding the library of bundled skills and improving the Skill Creation developer experience.
+- **Performance**: Optimizing token usage and compaction logic.
+
+Check the [GitHub Issues](https://github.com/clawdbot/clawdbot/issues) for "good first issue" labels!

docs/gateway/configuration.md

@@ -2847,8 +2847,9 @@ Control UI base path:
 - `gateway.controlUi.basePath` sets the URL prefix where the Control UI is served.
 - Examples: `"/ui"`, `"/clawdbot"`, `"/apps/clawdbot"`.
 - Default: root (`/`) (unchanged).
-- `gateway.controlUi.allowInsecureAuth` allows token-only auth over **HTTP** (no device identity).
-  Default: `false`. Prefer HTTPS (Tailscale Serve) or `127.0.0.1`.
+- `gateway.controlUi.allowInsecureAuth` allows token-only auth for the Control UI and skips
+  device identity + pairing (even on HTTPS). Default: `false`. Prefer HTTPS
+  (Tailscale Serve) or `127.0.0.1`.
 
 Related docs:
 - [Control UI](/web/control-ui)

docs/gateway/security.md

@@ -58,7 +58,7 @@ When the audit prints findings, treat this as a priority order:
 
 The Control UI needs a **secure context** (HTTPS or localhost) to generate device
 identity. If you enable `gateway.controlUi.allowInsecureAuth`, the UI falls back
-to **token-only auth** on plain HTTP and skips device pairing. This is a security
+to **token-only auth** and skips device pairing (even on HTTPS). This is a security
 downgrade—prefer HTTPS (Tailscale Serve) or open the UI on `127.0.0.1`.
 
 `clawdbot security audit` warns when this setting is enabled.

docs/tools/creating-skills.md

@@ -0,0 +1,41 @@
+# Creating Custom Skills 🛠
+
+Clawdbot is designed to be easily extensible. "Skills" are the primary way to add new capabilities to your assistant.
+
+## What is a Skill?
+A skill is a directory containing a `SKILL.md` file (which provides instructions and tool definitions to the LLM) and optionally some scripts or resources.
+
+## Step-by-Step: Your First Skill
+
+### 1. Create the Directory
+Skills live in your workspace, usually `~/clawd/skills/`. Create a new folder for your skill:
+```bash
+mkdir -p ~/clawd/skills/hello-world
+```
+
+### 2. Define the `SKILL.md`
+Create a `SKILL.md` file in that directory. This file uses YAML frontmatter for metadata and Markdown for instructions.
+
+```markdown
+---
+name: hello_world
+description: A simple skill that says hello.
+---
+
+# Hello World Skill
+When the user asks for a greeting, use the `echo` tool to say "Hello from your custom skill!".
+```
+
+### 3. Add Tools (Optional)
+You can define custom tools in the frontmatter or instruct the agent to use existing system tools (like `bash` or `browser`).
+
+### 4. Refresh Clawdbot
+Ask your agent to "refresh skills" or restart the gateway. Clawdbot will discover the new directory and index the `SKILL.md`.
+
+## Best Practices
+- **Be Concise**: Instruct the model on *what* to do, not how to be an AI.
+- **Safety First**: If your skill uses `bash`, ensure the prompts don't allow arbitrary command injection from untrusted user input.
+- **Test Locally**: Use `clawdbot agent --message "use my new skill"` to test.
+
+## Shared Skills
+You can also browse and contribute skills to [ClawdHub](https://clawdhub.com).

docs/web/control-ui.md

@@ -108,8 +108,8 @@ Clawdbot **blocks** Control UI connections without device identity.
 }
 ```
 
-This disables device identity + pairing for the Control UI. Use only if you
-trust the network.
+This disables device identity + pairing for the Control UI (even on HTTPS). Use
+only if you trust the network.
 
 See [Tailscale](/gateway/tailscale) for HTTPS setup guidance.
 

extensions/google-gemini-cli-auth/README.md

@@ -18,7 +18,18 @@ Restart the Gateway after enabling.
 clawdbot models auth login --provider google-gemini-cli --set-default
 ```
 
-## Env vars
+## Requirements
+
+If the Gemini CLI is installed, Clawdbot extracts the OAuth client ID automatically.
+
+```bash
+brew install gemini-cli
+# or: npm install -g @google/gemini-cli
+```
+
+## Env vars (optional)
+
+Override auto-detected credentials with:
 
 - `CLAWDBOT_GEMINI_OAUTH_CLIENT_ID` / `GEMINI_CLI_OAUTH_CLIENT_ID`
 - `CLAWDBOT_GEMINI_OAUTH_CLIENT_SECRET` / `GEMINI_CLI_OAUTH_CLIENT_SECRET`

extensions/google-gemini-cli-auth/oauth.test.ts

@@ -0,0 +1,205 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { join } from "node:path";
+
+// Mock fs module before importing the module under test
+const mockExistsSync = vi.fn();
+const mockReadFileSync = vi.fn();
+const mockRealpathSync = vi.fn();
+const mockReaddirSync = vi.fn();
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return {
+    ...actual,
+    existsSync: (...args: Parameters<typeof actual.existsSync>) => mockExistsSync(...args),
+    readFileSync: (...args: Parameters<typeof actual.readFileSync>) => mockReadFileSync(...args),
+    realpathSync: (...args: Parameters<typeof actual.realpathSync>) => mockRealpathSync(...args),
+    readdirSync: (...args: Parameters<typeof actual.readdirSync>) => mockReaddirSync(...args),
+  };
+});
+
+describe("extractGeminiCliCredentials", () => {
+  const FAKE_CLIENT_ID = "123456789-abcdef.apps.googleusercontent.com";
+  const FAKE_CLIENT_SECRET = "GOCSPX-FakeSecretValue123";
+  const FAKE_OAUTH2_CONTENT = `
+    const clientId = "${FAKE_CLIENT_ID}";
+    const clientSecret = "${FAKE_CLIENT_SECRET}";
+  `;
+  const FAKE_OAUTH2_ID_ONLY = `
+    const clientId = "${FAKE_CLIENT_ID}";
+  `;
+
+  let originalPath: string | undefined;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    originalPath = process.env.PATH;
+  });
+
+  afterEach(() => {
+    process.env.PATH = originalPath;
+  });
+
+  it("returns null when gemini binary is not in PATH", async () => {
+    process.env.PATH = "/nonexistent";
+    mockExistsSync.mockReturnValue(false);
+
+    const { extractGeminiCliCredentials, clearCredentialsCache } = await import("./oauth.js");
+    clearCredentialsCache();
+    expect(extractGeminiCliCredentials()).toBeNull();
+  });
+
+  it("extracts credentials from oauth2.js in known path", async () => {
+    const fakeBinDir = "/fake/bin";
+    const fakeGeminiPath = join(fakeBinDir, "gemini");
+    const fakeCliRoot = "/fake/lib/node_modules/@google/gemini-cli";
+    const fakeResolvedPath = `${fakeCliRoot}/dist/index.js`;
+    const fakeOauth2Path = `${fakeCliRoot}/node_modules/@google/gemini-cli-core/dist/src/code_assist/oauth2.js`;
+    const fakeShimContent = `node "${fakeResolvedPath}"`;
+
+    process.env.PATH = fakeBinDir;
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === fakeGeminiPath) return true;
+      if (p === fakeCliRoot) return true;
+      if (p === fakeOauth2Path) return true;
+      return false;
+    });
+    mockRealpathSync.mockReturnValue(fakeResolvedPath);
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === fakeGeminiPath || p === fakeResolvedPath) return fakeShimContent;
+      if (p === fakeOauth2Path) return FAKE_OAUTH2_CONTENT;
+      return "";
+    });
+
+    const { extractGeminiCliCredentials, clearCredentialsCache } = await import("./oauth.js");
+    clearCredentialsCache();
+    const result = extractGeminiCliCredentials();
+
+    expect(result).toEqual({
+      clientId: FAKE_CLIENT_ID,
+      clientSecret: FAKE_CLIENT_SECRET,
+    });
+  });
+
+  it("returns null when oauth2.js cannot be found", async () => {
+    const fakeBinDir = "/fake/bin";
+    const fakeGeminiPath = join(fakeBinDir, "gemini");
+    const fakeCliRoot = "/fake/lib/node_modules/@google/gemini-cli";
+    const fakeResolvedPath = `${fakeCliRoot}/dist/index.js`;
+    const fakeShimContent = `node "${fakeResolvedPath}"`;
+
+    process.env.PATH = fakeBinDir;
+
+    mockExistsSync.mockImplementation((p: string) => p === fakeGeminiPath || p === fakeCliRoot);
+    mockRealpathSync.mockReturnValue(fakeResolvedPath);
+    mockReaddirSync.mockReturnValue([]); // Empty directory for recursive search
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === fakeGeminiPath || p === fakeResolvedPath) return fakeShimContent;
+      return "";
+    });
+
+    const { extractGeminiCliCredentials, clearCredentialsCache } = await import("./oauth.js");
+    clearCredentialsCache();
+    expect(extractGeminiCliCredentials()).toBeNull();
+  });
+
+  it("returns null when oauth2.js lacks credentials", async () => {
+    const fakeBinDir = "/fake/bin";
+    const fakeGeminiPath = join(fakeBinDir, "gemini");
+    const fakeCliRoot = "/fake/lib/node_modules/@google/gemini-cli";
+    const fakeResolvedPath = `${fakeCliRoot}/dist/index.js`;
+    const fakeOauth2Path = `${fakeCliRoot}/node_modules/@google/gemini-cli-core/dist/src/code_assist/oauth2.js`;
+    const fakeShimContent = `node "${fakeResolvedPath}"`;
+
+    process.env.PATH = fakeBinDir;
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === fakeGeminiPath) return true;
+      if (p === fakeCliRoot) return true;
+      if (p === fakeOauth2Path) return true;
+      return false;
+    });
+    mockRealpathSync.mockReturnValue(fakeResolvedPath);
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === fakeGeminiPath || p === fakeResolvedPath) return fakeShimContent;
+      if (p === fakeOauth2Path) return "// no credentials here";
+      return "";
+    });
+
+    const { extractGeminiCliCredentials, clearCredentialsCache } = await import("./oauth.js");
+    clearCredentialsCache();
+    expect(extractGeminiCliCredentials()).toBeNull();
+  });
+
+  it("caches credentials after first extraction", async () => {
+    const fakeBinDir = "/fake/bin";
+    const fakeGeminiPath = join(fakeBinDir, "gemini");
+    const fakeCliRoot = "/fake/lib/node_modules/@google/gemini-cli";
+    const fakeResolvedPath = `${fakeCliRoot}/dist/index.js`;
+    const fakeOauth2Path = `${fakeCliRoot}/node_modules/@google/gemini-cli-core/dist/src/code_assist/oauth2.js`;
+    const fakeShimContent = `node "${fakeResolvedPath}"`;
+
+    process.env.PATH = fakeBinDir;
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === fakeGeminiPath) return true;
+      if (p === fakeCliRoot) return true;
+      if (p === fakeOauth2Path) return true;
+      return false;
+    });
+    mockRealpathSync.mockReturnValue(fakeResolvedPath);
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === fakeGeminiPath || p === fakeResolvedPath) return fakeShimContent;
+      if (p === fakeOauth2Path) return FAKE_OAUTH2_CONTENT;
+      return "";
+    });
+
+    const { extractGeminiCliCredentials, clearCredentialsCache } = await import("./oauth.js");
+    clearCredentialsCache();
+
+    // First call
+    const result1 = extractGeminiCliCredentials();
+    expect(result1).not.toBeNull();
+
+    // Second call should use cache (readFileSync not called again)
+    const readCount = mockReadFileSync.mock.calls.length;
+    const result2 = extractGeminiCliCredentials();
+    expect(result2).toEqual(result1);
+    expect(mockReadFileSync.mock.calls.length).toBe(readCount);
+  });
+
+  it("returns client id when secret is missing", async () => {
+    const fakeBinDir = "/fake/bin";
+    const fakeGeminiPath = join(fakeBinDir, "gemini");
+    const fakeCliRoot = "/fake/lib/node_modules/@google/gemini-cli";
+    const fakeResolvedPath = `${fakeCliRoot}/dist/index.js`;
+    const fakeOauth2Path = `${fakeCliRoot}/node_modules/@google/gemini-cli-core/dist/src/code_assist/oauth2.js`;
+    const fakeShimContent = `node "${fakeResolvedPath}"`;
+
+    process.env.PATH = fakeBinDir;
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p === fakeGeminiPath) return true;
+      if (p === fakeCliRoot) return true;
+      if (p === fakeOauth2Path) return true;
+      return false;
+    });
+    mockRealpathSync.mockReturnValue(fakeResolvedPath);
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p === fakeGeminiPath || p === fakeResolvedPath) return fakeShimContent;
+      if (p === fakeOauth2Path) return FAKE_OAUTH2_ID_ONLY;
+      return "";
+    });
+
+    const { extractGeminiCliCredentials, clearCredentialsCache } = await import("./oauth.js");
+    clearCredentialsCache();
+    const result = extractGeminiCliCredentials();
+
+    expect(result).toEqual({
+      clientId: FAKE_CLIENT_ID,
+      clientSecret: undefined,
+    });
+  });
+});

extensions/google-gemini-cli-auth/oauth.ts

@@ -1,6 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { createServer } from "node:http";
+import { delimiter, dirname, isAbsolute, join, normalize } from "node:path";
 
 const CLIENT_ID_KEYS = ["CLAWDBOT_GEMINI_OAUTH_CLIENT_ID", "GEMINI_CLI_OAUTH_CLIENT_ID"];
 const CLIENT_SECRET_KEYS = [
@@ -47,15 +48,203 @@ function resolveEnv(keys: string[]): string | undefined {
   return undefined;
 }
 
-function resolveOAuthClientConfig(): { clientId: string; clientSecret?: string } {
-  const clientId = resolveEnv(CLIENT_ID_KEYS);
-  if (!clientId) {
-    throw new Error(
-      "Missing Gemini OAuth client ID. Set CLAWDBOT_GEMINI_OAUTH_CLIENT_ID (or GEMINI_CLI_OAUTH_CLIENT_ID).",
-    );
+type GeminiCliClientConfig = { clientId: string; clientSecret?: string };
+
+let cachedGeminiCliCredentials: GeminiCliClientConfig | null = null;
+
+/** @internal */
+export function clearCredentialsCache(): void {
+  cachedGeminiCliCredentials = null;
+}
+
+/** Extracts OAuth credentials from the installed Gemini CLI's bundled oauth2.js. */
+export function extractGeminiCliCredentials(): GeminiCliClientConfig | null {
+  if (cachedGeminiCliCredentials) return cachedGeminiCliCredentials;
+
+  try {
+    const oauthPath = findGeminiCliOAuthPath();
+    if (!oauthPath) return null;
+
+    const content = readFileSync(oauthPath, "utf8");
+    const idMatch = content.match(/(\d+-[a-z0-9]+\.apps\.googleusercontent\.com)/i);
+    const secretMatch = content.match(/(GOCSPX-[A-Za-z0-9_-]+)/);
+    if (idMatch) {
+      cachedGeminiCliCredentials = { clientId: idMatch[1], clientSecret: secretMatch?.[1] };
+      return cachedGeminiCliCredentials;
+    }
+  } catch {
+    // Gemini CLI not installed or extraction failed
   }
-  const clientSecret = resolveEnv(CLIENT_SECRET_KEYS);
-  return { clientId, clientSecret };
+  return null;
+}
+
+function findGeminiCliOAuthPath(): string | null {
+  const geminiPath = findInPath("gemini");
+  if (!geminiPath) return null;
+
+  for (const root of getGeminiCliRoots(geminiPath)) {
+    const searchPaths = [
+      join(root, "node_modules", "@google", "gemini-cli-core", "dist", "src", "code_assist", "oauth2.js"),
+      join(root, "node_modules", "@google", "gemini-cli-core", "dist", "code_assist", "oauth2.js"),
+    ];
+    for (const p of searchPaths) {
+      if (existsSync(p)) return p;
+    }
+    if (shouldSearchRoot(root)) {
+      const found = findFile(root, "oauth2.js", 8);
+      if (found) return found;
+    }
+  }
+
+  return null;
+}
+
+function getGeminiCliRoots(geminiPath: string): string[] {
+  const roots = new Set<string>();
+  const resolved = safeRealpath(geminiPath);
+  for (const p of [geminiPath, resolved].filter(Boolean) as string[]) {
+    for (const root of extractGeminiCliRootsFromFile(p)) {
+      roots.add(root);
+    }
+    const fromPath = extractGeminiCliRootFromPath(p);
+    if (fromPath) roots.add(fromPath);
+  }
+
+  for (const globalRoot of getGlobalNodeModulesRoots()) {
+    const candidate = join(globalRoot, "@google", "gemini-cli");
+    if (existsSync(candidate)) roots.add(candidate);
+  }
+
+  return [...roots].filter((root) => existsSync(root));
+}
+
+function extractGeminiCliRootsFromFile(filePath: string): string[] {
+  const roots: string[] = [];
+  try {
+    const content = readFileSync(filePath, "utf8");
+    if (!content.includes("gemini-cli")) return roots;
+
+    const dir = dirname(filePath);
+    const regex = /["']([^"'\\r\\n]*@google[\\/]+gemini-cli[\\/]+dist[\\/]+index\\.js)["']/gi;
+    for (const match of content.matchAll(regex)) {
+      const resolved = resolveShimPath(dir, match[1]);
+      const root = extractGeminiCliRootFromPath(resolved);
+      if (root) roots.push(root);
+    }
+  } catch {
+    // ignore non-text files or missing paths
+  }
+  return roots;
+}
+
+function resolveShimPath(baseDir: string, rawPath: string): string {
+  let candidate = rawPath
+    .replace(/%~?dp0%/gi, baseDir)
+    .replace(/\$PSScriptRoot/gi, baseDir)
+    .replace(/__dirname/g, baseDir);
+
+  if (!isAbsolute(candidate)) {
+    candidate = join(baseDir, candidate);
+  }
+  return normalize(candidate);
+}
+
+function extractGeminiCliRootFromPath(pathValue: string): string | null {
+  const normalized = pathValue.replace(/\\/g, "/");
+  const marker = "/@google/gemini-cli/";
+  const idx = normalized.indexOf(marker);
+  if (idx === -1) return null;
+  return normalize(`${normalized.slice(0, idx)}${marker.slice(0, -1)}`);
+}
+
+function safeRealpath(pathValue: string): string | null {
+  try {
+    return realpathSync(pathValue);
+  } catch {
+    return null;
+  }
+}
+
+function getGlobalNodeModulesRoots(): string[] {
+  const roots = new Set<string>();
+  const prefix = process.env.npm_config_prefix ?? process.env.NPM_CONFIG_PREFIX ?? process.env.PREFIX;
+
+  if (prefix) {
+    if (process.platform === "win32") {
+      roots.add(join(prefix, "node_modules"));
+    } else {
+      roots.add(join(prefix, "lib", "node_modules"));
+    }
+  }
+
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA;
+    if (appData) roots.add(join(appData, "npm", "node_modules"));
+  } else {
+    roots.add("/usr/local/lib/node_modules");
+    roots.add("/opt/homebrew/lib/node_modules");
+  }
+
+  const pnpmHome = process.env.PNPM_HOME;
+  if (pnpmHome) {
+    roots.add(join(pnpmHome, "global", "5", "node_modules"));
+    roots.add(join(pnpmHome, "global", "4", "node_modules"));
+  }
+
+  return [...roots].filter((root) => existsSync(root));
+}
+
+function shouldSearchRoot(root: string): boolean {
+  const normalized = root.replace(/\\/g, "/");
+  if (normalized === "/" || /^[A-Za-z]:\/?$/.test(normalized)) return false;
+  const segments = normalized.split("/").filter(Boolean);
+  return segments.length >= 3;
+}
+
+function findInPath(name: string): string | null {
+  const exts = process.platform === "win32" ? [".cmd", ".bat", ".exe", ""] : [""];
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    for (const ext of exts) {
+      const p = join(dir, name + ext);
+      if (existsSync(p)) return p;
+    }
+  }
+  return null;
+}
+
+function findFile(dir: string, name: string, depth: number): string | null {
+  if (depth <= 0) return null;
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, entry.name);
+      if (entry.isFile() && entry.name === name) return p;
+      if (entry.isDirectory() && !entry.name.startsWith(".")) {
+        const found = findFile(p, name, depth - 1);
+        if (found) return found;
+      }
+    }
+  } catch {}
+  return null;
+}
+
+function resolveOAuthClientConfig(): { clientId: string; clientSecret?: string } {
+  // 1. Check env vars first (user override)
+  const envClientId = resolveEnv(CLIENT_ID_KEYS);
+  const envClientSecret = resolveEnv(CLIENT_SECRET_KEYS);
+  if (envClientId) {
+    return { clientId: envClientId, clientSecret: envClientSecret };
+  }
+
+  // 2. Try to extract from installed Gemini CLI
+  const extracted = extractGeminiCliCredentials();
+  if (extracted?.clientId) {
+    return extracted;
+  }
+
+  // 3. No credentials available
+  throw new Error(
+    "Gemini CLI credentials not found. Install it first: brew install gemini-cli (or npm install -g @google/gemini-cli), or set GEMINI_CLI_OAUTH_CLIENT_ID.",
+  );
 }
 
 function isWSL(): boolean {

extensions/matrix/src/matrix/monitor/handler.ts

@@ -329,16 +329,20 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         return;
       }
 
-      const contentType =
-        "info" in content && content.info && "mimetype" in content.info
-          ? (content.info as { mimetype?: string }).mimetype
+      const contentInfo =
+        "info" in content && content.info && typeof content.info === "object"
+          ? (content.info as { mimetype?: string; size?: number })
           : undefined;
+      const contentType = contentInfo?.mimetype;
+      const contentSize =
+        typeof contentInfo?.size === "number" ? contentInfo.size : undefined;
       if (mediaUrl?.startsWith("mxc://")) {
         try {
           media = await downloadMatrixMedia({
             client,
             mxcUrl: mediaUrl,
             contentType,
+            sizeBytes: contentSize,
             maxBytes: mediaMaxBytes,
             file: contentFile,
           });

extensions/matrix/src/matrix/monitor/media.test.ts

@@ -25,10 +25,8 @@ describe("downloadMatrixMedia", () => {
 
   it("decrypts encrypted media when file payloads are present", async () => {
     const decryptMedia = vi.fn().mockResolvedValue(Buffer.from("decrypted"));
-    const downloadContent = vi.fn().mockResolvedValue(Buffer.from("encrypted"));
 
     const client = {
-      downloadContent,
       crypto: { decryptMedia },
       mxcToHttp: vi.fn().mockReturnValue("https://example/mxc"),
     } as unknown as import("matrix-bot-sdk").MatrixClient;
@@ -55,7 +53,8 @@ describe("downloadMatrixMedia", () => {
       file,
     });
 
-    expect(decryptMedia).toHaveBeenCalled();
+    // decryptMedia should be called with just the file object (it handles download internally)
+    expect(decryptMedia).toHaveBeenCalledWith(file);
     expect(saveMediaBuffer).toHaveBeenCalledWith(
       Buffer.from("decrypted"),
       "image/png",
@@ -64,4 +63,41 @@ describe("downloadMatrixMedia", () => {
     );
     expect(result?.path).toBe("/tmp/media");
   });
+
+  it("rejects encrypted media that exceeds maxBytes before decrypting", async () => {
+    const decryptMedia = vi.fn().mockResolvedValue(Buffer.from("decrypted"));
+
+    const client = {
+      crypto: { decryptMedia },
+      mxcToHttp: vi.fn().mockReturnValue("https://example/mxc"),
+    } as unknown as import("matrix-bot-sdk").MatrixClient;
+
+    const file = {
+      url: "mxc://example/file",
+      key: {
+        kty: "oct",
+        key_ops: ["encrypt", "decrypt"],
+        alg: "A256CTR",
+        k: "secret",
+        ext: true,
+      },
+      iv: "iv",
+      hashes: { sha256: "hash" },
+      v: "v2",
+    };
+
+    await expect(
+      downloadMatrixMedia({
+        client,
+        mxcUrl: "mxc://example/file",
+        contentType: "image/png",
+        sizeBytes: 2048,
+        maxBytes: 1024,
+        file,
+      }),
+    ).rejects.toThrow("Matrix media exceeds configured size limit");
+
+    expect(decryptMedia).not.toHaveBeenCalled();
+    expect(saveMediaBuffer).not.toHaveBeenCalled();
+  });
 });

extensions/matrix/src/matrix/monitor/media.ts

@@ -40,6 +40,7 @@ async function fetchMatrixMediaBuffer(params: {
 
 /**
  * Download and decrypt encrypted media from a Matrix room.
+ * Uses matrix-bot-sdk's decryptMedia which handles both download and decryption.
  */
 async function fetchEncryptedMediaBuffer(params: {
   client: MatrixClient;
@@ -50,18 +51,13 @@ async function fetchEncryptedMediaBuffer(params: {
     throw new Error("Cannot decrypt media: crypto not enabled");
   }
 
-  // Download the encrypted content
-  const encryptedBuffer = await params.client.downloadContent(params.file.url);
-  if (encryptedBuffer.byteLength > params.maxBytes) {
+  // decryptMedia handles downloading and decrypting the encrypted content internally
+  const decrypted = await params.client.crypto.decryptMedia(params.file);
+
+  if (decrypted.byteLength > params.maxBytes) {
     throw new Error("Matrix media exceeds configured size limit");
   }
 
-  // Decrypt using matrix-bot-sdk crypto
-  const decrypted = await params.client.crypto.decryptMedia(
-    Buffer.from(encryptedBuffer),
-    params.file,
-  );
-
   return { buffer: decrypted };
 }
 
@@ -69,6 +65,7 @@ export async function downloadMatrixMedia(params: {
   client: MatrixClient;
   mxcUrl: string;
   contentType?: string;
+  sizeBytes?: number;
   maxBytes: number;
   file?: EncryptedFile;
 }): Promise<{
@@ -77,6 +74,12 @@ export async function downloadMatrixMedia(params: {
   placeholder: string;
 } | null> {
   let fetched: { buffer: Buffer; headerType?: string } | null;
+  if (
+    typeof params.sizeBytes === "number" &&
+    params.sizeBytes > params.maxBytes
+  ) {
+    throw new Error("Matrix media exceeds configured size limit");
+  }
 
   if (params.file) {
     // Encrypted media

extensions/matrix/src/matrix/monitor/types.ts

@@ -29,6 +29,7 @@ export type RoomMessageEventContent = MessageEventContent & {
   file?: EncryptedFile;
   info?: {
     mimetype?: string;
+    size?: number;
   };
   "m.relates_to"?: {
     rel_type?: string;

src/agents/model-selection.test.ts

@@ -1,252 +1,139 @@
-import { describe, expect, it } from "vitest";
-
-import type { ClawdbotConfig } from "../config/config.js";
-import { DEFAULT_PROVIDER } from "./defaults.js";
+import { describe, it, expect, vi } from "vitest";
 import {
-  buildAllowedModelSet,
-  modelKey,
   parseModelRef,
-  resolveAllowedModelRef,
-  resolveHooksGmailModel,
+  resolveModelRefFromString,
+  resolveConfiguredModelRef,
+  buildModelAliasIndex,
+  normalizeProviderId,
+  modelKey,
 } from "./model-selection.js";
+import type { ClawdbotConfig } from "../config/config.js";
 
-const catalog = [
-  {
-    provider: "openai",
-    id: "gpt-4",
-    name: "GPT-4",
-  },
-];
-
-describe("buildAllowedModelSet", () => {
-  it("always allows the configured default model", () => {
-    const cfg = {
-      agents: {
-        defaults: {
-          models: {
-            "openai/gpt-4": { alias: "gpt4" },
-          },
-        },
-      },
-    } as ClawdbotConfig;
-
-    const allowed = buildAllowedModelSet({
-      cfg,
-      catalog,
-      defaultProvider: "claude-cli",
-      defaultModel: "opus-4.5",
-    });
-
-    expect(allowed.allowAny).toBe(false);
-    expect(allowed.allowedKeys.has(modelKey("openai", "gpt-4"))).toBe(true);
-    expect(allowed.allowedKeys.has(modelKey("claude-cli", "opus-4.5"))).toBe(true);
-  });
-
-  it("includes the default model when no allowlist is set", () => {
-    const cfg = {
-      agents: { defaults: {} },
-    } as ClawdbotConfig;
-
-    const allowed = buildAllowedModelSet({
-      cfg,
-      catalog,
-      defaultProvider: "claude-cli",
-      defaultModel: "opus-4.5",
-    });
-
-    expect(allowed.allowAny).toBe(true);
-    expect(allowed.allowedKeys.has(modelKey("openai", "gpt-4"))).toBe(true);
-    expect(allowed.allowedKeys.has(modelKey("claude-cli", "opus-4.5"))).toBe(true);
-  });
-
-  it("allows explicit custom providers from models.providers", () => {
-    const cfg = {
-      agents: {
-        defaults: {
-          models: {
-            "moonshot/kimi-k2-0905-preview": { alias: "kimi" },
-          },
-        },
-      },
-      models: {
-        mode: "merge",
-        providers: {
-          moonshot: {
-            baseUrl: "https://api.moonshot.ai/v1",
-            apiKey: "x",
-            api: "openai-completions",
-            models: [{ id: "kimi-k2-0905-preview", name: "Kimi" }],
-          },
-        },
-      },
-    } as ClawdbotConfig;
-
-    const allowed = buildAllowedModelSet({
-      cfg,
-      catalog: [],
-      defaultProvider: "anthropic",
-      defaultModel: "claude-opus-4-5",
-    });
-
-    expect(allowed.allowAny).toBe(false);
-    expect(allowed.allowedKeys.has(modelKey("moonshot", "kimi-k2-0905-preview"))).toBe(true);
-  });
-});
-
-describe("parseModelRef", () => {
-  it("normalizes anthropic/opus-4.5 to claude-opus-4-5", () => {
-    const ref = parseModelRef("anthropic/opus-4.5", "anthropic");
-    expect(ref).toEqual({
-      provider: "anthropic",
-      model: "claude-opus-4-5",
+describe("model-selection", () => {
+  describe("normalizeProviderId", () => {
+    it("should normalize provider names", () => {
+      expect(normalizeProviderId("Anthropic")).toBe("anthropic");
+      expect(normalizeProviderId("Z.ai")).toBe("zai");
+      expect(normalizeProviderId("z-ai")).toBe("zai");
+      expect(normalizeProviderId("OpenCode-Zen")).toBe("opencode");
+      expect(normalizeProviderId("qwen")).toBe("qwen-portal");
     });
   });
 
-  it("normalizes google gemini 3 models to preview ids", () => {
-    expect(parseModelRef("google/gemini-3-pro", "anthropic")).toEqual({
-      provider: "google",
-      model: "gemini-3-pro-preview",
-    });
-    expect(parseModelRef("google/gemini-3-flash", "anthropic")).toEqual({
-      provider: "google",
-      model: "gemini-3-flash-preview",
-    });
-  });
-
-  it("normalizes default-provider google models", () => {
-    expect(parseModelRef("gemini-3-pro", "google")).toEqual({
-      provider: "google",
-      model: "gemini-3-pro-preview",
-    });
-  });
-});
-
-describe("resolveHooksGmailModel", () => {
-  it("returns null when hooks.gmail.model is not set", () => {
-    const cfg = {} satisfies ClawdbotConfig;
-    const result = resolveHooksGmailModel({
-      cfg,
-      defaultProvider: DEFAULT_PROVIDER,
-    });
-    expect(result).toBeNull();
-  });
-
-  it("returns null when hooks.gmail.model is empty", () => {
-    const cfg = {
-      hooks: { gmail: { model: "" } },
-    } satisfies ClawdbotConfig;
-    const result = resolveHooksGmailModel({
-      cfg,
-      defaultProvider: DEFAULT_PROVIDER,
-    });
-    expect(result).toBeNull();
-  });
-
-  it("parses provider/model from hooks.gmail.model", () => {
-    const cfg = {
-      hooks: { gmail: { model: "openrouter/meta-llama/llama-3.3-70b:free" } },
-    } satisfies ClawdbotConfig;
-    const result = resolveHooksGmailModel({
-      cfg,
-      defaultProvider: DEFAULT_PROVIDER,
-    });
-    expect(result).toEqual({
-      provider: "openrouter",
-      model: "meta-llama/llama-3.3-70b:free",
-    });
-  });
-
-  it("resolves alias from agent.models", () => {
-    const cfg = {
-      agents: {
-        defaults: {
-          models: {
-            "anthropic/claude-sonnet-4-1": { alias: "Sonnet" },
-          },
-        },
-      },
-      hooks: { gmail: { model: "Sonnet" } },
-    } satisfies ClawdbotConfig;
-    const result = resolveHooksGmailModel({
-      cfg,
-      defaultProvider: DEFAULT_PROVIDER,
-    });
-    expect(result).toEqual({
-      provider: "anthropic",
-      model: "claude-sonnet-4-1",
-    });
-  });
-
-  it("uses default provider when model omits provider", () => {
-    const cfg = {
-      hooks: { gmail: { model: "claude-haiku-3-5" } },
-    } satisfies ClawdbotConfig;
-    const result = resolveHooksGmailModel({
-      cfg,
-      defaultProvider: "anthropic",
-    });
-    expect(result).toEqual({
-      provider: "anthropic",
-      model: "claude-haiku-3-5",
-    });
-  });
-});
-
-describe("resolveAllowedModelRef", () => {
-  it("resolves aliases when allowed", () => {
-    const cfg = {
-      agents: {
-        defaults: {
-          models: {
-            "anthropic/claude-sonnet-4-1": { alias: "Sonnet" },
-          },
-        },
-      },
-    } satisfies ClawdbotConfig;
-    const resolved = resolveAllowedModelRef({
-      cfg,
-      catalog: [
-        {
-          provider: "anthropic",
-          id: "claude-sonnet-4-1",
-          name: "Sonnet",
-        },
-      ],
-      raw: "Sonnet",
-      defaultProvider: "anthropic",
-      defaultModel: "claude-opus-4-5",
-    });
-    expect("error" in resolved).toBe(false);
-    if ("ref" in resolved) {
-      expect(resolved.ref).toEqual({
+  describe("parseModelRef", () => {
+    it("should parse full model refs", () => {
+      expect(parseModelRef("anthropic/claude-3-5-sonnet", "openai")).toEqual({
         provider: "anthropic",
-        model: "claude-sonnet-4-1",
+        model: "claude-3-5-sonnet",
       });
-    }
+    });
+
+    it("should use default provider if none specified", () => {
+      expect(parseModelRef("claude-3-5-sonnet", "anthropic")).toEqual({
+        provider: "anthropic",
+        model: "claude-3-5-sonnet",
+      });
+    });
+
+    it("should return null for empty strings", () => {
+      expect(parseModelRef("", "anthropic")).toBeNull();
+      expect(parseModelRef("  ", "anthropic")).toBeNull();
+    });
+
+    it("should handle invalid slash usage", () => {
+      expect(parseModelRef("/", "anthropic")).toBeNull();
+      expect(parseModelRef("anthropic/", "anthropic")).toBeNull();
+      expect(parseModelRef("/model", "anthropic")).toBeNull();
+    });
   });
 
-  it("rejects disallowed models", () => {
-    const cfg = {
-      agents: {
-        defaults: {
-          models: {
-            "openai/gpt-4": { alias: "GPT4" },
+  describe("buildModelAliasIndex", () => {
+    it("should build alias index from config", () => {
+      const cfg: Partial<ClawdbotConfig> = {
+        agents: {
+          defaults: {
+            models: {
+              "anthropic/claude-3-5-sonnet": { alias: "fast" },
+              "openai/gpt-4o": { alias: "smart" },
+            },
           },
         },
-      },
-    } satisfies ClawdbotConfig;
-    const resolved = resolveAllowedModelRef({
-      cfg,
-      catalog: [
-        { provider: "openai", id: "gpt-4", name: "GPT-4" },
-        { provider: "anthropic", id: "claude-sonnet-4-1", name: "Sonnet" },
-      ],
-      raw: "anthropic/claude-sonnet-4-1",
-      defaultProvider: "openai",
-      defaultModel: "gpt-4",
+      };
+
+      const index = buildModelAliasIndex({
+        cfg: cfg as ClawdbotConfig,
+        defaultProvider: "anthropic",
+      });
+
+      expect(index.byAlias.get("fast")?.ref).toEqual({
+        provider: "anthropic",
+        model: "claude-3-5-sonnet",
+      });
+      expect(index.byAlias.get("smart")?.ref).toEqual({ provider: "openai", model: "gpt-4o" });
+      expect(index.byKey.get(modelKey("anthropic", "claude-3-5-sonnet"))).toEqual(["fast"]);
     });
-    expect(resolved).toEqual({
-      error: "model not allowed: anthropic/claude-sonnet-4-1",
+  });
+
+  describe("resolveModelRefFromString", () => {
+    it("should resolve from string with alias", () => {
+      const index = {
+        byAlias: new Map([
+          ["fast", { alias: "fast", ref: { provider: "anthropic", model: "sonnet" } }],
+        ]),
+        byKey: new Map(),
+      };
+
+      const resolved = resolveModelRefFromString({
+        raw: "fast",
+        defaultProvider: "openai",
+        aliasIndex: index,
+      });
+
+      expect(resolved?.ref).toEqual({ provider: "anthropic", model: "sonnet" });
+      expect(resolved?.alias).toBe("fast");
+    });
+
+    it("should resolve direct ref if no alias match", () => {
+      const resolved = resolveModelRefFromString({
+        raw: "openai/gpt-4",
+        defaultProvider: "anthropic",
+      });
+      expect(resolved?.ref).toEqual({ provider: "openai", model: "gpt-4" });
+    });
+  });
+
+  describe("resolveConfiguredModelRef", () => {
+    it("should fall back to anthropic and warn if provider is missing for non-alias", () => {
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const cfg: Partial<ClawdbotConfig> = {
+        agents: {
+          defaults: {
+            model: "claude-3-5-sonnet",
+          },
+        },
+      };
+
+      const result = resolveConfiguredModelRef({
+        cfg: cfg as ClawdbotConfig,
+        defaultProvider: "google",
+        defaultModel: "gemini-pro",
+      });
+
+      expect(result).toEqual({ provider: "anthropic", model: "claude-3-5-sonnet" });
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Falling back to "anthropic/claude-3-5-sonnet"'),
+      );
+      warnSpy.mockRestore();
+    });
+
+    it("should use default provider/model if config is empty", () => {
+      const cfg: Partial<ClawdbotConfig> = {};
+      const result = resolveConfiguredModelRef({
+        cfg: cfg as ClawdbotConfig,
+        defaultProvider: "openai",
+        defaultModel: "gpt-4",
+      });
+      expect(result).toEqual({ provider: "openai", model: "gpt-4" });
     });
   });
 });

src/agents/model-selection.ts

@@ -131,14 +131,24 @@ export function resolveConfiguredModelRef(params: {
       cfg: params.cfg,
       defaultProvider: params.defaultProvider,
     });
+    if (!trimmed.includes("/")) {
+      const aliasKey = normalizeAliasKey(trimmed);
+      const aliasMatch = aliasIndex.byAlias.get(aliasKey);
+      if (aliasMatch) return aliasMatch.ref;
+
+      // Default to anthropic if no provider is specified, but warn as this is deprecated.
+      console.warn(
+        `[clawdbot] Model "${trimmed}" specified without provider. Falling back to "anthropic/${trimmed}". Please use "anthropic/${trimmed}" in your config.`,
+      );
+      return { provider: "anthropic", model: trimmed };
+    }
+
     const resolved = resolveModelRefFromString({
       raw: trimmed,
       defaultProvider: params.defaultProvider,
       aliasIndex,
     });
     if (resolved) return resolved.ref;
-    // TODO(steipete): drop this fallback once provider-less agents.defaults.model is fully deprecated.
-    return { provider: "anthropic", model: trimmed };
   }
   return { provider: params.defaultProvider, model: params.defaultModel };
 }

src/auto-reply/heartbeat.ts

@@ -32,6 +32,8 @@ export function isHeartbeatContentEffectivelyEmpty(content: string | undefined |
     // This intentionally does NOT skip lines like "#TODO" or "#hashtag" which might be content
     // (Those aren't valid markdown headers - ATX headers require space after #)
     if (/^#+(\s|$)/.test(trimmed)) continue;
+    // Skip empty markdown list items like "- [ ]" or "* [ ]" or just "- "
+    if (/^[-*+]\s*(\[[\sXx]?\]\s*)?$/.test(trimmed)) continue;
     // Found a non-empty, non-comment line - there's actionable content
     return false;
   }

src/gateway/server.auth.e2e.test.ts

@@ -2,6 +2,7 @@ import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
 import { WebSocket } from "ws";
 import { PROTOCOL_VERSION } from "./protocol/index.js";
 import { getHandshakeTimeoutMs } from "./server-constants.js";
+import { buildDeviceAuthPayload } from "./device-auth.js";
 import {
   connectReq,
   getFreePort,
@@ -286,6 +287,70 @@ describe("gateway server auth/connect", () => {
     }
   });
 
+  test("allows control ui with device identity when insecure auth is enabled", async () => {
+    testState.gatewayControlUi = { allowInsecureAuth: true };
+    const { writeConfigFile } = await import("../config/config.js");
+    await writeConfigFile({
+      gateway: {
+        trustedProxies: ["127.0.0.1"],
+      },
+    } as any);
+    const prevToken = process.env.CLAWDBOT_GATEWAY_TOKEN;
+    process.env.CLAWDBOT_GATEWAY_TOKEN = "secret";
+    const port = await getFreePort();
+    const server = await startGatewayServer(port);
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`, {
+      headers: { "x-forwarded-for": "203.0.113.10" },
+    });
+    const challengePromise = onceMessage<{ payload?: unknown }>(
+      ws,
+      (o) => o.type === "event" && o.event === "connect.challenge",
+    );
+    await new Promise<void>((resolve) => ws.once("open", resolve));
+    const challenge = await challengePromise;
+    const nonce = (challenge.payload as { nonce?: unknown } | undefined)?.nonce;
+    expect(typeof nonce).toBe("string");
+    const { loadOrCreateDeviceIdentity, publicKeyRawBase64UrlFromPem, signDevicePayload } =
+      await import("../infra/device-identity.js");
+    const identity = loadOrCreateDeviceIdentity();
+    const signedAtMs = Date.now();
+    const payload = buildDeviceAuthPayload({
+      deviceId: identity.deviceId,
+      clientId: GATEWAY_CLIENT_NAMES.CONTROL_UI,
+      clientMode: GATEWAY_CLIENT_MODES.WEBCHAT,
+      role: "operator",
+      scopes: [],
+      signedAtMs,
+      token: "secret",
+      nonce: String(nonce),
+    });
+    const device = {
+      id: identity.deviceId,
+      publicKey: publicKeyRawBase64UrlFromPem(identity.publicKeyPem),
+      signature: signDevicePayload(identity.privateKeyPem, payload),
+      signedAt: signedAtMs,
+      nonce: String(nonce),
+    };
+    const res = await connectReq(ws, {
+      token: "secret",
+      device,
+      client: {
+        id: GATEWAY_CLIENT_NAMES.CONTROL_UI,
+        version: "1.0.0",
+        platform: "web",
+        mode: GATEWAY_CLIENT_MODES.WEBCHAT,
+      },
+    });
+    expect(res.ok).toBe(true);
+    ws.close();
+    await server.close();
+    if (prevToken === undefined) {
+      delete process.env.CLAWDBOT_GATEWAY_TOKEN;
+    } else {
+      process.env.CLAWDBOT_GATEWAY_TOKEN = prevToken;
+    }
+  });
+
   test("accepts device token auth for paired device", async () => {
     const { loadOrCreateDeviceIdentity } = await import("../infra/device-identity.js");
     const { approveDevicePairing, getPairedDevice, listDevicePairing } =

src/gateway/server/ws-connection/message-handler.ts

@@ -318,13 +318,13 @@ export function attachGatewayWsMessageHandler(params: {
         let devicePublicKey: string | null = null;
         const hasTokenAuth = Boolean(connectParams.auth?.token);
         const hasPasswordAuth = Boolean(connectParams.auth?.password);
+        const hasSharedAuth = hasTokenAuth || hasPasswordAuth;
         const isControlUi = connectParams.client.id === GATEWAY_CLIENT_IDS.CONTROL_UI;
+        const allowInsecureControlUi =
+          isControlUi && configSnapshot.gateway?.controlUi?.allowInsecureAuth === true;
 
         if (!device) {
-          const allowInsecureControlUi =
-            isControlUi && configSnapshot.gateway?.controlUi?.allowInsecureAuth === true;
-          const canSkipDevice =
-            isControlUi && allowInsecureControlUi ? hasTokenAuth || hasPasswordAuth : hasTokenAuth;
+          const canSkipDevice = allowInsecureControlUi ? hasSharedAuth : hasTokenAuth;
 
           if (isControlUi && !allowInsecureControlUi) {
             const errorMessage = "control ui requires HTTPS or localhost (secure context)";
@@ -569,7 +569,8 @@ export function attachGatewayWsMessageHandler(params: {
           return;
         }
 
-        if (device && devicePublicKey) {
+        const skipPairing = allowInsecureControlUi && hasSharedAuth;
+        if (device && devicePublicKey && !skipPairing) {
           const requirePairing = async (reason: string, _paired?: { deviceId: string }) => {
             const pairing = await requestDevicePairing({
               deviceId: device.id,

src/infra/node-shell.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+
+import { buildNodeShellCommand } from "./node-shell.js";
+
+describe("buildNodeShellCommand", () => {
+  it("uses cmd.exe for win32", () => {
+    expect(buildNodeShellCommand("echo hi", "win32")).toEqual([
+      "cmd.exe",
+      "/d",
+      "/s",
+      "/c",
+      "echo hi",
+    ]);
+  });
+
+  it("uses cmd.exe for windows labels", () => {
+    expect(buildNodeShellCommand("echo hi", "windows")).toEqual([
+      "cmd.exe",
+      "/d",
+      "/s",
+      "/c",
+      "echo hi",
+    ]);
+    expect(buildNodeShellCommand("echo hi", "Windows 11")).toEqual([
+      "cmd.exe",
+      "/d",
+      "/s",
+      "/c",
+      "echo hi",
+    ]);
+  });
+
+  it("uses /bin/sh for darwin", () => {
+    expect(buildNodeShellCommand("echo hi", "darwin")).toEqual(["/bin/sh", "-lc", "echo hi"]);
+  });
+
+  it("uses /bin/sh when platform missing", () => {
+    expect(buildNodeShellCommand("echo hi")).toEqual(["/bin/sh", "-lc", "echo hi"]);
+  });
+});

src/infra/node-shell.ts

@@ -2,7 +2,7 @@ export function buildNodeShellCommand(command: string, platform?: string | null)
   const normalized = String(platform ?? "")
     .trim()
     .toLowerCase();
-  if (normalized.includes("win")) {
+  if (normalized.startsWith("win")) {
     return ["cmd.exe", "/d", "/s", "/c", command];
   }
   return ["/bin/sh", "-lc", command];