browser-workspace 0.4.2 → 0.4.5

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."""
-

package/src/browser_harness/_ipc.py

@@ -1,201 +0,0 @@
-"""Daemon IPC plumbing. AF_UNIX socket on POSIX, TCP loopback on Windows."""
-import asyncio, json, os, re, secrets, socket, subprocess, sys
-from pathlib import Path
-
-from . import paths
-
-IS_WINDOWS = sys.platform == "win32"
-# Two caller-supplied dirs:
-#   BH_RUNTIME_DIR — sock/port/pid. AF_UNIX sun_path is 104 bytes on macOS, so
-#       the runtime dir must be short. Caller is responsible for keeping it
-#       within budget. Falls back to BH_TMP_DIR (legacy single-dir callers),
-#       then to the browser-harness runtime dir.
-#   BH_TMP_DIR — screenshots, debug overlays, daemon log. No path-length
-#       sensitivity; caller can use a deep persistent path.
-# By default, a caller-supplied dir is treated as per-instance and files use
-# bare "bu" stems. Set BH_RUNTIME_DIR_SHARED=1 or BH_TMP_DIR_SHARED=1 when the
-# dir is shared by multiple BU_NAME values and the filename must carry the name.
-BH_TMP_DIR = os.environ.get("BH_TMP_DIR")
-BH_RUNTIME_DIR = os.environ.get("BH_RUNTIME_DIR") or BH_TMP_DIR
-BH_RUNTIME_DIR_SHARED = os.environ.get("BH_RUNTIME_DIR_SHARED") == "1"
-BH_TMP_DIR_SHARED = os.environ.get("BH_TMP_DIR_SHARED") == "1"
-_TMP = paths.tmp_dir()
-_RUNTIME = paths.ensure_private_dir(Path(BH_RUNTIME_DIR).expanduser().resolve()) if BH_RUNTIME_DIR else paths.runtime_dir()
-_TMP.mkdir(parents=True, exist_ok=True)
-_RUNTIME.mkdir(parents=True, exist_ok=True)
-_NAME_RE = re.compile(r"\A[A-Za-z0-9_-]{1,64}\Z")
-
-# Set by serve() on Windows. Daemon's handle() requires every request to carry
-# this token (TCP loopback has no chmod-equivalent so any local process could
-# otherwise issue CDP commands). Stays None on POSIX where AF_UNIX + chmod 600
-# is the boundary.
-_server_token = None
-
-
-def _check(name):  # path-traversal guard for BU_NAME
-    if not _NAME_RE.match(name or ""):
-        raise ValueError(f"invalid BU_NAME {name!r}: must match [A-Za-z0-9_-]{{1,64}}")
-    return name
-
-
-def _runtime_stem(name):  # "bu" when BH_RUNTIME_DIR isolates us, else "bu-<NAME>"
-    _check(name)
-    return "bu" if BH_RUNTIME_DIR and not BH_RUNTIME_DIR_SHARED else f"bu-{name}"
-
-
-def _tmp_stem(name):  # "bu" when BH_TMP_DIR isolates us, else "bu-<NAME>"
-    _check(name)
-    return "bu" if BH_TMP_DIR and not BH_TMP_DIR_SHARED else f"bu-{name}"
-
-
-def log_path(name):   return _TMP / f"{_tmp_stem(name)}.log"
-def pid_path(name):   return _RUNTIME / f"{_runtime_stem(name)}.pid"
-def port_path(name):  return _RUNTIME / f"{_runtime_stem(name)}.port"  # Windows-only: holds {"port","token"} JSON
-def _sock_path(name): return _RUNTIME / f"{_runtime_stem(name)}.sock"
-
-
-def _read_port_file(name):
-    """(port, token) from the Windows port file, or (None, None) on any failure."""
-    try:
-        d = json.loads(port_path(name).read_text(encoding="utf-8"))
-        return int(d["port"]), d["token"]
-    except (FileNotFoundError, ValueError, KeyError, TypeError, OSError):
-        return None, None
-
-
-def sock_addr(name):  # display-only, used in log lines
-    if not IS_WINDOWS: return str(_sock_path(name))
-    port, _ = _read_port_file(name)
-    return f"127.0.0.1:{port}" if port else f"tcp:{_runtime_stem(name)}"
-
-
-def spawn_kwargs():  # subprocess.Popen flags so the daemon detaches from this terminal
-    if IS_WINDOWS:
-        # CREATE_NO_WINDOW: no console window for the daemon. CREATE_NEW_PROCESS_GROUP:
-        # daemon doesn't receive Ctrl-C/Ctrl-Break sent to the parent terminal, so
-        # closing that terminal doesn't kill it. DETACHED_PROCESS is intentionally
-        # omitted: per Win32 docs it overrides CREATE_NO_WINDOW, causing Windows to
-        # allocate a fresh console for the (still console-subsystem) python.exe.
-        return {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW}
-    return {"start_new_session": True}
-
-
-def connect(name, timeout=1.0):
-    """Blocking client. Returns (sock, token); token is None on POSIX, hex string on Windows.
-    Callers sending JSON requests MUST include the token as req["token"] on Windows."""
-    if not IS_WINDOWS:
-        # uv-Python on Windows lacks socket.AF_UNIX, so this branch must be gated.
-        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
-        s.settimeout(timeout); s.connect(str(_sock_path(name))); return s, None
-    port, token = _read_port_file(name)
-    if port is None: raise FileNotFoundError(str(port_path(name)))
-    s = socket.create_connection(("127.0.0.1", port), timeout=timeout)
-    s.settimeout(timeout); return s, token
-
-
-def request(c, token, req):
-    """One-shot send + recv + parse on an open socket. Injects token on Windows.
-    Returns the parsed JSON response. Caller closes the socket."""
-    if token: req = {**req, "token": token}
-    c.sendall((json.dumps(req) + "\n").encode())
-    data = b""
-    while not data.endswith(b"\n"):
-        chunk = c.recv(1 << 16)
-        if not chunk: break
-        data += chunk
-    return json.loads(data or b"{}")
-
-
-def ping(name, timeout=1.0):
-    """True iff a live daemon answers our ping. Defends against stale .port files
-    + port reuse: a bare TCP connect can succeed against an unrelated process that
-    grabbed the port after our daemon crashed; only our daemon answers {"pong":true}."""
-    try:
-        c, token = connect(name, timeout=timeout)
-    except (FileNotFoundError, ConnectionRefusedError, TimeoutError, socket.timeout, OSError):
-        return False
-    try:
-        resp = request(c, token, {"meta": "ping"})
-        # request() returns parsed JSON, which may be any valid value (a list,
-        # scalar, etc. from a stale or hostile endpoint). Anything that isn't
-        # a {pong: true} dict counts as "not our daemon" — never .get() blindly.
-        return isinstance(resp, dict) and resp.get("pong") is True
-    except (OSError, ValueError, AttributeError):
-        return False
-    finally:
-        try: c.close()
-        except OSError: pass
-
-
-def identify(name, timeout=1.0):
-    """Return the live daemon's PID, or None if unreachable.
-
-    Used by restart_daemon() to signal a process whose identity has been
-    verified end-to-end (live IPC + self-reported PID), instead of trusting
-    a pid file whose number may have been reused by an unrelated process."""
-    try:
-        c, token = connect(name, timeout=timeout)
-    except (FileNotFoundError, ConnectionRefusedError, TimeoutError, socket.timeout, OSError):
-        return None
-    try:
-        resp = request(c, token, {"meta": "ping"})
-        # request() returns parsed JSON, which may be any valid value (a list,
-        # scalar, etc. from a stale or hostile endpoint). Anything that isn't
-        # a {pong: true} dict gets None — never .get() on a non-dict.
-        if not isinstance(resp, dict) or resp.get("pong") is not True:
-            return None
-        pid = resp.get("pid")
-        # `type(pid) is int` (not isinstance) intentionally rejects bool: in
-        # Python, isinstance(True, int) is True, so a hostile/buggy daemon
-        # could reply with {"pid": True} and we'd treat that as PID 1 (init).
-        # Also reject 0/negatives — os.kill(0, sig) signals every process in
-        # the calling process group, os.kill(-1, sig) signals every process
-        # the caller can. Upper bound is 2**31 because C pid_t is typically
-        # signed 32-bit and a value outside that range makes os.kill() raise
-        # OverflowError, which would propagate out of restart_daemon() before
-        # its cleanup. Linux pid_max is also bounded at 2**22 in practice.
-        return pid if type(pid) is int and 0 < pid < (1 << 31) else None
-    except (OSError, ValueError, AttributeError):
-        return None
-    finally:
-        try: c.close()
-        except OSError: pass
-
-
-async def serve(name, handler):
-    """Run the server until cancelled. handler(reader, writer) sees the same interface either way."""
-    global _server_token
-    if not IS_WINDOWS:
-        path = str(_sock_path(name))
-        if os.path.exists(path): os.unlink(path)
-        # umask 0o077 makes bind() create the socket as 0600 — no TOCTOU window before chmod.
-        old_umask = os.umask(0o077)
-        try: server = await asyncio.start_unix_server(handler, path=path)
-        finally: os.umask(old_umask)
-        _server_token = None
-        async with server: await asyncio.Event().wait()
-        return
-    server = await asyncio.start_server(handler, "127.0.0.1", 0)
-    port = server.sockets[0].getsockname()[1]
-    _server_token = secrets.token_hex(32)
-    pf = port_path(name)
-    # Atomic write so a concurrent reader never sees a half-written file.
-    tmp = pf.with_name(pf.name + ".tmp")
-    tmp.write_text(json.dumps({"port": port, "token": _server_token}), encoding="utf-8")
-    os.replace(tmp, pf)
-    try:
-        async with server: await asyncio.Event().wait()
-    finally:
-        try: pf.unlink()
-        except FileNotFoundError: pass
-
-
-def expected_token():
-    """The token the running daemon will accept, or None on POSIX."""
-    return _server_token
-
-
-def cleanup_endpoint(name):  # best-effort; silent if already gone
-    p = _sock_path(name) if not IS_WINDOWS else port_path(name)
-    try: p.unlink()
-    except FileNotFoundError: pass