mixdog 0.7.14 → 0.7.16

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.7.14",
+  "version": "0.7.16",
   "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.14",
+  "version": "0.7.16",
   "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/config-merge.mjs

@@ -12,6 +12,7 @@ import {
   getSearchApiKey,
   getAgentApiKey,
   diagnoseDiscordTokenValue,
+  AGENT_PROVIDER_ENV,
 } from '../src/shared/config.mjs';
 
 const SUPPORTED_PROVIDERS = [
@@ -19,14 +20,6 @@ const SUPPORTED_PROVIDERS = [
   'tavily', 'firecrawl', 'exa',
 ];
 
-const AGENT_PROVIDER_ENV = Object.freeze({
-  openai: 'OPENAI_API_KEY',
-  anthropic: 'ANTHROPIC_API_KEY',
-  gemini: 'GEMINI_API_KEY',
-  deepseek: 'DEEPSEEK_API_KEY',
-  xai: 'XAI_API_KEY',
-});
-
 function envSecretPresent(account) {
   const key = 'MIXDOG_' + String(account || '').replace(/[.\s]+/g, '_').toUpperCase();
   if (process.env[key]) return true;

package/setup/launch-core.mjs

@@ -14,7 +14,7 @@
 // is derived inside launchConfigUi().
 
 import { spawn, execSync } from 'child_process';
-import { openSync, closeSync, readFileSync, writeSync, writeFileSync, appendFileSync } from 'fs';
+import { openSync, closeSync, readFileSync, writeSync, writeFileSync, appendFileSync, statSync, unlinkSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import http from 'http';
@@ -122,6 +122,154 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+// Cross-process launch mutex. Only ONE launcher runs the version-check →
+// reclaim critical section at a time. Now that prewarm takes over every
+// session, two concurrent session starts can both observe the same stale
+// server; without serialization the slower one kills the faster one's
+// freshly-spawned correct server. Exclusive-create lock file + stale-takeover
+// (a holder that crashed mid-launch leaves a lock no older than STALE_MS).
+// Best-effort: on timeout or an unexpected fs error we proceed lock-free
+// rather than deadlock the launcher.
+const LAUNCH_LOCK_PATH = join(tmpdir(), `mixdog-setup-launch-${PORT}.lock`);
+const LAUNCH_LOCK_STALE_MS = 30000;
+
+async function acquireLaunchLock(trace, timeoutMs = 20000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() <= deadline) {
+    try {
+      const fd = openSync(LAUNCH_LOCK_PATH, 'wx'); // exclusive create — EEXIST if held
+      writeSync(fd, `${process.pid} ${new Date().toISOString()}\n`);
+      closeSync(fd);
+      return true;
+    } catch (e) {
+      if (e?.code !== 'EEXIST') { trace(`launch-lock: unexpected ${e?.code || e} → proceeding lock-free`); return false; }
+      let stale = false;
+      try { stale = (Date.now() - statSync(LAUNCH_LOCK_PATH).mtimeMs) > LAUNCH_LOCK_STALE_MS; } catch {}
+      if (stale) { trace(`launch-lock: stale lock → reclaiming`); try { unlinkSync(LAUNCH_LOCK_PATH); } catch {} continue; }
+      await sleep(200);
+    }
+  }
+  trace(`launch-lock: wait timeout → proceeding lock-free`);
+  return false;
+}
+
+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
+// if the port cannot be reclaimed. Caller MUST hold the launch lock so two
+// launchers never race the kill+respawn.
+async function reclaimPort(pluginRoot, pluginData, remoteRoot, trace) {
+  let stalePid = null;
+  let pidResolveError = null;
+  let killError = null;
+  try {
+    if (process.platform === 'win32') {
+      // -State Listen is REQUIRED: Get-NetTCPConnection -LocalPort returns the
+      // LISTENING socket AND every ESTABLISHED/TIME_WAIT connection to it, so a
+      // bare `-First 1` can resolve a client/proxy PID (or 0) instead of the
+      // server — taskkill then misses the real owner and the port never frees.
+      const out = execSync(
+        `powershell -NoProfile -Command "(Get-NetTCPConnection -LocalPort ${PORT} -State Listen -ErrorAction SilentlyContinue | Select-Object -First 1).OwningProcess"`,
+        { encoding: 'utf8', timeout: 3000, windowsHide: true },
+      ).trim();
+      const n = parseInt(out, 10);
+      if (Number.isFinite(n) && n > 0) stalePid = n;
+    } else {
+      // 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) {
+    try {
+      if (process.platform === 'win32') {
+        // /T kills the whole process tree — the setup-server spawns child
+        // browser/server descendants that survive a PID-only Stop-Process.
+        execSync(`taskkill /T /F /PID ${stalePid}`, { timeout: 3000, windowsHide: true });
+      } else {
+        // Detached setup-server is its own process-group leader; the negative
+        // PID signals the group, reaping descendants a bare kill would orphan.
+        try { execSync(`kill -KILL -${stalePid}`, { timeout: 3000 }); }
+        catch { execSync(`kill -KILL ${stalePid}`, { timeout: 3000 }); }
+      }
+    } catch (e) { killError = e; }
+  }
+  // Poll until the port stops answering (250ms ticks, 5000ms deadline — a hair
+  // longer than the kill's own 3000ms timeout so a slow OS port release is not
+  // misread as a kill failure).
+  const killDeadline = Date.now() + 5000;
+  let portFree = false;
+  while (Date.now() < killDeadline) {
+    await sleep(250);
+    portFree = !(await ping(300));
+    if (portFree) break;
+  }
+  if (!portFree) {
+    const errorDetails = [
+      pidResolveError && `  PID resolution failure: ${pidResolveError?.message || String(pidResolveError)}`,
+      killError && `  kill failure: ${killError?.message || String(killError)}`,
+    ].filter(Boolean).join('\n');
+    throw new LaunchError(
+      `Port ${PORT} is in use by a different mixdog plugin instance and could not be reclaimed (kill of PID ${stalePid ?? 'unknown'} failed or timed out).\n` +
+      `  expected plugin root: ${pluginRoot}\n` +
+      `  actual plugin root:   ${remoteRoot}\n` +
+      (errorDetails ? errorDetails + '\n' : '') +
+      `Stop the other setup-server (or change PORT) and retry.\n`,
+    );
+  }
+  trace(`reclaimPort: killed stalePid=${stalePid}, port freed, spawning current server`);
+  await spawnServerWithLog(pluginRoot, pluginData, { openOnStart: false });
+  trace(`reclaimPort: spawnServerWithLog completed`);
+}
+
 async function waitForServer(timeoutMs = 4000, shouldStop = () => false) {
   const deadline = Date.now() + timeoutMs;
   let ready = false;
@@ -386,22 +534,13 @@ export async function launchConfigUi(options = {}) {
   const alive = await aliveProbe();
   __trace(`aliveProbe result alive=${alive}`);
 
-  // Pre-warm mode: ensure the server is booted window-free, then return.
-  // Already alive → cheap no-op (no requestOpen, no window). Not alive →
-  // spawn with openOnStart:false so setup-server boots without opening a
-  // browser window. No stale-server takeover: pre-warm is best-effort and
-  // must never kill another install's server.
-  if (prewarm) {
-    if (alive) {
-      __trace(`prewarm: server already alive → no-op`);
-      return CONFIG_UI_URL;
-    }
-    __trace(`prewarm: !alive → spawnServerWithLog (window-free)`);
-    await spawnServerWithLog(pluginRoot, pluginData, { openOnStart: false });
-    __trace(`prewarm: spawnServerWithLog completed`);
-    return CONFIG_UI_URL;
-  }
-
+  // Singleton / current-version invariant is enforced below for BOTH prewarm
+  // and interactive launches: prewarm no longer early-returns on a live
+  // server, so a stale old-version setup-server left running across a plugin
+  // update is taken over and replaced window-free at session start — instead
+  // of lingering until a manual /mixdog:config (the recurrence we hit). PORT
+  // is a fixed constant, so exactly one setup-server can own it; reclaiming a
+  // version-mismatched owner is the correct singleton behaviour even here.
   if (!alive) {
     // Boot window-free; the unconditional requestOpen below owns opening the
     // window. Spawning with openOnStart:1 here would double-open and races a
@@ -425,68 +564,40 @@ export async function launchConfigUi(options = {}) {
     const actual = normalize(remoteRoot);
     __trace(`compare expected=${expected} actual=${actual} mismatch=${expected !== actual}`);
     if (expected !== actual) {
-      // Invariant: single live plugin install owns PORT. The occupying server
-      // belongs to a different install — resolve its PID, terminate it, poll
-      // until the port is free, then take ownership via spawnServerWithLog().
-      let stalePid = null;
-      let pidResolveError = null;
-      let killError = null;
+      // Serialize the reclaim across processes: prewarm now takes over every
+      // session, so two concurrent launchers can both observe this stale
+      // server. Under the lock the recheck is authoritative — whoever acquires
+      // first reclaims, and the next acquirer re-reads a now-current server and
+      // skips, so a freshly-spawned correct server is never killed.
+      const locked = await acquireLaunchLock(__trace);
       try {
-        if (process.platform === 'win32') {
-          const out = execSync(
-            `powershell -NoProfile -Command "(Get-NetTCPConnection -LocalPort ${PORT} -ErrorAction SilentlyContinue | Select-Object -First 1).OwningProcess"`,
-            { encoding: 'utf8', timeout: 3000, windowsHide: true },
-          ).trim();
-          const n = parseInt(out, 10);
-          if (Number.isFinite(n) && n > 0) stalePid = n;
+        const recheckRoot = await fetchPluginPath();
+        if (recheckRoot && normalize(recheckRoot) !== expected) {
+          await reclaimPort(pluginRoot, pluginData, recheckRoot, __trace);
         } else {
-          const out = execSync(`lsof -ti :${PORT}`, { encoding: 'utf8', timeout: 3000 }).trim();
-          const n = parseInt(out.split('\n')[0], 10);
-          if (Number.isFinite(n) && n > 0) stalePid = n;
+          __trace(`takeover: server current under lock (recheckRoot=${recheckRoot}) → skip`);
         }
-      } catch (e) { pidResolveError = e; }
-      if (stalePid !== null) {
-        try {
-          if (process.platform === 'win32') {
-            // /T kills the whole process tree — the setup-server spawns child
-            // browser/server descendants that survive a PID-only Stop-Process,
-            // leaking processes and holding the port.
-            execSync(`taskkill /T /F /PID ${stalePid}`, { timeout: 3000, windowsHide: true });
-          } else {
-            // setup-server is launched detached (its own process-group leader),
-            // so the port-owning PID equals the group id. Negative PID signals
-            // the whole group, reaping descendants a bare kill would orphan.
-            try { execSync(`kill -KILL -${stalePid}`, { timeout: 3000 }); }
-            catch { execSync(`kill -KILL ${stalePid}`, { timeout: 3000 }); }
-          }
-        } catch (e) { killError = e; }
-      }
-      // Poll until port is free (250ms ticks, 3000ms deadline).
-      const killDeadline = Date.now() + 3000;
-      let portFree = false;
-      while (Date.now() < killDeadline) {
-        await sleep(250);
-        portFree = !(await ping(300));
-        if (portFree) break;
+      } finally {
+        if (locked) releaseLaunchLock();
       }
-      if (!portFree) {
-        const errorDetails = [
-          pidResolveError && `  PID resolution failure: ${pidResolveError?.message || String(pidResolveError)}`,
-          killError && `  kill failure: ${killError?.message || String(killError)}`,
-        ].filter(Boolean).join('\n');
-        throw new LaunchError(
-          `Port ${PORT} is in use by a different mixdog plugin instance and could not be reclaimed (kill of PID ${stalePid ?? 'unknown'} failed or timed out).\n` +
-          `  expected plugin root: ${pluginRoot}\n` +
-          `  actual plugin root:   ${remoteRoot}\n` +
-          (errorDetails ? errorDetails + '\n' : '') +
-          `Stop the other setup-server (or change PORT) and retry.\n`,
-        );
-      }
-      __trace(`takeover: killed stalePid=${stalePid}, port freed, spawning new server`);
-      await spawnServerWithLog(pluginRoot, pluginData, { openOnStart: false });
-      __trace(`takeover: spawnServerWithLog completed`);
     }
   }
+
+  // Ensure the server (just spawned, taken over, or concurrently swapped by
+  // another launcher) is actually answering before we report success or open a
+  // window — absorbs the brief port-down window during a concurrent reclaim so
+  // requestOpen never hits a refused port and prewarm never returns early.
+  if (!await waitForServer(15000)) {
+    throw new LaunchError(`setup-server did not become ready at ${CONFIG_UI_URL}/ before launch.\n`);
+  }
+
+  // Prewarm stops here: the current-version server is up (spawned or taken
+  // over above) and must NOT open a browser window.
+  if (prewarm) {
+    __trace(`prewarm: current-version server ensured → return`);
+    return CONFIG_UI_URL;
+  }
+
   // Invariant: a non-prewarm launch ALWAYS opens the window through the
   // idempotent /open endpoint once the server is ready — regardless of which
   // process (this launcher, a concurrent every-session prewarm, or a

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

@@ -15,10 +15,11 @@ import { listSchedules } from '../src/shared/schedules-store.mjs';
 import { ensureDataSeeds } from '../src/shared/seed.mjs';
 import { backupUserData, markUserDataInitialized, shouldSeedMissingUserData } from '../src/shared/user-data-guard.mjs';
 import { tmpdir } from 'os';
-import { readSection, writeSection, updateSection, saveSecret, deleteSecret, hasStoredSecret, SECRET_ACCOUNTS, getSearchApiKey, getAgentApiKey, getDiscordToken, getWebhookAuthtoken, diagnoseDiscordTokenValue } from '../src/shared/config.mjs';
+import { readSection, writeSection, updateSection, saveSecret, deleteSecret, hasStoredSecret, SECRET_ACCOUNTS, getSearchApiKey, getAgentApiKey, getDiscordToken, getWebhookAuthtoken, diagnoseDiscordTokenValue, AGENT_PROVIDER_ENV, AGENT_PROVIDER_ENV_ALIASES } from '../src/shared/config.mjs';
 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,
@@ -142,15 +143,11 @@ const SUPPORTED_PROVIDERS = [
   'anthropic-oauth', 'openai-oauth', 'openai-api', 'gemini-api', 'xai-api', 'grok-oauth',
   'tavily', 'firecrawl', 'exa',
 ];
-const AGENT_KEY_PROVIDER_IDS = ['openai', 'anthropic', 'gemini', 'deepseek', 'xai'];
+// AGENT_PROVIDER_ENV / AGENT_PROVIDER_ENV_ALIASES are the SSOT (src/shared/config.mjs);
+// derive the id list so a provider added there flows through every detection path
+// (keyStored, envKeys, secret presence) here automatically.
+const AGENT_KEY_PROVIDER_IDS = Object.keys(AGENT_PROVIDER_ENV);
 const SEARCH_KEY_PROVIDER_IDS = ['firecrawl', 'tavily', 'exa'];
-const AGENT_PROVIDER_ENV = Object.freeze({
-  openai: 'OPENAI_API_KEY',
-  anthropic: 'ANTHROPIC_API_KEY',
-  gemini: 'GEMINI_API_KEY',
-  deepseek: 'DEEPSEEK_API_KEY',
-  xai: 'XAI_API_KEY',
-});
 
 function envSecretPresent(account) {
   const key = 'MIXDOG_' + String(account || '').replace(/[.\s]+/g, '_').toUpperCase();
@@ -465,21 +462,19 @@ async function detectAuth(config = {}) {
   result.copilot = existsSync(join(configDir, 'github-copilot', 'hosts.json'))
     || existsSync(join(configDir, 'github-copilot', 'apps.json'));
   result.envKeys = {};
-  for (const [name, envKey] of [
-    ['openai', 'OPENAI_API_KEY'], ['anthropic', 'ANTHROPIC_API_KEY'],
-    ['gemini', 'GEMINI_API_KEY'], ['deepseek', 'DEEPSEEK_API_KEY'],
-    ['xai', 'XAI_API_KEY'],
-  ]) { result.envKeys[name] = !!process.env[envKey]; }
-  // GROK_API_KEY is the last-resort xAI env alias honored by getAgentApiKey('xai')
-  // (shared/config.mjs is the SSOT); mirror it here so a GROK_API_KEY-only env
-  // shows xAI as available. keyStored semantics (keychain-only) stay unchanged.
-  result.envKeys.xai = result.envKeys.xai || !!process.env.GROK_API_KEY;
+  for (const [id, env] of Object.entries(AGENT_PROVIDER_ENV)) result.envKeys[id] = !!process.env[env];
+  // Honor the shared last-resort env aliases (e.g. GROK_API_KEY for xai) so a
+  // GROK_API_KEY-only env still shows xAI as available, matching getAgentApiKey.
+  // keyStored semantics (keychain-only) stay unchanged.
+  for (const [id, aliases] of Object.entries(AGENT_PROVIDER_ENV_ALIASES)) {
+    if (!result.envKeys[id]) result.envKeys[id] = aliases.some((a) => !!process.env[a]);
+  }
   // Keychain-stored provider keys. Only this boolean is sent to the browser —
   // the secret value never leaves the server, so the UI can show "Set" without
   // exposing the key.
   result.keyStored = {};
-  for (const name of ['openai', 'anthropic', 'gemini', 'deepseek', 'xai']) {
-    result.keyStored[name] = hasStoredSecret(SECRET_ACCOUNTS.agentApiKey(name));
+  for (const id of AGENT_KEY_PROVIDER_IDS) {
+    result.keyStored[id] = hasStoredSecret(SECRET_ACCOUNTS.agentApiKey(id));
   }
   const ollamaUrl = config?.providers?.ollama?.baseURL || 'http://localhost:11434/v1';
   const lmstudioUrl = config?.providers?.lmstudio?.baseURL || 'http://localhost:1234/v1';
@@ -518,7 +513,7 @@ async function detectAuth(config = {}) {
 // in sync with src/agent/orchestrator/providers/registry.mjs.
 const _RUNTIME_PROVIDER_NAMES = [
   'anthropic', 'anthropic-oauth', 'openai', 'openai-oauth',
-  'gemini', 'deepseek', 'xai', 'grok-oauth',
+  'gemini', 'deepseek', 'xai', 'opencode-go', 'grok-oauth',
   'ollama', 'lmstudio',
 ];
 
@@ -1471,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(() => {