webhelm 1.0.0 → 1.0.2

package/README.md

@@ -9,7 +9,7 @@
 | [`lalalic/webhelm`](https://github.com/lalalic/webhelm) | npm Runtime/CLI, Skill (`skills/webhelm`), Chrome Extension, 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 is a small `npx --yes webhelm@latest` launcher; its contents may update without a Runtime release.
+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.
 
 ## Install and use
 
@@ -24,6 +24,7 @@ npx --yes webhelm@latest session exec SESSION_ID <<'JS'
 console.log(await snapshot());
 JS
 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`.
@@ -32,7 +33,7 @@ The Actions checkout is `~/.local/webhelm`, with site modules at `~/.local/webhe
 
 ## Architecture and compatibility
 
-The Runtime's managed Chrome profile and its IPC socket remain at their existing `~/.config/browser-workspace/` locations to preserve logins, sessions and queue data. Only one daemon is permitted to own the queue. A CLI package update does not kill a running daemon or close another agent's tabs; upgrade daemons when idle.
+The Runtime stores its managed Chrome profile, persistent FIFO queue, and IPC socket under `~/.config/webhelm/`. Run `webhelm migrate` with the legacy daemon and Chrome stopped to migrate existing `~/.config/browser-workspace/` data without dropping logins or queued turns. The command leaves a compatibility symlink for legacy maintenance scripts. Session idle GC runs on Node before new Session allocation (5 minutes without operations or explicit heartbeat). Managed tabs are navigated back to their Extension idle URL instead of closing CDP targets; the Extension does not use `tab.lastAccessed` GC. Only one daemon is permitted to own the queue. A CLI package update does not kill a running daemon or close another agent's tabs; upgrade daemons when idle.
 
 NeoY and Relay can continue using `webhelm` session commands, `result.stdout` JSON receipts, and `admin_helper` returned by `status`. An `admin_helper` inside the installed Skill is a stable connector to the same Node IPC socket. `webhelm capacity` replaces the legacy Python capacity probe.
 
@@ -45,3 +46,11 @@ npm pack --dry-run
 ```
 
 Keep platform-specific code and tests in `lalalic/webhelm-actions`. Runtime tests should use mock CDP or owned, temporary real Chrome tabs; protect other active Sessions. GitHub Actions runs Runtime/Extension CI. The Skill and Extension remain version-controlled together; npm publishing uses the standalone package at the repository root.
+
+### Adding an unsupported platform
+
+The WebHelm Skill includes [`skills/webhelm/NEW_PLATFORM.md`](skills/webhelm/NEW_PLATFORM.md). All new platform code belongs in **`~/.local/webhelm/platforms/<slug>`**, checked out from `lalalic/webhelm-actions`, including tests and docs. There is no separate `platforms/` directory in the Skill or npm package. Publishing an Action uses Git, not npm.
+
+## npm publishing
+
+`.github/workflows/publish.yml` publishes CLI/Runtime changes on `main` using GitHub Actions and npm OIDC trusted publishing. It reuses Agents Relay's bounded-test and publication-report Actions, as the other repositories do. The CI workflow never stores an npm write token or asks for a local 2FA approval. Configure the **webhelm** npm package's Trusted Publisher once: GitHub user `lalalic`, repository `webhelm`, workflow filename `publish.yml` (no environment), with **Allow npm publish** enabled. New configurations otherwise default to staged-only publishing and require individual approvals. A successful publish is verified against the npm registry and reported to Agents Relay. Skill-only and platform Action changes do not trigger npm publication.

package/package.json

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

package/runtime/admin.mjs

@@ -1,7 +1,7 @@
 import net from 'node:net';
-import os from 'node:os';
+import { RUNTIME_DIR } from './config-paths.mjs';
 import path from 'node:path';
-const socketPath=()=>process.env.WEBHELM_SOCKET||path.join(process.env.WEBHELM_RUNTIME_DIR||path.join(os.homedir(),'.config/browser-workspace/runtime'),'session-node.sock');
+const socketPath=()=>process.env.WEBHELM_SOCKET||path.join(process.env.WEBHELM_RUNTIME_DIR||RUNTIME_DIR,'session-node.sock');
 function request(payload){return new Promise((resolve,reject)=>{const s=net.createConnection(socketPath());let buf='';s.setEncoding('utf8');s.on('connect',()=>s.write(JSON.stringify(payload)+'\n'));s.on('data',d=>{buf+=d;if(!buf.includes('\n'))return;s.end();try{const v=JSON.parse(buf);v.error?reject(Error(v.error)):resolve(v)}catch(e){reject(e)}});s.on('error',reject)})}
 export async function ensureWorkspace(name,size=5){if(typeof name!=='string'||!name.trim())throw TypeError('workspace name must be a non-empty string');if(!Number.isInteger(size)||size<1)throw TypeError('workspace size must be a positive integer');return request({op:'workspace-create',name:name.trim(),pool_size:size})}
 export async function deleteWorkspace(name,{force=false}={}){if(typeof name!=='string'||!name.trim())throw TypeError('workspace name must be a non-empty string');return request({op:'workspace-delete',name:name.trim(),force:Boolean(force)})}

package/runtime/chatgpt/chatgpt-delivery-errors.mjs

@@ -74,7 +74,7 @@ export async function normalizeFailure(
   {
     logPath = join(
       homedir(),
-      ".config/browser-workspace/runtime/chatgpt-delivery-errors.jsonl",
+      ".config/webhelm/runtime/chatgpt-delivery-errors.jsonl",
     ),
   } = {},
 ) {

package/runtime/chrome.mjs

@@ -1,12 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
 import net from 'node:net';
 import { spawn, execFileSync } from 'node:child_process';
 
-const HOME = os.homedir();
-const ROOT = path.join(HOME, '.config/browser-workspace');
-const PROFILE = path.join(ROOT, 'chrome');
+import { CONFIG_ROOT, PROFILE_DIR, requireMigratedConfig } from './config-paths.mjs';
+const ROOT = CONFIG_ROOT;
+const PROFILE = PROFILE_DIR;
 const STATE = path.join(ROOT, 'managed-chrome.json');
 const LOCK = path.join(ROOT, 'managed-chrome-node.lock');
 const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
@@ -95,6 +94,7 @@ export async function ensureManagedChrome(){
   // Explicit CDP endpoints also support hermetic mock-browser tests.
   const specified=process.env.WEBHELM_CDP_URL;
   if (specified) return {mode:'override',reused:true,endpoint:specified,profile_dir:PROFILE};
+  requireMigratedConfig();
   return lockOwnership(async()=>{
     const existing=await fromState()||await discover();
     if(existing)return {...existing, mode:'managed',reused:true,endpoint:`http://127.0.0.1:${existing.port}`};

package/runtime/cli.mjs

@@ -7,6 +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';
 
 const ROOT = path.dirname(fileURLToPath(import.meta.url));
 const emit = value => console.log(JSON.stringify(value));
@@ -20,11 +21,13 @@ function help() {
   console.log(`webhelm — browser automation through one Node.js runtime
 
 Usage:
+  webhelm migrate  # after stopping Chrome and the old WebHelm daemon
   webhelm setup
   webhelm status
   webhelm capacity [--workspace NAME]
   webhelm session start [--url URL]
   webhelm session list
+  webhelm session heartbeat SESSION_ID  # keep a working Session alive
   webhelm session exec SESSION_ID [--code-file FILE]   # JavaScript
   webhelm session stop SESSION_ID|--all
   webhelm platform list
@@ -96,6 +99,7 @@ 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 === 'setup') {
     const repo=await ensureActions();
     const chrome=await ensureDaemon();
@@ -103,7 +107,7 @@ async function main(args = process.argv.slice(2)) {
   }
   if (group === 'status') {
     const daemon = await ensureDaemon();
-    return emit({version:'1.0.0', platform_dir:PLATFORMS, root:ROOT,
+    return emit({version:'1.0.1', 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,
@@ -123,6 +127,10 @@ async function main(args = process.argv.slice(2)) {
   if (group === 'session') {
     if (command === 'start') return emit(await request({op:'start', workspace:arg(args,'--workspace'), url:arg(args,'--url')}));
     if (command === 'list') return emit(await request({op:'list'}));
+    if (command === 'heartbeat') {
+      if (!args[2]) throw Error('session heartbeat requires SESSION_ID');
+      return emit(await request({op:'heartbeat',session_id:args[2]}));
+    }
     if (command === 'stop') return emit(await request(has(args,'--all') ? {op:'stop-all'} : {op:'stop',session_id:args[2]}));
     if (command === 'exec') {
       if (!args[2]) throw Error('session exec requires SESSION_ID');

package/runtime/config-paths.mjs

@@ -0,0 +1,14 @@
+import os from 'node:os';
+import path from 'node:path';
+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 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))
+    throw Error(`Legacy Chrome profile exists at ${LEGACY_ROOT}. Stop old Chrome and WebHelm daemon, then run webhelm migrate.`);
+}

package/runtime/migrate.mjs

@@ -0,0 +1,47 @@
+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';
+
+function liveSocket(socketPath) {
+  return new Promise(resolve => {
+    const socket = net.createConnection(socketPath);
+    const finish = result => { socket.destroy(); resolve(result); };
+    socket.once('connect', () => finish(true));
+    socket.once('error', () => finish(false));
+    socket.setTimeout(1200, () => finish(true)); // Fail closed if probing hangs.
+  });
+}
+
+export async function migrateConfig({ legacyRoot = LEGACY_ROOT, configRoot = CONFIG_ROOT,
+  processList = () => execFileSync('ps', ['-axo', 'command='], { encoding: 'utf8' }),
+  socketCheck = liveSocket } = {}) {
+  const legacy = path.resolve(legacyRoot);
+  const target = path.resolve(configRoot);
+  if (legacy === target) throw Error('Legacy and new config paths are identical');
+  let oldStat;
+  try { oldStat = fs.lstatSync(legacy); }
+  catch (e) { if (e.code === 'ENOENT') return { status: 'not_needed', config_root: target }; throw e; }
+  if (oldStat.isSymbolicLink()) {
+    if (fs.existsSync(target) && fs.realpathSync(legacy) === fs.realpathSync(target))
+      return { status: 'already_migrated', config_root: target, compatibility_symlink: legacy };
+    throw Error(`Legacy path is a different symlink: ${legacy}`);
+  }
+  if (!oldStat.isDirectory()) throw Error(`Legacy path is not a directory: ${legacy}`);
+  if (fs.existsSync(target)) throw Error(`Target already exists; refusing to overwrite: ${target}`);
+  const running = processList().split('\n').filter(line =>
+    line.includes(`--user-data-dir=${path.join(legacy, 'chrome')}`) ||
+    (line.includes('node-daemon.mjs daemon') && !line.includes('migrate.mjs')));
+  if (running.length) throw Error('Chrome or WebHelm daemon is still running; stop Sessions, daemon and Chrome before migration');
+  const socket = path.join(legacy, 'runtime', 'session-node.sock');
+  if (fs.existsSync(socket) && await socketCheck(socket))
+    throw Error('Legacy daemon socket is active; refusing migration');
+  fs.renameSync(legacy, target); // Same-volume atomic directory move; preserve Chrome data and FIFO WAL.
+  try { fs.symlinkSync(target, legacy, 'dir'); }
+  catch (error) {
+    fs.renameSync(target, legacy);
+    throw error;
+  }
+  return { status: 'migrated', config_root: target, compatibility_symlink: legacy };
+}

package/runtime/node-daemon.mjs

@@ -8,12 +8,14 @@ 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 { PROFILE_DIR, RUNTIME_DIR, requireMigratedConfig } from './config-paths.mjs';
 
 const ROOT = path.dirname(new URL(import.meta.url).pathname);
 const HOME = os.homedir();
-export const PROFILE_DIR = path.join(HOME, '.config/browser-workspace/chrome');
-const DEFAULT_RUNTIME = path.join(HOME, '.config/browser-workspace/runtime');
+export { PROFILE_DIR };
+const DEFAULT_RUNTIME = RUNTIME_DIR;
 const RUNTIME = process.env.WEBHELM_RUNTIME_DIR || DEFAULT_RUNTIME;
 const SOCKET = process.env.WEBHELM_SOCKET || path.join(RUNTIME, 'session-node.sock');
 const LOCK = process.env.WEBHELM_LOCK || path.join(RUNTIME, 'session-node.lock');
@@ -48,6 +50,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){
@@ -55,9 +58,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};
   });
 }
@@ -130,6 +134,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;
@@ -138,21 +143,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')},
@@ -290,12 +294,14 @@ 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 {
       ({targetId}=await browser.send('Target.createTarget',{url:'about:blank'}));
@@ -334,35 +340,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}`)}
@@ -417,6 +498,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=[];
@@ -437,6 +519,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;
@@ -450,7 +533,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.0',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:'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}`)}}
 function serve(conn) {
   let buffer = '';
   conn.setEncoding('utf8');
@@ -470,6 +553,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(){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(){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')}`)}
 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; }
+}