surf-cli 2.19.0 → 2.20.0

package/native/cli.cjs

@@ -16,7 +16,7 @@ const {
   validateWorkflowArgs,
   validateWorkflowFile,
 } = require("./workflow-definition.cjs");
-const { executeDoSteps, sendDoRequest } = require("./do-executor.cjs");
+const { executeDoSteps, semanticRequestContext, sendDoRequest } = require("./do-executor.cjs");
 const { runExtraction, renderExtractionMarkdown } = require("./extract.cjs");
 const { applyOptionsPrelude, parseScriptOptions } = require("./script-options.cjs");
 const { openClientTransport } = require("./client-transport.cjs");
@@ -202,6 +202,22 @@ try {
   process.exit(1);
 }
 
+if (args[0] === "semantic" || args[0]?.startsWith("semantic.")) {
+  const { formatSemanticOutput, handleSemanticCli } = require("./semantic-cli.cjs");
+  handleSemanticCli(args, { endpoint })
+    .then((result) => {
+      if (!result.handled) throw new Error("Semantic command was not handled");
+      if (result.value !== undefined) console.log(formatSemanticOutput(result));
+      process.exit(0);
+    })
+    .catch((error) => {
+      const code = error?.code ? ` [${error.code}]` : "";
+      console.error(`Error: ${error?.message || String(error)}${code}`);
+      process.exit(1);
+    });
+  return;
+}
+
 if (args[0] === "oracle") {
   if (args[1] === "ask" || args[1] === "follow") {
     console.error("[surf] Oracle requires exclusive browser access while dispatching; other sessions will queue.");
@@ -1200,6 +1216,15 @@ const TOOLS = {
         args: [],
         examples: [{ cmd: "frame.list", desc: "Show frame tree" }]
       },
+      "frame.diagnose": {
+        desc: "Compare DOM iframes, extension reachability, and the Chrome DevTools frame tree",
+        args: [],
+        opts: {
+          "tab-id": "Target tab ID",
+          json: "Print full frame inventories as JSON"
+        },
+        examples: [{ cmd: "frame.diagnose", desc: "Explain iframe access and count mismatches" }]
+      },
       "frame.switch": {
         desc: "Switch to iframe context",
         args: [],
@@ -1308,7 +1333,10 @@ const TOOLS = {
           "on-error": "stop (default) | continue",
           "no-auto-wait": "Disable automatic waits between steps",
           "step-delay": "Delay between steps in ms (default: 100)",
-          "dry-run": "Parse and validate without executing"
+          "dry-run": "Parse and validate without executing",
+          "allow-semantic": "Allow bounded TypeSafe semantic decisions",
+          "allow-write": "Allow declared semantic fill/check/click steps",
+          "inputs-stdin": "Read bounded private input slots as one JSON object from stdin",
         },
         examples: [
           { cmd: 'do \'go "https://example.com" | click e5 | screenshot\'', desc: "Inline workflow" },
@@ -1584,8 +1612,19 @@ Tips:
   - Use window.new --incognito for isolated cookies`
   },
   semantic: {
-    title: "Semantic Locators",
-    content: `Find elements by role, text, or label instead of refs or selectors.
+    title: "Semantic browser decisions and locators",
+    content: `Optional Jev commands (page-derived text is sent to TypeSafe only for these commands):
+  semantic.find "the notification control"
+  semantic.verify "Notification preferences were saved"
+  semantic.filter "notification preferences"
+  semantic.act "Open notification settings" --max-steps 5
+  semantic.act "Fill email" --input email="$EMAIL" --allow-write
+  semantic auth set|status|clear
+
+Every click/fill requires --allow-write. This broadly authorizes even high-impact controls;
+repeat --allow-ref <ref> to narrow authorization to exact observed refs.
+
+Local semantic locators find elements by role, text, or label instead of refs or selectors.
 
 By ARIA role:
   locate.role button --name "Submit" --action click
@@ -1691,7 +1730,7 @@ const ALL_SOCKET_TOOLS = [
   "form.fill",
   "perf.start", "perf.stop", "perf.metrics",
   "upload",
-  "frame.list", "frame.switch", "frame.main", "frame.js",
+  "frame.list", "frame.diagnose", "frame.switch", "frame.main", "frame.js",
   "cookie.list", "cookie.get", "cookie.set", "cookie.clear",
   "search", "batch",
   "zoom", "resize",
@@ -1714,6 +1753,7 @@ const SEE_ALSO = {
   "window.new": ["window.list"],
   "window.list": ["tab.list"],
   "frame.list": ["frame.switch", "frame.main"],
+  "frame.diagnose": ["frame.list", "frame.switch", "frame.js"],
   "frame.switch": ["frame.list", "frame.main", "frame.js"],
   "frame.main": ["frame.list", "frame.switch"],
   "frame.js": ["frame.switch", "js"],
@@ -1767,6 +1807,8 @@ Common Commands:
   animate-audit      JSON timeline of element animation/style samples
   perf-audit         PerformanceObserver snapshot for motion/jank debugging
   page.read          Get page accessibility tree (alias: read)
+  semantic.find      Optional Jev-powered candidate selection
+  semantic.act       Bounded semantic browser action controller
   locate.role <role> Find element by ARIA role
   search <term>      Search for text in page (alias: find)
   window.new <url>   Create isolated browser window
@@ -1844,6 +1886,11 @@ const showFullHelp = () => {
 
 Usage: surf <command> [args] [options]
 
+Semantic (optional TypeSafe/Jev):
+  surf semantic.find|verify|filter <goal> [--json]
+  surf semantic.act <goal> [--allow-write] [--allow-ref <ref>] [--input <name=value>]
+  surf semantic auth <set|status|clear>
+
 Oracle:
   surf oracle <ask|status|result|follow|list>
 
@@ -2407,9 +2454,12 @@ if (args[0] === "do") {
   let windowId = undefined;
   let explicitSession = undefined;
   let noWait = false;
+  let allowSemantic = false;
+  let allowWrite = false;
+  let inputsStdin = false;
 
   // Reserved flags that aren't workflow args
-  const reservedFlags = ['file', 'f', 'dry-run', 'on-error', 'no-auto-wait', 'step-delay', 'json', 'tab-id', 'window-id', 'session', 'no-lock', 'no-wait'];
+  const reservedFlags = ['file', 'f', 'dry-run', 'on-error', 'no-auto-wait', 'step-delay', 'json', 'tab-id', 'window-id', 'session', 'no-lock', 'no-wait', 'allow-semantic', 'allow-write', 'inputs-stdin'];
 
   // Workflow-specific args (collected for variable substitution)
   const workflowArgs = {};
@@ -2449,6 +2499,12 @@ if (args[0] === "do") {
       i++;
     } else if (arg === "--no-wait") {
       noWait = true;
+    } else if (arg === "--allow-semantic") {
+      allowSemantic = true;
+    } else if (arg === "--allow-write") {
+      allowWrite = true;
+    } else if (arg === "--inputs-stdin") {
+      inputsStdin = true;
     } else if (arg.startsWith("--")) {
       // Workflow-specific arg (e.g., --email, --password)
       const key = arg.slice(2);
@@ -2573,6 +2629,27 @@ if (args[0] === "do") {
 
   // Apply arg defaults
   const vars = workflow ? applyArgDefaults(workflow, workflowArgs) : workflowArgs;
+  let privateInputs = {};
+  if (inputsStdin) {
+    try {
+      const { SEMANTIC_POLICY } = require("./semantic-core.cjs");
+      const input = fs.readFileSync(0, "utf8");
+      if (Buffer.byteLength(input, "utf8") > 262144) throw new Error("input JSON exceeds 256 KiB");
+      privateInputs = JSON.parse(input);
+      if (!privateInputs || typeof privateInputs !== "object" || Array.isArray(privateInputs)) throw new Error("input JSON must be an object");
+      const entries = Object.entries(privateInputs);
+      if (entries.length > SEMANTIC_POLICY.limits.inputSlots) throw new Error(`input JSON supports at most ${SEMANTIC_POLICY.limits.inputSlots} slots`);
+      for (const [name, value] of entries) {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(name)) throw new Error("input JSON contains an invalid slot name");
+        if (!["string", "number", "boolean"].includes(typeof value)) throw new Error(`input slot '${name}' must be a string, number, or boolean`);
+        if (Buffer.byteLength(String(value), "utf8") > SEMANTIC_POLICY.limits.inputValueBytes) throw new Error(`input slot '${name}' exceeds ${SEMANTIC_POLICY.limits.inputValueBytes / 1024} KiB`);
+        if (Object.hasOwn(vars, name)) throw new Error(`input slot '${name}' was supplied more than once`);
+      }
+    } catch (error) {
+      console.error(`Error: Invalid --inputs-stdin JSON: ${error.message}`);
+      process.exit(1);
+    }
+  }
 
   // Validate with --dry-run
   if (dryRun) {
@@ -2593,6 +2670,21 @@ if (args[0] === "do") {
     process.exit(0);
   }
 
+  const semanticEnabled = Boolean(workflow?.semantic);
+  if (semanticEnabled && !allowSemantic) {
+    console.error("Error: semantic workflows require --allow-semantic");
+    process.exit(1);
+  }
+  if (semanticEnabled && onError === "continue") {
+    console.error("Error: semantic workflows do not support --on-error continue");
+    process.exit(1);
+  }
+  const writeOps = new Set(["ensureChecked", "fill", "click"]);
+  if (semanticEnabled && steps.some((step) => writeOps.has(step.args?.op)) && !allowWrite) {
+    console.error("Error: mutation-capable semantic steps require --allow-write");
+    process.exit(1);
+  }
+
   if (!wantJson) {
     if (workflowName) {
       console.log(`Running workflow: ${workflowName} (${steps.length} steps)...\n`);
@@ -2620,6 +2712,17 @@ if (args[0] === "do") {
         endpoint,
         transport,
       },
+      ...(semanticEnabled ? {
+        createSemanticExecutor: async ({ context }) => {
+          const { createConcreteSemanticExecutor } = require("./semantic-workflow-executor.cjs");
+          return createConcreteSemanticExecutor({
+            workflow,
+            inputs: { ...vars, ...privateInputs },
+            request: (tool, toolArgs, timeoutMs, identity) =>
+              sendDoRequest(tool, toolArgs, semanticRequestContext(context, timeoutMs, identity)),
+          });
+        },
+      } : {}),
       });
 
     // Print summary

package/native/do-executor.cjs

@@ -35,6 +35,14 @@ function sendDoRequest(toolName, toolArgs, context = {}) {
   })();
 }
 
+function semanticRequestContext(context, timeoutMs, identity) {
+  return {
+    ...context,
+    timeoutMs,
+    ...(identity ? { tabId: identity.tabId, windowId: undefined, session: undefined } : {}),
+  };
+}
+
 function summarizeArgs(step) {
   return Object.entries(step.args || {})
     .map(([key, value]) => typeof value === "string" && value.length > 40 ? `${key}="${value.slice(0, 37)}..."` : `${key}=${JSON.stringify(value)}`)
@@ -63,14 +71,32 @@ function printProgress(event) {
 
 async function executeDoSteps(steps, options = {}) {
   const context = options.context || {};
-  return runtime.executeWorkflow(steps, {
-    ...options,
-    executeTool: options.executeTool || ((tool, args) => sendDoRequest(tool, args, context)),
-    onProgress: options.quiet ? options.onProgress : (event) => {
-      printProgress(event);
-      options.onProgress?.(event);
-    },
-  });
+  let semanticExecutor;
+  const executeSemanticStep = steps.some((step) => step.cmd === "semantic.step")
+    ? async (step, semanticContext, executionOptions) => {
+      if (!semanticExecutor) {
+        semanticExecutor = options.executeSemanticStep;
+        if (!semanticExecutor && typeof options.createSemanticExecutor === "function") {
+          semanticExecutor = await options.createSemanticExecutor({ context });
+        }
+        if (typeof semanticExecutor !== "function") throw new Error("semantic.step requires an injected semantic executor");
+      }
+      return semanticExecutor(step, semanticContext, executionOptions);
+    }
+    : undefined;
+  try {
+    return await runtime.executeWorkflow(steps, {
+      ...options,
+      executeTool: options.executeTool || ((tool, args) => sendDoRequest(tool, args, context)),
+      ...(executeSemanticStep ? { executeSemanticStep } : {}),
+      onProgress: options.quiet ? options.onProgress : (event) => {
+        printProgress(event);
+        options.onProgress?.(event);
+      },
+    });
+  } finally {
+    await semanticExecutor?.close?.();
+  }
 }
 
 module.exports = {
@@ -83,6 +109,7 @@ module.exports = {
   extractStepOutput: runtime.extractStepOutput,
   getAutoWaitCommand: runtime.getAutoWaitCommand,
   resolveVar: runtime.resolveVar,
+  semanticRequestContext,
   sendDoRequest,
   shouldAutoWait: runtime.shouldAutoWait,
   substituteVars: runtime.substituteVars,

package/native/doctor.cjs

@@ -4,6 +4,17 @@ const os = require("os");
 const path = require("path");
 const { execFileSync } = require("child_process");
 const { connectEndpoint, selectEndpoint } = require("./endpoint.cjs");
+const {
+  convertWindowsPath,
+  getWindowsEnv,
+  nativeMessagingRegistryPath,
+  runWindowsExecutable,
+} = require("../scripts/windows-interop.cjs");
+const {
+  renderWslWrapper,
+  probeWindowsWrapper,
+} = require("./native-host-launch-probe.cjs");
+const { findNode, getHostPath } = require("../scripts/install-native-host.cjs");
 
 const HOST_NAME = "surf.browser.host";
 
@@ -115,32 +126,12 @@ function resolveBrowsers(browserArg) {
   return browsers;
 }
 
-function getWindowsEnv(name, { env = process.env, execFileSync: execFile = execFileSync } = {}) {
-  if (env[name]) return env[name];
-  try {
-    return execFile("cmd.exe", ["/c", "echo", `%${name}%`], { encoding: "utf8" })
-      .trim()
-      .replace(/\r/g, "");
-  } catch {
-    return null;
-  }
-}
-
-function windowsPathToWslPath(winPath) {
-  const normalized = winPath.replace(/\\/g, "/");
-  const match = normalized.match(/^([A-Za-z]):\/(.*)$/);
-  if (!match) return normalized;
-  return `/mnt/${match[1].toLowerCase()}/${match[2]}`;
-}
-
 function manifestPathForBrowser(browserKey, context) {
   const browser = BROWSERS[browserKey];
   if (!browser) return null;
 
   if (context.effectiveTarget === "wsl-windows") {
-    const localAppData = getWindowsEnv("LOCALAPPDATA", context);
-    if (!localAppData || !browser.wsl) return null;
-    return path.join(windowsPathToWslPath(localAppData), browser.wsl, `${HOST_NAME}.json`);
+    return null;
   }
 
   if (context.platform === "win32") {
@@ -156,7 +147,7 @@ function manifestPathForBrowser(browserKey, context) {
 
 function fsPathFromManifestPath(manifestPath, context) {
   if (context.platform === "linux" && /^[A-Za-z]:[\\/]/.test(manifestPath)) {
-    return windowsPathToWslPath(manifestPath);
+    return convertWindowsPath(manifestPath, context);
   }
   return manifestPath;
 }
@@ -164,17 +155,21 @@ function fsPathFromManifestPath(manifestPath, context) {
 function windowsRegistryPathForBrowser(browserKey) {
   const browser = BROWSERS[browserKey];
   if (!browser?.win32) return null;
-  return `HKCU\\Software\\${browser.win32}\\NativeMessagingHosts\\${HOST_NAME}`;
+  return nativeMessagingRegistryPath(browser.win32, HOST_NAME);
 }
 
 function readWindowsRegistryManifestPath(registryPath, context) {
   try {
-    const output = context.execFileSync("reg", ["query", registryPath, "/ve"], { encoding: "utf8" });
+    const output = runWindowsExecutable("reg.exe", ["query", registryPath, "/ve"], {
+      execFileSync: context.execFileSync,
+      allowWslFallback: context.effectiveTarget === "wsl-windows",
+      execOptions: { encoding: "utf8" },
+    });
     const line = output.split(/\r?\n/).find((item) => item.includes("REG_SZ"));
-    if (!line) return null;
-    return line.replace(/^.*REG_SZ\s+/, "").trim() || null;
-  } catch {
-    return null;
+    if (!line) return { manifestPath: null, error: "registry output contained no REG_SZ default value" };
+    return { manifestPath: line.replace(/^.*REG_SZ\s+/, "").trim() || null, error: null };
+  } catch (error) {
+    return { manifestPath: null, error: error.message };
   }
 }
 
@@ -192,15 +187,16 @@ function checkWindowsRegistry(browserKey, context) {
     };
   }
 
-  const manifestPath = readWindowsRegistryManifestPath(registryPath, context);
+  const registry = readWindowsRegistryManifestPath(registryPath, context);
+  const manifestPath = registry.manifestPath;
   return {
     check: {
       id: "windows-registry",
       status: manifestPath ? "pass" : "fail",
       browser: browserKey,
-      message: manifestPath
-        ? `Windows native messaging registry points to ${manifestPath}`
-        : `Windows native messaging registry entry not found: ${registryPath}`,
+      message: !manifestPath
+        ? `Windows native messaging registry entry not found: ${registryPath}${registry.error ? ` (${registry.error})` : ""}`
+        : `Windows native messaging registry points to ${manifestPath}`,
       registryPath,
       path: manifestPath,
     },
@@ -210,19 +206,32 @@ function checkWindowsRegistry(browserKey, context) {
 
 function checkManifest(manifestPath, context) {
   const checks = [];
-  const exists = manifestPath ? context.fs.existsSync(manifestPath) : false;
+  let manifestFsPath = manifestPath;
+  try {
+    manifestFsPath = manifestPath ? fsPathFromManifestPath(manifestPath, context) : manifestPath;
+  } catch (error) {
+    checks.push({
+      id: "manifest-file",
+      status: "fail",
+      message: `Could not resolve manifest path ${manifestPath}: ${error.message}`,
+      path: manifestPath,
+    });
+    return { checks, manifest: null };
+  }
+  const exists = manifestFsPath ? context.fs.existsSync(manifestFsPath) : false;
   checks.push({
     id: "manifest-file",
     status: exists ? "pass" : "fail",
-    message: exists ? `Manifest found: ${manifestPath}` : "Native messaging manifest not found",
+    message: exists ? `Manifest found: ${manifestPath}` : `Native messaging manifest not found: ${manifestPath}`,
     path: manifestPath,
+    fsPath: manifestFsPath,
   });
 
   if (!exists) return { checks, manifest: null };
 
   let manifest;
   try {
-    manifest = JSON.parse(context.fs.readFileSync(manifestPath, "utf8"));
+    manifest = JSON.parse(context.fs.readFileSync(manifestFsPath, "utf8"));
     checks.push({ id: "manifest-json", status: "pass", message: "Manifest JSON is valid" });
   } catch (error) {
     checks.push({ id: "manifest-json", status: "fail", message: `Manifest JSON is invalid: ${error.message}` });
@@ -288,6 +297,126 @@ function checkManifest(manifestPath, context) {
   return { checks, manifest };
 }
 
+function normalizeWindowsPath(filePath) {
+  return path.win32.normalize(filePath).replace(/[\\/]+$/, "").toLowerCase();
+}
+
+function checkWslWrapperLaunch(manifest, context) {
+  if (!manifest || typeof manifest.path !== "string" || manifest.path.length === 0) {
+    return null;
+  }
+
+  let canonicalWindowsPath;
+  try {
+    const localAppData = getWindowsEnv("LOCALAPPDATA", { execFileSync: context.execFileSync });
+    canonicalWindowsPath = path.win32.join(
+      localAppData,
+      "surf-cli",
+      "host-wrapper-wsl.cmd",
+    );
+  } catch (error) {
+    return {
+      id: "wrapper-launch",
+      status: "fail",
+      message: `Could not resolve Surf's managed Windows wrapper path: ${error.message}`,
+    };
+  }
+
+  if (normalizeWindowsPath(manifest.path) !== normalizeWindowsPath(canonicalWindowsPath)) {
+    return {
+      id: "wrapper-launch",
+      status: "warn",
+      message:
+        "Skipped launch probe because the manifest does not point to Surf's managed WSL wrapper. Run `surf install <extension-id>` to restore the managed wrapper.",
+      path: manifest.path,
+    };
+  }
+
+  let wrapperFsPath;
+  try {
+    wrapperFsPath = fsPathFromManifestPath(canonicalWindowsPath, context);
+  } catch (error) {
+    return {
+      id: "wrapper-launch",
+      status: "fail",
+      message: `Could not resolve Surf's managed WSL wrapper: ${error.message}`,
+      path: canonicalWindowsPath,
+    };
+  }
+
+  if (!context.fs.existsSync(wrapperFsPath)) {
+    return {
+      id: "wrapper-launch",
+      status: "fail",
+      message: `Surf's managed WSL wrapper does not exist: ${canonicalWindowsPath}`,
+      path: canonicalWindowsPath,
+      fsPath: wrapperFsPath,
+    };
+  }
+
+  let wrapperContent;
+  try {
+    wrapperContent = context.fs.readFileSync(wrapperFsPath, "utf8");
+  } catch (error) {
+    return {
+      id: "wrapper-launch",
+      status: "fail",
+      message: `Could not read Surf's managed WSL wrapper: ${error.message}`,
+      path: canonicalWindowsPath,
+      fsPath: wrapperFsPath,
+    };
+  }
+
+  const nodePath = context.nodePath || findNode();
+  const hostPath = context.hostPath || getHostPath();
+  const distro = context.env.WSL_DISTRO_NAME;
+  let explicitWrapper = null;
+  let defaultWrapper = null;
+  if (nodePath && hostPath && distro) {
+    try {
+      explicitWrapper = renderWslWrapper(nodePath, hostPath, distro);
+      defaultWrapper = renderWslWrapper(nodePath, hostPath, null);
+    } catch {
+      // Do not execute a wrapper whose installed paths cannot be rendered safely.
+    }
+  }
+  if (wrapperContent !== explicitWrapper && wrapperContent !== defaultWrapper) {
+    return {
+      id: "wrapper-launch",
+      status: "warn",
+      message:
+        "Surf's managed WSL wrapper does not match this installation, so it was not executed. Run `surf install <extension-id>` to replace it.",
+      path: canonicalWindowsPath,
+      fsPath: wrapperFsPath,
+    };
+  }
+
+  try {
+    const observedDistro = context.probeWindowsWrapper(canonicalWindowsPath, {
+      execFileSync: context.execFileSync,
+      verifyDistro: wrapperContent === defaultWrapper,
+    });
+    if (wrapperContent === defaultWrapper && observedDistro !== distro) {
+      throw new Error("Windows default WSL distro does not match this installation");
+    }
+    return {
+      id: "wrapper-launch",
+      status: "pass",
+      message: "Surf's managed WSL wrapper completed its launch probe",
+      path: canonicalWindowsPath,
+      fsPath: wrapperFsPath,
+    };
+  } catch (error) {
+    return {
+      id: "wrapper-launch",
+      status: "fail",
+      message: `Surf's managed WSL wrapper failed validation: ${error.message}`,
+      path: canonicalWindowsPath,
+      fsPath: wrapperFsPath,
+    };
+  }
+}
+
 async function checkSocket(socketPath, context) {
   const checks = [];
   if (context.platform !== "win32") {
@@ -371,6 +500,20 @@ function summarize(checks) {
 function buildRecommendations(report) {
   const recommendations = [];
   const failedIds = new Set(report.checks.filter((check) => check.status === "fail").map((check) => check.id));
+  const debugRelevantIds = new Set([
+    "windows-registry",
+    "manifest-file",
+    "manifest-json",
+    "manifest-shape",
+    "manifest-name",
+    "manifest-type",
+    "manifest-origins",
+    "manifest-path",
+    "manifest-path-executable",
+    "wrapper-launch",
+    "socket-file",
+    "socket-connect",
+  ]);
 
   if (failedIds.has("windows-registry")) {
     recommendations.push("Run `surf install <extension-id> --browser <browser>` so Windows registers the native messaging host, then restart the browser.");
@@ -384,12 +527,18 @@ function buildRecommendations(report) {
   if (failedIds.has("manifest-path") || failedIds.has("manifest-path-executable")) {
     recommendations.push("Reinstall the native host so the manifest path points at the current Surf wrapper.");
   }
+  if (failedIds.has("wrapper-launch")) {
+    recommendations.push("Rerun `surf install <extension-id>` from the same WSL distro so Surf can replace and validate the Windows wrapper.");
+  }
   if (failedIds.has("manifest-supported")) {
     recommendations.push("Choose a browser supported for this target, or rerun with `--browser all` to inspect every supported setup.");
   }
   if (failedIds.has("socket-file") || failedIds.has("socket-connect")) {
     recommendations.push("Make sure the browser is running with the Surf extension enabled, then restart the browser after install changes.");
   }
+  if ([...failedIds].some((id) => debugRelevantIds.has(id))) {
+    recommendations.push("Open chrome://extensions and inspect Surf's service worker console. In Surf's Details > Extension options, enable Debug Mode, reproduce the failure, then disable Debug Mode when finished.");
+  }
   if (report.environment.surfSocketSet) {
     recommendations.push("SURF_SOCKET is set; make sure Chrome launches the native host with the same socket value.");
   }
@@ -478,6 +627,9 @@ async function runDoctor(rawOptions = {}, deps = {}) {
     effectiveTarget,
     fs: deps.fs || fs,
     execFileSync: deps.execFileSync || execFileSync,
+    probeWindowsWrapper: deps.probeWindowsWrapper || probeWindowsWrapper,
+    nodePath: deps.nodePath,
+    hostPath: deps.hostPath,
     connectSocket: deps.connectSocket || connectSocket,
     connectTimeoutMs: options.connectTimeoutMs,
   };
@@ -493,15 +645,20 @@ async function runDoctor(rawOptions = {}, deps = {}) {
   for (const browserKey of browsers) {
     const browser = BROWSERS[browserKey];
     const browserChecks = [];
-    let manifestPath = manifestPathForBrowser(browserKey, context);
+    const usesWindowsRegistry =
+      (context.platform === "win32" || context.effectiveTarget === "wsl-windows") &&
+      Boolean(browser.win32);
+    let manifestPath = null;
 
-    if (context.platform === "win32" && browser.win32) {
+    if (usesWindowsRegistry) {
       const registry = checkWindowsRegistry(browserKey, context);
       browserChecks.push(registry.check);
-      if (registry.manifestPath) manifestPath = registry.manifestPath;
+      manifestPath = registry.manifestPath;
+    } else {
+      manifestPath = manifestPathForBrowser(browserKey, context);
     }
 
-    if (!manifestPath) {
+    if (!manifestPath && !usesWindowsRegistry) {
       const check = {
         id: "manifest-supported",
         status: options.browser === "all" ? "warn" : "fail",
@@ -516,6 +673,10 @@ async function runDoctor(rawOptions = {}, deps = {}) {
 
     const result = checkManifest(manifestPath, context);
     browserChecks.push(...result.checks.map((check) => ({ ...check, browser: browserKey })));
+    if (context.effectiveTarget === "wsl-windows" && result.manifest) {
+      const wrapperLaunch = checkWslWrapperLaunch(result.manifest, context);
+      if (wrapperLaunch) browserChecks.push({ ...wrapperLaunch, browser: browserKey });
+    }
     checks.push(...browserChecks);
     manifests.push({
       browser: browserKey,
@@ -638,5 +799,4 @@ module.exports = {
   parseDoctorArgs,
   runDoctor,
   runDoctorCli,
-  windowsPathToWslPath,
 };