webhelm 1.0.16 → 1.0.18

package/README.md

@@ -47,7 +47,7 @@ The Actions checkout is `~/.local/webhelm`, with site modules at `~/.local/webhe
 
 ## Architecture and compatibility
 
-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.
+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); no background sweep is started. A timed-out Session refuses subsequent exec, platform Actions and heartbeat, while already-issued browser effects retain tab ownership until settled. A stop that times out while queued cannot execute a late release, and a stop already physically releasing keeps its Session closing until the release finishes. Managed tabs are navigated back to their Extension idle URL instead of closing CDP targets; the Extension does not use `tab.lastAccessed` GC. An async Session execution has a finite deadline: if it expires, its helper capabilities are revoked and the poisoned Session is collected on the next Tab request (or immediately by an explicit stop). Session stop also has a bounded drain/release deadline and cannot leave a permanent closing flag. Client IPC requests have an independent absolute timeout and return an error if the daemon does not respond. These safeguards do not introduce periodic background 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.
 
@@ -63,7 +63,7 @@ Keep platform-specific code and tests in `lalalic/webhelm-actions`. Runtime test
 
 ### 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.
+For new platforms, follow the canonical [`platforms/NEW_PLATFORM.md`](https://github.com/lalalic/webhelm-actions/blob/main/platforms/NEW_PLATFORM.md) in the installed Actions checkout. 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webhelm",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "description": "Agent browser automation in a visible managed Chrome with persistent JavaScript sessions",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "PRIVACY.md"
   ],
   "scripts": {
-    "test": "node --test test/node/*.test.mjs test/workspace-manager.test.mjs skills/webhelm/tests/*.test.mjs",
+    "test": "node --test test/node/*.test.mjs test/workspace-manager.test.mjs test/skill/*.test.mjs",
     "test:package": "npm pack --dry-run --json",
     "test:e2e:extension": "node test/e2e/extension-control.e2e.mjs"
   },

package/runtime/cli-help.mjs

@@ -0,0 +1,322 @@
+// CLI help is the single agent-facing command reference. Keep it in sync with
+// the dispatcher's supported commands and flags.
+const common = 'Use \`webhelm COMMAND --help\` or \`webhelm help COMMAND\` for detailed usage.';
+
+const sections = {
+  '': `webhelm — operate managed Chrome through persistent browser Sessions and site Actions
+
+Usage:
+  webhelm <command> [options]
+  webhelm help [command [subcommand]]
+
+Commands:
+  webhelm setup                            Set up managed Chrome and local Actions
+  webhelm status                           Report browser and daemon status (JSON)
+  webhelm ensure                           Check and recover managed Chrome health
+  webhelm capacity                         Report available browser capacity (JSON)
+  webhelm session start [--url URL]        Start a persistent browser Session
+  webhelm session list                    List CLI-owned Sessions
+  webhelm session exec ID [--code-file F]  Run JavaScript in a Session
+  webhelm session heartbeat ID            Keep a Session alive during idle waits
+  webhelm session stop ID|--all           Stop a Session or explicitly stop all CLI Sessions
+  webhelm platform list                   List installed website integrations
+  webhelm platform profile NAME           Inspect a site's supported fields
+  webhelm platform source NAME ACTION     Read the source of an installed Action
+  webhelm platform run NAME ACTION [...]  Execute an installed site Action
+  webhelm platform sync                   Update installed site Actions
+  webhelm platform publish --message MSG  Publish reviewed site Action changes
+  webhelm migrate                         Migrate supported legacy local browser data
+  webhelm help [command [subcommand]]     Show command help
+Options:
+  -h, --help                       Show help without running the command
+
+Output: operational commands emit JSON; platform source prints JavaScript source.
+${common}`,
+  help: `webhelm help — show command usage without side effects
+
+Usage:
+  webhelm --help
+  webhelm help [COMMAND [SUBCOMMAND]]
+  webhelm COMMAND [SUBCOMMAND] --help
+
+Shows all commands or detailed usage for any available command and subcommand.
+Help never initializes Chrome, changes Sessions, or runs site Actions.
+
+Example:
+  webhelm help session exec`,
+  setup: `webhelm setup — prepare local Actions and managed Chrome
+
+Usage:
+  webhelm setup
+
+Initializes or reuses the site Actions checkout, starts or reuses managed
+Chrome and its daemon, and registers the login-time health check.
+Does not replace an existing Actions checkout with local changes.
+Output: JSON with status, Actions checkout path, daemon and browser details.
+
+Example:
+  webhelm setup`,
+  status: `webhelm status — inspect managed browser and daemon
+
+Usage:
+  webhelm status
+
+Output: JSON describing CLI version, installed Actions location, managed
+Chrome process and profile, health-check state, and daemon Session count.
+
+Example:
+  webhelm status`,
+  ensure: `webhelm ensure — verify and recover managed Chrome health
+
+Usage:
+  webhelm ensure
+
+Checks the existing daemon and managed browser and attempts a safe recovery.
+May defer an incompatible upgrade while active Sessions are running.
+Output: JSON health or deferred-upgrade result.
+
+Example:
+  webhelm ensure`,
+  capacity: `webhelm capacity — inspect browser availability
+
+Usage:
+  webhelm capacity
+
+Reports allocatable browser capacity without opening a Session.
+Output: JSON capacity information.
+
+Example:
+  webhelm capacity`,
+  migrate: `webhelm migrate — migrate supported legacy local browser data
+
+Usage:
+  webhelm migrate
+
+Run only after stopping the legacy daemon and browser and draining Sessions.
+Preserves the signed-in browser profile and supported local state.
+Output: JSON with migration results.
+
+Example:
+  webhelm migrate`,
+  session: `webhelm session — manage persistent JavaScript browser Sessions
+
+Usage:
+  webhelm session <subcommand> [options]
+
+Subcommands:
+  start [--url URL]           Start a Session and receive a session_id
+  list                        List active CLI-owned Sessions
+  exec ID [--code-file FILE]  Run JavaScript in a persistent Session
+  heartbeat ID                Refresh the idle timer for a Session
+  stop ID                     Stop one Session and release its tab
+  stop --all                  Stop all CLI-owned Sessions (destructive)
+
+Always reuse the returned session_id; stop only Sessions owned by your task.
+An idle Session can be reclaimed after five minutes without activity.
+Long-running workflows should heartbeat at least every 60 seconds.
+
+Examples:
+  webhelm session start --url https://example.com
+  webhelm session list
+  webhelm session exec SESSION_ID --code-file ./inspect.js
+  webhelm session stop SESSION_ID
+
+Run 'webhelm session <subcommand> --help' for detailed usage.`,
+  'session start': `webhelm session start — open a persistent browser Session
+
+Usage:
+  webhelm session start [--url URL]
+
+Options:
+  --url URL     Optional initial http(s) destination
+  -h, --help   Show help without opening a browser Session
+
+Output: JSON containing the new session_id. Retain it for exec and stop.
+
+Example:
+  webhelm session start --url https://example.com`,
+  'session list': `webhelm session list — list CLI-owned Sessions
+
+Usage:
+  webhelm session list
+
+Output: JSON with session_count and sessions array, including session_id.
+Does not create a Session.
+
+Example:
+  webhelm session list`,
+  'session exec': `webhelm session exec — run JavaScript in an existing Session
+
+Usage:
+  webhelm session exec SESSION_ID [--code-file FILE]
+  webhelm session exec SESSION_ID <<'JS'
+  console.log(await snapshot());
+  JS
+
+Arguments:
+  SESSION_ID       ID returned by 'webhelm session start'
+
+Options:
+  --code-file FILE Read JavaScript from FILE instead of standard input
+  -h, --help      Show help without executing code
+
+The JavaScript context persists across exec calls. Browser helpers are async:
+  snapshot, page_info, goto_url, wait_for_load, wait_for_element,
+  fill_input, click, js, cdp, new_tab, current_tab, list_tabs,
+  switch_tab, close_tab, upload_file, type_text, capture_screenshot,
+  wait.
+Read 'snapshot()' before using element references and refresh after navigation.
+Use 'new_tab()' rather than raw CDP target creation.
+Output: JSON with execution status and captured result/stdout.
+
+Example:
+  printf 'console.log(await page_info());\\n' | webhelm session exec SESSION_ID`,
+  'session heartbeat': `webhelm session heartbeat — keep an active Session alive
+
+Usage:
+  webhelm session heartbeat SESSION_ID
+
+Refreshes the Session's idle timer without navigating or changing tabs.
+Use at least every 60 seconds during long waits with no browser operations.
+Output: JSON heartbeat result.
+
+Example:
+  webhelm session heartbeat SESSION_ID`,
+  'session stop': `webhelm session stop — release browser Sessions
+
+Usage:
+  webhelm session stop SESSION_ID
+  webhelm session stop --all
+
+Arguments:
+  SESSION_ID    Release one Session owned by the current workflow
+
+Options:
+  --all        Stop every CLI-owned Session; use only when explicitly authorized
+  -h, --help  Show help without stopping Sessions
+
+Output: JSON release result. Stopping a Session may return its tab to idle.
+Do not use --all for ordinary task cleanup.
+
+Example:
+  webhelm session stop SESSION_ID`,
+  platform: `webhelm platform — use installed website Actions
+
+Usage:
+  webhelm platform <subcommand> [options]
+
+Subcommands:
+  list                         List installed site platforms
+  profile PLATFORM             Report site fields and capabilities
+  source PLATFORM ACTION       Print the Action's JavaScript source
+  run PLATFORM ACTION [opts]   Execute a site Action in a browser Session
+  sync                         Fast-forward local Action definitions
+  publish --message MESSAGE    Test, commit and push reviewed Action changes
+
+Examples:
+  webhelm platform list
+  webhelm platform profile chatgpt
+  webhelm platform source z new-turn
+  webhelm platform run z new-turn --session-id SESSION_ID --config ./input.json
+
+Run 'webhelm platform <subcommand> --help' for detailed usage.`,
+  'platform list': `webhelm platform list — discover installed website platforms
+
+Usage:
+  webhelm platform list
+
+Output: JSON array of available site names, read from installed Actions.
+
+Example:
+  webhelm platform list`,
+  'platform profile': `webhelm platform profile — inspect a website integration
+
+Usage:
+  webhelm platform profile PLATFORM
+
+Arguments:
+  PLATFORM    Site name from 'webhelm platform list'
+
+Output: JSON profile with available capabilities, field schemas and notes
+when declared by the platform. Read it before building Action input.
+
+Example:
+  webhelm platform profile chatgpt`,
+  'platform source': `webhelm platform source — inspect an installed site Action
+
+Usage:
+  webhelm platform source PLATFORM ACTION
+
+Arguments:
+  PLATFORM    Site name from 'webhelm platform list'
+  ACTION      Action name defined by the site's manifest
+
+Output: JavaScript source text (not JSON). Inspection has no browser effect.
+
+Example:
+  webhelm platform source z new-turn`,
+  'platform run': `webhelm platform run — execute an installed site Action
+
+Usage:
+  webhelm platform run PLATFORM ACTION --session-id SESSION_ID [--config FILE] [--url URL]
+  webhelm platform run PLATFORM ACTION --auto-session [--config FILE] [--url URL]
+  webhelm platform run chatgpt new-turn [--config FILE] [--mode async|sync] [--session-id ID]
+
+Arguments:
+  PLATFORM       Site name from 'webhelm platform list'
+  ACTION         Action name declared by the site's manifest
+
+Options:
+  --session-id ID Reuse a caller-owned Session (normal interactive mode)
+  --auto-session  Create and release a Session for one self-contained Action
+  --config FILE   Read a JSON object of Action-specific inputs (default: {})
+  --url URL       Optional initial URL for a browser Action
+  --mode MODE     Only for chatgpt/new-turn: async (default) or sync
+  -h, --help     Show help without executing an Action
+
+--session-id and --auto-session cannot be combined. For chatgpt/new-turn,
+async mode uses no Session option; sync mode requires --session-id.
+Inspect 'platform profile' and 'platform source' for Action-specific inputs.
+Output: JSON Action result. An accepted submission may require later verification.
+
+Examples:
+  webhelm platform run z new-turn --session-id SESSION_ID --config ./turn.json
+  webhelm platform run chatgpt new-turn --config ./turn.json
+  webhelm platform run chatgpt new-turn --mode sync --session-id SESSION_ID --config ./turn.json`,
+  'platform sync': `webhelm platform sync — update installed site Actions
+
+Usage:
+  webhelm platform sync
+
+Fetches and fast-forwards the Actions checkout. Refuses to overwrite local
+changes or a diverged checkout. Does not update the browser Runtime.
+Output: JSON sync status and revision.
+
+Example:
+  webhelm platform sync`,
+  'platform publish': `webhelm platform publish — publish verified site Action changes
+
+Usage:
+  webhelm platform publish --message "DESCRIPTION"
+
+Options:
+  --message DESCRIPTION  Required commit description (8–250 characters)
+  -h, --help             Show help without publishing
+
+Runs the independent Actions tests, stages site Action files, commits, and
+pushes without force. Use only for reviewed, authorized changes. Do not
+publish account data, secrets or browser traces.
+Output: JSON publish status and revision.
+
+Example:
+  webhelm platform publish --message "fix(z): update composer selector"`,
+};
+
+export const helpTopics = Object.freeze(Object.keys(sections).filter(Boolean));
+export function cliHelp(topics=[]) {
+  const parts = topics.filter(Boolean);
+  const key = parts.length>1 && ['session','platform'].includes(parts[0])
+    ? parts.slice(0,2).join(' ') : (parts[0] || '');
+  if (!Object.hasOwn(sections,key)) throw Error(`unknown help topic: ${parts.join(' ')}`);
+  return sections[key];
+}

