browser-workspace 0.4.2 → 0.4.9

package/src/browser_workspace_app/node/admin.mjs

@@ -0,0 +1,44 @@
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+function socketPath() {
+  if (process.env.BROWSER_WORKSPACE_TEST_MODE === "1" && process.env.BROWSER_WORKSPACE_SESSION_SOCKET) return process.env.BROWSER_WORKSPACE_SESSION_SOCKET;
+  return path.join(os.homedir(), ".config", "browser-workspace", "runtime", "session.sock");
+}
+
+function request(payload) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection({ path: socketPath() });
+    let buffer = "";
+    let settled = false;
+    const fail = (error) => { if (!settled) { settled = true; reject(error); } };
+    socket.setEncoding("utf8");
+    socket.on("connect", () => socket.write(`${JSON.stringify(payload)}\n`));
+    socket.on("data", chunk => {
+      buffer += chunk;
+      const newline = buffer.indexOf("\n");
+      if (newline < 0 || settled) return;
+      settled = true;
+      socket.end();
+      try {
+        const result = JSON.parse(buffer.slice(0, newline));
+        if (result && result.error) reject(new Error(result.error));
+        else resolve(result);
+      } catch (error) { reject(error); }
+    });
+    socket.on("error", fail);
+    socket.on("end", () => { if (!settled) fail(new Error("browser-workspace daemon closed without a response")); });
+  });
+}
+
+export async function ensureWorkspace(name, size = 5) {
+  if (typeof name !== "string" || !name.trim()) throw new TypeError("workspace name must be a non-empty string");
+  if (!Number.isInteger(size) || size < 1) throw new 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 new TypeError("workspace name must be a non-empty string");
+  return request({ op: "workspace-delete", name: name.trim(), force: Boolean(force) });
+}

package/src/browser_workspace_app/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "browser-workspace",
+  "version": "0.4.8",
+  "description": "Agent browser workspace with persistent sessions, tab leasing, snapshots, and platform workflows.",
+  "bin": {
+    "browser-workspace": "bin/browser-workspace"
+  },
+  "files": [
+    "bin/",
+    "node/",
+    "src/",
+    "agent-workspace/agent_helpers.py",
+    "interaction-skills/",
+    "platforms/",
+    "licenses/",
+    "platform_runner.py",
+    "session_client.py",
+    "session_daemon.py",
+    "pyproject.toml",
+    "README.md",
+    "SKILL.md",
+    "PRIVACY.md",
+    "managed_chrome.py",
+    "extension/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "python3 -m pytest -q test && node --test test/workspace-manager.test.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lalalic/browser-workspace.git"
+  }
+}

