webhelm 1.0.1 → 1.0.3

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

@@ -8,10 +8,13 @@ import crypto from 'node:crypto';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 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;
@@ -49,6 +52,7 @@ function leaseMutex(workspace) {
 }
 async function acquireIdentityLease(session) {
   return leaseMutex(session.workspace).run(async()=>{
+    await reconcileWorkspaceSessions(session.workspace);
     const lease=await extensionCall(session,'workspace.acquireIdentity',{name:session.workspace});
     const targetId=await targetForUrl(lease.identityUrl);
     if(!targetId){
@@ -56,9 +60,10 @@ async function acquireIdentityLease(session) {
       throw Error('Workspace extension leased a tab without a matching CDP target');
     }
     if(targets.has(targetId)){
-      // Never release a tab owned by another active Session.
+      // Do not navigate/release a tab still owned by another Session.
       throw Error('Workspace extension returned a target already owned by another Session');
     }
+    lease.idleUrl ||= idleUrlFromIdentity(lease.identityUrl, lease.tabId);
     return {lease,targetId};
   });
 }
@@ -95,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;
@@ -131,6 +138,7 @@ function makeHelpers(s){
     if(s.workspaceSupported){
       ({lease,targetId}=await acquireIdentityLease(s));
       s.leasedTabs.set(targetId,lease.tabId);
+      s.idleUrls.set(targetId,lease.idleUrl);
     }else ({targetId}=await browser.send('Target.createTarget',{url:'about:blank'}));
     await attach(s,targetId);
     s.targetId=targetId;
@@ -139,21 +147,20 @@ function makeHelpers(s){
     return targetId;
   },
   async close_tab(target) {
-    const targetId=typeof target==='string'?target:(target?.targetId||target?.target_id)||s.targetId;
-    if(!s.targets.has(targetId))throw Error('cannot close a tab outside the active WebHelm Session');
-    const lease=s.leasedTabs.get(targetId);
-    if(lease){
-      try{await extensionCall(s,'workspace.release',{name:s.workspace,tabId:lease});}
-      catch{await connectBrowser().then(b=>b.send('Target.closeTarget',{targetId}));}
-    }else await connectBrowser().then(b=>b.send('Target.closeTarget',{targetId}));
-    s.leasedTabs.delete(targetId);
-    s.targets.delete(targetId);
-    s.attachments.delete(targetId);
-    for(const dispose of s.eventDisposers.get(targetId)||[])dispose();
-    s.eventDisposers.delete(targetId);
-    targets.delete(targetId);
-    if(s.targetId===targetId)s.targetId=s.targets.values().next().value;
-    return {closed:true,target_id:targetId};
+    const tid=typeof target==='string'?target:(target?.targetId||target?.target_id)||s.targetId;
+    if(!s.targets.has(tid))throw Error('cannot close a tab outside the active WebHelm Session');
+    return leaseMutex(s.workspace).run(async()=>{
+      const browser=await connectBrowser();
+      if(s.leasedTabs.has(tid))await navigateIdle(browser,s,tid,s.idleUrls.get(tid));
+      else await browser.send('Target.closeTarget',{targetId:tid}); // Popup without pool slot.
+      const attachment=s.attachments.get(tid);
+      if(attachment)await browser.send('Target.detachFromTarget',{sessionId:attachment}).catch(()=>{});
+      s.leasedTabs.delete(tid);s.idleUrls.delete(tid);s.targets.delete(tid);s.attachments.delete(tid);
+      for(const dispose of s.eventDisposers.get(tid)||[])dispose();
+      s.eventDisposers.delete(tid);targets.delete(tid);
+      if(s.targetId===tid)s.targetId=s.targets.values().next().value;
+      return {closed:true,target_id:tid,returned_to_idle:true};
+    });
   },
   async page_info(){return evaluate(s,'({url:location.href,title:document.title,readyState:document.readyState})')},
   async wait_for_load(timeout=15000){const end=Date.now()+timeout;while(Date.now()<end){try{if(await evaluate(s,'document.readyState')==='complete')return true}catch{}await delay(100)}throw Error('page load timed out')},
@@ -291,14 +298,17 @@ async function createSession(req={}) {
   const sid=crypto.randomBytes(8).toString('hex');
   const s={session_id:sid, workspace:req.workspace||'Harness', targetId:null,
     rootTargetId:null, workspaceSupported:false,targets:new Set(), attachments:new Map(), eventDisposers:new Map(),
-    leasedTabs:new Map(), mutex:new Mutex(), events:[], namespace:null,context:null,last_used_at:Date.now()};
+    leasedTabs:new Map(), idleUrls:new Map(), mutex:new Mutex(), events:[], namespace:null,context:null,
+    inFlight:0, closing:false, last_used_at:Date.now()};
   let targetId,lease;
   try {
     if(await extensionSupported()) {
       ({lease,targetId}=await acquireIdentityLease(s));
       s.leasedTabs.set(targetId,lease.tabId);
+      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;
@@ -335,35 +345,110 @@ async function extensionSupported() {
   throw Error(`Browser Workspace extension installed but RPC unavailable: ${error?.message||'unknown'}`);
 }
 
-async function execute(req){const s=sessions.get(req.session_id);if(!s)throw Error(`unknown session_id: ${req.session_id}`);return s.mutex.run(async()=>{s.last_used_at=Date.now();const logs=[],errors=[];const sandbox={...s.namespace};sandbox.console={log:(...x)=>logs.push(x.map(v=>typeof v==='string'?v:JSON.stringify(v)).join(' ')),error:(...x)=>errors.push(x.map(v=>typeof v==='string'?v:JSON.stringify(v)).join(' ')),warn:(...x)=>errors.push(x.map(v=>typeof v==='string'?v:JSON.stringify(v)).join(' '))};s.context=vm.createContext(sandbox);try{let source=String(req.code||'').replace(/(^|\n)\s*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/g,'$1globalThis.$2 =');const lines=source.trimEnd().split('\n');const last=lines.at(-1)?.trim()||'';if(last&&!last.endsWith(';')&&!/^(return|throw|if|for|while|function|class|\}|\/\/)/.test(last)){lines[lines.length-1]=`return (${last})`}source=lines.join('\n');const script=new vm.Script(`(async()=>{${source}\n})()`,{filename:'<webhelm-session>'});const result=await script.runInContext(s.context,{timeout:30000});Object.assign(s.namespace,sandbox);const out={session_id:s.session_id,workspace:s.workspace,target_id:s.targetId,ok:true,stdout:logs.join('\n'),stderr:errors.join('\n')};if(result!==undefined)Object.assign(out,jsonSafe(result));return out}catch(e){return {session_id:s.session_id,workspace:s.workspace,target_id:s.targetId,ok:false,stdout:logs.join('\n'),stderr:errors.join('\n'),error:`${e.name}: ${e.message}`}}})}
+async function execute(req) {
+  const s=sessions.get(req.session_id);
+  if(!s || s.closing)throw Error(`unknown session_id: ${req.session_id} (missing or closing)`);
+  s.inFlight++;
+  try {return await s.mutex.run(async()=>{
+    if(s.closing)throw Error('session closing');
+    s.last_used_at=Date.now();
+    const logs=[],errors=[];
+    const sandbox={...s.namespace};
+    sandbox.console={log:(...x)=>logs.push(x.map(v=>typeof v==='string'?v:JSON.stringify(v)).join(' ')),error:(...x)=>errors.push(x.map(v=>typeof v==='string'?v:JSON.stringify(v)).join(' ')),warn:(...x)=>errors.push(x.map(v=>typeof v==='string'?v:JSON.stringify(v)).join(' '))};
+    s.context=vm.createContext(sandbox);
+    try {
+      let source=String(req.code||'').replace(/(^|\n)\s*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/g,'$1globalThis.$2 =');
+      const lines=source.trimEnd().split('\n');
+      const last=lines.at(-1)?.trim()||'';
+      if(last&&!last.endsWith(';')&&!/^(return|throw|if|for|while|function|class|\}|\/\/)/.test(last))lines[lines.length-1]=`return (${last})`;
+      source=lines.join('\n');
+      const script=new vm.Script(`(async()=>{${source}\n})()`,{filename:'<webhelm-session>'});
+      const result=await script.runInContext(s.context,{timeout:30000});
+      Object.assign(s.namespace,sandbox);
+      const out={session_id:s.session_id,workspace:s.workspace,target_id:s.targetId,ok:true,stdout:logs.join('\n'),stderr:errors.join('\n')};
+      if(result!==undefined)Object.assign(out,jsonSafe(result));
+      return out;
+    }catch(e){return {session_id:s.session_id,workspace:s.workspace,target_id:s.targetId,ok:false,stdout:logs.join('\n'),stderr:errors.join('\n'),error:`${e.name}: ${e.message}`}}
+  });} finally {s.inFlight--;s.last_used_at=Date.now();}
+}
+
+async function targetUrl(browser,targetId) {
+  const reply=await browser.send('Target.getTargetInfo',{targetId});
+  return reply.targetInfo?.url||'';
+}
+
+async function navigateIdle(browser,s,targetId,idleUrl){
+  if(!idleUrl)throw Error('missing idle URL for owned tab');
+  if(sameIdleUrl(await targetUrl(browser,targetId),idleUrl))return;
+  await browser.send('Page.navigate',{url:idleUrl},sidFor(s,targetId));
+  for(let i=0;i<60;i++){
+    if(sameIdleUrl(await targetUrl(browser,targetId),idleUrl))return;
+    await delay(50);
+  }
+  throw Error('idle navigation not confirmed; Session retained');
+}
+
+// Must be invoked while the workspace's allocation mutex is held.
+async function closeSessionOwned(s){
+  if(sessions.get(s.session_id)!==s)return {session_id:s.session_id,already_closed:true};
+  s.closing=true;
+  let release_error=null;
+  try {
+    const count=s.targets.size;
+    await s.mutex.run(async()=>{
+      const browser=await connectBrowser();
+      // Return managed tabs to their original Extension pool; keep their CDP targets.
+      for(const tid of [...s.targets]){
+        if(s.leasedTabs.has(tid)){
+          await navigateIdle(browser,s,tid,s.idleUrls.get(tid));
+        } else {
+          // Unleased child popup targets have no managed pool slot.
+          await browser.send('Target.closeTarget',{targetId:tid});
+        }
+      }
+      for(const [,attachment] of s.attachments)await browser.send('Target.detachFromTarget',{sessionId:attachment}).catch(()=>{});
+      for(const [tid,disposers] of s.eventDisposers){for(const dispose of disposers)dispose();targets.delete(tid);}
+      for(const tid of s.targets)targets.delete(tid);
+      s.targets.clear();s.attachments.clear();s.leasedTabs.clear();s.idleUrls.clear();s.eventDisposers.clear();
+      sessions.delete(s.session_id);
+    });
+    return {session_id:s.session_id,workspace:s.workspace,target_id:s.rootTargetId,closed_tabs:count,returned_to_idle:true,release_error};
+  }catch(error){
+    s.closing=false; // Keep ownership for a future retry; never reassign on unconfirmed navigation.
+    throw error;
+  }
+}
+
+async function reconcileWorkspaceSessions(workspace){
+  const browser=await connectBrowser();
+  for(const s of [...sessions.values()]){
+    if(s.workspace!==workspace||s.closing||s.inFlight>0)continue;
+    let alreadyIdle=false;
+    for(const [tid,idleUrl] of s.idleUrls){
+      try {if(sameIdleUrl(await targetUrl(browser,tid),idleUrl)){alreadyIdle=true;break;}}
+      catch {alreadyIdle=true;break;} // Lost target means this Session is no longer valid.
+    }
+    if(!alreadyIdle&&!staleSession(s))continue;
+    try {await closeSessionOwned(s);}
+    catch(error){console.error(JSON.stringify({component:'session-gc',session_id:s.session_id,error:String(error)}));}
+  }
+}
+
 async function stopSession(sid){
   const s=sessions.get(sid);
   if(!s)throw Error(`unknown session_id: ${sid}`);
-  const count=s.targets.size;
-  let release_error=null, recovered_tab_closes=0;
-  await s.mutex.run(async()=>{
-    const browser=await connectBrowser();
-    for(const tid of [...s.targets]){
-      try{
-        const leasedTabId=s.leasedTabs.get(tid);
-        if(leasedTabId) {
-          try{await extensionCall(s,'workspace.release',{name:s.workspace,tabId:leasedTabId});}
-          catch(error){
-            // If MV3 lost its transient ownership map, never leave an orphan.
-            // The CDP Target is owned exclusively by this Session.
-            await browser.send('Target.closeTarget',{targetId:tid});
-            recovered_tab_closes++;
-          }
-        }else await browser.send('Target.closeTarget',{targetId:tid});
-      }catch(error){release_error=release_error||String(error);}
-      s.leasedTabs.delete(tid);targets.delete(tid);
-      for(const dispose of s.eventDisposers.get(tid)||[])dispose();
-      s.eventDisposers.delete(tid);
-    }
-    for(const [,attachment] of s.attachments)await browser.send('Target.detachFromTarget',{sessionId:attachment}).catch(()=>{});
-    sessions.delete(sid);
-  });
-  return {session_id:sid,workspace:s.workspace,target_id:s.rootTargetId,closed_tabs:count,recovered_tab_closes,release_error};
+  s.closing=true;
+  // Do not hold the workspace allocation lock while an in-flight operation
+  // might be acquiring a new tab: that would deadlock its Session mutex.
+  await s.mutex.run(async()=>{});
+  return leaseMutex(s.workspace).run(()=>closeSessionOwned(s));
+}
+
+function heartbeatSession(sid){
+  const s=sessions.get(sid);
+  if(!s||s.closing)throw Error(`unknown session_id: ${sid} (missing or closing)`);
+  s.last_used_at=Date.now();
+  return {session_id:sid,alive:true,last_used_at:s.last_used_at};
 }
 
 async function workspaceOp(req){const h=makeHelpers({workspace:req.name||'Harness',targetId:'',targets:new Set(),attachments:new Map()});if(req.op==='workspace-create')return h.workspace_create(req.name,req.pool_size);if(req.op==='workspace-delete')return h.workspace_delete(req.name,req.force);throw Error(`unknown op: ${req.op}`)}
@@ -418,6 +503,7 @@ async function runPlatform(req) {
   const session=sessions.get(sid);
   if (!session) throw Error(`unknown session_id: ${sid}`);
   let result, cleanup;
+  session.inFlight++;
   try {
     result=await session.mutex.run(async()=>{
       const logs=[];
@@ -438,6 +524,7 @@ async function runPlatform(req) {
       }
     });
   } finally {
+    session.inFlight--;session.last_used_at=Date.now();
     cleanup=auto ? await stopSession(sid).catch(e=>({release_error:e.message})) : {caller_owned_session:true};
   }
   result.cleanup=cleanup;
@@ -451,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'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');
@@ -471,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};

package/runtime/session-lifecycle.mjs

@@ -0,0 +1,24 @@
+// A Session is live only while its owner performs operations or renews its heartbeat.
+export const SESSION_IDLE_MS = 5 * 60 * 1000;
+
+export function staleSession(session, now = Date.now(), ttl = SESSION_IDLE_MS) {
+  return !session.closing && !(session.inFlight > 0) &&
+    now - session.last_used_at >= ttl;
+}
+
+export function idleUrlFromIdentity(identityUrl, tabId) {
+  const url = new URL(identityUrl);
+  if (url.protocol !== 'chrome-extension:' || !url.pathname.endsWith('/workspace.html')) {
+    throw new Error('invalid extension identity URL');
+  }
+  url.searchParams.set('role', 'idle');
+  url.searchParams.set('slot', String(tabId));
+  return url.href;
+}
+
+export function sameIdleUrl(actual, expected) {
+  try {
+    const url = new URL(actual), idle = new URL(expected);
+    return url.protocol === 'chrome-extension:' && url.href === idle.href;
+  } catch { return false; }
+}