webhelm 1.0.2 → 1.0.4

package/README.md

@@ -6,7 +6,7 @@
 
 | Repository | Contents | Updates |
 |---|---|---|
-| [`lalalic/webhelm`](https://github.com/lalalic/webhelm) | npm Runtime/CLI, Skill (`skills/webhelm`), Chrome Extension, tests | npm `webhelm@latest`; Skill source separately |
+| [`lalalic/webhelm`](https://github.com/lalalic/webhelm) | npm Runtime/CLI (including the Daemon-managed Chrome Extension), Skill (`skills/webhelm`), tests | npm `webhelm@latest`; Skill source separately |
 | [`lalalic/webhelm-actions`](https://github.com/lalalic/webhelm-actions) | Site manifests, ChatGPT/Z.ai/DeepSeek/XHS/etc. Actions | Git checkout at `~/.local/webhelm` |
 
 The npm package **does not include** the Skill or site Actions. The Skill's executable uses `npm exec --yes --package=webhelm@latest -- webhelm` to avoid inherited npm lifecycle variable conflicts; its contents may update without a Runtime release.
@@ -27,7 +27,7 @@ npx --yes webhelm@latest session stop SESSION_ID
 # Long-running worker managers: session heartbeat SESSION_ID every 60 seconds
 ```
 
-Use `npx skills add lalalic/webhelm --skill webhelm` to install agent guidance and the bundled Extension source. The Skill lives **in this repo** at `skills/webhelm/SKILL.md`.
+Use `npx skills add lalalic/webhelm --skill webhelm` to install agent guidance. The Extension is bundled with the npm Runtime and staged by WebHelm Daemon at `~/.local/webhelm/extension`. The Skill lives **in this repo** at `skills/webhelm/SKILL.md`. No Chrome Web Store publication or manual Extension installation is required.
 
 The Actions checkout is `~/.local/webhelm`, with site modules at `~/.local/webhelm/platforms`. Setup clones if absent, then reuses that checkout without discarding local modifications. Run `platform sync` for new commits. For a verified local Action fix, `platform publish --message "..."` tests, commits and pushes only the action changes to the separate repo.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webhelm",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Agent browser automation in a visible managed Chrome with persistent JavaScript sessions",
   "type": "module",
   "bin": {

package/runtime/chrome.mjs

@@ -3,7 +3,8 @@ import path from 'node:path';
 import net from 'node:net';
 import { spawn, execFileSync } from 'node:child_process';
 
-import { CONFIG_ROOT, PROFILE_DIR, requireMigratedConfig } from './config-paths.mjs';
+import { CONFIG_ROOT, PROFILE_DIR, OLD_PROFILE_DIR, requireMigratedConfig } from './config-paths.mjs';
+import { stageExtension } from './extension-manager.mjs';
 const ROOT = CONFIG_ROOT;
 const PROFILE = PROFILE_DIR;
 const STATE = path.join(ROOT, 'managed-chrome.json');
@@ -90,6 +91,24 @@ async function lockOwnership(fn) {
   try {return await fn();}
   finally {fs.closeSync(fd);try {fs.unlinkSync(LOCK);}catch{}}
 }
+export function chromeMajorFromVersion(versionText){
+  const match=String(versionText).match(/(?:Chrome|Chromium)\s+(?:for Testing\s+)?(\d+)\./);
+  const major=match?Number(match[1]):NaN;
+  if(!Number.isSafeInteger(major)||major<50)throw Error(`Cannot determine managed Chrome version: ${versionText}`);
+  return major;
+}
+function chromeMajor(chromePath){
+  return chromeMajorFromVersion(execFileSync(chromePath,['--version'],{encoding:'utf8',timeout:5000}).trim());
+}
+export function chromeLaunchArgs(profile,port,extensionPath,major){
+  const args=[`--user-data-dir=${profile}`,`--remote-debugging-port=${port}`];
+  // Chrome 138 can load unpacked extensions with a compatibility flag.
+  // Chrome 139+ must rely on Extensions.loadUnpacked through CDP instead:
+  // passing --load-extension can leave a stale, non-running extension entry.
+  if(major<=138)args.push('--disable-features=DisableLoadExtensionCommandLineSwitch',`--load-extension=${extensionPath}`);
+  args.push('--no-first-run','--no-default-browser-check','about:blank');
+  return args;
+}
 export async function ensureManagedChrome(){
   // Explicit CDP endpoints also support hermetic mock-browser tests.
   const specified=process.env.WEBHELM_CDP_URL;
@@ -103,10 +122,10 @@ export async function ensureManagedChrome(){
     if(override)return {mode:'override',reused:true,endpoint:override,profile_dir:PROFILE};
     const port=await choosePort();
     const chrome=browserExecutable();
+    const extension=stageExtension();
     const log=fs.openSync(path.join(ROOT,'managed-chrome.log'),'a');
     fs.mkdirSync(PROFILE,{recursive:true});
-    const child=spawn(chrome,[`--user-data-dir=${PROFILE}`,`--remote-debugging-port=${port}`,
-      '--no-first-run','--no-default-browser-check','about:blank'],
+    const child=spawn(chrome,chromeLaunchArgs(PROFILE,port,extension.path,chromeMajor(chrome)),
       {detached:true,stdio:['ignore',log,log]});
     child.unref();
     fs.closeSync(log);

package/runtime/cli.mjs

@@ -7,7 +7,7 @@ import { randomUUID } from 'node:crypto';
 import { ensureDaemon, request, handle, SOCKET } from './node-daemon.mjs';
 import { PLATFORMS, listPlatforms, platformProfile, actionPath, validateConfig } from './platforms.mjs';
 import { ACTIONS_DIR, ensureActions, syncActions, publishActions } from './actions-repo.mjs';
-import { migrateConfig } from './migrate.mjs';
+import { migrateConfig, migrateChromeProfile } from './migrate.mjs';
 
 const ROOT = path.dirname(fileURLToPath(import.meta.url));
 const emit = value => console.log(JSON.stringify(value));
@@ -99,7 +99,12 @@ async function runPlatform(args) {
 async function main(args = process.argv.slice(2)) {
   const [group, command] = args;
   if (!group || ['--help', '-h', 'help'].includes(group) || has(args, '--help') || has(args, '-h')) return help();
-  if (group === 'migrate') return emit(await migrateConfig());
+  if (group === 'migrate') {
+    await ensureActions(); // ~/.local/webhelm is the Actions Git checkout, never create an empty replacement.
+    const legacy=await migrateConfig();
+    const chrome=await migrateChromeProfile();
+    return emit({legacy,chrome});
+  }
   if (group === 'setup') {
     const repo=await ensureActions();
     const chrome=await ensureDaemon();
@@ -107,7 +112,7 @@ async function main(args = process.argv.slice(2)) {
   }
   if (group === 'status') {
     const daemon = await ensureDaemon();
-    return emit({version:'1.0.1', platform_dir:PLATFORMS, root:ROOT,
+    return emit({version:daemon.version, platform_dir:PLATFORMS, root:ROOT,
       cli:fileURLToPath(import.meta.url),
       admin_helper:process.env.WEBHELM_ADMIN_HELPER || (fs.existsSync(path.join(os.homedir(),'.agents/skills/webhelm/scripts/admin.mjs')) ? path.join(os.homedir(),'.agents/skills/webhelm/scripts/admin.mjs') : path.join(ROOT,'admin.mjs')),
       managed_chrome:daemon.managed_chrome,

package/runtime/config-paths.mjs

@@ -4,11 +4,18 @@ import fs from 'node:fs';
 
 export const CONFIG_ROOT = path.join(os.homedir(), '.config', 'webhelm');
 export const LEGACY_ROOT = path.join(os.homedir(), '.config', 'browser-workspace');
-export const PROFILE_DIR = path.join(CONFIG_ROOT, 'chrome');
+export const LOCAL_ROOT = path.join(os.homedir(), '.local', 'webhelm');
+export const OLD_PROFILE_DIR = path.join(CONFIG_ROOT, 'chrome');
+export const PROFILE_DIR = path.join(LOCAL_ROOT, 'chrome');
 export const RUNTIME_DIR = path.join(CONFIG_ROOT, 'runtime');
 
 // Avoid starting a second FIFO dispatcher or empty Chrome profile against legacy data.
 export function requireMigratedConfig() {
-  if (fs.existsSync(path.join(LEGACY_ROOT, 'chrome')) && !fs.existsSync(PROFILE_DIR))
+  if (fs.existsSync(path.join(LEGACY_ROOT, 'chrome')) && !fs.existsSync(OLD_PROFILE_DIR) && !fs.existsSync(PROFILE_DIR))
     throw Error(`Legacy Chrome profile exists at ${LEGACY_ROOT}. Stop old Chrome and WebHelm daemon, then run webhelm migrate.`);
+  if (fs.existsSync(OLD_PROFILE_DIR) && !fs.existsSync(PROFILE_DIR))
+    throw Error(`Chrome profile is still at ${OLD_PROFILE_DIR}. Stop active Sessions, WebHelm daemon and managed Chrome, then run webhelm migrate.`);
+  if (fs.existsSync(OLD_PROFILE_DIR) && fs.existsSync(PROFILE_DIR) &&
+      fs.realpathSync(OLD_PROFILE_DIR)!==fs.realpathSync(PROFILE_DIR))
+    throw Error('Two distinct WebHelm Chrome Profiles exist; refusing to use either until reconciled.');
 }

package/runtime/extension/manifest.json

@@ -0,0 +1,25 @@
+{
+  "manifest_version": 3,
+  "name": "Browser Workspace",
+  "version": "0.3.3",
+  "description": "Own named Chrome tab-group workspaces and lazy reusable tab pools for browser agents.",
+  "permissions": [
+    "storage",
+    "tabs",
+    "tabGroups",
+    "webNavigation",
+    "contextMenus"
+  ],
+  "host_permissions": [
+    "http://*/*",
+    "https://*/*"
+  ],
+  "background": {
+    "service_worker": "service-worker.mjs",
+    "type": "module"
+  },
+  "action": {
+    "default_title": "Browser Workspace"
+  },
+  "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtovrqHYRxYDBSofmlykO8RDtsePhg8KV1fmq07nnhtbmYiNXAnIKrgRyLHeZv+cwm9DSgP5Ig7FDJ7Q6XrSi+Z1FpU6Y/SJkX5Rozo0oAJcX1ggoGD3vxpfHZThSSG/vRSnD8pH3XFf2nDUD7QP6GXc8dX9lN5pslRUNh1J4UCAOcu2UpPSsvpA+wPPTZr2JYzm3AevFXkQM6y0B+4exgw/Hy21ULST4nLWZihuCSu+gfWnftiTNzUPHtseRJcrpd0zT0R46d+OC+JRwXMVBpYSksDDtOXgERwMBSZf+vvskrEqYoXKN8Z9+Rrr7y9PTOvlwQioVLEDEjr9e7RIegQIDAQAB"
+}

package/runtime/extension/service-worker.mjs

@@ -0,0 +1,117 @@
+import { WorkspaceManager } from "./workspace-manager.mjs";
+
+const manager = new WorkspaceManager(chrome);
+const closingWindowIds = new Set();
+
+
+manager.restoreConfiguredWorkspaces().catch((error) => {
+  console.warn("Browser Workspace failed to restore configured workspaces", error);
+});
+
+const RELEASE_ALL_MENU_ID = "browser-workspace.release-all";
+
+async function ensureContextMenus() {
+  try {
+    await chrome.contextMenus.remove(RELEASE_ALL_MENU_ID);
+  } catch {
+    // Menu does not exist yet.
+  }
+  chrome.contextMenus.create({
+    id: RELEASE_ALL_MENU_ID,
+    title: "Release all tabs",
+    contexts: ["action"],
+  });
+}
+
+chrome.runtime.onInstalled.addListener(() => {
+  ensureContextMenus().catch((error) => {
+    console.warn("Browser Workspace failed to create extension menu", error);
+  });
+});
+
+chrome.runtime.onStartup.addListener(() => {
+  ensureContextMenus().catch((error) => {
+    console.warn("Browser Workspace failed to create extension menu", error);
+  });
+});
+
+ensureContextMenus().catch((error) => {
+  console.warn("Browser Workspace failed to initialize extension menu", error);
+});
+
+chrome.contextMenus.onClicked.addListener((info) => {
+  if (info.menuItemId !== RELEASE_ALL_MENU_ID) return;
+  manager.releaseAll().catch((error) => {
+    console.warn("Browser Workspace failed to release all tabs", error);
+  });
+});
+
+globalThis.browserWorkspaceManagerRpc = async (request) => {
+  try {
+    return { ok: true, result: await manager.rpc(request) };
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        message: error?.message || String(error),
+        name: error?.name || "Error",
+      },
+    };
+  }
+};
+
+chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {
+  globalThis.browserWorkspaceManagerRpc(request).then(sendResponse);
+  return true;
+});
+
+chrome.tabs.onCreated.addListener((tab) => {
+  manager.inheritWorkspaceForCreatedTab(tab).catch((error) => {
+    console.warn("Browser Workspace failed to inherit child tab group", error);
+  });
+
+  setTimeout(() => {
+    manager.reconcileCreatedTab(tab.id).catch((error) => {
+      if (!/No tab with id|Invalid tab ID/i.test(String(error?.message || error))) {
+        console.warn("Browser Workspace failed delayed created-tab reconciliation", error);
+      }
+    });
+  }, 150);
+});
+
+chrome.webNavigation.onCreatedNavigationTarget.addListener((details) => {
+  manager.inheritNavigationTarget(details).catch((error) => {
+    console.warn("Browser Workspace failed to inherit navigation target", error);
+  });
+});
+
+chrome.tabs.onUpdated.addListener((_tabId, changeInfo, tab) => {
+  if (!Object.prototype.hasOwnProperty.call(changeInfo, "groupId")) return;
+  manager.inheritWorkspaceForCreatedTab(tab).catch((error) => {
+    console.warn("Browser Workspace failed to reconcile tab group ownership", error);
+  });
+});
+
+chrome.tabs.onActivated.addListener((activeInfo) => {
+  manager.noteActivatedTab(activeInfo).catch((error) => {
+    console.warn("Browser Workspace failed to record active tab context", error);
+  });
+});
+
+chrome.tabs.onRemoved.addListener((_tabId, removeInfo) => {
+  if (!removeInfo?.isWindowClosing) return;
+  closingWindowIds.add(removeInfo.windowId);
+  setTimeout(() => closingWindowIds.delete(removeInfo.windowId), 1000);
+});
+
+chrome.tabGroups.onRemoved.addListener((group) => {
+  // Chrome also emits onRemoved while moving a group between windows, and
+  // while a whole window is closing. Defer one turn so a moved group can
+  // reappear, and preserve persisted workspaces across normal window closes.
+  setTimeout(() => {
+    if (closingWindowIds.has(group.windowId)) return;
+    manager.removeDeletedGroup(group).catch((error) => {
+      console.warn("Browser Workspace failed to remove deleted workspace", error);
+    });
+  }, 100);
+});

package/runtime/extension/workspace-manager.mjs

@@ -0,0 +1,661 @@
+const STORAGE_KEY = "browserWorkspaceManager.v1";
+const MIN_POOL_SIZE = 1;
+const MAX_POOL_SIZE = 64;
+const EXTENSION_MANAGEMENT_RECENCY_MS = 15_000;
+
+export function normalizeWorkspaceName(value) {
+  const name = String(value || "").trim();
+  if (!name) throw new Error("Workspace name is required");
+  if (name.length > 80) throw new Error("Workspace name must be at most 80 characters");
+  return name;
+}
+
+export function normalizePoolSize(value, fallback = 8) {
+  const number = Number(value ?? fallback);
+  if (!Number.isInteger(number) || number < MIN_POOL_SIZE || number > MAX_POOL_SIZE) {
+    throw new Error(`Pool size must be an integer between ${MIN_POOL_SIZE} and ${MAX_POOL_SIZE}`);
+  }
+  return number;
+}
+
+function queryString(workspace, slot) {
+  return new URLSearchParams({ workspace, role: "idle", slot: String(slot) }).toString();
+}
+
+export class WorkspaceManager {
+  constructor(chromeApi) {
+    this.chrome = chromeApi;
+    this.recentExtensionManagementByWindow = new Map();
+    this.ownedTabIds = new Set();
+  }
+
+  isOwnedTab(tab) {
+    const tabId = Number(tab?.id);
+    if (Number.isInteger(tabId) && this.ownedTabIds.has(tabId)) return true;
+    const meta = this.parseManagedUrl(this.tabUrl(tab));
+    return Boolean(meta?.workspace);
+  }
+
+  markOwned(tabId) {
+    const id = Number(tabId);
+    if (Number.isInteger(id)) this.ownedTabIds.add(id);
+  }
+
+  idleUrl(workspace, slot) {
+    return this.chrome.runtime.getURL(`workspace.html?${queryString(workspace, slot)}`);
+  }
+
+  identityTitle(tabId) {
+    return `__BW_TAB_${tabId}__`;
+  }
+
+  identityUrl(workspace, tabId) {
+    const query = new URLSearchParams({
+      workspace,
+      role: "lease",
+      slot: String(tabId),
+    }).toString();
+    return this.chrome.runtime.getURL(`workspace.html?${query}`);
+  }
+
+  parseManagedUrl(url) {
+    try {
+      const parsed = new URL(url);
+      const own = new URL(this.chrome.runtime.getURL("workspace.html"));
+      if (parsed.origin !== own.origin || parsed.pathname !== own.pathname) return null;
+      return {
+        workspace: parsed.searchParams.get("workspace") || "",
+        role: parsed.searchParams.get("role") || "",
+        slot: parsed.searchParams.get("slot") || "",
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  async loadConfig() {
+    const stored = (await this.chrome.storage.local.get(STORAGE_KEY))[STORAGE_KEY];
+    return stored && typeof stored === "object" ? stored : { workspaces: {} };
+  }
+
+  async saveConfig(config) {
+    await this.chrome.storage.local.set({ [STORAGE_KEY]: config });
+  }
+
+  async configuredWorkspace(name) {
+    const config = await this.loadConfig();
+    return { config, entry: config.workspaces[name] || null };
+  }
+
+  async setPoolSize(name, poolSize) {
+    const { config, entry } = await this.configuredWorkspace(name);
+    config.workspaces[name] = { ...(entry || {}), poolSize };
+    await this.saveConfig(config);
+  }
+
+  async removeConfig(name) {
+    const config = await this.loadConfig();
+    delete config.workspaces[name];
+    await this.saveConfig(config);
+  }
+
+  async removeDeletedGroup(group) {
+    const name = String(group?.title || "").trim();
+    if (!name) return null;
+
+    const { entry } = await this.configuredWorkspace(name);
+    if (!entry) return null;
+
+    const remaining = await this.workspaceGroup(name);
+    if (remaining) return null;
+
+    await this.removeConfig(name);
+    return { name, deleted: true };
+  }
+
+  async workspaceGroup(name) {
+    const groups = await this.chrome.tabGroups.query({});
+    const matches = groups.filter((group) => group.title === name);
+    if (matches.length > 1) {
+      throw new Error(`Workspace ${name} is ambiguous: ${matches.length} groups have that title`);
+    }
+    return matches[0] || null;
+  }
+
+  async groupTabs(groupId) {
+    if (!Number.isInteger(groupId) || groupId < 0) return [];
+    return await this.chrome.tabs.query({ groupId });
+  }
+
+  tabUrl(tab) {
+    return String(tab?.pendingUrl || tab?.url || "");
+  }
+
+  isExtensionManagementUrl(url) {
+    return /^chrome:\/\/extensions(?:\/|\?|#|$)/.test(String(url || ""));
+  }
+
+  isExtensionPageUrl(url) {
+    return /^chrome-extension:\/\//.test(String(url || ""));
+  }
+
+  async noteActivatedTab(activeInfo, now = Date.now()) {
+    const tabId = Number(activeInfo?.tabId);
+    const windowId = Number(activeInfo?.windowId);
+    if (!Number.isInteger(tabId) || !Number.isInteger(windowId)) return null;
+    if (typeof this.chrome.tabs.get !== "function") return null;
+
+    const tab = await this.chrome.tabs.get(tabId);
+    if (!this.isExtensionManagementUrl(this.tabUrl(tab))) return null;
+
+    this.recentExtensionManagementByWindow.set(windowId, now);
+    return { windowId, tabId, recordedAt: now };
+  }
+
+  async uniqueConfiguredWorkspace() {
+    const config = await this.loadConfig();
+    const names = Object.keys(config.workspaces || {});
+    if (!names.length) return null;
+
+    const groups = await this.chrome.tabGroups.query({});
+    const candidates = [];
+    for (const name of names) {
+      const matches = groups.filter((group) => group.title === name);
+      if (matches.length > 1) {
+        throw new Error(`Workspace ${name} is ambiguous: ${matches.length} groups have that title`);
+      }
+      if (matches[0]) {
+        candidates.push({
+          group: matches[0],
+          entry: config.workspaces[name],
+        });
+      }
+    }
+    return candidates.length === 1 ? candidates[0] : null;
+  }
+
+  async inheritNavigationTarget(details) {
+    const sourceTabId = Number(details?.sourceTabId);
+    const tabId = Number(details?.tabId);
+    if (!Number.isInteger(sourceTabId) || !Number.isInteger(tabId)) return null;
+
+    const [source, target] = await Promise.all([
+      this.chrome.tabs.get(sourceTabId),
+      this.chrome.tabs.get(tabId),
+    ]);
+    if (!this.isOwnedTab(source)) return null;
+
+    const groupId = Number(source.groupId);
+    if (!Number.isInteger(groupId) || groupId < 0) return null;
+
+    const groups = await this.chrome.tabGroups.query({});
+    const group = groups.find((candidate) => candidate.id === groupId);
+    if (!group?.title) return null;
+
+    const { entry } = await this.configuredWorkspace(group.title);
+    if (!entry) return null;
+
+    this.markOwned(tabId);
+    await this.chrome.tabs.group({ groupId, tabIds: [tabId] });
+
+    const tabs = await this.groupTabs(groupId);
+    if (tabs.length > entry.poolSize) {
+      const { idle } = this.classify(group.title, tabs);
+      const removable = idle.find((candidate) => candidate.id !== tabId);
+      if (removable) await this.chrome.tabs.remove(removable.id);
+    }
+
+    await this.chrome.tabGroups.update(groupId, {
+      title: group.title,
+      collapsed: true,
+    });
+
+    return {
+      workspace: group.title,
+      groupId,
+      tabId,
+      sourceTabId,
+      adoptionReason: "navigation-target",
+    };
+  }
+
+  async inheritWorkspaceForCreatedTab(tab) {
+    const tabId = Number(tab?.id);
+    const openerTabId = Number(tab?.openerTabId);
+    if (!Number.isInteger(tabId)) return null;
+
+    const allTabs = await this.chrome.tabs.query({});
+    const tabsById = new Map(allTabs.map((candidate) => [candidate.id, candidate]));
+    const groups = await this.chrome.tabGroups.query({});
+    const groupsById = new Map(groups.map((candidate) => [candidate.id, candidate]));
+
+    let ancestor = Number.isInteger(openerTabId) ? tabsById.get(openerTabId) : null;
+    const visited = new Set();
+    let inherited = null;
+    let extensionManagementAncestor = null;
+
+    while (ancestor && !visited.has(ancestor.id)) {
+      visited.add(ancestor.id);
+
+      if (this.isExtensionManagementUrl(this.tabUrl(ancestor))) {
+        extensionManagementAncestor = ancestor;
+      }
+
+      if (this.isOwnedTab(ancestor) && Number.isInteger(ancestor.groupId) && ancestor.groupId >= 0) {
+        const group = groupsById.get(ancestor.groupId);
+        if (group?.title) {
+          const { entry } = await this.configuredWorkspace(group.title);
+          if (entry) {
+            inherited = { ancestor, group, entry };
+            break;
+          }
+        }
+      }
+
+      const parentId = Number(ancestor.openerTabId);
+      ancestor = Number.isInteger(parentId) ? tabsById.get(parentId) : null;
+    }
+
+    let adoptionReason = "workspace-opener";
+    if (!inherited && this.isExtensionPageUrl(this.tabUrl(tab))) {
+      const windowId = Number(tab?.windowId);
+      const recentManagementAt = Number.isInteger(windowId)
+        ? this.recentExtensionManagementByWindow.get(windowId)
+        : null;
+      const hasRecentManagementContext =
+        Number.isFinite(recentManagementAt) &&
+        Date.now() - recentManagementAt <= EXTENSION_MANAGEMENT_RECENCY_MS;
+
+      if (extensionManagementAncestor || hasRecentManagementContext) {
+        const candidate = await this.uniqueConfiguredWorkspace();
+        if (candidate) {
+          inherited = {
+            ancestor: extensionManagementAncestor,
+            group: candidate.group,
+            entry: candidate.entry,
+          };
+          adoptionReason = extensionManagementAncestor
+            ? "extension-management-opener"
+            : "recent-extension-management";
+        }
+      }
+    }
+
+    if (!inherited) {
+      if (this.isOwnedTab(tab)) return {
+        tabId,
+        owned: true,
+      };
+
+      const groupId = Number(tab?.groupId);
+      const group = Number.isInteger(groupId) && groupId >= 0
+        ? groupsById.get(groupId)
+        : null;
+      if (group?.title) {
+        const { entry } = await this.configuredWorkspace(group.title);
+        const meta = this.parseManagedUrl(this.tabUrl(tab));
+        if (entry && meta?.workspace !== group.title) {
+          await this.chrome.tabs.ungroup([tabId]);
+          return {
+            workspace: group.title,
+            groupId,
+            tabId,
+            releasedUnexpected: true,
+          };
+        }
+      }
+      return null;
+    }
+
+    const { ancestor: workspaceAncestor, group, entry } = inherited;
+    this.markOwned(tabId);
+    await this.chrome.tabs.group({ groupId: group.id, tabIds: [tabId] });
+
+    const tabs = await this.groupTabs(group.id);
+    if (tabs.length > entry.poolSize) {
+      const { idle } = this.classify(group.title, tabs);
+      const removable = idle.find((candidate) => candidate.id !== tabId);
+      if (removable) await this.chrome.tabs.remove(removable.id);
+    }
+
+    await this.chrome.tabGroups.update(group.id, {
+      title: group.title,
+      collapsed: true,
+    });
+
+    const result = {
+      workspace: group.title,
+      groupId: group.id,
+      tabId,
+      inheritedFromTabId: Number.isInteger(openerTabId) ? openerTabId : null,
+      workspaceAncestorTabId: workspaceAncestor?.id ?? null,
+    };
+    if (adoptionReason !== "workspace-opener") result.adoptionReason = adoptionReason;
+    return result;
+  }
+
+  async reconcileCreatedTab(tabId) {
+    const id = Number(tabId);
+    if (!Number.isInteger(id)) return null;
+    const tab = await this.chrome.tabs.get(id);
+    return await this.inheritWorkspaceForCreatedTab(tab);
+  }
+
+  classify(name, tabs) {
+    const idle = [];
+    const leased = [];
+    for (const tab of tabs) {
+      const meta = this.parseManagedUrl(tab.url || "");
+      if (meta?.workspace === name && ["idle", "marker"].includes(meta.role)) idle.push(tab);
+      else leased.push(tab);
+    }
+    return { idle, leased };
+  }
+
+  async waitForIdleTab(tabId, workspace, timeoutMs = 3000) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const tabs = await this.chrome.tabs.query({});
+      const tab = tabs.find((candidate) => candidate.id === tabId);
+      const meta = this.parseManagedUrl(tab?.url || "");
+      if (tab && meta?.workspace === workspace && meta.role === "idle") return tab;
+      if (Date.now() >= deadline) {
+        throw new Error(`Timed out waiting for workspace ${workspace} idle tab ${tabId}`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+  }
+
+  async createGroup(name, poolSize) {
+    // Chrome groups are created by grouping a tab. Keep one seed tab so the
+    // workspace has an identity, then grow the physical pool on demand.
+    const created = [await this.chrome.tabs.create({
+      url: this.idleUrl(name, 0),
+      active: false,
+    })];
+    for (const tab of created) this.markOwned(tab.id);
+    const groupId = await this.chrome.tabs.group({ tabIds: created.map((tab) => tab.id) });
+    await this.chrome.tabGroups.update(groupId, { title: name, collapsed: true });
+    for (const tab of created) await this.waitForIdleTab(tab.id, name);
+    return await this.status(name);
+  }
+
+  async ensureWorkspace(name, poolSize = null) {
+    const normalizedName = normalizeWorkspaceName(name);
+    const { entry } = await this.configuredWorkspace(normalizedName);
+    const wanted = normalizePoolSize(poolSize, entry?.poolSize ?? 8);
+    if (!entry || entry.poolSize !== wanted) await this.setPoolSize(normalizedName, wanted);
+
+    const group = await this.workspaceGroup(normalizedName);
+    if (!group) return await this.createGroup(normalizedName, wanted);
+
+    await this.chrome.tabGroups.update(group.id, { title: normalizedName, collapsed: true });
+    await this.reconcilePool(normalizedName, group.id, wanted);
+    return await this.status(normalizedName);
+  }
+
+  async reconcilePool(name, groupId, poolSize) {
+    const tabs = await this.groupTabs(groupId);
+    const { idle } = this.classify(name, tabs);
+
+    // poolSize is a maximum concurrent capacity, not a target tab count.
+    // Only remove surplus idle tabs when shrinking; never refill a lazy pool.
+    if (tabs.length > poolSize && idle.length) {
+      const removable = Math.min(idle.length, tabs.length - poolSize);
+      await this.chrome.tabs.remove(idle.slice(0, removable).map((tab) => tab.id));
+    }
+
+    await this.chrome.tabGroups.update(groupId, { title: name, collapsed: true });
+  }
+
+  async status(name) {
+    const normalizedName = normalizeWorkspaceName(name);
+    const { entry } = await this.configuredWorkspace(normalizedName);
+    if (!entry) return { name: normalizedName, initialized: false };
+
+    const group = await this.workspaceGroup(normalizedName);
+    if (!group) {
+      return {
+        name: normalizedName,
+        initialized: false,
+        poolSize: entry.poolSize,
+        reason: "group-missing",
+      };
+    }
+
+    const tabs = await this.groupTabs(group.id);
+    const { idle, leased } = this.classify(normalizedName, tabs);
+    return {
+      name: normalizedName,
+      initialized: true,
+      groupId: group.id,
+      poolSize: entry.poolSize,
+      maxCapacity: entry.poolSize,
+      physicalTabs: tabs.length,
+      idle: idle.length,
+      leased: leased.length,
+      tabIds: tabs.map((tab) => tab.id),
+      idleTabIds: idle.map((tab) => tab.id),
+      leasedTabIds: leased.map((tab) => tab.id),
+      tabs: tabs.map((tab) => ({
+        tabId: tab.id,
+        groupId: tab.groupId,
+        title: tab.title || "",
+        url: tab.url || "",
+        active: Boolean(tab.active),
+      })),
+      collapsed: Boolean(group.collapsed),
+    };
+  }
+
+  async restoreConfiguredWorkspaces() {
+    const config = await this.loadConfig();
+    const restored = [];
+    for (const name of Object.keys(config.workspaces || {}).sort()) {
+      restored.push(await this.ensureWorkspace(name));
+    }
+    return { workspaces: restored };
+  }
+
+  async list() {
+    const config = await this.loadConfig();
+    const result = [];
+    for (const name of Object.keys(config.workspaces).sort()) {
+      result.push(await this.status(name));
+    }
+    return { workspaces: result };
+  }
+
+  async ensure(name, defaultPoolSize = 8) {
+    const normalizedName = normalizeWorkspaceName(name);
+    const { entry } = await this.configuredWorkspace(normalizedName);
+    if (entry) return await this.ensureWorkspace(normalizedName);
+    return await this.ensureWorkspace(
+      normalizedName,
+      normalizePoolSize(defaultPoolSize),
+    );
+  }
+
+  async create(name, poolSize = 8) {
+    return await this.ensureWorkspace(name, normalizePoolSize(poolSize));
+  }
+
+  async resize(name, poolSize) {
+    const normalizedName = normalizeWorkspaceName(name);
+    const wanted = normalizePoolSize(poolSize);
+    await this.setPoolSize(normalizedName, wanted);
+    return await this.ensureWorkspace(normalizedName, wanted);
+  }
+
+  async acquireIdentity(name) {
+    const normalizedName = normalizeWorkspaceName(name);
+    const ready = await this.ensureWorkspace(normalizedName);
+    const tabs = await this.groupTabs(ready.groupId);
+    const { idle, leased } = this.classify(normalizedName, tabs);
+    if (!idle.length && leased.length >= ready.poolSize) {
+      throw new Error(`Workspace ${normalizedName} pool is exhausted at size ${ready.poolSize}`);
+    }
+
+    let tab = idle[0];
+    if (!tab) {
+      tab = await this.chrome.tabs.create({
+        url: this.idleUrl(normalizedName, tabs.length),
+        active: false,
+      });
+      this.markOwned(tab.id);
+      await this.chrome.tabs.group({ groupId: ready.groupId, tabIds: [tab.id] });
+      tab = await this.waitForIdleTab(tab.id, normalizedName);
+    }
+
+    this.markOwned(tab.id);
+    const identityTitle = this.identityTitle(tab.id);
+    const identityUrl = this.identityUrl(normalizedName, tab.id);
+    const updated = await this.chrome.tabs.update(tab.id, { url: identityUrl, active: false });
+    await this.chrome.tabGroups.update(ready.groupId, { title: normalizedName, collapsed: true });
+    return {
+      workspace: normalizedName,
+      groupId: ready.groupId,
+      tabId: updated.id,
+      identityTitle,
+      identityUrl,
+      idleUrl: this.idleUrl(normalizedName, updated.id),
+      active: Boolean(updated.active),
+    };
+  }
+
+  async acquire(name, url) {
+    const normalizedName = normalizeWorkspaceName(name);
+    const parsed = new URL(String(url || ""));
+    if (!["http:", "https:", "chrome-extension:"].includes(parsed.protocol)) {
+      throw new Error("Workspace acquire requires an http(s) or chrome-extension URL");
+    }
+
+    const ready = await this.ensureWorkspace(normalizedName);
+    const tabs = await this.groupTabs(ready.groupId);
+    const { idle, leased } = this.classify(normalizedName, tabs);
+    if (!idle.length && leased.length >= ready.poolSize) {
+      throw new Error(`Workspace ${normalizedName} pool is exhausted at size ${ready.poolSize}`);
+    }
+
+    let tab = idle[0];
+    if (!tab) {
+      tab = await this.chrome.tabs.create({
+        url: this.idleUrl(normalizedName, tabs.length),
+        active: false,
+      });
+      // Group reconciliation can fire before the extension idle URL is visible.
+      // Mark ownership first so a legitimate Browser Harness lease is not ejected.
+      this.markOwned(tab.id);
+      await this.chrome.tabs.group({ groupId: ready.groupId, tabIds: [tab.id] });
+      tab = await this.waitForIdleTab(tab.id, normalizedName);
+    }
+    this.markOwned(tab.id);
+    const updated = await this.chrome.tabs.update(tab.id, { url: parsed.href, active: false });
+    await this.chrome.tabGroups.update(ready.groupId, { title: normalizedName, collapsed: true });
+    return {
+      workspace: normalizedName,
+      groupId: ready.groupId,
+      tabId: updated.id,
+      url: updated.url || parsed.href,
+      active: Boolean(updated.active),
+    };
+  }
+
+  async release(name, tabId) {
+    const normalizedName = normalizeWorkspaceName(name);
+    const ready = await this.ensureWorkspace(normalizedName);
+    const wanted = Number(tabId);
+    const tabs = await this.groupTabs(ready.groupId);
+    if (!tabs.some((tab) => tab.id === wanted)) {
+      throw new Error(`Tab ${wanted} is not owned by workspace ${normalizedName}`);
+    }
+
+    if (tabs.length > ready.poolSize) {
+      await this.chrome.tabs.remove(wanted);
+    } else {
+      try {
+        await this.chrome.tabs.update(wanted, {
+          url: this.idleUrl(normalizedName, wanted),
+          active: false,
+        });
+        await this.waitForIdleTab(wanted, normalizedName);
+      } catch {
+        // Legacy/unowned leases may refuse or fail to finish navigation back to
+        // the extension idle page. Preserve pool capacity by creating a clean
+        // idle replacement in the same group before removing the stale tab.
+        const replacement = await this.chrome.tabs.create({
+          url: this.idleUrl(normalizedName, wanted),
+          active: false,
+        });
+        this.markOwned(replacement.id);
+        await this.chrome.tabs.group({ groupId: ready.groupId, tabIds: [replacement.id] });
+        await this.waitForIdleTab(replacement.id, normalizedName);
+        await this.chrome.tabs.remove(wanted);
+      }
+    }
+    await this.chrome.tabGroups.update(ready.groupId, { title: normalizedName, collapsed: true });
+    return { workspace: normalizedName, tabId: wanted, released: true };
+  }
+
+  async releaseAll() {
+    const config = await this.loadConfig();
+    const released = [];
+
+    for (const name of Object.keys(config.workspaces || {}).sort()) {
+      const group = await this.workspaceGroup(name);
+      if (!group) continue;
+
+      // Snapshot first because release() mutates the group as tabs return idle
+      // or are removed when the group is above its configured capacity.
+      const tabs = await this.groupTabs(group.id);
+      const { leased } = this.classify(name, tabs);
+      for (const tab of leased) {
+        await this.release(name, tab.id);
+        released.push({ workspace: name, tabId: tab.id });
+      }
+
+      // Chrome destroys a tab group when it becomes empty. Release-all must
+      // preserve workspace identity, so re-ensure the workspace after the
+      // release pass and leave at least one idle seed tab if necessary.
+      await this.ensureWorkspace(name);
+    }
+
+    return {
+      released,
+      releasedCount: released.length,
+    };
+  }
+
+  async delete(name, force = false) {
+    const normalizedName = normalizeWorkspaceName(name);
+    const state = await this.status(normalizedName);
+    if (!state.initialized) {
+      await this.removeConfig(normalizedName);
+      return { name: normalizedName, deleted: true };
+    }
+    if (state.leasedTabIds.length && !force) {
+      throw new Error(`Workspace ${normalizedName} has ${state.leasedTabIds.length} leased tabs`);
+    }
+
+    const tabs = await this.groupTabs(state.groupId);
+    if (tabs.length) await this.chrome.tabs.remove(tabs.map((tab) => tab.id));
+    await this.removeConfig(normalizedName);
+    return { name: normalizedName, deleted: true };
+  }
+
+  async rpc(request) {
+    const method = String(request?.method || "");
+    const args = request?.args || {};
+    if (method === "workspace.create") return await this.create(args.name, args.poolSize);
+    if (method === "workspace.ensure") return await this.ensure(args.name, args.poolSize);
+    if (method === "workspace.status") return await this.status(args.name);
+    if (method === "workspace.list") return await this.list();
+    if (method === "workspace.acquire") return await this.acquire(args.name, args.url);
+    if (method === "workspace.acquireIdentity") return await this.acquireIdentity(args.name);
+    if (method === "workspace.release") return await this.release(args.name, args.tabId);
+    if (method === "workspace.releaseAll") return await this.releaseAll();
+    if (method === "workspace.resize") return await this.resize(args.name, args.poolSize);
+    if (method === "workspace.delete") return await this.delete(args.name, Boolean(args.force));
+    throw new Error(`Unknown workspace method: ${method}`);
+  }
+}

package/runtime/extension/workspace-page.mjs

@@ -0,0 +1,7 @@
+const params = new URLSearchParams(location.search);
+const role = params.get("role") || "";
+const slot = params.get("slot") || "";
+
+document.title = role === "lease" && /^\d+$/.test(slot)
+  ? `__BW_TAB_${slot}__`
+  : "Browser Workspace";

package/runtime/extension/workspace.html

@@ -0,0 +1,8 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>Browser Workspace</title>
+<script type="module" src="workspace-page.mjs"></script>
+<style>
+  body { font-family: system-ui, sans-serif; margin: 24px; }
+</style>
+<p>This tab belongs to a managed Browser Workspace pool.</p>

package/runtime/extension-manager.mjs

@@ -0,0 +1,105 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {fileURLToPath} from 'node:url';
+
+export const EXTENSION_ID='kkkpgmhpoeceojalkpfdidffdfnlgdog';
+export const EXTENSION_HOME=path.resolve(process.env.WEBHELM_EXTENSION_HOME || path.join(os.homedir(),'.local/webhelm/extension'));
+const SOURCE=fileURLToPath(new URL('./extension/',import.meta.url));
+const FILES=['manifest.json','service-worker.mjs','workspace-manager.mjs','workspace.html','workspace-page.mjs'];
+
+function manifest(dir){
+  const data=JSON.parse(fs.readFileSync(path.join(dir,'manifest.json'),'utf8'));
+  const digest=crypto.createHash('sha256').update(Buffer.from(data.key,'base64')).digest('hex').slice(0,32);
+  const id=[...digest].map(c=>String.fromCharCode(97+parseInt(c,16))).join('');
+  if(id!==EXTENSION_ID || data.manifest_version!==3 || !/^\d+\.\d+\.\d+$/.test(data.version))
+    throw Error('Unexpected WebHelm extension identity, manifest version, or version number');
+  return data;
+}
+export const extensionVersion=manifest(SOURCE).version;
+function identical(dir){
+  return fs.existsSync(path.join(dir,'manifest.json'))&&
+    JSON.stringify(fs.readdirSync(dir).sort())===JSON.stringify([...FILES].sort())&&
+    FILES.every(name=>fs.readFileSync(path.join(dir,name)).equals(fs.readFileSync(path.join(SOURCE,name))));
+}
+// Actions checkout contains this self-managed directory, but Git must never publish it.
+function excludeFromActionsGit(dir){
+  const root=path.dirname(dir), info=path.join(root,'.git/info/exclude');
+  if(!fs.existsSync(info))return;
+  const contents=fs.readFileSync(info,'utf8');
+  const additions=['/chrome/','/extension/','/.webhelm-extension-stage-*/','/.webhelm-extension-backup-*/'].filter(rule=>!contents.split(/\r?\n/).includes(rule));
+  if(additions.length)fs.appendFileSync(info,'\n'+additions.join('\n')+'\n');
+}
+export function stageExtension(dir=EXTENSION_HOME){
+  const target=path.resolve(dir);
+  const bundled=manifest(SOURCE);
+  if(fs.existsSync(target)&&fs.lstatSync(target).isSymbolicLink())throw Error('Refusing to replace extension symlink');
+  if(fs.existsSync(target)&&identical(target))return {path:target,version:bundled.version,updated:false};
+  if(fs.existsSync(target))manifest(target); // Never replace unrelated content.
+  const root=path.dirname(target);
+  fs.mkdirSync(root,{recursive:true,mode:0o700});
+  excludeFromActionsGit(target);
+  const stage=fs.mkdtempSync(path.join(root,'.webhelm-extension-stage-'));
+  let backup;
+  try {
+    for(const filename of FILES)fs.copyFileSync(path.join(SOURCE,filename),path.join(stage,filename));
+    if(!identical(stage))throw Error('WebHelm extension staged content mismatch');
+    if(fs.existsSync(target)){
+      backup=path.join(root,`.webhelm-extension-backup-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+      fs.renameSync(target,backup);
+    }
+    try {fs.renameSync(stage,target);}catch(error){if(backup)fs.renameSync(backup,target);throw error;}
+    if(backup)fs.rmSync(backup,{recursive:true,force:true});
+    return {path:target,version:bundled.version,updated:true};
+  }finally{if(fs.existsSync(stage))fs.rmSync(stage,{recursive:true,force:true});}
+}
+
+// Modern Chrome exposes this browser-level protocol. Older Chrome (including
+// Big Sur's Chrome 138) requires the managed startup flags instead.
+export async function ensureExtensionLoaded(browser, {skip=false,extensionDir=EXTENSION_HOME,allowUpdate=true}={}){
+  if(skip)return {skipped:true};
+  if(!allowUpdate && (!fs.existsSync(path.join(extensionDir,'manifest.json')) || !identical(extensionDir)))
+    throw Error('Extension update deferred: active browser Sessions must finish before staging new content');
+  const {path:dir,version}=allowUpdate?stageExtension(extensionDir):{path:extensionDir,version:extensionVersion};
+  let modern=false, installed;
+  try{
+    const state=await browser.send('Extensions.getExtensions');
+    modern=true;installed=state.extensions?.find(e=>e.id===EXTENSION_ID);
+    if(!installed || !installed.enabled || installed.version!==version || path.resolve(installed.path||'')!==dir){
+      if(!allowUpdate)throw Error('Extension reload deferred: active browser Sessions must finish');
+      const loaded=await browser.send('Extensions.loadUnpacked',{path:dir});
+      if(loaded.id!==EXTENSION_ID)throw Error('Chrome loaded an unexpected extension ID');
+    }
+  }catch(error){
+    if(modern || !/Method not available|wasn't found|Method not found|not supported/i.test(String(error.message)))
+      throw Error(`WebHelm extension install failed: ${error.message}`);
+  }
+  // Inspect the real extension context. An installed-but-asleep MV3 worker may
+  // need a temporary extension page, which is never a user's allocated tab.
+  const {targetInfos=[]}=await browser.send('Target.getTargets');
+  const prefix=`chrome-extension://${EXTENSION_ID}/`;
+  let target=targetInfos.find(t=>t.type==='service_worker'&&t.url.startsWith(prefix));
+  let temporary=false;
+  if(!target){
+    const created=await browser.send('Target.createTarget',{url:`${prefix}workspace.html?webhelm_wakeup=1`,background:true});
+    target={targetId:created.targetId};temporary=true;
+  }
+  let attached;
+  try{
+    ({sessionId:attached}=await browser.send('Target.attachToTarget',{targetId:target.targetId,flatten:true}));
+    for(let i=0;i<30;i++){
+      try{
+        const reply=await browser.send('Runtime.evaluate',{expression:'chrome.runtime?.getManifest?.().version',returnByValue:true},attached);
+        if(reply.result?.value===version)return {path:dir,version,method:modern?'cdp':'startup-flags'};
+        if(reply.result?.value && reply.result.value!==version)
+          throw Error(`Chrome has extension ${reply.result.value}; expected ${version}`);
+      }catch(error){if(/Chrome has extension/.test(error.message))throw error;}
+      await new Promise(r=>setTimeout(r,100));
+    }
+    throw Error(`Chrome did not initialize managed Extension ${version}. Restart managed Chrome when idle with local extension launch flags.`);
+  }finally{
+    if(attached)await browser.send('Target.detachFromTarget',{sessionId:attached}).catch(()=>{});
+    if(temporary)await browser.send('Target.closeTarget',{targetId:target.targetId}).catch(()=>{});
+  }
+}

package/runtime/migrate.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import net from 'node:net';
-import { CONFIG_ROOT, LEGACY_ROOT } from './config-paths.mjs';
+import { CONFIG_ROOT, LEGACY_ROOT, OLD_PROFILE_DIR, PROFILE_DIR } from './config-paths.mjs';
 
 function liveSocket(socketPath) {
   return new Promise(resolve => {
@@ -45,3 +45,36 @@ export async function migrateConfig({ legacyRoot = LEGACY_ROOT, configRoot = CON
   }
   return { status: 'migrated', config_root: target, compatibility_symlink: legacy };
 }
+
+// Move only the Chrome Profile. Durable FIFO and logs stay under ~/.config/webhelm/runtime.
+// Chrome must be stopped because its SingletonLock and keychain-bound profile
+// resources cannot be safely relocated while the browser is still running.
+export async function migrateChromeProfile({oldProfile=OLD_PROFILE_DIR,newProfile=PROFILE_DIR,
+  processList=()=>execFileSync('ps',['-axo','command='],{encoding:'utf8'}),
+  socketCheck=liveSocket}={}){
+  const old=path.resolve(oldProfile),target=path.resolve(newProfile);
+  if(old===target)throw Error('Chrome source and destination paths must differ');
+  if(fs.existsSync(target)){
+    if(!fs.existsSync(old))return {status:'already_migrated',profile_dir:target};
+    if(fs.realpathSync(old)===fs.realpathSync(target))return {status:'already_migrated',profile_dir:target,compatibility_symlink:old};
+    throw Error(`Different Chrome Profiles at ${old} and ${target}; refusing to overwrite`);
+  }
+  if(!fs.existsSync(old))return {status:'not_needed',profile_dir:target};
+  if(fs.lstatSync(old).isSymbolicLink() || !fs.statSync(old).isDirectory())
+    throw Error('Old Chrome Profile is not a regular directory');
+  const running=processList().split('\n').filter(s=>s.includes(`--user-data-dir=${old}`)||s.includes(`--user-data-dir=${target}`)||s.includes('node-daemon.mjs daemon') && !s.includes('migrate.mjs'));
+  if(running.length)throw Error('Managed Chrome or daemon is running; stop and drain before migrating Profile');
+  const socket=path.join(path.dirname(old),'runtime/session-node.sock');
+  if(fs.existsSync(socket)&&await socketCheck(socket))throw Error('Session daemon still accepting requests');
+  if(!fs.existsSync(path.join(old,'Default')))throw Error('Old Chrome Profile lacks Default; refusing to migrate');
+  const parent=path.dirname(target);
+  if(fs.existsSync(path.join(parent,'.git'))){
+    const info=path.join(parent,'.git/info/exclude');
+    const current=fs.existsSync(info)?fs.readFileSync(info,'utf8'):'';
+    if(!current.split(/\r?\n/).includes('/chrome/'))fs.appendFileSync(info,'\n/chrome/\n');
+  }
+  fs.mkdirSync(parent,{recursive:true});
+  fs.renameSync(old,target);
+  try{fs.symlinkSync(target,old,'dir');}catch(error){fs.renameSync(target,old);throw error;}
+  return {status:'migrated',profile_dir:target,compatibility_symlink:old};
+}

package/runtime/node-daemon.mjs

@@ -10,9 +10,11 @@ import { invokePlatformAction } from './platforms.mjs';
 import { ChatGPTQueue } from './chatgpt/chatgpt-queue.mjs';
 import { idleUrlFromIdentity, sameIdleUrl, staleSession } from './session-lifecycle.mjs';
 import { ensureManagedChrome } from './chrome.mjs';
+import { ensureExtensionLoaded } from './extension-manager.mjs';
 import { PROFILE_DIR, RUNTIME_DIR, requireMigratedConfig } from './config-paths.mjs';
 
-const ROOT = path.dirname(new URL(import.meta.url).pathname);
+const ROOT = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_VERSION=JSON.parse(fs.readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
 const HOME = os.homedir();
 export { PROFILE_DIR };
 const DEFAULT_RUNTIME = RUNTIME_DIR;
@@ -98,6 +100,8 @@ async function connectBrowser() {
       }
     });
     await browser.send('Target.setDiscoverTargets',{discover:true});
+    try{await ensureExtensionLoaded(browser,{skip:process.env.WEBHELM_NO_PROFILE_EXTENSION_PROBE==='1',allowUpdate:sessions.size===0});}
+    catch(error){browserWs=null;browser.ws?.close();throw error;}
     connected=true;
     if(!reconnecting){
       reconnecting=true;
@@ -304,6 +308,7 @@ async function createSession(req={}) {
       s.idleUrls.set(targetId,lease.idleUrl);
       s.workspaceSupported=true;
     } else {
+      if(process.env.WEBHELM_NO_PROFILE_EXTENSION_PROBE!=='1')throw Error('Managed WebHelm Extension unavailable; refusing unmanaged Tab allocation');
       ({targetId}=await browser.send('Target.createTarget',{url:'about:blank'}));
     }
     s.targetId=targetId;
@@ -533,7 +538,7 @@ async function runPlatform(req) {
     self_heal_capable:!auto,result};
 }
 
-export async function handle(req){switch(req.op){case'ping':return {ok:true,pid:process.pid,version:'1.0.1',queue_paused:process.env.WEBHELM_CHATGPT_QUEUE_PAUSED==='1',session_count:sessions.size,managed_chrome:managedChrome||{profile_dir:PROFILE_DIR, endpoint:process.env.WEBHELM_CDP_URL||'http://127.0.0.1:9222',reused:true}};case'heartbeat':return heartbeatSession(req.session_id);case'list':return {session_count:sessions.size,sessions:[...sessions.values()].map(s=>({session_id:s.session_id,workspace:s.workspace,target_id:s.targetId,last_used_at:s.last_used_at}))};case'start':return createSession(req);case'exec':return execute(req);case'stop':return stopSession(req.session_id);case'stop-all':{const stopped=[];for(const id of [...sessions.keys()])stopped.push(await stopSession(id));return {stopped_count:stopped.length,error_count:0,stopped,errors:[]}}case'capacity':return workspaceCapacity(req);case'workspace-create':case'workspace-delete':return workspaceOp(req);case'chatgpt-new-turn-enqueue':return getChatGPTQueue().enqueue(req.config);case'platform-run':return runPlatform(req);default:throw Error(`unknown op: ${req.op}`)}}
+export async function handle(req){switch(req.op){case'ping':return {ok:true,pid:process.pid,version:PACKAGE_VERSION,queue_paused:process.env.WEBHELM_CHATGPT_QUEUE_PAUSED==='1',session_count:sessions.size,managed_chrome:managedChrome||{profile_dir:PROFILE_DIR, endpoint:process.env.WEBHELM_CDP_URL||'http://127.0.0.1:9222',reused:true}};case'heartbeat':return heartbeatSession(req.session_id);case'list':return {session_count:sessions.size,sessions:[...sessions.values()].map(s=>({session_id:s.session_id,workspace:s.workspace,target_id:s.targetId,last_used_at:s.last_used_at}))};case'start':return createSession(req);case'exec':return execute(req);case'stop':return stopSession(req.session_id);case'stop-all':{const stopped=[];for(const id of [...sessions.keys()])stopped.push(await stopSession(id));return {stopped_count:stopped.length,error_count:0,stopped,errors:[]}}case'capacity':return workspaceCapacity(req);case'workspace-create':case'workspace-delete':return workspaceOp(req);case'chatgpt-new-turn-enqueue':return getChatGPTQueue().enqueue(req.config);case'platform-run':return runPlatform(req);default:throw Error(`unknown op: ${req.op}`)}}
 function serve(conn) {
   let buffer = '';
   conn.setEncoding('utf8');
@@ -553,6 +558,6 @@ function serve(conn) {
 
 async function main(){fs.mkdirSync(RUNTIME,{recursive:true,mode:0o700});let lockfd;try{lockfd=fs.openSync(LOCK,'wx',0o600);fs.writeFileSync(lockfd,String(process.pid))}catch{throw Error(`Node pilot lock exists: ${LOCK}`)}if(fs.existsSync(SOCKET)){try{const c=net.createConnection(SOCKET);await new Promise((res,rej)=>{c.once('connect',res);c.once('error',rej)});c.destroy();fs.closeSync(lockfd);fs.unlinkSync(LOCK);throw Error(`Node daemon socket already active: ${SOCKET}`)}catch(e){if(e.message.includes('already active'))throw e;fs.unlinkSync(SOCKET)}}socket=net.createServer(serve);await new Promise((res,rej)=>socket.listen(SOCKET,res).once('error',rej));fs.chmodSync(SOCKET,0o600);connectBrowser().catch(()=>{});getChatGPTQueue();const cleanup=async()=>{if(shuttingDown)return;shuttingDown=true;if(chatgptQueue)await chatgptQueue.shutdown().catch(()=>{});await handle({op:'stop-all'}).catch(()=>{});socket?.close();try{if(fs.existsSync(SOCKET))fs.unlinkSync(SOCKET)}catch{}try{fs.closeSync(lockfd);fs.unlinkSync(LOCK)}catch{}process.exit(0)};process.on('SIGTERM',cleanup);process.on('SIGINT',cleanup)}
 async function request(payload,ensure=true){if(ensure)await ensureDaemon();return new Promise((resolve,reject)=>{const c=net.createConnection(SOCKET);let data='';c.setEncoding('utf8');c.on('connect',()=>c.write(JSON.stringify(payload)+'\n'));c.on('data',x=>{data+=x;if(!data.includes('\n'))return;c.end();try{const r=JSON.parse(data);r.error?reject(Error(r.error)):resolve(r)}catch(e){reject(e)}});c.on('error',reject)})}
-export async function ensureDaemon(){requireMigratedConfig();try{const p=await request({op:'ping'},false);if(p.ok)return p}catch{}fs.mkdirSync(RUNTIME,{recursive:true,mode:0o700});if(fs.existsSync(LOCK)){let owner=0;try{owner=Number(fs.readFileSync(LOCK,'utf8').trim())}catch{};let alive=false;if(owner>0)try{process.kill(owner,0);alive=true}catch{};if(alive)throw Error(`daemon owner lock exists but socket is unreachable; refusing duplicate startup (${LOCK})`);fs.unlinkSync(LOCK)}const child=await import('node:child_process');const log=fs.openSync(path.join(RUNTIME,'session-node.log'),'a');child.spawn(process.execPath,[fileURLToPath(import.meta.url),'daemon'],{detached:true,stdio:['ignore',log,log],env:process.env}).unref();for(let i=0;i<100;i++){await delay(100);try{const p=await request({op:'ping'},false);if(p.ok)return p}catch{}}throw Error(`WebHelm Node daemon did not start; see ${path.join(RUNTIME,'session-node.log')}`)}
+export async function ensureDaemon(){try{const p=await request({op:'ping'},false);if(p.ok)return p}catch{}if(!process.env.WEBHELM_CDP_URL)requireMigratedConfig();fs.mkdirSync(RUNTIME,{recursive:true,mode:0o700});if(fs.existsSync(LOCK)){let owner=0;try{owner=Number(fs.readFileSync(LOCK,'utf8').trim())}catch{};let alive=false;if(owner>0)try{process.kill(owner,0);alive=true}catch{};if(alive)throw Error(`daemon owner lock exists but socket is unreachable; refusing duplicate startup (${LOCK})`);fs.unlinkSync(LOCK)}const child=await import('node:child_process');const log=fs.openSync(path.join(RUNTIME,'session-node.log'),'a');child.spawn(process.execPath,[fileURLToPath(import.meta.url),'daemon'],{detached:true,stdio:['ignore',log,log],env:process.env}).unref();for(let i=0;i<100;i++){await delay(100);try{const p=await request({op:'ping'},false);if(p.ok)return p}catch{}}throw Error(`WebHelm Node daemon did not start; see ${path.join(RUNTIME,'session-node.log')}`)}
 if(process.argv[2]==='daemon')main().catch(e=>{console.error(e);process.exit(1)});
 export {request,SOCKET,RUNTIME};