mixdog 0.7.15 → 0.7.17

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "source": {
         "source": "url",
         "url": "https://github.com/trib-plugin/mixdog.git",
-        "ref": "v0.7.15"
+        "ref": "v0.7.17"
       },
       "strict": false,
       "mcpServers": {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.7.15",
+  "version": "0.7.17",
   "description": "Claude Code all-in-one agent plugin — autonomous agents, continuous memory, cost-aware sub-agents, and syntax-aware code editing.",
   "hooks": "./hooks/hooks.json",
   "mcpServers": {

package/hooks/session-start.cjs

@@ -1257,11 +1257,19 @@ async function runRulesPart() {
   // only when it is not already alive and never opens a browser window, so
   // this is a cheap no-op once the server is running.
   try {
-    spawn('bun', [path.join(PLUGIN_ROOT, 'setup', 'launch.mjs'), '--prewarm'], {
+    const _prewarm = spawn('bun', [path.join(PLUGIN_ROOT, 'setup', 'launch.mjs'), '--prewarm'], {
       detached: true,
       stdio: 'ignore',
       windowsHide: true,
-    }).unref();
+    });
+    // ENOENT (bun not on PATH) and other spawn failures surface ASYNC as an
+    // 'error' event, NOT via the try/catch above. Without a listener Node
+    // throws it as an uncaught exception and crashes the hook. Fail soft:
+    // prewarm is a best-effort optimization, never required for a session.
+    _prewarm.on('error', (e) => {
+      teeStderr(`[session-start] prewarm spawn failed (non-fatal): ${(e && e.message) || e}\n`);
+    });
+    _prewarm.unref();
   } catch {}
 
   try {

package/hooks/shim-launcher.cjs

@@ -48,4 +48,18 @@ const child = spawnSync(shimPath, process.argv.slice(2), {
   windowsHide: true,
 });
 
-process.exit(child.status ?? 0);
+// spawnSync reports a failure to even START the child (EACCES on a non-exec
+// bit, ENOEXEC on a corrupt/foreign binary, etc.) via child.error, and leaves
+// child.status === null. The old `child.status ?? 0` collapsed that null to a
+// SUCCESS exit code, masking a broken shim as a clean run. Surface it instead.
+if (child.error) {
+  process.stderr.write(`[mixdog-shim] failed to launch ${shimPath}: ${child.error.message}\n`);
+  process.exit(126); // 126 = command found but not executable / could not run
+}
+if (child.status === null) {
+  // No error object but no exit code either: the child was killed by a signal
+  // (child.signal set) or otherwise terminated abnormally. Report non-zero.
+  process.stderr.write(`[mixdog-shim] ${shimPath} terminated abnormally${child.signal ? ` (signal ${child.signal})` : ''}\n`);
+  process.exit(1);
+}
+process.exit(child.status);

package/lib/keychain-cjs.cjs

@@ -6,7 +6,19 @@ const fs = require('fs');
 const { resolvePluginData } = require('./plugin-paths.cjs');
 
 const SERVICE = 'mixdog';
-const POWERSHELL_TIMEOUT_MS = Number(process.env.MIXDOG_KEYCHAIN_TIMEOUT_MS || 15000);
+// Shared bound for every synchronous keychain backend (DPAPI/PowerShell on
+// Windows, security(1) on macOS). A single env override keeps them consistent.
+const KEYCHAIN_TIMEOUT_MS = Number(process.env.MIXDOG_KEYCHAIN_TIMEOUT_MS || 15000);
+const POWERSHELL_TIMEOUT_MS = KEYCHAIN_TIMEOUT_MS;
+
+// CommonJS module: cannot import the ESM src/shared/wsl.mjs, so inline an
+// equivalent WSL check (process.platform reports 'linux' inside WSL).
+function isWSL() {
+    if (process.platform !== 'linux') return false;
+    if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) return true;
+    try { return /microsoft|wsl/i.test(fs.readFileSync('/proc/version', 'utf8')); }
+    catch { return false; }
+}
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -81,19 +93,30 @@ function dpApiFile(account) {
 // darwin — security(1)
 // ---------------------------------------------------------------------------
 
+// Bound security(1) calls so a stuck Keychain prompt (locked keychain, GUI
+// unlock dialog with no display) cannot block hook/server callers forever —
+// matching the Windows DPAPI and Linux keytar timeouts.
+function darwinRun(args) {
+    const r = run('security', args, { timeout: KEYCHAIN_TIMEOUT_MS });
+    if (r.error && r.error.code === 'ETIMEDOUT') {
+        throw new Error(`[keychain] security command timed out after ${KEYCHAIN_TIMEOUT_MS}ms`);
+    }
+    return r;
+}
+
 function darwinGet(account) {
-    const r = run('security', ['find-generic-password', '-a', account, '-s', SERVICE, '-w']);
+    const r = darwinRun(['find-generic-password', '-a', account, '-s', SERVICE, '-w']);
     if (r.status !== 0) return null;
     return r.stdout.trimEnd();
 }
 
 function darwinSet(account, value) {
-    const r = run('security', ['add-generic-password', '-a', account, '-s', SERVICE, '-w', value, '-U']);
+    const r = darwinRun(['add-generic-password', '-a', account, '-s', SERVICE, '-w', value, '-U']);
     if (r.status !== 0) throw new Error(`[keychain] security set failed: ${r.stderr || r.stdout}`);
 }
 
 function darwinDelete(account) {
-    const r = run('security', ['delete-generic-password', '-a', account, '-s', SERVICE]);
+    const r = darwinRun(['delete-generic-password', '-a', account, '-s', SERVICE]);
     if (r.status !== 0) throw new Error(`[keychain] security delete failed: ${r.stderr || r.stdout}`);
 }
 
@@ -112,7 +135,11 @@ function loadKeytar() {
         throw new Error(
             '[keychain] keytar is not installed — run: npm install keytar\n' +
             '  Requires libsecret-dev (Debian/Ubuntu) or libsecret (other distros).\n' +
-            '  Cannot access credentials on this platform without it.'
+            '  Cannot access credentials on this platform without it.' +
+            (isWSL()
+                ? '\n  Detected WSL: there is usually no Secret Service here; ' +
+                  'set the relevant MIXDOG_*/PROVIDER_API_KEY env var instead.'
+                : '')
         );
     }
     return _keytarMod;

package/lib/plugin-paths.cjs

@@ -29,6 +29,14 @@ const fs = require('fs');
 const DEFAULT_PLUGIN = 'mixdog';
 const DEFAULT_MARKETPLACE = 'trib-plugin';
 
+// Claude config base — honours CLAUDE_CONFIG_DIR when set, otherwise the
+// real Claude Code default of ~/.claude (matches settings-loader.cjs,
+// statusline, doctor, install). Only ADDS the env override; never relocates
+// the default base.
+function claudeConfigBase() {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
 function readPluginManifestName(root) {
   try {
     const manifest = JSON.parse(fs.readFileSync(path.join(root, '.claude-plugin', 'plugin.json'), 'utf8'));
@@ -46,14 +54,14 @@ function resolvePluginData() {
     if (/^\d+\.\d+\.\d+/.test(dirName)) {
       const pluginName = path.basename(path.join(root, '..'));
       const marketplace = path.basename(path.join(root, '..', '..'));
-      return path.join(os.homedir(), '.claude', 'plugins', 'data', `${pluginName}-${marketplace}`);
+      return path.join(claudeConfigBase(), 'plugins', 'data', `${pluginName}-${marketplace}`);
     }
     // Marketplace layout: .../marketplaces/{marketplace}/
     // The root dir itself is the marketplace. Plugin name lives in the
     // manifest; fall back to DEFAULT_PLUGIN when it's unreadable.
     const marketplace = dirName;
     const pluginName = readPluginManifestName(root);
-    return path.join(os.homedir(), '.claude', 'plugins', 'data', `${pluginName}-${marketplace}`);
+    return path.join(claudeConfigBase(), 'plugins', 'data', `${pluginName}-${marketplace}`);
   }
   throw new Error('[plugin-paths] CLAUDE_PLUGIN_DATA and CLAUDE_PLUGIN_ROOT are both unset — cannot resolve plugin data dir outside of Claude Code.');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.7.15",
+  "version": "0.7.17",
   "description": "Claude Code all-in-one bridge plugin: role-based bridge workers, continuous memory, and syntax-aware code editing.",
   "author": "mixdog contributors <dev@tribgames.com>",
   "license": "MIT",

package/setup/launch-core.mjs

@@ -157,6 +157,47 @@ function releaseLaunchLock() {
   try { unlinkSync(LAUNCH_LOCK_PATH); } catch {}
 }
 
+// POSIX listener-pid resolution with graceful degradation across minimal
+// images. Tries lsof → ss → fuser; returns the first listener pid found, or
+// null if none of the tools exist / none report a listener. A missing tool
+// throws ENOENT from execSync, which we swallow and move to the next probe so
+// a bare container without lsof does not wedge port reclaim.
+function resolveListenerPidPosix(trace) {
+  // lsof: -ti prints bare pids, -sTCP:LISTEN restricts to the listening socket.
+  try {
+    const out = execSync(`lsof -ti :${PORT} -sTCP:LISTEN`, { encoding: 'utf8', timeout: 3000 }).trim();
+    const n = parseInt(out.split('\n')[0], 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  } catch (e) {
+    if (trace) trace(`reclaimPort: lsof unavailable/failed (${e?.code || e?.message || e}) → trying ss`);
+  }
+  // ss (iproute2): -H no header, -l listening, -t tcp, -n numeric, -p process.
+  // The pid lives in the trailing `users:(("name",pid=1234,fd=7))` field.
+  try {
+    const out = execSync(`ss -Hltnp 'sport = :${PORT}'`, { encoding: 'utf8', timeout: 3000 }).trim();
+    const m = out.match(/pid=(\d+)/);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (Number.isFinite(n) && n > 0) return n;
+    }
+  } catch (e) {
+    if (trace) trace(`reclaimPort: ss unavailable/failed (${e?.code || e?.message || e}) → trying fuser`);
+  }
+  // fuser: prints the pids holding the tcp port to stdout (diagnostics on
+  // stderr). Take the first numeric token.
+  try {
+    const out = execSync(`fuser ${PORT}/tcp 2>/dev/null`, { encoding: 'utf8', timeout: 3000 }).trim();
+    const m = out.match(/\d+/);
+    if (m) {
+      const n = parseInt(m[0], 10);
+      if (Number.isFinite(n) && n > 0) return n;
+    }
+  } catch (e) {
+    if (trace) trace(`reclaimPort: fuser unavailable/failed (${e?.code || e?.message || e}) → no listener pid resolved`);
+  }
+  return null;
+}
+
 // Reclaim PORT from a version-mismatched setup-server: resolve the LISTENER
 // pid, kill it (tree on win32, process-group on unix), wait for the port to
 // free, then spawn the current-version server window-free. Throws LaunchError
@@ -179,9 +220,12 @@ async function reclaimPort(pluginRoot, pluginData, remoteRoot, trace) {
       const n = parseInt(out, 10);
       if (Number.isFinite(n) && n > 0) stalePid = n;
     } else {
-      const out = execSync(`lsof -ti :${PORT} -sTCP:LISTEN`, { encoding: 'utf8', timeout: 3000 }).trim();
-      const n = parseInt(out.split('\n')[0], 10);
-      if (Number.isFinite(n) && n > 0) stalePid = n;
+      // Resolve the LISTENER pid. lsof is the primary tool, but minimal
+      // Linux/WSL/container images often ship without it — falling back to
+      // ss (iproute2) then fuser keeps port reclaim working there instead
+      // of wedging on a missing-binary ENOENT. Each probe is independent and
+      // best-effort; the first that yields a pid wins.
+      stalePid = resolveListenerPidPosix(trace);
     }
   } catch (e) { pidResolveError = e; }
   if (stalePid !== null) {

package/setup/locate-claude.mjs

@@ -1,16 +1,34 @@
 // locate-claude.mjs — shared PATH scan for the Claude Code CLI executable.
 
 import { execFileSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, statSync, accessSync, constants as fsConstants } from 'node:fs';
 import { join } from 'node:path';
 
+// POSIX: a PATH match is only a real candidate if it is a regular file the
+// current user may EXECUTE. existsSync alone would return a non-exec data file
+// (e.g. a `claude` config/dir or a 0644 stray) and the caller would then fail
+// to spawn it. On win32 executability is governed by PATHEXT, not a mode bit,
+// so existence is the right test there.
+function isUsable(p) {
+  const win32 = process.platform === 'win32';
+  try {
+    if (!existsSync(p)) return false;
+    if (win32) return true;
+    if (!statSync(p).isFile()) return false;
+    accessSync(p, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function resolveClaudeExecutable() {
   const win32 = process.platform === 'win32';
   try {
     const cmd = win32 ? 'where' : 'which';
     const out = execFileSync(cmd, ['claude'], { encoding: 'utf8', windowsHide: true }).trim();
     const first = out.split(/\r?\n/).map((l) => l.trim()).find(Boolean);
-    if (first && existsSync(first)) return first;
+    if (first && isUsable(first)) return first;
   } catch { /* PATH scan */ }
 
   const pathSep = win32 ? ';' : ':';
@@ -30,9 +48,9 @@ export function resolveClaudeExecutable() {
         if (existsSync(bare)) return bare;
       } else {
         const candidate = join(dir, base);
-        if (existsSync(candidate)) return candidate;
+        if (isUsable(candidate)) return candidate;
       }
     }
   }
   return null;
-}
+}

package/setup/setup-server.mjs

@@ -19,6 +19,7 @@ import { readSection, writeSection, updateSection, saveSecret, deleteSecret, has
 import { applyDefaults as applyChannelsDefaults } from '../src/channels/lib/config.mjs';
 import { validateCronExpression } from '../src/channels/lib/scheduler.mjs';
 import { mergeAgentConfig, mergeMemoryConfig, mergeSearchConfig, mergeConfig, mergeEndpointConfig, mergeWebhookEndpointConfig } from './config-merge.mjs';
+import { isWSL } from '../src/shared/wsl.mjs';
 
 // C2 — Origin/Referer guard for mutating routes.
 // Returns true when the request is safe to handle (same-origin loopback UI,
@@ -1465,6 +1466,27 @@ async function openAppWindowSequence() {
     return { ...macResult, method: 'macOS open', attempts: [macAttempt] };
   }
 
+  // WSL: process.platform is 'linux' but xdg-open targets a (usually absent)
+  // Linux GUI. Reach the Windows-HOST browser instead, mirroring open-url.mjs:
+  // prefer wslview (wslu), then PowerShell Start-Process (cmd.exe is avoided —
+  // see the note below). Each is a sync spawn through trySyncOpen so a missing
+  // opener advances to the next.
+  if (isWSL()) {
+    if (trySyncOpen('wslview', 'wslview', [appUrl], attempts)) {
+      return { ok: true, method: 'wslview', attempts };
+    }
+    // cmd.exe `start` is intentionally NOT used: cmd re-parses URL
+    // metacharacters, so a query-string `&` is treated as a command separator
+    // and the URL truncates. Start-Process takes the URL as a single argument
+    // and does not reparse `&`; quotePowerShellString single-quotes the URL
+    // (doubling embedded quotes) so it is injection-safe.
+    const wslPsCommand = `Start-Process -FilePath ${quotePowerShellString(appUrl)}`;
+    if (trySyncOpen('PowerShell Start-Process', 'powershell.exe', ['-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-Command', wslPsCommand], attempts)) {
+      return { ok: true, method: 'PowerShell Start-Process', attempts };
+    }
+    return { ok: false, error: 'Failed to open Windows browser from WSL', attempts };
+  }
+
   const xdgResult = await new Promise(resolve => {
     const child = spawn('xdg-open', [appUrl], { stdio: 'ignore' });
     let timer = setTimeout(() => {

package/setup/setup.html

@@ -1310,7 +1310,7 @@
               <span style="font-size:11px;color:var(--text-3)">Description</span>
               <span class="file-open" onclick="wfOpenDescription()">Open</span>
             </div>
-            <textarea id="wf-description" class="r-input" placeholder="Free-form workflow description (markdown)." style="width:100%;height:150px;resize:vertical;font-family:inherit;padding:10px;line-height:1.5"></textarea>
+            <textarea id="wf-description" class="r-input" placeholder="Free-form workflow description (markdown)." style="width:100%;height:330px;resize:vertical;font-family:inherit;padding:10px;line-height:1.5"></textarea>
           </div>
           <div class="r r-opt">
             <div class="opt-body" style="width:100%">

package/src/agent/orchestrator/tools/builtin/path-utils.mjs

@@ -1,6 +1,7 @@
 import { homedir } from 'os';
 import { isAbsolute, relative, resolve } from 'path';
 import { realpathSync } from 'node:fs';
+import { isWSL } from '../../../../shared/wsl.mjs';
 
 // Restore the on-disk casing of a path (win32 only). rg relativizes candidate
 // paths against its process cwd with a CASE-SENSITIVE prefix strip before
@@ -28,6 +29,21 @@ export function posixPathToWindowsPath(posixPath) {
     return posixPath;
 }
 
+// Reverse of posixPathToWindowsPath, for WSL: a Windows-HOST drive path that
+// arrives from the host (e.g. `C:\Users\x` or `C:/Users/x`) is unreachable as
+// a literal under WSL — the drive surfaces at `/mnt/<letter>/...`. Map
+// `<drive>:` → `/mnt/<lowercase-drive>` and flip backslashes to slashes. Only
+// drive-letter paths are touched; anything else is returned unchanged.
+export function windowsPathToPosixPath(winPath) {
+    if (typeof winPath !== 'string') return winPath;
+    const m = winPath.match(/^([a-zA-Z]):[\\/](.*)$/);
+    if (m) return `/mnt/${m[1].toLowerCase()}/${m[2].replace(/\\/g, '/')}`;
+    // Bare `C:` with no separator → drive root.
+    const root = winPath.match(/^([a-zA-Z]):$/);
+    if (root) return `/mnt/${root[1].toLowerCase()}/`;
+    return winPath;
+}
+
 export function normalizeInputPath(p) {
     if (typeof p !== 'string') return p;
     // Trim leading/trailing whitespace — LLMs intermittently emit paths with
@@ -49,6 +65,13 @@ export function normalizeInputPath(p) {
         if (looksPosixDrive || looksCygdrive || looksWsl || looksUnc) {
             out = posixPathToWindowsPath(out);
         }
+    } else if (isWSL()) {
+        // Reverse direction: a Windows-style drive path from the host maps to
+        // the /mnt/<letter> mount. Native-Linux behavior is untouched (gated
+        // on isWSL()); a path already in /mnt/... POSIX form is left as-is.
+        if (/^[a-zA-Z]:([\\/]|$)/.test(out)) {
+            out = windowsPathToPosixPath(out);
+        }
     }
     try { out = out.normalize('NFC'); } catch {}
     return out;

package/src/agent/orchestrator/tools/builtin/shell-jobs.mjs

@@ -712,7 +712,11 @@ export function adoptForegroundShellJob({ command, cwd, pid, timeoutMs, mergeStd
 }
 
 function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellType, clientHostPid }) {
-    if (process.platform === 'win32' && isPowerShellShell(shell, shellType)) {
+    // Route ANY PowerShell shell to the PS wrapper, regardless of platform.
+    // Gating on win32 sent shell:'powershell' on macOS/Linux down the POSIX
+    // path below, which spawns `pwsh <wrapper>.sh` — pwsh then tries to run a
+    // bash script. isPowerShellShell already matches pwsh/powershell by stem.
+    if (isPowerShellShell(shell, shellType)) {
         return startBackgroundPowerShellJob({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, clientHostPid });
     }
 
@@ -738,9 +742,11 @@ function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr
     // only the setTimeout below enforced; a mixdog restart between spawn
     // and deadline would orphan the runaway. --preserve-status keeps the
     // user command's exit code on success; on timeout the wrapper exits 124.
-    // `timeout` ships with GNU coreutils on Linux and brew coreutils on
-    // macOS; absent platforms fall through to the inner
-    // command (the parent setTimeout still calls refreshShellJob to clean up).
+    // `timeout` ships with GNU coreutils on Linux. On macOS, Homebrew
+    // coreutils installs it as `gtimeout` (the un-prefixed name is NOT created
+    // by default), so the wrapper picks `timeout` if present else `gtimeout`.
+    // When neither exists it falls through to the inner command (the parent
+    // setTimeout still calls refreshShellJob to clean up).
     const userCmdQuoted = shellQuoteSingle(command);
     // P2 fix: invoke the resolved shell (not bash -c) so zsh / dash /
     // alternate shells run snapshot-aware commands correctly. Drop
@@ -762,7 +768,7 @@ function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr
     // status for processes that actually exited 0. `rm -- "$0"` removes
     // the staged wrapper .cmd.sh after donePath is published so a host
     // crash before this point still leaves the file for the sweep to GC.
-    const wrapped = `{ if command -v timeout >/dev/null 2>&1; then touch ${shellQuoteSingle(enforcedPath)}; timeout ${timeoutSeconds} ${innerShellQ} ${innerArgQ} ${userCmdQuoted}; else ${innerShellQ} ${innerArgQ} ${userCmdQuoted}; fi; rc=$?; printf '%s' "$rc" > ${shellQuoteSingle(exitPath)}; touch ${shellQuoteSingle(donePath)}; rm -- "$0" 2>/dev/null; exit $rc; }`;
+    const wrapped = `{ if command -v timeout >/dev/null 2>&1; then _to=timeout; elif command -v gtimeout >/dev/null 2>&1; then _to=gtimeout; else _to=; fi; if [ -n "$_to" ]; then touch ${shellQuoteSingle(enforcedPath)}; "$_to" ${timeoutSeconds} ${innerShellQ} ${innerArgQ} ${userCmdQuoted}; else ${innerShellQ} ${innerArgQ} ${userCmdQuoted}; fi; rc=$?; printf '%s' "$rc" > ${shellQuoteSingle(exitPath)}; touch ${shellQuoteSingle(donePath)}; rm -- "$0" 2>/dev/null; exit $rc; }`;
     // Stage the wrapped command to a .sh and let the script open its own
     // output files via `exec > … 2> …`. The parent does NOT pass file
     // descriptors via stdio inheritance (`stdio: 'ignore'` for all three).
@@ -841,9 +847,24 @@ function startBackgroundPowerShellJob({ command, timeoutMs, workDir, mergeStderr
         '$code = 1',
         'try {',
         "    $argList = @('-NoLogo', '-NoProfile', '-NonInteractive', '-EncodedCommand', $encoded)",
-        '    $p = Start-Process -FilePath $exe -ArgumentList $argList -RedirectStandardOutput $stdoutPath -RedirectStandardError $stderrPath -WindowStyle Hidden -PassThru',
+        // -WindowStyle is a Windows-only Start-Process parameter; pwsh on
+        // macOS/Linux throws "not supported on this platform". Add it only on win32.
+        '    $spArgs = @{ FilePath = $exe; ArgumentList = $argList; RedirectStandardOutput = $stdoutPath; RedirectStandardError = $stderrPath; PassThru = $true }',
+        '    if ($IsWindows -or $null -eq $IsWindows) { $spArgs[\'WindowStyle\'] = \'Hidden\' }',
+        '    $p = Start-Process @spArgs',
         '    if ($timeoutMs -gt 0 -and -not $p.WaitForExit($timeoutMs)) {',
-        '        try { Stop-Process -Id $p.Id -Force -ErrorAction SilentlyContinue } catch {}',
+        // Kill the whole process TREE, not just the direct child: Start-Process
+        // launches an intermediate pwsh that spawns the user command, so
+        // Stop-Process on $p.Id alone orphans the grandchildren. On Windows use
+        // `taskkill /T /F` (tree-terminate); on macOS/Linux pwsh, fall back to
+        // Stop-Process (no taskkill there).
+        '        try {',
+        '            if ($IsWindows -or $null -eq $IsWindows) {',
+        '                & taskkill.exe /pid $p.Id /t /f 2>$null | Out-Null',
+        '            } else {',
+        '                try { Stop-Process -Id $p.Id -Force -ErrorAction SilentlyContinue } catch {}',
+        '            }',
+        '        } catch {}',
         '        $code = 124',
         '    } else {',
         '        try { $p.WaitForExit() } catch {}',
@@ -875,9 +896,14 @@ function startBackgroundPowerShellJob({ command, timeoutMs, workDir, mergeStderr
     }
 
     const shellStem = basename(String(shell || '')).toLowerCase().replace(/\.exe$/, '');
-    const wrapperArgs = shellStem === 'powershell'
-        ? ['-NoLogo', '-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-ExecutionPolicy', 'Bypass', '-File', wrappedTempPath]
-        : ['-NoLogo', '-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-File', wrappedTempPath];
+    // `-WindowStyle Hidden` is a Windows-only CLI switch; pwsh on macOS/Linux
+    // rejects it. `-ExecutionPolicy` likewise only applies to Windows
+    // PowerShell. Build args per-platform so cross-OS pwsh background jobs run.
+    const isWin = process.platform === 'win32';
+    const wrapperArgs = ['-NoLogo', '-NoProfile', '-NonInteractive'];
+    if (isWin) wrapperArgs.push('-WindowStyle', 'Hidden');
+    if (isWin && shellStem === 'powershell') wrapperArgs.push('-ExecutionPolicy', 'Bypass');
+    wrapperArgs.push('-File', wrappedTempPath);
     // Spawn the staged wrapper directly. detached MUST be false on Windows:
     // a native pwsh launched with detached:true + stdio:'ignore' exits
     // immediately without running -File (verified — the detached child dies

package/src/agent/orchestrator/tools/builtin/shell-runtime.mjs

@@ -19,10 +19,15 @@ function shellTypeFor(shell) {
 
 function shellSpec(shell, shellType = shellTypeFor(shell)) {
     if (shellType === 'powershell') {
+        // `-WindowStyle Hidden` is a Windows-only switch. PowerShell Core
+        // (pwsh) on macOS/Linux rejects it, so only append it on win32.
+        const psArgs = ['-NoLogo', '-NoProfile', '-NonInteractive'];
+        if (process.platform === 'win32') psArgs.push('-WindowStyle', 'Hidden');
+        psArgs.push('-Command');
         return {
             shell,
             shellArg: '-Command',
-            shellArgs: ['-NoLogo', '-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-Command'],
+            shellArgs: psArgs,
             shellType,
         };
     }
@@ -60,8 +65,10 @@ function resolveWindowsPowerShell() {
 
 export function resolveShell() {
     if (_resolvedShell) return _resolvedShell;
-    const isWindows = process.platform === 'win32'
-        || !!(process.env.WINDIR || process.env.SystemRoot);
+    // Gate on the actual platform, NOT WINDIR/SystemRoot env presence: under
+    // WSL those vars can be inherited via interop while process.platform is
+    // 'linux', and WSL must resolve /bin/sh — not Windows PowerShell.
+    const isWindows = process.platform === 'win32';
     if (!isWindows) {
         _resolvedShell = shellSpec('/bin/sh', 'posix');
         return _resolvedShell;
@@ -76,7 +83,9 @@ export function resolveShell() {
 }
 
 function _isWindows() {
-    return process.platform === 'win32' || !!(process.env.WINDIR || process.env.SystemRoot);
+    // Real-platform check only (see resolveShell): env presence would make
+    // WSL (process.platform 'linux') mis-resolve to Windows Git Bash.
+    return process.platform === 'win32';
 }
 
 // Resolve Git Bash on Windows. Strategy (invariant-based, no silent fallback):

package/src/agent/orchestrator/tools/graph-binary-fetcher.mjs

@@ -118,7 +118,17 @@ export function ensureGraphBinary(dataDir) {
     const pkey = platformKey();
     const asset = manifest.assets?.[pkey];
     if (!asset || !asset.url || !asset.sha256) {
-      throw new Error(`[graph-fetcher] no prebuilt mixdog-graph asset for platform ${pkey}`);
+      // Unsupported platform/arch (e.g. win32-arm64): the manifest has no
+      // downloadable asset for this {os}-{arch}. The code graph has NO JS
+      // parsing fallback, so this is terminal — surface a single clear,
+      // actionable message instead of a cryptic crash downstream.
+      const supported = Object.keys(manifest.assets || {}).join(', ') || '(none)';
+      throw new Error(
+        `[graph-fetcher] no prebuilt mixdog-graph binary for platform ${pkey} `
+        + `(unsupported platform/arch — there is no JS parsing fallback). `
+        + `Supported platforms: ${supported}. `
+        + `Build it locally: cargo build --release in native/mixdog-graph.`,
+      );
     }
     const version = String(manifest.version || '0');
     const dir = graphBinDir(dataDir);

package/src/agent/orchestrator/tools/graph-manifest.json

@@ -1,26 +1,26 @@
 {
-  "version": "0.7.15",
+  "version": "0.7.17",
   "_comment": "Rewritten by .github/workflows/graph-release.yml on each tagged release. assets maps platformKey (process.platform-process.arch, e.g. win32-x64, linux-x64, darwin-arm64) to { url, sha256 } of the mixdog-graph binary on the GitHub release. A local cargo build under native/mixdog-graph/target/release always takes precedence at runtime. (v0.5.236 entries were filled manually after CI's commit step hit detached HEAD; the workflow now checks out ref: main so future releases self-update.)",
   "assets": {
     "darwin-arm64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.15/mixdog-graph-darwin-arm64",
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-graph-darwin-arm64",
       "sha256": "53f45f8373000fb55ccb49f9b03af0275ca2a663f924b68ee8ded4535e14445a"
     },
     "darwin-x64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.15/mixdog-graph-darwin-x64",
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-graph-darwin-x64",
       "sha256": "347dc5e1b39dfc33ae07e01319b085c1f1ee775a70be1ac09f7b0d2954b36591"
     },
     "linux-arm64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.15/mixdog-graph-linux-arm64",
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-graph-linux-arm64",
       "sha256": "7648be2c4bc89bef837b4843639a9ab38c382ba103518ad52d4439587521542f"
     },
     "linux-x64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.15/mixdog-graph-linux-x64",
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-graph-linux-x64",
       "sha256": "6e5a1b548c69c3a51170eb11c769985be7ca7029ede2597b19304c8dc106eded"
     },
     "win32-x64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.15/mixdog-graph-win32-x64.exe",
-      "sha256": "e2933fcf6ad0d7ab517c0beda4f8c7258638602bca73170dbda2cd8311c8637f"
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-graph-win32-x64.exe",
+      "sha256": "cd263b6bfd3d7371857f498fb53d1d67b4b4cc06dd4d9855408337390a56cee2"
     }
   }
 }

package/src/agent/orchestrator/tools/patch-binary-fetcher.mjs

@@ -107,7 +107,17 @@ export function ensurePatchBinary(dataDir) {
     const pkey = platformKey();
     const asset = manifest.assets?.[pkey];
     if (!asset || !asset.url || !asset.sha256) {
-      throw new Error(`[patch-fetcher] no prebuilt mixdog-patch asset for platform ${pkey}`);
+      // Unsupported platform/arch (e.g. win32-arm64): the manifest has no
+      // downloadable asset for this {os}-{arch}. apply_patch is native-only
+      // (no JS apply fallback), so this is terminal — surface a single clear,
+      // actionable message instead of a cryptic crash downstream.
+      const supported = Object.keys(manifest.assets || {}).join(', ') || '(none)';
+      throw new Error(
+        `[patch-fetcher] no prebuilt mixdog-patch binary for platform ${pkey} `
+        + `(unsupported platform/arch — apply_patch is native-only, no JS apply fallback). `
+        + `Supported platforms: ${supported}. `
+        + `Build it locally: cargo build --release in native/mixdog-patch.`,
+      );
     }
     const version = String(manifest.version || '0');
     const dir = patchBinDir(dataDir);

package/src/agent/orchestrator/tools/patch-manifest.json

@@ -1,26 +1,26 @@
 {
-  "version": "0.7.15",
+  "version": "0.7.17",
   "_comment": "Rewritten by .github/workflows/patch-release.yml on each tagged release. assets maps platformKey (process.platform-process.arch, e.g. win32-x64, linux-x64, darwin-arm64) to { url, sha256 } of the mixdog-patch binary on the GitHub release. A local cargo build under native/mixdog-patch/target/release always takes precedence; otherwise the binary is fetched per this manifest into the data dir (apply is native-only — no JS apply engine).",
   "assets": {
     "darwin-arm64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.15/mixdog-patch-darwin-arm64",
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-patch-darwin-arm64",
       "sha256": "836a0b60a443b0a6a8c1bbe24d15a79ed70ee92c2f0fbc05374c4e9ed2536415"
     },
     "darwin-x64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.15/mixdog-patch-darwin-x64",
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-patch-darwin-x64",
       "sha256": "cab10c4e1e8b72d3958241dffdff764712ed74f4861d105bafa8258961215c98"
     },
     "linux-arm64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.15/mixdog-patch-linux-arm64",
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-patch-linux-arm64",
       "sha256": "a90c32ce3417a7d853f2723f82f3613cf2cd030fe885cf710cfc9f8e4b193264"
     },
     "linux-x64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.15/mixdog-patch-linux-x64",
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-patch-linux-x64",
       "sha256": "0fea40ab98acd35bfb47515756024d1882a2abbaddce8a0b51642d20ac405577"
     },
     "win32-x64": {
-      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.15/mixdog-patch-win32-x64.exe",
-      "sha256": "bc57bc029667bd62ce3798b4bfe23a42e4278148a6bbb778236769b3713397d8"
+      "url": "https://github.com/trib-plugin/mixdog/releases/download/v0.7.17/mixdog-patch-win32-x64.exe",
+      "sha256": "af92ae25c2434f9b2999df0186e11f6a8802d70bcbc4b91290cfd92f3e143466"
     }
   }
 }

package/src/channels/lib/executor.mjs

@@ -130,30 +130,65 @@ function runScript(name, scriptName, onResult) {
     return;
   }
   const ext = extname(scriptName).toLowerCase();
-  const cmd = ext === ".py" ? "python3" : "node";
-  const proc = spawn(cmd, [scriptPath], {
-    timeout: 3e4,
-    env: { ...process.env },
-    windowsHide: true
-  });
-  let stdout = "";
-  let stderr = "";
-  if (proc.stdout) proc.stdout.on("data", (d) => {
-    stdout += d;
-  });
-  if (proc.stderr) proc.stderr.on("data", (d) => {
-    stderr += d;
-  });
-  proc.on("close", (code) => {
-    if (code !== 0) {
-      logEvent(`${name}: script exited ${code}: ${stderr.substring(0, 500)}`);
-    }
-    onResult(stdout.substring(0, 2e3), code);
-  });
-  proc.on("error", (err) => {
-    logEvent(`${name}: script spawn error: ${err.message}`);
-    onResult("", null);
-  });
+  // Pick interpreter candidates. `python3` does not exist on a default
+  // Windows install — the Python launcher `py` (and often `python`) does —
+  // so on win32 try py → python → python3, falling through on ENOENT.
+  // POSIX keeps python3 → python.
+  let candidates;
+  if (ext === ".py") {
+    candidates = process.platform === "win32"
+      ? ["py", "python", "python3"]
+      : ["python3", "python"];
+  } else {
+    candidates = ["node"];
+  }
+  // onResult MUST fire exactly once across the whole candidate chain. A failed
+  // ENOENT spawn emits BOTH 'error' (→ we advance) AND 'close', so guard the
+  // final callback at the chain level and mark each attempt that advanced so
+  // its own 'close' is ignored.
+  let resultSent = false;
+  const finish = (out, code) => {
+    if (resultSent) return;
+    resultSent = true;
+    onResult(out, code);
+  };
+  const trySpawn = (idx) => {
+    const cmd = candidates[idx];
+    let advanced = false;
+    const proc = spawn(cmd, [scriptPath], {
+      timeout: 3e4,
+      env: { ...process.env },
+      windowsHide: true
+    });
+    let stdout = "";
+    let stderr = "";
+    if (proc.stdout) proc.stdout.on("data", (d) => {
+      stdout += d;
+    });
+    if (proc.stderr) proc.stderr.on("data", (d) => {
+      stderr += d;
+    });
+    proc.on("close", (code) => {
+      // This attempt ENOENT'd and handed off to the next candidate — its
+      // 'close' is spurious and must not report a result.
+      if (advanced) return;
+      if (code !== 0) {
+        logEvent(`${name}: script exited ${code}: ${stderr.substring(0, 500)}`);
+      }
+      finish(stdout.substring(0, 2e3), code);
+    });
+    proc.on("error", (err) => {
+      // Interpreter not found → try the next candidate before giving up.
+      if (err.code === "ENOENT" && idx + 1 < candidates.length) {
+        advanced = true;
+        trySpawn(idx + 1);
+        return;
+      }
+      logEvent(`${name}: script spawn error: ${err.message}`);
+      finish("", null);
+    });
+  };
+  trySpawn(0);
 }
 export {
   applyParser,

package/src/channels/lib/hook-pipe-server.mjs

@@ -35,7 +35,14 @@ const {
 // net.createServer().listen() accepts both transparently.
 const PIPE_PATH = moduleRequire('../../../lib/hook-pipe-path.cjs')()
 
-const RUNTIME_ROOT = join(tmpdir(), 'mixdog')
+// Honor MIXDOG_RUNTIME_ROOT consistently with runtime-paths.mjs (the consumer
+// of these tool-exec signals): when the override is set, the signal PRODUCER
+// here must write into the same root the channels worker watches, or signals
+// are silently dropped. Default stays tmpdir()/mixdog so non-override installs
+// are unchanged.
+const RUNTIME_ROOT = process.env.MIXDOG_RUNTIME_ROOT
+  ? pathResolve(process.env.MIXDOG_RUNTIME_ROOT)
+  : join(tmpdir(), 'mixdog')
 const SIGNAL_CONSUMER_MARKER = join(RUNTIME_ROOT, '.tool-exec-consumer')
 const SUBAGENT_SIGNAL_CONSUMER_MARKER = join(RUNTIME_ROOT, '.tool-exec-subagent-consumer')
 const SIGNAL_RE_GENERIC = /^tool-exec-\d+-[0-9a-f]+\.signal$/

package/src/memory/lib/runtime-fetcher.mjs

@@ -341,13 +341,29 @@ export async function ensureRuntime(dataDir) {
   const pkey     = platformKey()
   const asset    = manifest.assets?.[pkey]
   if (!asset) {
+    // Platform/arch absent from the manifest entirely (e.g. win32-arm64).
+    // The memory PG runtime cannot start here; fail with a single clear,
+    // actionable message. The memory worker's init().catch reports this as
+    // degraded and the rest of mixdog (agent, tools) keeps working without
+    // memory.
+    const supported = Object.keys(manifest.assets || {})
+      .filter((k) => isUsableAsset(manifest.assets[k]))
+      .join(', ') || '(none)'
     throw new Error(
-      `[runtime-fetcher] no asset for platform ${pkey} in manifest. ` +
-      `Available: ${Object.keys(manifest.assets || {}).join(', ')}`
+      `[runtime-fetcher] memory runtime not available on ${pkey}: ` +
+      `no runtime asset for this platform/arch in the manifest. ` +
+      `Supported: ${supported}. ` +
+      `Memory is disabled on this platform; the rest of mixdog continues to work.`
     )
   }
   if (!isUsableAsset(asset)) {
-    throw new Error(`unsupported platform/arch: no validated runtime asset for ${pkey}`)
+    // Platform/arch present but explicitly marked unsupported or carrying a
+    // placeholder/TBD payload (e.g. linux-arm64). Same graceful-degrade path.
+    throw new Error(
+      `[runtime-fetcher] memory runtime not available on ${pkey}: ` +
+      `this platform/arch is marked unsupported (no validated runtime asset). ` +
+      `Memory is disabled on this platform; the rest of mixdog continues to work.`
+    )
   }
 
   const { url, sha256, size } = asset

package/src/search/lib/web-tools.mjs

@@ -6,6 +6,7 @@ import { Agent, fetch as undiciFetch } from 'undici'
 import { JSDOM } from 'jsdom'
 import puppeteer from 'puppeteer-core'
 import { Readability } from '@mozilla/readability'
+import { isWSL } from '../../shared/wsl.mjs'
 
 
 const PKG_VERSION = (() => { try { return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version } catch { return '0.0.1' } })()
@@ -38,13 +39,24 @@ const COMMON_BROWSER_PATHS = (() => {
     ].filter(Boolean)
   }
   if (platform === 'linux') {
-    return [
+    // Native-Linux Chromium/Chrome binaries first. The /mnt/c Windows .exe
+    // entries are reachable from WSL's filesystem but puppeteer-core CANNOT
+    // drive a Windows GUI browser as a Linux child process (CDP over a pipe to
+    // a Win32 binary launched from the Linux ABI does not work), so advertising
+    // puppeteer-available off a Windows .exe yields launch failures at runtime.
+    // Only offer the Windows .exe fallbacks on plain Linux (Wine/dual-mount
+    // edge cases), never under WSL.
+    const linuxNative = [
       '/usr/bin/google-chrome',
       '/usr/bin/google-chrome-stable',
       '/usr/bin/chromium',
       '/usr/bin/chromium-browser',
       '/snap/bin/chromium',
       '/usr/bin/microsoft-edge',
+    ]
+    if (isWSL()) return linuxNative
+    return [
+      ...linuxNative,
       '/mnt/c/Program Files/Google/Chrome/Application/chrome.exe',
       '/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe',
       '/mnt/c/Program Files/Microsoft/Edge/Application/msedge.exe',

package/src/shared/config.mjs

@@ -334,7 +334,26 @@ export function getAgentApiKey(provider) {
  * Never writes to mixdog-config.json.
  */
 export function saveSecret(account, value) {
-  _setSecret(account, value)
+  try {
+    _setSecret(account, value)
+  } catch (err) {
+    // On WSL/headless Linux (and any host missing a usable keychain backend,
+    // e.g. keytar/libsecret not installed or no running Secret Service) the OS
+    // write throws a cryptic backend error. Surface an actionable message that
+    // points at the env-var read path the getters already honor, instead of
+    // silently writing the plaintext secret to mixdog-config.json.
+    const envKey = _envKey(account)
+    const agentMatch = String(account || '').match(/^agent\.([^.]+)\.apiKey$/)
+    const stdEnv = agentMatch ? AGENT_PROVIDER_ENV[agentMatch[1]] : null
+    const envHint = stdEnv ? `${stdEnv} (or ${envKey})` : envKey
+    const e = new Error(
+      `[config] could not save secret to the OS keychain: ${err && err.message ? err.message : err}\n` +
+      `  No usable keychain backend on this host (common on WSL / headless Linux without libsecret).\n` +
+      `  Set the ${envHint} environment variable instead — the runtime reads it directly.`
+    )
+    e.cause = err
+    throw e
+  }
 }
 
 export function deleteSecret(account) {

package/src/shared/open-url.mjs

@@ -1,4 +1,5 @@
 import { spawn } from 'child_process';
+import { isWSL } from './wsl.mjs';
 
 /**
  * Open a URL in the user's default browser. Best-effort and non-blocking —
@@ -11,27 +12,51 @@ import { spawn } from 'child_process';
  *    treats the first quoted string as the WINDOW TITLE, so the URL is dropped
  *    and nothing opens.
  *  - macOS: `open <url>`.
+ *  - WSL: xdg-open usually fails (no Linux GUI), so reach the Windows-HOST
+ *    browser — prefer `wslview` (wslu), else `powershell.exe Start-Process`.
+ *    cmd.exe `start` is deliberately NOT used: cmd re-parses URL metacharacters
+ *    so a query-string `&` (e.g. `?a=1&b=2`) is treated as a command separator
+ *    and the URL truncates. PowerShell's Start-Process takes the URL as one
+ *    argument and does not reparse `&`; the URL is passed inside a single-quoted
+ *    PowerShell literal (single quotes doubled) so `&`, spaces and quotes
+ *    survive and no injection is possible. Falls back through the chain when an
+ *    opener is missing.
  *  - Linux/other: `xdg-open <url>`.
  */
 export function openInBrowser(url) {
   const u = String(url);
-  let cmd;
-  let args;
+  // Ordered [cmd, args] candidates. Every platform but WSL has exactly one;
+  // WSL has a fallback chain since the first opener may be absent.
+  let candidates;
   if (process.platform === 'win32') {
-    cmd = 'rundll32';
-    args = ['url.dll,FileProtocolHandler', u];
+    candidates = [['rundll32', ['url.dll,FileProtocolHandler', u]]];
   } else if (process.platform === 'darwin') {
-    cmd = 'open';
-    args = [u];
+    candidates = [['open', [u]]];
+  } else if (isWSL()) {
+    // Single-quoted PowerShell literal: double any embedded single quote.
+    // Everything else (incl. `&`) is literal inside a single-quoted string.
+    const psUrl = `'${u.replace(/'/g, "''")}'`;
+    candidates = [
+      ['wslview', [u]],
+      ['powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `Start-Process -FilePath ${psUrl}`]],
+    ];
   } else {
-    cmd = 'xdg-open';
-    args = [u];
+    candidates = [['xdg-open', [u]]];
   }
+  tryOpenCandidates(candidates, 0);
+}
+
+// Spawn candidates[index]; on spawn error (opener missing) advance to the next.
+// Always non-blocking — the caller prints the URL, so exhausting the chain is
+// never fatal.
+function tryOpenCandidates(candidates, index) {
+  if (index >= candidates.length) return;
+  const [cmd, args] = candidates[index];
   try {
     const child = spawn(cmd, args, { stdio: 'ignore', detached: true, windowsHide: true });
-    child.on('error', () => { /* opener missing — user uses the printed URL */ });
+    child.on('error', () => { tryOpenCandidates(candidates, index + 1); });
     child.unref();
   } catch {
-    /* spawn threw synchronously — user opens the printed URL manually */
+    tryOpenCandidates(candidates, index + 1);
   }
 }

package/src/shared/user-cwd.mjs

@@ -54,8 +54,20 @@ export function _safeProcessCwd() {
 function _normalizePlatformCwd(p) {
   if (!p || typeof p !== 'string') return p
   if (process.platform !== 'win32') return resolve(p)
-  const m = p.match(/^[\/\\]([a-zA-Z])[\/\\](.*)$/)
-  const native = m ? `${m[1].toUpperCase()}:\\${m[2].replace(/\//g, '\\')}` : p
+  // Map all three POSIX drive-prefix shapes to native Windows paths before
+  // resolution, aligned with path-utils.mjs posixPathToWindowsPath:
+  //   /cygdrive/c/... (Cygwin), /mnt/c/... (WSL), /c/... (MSYS/Git-Bash) → C:\...
+  // Cygwin/WSL prefixes must be tested before the bare single-letter form
+  // because their slice offsets differ.
+  const cyg = p.match(/^\/cygdrive\/([a-zA-Z])\//)
+  const wsl = p.match(/^\/mnt\/([a-zA-Z])\//)
+  let native = p
+  if (cyg) native = `${cyg[1].toUpperCase()}:\\${p.slice(11).replace(/\//g, '\\')}`
+  else if (wsl) native = `${wsl[1].toUpperCase()}:\\${p.slice(7).replace(/\//g, '\\')}`
+  else {
+    const m = p.match(/^[\/\\]([a-zA-Z])[\/\\](.*)$/)
+    if (m) native = `${m[1].toUpperCase()}:\\${m[2].replace(/\//g, '\\')}`
+  }
   return resolve(native)
 }
 

package/src/shared/wsl.mjs

@@ -0,0 +1,35 @@
+// WSL (Windows Subsystem for Linux) detection.
+//
+// process.platform reports 'linux' inside WSL, so any caller that needs
+// Windows-HOST behavior — opening the Windows default browser, reaching the
+// Windows credential store, translating Windows drive paths — must branch on
+// this explicitly rather than on process.platform alone. Plain-Linux behavior
+// stays the default; this only flags the WSL special case.
+//
+// Detection order (cheapest / most reliable first):
+//   1. WSL_DISTRO_NAME / WSL_INTEROP env vars (set by the WSL init for every
+//      interactive and most non-interactive sessions).
+//   2. /proc/version containing "microsoft"/"wsl" (the kernel is a Microsoft
+//      build under WSL1/WSL2). Read once and memoized.
+import { readFileSync } from 'node:fs';
+
+let _isWSL;
+
+export function isWSL() {
+  if (_isWSL !== undefined) return _isWSL;
+  if (process.platform !== 'linux') {
+    _isWSL = false;
+    return _isWSL;
+  }
+  if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) {
+    _isWSL = true;
+    return _isWSL;
+  }
+  try {
+    const v = readFileSync('/proc/version', 'utf8').toLowerCase();
+    _isWSL = v.includes('microsoft') || v.includes('wsl');
+  } catch {
+    _isWSL = false;
+  }
+  return _isWSL;
+}