@weavetab/mcp 2.5.0-beta.1 → 2.5.0-beta.4

package/SECURITY.md

@@ -42,28 +42,43 @@ Weavetab interacts directly with the local Chromium browser instance via the Chr
 
 ---
 
-## Blind Injection Threat Model
+## Blind Injection Threat Model & Hardening
 
-The **Blind Injection** architecture specifically ensures that credentials do not leak back into the LLM context or Weavetab logs.
+The **Blind Injection** architecture specifically ensures that credentials do not leak back into the LLM context, Weavetab logs, DOM snapshots, visual captures, or scrape results.
 
 ### Threats Mitigated
 
-- **Accidental context inclusion** — LLM reading the DOM and echoing passwords
-- **Log scraping** — Passwords appearing in plaintext audit logs
-- **DOM snapshot leakage** — Secret values masked as `[REDACTED]` in all subsequent maps, deltas, and AX tree dumps
-- **Prompt injection domain theft** — Domain check runs before the secret value is ever resolved
+- **Accidental Context Inclusion** — LLM reading the DOM, AX tree, or input discovery and echoing passwords
+- **DOM & Scrape Scraping** — Passwords extracted via direct DOM access, `browser_scrape`, or `document.querySelector().value`
+- **Visual Capture Leaks** — Passwords visible in screenshots, MHTML snapshots, or PDF printouts
+- **Log Scraping** — Passwords appearing in plaintext action logs or audit records
+- **DOM Snapshot Leakage** — Secret values masked as `[REDACTED]` in all subsequent maps, deltas, and AX tree dumps
+- **Prompt Injection Domain Theft** — Domain check runs before the secret value is ever resolved from disk
+- **Coercion & Serialization Leaks** — `JSON.stringify(el)`, `String(el)`, or array spreads leaking underlying element values
+
+### Defense-in-Depth Implementation
+
+1. **Storage at Rest**: Secrets in `~/.weavetab/secrets.json` are encrypted using AES-256-GCM with a machine-isolated key in `~/.weavetab-system/secrets-key`.
+2. **In-Process Resolution**: The AI model only receives and passes the key name (`envKey: "MY_KEY"`). The secret value is resolved in memory and injected directly via CDP `Input.insertText`.
+3. **DOM Property Hardening**: Injected elements are tagged `data-wt-secret="true"`, instance `.value` getters are overridden with `[REDACTED]`, and `Symbol.iterator`, `Symbol.toPrimitive`, and `toJSON` are locked.
+4. **In-Memory SessionSecretTracker**: Tracks node IDs and secret substrings per session to redact any coincidental echoes across ActionMaps, delta diffs, or scrape outputs.
+5. **Universal Tool Containment**:
+   - `browser_type`: Broad secret regex (`type`, `name`, `id`, `autocomplete`, `aria-label`, PINs, tokens, multi-language variants) auto-hardens target fields and suppresses raw value readbacks.
+   - `browser_fill`: Registers secrets in both single and `blast_mode`, redacting return values and scan discovery mode (`scan: true`).
+   - `browser_scrape`: Evaluates in-page extraction substituting all attributes of sensitive nodes with `[REDACTED]`.
+   - `browser_screenshot`, `browser_snapshot`, `browser_pdf`: Dynamically blanks/masks sensitive fields during capture and restores them in `finally` blocks.
 
 ### Threats NOT Mitigated
 
-- This does **not** protect against a compromised host or a malicious process reading the secrets file directly
-- It is not "zero-knowledge"; Weavetab must read the secret from `secrets.json` to inject it
+- This does **not** protect against a compromised host or a malicious OS process with elevated privileges reading the secrets file directly.
+- It is not "zero-knowledge"; Weavetab must read and decrypt the secret from `secrets.json` to inject it into Chromium.
 
 ### Secrets Resolution Order
 
 When `browser_type_secret({ envKey: 'MY_SECRET' })` is called, the `JsonSecretStore` resolves from:
 
