webhelm 1.0.5 → 1.0.7

package/runtime/extension/service-worker.mjs

@@ -1,54 +1,97 @@
 import { WorkspaceManager } from "./workspace-manager.mjs";
+import { ControlChannel } from "./control-channel.mjs";
+import { summarizeWorkspaces } from "./workspace-summary.mjs";
 
 const manager = new WorkspaceManager(chrome);
+const control = new ControlChannel(chrome);
 const closingWindowIds = new Set();
+let badgeTimer = null;
+
+async function refreshBadge() {
+  const state = await control.status();
+  const summary = summarizeWorkspaces((await manager.list()).workspaces, state.sessions);
+  const available = summary.totalAvailable;
+  await chrome.action.setBadgeText({
+    text: !state.connected ? "!" : available === null ? "?" : available > 99 ? "99+" : String(available),
+  });
+  await chrome.action.setBadgeBackgroundColor({
+    color: !state.connected || available === null ? "#667085"
+      : available === 0 ? "#A43145" : "#345FD5",
+  });
+  await chrome.action.setTitle({title: state.connected
+    ? `WebHelm — ${available === null ? "unknown" : available} available slot(s) across ${summary.workspaces.length} workspace(s)`
+    : "WebHelm — daemon offline or status stale"});
+}
 
+function scheduleBadge() {
+  if (badgeTimer !== null) clearTimeout(badgeTimer);
+  badgeTimer = setTimeout(() => {
+    badgeTimer = null;
+    refreshBadge().catch(error => console.warn("WebHelm badge update failed", error));
+  }, 100);
+}
 
-manager.restoreConfiguredWorkspaces().catch((error) => {
-  console.warn("Browser Workspace failed to restore configured workspaces", error);
+const BADGE_ALARM = "webhelm.badge-refresh";
+async function scheduleBadgeAlarm() {
+  await chrome.alarms.create(BADGE_ALARM, {periodInMinutes: 0.5});
+}
+chrome.alarms.onAlarm.addListener(alarm => {
+  if (alarm.name === BADGE_ALARM) scheduleBadge();
 });
+scheduleBadgeAlarm().catch(error => console.warn("WebHelm badge alarm failed", 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"],
-  });
+async function removeLegacyContextMenu() {
+  // Legacy release-all operated on extension tabs but did not stop Node Sessions.
+  try { await chrome.contextMenus.remove("browser-workspace.release-all"); }
+  catch { /* already absent */ }
 }
 
+manager.restoreConfiguredWorkspaces()
+  .then(scheduleBadge)
+  .catch(error => console.warn("WebHelm failed to restore configured workspaces", error));
+removeLegacyContextMenu().catch(() => {});
 chrome.runtime.onInstalled.addListener(() => {
-  ensureContextMenus().catch((error) => {
-    console.warn("Browser Workspace failed to create extension menu", error);
-  });
+  removeLegacyContextMenu().catch(() => {});
+  scheduleBadge();
 });
-
 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);
+  removeLegacyContextMenu().catch(() => {});
+  scheduleBadge();
 });
 