package/src/browser_workspace_app/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools==84.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "browser-workspace"
+version = "0.4.8"
+description = "Agent browser workspace with persistent Python sessions, tab leasing, snapshots, and platform workflows."
+requires-python = ">=3.11"
+dependencies = [
+  "browser-harness==0.1.13",
+  "cdp-use==1.4.5",
+  "fetch-use==0.4.0",
+  "pillow==12.3.0",
+  "PyYAML==6.0.2",
+  "websockets==15.0.1",
+]
+
+[project.scripts]
+browser-workspace = "browser_workspace_app.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+browser_workspace_app = ["**/*"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+addopts = "--import-mode=importlib"

package/src/browser_workspace_app/session_client.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+import fcntl, json, os, shutil, socket, subprocess, sys, time
+from pathlib import Path
+
+ROOT=Path(__file__).resolve().parent
+RUNTIME_DIR=Path.home()/'.config/browser-workspace/runtime'
+SOCKET_PATH=(Path(os.environ['BROWSER_WORKSPACE_SESSION_SOCKET']) if os.environ.get('BROWSER_WORKSPACE_TEST_MODE')=='1' and os.environ.get('BROWSER_WORKSPACE_SESSION_SOCKET') else RUNTIME_DIR/'session.sock')
+HARNESS_RUNTIME_SPEC='browser-harness @ git+https://github.com/lalalic/browser-harness.git@80b74e116b9126f5159c84e5e05a750573e5f192'
+
+def package_version():
+    try:
+        return json.loads((ROOT/'package.json').read_text()).get('version','dev')
+    except Exception:
+        return 'dev'
+
+def runtime_source():
+    configured=os.environ.get('BROWSER_WORKSPACE_RUNTIME_SOURCE')
+    if configured: return Path(configured)
+    if not (ROOT/'package.json').exists(): return ROOT
+    target=RUNTIME_DIR/'packages'/package_version()
+    marker=target/'.ready'
+    if marker.exists(): return target
+    target.parent.mkdir(parents=True,exist_ok=True)
+    tmp=target.with_name(target.name+'.tmp')
+    shutil.rmtree(tmp,ignore_errors=True)
+    tmp.mkdir(parents=True)
+    for name in ['pyproject.toml','session_daemon.py','session_client.py','platform_runner.py','managed_chrome.py','src','agent-workspace','interaction-skills','platforms','extension','licenses']:
+        source=ROOT/name
+        if not source.exists(): continue
+        destination=tmp/name
+        if source.is_dir(): shutil.copytree(source,destination)
+        else: shutil.copy2(source,destination)
+    # A published wheel installs directly under browser_workspace_app/ without
+    # a nested src/ tree. Reconstruct the build layout only in the runtime
+    # cache, never in the repository or published source tree.
+    if not (tmp/'src').exists():
+        package_root = tmp/'src'/'browser_workspace_app'
+        package_root.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(ROOT, package_root, ignore=shutil.ignore_patterns('__pycache__', '*.pyc', '.DS_Store'))
+    (tmp/'.ready').write_text(package_version())
+    shutil.rmtree(target,ignore_errors=True)
+    tmp.rename(target)
+    return target
+
+SOURCE=runtime_source()
+PYTHON=Path(os.environ.get('BROWSER_WORKSPACE_SESSION_PYTHON',RUNTIME_DIR/'venv'/package_version()/'bin/python'))
+
+
+
+def ensure_runtime_python():
+    if PYTHON.exists():
+        return PYTHON
+    RUNTIME_DIR.mkdir(parents=True, exist_ok=True)
+    lock_path=RUNTIME_DIR/'runtime-bootstrap.lock'
+    with open(lock_path,'a+b') as lock:
+        fcntl.flock(lock,fcntl.LOCK_EX)
+        if PYTHON.exists():
+            return PYTHON
+        uv=shutil.which('uv')
+        if uv:
+            subprocess.run([uv,'venv','--python','3.11',str(PYTHON.parent.parent)],check=True)
+            subprocess.run([uv,'pip','install','--python',str(PYTHON),'-e',str(SOURCE)],check=True)
+            subprocess.run([uv,'pip','install','--python',str(PYTHON),'--reinstall',HARNESS_RUNTIME_SPEC],check=True)
+            return PYTHON
+        if sys.version_info < (3,11):
+            raise RuntimeError(
+                'Browser Workspace needs Python 3.11+ for first-use bootstrap. '
+                'Install uv or Python 3.11+, then retry.'
+            )
+        subprocess.run([sys.executable,'-m','venv',str(PYTHON.parent.parent)],check=True)
+        subprocess.run([str(PYTHON),'-m','pip','install','-e',str(SOURCE)],check=True)
+        subprocess.run([str(PYTHON),'-m','pip','install','--force-reinstall',HARNESS_RUNTIME_SPEC],check=True)
+        return PYTHON
+
+def request(payload, ensure=True):
+    if ensure: ensure_daemon()
+    s=socket.socket(socket.AF_UNIX,socket.SOCK_STREAM)
+    try: s.connect(str(SOCKET_PATH))
+    except Exception:
+        s.close(); raise
+    with s:
+        f=s.makefile('rwb'); f.write((json.dumps(payload,ensure_ascii=False)+'\n').encode()); f.flush(); line=f.readline()
+    if not line: raise RuntimeError('browser-workspace session daemon closed without a response')
+    return json.loads(line)
+
+def ping():
+    try: return request({'op':'ping'},ensure=False)
+    except Exception: return None
+
+def owner_is_running():
+    """An exclusive owner lock means a live daemon already exists."""
+    owner_path=RUNTIME_DIR/'session.lock'
+    with open(owner_path,'a+b') as owner:
+        try:
+            fcntl.flock(owner,fcntl.LOCK_EX|fcntl.LOCK_NB)
+        except BlockingIOError:
+            return True
+        finally:
+            try: fcntl.flock(owner,fcntl.LOCK_UN)
+            except OSError: pass
+    return False
+
+def ensure_daemon():
+    p=ping()
+    if p and p.get('ok'): return p
+    RUNTIME_DIR.mkdir(parents=True,exist_ok=True)
+    if owner_is_running():
+        raise RuntimeError('browser-workspace daemon is alive but its socket is unreachable; refusing duplicate startup')
+    runtime_python=ensure_runtime_python()
+    log=open(RUNTIME_DIR/'session-daemon.log','ab',buffering=0)
+    subprocess.Popen([str(runtime_python),str(SOURCE/'session_daemon.py')],stdin=subprocess.DEVNULL,stdout=log,stderr=log,start_new_session=True,close_fds=True)
+    deadline=time.time()+15
+    while time.time()<deadline:
+        time.sleep(.1); p=ping()
+        if p and p.get('ok'): return p
+    raise RuntimeError(f'browser-workspace session daemon did not start; see {RUNTIME_DIR / "session-daemon.log"}')

package/src/browser_workspace_app/session_daemon.py

@@ -0,0 +1,431 @@
+#!/usr/bin/env python3
+import ast, atexit, contextlib, io, json, os, secrets, signal, socket, sys, threading, time, traceback
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+sys.path.insert(0, str(ROOT/'src'))
+os.environ.setdefault('BH_HOME', str(Path.home()/'.config/browser-workspace/browser-core'))
+# Preserve the canonical single Browser Harness daemon socket during migration.
+# This is runtime-state compatibility only; Browser Workspace owns the code/venv.
+os.environ.setdefault('BH_RUNTIME_DIR', str(Path.home()/'.config/browser-workspace/browser-core-runtime'))
+os.environ.setdefault('BU_NAME', 'browser-workspace')
+os.environ.setdefault('BH_AGENT_WORKSPACE', str(ROOT/'agent-workspace'))
+os.environ.setdefault('BH_WORKSPACE_NAME', 'Harness')
+
+from managed_chrome import ensure_managed_chrome
+MANAGED_CHROME = ensure_managed_chrome()
+from browser_harness.admin import ensure_daemon, _process_start_time
+from browser_harness import _ipc as harness_ipc
+from browser_harness import helpers as bh
+
+HARNESS_OWNER_TOKEN = secrets.token_hex(24)
+HARNESS_OWNER_PID = os.getpid()
+HARNESS_OWNER_STARTED = _process_start_time(HARNESS_OWNER_PID)
+HARNESS_OWNER_PIPE = None
+
+
+def stop_owned_harness():
+    """Only a harness matching this daemon generation may stop."""
+    try:
+        conn, token = harness_ipc.connect(os.environ.get('BU_NAME', 'browser-workspace'), timeout=1)
+        with conn:
+            response = harness_ipc.request(conn, token, {'meta': 'owner_shutdown', 'owner_token': HARNESS_OWNER_TOKEN})
+        if isinstance(response, dict) and response.get('ok'):
+            # Allow the harness its graceful CDP/IPC cleanup before EOF of
+            # our owner pipe forces the crash-only exit path.
+            deadline = time.monotonic() + 2
+            while time.monotonic() < deadline and harness_ipc.ping(os.environ.get('BU_NAME', 'browser-workspace'), timeout=0.1):
+                time.sleep(0.05)
+    except (OSError, ValueError, TimeoutError):
+        pass
+
+DEFAULT_WORKSPACE = os.environ.get('BH_WORKSPACE_NAME','Harness')
+RUNTIME_DIR = Path.home()/'.config/browser-workspace/runtime'
+SOCKET_PATH = (Path(os.environ['BROWSER_WORKSPACE_SESSION_SOCKET']) if os.environ.get('BROWSER_WORKSPACE_TEST_MODE')=='1' and os.environ.get('BROWSER_WORKSPACE_SESSION_SOCKET') else RUNTIME_DIR/'session.sock')
+OWNER_LOCK_PATH = RUNTIME_DIR/'session.lock'
+SESSIONS = {}
+SESSIONS_LOCK = threading.Lock()
+BROWSER_LOCK = threading.RLock()
+
+SESSION_RECONCILE_SECONDS = 30
+
+
+def is_reclaimed(info):
+    url = info.get('url', '')
+    if not url.startswith('chrome-extension://'):
+        return False
+    try:
+        from urllib.parse import urlparse, parse_qs
+        parsed = urlparse(url)
+        return parsed.path == '/workspace.html' and parse_qs(parsed.query).get('role') == ['idle']
+    except ValueError:
+        return False
+
+
+def reconcile_sessions():
+    """Drop records for completely released leases, never release those tabs again."""
+    with BROWSER_LOCK:
+        try:
+            targets = bh.cdp('Target.getTargets')['targetInfos']
+        except Exception:
+            return []
+        pages = {i['targetId']: i for i in targets if i.get('type') == 'page'}
+        removed = []
+        with SESSIONS_LOCK:
+            for sid, session in list(SESSIONS.items()):
+                if session.lock.locked():
+                    continue
+                # A leased root may have opened child tabs: keep any live child.
+                if all(tid not in pages or is_reclaimed(pages[tid])
+                       for tid in session.owned_target_ids):
+                    del SESSIONS[sid]
+                    removed.append(sid)
+        return removed
+
+
+def reconciliation_loop():
+    while True:
+        time.sleep(SESSION_RECONCILE_SECONDS)
+        reconcile_sessions()
+
+
+def compilable_module_body(body):
+    """Return a module body that remains valid after trailing-result extraction.
+
+    Submitted sessions commonly contain ordinary imports before a future import.
+    Python accepts that source form, but recompiling an AST after removing the
+    trailing result expression requires future imports to be moved first.
+    """
+    leading = []
+    if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant) and isinstance(body[0].value.value, str):
+        leading.append(body.pop(0))
+    future = [node for node in body if isinstance(node, ast.ImportFrom) and node.module == '__future__']
+    if not future:
+        return leading + body
+    rest = [node for node in body if node not in future]
+    return leading + future + rest
+
+
+class SessionBrowserProxy:
+    def __init__(self, session): self._session=session
+    def __getattr__(self, name): return getattr(bh, name)
+    def new_tab(self, url='about:blank'): return self._session._new_tab(url)
+    def close_tab(self, target=None): return self._session._close_tab(target)
+    def cdp(self, method, **kwargs): return self._session._cdp(method, **kwargs)
+
+class Session:
+    def __init__(self, sid, workspace, target_id, workspace_supported):
+        self.session_id=sid; self.workspace=workspace; self.target_id=target_id; self.workspace_supported=bool(workspace_supported)
+        self.created_at=time.time(); self.last_used_at=self.created_at
+        self.owned_target_ids={target_id}
+        self.lock=threading.Lock()
+        self.browser=SessionBrowserProxy(self)
+        self.namespace={'__name__':'__browser_workspace_session__','bh':self.browser,'target_id':target_id}
+        for name in dir(bh):
+            if not name.startswith('_'): self.namespace[name]=getattr(bh,name)
+        self.namespace['new_tab']=self._new_tab
+        self.namespace['close_tab']=self._close_tab
+        self.namespace['cdp']=self._cdp
+
+    def _remember_target(self, tid):
+        if tid:
+            self.owned_target_ids.add(tid)
+            self.target_id=tid
+            self.namespace['target_id']=tid
+        return tid
+
+    def _new_tab(self, url='about:blank'):
+        return self._remember_target(bh.new_tab(url))
+
+    def _close_tab(self, target=None):
+        wanted=target
+        if isinstance(wanted, dict): wanted=wanted.get('targetId') or wanted.get('target_id')
+        if wanted is None: wanted=bh.current_tab().get('targetId')
+        result=bh.close_tab(target)
+        if wanted: self.owned_target_ids.discard(wanted)
+        return result
+
+    def _cdp(self, method, **kwargs):
+        if method == 'Target.createTarget':
+            raise RuntimeError(
+                'Target.createTarget is disabled in Browser Workspace sessions; '
+                'use new_tab(url) so the tab is owned by the active session/workspace'
+            )
+        result=bh.cdp(method, **kwargs)
+        if method == 'Target.closeTarget':
+            self.owned_target_ids.discard(kwargs.get('targetId'))
+        return result
+
+def with_workspace(name, supported=None):
+    class Scope:
+        def __enter__(self):
+            self.name_token=bh.workspace_set_name(name)
+            self.support_token=bh.workspace_set_supported(supported) if supported is not None else None
+            return self
+        def __exit__(self,*_):
+            if self.support_token is not None: bh.workspace_reset_supported(self.support_token)
+            bh.workspace_reset_name(self.name_token)
+    return Scope()
+
+def execute(source, namespace):
+    out,err=io.StringIO(),io.StringIO(); value=None
+    try:
+        tree=ast.parse(source,mode='exec'); body=list(tree.body)
+        tail=body.pop() if body and isinstance(body[-1],ast.Expr) else None
+        body=compilable_module_body(body)
+        with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+            if body: exec(compile(ast.Module(body=body,type_ignores=[]),'<browser-workspace-session>','exec'),namespace,namespace)
+            if tail is not None:
+                value=eval(compile(ast.Expression(tail.value),'<browser-workspace-session>','eval'),namespace,namespace); namespace['_']=value
+        result={'ok':True,'stdout':out.getvalue(),'stderr':err.getvalue()}
+        if value is not None:
+            try: json.dumps(value); result['value']=value
+            except (TypeError,ValueError): result['value_repr']=repr(value)
+        return result
+    except BaseException as exc:
+        traceback.print_exc(file=err)
+        return {'ok':False,'stdout':out.getvalue(),'stderr':err.getvalue(),'error':f'{type(exc).__name__}: {exc}'}
+
+def start_session(workspace=None, url=None):
+    workspace=(workspace or DEFAULT_WORKSPACE).strip()
+    if not workspace: raise ValueError('workspace must not be empty')
+    sid=secrets.token_hex(8)
+    start_url=(url or 'about:blank').strip()
+    extension=bh.workspace_extension_status()
+    supported=bool(extension.get('supported'))
+    with BROWSER_LOCK, with_workspace(workspace, supported): tid=bh.new_tab(start_url)
+    s=Session(sid,workspace,tid,supported)
+    with SESSIONS_LOCK: SESSIONS[sid]=s
+    result={'session_id':sid,'workspace':workspace,'target_id':tid,'url':start_url,'workspace_supported':supported}
+    if not supported:
+        result['warning']='Browser Workspace extension is not installed; workspace grouping/leases are unavailable. Browser automation will continue without workspace isolation.'
+        result['extension_url']=extension.get('extensionUrl')
+    return result
+
+
+def absorb_owned_children(session):
+    """Adopt popup/child page targets whose opener ancestry belongs to this session."""
+    try:
+        infos=bh.cdp('Target.getTargets').get('targetInfos', [])
+    except Exception:
+        return
+    pages={i.get('targetId'): i for i in infos if i.get('type') == 'page' and i.get('targetId')}
+    changed=True
+    while changed:
+        changed=False
+        for tid, info in pages.items():
+            if tid in session.owned_target_ids:
+                continue
+            opener=info.get('openerId')
+            if opener and opener in session.owned_target_ids:
+                session.owned_target_ids.add(tid)
+                changed=True
+
+def close_owned_tabs(session):
+    """Close/release every live tab owned by the session, children before parents."""
+    absorb_owned_children(session)
+    errors=[]
+    # Close descendants/current tabs first. Repeatedly inspect live targets so already
+    # closed tabs disappear harmlessly and opener relationships remain usable.
+    while session.owned_target_ids:
+        try:
+            infos=bh.cdp('Target.getTargets').get('targetInfos', [])
+        except Exception:
+            infos=[]
+        live={i.get('targetId'): i for i in infos if i.get('type') == 'page' and i.get('targetId')}
+        owned_live=[tid for tid in session.owned_target_ids if tid in live]
+        if not owned_live:
+            session.owned_target_ids.clear()
+            break
+        parent_ids={live[tid].get('openerId') for tid in owned_live}
+        leaves=[tid for tid in owned_live if tid not in parent_ids]
+        targets=leaves or owned_live
+        for tid in targets:
+            try:
+                if session.workspace_supported:
+                    try:
+                        # Workspace-owned session tabs are leases. Release them back
+                        # to the persistent pool instead of destroying the Chrome tab
+                        # group when the final leased tab is stopped. Popup/child
+                        # targets that are outside the workspace are still closed.
+                        bh.close_tab(tid)
+                    except RuntimeError as exc:
+                        if 'outside workspace' not in str(exc):
+                            raise
+                        bh.cdp('Target.closeTarget', targetId=tid)
+                else:
+                    bh.cdp('Target.closeTarget', targetId=tid)
+            except Exception as exc:
+                errors.append(f'{tid}: {type(exc).__name__}: {exc}')
+            finally:
+                session.owned_target_ids.discard(tid)
+    return errors
+
+def get_session(sid):
+    with SESSIONS_LOCK: s=SESSIONS.get(sid)
+    if not s: raise KeyError(f'unknown session_id: {sid}')
+    return s
+
+def exec_session(sid, code):
+    s=get_session(sid)
+    s.last_used_at=time.time()
+    with s.lock, BROWSER_LOCK, with_workspace(s.workspace, s.workspace_supported):
+        bh.switch_tab(s.target_id,activate=False)
+        r=execute(code,s.namespace)
+        absorb_owned_children(s)
+        try:
+            cur=bh.current_tab(); s.target_id=cur.get('targetId') or s.target_id; s.namespace['target_id']=s.target_id
+        except Exception: pass
+    return {'session_id':sid,'workspace':s.workspace,'target_id':s.target_id,**r}
+
+def list_sessions():
+    with SESSIONS_LOCK:
+        sessions=list(SESSIONS.values())
+    return {
+        'session_count': len(sessions),
+        'sessions': [
+            {
+                'session_id': s.session_id,
+                'workspace': s.workspace,
+                'target_id': s.target_id,
+                'created_at': s.created_at,
+                'last_used_at': s.last_used_at,
+            }
+            for s in sessions
+        ],
+    }
+
+def stop_all_sessions():
+    with SESSIONS_LOCK:
+        ids=list(SESSIONS)
+    stopped=[]
+    errors=[]
+    for sid in ids:
+        try:
+            stopped.append(stop_session(sid))
+        except Exception as exc:
+            errors.append({'session_id':sid,'error':f'{type(exc).__name__}: {exc}'})
+    return {'stopped_count':len(stopped),'error_count':len(errors),'stopped':stopped,'errors':errors}
+
+def stop_session(sid):
+    with SESSIONS_LOCK: s=SESSIONS.pop(sid,None)
+    if not s: raise KeyError(f'unknown session_id: {sid}')
+    release_error=None
+    with s.lock, BROWSER_LOCK, with_workspace(s.workspace, s.workspace_supported):
+        absorb_owned_children(s)
+        closed_count=len(s.owned_target_ids)
+        errors=close_owned_tabs(s)
+        if errors: release_error='; '.join(errors)
+    return {'session_id':sid,'workspace':s.workspace,'target_id':s.target_id,'closed_tabs':closed_count,'release_error':release_error}
+
+SOCKET_IDENTITY = None
+
+def remove_owned_socket():
+    """Never unlink a socket replaced by another owner."""
+    if SOCKET_IDENTITY is None:
+        return
+    try:
+        st = SOCKET_PATH.lstat()
+        if (st.st_dev, st.st_ino) == SOCKET_IDENTITY:
+            SOCKET_PATH.unlink()
+    except FileNotFoundError:
+        pass
+
+def cleanup():
+    with SESSIONS_LOCK: ids=list(SESSIONS)
+    for sid in ids:
+        try: stop_session(sid)
+        except Exception: pass
+    stop_owned_harness()
+    # The write end is close-on-exec; its final close also detects SIGKILL
+    # and parent re-exec without relying on a recycled numeric PID.
+    if HARNESS_OWNER_PIPE is not None:
+        try: os.close(HARNESS_OWNER_PIPE)
+        except OSError: pass
+    try: remove_owned_socket()
+    except Exception: pass
+atexit.register(cleanup)
+
+def create_workspace(name, pool_size=5):
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError('workspace name must be a non-empty string')
+    size=int(pool_size)
+    if size < 1:
+        raise ValueError('workspace pool size must be at least 1')
+    with BROWSER_LOCK:
+        result=bh.workspace_create(name.strip(), size)
+    return {
+        'name': result.get('name', name.strip()),
+        'poolSize': result.get('poolSize', size),
+        'maxCapacity': result.get('maxCapacity', result.get('poolSize', size)),
+        'initialized': result.get('initialized', True),
+        'workspace_supported': True,
+    }
+
+def delete_workspace(name, force=False):
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError('workspace name must be a non-empty string')
+    with BROWSER_LOCK:
+        return bh.workspace_delete(name.strip(), bool(force))
+
+def handle(req):
+    op=req.get('op')
+    if op=='ping': return {'ok':True,'pid':os.getpid(),'session_count':len(SESSIONS),'managed_chrome':MANAGED_CHROME}
+    if op=='list': return list_sessions()
+    if op=='start': return start_session(req.get('workspace'), req.get('url'))
+    if op=='exec': return exec_session(req['session_id'],req.get('code',''))
+    if op=='stop': return stop_session(req['session_id'])
+    if op=='stop-all': return stop_all_sessions()
+    if op=='workspace-create': return create_workspace(req['name'], req.get('pool_size', 5))
+    if op=='workspace-delete': return delete_workspace(req['name'], req.get('force', False))
+    raise ValueError(f'unknown op: {op}')
+
+def serve_conn(conn):
+    with conn:
+        f=conn.makefile('rwb')
+        line=f.readline()
+        if not line: return
+        try: result=handle(json.loads(line))
+        except Exception as exc: result={'error':f'{type(exc).__name__}: {exc}'}
+        f.write((json.dumps(result,ensure_ascii=False)+'\n').encode()); f.flush()
+
+def main():
+    global SOCKET_IDENTITY
+    RUNTIME_DIR.mkdir(parents=True,exist_ok=True)
+    try: os.chmod(RUNTIME_DIR,0o700)
+    except Exception: pass
+    import fcntl
+    owner=open(OWNER_LOCK_PATH,'a+b')
+    try:
+        fcntl.flock(owner,fcntl.LOCK_EX|fcntl.LOCK_NB)
+    except BlockingIOError:
+        owner.close(); return
+    global HARNESS_OWNER_PIPE
+    read_fd, write_fd = os.pipe() if os.name == 'posix' else (None, None)
+    HARNESS_OWNER_PIPE = write_fd
+    try:
+        owner_env = {
+            'BH_OWNER_PID': str(HARNESS_OWNER_PID),
+            'BH_OWNER_STARTED': str(HARNESS_OWNER_STARTED or ''),
+            'BH_OWNER_TOKEN': HARNESS_OWNER_TOKEN,
+        }
+        if read_fd is not None:
+            owner_env['BH_OWNER_PIPE_FD'] = str(read_fd)
+        ensure_daemon(env=owner_env)
+    finally:
+        if read_fd is not None:
+            os.close(read_fd)
+    def terminate(_signum, _frame):
+        raise SystemExit(0)
+    signal.signal(signal.SIGTERM, terminate)
+    signal.signal(signal.SIGINT, terminate)
+    # Lock ownership is required before changing the shared socket path.
+    SOCKET_PATH.unlink(missing_ok=True)
+    srv=socket.socket(socket.AF_UNIX,socket.SOCK_STREAM); srv.bind(str(SOCKET_PATH)); os.chmod(SOCKET_PATH,0o600); SOCKET_IDENTITY=(SOCKET_PATH.stat().st_dev, SOCKET_PATH.stat().st_ino); srv.listen(32)
+    threading.Thread(target=reconciliation_loop, daemon=True).start()
+    try:
+        while True:
+            conn,_=srv.accept(); threading.Thread(target=serve_conn,args=(conn,),daemon=True).start()
+    finally:
+        srv.close(); owner.close()
+if __name__=='__main__': main()

package/src/browser_harness/__init__.py

@@ -1,2 +0,0 @@
-"""Browser Harness core package."""
-