package/runtime/cli.mjs

@@ -9,6 +9,7 @@ import { PLATFORMS, listPlatforms, platformProfile, actionPath, validateConfig }
 import { ACTIONS_DIR, ensureActions, syncActions, publishActions } from './actions-repo.mjs';
 import { migrateConfig, migrateChromeProfile } from './migrate.mjs';
 import { installLoginGuard, stageRuntimeForLoginGuard } from './login-guard.mjs';
+import { cliHelp } from './cli-help.mjs';
 
 const ROOT = path.dirname(fileURLToPath(import.meta.url));
 const CLI_WORKSPACE = 'WebHelm';
@@ -19,30 +20,6 @@ const arg = (items, name) => {
 };
 const has = (items, name) => items.includes(name);
 
-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 ensure  # verify/recover managed Chrome and WebHelm group, not just daemon ping
-  webhelm capacity  # WebHelm workspace only
-  webhelm session start [--url URL]  # WebHelm workspace only
-  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
-  webhelm platform sync
-  webhelm platform publish --message "DESCRIPTION"
-  webhelm platform profile PLATFORM
-  webhelm platform source PLATFORM ACTION
-  webhelm platform run PLATFORM ACTION [--session-id ID | --auto-session] [--config FILE] [--mode async|sync]
-
-Agent workflows should keep their session_id across browser actions and always stop owned sessions.
-`);
-}
 
 function loadConfig(args) {
   const file = arg(args, '--config');
@@ -118,7 +95,14 @@ async function requireCliSession(sessionId) {
 
 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 || ['--help', '-h', 'help'].includes(group) || has(args, '--help') || has(args, '-h') ||
+      ((group === 'session' || group === 'platform') && (!command || command === 'help'))) {
+    const topics = group === 'help'
+      ? args.slice(1).filter(item => !['--help', '-h'].includes(item))
+      : ['--help', '-h'].includes(group) ? [] : args.filter(item => !['--help', '-h', 'help'].includes(item));
+    if (group === 'help' && !topics.length && (has(args, '--help') || has(args, '-h'))) topics.push('help');
+    return console.log(cliHelp(topics));
+  }
   rejectWorkspaceOverride(args);
   if (group === 'migrate') {
     await ensureActions(); // ~/.local/webhelm is the Actions Git checkout, never create an empty replacement.

package/runtime/node-daemon.mjs

@@ -8,7 +8,7 @@ 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 { idleUrlFromIdentity, sameIdleUrl, staleSession, withinDeadline, SessionDeadlineError } from './session-lifecycle.mjs';
 import { stopMatchingSessions } from './session-control.mjs';
 import { ensureManagedChrome } from './chrome.mjs';
 import { ensureExtensionLoaded } from './extension-manager.mjs';
@@ -173,8 +173,8 @@ const managedChromeGuard=createManagedChromeGuard(guardManagedChrome,{
 function adoptPopup(info){if(info?.type!=='page'||!info.openerId)return;const owner=targets.get(info.openerId);if(owner){owner.targets.add(info.targetId);targets.set(info.targetId,owner)}}
 async function attach(s,targetId,b=null){b ||= await connectBrowser();const {sessionId}=await b.send('Target.attachToTarget',{targetId,flatten:true});s.targets.add(targetId);s.attachments.set(targetId,sessionId);targets.set(targetId,s);for(const d of ['Page','DOM','Runtime','Network'])await b.send(`${d}.enable`,{},sessionId);for(const dispose of s.eventDisposers?.get(targetId)||[])dispose();const removers=[];for(const method of ['Page.loadEventFired','Page.domContentEventFired','Page.javascriptDialogOpening','Page.javascriptDialogClosed','Runtime.exceptionThrown','Network.requestWillBeSent','Network.responseReceived'])removers.push(b.on(method,(params,owner)=>{if(owner===sessionId){if(s.events.length>=500)s.events.shift();s.events.push({method,params,session_id:sessionId,target_id:targetId})}}));s.eventDisposers?.set(targetId,removers);return sessionId}
 function sidFor(s,targetId=s.targetId){const sid=s.attachments.get(targetId);if(!sid)throw new Error(`target ${targetId} is not attached to this session`);return sid}
-async function evaluate(s,expression,targetId=s.targetId,awaitPromise=true){if(!s.targets.has(targetId))throw Error('cannot evaluate a target outside the active WebHelm session');const b=await connectBrowser();const r=await b.send('Runtime.evaluate',{expression,returnByValue:true,awaitPromise,userGesture:true},sidFor(s,targetId));if(r.exceptionDetails)throw new Error(r.exceptionDetails.exception?.description||r.exceptionDetails.text);return r.result?.value}
-async function cdp(s,method,params={},targetId=s.targetId){if(method==='Target.createTarget')throw Error('Target.createTarget is disabled; use new_tab(url)');if(method==='Target.attachToTarget'||method==='Target.detachFromTarget')throw Error('direct target attachment changes are disabled in WebHelm sessions');if(['Target.closeTarget','Target.activateTarget'].includes(method)&&!s.targets.has(params.targetId))throw Error('cannot operate on a tab outside the active WebHelm session');if(method.startsWith('Target.')||method.startsWith('Browser.')||method.startsWith('ServiceWorker.'))return connectBrowser().then(b=>b.send(method,params));return connectBrowser().then(b=>b.send(method,params,sidFor(s,targetId)))}
+async function evaluate(s,expression,targetId=s.targetId,awaitPromise=true){if(s.poisoned || s.closing)throw Error('Session execution expired or closing');if(!s.targets.has(targetId))throw Error('cannot evaluate a target outside the active WebHelm session');const b=await connectBrowser();if(s.poisoned || s.closing)throw Error('Session execution expired or closing');const r=await b.send('Runtime.evaluate',{expression,returnByValue:true,awaitPromise,userGesture:true},sidFor(s,targetId));if(r.exceptionDetails)throw new Error(r.exceptionDetails.exception?.description||r.exceptionDetails.text);return r.result?.value}
+async function cdp(s,method,params={},targetId=s.targetId){if(s.poisoned || s.closing)throw Error('Session execution expired or closing');if(method==='Target.createTarget')throw Error('Target.createTarget is disabled; use new_tab(url)');if(method==='Target.attachToTarget'||method==='Target.detachFromTarget')throw Error('direct target attachment changes are disabled in WebHelm sessions');if(['Target.closeTarget','Target.activateTarget'].includes(method)&&!s.targets.has(params.targetId))throw Error('cannot operate on a tab outside the active WebHelm session');return connectBrowser().then(browser=>{if(s.poisoned || s.closing)throw Error('Session execution expired or closing');if(method.startsWith('Target.')||method.startsWith('Browser.')||method.startsWith('ServiceWorker.'))return browser.send(method,params);return browser.send(method,params,sidFor(s,targetId));})}
 function makeHelpers(s){
  const h={
   js:(expression,target_id)=>evaluate(s,expression,target_id||s.targetId),
@@ -183,9 +183,11 @@ function makeHelpers(s){
   async current_tab(){const info=await cdp(s,'Target.getTargetInfo',{targetId:s.targetId});return info.targetInfo},
   async new_tab(url='about:blank') {
     const browser=await connectBrowser();
+    if(s.poisoned || s.closing)throw Error('Session execution expired or closing');
     let targetId,lease;
     if(s.workspaceSupported){
       ({lease,targetId}=await acquireIdentityLease(s));
+      if(s.poisoned || s.closing){await extensionCall(s,'workspace.release',{name:s.workspace,tabId:lease.tabId});throw Error('Session execution expired');}
       s.leasedTabs.set(targetId,lease.tabId);
       s.idleUrls.set(targetId,lease.idleUrl);
     }else ({targetId}=await browser.send('Target.createTarget',{url:'about:blank'}));
@@ -200,6 +202,7 @@ function makeHelpers(s){
     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.poisoned || s.closing)throw Error('Session execution expired or closing');
       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);
@@ -227,7 +230,7 @@ function makeHelpers(s){
   },
   async fill_input(selector,text){if(!await h.wait_for_element(selector))throw Error(`element not found: ${selector}`);return evaluate(s,`(()=>{const e=document.querySelector(${JSON.stringify(selector)});const set=Object.getOwnPropertyDescriptor(Object.getPrototypeOf(e),'value')?.set;if(set)set.call(e,${JSON.stringify(String(text))});else e.textContent=${JSON.stringify(String(text))};e.dispatchEvent(new InputEvent('input',{bubbles:true,inputType:'insertText',data:${JSON.stringify(String(text))}}));e.dispatchEvent(new Event('change',{bubbles:true}));return true})()`)},
   async click(selector){if(!await h.wait_for_element(selector))throw Error(`element not found: ${selector}`);return evaluate(s,`(()=>{const e=document.querySelector(${JSON.stringify(selector)});e.click();return true})()`)},
-  async capture_screenshot(pathname){const b=await connectBrowser();const data=await b.send('Page.captureScreenshot',{format:'png'},sidFor(s));if(pathname)fs.writeFileSync(pathname,Buffer.from(data.data,'base64'));return data.data},
+  async capture_screenshot(pathname){const b=await connectBrowser();if(s.poisoned || s.closing)throw Error('Session execution expired or closing');const data=await b.send('Page.captureScreenshot',{format:'png'},sidFor(s));if(s.poisoned || s.closing)throw Error('Session execution expired or closing');if(pathname)fs.writeFileSync(pathname,Buffer.from(data.data,'base64'));return data.data},
   async snapshot(interactive_only=false){const result=await evaluate(s,`(()=>{let n=0;const xs=[...document.querySelectorAll('button,a,input,textarea,select,[role],[tabindex]')].filter(e=>{const r=e.getBoundingClientRect(),s=getComputedStyle(e);return r.width&&r.height&&s.visibility!=='hidden'&&s.display!=='none'});return xs.map(e=>{const id='e'+(++n);e.setAttribute('data-ref',id);const role=e.getAttribute('role')||({BUTTON:'button',A:'link',INPUT:'textbox',TEXTAREA:'textbox',SELECT:'combobox'}[e.tagName]||e.tagName.toLowerCase());const name=e.getAttribute('aria-label')||e.innerText||e.value||e.placeholder||'';return '- '+role+' '+JSON.stringify(name.trim().slice(0,100))+' [ref='+id+']'}).join('\\n')})()`);return result||''},
   async workspace_status(){return extensionCall(s,'workspace.status',{name:s.workspace})},
   async workspace_capacity(){const r=await h.workspace_status();const idle=Array.isArray(r.idleTabIds)?r.idleTabIds.length:null,leased=Array.isArray(r.leasedTabIds)?r.leasedTabIds.length:null;return {name:r.name,poolSize:r.poolSize??null,maxCapacity:r.maxCapacity??r.poolSize??null,physicalTabs:r.physicalTabs??(idle!==null&&leased!==null?idle+leased:null),idle,leased,available:Number.isInteger(r.maxCapacity??r.poolSize)&&leased!==null?Math.max(0,(r.maxCapacity??r.poolSize)-leased):null}} ,
@@ -263,6 +266,22 @@ function makeHelpers(s){
   async current_url(){return (await h.page_info()).url},
   async title(){return (await h.page_info()).title}
  };
+ // Revoke even helper references retained by unresolved async VM scripts.
+ // A rejected async VM execution does not cancel browser operations it
+ // already started. Keep their tab ownership until those operations settle.
+ const effectHelpers=new Set(['js','cdp','goto_url','new_tab','close_tab','fill_input',
+   'click','capture_screenshot','snapshot','type_text','upload_file','switch_tab','activate_tab']);
+ for(const [name,helper] of Object.entries(h)){
+   if(typeof helper!=='function')continue;
+   h[name]=(...args)=>{
+     if(s.poisoned || s.closing)throw Error('Session execution expired or closing');
+     if(!effectHelpers.has(name))return helper(...args);
+     s.pendingEffects++;
+     try{
+       return Promise.resolve(helper(...args)).finally(()=>{s.pendingEffects--;});
+     }catch(error){s.pendingEffects--;throw error;}
+   };
+ }
  Object.defineProperty(h,'target_id',{get:()=>s.targetId});
  Object.defineProperty(h,'targetId',{get:()=>s.targetId});
  return h;
@@ -363,7 +382,7 @@ async function createSession(req={}) {
   const s={session_id:sid, workspace:req.workspace||await defaultWorkspaceName(), targetId:null,
     rootTargetId:null, workspaceSupported:false,targets:new Set(), attachments:new Map(), eventDisposers:new Map(),
     leasedTabs:new Map(), idleUrls:new Map(), mutex:new Mutex(), events:[], namespace:null,context:null,
-    inFlight:0, closing:false, last_used_at:Date.now()};
+    inFlight:0, pendingEffects:0, closing:false, poisoned:false, last_used_at:Date.now()};
   let targetId,lease;
   try {
     if(await extensionSupported()) {
@@ -411,10 +430,10 @@ async function extensionSupported() {
 
 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)`);