-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);
-  });
-});
+async function controlRpc(method, args) {
+  switch (method) {
+    case "workspace.control.status": {
+      const state = await control.status();
+      const summary = summarizeWorkspaces((await manager.list()).workspaces, state.sessions);
+      return {...state,...summary};
+    }
+    case "workspace.control.requestStop":
+      return control.requestStop(args.action, args.sessionId, args.workspace);
+    case "workspace.control.heartbeat":
+      return control.heartbeat(args.sessions);
+    case "workspace.control.poll": {
+      const result = await control.poll(args.sessions);
+      scheduleBadge();
+      return result;
+    }
+    case "workspace.control.complete":
+      return control.complete(args.id, args.response);
+    default:
+      throw new Error("Unknown workspace control method");
+  }
+}
 
 globalThis.browserWorkspaceManagerRpc = async (request) => {
   try {
-    return { ok: true, result: await manager.rpc(request) };
+    const method = String(request?.method || "");
+    const result = method.startsWith("workspace.control.")
+      ? await controlRpc(method, request.args || {})
+      : await manager.rpc(request);
+    if (["workspace.acquireIdentity", "workspace.acquire", "workspace.release",
+         "workspace.releaseAll", "workspace.resize", "workspace.ensure",
+         "workspace.delete", "workspace.create"].includes(method)) scheduleBadge();
+    return {ok: true, result};
   } catch (error) {
     return {
       ok: false,
@@ -60,45 +103,53 @@ globalThis.browserWorkspaceManagerRpc = async (request) => {
   }
 };
 
-chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {
+chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
+  if (request?.method?.startsWith("workspace.control.") &&
+      (sender?.url !== chrome.runtime.getURL("popup.html") ||
+        !["workspace.control.requestStop", "workspace.control.status"].includes(request.method))) {
+    sendResponse({ok:false,error:{message:"WebHelm control actions require the toolbar popup"}});
+    return false;
+  }
   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);
+  manager.inheritWorkspaceForCreatedTab(tab).then(scheduleBadge).catch((error) => {
+    console.warn("WebHelm failed to inherit child tab group", error);
   });
 
   setTimeout(() => {
-    manager.reconcileCreatedTab(tab.id).catch((error) => {
+    manager.reconcileCreatedTab(tab.id).then(scheduleBadge).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);
+        console.warn("WebHelm 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);
+  manager.inheritNavigationTarget(details).then(scheduleBadge).catch((error) => {
+    console.warn("WebHelm failed to inherit navigation target", error);
   });
 });
 
 chrome.tabs.onUpdated.addListener((_tabId, changeInfo, tab) => {
+  if (changeInfo.url || Object.prototype.hasOwnProperty.call(changeInfo, "groupId")) scheduleBadge();
   if (!Object.prototype.hasOwnProperty.call(changeInfo, "groupId")) return;
-  manager.inheritWorkspaceForCreatedTab(tab).catch((error) => {
-    console.warn("Browser Workspace failed to reconcile tab group ownership", error);
+  manager.inheritWorkspaceForCreatedTab(tab).then(scheduleBadge).catch((error) => {
+    console.warn("WebHelm 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);
+    console.warn("WebHelm failed to record active tab context", error);
   });
 });
 
 chrome.tabs.onRemoved.addListener((_tabId, removeInfo) => {
+  scheduleBadge();
   if (!removeInfo?.isWindowClosing) return;
   closingWindowIds.add(removeInfo.windowId);
   setTimeout(() => closingWindowIds.delete(removeInfo.windowId), 1000);
@@ -110,8 +161,8 @@ chrome.tabGroups.onRemoved.addListener((group) => {
   // 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);
+    manager.removeDeletedGroup(group).then(scheduleBadge).catch((error) => {
+      console.warn("WebHelm failed to remove deleted workspace", error);
     });
   }, 100);
 });

package/runtime/extension/workspace-manager.mjs

@@ -42,11 +42,11 @@ export class WorkspaceManager {
   }
 
   idleUrl(workspace, slot) {
-    return this.chrome.runtime.getURL(`workspace.html?${queryString(workspace, slot)}`);
+    return this.chrome.runtime.getURL(`helm.html?${queryString(workspace, slot)}`);
   }
 
   identityTitle(tabId) {
-    return `__BW_TAB_${tabId}__`;
+    return `__WEBHELM_TAB_${tabId}__`;
   }
 
   identityUrl(workspace, tabId) {
@@ -55,14 +55,15 @@ export class WorkspaceManager {
       role: "lease",
       slot: String(tabId),
     }).toString();
-    return this.chrome.runtime.getURL(`workspace.html?${query}`);
+    return this.chrome.runtime.getURL(`helm.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;
+      const own = new URL(this.chrome.runtime.getURL("helm.html"));
+      if (parsed.origin !== own.origin ||
+          !["/helm.html", "/workspace.html"].includes(parsed.pathname)) return null;
       return {
         workspace: parsed.searchParams.get("workspace") || "",
         role: parsed.searchParams.get("role") || "",
@@ -466,6 +467,44 @@ export class WorkspaceManager {
     return { workspaces: result };
   }
 
+  // The legacy default group is only renamed after all its tabs return idle.
+  // Preserve configured custom workspaces, old leased tabs and Chrome tab IDs.
+  async migrateDefaultWorkspace(activeLegacySessions = 0) {
+    const oldName = "Harness", newName = "WebHelm";
+    const config = await this.loadConfig();
+    if (!config.workspaces[oldName]) return {name: newName, migrated: false};
+    if (config.workspaces[newName]) return {name: newName, migrated: false, legacyPreserved: true};
+    if (activeLegacySessions > 0) return {name: oldName, deferred: "active-sessions"};
+    const group = await this.workspaceGroup(oldName);
+    const tabs = group ? await this.groupTabs(group.id) : [];
+    if (group && this.classify(oldName, tabs).leased.length)
+      return {name: oldName, deferred: "leased-tabs"};
+
+    // URL ownership and group identity change together. If navigation fails,
+    // restore both before retrying so no lease is silently adopted.
+    const updated = [];
+    try {
+      // Mark existing legacy tabs as owned before their URLs change. Chrome
+      // can emit grouping callbacks mid-migration.
+      for (const tab of tabs) this.markOwned(tab.id);
+      if (group) await this.chrome.tabGroups.update(group.id, {title: newName});
+      for (const tab of tabs) {
+        await this.chrome.tabs.update(tab.id, {url: this.idleUrl(newName, tab.id), active: false});
+        updated.push(tab);
+      }
+      config.workspaces[newName] = config.workspaces[oldName];
+      delete config.workspaces[oldName];
+      await this.saveConfig(config);
+      return {name: newName, migrated: true, migratedTabs: updated.length};
+    } catch(error) {
+      if (group) await this.chrome.tabGroups.update(group.id, {title: oldName}).catch(() => {});
+      for (const tab of updated) {
+        await this.chrome.tabs.update(tab.id,{url: tab.url,active:false}).catch(() => {});
+      }
+      throw error;
+    }
+  }
+
   async ensure(name, defaultPoolSize = 8) {
     const normalizedName = normalizeWorkspaceName(name);
     const { entry } = await this.configuredWorkspace(normalizedName);
@@ -544,7 +583,7 @@ export class WorkspaceManager {
         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.
+      // Mark ownership first so a legitimate WebHelm 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);
@@ -650,6 +689,7 @@ export class WorkspaceManager {
     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.migrateDefault") return await this.migrateDefaultWorkspace(Number(args.activeLegacySessions || 0));
     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);

package/runtime/extension/workspace-page.mjs

@@ -1,7 +1,29 @@
 const params = new URLSearchParams(location.search);
+const workspace = params.get("workspace") || "";
 const role = params.get("role") || "";
 const slot = params.get("slot") || "";
+const validSlot = /^\d+$/.test(slot);
 
-document.title = role === "lease" && /^\d+$/.test(slot)
-  ? `__BW_TAB_${slot}__`
-  : "Browser Workspace";
+// Keep this exact lease title: WebHelm's tab identity protocol depends on it.
+document.title = role === "lease" && validSlot
+  ? `${location.pathname.endsWith("/workspace.html") ? "__BW_TAB_" : "__WEBHELM_TAB_"}${slot}__`
+  : role === "idle" && workspace
+    ? "WebHelm · Idle"
+    : "WebHelm";
+
+const setText = (id, value) => {
+  const element = document.getElementById(id);
+  if (element) element.textContent = value;
+};
+
+setText("workspace-name", workspace || "Not assigned");
+setText("slot-number", validSlot ? slot : "—");
+
+if (role === "idle" && workspace) {
+  setText("status-label", "Idle · Awaiting next task");
+  setText("description", "This tab is in the WebHelm pool and will be reused automatically when a task needs it.");
+  setText("help-text", "No action required. Leave this tab open. This status describes the tab, not daemon connectivity.");
+} else if (role === "lease" && validSlot && workspace) {
+  setText("status-label", "Reserved for a task");
+  setText("description", "WebHelm has assigned this tab to a browser session.");
+}

package/runtime/extension/workspace-summary.mjs

@@ -0,0 +1,35 @@
+export function summarizeWorkspaces(workspaces, sessions = []) {
+  if (!Array.isArray(workspaces)) throw new Error('Workspace list is invalid');
+  const configured = workspaces.map(workspace => ({
+    name: workspace.name,
+    initialized: Boolean(workspace.initialized),
+    poolSize: Number.isInteger(workspace.poolSize) ? workspace.poolSize : null,
+    idleTabs: workspace.initialized ? workspace.idle : null,
+    leasedTabs: workspace.initialized ? workspace.leased : null,
+    available: workspace.initialized
+      ? Math.max(0, workspace.poolSize - workspace.leased) : null,
+    sessions: sessions.filter(session => session.workspace === workspace.name),
+    reason: workspace.reason || null,
+  }));
+  const configuredNames = new Set(configured.map(workspace => workspace.name));
+  // A running Session can outlive a deleted workspace group. Do not hide it.
+  for (const session of sessions) {
+    if (configuredNames.has(session.workspace)) continue;
+    configuredNames.add(session.workspace);
+    configured.push({
+      name: session.workspace, initialized: false, poolSize: null, idleTabs: null,
+      leasedTabs: null, available: null, sessions: sessions.filter(s => s.workspace === session.workspace),
+      reason: 'not-configured',
+    });
+  }
+  const known = configured.filter(workspace => workspace.initialized && workspace.available !== null);
+  return {
+    workspaces: configured,
+    totalAvailable: configured.length && known.length === configured.length
+      ? known.reduce((total, workspace) => total + workspace.available, 0) : null,
+    totalPhysicalIdle: known.length === configured.length
+      ? known.reduce((total, workspace) => total + workspace.idleTabs, 0) : null,
+    totalSessions: sessions.length,
+    partial: known.length !== configured.length,
+  };
+}

package/runtime/extension/workspace.html

@@ -1,8 +1,11 @@
 <!doctype html>
+<html lang="en">
+<head>
 <meta charset="utf-8">
-<title>Browser Workspace</title>
+<title>WebHelm · Legacy Tab</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>
+</head>
+<body>
+<p>This is a legacy WebHelm tab. It will return to the managed pool when its session ends.</p>
+</body>
+</html>

package/runtime/extension-manager.mjs

@@ -3,11 +3,16 @@ import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import {fileURLToPath} from 'node:url';
+import {LOCAL_ROOT} from './config-paths.mjs';
 
 export const EXTENSION_ID='kkkpgmhpoeceojalkpfdidffdfnlgdog';
-export const EXTENSION_HOME=path.resolve(process.env.WEBHELM_EXTENSION_HOME || path.join(os.homedir(),'.local/webhelm/extension'));
+export const EXTENSION_HOME=path.resolve(process.env.WEBHELM_EXTENSION_HOME || path.join(LOCAL_ROOT,'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'];
+const FILES=[
+  'manifest.json','service-worker.mjs','workspace-manager.mjs','workspace.html','helm.html','workspace-page.mjs',
+  'control-channel.mjs','workspace-summary.mjs','popup.html','popup.mjs',
+  ...[16,32,48,128].map(size => `icons/webhelm-${size}.png`),
+];
 
 function manifest(dir){
   const data=JSON.parse(fs.readFileSync(path.join(dir,'manifest.json'),'utf8'));
@@ -18,9 +23,20 @@ function manifest(dir){
   return data;
 }
 export const extensionVersion=manifest(SOURCE).version;
+function canonicalPath(value) {
+  try { return fs.realpathSync(value || ''); }
+  catch { return path.resolve(value || ''); }
+}
+
+function listRelativeFiles(dir, prefix='') {
+  return fs.readdirSync(path.join(dir,prefix),{withFileTypes:true}).flatMap(entry => {
+    const relative=path.join(prefix,entry.name);
+    return entry.isDirectory() ? listRelativeFiles(dir,relative) : [relative];
+  });
+}
 function identical(dir){
   return fs.existsSync(path.join(dir,'manifest.json'))&&
-    JSON.stringify(fs.readdirSync(dir).sort())===JSON.stringify([...FILES].sort())&&
+    JSON.stringify(listRelativeFiles(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.
@@ -43,7 +59,10 @@ export function stageExtension(dir=EXTENSION_HOME){
   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));
+    for(const filename of FILES){
+      fs.mkdirSync(path.dirname(path.join(stage,filename)),{recursive:true});
+      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')}`);
@@ -66,7 +85,7 @@ export async function ensureExtensionLoaded(browser, {skip=false,extensionDir=EX
   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(!installed || !installed.enabled || installed.version!==version || canonicalPath(installed.path)!==canonicalPath(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');
@@ -82,7 +101,7 @@ export async function ensureExtensionLoaded(browser, {skip=false,extensionDir=EX
   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});
+    const created=await browser.send('Target.createTarget',{url:`${prefix}helm.html?webhelm_wakeup=1`,background:true});
     target={targetId:created.targetId};temporary=true;
   }
   let attached;

package/runtime/login-guard.mjs

@@ -2,23 +2,57 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import {execFileSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
 
 const LABEL='com.lalalic.webhelm.keepalive';
+// launchd must never depend on npm's removable npx cache, or on the Skill
+// launcher being present. Stage an immutable, package-backed runtime locally.
+export function stageRuntimeForLoginGuard({home=os.homedir(),source=fileURLToPath(new URL('../',import.meta.url)),yamlSource=null}={}){
+  const manifest=JSON.parse(fs.readFileSync(path.join(source,'package.json'),'utf8'));
+  if(manifest.name!=='webhelm'||!/^\d+\.\d+\.\d+$/.test(manifest.version))throw Error('Invalid WebHelm runtime package');
+  const parent=path.join(home,'.local/share/webhelm');
+  const target=path.join(parent,`runtime-${manifest.version}`);
+  const keyfiles=['package.json','bin/webhelm.mjs','runtime/cli.mjs','runtime/node-daemon.mjs','runtime/login-guard.mjs'];
+  const equal=()=>keyfiles.every(name=>fs.existsSync(path.join(target,name))&&fs.readFileSync(path.join(target,name)).equals(fs.readFileSync(path.join(source,name))))&&fs.existsSync(path.join(target,'node_modules/yaml/package.json'));
+  if(equal())return {path:target,version:manifest.version,updated:false};
+  const yamlDir=yamlSource||path.resolve(fileURLToPath(import.meta.resolve('yaml')),'../..');
+  if(!fs.existsSync(path.join(yamlDir,'package.json')))throw Error('Bundled Runtime yaml dependency missing');
+  fs.mkdirSync(parent,{recursive:true,mode:0o700});
+  const tmp=fs.mkdtempSync(path.join(parent,'.webhelm-runtime-stage-'));
+  try{
+    for(const dirname of ['bin','runtime'])fs.cpSync(path.join(source,dirname),path.join(tmp,dirname),{recursive:true});
+    fs.copyFileSync(path.join(source,'package.json'),path.join(tmp,'package.json'));
+    fs.mkdirSync(path.join(tmp,'node_modules'),{recursive:true});
+    fs.cpSync(yamlDir,path.join(tmp,'node_modules/yaml'),{recursive:true});
+    let old=null;
+    if(fs.existsSync(target)){
+      old=path.join(parent,`.webhelm-runtime-old-${process.pid}-${Date.now()}`);
+      fs.renameSync(target,old);
+    }
+    try{fs.renameSync(tmp,target);}catch(error){if(old)fs.renameSync(old,target);throw error;}
+    if(old)fs.rmSync(old,{recursive:true,force:true});
+    return {path:target,version:manifest.version,updated:true};
+  }finally{if(fs.existsSync(tmp))fs.rmSync(tmp,{recursive:true,force:true});}
+}
+
 const escapeXml=s=>String(s).replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&apos;'}[c]));
-export function loginGuardDefinition(home=os.homedir()) {
-  const cli=path.join(home,'.local/bin/webhelm');
+export function loginGuardDefinition(home=os.homedir(),{cliPath=path.join(home,'.local/bin/webhelm'),nodePath=null}={}) {
+  const cli=cliPath;
+  const program=nodePath||cli;
+  const args=nodePath?`<string>${escapeXml(cli)}</string><string>ensure</string>`:'<string>ensure</string>';
   const environment=[path.join(home,'.local/bin'),path.join(home,'.local/opt/node22/bin'),
     '/opt/homebrew/bin','/usr/local/bin','/usr/bin','/bin'].join(':');
-  // The short-lived status check starts a missing daemon, and is a no-op if
-  // it already owns the IPC socket. Node daemon independently repairs Chrome.
-  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>${LABEL}</string>\n<key>ProgramArguments</key><array><string>${escapeXml(cli)}</string><string>status</string></array>\n<key>EnvironmentVariables</key><dict><key>PATH</key><string>${escapeXml(environment)}</string><key>HOME</key><string>${escapeXml(home)}</string></dict>\n<key>RunAtLoad</key><true/>\n<key>StartInterval</key><integer>300</integer>\n<key>StandardOutPath</key><string>/dev/null</string>\n<key>StandardErrorPath</key><string>/dev/null</string>\n</dict></plist>\n`;
+  // Use the cached, tested npm Runtime directly to avoid registry/network
+  // dependency at login or when Chrome has just auto-updated. This must call
+  // 'ensure', not 'status': a live daemon does not imply a live Chrome.
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>${LABEL}</string>\n<key>ProgramArguments</key><array><string>${escapeXml(program)}</string>${args}</array>\n<key>EnvironmentVariables</key><dict><key>PATH</key><string>${escapeXml(environment)}</string><key>HOME</key><string>${escapeXml(home)}</string></dict>\n<key>RunAtLoad</key><true/>\n<key>StartInterval</key><integer>30</integer>\n<key>StandardOutPath</key><string>/dev/null</string>\n<key>StandardErrorPath</key><string>/dev/null</string>\n</dict></plist>\n`;
 }
-export function installLoginGuard({home=os.homedir(), platform=process.platform, apply=true}={}){
+export function installLoginGuard({home=os.homedir(), platform=process.platform, apply=true,cliPath,nodePath}={}){
   if(platform!=='darwin')return {status:'unsupported',label:LABEL};
-  const cli=path.join(home,'.local/bin/webhelm');
-  if(!fs.existsSync(cli))return {status:'skipped',reason:'webhelm Skill launcher missing',label:LABEL};
+  const cli=cliPath||path.join(home,'.local/bin/webhelm');
+  if(!fs.existsSync(cli))return {status:'skipped',reason:'WebHelm runtime launcher missing',label:LABEL};
   const dest=path.join(home,'Library/LaunchAgents',`${LABEL}.plist`);
-  const content=loginGuardDefinition(home);
+  const content=loginGuardDefinition(home,{cliPath,nodePath});
   fs.mkdirSync(path.dirname(dest),{recursive:true});
   if(fs.existsSync(dest)){
     const old=fs.readFileSync(dest,'utf8');

package/runtime/managed-chrome-guard.mjs

@@ -2,15 +2,18 @@
 // close a user's Chrome windows to recover the managed browser.
 export function createManagedChromeGuard(check, {intervalMs=15000, onError=()=>{}}={}) {
   if(typeof check!=='function')throw TypeError('health check must be a function');
-  let timer=null, running=false, stopped=false;
+  let timer=null, inFlight=null, stopped=false;
   let last={status:'not_checked'};
-  const tick=async()=>{
-    if(running||stopped)return last;
-    running=true;
-    try{last={status:'healthy',...(await check())};}
-    catch(error){last={status:'degraded',error:String(error?.message||error)};onError(error);}
-    finally{running=false;}
-    return last;
+  const tick=()=>{
+    if(stopped)return Promise.resolve(last);
+    if(inFlight)return inFlight;
+    inFlight=(async()=>{
+      try{last={status:'healthy',...(await check())};}
+      catch(error){last={status:'degraded',error:String(error?.message||error)};onError(error);}
+      finally{inFlight=null;}
+      return last;
+    })();
+    return inFlight;
   };
   return {
     tick,