-1. `./.Weavetab/secrets.json` (project-scoped, opt-in via `Weavetab secrets init --project`)
-2. `~/.Weavetab/secrets.json` (global default)
+1. `./.weavetab/secrets.json` (project-scoped, opt-in via `weavetab secrets init --project`)
+2. `~/.weavetab/secrets.json` (global default)
 
 The old `EnvSecretProvider` (`.env`-based) is **deprecated and no longer supported**. All secrets must be stored in `secrets.json`. See the [README Secrets Management section](README.md#-secrets-management) for the full CLI workflow.
 
@@ -72,14 +87,10 @@ The old `EnvSecretProvider` (`.env`-based) is **deprecated and no longer support
 ```json
 {
   "ACME_CORP_PASSWORD": {
-    "value": "hunter2",
+    "value": "encrypted_aes_gcm_string",
     "domains": ["login.example.com"],
-    "description": "Account password"
-  },
-  "GITHUB_2FA": {
-    "value": "123456",
-    "domains": ["github.com"],
-    "description": "2FA Code"
+    "createdAt": "2026-08-29T10:00:00.000Z",
+    "updatedAt": "2026-08-29T10:00:00.000Z"
   }
 }
 ```
@@ -91,9 +102,9 @@ The old `EnvSecretProvider` (`.env`-based) is **deprecated and no longer support
 | Tool Category | admin | viewer | system |
 |---------------|-------|--------|--------|
 | All mutation tools | ✅ | ❌ | ❌ |
-| Read-only (map, find, scrape, console, eval, inspect, snapshot, screenshot, pdf, cookies, tabs, wait, github_*) | ✅ | ✅ | ❌ |
+| Read-only (map, find, scrape, console, eval, inspect, snapshot, screenshot, pdf, cookies, tabs, wait, browser_github) | ✅ | ✅ | ❌ |
 | burst, plan, wait, map | ✅ | ❌ | ✅ |
-| System (logs, detect, performance, reset_loop_counter) | ✅ | ❌ | ❌ |
+| System (logs, detect, performance) | ✅ | ❌ | ❌ |
 
 ### Role Definitions
 
@@ -131,7 +142,7 @@ If you discover a security vulnerability in Weavetab, please **do not** open a p
 
 Instead, report via one of the following channels:
 
-- **Email**: security@Weavetab.dev
+- **Email**: security@weavetab.dev
 - **GitHub**: Use the private vulnerability reporting feature on the repository
 
 ### Disclosure Timeline
@@ -185,8 +196,8 @@ To receive security notifications:
 
 For security-related inquiries:
 
-- **Security Vulnerabilities**: security@Weavetab.dev
-- **Security Questions**: conduct@Weavetab.dev
+- **Security Vulnerabilities**: security@weavetab.dev
+- **Security Questions**: conduct@weavetab.dev
 - **GitHub Security**: https://github.com/weavetab/mcp/security
 
 ---

package/TROUBLESHOOTING.md

@@ -108,7 +108,7 @@ browser_click({ id: "w:42" })
 
 **Cause:** The warning previously relied on strict text matching.
 
-**Solution:** `stuck_warning` now respects the underlying `delta` computation. If the DOM changed, the warning will not fire. If you still see false positives, use `browser_reset_loop_counter` to manually reset.
+**Solution:** `stuck_warning` now respects the underlying `delta` computation. If the DOM changed, the warning will not fire. If you still see false positives, use `browser_map({ force: true })` or `browser_wait({ reset_loop: true })` to manually reset.
 
 ---
 
@@ -199,7 +199,7 @@ browser_click({ id: "w:42" })
 **Cause:** Extension incompatibility or corrupted Chrome profile.
 
 **Solution:**
-- Try running without extension: Set `loadExtension: false` in config
+- Try running without extension: Set `"extension": false` in config
 - Use a fresh Chrome profile: Set `profileDir` to a new directory
 - Check Chrome version compatibility (requires Chrome 90+)
 - Disable hardware acceleration in Chrome settings
@@ -360,6 +360,6 @@ If you continue to experience issues:
 ## Additional Resources
 
 - [Architecture Documentation](ARCHITECTURE.md)
-- [Tool Reference](docs/TOOLS.md)
+- [Tool Reference](docs/tools/tools.md)
 - [Security Policy](SECURITY.md)
 - [Contributing Guidelines](CONTRIBUTING.md)

package/dist/cdp/bridge.d.ts

@@ -4,6 +4,7 @@ export interface BrowserInfo {
     name: string;
     path: string;
 }
+export declare function isValidElectronExecutablePath(execPath: string): boolean;
 export declare function findBrowser(preferred?: string): BrowserInfo | null;
 export declare function findFirefox(): BrowserInfo | null;
 export declare function probeAllBrowsers(): BrowserInfo[];
@@ -14,3 +15,12 @@ export declare function launchWithBridge(config: Config): Promise<{
     engine?: BrowserEngine;
 }>;
 export declare function injectStealthScript(session: CDP.Client): Promise<void>;
+export declare function getFreePort(preferredPort?: number): Promise<number>;
+export declare function testPortListening(port: number): Promise<boolean>;
+export declare function launchElectronApp(appName: string, config: Config): Promise<{
+    path: string;
+    name: string;
+    port: number;
+    engine: "chromium";
+    isElectron: true;
+}>;

package/dist/cdp/bridge.js

@@ -12,8 +12,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import CDP from "chrome-remote-interface";
 import { readLock, writeLock, clearLock, isLockValid, isLockPending } from "./lock.js";
-import { getSessionProfile } from "./profiles.js";
-import { getOutputDir, getDownloadDir, getConfigHeadless, getConfigProxy, getConfigDisableExtensions, getConfigDevMode, getConfigBlock, getConfigAllow, getConfigBrowserType, getConfigBrowserPath, getConfigBrowserFlags, getConfigCookies, getConfigProfileDir, getSystemDir } from "../config/loader.js";
+import { getSessionProfile, getElectronProfile } from "./profiles.js";
+import net from "node:net";
+import { getOutputDir, getDownloadDir, getConfigHeadless, getConfigProxy, getConfigDevMode, getConfigBlock, getConfigAllow, getConfigBrowserType, getConfigBrowserPath, getConfigBrowserFlags, getConfigCookies, getConfigProfileDir, getSystemDir, getElectronAppConfig, getConfigExtension } from "../config/loader.js";
 import { createBrowserFingerprint } from "./security.js";
 function withCDPTimeout(promise, ms, label) {
     return Promise.race([
@@ -97,6 +98,37 @@ function isValidBrowserPath(browserPath) {
     }
     return true;
 }
+export function isValidElectronExecutablePath(execPath) {
+    if (!execPath || typeof execPath !== "string")
+        return false;
+    const normalizedPath = execPath.toLowerCase().trim();
+    // Check for suspicious patterns that might indicate command injection or shell escapes
+    const suspiciousPatterns = [
+        '..', // path traversal
+        '%', // URL encoding
+        'cmd.exe', 'powershell.exe', 'bash', 'sh', 'wscript.exe', 'cscript.exe'
+    ];
+    if (suspiciousPatterns.some(pattern => normalizedPath.includes(pattern))) {
+        logDebug(`[SECURITY] Electron path validation failed: suspicious pattern in path: ${execPath}`);
+        return false;
+    }
+    // Verify that the file actually exists
+    try {
+        if (!fs.existsSync(execPath)) {
+            logDebug(`[SECURITY] Electron path validation failed: file does not exist: ${execPath}`);
+            return false;
+        }
+        const stat = fs.statSync(execPath);
+        if (!stat.isFile()) {
+            logDebug(`[SECURITY] Electron path validation failed: target is not a file: ${execPath}`);
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
 function pathsForPlatform(browserName) {
     const plat = os.platform();
     const winPaths = [];
@@ -424,14 +456,6 @@ function getLaunchFlags(config, extPath) {
         flags.push("--headless=new");
     if (getConfigProxy(config))
         flags.push(`--proxy-server=${getConfigProxy(config)}`);
-    // disableExtensions: NOTE — --disable-extensions kills ALL extensions including ours.
-    // --load-extension does NOT reliably override --disable-extensions on Edge.
-    // Since we can't disable other extensions while keeping ours (unpacked extensions
-    // have unpredictable IDs), we skip the flag entirely and let other extensions coexist.
-    // The user can manually disable extensions in their browser profile if needed.
-    if (getConfigDisableExtensions(config)) {
-        logDebug("[Weavetab] [SAFETY] disableExtensions=true — cannot safely disable other extensions while keeping Weavetab extension. Loading extension alongside any existing ones.");
-    }
     // devMode: enable verbose remote debugging
     if (getConfigDevMode(config)) {
         flags.push("--enable-logging", "--v=1");
@@ -477,7 +501,7 @@ export async function launchWithBridge(config) {
             "  - Google Chrome (https://www.google.com/chrome/)\n" +
             "  - Brave (https://brave.com/)\n" +
             "  - Microsoft Edge (https://www.microsoft.com/edge)\n" +
-            "  If you have a browser installed in a custom location, set it via: wt config browserPath \"/path/to/browser\"");
+            "  If you have a browser installed in a custom location, set it via: weavetab config browserPath \"/path/to/browser\"");
     }
     const debugPort = 0;
     const lock = readLock();
@@ -524,45 +548,53 @@ export async function launchWithBridge(config) {
             await new Promise(r => setTimeout(r, 1500));
         }
         try {
-            let extPath = path.resolve(__dirname, "../../ext-dist");
-            const systemExtPath = getSystemDir("extension");
-            if (fs.existsSync(extPath)) {
-                try {
-                    fs.cpSync(extPath, systemExtPath, { recursive: true, force: true });
+            const enableExtension = getConfigExtension(config) !== false;
+            let extPath = "";
+            let normalizedExtPath = "";
+            if (enableExtension) {
+                extPath = path.resolve(__dirname, "../../ext-dist");
+                const systemExtPath = getSystemDir("extension");
+                if (fs.existsSync(extPath)) {
+                    try {
+                        fs.cpSync(extPath, systemExtPath, { recursive: true, force: true });
+                    }
+                    catch (e) {
+                        logDebug(`[Weavetab] Failed to sync extension to system directory: ${e}`);
+                    }
                 }
-                catch (e) {
-                    logDebug(`[Weavetab] Failed to sync extension to system directory: ${e}`);
+                else {
+                    if (fs.existsSync(systemExtPath)) {
+                        logDebug(`[Weavetab] Local extension missing. Falling back to system extension directory.`);
+                        extPath = systemExtPath;
+                    }
+                    else {
+                        throw new Error(`[Weavetab] Extension directory does not exist: ${extPath}. Build the extension first.`);
+                    }
                 }
-            }
-            else {
-                if (fs.existsSync(systemExtPath)) {
-                    logDebug(`[Weavetab] Local extension missing. Falling back to system extension directory.`);
-                    extPath = systemExtPath;
+                const manifestPath = path.join(extPath, "manifest.json");
+                const contentPath = path.join(extPath, "content.js");
+                const backgroundPath = path.join(extPath, "background.js");
+                if (!fs.existsSync(manifestPath)) {
+                    throw new Error(`[Weavetab] Extension manifest missing: ${manifestPath}`);
                 }
-                else {
-                    throw new Error(`[Weavetab] Extension directory does not exist: ${extPath}. Build the extension first.`);
+                if (!fs.existsSync(contentPath)) {
+                    throw new Error(`[Weavetab] Extension content script missing: ${contentPath}`);
                 }
+                if (!fs.existsSync(backgroundPath)) {
+                    throw new Error(`[Weavetab] Extension background script missing: ${backgroundPath}`);
+                }
+                normalizedExtPath = os.platform() === 'win32'
+                    ? extPath.replace(/\//g, '\\')
+                    : extPath;
             }
-            const manifestPath = path.join(extPath, "manifest.json");
-            const contentPath = path.join(extPath, "content.js");
-            const backgroundPath = path.join(extPath, "background.js");
-            if (!fs.existsSync(manifestPath)) {
-                throw new Error(`[Weavetab] Extension manifest missing: ${manifestPath}`);
-            }
-            if (!fs.existsSync(contentPath)) {
-                throw new Error(`[Weavetab] Extension content script missing: ${contentPath}`);
-            }
-            if (!fs.existsSync(backgroundPath)) {
-                throw new Error(`[Weavetab] Extension background script missing: ${backgroundPath}`);
+            else {
+                logDebug(`[Weavetab] Browser extension loading disabled via config (extension: false).`);
             }
             const resolvedDownloadDir = getDownloadDir(config) && getDownloadDir(config).trim()
                 ? getDownloadDir(config).trim()
                 : getOutputDir("downloads", config);
             // Normalize paths for cross-platform compatibility
             const platform = os.platform();
-            const normalizedExtPath = platform === 'win32'
-                ? extPath.replace(/\//g, '\\')
-                : extPath;
             const normalizedProfileDir = platform === 'win32'
                 ? profileDir.replace(/\//g, '\\')
                 : profileDir;
@@ -584,40 +616,34 @@ export async function launchWithBridge(config) {
                     fs.unlinkSync(singletonCookie);
             }
             catch { /* non-fatal */ }
-            // Wipe the MV3 service worker cache before every launch so Chrome always
-            // executes the latest background.js from disk rather than a stale cached
-            // script stored in the profile. Without this, edits to ext-dist/background.js
-            // have no effect until Chrome manually reloads the extension — the SW cache
-            // (Default/Service Worker/ScriptCache + Default/Service Worker/Database) is
-            // keyed by URL hash and persists across sessions in the user-data-dir.
-            // This ensures any future background.js change takes effect immediately
-            // on all existing profiles without manual cache clearing.
-            try {
-                const swBase = path.join(profileDir, "Default", "Service Worker");
-                const swScriptCache = path.join(swBase, "ScriptCache");
-                const swDatabase = path.join(swBase, "Database");
-                if (fs.existsSync(swScriptCache)) {
-                    fs.rmSync(swScriptCache, { recursive: true, force: true });
-                    logDebug("[Weavetab] Wiped SW ScriptCache to force background.js reload.");
+            if (enableExtension) {
+                // Wipe the MV3 service worker cache before every launch so Chrome always
+                // executes the latest background.js from disk rather than a stale cached
+                // script stored in the profile.
+                try {
+                    const swBase = path.join(profileDir, "Default", "Service Worker");
+                    const swScriptCache = path.join(swBase, "ScriptCache");
+                    const swDatabase = path.join(swBase, "Database");
+                    if (fs.existsSync(swScriptCache)) {
+                        fs.rmSync(swScriptCache, { recursive: true, force: true });
+                        logDebug("[Weavetab] Wiped SW ScriptCache to force background.js reload.");
+                    }
+                    if (fs.existsSync(swDatabase)) {
+                        fs.rmSync(swDatabase, { recursive: true, force: true });
+                        logDebug("[Weavetab] Wiped SW Database to force background.js reload.");
+                    }
                 }
-                if (fs.existsSync(swDatabase)) {
-                    fs.rmSync(swDatabase, { recursive: true, force: true });
-                    logDebug("[Weavetab] Wiped SW Database to force background.js reload.");
+                catch (swErr) {
+                    logDebug(`[Weavetab] SW cache wipe failed (non-fatal): ${swErr}`);
                 }
             }
-            catch (swErr) {
-                logDebug(`[Weavetab] SW cache wipe failed (non-fatal): ${swErr}`);
-            }
             const args = [
                 `--remote-debugging-port=${debugPort}`,
                 `--user-data-dir=${normalizedProfileDir}`,
                 `--default-download-dir=${normalizedDownloadDir}`,
                 ...getLaunchFlags(config, extPath),
                 ...filterBrowserFlags(getConfigBrowserFlags(config) || []),
-                `--load-extension=${normalizedExtPath}`,
-                // NOTE: --disable-extensions-except was removed. It was killing any
-                // extensions the user manually loaded into the Weavetab profile.
-                // --load-extension alone is sufficient to auto-load the Weavetab extension.
+                ...(enableExtension ? [`--load-extension=${normalizedExtPath}`] : []),
                 "about:blank",
             ];
             let pid;
@@ -686,25 +712,27 @@ export async function launchWithBridge(config) {
             }
             else {
                 logDebug(`[Weavetab] [OK] ${browser.name} ready on :${actualPort} (attempt ${attempt})`);
-                // Verify extension loaded by checking for extension pages.
+                // Verify extension loaded by checking for extension pages if extension is enabled.
                 // MV3 service workers can take 1-3s to initialize after Chrome starts,
                 // so we wait briefly before querying targets.
-                try {
-                    await new Promise(r => setTimeout(r, 1500));
-                    const testSession = await withCDPTimeout(CDP({ host: "127.0.0.1", port: actualPort }), 4000, "CDP connect");
-                    const { targetInfos } = await withCDPTimeout(testSession.Target.getTargets(), 4000, "getTargets");
-                    const extensionTargets = targetInfos.filter(t => t.type === "service_worker" || (t.type === "page" && t.url.startsWith("chrome-extension://")));
-                    await testSession.close();
-                    if (extensionTargets.length > 0) {
-                        logDebug(`[Weavetab] [OK] Extension loaded - found ${extensionTargets.length} extension target(s)`);
+                if (enableExtension) {
+                    try {
+                        await new Promise(r => setTimeout(r, 1500));
+                        const testSession = await withCDPTimeout(CDP({ host: "127.0.0.1", port: actualPort }), 4000, "CDP connect");
+                        const { targetInfos } = await withCDPTimeout(testSession.Target.getTargets(), 4000, "getTargets");
+                        const extensionTargets = targetInfos.filter(t => t.type === "service_worker" || (t.type === "page" && t.url.startsWith("chrome-extension://")));
+                        await testSession.close();
+                        if (extensionTargets.length > 0) {
+                            logDebug(`[Weavetab] [OK] Extension loaded - found ${extensionTargets.length} extension target(s)`);
+                        }
+                        else {
+                            logDebug(`[Weavetab] [!] Extension may not have loaded - no extension targets found. Check chrome://extensions in the browser.`);
+                        }
                     }
-                    else {
-                        logDebug(`[Weavetab] [!] Extension may not have loaded - no extension targets found. Check chrome://extensions in the browser.`);
+                    catch (extCheckErr) {
+                        logDebug(`[Weavetab] [!] Could not verify extension load: ${extCheckErr}`);
                     }
                 }
-                catch (extCheckErr) {
-                    logDebug(`[Weavetab] [!] Could not verify extension load: ${extCheckErr}`);
-                }
             }
             await writeLock({ pid, port: actualPort, profileDir, browserPath: browser.path, mode: "session", pending: false });
             recordLaunchSuccess(profileDir);
@@ -838,3 +866,182 @@ async function resolvePortFromStderr(proc, pid, _engine) {
         });
     });
 }
+export async function getFreePort(preferredPort = 9222) {
+    const isAvailable = (p) => {
+        return new Promise((resolve) => {
+            const s = net.createServer();
+            s.once("error", () => resolve(false));
+            s.once("listening", () => {
+                s.close(() => resolve(true));
+            });
+            s.listen(p, "127.0.0.1");
+        });
+    };
+    if (preferredPort > 0 && (await isAvailable(preferredPort))) {
+        return preferredPort;
+    }
+    return new Promise((resolve, reject) => {
+        const s = net.createServer();
+        s.once("error", reject);
+        s.once("listening", () => {
+            const addr = s.address();
+            const p = typeof addr === "object" && addr ? addr.port : 9222;
+            s.close(() => resolve(p));
+        });
+        s.listen(0, "127.0.0.1");
+    });
+}
+export function testPortListening(port) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        const timeout = setTimeout(() => {
+            socket.destroy();
+            resolve(false);
+        }, 1000);
+        socket.connect(port, "127.0.0.1", () => {
+            clearTimeout(timeout);
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on("error", () => {
+            clearTimeout(timeout);
+            resolve(false);
+        });
+    });
+}
+export async function launchElectronApp(appName, config) {
+    const appCfg = getElectronAppConfig(appName, config);
+    if (!appCfg) {
+        throw new Error(`[Weavetab] ✗ Electron app "${appName}" is not configured in config.json.\n` +
+            `  Please add an entry under "electron": { "${appName}": "C:\\\\path\\\\to\\\\app.exe" } in your config.`);
+    }
+    // 1. Direct port dev attach mode (e.g., dev server or npm run dev)
+    if (appCfg.port && !appCfg.path) {
+        const isAlive = await testPortListening(appCfg.port);
+        if (isAlive) {
+            logDebug(`[Weavetab] Attached to live Electron dev server on port ${appCfg.port}`);
+            return { path: "dev-server", name: appName, port: appCfg.port, engine: "chromium", isElectron: true };
+        }
+        throw new Error(`[Weavetab] ✗ Electron dev app "${appName}" on port ${appCfg.port} is not responding. Ensure your dev server is running.`);
+    }
+    // 2. Direct URL dev attach mode
+    if (appCfg.url && !appCfg.path) {
+        try {
+            const parsed = new URL(appCfg.url);
+            const port = parseInt(parsed.port || (parsed.protocol === "https:" ? "443" : "80"), 10);
+            const isAlive = await testPortListening(port);
+            if (isAlive) {
+                logDebug(`[Weavetab] Attached to live Electron app at ${appCfg.url} (port ${port})`);
+                return { path: appCfg.url, name: appName, port, engine: "chromium", isElectron: true };
+            }
+            throw new Error(`[Weavetab] ✗ Electron dev app "${appName}" at ${appCfg.url} is not responding.`);
+        }
+        catch (e) {
+            throw new Error(`[Weavetab] ✗ Invalid or unreachable dev URL for "${appName}": ${e?.message || e}`);
+        }
+    }
+    const { resolveElectronExecutablePath } = await import("../desktop/discovery.js");
+    const execPath = resolveElectronExecutablePath(appName, appCfg.path) || appCfg.path;
+    if (!execPath || !isValidElectronExecutablePath(execPath)) {
+        throw new Error(`[Weavetab] ✗ Invalid or non-existent Electron executable path for "${appName}": ${execPath}`);
+    }
+    // Check app-scoped lock
+    const lock = readLock(appName);
+    if (lock && lock.mode === "session") {
+        if (isLockPending(lock)) {
+            logDebug(`[Weavetab] Launch already in progress for ${appName} (PID: ${lock.pid}). Waiting...`);
+            throw new Error(`Launch already in progress for ${appName}. Wait for it to complete.`);
+        }
+        const valid = await isLockValid(lock);
+        if (valid) {
+            logDebug(`[Weavetab] [OK] Reusing valid Electron lock for ${appName} (PID: ${lock.pid}, Port: ${lock.port})`);
+            return { path: execPath, name: appName, port: lock.port, engine: "chromium", isElectron: true };
+        }
+        logDebug(`[Weavetab] [!] Stale lock detected for ${appName}. Clearing.`);
+        clearLock(appName);
+    }
+    else if (lock) {
+        clearLock(appName);
+    }
+    const profileDir = getElectronProfile(appName, appCfg.profileDir);
+    const actualPort = appCfg.port && appCfg.port > 0 ? appCfg.port : await getFreePort(9222);
+    // Clean up SingletonLock
+    const singletonLock = path.join(profileDir, "SingletonLock");
+    const singletonCookie = path.join(profileDir, "SingletonCookie");
+    try {
+        if (fs.existsSync(singletonLock))
+            fs.unlinkSync(singletonLock);
+    }
+    catch { /* non-fatal */ }
+    try {
+        if (fs.existsSync(singletonCookie))
+            fs.unlinkSync(singletonCookie);
+    }
+    catch { /* non-fatal */ }
+    const platform = os.platform();
+    const normalizedProfileDir = platform === 'win32'
+        ? profileDir.replace(/\//g, '\\')
+        : profileDir;
+    const resolvedDownloadDir = getDownloadDir(config) && getDownloadDir(config).trim()
+        ? getDownloadDir(config).trim()
+        : getOutputDir("downloads", config);
+    const normalizedDownloadDir = platform === 'win32'
+        ? resolvedDownloadDir.replace(/\//g, '\\')
+        : resolvedDownloadDir;
+    // Notice: Clean Electron launch flags: only isolated user-data-dir, remote-debugging-port, and optional user args.
+    // We NEVER pass Chromium browser flags or extension flags to Electron binaries.
+    const args = [
+        `--remote-debugging-port=${actualPort}`,
+        `--user-data-dir=${normalizedProfileDir}`,
+        `--default-download-dir=${normalizedDownloadDir}`,
+        "--no-first-run",
+        "--no-default-browser-check",
+        ...(appCfg.args || []),
+    ];
+    const spawnOptions = {
+        detached: true,
+        stdio: "ignore",
+    };
+    if (platform === 'darwin' && execPath.includes('.app')) {
+        spawnOptions.shell = true;
+    }
+    const proc = spawn(execPath, args, spawnOptions);
+    proc.unref();
+    const pid = proc.pid;
+    logDebug(`[Weavetab] Launching Electron app ${appName} (PID: ${pid}, port: ${actualPort}).`);
+    // Poll CDP endpoint on actualPort
+    let confirmed = false;
+    for (let i = 0; i < 20; i++) {
+        try {
+            await withCDPTimeout(CDP.List({ host: "127.0.0.1", port: actualPort }), 1500, "CDP.List Electron");
+            confirmed = true;
+            break;
+        }
+        catch {
+            await new Promise(r => setTimeout(r, 600));
+        }
+    }
+    if (!confirmed) {
+        const isListening = await testPortListening(actualPort);
+        if (!isListening) {
+            try {
+                if (pid)
+                    process.kill(pid);
+            }
+            catch { /* ignore */ }
+            clearLock(appName);
+            throw new Error(`[Weavetab] Electron app ${appName} failed to start CDP listener on port ${actualPort} after 12s.`);
+        }
+    }
+    await writeLock({
+        pid,
+        port: actualPort,
+        profileDir,
+        browserPath: execPath,
+        mode: "session",
+        appName,
+        pending: false,
+        timestamp: Date.now(),
+    }, appName);
+    return { path: execPath, name: appName, port: actualPort, engine: "chromium", isElectron: true };
+}

package/dist/cdp/connector.d.ts

@@ -17,12 +17,16 @@ export interface BrowserClient {
     overlayInstalled: boolean;
     agentId: string;
     browserContextId?: string;
+    appName?: string;
+    isElectron?: boolean;
     /** Sticky pruning state: if true, all subsequent DOM reads by action tools (click, type, etc.) will also apply pruning. */
     pruneActive?: boolean;
+    /** Port the CDP session is connected to */
+    port?: number;
 }
-export declare function getOrConnect(config: Config): Promise<BrowserClient>;
-export declare function getTabList(agentId?: string): Promise<any[]>;
-export declare function connectToTab(targetId: string, port?: number, agentId?: string, browserContextId?: string): Promise<BrowserClient>;
+export declare function getOrConnect(config: Config, targetApp?: string): Promise<BrowserClient>;
+export declare function getTabList(agentId?: string, targetApp?: string): Promise<any[]>;
+export declare function connectToTab(targetId: string, port?: number, agentId?: string, browserContextId?: string, appName?: string): Promise<BrowserClient>;
 /**
  * Cancel analytics intervals and close the CDP WebSocket sessions without
  * touching the browser process. Safe to call in server mode — the browser