+  if(!s || s.closing || s.poisoned)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');
+    if(s.closing || s.poisoned)throw Error('session closing or expired');
     s.last_used_at=Date.now();
     const logs=[],errors=[];
     const sandbox={...s.namespace};
@@ -427,12 +446,15 @@ async function execute(req) {
       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});
+      const timeoutMs=Math.max(30,Math.min(30000,Number(process.env.WEBHELM_SESSION_EXEC_TIMEOUT_MS)||30000));
+      const result=await withinDeadline(
+        Promise.resolve().then(()=>script.runInContext(s.context,{timeout:timeoutMs})),timeoutMs,'Session exec');
+      if(s.poisoned)throw Error('Session expired during execution');
       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}`}}
+    }catch(e){if(e instanceof SessionDeadlineError || (e?.message||'').includes('Script execution timed out'))s.poisoned=true;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();}
 }
 
@@ -456,6 +478,7 @@ async function navigateIdle(browser,s,targetId,idleUrl){
 async function closeSessionOwned(s){
   if(sessions.get(s.session_id)!==s)return {session_id:s.session_id,already_closed:true};
   s.closing=true;
+  s.poisoned=true; // Revoke delayed helpers after terminal close.
   let release_error=null;
   try {
     const returnedTabs=s.leasedTabs.size;
@@ -487,7 +510,7 @@ async function closeSessionOwned(s){
 async function reconcileWorkspaceSessions(workspace){
   const browser=await connectBrowser();
   for(const s of [...sessions.values()]){
-    if(s.workspace!==workspace||s.closing||s.inFlight>0)continue;
+    if(s.workspace!==workspace||s.closing||s.inFlight>0||s.pendingEffects>0)continue;
     let alreadyIdle=false;
     for(const [tid,idleUrl] of s.idleUrls){
       try {if(sameIdleUrl(await targetUrl(browser,tid),idleUrl)){alreadyIdle=true;break;}}
@@ -503,15 +526,39 @@ async function stopSession(sid){
   const s=sessions.get(sid);
   if(!s)throw Error(`unknown session_id: ${sid}`);
   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));
+  // A timeout does not cancel a queued mutex callback. Fence this stop
+  // attempt before it can touch a Session whose close request failed.
+  const attempt={valid:true,releaseStarted:false};
+  const timeoutMs=Math.max(50,Math.min(90000,Number(process.env.WEBHELM_SESSION_STOP_TIMEOUT_MS)||60000));
+  const deadline=performance.now()+timeoutMs;
+  try {
+    await withinDeadline(s.mutex.run(async()=>{}),timeoutMs,'Session stop drain');
+    // Browser effects already dispatched by an expired VM may outlive its
+    // mutex. They must settle before an idle Tab can be reassigned.
+    while(s.pendingEffects>0){
+      const remaining=deadline-performance.now();
+      if(remaining<=0)throw new SessionDeadlineError('Session stop effects',timeoutMs);
+      await withinDeadline(delay(Math.min(25,remaining)),remaining,'Session stop effects');
+    }
+    return await withinDeadline(leaseMutex(s.workspace).run(async()=>{
+      if(!attempt.valid)throw new SessionDeadlineError('Cancelled Session stop',timeoutMs);
+      attempt.releaseStarted=true;
+      return closeSessionOwned(s);
+    }),Math.max(1,deadline-performance.now()),'Session stop release');
+  }catch(error){
+    attempt.valid=false;
+    if(sessions.get(sid)===s && !attempt.releaseStarted){
+      s.closing=false;s.poisoned=true;
+    }
+    // If physical close already started, keep closing=true until its own
+    // success/failure path finishes; otherwise GC could race its navigation.
+    throw error;
+  }
 }
 
 function heartbeatSession(sid){
   const s=sessions.get(sid);
-  if(!s||s.closing)throw Error(`unknown session_id: ${sid} (missing or closing)`);
+  if(!s||s.closing||s.poisoned)throw Error(`unknown session_id: ${sid} (missing, closing or expired)`);
   s.last_used_at=Date.now();
   return {session_id:sid,alive:true,last_used_at:s.last_used_at};
 }
@@ -629,25 +676,31 @@ async function runPlatform(req) {
   const sid=started.session_id;
   if (!sid) throw Error('platform run requires a session_id or auto_session');
   const session=sessions.get(sid);
-  if (!session) throw Error(`unknown session_id: ${sid}`);
+  if (!session || session.poisoned || session.closing) throw Error(`unknown session_id: ${sid}`);
   let result, cleanup;
   session.inFlight++;
   try {
     result=await session.mutex.run(async()=>{
+      if(session.poisoned||session.closing)throw Error('Session expired while waiting for platform action');
       const logs=[];
       const helpers=makeHelpers(session);
-      helpers.enqueueChatGPTTurn=request=>getChatGPTQueue().enqueue(request);
-      helpers.chatgptQueue=getChatGPTQueue();
+      helpers.enqueueChatGPTTurn=request=>{
+        if(session.poisoned||session.closing)throw Error('Session execution expired or closing');
+        return getChatGPTQueue().enqueue(request);
+      };
+      helpers.chatgptQueue={enqueue:helpers.enqueueChatGPTTurn};
       try {
-        const value=await invokePlatformAction(platform,action,{
+        const actionTimeoutMs=Math.max(50,Math.min(300000,Number(process.env.WEBHELM_PLATFORM_TIMEOUT_MS)||180000));
+        const value=await withinDeadline(Promise.resolve().then(()=>invokePlatformAction(platform,action,{
           helpers, config,
           log:(...items)=>logs.push(items.map(v=>typeof v==='string'?v:JSON.stringify(v)).join(' ')),
-        });
+        })),actionTimeoutMs,'Platform action');
         // Keep the legacy stdout JSON receipt for NeoY/Relay callers, while
         // retaining the structured `value` for new integrations. Do not print
         // a duplicate receipt if the Action already logged its JSON result.
         return {ok:true,stdout:actionOutput(logs,value),stderr:'',value};
       } catch(error) {
+        if(error instanceof SessionDeadlineError)session.poisoned=true;
         return {ok:false,stdout:logs.join('\n').slice(-40000),stderr:'',error:`${error.name}: ${error.message}`};
       }
     });
@@ -667,19 +720,27 @@ async function runPlatform(req) {
 }
 
 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},chrome_guard:managedChromeGuard.status()};case'guard-check':{let status=await managedChromeGuard.tick();for(let retry=0;retry<6 && status.status!=='healthy' && !status.skipped;retry++){await delay(800);status=await managedChromeGuard.tick();}if(status.status!=='healthy' && !status.skipped)throw Error(`WebHelm Chrome health degraded: ${status.error||status.status}`);return {ok:true,chrome_guard:status};}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':return stopAllSessions();case'stop-workspace':{if(typeof req.workspace!=='string'||!req.workspace.trim())throw Error('workspace required');return stopWorkspaceSessions(req.workspace)}case'capacity':return workspaceCapacity(req);case'workspace-create':case'workspace-resize':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 = '';
+export function serve(conn) {
+  let buffer = '', dispatched = false;
+  conn.on('error',()=>{ /* A disconnected client must not crash the daemon. */ });
   conn.setEncoding('utf8');
   conn.on('data', async (chunk) => {
+    if(dispatched)return;
     buffer += chunk;
+    if(buffer.length>8_000_000){
+      dispatched=true;
+      if(!conn.destroyed)conn.end(JSON.stringify({error:'WebHelm IPC request too large'})+'\n');
+      return;
+    }
     const newline = buffer.indexOf('\n');
-    if (newline < 0) return;
+    if (newline < 0 || dispatched) return;
+    dispatched=true;
     const raw = buffer.slice(0, newline);
     try {
       const reply = await handle(JSON.parse(raw));
-      conn.end(JSON.stringify(reply) + '\n');
+      if(!conn.destroyed)conn.end(JSON.stringify(reply) + '\n');
     } catch (error) {
-      conn.end(JSON.stringify({ error: `${error.name}: ${error.message}` }) + '\n');
+      if(!conn.destroyed)conn.end(JSON.stringify({ error: `${error.name}: ${error.message}` }) + '\n');
     }
   });
 }
@@ -688,7 +749,47 @@ async function main(){fs.mkdirSync(RUNTIME,{recursive:true,mode:0o700});let lock
   const controlTimer=setInterval(()=>pollExtensionControl(),3000);
   pollExtensionControl().catch(()=>{});
   const cleanup=async()=>{if(shuttingDown)return;shuttingDown=true;clearInterval(controlTimer);managedChromeGuard.stop();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)})}
+// IPC duration is independent of the daemon's JS/Action execution timeout.
+// A wedged daemon can no longer strand CLI processes indefinitely.
+export function ipcTimeoutMs(op) {
+  const override=Number(process.env.WEBHELM_IPC_TIMEOUT_MS);
+  if(Number.isFinite(override) && override>0)
+    return Math.max(50,Math.min(300000,override));
+  return ({ping:5000,heartbeat:15000,list:15000,capacity:30000,
+    stop:90000,'stop-all':120000,'stop-workspace':120000,
+    exec:45000,'platform-run':240000,start:90000}[op] || 60000);
+}
+async function request(payload,ensure=true){
+  if(ensure)await ensureDaemon();
+  return new Promise((resolve,reject)=>{
+    const conn=net.createConnection(SOCKET);
+    const op=payload?.op||'unknown';
+    let data='',settled=false,deadlineTimer;
+    const finish=(error,result)=>{
+      if(settled)return;
+      settled=true;
+      clearTimeout(deadlineTimer);
+      conn.destroy();
+      if(error)reject(error);
+      else resolve(result);
+    };
+    conn.setEncoding('utf8');
+    deadlineTimer=setTimeout(()=>finish(Error('WebHelm IPC '+op+' timed out')),ipcTimeoutMs(op));
+    conn.on('connect',()=>conn.write(JSON.stringify(payload)+'\n'));
+    conn.on('data',chunk=>{
+      data+=chunk;
+      if(data.length>8_000_000)return finish(Error('WebHelm IPC response too large'));
+      const newline=data.indexOf('\n');
+      if(newline<0)return;
+      try{
+        const result=JSON.parse(data.slice(0,newline));
+        result.error?finish(Error(String(result.error))):finish(null,result);
+      }catch(error){finish(error)}
+    });
+    conn.on('end',()=>{if(!settled)finish(Error('WebHelm IPC '+op+' closed without response'))});
+    conn.on('error',error=>finish(error));
+  });
+}
 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

@@ -1,9 +1,32 @@
 // A Session is live only while its owner performs operations or renews its heartbeat.
 export const SESSION_IDLE_MS = 5 * 60 * 1000;
 
+export class SessionDeadlineError extends Error {
+  constructor(operation, milliseconds) {
+    super(operation + ' exceeded ' + milliseconds + 'ms deadline');
+    this.name = 'SessionDeadlineError';
+  }
+}
+
+// A VM timeout cannot terminate an unresolved async Promise.
+// Callers must revoke Session helpers when a deadline expires.
+export async function withinDeadline(promise, milliseconds, operation) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new SessionDeadlineError(operation, milliseconds)), milliseconds);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 export function staleSession(session, now = Date.now(), ttl = SESSION_IDLE_MS) {
-  return !session.closing && !(session.inFlight > 0) &&
-    now - session.last_used_at >= ttl;
+  return !session.closing && !(session.inFlight > 0) && !(session.pendingEffects > 0) &&
+    (session.poisoned === true || now - session.last_used_at >= ttl);
 }
 
 export function idleUrlFromIdentity(identityUrl) {